@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/src/hooks/useImageMode.test.ts

@@ -0,0 +1,133 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useImageMode.test.ts
+ * @input Uses vitest, @testing-library/react, useImageMode hook
+ * @output Unit tests for useImageMode hook
+ * @position Testing; validates useImageMode.ts pixel-sampling + CORS behavior
+ *
+ * SYNC: When useImageMode.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {renderHook, waitFor, act} from '@testing-library/react';
+import {useImageMode} from './useImageMode';
+
+// jsdom has no fetch/createImageBitmap/OffscreenCanvas — stub them per test so
+// we can exercise the sampling path and the cross-origin failure path.
+
+/** Fill the sampled canvas with a flat RGB so perceptualLightness is deterministic. */
+function stubSamplingPipeline(rgb: [number, number, number]) {
+  // fetch resolves to a blob (same-origin / CORS-enabled image)
+  vi.stubGlobal(
+    'fetch',
+    vi.fn(async () => ({blob: async () => ({}) as Blob})),
+  );
+  vi.stubGlobal(
+    'createImageBitmap',
+    vi.fn(async () => ({width: 100, height: 100}) as ImageBitmap),
+  );
+  const [r, g, b] = rgb;
+  class FakeOffscreenCanvas {
+    constructor(
+      public width: number,
+      public height: number,
+    ) {}
+    getContext() {
+      return {
+        drawImage: vi.fn(),
+        getImageData: (_x: number, _y: number, w: number, h: number) => {
+          const data = new Uint8ClampedArray(w * h * 4);
+          for (let i = 0; i < data.length; i += 4) {
+            data[i] = r;
+            data[i + 1] = g;
+            data[i + 2] = b;
+            data[i + 3] = 255;
+          }
+          return {data};
+        },
+      };
+    }
+  }
+  vi.stubGlobal('OffscreenCanvas', FakeOffscreenCanvas);
+}
+
+/** Simulate a cross-origin image with no CORS headers: fetch rejects. */
+function stubCorsBlockedFetch() {
+  vi.stubGlobal(
+    'fetch',
+    vi.fn(async () => {
+      throw new TypeError(
+        'Failed to fetch: No Access-Control-Allow-Origin header',
+      );
+    }),
+  );
+  vi.stubGlobal('createImageBitmap', vi.fn());
+  vi.stubGlobal('OffscreenCanvas', class {});
+}
+
+describe('useImageMode', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('returns the fallback while no src is provided', () => {
+    const {result} = renderHook(() => useImageMode(null, {fallback: 'dark'}));
+    expect(result.current).toBe('dark');
+  });
+
+  it('samples a dark image and reports "dark"', async () => {
+    stubSamplingPipeline([10, 10, 10]);
+    const {result} = renderHook(() =>
+      useImageMode('data:image/png;base64,AAAA'),
+    );
+    await waitFor(() => expect(result.current).toBe('dark'));
+  });
+
+  it('samples a light image and reports "light"', async () => {
+    stubSamplingPipeline([240, 240, 240]);
+    const {result} = renderHook(() =>
+      useImageMode('data:image/png;base64,AAAA'),
+    );
+    await waitFor(() => expect(result.current).toBe('light'));
+  });
+
+  // ── Reproduction for BB-001 (cluster C6) ────────────────────────────────
+  // A cross-origin image with no `Access-Control-Allow-Origin` header cannot be
+  // fetched with `mode: 'cors'`, so the APCA sampling pipeline never runs and the
+  // hook silently stays on its fallback. This is why image-backed Thumbnail
+  // overlay/remove-button contrast is unreliable for hosted demo examples that
+  // point `src` at a non-CORS CDN URL.
+  it('stays on fallback when a cross-origin image cannot be sampled (CORS)', async () => {
+    stubCorsBlockedFetch();
+    const {result} = renderHook(() =>
+      useImageMode(
+        'https://lookaside.facebook.com/assets/astryx/moody-scene-vertical-2.png',
+        {fallback: null},
+      ),
+    );
+    // Give the rejected fetch + state update a chance to flush.
+    await act(async () => {
+      await new Promise(r => setTimeout(r, 0));
+    });
+    expect(result.current).toBeNull();
+  });
+
+  it('requests the image with CORS mode (the constraint that fails for non-CORS hosts)', async () => {
+    const fetchSpy = vi.fn(async () => {
+      throw new TypeError('CORS');
+    });
+    vi.stubGlobal('fetch', fetchSpy);
+    vi.stubGlobal('createImageBitmap', vi.fn());
+    vi.stubGlobal('OffscreenCanvas', class {});
+    renderHook(() => useImageMode('https://cross-origin.example/x.png'));
+    await waitFor(() => expect(fetchSpy).toHaveBeenCalled());
+    expect(fetchSpy).toHaveBeenCalledWith(
+      'https://cross-origin.example/x.png',
+      {mode: 'cors'},
+    );
+  });
+});

