Skip to content

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.md
new file mode 100644
index 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)
+@AKnassa
diff --git a/apps/docsite/src/__tests__/component-preview-state.test.ts b/apps/docsite/src/__tests__/component-preview-state.test.ts
index 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.ts
index 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.mjs
index 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.mjs
index 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.mjs
index 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.ts
index 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