@astryxdesign/core 0.0.0-bootstrap.0 → 0.0.15

package/src/utils/getKey.test.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {getKey} from './getKey';
+
+describe('getKey', () => {
+  it('uses the id key when present', () => {
+    expect(getKey('alpha', 0)).toBe('id:alpha');
+    expect(getKey(0, 1)).toBe('id:0');
+  });
+
+  it('uses the fallback key only when the id key is missing', () => {
+    expect(getKey(undefined, 0)).toBe('fallback:0');
+    expect(getKey(null, 'empty')).toBe('fallback:empty');
+    expect(getKey(undefined, () => 2)).toBe('fallback:2');
+  });
+
+  it('does not read lazy fallback keys when the id key is present', () => {
+    expect(
+      getKey('alpha', () => {
+        throw new Error('Fallback should not be read');
+      }),
+    ).toBe('id:alpha');
+  });
+});

package/src/utils/getKey.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getKey.ts
+ * @input Receives an optional id key and required fallback key
+ * @output Exports getKey for stable React list keys
+ * @position Shared utility; consumed by components that render keyed lists
+ */
+
+export type Key = string | number;
+export type KeyFallback = Key | (() => Key);
+
+export function getKey(
+  idKey: Key | null | undefined,
+  fallback: KeyFallback,
+): string {
+  if (idKey != null) {
+    return `id:${idKey}`;
+  }
+
+  const fallbackKey = typeof fallback === 'function' ? fallback() : fallback;
+  return `fallback:${fallbackKey}`;
+}

package/src/utils/groupItems.ts

@@ -0,0 +1,89 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file groupItems.ts
+ * @input Array of SearchableItem with optional auxiliaryData.group
+ * @output Grouped structure preserving insertion order
+ * @position Shared utility; used by CommandPalette, trigger menu, and
+ *   any future component that needs to group search results by category.
+ */
+
+import type {SearchableItem} from '../Typeahead/types';
+
+/**
+ * A group of items with an optional heading.
+ * `heading` is null for ungrouped items.
+ */
+export interface ItemGroup<T extends SearchableItem = SearchableItem> {
+  heading: string | null;
+  items: T[];
+}
+
+/**
+ * Extract the group string from an item's auxiliaryData.
+ */
+export function getItemGroup(item: SearchableItem): string | undefined {
+  const aux = item.auxiliaryData as Record<string, unknown> | undefined;
+  return typeof aux?.group === 'string' ? aux.group : undefined;
+}
+
+/**
+ * Group items by `auxiliaryData.group`, preserving insertion order of groups.
+ * Ungrouped items are collected into a final group with `heading: null`.
+ *
+ * If no items have a group, returns a single entry with `heading: null`.
+ *
+ * @example
+ * ```
+ * const items = [
+ *   {id: '1', label: 'Home', auxiliaryData: {group: 'Navigation'}},
+ *   {id: '2', label: 'Settings', auxiliaryData: {group: 'Navigation'}},
+ *   {id: '3', label: 'Dark mode', auxiliaryData: {group: 'Preferences'}},
+ *   {id: '4', label: 'Help'},
+ * ];
+ *
+ * groupItems(items)
+ * // [
+ * //   {heading: 'Navigation', items: [{id:'1',...}, {id:'2',...}]},
+ * //   {heading: 'Preferences', items: [{id:'3',...}]},
+ * //   {heading: null, items: [{id:'4',...}]},
+ * // ]
+ * ```
+ */
+export function groupItems<T extends SearchableItem>(
+  items: T[],
+): ItemGroup<T>[] {
+  const hasGroups = items.some(item => getItemGroup(item) != null);
+
+  if (!hasGroups) {
+    return [{heading: null, items}];
+  }
+
+  const groupOrder: string[] = [];
+  const groups = new Map<string, T[]>();
+  const ungrouped: T[] = [];
+
+  for (const item of items) {
+    const group = getItemGroup(item);
+    if (group != null) {
+      if (!groups.has(group)) {
+        groupOrder.push(group);
+        groups.set(group, []);
+      }
+      groups.get(group)?.push(item);
+    } else {
+      ungrouped.push(item);
+    }
+  }
+
+  const result: ItemGroup<T>[] = groupOrder.map(heading => ({
+    heading,
+    items: groups.get(heading) ?? [],
+  }));
+
+  if (ungrouped.length > 0) {
+    result.push({heading: null, items: ungrouped});
+  }
+
+  return result;
+}

