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.mdnew file mode 100644index 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.++@Geervandiff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.jsonindex 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.jsonindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.',+ },+ ],+ },+};+