@astryxdesign/core 0.1.3 → 0.1.4-canary.02643db

package/src/Table/useTableRowExpansion.doc.mjs

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableRowExpansion',
+  subComponentOf: 'Table',
+  displayName: 'useTableRowExpansion',
+  description:
+    'Hook that returns a TablePlugin implementing expandable rows with inherited columns. Child rows use the same columns as their parents, indented by depth. Clicking the chevron (or right-click context menu) toggles expansion. Pair with useTableRowExpansionState, which flattens the tree and derives this config (expand/collapse handlers + expand-all state) from a single expandedKeys set.',
+  props: [
+    {
+      name: 'expandedKeys',
+      type: 'Set<string>',
+      description: 'Set of currently-expanded row keys.',
+      required: true,
+    },
+    {
+      name: 'onToggle',
+      type: '(key: string) => void',
+      description: 'Called when a row expansion is toggled.',
+      required: true,
+    },
+    {
+      name: 'getRowKey',
+      type: '(item: T) => string',
+      description: 'Derive a stable unique key from a row item.',
+      required: true,
+    },
+    {
+      name: 'getChildren',
+      type: '(item: T) => T[]',
+      description: 'Return the children of a row (determines expandability).',
+      required: true,
+    },
+    {
+      name: 'getDepth',
+      type: '(item: T) => number',
+      description: 'Return the depth of a row in the hierarchy (0 = top-level). Used for indentation.',
+    },
+    {
+      name: 'getIsItemExpandable',
+      type: '(item: T) => boolean',
+      description: 'Control which rows are expandable. Defaults to checking getChildren length.',
+    },
+    {
+      name: 'hasRowClickExpansion',
+      type: 'boolean',
+      description: 'When true, clicking anywhere on the row toggles expansion.',
+      default: 'false',
+    },
+    {
+      name: 'isAllExpanded',
+      type: "boolean | 'indeterminate'",
+      description: 'State of the expand-all toggle in the header. Enables the header toggle button.',
+    },
+    {
+      name: 'onToggleExpandAll',
+      type: '(expand: boolean) => void',
+      description: 'Callback when the expand-all header toggle is clicked.',
+    },
+  ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description:
+    'Returns a TablePlugin for expandable rows w/ inherited columns. Child rows reuse parent columns, indented by depth. Chevron click (or right-click menu) toggles expansion. Pair w/ useTableRowExpansionState, which flattens the tree + derives this config from one expandedKeys set.',
+  propDescriptions: {
+    expandedKeys: 'Set of currently-expanded row keys.',
+    onToggle: 'Called when a row expansion is toggled.',
+    getRowKey: 'Derive a stable unique key from a row item.',
+    getChildren: 'Return children of a row; determines expandability.',
+    getDepth: 'Return depth of a row (0 = top-level). Used for indentation.',
+    getIsItemExpandable: 'Control which rows are expandable. Defaults to checking getChildren length.',
+    hasRowClickExpansion: 'If true, clicking anywhere on the row toggles expansion. Default false.',
+    isAllExpanded: 'State of the expand-all header toggle. Enables the header toggle button.',
+    onToggleExpandAll: 'Callback when the expand-all header toggle is clicked.',
+  },
+};

package/src/Table/useTableSortable.doc.mjs

@@ -6,7 +6,10 @@ export const docs = {
   name: 'useTableSortable',
   subComponentOf: 'Table',
   displayName: 'useTableSortable',
-  description: 'Headless multi-sort plugin for Table. The consumer owns sort state and provides a callback. Shift+click enables secondary sort columns. Sort indicators render in header cells automatically.',
+  description: 'Headless multi-sort plugin for Table. Call with a config object: `useTableSortable({ sort, onSortChange })`. Returns a TablePlugin to pass to `<Table plugins={{ sort: sortPlugin }} />`.',
+  usage: {
+    description: 'Call useTableSortable with a config object containing sort state and callback. Pass the returned plugin to Table via the plugins prop.',
+  },
   props: [
     {
       name: 'sort',

package/src/Text/Text.doc.mjs

@@ -16,7 +16,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-heading', visualProps: ['level', 'color']},
-      {className: 'astryx-text', visualProps: ['type', 'color']},
+      {className: 'astryx-text', visualProps: ['type', 'size', 'color']},
     ],
   },
   description: 'Semantic body text component that renders text with type-based styling from the theme, with optional truncation, decoration, and layout props.',
@@ -174,4 +174,4 @@ export const docsDense = {
       { guidance: false, description: 'Text for headings: use Heading with level (1\u20136).' },
     ],
   },
