@astryxdesign/core 0.1.2 → 0.1.3-canary.1e94ba0

package/src/Button/Button.tsx

@@ -21,6 +21,7 @@
 import {useRef, useTransition, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
+import {useTooltip} from '../Tooltip/useTooltip';
 import {
   colorVars,
   sizeVars,
@@ -32,13 +33,13 @@ import {
   fontWeightVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
-import {Tooltip} from '../Tooltip/Tooltip';
 import {Spinner} from '../Spinner';
+import {VisuallyHidden} from '../VisuallyHidden';
 
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {useSize} from '../SizeContext/SizeContext';
 import {useButtonGroup} from '../ButtonGroup/ButtonGroupContext';
-import {mergeProps} from '../utils';
+import {mergeProps, mergeRefs} from '../utils';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
 import {themeProps} from '../utils/themeProps';
@@ -124,17 +125,6 @@ const styles = stylex.create({
     textOverflow: 'ellipsis',
     minWidth: 0,
   },
-  visuallyHidden: {
-    position: 'absolute',
-    width: '1px',
-    height: '1px',
-    padding: 0,
-    margin: '-1px',
-    overflow: 'hidden',
-    clip: 'rect(0, 0, 0, 0)',
-    whiteSpace: 'nowrap',
-    borderWidth: 0,
-  },
   link: {
     textDecoration: 'none',
   },
@@ -590,6 +580,16 @@ export function Button({
   // for keyboard users to reach the tooltip. Otherwise use native disabled.
   const useAriaDisabled = tooltip != null && buttonDisabled;
 
+  // Attach tooltip behavior via the hook rather than wrapping the button in a
+  // <Tooltip> element. The hook adds hover/focus triggers to the button itself,
+  // so no extra DOM node is inserted — the button stays a direct child of its
+  // container (no layout shift, and edge-compensation markers remain
+  // discoverable through the container's direct-child `:has()` selector).
+  const tooltipHook = useTooltip({
+    placement: 'above',
+    isEnabled: tooltip != null,
+  });
+
   const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
     // The ref guard dedupes fire-once actions. Interruptible callers skip it so
     // a re-click while pending starts a fresh action that interrupts the prior.
@@ -690,12 +690,9 @@ export function Button({
         )}
       </span>
       {/* Live region for loading state announcements */}
-      <span
-        {...stylex.props(styles.visuallyHidden)}
-        role="status"
-        aria-live="polite">
+      <VisuallyHidden role="status" aria-live="polite">
         {isLoadingState ? 'Loading' : ''}
-      </span>
+      </VisuallyHidden>
     </>
   );
 
@@ -709,18 +706,39 @@ export function Button({
     (children != null && children !== label);
   const ariaLabelProp = needsAriaLabel ? {'aria-label': label} : null;
 
+  // When a tooltip is attached via the hook, point aria-describedby at the
+  // tooltip content (composing with any consumer-provided value).
+  const describedByProp =
+    tooltip != null
+      ? {
+          'aria-describedby':
+            [props['aria-describedby'], tooltipHook.describedBy]
+              .filter(Boolean)
+              .join(' ') || undefined,
+        }
+      : null;
+
+  // Merge the consumer ref with the tooltip hook's trigger ref so both point at
+  // the same element. mergeRefs tolerates undefined, so this is a no-op for the
+  // tooltip side when no tooltip is set.
+  const mergedButtonRef = mergeRefs(
+    ref,
+    tooltip != null ? tooltipHook.ref : undefined,
+  );
+
   let element: ReactNode;
 
   if (renderAsLink) {
     element = (
       <LinkComponent
-        ref={ref as React.Ref<HTMLAnchorElement>}
+        ref={mergedButtonRef as React.Ref<HTMLAnchorElement>}
         href={href}
         target={target}
         rel={rel}
         {...sharedMergedProps}
         {...props}
         {...ariaLabelProp}
+        {...describedByProp}
         {...edgeCompAttr}
         onClick={handleClick}>
         {buttonContent}
@@ -729,12 +747,13 @@ export function Button({
   } else {
     element = (
       <button
-        ref={ref}
+        ref={mergedButtonRef}
         type={type}
         disabled={useAriaDisabled ? undefined : buttonDisabled}
         {...sharedMergedProps}
         {...props}
         {...ariaLabelProp}
+        {...describedByProp}
         {...edgeCompAttr}
         aria-busy={isLoadingState || undefined}
         aria-disabled={useAriaDisabled || undefined}
@@ -747,9 +766,10 @@ export function Button({
 
   if (tooltip) {
     return (
-      <Tooltip content={tooltip} placement="above">
+      <>
         {element}
-      </Tooltip>
+        {tooltipHook.renderTooltip(tooltip)}
+      </>
     );
   }
 

package/src/ButtonGroup/ButtonGroup.test.tsx

@@ -88,17 +88,18 @@ describe('ButtonGroup', () => {
     expect(refValue).toBe(screen.getByRole('group'));
   });
 
-  it('sets aria-orientation', () => {
+  it('reflects orientation via data-orientation, not aria-orientation', () => {
+    // aria-orientation is not a valid ARIA attribute on role="group"; the
+    // orientation is exposed through data-orientation instead.
     const {rerender} = render(
       <ButtonGroup label="Actions">
         <Button label="Copy" />
       </ButtonGroup>,
     );
 
-    expect(screen.getByRole('group')).toHaveAttribute(
-      'aria-orientation',
-      'horizontal',
-    );
+    let group = screen.getByRole('group');
+    expect(group).not.toHaveAttribute('aria-orientation');
+    expect(group).toHaveAttribute('data-orientation', 'horizontal');
 
     rerender(
       <ButtonGroup label="Actions" orientation="vertical">
@@ -106,10 +107,9 @@ describe('ButtonGroup', () => {
       </ButtonGroup>,
     );
 
-    expect(screen.getByRole('group')).toHaveAttribute(
-      'aria-orientation',
-      'vertical',
-    );
+    group = screen.getByRole('group');
+    expect(group).not.toHaveAttribute('aria-orientation');
+    expect(group).toHaveAttribute('data-orientation', 'vertical');
   });
 
   it('renders with vertical orientation', () => {

package/src/ButtonGroup/ButtonGroup.tsx

@@ -141,7 +141,6 @@ export function ButtonGroup({
           role="group"
           aria-label={label}
           onKeyDown={handleKeyDown}
-          aria-orientation={orientation}
           aria-disabled={isDisabled || undefined}
           data-testid={testId}
           {...mergeProps(

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' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | '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

@@ -10,19 +10,21 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {act, render, screen} from '@testing-library/react';
+import {act, render, screen, within} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Calendar} from './Calendar';
 import type {CalendarHandle} from './Calendar';
 
 /**
  * Helper to find a day button by its day number.
- * Day buttons have aria-labels like "Thursday, January 15, 2026".
+ * Day buttons are native <button> elements with aria-labels like
+ * "Thursday, January 15, 2026". Each button is the sole child of a
+ * role="gridcell" wrapper.
  */
 function getDayButton(day: number, month = 'January', year = 2026) {
   // Match the full date pattern with the day number
   const pattern = new RegExp(`${month}\\s+${day},\\s+${year}`);
-  return screen.getByRole('gridcell', {name: pattern});
+  return screen.getByRole('button', {name: pattern});
 }
 
 describe('Calendar', () => {
@@ -146,10 +148,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 +188,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 +235,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 +257,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 +279,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
@@ -321,6 +325,75 @@ describe('Calendar', () => {
     expect(screen.getAllByRole('gridcell').length).toBeGreaterThan(0);
   });
 
+  it('renders a valid APG grid: one grid, header row of columnheaders inside it, week rows of gridcells', () => {
+    render(<Calendar focusDate="2026-01-01" />);
+
+    const grids = screen.getAllByRole('grid');
+    expect(grids.length).toBe(1);
+    const grid = grids[0];
+
+    // The columnheaders live INSIDE the grid.
+    const columnHeaders = screen.getAllByRole('columnheader');
+    expect(columnHeaders.length).toBe(7);
+    for (const header of columnHeaders) {
+      expect(grid.contains(header)).toBe(true);
+    }
+
+    // The grid's rows: first is the header row of columnheaders, the rest are
+    // week rows whose direct children are gridcells.
+    const rows = within(grid).getAllByRole('row');
+    // 1 header row + 6 week rows (fixed 6-row grid).
+    expect(rows.length).toBe(7);
+
+    const [headerRow, ...weekRows] = rows;
+
+    // Header row's direct children are the 7 columnheaders.
+    const headerChildren = Array.from(headerRow.children);
+    const headerColHeaders = headerChildren.filter(
+      child => child.getAttribute('role') === 'columnheader',
+    );
+    expect(headerColHeaders.length).toBe(7);
+
+    // Each week row's direct children are gridcells (7 per row).
+    for (const row of weekRows) {
+      const gridcellChildren = Array.from(row.children).filter(
+        child => child.getAttribute('role') === 'gridcell',
+      );
+      expect(gridcellChildren.length).toBe(7);
+    }
+  });
+
+  it('renders week-number cells as rowheader when hasWeekNumbers is set', () => {
+    render(<Calendar hasWeekNumbers focusDate="2026-01-01" />);
+
+    const grid = screen.getByRole('grid');
+    const rowHeaders = within(grid).getAllByRole('rowheader');
+    // One rowheader (week number) per week row.
+    expect(rowHeaders.length).toBeGreaterThanOrEqual(5);
+    // Week numbers are numeric.
+    for (const header of rowHeaders) {
+      expect(header.textContent).toMatch(/^\d+$/);
+    }
+  });
+
+  it('gridcell wrappers are direct children of week rows, and the button is inside the gridcell', () => {
+    render(<Calendar focusDate="2026-01-01" />);
+
+    const grid = screen.getByRole('grid');
+    const gridcells = within(grid).getAllByRole('gridcell');
+    for (const cell of gridcells) {
+      // The gridcell's parent is a role="row".
+      const parent = cell.parentElement;
+      expect(parent?.getAttribute('role')).toBe('row');
+      // The day button (if present) is a descendant of the gridcell.
+      const button = cell.querySelector('button');
+      if (button) {
+        expect(cell.contains(button)).toBe(true);
+        expect(button).not.toHaveAttribute('role', 'gridcell');
+      }
+    }
+  });
+
   it('has navigation buttons with accessible labels', () => {
     render(<Calendar />);
 
@@ -346,16 +419,13 @@ describe('Calendar', () => {
     const handleFocusChange = vi.fn();
 
     render(
-      <Calendar
-        focusDate="2026-01-01"
-        onFocusDateChange={handleFocusChange}
-      />,
+      <Calendar focusDate="2026-01-01" onFocusDateChange={handleFocusChange} />,
     );
 
     // Focus Jan 28
     const day28 = getDayButton(28);
     await user.click(day28);
-    day28.querySelector('button')?.focus();
+    day28.focus();
 
     // Press ArrowDown — should move to Feb 4 (+7 days), not Feb 28
     await user.keyboard('{ArrowDown}');
@@ -365,6 +435,78 @@ describe('Calendar', () => {
     expect(focusedElement).toHaveAttribute('data-date', '2026-02-04');
   });
 
+  it('ArrowDown lands on the same weekday +7 days even when earlier days are disabled (complex-2)', async () => {
+    const user = userEvent.setup();
+
+    // min disables Jan 1–4 (HTML-disabled). Jan 8 is a Thursday; ArrowDown must
+    // land on Jan 15 (the same weekday, +7 days), not a shifted date caused by
+    // the removed enabled cells.
+    render(<Calendar focusDate="2026-01-01" min="2026-01-05" />);
+
+    const day1 = getDayButton(1);
+    expect(day1).toBeDisabled();
+
+    const day8 = getDayButton(8);
+    day8.focus();
+
+    await user.keyboard('{ArrowDown}');
+    expect(document.activeElement).toHaveAttribute('data-date', '2026-01-15');
+
+    await user.keyboard('{ArrowDown}');
+    expect(document.activeElement).toHaveAttribute('data-date', '2026-01-22');
+  });
+
+  it('ArrowUp skips a disabled cell in the same column to the next enabled row (complex-2)', async () => {
+    const user = userEvent.setup();
+
+    // max disables Jan 22 onward. Focus Feb 5 handling is out of scope; instead
+    // use dateConstraints to disable a single mid-grid day and verify column
+    // geometry is preserved (ArrowUp from Jan 15 skips disabled Jan 8 → Jan 1).
+    const disableJan8 = (date: Date) =>
+      !(
+        date.getFullYear() === 2026 &&
+        date.getMonth() === 0 &&
+        date.getDate() === 8
+      );
+
+    render(<Calendar focusDate="2026-01-01" dateConstraints={[disableJan8]} />);
+
+    const day8 = getDayButton(8);
+    expect(day8).toBeDisabled();
+
+    const day15 = getDayButton(15);
+    day15.focus();
+
+    // ArrowUp: same column one row up is Jan 8 (disabled) → skip to Jan 1.
+    await user.keyboard('{ArrowUp}');
+    expect(document.activeElement).toHaveAttribute('data-date', '2026-01-01');
+  });
+
+  it('cross-month arrow nav resolves the focused date from data-date (locale-safe)', async () => {
+    // Regression for complex-4: getFocusedDate must read the machine-readable
+    // data-date attribute, not parse the human-readable aria-label with
+    // new Date() (which is locale-dependent). We prove the resolution path by
+    // corrupting the aria-label to something new Date() cannot parse — cross-
+    // month navigation must still report the correct ISO date.
+    const user = userEvent.setup();
+    const handleFocusChange = vi.fn();
+
+    render(
+      <Calendar focusDate="2026-01-01" onFocusDateChange={handleFocusChange} />,
+    );
+
+    const day28 = getDayButton(28);
+    await user.click(day28);
+    day28.focus();
+    // Simulate a non-English/unparseable aria-label while keeping data-date.
+    day28.setAttribute('aria-label', '2026年1月28日 水曜日');
+
+    await user.keyboard('{ArrowDown}');
+
+    // Feb 4 (+7 days) — resolved via data-date despite the unparseable label.
+    expect(document.activeElement).toHaveAttribute('data-date', '2026-02-04');
+  });
+
   it('prev button is disabled when focusDate month contains min', () => {
     render(<Calendar focusDate="2026-01-01" min="2026-01-15" />);
 
@@ -414,11 +556,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