@astryxdesign/core 0.4.1 → 0.4.2-canary.356d2f9

package/dist/theme/mergeComponents.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file Component style-map merging
+ *
+ * One merge rule for component overrides, shared by every layer that composes
+ * them: `extends` inheritance, generated type-scale rules, and the on-media
+ * (`onDark`/`onLight`) surfaces. Merging is per style key, so a child that
+ * restates one property of `button.base` keeps the rest of the base's.
+ *
+ * @input two ComponentStyleMaps — the base and the overrides that win
+ * @output a merged ComponentStyleMap
+ * @position packages/core/src/theme/mergeComponents.ts
+ */
+import type { ComponentStyleMap } from './defineTheme';
+/**
+ * Deep-merge component style maps: `overrides` wins per style key, and every
+ * component and key the base declared that the overrides do not mention is
+ * carried through untouched.
+ */
+export declare function deepMergeComponents(base?: ComponentStyleMap, overrides?: ComponentStyleMap): ComponentStyleMap | undefined;
+//# sourceMappingURL=mergeComponents.d.ts.map

package/dist/theme/mergeComponents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mergeComponents.d.ts","sourceRoot":"","sources":["../../src/theme/mergeComponents.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAErD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,CAAC,EAAE,iBAAiB,EACxB,SAAS,CAAC,EAAE,iBAAiB,GAC5B,iBAAiB,GAAG,SAAS,CAiC/B"}

package/dist/theme/mergeComponents.js

@@ -0,0 +1,56 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Component style-map merging
+ *
+ * One merge rule for component overrides, shared by every layer that composes
+ * them: `extends` inheritance, generated type-scale rules, and the on-media
+ * (`onDark`/`onLight`) surfaces. Merging is per style key, so a child that
+ * restates one property of `button.base` keeps the rest of the base's.
+ *
+ * @input two ComponentStyleMaps — the base and the overrides that win
+ * @output a merged ComponentStyleMap
+ * @position packages/core/src/theme/mergeComponents.ts
+ */
+
+/**
+ * Deep-merge component style maps: `overrides` wins per style key, and every
+ * component and key the base declared that the overrides do not mention is
+ * carried through untouched.
+ */
+export function deepMergeComponents(base, overrides) {
+  if (!base && !overrides) {
+    return undefined;
+  }
+  if (!base) {
+    return overrides;
+  }
+  if (!overrides) {
+    return base;
+  }
+  const result = {};
+
+  // Start with all base entries
+  for (const [component, rules] of Object.entries(base)) {
+    result[component] = {
+      ...rules
+    };
+  }
+
+  // Merge overrides on top
+  for (const [component, rules] of Object.entries(overrides)) {
+    if (!result[component]) {
+      result[component] = {
+        ...rules
+      };
+    } else {
+      for (const [key, styles] of Object.entries(rules)) {
+        result[component][key] = {
+          ...result[component][key],
+          ...styles
+        };
+      }
+    }
+  }
+  return result;
+}

package/dist/theme/onMediaTokens.d.ts

@@ -53,6 +53,11 @@ export declare const defaultOnLightTokens: Record<string, string>;
 /**
  * Resolve on-media overrides: merge user tokens with defaults,
  * pass through component overrides.
+ *
+ * `base` is the already-resolved surface of a theme being extended. It sits
+ * between the defaults and this theme's own input, so a child theme inherits
+ * the surface customizations of the theme it extends instead of silently
+ * reverting them to the defaults.
  */
-export declare function resolveOnMedia(surface: 'dark' | 'light', input?: OnMediaOverrides): ResolvedOnMedia;
+export declare function resolveOnMedia(surface: 'dark' | 'light', input?: OnMediaOverrides, base?: ResolvedOnMedia): ResolvedOnMedia;
 //# sourceMappingURL=onMediaTokens.d.ts.map

