@appinternalleads/ui 0.2.0

package/src/ds/blockOverlay.tsx

@@ -0,0 +1,477 @@
+import { useCallback, useEffect, useId, useRef, useState, type ReactNode } from 'react';
+import type { View } from 'react-native';
+import {
+  Box, Icon, Layer, MotionView, Pressable, Text, useAnchor, useTween, type IconName,
+} from '../core';
+import { blockRadii, useDs } from '../tokens';
+
+/**
+ * **Solarium Building Blocks — overlay.** O2 Collapsible · O3 Dropdown menu · O4 Modal, Popover,
+ * Tooltip. (O1 Toast is the existing `ToastProvider`, extended with a title/body notice in
+ * `overlays.tsx` — one notification system, not two.)
+ *
+ * Menu, popover and modal share `core/Layer`: focus is trapped inside while open, Escape and a
+ * backdrop press close, and focus returns to the control that opened the layer. On React Native
+ * the menu is a sheet — "Bottom sheet on RN" — which the caller gets by using `core/Select` or
+ * `HomeSheet` there; this menu is the pointer-and-keyboard surface.
+ */
+
+/* ── O2 · Collapsible ────────────────────────────────────────────────────── */
+
+/**
+ * **A Row header with a chevron; the body stays mounted and is inert when closed.** Mounted, so
+ * its state (a half-typed field) survives a close; inert, so a closed body is neither focusable
+ * nor read out. The header is a button with `aria-expanded` and `aria-controls`.
+ *
+ * Open/close eases the height at `slow` (M3) and turns the chevron 180°; reduced motion jumps.
+ * Controlled when `open` is passed, uncontrolled from `defaultOpen` otherwise.
+ */
+export function Collapsible({
+  title, subtitle, children, open: controlled, defaultOpen = false, onOpenChange, variant = 'card', leading, meta,
+}: {
+  title: string;
+  subtitle?: string;
+  children: ReactNode;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** `plain`: no border — a row inside a card (onboarding Permissions); the header fills on hover. */
+  variant?: 'card' | 'plain';
+  /** Before the title — a tile. */
+  leading?: ReactNode;
+  /** Before the chevron — a count chip. */
+  meta?: ReactNode;
+}) {
+  const { colors, density } = useDs();
+  const [own, setOwn] = useState(defaultOpen);
+  const [hover, setHover] = useState(false);
+  const open = controlled ?? own;
+  const [height, setHeight] = useState<number | null>(null);
+  const t = useTween(open ? 1 : 0);
+  const body = useRef<View>(null);
+  const id = `collapsible-${useId().replace(/:/g, '')}`;
+
+  /* `inert` is the web's one attribute for "present but not interactive". react-native-web does
+     not forward it, so it is set on the DOM node directly; on native the node has no such method
+     and the aria-hidden + pointerEvents pair below carries the same meaning. */
+  useEffect(() => {
+    const el = body.current as unknown as { setAttribute?: (k: string, v: string) => void; removeAttribute?: (k: string) => void } | null;
+    if (!el?.setAttribute) return;
+    if (open) el.removeAttribute?.('inert');
+    else el.setAttribute('inert', '');
+  }, [open]);
+
+  const toggle = () => {
+    if (controlled === undefined) setOwn(!open);
+    onOpenChange?.(!open);
+  };
+
+  return (
+    <Box style={variant === 'plain' ? { overflow: 'hidden' } : { borderRadius: blockRadii.mid, boxShadow: `0 0 0 1px ${colors.hairlineStrong}`, overflow: 'hidden', backgroundColor: colors.surface1 }}>
+      <Pressable
+        onPress={toggle}
+        onHoverIn={variant === 'plain' ? () => setHover(true) : undefined}
+        onHoverOut={variant === 'plain' ? () => setHover(false) : undefined}
+        aria-expanded={open}
+        aria-controls={id}
+        aria-label={title}
+        row
+        justify="space-between"
+        gap="s3"
+        px={variant === 'plain' ? 's2' : 's3'}
+        minHeight={Math.max(44, density.rowH)}
+        style={variant === 'plain' ? { borderRadius: blockRadii.inset, backgroundColor: hover ? colors.surfaceSunken : undefined } : undefined}>
+        {leading}
+        <Box flex={1} style={{ minWidth: 0 }}>
+          <Text variant="caption" style={{ fontWeight: '600' }} color="textPrimary">{title}</Text>
+          {subtitle ? <Text variant="caption" color="textSecondary" style={{ fontSize: 12 }}>{subtitle}</Text> : null}
+        </Box>
+        {meta}
+        <MotionView style={{ transform: [{ rotate: t.interpolate({ inputRange: [0, 1], outputRange: ['0deg', '180deg'] }) }] }}>
+          <Icon name="chev-d" size={14} color={colors.textSecondary} />
+        </MotionView>
+      </Pressable>
+      <MotionView
+        style={{
+          overflow: 'hidden',
+          opacity: t,
+          height: height === null ? (open ? undefined : 0) : t.interpolate({ inputRange: [0, 1], outputRange: [0, height] }),
+        }}>
+        <Box
+          ref={body}
+          nativeID={id}
+          role="region"
+          aria-label={title}
+          aria-hidden={!open}
+          style={{ pointerEvents: open ? 'auto' : 'none' }}
+          onLayout={e => {
+            const h = e.nativeEvent.layout.height;
+            if (h > 0 && h !== height) setHeight(h);
+          }}>
+          <Box px={variant === 'plain' ? 's2' : 's3'} pb="s3">{children}</Box>
+        </Box>
+      </MotionView>
+    </Box>
+  );
+}
+
+/* ── O3 · Dropdown menu ──────────────────────────────────────────────────── */
+
+export type MenuItem<T extends string = string> = { value: T; label: string };
+
+/** A menu is never narrower than this — the handoff's "min 220 wide". */
+export const MENU_MIN_WIDTH = 220;
+
+/**
+ * **A trigger and a menu of 36px items; ✓ on the selected one.** The trigger is a button with
+ * `aria-haspopup="menu"` and `aria-expanded`. Opening focuses the selected item (or the first);
+ * ArrowUp/Down move, Home/End jump, Enter chooses, Escape and Tab close — and focus goes back to
+ * the trigger, the one place a keyboard user expects to be after a menu.
+ *
+ * `value` makes it a single-choice menu (`menuitemradio` with `aria-checked`); omit it for a menu
+ * of actions (`menuitem`).
+ */
+export function Menu<T extends string>({
+  label, items, value, onSelect, trigger,
+}: {
+  /** The menu's name, and the trigger's when `trigger` is omitted. */
+  label: string;
+  items: MenuItem<T>[];
+  value?: T;
+  onSelect: (value: T) => void;
+  /** The trigger's visible text. Defaults to the selected item's label, then `label`. */
+  trigger?: string;
+}) {
+  const { colors, density } = useDs();
+  const anchor = useAnchor();
+  const [open, setOpen] = useState(false);
+  const refs = useRef<(View | null)[]>([]);
+  const selected = value === undefined ? -1 : items.findIndex(i => i.value === value);
+  const menuId = `menu-${useId().replace(/:/g, '')}`;
+
+  const close = () => setOpen(false);
+  const focusAt = (i: number) => refs.current[(i + items.length) % items.length]?.focus();
+  const focusSelected = useCallback(() => refs.current[Math.max(0, selected)]?.focus(), [selected]);
+  const current = selected >= 0 ? items[selected]!.label : undefined;
+
+  return (
+    <>
+      <Pressable
+        ref={anchor.ref}
+        onPress={() => { anchor.measure(); setOpen(true); }}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        aria-controls={open ? menuId : undefined}
+        aria-label={current ? `${label}: ${current}` : label}
+        row
+        gap="s2"
+        px="s3"
+        alignSelf="flex-start"
+        minHeight={density.controlH}
+        style={{ borderRadius: blockRadii.inset, boxShadow: `0 0 0 1px ${colors.hairlineStrong}`, backgroundColor: colors.surface1 }}>
+        <Text variant="caption" color="textPrimary" numberOfLines={1}>{trigger ?? current ?? label}</Text>
+        <Icon name="chev-d" size={12} color={colors.textSecondary} />
+      </Pressable>
+      <Layer
+        open={open}
+        onClose={close}
+        label={label}
+        initialFocus={focusSelected}
+        returnFocus={anchor.focus}
+        placement={{ kind: 'anchor', rect: anchor.rect, width: MENU_MIN_WIDTH }}>
+        <Box
+          nativeID={menuId}
+          role="menu"
+          aria-label={label}
+          style={{ padding: 4, borderRadius: blockRadii.mid, backgroundColor: colors.surface1 }}
+          lift={2}>
+          {items.map((item, i) => {
+            const on = i === selected;
+            return (
+              <Pressable
+                key={item.value}
+                ref={el => { refs.current[i] = el; }}
+                role={value === undefined ? 'menuitem' : 'menuitemradio'}
+                aria-checked={value === undefined ? undefined : on}
+                aria-label={item.label}
+                tabIndex={-1}
+                onPress={() => { onSelect(item.value); close(); }}
+                onKeyDown={e => {
+                  if (e.key === 'ArrowDown') { e.preventDefault(); focusAt(i + 1); }
+                  else if (e.key === 'ArrowUp') { e.preventDefault(); focusAt(i - 1); }
+                  else if (e.key === 'Home') { e.preventDefault(); focusAt(0); }
+                  else if (e.key === 'End') { e.preventDefault(); focusAt(items.length - 1); }
+                  else if (e.key === 'Escape' || e.key === 'Tab') { e.preventDefault(); close(); }
+                }}
+                row
+                justify="space-between"
+                px="s3"
+                height={36}
+                style={{ borderRadius: blockRadii.inset, backgroundColor: on ? colors.surfaceSunken : undefined }}>
+                <Text variant="caption" color="textPrimary" numberOfLines={1}>{item.label}</Text>
+                {on ? <Icon name="check" size={14} color={colors.accentInk} /> : null}
+              </Pressable>
+            );
+          })}
+        </Box>
+      </Layer>
+    </>
+  );
+}
+
+/* ── O3 · Action menu (onboarding batch 2) ───────────────────────────────── */
+
+export type ActionMenuItem<T extends string = string> = {
+  value: T;
+  label: string;
+  /** The consequence, said before it happens — "12 members become unassigned". */
+  detail?: string;
+  /** `danger`: apricot deep text and a trash glyph. Never red. */
+  tone?: 'danger';
+};
+
+/**
+ * **An icon button that opens a menu of actions** — a row's "⋯" (Rename · Remove) or its Delete
+ * with a confirm step. The same contract as `Menu`: `aria-haspopup="menu"`, focus moves to the
+ * first item on open, arrows / Home / End move, Escape and Tab close, focus returns to the trigger.
+ * A **danger** item uses apricot deep text, a trash glyph and explicit consequence copy (decision
+ * §5.4 of the batch-2 handoff).
+ *
+ * `open` / `onOpenChange` make it controlled, so a restored session can open with it showing; it
+ * measures its anchor on mount when it starts open.
+ */
+export function ActionMenu<T extends string>({
+  label, triggerLabel, triggerIcon = 'more', items, onSelect, open: openProp, onOpenChange, disabled, width = MENU_MIN_WIDTH + 40,
+  trigger, side = 'below', align = 'start',
+}: {
+  /** The menu's name. */
+  label: string;
+  /** The trigger's accessible name — "Delete Engineering". */
+  triggerLabel: string;
+  triggerIcon?: IconName;
+  items: ActionMenuItem<T>[];
+  onSelect: (value: T) => void;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  disabled?: boolean;
+  width?: number;
+  /**
+   * A text trigger instead of the icon — the ghost button a footer carries ("Snooze", batch 3's
+   * Event Reminder). The same 8px ghost as `Button variant="secondary"`, at the density's height.
+   */
+  trigger?: string;
+  /** Open upward — a menu on a card's footer. */
+  side?: 'below' | 'above';
+  /** `end`: the menu's right edge on the trigger's. */
+  align?: 'start' | 'end';
+}) {
+  const { colors, density } = useDs();
+  const anchor = useAnchor();
+  const [ownOpen, setOwnOpen] = useState(false);
+  const open = openProp ?? ownOpen;
+  const setOpen = (v: boolean) => { setOwnOpen(v); onOpenChange?.(v); };
+  const refs = useRef<(View | null)[]>([]);
+  const menuId = `amenu-${useId().replace(/:/g, '')}`;
+  const focusAt = (i: number) => refs.current[(i + items.length) % items.length]?.focus();
+  const focusFirst = useCallback(() => refs.current[0]?.focus(), []);
+  /* A menu that starts open (a restored session) still needs its anchor measured. */
+  useEffect(() => { if (open) anchor.measure(); }, [open]);
+
+  return (
+    <>
+      <Pressable
+        ref={anchor.ref}
+        onPress={() => { anchor.measure(); setOpen(!open); }}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        aria-controls={open ? menuId : undefined}
+        aria-label={triggerLabel}
+        disabled={disabled}
+        {...(trigger !== undefined
+          ? {
+            row: true, px: 's3' as const, minHeight: density.controlH,
+            style: { borderRadius: blockRadii.inset, borderWidth: 1, borderColor: colors.hairlineStrong, backgroundColor: colors.surface1, opacity: disabled ? 0.45 : 1 },
+          }
+          : { width: 32, height: 32, radius: 'pill' as const })}>
+        {trigger !== undefined
+          ? <Text variant="caption" numeric color="textPrimary" numberOfLines={1} style={{ fontSize: 13, fontWeight: '600' }}>{trigger}</Text>
+          : <Icon name={triggerIcon} size={16} color={colors.textSecondary} />}
+      </Pressable>
+      <Layer open={open} onClose={() => setOpen(false)} label={label} initialFocus={focusFirst} returnFocus={anchor.focus} placement={{ kind: 'anchor', rect: anchor.rect, width, side, align }}>
+        <Box nativeID={menuId} role="menu" aria-label={label} lift={2} style={{ padding: 4, borderRadius: blockRadii.mid, backgroundColor: colors.surface1, borderWidth: 1, borderColor: colors.hairlineStrong }}>
+          {items.map((item, i) => {
+            const danger = item.tone === 'danger';
+            const ink = danger ? colors.status.needsUser : colors.textPrimary;
+            return (
+              <Pressable
+                key={item.value}
+                ref={el => { refs.current[i] = el; }}
+                role="menuitem"
+                aria-label={item.detail ? `${item.label} · ${item.detail}` : item.label}
+                tabIndex={-1}
+                onPress={() => { setOpen(false); onSelect(item.value); }}
+                onKeyDown={e => {
+                  if (e.key === 'ArrowDown') { e.preventDefault(); focusAt(i + 1); }
+                  else if (e.key === 'ArrowUp') { e.preventDefault(); focusAt(i - 1); }
+                  else if (e.key === 'Home') { e.preventDefault(); focusAt(0); }
+                  else if (e.key === 'End') { e.preventDefault(); focusAt(items.length - 1); }
+                  else if (e.key === 'Escape' || e.key === 'Tab') { e.preventDefault(); setOpen(false); }
+                }}
+                row
+                align="flex-start"
+                justify="flex-start"
+                gap="s2"
+                style={{ borderRadius: blockRadii.inset, paddingVertical: 8, paddingHorizontal: 10 }}>
+                {danger ? <Box pt="s1"><Icon name="trash" size={14} color={ink} /></Box> : null}
+                <Box flex={1} style={{ minWidth: 0 }}>
+                  <Text variant="caption" style={{ color: ink, fontWeight: danger ? '600' : '400' }}>{item.label}</Text>
+                  {item.detail ? <Text variant="caption" style={{ fontSize: 12, color: danger ? colors.status.needsUser : colors.textSecondary }}>{item.detail}</Text> : null}
+                </Box>
+              </Pressable>
+            );
+          })}
+        </Box>
+      </Layer>
+    </>
+  );
+}
+
+/* ── O4 · Modal ──────────────────────────────────────────────────────────── */
+
+/**
+ * **A dialog over a scrim: title, body, verb buttons.** `role="dialog"`, `aria-modal`, named by
+ * its title. Focus is trapped while open; Escape and the scrim close it; focus returns to whatever
+ * opened it (pass `returnFocus`, usually `useAnchor().focus`). Buttons say the verb — "Remove",
+ * not "OK" — the same rule `useConfirm` states.
+ */
+export function Modal({
+  open, onClose, title, children, actions, returnFocus, maxWidth = 420,
+}: {
+  open: boolean;
+  onClose: () => void;
+  title: string;
+  children?: ReactNode;
+  /** The verb buttons, primary last. */
+  actions?: ReactNode;
+  returnFocus?: () => void;
+  maxWidth?: number;
+}) {
+  const { colors, lift2 } = useDs();
+  const titleId = `modal-${useId().replace(/:/g, '')}`;
+  return (
+    <Layer open={open} onClose={onClose} returnFocus={returnFocus} scrim labelledBy={titleId} placement={{ kind: 'center', maxWidth }}>
+      <Box p="s5" gap="s3" style={{ borderRadius: blockRadii.major, backgroundColor: colors.surface1, boxShadow: lift2 }}>
+        <Text nativeID={titleId} variant="heading" role="heading" aria-level={2}>{title}</Text>
+        {typeof children === 'string' ? <Text variant="caption" color="textSecondary">{children}</Text> : children}
+        {actions ? <Box row wrap gap="s2" justify="flex-end">{actions}</Box> : null}
+      </Box>
+    </Layer>
+  );
+}
+
+/* ── O4 · Popover ────────────────────────────────────────────────────────── */
+
+/**
+ * **Anchored content that is not a menu** — a small form, a detail. A button with
+ * `aria-haspopup="dialog"` opens a labelled, non-scrimmed layer below it; Escape and an outside
+ * press close it and return focus to the trigger.
+ */
+export function Popover({
+  label, trigger, children, width = 260,
+}: {
+  label: string;
+  /** The trigger's visible text. */
+  trigger: string;
+  children: ReactNode;
+  width?: number;
+}) {
+  const { colors, density, lift2 } = useDs();
+  const anchor = useAnchor();
+  const [open, setOpen] = useState(false);
+  const close = () => setOpen(false);
+  return (
+    <>
+      <Pressable
+        ref={anchor.ref}
+        onPress={() => { anchor.measure(); setOpen(true); }}
+        aria-haspopup="dialog"
+        aria-expanded={open}
+        aria-label={trigger}
+        px="s3"
+        alignSelf="flex-start"
+        minHeight={density.controlH}
+        style={{ borderRadius: blockRadii.inset, boxShadow: `0 0 0 1px ${colors.hairlineStrong}`, backgroundColor: colors.surface1 }}>
+        <Text variant="caption" color="textPrimary">{trigger}</Text>
+      </Pressable>
+      <Layer open={open} onClose={close} returnFocus={anchor.focus} label={label} placement={{ kind: 'anchor', rect: anchor.rect, width }}>
+        <Box p="s3" gap="s2" style={{ borderRadius: blockRadii.mid, backgroundColor: colors.surface1, boxShadow: lift2 }}>
+          {children}
+        </Box>
+      </Layer>
+    </>
+  );
+}
+
+/* ── O4 · Tooltip ────────────────────────────────────────────────────────── */
+
+/** Hover or focus must rest this long before a tooltip appears — the handoff's 300ms. */
+export const TOOLTIP_DELAY_MS = 300;
+
+export type TooltipTriggerProps = {
+  onHoverIn: () => void;
+  onHoverOut: () => void;
+  onFocus: () => void;
+  onBlur: () => void;
+  onKeyDown: (e: { key: string; preventDefault: () => void }) => void;
+  'aria-describedby': string;
+};
+
+/**
+ * **A short description, shown after 300ms of hover or focus; Escape dismisses it.** A render
+ * prop hands the trigger its handlers and `aria-describedby`, so the tooltip describes a real
+ * control instead of wrapping it in a second button. Never put anything in a tooltip that a touch
+ * user needs: touch has no hover, and this does not pretend otherwise.
+ */
+export function Tooltip({
+  label, children,
+}: {
+  label: string;
+  children: (trigger: TooltipTriggerProps) => ReactNode;
+}) {
+  const { colors } = useDs();
+  const [shown, setShown] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const id = `tip-${useId().replace(/:/g, '')}`;
+  useEffect(() => () => { if (timer.current) clearTimeout(timer.current); }, []);
+
+  const show = () => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = setTimeout(() => setShown(true), TOOLTIP_DELAY_MS);
+  };
+  const hide = () => {
+    if (timer.current) clearTimeout(timer.current);
+    setShown(false);
+  };
+
+  return (
+    <Box alignSelf="flex-start" style={{ position: 'relative' }}>
+      {children({
+        onHoverIn: show, onHoverOut: hide, onFocus: show, onBlur: hide,
+        onKeyDown: e => { if (e.key === 'Escape') hide(); },
+        'aria-describedby': id,
+      })}
+      <Box
+        nativeID={id}
+        role="tooltip"
+        aria-hidden={!shown}
+        style={{
+          position: 'absolute', bottom: '100%', left: 0, marginBottom: 6,
+          paddingHorizontal: 8, paddingVertical: 4, borderRadius: blockRadii.inset,
+          backgroundColor: colors.textPrimary, minWidth: 120, maxWidth: 240,
+          opacity: shown ? 1 : 0, pointerEvents: 'none',
+        }}>
+        <Text variant="caption" style={{ fontSize: 12, color: colors.surface1 }}>{label}</Text>
+      </Box>
+    </Box>
+  );
+}