@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/theme/generateThemeRules.test.ts

@@ -7,7 +7,13 @@
  */
 
 import {describe, it, expect} from 'vitest';
-import {defineTheme, generateThemeCSS, generateThemeRules} from './index';
+import {
+  dataTokenDefaults,
+  defineTheme,
+  generateThemeCSS,
+  generateThemeRules,
+} from './index';
+import {generateDataTokenDefaultsCSS} from './generateThemeRules';
 
 const defaultInput = {
   name: 'default',
@@ -702,3 +708,95 @@ describe('physical padding longhands', () => {
     expect(rule).not.toContain('--_dropdown-menu-padding');
   });
 });
+
+describe('renamed theme targets', () => {
+  // The renamed targets emit both classes, so a rule written against either
+  // key selects the element. What is easy to miss is the derived-var half: a
+  // key the registry does not know still emits a rule, minus every var the
+  // component actually reads — the same silent nothing a misspelled key gives.
+  it('expands derived vars for a renamed key and its deprecated spelling', () => {
+    const rules = (component: string, styles: Record<string, string>) =>
+      generateThemeRules(
+        defineTheme({
+          name: `test-renamed-${component}`,
+          components: {[component]: {base: styles}},
+        }),
+      ).join('\n');
+
+    const hoverCard = rules('hover-card', {borderRadius: '9px'});
+    expect(hoverCard).toContain('.astryx-hover-card');
+    expect(hoverCard).toContain('--_hovercard-radius: 9px');
+    expect(rules('hovercard', {borderRadius: '9px'})).toContain(
+      '--_hovercard-radius: 9px',
+    );
+
+    const textArea = rules('text-area', {paddingInline: '11px'});
+    expect(textArea).toContain('.astryx-text-area');
+    expect(textArea).toContain('--_textarea-inline-padding: 11px');
+    expect(rules('textarea', {paddingInline: '11px'})).toContain(
+      '--_textarea-inline-padding: 11px',
+    );
+
+    const mark = rules('progress-bar-mark', {width: '3px'});
+    expect(mark).toContain('.astryx-progress-bar-mark');
+    expect(mark).toContain('--_progressbar-mark-width: 3px');
+    expect(rules('progressbar-mark', {width: '3px'})).toContain(
+      '--_progressbar-mark-width: 3px',
+    );
+  });
+});
+
+describe('data visualization tokens', () => {
+  const scopeBlock = (theme: Parameters<typeof generateThemeRules>[0]) =>
+    generateThemeRules(theme).find(r => r.includes(':scope'));
+
+  it('seeds the whole palette once, at :root', () => {
+    const css = generateDataTokenDefaultsCSS();
+
+    expect(css.startsWith(':root {')).toBe(true);
+    for (const [name, value] of Object.entries(dataTokenDefaults)) {
+      expect(css).toContain(`${name}: ${value};`);
+    }
+  });
+
+  it('leaves the defaults out of a theme scope block', () => {
+    // A scope block that re-declared them would shadow a parent theme's
+    // override in every nested <Theme>, which no other token family does.
+    expect(scopeBlock(defineTheme({name: 'data-bare'}))).toBeUndefined();
+  });
+
+  it("puts only the theme's own data token in its scope block", () => {
+    const block = scopeBlock(
+      defineTheme({
+        name: 'data-override',
+        tokens: {'--color-data-categorical-blue': ['#123456', '#654321']},
+      }),
+    )!;
+
+    expect(block).toContain(
+      '--color-data-categorical-blue: light-dark(#123456, #654321);',
+    );
+    expect(block.match(/--color-data-/g)).toHaveLength(1);
+    expect(block).not.toContain('--color-data-categorical-orange');
+  });
+
+  it('keeps the palette out of the scoped stylesheet', () => {
+    // The palette's own contents are asserted once, against
+    // `dataTokenDefaults`, in `seeds the whole palette once, at :root` above.
+    const {component, prose} = generateThemeCSS(
+      defineTheme({name: 'data-css'}),
+    );
+
+    expect(component).not.toContain('--color-data-');
+    expect(prose).not.toContain('--color-data-');
+  });
+
+  it('keeps generateThemeCSS to its two scoped blocks', () => {
+    // The defaults are theme-independent, so they are not part of the theme
+    // CSS contract: `astryx theme build` formats them from the public
+    // `dataTokenDefaults` export instead.
+    expect(
+      Object.keys(generateThemeCSS(defineTheme({name: 'data-shape'}))).sort(),
+    ).toEqual(['component', 'prose']);
+  });
+});

