@astryxdesign/core 0.7.4 → 0.7.5-canary.031a639

package/src/utils/touchPresentation.test.ts

@@ -0,0 +1,323 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file touchPresentation.test.ts
+ * @input Uses vitest, React Testing Library, react-dom/server and a
+ *   query-aware matchMedia stub
+ * @output The touch presentation's answers: touch from the primary pointer,
+ *   compact from the width, both for presentations, the same answer on every
+ *   engine; the server default and hints; live updates; the one-moment read;
+ *   core's compact-touch media keys and iOS style-gate keys spelled and nested
+ *   as the shared queries; the adaptive presentation reading them
+ * @position Unit tests of packages/core/src/utils/touchPresentation.ts
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {act, renderHook} from '@testing-library/react';
+import {createElement, type ComponentProps, type ReactNode} from 'react';
+import {renderToString} from 'react-dom/server';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {
+  COMPACT_TOUCH_PRESENTATION_QUERY,
+  useAdaptivePresentation,
+} from '../hooks/useAdaptivePresentation';
+import {DEFAULT_COMPACT_DEFINITION} from '../theme/themeAdaptations';
+import {Theme, defineTheme} from '../theme';
+import {
+  COMPACT_QUERY,
+  COMPACT_TOUCH_QUERY,
+  IOS_SUPPORTS_QUERY,
+  IOS_TOUCH_STYLE_KEYS,
+  TOUCH_QUERY,
+  readTouchPresentation,
+  useTouchPresentation,
+} from './touchPresentation';
+
+/**
+ * A device: what its primary pointer is, how big its viewport is, and
+ * whether its engine is iOS WebKit (implements -webkit-touch-callout).
+ */
+const device = {coarse: false, width: 1280, height: 800, iosWebKit: false};
+const listeners = new Set<() => void>();
+
+/** Answers a media query list: `,` is or, `and` is and. */
+function answer(query: string): boolean {
+  return query.split(', ').some(alternative =>
+    alternative.split(' and ').every(part => {
+      if (part === '(pointer: coarse)') {
+        return device.coarse;
+      }
+      const range = /^\((width|height) < (\d+)px\)$/.exec(part);
+      if (range != null) {
+        return device[range[1] as 'width' | 'height'] < Number(range[2]);
+      }
+      throw new Error(`unexpected query ${query}`);
+    }),
+  );
+}
+
+function setDevice(next: Partial<typeof device>): void {
+  Object.assign(device, next);
+  for (const listener of [...listeners]) {
+    listener();
+  }
+}
+
+beforeEach(() => {
+  setDevice({coarse: false, width: 1280, height: 800, iosWebKit: false});
+  vi.stubGlobal('CSS', {
+    supports: (condition: string) =>
+      condition === IOS_SUPPORTS_QUERY && device.iosWebKit,
+  });
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn((query: string) => ({
+      get matches() {
+        return answer(query);
+      },
+      media: query,
+      addEventListener: (_type: string, listener: () => void) =>
+        listeners.add(listener),
+      removeEventListener: (_type: string, listener: () => void) =>
+        listeners.delete(listener),
+    })),
+  );
+});
+
+afterEach(() => {
+  listeners.clear();
+  vi.unstubAllGlobals();
+});
+
+describe('touch presentation', () => {
+  it('keys touch on the primary pointer and compact on the width', () => {
+    const {result} = renderHook(() => useTouchPresentation());
+    expect(result.current).toEqual({
+      isTouch: false,
+      isCompact: false,
+    });
+    // A tablet: a finger at any width.
+    act(() => setDevice({coarse: true, width: 1024, height: 1366}));
+    expect(result.current).toEqual({
+      isTouch: true,
+      isCompact: false,
+    });
+    // A narrowed desktop window: compact, still a mouse.
+    act(() => setDevice({coarse: false, width: 600, height: 900}));
+    expect(result.current).toEqual({
+      isTouch: false,
+      isCompact: true,
+    });
+    // A phone: both.
+    act(() => setDevice({coarse: true, width: 390, height: 844}));
+    expect(result.current).toEqual({
+      isTouch: true,
+      isCompact: true,
+    });
+  });
+
+  it('answers the same on every engine: iOS WebKit and Android alike', () => {
+    const {result} = renderHook(() => useTouchPresentation());
+    // An Android phone: a finger, no -webkit-touch-callout.
+    act(() => setDevice({coarse: true, width: 412, height: 915}));
+    const android = result.current;
+    // The same phone size in iOS WebKit gets the same answer.
+    act(() => setDevice({iosWebKit: true}));
+    expect(result.current).toEqual(android);
+    expect(result.current).toEqual({isTouch: true, isCompact: true});
+  });
+
+  it('keeps one answer object while nothing changes', () => {
+    const {result, rerender} = renderHook(() => useTouchPresentation());
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
+
+  it('answers the server default, or the server hint, before hydration', () => {
+    const Probe = (props: {hint?: boolean}) => {
+      const presentation = useTouchPresentation(
+        props.hint === true ? {isTouch: true, isCompact: true} : {},
+      );
+      return createElement(
+        'span',
+        null,
+        `${presentation.isTouch}/${presentation.isCompact}`,
+      );
+    };
+    setDevice({iosWebKit: true, coarse: true, width: 390, height: 844});
+    expect(renderToString(createElement(Probe))).toContain('false/false');
+    expect(renderToString(createElement(Probe, {hint: true}))).toContain(
+      'true/true',
+    );
+  });
+
+  it('is the theme compact definition: width below md or height below 500 (spec:AST-012 FR9)', () => {
+    const {result} = renderHook(() => useTouchPresentation());
+    // At the md point and taller than 500: not compact.
+    act(() => setDevice({coarse: true, width: 768, height: 1024}));
+    expect(result.current.isCompact).toBe(false);
+    // One pixel narrower: compact.
+    act(() => setDevice({coarse: true, width: 767, height: 1024}));
+    expect(result.current.isCompact).toBe(true);
+    // A phone in landscape: wide, but shorter than 500.
+    act(() => setDevice({coarse: true, width: 852, height: 393}));
+    expect(result.current.isCompact).toBe(true);
+    // A wide, short window at exactly 500 tall: not compact.
+    act(() => setDevice({coarse: true, width: 1024, height: 500}));
+    expect(result.current.isCompact).toBe(false);
+  });
+
+  it('reads the conditions at one moment, and without a window', () => {
+    setDevice({coarse: true, width: 390, height: 844});
+    expect(readTouchPresentation(window, DEFAULT_COMPACT_DEFINITION)).toEqual({
+      isTouch: true,
+      isCompact: true,
+    });
+    expect(readTouchPresentation(null, DEFAULT_COMPACT_DEFINITION)).toEqual({
+      isTouch: false,
+      isCompact: false,
+    });
+  });
+
+  it('keeps every iOS gate in core spelled and nested as the resolver', () => {
+    // The gate is the media query outside and the supports query inside; a
+    // single supports query that names the pointer never matches anywhere.
+    expect(IOS_TOUCH_STYLE_KEYS).toEqual([
+      '@media (pointer: coarse)',
+      '@supports (-webkit-touch-callout: none)',
+    ]);
+    const root = path.resolve(__dirname, '..');
+    const problems: string[] = [];
+    let gates = 0;
+    const walk = (dir: string): void => {
+      for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          if (entry.name !== '__tests__' && entry.name !== 'node_modules') {
+            walk(full);
+          }
+        } else if (
+          /\.(ts|tsx)$/.test(entry.name) &&
+          !/\.test\.|\.spec\./.test(entry.name) &&
+          entry.name !== 'touchPresentation.ts'
+        ) {
+          const lines = fs.readFileSync(full, 'utf8').split('\n');
+          lines.forEach((line, index) => {
+            for (const match of line.matchAll(/'@supports ([^']*)'/g)) {
+              const where = `${path.relative(root, full)}:${index + 1}`;
+              if (match[1].includes('pointer')) {
+                problems.push(`${where}: @supports ${match[1]} never matches`);
+              }
+              if (!match[1].includes('touch-callout')) {
+                continue;
+              }
+              gates++;
+              if (`@supports ${match[1]}` !== IOS_TOUCH_STYLE_KEYS[1]) {
+                problems.push(`${where}: @supports ${match[1]}`);
+              }
+              const outer = lines
+                .slice(0, index)
+                .reverse()
+                .find(previous => /'@(media|supports) /.test(previous));
+              if (
+                outer == null ||
+                !outer.includes(`'${IOS_TOUCH_STYLE_KEYS[0]}'`)
+              ) {
+                problems.push(
+                  `${where}: not inside ${IOS_TOUCH_STYLE_KEYS[0]}`,
+                );
+              }
+            }
+          });
+        }
+      }
+    };
+    walk(root);
+    expect(problems).toEqual([]);
+    // Core already gates its 16px input floor this way.
+    expect(gates).toBeGreaterThan(0);
+  });
+
+  it('keeps every compact-touch media key in core spelled as the resolver', () => {
+    // A style key that joins a coarse pointer with a width or height is a
+    // presentation decision: it must be the shared query, not its own.
+    const root = path.resolve(__dirname, '..');
+    const found: string[] = [];
+    const walk = (dir: string): void => {
+      for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          if (entry.name !== '__tests__' && entry.name !== 'node_modules') {
+            walk(full);
+          }
+        } else if (
+          /\.(ts|tsx)$/.test(entry.name) &&
+          !/\.test\.|\.spec\./.test(entry.name)
+        ) {
+          const source = fs.readFileSync(full, 'utf8');
+          for (const match of source.matchAll(/'@media ([^']*)'/g)) {
+            const query = match[1];
+            if (
+              query.includes('pointer: coarse') &&
+              /\b(width|height)\b/.test(query)
+            ) {
+              found.push(`${path.relative(root, full)}: ${query}`);
+            }
+          }
+        }
+      }
+    };
+    walk(root);
+    for (const entry of found) {
+      expect(entry.slice(entry.indexOf(': ') + 2), entry).toBe(
+        COMPACT_TOUCH_QUERY,
+      );
+    }
+    expect(TOUCH_QUERY).toBe('(pointer: coarse)');
+    expect(COMPACT_QUERY).toBe(DEFAULT_COMPACT_DEFINITION.query);
+    expect(COMPACT_TOUCH_QUERY).toBe(
+      DEFAULT_COMPACT_DEFINITION.coarsePointerQuery,
+    );
+  });
+
+  it("follows the active theme's md point (spec:AST-012 FR9)", () => {
+    const wideMd = defineTheme({
+      name: 'wide-md-touch',
+      adaptations: {widthBreakpoints: {md: 1000, lg: 1100}},
+    });
+    const wrapper = ({children}: {children: ReactNode}) =>
+      createElement(
+        Theme,
+        {theme: wideMd} as ComponentProps<typeof Theme>,
+        children,
+      );
+    setDevice({coarse: true, width: 900, height: 1024});
+    // Under the default md point (768) this screen is not compact.
+    const plain = renderHook(() => useAdaptivePresentation('adaptive'));
+    expect(plain.result.current).toBe('popover');
+    plain.unmount();
+    // Under a theme whose md is 1000, the same screen is compact.
+    const themed = renderHook(() => useAdaptivePresentation('adaptive'), {
+      wrapper,
+    });
+    expect(themed.result.current).toBe('bottom-sheet');
+    const touch = renderHook(() => useTouchPresentation(), {wrapper});
+    expect(touch.result.current.isCompact).toBe(true);
+  });
+
+  it('is the query the adaptive popover-or-sheet presentation reads', () => {
+    expect(COMPACT_TOUCH_PRESENTATION_QUERY).toBe(COMPACT_TOUCH_QUERY);
+    const {result} = renderHook(() => useAdaptivePresentation('adaptive'));
+    expect(result.current).toBe('popover');
+    act(() => setDevice({coarse: true, width: 390, height: 844}));
+    expect(result.current).toBe('bottom-sheet');
+    // A phone in landscape too.
+    act(() => setDevice({coarse: true, width: 852, height: 393}));
+    expect(result.current).toBe('bottom-sheet');
+    // A tablet at the md point keeps the anchored popover.
+    act(() => setDevice({coarse: true, width: 768, height: 1024}));
+    expect(result.current).toBe('popover');
+  });
+});