package/dist/theme/onMediaTokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"onMediaTokens.d.ts","sourceRoot":"","sources":["../../src/theme/onMediaTokens.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAE,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAC7C,yDAAyD;IACzD,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,yDAAyD;IACzD,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAStD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CASvD,CAAC;AAYF;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,GAAG,OAAO,EACzB,KAAK,CAAC,EAAE,gBAAgB,GACvB,eAAe,CAkBjB"}
+{"version":3,"file":"onMediaTokens.d.ts","sourceRoot":"","sources":["../../src/theme/onMediaTokens.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAE,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAGjE;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAC7C,yDAAyD;IACzD,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,yDAAyD;IACzD,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAStD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CASvD,CAAC;AAYF;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,GAAG,OAAO,EACzB,KAAK,CAAC,EAAE,gBAAgB,EACxB,IAAI,CAAC,EAAE,eAAe,GACrB,eAAe,CAkBjB"}

package/dist/theme/onMediaTokens.js

@@ -20,6 +20,8 @@
  * `onDark`/`onLight` fields in `defineTheme()`.
  */
 
+import { deepMergeComponents } from "./mergeComponents.js";
+
 /**
  * On-media theme overrides — same shape as the main theme but scoped
  * to a surface luminance context.
@@ -71,11 +73,17 @@ function resolveValue(value) {
 /**
  * Resolve on-media overrides: merge user tokens with defaults,
  * pass through component overrides.
+ *
+ * `base` is the already-resolved surface of a theme being extended. It sits
+ * between the defaults and this theme's own input, so a child theme inherits
+ * the surface customizations of the theme it extends instead of silently
+ * reverting them to the defaults.
  */
-export function resolveOnMedia(surface, input) {
+export function resolveOnMedia(surface, input, base) {
   const defaults = surface === 'dark' ? defaultOnDarkTokens : defaultOnLightTokens;
   const tokens = {
-    ...defaults
+    ...defaults,
+    ...base?.tokens
   };
   if (input?.tokens) {
     for (const [key, value] of Object.entries(input.tokens)) {
@@ -86,6 +94,6 @@ export function resolveOnMedia(surface, input) {
   }
   return {
     tokens,
-    components: input?.components
+    components: deepMergeComponents(base?.components, input?.components)
   };
 }

package/dist/theme/tokens.stylex.d.ts

@@ -6,7 +6,9 @@
  * - *Vars: CSS custom properties that themes can override via createTheme
  *
  * SYNC: When modified, run `node scripts/generate-token-docs.mjs` to update docs.
- * CI checks for drift via --check flag.
+ * CI checks for drift via --check flag. Adding or removing a token FAMILY (a
+ * whole `*Defaults` group) also means updating:
+ * - /packages/cli/assets/theme.template.ts (its inventory of what exists)
  *
  * Domain tokens (syntax highlighting, data visualization) live separately in
  * /packages/core/src/theme/domainTokens/ — they're tree-shaken from core components.

package/dist/theme/tokens.stylex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.stylex.d.ts","sourceRoot":"","sources":["../../src/theme/tokens.stylex.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAM3C,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyHhB,CAAC;AAEX,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAAmC,CAAC;AAM1D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;CAgBlB,CAAC;AAEX,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;WAAqC,CAAC;AAM9D,eAAO,MAAM,YAAY;;;;CAIf,CAAC;AAEX,eAAO,MAAM,QAAQ;;;;WAAkC,CAAC;AAMxD,eAAO,MAAM,cAAc;;CAEjB,CAAC;AAEX,eAAO,MAAM,UAAU;;WAAoC,CAAC;AAE5D,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,cAAc,CAAC;AAWxD,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,eAAO,MAAM,SAAS;;;;;WAAmC,CAAC;AAM1D,eAAO,MAAM,cAAc;;;;;;;;CAWjB,CAAC;AAEX,eAAO,MAAM,UAAU;;;;;;;;WAAoC,CAAC;AAQ5D,eAAO,MAAM,cAAc;;;;;;;;;CAejB,CAAC;AAEX,eAAO,MAAM,UAAU;;;;;;;;;WAAoC,CAAC;AAU5D,eAAO,MAAM,gBAAgB;;;;;;;;;;CAUnB,CAAC;AAEX,eAAO,MAAM,YAAY;;;;;;;;;;WAAsC,CAAC;AAEhE,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAM5D,eAAO,MAAM,YAAY;;CAEf,CAAC;AAEX,eAAO,MAAM,QAAQ;;WAAkC,CAAC;AAExD,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,YAAY,CAAC;AAKpD,eAAO,MAAM,kBAAkB;;;;CAMrB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;WAAwC,CAAC;AAMpE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;CAcnB,CAAC;AAEX,eAAO,MAAM,YAAY;;;;;;;;;;;;;WAAsC,CAAC;AAMhE,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;;WAAwC,CAAC;AAMpE,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,aAAa,CAAC;AACtD,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,eAAe,CAAC;AAC1D,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,YAAY,CAAC;AACpD,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,cAAc,CAAC;AACxD,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,cAAc,CAAC;AACxD,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAC5D,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAehE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0DpB,CAAC;AAEX,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAAuC,CAAC;AAElE,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,iBAAiB,CAAC"}
+{"version":3,"file":"tokens.stylex.d.ts","sourceRoot":"","sources":["../../src/theme/tokens.stylex.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAM3C,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyHhB,CAAC;AAEX,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAAmC,CAAC;AAM1D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;CAgBlB,CAAC;AAEX,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;WAAqC,CAAC;AAM9D,eAAO,MAAM,YAAY;;;;CAIf,CAAC;AAEX,eAAO,MAAM,QAAQ;;;;WAAkC,CAAC;AAMxD,eAAO,MAAM,cAAc;;CAEjB,CAAC;AAEX,eAAO,MAAM,UAAU;;WAAoC,CAAC;AAE5D,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,cAAc,CAAC;AAWxD,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,eAAO,MAAM,SAAS;;;;;WAAmC,CAAC;AAM1D,eAAO,MAAM,cAAc;;;;;;;;CAWjB,CAAC;AAEX,eAAO,MAAM,UAAU;;;;;;;;WAAoC,CAAC;AAQ5D,eAAO,MAAM,cAAc;;;;;;;;;CAejB,CAAC;AAEX,eAAO,MAAM,UAAU;;;;;;;;;WAAoC,CAAC;AAU5D,eAAO,MAAM,gBAAgB;;;;;;;;;;CAUnB,CAAC;AAEX,eAAO,MAAM,YAAY;;;;;;;;;;WAAsC,CAAC;AAEhE,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAM5D,eAAO,MAAM,YAAY;;CAEf,CAAC;AAEX,eAAO,MAAM,QAAQ;;WAAkC,CAAC;AAExD,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,YAAY,CAAC;AAKpD,eAAO,MAAM,kBAAkB;;;;CAMrB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;WAAwC,CAAC;AAMpE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;CAcnB,CAAC;AAEX,eAAO,MAAM,YAAY;;;;;;;;;;;;;WAAsC,CAAC;AAMhE,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;;WAAwC,CAAC;AAMpE,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,aAAa,CAAC;AACtD,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,eAAe,CAAC;AAC1D,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,YAAY,CAAC;AACpD,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,cAAc,CAAC;AACxD,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,cAAc,CAAC;AACxD,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAC5D,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAehE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0DpB,CAAC;AAEX,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAAuC,CAAC;AAElE,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,iBAAiB,CAAC"}

package/dist/theme/tokens.stylex.js

@@ -8,7 +8,9 @@
  * - *Vars: CSS custom properties that themes can override via createTheme
  *
  * SYNC: When modified, run `node scripts/generate-token-docs.mjs` to update docs.
- * CI checks for drift via --check flag.
+ * CI checks for drift via --check flag. Adding or removing a token FAMILY (a
+ * whole `*Defaults` group) also means updating:
+ * - /packages/cli/assets/theme.template.ts (its inventory of what exists)
  *
  * Domain tokens (syntax highlighting, data visualization) live separately in
  * /packages/core/src/theme/domainTokens/ — they're tree-shaken from core components.

package/locales/en.json

@@ -419,6 +419,66 @@
     "defaultMessage": "Next",
     "description": "Screen-reader-only label on the right-arrow button in a Lightbox (navigates to next media item). Pairs with `lightbox.previous`."
   },
+  "@astryx.listInput.emptyTitle": {
+    "defaultMessage": "No {itemName}s yet",
+    "description": "EmptyState title shown inside a lab ListInput when its collection has no records. `{itemName}` is the consumer's singular noun for one record (e.g. \"guest\"); the source appends a literal \"s\" to pluralize it, which only works for regular English plurals. If your language cannot pluralize an interpolated noun this way, rephrase around `{itemName}` instead (e.g. \"No {itemName} added yet\")."
+  },
+  "@astryx.listInput.emptyDescription": {
+    "defaultMessage": "Add a {itemName} to get started.",
+    "description": "EmptyState supporting text shown inside a lab ListInput when its collection has no records. `{itemName}` is the consumer's singular noun for one record (e.g. \"guest\")."
+  },
+  "@astryx.listInput.addItem": {
+    "defaultMessage": "Add {itemName}",
+    "description": "Accessible label on the button that appends a new record to a lab ListInput. `{itemName}` is the consumer's singular noun for one record (e.g. \"guest\")."
+  },
+  "@astryx.listInput.removeItem": {
+    "defaultMessage": "Remove {itemName} {position, number}",
+    "description": "Accessible label and tooltip on the button that deletes one record from a lab ListInput. `{itemName}` is the consumer's singular noun for one record; `{position}` is its 1-based row number (e.g. \"Remove guest 2\")."
+  },
+  "@astryx.listInput.reorderItem": {
+    "defaultMessage": "Reorder {itemName} {position, number}",
+    "description": "Accessible label on the drag-handle button that reorders one record in a lab ListInput. `{itemName}` is the consumer's singular noun for one record; `{position}` is its 1-based row number (e.g. \"Reorder guest 2\")."
+  },
+  "@astryx.listInput.fieldLabelWithPosition": {
+    "defaultMessage": "{header}, {itemName} {position, number} of {total, number}",
+    "description": "Accessible name for a field inside a lab ListInput row after the first row, disambiguating repeated column labels. `{header}` is the column's own label (e.g. \"Name\"); `{itemName}` is the consumer's singular noun for one record; `{position}`/`{total}` are the row's 1-based index and the total row count (e.g. \"Name, guest 2 of 3\")."
+  },
+  "@astryx.listInput.reorderInstructions": {
+    "defaultMessage": "Use Arrow Up or Arrow Down to move this item one position. Press Space or Enter to pick it up for extended keyboard reordering.",
+    "description": "Visually-hidden instructions describing how to use a lab ListInput row's keyboard reorder handle, referenced via aria-describedby from every reorder button."
+  },
+  "@astryx.listInput.announceAdded": {
+    "defaultMessage": "Added {itemName} {position, number}.",
+    "description": "Screen-reader-only live announcement after a new record is appended to a lab ListInput. `{itemName}` is the consumer's singular noun for one record; `{position}` is the new record's 1-based row number."
+  },
+  "@astryx.listInput.announceRemoved": {
+    "defaultMessage": "Removed {itemName} {position, number}.",
+    "description": "Screen-reader-only live announcement after a record is deleted from a lab ListInput. `{itemName}` is the consumer's singular noun for one record; `{position}` is the removed record's former 1-based row number."
+  },
+  "@astryx.listInput.announceGrabbed": {
+    "defaultMessage": "{itemName} {position, number} grabbed. Use arrow keys to move, Space or Enter to drop, and Escape to cancel.",
+    "description": "Screen-reader-only live announcement when a lab ListInput record's keyboard reorder handle enters extended \"lift\" mode. `{itemName}` is the consumer's singular noun for one record; `{position}` is its 1-based row number."
+  },
+  "@astryx.listInput.announceMovedToPosition": {
+    "defaultMessage": "{itemName} moved to position {position, number} of {total, number}.",
+    "description": "Screen-reader-only live announcement each time a lab ListInput record's reorder position changes (arrow-key step, keyboard lift-mode preview, or pointer drag). `{itemName}` is the consumer's singular noun for one record; `{position}`/`{total}` are the record's new 1-based position and the total row count."
+  },
+  "@astryx.listInput.announceReorderCancelled": {
+    "defaultMessage": "Reordering cancelled.",
+    "description": "Screen-reader-only live announcement when a lab ListInput reorder in progress is cancelled (Escape key, blur, or the collection becoming disabled/loading mid-drag)."
+  },
+  "@astryx.listInput.announceReturnedToPosition": {
+    "defaultMessage": "{itemName} returned to position {position, number}.",
+    "description": "Screen-reader-only live announcement when a lab ListInput reorder is committed without the record's position actually changing. `{itemName}` is the consumer's singular noun for one record; `{position}` is its unchanged 1-based row number."
+  },
+  "@astryx.listInput.announceDropped": {
+    "defaultMessage": "{itemName} dropped at position {position, number} of {total, number}.",
+    "description": "Screen-reader-only live announcement when a lab ListInput reorder is committed with the record's position actually changing. `{itemName}` is the consumer's singular noun for one record; `{position}`/`{total}` are its new 1-based position and the total row count."
+  },
+  "@astryx.listInput.announceAlreadyAtBoundary": {
+    "defaultMessage": "This {itemName} is already {boundary, select, first {first} last {last} other {}}.",
+    "description": "Screen-reader-only live announcement when an arrow-key reorder attempt has no effect because the record is already at that end of the list. `{itemName}` is the consumer's singular noun for one record; `{boundary}` is always exactly \"first\" or \"last\"."
+  },
   "@astryx.markdown.taskList": {
     "defaultMessage": "Task list",
     "description": "Screen-reader-only accessible name for a GitHub-flavored Markdown task list (rendered from `- [ ] item` / `- [x] done` syntax)."
@@ -643,6 +703,14 @@
     "defaultMessage": "Invalid date",
     "description": "Screen-reader-only live-region alert in DateInput / DateTimeInput when the typed date cannot be parsed. The field silently reverts on blur, so this is the only rejection feedback a screen-reader user gets."
   },
+  "@astryx.dateTimeInput.timeHint12h": {
+    "defaultMessage": "e.g., 2:30 PM",
+    "description": "Placeholder hint shown in the DateTimeInput time field when focused and empty with 12-hour format. Gives an example of expected input format."
+  },
+  "@astryx.dateTimeInput.timeHint24h": {
+    "defaultMessage": "e.g., 14:30",
+    "description": "Placeholder hint shown in the DateTimeInput time field when focused and empty with 24-hour format. Gives an example of expected input format."
+  },
   "@astryx.dateTimeInput.timeSuffix": {
     "defaultMessage": "{label} time",
     "description": "Screen-reader-only accessible name for the time-of-day slot in a DateTimeInput. Example: `Start date time`; reorder freely (e.g. \"time of {label}\")."
@@ -935,6 +1003,10 @@
     "defaultMessage": "Collapse {label}",
     "description": "Screen-reader-only label on the same chevron when the group is expanded. Example: `Collapse Settings`. Pairs with `sideNavItem.expand`."
   },
+  "@astryx.sideNavItem.submenuLabel": {
+    "defaultMessage": "{label} submenu",
+    "description": "Accessible name for the flyout dialog that opens from a collapsed (icon-only) SideNav item to show its sub-items. {label} is the parent item's label. Example: `Settings submenu`."
+  },
   "@astryx.tableFiltering.filterByColumn": {
     "defaultMessage": "Filter {header}",
     "description": "Triple-use string on per-column filter controls: visible label, placeholder, AND aria label. `{header}` is the column header — example: `Filter Name`. Keep short."
@@ -1050,5 +1122,17 @@
   "@astryx.token.remove": {
     "defaultMessage": "Remove {label}",
     "description": "Screen-reader-only label on the \"×\" on an individual Token/chip. Example: `Remove John Smith`, `Remove Active`. Imperative verb."
+  },
+  "@astryx.commandPalette.footer.navigate": {
+    "defaultMessage": "Navigate",
+    "description": "Keyboard hint in the CommandPalette footer, paired with up/down arrow key icons. Tells users arrow keys move between items."
+  },
+  "@astryx.commandPalette.footer.select": {
+    "defaultMessage": "Select",
+    "description": "Keyboard hint in the CommandPalette footer, paired with the Enter key icon. Tells users Enter activates the highlighted item."
+  },
+  "@astryx.commandPalette.footer.close": {
+    "defaultMessage": "Close",
+    "description": "Keyboard hint in the CommandPalette footer, paired with the Escape key icon. Tells users Escape dismisses the palette."
   }
 }

package/locales/pseudo.json

@@ -314,6 +314,51 @@
   "@astryx.lightbox.next": {
     "defaultMessage": "⟦Ñéẋţ⟧"
   },
+  "@astryx.listInput.emptyTitle": {
+    "defaultMessage": "⟦Ñó {itemName}š ýéţ⟧"
+  },
+  "@astryx.listInput.emptyDescription": {
+    "defaultMessage": "⟦Àðð à {itemName} ţó ĝéţ šţàřţéð.⟧"
+  },
+  "@astryx.listInput.addItem": {
+    "defaultMessage": "⟦Àðð {itemName}⟧"
+  },
+  "@astryx.listInput.removeItem": {
+    "defaultMessage": "⟦Řéɱóṽé {itemName} {position, number}⟧"
+  },
+  "@astryx.listInput.reorderItem": {
+    "defaultMessage": "⟦Řéóřðéř {itemName} {position, number}⟧"
+  },
+  "@astryx.listInput.fieldLabelWithPosition": {
+    "defaultMessage": "⟦{header}, {itemName} {position, number} óƒ {total, number}⟧"
+  },
+  "@astryx.listInput.reorderInstructions": {
+    "defaultMessage": "⟦Úšé Àřřóŵ Úþ óř Àřřóŵ Ðóŵñ ţó ɱóṽé ţĥíš íţéɱ óñé þóšíţíóñ. Þřéšš Šþàçé óř Éñţéř ţó þíçķ íţ úþ ƒóř éẋţéñðéð ķéýƀóàřð řéóřðéříñĝ.⟧"
+  },
+  "@astryx.listInput.announceAdded": {
+    "defaultMessage": "⟦Àððéð {itemName} {position, number}.⟧"
+  },
+  "@astryx.listInput.announceRemoved": {
+    "defaultMessage": "⟦Řéɱóṽéð {itemName} {position, number}.⟧"
+  },
+  "@astryx.listInput.announceGrabbed": {
+    "defaultMessage": "⟦{itemName} {position, number} ĝřàƀƀéð. Úšé àřřóŵ ķéýš ţó ɱóṽé, Šþàçé óř Éñţéř ţó ðřóþ, àñð Éšçàþé ţó çàñçéł.⟧"
+  },
+  "@astryx.listInput.announceMovedToPosition": {
+    "defaultMessage": "⟦{itemName} ɱóṽéð ţó þóšíţíóñ {position, number} óƒ {total, number}.⟧"
+  },
+  "@astryx.listInput.announceReorderCancelled": {
+    "defaultMessage": "⟦Řéóřðéříñĝ çàñçéłłéð.⟧"
+  },
+  "@astryx.listInput.announceReturnedToPosition": {
+    "defaultMessage": "⟦{itemName} řéţúřñéð ţó þóšíţíóñ {position, number}.⟧"
+  },
+  "@astryx.listInput.announceDropped": {
+    "defaultMessage": "⟦{itemName} ðřóþþéð àţ þóšíţíóñ {position, number} óƒ {total, number}.⟧"
+  },
+  "@astryx.listInput.announceAlreadyAtBoundary": {
+    "defaultMessage": "⟦Ţĥíš {itemName} íš àłřéàðý {boundary, select, first {first} last {last} other {}}.⟧"
+  },
   "@astryx.markdown.taskList": {
     "defaultMessage": "⟦Ţàšķ łíšţ⟧"
   },
@@ -482,6 +527,12 @@
   "@astryx.dateInput.invalidDate": {
     "defaultMessage": "⟦Íñṽàłíð ðàţé⟧"
   },
+  "@astryx.dateTimeInput.timeHint12h": {
+    "defaultMessage": "⟦é.ĝ., 2:30 ÞṀ⟧"
+  },
+  "@astryx.dateTimeInput.timeHint24h": {
+    "defaultMessage": "⟦é.ĝ., 14:30⟧"
+  },
   "@astryx.dateTimeInput.timeSuffix": {
     "defaultMessage": "⟦{label} ţíɱé⟧"
   },
@@ -701,6 +752,9 @@
   "@astryx.sideNavItem.collapse": {
     "defaultMessage": "⟦Çółłàþšé {label}⟧"
   },
+  "@astryx.sideNavItem.submenuLabel": {
+    "defaultMessage": "⟦{label} šúƀɱéñú⟧"
+  },
   "@astryx.tableFiltering.filterByColumn": {
     "defaultMessage": "⟦Ƒíłţéř {header}⟧"
   },
@@ -787,5 +841,14 @@
   },
   "@astryx.token.remove": {
     "defaultMessage": "⟦Řéɱóṽé {label}⟧"
+  },
+  "@astryx.commandPalette.footer.navigate": {
+    "defaultMessage": "⟦Ñàṽíĝàţé⟧"
+  },
+  "@astryx.commandPalette.footer.select": {
+    "defaultMessage": "⟦Šéłéçţ⟧"
+  },
+  "@astryx.commandPalette.footer.close": {
+    "defaultMessage": "⟦Çłóšé⟧"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.4.1",
+  "version": "0.4.2-canary.356d2f9",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -654,6 +654,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/cli": "0.4.2-canary.356d2f9",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",
@@ -662,8 +663,7 @@
     "@testing-library/dom": "^10.0.0",
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
-    "rimraf": "^6.0.1",
-    "@astryxdesign/cli": "0.4.1"
+    "rimraf": "^6.0.1"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/Avatar/Avatar.doc.mjs

@@ -33,6 +33,9 @@ export const docs = {
       {className: 'astryx-avatar-status-dot', visualProps: ['variant']},
       {className: 'astryx-avatar-status-dot-glyph', visualProps: ['shape']},
     ],
+    vars: [
+      {name: '--_avatar-group-overlap', description: 'Negative inline offset applied to every avatar after the first when avatars are stacked in an AvatarGroup. Set from the group size; a more negative value tightens the stack.', default: 'set at runtime from the group avatar size (px)', private: true},
+    ],
   },
   description: 'Displays a user avatar with image, initials fallback, and optional status indicator.',
   props: [
@@ -59,7 +62,7 @@ export const docs = {
     {
       name: 'size',
       type: "'xsm' | 'sm' | 'md' | 'lg' | 'xl' | number",
-      description: "Avatar size. Use a named size ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or a numeric pixel value. Avatar shares Icon's abbreviated scale, but its tiers are larger because avatars align with media rather than glyphs.",
+      description: "Avatar size. Use a named size ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or a numeric pixel value. Avatar shares Icon's abbreviated scale, but its tiers are larger because avatars align with media rather than glyphs. Inside an AvatarGroup the group's size wins and this prop is ignored.",
       default: "'md'",
     },
     {
@@ -151,7 +154,7 @@ export const docsDense = {
     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 ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or numeric px.",
+    size: "avatar size. Named ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or numeric px. An AvatarGroup's size overrides it.",
     status:
       'corner content for status indicators; its `label` is composed into the avatar accessible name ("Jane Doe, Online")',
     tooltip:

package/src/Avatar/Avatar.test.tsx

@@ -65,6 +65,27 @@ describe('Avatar', () => {
     expect(icon?.querySelector('svg')).not.toBeNull();
   });
 
+  it('puts the avatar box on the element that carries the theme target', () => {
+    // T7: `.astryx-avatar` documents a `size` visual prop, so the width and
+    // height that prop selects on must live on the targeted element — a theme
+    // rule that resizes the target has to resize the whole avatar, not leave a
+    // fixed-size circle inside a grown box.
+    render(<Avatar name="Ada Lovelace" size="lg" data-testid="a" />);
+    const root = screen.getByTestId('a');
+    expect(root.className).toContain('astryx-avatar');
+    const rootStyle = root.getAttribute('style') ?? '';
+    expect(rootStyle).toContain('48px');
+
+    const content = root.firstElementChild as HTMLElement;
+    expect(content.getAttribute('style') ?? '').not.toContain('48px');
+  });
+
+  it('keeps the box on the root for an interactive avatar too', () => {
+    render(<Avatar name="Ada" size="lg" href="/ada" />);
+    const link = screen.getByRole('link', {name: 'Ada'});
+    expect(link.getAttribute('style') ?? '').toContain('48px');
+  });
+
   it('does not split an emoji surrogate pair when generating initials', () => {
     render(<Avatar name="😀 Ada" data-testid="avatar" />);
     expect(screen.getByTestId('avatar')).toHaveTextContent('😀A');
@@ -184,6 +205,36 @@ describe('Avatar', () => {
     });
   });
 
+  describe('a whitespace-only name carries no identity', () => {
+    it('falls through to the default icon instead of an empty plate', () => {
+      render(<Avatar name="   " data-testid="a" />);
+      const el = screen.getByTestId('a');
+      expect(el.querySelector('svg')).not.toBeNull();
+      expect(el).toHaveTextContent('');
+    });
+
+    it('is decorative rather than a role="img" with a blank name', () => {
+      render(<Avatar name="   " data-testid="a" />);
+      const el = screen.getByTestId('a');
+      expect(el).toHaveAttribute('aria-hidden', 'true');
+      expect(el).not.toHaveAttribute('aria-label');
+    });
+
+    it('keeps a meaningful alt as the accessible name and still shows the icon', () => {
+      render(<Avatar name="   " alt="Profile photo" data-testid="a" />);
+      const el = screen.getByRole('img', {name: 'Profile photo'});
+      expect(el).toBe(screen.getByTestId('a'));
+      expect(el.querySelector('svg')).not.toBeNull();
+    });
+
+    it('treats a whitespace-only alt the same way', () => {
+      render(<Avatar alt="  " name="Ada Lovelace" data-testid="a" />);
+      expect(
+        screen.getByRole('img', {name: 'Ada Lovelace'}),
+      ).toBeInTheDocument();
+    });
+  });
+
   it('retries a new fallbackSrc after a previous fallbackSrc failed to load', () => {
     const {rerender} = render(
       <Avatar name="Ada" fallbackSrc="https://example.com/broken.jpg" />,

package/src/Avatar/Avatar.tsx

@@ -33,6 +33,7 @@ import {mergeProps, mergeRefs} from '../utils';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useTooltip} from '../Tooltip/useTooltip';
+import {useDevWarning} from '../hooks/useDevWarning';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
 import {useTranslator} from '../i18n';
@@ -112,16 +113,17 @@ const styles = stylex.create({
     position: 'relative',
     display: 'inline-flex',
     flexShrink: 0,
-    // The wrapper is not clipped (so the status dot can overflow), so it must be
-    // rounded itself: a theme can set a background on the `.astryx-avatar`
-    // wrapper, and an unrounded wrapper would show that fill as square corners
-    // behind the circular content.
+    // The wrapper carries the avatar's box as well as its radius, so a theme
+    // rule on the `.astryx-avatar` target reaches both: the size the `size`
+    // visual prop selects on is set here, and the content below fills it.
     borderRadius: radiusVars['--radius-full'],
   },
   content: {
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'center',
+    width: '100%',
+    height: '100%',
     borderRadius: radiusVars['--radius-full'],
     overflow: 'hidden',
     userSelect: 'none',
@@ -251,6 +253,9 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
   /**
    * The size of the avatar. A named size (`xsm` 20px, `sm` 24px, `md` 36px,
    * `lg` 48px, `xl` 128px) or a specific pixel value.
+   *
+   * Inside an `AvatarGroup` the group's `size` wins: a group sizes its members
+   * uniformly, so this prop is ignored there.
    * @default 'md'
    */
   size?: AvatarSize;
@@ -397,7 +402,7 @@ function DefaultIcon({size}: {size: number}) {
  * ```
  * <Avatar src="/user.jpg" name="John Doe" />
  * <Avatar name="Jane Smith" size="xl" />
- * <Avatar src="/user.jpg" status={<OnlineIndicator />} />
+ * <Avatar src="/user.jpg" status={<AvatarStatusDot variant="success" label="Online" />} />
  * <Avatar name="jsmith" tooltip="Jane Smith, Staff Engineer" />
  * <Avatar name="Jane" tooltip={false} />
  * <Avatar src="/user.jpg" name="John Doe" href="/users/john" />
@@ -434,8 +439,13 @@ export function Avatar({
   const showImage = src && erroredSrc !== src;
   const showFallbackImage =
     !showImage && fallbackSrc && erroredFallbackSrc !== fallbackSrc;
-  const showInitials = !showImage && !showFallbackImage && name;
-  const showIcon = !showImage && !showFallbackImage && !name;
+  // A whitespace-only string carries no identity. Without this it produces no
+  // initials (getInitials trims to nothing) and no default icon (a space is
+  // truthy), leaving an empty plate behind a blank accessible name.
+  const meaningfulName = name?.trim() ? name : undefined;
+  const meaningfulAlt = alt?.trim() ? alt : undefined;
+  const showInitials = !showImage && !showFallbackImage && meaningfulName;
+  const showIcon = !showImage && !showFallbackImage && !meaningfulName;
 
   // A meaningful accessible name comes from `alt`/`name`, composed with the
   // status element's `label` when one is present ("Jane Doe, Online") — the
@@ -446,7 +456,7 @@ export function Avatar({
   // it as `presentation`/`aria-hidden` rather than announcing a meaningless
   // generic "Avatar" (obs-9).
   const t = useTranslator();
-  const nameLabel = alt || name;
+  const nameLabel = meaningfulAlt || meaningfulName;
   const statusLabel = getStatusLabel(status);
   const accessibleName =
     nameLabel && statusLabel
@@ -471,7 +481,7 @@ export function Avatar({
       ? undefined
       : typeof tooltip === 'string'
         ? tooltip
-        : name;
+        : meaningfulName;
   const trimmedTooltip = tooltipContent?.trim();
   const showTooltip = trimmedTooltip != null && trimmedTooltip !== '';
   // Whether the tooltip text is a consumer-authored override (a custom string)
@@ -513,20 +523,19 @@ export function Avatar({
   const LinkComponent = useLinkComponent(as);
 
   // An interactive control with no accessible name is an unacceptable control
-  // name. Warn in the same client-safe way sibling components do (Field,
-  // Timestamp, Popover) — a plain `console.warn`, never gated on `process.env`
-  // (which is not available on the client in this codebase).
-  if (isInteractive && !accessibleName) {
-    console.warn(
-      'Avatar: an interactive avatar (with `href` or `onClick`) needs a ' +
-        'meaningful accessible name. Pass `alt` or `name`.',
-    );
-  }
+  // name. `useDevWarning` is the shared guardrail: it warns once per mount
+  // rather than on every render, and compiles out of production builds.
+  useDevWarning(
+    'Avatar',
+    'an interactive avatar (with `href` or `onClick`) needs a meaningful ' +
+      'accessible name. Pass `alt` or `name`.',
+    isInteractive && !accessibleName,
+  );
 
   // The inner visuals are identical across the static and interactive variants.
   const visualContent = (
     <>
-      <div {...stylex.props(styles.content, dynamicStyles.size(numericSize))}>
+      <div {...stylex.props(styles.content)}>
         {showImage && (
           <img
             src={src}
@@ -552,7 +561,7 @@ export function Avatar({
                 dynamicStyles.fontSize(numericSize),
               ),
             )}>
-            {getInitials(name)}
+            {getInitials(meaningfulName)}
           </div>
         )}
         {showIcon && (
@@ -585,6 +594,7 @@ export function Avatar({
     themeProps('avatar', {size: resolvedSize}),
     focusOutlineProps.focusVisible(
       styles.wrapper,
+      dynamicStyles.size(numericSize),
       isInteractive && styles.interactive,
       avatarGroup && groupStyles.ring,
       avatarGroup && groupStyles.overlap,

package/src/AvatarGroup/AvatarGroup.doc.mjs

@@ -25,7 +25,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-avatar-group', visualProps: ['size']},
-      {className: 'astryx-avatar-group-overflow'},
+      {className: 'astryx-avatar-group-overflow', visualProps: ['size']},
     ],
   },
   description: 'Stacked avatar display with overlapping layout and optional overflow indicator. Children are Avatar elements.',