pixelize-native-library 1.0.7 → 1.2.1

package/lib/module/modules/search-bar/MODULE.md

@@ -0,0 +1,115 @@
+# search-bar/ — a query field with the affordances every list screen re-implements
+
+`SearchBar` bundles what a search box needs beyond a plain text field: a leading `search` glyph
+(swapped for a spinner while `loading`), a trailing clear button with its own accessible name and
+touch target, optional debounced reporting, and an optional "Cancel" text button. It owns its own
+`TextInput` rather than wrapping `input/` — see "Design decisions" below.
+
+## Files
+
+| File | Role |
+|------|------|
+| `SearchBar.tsx` | The component. Field composition, debounce timer, clear/cancel wiring, a11y wiring, focus ring. |
+| `SearchBar.variants.ts` | Pure resolvers (`resolveSearchBarColors`, `resolveSearchBarBorderColor`, `resolveSearchBarAccessibility`, `shouldShowClear`, `resolveSearchBarFieldHitSlop`, `resolveSearchBarTrailingHitSlop`) + the themed structural resolvers (`searchBarRowStructure`, `searchBarFieldStructure`, `searchBarClearStructure`, `searchBarCancelStructure`). No React, no lucide. |
+| `index.ts` | Public surface: `SearchBar`, `SearchBarProps`, `SearchBarSize`. |
+| `__tests__/SearchBar.test.ts` | Pure: WCAG contrast (all brands × modes) + per-edge touch target + visibility/a11y contracts. |
+| `__tests__/SearchBar.render.test.tsx` | Render: value/placeholder, the field's `search` role, immediate vs debounced typing, clear isolation, `showCancel` lifecycle, submit flushing a pending debounce, focus ring, the rendered per-edge `hitSlop`. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `value` | `string` | — | Required — controlled. |
+| `onChangeText` | `(text: string) => void` | — | Required. Debounced per `debounceMs`; the rendered text never lags. |
+| `placeholder` | `string` | `"Search"` | Falls back into the field's `accessibilityLabel` — SearchBar renders no visible label. |
+| `accessibilityLabel` | `string` | `placeholder` | Overrides the placeholder fallback — a placeholder that reads as a prompt ("Search…") rather than a name tells a screen-reader user nothing about WHAT is being searched. Previously absent: the placeholder was the only name, with no override. |
+| `onSubmit` | `() => void` | — | Fires on the keyboard's search key. Flushes a pending debounce first. |
+| `onClear` | `() => void` | — | Fires after the clear button or "Cancel" empties the query. |
+| `debounceMs` | `number` | `0` | `0` = report every keystroke. Above `0`, `onChangeText` is debounced while local state keeps the visible text instant. |
+| `showCancel` | `boolean` | `false` | Reveals a trailing "Cancel" text button on focus. |
+| `cancelLabel` | `string` | `"Cancel"` | |
+| `loading` | `boolean` | `false` | Swaps the leading `search` icon for `Spinner`. |
+| `autoFocus` | `boolean` | `false` | |
+| `disabled` | `boolean` | `false` | Dims the field, blocks editing, hides the clear button even with a query. |
+| `size` | `sm \| md` | `md` | 32 / 40 dp — identical numbers to `Input`'s `sm`/`md`. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost (the row `View`), applied exactly once, last. |
+| `testID` | `string` | — | Seeds `${testID}-input`, `${testID}-clear`, `${testID}-cancel`, `${testID}-spinner`. |
+
+No `status`/`tone` union and no `label` — a search field reports no validity state and needs no
+above-field caption; the placeholder carries the only name it has.
+
+## Accessibility contract (WCAG)
+
+- **4.1.2 / semantics** — the **`TextInput`** carries `accessibilityRole="search"`, not the row. The
+  row is a plain layout `View` that is not `accessible`, so a role there reached neither platform
+  (iOS never got the search trait; Android put it on a non-focusable ViewGroup) — the role has to sit
+  on the node that actually takes focus. The clear button and the "Cancel" button are separate
+  `button`-role `Pressable`s with their own labels (`"Clear search"`, `cancelLabel`) — activating
+  either can never be confused with submitting, the same isolation `Banner`'s dismiss-vs-action split
+  documents.
+- **2.5.8 / 2.5.5 target size** — the field reaches ≥ 44dp via `hitSlop`, same mechanism as `Input`.
+  The clear button's height comes from `alignSelf: "stretch"` + the field's own vertical hitSlop; its
+  WIDTH is a structural 44dp `CLEAR_BUTTON_WIDTH`, not hitSlop — horizontal hitSlop on either the
+  field or the clear button would overlap the other (RN resolves an overlap to whichever renders
+  LATER, silently stealing taps), so `resolveSearchBarFieldHitSlop` zeroes the field's right edge
+  once any trailing affordance renders, and `resolveSearchBarTrailingHitSlop` zeroes the clear
+  button's own left/right — the identical per-edge elimination `ButtonGroup` documents for its
+  segments. The "Cancel" button gets `minWidth: 44` for the same reason. `SearchBar.render.test.tsx`
+  asserts the **rendered** `hitSlop` prop on the field, the clear button and the cancel button per
+  size — the resolver arithmetic in `SearchBar.test.ts` only reaches the user if the object lands on
+  the node.
+- **1.4.3** — query text, placeholder, and the "Cancel" label are each measured ≥ 4.5:1 against
+  `bg.canvas` (the field renders no fill, like `Input`'s box) for all 8 brands × both modes. The
+  pressed clear/cancel foreground is measured ≥ 4.5:1 against its own `pressedFill` too — not just
+  assumed from the resting canvas pairing.
+- **1.4.11** — the field's resting and focused border, and the leading/clear glyphs, are measured
+  ≥ 3:1 against the canvas.
+- **2.4.7** — a `border.focus` ring appears offset outside the field on focus, identical
+  geometry/token to `Input`'s.
+- **2.3.3** — n/a: nothing here animates (the cancel button is a conditional render, not a
+  transition). The one moving part, `loading`'s `Spinner`, already honours reduced motion itself.
+
+## Patterns copied from Input / ButtonGroup / Menu
+
+1. **Structure vs colour split**, **pure testable resolvers**, **closed `size` union**, no
+   `{...rest}`, `style` once on the outermost node.
+2. **Per-edge hitSlop elimination** — copied from `ButtonGroup`'s segment-edge fix, applied to the
+   field/clear/cancel trio instead of a segmented row.
+3. **`bg.sunken` (not `bg.hover`) for a pressed fill** — same reasoning as `Menu`'s pressed row.
+4. **Clear/cancel presses** — `usePressState` (scale + state-layer overlay) on both affordances.
+
+## Design decisions specific to this module
+
+- **Owns its own `TextInput` rather than wrapping `Input`.** `Input`'s `trailingIcon` is documented
+  decorative-only — it cannot host a separate pressable, which "clearing never fires submit" requires
+  — and `Input` exposes no submit/focus/autoFocus surface. Widening `Input` for one consumer would
+  push search-only concerns into every form field; this is a standalone sibling, like `ButtonGroup`
+  not importing `Button`, that mirrors `Input`'s size specs and role tokens instead of inventing new
+  ones.
+- **Debounce keeps a local `draft` for the rendered text and a `ref` of the last-emitted value.** An
+  external reset (e.g. a "clear filters" button elsewhere on screen) that changes the `value` prop
+  must still reach the field even mid-debounce, but the effect only re-syncs when `value` differs
+  from what this component itself last emitted — otherwise its own debounced echo would fight newer
+  keystrokes.
+- **`showCancel` visibility is separate state from `focused`.** The cancel button, once revealed,
+  stays visible through its own press (which blurs the field) instead of vanishing on blur first —
+  otherwise pressing it would hide the button out from under the tap.
+
+## Known gaps
+
+- No leading/trailing custom icon slot — the glyphs are fixed (`search` / spinner / `x`), matching
+  the spec this module was built against.
+- `debounceMs` has no visual "typing…" indicator beyond `loading` (which is caller-driven, not tied
+  to the debounce window itself).
+
+## Performance
+
+Wrapped in `React.memo`. `handleChangeText`, `handleClear`, `handleSubmit`, `handleFocus`, and
+`handleCancel` are all `useCallback`'d; the debounce `setTimeout` is cleared on unmount and on every
+new keystroke so no stale timer can fire after the value has moved on.
+
+## 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.

package/lib/module/modules/search-bar/SearchBar.js

@@ -0,0 +1,276 @@
+"use strict";
+
+/**
+ * SearchBar — the affordances every list screen re-implements around a query field: a leading
+ * `search` glyph (swapped for a `Spinner` while `loading`), a trailing clear button with its own
+ * accessible name and its own 44dp target, optional debounced reporting, and an optional "Cancel"
+ * text button.
+ *
+ * It owns its own `TextInput` rather than wrapping this library's `Input`. Reuse was evaluated:
+ * `Input`'s `trailingIcon` is documented decorative-only (it cannot host a separate pressable, which
+ * is exactly what "clearing never fires submit" requires), and `Input` exposes no submit/focus/
+ * autoFocus surface. Widening `Input` for one consumer would push search concerns into every form
+ * field, so — like `ButtonGroup` not importing `Button` — this is a standalone sibling that mirrors
+ * `Input`'s size specs, role tokens, and offset focus ring exactly instead of inventing new ones.
+ *
+ * Nothing here animates (the cancel button is a conditional render, not a transition), so there is
+ * no motion for `useReducedMotion` (WCAG 2.3.3) to gate. The one moving part on screen — the
+ * `loading` spinner — is `Spinner`'s own, which already honours reduced motion internally.
+ */
+
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Platform, Pressable, StyleSheet, Text, TextInput, View } from "react-native";
+import Animated from "react-native-reanimated";
+import { Icon } from "../../core/icon/index.js";
+import { usePressState } from "../../core/motion/usePressState.js";
+import { floatingBackground, floatingSurfaceStyle } from "../../theme/platform/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { Spinner } from "../spinner/index.js";
+import { resolveSearchBarAccessibility, resolveSearchBarBorderColor, resolveSearchBarColors, resolveSearchBarFieldHitSlop, resolveSearchBarTrailingHitSlop, SEARCH_BAR_SIZES, searchBarCancelStructure, searchBarClearStructure, searchBarFieldStructure, searchBarRowStructure, shouldShowClear } from "./SearchBar.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const FOCUS_RING_WIDTH = 2;
+const FOCUS_RING_GAP = 2;
+const ICON_STROKE = 2;
+const CLEAR_ACCESSIBILITY_LABEL = "Clear search";
+const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
+export const SearchBar = /*#__PURE__*/memo(function SearchBar({
+  value,
+  onChangeText,
+  placeholder = "Search",
+  onSubmit,
+  onClear,
+  debounceMs = 0,
+  showCancel = false,
+  cancelLabel = "Cancel",
+  loading = false,
+  autoFocus = false,
+  disabled = false,
+  size = "md",
+  accessibilityLabel,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const inputRef = useRef(null);
+  const timerRef = useRef(undefined);
+  const emittedRef = useRef(value);
+  const [draft, setDraft] = useState(value);
+  const [focused, setFocused] = useState(false);
+  const [cancelVisible, setCancelVisible] = useState(false);
+  const debounced = debounceMs > 0;
+  const displayed = debounced ? draft : value;
+
+  // An external reset (a "clear filters" button elsewhere on the screen) must reach the field even
+  // while a debounce is pending — but echoing back the value this component just emitted would
+  // clobber newer keystrokes with a stale one.
+  useEffect(() => {
+    if (value !== emittedRef.current) {
+      emittedRef.current = value;
+      setDraft(value);
+    }
+  }, [value]);
+  useEffect(() => () => {
+    if (timerRef.current !== undefined) clearTimeout(timerRef.current);
+  }, []);
+  const emit = useCallback(next => {
+    emittedRef.current = next;
+    onChangeText(next);
+  }, [onChangeText]);
+  const handleChangeText = useCallback(next => {
+    setDraft(next);
+    if (!debounced) {
+      emit(next);
+      return;
+    }
+    if (timerRef.current !== undefined) clearTimeout(timerRef.current);
+    timerRef.current = setTimeout(() => {
+      timerRef.current = undefined;
+      emit(next);
+    }, debounceMs);
+  }, [debounced, debounceMs, emit]);
+  const handleClear = useCallback(() => {
+    if (timerRef.current !== undefined) {
+      clearTimeout(timerRef.current);
+      timerRef.current = undefined;
+    }
+    setDraft("");
+    emit("");
+    onClear?.();
+  }, [emit, onClear]);
+  const handleSubmit = useCallback(() => {
+    // Submitting a debounced field must search what the user can SEE, not the last value the timer
+    // happened to flush.
+    if (timerRef.current !== undefined) {
+      clearTimeout(timerRef.current);
+      timerRef.current = undefined;
+      emit(displayed);
+    }
+    onSubmit?.();
+  }, [displayed, emit, onSubmit]);
+  const handleFocus = useCallback(() => {
+    setFocused(true);
+    if (showCancel) setCancelVisible(true);
+  }, [showCancel]);
+  const handleCancel = useCallback(() => {
+    inputRef.current?.blur();
+    setCancelVisible(false);
+    handleClear();
+  }, [handleClear]);
+  const colors = resolveSearchBarColors(theme.colors);
+  const a11y = resolveSearchBarAccessibility({
+    placeholder,
+    accessibilityLabel,
+    disabled
+  });
+  const spec = SEARCH_BAR_SIZES[size];
+  const clearVisible = shouldShowClear(displayed, disabled);
+  const showCancelButton = showCancel && cancelVisible;
+  const fieldHitSlop = resolveSearchBarFieldHitSlop(size, {
+    trailingAdjacent: clearVisible || showCancelButton
+  });
+  const clearPress = usePressState(false);
+  const cancelPress = usePressState(false);
+  const overlayStaticStyle = {
+    backgroundColor: colors.pressedFill,
+    borderRadius: theme.radii.full,
+    borderCurve: "continuous"
+  };
+  const floatingFieldStyle = useMemo(() => ({
+    backgroundColor: floatingBackground(theme, "sm"),
+    ...floatingSurfaceStyle(theme, "sm")
+  }), [theme]);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: [searchBarRowStructure(theme), style],
+    children: [/*#__PURE__*/_jsxs(View, {
+      style: [searchBarFieldStructure(theme, {
+        size
+      }), floatingFieldStyle, {
+        borderColor: resolveSearchBarBorderColor(colors, focused)
+      }, disabled && styles.dimmed],
+      children: [focused && !disabled && /*#__PURE__*/_jsx(View, {
+        pointerEvents: "none",
+        testID: "search-bar-focus-ring",
+        style: {
+          position: "absolute",
+          top: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+          left: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+          right: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+          bottom: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+          borderWidth: FOCUS_RING_WIDTH,
+          borderColor: colors.focusBorder,
+          borderRadius: theme.radii.md + FOCUS_RING_GAP + FOCUS_RING_WIDTH,
+          borderCurve: "continuous"
+        }
+      }), loading ? /*#__PURE__*/_jsx(Spinner, {
+        size: "sm",
+        tone: "neutral",
+        testID: testID ? `${testID}-spinner` : undefined
+      }) : /*#__PURE__*/_jsx(Icon, {
+        name: "search",
+        size: spec.iconSize,
+        color: colors.icon,
+        strokeWidth: ICON_STROKE
+      }), /*#__PURE__*/_jsx(TextInput, {
+        ref: inputRef,
+        testID: testID ? `${testID}-input` : undefined,
+        value: displayed,
+        onChangeText: handleChangeText,
+        placeholder: placeholder,
+        placeholderTextColor: colors.placeholder,
+        editable: a11y.editable
+        // The role belongs on the node AT tech actually focuses: the row is a plain layout View
+        // (not `accessible`), so a role there reaches neither the iOS trait nor Android's focus.
+        ,
+        accessibilityRole: "search",
+        accessibilityLabel: a11y.accessibilityLabel,
+        "aria-disabled": a11y["aria-disabled"],
+        autoFocus: autoFocus,
+        autoCapitalize: "none",
+        autoCorrect: false,
+        returnKeyType: "search",
+        onSubmitEditing: handleSubmit,
+        onFocus: handleFocus,
+        onBlur: () => setFocused(false),
+        hitSlop: fieldHitSlop
+        // A search box is not a form field: the OS autofill/keyboard-suggestion strip it would
+        // otherwise raise eats the vertical space the results list sits in (see Input's own note).
+        ,
+        autoComplete: "off",
+        importantForAutofill: "no",
+        style: [{
+          flex: 1,
+          alignSelf: "stretch",
+          fontSize: spec.fontSize,
+          color: colors.text,
+          padding: 0
+        }, theme.fontStyleForWeight(theme.fontWeights.regular), Platform.OS === "web" && styles.webOutlineReset]
+      }), clearVisible && /*#__PURE__*/_jsxs(AnimatedPressable, {
+        testID: testID ? `${testID}-clear` : undefined,
+        accessibilityRole: "button",
+        accessibilityLabel: CLEAR_ACCESSIBILITY_LABEL,
+        onPress: handleClear,
+        onPressIn: clearPress.handlers.onPressIn,
+        onPressOut: clearPress.handlers.onPressOut,
+        onLayout: clearPress.onLayout,
+        hitSlop: resolveSearchBarTrailingHitSlop(size, {
+          outerRight: false
+        }),
+        style: [searchBarClearStructure(theme), {
+          overflow: "hidden"
+        }, clearPress.animatedStyle],
+        children: [/*#__PURE__*/_jsx(Animated.View, {
+          pointerEvents: "none",
+          style: [StyleSheet.absoluteFill, overlayStaticStyle, clearPress.overlayStyle]
+        }), /*#__PURE__*/_jsx(Icon, {
+          name: "x",
+          size: spec.iconSize,
+          color: clearPress.pressed ? colors.onPressedFill : colors.icon,
+          strokeWidth: ICON_STROKE
+        })]
+      })]
+    }), showCancelButton && /*#__PURE__*/_jsxs(AnimatedPressable, {
+      testID: testID ? `${testID}-cancel` : undefined,
+      accessibilityRole: "button",
+      accessibilityLabel: cancelLabel,
+      onPress: handleCancel,
+      onPressIn: cancelPress.handlers.onPressIn,
+      onPressOut: cancelPress.handlers.onPressOut,
+      onLayout: cancelPress.onLayout,
+      hitSlop: resolveSearchBarTrailingHitSlop(size, {
+        outerRight: true
+      }),
+      style: [searchBarCancelStructure(theme, {
+        size
+      }), {
+        overflow: "hidden"
+      }, cancelPress.animatedStyle],
+      children: [/*#__PURE__*/_jsx(Animated.View, {
+        pointerEvents: "none",
+        style: [StyleSheet.absoluteFill, overlayStaticStyle, cancelPress.overlayStyle]
+      }), /*#__PURE__*/_jsx(Text, {
+        numberOfLines: 1,
+        style: [theme.fontStyleForWeight(theme.fontWeights.medium), {
+          fontSize: spec.fontSize,
+          color: cancelPress.pressed ? colors.onPressedFill : colors.cancelLabel
+        }],
+        children: cancelLabel
+      })]
+    })]
+  });
+});
+const styles = StyleSheet.create({
+  // A disabled control is exempt from the contrast minimum (WCAG 1.4.3), so a uniform dim is correct.
+  dimmed: {
+    opacity: 0.5
+  },
+  // RNW renders `TextInput` as a real `<input>`, which paints the browser's own default focus
+  // outline on top of the themed ring above it — a visible double border. Web-only: `outlineWidth`
+  // also drives native TV remote-control focus, so zeroing it globally would break that.
+  webOutlineReset: {
+    outlineStyle: "solid",
+    outlineWidth: 0,
+    borderWidth: 0
+  }
+});
+//# sourceMappingURL=SearchBar.js.map

