pixelize-native-library 1.0.7 → 1.2.0

package/lib/module/modules/rich-text-editor/RichTextEditor.variants.js

@@ -0,0 +1,316 @@
+"use strict";
+
+/**
+ * RichTextEditor's style + behaviour resolution — the same split every sibling module holds to:
+ *  - STRUCTURE lives in the `createThemedVariants` resolvers below — static per (brand, mode).
+ *  - COLOUR is resolved from the theme's ROLE colours (`resolveRichTextEditorColors`,
+ *    `resolveRichTextEditorHtmlStyle`), never a raw ramp, never a hardcoded hex.
+ *  - The toolbar/mention behaviour (`RICH_TEXT_EDITOR_TOOLBAR_ITEMS`, `resolveRichTextEditorActiveActions`,
+ *    `filterMentionCandidates`) is pure, so it is unit-tested without mounting the native editor.
+ *
+ * `resolveRichTextEditorHtmlStyle` is the one resolver that talks to `react-native-enriched-html`'s
+ * own `HtmlStyle` shape (types-only import — no runtime dependency on the package from this file).
+ * The mention pill (`mention`) reuses `accent.subtle`/`accent.text`, the one tint pair the role table
+ * already guarantees at 4.5:1 for every brand × mode (see `org-switcher/OrgSwitcher.variants.ts` for
+ * the same reasoning) rather than inventing a new pairing that would need its own contrast proof.
+ *
+ * Free of React and of any native 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";
+
+/** An uploaded image ready to insert. `width`/`height` are the DISPLAY size in dp: the native editor
+ *  reads an `<img>`'s dimensions once at parse time and never re-measures, so a 0 renders 0×0. */
+
+/** Every toolbar action this module renders a button for. `image`/`mention` are triggers, not
+ *  toggles — neither has an entry in `resolveRichTextEditorActiveActions`' output. */
+
+/** Order is the rendered order, left to right in the toolbar's horizontal scroller. */
+export const RICH_TEXT_EDITOR_TOOLBAR_ITEMS = [{
+  action: "bold",
+  icon: "bold",
+  label: "Bold",
+  toggle: true
+}, {
+  action: "italic",
+  icon: "italic",
+  label: "Italic",
+  toggle: true
+}, {
+  action: "underline",
+  icon: "underline",
+  label: "Underline",
+  toggle: true
+}, {
+  action: "strikethrough",
+  icon: "strikethrough",
+  label: "Strikethrough",
+  toggle: true
+}, {
+  action: "inlineCode",
+  icon: "code",
+  label: "Inline code",
+  toggle: true
+}, {
+  action: "h1",
+  icon: "heading-1",
+  label: "Heading 1",
+  toggle: true
+}, {
+  action: "h2",
+  icon: "heading-2",
+  label: "Heading 2",
+  toggle: true
+}, {
+  action: "h3",
+  icon: "heading-3",
+  label: "Heading 3",
+  toggle: true
+}, {
+  action: "blockQuote",
+  icon: "quote",
+  label: "Quote",
+  toggle: true
+}, {
+  action: "codeBlock",
+  icon: "square-code",
+  label: "Code block",
+  toggle: true
+}, {
+  action: "unorderedList",
+  icon: "list",
+  label: "Bullet list",
+  toggle: true
+}, {
+  action: "orderedList",
+  icon: "list-ordered",
+  label: "Numbered list",
+  toggle: true
+}, {
+  action: "checkboxList",
+  icon: "list-checks",
+  label: "Checklist",
+  toggle: true
+}, {
+  action: "link",
+  icon: "link",
+  label: "Insert link",
+  toggle: true
+}, {
+  action: "image",
+  icon: "image",
+  label: "Insert image",
+  toggle: false
+}, {
+  action: "mention",
+  icon: "at-sign",
+  label: "Mention someone",
+  toggle: false
+}];
+
+/**
+ * Maps the native editor's per-keystroke `onChangeState` payload onto the closed action set — this
+ * is what drives toolbar toggle highlighting (active = `variant="solid"`, inactive = `"outline"`).
+ * `image`/`mention` are intentionally absent: both open a picker rather than toggling a style.
+ */
+export function resolveRichTextEditorActiveActions(state) {
+  return {
+    bold: state.bold.isActive,
+    italic: state.italic.isActive,
+    underline: state.underline.isActive,
+    strikethrough: state.strikeThrough.isActive,
+    inlineCode: state.inlineCode.isActive,
+    h1: state.h1.isActive,
+    h2: state.h2.isActive,
+    h3: state.h3.isActive,
+    blockQuote: state.blockQuote.isActive,
+    codeBlock: state.codeBlock.isActive,
+    unorderedList: state.unorderedList.isActive,
+    orderedList: state.orderedList.isActive,
+    checkboxList: state.checkboxList.isActive,
+    link: state.link.isActive
+  };
+}
+/**
+ * Derives the editor's accessible-name surface purely.
+ *
+ * The visible label stays EXPOSED on web: `react-native-enriched-html`'s web build renders a TipTap
+ * `EditorContent` and forwards no accessibility prop to the contenteditable at all (it sets only
+ * `enterkeyhint`), so the field never gets the name there. Hiding the label too would leave a web
+ * screen-reader user with nothing — see MODULE.md's "Known gaps".
+ */
+export function resolveRichTextEditorAccessibility(input) {
+  const name = input.accessibilityLabel ?? input.label;
+  return {
+    accessibilityLabel: name,
+    "aria-hidden": !input.web && name !== undefined ? true : undefined
+  };
+}
+
+/** Web caps the mention dropdown at 8 rows (`mentionSuggestion.ts`) — matched here for parity. */
+export const MENTION_CANDIDATE_LIMIT = 8;
+
+/** Case-insensitive substring match on `label`, capped to `limit`. Empty `query` (just-opened
+ *  dropdown) returns the first `limit` candidates, same as web's `items()` with an empty query. */
+export function filterMentionCandidates(users, query, limit = MENTION_CANDIDATE_LIMIT) {
+  const needle = query.toLowerCase();
+  return users.filter(u => u.label.toLowerCase().includes(needle)).slice(0, limit);
+}
+/** The card owns the boundary: Android's `SimpleViewManager` declares no `border*` prop, so a border
+ *  on the native view's own style is silently dropped there. */
+export function resolveRichTextEditorColors(colors) {
+  return {
+    toolbarBackground: colors.bg.raised,
+    toolbarDivider: colors.border.default,
+    cardBackground: colors.bg.surface,
+    cardBorder: colors.border.interactive,
+    cardBorderFocus: colors.border.focus,
+    text: colors.fg.default,
+    placeholder: colors.fg.muted,
+    cursor: colors.accent.solid,
+    selection: colors.accent.subtle,
+    mentionDropdownBackground: colors.bg.surface,
+    mentionDropdownBorder: colors.border.default,
+    mentionRowBackground: colors.bg.surface,
+    mentionRowPressed: colors.bg.sunken,
+    mentionRowText: colors.fg.default
+  };
+}
+
+/**
+ * The slice of `Theme` this resolver actually reads — deliberately NOT the full `Theme` (which also
+ * carries `palette`, `elevation`, `fontStyleForWeight`, …, none of which a pure test can construct
+ * without mounting `PixelizeProvider`). Every field here is a plain token module import, so
+ * `RichTextEditor.test.ts` builds a real fixture and measures real contrast, the same rigor
+ * `Avatar.test.ts`/`OrgSwitcher.test.ts` apply — without needing a rendered theme to do it.
+ */
+
+/**
+ * Themes the HTML content `react-native-enriched-html` renders inside the editor. Every colour is a
+ * role lookup — never a hex the native lib is handed directly:
+ *  - `code`/`mention` share `accent.subtle` + `accent.text`, the tint pair already proven ≥ 4.5:1 for
+ *    every brand × mode (see the header comment) — the mention pill is the one place this rigor
+ *    matters most, since it is the only "chip" the rendered content shows.
+ *  - `codeblock` uses `bg.sunken` + `fg.default`, the identical pair `Avatar`'s neutral fill already
+ *    measures ≥ 4.5:1 for every brand × mode (`resolveAvatarColors`) — reused rather than re-proven.
+ *  - `blockquote`'s bar is `border.interactive` (≥ 3:1, the same non-text-UI floor every interactive
+ *    outline in this library holds to), its text `fg.muted` (≥ 4.5:1 against every surface it sits on
+ *    — see `roleColors`' `fg.muted` derivation).
+ */
+export function resolveRichTextEditorHtmlStyle(theme) {
+  const c = theme.colors;
+  const heading = fontSize => ({
+    fontSize,
+    bold: true
+  });
+  return {
+    h1: heading(theme.fontSizes["2xl"]),
+    h2: heading(theme.fontSizes.xl),
+    h3: heading(theme.fontSizes.lg),
+    blockquote: {
+      borderColor: c.border.interactive,
+      borderWidth: theme.borderWidths.thick,
+      gapWidth: theme.space[3],
+      color: c.fg.muted
+    },
+    codeblock: {
+      color: c.fg.default,
+      borderRadius: theme.radii.base,
+      backgroundColor: c.bg.sunken
+    },
+    code: {
+      color: c.accent.text,
+      backgroundColor: c.accent.subtle
+    },
+    a: {
+      color: c.accent.text,
+      textDecorationLine: "underline"
+    },
+    mention: {
+      color: c.accent.text,
+      backgroundColor: c.accent.subtle,
+      textDecorationLine: "none"
+    },
+    ol: {
+      gapWidth: theme.space[1],
+      marginLeft: theme.space[4],
+      markerFontWeight: theme.fontWeights.semibold,
+      markerColor: c.fg.muted
+    },
+    ul: {
+      bulletColor: c.fg.muted,
+      bulletSize: 4,
+      marginLeft: theme.space[4],
+      gapWidth: theme.space[1]
+    },
+    ulCheckbox: {
+      boxSize: 18,
+      gapWidth: theme.space[2],
+      marginLeft: theme.space[4],
+      boxColor: c.border.interactive
+    }
+  };
+}
+export const richTextEditorLayout = createThemedVariants(theme => ({
+  base: {
+    rowGap: theme.space[2]
+  }
+}));
+
+/** No `overflow: "hidden"` — the mention dropdown overflows the field by design. */
+export const richTextEditorCardStructure = createThemedVariants(theme => ({
+  base: {
+    borderWidth: theme.borderWidths.thin,
+    borderRadius: theme.radii.base
+  }
+}));
+export const richTextEditorToolbarStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    columnGap: theme.space[2],
+    padding: theme.space[2],
+    borderBottomWidth: theme.borderWidths.thin,
+    borderTopLeftRadius: theme.radii.base - theme.borderWidths.thin,
+    borderTopRightRadius: theme.radii.base - theme.borderWidths.thin
+  }
+}));
+
+/** Applied to the `EnrichedTextInput`'s own `style` prop — `EnrichedInputStyle` is a RESTRICTED
+ *  subset of `TextStyle` (no `flexDirection`/`alignItems`/etc.), so this stays to the keys that
+ *  subset actually allows: padding, `minHeight`, `color`. Border, radius and fill deliberately
+ *  belong to the card instead (see `resolveRichTextEditorColors`). */
+export const richTextEditorFieldStructure = createThemedVariants(theme => ({
+  base: {
+    paddingHorizontal: theme.space[3],
+    paddingVertical: theme.space[2],
+    fontSize: theme.fontSizes.md
+  }
+}));
+
+/** Positioned "below the toolbar": the wrapping field container is the `relative` anchor, so `top: 0`
+ *  here lands the dropdown right under the toolbar, overlaying the editor field beneath it. */
+export const richTextEditorMentionDropdownStructure = createThemedVariants(theme => ({
+  base: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    maxHeight: 200,
+    borderWidth: theme.borderWidths.thin,
+    borderRadius: theme.radii.base,
+    zIndex: theme.zIndices.dropdown,
+    ...theme.elevation.md
+  }
+}));
+export const richTextEditorMentionRowStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    minHeight: 40,
+    paddingHorizontal: theme.space[3],
+    paddingVertical: theme.space[2]
+  }
+}));
+//# sourceMappingURL=RichTextEditor.variants.js.map

