@astryxdesign/core 0.1.4-canary.39ffd21 → 0.1.4-canary.3d64ef2

package/dist/utils/color.js

@@ -0,0 +1,150 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file color.ts
+ * @input CSS color strings (hex, rgb()/rgba(), a small set of named colors)
+ * @output Shared color parsing/formatting primitives used across the design system
+ * @position Package utility; backs theme token resolution, HCT color math, and chart rendering
+ *
+ * A single home for the color parsers that were previously duplicated across
+ * the theme layer, charts, and lab. Consumers get one well-tested definition of
+ * "parse this color" rather than several subtly different regexes.
+ */
+
+/** A color decomposed into 0-255 RGB channels and a 0-1 alpha. */
+
+/** The named colors the design system relies on in token expressions. */
+const NAMED_COLORS = {
+  transparent: {
+    r: 0,
+    g: 0,
+    b: 0,
+    a: 0
+  },
+  black: {
+    r: 0,
+    g: 0,
+    b: 0,
+    a: 1
+  },
+  white: {
+    r: 255,
+    g: 255,
+    b: 255,
+    a: 1
+  }
+};
+const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+
+/** Expand a shorthand hex body (`rgb`/`rgba`) to its full form (`rrggbb`/`rrggbbaa`). */
+function expandShorthand(body) {
+  return body.split('').map(c => c + c).join('');
+}
+
+/**
+ * Parse a hex color into {@link RGBA}. Accepts `#rgb`, `#rgba`, `#rrggbb`, and
+ * `#rrggbbaa`, with or without the leading `#`. Returns null for anything else.
+ */
+export function parseHex(hex) {
+  if (typeof hex !== 'string') {
+    return null;
+  }
+  const body = hex.trim().replace(/^#/, '');
+  const normalized = body.length === 3 || body.length === 4 ? expandShorthand(body) : body;
+  if (normalized.length !== 6 && normalized.length !== 8 || !/^[0-9a-fA-F]+$/.test(normalized)) {
+    return null;
+  }
+  return {
+    r: parseInt(normalized.slice(0, 2), 16),
+    g: parseInt(normalized.slice(2, 4), 16),
+    b: parseInt(normalized.slice(4, 6), 16),
+    a: normalized.length === 8 ? parseInt(normalized.slice(6, 8), 16) / 255 : 1
+  };
+}
+
+/**
+ * Parse an `rgb()`/`rgba()` color into {@link RGBA}. Accepts comma- or
+ * space-separated channels, an optional `/ alpha`, and percentage channels.
+ */
+export function parseRgb(value) {
+  const open = value.indexOf('(');
+  if (open === -1 || !value.trim().endsWith(')')) {
+    return null;
+  }
+  const body = value.slice(open + 1, value.lastIndexOf(')')).replace(/\//g, ' ');
+  const parts = body.split(/[\s,]+/).map(p => p.trim()).filter(Boolean);
+  if (parts.length < 3) {
+    return null;
+  }
+  const channel = p => {
+    const n = p.endsWith('%') ? parseFloat(p) / 100 * 255 : parseFloat(p);
+    return clamp(n, 0, 255);
+  };
+  const r = channel(parts[0]);
+  const g = channel(parts[1]);
+  const b = channel(parts[2]);
+  if ([r, g, b].some(Number.isNaN)) {
+    return null;
+  }
+  let a = 1;
+  if (parts.length >= 4) {
+    const raw = parts[3];
+    a = raw.endsWith('%') ? parseFloat(raw) / 100 : parseFloat(raw);
+    if (Number.isNaN(a)) {
+      return null;
+    }
+    a = clamp(a, 0, 1);
+  }
+  return {
+    r,
+    g,
+    b,
+    a
+  };
+}
+
+/**
+ * Parse a concrete CSS color string into {@link RGBA}. Supports hex,
+ * `rgb()`/`rgba()`, and the named colors used in token expressions. Returns
+ * null for anything it can't evaluate (e.g. `var()`, `oklch()`, unknown names)
+ * so callers can preserve the original expression rather than guessing.
+ */
+export function parseColor(value) {
+  const trimmed = value.trim();
+  const named = NAMED_COLORS[trimmed.toLowerCase()];
+  if (named) {
+    return {
+      ...named
+    };
+  }
+  if (trimmed.startsWith('#')) {
+    return parseHex(trimmed);
+  }
+  if (/^rgba?\(/i.test(trimmed)) {
+    return parseRgb(trimmed);
+  }
+  return null;
+}
+
+/** Format RGB channels (0-255) as an uppercase `#RRGGBB` string. */
+export function formatHex(r, g, b) {
+  const channel = c => clamp(Math.round(c), 0, 255).toString(16).padStart(2, '0').toUpperCase();
+  return `#${channel(r)}${channel(g)}${channel(b)}`;
+}
+
+/**
+ * Serialize {@link RGBA} to a compact, JS-usable CSS color: `#RRGGBB` when
+ * fully opaque, otherwise `rgba(r, g, b, a)`.
+ */
+export function formatColor({
+  r,
+  g,
+  b,
+  a
+}) {
+  if (a >= 1) {
+    return formatHex(r, g, b);
+  }
+  const round = n => clamp(Math.round(n), 0, 255);
+  return `rgba(${round(r)}, ${round(g)}, ${round(b)}, ${parseFloat(a.toFixed(4))})`;
+}

package/dist/utils/index.d.ts

@@ -22,4 +22,6 @@ export { observeResize, unobserveResize } from './sharedResizeObserver';
 export { isRenderable } from './isRenderable';
 export { getInputARIA } from './inputAria';
 export type { InputARIA, InputARIAInputGroup } from './inputAria';
+export { parseHex, parseRgb, parseColor, formatHex, formatColor } from './color';
+export type { RGBA } from './color';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,YAAY,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAEvC,YAAY,EAAC,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAC,MAAM,aAAa,CAAC;AAEhF,OAAO,EACL,cAAc,EACd,SAAS,EACT,QAAQ,EACR,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,8BAA8B,EAC9B,sBAAsB,EACtB,eAAe,EACf,wBAAwB,EACxB,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,WAAW,EACX,aAAa,EACb,SAAS,EACT,UAAU,EACV,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAC,aAAa,EAAE,UAAU,EAAC,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAC,MAAM,EAAE,KAAK,GAAG,EAAE,KAAK,WAAW,EAAC,MAAM,UAAU,CAAC;AAE5D,OAAO,EAAC,UAAU,EAAC,MAAM,cAAc,CAAC;AACxC,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AACtC,OAAO,EAAC,UAAU,EAAE,mBAAmB,EAAC,MAAM,cAAc,CAAC;AAC7D,YAAY,EACV,UAAU,EACV,UAAU,EACV,mBAAmB,EACnB,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,OAAO,EAAC,UAAU,EAAE,YAAY,EAAC,MAAM,cAAc,CAAC;AACtD,YAAY,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAC,aAAa,EAAE,eAAe,EAAC,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAC,YAAY,EAAC,MAAM,aAAa,CAAC;AACzC,YAAY,EAAC,SAAS,EAAE,mBAAmB,EAAC,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,YAAY,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAEvC,YAAY,EAAC,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAC,MAAM,aAAa,CAAC;AAEhF,OAAO,EACL,cAAc,EACd,SAAS,EACT,QAAQ,EACR,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,8BAA8B,EAC9B,sBAAsB,EACtB,eAAe,EACf,wBAAwB,EACxB,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,WAAW,EACX,aAAa,EACb,SAAS,EACT,UAAU,EACV,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAC,aAAa,EAAE,UAAU,EAAC,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAC,MAAM,EAAE,KAAK,GAAG,EAAE,KAAK,WAAW,EAAC,MAAM,UAAU,CAAC;AAE5D,OAAO,EAAC,UAAU,EAAC,MAAM,cAAc,CAAC;AACxC,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AACtC,OAAO,EAAC,UAAU,EAAE,mBAAmB,EAAC,MAAM,cAAc,CAAC;AAC7D,YAAY,EACV,UAAU,EACV,UAAU,EACV,mBAAmB,EACnB,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,OAAO,EAAC,UAAU,EAAE,YAAY,EAAC,MAAM,cAAc,CAAC;AACtD,YAAY,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAC,aAAa,EAAE,eAAe,EAAC,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAC,YAAY,EAAC,MAAM,aAAa,CAAC;AACzC,YAAY,EAAC,SAAS,EAAE,mBAAmB,EAAC,MAAM,aAAa,CAAC;AAEhE,OAAO,EAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAC,MAAM,SAAS,CAAC;AAC/E,YAAY,EAAC,IAAI,EAAC,MAAM,SAAS,CAAC"}

package/dist/utils/index.js

@@ -18,4 +18,5 @@ export { themeProps, themeDataAttributes } from "./themeProps.js";
 export { groupItems, getItemGroup } from "./groupItems.js";
 export { observeResize, unobserveResize } from "./sharedResizeObserver.js";
 export { isRenderable } from "./isRenderable.js";
-export { getInputARIA } from "./inputAria.js";
+export { getInputARIA } from "./inputAria.js";
+export { parseHex, parseRgb, parseColor, formatHex, formatColor } from "./color.js";

package/dist/utils/timeParser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timeParser.d.ts","sourceRoot":"","sources":["../../src/utils/timeParser.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG;IAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAMvE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA6B5D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,cAAc,GAAE,OAAe,GAC9B,aAAa,CAUf;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,cAAc,GAAE,OAAe,GAC9B,MAAM,CAqBR;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,cAAc,GAAE,OAAe,GAC9B,MAAM,CAmBR;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,cAAc,GAAE,OAAe,GAC9B,aAAa,GAAG,IAAI,CAuGtB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,CAAC,EAAE,aAAa,GAAG,SAAS,EAC5B,CAAC,EAAE,aAAa,GAAG,SAAS,GAC3B,MAAM,CA4BR;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,GAClB,OAAO,CAQT;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,cAAc,GAAE,OAAe,GAC9B,aAAa,CAoBf;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,aAAa,EACnB,YAAY,EAAE,MAAM,EACpB,cAAc,GAAE,OAAe,GAC9B,aAAa,CAqBf"}
+{"version":3,"file":"timeParser.d.ts","sourceRoot":"","sources":["../../src/utils/timeParser.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG;IAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAMvE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA6B5D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,cAAc,GAAE,OAAe,GAC9B,aAAa,CAUf;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,cAAc,GAAE,OAAe,GAC9B,MAAM,CAqBR;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,cAAc,GAAE,OAAe,GAC9B,MAAM,CAmBR;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,cAAc,GAAE,OAAe,GAC9B,aAAa,GAAG,IAAI,CAuGtB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,CAAC,EAAE,aAAa,GAAG,SAAS,EAC5B,CAAC,EAAE,aAAa,GAAG,SAAS,GAC3B,MAAM,CA4BR;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,GAClB,OAAO,CAQT;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,cAAc,GAAE,OAAe,GAC9B,aAAa,CAoBf;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,aAAa,EACnB,YAAY,EAAE,MAAM,EACpB,cAAc,GAAE,OAAe,GAC9B,aAAa,CAwBf"}

package/dist/utils/timeParser.js

@@ -305,13 +305,16 @@ export function adjustTime(time, deltaMinutes, includeSeconds = false) {
   if (!parsed) {
     return time;
   }
-  let totalMinutes = parsed.hour * 60 + parsed.minute + deltaMinutes;
 
-  // Wrap around midnight
-  while (totalMinutes < 0) {
-    totalMinutes += 24 * 60;
+  // A non-finite delta would spin the wrap-around forever (-Infinity) or
+  // produce "NaN:NaN" (NaN) — return the input unchanged instead.
+  if (!Number.isFinite(deltaMinutes)) {
+    return time;
   }
-  totalMinutes = totalMinutes % (24 * 60);
+  let totalMinutes = parsed.hour * 60 + parsed.minute + deltaMinutes;
+
+  // Wrap around midnight (double-modulo handles negatives in O(1))
+  totalMinutes = (totalMinutes % (24 * 60) + 24 * 60) % (24 * 60);
   const newHour = Math.floor(totalMinutes / 60);
   const newMinute = totalMinutes % 60;
   return formatISOTime({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.1.4-canary.39ffd21",
+  "version": "0.1.4-canary.3d64ef2",
   "displayName": "XDS Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",

package/src/Avatar/Avatar.doc.mjs

@@ -106,4 +106,15 @@ export const docsDense = {
       {guidance: false, description: 'Force a square or custom shape. Avatars are always circular.'},
     ],
   },
+  propDescriptions: {
+    src: 'primary image source URL',
+    fallbackSrc: 'fallback image when primary fails',
+    name: 'user name for initials and alt text',
+    alt: 'alt text; falls back to name',
+    size: "avatar size. Named ('tiny', 'xsmall', 'small', 'medium', 'large') or numeric px. Short names 'sm'/'md'/'lg' are NOT valid; use full words.",
+    status: 'corner content for status indicators',
+  },
+  components: [
+    {name: 'AvatarStatusDot', description: 'size-aware status indicator rendered in the Avatar corner'},
+  ],
 };

package/src/Banner/Banner.doc.mjs

@@ -113,6 +113,7 @@ export const docs = {
     targets: [
       {className: 'astryx-banner', visualProps: ['container', 'status']},
       {className: 'astryx-banner-icon', visualProps: ['status']},
+      {className: 'astryx-banner-content', visualProps: ['container', 'status']},
     ],
     vars: [
       {name: '--_banner-radius', description: 'Border radius (card container only)', default: 'var(--radius-container)', private: true},
@@ -180,6 +181,13 @@ export const docsZh = {
           'status',
         ],
       },
+      {
+        className: 'astryx-banner-content',
+        visualProps: [
+          'container',
+          'status',
+        ],
+      },
     ],
     vars: [
       {name: '--_banner-radius', description: 'Border radius (card container only)', default: 'var(--radius-container)', private: true},

package/src/Banner/Banner.test.tsx

@@ -270,6 +270,44 @@ describe('Banner', () => {
     expect(expandIndex).toBeLessThan(dismissIndex);
   });
 
+  it('links the expand toggle to its content region via aria-controls', () => {
+    render(
+      <Banner status="info" title="Controls Test" defaultIsExpanded>
+        <div data-testid="region-content">Region content</div>
+      </Banner>,
+    );
+
+    const toggle = screen.getByRole('button', {name: 'Collapse'});
+    const controlsId = toggle.getAttribute('aria-controls');
+    // aria-controls must be present and point at the real content region.
+    expect(controlsId).toBeTruthy();
+    const region = document.getElementById(controlsId as string);
+    expect(region).not.toBeNull();
+    expect(region).toContainElement(screen.getByTestId('region-content'));
+  });
+
+  it('sets aria-controls only while the content region is mounted', async () => {
+    const user = userEvent.setup();
+    render(
+      <Banner status="info" title="Controls Toggle">
+        <div data-testid="region-content">Region content</div>
+      </Banner>,
+    );
+
+    // Collapsed: the region is unmounted, so no dangling aria-controls target.
+    const collapsedToggle = screen.getByRole('button', {name: 'Expand'});
+    expect(collapsedToggle).not.toHaveAttribute('aria-controls');
+
+    // Expanded: aria-controls resolves to the mounted region with the children.
+    await user.click(collapsedToggle);
+    const expandedToggle = screen.getByRole('button', {name: 'Collapse'});
+    const controlsId = expandedToggle.getAttribute('aria-controls');
+    expect(controlsId).toBeTruthy();
+    const region = document.getElementById(controlsId as string);
+    expect(region).not.toBeNull();
+    expect(region).toContainElement(screen.getByTestId('region-content'));
+  });
+
   it('does not render content area when no children', () => {
     const {container} = render(<Banner status="info" title="No Children" />);
     const root = container.firstElementChild;

package/src/Banner/Banner.tsx

@@ -31,7 +31,7 @@
  * - /packages/cli/templates/blocks/components/Banner/ (showcase blocks)
  */
 
-import {useState, type ReactNode} from 'react';
+import {useId, useState, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
 import {Button} from '../Button';
@@ -387,6 +387,11 @@ export function Banner({
 }: BannerProps) {
   const [isDismissed, setIsDismissed] = useState(false);
   const [isExpanded, setIsExpanded] = useState(defaultIsExpanded);
+  // Links the expand/collapse toggle to the content region it shows/hides so
+  // assistive tech can move from the button to its controlled content
+  // (disclosure pattern). The region is conditionally rendered, so aria-controls
+  // below is set only while it's mounted to avoid a dangling reference.
+  const contentId = useId();
   const defaultIconName = defaultIconNames[status];
   const role = statusRole[status];
   const iconColor = statusIconColor[status];
@@ -477,6 +482,7 @@ export function Banner({
                 }
                 onClick={handleToggleExpand}
                 aria-expanded={isExpanded}
+                aria-controls={showContent ? contentId : undefined}
                 isIconOnly
               />
             )}
@@ -497,6 +503,7 @@ export function Banner({
       {/* Content area: collapsible card background — theme target ('banner-content') */}
       {showContent && (
         <div
+          id={contentId}
           {...mergeProps(
             themeProps('banner-content', {container, status}),
             stylex.props(styles.contentArea, isCard && styles.contentAreaCard),

package/src/Calendar/Calendar.doc.mjs

@@ -19,7 +19,7 @@ export const docs = {
       {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.'},
+      {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.'},

package/src/Calendar/Calendar.test.tsx

@@ -12,8 +12,10 @@
 import {describe, it, expect, vi} from 'vitest';
 import {act, render, screen, within} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import * as stylex from '@stylexjs/stylex';
 import {Calendar} from './Calendar';
 import type {CalendarHandle} from './Calendar';
+import {calendarStyles} from './styles';
 
 /**
  * Helper to find a day button by its day number.
@@ -71,6 +73,24 @@ describe('Calendar', () => {
     expect(screen.getByText(expectedLabel)).toBeInTheDocument();
   });
 
+  it("marks today's cell with aria-current='date'", () => {
+    render(<Calendar />);
+
+    const now = new Date();
+    const iso = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
+
+    const todayCell = document.querySelector(`button[data-date="${iso}"]`);
+    expect(todayCell).not.toBeNull();
+    expect(todayCell).toHaveAttribute('aria-current', 'date');
+
+    // Only today's cell is marked current.
+    const others = Array.from(
+      document.querySelectorAll('button[data-date]'),
+    ).filter(el => el.getAttribute('data-date') !== iso);
+    expect(others.length).toBeGreaterThan(0);
+    others.forEach(el => expect(el).not.toHaveAttribute('aria-current'));
+  });
+
   it('displays day names', () => {
     render(<Calendar />);
 
@@ -97,7 +117,11 @@ describe('Calendar', () => {
     render(<Calendar value="2026-01-15" focusDate="2026-01-01" />);
 
     const day15 = getDayButton(15);
-    expect(day15).toHaveAttribute('aria-selected', 'true');
+    // In an ARIA grid, selection state lives on the gridcell, not the button
+    // (a plain button role does not permit aria-selected).
+    const gridcell15 = day15.closest('[role="gridcell"]');
+    expect(gridcell15).toHaveAttribute('aria-selected', 'true');
+    expect(day15).not.toHaveAttribute('aria-selected');
   });
 
   it('calls onChange when date is selected', async () => {
@@ -215,6 +239,33 @@ describe('Calendar', () => {
     expect(screen.getByText(/February 2026.*March 2026/)).toBeInTheDocument();
   });
 
+  it('clamps out-of-range numberOfMonths to a single month', () => {
+    // 1000 would otherwise try to render 1000 month grids and lock the page up.
+    render(
+      <Calendar
+        numberOfMonths={1000 as unknown as 1 | 2}
+        focusDate="2026-01-01"
+      />,
+    );
+
+    // Only the focused month renders — no second month, no range separator.
+    expect(screen.getByText('January 2026')).toBeInTheDocument();
+    expect(screen.queryByText(/February 2026/)).not.toBeInTheDocument();
+  });
+
+  it('clamps numberOfMonths={0} to a single month', () => {
+    render(
+      <Calendar
+        numberOfMonths={0 as unknown as 1 | 2}
+        focusDate="2026-01-01"
+      />,
+    );
+
+    // 0 previously rendered no months at all; now falls back to one.
+    expect(screen.getByText('January 2026')).toBeInTheDocument();
+    expect(screen.getAllByRole('gridcell').length).toBeGreaterThan(0);
+  });
+
   // ─── Display Options ─────────────────────────────────────────
 
   it('shows week numbers when hasWeekNumbers is true', () => {
@@ -310,9 +361,22 @@ describe('Calendar', () => {
     const day12 = getDayButton(12);
     const day15 = getDayButton(15);
 
-    expect(day10).toHaveAttribute('aria-selected', 'true');
-    expect(day12).toHaveAttribute('aria-selected', 'true');
-    expect(day15).toHaveAttribute('aria-selected', 'true');
+    // Selection state lives on the gridcell wrapper, not the day button.
+    expect(day10.closest('[role="gridcell"]')).toHaveAttribute(
+      'aria-selected',
+      'true',
+    );
+    expect(day12.closest('[role="gridcell"]')).toHaveAttribute(
+      'aria-selected',
+      'true',
+    );
+    expect(day15.closest('[role="gridcell"]')).toHaveAttribute(
+      'aria-selected',
+      'true',
+    );
+    expect(day10).not.toHaveAttribute('aria-selected');
+    expect(day12).not.toHaveAttribute('aria-selected');
+    expect(day15).not.toHaveAttribute('aria-selected');
   });
 
   it('caps the range highlight next to a disabled mid-range day (#2715)', () => {
@@ -675,4 +739,48 @@ describe('Calendar', () => {
       }
     }
   });
+
+  // ─── RTL (#3388) ─────────────────────────────────────────────
+
+  describe('RTL month navigation', () => {
+    // jsdom does not apply compiled StyleX CSS, so the scaleX(-1) mirror
+    // itself is only observable in a browser (see the dir="rtl" Storybook
+    // story). These tests pin the structure the fix depends on: both nav
+    // chevrons render inside the navIcon wrapper that carries the
+    // ':is([dir="rtl"] *)' conditional transform.
+    it('wraps both nav chevrons in the RTL-mirroring navIcon wrapper', () => {
+      render(<Calendar focusDate="2026-01-01" />);
+
+      const {className: navIconClass} = stylex.props(calendarStyles.navIcon);
+      expect(navIconClass).toBeTruthy();
+
+      for (const name of ['Previous month', 'Next month']) {
+        const button = screen.getByRole('button', {name});
+        const wrappers = Array.from(button.querySelectorAll('span')).filter(
+          span => span.className === navIconClass,
+        );
+        expect(wrappers.length).toBe(1);
+      }
+    });
+
+    it('keeps navigation semantics unchanged under dir="rtl"', async () => {
+      const user = userEvent.setup();
+
+      render(
+        <div dir="rtl">
+          <Calendar focusDate="2026-02-01" />
+        </div>,
+      );
+
+      expect(screen.getByText('February 2026')).toBeInTheDocument();
+
+      // DOM order and handlers must not change in RTL: flexbox already
+      // places "Previous month" at the visual right; only the glyph mirrors.
+      await user.click(screen.getByRole('button', {name: 'Previous month'}));
+      expect(screen.getByText('January 2026')).toBeInTheDocument();
+
+      await user.click(screen.getByRole('button', {name: 'Next month'}));
+      expect(screen.getByText('February 2026')).toBeInTheDocument();
+    });
+  });
 });

package/src/Calendar/Calendar.tsx

@@ -203,7 +203,7 @@ export function Calendar({ref, ...props}: CalendarProps) {
     value,
     defaultValue,
     onChange,
-    numberOfMonths = 1,
+    numberOfMonths: numberOfMonthsProp = 1,
     min,
     max,
     dateConstraints,
@@ -223,6 +223,11 @@ export function Calendar({ref, ...props}: CalendarProps) {
   // DayOfWeek so all downstream date math keeps working with an index.
   const weekStartsOn = normalizeDayOfWeek(weekStartsOnProp);
 
+  // `numberOfMonths` is typed `1 | 2`; defensively clamp anything else that
+  // slips through at runtime to 1 so `Array.from({length})` can't render an
+  // absurd number of month grids (e.g. `numberOfMonths={1000}`).
+  const numberOfMonths = numberOfMonthsProp === 2 ? 2 : 1;
+
   // Today's date (memoized)
   const today = useMemo(() => plainDateToday(), []);
 
@@ -426,7 +431,14 @@ export function Calendar({ref, ...props}: CalendarProps) {
         <Button
           label="Previous month"
           variant="ghost"
-          icon={<Icon icon="chevronLeft" size="sm" color="inherit" />}
+          icon={
+            // Wrapper span (not Icon props): Icon's string mode clobbers
+            // caller classNames, so the RTL mirror must live on its own
+            // element.
+            <span {...stylex.props(calendarStyles.navIcon)}>
+              <Icon icon="chevronLeft" size="sm" color="inherit" />
+            </span>
+          }
           onClick={() => navigateMonth(-1)}
           isDisabled={!canNavigatePrevious}
           isIconOnly
@@ -439,7 +451,11 @@ export function Calendar({ref, ...props}: CalendarProps) {
         <Button
           label="Next month"
           variant="ghost"
-          icon={<Icon icon="chevronRight" size="sm" color="inherit" />}
+          icon={
+            <span {...stylex.props(calendarStyles.navIcon)}>
+              <Icon icon="chevronRight" size="sm" color="inherit" />
+            </span>
+          }
           onClick={() => navigateMonth(1)}
           isDisabled={!canNavigateNext}
           isIconOnly
@@ -912,7 +928,10 @@ function DayCell({
   });
 
   return (
-    <div role="gridcell" {...stylex.props(dayCellStyles.cell)}>
+    <div
+      role="gridcell"
+      aria-selected={state.isSelected || state.isInRange || undefined}
+      {...stylex.props(dayCellStyles.cell)}>
       {/* Range background */}
       {state.isInRange && (
         <div
@@ -952,8 +971,10 @@ function DayCell({
         type="button"
         data-date={day.iso}
         aria-label={plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY)}
-        aria-selected={state.isSelected || state.isInRange || undefined}
         aria-disabled={state.effectivelyDisabled || undefined}
+        // Mark today's cell programmatically (APG date-picker pattern), not just
+        // visually, so screen-reader users can identify the current date.
+        aria-current={state.isToday ? 'date' : undefined}
         disabled={isDisabled}
         // Initial roving tab-stop seed; useGridFocus owns it after mount.
         tabIndex={isTabbableDay ? 0 : -1}

package/src/Calendar/styles.ts

@@ -64,9 +64,19 @@ export const calendarStyles = stylex.create({
     whiteSpace: 'nowrap',
     borderWidth: 0,
   },
+  /**
+   * Wrapper for the month nav chevrons. In RTL the flex header already
+   * swaps the buttons' visual sides; the glyphs must mirror with them so
+   * "Previous month" points outward (visually right) instead of inward.
+   * Keyed on the dir attribute (dir="rtl"), same as MobileNav's drawer
+   * transform — bare CSS `direction: rtl` alone won't trigger it.
+   */
   navIcon: {
-    width: spacingVars['--spacing-4'],
-    height: spacingVars['--spacing-4'],
+    display: 'inline-flex',
+    transform: {
+      default: null,
+      ':is([dir="rtl"] *)': 'scaleX(-1)',
+    },
   },
 });
 

package/src/Card/Card.tsx

@@ -44,8 +44,10 @@ import {themeProps} from '../utils/themeProps';
  * - Non-semantic palette: `blue | cyan | gray | green | orange | pink | purple | red | teal | yellow`
  *   Each uses the corresponding `--color-background-<name>` token (20% opacity tint).
  *
- * All variants include a transparent border to prevent layout jitter
- * when switching variants. Themes can override borderWidth/borderColor.
+ * Only `default` draws a visible border. Its border width is subtracted from
+ * the padding so the total inset (border + padding) equals the padding token —
+ * keeping content geometry faithful to the spacing scale and identical to the
+ * borderless variants. Themes can override borderWidth/borderColor.
  */
 export type CardVariant =
   | 'default'
@@ -71,12 +73,18 @@ const styles = stylex.create({
     '--_card-radius': radiusVars['--radius-container'],
     borderRadius: 'var(--_card-radius)',
     overflow: 'clip',
-    borderWidth: borderVars['--border-width'],
-    borderStyle: 'solid',
-    borderColor: 'transparent',
   },
+  // The border is drawn *inside* the padding — its width is subtracted from
+  // each side — so total inset (border + padding) equals the padding token
+  // rather than exceeding it by the border width.
   withBorder: {
+    borderWidth: borderVars['--border-width'],
+    borderStyle: 'solid',
     borderColor: colorVars['--color-border-emphasized'],
+    paddingInlineStart: `calc(var(--container-padding-inline-start) - ${borderVars['--border-width']})`,
+    paddingInlineEnd: `calc(var(--container-padding-inline-end) - ${borderVars['--border-width']})`,
+    paddingBlockStart: `calc(var(--container-padding-block-start) - ${borderVars['--border-width']})`,
+    paddingBlockEnd: `calc(var(--container-padding-block-end) - ${borderVars['--border-width']})`,
   },
   // Fixed-height cards scroll content; overflow: auto also clips to border-radius
   scrollable: {
@@ -266,7 +274,6 @@ export function Card({
         stylex.props(
           styles.card,
           variantStyles[variant],
-          variant === 'default' && styles.withBorder,
           hasFixedHeight && styles.scrollable,
           dynamicStyles.sizing(
             width ?? null,
@@ -296,6 +303,9 @@ export function Card({
           !useThemeDefault &&
             effectivePadding !== 4 &&
             containerPaddingBlockEndVarStyles[effectivePadding],
+          // Applied after the container padding so the border-inset calc wins;
+          // it reads the --container-padding-* vars set above.
+          variant === 'default' && styles.withBorder,
           xstyle,
         ),
         className,