@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/dist/utils/color.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @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. */
+export interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/**
+ * Parse a hex color into {@link RGBA}. Accepts `#rgb`, `#rgba`, `#rrggbb`, and
+ * `#rrggbbaa`, with or without the leading `#`. Returns null for anything else.
+ */
+export declare function parseHex(hex: string): RGBA | null;
+/**
+ * Parse an `rgb()`/`rgba()` color into {@link RGBA}. Accepts comma- or
+ * space-separated channels, an optional `/ alpha`, and percentage channels.
+ */
+export declare function parseRgb(value: string): RGBA | null;
+/**
+ * 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 declare function parseColor(value: string): RGBA | null;
+/** Format RGB channels (0-255) as an uppercase `#RRGGBB` string. */
+export declare function formatHex(r: number, g: number, b: number): string;
+/**
+ * Serialize {@link RGBA} to a compact, JS-usable CSS color: `#RRGGBB` when
+ * fully opaque, otherwise `rgba(r, g, b, a)`.
+ */
+export declare function formatColor({ r, g, b, a }: RGBA): string;
+//# sourceMappingURL=color.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../src/utils/color.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,kEAAkE;AAClE,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAoBD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAqBjD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAqCnD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAarD;AAED,oEAAoE;AACpE,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAIjE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAC,EAAE,IAAI,GAAG,MAAM,CAMtD"}

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,7 +1,7 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.1.4",
-  "displayName": "XDS Core",
+  "version": "0.1.5-canary.76e6697",
+  "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
   "license": "MIT",
@@ -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.doc.mjs

@@ -28,6 +28,10 @@ export const docs = {
       {guidance: false, description: 'Use AlertDialog for non-destructive actions; use a standard Dialog instead.'},
     ],
   },
