pixelize-native-library 1.0.7 → 1.2.0

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

@@ -0,0 +1,256 @@
+"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, useRef, useState } from "react";
+import { Platform, Pressable, StyleSheet, Text, TextInput, View } from "react-native";
+import { Icon } from "../../core/icon/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";
+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
+  });
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: [searchBarRowStructure(theme), style],
+    children: [/*#__PURE__*/_jsxs(View, {
+      style: [searchBarFieldStructure(theme, {
+        size
+      }), {
+        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.base + FOCUS_RING_GAP + FOCUS_RING_WIDTH
+        }
+      }), 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__*/_jsx(Pressable, {
+        testID: testID ? `${testID}-clear` : undefined,
+        accessibilityRole: "button",
+        accessibilityLabel: CLEAR_ACCESSIBILITY_LABEL,
+        onPress: handleClear,
+        hitSlop: resolveSearchBarTrailingHitSlop(size, {
+          outerRight: false
+        }),
+        style: ({
+          pressed
+        }) => [searchBarClearStructure(theme), pressed && {
+          backgroundColor: colors.pressedFill
+        }],
+        children: ({
+          pressed
+        }) => /*#__PURE__*/_jsx(Icon, {
+          name: "x",
+          size: spec.iconSize,
+          color: pressed ? colors.onPressedFill : colors.icon,
+          strokeWidth: ICON_STROKE
+        })
+      })]
+    }), showCancelButton && /*#__PURE__*/_jsx(Pressable, {
+      testID: testID ? `${testID}-cancel` : undefined,
+      accessibilityRole: "button",
+      accessibilityLabel: cancelLabel,
+      onPress: handleCancel,
+      hitSlop: resolveSearchBarTrailingHitSlop(size, {
+        outerRight: true
+      }),
+      style: ({
+        pressed
+      }) => [searchBarCancelStructure(theme, {
+        size
+      }), pressed && {
+        backgroundColor: colors.pressedFill
+      }],
+      children: ({
+        pressed
+      }) => /*#__PURE__*/_jsx(Text, {
+        numberOfLines: 1,
+        style: [theme.fontStyleForWeight(theme.fontWeights.medium), {
+          fontSize: spec.fontSize,
+          color: 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,205 @@
+"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: 32,
+    fontSize: 14,
+    iconSize: 16,
+    hitSlop: slopFor(32)
+  },
+  md: {
+    height: 40,
+    fontSize: 16,
+    iconSize: 18,
+    hitSlop: slopFor(40)
+  }
+};
+
+/**
+ * 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.muted,
+    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.base
+  },
+  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.base
+  }
+}));
+
+/**
+ * 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.base
+  },
+  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,39 @@
+# 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`.

package/lib/module/modules/section/Section.js

@@ -0,0 +1,42 @@
+"use strict";
+
+/**
+ * Section — a labelled content block with a hairline top border, an uppercase muted label, and
+ * ordinary `children` composition below.
+ *
+ * The label is the section's heading, so it carries `accessibilityRole="header"` at level 2 (WCAG
+ * 1.3.1 / 2.4.6) — the same role and level `SectionList`'s own section header renders with.
+ */
+
+import { memo, useMemo } from "react";
+import { View } from "react-native";
+import { HEADING_LEVEL, HeadingText } from "../../core/heading/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { resolveSectionColors, sectionContainerStructure, sectionLabelStructure } from "./Section.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export const Section = /*#__PURE__*/memo(function Section({
+  label,
+  children,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const colors = useMemo(() => resolveSectionColors(theme.colors), [theme.colors]);
+  const rootStyle = useMemo(() => [sectionContainerStructure(theme), {
+    borderTopColor: colors.border
+  }, style], [theme, colors, style]);
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.bold), sectionLabelStructure(theme), {
+    color: colors.label
+  }], [theme, colors]);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: rootStyle,
+    children: [/*#__PURE__*/_jsx(HeadingText, {
+      accessibilityRole: "header",
+      "aria-level": HEADING_LEVEL.section,
+      style: labelStyle,
+      children: label
+    }), children]
+  });
+});
+//# sourceMappingURL=Section.js.map

package/lib/module/modules/section/Section.variants.js

