Skip to content

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

TypeScript

docs(core): reconcile API contract props across 10 complex components (#4163) (#4316)

Ojas Mutrejad334c4a19305
diff --git a/.changeset/complex-component-contract-docs-tjsk.md b/.changeset/complex-component-contract-docs-tjsk.md
new file mode 100644
index 0000000000..c7acbc8237
--- /dev/null
+++ b/.changeset/complex-component-contract-docs-tjsk.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] document missing props across complex components (MultiSelector, Tokenizer, PowerSearch, Typeahead, Layout, DropdownMenu, HoverCard, Tooltip, Link, Lightbox) (#4163)
+
+@HelloOjasMutreja
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
index 383a1d4c13..ac1d053261 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
@@ -89,6 +89,12 @@ export const docs = {
type: '() => void',
description: 'Callback fired when the trigger button is clicked.',
},
+ {
+ name: 'placement',
+ type: "'above' | 'below' | 'start' | 'end'",
+ description: 'Position placement for the menu popover relative to the trigger button.',
+ default: "'below'",
+ },
{
name: 'hasChevron',
type: 'boolean',
diff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjs
index 4fbad801b1..3ddde4caa0 100644
--- a/packages/core/src/HoverCard/HoverCard.doc.mjs
+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs
@@ -109,6 +109,11 @@ export const docs = {
type: 'boolean',
description: 'Whether the hover card should be shown on mount. Still dismissible.',
},
+ {
+ name: 'isOpen',
+ type: 'boolean',
+ description: 'Controlled open state for the hover card.',
+ },
],
},
],
diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjs
index 7b2aadfcde..4adc4ff402 100644
--- a/packages/core/src/Layout/Layout.doc.mjs
+++ b/packages/core/src/Layout/Layout.doc.mjs
@@ -95,9 +95,9 @@ export const docs = {
},
{
name: 'contentWidth',
- type: 'number | string',
+ type: 'SizeValue',
description:
- 'Maximum width of the content within each slot (header, content, footer, panels), centered when narrower than the available space. Dividers stay full-bleed. Numbers are pixels, strings are used as-is (e.g. `60ch`). Common page widths: 640 for forms, settings, and text-focused pages; 960 for content pages and wider layouts.',
+ 'Maximum width of the content within each slot (header, content, footer, panels), centered when narrower than the available space. Dividers stay full-bleed. Numbers are treated as pixels, strings are used as-is (e.g. `60ch`). Common page widths: 640 for forms, settings, and text-focused pages; 960 for content pages and wider layouts.',
},
{
name: 'padding',
diff --git a/packages/core/src/Lightbox/Lightbox.doc.mjs b/packages/core/src/Lightbox/Lightbox.doc.mjs
index f6edf5e133..aa21aa1dfa 100644
--- a/packages/core/src/Lightbox/Lightbox.doc.mjs
+++ b/packages/core/src/Lightbox/Lightbox.doc.mjs
@@ -47,6 +47,18 @@ export const docs = {
description: 'Enable zoom on double-click, or Enter/Space/+/- via keyboard (images only). When zoomed, drag or use arrow keys to pan.',
default: 'false',
},
+ {
+ name: 'defaultIndex',
+ type: 'number',
+ description: 'Initial image index in gallery mode for uncontrolled usage.',
+ default: '0',
+ },
+ {
+ name: 'hasAutoPlay',
+ type: 'boolean',
+ description: 'Automatically start video playback when a video media item is shown.',
+ default: 'false',
+ },
{
name: 'xstyle',
type: 'StyleXStyles',
diff --git a/packages/core/src/Link/Link.doc.mjs b/packages/core/src/Link/Link.doc.mjs
index 81116e8ff9..48cc492bdb 100644
--- a/packages/core/src/Link/Link.doc.mjs
+++ b/packages/core/src/Link/Link.doc.mjs
@@ -105,6 +105,34 @@ export const docs = {
description: 'Applies base font sizing',
default: 'false',
},
+ {
+ name: 'size',
+ type: "'4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl'",
+ description: 'Explicit font size override forwarded to Text.',
+ },
+ {
+ name: 'weight',
+ type: "'normal' | 'medium' | 'semibold' | 'bold'",
+ description: 'Font weight override forwarded to Text.',
+ },
+ {
+ name: 'color',
+ type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
+ description: 'Text color forwarded to Text.',
+ default: "'accent'",
+ },
+ {
+ name: 'display',
+ type: "'inline' | 'block'",
+ description: 'Display type for Text.',
+ default: "'inline'",
+ },
+ {
+ name: 'maxLines',
+ type: 'number',
+ description: 'Maximum lines before truncation.',
+ default: '0',
+ },
{
name: 'children',
type: 'ReactNode',
diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
index aa53eb87d4..b6ac0a032b 100644
--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs
+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
@@ -213,6 +213,23 @@ export const docs = {
description:
'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
},
+ {
+ name: 'startIcon',
+ type: 'IconType | ReactNode',
+ description: 'Icon displayed at the start of the selector trigger.',
+ },
+ {
+ name: 'hasClear',
+ type: 'boolean',
+ description: 'Shows a clear button when values are selected.',
+ default: 'false',
+ },
+ {
+ name: 'isDefaultOpen',
+ type: 'boolean',
+ description: 'Whether the dropdown starts open on mount.',
+ default: 'false',
+ },
{
name: 'xstyle',
type: 'StyleXStyles',
diff --git a/packages/core/src/PowerSearch/PowerSearch.doc.mjs b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
index 7b57c94926..5877453f39 100644
--- a/packages/core/src/PowerSearch/PowerSearch.doc.mjs
+++ b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
@@ -142,6 +142,22 @@ export const docs = {
description: 'Size of the search input and tokens.',
default: "'md'",
},
+ {
+ name: 'menuWidth',
+ type: 'number',
+ description: 'Maximum width for the operator/value dropdown menu in pixels.',
+ },
+ {
+ name: 'maxOperatorMenuItems',
+ type: 'number',
+ description: 'Maximum number of items displayed in the operator dropdown.',
+ },
+ {
+ name: 'tokenOverflowBehavior',
+ type: "'none' | 'unfocusedInline' | 'unfocusedLayer'",
+ description: 'Controls how tokens overflow when the container is too narrow. Forwarded to Tokenizer.',
+ default: "'none'",
+ },
{
name: 'onFocus',
type: '(e: FocusEvent<HTMLInputElement>) => void',
diff --git a/packages/core/src/Tokenizer/Tokenizer.doc.mjs b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
index d8dc231cef..410ee5d923 100644
--- a/packages/core/src/Tokenizer/Tokenizer.doc.mjs
+++ b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
@@ -201,6 +201,12 @@ export const docs = {
description:
'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
},
+ {
+ name: 'tokenOverflowBehavior',
+ type: "'none' | 'unfocusedInline' | 'unfocusedLayer'",
+ description: 'Controls how tokens overflow when the container is too narrow.',
+ default: "'none'",
+ },
{
name: 'onFocus',
type: '(e: FocusEvent<HTMLInputElement>) => void',
diff --git a/packages/core/src/Tooltip/Tooltip.doc.mjs b/packages/core/src/Tooltip/Tooltip.doc.mjs
index 8d3f713b27..1eae41ee17 100644
--- a/packages/core/src/Tooltip/Tooltip.doc.mjs
+++ b/packages/core/src/Tooltip/Tooltip.doc.mjs
@@ -96,6 +96,11 @@ export const docs = {
type: 'boolean',
description: 'Whether the tooltip should be shown on mount. Still dismissible.',
},
+ {
+ name: 'isOpen',
+ type: 'boolean',
+ description: 'Controlled open state for the tooltip.',
+ },
],
},
],
diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjs
index e3d8799588..72c365583b 100644
--- a/packages/core/src/Typeahead/Typeahead.doc.mjs
+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs
@@ -171,6 +171,11 @@ export const docs = {
description:
'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
},
+ {
+ name: 'startIcon',
+ type: 'IconType | ReactNode',
+ description: 'SVG icon component displayed at the start of the input.',
+ },
{
name: 'xstyle',
type: 'StyleXStyles',
diff --git a/packages/core/src/__tests__/complexComponentContract.test.tsx b/packages/core/src/__tests__/complexComponentContract.test.tsx
new file mode 100644
index 0000000000..0c39fe60dc
--- /dev/null
+++ b/packages/core/src/__tests__/complexComponentContract.test.tsx
@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+import {docs as DropdownMenuDocs} from '../DropdownMenu/DropdownMenu.doc.mjs';
+import {docs as HoverCardDocs} from '../HoverCard/HoverCard.doc.mjs';
+import {docs as LayoutDocs} from '../Layout/Layout.doc.mjs';
+import {docs as LightboxDocs} from '../Lightbox/Lightbox.doc.mjs';
+import {docs as LinkDocs} from '../Link/Link.doc.mjs';
+import {docs as MultiSelectorDocs} from '../MultiSelector/MultiSelector.doc.mjs';
+import {docs as PowerSearchDocs} from '../PowerSearch/PowerSearch.doc.mjs';
+import {docs as TokenizerDocs} from '../Tokenizer/Tokenizer.doc.mjs';
+import {docs as TooltipDocs} from '../Tooltip/Tooltip.doc.mjs';
+import {docs as TypeaheadDocs} from '../Typeahead/Typeahead.doc.mjs';
+
+// `docs` is the ComponentDoc union (single vs multi component); narrow it
+// for structural access to either the top-level props or the first
+// sub-component's props.
+function getProps(docs: unknown): {name: string}[] {
+ const doc = docs as {
+ props?: {name: string}[];
+ components?: {props?: {name: string}[]}[];
+ };
+ return doc.props || doc.components?.[0]?.props || [];
+}
+
+describe('Complex Component API Contract Drift (#4163)', () => {
+ it('documents search and tokenizer props across input components', () => {
+ const multiProps = getProps(MultiSelectorDocs).map(p => p.name);
+ const tokProps = getProps(TokenizerDocs).map(p => p.name);
+ const powerProps = getProps(PowerSearchDocs).map(p => p.name);
+ const typeProps = getProps(TypeaheadDocs).map(p => p.name);
+
+ expect(multiProps).toContain('startIcon');
+ expect(multiProps).toContain('hasClear');
+ expect(multiProps).toContain('isDefaultOpen');
+
+ expect(tokProps).toContain('startIcon');
+ expect(tokProps).toContain('tokenOverflowBehavior');
+
+ expect(powerProps).toContain('startIcon');
+ expect(powerProps).toContain('menuWidth');
+ expect(powerProps).toContain('maxOperatorMenuItems');
+ expect(powerProps).toContain('tokenOverflowBehavior');
+
+ expect(typeProps).toContain('startIcon');
+ });
+
+ it('documents Layout and DropdownMenu layout props', () => {
+ const layoutProps = getProps(LayoutDocs).map(p => p.name);
+ const dropProps = getProps(DropdownMenuDocs).map(p => p.name);
+
+ expect(layoutProps).toContain('contentWidth');
+ expect(layoutProps).toContain('padding');
+ expect(layoutProps).toContain('defaultHasDividers');
+
+ expect(dropProps).toContain('placement');
+ });
+
+ it('documents HoverCard and Tooltip open state props', () => {
+ const hoverProps = getProps(HoverCardDocs).map(p => p.name);
+ const toolProps = getProps(TooltipDocs).map(p => p.name);
+
+ expect(hoverProps).toContain('isOpen');
+ expect(toolProps).toContain('isOpen');
+ });
+
+ it('documents Link typography and Lightbox gallery props', () => {
+ const linkProps = getProps(LinkDocs).map(p => p.name);
+ const lightProps = getProps(LightboxDocs).map(p => p.name);
+
+ expect(linkProps).toContain('size');
+ expect(linkProps).toContain('weight');
+ expect(linkProps).toContain('color');
+ expect(linkProps).toContain('display');
+ expect(linkProps).toContain('maxLines');
+
+ expect(lightProps).toContain('defaultIndex');
+ expect(lightProps).toContain('hasAutoPlay');
+ });
+});