pixelize-native-library 1.0.7 → 1.2.1

package/lib/module/modules/fab/FabGroup.js

@@ -0,0 +1,361 @@
+"use strict";
+
+/**
+ * FabGroup — a speed-dial: a Fab-shaped trigger that expands into a vertical stack of labeled mini
+ * actions above itself, behind a dismiss scrim. Deliberately NOT React Native's own `<Modal>` (unlike
+ * Menu/Select/Drawer) — a speed dial must stay visually anchored exactly where its own trigger sits
+ * on screen, and RN's `<Modal>` can only present a new, unrelated native surface. The scrim and the
+ * trigger+actions anchor are declared as SIBLINGS at this component's own root (no wrapping node of
+ * its own), so both resolve their `position: "absolute"` against the SAME nearest positioned ancestor
+ * — ordinarily the screen's own root container — the scrim covering it edge-to-edge while the anchor
+ * still hugs its own corner/edge. Declaring the scrim first and the anchor second puts the anchor
+ * visibly on top with no `zIndex` needed between the two, the same source-order idiom `Menu.tsx`'s
+ * own backdrop-then-sheet pair already relies on.
+ *
+ * Not being a `<Modal>` costs the one thing a Modal gives for free, though: RN's `<Modal>` presents
+ * its own native surface, so what it covers leaves the accessibility tree by construction. Nothing
+ * does that here, so the anchor declares `accessibilityViewIsModal` (+ `onAccessibilityEscape`) for
+ * itself while the scrim is mounted — otherwise the screen the scrim covers stays swipeable.
+ *
+ * The expand/collapse lifecycle mirrors `Drawer.tsx`'s exactly: `mounted` stays true through the exit
+ * animation (driven by a `useEffect` reacting to the resolved `expanded` value, not to who changed
+ * it) so the fade/slide can actually play before the tree unmounts, using the same plain-`setTimeout`
+ * determinism fix `Drawer`'s own top comment explains (an `Animated.timing` completion callback rides
+ * `requestAnimationFrame`, which doesn't resolve on a predictable jest-fake-timer tick). Driving the
+ * animation from an effect on `expanded` — rather than only inside the trigger's own press handler —
+ * is what makes a CONTROLLED caller flipping `open` externally (not via this trigger) animate too.
+ *
+ * Uncontrolled by default (`open`/`onOpenChange` both omitted → internal state); controlled the
+ * instant a caller passes `open`, the conventional React controlled/uncontrolled split.
+ */
+
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Animated, Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import Reanimated from "react-native-reanimated";
+import { useDismissOnEscape, useFocusTrap } from "../../core/a11y/keyboard";
+import { Icon } from "../../core/icon/index.js";
+import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { usePressState } from "../../core/motion/usePressState.js";
+import { rippleColor } from "../../theme/platform/stateLayer.native.js";
+import { useTheme } from "../../theme/hooks.js";
+import { fabCircleStructure, fabOverlayColor, FAB_ACTION_ICON_SIZE, fabGroupActionCircleStructure, fabGroupActionLabelStructure, fabGroupActionRowStructure, fabGroupActionsStackStructure, FAB_GROUP_SCRIM, FAB_SIZES, resolveFabAccessibility, resolveFabAnchorStyle, resolveFabBottomInset, resolveFabFocusRingStyle, resolveFabGroupActionDirection, resolveFabGroupActionWindow, resolveFabGroupStackAlign, resolveFabGroupTriggerAccessibilityLabel, resolveFabHorizontalInset, resolveFabTone } from "./Fab.variants.js";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+const AnimatedPressable = Reanimated.createAnimatedComponent(Pressable);
+const ICON_STROKE = 2;
+const ACTION_ICON_STROKE = 2;
+const DEFAULT_ICON = "plus";
+const styles = StyleSheet.create({
+  dimmed: {
+    opacity: 0.5
+  },
+  // The trigger is declared FIRST so Tab reaches it before the actions it opened, and action 0 is
+  // declared first so Tab walks outward from the trigger. `column-reverse` on both restores the
+  // painted layout: trigger at the bottom, action 0 the row just above it.
+  anchorFlow: {
+    flexDirection: "column-reverse"
+  },
+  actionsFlow: {
+    flexDirection: "column-reverse"
+  }
+});
+function FabGroupActionRowImpl({
+  action,
+  fallbackTone,
+  direction,
+  progress,
+  window,
+  onSelect,
+  testID
+}) {
+  const theme = useTheme();
+  const motion = useMotion();
+  const press = usePressState();
+  const colors = resolveFabTone(theme.colors, action.tone ?? fallbackTone);
+  const handlePress = useCallback(() => onSelect(action), [onSelect, action]);
+  const [start, end] = window;
+  const revealOpacity = useMemo(() => progress.interpolate({
+    inputRange: [start, end],
+    outputRange: [0, 1],
+    extrapolate: "clamp"
+  }), [progress, start, end]);
+  const translateY = useMemo(() => progress.interpolate({
+    inputRange: [start, end],
+    outputRange: [motion.transform.offsetY, 0],
+    extrapolate: "clamp"
+  }), [progress, start, end, motion.transform.offsetY]);
+  const revealStyle = useMemo(() => ({
+    opacity: revealOpacity,
+    transform: [{
+      translateY
+    }]
+  }), [revealOpacity, translateY]);
+  const androidRipple = useMemo(() => {
+    if (Platform.OS !== "android") return undefined;
+    return {
+      color: rippleColor(theme.mode),
+      borderless: false
+    };
+  }, [theme.mode]);
+
+  // Reveal (classic Animated) nests press feedback (Reanimated `usePressState`) — fades compose.
+  return /*#__PURE__*/_jsx(Animated.View, {
+    style: revealStyle,
+    children: /*#__PURE__*/_jsxs(AnimatedPressable, {
+      testID: testID,
+      accessibilityRole: "button",
+      accessibilityLabel: action.label,
+      onPress: handlePress,
+      onPressIn: press.handlers.onPressIn,
+      onPressOut: press.handlers.onPressOut,
+      onLayout: press.onLayout,
+      android_ripple: androidRipple,
+      style: [fabGroupActionRowStructure(theme), {
+        flexDirection: direction
+      }, press.animatedStyle],
+      children: [/*#__PURE__*/_jsx(View, {
+        style: [fabGroupActionLabelStructure(theme), {
+          backgroundColor: theme.colors.bg.raised
+        }, theme.elevation.sm],
+        children: /*#__PURE__*/_jsx(Text, {
+          numberOfLines: 1,
+          style: [theme.fontStyleForWeight(theme.fontWeights.medium), {
+            fontSize: theme.fontSizes.sm,
+            color: theme.colors.fg.default
+          }],
+          children: action.label
+        })
+      }), /*#__PURE__*/_jsx(View, {
+        style: [fabGroupActionCircleStructure(theme), {
+          backgroundColor: colors.fill
+        }, theme.elevation.md],
+        children: /*#__PURE__*/_jsx(Icon, {
+          name: action.icon,
+          size: FAB_ACTION_ICON_SIZE,
+          color: colors.onFill,
+          strokeWidth: ACTION_ICON_STROKE
+        })
+      })]
+    })
+  });
+}
+const FabGroupActionRow = /*#__PURE__*/memo(FabGroupActionRowImpl);
+function FabGroupImpl({
+  actions,
+  icon = DEFAULT_ICON,
+  open,
+  onOpenChange,
+  tone = "accent",
+  size = "lg",
+  position = "bottom-right",
+  disabled = false,
+  accessibilityLabel,
+  offset,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const motion = useMotion();
+  const [internalOpen, setInternalOpen] = useState(false);
+  const isControlled = open !== undefined;
+  const expanded = isControlled ? open : internalOpen;
+  const duration = motion.duration("normal");
+
+  // Kept mounted through the exit animation — see the file-level comment for why this can't just
+  // follow `expanded` directly.
+  const [mounted, setMounted] = useState(expanded);
+  const mountedRef = useRef(mounted);
+  mountedRef.current = mounted;
+  const progress = useAnimatedValue(expanded ? 1 : 0);
+  const running = useRef(null);
+  const unmountTimer = useRef(null);
+  useEffect(() => {
+    const clearUnmountTimer = () => {
+      if (unmountTimer.current !== null) {
+        clearTimeout(unmountTimer.current);
+        unmountTimer.current = null;
+      }
+    };
+    clearUnmountTimer();
+    running.current?.stop();
+    if (expanded) {
+      setMounted(true);
+      if (!motion.enabled || duration === 0) {
+        progress.setValue(1);
+        return;
+      }
+      running.current = motion.timing(progress, 1, {
+        easing: "decelerate"
+      });
+      running.current.start();
+      return clearUnmountTimer;
+    }
+    if (!mountedRef.current) return;
+    if (!motion.enabled || duration === 0) {
+      progress.setValue(0);
+      setMounted(false);
+      return;
+    }
+    running.current = motion.timing(progress, 0, {
+      easing: "accelerate"
+    });
+    running.current.start();
+    unmountTimer.current = setTimeout(() => {
+      unmountTimer.current = null;
+      setMounted(false);
+    }, duration);
+    return clearUnmountTimer;
+  }, [expanded, duration, motion, progress]);
+  useEffect(() => () => {
+    running.current?.stop();
+    if (unmountTimer.current !== null) clearTimeout(unmountTimer.current);
+  }, []);
+  const requestExpandedChange = useCallback(next => {
+    if (!isControlled) setInternalOpen(next);
+    onOpenChange?.(next);
+  }, [isControlled, onOpenChange]);
+  const toggle = useCallback(() => {
+    if (disabled) return;
+    requestExpandedChange(!expanded);
+  }, [disabled, expanded, requestExpandedChange]);
+  const closeGroup = useCallback(() => requestExpandedChange(false), [requestExpandedChange]);
+
+  // No <Modal> here (see the file header), so nothing else supplies these on web: Escape to collapse,
+  // Tab confined to trigger+actions while the scrim is up, and focus back on the trigger afterwards —
+  // including after an action runs, since `runAction` collapses the group.
+  const anchorRef = useRef(null);
+  useDismissOnEscape(mounted, closeGroup);
+  useFocusTrap(anchorRef, mounted);
+  const runAction = useCallback(action => {
+    closeGroup();
+    action.onPress();
+  }, [closeGroup]);
+  const spec = FAB_SIZES[size];
+  const triggerColors = resolveFabTone(theme.colors, tone);
+  const a11y = resolveFabAccessibility({
+    accessibilityLabel: resolveFabGroupTriggerAccessibilityLabel(expanded, accessibilityLabel),
+    disabled,
+    onPress: toggle
+  });
+  const bottomInset = resolveFabBottomInset(theme.space[4], Platform.OS, offset?.bottom ?? 0);
+  const horizontalInset = resolveFabHorizontalInset(theme.space[4], offset?.horizontal ?? 0);
+  const anchor = resolveFabAnchorStyle({
+    position,
+    bottomInset,
+    horizontalInset,
+    zIndex: theme.zIndices.overlay
+  });
+  const actionDirection = resolveFabGroupActionDirection(position);
+  const stackAlign = resolveFabGroupStackAlign(position);
+  const rotate = useMemo(() => progress.interpolate({
+    inputRange: [0, 1],
+    outputRange: ["0deg", "45deg"]
+  }), [progress]);
+  const triggerPress = usePressState(disabled);
+  const triggerOverlayColor = fabOverlayColor(triggerColors.onFill);
+  const triggerRipple = useMemo(() => {
+    if (Platform.OS !== "android" || disabled) return undefined;
+    return {
+      color: rippleColor(theme.mode),
+      borderless: true
+    };
+  }, [disabled, theme.mode]);
+
+  // Same circular control as `Fab`, so the ring geometry is shared, not re-derived.
+  const [focused, setFocused] = useState(false);
+  const handleFocus = useCallback(() => setFocused(true), []);
+  const handleBlur = useCallback(() => setFocused(false), []);
+  const focusRingStyle = useMemo(() => resolveFabFocusRingStyle(theme.colors.border.focus, theme.radii.full), [theme.colors.border.focus, theme.radii.full]);
+  const rows = useMemo(() => actions.map((action, index) => ({
+    action,
+    index,
+    window: resolveFabGroupActionWindow(index, actions.length, motion.decorative)
+  })), [actions, motion.decorative]);
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [mounted && /*#__PURE__*/_jsx(Pressable, {
+      testID: testID ? `${testID}-scrim` : undefined,
+      accessible: false,
+      tabIndex: -1,
+      style: StyleSheet.absoluteFill,
+      onPress: closeGroup,
+      children: /*#__PURE__*/_jsx(Animated.View, {
+        pointerEvents: "none",
+        style: [StyleSheet.absoluteFill, {
+          backgroundColor: FAB_GROUP_SCRIM,
+          opacity: progress
+        }]
+      })
+    }), /*#__PURE__*/_jsxs(View, {
+      ref: anchorRef,
+      testID: testID ? `${testID}-anchor` : undefined,
+      style: [anchor, styles.anchorFlow, style]
+      // Modal exactly while the scrim is mounted, and on the anchor rather than the action stack
+      // so the trigger — the close affordance — stays inside the modal view with the actions.
+      // Both spellings: RN's View has no `aria-modal`, react-native-web has no
+      // `accessibilityViewIsModal`, and this node has to be modal on both.
+      ,
+      accessibilityViewIsModal: mounted,
+      "aria-modal": mounted,
+      onAccessibilityEscape: mounted ? closeGroup : undefined,
+      pointerEvents: "box-none",
+      children: [/*#__PURE__*/_jsxs(AnimatedPressable, {
+        testID: testID ? `${testID}-trigger` : undefined,
+        accessibilityRole: a11y.accessibilityRole,
+        accessibilityLabel: a11y.accessibilityLabel,
+        "aria-disabled": a11y["aria-disabled"],
+        "aria-expanded": expanded,
+        disabled: a11y.disabled,
+        onPress: a11y.onPress,
+        onPressIn: triggerPress.handlers.onPressIn,
+        onPressOut: triggerPress.handlers.onPressOut,
+        onFocus: handleFocus,
+        onBlur: handleBlur,
+        onLayout: triggerPress.onLayout,
+        android_ripple: triggerRipple,
+        style: [fabCircleStructure(theme, {
+          size
+        }), {
+          backgroundColor: triggerColors.fill
+        }, triggerPress.animatedStyle, disabled && styles.dimmed, theme.elevation.lg],
+        children: [/*#__PURE__*/_jsx(Reanimated.View, {
+          pointerEvents: "none",
+          style: [StyleSheet.absoluteFill, {
+            backgroundColor: triggerOverlayColor,
+            borderRadius: theme.radii.full,
+            borderCurve: "continuous"
+          }, triggerPress.overlayStyle]
+        }), focused && /*#__PURE__*/_jsx(View, {
+          pointerEvents: "none",
+          testID: testID ? `${testID}-trigger-focus-ring` : undefined,
+          style: focusRingStyle
+        }), /*#__PURE__*/_jsx(Animated.View, {
+          style: {
+            transform: [{
+              rotate
+            }]
+          },
+          children: /*#__PURE__*/_jsx(Icon, {
+            name: icon,
+            size: spec.iconSize,
+            color: triggerColors.onFill,
+            strokeWidth: ICON_STROKE
+          })
+        })]
+      }), mounted && /*#__PURE__*/_jsx(View, {
+        style: [fabGroupActionsStackStructure(theme, {
+          align: stackAlign
+        }), styles.actionsFlow],
+        children: rows.map(row => /*#__PURE__*/_jsx(FabGroupActionRow, {
+          testID: testID ? `${testID}-action-${row.index}` : undefined,
+          action: row.action,
+          fallbackTone: tone,
+          direction: actionDirection,
+          progress: progress,
+          window: row.window,
+          onSelect: runAction
+        }, `${row.action.label}-${row.index}`))
+      })]
+    })]
+  });
+}
+export const FabGroup = /*#__PURE__*/memo(FabGroupImpl);
+//# sourceMappingURL=FabGroup.js.map

