@astryxdesign/core 0.7.5 → 0.7.6-canary.5cd7a15

package/src/utils/presentation.ts

@@ -0,0 +1,180 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file presentation.ts
+ * @input A component's `presentation` prop (a caller's value, or omitted),
+ *   what the component does when it is omitted, and the touch presentation
+ *   (utils/touchPresentation.ts)
+ * @output usePresentation and readPresentation (and the pure
+ *   resolvePresentation): the surface to render and whether the component's
+ *   touch input modes apply
+ * @position Internal resolver for stable components that, under a finger,
+ *   present a different surface or switch how an open surface follows input
+ *   (architecture:public-component-api INV16)
+ *
+ * A caller's explicit `presentation` always wins over the touch default:
+ *
+ * - `'popover'`: the fine-pointer surface AND input modes, on every device;
+ * - `'bottom-sheet'`: the sheet everywhere, with touch input modes under a
+ *   finger;
+ * - `'adaptive'`: the sheet on a compact touch screen and the popover
+ *   elsewhere, with touch input modes under a finger;
+ * - omitted: the component's default. `whenOmitted: 'popover'` answers as
+ *   `'popover'` (today's components). `whenOmitted: 'touch'` keeps the
+ *   popover surface and turns the component's touch input modes on under a
+ *   finger, as UIMenu tracks a finger in an anchored menu. Making `'touch'`
+ *   a released component's default is a functional default change
+ *   (`spec:AST-017` FR3) whose Changeset names `presentation="popover"`.
+ *
+ * One touch model on every touch device: the modes depend on the pointer,
+ * never on the platform. Touch styling (press paint, the text-size floor)
+ * and touch-only behavior that a component's own record defines (a row
+ * swipe, a slider's thumb) do not read this: they keep the touch
+ * presentation.
+ *
+ * CSS: a style that implements a touch surface or input mode is applied with
+ * `touchModes` (`stylex.props(touchModes && styles.touchMode)`), never as a
+ * bare media key on a base style, so a pinned `'popover'` keeps none of it.
+ * A rule inside it that needs the touch query uses the touch presentation's
+ * touch key; the iOS `@supports` gate is only for the one style iOS WebKit
+ * itself requires (the 16px text-size floor), never for a touch mode. On the
+ * server and while hydrating, `touchModes` is false and `'adaptive'` is the
+ * popover: a touch surface or mode opens only after hydration
+ * (`spec:AST-094` FR13), and no hint changes that. usePresentation listens
+ * only to the queries a request reads (`architecture:react-component-runtime`
+ * INV5): none for a pinned `'popover'`.
+ *
+ * SYNC: When modified, update presentation.test.ts.
+ */
+
+import {useCallback, useMemo, useSyncExternalStore} from 'react';
+import type {AdaptivePresentation} from '../hooks/useAdaptivePresentation';
+import type {CompactDefinition} from '../theme/themeAdaptations';
+import {
+  readTouchPresentation,
+  TOUCH_QUERY,
+  useCompactDefinition,
+  type TouchPresentation,
+} from './touchPresentation';
+
+/** What a component does when the caller omits `presentation`. */
+export type PresentationDefault = 'popover' | 'touch';
+
+export interface ResolvedPresentation {
+  /** The surface to render. */
+  readonly surface: 'popover' | 'bottom-sheet';
+  /**
+   * The component's touch input modes apply: a finger, and `presentation`
+   * not pinned to `'popover'`.
+   */
+  readonly touchModes: boolean;
+}
+
+export interface PresentationOptions {
+  /** What an omitted `presentation` means. @default 'popover' */
+  readonly whenOmitted?: PresentationDefault;
+}
+
+/**
+ * usePresentation's options. There is no server hint: the server and
+ * hydrating render never present touch modes (`spec:AST-094` FR13).
+ */
+export type UsePresentationOptions = PresentationOptions;
+
+export interface ReadPresentationOptions extends PresentationOptions {
+  /** The window to read; the global one by default. */
+  readonly view?: Window | null;
+  /**
+   * The active theme's compact definition (`useCompactDefinition()`, read
+   * while rendering), so a theme that moves `md` moves the sheet too
+   * (`spec:AST-012` FR9).
+   */
+  readonly compact: CompactDefinition;
+}
+
+/** The decision, from a presentation request and a touch presentation. */
+export function resolvePresentation(
+  presentation: AdaptivePresentation | undefined,
+  touch: TouchPresentation,
+  whenOmitted: PresentationDefault = 'popover',
+): ResolvedPresentation {
+  const request = presentation ?? whenOmitted;
+  const surface =
+    request === 'bottom-sheet' ||
+    (request === 'adaptive' && touch.isTouch && touch.isCompact)
+      ? 'bottom-sheet'
+      : 'popover';
+  const touchModes = request !== 'popover' && touch.isTouch;
+  return {surface, touchModes};
+}
+
+const noSubscription = () => () => {};
+/** The server and hydrating render match no query (`spec:AST-094` FR13). */
+const matchesNothing = () => false;
+
+/**
+ * A media query's match, subscribed only while `query` is given
+ * (`architecture:react-component-runtime` INV5); false on the server and
+ * while hydrating (`spec:AST-094` FR13).
+ */
+function useMatchWhileRead(query: string | null): boolean {
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      if (query == null) {
+        return noSubscription();
+      }
+      const mql = window.matchMedia(query);
+      mql.addEventListener('change', onStoreChange);
+      return () => mql.removeEventListener('change', onStoreChange);
+    },
+    [query],
+  );
+  const getSnapshot = useCallback(
+    () => query != null && window.matchMedia(query).matches,
+    [query],
+  );
+  return useSyncExternalStore(subscribe, getSnapshot, matchesNothing);
+}
+
+/**
+ * The presentation now, following the pointer and the size as they change
+ * (a tablet docking a trackpad). SSR-safe: renders the server default (not
+ * touch, not compact) until hydrated (`spec:AST-094` FR13). It subscribes
+ * only to what the request reads: a pinned `'popover'` to neither query,
+ * `'bottom-sheet'` and the omitted `'touch'` default to the pointer, and
+ * `'adaptive'` to the pointer and the compact size.
+ */
+export function usePresentation(
+  presentation: AdaptivePresentation | undefined,
+  {whenOmitted = 'popover'}: UsePresentationOptions = {},
+): ResolvedPresentation {
+  const request = presentation ?? whenOmitted;
+  const compact = useCompactDefinition();
+  const isTouch = useMatchWhileRead(request === 'popover' ? null : TOUCH_QUERY);
+  const isCompact = useMatchWhileRead(
+    request === 'adaptive' ? compact.query : null,
+  );
+  return useMemo(
+    () => resolvePresentation(presentation, {isTouch, isCompact}, whenOmitted),
+    [presentation, isTouch, isCompact, whenOmitted],
+  );
+}
+
+/**
+ * The presentation at this moment, for a decision taken once (a menu
+ * deciding how it follows the finger that opened it).
+ */
+export function readPresentation(
+  presentation: AdaptivePresentation | undefined,
+  {whenOmitted = 'popover', view, compact}: ReadPresentationOptions,
+): ResolvedPresentation {
+  const target =
+    view === undefined ? (typeof window === 'undefined' ? null : window) : view;
+  return resolvePresentation(
+    presentation,
+    readTouchPresentation(target, compact),
+    whenOmitted,
+  );
+}