-};
+};

package/src/Text/Text.test.tsx

@@ -114,6 +114,17 @@ describe('Text', () => {
       expect(screen.getByText('Bold text')).toBeInTheDocument();
     });
 
+    it('reflects explicit size overrides for styling and theming', () => {
+      render(
+        <Text type="code" size="2xs">
+          Tiny code
+        </Text>,
+      );
+      const element = screen.getByText('Tiny code');
+      expect(element).toHaveAttribute('data-size', '2xs');
+      expect(element.className).toContain('size-2xs');
+    });
+
     it('accepts display prop', () => {
       render(
         <Text type="body" display="block">

package/src/Text/Text.tsx

@@ -32,6 +32,7 @@ import type {
 import {
   colorStyles,
   defaultWeightByTypeStyles,
+  sizeStyles,
   sizeByTypeStyles,
   weightStyles,
   displayStyles,
@@ -201,7 +202,7 @@ function resolveStyleType(type: TextType): BuiltinTextType {
  */
 export function Text({
   type = 'body',
-  size: _size,
+  size,
   color,
   weight,
   display = 'inline',
@@ -254,10 +255,11 @@ export function Text({
       <Component
         ref={mergeRefs(ref, truncation.ref, textRef)}
         {...mergeProps(
-          themeProps('text', {type, color: resolvedColor}),
+          themeProps('text', {type, size, color: resolvedColor}),
           stylex.props(
             colorStyles[resolvedColor],
             sizeByTypeStyles[styleType],
+            size && sizeStyles[size],
             defaultWeightByTypeStyles[styleType],
             weight && weightStyles[weight],
             // Display: use truncation styles when maxLines > 0

package/src/Text/text.stylex.ts

@@ -14,6 +14,7 @@ import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
   fontWeightVars,
+  textSizeVars,
   typeScaleVars,
   typographyVars,
 } from '../theme/tokens.stylex';
@@ -145,6 +146,46 @@ export const sizeByTypeStyles = stylex.create({
   },
 });
 
+// =============================================================================
+// Explicit Size Override
+// =============================================================================
+
+export const sizeStyles = stylex.create({
+  '4xs': {
+    fontSize: textSizeVars['--font-size-4xs'],
+  },
+  '3xs': {
+    fontSize: textSizeVars['--font-size-3xs'],
+  },
+  '2xs': {
+    fontSize: textSizeVars['--font-size-2xs'],
+  },
+  xsm: {
+    fontSize: textSizeVars['--font-size-xs'],
+  },
+  sm: {
+    fontSize: textSizeVars['--font-size-sm'],
+  },
+  base: {
+    fontSize: textSizeVars['--font-size-base'],
+  },
+  lg: {
+    fontSize: textSizeVars['--font-size-lg'],
+  },
+  xl: {
+    fontSize: textSizeVars['--font-size-xl'],
+  },
+  '2xl': {
+    fontSize: textSizeVars['--font-size-2xl'],
+  },
+  '3xl': {
+    fontSize: textSizeVars['--font-size-3xl'],
+  },
+  '4xl': {
+    fontSize: textSizeVars['--font-size-4xl'],
+  },
+});
+
 // =============================================================================
 // Baseline Size/Leading by Heading Level (from type-scale tokens)
 //

package/src/TextArea/TextArea.doc.mjs

@@ -74,7 +74,7 @@ export const docs = {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the textarea is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the textarea focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextArea in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the textarea is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the textarea focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextArea in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'isLoading',

package/src/TextInput/TextInput.doc.mjs

@@ -82,7 +82,7 @@ export const docs = {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextInput in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'isLoading',

package/src/TimeInput/TimeInput.doc.mjs

@@ -26,7 +26,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Choose the hour format (12h or 24h) that matches your audience\'s locale; 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.',
+          'Choose the hour format (12h or 24h) that matches your audience\'s locale: 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.',
       },
       {
         guidance: true,
@@ -41,7 +41,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Use the status prop to surface validation errors inline; show a message like "Time must be during business hours" so users know exactly what to fix.',
+          'Use the status prop to surface validation errors inline: show a message like "Time must be during business hours" so users know exactly what to fix.',
       },
       {
         guidance: true,
@@ -146,7 +146,7 @@ export const docs = {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled TimeInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled TimeInput in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'value',
@@ -396,7 +396,7 @@ export const docsZh = {
       {
         guidance: true,
         description:
-          'Choose the hour format (12h or 24h) that matches your audience\'s locale; 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.',
+          'Choose the hour format (12h or 24h) that matches your audience\'s locale: 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.',
       },
       {
         guidance: true,
@@ -411,7 +411,7 @@ export const docsZh = {
       {
         guidance: true,
         description:
-          'Use the status prop to surface validation errors inline; show a message like "Time must be during business hours" so users know exactly what to fix.',
+          'Use the status prop to surface validation errors inline: show a message like "Time must be during business hours" so users know exactly what to fix.',
       },
       {
         guidance: true,
@@ -480,7 +480,7 @@ export const docsDense = {
       {
         guidance: true,
         description:
-          'Choose hour format (12h/24h) to match locale; 12h for US, 24h for international.',
+          'Choose hour format (12h/24h) to match locale: 12h for US, 24h for international.',
       },
       {
         guidance: true,
@@ -497,6 +497,11 @@ export const docsDense = {
         description: 'Use status prop for inline validation errors.',
       },
       {guidance: true, description: 'Enable hasClear for optional fields.'},
+      {
+        guidance: true,
+        description:
+          'Place inside InputGroup for a single-line prefix or suffix addon, like a label or timezone marker.',
+      },
       {
         guidance: false,
         description:

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -70,11 +70,17 @@ export const docs = {
       description: 'Disables the input and all token interactions.',
       default: 'false',
     },
+    {
+      name: 'htmlName',
+      type: 'string',
+      description:
+        'The HTML name attribute for form submissions. Renders one hidden input per selected item id.',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the tokenizer is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled Tokenizer in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the tokenizer is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled Tokenizer in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'status',
@@ -277,11 +283,16 @@ export const docsZh = {
       description: '\u7981\u7528\u8f93\u5165\u6846\u548c\u6240\u6709\u6807\u8bb0\u4ea4\u4e92\u3002',
       default: 'false',
     },
+    {
+      name: 'htmlName',
+      type: 'string',
+      description: '用于表单提交的 HTML name 属性。为每个已选项目的 id 渲染一个隐藏输入。',
+    },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the tokenizer is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled Tokenizer in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the tokenizer is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled Tokenizer in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'status',
@@ -435,6 +446,7 @@ export const docsDense = {
     renderToken: 'Custom token render. Default renders Token w/ label+onRemove.',
     renderItem: 'Custom dropdown item render. Default renders TypeaheadItem.',
     isDisabled: 'Disables input+all token interactions.',
+    htmlName: 'HTML name attr; one hidden input per selected item id.',
     status: 'Validation status w/ type+message for error/warning/success.',
     isLabelHidden: 'Visually hides label; keeps a11y.',
     description: 'Helper text below label.',

package/src/Tokenizer/Tokenizer.test.tsx

@@ -867,4 +867,37 @@ describe('Tokenizer', () => {
       expect(screen.getByRole('combobox')).toBeDisabled();
     });
   });
+  describe('form participation', () => {
+    it('submits one entry per token id under htmlName', () => {
+      const {container} = render(
+        <form>
+          <Tokenizer
+            label="Users"
+            htmlName="users"
+            searchSource={userSource}
+            value={[users[0], users[1]]}
+            onChange={() => {}}
+          />
+        </form>,
+      );
+      const data = new FormData(container.querySelector('form')!);
+      expect(data.getAll('users')).toEqual([users[0].id, users[1].id]);
+    });
+
+    it('is excluded from form data when disabled', () => {
+      const {container} = render(
+        <form>
+          <Tokenizer
+            label="Users"
+            htmlName="users"
+            searchSource={userSource}
+            value={[users[0]]}
+            onChange={() => {}}
+            isDisabled
+          />
+        </form>,
+      );
+      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+    });
+  });
 });

package/src/Tokenizer/Tokenizer.tsx

@@ -128,6 +128,12 @@ export interface TokenizerProps<T extends SearchableItem> extends Omit<
   searchSource: SearchSource<T>;
   /** Currently selected items. */
   value: T[];
+
+  /**
+   * The HTML name attribute for form submissions. When set, hidden inputs
+   * carry one entry per selected item's id under this name.
+   */
+  htmlName?: string;
   /** Callback when selection changes. Includes change metadata. */
   onChange: (items: T[], change: TokenizerChange<T>) => void;
   /** Render function for dropdown items. Default: TypeaheadItem. */
@@ -377,6 +383,7 @@ export function Tokenizer<T extends SearchableItem>({
   maxMenuItems,
   emptySearchResultsText,
   isDisabled = false,
+  htmlName,
   disabledMessage,
   hasClear = false,
   endContent,
@@ -760,6 +767,18 @@ export function Tokenizer<T extends SearchableItem>({
               : undefined
         }
       />
+      {htmlName != null &&
+        value.map(item => (
+          <input
+            key={item.id}
+            type="hidden"
+            name={htmlName}
+            value={item.id}
+            // Disabled native controls are excluded from form submission;
+            // mirror that for the hidden carriers.
+            disabled={isDisabled}
+          />
+        ))}
       {(endContent || (hasClear && value.length > 0 && !isDisabled)) && (
         <div {...stylex.props(styles.endSection, endSectionSizeStyles[size])}>
           {endContent}

package/src/Toolbar/Toolbar.test.tsx

@@ -168,7 +168,7 @@ describe('Toolbar', () => {
 
   it('passes variant to Section', () => {
     const {container} = render(<Toolbar label="Actions" variant="muted" />);
-    // Section renders with xds-section class containing the variant
+    // Section renders with astryx-section class containing the variant
     const sectionInner = container.querySelector('.astryx-section');
     expect(sectionInner).toBeInTheDocument();
     expect(sectionInner?.className).toContain('muted');

package/src/Typeahead/BaseTypeahead.doc.mjs

@@ -8,6 +8,16 @@ export const docs = {
   displayName: 'Base Typeahead',
   isHiddenFromOverview: true,
   description: 'Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by Typeahead and Tokenizer for custom compositions.',
+  usage: {
+    description: 'Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by Typeahead and Tokenizer for custom compositions.',
+    bestPractices: [
+      { guidance: true, description: 'Use Typeahead or Tokenizer for standard fields — they wrap BaseTypeahead with the wrapper div, border styling, and token rendering it intentionally omits.' },
+      { guidance: true, description: 'Provide your own wrapper div with border and layout when composing directly — BaseTypeahead renders no visual chrome of its own.' },
+      { guidance: true, description: 'Pass anchorRef pointing to your wrapper so the dropdown positions against your custom input chrome, not just the bare input element.' },
+      { guidance: false, description: 'Expect a wrapper div, border, or token rendering — BaseTypeahead is an engine only; all visual chrome is the caller\'s responsibility.' },
+      { guidance: false, description: 'Use BaseTypeahead when Typeahead or Tokenizer would suffice — the extra wrapper and styling work is only justified for truly custom compositions.' },
+    ],
+  },
   props: [
     {
       name: 'searchSource',

package/src/Typeahead/Typeahead.doc.mjs

@@ -75,7 +75,7 @@ export const docs = {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled Typeahead in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled Typeahead in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
     },
     {
       name: 'maxMenuItems',
@@ -287,6 +287,11 @@ export const docsDense = {
         description:
           'Add a search delay for remote data sources to avoid excessive network requests.',
       },
+      {
+        guidance: true,
+        description:
+          'Use inside InputGroup when the typeahead needs a single-line prefix or suffix addon.',
+      },
       {
         guidance: false,
         description:

package/src/docs-types.ts

@@ -217,6 +217,11 @@ export interface ComponentEntry {
   examples?: ExampleDoc[];
   /** When true, this sub-component is excluded from the overview page. */
   isHiddenFromOverview?: boolean;
+  /** Playground configuration for this specific component. Falls back to
+   *  the directory doc's `playground` when omitted — declare one here when
+   *  siblings must not share it (e.g. an overlay drawer whose toggle
+   *  sub-component should not inherit `overlay: true`). */
+  playground?: PlaygroundConfig;
 }
 
 /**
@@ -390,6 +395,13 @@ export interface PlaygroundConfig {
   /** Initial prop values for the playground preview.
    *  Keys are prop names. Values are primitives or ElementDescriptors. */
   defaults?: Record<string, unknown>;
+  /** The component opens as a full-viewport overlay (e.g. via
+   *  `dialog.showModal()`) and renders nothing inline while closed. The
+   *  interactive preview shows an open-trigger placeholder instead of an
+   *  empty stage while `isOpen` is false, and lets the real overlay render
+   *  when opened. Include `isOpen: false` in `defaults` so the preview can
+   *  bridge `onOpenChange` back into playground state. */
+  overlay?: boolean;
   /** Required parent wrapper for sub-components that depend on a parent
    *  context provider (e.g. `Tab` calls `useTabListContext()` and throws
    *  standalone). The preview wraps the component in this parent before

package/src/hooks/useKeyboardHint.doc.mjs

@@ -38,7 +38,7 @@ export const docs = {
     {
       name: 'hintElement',
       type: 'ReactNode',
-      description: 'The popover hint element to render inside the composite container (as the last child). Portals to the top layer via popover="manual", renders arrow keys with Kbd, and manages its own visibility — render it unconditionally.',
+      description: 'The popover hint element to render inside the composite container (as the last child). Portals to the top layer via popover="manual", renders arrow keys with Kbd, and manages its own visibility; render it unconditionally.',
     },
     {
       name: 'onFocus',
@@ -58,12 +58,12 @@ export const docs = {
   ],
   usage: {
     description:
-      'Shows an ephemeral "← → to navigate" hint anchored to the focused item the first time a roving-tabindex composite (Toolbar, TabList, SegmentedControl, etc.) receives keyboard focus. It teaches sighted keyboard users that arrow keys move within the group. The hint renders arrow keys with Kbd in the top layer (popover="manual") and is CSS-anchor-positioned to the focused element, so overflow containers never clip it. It auto-dismisses on the first arrow press, on timeout, or on blur, and does not re-show for that instance. Toolbar, TabList, and SegmentedControl wire this in automatically — reach for the hook directly only when building a custom roving-tabindex widget.',
+      'Shows an ephemeral "← → to navigate" hint anchored to the focused item the first time a roving-tabindex composite (Toolbar, TabList, SegmentedControl, etc.) receives keyboard focus. It teaches sighted keyboard users that arrow keys move within the group. The hint renders arrow keys with Kbd in the top layer (popover="manual") and is CSS-anchor-positioned to the focused element, so overflow containers never clip it. It auto-dismisses on the first arrow press, on timeout, or on blur, and does not re-show for that instance. Toolbar, TabList, and SegmentedControl wire this in automatically; reach for the hook directly only when building a custom roving-tabindex widget.',
     bestPractices: [
-      { guidance: true, description: 'Compose the returned onFocus/onKeyDown with your existing focus handlers rather than replacing them — call onKeyDown first (it only dismisses, never prevents), then your navigation handler.' },
+      { guidance: true, description: 'Compose the returned onFocus/onKeyDown with your existing focus handlers rather than replacing them: call onKeyDown first (it only dismisses, never prevents), then your navigation handler.' },
       { guidance: true, description: 'Render hintElement as the last child of the composite container; it is position:fixed in the top layer and aria-hidden, so it never affects layout or the accessibility tree.' },
       { guidance: true, description: 'Match orientation to the arrow keys your widget actually responds to so the hint shows the correct icons.' },
-      { guidance: false, description: 'Use for single controls or widgets without roving-tabindex navigation — the hint only makes sense where arrows move focus within a group.' },
+      { guidance: false, description: 'Use for single controls or widgets without roving-tabindex navigation; the hint only makes sense where arrows move focus within a group.' },
     ],
   },
   relatedComponents: ['Toolbar', 'TabList', 'SegmentedControl'],
@@ -83,7 +83,7 @@ export const docsDense = {
     'options.isEnabled': 'whether the hint is enabled; false suppresses it (e.g. disabled/read-only widget).',
   },
   returnDescriptions: {
-    hintElement: 'popover hint to render as last child of the container. Kbd-rendered arrows, top-layer, self-managing — render unconditionally.',
+    hintElement: 'popover hint to render as last child of the container. Kbd-rendered arrows, top-layer, self-managing; render unconditionally.',
     onFocus: 'container onFocus: shows hint on first :focus-visible entry from outside.',
     onBlur: 'container onBlur: hides on leaving the composite; re-anchors on internal moves.',
     onKeyDown: 'container onKeyDown: dismisses on first arrow press. Never prevents default.',
@@ -92,7 +92,7 @@ export const docsDense = {
     description:
       'Ephemeral "← → to navigate" hint on first keyboard focus of a roving-tabindex composite. Top-layer anchored popover, aria-hidden. Auto-dismisses on first arrow press, timeout, or blur; no re-show. Toolbar/TabList/SegmentedControl wire it in automatically.',
     bestPractices: [
-      { guidance: true, description: 'Compose returned onFocus/onKeyDown with existing handlers (call onKeyDown first — it only dismisses).' },
+      { guidance: true, description: 'Compose returned onFocus/onKeyDown with existing handlers (call onKeyDown first; it only dismisses).' },
       { guidance: true, description: 'Render hintElement as last child; top-layer + aria-hidden, no layout/a11y impact.' },
       { guidance: true, description: 'Match orientation to the arrows the widget responds to.' },
       { guidance: false, description: 'Use for single controls / non-roving widgets.' },