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

package/src/utils/color.ts

@@ -0,0 +1,148 @@
+// 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. */
+export interface RGBA {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+/** The named colors the design system relies on in token expressions. */
+const NAMED_COLORS: Record<string, RGBA> = {
+  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: number, min: number, max: number): number =>
+  Math.max(min, Math.min(max, value));
+
+/** Expand a shorthand hex body (`rgb`/`rgba`) to its full form (`rrggbb`/`rrggbbaa`). */
+function expandShorthand(body: string): string {
+  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: string): RGBA | null {
+  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: string): RGBA | null {
+  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: string): number => {
+    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: string): RGBA | null {
+  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: number, g: number, b: number): string {
+  const channel = (c: number): string =>
+    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}: RGBA): string {
+  if (a >= 1) {
+    return formatHex(r, g, b);
+  }
+  const round = (n: number): number => clamp(Math.round(n), 0, 255);
+  return `rgba(${round(r)}, ${round(g)}, ${round(b)}, ${parseFloat(a.toFixed(4))})`;
+}

package/src/utils/composeEventHandlers.test.ts

@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it, vi} from 'vitest';
+import type {SyntheticEvent} from 'react';
+import {composeEventHandlers} from './composeEventHandlers';
+
+function fakeEvent(): SyntheticEvent {
+  const event = {
+    defaultPrevented: false,
+    preventDefault() {
+      event.defaultPrevented = true;
+    },
+  };
+  return event as unknown as SyntheticEvent;
+}
+
+describe('composeEventHandlers', () => {
+  it('calls every handler in argument order', () => {
+    const calls: string[] = [];
+    const composed = composeEventHandlers(
+      () => calls.push('first'),
+      () => calls.push('second'),
+    );
+    composed(fakeEvent());
+    expect(calls).toEqual(['first', 'second']);
+  });
+
+  it('skips undefined handlers', () => {
+    const handler = vi.fn();
+    const composed = composeEventHandlers(undefined, handler, undefined);
+    composed(fakeEvent());
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('passes the same event to each handler', () => {
+    const event = fakeEvent();
+    const a = vi.fn();
+    const b = vi.fn();
+    composeEventHandlers(a, b)(event);
+    expect(a).toHaveBeenCalledWith(event);
+    expect(b).toHaveBeenCalledWith(event);
+  });
+
+  it('stops after a handler prevents default', () => {
+    const first = vi.fn((e: SyntheticEvent) => e.preventDefault());
+    const second = vi.fn();
+    composeEventHandlers(first, second)(fakeEvent());
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).not.toHaveBeenCalled();
+  });
+
+  it('lets a consumer handler opt out of later behavior (consumer-first order)', () => {
+    const consumer = vi.fn((e: SyntheticEvent) => e.preventDefault());
+    const ownBehavior = vi.fn();
+    composeEventHandlers(consumer, ownBehavior)(fakeEvent());
+    expect(ownBehavior).not.toHaveBeenCalled();
+  });
+
+  it('runs later handlers when default is not prevented', () => {
+    const consumer = vi.fn();
+    const ownBehavior = vi.fn();
+    composeEventHandlers(consumer, ownBehavior)(fakeEvent());
+    expect(ownBehavior).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns a no-op-safe function when all handlers are undefined', () => {
+    expect(() =>
+      composeEventHandlers(undefined, undefined)(fakeEvent()),
+    ).not.toThrow();
+  });
+});

package/src/utils/composeEventHandlers.ts

@@ -0,0 +1,44 @@
+// 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.
+ */
+
+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 function composeEventHandlers<E extends SyntheticEvent>(
+  ...handlers: (((event: E) => void) | undefined)[]
+): (event: E) => void {
+  return (event: E) => {
+    for (const handler of handlers) {
+      handler?.(event);
+      if (event.defaultPrevented) {
+        return;
+      }
+    }
+  };
+}

package/src/utils/index.ts

@@ -68,6 +68,7 @@ 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,
@@ -81,3 +82,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';

package/src/utils/mergeProps.test.ts

@@ -0,0 +1,166 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {mergeProps} from './mergeProps';
+
+describe('mergeProps', () => {
+  describe('string-first form (xdsClass, stylexResult, className?, style?)', () => {
+    it('returns the xds class alone when the stylex result has no class', () => {
+      expect(mergeProps('astryx-button', {className: ''})).toEqual({
+        className: 'astryx-button',
+        style: undefined,
+      });
+    });
+
+    it('prefixes the xds class before the stylex class name', () => {
+      expect(mergeProps('astryx-button', {className: 'x1 x2'})).toEqual({
+        className: 'astryx-button x1 x2',
+        style: undefined,
+      });
+    });
+
+    it('appends a consumer className after the stylex classes', () => {
+      expect(
+        mergeProps('astryx-button', {className: 'x1'}, 'consumer'),
+      ).toEqual({
+        className: 'astryx-button x1 consumer',
+        style: undefined,
+      });
+    });
+
+    it('omits the consumer className when it is falsy', () => {
+      expect(mergeProps('astryx-button', {className: 'x1'}, undefined)).toEqual(
+        {
+          className: 'astryx-button x1',
+          style: undefined,
+        },
+      );
+      expect(mergeProps('astryx-button', {className: 'x1'}, '')).toEqual({
+        className: 'astryx-button x1',
+        style: undefined,
+      });
+    });
+
+    it('defaults the stylex result to an empty class when omitted', () => {
+      expect(mergeProps('astryx-button')).toEqual({
+        className: 'astryx-button',
+        style: undefined,
+      });
+    });
+
+    it('lets the consumer style override the stylex style key-by-key', () => {
+      const result = mergeProps(
+        'astryx-button',
+        {className: 'x1', style: {color: 'red', margin: 0}},
+        undefined,
+        {color: 'blue'},
+      );
+      expect(result.style).toEqual({color: 'blue', margin: 0});
+    });
+
+    it('uses only the stylex style when no consumer style is given', () => {
+      const result = mergeProps('astryx-button', {
+        className: 'x1',
+        style: {color: 'red'},
+      });
+      expect(result.style).toEqual({color: 'red'});
+    });
+
+    it('uses only the consumer style when the stylex result has none', () => {
+      const result = mergeProps('astryx-button', {className: 'x1'}, undefined, {
+        color: 'blue',
+      });
+      expect(result.style).toEqual({color: 'blue'});
+    });
+
+    it('preserves extra keys from the stylex result via spread', () => {
+      const result = mergeProps('astryx-button', {
+        className: 'x1',
+        'data-style-src': 'stylex',
+      });
+      expect(result['data-style-src']).toBe('stylex');
+    });
+  });
+
+  describe('object-first form (arbitrary prop merge)', () => {
+    it('space-joins class names from both objects', () => {
+      expect(mergeProps({className: 'a'}, {className: 'b'})).toEqual({
+        className: 'a b',
+      });
+    });
+
+    it('keeps the single class name when only one side has one', () => {
+      expect(mergeProps({className: 'a'}, {})).toEqual({className: 'a'});
+      expect(mergeProps({}, {className: 'b'})).toEqual({className: 'b'});
+    });
+
+    it('drops className entirely when neither side has one', () => {
+      const result = mergeProps({id: 'x'}, {role: 'button'});
+      expect('className' in result).toBe(false);
+      expect(result).toEqual({id: 'x', role: 'button'});
+    });
+
+    it('lets override props win over base props', () => {
+      expect(mergeProps({role: 'button', id: 'a'}, {id: 'b'})).toEqual({
+        role: 'button',
+        id: 'b',
+      });
+    });
+
+    it('merges styles with the override winning per key', () => {
+      const result = mergeProps(
+        {style: {color: 'red', margin: 0}},
+        {style: {color: 'green'}},
+      );
+      expect(result.style).toEqual({color: 'green', margin: 0});
+    });
+
+    it('drops style entirely when neither side has one', () => {
+      const result = mergeProps({id: 'x'}, {id: 'y'});
+      expect('style' in result).toBe(false);
+    });
+
+    it('treats a string third argument as an appended className', () => {
+      expect(mergeProps({className: 'a'}, {className: 'b'}, 'c')).toEqual({
+        className: 'a b c',
+      });
+    });
+
+    it('treats an object third argument as a style', () => {
+      const result = mergeProps({className: 'a'}, {}, {color: 'red'});
+      expect(result).toEqual({className: 'a', style: {color: 'red'}});
+    });
+
+    it('applies the fourth argument as an overriding style', () => {
+      const result = mergeProps({style: {color: 'red'}}, {}, undefined, {
+        color: 'blue',
+      });
+      expect(result.style).toEqual({color: 'blue'});
+    });
+
+    it('accepts a string second argument as a className', () => {
+      expect(mergeProps({className: 'a'}, 'b')).toEqual({className: 'a b'});
+    });
+
+    it('merges arbitrary data attributes, override winning', () => {
+      const result = mergeProps(
+        {'data-variant': 'primary', 'data-size': 'md'},
+        {'data-size': 'lg'},
+      );
+      expect(result).toEqual({'data-variant': 'primary', 'data-size': 'lg'});
+    });
+
+    it('does not mutate the input objects', () => {
+      const base = {className: 'a', style: {color: 'red'}};
+      const overrides = {className: 'b', style: {color: 'blue'}};
+      mergeProps(base, overrides);
+      expect(base).toEqual({className: 'a', style: {color: 'red'}});
+      expect(overrides).toEqual({className: 'b', style: {color: 'blue'}});
+    });
+
+    it('ignores a null third argument (no style, no class added)', () => {
+      const result = mergeProps({className: 'a'}, {className: 'b'}, undefined);
+      expect(result).toEqual({className: 'a b'});
+    });
+  });
+});

package/src/utils/sharedResizeObserver.test.ts

@@ -15,7 +15,7 @@ describe('sharedResizeObserver', () => {
     mockDisconnect = vi.fn();
     constructorCalls = 0;
 
-    global.ResizeObserver = vi.fn((cb: ResizeObserverCallback) => {
+    global.ResizeObserver = vi.fn(function (cb: ResizeObserverCallback) {
       constructorCalls++;
       capturedCallback = cb;
       return {
@@ -23,7 +23,7 @@ describe('sharedResizeObserver', () => {
         unobserve: mockUnobserve,
         disconnect: mockDisconnect,
       };
-    });
+    }) as unknown as typeof ResizeObserver;
   });
 
   afterEach(() => {

package/src/utils/timeParser.test.ts

@@ -249,6 +249,19 @@ describe('isTimeInRange', () => {
 });
 
 describe('adjustTime', () => {
+  it('returns the input unchanged for non-finite deltas', () => {
+    // -Infinity previously spun the wrap-around loop forever;
+    // NaN previously produced the corrupt string "NaN:NaN".
+    expect(adjustTime('10:00' as ISOTimeString, -Infinity)).toBe('10:00');
+    expect(adjustTime('10:00' as ISOTimeString, Infinity)).toBe('10:00');
+    expect(adjustTime('10:00' as ISOTimeString, NaN)).toBe('10:00');
+  });
+
+  it('wraps large negative deltas in constant time', () => {
+    expect(adjustTime('10:00' as ISOTimeString, -1440 * 1e7)).toBe('10:00');
+    expect(adjustTime('10:00' as ISOTimeString, -1440 * 1e7 - 30)).toBe('09:30');
+  });
+
   it('adds minutes', () => {
     expect(adjustTime('14:30' as ISOTimeString, 15)).toBe('14:45');
     expect(adjustTime('14:30' as ISOTimeString, 30)).toBe('15:00');

package/src/utils/timeParser.ts

@@ -361,13 +361,16 @@ export function adjustTime(
     return time;
   }
 
+  // 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;
+  }
+
   let totalMinutes = parsed.hour * 60 + parsed.minute + deltaMinutes;
 
-  // Wrap around midnight
-  while (totalMinutes < 0) {
-    totalMinutes += 24 * 60;
-  }
-  totalMinutes = totalMinutes % (24 * 60);
+  // 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;

package/dist/Carousel/carousel.markers.stylex.d.ts

@@ -1,7 +0,0 @@
-import * as stylex from '@stylexjs/stylex';
-/**
- * Scoped marker for Carousel ancestor selectors.
- * Prevents hover styles from leaking from parent containers.
- */
-export declare const carouselScope: ReturnType<typeof stylex.defineMarker>;
-//# sourceMappingURL=carousel.markers.stylex.d.ts.map

package/dist/Carousel/carousel.markers.stylex.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"carousel.markers.stylex.d.ts","sourceRoot":"","sources":["../../src/Carousel/carousel.markers.stylex.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,UAAU,CAAC,OAAO,MAAM,CAAC,YAAY,CAC1C,CAAC"}

package/dist/Carousel/carousel.markers.stylex.js

@@ -1,12 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import * as stylex from '@stylexjs/stylex';
-
-/**
- * Scoped marker for Carousel ancestor selectors.
- * Prevents hover styles from leaking from parent containers.
- */
-export const carouselScope = {
-  xrkij8s: "xrkij8s",
-  $$css: true
-};

package/src/Carousel/carousel.markers.stylex.ts

@@ -1,10 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import * as stylex from '@stylexjs/stylex';
-
-/**
- * Scoped marker for Carousel ancestor selectors.
- * Prevents hover styles from leaking from parent containers.
- */
-export const carouselScope: ReturnType<typeof stylex.defineMarker> =
-  stylex.defineMarker();