@astryxdesign/core 0.3.0 → 0.4.0

package/src/ComplexSelector/ComplexSelector.tsx

@@ -42,6 +42,8 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
+import {composeEventHandlers} from '../utils/composeEventHandlers';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 
@@ -97,25 +99,28 @@ const styles = stylex.create({
   placeholder: {
     color: colorVars['--color-text-secondary'],
   },
+  // Only what Icon does not already provide: `sm` gives the 16px box and
+  // `color="secondary"` the color, but the glyph still must not shrink inside
+  // the flex trigger.
   triggerIcon: {
     flexShrink: 0,
-    display: 'flex',
-    alignItems: 'center',
-    justifyContent: 'center',
-    width: 16,
-    height: 16,
+  },
+  // Rotation lives on the chevron glyph itself (passed through `xstyle`), not
+  // on the layout wrapper above, so the icon's
+  // `complex-selector-indicator-icon` theme target and the open/closed
+  // transform sit on one element — a theme can restyle the mark and its
+  // rotation through a single selector. The wrapper keeps only layout.
+  triggerIconRotation: {
     transitionProperty: 'transform',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
     transformOrigin: 'center',
-    color: colorVars['--color-icon-secondary'],
   },
   triggerIconOpen: {
     transform: 'rotate(180deg)',
   },
   popover: {
     minWidth: 'anchor-size(width)',
-    marginBlockStart: spacingVars['--spacing-1'],
   },
   content: {
     boxSizing: 'border-box',
@@ -135,12 +140,6 @@ const styles = stylex.create({
   disabled: {
     cursor: 'not-allowed',
   },
-  focusRing: {
-    ':focus-within': {
-      outline: `2px solid ${colorVars['--color-accent']}`,
-      outlineOffset: '2px',
-    },
-  },
 });
 
 export type ComplexSelectorSize = 'sm' | 'md' | 'lg';
@@ -266,6 +265,7 @@ export function ComplexSelector<Value>({
   className,
   style,
   'data-testid': testId,
+  onClick: onClickProp,
   ...props
 }: ComplexSelectorProps<Value>) {
   const t = useTranslator();
@@ -313,7 +313,16 @@ export function ComplexSelector<Value>({
   const triggerContent = triggerLabel ?? placeholder;
 
   const content = (
-    <div id={contentId} {...stylex.props(styles.content, contentXstyle)}>
+    // The theme target sits here, not on the layer: the layer element is a
+    // bare positioning box (useLayer zeroes its borders, padding and
+    // background), so this content box is the surface a theme has to reach to
+    // paint the popup.
+    <div
+      id={contentId}
+      {...mergeProps(
+        themeProps('complex-selector-popup'),
+        stylex.props(styles.content, contentXstyle),
+      )}>
       {children(optimisticValue, commitValue, popover.hide, {
         isOpen: popover.isOpen,
         isBusy,
@@ -329,11 +338,11 @@ export function ComplexSelector<Value>({
         ref={popover.triggerRef}
         data-testid={testId}
         {...props}
-        onClick={() => {
+        onClick={composeEventHandlers(onClickProp, () => {
           if (!isDisabled) {
             popover.toggle();
           }
-        }}
+        })}
         {...mergeProps(
           themeProps('complex-selector', {
             size,
@@ -343,7 +352,11 @@ export function ComplexSelector<Value>({
             inputWrapperStyles.base,
             styles.triggerContainer,
             styles[size],
-            styles.focusRing,
+            // The ring belongs to the wrapper (the focusable `<button>` sits
+            // inside it), but it must still be a KEYBOARD ring: `:focus-within`
+            // matched a mouse click on the trigger and drew the outline for
+            // pointer users too. `focusWithin` here is `:has(:focus-visible)`.
+            focusOutlineStyles.focusWithin,
             isDisabled && inputWrapperStyles.disabled,
             isDisabled && styles.disabled,
             triggerLabel == null && styles.placeholder,
@@ -374,25 +387,29 @@ export function ComplexSelector<Value>({
           <span {...stylex.props(styles.triggerText)}>{triggerContent}</span>
         </button>
         {isBusy && <Spinner size="sm" />}
-        <span
-          {...stylex.props(
+        <Icon
+          icon="chevronDown"
+          size="sm"
+          color="secondary"
+          // No wrapper: Icon's own span already provides the 16px box (`sm`)
+          // and the secondary icon color the wrapper used to set, so the glyph
+          // IS the trigger's icon element — one node carrying the box, the
+          // color, the rotation, and the theme target.
+          xstyle={[
             styles.triggerIcon,
+            styles.triggerIconRotation,
             popover.isOpen && styles.triggerIconOpen,
-          )}>
-          <Icon
-            icon="chevronDown"
-            size="sm"
-            color="inherit"
-            {...themeProps('complex-selector-indicator-icon', {
-              state: popover.isOpen ? 'expanded' : 'collapsed',
-            })}
-          />
-        </span>
+          ]}
+          {...themeProps('complex-selector-indicator-icon', {
+            state: popover.isOpen ? 'expanded' : 'collapsed',
+          })}
+        />
       </div>
 
       {popover.render(content, {
         placement,
         alignment: 'start',
+        offset: spacingVars['--spacing-1'],
         xstyle: [styles.popover, layerAnimations[placement]],
       })}
     </>

package/src/ContextMenu/ContextMenu.doc.mjs

@@ -32,7 +32,7 @@ export const docs = {
     {
       name: 'items',
       type: 'ContextMenuOption[]',
-      description: 'Array of menu entries. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?}`, a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.',
+      description: 'Array of menu entries. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?, variant?}` (variant `"destructive"` renders it in the error color), a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.',
       required: true,
     },
     {

package/src/ContextMenu/ContextMenu.test.tsx

@@ -14,6 +14,7 @@ import userEvent from '@testing-library/user-event';
 import {ContextMenu} from './ContextMenu';
 import {
   ContextMenuItem,
+  ContextMenuDivider,
   ContextMenuCheckboxItem,
   ContextMenuRadioGroup,
   ContextMenuRadioItem,
@@ -348,6 +349,27 @@ describe('ContextMenu items', () => {
   });
 });
 
+describe('ContextMenu destructive variant', () => {
+  it('forwards a destructive item variant to the shared menu item', () => {
+    render(
+      <ContextMenu
+        items={[
+          {label: 'Delete', variant: 'destructive', onClick: () => {}},
+          {label: 'Rename', onClick: () => {}},
+        ]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    expect(
+      screen.getByRole('menuitem', {name: 'Delete', hidden: true}),
+    ).toHaveAttribute('data-variant', 'destructive');
+    expect(
+      screen.getByRole('menuitem', {name: 'Rename', hidden: true}),
+    ).not.toHaveAttribute('data-variant');
+  });
+});
+
 describe('ContextMenu sections', () => {
   it('renders section with title', () => {
     render(
@@ -448,6 +470,25 @@ describe('ContextMenu compound mode', () => {
     expect(screen.getByTestId('shortcut')).toHaveTextContent('⌘X');
   });
 
+  it('renders the menu divider surface through the ContextMenu alias', () => {
+    render(
+      <ContextMenu
+        menuContent={
+          <>
+            <ContextMenuItem label="Cut" onClick={() => {}} />
+            <ContextMenuDivider />
+            <ContextMenuItem label="Delete" onClick={() => {}} />
+          </>
+        }>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    expect(screen.getByRole('separator', {hidden: true})).toHaveClass(
+      'astryx-dropdown-menu-divider',
+    );
+  });
+
   it('calls onClick when compound item is clicked', async () => {
     const user = userEvent.setup();
     const handleClick = vi.fn();

package/src/ContextMenu/ContextMenu.tsx

@@ -71,7 +71,7 @@ import {useTranslator} from '../i18n';
 import type {
   DropdownMenuOption,
   DropdownMenuItemData,
-  DropdownMenuDivider,
+  DropdownMenuDividerData,
   DropdownMenuSection,
 } from '../DropdownMenu/DropdownMenu';
 
@@ -128,7 +128,7 @@ const styles = stylex.create({
 
 export type ContextMenuItemData = DropdownMenuItemData;
 
-export type ContextMenuDivider = DropdownMenuDivider;
+export type ContextMenuDividerData = DropdownMenuDividerData;
 
 export type ContextMenuSection = DropdownMenuSection;
 
@@ -466,9 +466,9 @@ export function ContextMenu({
     <>
       <div
         ref={mergeRefs(ref, triggerRef)}
+        {...triggerProps}
         onContextMenu={handleContextMenu}
         {...longPressHandlers}
-        {...triggerProps}
         data-testid={testId}
         {...stylex.props(
           styles.trigger,

package/src/ContextMenu/index.ts

@@ -11,7 +11,7 @@ export {
   ContextMenu,
   type ContextMenuProps,
   type ContextMenuItemData,
-  type ContextMenuDivider,
+  type ContextMenuDividerData,
   type ContextMenuSection,
   type ContextMenuOption,
 } from './ContextMenu';
@@ -20,6 +20,10 @@ export {
   DropdownMenuItem as ContextMenuItem,
   type DropdownMenuItemProps as ContextMenuItemProps,
 } from '../DropdownMenu/DropdownMenuItem';
+export {
+  DropdownMenuDivider as ContextMenuDivider,
+  type DropdownMenuDividerProps as ContextMenuDividerProps,
+} from '../DropdownMenu/DropdownMenuDivider';
 
 // Selectable items work inside a ContextMenu too — re-exported under the
 // ContextMenu name for a coherent API.

package/src/DateInput/DateInput.doc.mjs

@@ -142,6 +142,13 @@ export const docs = {
         'Number of months displayed simultaneously in the calendar popover.',
       default: '1',
     },
+    {
+      name: 'weekStartsOn',
+      type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",
+      description:
+        'First day of week in the calendar popover. A number (0 = Sunday to 6 = Saturday) or a three-letter day name.',
+      default: '0',
+    },
     {
       name: 'format',
       type: "'date' | 'date_long' | 'date_weekday' | 'system_date' | ((value: ISODateString) => string)",
@@ -164,9 +171,9 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-date-input', visualProps: ['size', 'status']},
+      {className: 'astryx-date-input', visualProps: ['size', 'status'], states: ['disabled']},
       {className: 'astryx-date-input-toggle-icon', states: ['state']},
-      {className: 'astryx-date-input-clear-icon'},
+      {className: 'astryx-date-input-clear-icon', deprecatedFor: 'input-clear-icon'},
     ],
   },
   usage: {
@@ -417,6 +424,12 @@ export const docsZh = {
       description: '日历弹出层中同时显示的月份数量。',
       default: '1',
     },
+    {
+      name: 'weekStartsOn',
+      type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",
+      description: '日历弹出层中每周的起始日。可为数字（0=周日……6=周六）或三字母星期缩写。',
+      default: '0',
+    },
     {
       name: 'format',
       type: "'date' | 'date_long' | 'date_weekday' | 'system_date' | ((value: ISODateString) => string)",
@@ -436,9 +449,10 @@ export const docsZh = {
       {
         className: 'astryx-date-input',
         visualProps: ['size', 'status'],
+        states: ['disabled'],
       },
       {className: 'astryx-date-input-toggle-icon', states: ['state']},
-      {className: 'astryx-date-input-clear-icon'},
+      {className: 'astryx-date-input-clear-icon', deprecatedFor: 'input-clear-icon'},
     ],
   },
 };
@@ -520,6 +534,7 @@ export const docsDense = {
     labelTooltip: 'tooltip text via info icon at label end',
     hasClear: 'Shows clear button when date is set. Clears value on click.',
     numberOfMonths: 'months shown simultaneously in calendar popover',
+    weekStartsOn: 'first day of week in calendar (0=Sunday, or name e.g. "mon")',
     format:
       "committed-value display: 'date_long' (default, March 21, 2026), 'date' (Mar 21, 2026), 'date_weekday' (Wed, Mar 21, 2026), 'system_date' (2026-03-21), or (iso)=>string; reuses Timestamp vocabulary. Committed value only, not while typing.",
     xstyle: 'StyleX styles for layout; must be stylex.create() value',

package/src/DateInput/DateInput.test.tsx

@@ -949,6 +949,61 @@ describe('DateInput', () => {
       expect(screen.getByDisplayValue('Mar 10, 2026')).toBeInTheDocument();
     });
   });
+  describe('weekStartsOn', () => {
+    // The calendar popover renders in the top layer; jsdom keeps the content in
+    // the DOM but role queries skip it, so read the columnheaders directly.
+    const openAndReadWeekdays = (container: HTMLElement): (string | null)[] => {
+      fireEvent.keyDown(screen.getByRole('combobox'), {key: 'ArrowDown'});
+      return Array.from(container.querySelectorAll('[role="columnheader"]'))
+        .slice(0, 7)
+        .map(h => h.textContent);
+    };
+
+    it('defaults to a Sunday-first week', () => {
+      const {container} = render(
+        <DateInput label="Date" onChange={() => {}} />,
+      );
+      expect(openAndReadWeekdays(container)).toEqual([
+        'Su',
+        'Mo',
+        'Tu',
+        'We',
+        'Th',
+        'Fr',
+        'Sa',
+      ]);
+    });
+
+    it('forwards a numeric weekStartsOn to the calendar', () => {
+      const {container} = render(
+        <DateInput label="Date" onChange={() => {}} weekStartsOn={1} />,
+      );
+      expect(openAndReadWeekdays(container)).toEqual([
+        'Mo',
+        'Tu',
+        'We',
+        'Th',
+        'Fr',
+        'Sa',
+        'Su',
+      ]);
+    });
+
+    it('accepts a three-letter day name', () => {
+      const {container} = render(
+        <DateInput label="Date" onChange={() => {}} weekStartsOn="mon" />,
+      );
+      expect(openAndReadWeekdays(container)).toEqual([
+        'Mo',
+        'Tu',
+        'We',
+        'Th',
+        'Fr',
+        'Sa',
+        'Su',
+      ]);
+    });
+  });
 });
 
 describe('DateInput statusVariant forwarding', () => {
@@ -994,7 +1049,7 @@ describe('DateInput clear icon theme target', () => {
     return icon as HTMLElement;
   };
 
-  it('renders the astryx-date-input-clear-icon target on the clear glyph', () => {
+  it('renders the astryx-input-clear-icon target (plus the legacy alias) on the clear glyph', () => {
     render(
       <DateInput
         label="Date"
@@ -1003,11 +1058,13 @@ describe('DateInput clear icon theme target', () => {
         hasClear
       />,
     );
-    // The stable theme target lands on the icon element itself (not the
-    // button), so a theme can restyle just this glyph (color, size, hover)
-    // via `defineTheme` — a button-level target could not reach the icon's
-    // own color/size.
+    // The canonical target lands on the icon element itself (not the button),
+    // so a theme can restyle just this glyph (color, size, hover) via
+    // `defineTheme` — a button-level target could not reach the icon's own
+    // color/size. The original per-component name rides along for a
+    // deprecation window.
     const icon = getClearIcon();
+    expect(icon).toHaveClass('astryx-input-clear-icon');
     expect(icon).toHaveClass('astryx-date-input-clear-icon');
     expect(icon).toHaveClass('astryx-icon');
   });
@@ -1028,11 +1085,13 @@ describe('DateInput clear icon theme target', () => {
     expect(onChange).toHaveBeenCalledWith(undefined);
   });
 
-  it('renders the default icon (secondary color, sm size) byte-identically', () => {
-    // Pixel-identical default guard: the clear glyph must carry the exact same
-    // StyleX color/size classes as a standalone secondary/sm icon. The added
-    // target class is purely additive — it changes nothing until a theme
-    // targets it.
+  it('routes the clear glyph through the shared clear button, keeping the legacy target', () => {
+    // The clear affordance now composes the shared InputClearButton (a ghost
+    // Button with a secondary/sm glyph), so the icon carries the canonical
+    // `astryx-input-clear-icon` target and — for a deprecation window — the
+    // original `astryx-date-input-clear-icon`. Aside from those target classes
+    // it matches the shared button's own `close`/`sm`/`secondary` glyph
+    // exactly, so the default look is defined in one place.
     render(
       <DateInput
         label="Date"
@@ -1042,6 +1101,8 @@ describe('DateInput clear icon theme target', () => {
       />,
     );
     const icon = getClearIcon();
+    expect(icon).toHaveClass('astryx-input-clear-icon');
+    expect(icon).toHaveClass('astryx-date-input-clear-icon');
 
     const {container: refContainer} = render(
       <Icon icon="close" size="sm" color="secondary" />,
@@ -1051,7 +1112,11 @@ describe('DateInput clear icon theme target', () => {
     const styleClasses = (el: HTMLElement) =>
       el.className
         .split(' ')
-        .filter(c => c !== 'astryx-date-input-clear-icon')
+        .filter(
+          c =>
+            c !== 'astryx-input-clear-icon' &&
+            c !== 'astryx-date-input-clear-icon',
+        )
         .sort();
 
     expect(styleClasses(icon)).toEqual(styleClasses(refIcon));
@@ -1177,3 +1242,20 @@ describe('DateInput calendar-toggle icon theme target', () => {
     expect(css).toContain('color: var(--color-icon-primary)');
   });
 });
+
+describe('DateInput disabled theme state', () => {
+  it('reflects disabled on the root target so themes can gate paint on it', () => {
+    const {container} = render(
+      <DateInput label="Date" onChange={() => {}} isDisabled />,
+    );
+    const root = container.querySelector('.astryx-date-input');
+    expect(root).toHaveAttribute('data-disabled', 'disabled');
+    expect(root).toHaveClass('disabled');
+  });
+
+  it('omits data-disabled when enabled, like status does', () => {
+    const {container} = render(<DateInput label="Date" onChange={() => {}} />);
+    const root = container.querySelector('.astryx-date-input');
+    expect(root).not.toHaveAttribute('data-disabled');
+  });
+});

package/src/DateInput/DateInput.tsx

@@ -35,6 +35,7 @@ import {
 } from '../theme/tokens.stylex';
 import {
   Field,
+  InputClearButton,
   type InputStatus,
   inputWrapperStyles,
   inputStatusBorderStyles,
@@ -48,7 +49,13 @@ import {useInputGroup} from '../InputGroup/InputGroupContext';
 import {groupStyles} from '../InputGroup/groupStyles';
 import {useSize} from '../SizeContext/SizeContext';
 import {Spinner} from '../Spinner';
-import {Calendar, type ISODateString, type CalendarHandle} from '../Calendar';
+import {
+  Calendar,
+  type ISODateString,
+  type CalendarHandle,
+  type DayOfWeek,
+  type DayOfWeekName,
+} from '../Calendar';
 import {useCalendarConstraints} from '../Calendar/hooks';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
 import {usePopover} from '../Popover';
@@ -152,10 +159,11 @@ export type {
   InputStatus as DateInputStatus,
   InputStatusType as DateInputStatusType,
 } from '../Field';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps, mergeRefs, isFocusDetached} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
+import {stableClassName} from '../naming';
 import {useTranslator} from '../i18n';
 
 export interface DateInputProps extends Omit<
@@ -311,6 +319,14 @@ export interface DateInputProps extends Omit<
    */
   numberOfMonths?: 1 | 2;
 
+  /**
+   * First day of week in the calendar popover. Accepts a number
+   * (0 = Sunday … 6 = Saturday) or a three-letter day name ('sun'–'sat',
+   * case-insensitive).
+   * @default 0
+   */
+  weekStartsOn?: DayOfWeek | DayOfWeekName;
+
   /**
    * How the committed date value is displayed in the text field. Accepts a
    * named format reused from `Timestamp`'s `format` vocabulary (so the same
@@ -377,6 +393,7 @@ export function DateInput({
   labelTooltip,
   hasClear = false,
   numberOfMonths = 1,
+  weekStartsOn,
   format = 'date_long',
   width,
   xstyle,
@@ -489,7 +506,18 @@ export function DateInput({
   const popover = usePopover({
     dialogLabel: t('@astryx.dateInput.dialogLabel'),
     closeButtonLabel: t('@astryx.dateInput.closeCalendar'),
-    onHide: () => inputRef.current?.focus(),
+    // Return focus to the input when the calendar closes — but only when the
+    // dismiss left focus detached (Escape, or a click on non-focusable empty
+    // space), which the focus trap can't restore on its own. A native
+    // popover="auto" light-dismiss fires synchronously with the pointer event
+    // that moved focus, so if the user clicked another control — the clear
+    // button, another field, anywhere — focus has already landed there;
+    // reclaiming it would fight their click.
+    onHide: () => {
+      if (isFocusDetached()) {
+        inputRef.current?.focus();
+      }
+    },
   });
 
   // Handle toggling the popover from button click (focus calendar)
@@ -635,7 +663,11 @@ export function DateInput({
       }}
       {...rest}
       {...mergeProps(
-        themeProps('date-input', {size, status: status?.type ?? null}),
+        themeProps('date-input', {
+          size,
+          status: status?.type ?? null,
+          disabled: isDisabled ? 'disabled' : null,
+        }),
         stylex.props(
           inputWrapperStyles.base,
           sizeStyles[size],
@@ -725,22 +757,11 @@ export function DateInput({
         {!isInputValid ? 'Invalid date' : ''}
       </VisuallyHidden>
       {hasClear && value !== undefined && !isEffectivelyDisabled && (
-        <button
-          type="button"
+        <InputClearButton
+          label={t('@astryx.dateInput.clear', {label})}
           onClick={handleClear}
-          aria-label={t('@astryx.dateInput.clear', {label})}
-          {...stylex.props(styles.iconButton)}>
-          <Icon
-            icon="close"
-            size="sm"
-            color="secondary"
-            // Stable theme target on the clear glyph itself, so a theme can
-            // restyle just this icon (color, size, hover) via `defineTheme`.
-            // Same-element rules in @layer astryx-theme win over the icon's own
-            // base color/size, which a button-level target could not reach.
-            {...themeProps('date-input-clear-icon')}
-          />
-        </button>
+          iconClassName={stableClassName('date-input-clear-icon')}
+        />
       )}
       {isBusy && <Spinner size="sm" />}
       {statusIcon}
@@ -754,6 +775,7 @@ export function DateInput({
           max={max}
           dateConstraints={dateConstraints}
           numberOfMonths={numberOfMonths}
+          weekStartsOn={weekStartsOn}
         />,
         {placement: 'below', alignment: 'start'},
       )}

package/src/DateRangeInput/DateRangeInput.doc.mjs

@@ -145,6 +145,13 @@ export const docs = {
       description: 'Number of months in the calendar.',
       default: '2',
     },
+    {
+      name: 'weekStartsOn',
+      type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",
+      description:
+        'First day of week in the calendar. A number (0 = Sunday to 6 = Saturday) or a three-letter day name.',
+      default: '0',
+    },
     {
       name: 'width',
       type: 'SizeValue',
@@ -159,9 +166,9 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-date-range-input', visualProps: ['size', 'status']},
+      {className: 'astryx-date-range-input', visualProps: ['size', 'status'], states: ['disabled']},
       {className: 'astryx-date-range-input-toggle-icon', states: ['state']},
-      {className: 'astryx-date-range-input-clear-icon'},
+      {className: 'astryx-date-range-input-clear-icon', deprecatedFor: 'input-clear-icon'},
     ],
   },
   usage: {
@@ -314,6 +321,7 @@ export const docsDense = {
     statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
     labelTooltip: 'tooltip via info icon at label end',
     numberOfMonths: 'months in calendar (default 2)',
+    weekStartsOn: 'first day of week in calendar (0=Sunday, or name e.g. "mon")',
     changeAction:
       'async action fired after onChange; drives optimistic UI updates via useTransition',
     isLoading: 'loading state; disables interaction + shows a spinner',