@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/src/AlertDialog/__tests__/AlertDialog.a11y.states.ts

@@ -0,0 +1,68 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file AlertDialog.a11y.states.ts
+ * @input AlertDialog's representative modal states and the facts ALERT_DIALOG_PATTERN reads
+ * @output ALERT_DIALOG_BINDING_STATES, the shared labels, and the explicit ownership exclusions for this binding
+ * @position Binding inventory shared by the jsdom test, the Chromium spec, and the story (component:AlertDialog AR1)
+ */
+
+import type {AlertDialogStateFacts} from '@astryxdesign/a11y-spec';
+
+export const ALERT_DIALOG_OPEN_LABEL = 'Delete report';
+export const ALERT_DIALOG_TITLE = 'Delete this report?';
+export const ALERT_DIALOG_MESSAGE =
+  'This permanently deletes the report and its 12 comments.';
+export const ALERT_DIALOG_CANCEL_LABEL = 'Keep report';
+export const ALERT_DIALOG_ACTION_LABEL = 'Delete';
+
+export interface AlertDialogBindingState {
+  readonly id: string;
+  readonly summary: string;
+  readonly storyId: string;
+  readonly facts: AlertDialogStateFacts;
+  readonly isActionLoading?: boolean;
+}
+
+const facts: AlertDialogStateFacts = {
+  modal: true,
+  // Dialog `purpose="form"`: Escape closes, a backdrop click does nothing.
+  dismissesOnEscape: true,
+  dismissesOnBackdrop: false,
+};
+
+const story = (id: string) => `a11y-alertdialog--${id}`;
+
+export const ALERT_DIALOG_BINDING_STATES = [
+  {
+    id: 'modal-confirm',
+    summary:
+      'a modal AlertDialog with a destructive action, opened from a button',
+    storyId: story('modal-confirm'),
+    facts,
+  },
+  {
+    id: 'modal-action-loading',
+    summary:
+      'the same AlertDialog while its action is loading: Cancel stays the first focus and Escape still cancels',
+    storyId: story('modal-action-loading'),
+    facts,
+    isActionLoading: true,
+  },
+] as const satisfies ReadonlyArray<AlertDialogBindingState>;
+
+export const ALERT_DIALOG_EXCLUSIONS = [
+  {
+    id: 'modal-mechanics',
+    owner:
+      'MODAL_DIALOG_PATTERN bound by Dialog (Dialog.a11y.test.tsx and its Chromium spec)',
+    reason:
+      'AlertDialog composes Dialog for the top layer, the inert page behind it, focus entering after modal presentation, and focus returning to the opener on close. Those outcomes are proven once on Dialog; this binding proves only what the alert dialog adds: its role, references, modality claim, initial focus on Cancel, and its dismissal rules.',
+  },
+  {
+    id: 'inline-preview',
+    owner: 'AlertDialog.test.tsx (inline preview suite)',
+    reason:
+      'The `isInline` preview renders the same anatomy as a plain `role="group"` without modality; it is not an alert dialog and makes none of this pattern\'s claims, so it is not a binding state.',
+  },
+] as const;

package/src/AlertDialog/__tests__/AlertDialog.a11y.test.tsx