+  // Intentionally a contained isInline preview, not playground.overlay: the
+  // component stays visible on load and knobs stay live, whereas a real
+  // showModal() overlay makes the page inert — see PlaygroundConfig.overlay
+  // in docs-types.ts (#3657).
   playground: {
     defaults: {
       isOpen: true,

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/AlertDialog/useImperativeAlertDialog.tsx

@@ -36,7 +36,6 @@ export interface ImperativeAlertDialogReturn {
  * @example
  * ```
  * const alert = useImperativeAlertDialog();
- *
  * const handleDelete = () => {
  *   alert.show({
  *     title: 'Delete item?',
@@ -45,7 +44,6 @@ export interface ImperativeAlertDialogReturn {
  *     onAction: async () => { await deleteItem(); alert.hide(); },
  *   });
  * };
- *
  * return (
  *   <>
  *     <button onClick={handleDelete}>Delete</button>

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

@@ -13,6 +13,7 @@ export const docs = {
     bestPractices: [
       {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
       {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
+      {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
     ],
@@ -24,6 +25,17 @@ export const docs = {
       description: 'Aspect ratio as width/height (e.g. 16/9, 1).',
       required: true,
     },
+    {
+      name: 'shape',
+      type: "'rectangle' | 'ellipse'",
+      description: 'Container shape. Both respect the `ratio`. `ellipse` clips to an oval (a circle when `ratio={1}`).',
+      default: "'rectangle'",
+    },
+    {
+      name: 'fit',
+      type: "'cover' | 'contain' | 'center'",
+      description: 'How the child is sized inside the ratio box. `cover` fills and crops media, `contain` fills and letterboxes, `center` keeps the natural size centered. When omitted, the child styles itself.',
+    },
     {
       name: 'children',
       type: 'ReactNode',
@@ -60,12 +72,24 @@ export const docsZh = {
     bestPractices: [
       {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
       {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
+      {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
     ],
   },
   props: [
     {name: 'ratio', type: 'number', description: '宽高比，以宽/高表示（例如 16/9、1）。', required: true},
+    {
+      name: 'shape',
+      type: "'rectangle' | 'ellipse'",
+      description: '容器形状。两种形状都遵循 `ratio`。`ellipse` 裁剪为椭圆（`ratio={1}` 时为正圆）。',
+      default: "'rectangle'",
+    },
+    {
+      name: 'fit',
+      type: "'cover' | 'contain' | 'center'",
+      description: '子元素在比例框内的布局方式。`cover` 填满并裁剪媒体，`contain` 填满并留边，`center` 保持原始尺寸居中。省略时子元素自行设置样式。',
+    },
     {name: 'children', type: 'ReactNode', description: '通过绝对定位填充容器的内容。', required: true},
     {
       name: 'xstyle',
@@ -76,7 +100,7 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-aspect-ratio'},
+      {className: 'astryx-aspect-ratio', visualProps: ['shape']},
     ],
   },
 };
@@ -90,12 +114,15 @@ export const docsDense = {
     bestPractices: [
       {guidance: true, description: 'Express the ratio as a fraction like `16/9` or `4/3` for readability.'},
       {guidance: true, description: 'Use for media that needs consistent proportions across screen sizes.'},
+      {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
     ],
   },
   propDescriptions: {
     ratio: 'width/height ratio (e.g. 16/9, 1)',
+    shape: "container shape: 'rectangle' (default) | 'ellipse' (circle at ratio 1)",
+    fit: "child layout: 'cover' fill+crop | 'contain' fill+letterbox | 'center' natural size; omitted = child styles itself",
     children: 'content positioned absolutely to fill container',
     xstyle: 'StyleX layout customization via stylex.create()',
   },

package/src/AspectRatio/AspectRatio.test.tsx

@@ -9,7 +9,7 @@
  * SYNC: When AspectRatio.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi} from 'vitest';
+import {describe, it, expect, vi, beforeAll} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {AspectRatio} from './AspectRatio';
 
@@ -176,4 +176,145 @@ describe('AspectRatio', () => {
     const video = screen.getByTestId('video');
     expect(video).toBeInTheDocument();
   });
+
+  describe('fit', () => {
+    it('marks the child\'s direct parent with data-astryx-aspect-ratio-override for fit="cover"', () => {
+      render(
+        <AspectRatio ratio={16 / 9} fit="cover">
+          <img src="test.jpg" alt="Test" data-testid="image" />
+        </AspectRatio>,
+      );
+      // The marker sits on the child's actual parent, so the reset.css
+      // sizing rules are direct-child selectors with no dependence on
+      // AspectRatio's internal structure.
+      const wrapper = screen.getByTestId('image').parentElement;
+      expect(wrapper).toHaveAttribute(
+        'data-astryx-aspect-ratio-override',
+        'cover',
+      );
+    });
+
+    it('marks the child\'s direct parent with data-astryx-aspect-ratio-override for fit="contain"', () => {
+      render(
+        <AspectRatio ratio={16 / 9} fit="contain">
+          <img src="test.jpg" alt="Test" data-testid="image" />
+        </AspectRatio>,
+      );
+      const wrapper = screen.getByTestId('image').parentElement;
+      expect(wrapper).toHaveAttribute(
+        'data-astryx-aspect-ratio-override',
+        'contain',
+      );
+    });
+
+    it('does not expose fit on the theming surface', () => {
+      render(
+        <AspectRatio ratio={16 / 9} fit="cover" data-testid="aspect-ratio">
+          <img src="test.jpg" alt="Test" />
+        </AspectRatio>,
+      );
+      const element = screen.getByTestId('aspect-ratio');
+      // fit is structural, not visual — no data-fit attribute or class
+      // token on the themeable root (only shape is a theming target).
+      expect(element).not.toHaveAttribute('data-fit');
+      expect(element.className).not.toContain('cover');
+    });
+
+    it('emits no marker when fit is omitted (back-compat)', () => {
+      render(
+        <AspectRatio ratio={16 / 9} data-testid="aspect-ratio">
+          <img src="test.jpg" alt="Test" data-testid="image" />
+        </AspectRatio>,
+      );
+      const wrapper = screen.getByTestId('image').parentElement;
+      expect(wrapper).not.toHaveAttribute('data-astryx-aspect-ratio-override');
+      // Without the marker, none of the reset.css fit rules can match, so
+      // existing self-styled children render exactly as before.
+      expect(screen.getByTestId('image')).not.toHaveAttribute('class');
+    });
+
+    it('never touches the child element props', () => {
+      render(
+        <AspectRatio ratio={16 / 9} fit="cover">
+          <img
+            src="test.jpg"
+            alt="Test"
+            data-testid="image"
+            className="consumer-class"
+            style={{objectFit: 'contain'}}
+          />
+        </AspectRatio>,
+      );
+      const image = screen.getByTestId('image');
+      // Fit styling is pure CSS (zero-specificity reset rules); the child's
+      // own className/style pass through untouched and always win, so
+      // children that already size themselves keep their behavior.
+      expect(image.className).toBe('consumer-class');
+      expect(image.style.objectFit).toBe('contain');
+    });
+
+    it('centers the child via the wrapper with fit="center"', () => {
+      render(
+        <AspectRatio ratio={16 / 9} fit="center">
+          <img src="test.jpg" alt="Test" data-testid="image" />
+        </AspectRatio>,
+      );
+      const image = screen.getByTestId('image');
+      expect(image).not.toHaveAttribute('class');
+      const wrapper = image.parentElement;
+      expect(wrapper?.className).toContain('childCenter');
+    });
+
+    it('does not center the wrapper for other fit values', () => {
+      render(
+        <AspectRatio ratio={16 / 9} fit="cover">
+          <img src="test.jpg" alt="Test" data-testid="image" />
+        </AspectRatio>,
+      );
+      const wrapper = screen.getByTestId('image').parentElement;
+      expect(wrapper?.className).not.toContain('childCenter');
+    });
+  });
+
+  describe('reset.css fit baseline rules', () => {
+    // The cover/contain child sizing ships as zero-specificity baseline
+    // rules in reset.css keyed on the data-astryx-aspect-ratio-override
+    // marker the component sets on the child's direct parent. These
+    // assertions keep the stylesheet in sync with the component contract.
+    let resetCSS: string;
+
+    beforeAll(async () => {
+      const fs = await import('fs');
+      const path = await import('path');
+      resetCSS = fs.readFileSync(
+        path.resolve(__dirname, '../reset.css'),
+        'utf-8',
+      );
+    });
+
+    it('sizes the child to fill the box for cover and contain', () => {
+      const fillMatch = resetCSS.match(
+        /:where\(\[data-astryx-aspect-ratio-override="cover"\], \[data-astryx-aspect-ratio-override="contain"\]\)\s*>\s*:where\(\*\)\s*\{([^}]+)\}/,
+      );
+      expect(fillMatch).not.toBeNull();
+      expect(fillMatch![1]).toContain('width: 100%');
+      expect(fillMatch![1]).toContain('height: 100%');
+    });
+
+    it('crops media with object-fit: cover for fit="cover"', () => {
+      const coverMatch = resetCSS.match(
+        /:where\(\[data-astryx-aspect-ratio-override="cover"\]\)\s*>\s*:where\(img, video\)\s*\{([^}]+)\}/,
+      );
+      expect(coverMatch).not.toBeNull();
+      expect(coverMatch![1]).toContain('object-fit: cover');
+    });
+
+    it('letterboxes media with object-fit: contain for fit="contain"', () => {
+      const containMatch = resetCSS.match(
+        /:where\(\[data-astryx-aspect-ratio-override="contain"\]\)\s*>\s*:where\(img, video\)\s*\{([^}]+)\}/,
+      );
+      expect(containMatch).not.toBeNull();
+      expect(containMatch![1]).toContain('object-fit: contain');
+    });
+  });
 });