Skip to content

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

TypeScript

fix(docsite): show Tokenizer in properties preview (#5982)

홍규진85155353a8b2
diff --git a/.changeset/tokenizer-playground-default.md b/.changeset/tokenizer-playground-default.md
new file mode 100644
index 0000000000..95e8f574f7
--- /dev/null
+++ b/.changeset/tokenizer-playground-default.md
@@ -0,0 +1,9 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Tokenizer: render and interact in the docsite properties preview (#5982)
+
+Seeds playground defaults for the required `value` array so the properties-tab preview shows a labeled field with tokens on first load instead of the missing-required-props placeholder, and wires the preview's `onChange` bridge back to the controlled `value` so removing a token updates the field.
+
+@Kyujenius
diff --git a/apps/docsite/src/__tests__/component-preview-state.test.ts b/apps/docsite/src/__tests__/component-preview-state.test.ts
index b0158e2579..b6fd1bb6f7 100644
--- a/apps/docsite/src/__tests__/component-preview-state.test.ts
+++ b/apps/docsite/src/__tests__/component-preview-state.test.ts
@@ -444,6 +444,78 @@ describe('component detail preview state', () => {
expect(onPropChange).toHaveBeenCalledWith('value', 42);
});
+ it('bridges a Tokenizer removal back to its controlled value', () => {
+ const knobs = pickPrimaryProps('Tokenizer', [
+ prop({name: 'label', type: 'string', required: true}),
+ prop({name: 'value', type: 'T[]', required: true}),
+ prop({
+ name: 'onChange',
+ type: '(items: T[], change: TokenizerChange<T>) => void',
+ required: true,
+ }),
+ ]);
+
+ const seeded = [
+ {id: '1', label: 'Design'},
+ {id: '2', label: 'Engineering'},
+ ];
+ const onPropChange = vi.fn();
+ const runtimeState = buildRuntimePreviewState(
+ {label: 'Tags', value: seeded},
+ onPropChange,
+ {knobs},
+ );
+
+ // onChange's first param is `items`, which is not a prop — it falls back
+ // to the controlled `value`, so removing a token updates the preview.
+ expect(runtimeState.onChange).toEqual(expect.any(Function));
+ (runtimeState.onChange as (items: unknown[], change: unknown) => void)(
+ [seeded[1]],
+ {item: seeded[0], type: 'remove'},
+ );
+ expect(onPropChange).toHaveBeenCalledWith('value', [seeded[1]]);
+ });
+
+ it('bridges a Switch toggle back to its controlled value', () => {
+ const knobs = pickPrimaryProps('Switch', [
+ prop({name: 'value', type: 'boolean', required: true}),
+ prop({
+ name: 'onChange',
+ type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void',
+ }),
+ ]);
+
+ const onPropChange = vi.fn();
+ const runtimeState = buildRuntimePreviewState(
+ {value: false},
+ onPropChange,
+ {
+ knobs,
+ },
+ );
+
+ (runtimeState.onChange as (checked: boolean) => void)(true);
+ expect(onPropChange).toHaveBeenCalledWith('value', true);
+ });
+
+ it('does not invent a value target for non-onChange handlers', () => {
+ const knobs = pickPrimaryProps('OverflowList', [
+ prop({name: 'value', type: 'string'}),
+ prop({
+ name: 'onOverflowChange',
+ type: '(overflowItems: OverflowItem[]) => void',
+ }),
+ ]);
+
+ const state = {value: 'a'};
+ const onPropChange = vi.fn();
+ const runtimeState = buildRuntimePreviewState(state, onPropChange, {knobs});
+
+ // `overflowItems` is not a prop, and a named on*Change handler reports
+ // something other than the controlled value — leave it alone.
+ expect(runtimeState).toBe(state);
+ });
+
it('leaves callbacks alone when no matching value prop exists in state', () => {
const knobs = pickPrimaryProps('Button', [
prop({name: 'label', type: 'string'}),
diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.ts
index 4b2fa5b300..5f87881fe8 100644
--- a/apps/docsite/src/__tests__/data-extraction.test.ts
+++ b/apps/docsite/src/__tests__/data-extraction.test.ts
@@ -334,6 +334,21 @@ describe('componentRegistry', () => {
});
});
+ it('Tokenizer satisfies its required value prop via playground defaults', () => {
+ const core = components['@astryxdesign/core'];
+ const tokenizer = core.find(c => c.name === 'Tokenizer');
+ expect(tokenizer).toBeDefined();
+ // `value` is an array of custom items the preview cannot auto-generate;
+ // without this default the properties tab has no interactive preview.
+ expect(tokenizer!.playground?.defaults).toMatchObject({
+ label: 'Tags',
+ value: [
+ {id: '1', label: 'Design'},
+ {id: '2', label: 'Engineering'},
+ ],
+ });
+ });
+
it('MetadataListItem declares a playground wrapper for realistic preview structure', () => {
const core = components['@astryxdesign/core'];
const metadataListItem = core.find(c => c.name === 'MetadataListItem');
diff --git a/apps/docsite/src/__tests__/interactive-preview.test.ts b/apps/docsite/src/__tests__/interactive-preview.test.ts
index 81cac02149..d4aba86639 100644
--- a/apps/docsite/src/__tests__/interactive-preview.test.ts
+++ b/apps/docsite/src/__tests__/interactive-preview.test.ts
@@ -4,8 +4,9 @@
/**
* @file InteractivePreview tests.
- * @input InteractivePreviewStage and a radio-item playground preview
- * @output Regression coverage for wrapper-owned selection state.
+ * @input InteractivePreviewStage with radio-item and Tokenizer playground previews
+ * @output Regression coverage for wrapper-owned selection state and for the
+ * controlled-value change bridge.
*/
import {
@@ -20,6 +21,7 @@ import '@testing-library/jest-dom/vitest';
import {render, screen} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {InteractivePreviewStage} from '../components/component-detail/InteractivePreview';
+import {pickPrimaryProps} from '../components/component-detail/interactiveState';
vi.mock('@stylexjs/stylex', () => ({
create: (styles: unknown) => styles,
@@ -94,6 +96,41 @@ function MockRadioItem({value, label}: {value: string; label: string}) {
);
}
+type TokenItem = {id: string; label: string};
+
+function MockTokenizer({
+ label,
+ value,
+ onChange,
+}: {
+ label: string;
+ value: TokenItem[];
+ onChange: (items: TokenItem[], change: unknown) => void;
+}) {
+ return createElement(
+ 'div',
+ {'aria-label': label, role: 'group'},
+ value.map(item =>
+ createElement(
+ 'span',
+ {key: item.id},
+ createElement('span', null, item.label),
+ createElement(
+ 'button',
+ {
+ onClick: () =>
+ onChange(
+ value.filter(entry => entry.id !== item.id),
+ {item, type: 'remove'},
+ ),
+ },
+ `Remove ${item.label}`,
+ ),
+ ),
+ ),
+ );
+}
+
vi.mock('@astryxdesign/core', () => ({
Button: MockButton,
Card: Box,
@@ -102,6 +139,7 @@ vi.mock('@astryxdesign/core', () => ({
DropdownMenuRadioGroup: MockRadioGroup,
DropdownMenuRadioItem: MockRadioItem,
Text: Box,
+ Tokenizer: MockTokenizer,
VStack: Box,
}));
@@ -145,4 +183,41 @@ describe('InteractivePreviewStage', () => {
await user.click(item);
expect(item).toHaveAttribute('aria-checked', 'true');
});
+
+ it('drops a removed Tokenizer token from the rendered preview (#5981)', async () => {
+ const user = userEvent.setup();
+ const knobs = pickPrimaryProps('Tokenizer', [
+ {name: 'label', type: 'string', description: '', required: true},
+ {name: 'value', type: 'T[]', description: '', required: true},
+ {
+ name: 'onChange',
+ type: '(items: T[], change: TokenizerChange<T>) => void',
+ description: '',
+ required: true,
+ },
+ ]);
+
+ function PreviewHarness() {
+ const [value, setValue] = useState<TokenItem[]>([
+ {id: '1', label: 'Design'},
+ {id: '2', label: 'Engineering'},
+ ]);
+ return createElement(InteractivePreviewStage, {
+ name: 'Tokenizer',
+ state: {label: 'Tags', value},
+ knobs,
+ onPropChange: (_propName: string, nextValue: unknown) =>
+ setValue(nextValue as TokenItem[]),
+ });
+ }
+
+ render(createElement(PreviewHarness));
+ expect(screen.getByText('Design')).toBeInTheDocument();
+ expect(screen.getByText('Engineering')).toBeInTheDocument();
+
+ await user.click(screen.getByRole('button', {name: 'Remove Design'}));
+
+ expect(screen.queryByText('Design')).not.toBeInTheDocument();
+ expect(screen.getByText('Engineering')).toBeInTheDocument();
+ });
});
diff --git a/apps/docsite/src/components/component-detail/interactiveState.ts b/apps/docsite/src/components/component-detail/interactiveState.ts
index bee5ae455b..26f59b1e9e 100644
--- a/apps/docsite/src/components/component-detail/interactiveState.ts
+++ b/apps/docsite/src/components/component-detail/interactiveState.ts
@@ -290,12 +290,36 @@ function getCallbackTargetProp(type: string): string | null {
return /^[A-Za-z_$][\w$]*$/.test(name) ? name : null;
}
+/**
+ * The state prop a change handler writes back to, or `null` when the preview
+ * cannot tell. Prefers the first parameter's name; for `onChange` falls back
+ * to the controlled `value` prop, whose payload it carries by convention.
+ */
+function resolveChangeTarget(
+ name: string,
+ type: string,
+ state: Record<string, unknown>,
+): string | null {
+ const named = getCallbackTargetProp(type);
+ if (named != null && named in state) {
+ return named;
+ }
+ return name === 'onChange' && 'value' in state ? 'value' : null;
+}
+
/**
* Wires controlled-component change handlers back into playground state so the
* preview reflects interaction (clicking a Pagination page, etc.). A callback
* whose first parameter names a value prop in `state` (page/onChange,
* value/onChange, pageSize/onPageSizeChange) replaces its noop with one that
* updates that prop. isOpen/onOpenChange stays gated behind canControlOpenState.
+ *
+ * `onChange` is the exception to the name match: it conventionally documents
+ * its first parameter after the payload it carries (`checked`, `items`,
+ * `values`) rather than after the prop that holds it, so it falls back to the
+ * component's controlled `value`. Without that fallback a Switch never
+ * toggles and a Tokenizer token never leaves, because the component is
+ * controlled and nothing writes the next value back (#5981).
*/
export function buildRuntimePreviewState(
state: Record<string, unknown>,
@@ -318,8 +342,8 @@ export function buildRuntimePreviewState(
if (!/^on[A-Z].*Change$/.test(row.name) && row.name !== 'onChange') {
continue;
}
- const target = getCallbackTargetProp(row.type);
- if (target == null || !(target in state)) {
+ const target = resolveChangeTarget(row.name, row.type, state);
+ if (target == null) {
continue;
}
if (target === 'isOpen' && options?.canControlOpenState !== true) {
diff --git a/packages/core/src/Tokenizer/Tokenizer.doc.mjs b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
index 9f17f62b49..9695ccd1bb 100644
--- a/packages/core/src/Tokenizer/Tokenizer.doc.mjs
+++ b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
@@ -7,6 +7,20 @@ export const docs = {
displayName: 'Tokenizer',
category: 'Form Controls',
keywords: ["tokenizer","multiselect","multi-select","chips","tags","combobox","autocomplete","taginput","chipinput"],
+ playground: {
+ // `value` is a required array of custom items the preview cannot
+ // auto-generate; without a default the properties tab shows the
+ // missing-props placeholder instead of the field. `searchSource` and
+ // `onChange` are supplied by the preview's own fallbacks.
+ defaults: {
+ label: 'Tags',
+ placeholder: 'Search...',
+ value: [
+ {id: '1', label: 'Design'},
+ {id: '2', label: 'Engineering'},
+ ],
+ },
+ },
props: [
{
name: 'label',