@@ -0,0 +1,29 @@
+"use strict";
+
+/**
+ * Section's style resolution — same split as `Divider.variants` / `Card.variants`.
+ */
+
+import { createThemedTextVariants, createThemedVariants } from "../../core/style/index.js";
+export function resolveSectionColors(colors) {
+  return {
+    border: colors.border.default,
+    label: colors.fg.muted
+  };
+}
+export const sectionContainerStructure = createThemedVariants(theme => ({
+  base: {
+    borderTopWidth: theme.borderWidths.thin,
+    paddingTop: theme.space[2],
+    paddingBottom: theme.space[2],
+    rowGap: theme.space[2]
+  }
+}));
+export const sectionLabelStructure = createThemedTextVariants(theme => ({
+  base: {
+    fontSize: theme.fontSizes.xs,
+    letterSpacing: 0.6,
+    textTransform: "uppercase"
+  }
+}));
+//# sourceMappingURL=Section.variants.js.map

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

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

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

@@ -0,0 +1,18 @@
+# section-list/
+
+Virtualized sectioned list via `core/list/VirtualSectionList`.
+
+## Accessibility
+
+- **1.3.1 / 2.4.6** — a section header carries `accessibilityRole="header"` and `aria-level={2}`
+  (`HEADING_LEVEL.section`, `core/heading`) — the level `Section`'s own label and `EmptyState`'s
+  title also use, nesting under the screen's `AppBar` `<h1>`. Without a level, `react-native-web`
+  still renders `<h1>` by default, but every other level-2 heading on the same screen would collapse
+  into the same tag as this one.
+
+## Tests
+
+| Test | Covers |
+|------|--------|
+| `__tests__/SectionList.render.test.tsx` | Render: section header + item, heading role + level. |
+| `__tests__/SectionList.dom.test.tsx` | Real DOM (`jest.web.config.js`): the header renders a real `<h2>`. |

package/lib/module/modules/section-list/SectionList.js

@@ -0,0 +1,64 @@
+"use strict";
+
+/**
+ * SectionList — virtualized sections built on `core/list` VirtualSectionList.
+ */
+
+import { memo, useCallback, useMemo } from "react";
+import { View } from "react-native";
+import { HEADING_LEVEL, HeadingText } from "../../core/heading/index.js";
+import { VirtualSectionList } from "../../core/list/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { sectionListHeaderStructure } from "./SectionList.variants.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+function SectionListInner({
+  sections,
+  renderItem,
+  keyExtractor,
+  itemHeight,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const headerStyle = useMemo(() => [sectionListHeaderStructure(theme), theme.fontStyleForWeight(theme.fontWeights.semibold), {
+    fontSize: theme.fontSizes.sm,
+    color: theme.colors.fg.muted,
+    textTransform: "uppercase"
+  }], [theme]);
+
+  // Section identity is the caller's object, so an index lookup stays O(1) per rendered row.
+  const sectionIndices = useMemo(() => new Map(sections.map((section, index) => [section, index])), [sections]);
+  const renderSectionHeader = useCallback(section => /*#__PURE__*/_jsx(SectionHeader, {
+    title: section.title,
+    style: headerStyle
+  }), [headerStyle]);
+  const renderVirtualItem = useCallback(info => renderItem({
+    item: info.item,
+    sectionIndex: sectionIndices.get(info.section) ?? -1,
+    index: info.index
+  }), [renderItem, sectionIndices]);
+  return /*#__PURE__*/_jsx(View, {
+    testID: testID,
+    style: style,
+    children: /*#__PURE__*/_jsx(VirtualSectionList, {
+      sections: sections,
+      renderSectionHeader: renderSectionHeader,
+      renderItem: renderVirtualItem,
+      keyExtractor: keyExtractor,
+      itemHeight: itemHeight
+    })
+  });
+}
+const SectionHeader = /*#__PURE__*/memo(function SectionHeader({
+  title,
+  style
+}) {
+  return /*#__PURE__*/_jsx(HeadingText, {
+    accessibilityRole: "header",
+    "aria-level": HEADING_LEVEL.section,
+    style: style,
+    children: title
+  });
+});
+export const SectionList = /*#__PURE__*/memo(SectionListInner);
+//# sourceMappingURL=SectionList.js.map