package/src/utils/index.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input Utils module exports
+ * @output Re-exports all utility functions and shared types
+ * @position Package entry point for utils
+ */
+
+export type {SizeValue} from './types';
+
+export type {ISODateString, DayOfWeek, PlainDate, DateRange} from './dateTypes';
+
+export {
+  parseDateInput,
+  dateToISO,
+  parseISO,
+  isLocaleDayFirst,
+} from './dateParser';
+
+export {
+  plainDateCreate,
+  plainDateFromISO,
+  plainDateToISO,
+  plainDateToDate,
+  plainDateFromDate,
+  plainDateToday,
+  getDaysInMonth,
+  plainDateDayOfWeek,
+  plainDateAddMonths,
+  plainDateAddDays,
+  plainDateToInstant,
+  plainDateFromInstant,
+  plainDateIsBefore,
+  plainDateIsAfter,
+  plainDateIsEqual,
+  plainDateMax,
+  plainDateMin,
+  plainDateIsInRange,
+  plainDateSetFirstOfMonth,
+  plainDateSetStartOfWeek,
+  plainDateSetEndOfWeekExclusive,
+  plainDateGetWeekNumber,
+  plainDateFormat,
+  DATE_FORMAT_WITH_WEEKDAY,
+  DATE_FORMAT_LONG,
+  DATE_FORMAT_MONTH_YEAR,
+  DATE_FORMAT_SHORT,
+  DATE_FORMAT_SHORT_WITH_YEAR,
+} from './plainDate';
+
+export {
+  parseISOTime,
+  formatISOTime,
+  formatDisplayTime12h,
+  formatDisplayTime24h,
+  parseTimeInput,
+  compareTime,
+  isTimeInRange,
+  clampTime,
+  adjustTime,
+  createISOTimeString,
+} from './timeParser';
+export type {ISOTimeString, ParsedTime} from './timeParser';
+
+export {parseStyleKey} from './parseStyleKey';
+export {getKey, type Key, type KeyFallback} from './getKey';
+
+export {mergeProps} from './mergeProps';
+export {mergeRefs} from './mergeRefs';
+export {groupItems, getItemGroup} from './groupItems';
+export type {ItemGroup} from './groupItems';
+export {observeResize, unobserveResize} from './sharedResizeObserver';
+export {isRenderable} from './isRenderable';

package/src/utils/isRenderable.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file isRenderable.ts
+ * @input A ReactNode value
+ * @output Boolean indicating whether the value will produce DOM output
+ * @position Utility for checking if a React slot prop has meaningful content.
+ *
+ * React treats null, undefined, true, false, and '' as empty — they render
+ * nothing. This utility checks if a ReactNode is NOT one of those values,
+ * meaning it will produce actual DOM output when rendered.
+ *
+ * Use this instead of `prop != null` when checking if a slot has content,
+ * since boolean/empty-string props also render nothing.
+ */
+
+import type {ReactNode} from 'react';
+
+/**
+ * Returns true if a ReactNode value will produce DOM output when rendered.
+ * Returns false for null, undefined, true, false, and empty string.
+ *
+ * @example
+ * ```tsx
+ * const hasSideNav = isRenderable(sideNav);
+ * const hasTopNav = isRenderable(topNav);
+ * ```
+ */
+export function isRenderable(node: ReactNode): boolean {
+  return node != null && typeof node !== 'boolean' && node !== '';
+}

package/src/utils/mergeProps.ts

