@astryxdesign/core 0.3.0 → 0.4.0-canary.3112e99

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,gBAAgB,EAChB,wBAAwB,EACxB,8BAA8B,EAC9B,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAC,gBAAgB,EAAC,MAAM,aAAa,CAAC;AAElD,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,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAC5D,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,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,SAAS,EACT,WAAW,EACX,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,YAAY,EAAC,IAAI,EAAC,MAAM,SAAS,CAAC;AAElC,OAAO,EAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,gBAAgB,EAAC,MAAM,cAAc,CAAC;AAE3E,OAAO,EAAC,SAAS,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,gBAAgB,EAChB,wBAAwB,EACxB,8BAA8B,EAC9B,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAC,gBAAgB,EAAC,MAAM,aAAa,CAAC;AAElD,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,eAAe,EAAC,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAC5D,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,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,SAAS,EACT,WAAW,EACX,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,YAAY,EAAC,IAAI,EAAC,MAAM,SAAS,CAAC;AAElC,OAAO,EAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,gBAAgB,EAAC,MAAM,cAAc,CAAC;AAE3E,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAItC,OAAO,EAAC,kBAAkB,EAAE,iBAAiB,EAAC,MAAM,uBAAuB,CAAC"}

package/dist/utils/index.js

@@ -14,6 +14,7 @@ export { parseStyleKey } from "./parseStyleKey.js";
 export { getKey } from "./getKey.js";
 export { mergeProps } from "./mergeProps.js";
 export { mergeRefs } from "./mergeRefs.js";
+export { isFocusDetached } from "./focusReturn.js";
 export { composeEventHandlers } from "./composeEventHandlers.js";
 export { themeProps, themeDataAttributes } from "./themeProps.js";
 export { groupItems, getItemGroup } from "./groupItems.js";
@@ -22,4 +23,8 @@ export { isRenderable } from "./isRenderable.js";
 export { getInputARIA } from "./inputAria.js";
 export { parseHex, parseRgb, parseColor, formatHex, formatColor, toGLFloats } from "./color.js";
 export { devWarn, devError, warnOnce, formatDevMessage } from "./devWarning.js";
-export { rtlStyles } from "./rtlStyles.js";
+export { rtlStyles } from "./rtlStyles.js";
+
+// The shared focus ring, exported for @astryxdesign/lab — same reason
+// rtlStyles is: a style that must be identical across packages, not copied.
+export { focusOutlineStyles, focusOutlineProps } from "./focusOutline.stylex.js";

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