package/src/utils/pressPaintPriority.test.ts

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file pressPaintPriority.test.ts
+ * @input Uses vitest, Babel with the StyleX plugin (the repository's shared
+ *   module resolution) and interactionOverlay.stylex.ts
+ * @output Checks, in the compiled CSS, that the press paint outranks the
+ *   coarse-pointer `:active` reset of the overlay
+ * @position Regression test for the cascade order of the press overlay
+ *
+ * WebKit applies `:active` during a touch. Under a coarse pointer the overlay
+ * turns the bare `:active` image off, and the press paint
+ * (`[data-astryx-press="on"]`) must still win: its rule has to sit in a
+ * higher StyleX priority than the reset. The order is a property of how
+ * each key is spelled: an imported `defineConsts` key compiles to a higher
+ * priority than the same literal, which put the reset above the paint and
+ * erased the touch-down frame.
+ */
+
+import fs from 'node:fs';
+import {createRequire} from 'node:module';
+import path from 'node:path';
+import {describe, expect, it} from 'vitest';
+import stylexResolution from '../../../../scripts/stylex-module-resolution.cjs';
+
+type Rule = [string, {ltr: string}, number];
+
+// Babel's types are not part of core's typecheck; type the one call used.
+const {transformSync} = createRequire(import.meta.url)('@babel/core') as {
+  transformSync: (
+    code: string,
+    options: Record<string, unknown>,
+  ) => {metadata?: unknown} | null;
+};
+
+function compiledRules(file: string): Rule[] {
+  const output = transformSync(fs.readFileSync(file, 'utf8'), {
+    filename: file,
+    babelrc: false,
+    configFile: false,
+    parserOpts: {plugins: ['typescript', 'jsx']},
+    plugins: [
+      [
+        '@stylexjs/babel-plugin',
+        {
+          dev: false,
+          runtimeInjection: false,
+          genConditionalClasses: true,
+          treeshakeCompensation: true,
+          unstable_moduleResolution: stylexResolution.stylexModuleResolution,
+        },
+      ],
+    ],
+  });
+  return (output?.metadata as {stylex?: Rule[]}).stylex ?? [];
+}
+
+describe('press overlay cascade', () => {
+  it('ranks the press paint above the coarse-pointer :active reset', () => {
+    const rules = compiledRules(
+      path.resolve(__dirname, 'interactionOverlay.stylex.ts'),
+    );
+    const resets = rules.filter(
+      // Matched without its condition's text: an imported key compiles to a
+      // placeholder until the bundle step.
+      ([, {ltr}]) =>
+        ltr.includes(':active') && ltr.includes('background-image:none'),
+    );
+    const paints = rules.filter(
+      ([, {ltr}]) =>
+        ltr.includes('[data-astryx-press="on"]') &&
+        ltr.includes('background-image:'),
+    );
+    expect(resets.length).toBeGreaterThan(0);
+    expect(paints.length).toBeGreaterThan(0);
+    const highestReset = Math.max(...resets.map(([, , priority]) => priority));
+    const lowestPaint = Math.min(...paints.map(([, , priority]) => priority));
+    expect(highestReset).toBeLessThan(lowestPaint);
+  });
+});