@@ -0,0 +1,110 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Merge xds-* props, stylex.props result, and optional consumer className/style.
+ *
+ * stylex.props() returns { className, style }. This merges the Astryx stable
+ * class name plus any data-attribute reflection from `xdsThemeProps()` with the
+ * StyleX class name so both StyleX styles and the theme-targeting surface are
+ * applied.
+ *
+ * Consumer className is appended after StyleX classes.
+ * Consumer style is spread after StyleX inline styles, so these values take priority.
+ *
+ * @example
+ * ```tsx
+ * // Root element with xdsThemeProps
+ * <div {...mergeProps(
+ *   xdsThemeProps('button', { variant }),
+ *   stylex.props(styles.base, variants[variant]),
+ *   className,
+ *   style,
+ * )} />
+ *
+ * // Internal element — stylex + dynamic style only
+ * <div {...mergeProps(
+ *   stylex.props(styles.track),
+ *   { style: { width: dynamicWidth } },
+ * )} />
+ * ```
+ */
+
+type StyleObject = React.CSSProperties;
+type PropsObject = {
+  className?: string;
+  style?: StyleObject;
+  [key: string]: unknown;
+};
+
+function mergeTwoProps(base: PropsObject, overrides: PropsObject): PropsObject {
+  const merged: PropsObject = {...base, ...overrides};
+
+  const cls = [base.className, overrides.className].filter(Boolean).join(' ');
+  if (cls) {
+    merged.className = cls;
+  } else {
+    delete merged.className;
+  }
+
+  const mergedStyle =
+    overrides.style && base.style
+      ? {...base.style, ...overrides.style}
+      : overrides.style || base.style;
+  if (mergedStyle) {
+    merged.style = mergedStyle;
+  } else {
+    delete merged.style;
+  }
+
+  return merged;
+}
+
+export function mergeProps(
+  xdsClassOrStylexResult: string | PropsObject,
+  stylexResultOrClassName?: PropsObject | string,
+  classNameOrStyle?: string | React.CSSProperties,
+  style?: React.CSSProperties,
+): PropsObject {
+  // Disambiguate: first arg is string → (xdsClass, stylexResult, className?, style?)
+  // first arg is object → merge arbitrary props (supports xdsThemeProps + data attrs).
+  if (typeof xdsClassOrStylexResult === 'string') {
+    const xdsClass = xdsClassOrStylexResult;
+    const stylexResult = (stylexResultOrClassName as PropsObject) ?? {
+      className: '',
+    };
+    const className = classNameOrStyle as string | undefined;
+
+    let cls = stylexResult.className
+      ? `${xdsClass} ${stylexResult.className}`
+      : xdsClass;
+    if (className) {
+      cls = `${cls} ${className}`;
+    }
+
+    const mergedStyle =
+      style && stylexResult.style
+        ? {...stylexResult.style, ...style}
+        : style || stylexResult.style;
+
+    return {...stylexResult, className: cls, style: mergedStyle};
+  }
+
+  const first = xdsClassOrStylexResult;
+  const second =
+    typeof stylexResultOrClassName === 'string'
+      ? {className: stylexResultOrClassName}
+      : (stylexResultOrClassName ?? {});
+  let merged = mergeTwoProps(first, second);
+
+  if (typeof classNameOrStyle === 'string') {
+    merged = mergeTwoProps(merged, {className: classNameOrStyle});
+  } else if (classNameOrStyle != null) {
+    merged = mergeTwoProps(merged, {style: classNameOrStyle});
+  }
+
+  if (style != null) {
+    merged = mergeTwoProps(merged, {style});
+  }
+
+  return merged;
+}

package/src/utils/mergeRefs.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file mergeRefs.ts
+ * @input Multiple React refs (callback, object, or undefined)
+ * @output A single callback ref that forwards to all inputs
+ * @position Utility; used by components that need to merge an external ref
+ *   with an internal ref (e.g., popover trigger + consumer ref).
+ */
+
+import type {Ref, RefCallback} from 'react';
+
+export function mergeRefs<T>(...refs: (Ref<T> | undefined)[]): RefCallback<T> {
+  return (value: T | null) => {
+    const cleanups: (() => void)[] = [];
+    for (const ref of refs) {
+      if (typeof ref === 'function') {
+        const cleanup = ref(value);
+        if (typeof cleanup === 'function') {
+          cleanups.push(cleanup);
+        }
+      } else if (ref != null) {
+        (ref as {current: T | null}).current = value;
+      }
+    }
+    if (cleanups.length > 0) {
+      return () => {
+        for (const cleanup of cleanups) {cleanup();}
+      };
+    }
+  };
+}