@@ -1 +1 @@
-{"version":3,"file":"mergeRefs.d.ts","sourceRoot":"","sources":["../../src/utils/mergeRefs.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,GAAG,EAAE,WAAW,EAAC,MAAM,OAAO,CAAC;AAE5C,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,CAmB5E"}
+{"version":3,"file":"mergeRefs.d.ts","sourceRoot":"","sources":["../../src/utils/mergeRefs.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,GAAG,EAAE,WAAW,EAAC,MAAM,OAAO,CAAC;AAE5C,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,CAyB5E"}

package/dist/utils/mergeRefs.js

@@ -14,14 +14,16 @@ export function mergeRefs(...refs) {
     for (const ref of refs) {
       if (typeof ref === 'function') {
         const cleanup = ref(value);
-        if (typeof cleanup === 'function') {
-          cleanups.push(cleanup);
-        }
+        cleanups.push(typeof cleanup === 'function' ? cleanup : () => ref(null));
       } else if (ref != null) {
-        ref.current = value;
+        const mutableRef = ref;
+        mutableRef.current = value;
+        cleanups.push(() => {
+          mutableRef.current = null;
+        });
       }
     }
-    if (cleanups.length > 0) {
+    if (value != null && cleanups.length > 0) {
       return () => {
         for (const cleanup of cleanups) {
           cleanup();

package/dist/utils/rtlStyles.d.ts

@@ -2,8 +2,8 @@
  * @file rtlStyles.ts
  * @input None
  * @output Shared StyleX style that horizontally mirrors an element under RTL
- * @position Core utility; applied to directional-icon wrappers in Calendar,
- *   Lightbox, and the Table expand/disclosure plugins
+ * @position Core utility; applied to directional icons in Calendar, Lightbox,
+ *   Pagination, Carousel and the Table expand/disclosure plugins
  *
  * `mirror` flips its element on the horizontal axis only when an ancestor
  * carries `dir="rtl"`. Using `scaleX(-1)` (not `scale(-1, -1)`) keeps the

package/dist/utils/rtlStyles.js

@@ -4,8 +4,8 @@
  * @file rtlStyles.ts
  * @input None
  * @output Shared StyleX style that horizontally mirrors an element under RTL
- * @position Core utility; applied to directional-icon wrappers in Calendar,
- *   Lightbox, and the Table expand/disclosure plugins
+ * @position Core utility; applied to directional icons in Calendar, Lightbox,
+ *   Pagination, Carousel and the Table expand/disclosure plugins
  *
  * `mirror` flips its element on the horizontal axis only when an ancestor
  * carries `dir="rtl"`. Using `scaleX(-1)` (not `scale(-1, -1)`) keeps the

package/dist/utils/themeProps.d.ts

@@ -24,5 +24,24 @@ export declare function themeDataAttributes(props?: ClassProps): ThemeDataAttrib
  * // → { className: 'astryx-button primary sm', data-variant: 'primary', data-size: 'sm' }
  * ```
  */
-export declare function themeProps(component: string, props?: ClassProps): ThemeProps;
+/**
+ * Options for {@link themeProps}.
+ */
+export type ThemePropsOptions = {
+    /**
+     * Stable class names to emit ALONGSIDE the component's own, for targets that
+     * have been renamed.
+     *
+     * A theme target is public API: renaming one silently breaks every theme
+     * that styles it. Emitting the old name beside the new one keeps those
+     * themes working through a deprecation window, at the cost of one extra
+     * class on the element until the old name is dropped in a major.
+     *
+     * Pass plain string literals — the theming guards scan for them statically.
+     * Document the old name with `deprecated` in the component's
+     * `theming.targets` so the docsite says which to use.
+     */
+    legacyNames?: ReadonlyArray<string>;
+};
+export declare function themeProps(component: string, props?: ClassProps, options?: ThemePropsOptions): ThemeProps;
 //# sourceMappingURL=themeProps.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"themeProps.d.ts","sourceRoot":"","sources":["../../src/utils/themeProps.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;AAC5D,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AACpD,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,QAAQ,MAAM,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAC/E,MAAM,MAAM,UAAU,GAAG;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,GAAG,mBAAmB,CAAC;AA6DnE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,CAAC,EAAE,UAAU,GACjB,mBAAmB,CAarB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,UAAU,GACjB,UAAU,CAKZ"}
+{"version":3,"file":"themeProps.d.ts","sourceRoot":"","sources":["../../src/utils/themeProps.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;AAC5D,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AACpD,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,QAAQ,MAAM,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAC/E,MAAM,MAAM,UAAU,GAAG;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,GAAG,mBAAmB,CAAC;AA6DnE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,mBAAmB,CAa3E;AAED;;;;;;;;;;;GAWG;AACH;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACrC,CAAC;AAEF,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,UAAU,CAQZ"}

package/dist/utils/themeProps.js

@@ -89,9 +89,15 @@ export function themeDataAttributes(props) {
  * // → { className: 'astryx-button primary sm', data-variant: 'primary', data-size: 'sm' }
  * ```
  */
-export function themeProps(component, props) {
+/**
+ * Options for {@link themeProps}.
+ */
+
+export function themeProps(component, props, options) {
+  const className = buildClassName(component, props);
+  const legacy = options?.legacyNames?.map(name => stableClassName(name)) ?? [];
   return {
-    className: buildClassName(component, props),
+    className: legacy.length > 0 ? [className, ...legacy].join(' ') : className,
     ...themeDataAttributes(props)
   };
 }

package/locales/en.json

@@ -639,6 +639,10 @@
     "defaultMessage": "Clear {label}",
     "description": "Aria label for the clear-value button in DateInput / DateRangeInput / DateTimeInput. `{label}` is the field's own label so screen readers announce e.g. 'Clear Start date'."
   },
+  "@astryx.dateInput.invalidDate": {
+    "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.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}\")."
@@ -711,6 +715,10 @@
     "defaultMessage": "Select a time",
     "description": "\"Time\" = clock time (HH:MM), not duration or era. Grey placeholder inside an empty TimeInput field; imperative verb."
   },
+  "@astryx.timeInput.invalidTime": {
+    "defaultMessage": "Invalid time",
+    "description": "Screen-reader-only live-region alert in TimeInput / DateTimeInput when the typed time cannot be parsed. \"Time\" = clock time (HH:MM). The field silently reverts on blur, so this is the only rejection feedback a screen-reader user gets."
+  },
   "@astryx.topNav.heading.dialogLabel": {
     "defaultMessage": "Navigation menu",
     "description": "Screen-reader-only accessible name for the dropdown dialog opened from a TopNavHeading's overflow menu. Kept separate from the SideNav sibling."
@@ -807,6 +815,38 @@
     "defaultMessage": "Clear {label}",
     "description": "Screen-reader-only label on the X that removes the selected file from a FileInput. Example: `Clear Attachment`, `Clear Résumé`."
   },
+  "@astryx.fileInput.dropHint": {
+    "defaultMessage": "Drop files here",
+    "description": "Text shown in the dropzone area when a user is dragging files over the FileInput."
+  },
+  "@astryx.fileInput.errorInvalidType": {
+    "defaultMessage": "\"{fileName}\" is not an accepted file type",
+    "description": "Validation error shown when a selected file does not match the accepted types."
+  },
+  "@astryx.fileInput.errorMaxFiles": {
+    "defaultMessage": "Maximum {maxFiles} files allowed",
+    "description": "Validation error shown when the number of selected files exceeds the maximum."
+  },
+  "@astryx.fileInput.errorMaxSize": {
+    "defaultMessage": "\"{fileName}\" exceeds {maxSize} limit",
+    "description": "Validation error shown when a selected file exceeds the maximum size. {maxSize} is a formatted size string like \"2.0 MB\"."
+  },
+  "@astryx.fileInput.fileSelected": {
+    "defaultMessage": "1 file selected: {fileName}",
+    "description": "Live-region announcement when a single file is successfully selected."
+  },
+  "@astryx.fileInput.filesSelected": {
+    "defaultMessage": "{count} files selected",
+    "description": "Live-region announcement when multiple files are successfully selected."
+  },
+  "@astryx.fileInput.placeholder": {
+    "defaultMessage": "Choose file",
+    "description": "Default placeholder text shown when no file is selected in a single-file FileInput."
+  },
+  "@astryx.fileInput.placeholderMultiple": {
+    "defaultMessage": "Choose files",
+    "description": "Default placeholder text shown when no files are selected in a multi-file FileInput."
+  },
   "@astryx.fileInput.required": {
     "defaultMessage": "Required",
     "description": "Screen-reader-only description on the FileInput trigger indicating the field must be filled in. Mirrors the visible `Required` indicator next to the field label; conveyed via description because aria-required is not supported on role=\"button\"."
@@ -867,6 +907,14 @@
     "defaultMessage": "Clear {label}",
     "description": "Screen-reader-only label on the X that clears the value from a NumberInput. Example: `Clear Age`, `Clear Quantity`."
   },
+  "@astryx.numberInput.decrementLabel": {
+    "defaultMessage": "Decrement {label}",
+    "description": "Accessible label for the NumberInput button that decreases the value by one configured step. Example: `Decrement Quantity`."
+  },
+  "@astryx.numberInput.incrementLabel": {
+    "defaultMessage": "Increment {label}",
+    "description": "Accessible label for the NumberInput button that increases the value by one configured step. Example: `Increment Quantity`."
+  },
   "@astryx.selector.clearLabel": {
     "defaultMessage": "Clear {label}",
     "description": "Screen-reader-only label on the X that clears the selected value from a Selector. `{label}` is the selector's visible label — example: `Clear Country`."
@@ -923,6 +971,10 @@
     "defaultMessage": "Go to step {stepNumber, number}: {label}, {status}",
     "description": "Accessible name for a clickable lab Stepper step that also carries a status. {status} is one of the translated `step.status.*` words (completed/warning/error). Keep the pattern parallel to `step.goToStep`."
   },
+  "@astryx.step.optional": {
+    "defaultMessage": "Optional",
+    "description": "Visible indicator appended after a lab Stepper step's label when the step is optional (isOptional). Very short; appears inline after the label text."
+  },
   "@astryx.step.status.completed": {
     "defaultMessage": "completed",
     "description": "Screen-reader-only status word rendered next to a lab Stepper step label when the step is done (either progress-completed or status=success). Lowercase adjective; it is read mid-sentence after the step label."

package/locales/pseudo.json

@@ -479,6 +479,9 @@
   "@astryx.dateInput.clear": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },
+  "@astryx.dateInput.invalidDate": {
+    "defaultMessage": "⟦Íñṽàłíð ðàţé⟧"
+  },
   "@astryx.dateTimeInput.timeSuffix": {
     "defaultMessage": "⟦{label} ţíɱé⟧"
   },
@@ -533,6 +536,9 @@
   "@astryx.timeInput.placeholder": {
     "defaultMessage": "⟦Šéłéçţ à ţíɱé⟧"
   },
+  "@astryx.timeInput.invalidTime": {
+    "defaultMessage": "⟦Íñṽàłíð ţíɱé⟧"
+  },
   "@astryx.topNav.heading.dialogLabel": {
     "defaultMessage": "⟦Ñàṽíĝàţíóñ ɱéñú⟧"
   },
@@ -605,6 +611,30 @@
   "@astryx.fileInput.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },
+  "@astryx.fileInput.dropHint": {
+    "defaultMessage": "⟦Ðřóþ ƒíłéš ĥéřé⟧"
+  },
+  "@astryx.fileInput.errorInvalidType": {
+    "defaultMessage": "⟦\"{fileName}\" íš ñóţ àñ àççéþţéð ƒíłé ţýþé⟧"
+  },
+  "@astryx.fileInput.errorMaxFiles": {
+    "defaultMessage": "⟦Ṁàẋíɱúɱ {maxFiles} ƒíłéš àłłóŵéð⟧"
+  },
+  "@astryx.fileInput.errorMaxSize": {
+    "defaultMessage": "⟦\"{fileName}\" éẋçééðš {maxSize} łíɱíţ⟧"
+  },
+  "@astryx.fileInput.fileSelected": {
+    "defaultMessage": "⟦1 ƒíłé šéłéçţéð: {fileName}⟧"
+  },
+  "@astryx.fileInput.filesSelected": {
+    "defaultMessage": "⟦{count} ƒíłéš šéłéçţéð⟧"
+  },
+  "@astryx.fileInput.placeholder": {
+    "defaultMessage": "⟦Çĥóóšé ƒíłé⟧"
+  },
+  "@astryx.fileInput.placeholderMultiple": {
+    "defaultMessage": "⟦Çĥóóšé ƒíłéš⟧"
+  },
   "@astryx.fileInput.required": {
     "defaultMessage": "⟦Řéɋúířéð⟧"
   },
@@ -650,6 +680,12 @@
   "@astryx.numberInput.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },
+  "@astryx.numberInput.decrementLabel": {
+    "defaultMessage": "⟦Ðéçřéɱéñţ {label}⟧"
+  },
+  "@astryx.numberInput.incrementLabel": {
+    "defaultMessage": "⟦Íñçřéɱéñţ {label}⟧"
+  },
   "@astryx.selector.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },
@@ -692,6 +728,9 @@
   "@astryx.step.goToStepWithStatus": {
     "defaultMessage": "⟦Ĝó ţó šţéþ {stepNumber, number}: {label}, {status}⟧"
   },
+  "@astryx.step.optional": {
+    "defaultMessage": "⟦Óþţíóñàł⟧"
+  },
   "@astryx.step.status.completed": {
     "defaultMessage": "⟦çóɱþłéţéð⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.3.0",
+  "version": "0.4.0-canary.3112e99",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -297,6 +297,11 @@
       "types": "./dist/IconButton/index.d.ts",
       "default": "./dist/IconButton/index.js"
     },
+    "./Indicator": {
+      "source": "./src/Indicator/index.ts",
+      "types": "./dist/Indicator/index.d.ts",
+      "default": "./dist/Indicator/index.js"
+    },
     "./InputGroup": {
       "source": "./src/InputGroup/index.ts",
       "types": "./dist/InputGroup/index.d.ts",
@@ -649,6 +654,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/cli": "0.4.0-canary.3112e99",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",
@@ -657,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.3.0"
+    "rimraf": "^6.0.1"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/AlertDialog/AlertDialog.doc.mjs

@@ -21,11 +21,21 @@ export const docs = {
   ],
   usage: {
     description:
-      'AlertDialog asks the user to confirm a destructive or irreversible action before it happens. Use it for things like deleting content, revoking access, or discarding unsaved changes.\n\nFor cases where you want to show an alert without managing open state, use the `useImperativeAlertDialog` hook: call `alert.show(options)` and render `alert.element` in your tree.',
+      'AlertDialog asks the user to confirm a destructive or irreversible action before it happens. Use it for things like deleting content, revoking access, or discarding unsaved changes.\n\nIt implements the WAI-ARIA APG [Alert Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/): `role="alertdialog"`, a title linked by `aria-labelledby`, a consequence description linked by `aria-describedby`, focus moved into the dialog on open and returned to the trigger on close, and no dismissal by clicking outside. Escape cancels.\n\nFor cases where you want to show an alert without managing open state, use the `useImperativeAlertDialog` hook: call `alert.show(options)` and render `alert.element` in your tree.',
     bestPractices: [
       {guidance: true, description: 'Make the action button label specific: "Delete project" is better than "OK" or "Confirm".'},
       {guidance: true, description: 'Describe what will happen in the description so the user knows the consequences before confirming.'},
+      {guidance: true, description: 'Keep the cancel button first: it takes initial focus, so the least destructive choice is the one already selected when the dialog opens.'},
       {guidance: false, description: 'Use AlertDialog for non-destructive actions; use a standard Dialog instead.'},
+      {guidance: false, description: 'Rely on color alone to signal danger; the action label itself should say what will happen.'},
+      {guidance: false, description: 'Close the dialog from onAction before the work finishes; hold it open with isActionLoading and call onOpenChange(false) when the action settles.'},
+    ],
+    anatomy: [
+      {name: 'Title', required: true, description: 'The question being asked. Renders as a level-2 heading and labels the dialog via aria-labelledby.'},
+      {name: 'Description', required: true, description: 'What will happen if the user confirms. Linked to the dialog via aria-describedby.'},
+      {name: 'Cancel button', required: true, description: 'Ghost button that dismisses without acting. Takes initial focus, and Escape does the same thing.'},
+      {name: 'Action button', required: true, description: 'The confirming action. Destructive by default; shows a spinner while isActionLoading is set.'},
+      {name: 'Backdrop', required: true, description: 'Overlay behind the dialog that blocks page interaction. Clicking it does not dismiss.'},
     ],
   },
   // Intentionally a contained isInline preview, not playground.overlay: the
@@ -107,7 +117,7 @@ export const docs = {
       name: 'isInline',
       type: 'boolean',
       default: 'false',
-      description: 'Renders alert dialog content inline without modal behavior. For documentation previews and showcases only.',
+      description: 'Renders alert dialog content inline without modal behavior. For documentation previews and showcases only. Not being a modal, the inline path renders role="group" instead of role="alertdialog".',
     },
   ],
   components: [
@@ -125,11 +135,14 @@ export const docsDense = {
   description: 'Confirms destructive/irreversible action before it happens (delete, revoke access, discard unsaved changes).',
   usage: {
     description:
-      'AlertDialog confirms destructive/irreversible action (delete, revoke access, discard changes). To show w/o managing open state, use useImperativeAlertDialog hook: call alert.show(options) + render alert.element in tree.',
+      'AlertDialog confirms destructive/irreversible action (delete, revoke access, discard changes). Implements WAI-ARIA APG Alert Dialog pattern (https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/): role="alertdialog", aria-labelledby title, aria-describedby description, focus into dialog on open + back to trigger on close, no outside-click dismissal, Escape cancels. To show w/o managing open state, use useImperativeAlertDialog hook: call alert.show(options) + render alert.element in tree.',
     bestPractices: [
       {guidance: true, description: 'Make action button label specific: "Delete project" > "OK"/"Confirm".'},
       {guidance: true, description: 'Describe consequences in description so user knows outcome before confirming.'},
+      {guidance: true, description: 'Keep cancel first: it takes initial focus, so least destructive choice is preselected.'},
       {guidance: false, description: 'Use AlertDialog for non-destructive actions; use standard Dialog instead.'},
+      {guidance: false, description: 'Rely on color alone for danger; the action label should say what happens.'},
+      {guidance: false, description: 'Close from onAction before work finishes; hold open w/ isActionLoading, call onOpenChange(false) when it settles.'},
     ],
   },
 };

package/src/AlertDialog/AlertDialog.test.tsx

@@ -10,8 +10,10 @@
  */
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {AlertDialog} from './AlertDialog';
+import {useImperativeAlertDialog} from './useImperativeAlertDialog';
 
 beforeEach(() => {
   HTMLDialogElement.prototype.showModal = vi.fn(function (
@@ -111,4 +113,209 @@ describe('AlertDialog', () => {
     render(<AlertDialog {...defaultProps} />);
     expect(screen.getByText('Cancel')).toBeInTheDocument();
   });
+
+  describe('keyboard', () => {
+    it('calls onOpenChange(false) on Escape', async () => {
+      const onOpenChange = vi.fn();
+      render(<AlertDialog {...defaultProps} onOpenChange={onOpenChange} />);
+      fireEvent.keyDown(screen.getByRole('alertdialog'), {key: 'Escape'});
+      await waitFor(() => expect(onOpenChange).toHaveBeenCalledWith(false));
+    });
+
+    it('does not call onAction on Escape', () => {
+      const onAction = vi.fn();
+      render(<AlertDialog {...defaultProps} onAction={onAction} />);
+      fireEvent.keyDown(screen.getByRole('alertdialog'), {key: 'Escape'});
+      expect(onAction).not.toHaveBeenCalled();
+    });
+
+    it('activates cancel with Enter', async () => {
+      const user = userEvent.setup();
+      const onOpenChange = vi.fn();
+      render(<AlertDialog {...defaultProps} onOpenChange={onOpenChange} />);
+      screen.getByRole('button', {name: 'Cancel'}).focus();
+      await user.keyboard('{Enter}');
+      expect(onOpenChange).toHaveBeenCalledWith(false);
+    });
+
+    it('activates the action button with Space', async () => {
+      const user = userEvent.setup();
+      const onAction = vi.fn();
+      render(<AlertDialog {...defaultProps} onAction={onAction} />);
+      screen.getByRole('button', {name: 'Delete'}).focus();
+      await user.keyboard(' ');
+      expect(onAction).toHaveBeenCalled();
+    });
+
+    it('reaches both buttons by Tab, cancel first', async () => {
+      const user = userEvent.setup();
+      render(<AlertDialog {...defaultProps} />);
+      const cancel = screen.getByRole('button', {name: 'Cancel'});
+      const action = screen.getByRole('button', {name: 'Delete'});
+      cancel.focus();
+      expect(cancel).toHaveFocus();
+      await user.tab();
+      expect(action).toHaveFocus();
+    });
+  });
+
+  describe('focus', () => {
+    it('marks cancel as the initial focus target', () => {
+      render(<AlertDialog {...defaultProps} />);
+      // Dialog focuses [data-autofocus] itself after showModal(), so the
+      // contract this component owns is which element carries the attribute.
+      expect(screen.getByRole('button', {name: 'Cancel'})).toHaveAttribute(
+        'data-autofocus',
+      );
+      expect(screen.getByRole('button', {name: 'Delete'})).not.toHaveAttribute(
+        'data-autofocus',
+      );
+    });
+
+    it('keeps the initial focus target on the least destructive action', () => {
+      render(<AlertDialog {...defaultProps} cancelLabel="Never mind" />);
+      expect(screen.getByRole('button', {name: 'Never mind'})).toHaveAttribute(
+        'data-autofocus',
+      );
+    });
+
+    it('returns focus to the trigger when it closes', async () => {
+      const trigger = document.createElement('button');
+      trigger.textContent = 'Open';
+      document.body.appendChild(trigger);
+      trigger.focus();
+
+      const {rerender} = render(<AlertDialog {...defaultProps} />);
+      rerender(<AlertDialog {...defaultProps} isOpen={false} />);
+
+      await waitFor(() => expect(trigger).toHaveFocus());
+      trigger.remove();
+    });
+
+    it('does not disable the cancel button while the action is loading', () => {
+      render(<AlertDialog {...defaultProps} isActionLoading />);
+      expect(screen.getByRole('button', {name: 'Cancel'})).toBeEnabled();
+    });
+  });
+
+  describe('aria', () => {
+    it('marks the action button busy while loading', () => {
+      render(<AlertDialog {...defaultProps} isActionLoading />);
+      expect(screen.getByRole('button', {name: /Delete/})).toHaveAttribute(
+        'aria-busy',
+        'true',
+      );
+    });
+
+    it('is a modal alertdialog', () => {
+      render(<AlertDialog {...defaultProps} />);
+      expect(screen.getByRole('alertdialog')).toHaveAttribute(
+        'aria-modal',
+        'true',
+      );
+    });
+
+    describe('the inline preview path', () => {
+      it('does not claim the alertdialog role', () => {
+        render(<AlertDialog {...defaultProps} isInline />);
+        expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument();
+      });
+
+      it('exposes a named group instead, with no aria-modal', () => {
+        render(<AlertDialog {...defaultProps} isInline />);
+        const group = screen.getByRole('group', {name: 'Delete item?'});
+        expect(group).not.toHaveAttribute('aria-modal');
+        const describedBy = group.getAttribute('aria-describedby');
+        expect(describedBy).toBeTruthy();
+        expect(document.getElementById(describedBy!)).toHaveTextContent(
+          'This action cannot be undone.',
+        );
+      });
+    });
+  });
+});
+
+describe('useImperativeAlertDialog', () => {
+  const noop = () => {};
+
+  function Harness({onAction = noop}: {onAction?: () => unknown}) {
+    const alert = useImperativeAlertDialog();
+    return (
+      <>
+        <button
+          type="button"
+          onClick={() =>
+            alert.show({
+              title: 'Delete item?',
+              description: 'This action cannot be undone.',
+              actionLabel: 'Delete',
+              onAction,
+            })
+          }>
+          Open
+        </button>
+        <button type="button" onClick={alert.hide}>
+          Close it
+        </button>
+        <span data-testid="is-open">{String(alert.isOpen)}</span>
+        {alert.element}
+      </>
+    );
+  }
+
+  it('renders nothing until show is called', () => {
+    render(<Harness />);
+    expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument();
+    expect(screen.getByTestId('is-open')).toHaveTextContent('false');
+  });
+
+  it('shows the dialog with the given options', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    expect(screen.getByRole('alertdialog')).toBeInTheDocument();
+    expect(screen.getByText('Delete item?')).toBeInTheDocument();
+    expect(
+      screen.getByText('This action cannot be undone.'),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId('is-open')).toHaveTextContent('true');
+  });
+
+  it('hides on hide()', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    await user.click(screen.getByRole('button', {name: 'Close it'}));
+    expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument();
+    expect(screen.getByTestId('is-open')).toHaveTextContent('false');
+  });
+
+  it('closes when the dialog cancels', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    await user.click(screen.getByRole('button', {name: 'Cancel'}));
+    expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument();
+    expect(screen.getByTestId('is-open')).toHaveTextContent('false');
+  });
+
+  it('forwards onAction and leaves closing to the caller', async () => {
+    const user = userEvent.setup();
+    const onAction = vi.fn();
+    render(<Harness onAction={onAction} />);
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    await user.click(screen.getByRole('button', {name: 'Delete'}));
+    expect(onAction).toHaveBeenCalledTimes(1);
+    expect(screen.getByRole('alertdialog')).toBeInTheDocument();
+  });
+
+  it('can be shown again after being hidden', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    await user.click(screen.getByRole('button', {name: 'Close it'}));
+    await user.click(screen.getByRole('button', {name: 'Open'}));
+    expect(screen.getByRole('alertdialog')).toBeInTheDocument();
+    expect(screen.getByTestId('is-open')).toHaveTextContent('true');
+  });
 });