An open source design system that's fully customizable and agent ready
TypeScript
Replace markdown READMEs with typed .doc.mjs files (no tsx runtime) (#454)
Joey8527b3368c81
diff --git a/.claude/commands/create-component.md b/.claude/commands/create-component.mdindex 5ba7fbdc45..49d6737d9b 100644--- a/.claude/commands/create-component.md+++ b/.claude/commands/create-component.md@@ -22,7 +22,7 @@ Use this structure based on Button.tsx:* @position Core implementation** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/{ComponentName}/README.md+ * - /packages/core/src/{ComponentName}/{ComponentName}.doc.mjs* - /packages/core/src/{ComponentName}/{ComponentName}.test.tsx* - /packages/core/src/{ComponentName}/index.ts* - /apps/storybook/stories/{ComponentName}.stories.tsx@@ -111,46 +111,40 @@ export { {ComponentName} } from './{ComponentName}';export type { {ComponentName}Props, {ComponentName}Variant } from './{ComponentName}';```-### 3. README.md--```markdown-# /packages/core/src/{ComponentName}--Brief description of the component.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Variants**: List variants-- Other features--## Usage--\`\`\`tsx-import { {ComponentName} } from '@xds/core/{ComponentName}';--<{ComponentName} variant="default">Content</{ComponentName}>-\`\`\`--## Props--| Prop | Type | Default | Description |-|------|------|---------|-------------|-| `variant` | `'{variant1}' \| '{variant2}'` | `'default'` | Visual style variant |-| `children` | `ReactNode` | — | Component content |--## Files--| File | Role | Purpose |-|------|------|---------|-| `index.ts` | Entry | Exports component and types |-| `{ComponentName}.tsx` | Core | Component implementation |-| `{ComponentName}.test.tsx` | Test | Unit tests |--## Implementation Notes--- Variant type derived from `keyof typeof variants`+### 3. {ComponentName}.doc.mjs++```js+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: '{ComponentName}',+ description: 'Brief description of the component.',+ features: ['Variants: list available variants'],+ props: [+ {+ name: 'variant',+ type: "'{variant1}' | '{variant2}'",+ description: 'Visual style variant',+ default: "'default'",+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Component content',+ required: true,+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<{ComponentName} variant="default">Content</{ComponentName}>`,+ },+ ],+ theming: {+ componentKey: '{componentName}',+ surfaces: [{name: 'root', description: 'Outer wrapper element'}],+ },+};```### 4. Update /packages/core/src/index.ts@@ -172,6 +166,7 @@ export * from './{ComponentName}';## Token ReferenceAvailable tokens from `tokens.stylex`:+- `colorTokens`: accent, surface, textPrimary, hoverOverlay, pressedOverlay, focusOutline, negative, etc.- `spacingTokens`: space0, space0_5, space1, space2, space3, space4, space5, space6, space7- `radiusTokens`: rounded, container, element, contentdiff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 62a6b40ed0..56e97c38f3 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -58,6 +58,9 @@ jobs:- run: yarn build+ - name: Typecheck component docs+ run: yarn workspace @xds/core typecheck:docs+# Build storybook + analyze components (parallel with test)# Uploads storybook preview and analysis artifacts for downstream jobsbuild:diff --git a/CLAUDE.md b/CLAUDE.mdindex cb2bc31b43..f2ba05b9e1 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -55,7 +55,7 @@ For architectural context, decisions, and research, see the **[GitHub Wiki](http- **Research** — AI + Design Systems, AI Model Trajectory, Swizzle Ergonomics- **Future** — Animation System, RSC Utilities, Distribution Strategy-For component-specific documentation, see the `README.md` in each component directory under `packages/core/src/`.+For component-specific documentation, see the `{Name}.doc.mjs` file in each component directory under `packages/core/src/` (e.g. `Button/Button.doc.mjs`). These are plain JS files with JSDoc type annotations exporting a `ComponentDoc` object (typed via `packages/core/src/docs-types.ts`).## Documentation Standarddiff --git a/apps/sandbox/src/app/pages/polymorphic-link/page.tsx b/apps/sandbox/src/app/pages/polymorphic-link/page.tsxindex f5cb64093f..7f80244d34 100644--- a/apps/sandbox/src/app/pages/polymorphic-link/page.tsx+++ b/apps/sandbox/src/app/pages/polymorphic-link/page.tsx@@ -7,9 +7,8 @@ import {type ReactNode,} from 'react';import * as stylex from '@stylexjs/stylex';-import {XDSVStack, XDSHStack} from '@xds/core/Layout';+import {XDSVStack} from '@xds/core/Layout';import {XDSText, XDSHeading} from '@xds/core/Text';-import {XDSButton} from '@xds/core/Button';import {XDSDivider} from '@xds/core';import {XDSTopNav, XDSTopNavTitle, XDSTopNavItem} from '@xds/core/TopNav';import {XDSSideNav, XDSSideNavItem} from '@xds/core/SideNav';diff --git a/apps/storybook/stories/TopNavMenu.stories.tsx b/apps/storybook/stories/TopNavMenu.stories.tsxindex c9787a4199..8f3adbde6c 100644--- a/apps/storybook/stories/TopNavMenu.stories.tsx+++ b/apps/storybook/stories/TopNavMenu.stories.tsx@@ -17,7 +17,6 @@ import {CodeBracketIcon,GlobeAltIcon,UserCircleIcon,- MagnifyingGlassIcon,} from '@heroicons/react/24/outline';// =============================================================================@@ -155,7 +154,7 @@ export const MultipleMenus: Story = {export const MegaMenu: Story = {name: 'Mega Menu',render: function MegaMenuStory() {- const [menuOpen, setMenuOpen] = useState(false);+ const [, setMenuOpen] = useState(false);return (<div style={{position: 'relative'}}>diff --git a/docs/COMPONENT_README_GUIDE.md b/docs/COMPONENT_README_GUIDE.mddeleted file mode 100644index 5b16e89eec..0000000000--- a/docs/COMPONENT_README_GUIDE.md+++ /dev/null@@ -1,212 +0,0 @@-# Component README Structure Guide--## Why This Matters--The XDS CLI's `extractBrief` function parses component READMEs to generate-LLM-friendly documentation. This documentation powers:--- **`xds component --brief-all`** — compact docs that LLMs use to discover and- correctly use XDS components-- **Vibe tests** — automated evaluations of how well LLMs can build UIs with XDS-- **Developer experience** — `xds component <name>` shows formatted docs in the terminal--When a README doesn't follow the expected structure, the brief extractor can't-find props or examples. This means LLMs miss critical API details — for example,-`XDSText.type` (which controls the semantic HTML element) was invisible to LLMs-because the Text README used `### XDSText / XDSHeading` instead of separate-`### XDSText` and `### XDSHeading` sections.--## Validation--Run the validation script to check all READMEs:--```bash-yarn validate-readmes-```--This runs automatically in CI to catch issues before merge.--## Required Structure--### Single-Component Directories--For directories with one `XDS*.tsx` file (e.g., `Button/`, `Card/`, `Spinner/`):--```markdown-# ComponentName--Brief description of what the component does.--## Usage--\`\`\`tsx-import { XDSComponent } from '@xds/core/Component';--<XDSComponent variant="primary" />-\`\`\`--## Props--| Prop | Type | Default | Description |-| ------------ | ---------------------------- | ------------- | --------------------- |-| \`variant\` | \`'primary' \| 'secondary'\` | \`'primary'\` | Visual style |-| \`size\` | \`'sm' \| 'md' \| 'lg'\` | \`'md'\` | Size of the component |-| \`children\` | \`ReactNode\` | — | Content |-```--**Requirements:**--- A `## Props` section-- A markdown table inside `## Props` with at least one `| \`propName\`` row--### Multi-Component Directories--For directories with multiple `XDS*.tsx` files (e.g., `Text/`, `Stack/`, `Dialog/`):--```markdown-# ComponentGroup--Brief description of the component group.--### XDSComponentA--Description of ComponentA.--\`\`\`tsx-import { XDSComponentA } from '@xds/core/ComponentGroup';--<XDSComponentA requiredProp="value">Content</XDSComponentA>-\`\`\`--| Prop | Type | Default | Description |-| ---------------- | --------------------- | ------- | ---------------------- |-| \`requiredProp\` | \`'a' \| 'b' \| 'c'\` | — | Description (required) |-| \`children\` | \`ReactNode\` | — | Content |--### XDSComponentB--Description of ComponentB.--\`\`\`tsx-<XDSComponentB prop="value" />-\`\`\`--| Prop | Type | Default | Description |-| -------- | ---------- | ------- | ----------- |-| \`prop\` | \`string\` | — | Description |-```--**Requirements for each component:**--- A `### XDSComponentName` heading (exact match — no slashes, no extra text)-- A markdown props table within that section-- At least one `\`\`\`tsx`or`\`\`\`jsx`code block with`<XDS` JSX usage--## Common Mistakes--### ❌ Combined headings--```markdown-### XDSText / XDSHeading-```--The extractor looks for exact `### XDSText` and `### XDSHeading` matches.-Combined headings are invisible to it.--**Fix:** Split into separate sections:--```markdown-### XDSText--...props table and example...--### XDSHeading--...props table and example...-```--### ❌ Props table outside the component section--```markdown-### XDSDialog--Description of Dialog.--## Props--| Prop | Type | Default | Description |-```--The `## Props` heading breaks out of the `### XDSDialog` section (it's a-higher-level heading). The extractor can't associate the table with the component.--**Fix:** Put the table directly under the `###` heading without a separate-`## Props` section:--```markdown-### XDSDialog--Description of Dialog.--| Prop | Type | Default | Description |-```--### ❌ Missing code example--```markdown-### XDSButton--| Prop | Type | Default | Description |-| ----------- | ---------- | ------- | ------------ |-| \`variant\` | \`string\` | — | Visual style |-```--The extractor needs at least one code example to show LLMs how the component-is used.--**Fix:** Add a code block before or after the props table:--```markdown-### XDSButton--\`\`\`tsx-<XDSButton variant="primary" onClick={handleClick}>Save</XDSButton>-\`\`\`--| Prop | Type | Default | Description |-```--### ❌ Code example without XDS JSX--```markdown-\`\`\`tsx-const items = data.map(item => <li>{item.name}</li>);-\`\`\`-```--The extractor looks for `<XDS` in code blocks to find component usage examples.--**Fix:** Include actual component JSX:--```markdown-\`\`\`tsx-<XDSList>-{data.map(item => (-<XDSListItem key={item.id}>{item.name}</XDSListItem>-))}-</XDSList>-\`\`\`-```--## CLI Warnings--When running `xds component --brief` or `--brief-all`, the CLI will print-warnings to stderr if it can't extract complete information:--```-⚠️ No props found for XDSText. Ensure README has a '### XDSText' section with a props table.-⚠️ No code example found for XDSText.-```--These warnings help you identify and fix README structure issues during-development without polluting the brief output itself.diff --git a/internal/vibe-tests/app/src/preview.tsx b/internal/vibe-tests/app/src/preview.tsxindex 94c4aa80af..e2c253f217 100644--- a/internal/vibe-tests/app/src/preview.tsx+++ b/internal/vibe-tests/app/src/preview.tsx@@ -1,3 +1,3 @@-export default function Preview({theme}: {theme: string}) {+export default function Preview({theme: _theme}: {theme: string}) {return <div>No component loaded. Use the screenshot script.</div>;}diff --git a/internal/vibe-tests/src/build-previews.ts b/internal/vibe-tests/src/build-previews.tsindex b9c6751464..67f42fb5b4 100644--- a/internal/vibe-tests/src/build-previews.ts+++ b/internal/vibe-tests/src/build-previews.ts@@ -18,7 +18,7 @@ import {getResultsDir, ensureDir, readJson, writeJson} from './utils.js';const __dirname = path.dirname(new URL(import.meta.url).pathname);const VIBE_DIR = path.resolve(__dirname, '..');-const APP_DIR = path.join(VIBE_DIR, 'app');+const _APP_DIR = path.join(VIBE_DIR, 'app');const REPO_ROOT = path.resolve(VIBE_DIR, '../..');interface PreviewManifest {diff --git a/package.json b/package.jsonindex ca7bd4ddd3..4d63d4d8ae 100644--- a/package.json+++ b/package.json@@ -22,7 +22,6 @@"sync:exports": "node scripts/sync-exports.js","sync:exports:check": "node scripts/sync-exports.js --check","xds": "yarn workspace @xds/cli xds",- "validate-readmes": "node scripts/validate-readmes.mjs","package:source": "node scripts/package-source.js","changeset": "changeset","version-packages": "changeset version",diff --git a/packages/cli/src/commands/component.mjs b/packages/cli/src/commands/component.mjsindex a597cf9a43..d12af2cdf4 100644--- a/packages/cli/src/commands/component.mjs+++ b/packages/cli/src/commands/component.mjs@@ -4,6 +4,9 @@* `xds component --list` prints all components grouped by category.* `xds component <name>` prints the full component README.* `xds component <name> --compact` prints a token-optimized version for LLMs.+ *+ * Component docs live in typed {Name}.doc.mjs files (ComponentDoc exports).+ * This file imports them directly — no markdown parsing needed.*/import * as fs from 'node:fs';@@ -120,6 +123,174 @@ export function discoverComponents(coreDir) {return ordered;}+/**+ * Load the typed docs object from a .doc.mjs file.+ */+export async function loadDocs(readmePath) {+ const mod = await import(pathToFileURL(readmePath).href);+ return mod.docs;+}++/**+ * Find the doc file for a component, checking both top-level+ * and nested directories. Prefers {Name}.doc.mjs, then README.md+ * (for backward compatibility).+ */+export function findComponentReadme(coreDir, name) {+ const srcDir = path.join(coreDir, 'src');+ // Preferred: {Name}.doc.mjs, then README.md+ const docNames = [`${name}.doc.mjs`, 'README.md'];++ for (const docName of docNames) {+ // Direct match: src/{name}/{Name}.doc.mjs (or README.md)+ const direct = path.join(srcDir, name, docName);+ if (fs.existsSync(direct)) return direct;+ }++ // Nested match: src/*/{name}/{Name}.doc.mjs (or README.md)+ const entries = fs.readdirSync(srcDir, {withFileTypes: true});+ for (const docName of docNames) {+ for (const entry of entries) {+ if (!entry.isDirectory()) continue;+ const nested = path.join(srcDir, entry.name, name, docName);+ if (fs.existsSync(nested)) return nested;+ }+ }++ // Fallback: find the directory containing XDS{name}.tsx,+ // then return the doc file in that directory or nearest parent+ const sourcePath = findComponentSource(coreDir, name);+ if (sourcePath) {+ let dir = path.dirname(sourcePath);+ while (dir.startsWith(srcDir)) {+ for (const docName of docNames) {+ const docFile = path.join(dir, docName);+ if (fs.existsSync(docFile)) return docFile;+ }+ dir = path.dirname(dir);+ }+ }++ return null;+}++/**+ * Find the main source file for a component (XDS*.tsx, excluding tests).+ * For "Button" finds src/Button/XDSButton.tsx+ * For "Layout" finds src/Layout/XDSLayout/XDSLayout.tsx+ * For "Card" finds src/Layout/Container/XDSCard.tsx (deep search fallback)+ */+export function findComponentSource(coreDir, name) {+ const srcDir = path.join(coreDir, 'src');+ const xdsName = `XDS${name}.tsx`;++ function searchDir(dirPath) {+ if (!fs.existsSync(dirPath)) return null;+ const entries = fs.readdirSync(dirPath, {withFileTypes: true});++ // Check for exact match first+ const exact = path.join(dirPath, xdsName);+ if (fs.existsSync(exact)) return exact;++ // Recurse into subdirectories+ for (const entry of entries) {+ if (entry.isDirectory()) {+ const found = searchDir(path.join(dirPath, entry.name));+ if (found) return found;+ }+ }+ return null;+ }++ // Search in the component's directory+ const directDir = path.join(srcDir, name);+ if (fs.existsSync(directDir)) {+ const found = searchDir(directDir);+ if (found) return found;+ }++ // Search nested (component might be under a parent dir)+ const entries = fs.readdirSync(srcDir, {withFileTypes: true});+ for (const entry of entries) {+ if (!entry.isDirectory()) continue;+ const nestedDir = path.join(srcDir, entry.name, name);+ if (fs.existsSync(nestedDir)) {+ const found = searchDir(nestedDir);+ if (found) return found;+ }+ }++ // Fallback: search entire src tree for the file+ return searchDir(srcDir);+}++/**+ * Compute the Levenshtein (edit) distance between two strings.+ * Used for fuzzy-matching component names. Dependency-free.+ */+export function levenshteinDistance(a, b) {+ const m = a.length, n = b.length;+ const dp = Array.from({length: m + 1}, () => Array(n + 1).fill(0));+ for (let i = 0; i <= m; i++) dp[i][0] = i;+ for (let j = 0; j <= n; j++) dp[0][j] = j;+ for (let i = 1; i <= m; i++) {+ for (let j = 1; j <= n; j++) {+ dp[i][j] = a[i-1] === b[j-1]+ ? dp[i-1][j-1]+ : 1 + Math.min(dp[i-1][j], dp[i][j-1], dp[i-1][j-1]);+ }+ }+ return dp[m][n];+}++/**+ * Find the closest component names to a given (possibly misspelled) name.+ * Returns matches sorted by distance, filtered to maxDistance.+ */+export function findClosestComponents(name, components, maxDistance = 3) {+ const allNames = Object.values(components).flat();+ const needle = name.toLowerCase();++ const matches = allNames+ .map(comp => ({+ name: comp,+ distance: levenshteinDistance(needle, comp.toLowerCase()),+ }))+ .filter(m => m.distance <= maxDistance)+ .sort((a, b) => a.distance - b.distance);++ return matches;+}++/**+ * Resolve the import path for a component.+ * Returns e.g. '@xds/core/Table' or '@xds/core' depending on package.json exports.+ */+export function resolveImportPath(coreDir, componentName) {+ const srcDir = path.join(coreDir, 'src');+ const sourcePath = findComponentSource(coreDir, componentName);+ if (!sourcePath) return '@xds/core';++ // Get the top-level directory under src/ from the source path+ const relToSrc = path.relative(srcDir, sourcePath);+ const topDir = relToSrc.split(path.sep)[0];++ // Check package.json exports for ./${topDir}+ const pkgPath = path.join(coreDir, 'package.json');+ if (fs.existsSync(pkgPath)) {+ const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));+ if (pkg.exports && pkg.exports[`./${topDir}`]) {+ return `@xds/core/${topDir}`;+ }+ }++ return '@xds/core';+}++// ── Legacy markdown-parsing functions ────────────────────────────────+// These are kept for backward compatibility with existing tests.+// The CLI action handler uses the new format functions below instead.+/*** Minimal cleanup for full docs (default mode).* Strips SYNC comments, rewrites title, collapses blank lines.@@ -277,129 +448,6 @@ export function extractCompact(content, componentName) {return cleaned.join('\n') + '\n';}-/**- * Find the README for a component, checking both top-level- * and nested directories. Falls back to finding the directory- * containing XDS{name}.tsx and returning its nearest README.- */-export function findComponentReadme(coreDir, name) {- const srcDir = path.join(coreDir, 'src');-- // Direct match: src/{name}/README.md- const direct = path.join(srcDir, name, 'README.md');- if (fs.existsSync(direct)) return direct;-- // Nested match: src/*/{name}/README.md- const entries = fs.readdirSync(srcDir, {withFileTypes: true});- for (const entry of entries) {- if (!entry.isDirectory()) continue;- const nested = path.join(srcDir, entry.name, name, 'README.md');- if (fs.existsSync(nested)) return nested;- }-- // Fallback: find the directory containing XDS{name}.tsx,- // then return the README.md in that directory or nearest parent- const sourcePath = findComponentSource(coreDir, name);- if (sourcePath) {- let dir = path.dirname(sourcePath);- while (dir.startsWith(srcDir)) {- const readme = path.join(dir, 'README.md');- if (fs.existsSync(readme)) return readme;- dir = path.dirname(dir);- }- }-- return null;-}--/**- * Find the main source file for a component (XDS*.tsx, excluding tests).- * For "Button" finds src/Button/XDSButton.tsx- * For "Layout" finds src/Layout/XDSLayout/XDSLayout.tsx- * For "Card" finds src/Layout/Container/XDSCard.tsx (deep search fallback)- */-export function findComponentSource(coreDir, name) {- const srcDir = path.join(coreDir, 'src');- const xdsName = `XDS${name}.tsx`;-- function searchDir(dirPath) {- if (!fs.existsSync(dirPath)) return null;- const entries = fs.readdirSync(dirPath, {withFileTypes: true});-- // Check for exact match first- const exact = path.join(dirPath, xdsName);- if (fs.existsSync(exact)) return exact;-- // Recurse into subdirectories- for (const entry of entries) {- if (entry.isDirectory()) {- const found = searchDir(path.join(dirPath, entry.name));- if (found) return found;- }- }- return null;- }-- // Search in the component's directory- const directDir = path.join(srcDir, name);- if (fs.existsSync(directDir)) {- const found = searchDir(directDir);- if (found) return found;- }-- // Search nested (component might be under a parent dir)- const entries = fs.readdirSync(srcDir, {withFileTypes: true});- for (const entry of entries) {- if (!entry.isDirectory()) continue;- const nestedDir = path.join(srcDir, entry.name, name);- if (fs.existsSync(nestedDir)) {- const found = searchDir(nestedDir);- if (found) return found;- }- }-- // Fallback: search entire src tree for the file- return searchDir(srcDir);-}--/**- * Compute the Levenshtein (edit) distance between two strings.- * Used for fuzzy-matching component names. Dependency-free.- */-export function levenshteinDistance(a, b) {- const m = a.length, n = b.length;- const dp = Array.from({length: m + 1}, () => Array(n + 1).fill(0));- for (let i = 0; i <= m; i++) dp[i][0] = i;- for (let j = 0; j <= n; j++) dp[0][j] = j;- for (let i = 1; i <= m; i++) {- for (let j = 1; j <= n; j++) {- dp[i][j] = a[i-1] === b[j-1]- ? dp[i-1][j-1]- : 1 + Math.min(dp[i-1][j], dp[i][j-1], dp[i-1][j-1]);- }- }- return dp[m][n];-}--/**- * Find the closest component names to a given (possibly misspelled) name.- * Returns matches sorted by distance, filtered to maxDistance.- */-export function findClosestComponents(name, components, maxDistance = 3) {- const allNames = Object.values(components).flat();- const needle = name.toLowerCase();-- const matches = allNames- .map(comp => ({- name: comp,- distance: levenshteinDistance(needle, comp.toLowerCase()),- }))- .filter(m => m.distance <= maxDistance)- .sort((a, b) => a.distance - b.distance);-- return matches;-}-/*** Extract a brief, LLM-optimized summary from a README.*@@ -642,31 +690,6 @@ export function extractBriefAll(coreDir) {return output.join('\n');}-/**- * Resolve the import path for a component.- * Returns e.g. '@xds/core/Table' or '@xds/core' depending on package.json exports.- */-export function resolveImportPath(coreDir, componentName) {- const srcDir = path.join(coreDir, 'src');- const sourcePath = findComponentSource(coreDir, componentName);- if (!sourcePath) return '@xds/core';-- // Get the top-level directory under src/ from the source path- const relToSrc = path.relative(srcDir, sourcePath);- const topDir = relToSrc.split(path.sep)[0];-- // Check package.json exports for ./${topDir}- const pkgPath = path.join(coreDir, 'package.json');- if (fs.existsSync(pkgPath)) {- const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));- if (pkg.exports && pkg.exports[`./${topDir}`]) {- return `@xds/core/${topDir}`;- }- }-- return '@xds/core';-}-/*** Ensure compact output includes an import statement.* If the output already contains `from '@xds/core`, returns as-is.@@ -753,6 +776,292 @@ export function extractProps(content, componentName) {return output.join('\n') + '\n';}+// ── Format functions ────────────────────────────────────────────────+// These operate on the typed ComponentDoc object directly.+// Used by the CLI action handler for .doc.mjs files.++/**+ * Render a props array as a markdown table.+ */+function formatPropsTable(props) {+ if (!props || props.length === 0) return '';+ const lines = [];+ lines.push('| Prop | Type | Default | Description |');+ lines.push('|------|------|---------|-------------|');+ for (const p of props) {+ const def = p.default ? `\`${p.default}\`` : '—';+ const req = p.required ? ' **(required)**' : '';+ lines.push(`| \`${p.name}\` | \`${p.type}\` | ${def} | ${p.description}${req} |`);+ }+ return lines.join('\n');+}++/**+ * Format full component docs (default mode, replaces cleanReadme).+ */+export function formatFull(docs) {+ const sections = [];++ sections.push(`# ${docs.name}\n`);+ sections.push(docs.description + '\n');++ if (docs.features?.length) {+ sections.push('## Features\n');+ sections.push(docs.features.map(f => `- ${f}`).join('\n') + '\n');+ }++ // Single component props+ if ('props' in docs) {+ sections.push('## Props\n');+ sections.push(formatPropsTable(docs.props) + '\n');+ }++ // Multi-component+ if ('components' in docs) {+ sections.push('## Components\n');+ for (const comp of docs.components) {+ sections.push(`### ${comp.name}\n`);+ sections.push(comp.description + '\n');+ sections.push(formatPropsTable(comp.props) + '\n');+ if (comp.examples?.length) {+ for (const ex of comp.examples) {+ if (ex.label) sections.push(`#### ${ex.label}\n`);+ sections.push('```tsx\n' + ex.code + '\n```\n');+ }+ }+ }+ }++ if (docs.examples?.length) {+ sections.push('## Examples\n');+ for (const ex of docs.examples) {+ if (ex.label) sections.push(`### ${ex.label}\n`);+ sections.push('```tsx\n' + ex.code + '\n```\n');+ }+ }++ if (docs.theming) {+ sections.push('## Theming\n');+ sections.push(`Component key: \`${docs.theming.componentKey}\`\n`);+ if (docs.theming.surfaces?.length) {+ const surfaceLines = [];+ surfaceLines.push('| Surface | Description |');+ surfaceLines.push('|---------|-------------|');+ for (const s of docs.theming.surfaces) {+ surfaceLines.push(`| \`${s.name}\` | ${s.description} |`);+ }+ sections.push(surfaceLines.join('\n') + '\n');+ }+ }++ if (docs.accessibility?.length) {+ sections.push('## Accessibility\n');+ sections.push(docs.accessibility.map(a => `- ${a}`).join('\n') + '\n');+ }++ if (docs.keyboard) {+ sections.push('## Keyboard\n');+ sections.push(docs.keyboard + '\n');+ }++ if (docs.notes?.length) {+ sections.push('## Notes\n');+ sections.push(docs.notes.map(n => `- ${n}`).join('\n') + '\n');+ }++ return sections.join('\n');+}++/**+ * Format compact docs for LLM consumption (replaces extractCompact + ensureImportStatement).+ * Includes: import, features, props, limited examples, keyboard, notes.+ */+export function formatCompact(docs, componentName, importHint) {+ const displayName = componentName.startsWith('XDS')+ ? componentName+ : `XDS${componentName}`;++ const sections = [];++ sections.push(`# ${docs.name}\n`);+ sections.push(docs.description + '\n');++ // Import statement+ if (importHint) {+ sections.push('## Import\n');+ sections.push(`\`\`\`tsx\nimport { ${displayName} } from '${importHint}';\n\`\`\`\n`);+ }++ if (docs.features?.length) {+ sections.push('## Features\n');+ sections.push(docs.features.map(f => `- ${f}`).join('\n') + '\n');+ }++ // Props+ if ('props' in docs) {+ sections.push('## Props\n');+ sections.push(formatPropsTable(docs.props) + '\n');+ }++ if ('components' in docs) {+ for (const comp of docs.components) {+ sections.push(`### ${comp.name}\n`);+ sections.push(comp.description + '\n');+ sections.push(formatPropsTable(comp.props) + '\n');+ }+ }++ // Limited examples (max 3)+ const examples = docs.examples?.slice(0, 3) || [];+ if (examples.length) {+ sections.push('## Usage\n');+ for (const ex of examples) {+ if (ex.label) sections.push(`### ${ex.label}\n`);+ sections.push('```tsx\n' + ex.code + '\n```\n');+ }+ }++ if (docs.keyboard) {+ sections.push('## Keyboard\n');+ sections.push(docs.keyboard + '\n');+ }++ if (docs.notes?.length) {+ sections.push('## Notes\n');+ sections.push(docs.notes.map(n => `- ${n}`).join('\n') + '\n');+ }++ return sections.join('\n');+}++/**+ * Format a brief, LLM-optimized summary (replaces extractBrief).+ *+ * Format: component signature + key props + one usage example.+ * Targets ~200-400 chars per component (vs ~2-3KB for --compact).+ *+ * For multi-component docs, extracts the entry matching componentName.+ */+export function formatBrief(docs, componentName, importHint) {+ const displayName = componentName.startsWith('XDS')+ ? componentName+ : `XDS${componentName}`;++ // Find the right props and examples for this component+ let props = [];+ let description = docs.description;+ let examples = docs.examples || [];++ if ('props' in docs) {+ props = docs.props;+ } else if ('components' in docs) {+ const entry = docs.components.find(c => c.name === displayName);+ if (entry) {+ props = entry.props;+ description = entry.description;+ examples = entry.examples || docs.examples || [];+ }+ }++ // Build signature from union-type props+ const signatureProps = [];+ const otherProps = [];++ for (const prop of props) {+ if (prop.type.includes('|') && !prop.type.includes('ReactNode')) {+ const values = prop.type+ .replace(/['"]/g, '')+ .split('|')+ .map(v => v.trim())+ .join('|');+ signatureProps.push(`${prop.name}: ${values}`);+ } else if (prop.required) {+ otherProps.unshift(`${prop.name}: ${prop.type.split('|')[0].trim()}`);+ } else {+ otherProps.push(prop.name);+ }+ }++ // Build output+ const output = [];++ // Signature line+ const sigStr =+ signatureProps.length > 0+ ? `${displayName}(${signatureProps.join(', ')})`+ : displayName;+ output.push(importHint ? `${sigStr} ← from '${importHint}'` : sigStr);++ // Description (shortened)+ if (description) {+ const shortDesc =+ description.length > 80+ ? description.slice(0, 77) + '...'+ : description;+ output.push(` ${shortDesc}`);+ }++ // Other props+ if (otherProps.length > 0) {+ output.push(` ${otherProps.join(' · ')}`);+ }++ // First code example+ if (examples.length > 0) {+ const code = examples[0].code;+ const codeLine =+ code.split('\n').find(l => l.trim().startsWith('<XDS')) ||+ code.split('\n')[0];+ output.push(` ${codeLine.trim()}`);+ }++ return output.join('\n') + '\n';+}++/**+ * Format only the props tables (replaces extractProps).+ */+export function formatProps(docs, componentName) {+ if ('props' in docs) {+ return `## Props\n\n${formatPropsTable(docs.props)}\n`;+ }++ if ('components' in docs) {+ const sections = [];+ for (const comp of docs.components) {+ sections.push(`### ${comp.name} Props\n`);+ sections.push(formatPropsTable(comp.props) + '\n');+ }+ return sections.join('\n');+ }++ return `No props documentation found for ${componentName}.\n`;+}++/**+ * Format brief summaries for ALL components in one output.+ */+export async function formatBriefAll(coreDir) {+ const components = discoverComponents(coreDir);+ const output = [];++ for (const [category, comps] of Object.entries(components)) {+ output.push(`## ${category}\n`);+ for (const comp of comps) {+ const readmePath = findComponentReadme(coreDir, comp);+ if (readmePath) {+ const docs = await loadDocs(readmePath);+ const importPath = resolveImportPath(coreDir, comp);+ output.push(formatBrief(docs, comp, importPath));+ } else {+ output.push(`XDS${comp}\n (no docs)\n`);+ }+ }+ }++ return output.join('\n');+}+export function registerComponent(program) {program.command('component [name]')diff --git a/packages/core/package.json b/packages/core/package.jsonindex 6f3c8445ef..2ac7c630be 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -371,6 +371,7 @@"test": "vitest run --root ../..","test:watch": "vitest --root ../..","lint": "eslint src",+ "typecheck:docs": "tsc --project tsconfig.docs.json","build:css": "node ../../scripts/build-css.mjs","postbuild": "yarn build:css"},diff --git a/packages/core/src/AppShell/AppShell.doc.mjs b/packages/core/src/AppShell/AppShell.doc.mjsnew file mode 100644index 0000000000..e7552d6184--- /dev/null+++ b/packages/core/src/AppShell/AppShell.doc.mjs@@ -0,0 +1,232 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'AppShell',+ description:+ 'Application-level layout shell providing header, side navigation, and main content area — composes XDSLayout internally and replaces the XDSPage + XDSPageLayout pattern.',+ features: [+ 'Two navigation slots: topNav (horizontal bar) and sideNav (vertical sidebar)',+ 'Two height modes: fill (viewport-height, independent scroll containers) and auto (page-scroll with sticky nav)',+ 'Controlled and uncontrolled sideNav collapse with responsive auto-collapse via sideNavBreakpoint',+ 'Mobile: collapsed sideNav renders as an overlay with backdrop',+ 'Composes XDSLayout internally for automatic padding collapse, scroll containment, and slot awareness',+ 'Semantic HTML: <main> with role="main", SideNav with role="navigation", skip-to-content link',+ 'Escape key closes mobile sideNav overlay',+ ],+ examples: [+ {+ label: 'TopNav + SideNav (most common)',+ code: `<XDSAppShell+ topNav={+ <XDSTopNav+ label="Main navigation"+ title={<XDSTopNavTitle title="My App" logo={<Logo />} />}+ startContent={+ <>+ <XDSTopNavItem label="Home" href="/" isSelected />+ <XDSTopNavItem label="Products" href="/products" />+ </>+ }+ />+ }+ sideNav={+ // No header — TopNav has the app identity+ <XDSSideNav>+ <XDSSideNavSection title="Main" isHeaderHidden>+ <XDSSideNavItem+ label="Dashboard"+ icon={HomeIcon}+ isSelected+ href="/dashboard"+ />+ <XDSSideNavItem+ label="Analytics"+ icon={ChartBarIcon}+ href="/analytics"+ />+ </XDSSideNavSection>+ <XDSSideNavSection title="Settings">+ <XDSSideNavItem label="General" icon={CogIcon} href="/settings" />+ </XDSSideNavSection>+ </XDSSideNav>+ }>+ <DashboardContent />+</XDSAppShell>`,+ },+ {+ label: 'SideNav only (no TopNav)',+ code: `<XDSAppShell+ sideNav={+ <XDSSideNav+ header={+ <XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />+ }>+ <XDSSideNavSection title="Main" isHeaderHidden>+ <XDSSideNavItem+ label="Dashboard"+ icon={HomeIcon}+ isSelected+ href="/dashboard"+ />+ <XDSSideNavItem+ label="Analytics"+ icon={ChartBarIcon}+ href="/analytics"+ />+ </XDSSideNavSection>+ </XDSSideNav>+ }>+ <DashboardContent />+</XDSAppShell>`,+ },+ {+ label: 'TopNav only (no sideNav)',+ code: `<XDSAppShell+ topNav={+ <XDSTopNav+ label="Navigation"+ title={<XDSTopNavTitle title="Landing Page" />}+ />+ }>+ <LandingContent />+</XDSAppShell>`,+ },+ {+ label: 'Auto height for content-heavy pages',+ code: `<XDSAppShell+ topNav={<XDSTopNav label="Docs" title={<XDSTopNavTitle title="Docs" />} />}+ sideNav={<XDSSideNav>...</XDSSideNav>}+ height="auto"+>+ <LongDocumentContent />+</XDSAppShell>`,+ },+ {+ label: 'Controlled sideNav collapse',+ code: `<XDSAppShell+ topNav={<XDSTopNav label="App" title={<XDSTopNavTitle title="App" />} />}+ sideNav={<XDSSideNav>...</XDSSideNav>}+ isSideNavCollapsed={collapsed}+ onSideNavCollapsedChange={setCollapsed}+>+ <Content />+</XDSAppShell>`,+ },+ {+ label: 'Responsive: SideNav + MobileNav',+ code: `const [mobileOpen, setMobileOpen] = useState(false);+const isMobile = useMediaQuery('(max-width: 768px)');++<XDSAppShell+ topNav={+ <XDSTopNav+ label="Navigation"+ title={<XDSTopNavTitle title="My App" />}+ startContent={+ isMobile ? (+ <XDSButton+ label="Menu"+ icon={<XDSIcon icon="menu" color="inherit" />}+ variant="ghost"+ onClick={() => setMobileOpen(true)}+ />+ ) : (+ <XDSTopNavItem label="Home" href="/" isSelected />+ )+ }+ />+ }+ sideNav={<XDSSideNav>{navSections}</XDSSideNav>}+ mobileNav={+ <XDSMobileNav+ isOpen={mobileOpen}+ onOpenChange={open => setMobileOpen(open)}+ title="My App">+ {navSections}+ </XDSMobileNav>+ }>+ <Content />+</XDSAppShell>`,+ },+ ],+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Main content area, rendered inside a <main> element.',+ },+ {+ name: 'topNav',+ type: 'ReactNode',+ description: 'Top navigation slot, typically XDSTopNav.',+ },+ {+ name: 'sideNav',+ type: 'ReactNode',+ description: 'Side navigation slot, typically XDSSideNav.',+ },+ {+ name: 'mobileNav',+ type: 'ReactNode',+ description:+ 'Mobile navigation slot, typically an XDSMobileNav component. Rendered when the viewport is below the sideNavBreakpoint.',+ },+ {+ name: 'banner',+ type: 'ReactNode',+ description:+ 'Banner slot for system-wide announcements, placed above the topNav.',+ },+ {+ name: 'height',+ type: "'fill' | 'auto'",+ description:+ "Height behavior: 'fill' makes the shell fill the viewport (100dvh) with independent scroll containers; 'auto' lets the shell grow with content and uses sticky positioning for nav.",+ default: "'fill'",+ },+ {+ name: 'isSideNavCollapsed',+ type: 'boolean',+ description: 'Whether the sideNav is collapsed (controlled mode).',+ },+ {+ name: 'defaultIsSideNavCollapsed',+ type: 'boolean',+ description: 'Initial collapsed state for uncontrolled mode.',+ default: 'false',+ },+ {+ name: 'onSideNavCollapsedChange',+ type: '(isCollapsed: boolean) => void',+ description: 'Callback fired when the sideNav collapse state changes.',+ },+ {+ name: 'sideNavBreakpoint',+ type: "'sm' | 'md' | 'lg' | 'none'",+ description:+ 'Viewport-width breakpoint below which the sideNav auto-collapses. Use "none" to disable responsive collapse.',+ default: "'md'",+ },+ {+ name: 'sideNavWidth',+ type: 'number',+ description: 'Width of the sideNav panel in pixels.',+ default: '260',+ },+ ],+ accessibility: [+ 'Semantic HTML via XDSLayout slots — each slot maps to a proper landmark element.',+ '<main> content area has role="main" for landmark navigation.',+ 'SideNav has role="navigation" with aria-label="Application navigation".',+ 'Skip-to-content link is visually hidden but shown on focus for keyboard users.',+ 'Escape key closes the mobile sideNav overlay.',+ ],+ notes: [+ 'When a TopNav is present, omit XDSSideNavHeader from the SideNav — the TopNav already provides app identity. Adding both would double the identity.',+ 'When there is no TopNav, include XDSSideNavHeader inside the SideNav so the app name and logo are present.',+ 'XDSAppShell composes XDSLayout internally: topNav + banner map to XDSLayoutHeader, sideNav maps to XDSLayoutPanel, and children map to XDSLayoutContent.',+ 'SideNav collapse animations currently snap open/closed; ViewTransitions support is planned.',+ 'In "auto" height mode, TopNav gets position: sticky; top: 0 and SideNav gets position: sticky; top: <header-height>.',+ 'In "fill" height mode, the shell fills 100dvh, TopNav is pinned at the top, and both the SideNav and content area have independent scroll containers.',+ ],+};diff --git a/packages/core/src/AppShell/README.md b/packages/core/src/AppShell/README.mddeleted file mode 100644index 352f640dd0..0000000000--- a/packages/core/src/AppShell/README.md+++ /dev/null@@ -1,256 +0,0 @@-# AppShell--Application-level layout shell component.--<!-- SYNC: When files in this directory change, update this document. -->--## Overview--XDSAppShell provides the structural frame for an application: header, side navigation, and main content area. It composes XDSLayout internally and replaces the internal XDSPage + XDSPageLayout pattern.--## Import--```tsx-import {XDSAppShell} from '@xds/core/AppShell';-```--## Composition Patterns--XDSAppShell has two navigation slots: `topNav` (horizontal bar) and `sideNav` (vertical sidebar). How you combine them determines where app identity lives.--### TopNav + SideNav (most common)--When a TopNav is present, the SideNav should **not** include a header — the TopNav already provides the app name and logo. Adding `XDSSideNavHeader` would double the identity.--```tsx-<XDSAppShell- topNav={- <XDSTopNav- label="Main navigation"- title={<XDSTopNavTitle title="My App" logo={<Logo />} />}- startContent={- <>- <XDSTopNavItem label="Home" href="/" isSelected />- <XDSTopNavItem label="Products" href="/products" />- </>- }- />- }- sideNav={- // No header — TopNav has the app identity- <XDSSideNav>- <XDSSideNavSection title="Main" isHeaderHidden>- <XDSSideNavItem- label="Dashboard"- icon={HomeIcon}- isSelected- href="/dashboard"- />- <XDSSideNavItem- label="Analytics"- icon={ChartBarIcon}- href="/analytics"- />- </XDSSideNavSection>- <XDSSideNavSection title="Settings">- <XDSSideNavItem label="General" icon={CogIcon} href="/settings" />- </XDSSideNavSection>- </XDSSideNav>- }>- <DashboardContent />-</XDSAppShell>-```--### SideNav Only (no TopNav)--Without a TopNav, the SideNav needs its own header to provide app identity.--```tsx-<XDSAppShell- sideNav={- <XDSSideNav- header={- <XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />- }>- <XDSSideNavSection title="Main" isHeaderHidden>- <XDSSideNavItem- label="Dashboard"- icon={HomeIcon}- isSelected- href="/dashboard"- />- <XDSSideNavItem- label="Analytics"- icon={ChartBarIcon}- href="/analytics"- />- </XDSSideNavSection>- </XDSSideNav>- }>- <DashboardContent />-</XDSAppShell>-```--### TopNav Only (no sideNav)--For landing pages or simple apps that don't need secondary navigation.--```tsx-<XDSAppShell- topNav={- <XDSTopNav- label="Navigation"- title={<XDSTopNavTitle title="Landing Page" />}- />- }>- <LandingContent />-</XDSAppShell>-```--### Responsive: SideNav + MobileNav--For apps that need both desktop and mobile layouts, use the `mobileNav` slot.-On desktop the SideNav renders inline; on mobile AppShell hides the SideNav-(via `sideNavBreakpoint`) and the consumer shows an XDSMobileNav drawer instead.--Pass a fully composed `<XDSMobileNav>` — AppShell just renders it, same as-every other slot. All drawer props (`isOpen`, `onOpenChange`, `title`) stay on-XDSMobileNav where they belong.--```tsx-const [mobileOpen, setMobileOpen] = useState(false);-const isMobile = useMediaQuery('(max-width: 768px)');--<XDSAppShell- topNav={- <XDSTopNav- label="Navigation"- title={<XDSTopNavTitle title="My App" />}- startContent={- isMobile ? (- <XDSButton- label="Menu"- icon={<XDSIcon icon="menu" color="inherit" />}- variant="ghost"- onClick={() => setMobileOpen(true)}- />- ) : (- <XDSTopNavItem label="Home" href="/" isSelected />- )- }- />- }- sideNav={<XDSSideNav>{navSections}</XDSSideNav>}- mobileNav={- <XDSMobileNav- isOpen={mobileOpen}- onOpenChange={open => setMobileOpen(open)}- title="My App">- {navSections}- </XDSMobileNav>- }>- <Content />-</XDSAppShell>;-```--### Pattern Summary--| Layout | TopNav | SideNav Header | When to use |-| ---------------- | ------ | -------------- | ------------------------------- |-| TopNav + SideNav | ✅ | ❌ Omit | Dashboards, admin panels, tools |-| SideNav only | ❌ | ✅ Include | Simpler apps, focused tools |-| TopNav only | ✅ | N/A | Landing pages, single-page apps |-| Neither | ❌ | N/A | Auth screens, embedded views |--## More Usage--```tsx-// Auto-height for content-heavy pages-<XDSAppShell- topNav={<XDSTopNav label="Docs" title={<XDSTopNavTitle title="Docs" />} />}- sideNav={<XDSSideNav>...</XDSSideNav>}- height="auto"->- <LongDocumentContent />-</XDSAppShell>--// Controlled sideNav collapse-<XDSAppShell- topNav={<XDSTopNav label="App" title={<XDSTopNavTitle title="App" />} />}- sideNav={<XDSSideNav>...</XDSSideNav>}- isSideNavCollapsed={collapsed}- onSideNavCollapsedChange={setCollapsed}->- <Content />-</XDSAppShell>-```--## Props--| Prop | Type | Default | Description |-| --------------------------- | -------------------------------- | -------- | ------------------------------------------- |-| `children` | `ReactNode` | — | Main content area (rendered as `<main>`) |-| `topNav` | `ReactNode` | — | Top navigation slot (typically XDSTopNav) |-| `sideNav` | `ReactNode` | — | Side navigation slot (typically XDSSideNav) |-| `banner` | `ReactNode` | — | Banner slot for system-wide announcements |-| `height` | `'fill' \| 'auto'` | `'fill'` | Height behavior |-| `isSideNavCollapsed` | `boolean` | — | Whether sideNav is collapsed (controlled) |-| `defaultIsSideNavCollapsed` | `boolean` | `false` | Default collapsed state (uncontrolled) |-| `mobileNav` | `ReactNode` | — | Mobile navigation (typically XDSMobileNav) |-| `onSideNavCollapsedChange` | `(isCollapsed: boolean) => void` | — | Collapse change callback |-| `sideNavBreakpoint` | `'sm' \| 'md' \| 'lg' \| 'none'` | `'md'` | Breakpoint for auto-collapse |-| `sideNavWidth` | `number` | `260` | SideNav width in pixels |-| `xstyle` | `StyleXStyles` | — | StyleX overrides |-| `data-testid` | `string` | — | Test ID |--## Height Modes--### Fill (default)--- Shell fills viewport (`100dvh`)-- TopNav is pinned at top-- SideNav has its own scroll container-- Content area scrolls independently-- Best for: dashboards, admin panels, tools--### Auto--- Shell grows with content, page scrolls-- TopNav gets `position: sticky; top: 0`-- SideNav gets `position: sticky; top: <header-height>`-- Best for: docs sites, content-heavy pages--## SideNav Behavior--- **Controlled**: Use `isSideNavCollapsed` + `onSideNavCollapsedChange`-- **Uncontrolled**: Use `defaultIsSideNavCollapsed`-- **Responsive**: `sideNavBreakpoint` auto-collapses below the specified width-- **Mobile**: Collapsed sideNav renders as an overlay with backdrop-- **Animations**: Snap open/closed for now; ViewTransitions support planned--## Internal Composition--XDSAppShell composes `XDSLayout` internally with:--- `header` → `XDSLayoutHeader` containing topNav + banner-- `start` → `XDSLayoutPanel` containing sideNav-- `content` → `XDSLayoutContent` containing children as `<main>`--This gives automatic padding collapse, scroll containment, and slot awareness.--## Accessibility--- Semantic HTML via XDSLayout slots-- `<main>` has `role="main"` for landmark navigation-- SideNav has `role="navigation"` with `aria-label="Application navigation"`-- Skip-to-content link (visually hidden, shown on focus)-- Escape closes mobile sideNav overlay--## Files--| File | Role | Purpose |-| ---------------------- | --------- | --------------------------- |-| `index.ts` | Entry | Exports component and types |-| `XDSAppShell.tsx` | Component | Main shell implementation |-| `XDSAppShell.test.tsx` | Tests | Unit tests |-| `README.md` | Docs | This documentation |diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsxindex 897c6c3696..31dd2692a0 100644--- a/packages/core/src/AppShell/XDSAppShell.tsx+++ b/packages/core/src/AppShell/XDSAppShell.tsx@@ -7,7 +7,7 @@* Use for any app that needs a top nav, side navigation, and scrollable content.** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/AppShell/README.md+ * - /packages/core/src/AppShell/AppShell.doc.mjs* - /packages/core/src/AppShell/index.ts* - /packages/core/src/AppShell/XDSAppShell.test.tsx* - /apps/storybook/stories/AppShell.stories.tsxdiff --git a/packages/core/src/AppShell/index.ts b/packages/core/src/AppShell/index.tsindex ce183c4859..9ac9b90405 100644--- a/packages/core/src/AppShell/index.ts+++ b/packages/core/src/AppShell/index.ts@@ -4,7 +4,7 @@* @output Exports XDSAppShell and related types* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/AppShell/README.md+ * SYNC: When modified, update this header and /packages/core/src/AppShell/AppShell.doc.mjs*/export {XDSAppShell} from './XDSAppShell';diff --git a/packages/core/src/AspectRatio/AspectRatio.doc.mjs b/packages/core/src/AspectRatio/AspectRatio.doc.mjsnew file mode 100644index 0000000000..d84f2ac34a--- /dev/null+++ b/packages/core/src/AspectRatio/AspectRatio.doc.mjs@@ -0,0 +1,54 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'AspectRatio',+ description: 'Maintains a specific aspect ratio for its children.',+ features: [+ 'Accepts any numeric ratio expressed as width/height (e.g. 16/9, 4/3, 1)',+ 'Children are positioned absolutely to fill the container',+ 'Supports theming via the aspectRatio component key',+ ],+ examples: [+ {+ label: 'Widescreen image (16:9)',+ code: `<XDSAspectRatio ratio={16 / 9}>+ <img src="image.jpg" alt="Widescreen image" style={{objectFit: 'cover'}} />+</XDSAspectRatio>`,+ },+ {+ label: 'Square',+ code: `<XDSAspectRatio ratio={1}>+ <Avatar />+</XDSAspectRatio>`,+ },+ {+ label: '4:3 video',+ code: `<XDSAspectRatio ratio={4 / 3}>+ <video src="video.mp4" />+</XDSAspectRatio>`,+ },+ ],+ props: [+ {+ name: 'ratio',+ type: 'number',+ description: 'Aspect ratio as width/height (e.g. 16/9, 1).',+ required: true,+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Content positioned absolutely to fill the container.',+ required: true,+ },+ ],+ theming: {+ componentKey: 'aspectRatio',+ surfaces: [+ {+ name: 'root',+ description: 'Root container styles.',+ },+ ],+ },+};diff --git a/packages/core/src/AspectRatio/README.md b/packages/core/src/AspectRatio/README.mddeleted file mode 100644index c9ecd7c7ae..0000000000--- a/packages/core/src/AspectRatio/README.md+++ /dev/null@@ -1,57 +0,0 @@-# XDSAspectRatio--Maintains a specific aspect ratio for its children.--## Import--```tsx-import {XDSAspectRatio} from '@xds/core/AspectRatio';-```--## Usage--```tsx-<XDSAspectRatio ratio={16 / 9}>- <img src="image.jpg" alt="Widescreen image" style={{objectFit: 'cover'}} />-</XDSAspectRatio>--// Square-<XDSAspectRatio ratio={1}>- <Avatar />-</XDSAspectRatio>--// 4:3 video-<XDSAspectRatio ratio={4 / 3}>- <video src="video.mp4" />-</XDSAspectRatio>-```--## Theming--Themes can override `AspectRatio` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- aspectRatio: {- root: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------- | --------------------- |-| `root` | Root container styles |--## Props--| Prop | Type | Default | Description |-| ---------- | -------------- | ------- | ------------------------------------------------- |-| `ratio` | `number` | — | Aspect ratio as width/height (e.g., 16/9, 1) |-| `children` | `ReactNode` | — | Content positioned absolutely to fill container |-| `xstyle` | `StyleXStyles` | — | StyleX overrides for the container |diff --git a/packages/core/src/AspectRatio/XDSAspectRatio.tsx b/packages/core/src/AspectRatio/XDSAspectRatio.tsxindex d06afdbf47..af6892ed41 100644--- a/packages/core/src/AspectRatio/XDSAspectRatio.tsx+++ b/packages/core/src/AspectRatio/XDSAspectRatio.tsx@@ -5,7 +5,7 @@* @position AspectRatio component; maintains a specific aspect ratio for its children** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/AspectRatio/README.md+ * - /packages/core/src/AspectRatio/AspectRatio.doc.mjs* - /packages/core/src/AspectRatio/XDSAspectRatio.test.tsx* - /apps/storybook/stories/AspectRatio.stories.tsx*/diff --git a/packages/core/src/AspectRatio/index.ts b/packages/core/src/AspectRatio/index.tsindex a93048e2c3..507797266b 100644--- a/packages/core/src/AspectRatio/index.ts+++ b/packages/core/src/AspectRatio/index.ts@@ -4,7 +4,7 @@* @output Exports XDSAspectRatio component and props type* @position Package entry point for AspectRatio*- * SYNC: When modified, update /packages/core/src/AspectRatio/README.md+ * SYNC: When modified, update /packages/core/src/AspectRatio/AspectRatio.doc.mjs*/export {XDSAspectRatio} from './XDSAspectRatio';diff --git a/packages/core/src/Avatar/Avatar.doc.mjs b/packages/core/src/Avatar/Avatar.doc.mjsnew file mode 100644index 0000000000..813a6c28d6--- /dev/null+++ b/packages/core/src/Avatar/Avatar.doc.mjs@@ -0,0 +1,153 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Avatar',+ description:+ 'Avatar component for displaying user profile pictures with fallback support.',+ features: [+ 'Image loading: Primary and fallback image sources',+ 'Initials fallback: Auto-generates initials from user name',+ 'Default icon: Generic person icon when no image or name provided',+ 'Sizes: tiny (20px), xsmall (24px), small (36px), medium (48px), large (128px), plus numeric pixel values',+ 'Status slot: Corner position for status indicators or badges',+ 'Size-aware status dot: Built-in XDSAvatarStatusDot that scales proportionally with avatar size',+ 'Accessible: Proper role and aria-label support',+ ],+ examples: [+ {+ label: 'With image',+ code: '<XDSAvatar src="/user.jpg" name="John Doe" />',+ },+ {+ label: 'Initials fallback',+ code: '<XDSAvatar name="Jane Smith" size="large" />',+ },+ {+ label: 'With size-aware status indicator',+ code: `<XDSAvatar+ src="/user.jpg"+ name="John Doe"+ size="medium"+ status={<XDSAvatarStatusDot variant="positive" label="Online" />}+/>`,+ },+ {+ label: 'Status dot scales automatically across sizes',+ code: `<XDSAvatar name="AB" size="tiny" status={<XDSAvatarStatusDot />} />+<XDSAvatar name="CD" size="large" status={<XDSAvatarStatusDot />} />`,+ },+ {+ label: 'Different variants for different contexts',+ code: `<XDSAvatar name="EF" status={<XDSAvatarStatusDot variant="negative" label="Busy" />} />+<XDSAvatar name="GH" status={<XDSAvatarStatusDot variant="neutral" label="Away" />} />`,+ },+ ],+ theming: {+ componentKey: 'avatar',+ surfaces: [+ {name: 'root', description: 'Root wrapper styles'},+ {name: 'fallback', description: 'Fallback/initials container styles'},+ ],+ },+ notes: [+ 'Always circular shape (border-radius: 50%)',+ 'Uses color.deemphasized and color.textSecondary for fallback background',+ 'Initials extracted from first and last word of name',+ 'XDSAvatarSizeContext provides the resolved numeric size to sub-components',+ 'Status dot uses CIRCLE_EDGE_OFFSET_RATIO for positioning at the 45° point on the circle edge',+ 'Fallback cascade: (1) src loads → show image; (2) src fails → try fallbackSrc; (3) fallbackSrc fails/missing → show initials from name; (4) no name → show generic person icon',+ 'Status dot size tiers: avatar ≤ 36px → 8px dot with 1px border; avatar 40–72px → 16px dot with 2px border; avatar ≥ 96px → 24px dot with 4px border',+ ],+ components: [+ {+ name: 'XDSAvatar',+ description:+ 'Displays a user avatar with image, initials fallback, and optional status indicator.',+ props: [+ {+ name: 'src',+ type: 'string',+ description: 'Primary image source URL.',+ },+ {+ name: 'fallbackSrc',+ type: 'string',+ description: 'Fallback image when primary fails.',+ },+ {+ name: 'name',+ type: 'string',+ description: 'User name for initials and alt text.',+ },+ {+ name: 'alt',+ type: 'string',+ description: 'Alt text (falls back to name).',+ },+ {+ name: 'size',+ type: 'XDSAvatarSize',+ description: 'Avatar size (named or numeric pixel value).',+ default: "'small'",+ },+ {+ name: 'status',+ type: 'ReactNode',+ description: 'Corner content for status indicators.',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: '<XDSAvatar src="/user.jpg" name="John Doe" size="medium" />',+ },+ {+ label: 'With status dot',+ code: `<XDSAvatar+ src="/user.jpg"+ name="John Doe"+ size="medium"+ status={<XDSAvatarStatusDot variant="positive" label="Online" />}+/>`,+ },+ ],+ },+ {+ name: 'XDSAvatarStatusDot',+ description:+ 'Size-aware status indicator dot that reads avatar size from context and scales proportionally.',+ props: [+ {+ name: 'variant',+ type: "'positive' | 'neutral' | 'negative'",+ description: 'Semantic color variant of the dot.',+ default: "'positive'",+ },+ {+ name: 'label',+ type: 'string',+ description: 'Accessible label for screen readers.',+ },+ {+ name: 'icon',+ type: 'ReactNode',+ description: 'Icon centered inside the dot (hidden at tiny sizes).',+ },+ ],+ examples: [+ {+ label: 'Online',+ code: '<XDSAvatarStatusDot variant="positive" label="Online" />',+ },+ {+ label: 'Busy',+ code: '<XDSAvatarStatusDot variant="negative" label="Busy" />',+ },+ {+ label: 'Away',+ code: '<XDSAvatarStatusDot variant="neutral" label="Away" />',+ },+ ],+ },+ ],+};diff --git a/packages/core/src/Avatar/README.md b/packages/core/src/Avatar/README.mddeleted file mode 100644index 4beb7aff82..0000000000--- a/packages/core/src/Avatar/README.md+++ /dev/null@@ -1,129 +0,0 @@-# Avatar--Avatar component for displaying user profile pictures with fallback support.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Image loading**: Primary and fallback image sources-- **Initials fallback**: Auto-generates initials from user name-- **Default icon**: Generic person icon when no image or name provided-- **Sizes**: tiny (20px), xsmall (24px), small (36px), medium (48px), large (128px), plus numeric pixel values-- **Status slot**: Corner position for status indicators or badges-- **Size-aware status dot**: Built-in `XDSAvatarStatusDot` that scales proportionally with avatar size-- **Accessible**: Proper role and aria-label support--## Usage--```tsx-import { XDSAvatar, XDSAvatarStatusDot } from '@xds/core/Avatar';--// With image-<XDSAvatar src="/user.jpg" name="John Doe" />--// Initials fallback-<XDSAvatar name="Jane Smith" size="large" />--// With size-aware status indicator-<XDSAvatar- src="/user.jpg"- name="John Doe"- size="medium"- status={<XDSAvatarStatusDot variant="positive" label="Online" />}-/>--// Status dot scales automatically across sizes-<XDSAvatar name="AB" size="tiny" status={<XDSAvatarStatusDot />} />-<XDSAvatar name="CD" size="large" status={<XDSAvatarStatusDot />} />--// Different variants for different contexts-<XDSAvatar name="EF" status={<XDSAvatarStatusDot variant="negative" label="Busy" />} />-<XDSAvatar name="GH" status={<XDSAvatarStatusDot variant="neutral" label="Away" />} />-```--## Props--### XDSAvatar--```tsx-<XDSAvatar src="/user.jpg" name="John Doe" size="medium" />-```--| Prop | Type | Default | Description |-| ------------- | --------------- | --------- | ------------------------------------ |-| `src` | `string` | — | Primary image source URL |-| `fallbackSrc` | `string` | — | Fallback image when primary fails |-| `name` | `string` | — | User name for initials and alt text |-| `alt` | `string` | — | Alt text (falls back to `name`) |-| `size` | `XDSAvatarSize` | `'small'` | Avatar size (named or numeric) |-| `status` | `ReactNode` | — | Corner content for status indicators |-| `data-testid` | `string` | — | Test ID for testing |--### XDSAvatarStatusDot--```tsx-<XDSAvatarStatusDot variant="positive" label="Online" />-```--| Prop | Type | Default | Description |-| --------- | --------------------------------------- | ------------ | --------------------------------------------------- |-| `variant` | `'positive' \| 'neutral' \| 'negative'` | `'positive'` | Semantic color variant of the dot |-| `label` | `string` | — | Accessible label for screen readers |-| `icon` | `ReactNode` | — | Icon centered inside the dot (hidden at tiny sizes) |--The status dot reads the avatar size from context and uses discrete size tiers:--| Avatar size | Dot size | Border |-| ----------- | -------- | ------ |-| ≤ 36px | 8px | 1px |-| 40–72px | 16px | 2px |-| ≥ 96px | 24px | 4px |--## Fallback Cascade--1. `src` loads → show image-2. `src` fails → try `fallbackSrc`-3. `fallbackSrc` fails/missing → show initials from `name`-4. No `name` → show generic person icon--## Theming--Themes can override `Avatar` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- avatar: {- root: myStyles,- fallback: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ---------- | ---------------------------------- |-| `root` | Root wrapper styles |-| `fallback` | Fallback/initials container styles |--## Files--| File | Role | Purpose |-| ------------------------- | -------- | ------------------------------------------ |-| `index.ts` | Entry | Exports components and types |-| `XDSAvatar.tsx` | Core | Avatar component implementation |-| `XDSAvatarStatusDot.tsx` | Sub-comp | Size-aware status indicator dot |-| `XDSAvatarSizeContext.ts` | Context | Internal context for passing size to slots |--## Implementation Notes--- Always circular shape (border-radius: 50%)-- Uses `color.deemphasized` and `color.textSecondary` for fallback background-- Initials extracted from first and last word of name-- `XDSAvatarSizeContext` provides the resolved numeric size to sub-components-- Status dot uses `CIRCLE_EDGE_OFFSET_RATIO` for positioning at the 45° point on the circle edgediff --git a/packages/core/src/Avatar/XDSAvatar.tsx b/packages/core/src/Avatar/XDSAvatar.tsxindex 09dd046df6..f6d92e6424 100644--- a/packages/core/src/Avatar/XDSAvatar.tsx+++ b/packages/core/src/Avatar/XDSAvatar.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Avatar/README.md (props table, features, implementation notes)+ * - /packages/core/src/Avatar/Avatar.doc.mjs (props table, features, implementation notes)* - /packages/core/src/Avatar/XDSAvatar.test.tsx (tests for new/changed behavior)* - /packages/core/src/Avatar/index.ts (exports if types change)* - /apps/storybook/stories/Avatar.stories.tsx (storybook stories)diff --git a/packages/core/src/Avatar/XDSAvatarSizeContext.ts b/packages/core/src/Avatar/XDSAvatarSizeContext.tsindex 3a400de398..08535cd2d7 100644--- a/packages/core/src/Avatar/XDSAvatarSizeContext.ts+++ b/packages/core/src/Avatar/XDSAvatarSizeContext.ts@@ -5,7 +5,7 @@* @position Internal context; provided by XDSAvatar, consumed by sub-components** SYNC: When modified, update:- * - /packages/core/src/Avatar/README.md+ * - /packages/core/src/Avatar/Avatar.doc.mjs*/'use client';diff --git a/packages/core/src/Avatar/XDSAvatarStatusDot.tsx b/packages/core/src/Avatar/XDSAvatarStatusDot.tsxindex ff58fa0443..1b62c54283 100644--- a/packages/core/src/Avatar/XDSAvatarStatusDot.tsx+++ b/packages/core/src/Avatar/XDSAvatarStatusDot.tsx@@ -5,7 +5,7 @@* @position Sub-component of XDSAvatar; renders a size-aware status indicator** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Avatar/README.md (features, files table)+ * - /packages/core/src/Avatar/Avatar.doc.mjs (features, files table)* - /packages/core/src/Avatar/index.ts (exports)* - /apps/storybook/stories/Avatar.stories.tsx (storybook stories)*/diff --git a/packages/core/src/Avatar/index.ts b/packages/core/src/Avatar/index.tsindex 769a552653..76cc5dc3cc 100644--- a/packages/core/src/Avatar/index.ts+++ b/packages/core/src/Avatar/index.ts@@ -4,7 +4,7 @@* @output Exports XDSAvatar, XDSAvatarProps, XDSAvatarSize, XDSAvatarStatusDot, XDSAvatarStatusDotProps, XDSAvatarStatusDotVariant* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/Avatar/README.md+ * SYNC: When modified, update this header and /packages/core/src/Avatar/Avatar.doc.mjs*/export {XDSAvatar} from './XDSAvatar';diff --git a/packages/core/src/Badge/Badge.doc.mjs b/packages/core/src/Badge/Badge.doc.mjsnew file mode 100644index 0000000000..e8c355936f--- /dev/null+++ b/packages/core/src/Badge/Badge.doc.mjs@@ -0,0 +1,59 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Badge',+ description:+ 'A badge component for displaying status indicators, counts, or labels.',+ props: [+ {+ name: 'variant',+ type: "'neutral' | 'info' | 'success' | 'warning' | 'error'",+ description: 'Visual style variant.',+ default: "'neutral'",+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Badge content. Omit for dot indicator.',+ },+ {+ name: 'icon',+ type: 'ReactNode',+ description: 'Optional leading icon.',+ },+ ],+ examples: [+ {+ label: 'Text badge',+ code: '<XDSBadge>Default</XDSBadge>',+ },+ {+ label: 'Status variants',+ code: `<XDSBadge variant="success">Active</XDSBadge>+<XDSBadge variant="error">Failed</XDSBadge>+<XDSBadge variant="warning">Pending</XDSBadge>`,+ },+ {+ label: 'Count badge',+ code: '<XDSBadge variant="info">42</XDSBadge>',+ },+ {+ label: 'Dot indicator (no children)',+ code: '<XDSBadge variant="success" />',+ },+ ],+ theming: {+ componentKey: 'badge',+ surfaces: [+ {+ name: 'root',+ description: 'Root badge styles.',+ },+ {+ name: 'variants',+ description:+ 'Per-variant overrides (Partial<Record<XDSBadgeVariant, StyleXStyles>>).',+ },+ ],+ },+};diff --git a/packages/core/src/Badge/README.md b/packages/core/src/Badge/README.mddeleted file mode 100644index eedb4d9f4a..0000000000--- a/packages/core/src/Badge/README.md+++ /dev/null@@ -1,71 +0,0 @@-# Badge--A badge component for displaying status indicators, counts, or labels.--## Exports--| Export | Type | Description |-| ----------------- | --------- | -------------------- |-| `XDSBadge` | Component | Main badge component |-| `XDSBadgeProps` | Type | Props interface |-| `XDSBadgeVariant` | Type | Variant union type |--## Props--| Prop | Type | Default | Description |-| ---------- | ---------------------------------------------------------- | ----------- | ------------------------------------- |-| `variant` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'error'` | `'neutral'` | Visual style variant |-| `children` | `ReactNode` | - | Badge content. Omit for dot indicator |-| `icon` | `ReactNode` | - | Optional leading icon |--## Usage--```tsx-import {XDSBadge} from '@xds/core/Badge';--// Text badge-<XDSBadge>Default</XDSBadge>--// Status variants-<XDSBadge variant="success">Active</XDSBadge>-<XDSBadge variant="error">Failed</XDSBadge>-<XDSBadge variant="warning">Pending</XDSBadge>--// Count badge-<XDSBadge variant="info">42</XDSBadge>--// Dot indicator (no children)-<XDSBadge variant="success" />-```--## Theming--Themes can override `Badge` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- badge: {- root: myStyles,- variants: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ---------- | ---------------------------------------------------------------------- |-| `root` | Root badge styles |-| `variants` | Per-variant overrides (Partial<Record<XDSBadgeVariant, StyleXStyles>>) |--## Files--| File | Purpose |-| ------------------- | ------------------------ |-| `XDSBadge.tsx` | Component implementation |-| `XDSBadge.test.tsx` | Unit tests |-| `index.ts` | Barrel exports |diff --git a/packages/core/src/Badge/XDSBadge.tsx b/packages/core/src/Badge/XDSBadge.tsxindex 4240360aa3..203ddb9b87 100644--- a/packages/core/src/Badge/XDSBadge.tsx+++ b/packages/core/src/Badge/XDSBadge.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Badge/README.md (props table, features, implementation notes)+ * - /packages/core/src/Badge/Badge.doc.mjs (props table, features, implementation notes)* - /packages/core/src/Badge/XDSBadge.test.tsx (tests for new/changed behavior)* - /packages/core/src/Badge/index.ts (exports if types change)* - /apps/storybook/stories/Badge.stories.tsx (storybook stories)diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjsnew file mode 100644index 0000000000..f6f2a5c218--- /dev/null+++ b/packages/core/src/Banner/Banner.doc.mjs@@ -0,0 +1,115 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Banner',+ description:+ 'Persistent status notification for info, warning, error, or success messages.',++ features: [+ 'Two-part layout: colored status header with icon, title, description, action buttons, and optional dismiss; optional card-background content area below',+ 'When no children are provided, only the colored header renders',+ 'Self-managed dismiss state — banner hides itself on dismiss without requiring external state wiring',+ 'onDismiss callback fires alongside the internal state change for logging or backend sync',+ 'Default status icons from @heroicons/react/24/solid: InformationCircleIcon (info), ExclamationTriangleIcon (warning), XCircleIcon (error), CheckCircleIcon (success)',+ 'Status colors: info uses --color-accent-deemphasized, warning uses --color-warning-deemphasized, error uses --color-negative-deemphasized, success uses --color-positive-deemphasized',+ 'Card variant (default): has border-radius with optional card content area below the colored header',+ 'Section variant: no border-radius, full-width for page-level banners',+ ],++ examples: [+ {+ label: 'Simple — just the colored header',+ code: '<XDSBanner status="info" title="New update available" />',+ },+ {+ label: 'With description and self-dismissing behavior',+ code: `<XDSBanner+ status="error"+ title="Something went wrong"+ description="Please try again later."+ isDismissable+ onDismiss={() => logDismiss()}+/>`,+ },+ {+ label: 'With content area (card background below header)',+ code: `<XDSBanner+ status="error"+ title="Multiple errors found"+ description="The following issues need to be resolved:"+>+ <ul>+ <li>Email address is invalid</li>+ <li>Password must be at least 8 characters</li>+ </ul>+</XDSBanner>`,+ },+ ],++ props: [+ {+ name: 'status',+ type: "'info' | 'warning' | 'error' | 'success'",+ description: 'Status type controlling icon and color.',+ required: true,+ },+ {+ name: 'title',+ type: 'ReactNode',+ description: 'Title text or ReactNode displayed in the header.',+ required: true,+ },+ {+ name: 'description',+ type: 'ReactNode',+ description: 'Description text rendered below the title in the header.',+ },+ {+ name: 'icon',+ type: 'ReactNode',+ description: 'Override the default status icon.',+ },+ {+ name: 'isDismissable',+ type: 'boolean',+ description: 'Whether the banner can be dismissed by the user.',+ default: 'false',+ },+ {+ name: 'onDismiss',+ type: '() => void',+ description:+ 'Called when the dismiss button is clicked; banner hides itself regardless of whether this is provided.',+ },+ {+ name: 'endContent',+ type: 'ReactNode',+ description:+ 'Action content rendered in the header area, end-aligned. Typically a button or link.',+ },+ {+ name: 'variant',+ type: "'card' | 'section'",+ description:+ 'Visual variant: card has border-radius; section is full-width with no border-radius for page-level use.',+ default: "'card'",+ },+ {+ name: 'children',+ type: 'ReactNode',+ description:+ 'Content rendered in the card-background area below the colored header.',+ },+ ],++ accessibility: [+ 'Uses role="alert" for error and warning statuses',+ 'Uses role="status" for info and success statuses',+ 'Dismiss button has aria-label="Dismiss"',+ 'Status icon is aria-hidden="true" — status is conveyed by the ARIA role instead',+ ],++ notes: [+ 'Collapsible support is planned: the content area will support collapsing via useXDSCollapsible (issue #187)',+ ],+};diff --git a/packages/core/src/Banner/README.md b/packages/core/src/Banner/README.mddeleted file mode 100644index aeffec2cb5..0000000000--- a/packages/core/src/Banner/README.md+++ /dev/null@@ -1,109 +0,0 @@-# XDSBanner--Persistent status notification for info, warning, error, or success messages.--## Visual Structure--The banner has a two-part layout:--1. **Header area** — colored status background with icon, title, description, action buttons, and dismiss-2. **Content area** (optional) — card background below the header for additional rich content--When no `children` are provided, only the colored header renders.--## Usage--```tsx-import {XDSBanner} from '@xds/core/Banner';--// Simple — just the colored header-<XDSBanner status="info" title="New update available" />--// With description and self-dismissing behavior-<XDSBanner- status="error"- title="Something went wrong"- description="Please try again later."- isDismissable- onDismiss={() => logDismiss()}-/>--// With content area (card background below header)-<XDSBanner- status="error"- title="Multiple errors found"- description="The following issues need to be resolved:"->- <ul>- <li>Email address is invalid</li>- <li>Password must be at least 8 characters</li>- </ul>-</XDSBanner>-```--## Props--| Prop | Type | Default | Description |-| --------------- | --------------------------------------------- | -------- | ----------------------------------------------------- |-| `status` | `'info' \| 'warning' \| 'error' \| 'success'` | — | Status type controlling icon and color (required) |-| `title` | `ReactNode` | — | Title text or ReactNode (required) |-| `description` | `ReactNode` | — | Description text below the title |-| `icon` | `ReactNode` | — | Override the default status icon |-| `isDismissable` | `boolean` | `false` | Whether the banner can be dismissed |-| `onDismiss` | `() => void` | — | Called on dismiss (banner hides itself regardless) |-| `endContent` | `ReactNode` | — | Action button in the header area (end-aligned) |-| `variant` | `'card' \| 'section'` | `'card'` | Visual variant |-| `children` | `ReactNode` | — | Content rendered in card-background area below header |-| `xstyle` | `StyleXStyles` | — | StyleX overrides |-| `data-testid` | `string` | — | Test ID |--## Dismiss Behavior--When `isDismissable` is true, the banner manages its own dismissed state internally.-Clicking the dismiss button hides the banner immediately, even if `onDismiss` is not provided.-This ensures product teams get working dismiss behavior out of the box without needing-to wire up state management. The `onDismiss` callback is optional and fires alongside-the internal state change for logging or backend sync.--## Status Colors--| Status | Background Token | Role |-| --------- | ------------------------------- | -------- |-| `info` | `--color-accent-deemphasized` | `status` |-| `warning` | `--color-warning-deemphasized` | `alert` |-| `error` | `--color-negative-deemphasized` | `alert` |-| `success` | `--color-positive-deemphasized` | `status` |--## Variants--- **Card** (default): Has border-radius, colored header with optional card content area below-- **Section**: No border-radius, full-width for page-level banners--## Default Icons--Each status has a default icon from `@heroicons/react/24/solid`:--- `info` → `InformationCircleIcon`-- `warning` → `ExclamationTriangleIcon`-- `error` → `XCircleIcon`-- `success` → `CheckCircleIcon`--## Accessibility--- Uses `role="alert"` for error/warning statuses-- Uses `role="status"` for info/success statuses-- Dismiss button has `aria-label="Dismiss"`-- Status icon is `aria-hidden="true"` (status conveyed by role)--## Future--- **Collapsible**: Banner will support collapsing the content area via `useXDSCollapsible` (#187)--## File Manifest--| File | Purpose |-| -------------------- | ------------------------ |-| `XDSBanner.tsx` | Component implementation |-| `XDSBanner.test.tsx` | Unit tests |-| `index.ts` | Public exports |-| `README.md` | Documentation |diff --git a/packages/core/src/Banner/XDSBanner.tsx b/packages/core/src/Banner/XDSBanner.tsxindex ffcc79ad4d..49df65bba7 100644--- a/packages/core/src/Banner/XDSBanner.tsx+++ b/packages/core/src/Banner/XDSBanner.tsx@@ -11,7 +11,7 @@* - When children are provided, a collapse/expand toggle button appears in the end area** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Banner/README.md (props table, features, implementation notes)+ * - /packages/core/src/Banner/Banner.doc.mjs (props table, features, implementation notes)* - /packages/core/src/Banner/XDSBanner.test.tsx (tests for new/changed behavior)* - /packages/core/src/Banner/index.ts (exports if types change)* - /apps/storybook/stories/Banner.stories.tsx (storybook stories)diff --git a/packages/core/src/Banner/index.ts b/packages/core/src/Banner/index.tsindex d459e8d07e..31589d2615 100644--- a/packages/core/src/Banner/index.ts+++ b/packages/core/src/Banner/index.ts@@ -4,7 +4,7 @@* @output Exports XDSBanner, XDSBannerProps, XDSBannerStatus, XDSBannerVariant* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/Banner/README.md+ * SYNC: When modified, update this header and /packages/core/src/Banner/Banner.doc.mjs*/export {XDSBanner} from './XDSBanner';diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjsnew file mode 100644index 0000000000..bddebdbb94--- /dev/null+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs@@ -0,0 +1,158 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Breadcrumbs',+ description: 'A navigation breadcrumb trail with semantic HTML.',+ features: [+ 'Renders a <nav> landmark with an ordered list of breadcrumb items',+ 'Configurable separator between items (defaults to /)',+ 'Two visual variants: default and supporting (smaller, secondary text)',+ 'Current page item is marked with aria-current="page"',+ 'Separators are hidden from assistive technology via aria-hidden',+ 'Supports icons before item labels via startIcon',+ 'Auto-detects the last child as the current page when no isCurrent is set',+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSBreadcrumbs>+ <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>+ <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>+ <XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>+</XDSBreadcrumbs>`,+ },+ {+ label: 'Supporting variant',+ code: `<XDSBreadcrumbs variant="supporting">+ <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>+ <XDSBreadcrumbItem isCurrent>Page</XDSBreadcrumbItem>+</XDSBreadcrumbs>`,+ },+ {+ label: 'With icons',+ code: `<XDSBreadcrumbs>+ <XDSBreadcrumbItem href="/" startIcon={<XDSIcon icon={HomeIcon} size="sm" />}>+ Home+ </XDSBreadcrumbItem>+ <XDSBreadcrumbItem isCurrent>Settings</XDSBreadcrumbItem>+</XDSBreadcrumbs>`,+ },+ {+ label: 'Item with icon and click handler',+ code: `<XDSBreadcrumbItem href="/settings" startIcon={<XDSIcon icon={CogIcon} size="sm" />}>+ Settings+</XDSBreadcrumbItem>`,+ },+ ],+ accessibility: [+ 'Container renders as a <nav aria-label> landmark; the label defaults to "Breadcrumb" and is customizable via the label prop',+ 'Items are placed inside an <ol> with individual <li> wrappers for correct list semantics',+ 'The current page item receives aria-current="page"',+ 'Separators are rendered with aria-hidden="true" so screen readers skip them',+ 'Auto-detects the last child as the current item when no isCurrent prop is explicitly set',+ ],+ components: [+ {+ name: 'XDSBreadcrumbs',+ description:+ 'Navigation container that renders a <nav> with an ordered list of breadcrumb items.',+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description:+ 'XDSBreadcrumbItem elements to render inside the breadcrumb trail.',+ required: true,+ },+ {+ name: 'separator',+ type: 'ReactNode',+ description: 'Separator rendered between breadcrumb items.',+ default: "'/'",+ },+ {+ name: 'variant',+ type: "'default' | 'supporting'",+ description:+ 'Visual variant — supporting is smaller with secondary text styling.',+ default: "'default'",+ },+ {+ name: 'label',+ type: 'string',+ description: 'Accessible label for the nav landmark (aria-label).',+ default: "'Breadcrumb'",+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSBreadcrumbs>+ <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>+ <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>+ <XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>+</XDSBreadcrumbs>`,+ },+ {+ label: 'Supporting variant',+ code: `<XDSBreadcrumbs variant="supporting">+ <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>+ <XDSBreadcrumbItem isCurrent>Page</XDSBreadcrumbItem>+</XDSBreadcrumbs>`,+ },+ ],+ },+ {+ name: 'XDSBreadcrumbItem',+ description:+ 'Individual breadcrumb item that renders as a link when href is provided, or as plain text for the current page.',+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Label content for the breadcrumb item.',+ required: true,+ },+ {+ name: 'href',+ type: 'string',+ description:+ 'URL the breadcrumb links to; omit for non-navigable items.',+ },+ {+ name: 'onClick',+ type: '(e: MouseEvent) => void',+ description: 'Click handler for the breadcrumb item.',+ },+ {+ name: 'isCurrent',+ type: 'boolean',+ description:+ 'Marks this item as the current page, applying aria-current="page".',+ default: 'false',+ },+ {+ name: 'startIcon',+ type: 'ReactNode',+ description: 'Icon rendered before the item label.',+ },+ ],+ examples: [+ {+ label: 'Link item',+ code: `<XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>`,+ },+ {+ label: 'Current page item',+ code: `<XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>`,+ },+ {+ label: 'With icon',+ code: `<XDSBreadcrumbItem href="/settings" startIcon={<XDSIcon icon={CogIcon} size="sm" />}>+ Settings+</XDSBreadcrumbItem>`,+ },+ ],+ },+ ],+};diff --git a/packages/core/src/Breadcrumbs/README.md b/packages/core/src/Breadcrumbs/README.mddeleted file mode 100644index 9784719ec0..0000000000--- a/packages/core/src/Breadcrumbs/README.md+++ /dev/null@@ -1,97 +0,0 @@-# Breadcrumbs--A navigation breadcrumb trail with semantic HTML.--## Exports--| Export | Type | Description |-| ------------------------ | --------- | -------------------------- |-| `XDSBreadcrumbs` | Component | Container with nav + ol |-| `XDSBreadcrumbsProps` | Type | Container props interface |-| `XDSBreadcrumbsVariant` | Type | Variant union type |-| `XDSBreadcrumbItem` | Component | Individual breadcrumb item |-| `XDSBreadcrumbItemProps` | Type | Item props interface |--### XDSBreadcrumbs--Navigation container that renders a `<nav>` with an ordered list of breadcrumb items.--```tsx-<XDSBreadcrumbs>- <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>- <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>- <XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>-</XDSBreadcrumbs>-```--| Prop | Type | Default | Description |-| ------------- | --------------------------- | -------------- | --------------------------------- |-| `children` | `ReactNode` | — | XDSBreadcrumbItem elements |-| `separator` | `ReactNode` | `'/'` | Separator between items |-| `variant` | `'default' \| 'supporting'` | `'default'` | Visual variant |-| `xstyle` | `StyleXStyles` | — | StyleX overrides |-| `label` | `string` | `'Breadcrumb'` | Accessible label for nav landmark |-| `data-testid` | `string` | — | Test ID |--### XDSBreadcrumbItem--Individual breadcrumb item that renders as a link or plain text.--```tsx-<XDSBreadcrumbItem href="/settings" startIcon={<XDSIcon icon={CogIcon} size="sm" />}>- Settings-</XDSBreadcrumbItem>-```--| Prop | Type | Default | Description |-| ------------- | ------------------------- | ------- | ------------------------------------ |-| `children` | `ReactNode` | — | Item label content |-| `href` | `string` | — | URL for the breadcrumb link |-| `onClick` | `(e: MouseEvent) => void` | — | Click handler |-| `isCurrent` | `boolean` | `false` | Marks as current page (aria-current) |-| `startIcon` | `ReactNode` | — | Icon before the label |-| `data-testid` | `string` | — | Test ID |--## Usage--```tsx-import {XDSBreadcrumbs, XDSBreadcrumbItem} from '@xds/core/Breadcrumbs';--// Basic breadcrumbs-<XDSBreadcrumbs>- <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>- <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>- <XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>-</XDSBreadcrumbs>--// Supporting variant (smaller, secondary text)-<XDSBreadcrumbs variant="supporting">- <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>- <XDSBreadcrumbItem isCurrent>Page</XDSBreadcrumbItem>-</XDSBreadcrumbs>--// With icons-<XDSBreadcrumbs>- <XDSBreadcrumbItem href="/" startIcon={<XDSIcon icon={HomeIcon} size="sm" />}>- Home- </XDSBreadcrumbItem>- <XDSBreadcrumbItem isCurrent>Settings</XDSBreadcrumbItem>-</XDSBreadcrumbs>-```--## Accessibility--- Container is `<nav aria-label>` landmark-- Items in `<ol>` with `<li>` elements-- Current item has `aria-current="page"`-- Separators are `aria-hidden="true"`-- Auto-detects last child as current when no `isCurrent` is set--## Files--| File | Purpose |-| ------------------------- | ------------------------- |-| `XDSBreadcrumbs.tsx` | Container component |-| `XDSBreadcrumbItem.tsx` | Individual item component |-| `XDSBreadcrumbs.test.tsx` | Unit tests |-| `index.ts` | Barrel exports |diff --git a/packages/core/src/Breadcrumbs/XDSBreadcrumbItem.tsx b/packages/core/src/Breadcrumbs/XDSBreadcrumbItem.tsxindex 374c485c60..82f426257f 100644--- a/packages/core/src/Breadcrumbs/XDSBreadcrumbItem.tsx+++ b/packages/core/src/Breadcrumbs/XDSBreadcrumbItem.tsx@@ -5,7 +5,7 @@* @position Individual breadcrumb item; used inside XDSBreadcrumbs** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Breadcrumbs/README.md+ * - /packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs* - /packages/core/src/Breadcrumbs/XDSBreadcrumbs.test.tsx* - /packages/core/src/Breadcrumbs/index.ts* - /apps/storybook/stories/Breadcrumbs.stories.tsxdiff --git a/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx b/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsxindex d6cd87f8ca..647aeccb05 100644--- a/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx+++ b/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx@@ -5,7 +5,7 @@* @position Core container component; consumed by index.ts** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Breadcrumbs/README.md+ * - /packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs* - /packages/core/src/Breadcrumbs/XDSBreadcrumbs.test.tsx* - /packages/core/src/Breadcrumbs/index.ts* - /apps/storybook/stories/Breadcrumbs.stories.tsxdiff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjsnew file mode 100644index 0000000000..912eb08ef8--- /dev/null+++ b/packages/core/src/Button/Button.doc.mjs@@ -0,0 +1,141 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Button',+ description:+ 'XDSButton component with multiple variants, sizes, and isLoading state support.',++ features: [+ "Variants: 'primary', 'secondary', 'ghost', 'destructive'",+ 'Sizes: sm (28px), md (32px), lg (36px)',+ 'Loading state: Shows spinner, disables interaction',+ 'Focus visible: Accessible focus outline with variant-specific colors',+ 'Hover/active states: Uses overlay colors via backgroundImage for consistent layering',+ ],++ props: [+ {+ name: 'label',+ type: 'string',+ description:+ 'Accessible label; used as aria-label for icon-only buttons.',+ required: true,+ },+ {+ name: 'variant',+ type: "'primary' | 'secondary' | 'ghost' | 'destructive'",+ description: 'Visual style variant.',+ default: "'secondary'",+ },+ {+ name: 'size',+ type: "'sm' | 'md' | 'lg'",+ description: 'Size variant.',+ default: "'md'",+ },+ {+ name: 'isLoading',+ type: 'boolean',+ description: 'Shows a loading spinner and disables interaction.',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Disables the button.',+ default: 'false',+ },+ {+ name: 'icon',+ type: 'ReactNode',+ description:+ 'Icon element. When provided without children the button renders as a square icon-only button.',+ },+ {+ name: 'children',+ type: 'ReactNode',+ description:+ 'Button content. When provided alongside icon, the text is rendered next to the icon.',+ },+ {+ name: 'endSlot',+ type: 'ReactElement<XDSIconProps> | ReactElement<XDSBadgeProps>',+ description:+ 'Trailing icon or badge rendered after the label. Only accepts <XDSIcon> or <XDSBadge>. Ignored for icon-only buttons. Color is inherited from the button variant.',+ },+ {+ name: 'tooltip',+ type: 'string',+ description: 'Tooltip text shown on hover.',+ },+ {+ name: 'onClick',+ type: '(e: MouseEvent) => void',+ description:+ 'Standard click handler (passed through from ButtonHTMLAttributes).',+ },+ {+ name: 'onClickAction',+ type: '(e: MouseEvent) => void | Promise<void>',+ description:+ 'Async click handler. Shows loading state while the returned promise is pending.',+ },+ ],++ examples: [+ {+ label: 'Basic',+ code: '<XDSButton label="Click me" variant="primary" />',+ },+ {+ label: 'With size',+ code: '<XDSButton label="Large button" variant="primary" size="lg" />',+ },+ {+ label: 'Loading state',+ code: '<XDSButton label="Saving..." variant="primary" isLoading />',+ },+ {+ label: 'Destructive action',+ code: '<XDSButton label="Delete" variant="destructive" />',+ },+ {+ label: 'Icon-only button',+ code: `// Pass \`icon\` without \`children\` — \`label\` becomes the aria-label+<XDSButton label="Settings" icon={<GearIcon />} variant="ghost" />`,+ },+ {+ label: 'Icon-only with emoji content',+ code: '<XDSButton label="Select rocket emoji" icon={<span>🚀</span>} variant="ghost" size="sm" />',+ },+ {+ label: 'Icon + visible label',+ code: '<XDSButton label="Edit" icon={<PencilIcon />}>Edit</XDSButton>',+ },+ {+ label: 'endSlot — badge after label',+ code: '<XDSButton label="Messages" endSlot={<XDSBadge>3</XDSBadge>} />',+ },+ {+ label: 'endSlot — icon, label, and badge',+ code: '<XDSButton label="Edit" icon={<PencilIcon />} endSlot={<XDSBadge>New</XDSBadge>}>Edit</XDSButton>',+ },+ {+ label: 'endSlot — settings with badge',+ code: `<XDSButton label="Settings" icon={<GearIcon />} endSlot={<XDSBadge>New</XDSBadge>}>+ Settings+</XDSButton>`,+ },+ ],++ notes: [+ 'XDSButtonVariant type is derived from the variants StyleX object using keyof typeof variants.',+ 'Hover/active states use backgroundImage with linear-gradient to layer overlay colors on top of the base background.',+ 'Destructive variant uses colorTokens.negative for its focus outline color.',+ 'endSlot is wrapped in a <span> with color: inherit so icons/badges match the button text color across all variants.',+ 'When icon is provided without children, the button becomes icon-only: it renders as a perfect square (aspectRatio: 1/1), and label is used as aria-label (not rendered visually). Works with any ReactNode as the icon — SVG components, emoji, or text.',+ 'endSlot is ignored for icon-only buttons (when icon is provided without children) to preserve the square aspect ratio.',+ 'Prefer XDSButton over <div onClick> or <span onClick> for accessibility — it provides keyboard navigation, focus management, and screen reader support.',+ 'Icon-only buttons are suitable for toolbars, action grids, and compact controls.',+ ],+};diff --git a/packages/core/src/Button/README.md b/packages/core/src/Button/README.mddeleted file mode 100644index 26e4b5cfa0..0000000000--- a/packages/core/src/Button/README.md+++ /dev/null@@ -1,104 +0,0 @@-# Button--XDSButton component with multiple variants, sizes, and isLoading state support.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Variants**: `primary`, `secondary`, `ghost`, `destructive`-- **Sizes**: `sm` (28px), `md` (32px), `lg` (36px)-- **Loading state**: Shows spinner, disables interaction-- **Focus visible**: Accessible focus outline with variant-specific colors-- **Hover/active states**: Uses overlay colors via `backgroundImage` for consistent layering--## Usage--```tsx-import { XDSButton } from '@xds/core/Button';--// Basic usage-<XDSButton label="Click me" variant="primary" />--// With size-<XDSButton label="Large button" variant="primary" size="lg" />--// With isLoading state-<XDSButton label="Saving..." variant="primary" isLoading />--// Destructive action-<XDSButton label="Delete" variant="destructive" />--// Icon-only button (renders as a square)-// Pass `icon` without `children` — `label` becomes the aria-label-<XDSButton label="Settings" icon={<GearIcon />} variant="ghost" />--// Icon-only with emoji or text content-<XDSButton label="Select rocket emoji" icon={<span>🚀</span>} variant="ghost" size="sm" />--// Icon + visible label (pass children to show text alongside icon)-<XDSButton label="Edit" icon={<PencilIcon />}>Edit</XDSButton>--// With endSlot — badge or trailing icon after the label-<XDSButton label="Messages" endSlot={<XDSBadge>3</XDSBadge>} />-<XDSButton label="Edit" icon={<PencilIcon />} endSlot={<XDSBadge>New</XDSBadge>}>Edit</XDSButton>-```--### Icon-Only Buttons--When `icon` is provided without `children`, the button becomes **icon-only**:--- Renders as a perfect square (`aspectRatio: 1/1`)-- `label` is used as `aria-label` for accessibility (not rendered visually)-- Works with any `ReactNode` as the icon — SVG components, emoji, or text--Use icon-only buttons for toolbars, action grids, compact controls, and anywhere-you need a small clickable element. Always prefer `XDSButton` over `<div onClick>`-or `<span onClick>` for accessibility (keyboard navigation, focus management, screen readers).--## Props--| Prop | Type | Default | Description |-| ------------ | ----------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |-| `label` | `string` | — | Accessible label (required) |-| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'destructive'` | `'secondary'` | Visual style variant |-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant |-| `isLoading` | `boolean` | `false` | Shows isLoading spinner |-| `isDisabled` | `boolean` | `false` | Disables the button |-| `icon` | `ReactNode` | — | Icon element |-| `children` | `ReactNode` | — | Button content |-| `endSlot` | `ReactElement<XDSIconProps> \| ReactElement<XDSBadgeProps>` | — | Trailing icon or badge after the label. Only accepts `<XDSIcon>` or `<XDSBadge>`. Ignored for icon-only. Color is inherited from the button variant. |-| `tooltip` | `string` | — | Tooltip text shown on hover |-| `onClick` | `(e: MouseEvent) => void` | — | Standard click handler (passed through from `ButtonHTMLAttributes`) |-| `onClickAction` | `(e: MouseEvent) => void \| Promise<void>` | — | Async click handler. Shows loading state while the returned promise is pending. |--## Files--| File | Role | Purpose |-| -------------------- | ----- | ------------------------------------- |-| `index.ts` | Entry | Exports XDSButton component and types |-| `XDSButton.tsx` | Core | XDSButton component implementation |-| `XDSButton.test.tsx` | Test | Unit tests for XDSButton component |--### endSlot--The `endSlot` prop renders an `<XDSIcon>` or `<XDSBadge>` after the label text:--```tsx-// Counter badge-<XDSButton label="Messages" endSlot={<XDSBadge>3</XDSBadge>} />--// Icon + label + endSlot-<XDSButton label="Settings" icon={<GearIcon />} endSlot={<XDSBadge>New</XDSBadge>}>- Settings-</XDSButton>-```--`endSlot` is ignored for icon-only buttons (when `icon` is provided without `children`) to preserve the square aspect ratio. The endSlot is wrapped in a container that inherits the button's text color (`color: inherit`), so `<XDSIcon>` elements will automatically match the button variant's color (e.g., white text on `primary`/`destructive` variants) without needing an explicit `color` prop.--## Implementation Notes--- `XDSButtonVariant` type is derived from the `variants` StyleX object using `keyof typeof variants`-- Hover/active states use `backgroundImage` with `linear-gradient` to layer overlay colors on top of the base background-- Destructive variant uses `colorTokens.negative` for its focus outline color-- `endSlot` is wrapped in a `<span>` with `color: inherit` so icons/badges match the button's text color across all variantsdiff --git a/packages/core/src/Button/XDSButton.tsx b/packages/core/src/Button/XDSButton.tsxindex 47092a38d9..c9f1753f38 100644--- a/packages/core/src/Button/XDSButton.tsx+++ b/packages/core/src/Button/XDSButton.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSButton.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Button/README.md (props table, features, implementation notes)+ * - /packages/core/src/Button/Button.doc.mjs (props table, features, implementation notes)* - /packages/core/src/Button/XDSButton.test.tsx (tests for new/changed behavior)* - /packages/core/src/Button/index.ts (exports if types change)* - /apps/storybook/stories/Button.stories.tsx (storybook stories)diff --git a/packages/core/src/Button/index.ts b/packages/core/src/Button/index.tsindex ce5abca43c..b719630a87 100644--- a/packages/core/src/Button/index.ts+++ b/packages/core/src/Button/index.ts@@ -4,7 +4,7 @@* @output Exports XDSButton, XDSButtonProps, XDSButtonVariant* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/Button/README.md+ * SYNC: When modified, update this header and /packages/core/src/Button/Button.doc.mjs*/export {XDSButton} from './XDSButton';diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjsnew file mode 100644index 0000000000..eed8f94535--- /dev/null+++ b/packages/core/src/Calendar/Calendar.doc.mjs@@ -0,0 +1,133 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Calendar',+ description:+ 'XDSCalendar component for date selection with single and range modes.',+ features: [+ "Selection Modes: 'single' (default) and 'range'",+ 'Multi-Month Display: Show 1 or 2 months side by side',+ 'Date Constraints: min, max, and custom dateConstraints functions',+ 'Locale Options: weekStartsOn for configurable first day of week',+ 'Week Numbers: Optional ISO week number column',+ 'Controlled/Uncontrolled: Supports both patterns via value/defaultValue',+ ],+ examples: [+ {+ label: 'Single date selection',+ code: `<XDSCalendar+ value="2026-01-28"+ onChange={(value, valueAsDate) => console.log(value)}+/>`,+ },+ {+ label: 'Range selection',+ code: `<XDSCalendar+ mode="range"+ value={{ start: "2026-01-28", end: "2026-02-05" }}+ onChange={(range) => console.log(range.start, range.end)}+/>`,+ },+ {+ label: 'Two months with constraints',+ code: `<XDSCalendar+ numberOfMonths={2}+ min="2026-01-01"+ max="2026-12-31"+ weekStartsOn={1}+/>`,+ },+ ],+ props: [+ {+ name: 'mode',+ type: "'single' | 'range'",+ description: 'Selection mode.',+ default: "'single'",+ },+ {+ name: 'value',+ type: 'ISODateString | DateRange',+ description: 'Controlled selected value.',+ },+ {+ name: 'defaultValue',+ type: 'ISODateString | DateRange',+ description: 'Uncontrolled default value.',+ },+ {+ name: 'onChange',+ type: 'Function',+ description: 'Selection callback.',+ },+ {+ name: 'numberOfMonths',+ type: '1 | 2',+ description: 'Number of months to display.',+ default: '1',+ },+ {+ name: 'min',+ type: 'ISODateString',+ description: 'Minimum selectable date.',+ },+ {+ name: 'max',+ type: 'ISODateString',+ description: 'Maximum selectable date.',+ },+ {+ name: 'dateConstraints',+ type: 'Array<(date: Date) => boolean>',+ description: 'Custom constraint functions.',+ },+ {+ name: 'focusDate',+ type: 'ISODateString',+ description: 'Controlled visible month.',+ },+ {+ name: 'onFocusDateChange',+ type: '(focusDate: ISODateString) => void',+ description: 'Navigation callback.',+ },+ {+ name: 'hasOutsideDays',+ type: 'boolean',+ description: 'Show days from adjacent months.',+ default: 'true',+ },+ {+ name: 'hasWeekNumbers',+ type: 'boolean',+ description: 'Show ISO week numbers.',+ default: 'false',+ },+ {+ name: 'hasVariableRowCount',+ type: 'boolean',+ description: 'Variable vs fixed 6-row grid.',+ default: 'false',+ },+ {+ name: 'weekStartsOn',+ type: '0 | 1 | 2 | 3 | 4 | 5 | 6',+ description: 'First day of week (0=Sunday).',+ default: '0',+ },+ ],+ theming: {+ componentKey: 'calendar',+ surfaces: [+ {+ name: 'root',+ description: 'Root container styles',+ },+ ],+ },+ notes: [+ 'ISODateString type: `${number}${number}${number}${number}-${number}${number}-${number}${number}`',+ 'DayOfWeek type: 0 | 1 | 2 | 3 | 4 | 5 | 6',+ 'DateRange interface: { start: ISODateString; end: ISODateString }',+ ],+};diff --git a/packages/core/src/Calendar/README.md b/packages/core/src/Calendar/README.mddeleted file mode 100644index b1ad07069d..0000000000--- a/packages/core/src/Calendar/README.md+++ /dev/null@@ -1,103 +0,0 @@-# Calendar--XDSCalendar component for date selection with single and range modes.--## Features--- **Selection Modes**: `single` (default) and `range`-- **Multi-Month Display**: Show 1 or 2 months side by side-- **Date Constraints**: `min`, `max`, and custom `dateConstraints` functions-- **Locale Options**: `weekStartsOn` for configurable first day of week-- **Week Numbers**: Optional ISO week number column-- **Controlled/Uncontrolled**: Supports both patterns via `value`/`defaultValue`--## Usage--```tsx-import { XDSCalendar } from '@xds/core/Calendar';--// Single date selection-<XDSCalendar- value="2026-01-28"- onChange={(value, valueAsDate) => console.log(value)}-/>--// Range selection-<XDSCalendar- mode="range"- value={{ start: "2026-01-28", end: "2026-02-05" }}- onChange={(range) => console.log(range.start, range.end)}-/>--// Two months with constraints-<XDSCalendar- numberOfMonths={2}- min="2026-01-01"- max="2026-12-31"- weekStartsOn={1}-/>-```--## Props--| Prop | Type | Default | Description |-| --------------------- | ------------------------------------ | ---------- | ------------------------------ |-| `mode` | `'single' \| 'range'` | `'single'` | Selection mode |-| `value` | `ISODateString \| DateRange` | — | Controlled selected value |-| `defaultValue` | `ISODateString \| DateRange` | — | Uncontrolled default value |-| `onChange` | `Function` | — | Selection callback |-| `numberOfMonths` | `1 \| 2` | `1` | Number of months to display |-| `min` | `ISODateString` | — | Minimum selectable date |-| `max` | `ISODateString` | — | Maximum selectable date |-| `dateConstraints` | `Array<(date: Date) => boolean>` | — | Custom constraint functions |-| `focusDate` | `ISODateString` | — | Controlled visible month |-| `onFocusDateChange` | `(focusDate: ISODateString) => void` | — | Navigation callback |-| `hasOutsideDays` | `boolean` | `true` | Show days from adjacent months |-| `hasWeekNumbers` | `boolean` | `false` | Show ISO week numbers |-| `hasVariableRowCount` | `boolean` | `false` | Variable vs fixed 6-row grid |-| `weekStartsOn` | `0-6` | `0` | First day of week (0=Sunday) |--## Types--```typescript-type ISODateString =- `${number}${number}${number}${number}-${number}${number}-${number}${number}`;--type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;--interface DateRange {- start: ISODateString;- end: ISODateString;-}-```--## Theming--Themes can override `Calendar` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- calendar: {- root: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------- | --------------------- |-| `root` | Root container styles |--## Files--| File | Role | Purpose |-| -------------------- | ------ | ------------------------ |-| XDSCalendar.tsx | Core | Component implementation |-| XDSCalendar.test.tsx | Test | Unit tests |-| index.ts | Export | Public API exports |-| README.md | Docs | This documentation |diff --git a/packages/core/src/Calendar/XDSCalendar.tsx b/packages/core/src/Calendar/XDSCalendar.tsxindex 1c5fce5ee8..60c663139b 100644--- a/packages/core/src/Calendar/XDSCalendar.tsx+++ b/packages/core/src/Calendar/XDSCalendar.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSCalendar.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Calendar/README.md (props table, features, implementation notes)+ * - /packages/core/src/Calendar/Calendar.doc.mjs (props table, features, implementation notes)* - /packages/core/src/Calendar/XDSCalendar.test.tsx (tests for new/changed behavior)* - /packages/core/src/Calendar/index.ts (exports if types change)* - /apps/storybook/stories/Calendar.stories.tsx (storybook stories)diff --git a/packages/core/src/Calendar/index.ts b/packages/core/src/Calendar/index.tsindex 86dc69a2da..e3f7f8020f 100644--- a/packages/core/src/Calendar/index.ts+++ b/packages/core/src/Calendar/index.ts@@ -4,7 +4,7 @@* @output Exports XDSCalendar and related types* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/Calendar/README.md+ * SYNC: When modified, update this header and /packages/core/src/Calendar/Calendar.doc.mjs*/export {XDSCalendar} from './XDSCalendar';diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjsnew file mode 100644index 0000000000..f47f8a4636--- /dev/null+++ b/packages/core/src/Card/Card.doc.mjs@@ -0,0 +1,96 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Card',+ description: 'Card container component with elevation and themed styling.',+ features: [+ 'Top-level container for elevated content',+ 'Provides card-specific appearance: background, shadow, and border-radius',+ 'Sets CSS variables for child layout components',+ 'Supports optional full-bleed mode to remove internal padding for edge-to-edge content',+ 'Composable with XDSLayout, XDSCollapsible, and XDSCollapsibleGroup',+ ],+ props: [+ {+ name: 'width',+ type: 'SizeValue',+ description: 'Width of the card (number = pixels, string = used as-is).',+ },+ {+ name: 'height',+ type: 'SizeValue',+ description: 'Height of the card (number = pixels, string = used as-is).',+ },+ {+ name: 'maxWidth',+ type: 'SizeValue',+ description: 'Maximum width of the card.',+ },+ {+ name: 'minHeight',+ type: 'SizeValue',+ description: 'Minimum height of the card.',+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Content to render inside the card.',+ },+ {+ name: 'isFullBleed',+ type: 'boolean',+ description: 'Removes internal padding for edge-to-edge content.',+ default: 'false',+ },+ ],+ examples: [+ {+ label: 'Basic card with layout',+ code: `<XDSCard width={400} height={300}>+ <XDSLayout+ header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}+ content={<XDSLayoutContent>Content</XDSLayoutContent>}+ footer={<XDSLayoutFooter hasDivider>Actions</XDSLayoutFooter>}+ />+</XDSCard>`,+ },+ {+ label: 'Simple content',+ code: `<XDSCard>+ <p>Card content with default padding</p>+</XDSCard>`,+ },+ {+ label: 'Collapsible card',+ code: `<XDSCard>+ <XDSCollapsible trigger="Details">+ <p>This content can be collapsed</p>+ </XDSCollapsible>+</XDSCard>`,+ },+ {+ label: 'Accordion of cards',+ code: `<XDSCollapsibleGroup type="single" defaultValue="general">+ <XDSVStack gap="space2">+ <XDSCard>+ <XDSCollapsible trigger="General" value="general">+ <GeneralSettings />+ </XDSCollapsible>+ </XDSCard>+ <XDSCard>+ <XDSCollapsible trigger="Advanced" value="advanced">+ <AdvancedSettings />+ </XDSCollapsible>+ </XDSCard>+ </XDSVStack>+</XDSCollapsibleGroup>`,+ },+ ],+ theming: {+ componentKey: 'card',+ surfaces: [+ {name: 'container', description: 'Outer card wrapper element'},+ {name: 'content', description: 'Inner content area with padding'},+ ],+ },+};diff --git a/packages/core/src/Card/README.md b/packages/core/src/Card/README.mddeleted file mode 100644index 1dae5871e1..0000000000--- a/packages/core/src/Card/README.md+++ /dev/null@@ -1,88 +0,0 @@-# Card--Card container component with elevation and themed styling.--<!-- SYNC: When files in this directory change, update this document. -->--## Overview--XDSCard is a top-level container for elevated content. It provides card-specific appearance (background, shadow, border-radius) and sets CSS variables for child layout components.--## Import--```tsx-import {XDSCard} from '@xds/core/Card';-```--## Usage--```tsx-// Basic card with layout-<XDSCard width={400} height={300}>- <XDSLayout- header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}- content={<XDSLayoutContent>Content</XDSLayoutContent>}- footer={<XDSLayoutFooter hasDivider>Actions</XDSLayoutFooter>}- />-</XDSCard>--// Simple content-<XDSCard>- <p>Card content with default padding</p>-</XDSCard>--// Collapsible card — compose XDSCollapsible inside-<XDSCard>- <XDSCollapsible trigger="Details">- <p>This content can be collapsed</p>- </XDSCollapsible>-</XDSCard>--// Accordion of cards-<XDSCollapsibleGroup type="single" defaultValue="general">- <XDSVStack gap="space2">- <XDSCard>- <XDSCollapsible trigger="General" value="general">- <GeneralSettings />- </XDSCollapsible>- </XDSCard>- <XDSCard>- <XDSCollapsible trigger="Advanced" value="advanced">- <AdvancedSettings />- </XDSCollapsible>- </XDSCard>- </XDSVStack>-</XDSCollapsibleGroup>-```--## Props--| Prop | Type | Default | Description |-| ------------- | ----------- | ------- | ------------------------------------------------- |-| `width` | `SizeValue` | — | Width (number = pixels, string = as-is) |-| `height` | `SizeValue` | — | Height (number = pixels, string = as-is) |-| `maxWidth` | `SizeValue` | — | Maximum width |-| `minHeight` | `SizeValue` | — | Minimum height |-| `children` | `ReactNode` | — | Content to render inside the card |-| `isFullBleed` | `boolean` | `false` | Removes internal padding for edge-to-edge content |--## Theming--```tsx-declare module '@xds/core' {- interface ComponentStyles {- card?: {- container?: StyleXStyles;- content?: StyleXStyles;- };- }-}-```--## Files--| File | Role | Purpose |-| ------------- | --------- | ----------------------------- |-| `index.ts` | Entry | Exports component and types |-| `XDSCard.tsx` | Component | Card container implementation |-| `README.md` | Docs | This documentation |diff --git a/packages/core/src/Card/XDSCard.tsx b/packages/core/src/Card/XDSCard.tsxindex ee8d506239..44bdd649ae 100644--- a/packages/core/src/Card/XDSCard.tsx+++ b/packages/core/src/Card/XDSCard.tsx@@ -5,7 +5,7 @@* @position Core card container component** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Card/README.md (props table, features)+ * - /packages/core/src/Card/Card.doc.mjs (props table, features)* - /packages/core/src/Card/index.ts (exports if types change)* - /apps/storybook/stories/Card.stories.tsx (storybook stories)*/diff --git a/packages/core/src/Card/index.ts b/packages/core/src/Card/index.tsindex af25b12d5e..ae2ecec091 100644--- a/packages/core/src/Card/index.ts+++ b/packages/core/src/Card/index.ts@@ -4,7 +4,7 @@* @output Exports XDSCard component and types* @position Entry point for @xds/core/Card module*- * SYNC: When modified, update /packages/core/src/Card/README.md+ * SYNC: When modified, update /packages/core/src/Card/Card.doc.mjs*/export {XDSCard} from './XDSCard';diff --git a/packages/core/src/Center/Center.doc.mjs b/packages/core/src/Center/Center.doc.mjsnew file mode 100644index 0000000000..9dfd0581cc--- /dev/null+++ b/packages/core/src/Center/Center.doc.mjs@@ -0,0 +1,69 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Center',+ description: 'Centers children horizontally and/or vertically using flexbox.',+ features: [+ 'Supports centering on both axes, horizontal only, or vertical only',+ 'Inline-flex mode for centering inline content such as text and icons',+ 'Accepts explicit width and height to size the container',+ ],+ examples: [+ {+ label: 'Center both axes (default)',+ code: `<XDSCenter width={300} height={200}>+ <Content />+</XDSCenter>`,+ },+ {+ label: 'Center horizontally only',+ code: `<XDSCenter axis="horizontal">+ <Logo />+</XDSCenter>`,+ },+ {+ label: 'Inline centering for icons',+ code: `<XDSCenter isInline>+ <XDSIcon icon={StarIcon} />+</XDSCenter>`,+ },+ ],+ props: [+ {+ name: 'axis',+ type: "'both' | 'horizontal' | 'vertical'",+ description: 'Which direction(s) to center.',+ default: "'both'",+ },+ {+ name: 'width',+ type: 'number | string',+ description: 'Container width (px or CSS value).',+ },+ {+ name: 'height',+ type: 'number | string',+ description: 'Container height (px or CSS value).',+ },+ {+ name: 'isInline',+ type: 'boolean',+ description: 'Use inline-flex (useful for text/icons).',+ default: 'false',+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Content to center.',+ },+ ],+ theming: {+ componentKey: 'center',+ surfaces: [+ {+ name: 'root',+ description: 'Root container styles',+ },+ ],+ },+};diff --git a/packages/core/src/Center/README.md b/packages/core/src/Center/README.mddeleted file mode 100644index 3bf10a969f..0000000000--- a/packages/core/src/Center/README.md+++ /dev/null@@ -1,61 +0,0 @@-# XDSCenter--Centers children horizontally and/or vertically using flexbox.--## Import--```tsx-import {XDSCenter} from '@xds/core/Center';-```--## Usage--```tsx-// Center both axes (default)-<XDSCenter width={300} height={200}>- <Content />-</XDSCenter>--// Center horizontally only-<XDSCenter axis="horizontal">- <Logo />-</XDSCenter>--// Inline centering for icons-<XDSCenter isInline>- <XDSIcon icon={StarIcon} />-</XDSCenter>-```--## Theming--Themes can override `Center` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- center: {- root: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------- | --------------------- |-| `root` | Root container styles |--## Props--| Prop | Type | Default | Description |-| ---------- | -------------------------------------------- | -------- | -------------------------------------------------- |-| `axis` | `'both' \| 'horizontal' \| 'vertical'` | `'both'` | Which direction(s) to center |-| `width` | `number \| string` | — | Container width (px or CSS value) |-| `height` | `number \| string` | — | Container height (px or CSS value) |-| `isInline` | `boolean` | `false` | Use inline-flex (useful for text/icons) |-| `children` | `ReactNode` | — | Content to center |-| `xstyle` | `StyleXStyles` | — | StyleX overrides |diff --git a/packages/core/src/Center/XDSCenter.tsx b/packages/core/src/Center/XDSCenter.tsxindex db55d72a4e..77c00ff4bb 100644--- a/packages/core/src/Center/XDSCenter.tsx+++ b/packages/core/src/Center/XDSCenter.tsx@@ -5,7 +5,7 @@* @position Center component for centering children horizontally/vertically** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Center/README.md+ * - /packages/core/src/Center/Center.doc.mjs* - /packages/core/src/Center/XDSCenter.test.tsx* - /apps/storybook/stories/Center.stories.tsx*/diff --git a/packages/core/src/Center/index.ts b/packages/core/src/Center/index.tsindex 64481b735a..0a9f6b9a85 100644--- a/packages/core/src/Center/index.ts+++ b/packages/core/src/Center/index.ts@@ -4,7 +4,7 @@* @output Exports XDSCenter and types for @xds/core/Center* @position Entry point for Center component*- * SYNC: When modified, update /packages/core/src/Center/README.md+ * SYNC: When modified, update /packages/core/src/Center/Center.doc.mjs*/export {XDSCenter} from './XDSCenter';diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjsnew file mode 100644index 0000000000..737c8c85cc--- /dev/null+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs@@ -0,0 +1,110 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'CheckboxInput',+ description: 'A checkbox input component for toggling boolean values.',+ features: [+ 'Accessible — always includes a label (can be visually hidden)',+ 'Indeterminate state — supports indeterminate state for "select all" patterns',+ 'Descriptions — optional description text below the label',+ 'Custom styling — uses StyleX with XDS design tokens',+ 'Disabled state — full support for disabled state styling',+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description:+ 'Label text for the checkbox (always rendered for accessibility).',+ required: true,+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: 'Whether to visually hide the label.',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Description text displayed below the label.',+ },+ {+ name: 'value',+ type: "boolean | 'indeterminate'",+ description:+ 'Whether the checkbox is checked, unchecked, or indeterminate.',+ required: true,+ },+ {+ name: 'onChange',+ type: '(checked: boolean, e: ChangeEvent) => void',+ description: 'Callback fired when the checkbox state changes.',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Whether the checkbox is disabled.',+ default: 'false',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSCheckboxInput+ label="Accept terms and conditions"+ value={accepted}+ onChange={setAccepted}+/>`,+ },+ {+ label: 'With description',+ code: `<XDSCheckboxInput+ label="Subscribe to newsletter"+ description="Receive weekly updates about new features"+ value={subscribed}+ onChange={setSubscribed}+/>`,+ },+ {+ label: 'Indeterminate state',+ code: `<XDSCheckboxInput+ label="Select all items"+ value="indeterminate"+ onChange={setSelectAll}+/>`,+ },+ {+ label: 'Hidden label',+ code: `<XDSCheckboxInput+ label="Select row"+ isLabelHidden+ value={selected}+ onChange={setSelected}+/>`,+ },+ {+ label: 'Disabled',+ code: `<XDSCheckboxInput+ label="Premium feature"+ description="Upgrade to enable this option"+ value={false}+ onChange={() => {}}+ isDisabled+/>`,+ },+ ],+ theming: {+ componentKey: 'checkboxInput',+ surfaces: [+ {name: 'root', description: 'Root container styles'},+ {name: 'checkbox', description: 'Visual checkbox element styles'},+ ],+ },+ notes: [+ 'Uses a hidden native <input type="checkbox"> for accessibility with a custom visual checkbox overlay.',+ 'The visual checkbox responds to hover, focus, and checked states via sibling selectors in CSS.',+ 'Label is clickable and properly associated with the input via htmlFor/id.',+ 'Focus outline uses the standard XDS focus outline token.',+ ],+};diff --git a/packages/core/src/CheckboxInput/README.md b/packages/core/src/CheckboxInput/README.mddeleted file mode 100644index b590ed4f53..0000000000--- a/packages/core/src/CheckboxInput/README.md+++ /dev/null@@ -1,108 +0,0 @@-# CheckboxInput--A checkbox input component for toggling boolean values.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Accessible**: Always includes a label (can be visually hidden)-- **Indeterminate state**: Supports indeterminate state for "select all" patterns-- **Descriptions**: Optional description text below the label-- **Custom styling**: Uses StyleX with XDS design tokens-- **Disabled state**: Full support for disabled state styling--## Usage--```tsx-import { XDSCheckboxInput } from '@xds/core/CheckboxInput';--// Basic usage-<XDSCheckboxInput- label="Accept terms and conditions"- value={accepted}- onChange={setAccepted}-/>--// With description-<XDSCheckboxInput- label="Subscribe to newsletter"- description="Receive weekly updates about new features"- value={subscribed}- onChange={setSubscribed}-/>--// Indeterminate state (e.g., for "select all" when some items are selected)-<XDSCheckboxInput- label="Select all items"- value="indeterminate"- onChange={setSelectAll}-/>--// Hidden label (still accessible)-<XDSCheckboxInput- label="Select row"- isLabelHidden- value={selected}- onChange={setSelected}-/>--// Disabled-<XDSCheckboxInput- label="Premium feature"- description="Upgrade to enable this option"- value={false}- onChange={() => {}}- isDisabled-/>-```--## Props--| Prop | Type | Default | Description |-| --------------- | -------------------------------------------- | ------- | --------------------------------------------------------------- |-| `label` | `string` | — | Label text for the checkbox (always rendered for accessibility) |-| `isLabelHidden` | `boolean` | `false` | Whether to visually hide the label |-| `description` | `string` | — | Description text displayed below the label |-| `value` | `boolean \| 'indeterminate'` | — | Whether the checkbox is checked, unchecked, or indeterminate |-| `onChange` | `(checked: boolean, e: ChangeEvent) => void` | — | Callback fired when the checkbox state changes |-| `isDisabled` | `boolean` | `false` | Whether the checkbox is disabled |--## Theming--Themes can override `CheckboxInput` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- checkboxInput: {- root: myStyles,- checkbox: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ---------- | ------------------------------ |-| `root` | Root container styles |-| `checkbox` | Visual checkbox element styles |--## Files--| File | Role | Purpose |-| --------------------------- | ----- | --------------------------- |-| `index.ts` | Entry | Exports component and types |-| `XDSCheckboxInput.tsx` | Core | Component implementation |-| `XDSCheckboxInput.test.tsx` | Test | Unit tests |--## Implementation Notes--- Uses a hidden native `<input type="checkbox">` for accessibility with a custom visual checkbox overlay-- The visual checkbox responds to hover, focus, and checked states via sibling selectors in CSS-- Label is clickable and properly associated with the input via `htmlFor`/`id`-- Focus outline uses the standard XDS focus outline tokendiff --git a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsxindex 12e0712d28..f1cdc40bb7 100644--- a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx+++ b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSCheckboxInput.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/CheckboxInput/README.md (props table, features, implementation notes)+ * - /packages/core/src/CheckboxInput/CheckboxInput.doc.mjs (props table, features, implementation notes)* - /packages/core/src/CheckboxInput/XDSCheckboxInput.test.tsx (tests for new/changed behavior)* - /packages/core/src/CheckboxInput/index.ts (exports if types change)* - /apps/storybook/stories/CheckboxInput.stories.tsx (storybook stories)diff --git a/packages/core/src/CheckboxInput/index.ts b/packages/core/src/CheckboxInput/index.tsindex e38b33de48..88840283f2 100644--- a/packages/core/src/CheckboxInput/index.ts+++ b/packages/core/src/CheckboxInput/index.ts@@ -4,7 +4,7 @@* @output Exports XDSCheckboxInput, XDSCheckboxInputProps, XDSCheckboxInputSize* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/CheckboxInput/README.md+ * SYNC: When modified, update this header and /packages/core/src/CheckboxInput/CheckboxInput.doc.mjs*/export {XDSCheckboxInput} from './XDSCheckboxInput';diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjsnew file mode 100644index 0000000000..1f4d016be5--- /dev/null+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs@@ -0,0 +1,216 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Collapsible',+ description: 'Collapsible content primitive and group coordination.',+ features: [+ 'XDSCollapsible makes any content collapsible — a trigger toggles visibility of the content area',+ 'Handles state management, accessibility (aria-expanded, keyboard activation), and a chevron indicator',+ 'Supports uncontrolled (defaultIsOpen), controlled (isOpen / onOpenChange), and group-coordinated modes',+ 'XDSCollapsibleGroup coordinates multiple XDSCollapsible instances so only one (single mode) or multiple (multiple mode) can be open at a time',+ 'XDSCollapsibleGroup renders no wrapper DOM element',+ 'When inside a group, XDSCollapsible defers open/close state to the group context via the value prop',+ ],+ keyboard:+ 'Enter or Space activates the trigger button to toggle open/close state.',+ accessibility: [+ 'Trigger renders as a <button> with aria-expanded reflecting the current open state',+ 'A chevron indicator provides a visual affordance for the expanded/collapsed state',+ ],+ notes: [+ 'XDSCollapsible manages its own open/close state by default (uncontrolled)',+ 'When nested inside an XDSCollapsibleGroup with a matching value prop, it defers to the group context',+ 'XDSCollapsibleGroup provides context with isOpen(value) and toggle(value) methods',+ 'The group renders no wrapper DOM — layout is the responsibility of the consumer (e.g. XDSVStack)',+ ],+ examples: [+ {+ label: 'Standalone collapsible',+ code: `// Inside a card+<XDSCard>+ <XDSCollapsible trigger="Details">+ <p>This content can be collapsed</p>+ </XDSCollapsible>+</XDSCard>++// Starts collapsed+<XDSCard>+ <XDSCollapsible trigger="Advanced" defaultIsOpen={false}>+ <p>Hidden by default</p>+ </XDSCollapsible>+</XDSCard>++// Controlled+<XDSCard>+ <XDSCollapsible trigger="Settings" isOpen={open} onOpenChange={setOpen}>+ <p>Controlled externally</p>+ </XDSCollapsible>+</XDSCard>++// Without a card — works anywhere+<XDSCollapsible trigger="Show more">+ <p>Expandable content</p>+</XDSCollapsible>`,+ },+ {+ label: 'Coordinated group — single mode (accordion)',+ code: `// Single mode — only one open at a time (FAQ, settings panels)+<XDSCollapsibleGroup type="single" defaultValue="general">+ <XDSVStack gap="space2">+ <XDSCard>+ <XDSCollapsible trigger="General Settings" value="general">+ <GeneralContent />+ </XDSCollapsible>+ </XDSCard>+ <XDSCard>+ <XDSCollapsible trigger="Advanced Settings" value="advanced">+ <AdvancedContent />+ </XDSCollapsible>+ </XDSCard>+ </XDSVStack>+</XDSCollapsibleGroup>`,+ },+ {+ label: 'Coordinated group — multiple mode',+ code: `// Multiple mode — any number open+<XDSCollapsibleGroup type="multiple" defaultValue={["s1", "s2"]}>+ <XDSVStack gap="space2">+ <XDSCard>+ <XDSCollapsible trigger="Section 1" value="s1">...</XDSCollapsible>+ </XDSCard>+ <XDSCard>+ <XDSCollapsible trigger="Section 2" value="s2">...</XDSCollapsible>+ </XDSCard>+ </XDSVStack>+</XDSCollapsibleGroup>`,+ },+ {+ label: 'With Layout (structured header)',+ code: `<XDSCard>+ <XDSCollapsible trigger="Report Details" value="report">+ <XDSLayout+ content={<XDSLayoutContent>Report body</XDSLayoutContent>}+ footer={<XDSLayoutFooter hasDivider>Actions</XDSLayoutFooter>}+ />+ </XDSCollapsible>+</XDSCard>`,+ },+ ],+ components: [+ {+ name: 'XDSCollapsible',+ description:+ 'A primitive that makes any content collapsible — a trigger button toggles visibility of the content area, managing its own state or deferring to a parent XDSCollapsibleGroup.',+ props: [+ {+ name: 'trigger',+ type: 'ReactNode',+ description: 'Content shown in the trigger area (always visible).',+ required: true,+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Content that collapses and expands.',+ },+ {+ name: 'defaultIsOpen',+ type: 'boolean',+ description: 'Default open state (uncontrolled).',+ default: 'true',+ },+ {+ name: 'isOpen',+ type: 'boolean',+ description: 'Controlled open state.',+ },+ {+ name: 'onOpenChange',+ type: '(isOpen: boolean) => void',+ description: 'Callback invoked when the open state changes.',+ },+ {+ name: 'value',+ type: 'string',+ description:+ 'Identifier used for group coordination. Required when placed inside an XDSCollapsibleGroup.',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSCollapsible trigger="Details">+ <p>This content can be collapsed</p>+</XDSCollapsible>`,+ },+ {+ label: 'Starts collapsed',+ code: `<XDSCollapsible trigger="Advanced" defaultIsOpen={false}>+ <p>Hidden by default</p>+</XDSCollapsible>`,+ },+ {+ label: 'Controlled',+ code: `<XDSCollapsible trigger="Settings" isOpen={open} onOpenChange={setOpen}>+ <p>Controlled externally</p>+</XDSCollapsible>`,+ },+ ],+ },+ {+ name: 'XDSCollapsibleGroup',+ description:+ 'Coordinates multiple XDSCollapsible instances so only one (single mode) or any number (multiple mode) can be open at a time. Renders no wrapper DOM element.',+ props: [+ {+ name: 'type',+ type: "'single' | 'multiple'",+ description: 'Whether one or many items can be open simultaneously.',+ default: "'single'",+ },+ {+ name: 'defaultValue',+ type: 'string | string[]',+ description:+ 'Default open item(s) for uncontrolled usage. Use a string for single mode and an array for multiple mode.',+ },+ {+ name: 'value',+ type: 'string | string[]',+ description: 'Controlled open item(s).',+ },+ {+ name: 'onChange',+ type: '(value: string | string[]) => void',+ description: 'Callback invoked when the set of open items changes.',+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'XDSCollapsible instances to coordinate.',+ required: true,+ },+ ],+ examples: [+ {+ label: 'Single mode (accordion)',+ code: `<XDSCollapsibleGroup type="single" defaultValue="general">+ <XDSCollapsible trigger="General" value="general">+ <p>General settings</p>+ </XDSCollapsible>+ <XDSCollapsible trigger="Advanced" value="advanced">+ <p>Advanced settings</p>+ </XDSCollapsible>+</XDSCollapsibleGroup>`,+ },+ {+ label: 'Multiple mode',+ code: `<XDSCollapsibleGroup type="multiple" defaultValue={["s1", "s2"]}>+ <XDSCollapsible trigger="Section 1" value="s1">...</XDSCollapsible>+ <XDSCollapsible trigger="Section 2" value="s2">...</XDSCollapsible>+</XDSCollapsibleGroup>`,+ },+ ],+ },+ ],+};diff --git a/packages/core/src/Collapsible/README.md b/packages/core/src/Collapsible/README.mddeleted file mode 100644index 61133ba78d..0000000000--- a/packages/core/src/Collapsible/README.md+++ /dev/null@@ -1,152 +0,0 @@-# Collapsible--Collapsible content primitive and group coordination.--<!-- SYNC: When files in this directory change, update this document. -->--## Overview--XDSCollapsible is a primitive that makes any content collapsible — a trigger toggles visibility of the content area. It handles state management, accessibility (aria-expanded, keyboard activation), and a chevron indicator.--XDSCollapsibleGroup coordinates multiple XDSCollapsible instances so only one (or multiple) can be open at a time. It renders no wrapper DOM.--## Import--```tsx-import {XDSCollapsible, XDSCollapsibleGroup} from '@xds/core/Collapsible';-```--## Usage--### Standalone collapsible--```tsx-// Inside a card-<XDSCard>- <XDSCollapsible trigger="Details">- <p>This content can be collapsed</p>- </XDSCollapsible>-</XDSCard>--// Starts collapsed-<XDSCard>- <XDSCollapsible trigger="Advanced" defaultIsOpen={false}>- <p>Hidden by default</p>- </XDSCollapsible>-</XDSCard>--// Controlled-<XDSCard>- <XDSCollapsible trigger="Settings" isOpen={open} onOpenChange={setOpen}>- <p>Controlled externally</p>- </XDSCollapsible>-</XDSCard>--// Without a card — works anywhere-<XDSCollapsible trigger="Show more">- <p>Expandable content</p>-</XDSCollapsible>-```--### Coordinated group (accordion pattern)--```tsx-// Single mode — only one open at a time (FAQ, settings panels)-<XDSCollapsibleGroup type="single" defaultValue="general">- <XDSVStack gap="space2">- <XDSCard>- <XDSCollapsible trigger="General Settings" value="general">- <GeneralContent />- </XDSCollapsible>- </XDSCard>- <XDSCard>- <XDSCollapsible trigger="Advanced Settings" value="advanced">- <AdvancedContent />- </XDSCollapsible>- </XDSCard>- </XDSVStack>-</XDSCollapsibleGroup>--// Multiple mode — any number open-<XDSCollapsibleGroup type="multiple" defaultValue={["s1", "s2"]}>- <XDSVStack gap="space2">- <XDSCard>- <XDSCollapsible trigger="Section 1" value="s1">...</XDSCollapsible>- </XDSCard>- <XDSCard>- <XDSCollapsible trigger="Section 2" value="s2">...</XDSCollapsible>- </XDSCard>- </XDSVStack>-</XDSCollapsibleGroup>-```--### With Layout (structured header)--```tsx-<XDSCard>- <XDSCollapsible trigger="Report Details" value="report">- <XDSLayout- content={<XDSLayoutContent>Report body</XDSLayoutContent>}- footer={<XDSLayoutFooter hasDivider>Actions</XDSLayoutFooter>}- />- </XDSCollapsible>-</XDSCard>-```--## Props--### XDSCollapsible--```tsx-<XDSCollapsible trigger="Details">- <p>This content can be collapsed</p>-</XDSCollapsible>-```--| Prop | Type | Default | Description |-| --------------- | --------------------------- | ------- | -------------------------------------------------- |-| `trigger` | `ReactNode` | — | Content shown in the trigger area (always visible) |-| `children` | `ReactNode` | — | Content that collapses/expands |-| `defaultIsOpen` | `boolean` | `true` | Default open state (uncontrolled) |-| `isOpen` | `boolean` | — | Controlled open state |-| `onOpenChange` | `(isOpen: boolean) => void` | — | Callback when open state changes |-| `value` | `string` | — | Identifier for group coordination |--### XDSCollapsibleGroup--```tsx-<XDSCollapsibleGroup type="single" defaultValue="general">- <XDSCollapsible trigger="General" value="general">- <p>General settings</p>- </XDSCollapsible>- <XDSCollapsible trigger="Advanced" value="advanced">- <p>Advanced settings</p>- </XDSCollapsible>-</XDSCollapsibleGroup>-```--| Prop | Type | Default | Description |-| -------------- | ------------------------------------- | ---------- | -------------------------------------- |-| `type` | `"single" \| "multiple"` | `"single"` | Whether one or many items can be open |-| `defaultValue` | `string \| string[]` | — | Default open item(s) — uncontrolled |-| `value` | `string \| string[]` | — | Controlled open item(s) |-| `onChange` | `(value: string \| string[]) => void` | — | Callback when open items change |-| `children` | `ReactNode` | — | XDSCollapsible instances to coordinate |--## How It Works--1. XDSCollapsible manages its own open/close state by default-2. When inside an XDSCollapsibleGroup with a `value` prop, it defers to the group-3. XDSCollapsibleGroup provides context with `isOpen(value)` and `toggle(value)` methods-4. The trigger renders as a button with `aria-expanded` and a chevron indicator--## Files--| File | Role | Purpose |-| -------------------------------- | --------- | ------------------------------- |-| `index.ts` | Entry | Exports components, hook, types |-| `XDSCollapsibleGroup.tsx` | Component | Collapsible group provider |-| `XDSCollapsibleGroupContext.tsx` | Context | React context definition |-| `useXDSCollapsible.ts` | Hook | Collapsible state management |-| `XDSCollapsibleGroup.test.tsx` | Tests | Unit tests |-| `README.md` | Docs | This documentation |diff --git a/packages/core/src/Collapsible/XDSCollapsible.tsx b/packages/core/src/Collapsible/XDSCollapsible.tsxindex 04ee7a6ea6..3ba15d07cb 100644--- a/packages/core/src/Collapsible/XDSCollapsible.tsx+++ b/packages/core/src/Collapsible/XDSCollapsible.tsx@@ -12,7 +12,7 @@** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Collapsible/index.ts (exports)- * - /packages/core/src/Collapsible/README.md+ * - /packages/core/src/Collapsible/Collapsible.doc.mjs* - /apps/storybook/stories/Collapsible.stories.tsx*/diff --git a/packages/core/src/Collapsible/XDSCollapsibleGroup.tsx b/packages/core/src/Collapsible/XDSCollapsibleGroup.tsxindex 8765412320..8185c6c673 100644--- a/packages/core/src/Collapsible/XDSCollapsibleGroup.tsx+++ b/packages/core/src/Collapsible/XDSCollapsibleGroup.tsx@@ -13,7 +13,7 @@** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Collapsible/XDSCollapsibleGroupContext.tsx (context type)- * - /packages/core/src/Collapsible/README.md+ * - /packages/core/src/Collapsible/Collapsible.doc.mjs* - /packages/core/src/Collapsible/index.ts (exports)* - /apps/storybook/stories/Collapsible.stories.tsx*/diff --git a/packages/core/src/Collapsible/XDSCollapsibleGroupContext.tsx b/packages/core/src/Collapsible/XDSCollapsibleGroupContext.tsxindex de70c4668a..30ba9f106a 100644--- a/packages/core/src/Collapsible/XDSCollapsibleGroupContext.tsx+++ b/packages/core/src/Collapsible/XDSCollapsibleGroupContext.tsx@@ -6,7 +6,7 @@** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Collapsible/XDSCollapsibleGroup.tsx (provider)- * - /packages/core/src/Collapsible/README.md+ * - /packages/core/src/Collapsible/Collapsible.doc.mjs*/'use client';diff --git a/packages/core/src/Collapsible/index.ts b/packages/core/src/Collapsible/index.tsindex e3dad11eaf..e20a08bd69 100644--- a/packages/core/src/Collapsible/index.ts+++ b/packages/core/src/Collapsible/index.ts@@ -4,7 +4,7 @@* @output Exports components, hook, and types* @position Entry point for @xds/core/Collapsible module*- * SYNC: When modified, update /packages/core/src/Collapsible/README.md+ * SYNC: When modified, update /packages/core/src/Collapsible/Collapsible.doc.mjs*/export {XDSCollapsible} from './XDSCollapsible';diff --git a/packages/core/src/Collapsible/useXDSCollapsible.ts b/packages/core/src/Collapsible/useXDSCollapsible.tsindex c063870b98..2277d222c9 100644--- a/packages/core/src/Collapsible/useXDSCollapsible.ts+++ b/packages/core/src/Collapsible/useXDSCollapsible.ts@@ -12,7 +12,7 @@** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Collapsible/index.ts (exports)- * - /packages/core/src/Collapsible/README.md+ * - /packages/core/src/Collapsible/Collapsible.doc.mjs** NOTE: Public hooks use the `useXDS` prefix per XDS naming conventions.*/diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjsnew file mode 100644index 0000000000..b68778c018--- /dev/null+++ b/packages/core/src/DateInput/DateInput.doc.mjs@@ -0,0 +1,168 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'DateInput',+ description:+ 'XDSDateInput component combining a text input with a calendar popover for date selection.',+ features: [+ 'Text Input — manual date entry with flexible parsing (supports various formats)',+ 'Calendar Popover — click icon or use keyboard to open calendar picker',+ 'Date Constraints — min, max, and custom dateConstraints functions',+ 'Status Indicators — error, warning, and success states with messages',+ 'Accessibility — full keyboard navigation, focus trapping, screen reader support',+ 'Field Integration — built on XDSField for consistent label, description, and validation states',+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSDateInput+ label="Event date"+ value={date}+ onChange={setDate}+/>`,+ },+ {+ label: 'With constraints',+ code: `<XDSDateInput+ label="Departure date"+ value={date}+ onChange={setDate}+ min="2026-01-01"+ max="2026-12-31"+ placeholder="Pick a date"+/>`,+ },+ {+ label: 'Two-month calendar',+ code: `<XDSDateInput+ label="Check-in date"+ value={date}+ onChange={setDate}+ numberOfMonths={2}+/>`,+ },+ {+ label: 'With description and required',+ code: `<XDSDateInput+ label="Due date"+ description="When should this task be completed?"+ isRequired+ value={date}+ onChange={setDate}+/>`,+ },+ {+ label: 'With error status',+ code: `<XDSDateInput+ label="Event date"+ value={date}+ onChange={setDate}+ status={{+ type: 'error',+ message: 'This date is not available',+ }}+/>`,+ },+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Label text.',+ required: true,+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: 'Visually hide the label.',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Helper text displayed below the label.',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description: 'Show an "(optional)" indicator next to the label.',+ default: 'false',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description: 'Mark the field as required.',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Disable the input and calendar.',+ default: 'false',+ },+ {+ name: 'value',+ type: 'ISODateString',+ description: 'Selected date in YYYY-MM-DD format.',+ },+ {+ name: 'onChange',+ type: '(value: ISODateString | undefined) => void',+ description: 'Callback invoked when the selected date changes.',+ },+ {+ name: 'min',+ type: 'ISODateString',+ description: 'Minimum selectable date (YYYY-MM-DD).',+ },+ {+ name: 'max',+ type: 'ISODateString',+ description: 'Maximum selectable date (YYYY-MM-DD).',+ },+ {+ name: 'dateConstraints',+ type: 'Array<(date: Date) => boolean>',+ description:+ 'Array of custom constraint functions that disable specific dates.',+ },+ {+ name: 'placeholder',+ type: 'string',+ description: 'Placeholder text shown in the text input.',+ default: "'Select a date'",+ },+ {+ name: 'size',+ type: "'sm' | 'md' | 'lg'",+ description: 'Size of the input control.',+ default: "'md'",+ },+ {+ name: 'status',+ type: 'XDSInputStatus',+ description:+ 'Status indicator object for error, warning, or success states with a message.',+ },+ {+ name: 'numberOfMonths',+ type: '1 | 2',+ description:+ 'Number of months displayed simultaneously in the calendar popover.',+ default: '1',+ },+ ],+ keyboard:+ 'Tab moves between input and calendar icon button; Enter/Space on icon opens the calendar and moves focus into it; Escape closes the calendar popover; Arrow keys navigate between days; Page Up/Down navigate between months.',+ notes: [+ 'The text input accepts multiple date formats: ISO (2026-01-28), US (01/28/2026, 1/28/2026), and written (Jan 28, 2026 / January 28 2026).',+ 'Invalid input reverts to the previous valid value on blur.',+ ],+ theming: {+ componentKey: 'dateInput',+ surfaces: [+ {name: 'wrapper', description: 'Input wrapper element styles'},+ {name: 'input', description: 'Text input element styles'},+ ],+ },+};diff --git a/packages/core/src/DateInput/README.md b/packages/core/src/DateInput/README.mddeleted file mode 100644index 9d78d2198c..0000000000--- a/packages/core/src/DateInput/README.md+++ /dev/null@@ -1,134 +0,0 @@-# DateInput--XDSDateInput component combining a text input with a calendar popover for date selection.--## Features--- **Text Input**: Manual date entry with flexible parsing (supports various formats)-- **Calendar Popover**: Click icon or use keyboard to open calendar picker-- **Date Constraints**: `min`, `max`, and custom `dateConstraints` functions-- **Status Indicators**: Error, warning, and success states with messages-- **Accessibility**: Full keyboard navigation, focus trapping, screen reader support-- **Field Integration**: Built on XDSField for consistent label, description, and validation states--## Usage--```tsx-import { XDSDateInput } from '@xds/core/DateInput';--// Basic usage-<XDSDateInput- label="Event date"- value={date}- onChange={setDate}-/>--// With constraints-<XDSDateInput- label="Departure date"- value={date}- onChange={setDate}- min="2026-01-01"- max="2026-12-31"- placeholder="Pick a date"-/>--// Two-month calendar-<XDSDateInput- label="Check-in date"- value={date}- onChange={setDate}- numberOfMonths={2}-/>--// With description and required-<XDSDateInput- label="Due date"- description="When should this task be completed?"- isRequired- value={date}- onChange={setDate}-/>--// With error status-<XDSDateInput- label="Event date"- value={date}- onChange={setDate}- status={{- type: 'error',- message: 'This date is not available',- }}-/>-```--## Props--| Prop | Type | Default | Description |-| ----------------- | --------------------------------------------- | ----------------- | ---------------------------------------- |-| `label` | `string` | — | Label text (required) |-| `isLabelHidden` | `boolean` | `false` | Visually hide label |-| `description` | `string` | — | Helper text below label |-| `isOptional` | `boolean` | `false` | Show "(optional)" indicator |-| `isRequired` | `boolean` | `false` | Mark field as required |-| `isDisabled` | `boolean` | `false` | Disable input and calendar |-| `value` | `ISODateString` | — | Selected date (YYYY-MM-DD) |-| `onChange` | `(value: ISODateString \| undefined) => void` | — | Selection callback |-| `min` | `ISODateString` | — | Minimum selectable date |-| `max` | `ISODateString` | — | Maximum selectable date |-| `dateConstraints` | `Array<(date: Date) => boolean>` | — | Custom constraint functions |-| `placeholder` | `string` | `"Select a date"` | Input placeholder text |-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Input size |-| `status` | `XDSInputStatus` | — | Status indicator (error/warning/success) |-| `numberOfMonths` | `1 \| 2` | `1` | Months shown in calendar popover |--## Keyboard Navigation--- **Tab**: Move between input and calendar icon button-- **Enter/Space** on icon: Open calendar and move focus into it-- **Escape**: Close calendar popover-- **Arrow keys** in calendar: Navigate between days-- **Page Up/Down** in calendar: Navigate between months--## Date Input Parsing--The text input accepts various date formats:--- ISO format: `2026-01-28`-- US format: `01/28/2026`, `1/28/2026`-- Written: `Jan 28, 2026`, `January 28 2026`--Invalid input reverts to the previous valid value on blur.--## Theming--Themes can override `DateInput` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- dateInput: {- wrapper: myStyles,- input: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| --------- | ------------------------- |-| `wrapper` | Input wrapper styles |-| `input` | Text input element styles |--## Files--| File | Role | Purpose |-| --------------------- | ------ | ------------------------ |-| XDSDateInput.tsx | Core | Component implementation |-| XDSDateInput.test.tsx | Test | Unit tests |-| index.ts | Export | Public API exports |-| README.md | Docs | This documentation |diff --git a/packages/core/src/DateInput/XDSDateInput.tsx b/packages/core/src/DateInput/XDSDateInput.tsxindex ee037c9d6f..ddee3d25db 100644--- a/packages/core/src/DateInput/XDSDateInput.tsx+++ b/packages/core/src/DateInput/XDSDateInput.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSDateInput.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/DateInput/README.md (props table, features, implementation notes)+ * - /packages/core/src/DateInput/DateInput.doc.mjs (props table, features, implementation notes)* - /packages/core/src/DateInput/XDSDateInput.test.tsx (tests for new/changed behavior)* - /packages/core/src/DateInput/index.ts (exports if types change)* - /apps/storybook/stories/DateInput.stories.tsx (storybook stories)diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjsnew file mode 100644index 0000000000..5b2eba48cb--- /dev/null+++ b/packages/core/src/Dialog/Dialog.doc.mjs@@ -0,0 +1,258 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Dialog',+ description:+ 'Modal dialog using the native <dialog> element with automatic focus trapping, backdrop, and purpose-based dismissal control.',+ features: [+ "Native <dialog>: Uses the browser's built-in modal behavior via showModal()",+ 'Automatic focus trap: Focus is trapped within the dialog when open (browser-native)',+ 'Backdrop: Native ::backdrop pseudo-element with blur effect',+ 'Variants: standard (configurable dimensions) and fullscreen (full viewport)',+ 'Purpose-based dismissal: required, form, and info control Escape key and backdrop-click behavior',+ 'Custom positioning: Static position support via the position prop',+ 'Accessible: Proper ARIA attributes and keyboard navigation',+ ],+ examples: [+ {+ label: 'Basic dialog with Layout',+ code: `import {XDSDialog} from '@xds/core/Dialog';+import {+ XDSLayout,+ XDSLayoutHeader,+ XDSLayoutContent,+ XDSLayoutFooter,+} from '@xds/core/Layout';+import {XDSButton} from '@xds/core/Button';+import {useState} from 'react';++function Example() {+ const [isOpen, setIsOpen] = useState(false);++ return (+ <>+ <XDSButton label="Open Dialog" onClick={() => setIsOpen(true)} />++ <XDSDialog isOpen={isOpen} onOpenChange={open => setIsOpen(open)}>+ <XDSLayout+ header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}+ content={<XDSLayoutContent>Content goes here</XDSLayoutContent>}+ footer={+ <XDSLayoutFooter hasDivider>+ <XDSButton+ label="Cancel"+ variant="secondary"+ onClick={() => setIsOpen(false)}+ />+ <XDSButton+ label="Confirm"+ variant="primary"+ onClick={() => setIsOpen(false)}+ />+ </XDSLayoutFooter>+ }+ />+ </XDSDialog>+ </>+ );+}`,+ },+ {+ label: 'Static position',+ code: `<XDSDialog+ isOpen={isOpen}+ onOpenChange={open => setIsOpen(open)}+ position={{top: 100, right: 20}}>+ {/* content */}+</XDSDialog>`,+ },+ {+ label: 'Fullscreen variant',+ code: `<XDSDialog+ isOpen={isOpen}+ onOpenChange={open => setIsOpen(open)}+ variant="fullscreen">+ <XDSLayout+ header={<XDSLayoutHeader hasDivider>Full-screen title</XDSLayoutHeader>}+ content={<XDSLayoutContent>Content goes here</XDSLayoutContent>}+ footer={+ <XDSLayoutFooter hasDivider>+ <XDSButton label="Close" onClick={() => setIsOpen(false)} />+ </XDSLayoutFooter>+ }+ />+</XDSDialog>`,+ },+ {+ label: 'Required purpose (non-dismissible)',+ code: `<XDSDialog+ isOpen={isOpen}+ onOpenChange={open => setIsOpen(open)}+ purpose="required">+ {/* user must take an explicit action to close */}+</XDSDialog>`,+ },+ {+ label: 'XDSDialogHeader with close button',+ code: `<XDSDialogHeader+ title="Confirm Action"+ subtitle="This cannot be undone"+ onOpenChange={open => setIsOpen(open)}+/>`,+ },+ ],+ theming: {+ componentKey: 'dialog',+ surfaces: [+ {name: 'root', description: 'Dialog element styles'},+ {name: 'backdrop', description: 'Backdrop overlay styles'},+ ],+ },+ keyboard:+ 'Escape closes the dialog (unless purpose="required"); focus is trapped inside the dialog while open.',+ accessibility: [+ 'Uses the native <dialog> element with showModal() for correct ARIA modal semantics.',+ 'Focus is automatically trapped by the browser when using showModal().',+ 'XDSDialogHeader title receives focus when the dialog opens.',+ ],+ notes: [+ 'Height is unset (grows with content) and constrained by the maxHeight prop.',+ 'When variant="fullscreen", the width, maxHeight, and position props are ignored.',+ 'For form purpose, backdrop click is only allowed before the user has interacted with the dialog.',+ 'Purpose=required disables both Escape key and backdrop click; purpose=form disables backdrop click after interaction; purpose=info (default) allows both.',+ 'XDSDialog is designed to be used with XDSLayout as its child.',+ ],+ components: [+ {+ name: 'XDSDialog',+ description: 'Modal dialog using the native <dialog> element.',+ props: [+ {+ name: 'isOpen',+ type: 'boolean',+ description: 'Whether the dialog is open (required).',+ required: true,+ },+ {+ name: 'onOpenChange',+ type: '(isOpen: boolean) => unknown',+ description: 'Callback when dialog visibility changes (required).',+ required: true,+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Dialog content.',+ required: true,+ },+ {+ name: 'width',+ type: 'number | string',+ description: 'Width of the dialog in pixels or any CSS value.',+ default: '400',+ },+ {+ name: 'maxHeight',+ type: 'number | string',+ description: 'Maximum height of the dialog.',+ default: "'75vh'",+ },+ {+ name: 'position',+ type: 'XDSDialogPosition',+ description:+ 'Static position for the dialog; centered by default when omitted.',+ },+ {+ name: 'variant',+ type: "'standard' | 'fullscreen'",+ description:+ 'Dialog variant — fullscreen expands to fill the entire viewport.',+ default: "'standard'",+ },+ {+ name: 'purpose',+ type: "'required' | 'form' | 'info'",+ description:+ 'Controls dismissal behavior: required disables Escape and backdrop click; form disables backdrop click after interaction; info allows both.',+ default: "'info'",+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSDialog isOpen={isOpen} onOpenChange={open => setIsOpen(open)}>+ <XDSLayout+ header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}+ content={<XDSLayoutContent>Content goes here</XDSLayoutContent>}+ footer={+ <XDSLayoutFooter hasDivider>+ <XDSButton label="Confirm" variant="primary" onClick={() => setIsOpen(false)} />+ </XDSLayoutFooter>+ }+ />+</XDSDialog>`,+ },+ ],+ },+ {+ name: 'XDSDialogHeader',+ description:+ 'Header for dialogs with a title, optional subtitle, close button, and start/end content slots.',+ props: [+ {+ name: 'title',+ type: 'string',+ description: 'Dialog title (receives focus on open).',+ },+ {+ name: 'subtitle',+ type: 'string',+ description: 'Subtitle below the title.',+ },+ {+ name: 'onOpenChange',+ type: '(isOpen: boolean) => unknown',+ description:+ 'Close button callback (no button if omitted).',+ },+ {+ name: 'startContent',+ type: 'ReactNode',+ description:+ 'Content before the title (e.g., a back button).',+ },+ {+ name: 'endContent',+ type: 'ReactNode',+ description:+ 'Content after the title, before close button.',+ },+ {+ name: 'hasDivider',+ type: 'boolean',+ description: 'Adds border at the bottom edge.',+ default: 'true',+ },+ ],+ examples: [+ {+ label: 'With title, subtitle, and close button',+ code: `<XDSDialogHeader+ title="Confirm Action"+ subtitle="This cannot be undone"+ onOpenChange={open => setIsOpen(open)}+/>`,+ },+ {+ label: 'With start content (back button)',+ code: `<XDSDialogHeader+ title="Step 2 of 3"+ startContent={<XDSButton label="Back" variant="secondary" onClick={goBack} />}+ onOpenChange={open => setIsOpen(open)}+/>`,+ },+ ],+ },+ ],+};diff --git a/packages/core/src/Dialog/README.md b/packages/core/src/Dialog/README.mddeleted file mode 100644index 339c4b2e44..0000000000--- a/packages/core/src/Dialog/README.md+++ /dev/null@@ -1,183 +0,0 @@-# Dialog--XDSDialog component using the native `<dialog>` element for modal dialogs.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Native `<dialog>`**: Uses browser's built-in modal behavior-- **Automatic focus trap**: Focus is trapped within the dialog when open-- **Backdrop**: Native `::backdrop` pseudo-element with blur effect-- **Variants**: `standard` (configurable dimensions), `fullscreen` (full viewport)-- **Purpose-based dismissal**: `required`, `form`, `info` control exit behavior-- **Custom positioning**: Static position support via `position` prop-- **Accessible**: Proper ARIA attributes and keyboard navigation--## Usage--XDSDialog is designed to be used with XDSLayout as its child:--```tsx-import {XDSDialog} from '@xds/core/Dialog';-import {- XDSLayout,- XDSLayoutHeader,- XDSLayoutContent,- XDSLayoutFooter,-} from '@xds/core/Layout';-import {XDSButton} from '@xds/core/Button';-import {useState} from 'react';--function Example() {- const [isOpen, setIsOpen] = useState(false);-- return (- <>- <XDSButton label="Open Dialog" onClick={() => setIsOpen(true)} />-- <XDSDialog isOpen={isOpen} onOpenChange={open => setIsOpen(open)}>- <XDSLayout- header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}- content={<XDSLayoutContent>Content goes here</XDSLayoutContent>}- footer={- <XDSLayoutFooter hasDivider>- <XDSButton- label="Cancel"- variant="secondary"- onClick={() => setIsOpen(false)}- />- <XDSButton- label="Confirm"- variant="primary"- onClick={() => setIsOpen(false)}- />- </XDSLayoutFooter>- }- />- </XDSDialog>- </>- );-}-```--## Components--### XDSDialog--Modal dialog using the native `<dialog>` element.--```tsx-<XDSDialog isOpen={isOpen} onOpenChange={open => setIsOpen(open)}>- <XDSLayout- header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}- content={<XDSLayoutContent>Content goes here</XDSLayoutContent>}- footer={- <XDSLayoutFooter hasDivider>- <XDSButton- label="Confirm"- variant="primary"- onClick={() => setIsOpen(false)}- />- </XDSLayoutFooter>- }- />-</XDSDialog>-```--| Prop | Type | Default | Description |-| -------------- | -------------------------------- | ------------ | -------------------------------------------------- |-| `isOpen` | `boolean` | — | Whether the dialog is open (required) |-| `onOpenChange` | `(isOpen: boolean) => unknown` | — | Callback when dialog visibility changes (required) |-| `width` | `number \| string` | `400` | Width of the dialog (px or CSS value) |-| `maxHeight` | `number \| string` | `'75vh'` | Maximum height of the dialog |-| `position` | `XDSDialogPosition` | — | Static position (centered by default) |-| `variant` | `'standard' \| 'fullscreen'` | `'standard'` | Dialog variant |-| `purpose` | `'required' \| 'form' \| 'info'` | `'info'` | Dismissal behavior |-| `children` | `ReactNode` | — | Dialog content (required) |--### XDSDialogHeader--Header for dialogs with title, optional subtitle, close button, and start/end content slots.--```tsx-<XDSDialogHeader- title="Confirm Action"- subtitle="This cannot be undone"- onOpenChange={open => setIsOpen(open)}-/>-```--| Prop | Type | Default | Description |-| -------------- | --------------- | ------- | -------------------------------------------- |-| `title` | `string` | — | Dialog title (receives focus on open) |-| `subtitle` | `string` | — | Subtitle below the title |-| `onOpenChange` | `() => unknown` | — | Close button callback (no button if omitted) |-| `startContent` | `ReactNode` | — | Content before the title (e.g., back button) |-| `endContent` | `ReactNode` | — | Content after the title, before close button |-| `hasDivider` | `boolean` | `true` | Adds border at the bottom edge |--## Purpose Prop--The `purpose` prop controls how users can dismiss the dialog:--| Purpose | Escape Key | Backdrop Click | Use Case |-| ---------- | ----------- | -------------- | ------------------------------------------ |-| `required` | ❌ Disabled | ❌ Disabled | Mandatory flows (security, permissions) |-| `form` | ✅ Allowed | ❌ Disabled\* | Forms where accidental dismiss = data loss |-| `info` | ✅ Allowed | ✅ Allowed | Informational content, low-cost dismissal |--\*For `form` purpose, backdrop click is only allowed before user interaction.--## Position Prop--Configure a static position instead of centering:--```tsx-<XDSDialog- isOpen={isOpen}- onOpenChange={open => setIsOpen(open)}- position={{top: 100, right: 20}}>- {/* content */}-</XDSDialog>-```--## Theming--Themes can override `Dialog` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- dialog: {- root: myStyles,- backdrop: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ---------- | ----------------------- |-| `root` | Dialog element styles |-| `backdrop` | Backdrop overlay styles |--## Files--| File | Role | Purpose |-| -------------------- | ----- | ------------------------------------- |-| `index.ts` | Entry | Exports XDSDialog component and types |-| `XDSDialog.tsx` | Core | XDSDialog component implementation |-| `XDSDialog.test.tsx` | Test | Unit tests for XDSDialog component |--## Implementation Notes--- Uses native `<dialog>` element with `showModal()` for proper modal behavior-- Height is `unset` (grows with content) and constrained by `maxHeight`-- Focus is automatically trapped by the browser when using `showModal()`-- Escape key and backdrop clicks are controlled by the `purpose` prop-- When `variant="fullscreen"`, the `width`, `maxHeight`, and `position` props are ignoreddiff --git a/packages/core/src/Dialog/XDSDialog.tsx b/packages/core/src/Dialog/XDSDialog.tsxindex ade557591c..bbde713a3b 100644--- a/packages/core/src/Dialog/XDSDialog.tsx+++ b/packages/core/src/Dialog/XDSDialog.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSDialog.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Dialog/README.md (props table, features, implementation notes)+ * - /packages/core/src/Dialog/Dialog.doc.mjs (props table, features, implementation notes)* - /packages/core/src/Dialog/XDSDialog.test.tsx (tests for new/changed behavior)* - /packages/core/src/Dialog/index.ts (exports if types change)* - /apps/storybook/stories/Dialog.stories.tsx (storybook stories)diff --git a/packages/core/src/Dialog/XDSDialogHeader.tsx b/packages/core/src/Dialog/XDSDialogHeader.tsxindex 40446bde14..03721cfe12 100644--- a/packages/core/src/Dialog/XDSDialogHeader.tsx+++ b/packages/core/src/Dialog/XDSDialogHeader.tsx@@ -5,7 +5,7 @@* @position Dialog header component; used with XDSDialog and XDSLayout** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Dialog/README.md+ * - /packages/core/src/Dialog/Dialog.doc.mjs* - /packages/core/src/Dialog/XDSDialogHeader.test.tsx* - /packages/core/src/Dialog/index.ts* - /apps/storybook/stories/Dialog.stories.tsxdiff --git a/packages/core/src/Dialog/index.ts b/packages/core/src/Dialog/index.tsindex 35ac941624..f1f64729e0 100644--- a/packages/core/src/Dialog/index.ts+++ b/packages/core/src/Dialog/index.ts@@ -4,7 +4,7 @@* @output Exports XDSDialog, XDSDialogHeader, and related types* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/Dialog/README.md+ * SYNC: When modified, update this header and /packages/core/src/Dialog/Dialog.doc.mjs*/export {XDSDialog} from './XDSDialog';diff --git a/packages/core/src/Divider/Divider.doc.mjs b/packages/core/src/Divider/Divider.doc.mjsnew file mode 100644index 0000000000..1943cc0a31--- /dev/null+++ b/packages/core/src/Divider/Divider.doc.mjs@@ -0,0 +1,69 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Divider',+ description: 'Visual separator with optional label, using XDS design tokens.',+ features: [+ 'Supports horizontal and vertical orientations',+ 'Optional label centered on the divider line',+ 'Subtle and strong visual weight variants',+ 'Full-bleed mode extends the divider to container edges via negative margins',+ 'Themeable via ComponentStyles — exposes root, line, and label surfaces',+ ],+ examples: [+ {+ label: 'Basic',+ code: '<XDSDivider />',+ },+ {+ label: 'With label',+ code: '<XDSDivider label="or" />',+ },+ {+ label: 'Vertical',+ code: '<XDSDivider orientation="vertical" />',+ },+ {+ label: 'Strong variant',+ code: '<XDSDivider variant="strong" />',+ },+ {+ label: 'Full bleed',+ code: '<XDSDivider isFullBleed />',+ },+ ],+ props: [+ {+ name: 'orientation',+ type: "'horizontal' | 'vertical'",+ description: 'Orientation of the divider.',+ default: "'horizontal'",+ },+ {+ name: 'label',+ type: 'ReactNode',+ description: 'Optional label centered on the divider.',+ },+ {+ name: 'variant',+ type: "'subtle' | 'strong'",+ description: 'Visual weight of the divider line.',+ default: "'subtle'",+ },+ {+ name: 'isFullBleed',+ type: 'boolean',+ description:+ 'Extend the divider to container edges with negative margins.',+ default: 'false',+ },+ ],+ theming: {+ componentKey: 'divider',+ surfaces: [+ {name: 'root', description: 'Root container element'},+ {name: 'line', description: 'Divider line element'},+ {name: 'label', description: 'Label text element'},+ ],+ },+};diff --git a/packages/core/src/Divider/README.md b/packages/core/src/Divider/README.mddeleted file mode 100644index 27e7e90143..0000000000--- a/packages/core/src/Divider/README.md+++ /dev/null@@ -1,64 +0,0 @@-# XDSDivider--Visual separator with optional label, using XDS design tokens.--## Import--```tsx-import {XDSDivider} from '@xds/core/Divider';-```--## Usage--```tsx-// Simple horizontal divider-<XDSDivider />--// With label-<XDSDivider label="or" />--// Vertical divider-<XDSDivider orientation="vertical" />--// Strong variant (more visible)-<XDSDivider variant="strong" />--// Full bleed (extends to container edges)-<XDSDivider isFullBleed />-```--## Theming--Themes can override `Divider` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- divider: {- root: myStyles,- line: myStyles,- label: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------- | --------------------- |-| `root` | Root container styles |-| `line` | Divider line styles |-| `label` | Label text styles |--## Props--| Prop | Type | Default | Description |-| ------------- | ------------------------------ | -------------- | ----------------------------------------------- |-| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Orientation of the divider |-| `label` | `ReactNode` | — | Optional label centered on the divider |-| `variant` | `'subtle' \| 'strong'` | `'subtle'` | Visual weight of the divider line |-| `isFullBleed` | `boolean` | `false` | Extend to container edges with negative margins |-| `xstyle` | `StyleXStyles` | — | StyleX overrides |diff --git a/packages/core/src/Divider/XDSDivider.tsx b/packages/core/src/Divider/XDSDivider.tsxindex 8a3bd76ab6..012505a284 100644--- a/packages/core/src/Divider/XDSDivider.tsx+++ b/packages/core/src/Divider/XDSDivider.tsx@@ -5,7 +5,7 @@* @position Divider component; provides visual separation with optional label** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Divider/README.md+ * - /packages/core/src/Divider/Divider.doc.mjs* - /packages/core/src/Divider/XDSDivider.test.tsx* - /apps/storybook/stories/Divider.stories.tsx*/diff --git a/packages/core/src/Divider/index.ts b/packages/core/src/Divider/index.tsindex d445499f55..887f4c2ede 100644--- a/packages/core/src/Divider/index.ts+++ b/packages/core/src/Divider/index.ts@@ -4,7 +4,7 @@* @output Exports XDSDivider component and props type* @position Package entry point for Divider*- * SYNC: When modified, update /packages/core/src/Divider/README.md+ * SYNC: When modified, update /packages/core/src/Divider/Divider.doc.mjs*/export {XDSDivider} from './XDSDivider';diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjsnew file mode 100644index 0000000000..eb42a65603--- /dev/null+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs@@ -0,0 +1,326 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'DropdownMenu',+ description:+ 'A dropdown menu component for displaying actionable items in a popup menu.',+ features: [+ 'Button customization: Customize the trigger button via the `button` prop (supports all XDSButton props)',+ 'Data-driven items: Pass items via the `items` prop with support for sections and dividers',+ 'Controlled/Uncontrolled: Supports both controlled (`isMenuOpen`/`onOpenChange`) and uncontrolled modes',+ 'Custom menu width: Override default width (matches button) via `menuWidth` prop',+ 'Sections: Group related items with optional headers using `XDSDropdownMenuSection`',+ 'Keyboard navigation: Full keyboard support (Arrow keys, Home, End, Enter, Space, Escape)',+ 'Accessibility: Proper ARIA roles (menu, menuitem) and attributes',+ 'Custom rendering: Optional `children` render function with `XDSDropdownMenuItem` helper',+ ],+ examples: [+ {+ label: 'Basic usage',+ code: `<XDSDropdownMenu+ button={{ label: 'Actions' }}+ items={[+ { label: 'Edit', onClick: () => handleEdit() },+ { label: 'Delete', onClick: () => handleDelete() },+ ]}+/>`,+ },+ {+ label: 'With icons',+ code: `<XDSDropdownMenu+ button={{ label: 'Actions' }}+ items={[+ { label: 'Edit', icon: PencilIcon, onClick: () => handleEdit() },+ { label: 'Delete', icon: TrashIcon, onClick: () => handleDelete() },+ ]}+/>`,+ },+ {+ label: 'With sections',+ code: `<XDSDropdownMenu+ button={{ label: 'File', variant: 'ghost' }}+ items={[+ {+ type: 'section',+ title: 'Create',+ items: [+ { label: 'New File', onClick: () => handleNew() },+ { label: 'New Folder', onClick: () => handleNewFolder() },+ ],+ },+ {+ type: 'section',+ title: 'Manage',+ items: [+ { label: 'Rename', onClick: () => handleRename() },+ { label: 'Delete', isDisabled: true },+ ],+ },+ ]}+/>`,+ },+ {+ label: 'With dividers',+ code: `<XDSDropdownMenu+ button={{ label: 'Actions' }}+ items={[+ { label: 'Edit', onClick: () => handleEdit() },+ { type: 'divider' },+ { label: 'Delete', onClick: () => handleDelete() },+ ]}+/>`,+ },+ {+ label: 'Controlled mode',+ code: `const [isOpen, setIsOpen] = useState(false);+<XDSDropdownMenu+ button={{ label: 'Options' }}+ items={[...]}+ isMenuOpen={isOpen}+ onOpenChange={setIsOpen}+/>`,+ },+ {+ label: 'Custom item rendering with XDSDropdownMenuItem',+ code: `<XDSDropdownMenu+ button={{ label: 'Users' }}+ items={users}+>+ {item => (+ <XDSDropdownMenuItem+ icon={item.icon}+ label={item.label}+ description={item.email}+ />+ )}+</XDSDropdownMenu>`,+ },+ ],+ theming: {+ componentKey: 'dropdownMenu',+ surfaces: [+ {name: 'root', description: 'Dropdown container styles'},+ {name: 'item', description: 'Menu item styles'},+ ],+ },+ keyboard:+ 'Arrow keys navigate items, Home/End jump to first/last, Enter/Space select, Escape closes the menu',+ accessibility: [+ 'Uses proper ARIA roles: `menu` on the popup container, `menuitem` on each item',+ 'Focus returns to the trigger button when the menu closes',+ 'Keyboard navigation automatically skips disabled items',+ ],+ notes: [+ 'Uses `useXDSLayer` with `mode: "context"` for CSS anchor positioning',+ 'Uses `XDSButton` internally with `ChevronDownIcon` that inherits button text color',+ 'Items are tracked via the `items` prop to enable keyboard navigation',+ 'Light dismiss is enabled by default (clicking outside closes menu)',+ ],+ components: [+ {+ name: 'XDSDropdownMenu',+ description:+ 'Main dropdown menu component with a trigger button and popup item list.',+ props: [+ {+ name: 'button',+ type: 'XDSDropdownMenuButtonProps',+ description:+ 'Props for the trigger button (XDSButton props except onClick).',+ default: "{ label: 'Menu' }",+ },+ {+ name: 'items',+ type: 'XDSDropdownMenuOption[]',+ description:+ 'Menu items, dividers, or sections to display in the popup.',+ required: true,+ },+ {+ name: 'isMenuOpen',+ type: 'boolean',+ description: 'Controlled open state for the menu.',+ },+ {+ name: 'onOpenChange',+ type: '(isOpen: boolean) => void',+ description: 'Callback fired when the open state changes.',+ },+ {+ name: 'menuWidth',+ type: 'number | string',+ description:+ 'Custom menu width; defaults to matching the trigger button width.',+ },+ {+ name: 'onClick',+ type: '() => void',+ description: 'Callback fired when the trigger button is clicked.',+ },+ {+ name: 'children',+ type: '(item: XDSDropdownMenuItemData) => ReactNode',+ description: 'Custom render function for each item in the list.',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSDropdownMenu+ button={{ label: 'Actions' }}+ items={[+ { label: 'Edit', icon: PencilIcon, onClick: () => handleEdit() },+ { label: 'Delete', icon: TrashIcon, onClick: () => handleDelete() },+ ]}+/>`,+ },+ ],+ },+ {+ name: 'XDSDropdownMenuItem',+ description:+ 'Helper component for custom item rendering with consistent styling.',+ props: [+ {+ name: 'icon',+ type: 'XDSIconType',+ description: 'Icon to display before the label.',+ },+ {+ name: 'label',+ type: 'ReactNode',+ description: 'Primary label text.',+ },+ {+ name: 'description',+ type: 'ReactNode',+ description: 'Secondary description text displayed below the label.',+ },+ {+ name: 'children',+ type: 'ReactNode',+ description:+ 'Additional content rendered after the label and description.',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description: 'StyleX styles for the root container.',+ },+ ],+ examples: [+ {+ label: 'With icon and description',+ code: `<XDSDropdownMenuItem+ icon={UserIcon}+ label="Alice Johnson"+ description="[email protected]"+/>`,+ },+ ],+ },+ {+ name: 'XDSDropdownMenuItemData',+ description:+ 'Data shape for a single actionable menu item passed via the `items` prop.',+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Display label for the item.',+ required: true,+ },+ {+ name: 'onClick',+ type: '() => void',+ description: 'Callback fired when the item is selected.',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description:+ 'Whether the item is disabled; disabled items are skipped during keyboard navigation.',+ default: 'false',+ },+ {+ name: 'icon',+ type: 'XDSIconType',+ description: 'Icon to display before the item label.',+ },+ ],+ examples: [+ {+ label: 'Basic item',+ code: `{ label: 'Edit', onClick: () => handleEdit() }`,+ },+ {+ label: 'Disabled item with icon',+ code: `{ label: 'Delete', icon: TrashIcon, isDisabled: true }`,+ },+ ],+ },+ {+ name: 'XDSDropdownMenuDivider',+ description:+ 'A visual divider that can be placed between items in the `items` array.',+ props: [+ {+ name: 'type',+ type: "'divider'",+ description:+ 'Discriminant value that identifies this entry as a divider.',+ required: true,+ },+ ],+ examples: [+ {+ label: 'Divider between items',+ code: `items={[+ { label: 'Edit', onClick: () => handleEdit() },+ { type: 'divider' },+ { label: 'Delete', onClick: () => handleDelete() },+]}`,+ },+ ],+ },+ {+ name: 'XDSDropdownMenuSection',+ description:+ 'A labeled group of items that can be placed in the `items` array.',+ props: [+ {+ name: 'type',+ type: "'section'",+ description:+ 'Discriminant value that identifies this entry as a section.',+ required: true,+ },+ {+ name: 'title',+ type: 'string',+ description:+ 'Optional header text displayed above the section items.',+ },+ {+ name: 'items',+ type: 'XDSDropdownMenuItemData[]',+ description: 'The actionable items that belong to this section.',+ required: true,+ },+ ],+ examples: [+ {+ label: 'Section with title',+ code: `{+ type: 'section',+ title: 'Create',+ items: [+ { label: 'New File', onClick: () => handleNew() },+ { label: 'New Folder', onClick: () => handleNewFolder() },+ ],+}`,+ },+ ],+ },+ ],+};diff --git a/packages/core/src/DropdownMenu/README.md b/packages/core/src/DropdownMenu/README.mddeleted file mode 100644index 1588f9172e..0000000000--- a/packages/core/src/DropdownMenu/README.md+++ /dev/null@@ -1,206 +0,0 @@-# DropdownMenu--A dropdown menu component for displaying actionable items in a popup menu.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Button customization**: Customize the trigger button via the `button` prop (supports all XDSButton props)-- **Data-driven items**: Pass items via the `items` prop with support for sections and dividers-- **Controlled/Uncontrolled**: Supports both controlled (`isMenuOpen`/`onOpenChange`) and uncontrolled modes-- **Custom menu width**: Override default width (matches button) via `menuWidth` prop-- **Sections**: Group related items with optional headers using `XDSDropdownMenuSection`-- **Keyboard navigation**: Full keyboard support (Arrow keys, Home, End, Enter, Space, Escape)-- **Accessibility**: Proper ARIA roles (menu, menuitem) and attributes-- **Custom rendering**: Optional `children` render function with `XDSDropdownMenuItem` helper--## Usage--```tsx-import {XDSDropdownMenu, XDSDropdownMenuItem} from '@xds/core/DropdownMenu';--// Basic usage-<XDSDropdownMenu- button={{ label: 'Actions' }}- items={[- { label: 'Edit', onClick: () => handleEdit() },- { label: 'Delete', onClick: () => handleDelete() },- ]}-/>--// With icons-<XDSDropdownMenu- button={{ label: 'Actions' }}- items={[- { label: 'Edit', icon: PencilIcon, onClick: () => handleEdit() },- { label: 'Delete', icon: TrashIcon, onClick: () => handleDelete() },- ]}-/>--// With sections-<XDSDropdownMenu- button={{ label: 'File', variant: 'ghost' }}- items={[- {- type: 'section',- title: 'Create',- items: [- { label: 'New File', onClick: () => handleNew() },- { label: 'New Folder', onClick: () => handleNewFolder() },- ],- },- {- type: 'section',- title: 'Manage',- items: [- { label: 'Rename', onClick: () => handleRename() },- { label: 'Delete', disabled: true },- ],- },- ]}-/>--// With dividers-<XDSDropdownMenu- button={{ label: 'Actions' }}- items={[- { label: 'Edit', onClick: () => handleEdit() },- { type: 'divider' },- { label: 'Delete', onClick: () => handleDelete() },- ]}-/>--// Controlled mode-const [isOpen, setIsOpen] = useState(false);-<XDSDropdownMenu- button={{ label: 'Options' }}- items={[...]}- isMenuOpen={isOpen}- onOpenChange={setIsOpen}-/>--// Custom item rendering with XDSDropdownMenuItem-<XDSDropdownMenu- button={{ label: 'Users' }}- items={users}->- {item => (- <XDSDropdownMenuItem- icon={item.icon}- label={item.label}- description={item.email}- />- )}-</XDSDropdownMenu>-```--## Props--### XDSDropdownMenu--```tsx-<XDSDropdownMenu- button={{label: 'Actions'}}- items={[- {label: 'Edit', icon: PencilIcon, onClick: () => handleEdit()},- {label: 'Delete', icon: TrashIcon, onClick: () => handleDelete()},- ]}-/>-```--| Prop | Type | Default | Description |-| -------------- | ---------------------------------------------- | ------------------- | ------------------------------------------------------------- |-| `button` | `XDSDropdownMenuButtonProps` | `{ label: 'Menu' }` | Props for the trigger button (XDSButton props except onClick) |-| `items` | `XDSDropdownMenuOption[]` | — | Menu items (items, dividers, or sections) |-| `isMenuOpen` | `boolean` | — | Controlled open state |-| `onOpenChange` | `(isOpen: boolean) => void` | — | Callback when menu visibility changes |-| `menuWidth` | `number \| string` | — | Custom menu width (default: matches button) |-| `onClick` | `() => void` | — | Callback when button is clicked |-| `children` | `(item: XDSDropdownMenuItemData) => ReactNode` | — | Custom render function for items |--### XDSDropdownMenuItem--Helper component for custom item rendering with consistent styling.--```tsx-<XDSDropdownMenuItem- icon={UserIcon}- label="Alice Johnson"- description="[email protected]"-/>-```--| Prop | Type | Default | Description |-| ------------- | -------------- | ------- | ---------------------------------------------- |-| `icon` | `XDSIconType` | — | Icon to display before the label |-| `label` | `ReactNode` | — | Primary label text |-| `description` | `ReactNode` | — | Secondary description text below the label |-| `children` | `ReactNode` | — | Additional content after the label/description |-| `xstyle` | `StyleXStyles` | — | StyleX styles for the root container |--### XDSDropdownMenuItemData--| Prop | Type | Default | Description |-| ---------- | ------------- | ------- | -------------------------------- |-| `label` | `string` | — | Display label for the item |-| `onClick` | `() => void` | — | Callback when item is selected |-| `disabled` | `boolean` | `false` | Whether the item is disabled |-| `icon` | `XDSIconType` | — | Icon to display before the label |--### XDSDropdownMenuDivider--| Prop | Type | Value | Description |-| ------ | ----------- | ----------- | ----------------- |-| `type` | `'divider'` | `'divider'` | Indicates divider |--### XDSDropdownMenuSection--| Prop | Type | Default | Description |-| ------- | --------------------------- | ------- | ----------------------- |-| `type` | `'section'` | — | Indicates section |-| `title` | `string` | — | Optional section header |-| `items` | `XDSDropdownMenuItemData[]` | — | Items in the section |--## Theming--Themes can override `DropdownMenu` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- dropdownMenu: {- root: myStyles,- item: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------- | ------------------------- |-| `root` | Dropdown container styles |-| `item` | Menu item styles |--## Files--| File | Role | Purpose |-| -------------------------- | --------- | -------------------------------- |-| `index.ts` | Entry | Exports components and types |-| `XDSDropdownMenu.tsx` | Core | Main component implementation |-| `XDSDropdownMenuItem.tsx` | Component | Helper for custom item rendering |-| `XDSDropdownMenu.test.tsx` | Testing | Unit tests |--## Implementation Notes--- Uses `useXDSLayer` with `mode: 'context'` for CSS anchor positioning-- Uses `XDSButton` internally with `ChevronDownIcon` that inherits button text color-- Items are tracked via the `items` prop to enable keyboard navigation-- Keyboard navigation skips disabled items-- Light dismiss is enabled by default (clicking outside closes menu)-- Focus returns to button when menu closes-- `XDSDropdownMenuItem` provides consistent styling for custom item layoutsdiff --git a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsxindex 619d7bc1ac..5b5e390806 100644--- a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx+++ b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/DropdownMenu/README.md+ * - /packages/core/src/DropdownMenu/DropdownMenu.doc.mjs* - /packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsx* - /packages/core/src/DropdownMenu/index.ts* - /apps/storybook/stories/DropdownMenu.stories.tsxdiff --git a/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsxindex b29f72c4cb..c4e4127634 100644--- a/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx+++ b/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx@@ -4,7 +4,7 @@* @position Sub-component; used by XDSDropdownMenu and consumers for custom items** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/DropdownMenu/README.md+ * - /packages/core/src/DropdownMenu/DropdownMenu.doc.mjs* - /packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsx* - /packages/core/src/DropdownMenu/index.ts* - /apps/storybook/stories/DropdownMenu.stories.tsxdiff --git a/packages/core/src/EmptyState/EmptyState.doc.mjs b/packages/core/src/EmptyState/EmptyState.doc.mjsnew file mode 100644index 0000000000..548c96c8b1--- /dev/null+++ b/packages/core/src/EmptyState/EmptyState.doc.mjs@@ -0,0 +1,85 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'EmptyState',+ description:+ 'An empty state placeholder for content areas with no data. Displays an icon or illustration, title, optional description, and action buttons.',+ features: [+ 'Uses role="status" so screen readers announce the empty state automatically',+ 'Icon slot renders as decorative (aria-hidden="true") — no extra labeling needed',+ 'Title renders as an <h3> heading element for correct document outline',+ 'Actions are laid out horizontally by default and stack vertically in compact mode',+ 'Compact variant reduces spacing for constrained content areas',+ 'Accepts StyleX override styles via xstyle for custom container adjustments',+ 'Forwarded ref lands on the root <div> container',+ ],+ examples: [+ {+ label: 'Minimal',+ code: '<XDSEmptyState title="No results found" />',+ },+ {+ label: 'With description',+ code: `<XDSEmptyState+ title="No results found"+ description="Try adjusting your search or filters."+/>`,+ },+ {+ label: 'Full example with icon and action',+ code: `<XDSEmptyState+ icon={<XDSIcon icon={InboxIcon} size="lg" />}+ title="No messages"+ description="You're all caught up!"+ actions={<XDSButton label="Compose" variant="primary" />}+/>`,+ },+ {+ label: 'Compact variant',+ code: `<XDSEmptyState+ title="No items"+ description="Nothing to show here."+ isCompact+/>`,+ },+ ],+ props: [+ {+ name: 'title',+ type: 'string',+ description:+ 'Primary message rendered as an <h3> heading inside the empty state.',+ required: true,+ },+ {+ name: 'description',+ type: 'string',+ description:+ 'Optional secondary text providing additional context below the title.',+ },+ {+ name: 'icon',+ type: 'ReactNode',+ description:+ 'Optional icon or illustration displayed above the title; rendered as decorative (aria-hidden="true").',+ },+ {+ name: 'actions',+ type: 'ReactNode',+ description:+ 'Optional action buttons displayed below the description, laid out horizontally by default and stacked vertically when isCompact is true.',+ },+ {+ name: 'isCompact',+ type: 'boolean',+ description:+ 'Enables the compact variant with reduced spacing for constrained content areas.',+ default: 'false',+ },+ ],+ accessibility: [+ 'Container uses role="status" to announce the empty state content to screen readers.',+ 'Icon wrapper has aria-hidden="true" so decorative icons are ignored by assistive technology.',+ 'Title renders as an <h3> element, keeping it in the document heading outline.',+ ],+};diff --git a/packages/core/src/EmptyState/README.md b/packages/core/src/EmptyState/README.mddeleted file mode 100644index a5f962e5f0..0000000000--- a/packages/core/src/EmptyState/README.md+++ /dev/null@@ -1,66 +0,0 @@-# EmptyState--An empty state placeholder for content areas with no data. Displays an icon or illustration, title, optional description, and action buttons.--## Exports--| Export | Type | Description |-| -------------------- | --------- | -------------------------- |-| `XDSEmptyState` | Component | Main empty state component |-| `XDSEmptyStateProps` | Type | Props interface |--## Props--| Prop | Type | Default | Description |-| ------------- | -------------- | ------- | ------------------------------------------------------------- |-| `title` | `string` | — | Primary message (required) |-| `description` | `string` | — | Optional secondary text |-| `icon` | `ReactNode` | — | Optional icon/illustration (rendered decorative, aria-hidden) |-| `actions` | `ReactNode` | — | Optional action buttons (horizontal, stacked when compact) |-| `isCompact` | `boolean` | `false` | Compact variant with reduced spacing |-| `xstyle` | `StyleXStyles` | — | StyleX override styles for the container |-| `data-testid` | `string` | — | Test ID for the container element |--## Usage--```tsx-import {XDSEmptyState} from '@xds/core/EmptyState';--// Minimal-<XDSEmptyState title="No results found" />--// With description-<XDSEmptyState- title="No results found"- description="Try adjusting your search or filters."-/>--// Full example-<XDSEmptyState- icon={<XDSIcon icon={InboxIcon} size="lg" />}- title="No messages"- description="You're all caught up!"- actions={<XDSButton label="Compose" variant="primary" />}-/>--// Compact variant-<XDSEmptyState- title="No items"- description="Nothing to show here."- isCompact-/>-```--## Accessibility--- Container uses `role="status"` to announce content to screen readers-- Icon wrapper has `aria-hidden="true"` (decorative)-- Title renders as an `<h3>` heading element--## Files--| File | Purpose |-| ------------------------ | ------------------------ |-| `XDSEmptyState.tsx` | Component implementation |-| `XDSEmptyState.test.tsx` | Unit tests |-| `index.ts` | Barrel exports |diff --git a/packages/core/src/EmptyState/XDSEmptyState.tsx b/packages/core/src/EmptyState/XDSEmptyState.tsxindex 6d6802780f..1ccfa58241 100644--- a/packages/core/src/EmptyState/XDSEmptyState.tsx+++ b/packages/core/src/EmptyState/XDSEmptyState.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/EmptyState/README.md (props table, features, implementation notes)+ * - /packages/core/src/EmptyState/EmptyState.doc.mjs (props table, features, implementation notes)* - /packages/core/src/EmptyState/XDSEmptyState.test.tsx (tests for new/changed behavior)* - /packages/core/src/EmptyState/index.ts (exports if types change)* - /apps/storybook/stories/EmptyState.stories.tsx (storybook stories)diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjsnew file mode 100644index 0000000000..4d7d7f86c5--- /dev/null+++ b/packages/core/src/Field/Field.doc.mjs@@ -0,0 +1,262 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Field',+ description:+ 'A form field wrapper component that provides label, description, and optional/required indicators.',+ features: [+ 'Label Support — required label for accessibility (can be visually hidden)',+ 'Description — optional description text displayed between the label and input',+ 'Optional/Required Indicators — display "Optional" or "Required" text with bullet separator',+ 'Label Tooltip — optional info icon with tooltip at end of label',+ 'Accessible — label properly associated with input via htmlFor/id',+ 'Styled with StyleX — uses XDS design tokens for consistent styling',+ ],+ examples: [+ {+ label: 'Basic usage',+ code: `const id = useId();+<XDSField label="Email" inputID={id}>+ <input id={id} />+</XDSField>`,+ },+ {+ label: 'With description',+ code: `const inputId = useId();+const descId = useId();+<XDSField+ label="Email"+ description="We'll never share your email"+ inputID={inputId}+ descriptionID={descId}>+ <input id={inputId} aria-describedby={descId} />+</XDSField>`,+ },+ {+ label: 'Hidden label (screen readers only)',+ code: `const searchId = useId();+<XDSField label="Search" isLabelHidden inputID={searchId}>+ <input id={searchId} placeholder="Search..." />+</XDSField>`,+ },+ {+ label: 'Optional field',+ code: `const nicknameId = useId();+<XDSField label="Nickname" isOptional inputID={nicknameId}>+ <input id={nicknameId} placeholder="Enter your nickname" />+</XDSField>`,+ },+ {+ label: 'Required field',+ code: `const usernameId = useId();+<XDSField label="Username" isRequired inputID={usernameId}>+ <input id={usernameId} placeholder="Enter your username" />+</XDSField>`,+ },+ {+ label: 'Description with optional indicator (shows bullet separator)',+ code: `const bioId = useId();+const bioDescId = useId();+<XDSField+ label="Bio"+ description="Tell us about yourself"+ isOptional+ inputID={bioId}+ descriptionID={bioDescId}>+ <input id={bioId} aria-describedby={bioDescId} />+</XDSField>`,+ },+ ],+ theming: {+ componentKey: 'field',+ surfaces: [+ {name: 'root', description: 'Root container styles'},+ {name: 'description', description: 'Description text styles'},+ ],+ },+ notes: [+ 'Parent components are responsible for generating IDs (using the useId hook).',+ 'Label is always rendered for accessibility; use isLabelHidden to hide visually.',+ 'Hidden label uses a CSS technique that remains accessible to screen readers.',+ 'Description is rendered when provided; if descriptionID is also provided, the description element gets that ID for aria-describedby association.',+ 'isOptional and isRequired are mutually exclusive; setting both will show "Optional".',+ 'Optional/Required text appears on the same line as the label.',+ ],+ components: [+ {+ name: 'XDSField',+ description:+ 'Form field wrapper that provides label, description, and optional/required indicators.',+ examples: [+ {+ label: 'Basic',+ code: `<XDSField label="Email" inputID={id}>+ <input id={id} />+</XDSField>`,+ },+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description:+ 'Label text for the field (always rendered for accessibility).',+ required: true,+ },+ {+ name: 'inputID',+ type: 'string',+ description:+ 'ID for the input element (used for the label htmlFor attribute).',+ required: true,+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'The input or control to render.',+ required: true,+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description:+ 'Visually hide the label (still accessible to screen readers).',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description:+ 'Description text displayed between the label and input.',+ },+ {+ name: 'descriptionID',+ type: 'string',+ description:+ 'ID for the description element (use for aria-describedby on the input).',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description:+ 'Whether the field is optional (mutually exclusive with isRequired).',+ default: 'false',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description:+ 'Whether the field is required (mutually exclusive with isOptional).',+ default: 'false',+ },+ {+ name: 'labelIcon',+ type: 'XDSIconType',+ description: 'Icon to display before the label text.',+ },+ {+ name: 'labelTooltip',+ type: 'string',+ description:+ 'Tooltip text to display in an info icon at the end of the label.',+ },+ ],+ },+ {+ name: 'XDSFieldLabel',+ description:+ 'Standalone label component with optional/required indicators and tooltip support.',+ examples: [+ {+ label: 'Basic',+ code: '<XDSFieldLabel label="Username" inputID={id} isRequired />',+ },+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Label text.',+ required: true,+ },+ {+ name: 'inputID',+ type: 'string',+ description: 'ID of the input this label is for.',+ required: true,+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: 'Visually hide the label.',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Whether the associated input is disabled.',+ default: 'false',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description: 'Show "Optional" indicator.',+ default: 'false',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description: 'Show "Required" indicator.',+ default: 'false',+ },+ {+ name: 'labelIcon',+ type: 'XDSIconType',+ description: 'Icon before the label text.',+ },+ {+ name: 'labelTooltip',+ type: 'string',+ description: 'Tooltip text for info icon at end of label.',+ },+ ],+ },+ {+ name: 'XDSFieldStatus',+ description:+ 'Status message component for form field validation feedback.',+ examples: [+ {+ label: 'Error',+ code: '<XDSFieldStatus type="error" message="This field is required" />',+ },+ ],+ props: [+ {+ name: 'type',+ type: "'error' | 'warning' | 'success'",+ description: 'Status type.',+ required: true,+ },+ {+ name: 'message',+ type: 'string',+ description: 'Status message text.',+ required: true,+ },+ {+ name: 'id',+ type: 'string',+ description: 'ID for aria-describedby association.',+ },+ {+ name: 'variant',+ type: "'attached' | 'detached'",+ description:+ 'Visual variant — attached overlaps the input, detached floats below.',+ default: "'attached'",+ },+ ],+ },+ ],+};diff --git a/packages/core/src/Field/README.md b/packages/core/src/Field/README.mddeleted file mode 100644index a5d6629fb6..0000000000--- a/packages/core/src/Field/README.md+++ /dev/null@@ -1,188 +0,0 @@-# Field--A form field wrapper component that provides label and description.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Label Support**: Required label for accessibility (can be visually hidden)-- **Description**: Optional description text displayed between the label and input-- **Optional/Required Indicators**: Display "Optional" or "Required" text with bullet separator-- **Label Tooltip**: Optional info icon with tooltip at end of label-- **Accessible**: Label properly associated with input via htmlFor/id-- **Styled with StyleX**: Uses XDS design tokens for consistent styling--## Components--### XDSField--Form field wrapper that provides label, description, and optional/required indicators.--```tsx-<XDSField label="Email" inputID={id}>- <input id={id} />-</XDSField>-```--| Prop | Type | Default | Description |-| ---------------- | ------------- | ------- | --------------------------------------------- |-| `label` | `string` | — | Label text (required for accessibility) |-| `isLabelHidden` | `boolean` | `false` | Visually hide the label |-| `description` | `string` | — | Description text between label and input |-| `inputID` | `string` | — | ID for the input (used for label's htmlFor) |-| `descriptionID` | `string` | — | ID for the description (for aria-describedby) |-| `isOptional` | `boolean` | `false` | Show "Optional" indicator |-| `isRequired` | `boolean` | `false` | Show "Required" indicator |-| `labelStartIcon` | `XDSIconType` | — | Icon before the label text |-| `labelTooltip` | `string` | — | Tooltip text for info icon at end of label |-| `children` | `ReactNode` | — | The input or control to render |--### XDSFieldLabel--Standalone label component with optional/required indicators and tooltip support.--```tsx-<XDSFieldLabel label="Username" inputID={id} isRequired />-```--| Prop | Type | Default | Description |-| --------------- | ------------- | ------- | ------------------------------------------ |-| `label` | `string` | — | Label text (required) |-| `inputID` | `string` | — | ID of the input this label is for |-| `isLabelHidden` | `boolean` | `false` | Visually hide the label |-| `isDisabled` | `boolean` | `false` | Whether the associated input is disabled |-| `isOptional` | `boolean` | `false` | Show "Optional" indicator |-| `isRequired` | `boolean` | `false` | Show "Required" indicator |-| `startIcon` | `XDSIconType` | — | Icon before the label text |-| `tooltip` | `string` | — | Tooltip text for info icon at end of label |--### XDSFieldStatus--Status message component for form field validation feedback.--```tsx-<XDSFieldStatus type="error" message="This field is required" />-```--| Prop | Type | Default | Description |-| --------- | ----------------------------------- | ------------ | ----------------------------------------------- |-| `type` | `'error' \| 'warning' \| 'success'` | — | Status type |-| `message` | `string` | — | Status message text |-| `id` | `string` | — | ID for aria-describedby association |-| `variant` | `'attached' \| 'detached'` | `'attached'` | Visual variant (overlaps vs floats below input) |--## Usage--```tsx-import {XDSField} from '@xds/core/Field';-import {useId} from 'react';--// Basic usage with explicit IDs-const id = useId();-<XDSField label="Email" inputID={id}>- <input id={id} />-</XDSField>;--// With description-const inputId = useId();-const descId = useId();-<XDSField- label="Email"- description="We'll never share your email"- inputID={inputId}- descriptionID={descId}>- <input id={inputId} aria-describedby={descId} />-</XDSField>;--// Hidden label (for screen readers only)-const searchId = useId();-<XDSField label="Search" isLabelHidden inputID={searchId}>- <input id={searchId} placeholder="Search..." />-</XDSField>;--// Optional field-const nicknameId = useId();-<XDSField label="Nickname" isOptional inputID={nicknameId}>- <input id={nicknameId} placeholder="Enter your nickname" />-</XDSField>;--// Required field-const usernameId = useId();-<XDSField label="Username" isRequired inputID={usernameId}>- <input id={usernameId} placeholder="Enter your username" />-</XDSField>;--// Description with optional indicator (shows bullet separator)-const bioId = useId();-const bioDescId = useId();-<XDSField- label="Bio"- description="Tell us about yourself"- isOptional- inputID={bioId}- descriptionID={bioDescId}>- <input id={bioId} aria-describedby={bioDescId} />-</XDSField>;-```--## Props--| Prop | Type | Required | Description |-| ---------------- | ------------- | -------- | ---------------------------------------------------------------------- |-| `label` | `string` | Yes | Label text for the field (always rendered for accessibility) |-| `isLabelHidden` | `boolean` | No | Visually hide the label (still accessible to screen readers) |-| `description` | `string` | No | Description text displayed between the label and input |-| `inputID` | `string` | Yes | ID for the input element (used for label's htmlFor attribute) |-| `descriptionID` | `string` | No | ID for the description element (use for aria-describedby on the input) |-| `isOptional` | `boolean` | No | Whether the field is optional (mutually exclusive with isRequired) |-| `isRequired` | `boolean` | No | Whether the field is required (mutually exclusive with isOptional) |-| `labelStartIcon` | `XDSIconType` | No | Icon to display before the label text |-| `labelTooltip` | `string` | No | Tooltip text to display in an info icon at the end of the label |-| `children` | `ReactNode` | Yes | The input or control to render |--## Theming--Themes can override `Field` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- field: {- root: myStyles,- description: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------------- | ----------------------- |-| `root` | Root container styles |-| `description` | Description text styles |--## Files--| File | Role | Purpose |-| ------------------------ | ------ | ------------------------------------------------- |-| `index.ts` | Entry | Exports component, types, and shared input styles |-| `XDSField.tsx` | Core | Component implementation |-| `XDSFieldLabel.tsx` | Core | Standalone label component |-| `XDSFieldStatus.tsx` | Core | Status message component |-| `XDSField.test.tsx` | Test | Unit tests |-| `XDSFieldLabel.test.tsx` | Test | Unit tests for label component |-| `types.ts` | Types | Shared input types (status, size) |-| `inputStyles.stylex.ts` | Styles | Shared input wrapper appearance styles |--## Implementation Notes--- Parent components are responsible for generating IDs (using `useId` hook)-- Label is always rendered for accessibility; use `isLabelHidden` to hide visually-- Hidden label uses CSS technique that remains accessible to screen readers-- Description is rendered when provided; if `descriptionID` is also provided, the description element gets that ID for `aria-describedby` association-- `isOptional` and `isRequired` are mutually exclusive; setting both will show "Optional"-- Optional/Required text appears on the same line as the labeldiff --git a/packages/core/src/Field/XDSField.tsx b/packages/core/src/Field/XDSField.tsxindex dd8231f6c1..a559119e3d 100644--- a/packages/core/src/Field/XDSField.tsx+++ b/packages/core/src/Field/XDSField.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSField.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Field/README.md (props table, features, implementation notes)+ * - /packages/core/src/Field/Field.doc.mjs (props table, features, implementation notes)* - /packages/core/src/Field/XDSField.test.tsx (tests for new/changed behavior)* - /packages/core/src/Field/index.ts (exports if types change)* - /apps/storybook/stories/Field.stories.tsx (storybook stories)diff --git a/packages/core/src/Field/XDSFieldLabel.tsx b/packages/core/src/Field/XDSFieldLabel.tsxindex 73e6a37e8a..2798155e35 100644--- a/packages/core/src/Field/XDSFieldLabel.tsx+++ b/packages/core/src/Field/XDSFieldLabel.tsx@@ -5,7 +5,7 @@* @position Core label implementation; used by XDSField, XDSCheckboxInput** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Field/README.md (props table, features, implementation notes)+ * - /packages/core/src/Field/Field.doc.mjs (props table, features, implementation notes)* - /packages/core/src/Field/index.ts (exports if types change)*/diff --git a/packages/core/src/Field/XDSFieldStatus.tsx b/packages/core/src/Field/XDSFieldStatus.tsxindex fe25f0e2a1..b0d23af9b7 100644--- a/packages/core/src/Field/XDSFieldStatus.tsx+++ b/packages/core/src/Field/XDSFieldStatus.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, XDSField.tsx, XDSSwitch.tsx, XDSCheckboxInput.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Field/README.md (props table, features, implementation notes)+ * - /packages/core/src/Field/Field.doc.mjs (props table, features, implementation notes)* - /packages/core/src/Field/index.ts (exports if types change)*/diff --git a/packages/core/src/Field/index.ts b/packages/core/src/Field/index.tsindex 973e8c7bfc..f29c197731 100644--- a/packages/core/src/Field/index.ts+++ b/packages/core/src/Field/index.ts@@ -4,7 +4,7 @@* @output Exports XDSField, XDSFieldProps, XDSFieldStatus, XDSFieldStatusType, XDSFieldLabel, XDSFieldLabelProps, XDSFieldStatus component* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/Field/README.md+ * SYNC: When modified, update this header and /packages/core/src/Field/Field.doc.mjs*/export {XDSField} from './XDSField';diff --git a/packages/core/src/FormLayout/FormLayout.doc.mjs b/packages/core/src/FormLayout/FormLayout.doc.mjsnew file mode 100644index 0000000000..77525c2777--- /dev/null+++ b/packages/core/src/FormLayout/FormLayout.doc.mjs@@ -0,0 +1,80 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'FormLayout',+ description:+ 'A spatial layout container for arranging form fields with consistent spacing and direction.',+ props: [+ {+ name: 'direction',+ type: "'vertical' | 'horizontal' | 'horizontal-labels'",+ description:+ 'Controls field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right with equal flex-grow, and horizontal-labels uses CSS Grid with labels to the left of inputs (collapses to vertical on narrow viewports <=480px).',+ default: "'vertical'",+ },+ {+ name: 'children',+ type: 'ReactNode',+ description:+ 'Form fields to arrange. Accepts XDS inputs (XDSTextInput, XDSSelector, etc.) and XDSField-wrapped custom controls.',+ },+ ],+ examples: [+ {+ label: 'Vertical layout (default)',+ code: `<XDSFormLayout>+ <XDSTextInput label="Name" value={name} onChange={setName} />+ <XDSTextInput label="Email" value={email} onChange={setEmail} />+</XDSFormLayout>`,+ },+ {+ label: 'Horizontal layout for related fields',+ code: `<XDSFormLayout direction="horizontal">+ <XDSTextInput label="First Name" value={first} onChange={setFirst} />+ <XDSTextInput label="Last Name" value={last} onChange={setLast} />+</XDSFormLayout>`,+ },+ {+ label: 'Horizontal labels for settings panels',+ code: `<XDSFormLayout direction="horizontal-labels">+ <XDSTextInput label="Display Name" value={name} onChange={setName} />+ <XDSSelector label="Timezone" value={tz} onChange={setTz} options={tzs} />+</XDSFormLayout>`,+ },+ {+ label: 'Nested layouts',+ code: `<XDSFormLayout direction="vertical">+ <XDSFormLayout direction="horizontal">+ <XDSTextInput label="First Name" value={first} onChange={setFirst} />+ <XDSTextInput label="Last Name" value={last} onChange={setLast} />+ </XDSFormLayout>+ <XDSTextInput label="Email" value={email} onChange={setEmail} />+</XDSFormLayout>`,+ },+ {+ label: 'Dialog composition via HTML form attribute',+ code: `<XDSDialog>+ <form id="edit-form" onSubmit={handleSubmit}>+ <XDSFormLayout>+ <XDSTextInput label="Name" value={name} onChange={setName} />+ </XDSFormLayout>+ </form>+ <XDSDialogFooter>+ <XDSButton label="Save" type="submit" form="edit-form" />+ </XDSDialogFooter>+</XDSDialog>`,+ },+ ],+ features: [+ "Three layout modes: 'vertical' (default), 'horizontal', and 'horizontal-labels'",+ 'Direction context via XDSFormLayoutContext — children can read the current layout direction',+ 'Responsive: horizontal-labels collapses to vertical on narrow viewports (<=480px)',+ 'Nestable: inner FormLayout overrides context for its children',+ 'Purely spatial: does not manage form state or render <form> — form submission is separate',+ ],+ notes: [+ 'Renders a <div>, not a <form>. Use a separate <form> element and connect submit buttons via the HTML form attribute.',+ 'XDSFormLayoutContext provides { direction } to children. Import from @xds/core/FormLayout to read layout direction in custom components.',+ 'Also accepts standard HTML div attributes (id, role, aria-*, etc.) via rest props.',+ ],+};diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjsnew file mode 100644index 0000000000..da70b3c6f1--- /dev/null+++ b/packages/core/src/Grid/Grid.doc.mjs@@ -0,0 +1,162 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Grid',+ description: 'CSS Grid-based layout with responsive auto-fit support.',+ features: [+ 'Fixed-column grids via the `columns` prop',+ 'Responsive auto-fit columns via `minChildWidth` — items wrap based on available space',+ 'Combine `minChildWidth` and `columns` to cap the maximum number of columns',+ 'Gap tokens via `SpacingScale` values for `gap`, `rowGap`, and `columnGap`',+ 'Vertical and horizontal item alignment via `align` and `justify`',+ 'XDSGridSpan lets individual items span multiple columns or rows',+ 'Theming support — override root styles via the `grid` component key',+ ],+ examples: [+ {+ label: 'Fixed 3-column grid',+ code: `<XDSGrid columns={3} gap="space4">+ <Item />+ <Item />+ <Item />+</XDSGrid>`,+ },+ {+ label: 'Responsive auto-fit',+ code: `<XDSGrid minChildWidth={200} gap="space4">+ <Card />+ <Card />+ <Card />+</XDSGrid>`,+ },+ {+ label: 'Auto-fit with max columns cap',+ code: `<XDSGrid minChildWidth={200} columns={4} gap="space4">+ <Card />+</XDSGrid>`,+ },+ {+ label: 'Grid item spanning multiple columns',+ code: `<XDSGrid columns={3} gap="space4">+ <XDSGridSpan columns={2}>Wide item</XDSGridSpan>+ <div>Normal item</div>+</XDSGrid>`,+ },+ {+ label: 'Dense grid (e.g. color swatches, icon grids, compact controls)',+ code: `<XDSGrid columns={6} gap="space2">+ {items.map(item => (+ <XDSButton key={item.id} label={item.label} icon={item.icon} variant="ghost" size="sm" />+ ))}+</XDSGrid>`,+ },+ ],+ theming: {+ componentKey: 'grid',+ surfaces: [{name: 'root', description: 'Root grid container styles'}],+ },+ notes: [+ 'Use XDSGrid for any grid layout instead of manual CSS grid (`display: "grid"`, `gridTemplateColumns`). It handles gap tokens and works with any column count.',+ ],+ components: [+ {+ name: 'XDSGrid',+ description: 'Grid container with fixed or responsive auto-fit columns.',+ props: [+ {+ name: 'columns',+ type: 'number',+ description: 'Maximum number of columns.',+ },+ {+ name: 'minChildWidth',+ type: 'number',+ description:+ 'Minimum item width in px; enables responsive auto-fit column behaviour.',+ },+ {+ name: 'width',+ type: 'number | string',+ description: 'Container width.',+ },+ {+ name: 'height',+ type: 'number | string',+ description: 'Container height.',+ },+ {+ name: 'gap',+ type: 'SpacingScale',+ description: 'Spacing between all items.',+ },+ {+ name: 'rowGap',+ type: 'SpacingScale',+ description: 'Row spacing; overrides `gap` for the row axis.',+ },+ {+ name: 'columnGap',+ type: 'SpacingScale',+ description: 'Column spacing; overrides `gap` for the column axis.',+ },+ {+ name: 'align',+ type: 'GridAlignment',+ description: 'Vertical alignment of items.',+ default: "'stretch'",+ },+ {+ name: 'justify',+ type: 'GridAlignment',+ description: 'Horizontal alignment of items.',+ default: "'stretch'",+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Grid content.',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSGrid columns={3} gap="space4">+ <Item />+ <Item />+ <Item />+</XDSGrid>`,+ },+ ],+ },+ {+ name: 'XDSGridSpan',+ description: 'Grid item that spans multiple columns or rows.',+ props: [+ {+ name: 'columns',+ type: "number | 'full'",+ description: "Columns to span; use `'full'` to span the entire row.",+ },+ {+ name: 'rows',+ type: 'number',+ description: 'Rows to span.',+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Content.',+ },+ ],+ examples: [+ {+ label: 'Spanning two columns',+ code: `<XDSGrid columns={3} gap="space4">+ <XDSGridSpan columns={2}>Wide item</XDSGridSpan>+ <div>Normal item</div>+</XDSGrid>`,+ },+ ],+ },+ ],+};diff --git a/packages/core/src/Grid/README.md b/packages/core/src/Grid/README.mddeleted file mode 100644index 6e4d72f862..0000000000--- a/packages/core/src/Grid/README.md+++ /dev/null@@ -1,114 +0,0 @@-# XDSGrid--CSS Grid-based layout with responsive auto-fit support.--## Import--```tsx-import {XDSGrid, XDSGridSpan} from '@xds/core/Grid';-```--### XDSGrid--Grid container with fixed or responsive auto-fit columns.--```tsx-<XDSGrid columns={3} gap="space4">- <Item />- <Item />- <Item />-</XDSGrid>-```--| Prop | Type | Default | Description |-| --------------- | ---------------- | ----------- | ---------------------------------------------- |-| `columns` | `number` | — | Maximum number of columns |-| `minChildWidth` | `number` | — | Min item width in px (enables auto-fit) |-| `width` | `number \| string` | — | Container width |-| `height` | `number \| string` | — | Container height |-| `gap` | `SpacingScale` | — | Spacing between all items |-| `rowGap` | `SpacingScale` | — | Row spacing (overrides gap) |-| `columnGap` | `SpacingScale` | — | Column spacing (overrides gap) |-| `align` | `GridAlignment` | `'stretch'` | Vertical alignment of items |-| `justify` | `GridAlignment` | `'stretch'` | Horizontal alignment of items |-| `xstyle` | `StyleXStyles` | — | StyleX overrides |-| `children` | `ReactNode` | — | Grid content |--### XDSGridSpan--Grid item that spans multiple columns or rows.--```tsx-<XDSGrid columns={3} gap="space4">- <XDSGridSpan columns={2}>Wide item</XDSGridSpan>- <div>Normal item</div>-</XDSGrid>-```--| Prop | Type | Default | Description |-| ---------- | -------------------- | ------- | ---------------------------------------- |-| `columns` | `number \| 'full'` | — | Columns to span ('full' = entire row) |-| `rows` | `number` | — | Rows to span |-| `xstyle` | `StyleXStyles` | — | StyleX overrides |-| `children` | `ReactNode` | — | Content |--## Usage--```tsx-// Fixed 3-column grid-<XDSGrid columns={3} gap="space4">- <Item />- <Item />- <Item />-</XDSGrid>--// Responsive auto-fit (items wrap based on min width)-<XDSGrid minChildWidth={200} gap="space4">- <Card />- <Card />- <Card />-</XDSGrid>--// Auto-fit with max columns cap-<XDSGrid minChildWidth={200} columns={4} gap="space4">- <Card />-</XDSGrid>--// Grid item spanning multiple columns-<XDSGrid columns={3} gap="space4">- <XDSGridSpan span={2}>Wide item</XDSGridSpan>- <div>Normal item</div>-</XDSGrid>--// Dense grid (e.g. color swatches, icon grids, compact controls)-<XDSGrid columns={6} gap="space2">- {items.map(item => (- <XDSButton key={item.id} label={item.label} icon={item.icon} variant="ghost" size="sm" />- ))}-</XDSGrid>-```--Use `XDSGrid` for any grid layout instead of manual CSS grid (`display: 'grid'`,-`gridTemplateColumns`). It handles gap tokens and works with any column count.--## Theming--Themes can override `Grid` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- grid: {- root: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------- | -------------------------- |-| `root` | Root grid container styles |diff --git a/packages/core/src/Grid/XDSGrid.tsx b/packages/core/src/Grid/XDSGrid.tsxindex b8a1505703..cc68abe845 100644--- a/packages/core/src/Grid/XDSGrid.tsx+++ b/packages/core/src/Grid/XDSGrid.tsx@@ -5,7 +5,7 @@* @position Grid component; provides CSS Grid-based layout** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Grid/README.md+ * - /packages/core/src/Grid/Grid.doc.mjs* - /packages/core/src/Grid/XDSGrid.test.tsx* - /apps/storybook/stories/Grid.stories.tsx*/diff --git a/packages/core/src/Grid/XDSGridSpan.tsx b/packages/core/src/Grid/XDSGridSpan.tsxindex 48bd5eeb57..7d7d331730 100644--- a/packages/core/src/Grid/XDSGridSpan.tsx+++ b/packages/core/src/Grid/XDSGridSpan.tsx@@ -5,7 +5,7 @@* @position Grid span component; controls grid item span** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Grid/README.md+ * - /packages/core/src/Grid/Grid.doc.mjs* - /packages/core/src/Grid/XDSGrid.test.tsx* - /apps/storybook/stories/Grid.stories.tsx*/diff --git a/packages/core/src/Grid/index.ts b/packages/core/src/Grid/index.tsindex 839cce3dde..072f1cda27 100644--- a/packages/core/src/Grid/index.ts+++ b/packages/core/src/Grid/index.ts@@ -4,7 +4,7 @@* @output Exports Grid components and types* @position Package entry point for Grid*- * SYNC: When modified, update /packages/core/src/Grid/README.md+ * SYNC: When modified, update /packages/core/src/Grid/Grid.doc.mjs*/export {XDSGrid} from './XDSGrid';diff --git a/packages/core/src/Icon/Icon.doc.mjs b/packages/core/src/Icon/Icon.doc.mjsnew file mode 100644index 0000000000..ca138029f5--- /dev/null+++ b/packages/core/src/Icon/Icon.doc.mjs@@ -0,0 +1,97 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Icon',+ description:+ 'Renders icons with XDS design system colors and sizes. Supports both direct SVG icon components and semantic icon names that adapt to the active theme.',+ features: [+ "Semantic Icon Names: Use names like 'close' or 'chevronDown' — resolved from the theme's icon registry",+ 'Direct Icon Components: Pass any SVG icon component (heroicons, lucide, etc.) directly',+ "Theme-Adaptable: Semantic icons automatically match the active theme's icon set",+ 'Built-in Fallbacks: 12 lightweight inline SVGs (~1.4KB) ensure icons render without a theme',+ 'Theme Colors: Color variants mapped to XDS icon color tokens',+ 'Consistent Sizing: Four size options aligned with common UI patterns',+ 'Accessible: Icons are hidden from screen readers by default (aria-hidden)',+ ],+ props: [+ {+ name: 'icon',+ type: 'XDSIconName | ComponentType<SVGProps>',+ description: 'Semantic name or SVG icon component.',+ required: true,+ },+ {+ name: 'color',+ type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'positive' | 'negative' | 'warning' | 'inherit'",+ description: 'Color variant mapped to XDS icon color tokens.',+ default: "'primary'",+ },+ {+ name: 'size',+ type: "'xsm' | 'sm' | 'md' | 'lg'",+ description: 'Icon size.',+ default: "'md'",+ },+ ],+ examples: [+ {+ label: 'Semantic icon names (theme-adaptable)',+ code: `import { XDSIcon } from '@xds/core/Icon';++// Semantic name — adapts to theme+<XDSIcon icon="close" />+<XDSIcon icon="chevronDown" size="sm" color="inherit" />+<XDSIcon icon="checkCircle" color="positive" />++// Great for building theme-adaptable UI+<XDSIcon icon="info" size="sm" color="secondary" />`,+ },+ {+ label: 'Direct icon components',+ code: `import { XDSIcon } from '@xds/core/Icon';+import { HomeIcon } from '@heroicons/react/24/outline';+import { HeartIcon } from '@heroicons/react/24/solid';++// Direct component+<XDSIcon icon={HomeIcon} />+<XDSIcon icon={HomeIcon} color="accent" size="lg" />+<XDSIcon icon={HeartIcon} color="negative" />++// Accessible icon with label+<XDSIcon icon={HomeIcon} aria-hidden={false} aria-label="Home" role="img" />`,+ },+ {+ label: 'Icon sources',+ code: `// Heroicons+import {HomeIcon} from '@heroicons/react/24/outline';++// Lucide+import {Home} from 'lucide-react';++// Any component matching ComponentType<SVGProps<SVGSVGElement>>`,+ },+ ],+ theming: {+ componentKey: 'icon',+ surfaces: [+ {+ name: 'root',+ description: 'Root SVG element styles',+ },+ ],+ },+ accessibility: [+ 'Icons are hidden from screen readers by default via aria-hidden="true" since icons are typically decorative.',+ 'For meaningful icons, set aria-hidden={false}, role="img", and aria-label to provide accessible context.',+ ],+ notes: [+ 'When icon is a semantic name string, resolution order is: (1) theme registry — if an XDSTheme is active and provides an icon for that name, it is used; (2) built-in fallback — otherwise, a lightweight inline SVG is rendered. Components always render visually complete, even without a theme. Themes can override any or all icons; the registry accepts partial overrides.',+ 'When icon is a component, additional SVG props (like aria-label, role) are passed through to the underlying SVG element.',+ 'flexShrink: 0 prevents icons from shrinking in flex containers.',+ 'String mode wraps the resolved icon in a <span> with fontSize-based sizing so 1em-based registry icons scale correctly.',+ 'Component mode passes stylex.props directly to the SVG element for zero-overhead styling.',+ 'Semantic icon names and their usages — close (CloseButton, TimeInput): ✕ close/dismiss; chevronDown (DropdownMenu, Selector, TabMenu): ▾ expand/dropdown; chevronLeft (Calendar): ‹ previous; chevronRight (Calendar): › next; check (Selector, TabMenu): ✓ selected item; checkCircle (Input status): ✓○ success; xCircle (Input status): ✕○ error; warning (Input status): △! warning; info (FieldLabel): ⓘ information tooltip; calendar (DateInput): 📅 date picker; clock (TimeInput): 🕐 time picker; externalLink (Link): ↗ opens in new window.',+ 'Color token mappings — primary: --color-icon-primary (default); secondary: --color-icon-secondary (de-emphasized); tertiary: --color-icon-tertiary (subtle/background); disabled: --color-icon-disabled (disabled state); accent: --color-accent (interactive/actionable); positive: --color-positive (success/confirmation); negative: --color-negative (error/destructive); warning: --color-warning (caution/attention); inherit: currentColor (inherits from parent text color).',+ 'Size dimensions — xsm: 12x12px (dense UI, badges, indicators); sm: 16x16px (inline with text, compact UI); md: 20x20px (default, buttons, inputs); lg: 24x24px (emphasis, standalone icons).',+ ],+};diff --git a/packages/core/src/Icon/IconRegistry.tsx b/packages/core/src/Icon/IconRegistry.tsxindex f48866d284..f19f14891e 100644--- a/packages/core/src/Icon/IconRegistry.tsx+++ b/packages/core/src/Icon/IconRegistry.tsx@@ -5,7 +5,7 @@* @position Core icon infrastructure; consumed by components that need internal icons** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Icon/README.md (features, usage)+ * - /packages/core/src/Icon/Icon.doc.mjs (features, usage)* - /packages/core/src/Icon/index.ts (exports)* - /packages/core/src/Icon/defaultIcons.tsx (fallback icon set)*/diff --git a/packages/core/src/Icon/README.md b/packages/core/src/Icon/README.mddeleted file mode 100644index f7ad785c62..0000000000--- a/packages/core/src/Icon/README.md+++ /dev/null@@ -1,166 +0,0 @@-# Icon--Renders icons with XDS design system colors and sizes. Supports both direct SVG icon components and semantic icon names that adapt to the active theme.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Semantic Icon Names**: Use names like `'close'` or `'chevronDown'` — resolved from the theme's icon registry-- **Direct Icon Components**: Pass any SVG icon component (heroicons, lucide, etc.) directly-- **Theme-Adaptable**: Semantic icons automatically match the active theme's icon set-- **Built-in Fallbacks**: 12 lightweight inline SVGs (~1.4KB) ensure icons render without a theme-- **Theme Colors**: Color variants mapped to XDS icon color tokens-- **Consistent Sizing**: Four size options aligned with common UI patterns-- **Accessible**: Icons are hidden from screen readers by default (aria-hidden)--## Usage--### Semantic icon names (theme-adaptable)--Use semantic names for icons that should adapt to the active theme. These resolve from the theme's icon registry, falling back to built-in SVGs when no theme is present.--```tsx-import { XDSIcon } from '@xds/core/Icon';--// Semantic name — adapts to theme-<XDSIcon icon="close" />-<XDSIcon icon="chevronDown" size="sm" color="inherit" />-<XDSIcon icon="checkCircle" color="positive" />--// Great for building theme-adaptable UI-<XDSIcon icon="info" size="sm" color="secondary" />-```--### Direct icon components--Pass SVG icon components directly when you need a specific icon that isn't in the semantic set, or when you want full control.--```tsx-import { XDSIcon } from '@xds/core/Icon';-import { HomeIcon } from '@heroicons/react/24/outline';-import { HeartIcon } from '@heroicons/react/24/solid';--// Direct component-<XDSIcon icon={HomeIcon} />-<XDSIcon icon={HomeIcon} color="accent" size="lg" />-<XDSIcon icon={HeartIcon} color="negative" />--// Accessible icon with label-<XDSIcon icon={HomeIcon} aria-hidden={false} aria-label="Home" role="img" />-```--## Props--| Prop | Type | Default | Description |-| ------- | ------------------------------------------------------------------------------------------------------------------------ | ----------- | ----------------------------------- |-| `icon` | `XDSIconName \| ComponentType<SVGProps>` | (required) | Semantic name or SVG icon component |-| `color` | `'primary' \| 'secondary' \| 'tertiary' \| 'disabled' \| 'accent' \| 'positive' \| 'negative' \| 'warning' \| 'inherit'` | `'primary'` | Color variant |-| `size` | `'xsm' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Icon size |--When `icon` is a component, additional SVG props (like `aria-label`, `role`) are passed through to the underlying SVG element.--## Semantic Icon Names--These names are used internally by XDS components and can be used in your own UI to build theme-adaptable interfaces. They resolve from the theme's icon registry, or fall back to built-in lightweight SVGs.--| Name | Used by | Description |-| -------------- | ------------------------------- | --------------------- |-| `close` | CloseButton, TimeInput | ✕ close / dismiss |-| `chevronDown` | DropdownMenu, Selector, TabMenu | ▾ expand / dropdown |-| `chevronLeft` | Calendar | ‹ previous |-| `chevronRight` | Calendar | › next |-| `check` | Selector, TabMenu | ✓ selected item |-| `checkCircle` | Input status | ✓○ success |-| `xCircle` | Input status | ✕○ error |-| `warning` | Input status | △! warning |-| `info` | FieldLabel | ⓘ information tooltip |-| `calendar` | DateInput | 📅 date picker |-| `clock` | TimeInput | 🕐 time picker |-| `externalLink` | Link | ↗ opens in new window |--## Color Variants--| Value | Token | Use Case |-| ----------- | ------------------------ | ------------------------------- |-| `primary` | `--color-icon-primary` | Default icon color |-| `secondary` | `--color-icon-secondary` | De-emphasized icons |-| `tertiary` | `--color-icon-tertiary` | Subtle, background icons |-| `disabled` | `--color-icon-disabled` | Disabled state |-| `accent` | `--color-accent` | Interactive, actionable icons |-| `positive` | `--color-positive` | Success, confirmation |-| `negative` | `--color-negative` | Error, destructive actions |-| `warning` | `--color-warning` | Caution, attention |-| `inherit` | `currentColor` | Inherits from parent text color |--## Size Variants--| Value | Dimensions | Use Case |-| ----- | ---------- | ---------------------------- |-| `xsm` | 12x12px | Dense UI, badges, indicators |-| `sm` | 16x16px | Inline with text, compact UI |-| `md` | 20x20px | Default, buttons, inputs |-| `lg` | 24x24px | Emphasis, standalone icons |--## How Icon Resolution Works--When `icon` is a semantic name string:--1. **Theme registry** — If an `XDSTheme` is active and provides an icon for that name, it's used-2. **Built-in fallback** — Otherwise, a lightweight inline SVG is rendered--This means components always render visually complete, even without a theme. Themes can override any or all icons — the registry accepts partial overrides.--## Icon Sources--Any SVG icon component works with the direct component mode:--```tsx-// Heroicons-import {HomeIcon} from '@heroicons/react/24/outline';--// Lucide-import {Home} from 'lucide-react';--// Any component matching ComponentType<SVGProps<SVGSVGElement>>-```--## Theming--Themes can override `Icon` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- icon: {- root: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------- | ----------------------- |-| `root` | Root SVG element styles |--## Files--| File | Role | Purpose |-| ------------------ | -------- | ---------------------------------------- |-| `index.ts` | Entry | Exports component, types, and registry |-| `XDSIcon.tsx` | Core | Component implementation (both modes) |-| `IconRegistry.tsx` | Registry | Context, hook, and semantic name types |-| `defaultIcons.tsx` | Fallback | 12 lightweight inline SVG fallback icons |-| `XDSIcon.test.tsx` | Test | Unit tests |--## Implementation Notes--- Uses `aria-hidden="true"` by default since icons are typically decorative-- For meaningful icons, set `aria-hidden={false}`, `role="img"`, and `aria-label`-- `flexShrink: 0` prevents icons from shrinking in flex containers-- String mode wraps the resolved icon in a `<span>` with `fontSize`-based sizing so `1em`-based registry icons scale correctly-- Component mode passes `stylex.props` directly to the SVG element for zero-overhead stylingdiff --git a/packages/core/src/Icon/XDSIcon.tsx b/packages/core/src/Icon/XDSIcon.tsxindex 007932a997..433c152ff7 100644--- a/packages/core/src/Icon/XDSIcon.tsx+++ b/packages/core/src/Icon/XDSIcon.tsx@@ -11,7 +11,7 @@* theme's icon registry (or built-in fallback SVGs) and wrapped in a styled span.** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Icon/README.md (props table, features, implementation notes)+ * - /packages/core/src/Icon/Icon.doc.mjs (props table, features, implementation notes)* - /packages/core/src/Icon/XDSIcon.test.tsx (tests for new/changed behavior)* - /packages/core/src/Icon/index.ts (exports if types change)* - /apps/storybook/stories/Icon.stories.tsx (storybook stories)diff --git a/packages/core/src/Icon/defaultIcons.tsx b/packages/core/src/Icon/defaultIcons.tsxindex b17add46b2..07aa267bd9 100644--- a/packages/core/src/Icon/defaultIcons.tsx+++ b/packages/core/src/Icon/defaultIcons.tsx@@ -18,7 +18,7 @@** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Icon/IconRegistry.tsx (XDSIconName type if names change)- * - /packages/core/src/Icon/README.md (fallback icon documentation)+ * - /packages/core/src/Icon/Icon.doc.mjs (fallback icon documentation)*/import type {XDSIconRegistry} from './IconRegistry';diff --git a/packages/core/src/Icon/index.ts b/packages/core/src/Icon/index.tsindex 828d275321..642f72ade0 100644--- a/packages/core/src/Icon/index.ts+++ b/packages/core/src/Icon/index.ts@@ -4,7 +4,7 @@* @output Exports XDSIcon, its prop types, icon registry context, and semantic name types* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/Icon/README.md+ * SYNC: When modified, update this header and /packages/core/src/Icon/Icon.doc.mjs*/export {XDSIcon} from './XDSIcon';diff --git a/packages/core/src/Layer/Layer.doc.mjs b/packages/core/src/Layer/Layer.doc.mjsnew file mode 100644index 0000000000..41eb544a28--- /dev/null+++ b/packages/core/src/Layer/Layer.doc.mjs@@ -0,0 +1,464 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Layer',+ description:+ 'Hooks and components for overlay content using CSS Anchor Positioning and the Popover API — no React portals needed.',+ features: [+ 'CSS Anchor Positioning for automatic placement relative to trigger elements',+ 'Popover API for top-layer rendering — no React portals needed',+ 'Type-safe mode system: context mode (anchor positioning) and fixed mode (manual coordinates)',+ 'TypeScript enforces correct render props per mode at compile time',+ 'Hover/focus triggered layers with configurable show and hide delays',+ 'Controlled and uncontrolled popover modes',+ 'Light dismiss support (click outside or Escape to close)',+ 'Focus trap inside open popovers',+ 'ARIA button + dialog pattern applied automatically to trigger elements',+ 'Graceful degradation in Firefox: Popover API works, anchor positioning degrades acceptably',+ 'Full support in Chrome and Safari',+ ],+ notes: [+ 'CSS Anchor Positioning is fully supported in Chrome and Safari. Firefox supports the Popover API but not anchor positioning — this is an acceptable degradation.',+ 'useXDSLayer context mode: pass a ref to the trigger element, then call render(children, { placement?, alignment? }). Fixed mode: call show() to display, then render(children, { x, y }) with required coordinates.',+ 'When using hooks directly, compose aria-describedby with your own IDs using a mergeIds utility: ids.filter(Boolean).join(" ") || undefined.',+ 'XDSPopover locates the trigger button inside children by searching for <button> or [role="button"] — the child tree must contain one. It applies click/keydown handlers and aria-haspopup, aria-expanded, aria-controls automatically.',+ 'XDSPopover uses an inline-flex anchor wrapper so that pressed-state transforms on the trigger (e.g. :active scale) do not shift the anchor position and cause popover jitter.',+ 'In sibling mode (anchorRef prop), XDSPopover and XDSTooltip attach to an external ref rather than wrapping children — useful when the trigger and overlay are not parent/child.',+ 'XDSHoverCard (hook) returns a describedBy id — pass it as aria-describedby on the trigger for screen reader support.',+ 'LayerPlacement values: above | below | start | end. LayerAlignment values: start | center | end.',+ ],+ accessibility: [+ 'XDSPopover implements the button + dialog ARIA pattern: aria-haspopup, aria-expanded, and aria-controls are set on the trigger button automatically.',+ 'XDSTooltip links the tooltip content to the trigger via aria-describedby.',+ 'useXDSHoverCard returns a describedBy id that should be spread onto the trigger element so screen readers announce the hover card content.',+ 'When composing multiple aria-describedby sources, merge them with a utility: ids.filter(Boolean).join(" ") || undefined.',+ 'XDSPopover traps focus inside the popover dialog while it is open.',+ 'XDSPopover supports keyboard activation for role="button" elements (Enter and Space) in addition to native <button> click synthesis.',+ ],+ keyboard:+ 'Escape closes any open layer. Enter/Space open a popover when the trigger has focus. Focus is trapped inside an open XDSPopover.',+ examples: [+ {+ label: 'useXDSLayer — context mode',+ code: `const layer = useXDSLayer({mode: 'context'});++<button ref={layer.ref}>Trigger</button>+{layer.render(<Content />, {placement: 'above', alignment: 'center'})}`,+ },+ {+ label: 'useXDSLayer — fixed mode',+ code: `const layer = useXDSLayer({mode: 'fixed'});++layer.show();+{layer.render(<Content />, {x: mouseX, y: mouseY})}`,+ },+ {+ label: 'useXDSHoverCard',+ code: `const hoverCard = useXDSHoverCard({placement: 'above'});++<XDSButton ref={hoverCard.ref} aria-describedby={hoverCard.describedBy}>+ Hover me+</XDSButton>+{hoverCard.renderHoverCard(<ProfileCard user={user} />)}`,+ },+ {+ label: 'XDSTooltip',+ code: `<XDSTooltip content="Save your changes" placement="above">+ <XDSButton label="Save" variant="primary" />+</XDSTooltip>`,+ },+ {+ label: 'XDSHoverCard',+ code: `<XDSHoverCard content={<ProfileCard user={user} />} placement="above">+ <XDSButton>Hover me</XDSButton>+</XDSHoverCard>`,+ },+ {+ label: 'XDSPopover — basic',+ code: `<XDSPopover label="Settings" content={<SettingsPanel />} placement="below">+ <XDSButton label="Settings" />+</XDSPopover>`,+ },+ {+ label: 'XDSPopover — controlled',+ code: `<XDSPopover+ isShown={isOpen}+ onToggle={setIsOpen}+ label="Filter"+ content={<FilterForm />}+>+ <XDSButton label="Filter" />+</XDSPopover>`,+ },+ {+ label: 'XDSPopover — sibling mode with anchorRef',+ code: `<XDSPopover+ anchorRef={myButtonRef}+ label="Actions"+ content={<ActionMenu />}+ placement="below"+/>`,+ },+ {+ label: 'Composing aria-describedby with useXDSHoverCard',+ code: `const hoverCard = useXDSHoverCard();++function mergeIds(...ids: (string | undefined)[]) {+ return ids.filter(Boolean).join(' ') || undefined;+}++<XDSInput+ ref={hoverCard.ref}+ aria-describedby={mergeIds(fieldErrorId, hoverCard.describedBy)}+/>`,+ },+ ],+ components: [+ {+ name: 'useXDSLayer',+ description:+ 'Core layer hook with type-safe modes for different positioning strategies (context mode for anchor positioning, fixed mode for manual coordinates).',+ props: [+ {+ name: 'mode',+ type: "'context' | 'fixed'",+ description:+ 'Positioning strategy: context uses CSS anchor positioning relative to a trigger ref; fixed uses explicit x/y coordinates.',+ required: true,+ },+ {+ name: 'onShow',+ type: '() => void',+ description: 'Callback fired when the layer becomes visible.',+ },+ {+ name: 'onHide',+ type: '() => void',+ description: 'Callback fired when the layer is hidden.',+ },+ ],+ examples: [+ {+ label: 'Context mode',+ code: `const layer = useXDSLayer({mode: 'context'});++<button ref={layer.ref}>Trigger</button>+{layer.render(<Content />, {placement: 'above', alignment: 'center'})}`,+ },+ {+ label: 'Fixed mode',+ code: `const layer = useXDSLayer({mode: 'fixed'});++layer.show();+{layer.render(<Content />, {x: mouseX, y: mouseY})}`,+ },+ ],+ },+ {+ name: 'useXDSHoverCard',+ description:+ 'Hook for hover/focus triggered layers with configurable show and hide timing.',+ props: [+ {+ name: 'placement',+ type: 'LayerPlacement',+ description: 'Position relative to the anchor element.',+ default: "'above'",+ },+ {+ name: 'alignment',+ type: 'LayerAlignment',+ description: 'Alignment along the placement axis.',+ default: "'center'",+ },+ {+ name: 'delay',+ type: 'number',+ description: 'Show delay in milliseconds.',+ default: '300',+ },+ {+ name: 'hideDelay',+ type: 'number',+ description: 'Hide delay in milliseconds.',+ default: '200',+ },+ {+ name: 'focusTrigger',+ type: "'auto' | 'always' | 'never'",+ description: 'Controls when focus events trigger the layer.',+ default: "'auto'",+ },+ {+ name: 'isEnabled',+ type: 'boolean',+ description: 'Enables or disables all hover and focus triggers.',+ default: 'true',+ },+ {+ name: 'onShow',+ type: '() => void',+ description: 'Callback fired when the hover card becomes visible.',+ },+ {+ name: 'onHide',+ type: '() => void',+ description: 'Callback fired when the hover card is hidden.',+ },+ ],+ examples: [+ {+ label: 'Basic usage',+ code: `const hoverCard = useXDSHoverCard({placement: 'above'});++<XDSButton ref={hoverCard.ref} aria-describedby={hoverCard.describedBy}>+ Hover me+</XDSButton>+{hoverCard.renderHoverCard(<ProfileCard user={user} />)}`,+ },+ ],+ },+ {+ name: 'XDSTooltip',+ description:+ 'Component wrapper for tooltip display triggered on hover or focus.',+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Trigger element(s) that activate the tooltip.',+ },+ {+ name: 'anchorRef',+ type: 'RefObject<HTMLElement>',+ description:+ 'External anchor ref for sibling mode — attaches the tooltip to this element instead of wrapping children.',+ },+ {+ name: 'content',+ type: 'ReactNode',+ description: 'Tooltip content, typically short text.',+ },+ {+ name: 'placement',+ type: 'LayerPlacement',+ description: 'Position relative to the anchor element.',+ default: "'above'",+ },+ {+ name: 'alignment',+ type: 'LayerAlignment',+ description: 'Alignment along the placement axis.',+ default: "'center'",+ },+ {+ name: 'delay',+ type: 'number',+ description: 'Show delay in milliseconds.',+ default: '200',+ },+ {+ name: 'hideDelay',+ type: 'number',+ description: 'Hide delay in milliseconds.',+ default: '0',+ },+ {+ name: 'focusTrigger',+ type: "'auto' | 'always' | 'never'",+ description: 'Controls when focus events trigger the tooltip.',+ default: "'auto'",+ },+ {+ name: 'isEnabled',+ type: 'boolean',+ description: 'Enables or disables the tooltip triggers.',+ default: 'true',+ },+ {+ name: 'hasHoverIndication',+ type: "'auto' | boolean",+ description:+ 'Shows a dashed underline on the trigger element to indicate a tooltip is available.',+ default: "'auto'",+ },+ ],+ examples: [+ {+ label: 'Basic tooltip',+ code: `<XDSTooltip content="Save your changes" placement="above">+ <XDSButton label="Save" variant="primary" />+</XDSTooltip>`,+ },+ ],+ },+ {+ name: 'XDSHoverCard',+ description:+ 'Component wrapper for hover card display — a richer, larger overlay triggered on hover or focus.',+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Trigger element that must accept a ref.',+ },+ {+ name: 'content',+ type: 'ReactNode',+ description: 'Hover card content.',+ required: true,+ },+ {+ name: 'placement',+ type: 'LayerPlacement',+ description: 'Position relative to the anchor element.',+ default: "'above'",+ },+ {+ name: 'alignment',+ type: 'LayerAlignment',+ description: 'Alignment along the placement axis.',+ default: "'center'",+ },+ {+ name: 'delay',+ type: 'number',+ description: 'Show delay in milliseconds.',+ default: '300',+ },+ {+ name: 'hideDelay',+ type: 'number',+ description: 'Hide delay in milliseconds.',+ default: '200',+ },+ {+ name: 'focusTrigger',+ type: "'auto' | 'always' | 'never'",+ description: 'Controls when focus events trigger the hover card.',+ default: "'auto'",+ },+ {+ name: 'isEnabled',+ type: 'boolean',+ description: 'Enables or disables the hover and focus triggers.',+ default: 'true',+ },+ ],+ examples: [+ {+ label: 'Basic hover card',+ code: `<XDSHoverCard content={<ProfileCard user={user} />} placement="above">+ <XDSButton>Hover me</XDSButton>+</XDSHoverCard>`,+ },+ ],+ },+ {+ name: 'XDSPopover',+ description:+ 'A click-triggered popover for displaying interactive content anchored to a trigger element, implementing the button + dialog ARIA pattern.',+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description:+ 'Trigger element. Must contain a <button> or [role="button"] element — the popover finds it and applies click/keydown handlers and ARIA attributes.',+ },+ {+ name: 'anchorRef',+ type: 'React.RefObject<HTMLElement>',+ description:+ 'External ref to use as the popover anchor in sibling mode. The referenced element must be a <button> or [role="button"].',+ },+ {+ name: 'content',+ type: 'ReactNode',+ description: 'Content to display inside the popover.',+ required: true,+ },+ {+ name: 'placement',+ type: 'LayerPlacement',+ description:+ 'Position placement relative to the trigger using CSS anchor positioning.',+ default: "'below'",+ },+ {+ name: 'alignment',+ type: 'LayerAlignment',+ description: 'Alignment along the placement axis.',+ default: "'start'",+ },+ {+ name: 'isOpen',+ type: 'boolean',+ description:+ 'Whether the popover is shown in controlled mode. Omit for uncontrolled behavior.',+ },+ {+ name: 'onOpenChange',+ type: '(isOpen: boolean) => void',+ description: 'Callback fired when the popover visibility changes.',+ },+ {+ name: 'isEnabled',+ type: 'boolean',+ description: 'When false, trigger interactions are ignored.',+ default: 'true',+ },+ {+ name: 'width',+ type: 'number | string',+ description:+ 'Width of the popover container. Numbers are treated as px; strings are used as-is. Defaults to matching the trigger width.',+ default: "'auto'",+ },+ {+ name: 'label',+ type: 'string',+ description:+ 'Accessible label for the popover dialog, used as aria-label on the dialog element. Recommended for accessibility.',+ },+ ],+ examples: [+ {+ label: 'Basic popover',+ code: `<XDSPopover label="Settings" content={<SettingsPanel />} placement="below">+ <XDSButton label="Settings" />+</XDSPopover>`,+ },+ {+ label: 'Controlled popover',+ code: `<XDSPopover+ isShown={isOpen}+ onToggle={setIsOpen}+ label="Filter"+ content={<FilterForm />}+>+ <XDSButton label="Filter" />+</XDSPopover>`,+ },+ {+ label: 'Sibling mode with anchorRef',+ code: `<XDSPopover+ anchorRef={myButtonRef}+ label="Actions"+ content={<ActionMenu />}+ placement="below"+/>`,+ },+ ],+ },+ ],+ theming: {+ componentKey: 'popover',+ surfaces: [+ {+ name: 'container',+ description:+ 'Inner content container of the popover (background, border-radius, shadow, padding).',+ },+ ],+ },+};diff --git a/packages/core/src/Layer/README.md b/packages/core/src/Layer/README.mddeleted file mode 100644index 01356c9864..0000000000--- a/packages/core/src/Layer/README.md+++ /dev/null@@ -1,181 +0,0 @@-# Layer--Layer components for overlay content using modern browser APIs.--<!-- SYNC: When files in this directory change, update this document. -->--## Overview--The Layer system provides hooks and components for overlay content using:--- **CSS Anchor Positioning** for automatic positioning relative to trigger elements-- **Popover API** for top-layer rendering (no React portals needed)--## Browser Support--- **Chrome**: Full support-- **Safari**: Full support-- **Firefox**: Popover API works, anchor positioning not yet (acceptable degradation)--## Import--```tsx-import {useXDSLayer, useXDSHoverCard, XDSHoverCard} from '@xds/core/Layer';-```--## Hooks--### useXDSLayer--Core layer hook with type-safe modes for different positioning strategies.--```tsx-// Context mode (anchor positioning)-const layer = useXDSLayer({mode: 'context'});--<button ref={layer.ref}>Trigger</button>;-{- layer.render(<Content />, {placement: 'above', alignment: 'center'});-}--// Fixed mode (manual coordinates)-const layer = useXDSLayer({mode: 'fixed'});--layer.show();-{- layer.render(<Content />, {x: mouseX, y: mouseY});-}-```--TypeScript enforces correct render props per mode:--- **Context mode**: `render(children, { placement?, alignment? })`-- **Fixed mode**: `render(children, { x, y })` (required)--| Option | Type | Description |-| -------- | ---------------------- | -------------------- |-| `mode` | `'context' \| 'fixed'` | Positioning strategy |-| `onShow` | `() => void` | Callback when shown |-| `onHide` | `() => void` | Callback when hidden |--### useXDSHoverCard--Hook for hover/focus triggered layers with timing control.--```tsx-const hoverCard = useXDSHoverCard({placement: 'above'});--<XDSButton ref={hoverCard.ref} aria-describedby={hoverCard.describedBy}>- Hover me-</XDSButton>;--{- hoverCard.renderHoverCard(<ProfileCard user={user} />);-}-```--| Option | Type | Default | Description |-| -------------- | ------------------------------- | --------- | --------------------------- |-| `placement` | `LayerPlacement` | `'above'` | Position relative to anchor |-| `alignment` | `LayerAlignment` | `'start'` | Alignment on placement axis |-| `delay` | `number` | `300` | Show delay in ms |-| `hideDelay` | `number` | `200` | Hide delay in ms |-| `focusTrigger` | `'auto' \| 'always' \| 'never'` | `'auto'` | Focus listener behavior |-| `isEnabled` | `boolean` | `true` | Enable/disable triggers |-| `onShow` | `() => void` | — | Callback when shown |-| `onHide` | `() => void` | — | Callback when hidden |--## Components--### XDSTooltip--Component wrapper for tooltip display on hover/focus.--```tsx-<XDSTooltip content="Save your changes" placement="above">- <XDSButton label="Save" variant="primary" />-</XDSTooltip>-```--| Prop | Type | Default | Description |-| -------------------- | ------------------------------- | ---------- | -------------------------------------- |-| `children` | `ReactNode` | — | Trigger element(s) |-| `anchorRef` | `RefObject<HTMLElement>` | — | External anchor ref (sibling mode) |-| `content` | `ReactNode` | — | Tooltip content (typically short text) |-| `placement` | `LayerPlacement` | `'above'` | Position relative to anchor |-| `alignment` | `LayerAlignment` | `'center'` | Alignment on placement axis |-| `delay` | `number` | `200` | Show delay in ms |-| `hideDelay` | `number` | `0` | Hide delay in ms |-| `focusTrigger` | `'auto' \| 'always' \| 'never'` | `'auto'` | When to trigger on focus |-| `isEnabled` | `boolean` | `true` | Enable/disable triggers |-| `hasHoverIndication` | `'auto' \| boolean` | `'auto'` | Show dashed underline on trigger |-| `onOpenChange` | `(isOpen: boolean) => void` | — | Callback when visibility changes |--### XDSHoverCard--Component wrapper for simpler hover card usage.--```tsx-<XDSHoverCard content={<ProfileCard user={user} />} placement="above">- <XDSButton>Hover me</XDSButton>-</XDSHoverCard>-```--| Prop | Type | Default | Description |-| -------------- | ------------------------------- | --------- | --------------------------------- |-| `children` | `ReactElement` | Required | Trigger element (must accept ref) |-| `content` | `ReactNode` | Required | Hover card content |-| `placement` | `LayerPlacement` | `'above'` | Position relative to anchor |-| `alignment` | `LayerAlignment` | `'start'` | Alignment on placement axis |-| `delay` | `number` | `300` | Show delay in ms |-| `hideDelay` | `number` | `200` | Hide delay in ms |-| `focusTrigger` | `'auto' \| 'always' \| 'never'` | `'auto'` | Focus listener behavior |-| `isEnabled` | `boolean` | `true` | Enable/disable triggers |-| `onOpenChange` | `(isOpen: boolean) => void` | — | Callback when visibility changes |--## Position Values--### LayerPlacement--| Value | Description |-| ------- | ------------------------ |-| `above` | Above the anchor |-| `below` | Below the anchor |-| `start` | Start side (left in LTR) |-| `end` | End side (right in LTR) |--### LayerAlignment--| Value | Description |-| -------- | ------------------- |-| `start` | Align to start edge |-| `center` | Center aligned |-| `end` | Align to end edge |--## ARIA Guidelines--When using hooks directly, compose `aria-describedby` with your own IDs:--```tsx-const hoverCard = useXDSHoverCard();--<XDSInput- ref={hoverCard.ref}- aria-describedby={mergeIds(fieldErrorId, hoverCard.describedBy)}-/>;--// Utility function-function mergeIds(...ids: (string | undefined)[]) {- return ids.filter(Boolean).join(' ') || undefined;-}-```--## Files--| File | Role | Purpose |-| ----------------------- | --------- | ------------------------------------------ |-| `index.ts` | Entry | Exports all layer utilities and components |-| `useXDSLayer.ts` | Hook | Core popover and positioning logic |-| `useXDSHoverCard.ts` | Hook | Hover/focus triggers for layers |-| `XDSHoverCard.tsx` | Component | Wrapper component for hover cards |-| `XDSHoverCard.test.tsx` | Test | HoverCard unit tests |diff --git a/packages/core/src/Layer/XDSHoverCard.tsx b/packages/core/src/Layer/XDSHoverCard.tsxindex f5177c9353..be54162803 100644--- a/packages/core/src/Layer/XDSHoverCard.tsx+++ b/packages/core/src/Layer/XDSHoverCard.tsx@@ -5,7 +5,7 @@* @position Layer component; uses display:contents wrapper to avoid cloneElement** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Layer/README.md+ * - /packages/core/src/Layer/Layer.doc.mjs* - /packages/core/src/Layer/XDSHoverCard.test.tsx* - /packages/core/src/Layer/index.ts* - /apps/storybook/stories/HoverCard.stories.tsxdiff --git a/packages/core/src/Layer/XDSPopover.tsx b/packages/core/src/Layer/XDSPopover.tsxindex 89bf8e241c..3f880e9eee 100644--- a/packages/core/src/Layer/XDSPopover.tsx+++ b/packages/core/src/Layer/XDSPopover.tsx@@ -7,7 +7,7 @@* For hover-triggered overlays, use XDSHoverCard instead.** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Layer/README.md+ * - /packages/core/src/Layer/Layer.doc.mjs* - /packages/core/src/Layer/XDSPopover.test.tsx* - /packages/core/src/Layer/index.ts* - /apps/storybook/stories/Popover.stories.tsxdiff --git a/packages/core/src/Layer/XDSTooltip.tsx b/packages/core/src/Layer/XDSTooltip.tsxindex 97f380d79c..3bfc7062bd 100644--- a/packages/core/src/Layer/XDSTooltip.tsx+++ b/packages/core/src/Layer/XDSTooltip.tsx@@ -5,7 +5,7 @@* @position Layer component; uses display:contents wrapper to avoid cloneElement** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Layer/README.md+ * - /packages/core/src/Layer/Layer.doc.mjs* - /packages/core/src/Layer/XDSTooltip.test.tsx* - /packages/core/src/Layer/index.ts* - /apps/storybook/stories/Tooltip.stories.tsxdiff --git a/packages/core/src/Layer/useXDSHoverCard.tsx b/packages/core/src/Layer/useXDSHoverCard.tsxindex 7188b7fc9e..bc3c00c34e 100644--- a/packages/core/src/Layer/useXDSHoverCard.tsx+++ b/packages/core/src/Layer/useXDSHoverCard.tsx@@ -5,7 +5,7 @@* @position Layer hook; builds on useXDSLayer for hover card behavior** SYNC: When modified, update:- * - /packages/core/src/Layer/README.md+ * - /packages/core/src/Layer/Layer.doc.mjs* - /packages/core/src/Layer/index.ts*/diff --git a/packages/core/src/Layer/useXDSLayer.tsx b/packages/core/src/Layer/useXDSLayer.tsxindex b32696b31e..b7817fc909 100644--- a/packages/core/src/Layer/useXDSLayer.tsx+++ b/packages/core/src/Layer/useXDSLayer.tsx@@ -5,7 +5,7 @@* @position Core layer utility; used by useXDSHoverCard, useXDSTooltip, etc.** SYNC: When modified, update:- * - /packages/core/src/Layer/README.md+ * - /packages/core/src/Layer/Layer.doc.mjs* - /packages/core/src/Layer/index.ts*/diff --git a/packages/core/src/Layer/useXDSPopover.tsx b/packages/core/src/Layer/useXDSPopover.tsxindex c42aa43523..39f233173f 100644--- a/packages/core/src/Layer/useXDSPopover.tsx+++ b/packages/core/src/Layer/useXDSPopover.tsx@@ -8,7 +8,7 @@* Use this for interactive popover content that should trap focus.** SYNC: When modified, update:- * - /packages/core/src/Layer/README.md+ * - /packages/core/src/Layer/Layer.doc.mjs* - /packages/core/src/Layer/index.ts*/diff --git a/packages/core/src/Layer/useXDSTooltip.tsx b/packages/core/src/Layer/useXDSTooltip.tsxindex 8e179045e6..dd3bf76688 100644--- a/packages/core/src/Layer/useXDSTooltip.tsx+++ b/packages/core/src/Layer/useXDSTooltip.tsx@@ -5,7 +5,7 @@* @position Layer hook; builds on useXDSLayer for tooltip behavior** SYNC: When modified, update:- * - /packages/core/src/Layer/README.md+ * - /packages/core/src/Layer/Layer.doc.mjs* - /packages/core/src/Layer/index.ts*/diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjsnew file mode 100644index 0000000000..2d9f8e674a--- /dev/null+++ b/packages/core/src/Layout/Layout.doc.mjs@@ -0,0 +1,414 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Layout',+ description:+ 'Composable utilities and components for building structured layouts with a container/content separation pattern.',+ features: [+ 'Primitive + higher-order architecture — XDSLayoutContainer is a primitive; XDSCard, XDSSection are higher-order',+ 'Directional padding via CSS variables — inner/outer, horizontal/vertical padding control',+ 'Context-aware defaults — components detect their slot and self-adjust',+ 'Automatic RTL support — uses CSS logical properties',+ 'XDSLayout provides a page shell with header, sidebar(s), content, and footer slots',+ 'XDSHStack and XDSVStack for simple stacking layouts',+ 'XDSStackItem for fill/alignment control within stacks',+ ],+ examples: [+ {+ label: 'Basic page layout',+ code: `<XDSLayout+ header={<XDSLayoutHeader hasDivider>App Name</XDSLayoutHeader>}+ content={<XDSLayoutContent>Body content</XDSLayoutContent>}+ footer={<XDSLayoutFooter hasDivider>Footer</XDSLayoutFooter>}+/>`,+ },+ {+ label: 'App shell with sidebar',+ code: `<XDSLayout+ header={<XDSLayoutHeader hasDivider>App Name</XDSLayoutHeader>}+ start={+ <XDSLayoutPanel hasDivider width={240} role="navigation">+ <Navigation />+ </XDSLayoutPanel>+ }+ content={+ <XDSLayoutContent role="main">+ <MainContent />+ </XDSLayoutContent>+ }+/>`,+ },+ {+ label: 'Card layout',+ code: `<XDSCard>+ <XDSLayout+ header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}+ content={<XDSLayoutContent>Body content</XDSLayoutContent>}+ footer={+ <XDSLayoutFooter hasDivider>+ <XDSHStack gap="space2" hAlign="end">+ <XDSButton variant="secondary">Cancel</XDSButton>+ <XDSButton variant="primary">Save</XDSButton>+ </XDSHStack>+ </XDSLayoutFooter>+ }+ />+</XDSCard>`,+ },+ ],+ notes: [+ 'Use XDSLayout for page shells and app layouts — any UI with a header bar, sidebar navigation, scrollable content area, or action footer. Do not use for simple stacking (use XDSVStack/XDSHStack instead).',+ 'XDSLayoutContainer sets CSS variables that child components read: --layout-padding-outer-x (outer horizontal padding), --layout-padding-outer-y (outer vertical padding), --layout-padding-inner-x (inner horizontal padding used by Header, Footer, Content, Panel), --layout-padding-inner-y (inner vertical padding used by Header, Footer, Content, Panel).',+ 'Architecture layers from top to bottom: Higher-Order Components (XDSCard, XDSSection), Layout Structure (XDSLayout + XDSLayoutHeader/Footer/Content/Panel), Primitive (XDSLayoutContainer sets CSS variables), Layout Utilities (XDSHStack, XDSVStack, stack(), stackItem()).',+ 'All layout utilities and components are exported from @xds/core/Layout.',+ ],+ components: [+ {+ name: 'XDSLayout',+ description:+ 'Page shell with header, sidebar(s), content, and footer slots for building full app layouts.',+ props: [+ {+ name: 'content',+ type: 'ReactNode',+ description: 'Main content area (center).',+ },+ {+ name: 'header',+ type: 'ReactNode',+ description: 'Header slot.',+ },+ {+ name: 'footer',+ type: 'ReactNode',+ description: 'Footer slot.',+ },+ {+ name: 'start',+ type: 'ReactNode',+ description: 'Start panel (left in LTR).',+ },+ {+ name: 'end',+ type: 'ReactNode',+ description: 'End panel (right in LTR).',+ },+ {+ name: 'height',+ type: "'fill' | 'auto'",+ description:+ 'Height behavior — fill the container or grow with content.',+ default: "'fill'",+ },+ {+ name: 'isFullBleed',+ type: 'boolean',+ description: 'Remove padding at outer edges.',+ default: 'false',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSLayout+ header={<XDSLayoutHeader hasDivider>App Name</XDSLayoutHeader>}+ content={<XDSLayoutContent>Body content</XDSLayoutContent>}+ footer={<XDSLayoutFooter hasDivider>Footer</XDSLayoutFooter>}+/>`,+ },+ {+ label: 'With start panel',+ code: `<XDSLayout+ header={<XDSLayoutHeader hasDivider>App Name</XDSLayoutHeader>}+ start={+ <XDSLayoutPanel hasDivider width={240} role="navigation">+ <Navigation />+ </XDSLayoutPanel>+ }+ content={+ <XDSLayoutContent role="main">+ <MainContent />+ </XDSLayoutContent>+ }+/>`,+ },+ ],+ },+ {+ name: 'XDSLayoutHeader',+ description: 'Top bar for page titles, app bars, and toolbars.',+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Header content.',+ },+ {+ name: 'hasDivider',+ type: 'boolean',+ description: 'Border at bottom edge.',+ default: 'false',+ },+ {+ name: 'height',+ type: 'number | string',+ description: 'Header height.',+ },+ {+ name: 'isFullBleed',+ type: 'boolean',+ description: 'Remove internal padding.',+ default: 'false',+ },+ {+ name: 'label',+ type: 'string',+ description: 'Accessible label for the landmark element.',+ },+ {+ name: 'role',+ type: 'AriaRole',+ description: 'ARIA landmark role.',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSLayoutHeader hasDivider role="banner">+ Page Title+</XDSLayoutHeader>`,+ },+ ],+ },+ {+ name: 'XDSLayoutContent',+ description: 'Scrollable main content area.',+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Content.',+ },+ {+ name: 'isFullBleed',+ type: 'boolean',+ description: 'Remove internal padding.',+ default: 'false',+ },+ {+ name: 'isScrollable',+ type: 'boolean',+ description: 'Enable scrollable overflow.',+ default: 'true',+ },+ {+ name: 'label',+ type: 'string',+ description: 'Accessible label for the landmark element.',+ },+ {+ name: 'role',+ type: 'AriaRole',+ description: 'ARIA landmark role.',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSLayoutContent role="main">+ <MainContent />+</XDSLayoutContent>`,+ },+ ],+ },+ {+ name: 'XDSLayoutFooter',+ description: 'Bottom bar for action bars, pagination, and status bars.',+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Footer content.',+ },+ {+ name: 'hasDivider',+ type: 'boolean',+ description: 'Border at top edge.',+ default: 'false',+ },+ {+ name: 'height',+ type: 'number | string',+ description: 'Footer height.',+ },+ {+ name: 'isFullBleed',+ type: 'boolean',+ description: 'Remove internal padding.',+ default: 'false',+ },+ {+ name: 'label',+ type: 'string',+ description: 'Accessible label for the landmark element.',+ },+ {+ name: 'role',+ type: 'AriaRole',+ description: 'ARIA landmark role.',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSLayoutFooter hasDivider>+ <XDSButton label="Save" variant="primary" />+</XDSLayoutFooter>`,+ },+ ],+ },+ {+ name: 'XDSLayoutPanel',+ description: 'Sidebar for navigation, settings, or inspector panels.',+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Panel content.',+ },+ {+ name: 'hasDivider',+ type: 'boolean',+ description: 'Border on the appropriate edge.',+ default: 'false',+ },+ {+ name: 'isFullBleed',+ type: 'boolean',+ description: 'Remove internal padding.',+ default: 'false',+ },+ {+ name: 'isScrollable',+ type: 'boolean',+ description: 'Enable scrollable overflow.',+ default: 'true',+ },+ {+ name: 'label',+ type: 'string',+ description: 'Accessible label for the landmark element.',+ },+ {+ name: 'role',+ type: 'AriaRole',+ description: 'ARIA landmark role.',+ },+ ],+ examples: [+ {+ label: 'Navigation sidebar',+ code: `<XDSLayoutPanel hasDivider width={240} role="navigation">+ <Navigation />+</XDSLayoutPanel>`,+ },+ ],+ },+ {+ name: 'XDSLayoutContainer',+ description:+ 'Primitive component that sets CSS variables for padding, used as the base for XDSCard and XDSSection.',+ props: [],+ examples: [+ {+ label: 'Basic',+ code: '<XDSLayoutContainer>Content</XDSLayoutContainer>',+ },+ ],+ },+ {+ name: 'XDSCard',+ description:+ 'Card with elevation and themed styling, built on XDSLayoutContainer.',+ props: [],+ examples: [+ {+ label: 'Basic',+ code: '<XDSCard>Card content</XDSCard>',+ },+ {+ label: 'With layout structure',+ code: `<XDSCard>+ <XDSLayout+ header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}+ content={<XDSLayoutContent>Body content</XDSLayoutContent>}+ footer={+ <XDSLayoutFooter hasDivider>+ <XDSHStack gap="space2" hAlign="end">+ <XDSButton variant="secondary">Cancel</XDSButton>+ <XDSButton variant="primary">Save</XDSButton>+ </XDSHStack>+ </XDSLayoutFooter>+ }+ />+</XDSCard>`,+ },+ ],+ },+ {+ name: 'XDSSection',+ description:+ 'Section with background variants (section, transparent, wash), built on XDSLayoutContainer.',+ props: [],+ examples: [+ {+ label: 'Basic',+ code: '<XDSSection>Section content</XDSSection>',+ },+ ],+ },+ {+ name: 'XDSHStack',+ description: 'Horizontal stack that arranges children left-to-right.',+ props: [],+ examples: [+ {+ label: 'Basic',+ code: `<XDSHStack gap="space2" hAlign="end">+ <XDSButton variant="secondary">Cancel</XDSButton>+ <XDSButton variant="primary">Save</XDSButton>+</XDSHStack>`,+ },+ ],+ },+ {+ name: 'XDSVStack',+ description: 'Vertical stack that arranges children top-to-bottom.',+ props: [],+ examples: [+ {+ label: 'Basic',+ code: `<XDSVStack gap="space4">+ <XDSCard>First</XDSCard>+ <XDSCard>Second</XDSCard>+</XDSVStack>`,+ },+ ],+ },+ {+ name: 'XDSStackItem',+ description:+ 'Stack item with fill and alignment control for use inside XDSHStack or XDSVStack.',+ props: [],+ examples: [+ {+ label: 'Fill remaining space',+ code: `<XDSHStack>+ <XDSStackItem grow>Main content</XDSStackItem>+ <XDSButton variant="primary">Action</XDSButton>+</XDSHStack>`,+ },+ ],+ },+ ],+};diff --git a/packages/core/src/Layout/README.md b/packages/core/src/Layout/README.mddeleted file mode 100644index b8cd028150..0000000000--- a/packages/core/src/Layout/README.md+++ /dev/null@@ -1,278 +0,0 @@-# Layout--XDS Layout System - composable utilities and components for building structured layouts.--<!-- SYNC: When files in this directory change, update this document. -->--## Overview--The layout system provides a container/content separation pattern with:--- **Primitive + higher-order architecture** — XDSLayoutContainer is a primitive; XDSCard, XDSSection are higher-order-- **Directional padding via CSS variables** — Inner/outer, horizontal/vertical padding control-- **Context-aware defaults** — Components detect their slot and self-adjust-- **Automatic RTL support** — Uses CSS logical properties--## Import--All layout utilities and components are exported from `@xds/core/Layout`:--```tsx-import {- // Container components- XDSLayoutContainer,- XDSCard,- XDSSection,- // Layout structure- XDSLayout,- XDSLayoutHeader,- XDSLayoutFooter,- XDSLayoutContent,- XDSLayoutPanel,- // Stack utilities- XDSHStack,- XDSVStack,- XDSStackItem,- stack,- stackItem,-} from '@xds/core/Layout';-```--## Structure--```-Layout/-├── index.ts # Entry point, re-exports everything-├── README.md # This documentation-├── Container/ # Container primitive and higher-order components-│ ├── index.ts-│ ├── README.md-│ ├── XDSLayoutContainer.tsx # Primitive-│ ├── XDSCard.tsx # Card with elevation-│ └── XDSSection.tsx # Section with background variants-├── XDSLayout/ # Layout structure components-│ ├── index.ts-│ ├── README.md-│ ├── XDSLayout.tsx-│ ├── XDSLayoutHeader.tsx-│ ├── XDSLayoutFooter.tsx-│ ├── XDSLayoutContent.tsx-│ ├── XDSLayoutPanel.tsx-│ └── XDSLayoutAreaContext.ts-└── Stack/ # Stack utilities and components- ├── index.ts- ├── README.md- ├── stack.stylex.ts- ├── stackItem.stylex.ts- ├── XDSHStack.tsx- ├── XDSVStack.tsx- └── XDSStackItem.tsx-```--## Quick Start--### XDSLayout--Page shell with header, sidebar(s), content, and footer slots.--```tsx-<XDSLayout- header={<XDSLayoutHeader hasDivider>App Name</XDSLayoutHeader>}- content={<XDSLayoutContent>Body content</XDSLayoutContent>}- footer={<XDSLayoutFooter hasDivider>Footer</XDSLayoutFooter>}-/>-```--| Prop | Type | Default | Description |-| ------------- | --------------- | -------- | ----------------------------------------------- |-| `content` | `ReactNode` | — | Main content area (center) |-| `header` | `ReactNode` | — | Header slot |-| `footer` | `ReactNode` | — | Footer slot |-| `start` | `ReactNode` | — | Start panel (left in LTR) |-| `end` | `ReactNode` | — | End panel (right in LTR) |-| `height` | `'fill' \| 'auto'` | `'fill'` | Height behavior (fill container vs grow) |-| `isFullBleed` | `boolean` | `false` | Remove padding at outer edges |--### XDSLayoutHeader--Top bar for page titles, app bars, and toolbars.--```tsx-<XDSLayoutHeader hasDivider role="banner">- Page Title-</XDSLayoutHeader>-```--| Prop | Type | Default | Description |-| ------------- | ------------------ | ------- | ------------------------------------- |-| `children` | `ReactNode` | — | Header content |-| `hasDivider` | `boolean` | `false` | Border at bottom edge |-| `height` | `number \| string` | — | Header height |-| `isFullBleed` | `boolean` | `false` | Remove internal padding |-| `label` | `string` | — | Accessible label for landmark |-| `role` | `AriaRole` | — | ARIA landmark role |--### XDSLayoutContent--Scrollable main content area.--```tsx-<XDSLayoutContent role="main">- <MainContent />-</XDSLayoutContent>-```--| Prop | Type | Default | Description |-| -------------- | ---------- | ------- | ------------------------------------- |-| `children` | `ReactNode`| — | Content |-| `isFullBleed` | `boolean` | `false` | Remove internal padding |-| `isScrollable` | `boolean` | `true` | Enable scrollable overflow |-| `label` | `string` | — | Accessible label for landmark |-| `role` | `AriaRole` | — | ARIA landmark role |--### XDSLayoutFooter--Bottom bar for action bars, pagination, and status bars.--```tsx-<XDSLayoutFooter hasDivider>- <XDSButton label="Save" variant="primary" />-</XDSLayoutFooter>-```--| Prop | Type | Default | Description |-| ------------- | ------------------ | ------- | ------------------------------------- |-| `children` | `ReactNode` | — | Footer content |-| `hasDivider` | `boolean` | `false` | Border at top edge |-| `height` | `number \| string` | — | Footer height |-| `isFullBleed` | `boolean` | `false` | Remove internal padding |-| `label` | `string` | — | Accessible label for landmark |-| `role` | `AriaRole` | — | ARIA landmark role |--### XDSLayoutPanel--Sidebar for navigation, settings, or inspector panels.--```tsx-<XDSLayoutPanel hasDivider width={240} role="navigation">- <Navigation />-</XDSLayoutPanel>-```--| Prop | Type | Default | Description |-| -------------- | ------------------ | ------- | ------------------------------------- |-| `children` | `ReactNode` | — | Panel content |-| `hasDivider` | `boolean` | `false` | Border on appropriate edge |-| `isFullBleed` | `boolean` | `false` | Remove internal padding |-| `isScrollable` | `boolean` | `true` | Enable scrollable overflow |-| `label` | `string` | — | Accessible label for landmark |-| `role` | `AriaRole` | — | ARIA landmark role |--## Usage Examples--### Card Layout--```tsx-<XDSCard>- <XDSLayout- header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}- content={<XDSLayoutContent>Body content</XDSLayoutContent>}- footer={- <XDSLayoutFooter hasDivider>- <XDSHStack gap="space2" hAlign="end">- <XDSButton variant="secondary">Cancel</XDSButton>- <XDSButton variant="primary">Save</XDSButton>- </XDSHStack>- </XDSLayoutFooter>- }- />-</XDSCard>-```--### App shell with sidebar--```tsx-<XDSLayout- header={<XDSLayoutHeader hasDivider>App Name</XDSLayoutHeader>}- start={- <XDSLayoutPanel hasDivider width={240} role="navigation">- <Navigation />- </XDSLayoutPanel>- }- content={- <XDSLayoutContent role="main">- <MainContent />- </XDSLayoutContent>- }-/>-```--## Components--### Container Components--| Component | Description |-| -------------------- | ------------------------------------------------------------- |-| `XDSLayoutContainer` | Primitive that sets CSS variables for padding |-| `XDSCard` | Card with elevation and themed styling |-| `XDSSection` | Section with background variants (section, transparent, wash) |--See [Container/README.md](./Container/README.md) for full documentation.--### Layout Structure--Use XDSLayout for page shells and app layouts — any UI with a header bar, sidebar navigation,-scrollable content area, or action footer. Don't use for simple stacking (use XDSVStack/XDSHStack).--| Component | Description |-| ------------------ | ----------------------------------------------------------------------- |-| `XDSLayout` | Page shell with header, sidebar(s), content, and footer slots |-| `XDSLayoutHeader` | Top bar — page titles, app bars, toolbars |-| `XDSLayoutFooter` | Bottom bar — action bars, pagination, status bars |-| `XDSLayoutContent` | Scrollable main content area |-| `XDSLayoutPanel` | Sidebar — navigation panels, settings sidebars, detail/inspector panels |--See [XDSLayout/README.md](./XDSLayout/README.md) for full documentation.--### Stack Components--| Component | Description |-| -------------- | -------------------------------------- |-| `XDSHStack` | Horizontal stack (left-to-right) |-| `XDSVStack` | Vertical stack (top-to-bottom) |-| `XDSStackItem` | Stack item with fill/alignment control |--See [Stack/README.md](./Stack/README.md) for full documentation.--## Architecture--```-┌─────────────────────────────────────────────────────────┐-│ Higher-Order Components │-│ XDSCard, XDSSection (future: XDSModal, XDSPopover) │-├─────────────────────────────────────────────────────────┤-│ Layout Structure │-│ XDSLayout + XDSLayoutHeader/Footer/Content/Panel │-├─────────────────────────────────────────────────────────┤-│ Primitive │-│ XDSLayoutContainer (sets CSS variables) │-├─────────────────────────────────────────────────────────┤-│ Layout Utilities │-│ XDSHStack, XDSVStack, stack(), stackItem() │-└─────────────────────────────────────────────────────────┘-```--## CSS Variables--XDSLayoutContainer sets these CSS variables that child components read:--| Variable | Used By | Purpose |-| -------------------------- | ------------------------------ | ------------------------ |-| `--layout-padding-outer-x` | XDSLayout | Outer horizontal padding |-| `--layout-padding-outer-y` | XDSLayout | Outer vertical padding |-| `--layout-padding-inner-x` | Header, Footer, Content, Panel | Inner horizontal padding |-| `--layout-padding-inner-y` | Header, Footer, Content, Panel | Inner vertical padding |--## Related--- See the [System Architecture](https://github.com/facebookexperimental/xds/wiki/System-Architecture) wiki page for the broader layout philosophydiff --git a/packages/core/src/Layout/XDSLayout.tsx b/packages/core/src/Layout/XDSLayout.tsxindex 1a076318e4..366fffaec7 100644--- a/packages/core/src/Layout/XDSLayout.tsx+++ b/packages/core/src/Layout/XDSLayout.tsx@@ -8,7 +8,7 @@* Manages padding collapse, scroll containment, and responsive slot sizing automatically.** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Layout/XDSLayout/README.md+ * - /packages/core/src/Layout/Layout.doc.mjs* - /packages/core/src/Layout/XDSLayout/index.ts* - /apps/storybook/stories/Layout.stories.tsx*/diff --git a/packages/core/src/Layout/XDSLayoutAreaContext.ts b/packages/core/src/Layout/XDSLayoutAreaContext.tsindex 70a76d2aa6..321c157d32 100644--- a/packages/core/src/Layout/XDSLayoutAreaContext.ts+++ b/packages/core/src/Layout/XDSLayoutAreaContext.ts@@ -5,7 +5,7 @@* @position Context for layout slot detection** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Layout/XDSLayout/README.md+ * - /packages/core/src/Layout/Layout.doc.mjs*/'use client';diff --git a/packages/core/src/Layout/XDSLayoutContent.tsx b/packages/core/src/Layout/XDSLayoutContent.tsxindex 4f15ad84d0..ff3b2cc400 100644--- a/packages/core/src/Layout/XDSLayoutContent.tsx+++ b/packages/core/src/Layout/XDSLayoutContent.tsx@@ -6,7 +6,7 @@* with automatic scroll containment and context-aware padding.** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Layout/XDSLayout/README.md+ * - /packages/core/src/Layout/Layout.doc.mjs* - /apps/storybook/stories/Layout.stories.tsx*/diff --git a/packages/core/src/Layout/XDSLayoutFooter.tsx b/packages/core/src/Layout/XDSLayoutFooter.tsxindex fe1b61bec5..7991464537 100644--- a/packages/core/src/Layout/XDSLayoutFooter.tsx+++ b/packages/core/src/Layout/XDSLayoutFooter.tsx@@ -6,7 +6,7 @@* pagination, status bars, or any fixed-height content at the bottom of a layout.** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Layout/XDSLayout/README.md+ * - /packages/core/src/Layout/Layout.doc.mjs* - /apps/storybook/stories/Layout.stories.tsx*/diff --git a/packages/core/src/Layout/XDSLayoutHeader.tsx b/packages/core/src/Layout/XDSLayoutHeader.tsxindex 3138395944..1c82b317a7 100644--- a/packages/core/src/Layout/XDSLayoutHeader.tsx+++ b/packages/core/src/Layout/XDSLayoutHeader.tsx@@ -6,7 +6,7 @@* toolbar areas, or any fixed-height content at the top of a layout.** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Layout/XDSLayout/README.md+ * - /packages/core/src/Layout/Layout.doc.mjs* - /apps/storybook/stories/Layout.stories.tsx*/diff --git a/packages/core/src/Layout/XDSLayoutPanel.tsx b/packages/core/src/Layout/XDSLayoutPanel.tsxindex 5fad27f3c1..7906021573 100644--- a/packages/core/src/Layout/XDSLayoutPanel.tsx+++ b/packages/core/src/Layout/XDSLayoutPanel.tsx@@ -6,7 +6,7 @@* settings sidebars, detail panels, or any fixed-width side content.** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Layout/XDSLayout/README.md+ * - /packages/core/src/Layout/Layout.doc.mjs* - /apps/storybook/stories/Layout.stories.tsx*/diff --git a/packages/core/src/Layout/XDSLayoutSlotsContext.ts b/packages/core/src/Layout/XDSLayoutSlotsContext.tsindex 5decd7ef31..6551eddfef 100644--- a/packages/core/src/Layout/XDSLayoutSlotsContext.ts+++ b/packages/core/src/Layout/XDSLayoutSlotsContext.ts@@ -5,7 +5,7 @@* @position Context for layout slot information** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Layout/XDSLayout/README.md+ * - /packages/core/src/Layout/Layout.doc.mjs* - /packages/core/src/Layout/XDSLayout/index.ts*/diff --git a/packages/core/src/Layout/container.stylex.ts b/packages/core/src/Layout/container.stylex.tsindex 6669d8c846..bafb8545f9 100644--- a/packages/core/src/Layout/container.stylex.ts+++ b/packages/core/src/Layout/container.stylex.ts@@ -4,7 +4,7 @@* @output StyleX utility for layout container styling* @position Layout utility; used by XDSCard, XDSSection components*- * SYNC: When modified, update /packages/core/src/Layout/README.md+ * SYNC: When modified, update /packages/core/src/Layout/Layout.doc.mjs*/import * as stylex from '@stylexjs/stylex';diff --git a/packages/core/src/Layout/edgeCompensation.stylex.ts b/packages/core/src/Layout/edgeCompensation.stylex.tsindex 03e39eddd4..f1115647df 100644--- a/packages/core/src/Layout/edgeCompensation.stylex.ts+++ b/packages/core/src/Layout/edgeCompensation.stylex.ts@@ -41,7 +41,7 @@* by Divider and Section for edge-to-edge bleeds in both directions — we don't* want to overload it with a value that only represents one axis.*- * SYNC: When modified, update /packages/core/src/Layout/README.md+ * SYNC: When modified, update /packages/core/src/Layout/Layout.doc.mjs*/import * as stylex from '@stylexjs/stylex';diff --git a/packages/core/src/Layout/index.ts b/packages/core/src/Layout/index.tsindex 1b08d6e65b..b837246fbd 100644--- a/packages/core/src/Layout/index.ts+++ b/packages/core/src/Layout/index.ts@@ -4,7 +4,7 @@* @output Exports XDS layout system* @position Entry point for @xds/core/Layout*- * SYNC: When modified, update /packages/core/src/Layout/README.md+ * SYNC: When modified, update /packages/core/src/Layout/Layout.doc.mjs*/// Container utilitydiff --git a/packages/core/src/Link/Link.doc.mjs b/packages/core/src/Link/Link.doc.mjsnew file mode 100644index 0000000000..4b4822894e--- /dev/null+++ b/packages/core/src/Link/Link.doc.mjs@@ -0,0 +1,214 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Link',+ description:+ 'XDSLink component for styled anchor links with multiple variants and features, plus polymorphic link infrastructure for rendering custom link components (Next.js Link, React Router Link, etc.).',+ features: [+ "Color control: Uses XDSText color prop ('active' default, 'secondary', 'inherit', etc.)",+ 'External links: Opens in new tab with external link icon',+ 'Tooltip support: Display tooltip text on hover',+ 'Underline control: Always show underline or only on hover',+ 'Inline support: Inherits parent font styles when used within text',+ 'Standalone mode: Applies base font sizing for independent links',+ 'Disabled state: Visual and interaction disabled',+ 'Focus visible: Accessible focus outline',+ 'Polymorphic link: Render as a custom component via `as` prop or XDSLinkProvider',+ ],+ examples: [+ {+ label: 'Basic link',+ code: '<XDSLink label="Documentation" href="/docs">Documentation</XDSLink>',+ },+ {+ label: 'External link (opens in new tab with icon)',+ code: '<XDSLink label="GitHub" href="https://github.com" isExternalLink>GitHub</XDSLink>',+ },+ {+ label: 'Link with tooltip',+ code: `<XDSLink label="Settings" href="/settings" tooltip="Configure your preferences">+ Settings+</XDSLink>`,+ },+ {+ label: 'Always underlined link',+ code: '<XDSLink label="Privacy Policy" href="/privacy" hasUnderline>Privacy Policy</XDSLink>',+ },+ {+ label: 'Inline within text (inherits parent font styles)',+ code: '<XDSText>Read the <XDSLink label="docs" href="/docs">documentation</XDSLink> for more info.</XDSText>',+ },+ {+ label: 'Standalone link',+ code: '<XDSLink label="Settings" href="/settings" isStandalone>Settings</XDSLink>',+ },+ {+ label: 'Disabled link',+ code: '<XDSLink label="Disabled" href="/disabled" isDisabled>Disabled Link</XDSLink>',+ },+ {+ label: 'Provider (global default) — Next.js',+ code: `import Link from 'next/link';+import {XDSLinkProvider} from '@xds/core/Link';++<XDSLinkProvider component={Link}>+ <App />+</XDSLinkProvider>`,+ },+ {+ label: 'Per-component override (as prop)',+ code: `import {Link as RouterLink} from 'react-router-dom';++<XDSLink label="Docs" href="/docs" as={RouterLink}>+ Docs+</XDSLink>`,+ },+ {+ label: 'Hook: useXDSLinkComponent',+ code: `import {useXDSLinkComponent} from '@xds/core/Link';++function MyComponent({as}: {as?: XDSLinkComponentType}) {+ const LinkComponent = useXDSLinkComponent(as);+ return <LinkComponent href="/foo">Click me</LinkComponent>;+}`,+ },+ ],+ theming: {+ componentKey: 'link',+ surfaces: [{name: 'root', description: 'Root anchor element styles'}],+ },+ notes: [+ 'By default, links inherit font family, size, line-height, and weight from parent elements',+ 'Use isStandalone prop when the link is not inline within other text content',+ 'isExternalLink automatically sets target="_blank" and rel="noopener noreferrer" for security',+ 'Disabled state uses aria-disabled and pointer-events: none for accessibility',+ 'Tooltip wraps the link in XDSTooltip component when provided',+ 'XDSLinkComponentType is React.ElementType, allowing both string tags ("a") and custom components',+ 'XDSLinkContext is separated from XDSLinkProvider (mirrors ThemeContext/XDSTheme pattern) so consumers can import the context without the full provider',+ 'XDSLinkProvider memoizes its context value to prevent unnecessary re-renders',+ 'Polymorphic link resolution order: (1) per-component as prop (highest priority), (2) XDSLinkProvider context, (3) native <a> element (default)',+ 'All XDS components that render links (XDSLink, XDSTopNavItem, XDSSideNavItem, XDSBreadcrumbItem, XDSTab) support rendering as a custom link component',+ ],+ components: [+ {+ name: 'XDSLink',+ description:+ 'Styled anchor link with variants, external link support, and polymorphic rendering.',+ props: [+ {+ name: 'as',+ type: 'XDSLinkComponentType',+ description: 'Custom component to render instead of <a>',+ },+ {+ name: 'label',+ type: 'string',+ description: 'Accessible label',+ required: true,+ },+ {+ name: 'href',+ type: 'string',+ description: 'Link destination URL',+ },+ {+ name: 'hasUnderline',+ type: 'boolean',+ description: 'Always show underline',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Disables the link',+ default: 'false',+ },+ {+ name: 'isExternalLink',+ type: 'boolean',+ description: 'Opens in new tab with external icon',+ default: 'false',+ },+ {+ name: 'target',+ type: 'string',+ description: 'Where to open linked document',+ },+ {+ name: 'onClick',+ type: 'MouseEventHandler',+ description: 'Click event handler',+ },+ {+ name: 'tooltip',+ type: 'string',+ description: 'Tooltip text displayed on hover',+ },+ {+ name: 'isStandalone',+ type: 'boolean',+ description: 'Applies base font sizing',+ default: 'false',+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Link content',+ required: true,+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: '<XDSLink label="Documentation" href="/docs">Documentation</XDSLink>',+ },+ {+ label: 'External link',+ code: '<XDSLink label="GitHub" href="https://github.com" isExternalLink>GitHub</XDSLink>',+ },+ {+ label: 'With tooltip',+ code: `<XDSLink label="Settings" href="/settings" tooltip="Configure your preferences">+ Settings+</XDSLink>`,+ },+ {+ label: 'With custom component (as prop)',+ code: `<XDSLink label="Docs" href="/docs" as={RouterLink}>+ Docs+</XDSLink>`,+ },+ ],+ },+ {+ name: 'XDSLinkProvider',+ description:+ 'Provider that sets the default link component for all XDS link components in the subtree.',+ props: [+ {+ name: 'component',+ type: 'XDSLinkComponentType',+ description: 'Component to use for all link elements',+ required: true,+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Subtree',+ required: true,+ },+ ],+ examples: [+ {+ label: 'With Next.js Link',+ code: `import Link from 'next/link';+import {XDSLinkProvider} from '@xds/core/Link';++<XDSLinkProvider component={Link}>+ <App />+</XDSLinkProvider>`,+ },+ ],+ },+ ],+};diff --git a/packages/core/src/Link/README.md b/packages/core/src/Link/README.mddeleted file mode 100644index 60b32eef7b..0000000000--- a/packages/core/src/Link/README.md+++ /dev/null@@ -1,201 +0,0 @@-# Link--XDSLink component for styled anchor links with multiple variants and features, plus polymorphic link infrastructure for rendering custom link components (Next.js Link, React Router Link, etc.).--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Variants**: `default`, `subtle`, `inherit`-- **External links**: Opens in new tab with external link icon-- **Tooltip support**: Display tooltip text on hover-- **Underline control**: Always show underline or only on hover-- **Inline support**: Inherits parent font styles when used within text-- **Standalone mode**: Applies base font sizing for independent links-- **Disabled state**: Visual and interaction disabled-- **Focus visible**: Accessible focus outline-- **Polymorphic link**: Render as a custom component via `as` prop or `XDSLinkProvider`--## Components--### XDSLink--Styled anchor link with variants, external link support, and polymorphic rendering.--```tsx-<XDSLink label="Documentation" href="/docs">Documentation</XDSLink>-```--| Prop | Type | Default | Description |-| ---------------- | ------------------------------------ | ----------- | ------------------------------------------- |-| `as` | `XDSLinkComponentType` | — | Custom component to render instead of `<a>` |-| `label` | `string` | — | Accessible label (required) |-| `href` | `string` | — | Link destination URL |-| `variant` | `'default' \| 'subtle' \| 'inherit'` | `'default'` | Visual style variant |-| `hasUnderline` | `boolean` | `false` | Always show underline |-| `isDisabled` | `boolean` | `false` | Disables the link |-| `isExternalLink` | `boolean` | `false` | Opens in new tab with external icon |-| `target` | `string` | — | Where to open linked document |-| `onClick` | `MouseEventHandler` | — | Click event handler |-| `tooltip` | `string` | — | Tooltip text displayed on hover |-| `isStandalone` | `boolean` | `false` | Applies base font sizing |-| `children` | `ReactNode` | — | Link content (required) |--### XDSLinkProvider--Provider that sets the default link component for all XDS link components in the subtree.--```tsx-<XDSLinkProvider component={Link}>- <App />-</XDSLinkProvider>-```--| Prop | Type | Default | Description |-| ----------- | ---------------------- | ------- | ------------------------------------------------ |-| `component` | `XDSLinkComponentType` | — | Component to use for all link elements (required)|-| `children` | `ReactNode` | — | Subtree |--## Usage--```tsx-import { XDSLink } from '@xds/core/Link';--// Basic link-<XDSLink label="Documentation" href="/docs">Documentation</XDSLink>--// External link (opens in new tab with icon)-<XDSLink label="GitHub" href="https://github.com" isExternalLink>GitHub</XDSLink>--// Link with tooltip-<XDSLink label="Settings" href="/settings" tooltip="Configure your preferences">- Settings-</XDSLink>--// Always underlined link-<XDSLink label="Privacy Policy" href="/privacy" hasUnderline>Privacy Policy</XDSLink>--// Inline within text (inherits parent font styles)-<XDSText>Read the <XDSLink label="docs" href="/docs">documentation</XDSLink> for more info.</XDSText>--// Standalone link-<XDSLink label="Settings" href="/settings" isStandalone>Settings</XDSLink>--// Subtle variant-<XDSLink label="Privacy" href="/privacy" variant="subtle">Privacy Policy</XDSLink>--// Disabled link-<XDSLink label="Disabled" href="/disabled" isDisabled>Disabled Link</XDSLink>-```--## Polymorphic Link--All XDS components that render links (`XDSLink`, `XDSTopNavItem`, `XDSSideNavItem`, `XDSBreadcrumbItem`, `XDSTab`) support rendering as a custom link component instead of the native `<a>` element. This enables framework-specific routing (Next.js, React Router, etc.).--### Provider (global default)--Wrap your app in `XDSLinkProvider` to set the default link component for all XDS components in the subtree:--```tsx-import Link from 'next/link';-import {XDSLinkProvider} from '@xds/core/Link';--<XDSLinkProvider component={Link}>- <App />-</XDSLinkProvider>;-```--### Per-component override (`as` prop)--Override the provider for a single component using the `as` prop:--```tsx-import {Link as RouterLink} from 'react-router-dom';--<XDSLink label="Docs" href="/docs" as={RouterLink}>- Docs-</XDSLink>;-```--### Resolution order--1. Per-component `as` prop (highest priority)-2. `XDSLinkProvider` context-3. Native `<a>` element (default)--### Hook: `useXDSLinkComponent`--For custom components that need to resolve the link component:--```tsx-import {useXDSLinkComponent} from '@xds/core/Link';--function MyComponent({as}: {as?: XDSLinkComponentType}) {- const LinkComponent = useXDSLinkComponent(as);- return <LinkComponent href="/foo">Click me</LinkComponent>;-}-```--## Props--| Prop | Type | Default | Description |-| ---------------- | ------------------------------------ | ----------- | ------------------------------------------- |-| `as` | `XDSLinkComponentType` | — | Custom component to render instead of `<a>` |-| `label` | `string` | — | Accessible label (required) |-| `href` | `string` | — | Link destination URL |-| `variant` | `'default' \| 'subtle' \| 'inherit'` | `'default'` | Visual style variant |-| `hasUnderline` | `boolean` | `false` | Always show underline |-| `isDisabled` | `boolean` | `false` | Disables the link |-| `isExternalLink` | `boolean` | `false` | Opens in new tab with external icon |-| `target` | `string` | — | Where to open linked document |-| `onClick` | `MouseEventHandler` | — | Click event handler |-| `tooltip` | `string` | — | Tooltip text displayed on hover |-| `isStandalone` | `boolean` | `false` | Applies base font sizing |-| `children` | `ReactNode` | — | Link content (required) |--## Theming--Themes can override `Link` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- link: {- root: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------- | -------------------------- |-| `root` | Root anchor element styles |--## Files--| File | Role | Purpose |-| ------------------------------ | -------- | ------------------------------------------------ |-| `index.ts` | Entry | Exports all public Link components, hooks, types |-| `XDSLink.tsx` | Core | XDSLink component implementation |-| `XDSLink.test.tsx` | Test | Unit tests for XDSLink component |-| `XDSLinkProvider.tsx` | Provider | Sets default link component for subtree |-| `XDSLinkContext.ts` | Context | React context definition for link provider |-| `useXDSLinkComponent.ts` | Hook | Resolves link component (as > provider > `<a>`) |-| `useXDSLinkComponent.test.tsx` | Test | Unit tests for hook and provider |-| `types.ts` | Types | Shared XDSLinkComponentType definition |--## Implementation Notes--- `XDSLinkVariant` type is derived from the `variants` StyleX object using `keyof typeof variants`-- By default, links inherit font family, size, line-height, and weight from parent elements-- Use `isStandalone` prop when the link is not inline within other text content-- `isExternalLink` automatically sets `target="_blank"` and `rel="noopener noreferrer"` for security-- Disabled state uses `aria-disabled` and `pointer-events: none` for accessibility-- Tooltip wraps the link in `XDSTooltip` component when provided-- `XDSLinkComponentType` is `React.ElementType`, allowing both string tags (`'a'`) and custom components-- `XDSLinkContext` is separated from `XDSLinkProvider` (mirrors `ThemeContext`/`XDSTheme` pattern) so consumers can import the context without the full provider-- `XDSLinkProvider` memoizes its context value to prevent unnecessary re-rendersdiff --git a/packages/core/src/Link/XDSLink.tsx b/packages/core/src/Link/XDSLink.tsxindex 9604513704..5f8ff12ee0 100644--- a/packages/core/src/Link/XDSLink.tsx+++ b/packages/core/src/Link/XDSLink.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSLink.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Link/README.md (props table, features, implementation notes)+ * - /packages/core/src/Link/Link.doc.mjs (props table, features, implementation notes)* - /packages/core/src/Link/XDSLink.test.tsx (tests for new/changed behavior)* - /packages/core/src/Link/index.ts (exports if types change)* - /apps/storybook/stories/Link.stories.tsx (storybook stories)diff --git a/packages/core/src/Link/XDSLinkContext.ts b/packages/core/src/Link/XDSLinkContext.tsindex 7bc120deb1..5187527ed7 100644--- a/packages/core/src/Link/XDSLinkContext.ts+++ b/packages/core/src/Link/XDSLinkContext.ts@@ -12,7 +12,7 @@* - /packages/core/src/Link/XDSLinkProvider.tsx* - /packages/core/src/Link/useXDSLinkComponent.ts* - /packages/core/src/Link/index.ts- * - /packages/core/src/Link/README.md+ * - /packages/core/src/Link/Link.doc.mjs*/'use client';diff --git a/packages/core/src/Link/XDSLinkProvider.tsx b/packages/core/src/Link/XDSLinkProvider.tsxindex a27957f04d..79f00d7384 100644--- a/packages/core/src/Link/XDSLinkProvider.tsx+++ b/packages/core/src/Link/XDSLinkProvider.tsx@@ -18,7 +18,7 @@** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Link/index.ts- * - /packages/core/src/Link/README.md+ * - /packages/core/src/Link/Link.doc.mjs*/'use client';diff --git a/packages/core/src/Link/index.ts b/packages/core/src/Link/index.tsindex c8e94e9789..9544c7dc3f 100644--- a/packages/core/src/Link/index.ts+++ b/packages/core/src/Link/index.ts@@ -4,7 +4,7 @@* @output Exports all public Link components, hooks, and types* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/Link/README.md+ * SYNC: When modified, update this header and /packages/core/src/Link/Link.doc.mjs*/export {XDSLink} from './XDSLink';diff --git a/packages/core/src/Link/types.ts b/packages/core/src/Link/types.tsindex f3e26440cf..4c0362e4f4 100644--- a/packages/core/src/Link/types.ts+++ b/packages/core/src/Link/types.ts@@ -6,7 +6,7 @@** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Link/index.ts- * - /packages/core/src/Link/README.md+ * - /packages/core/src/Link/Link.doc.mjs*/import type {ElementType} from 'react';diff --git a/packages/core/src/Link/useXDSLinkComponent.ts b/packages/core/src/Link/useXDSLinkComponent.tsindex 5f5f497f0e..db27235b0a 100644--- a/packages/core/src/Link/useXDSLinkComponent.ts+++ b/packages/core/src/Link/useXDSLinkComponent.ts@@ -8,7 +8,7 @@** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Link/index.ts- * - /packages/core/src/Link/README.md+ * - /packages/core/src/Link/Link.doc.mjs*/'use client';diff --git a/packages/core/src/List/List.doc.mjs b/packages/core/src/List/List.doc.mjsnew file mode 100644index 0000000000..6e3a746db9--- /dev/null+++ b/packages/core/src/List/List.doc.mjs@@ -0,0 +1,183 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'List',+ description:+ 'Vertical list component for rendering collections of items with consistent spacing, dividers, and marker styles. Uses a composition model: XDSList wraps XDSListItem sub-components.',+ features: [+ 'Composition model — XDSList wraps XDSListItem sub-components',+ 'Density variants: compact, balanced, spacious',+ 'Optional dividers between items',+ 'Optional header associated via aria-labelledby',+ 'List marker styles: none, disc, decimal (renders <ol>), circle',+ 'Interactive items via invisible button or anchor pattern',+ 'Start and end content slots (icon, avatar, badge, chevron)',+ ],+ examples: [+ {+ label: 'Basic list',+ code: `<XDSList>+ <XDSListItem label="Notifications" description="Manage your alerts" />+ <XDSListItem label="Privacy" description="Control your data" />+</XDSList>`,+ },+ {+ label: 'With dividers and header',+ code: `<XDSList hasDividers header={<strong>Team Members</strong>}>+ <XDSListItem+ label="Alice Johnson"+ description="Engineering"+ startContent={<XDSIcon icon={UserIcon} />}+ />+ <XDSListItem+ label="Bob Smith"+ description="Design"+ startContent={<XDSIcon icon={UserIcon} />}+ />+</XDSList>`,+ },+ {+ label: 'Interactive items',+ code: `<XDSList>+ <XDSListItem label="Settings" onClick={() => navigate('/settings')} />+ <XDSListItem label="Docs" href="/docs" target="_blank" />+</XDSList>`,+ },+ {+ label: 'Ordered list',+ code: `<XDSList listStyle="decimal">+ <XDSListItem label="First step" />+ <XDSListItem label="Second step" />+</XDSList>`,+ },+ ],+ accessibility: [+ 'Semantic <ul> / <ol> with <li> elements',+ 'role="list" added when listStyle=\'none\' (Safari fix for list semantics removed by CSS list-style:none)',+ 'aria-labelledby links the header element to the list',+ 'aria-selected on selected items',+ 'aria-disabled on disabled items',+ 'Dividers are aria-hidden="true"',+ 'Interactive items are keyboard-focusable via Tab',+ ],+ notes: [+ 'Invisible button pattern: when onClick is provided, an invisible <button> wraps the label + description for accessibility. The <li> is the visual container with hover/press styles. startContent and endContent are siblings to the button (not inside it). Container click fires onClick unless the click originated from an interactive child. :focus-within on the container shows the focus outline.',+ 'When href is provided instead of onClick, the same invisible pattern uses an <a> element.',+ ],+ components: [+ {+ name: 'XDSList',+ description: 'List container with density, dividers, and header support.',+ examples: [+ {+ label: 'With dividers and header',+ code: `<XDSList hasDividers header={<strong>Team Members</strong>}>+ <XDSListItem label="Alice" description="Engineering" />+ <XDSListItem label="Bob" description="Design" />+</XDSList>`,+ },+ ],+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'List items (XDSListItem components).',+ },+ {+ name: 'density',+ type: "'compact' | 'balanced' | 'spacious'",+ description: 'Spacing density for items.',+ default: "'balanced'",+ },+ {+ name: 'hasDividers',+ type: 'boolean',+ description: 'Show dividers between items.',+ default: 'false',+ },+ {+ name: 'header',+ type: 'ReactNode',+ description:+ 'Header content, associated with the list via aria-labelledby.',+ },+ {+ name: 'listStyle',+ type: "'none' | 'disc' | 'decimal' | 'circle'",+ description:+ "List marker style. 'decimal' renders an <ol> element instead of <ul>.",+ default: "'none'",+ },+ ],+ },+ {+ name: 'XDSListItem',+ description:+ 'List item with label, description, start/end content slots, and interactive patterns.',+ examples: [+ {+ label: 'With icon and click handler',+ code: `<XDSListItem+ label="Settings"+ description="Manage your preferences"+ startContent={<XDSIcon icon={CogIcon} />}+ onClick={() => navigate('/settings')}+/>`,+ },+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Primary text.',+ required: true,+ },+ {+ name: 'description',+ type: 'string',+ description: 'Secondary text displayed below the label.',+ },+ {+ name: 'startContent',+ type: 'ReactNode',+ description:+ 'Content rendered before the label area (e.g. icon, avatar).',+ },+ {+ name: 'endContent',+ type: 'ReactNode',+ description:+ 'Content rendered after the label area (e.g. badge, chevron).',+ },+ {+ name: 'onClick',+ type: '(e: MouseEvent) => void',+ description: 'Click handler; enables the invisible button pattern.',+ },+ {+ name: 'href',+ type: 'string',+ description: 'Link URL; enables the invisible anchor pattern.',+ },+ {+ name: 'target',+ type: 'string',+ description:+ 'Link target attribute, only applicable when href is provided.',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Disabled state; sets aria-disabled on the item.',+ default: 'false',+ },+ {+ name: 'isSelected',+ type: 'boolean',+ description: 'Selected state; sets aria-selected on the item.',+ default: 'false',+ },+ ],+ },+ ],+};diff --git a/packages/core/src/List/README.md b/packages/core/src/List/README.mddeleted file mode 100644index 87705af11d..0000000000--- a/packages/core/src/List/README.md+++ /dev/null@@ -1,130 +0,0 @@-# XDSList--Vertical list component for rendering collections of items with consistent spacing, dividers, and marker styles. Uses a composition model: `XDSList` wraps `XDSListItem` sub-components.--## Files--<!-- SYNC: Update when files are added/removed -->--| File | Purpose |-| -------------------- | ------------------------------------ |-| `XDSList.tsx` | List container component |-| `XDSListItem.tsx` | List item component |-| `XDSListContext.tsx` | Internal context for density sharing |-| `XDSList.test.tsx` | Unit tests |-| `index.ts` | Public exports |-| `README.md` | This documentation |--## Usage--```tsx-import {XDSList, XDSListItem} from '@xds/core';--// Basic list-<XDSList>- <XDSListItem label="Notifications" description="Manage your alerts" />- <XDSListItem label="Privacy" description="Control your data" />-</XDSList>--// With dividers and header-<XDSList hasDividers header={<strong>Team Members</strong>}>- <XDSListItem- label="Alice Johnson"- description="Engineering"- startContent={<XDSIcon icon={UserIcon} />}- />- <XDSListItem- label="Bob Smith"- description="Design"- startContent={<XDSIcon icon={UserIcon} />}- />-</XDSList>--// Interactive items-<XDSList>- <XDSListItem label="Settings" onClick={() => navigate('/settings')} />- <XDSListItem label="Docs" href="/docs" target="_blank" />-</XDSList>--// Ordered list-<XDSList listStyle="decimal">- <XDSListItem label="First step" />- <XDSListItem label="Second step" />-</XDSList>-```--### XDSList--List container with density, dividers, and header support.--```tsx-<XDSList hasDividers header={<strong>Team Members</strong>}>- <XDSListItem label="Alice" description="Engineering" />- <XDSListItem label="Bob" description="Design" />-</XDSList>-```--| Prop | Type | Default | Description |-| ------------- | ------------------------------------------- | ------------ | ------------------------------------------------ |-| `children` | `ReactNode` | — | List items (XDSListItem components) |-| `density` | `'compact' \| 'balanced' \| 'spacious'` | `'balanced'` | Spacing density for items |-| `hasDividers` | `boolean` | `false` | Show dividers between items |-| `header` | `ReactNode` | — | Header content, associated via `aria-labelledby` |-| `listStyle` | `'none' \| 'disc' \| 'decimal' \| 'circle'` | `'none'` | List marker style. `'decimal'` renders `<ol>` |-| `xstyle` | `StyleXStyles` | — | Style overrides |-| `data-testid` | `string` | — | Test ID |--### XDSListItem--List item with label, description, start/end content slots, and interactive patterns.--```tsx-<XDSListItem- label="Settings"- description="Manage your preferences"- startContent={<XDSIcon icon={CogIcon} />}- onClick={() => navigate('/settings')}-/>-```--| Prop | Type | Default | Description |-| -------------- | ------------------------- | ------- | ------------------------------------------------ |-| `label` | `string` | — | Primary text (required) |-| `description` | `string` | — | Secondary text below label |-| `startContent` | `ReactNode` | — | Content before label area (icon, avatar) |-| `endContent` | `ReactNode` | — | Content after label area (badge, chevron) |-| `onClick` | `(e: MouseEvent) => void` | — | Click handler (enables invisible button pattern) |-| `href` | `string` | — | Link URL (enables invisible anchor pattern) |-| `target` | `string` | — | Link target (only with `href`) |-| `isDisabled` | `boolean` | `false` | Disabled state |-| `isSelected` | `boolean` | `false` | Selected state (`aria-selected`) |-| `xstyle` | `StyleXStyles` | — | Style overrides |-| `data-testid` | `string` | — | Test ID |--## Interactive Pattern--When `onClick` is provided, XDSListItem uses the **invisible button pattern**:--```-┌─ li (container, :focus-within outline, click area) ──────────┐-│ [startContent] [button.invisible(label + desc)] [endContent] │-└──────────────────────────────────────────────────────────────────┘-```--- The `<li>` is the visual container with hover/press styles-- An invisible `<button>` wraps the label + description for accessibility-- `startContent` and `endContent` are siblings to the button (not inside it)-- Container click fires `onClick` unless the click originated from an interactive child-- `:focus-within` on the container shows the focus outline--When `href` is provided, the same pattern uses an invisible `<a>` instead.--## Accessibility--- Semantic `<ul>` / `<ol>` with `<li>` elements-- `role="list"` added when `listStyle='none'` (Safari fix)-- `aria-labelledby` links header to list-- `aria-selected` on selected items-- `aria-disabled` on disabled items-- Dividers are `aria-hidden="true"`-- Interactive items are keyboard-focusable via Tabdiff --git a/packages/core/src/List/XDSList.tsx b/packages/core/src/List/XDSList.tsxindex 46c37aec8f..318eb878ae 100644--- a/packages/core/src/List/XDSList.tsx+++ b/packages/core/src/List/XDSList.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSList.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/List/README.md+ * - /packages/core/src/List/List.doc.mjs* - /packages/core/src/List/XDSList.test.tsx* - /packages/core/src/List/index.ts* - /apps/storybook/stories/List.stories.tsxdiff --git a/packages/core/src/List/XDSListItem.tsx b/packages/core/src/List/XDSListItem.tsxindex e5d5f86ca4..4896bfc2c0 100644--- a/packages/core/src/List/XDSListItem.tsx+++ b/packages/core/src/List/XDSListItem.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by XDSList, index.ts, tested by XDSList.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/List/README.md+ * - /packages/core/src/List/List.doc.mjs* - /packages/core/src/List/XDSList.test.tsx* - /packages/core/src/List/index.ts* - /apps/storybook/stories/List.stories.tsxdiff --git a/packages/core/src/List/index.ts b/packages/core/src/List/index.tsindex 1ebd48cd4d..f3d283371b 100644--- a/packages/core/src/List/index.ts+++ b/packages/core/src/List/index.ts@@ -4,7 +4,7 @@* @output Exports XDSList, XDSListItem components and their props/types* @position Package entry point for List*- * SYNC: When modified, update /packages/core/src/List/README.md+ * SYNC: When modified, update /packages/core/src/List/List.doc.mjs*/export {XDSList} from './XDSList';diff --git a/packages/core/src/MobileNav/MobileNav.doc.mjs b/packages/core/src/MobileNav/MobileNav.doc.mjsnew file mode 100644index 0000000000..bbb8828834--- /dev/null+++ b/packages/core/src/MobileNav/MobileNav.doc.mjs@@ -0,0 +1,150 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'MobileNav',+ description:+ 'Slide-out drawer overlay for mobile navigation. The mobile counterpart to XDSSideNav — accepts the same children (XDSSideNavSection, XDSSideNavItem, or any ReactNode).',+ props: [+ {+ name: 'isOpen',+ type: 'boolean',+ description: 'Whether the drawer is open.',+ required: true,+ },+ {+ name: 'onOpenChange',+ type: '(isOpen: boolean) => void',+ description:+ 'Called when the drawer visibility changes (backdrop click, Escape key, or close button).',+ required: true,+ },+ {+ name: 'children',+ type: 'ReactNode',+ description:+ 'Drawer content — typically XDSSideNavSection/XDSSideNavItem, or any ReactNode.',+ required: true,+ },+ {+ name: 'title',+ type: 'string',+ description: 'Optional title shown at the top of the drawer.',+ },+ {+ name: 'width',+ type: 'number',+ description:+ 'Drawer width in pixels. Capped at 85vw to prevent overflow on small screens.',+ default: '280',+ },+ {+ name: 'side',+ type: "'start' | 'end'",+ description:+ 'Which side the drawer slides from. Start is left in LTR, right in RTL.',+ default: "'start'",+ },+ ],+ examples: [+ {+ label: 'Basic hamburger menu',+ code: `const [isOpen, setIsOpen] = useState(false);++<XDSButton+ label="Menu"+ icon={<MenuIcon />}+ variant="ghost"+ onClick={() => setIsOpen(true)}+/>++<XDSMobileNav+ isOpen={isOpen}+ onOpenChange={() => setIsOpen(false)}+ title="Navigation"+>+ <XDSSideNavSection title="Main">+ <XDSSideNavItem label="Dashboard" href="/dashboard" isSelected />+ <XDSSideNavItem label="Analytics" href="/analytics" />+ <XDSSideNavItem label="Settings" href="/settings" />+ </XDSSideNavSection>+</XDSMobileNav>`,+ },+ {+ label: 'Responsive sidebar/drawer pattern',+ code: `const isMobile = useMediaQuery('(max-width: 768px)');+const [drawerOpen, setDrawerOpen] = useState(false);++const navSections = (+ <>+ <XDSSideNavSection title="Main">+ <XDSSideNavItem label="Dashboard" href="/" isSelected />+ <XDSSideNavItem label="Projects" href="/projects" />+ </XDSSideNavSection>+ <XDSSideNavSection title="Settings">+ <XDSSideNavItem label="General" href="/settings" />+ <XDSSideNavItem label="Security" href="/security" />+ </XDSSideNavSection>+ </>+);++{isMobile ? (+ <>+ <XDSButton+ label="Menu"+ icon={<MenuIcon />}+ variant="ghost"+ onClick={() => setDrawerOpen(true)}+ />+ <XDSMobileNav+ isOpen={drawerOpen}+ onOpenChange={() => setDrawerOpen(false)}+ title="My App"+ >+ {navSections}+ </XDSMobileNav>+ </>+) : (+ <XDSSideNav>{navSections}</XDSSideNav>+)}`,+ },+ {+ label: 'Shared children with XDSSideNav',+ code: `const sections = (+ <XDSSideNavSection title="Main">+ <XDSSideNavItem label="Home" href="/" />+ <XDSSideNavItem label="Settings" href="/settings" />+ </XDSSideNavSection>+);++// Desktop: sidebar+<XDSSideNav>{sections}</XDSSideNav>++// Mobile: drawer+<XDSMobileNav isOpen={open} onOpenChange={close}>{sections}</XDSMobileNav>`,+ },+ ],+ features: [+ 'Native <dialog> element with showModal() for top-layer rendering — no z-index stacking issues',+ 'Animated slide-in from start or end edge with backdrop fade',+ 'Shares children with XDSSideNav — extract nav sections into a variable and render in both',+ 'RTL-aware: automatically mirrors slide direction for right-to-left layouts',+ 'Respects prefers-reduced-motion: reduces animation duration',+ ],+ accessibility: [+ 'Uses native <dialog> with showModal() for correct ARIA modal semantics.',+ "aria-label set to title or 'Navigation' as fallback.",+ 'Focus trapping provided by showModal() (browser-native).',+ 'Escape key closes via native cancel event.',+ 'Backdrop click closes the drawer.',+ 'Body scroll locked while modal is open.',+ ],+ keyboard:+ 'Escape closes the drawer; Tab/Shift+Tab cycles focus within the drawer (browser-native focus trapping)',+ theming: {+ componentKey: 'mobileNav',+ surfaces: [+ {name: 'root', description: 'Root dialog element styles'},+ {name: 'drawer', description: 'Drawer panel styles'},+ ],+ },+};diff --git a/packages/core/src/MoreMenu/MoreMenu.doc.mjs b/packages/core/src/MoreMenu/MoreMenu.doc.mjsnew file mode 100644index 0000000000..8c861ceec7--- /dev/null+++ b/packages/core/src/MoreMenu/MoreMenu.doc.mjs@@ -0,0 +1,148 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'MoreMenu',+ description:+ 'Overflow menu with a three-dot icon trigger. A convenience wrapper that composes an icon-only XDSButton with a dropdown menu, eliminating the boilerplate of wiring up state management, positioning, and accessibility attributes.',+ props: [+ {+ name: 'items',+ type: 'XDSDropdownMenuOption[]',+ description:+ 'Menu items — data array of actions, dividers, and sections. Same type as XDSDropdownMenu items prop.',+ required: true,+ },+ {+ name: 'label',+ type: 'string',+ description:+ 'Accessible label for the trigger button (aria-label) and tooltip text.',+ default: "'More options'",+ },+ {+ name: 'variant',+ type: 'XDSButtonVariant',+ description: 'Visual style variant of the trigger button.',+ default: "'ghost'",+ },+ {+ name: 'size',+ type: 'XDSButtonSize',+ description: 'Size of the trigger button.',+ default: "'md'",+ },+ {+ name: 'icon',+ type: 'ReactNode',+ description:+ 'Override the default three-dot icon. Accepts any ReactNode.',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Whether the menu trigger is disabled.',+ default: 'false',+ },+ {+ name: 'children',+ type: '(item: XDSDropdownMenuItemData) => ReactNode',+ description:+ 'Custom render function for items. Only called for selectable items (not dividers/sections).',+ },+ ],+ examples: [+ {+ label: 'Minimal actions',+ code: `<XDSMoreMenu+ items={[+ { label: 'Edit', onClick: handleEdit },+ { label: 'Delete', onClick: handleDelete },+ ]}+/>`,+ },+ {+ label: 'Table row actions with icons',+ code: `<XDSMoreMenu+ label="Row actions"+ size="sm"+ items={[+ { label: 'Edit', icon: PencilIcon, onClick: () => handleEdit(row) },+ { type: 'divider' },+ { label: 'Delete', icon: TrashIcon, onClick: () => handleDelete(row) },+ ]}+/>`,+ },+ {+ label: 'With sections',+ code: `<XDSMoreMenu+ label="Document actions"+ items={[+ {+ type: 'section',+ title: 'Actions',+ items: [+ { label: 'Edit', onClick: handleEdit },+ { label: 'Duplicate', onClick: handleDuplicate },+ ],+ },+ {+ type: 'section',+ title: 'Danger zone',+ items: [+ { label: 'Delete', onClick: handleDelete },+ ],+ },+ ]}+/>`,+ },+ {+ label: 'Card header with overflow menu',+ code: `<XDSHStack align="center" justify="between">+ <XDSHeading level={3}>Card Title</XDSHeading>+ <XDSMoreMenu+ items={[+ { label: 'Edit', onClick: handleEdit },+ { label: 'Duplicate', onClick: handleDuplicate },+ { type: 'divider' },+ { label: 'Delete', onClick: handleDelete },+ ]}+ />+</XDSHStack>`,+ },+ {+ label: 'Custom item rendering',+ code: `<XDSMoreMenu+ label="User actions"+ items={actions}+>+ {item => (+ <XDSDropdownMenuItem+ icon={item.icon}+ label={item.label}+ description={item.description}+ />+ )}+</XDSMoreMenu>`,+ },+ ],+ features: [+ "Zero-config defaults: three-dot icon, 'More options' label, ghost variant — just pass items",+ 'Data-driven items: same items prop as XDSDropdownMenu (items, dividers, sections)',+ 'Icon-only trigger: always renders as a square icon button with aria-label',+ 'Tooltip: shows label on hover, hidden when menu is open',+ 'Custom rendering: optional children render function for custom item content',+ ],+ accessibility: [+ 'Proper ARIA roles: menu and menuitem on dropdown elements.',+ 'Trigger button has aria-haspopup="menu" and aria-expanded.',+ 'aria-activedescendant tracks the highlighted menu item.',+ 'Disabled items have aria-disabled set.',+ 'Sections use role="group" with aria-label.',+ ],+ keyboard:+ 'Arrow keys navigate items; Home/End jump to first/last; Enter/Space select highlighted item; Escape closes menu',+ notes: [+ 'For full control over trigger rendering or menu content, compose XDSButton + useXDSLayer + XDSDropdownMenuItem directly.',+ 'Use XDSMoreMenu for icon-only overflow actions in tight spaces (table rows, card headers). Use XDSDropdownMenu for labeled trigger buttons with chevrons.',+ ],+};diff --git a/packages/core/src/NavIcon/NavIcon.doc.mjs b/packages/core/src/NavIcon/NavIcon.doc.mjsnew file mode 100644index 0000000000..fe7e2ecac3--- /dev/null+++ b/packages/core/src/NavIcon/NavIcon.doc.mjs@@ -0,0 +1,50 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'NavIcon',+ description:+ 'Circular icon container with accent background for navigation headers.',+ features: [+ 'Shared — used in both XDSTopNavTitle and XDSPageNavHeader',+ 'Accent background — uses --color-accent with --color-icon-on-media contrast',+ 'Fixed size — renders at the medium (--size-md) design token size',+ ],+ props: [+ {+ name: 'icon',+ type: 'ReactNode',+ description:+ 'The icon element to render inside the circular background. Should be an XDSIcon or similar icon component.',+ required: true,+ },+ ],+ examples: [+ {+ label: 'In top navigation',+ code: `import {CubeIcon} from '@heroicons/react/24/solid';++<XDSTopNavTitle+ title="My App"+ logo={<XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />}+/>`,+ },+ {+ label: 'In side navigation',+ code: `import {CubeIcon} from '@heroicons/react/24/solid';++<XDSPageNavHeader+ icon={<XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />}+ title="My App"+/>`,+ },+ {+ label: 'With HomeIcon',+ code: `import {HomeIcon} from '@heroicons/react/24/solid';++<XDSTopNavTitle+ title="Dashboard"+ logo={<XDSNavIcon icon={<HomeIcon style={{width: 16, height: 16}} />} />}+/>`,+ },+ ],+};diff --git a/packages/core/src/NavIcon/README.md b/packages/core/src/NavIcon/README.mddeleted file mode 100644index c88980c5f8..0000000000--- a/packages/core/src/NavIcon/README.md+++ /dev/null@@ -1,50 +0,0 @@-# /packages/core/src/NavIcon--Circular icon container for navigation headers.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Shared** — used in both XDSTopNavTitle and XDSPageNavHeader-- **Accent background** — uses `--color-accent` with `--color-icon-on-media` contrast-- **Fixed size** — renders at the medium (`--size-md`) design token size--## Usage--```tsx-import {XDSNavIcon} from '@xds/core/NavIcon';-import {CubeIcon} from '@heroicons/react/24/solid';--// In top navigation-<XDSTopNavTitle- title="My App"- logo={<XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />}-/>--// In side navigation-<XDSPageNavHeader- icon={<XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />}- title="My App"-/>-```--## Components--- **XDSNavIcon** — Circular icon container with accent background--## Props--### XDSNavIcon--| Prop | Type | Default | Description |-| ------ | ----------- | ------- | ----------------------- |-| `icon` | `ReactNode` | — | Icon element (required) |--## Files--| File | Role | Purpose |-| --------------------- | ----- | --------------------------- |-| `index.ts` | Entry | Exports component and types |-| `XDSNavIcon.tsx` | Core | Circular icon container |-| `XDSNavIcon.test.tsx` | Test | Unit tests |diff --git a/packages/core/src/NavIcon/XDSNavIcon.tsx b/packages/core/src/NavIcon/XDSNavIcon.tsxindex 65975d71f9..7412d8c4a6 100644--- a/packages/core/src/NavIcon/XDSNavIcon.tsx+++ b/packages/core/src/NavIcon/XDSNavIcon.tsx@@ -5,7 +5,7 @@* @position Shared circular icon container for navigation headers (TopNav, PageNav)** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/NavIcon/README.md+ * - /packages/core/src/NavIcon/NavIcon.doc.mjs* - /packages/core/src/NavIcon/XDSNavIcon.test.tsx* - /packages/core/src/NavIcon/index.ts* - /apps/storybook/stories/TopNav.stories.tsxdiff --git a/packages/core/src/NavIcon/index.ts b/packages/core/src/NavIcon/index.tsindex 9f69801cee..7af743a15d 100644--- a/packages/core/src/NavIcon/index.ts+++ b/packages/core/src/NavIcon/index.ts@@ -4,7 +4,7 @@* @output Exports XDSNavIcon component and types* @position Entry point for NavIcon module*- * SYNC: When modified, update /packages/core/src/NavIcon/README.md+ * SYNC: When modified, update /packages/core/src/NavIcon/NavIcon.doc.mjs*/export {XDSNavIcon} from './XDSNavIcon';diff --git a/packages/core/src/NumberInput/NumberInput.doc.mjs b/packages/core/src/NumberInput/NumberInput.doc.mjsnew file mode 100644index 0000000000..2c97ca7714--- /dev/null+++ b/packages/core/src/NumberInput/NumberInput.doc.mjs@@ -0,0 +1,240 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'NumberInput',+ description:+ 'A number input component for collecting numeric user input with validation.',+ features: [+ 'Label Support — required label for accessibility (can be visually hidden)',+ 'Description — optional description text displayed between the label and input',+ 'Optional/Required Indicators — display "Optional" or "Required" text with bullet separator',+ 'Label Tooltip — optional info icon with tooltip at end of label',+ 'Label Icon — optional icon before the label text',+ 'Accessible — label properly associated with input via htmlFor/id',+ 'Styled with StyleX — uses XDS design tokens for consistent styling',+ 'Size Variants — three sizes (sm, md, lg) for different contexts',+ 'Status Handling — error, warning, and success states with messages',+ 'Number Constraints — support for min, max, and step attributes',+ 'Validated onChange — only calls onChange when the entered value passes validation',+ 'Units Display — optional units suffix (e.g., "%" or "GB")',+ 'Integer Mode — option to restrict to integers only',+ 'Native Controls — uses type="number" for browser step controls',+ 'Event Callbacks — onFocus, onBlur, and onEnter handlers',+ ],+ examples: [+ {+ label: 'Basic',+ code: '<XDSNumberInput label="Quantity" value={quantity} onChange={setQuantity} />',+ },+ {+ label: 'With placeholder',+ code: '<XDSNumberInput label="Age" value={age} onChange={setAge} placeholder="Enter your age" />',+ },+ {+ label: 'With min/max constraints',+ code: '<XDSNumberInput label="Rating" value={rating} onChange={setRating} min={1} max={5} />',+ },+ {+ label: 'With step for decimals',+ code: '<XDSNumberInput label="Price" value={price} onChange={setPrice} min={0} step={0.01} />',+ },+ {+ label: 'With units display',+ code: '<XDSNumberInput label="Discount" value={discount} onChange={setDiscount} units="%" />',+ },+ {+ label: 'Integer only',+ code: '<XDSNumberInput label="Count" value={count} onChange={setCount} isIntegerOnly />',+ },+ {+ label: 'With description',+ code: '<XDSNumberInput label="Quantity" description="Enter the number of items" value={qty} onChange={setQty} />',+ },+ {+ label: 'Optional field',+ code: '<XDSNumberInput label="Phone Extension" isOptional value={ext} onChange={setExt} />',+ },+ {+ label: 'Required field',+ code: '<XDSNumberInput label="Amount" isRequired value={amount} onChange={setAmount} />',+ },+ {+ label: 'With validation status',+ code: `<XDSNumberInput+ label="Age"+ value={age}+ onChange={setAge}+ status={{ type: 'error', message: 'Age must be between 18 and 120' }}+/>`,+ },+ {+ label: 'With event handlers',+ code: `<XDSNumberInput+ label="Search"+ value={search}+ onChange={setSearch}+ onEnter={() => handleSearch()}+ onFocus={() => console.log('focused')}+ onBlur={() => console.log('blurred')}+/>`,+ },+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description:+ 'Label text for the input (always rendered for accessibility).',+ required: true,+ },+ {+ name: 'value',+ type: 'number | null | undefined',+ description: 'Current value of the input.',+ required: true,+ },+ {+ name: 'onChange',+ type: '(value: number) => void',+ description:+ 'Callback fired when input value changes (only on valid input).',+ required: true,+ },+ {+ name: 'size',+ type: "'sm' | 'md' | 'lg'",+ description: 'Size variant.',+ default: "'md'",+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description:+ 'Visually hide the label (still accessible to screen readers).',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Description text displayed between the label and input.',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description:+ 'Whether the field is optional (mutually exclusive with isRequired).',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description:+ 'Whether the field is required (mutually exclusive with isOptional).',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Whether the input is disabled.',+ },+ {+ name: 'placeholder',+ type: 'string',+ description: 'Placeholder text.',+ },+ {+ name: 'labelTooltip',+ type: 'string',+ description:+ 'Tooltip text to display in an info icon at the end of the label.',+ },+ {+ name: 'startIcon',+ type: 'XDSIconType',+ description: 'Icon to display at the start of the input.',+ },+ {+ name: 'labelIcon',+ type: 'XDSIconType',+ description: 'Icon to display before the label text.',+ },+ {+ name: 'status',+ type: "{type: 'error' | 'warning' | 'success', message?: string}",+ description: 'Validation status with optional message.',+ },+ {+ name: 'min',+ type: 'number | null',+ description: 'Minimum value allowed.',+ },+ {+ name: 'max',+ type: 'number | null',+ description: 'Maximum value allowed.',+ },+ {+ name: 'step',+ type: 'number | null',+ description: 'Step increment for the input.',+ default: '1',+ },+ {+ name: 'units',+ type: 'string | null',+ description:+ 'Units text to display at the end of the input (e.g., "%" or "GB").',+ },+ {+ name: 'isIntegerOnly',+ type: 'boolean',+ description: 'Only allow integer values (no floating point).',+ },+ {+ name: 'htmlName',+ type: 'string',+ description: 'HTML name attribute for form submissions.',+ },+ {+ name: 'autoComplete',+ type: 'string',+ description: 'HTML autocomplete attribute.',+ },+ {+ name: 'hasAutoFocus',+ type: 'boolean',+ description: 'Whether to focus the input on mount.',+ },+ {+ name: 'onFocus',+ type: '(e: FocusEvent<HTMLInputElement>) => void',+ description: 'Callback fired when the input receives focus.',+ },+ {+ name: 'onBlur',+ type: '(e: FocusEvent<HTMLInputElement>) => void',+ description: 'Callback fired when the input loses focus.',+ },+ {+ name: 'onEnter',+ type: '() => void',+ description: 'Callback fired when the user presses the Enter key.',+ },+ ],+ theming: {+ componentKey: 'numberInput',+ surfaces: [+ {name: 'wrapper', description: 'Input wrapper styles'},+ {name: 'input', description: 'Number input element styles'},+ ],+ },+ accessibility: [+ 'Label is always rendered and associated with the input via htmlFor/id using the useId hook.',+ 'Use isLabelHidden to hide the label visually while keeping it accessible to screen readers via a CSS technique.',+ 'Wraps XDSField for consistent label, description, and optional/required indicator handling.',+ ],+ notes: [+ 'isOptional and isRequired are mutually exclusive; if both are set, "Optional" is shown.',+ 'Uses type="number" to enable native browser step controls (up/down arrows).',+ 'Validated onChange: only calls onChange when the entered value is a valid number that passes min/max/integer constraints.',+ 'Uses internal pending state to allow free-form typing while validating on commit.',+ 'Units are displayed as a lighter grey suffix after the input value.',+ ],+};diff --git a/packages/core/src/NumberInput/README.md b/packages/core/src/NumberInput/README.mddeleted file mode 100644index 1c63d11f7c..0000000000--- a/packages/core/src/NumberInput/README.md+++ /dev/null@@ -1,148 +0,0 @@-# NumberInput--A number input component for collecting numeric user input with validation.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Label Support**: Required label for accessibility (can be visually hidden)-- **Description**: Optional description text displayed between the label and input-- **Optional/Required Indicators**: Display "Optional" or "Required" text with bullet separator-- **Label Tooltip**: Optional info icon with tooltip at end of label-- **Label Icon**: Optional icon before the label text-- **Accessible**: Label properly associated with input via htmlFor/id-- **Styled with StyleX**: Uses XDS design tokens for consistent styling-- **Size Variants**: Three sizes (sm, md, lg) for different contexts-- **Status Handling**: Error, warning, and success states with messages-- **Number Constraints**: Support for min, max, and step attributes-- **Validated onChange**: Only calls onChange when the entered value passes validation-- **Units Display**: Optional units suffix (e.g., "%" or "GB")-- **Integer Mode**: Option to restrict to integers only-- **Native Controls**: Uses `type="number"` for browser step controls-- **Event Callbacks**: onFocus, onBlur, and onEnter handlers--## Usage--```tsx-import { XDSNumberInput } from '@xds/core/NumberInput';--// Basic input with label-<XDSNumberInput label="Quantity" value={quantity} onChange={setQuantity} />--// With placeholder-<XDSNumberInput label="Age" value={age} onChange={setAge} placeholder="Enter your age" />--// With min/max constraints-<XDSNumberInput label="Rating" value={rating} onChange={setRating} min={1} max={5} />--// With step for decimals-<XDSNumberInput label="Price" value={price} onChange={setPrice} min={0} step={0.01} />--// With units display-<XDSNumberInput label="Discount" value={discount} onChange={setDiscount} units="%" />--// Integer only-<XDSNumberInput label="Count" value={count} onChange={setCount} isIntegerOnly />--// With description-<XDSNumberInput label="Quantity" description="Enter the number of items" value={qty} onChange={setQty} />--// Optional field-<XDSNumberInput label="Phone Extension" isOptional value={ext} onChange={setExt} />--// Required field-<XDSNumberInput label="Amount" isRequired value={amount} onChange={setAmount} />--// With validation status (error, warning, or success)-<XDSNumberInput- label="Age"- value={age}- onChange={setAge}- status={{ type: 'error', message: 'Age must be between 18 and 120' }}-/>--// With event handlers-<XDSNumberInput- label="Search"- value={search}- onChange={setSearch}- onEnter={() => handleSearch()}- onFocus={() => console.log('focused')}- onBlur={() => console.log('blurred')}-/>-```--## Props--| Prop | Type | Required | Description |-| --------------- | --------------------------------------------------------- | -------- | ------------------------------------------------------------------ |-| `label` | `string` | Yes | Label text for the input (always rendered for accessibility) |-| `value` | `number \| null \| undefined` | Yes | Current value of the input |-| `onChange` | `(value: number) => void` | Yes | Callback fired when input value changes (only on valid input) |-| `size` | `'sm' \| 'md' \| 'lg'` | No | Size variant (default: `'md'`) |-| `isLabelHidden` | `boolean` | No | Visually hide the label (still accessible to screen readers) |-| `description` | `string` | No | Description text displayed between the label and input |-| `isOptional` | `boolean` | No | Whether the field is optional (mutually exclusive with isRequired) |-| `isRequired` | `boolean` | No | Whether the field is required (mutually exclusive with isOptional) |-| `isDisabled` | `boolean` | No | Whether the input is disabled |-| `placeholder` | `string` | No | Placeholder text |-| `tooltip` | `string` | No | Tooltip text to display in an info icon at the end of the label |-| `startIcon` | `XDSIconType` | No | Icon to display at the start of the input |-| `labelIcon` | `XDSIconType` | No | Icon to display before the label text |-| `status` | `{type: 'error'\|'warning'\|'success', message?: string}` | No | Validation status with optional message |-| `min` | `number \| null` | No | Minimum value allowed |-| `max` | `number \| null` | No | Maximum value allowed |-| `step` | `number \| null` | No | Step increment for the input (default: 1) |-| `units` | `string \| null` | No | Units text to display at the end of the input (e.g., "%" or "GB") |-| `isIntegerOnly` | `boolean` | No | Only allow integer values (no floating point) |-| `htmlName` | `string` | No | HTML name attribute for form submissions |-| `autoComplete` | `string` | No | HTML autocomplete attribute |-| `hasAutoFocus` | `boolean` | No | Whether to focus the input on mount |-| `onFocus` | `(e: FocusEvent<HTMLInputElement>) => void` | No | Callback fired when the input receives focus |-| `onBlur` | `(e: FocusEvent<HTMLInputElement>) => void` | No | Callback fired when the input loses focus |-| `onEnter` | `() => void` | No | Callback fired when the user presses the Enter key |--## Theming--Themes can override `NumberInput` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- numberInput: {- wrapper: myStyles,- input: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| --------- | --------------------------- |-| `wrapper` | Input wrapper styles |-| `input` | Number input element styles |--## Files--| File | Role | Purpose |-| ------------------------- | ----- | --------------------------- |-| `index.ts` | Entry | Exports component and types |-| `XDSNumberInput.tsx` | Core | Component implementation |-| `XDSNumberInput.test.tsx` | Test | Unit tests |--## Implementation Notes--- Uses `useId` hook for accessible label-input association-- Label is always rendered for accessibility; use `isLabelHidden` to hide visually-- Hidden label uses CSS technique that remains accessible to screen readers-- Wraps `XDSField` component for label, description, and optional/required handling-- `isOptional` and `isRequired` are mutually exclusive; setting both will show "Optional"-- Uses `type="number"` to enable native browser step controls (up/down arrows)-- **Validated onChange**: Only calls `onChange` when the entered value is a valid number that passes min/max/integer constraints-- Uses internal pending state to allow free-form typing while validating-- Units are displayed as a lighter grey suffix after the input valuediff --git a/packages/core/src/NumberInput/XDSNumberInput.tsx b/packages/core/src/NumberInput/XDSNumberInput.tsxindex 5191b205aa..e69628307f 100644--- a/packages/core/src/NumberInput/XDSNumberInput.tsx+++ b/packages/core/src/NumberInput/XDSNumberInput.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSNumberInput.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/NumberInput/README.md (props table, features, implementation notes)+ * - /packages/core/src/NumberInput/NumberInput.doc.mjs (props table, features, implementation notes)* - /packages/core/src/NumberInput/XDSNumberInput.test.tsx (tests for new/changed behavior)* - /packages/core/src/NumberInput/index.ts (exports if types change)* - /apps/storybook/stories/NumberInput.stories.tsx (storybook stories)diff --git a/packages/core/src/NumberInput/index.ts b/packages/core/src/NumberInput/index.tsindex b83c464db7..ad6557def8 100644--- a/packages/core/src/NumberInput/index.ts+++ b/packages/core/src/NumberInput/index.ts@@ -4,7 +4,7 @@* @output Exports XDSNumberInput, XDSNumberInputProps, XDSNumberInputSize, XDSNumberInputStatus, XDSNumberInputStatusType* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/NumberInput/README.md+ * SYNC: When modified, update this header and /packages/core/src/NumberInput/NumberInput.doc.mjs*/export {XDSNumberInput} from './XDSNumberInput';diff --git a/packages/core/src/Pagination/Pagination.doc.mjs b/packages/core/src/Pagination/Pagination.doc.mjsnew file mode 100644index 0000000000..2dfa8cd82e--- /dev/null+++ b/packages/core/src/Pagination/Pagination.doc.mjs@@ -0,0 +1,162 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Pagination',+ description:+ 'Standalone pagination controls for navigating through pages of content. Supports multiple display variants and works with known totals or cursor-based pagination.',+ props: [+ {+ name: 'page',+ type: 'number',+ description: 'Current page number (1-based). Page 1 is the first page.',+ required: true,+ },+ {+ name: 'onChange',+ type: '(page: number) => void',+ description: 'Called when the page changes.',+ required: true,+ },+ {+ name: 'onChangeAction',+ type: '(page: number) => void | Promise<void>',+ description:+ 'Async action on page change. Fires after onChange and uses React transitions for built-in loading state.',+ },+ {+ name: 'totalItems',+ type: 'number',+ description:+ 'Total number of items. Used to calculate page count. Takes precedence over totalPages if both provided.',+ },+ {+ name: 'totalPages',+ type: 'number',+ description:+ 'Total number of pages. Use when you know page count but not item count.',+ },+ {+ name: 'hasMore',+ type: 'boolean',+ description:+ 'Whether more pages exist after the current one. Use for cursor-based pagination where total is unknown.',+ },+ {+ name: 'pageSize',+ type: 'number',+ description: 'Number of items per page.',+ default: '10',+ },+ {+ name: 'pageSizeOptions',+ type: 'number[]',+ description:+ 'Available page size options. Shows a page size selector dropdown when provided.',+ },+ {+ name: 'onPageSizeChange',+ type: '(pageSize: number) => void',+ description:+ 'Called when the page size changes. Automatically resets to page 1.',+ },+ {+ name: 'variant',+ type: "'pages' | 'count' | 'compact' | 'dots' | 'none'",+ description:+ "Visual variant controlling what appears between prev/next buttons. 'pages' shows page number buttons with ellipsis, 'count' shows 'X-Y of Z' text, 'compact' shows 'Page X of Y', 'dots' shows dot indicators, 'none' shows just prev/next buttons.",+ default: "'pages'",+ },+ {+ name: 'siblingCount',+ type: 'number',+ description:+ "Number of page buttons to show on each side of the current page. Only applies when variant='pages'.",+ default: '1',+ },+ {+ name: 'size',+ type: "'sm' | 'md'",+ description: 'Size of the pagination controls.',+ default: "'md'",+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Whether the component is disabled.',+ default: 'false',+ },+ {+ name: 'label',+ type: 'string',+ description: 'Accessible label for the navigation landmark.',+ default: "'Pagination'",+ },+ ],+ examples: [+ {+ label: 'Page number buttons (default)',+ code: `<XDSPagination+ page={page}+ onChange={setPage}+ totalItems={200}+ pageSize={20}+/>`,+ },+ {+ label: 'Count display with page size selector',+ code: `<XDSPagination+ page={page}+ onChange={setPage}+ totalItems={200}+ variant="count"+ pageSizeOptions={[10, 20, 50]}+ onPageSizeChange={setPageSize}+/>`,+ },+ {+ label: 'Cursor-based (no total known)',+ code: `<XDSPagination+ page={page}+ onChange={setPage}+ hasMore={data.hasNextPage}+/>`,+ },+ {+ label: 'Carousel dots',+ code: `<XDSPagination+ page={slideIndex}+ onChange={setSlideIndex}+ totalPages={slides.length}+ variant="dots"+/>`,+ },+ ],+ features: [+ "Five display variants: 'pages', 'count', 'compact', 'dots', 'none'",+ 'Offset and cursor-based pagination: provide totalItems/totalPages for known totals, or hasMore for cursor-based',+ 'Page size selector: shows a dropdown when pageSizeOptions is provided',+ 'Ellipsis truncation for page numbers via generatePageRange utility',+ 'React transitions: onChangeAction uses useTransition for built-in loading state',+ "Sizes: 'sm' and 'md'",+ ],+ accessibility: [+ 'Root is <nav> with configurable aria-label.',+ 'Current page button has aria-current="page".',+ 'Prev/next buttons have descriptive aria-label.',+ 'Ellipsis elements are aria-hidden.',+ 'All interactive elements are keyboard accessible.',+ ],+ theming: {+ componentKey: 'pagination',+ surfaces: [+ {name: 'root', description: 'Root nav container styles'},+ ],+ },+ notes: [+ "Page number buttons use XDSButton (variant='ghost' for inactive, variant='primary' for active) for theming and swizzle compatibility.",+ "Prev/next buttons use XDSButton with variant='ghost' and icon-only mode.",+ 'Dot indicators remain custom elements (intentionally different visual treatment from buttons).',+ 'Returns null when totalItems <= 0 or totalPages <= 0.',+ 'Also exports generatePageRange utility for computing visible page numbers with ellipsis.',+ ],+};diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjsnew file mode 100644index 0000000000..6e76b0f680--- /dev/null+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs@@ -0,0 +1,112 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'ProgressBar',+ description:+ 'A progress bar for displaying determinate or indeterminate progress.',+ features: [+ 'Determinate mode uses role="meter" with aria-valuenow, aria-valuemin, and aria-valuemax',+ 'Indeterminate mode uses role="progressbar" without value attributes',+ 'Label is always connected via aria-labelledby',+ 'aria-valuetext provides human-readable value description (determinate only)',+ 'Indeterminate animation respects prefers-reduced-motion',+ 'Supports four semantic color variants: accent, positive, warning, negative',+ 'Three track height sizes: sm=4px, md=8px, lg=12px',+ 'Supports custom value label formatter via formatValueLabel',+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Accessible label (required).',+ required: true,+ },+ {+ name: 'value',+ type: 'number',+ description: 'Current value (ignored when indeterminate).',+ default: '0',+ },+ {+ name: 'max',+ type: 'number',+ description: 'Maximum value.',+ default: '100',+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: 'Visually hide the label (remains accessible).',+ default: 'false',+ },+ {+ name: 'hasValueLabel',+ type: 'boolean',+ description: 'Show formatted value text (ignored when indeterminate).',+ default: 'false',+ },+ {+ name: 'formatValueLabel',+ type: '(value: number, max: number) => string',+ description:+ 'Custom value label formatter; defaults to a percentage string.',+ },+ {+ name: 'variant',+ type: "'accent' | 'positive' | 'warning' | 'negative'",+ description: 'Semantic color variant.',+ default: "'accent'",+ },+ {+ name: 'size',+ type: "'sm' | 'md' | 'lg'",+ description: 'Track height: sm=4px, md=8px, lg=12px.',+ default: "'md'",+ },+ {+ name: 'isIndeterminate',+ type: 'boolean',+ description: 'Animated loading indicator for unknown progress.',+ default: 'false',+ },+ ],+ examples: [+ {+ label: 'Determinate progress bar',+ code: `<XDSProgressBar value={75} label="Upload progress" />`,+ },+ {+ label: 'With visible value label',+ code: `<XDSProgressBar value={75} label="Storage used" hasValueLabel />`,+ },+ {+ label: 'Custom value label formatter',+ code: `<XDSProgressBar+ value={3.2}+ max={5}+ label="Disk usage"+ hasValueLabel+ formatValueLabel={(value, max) => \`\${value} GB / \${max} GB\`}+/>`,+ },+ {+ label: 'Indeterminate loading',+ code: `<XDSProgressBar isIndeterminate label="Loading..." />`,+ },+ {+ label: 'Variant and size',+ code: `<XDSProgressBar value={92} label="Disk" variant="negative" size="sm" />`,+ },+ {+ label: 'Hidden label (accessible but not visible)',+ code: `<XDSProgressBar value={50} label="Loading" isLabelHidden />`,+ },+ ],+ accessibility: [+ 'Determinate: uses role="meter" with aria-valuenow, aria-valuemin, aria-valuemax',+ 'Indeterminate: uses role="progressbar" without value attributes',+ 'Label is always connected via aria-labelledby',+ 'aria-valuetext provides human-readable value description (determinate only)',+ 'Indeterminate animation respects prefers-reduced-motion',+ ],+};diff --git a/packages/core/src/ProgressBar/README.md b/packages/core/src/ProgressBar/README.mddeleted file mode 100644index a2e7c24c6f..0000000000--- a/packages/core/src/ProgressBar/README.md+++ /dev/null@@ -1,74 +0,0 @@-# ProgressBar--A progress bar for displaying determinate or indeterminate progress.--## Exports--| Export | Type | Description |-| ----------------------- | --------- | --------------------------- |-| `XDSProgressBar` | Component | Main progress bar component |-| `XDSProgressBarProps` | Type | Props interface |-| `XDSProgressBarVariant` | Type | Variant union type |-| `XDSProgressBarSize` | Type | Size union type |--## Props--| Prop | Type | Default | Description |-| ------------------ | --------------------------------------------------- | ---------- | ------------------------------------------------------ |-| `value` | `number` | `0` | Current value (ignored when indeterminate) |-| `max` | `number` | `100` | Maximum value |-| `label` | `string` | — | Accessible label (required) |-| `isLabelHidden` | `boolean` | `false` | Visually hide the label (remains accessible) |-| `hasValueLabel` | `boolean` | `false` | Show formatted value text (ignored when indeterminate) |-| `formatValueLabel` | `(value: number, max: number) => string` | percentage | Custom value label formatter |-| `variant` | `'accent' \| 'positive' \| 'warning' \| 'negative'` | `'accent'` | Semantic color variant |-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Track height: sm=4px, md=8px, lg=12px |-| `isIndeterminate` | `boolean` | `false` | Animated loading indicator for unknown progress |-| `xstyle` | `StyleXStyles` | — | StyleX overrides for outer container |-| `data-testid` | `string` | — | Test ID |--## Usage--```tsx-import {XDSProgressBar} from '@xds/core/ProgressBar';--// Determinate progress bar-<XDSProgressBar value={75} label="Upload progress" />--// With visible value label-<XDSProgressBar value={75} label="Storage used" hasValueLabel />--// Custom format-<XDSProgressBar- value={3.2}- max={5}- label="Disk usage"- hasValueLabel- formatValueLabel={(value, max) => `${value} GB / ${max} GB`}-/>--// Indeterminate loading-<XDSProgressBar isIndeterminate label="Loading..." />--// Variant and size-<XDSProgressBar value={92} label="Disk" variant="negative" size="sm" />--// Hidden label (accessible but not visible)-<XDSProgressBar value={50} label="Loading" isLabelHidden />-```--## Accessibility--- Determinate: uses `role="meter"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`-- Indeterminate: uses `role="progressbar"` without value attributes-- Label is always connected via `aria-labelledby`-- `aria-valuetext` provides human-readable value description (determinate only)-- Indeterminate animation respects `prefers-reduced-motion`--## Files--| File | Purpose |-| ------------------------- | ------------------------ |-| `XDSProgressBar.tsx` | Component implementation |-| `XDSProgressBar.test.tsx` | Unit tests |-| `index.ts` | Barrel exports |diff --git a/packages/core/src/ProgressBar/XDSProgressBar.tsx b/packages/core/src/ProgressBar/XDSProgressBar.tsxindex 046f02eb5b..8c1309b58e 100644--- a/packages/core/src/ProgressBar/XDSProgressBar.tsx+++ b/packages/core/src/ProgressBar/XDSProgressBar.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/ProgressBar/README.md (props table, features, implementation notes)+ * - /packages/core/src/ProgressBar/ProgressBar.doc.mjs (props table, features, implementation notes)* - /packages/core/src/ProgressBar/XDSProgressBar.test.tsx (tests for new/changed behavior)* - /packages/core/src/ProgressBar/index.ts (exports if types change)* - /apps/storybook/stories/ProgressBar.stories.tsx (storybook stories)diff --git a/packages/core/src/RadioList/README.md b/packages/core/src/RadioList/README.mddeleted file mode 100644index 33d421a38a..0000000000--- a/packages/core/src/RadioList/README.md+++ /dev/null@@ -1,176 +0,0 @@-# RadioList--A radio group component for single-value selection from a list of options.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Accessible**: Uses native `<input type="radio">` with proper `role="radiogroup"` and ARIA attributes-- **Orientation**: Supports `vertical` and `horizontal` layouts-- **Sizes**: `sm` (18px radio, 20px wrapper) and `md` (22px radio, 24px wrapper)-- **Descriptions**: Optional description text per item-- **Custom content**: `startContent` and `endContent` slots on each item-- **Disabled state**: Supports disabling the entire group or individual items-- **Field integration**: Uses `XDSField` for label, description, required/optional, and status messaging--## Usage--```tsx-import { XDSRadioList, XDSRadioListItem } from '@xds/core/RadioList';--// Basic usage-<XDSRadioList- label="Notification preference"- value={selected}- onChange={setSelected}->- <XDSRadioListItem label="Email" value="email" />- <XDSRadioListItem label="SMS" value="sms" />- <XDSRadioListItem label="Push" value="push" />-</XDSRadioList>--// With descriptions-<XDSRadioList- label="Plan"- value={plan}- onChange={setPlan}->- <XDSRadioListItem- label="Free"- value="free"- description="Basic features, limited usage"- />- <XDSRadioListItem- label="Pro"- value="pro"- description="All features, unlimited usage"- />-</XDSRadioList>--// Horizontal layout-<XDSRadioList- label="Size"- value={size}- onChange={setSize}- orientation="horizontal"->- <XDSRadioListItem label="Small" value="sm" />- <XDSRadioListItem label="Medium" value="md" />- <XDSRadioListItem label="Large" value="lg" />-</XDSRadioList>--// With status-<XDSRadioList- label="Required choice"- value={choice}- onChange={setChoice}- isRequired- status={{ type: 'error', message: 'Please select an option' }}->- <XDSRadioListItem label="Option A" value="a" />- <XDSRadioListItem label="Option B" value="b" />-</XDSRadioList>--// Disabled group-<XDSRadioList- label="Locked selection"- value="locked"- onChange={() => {}}- isDisabled->- <XDSRadioListItem label="Locked" value="locked" />- <XDSRadioListItem label="Unavailable" value="unavailable" />-</XDSRadioList>-```--### XDSRadioList--Radio group container with field integration for label, description, and status.--```tsx-<XDSRadioList label="Notification preference" value={selected} onChange={setSelected}>- <XDSRadioListItem label="Email" value="email" />- <XDSRadioListItem label="SMS" value="sms" />-</XDSRadioList>-```--| Prop | Type | Default | Description |-| --------------- | ---------------------------- | ------------ | -------------------------------------------------------------------- |-| `label` | `string` | — | Label text for the radio group (always rendered for accessibility) |-| `isLabelHidden` | `boolean` | `false` | Whether to visually hide the label |-| `description` | `string` | — | Description text displayed below the label |-| `value` | `string` | — | The currently selected value |-| `onChange` | `(value: string) => void` | — | Callback fired when the selected value changes |-| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction of the radio items |-| `isDisabled` | `boolean` | `false` | Whether all radio items are disabled |-| `isRequired` | `boolean` | `false` | Whether the radio group is required |-| `isOptional` | `boolean` | `false` | Whether the field is optional (mutually exclusive with `isRequired`) |-| `status` | `XDSInputStatus` | — | Status indicator (`{ type, message }`) |-| `size` | `'sm' \| 'md'` | `'md'` | Size of the radio controls |-| `labelTooltip` | `string` | — | Tooltip text for an info icon next to the label |-| `xstyle` | `StyleXStyles` | — | Additional styles for the outer container |-| `data-testid` | `string` | — | Test ID for the outer container |-| `children` | `ReactNode` | — | `XDSRadioListItem` elements |--### XDSRadioListItem--Individual radio item with label, description, and content slots.--```tsx-<XDSRadioListItem- label="Pro"- value="pro"- description="All features, unlimited usage"-/>-```--| Prop | Type | Default | Description |-| -------------- | ----------- | ------- | ---------------------------------------------- |-| `label` | `string` | — | Label text for the radio item |-| `value` | `string` | — | Value of this radio item |-| `description` | `string` | — | Description text displayed below the label |-| `isDisabled` | `boolean` | `false` | Whether this individual radio item is disabled |-| `startContent` | `ReactNode` | — | Content to render before the radio circle |-| `endContent` | `ReactNode` | — | Content to render after the label |-| `data-testid` | `string` | — | Test ID for the radio item container |--## Theming--Themes can override `RadioList` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- radioList: {- root: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------- | ----------------------- |-| `root` | Root radio group styles |--## Files--| File | Role | Purpose |-| ----------------------- | ----- | -------------------------------------------------- |-| `index.ts` | Entry | Exports components and types |-| `XDSRadioList.tsx` | Core | Radio group container with context provider |-| `XDSRadioListItem.tsx` | Core | Individual radio item consuming `RadioListContext` |-| `XDSRadioList.test.tsx` | Test | Unit tests |--## Implementation Notes--- `XDSRadioList` creates a `RadioListContext` that provides `name`, `value`, `onChange`, `isDisabled`, `isRequired`, `size`, and `status` to child items-- `XDSRadioListItem` must be used within an `XDSRadioList` — throws if context is missing-- Uses a hidden native `<input type="radio">` with a custom visual overlay for consistent styling-- Focus outline uses the standard XDS focus outline token with `2px` offset-- Hover states use `color-mix()` for consistent overlay tinting-- Size variants match `CheckboxInput` dimensions for visual consistencydiff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjsnew file mode 100644index 0000000000..f88aaf161a--- /dev/null+++ b/packages/core/src/RadioList/RadioList.doc.mjs@@ -0,0 +1,244 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'RadioList',+ description:+ 'A radio group component for single-value selection from a list of options.',+ features: [+ 'Accessible — uses native <input type="radio"> with proper role="radiogroup" and ARIA attributes',+ 'Orientation — supports vertical and horizontal layouts',+ 'Sizes — sm (18px radio, 20px wrapper) and md (22px radio, 24px wrapper)',+ 'Descriptions — optional description text per item',+ 'Custom content — startContent and endContent slots on each item',+ 'Disabled state — supports disabling the entire group or individual items',+ 'Field integration — uses XDSField for label, description, required/optional, and status messaging',+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSRadioList+ label="Notification preference"+ value={selected}+ onChange={setSelected}+>+ <XDSRadioListItem label="Email" value="email" />+ <XDSRadioListItem label="SMS" value="sms" />+ <XDSRadioListItem label="Push" value="push" />+</XDSRadioList>`,+ },+ {+ label: 'With descriptions',+ code: `<XDSRadioList+ label="Plan"+ value={plan}+ onChange={setPlan}+>+ <XDSRadioListItem+ label="Free"+ value="free"+ description="Basic features, limited usage"+ />+ <XDSRadioListItem+ label="Pro"+ value="pro"+ description="All features, unlimited usage"+ />+</XDSRadioList>`,+ },+ {+ label: 'Horizontal layout',+ code: `<XDSRadioList+ label="Size"+ value={size}+ onChange={setSize}+ orientation="horizontal"+>+ <XDSRadioListItem label="Small" value="sm" />+ <XDSRadioListItem label="Medium" value="md" />+ <XDSRadioListItem label="Large" value="lg" />+</XDSRadioList>`,+ },+ {+ label: 'With status',+ code: `<XDSRadioList+ label="Required choice"+ value={choice}+ onChange={setChoice}+ isRequired+ status={{ type: 'error', message: 'Please select an option' }}+>+ <XDSRadioListItem label="Option A" value="a" />+ <XDSRadioListItem label="Option B" value="b" />+</XDSRadioList>`,+ },+ {+ label: 'Disabled group',+ code: `<XDSRadioList+ label="Locked selection"+ value="locked"+ onChange={() => {}}+ isDisabled+>+ <XDSRadioListItem label="Locked" value="locked" />+ <XDSRadioListItem label="Unavailable" value="unavailable" />+</XDSRadioList>`,+ },+ ],+ theming: {+ componentKey: 'radioList',+ surfaces: [{name: 'root', description: 'Root radio group styles'}],+ },+ notes: [+ 'XDSRadioList creates a RadioListContext that provides name, value, onChange, isDisabled, isRequired, size, and status to child items',+ 'XDSRadioListItem must be used within an XDSRadioList — throws if context is missing',+ 'Uses a hidden native <input type="radio"> with a custom visual overlay for consistent styling',+ 'Focus outline uses the standard XDS focus outline token with 2px offset',+ 'Hover states use color-mix() for consistent overlay tinting',+ 'Size variants match CheckboxInput dimensions for visual consistency',+ ],+ components: [+ {+ name: 'XDSRadioList',+ description:+ 'Radio group container with field integration for label, description, and status.',+ examples: [+ {+ label: 'Basic',+ code: `<XDSRadioList label="Notification preference" value={selected} onChange={setSelected}>+ <XDSRadioListItem label="Email" value="email" />+ <XDSRadioListItem label="SMS" value="sms" />+</XDSRadioList>`,+ },+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description:+ 'Label text for the radio group (always rendered for accessibility).',+ required: true,+ },+ {+ name: 'value',+ type: 'string',+ description: 'The currently selected value.',+ required: true,+ },+ {+ name: 'onChange',+ type: '(value: string) => void',+ description: 'Callback fired when the selected value changes.',+ required: true,+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'XDSRadioListItem elements.',+ required: true,+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: 'Whether to visually hide the label.',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Description text displayed below the label.',+ },+ {+ name: 'orientation',+ type: "'vertical' | 'horizontal'",+ description: 'Layout direction of the radio items.',+ default: "'vertical'",+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Whether all radio items are disabled.',+ default: 'false',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description: 'Whether the radio group is required.',+ default: 'false',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description:+ 'Whether the field is optional (mutually exclusive with isRequired).',+ default: 'false',+ },+ {+ name: 'status',+ type: 'XDSInputStatus',+ description: 'Status indicator ({ type, message }).',+ },+ {+ name: 'size',+ type: "'sm' | 'md'",+ description: 'Size of the radio controls.',+ default: "'md'",+ },+ {+ name: 'labelTooltip',+ type: 'string',+ description: 'Tooltip text for an info icon next to the label.',+ },+ ],+ },+ {+ name: 'XDSRadioListItem',+ description:+ 'Individual radio item with label, description, and content slots.',+ examples: [+ {+ label: 'With description',+ code: `<XDSRadioListItem+ label="Pro"+ value="pro"+ description="All features, unlimited usage"+/>`,+ },+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Label text for the radio item.',+ required: true,+ },+ {+ name: 'value',+ type: 'string',+ description: 'Value of this radio item.',+ required: true,+ },+ {+ name: 'description',+ type: 'string',+ description: 'Description text displayed below the label.',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Whether this individual radio item is disabled.',+ default: 'false',+ },+ {+ name: 'startContent',+ type: 'ReactNode',+ description: 'Content to render before the radio circle.',+ },+ {+ name: 'endContent',+ type: 'ReactNode',+ description: 'Content to render after the label.',+ },+ ],+ },+ ],+};diff --git a/packages/core/src/RadioList/XDSRadioList.tsx b/packages/core/src/RadioList/XDSRadioList.tsxindex d9e0631a20..5677a8cf9c 100644--- a/packages/core/src/RadioList/XDSRadioList.tsx+++ b/packages/core/src/RadioList/XDSRadioList.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSRadioList.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/RadioList/README.md+ * - /packages/core/src/RadioList/RadioList.doc.mjs* - /packages/core/src/RadioList/XDSRadioList.test.tsx* - /packages/core/src/RadioList/index.ts* - /apps/storybook/stories/RadioList.stories.tsxdiff --git a/packages/core/src/RadioList/XDSRadioListItem.tsx b/packages/core/src/RadioList/XDSRadioListItem.tsxindex 7b28c6aef8..4c35d602e7 100644--- a/packages/core/src/RadioList/XDSRadioListItem.tsx+++ b/packages/core/src/RadioList/XDSRadioListItem.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSRadioList.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/RadioList/README.md+ * - /packages/core/src/RadioList/RadioList.doc.mjs* - /packages/core/src/RadioList/XDSRadioList.test.tsx* - /packages/core/src/RadioList/index.ts* - /apps/storybook/stories/RadioList.stories.tsxdiff --git a/packages/core/src/Section/README.md b/packages/core/src/Section/README.mddeleted file mode 100644index 0eaa8d5365..0000000000--- a/packages/core/src/Section/README.md+++ /dev/null@@ -1,46 +0,0 @@-# Section--Section container component with background variants.--<!-- SYNC: When files in this directory change, update this document. -->--## Overview--XDSSection is a container with background variants for creating visually distinct regions. Sections automatically escape parent container padding for edge-to-edge fills.--## Import--```tsx-import {XDSSection} from '@xds/core/Section';-```--## Usage--```tsx-<XDSSection variant="wash" width={300} height={250}>- <XDSLayout- content={<XDSLayoutContent>Content in wash section</XDSLayoutContent>}- />-</XDSSection>-```--## Props--| Prop | Type | Default | Description |-| ------------- | ---------------------------------------- | ----------- | ------------------------------------------------- |-| `variant` | `'section' \| 'transparent' \| 'wash'` | `'section'` | Background variant |-| `width` | `SizeValue` | — | Width (number = pixels, string = as-is) |-| `height` | `SizeValue` | — | Height (number = pixels, string = as-is) |-| `maxWidth` | `SizeValue` | — | Maximum width |-| `minHeight` | `SizeValue` | — | Minimum height |-| `children` | `ReactNode` | — | Content |-| `dividers` | `Array<'top'\|'bottom'\|'start'\|'end'>` | — | Which sides have divider borders |-| `isFullBleed` | `boolean` | `false` | Removes internal padding for edge-to-edge content |--## Files--| File | Role | Purpose |-| ---------------- | --------- | -------------------------------- |-| `index.ts` | Entry | Exports component and types |-| `XDSSection.tsx` | Component | Section container implementation |-| `README.md` | Docs | This documentation |diff --git a/packages/core/src/Section/Section.doc.mjs b/packages/core/src/Section/Section.doc.mjsnew file mode 100644index 0000000000..4ea97e5fb0--- /dev/null+++ b/packages/core/src/Section/Section.doc.mjs@@ -0,0 +1,94 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Section',+ description:+ 'Container with background variants for creating visually distinct regions that automatically escape parent container padding for edge-to-edge fills.',+ features: [+ 'Background variants: section, transparent, and wash',+ 'Automatically escapes parent container padding for edge-to-edge fills',+ 'Supports divider borders on any combination of sides (top, bottom, start, end)',+ 'Flexible sizing via SizeValue for width, height, maxWidth, and minHeight',+ 'Full-bleed mode removes internal padding for edge-to-edge content',+ ],+ examples: [+ {+ label: 'Wash variant',+ code: `<XDSSection variant="wash" width={300} height={250}>+ <XDSLayout+ content={<XDSLayoutContent>Content in wash section</XDSLayoutContent>}+ />+</XDSSection>`,+ },+ {+ label: 'Transparent variant',+ code: `<XDSSection variant="transparent">+ <XDSLayout+ content={<XDSLayoutContent>Transparent background</XDSLayoutContent>}+ />+</XDSSection>`,+ },+ {+ label: 'With dividers',+ code: `<XDSSection variant="section" dividers={['top', 'bottom']}>+ <XDSLayout+ content={<XDSLayoutContent>Section with top and bottom borders</XDSLayoutContent>}+ />+</XDSSection>`,+ },+ {+ label: 'Full bleed',+ code: `<XDSSection variant="wash" isFullBleed>+ <XDSLayout+ content={<XDSLayoutContent>Edge-to-edge content</XDSLayoutContent>}+ />+</XDSSection>`,+ },+ ],+ props: [+ {+ name: 'variant',+ type: "'section' | 'transparent' | 'wash'",+ description: 'Background variant applied to the section container.',+ default: "'section'",+ },+ {+ name: 'width',+ type: 'SizeValue',+ description:+ 'Width of the section; a number is interpreted as pixels, a string is used as-is.',+ },+ {+ name: 'height',+ type: 'SizeValue',+ description:+ 'Height of the section; a number is interpreted as pixels, a string is used as-is.',+ },+ {+ name: 'maxWidth',+ type: 'SizeValue',+ description: 'Maximum width of the section.',+ },+ {+ name: 'minHeight',+ type: 'SizeValue',+ description: 'Minimum height of the section.',+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Content rendered inside the section.',+ },+ {+ name: 'dividers',+ type: "Array<'top' | 'bottom' | 'start' | 'end'>",+ description: 'Which sides of the section have divider borders.',+ },+ {+ name: 'isFullBleed',+ type: 'boolean',+ description: 'Removes internal padding so content extends edge-to-edge.',+ default: 'false',+ },+ ],+};diff --git a/packages/core/src/Section/XDSSection.tsx b/packages/core/src/Section/XDSSection.tsxindex dc8cfec101..28d0865113 100644--- a/packages/core/src/Section/XDSSection.tsx+++ b/packages/core/src/Section/XDSSection.tsx@@ -5,7 +5,7 @@* @position Core section container component** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Section/README.md (props table, features)+ * - /packages/core/src/Section/Section.doc.mjs (props table, features)* - /packages/core/src/Section/index.ts (exports if types change)* - /apps/storybook/stories/Section.stories.tsx (storybook stories)*/diff --git a/packages/core/src/Section/index.ts b/packages/core/src/Section/index.tsindex 62796faf7a..5bb74d0356 100644--- a/packages/core/src/Section/index.ts+++ b/packages/core/src/Section/index.ts@@ -4,7 +4,7 @@* @output Exports XDSSection component and types* @position Entry point for @xds/core/Section module*- * SYNC: When modified, update /packages/core/src/Section/README.md+ * SYNC: When modified, update /packages/core/src/Section/Section.doc.mjs*/export {XDSSection} from './XDSSection';diff --git a/packages/core/src/Selector/README.md b/packages/core/src/Selector/README.mddeleted file mode 100644index 50c757acd6..0000000000--- a/packages/core/src/Selector/README.md+++ /dev/null@@ -1,156 +0,0 @@-# XDSSelector--Dropdown selector for choosing from a list of options. Follows XDS input conventions with label, status, and field props.--## Usage--```tsx-import {XDSSelector, XDSSelectorOption} from '@xds/core/Selector';--// Basic usage (label is required)-<XDSSelector- label="Fruit"- options={['Apple', 'Banana', 'Orange']}- value={value}- onChange={setValue}-/>--// With object options (supports disabled, icons)-<XDSSelector- label="Settings"- options={[- {value: 'profile', label: 'Profile', icon: UserIcon},- {value: 'settings', label: 'Settings', icon: CogIcon, disabled: true},- ]}- value={value}- onChange={setValue}-/>--// Sections (automatically include labeled dividers)-<XDSSelector- label="Fruit"- options={[- {value: 'apple', label: 'Apple'},- {type: 'section', title: 'Citrus', options: [- {value: 'orange', label: 'Orange'},- ]},- ]}- value={value}- onChange={setValue}-/>--// Custom rendering with XDSSelectorOption-<XDSSelector label="User" options={users} value={value} onChange={setValue}>- {option => (- <XDSSelectorOption- icon={UserIcon}- label={option.label}- description={option.email}- />- )}-</XDSSelector>--// With status and field props-<XDSSelector- label="Fruit"- isRequired- status={{type: 'error', message: 'Required'}}- options={['Apple', 'Banana']}- value={value}- onChange={setValue}-/>-```--### XDSSelector--Dropdown selector for choosing from a list of options.--```tsx-<XDSSelector- label="Fruit"- options={['Apple', 'Banana', 'Orange']}- value={value}- onChange={setValue}-/>-```--| Prop | Type | Description |-| --------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------- |-| `label` | `string` | **Required.** Label text for accessibility |-| `options` | `XDSSelectorOptionType[]` | **Required.** Array of options (strings, objects, dividers, sections) |-| `value` | `string` | Selected value |-| `onChange` | `(value: string) => void` | Selection callback |-| `placeholder` | `string` | Placeholder text (default: `'Select...'`) |-| `size` | `'sm' \| 'md' \| 'lg'` | Size variant (default: `'md'`) |-| `isDisabled` | `boolean` | Disable selector |-| `isLabelHidden` | `boolean` | Visually hide label |-| `description` | `string` | Helper text below label |-| `isOptional` / `isRequired` | `boolean` | Field requirement indicators |-| `status` | `{type: 'error'\|'warning'\|'success', message?: string}` | Status with optional message |-| `children` | `(option: XDSSelectorOptionData) => ReactNode` | Custom option renderer |--## Option Types--```tsx-// String - converted to {value: 'Apple', label: 'Apple'}-'Apple'--// Object - with optional icon, disabled-{value: 'apple', label: 'Apple', icon?: IconComponent, disabled?: boolean}--// Divider - horizontal separator-{type: 'divider'}--// Section - grouped options with labeled divider-{type: 'section', title: 'Group Name', options: [...]}-```--### XDSSelectorOption--Helper for custom option rendering:--```tsx-<XDSSelectorOption- icon={UserIcon}- label="Primary text"- description="Secondary"-/>-```--| Prop | Type | Default | Description |-| ------------- | ------------- | ------- | ----------------------------- |-| `icon` | `XDSIconType` | — | Icon before the label |-| `label` | `ReactNode` | — | Primary label text (required) |-| `description` | `ReactNode` | — | Secondary description text |--## Keyboard--↑↓ navigate, Enter/Space select, Escape close, Home/End jump, A-Z typeahead.--## Accessibility--Uses `role="combobox"` trigger, `role="listbox"` dropdown, `role="group"` for sections, `aria-activedescendant` for focus.--## Theming--Themes can override `Selector` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- selector: {- trigger: myStyles,- dropdown: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ---------- | ------------------------- |-| `trigger` | Trigger button styles |-| `dropdown` | Dropdown container styles |diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjsnew file mode 100644index 0000000000..201ada2e39--- /dev/null+++ b/packages/core/src/Selector/Selector.doc.mjs@@ -0,0 +1,228 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Selector',+ description:+ 'Dropdown selector for choosing from a list of options. Follows XDS input conventions with label, status, and field props.',+ features: [+ 'Supports string items (auto-converted to {value, label}), object items with optional icon and disabled state, dividers, and labeled sections',+ 'Custom item rendering via children render prop and XDSSelectorItem helper',+ 'Integrates with XDS field conventions: label, description, isRequired, isOptional, isLabelHidden, status',+ 'Size variants: sm, md, lg',+ 'Full keyboard navigation with typeahead support',+ 'Accessible — role="combobox" trigger, role="listbox" dropdown, role="group" for sections, aria-activedescendant for focus',+ ],+ keyboard:+ '↑↓ navigate, Enter/Space select, Escape close, Home/End jump, A-Z typeahead.',+ accessibility: [+ 'Uses role="combobox" on the trigger button.',+ 'Dropdown uses role="listbox".',+ 'Section groups use role="group".',+ 'aria-activedescendant tracks the focused option.',+ ],+ theming: {+ componentKey: 'selector',+ surfaces: [+ {name: 'trigger', description: 'Trigger button styles'},+ {name: 'dropdown', description: 'Dropdown container styles'},+ ],+ },+ examples: [+ {+ label: 'Basic',+ code: `<XDSSelector+ label="Fruit"+ options={['Apple', 'Banana', 'Orange']}+ value={value}+ onChange={setValue}+/>`,+ },+ {+ label: 'With object items (icon, disabled)',+ code: `<XDSSelector+ label="Settings"+ options={[+ {value: 'profile', label: 'Profile', icon: UserIcon},+ {value: 'settings', label: 'Settings', icon: CogIcon, disabled: true},+ ]}+ value={value}+ onChange={setValue}+/>`,+ },+ {+ label: 'Sections',+ code: `<XDSSelector+ label="Fruit"+ options={[+ {value: 'apple', label: 'Apple'},+ {type: 'section', title: 'Citrus', items: [+ {value: 'orange', label: 'Orange'},+ ]},+ ]}+ value={value}+ onChange={setValue}+/>`,+ },+ {+ label: 'Custom rendering with XDSSelectorItem',+ code: `<XDSSelector label="User" options={users} value={value} onChange={setValue}>+ {user => (+ <XDSSelectorItem+ icon={UserIcon}+ label={user.label}+ description={user.email}+ />+ )}+</XDSSelector>`,+ },+ {+ label: 'With status and field props',+ code: `<XDSSelector+ label="Fruit"+ isRequired+ status={{type: 'error', message: 'Required'}}+ options={['Apple', 'Banana']}+ value={value}+ onChange={setValue}+/>`,+ },+ ],+ components: [+ {+ name: 'XDSSelector',+ description: 'Dropdown selector for choosing from a list of options.',+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Label text for accessibility.',+ required: true,+ },+ {+ name: 'options',+ type: 'XDSSelectorOption[]',+ description:+ 'Array of items — strings, objects with value/label/icon/disabled, dividers ({type: "divider"}), or sections ({type: "section", title, items}).',+ required: true,+ },+ {+ name: 'value',+ type: 'string',+ description: 'Currently selected value.',+ },+ {+ name: 'onChange',+ type: '(value: string) => void',+ description: 'Callback fired when the selection changes.',+ },+ {+ name: 'placeholder',+ type: 'string',+ description: 'Placeholder text shown when no value is selected.',+ default: "'Select...'",+ },+ {+ name: 'size',+ type: "'sm' | 'md' | 'lg'",+ description: 'Size variant for the selector.',+ default: "'md'",+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Disables the selector.',+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: 'Visually hides the label while keeping it accessible.',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Helper text displayed below the label.',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description: 'Marks the field as optional.',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description: 'Marks the field as required.',+ },+ {+ name: 'status',+ type: "{type: 'error' | 'warning' | 'success', message?: string}",+ description: 'Validation status with an optional message.',+ },+ {+ name: 'children',+ type: '(item: XDSSelectorItemData) => ReactNode',+ description: 'Custom render function for each item in the dropdown.',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSSelector+ label="Fruit"+ options={['Apple', 'Banana', 'Orange']}+ value={value}+ onChange={setValue}+/>`,+ },+ {+ label: 'With object items',+ code: `<XDSSelector+ label="Settings"+ options={[+ {value: 'profile', label: 'Profile', icon: UserIcon},+ {value: 'settings', label: 'Settings', icon: CogIcon, disabled: true},+ ]}+ value={value}+ onChange={setValue}+/>`,+ },+ ],+ },+ {+ name: 'XDSSelectorItem',+ description:+ 'Helper component for custom item rendering inside an XDSSelector children render prop.',+ props: [+ {+ name: 'label',+ type: 'ReactNode',+ description: 'Primary label text for the item.',+ required: true,+ },+ {+ name: 'icon',+ type: 'XDSIconType',+ description: 'Icon displayed before the label.',+ },+ {+ name: 'description',+ type: 'ReactNode',+ description: 'Secondary description text displayed below the label.',+ },+ ],+ examples: [+ {+ label: 'Custom item rendering',+ code: `<XDSSelector label="User" options={users} value={value} onChange={setValue}>+ {user => (+ <XDSSelectorItem+ icon={UserIcon}+ label={user.label}+ description={user.email}+ />+ )}+</XDSSelector>`,+ },+ ],+ },+ ],+};diff --git a/packages/core/src/Selector/XDSSelector.tsx b/packages/core/src/Selector/XDSSelector.tsxindex 73fef9bcc6..d039ae796e 100644--- a/packages/core/src/Selector/XDSSelector.tsx+++ b/packages/core/src/Selector/XDSSelector.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts** SYNC: When modified, update:- * - /packages/core/src/Selector/README.md+ * - /packages/core/src/Selector/Selector.doc.mjs* - /packages/core/src/Selector/index.ts*/diff --git a/packages/core/src/SideNav/README.md b/packages/core/src/SideNav/README.mddeleted file mode 100644index ed5926d915..0000000000--- a/packages/core/src/SideNav/README.md+++ /dev/null@@ -1,197 +0,0 @@-# SideNav--Sidebar navigation component for application pages. Supports sections, nested items, selected state, icons, and responsive collapse.--## Components--### XDSSideNav--Container with five zones: header, topContent, children (scrollable), footer, footerIcons.--```tsx-<XDSSideNav- header={<XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />}- topContent={<XDSButton label="Create new" variant="primary" />}>- <XDSSideNavSection title="Main">- <XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected href="/dashboard" />- <XDSSideNavItem label="Projects" icon={FolderIcon} href="/projects" />- </XDSSideNavSection>-</XDSSideNav>-```--| Prop | Type | Default | Description |-| ------------- | -------------- | ------- | -------------------------------------------- |-| `header` | `ReactNode` | — | Header area (XDSSideNavHeader). Sticky |-| `topContent` | `ReactNode` | — | Content below header (e.g., create button) |-| `children` | `ReactNode` | — | Navigation sections and items. Scrollable |-| `footer` | `ReactNode` | — | Footer area above icon bar |-| `footerIcons` | `ReactNode` | — | Footer icon bar |-| `xstyle` | `StyleXStyles` | — | StyleX overrides |-| `data-testid` | `string` | — | Test ID |--### XDSSideNavHeader--Product/suite/account header with smart interaction boundary logic.--```tsx-<XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />-```--| Prop | Type | Default | Description |-| ---------------- | -------------- | ------- | --------------------------------- |-| `icon` | `ReactNode` | — | Product/app icon |-| `title` | `string` | — | Product/app name (required) |-| `titleHref` | `string` | — | Link for the title |-| `supertitle` | `string` | — | Text above the title |-| `supertitleHref` | `string` | — | Link for the supertitle |-| `subtitle` | `string` | — | Text below the title |-| `subtitleHref` | `string` | — | Link for the subtitle |-| `menu` | `ReactNode` | — | Menu content in a popover |-| `xstyle` | `StyleXStyles` | — | StyleX overrides |-| `data-testid` | `string` | — | Test ID |--### XDSSideNavItem--Navigation item with icon, selected state, and nesting support.--```tsx-<XDSSideNavItem- label="Dashboard"- icon={HomeIcon}- selectedIcon={HomeIconSolid}- isSelected- href="/dashboard"- endContent={<XDSBadge>3</XDSBadge>}-/>-```--| Prop | Type | Default | Description |-| -------------- | ---------------------- | ------- | ------------------------------------ |-| `as` | `XDSLinkComponentType` | — | Custom link component |-| `label` | `string` | — | Item label (required) |-| `icon` | `XDSIconType` | — | Icon (outline variant) |-| `selectedIcon` | `XDSIconType` | — | Icon when selected (filled variant) |-| `isSelected` | `boolean` | `false` | Current page indicator |-| `isDisabled` | `boolean` | `false` | Disabled state |-| `href` | `string` | — | Navigation URL |-| `onClick` | `(e: MouseEvent) => void` | — | Click handler |-| `endContent` | `ReactNode` | — | Right-side content (badges, counts) |-| `children` | `ReactNode` | — | Sub-items for nesting |-| `data-testid` | `string` | — | Test ID |--### XDSSideNavSection--Section grouping with optional title and end content.--```tsx-<XDSSideNavSection title="Settings" endContent={<XDSBadge>New</XDSBadge>}>- <XDSSideNavItem label="General" href="/settings/general" />- <XDSSideNavItem label="Security" href="/settings/security" />-</XDSSideNavSection>-```--| Prop | Type | Default | Description |-| ---------------- | ----------- | ------- | ------------------------------------------- |-| `title` | `string` | — | Section title (required) |-| `subtitle` | `string` | — | Section subtitle |-| `children` | `ReactNode` | — | Section items |-| `endContent` | `ReactNode` | — | Right-side content in section header |-| `isHeaderHidden` | `boolean` | `false` | Visually hide header (still accessible) |-| `data-testid` | `string` | — | Test ID |--## Usage--```tsx-import {- XDSSideNav,- XDSSideNavHeader,- XDSSideNavItem,- XDSSideNavSection,-} from '@xds/core/SideNav';-```--### With XDSAppShell + TopNav--When used inside `XDSAppShell` alongside a `XDSTopNav`, **omit the header** — the TopNav already provides the app name and logo. Including `XDSSideNavHeader` would double the identity.--```tsx-// TopNav provides identity → SideNav has no header-<XDSAppShell- topNav={<XDSTopNav title={<XDSTopNavTitle title="My App" />} />}- sideNav={- <XDSSideNav>- <XDSSideNavSection title="Main" isHeaderHidden>- <XDSSideNavItem- label="Dashboard"- icon={HomeIcon}- isSelected- href="/dashboard"- />- <XDSSideNavItem label="Projects" icon={FolderIcon} href="/projects" />- </XDSSideNavSection>- </XDSSideNav>- }>- <Content />-</XDSAppShell>-```--### Standalone (no TopNav)--Without a TopNav, include `XDSSideNavHeader` to provide app identity.--```tsx-// No TopNav → SideNav header provides identity-<XDSAppShell- sideNav={- <XDSSideNav- header={- <XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />- }- topContent={<XDSButton label="Create new" variant="primary" />}- footerIcons={<XDSButton icon={HelpIcon} variant="ghost" label="Help" />}>- <XDSSideNavSection title="Main">- <XDSSideNavItem- label="Dashboard"- icon={HomeIcon}- selectedIcon={HomeIconSolid}- isSelected- href="/dashboard"- />- <XDSSideNavItem- label="Projects"- icon={FolderIcon}- href="/projects"- endContent={<XDSBadge>3</XDSBadge>}- />- </XDSSideNavSection>-- <XDSSideNavSection title="Settings">- <XDSSideNavItem label="General" href="/settings/general" />- <XDSSideNavItem label="Security" href="/settings/security" />- </XDSSideNavSection>- </XDSSideNav>- }>- <Content />-</XDSAppShell>-```--## Header Interaction Model--| Props provided | Behavior |-| --------------------------------------- | -------------------------------------------------------------- |-| `titleHref` only, no menu | Whole header is one link |-| `titleHref` + `supertitleHref`, no menu | Each text is an independent link |-| `menu` only, no hrefs | Whole header is the popover trigger |-| `menu` + hrefs | Links are independent `<a>`, chevron/remaining area is trigger |--## Accessibility--- `<nav aria-label="Side navigation">`-- `aria-current="page"` on selected item-- Sections: `role="group"` with `aria-labelledby`-- Keyboard: Tab through items, Enter/Space to activate--## Dependencies--- `useXDSPopover` — for header menu popover-- `XDSIcon` — for rendering icon components in nav itemsdiff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjsnew file mode 100644index 0000000000..af07f05d9e--- /dev/null+++ b/packages/core/src/SideNav/SideNav.doc.mjs@@ -0,0 +1,351 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'SideNav',+ description:+ 'Sidebar navigation component for application pages. Supports sections, nested items, selected state, icons, and responsive collapse.',+ features: [+ 'Five-zone layout: header, topContent, children (scrollable), footer, footerIcons',+ 'Smart header interaction boundary logic — links and menu trigger coexist without overlap',+ 'Nested items via children on XDSSideNavItem',+ 'Selected state with optional alternate icon for filled/outline variants',+ 'Section grouping with optional title, subtitle, and end content',+ 'Accessible — nav landmark, aria-current="page", role="group" with aria-labelledby on sections',+ 'Keyboard navigable — Tab through items, Enter/Space to activate',+ ],+ accessibility: [+ '<nav aria-label="Side navigation"> wraps the entire component',+ 'aria-current="page" is applied to the selected item',+ 'Sections use role="group" with aria-labelledby pointing to the section title',+ 'isHeaderHidden visually hides the section title while keeping it accessible to screen readers',+ ],+ keyboard: 'Tab through items, Enter/Space to activate links',+ notes: [+ 'When used inside XDSAppShell alongside XDSTopNav, omit XDSSideNavHeader — the TopNav already provides app identity and including the header would duplicate it.',+ 'Without a TopNav, include XDSSideNavHeader to provide app identity.',+ 'Header interaction model: titleHref only → whole header is one link; titleHref + supertitleHref, no menu → each text is an independent link; menu only, no hrefs → whole header is the popover trigger; menu + hrefs → links are independent <a> elements, chevron/remaining area is the popover trigger.',+ 'Depends on useXDSPopover for the header menu popover and XDSIcon for rendering icon components in nav items.',+ ],+ examples: [+ {+ label: 'With XDSAppShell + TopNav (no header)',+ code: `// TopNav provides identity → SideNav has no header+<XDSAppShell+ topNav={<XDSTopNav title={<XDSTopNavTitle title="My App" />} />}+ sideNav={+ <XDSSideNav>+ <XDSSideNavSection title="Main" isHeaderHidden>+ <XDSSideNavItem+ label="Dashboard"+ icon={HomeIcon}+ isSelected+ href="/dashboard"+ />+ <XDSSideNavItem label="Projects" icon={FolderIcon} href="/projects" />+ </XDSSideNavSection>+ </XDSSideNav>+ }>+ <Content />+</XDSAppShell>`,+ },+ {+ label: 'Standalone (no TopNav)',+ code: `// No TopNav → SideNav header provides identity+<XDSAppShell+ sideNav={+ <XDSSideNav+ header={+ <XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />+ }+ topContent={<XDSButton label="Create new" variant="primary" />}+ footerIcons={<XDSButton icon={HelpIcon} variant="ghost" label="Help" />}>+ <XDSSideNavSection title="Main">+ <XDSSideNavItem+ label="Dashboard"+ icon={HomeIcon}+ selectedIcon={HomeIconSolid}+ isSelected+ href="/dashboard"+ />+ <XDSSideNavItem+ label="Projects"+ icon={FolderIcon}+ href="/projects"+ endContent={<XDSBadge>3</XDSBadge>}+ />+ </XDSSideNavSection>++ <XDSSideNavSection title="Settings">+ <XDSSideNavItem label="General" href="/settings/general" />+ <XDSSideNavItem label="Security" href="/settings/security" />+ </XDSSideNavSection>+ </XDSSideNav>+ }>+ <Content />+</XDSAppShell>`,+ },+ ],+ components: [+ {+ name: 'XDSSideNav',+ description:+ 'Container with five zones: header, topContent, children (scrollable), footer, and footerIcons.',+ props: [+ {+ name: 'header',+ type: 'ReactNode',+ description: 'Header area (typically XDSSideNavHeader). Sticky.',+ },+ {+ name: 'topContent',+ type: 'ReactNode',+ description: 'Content below the header, e.g., a create button.',+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Navigation sections and items. Scrollable.',+ },+ {+ name: 'footer',+ type: 'ReactNode',+ description: 'Footer area above the icon bar.',+ },+ {+ name: 'footerIcons',+ type: 'ReactNode',+ description: 'Footer icon bar.',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSSideNav+ header={<XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />}+ topContent={<XDSButton label="Create new" variant="primary" />}>+ <XDSSideNavSection title="Main">+ <XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected href="/dashboard" />+ <XDSSideNavItem label="Projects" icon={FolderIcon} href="/projects" />+ </XDSSideNavSection>+</XDSSideNav>`,+ },+ ],+ },+ {+ name: 'XDSSideNavHeader',+ description:+ 'Product/suite/account header with smart interaction boundary logic for links and a menu popover.',+ props: [+ {+ name: 'title',+ type: 'string',+ description: 'Product/app name.',+ required: true,+ },+ {+ name: 'icon',+ type: 'ReactNode',+ description: 'Product/app icon.',+ },+ {+ name: 'titleHref',+ type: 'string',+ description: 'Link for the title.',+ },+ {+ name: 'supertitle',+ type: 'string',+ description: 'Text above the title.',+ },+ {+ name: 'supertitleHref',+ type: 'string',+ description: 'Link for the supertitle.',+ },+ {+ name: 'subtitle',+ type: 'string',+ description: 'Text below the title.',+ },+ {+ name: 'subtitleHref',+ type: 'string',+ description: 'Link for the subtitle.',+ },+ {+ name: 'menu',+ type: 'ReactNode',+ description: 'Menu content rendered inside a popover.',+ },+ ],+ examples: [+ {+ label: 'Title link only',+ code: `<XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />`,+ },+ {+ label: 'With supertitle and subtitle',+ code: `<XDSSideNavHeader+ icon={<AppIcon />}+ supertitle="Acme Corp"+ supertitleHref="/org"+ title="My App"+ titleHref="/"+ subtitle="v2.0"+/>`,+ },+ {+ label: 'With menu',+ code: `<XDSSideNavHeader+ icon={<AppIcon />}+ title="My App"+ titleHref="/"+ menu={<WorkspaceSwitcher />}+/>`,+ },+ ],+ },+ {+ name: 'XDSSideNavItem',+ description:+ 'Navigation item with icon, selected state, optional end content, and nesting support via children.',+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Item label.',+ required: true,+ },+ {+ name: 'as',+ type: 'XDSLinkComponentType',+ description: 'Custom link component.',+ },+ {+ name: 'icon',+ type: 'XDSIconType',+ description: 'Icon displayed in the outline (unselected) variant.',+ },+ {+ name: 'selectedIcon',+ type: 'XDSIconType',+ description:+ 'Icon displayed when the item is selected (filled variant).',+ },+ {+ name: 'isSelected',+ type: 'boolean',+ description: 'Marks this item as the current page.',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Disabled state.',+ default: 'false',+ },+ {+ name: 'href',+ type: 'string',+ description: 'Navigation URL.',+ },+ {+ name: 'onClick',+ type: '(e: MouseEvent) => void',+ description: 'Click handler.',+ },+ {+ name: 'endContent',+ type: 'ReactNode',+ description: 'Right-side content such as badges or counts.',+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Sub-items for nesting.',+ },+ ],+ examples: [+ {+ label: 'Basic link',+ code: `<XDSSideNavItem label="Dashboard" icon={HomeIcon} href="/dashboard" />`,+ },+ {+ label: 'Selected with alternate icon and badge',+ code: `<XDSSideNavItem+ label="Dashboard"+ icon={HomeIcon}+ selectedIcon={HomeIconSolid}+ isSelected+ href="/dashboard"+ endContent={<XDSBadge>3</XDSBadge>}+/>`,+ },+ {+ label: 'Nested items',+ code: `<XDSSideNavItem label="Settings" icon={GearIcon} href="/settings">+ <XDSSideNavItem label="General" href="/settings/general" />+ <XDSSideNavItem label="Security" href="/settings/security" />+</XDSSideNavItem>`,+ },+ ],+ },+ {+ name: 'XDSSideNavSection',+ description:+ 'Section grouping with an optional title, subtitle, and end content.',+ props: [+ {+ name: 'title',+ type: 'string',+ description: 'Section title.',+ required: true,+ },+ {+ name: 'subtitle',+ type: 'string',+ description: 'Section subtitle.',+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Section items.',+ },+ {+ name: 'endContent',+ type: 'ReactNode',+ description: 'Right-side content in the section header.',+ },+ {+ name: 'isHeaderHidden',+ type: 'boolean',+ description:+ 'Visually hides the section header while keeping it accessible to screen readers.',+ default: 'false',+ },+ ],+ examples: [+ {+ label: 'Basic section',+ code: `<XDSSideNavSection title="Main">+ <XDSSideNavItem label="Dashboard" href="/dashboard" />+ <XDSSideNavItem label="Projects" href="/projects" />+</XDSSideNavSection>`,+ },+ {+ label: 'With end content and hidden header',+ code: `<XDSSideNavSection title="Settings" endContent={<XDSBadge>New</XDSBadge>}>+ <XDSSideNavItem label="General" href="/settings/general" />+ <XDSSideNavItem label="Security" href="/settings/security" />+</XDSSideNavSection>`,+ },+ {+ label: 'Hidden header (used with TopNav)',+ code: `<XDSSideNavSection title="Main" isHeaderHidden>+ <XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected href="/dashboard" />+</XDSSideNavSection>`,+ },+ ],+ },+ ],+};diff --git a/packages/core/src/SideNav/XDSSideNav.tsx b/packages/core/src/SideNav/XDSSideNav.tsxindex 4cafa9bac9..53294526cc 100644--- a/packages/core/src/SideNav/XDSSideNav.tsx+++ b/packages/core/src/SideNav/XDSSideNav.tsx@@ -8,7 +8,7 @@* children (scrollable), footer, and footerIcons (sticky bottom).** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/SideNav/README.md+ * - /packages/core/src/SideNav/SideNav.doc.mjs* - /packages/core/src/SideNav/XDSSideNav.test.tsx* - /packages/core/src/SideNav/index.ts* - /apps/storybook/stories/SideNav.stories.tsxdiff --git a/packages/core/src/SideNav/XDSSideNavHeader.tsx b/packages/core/src/SideNav/XDSSideNavHeader.tsxindex 8d83f35be8..95eb1bf060 100644--- a/packages/core/src/SideNav/XDSSideNavHeader.tsx+++ b/packages/core/src/SideNav/XDSSideNavHeader.tsx@@ -8,7 +8,7 @@* Composes useXDSPopover internally when menu prop is provided.** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/SideNav/README.md+ * - /packages/core/src/SideNav/SideNav.doc.mjs* - /packages/core/src/SideNav/XDSSideNav.test.tsx* - /packages/core/src/SideNav/index.ts* - /apps/storybook/stories/SideNav.stories.tsxdiff --git a/packages/core/src/SideNav/XDSSideNavItem.tsx b/packages/core/src/SideNav/XDSSideNavItem.tsxindex 8bd985a888..8ed41bd24c 100644--- a/packages/core/src/SideNav/XDSSideNavItem.tsx+++ b/packages/core/src/SideNav/XDSSideNavItem.tsx@@ -7,7 +7,7 @@* Navigation item with icon, selected state, and nesting.** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/SideNav/README.md+ * - /packages/core/src/SideNav/SideNav.doc.mjs* - /packages/core/src/SideNav/XDSSideNav.test.tsx* - /packages/core/src/SideNav/index.ts* - /apps/storybook/stories/SideNav.stories.tsxdiff --git a/packages/core/src/SideNav/XDSSideNavSection.tsx b/packages/core/src/SideNav/XDSSideNavSection.tsxindex 775fb2673b..b2a46d9f7f 100644--- a/packages/core/src/SideNav/XDSSideNavSection.tsx+++ b/packages/core/src/SideNav/XDSSideNavSection.tsx@@ -7,7 +7,7 @@* Section grouping for navigation items with optional title and end content.** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/SideNav/README.md+ * - /packages/core/src/SideNav/SideNav.doc.mjs* - /packages/core/src/SideNav/XDSSideNav.test.tsx* - /packages/core/src/SideNav/index.ts* - /apps/storybook/stories/SideNav.stories.tsxdiff --git a/packages/core/src/SideNav/index.ts b/packages/core/src/SideNav/index.tsindex 40d6dfea8b..1ca276f88e 100644--- a/packages/core/src/SideNav/index.ts+++ b/packages/core/src/SideNav/index.ts@@ -4,7 +4,7 @@* @output Exports XDSSideNav, XDSSideNavHeader, XDSSideNavItem, XDSSideNavSection* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/SideNav/README.md+ * SYNC: When modified, update this header and /packages/core/src/SideNav/SideNav.doc.mjs*/export {XDSSideNav} from './XDSSideNav';diff --git a/packages/core/src/Skeleton/README.md b/packages/core/src/Skeleton/README.mddeleted file mode 100644index 3710a87f95..0000000000--- a/packages/core/src/Skeleton/README.md+++ /dev/null@@ -1,102 +0,0 @@-# Skeleton--A placeholder loading component that displays an animated pulsing effect while content is loading.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Pulsing Animation**: Smooth opacity animation using stepped timing for a subtle shimmer effect-- **Staggered Animation**: Sequential skeletons can be staggered to create a wave effect-- **High Contrast Support**: Automatically adjusts for users with `prefers-contrast: more`-- **Flexible Sizing**: Width and height props accept pixels or any CSS value-- **Token-aligned Radius**: Border radius options map directly to design tokens--## Usage--```tsx-import { XDSSkeleton } from '@xds/core/Skeleton';--// Basic text placeholder-<XDSSkeleton width={200} height={16} />--// Circular avatar placeholder-<XDSSkeleton width={40} height={40} radius="rounded" />--// Full-width with percentage-<XDSSkeleton width="100%" height={20} />--// Staggered animation for multiple skeletons-<div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>- <XDSSkeleton width={300} height={16} index={0} />- <XDSSkeleton width={280} height={16} index={1} />- <XDSSkeleton width={320} height={16} index={2} />-</div>-```--## Props--| Prop | Type | Default | Description |-| ------------- | ------------------------------------------------------------------------- | ------------- | ----------------------------------------------- |-| `width` | `number \| string` | `'100%'` | Width in pixels (number) or CSS value (string) |-| `height` | `number \| string` | `'100%'` | Height in pixels (number) or CSS value (string) |-| `radius` | `'none' \| 'inner' \| 'content' \| 'element' \| 'container' \| 'rounded'` | `'container'` | Border radius using design tokens |-| `index` | `number` | `0` | Index for staggered animation timing |-| `data-testid` | `string` | — | Test ID for testing |--## Radius Options--| Value | Use Case |-| ----------- | --------------------------------------- |-| `none` | Sharp corners (images, rectangles) |-| `inner` | Inner elements |-| `content` | Content areas |-| `element` | Standard elements |-| `container` | Container-level rounding (default) |-| `rounded` | Fully rounded (avatars, pills, circles) |--## Animation Timing--The skeleton uses three timing constants:--- **DELAY_TIME** (1000ms): Initial delay before animation starts-- **FADE_TIME** (1000ms): Duration of one opacity cycle-- **STAGGER_TIME** (100ms): Delay increment between sequential elements--For element at index `n`, animation starts at: `DELAY_TIME + (STAGGER_TIME × n)`--## Theming--Themes can override `Skeleton` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- skeleton: {- root: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------- | ---------------------------- |-| `root` | Root skeleton element styles |--## Files--| File | Role | Purpose |-| ----------------- | ----- | --------------------------- |-| `index.ts` | Entry | Exports component and types |-| `XDSSkeleton.tsx` | Core | Component implementation |--## Implementation Notes--- Uses `steps(10, end)` timing function for a subtle shimmer effect-- Animation alternates between 0.25 and 1.0 opacity-- Background color comes from the `glimmer` token, with `glimmerHighContrast` for accessibility-- Numeric dimensions are converted to pixels; strings are passed through as-isdiff --git a/packages/core/src/Skeleton/Skeleton.doc.mjs b/packages/core/src/Skeleton/Skeleton.doc.mjsnew file mode 100644index 0000000000..8ccd4fa5e4--- /dev/null+++ b/packages/core/src/Skeleton/Skeleton.doc.mjs@@ -0,0 +1,80 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Skeleton',+ description:+ 'A placeholder loading component that displays an animated pulsing effect while content is loading.',+ features: [+ 'Pulsing Animation: Smooth opacity animation using stepped timing for a subtle shimmer effect',+ 'Staggered Animation: Sequential skeletons can be staggered to create a wave effect',+ 'High Contrast Support: Automatically adjusts for users with prefers-contrast: more',+ 'Flexible Sizing: Width and height props accept pixels or any CSS value',+ 'Token-aligned Radius: Border radius options map directly to design tokens',+ ],+ props: [+ {+ name: 'width',+ type: 'number | string',+ description: 'Width in pixels (number) or CSS value (string).',+ default: "'100%'",+ },+ {+ name: 'height',+ type: 'number | string',+ description: 'Height in pixels (number) or CSS value (string).',+ default: "'100%'",+ },+ {+ name: 'radius',+ type: "'none' | 'inner' | 'content' | 'element' | 'container' | 'rounded'",+ description:+ 'Border radius using design tokens. Use none for sharp corners, rounded for fully rounded (avatars, pills, circles).',+ default: "'container'",+ },+ {+ name: 'index',+ type: 'number',+ description:+ 'Index for staggered animation timing. For element at index n, animation starts at DELAY_TIME + (STAGGER_TIME × n).',+ default: '0',+ },+ ],+ examples: [+ {+ label: 'Basic text placeholder',+ code: '<XDSSkeleton width={200} height={16} />',+ },+ {+ label: 'Circular avatar placeholder',+ code: '<XDSSkeleton width={40} height={40} radius="rounded" />',+ },+ {+ label: 'Full-width with percentage',+ code: '<XDSSkeleton width="100%" height={20} />',+ },+ {+ label: 'Staggered animation for multiple skeletons',+ code: `<div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>+ <XDSSkeleton width={300} height={16} index={0} />+ <XDSSkeleton width={280} height={16} index={1} />+ <XDSSkeleton width={320} height={16} index={2} />+</div>`,+ },+ ],+ theming: {+ componentKey: 'skeleton',+ surfaces: [+ {+ name: 'root',+ description: 'Root skeleton element styles',+ },+ ],+ },+ notes: [+ 'Uses steps(10, end) timing function for a subtle shimmer effect.',+ 'Animation alternates between 0.25 and 1.0 opacity.',+ 'Background color comes from the glimmer token, with glimmerHighContrast for accessibility.',+ 'Numeric dimensions are converted to pixels; strings are passed through as-is.',+ 'Animation timing constants: DELAY_TIME (1000ms) initial delay before animation starts, FADE_TIME (1000ms) duration of one opacity cycle, STAGGER_TIME (100ms) delay increment between sequential elements.',+ ],+};diff --git a/packages/core/src/Skeleton/XDSSkeleton.tsx b/packages/core/src/Skeleton/XDSSkeleton.tsxindex 818584d1ef..e0c8beb178 100644--- a/packages/core/src/Skeleton/XDSSkeleton.tsx+++ b/packages/core/src/Skeleton/XDSSkeleton.tsx@@ -5,7 +5,7 @@* @position Core implementation of skeleton loading placeholder** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Skeleton/README.md+ * - /packages/core/src/Skeleton/Skeleton.doc.mjs* - /packages/core/src/Skeleton/index.ts* - /apps/storybook/stories/Skeleton.stories.tsx*/diff --git a/packages/core/src/Slider/README.md b/packages/core/src/Slider/README.mddeleted file mode 100644index 3e6d44cb21..0000000000--- a/packages/core/src/Slider/README.md+++ /dev/null@@ -1,185 +0,0 @@-# Slider--A slider component for selecting numeric values or ranges with full keyboard and pointer support.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Single & range modes**: Pass a `number` for single thumb, `[number, number]` for range-- **Orientation**: Supports `horizontal` and `vertical` layouts-- **Value display**: Tooltip (default), inline text, or none-- **Tick marks**: Optional marks at specified positions with labels-- **Keyboard navigation**: Arrow keys, Page Up/Down, Home/End-- **Drag interaction**: Pointer capture for smooth dragging-- **Custom formatting**: `formatValue` function for display and `aria-valuetext`-- **Field integration**: Uses `XDSField` for label, description, required/optional, and status messaging-- **Accessible**: Uses `role="slider"` with full ARIA attributes--## Usage--```tsx-import { XDSSlider } from '@xds/core/Slider';--// Basic single value-<XDSSlider label="Volume" value={50} onChange={setValue} />--// Range slider-<XDSSlider- label="Price range"- value={[20, 80]}- onChange={setRange}-/>--// With custom formatting-<XDSSlider- label="Temperature"- value={72}- onChange={setTemp}- min={32}- max={212}- formatValue={(v) => `${v}°F`}-/>--// With step and marks-<XDSSlider- label="Rating"- value={3}- onChange={setRating}- min={1}- max={5}- step={1}- marks={[- { value: 1, label: 'Poor' },- { value: 3, label: 'Average' },- { value: 5, label: 'Excellent' },- ]}-/>--// Text value display-<XDSSlider- label="Opacity"- value={75}- onChange={setOpacity}- formatValue={(v) => `${v}%`}- valueDisplay="text"-/>--// Range with minimum gap-<XDSSlider- label="Date range"- value={[10, 90]}- onChange={setDateRange}- minStepsBetweenThumbs={5}-/>--// With onChangeEnd for committing value-<XDSSlider- label="Brightness"- value={brightness}- onChange={setBrightness}- onChangeEnd={commitBrightness}-/>--// Vertical orientation-<XDSSlider- label="Level"- value={60}- onChange={setLevel}- orientation="vertical"-/>--// Disabled-<XDSSlider- label="Locked"- value={50}- onChange={() => {}}- isDisabled-/>-```--## Props--| Prop | Type | Default | Description |-| --------------- | ------------------------------------------ | -------------- | -------------------------------------------------------- |-| `label` | `string` | — | Label text (always rendered for accessibility) |-| `isLabelHidden` | `boolean` | `false` | Whether to visually hide the label |-| `description` | `string` | — | Description text below the label |-| `isDisabled` | `boolean` | `false` | Whether the slider is disabled |-| `isOptional` | `boolean` | `false` | Whether the field is optional |-| `isRequired` | `boolean` | `false` | Whether the field is required |-| `status` | `XDSInputStatus` | — | Status indicator (`{ type, message }`) |-| `labelTooltip` | `string` | — | Tooltip text for an info icon next to the label |-| `min` | `number` | `0` | Minimum value |-| `max` | `number` | `100` | Maximum value |-| `step` | `number` | `1` | Step increment |-| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Orientation of the slider |-| `formatValue` | `(value: number) => string` | — | Custom value formatting for display and `aria-valuetext` |-| `valueDisplay` | `'tooltip' \| 'text' \| 'none'` | `'tooltip'` | How the current value is displayed |-| `marks` | `Array<{ value: number; label?: string }>` | — | Tick marks at specified positions with optional labels |-| `xstyle` | `StyleXStyles` | — | Additional styles |-| `data-testid` | `string` | — | Test ID for the root element |--### Single Value Mode--| Prop | Type | Description |-| ------------- | ------------------------- | ------------------------------------------ |-| `value` | `number` | Current value |-| `onChange` | `(value: number) => void` | Callback fired on value change during drag |-| `onChangeEnd` | `(value: number) => void` | Callback fired when drag ends |--### Range Mode--| Prop | Type | Default | Description |-| ----------------------- | ----------------------------------- | ------- | -------------------------------------- |-| `value` | `[number, number]` | — | Current range `[min, max]` |-| `onChange` | `(value: [number, number]) => void` | — | Callback fired on value change |-| `onChangeEnd` | `(value: [number, number]) => void` | — | Callback fired when drag ends |-| `minStepsBetweenThumbs` | `number` | `0` | Minimum number of steps between thumbs |--## Theming--Themes can override `Slider` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- slider: {- root: myStyles,- track: myStyles,- filledTrack: myStyles,- thumb: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------------- | -------------------------- |-| `root` | Root container styles |-| `track` | Background track styles |-| `filledTrack` | Filled/active track styles |-| `thumb` | Thumb handle styles |--## Files--| File | Role | Purpose |-| -------------------- | ----- | --------------------------------------------------- |-| `index.ts` | Entry | Exports XDSSlider component and all type variants |-| `XDSSlider.tsx` | Core | Slider component with single and range mode support |-| `XDSSlider.test.tsx` | Test | Unit tests |--## Implementation Notes--- The component uses `forwardRef` — the ref is merged with an internal `trackRef` for pointer position calculations-- Pointer capture is used during drag for smooth interaction even when the cursor leaves the track-- `snapToStep` rounds to the nearest valid step value; `clamp` enforces min/max bounds-- In range mode, the closest thumb is selected on track click based on distance to each thumb-- `minStepsBetweenThumbs` prevents range thumbs from overlapping by enforcing a minimum gap-- Keyboard navigation: Arrow keys ±1 step, Page Up/Down ±10 steps, Home/End jump to min/max-- Tooltip display wraps each thumb in `XDSTooltip` with `delay={0}` and `focusTrigger="always"`-- Vertical orientation inverts the Y axis (bottom = min, top = max)diff --git a/packages/core/src/Slider/Slider.doc.mjs b/packages/core/src/Slider/Slider.doc.mjsnew file mode 100644index 0000000000..99a50878cf--- /dev/null+++ b/packages/core/src/Slider/Slider.doc.mjs@@ -0,0 +1,242 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Slider',+ description:+ 'A slider component for selecting numeric values or ranges with full keyboard and pointer support.',+ features: [+ 'Single & range modes: Pass a `number` for single thumb, `[number, number]` for range',+ 'Orientation: Supports `horizontal` and `vertical` layouts',+ 'Value display: Tooltip (default), inline text, or none',+ 'Tick marks: Optional marks at specified positions with labels',+ 'Keyboard navigation: Arrow keys, Page Up/Down, Home/End',+ 'Drag interaction: Pointer capture for smooth dragging',+ 'Custom formatting: `formatValue` function for display and `aria-valuetext`',+ 'Field integration: Uses `XDSField` for label, description, required/optional, and status messaging',+ 'Accessible: Uses `role="slider"` with full ARIA attributes',+ ],+ examples: [+ {+ label: 'Basic single value',+ code: '<XDSSlider label="Volume" value={50} onChange={setValue} />',+ },+ {+ label: 'Range slider',+ code: `<XDSSlider+ label="Price range"+ value={[20, 80]}+ onChange={setRange}+/>`,+ },+ {+ label: 'With custom formatting',+ code: `<XDSSlider+ label="Temperature"+ value={72}+ onChange={setTemp}+ min={32}+ max={212}+ formatValue={(v) => \`\${v}°F\`}+/>`,+ },+ {+ label: 'With step and marks',+ code: `<XDSSlider+ label="Rating"+ value={3}+ onChange={setRating}+ min={1}+ max={5}+ step={1}+ marks={[+ { value: 1, label: 'Poor' },+ { value: 3, label: 'Average' },+ { value: 5, label: 'Excellent' },+ ]}+/>`,+ },+ {+ label: 'Text value display',+ code: `<XDSSlider+ label="Opacity"+ value={75}+ onChange={setOpacity}+ formatValue={(v) => \`\${v}%\`}+ valueDisplay="text"+/>`,+ },+ {+ label: 'Range with minimum gap',+ code: `<XDSSlider+ label="Date range"+ value={[10, 90]}+ onChange={setDateRange}+ minStepsBetweenThumbs={5}+/>`,+ },+ {+ label: 'With onChangeEnd for committing value',+ code: `<XDSSlider+ label="Brightness"+ value={brightness}+ onChange={setBrightness}+ onChangeEnd={commitBrightness}+/>`,+ },+ {+ label: 'Vertical orientation',+ code: `<XDSSlider+ label="Level"+ value={60}+ onChange={setLevel}+ orientation="vertical"+/>`,+ },+ {+ label: 'Disabled',+ code: `<XDSSlider+ label="Locked"+ value={50}+ onChange={() => {}}+ isDisabled+/>`,+ },+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Label text (always rendered for accessibility).',+ required: true,+ },+ {+ name: 'value',+ type: 'number | [number, number]',+ description:+ 'Current value — a `number` for single thumb mode or `[number, number]` for range mode.',+ required: true,+ },+ {+ name: 'onChange',+ type: '(value: number) => void | (value: [number, number]) => void',+ description: 'Callback fired on value change during drag.',+ },+ {+ name: 'onChangeEnd',+ type: '(value: number) => void | (value: [number, number]) => void',+ description: 'Callback fired when drag ends.',+ },+ {+ name: 'min',+ type: 'number',+ description: 'Minimum value.',+ default: '0',+ },+ {+ name: 'max',+ type: 'number',+ description: 'Maximum value.',+ default: '100',+ },+ {+ name: 'step',+ type: 'number',+ description: 'Step increment.',+ default: '1',+ },+ {+ name: 'orientation',+ type: "'horizontal' | 'vertical'",+ description: 'Orientation of the slider.',+ default: "'horizontal'",+ },+ {+ name: 'formatValue',+ type: '(value: number) => string',+ description:+ 'Custom value formatting function used for display and `aria-valuetext`.',+ },+ {+ name: 'valueDisplay',+ type: "'tooltip' | 'text' | 'none'",+ description: 'How the current value is displayed.',+ default: "'tooltip'",+ },+ {+ name: 'marks',+ type: 'Array<{ value: number; label?: string }>',+ description: 'Tick marks at specified positions with optional labels.',+ },+ {+ name: 'minStepsBetweenThumbs',+ type: 'number',+ description:+ 'Minimum number of steps between thumbs in range mode; prevents thumbs from overlapping.',+ default: '0',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Whether the slider is disabled.',+ default: 'false',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description: 'Whether the field is optional.',+ default: 'false',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description: 'Whether the field is required.',+ default: 'false',+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: 'Whether to visually hide the label.',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Description text rendered below the label.',+ },+ {+ name: 'status',+ type: 'XDSInputStatus',+ description:+ 'Status indicator object (`{ type, message }`) for validation feedback.',+ },+ {+ name: 'labelTooltip',+ type: 'string',+ description: 'Tooltip text for an info icon displayed next to the label.',+ },+ ],+ theming: {+ componentKey: 'slider',+ surfaces: [+ {name: 'root', description: 'Root container element'},+ {name: 'track', description: 'Background track element'},+ {name: 'filledTrack', description: 'Filled/active portion of the track'},+ {name: 'thumb', description: 'Draggable thumb handle'},+ ],+ },+ accessibility: [+ 'Uses `role="slider"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-valuetext` on each thumb.',+ 'The label is always rendered in the DOM for accessibility even when `isLabelHidden` is true.',+ 'Tooltip display uses `XDSTooltip` with `delay={0}` and `focusTrigger="always"` so value is always visible on focus.',+ ],+ keyboard:+ 'Arrow keys ±1 step, Page Up/Down ±10 steps, Home/End jump to min/max.',+ notes: [+ 'The component uses `forwardRef` — the ref is merged with an internal `trackRef` used for pointer position calculations.',+ 'Pointer capture is used during drag for smooth interaction even when the cursor leaves the track.',+ '`snapToStep` rounds to the nearest valid step value; `clamp` enforces min/max bounds.',+ 'In range mode, the closest thumb to the click position is selected automatically.',+ '`minStepsBetweenThumbs` enforces a minimum gap between range thumbs.',+ 'Vertical orientation inverts the Y axis so that bottom = min and top = max.',+ ],+};diff --git a/packages/core/src/Slider/XDSSlider.tsx b/packages/core/src/Slider/XDSSlider.tsxindex eeb8aace06..a456a19bb7 100644--- a/packages/core/src/Slider/XDSSlider.tsx+++ b/packages/core/src/Slider/XDSSlider.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSSlider.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Slider/README.md+ * - /packages/core/src/Slider/Slider.doc.mjs* - /packages/core/src/Slider/XDSSlider.test.tsx* - /packages/core/src/Slider/index.ts* - /apps/storybook/stories/Slider.stories.tsxdiff --git a/packages/core/src/Spinner/README.md b/packages/core/src/Spinner/README.mddeleted file mode 100644index c3ee269865..0000000000--- a/packages/core/src/Spinner/README.md+++ /dev/null@@ -1,95 +0,0 @@-# Spinner--A pure spinner component for indicating loading state. No layout, no text — just the spinning indicator.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **CSS Border Animation**: Lightweight border-based spinner with smooth 360° rotation-- **Size Variants**: Three sizes (sm, md, lg) matching existing inline spinners-- **Shade Support**: Default shade for light backgrounds, onMedia for dark/accent backgrounds-- **Accessible**: `role="status"` and `aria-label="Loading"` by default--## Usage--```tsx-import { XDSSpinner } from '@xds/core/Spinner';--// Default spinner-<XDSSpinner />--// Small spinner-<XDSSpinner size="sm" />--// Large spinner on a dark background-<XDSSpinner size="lg" shade="onMedia" />-```--### Composing with layout--XDSSpinner is intentionally minimal. Compose with layout and text components for loading states:--```tsx-import {XDSSpinner} from '@xds/core/Spinner';-import {XDSVStack} from '@xds/core/Layout';-import {XDSText} from '@xds/core/Text';--<XDSVStack gap="space2" align="center">- <XDSSpinner size="lg" />- <XDSText color="secondary">Loading...</XDSText>-</XDSVStack>;-```--## Props--| Prop | Type | Default | Description |-| ------------- | ------------------------ | ----------- | ----------------------------------------- |-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Spinner size (12px, 20px, 28px) |-| `shade` | `'default' \| 'onMedia'` | `'default'` | Color shade for light or dark backgrounds |-| `data-testid` | `string` | — | Test ID for testing |--## Size Reference--| Size | Dimensions | Border Width | Use Case |-| ---- | ---------- | ------------ | ----------------------------- |-| `sm` | 12×12px | 2px | Inline with text, buttons |-| `md` | 20×20px | 2px | Default, standalone indicator |-| `lg` | 28×28px | 3px | Full-page or section loading |--## Theming--Themes can override `Spinner` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- spinner: {- root: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------- | --------------------------- |-| `root` | Root spinner element styles |--## Files--| File | Role | Purpose |-| --------------------- | ----- | --------------------------- |-| `index.ts` | Entry | Exports component and types |-| `XDSSpinner.tsx` | Core | Component implementation |-| `XDSSpinner.test.tsx` | Test | Unit tests |--## Implementation Notes--- Uses CSS `border` technique: three visible borders + one transparent for the gap-- Animation: `rotate(360deg)` at 0.6s linear infinite-- Color inherits from `currentColor`, controlled by shade styles using theme tokens-- Element is a `<span>` with `display: inline-block` for inline composabilitydiff --git a/packages/core/src/Spinner/Spinner.doc.mjs b/packages/core/src/Spinner/Spinner.doc.mjsnew file mode 100644index 0000000000..b33a107a58--- /dev/null+++ b/packages/core/src/Spinner/Spinner.doc.mjs@@ -0,0 +1,65 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Spinner',+ description:+ 'A pure spinner component for indicating loading state. No layout, no text — just the spinning indicator.',+ features: [+ 'CSS Border Animation: Lightweight border-based spinner with smooth 360° rotation',+ 'Size Variants: Three sizes (sm, md, lg) matching existing inline spinners',+ 'Shade Support: Default shade for light backgrounds, onMedia for dark/accent backgrounds',+ 'Accessible: role="status" and aria-label="Loading" by default',+ ],+ props: [+ {+ name: 'size',+ type: "'sm' | 'md' | 'lg'",+ description: 'Spinner size (10px, 14px, 18px).',+ default: "'md'",+ },+ {+ name: 'shade',+ type: "'default' | 'onMedia'",+ description: 'Color shade for light or dark backgrounds.',+ default: "'default'",+ },+ ],+ examples: [+ {+ label: 'Default',+ code: `<XDSSpinner />`,+ },+ {+ label: 'Small',+ code: `<XDSSpinner size="sm" />`,+ },+ {+ label: 'Large on dark background',+ code: `<XDSSpinner size="lg" shade="onMedia" />`,+ },+ {+ label: 'Composing with layout and text',+ code: `<XDSVStack gap="space2" align="center">+ <XDSSpinner size="lg" />+ <XDSText color="secondary">Loading...</XDSText>+</XDSVStack>`,+ },+ ],+ theming: {+ componentKey: 'spinner',+ surfaces: [+ {+ name: 'root',+ description: 'Root spinner element styles',+ },+ ],+ },+ notes: [+ 'Uses CSS border technique: three visible borders + one transparent for the gap.',+ 'Animation: rotate(360deg) at 0.75s linear infinite.',+ 'Color inherits from currentColor, controlled by shade styles using theme tokens.',+ 'Element is a <span> with display: inline-block for inline composability.',+ 'XDSSpinner is intentionally minimal — compose with layout and text components for full loading states.',+ 'Size reference: sm = 10×10px / 3px border, md = 14×14px / 3px border, lg = 18×18px / 3px border.',+ ],+};diff --git a/packages/core/src/Spinner/XDSSpinner.tsx b/packages/core/src/Spinner/XDSSpinner.tsxindex 0ff51922d6..4fc930dd9c 100644--- a/packages/core/src/Spinner/XDSSpinner.tsx+++ b/packages/core/src/Spinner/XDSSpinner.tsx@@ -5,7 +5,7 @@* @position Core implementation of spinner loading indicator** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Spinner/README.md+ * - /packages/core/src/Spinner/Spinner.doc.mjs* - /packages/core/src/Spinner/XDSSpinner.test.tsx* - /packages/core/src/Spinner/index.ts* - /apps/storybook/stories/Spinner.stories.tsxdiff --git a/packages/core/src/Stack/README.md b/packages/core/src/Stack/README.mddeleted file mode 100644index 7e3b31cdc9..0000000000--- a/packages/core/src/Stack/README.md+++ /dev/null@@ -1,241 +0,0 @@-# Stack--Stack layout primitives for arranging items in horizontal or vertical sequences.--<!-- SYNC: When files in this directory change, update this document. -->--## Overview--The Stack system provides flexbox-based layout components with:--- Horizontal (`XDSHStack`) and vertical (`XDSVStack`) stacking-- Themed spacing via gap tokens-- Individual item control via `XDSStackItem`-- Polymorphic rendering support--## Import--```tsx-import {- XDSHStack,- XDSVStack,- XDSStackItem,- stack,- stackItem,-} from '@xds/core/Layout';-```--## Components--### XDSHStack--Horizontal stack for arranging items left-to-right. Supports polymorphic rendering.--```tsx-// Basic horizontal stack-<XDSHStack gap="space2">- <Item />- <Item />-</XDSHStack>--// With alignment-<XDSHStack gap="space4" vAlign="center">- <Item />- <Item />-</XDSHStack>--// Polymorphic rendering-<XDSHStack element="nav" gap="space2">- <Link />- <Link />-</XDSHStack>-```--| Prop | Type | Default | Description |-| ---------- | ------------------------------------------- | ----------- | ------------------------------------------------------------------------ |-| `gap` | `SpacingScale` | — | Spacing token: `space0` `space1` `space2` `space3` `space4` `space5` ... |-| `vAlign` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` | Vertical alignment |-| `wrap` | `'nowrap' \| 'wrap' \| 'wrap-reverse'` | `'nowrap'` | Flex wrap behavior |-| `element` | `ElementType` | `'div'` | HTML element to render |-| `children` | `ReactNode` | — | Stack content |--### XDSVStack--Vertical stack for arranging items top-to-bottom. Supports polymorphic rendering.--```tsx-// Basic vertical stack-<XDSVStack gap="space2">- <Item />- <Item />-</XDSVStack>--// With alignment-<XDSVStack gap="space4" hAlign="center">- <Item />- <Item />-</XDSVStack>--// Polymorphic rendering-<XDSVStack element="main" gap="space4">- <Header />- <Content />-</XDSVStack>-```--| Prop | Type | Default | Description |-| ---------- | ------------------------------------------- | ----------- | ------------------------------------------------------------------------ |-| `gap` | `SpacingScale` | — | Spacing token: `space0` `space1` `space2` `space3` `space4` `space5` ... |-| `hAlign` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` | Horizontal alignment |-| `wrap` | `'nowrap' \| 'wrap' \| 'wrap-reverse'` | `'nowrap'` | Flex wrap behavior |-| `element` | `ElementType` | `'div'` | HTML element to render |-| `children` | `ReactNode` | — | Stack content |--### XDSStackItem--Stack item for controlling individual item behavior within a stack. Supports polymorphic rendering.--```tsx-// Basic usage with fill-<XDSHStack gap="space2">- <XDSStackItem size="static">Logo</XDSStackItem>- <XDSStackItem size="fill">Content</XDSStackItem>- <XDSStackItem size="static">Actions</XDSStackItem>-</XDSHStack>--// Override alignment-<XDSHStack vAlign="start">- <XDSStackItem crossAlignSelf="center">Centered</XDSStackItem>- <XDSStackItem>Top-aligned</XDSStackItem>-</XDSHStack>--// Polymorphic rendering-<XDSStackItem element="section" size="fill">- Section content-</XDSStackItem>-```--| Prop | Type | Default | Description |-| ---------------- | ------------------------------------------- | ---------- | ----------------------------- |-| `size` | `'static' \| 'fill'` | `'static'` | Flex grow behavior |-| `crossAlignSelf` | `'start' \| 'center' \| 'end' \| 'stretch'` | — | Override cross-axis alignment |-| `element` | `ElementType` | `'div'` | HTML element to render |-| `children` | `ReactNode` | — | Item content |--## Utilities--For advanced use cases, you can use the underlying StyleX utilities directly.--### stack--StyleX utility for creating flex containers.--```tsx-import {stack} from '@xds/core/Layout';-import * as stylex from '@stylexjs/stylex';--<div {...stylex.props(...stack({direction: 'horizontal', gap: 'space2'}))}>- <Child />- <Child />-</div>;-```--| Option | Type | Default | Description |-| ------------ | ------------------------------------------- | ---------- | ------------------------------------------------------------------------ |-| `direction` | `'horizontal' \| 'vertical'` | Required | Stack direction |-| `gap` | `SpacingScale` | — | Spacing token: `space0` `space1` `space2` `space3` `space4` `space5` ... |-| `crossAlign` | `'start' \| 'center' \| 'end' \| 'stretch'` | — | Cross-axis alignment |-| `wrap` | `'nowrap' \| 'wrap' \| 'wrap-reverse'` | `'nowrap'` | Flex wrap behavior |--### stackItem--StyleX utility for controlling flex item behavior.--```tsx-import {stackItem} from '@xds/core/Layout';-import * as stylex from '@stylexjs/stylex';--<div {...stylex.props(...stackItem({size: 'fill'}))}>Content</div>;-```--| Option | Type | Default | Description |-| ---------------- | ------------------------------------------- | ---------- | ----------------------------- |-| `size` | `'static' \| 'fill'` | `'static'` | Flex grow behavior |-| `crossAlignSelf` | `'start' \| 'center' \| 'end' \| 'stretch'` | — | Override cross-axis alignment |--## Spacing Scale--The `gap` prop uses spacing tokens from the theme:--| Token | Description |-| ---------- | -------------------- |-| `space0` | No spacing |-| `space0.5` | Extra small spacing |-| `space1` | Small spacing |-| `space2` | Medium-small spacing |-| `space3` | Medium spacing |-| `space4` | Medium-large spacing |-| `space5` | Large spacing |-| `space6` | Extra large spacing |-| `space7` | Maximum spacing |--## Common Patterns--### Header Layout--```tsx-<XDSHStack element="header" gap="space2">- <XDSStackItem size="static">- <Logo />- </XDSStackItem>- <XDSStackItem size="fill">- <Navigation />- </XDSStackItem>- <XDSStackItem size="static">- <UserMenu />- </XDSStackItem>-</XDSHStack>-```--### Sidebar Layout--```tsx-<XDSHStack gap="space4">- <XDSStackItem size="static">- <Sidebar />- </XDSStackItem>- <XDSStackItem size="fill">- <MainContent />- </XDSStackItem>-</XDSHStack>-```--### Page Layout--```tsx-<XDSVStack element="main" gap="space6">- <XDSStackItem size="static">- <PageHeader />- </XDSStackItem>- <XDSStackItem size="fill">- <PageContent />- </XDSStackItem>- <XDSStackItem size="static">- <PageFooter />- </XDSStackItem>-</XDSVStack>-```--## Files--| File | Role | Purpose |-| ----------------------- | --------- | ------------------------------------------------- |-| `index.ts` | Entry | Exports all stack utilities and components |-| `stack.stylex.ts` | Utility | StyleX styles for stack (flex container) behavior |-| `stackItem.stylex.ts` | Utility | StyleX styles for stack item behavior |-| `XDSHStack.tsx` | Component | Horizontal stack component |-| `XDSHStack.test.tsx` | Test | XDSHStack unit tests |-| `XDSVStack.tsx` | Component | Vertical stack component |-| `XDSVStack.test.tsx` | Test | XDSVStack unit tests |-| `XDSStackItem.tsx` | Component | Stack item wrapper component |-| `XDSStackItem.test.tsx` | Test | XDSStackItem unit tests |diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjsnew file mode 100644index 0000000000..bd75fe3cc3--- /dev/null+++ b/packages/core/src/Stack/Stack.doc.mjs@@ -0,0 +1,322 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Stack',+ description:+ 'Stack layout primitives for arranging items in horizontal or vertical sequences using flexbox-based layout with themed spacing tokens.',+ features: [+ 'Horizontal (XDSHStack) and vertical (XDSVStack) stacking',+ 'Themed spacing via gap tokens from the design system spacing scale',+ 'Individual item control via XDSStackItem',+ 'Polymorphic rendering support via the element prop',+ 'Low-level StyleX utilities (stack, stackItem) for advanced use cases',+ ],+ examples: [+ {+ label: 'Header layout',+ code: `<XDSHStack element="header" gap="space2">+ <XDSStackItem size="static">+ <Logo />+ </XDSStackItem>+ <XDSStackItem size="fill">+ <Navigation />+ </XDSStackItem>+ <XDSStackItem size="static">+ <UserMenu />+ </XDSStackItem>+</XDSHStack>`,+ },+ {+ label: 'Sidebar layout',+ code: `<XDSHStack gap="space4">+ <XDSStackItem size="static">+ <Sidebar />+ </XDSStackItem>+ <XDSStackItem size="fill">+ <MainContent />+ </XDSStackItem>+</XDSHStack>`,+ },+ {+ label: 'Page layout',+ code: `<XDSVStack element="main" gap="space6">+ <XDSStackItem size="static">+ <PageHeader />+ </XDSStackItem>+ <XDSStackItem size="fill">+ <PageContent />+ </XDSStackItem>+ <XDSStackItem size="static">+ <PageFooter />+ </XDSStackItem>+</XDSVStack>`,+ },+ {+ label: 'Override alignment per item',+ code: `<XDSHStack vAlign="start">+ <XDSStackItem crossAlignSelf="center">Centered</XDSStackItem>+ <XDSStackItem>Top-aligned</XDSStackItem>+</XDSHStack>`,+ },+ {+ label: 'StyleX utility — advanced use',+ code: `import {stack} from '@xds/core/Layout';+import * as stylex from '@stylexjs/stylex';++<div {...stylex.props(...stack({direction: 'horizontal', gap: 'space2'}))}>+ <Child />+ <Child />+</div>`,+ },+ ],+ notes: [+ "Import from '@xds/core/Layout': XDSHStack, XDSVStack, XDSStackItem, stack, stackItem.",+ 'The gap prop accepts spacing tokens: space0, space0.5, space1, space2, space3, space4, space5, space6, space7.',+ 'stack and stackItem are low-level StyleX utilities for advanced cases where the component API is insufficient.',+ ],+ components: [+ {+ name: 'XDSHStack',+ description:+ 'Horizontal stack for arranging items left-to-right. Supports polymorphic rendering.',+ props: [+ {+ name: 'gap',+ type: 'SpacingScale',+ description:+ 'Spacing token controlling the gap between items: space0, space1, space2, space3, space4, space5, space6, space7.',+ },+ {+ name: 'vAlign',+ type: "'start' | 'center' | 'end' | 'stretch'",+ description: 'Vertical (cross-axis) alignment of items.',+ default: "'stretch'",+ },+ {+ name: 'wrap',+ type: "'nowrap' | 'wrap' | 'wrap-reverse'",+ description: 'Flex wrap behavior.',+ default: "'nowrap'",+ },+ {+ name: 'element',+ type: 'ElementType',+ description: 'HTML element to render as the stack container.',+ default: "'div'",+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Stack content.',+ },+ ],+ examples: [+ {+ label: 'Basic horizontal stack',+ code: `<XDSHStack gap="space2">+ <Item />+ <Item />+</XDSHStack>`,+ },+ {+ label: 'With vertical alignment',+ code: `<XDSHStack gap="space4" vAlign="center">+ <Item />+ <Item />+</XDSHStack>`,+ },+ {+ label: 'Polymorphic rendering',+ code: `<XDSHStack element="nav" gap="space2">+ <Link />+ <Link />+</XDSHStack>`,+ },+ ],+ },+ {+ name: 'XDSVStack',+ description:+ 'Vertical stack for arranging items top-to-bottom. Supports polymorphic rendering.',+ props: [+ {+ name: 'gap',+ type: 'SpacingScale',+ description:+ 'Spacing token controlling the gap between items: space0, space1, space2, space3, space4, space5, space6, space7.',+ },+ {+ name: 'hAlign',+ type: "'start' | 'center' | 'end' | 'stretch'",+ description: 'Horizontal (cross-axis) alignment of items.',+ default: "'stretch'",+ },+ {+ name: 'wrap',+ type: "'nowrap' | 'wrap' | 'wrap-reverse'",+ description: 'Flex wrap behavior.',+ default: "'nowrap'",+ },+ {+ name: 'element',+ type: 'ElementType',+ description: 'HTML element to render as the stack container.',+ default: "'div'",+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Stack content.',+ },+ ],+ examples: [+ {+ label: 'Basic vertical stack',+ code: `<XDSVStack gap="space2">+ <Item />+ <Item />+</XDSVStack>`,+ },+ {+ label: 'With horizontal alignment',+ code: `<XDSVStack gap="space4" hAlign="center">+ <Item />+ <Item />+</XDSVStack>`,+ },+ {+ label: 'Polymorphic rendering',+ code: `<XDSVStack element="main" gap="space4">+ <Header />+ <Content />+</XDSVStack>`,+ },+ ],+ },+ {+ name: 'XDSStackItem',+ description:+ 'Stack item for controlling individual item behavior within a stack. Supports polymorphic rendering.',+ props: [+ {+ name: 'size',+ type: "'static' | 'fill'",+ description:+ 'Flex grow behavior: static keeps natural size, fill expands to consume remaining space.',+ default: "'static'",+ },+ {+ name: 'crossAlignSelf',+ type: "'start' | 'center' | 'end' | 'stretch'",+ description:+ 'Override the cross-axis alignment for this individual item, ignoring the parent stack alignment.',+ },+ {+ name: 'element',+ type: 'ElementType',+ description: 'HTML element to render as the item wrapper.',+ default: "'div'",+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Item content.',+ },+ ],+ examples: [+ {+ label: 'Static and fill sizing',+ code: `<XDSHStack gap="space2">+ <XDSStackItem size="static">Logo</XDSStackItem>+ <XDSStackItem size="fill">Content</XDSStackItem>+ <XDSStackItem size="static">Actions</XDSStackItem>+</XDSHStack>`,+ },+ {+ label: 'Override alignment per item',+ code: `<XDSHStack vAlign="start">+ <XDSStackItem crossAlignSelf="center">Centered</XDSStackItem>+ <XDSStackItem>Top-aligned</XDSStackItem>+</XDSHStack>`,+ },+ {+ label: 'Polymorphic rendering',+ code: `<XDSStackItem element="section" size="fill">+ Section content+</XDSStackItem>`,+ },+ ],+ },+ {+ name: 'stack',+ description:+ 'Low-level StyleX utility for creating flex containers with stack behavior. Use when the component API is insufficient.',+ props: [+ {+ name: 'direction',+ type: "'horizontal' | 'vertical'",+ description: 'Stack direction.',+ required: true,+ },+ {+ name: 'gap',+ type: 'SpacingScale',+ description:+ 'Spacing token controlling the gap between items: space0, space1, space2, space3, space4, space5, space6, space7.',+ },+ {+ name: 'crossAlign',+ type: "'start' | 'center' | 'end' | 'stretch'",+ description: 'Cross-axis alignment of all items.',+ },+ {+ name: 'wrap',+ type: "'nowrap' | 'wrap' | 'wrap-reverse'",+ description: 'Flex wrap behavior.',+ default: "'nowrap'",+ },+ ],+ examples: [+ {+ label: 'StyleX horizontal container',+ code: `import {stack} from '@xds/core/Layout';+import * as stylex from '@stylexjs/stylex';++<div {...stylex.props(...stack({direction: 'horizontal', gap: 'space2'}))}>+ <Child />+ <Child />+</div>`,+ },+ ],+ },+ {+ name: 'stackItem',+ description:+ 'Low-level StyleX utility for controlling flex item behavior. Use when the component API is insufficient.',+ props: [+ {+ name: 'size',+ type: "'static' | 'fill'",+ description:+ 'Flex grow behavior: static keeps natural size, fill expands to consume remaining space.',+ default: "'static'",+ },+ {+ name: 'crossAlignSelf',+ type: "'start' | 'center' | 'end' | 'stretch'",+ description:+ 'Override the cross-axis alignment for this individual item.',+ },+ ],+ examples: [+ {+ label: 'StyleX fill item',+ code: `import {stackItem} from '@xds/core/Layout';+import * as stylex from '@stylexjs/stylex';++<div {...stylex.props(...stackItem({size: 'fill'}))}>Content</div>`,+ },+ ],+ },+ ],+};diff --git a/packages/core/src/Stack/XDSHStack.tsx b/packages/core/src/Stack/XDSHStack.tsxindex 32e457f1f3..8a424639e5 100644--- a/packages/core/src/Stack/XDSHStack.tsx+++ b/packages/core/src/Stack/XDSHStack.tsx@@ -5,7 +5,7 @@* @position Layout/Stack component; wraps XDSStack with direction='horizontal'** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Layout/Stack/README.md+ * - /packages/core/src/Stack/Stack.doc.mjs* - /packages/core/src/Layout/Stack/XDSHStack.test.tsx* - /apps/storybook/stories/HStack.stories.tsx*/diff --git a/packages/core/src/Stack/XDSStack.tsx b/packages/core/src/Stack/XDSStack.tsxindex afc6a958af..fd5e455df9 100644--- a/packages/core/src/Stack/XDSStack.tsx+++ b/packages/core/src/Stack/XDSStack.tsx@@ -5,7 +5,7 @@* @position Layout/Stack component; uses stack.stylex.ts** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Layout/Stack/README.md+ * - /packages/core/src/Stack/Stack.doc.mjs* - /packages/core/src/Layout/Stack/XDSStack.test.tsx* - /apps/storybook/stories/Stack.stories.tsx*/diff --git a/packages/core/src/Stack/XDSStackItem.tsx b/packages/core/src/Stack/XDSStackItem.tsxindex d0c15f6270..b6d95c2f8b 100644--- a/packages/core/src/Stack/XDSStackItem.tsx+++ b/packages/core/src/Stack/XDSStackItem.tsx@@ -5,7 +5,7 @@* @position Layout/Stack component; uses stackItem.stylex.ts** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Layout/README.md+ * - /packages/core/src/Stack/Stack.doc.mjs* - /packages/core/src/Layout/Stack/XDSStackItem.test.tsx* - /apps/storybook/stories/StackItem.stories.tsx*/diff --git a/packages/core/src/Stack/XDSVStack.tsx b/packages/core/src/Stack/XDSVStack.tsxindex 0edcff80a9..9abf85701a 100644--- a/packages/core/src/Stack/XDSVStack.tsx+++ b/packages/core/src/Stack/XDSVStack.tsx@@ -5,7 +5,7 @@* @position Layout/Stack component; wraps XDSStack with direction='vertical'** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Layout/Stack/README.md+ * - /packages/core/src/Stack/Stack.doc.mjs* - /packages/core/src/Layout/Stack/XDSVStack.test.tsx* - /apps/storybook/stories/VStack.stories.tsx*/diff --git a/packages/core/src/Stack/index.ts b/packages/core/src/Stack/index.tsindex 8d671f7803..fcdbef34ca 100644--- a/packages/core/src/Stack/index.ts+++ b/packages/core/src/Stack/index.ts@@ -4,7 +4,7 @@* @output Exports XDSStack, XDSHStack, XDSVStack, XDSStackItem components* @position Entry point for Layout/Stack*- * SYNC: When modified, update /packages/core/src/Layout/README.md+ * SYNC: When modified, update /packages/core/src/Stack/Stack.doc.mjs*/// Unified stack componentdiff --git a/packages/core/src/Stack/stack.stylex.ts b/packages/core/src/Stack/stack.stylex.tsindex d81c569ba8..4e75441cff 100644--- a/packages/core/src/Stack/stack.stylex.ts+++ b/packages/core/src/Stack/stack.stylex.ts@@ -4,7 +4,7 @@* @output StyleX utility for stack (flex container) styling* @position Layout utility; used by XDSHStack, XDSVStack components*- * SYNC: When modified, update /packages/core/src/Layout/README.md+ * SYNC: When modified, update /packages/core/src/Stack/Stack.doc.mjs*/import * as stylex from '@stylexjs/stylex';diff --git a/packages/core/src/Stack/stackItem.stylex.ts b/packages/core/src/Stack/stackItem.stylex.tsindex f3b4d530a2..f8ac6d7be2 100644--- a/packages/core/src/Stack/stackItem.stylex.ts+++ b/packages/core/src/Stack/stackItem.stylex.ts@@ -4,7 +4,7 @@* @output StyleX utility for stack item styling* @position Layout utility; used by XDSStackItem and directly by components*- * SYNC: When modified, update /packages/core/src/Layout/README.md+ * SYNC: When modified, update /packages/core/src/Stack/Stack.doc.mjs*/import * as stylex from '@stylexjs/stylex';diff --git a/packages/core/src/StatusDot/README.md b/packages/core/src/StatusDot/README.mddeleted file mode 100644index e34aff48f6..0000000000--- a/packages/core/src/StatusDot/README.md+++ /dev/null@@ -1,54 +0,0 @@-# StatusDot--A small colored dot indicator for status display (online/offline, severity, etc).--## Exports--| Export | Type | Description |-| --------------------- | --------- | ------------------------ |-| `XDSStatusDot` | Component | Main status dot component |-| `XDSStatusDotProps` | Type | Props interface |-| `XDSStatusDotVariant` | Type | Variant union type |-| `XDSStatusDotSize` | Type | Size union type |--## Props--| Prop | Type | Default | Description |-| ------------- | ----------------------------------------------------------------- | -------- | ------------------------------------------------ |-| `variant` | `'positive' \| 'warning' \| 'negative' \| 'info' \| 'neutral'` | - | Semantic color variant (required) |-| `size` | `'sm' \| 'md'` | `'md'` | Dot size: sm=8px, md=10px |-| `label` | `string` | - | Accessible label (required) |-| `isPulsing` | `boolean` | `false` | Pulse animation, respects prefers-reduced-motion |-| `xstyle` | `StyleXStyles` | - | Optional StyleX style override |-| `data-testid` | `string` | - | Optional test ID |--## Usage--```tsx-import {XDSStatusDot} from '@xds/core/StatusDot';--// Basic status indicators-<XDSStatusDot variant="positive" label="Online" />-<XDSStatusDot variant="negative" label="Offline" />-<XDSStatusDot variant="warning" label="Away" />--// Small size-<XDSStatusDot variant="positive" label="Active" size="sm" />--// Pulsing animation-<XDSStatusDot variant="positive" label="Live" isPulsing />-```--## Accessibility--- Renders as `<span role="img" aria-label={label}>` for screen reader support-- Not focusable (decorative indicator)-- `isPulsing` animation respects `prefers-reduced-motion: reduce`--## Files--| File | Purpose |-| ----------------------- | ------------------------ |-| `XDSStatusDot.tsx` | Component implementation |-| `XDSStatusDot.test.tsx` | Unit tests |-| `index.ts` | Barrel exports |diff --git a/packages/core/src/StatusDot/StatusDot.doc.mjs b/packages/core/src/StatusDot/StatusDot.doc.mjsnew file mode 100644index 0000000000..7c028d2313--- /dev/null+++ b/packages/core/src/StatusDot/StatusDot.doc.mjs@@ -0,0 +1,62 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'StatusDot',+ description:+ 'A small colored dot indicator for status display (online/offline, severity, etc).',+ features: [+ 'Five semantic color variants: positive, warning, negative, info, neutral',+ 'Two sizes: sm (8px) and md (10px)',+ 'Optional pulse animation that respects prefers-reduced-motion',+ 'Accessible — renders as <span role="img" aria-label={label}> for screen reader support',+ 'Not focusable (decorative indicator)',+ ],+ props: [+ {+ name: 'variant',+ type: "'positive' | 'warning' | 'negative' | 'info' | 'neutral'",+ description: 'Semantic color variant.',+ required: true,+ },+ {+ name: 'label',+ type: 'string',+ description: 'Accessible label surfaced via aria-label.',+ required: true,+ },+ {+ name: 'size',+ type: "'sm' | 'md'",+ description: 'Dot size: sm=8px, md=10px.',+ default: "'md'",+ },+ {+ name: 'isPulsing',+ type: 'boolean',+ description:+ 'Enables a pulse animation; respects prefers-reduced-motion: reduce.',+ default: 'false',+ },+ ],+ examples: [+ {+ label: 'Basic status indicators',+ code: `<XDSStatusDot variant="positive" label="Online" />+<XDSStatusDot variant="negative" label="Offline" />+<XDSStatusDot variant="warning" label="Away" />`,+ },+ {+ label: 'Small size',+ code: `<XDSStatusDot variant="positive" label="Active" size="sm" />`,+ },+ {+ label: 'Pulsing animation',+ code: `<XDSStatusDot variant="positive" label="Live" isPulsing />`,+ },+ ],+ accessibility: [+ 'Renders as <span role="img" aria-label={label}> for screen reader support.',+ 'Not focusable — intended as a decorative indicator only.',+ 'isPulsing animation respects prefers-reduced-motion: reduce.',+ ],+};diff --git a/packages/core/src/StatusDot/XDSStatusDot.tsx b/packages/core/src/StatusDot/XDSStatusDot.tsxindex cdc26cea5e..a219e80ae2 100644--- a/packages/core/src/StatusDot/XDSStatusDot.tsx+++ b/packages/core/src/StatusDot/XDSStatusDot.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/StatusDot/README.md (props table, features, implementation notes)+ * - /packages/core/src/StatusDot/StatusDot.doc.mjs (props table, features, implementation notes)* - /packages/core/src/StatusDot/XDSStatusDot.test.tsx (tests for new/changed behavior)* - /packages/core/src/StatusDot/index.ts (exports if types change)* - /apps/storybook/stories/StatusDot.stories.tsx (storybook stories)diff --git a/packages/core/src/Switch/README.md b/packages/core/src/Switch/README.mddeleted file mode 100644index 4cf1a4c051..0000000000--- a/packages/core/src/Switch/README.md+++ /dev/null@@ -1,116 +0,0 @@-# Switch--A toggle switch component for boolean values with integrated label support.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Boolean Toggle**: Clean on/off switch for boolean values (40x24px with 20px thumb)-- **Label Integration**: Uses XDSFieldLabel for accessible labels with optional tooltip and icon-- **Label Position**: Label can appear before or after the switch (`start` or `end`)-- **Label Spacing**: Support for spread layout (label and switch on opposite ends)-- **Description**: Optional description text below the label-- **Optional/Required**: Visual indicators for field status-- **Accessibility**: Uses native checkbox with `role="switch"`, proper ARIA attributes--## Usage--```tsx-import { XDSSwitch } from '@xds/core/Switch';--// Basic usage-<XDSSwitch- label="Enable notifications"- value={enabled}- onChange={setEnabled}-/>--// With description-<XDSSwitch- label="Dark mode"- description="Switch to a darker color scheme"- value={darkMode}- onChange={setDarkMode}-/>--// With label icon and tooltip-<XDSSwitch- label="Auto-save"- labelIcon={CloudArrowUpIcon}- labelTooltip="Automatically save changes"- value={autoSave}- onChange={setAutoSave}-/>--// Label at start with spread spacing (settings panel style)-<XDSSwitch- label="Enable notifications"- value={enabled}- onChange={setEnabled}- labelPosition="start"- labelSpacing="spread"-/>-```--## Props--| Prop | Type | Default | Description |-| --------------- | -------------------------------------------- | ----------- | --------------------------------------------- |-| `label` | `string` | — | Label text for the switch (required) |-| `value` | `boolean` | — | Whether the switch is on or off |-| `onChange` | `(checked: boolean, e: ChangeEvent) => void` | — | Callback fired when state changes |-| `isLabelHidden` | `boolean` | `false` | Visually hide the label (still accessible) |-| `description` | `string` | — | Description text below the label |-| `isDisabled` | `boolean` | `false` | Whether the switch is disabled |-| `isOptional` | `boolean` | `false` | Whether the field is optional |-| `isRequired` | `boolean` | `false` | Whether the switch is required |-| `onFocus` | `(e: FocusEvent) => void` | — | Callback on focus |-| `onBlur` | `(e: FocusEvent) => void` | — | Callback on blur |-| `labelIcon` | `XDSIconType` | — | Icon before the label |-| `labelTooltip` | `string` | — | Tooltip on info icon after label |-| `labelPosition` | `'start' \| 'end'` | `'end'` | Which side of the switch the label appears on |-| `labelSpacing` | `'default' \| 'spread'` | `'default'` | Spacing behavior between label and switch |--## Theming--Themes can override `Switch` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- switch: {- root: myStyles,- track: myStyles,- thumb: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------- | --------------------- |-| `root` | Root container styles |-| `track` | Switch track styles |-| `thumb` | Switch thumb styles |--## Files--| File | Role | Purpose |-| -------------------- | ----- | --------------------------- |-| `index.ts` | Entry | Exports component and types |-| `XDSSwitch.tsx` | Core | Component implementation |-| `XDSSwitch.test.tsx` | Test | Unit tests |--## Implementation Notes--- Fixed dimensions: 40px width, 24px height, 16px thumb (off) / 20px thumb (on)-- Uses CSS custom properties for hover state management-- Native checkbox input with `role="switch"` for proper semantics-- Track and thumb animation with CSS transitions-- Follows the same patterns as XDSCheckboxInput for consistency-- `labelPosition="start"` with `labelSpacing="spread"` creates a settings panel style layoutdiff --git a/packages/core/src/Switch/Switch.doc.mjs b/packages/core/src/Switch/Switch.doc.mjsnew file mode 100644index 0000000000..e550b40c9e--- /dev/null+++ b/packages/core/src/Switch/Switch.doc.mjs@@ -0,0 +1,207 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Switch',+ description:+ 'A toggle switch component for boolean values with integrated label support.',+ features: [+ 'Boolean toggle — fixed 40x24px track with animated 16px (off) / 20px (on) thumb',+ 'Label integration — uses XDSFieldLabel for accessible labels with optional tooltip and icon',+ 'Label position — label can appear before or after the switch via labelPosition',+ 'Label spacing — supports spread layout to push label and switch to opposite ends',+ 'Description — optional description text displayed below the label',+ 'Optional/required indicators — visual markers for field status',+ 'Status messages — error, warning, success, or info message boxes below the switch',+ 'Async action support — onChangeAction with optimistic UI and built-in loading spinner',+ 'Accessibility — native checkbox with role="switch", aria-describedby, aria-invalid, aria-busy',+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSSwitch+ label="Enable notifications"+ value={enabled}+ onChange={setEnabled}+/>`,+ },+ {+ label: 'With description',+ code: `<XDSSwitch+ label="Dark mode"+ description="Switch to a darker color scheme"+ value={darkMode}+ onChange={setDarkMode}+/>`,+ },+ {+ label: 'With label icon and tooltip',+ code: `<XDSSwitch+ label="Auto-save"+ labelIcon={CloudArrowUpIcon}+ labelTooltip="Automatically save changes"+ value={autoSave}+ onChange={setAutoSave}+/>`,+ },+ {+ label: 'Settings panel style (label start, spread spacing)',+ code: `<XDSSwitch+ label="Enable notifications"+ value={enabled}+ onChange={setEnabled}+ labelPosition="start"+ labelSpacing="spread"+/>`,+ },+ {+ label: 'With async action and optimistic UI',+ code: `<XDSSwitch+ label="Sync to cloud"+ value={syncEnabled}+ onChange={setSyncEnabled}+ onChangeAction={async (checked) => {+ await updateSetting('sync', checked);+ }}+/>`,+ },+ {+ label: 'With error status',+ code: `<XDSSwitch+ label="Two-factor authentication"+ value={twoFactor}+ onChange={setTwoFactor}+ status={{type: 'error', message: 'Failed to save setting'}}+/>`,+ },+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description:+ 'Label text for the switch (always rendered for accessibility).',+ required: true,+ },+ {+ name: 'value',+ type: 'boolean',+ description: 'Whether the switch is on or off.',+ required: true,+ },+ {+ name: 'onChange',+ type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void',+ description: 'Callback fired when the switch state changes.',+ },+ {+ name: 'onChangeAction',+ type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>',+ description:+ 'Async action fired after onChange. Triggers optimistic UI and shows a loading spinner until the promise resolves.',+ },+ {+ name: 'isLoading',+ type: 'boolean',+ description:+ 'Whether the switch is in a loading state, showing a spinner inside the thumb.',+ default: 'false',+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description:+ 'Visually hides the label while keeping it accessible to screen readers.',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Description text displayed below the label.',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Whether the switch is disabled.',+ default: 'false',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description:+ 'Whether the field is optional. Mutually exclusive with isRequired.',+ default: 'false',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description:+ 'Whether the switch is required. Mutually exclusive with isOptional.',+ default: 'false',+ },+ {+ name: 'status',+ type: 'XDSInputStatus',+ description:+ 'Status indicator with type and message. Displays a colored message box below the switch and sets aria-invalid when type is "error".',+ },+ {+ name: 'onFocus',+ type: '(e: FocusEvent<HTMLInputElement>) => void',+ description: 'Callback fired when the switch receives focus.',+ },+ {+ name: 'onBlur',+ type: '(e: FocusEvent<HTMLInputElement>) => void',+ description: 'Callback fired when the switch loses focus.',+ },+ {+ name: 'labelIcon',+ type: 'XDSIconType',+ description: 'Icon displayed before the label text.',+ },+ {+ name: 'labelTooltip',+ type: 'string',+ description:+ 'Tooltip text shown in an info icon at the end of the label.',+ },+ {+ name: 'labelPosition',+ type: "'start' | 'end'",+ description:+ 'Which side of the switch the label appears on. "start" places the label before the switch.',+ default: "'end'",+ },+ {+ name: 'labelSpacing',+ type: "'default' | 'spread'",+ description:+ 'Spacing behavior between label and switch. "spread" pushes them to opposite ends of the container (full width).',+ default: "'default'",+ },+ ],+ theming: {+ componentKey: 'switch',+ surfaces: [+ {name: 'root', description: 'Root container flex wrapper'},+ {name: 'track', description: 'Switch track background element'},+ {name: 'thumb', description: 'Animated circular thumb inside the track'},+ ],+ },+ accessibility: [+ 'Renders a native <input type="checkbox" role="switch"> for correct switch semantics',+ 'Label is always associated via htmlFor/id even when visually hidden',+ 'Description text is linked via aria-describedby on the input element',+ 'Status messages are linked via aria-describedby; aria-invalid is set when status type is "error"',+ 'aria-busy is set during async onChangeAction execution',+ ],+ keyboard: 'Space toggles the switch; Tab/Shift+Tab moves focus in and out',+ notes: [+ 'Fixed dimensions: 40px width, 24px height, 16px thumb (off), 20px thumb (on)',+ 'Track and thumb use CSS transitions for background-color, transform, width, and height',+ 'Hover tints are applied via stylex.when.ancestor with a @media (hover: hover) guard',+ 'onChangeAction uses React useTransition and useOptimistic for seamless async toggling',+ 'labelPosition="start" with labelSpacing="spread" produces a settings panel style layout',+ 'Follows the same patterns as XDSCheckboxInput for structural consistency',+ ],+};diff --git a/packages/core/src/Switch/XDSSwitch.tsx b/packages/core/src/Switch/XDSSwitch.tsxindex cea70a1b76..8124b79ae9 100644--- a/packages/core/src/Switch/XDSSwitch.tsx+++ b/packages/core/src/Switch/XDSSwitch.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSSwitch.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Switch/README.md (props table, features, implementation notes)+ * - /packages/core/src/Switch/Switch.doc.mjs (props table, features, implementation notes)* - /packages/core/src/Switch/XDSSwitch.test.tsx (tests for new/changed behavior)* - /packages/core/src/Switch/index.ts (exports if types change)* - /apps/storybook/stories/Switch.stories.tsx (storybook stories)diff --git a/packages/core/src/TabList/README.md b/packages/core/src/TabList/README.mddeleted file mode 100644index 51ad962550..0000000000--- a/packages/core/src/TabList/README.md+++ /dev/null@@ -1,178 +0,0 @@-# TabList--XDSTabList component for tab navigation with overflow menu support.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Context-based communication**: `XDSTabListContext` passes value/onChange/size from XDSTabList to children-- **Single-responsibility XDSTab**: Renders as `<button>` or `<a>` (when `href` is provided) in the nav-- **Overflow menu**: `XDSTabMenu` accepts an `options` prop and renders menu items internally-- **Dynamic trigger label**: Menu trigger shows the selected option's label when one is active-- **Menu heading**: Dropdown includes an `XDSDivider` with the menu's `label` as a separator heading-- **Selection indicator**: Selected menu items show a checkmark icon (matching XDSSelector pattern)-- **Keyboard navigation**: Tab between items, ArrowUp/Down in menu, Home/End, Escape closes menu (via `useListFocus`)-- **Hover state**: Unselected tabs show a gray underline on hover; no background hover overlay-- **Accessibility**: `nav` landmark, `aria-current="page"` on selected tabs, `role="menu"` + `aria-label` on dropdown, `aria-controls` connecting trigger to menu, `role="menuitem"` for items, `role="separator"` for heading divider--## Usage--```tsx-import { XDSTabList, XDSTab, XDSTabMenu } from '@xds/core/TabList';--// Basic usage-<XDSTabList value={activeTab} onChange={setActiveTab}>- <XDSTab value="home" label="Home" />- <XDSTab value="settings" label="Settings" />-</XDSTabList>--// With links-<XDSTabList value={activeTab} onChange={setActiveTab}>- <XDSTab value="home" label="Home" href="/home" />- <XDSTab value="settings" label="Settings" href="/settings" />-</XDSTabList>--// With icons-<XDSTabList value={activeTab} onChange={setActiveTab}>- <XDSTab value="home" label="Home" icon={<HomeIcon />} selectedIcon={<HomeFilledIcon />} />- <XDSTab value="settings" label="Settings" icon={<CogIcon />} />-</XDSTabList>--// With bottom divider-<XDSTabList value={activeTab} onChange={setActiveTab} hasDivider>- <XDSTab value="home" label="Home" />- <XDSTab value="settings" label="Settings" />-</XDSTabList>--// With overflow menu (including icons on menu items)-<XDSTabList value={activeTab} onChange={setActiveTab}>- <XDSTab value="home" label="Home" />- <XDSTab value="settings" label="Settings" />- <XDSTabMenu- label="More"- options={[- {value: 'analytics', label: 'Analytics', icon: ChartBarIcon},- {value: 'reports', label: 'Reports', icon: DocumentTextIcon},- ]}- />-</XDSTabList>-```--## Props--### XDSTabList--```tsx-<XDSTabList value={activeTab} onChange={setActiveTab} hasDivider>- <XDSTab value="home" label="Home" />- <XDSTab value="settings" label="Settings" />-</XDSTabList>-```--| Prop | Type | Default | Description |-| ------------ | ---------------------- | ------- | ---------------------------------- |-| `value` | `string` | — | Active tab value |-| `onChange` | `(v: string) => void` | — | Tab change callback |-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant for tabs |-| `hasDivider` | `boolean` | `false` | Show bottom divider under tab list |-| `children` | `ReactNode` | — | XDSTab/XDSTabMenu items |--### XDSTab--```tsx-<XDSTab value="home" label="Home" href="/home" icon={<HomeIcon />} />-```--| Prop | Type | Default | Description |-| -------------- | ----------- | ----------- | ----------------------------------------- |-| `value` | `string` | — | Unique tab value |-| `label` | `string` | — | Visible label text |-| `href` | `string` | `undefined` | URL; renders as `<a>` when provided |-| `icon` | `ReactNode` | `undefined` | Icon when not selected |-| `selectedIcon` | `ReactNode` | `undefined` | Icon when selected (falls back to `icon`) |--### XDSTabMenu--```tsx-<XDSTabMenu- label="More"- options={[- {value: 'analytics', label: 'Analytics', icon: ChartBarIcon},- {value: 'reports', label: 'Reports', icon: DocumentTextIcon},- ]}-/>-```--| Prop | Type | Default | Description |-| --------- | -------------------- | ------- | --------------------------------------------------------- |-| `label` | `string` | — | Trigger label (shown when no option selected) and heading |-| `options` | `XDSTabMenuOption[]` | — | Menu options rendered in dropdown |--### XDSTabMenuOption--| Field | Type | Description |-| ------- | ------------- | ------------------------------ |-| `value` | `string` | Option value |-| `label` | `string` | Option display label |-| `icon` | `XDSIconType` | Optional icon before the label |--## Theming--Themes can override `TabList` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- tabList: {- root: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------- | ------------------------- |-| `root` | Root nav container styles |--## Files--| File | Role | Purpose |-| ---------------------- | ------- | ------------------------------------------ |-| `index.ts` | Entry | Exports all components and types |-| `XDSTabListContext.ts` | Context | XDSTabListContext definition |-| `XDSTabList.tsx` | Core | Nav wrapper providing XDSTabListContext |-| `XDSTab.tsx` | Core | Tab button/link with `aria-current="page"` |-| `XDSTabMenu.tsx` | Core | Menu trigger with `role="menu"` dropdown |-| `XDSTabList.test.tsx` | Test | Unit tests |--## Accessibility--### XDSTab--- Renders as `<button>` or `<a>` (no `role="tab"` — uses navigation pattern instead)-- Selected tab has `aria-current="page"`-- Hover shows gray underline; selected shows accent underline--### XDSTabMenu--- Trigger: `aria-haspopup="menu"` + `aria-expanded` + `aria-controls` pointing to menu-- Dropdown: `role="menu"` + `id` (matching `aria-controls`) + `aria-label`-- Heading: `XDSDivider` with `role="separator"`-- Items: `role="menuitem"` + `aria-current="true"` for selected-- Keyboard: ArrowUp/Down (wrapping), Home/End, Escape to close (via `useListFocus` hook)--## Implementation Notes--- `XDSTab` renders as `<button>` by default, `<a>` when `href` is provided-- `XDSTabMenu` renders menu items internally from `options` prop — no child composition-- Trigger label derives from `options.find(o => o.value === ctx.value)?.label ?? label`-- Menu trigger underline scopes to the label text only (not the chevron icon)-- Icons on menu items render via `XDSIcon` with `size="sm"` and `color="secondary"`-- Selected menu items show a `CheckIcon` checkmark (matching XDSSelector pattern)-- `hasDivider` on XDSTabList controls the bottom border (default: off)-- Size uses hardcoded 28/32/36px heights (`sizeVars` not yet available on this branch)diff --git a/packages/core/src/TabList/TabList.doc.mjs b/packages/core/src/TabList/TabList.doc.mjsnew file mode 100644index 0000000000..34844ed1b4--- /dev/null+++ b/packages/core/src/TabList/TabList.doc.mjs@@ -0,0 +1,238 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'TabList',+ description:+ 'Tab navigation components with overflow menu support, rendering as a semantic nav landmark with button or anchor tab items.',+ features: [+ 'Context-based communication: XDSTabListContext passes value/onChange/size from XDSTabList to children',+ 'Single-responsibility XDSTab: renders as <button> or <a> (when href is provided) in the nav',+ 'Overflow menu: XDSTabMenu accepts an options prop and renders menu items internally from the dropdown',+ "Dynamic trigger label: menu trigger shows the selected option's label when one is active",+ "Menu heading: dropdown includes an XDSDivider with the menu's label as a separator heading",+ 'Selection indicator: selected menu items show a checkmark icon (matching XDSSelector pattern)',+ 'Keyboard navigation: Tab between items, ArrowUp/Down in menu, Home/End, Escape closes menu (via useListFocus)',+ 'Hover state: unselected tabs show a gray underline on hover; no background hover overlay',+ 'Accessibility: nav landmark, aria-current="page" on selected tabs, role="menu" + aria-label on dropdown, aria-controls connecting trigger to menu, role="menuitem" for items, role="separator" for heading divider',+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSTabList value={activeTab} onChange={setActiveTab}>+ <XDSTab value="home" label="Home" />+ <XDSTab value="settings" label="Settings" />+</XDSTabList>`,+ },+ {+ label: 'With links',+ code: `<XDSTabList value={activeTab} onChange={setActiveTab}>+ <XDSTab value="home" label="Home" href="/home" />+ <XDSTab value="settings" label="Settings" href="/settings" />+</XDSTabList>`,+ },+ {+ label: 'With icons',+ code: `<XDSTabList value={activeTab} onChange={setActiveTab}>+ <XDSTab value="home" label="Home" icon={<HomeIcon />} selectedIcon={<HomeFilledIcon />} />+ <XDSTab value="settings" label="Settings" icon={<CogIcon />} />+</XDSTabList>`,+ },+ {+ label: 'With bottom divider',+ code: `<XDSTabList value={activeTab} onChange={setActiveTab} hasDivider>+ <XDSTab value="home" label="Home" />+ <XDSTab value="settings" label="Settings" />+</XDSTabList>`,+ },+ {+ label: 'With overflow menu',+ code: `<XDSTabList value={activeTab} onChange={setActiveTab}>+ <XDSTab value="home" label="Home" />+ <XDSTab value="settings" label="Settings" />+ <XDSTabMenu+ label="More"+ options={[+ {value: 'analytics', label: 'Analytics', icon: ChartBarIcon},+ {value: 'reports', label: 'Reports', icon: DocumentTextIcon},+ ]}+ />+</XDSTabList>`,+ },+ ],+ theming: {+ componentKey: 'tabList',+ surfaces: [{name: 'root', description: 'Root nav container styles'}],+ },+ accessibility: [+ 'XDSTabList renders as a <nav> landmark with aria-label="Tabs"',+ 'XDSTab renders as <button> or <a> — uses navigation pattern, not role="tab"',+ 'Selected XDSTab has aria-current="page"',+ 'XDSTabMenu trigger has aria-haspopup="menu", aria-expanded, and aria-controls pointing to the menu element',+ 'XDSTabMenu dropdown has role="menu" and aria-label matching the label prop',+ 'XDSTabMenu heading divider has role="separator"',+ 'XDSTabMenu items have role="menuitem" and aria-current="true" when selected',+ ],+ keyboard:+ 'Tab moves focus between tab items; within the XDSTabMenu dropdown: ArrowUp/ArrowDown navigate items (wrapping), Home/End jump to first/last item, Escape closes the menu.',+ notes: [+ 'XDSTab renders as <button> by default and as <a> when href is provided',+ 'XDSTabMenu renders menu items internally from the options prop — no child composition',+ 'Trigger label derives from options.find(o => o.value === ctx.value)?.label ?? label',+ 'Menu trigger underline scopes to the label text span only, not the chevron icon',+ 'Icons on menu items render via XDSIcon with size="sm" and color="secondary"',+ 'Selected menu items show a CheckIcon checkmark (matching XDSSelector pattern)',+ 'hasDivider on XDSTabList controls the bottom border (default: off)',+ 'Size uses sizeVars tokens for tab heights (sm/md/lg)',+ ],+ components: [+ {+ name: 'XDSTabList',+ description:+ 'Nav wrapper that provides XDSTabListContext (value, onChange, size) to XDSTab and XDSTabMenu children.',+ props: [+ {+ name: 'value',+ type: 'string',+ description: 'The currently selected tab value.',+ required: true,+ },+ {+ name: 'onChange',+ type: '(value: string) => void',+ description: 'Callback fired when a tab is selected.',+ required: true,+ },+ {+ name: 'size',+ type: "'sm' | 'md' | 'lg'",+ description: 'Size variant applied to all child tabs.',+ default: "'md'",+ },+ {+ name: 'hasDivider',+ type: 'boolean',+ description:+ 'Whether to show a bottom border divider under the tab list.',+ default: 'false',+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'XDSTab and XDSTabMenu items to render inside the nav.',+ required: true,+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSTabList value={activeTab} onChange={setActiveTab}>+ <XDSTab value="home" label="Home" />+ <XDSTab value="settings" label="Settings" />+</XDSTabList>`,+ },+ {+ label: 'With divider',+ code: `<XDSTabList value={activeTab} onChange={setActiveTab} hasDivider size="sm">+ <XDSTab value="home" label="Home" />+ <XDSTab value="settings" label="Settings" />+</XDSTabList>`,+ },+ ],+ },+ {+ name: 'XDSTab',+ description:+ 'Individual tab item that renders as a button or an anchor link, with selected-state styling and optional icons.',+ props: [+ {+ name: 'value',+ type: 'string',+ description:+ 'Unique value for this tab, matched against XDSTabListContext.value.',+ required: true,+ },+ {+ name: 'label',+ type: 'string',+ description: 'Visible label text for this tab.',+ required: true,+ },+ {+ name: 'href',+ type: 'string',+ description:+ 'URL to navigate to; when provided, the tab renders as an anchor element.',+ },+ {+ name: 'as',+ type: 'XDSLinkComponentType',+ description:+ 'Custom component to render instead of <a> for link tabs. Overrides the XDSLinkProvider default. Only applies when href is provided.',+ },+ {+ name: 'icon',+ type: 'ReactNode',+ description: 'Icon element shown when the tab is not selected.',+ },+ {+ name: 'selectedIcon',+ type: 'ReactNode',+ description:+ 'Icon element shown when the tab is selected; falls back to icon if not provided.',+ },+ ],+ examples: [+ {+ label: 'Button tab',+ code: '<XDSTab value="home" label="Home" />',+ },+ {+ label: 'Link tab with icons',+ code: '<XDSTab value="home" label="Home" href="/home" icon={<HomeIcon />} selectedIcon={<HomeFilledIcon />} />',+ },+ ],+ },+ {+ name: 'XDSTabMenu',+ description:+ "Overflow menu trigger that opens a dropdown of additional tab options, showing the selected option's label as the trigger text.",+ props: [+ {+ name: 'label',+ type: 'string',+ description:+ 'Label for the trigger button (shown when no option is selected) and the dropdown heading divider.',+ required: true,+ },+ {+ name: 'options',+ type: 'XDSTabMenuOption[]',+ description: 'Array of menu options rendered in the dropdown.',+ required: true,+ },+ ],+ examples: [+ {+ label: 'With icons',+ code: `<XDSTabMenu+ label="More"+ options={[+ {value: 'analytics', label: 'Analytics', icon: ChartBarIcon},+ {value: 'reports', label: 'Reports', icon: DocumentTextIcon},+ ]}+/>`,+ },+ {+ label: 'Text only',+ code: `<XDSTabMenu+ label="More"+ options={[+ {value: 'analytics', label: 'Analytics'},+ {value: 'reports', label: 'Reports'},+ ]}+/>`,+ },+ ],+ },+ ],+};diff --git a/packages/core/src/TabList/XDSTab.tsx b/packages/core/src/TabList/XDSTab.tsxindex 5c24efeb3a..329a64a295 100644--- a/packages/core/src/TabList/XDSTab.tsx+++ b/packages/core/src/TabList/XDSTab.tsx@@ -5,7 +5,7 @@* @position Core tab item; renders as button or anchor in navigation** SYNC: When modified, update:- * - /packages/core/src/TabList/README.md+ * - /packages/core/src/TabList/TabList.doc.mjs* - /packages/core/src/TabList/index.ts* - /packages/core/src/TabList/XDSTabList.test.tsx*/diff --git a/packages/core/src/TabList/XDSTabList.tsx b/packages/core/src/TabList/XDSTabList.tsxindex fb21fb252d..e8db9b3be5 100644--- a/packages/core/src/TabList/XDSTabList.tsx+++ b/packages/core/src/TabList/XDSTabList.tsx@@ -5,7 +5,7 @@* @position Nav wrapper; provides XDSTabListContext to XDSTab and XDSTabMenu children** SYNC: When modified, update:- * - /packages/core/src/TabList/README.md+ * - /packages/core/src/TabList/TabList.doc.mjs* - /packages/core/src/TabList/index.ts* - /packages/core/src/TabList/XDSTabList.test.tsx*/diff --git a/packages/core/src/TabList/XDSTabListContext.ts b/packages/core/src/TabList/XDSTabListContext.tsindex 4653a11738..aaa22947e5 100644--- a/packages/core/src/TabList/XDSTabListContext.ts+++ b/packages/core/src/TabList/XDSTabListContext.ts@@ -4,7 +4,7 @@* @output Exports XDSTabListContext, useXDSTabListContext* @position Context provider; consumed by XDSTab.tsx, XDSTabMenu.tsx*- * SYNC: When modified, update /packages/core/src/TabList/README.md+ * SYNC: When modified, update /packages/core/src/TabList/TabList.doc.mjs*/'use client';diff --git a/packages/core/src/TabList/XDSTabMenu.tsx b/packages/core/src/TabList/XDSTabMenu.tsxindex c3e79342d3..3b18e026df 100644--- a/packages/core/src/TabList/XDSTabMenu.tsx+++ b/packages/core/src/TabList/XDSTabMenu.tsx@@ -5,7 +5,7 @@* @position Menu trigger button; opens dropdown of overflow menu items** SYNC: When modified, update:- * - /packages/core/src/TabList/README.md+ * - /packages/core/src/TabList/TabList.doc.mjs* - /packages/core/src/TabList/index.ts* - /packages/core/src/TabList/XDSTabList.test.tsx*/diff --git a/packages/core/src/TabList/index.ts b/packages/core/src/TabList/index.tsindex e539436e1e..112bb768d7 100644--- a/packages/core/src/TabList/index.ts+++ b/packages/core/src/TabList/index.ts@@ -4,7 +4,7 @@* @output Exports XDSTabList, XDSTab, XDSTabMenu and their types* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/TabList/README.md+ * SYNC: When modified, update this header and /packages/core/src/TabList/TabList.doc.mjs*/export {XDSTabList} from './XDSTabList';diff --git a/packages/core/src/Table/README.md b/packages/core/src/Table/README.mddeleted file mode 100644index 9d94ecb04e..0000000000--- a/packages/core/src/Table/README.md+++ /dev/null@@ -1,385 +0,0 @@-# Table--Data-driven table with rich cell content via `renderCell`. Compose cells with-XDSBadge, XDSStatusDot, XDSText, XDSAvatar, and layout primitives.--<!-- SYNC: When files in this directory change, update this document. -->--## Components--| File | Export | Purpose |-| ------------------------ | -------------------- | ------------------------------------------------------------ |-| `XDSTable.tsx` | `XDSTable` | Styled, data-driven table with density, dividers, and hover |-| `XDSBaseTable.tsx` | `XDSBaseTable` | Unstyled table with colgroup, plugin pipeline, children mode |-| `XDSTableRow.tsx` | `XDSTableRow` | `<tr>` wrapper with context-aware styling + `xstyle` |-| `XDSTableCell.tsx` | `XDSTableCell` | `<td>` wrapper with context-aware styling + `xstyle` |-| `XDSTableHeaderCell.tsx` | `XDSTableHeaderCell` | `<th>` wrapper with context-aware header styling + `xstyle` |-| `XDSTableContext.ts` | `XDSTableContext` | Context for passing styling props to row/cell components |--## Hooks--| File | Export | Purpose |-| -------------------------- | ---------------------- | ---------------------------------------------------- |-| `useXDSTableSelection.tsx` | `useXDSTableSelection` | Selection plugin hook — checkboxes, select-all, aria |--## Utilities--| File | Export | Purpose |-| ---------------- | ------------------ | -------------------------------------------- |-| `columnUtils.ts` | `proportional` | Create a proportional (fr-like) column width |-| `columnUtils.ts` | `pixel` | Create a fixed pixel column width |-| `columnUtils.ts` | `generateColumns` | Auto-generate columns from data object keys |-| `columnUtils.ts` | `columnWidthToCSS` | Convert a ColumnWidth to a CSS width string |--## Types--| File | Export | Purpose |-| -------------------------- | ------------------------------- | ------------------------------------------------ |-| `types.ts` | `XDSTableColumn` | Column definition (key, header, width, renderer) |-| `types.ts` | `ColumnWidth` | Proportional or pixel width union |-| `types.ts` | `TablePlugin` | Plugin interface for transform-props pipeline |-| `types.ts` | `XDSBaseTableProps` | Props for the unstyled base table |-| `types.ts` | `TableRowComponentProps` | Props interface for Row components |-| `types.ts` | `TableCellComponentProps` | Props interface for Cell components |-| `types.ts` | `TableHeaderCellComponentProps` | Props interface for HeaderCell components |-| `useXDSTableSelection.tsx` | `UseXDSTableSelectionConfig` | Config type for the selection hook |--## Components--### XDSTable--Styled, data-driven table. Use `renderCell` on columns for rich cell content —-compose with XDSBadge, XDSStatusDot, XDSText, XDSAvatar, and layout primitives.--```tsx-<XDSTable- data={users}- columns={[- {- key: 'name',- header: 'Name',- renderCell: user => (- <XDSHStack gap="space2" align="center">- <XDSAvatar name={user.name} size="small" />- <XDSVStack gap="space1">- <XDSText type="body" weight="semibold">- {user.name}- </XDSText>- <XDSText type="supporting" color="secondary">- {user.email}- </XDSText>- </XDSVStack>- </XDSHStack>- ),- },- {- key: 'status',- header: 'Status',- width: pixel(140),- renderCell: user => (- <XDSHStack gap="space2" align="center">- <XDSStatusDot status={user.isActive ? 'positive' : 'negative'} />- <XDSBadge variant={user.isActive ? 'success' : 'error'}>- {user.isActive ? 'Active' : 'Inactive'}- </XDSBadge>- </XDSHStack>- ),- },- {- key: 'role',- header: 'Role',- renderCell: user => (- <XDSText type="label" color="secondary">- {user.role}- </XDSText>- ),- },- ]}- density="balanced"- dividers="rows"- hasHover-/>-```--| Prop | Type | Default | Description |-| ----------- | --------------------------------------- | ------------ | -------------------------------------------------------------- |-| `data` | `T[]` | — | Array of data items |-| `columns` | `XDSTableColumn<T>[]` | — | Column definitions with optional `renderCell` for rich content |-| `idKey` | `string \| (item: T) => string` | — | Row key for React reconciliation |-| `density` | `'compact' \| 'balanced' \| 'spacious'` | `'balanced'` | Row density |-| `dividers` | `XDSTableDividers` | `'rows'` | Divider style |-| `isStriped` | `boolean` | `false` | Striped even rows |-| `hasHover` | `boolean` | `false` | Hover highlight on rows |-| `plugins` | `Record<string, TablePlugin<T>>` | — | Named plugins to extend behavior |-| `children` | `ReactNode` | — | Children mode (manual rows) |--### XDSBaseTable--Unstyled table with colgroup, plugin pipeline, and components prop for custom rendering.--```tsx-<XDSBaseTable- data={items}- columns={columns}- plugins={[myPlugin]}- components={{Row: XDSTableRow, Cell: XDSTableCell}}-/>-```--| Prop | Type | Default | Description |-| ------------ | ------------------------------- | ------- | -------------------------------------- |-| `data` | `T[]` | — | Array of data items |-| `columns` | `XDSTableColumn<T>[]` | — | Column definitions |-| `idKey` | `string \| (item: T) => string` | — | Row key for React reconciliation |-| `plugins` | `TablePlugin<T>[]` | — | Ordered plugins for transform pipeline |-| `components` | `{Row?, Cell?, HeaderCell?}` | — | Component overrides for table elements |-| `children` | `ReactNode` | — | Children mode |-| `tableProps` | `HTMLAttributes` | — | Additional attrs for `<table>` element |--### XDSTableRow--`<tr>` wrapper with context-aware styling and xstyle support.--```tsx-<XDSTableRow>- <XDSTableCell>Alice</XDSTableCell>- <XDSTableCell>30</XDSTableCell>-</XDSTableRow>-```--| Prop | Type | Default | Description |-| ---------- | ---------------- | ------- | --------------- |-| `children` | `ReactNode` | — | Row cells |-| `xstyle` | `StyleXStyles[]` | — | Style overrides |--### XDSTableCell--`<td>` wrapper with context-aware styling and xstyle support. Accepts any ReactNode-as children — compose rich content with XDS components like XDSBadge, XDSStatusDot,-XDSText, XDSAvatar, and layout primitives.--```tsx-<XDSTableCell>- <XDSHStack gap="space2" align="center">- <XDSStatusDot status="positive" />- <XDSText weight="semibold">Active</XDSText>- </XDSHStack>-</XDSTableCell>-```--| Prop | Type | Default | Description |-| ---------- | ------------------------------ | ------- | --------------- |-| `children` | `ReactNode` | — | Cell content |-| `xstyle` | `StyleXStyles \| StyleXStyles` | — | Style overrides |--### XDSTableHeaderCell--`<th>` wrapper with context-aware header styling and xstyle support.--```tsx-<XDSTableHeaderCell>Name</XDSTableHeaderCell>-```--| Prop | Type | Default | Description |-| ---------- | -------------------------------- | ------- | --------------- |-| `children` | `ReactNode` | — | Header content |-| `xstyle` | `StyleXStyles \| StyleXStyles[]` | — | Style overrides |--## Usage Patterns--### Rich cell content with renderCell--Use `renderCell` to compose XDS components inside table cells. This is the-recommended pattern for any table that displays more than plain text.--```tsx-const columns = [- {- key: 'transaction',- header: 'Transaction',- renderCell: item => (- <XDSVStack gap="space1">- <XDSText type="body" weight="semibold">- {item.description}- </XDSText>- <XDSText type="supporting" color="secondary">- {item.date}- </XDSText>- </XDSVStack>- ),- },- {- key: 'amount',- header: 'Amount',- width: pixel(120),- renderCell: item => (- <XDSText- type="body"- weight="semibold"- color={item.amount > 0 ? 'positive' : 'primary'}>- {item.amount > 0 ? '+' : ''}- {item.amount.toFixed(2)}- </XDSText>- ),- },- {- key: 'status',- header: 'Status',- width: pixel(140),- renderCell: item => (- <XDSHStack gap="space2" align="center">- <XDSStatusDot status={statusMap[item.status]} />- <XDSBadge variant={badgeMap[item.status]}>{item.status}</XDSBadge>- </XDSHStack>- ),- },-];--<XDSTable data={transactions} columns={columns} hasHover dividers="rows" />;-```--### Data-driven table (plain text)--For simple tables where plain text is sufficient, columns default to `String(item[key])`:--```tsx-<XDSTable- data={users}- columns={[- {key: 'name', header: 'Name'},- {key: 'email', header: 'Email', width: proportional(2)},- {key: 'age', header: 'Age', width: pixel(80)},- ]}- density="balanced"- dividers="rows"- hasHover-/>-```--### Auto-generated columns--```tsx-// Columns auto-generated from data keys with capitalized headers-<XDSTable data={users} isStriped />-```--### Children mode--For fully custom row layouts, use children mode with XDSTableRow and XDSTableCell:--```tsx-<XDSTable density="balanced" dividers="rows" isStriped hasHover>- <XDSTableRow>- <XDSTableCell>- <XDSHStack gap="space2" align="center">- <XDSAvatar name="Alice" size="small" />- <XDSText weight="semibold">Alice</XDSText>- </XDSHStack>- </XDSTableCell>- <XDSTableCell>- <XDSBadge variant="success">Active</XDSBadge>- </XDSTableCell>- </XDSTableRow>-</XDSTable>-```--### Custom plugin--```tsx-const highlightPlugin: TablePlugin<User> = {- transformBodyRow(props, item) {- if (item.isActive) {- return {...props, styles: [...props.styles, activeRowStyle]};- }- return props;- },-};--<XDSTable data={users} plugins={{highlight: highlightPlugin}} />;-```--### Selection--```tsx-const [selectedKeys, setSelectedKeys] = useState<Set<string>>(new Set());--const selectionPlugin = useXDSTableSelection<User>({- getIsItemSelected: item => selectedKeys.has(item.id),- onSelectItem: ({item, isSelected}) => {- const next = new Set(selectedKeys);- isSelected ? next.add(item.id) : next.delete(item.id);- setSelectedKeys(next);- },- onSelectAll: ({isAllSelected}) => {- setSelectedKeys(isAllSelected ? new Set(users.map(u => u.id)) : new Set());- },- getIsAllSelected: () => users.every(u => selectedKeys.has(u.id)),- getIsIndeterminate: () => {- const count = users.filter(u => selectedKeys.has(u.id)).length;- return count > 0 && count < users.length;- },- // Optional: hide checkbox for non-selectable rows- getIsItemSelectable: item => item.role !== 'admin',- // Optional: disable checkbox for locked rows- getIsItemEnabled: item => !item.isLocked,-});--<XDSTable- data={users}- columns={columns}- plugins={{selection: selectionPlugin}}-/>;-```--## Architecture--Two-layer design: **XDSBaseTable** provides unstyled structure, the plugin pipeline, and a `components` prop for rendering custom elements. **XDSTable** wraps it, providing `XDSTableContext` with appearance configuration and passing styled components (`XDSTableRow`, `XDSTableCell`, `XDSTableHeaderCell`) that read context to apply density, dividers, isStriped, and hasHover styles.--### Component-Based Styling--Styling is owned by components rather than a styling plugin:--- **XDSTableRow** — reads `XDSTableContext` for striped/hover/divider styles-- **XDSTableCell** — reads `XDSTableContext` for density/divider styles-- **XDSTableHeaderCell** — reads `XDSTableContext` for density/header/divider styles--Each component accepts `xstyle` for additional styles from plugin transforms (e.g., selected row background from the selection plugin).--### Plugin System--Plugins transform render props at each structural level (`transformTable`, `transformHeaderRow`, `transformBodyRow`, etc.). XDSTable accepts plugins as a named record (`Record<string, TablePlugin<T>>`), while XDSBaseTable accepts an ordered array. XDSTable converts the record to an array internally.--Plugins can also provide:--- `transformTableContext` — wrap the table output in context providers (used by selection to provide `SelectionContext`)-- Row transforms receive pre-rendered `children` (cells), allowing plugins to prepend/append elements--### Selection Architecture--The selection plugin uses React Context so that `SelectAllCheckbox` and `SelectionRowCheckbox` re-render independently from row content. The hook returns a stable plugin object via ref — only the context value updates when selection state changes. Selection cells render `XDSTableCell` and `XDSTableHeaderCell` directly, inheriting styling from `XDSTableContext`.--### Performance--Body rows are memoized via `React.memo` with a custom comparison function. When a single data item changes, only that row re-renders — unchanged rows are skipped. For this to work optimally, consumers should define `columns` outside the component or memoize them.--## Theming--Themes can override `Table` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- table: {- root: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------- | ----------------- |-| `root` | Root table styles |diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjsnew file mode 100644index 0000000000..28d168d483--- /dev/null+++ b/packages/core/src/Table/Table.doc.mjs@@ -0,0 +1,493 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Table',+ description:+ 'Data-driven table with rich cell content via renderCell. Compose cells with XDSBadge, XDSStatusDot, XDSText, XDSAvatar, and layout primitives. XDSBaseTable provides the unstyled structural core with a composable plugin pipeline.',+ features: [+ 'Data-driven rendering — pass data + columns, rows render automatically',+ 'Rich cell content via renderCell — compose XDS components (XDSBadge, XDSStatusDot, XDSText, XDSAvatar) inside table cells',+ 'Children mode — compose XDSTableRow/XDSTableCell directly for manual layouts',+ 'Plugin system — extend table behavior with composable transform plugins',+ 'Density variants: compact, balanced, spacious',+ 'Divider styles: rows, columns, grid, none',+ 'Striped even rows and hover highlight via XDSTableContext',+ 'Selection via useXDSTableSelection — checkboxes, select-all, aria-selected',+ 'Body rows memoized with custom comparison — only changed rows re-render',+ 'Auto-generated columns from data object keys when columns prop is omitted',+ 'Theming — root, headerRow, bodyRow, headerCell, bodyCell surfaces via ComponentStyles',+ ],+ examples: [+ {+ label: 'Basic data-driven table',+ code: `<XDSTable+ data={users}+ columns={[+ {+ key: 'name',+ header: 'Name',+ renderCell: user => (+ <XDSHStack gap="space2" align="center">+ <XDSAvatar name={user.name} size="small" />+ <XDSVStack gap="space1">+ <XDSText type="body" weight="semibold">+ {user.name}+ </XDSText>+ <XDSText type="supporting" color="secondary">+ {user.email}+ </XDSText>+ </XDSVStack>+ </XDSHStack>+ ),+ },+ {+ key: 'status',+ header: 'Status',+ width: pixel(140),+ renderCell: user => (+ <XDSHStack gap="space2" align="center">+ <XDSStatusDot status={user.isActive ? 'positive' : 'negative'} />+ <XDSBadge variant={user.isActive ? 'success' : 'error'}>+ {user.isActive ? 'Active' : 'Inactive'}+ </XDSBadge>+ </XDSHStack>+ ),+ },+ {+ key: 'role',+ header: 'Role',+ renderCell: user => (+ <XDSText type="label" color="secondary">+ {user.role}+ </XDSText>+ ),+ },+ ]}+ density="balanced"+ dividers="rows"+ hasHover+/>`,+ },+ {+ label: 'Auto-generated columns',+ code: `// Columns auto-generated from data keys with capitalized headers+<XDSTable data={users} isStriped />`,+ },+ {+ label: 'Rich cell content with renderCell',+ code: `<XDSTable+ data={transactions}+ columns={[+ {+ key: 'description',+ header: 'Transaction',+ renderCell: tx => (+ <XDSVStack gap="space1">+ <XDSText weight="semibold">{tx.description}</XDSText>+ <XDSText type="supporting" color="secondary">+ {tx.date}+ </XDSText>+ </XDSVStack>+ ),+ },+ {+ key: 'amount',+ header: 'Amount',+ renderCell: tx => (+ <XDSText+ weight="semibold"+ color={tx.amount > 0 ? 'positive' : 'negative'}>+ {tx.amount > 0 ? '+' : ''}+ {tx.amount.toFixed(2)}+ </XDSText>+ ),+ },+ {+ key: 'status',+ header: 'Status',+ renderCell: tx => (+ <XDSBadge+ variant={+ tx.status === 'completed'+ ? 'success'+ : tx.status === 'pending'+ ? 'warning'+ : 'error'+ }>+ {tx.status}+ </XDSBadge>+ ),+ },+ ]}+ density="balanced"+ dividers="rows"+ hasHover+/>`,+ },+ {+ label: 'Children mode',+ code: `<XDSTable density="balanced" dividers="rows" isStriped hasHover>+ <XDSTableRow>+ <XDSTableCell>+ <XDSHStack gap="space2" align="center">+ <XDSAvatar name="Alice" size="small" />+ <XDSText weight="semibold">Alice</XDSText>+ </XDSHStack>+ </XDSTableCell>+ <XDSTableCell>+ <XDSBadge variant="success">Active</XDSBadge>+ </XDSTableCell>+ </XDSTableRow>+</XDSTable>`,+ },+ {+ label: 'Selection plugin',+ code: `const [selectedKeys, setSelectedKeys] = useState<Set<string>>(new Set());++const selectionPlugin = useXDSTableSelection<User>({+ getIsItemSelected: item => selectedKeys.has(item.id),+ onSelectItem: ({item, isSelected}) => {+ const next = new Set(selectedKeys);+ isSelected ? next.add(item.id) : next.delete(item.id);+ setSelectedKeys(next);+ },+ onSelectAll: ({isAllSelected}) => {+ setSelectedKeys(isAllSelected ? new Set(users.map(u => u.id)) : new Set());+ },+ getIsAllSelected: () => users.every(u => selectedKeys.has(u.id)),+ getIsIndeterminate: () => {+ const count = users.filter(u => selectedKeys.has(u.id)).length;+ return count > 0 && count < users.length;+ },+});++<XDSTable+ data={users}+ columns={columns}+ plugins={{selection: selectionPlugin}}+/>`,+ },+ {+ label: 'Custom plugin',+ code: `const highlightPlugin: TablePlugin<User> = {+ transformBodyRow(props, item) {+ if (item.isActive) {+ return {...props, styles: [...props.styles, activeRowStyle]};+ }+ return props;+ },+};++<XDSTable data={users} plugins={{highlight: highlightPlugin}} />`,+ },+ ],+ theming: {+ componentKey: 'table',+ surfaces: [+ {name: 'root', description: 'Root table element styles'},+ {name: 'headerRow', description: 'Header row styles'},+ {name: 'bodyRow', description: 'Body row styles'},+ {name: 'headerCell', description: 'Header cell styles'},+ {name: 'bodyCell', description: 'Body cell styles'},+ ],+ },+ accessibility: [+ 'Selection plugin sets aria-selected on selected body rows',+ 'Select-all and per-row checkboxes use visually hidden labels ("Select all rows", "Select row") via isLabelHidden',+ 'Non-selectable rows (getIsItemSelectable returns false) render no checkbox',+ 'Disabled rows (getIsItemEnabled returns false) render a disabled checkbox',+ ],+ notes: [+ 'Two-layer design: XDSBaseTable provides unstyled structure and the plugin pipeline; XDSTable wraps it with XDSTableContext and styled sub-components.',+ 'Styling is owned by components (XDSTableRow, XDSTableCell, XDSTableHeaderCell), not by plugins — each reads XDSTableContext to apply density, dividers, striped, and hover styles.',+ 'XDSTable accepts plugins as a named Record<string, TablePlugin<T>> and converts to an ordered array internally; XDSBaseTable accepts an ordered array directly.',+ 'The selection plugin uses React Context so SelectAllCheckbox and SelectionRowCheckbox re-render independently from row content — only the context value updates when selection state changes.',+ 'Body rows are memoized via React.memo with a custom comparison. For optimal performance, define columns outside the component or memoize them to avoid triggering full re-renders.',+ 'Columns can be auto-generated from data keys using generateColumns(); column widths are expressed as proportional (fr-like) or fixed pixel values via the proportional() and pixel() helpers.',+ 'tableProps on XDSBaseTable passes additional HTML attributes directly to the <table> element.',+ ],+ components: [+ {+ name: 'XDSTable',+ description:+ 'Styled, data-driven table with density, dividers, hover highlight, striped rows, and named plugin support.',+ props: [+ {+ name: 'data',+ type: 'T[]',+ description: 'Array of data items to render as rows.',+ },+ {+ name: 'columns',+ type: 'XDSTableColumn<T>[]',+ description:+ 'Column definitions. If omitted, columns are auto-generated from data object keys.',+ },+ {+ name: 'idKey',+ type: '(keyof T & string) | ((item: T) => string | number)',+ description:+ 'Row key for React reconciliation. Pass a property name string or a function. Falls back to row index if omitted.',+ },+ {+ name: 'density',+ type: "'compact' | 'balanced' | 'spacious'",+ description: 'Row density controlling cell padding and font size.',+ default: "'balanced'",+ },+ {+ name: 'dividers',+ type: "'rows' | 'columns' | 'grid' | 'none'",+ description: 'Divider style rendered between cells.',+ default: "'rows'",+ },+ {+ name: 'isStriped',+ type: 'boolean',+ description: 'Applies a background wash to even-numbered rows.',+ default: 'false',+ },+ {+ name: 'hasHover',+ type: 'boolean',+ description:+ 'Applies a hover highlight background to rows on pointer devices.',+ default: 'false',+ },+ {+ name: 'plugins',+ type: 'Record<string, TablePlugin<T>>',+ description:+ 'Named plugins that extend table behavior via the transform pipeline. Converted to an ordered array internally.',+ },+ {+ name: 'children',+ type: 'ReactNode',+ description:+ 'Children mode — render XDSTableRow/XDSTableCell directly instead of using data-driven rendering.',+ },+ ],+ examples: [+ {+ label: 'Data-driven',+ code: `<XDSTable+ data={users}+ columns={[+ {key: 'name', header: 'Name'},+ {key: 'email', header: 'Email', width: proportional(2)},+ ]}+ density="compact"+ dividers="grid"+ isStriped+ hasHover+/>`,+ },+ {+ label: 'Children mode',+ code: `<XDSTable density="balanced" dividers="rows">+ <XDSTableRow>+ <XDSTableCell>Alice</XDSTableCell>+ <XDSTableCell>30</XDSTableCell>+ </XDSTableRow>+</XDSTable>`,+ },+ ],+ },+ {+ name: 'XDSBaseTable',+ description:+ 'Unstyled structural table component with a plugin transform pipeline and a components prop for swapping in custom row/cell renderers.',+ props: [+ {+ name: 'data',+ type: 'T[]',+ description: 'Array of data items to render as rows.',+ },+ {+ name: 'columns',+ type: 'XDSTableColumn<T>[]',+ description:+ 'Column definitions. If omitted, columns are auto-generated from data object keys.',+ },+ {+ name: 'idKey',+ type: '(keyof T & string) | ((item: T) => string | number)',+ description:+ 'Row key for React reconciliation. Pass a property name string or a function. Falls back to row index if omitted.',+ },+ {+ name: 'plugins',+ type: 'TablePlugin<T>[]',+ description:+ 'Ordered array of plugins applied as a sequential transform pipeline.',+ },+ {+ name: 'components',+ type: '{Row?: ComponentType<TableRowComponentProps>; Cell?: ComponentType<TableCellComponentProps>; HeaderCell?: ComponentType<TableHeaderCellComponentProps>}',+ description:+ 'Component overrides for row and cell elements. When provided, these components receive xstyle from plugin transforms.',+ },+ {+ name: 'children',+ type: 'ReactNode',+ description:+ 'Children mode — render rows directly in the tbody instead of using data-driven rendering.',+ },+ {+ name: 'tableProps',+ type: 'HTMLAttributes<HTMLTableElement>',+ description:+ 'Additional HTML attributes passed directly to the root <table> element.',+ },+ ],+ examples: [+ {+ label: 'With styled components',+ code: `<XDSBaseTable+ data={items}+ columns={columns}+ plugins={[myPlugin]}+ components={{Row: XDSTableRow, Cell: XDSTableCell, HeaderCell: XDSTableHeaderCell}}+/>`,+ },+ ],+ },+ {+ name: 'XDSTableRow',+ description:+ '<tr> wrapper that reads XDSTableContext to apply striped, hover, and divider styles when used inside XDSTable.',+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Row cell elements.',+ required: true,+ },+ ],+ examples: [+ {+ code: `<XDSTableRow>+ <XDSTableCell>Alice</XDSTableCell>+ <XDSTableCell>30</XDSTableCell>+</XDSTableRow>`,+ },+ ],+ },+ {+ name: 'XDSTableCell',+ description:+ '<td> wrapper that reads XDSTableContext to apply density padding, font size, and divider borders when used inside XDSTable.',+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Cell content.',+ },+ ],+ examples: [+ {+ code: `<XDSTableCell>Cell content</XDSTableCell>`,+ },+ ],+ },+ {+ name: 'XDSTableHeaderCell',+ description:+ '<th> wrapper that reads XDSTableContext to apply density padding, semibold weight, secondary text color, and divider borders when used inside XDSTable.',+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Header cell content.',+ },+ ],+ examples: [+ {+ code: `<XDSTableHeaderCell>Name</XDSTableHeaderCell>`,+ },+ ],+ },+ {+ name: 'useXDSTableSelection',+ description:+ 'Hook that returns a TablePlugin implementing row selection with checkboxes, select-all, and aria-selected. Uses React Context for independent checkbox re-renders.',+ props: [+ {+ name: 'getIsItemSelected',+ type: '(item: T) => boolean',+ description: 'Returns whether the given item is currently selected.',+ required: true,+ },+ {+ name: 'onSelectItem',+ type: '(event: {item: T; isSelected: boolean}) => void',+ description:+ 'Called when a row checkbox is toggled. isSelected is the new desired state.',+ required: true,+ },+ {+ name: 'onSelectAll',+ type: '(event: {isAllSelected: boolean}) => void',+ description: 'Called when the select-all header checkbox is toggled.',+ required: true,+ },+ {+ name: 'getIsAllSelected',+ type: '() => boolean',+ description:+ 'Returns whether all selectable items are currently selected.',+ required: true,+ },+ {+ name: 'getIsIndeterminate',+ type: '() => boolean',+ description:+ 'Returns whether selection is partial (some but not all). Renders the select-all checkbox in indeterminate state.',+ },+ {+ name: 'getIsItemSelectable',+ type: '(item: T) => boolean',+ description:+ 'Returns whether a row should show a checkbox. Non-selectable rows render nothing in the selection cell.',+ default: '() => true',+ },+ {+ name: 'getIsItemEnabled',+ type: '(item: T) => boolean',+ description:+ 'Returns whether a row checkbox is interactive. Disabled rows show a disabled checkbox.',+ default: '() => true',+ },+ ],+ examples: [+ {+ label: 'Basic selection',+ code: `const [selectedKeys, setSelectedKeys] = useState<Set<string>>(new Set());++const selectionPlugin = useXDSTableSelection<User>({+ getIsItemSelected: item => selectedKeys.has(item.id),+ onSelectItem: ({item, isSelected}) => {+ const next = new Set(selectedKeys);+ isSelected ? next.add(item.id) : next.delete(item.id);+ setSelectedKeys(next);+ },+ onSelectAll: ({isAllSelected}) => {+ setSelectedKeys(isAllSelected ? new Set(users.map(u => u.id)) : new Set());+ },+ getIsAllSelected: () => users.every(u => selectedKeys.has(u.id)),+ getIsIndeterminate: () => {+ const count = users.filter(u => selectedKeys.has(u.id)).length;+ return count > 0 && count < users.length;+ },+});++<XDSTable+ data={users}+ columns={columns}+ plugins={{selection: selectionPlugin}}+/>`,+ },+ ],+ },+ ],+};diff --git a/packages/core/src/Table/XDSBaseTable.tsx b/packages/core/src/Table/XDSBaseTable.tsxindex 37b52334a8..5b417609cd 100644--- a/packages/core/src/Table/XDSBaseTable.tsx+++ b/packages/core/src/Table/XDSBaseTable.tsx@@ -5,7 +5,7 @@* @position Core structural component; wrapped by XDSTable.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Table/README.md (component description, props)+ * - /packages/core/src/Table/Table.doc.mjs (component description, props)* - /packages/core/src/Table/XDSTable.test.tsx (tests for new/changed behavior)* - /packages/core/src/Table/index.ts (exports if types change)*/diff --git a/packages/core/src/Table/XDSTable.tsx b/packages/core/src/Table/XDSTable.tsxindex 45de4676ed..4370627995 100644--- a/packages/core/src/Table/XDSTable.tsx+++ b/packages/core/src/Table/XDSTable.tsx@@ -5,7 +5,7 @@* @position Styled wrapper; the primary table API for consumers** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Table/README.md (props table, features, usage examples)+ * - /packages/core/src/Table/Table.doc.mjs (props table, features, usage examples)* - /packages/core/src/Table/XDSTable.test.tsx (tests for new/changed behavior)* - /packages/core/src/Table/index.ts (exports if types change)* - /apps/storybook/stories/Table.stories.tsx (storybook stories)diff --git a/packages/core/src/Table/XDSTableCell.tsx b/packages/core/src/Table/XDSTableCell.tsxindex ed5fe8e1cd..87024041fe 100644--- a/packages/core/src/Table/XDSTableCell.tsx+++ b/packages/core/src/Table/XDSTableCell.tsx@@ -5,7 +5,7 @@* @position Sub-component; used inside XDSTable children mode** SYNC: When modified, update:- * - /packages/core/src/Table/README.md+ * - /packages/core/src/Table/Table.doc.mjs* - /packages/core/src/Table/index.ts*/diff --git a/packages/core/src/Table/XDSTableHeaderCell.tsx b/packages/core/src/Table/XDSTableHeaderCell.tsxindex 89aa558777..1fa49e9005 100644--- a/packages/core/src/Table/XDSTableHeaderCell.tsx+++ b/packages/core/src/Table/XDSTableHeaderCell.tsx@@ -5,7 +5,7 @@* @position Sub-component; used inside XDSTable for header cells** SYNC: When modified, update:- * - /packages/core/src/Table/README.md+ * - /packages/core/src/Table/Table.doc.mjs* - /packages/core/src/Table/index.ts*/diff --git a/packages/core/src/Table/XDSTableRow.tsx b/packages/core/src/Table/XDSTableRow.tsxindex 5c7dd6d2cb..709f918c46 100644--- a/packages/core/src/Table/XDSTableRow.tsx+++ b/packages/core/src/Table/XDSTableRow.tsx@@ -5,7 +5,7 @@* @position Sub-component; used inside XDSTable children mode** SYNC: When modified, update:- * - /packages/core/src/Table/README.md+ * - /packages/core/src/Table/Table.doc.mjs* - /packages/core/src/Table/index.ts*/diff --git a/packages/core/src/Table/columnUtils.ts b/packages/core/src/Table/columnUtils.tsindex bbc9845f0d..fb7140cde3 100644--- a/packages/core/src/Table/columnUtils.ts+++ b/packages/core/src/Table/columnUtils.ts@@ -5,7 +5,7 @@* @position Utility layer; consumed by XDSBaseTable.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Table/README.md (utility descriptions)+ * - /packages/core/src/Table/Table.doc.mjs (utility descriptions)* - /packages/core/src/Table/index.ts (exports if functions change)*/diff --git a/packages/core/src/Table/index.ts b/packages/core/src/Table/index.tsindex 84a940a2e3..1c9f210741 100644--- a/packages/core/src/Table/index.ts+++ b/packages/core/src/Table/index.ts@@ -4,7 +4,7 @@* @output Exports all Table components, types, and utilities* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/Table/README.md+ * SYNC: When modified, update this header and /packages/core/src/Table/Table.doc.mjs*/export {XDSBaseTable} from './XDSBaseTable';diff --git a/packages/core/src/Table/plugins/selection/useXDSTableSelection.tsx b/packages/core/src/Table/plugins/selection/useXDSTableSelection.tsxindex 7b4dc0ff38..102fc5c961 100644--- a/packages/core/src/Table/plugins/selection/useXDSTableSelection.tsx+++ b/packages/core/src/Table/plugins/selection/useXDSTableSelection.tsx@@ -5,7 +5,7 @@* @position Selection plugin; consumed by XDSTable via plugins prop** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Table/README.md (selection documentation)+ * - /packages/core/src/Table/Table.doc.mjs (selection documentation)* - /packages/core/src/Table/index.ts (exports)*/diff --git a/packages/core/src/Table/types.ts b/packages/core/src/Table/types.tsindex 1077eced29..6735254325 100644--- a/packages/core/src/Table/types.ts+++ b/packages/core/src/Table/types.ts@@ -5,7 +5,7 @@* @position Type foundation; consumed by XDSBaseTable and extended by XDSTable** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Table/README.md (type descriptions)+ * - /packages/core/src/Table/Table.doc.mjs (type descriptions)* - /packages/core/src/Table/index.ts (exports if types change)*/diff --git a/packages/core/src/Text/README.md b/packages/core/src/Text/README.mddeleted file mode 100644index 43783411ee..0000000000--- a/packages/core/src/Text/README.md+++ /dev/null@@ -1,109 +0,0 @@-# Text--Typography components for the XDS design system.--<!-- SYNC: When files in this directory change, update this document. -->--## Components--| File | Export | Purpose |-| -------------------- | ------------------------- | ---------------------------------------------------------- |-| `XDSText.tsx` | `XDSText` | Body text with semantic variants (body, supporting, label) |-| `XDSHeading.tsx` | `XDSHeading` | Headings with level and size props |-| `XDSFontWrapper.tsx` | `XDSFontWrapper` | Wrapper that applies typography styles to native HTML |-| `XDSFontWrapper.tsx` | `useXDSFontWrapperStyles` | Hook for programmatic StyleX access to typography styles |--## Utilities--| File | Export | Purpose |-| ------------------ | --------------- | ---------------------------------------------------------- |-| `text.stylex.ts` | Various | StyleX styles for color, weight, display, truncation, etc. |-| `useTruncation.ts` | `useTruncation` | Hook for detecting text overflow |--## Usage Patterns--### XDSText--Body text with semantic variants and truncation support.--```tsx-<XDSText type="body" color="primary">Body text content.</XDSText>-```--| Prop | Type | Default | Description |-| -------------------- | --------------------------------------- | ---------- | --------------------------------------------- |-| `type` | `XDSTextType` | — | Semantic text type (body, supporting, label) |-| `size` | `XDSTextSize` | — | Explicit font size override |-| `color` | `XDSTextColor` | — | Text color (defaults vary by type) |-| `weight` | `XDSTextWeight` | — | Font weight override |-| `display` | `XDSTextDisplay` | `'inline'` | Display type |-| `maxLines` | `number` | `0` | Max lines before truncation |-| `hasTruncateTooltip` | `boolean \| LayerPlacement` | `true` | Tooltip for truncated text |-| `wordBreak` | `XDSWordBreak` | — | Word break behavior |-| `textWrap` | `XDSTextWrap` | — | Text wrapping behavior |-| `hasCapsize` | `boolean` | `false` | Enable optical alignment (text-box-trim) |-| `hasStrikethrough` | `boolean` | `false` | Strikethrough decoration |-| `hasTabularNumbers` | `boolean` | `false` | Use tabular (monospace) numbers |-| `as` | `'span' \| 'p' \| 'div' \| 'label'` | `'span'` | HTML element to render |-| `xstyle` | `StyleXStyles` | — | Constrained styles for layout integration |-| `children` | `ReactNode` | — | Text content |--### XDSHeading--Headings with level-based styling and optional accessibility level override.--```tsx-<XDSHeading level={1} size="2xl">Page Title</XDSHeading>-```--| Prop | Type | Default | Description |-| -------------------- | --------------------------- | ----------- | ---------------------------------------------- |-| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | — | Visual heading level (required) |-| `accessibilityLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | same as `level` | ARIA level override |-| `variant` | `'default' \| 'editorial'` | `'default'` | Visual variant (dense vs editorial scale) |-| `color` | `XDSTextColor` | `'primary'` | Text color |-| `display` | `XDSTextDisplay` | `'block'` | Display type |-| `maxLines` | `number` | `0` | Max lines before truncation |-| `hasTruncateTooltip` | `boolean \| LayerPlacement` | `true` | Tooltip for truncated text |-| `wordBreak` | `XDSWordBreak` | — | Word break behavior |-| `textWrap` | `XDSTextWrap` | — | Text wrapping behavior |-| `hasCapsize` | `boolean` | `false` | Enable optical alignment |-| `hasStrikethrough` | `boolean` | `false` | Strikethrough decoration |-| `xstyle` | `StyleXStyles` | — | Constrained styles for layout integration |-| `children` | `ReactNode` | — | Heading content |--### XDSFontWrapper--Wrapper that applies typography styles to native HTML (for user content/markdown).--```tsx-<XDSFontWrapper variant="editorial">- <article dangerouslySetInnerHTML={{__html: markdownContent}} />-</XDSFontWrapper>-```--| Prop | Type | Default | Description |-| ------------- | ---------------------------- | ----------- | ------------------------------- |-| `variant` | `'default' \| 'editorial'` | `'default'` | Heading scale variant |-| `children` | `ReactNode` | — | Content to style |-| `data-testid` | `string` | — | Test ID |--### useXDSFontWrapperStyles--Use when you want StyleX-based styling with theme tokens:--```tsx-import {useXDSFontWrapperStyles} from '@xds/core';-import * as stylex from '@stylexjs/stylex';--function Article() {- const {headingStyles, proseStyles} = useXDSFontWrapperStyles();-- return (- <article>- <h1 {...stylex.props(headingStyles?.h1)}>Title</h1>- <p {...stylex.props(proseStyles?.p)}>Content...</p>- </article>- );-}-```diff --git a/packages/core/src/Text/Text.doc.mjs b/packages/core/src/Text/Text.doc.mjsnew file mode 100644index 0000000000..344277c29b--- /dev/null+++ b/packages/core/src/Text/Text.doc.mjs@@ -0,0 +1,352 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Text',+ description:+ 'Typography components for the XDS design system, including semantic body text, headings, and a wrapper for applying typography styles to native HTML.',+ examples: [+ {+ label: 'Body text',+ code: '<XDSText type="body">Body text content.</XDSText>',+ },+ {+ label: 'Supporting text',+ code: '<XDSText type="supporting">Helper text beneath a field.</XDSText>',+ },+ {+ label: 'Heading',+ code: '<XDSHeading level={1}>Page Title</XDSHeading>',+ },+ {+ label: 'Editorial heading',+ code: '<XDSHeading level={1} variant="editorial">Article Title</XDSHeading>',+ },+ {+ label: 'Truncated text with tooltip',+ code: '<XDSText type="body" maxLines={2}>Very long text that will be clamped after two lines and show a tooltip on hover.</XDSText>',+ },+ {+ label: 'Font wrapper for native HTML',+ code: `<XDSFontWrapper variant="editorial">+ <article dangerouslySetInnerHTML={{__html: markdownContent}} />+</XDSFontWrapper>`,+ },+ ],+ features: [+ 'Semantic text types (body, large, label, supporting, code) driven by theme tokens',+ 'Headings use native h1–h6 elements with optional aria-level override for decoupled visual vs document hierarchy',+ 'Line-clamp truncation with automatic overflow-detecting tooltip',+ 'Optical alignment (text-box-trim / capsize) for precise vertical rhythm',+ 'XDSFontWrapper applies typography styles to native HTML — useful for user-generated content and markdown output',+ 'useXDSFontWrapperStyles hook for programmatic StyleX access to heading and prose styles',+ 'Tabular number support for aligned numeric data',+ 'All typography driven by CSS custom properties — fully themeable per-component',+ ],+ accessibility: [+ 'XDSHeading renders the correct semantic h1–h6 element based on the `level` prop.',+ 'When `accessibilityLevel` differs from `level`, `aria-level` is set so screen readers announce the correct document outline position while preserving the visual style.',+ 'Truncated text sets a native `title` attribute as a fallback, and also lazily renders an XDSTooltip for sighted keyboard users.',+ ],+ components: [+ {+ name: 'XDSText',+ description:+ 'Semantic body text component that renders text with type-based styling from the theme, with optional truncation, decoration, and layout props.',+ examples: [+ {+ label: 'Basic',+ code: '<XDSText type="body">Body text</XDSText>',+ },+ {+ label: 'All types',+ code: `<XDSText type="body">Body</XDSText>+<XDSText type="large">Large body</XDSText>+<XDSText type="label">Label</XDSText>+<XDSText type="supporting">Supporting</XDSText>+<XDSText type="code">{'const x = 1;'}</XDSText>`,+ },+ {+ label: 'Truncation',+ code: '<XDSText type="body" maxLines={2}>Clamped to two lines with a tooltip on hover.</XDSText>',+ },+ {+ label: 'Styled text',+ code: '<XDSText type="body" color="secondary" weight="bold" hasTabularNumbers>42,000</XDSText>',+ },+ {+ label: 'Block with strikethrough',+ code: '<XDSText type="body" display="block" hasStrikethrough>Deprecated item</XDSText>',+ },+ ],+ props: [+ {+ name: 'type',+ type: "'body' | 'large' | 'label' | 'supporting' | 'code'",+ description:+ 'Semantic text type. Determines size, weight, and line-height from the theme.',+ required: true,+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Text content.',+ required: true,+ },+ {+ name: 'size',+ type: "'4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl'",+ description:+ 'Explicit font size override. Overrides the size from `type` but preserves other type properties. Prefer using `type` alone.',+ },+ {+ name: 'color',+ type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",+ description:+ "Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others.",+ },+ {+ name: 'weight',+ type: "'normal' | 'medium' | 'semibold' | 'bold'",+ description: 'Font weight override.',+ },+ {+ name: 'display',+ type: "'inline' | 'block'",+ description:+ "Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true.",+ default: "'inline'",+ },+ {+ name: 'as',+ type: "'span' | 'p' | 'div' | 'label'",+ description: 'HTML element to render.',+ default: "'span'",+ },+ {+ name: 'maxLines',+ type: 'number',+ description:+ 'Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated.',+ default: '0',+ },+ {+ name: 'hasTruncateTooltip',+ type: 'boolean | LayerPlacement',+ description:+ 'Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a LayerPlacement string sets a specific position.',+ default: 'true',+ },+ {+ name: 'wordBreak',+ type: "'break-word' | 'break-all'",+ description:+ "Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise.",+ },+ {+ name: 'textWrap',+ type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",+ description: 'Text wrapping behavior.',+ },+ {+ name: 'hasCapsize',+ type: 'boolean',+ description:+ 'Enable optical alignment using text-box-trim. Forces block display.',+ default: 'false',+ },+ {+ name: 'hasStrikethrough',+ type: 'boolean',+ description: 'Apply strikethrough text decoration.',+ default: 'false',+ },+ {+ name: 'hasTabularNumbers',+ type: 'boolean',+ description:+ 'Use tabular (monospace) numbers for aligned numeric data.',+ default: 'false',+ },+ {+ name: 'id',+ type: 'string',+ description: 'HTML id attribute.',+ },+ ],+ },+ {+ name: 'XDSHeading',+ description:+ 'Semantic heading component that renders h1–h6 elements with themed styling, optional editorial scale, and line-clamp truncation.',+ examples: [+ {+ label: 'Basic',+ code: '<XDSHeading level={1}>Page Title</XDSHeading>',+ },+ {+ label: 'Editorial scale',+ code: '<XDSHeading level={1} variant="editorial">Article Title</XDSHeading>',+ },+ {+ label: 'Accessibility level override',+ code: '<XDSHeading level={2} accessibilityLevel={3}>Sidebar Section</XDSHeading>',+ },+ {+ label: 'Truncated heading',+ code: '<XDSHeading level={2} maxLines={1}>Very Long Section Title That Gets Clipped</XDSHeading>',+ },+ {+ label: 'Muted heading',+ code: '<XDSHeading level={3} color="secondary">Muted Heading</XDSHeading>',+ },+ ],+ props: [+ {+ name: 'level',+ type: '1 | 2 | 3 | 4 | 5 | 6',+ description:+ 'Visual heading level. Determines both the HTML element (h1–h6) and the styling from the theme.',+ required: true,+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Heading content.',+ required: true,+ },+ {+ name: 'accessibilityLevel',+ type: '1 | 2 | 3 | 4 | 5 | 6',+ description:+ 'Accessibility level override. When set and different from `level`, applies `aria-level` so the document outline differs from the visual style.',+ },+ {+ name: 'variant',+ type: "'default' | 'editorial'",+ description:+ "Visual variant. 'default' uses a dense scale for internal tools (h1: 20px); 'editorial' uses a larger scale for content-heavy pages (h1: 32px).",+ default: "'default'",+ },+ {+ name: 'color',+ type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",+ description: 'Text color.',+ default: "'primary'",+ },+ {+ name: 'display',+ type: "'inline' | 'block'",+ description:+ "Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true.",+ default: "'block'",+ },+ {+ name: 'maxLines',+ type: 'number',+ description:+ 'Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated.',+ default: '0',+ },+ {+ name: 'hasTruncateTooltip',+ type: 'boolean | LayerPlacement',+ description:+ 'Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a LayerPlacement string sets a specific position.',+ default: 'true',+ },+ {+ name: 'wordBreak',+ type: "'break-word' | 'break-all'",+ description:+ "Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise.",+ },+ {+ name: 'textWrap',+ type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",+ description: 'Text wrapping behavior.',+ },+ {+ name: 'hasCapsize',+ type: 'boolean',+ description:+ 'Enable optical alignment using text-box-trim. Forces block display.',+ default: 'false',+ },+ {+ name: 'hasStrikethrough',+ type: 'boolean',+ description: 'Apply strikethrough text decoration.',+ default: 'false',+ },+ {+ name: 'id',+ type: 'string',+ description: 'HTML id attribute.',+ },+ ],+ },+ {+ name: 'XDSFontWrapper',+ description:+ 'Wrapper that applies XDS typography styles to native HTML elements within its scope. Useful for user-generated content, markdown output, and other scenarios where XDSText and XDSHeading cannot be used directly.',+ examples: [+ {+ label: 'Default variant',+ code: `<XDSFontWrapper>+ <h1>Page Title</h1>+ <p>Body text with <strong>bold</strong> and <em>italic</em>.</p>+ <ul>+ <li>List item 1</li>+ <li>List item 2</li>+ </ul>+</XDSFontWrapper>`,+ },+ {+ label: 'Editorial variant',+ code: `<XDSFontWrapper variant="editorial">+ <article dangerouslySetInnerHTML={{__html: markdownContent}} />+</XDSFontWrapper>`,+ },+ ],+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Content to style with XDS typography.',+ required: true,+ },+ {+ name: 'variant',+ type: "'default' | 'editorial'",+ description:+ "Heading scale variant. 'default' uses a dense scale for internal tools; 'editorial' uses a larger scale for content-heavy pages.",+ default: "'default'",+ },+ ],+ },+ {+ name: 'useXDSFontWrapperStyles',+ description:+ 'Hook that returns StyleX style objects from the current theme for headings and prose elements, for use when applying typography styles to native HTML programmatically.',+ examples: [+ {+ label: 'Basic usage',+ code: `import {useXDSFontWrapperStyles} from '@xds/core';+import * as stylex from '@stylexjs/stylex';++function Article() {+ const {headingStyles, proseStyles} = useXDSFontWrapperStyles();++ return (+ <article>+ <h1 {...stylex.props(headingStyles?.h1)}>Title</h1>+ <p {...stylex.props(proseStyles?.p)}>Content...</p>+ </article>+ );+}`,+ },+ ],+ props: [],+ },+ ],+};diff --git a/packages/core/src/Text/XDSFontWrapper.tsx b/packages/core/src/Text/XDSFontWrapper.tsxindex d4cf469af7..aa81704412 100644--- a/packages/core/src/Text/XDSFontWrapper.tsx+++ b/packages/core/src/Text/XDSFontWrapper.tsx@@ -5,7 +5,7 @@* @position Typography component; provides base styles for wrapped content** SYNC: When modified, update:- * - /packages/core/src/Text/README.md+ * - /packages/core/src/Text/Text.doc.mjs* - /packages/core/src/Text/index.ts*/diff --git a/packages/core/src/Text/XDSHeading.tsx b/packages/core/src/Text/XDSHeading.tsxindex 431f53fc95..945c3d13b2 100644--- a/packages/core/src/Text/XDSHeading.tsx+++ b/packages/core/src/Text/XDSHeading.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSHeading.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Text/README.md (props table, features, implementation notes)+ * - /packages/core/src/Text/Text.doc.mjs (props table, features, implementation notes)* - /packages/core/src/Text/XDSHeading.test.tsx (tests for new/changed behavior)* - /packages/core/src/Text/index.ts (exports if types change)* - /apps/storybook/stories/Text.stories.tsx (storybook stories)diff --git a/packages/core/src/Text/XDSText.tsx b/packages/core/src/Text/XDSText.tsxindex 8a39700eba..836a2fb368 100644--- a/packages/core/src/Text/XDSText.tsx+++ b/packages/core/src/Text/XDSText.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSText.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Text/README.md (props table, features, implementation notes)+ * - /packages/core/src/Text/Text.doc.mjs (props table, features, implementation notes)* - /packages/core/src/Text/XDSText.test.tsx (tests for new/changed behavior)* - /packages/core/src/Text/index.ts (exports if types change)* - /apps/storybook/stories/Text.stories.tsx (storybook stories)diff --git a/packages/core/src/Text/text.stylex.ts b/packages/core/src/Text/text.stylex.tsindex 07aac939a8..e049d5149d 100644--- a/packages/core/src/Text/text.stylex.ts+++ b/packages/core/src/Text/text.stylex.ts@@ -5,7 +5,7 @@* @position Styles module; consumed by XDSText.tsx, XDSHeading.tsx** SYNC: When modified, update:- * - /packages/core/src/Text/README.md+ * - /packages/core/src/Text/Text.doc.mjs*/import * as stylex from '@stylexjs/stylex';diff --git a/packages/core/src/Text/useTruncation.ts b/packages/core/src/Text/useTruncation.tsindex 07879aa752..954ae2c887 100644--- a/packages/core/src/Text/useTruncation.ts+++ b/packages/core/src/Text/useTruncation.ts@@ -5,7 +5,7 @@* @position Hook; consumed by XDSText.tsx, XDSHeading.tsx** SYNC: When modified, update:- * - /packages/core/src/Text/README.md+ * - /packages/core/src/Text/Text.doc.mjs*/'use client';diff --git a/packages/core/src/TextArea/README.md b/packages/core/src/TextArea/README.mddeleted file mode 100644index 20b5ad963b..0000000000--- a/packages/core/src/TextArea/README.md+++ /dev/null@@ -1,102 +0,0 @@-# TextArea--A multi-line text input component for collecting longer user input.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Label Support**: Required label for accessibility (can be visually hidden)-- **Description**: Optional description text displayed between the label and textarea-- **Optional/Required Indicators**: Display "Optional" or "Required" text with bullet separator-- **Disabled State**: Support for disabled textarea with visual styling-- **Accessible**: Label properly associated with textarea via htmlFor/id-- **Styled with StyleX**: Uses XDS design tokens for consistent styling-- **Resizable**: Vertical resize enabled by default with a minimum height--## Usage--```tsx-import { XDSTextArea } from '@xds/core/TextArea';--// Basic textarea with label-<XDSTextArea label="Description" value={description} onChange={setDescription} />--// With placeholder-<XDSTextArea label="Notes" value={notes} onChange={setNotes} placeholder="Enter your notes..." />--// With custom rows-<XDSTextArea label="Message" rows={5} value={message} onChange={setMessage} />--// Hidden label (for screen readers only)-<XDSTextArea label="Comments" isLabelHidden value={comments} onChange={setComments} placeholder="Add a comment..." />--// With description-<XDSTextArea label="Bio" description="Tell us about yourself" value={bio} onChange={setBio} />--// Optional field-<XDSTextArea label="Additional Notes" isOptional value={notes} onChange={setNotes} />--// Required field-<XDSTextArea label="Feedback" isRequired value={feedback} onChange={setFeedback} />--// Disabled field-<XDSTextArea label="Disabled" isDisabled value="Cannot edit this" onChange={setDisabled} />-```--## Props--| Prop | Type | Required | Description |-| --------------- | -------------------------------------------------------------- | -------- | ------------------------------------------------------------------ |-| `label` | `string` | Yes | Label text for the textarea (always rendered for accessibility) |-| `value` | `string` | Yes | Current value of the textarea |-| `onChange` | `(value: string, e: ChangeEvent<HTMLTextAreaElement>) => void` | Yes | Callback fired when textarea value changes |-| `isLabelHidden` | `boolean` | No | Visually hide the label (still accessible to screen readers) |-| `description` | `string` | No | Description text displayed between the label and textarea |-| `isOptional` | `boolean` | No | Whether the field is optional (mutually exclusive with isRequired) |-| `isRequired` | `boolean` | No | Whether the field is required (mutually exclusive with isOptional) |-| `placeholder` | `string` | No | Placeholder text |-| `rows` | `number` | No | Number of visible text rows (default: 3) |-| `isDisabled` | `boolean` | No | Whether the textarea is disabled (default: false) |--## Theming--Themes can override `TextArea` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- textArea: {- wrapper: myStyles,- textarea: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ---------- | ------------------------ |-| `wrapper` | Wrapper container styles |-| `textarea` | Textarea element styles |--## Files--| File | Role | Purpose |-| ---------------------- | ----- | --------------------------- |-| `index.ts` | Entry | Exports component and types |-| `XDSTextArea.tsx` | Core | Component implementation |-| `XDSTextArea.test.tsx` | Test | Unit tests |--## Implementation Notes--- Uses `useId` hook for accessible label-textarea association-- Label is always rendered for accessibility; use `isLabelHidden` to hide visually-- Hidden label uses CSS technique that remains accessible to screen readers-- Wraps `XDSField` component for label, description, and optional/required handling-- `isOptional` and `isRequired` are mutually exclusive; setting both will show "Optional"-- Optional/Required text appears on the same line as the label-- Textarea has vertical resize enabled with a minimum height of 80pxdiff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjsnew file mode 100644index 0000000000..f156d58882--- /dev/null+++ b/packages/core/src/TextArea/TextArea.doc.mjs@@ -0,0 +1,209 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'TextArea',+ description:+ 'A multi-line text input component for collecting longer user input.',+ features: [+ 'Label support — required label for accessibility, can be visually hidden',+ 'Description — optional text displayed between the label and textarea',+ 'Optional/Required indicators — displays "Optional" or "Required" text with bullet separator',+ 'Status variants — warning, error, and success states with colored borders and icons',+ 'Character counter — displays current/max length when maxLength is set',+ 'Start icon — optional icon rendered inside the leading edge of the input',+ 'Label tooltip — optional info icon with tooltip at the end of the label',+ 'Loading state — shows a spinner and uses optimistic updates via useOptimistic',+ 'Async action support — onChangeAction fires after onChange inside a React transition',+ 'Disabled state — visual opacity and cursor changes, no interaction',+ 'Accessible — label associated via htmlFor/id, aria-describedby, aria-required, aria-invalid, aria-busy',+ 'Resizable — vertical resize enabled by default with a minimum height of 80px',+ 'Spell check — browser spell checking enabled by default, configurable',+ ],+ examples: [+ {+ label: 'Basic',+ code: '<XDSTextArea label="Description" value={description} onChange={setDescription} />',+ },+ {+ label: 'With placeholder and custom rows',+ code: '<XDSTextArea label="Notes" rows={5} value={notes} onChange={setNotes} placeholder="Enter your notes..." />',+ },+ {+ label: 'Hidden label',+ code: '<XDSTextArea label="Comments" isLabelHidden value={comments} onChange={setComments} placeholder="Add a comment..." />',+ },+ {+ label: 'With description and optional indicator',+ code: '<XDSTextArea label="Bio" description="Tell us about yourself" isOptional value={bio} onChange={setBio} />',+ },+ {+ label: 'Error status with message',+ code: `<XDSTextArea+ label="Feedback"+ isRequired+ value={feedback}+ onChange={setFeedback}+ status={{type: 'error', message: 'Feedback is required'}}+/>`,+ },+ {+ label: 'With character counter',+ code: '<XDSTextArea label="Summary" maxLength={280} value={summary} onChange={setSummary} />',+ },+ {+ label: 'Disabled',+ code: '<XDSTextArea label="Read-only notes" isDisabled value="Cannot edit this" onChange={() => {}} />',+ },+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description:+ 'Label text for the textarea — always rendered for accessibility.',+ required: true,+ },+ {+ name: 'value',+ type: 'string',+ description: 'Current value of the textarea.',+ required: true,+ },+ {+ name: 'onChange',+ type: '(value: string, e: ChangeEvent<HTMLTextAreaElement>) => void',+ description: 'Callback fired when the textarea value changes.',+ },+ {+ name: 'onChangeAction',+ type: '(value: string, e: ChangeEvent<HTMLTextAreaElement>) => void | Promise<void>',+ description:+ 'Async action fired after onChange inside a React transition. Enables optimistic updates via useOptimistic.',+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description:+ 'Visually hides the label while keeping it accessible to screen readers.',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Helper text displayed between the label and textarea.',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description:+ 'Displays an "Optional" indicator next to the label. Mutually exclusive with isRequired.',+ default: 'false',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description:+ 'Displays a "Required" indicator next to the label and sets aria-required. Mutually exclusive with isOptional.',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Disables the textarea, preventing interaction.',+ default: 'false',+ },+ {+ name: 'isLoading',+ type: 'boolean',+ description:+ 'Puts the textarea in a loading state, showing a spinner inside the input.',+ default: 'false',+ },+ {+ name: 'placeholder',+ type: 'string',+ description: 'Placeholder text shown when the textarea is empty.',+ },+ {+ name: 'rows',+ type: 'number',+ description: 'Number of visible text rows.',+ default: '3',+ },+ {+ name: 'maxLength',+ type: 'number',+ description:+ 'Maximum number of characters allowed. When set, a character counter (current/max) is displayed below the textarea.',+ },+ {+ name: 'status',+ type: "{ type: 'warning' | 'error' | 'success'; message?: string }",+ description:+ 'Status indicator that applies a colored border and icon. An optional message is displayed in a floating box below the textarea.',+ },+ {+ name: 'labelTooltip',+ type: 'string',+ description:+ 'Tooltip text displayed in an info icon at the end of the label.',+ },+ {+ name: 'startIcon',+ type: 'XDSIconType',+ description:+ 'Icon component rendered inside the leading edge of the textarea wrapper.',+ },+ {+ name: 'hasSpellCheck',+ type: 'boolean',+ description: 'Enables or disables browser spell checking.',+ default: 'true',+ },+ {+ name: 'hasAutoFocus',+ type: 'boolean',+ description: 'Automatically focuses the textarea on mount.',+ default: 'false',+ },+ {+ name: 'onPaste',+ type: '(e: ClipboardEvent<HTMLTextAreaElement>) => void',+ description: 'Callback fired when content is pasted into the textarea.',+ },+ {+ name: 'htmlName',+ type: 'string',+ description:+ 'HTML name attribute for the textarea element, useful for form submissions.',+ },+ ],+ theming: {+ componentKey: 'textArea',+ surfaces: [+ {+ name: 'wrapper',+ description: 'Outer wrapper div that contains the textarea and icons.',+ },+ {+ name: 'textarea',+ description: 'The textarea element itself.',+ },+ ],+ },+ accessibility: [+ 'Label is always rendered in the DOM; use isLabelHidden to hide it visually while keeping it accessible.',+ 'The textarea id is generated via useId and linked to its label via htmlFor, ensuring correct label association.',+ 'aria-describedby is set to the description and/or status message IDs when those elements are present.',+ 'aria-required="true" is set when isRequired is true.',+ 'aria-invalid="true" is set when status.type is "error".',+ 'aria-busy is set while an optimistic update or loading state is active.',+ ],+ notes: [+ 'isOptional and isRequired are mutually exclusive; if both are set, "Optional" takes precedence.',+ 'The component uses useOptimistic for instant UI feedback when onChangeAction returns a Promise.',+ 'Textarea has vertical resize enabled via CSS with a minimum height of 80px.',+ 'Wraps XDSField for consistent label, description, and status message layout.',+ 'The character counter text turns red when value.length exceeds maxLength.',+ ],+};diff --git a/packages/core/src/TextArea/XDSTextArea.tsx b/packages/core/src/TextArea/XDSTextArea.tsxindex 39e08b68ab..a7d7d96fe5 100644--- a/packages/core/src/TextArea/XDSTextArea.tsx+++ b/packages/core/src/TextArea/XDSTextArea.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSTextArea.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/TextArea/README.md (props table, features, implementation notes)+ * - /packages/core/src/TextArea/TextArea.doc.mjs (props table, features, implementation notes)* - /packages/core/src/TextArea/XDSTextArea.test.tsx (tests for new/changed behavior)* - /packages/core/src/TextArea/index.ts (exports if types change)* - /apps/storybook/stories/TextArea.stories.tsx (storybook stories)diff --git a/packages/core/src/TextArea/index.ts b/packages/core/src/TextArea/index.tsindex 43b395cfad..49781c7c2e 100644--- a/packages/core/src/TextArea/index.ts+++ b/packages/core/src/TextArea/index.ts@@ -4,7 +4,7 @@* @output Exports XDSTextArea, XDSTextAreaProps, XDSTextAreaStatus, XDSTextAreaStatusType* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/TextArea/README.md+ * SYNC: When modified, update this header and /packages/core/src/TextArea/TextArea.doc.mjs*/export {XDSTextArea} from './XDSTextArea';diff --git a/packages/core/src/TextInput/README.md b/packages/core/src/TextInput/README.mddeleted file mode 100644index f1b96791b4..0000000000--- a/packages/core/src/TextInput/README.md+++ /dev/null@@ -1,103 +0,0 @@-# TextInput--A text input component for collecting user text input.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Label Support**: Required label for accessibility (can be visually hidden)-- **Description**: Optional description text displayed between the label and input-- **Optional/Required Indicators**: Display "Optional" or "Required" text with bullet separator-- **Label Tooltip**: Optional info icon with tooltip at end of label-- **Accessible**: Label properly associated with input via htmlFor/id-- **Styled with StyleX**: Uses XDS design tokens for consistent styling--## Usage--```tsx-import { XDSTextInput } from '@xds/core/TextInput';--// Basic input with label-<XDSTextInput label="Name" value={name} onChange={setName} />--// With placeholder-<XDSTextInput label="Email" value={email} onChange={setEmail} placeholder="[email protected]" />--// Hidden label (for screen readers only)-<XDSTextInput label="Search" isLabelHidden value={query} onChange={setQuery} placeholder="Search..." />--// With description-<XDSTextInput label="Email" description="We'll never share your email" value={email} onChange={setEmail} />--// Optional field-<XDSTextInput label="Nickname" isOptional value={nickname} onChange={setNickname} />--// Required field-<XDSTextInput label="Username" isRequired value={username} onChange={setUsername} />--// With validation status (error, warning, or success)-<XDSTextInput- label="Email"- value={email}- onChange={setEmail}- status={{ type: 'error', message: 'Invalid email address' }}-/>-```--## Props--| Prop | Type | Required | Description |-| --------------- | ----------------------------------------------------------- | -------- | --------------------------------------------------------------------- |-| `label` | `string` | Yes | Label text for the input (always rendered for accessibility) |-| `value` | `string` | Yes | Current value of the input |-| `onChange` | `(value: string, e: ChangeEvent<HTMLInputElement>) => void` | Yes | Callback fired when input value changes |-| `size` | `'sm' \| 'md' \| 'lg'` | No | Size variant (default: `'md'`) |-| `isLabelHidden` | `boolean` | No | Visually hide the label (still accessible to screen readers) |-| `description` | `string` | No | Description text displayed between the label and input |-| `isOptional` | `boolean` | No | Whether the field is optional (mutually exclusive with isRequired) |-| `isRequired` | `boolean` | No | Whether the field is required (mutually exclusive with isOptional) |-| `placeholder` | `string` | No | Placeholder text |-| `labelTooltip` | `string` | No | Tooltip text to display in an info icon at the end of the label |-| `status` | `{type: 'error'\|'warning'\|'success', message?: string}` | No | Validation status with optional message (sets aria-invalid for error) |--## Theming--Themes can override `TextInput` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- textInput: {- wrapper: myStyles,- input: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| --------- | ------------------------ |-| `wrapper` | Wrapper container styles |-| `input` | Input element styles |--## Files--| File | Role | Purpose |-| ----------------------- | ----- | --------------------------- |-| `index.ts` | Entry | Exports component and types |-| `XDSTextInput.tsx` | Core | Component implementation |-| `XDSTextInput.test.tsx` | Test | Unit tests |--## Implementation Notes--- Uses `useId` hook for accessible label-input association-- Label is always rendered for accessibility; use `isLabelHidden` to hide visually-- Hidden label uses CSS technique that remains accessible to screen readers-- Wraps `XDSField` component for label, description, and optional/required handling-- `isOptional` and `isRequired` are mutually exclusive; setting both will show "Optional"-- Optional/Required text appears on the same line as the labeldiff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjsnew file mode 100644index 0000000000..8b223c6c5d--- /dev/null+++ b/packages/core/src/TextInput/TextInput.doc.mjs@@ -0,0 +1,204 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'TextInput',+ description:+ 'A text input component for collecting user text input, with label, description, validation status, and optional/required indicators.',+ features: [+ 'Label support — required label for accessibility (can be visually hidden)',+ 'Description — optional text displayed between the label and input',+ 'Optional/Required indicators — "Optional" or "Required" text with bullet separator',+ 'Label tooltip — optional info icon with tooltip at the end of the label',+ 'Validation status — error, warning, and success states with colored borders and icons',+ 'Start icon — optional icon displayed at the start of the input',+ 'Loading state — shows a spinner and sets aria-busy while an async action is pending',+ 'Disabled state — visually dims the input and prevents interaction',+ 'Accessible — label is always associated with the input via htmlFor/id; sets aria-invalid, aria-required, aria-busy, and aria-describedby as appropriate',+ 'Styled with StyleX — uses XDS design tokens for consistent styling',+ ],+ examples: [+ {+ label: 'Basic',+ code: '<XDSTextInput label="Name" value={name} onChange={setName} />',+ },+ {+ label: 'With placeholder',+ code: '<XDSTextInput label="Email" value={email} onChange={setEmail} placeholder="[email protected]" />',+ },+ {+ label: 'Hidden label',+ code: '<XDSTextInput label="Search" isLabelHidden value={query} onChange={setQuery} placeholder="Search..." />',+ },+ {+ label: 'With description',+ code: `<XDSTextInput+ label="Email"+ description="We'll never share your email"+ value={email}+ onChange={setEmail}+/>`,+ },+ {+ label: 'Optional and required',+ code: `<XDSTextInput label="Nickname" isOptional value={nickname} onChange={setNickname} />+<XDSTextInput label="Username" isRequired value={username} onChange={setUsername} />`,+ },+ {+ label: 'Validation status',+ code: `<XDSTextInput+ label="Email"+ value={email}+ onChange={setEmail}+ status={{type: 'error', message: 'Invalid email address'}}+/>`,+ },+ {+ label: 'With start icon',+ code: `<XDSTextInput+ label="Search"+ value={query}+ onChange={setQuery}+ startIcon={MagnifyingGlassIcon}+ placeholder="Search..."+/>`,+ },+ {+ label: 'Async action with loading state',+ code: `<XDSTextInput+ label="Username"+ value={username}+ onChange={setUsername}+ onChangeAction={async (value) => {+ await checkAvailability(value);+ }}+/>`,+ },+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description:+ 'Label text for the input — always rendered for accessibility.',+ required: true,+ },+ {+ name: 'value',+ type: 'string',+ description: 'Current value of the input.',+ required: true,+ },+ {+ name: 'onChange',+ type: '(value: string, e: ChangeEvent<HTMLInputElement>) => void',+ description: 'Callback fired when the input value changes.',+ },+ {+ name: 'onChangeAction',+ type: '(value: string, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>',+ description:+ 'Async action fired after onChange (if not prevented). Triggers optimistic update and shows a loading spinner while pending.',+ },+ {+ name: 'size',+ type: "'sm' | 'md' | 'lg'",+ description: 'Size variant of the input.',+ default: "'md'",+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description:+ 'Visually hides the label while keeping it accessible to screen readers.',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Description text displayed between the label and input.',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description:+ 'Displays an "Optional" indicator next to the label. Mutually exclusive with isRequired.',+ default: 'false',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description:+ 'Displays a "Required" indicator next to the label and sets aria-required. Mutually exclusive with isOptional.',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description:+ 'Disables the input, preventing interaction and dimming the element.',+ default: 'false',+ },+ {+ name: 'isLoading',+ type: 'boolean',+ description:+ 'Puts the input in a loading state, showing a spinner and setting aria-busy.',+ default: 'false',+ },+ {+ name: 'placeholder',+ type: 'string',+ description: 'Placeholder text shown when the input is empty.',+ },+ {+ name: 'labelTooltip',+ type: 'string',+ description:+ 'Tooltip text displayed in an info icon at the end of the label.',+ },+ {+ name: 'startIcon',+ type: 'XDSIconType',+ description:+ 'SVG icon component displayed at the start of the input (e.g. from heroicons or lucide).',+ },+ {+ name: 'status',+ type: "{type: 'error' | 'warning' | 'success', message?: string}",+ description:+ 'Validation status — applies a colored border and status icon. If message is provided, displays a floating message below the input. Error type also sets aria-invalid.',+ },+ {+ name: 'hasAutoFocus',+ type: 'boolean',+ description: 'Automatically focuses the input on mount.',+ default: 'false',+ },+ {+ name: 'htmlName',+ type: 'string',+ description:+ 'The HTML name attribute for the input, useful for form submissions.',+ },+ ],+ theming: {+ componentKey: 'textInput',+ surfaces: [+ {name: 'wrapper', description: 'Wrapper container element'},+ {name: 'input', description: 'Input element'},+ ],+ },+ accessibility: [+ 'Label is always rendered and associated with the input via htmlFor/id (using useId). Use isLabelHidden to hide it visually while keeping it accessible to screen readers.',+ 'aria-describedby is set automatically when description or a status message is present.',+ 'aria-invalid="true" is set when status.type is "error".',+ 'aria-required="true" is set when isRequired is true.',+ 'aria-busy is set while an optimistic update or isLoading is active.',+ ],+ notes: [+ 'isOptional and isRequired are mutually exclusive — if both are set, "Optional" is shown.',+ 'onChangeAction fires after onChange inside a React transition, enabling useOptimistic for an instant UI update while the async work completes.',+ 'The component wraps XDSField for label, description, and optional/required rendering.',+ 'The size prop supports "sm", "md", and "lg".',+ ],+};diff --git a/packages/core/src/TextInput/XDSTextInput.tsx b/packages/core/src/TextInput/XDSTextInput.tsxindex 694cb42e82..a2aa8471f2 100644--- a/packages/core/src/TextInput/XDSTextInput.tsx+++ b/packages/core/src/TextInput/XDSTextInput.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSTextInput.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/TextInput/README.md (props table, features, implementation notes)+ * - /packages/core/src/TextInput/TextInput.doc.mjs (props table, features, implementation notes)* - /packages/core/src/TextInput/XDSTextInput.test.tsx (tests for new/changed behavior)* - /packages/core/src/TextInput/index.ts (exports if types change)* - /apps/storybook/stories/TextInput.stories.tsx (storybook stories)diff --git a/packages/core/src/TextInput/index.ts b/packages/core/src/TextInput/index.tsindex e83eabd27a..dd6c6e1a12 100644--- a/packages/core/src/TextInput/index.ts+++ b/packages/core/src/TextInput/index.ts@@ -4,7 +4,7 @@* @output Exports XDSTextInput, XDSTextInputProps, XDSTextInputSize, XDSTextInputStatus, XDSTextInputStatusType* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/TextInput/README.md+ * SYNC: When modified, update this header and /packages/core/src/TextInput/TextInput.doc.mjs*/export {XDSTextInput} from './XDSTextInput';diff --git a/packages/core/src/TimeInput/README.md b/packages/core/src/TimeInput/README.mddeleted file mode 100644index 0c1dea3240..0000000000--- a/packages/core/src/TimeInput/README.md+++ /dev/null@@ -1,93 +0,0 @@-# XDSTimeInput--Time input with text parsing and keyboard navigation.--## Import--```tsx-import {XDSTimeInput} from '@xds/core/TimeInput';-```--## Usage--```tsx-// Basic usage-<XDSTimeInput- label="Start time"- value={time}- onChange={setTime}-/>--// 24-hour format with clear button-<XDSTimeInput- label="Meeting time"- value={time}- onChange={setTime}- hourFormat="24h"- hasClear-/>--// With min/max constraints-<XDSTimeInput- label="Business hours"- value={time}- onChange={setTime}- min="09:00"- max="17:00"-/>--// With seconds and validation-<XDSTimeInput- label="Precise time"- value={time}- onChange={setTime}- hasSeconds- status={{ type: 'error', message: 'Invalid time' }}-/>-```--## Props--| Prop | Type | Default | Description |-| --------------- | ------------------------------------------------- | ----------------- | ---------------------------------------------- |-| `label` | `string` | — | Label text (required for accessibility) |-| `isLabelHidden` | `boolean` | `false` | Visually hide label |-| `description` | `string` | — | Description text below label |-| `isOptional` | `boolean` | `false` | Show "(optional)" indicator |-| `isRequired` | `boolean` | `false` | Mark field as required |-| `isDisabled` | `boolean` | `false` | Disable the input |-| `value` | `ISOTimeString` | — | Selected time (HH:MM or HH:MM:SS) |-| `onChange` | `(value: ISOTimeString \| undefined) => void` | — | Callback fired when time changes |-| `min` | `ISOTimeString` | — | Minimum selectable time |-| `max` | `ISOTimeString` | — | Maximum selectable time |-| `hasSeconds` | `boolean` | `false` | Include seconds in the time input |-| `hasClear` | `boolean` | `false` | Show clear button when value is set |-| `hourFormat` | `'12h' \| '24h'` | `'12h'` | Hour display format |-| `increment` | `number` | `1` | Increment in minutes for arrow keys |-| `placeholder` | `string` | `"Select a time"` | Placeholder text |-| `size` | `'sm' \| 'md'` | `'md'` | Input size |-| `status` | `XDSInputStatus` | — | Status indicator (error/warning/success) |--## Theming--Themes can override `TimeInput` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- timeInput: {- wrapper: myStyles,- input: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| --------- | ------------------------- |-| `wrapper` | Input wrapper styles |-| `input` | Text input element styles |diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjsnew file mode 100644index 0000000000..b793a1b19f--- /dev/null+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs@@ -0,0 +1,213 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'TimeInput',+ description:+ 'Time input with free-text entry, text parsing, and arrow-key navigation.',+ features: [+ 'Accepts free-text time entry and parses common formats (e.g. "2:30 PM", "14:30")',+ 'Supports 12-hour and 24-hour display formats',+ 'Arrow-up / arrow-down adjust the time by a configurable minute increment',+ 'Optional seconds display via hasSeconds',+ 'Optional clear button via hasClear',+ 'Min / max range constraints reject out-of-range values',+ 'Async action support via onChangeAction with optimistic UI and loading spinner',+ 'Accessible — label, description, and status message are wired to aria-describedby; aria-required and aria-invalid reflect field state',+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSTimeInput+ label="Start time"+ value={time}+ onChange={setTime}+/>`,+ },+ {+ label: '24-hour format with clear button',+ code: `<XDSTimeInput+ label="Meeting time"+ value={time}+ onChange={setTime}+ hourFormat="24h"+ hasClear+/>`,+ },+ {+ label: 'Min / max constraints',+ code: `<XDSTimeInput+ label="Business hours"+ value={time}+ onChange={setTime}+ min="09:00"+ max="17:00"+/>`,+ },+ {+ label: 'With seconds and error status',+ code: `<XDSTimeInput+ label="Precise time"+ value={time}+ onChange={setTime}+ hasSeconds+ status={{type: 'error', message: 'Invalid time'}}+/>`,+ },+ {+ label: 'Async action with optimistic update',+ code: `<XDSTimeInput+ label="Scheduled time"+ value={time}+ onChange={setTime}+ onChangeAction={async (value) => {+ await saveTime(value);+ }}+/>`,+ },+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Label text for the input (required for accessibility).',+ required: true,+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description:+ 'Visually hides the label while keeping it accessible to screen readers.',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Description text displayed between the label and input.',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description:+ 'Shows an "(optional)" indicator next to the label. Mutually exclusive with isRequired.',+ default: 'false',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description:+ 'Marks the field as required and sets aria-required. Mutually exclusive with isOptional.',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Disables the input and suppresses interactions.',+ default: 'false',+ },+ {+ name: 'value',+ type: 'ISOTimeString',+ description: 'Controlled time value in ISO format (HH:MM or HH:MM:SS).',+ },+ {+ name: 'onChange',+ type: '(value: ISOTimeString | undefined) => void',+ description:+ 'Callback fired when the time changes. Receives undefined when the input is cleared.',+ },+ {+ name: 'onChangeAction',+ type: '(value: ISOTimeString | undefined) => void | Promise<void>',+ description:+ 'Async action fired after onChange. Wrapped in a React transition to provide optimistic UI; triggers the loading spinner while pending.',+ },+ {+ name: 'isLoading',+ type: 'boolean',+ description: 'Puts the input into a loading state, displaying a spinner.',+ default: 'false',+ },+ {+ name: 'min',+ type: 'ISOTimeString',+ description:+ 'Minimum selectable time in ISO format. Values outside the range are rejected.',+ },+ {+ name: 'max',+ type: 'ISOTimeString',+ description:+ 'Maximum selectable time in ISO format. Values outside the range are rejected.',+ },+ {+ name: 'hasSeconds',+ type: 'boolean',+ description: 'Includes seconds in the time display and parsing.',+ default: 'false',+ },+ {+ name: 'hasClear',+ type: 'boolean',+ description:+ 'Shows a clear button when a value is set and the input is not disabled.',+ default: 'false',+ },+ {+ name: 'hourFormat',+ type: "'12h' | '24h'",+ description:+ "Controls the display format. '12h' shows AM/PM (e.g. '2:30 PM'); '24h' uses 24-hour notation (e.g. '14:30').",+ default: "'12h'",+ },+ {+ name: 'increment',+ type: 'number',+ description:+ 'Number of minutes to add or subtract when the user presses the up or down arrow key.',+ default: '1',+ },+ {+ name: 'placeholder',+ type: 'string',+ description:+ 'Placeholder text shown when no time is selected. When the input is focused and empty, a format hint overrides this text.',+ default: "'Select a time'",+ },+ {+ name: 'size',+ type: "'sm' | 'md' | 'lg'",+ description: 'Controls the height of the input element.',+ default: "'md'",+ },+ {+ name: 'status',+ type: 'XDSInputStatus',+ description:+ 'Status indicator that colors the border and displays an icon. When a message is provided it is rendered below the input.',+ },+ {+ name: 'labelTooltip',+ type: 'string',+ description:+ 'Tooltip text rendered as an info icon at the end of the label row.',+ },+ ],+ theming: {+ componentKey: 'timeInput',+ surfaces: [+ {name: 'wrapper', description: 'Outer input wrapper div'},+ {name: 'input', description: 'Text input element'},+ ],+ },+ accessibility: [+ 'The visible label is associated with the input via htmlFor / id.',+ 'isLabelHidden visually hides the label while keeping it in the accessibility tree.',+ 'description and status.message are linked to the input via aria-describedby.',+ 'aria-required is set when isRequired is true.',+ 'aria-invalid is set when status.type is "error".',+ 'aria-busy reflects the loading / optimistic-pending state.',+ 'The clear button has an explicit aria-label of "Clear time".',+ ],+ keyboard:+ 'ArrowUp / ArrowDown adjust the current time by the configured increment in minutes. Typing a time string in common formats (e.g. "2:30 PM", "14:30") is parsed on blur. Pressing the clear button returns focus to the input.',+};diff --git a/packages/core/src/TimeInput/XDSTimeInput.tsx b/packages/core/src/TimeInput/XDSTimeInput.tsxindex 81be6152cf..c0c0250bfd 100644--- a/packages/core/src/TimeInput/XDSTimeInput.tsx+++ b/packages/core/src/TimeInput/XDSTimeInput.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSTimeInput.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/TimeInput/README.md (props table, features, implementation notes)+ * - /packages/core/src/TimeInput/TimeInput.doc.mjs (props table, features, implementation notes)* - /packages/core/src/TimeInput/XDSTimeInput.test.tsx (tests for new/changed behavior)* - /packages/core/src/TimeInput/index.ts (exports if types change)* - /apps/storybook/stories/TimeInput.stories.tsx (storybook stories)diff --git a/packages/core/src/TimeInput/index.ts b/packages/core/src/TimeInput/index.tsindex 199efc953b..2912e80261 100644--- a/packages/core/src/TimeInput/index.ts+++ b/packages/core/src/TimeInput/index.ts@@ -4,7 +4,7 @@* @output Exports XDSTimeInput and related types* @position Component entry point; re-exported by /packages/core/src/index.ts*- * SYNC: When modified, update this header and /packages/core/src/TimeInput/README.md+ * SYNC: When modified, update this header and /packages/core/src/TimeInput/TimeInput.doc.mjs*/export {XDSTimeInput} from './XDSTimeInput';diff --git a/packages/core/src/Token/README.md b/packages/core/src/Token/README.mddeleted file mode 100644index dac65ee28d..0000000000--- a/packages/core/src/Token/README.md+++ /dev/null@@ -1,62 +0,0 @@-# Token--A chip/tag component for displaying entities inline. Renders as a `<span>` by default, `<button>` when `onClick` is provided, or `<a>` when `href` is provided.--Long labels are automatically truncated with an ellipsis. When `onClick` is provided, the focus outline wraps the entire token (not just the label) via `:focus-within` on the container.--## Exports--| Export | Type | Description |-| --------------- | --------- | -------------------- |-| `XDSToken` | Component | Main token component |-| `XDSTokenProps` | Type | Props interface |-| `XDSTokenColor` | Type | Color union type |--## Props--| Prop | Type | Default | Description |-| --------------- | --------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------- |-| `label` | `string` | — | Text label (required) |-| `color` | `'default' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'cyan' \| 'blue' \| 'purple' \| 'pink' \| 'gray'` | `'default'` | Color variant |-| `icon` | `ReactNode` | — | Optional leading icon |-| `isDisabled` | `boolean` | `false` | Whether the token is disabled |-| `onRemove` | `(e: MouseEvent \| KeyboardEvent) => void` | — | Remove handler; shows X button when provided |-| `onClick` | `(e: MouseEvent) => void` | — | Click handler; renders as `<button>` |-| `href` | `string` | — | Link URL; renders as `<a>` |-| `description` | `string` | — | Accessible description |-| `endContent` | `ReactNode` | — | Content after the label |-| `isLabelHidden` | `boolean` | `false` | Visually hide label (still accessible) |-| `xstyle` | `StyleXStyles` | — | Additional StyleX styles |-| `data-testid` | `string` | — | Test ID for testing frameworks |--## Usage--```tsx-import {XDSToken} from '@xds/core/Token';--// Basic-<XDSToken label="Tag" />--// Colored-<XDSToken label="Status" color="green" />--// Removable-<XDSToken label="Filter" onRemove={(e) => handleRemove(e)} />--// Clickable-<XDSToken label="Category" onClick={() => navigate('/category')} />--// As link-<XDSToken label="Profile" href="/user/123" />--// With icon-<XDSToken label="User" icon={<UserIcon />} />-```--## Files--| File | Purpose |-| ------------------- | ------------------------ |-| `XDSToken.tsx` | Component implementation |-| `XDSToken.test.tsx` | Unit tests |-| `index.ts` | Barrel exports |diff --git a/packages/core/src/Token/Token.doc.mjs b/packages/core/src/Token/Token.doc.mjsnew file mode 100644index 0000000000..a2bb01c335--- /dev/null+++ b/packages/core/src/Token/Token.doc.mjs@@ -0,0 +1,114 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Token',+ description:+ 'A chip/tag component for displaying entities inline. Renders as a <span> by default, <a> when href is provided, or a <span> with an invisible <button> inside when onClick is provided.',+ features: [+ 'Polymorphic — renders as <span>, <a>, or interactive <span>+<button> based on props',+ 'Invisible button pattern for onClick preserves real button semantics while allowing focus-within outline on the full token',+ 'Remove button with expanded 14px hit-area tap target via ::after pseudo-element',+ 'Eleven color variants including a neutral default',+ 'Leading icon and trailing endContent slots',+ 'Label can be visually hidden while remaining accessible to screen readers',+ 'Disabled state reduces opacity and blocks pointer events',+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Text label displayed inside the token.',+ required: true,+ },+ {+ name: 'color',+ type: "'default' | 'red' | 'orange' | 'yellow' | 'green' | 'teal' | 'cyan' | 'blue' | 'purple' | 'pink' | 'gray'",+ description: 'Color variant of the token.',+ default: "'default'",+ },+ {+ name: 'icon',+ type: 'ReactNode',+ description: 'Optional icon rendered before the label.',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description:+ 'Whether the token is disabled; reduces opacity and blocks interactions.',+ default: 'false',+ },+ {+ name: 'onRemove',+ type: '(e: React.MouseEvent) => void',+ description:+ 'Callback fired when the remove button is clicked. When provided, an X button is rendered inside the token.',+ },+ {+ name: 'onClick',+ type: '(e: React.MouseEvent) => void',+ description:+ 'Click handler. When provided, the token renders as a <span> container with an invisible <button> inside for accessibility.',+ },+ {+ name: 'href',+ type: 'string',+ description:+ 'Link URL. When provided, the token renders as an <a> element.',+ },+ {+ name: 'description',+ type: 'string',+ description:+ 'Accessible description applied via aria-description on the root element.',+ },+ {+ name: 'endContent',+ type: 'ReactNode',+ description:+ 'Content rendered after the label and before the remove button.',+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description:+ 'Visually hides the label using a screen-reader-only clip technique; the label remains accessible.',+ default: 'false',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: '<XDSToken label="Tag" />',+ },+ {+ label: 'Colored',+ code: '<XDSToken label="Status" color="green" />',+ },+ {+ label: 'Removable',+ code: '<XDSToken label="Filter" onRemove={(e) => handleRemove(e)} />',+ },+ {+ label: 'Clickable',+ code: '<XDSToken label="Category" onClick={() => navigate(\'/category\')} />',+ },+ {+ label: 'As link',+ code: '<XDSToken label="Profile" href="/user/123" />',+ },+ {+ label: 'With icon and hidden label',+ code: '<XDSToken label="User" icon={<UserIcon />} isLabelHidden />',+ },+ ],+ accessibility: [+ 'When isLabelHidden is true, the label is clipped visually but exposed via aria-label on the root element so screen readers still announce it.',+ 'The description prop maps to aria-description on the root element for supplementary context.',+ 'When onClick is provided, the clickable content is wrapped in a real <button> so keyboard users can activate it with Enter or Space.',+ 'The remove button has an automatic aria-label of "Remove <label>" and an expanded touch target via a ::after pseudo-element.',+ 'When href is provided, aria-disabled is set on the <a> element when isDisabled is true.',+ ],+ keyboard:+ 'Tab focuses the token (or its inner button when onClick is used). Enter/Space activate a clickable token or the remove button. Remove button is reachable as a separate Tab stop.',+};diff --git a/packages/core/src/Token/XDSToken.test.tsx b/packages/core/src/Token/XDSToken.test.tsxindex 913215ceb8..705c9149fb 100644--- a/packages/core/src/Token/XDSToken.test.tsx+++ b/packages/core/src/Token/XDSToken.test.tsx@@ -328,7 +328,7 @@ describe('XDSToken text overflow', () => {});it('label element has overflow styles when onClick is provided', () => {- const {container} = render(+ const {container: _container} = render(<XDSToken label="A very long clickable label" onClick={() => {}} />,);// In onClick mode, the label is inside the invisible buttondiff --git a/packages/core/src/Token/XDSToken.tsx b/packages/core/src/Token/XDSToken.tsxindex e0302f2922..8aa4b9271e 100644--- a/packages/core/src/Token/XDSToken.tsx+++ b/packages/core/src/Token/XDSToken.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts, tested by XDSToken.test.tsx** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Token/README.md (props table, features, implementation notes)+ * - /packages/core/src/Token/Token.doc.mjs (props table, features, implementation notes)* - /packages/core/src/Token/XDSToken.test.tsx (tests for new/changed behavior)* - /packages/core/src/Token/index.ts (exports if types change)* - /apps/storybook/stories/Token.stories.tsx (storybook stories)diff --git a/packages/core/src/Tokenizer/Tokenizer.doc.mjs b/packages/core/src/Tokenizer/Tokenizer.doc.mjsnew file mode 100644index 0000000000..e74d222467--- /dev/null+++ b/packages/core/src/Tokenizer/Tokenizer.doc.mjs@@ -0,0 +1,212 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Tokenizer',+ description:+ 'Multi-select typeahead with token chips for selected items. Composes XDSBaseTypeahead for search and XDSToken for chips.',+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Accessible label for the input.',+ required: true,+ },+ {+ name: 'searchSource',+ type: 'XDSSearchSource<T>',+ description:+ 'Data source providing search and bootstrap methods for populating the dropdown.',+ required: true,+ },+ {+ name: 'value',+ type: 'T[]',+ description: 'Array of currently selected items.',+ required: true,+ },+ {+ name: 'onChange',+ type: '(items: T[], change: XDSTokenizerChange<T>) => void',+ description:+ "Called when selection changes. The change argument includes the affected item and type ('add' | 'remove' | 'reorder').",+ required: true,+ },+ {+ name: 'placeholder',+ type: 'string',+ description:+ 'Input placeholder text. Only shown when no tokens are selected.',+ },+ {+ name: 'maxEntries',+ type: 'number',+ description:+ 'Maximum number of selections allowed. Input is hidden when the limit is reached.',+ },+ {+ name: 'hasClear',+ type: 'boolean',+ description: 'Show a clear-all button for bulk removal of all tokens.',+ default: 'false',+ },+ {+ name: 'renderToken',+ type: '(item: T, onRemove: () => void) => ReactNode',+ description:+ 'Custom render function for selected tokens. Default renders XDSToken with label and onRemove.',+ },+ {+ name: 'renderItem',+ type: '(item: T) => ReactNode',+ description:+ 'Custom render function for dropdown items. Default renders XDSTypeaheadItem.',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Disables the input and all token interactions.',+ default: 'false',+ },+ {+ name: 'status',+ type: 'XDSInputStatus',+ description:+ 'Validation status object with type and message for error/warning/success states.',+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: 'Visually hides the label while keeping it accessible.',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Helper text displayed below the label.',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description: 'Marks the field as required.',+ default: 'false',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description: 'Shows an optional indicator on the label.',+ default: 'false',+ },+ {+ name: 'labelTooltip',+ type: 'string',+ description: 'Tooltip text shown on the label.',+ },+ {+ name: 'hasEntriesOnFocus',+ type: 'boolean',+ description: 'Show bootstrap results on focus before typing.',+ default: 'false',+ },+ {+ name: 'maxMenuItems',+ type: 'number',+ description: 'Maximum number of dropdown items to display.',+ default: '10',+ },+ {+ name: 'emptySearchResultsText',+ type: 'string',+ description: 'Text shown when search returns no results.',+ default: "'No results found'",+ },+ {+ name: 'hasAutoFocus',+ type: 'boolean',+ description: 'Auto-focus the input on mount.',+ default: 'false',+ },+ {+ name: 'size',+ type: "'sm' | 'md'",+ description: 'Input and token size.',+ default: "'md'",+ },+ {+ name: 'debounceMs',+ type: 'number',+ description:+ 'Debounce delay in ms before triggering search. Set to 0 for synchronous sources.',+ default: '150',+ },+ {+ name: 'onChangeQuery',+ type: '(query: string) => void',+ description: 'Callback fired when the search query text changes.',+ },+ ],+ examples: [+ {+ label: 'Basic multi-select',+ code: `const source = {+ search: query => users.filter(u => u.label.includes(query)),+ bootstrap: () => users.slice(0, 5),+};++<XDSTokenizer+ label="Team Members"+ searchSource={source}+ value={selected}+ onChange={(items, change) => {+ setSelected(items);+ }}+ placeholder="Search people..."+/>`,+ },+ {+ label: 'With max entries and clear all',+ code: `<XDSTokenizer+ label="Tags"+ searchSource={tagSource}+ value={tags}+ onChange={(items) => setTags(items)}+ maxEntries={5}+ hasClear+ placeholder="Add up to 5 tags..."+/>`,+ },+ {+ label: 'Custom token rendering',+ code: `<XDSTokenizer+ label="Tags"+ searchSource={tagSource}+ value={tags}+ onChange={(items) => setTags(items)}+ renderToken={(item, onRemove) => (+ <XDSToken+ label={item.label}+ color={item.auxiliaryData.color}+ onRemove={onRemove}+ />+ )}+ maxEntries={10}+/>`,+ },+ ],+ features: [+ 'Token chips for each selected item with remove buttons',+ 'Filtered search that automatically excludes already-selected items',+ 'Max entries to limit number of selections — input hides when limit is reached',+ 'Clear all button for bulk removal of all tokens',+ 'Custom token and item rendering via renderToken and renderItem',+ 'Backspace on empty input removes the last token',+ "Change metadata: onChange receives a second argument with type ('add' | 'remove' | 'reorder')",+ ],+ accessibility: [+ 'Wrapped in XDSField for label, description, and status message association.',+ 'Token container has role="group" with aria-label.',+ 'Clear all button has aria-label="Clear all".',+ 'Combobox pattern provided by XDSBaseTypeahead with aria-expanded and aria-autocomplete.',+ ],+ keyboard:+ 'Backspace on empty input removes last token; Arrow keys navigate dropdown; Enter selects highlighted item; Escape closes dropdown',+};diff --git a/packages/core/src/Tokenizer/XDSTokenizer.test.tsx b/packages/core/src/Tokenizer/XDSTokenizer.test.tsxindex f752ad9e03..58314259cb 100644--- a/packages/core/src/Tokenizer/XDSTokenizer.test.tsx+++ b/packages/core/src/Tokenizer/XDSTokenizer.test.tsx@@ -298,7 +298,7 @@ describe('XDSTokenizer', () => {});it('renders tokens as direct children of wrapper (not in a sub-container)', () => {- const {container} = render(+ const {container: _container} = render(<XDSTokenizerlabel="Members"searchSource={userSource}diff --git a/packages/core/src/TopNav/README.md b/packages/core/src/TopNav/README.mddeleted file mode 100644index 28035c07de..0000000000--- a/packages/core/src/TopNav/README.md+++ /dev/null@@ -1,246 +0,0 @@-# TopNav--Top navigation bar component for application headers.--<!-- SYNC: When files in this directory change, update this document. -->--## Features--- **Slot-based layout**: `title`, `startContent`, `endContent` for flexible organization-- **Companion components**: XDSTopNavTitle, XDSTopNavItem-- **Accessible**: Proper ARIA roles and keyboard navigation-- **Themeable**: Uses XDS design tokens for styling--## Usage--```tsx-import {XDSTopNav, XDSTopNavTitle, XDSTopNavItem} from '@xds/core/TopNav';-import {XDSNavIcon} from '@xds/core/NavIcon';-import {XDSButton} from '@xds/core/Button';-import {HomeIcon, BellIcon, UserCircleIcon} from '@heroicons/react/24/outline';--<XDSTopNav- label="Main navigation"- title={- <XDSTopNavTitle- title="My App"- logo={<XDSNavIcon icon={<HomeIcon style={{width: 16, height: 16}} />} />}- href="/"- />- }- startContent={- <>- <XDSTopNavItem label="Dashboard" href="/dashboard" isSelected />- <XDSTopNavItem label="Products" href="/products" />- <XDSTopNavItem label="Reports" href="/reports" />- </>- }- endContent={- <>- <XDSButton- label="Notifications"- variant="ghost"- icon={<BellIcon style={{width: 16, height: 16}} />}- />- <XDSButton- label="Profile"- variant="ghost"- icon={<UserCircleIcon style={{width: 16, height: 16}} />}- />- </>- }-/>;-```--## Components--- **XDSTopNav** — Main navigation container-- **XDSTopNavTitle** — Title with logo and text-- **XDSTopNavItem** — Navigation link item-- **XDSTopNavMenu** — Navigation item with hover-triggered overflow menu--For the circular icon container, use `XDSNavIcon` from `@xds/core/NavIcon`.--## Props--### XDSTopNav--```tsx-<XDSTopNav- label="Main navigation"- title={<XDSTopNavTitle title="My App" href="/" />}- startContent={<XDSTopNavItem label="Dashboard" href="/dashboard" isSelected />}- endContent={<XDSButton label="Profile" variant="ghost" />}-/>-```--| Prop | Type | Default | Description |-| -------------- | ----------- | ------- | ----------------------------------------------------- |-| `title` | `ReactNode` | — | Title slot (logo, brand) - left aligned |-| `startContent` | `ReactNode` | — | Start content (nav items, breadcrumbs) - left aligned |-| `endContent` | `ReactNode` | — | End content (search, icons, profile) - right aligned |-| `label` | `string` | — | Accessible label for navigation landmark |--### XDSTopNavTitle--```tsx-<XDSTopNavTitle title="My App" logo={<XDSNavIcon icon={<HomeIcon />} />} href="/" />-```--| Prop | Type | Default | Description |-| ------- | ----------- | ------- | -------------------------------- |-| `title` | `string` | — | Title text to display |-| `logo` | `ReactNode` | — | Logo element (image, XDSNavIcon) |-| `href` | `string` | — | URL to navigate to when clicked |--### XDSTopNavItem--```tsx-<XDSTopNavItem label="Dashboard" href="/dashboard" isSelected icon={<HomeIcon />} />-```--| Prop | Type | Default | Description |-| ------------ | ----------- | ------- | ------------------------------- |-| `label` | `string` | — | Accessible label (required) |-| `href` | `string` | — | Navigation target URL |-| `isSelected` | `boolean` | `false` | Selected/highlighted state |-| `isDisabled` | `boolean` | `false` | Disabled state |-| `icon` | `ReactNode` | — | Optional icon element |-| `children` | `ReactNode` | — | Custom content instead of label |--### XDSTopNavMenu--```tsx-<XDSTopNavMenu- label="Products"- items={[- {title: 'Analytics', description: 'View metrics', href: '/analytics'},- {title: 'Reports', description: 'Generate reports', href: '/reports'},- ]}-/>-```--| Prop | Type | Default | Description |-| ----------- | ------------------------- | ------- | ------------------------------------------- |-| `label` | `string` | — | Visible label for the trigger (required) |-| `items` | `XDSTopNavMenuItemData[]` | — | Menu items to display in the hover popover |-| `delay` | `number` | `150` | Delay before showing on hover (ms) |-| `hideDelay` | `number` | `200` | Delay before hiding after mouse leaves (ms) |--#### XDSTopNavMenuItemData--| Property | Type | Description |-| ------------- | ------------ | -------------------------------- |-| `title` | `string` | Display title (required) |-| `description` | `string` | Optional description below title |-| `icon` | `ReactNode` | Optional icon on the left |-| `href` | `string` | URL to navigate to |-| `onClick` | `() => void` | Callback on click |--## Selected State--When `isSelected` is true, nav items show:--- **Background**: `--color-accent-deemphasized` (subtle accent tint)-- **Text**: `--color-text-primary` with semibold weight-- **Icon**: Primary color; use `selectedIcon` for filled variants--## Theming--Themes can override `TopNav` styles via `ComponentStyles`:--```tsx-// In your theme definition-const theme: Theme = {- // ...tokens...- components: {- topNav: {- root: myStyles,- },- },-};-```--### Available surfaces--| Surface | Description |-| ------- | ------------------- |-| `root` | Root nav bar styles |--## Files--| File | Role | Purpose |-| ------------------------ | ----- | --------------------------------- |-| `index.ts` | Entry | Exports components and types |-| `XDSTopNav.tsx` | Core | Main navigation container |-| `XDSTopNavTitle.tsx` | Core | Title with logo and text |-| `XDSTopNavItem.tsx` | Core | Navigation link item |-| `XDSTopNavMenu.tsx` | Core | Nav item with hover overflow menu |-| `XDSTopNav.test.tsx` | Test | Unit tests for TopNav components |-| `XDSTopNavMenu.test.tsx` | Test | Unit tests for XDSTopNavMenu |--## Layout Structure--XDSTopNav works in XDSLayout's `header` slot via XDSLayoutHeader (which handles-the divider) or directly. TopNav manages its own padding and height.--```tsx-import {XDSLayout, XDSLayoutContent, XDSLayoutPanel} from '@xds/core/Layout';-import {XDSTopNav, XDSTopNavTitle, XDSTopNavItem} from '@xds/core/TopNav';--<XDSLayout- header={- <XDSTopNav- label="Main navigation"- title={<XDSTopNavTitle title="My App" logo={<Logo />} />}- startContent={- <>- <XDSTopNavItem label="Home" href="/" isSelected />- <XDSTopNavItem label="Settings" href="/settings" />- </>- }- endContent={<Avatar />}- />- }- content={- <XDSLayoutContent role="main">- <MainContent />- </XDSLayoutContent>- }-/>;-```--## Slot Layout Structure--```-┌─────────────────────────────────────────────────────────────┐-│ [title] [startContent ...] [...endContent] │-│ └─ left aligned ─────────────────────────── right aligned ─┤-└─────────────────────────────────────────────────────────────┘-```--**Three-column layout** (with `centerContent`):--```-┌─────────────────────────────────────────────────────────────┐-│ [title] [start...] [centerContent...] [...endContent] │-│ └─ 1fr start ──┘ └── auto center ──┘ └── 1fr end ───┤-└─────────────────────────────────────────────────────────────┘-```--When `centerContent` is provided, the layout switches to a CSS grid with-`gridTemplateColumns: '1fr auto 1fr'`. This guarantees the center column-is always at the exact horizontal center of the nav bar, regardless of-left/right content widths. The right column is always rendered (even when-`endContent` is absent) to maintain the three-column grid structure.--## Implementation Notes--- XDSTopNav uses `role="navigation"` and accepts `aria-label` via the `label` prop-- Without `centerContent`: title and startContent grow to push endContent right-- With `centerContent`: switches to CSS grid (`1fr auto 1fr`) for true centering-- XDSTopNavItem supports `aria-current="page"` when `isSelected` is true-- Default height is 48px with 16px horizontal padding-- Uses `--color-navbar` token for background (defaults to white)-- Positioning (sticky/fixed) is handled by the layout system (e.g. XDSAppShell), not TopNav itself-- Dividers are controlled by the layout system (e.g. XDSLayoutHeader's `hasDivider`), not TopNavdiff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjsnew file mode 100644index 0000000000..bbbc516146--- /dev/null+++ b/packages/core/src/TopNav/TopNav.doc.mjs@@ -0,0 +1,475 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'TopNav',+ description:+ 'Top navigation bar component for application headers with slot-based layout and companion nav item components.',+ features: [+ 'Slot-based layout — title, startContent, centerContent, and endContent slots for flexible organization',+ 'Three-column centering — when centerContent is provided, switches to CSS grid (1fr auto 1fr) for true horizontal centering',+ 'Companion components — XDSTopNavTitle, XDSTopNavItem, XDSTopNavMenu, XDSTopNavMegaMenu',+ 'Accessible — uses role="navigation" with aria-label, aria-current="page" on selected items',+ 'Themeable — supports root style override via theme ComponentStyles',+ 'Link customization — XDSTopNavItem accepts an as prop to swap the anchor element (e.g. for React Router)',+ ],+ examples: [+ {+ label: 'Basic nav with title and items',+ code: `<XDSTopNav+ label="Main navigation"+ title={+ <XDSTopNavTitle+ title="My App"+ logo={<XDSNavIcon icon={<HomeIcon style={{width: 16, height: 16}} />} />}+ href="/"+ />+ }+ startContent={+ <>+ <XDSTopNavItem label="Dashboard" href="/dashboard" isSelected />+ <XDSTopNavItem label="Products" href="/products" />+ <XDSTopNavItem label="Reports" href="/reports" />+ </>+ }+ endContent={+ <>+ <XDSButton+ label="Notifications"+ variant="ghost"+ icon={<BellIcon style={{width: 16, height: 16}} />}+ />+ <XDSButton+ label="Profile"+ variant="ghost"+ icon={<UserCircleIcon style={{width: 16, height: 16}} />}+ />+ </>+ }+/>`,+ },+ {+ label: 'With centered content (three-column layout)',+ code: `<XDSTopNav+ label="Main navigation"+ title={<XDSTopNavTitle title="My App" href="/" />}+ startContent={<XDSTopNavItem label="Home" href="/" isSelected />}+ centerContent={<SearchBar />}+ endContent={<Avatar />}+/>`,+ },+ {+ label: 'With hover menu and mega menu',+ code: `<XDSTopNav+ label="Main navigation"+ title={<XDSTopNavTitle title="My App" href="/" />}+ startContent={+ <>+ <XDSTopNavItem label="Home" href="/" isSelected />+ <XDSTopNavMenu+ label="Products"+ items={[+ {title: 'Analytics', description: 'View metrics', href: '/analytics'},+ {title: 'Reports', description: 'Generate reports', href: '/reports'},+ ]}+ />+ <XDSTopNavMegaMenu+ label="Solutions"+ items={[+ {title: 'Enterprise', description: 'For large teams', icon: <BuildingIcon />, href: '/enterprise'},+ {title: 'Startups', description: 'Move fast', icon: <RocketIcon />, href: '/startups'},+ ]}+ featured={{+ title: 'New: AI Features',+ description: 'Explore our latest AI-powered tools.',+ linkText: 'Learn more →',+ linkHref: '/ai',+ }}+ />+ </>+ }+/>`,+ },+ {+ label: 'In XDSLayout header slot',+ code: `<XDSLayout+ header={+ <XDSTopNav+ label="Main navigation"+ title={<XDSTopNavTitle title="My App" logo={<Logo />} href="/" />}+ startContent={+ <>+ <XDSTopNavItem label="Home" href="/" isSelected />+ <XDSTopNavItem label="Settings" href="/settings" />+ </>+ }+ endContent={<Avatar />}+ />+ }+ content={+ <XDSLayoutContent role="main">+ <MainContent />+ </XDSLayoutContent>+ }+/>`,+ },+ ],+ theming: {+ componentKey: 'topNav',+ surfaces: [{name: 'root', description: 'Root nav bar element'}],+ },+ accessibility: [+ 'XDSTopNav renders a <nav> element with role="navigation" and aria-label set from the label prop',+ 'XDSTopNavItem sets aria-current="page" when isSelected is true',+ 'XDSTopNavItem sets aria-label for icon-only items (when icon is provided and no children or label text is visible)',+ 'XDSTopNavItem sets aria-disabled and tabIndex=-1 when isDisabled is true',+ 'XDSTopNavMenu sets aria-haspopup="true" on the trigger button',+ 'XDSTopNavMegaMenu sets aria-haspopup="true" and aria-expanded on the trigger button',+ 'XDSTopNavMegaMenu menu items are unreachable by keyboard (tabIndex=-1) when the panel is closed',+ 'Escape key closes the XDSTopNavMegaMenu panel',+ ],+ keyboard:+ 'Tab to navigate between items; Escape closes XDSTopNavMegaMenu panels',+ notes: [+ 'Default height is 48px (--spacing-12) with 16px horizontal padding',+ 'Uses --color-navbar token for background (defaults to white)',+ 'Without centerContent: title and startContent grow to push endContent right (flex layout)',+ 'With centerContent: switches to CSS grid (gridTemplateColumns: 1fr auto 1fr) — the right column is always rendered even when endContent is absent to maintain the three-column structure',+ 'Positioning (sticky/fixed) is handled by the layout system (e.g. XDSAppShell), not TopNav itself',+ 'Dividers are controlled by the layout system (e.g. XDSLayoutHeader hasDivider), not TopNav',+ 'XDSTopNavMegaMenu panels position relative to the nearest positioned ancestor — wrap XDSTopNav in a container with position: relative for correct full-width behavior',+ ],+ components: [+ {+ name: 'XDSTopNav',+ description: 'Main navigation bar container with slot-based layout.',+ props: [+ {+ name: 'title',+ type: 'ReactNode',+ description:+ 'Title slot content (logo, brand) — positioned at the left edge of the nav bar.',+ },+ {+ name: 'startContent',+ type: 'ReactNode',+ description:+ 'Start content slot for navigation items or breadcrumbs — positioned after the title, left-aligned.',+ },+ {+ name: 'centerContent',+ type: 'ReactNode',+ description:+ 'Center content slot (tabs, search bar, primary navigation) — when provided, switches the layout to a three-column CSS grid for true horizontal centering.',+ },+ {+ name: 'endContent',+ type: 'ReactNode',+ description:+ 'End content slot for search, icons, or user profile — positioned at the right edge.',+ },+ {+ name: 'label',+ type: 'string',+ description:+ 'Accessible label for the navigation landmark, applied as aria-label on the <nav> element.',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSTopNav+ label="Main navigation"+ title={<XDSTopNavTitle title="My App" href="/" />}+ startContent={<XDSTopNavItem label="Dashboard" href="/dashboard" isSelected />}+ endContent={<XDSButton label="Profile" variant="ghost" />}+/>`,+ },+ {+ label: 'With centered content',+ code: `<XDSTopNav+ label="Main navigation"+ title={<XDSTopNavTitle title="My App" href="/" />}+ centerContent={<SearchInput placeholder="Search..." />}+ endContent={<Avatar />}+/>`,+ },+ ],+ },+ {+ name: 'XDSTopNavTitle',+ description:+ 'Title component for the XDSTopNav title slot — displays a logo and/or title text, optionally as a clickable link.',+ props: [+ {+ name: 'title',+ type: 'string',+ description: 'Title text to display.',+ },+ {+ name: 'logo',+ type: 'ReactNode',+ description:+ 'Logo element to display before the title text. Can be an image, XDSNavIcon, or any ReactNode.',+ },+ {+ name: 'href',+ type: 'string',+ description:+ 'URL to navigate to when clicked. When provided, renders as an anchor element.',+ },+ ],+ examples: [+ {+ label: 'Logo with text link',+ code: `<XDSTopNavTitle+ title="My App"+ logo={<img src="/logo.svg" alt="" width={24} height={24} />}+ href="/"+/>`,+ },+ {+ label: 'With XDSNavIcon',+ code: `<XDSTopNavTitle+ title="Dashboard"+ logo={<XDSNavIcon icon={<HomeIcon style={{width: 16, height: 16}} />} />}+ href="/"+/>`,+ },+ {+ label: 'Logo only',+ code: `<XDSTopNavTitle logo={<BrandLogo />} href="/" />`,+ },+ ],+ },+ {+ name: 'XDSTopNavItem',+ description:+ 'Navigation link item for use in XDSTopNav startContent — renders as an anchor with hover and selected states.',+ props: [+ {+ name: 'label',+ type: 'string',+ description:+ 'Accessible label for the nav item. Used as visible text, or as aria-label for icon-only items.',+ required: true,+ },+ {+ name: 'href',+ type: 'string',+ description: 'Navigation target URL.',+ },+ {+ name: 'isSelected',+ type: 'boolean',+ description:+ 'Whether this nav item is currently selected. Sets aria-current="page" and applies highlighted styles.',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description:+ 'Whether the nav item is disabled. Sets aria-disabled and prevents interaction.',+ default: 'false',+ },+ {+ name: 'icon',+ type: 'ReactNode',+ description:+ 'Optional icon to display before the label. If provided without children, the item becomes icon-only.',+ },+ {+ name: 'children',+ type: 'ReactNode',+ description:+ 'Custom content to render instead of the label text. When omitted and an icon is provided, the item becomes icon-only.',+ },+ {+ name: 'as',+ type: 'XDSLinkComponentType',+ description:+ 'Custom component to render instead of <a>. Overrides the provider-level default set by XDSLinkProvider. Must accept href, className, style, and children props.',+ },+ ],+ examples: [+ {+ label: 'Basic nav items',+ code: `<>+ <XDSTopNavItem label="Home" href="/" isSelected />+ <XDSTopNavItem label="Products" href="/products" />+ <XDSTopNavItem label="Settings" href="/settings" isDisabled />+</>`,+ },+ {+ label: 'With icon',+ code: `<XDSTopNavItem+ label="Settings"+ href="/settings"+ icon={<GearIcon style={{width: 16, height: 16}} />}+/>`,+ },+ {+ label: 'Icon only',+ code: `<XDSTopNavItem+ label="Notifications"+ href="/notifications"+ icon={<BellIcon style={{width: 16, height: 16}} />}+/>`,+ },+ ],+ },+ {+ name: 'XDSTopNavMenu',+ description:+ 'Navigation item that displays a hover-triggered popover menu with rich items containing an icon, title, and optional description.',+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Visible label for the trigger button.',+ required: true,+ },+ {+ name: 'items',+ type: 'XDSTopNavMenuItemData[]',+ description: 'Menu items to display in the hover popover.',+ required: true,+ },+ {+ name: 'delay',+ type: 'number',+ description:+ 'Delay in milliseconds before showing the menu on hover.',+ default: '150',+ },+ {+ name: 'hideDelay',+ type: 'number',+ description:+ 'Delay in milliseconds before hiding the menu after the mouse leaves.',+ default: '200',+ },+ ],+ examples: [+ {+ label: 'Basic hover menu',+ code: `<XDSTopNavMenu+ label="Products"+ items={[+ {title: 'Analytics', description: 'View metrics', href: '/analytics'},+ {title: 'Reports', description: 'Generate reports', href: '/reports'},+ ]}+/>`,+ },+ {+ label: 'With icons and click handlers',+ code: `<XDSTopNavMenu+ label="Tools"+ items={[+ {+ title: 'Analytics',+ description: 'Track and analyze user behavior',+ icon: <ChartBarIcon />,+ href: '/analytics',+ },+ {+ title: 'Export',+ description: 'Download your data',+ icon: <ArrowDownTrayIcon />,+ onClick: () => openExportDialog(),+ },+ ]}+/>`,+ },+ ],+ },+ {+ name: 'XDSTopNavMegaMenu',+ description:+ 'Navigation item that displays a full-width mega menu panel on hover, with items in a two-column grid and an optional featured content area.',+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Visible label for the trigger button.',+ required: true,+ },+ {+ name: 'items',+ type: 'XDSTopNavMegaMenuItemData[]',+ description: 'Menu items to display in the mega menu panel.',+ required: true,+ },+ {+ name: 'featured',+ type: 'XDSTopNavMegaMenuFeatured',+ description:+ 'Optional featured content displayed on the right side of the mega menu panel.',+ },+ {+ name: 'delay',+ type: 'number',+ description:+ 'Delay in milliseconds before showing the menu on hover.',+ default: '150',+ },+ {+ name: 'hideDelay',+ type: 'number',+ description:+ 'Delay in milliseconds before hiding the menu after the mouse leaves.',+ default: '250',+ },+ {+ name: 'isSingleColumn',+ type: 'boolean',+ description:+ 'Whether to use a single-column layout for menu items instead of two columns.',+ default: 'false',+ },+ {+ name: 'onOpenChange',+ type: '(isOpen: boolean) => void',+ description:+ 'Callback fired when the mega menu opens or closes. Useful for coordinating wrapper styles.',+ },+ ],+ examples: [+ {+ label: 'With featured content',+ code: `<div style={{position: 'relative'}}>+ <XDSTopNav+ startContent={+ <XDSTopNavMegaMenu+ label="Solutions"+ items={[+ {title: 'Enterprise', description: 'For large teams', icon: <BuildingIcon />, href: '/enterprise'},+ {title: 'Startups', description: 'Move fast', icon: <RocketIcon />, href: '/startups'},+ ]}+ featured={{+ title: 'New: AI Features',+ description: 'Explore our latest AI-powered tools.',+ linkText: 'Learn more →',+ linkHref: '/ai',+ }}+ />+ }+ />+</div>`,+ },+ {+ label: 'Single column layout',+ code: `<XDSTopNavMegaMenu+ label="Products"+ isSingleColumn+ items={[+ {title: 'Analytics', description: 'Track behavior', icon: <ChartIcon />, href: '/analytics'},+ {title: 'Messaging', description: 'Real-time comms', icon: <ChatIcon />, href: '/messaging'},+ {title: 'Storage', description: 'Manage your data', icon: <DatabaseIcon />, href: '/storage'},+ ]}+/>`,+ },+ ],+ },+ ],+};diff --git a/packages/core/src/TopNav/XDSTopNav.tsx b/packages/core/src/TopNav/XDSTopNav.tsxindex 56c9149c1f..8a0dff0354 100644--- a/packages/core/src/TopNav/XDSTopNav.tsx+++ b/packages/core/src/TopNav/XDSTopNav.tsx@@ -5,7 +5,7 @@* @position Core implementation; consumed by index.ts** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/TopNav/README.md+ * - /packages/core/src/TopNav/TopNav.doc.mjs* - /packages/core/src/TopNav/XDSTopNav.test.tsx* - /packages/core/src/TopNav/index.ts* - /apps/storybook/stories/TopNav.stories.tsxdiff --git a/packages/core/src/TopNav/XDSTopNavItem.tsx b/packages/core/src/TopNav/XDSTopNavItem.tsxindex 656dd13aa4..2d6ae4fcb8 100644--- a/packages/core/src/TopNav/XDSTopNavItem.tsx+++ b/packages/core/src/TopNav/XDSTopNavItem.tsx@@ -5,7 +5,7 @@* @position Navigation item component for XDSTopNav startContent** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/TopNav/README.md+ * - /packages/core/src/TopNav/TopNav.doc.mjs* - /packages/core/src/TopNav/XDSTopNav.test.tsx* - /packages/core/src/TopNav/index.ts* - /apps/storybook/stories/TopNav.stories.tsxdiff --git a/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx b/packages/core/src/TopNav/XDSTopNavMegaMenu.tsxindex 999f08d12b..9ec0bf2d48 100644--- a/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx+++ b/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx@@ -9,7 +9,7 @@* the nav wrapper.** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/TopNav/README.md+ * - /packages/core/src/TopNav/TopNav.doc.mjs* - /packages/core/src/TopNav/index.ts*/diff --git a/packages/core/src/TopNav/XDSTopNavMenu.tsx b/packages/core/src/TopNav/XDSTopNavMenu.tsxindex e27a80e8ef..d484c56bbb 100644--- a/packages/core/src/TopNav/XDSTopNavMenu.tsx+++ b/packages/core/src/TopNav/XDSTopNavMenu.tsx@@ -5,7 +5,7 @@* @position Navigation item with hover-triggered overflow menu for XDSTopNav** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/TopNav/README.md+ * - /packages/core/src/TopNav/TopNav.doc.mjs* - /packages/core/src/TopNav/XDSTopNavMenu.test.tsx* - /packages/core/src/TopNav/index.ts*/diff --git a/packages/core/src/TopNav/XDSTopNavTitle.tsx b/packages/core/src/TopNav/XDSTopNavTitle.tsxindex 213fe11662..aa7d30670b 100644--- a/packages/core/src/TopNav/XDSTopNavTitle.tsx+++ b/packages/core/src/TopNav/XDSTopNavTitle.tsx@@ -5,7 +5,7 @@* @position Companion component for XDSTopNav title slot** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/TopNav/README.md+ * - /packages/core/src/TopNav/TopNav.doc.mjs* - /packages/core/src/TopNav/XDSTopNav.test.tsx* - /packages/core/src/TopNav/index.ts* - /apps/storybook/stories/TopNav.stories.tsxdiff --git a/packages/core/src/TopNav/index.ts b/packages/core/src/TopNav/index.tsindex cfc8206376..a9adb5a1ad 100644--- a/packages/core/src/TopNav/index.ts+++ b/packages/core/src/TopNav/index.ts@@ -4,7 +4,7 @@* @output Exports XDSTopNav and companion components* @position Entry point for TopNav module*- * SYNC: When modified, update /packages/core/src/TopNav/README.md+ * SYNC: When modified, update /packages/core/src/TopNav/TopNav.doc.mjs*/export {XDSTopNav} from './XDSTopNav';diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjsnew file mode 100644index 0000000000..8cb13f5faf--- /dev/null+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs@@ -0,0 +1,405 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Typeahead',+ description:+ 'Searchable dropdown components for single-item selection with keyboard navigation. Supports async and sync search via a searchSource interface.',+ features: [+ 'Async and sync search via a searchSource interface with search() and bootstrap() methods',+ 'Bootstrap results shown on focus before typing (via hasEntriesOnFocus)',+ 'Edit mode: clicking selected token enters edit mode with text pre-populated and selected',+ 'Combobox ARIA pattern for full accessibility',+ 'Debounced search with configurable delay (default 150ms, set to 0 for synchronous sources)',+ 'Two-layer architecture: XDSBaseTypeahead provides the engine, XDSTypeahead adds field chrome',+ ],+ examples: [+ {+ label: 'Basic typeahead',+ code: `const source = {+ search: query => fruits.filter(f => f.label.includes(query)),+ bootstrap: () => fruits.slice(0, 5),+};++<XDSTypeahead+ label="Fruit"+ searchSource={source}+ value={selected}+ onChange={setSelected}+ placeholder="Search fruits..."+/>`,+ },+ {+ label: 'With custom item rendering',+ code: `<XDSTypeahead+ label="Assignee"+ searchSource={userSource}+ value={assignee}+ onChange={setAssignee}+ placeholder="Search users..."+ hasEntriesOnFocus+ renderItem={(item) => (+ <XDSTypeaheadItem+ item={item}+ icon={<XDSAvatar src={item.auxiliaryData.avatar} size="sm" />}+ description={item.auxiliaryData.role}+ />+ )}+/>`,+ },+ {+ label: 'With validation status',+ code: `<XDSTypeahead+ label="Manager"+ searchSource={managerSource}+ value={manager}+ onChange={setManager}+ isRequired+ status={{ type: 'error', message: 'A manager is required' }}+/>`,+ },+ ],+ components: [+ {+ name: 'XDSTypeahead',+ description:+ 'Styled typeahead with label, description, validation, and all field features. Wraps XDSBaseTypeahead with XDSField for the primary use case.',+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Accessible label for the input.',+ required: true,+ },+ {+ name: 'searchSource',+ type: 'XDSSearchSource<T>',+ description:+ 'Data source providing search and bootstrap methods for populating the dropdown.',+ required: true,+ },+ {+ name: 'value',+ type: 'T | null',+ description:+ 'Currently selected item, or null if nothing is selected.',+ required: true,+ },+ {+ name: 'onChange',+ type: '(item: T | null) => void',+ description: 'Called when the selection changes.',+ required: true,+ },+ {+ name: 'placeholder',+ type: 'string',+ description: 'Input placeholder text.',+ },+ {+ name: 'hasEntriesOnFocus',+ type: 'boolean',+ description: 'Show bootstrap results on focus before typing.',+ default: 'false',+ },+ {+ name: 'hasClear',+ type: 'boolean',+ description: 'Show clear button to deselect the current value.',+ default: 'true',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Disables the input.',+ default: 'false',+ },+ {+ name: 'maxMenuItems',+ type: 'number',+ description: 'Maximum number of dropdown items to display.',+ default: '10',+ },+ {+ name: 'status',+ type: 'XDSInputStatus',+ description:+ 'Validation status object with type and message for error/warning/success states.',+ },+ {+ name: 'renderItem',+ type: '(item: T) => ReactNode',+ description:+ 'Custom render function for dropdown items. Default renders XDSTypeaheadItem.',+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: 'Visually hides the label while keeping it accessible.',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Helper text displayed below the label.',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description: 'Marks the field as required.',+ default: 'false',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description: 'Shows an optional indicator on the label.',+ default: 'false',+ },+ {+ name: 'labelTooltip',+ type: 'string',+ description: 'Tooltip text shown on the label.',+ },+ {+ name: 'emptySearchResultsText',+ type: 'string',+ description: 'Text shown when search returns no results.',+ default: "'No results found'",+ },+ {+ name: 'hasAutoFocus',+ type: 'boolean',+ description: 'Auto-focus the input on mount.',+ default: 'false',+ },+ {+ name: 'size',+ type: "'sm' | 'md'",+ description: 'Input and token size.',+ default: "'md'",+ },+ {+ name: 'debounceMs',+ type: 'number',+ description:+ 'Debounce delay in ms before triggering search. Set to 0 for synchronous sources.',+ default: '150',+ },+ {+ name: 'onChangeQuery',+ type: '(query: string) => void',+ description: 'Callback fired when the search query text changes.',+ },+ {+ name: 'onOpenChange',+ type: '(isOpen: boolean) => void',+ description: 'Callback when the dropdown opens or closes.',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSTypeahead+ label="Assignee"+ searchSource={userSource}+ value={assignee}+ onChange={setAssignee}+ placeholder="Search users..."+/>`,+ },+ {+ label: 'With bootstrap on focus',+ code: `<XDSTypeahead+ label="Project"+ searchSource={projectSource}+ value={project}+ onChange={setProject}+ hasEntriesOnFocus+ placeholder="Select a project..."+/>`,+ },+ ],+ },+ {+ name: 'XDSBaseTypeahead',+ description:+ 'Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by XDSTypeahead and XDSTokenizer for custom compositions.',+ props: [+ {+ name: 'searchSource',+ type: 'XDSSearchSource<T>',+ description: 'Data source providing search and bootstrap methods.',+ required: true,+ },+ {+ name: 'value',+ type: 'T | null',+ description: 'Currently selected item.',+ required: true,+ },+ {+ name: 'onChange',+ type: '(item: T | null) => void',+ description: 'Called when the selection changes.',+ required: true,+ },+ {+ name: 'renderItem',+ type: '(item: T) => ReactNode',+ description: 'Custom render function for dropdown items.',+ },+ {+ name: 'placeholder',+ type: 'string',+ description: 'Input placeholder text.',+ default: "'Search...'",+ },+ {+ name: 'hasEntriesOnFocus',+ type: 'boolean',+ description: 'Show bootstrap results on focus before typing.',+ default: 'false',+ },+ {+ name: 'maxMenuItems',+ type: 'number',+ description: 'Maximum dropdown items to display.',+ default: '10',+ },+ {+ name: 'emptySearchResultsText',+ type: 'string',+ description: 'Text shown when search returns no results.',+ default: "'No results found'",+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Whether the input is disabled.',+ default: 'false',+ },+ {+ name: 'hasAutoFocus',+ type: 'boolean',+ description: 'Auto-focus the input on mount.',+ default: 'false',+ },+ {+ name: 'debounceMs',+ type: 'number',+ description:+ 'Debounce delay in ms before triggering search. Set to 0 for synchronous sources.',+ default: '150',+ },+ {+ name: 'anchorRef',+ type: 'RefObject<HTMLElement | null>',+ description:+ 'Ref to the anchor element for dropdown positioning. If not provided, the input itself is used.',+ },+ {+ name: 'inputXStyle',+ type: 'StyleXStyles',+ description: 'Additional StyleX styles for the input element.',+ },+ {+ name: 'onKeyDown',+ type: '(e: React.KeyboardEvent<HTMLInputElement>) => void',+ description:+ 'Additional keydown handler called before internal keyboard navigation. Call e.preventDefault() to skip internal handling.',+ },+ {+ name: 'onChangeQuery',+ type: '(query: string) => void',+ description: 'Callback fired when the search query text changes.',+ },+ {+ name: 'onOpenChange',+ type: '(isOpen: boolean) => void',+ description: 'Callback when the dropdown opens or closes.',+ },+ {+ name: 'inputId',+ type: 'string',+ description: 'ID for the input element (for label association).',+ },+ {+ name: 'ariaDescribedBy',+ type: 'string',+ description: 'Additional aria-describedby IDs.',+ },+ ],+ examples: [+ {+ label: 'With custom wrapper',+ code: `<XDSBaseTypeahead+ searchSource={source}+ value={selected}+ onChange={setSelected}+ anchorRef={wrapperRef}+ placeholder="Search..."+/>`,+ },+ ],+ },+ {+ name: 'XDSTypeaheadItem',+ description:+ 'Default dropdown item renderer for typeahead results. Shows label with optional icon, description, and avatar. Exported for use in custom renderItem implementations.',+ props: [+ {+ name: 'item',+ type: 'XDSSearchableItem',+ description: 'The search result item to render.',+ required: true,+ },+ {+ name: 'icon',+ type: 'ReactNode',+ description: 'Icon or avatar to display before the label.',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Description text displayed below the label.',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Whether this item is visually disabled.',+ default: 'false',+ },+ {+ name: 'group',+ type: 'string',+ description: 'Group label for grouping items visually.',+ },+ ],+ examples: [+ {+ label: 'Custom renderItem with icon and description',+ code: `<XDSTypeaheadItem+ item={user}+ icon={<XDSAvatar src={user.auxiliaryData.avatar} size="sm" />}+ description={user.auxiliaryData.role}+/>`,+ },+ ],+ },+ ],+ accessibility: [+ 'Uses combobox ARIA pattern with role="combobox", aria-expanded, aria-autocomplete="list".',+ 'Dropdown uses role="listbox" with role="option" on each item.',+ 'aria-activedescendant tracks the highlighted option.',+ 'Selected item has aria-selected="true".',+ 'Loading state has role="status" with aria-label="Loading".',+ 'XDSTypeahead wraps in XDSField for label and description association.',+ ],+ keyboard:+ 'Arrow keys navigate dropdown items; Enter selects highlighted item; Escape closes dropdown or restores previous value in edit mode; Home/End jump to first/last item',+ notes: [+ 'XDSSearchSource requires items to implement XDSSearchableItem ({ id: string; label: string; [key: string]: unknown }).',+ 'Edit mode in XDSTypeahead: clicking the selected token removes it visually, populates the input with the label text, and selects all. Blurring without selecting restores the original token.',+ 'XDSBaseTypeahead renders only the <input> and dropdown popover — consumers provide their own wrapper.',+ 'If item has an element property, XDSTypeaheadItem renders it directly instead of the standard layout.',+ ],+};diff --git a/packages/core/src/Typeahead/XDSTypeahead.test.tsx b/packages/core/src/Typeahead/XDSTypeahead.test.tsxindex 26f54b64d7..eddd916190 100644--- a/packages/core/src/Typeahead/XDSTypeahead.test.tsx+++ b/packages/core/src/Typeahead/XDSTypeahead.test.tsx@@ -249,7 +249,7 @@ describe('XDSTypeahead edit mode', () => {onChange={onChange}/>,);- const input = screen.getByRole('combobox');+ screen.getByRole('combobox');// Click the token area to enter edit modeconst removeButton = screen.getByRole('button', {diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.tsnew file mode 100644index 0000000000..616590fd0a--- /dev/null+++ b/packages/core/src/docs-types.ts@@ -0,0 +1,200 @@+/**+ * @file Type definitions for component documentation.+ *+ * Every component directory under `packages/core/src/` has a `{Name}.doc.mjs`+ * that exports a single `docs` constant typed via JSDoc. The CLI imports these+ * directly — no markdown parsing needed.+ */++/**+ * Documents a single component prop. Each prop the component accepts+ * should have an entry. Skip internal/styling props like `xstyle`,+ * `className`, `style`, and `data-testid`.+ *+ * @example+ * ```+ * {name: 'label', type: 'string', description: 'Visible label text', required: true}+ * {name: 'size', type: "'sm' | 'md' | 'lg'", description: 'Control size', default: "'md'"}+ * {name: 'onChange', type: '(value: string) => void', description: 'Called when value changes.'}+ * ```+ */+export interface PropDoc {+ /** Prop name exactly as used in JSX, camelCased.+ * Callbacks start with `on` (`"onChange"`, `"onToggle"`).+ * Booleans use `is`/`has` prefix (`"isDisabled"`, `"hasHover"`). */+ name: string;+ /** TypeScript type signature as a string. Use single quotes for string+ * literal unions. Keep close to the actual TS type.+ *+ * Simple: `"string"`, `"boolean"`, `"ReactNode"`+ * Union: `"'primary' | 'secondary' | 'ghost'"`+ * Function: `"(checked: boolean, e: ChangeEvent) => void"`+ * Async: `"(e: MouseEvent) => void | Promise<void>"`+ * Generic: `"XDSTableColumn<T>[]"` */+ type: string;+ /** What this prop does, in 1-2 sentences. Focus on behavior and+ * consequences rather than restating the prop name.+ *+ * Good: `"Shows a loading spinner and disables interaction."`+ * Weak: `"Shows a loading spinner."` */+ description: string;+ /** Default value as a string, if the prop is optional and has one.+ * String literals in single quotes: `"'md'"`, `"'balanced'"`.+ * Other values unquoted: `"false"`, `"0"`, `"() => true"`.+ * Omit entirely for required props or optional props with no default. */+ default?: string;+ /** True if the prop must be provided. Omit (don't set to false) if optional. */+ required?: boolean;+}++/**+ * A usage example showing the component in JSX. Examples should progress+ * from basic to advanced. Include 2-5 examples per component (complex+ * components like Table or Layer may justify more).+ *+ * @example+ * ```+ * {label: 'Basic', code: '<XDSButton variant="primary">Save</XDSButton>'}+ * {label: 'With icon', code: '<XDSButton icon={PlusIcon} variant="secondary">Add</XDSButton>'}+ * ```+ */+export interface Example {+ /** Short descriptive title in sentence case, 2-8 words.+ * e.g. `"Basic"`, `"With icon"`, `"Rich cell content with renderCell"`.+ * Omit only for trivial single-example sub-components. */+ label?: string;+ /** JSX code string. Use regular strings for single-line snippets and+ * template literals for multi-line code. Prefer realistic variable names+ * (`users`, `transactions`) over generic ones (`data`, `value1`). */+ code: string;+}++/**+ * A themeable style surface that consumers can override via their theme's+ * `ComponentStyles`. Each component exposes named surfaces (e.g. `root`,+ * `trigger`, `track`) that map to internal styled elements.+ *+ * @example+ * ```+ * {name: 'root', description: 'Outer wrapper element'}+ * {name: 'track', description: 'Slider track background'}+ * ```+ */+export interface ThemingSurface {+ /** Surface key as used in the theme object, always camelCase.+ * e.g. `"root"`, `"track"`, `"filledTrack"`, `"headerRow"`, `"bodyCell"` */+ name: string;+ /** Short noun phrase describing the DOM element or visual region.+ * No trailing period. e.g. `"Outer wrapper element"`,+ * `"Animated circular thumb inside the track"` */+ description: string;+}++/**+ * Documents one component within a multi-component directory. Used when a+ * directory exports multiple public components (e.g. Table exports XDSTable,+ * XDSBaseTable, XDSTableRow, XDSTableCell, XDSTableHeaderCell).+ *+ * Also use for hooks with config objects (e.g. useXDSTableSelection) —+ * treat config options as "props". Order components with the primary/most-used+ * component first.+ */+export interface ComponentEntry {+ /** Full export name including XDS prefix. e.g. `"XDSTableRow"`,+ * `"XDSDialogHeader"`, `"useXDSTableSelection"` */+ name: string;+ /** One-sentence description of what this specific component does.+ * For sub-components, explain the role within the parent composition. */+ description: string;+ /** All public props for this component. */+ props: PropDoc[];+ /** At least one usage example for this component. */+ examples: Example[];+}++/**+ * Shared fields between single-component and multi-component docs.+ * Do not use this interface directly — use `ComponentDoc` (the union type).+ */+interface BaseDoc {+ /** Directory name without the XDS prefix, PascalCase.+ * e.g. `"Button"`, `"Table"`, `"TextInput"`, `"AppShell"` */+ name: string;+ /** One-sentence summary of the component or component group.+ * Be specific enough to differentiate from similar components.+ * e.g. `"Data-driven table with rich cell content via renderCell."` */+ description: string;+ /** Top-level usage examples showing the component in real scenarios.+ * For multi-component dirs, these show how the components work together.+ * Start with the most common usage pattern, then progress to advanced.+ * Include 2-5 examples (complex components may justify more). */+ examples: Example[];+ /** Key capabilities as short bullet points. Each string is one feature.+ * Strongly recommended even though optional — all existing components+ * include this field. Use "Category: details" format.+ * e.g. `"Variants: 'primary', 'secondary', 'ghost', 'destructive'"`,+ * `"Single & range modes: pass a number or [number, number]"` */+ features?: string[];+ /** Theming configuration. Include only if the component supports+ * style overrides via the theme's `ComponentStyles`. */+ theming?: {+ /** The key used in the theme's `components` object.+ * Always lowercase, matches the directory name.+ * e.g. `"button"`, `"switch"`, `"table"` */+ componentKey: string;+ /** All styleable surfaces this component exposes. */+ surfaces: ThemingSurface[];+ };+ /** Accessibility notes — ARIA patterns, screen reader behavior.+ * Each string is one self-contained, declarative note.+ * e.g. `"Uses native <dialog> with showModal() for correct ARIA modal semantics."`,+ * `"Selection plugin sets aria-selected on selected body rows"` */+ accessibility?: string[];+ /** Keyboard interaction summary as a single string. Separate bindings+ * with semicolons or commas. Use key names like `Arrow keys`, `Enter/Space`,+ * `Escape`, `Tab/Shift+Tab`, `Home/End`.+ * e.g. `"Space toggles the switch; Tab/Shift+Tab moves focus in and out"` */+ keyboard?: string;+ /** Additional technical notes — architecture decisions, performance+ * considerations, implementation details, caveats. Each string is one+ * self-contained note. Do not duplicate information from `features`,+ * `accessibility`, or `keyboard`. */+ notes?: string[];+}++/**+ * Documentation for a directory that exports a single primary component.+ * Props live directly on this object.+ *+ * Use this when the directory has one main `XDS*.tsx` file+ * (e.g. Switch, Badge, Spinner, TextInput).+ */+export interface SingleComponentDoc extends BaseDoc {+ /** All public props for the component. */+ props: PropDoc[];+}++/**+ * Documentation for a directory that exports multiple public components.+ * Props live on each entry in `components`.+ *+ * Use this when the directory has multiple `XDS*.tsx` files+ * (e.g. Table, Dialog, TabList, TopNav, Layout).+ */+export interface MultiComponentDoc extends BaseDoc {+ /** Each public component/hook exported from this directory. */+ components: ComponentEntry[];+}++/**+ * The documentation type for a component directory's {Name}.doc.mjs file.+ *+ * Every .doc.mjs must export a single `docs` constant of this type:+ *+ * /\*\* \@type \{import('../docs-types').ComponentDoc\} *\/+ * export const docs = \{ ... \};+ *+ * Use SingleComponentDoc (with `props`) for single-component directories.+ * Use MultiComponentDoc (with `components`) for multi-component directories.+ */+export type ComponentDoc = SingleComponentDoc | MultiComponentDoc;diff --git a/packages/core/src/theme/README.md b/packages/core/src/theme/README.mdindex 46ace94a1d..a3704aa88b 100644--- a/packages/core/src/theme/README.md+++ b/packages/core/src/theme/README.md@@ -83,7 +83,7 @@ const icons: Partial<XDSIconRegistry> = {When no theme is active, components use built-in lightweight SVG fallbacks.-See the [Icon README](../Icon/README.md) for the full list of semantic names.+See the [Icon docs](../Icon/Icon.doc.mjs) for the full list of semantic names.### Adding icons to a custom themediff --git a/packages/core/tsconfig.docs.json b/packages/core/tsconfig.docs.jsonnew file mode 100644index 0000000000..dc9ba6edbc--- /dev/null+++ b/packages/core/tsconfig.docs.json@@ -0,0 +1,10 @@+{+ "extends": "../../tsconfig.json",+ "compilerOptions": {+ "rootDir": "./src",+ "allowJs": true,+ "checkJs": true,+ "noEmit": true+ },+ "include": ["src/**/*.doc.mjs", "src/docs-types.ts"]+}diff --git a/scripts/validate-readmes.mjs b/scripts/validate-readmes.mjsdeleted file mode 100644index af8455c050..0000000000--- a/scripts/validate-readmes.mjs+++ /dev/null@@ -1,205 +0,0 @@-#!/usr/bin/env node--/**- * @file Validate component README structure for CLI brief extractor compatibility.- *- * The XDS CLI's `extractBrief` function parses READMEs to generate LLM-friendly- * docs. It expects a specific structure:- *- * - Multi-component directories: `### XDSComponentName` subsection per component,- * each with a props table and code example.- * - Single-component directories: `## Props` section with a table.- *- * This script scans all packages/core/src/* directories and reports any READMEs- * that don't follow the expected structure.- *- * Usage: node scripts/validate-readmes.mjs- * Exit code: 0 if all pass, 1 if any issues found.- */--import * as fs from 'node:fs';-import * as path from 'node:path';-import {fileURLToPath} from 'node:url';--const __dirname = path.dirname(fileURLToPath(import.meta.url));-const ROOT = path.resolve(__dirname, '..');-const SRC_DIR = path.join(ROOT, 'packages', 'core', 'src');-const SKIP_DIRS = new Set(['hooks', 'utils', 'theme', '__tests__', 'node_modules']);--/**- * Find all XDS*.tsx component files in a directory (non-recursive),- * excluding test files and Context files.- */-function findComponentFiles(dirPath) {- if (!fs.existsSync(dirPath)) return [];- return fs- .readdirSync(dirPath)- .filter(- f =>- /^XDS[A-Z]\w+\.tsx$/.test(f) &&- !f.includes('.test') &&- !f.includes('Context'),- )- .map(f => f.replace(/\.tsx$/, ''));-}--/**- * Extract the content of a ### heading section from markdown lines.- * Returns all lines from the heading until the next ### (or end of file).- */-function extractSection(lines, heading) {- const headingRe = new RegExp(`^###\\s+${escapeRegex(heading)}\\s*$`);- let inSection = false;- const sectionLines = [];-- for (const line of lines) {- if (headingRe.test(line)) {- inSection = true;- continue;- }- if (inSection && /^###\s+/.test(line)) {- break;- }- if (inSection) {- sectionLines.push(line);- }- }-- return inSection ? sectionLines : null;-}--/**- * Check if lines contain a markdown props table.- * Looks for at least one row like `| \`propName\` |`- */-function hasPropsTable(lines) {- return lines.some(line => /^\|\s*`[a-zA-Z]/.test(line));-}--/**- * Check if lines contain a code example with <XDS JSX.- * Looks for ```tsx or ```jsx blocks containing <XDS.- */-function hasCodeExample(lines) {- let inCode = false;- for (const line of lines) {- if (/^```(?:tsx|jsx)/.test(line)) {- inCode = true;- continue;- }- if (inCode && line.startsWith('```')) {- inCode = false;- continue;- }- if (inCode && line.includes('<XDS')) {- return true;- }- }- return false;-}--function escapeRegex(str) {- return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');-}--function validate() {- const issues = [];- const entries = fs.readdirSync(SRC_DIR, {withFileTypes: true});-- for (const entry of entries) {- if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;-- const dirPath = path.join(SRC_DIR, entry.name);- const components = findComponentFiles(dirPath);- if (components.length === 0) continue;-- const readmePath = path.join(dirPath, 'README.md');- const relReadme = path.relative(ROOT, readmePath);-- if (!fs.existsSync(readmePath)) {- issues.push(`${relReadme}: README.md is missing.`);- continue;- }-- const content = fs.readFileSync(readmePath, 'utf-8');- const lines = content.split('\n');- const isMultiComponent = components.length > 1;-- if (isMultiComponent) {- // Multi-component: each component needs ### XDSComponentName- for (const comp of components) {- const section = extractSection(lines, comp);-- if (!section) {- issues.push(- `${relReadme}: Missing section \`### ${comp}\`. ` +- `Each component needs its own ### heading for the CLI brief extractor to work.`,- );- continue;- }-- if (!hasPropsTable(section)) {- issues.push(- `${relReadme}: Section \`### ${comp}\` has no props table. ` +- `Add a markdown table with | Prop | Type | Default | Description | columns.`,- );- }-- if (!hasCodeExample(section)) {- issues.push(- `${relReadme}: Section \`### ${comp}\` has no code example. ` +- `Add a \`\`\`tsx block with <XDS JSX usage.`,- );- }- }- } else {- // Single-component: needs ## Props with a table- const hasPropsSection = /^## Props/m.test(content);-- if (!hasPropsSection) {- issues.push(- `${relReadme}: Missing \`## Props\` section. ` +- `Single-component READMEs need a ## Props heading with a props table.`,- );- } else {- // Extract the ## Props section content- let inProps = false;- const propsLines = [];- for (const line of lines) {- if (/^## Props/.test(line)) {- inProps = true;- continue;- }- if (inProps && /^## /.test(line)) break;- if (inProps) propsLines.push(line);- }-- if (!hasPropsTable(propsLines)) {- issues.push(- `${relReadme}: \`## Props\` section has no props table. ` +- `Add a markdown table with | Prop | Type | Default | Description | columns.`,- );- }- }- }- }-- return issues;-}--// Run validation-const issues = validate();--if (issues.length > 0) {- console.error(`\n❌ Found ${issues.length} README structure issue(s):\n`);- for (const issue of issues) {- console.error(` • ${issue}`);- }- console.error(- `\nSee docs/COMPONENT_README_GUIDE.md for the expected structure.\n`,- );- process.exit(1);-} else {- console.log('\n✅ All component READMEs follow the expected structure.\n');- process.exit(0);-}