package/src/hooks/useKeyboardHint.doc.mjs

@@ -0,0 +1,101 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').HookDoc} */
+export const docs = {
+  name: 'useKeyboardHint',
+  displayName: 'useKeyboardHint',
+  keywords: ['keyboard', 'hint', 'arrow', 'navigation', 'roving', 'tabindex', 'focus', 'discoverability', 'toolbar', 'tabs', 'segmented', 'affordance', 'a11y'],
+  params: [
+    {
+      name: 'options',
+      type: 'UseKeyboardHintOptions',
+      description: 'Configuration object for the keyboard hint.',
+      required: false,
+    },
+    {
+      name: 'options.orientation',
+      type: "'horizontal' | 'vertical' | 'both'",
+      description: 'Which arrow-key axis the composite navigates, controlling which arrow icons the hint shows (← → for horizontal, ↑ ↓ for vertical, all four for both).',
+      default: "'horizontal'",
+      required: false,
+    },
+    {
+      name: 'options.dismissAfterMs',
+      type: 'number',
+      description: 'Milliseconds before the hint auto-dismisses after appearing.',
+      default: '3000',
+      required: false,
+    },
+    {
+      name: 'options.isEnabled',
+      type: 'boolean',
+      description: 'Whether the hint is enabled. Set to false to suppress it for a specific instance (e.g. a disabled or read-only widget).',
+      default: 'true',
+      required: false,
+    },
+  ],
+  returns: [
+    {
+      name: 'hintElement',
+      type: 'ReactNode',
+      description: 'The popover hint element to render inside the composite container (as the last child). Portals to the top layer via popover="manual", renders arrow keys with Kbd, and manages its own visibility — render it unconditionally.',
+    },
+    {
+      name: 'onFocus',
+      type: '(e: React.FocusEvent) => void',
+      description: 'Attach to the container onFocus. Shows the hint on the first keyboard-focus (:focus-visible) entry from outside the composite.',
+    },
+    {
+      name: 'onBlur',
+      type: '(e: React.FocusEvent) => void',
+      description: 'Attach to the container onBlur. Hides the hint when focus leaves the composite entirely, and re-anchors when focus moves within.',
+    },
+    {
+      name: 'onKeyDown',
+      type: '(e: React.KeyboardEvent) => void',
+      description: 'Attach to the container onKeyDown. Dismisses the hint on the first arrow press (the user has discovered the interaction). Never prevents default or stops propagation.',
+    },
+  ],
+  usage: {
+    description:
+      'Shows an ephemeral "← → to navigate" hint anchored to the focused item the first time a roving-tabindex composite (Toolbar, TabList, SegmentedControl, etc.) receives keyboard focus. It teaches sighted keyboard users that arrow keys move within the group. The hint renders arrow keys with Kbd in the top layer (popover="manual") and is CSS-anchor-positioned to the focused element, so overflow containers never clip it. It auto-dismisses on the first arrow press, on timeout, or on blur, and does not re-show for that instance. Toolbar, TabList, and SegmentedControl wire this in automatically — reach for the hook directly only when building a custom roving-tabindex widget.',
+    bestPractices: [
+      { guidance: true, description: 'Compose the returned onFocus/onKeyDown with your existing focus handlers rather than replacing them — call onKeyDown first (it only dismisses, never prevents), then your navigation handler.' },
+      { guidance: true, description: 'Render hintElement as the last child of the composite container; it is position:fixed in the top layer and aria-hidden, so it never affects layout or the accessibility tree.' },
+      { guidance: true, description: 'Match orientation to the arrow keys your widget actually responds to so the hint shows the correct icons.' },
+      { guidance: false, description: 'Use for single controls or widgets without roving-tabindex navigation — the hint only makes sense where arrows move focus within a group.' },
+    ],
+  },
+  relatedComponents: ['Toolbar', 'TabList', 'SegmentedControl'],
+  relatedHooks: ['useListFocus', 'useGridFocus', 'useTreeFocus'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'focus',
+};
+
+/** @type {import('../docs-types').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Ephemeral "← → to navigate" hint anchored to the focused item on first keyboard focus of a roving-tabindex composite (Toolbar/TabList/SegmentedControl). Teaches sighted keyboard users that arrows move within the group. Kbd-rendered arrows in a top-layer popover="manual", CSS-anchor-positioned (never clipped by overflow), aria-hidden. Auto-dismisses on first arrow press, timeout, or blur; never re-shows for that instance.',
+  paramDescriptions: {
+    options: 'config for the keyboard hint.',
+    'options.orientation': "arrow axis: 'horizontal' (← →), 'vertical' (↑ ↓), 'both' (all four). Controls shown icons.",
+    'options.dismissAfterMs': 'ms before auto-dismiss after appearing.',
+    'options.isEnabled': 'whether the hint is enabled; false suppresses it (e.g. disabled/read-only widget).',
+  },
+  returnDescriptions: {
+    hintElement: 'popover hint to render as last child of the container. Kbd-rendered arrows, top-layer, self-managing — render unconditionally.',
+    onFocus: 'container onFocus: shows hint on first :focus-visible entry from outside.',
+    onBlur: 'container onBlur: hides on leaving the composite; re-anchors on internal moves.',
+    onKeyDown: 'container onKeyDown: dismisses on first arrow press. Never prevents default.',
+  },
+  usage: {
+    description:
+      'Ephemeral "← → to navigate" hint on first keyboard focus of a roving-tabindex composite. Top-layer anchored popover, aria-hidden. Auto-dismisses on first arrow press, timeout, or blur; no re-show. Toolbar/TabList/SegmentedControl wire it in automatically.',
+    bestPractices: [
+      { guidance: true, description: 'Compose returned onFocus/onKeyDown with existing handlers (call onKeyDown first — it only dismisses).' },
+      { guidance: true, description: 'Render hintElement as last child; top-layer + aria-hidden, no layout/a11y impact.' },
+      { guidance: true, description: 'Match orientation to the arrows the widget responds to.' },
+      { guidance: false, description: 'Use for single controls / non-roving widgets.' },
+    ],
+  },
+};

package/src/hooks/useKeyboardHint.test.tsx

@@ -0,0 +1,70 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useKeyboardHint.test.tsx
+ * @input Uses React Testing Library, useKeyboardHint
+ * @output Unit tests for keyboard hint rendering
+ */
+
+import {render} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {useKeyboardHint, type KeyboardHintOrientation} from './useKeyboardHint';
+
+function TestHint({orientation}: {orientation?: KeyboardHintOrientation}) {
+  const {hintElement} = useKeyboardHint({orientation});
+  return <div>{hintElement}</div>;
+}
+
+function getKeyLabels(container: HTMLElement): (string | null)[] {
+  return Array.from(container.querySelectorAll('.astryx-kbd')).map(key =>
+    key.getAttribute('aria-label'),
+  );
+}
+
+function getKeyText(container: HTMLElement): string[] {
+  return Array.from(container.querySelectorAll('kbd')).map(
+    key => key.textContent ?? '',
+  );
+}
+
+describe('useKeyboardHint', () => {
+  it('renders horizontal arrow keys with Kbd', () => {
+    const {container} = render(<TestHint orientation="horizontal" />);
+
+    expect(getKeyLabels(container)).toEqual(['Left arrow', 'Right arrow']);
+    expect(getKeyText(container)).toEqual(['←', '→']);
+  });
+
+  it('renders vertical arrow keys with Kbd', () => {
+    const {container} = render(<TestHint orientation="vertical" />);
+
+    expect(getKeyLabels(container)).toEqual(['Up arrow', 'Down arrow']);
+    expect(getKeyText(container)).toEqual(['↑', '↓']);
+  });
+
+  it('renders all arrow keys for both-axis navigation', () => {
+    const {container} = render(<TestHint orientation="both" />);
+
+    expect(getKeyLabels(container)).toEqual([
+      'Left arrow',
+      'Right arrow',
+      'Up arrow',
+      'Down arrow',
+    ]);
+    expect(getKeyText(container)).toEqual(['←', '→', '↑', '↓']);
+  });
+
+  it('positions the hint farther from the anchor', () => {
+    const {container} = render(<TestHint />);
+    const hint = container.querySelector('[popover="manual"]') as HTMLElement;
+
+    expect(hint.style.marginBlockStart).toBe('var(--spacing-2)');
+  });
+
+  it('keeps the hint surface padding after useLayer reset styles', () => {
+    const {container} = render(<TestHint />);
+    const hint = container.querySelector('[popover="manual"]') as HTMLElement;
+
+    expect(hint.className).toContain('useKeyboardHint__styles.hint');
+  });
+});

package/src/hooks/useKeyboardHint.tsx

@@ -0,0 +1,332 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useKeyboardHint.tsx
+ * @input Uses React, StyleX, Kbd, useLayer
+ * @output Exports useKeyboardHint hook — ephemeral arrow-key navigation hint
+ * @position Core hook; shows sighted keyboard users how to navigate composite
+ *   widgets that use roving tabindex (single Tab stop, arrows inside)
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/useKeyboardHint.doc.mjs
+ * - /apps/storybook/stories/useKeyboardHint.stories.tsx
+ * - /packages/cli/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx
+ */
+
+import React, {useCallback, useEffect, useRef, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+  colorVars,
+  radiusVars,
+  shadowVars,
+  spacingVars,
+  typeScaleVars,
+} from '../theme/tokens.stylex';
+import {Kbd} from '../Kbd';
+import {useLayer} from '../Layer/useLayer';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type KeyboardHintOrientation = 'horizontal' | 'vertical' | 'both';
+
+export interface UseKeyboardHintOptions {
+  /**
+   * Orientation of the arrow-key navigation. Controls which arrow icons are
+   * shown in the hint badge.
+   * - `'horizontal'` → ← →
+   * - `'vertical'` → ↑ ↓
+   * - `'both'` → ← → ↑ ↓
+   * @default 'horizontal'
+   */
+  orientation?: KeyboardHintOrientation;
+
+  /**
+   * Milliseconds before the hint auto-dismisses after appearing.
+   * @default 3000
+   */
+  dismissAfterMs?: number;
+
+  /**
+   * Whether the hint is enabled. Set to false to disable for a specific
+   * instance (e.g. when the widget is read-only or the user has dismissed
+   * globally).
+   * @default true
+   */
+  isEnabled?: boolean;
+}
+
+export interface UseKeyboardHintReturn {
+  /**
+   * The popover hint element to render inside your component tree (portals to
+   * top layer via `popover="manual"`). Render unconditionally — it manages its
+   * own visibility.
+   */
+  hintElement: ReactNode;
+
+  /**
+   * Attach to the composite container's `onFocus`. Shows the hint on the first
+   * keyboard-focus (`:focus-visible`) entry from outside.
+   */
+  onFocus: (e: React.FocusEvent) => void;
+
+  /**
+   * Attach to the composite container's `onBlur`. Hides the hint when focus
+   * leaves the composite entirely.
+   */
+  onBlur: (e: React.FocusEvent) => void;
+
+  /**
+   * Attach to the composite container's `onKeyDown`. Dismisses the hint on the
+   * first arrow press (the user discovered the interaction).
+   */
+  onKeyDown: (e: React.KeyboardEvent) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Styles
+// ---------------------------------------------------------------------------
+
+const ARROW_KEYS = new Set(['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown']);
+
+const ARROW_HINT_KEYS: Record<
+  KeyboardHintOrientation,
+  ReadonlyArray<string>
+> = {
+  horizontal: ['left', 'right'],
+  vertical: ['up', 'down'],
+  both: ['left', 'right', 'up', 'down'],
+};
+
+const styles = stylex.create({
+  hint: {
+    // Top layer + anchor positioned
+    position: 'fixed',
+    inset: 'auto',
+    margin: 0,
+    border: 'none',
+
+    // Surface
+    backgroundColor: colorVars['--color-background-popover'],
+    borderRadius: radiusVars['--radius-element'],
+    boxShadow: shadowVars['--shadow-low'],
+    paddingBlockStart: spacingVars['--spacing-1'],
+    paddingBlockEnd: spacingVars['--spacing-1'],
+    paddingInlineStart: spacingVars['--spacing-2'],
+    paddingInlineEnd: spacingVars['--spacing-2'],
+
+    // Typography
+    fontSize: typeScaleVars['--text-supporting-size'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
+    color: colorVars['--color-text-secondary'],
+    whiteSpace: 'nowrap',
+
+    // Animation
+    opacity: {
+      default: 0,
+      ':popover-open': 1,
+    },
+    transitionProperty: 'opacity, display, overlay',
+    transitionDuration: '150ms',
+    transitionBehavior: 'allow-discrete',
+
+    // Don't capture pointer events (hint floats above content)
+    pointerEvents: 'none',
+  },
+  keys: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+  },
+  label: {
+    marginInlineStart: spacingVars['--spacing-1'],
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Shows an ephemeral visual hint ("← → to navigate") anchored to the focused
+ * item when a composite widget first receives keyboard focus. Teaches sighted
+ * keyboard users that arrows navigate within the group.
+ *
+ * The hint renders in the top layer (popover="manual") and is CSS-anchor-
+ * positioned to the currently focused element, so it is never clipped by
+ * overflow containers. It auto-dismisses on first arrow press, timeout, or
+ * blur, and does not re-show for that instance.
+ *
+ * @example
+ * ```
+ * const hint = useKeyboardHint({orientation: 'horizontal'});
+ * <div role="toolbar" onFocus={hint.onFocus} onBlur={hint.onBlur} onKeyDown={hint.onKeyDown}>
+ *   {children}
+ *   {hint.hintElement}
+ * </div>
+ * ```
+ */
+export function useKeyboardHint(
+  options: UseKeyboardHintOptions = {},
+): UseKeyboardHintReturn {
+  const {
+    orientation = 'horizontal',
+    dismissAfterMs = 3000,
+    isEnabled = true,
+  } = options;
+
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const dismissedRef = useRef(false);
+  const isVisibleRef = useRef(false);
+  const layerAnchorRef = useRef<(el: HTMLElement | null) => void>(() => {});
+
+  const clearDismissTimeout = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  }, []);
+
+  const handleLayerShow = useCallback(() => {
+    isVisibleRef.current = true;
+  }, []);
+
+  const handleLayerHide = useCallback(() => {
+    isVisibleRef.current = false;
+    clearDismissTimeout();
+    layerAnchorRef.current(null);
+  }, [clearDismissTimeout]);
+
+  const layer = useLayer({
+    mode: 'context',
+    onShow: handleLayerShow,
+    onHide: handleLayerHide,
+  });
+  layerAnchorRef.current = layer.ref;
+
+  // Hide + mark dismissed (won't re-show for this instance)
+  const dismiss = useCallback(() => {
+    dismissedRef.current = true;
+    clearDismissTimeout();
+    layer.hide();
+    isVisibleRef.current = false;
+    layerAnchorRef.current(null);
+  }, [clearDismissTimeout, layer]);
+
+  // Show the layer anchored to the focused element
+  const show = useCallback(
+    (anchor: HTMLElement) => {
+      if (dismissedRef.current || !isEnabled) {
+        return;
+      }
+
+      layerAnchorRef.current(anchor);
+      layer.show();
+
+      clearDismissTimeout();
+      timeoutRef.current = setTimeout(() => {
+        dismiss();
+      }, dismissAfterMs);
+    },
+    [clearDismissTimeout, dismiss, dismissAfterMs, isEnabled, layer],
+  );
+
+  // Cleanup on unmount
+  useEffect(
+    () => () => {
+      clearDismissTimeout();
+      layerAnchorRef.current(null);
+    },
+    [clearDismissTimeout],
+  );
+
+  // --- Handlers ---
+
+  const onFocus = useCallback(
+    (e: React.FocusEvent) => {
+      if (dismissedRef.current || !isEnabled) {
+        return;
+      }
+      // Only show on keyboard focus (focus-visible)
+      const target = e.target as HTMLElement;
+      if (!target.matches(':focus-visible')) {
+        return;
+      }
+      // Only show when focus enters from outside the container
+      const container = e.currentTarget as HTMLElement;
+      if (
+        e.relatedTarget instanceof Node &&
+        container.contains(e.relatedTarget)
+      ) {
+        return;
+      }
+      show(target);
+    },
+    [show, isEnabled],
+  );
+
+  const onBlur = useCallback(
+    (e: React.FocusEvent) => {
+      if (!isVisibleRef.current) {
+        return;
+      }
+      const container = e.currentTarget as HTMLElement;
+      // Only dismiss when focus leaves the container entirely
+      if (
+        e.relatedTarget instanceof Node &&
+        container.contains(e.relatedTarget)
+      ) {
+        // Focus moved within — re-anchor to the new target
+        if (!dismissedRef.current && e.relatedTarget instanceof HTMLElement) {
+          layerAnchorRef.current(e.relatedTarget);
+        }
+        return;
+      }
+      dismiss();
+    },
+    [dismiss],
+  );
+
+  const onKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (!isVisibleRef.current) {
+        return;
+      }
+      if (ARROW_KEYS.has(e.key)) {
+        dismiss();
+      }
+    },
+    [dismiss],
+  );
+
+  // --- Render the hint element ---
+
+  const arrowContent = (
+    <span {...stylex.props(styles.keys)}>
+      {ARROW_HINT_KEYS[orientation].map(key => (
+        <Kbd key={key} keys={key} />
+      ))}
+    </span>
+  );
+
+  const hintElement = layer.render(
+    <span aria-hidden="true">
+      {arrowContent}
+      <span {...stylex.props(styles.label)}>to navigate</span>
+    </span>,
+    {
+      placement: 'below',
+      alignment: 'start',
+      xstyle: styles.hint,
+      style: {
+        marginBlockStart: spacingVars['--spacing-2'],
+      },
+    },
+  );
+
+  return {hintElement, onFocus, onBlur, onKeyDown};
+}