An open source design system that's fully customizable and agent ready
TypeScript
fix(docsite): adopt overlay preview for Lightbox (#3689)
AKfd7ab464b143
diff --git a/.changeset/lightbox-overlay-open-trigger-preview.md b/.changeset/lightbox-overlay-open-trigger-preview.mdnew file mode 100644index 0000000000..0a440791c7--- /dev/null+++ b/.changeset/lightbox-overlay-open-trigger-preview.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[docs] Document when playground.overlay applies: components with no inline containment (MobileNav, Lightbox) use it, while Dialog, AlertDialog, and CommandPalette intentionally keep their contained isInline previews so knobs stay usable. Adds regression tests guarding both shapes (#3657)+@AKnassadiff --git a/apps/docsite/src/__tests__/component-preview-state.test.ts b/apps/docsite/src/__tests__/component-preview-state.test.tsindex dedb2494f4..ba0a5cb9af 100644--- a/apps/docsite/src/__tests__/component-preview-state.test.ts+++ b/apps/docsite/src/__tests__/component-preview-state.test.ts@@ -352,6 +352,102 @@ describe('component detail preview state', () => {expect(onPropChange).toHaveBeenCalledWith('isOpen', true);});+ it('bridges a required onOpenChange knob for overlay previews via the knob path', () => {+ // Lightbox shape: isOpen/onOpenChange/media are all REQUIRED — the+ // MobileNav test above covers the optional-props variant of this bridge.+ const knobs = pickPrimaryProps('Lightbox', [+ prop({name: 'isOpen', type: 'boolean', required: true}),+ prop({+ name: 'onOpenChange',+ type: '(isOpen: boolean) => void',+ required: true,+ }),+ prop({+ name: 'media',+ type: 'LightboxMedia | LightboxMedia[]',+ required: true,+ }),+ ]);++ const playground = {+ overlay: true,+ defaults: {+ isOpen: false,+ media: {src: 'https://example.com/scene.png', alt: 'Scene'},+ },+ };+ const state = buildInitialState(knobs, playground);++ // The explicit isOpen: false survives (not eaten by required fallbacks),+ // media is satisfied from defaults, and the stage starts closed.+ expect(state.isOpen).toBe(false);+ expect(state.media).toMatchObject({alt: 'Scene'});+ expect(getMissingRequiredProps(knobs, state)).toEqual([]);+ expect(isOverlayPreviewClosed(playground, state)).toBe(true);++ // The Open-preview trigger and the component's own Esc/backdrop close both+ // round-trip through the bridged onOpenChange.+ const onPropChange = vi.fn();+ const runtimeState = buildRuntimePreviewState(state, onPropChange, {+ knobs,+ canControlOpenState: true,+ });+ (runtimeState.onOpenChange as (isOpen: boolean) => void)(true);+ expect(onPropChange).toHaveBeenCalledWith('isOpen', true);+ expect(isOverlayPreviewClosed(playground, {...state, isOpen: true})).toBe(+ false,+ );+ });++ it('bridges gallery onIndexChange only when index is seeded in state', () => {+ const knobs = pickPrimaryProps('Lightbox', [+ prop({name: 'isOpen', type: 'boolean', required: true}),+ prop({+ name: 'onOpenChange',+ type: '(isOpen: boolean) => void',+ required: true,+ }),+ prop({+ name: 'media',+ type: 'LightboxMedia | LightboxMedia[]',+ required: true,+ }),+ prop({name: 'index', type: 'number'}),+ prop({name: 'onIndexChange', type: '(index: number) => void'}),+ ]);+ const media = [+ {src: 'https://example.com/one.png', alt: 'One'},+ {src: 'https://example.com/two.png', alt: 'Two'},+ ];+ const onPropChange = vi.fn();++ // Without an index default, `index` is absent from state, so the gallery+ // callback is not bridged — prev/next inside the open preview cannot+ // update playground state.+ const state = buildInitialState(knobs, {+ overlay: true,+ defaults: {isOpen: false, media},+ });+ expect(state.index).toBeUndefined();+ const runtimeState = buildRuntimePreviewState(state, onPropChange, {+ knobs,+ canControlOpenState: true,+ });+ expect(runtimeState.onIndexChange).toBeUndefined();++ // Seeding index in defaults opts the gallery into the bridge.+ const seeded = buildInitialState(knobs, {+ overlay: true,+ defaults: {isOpen: false, index: 0, media},+ });+ const seededRuntime = buildRuntimePreviewState(seeded, onPropChange, {+ knobs,+ canControlOpenState: true,+ });+ (seededRuntime.onIndexChange as (index: number) => void)(1);+ expect(onPropChange).toHaveBeenCalledWith('index', 1);+ });+it('flags closed overlay previews only for overlay-mode playgrounds', () => {expect(isOverlayPreviewClosed({overlay: true}, {isOpen: false})).toBe(true);expect(isOverlayPreviewClosed({overlay: true}, {})).toBe(true);diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.tsindex 8384f8b0c8..7246b5b825 100644--- a/apps/docsite/src/__tests__/data-extraction.test.ts+++ b/apps/docsite/src/__tests__/data-extraction.test.ts@@ -309,6 +309,38 @@ describe('componentRegistry', () => {});});+ it('Lightbox declares an overlay playground with a closed initial state (#3657)', () => {+ const core = components['@astryxdesign/core'];+ const lightbox = core.find(c => c.name === 'Lightbox');+ expect(lightbox).toBeDefined();+ // Lightbox opens via showModal() and renders nothing while closed; without+ // overlay mode the properties tab is an empty stage on load.+ expect(lightbox!.playground?.overlay).toBe(true);+ expect(lightbox!.playground?.defaults).toMatchObject({+ isOpen: false,+ media: {+ src: expect.stringContaining('https://'),+ alt: expect.any(String),+ },+ });+ });++ it('dialog-family components keep contained isInline previews, not overlay mode (#3657)', () => {+ const core = components['@astryxdesign/core'];+ for (const name of ['Dialog', 'AlertDialog', 'CommandPalette']) {+ const entry = core.find(c => c.name === name);+ expect(entry, name).toBeDefined();+ // Intentional: the contained preview keeps knobs usable while the+ // component is visible. Guard the half-migrated shape too — overlay+ // with isOpen: true would never show the open trigger.+ expect(entry!.playground?.overlay, name).toBeUndefined();+ expect(entry!.playground?.defaults, name).toMatchObject({+ isOpen: true,+ isInline: true,+ });+ }+ });+it('Chat has many sub-components (standalone docs take priority over compound entries)', () => {const core = components['@astryxdesign/core'];// Chat compound doc has 14 sub-components, but ChatToolCalls and@@ -898,8 +930,7 @@ describe('Card playground defaults', () => {const entry = coreComponent('ClickableCard');expect(entry).toBeDefined();const defaults = entry!.playground?.defaults as- | Record<string, unknown>- | undefined;+ Record<string, unknown> | undefined;expect(defaults).toBeDefined();expect(typeof defaults!.label).toBe('string');expect(defaults!.href).toBeDefined();@@ -912,8 +943,7 @@ describe('Card playground defaults', () => {const entry = coreComponent('SelectableCard');expect(entry).toBeDefined();const defaults = entry!.playground?.defaults as- | Record<string, unknown>- | undefined;+ Record<string, unknown> | undefined;expect(defaults).toBeDefined();expect(typeof defaults!.label).toBe('string');expect(typeof defaults!.isSelected).toBe('boolean');diff --git a/packages/core/src/AlertDialog/AlertDialog.doc.mjs b/packages/core/src/AlertDialog/AlertDialog.doc.mjsindex 8ba68dcd88..3d95111a18 100644--- a/packages/core/src/AlertDialog/AlertDialog.doc.mjs+++ b/packages/core/src/AlertDialog/AlertDialog.doc.mjs@@ -28,6 +28,10 @@ export const docs = {{guidance: false, description: 'Use AlertDialog for non-destructive actions; use a standard Dialog instead.'},],},+ // Intentionally a contained isInline preview, not playground.overlay: the+ // component stays visible on load and knobs stay live, whereas a real+ // showModal() overlay makes the page inert — see PlaygroundConfig.overlay+ // in docs-types.ts (#3657).playground: {defaults: {isOpen: true,diff --git a/packages/core/src/CommandPalette/CommandPalette.doc.mjs b/packages/core/src/CommandPalette/CommandPalette.doc.mjsindex 96a7284335..7a6cd96133 100644--- a/packages/core/src/CommandPalette/CommandPalette.doc.mjs+++ b/packages/core/src/CommandPalette/CommandPalette.doc.mjs@@ -20,6 +20,10 @@ export const docs = {'navigation',],description: 'Root component. Manages open state, search, keyboard navigation, and composition slots.',+ // Intentionally a contained isInline preview, not playground.overlay: the+ // component stays visible on load and knobs stay live, whereas a real+ // showModal() overlay makes the page inert — see PlaygroundConfig.overlay+ // in docs-types.ts (#3657).playground: {defaults: {isOpen: true,diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjsindex d384a37dce..1d8fbeea7e 100644--- a/packages/core/src/Dialog/Dialog.doc.mjs+++ b/packages/core/src/Dialog/Dialog.doc.mjs@@ -8,6 +8,10 @@ export const docs = {group: 'Dialog',category: 'Overlay',keywords: ["dialog","modal","popup","overlay","lightbox","alert","confirm","prompt","backdrop","focus trap","imperative"],+ // Intentionally a contained isInline preview, not playground.overlay: the+ // component stays visible on load and knobs stay live, whereas a real+ // showModal() overlay makes the page inert — see PlaygroundConfig.overlay+ // in docs-types.ts (#3657).playground: {defaults: {isOpen: true,diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.tsindex b7d31dcd5b..dc3486ed5e 100644--- a/packages/core/src/docs-types.ts+++ b/packages/core/src/docs-types.ts@@ -400,7 +400,13 @@ export interface PlaygroundConfig {* interactive preview shows an open-trigger placeholder instead of an* empty stage while `isOpen` is false, and lets the real overlay render* when opened. Include `isOpen: false` in `defaults` so the preview can- * bridge `onOpenChange` back into playground state. */+ * bridge `onOpenChange` back into playground state.+ *+ * Only for components with no inline containment (MobileNav, Lightbox).+ * Components with an `isInline` docs-preview prop (Dialog, AlertDialog,+ * CommandPalette) intentionally keep contained inline previews instead:+ * the component is visible on load and knobs stay usable, whereas a real+ * top-layer modal makes the rest of the page inert (#3657). */overlay?: boolean;/** Required parent wrapper for sub-components that depend on a parent* context provider (e.g. `Tab` calls `useTabListContext()` and throws