pixelize-native-library 1.0.7 → 1.2.1

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

@@ -0,0 +1,192 @@
+"use strict";
+
+/**
+ * Fab — a floating action button: an absolutely-positioned, safe-area-aware primary-action circle
+ * (or pill, when `label` is given — the EXTENDED variant, icon + text). It renders one small
+ * wrapper View around its own `Pressable` — `position: "absolute"` for every floating `position`,
+ * plain in-flow `position: "relative"` for `"static"` — so `bottom-center` can center a
+ * variable-width extended Fab via `alignItems` rather than a measured `translateX`
+ * (`resolveFabAnchorStyle`'s own comment has the full reasoning).
+ *
+ * `FabProps` is a discriminated union, the same shape `ButtonProps` already establishes: a labelled
+ * (extended) Fab, or an icon-only Fab whose `accessibilityLabel` is REQUIRED at the type level — the
+ * same unlabelled-icon-button trap `Button.tsx`'s own top comment documents; `label?: never` keeps
+ * the two shapes mutually exclusive.
+ *
+ * Press feedback (one motion-system value driving the state-layer overlay + the press scale, with a
+ * brightness-aware scrim direction) and the offset focus ring are Button's own techniques, copied
+ * here rather than imported — `fab/` stays
+ * free of a cross-module dependency on `button/` internals, the same isolation `Toast.variants.ts`
+ * documents for its own duplicated `MIN_TOUCH_TARGET`.
+ */
+
+import { memo, useCallback, useMemo, useState } from "react";
+import { ActivityIndicator, Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import Animated from "react-native-reanimated";
+import { usePressState } from "../../core/motion/usePressState.js";
+import { Icon } from "../../core/icon/index.js";
+import { AccentGradientFill } from "../../core/gradient/index.js";
+import { elevation, floatingSurfaceStyle, highlight } from "../../theme/platform/index.js";
+import { elevation as elevationTokens } from "../../theme/tokens/primitives/index.js";
+import { rippleColor } from "../../theme/platform/stateLayer.native.js";
+import { useTheme } from "../../theme/hooks.js";
+import { fabCircleStructure, fabExtendedStructure, fabOverlayColor, FAB_SIZES, resolveFabAccessibility, resolveFabAnchorStyle, resolveFabBottomInset, resolveFabFocusRingStyle, resolveFabHorizontalInset, resolveFabTone } from "./Fab.variants.js";
+
+/** A Fab with a visible text label — the EXTENDED variant (a pill, icon + text). */
+
+/** An icon-only Fab. No visible text, so `accessibilityLabel` is REQUIRED at the type level — the
+ *  same trap `Button`'s icon-only shape closes. `label?: never` keeps the two shapes exclusive. */
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
+const ICON_STROKE = 2;
+function FabImpl(props) {
+  const {
+    icon,
+    label,
+    onPress,
+    onLongPress,
+    onPressOut,
+    onHoverIn,
+    onHoverOut,
+    onFocus,
+    onBlur,
+    tone = "accent",
+    size = "lg",
+    position = "bottom-right",
+    disabled = false,
+    loading = false,
+    offset,
+    style,
+    testID,
+    accessibilityLabel,
+    accessibilityHint,
+    "aria-describedby": ariaDescribedBy
+  } = props;
+  const theme = useTheme();
+  const blocked = disabled || loading;
+  const press = usePressState(blocked);
+  // Keyboard / external-keyboard / assistive-tech focus (no-op on pure touch, correct everywhere else).
+  const [focused, setFocused] = useState(false);
+  const spec = FAB_SIZES[size];
+  const toneColors = resolveFabTone(theme.colors, tone);
+  const a11y = resolveFabAccessibility({
+    label,
+    accessibilityLabel,
+    disabled,
+    loading,
+    onPress
+  });
+  const overlayColor = fabOverlayColor(toneColors.onFill);
+  const extended = label !== undefined;
+  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.docked
+  });
+  const handlePressOut = useCallback(event => {
+    press.handlers.onPressOut();
+    onPressOut?.(event);
+  }, [press.handlers, onPressOut]);
+  const handleFocus = useCallback(event => {
+    setFocused(true);
+    onFocus?.(event);
+  }, [onFocus]);
+  const handleBlur = useCallback(event => {
+    setFocused(false);
+    onBlur?.(event);
+  }, [onBlur]);
+  const focusRingStyle = useMemo(() => resolveFabFocusRingStyle(theme.colors.border.focus, theme.radii.full), [theme.colors.border.focus, theme.radii.full]);
+  const floatingDepth = useMemo(() => {
+    highlight("subtle", theme.mode);
+    elevation(elevationTokens.md);
+    void theme.elevatedSurfaces;
+    return floatingSurfaceStyle(theme, "md");
+  }, [theme]);
+  const androidRipple = useMemo(() => {
+    if (Platform.OS !== "android" || blocked) return undefined;
+    return {
+      color: rippleColor(theme.mode),
+      borderless: !extended
+    };
+  }, [blocked, theme.mode, extended]);
+
+  // aria-busy already announces loading; the spinner itself is hidden from AT.
+  const content = loading ? /*#__PURE__*/_jsx(ActivityIndicator, {
+    size: "small",
+    color: toneColors.onFill,
+    "aria-hidden": true
+  }) : /*#__PURE__*/_jsx(Icon, {
+    name: icon,
+    size: spec.iconSize,
+    color: toneColors.onFill,
+    strokeWidth: ICON_STROKE
+  });
+  return /*#__PURE__*/_jsx(View, {
+    style: [anchor, style],
+    pointerEvents: "box-none",
+    children: /*#__PURE__*/_jsxs(AnimatedPressable, {
+      testID: testID,
+      accessibilityRole: a11y.accessibilityRole,
+      accessibilityLabel: a11y.accessibilityLabel,
+      accessibilityHint: accessibilityHint,
+      "aria-describedby": ariaDescribedBy,
+      "aria-disabled": a11y["aria-disabled"],
+      "aria-busy": a11y["aria-busy"],
+      disabled: a11y.disabled,
+      onPress: a11y.onPress,
+      onLongPress: onLongPress,
+      onPressIn: press.handlers.onPressIn,
+      onPressOut: handlePressOut,
+      onHoverIn: onHoverIn,
+      onHoverOut: onHoverOut,
+      onFocus: handleFocus,
+      onBlur: handleBlur,
+      onLayout: press.onLayout,
+      android_ripple: androidRipple,
+      style: [extended ? fabExtendedStructure(theme, {
+        size
+      }) : fabCircleStructure(theme, {
+        size
+      }), {
+        overflow: "hidden",
+        ...floatingDepth
+      }, press.animatedStyle, (disabled || loading) && styles.dimmed],
+      children: [/*#__PURE__*/_jsx(AccentGradientFill, {
+        color: toneColors.fill
+      }), /*#__PURE__*/_jsx(Animated.View, {
+        pointerEvents: "none",
+        style: [StyleSheet.absoluteFill, {
+          backgroundColor: overlayColor,
+          borderRadius: theme.radii.full,
+          borderCurve: "continuous"
+        }, press.overlayStyle]
+      }), focused && /*#__PURE__*/_jsx(View, {
+        pointerEvents: "none",
+        testID: testID ? `${testID}-focus-ring` : undefined,
+        style: focusRingStyle
+      }), content, extended && /*#__PURE__*/_jsx(Text, {
+        numberOfLines: 1,
+        style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+          fontSize: spec.fontSize,
+          color: toneColors.onFill
+        }],
+        children: label
+      })]
+    })
+  });
+}
+const styles = StyleSheet.create({
+  // A disabled/loading control is exempt from the contrast minimum (WCAG 1.4.3), so a uniform dim is
+  // correct — same idiom Button's own `dimmed` style uses.
+  dimmed: {
+    opacity: 0.5
+  }
+});
+
+// A consumer's screen re-renders far more often than Fab's own props change — memo is near-free
+// insurance for a design-system primitive (see CLAUDE.md "Performance" section).
+export const Fab = /*#__PURE__*/memo(FabImpl);
+//# sourceMappingURL=Fab.js.map