package/lib/module/modules/rich-text-editor/index.js

@@ -0,0 +1,10 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/rich-text-editor`. Value exports and type exports are
+ * split for `verbatimModuleSyntax`.
+ */
+
+export { RichTextEditor } from "./RichTextEditor.js";
+export { RICH_TEXT_EDITOR_TOOLBAR_ITEMS } from "./RichTextEditor.variants.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,57 @@
+# screen/ — SafeArea + keyboard + refresh + async-state slots
+
+`Screen` is a screen shell: `SafeAreaView` (via `react-native-safe-area-context`), optional
+`KeyboardAvoidingView`, optional pull-to-refresh, and `state` slots that swap in loading/empty/error
+content instead of `children`.
+
+## Files
+
+| File | Role |
+|------|------|
+| `Screen.tsx` | The component. Composes safe area, keyboard avoidance, refresh, and state slots. |
+| `Screen.variants.ts` | Pure resolver (`resolveScreenColors`) + themed structural resolvers + `ScreenEdge` / `ScreenState` unions. |
+| `index.ts` | Public surface: `Screen`, `ScreenProps`, `ScreenEdge`, `ScreenState`. |
+| `__tests__/Screen.test.ts` | Pure: colour mapping, default edges. |
+| `__tests__/Screen.render.test.tsx` | Render: default loading slot, idle children, consumer `style` last. Mocks `core/a11y` via `jest.requireActual` + override, not a full replacement — the default `LoadingState`/`ErrorState` slots call `useAnnounce`, which a full-replacement mock would drop. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `children` | `ReactNode` | — | Shown when `state="idle"`. |
+| `edges` | `ScreenEdge[]` | `["top"]` | Passed to `SafeAreaView`. |
+| `padded` | `boolean` | `false` | Adds theme padding around content. |
+| `keyboardAvoiding` | `boolean` | `false` | Wraps in `KeyboardAvoidingView`. |
+| `keyboardVerticalOffset` | `number` | `0` | Passed to `KeyboardAvoidingView`. |
+| `refreshing` | `boolean` | `false` | Pull-to-refresh indicator state. |
+| `onRefresh` | `() => void` | — | When set, wraps body in `ScrollView` + `RefreshControl`. |
+| `state` | `"idle" \| "loading" \| "empty" \| "error"` | `"idle"` | Selects which body slot renders. |
+| `loading` | `ReactNode` | `<LoadingState />` | Custom loading slot. |
+| `empty` | `ReactNode` | — | Compose `EmptyState` here. |
+| `error` | `ReactNode` | — | Compose `ErrorState` here. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+| `testID` | `string` | — | Forwarded to the outermost shell node. |
+
+## Known gaps
+
+- **`onRefresh` + list children:** when `onRefresh` is set, the body is wrapped in a `ScrollView`.
+  Screens whose main content is already a `FlatList` should attach `RefreshControl` to that list
+  directly and omit `onRefresh` here.
+
+## Motion
+
+**None, deliberately.** Screen is a layout shell with no surface of its own to animate: a state
+swap (`idle` → `loading` → `error`) is the composed `LoadingState` / `EmptyState` / `ErrorState`
+block's business, and anything Screen could animate itself (a scroll-driven header, a state
+transition it owns) would need a new public prop. Consumers animate their own content.
+
+## Performance
+
+Wrapped in `React.memo`. The active body slot is `useMemo`'d on `state` and slot props. Everything
+else the render path rebuilds is memoized too: the safe-area style array (on `theme`, `padded`,
+background), the root array that appends the consumer `style`, the `KeyboardAvoidingView` style
+array, and the `RefreshControl` element (on `onRefresh`, `refreshing`, accent colour). The inner
+`SafeAreaView` is now built inside the `keyboardAvoiding` branch that uses it, not on every render.
+
+Consumer `style` is still applied exactly once, outermost, last — on the `SafeAreaView` without
+`keyboardAvoiding`, on the `KeyboardAvoidingView` with it.

package/lib/module/modules/screen/Screen.js

@@ -0,0 +1,106 @@
+"use strict";
+
+/**
+ * Screen — a screen shell composing SafeArea, optional KeyboardAvoidingView, optional pull-to-refresh,
+ * and async-state slots that swap in `LoadingState` / consumer-provided empty/error content instead of
+ * `children`. Replaces the per-app `SafeAreaView` + `KeyboardAvoidingView` + `RefreshControl` wiring
+ * that tickets/mobile and crm-mobile each re-declared.
+ *
+ * Requires `react-native-safe-area-context` — Screen's whole purpose is safe-area handling; consumers
+ * using this module are expected to install that optional peer (see MODULE.md).
+ *
+ * No `accessibilityRole` of its own: like `Card`, this is a layout shell — children and composed
+ * state blocks carry their own semantics.
+ */
+
+import { memo, useMemo } from "react";
+import { KeyboardAvoidingView, Platform, RefreshControl, ScrollView, View } from "react-native";
+import { SafeAreaView } from "react-native-safe-area-context";
+import { useTheme, useThemeColors } from "../../theme/hooks.js";
+import { LoadingState } from "../state-block/index.js";
+import { SCREEN_DEFAULT_EDGES, resolveScreenColors, screenPaddedStructure, screenRootStructure, screenScrollContentStructure, screenStateSlotStructure } from "./Screen.variants.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+export const Screen = /*#__PURE__*/memo(function Screen({
+  children,
+  edges = SCREEN_DEFAULT_EDGES,
+  padded = false,
+  keyboardAvoiding = false,
+  keyboardVerticalOffset = 0,
+  refreshing = false,
+  onRefresh,
+  state = "idle",
+  loading,
+  empty,
+  error,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const roleColors = useThemeColors();
+  const screenColors = resolveScreenColors(theme.colors);
+  const body = useMemo(() => {
+    if (state === "loading") {
+      return /*#__PURE__*/_jsx(View, {
+        style: screenStateSlotStructure(theme),
+        testID: testID === undefined ? undefined : `${testID}-loading`,
+        children: loading ?? /*#__PURE__*/_jsx(LoadingState, {})
+      });
+    }
+    if (state === "empty") {
+      return /*#__PURE__*/_jsx(View, {
+        style: screenStateSlotStructure(theme),
+        testID: testID === undefined ? undefined : `${testID}-empty`,
+        children: empty
+      });
+    }
+    if (state === "error") {
+      return /*#__PURE__*/_jsx(View, {
+        style: screenStateSlotStructure(theme),
+        testID: testID === undefined ? undefined : `${testID}-error`,
+        children: error
+      });
+    }
+    return children;
+  }, [children, empty, error, loading, state, testID, theme]);
+  const accent = roleColors.accent.solid;
+  const refreshControl = useMemo(() => onRefresh === undefined ? undefined : /*#__PURE__*/_jsx(RefreshControl, {
+    refreshing: refreshing,
+    onRefresh: onRefresh,
+    colors: [accent],
+    tintColor: accent
+  }), [onRefresh, refreshing, accent]);
+  const inner = refreshControl === undefined ? body : /*#__PURE__*/_jsx(ScrollView, {
+    contentContainerStyle: screenScrollContentStructure(),
+    refreshControl: refreshControl,
+    keyboardShouldPersistTaps: "handled",
+    children: body
+  });
+  const background = screenColors.background;
+  const safeAreaStyle = useMemo(() => [screenRootStructure(theme), padded ? screenPaddedStructure(theme) : undefined, {
+    backgroundColor: background
+  }], [theme, padded, background]);
+  const rootStyle = useMemo(() => [...safeAreaStyle, style], [safeAreaStyle, style]);
+  const keyboardStyle = useMemo(() => [screenRootStructure(theme), {
+    backgroundColor: background
+  }, style], [theme, background, style]);
+  if (!keyboardAvoiding) {
+    return /*#__PURE__*/_jsx(SafeAreaView, {
+      edges: edges,
+      style: rootStyle,
+      testID: testID,
+      children: inner
+    });
+  }
+  return /*#__PURE__*/_jsx(KeyboardAvoidingView, {
+    style: keyboardStyle,
+    behavior: Platform.OS === "ios" ? "padding" : "height",
+    keyboardVerticalOffset: keyboardVerticalOffset,
+    testID: testID,
+    children: /*#__PURE__*/_jsx(SafeAreaView, {
+      edges: edges,
+      style: safeAreaStyle,
+      children: inner
+    })
+  });
+});
+//# sourceMappingURL=Screen.js.map

package/lib/module/modules/screen/Screen.variants.js

@@ -0,0 +1,43 @@
+"use strict";
+
+/**
+ * Screen's style resolution — same split as `Card.variants` / `EmptyState.variants`:
+ *  - STRUCTURE (flex root, padded inset, centred state slots) lives in the themed resolvers below.
+ *  - COLOUR is resolved from the theme's ROLE colours by `resolveScreenColors`, never a raw ramp.
+ *
+ * Free of React and lucide, so the behaviour tests import this directly (mocking only
+ * `react-native`'s `StyleSheet`, as `core/style` and every sibling module's tests do).
+ */
+
+import { createThemedVariants, createVariants } from "../../core/style/index.js";
+export const SCREEN_DEFAULT_EDGES = ["top"];
+export function resolveScreenColors(colors) {
+  return {
+    background: colors.bg.canvas
+  };
+}
+export const screenRootStructure = createThemedVariants(_theme => ({
+  base: {
+    flex: 1
+  }
+}));
+export const screenPaddedStructure = createThemedVariants(theme => ({
+  base: {
+    padding: theme.space[4]
+  }
+}));
+export const screenStateSlotStructure = createThemedVariants(theme => ({
+  base: {
+    flex: 1,
+    alignItems: "center",
+    justifyContent: "center",
+    paddingHorizontal: theme.space[4],
+    paddingVertical: theme.space[8]
+  }
+}));
+export const screenScrollContentStructure = createVariants({
+  base: {
+    flexGrow: 1
+  }
+});
+//# sourceMappingURL=Screen.variants.js.map

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

@@ -0,0 +1,10 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/screen`. Value exports and type exports are split for
+ * `verbatimModuleSyntax`. The resolvers stay internal — a consumer configures a Screen through its
+ * props, never by importing its internals.
+ */
+
+export { Screen } from "./Screen.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,114 @@
+# 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.
+
+## 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.