@astryxdesign/core 0.7.2-canary.caec7ca → 0.7.2-canary.d150f78

package/dist/utils/plainDate.js

@@ -202,15 +202,21 @@ export function plainDateSetEndOfWeekExclusive(pd, weekStartsOn) {
   return plainDateAddDays(plainDateSetStartOfWeek(pd, weekStartsOn), 7);
 }
 export function plainDateGetWeekNumber(pd) {
-  const d = plainDateToDate(pd);
-  const dayNum = d.getDay() || 7;
-  d.setDate(d.getDate() + 4 - dayNum);
-  const yearStart = plainDateToDate({
-    year: d.getFullYear(),
-    month: 1,
-    day: 1
-  });
-  return Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+  // ISO week number: ceil(day-of-year of the week's Thursday / 7). Computed
+  // entirely on UTC anchors — the same DST immunity plainDateDiffDays relies
+  // on — because mixing local-time instants leaks the host zone's DST offset
+  // into the day count. When Jan 1 is a Friday (so every Thursday's day-of-year
+  // is an exact multiple of 7), a one-hour offset from a zone whose DST ends
+  // after New Year rounds a whole week up: Sydney, Auckland and Santiago users
+  // saw week 15 for the week that is ISO week 14. utcTime keeps years 1-99
+  // as given, like the other Calendar date helpers.
+  const msPerDay = 24 * 60 * 60 * 1000;
+  const utcMidnight = utcTime(pd.year, pd.month - 1, pd.day);
+  const dayNum = new Date(utcMidnight).getUTCDay() || 7;
+  const thursday = utcMidnight + (4 - dayNum) * msPerDay;
+  const yearStart = utcTime(new Date(thursday).getUTCFullYear(), 0, 1);
+  const dayOfYear = (thursday - yearStart) / msPerDay + 1;
+  return Math.ceil(dayOfYear / 7);
 }
 
 // e.g. "Wednesday, May 21, 2026" (locale-dependent)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.2-canary.caec7ca",
+  "version": "0.7.2-canary.d150f78",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -792,8 +792,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.7.2-canary.caec7ca",
-    "@astryxdesign/cli": "0.7.2-canary.caec7ca",
+    "@astryxdesign/a11y-spec": "0.7.2-canary.d150f78",
+    "@astryxdesign/cli": "0.7.2-canary.d150f78",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -209,6 +209,40 @@ describe('CheckboxInput', () => {
     );
   });
 