package/src/utils/primaryClick.test.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file primaryClick.test.ts
+ * @input isPrimaryClick over button presses on Apple and other platforms
+ * @output Tests that only the main button, and not a ctrl-click on macOS,
+ *   is a primary click (spec:AST-094 FR43)
+ * @position Unit tests of packages/core/src/utils/primaryClick.ts
+ */
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {isPrimaryClick} from './primaryClick';
+
+function onPlatform(platform: string) {
+  vi.spyOn(navigator, 'platform', 'get').mockReturnValue(platform);
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('isPrimaryClick (spec:AST-094 FR43)', () => {
+  it('takes the main button, and no right click or pen barrel button', () => {
+    onPlatform('Win32');
+    expect(isPrimaryClick({button: 0, ctrlKey: false})).toBe(true);
+    expect(isPrimaryClick({button: 2, ctrlKey: false})).toBe(false);
+    expect(isPrimaryClick({button: 1, ctrlKey: false})).toBe(false);
+  });
+
+  it("takes no ctrl-click on macOS, that platform's context click, and a ctrl-click elsewhere", () => {
+    onPlatform('MacIntel');
+    expect(isPrimaryClick({button: 0, ctrlKey: true})).toBe(false);
+    expect(isPrimaryClick({button: 0, ctrlKey: false})).toBe(true);
+    vi.restoreAllMocks();
+    onPlatform('Win32');
+    expect(isPrimaryClick({button: 0, ctrlKey: true})).toBe(true);
+  });
+});

package/src/utils/primaryClick.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file primaryClick.ts
+ * @input A mouse or pen button press: its `button` and `ctrlKey`
+ * @output Exports isPrimaryClick
+ * @position Internal util, the one primary-click rule: the gesture host
+ *   starts a press only for one, and the press controller paints only one;
+ *   platform detection is utils/isApplePlatform.ts
+ *
+ * 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 {isApplePlatform} from './isApplePlatform';
+
+/**
+ * Whether a button press is a primary click: the main button, and not a
+ * ctrl-click on macOS or iPadOS, which is that platform's context click
+ * (`spec:AST-094` FR43). A right click, a pen's barrel button and a macOS
+ * ctrl-click start no press.
+ */
+export function isPrimaryClick(event: {
+  readonly button: number;
+  readonly ctrlKey: boolean;
+}): boolean {
+  return event.button === 0 && !(event.ctrlKey && isApplePlatform());
+}

package/src/utils/timeFormat.test.ts

@@ -0,0 +1,204 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file timeFormat.test.ts
+ * @input Uses vitest and the timeFormat helpers
+ * @output Unit tests for locale hour cycles, locale time text, and parsing it back
+ * @position Testing; validates utils/timeFormat.ts
+ *
+ * SYNC: When timeFormat.ts changes, update tests to match new behavior
+ */
+
+import {describe, expect, it} from 'vitest';
+import {
+  formatLocaleTime,
+  parseLocaleTime,
+  resolveHourFormat,
+  type HourFormat,
+} from './timeFormat';
+import {parseTimeInput, type ISOTimeString} from './timeParser';
+
+const iso = (time: string) => time as ISOTimeString;
+
+describe('resolveHourFormat', () => {
+  it.each([
+    ['en', '12h'],
+    ['en-US', '12h'],
+    ['ko-KR', '12h'],
+    ['en-GB', '24h'],
+    ['de-DE', '24h'],
+    ['vi-VN', '24h'],
+    ['fr-FR', '24h'],
+  ] as const)('reads the hour cycle of %s as %s', (locale, expected) => {
+    expect(resolveHourFormat(locale)).toBe(expected);
+  });
+
+  it('honors a -u-hc- preference carried on the locale tag', () => {
+    expect(resolveHourFormat('en-US-u-hc-h23')).toBe('24h');
+    expect(resolveHourFormat('de-DE-u-hc-h12')).toBe('12h');
+  });
+
+  it('lets an explicit hour format win over the locale', () => {
+    expect(resolveHourFormat('de-DE', '12h')).toBe('12h');
+    expect(resolveHourFormat('en-US', '24h')).toBe('24h');
+  });
+
+  it('falls back to twelve-hour for a malformed tag', () => {
+    expect(resolveHourFormat('not a locale')).toBe('12h');
+  });
+});
+
+describe('formatLocaleTime', () => {
+  it('keeps the released English text exactly, with a plain space', () => {
+    expect(formatLocaleTime(iso('14:30'), 'en', '12h')).toBe('2:30 PM');
+    expect(formatLocaleTime(iso('00:05'), 'en', '12h')).toBe('12:05 AM');
+    expect(formatLocaleTime(iso('14:30:05'), 'en', '12h', true)).toBe(
+      '2:30:05 PM',
+    );
+    expect(formatLocaleTime(iso('09:05'), 'en', '24h')).toBe('09:05');
+    expect(formatLocaleTime(iso('09:05:07'), 'en', '24h', true)).toBe(
+      '09:05:07',
+    );
+  });
+
+  it("uses the locale's day-period words and their position", () => {
+    expect(formatLocaleTime(iso('14:30'), 'ko-KR', '12h')).toBe('오후 2:30');
+    expect(formatLocaleTime(iso('09:05'), 'zh-CN', '12h')).toBe('上午9:05');
+    expect(formatLocaleTime(iso('14:30'), 'es-ES', '12h')).toBe('2:30 p. m.');
+  });
+
+  it('writes noon as 12 in a twelve-hour reading, not 0', () => {
+    expect(formatLocaleTime(iso('12:30'), 'ja-JP', '12h')).toBe('午後12:30');
+  });
+
+  it('writes English twelve-hour text when the locale would drop the day period', () => {
+    // fr-CM's twelve-hour reading writes 02:30 and 14:30 both as "2:30".
+    expect(formatLocaleTime(iso('14:30'), 'fr-CM', '12h')).toBe('2:30 PM');
+    expect(formatLocaleTime(iso('02:30'), 'fr-CM', '12h')).toBe('2:30 AM');
+    expect(formatLocaleTime(iso('14:30'), 'fr-CM', '24h')).toBe('14:30');
+  });
+
+  it("uses the locale's separator and digits", () => {
+    expect(formatLocaleTime(iso('14:30'), 'fi-FI', '24h')).toBe('14.30');
+    expect(formatLocaleTime(iso('14:30'), 'ar-EG', '12h')).toBe('٢:٣٠ م');
+  });
+
+  it('returns empty text for an empty or malformed time', () => {
+    expect(formatLocaleTime(undefined, 'en', '12h')).toBe('');
+    expect(formatLocaleTime(iso('25:00'), 'en', '12h')).toBe('');
+  });
+});
+
+describe('parseLocaleTime', () => {
+  const LOCALES = [
+    'en-US',
+    'en-GB',
+    'de-DE',
+    'fi-FI',
+    'fr-CA',
+    'es-ES',
+    'sv-SE',
+    'vi-VN',
+    'ja-JP',
+    'ko-KR',
+    'zh-TW',
+    'ar-EG',
+    'fa-IR',
+    'he-IL',
+    // Twelve-hour readings whose separators or surrounding words differ from
+    // the twenty-four-hour reading: a dot (as, nds), "h" (oc), a word between
+    // the day period and the hour (brx, ee), a word before the hour (dz, nds,
+    // tok), and Tibetan digits (dz).
+    'as',
+    'brx',
+    'dz',
+    'ee',
+    'nds',
+    'oc',
+    'tok',
+    // A one-letter day period that English input contains ("m" in "pm").
+    'gd',
+    // A twelve-hour reading with no day period at all.
+    'fr-CM',
+  ];
+  const TIMES = ['00:00', '00:30', '09:05', '11:59', '12:00', '12:30', '23:45'];
+  const FORMATS: HourFormat[] = ['12h', '24h'];
+
+  it.each(LOCALES)('reads back every time %s writes', locale => {
+    for (const hourFormat of FORMATS) {
+      for (const time of TIMES) {
+        const text = formatLocaleTime(iso(time), locale, hourFormat);
+        expect(
+          parseLocaleTime(text, locale),
+          `${locale} ${hourFormat} "${text}"`,
+        ).toBe(time);
+      }
+      const withSeconds = formatLocaleTime(
+        iso('14:30:05'),
+        locale,
+        hourFormat,
+        true,
+      );
+      expect(parseLocaleTime(withSeconds, locale, true)).toBe('14:30:05');
+    }
+  });
+
+  it('reads a spaced day period as the half of the day it names', () => {
+    // Previously parsed as 02:30: the English matcher missed "p. m.".
+    expect(parseLocaleTime('2:30 p. m.', 'es-ES')).toBe('14:30');
+    expect(parseLocaleTime('午後2:30', 'ja-JP')).toBe('14:30');
+  });
+
+  it('reads twelve-hour text whose pattern differs from the 24-hour one', () => {
+    expect(parseLocaleTime('অপৰাহ্ন ২.৩০', 'as')).toBe('14:30');
+    expect(parseLocaleTime('ɣetrɔ ga 2:30', 'ee')).toBe('14:30');
+    expect(parseLocaleTime('Klock 2.30:05 PM', 'nds', true)).toBe('14:30:05');
+    expect(parseLocaleTime('2h30:05 PM', 'oc', true)).toBe('14:30:05');
+  });
+
+  it("reads the locale's separator", () => {
+    // Previously "14.30" read only its "14" prefix.
+    expect(parseLocaleTime('14.30', 'fi-FI')).toBe('14:30');
+    expect(parseLocaleTime('14 h 30', 'fr-CA')).toBe('14:30');
+  });
+
+  it('does not read a day-period word out of the middle of an English word', () => {
+    // gd writes the morning as "m": the "m" of "pm" is not that word.
+    expect(parseLocaleTime('2:30 PM', 'gd')).toBe('14:30');
+    expect(parseLocaleTime('12:00 PM', 'gd')).toBe('12:00');
+    expect(parseLocaleTime('2pm', 'gd')).toBe('14:00');
+    expect(parseLocaleTime('2:30 p.m', 'gd')).toBe('14:30');
+    expect(parseLocaleTime('12:00 p.m', 'gd')).toBe('12:00');
+    expect(parseLocaleTime('2 p.m', 'gd')).toBe('14:00');
+    expect(parseLocaleTime('11 a.m', 'gd')).toBe('11:00');
+    expect(parseLocaleTime('2:30m', 'gd')).toBe('02:30');
+  });
+
+  it('still reads English input in every locale exactly as before', () => {
+    const inputs = [
+      '2:30 PM',
+      '2:30 p.m',
+      '2:30 p.m.',
+      '12:00 PM',
+      '12:00 AM',
+      '2pm',
+      '2 p.m',
+      '11 a.m',
+      '14:30',
+      '1430',
+    ];
+    for (const locale of LOCALES) {
+      for (const input of inputs) {
+        expect(parseLocaleTime(input, locale), `${locale} "${input}"`).toBe(
+          parseTimeInput(input),
+        );
+      }
+    }
+  });
+
+  it('rejects text no reading fits', () => {
+    expect(parseLocaleTime('', 'en-US')).toBeNull();
+    expect(parseLocaleTime('25:99', 'de-DE')).toBeNull();
+    expect(parseLocaleTime('午後14:30', 'ja-JP')).toBeNull();
+  });
+});