package/src/utils/parseStyleKey.test.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {parseStyleKey} from './parseStyleKey';
+
+describe('parseStyleKey', () => {
+  it('returns empty string for base', () => {
+    expect(parseStyleKey('base')).toBe('');
+  });
+
+  it('converts variant:value to .value', () => {
+    expect(parseStyleKey('variant:secondary')).toBe('.secondary');
+  });
+
+  it('prefixes numeric values with prop name', () => {
+    expect(parseStyleKey('level:1')).toBe('.level-1');
+  });
+
+  it('handles compound keys', () => {
+    expect(parseStyleKey('variant:destructive+size:sm')).toBe(
+      '.destructive.sm',
+    );
+  });
+
+  it('handles compound with numeric value', () => {
+    expect(parseStyleKey('variant:primary+level:2')).toBe('.primary.level-2');
+  });
+});
+
+describe('parseStyleKey — bare state keys', () => {
+  it('converts bare state to .state', () => {
+    expect(parseStyleKey('checked')).toBe('.checked');
+  });
+
+  it('converts disabled state', () => {
+    expect(parseStyleKey('disabled')).toBe('.disabled');
+  });
+
+  it('converts selected state', () => {
+    expect(parseStyleKey('selected')).toBe('.selected');
+  });
+
+  it('handles compound bare states', () => {
+    expect(parseStyleKey('checked+disabled')).toBe('.checked.disabled');
+  });
+
+  it('handles mixed bare state + prop:value', () => {
+    expect(parseStyleKey('variant:destructive+disabled')).toBe(
+      '.destructive.disabled',
+    );
+  });
+});

package/src/utils/parseStyleKey.ts

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Parse a component style key into a CSS selector suffix.
+ *
+ * Used by both defineTheme (CSS generation) and components (class name rendering)
+ * to ensure the same convention is applied consistently.
+ *
+ * <!-- SYNC: packages/core/src/utils/xdsThemeProps.ts -->
+ *
+ * Emits the legacy class-selector suffix used by defineTheme/component override
+ * generation today. Components also reflect the same prop values as data
+ * attributes via `xdsThemeProps()` (`variant:secondary` renders both `.secondary`
+ * and `[data-variant="secondary"]` in the DOM), but generated theme CSS still
+ * uses these class selectors until the selector contract migrates fully.
+ *
+ * Values starting with a digit get prefixed with the prop name since
+ * CSS class names can't start with a number.
+ *
+ * Bare state names (no colon) are used directly as class names.
+ * This supports state-based theming targets like 'checked', 'disabled',
+ * 'selected' documented in the Theming Infrastructure wiki.
+ *
+ * @example
+ * ```ts
+ * parseStyleKey('base')                        // ''
+ * parseStyleKey('checked')                      // '.checked'
+ * parseStyleKey('checked+disabled')             // '.checked.disabled'
+ * parseStyleKey('variant:secondary')            // '.secondary'
+ * parseStyleKey('level:1')                      // '.level-1'
+ * parseStyleKey('variant:destructive+size:sm')  // '.destructive.sm'
+ * ```
+ */
+export function parseStyleKey(key: string): string {
+  if (key === 'base') {
+    return '';
+  }
+
+  return key
+    .split('+')
+    .map(part => {
+      const [prop, value] = part.split(':');
+      // Bare state name (no colon) — e.g. 'checked', 'disabled', 'selected'
+      if (value === undefined) {
+        return `.${prop}`;
+      }
+      // CSS classes can't start with a digit — prefix with prop name
+      if (/^\d/.test(value)) {
+        return `.${prop}-${value}`;
+      }
+      return `.${value}`;
+    })
+    .join('');
+}