+  it('preserves a caller-provided id on the input and its label', () => {
+    render(
+      <CheckboxInput
+        id="accept-terms"
+        label="Accept terms"
+        value={false}
+        onChange={() => {}}
+      />,
+    );
+
+    const checkbox = screen.getByRole('checkbox');
+    expect(checkbox).toHaveAttribute('id', 'accept-terms');
+    expect(screen.getByText('Accept terms').closest('label')).toHaveAttribute(
+      'for',
+      'accept-terms',
+    );
+    expect(screen.getByLabelText('Accept terms')).toBe(checkbox);
+  });
+
+  it('generates an id the label resolves when the caller passes an empty id', () => {
+    render(
+      <CheckboxInput
+        id=""
+        label="Accept terms"
+        value={false}
+        onChange={() => {}}
+      />,
+    );
+
+    const checkbox = screen.getByRole('checkbox');
+    expect(checkbox.id).not.toBe('');
+    expect(screen.getByLabelText('Accept terms')).toBe(checkbox);
+  });
+
   it('forwards arbitrary data-* attributes to the input', () => {
     render(
       <CheckboxInput

package/src/CheckboxInput/CheckboxInput.tsx

@@ -311,6 +311,7 @@ const dynamicWidthStyles = stylex.create({
  * ```
  */
 export function CheckboxInput({
+  id: idProp,
   label,
   isLabelHidden = false,
   description,
@@ -340,7 +341,8 @@ export function CheckboxInput({
   // The row is the pressable: the overlay's pressed arm reads the row's
   // scope marker, the way the indicator's hover tint does.
   const pressable = usePressFeedback();
-  const id = useId();
+  const generatedId = useId();
+  const id = idProp || generatedId;
   const descriptionID = useId();
   const statusMessageID = useId();
   // Announce the effective required state (form default included) while the

package/src/Dialog/Dialog.test.tsx

@@ -110,6 +110,52 @@ beforeEach(() => {
 });
 
 describe('Dialog', () => {
+  it('restores focus to the opener when content mounts in the open commit', () => {
+    function Harness({
+      open,
+      onOpenChange,
+    }: {
+      open: boolean;
+      onOpenChange: (v: boolean) => void;
+    }) {
+      return (
+        <>
+          <button type="button" onClick={() => onOpenChange(true)}>
+            Open
+          </button>
+          <Dialog isOpen={open} onOpenChange={onOpenChange}>
+            {open ? (
+              <div>
+                <DialogHeader title="Review" />
+                <p>Body</p>
+              </div>
+            ) : null}
+          </Dialog>
+        </>
+      );
+    }
+
+    let open = false;
+    const setOpen = (v: boolean) => {
+      open = v;
+    };
+    const harness = render(<Harness open={open} onOpenChange={setOpen} />);
+    const opener = screen.getByRole('button', {name: 'Open'});
+    opener.focus();
+
+    fireEvent.click(opener);
+    harness.rerender(<Harness open={open} onOpenChange={setOpen} />);
+
+    // The freshly mounted header title is the focused screen reader anchor
+    // while the dialog is open...
+    expect(document.activeElement).toBe(screen.getByText('Review'));
+
+    // ...but closing restores the element that opened the dialog, not the
+    // (now unmounted) title.
+    harness.rerender(<Harness open={false} onOpenChange={setOpen} />);
+    expect(document.activeElement).toBe(opener);
+  });
+
   it('renders when isOpen is true', () => {
     render(
       <Dialog isOpen={true} onOpenChange={() => {}}>

package/src/Dialog/Dialog.tsx

@@ -32,6 +32,7 @@ import {
   useCallback,
   useEffect,
   useId,
+  useLayoutEffect,
   useMemo,
   useRef,
   type ReactNode,
@@ -505,12 +506,26 @@ export function Dialog({
 
   const mergedDialogRef = useMergedRefs(ref, attachDialog);
 
-  // Capture the element that was focused when the dialog opened,
-  // for directional animation origin and focus restoration on close.
+  // Capture the element that was focused when the dialog opened, for
+  // directional animation origin and focus restoration on close.
   const triggerElementRef = useRef<HTMLElement | null>(null);
 
   useInteractionModalityTracking();
 
+  // This runs in a layout effect so the capture lands before any descendant's
+  // passive mount effect: all layout effects run before any passive effect,
+  // while a child's passive effect runs before this parent's passive effect.
+  // Content that mounts in the open commit — e.g. a DialogHeader focusing its
+  // own title on mount — would otherwise move document.activeElement inside
+  // the dialog before the capture ran, and closing would then restore focus
+  // to a detached node, stranding the user's focus on <body>.
+  useLayoutEffect(() => {
+    if (isInline || !isOpen) {
+      return;
+    }
+    triggerElementRef.current = document.activeElement as HTMLElement | null;
+  }, [isOpen, isInline]);
+
   // Derive dismissal behavior from purpose
   const allowEscape = purpose !== 'required';
   const allowBackdropClick = purpose === 'info';
@@ -526,11 +541,9 @@ export function Dialog({
     }
 
     if (isOpen) {
-      // Capture the currently focused element as the trigger — used for
-      // directional animation origin and focus restoration on close.
-      triggerElementRef.current = document.activeElement as HTMLElement | null;
-
-      // Set directional CSS custom properties before opening
+      // Set directional CSS custom properties before opening. The trigger was
+      // captured by the layout effect above, before any descendant effect
+      // could move focus.
       const trigger = triggerElementRef.current;
       if (trigger && trigger !== document.body) {
         const dir = getDialogDirection(trigger);

package/src/Dialog/__tests__/Dialog.a11y.known-failures.ts

@@ -25,18 +25,4 @@ export const DIALOG_MODAL_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
     reason:
       'This migration records the existing focus-order violation without changing the overlapping Dialog implementation path.',
   },
-  {
-    expectation: 'modal-dialog.focus.restored',
-    binding: 'Dialog',
-    state: 'conditional-content-focus-restoration',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      'closing the modal dialog did not return focus to its still-available invoker',
-    standardsReference:
-      'Astryx component:Dialog FR4 — closing a native Dialog must return focus to its still-connected invoker when it can receive focus.',
-    userImpact:
-      'When focus-moving content mounts only while the dialog is open, closing can leave the user at the document body instead of the control that opened the task.',
-    reason:
-      'This migration records the existing restoration violation without changing the overlapping Dialog implementation path.',
-  },
 ];

package/src/Item/Item.doc.mjs

@@ -49,7 +49,7 @@ export const docs = {
       {
         name: '--_item-inset-inline',
         description:
-          'Inline inset of the row. Item derives its paddingInline from this variable, and List reads it to cancel the inset when edgeCompensation="inline". Set paddingInline on `item` in a theme and both stay in sync.',
+          'Inline inset of the row. Item derives its paddingInline from this variable, and List reads it to place rows for its edge treatments (edge="flush", "outset", and "bleed"). Set paddingInline on `item` in a theme and both stay in sync.',
         default: 'var(--spacing-2) (var(--spacing-3) for density="spacious")',
         private: true,
       },

package/src/Item/Item.tsx

@@ -342,7 +342,7 @@ const styles = stylex.create({
     gap: spacingVars['--spacing-2'],
     // The inline inset is published as --_item-inset-inline and the padding
     // derives from it, so consumers that need to compensate for the inset
-    // (List's edgeCompensation) read the var instead of mirroring the values.
+    // (List's edge treatments) read the var instead of mirroring the values.
     // Themes that set paddingInline on `item` also feed this var via the
     // derived var registry, keeping padding and compensation in sync.
     '--_item-inset-inline': spacingVars['--spacing-2'],

package/src/List/List.doc.mjs

@@ -41,11 +41,18 @@ export const docs = {
       description: 'Show dividers between items.',
       default: 'false',
     },
+    {
+      name: 'edge',
+      type: "'padded' | 'flush' | 'outset' | 'bleed'",
+      description:
+        "Where each row's text, dividers, and hover and selection backgrounds sit, relative to the list's edges and the container around it. 'padded' keeps text inside each row's padding, so it starts a little in from a heading above the list and backgrounds have room around it. 'flush' drops the rows' side padding: text starts on the heading's line, and dividers and backgrounds stop at the row's content, with no room beyond it on either side. It works anywhere and suits static rows. 'outset' puts text on the heading's line and reaches dividers and backgrounds a little past it into the container's padding; it suits interactive rows in a container. 'bleed' puts text on the heading's line and reaches dividers and backgrounds to the container's edges with square corners, like Table rows in a Card. A row's first content is what lines up with the heading: its marker, icon, or avatar when it has one, otherwise its label. 'outset' and 'bleed' reach into the padding of the nearest container that shares its padding: a Card, Section, Dialog, or BottomSheet, or a transparent container such as a Layout region with explicit padding or a padded ScrollableArea. Place the List directly in that container's padding: padding that Stack, Center, or your own styles add in between is not counted. Drawers and the automatic padding of LayoutContent and LayoutPanel aren't supported yet. With no such container, including in a Popover, they look like 'padded'. In a container with less padding than the rows' own, text starts a little after the heading's line. A theme's inline padding on `item` replaces the row padding of every value, including the zero padding of flush.",
+      default: "'padded'",
+    },
     {
       name: 'edgeCompensation',
       type: "'inline'",
       description:
-        "Compensate for item content inset on each inline edge by cancelling the smaller of each item's built-in horizontal inset and the container's published inline padding. The margin reads the same variable the items derive their inline padding from, so it tracks density and theme padding overrides automatically without pulling rows outside zero-padding or full-bleed surfaces. Use under a section heading to bring row text toward the heading text. Content aligns when container padding is at least the item inset; smaller padding leaves some inset uncompensated. Omit to leave item positions unchanged.",
+        "Deprecated: use edge=\"outset\", which this sets. Still works; edge wins when both are set. `astryx upgrade` rewrites existing usage.",
     },
     {
       name: 'header',
@@ -89,6 +96,8 @@ export const docs = {
     bestPractices: [
       { guidance: true, description: 'Provide a header to label the list and give context to screen readers.' },
       { guidance: true, description: 'Use start and end content slots to add icons, avatars, or badges to each item.' },
+      { guidance: true, description: 'Set edge to line row text up with a heading above the list: flush for static rows, outset or bleed for rows in a Card, Section, or Dialog.' },
+      { guidance: true, description: 'To line text up with a heading and keep room around the highlight where there is no Card, such as a sidebar, put the heading and the list in a Section with variant="transparent" and set edge="outset".' },
       { guidance: false, description: 'Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.' },
       { guidance: false, description: 'Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.' },
       { guidance: false, description: 'Mix clickable and non-clickable items in the same list without clear visual distinction.' },
@@ -109,6 +118,8 @@ export const docsZh = {
     bestPractices: [
       { guidance: true, description: 'Provide a header to label the list and give context to screen readers.' },
       { guidance: true, description: 'Use start and end content slots to add icons, avatars, or badges to each item.' },
+      { guidance: true, description: 'Set edge to line row text up with a heading above the list: flush for static rows, outset or bleed for rows in a Card, Section, or Dialog.' },
+      { guidance: true, description: 'To line text up with a heading and keep room around the highlight where there is no Card, such as a sidebar, put the heading and the list in a Section with variant="transparent" and set edge="outset".' },
       { guidance: false, description: 'Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.' },
       { guidance: false, description: 'Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.' },
       { guidance: false, description: 'Mix clickable and non-clickable items in the same list without clear visual distinction.' },
@@ -132,6 +143,8 @@ export const docsDense = {
     bestPractices: [
       { guidance: true, description: 'Provide a header to label the list and give context to screen readers.' },
       { guidance: true, description: 'Use start and end content slots to add icons, avatars, or badges to each item.' },
+      { guidance: true, description: 'Set edge to line row text up with a heading above the list: flush for static rows, outset or bleed for rows in a Card, Section, or Dialog.' },
+      { guidance: true, description: 'To line text up with a heading and keep room around the highlight where there is no Card, such as a sidebar, put the heading and the list in a Section with variant="transparent" and set edge="outset".' },
       { guidance: false, description: 'Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.' },
       { guidance: false, description: 'Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.' },
       { guidance: false, description: 'Mix clickable and non-clickable items in the same list without clear visual distinction.' },