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.mdnew file mode 100644index 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)++@HelloOjasMutrejadiff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.tsxnew file mode 100644index 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');+ });+});