@astryxdesign/core 0.1.1 → 0.1.2-canary.2581eb4

package/src/Calendar/Calendar.doc.mjs

@@ -103,8 +103,8 @@ export const docs = {
     },
     {
       name: 'weekStartsOn',
-      type: '0 | 1 | 2 | 3 | 4 | 5 | 6',
-      description: 'First day of week (0=Sunday).',
+      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").',
       default: '0',
     },
   ],
@@ -147,7 +147,7 @@ export const docsZh = {
     {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', description: '每周起始日（0=周日）。', default: '0'},
+    {name: 'weekStartsOn', type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun'…'sat'", description: '每周起始日。可为数字（0=周日）或三字母星期缩写（如 "mon"）。', default: '0'},
   ],
   theming: {
     targets: [
@@ -200,6 +200,6 @@ export const docsDense = {
     hasOutsideDays: 'show days from adjacent months',
     hasWeekNumbers: 'show ISO week numbers',
     hasVariableRowCount: 'variable vs fixed 6-row grid',
-    weekStartsOn: 'first day of week (0=Sunday)',
+    weekStartsOn: 'first day of week (0=Sunday, or name e.g. "mon")',
   },
 };

package/src/Calendar/Calendar.test.tsx

@@ -146,10 +146,7 @@ describe('Calendar', () => {
     const handleFocusChange = vi.fn();
 
     render(
-      <Calendar
-        focusDate="2026-01-01"
-        onFocusDateChange={handleFocusChange}
-      />,
+      <Calendar focusDate="2026-01-01" onFocusDateChange={handleFocusChange} />,
     );
 
     const nextButton = screen.getByRole('button', {name: 'Next month'});
@@ -189,9 +186,7 @@ describe('Calendar', () => {
       return day !== 0 && day !== 6;
     };
 
-    render(
-      <Calendar focusDate="2026-01-01" dateConstraints={[isWeekday]} />,
-    );
+    render(<Calendar focusDate="2026-01-01" dateConstraints={[isWeekday]} />);
 
     // January 4, 2026 is a Sunday - should be disabled
     const sunday = getDayButton(4);
@@ -238,6 +233,21 @@ describe('Calendar', () => {
     expect(dayNames[0]).toHaveTextContent('Mo');
   });
 
+  it('accepts a three-letter day name for weekStartsOn', () => {
+    render(<Calendar weekStartsOn="mon" />);
+
+    // "mon" should behave exactly like the numeric 1 (Monday first).
+    const dayNames = screen.getAllByText(/^(Mo|Tu|We|Th|Fr|Sa|Su)$/);
+    expect(dayNames[0]).toHaveTextContent('Mo');
+  });
+
+  it('treats weekStartsOn day names case-insensitively', () => {
+    render(<Calendar weekStartsOn={'WED' as 'wed'} />);
+
+    const dayNames = screen.getAllByText(/^(Mo|Tu|We|Th|Fr|Sa|Su)$/);
+    expect(dayNames[0]).toHaveTextContent('We');
+  });
+
   // ─── Range Mode ──────────────────────────────────────────────
 
   it('supports range selection mode', async () => {
@@ -245,11 +255,7 @@ describe('Calendar', () => {
     const handleChange = vi.fn();
 
     render(
-      <Calendar
-        mode="range"
-        onChange={handleChange}
-        focusDate="2026-01-01"
-      />,
+      <Calendar mode="range" onChange={handleChange} focusDate="2026-01-01" />,
     );
 
     // Click start date
@@ -271,11 +277,7 @@ describe('Calendar', () => {
     const handleChange = vi.fn();
 
     render(
-      <Calendar
-        mode="range"
-        onChange={handleChange}
-        focusDate="2026-01-01"
-      />,
+      <Calendar mode="range" onChange={handleChange} focusDate="2026-01-01" />,
     );
 
     // Click later date first
@@ -346,10 +348,7 @@ describe('Calendar', () => {
     const handleFocusChange = vi.fn();
 
     render(
-      <Calendar
-        focusDate="2026-01-01"
-        onFocusDateChange={handleFocusChange}
-      />,
+      <Calendar focusDate="2026-01-01" onFocusDateChange={handleFocusChange} />,
     );
 
     // Focus Jan 28
@@ -414,11 +413,7 @@ describe('Calendar', () => {
     const handleChange = vi.fn();
 
     render(
-      <Calendar
-        mode="range"
-        onChange={handleChange}
-        focusDate="2026-01-01"
-      />,
+      <Calendar mode="range" onChange={handleChange} focusDate="2026-01-01" />,
     );
 
     // Click start date to begin range selection

package/src/Calendar/Calendar.tsx

@@ -70,8 +70,19 @@ import {
 // Types
 // =============================================================================
 
-export type {ISODateString, DayOfWeek, DateRange} from '../utils/dateTypes';
-import type {ISODateString, DayOfWeek, DateRange} from '../utils/dateTypes';
+export type {
+  ISODateString,
+  DayOfWeek,
+  DayOfWeekName,
+  DateRange,
+} from '../utils/dateTypes';
+import type {
+  ISODateString,
+  DayOfWeek,
+  DayOfWeekName,
+  DateRange,
+} from '../utils/dateTypes';
+import {normalizeDayOfWeek} from '../utils/dateTypes';
 import {themeProps} from '../utils/themeProps';
 
 /** Imperative handle for Calendar handleRef */
@@ -134,10 +145,11 @@ interface CalendarBaseProps extends Omit<
   hasVariableRowCount?: boolean;
 
   /**
-   * First day of week.
+   * First day of week. Accepts a number (0 = Sunday … 6 = Saturday) or a
+   * three-letter day name ('sun'–'sat', case-insensitive) for readability.
    * Default: 0 (Sunday)
    */
-  weekStartsOn?: DayOfWeek;
+  weekStartsOn?: DayOfWeek | DayOfWeekName;
 }
 
 // ─── Mode-specific Props (discriminated union) ────────────────
@@ -200,13 +212,17 @@ export function Calendar({ref, ...props}: CalendarProps) {
     hasOutsideDays = true,
     hasWeekNumbers = false,
     hasVariableRowCount = false,
-    weekStartsOn = 0,
+    weekStartsOn: weekStartsOnProp = 0,
     xstyle,
     className,
     style,
     ...rest
   } = props;
 
+  // Normalize `weekStartsOn` (number or three-letter day name) to a numeric
+  // DayOfWeek so all downstream date math keeps working with an index.
+  const weekStartsOn = normalizeDayOfWeek(weekStartsOnProp);
+
   // Today's date (memoized)
   const today = useMemo(() => plainDateToday(), []);
 

package/src/Calendar/index.ts

@@ -17,6 +17,7 @@ export type {
   CalendarHandle,
   ISODateString,
   DayOfWeek,
+  DayOfWeekName,
   DateRange,
 } from './Calendar';
 

package/src/Chat/ChatComposer.doc.mjs

@@ -7,6 +7,9 @@ export const docs = {
   subComponentOf: 'Chat',
   displayName: 'Chat Composer',
   description: 'Layout shell for a chat composer. Arranges named slots (drawer, header, input, footer, send) with page-radius container, hover/focus shadows, and concentric inner radius for child elements.',
+  playground: {
+    wrapper: {component: 'Stack', props: {width: 480}},
+  },
   props: [
     {
       name: 'onSubmit',

package/src/Chat/ChatComposerDrawer.doc.mjs

@@ -8,6 +8,18 @@ export const docs = {
   displayName: 'Chat Composer Drawer',
   isHiddenFromOverview: true,
   description: "Collapsible drawer panel that sits above the chat input inside ChatComposer. Pass it to the composer's `drawer` slot to show attachments, context chips, or any supplementary content. When `count` is provided the drawer gains a collapse toggle: collapsed state shows a badge and label, expanded state shows all children.",
+  playground: {
+    wrapper: {component: 'Stack', props: {width: 480}},
+    defaults: {
+      count: 3,
+      label: 'Attachments',
+      children: [
+        {__element: 'Token', props: {label: 'design-spec.pdf'}},
+        {__element: 'Token', props: {label: 'api-schema.json'}},
+        {__element: 'Token', props: {label: 'screenshot.png'}},
+      ],
+    },
+  },
   props: [
     {
       name: 'children',

package/src/CheckboxInput/CheckboxInput.doc.mjs

@@ -63,6 +63,13 @@ export const docs = {
       description: 'Whether the checkbox is disabled.',
       default: 'false',
     },
+    {
+      name: 'isReadOnly',
+      type: 'boolean',
+      description:
+        'Whether the checkbox is read-only. Displays the current state at full opacity but prevents interaction. Unlike `isDisabled`, read-only checkboxes are not visually dimmed.',
+      default: 'false',
+    },
     {
       name: 'isOptional',
       type: 'boolean',
@@ -156,6 +163,7 @@ export const docsZh = {
     },
     {name: 'isLoading', type: 'boolean', description: '复选框是否处于加载状态。显示旋转器并阻止交互。', default: 'false'},
     {name: 'isDisabled', type: 'boolean', description: '复选框是否禁用。', default: 'false'},
+    {name: 'isReadOnly', type: 'boolean', description: '复选框是否为只读。以完整不透明度显示当前状态但阻止交互。与 isDisabled 不同，只读复选框不会变暗。', default: 'false'},
     {name: 'isOptional', type: 'boolean', description: '字段是否可选。与 isRequired 互斥。', default: 'false'},
     {name: 'isRequired', type: 'boolean', description: '复选框是否必填。与 isOptional 互斥。', default: 'false'},
     {name: 'size', type: "'sm' | 'md'", description: '复选框尺寸。sm 用于紧凑布局，md 为默认。', default: "'md'"},

package/src/ClickableCard/ClickableCard.doc.mjs

@@ -37,6 +37,21 @@ export const docs = {
     container: true,
     targets: [{className: 'astryx-clickable-card', visualProps: ['variant']}],
   },
+  playground: {
+    defaults: {
+      label: 'View product details',
+      href: '#',
+      padding: 4,
+      children: {
+        __element: 'XDSVStack',
+        props: {gap: 1},
+        children: [
+          {__element: 'XDSHeading', props: {level: 3}, children: 'Wireless Headphones'},
+          {__element: 'XDSText', props: {type: 'body'}, children: 'Noise-cancelling over-ear headphones with 30-hour battery life.'},
+        ],
+      },
+    },
+  },
 };
 
 /** @type {import('../docs-types').TranslationDoc} */

package/src/DateTimeInput/DateTimeInput.doc.mjs

@@ -108,9 +108,15 @@ export const docs = {
     {
       name: 'placeholder',
       type: 'string',
-      description: 'Placeholder text shown when no datetime is selected.',
+      description: 'Placeholder text shown in the date portion when no date is selected.',
       default: "'Select a date'",
     },
+    {
+      name: 'timePlaceholder',
+      type: 'string',
+      description: 'Placeholder text shown in the time portion when no time is selected.',
+      default: "'Select a time'",
+    },
     {
       name: 'size',
       type: "'sm' | 'md' | 'lg'",
@@ -202,7 +208,8 @@ export const docsZh = {
     {name: 'hourFormat', type: "'12h' | '24h'", description: "控制显示格式。'12h' 显示 AM/PM；'24h' 使用 24 小时制。", default: "'12h'"},
     {name: 'timeIncrement', type: 'number', description: '在时间输入中按箭头键时增减的分钟数。', default: '1'},
     {name: 'hasClear', type: 'boolean', description: '当有值时显示清除按钮。', default: 'false'},
-    {name: 'placeholder', type: 'string', description: '未选择日期时显示的占位符文本。', default: "'Select a date'"},
+    {name: 'placeholder', type: 'string', description: '日期部分未选择日期时显示的占位符文本。', default: "'Select a date'"},
+    {name: 'timePlaceholder', type: 'string', description: '时间部分未选择时间时显示的占位符文本。', default: "'Select a time'"},
     {name: 'size', type: "'sm' | 'md' | 'lg'", description: '输入控件的尺寸。', default: "'md'"},
     {name: 'status', type: 'InputStatus', description: '错误、警告或成功状态的状态指示对象，附带消息。'},
     {name: 'labelTooltip', type: 'string', description: '通过标签末尾的信息图标显示的提示文本。'},
@@ -249,7 +256,8 @@ export const docsDense = {
     hourFormat: "display format. '12h' shows AM/PM; '24h' uses 24-hour",
     timeIncrement: 'minutes to add/subtract on arrow keys in time input',
     hasClear: 'Shows clear button when datetime is set',
-    placeholder: 'placeholder text when empty',
+    placeholder: 'date-portion placeholder when empty',
+    timePlaceholder: 'time-portion placeholder when empty',
     size: 'input control size',
     status: 'error/warning/success status w/ message',
     labelTooltip: 'tooltip text via info icon at label end',

package/src/DateTimeInput/DateTimeInput.test.tsx

@@ -31,6 +31,28 @@ describe('DateTimeInput', () => {
     expect(screen.getByPlaceholderText('Pick a date')).toBeInTheDocument();
   });
 
+  it('defaults the time portion placeholder to "Select a time"', () => {
+    render(<DateTimeInput label="Meeting" onChange={() => {}} />);
+    expect(screen.getByPlaceholderText('Select a time')).toBeInTheDocument();
+  });
+
+  it('applies a custom timePlaceholder to the time portion', () => {
+    render(
+      <DateTimeInput
+        label="Meeting"
+        onChange={() => {}}
+        placeholder="Pick a date"
+        timePlaceholder="Pick a time"
+      />,
+    );
+    // Time portion uses the override; date portion keeps its own placeholder.
+    expect(screen.getByPlaceholderText('Pick a time')).toBeInTheDocument();
+    expect(screen.getByPlaceholderText('Pick a date')).toBeInTheDocument();
+    expect(
+      screen.queryByPlaceholderText('Select a time'),
+    ).not.toBeInTheDocument();
+  });
+
   it('renders both date and time inputs', () => {
     render(<DateTimeInput label="Meeting" onChange={() => {}} />);
     expect(screen.getByRole('combobox')).toBeInTheDocument();
@@ -90,9 +112,7 @@ describe('DateTimeInput', () => {
   });
 
   it('visually hides label when isLabelHidden is true', () => {
-    render(
-      <DateTimeInput label="Meeting" isLabelHidden onChange={() => {}} />,
-    );
+    render(<DateTimeInput label="Meeting" isLabelHidden onChange={() => {}} />);
     const label = screen.getByText('Meeting');
     expect(label).toBeInTheDocument();
     expect(screen.getByLabelText('Meeting')).toBeInTheDocument();

package/src/DateTimeInput/DateTimeInput.tsx

@@ -48,11 +48,7 @@ import {
 } from '../Field';
 import {Icon} from '../Icon';
 import {Spinner} from '../Spinner';
-import {
-  Calendar,
-  type ISODateString,
-  type CalendarHandle,
-} from '../Calendar';
+import {Calendar, type ISODateString, type CalendarHandle} from '../Calendar';
 import {useCalendarConstraints} from '../Calendar/hooks';
 import {usePopover} from '../Popover';
 import {useInputContainer} from '../hooks/useInputContainer';
@@ -278,11 +274,17 @@ export interface DateTimeInputProps extends Omit<
   hasClear?: boolean;
 
   /**
-   * Placeholder text shown when no date is selected.
+   * Placeholder text shown in the date portion when no date is selected.
    * @default "Select a date"
    */
   placeholder?: string;
 
+  /**
+   * Placeholder text shown in the time portion when no time is selected.
+   * @default "Select a time"
+   */
+  timePlaceholder?: string;
+
   /**
    * The size of the inputs.
    * @default 'md'
@@ -385,6 +387,7 @@ export function DateTimeInput({
   timeIncrement = 1,
   hasClear = false,
   placeholder = 'Select a date',
+  timePlaceholder = 'Select a time',
   size: sizeProp,
   status,
   labelTooltip,
@@ -520,12 +523,12 @@ export function DateTimeInput({
     return isTimeInRange(parsed, timeMin, timeMax);
   }, [timePendingInput, hasSeconds, timeMin, timeMax]);
 
-  const timePlaceholder = useMemo(() => {
+  const resolvedTimePlaceholder = useMemo(() => {
     if (isTimeFocused && !timeDisplayValue) {
       return hourFormat === '12h' ? 'e.g., 2:30 PM' : 'e.g., 14:30';
     }
-    return 'Select a time';
-  }, [isTimeFocused, timeDisplayValue, hourFormat]);
+    return timePlaceholder;
+  }, [isTimeFocused, timeDisplayValue, hourFormat, timePlaceholder]);
 
   // --- Unified change handler ---
   const fireChange = useCallback(
@@ -893,7 +896,7 @@ export function DateTimeInput({
             onFocus={handleTimeFocus}
             onBlur={handleTimeBlur}
             onKeyDown={handleTimeKeyDown}
-            placeholder={timePlaceholder}
+            placeholder={resolvedTimePlaceholder}
             disabled={isEffectivelyDisabled}
             aria-label="Time"
             aria-required={isRequired === true ? 'true' : undefined}

package/src/Dialog/Dialog.doc.mjs

@@ -40,13 +40,13 @@ export const docs = {
     {
       name: 'isOpen',
       type: 'boolean',
-      description: 'Whether the dialog is open (required).',
+      description: 'Whether the dialog is open.',
       required: true,
     },
     {
       name: 'onOpenChange',
       type: '(isOpen: boolean) => unknown',
-      description: 'Callback when dialog visibility changes (required).',
+      description: 'Callback when dialog visibility changes.',
       required: true,
     },
     {

package/src/EmptyState/EmptyState.test.tsx

@@ -45,11 +45,13 @@ describe('EmptyState', () => {
       />,
     );
     expect(screen.getByText('Try adjusting your search.')).toBeInTheDocument();
+    // Description renders as <div> (never <p>) so block content composes safely.
+    expect(screen.getByText('Try adjusting your search.').tagName).toBe('DIV');
   });
 
   it('does not render description when not provided', () => {
-    const {container} = render(<EmptyState title="No results" />);
-    expect(container.querySelector('p')).not.toBeInTheDocument();
+    render(<EmptyState title="No results" />);
+    expect(screen.queryByText('Try adjusting your search.')).toBeNull();
   });
 
   it('renders with icon', () => {

package/src/EmptyState/EmptyState.tsx

@@ -174,13 +174,17 @@ export function EmptyState({
           title,
         )}
         {description != null && (
-          <p
+          // Rendered as <div> (not <p>): description accepts ReactNode and a
+          // <p> cannot legally contain block children, which causes hydration
+          // mismatches. The StyleX style sets margin: 0, so appearance is
+          // unchanged.
+          <div
             {...stylex.props(
               styles.description,
               isCompact && styles.descriptionCompact,
             )}>
             {description}
-          </p>
+          </div>
         )}
       </div>
       {actions != null && (

package/src/HoverCard/HoverCard.doc.mjs

@@ -108,6 +108,7 @@ export const docs = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
+      { guidance: false, description: 'Nest a HoverCard whose content has block elements directly inside phrasing-only contexts such as a <p>, <label>, or heading. The card renders inline, so block content there is invalid HTML the browser reparents. Wrap the surrounding text in a block element (e.g. a <div>) instead.' },
     ],
     anatomy: [
       {name: 'Trigger', required: true, description: 'The element that opens the hover card on hover or focus: a button, link, or inline text.'},
@@ -216,6 +217,7 @@ export const docsZh = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
+      { guidance: false, description: 'Nest a HoverCard whose content has block elements directly inside phrasing-only contexts such as a <p>, <label>, or heading. The card renders inline, so block content there is invalid HTML the browser reparents. Wrap the surrounding text in a block element (e.g. a <div>) instead.' },
     ],
   },
 };
@@ -233,6 +235,7 @@ export const docsDense = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
+      { guidance: false, description: 'Nest a block-content HoverCard directly inside phrasing-only contexts (<p>, <label>, heading); it renders inline so block content is invalid HTML there. Wrap surrounding text in a block element instead.' },
     ],
   },
   components: [