package/lib/module/modules/fab/MODULE.md

@@ -0,0 +1,194 @@
+# fab/ — a floating action button, and its speed-dial sibling
+
+`Fab` is an absolutely-positioned, safe-area-aware primary-action control — a circle, or an
+EXTENDED pill (icon + label) when `label` is given. `FabGroup` is a speed-dial: a Fab-shaped
+trigger that expands a vertical stack of labeled mini actions above itself, behind a dismiss scrim.
+Neither uses React Native's own `<Modal>` — both must stay visually anchored exactly where placed,
+which a Modal's own separate native surface can't do (see `FabGroup.tsx`'s top comment).
+
+## Files
+
+| File | Role |
+|------|------|
+| `Fab.tsx` | The button. Discriminated icon-only/extended props, tone/press/focus, safe-area anchor. |
+| `FabGroup.tsx` | The speed-dial. Controlled/uncontrolled expand state, mount-through-exit-animation lifecycle (mirrors `Drawer.tsx`), scrim, mini-action rows. |
+| `Fab.variants.ts` | Pure resolvers (`resolveFabTone`, `resolveFabAccessibility`, `resolveFabAnchorStyle`, `resolveFabFocusRingStyle`, `resolveFabGroupActionWindow`, the inset/direction/align/label resolvers) + the themed structural resolvers. No React, no lucide. |
+| `index.ts` | Public surface: `Fab`, `FabGroup`, their prop/action types, the closed unions, `IconName`. |
+| `__tests__/Fab.test.ts` | Pure: WCAG contrast (all 9 brands × both modes) + touch target + a11y + positioning/animation resolvers. |
+| `__tests__/Fab.render.test.tsx` | Render: press wiring for both, extended/icon-only, focus rings (Fab + the speed-dial trigger), FabGroup's full expand/collapse lifecycle (uncontrolled + controlled), scrim, its modal semantics, reduced motion. |
+| `__tests__/FabGroup.keyboard.web.test.tsx` | Escape, Tab confinement, focus return, and the trigger-before-actions source order. |
+
+## Props
+
+**Fab** — `icon: IconName` (required), `label?: string` (renders the EXTENDED pill), `onPress: () => void`
+(required), `tone?: accent \| neutral \| danger` (`accent`), `size?: md \| lg` (`lg`; 48/56dp — both
+already clear 44dp), `position?: bottom-right \| bottom-left \| bottom-center \| static` (`bottom-right`),
+`disabled?`, `loading?` (spinner replaces the icon, press suppressed), `accessibilityLabel?` —
+**required** when `label` is absent (type-enforced discriminated union, the same shape `ButtonProps`
+uses), `offset?: { bottom?; horizontal? }`, `style?: LayoutStyle`, `testID?`, plus the tooltip-trigger
+set `onLongPress?`/`onPressOut?`/`onHoverIn?`/`onHoverOut?`/`onFocus?`/`onBlur?`/`accessibilityHint?`/
+`aria-describedby?` (the web half of the hint — react-native-web has no `accessibilityHint`) —
+declared explicitly (no `{...rest}`) so a wrapping `Tooltip` actually reaches the control; each chains
+after the Fab's own press/focus ring rather than replacing it. **`FabGroup` does not accept them**, so
+its trigger is not a tooltip target.
+
+**FabGroup** — `actions: { icon, label, onPress, tone? }[]`, `icon?` (`"plus"`), `open?` +
+`onOpenChange?` (uncontrolled if both omitted), plus `tone?`/`size?`/`position?`/`disabled?`/
+`accessibilityLabel?`/`offset?`/`style?`/`testID?` (the trigger's own Fab-shaped props).
+`testID` seeds `${testID}-anchor`, `${testID}-trigger`, `${testID}-trigger-focus-ring`,
+`${testID}-scrim`, `${testID}-action-${index}`.
+
+## Accessibility contract (WCAG)
+
+- **2.5.5 / 2.5.8 target size** — both Fab sizes (48/56dp) and every FabGroup mini action (44dp)
+  clear the 44dp floor directly, no `hitSlop` needed.
+- **1.4.3 / 1.4.11** — `resolveFabTone`'s `onFill` is measured ≥ 4.5:1 against `fill` for every tone
+  × brand × mode (covers both the icon's 3:1 non-text floor and the extended variant's 4.5:1 text
+  label in one pairing); a FabGroup mini action's label chip text (`fg.default` on `bg.raised`) is
+  measured the same way.
+- **Icon-only rule** — `FabProps` is a discriminated union: `label?: never` + required
+  `accessibilityLabel` makes an unlabelled icon-only Fab a type error, mirroring `ButtonProps`.
+- **4.1.2** — the speed-dial trigger carries `aria-expanded`; every mini action carries its own
+  `accessibilityLabel` (always its visible `label` — a mini action is never icon-only).
+- **Flat `aria-*`, never `accessibilityState={{…}}`** — react-native-web 0.21 forwards only a flat
+  vocabulary and discards the object, so the object form shipped a role with no state at all on web.
+  `resolveFabAccessibility` returns `"aria-disabled"`/`"aria-busy"`; FabGroup's trigger adds
+  `aria-expanded`. RN's own `Pressable` merges the flat props back into `accessibilityState`, so one
+  flat form is correct on both platforms (same migration `resolveCheckboxAccessibility` documents).
+- **4.1.2 / modal semantics** — while the scrim is mounted, FabGroup's ANCHOR carries BOTH
+  `accessibilityViewIsModal` and `aria-modal` — RN's `View` understands only the first,
+  react-native-web only the second — plus `onAccessibilityEscape={closeGroup}`; the scrim itself stays
+  `accessible={false}`. Menu's `accessible={false}` backdrop is **not** a precedent for omitting
+  this: Menu's backdrop sits inside an RN `<Modal>`, whose separate native surface removes the
+  covered screen from the accessibility tree by construction. FabGroup is deliberately not a
+  `<Modal>`, so nothing did that here — the scrim blocked touch while a swipe still reached the
+  whole screen behind it. On the anchor (not the action stack) so the trigger — the "Close actions
+  menu" affordance — stays inside the modal view, and gated on `mounted` so the modality lasts
+  exactly as long as the scrim, exit animation included.
+- **2.1.1 keyboard (web only)** — FabGroup is not a `<Modal>`, so `react-native-web` gave it
+  nothing: no Escape, no Tab confinement, no focus return. (`onAccessibilityEscape` above is a
+  VoiceOver gesture; RNW does not forward it.) While the scrim is mounted the anchor now wires
+  `useDismissOnEscape` + `useFocusTrap` (`core/a11y/keyboard`), so Escape collapses the dial, Tab
+  cycles within trigger+actions, and focus returns to the trigger on collapse — including after an
+  action runs, since `runAction` collapses first.
+- **2.4.3 focus order** — the trigger and action 0 are declared FIRST in the tree, with
+  `flexDirection: "column-reverse"` on the anchor and on the action stack restoring the painted
+  layout (trigger at the bottom, action 0 just above it). Tab order follows source order, so before
+  this the actions were reachable only by Shift+Tab, bottom-to-top, after Tab had already left the
+  group. This also changes the order a screen reader walks the group on native: trigger first, then
+  the actions outward from it.
+- **2.4.7 focus indicator** — the speed-dial trigger draws the same offset `border.focus` ring `Fab`
+  does (`resolveFabFocusRingStyle`, shared by both since they are the same circular silhouette).
+- **1.4.1** — `loading` (Fab only) sets `aria-busy`; the spinner is hidden from AT with
+  `aria-hidden` — the one spelling that works natively AND on web, where
+  `accessibilityElementsHidden`/`importantForAccessibility` are discarded and left it exposed.
+- **2.3.3** — every animation in this module runs through `useMotion()` (`core/motion`), which
+  folds the OS reduce-motion setting and the device tier into one resolved duration. With motion
+  off, Fab's press state and FabGroup's expand/collapse `setValue` their final state — no tween,
+  no frozen frame — and the speed-dial unmounts immediately instead of waiting out an exit.
+
+## Patterns copied from Button / Card / Drawer / Toast (the reference modules)
+
+1. **Structure vs colour split**, **closed unions**, **discriminated icon-only prop**, **the
+   animated state-layer press overlay + offset focus ring** — all duplicated from `Button.tsx`
+   rather than imported (module isolation; same status `Toast.variants.ts` documents for its own
+   duplicated `MIN_TOUCH_TARGET`). Inside this module the ring is NOT duplicated a second time:
+   `Fab` and `FabGroup`'s trigger both call `resolveFabFocusRingStyle`.
+2. **Elevation applied directly** from `theme.elevation.lg`/`.md`/`.sm`, the same idiom `Card`/`Toast` use.
+3. **Safe-area-less bottom-inset approximation** (`resolveFabBottomInset`) — the identical formula
+   and value `Drawer.variants.ts`/`BottomNav.variants.ts` each already carry independently.
+   `react-native-safe-area-context` is an optional peer but not a real dependency of this package, so
+   `useSafeAreaInsets` is never imported here either (see "Known gaps").
+4. **Mount-through-exit-animation lifecycle** (`mounted` state + a `useEffect` on the resolved
+   `expanded` value + a plain `setTimeout` unmount) — copied from `Drawer.tsx` verbatim, including
+   *why* it's a `useEffect` reacting to the value rather than the trigger's own handler: a controlled
+   caller flipping `open` externally still animates correctly.
+5. **Source-order stacking, no `zIndex` between siblings** — the scrim declared before the
+   trigger+actions anchor, the same idiom `Menu.tsx`'s backdrop-then-sheet pair relies on.
+
+## Design decisions specific to this module
+
+- **Not RN's `<Modal>`.** A speed dial must stay visually anchored to its own on-screen position;
+  `<Modal>` presents an unrelated native surface. The scrim and the anchor are declared as siblings
+  at `FabGroup`'s own root (no wrapping node), so both resolve `position: "absolute"` against the
+  same ancestor — ordinarily the screen's own root container. The cost of that choice is that
+  nothing hides the covered screen from assistive tech for free, so the anchor declares
+  `accessibilityViewIsModal` itself (see 4.1.2 above) — a `<Modal>`-based overlay never has to.
+- **`bottom-center` centers via `alignItems`, not a measured `translateX`** — works regardless of an
+  extended Fab's caller-length-driven rendered width, the same idiom `Toast`'s centered card uses.
+- **FabGroup action rows are NOT stretched to the widest row.** The anchor's and the action stack's
+  `alignItems` are both set to the same edge (`resolveFabGroupStackAlign`), so rows size to their own
+  natural width and align flush to that edge, instead of flexbox's default `stretch` forcing every
+  row to the widest row's width and bunching shorter content at one end.
+- **A mini action's label chip is a constant neutral surface, never the action's own tone fill** —
+  the same "state isn't conveyed by a background swap" reasoning `Select`'s row fill documents.
+
+## Known gaps
+
+- **Fab's own focus ring can be clipped by its `overflow: "hidden"`** — the ring is drawn with
+  negative offsets outside the control's own bounds, and the Pressable clips to its own rect. Found
+  in the Round 5 Android-parity pass, not fixed here (unrelated to that pass's scope). FabGroup's
+  trigger avoids this: it carries no `overflow: "hidden"`, since its overlay self-clips via its own
+  `borderRadius`.
+- **No safe-area inset awareness** beyond the static iOS home-indicator approximation (see pattern
+  #3) — same documented gap `Toast`/`Drawer`/`BottomNav` already carry.
+- **No focus ring on the mini action ROWS.** The trigger reached parity with `Fab` (identical
+  circular control, identical ring geometry), but a row is a two-part composite — label chip + icon
+  circle, with a gap — and one pill ring around both would claim a silhouette the control doesn't
+  have. A design decision, not a copied style, so it is deliberately left out the way
+  `button-group`/`radio-group` record theirs; the same `onFocus`/`onBlur` pattern extends cleanly.
+- **No sibling-hiding on Android for the expanded speed dial** — `accessibilityViewIsModal` is an
+  iOS prop (react-native-web ignores it entirely, which is why `aria-modal` is emitted alongside it);
+  Android's equivalent would mean setting
+  `importantForAccessibility="no-hide-descendants"` on a tree FabGroup does not own. Same gap
+  `Modal`'s own docs record for its "no full screen-reader trap".
+- **The web focus trap only cycles Tab** — it does not pull focus back if a click outside or a
+  programmatic `focus()` takes it out of the group. Inherited from `core/a11y/keyboard`; the fix is
+  sentinel nodes at the anchor's edges.
+- **No hardware-back dismissal for FabGroup** on Android — Menu/Select/Drawer get this for free from
+  RN's own `<Modal onRequestClose>`; FabGroup deliberately isn't a Modal (see "Design decisions"), so
+  there is no `BackHandler` wiring in v1. The scrim press and the trigger's own toggle remain the
+  dismissal paths.
+- **`static` FabGroup's mini-action stack has no real anchor edge** — it defaults to the same
+  trailing (`flex-end`) alignment `bottom-right` uses, an arbitrary but documented default.
+
+## Motion
+
+Nothing in this module owns a duration, easing or `Animated.timing` config — all of it comes from
+`useMotion()` / `usePressMotion()` in `core/motion`, so retuning `core/motion/config.ts` retunes the
+Fab too. Everything animates `opacity`/`transform` only, always on the native driver.
+
+- **Press feedback** — Fab, the FabGroup trigger, and each action row all use `usePressState`
+  (`core/motion/usePressState`), the same width-aware scale + state-layer overlay + spring settle
+  every other pressable in this library uses (Round 5 press-feedback unification).
+- **FabGroup expand/collapse** — one classic `progress` value; the trigger glyph rotates 0→45°, the
+  scrim fades, and each action row reveals over its own slice of that same value.
+- **The action stagger is decorative** (`motion.decorative`, high tier only). It is expressed as a
+  per-row interpolation *window* (`resolveFabGroupActionWindow`), not per-row animations: no extra
+  timers or `Animated.Value`s, and it reverses correctly on close. On low/mid tier every row shares
+  the full `[0, 1]` window and the rows reveal together.
+- **Action rows nest two animation systems**: an outer classic-`Animated.View` reveal (opacity +
+  translateY, tied to `progress`) wraps the inner `usePressState`-driven `AnimatedPressable` — the
+  two fades compose by nesting instead of `Animated.multiply`.
+- In-flight animations are stopped on effect cleanup and on unmount.
+
+## Performance
+
+Both wrapped in `React.memo`. `toggle`/`closeGroup`/`requestExpandedChange`/`runAction` are
+`useCallback`'d, and each action row is its own `React.memo`'d `FabGroupActionRow` with a stable
+`onSelect` — the per-row `onPress` closure, tone lookup and style arrays are no longer rebuilt on
+every parent render. The reversed row list is `useMemo`'d. The action stack and scrim are built only
+while `mounted` (never while the trigger alone is on screen), matching Menu/Select/Drawer's
+identical "sheet content built only while open" convention.
+
+## Modernization (v1.0.7)
+
+- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
+- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
+- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.
+
+- **Round 2 visual** — radii retarget (`radii.md`/`lg`/`xl`/`full`), `borderCurve: continuous` on md+ corners; floating surfaces wire platform elevation/highlight where applicable.
+- **Round 5 (Android parity + press unification)** — Fab, the trigger, and action rows switched from
+  hand-rolled classic-`Animated` press timing to the shared `usePressState`; `android_ripple` added
+  everywhere it was missing (`borderless: true` on the two circular icon-only targets, `false`
+  elsewhere); the trigger gained a press-state overlay matching Fab's own.

package/lib/module/modules/fab/index.js

@@ -0,0 +1,13 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/fab`. Value exports and type exports are split for
+ * `verbatimModuleSyntax`. The resolvers stay internal — a consumer configures a Fab/FabGroup through
+ * their props, never by importing internals.
+ */
+
+export { Fab } from "./Fab.js";
+export { FabGroup } from "./FabGroup.js";
+
+// Re-exported so a caller can type an `icon`/action `icon` prop without a separate import from `core/icon`.
+//# sourceMappingURL=index.js.map