An open source design system that's fully customizable and agent ready
TypeScript
docs(core): reconcile missing API contract props across 11 components (#4163) (#4315)
Ojas Mutreja6909d0d9c7a6
diff --git a/.changeset/api-contract-drift-docs-tjsk.md b/.changeset/api-contract-drift-docs-tjsk.mdnew file mode 100644index 0000000000..9800f28aa8--- /dev/null+++ b/.changeset/api-contract-drift-docs-tjsk.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[docs] document missing API contract props across Button, Toast, ContextMenu, MoreMenu, Selector, Link, and Dialog (#4163)++@HelloOjasMutrejadiff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjsindex 9768468110..26f76dc75a 100644--- a/packages/core/src/Button/Button.doc.mjs+++ b/packages/core/src/Button/Button.doc.mjs@@ -150,6 +150,28 @@ export const docs = {description:'Async click handler. Shows loading state while the returned promise is pending.',},+ {+ name: 'href',+ type: 'string',+ description:+ 'When provided, renders the button as a link element (<a> or custom link component).',+ },+ {+ name: 'as',+ type: 'ComponentType',+ description:+ 'Custom link component to use when href is provided (e.g. Next.js Link).',+ },+ {+ name: 'target',+ type: 'string',+ description: 'HTML target attribute when rendered as a link (e.g. "_blank").',+ },+ {+ name: 'rel',+ type: 'string',+ description: 'HTML rel attribute when rendered as a link (e.g. "noopener noreferrer").',+ },],playground: {defaults: {diff --git a/packages/core/src/ContextMenu/ContextMenu.doc.mjs b/packages/core/src/ContextMenu/ContextMenu.doc.mjsindex 26a5c87aa5..f041ca9fdb 100644--- a/packages/core/src/ContextMenu/ContextMenu.doc.mjs+++ b/packages/core/src/ContextMenu/ContextMenu.doc.mjs@@ -58,6 +58,11 @@ export const docs = {description: 'Accessible name for the menu surface, announced when it opens.',default: "'Context menu'",},+ {+ name: 'onOpenChange',+ type: '(isOpen: boolean) => void',+ description: 'Callback fired when the menu opens or closes.',+ },{name: 'isDisabled',type: 'boolean',diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjsindex bf45ed2276..78f3fc230e 100644--- a/packages/core/src/Dialog/Dialog.doc.mjs+++ b/packages/core/src/Dialog/Dialog.doc.mjs@@ -90,6 +90,11 @@ export const docs = {description: 'Controls dismissal behavior: required disables Escape and backdrop click; form disables backdrop click after interaction; info allows both.',default: "'info'",},+ {+ name: 'padding',+ type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',+ description: 'Internal padding of the dialog using the spacing scale step.',+ },{name: 'isInline',type: 'boolean',diff --git a/packages/core/src/Link/Link.doc.mjs b/packages/core/src/Link/Link.doc.mjsindex 9f68cbad55..81116e8ff9 100644--- a/packages/core/src/Link/Link.doc.mjs+++ b/packages/core/src/Link/Link.doc.mjs@@ -78,6 +78,17 @@ export const docs = {description:'Link relationship tokens. noopener noreferrer are merged automatically for target="_blank".',},+ {+ name: 'download',+ type: 'string | boolean',+ description:+ 'Causes the browser to download the linked URL. A string specifies the suggested filename.',+ },+ {+ name: 'referrerPolicy',+ type: 'HTMLAttributeReferrerPolicy',+ description: 'Referrer policy for the link.',+ },{name: 'onClick',type: 'MouseEventHandler',diff --git a/packages/core/src/MoreMenu/MoreMenu.doc.mjs b/packages/core/src/MoreMenu/MoreMenu.doc.mjsindex 424de946ee..1d52c38013 100644--- a/packages/core/src/MoreMenu/MoreMenu.doc.mjs+++ b/packages/core/src/MoreMenu/MoreMenu.doc.mjs@@ -46,7 +46,8 @@ export const docs = {type: 'boolean',description: 'Whether the menu trigger is disabled.',default: 'false',- }, {+ },+ {name: 'placement',type: "'above' | 'below' | 'start' | 'end'",description:@@ -60,6 +61,11 @@ export const docs = {"Alignment along the placement axis. Use 'end' to align the menu with the trigger's trailing edge, which is usually what an overflow menu wants.",default: "'start'",},+ {+ name: 'onOpenChange',+ type: '(isOpen: boolean) => void',+ description: 'Callback fired when the menu opens or closes.',+ },{name: 'xstyle',type: 'StyleXStyles',diff --git a/packages/core/src/NumberInput/NumberInput.doc.mjs b/packages/core/src/NumberInput/NumberInput.doc.mjsindex 762adc5b47..6f121e5f8e 100644--- a/packages/core/src/NumberInput/NumberInput.doc.mjs+++ b/packages/core/src/NumberInput/NumberInput.doc.mjs@@ -61,6 +61,11 @@ export const docs = {description:'Whether the field is optional (mutually exclusive with isRequired).',},+ {+ name: 'onKeyDown',+ type: '(e: KeyboardEvent<HTMLInputElement>) => void',+ description: 'Callback fired on keydown events on the input.',+ },{name: 'isRequired',type: 'boolean',diff --git a/packages/core/src/PowerSearch/PowerSearch.doc.mjs b/packages/core/src/PowerSearch/PowerSearch.doc.mjsindex 44377f0b9e..7b57c94926 100644--- a/packages/core/src/PowerSearch/PowerSearch.doc.mjs+++ b/packages/core/src/PowerSearch/PowerSearch.doc.mjs@@ -142,6 +142,16 @@ export const docs = {description: 'Size of the search input and tokens.',default: "'md'",},+ {+ name: 'onFocus',+ type: '(e: FocusEvent<HTMLInputElement>) => void',+ description: 'Fires when focus enters the search input.',+ },+ {+ name: 'onBlur',+ type: '(e: FocusEvent<HTMLInputElement>) => void',+ description: 'Fires when focus leaves the search input.',+ },{name: 'xstyle',type: 'StyleXStyles',diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjsindex b16bff127f..bc5c11355a 100644--- a/packages/core/src/Selector/Selector.doc.mjs+++ b/packages/core/src/Selector/Selector.doc.mjs@@ -186,6 +186,17 @@ 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: 'isLoading',+ type: 'boolean',+ description: 'Shows a loading spinner in the trigger.',+ default: 'false',+ },{name: 'xstyle',type: 'StyleXStyles',diff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjsindex 08757daa46..271c16a084 100644--- a/packages/core/src/TextInput/TextInput.doc.mjs+++ b/packages/core/src/TextInput/TextInput.doc.mjs@@ -71,6 +71,16 @@ export const docs = {'Displays a "Required" indicator next to the label and sets aria-required. Mutually exclusive with isOptional.',default: 'false',},+ {+ name: 'onEnter',+ type: '() => void',+ description: 'Callback fired when the user presses the Enter key.',+ },+ {+ name: 'onKeyDown',+ type: '(e: KeyboardEvent<HTMLInputElement>) => void',+ description: 'Callback fired on keydown events on the input.',+ },{name: 'isDisabled',type: 'boolean',diff --git a/packages/core/src/Toast/Toast.doc.mjs b/packages/core/src/Toast/Toast.doc.mjsindex 9187d81c94..818ba41745 100644--- a/packages/core/src/Toast/Toast.doc.mjs+++ b/packages/core/src/Toast/Toast.doc.mjs@@ -60,6 +60,12 @@ export const docs = {type: '(reason: "auto" | "manual") => void',description: 'Callback fired when the toast is removed.',},+ {+ name: 'onDismiss',+ type: '(reason: "auto" | "manual") => void',+ description: 'Callback fired when the toast is dismissed.',+ required: true,+ },], theming: {targets: [{className: 'astryx-toast', visualProps: ['type']},diff --git a/packages/core/src/Tokenizer/Tokenizer.doc.mjs b/packages/core/src/Tokenizer/Tokenizer.doc.mjsindex f9779566b8..d8dc231cef 100644--- a/packages/core/src/Tokenizer/Tokenizer.doc.mjs+++ b/packages/core/src/Tokenizer/Tokenizer.doc.mjs@@ -201,6 +201,16 @@ 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: 'onFocus',+ type: '(e: FocusEvent<HTMLInputElement>) => void',+ description: 'Fires when focus enters the tokenizer input.',+ },+ {+ name: 'onBlur',+ type: '(e: FocusEvent<HTMLInputElement>) => void',+ description: 'Fires when focus leaves the tokenizer input.',+ },{name: 'xstyle',type: 'StyleXStyles',diff --git a/packages/core/src/__tests__/apiContractDrift.test.tsx b/packages/core/src/__tests__/apiContractDrift.test.tsxnew file mode 100644index 0000000000..0f9462bf8a--- /dev/null+++ b/packages/core/src/__tests__/apiContractDrift.test.tsx@@ -0,0 +1,80 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, it, expect} from 'vitest';++import {docs as ButtonDocs} from '../Button/Button.doc.mjs';+import {docs as ContextMenuDocs} from '../ContextMenu/ContextMenu.doc.mjs';+import {docs as DialogDocs} from '../Dialog/Dialog.doc.mjs';+import {docs as LinkDocs} from '../Link/Link.doc.mjs';+import {docs as MoreMenuDocs} from '../MoreMenu/MoreMenu.doc.mjs';+import {docs as NumberInputDocs} from '../NumberInput/NumberInput.doc.mjs';+import {docs as PowerSearchDocs} from '../PowerSearch/PowerSearch.doc.mjs';+import {docs as SelectorDocs} from '../Selector/Selector.doc.mjs';+import {docs as TextInputDocs} from '../TextInput/TextInput.doc.mjs';+import {docs as ToastDocs} from '../Toast/Toast.doc.mjs';+import {docs as TokenizerDocs} from '../Tokenizer/Tokenizer.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('API Contract Drift Audit (#4163)', () => {+ it('documents Button link mode props', () => {+ const props = getProps(ButtonDocs).map(p => p.name);+ expect(props).toContain('href');+ expect(props).toContain('as');+ expect(props).toContain('target');+ expect(props).toContain('rel');+ });++ it('documents Toast onDismiss callback', () => {+ const props = getProps(ToastDocs).map(p => p.name);+ expect(props).toContain('onDismiss');+ });++ it('documents ContextMenu and MoreMenu onOpenChange callback', () => {+ const contextProps = getProps(ContextMenuDocs).map(p => p.name);+ const moreProps = getProps(MoreMenuDocs).map(p => p.name);+ expect(contextProps).toContain('onOpenChange');+ expect(moreProps).toContain('onOpenChange');+ });++ it('documents Selector startIcon and isLoading props', () => {+ const props = getProps(SelectorDocs).map(p => p.name);+ expect(props).toContain('startIcon');+ expect(props).toContain('isLoading');+ });++ it('documents TextInput and NumberInput onEnter / onKeyDown callbacks', () => {+ const textProps = getProps(TextInputDocs).map(p => p.name);+ const numProps = getProps(NumberInputDocs).map(p => p.name);+ expect(textProps).toContain('onEnter');+ expect(textProps).toContain('onKeyDown');+ expect(numProps).toContain('onEnter');+ expect(numProps).toContain('onKeyDown');+ });++ it('documents PowerSearch and Tokenizer onFocus / onBlur callbacks', () => {+ const powerProps = getProps(PowerSearchDocs).map(p => p.name);+ const tokProps = getProps(TokenizerDocs).map(p => p.name);+ expect(powerProps).toContain('onFocus');+ expect(powerProps).toContain('onBlur');+ expect(tokProps).toContain('onFocus');+ expect(tokProps).toContain('onBlur');+ });++ it('documents Link download / referrerPolicy and Dialog padding props', () => {+ const linkProps = getProps(LinkDocs).map(p => p.name);+ const dialogProps = getProps(DialogDocs).map(p => p.name);+ expect(linkProps).toContain('download');+ expect(linkProps).toContain('referrerPolicy');+ expect(dialogProps).toContain('padding');+ });+});