@astryxdesign/core 0.1.3 → 0.1.4-canary.01e5b29

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/composeEventHandlers.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file composeEventHandlers.ts
+ * @input Multiple React event handlers (or undefined)
+ * @output A single handler that calls each in order, stopping if one prevents default
+ * @position Utility; used by components that own an interaction (a click that
+ *   selects, a keydown that drives arrow navigation) but also accept a consumer
+ *   handler for the same event through {...rest}. Composes them instead of
+ *   letting one clobber the other.
+ *
+ * Order is call order: the first argument runs first. Put the consumer handler
+ * first so it can opt out of the component's built-in behavior via
+ * `event.preventDefault()`; put the component's handler first when its behavior
+ * must always run regardless of the consumer.
+ */
+import type { SyntheticEvent } from 'react';
+/**
+ * Compose event handlers into one. Each handler runs in argument order; if any
+ * calls `event.preventDefault()`, the remaining handlers are skipped.
+ *
+ * @example
+ * ```tsx
+ * // Consumer first: a consumer onClick can preventDefault to block selection.
+ * <button onClick={composeEventHandlers(onClickProp, handleSelect)} />
+ *
+ * // Component first: built-in keyboard nav always runs.
+ * <div onKeyDown={composeEventHandlers(handleArrowKeys, onKeyDownProp)} />
+ * ```
+ */
+export declare function composeEventHandlers<E extends SyntheticEvent>(...handlers: (((event: E) => void) | undefined)[]): (event: E) => void;
+//# sourceMappingURL=composeEventHandlers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"composeEventHandlers.d.ts","sourceRoot":"","sources":["../../src/utils/composeEventHandlers.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,OAAO,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,cAAc,EAC3D,GAAG,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE,GAChD,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CASpB"}

package/dist/utils/composeEventHandlers.js

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file composeEventHandlers.ts
+ * @input Multiple React event handlers (or undefined)
+ * @output A single handler that calls each in order, stopping if one prevents default
+ * @position Utility; used by components that own an interaction (a click that
+ *   selects, a keydown that drives arrow navigation) but also accept a consumer
+ *   handler for the same event through {...rest}. Composes them instead of
+ *   letting one clobber the other.
+ *
+ * Order is call order: the first argument runs first. Put the consumer handler
+ * first so it can opt out of the component's built-in behavior via
+ * `event.preventDefault()`; put the component's handler first when its behavior
+ * must always run regardless of the consumer.
+ */
+
+/**
+ * Compose event handlers into one. Each handler runs in argument order; if any
+ * calls `event.preventDefault()`, the remaining handlers are skipped.
+ *
+ * @example
+ * ```tsx
+ * // Consumer first: a consumer onClick can preventDefault to block selection.
+ * <button onClick={composeEventHandlers(onClickProp, handleSelect)} />
+ *
+ * // Component first: built-in keyboard nav always runs.
+ * <div onKeyDown={composeEventHandlers(handleArrowKeys, onKeyDownProp)} />
+ * ```
+ */
+export function composeEventHandlers(...handlers) {
+  return event => {
+    for (const handler of handlers) {
+      handler?.(event);
+      if (event.defaultPrevented) {
+        return;
+      }
+    }
+  };
+}

package/dist/utils/index.d.ts

@@ -14,6 +14,7 @@ export { parseStyleKey } from './parseStyleKey';
 export { getKey, type Key, type KeyFallback } from './getKey';
 export { mergeProps } from './mergeProps';
 export { mergeRefs } from './mergeRefs';
+export { composeEventHandlers } from './composeEventHandlers';
 export { themeProps, themeDataAttributes } from './themeProps';
 export type { ClassValue, ClassProps, ThemeDataAttributes, ThemeProps, } from './themeProps';
 export { groupItems, getItemGroup } from './groupItems';
@@ -22,4 +23,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,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,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

@@ -14,8 +14,10 @@ export { parseStyleKey } from "./parseStyleKey.js";
 export { getKey } from "./getKey.js";
 export { mergeProps } from "./mergeProps.js";
 export { mergeRefs } from "./mergeRefs.js";
+export { composeEventHandlers } from "./composeEventHandlers.js";
 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.3",