@@ -0,0 +1,144 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file AlertDialog.a11y.test.tsx
+ * @input ALERT_DIALOG_PATTERN bound to AlertDialog's representative states
+ * @output jsdom-lane proof of the DOM expectation (the description reference) and an honest "unrun" report for the browser layers
+ * @position Binding test for component:AlertDialog AR1 (the Chromium spec covers the rest)
+ */
+
+import {cleanup, fireEvent, render, screen} from '@testing-library/react';
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+import {
+  ALERT_DIALOG_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {renderAlertDialogState} from './AlertDialog.a11y.renders';
+import {
+  ALERT_DIALOG_BINDING_STATES,
+  ALERT_DIALOG_CANCEL_LABEL,
+  ALERT_DIALOG_EXCLUSIONS,
+  ALERT_DIALOG_OPEN_LABEL,
+  type AlertDialogBindingState,
+} from './AlertDialog.a11y.states';
+
+// jsdom has no native dialog methods; the DOM lane only needs the open flag.
+beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+});
+
+function surface(): HTMLElement {
+  const element = document.querySelector('dialog');
+  if (element == null) {
+    throw new Error('no dialog element rendered');
+  }
+  return element;
+}
+
+function related(): Record<string, HTMLElement> {
+  const message = document.getElementById(
+    surface().getAttribute('aria-describedby') ?? '',
+  );
+  const cancel = screen.getByRole('button', {
+    name: ALERT_DIALOG_CANCEL_LABEL,
+    hidden: true,
+  });
+  return {
+    message: message ?? document.body,
+    cancel,
+  };
+}
+
+function openSurface(): void {
+  fireEvent.click(screen.getByRole('button', {name: ALERT_DIALOG_OPEN_LABEL}));
+}
+
+async function checkState(
+  state: AlertDialogBindingState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: ALERT_DIALOG_PATTERN,
+    binding: 'AlertDialog',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      render(renderAlertDialogState(state));
+      openSurface();
+      return createJsdomHarness({subject: surface(), related: related()});
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('AlertDialog — alert dialog pattern, jsdom lane', () => {
+  it.each(
+    ALERT_DIALOG_BINDING_STATES.map(
+      state => [state.id, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: ALERT_DIALOG_PATTERN,
+      binding: 'AlertDialog',
+      state: state.id,
+      facts: state.facts,
+      render: () => {
+        render(renderAlertDialogState(state));
+      },
+      subject: () => surface(),
+      related: () => related(),
+      cleanup,
+    });
+  });
+
+  it('runs the DOM layer and reports the browser-owned outcomes as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of ALERT_DIALOG_BINDING_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(ALERT_DIALOG_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('AlertDialog binding inventory', () => {
+  it('gives every representative state a distinct checked-in story', () => {
+    const stories = ALERT_DIALOG_BINDING_STATES.map(state => state.storyId);
+    expect(new Set(stories).size).toBe(stories.length);
+  });
+
+  it('keeps modal mechanics and the inline preview explicitly owned elsewhere', () => {
+    expect(ALERT_DIALOG_EXCLUSIONS.map(exclusion => exclusion.id)).toEqual([
+      'modal-mechanics',
+      'inline-preview',
+    ]);
+    for (const exclusion of ALERT_DIALOG_EXCLUSIONS) {
+      expect(exclusion.owner.length, exclusion.id).toBeGreaterThan(20);
+      expect(exclusion.reason.length, exclusion.id).toBeGreaterThan(80);
+    }
+  });
+
+  it('renders the opener, the surface, its message and Cancel for every state', () => {
+    for (const state of ALERT_DIALOG_BINDING_STATES) {
+      render(renderAlertDialogState(state));
+      openSurface();
+      expect(surface(), state.id).toBeTruthy();
+      expect(related().message, state.id).not.toBe(document.body);
+      expect(related().cancel, state.id).toBeTruthy();
+      cleanup();
+    }
+  });
+});

package/src/Button/Button.test.tsx

@@ -9,6 +9,7 @@
  * SYNC: When Button.tsx changes, update tests to match new behavior
  */
 
+import {readFileSync} from 'node:fs';
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
@@ -21,6 +22,8 @@ import {
 } from '../__tests__/pressState';
 import {Badge} from '../Badge/Badge';
 import {ButtonGroup} from '../ButtonGroup';
+import {InputGroup} from '../InputGroup';
+import {TextInput} from '../TextInput';
 import {IconButton} from '../IconButton';
 import {InternationalizationProvider} from '../i18n';
 
@@ -39,6 +42,40 @@ describe('Button', () => {
     expect(screen.getByRole('button')).toHaveTextContent('Click me');
   });
 
+  it('uses InputGroup end-cap geometry and keeps its keyboard ring above adjacent members', () => {
+    const {rerender} = render(
+      <InputGroup label="Visibility">
+        <TextInput
+          label="Audience"
+          isLabelHidden
+          value="Members"
+          onChange={() => {}}
+        />
+        <Button label="Save" />
+      </InputGroup>,
+    );
+
+    const addon = screen.getByRole('button', {name: 'Save'});
+    expect(addon.className).toContain('groupStyles.buttonAddon');
+
+    // jsdom cannot resolve this compound StyleX focus selector. Keep the
+    // direct-child keyboard stacking rule explicit at its definition instead.
+    const groupStylesSource = readFileSync(
+      'packages/core/src/InputGroup/groupStyles.ts',
+      'utf8',
+    );
+    expect(groupStylesSource).toContain(
+      "':where(.astryx-input-group > *):focus-visible'",
+    );
+    expect(groupStylesSource).toMatch(
+      /zIndex:\s*\{\s*default: null,\s*\[DIRECT_INPUT_GROUP_ADDON_FOCUS_VISIBLE\]: 2,/,
+    );
+
+    rerender(<Button label="Save" />);
+    const standalone = screen.getByRole('button', {name: 'Save'});
+    expect(standalone.className).not.toContain('groupStyles.buttonAddon');
+  });
+
   it('renders children instead of label when provided', () => {
     render(<Button label="Accessible name">Custom content</Button>);
     const button = screen.getByRole('button');

package/src/Button/Button.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Button.tsx
- * @input Uses React, ButtonHTMLAttributes, ReactNode, i18n (useTranslator)
+ * @input Uses React, ButtonHTMLAttributes, ReactNode, i18n (useTranslator), group contexts
  * @output Exports Button component, ButtonProps, ButtonVariant types
  * @position Core implementation; consumed by index.ts, tested by Button.test.tsx
  *
@@ -44,6 +44,8 @@ import {iconBoxSizeStyles, type IconSize} from '../Icon/IconSize.stylex';
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {useSize} from '../SizeContext/SizeContext';
 import {useButtonGroup} from '../ButtonGroup/ButtonGroupContext';
+import {useInputGroup} from '../InputGroup/InputGroupContext';
+import {groupStyles as inputGroupStyles} from '../InputGroup/groupStyles';
 import {mergeProps} from '../utils';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useLinkComponent} from '../Link/useLinkComponent';
@@ -576,6 +578,7 @@ export function Button({
   const t = useTranslator();
   const size = useSize(sizeProp, 'md');
   const buttonGroup = useButtonGroup();
+  const inputGroup = useInputGroup();
 
   const [isPending, startTransition] = useTransition();
   // clickAction is normally fire-once (submit/save/pay), so a same-tick
@@ -674,6 +677,7 @@ export function Button({
       (buttonGroup.orientation === 'horizontal'
         ? groupStyles.horizontal
         : groupStyles.vertical),
+    inputGroup != null && buttonGroup == null && inputGroupStyles.buttonAddon,
     buttonGroup &&
       (variant === 'primary' || variant === 'destructive') &&
       (buttonGroup.orientation === 'horizontal'

package/src/Calendar/Calendar.doc.mjs

@@ -6,23 +6,85 @@ export const docs = {
   name: 'Calendar',
   displayName: 'Calendar',
   category: 'Form Controls',
-  keywords: ["calendar","datepicker","date picker","rangepicker","date range","monthview","daypicker"],
+  keywords: [
+    'calendar',
+    'datepicker',
+    'date picker',
+    'rangepicker',
+    'date range',
+    'monthview',
+    'daypicker',
+  ],
   usage: {
     description:
       'Calendar lets the user pick a date or date range from a month grid. Use it in booking flows, scheduling UIs, date filters, or anywhere the user needs to see surrounding dates for context.',
     bestPractices: [
-      {guidance: true, description: 'Set min and max dates to limit selection to a valid window, like only future dates for a booking or the current quarter for a report.'},
-      {guidance: true, description: 'Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.'},
-      {guidance: true, description: 'Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.'},
-      {guidance: true, description: 'Show two months side by side when the user frequently selects dates that span a month boundary.'},
-      {guidance: false, description: 'Use a calendar for dates far in the past or future like a birth date. A text input is faster for open-ended entry.'},
-      {guidance: false, description: 'Disable large blocks of dates without context. The user should understand why dates are unavailable.'},
+      {
+        guidance: true,
+        description:
+          'Set min and max dates to limit selection to a valid window, like only future dates for a booking or the current quarter for a report.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.',
+      },
+      {
+        guidance: true,
+        description:
+          'Show two months side by side when the user frequently selects dates that span a month boundary.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use a calendar for dates far in the past or future like a birth date. A text input is faster for open-ended entry.',
+      },
+      {
+        guidance: false,
+        description:
+          'Disable large blocks of dates without context. The user should understand why dates are unavailable.',
+      },
     ],
     anatomy: [
-      {name: 'Month header', required: true, description: 'The month name and year with navigation arrows to move between months. The arrows mirror automatically under dir="rtl".'},
-      {name: 'Day grid', required: true, description: 'A 7-column grid of days with column headers for the day names.'},
-      {name: 'Selected day', required: false, description: 'The currently selected date, highlighted. In range mode, the start and end dates plus the days between them.'},
-      {name: 'Today marker', required: false, description: 'A subtle indicator on the current date for orientation.'},
+      {
+        name: 'Calendar root',
+        required: true,
+        description:
+          'The container that holds the month header and the day grid.',
+      },
+      {
+        name: 'Month header',
+        required: true,
+        description:
+          'The month name and year with navigation arrows to move between months. The arrows mirror automatically under dir="rtl".',
+      },
+      {
+        name: 'Day grid',
+        required: true,
+        description:
+          'A 7-column grid of days with column headers for the day names.',
+      },
+      {
+        name: 'Day button',
+        required: true,
+        description: 'One day in the grid; the control a date is picked with.',
+      },
+      {
+        name: 'Selected day',
+        required: false,
+        description:
+          'The currently selected date, highlighted. In range mode, the start and end dates plus the days between them.',
+      },
+      {
+        name: 'Today marker',
+        required: false,
+        description: 'A subtle indicator on the current date for orientation.',
+      },
     ],
   },
   props: [
@@ -35,7 +97,8 @@ export const docs = {
     {
       name: 'value',
       type: 'ISODateString | DateRange | null',
-      description: 'Controlled selected value. Use null for no selection; omit value or pass undefined for uncontrolled mode.',
+      description:
+        'Controlled selected value. Use null for no selection; omit value or pass undefined for uncontrolled mode.',
     },
     {
       name: 'defaultValue',
@@ -94,7 +157,8 @@ export const docs = {
     {
       name: 'handleRef',
       type: 'React.Ref<CalendarHandle>',
-      description: 'Imperative handle for calendar navigation, including navigateTo().',
+      description:
+        'Imperative handle for calendar navigation, including navigateTo().',
     },
     {
       name: 'hasOutsideDays',
@@ -117,15 +181,23 @@ export const docs = {
     {
       name: 'weekStartsOn',
       type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",
-      description: 'First day of week. Accepts a number (0=Sunday) or a three-letter day name (e.g. "mon").',
+      description:
+        'First day of week. Accepts a number (0=Sunday) or a three-letter day name (e.g. "mon").',
       default: '0',
     },
   ],
   theming: {
     targets: [
       {className: 'astryx-calendar', visualProps: ['mode']},
-      {className: 'astryx-calendar-nav', visualProps: ['nav'], states: ['disabled']},
-      {className: 'astryx-calendar-day', states: ['selected', 'today', 'disabled', 'in-range', 'marker']},
+      {
+        className: 'astryx-calendar-nav',
+        visualProps: ['nav'],
+        states: ['disabled'],
+      },
+      {
+        className: 'astryx-calendar-day',
+        states: ['selected', 'today', 'disabled', 'in-range', 'marker'],
+      },
     ],
   },
 };
@@ -138,59 +210,138 @@ export const docsZh = {
     description:
       'Calendar lets the user pick a date or date range from a month grid. Use it in booking flows, scheduling UIs, date filters, or anywhere the user needs to see surrounding dates for context.',
     bestPractices: [
-      {guidance: true, description: 'Set min and max dates to limit selection to a valid window, like only future dates for a booking or the current quarter for a report.'},
-      {guidance: true, description: 'Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.'},
-      {guidance: true, description: 'Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.'},
-      {guidance: true, description: 'Show two months side by side when the user frequently selects dates that span a month boundary.'},
-      {guidance: false, description: 'Use a calendar for dates far in the past or future like a birth date. A text input is faster for open-ended entry.'},
-      {guidance: false, description: 'Disable large blocks of dates without context. The user should understand why dates are unavailable.'},
+      {
+        guidance: true,
+        description:
+          'Set min and max dates to limit selection to a valid window, like only future dates for a booking or the current quarter for a report.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.',
+      },
+      {
+        guidance: true,
+        description:
+          'Show two months side by side when the user frequently selects dates that span a month boundary.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use a calendar for dates far in the past or future like a birth date. A text input is faster for open-ended entry.',
+      },
+      {
+        guidance: false,
+        description:
+          'Disable large blocks of dates without context. The user should understand why dates are unavailable.',
+      },
     ],
   },
   props: [
-    {name: 'mode', type: "'single' | 'range'", description: '选择模式。', default: "'single'"},
-    {name: 'value', type: 'ISODateString | DateRange | null', description: '受控选中值。null 表示没有选中值；省略或传入 undefined 为非受控模式。'},
-    {name: 'defaultValue', type: 'ISODateString | DateRange', description: '非受控默认值。'},
+    {
+      name: 'mode',
+      type: "'single' | 'range'",
+      description: '选择模式。',
+      default: "'single'",
+    },
+    {
+      name: 'value',
+      type: 'ISODateString | DateRange | null',
+      description:
+        '受控选中值。null 表示没有选中值；省略或传入 undefined 为非受控模式。',
+    },
+    {
+      name: 'defaultValue',
+      type: 'ISODateString | DateRange',
+      description: '非受控默认值。',
+    },
     {name: 'onChange', type: 'Function', description: '选择回调函数。'},
-    {name: 'numberOfMonths', type: '1 | 2', description: '显示的月份数量。', default: '1'},
+    {
+      name: 'numberOfMonths',
+      type: '1 | 2',
+      description: '显示的月份数量。',
+      default: '1',
+    },
     {name: 'min', type: 'ISODateString', description: '可选择的最早日期。'},
     {name: 'max', type: 'ISODateString', description: '可选择的最晚日期。'},
-    {name: 'dateConstraints', type: 'Array<(date: Date) => boolean>', description: '自定义约束函数。'},
-    {name: 'maxRangeSpan', type: 'number', description: '范围模式：范围最多可跨越的天数，含首尾两端（7 = 7 天窗口）。选定起始日后限制窗口大小。'},
-    {name: 'minRangeSpan', type: 'number', description: '范围模式：范围最少需跨越的天数，含首尾两端（2 表示禁止单日范围）。再次点击开始日期时，若最小范围允许则提交单日范围；否则取消进行中的选择。默认为 1。'},
-    {name: 'focusDate', type: 'ISODateString', description: '受控可见月份。未设置时，日历打开时显示已选日期所在月份；若无选中值，则显示今天，并将其限制在 min/max 范围内。'},
-    {name: 'onFocusDateChange', type: '(focusDate: ISODateString) => void', description: '导航回调函数。'},
-    {name: 'handleRef', type: 'React.Ref<CalendarHandle>', description: '日历导航的命令式句柄，包括 navigateTo()。'},
-    {name: 'hasOutsideDays', type: 'boolean', description: '显示相邻月份的日期。', default: 'true'},
-    {name: 'hasWeekNumbers', type: 'boolean', description: '显示 ISO 周数。', default: 'false'},
-    {name: 'hasVariableRowCount', type: 'boolean', description: '可变行数与固定 6 行网格。', default: 'false'},
-    {name: 'weekStartsOn', type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'", description: '每周起始日。可为数字（0=周日）或三字母星期缩写（如 "mon"）。', default: '0'},
+    {
+      name: 'dateConstraints',
+      type: 'Array<(date: Date) => boolean>',
+      description: '自定义约束函数。',
+    },
+    {
+      name: 'maxRangeSpan',
+      type: 'number',
+      description:
+        '范围模式：范围最多可跨越的天数，含首尾两端（7 = 7 天窗口）。选定起始日后限制窗口大小。',
+    },
+    {
+      name: 'minRangeSpan',
+      type: 'number',
+      description:
+        '范围模式：范围最少需跨越的天数，含首尾两端（2 表示禁止单日范围）。再次点击开始日期时，若最小范围允许则提交单日范围；否则取消进行中的选择。默认为 1。',
+    },
+    {
+      name: 'focusDate',
+      type: 'ISODateString',
+      description:
+        '受控可见月份。未设置时，日历打开时显示已选日期所在月份；若无选中值，则显示今天，并将其限制在 min/max 范围内。',
+    },
+    {
+      name: 'onFocusDateChange',
+      type: '(focusDate: ISODateString) => void',
+      description: '导航回调函数。',
+    },
+    {
+      name: 'handleRef',
+      type: 'React.Ref<CalendarHandle>',
+      description: '日历导航的命令式句柄，包括 navigateTo()。',
+    },
+    {
+      name: 'hasOutsideDays',
+      type: 'boolean',
+      description: '显示相邻月份的日期。',
+      default: 'true',
+    },
+    {
+      name: 'hasWeekNumbers',
+      type: 'boolean',
+      description: '显示 ISO 周数。',
+      default: 'false',
+    },
+    {
+      name: 'hasVariableRowCount',
+      type: 'boolean',
+      description: '可变行数与固定 6 行网格。',
+      default: 'false',
+    },
+    {
+      name: 'weekStartsOn',
+      type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",
+      description:
+        '每周起始日。可为数字（0=周日）或三字母星期缩写（如 "mon"）。',
+      default: '0',
+    },
   ],
   theming: {
     targets: [
       {
         className: 'astryx-calendar',
-        visualProps: [
-          'mode',
-        ],
+        visualProps: ['mode'],
       },
       {
         className: 'astryx-calendar-nav',
-        visualProps: [
-          'nav',
-        ],
-        states: [
-          'disabled',
-        ],
+        visualProps: ['nav'],
+        states: ['disabled'],
       },
       {
         className: 'astryx-calendar-day',
-        states: [
-          'selected',
-          'today',
-          'disabled',
-          'in-range',
-          'marker',
-        ],
+        states: ['selected', 'today', 'disabled', 'in-range', 'marker'],
       },
     ],
   },
@@ -203,11 +354,31 @@ export const docsDense = {
     description:
       'Calendar lets the user pick a date or date range from a month grid. Use in booking, scheduling, date filters.',
     bestPractices: [
-      {guidance: true, description: 'Set min/max to limit selection to a valid window: only future dates for booking, current quarter for a report.'},
-      {guidance: true, description: 'Use range mode when user picks start + end dates: trip, time-off request.'},
-      {guidance: true, description: 'Use dateConstraints to disable specific dates (weekends/holidays); explain why unavailable.'},
-      {guidance: true, description: 'Show two months side by side when user frequently selects dates spanning a month boundary.'},
-      {guidance: false, description: 'Use for dates far in the past/future; text input is faster.'},
+      {
+        guidance: true,
+        description:
+          'Set min/max to limit selection to a valid window: only future dates for booking, current quarter for a report.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use range mode when user picks start + end dates: trip, time-off request.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use dateConstraints to disable specific dates (weekends/holidays); explain why unavailable.',
+      },
+      {
+        guidance: true,
+        description:
+          'Show two months side by side when user frequently selects dates spanning a month boundary.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for dates far in the past/future; text input is faster.',
+      },
       {guidance: false, description: 'Disable dates without explaining why.'},
     ],
   },
@@ -220,9 +391,12 @@ export const docsDense = {
     min: 'minimum selectable date',
     max: 'maximum selectable date',
     dateConstraints: 'custom constraint fns',
-    maxRangeSpan: 'range mode: max days a range may span, both ends counted (7 = 7-day window)',
-    minRangeSpan: 'range mode: min days a range must span, both ends counted; repeated start click commits one day when allowed, otherwise cancels (default 1)',
-    focusDate: 'controlled visible month (default: selected date, else today clamped into min/max)',
+    maxRangeSpan:
+      'range mode: max days a range may span, both ends counted (7 = 7-day window)',
+    minRangeSpan:
+      'range mode: min days a range must span, both ends counted; repeated start click commits one day when allowed, otherwise cancels (default 1)',
+    focusDate:
+      'controlled visible month (default: selected date, else today clamped into min/max)',
     onFocusDateChange: 'navigation callback',
     handleRef: 'imperative navigation handle',
     hasOutsideDays: 'show days from adjacent months',