package/src/theme/generateThemeRules.ts

@@ -18,6 +18,7 @@
 import type {DefinedTheme} from './defineTheme';
 import {parseStyleKey} from '../utils/parseStyleKey';
 import {getDerivedVars} from './derivedVarRegistry';
+import {dataTokenDefaults} from './domainTokens/dataTokens';
 import {cssVar, classPrefix, dataAttrNamespace} from '../naming';
 
 /**
@@ -758,6 +759,30 @@ export function generateOnMediaCSS(theme: DefinedTheme): string {
   return `@scope (${scopeSelector}) to (${THEME_SCOPE_TO}) {\n${inner}\n}`;
 }
 
+/**
+ * The `--color-data-*` defaults as one unscoped `:root` block.
+ *
+ * Core tokens reach CSS once, at `:root`, from StyleX's `defineVars` output in
+ * `@layer astryx-base`; a theme's own scope block then carries only the tokens
+ * that theme overrides, which is why a nested theme inherits its parent's
+ * override instead of shadowing it. Data tokens are not StyleX vars, so nothing
+ * declares them — this is their equivalent, and callers put it in
+ * `@layer astryx-base` so a theme's override wins by layer rather than by
+ * specificity. Seeding it per theme scope instead re-declares the default
+ * inside every nested theme, which is the shadowing this shape avoids.
+ *
+ * @internal Not exported from `@astryxdesign/core/theme`: the `<Theme>`
+ * runtime is the only caller. `astryx theme build` formats the same block from
+ * the public `dataTokenDefaults` export, and a CLI test asserts the two are
+ * byte-identical.
+ */
+export function generateDataTokenDefaultsCSS(): string {
+  const declarations = Object.entries(dataTokenDefaults)
+    .map(([prop, value]) => `  ${prop}: ${value};`)
+    .join('\n');
+  return `:root {\n${declarations}\n}`;
+}
+
 /**
  * Generate layered CSS for a theme — runtime path.
  *
@@ -768,6 +793,9 @@ export function generateOnMediaCSS(theme: DefinedTheme): string {
  * This separation ensures prose defaults (what bare HTML looks like in a theme)
  * sit at reset-layer priority where any class-based style wins, while component
  * overrides sit above StyleX so themes can restyle components intentionally.
+ *
+ * The theme-independent `--color-data-*` defaults are not part of this output:
+ * see `generateDataTokenDefaultsCSS`.
  */
 export function generateThemeCSS(theme: DefinedTheme): ThemeCSSOutput {
   const {component, prose} = generateThemeRulesSplit(theme);

package/src/theme/syntax/tokens.ts

@@ -44,8 +44,11 @@ export const syntaxTokenDefaults = {
   '--color-syntax-attribute': 'var(--color-text-teal)',
   // property -> cyan text (object properties)
   '--color-syntax-property': 'var(--color-text-cyan)',
-  // punctuation -> disabled text (brackets, semicolons)
-  '--color-syntax-punctuation': 'var(--color-text-disabled)',
+  // punctuation -> secondary text (brackets, semicolons). Not disabled text:
+  // disabled grey is calibrated to fail AA on purpose (WCAG exempts inactive
+  // controls), and punctuation in a code sample is normal, always-active
+  // text — see #5386.
+  '--color-syntax-punctuation': 'var(--color-text-secondary)',
   // background -> muted surface
   '--color-syntax-background': 'var(--color-background-muted)',
 } as const;

package/src/utils/groupItems.ts

@@ -19,6 +19,11 @@ export interface ItemGroup<T extends SearchableItem = SearchableItem> {
   items: T[];
 }
 
+export interface GroupItemsOptions {
+  /** Place ungrouped items before named groups instead of after them. */
+  ungroupedFirst?: boolean;
+}
+
 /**
  * Extract the group string from an item's auxiliaryData.
  */
@@ -52,6 +57,7 @@ export function getItemGroup(item: SearchableItem): string | undefined {
  */
 export function groupItems<T extends SearchableItem>(
   items: T[],
+  {ungroupedFirst = false}: GroupItemsOptions = {},
 ): ItemGroup<T>[] {
   const hasGroups = items.some(item => getItemGroup(item) != null);
 
@@ -76,14 +82,14 @@ export function groupItems<T extends SearchableItem>(
     }
   }
 
-  const result: ItemGroup<T>[] = groupOrder.map(heading => ({
+  const namedGroups: ItemGroup<T>[] = groupOrder.map(heading => ({
     heading,
     items: groups.get(heading) ?? [],
   }));
+  const ungroupedGroup: ItemGroup<T>[] =
+    ungrouped.length > 0 ? [{heading: null, items: ungrouped}] : [];
 
-  if (ungrouped.length > 0) {
-    result.push({heading: null, items: ungrouped});
-  }
-
-  return result;
+  return ungroupedFirst
+    ? [...ungroupedGroup, ...namedGroups]
+    : [...namedGroups, ...ungroupedGroup];
 }

package/src/utils/index.ts

@@ -86,7 +86,7 @@ export type {
   ThemeProps,
 } from './themeProps';
 export {groupItems, getItemGroup} from './groupItems';
-export type {ItemGroup} from './groupItems';
+export type {ItemGroup, GroupItemsOptions} from './groupItems';
 export {observeResize, unobserveResize} from './sharedResizeObserver';
 export {isRenderable} from './isRenderable';
 export {getInputARIA} from './inputAria';

package/src/utils/isApplePlatform.test.ts

@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file isApplePlatform.test.ts
+ * @input Uses vitest, isApplePlatform
+ * @output Unit tests for isApplePlatform
+ * @position Testing; validates isApplePlatform.ts implementation
+ */
+
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import {isApplePlatform} from './isApplePlatform';
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('isApplePlatform', () => {
+  it('trusts a client-hints platform that names one', () => {
+    vi.stubGlobal('navigator', {
+      userAgentData: {platform: 'macOS'},
+      platform: 'Win32',
+    });
+    expect(isApplePlatform()).toBe(true);
+
+    vi.stubGlobal('navigator', {
+      userAgentData: {platform: 'Windows'},
+      platform: 'MacIntel',
+    });
+    expect(isApplePlatform()).toBe(false);
+  });
+
+  it.each([
+    ['blank', ''],
+    ['whitespace', '   '],
+    ['the spec Unknown sentinel', 'Unknown'],
+    ['unknown in any case', 'UNKNOWN'],
+    ['a non-string', null],
+  ])('falls through to navigator.platform on %s', (_label, platform) => {
+    vi.stubGlobal('navigator', {
+      userAgentData: {platform},
+      platform: 'MacIntel',
+    });
+    expect(isApplePlatform()).toBe(true);
+
+    vi.stubGlobal('navigator', {userAgentData: {platform}, platform: 'Win32'});
+    expect(isApplePlatform()).toBe(false);
+  });
+
+  it('falls back to navigator.platform when client hints are absent', () => {
+    vi.stubGlobal('navigator', {platform: 'iPhone'});
+    expect(isApplePlatform()).toBe(true);
+
+    vi.stubGlobal('navigator', {platform: 'Linux x86_64'});
+    expect(isApplePlatform()).toBe(false);
+  });
+
+  it('answers false when there is no navigator at all', () => {
+    vi.stubGlobal('navigator', undefined);
+    expect(isApplePlatform()).toBe(false);
+  });
+});

package/src/utils/isApplePlatform.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file isApplePlatform.ts
+ * @input Reads navigator.userAgentData.platform and navigator.platform
+ * @output Exports isApplePlatform
+ * @position Internal util; the single platform detection behind useHotkeys and Kbd
+ *
+ * Deliberately absent from utils/index.ts: packages/core/src/index.ts does
+ * `export * from './utils'`, so naming it there would publish it as API.
+ * Import it by path, as interactionModality is imported.
+ */
+
+/**
+ * Detects whether the current platform is macOS/iOS.
+ * Prefers the User-Agent Client Hints API when it names a platform (modern
+ * Chrome/Edge), falls back to navigator.platform (deprecated but universally
+ * supported) when it names none.
+ */
+export function isApplePlatform(): boolean {
+  if (typeof navigator === 'undefined') {
+    return false;
+  }
+  const uaData = 'userAgentData' in navigator ? navigator.userAgentData : null;
+  if (uaData && typeof uaData === 'object' && 'platform' in uaData) {
+    const uaPlatform = (uaData as {platform?: unknown}).platform;
+    const named = typeof uaPlatform === 'string' ? uaPlatform.trim() : '';
+    // A value that names nothing is no answer, not a negative one: builds that
+    // rewrite their client-hints identity ship '', and 'Unknown' is the spec's
+    // own sentinel for "cannot say". Both fall through rather than reading as
+    // "not Apple".
+    if (named !== '' && named.toLowerCase() !== 'unknown') {
+      return /mac/i.test(named);
+    }
+  }
+  return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
+}

package/src/utils/sharedResizeObserver.ts

@@ -24,7 +24,15 @@ type ResizeCallback = (entry: ResizeObserverEntry) => void;
 let observer: ResizeObserver | null = null;
 const callbacks = new Map<Element, ResizeCallback>();
 
-function getObserver(): ResizeObserver {
+/**
+ * The shared observer, or null where the API does not exist (jsdom, an old
+ * browser). Callers still get the one-shot measurement `observeResize` fires
+ * on registration; live resize updates are the part that needs the API.
+ */
+function getObserver(): ResizeObserver | null {
+  if (typeof ResizeObserver === 'undefined') {
+    return null;
+  }
   if (!observer) {
     observer = new ResizeObserver(entries => {
       for (const entry of entries) {
@@ -64,7 +72,7 @@ export function observeResize(
   callback: ResizeCallback,
 ): void {
   callbacks.set(element, callback);
-  getObserver().observe(element);
+  getObserver()?.observe(element);
 
   // Fire once immediately so callers get an initial measurement
   // without duplicating their logic outside the observer path.

package/src/utils/timeParser.test.ts

@@ -135,6 +135,9 @@ describe('parseTimeInput', () => {
   it('parses compact formats', () => {
     expect(parseTimeInput('1430')).toBe('14:30');
     expect(parseTimeInput('0000')).toBe('00:00');
+    expect(parseTimeInput('0230pm')).toBe('14:30');
+    expect(parseTimeInput('1230am')).toBe('00:30');
+    expect(parseTimeInput('023045pm', true)).toBe('14:30:45');
   });
 
   it('parses hour-only with meridiem', () => {
@@ -259,7 +262,9 @@ describe('adjustTime', () => {
 
   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');
+    expect(adjustTime('10:00' as ISOTimeString, -1440 * 1e7 - 30)).toBe(
+      '09:30',
+    );
   });
 
   it('adds minutes', () => {

package/src/utils/timeParser.ts

@@ -4,7 +4,7 @@
  * @file timeParser.ts
  * @input Uses string parsing
  * @output Exports time parsing and formatting utilities
- * @position Shared utility; used by TimePicker
+ * @position Shared utility; used by TimeInput and DateTimeInput
  *
  * SYNC: When modified, update this header
  */
@@ -175,16 +175,29 @@ export function parseTimeInput(
   // Remove AM/PM suffix
   const timeStr = trimmed.replace(/\s*[ap]\.?m?\.?\s*$/i, '').trim();
 
+  const convertHourTo24Hour = (hour: number): number | null => {
+    if (!hasMeridiem) {
+      return hour;
+    }
+    if (hour < 1 || hour > 12) {
+      return null;
+    }
+    if (isPM && hour !== 12) {
+      return hour + 12;
+    }
+    if (isAM && hour === 12) {
+      return 0;
+    }
+    return hour;
+  };
+
   // Handle formats like "2pm" -> "2"
   if (/^\d{1,2}$/.test(timeStr)) {
     const hour = parseInt(timeStr, 10);
-    if (hour >= 1 && hour <= 12 && hasMeridiem) {
-      let hour24 = hour;
-      if (isPM && hour !== 12) {
-        hour24 = hour + 12;
-      }
-      if (isAM && hour === 12) {
-        hour24 = 0;
+    if (hasMeridiem) {
+      const hour24 = convertHourTo24Hour(hour);
+      if (hour24 === null) {
+        return null;
       }
       return formatISOTime(
         {hour: hour24, minute: 0, second: 0},
@@ -201,8 +214,15 @@ export function parseTimeInput(
   if (/^\d{4}$/.test(timeStr)) {
     const hour = parseInt(timeStr.slice(0, 2), 10);
     const minute = parseInt(timeStr.slice(2, 4), 10);
-    if (hour >= 0 && hour <= 23 && minute >= 0 && minute <= 59) {
-      return formatISOTime({hour, minute, second: 0}, includeSeconds);
+    const hour24 = convertHourTo24Hour(hour);
+    if (
+      hour24 !== null &&
+      hour24 >= 0 &&
+      hour24 <= 23 &&
+      minute >= 0 &&
+      minute <= 59
+    ) {
+      return formatISOTime({hour: hour24, minute, second: 0}, includeSeconds);
     }
     return null;
   }
@@ -212,15 +232,17 @@ export function parseTimeInput(
     const hour = parseInt(timeStr.slice(0, 2), 10);
     const minute = parseInt(timeStr.slice(2, 4), 10);
     const second = parseInt(timeStr.slice(4, 6), 10);
+    const hour24 = convertHourTo24Hour(hour);
     if (
-      hour >= 0 &&
-      hour <= 23 &&
+      hour24 !== null &&
+      hour24 >= 0 &&
+      hour24 <= 23 &&
       minute >= 0 &&
       minute <= 59 &&
       second >= 0 &&
       second <= 59
     ) {
-      return formatISOTime({hour, minute, second}, includeSeconds);
+      return formatISOTime({hour: hour24, minute, second}, includeSeconds);
     }
     return null;
   }

package/src/__tests__/inputWidthContract.test.tsx

@@ -1,69 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, it, expect} from 'vitest';
-
-import {docs as CheckboxInputDocs} from '../CheckboxInput/CheckboxInput.doc.mjs';
-import {docs as CheckboxListDocs} from '../CheckboxList/CheckboxList.doc.mjs';
-import {docs as DateInputDocs} from '../DateInput/DateInput.doc.mjs';
-import {docs as DateRangeInputDocs} from '../DateRangeInput/DateRangeInput.doc.mjs';
-import {docs as DateTimeInputDocs} from '../DateTimeInput/DateTimeInput.doc.mjs';
-import {docs as FileInputDocs} from '../FileInput/FileInput.doc.mjs';
-import {docs as MultiSelectorDocs} from '../MultiSelector/MultiSelector.doc.mjs';
-import {docs as NumberInputDocs} from '../NumberInput/NumberInput.doc.mjs';
-import {docs as RadioListDocs} from '../RadioList/RadioList.doc.mjs';
-import {docs as SelectorDocs} from '../Selector/Selector.doc.mjs';
-import {docs as SliderDocs} from '../Slider/Slider.doc.mjs';
-import {docs as SwitchDocs} from '../Switch/Switch.doc.mjs';
-import {docs as TextAreaDocs} from '../TextArea/TextArea.doc.mjs';
-import {docs as TextInputDocs} from '../TextInput/TextInput.doc.mjs';
-import {docs as TimeInputDocs} from '../TimeInput/TimeInput.doc.mjs';
-import {docs as TokenizerDocs} from '../Tokenizer/Tokenizer.doc.mjs';
-import {docs as TypeaheadDocs} from '../Typeahead/Typeahead.doc.mjs';
-
-const inputDocsSuite = [
-  {name: 'CheckboxInput', docs: CheckboxInputDocs},
-  {name: 'CheckboxList', docs: CheckboxListDocs},
-  {name: 'DateInput', docs: DateInputDocs},
-  {name: 'DateRangeInput', docs: DateRangeInputDocs},
-  {name: 'DateTimeInput', docs: DateTimeInputDocs},
-  {name: 'FileInput', docs: FileInputDocs},
-  {name: 'MultiSelector', docs: MultiSelectorDocs},
-  {name: 'NumberInput', docs: NumberInputDocs},
-  {name: 'RadioList', docs: RadioListDocs},
-  {name: 'Selector', docs: SelectorDocs},
-  {name: 'Slider', docs: SliderDocs},
-  {name: 'Switch', docs: SwitchDocs},
-  {name: 'TextArea', docs: TextAreaDocs},
-  {name: 'TextInput', docs: TextInputDocs},
-  {name: 'TimeInput', docs: TimeInputDocs},
-  {name: 'Tokenizer', docs: TokenizerDocs},
-  {name: 'Typeahead', docs: TypeaheadDocs},
-];
-
-describe('Input Family width Prop Contract (#4163)', () => {
-  inputDocsSuite.forEach(({name, docs}) => {
-    it(`documents the width prop for ${name}`, () => {
-      // `docs` is the ComponentDoc union (single vs multi component); narrow it
-      // for structural access to either the top-level props or the first
-      // sub-component's props.
-      const doc = docs as {
-        props?: {name: string; type: string}[];
-        components?: {props?: {name: string; type: string}[]}[];
-      };
-      const propsList = (doc.props || doc.components?.[0]?.props) as {
-        name: string;
-        type: string;
-      }[];
-      expect(
-        propsList,
-        `${name}.doc.mjs must expose a props array`,
-      ).toBeDefined();
-      const widthProp = propsList.find(p => p.name === 'width');
-      expect(
-        widthProp,
-        `${name}.doc.mjs must document the width prop`,
-      ).toBeDefined();
-      expect(widthProp?.type).toBe('SizeValue');
-    });
-  });
-});