+  "version": "0.1.4-canary.01e5b29",
   "displayName": "XDS Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -626,14 +626,14 @@
     "CHANGELOG.md"
   ],
   "peerDependencies": {
-    "@stylexjs/stylex": "^0.18.3",
+    "@stylexjs/stylex": "^0.19.0",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
-    "@babel/preset-react": "^7.29.7",
+    "@babel/preset-react": "^8.0.1",
     "@babel/preset-typescript": "^7.29.7",
     "@stylexjs/babel-plugin": "^0.19.0",
     "@testing-library/dom": "^10.0.0",

package/src/AlertDialog/AlertDialog.tsx

@@ -132,6 +132,7 @@ export function AlertDialog({
   className,
   style,
   'data-testid': testId,
+  ...rest
 }: AlertDialogProps) {
   const titleId = useId();
   const descriptionId = useId();
@@ -142,6 +143,7 @@ export function AlertDialog({
 
   return (
     <Dialog
+      {...rest}
       ref={ref}
       isOpen={isOpen}
       isInline={isInline}

package/src/AppShell/AppShell.tsx

@@ -470,6 +470,7 @@ export function AppShell({
   className,
   style,
   ref,
+  ...rest
 }: AppShellProps) {
   // =========================================================================
   // Parse mobileNav prop — normalize to config, custom element, or disabled
@@ -768,6 +769,7 @@ export function AppShell({
   return (
     <AppShellMobileContext value={mobileContextValue}>
       <div
+        {...rest}
         ref={mergeRefs(ref, shellRef)}
         data-testid={dataTestId}
         {...mergeProps(

package/src/AspectRatio/AspectRatio.doc.mjs

@@ -45,7 +45,7 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-aspect-ratio'},
+      {className: 'astryx-aspect-ratio', visualProps: ['shape']},
     ],
   },
 };

package/src/Avatar/Avatar.doc.mjs

@@ -55,8 +55,8 @@ export const docs = {
     },
     {
       name: 'size',
-      type: 'AvatarSize',
-      description: 'Avatar size (named or numeric pixel value).',
+      type: "'tiny' | 'xsmall' | 'small' | 'medium' | 'large' | number",
+      description: "Avatar size. Use a named size ('tiny', 'xsmall', 'small', 'medium', 'large') or a numeric pixel value. Note: short names like 'sm', 'md', 'lg' are NOT valid; use the full words.",
       default: "'small'",
     },
     {
@@ -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/Avatar/Avatar.test.tsx

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent} from '@testing-library/react';
 import {Avatar} from './Avatar';
 
 describe('Avatar', () => {
@@ -34,4 +34,35 @@ describe('Avatar', () => {
     // The inner <img> carries an empty alt so it isn't announced separately.
     expect(innerImg).toHaveAttribute('alt', '');
   });
+
+  it('retries a new src after a previous src failed to load', () => {
+    const {rerender} = render(
+      <Avatar name="Ada" src="https://example.com/broken.jpg" />,
+    );
+    const wrapper = screen.getByRole('img', {name: 'Ada'});
+    fireEvent.error(wrapper.querySelector('img')!);
+    // Broken image falls back to initials.
+    expect(wrapper.querySelector('img')).toBeNull();
+    expect(wrapper).toHaveTextContent('A');
+
+    // A different src must get a fresh load attempt, not the stale error.
+    rerender(<Avatar name="Ada" src="https://example.com/ada.jpg" />);
+    const img = wrapper.querySelector('img');
+    expect(img).not.toBeNull();
+    expect(img).toHaveAttribute('src', 'https://example.com/ada.jpg');
+  });
+
+  it('retries a new fallbackSrc after a previous fallbackSrc failed to load', () => {
+    const {rerender} = render(
+      <Avatar name="Ada" fallbackSrc="https://example.com/broken.jpg" />,
+    );
+    const wrapper = screen.getByRole('img', {name: 'Ada'});
+    fireEvent.error(wrapper.querySelector('img')!);
+    expect(wrapper.querySelector('img')).toBeNull();
+
+    rerender(<Avatar name="Ada" fallbackSrc="https://example.com/ada.jpg" />);
+    const img = wrapper.querySelector('img');
+    expect(img).not.toBeNull();
+    expect(img).toHaveAttribute('src', 'https://example.com/ada.jpg');
+  });
 });

package/src/Avatar/Avatar.tsx

@@ -63,20 +63,7 @@ type AvatarNamedSize = 'tiny' | 'xsmall' | 'small' | 'medium' | 'large';
  * Numeric size options (in pixels)
  */
 type AvatarNumericSize =
-  | 16
-  | 20
-  | 24
-  | 32
-  | 36
-  | 40
-  | 48
-  | 60
-  | 64
-  | 72
-  | 96
-  | 128
-  | 144
-  | 180;
+  16 | 20 | 24 | 32 | 36 | 40 | 48 | 60 | 64 | 72 | 96 | 128 | 144 | 180;
 
 /**
  * Avatar size - can be a named size or a specific pixel value
@@ -289,11 +276,16 @@ export function Avatar({
   ref,
   ...props
 }: AvatarProps) {
-  const [imageError, setImageError] = useState(false);
-  const [fallbackError, setFallbackError] = useState(false);
+  // Track the exact src that failed (rather than a boolean) so a changed
+  // src/fallbackSrc gets a fresh load attempt instead of the stale error.
+  const [erroredSrc, setErroredSrc] = useState<string | undefined>(undefined);
+  const [erroredFallbackSrc, setErroredFallbackSrc] = useState<
+    string | undefined
+  >(undefined);
 
-  const showImage = src && !imageError;
-  const showFallbackImage = !showImage && fallbackSrc && !fallbackError;
+  const showImage = src && erroredSrc !== src;
+  const showFallbackImage =
+    !showImage && fallbackSrc && erroredFallbackSrc !== fallbackSrc;
   const showInitials = !showImage && !showFallbackImage && name;
   const showIcon = !showImage && !showFallbackImage && !name;
 
@@ -332,7 +324,7 @@ export function Avatar({
             <img
               src={src}
               alt=""
-              onError={() => setImageError(true)}
+              onError={() => setErroredSrc(src)}
               {...stylex.props(styles.image)}
             />
           )}
@@ -340,7 +332,7 @@ export function Avatar({
             <img
               src={fallbackSrc}
               alt=""
-              onError={() => setFallbackError(true)}
+              onError={() => setErroredFallbackSrc(fallbackSrc)}
               {...stylex.props(styles.image)}
             />
           )}

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),