Skip to content

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.md
new file mode 100644
index 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)
+
+@HelloOjasMutreja
diff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.tsx
new file mode 100644
index 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');
+ });
+});