package/lib/module/modules/fab/Fab.variants.js

@@ -0,0 +1,360 @@
+"use strict";
+
+/**
+ * Fab's style + behaviour resolution — same split as Button/Card:
+ *  - STRUCTURE (diameter/padding/radius) lives in the `createThemedVariants` resolvers below, static
+ *    per (brand, mode), registered once via `StyleSheet.create`.
+ *  - COLOUR is tone-driven and resolved from the theme's ROLE colours by `resolveFabTone` — the same
+ *    three-tone mapping `resolveButtonTone` uses for Button's `solid` variant (a Fab IS a solid
+ *    circular/pill button; there is no outline/ghost/link shape here). Duplicated, not imported —
+ *    modules stay isolated, the same status `Toast.variants.ts` documents for its own duplicated
+ *    `MIN_TOUCH_TARGET`.
+ *  - ACCESSIBILITY prop derivation is `resolveFabAccessibility`, the same disabled/loading→busy,
+ *    gated-onPress contract `resolveButtonAccessibility` establishes.
+ *  - POSITIONING (`resolveFabAnchorStyle`, `resolveFabBottomInset`, `resolveFabHorizontalInset`) is
+ *    pure so the safe-area-less approximation is unit-testable without rendering React Native — the
+ *    same idiom `Drawer.variants.ts`'s `resolveDrawerBottomInset` and `BottomNav.variants.ts`'s
+ *    `resolveBottomNavBottomInset` already establish (see MODULE.md "Known gaps" for why
+ *    `react-native-safe-area-context` isn't imported here either — it is an optional peer, not a
+ *    real dependency of this package).
+ *
+ * Free of React, lucide, and any Pressable/Animated import, so the WCAG + behaviour tests import it
+ * directly (mocking only `react-native`'s `StyleSheet`, as `core/style` does).
+ */
+
+import { createThemedVariants } from "../../core/style/index.js";
+/** Both sizes already clear this floor directly (48dp / 56dp) — no `hitSlop` needed, unlike Button's
+ *  shorter sizes (WCAG 2.5.5 AAA / Apple HIG minimum). */
+export const MIN_TOUCH_TARGET = 44;
+export const FAB_SIZES = {
+  md: {
+    diameter: 48,
+    iconSize: 20,
+    fontSize: 14,
+    extendedPaddingHorizontal: 16
+  },
+  lg: {
+    diameter: 56,
+    iconSize: 24,
+    fontSize: 16,
+    extendedPaddingHorizontal: 20
+  }
+};
+
+/** A FabGroup mini action reads at one fixed size, independent of the trigger's own `size` — the
+ *  same "an action list's row size isn't a caller-facing choice" precedent `Menu`'s row size sets. */
+export const FAB_ACTION_SIZE = MIN_TOUCH_TARGET;
+export const FAB_ACTION_ICON_SIZE = 18;
+/**
+ * Maps `tone` onto the theme's role colours — identical to `resolveButtonTone`'s `solid` branch (a
+ * Fab has no outline/ghost/link shape, so only `fill`/`onFill` are needed). The whole reason the
+ * prop is a closed union and not `color?: string`: every colour a Fab can show is one of these role
+ * lookups, so it inverts light↔dark for free and can never be an off-palette value an app invented.
+ */
+export function resolveFabTone(colors, tone) {
+  switch (tone) {
+    case "accent":
+      return {
+        fill: colors.accent.solid,
+        onFill: colors.accent.onSolid
+      };
+    case "danger":
+      return {
+        fill: colors.status.danger.solid,
+        onFill: colors.status.danger.onSolid
+      };
+    case "neutral":
+      // Monochrome high-emphasis — the identical substitution Button's own "neutral" tone documents.
+      return {
+        fill: colors.fg.default,
+        onFill: colors.bg.canvas
+      };
+  }
+}
+const FAB_PRESS_SCRIM_DARK = "#00000026";
+const FAB_PRESS_SCRIM_LIGHT = "#ffffff26";
+function isLightOnFill(hex) {
+  const n = parseInt(hex.slice(1, 7), 16);
+  const r = n >> 16 & 0xff;
+  const g = n >> 8 & 0xff;
+  const b = n & 0xff;
+  return r * 0.299 + g * 0.587 + b * 0.114 > 140;
+}
+
+/** Press scrim direction, chosen by brightness — shared by `Fab` and `FabGroup`'s trigger. */
+export function fabOverlayColor(onFill) {
+  return isLightOnFill(onFill) ? FAB_PRESS_SCRIM_DARK : FAB_PRESS_SCRIM_LIGHT;
+}
+/**
+ * Same disabled/loading→busy, gated-onPress derivation as `resolveButtonAccessibility` (WCAG 1.4.1
+ * busy announcement / 4.1.2 name-role-value), kept pure so it's testable without rendering RN.
+ *
+ * FLAT `aria-*`, not `accessibilityState={{…}}`: react-native-web 0.21 forwards a purely flat
+ * vocabulary and drops the object entirely, so the web build announced the role with no state at
+ * all. RN's own `Pressable` merges the flat props back INTO `accessibilityState`, so one flat form
+ * is correct on both platforms — the same migration `resolveCheckboxAccessibility` documents.
+ */
+export function resolveFabAccessibility(input) {
+  const isDisabled = input.disabled === true;
+  const isLoading = input.loading === true;
+  const blocked = isDisabled || isLoading;
+  return {
+    accessibilityRole: "button",
+    accessibilityLabel: input.accessibilityLabel ?? input.label,
+    "aria-disabled": blocked,
+    "aria-busy": isLoading,
+    disabled: blocked,
+    onPress: blocked ? undefined : input.onPress
+  };
+}
+
+/**
+ * iOS home-indicator approximation — same formula and value `Drawer.variants.ts`'s
+ * `DRAWER_IOS_HOME_INDICATOR_INSET` and `BottomNav.variants.ts`'s `BOTTOM_NAV_IOS_HOME_INDICATOR_INSET`
+ * each carry independently. `react-native-safe-area-context` is listed as an optional peer in
+ * `package.json`, but — as both of those modules' own MODULE.md already record — it is not actually
+ * installed as a dependency of THIS package, so importing `useSafeAreaInsets` here would resolve in
+ * this repo's dev sandbox and then fail in a consumer app that hasn't separately installed it. Carried
+ * a third time here rather than imported from a sibling module's `.variants.ts` — cross-module
+ * internals reach-in isn't a dependency this library's modules take on each other.
+ */
+export const FAB_IOS_HOME_INDICATOR_INSET = 20;
+
+/** Adds the static iOS home-indicator approximation, plus any caller-supplied `offset.bottom`, to a
+ *  base padding. Android's gesture/3-button nav already reserves its own space outside the app
+ *  window, so it gets no extra padding beyond the caller's own `offset`. */
+export function resolveFabBottomInset(basePadding, platformOS, extra = 0) {
+  const safeArea = platformOS === "ios" ? FAB_IOS_HOME_INDICATOR_INSET : 0;
+  return basePadding + safeArea + extra;
+}
+
+/** Adds any caller-supplied `offset.horizontal` to a base padding — no platform-specific inset on
+ *  this axis (the home-indicator approximation above is bottom-edge only). */
+export function resolveFabHorizontalInset(basePadding, extra = 0) {
+  return basePadding + extra;
+}
+/**
+ * The wrapper Fab/FabGroup render around their own control. `bottom-center` spans the full width
+ * (`left: 0, right: 0`) and centers via `alignItems` rather than a measured `translateX` — the same
+ * idiom `Toast.variants.ts`'s `toastOverlayStructure` already uses for its own centered card, which
+ * works regardless of the (possibly caller-length-driven) rendered width of an extended Fab.
+ * `bottom-right`/`bottom-left` edge-anchor directly; their `alignItems` also right/left-aligns
+ * FabGroup's mini-action rows (which vary in width) flush against the trigger's own edge. `static`
+ * renders no absolute positioning at all — the caller places it exactly like any other in-flow
+ * element, and gets no `zIndex` either (nothing to float above).
+ */
+export function resolveFabAnchorStyle(input) {
+  if (input.position === "static") return {
+    position: "relative"
+  };
+  const base = {
+    position: "absolute",
+    bottom: input.bottomInset,
+    zIndex: input.zIndex
+  };
+  switch (input.position) {
+    case "bottom-right":
+      return {
+        ...base,
+        right: input.horizontalInset,
+        alignItems: "flex-end"
+      };
+    case "bottom-left":
+      return {
+        ...base,
+        left: input.horizontalInset,
+        alignItems: "flex-start"
+      };
+    case "bottom-center":
+      return {
+        ...base,
+        left: 0,
+        right: 0,
+        alignItems: "center"
+      };
+  }
+}
+
+/** Whether a FabGroup action row reads label-then-icon or icon-then-label. The label always renders
+ *  toward screen CENTER, away from the edge the group is anchored to, so it can never clip off-screen
+ *  on a narrow device — `bottom-right`/`bottom-center`/`static` all read label-then-icon (nothing to
+ *  clip on the left); only `bottom-left` flips. */
+export function resolveFabGroupActionDirection(position) {
+  return position === "bottom-left" ? "row-reverse" : "row";
+}
+
+/** The mini-action stack's own cross-axis alignment — matches `resolveFabAnchorStyle`'s edge for the
+ *  floating positions; `static` defaults to the same trailing edge as `bottom-right` (an arbitrary
+ *  but documented default — see MODULE.md "Design decisions"), since a `static` group's actions have
+ *  no anchor edge of their own to read. */
+export function resolveFabGroupStackAlign(position) {
+  switch (position) {
+    case "bottom-left":
+      return "flex-start";
+    case "bottom-center":
+      return "center";
+    case "bottom-right":
+    case "static":
+      return "flex-end";
+  }
+}
+
+/** The speed-dial trigger's accessible name: the caller's own override, else "Open"/"Close actions
+ *  menu" swapping with `expanded` — the same fixed-default-with-override idiom Toast's close button
+ *  uses (`accessibilityLabel="Dismiss notification"`), reflecting the disclosure action itself since
+ *  the trigger has no visible label of its own to fall back to. */
+export function resolveFabGroupTriggerAccessibilityLabel(expanded, override) {
+  if (override !== undefined) return override;
+  return expanded ? "Close actions menu" : "Open actions menu";
+}
+
+/** Longest slice of the shared progress value the stagger may consume — the last row still gets
+ *  half the run, so a long action list never crawls. */
+const FAB_GROUP_STAGGER_SPAN = 0.5;
+const FAB_GROUP_STAGGER_STEP = 0.15;
+
+/**
+ * The slice of the speed-dial's single `progress` value one action row reveals over. Staggering by
+ * interpolation window rather than per-row animations costs no extra timers or Animated values, and
+ * reverses correctly on close. `staggered` is false whenever the device tier can't afford decorative
+ * motion, which collapses every row onto the same [0, 1] window.
+ */
+export function resolveFabGroupActionWindow(index, count, staggered) {
+  const step = staggered ? Math.min(FAB_GROUP_STAGGER_STEP, FAB_GROUP_STAGGER_SPAN / Math.max(count - 1, 1)) : 0;
+  const start = step * index;
+  return [start, start + (1 - step * Math.max(count - 1, 0))];
+}
+
+/** The focus ring sits a small gap OUTSIDE the control, on the canvas, because `border.focus` is the
+ *  role token proven ≥ 3:1 against the canvas (WCAG 2.4.11) — drawn over a solid fill it could fail. */
+export const FAB_FOCUS_RING_WIDTH = 2;
+export const FAB_FOCUS_RING_GAP = 2;
+/** The offset ring `Fab` and `FabGroup`'s trigger both draw on focus — one definition, since the two
+ *  are the same circular silhouette. Kept a pure function of the two role/scale values it needs, so
+ *  the ring geometry is unit-testable without rendering React Native. */
+export function resolveFabFocusRingStyle(borderColor, borderRadius) {
+  const offset = -(FAB_FOCUS_RING_GAP + FAB_FOCUS_RING_WIDTH);
+  return {
+    position: "absolute",
+    top: offset,
+    left: offset,
+    right: offset,
+    bottom: offset,
+    borderWidth: FAB_FOCUS_RING_WIDTH,
+    borderColor,
+    borderRadius
+  };
+}
+
+/** The dismiss scrim behind an expanded FabGroup — a design constant, not a role token: decorative,
+ *  same status `BACKDROP_SCRIM` (Menu/Select) and `DRAWER_BACKDROP` already have. */
+export const FAB_GROUP_SCRIM = "#00000080";
+
+/** Structural circle — the icon-only shape. Colour (fill) is tone-driven, applied inline over this. */
+export const fabCircleStructure = createThemedVariants(theme => ({
+  base: {
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: theme.radii.full
+  },
+  variants: {
+    size: {
+      md: {
+        width: FAB_SIZES.md.diameter,
+        height: FAB_SIZES.md.diameter
+      },
+      lg: {
+        width: FAB_SIZES.lg.diameter,
+        height: FAB_SIZES.lg.diameter
+      }
+    }
+  },
+  defaultVariants: {
+    size: "lg"
+  }
+}));
+
+/** Structural pill — the extended (icon + label) shape. Width hugs its content. */
+export const fabExtendedStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: theme.radii.full,
+    columnGap: theme.space[2]
+  },
+  variants: {
+    size: {
+      md: {
+        height: FAB_SIZES.md.diameter,
+        paddingHorizontal: FAB_SIZES.md.extendedPaddingHorizontal
+      },
+      lg: {
+        height: FAB_SIZES.lg.diameter,
+        paddingHorizontal: FAB_SIZES.lg.extendedPaddingHorizontal
+      }
+    }
+  },
+  defaultVariants: {
+    size: "lg"
+  }
+}));
+
+/** The column of mini-action rows above the trigger. `align` mirrors `resolveFabGroupStackAlign` so
+ *  rows size to their own natural width (never stretched to the widest row) and align flush to the
+ *  correct edge — see MODULE.md "Design decisions" for the flexbox reasoning. */
+export const fabGroupActionsStackStructure = createThemedVariants(theme => ({
+  base: {
+    rowGap: theme.space[3],
+    marginBottom: theme.space[4]
+  },
+  variants: {
+    align: {
+      "flex-end": {
+        alignItems: "flex-end"
+      },
+      "flex-start": {
+        alignItems: "flex-start"
+      },
+      center: {
+        alignItems: "center"
+      }
+    }
+  },
+  defaultVariants: {
+    align: "flex-end"
+  }
+}));
+
+/** One FabGroup mini-action row: label chip + icon circle, laid out by `resolveFabGroupActionDirection`. */
+export const fabGroupActionRowStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    minHeight: FAB_ACTION_SIZE,
+    columnGap: theme.space[2]
+  }
+}));
+
+/** The mini action's own circular icon backdrop. */
+export const fabGroupActionCircleStructure = createThemedVariants(theme => ({
+  base: {
+    width: FAB_ACTION_SIZE,
+    height: FAB_ACTION_SIZE,
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: theme.radii.full
+  }
+}));
+
+/** The mini action's label chip — a small elevated surface, never the action's own tone fill: labels
+ *  are read against one constant neutral surface regardless of the action's tone, the same
+ *  "selection/emphasis isn't conveyed by a background swap" reasoning `Select`'s row fill documents. */
+export const fabGroupActionLabelStructure = createThemedVariants(theme => ({
+  base: {
+    borderRadius: theme.radii.full,
+    paddingHorizontal: theme.space[3],
+    paddingVertical: theme.space[2]
+  }
+}));
+//# sourceMappingURL=Fab.variants.js.map