package/lib/module/modules/search-bar/SearchBar.variants.js

@@ -0,0 +1,208 @@
+"use strict";
+
+/**
+ * SearchBar's style + behaviour resolution — same split as `Input.variants`:
+ *  - STRUCTURE (row/field/affordance sizing, radius, border WIDTH) lives in the `createThemedVariants`
+ *    resolvers below, registered once per (theme, size) — never rebuilt per render.
+ *  - COLOUR is resolved from the theme's ROLE colours by `resolveSearchBarColors` /
+ *    `resolveSearchBarBorderColor`, never a raw ramp and never a hardcoded hex.
+ *  - BEHAVIOUR derivation (`resolveSearchBarAccessibility`, `shouldShowClear`,
+ *    `resolveSearchBarFieldHitSlop`, `resolveSearchBarTrailingHitSlop`) is kept pure so the a11y +
+ *    touch-target contract is unit-testable without rendering React Native.
+ *
+ * Free of React and of `lucide`, 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";
+/** Same floor as Button/Input/ButtonGroup — 44dp (WCAG 2.5.5 / HIG). Duplicated, not imported:
+ * modules stay isolated. */
+export const MIN_TOUCH_TARGET = 44;
+const slopFor = height => Math.max(0, Math.ceil((MIN_TOUCH_TARGET - height) / 2));
+/**
+ * Deliberately the same height/fontSize/iconSize numbers as `INPUT_SIZES` `sm`/`md`, so a SearchBar
+ * and an Input placed in the same form line up exactly.
+ */
+export const SEARCH_BAR_SIZES = {
+  sm: {
+    height: 44,
+    fontSize: 14,
+    iconSize: 16,
+    hitSlop: slopFor(44)
+  },
+  md: {
+    height: 52,
+    fontSize: 16,
+    iconSize: 18,
+    hitSlop: slopFor(52)
+  }
+};
+
+/**
+ * The clear button's own rendered width. Its height comes from `alignSelf: "stretch"` (the field's
+ * full `spec.height`) plus the same vertical `hitSlop` the field uses, but its WIDTH cannot come
+ * from horizontal hitSlop: the clear button sits flush against the `TextInput`, and React Native
+ * never clips hitSlop to a sibling's bounds — it resolves an overlap to whichever renders LATER,
+ * which is the clear button. Horizontal slop there would silently steal taps from the right end of
+ * the query text. So the rendered node clears 44dp on its own and both horizontal slops are 0 —
+ * the same overlap-elimination `ButtonGroup` documents for its internal segment edges.
+ */
+export const CLEAR_BUTTON_WIDTH = MIN_TOUCH_TARGET;
+/**
+ * Maps SearchBar's fixed visual roles onto ROLE colours — never a hardcoded hex. There is no `tone`
+ * or `status` union: a search field reports no validity state and carries no brand identity of its
+ * own, so — like `RadioGroup`/`ButtonGroup` — this is pure indirection, not a union to resolve.
+ *
+ * The field renders NO background fill (transparent, exactly like `Input`'s box), so every colour
+ * here is read against `bg.canvas`.
+ */
+export function resolveSearchBarColors(colors) {
+  return {
+    text: colors.fg.default,
+    placeholder: colors.fg.placeholder,
+    icon: colors.fg.muted,
+    border: colors.border.interactive,
+    focusBorder: colors.border.focus,
+    pressedFill: colors.bg.sunken,
+    onPressedFill: colors.fg.default,
+    cancelLabel: colors.accent.text
+  };
+}
+
+/** The field outline tracks focus, same cue `Select`'s trigger uses for focused-or-open. */
+export function resolveSearchBarBorderColor(colors, focused) {
+  return focused ? colors.focusBorder : colors.border;
+}
+
+/** The clear affordance exists only for a non-empty query, and never on a disabled field. */
+export function shouldShowClear(value, disabled) {
+  return value.length > 0 && !disabled;
+}
+/**
+ * The query field's per-edge touch expansion. Vertical and left expansion are always safe (nothing
+ * interactive sits above, below, or to the left of the field). The RIGHT edge is zeroed whenever a
+ * trailing affordance — the clear button, or the "Cancel" button outside the field — is rendered:
+ * the field's own slop would otherwise overlap it, and React Native resolves overlapping siblings'
+ * hitSlop to whichever renders LATER, so the field would never win that region anyway while
+ * silently enlarging the ambiguous zone. Same per-edge reasoning as `ButtonGroup`'s segments.
+ */
+export function resolveSearchBarFieldHitSlop(size, input) {
+  const slop = SEARCH_BAR_SIZES[size].hitSlop;
+  return {
+    top: slop,
+    bottom: slop,
+    left: slop,
+    right: input.trailingAdjacent ? 0 : slop
+  };
+}
+
+/**
+ * A trailing affordance's per-edge touch expansion. Vertical only for the clear button (it sits
+ * between the query text and the field's own right edge); the cancel button additionally expands
+ * right, since that edge is the whole control's true outer edge and shares with nothing.
+ */
+export function resolveSearchBarTrailingHitSlop(size, input) {
+  const slop = SEARCH_BAR_SIZES[size].hitSlop;
+  return {
+    top: slop,
+    bottom: slop,
+    left: 0,
+    right: input.outerRight ? slop : 0
+  };
+}
+export function resolveSearchBarAccessibility(input) {
+  const disabled = input.disabled === true;
+  return {
+    accessibilityLabel: input.accessibilityLabel ?? input.placeholder,
+    "aria-disabled": disabled,
+    editable: !disabled
+  };
+}
+
+/** The outer row — the field plus, when shown, the "Cancel" button beside it. */
+export const searchBarRowStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    columnGap: theme.space[2]
+  }
+}));
+
+/**
+ * The field box. Structural only — layout, height, padding, radius, border WIDTH; the border COLOUR
+ * is focus-driven and applied inline over this. No background: like `Input`, the field is
+ * transparent so every colour it shows is read against the canvas (which is what `SearchBar.test.ts`
+ * measures).
+ */
+export const searchBarFieldStructure = createThemedVariants(theme => ({
+  base: {
+    flex: 1,
+    flexDirection: "row",
+    alignItems: "center",
+    columnGap: theme.space[2],
+    borderWidth: theme.borderWidths.thin,
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous"
+  },
+  variants: {
+    size: {
+      sm: {
+        height: SEARCH_BAR_SIZES.sm.height,
+        paddingHorizontal: theme.space[3]
+      },
+      md: {
+        height: SEARCH_BAR_SIZES.md.height,
+        paddingHorizontal: theme.space[4]
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+
+/**
+ * The clear button. `alignSelf: "stretch"` fills the field's full height (so the vertical hitSlop
+ * math holds against what actually renders — the same assumption `Input`'s `TextInput` relies on),
+ * and `width` carries the horizontal 44dp floor on its own (see `CLEAR_BUTTON_WIDTH`).
+ */
+export const searchBarClearStructure = createThemedVariants(theme => ({
+  base: {
+    width: CLEAR_BUTTON_WIDTH,
+    alignSelf: "stretch",
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous"
+  }
+}));
+
+/**
+ * The "Cancel" text button. `minWidth` keeps the rendered node at the 44dp floor even for a short
+ * `cancelLabel` — horizontal hitSlop can only expand its outer right edge, so the node itself must
+ * clear the floor, the same fix `ButtonGroup`'s segments use.
+ */
+export const searchBarCancelStructure = createThemedVariants(theme => ({
+  base: {
+    minWidth: MIN_TOUCH_TARGET,
+    alignItems: "center",
+    justifyContent: "center",
+    paddingHorizontal: theme.space[2],
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous"
+  },
+  variants: {
+    size: {
+      sm: {
+        height: SEARCH_BAR_SIZES.sm.height
+      },
+      md: {
+        height: SEARCH_BAR_SIZES.md.height
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+//# sourceMappingURL=SearchBar.variants.js.map

package/lib/module/modules/search-bar/index.js

@@ -0,0 +1,12 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/search-bar`. Value exports and type exports are split
+ * for `verbatimModuleSyntax`. The resolvers (`resolveSearchBarColors`, `SEARCH_BAR_SIZES`, …) stay
+ * internal — a consumer configures a SearchBar through its props, never by importing its internals.
+ * No `icon` prop (the leading/trailing glyphs are fixed), so unlike `input/index.ts` there is no
+ * `IconName` re-export.
+ */
+
+export { SearchBar } from "./SearchBar.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,41 @@
+# section/ — hairline top border + uppercase label + body
+
+`Section` groups an uppercase muted label and ordinary `children` below a hairline top border —
+the settings-section pattern re-declared across consumer apps.
+
+## Files
+
+| File | Role |
+|------|------|
+| `Section.tsx` | The component. Hairline + label + children; `style` last. |
+| `Section.variants.ts` | Pure resolver (`resolveSectionColors`) + themed structural resolver. |
+| `index.ts` | Public surface: `Section`, `SectionProps`. |
+| `__tests__/Section.test.ts` | Pure: WCAG 1.4.3 on the label, colour mapping. |
+| `__tests__/Section.render.test.tsx` | Render: label + children, heading role + level, consumer `style` last. |
+| `__tests__/Section.dom.test.tsx` | Real DOM (`jest.web.config.js`): the label renders a real `<h2>`. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | `string` | — | Required. Uppercase, muted, bold. |
+| `children` | `ReactNode` | — | Body content below the label. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, last. |
+| `testID` | `string` | — | Forwarded to the outermost `View`. |
+
+## Accessibility contract (WCAG)
+
+- **1.3.1 / 2.4.6 — the label is a level-2 heading**: `accessibilityRole="header"`,
+  `aria-level={2}` (`HEADING_LEVEL.section`, `core/heading`) — the same role and level
+  `SectionList`'s own section header carries, nesting under the screen's `AppBar` `<h1>` rather than
+  restarting the outline. `AppBar` + `Section` are what almost every screen is built from, so a
+  label without it leaves rotor heading navigation with nothing to land on.
+- No `accessibilityRole` on the container — like `Card`, a plain grouping box; `children` carry
+  their own semantics.
+- **2.3.3** — n/a: nothing here animates.
+
+## Performance
+
+Wrapped in `React.memo`.
+
+- **Round 2 visual** — radii retarget (`radii.md`/`lg`/`xl`/`full`), `borderCurve: continuous` on md+ corners; floating surfaces wire platform elevation/highlight where applicable.