Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(useLightbox): add hook docs and a gallery grid example block (#9752)

Geervanff5b5ac7edc7
diff --git a/.changeset/hook-doc-use-lightbox.md b/.changeset/hook-doc-use-lightbox.md
new file mode 100644
index 0000000000..1781ea2132
--- /dev/null
+++ b/.changeset/hook-doc-use-lightbox.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/core': patch
+'@astryxdesign/cli': patch
+---
+
+[docs] Hook docs for `useLightbox`, so `astryx hook useLightbox` and `astryx search` return it, and a `useLightbox — Gallery Grid` example block: a grid of photo thumbnails that opens a fullscreen gallery at the clicked item.
+
+@Geervan
diff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.json
index ddccff9248..dbf3d77330 100644
--- a/apps/sandbox/scripts/next-export-routes.json
+++ b/apps/sandbox/scripts/next-export-routes.json
@@ -391,6 +391,7 @@
"/templates/LayoutShowcase/",
"/templates/LayoutSidebarLayout/",
"/templates/LightboxGallery/",
+ "/templates/LightboxHookUsage/",
"/templates/LightboxShowcase/",
"/templates/LightboxVideo/",
"/templates/LightboxZoom/",
diff --git a/internal/shadcn-registry/routes.lock.json b/internal/shadcn-registry/routes.lock.json
index 0a270aa984..92b00463a1 100644
--- a/internal/shadcn-registry/routes.lock.json
+++ b/internal/shadcn-registry/routes.lock.json
@@ -3696,6 +3696,11 @@
"path": "examples/use-layer/anchored-layer",
"aliases": []
},
+ {
+ "name": "example-use-lightbox-gallery-grid",
+ "path": "examples/use-lightbox/gallery-grid",
+ "aliases": []
+ },
{
"name": "example-use-list-focus-recent-files",
"path": "examples/use-list-focus/recent-files",
@@ -3951,6 +3956,11 @@
"path": "hooks/use-layer",
"aliases": []
},
+ {
+ "name": "hook-use-lightbox",
+ "path": "hooks/use-lightbox",
+ "aliases": []
+ },
{
"name": "hook-use-list-focus",
"path": "hooks/use-list-focus",
diff --git a/packages/cli/assets/templates/blocks/components/Lightbox/LightboxHookUsage.doc.mjs b/packages/cli/assets/templates/blocks/components/Lightbox/LightboxHookUsage.doc.mjs
new file mode 100644
index 0000000000..e7b374e9db
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Lightbox/LightboxHookUsage.doc.mjs
@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'useLightbox',
+ name: 'useLightbox — Gallery Grid',
+ displayName: 'useLightbox — Gallery Grid',
+ description:
+ 'Photo gallery thumbnail grid using useLightbox for trigger props, keyboard navigation, and open state.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Lightbox', 'Grid'],
+};
+
diff --git a/packages/cli/assets/templates/blocks/components/Lightbox/LightboxHookUsage.tsx b/packages/cli/assets/templates/blocks/components/Lightbox/LightboxHookUsage.tsx
new file mode 100644
index 0000000000..416ef607e0
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Lightbox/LightboxHookUsage.tsx
@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useLightbox} from '@astryxdesign/core/Lightbox';
+import {Grid} from '@astryxdesign/core/Grid';
+
+const PHOTOS = [
+ {
+ src: '/template-assets/Neutral-Backpack.png',
+ alt: 'Backpack',
+ caption: 'Backpack on a neutral background',
+ },
+ {
+ src: '/template-assets/Neutral-Blanket.png',
+ alt: 'Blanket',
+ caption: 'Cozy blanket on a neutral background',
+ },
+ {
+ src: '/template-assets/Neutral-Headphones.png',
+ alt: 'Headphones',
+ caption: 'Wireless headphones on a neutral background',
+ },
+ {
+ src: '/template-assets/Neutral-Tumbler.png',
+ alt: 'Tumbler',
+ caption: 'Stainless tumbler on a neutral background',
+ },
+ {
+ src: '/template-assets/Neutral-Wallet.png',
+ alt: 'Wallet',
+ caption: 'Leather wallet on a neutral background',
+ },
+ {
+ src: '/template-assets/Neutral-Watch.png',
+ alt: 'Watch',
+ caption: 'Wristwatch on a neutral background',
+ },
+];
+
+export default function LightboxHookUsage() {
+ const lightbox = useLightbox({media: PHOTOS});
+
+ return (
+ <>
+ <Grid columns={3} gap={2} width={304}>
+ {PHOTOS.map((photo, i) => (
+ <img
+ key={photo.alt}
+ src={photo.src}
+ alt={photo.alt}
+ width={96}
+ height={96}
+ style={{objectFit: 'cover'}}
+ {...lightbox.getTriggerProps(i)}
+ />
+ ))}
+ </Grid>
+ {lightbox.element}
+ </>
+ );
+}
diff --git a/packages/core/src/Lightbox/useLightbox.doc.mjs b/packages/core/src/Lightbox/useLightbox.doc.mjs
new file mode 100644
index 0000000000..df0f136fef
--- /dev/null
+++ b/packages/core/src/Lightbox/useLightbox.doc.mjs
@@ -0,0 +1,167 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+ name: 'useLightbox',
+ displayName: 'useLightbox',
+ group: 'Lightbox',
+ keywords: [
+ 'lightbox',
+ 'gallery',
+ 'viewer',
+ 'image',
+ 'video',
+ 'media',
+ 'modal',
+ 'overlay',
+ 'trigger',
+ ],
+ params: [
+ {
+ name: 'options',
+ type: 'UseLightboxOptions',
+ description: 'Configuration options for the lightbox.',
+ required: true,
+ },
+ {
+ name: 'options.media',
+ type: 'LightboxMedia | LightboxMedia[]',
+ description:
+ 'Media to display in the lightbox. Pass a single object for one item, or an array for gallery mode.',
+ required: true,
+ },
+ {
+ name: 'options.hasZoom',
+ type: 'boolean',
+ description:
+ 'Enable zoom on double-click, or Enter/Space/+/- via keyboard (images only). When zoomed, drag or use arrow keys to pan.',
+ default: 'false',
+ required: false,
+ },
+ {
+ name: 'options.hasAutoPlay',
+ type: 'boolean',
+ description: 'Whether video should autoplay when the lightbox opens.',
+ default: 'false',
+ required: false,
+ },
+ ],
+ returns: [
+ {
+ name: 'open',
+ type: '(index?: number) => void',
+ description:
+ 'Open the lightbox, optionally at a specific gallery index (defaults to 0).',
+ },
+ {
+ name: 'close',
+ type: '() => void',
+ description: 'Close the lightbox.',
+ },
+ {
+ name: 'isOpen',
+ type: 'boolean',
+ description: 'Whether the lightbox is currently open.',
+ },
+ {
+ name: 'index',
+ type: 'number',
+ description: 'Current gallery index.',
+ },
+ {
+ name: 'element',
+ type: 'ReactNode',
+ description:
+ 'Pre-wired Lightbox component element to render in your JSX tree.',
+ },
+ {
+ name: 'triggerProps',
+ type: "{role: 'button', tabIndex: 0, 'aria-haspopup': 'dialog', onClick: () => void, onKeyDown: (e: React.KeyboardEvent) => void}",
+ description:
+ 'Props to spread onto a single trigger element to open the lightbox at index 0 on click, Enter, or Space.',
+ },
+ {
+ name: 'getTriggerProps',
+ type: "(index: number) => {role: 'button', tabIndex: 0, 'aria-haspopup': 'dialog', onClick: () => void, onKeyDown: (e: React.KeyboardEvent) => void}",
+ description:
+ 'Returns trigger props to spread onto an element to open the lightbox at a specific gallery index on click, Enter, or Space.',
+ },
+ ],
+ usage: {
+ description:
+ 'State management and accessible trigger wiring for Lightbox. Eliminates boilerplate for managing open state and current index. Returns trigger props with button role, tabIndex={0}, aria-haspopup="dialog", and keyboard activation handlers, along with a pre-wired Lightbox element that handles dismissal, next/previous navigation, and focus restoration.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Spread getTriggerProps(index) onto image or thumbnail elements to give them accessible button semantics and keyboard activation.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Render lightbox.element once in your component JSX tree alongside the triggers.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Manage separate isOpen or index state alongside useLightbox; the hook already tracks both.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Add custom click or keydown handlers to open the lightbox when using triggerProps or getTriggerProps.',
+ },
+ ],
+ },
+ relatedComponents: ['Lightbox', 'Grid', 'Thumbnail'],
+ relatedHooks: [],
+ importPath: '@astryxdesign/core/Lightbox',
+ category: 'interaction',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+ description:
+ 'State management and accessible trigger wiring for Lightbox. Eliminates boilerplate for open state and index. Returns trigger props and pre-wired Lightbox element.',
+ paramDescriptions: {
+ options: 'configuration options for the lightbox.',
+ 'options.media':
+ 'media to display (single item or array for gallery mode).',
+ 'options.hasZoom':
+ 'enable zoom on double-click or Enter/Space/+/- (images only).',
+ 'options.hasAutoPlay': 'whether video should autoplay when opened.',
+ },
+ returnDescriptions: {
+ open: 'open the lightbox, optionally at a specific gallery index.',
+ close: 'close the lightbox.',
+ isOpen: 'whether the lightbox is currently open.',
+ index: 'current gallery index.',
+ element: 'pre-wired Lightbox element to render in JSX tree.',
+ triggerProps:
+ 'trigger attributes to spread onto a single trigger element.',
+ getTriggerProps:
+ '(index) => props: returns trigger attributes for opening at index on click, Enter, or Space.',
+ },
+ usage: {
+ description:
+ 'State management and trigger wiring for Lightbox. Returns trigger props and pre-wired element.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Spread getTriggerProps(index) onto image elements for accessible button semantics.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Render lightbox.element once in JSX alongside the triggers.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Manage separate isOpen or index state alongside useLightbox.',
+ },
+ ],
+ },
+};
+