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

package/src/hooks/useHotkeys.ts

@@ -18,7 +18,8 @@
  * unless a hotkey opts in via `allowInInputs`.
  *
  * Platform-aware: `mod` maps to metaKey (⌘) on Apple platforms and
- * ctrlKey elsewhere — mirrors the detection used by Kbd.
+ * ctrlKey elsewhere, through the same isApplePlatform util Kbd reads, so
+ * displayed and handled shortcuts cannot disagree.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
@@ -26,6 +27,7 @@
  */
 
 import {useEffect, useRef} from 'react';
+import {isApplePlatform} from '../utils/isApplePlatform';
 
 /**
  * A single keyboard shortcut registration.
@@ -71,23 +73,6 @@ const KEY_ALIASES: Record<string, string> = {
   plus: '+',
 };
 
-/**
- * Detects whether the current platform is macOS/iOS.
- * Prefers the User-Agent Client Hints API when available (modern Chrome/Edge),
- * falls back to navigator.platform (deprecated but universally supported).
- * Mirrors the detection used by Kbd so displayed and handled shortcuts agree.
- */
-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) {
-    return /mac/i.test((uaData as {platform: string}).platform ?? '');
-  }
-  return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
-}
-
 /**
  * Whether the event target is a typing surface where global shortcuts
  * should stay silent by default.

package/src/hooks/useIndicatorFocusRing.doc.mjs

@@ -0,0 +1,104 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useIndicatorFocusRing',
+  displayName: 'useIndicatorFocusRing',
+  keywords: [
+    'focus ring',
+    'focus',
+    'focus-visible',
+    'outline',
+    'indicator',
+    'checkbox',
+    'radio',
+    'visually hidden input',
+    'keyboard',
+    'accessibility',
+    'a11y',
+    'wcag',
+  ],
+  params: [
+    {
+      name: 'containerRef',
+      type: 'RefObject<HTMLElement | null>',
+      description:
+        'Ref to an element wrapping only the indicator, so its single element child is unambiguously the thing to ring.',
+      required: true,
+    },
+    {
+      name: 'isDisabled',
+      type: 'boolean',
+      description: 'Skip the ring; a disabled control is not focusable.',
+      default: 'false',
+    },
+  ],
+  returns: [
+    {
+      name: 'focusProps',
+      type: '{onFocus: (event: FocusEvent<HTMLElement>) => void; onBlur: () => void}',
+      description: 'Spread onto the element that owns the focusable input.',
+    },
+  ],
+  usage: {
+    description:
+      "Draws the standard focus ring on the indicator of a control whose real input is visually hidden; a checkbox or radio focuses an opacity-0 input, so the ring has to appear on the picture beside it. The ring is painted imperatively on the indicator's own element, which is the only element whose border-radius can shape it, and only on :focus-visible, so pointer clicks stay quiet. Owning it here means a theme-supplied indicator cannot ship a control with no visible focus (WCAG 2.4.7) by ignoring a prop.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Wrap only the indicator in the ref'd element; a wrapper holding label text would ring the whole row.",
+      },
+      {
+        guidance: true,
+        description:
+          'Spread focusProps on the element that contains the hidden input, not on the input itself.',
+      },
+      {
+        guidance: false,
+        description:
+          'Ask a themeable indicator to draw its own focus ring; a replacement that ignores the prop leaves the control with no visible focus.',
+      },
+    ],
+  },
+  relatedComponents: ['CheckboxInput', 'RadioList', 'Selector'],
+  relatedHooks: ['useFocusTrap'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'focus',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Draws the standard focus ring on the indicator of a control whose input is visually hidden (checkbox / radio). Painted imperatively on the indicator element (only element whose border-radius shapes the outline), on :focus-visible only.',
+  paramDescriptions: {
+    containerRef:
+      'ref to element wrapping ONLY the indicator; its single element child gets the ring.',
+    isDisabled: 'skip the ring; disabled control is not focusable.',
+  },
+  returnDescriptions: {
+    focusProps:
+      'onFocus / onBlur to spread onto the element owning the focusable input.',
+  },
+  usage: {
+    description:
+      'Owner draws the ring so a theme-supplied indicator cannot ship a control w/ no visible focus (WCAG 2.4.7).',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Wrap only the indicator in the ref'd element; a wrapper w/ label text rings the whole row.",
+      },
+      {
+        guidance: true,
+        description:
+          'Spread focusProps on the element containing the hidden input, not the input.',
+      },
+      {
+        guidance: false,
+        description:
+          'Delegate the ring to a themeable indicator; a replacement that ignores it loses visible focus.',
+      },
+    ],
+  },
+};

package/src/hooks/useInputStatusIcon.doc.mjs

@@ -0,0 +1,142 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useInputStatusIcon',
+  displayName: 'useInputStatusIcon',
+  keywords: [
+    'input',
+    'status',
+    'icon',
+    'error',
+    'warning',
+    'success',
+    'validation',
+    'tooltip',
+    'info tip',
+    'field',
+    'describedby',
+    'accessibility',
+    'a11y',
+  ],
+  params: [
+    {
+      name: 'options',
+      type: 'UseInputStatusIconOptions',
+      description: 'Configuration object.',
+      required: true,
+    },
+    {
+      name: 'options.status',
+      type: 'InputStatus',
+      description:
+        "The input's status (type plus message), or undefined when there is none.",
+    },
+    {
+      name: 'options.statusVariant',
+      type: "'attached' | 'detached' | 'tooltip'",
+      description: 'How the status is presented relative to the input.',
+      default: "'attached'",
+    },
+    {
+      name: 'options.isInGroup',
+      type: 'boolean',
+      description:
+        'Whether the input sits inside an InputGroup, which owns status rendering itself.',
+      default: 'false',
+    },
+    {
+      name: 'options.size',
+      type: 'IconSize',
+      description: 'Size of the on-field icon.',
+      default: "'md'",
+    },
+  ],
+  returns: [
+    {
+      name: 'statusIcon',
+      type: 'ReactNode',
+      description:
+        'The affordance to render inside the input container: a plain icon, or a focusable info-tip button with its tooltip. Null when no icon should render.',
+    },
+    {
+      name: 'describedBy',
+      type: 'string | undefined',
+      description:
+        "ID to add to the input's aria-describedby, present exactly when a tooltip element is in the DOM, so there is never a dangling reference.",
+    },
+  ],
+  usage: {
+    description:
+      'Builds the on-field status affordance for a bordered input and its accessibility wiring, so every input in the family behaves the same for a given status. The attached variant renders a plain glyph and leaves the text to the message box; the detached variant renders nothing here, because the message box already carries its own icon; the tooltip variant renders a real focusable button whose tooltip is reachable by keyboard, pointer, touch and assistive tech. Use it when building a bordered input, not for field-level messaging.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Render statusIcon inside the input container and merge describedBy into the control's aria-describedby list.",
+      },
+      {
+        guidance: true,
+        description:
+          'Let it decide when nothing should render; pass isInGroup and the variant through rather than branching at the call site.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use it to convey the status by icon alone; the tooltip variant is the only one that carries the message, so the others still need a message box.',
+      },
+    ],
+  },
+  relatedComponents: [
+    'TextInput',
+    'TextArea',
+    'NumberInput',
+    'DateInput',
+    'FileInput',
+    'FieldStatus',
+    'InputGroup',
+  ],
+  relatedHooks: ['useInputContainer'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'interaction',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'On-field status affordance + a11y wiring for bordered inputs. attached = plain glyph (message box carries text); detached = nothing (box has own icon); tooltip = focusable info-tip button reachable by keyboard / pointer / touch / AT.',
+  paramDescriptions: {
+    options: 'config.',
+    'options.status': 'input status (type + message), or undefined.',
+    'options.statusVariant': 'how status is presented relative to input.',
+    'options.isInGroup': 'inside InputGroup, which owns status rendering.',
+    'options.size': 'on-field icon size.',
+  },
+  returnDescriptions: {
+    statusIcon:
+      'node to render inside input container; null when nothing should render.',
+    describedBy:
+      'id for aria-describedby, present exactly when the tooltip element is in the DOM.',
+  },
+  usage: {
+    description:
+      'Use when building a bordered input so all inputs behave the same per status; not for field-level messaging.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Render statusIcon in the input container; merge describedBy into aria-describedby.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pass isInGroup + variant through; let the hook decide when nothing renders.',
+      },
+      {
+        guidance: false,
+        description:
+          'Rely on the icon alone for meaning; only the tooltip variant carries the message.',
+      },
+    ],
+  },
+};

package/src/hooks/useInteractiveRole.doc.mjs

@@ -0,0 +1,119 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useInteractiveRole',
+  displayName: 'useInteractiveRole',
+  keywords: [
+    'role',
+    'polymorphic',
+    'link',
+    'button',
+    'inert',
+    'href',
+    'onClick',
+    'element type',
+    'as',
+    'trigger',
+    'semantics',
+    'accessibility',
+    'a11y',
+  ],
+  params: [
+    {
+      name: 'options',
+      type: 'UseInteractiveRoleOptions',
+      description: 'The interactivity inputs the component received.',
+      required: true,
+    },
+    {
+      name: 'options.href',
+      type: 'string',
+      description:
+        'URL for navigation. Highest priority: with an href the component is a link.',
+    },
+    {
+      name: 'options.onClick',
+      type: '((...args: never[]) => unknown) | null',
+      description:
+        'Click handler. Resolves to a button, ahead of any context-provided role.',
+    },
+    {
+      name: 'options.isDisabled',
+      type: 'boolean',
+      description:
+        'When true, href is ignored for role resolution (a disabled link is an anti-pattern), so the role comes from onClick, then context, then inert.',
+      default: 'false',
+    },
+  ],
+  returns: [
+    {
+      name: 'role',
+      type: "'link' | 'button' | 'inert'",
+      description:
+        'The element the component should render: an anchor, a button, or a non-interactive span/div.',
+    },
+  ],
+  usage: {
+    description:
+      'Resolves what a polymorphic component should render as, in one place: href wins, then onClick, then an interactive trigger context supplied by a parent (Popover, DropdownMenu and friends), then inert. Use it in any component that is sometimes a link, sometimes a button, and sometimes plain content; Token, Thumbnail, Item and ClickableCard all do. Because context is part of the resolution, a component built on it becomes a valid trigger for new surfaces without changing.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Switch on the returned role to pick the element, and render an anchor only for "link" so keyboard and middle-click behavior come from the platform.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pass isDisabled through rather than dropping the href yourself; the hook already keeps disabled links out of the tab order.',
+      },
+      {
+        guidance: false,
+        description:
+          'Add another ad-hoc href/onClick precedence check in a component; new trigger contexts are added here so every consumer inherits them.',
+      },
+    ],
+  },
+  relatedComponents: ['Token', 'Thumbnail', 'Item', 'ClickableCard'],
+  relatedHooks: ['useClickableContainer'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'interaction',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Resolves what a polymorphic component renders as: href -> link, onClick -> button, interactive trigger context -> its role, else inert. Single place the precedence lives.',
+  paramDescriptions: {
+    options: 'interactivity inputs the component received.',
+    'options.href': 'navigation URL; highest priority.',
+    'options.onClick': 'click handler; button, ahead of context role.',
+    'options.isDisabled':
+      'true = href ignored for resolution (disabled link is anti-pattern); falls to onClick / context / inert.',
+  },
+  returnDescriptions: {
+    role: "element to render: 'link' (anchor), 'button', or 'inert' (span/div).",
+  },
+  usage: {
+    description:
+      'For components that are sometimes link, sometimes button, sometimes plain content (Token, Thumbnail, Item, ClickableCard). Context-aware, so consumers become valid triggers for new surfaces w/o changing.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Switch on returned role; render a real anchor for "link" so platform keyboard / middle-click behavior applies.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pass isDisabled through instead of dropping href yourself.',
+      },
+      {
+        guidance: false,
+        description:
+          'Re-implement href/onClick precedence per component; new trigger contexts are added here.',
+      },
+    ],
+  },
+};

package/src/hooks/useLongPress.doc.mjs

@@ -0,0 +1,123 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useLongPress',
+  displayName: 'useLongPress',
+  keywords: [
+    'long press',
+    'touch',
+    'press and hold',
+    'context menu',
+    'mobile',
+    'ios',
+    'safari',
+    'gesture',
+    'tap',
+  ],
+  params: [
+    {
+      name: 'options',
+      type: 'UseLongPressOptions',
+      description: 'Configuration object.',
+      required: true,
+    },
+    {
+      name: 'options.onLongPress',
+      type: '(point: {x: number; y: number}) => void',
+      description:
+        'Fired with the touch start point once the press is held for delayMs.',
+      required: true,
+    },
+    {
+      name: 'options.disabled',
+      type: 'boolean',
+      description: 'When true, the returned touch handlers are inert.',
+      default: 'false',
+    },
+    {
+      name: 'options.delayMs',
+      type: 'number',
+      description: 'Hold duration before the press fires, in milliseconds.',
+      default: '500',
+    },
+    {
+      name: 'options.moveCancelPx',
+      type: 'number',
+      description:
+        'Movement past this distance on either axis cancels the press, treating it as a scroll or drag.',
+      default: '10',
+    },
+  ],
+  returns: [
+    {
+      name: 'handlers',
+      type: 'UseLongPressHandlers',
+      description:
+        'onTouchStart, onTouchMove, onTouchEnd and onTouchCancel to spread onto the target element.',
+    },
+  ],
+  usage: {
+    description:
+      'Detects a single-finger press-and-hold and reports where it happened, so touch users can reach affordances that a pointer gets from right-click. iOS Safari never synthesizes a contextmenu event on long-press, which makes this the only touch route into a cursor-positioned surface such as ContextMenu. The press cancels on movement, lift, multi-touch or unmount.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use the reported point to position the surface you open, so it appears under the finger.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pair it with the pointer contextmenu handler rather than replacing it; this hook only covers touch.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use it for the primary action of a control; press-and-hold is undiscoverable as the only way to do something.',
+      },
+    ],
+  },
+  relatedComponents: ['ContextMenu'],
+  relatedHooks: ['useClickableContainer', 'useHotkeys'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'interaction',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Single-finger press-and-hold detection reporting the touch point. iOS Safari never fires contextmenu on long-press, so this is the only touch route to cursor-positioned surfaces. Cancels on move / lift / multi-touch / unmount.',
+  paramDescriptions: {
+    options: 'config.',
+    'options.onLongPress': 'fired w/ touch start point after delayMs.',
+    'options.disabled': 'true = handlers inert.',
+    'options.delayMs': 'hold duration before firing, ms.',
+    'options.moveCancelPx':
+      'movement past this (px, either axis) cancels as scroll / drag.',
+  },
+  returnDescriptions: {
+    handlers:
+      'onTouchStart / onTouchMove / onTouchEnd / onTouchCancel to spread onto the element.',
+  },
+  usage: {
+    description:
+      'Touch press-and-hold for affordances a pointer reaches by right-click (e.g. ContextMenu). Reports the point so the surface opens under the finger.',
+    bestPractices: [
+      {
+        guidance: true,
+        description: 'Position the opened surface at the reported point.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pair w/ pointer contextmenu handler; this covers touch only.',
+      },
+      {
+        guidance: false,
+        description:
+          'Make press-and-hold the only way to reach an action; it is undiscoverable.',
+      },
+    ],
+  },
+};

package/src/hooks/useMergedRefs.doc.mjs

@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useMergedRefs',
+  displayName: 'useMergedRefs',
+  keywords: [
+    'ref',
+    'refs',
+    'merge',
+    'forwardRef',
+    'callback ref',
+    'stable ref',
+  ],
+  params: [
+    {
+      name: 'refs',
+      type: 'Array<Ref<T> | undefined>',
+      description: 'Up to six refs that should all receive the same element.',
+      required: true,
+    },
+  ],
+  returns: [
+    {
+      name: 'ref',
+      type: 'RefCallback<T>',
+      description:
+        'A merged callback ref that remains stable until an input ref changes.',
+    },
+  ],
+  usage: {
+    description:
+      'Combines multiple object or callback refs into one stable callback ref. Use it when a component must forward a consumer ref while also attaching internal refs. Unlike calling mergeRefs during render, the callback identity stays stable across unrelated rerenders, so React does not detach and reattach the element.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use useMergedRefs when one element must receive both a forwarded ref and one or more internal refs.',
+      },
+      {
+        guidance: false,
+        description:
+          'Call mergeRefs directly in a JSX ref prop; that creates a new callback on every render and forces unnecessary detach and attach work.',
+      },
+    ],
+  },
+  relatedComponents: [],
+  relatedHooks: [],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'utility',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Combines object/callback refs into one stable callback ref. Identity changes only when an input ref changes, avoiding detach/attach churn from inline mergeRefs calls.',
+  paramDescriptions: {
+    refs: 'refs that should all receive the same element.',
+  },
+  returnDescriptions: {
+    ref: 'stable merged callback ref; changes only when an input ref changes.',
+  },
+  usage: {
+    description:
+      'Use when one element needs a forwarded consumer ref plus internal refs. Keeps the callback stable across unrelated rerenders.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use for a forwarded ref plus internal measurement, focus, or anchor refs.',
+      },
+      {
+        guidance: false,
+        description:
+          'Call mergeRefs inline in JSX; it forces ref detach/attach on every render.',
+      },
+    ],
+  },
+};

package/src/hooks/useMergedRefs.test.tsx

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useMergedRefs.test.tsx
+ * @input Uses vitest, @testing-library/react, useMergedRefs hook
+ * @output Unit tests for stable merged ref behavior
+ * @position Testing; validates useMergedRefs.ts
+ *
+ * SYNC: When useMergedRefs.ts changes, update tests to match new behavior
+ */
+
+import {renderHook} from '@testing-library/react';
+import {createRef} from 'react';
+import {describe, expect, it, vi} from 'vitest';
+import {useMergedRefs} from './useMergedRefs';
+
+describe('useMergedRefs', () => {
+  it('forwards values to callback and object refs', () => {
+    const callbackRef = vi.fn();
+    const objectRef = createRef<HTMLDivElement>();
+    const {result} = renderHook(() =>
+      useMergedRefs<HTMLDivElement>(callbackRef, objectRef),
+    );
+    const element = document.createElement('div');
+
+    const cleanup = result.current(element);
+
+    expect(callbackRef).toHaveBeenCalledWith(element);
+    expect(objectRef.current).toBe(element);
+
+    cleanup?.();
+    expect(callbackRef).toHaveBeenLastCalledWith(null);
+    expect(objectRef.current).toBeNull();
+  });
+
+  it('keeps the merged callback stable when input refs are unchanged', () => {
+    const callbackRef = vi.fn();
+    const objectRef = createRef<HTMLDivElement>();
+    const {result, rerender} = renderHook(() =>
+      useMergedRefs<HTMLDivElement>(callbackRef, objectRef),
+    );
+    const first = result.current;
+
+    rerender();
+
+    expect(result.current).toBe(first);
+  });
+
+  it('updates the merged callback when an input ref changes', () => {
+    const firstRef = vi.fn();
+    const secondRef = vi.fn();
+    const {result, rerender} = renderHook(
+      ({ref}) => useMergedRefs<HTMLDivElement>(ref),
+      {initialProps: {ref: firstRef}},
+    );
+    const first = result.current;
+
+    rerender({ref: secondRef});
+
+    expect(result.current).not.toBe(first);
+  });
+});