package/src/utils/touchPresentation.ts

@@ -0,0 +1,153 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file touchPresentation.ts
+ * @input Uses the SSR-safe useMediaQuery hook and window.matchMedia
+ * @output The one definition of when a component presents itself the touch
+ *   way: TOUCH_QUERY, COMPACT_QUERY, COMPACT_TOUCH_QUERY, the iOS style gate
+ *   (IOS_SUPPORTS_QUERY and its StyleX keys); the hook useTouchPresentation;
+ *   readTouchPresentation for a decision taken at one moment
+ * @position Internal shared resolver beside interactionModality.ts
+ *
+ * Two questions, answered once:
+ *
+ * - TOUCH behaviours (the press model, gesture recognizers, UIKit springs and
+ *   timings) key on the PRIMARY pointer being coarse: a finger. A touchscreen
+ *   laptop reports its trackpad (fine) and keeps pointer behaviours; a tablet
+ *   reports coarse and gets touch ones at any width. Not `hover: none` (some
+ *   touch browsers report hover) and not `any-pointer` (a laptop's touch
+ *   screen is not how it is driven).
+ * - LAYOUT behaviours key on the available size, whatever the pointer:
+ *   the theme's one compact definition (`spec:AST-012` FR9), width below the
+ *   `md` point or height below 500, the same numbers on every platform. A
+ *   phone in landscape is compact by its height; no platform size class is
+ *   consulted.
+ * - A presentation that needs both (a bottom sheet in place of a popover, a
+ *   drilled-in sub-menu in place of a flyout) asks for both.
+ *
+ * Touch behaviour is one model on every touch device, iOS and Android alike;
+ * nothing here chooses a platform. Touch motion reads the theme's motion
+ * roles, whose defaults are the measured table.
+ *
+ * CSS first: a style that changes with these conditions writes the same
+ * query as a StyleX media key, spelled exactly as here (`@media` followed by
+ * the constant's text), so the right rule paints before hydration. The iOS
+ * gate is two nested keys, the media query outside and the supports query
+ * inside (IOS_TOUCH_STYLE_KEYS):
+ *
+ *   '@media (pointer: coarse)': {
+ *     '@supports (-webkit-touch-callout: none)': value,
+ *   },
+ *
+ * One `@supports (-webkit-touch-callout: none) and (pointer: coarse)` never
+ * matches anywhere (`pointer` is not a property), so it is not written. A
+ * test keeps core's compact-touch keys identical to COMPACT_TOUCH_QUERY and
+ * every touch-callout key spelled and nested as above. The iOS style gate
+ * is only for a style iOS WebKit itself requires (core's 16px input floor);
+ * it never selects a behaviour. The keys are literal because the Astryx
+ * StyleX build does not resolve a key shared across files through
+ * `defineConsts`. The hook is for behaviour. It answers the server default
+ * (not touch, not compact) until hydrated unless the caller passes a server
+ * hint, and follows the pointer and size when they change (a tablet docking
+ * a mouse).
+ *
+ * SYNC: When modified, update touchPresentation.test.ts and every StyleX
+ * media key that spells these queries.
+ */
+
+import {useMemo} from 'react';
+import {useMediaQuery} from '../hooks/useMediaQuery';
+import {
+  DEFAULT_COMPACT_DEFINITION,
+  compactDefinition,
+  type CompactDefinition,
+} from '../theme/themeAdaptations';
+import {useThemeDefinition} from '../theme/useTheme';
+
+/** The primary pointer is coarse: touch behaviours. */
+export const TOUCH_QUERY = '(pointer: coarse)';
+
+/**
+ * The viewport is compact at the default width points: layout behaviours
+ * (`spec:AST-012` FR9). A StyleX media key, which cannot read the theme,
+ * spells this; behaviour reads the active theme's definition
+ * (useCompactDefinition), so a theme that moves `md` moves compact with it.
+ */
+export const COMPACT_QUERY = DEFAULT_COMPACT_DEFINITION.query;
+
+/** Both, at the default width points: a sheet in place of a popover. */
+export const COMPACT_TOUCH_QUERY =
+  DEFAULT_COMPACT_DEFINITION.coarsePointerQuery;
+
+/**
+ * The engine is WebKit on iOS or iPadOS: the only one that implements
+ * `-webkit-touch-callout`. For a style iOS WebKit requires, never a
+ * behaviour.
+ */
+export const IOS_SUPPORTS_QUERY = '(-webkit-touch-callout: none)';
+
+/**
+ * The iOS gate as StyleX keys, nested in this order: the media query
+ * outside, the supports query inside.
+ */
+export const IOS_TOUCH_STYLE_KEYS = [
+  `@media ${TOUCH_QUERY}`,
+  `@supports ${IOS_SUPPORTS_QUERY}`,
+] as const;
+
+export interface TouchPresentation {
+  /** The primary pointer is coarse (a finger). */
+  readonly isTouch: boolean;
+  /** The viewport is compact. */
+  readonly isCompact: boolean;
+}
+
+/**
+ * The active theme's compact definition (`spec:AST-012` FR9): width below the
+ * theme's effective `md` point, or height below 500.
+ */
+export function useCompactDefinition(): CompactDefinition {
+  const points = useThemeDefinition()?.__adaptations?.widthBreakpoints;
+  return useMemo(
+    () =>
+      points == null ? DEFAULT_COMPACT_DEFINITION : compactDefinition(points),
+    [points],
+  );
+}
+
+/**
+ * The touch presentation now. SSR-safe: hooks render the server default and
+ * update after hydration.
+ */
+export function useTouchPresentation(
+  serverDefault: Partial<TouchPresentation> = {},
+): TouchPresentation {
+  const compact = useCompactDefinition();
+  const isTouch = useMediaQuery(TOUCH_QUERY, serverDefault.isTouch ?? false);
+  const isCompact = useMediaQuery(
+    compact.query,
+    serverDefault.isCompact ?? false,
+  );
+  return useMemo(() => ({isTouch, isCompact}), [isTouch, isCompact]);
+}
+
+/**
+ * The touch presentation at this moment, for a decision taken once (a menu
+ * deciding how it presents as it opens). `compact` is the active theme's
+ * definition (`useCompactDefinition()`, read while rendering), required so a
+ * theme that moves `md` is never ignored (spec:AST-012 FR9). Not touch and
+ * not compact where there is no window.
+ */
+export function readTouchPresentation(
+  view: Window | null,
+  compact: CompactDefinition,
+): TouchPresentation {
+  if (view == null || typeof view.matchMedia !== 'function') {
+    return {isTouch: false, isCompact: false};
+  }
+  const isTouch = view.matchMedia(TOUCH_QUERY).matches;
+  const isCompact = view.matchMedia(compact.query).matches;
+  return {isTouch, isCompact};
+}