pixelize-native-library 1.0.7 → 1.2.1

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

@@ -0,0 +1,163 @@
+# pagination/ — page navigation controls in three shapes
+
+`Pagination` renders the controls for a paged list: `numbered` (a windowed strip of page numbers
+with gap markers), `compact` (`"Page 3 of 12"` between two arrows — the shape that actually fits a
+phone), and `loadMore` (one button, for a cursor list that has no page count at all). It owns no
+state and knows nothing about the caller's data source: pages in, `onPageChange(page)` out.
+
+The module exists for `buildPageRange` more than for the pixels. Deciding which page numbers to
+show around the current one — and where a gap marker earns its slot — is fiddly pure arithmetic
+that gets re-derived, and subtly re-broken, in every app that needs a pager.
+
+## Files
+
+| File | Role |
+|------|------|
+| `Pagination.tsx` | The component. Variant branching, control composition, press + a11y wiring. The numbered strip lives in a horizontal `ScrollView` — see "Design decisions". |
+| `Pagination.variants.ts` | Pure resolvers (`buildPageRange`, `clampPage`, `resolvePaginationColors`, `resolvePaginationStep`, `resolvePaginationPage`, `resolvePaginationHitSlop`, `PAGINATION_SIZES`) + the themed structural resolvers. No React, no lucide, no native import. |
+| `index.ts` | Public surface: `Pagination`, `PaginationProps`, `PaginationVariant`, `PaginationSize`, `PageItem`, and — unusually for this repo — `buildPageRange` / `clampPage` (see "Design decisions"). |
+| `__tests__/Pagination.test.ts` | Pure: the page arithmetic (explicit table + a brute-force invariant sweep over pageCount × siblingCount × page, including out-of-bounds), the a11y contract, WCAG contrast (every brand × mode), touch target. |
+| `__tests__/Pagination.render.test.tsx` | Render: what each variant mounts, navigation, boundary/disabled/loading gating, the decorative gap marker, and the ACTUAL rendered fill / `minWidth` / `hitSlop`. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `page` | `number` | — | 1-indexed. Out-of-bounds values clamp — never a crash, never a blank strip. |
+| `pageCount` | `number` | — | `0` renders nothing. Ignored by `loadMore`. |
+| `onPageChange` | `(page: number) => void` | — | Fires with the destination page; never fires for the current page. |
+| `variant` | `numbered \| compact \| loadMore` | `numbered` | `loadMore` needs `onLoadMore` + `hasMore`. |
+| `siblingCount` | `number` | `1` | Pages either side of the current one. `numbered` only. Fractional/negative values normalise. |
+| `showFirstLast` | `boolean` | `false` | Adds jump-to-first/last. `numbered` and `compact`. |
+| `disabled` | `boolean` | `false` | Blocks every press; every control announces `disabled`. |
+| `loading` | `boolean` | `false` | Blocks every press and announces `busy`; in `loadMore` it also shows a spinner. |
+| `onLoadMore` / `hasMore` | `() => void` / `boolean` | — / `false` | `loadMore` only. `hasMore: false` renders nothing once nothing is in flight. |
+| `loadMoreLabel` | `string` | `"Load more"` | |
+| `size` | `sm \| md` | `md` | 32 / 40 dp control height; both reach 44dp via vertical `hitSlop`. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+| `testID` | `string` | — | Seeds `${testID}-{first,previous,next,last,summary,load-more}`, `${testID}-page-${n}`, and a `-focus-ring` child on each focused control. |
+
+No `tone`/`variant` colour union: the current page is always the accent role, so there is nothing
+for a closed union to resolve.
+
+## Accessibility contract (WCAG)
+
+- **4.1.2** — the container is `accessibilityRole="none"` (it carries no information of its own,
+  same as `Divider`); every control is `accessibilityRole="button"`. The current page carries
+  `aria-current="page"` (web) AND `accessibilityState={{ selected: true }}` (native) plus an
+  `accessibilityLabel` of `"Page 3 of 12, current page"`; every other page reads `"Page 4 of 12"`.
+  Steps are labelled `"First page"` / `"Previous page"` / `"Next page"` / `"Last page"`.
+  `aria-current`, not `aria-selected`: this is a set of buttons, not a `listbox`/`tablist`, and
+  `aria-current="page"` is the correct WAI-ARIA signal for "the page you are on" — it also has no
+  React Native equivalent, which is why native rides the separate `accessibilityState` prop instead
+  (see `docs/PLATFORM-A11Y-PROPS.md`).
+- **1.4.13 / 4.1.2 boundaries** — a step at an end carries flat `aria-disabled` (never
+  `accessibilityState={{…}}` — react-native-web discards the object form) and its `onPress` is
+  `undefined`, so a screen-reader user is told they are at an end instead of pressing a silently
+  dead control. The **current page is inert but NOT disabled**: it is selected, not unavailable, and
+  announcing both would misreport the user's own position.
+- **1.4.11 — a disabled control still has to be seen.** This module deliberately does NOT copy
+  Button's `opacity: 0.5` dim, which relies on disabled controls being exempt from the contrast
+  minimum. A greyed arrow is the only thing telling a user they have reached the first/last page, so
+  inert controls swap to `fg.muted` instead — measured ≥ 3:1 (in fact ≥ 4.5:1) against the canvas on
+  every brand × mode.
+- **1.4.3** — the current page's label is the DERIVED `accent.onSolid` on `accent.solid` (never a
+  hardcoded white); an idle page number is `fg.default`, measured on both the canvas and its pressed
+  `bg.sunken` fill — NOT `bg.hover`, whose saturated mid-tone drops a brand-tinted label below
+  4.5:1 (the bug Button's "neutral" tone and Menu's rows document fixing the same way).
+- **1.4.11 — boundaries** — the current-page pill and the load-more outline are each measured ≥ 3:1
+  against the canvas. Unlike `ButtonGroup`'s flush segments, controls here are a `space[1]` gutter
+  apart, so a boundary is always fill-vs-canvas and never fill-vs-neighbour.
+- **2.5.5 / 2.5.8 target size** — every control reaches ≥ 44dp on both axes. Vertical via symmetric
+  `hitSlop` (32/40dp + 6/2dp); horizontal via a structural `minWidth: 44` on the node itself, with
+  horizontal `hitSlop` pinned to exactly 0 — React Native resolves overlapping siblings' `hitSlop`
+  to whichever renders LATER, not whichever is visually closer, so sideways expansion across the
+  gutter would hand a tap to the wrong page (`ButtonGroup` documents the same defect).
+- **2.4.7 focus visible** — every step and page control paints a `border.focus` ring while focused
+  (keyboard, external keyboard, TV remote), gated off whenever the control is disabled/at-limit,
+  which is also `focusable={false}` so a remote cannot land on it (`NumberInput`'s treatment). The
+  ring is drawn **INSET** — the opposite of Button's outside offsets — because the numbered strip's
+  `ScrollView` is exactly one control tall and clips (`overflow: 'scroll'` native,
+  `overflowY: 'hidden'` on react-native-web), so an outside ring would never be painted. The current
+  page rings like any other: it is selected, not disabled.
+- **1.3.1** — the gap marker is `accessible={false}` + `accessibilityElementsHidden` +
+  `importantForAccessibility="no-hide-descendants"`: it navigates nowhere and reads as noise
+  (Button's spinner is hidden the same way).
+- **4.1.3** — the compact summary's page change is announced via `useAnnounce` (`core/a11y`), not
+  `accessibilityLiveRegion` — that prop is Android-only (iOS VoiceOver never hears it) and
+  react-native-web additionally logs a deprecation warning for it. No `accessibilityLiveRegion` is
+  also set on the rendered summary text: `useAnnounce` already announces on both platforms, so
+  keeping both would double-announce on Android (same rule `Input`/`FormField`/`FileUpload` follow).
+- **2.3.3** — the compact summary's fade is skipped and its opacity `setValue`'d whenever
+  `useMotion().enabled` is false (reduced motion or the global kill switch). Page controls and the
+  load-more button use `usePressState` (scale + state-layer overlay), which snaps under reduce motion.
+
+## Page-change motion
+
+`compact` fades its "Page 3 of 12" summary back in when the resolved page changes (`core/motion`,
+`fast` + `decelerate`) — opacity only, native driver, no fade on first mount, stopped on effect
+cleanup and unmount. That is the whole motion budget for this module.
+
+`numbered` deliberately animates **nothing**: it is a row of up to nine controls, and moving or
+fading each one on every page change reads as noise rather than feedback. `loadMore` keeps its
+existing spinner and no transition.
+
+## Patterns copied from Button / ButtonGroup / Menu
+
+1. **Structure vs colour split** — control height/padding/radius via `createThemedVariants`
+   (registered once per `(theme, size)`); colour resolved from `RoleColors` and applied inline.
+2. **Pure, testable resolvers** — the page arithmetic and the a11y derivation are unit-tested
+   against the real palettes and a brute-force page matrix, never eyeballed.
+3. **Per-edge `hitSlop`, not one flat number** — ButtonGroup's fix, applied to a gapped row.
+4. **Defence-in-depth press gating** — `onPress` is `undefined` whenever a control is inert, on top
+   of the `Pressable` `disabled` prop.
+5. **No `{...rest}`, `style` once on the outermost node, closed unions only.**
+
+## Design decisions specific to this module
+
+- **A gap marker must hide at least TWO pages.** The usual implementation's `leftSibling > 2` lets a
+  marker stand in for a single number, which costs the same slot and navigates nowhere. The
+  thresholds here are `> 3` / `< total - 2`, which keeps the strip at a constant `2·siblingCount + 5`
+  slots (so it never reflows as the user pages) while showing the number instead of a useless marker.
+- **The numbered strip scrolls.** Nine controls at the 44dp floor is wider than a phone. Shrinking
+  the controls to fit would break the touch target, so the strip lives in a horizontal `ScrollView`
+  instead — the same "a `.map()` with no scroll container silently loses content" reasoning Menu's
+  rows document. `compact` exists precisely so a narrow screen usually doesn't need this.
+- **`buildPageRange` / `clampPage` are public**, unlike every other module's resolvers. They are
+  pure and dependency-free, and an app drawing its own pager re-deriving them by hand is exactly
+  the failure this module was built to stop.
+- **`loadMore` renders nothing when `hasMore` is false** and no fetch is in flight — the standard
+  end-of-list behaviour. It stays mounted while `loading` so the spinner a press started does not
+  vanish if the caller optimistically flips `hasMore`.
+
+## Known gaps
+
+- **Strings are English-only** (`"Page 3 of 12"`, `"Previous page"`, `"Load more"`). Only
+  `loadMoreLabel` is caller-supplied; a full localisation surface would be a `labels` prop, deferred
+  until a consumer actually ships a second locale.
+- **No page-size ("rows per page") selector** and no total-item count — those are a different
+  control; compose `Select` beside this one.
+- **The load-more button has no focus ring** — only the step and page controls do; `loadMore` is a
+  single button outside the clipping strip and was left on Button's pattern to adopt.
+- The inert treatment is a token swap (`fg.default` → `fg.muted`) whose measured contrast is
+  asserted, but the *perceptual delta between the two* is not — the tests prove a disabled arrow is
+  readable, not that it looks unmistakably disabled on every brand.
+
+## Performance
+
+Wrapped in `React.memo` (repo-wide re-render audit — see root `CLAUDE.md`), exported as
+`Pagination = memo(PaginationImpl)`. Each control is a private, memo'd component in
+`PaginationControls.tsx` fed primitives plus the memoized colour/hitSlop objects — it resolves its
+own a11y surface and builds its own press handler and style callback, so nothing is rebuilt per
+control per render and a page change re-renders only the controls whose state changed. `renderStep`,
+`buildPageRange`'s result and both root style arrays are memoized. Every hook is called above the
+variant early-returns. The strip is a plain `.map()` inside a `ScrollView`, not a `FlatList`: a page window is at
+most `2·siblingCount + 5` items, so `VirtualizedList` setup would be pure cost with no windowing
+benefit (Menu's rows document the same measurement). The themed structural resolvers compile once
+per `(theme, size)` via the `WeakMap` cache and never rebuild per render.
+
+## 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/pagination/Pagination.js

@@ -0,0 +1,236 @@
+"use strict";
+
+/**
+ * Pagination — page navigation controls in three shapes, driven entirely by props: `numbered` (a
+ * windowed strip of page numbers), `compact` ("Page 3 of 12" between two arrows — the shape that
+ * actually fits a phone), and `loadMore` (one button, for a cursor/infinite list that has no page
+ * count at all).
+ *
+ * All the interesting logic is pure and lives in `Pagination.variants.ts` — `buildPageRange` is the
+ * whole reason this module exists, since every app that re-derives it gets an edge case wrong.
+ * This file is the wiring: role colours in, `onPageChange` out. It owns no state and makes no
+ * assumption about where the pages come from.
+ *
+ * The one animated surface is `compact`'s summary, which fades in when the page changes
+ * (`core/motion`). The `numbered` strip is deliberately static — it is a row of controls, and
+ * animating each one on every page change is noise, not feedback.
+ */
+
+import { memo, useCallback, useEffect, useMemo, useRef } from "react";
+import { ActivityIndicator, Animated, Pressable, ScrollView, StyleSheet, Text, View } from "react-native";
+import Reanimated, { FadeInDown, ReduceMotion } from "react-native-reanimated";
+import { useAnnounce } from "../../core/a11y/index.js";
+import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { usePressState } from "../../core/motion/usePressState.js";
+import { useTheme } from "../../theme/hooks.js";
+import { floatingBackground, floatingSurfaceStyle } from "../../theme/platform/index.js";
+import { stateLayerScrim } from "../../theme/platform/stateLayer.native.js";
+import { DEFAULT_LOAD_MORE_LABEL, PAGINATION_SIZES, clampPage, buildPageRange, formatPageLabel, normalizePageCount, paginationLoadMoreStructure, paginationRowStructure, paginationScrollContentStructure, paginationStripRootStructure, resolvePaginationColors, resolvePaginationHitSlop } from "./Pagination.variants.js";
+import { PaginationEllipsis, PaginationPageControl, PaginationStepControl } from "./PaginationControls.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const AnimatedPressable = Reanimated.createAnimatedComponent(Pressable);
+function LoadMoreButton({
+  inert,
+  loading,
+  loadMoreLabel,
+  onLoadMore,
+  theme,
+  colors,
+  hitSlop,
+  size,
+  spec,
+  testID
+}) {
+  const press = usePressState(inert);
+  const overlayStaticStyle = useMemo(() => ({
+    backgroundColor: stateLayerScrim(theme.mode),
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous"
+  }), [theme.mode, theme.radii.md]);
+  return /*#__PURE__*/_jsxs(AnimatedPressable, {
+    testID: testID ? `${testID}-load-more` : undefined,
+    accessibilityRole: "button",
+    accessibilityLabel: loadMoreLabel,
+    "aria-disabled": inert,
+    "aria-busy": loading,
+    disabled: inert,
+    onPress: inert ? undefined : onLoadMore,
+    onPressIn: press.handlers.onPressIn,
+    onPressOut: press.handlers.onPressOut,
+    onLayout: press.onLayout,
+    hitSlop: hitSlop,
+    style: [paginationLoadMoreStructure(theme, {
+      size
+    }), {
+      borderColor: colors.border,
+      overflow: "hidden"
+    }, press.animatedStyle],
+    children: [/*#__PURE__*/_jsx(Reanimated.View, {
+      pointerEvents: "none",
+      style: [StyleSheet.absoluteFill, overlayStaticStyle, press.overlayStyle]
+    }), loading && /*#__PURE__*/_jsx(ActivityIndicator, {
+      size: "small",
+      color: colors.inactiveLabel,
+      accessibilityElementsHidden: true,
+      importantForAccessibility: "no-hide-descendants"
+    }), /*#__PURE__*/_jsx(Text, {
+      numberOfLines: 1,
+      style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+        fontSize: spec.fontSize,
+        color: inert ? colors.inactiveLabel : colors.label
+      }],
+      children: loadMoreLabel
+    })]
+  });
+}
+function PaginationImpl({
+  page,
+  pageCount,
+  onPageChange,
+  variant = "numbered",
+  siblingCount = 1,
+  showFirstLast = false,
+  disabled = false,
+  loading = false,
+  onLoadMore,
+  hasMore = false,
+  loadMoreLabel = DEFAULT_LOAD_MORE_LABEL,
+  size = "md",
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const motion = useMotion();
+  const colors = useMemo(() => resolvePaginationColors(theme.colors), [theme.colors]);
+  const spec = PAGINATION_SIZES[size];
+  const hitSlop = useMemo(() => resolvePaginationHitSlop(size), [size]);
+  const total = normalizePageCount(pageCount);
+  const current = clampPage(page, total);
+  const blocked = disabled || loading;
+  const summaryOpacity = useAnimatedValue(1);
+  const running = useRef(null);
+  const settled = useRef(false);
+
+  // Only the compact variant renders a summary line; the numbered strip announces through the
+  // pressed control itself, so announcing here too would double-speak.
+  useAnnounce(variant === "compact" ? formatPageLabel(current, total) : undefined);
+  useEffect(() => {
+    running.current?.stop();
+    // The first render is not a page change — only a later one is worth acknowledging.
+    if (!motion.enabled || !settled.current) {
+      settled.current = true;
+      summaryOpacity.setValue(1);
+      return;
+    }
+    summaryOpacity.setValue(0);
+    running.current = motion.timing(summaryOpacity, 1, {
+      duration: "fast",
+      easing: "decelerate"
+    });
+    running.current.start();
+    return () => running.current?.stop();
+  }, [current, motion, summaryOpacity]);
+  useEffect(() => () => running.current?.stop(), []);
+  const items = useMemo(() => variant === "numbered" ? buildPageRange(current, total, siblingCount) : [], [variant, current, total, siblingCount]);
+  const renderStep = useCallback((kind, icon) => /*#__PURE__*/_jsx(PaginationStepControl, {
+    kind: kind,
+    icon: icon,
+    page: current,
+    pageCount: total,
+    disabled: disabled,
+    loading: loading,
+    size: size,
+    iconSize: spec.iconSize,
+    theme: theme,
+    colors: colors,
+    hitSlop: hitSlop,
+    onPageChange: onPageChange,
+    testID: testID ? `${testID}-${kind}` : undefined
+  }, kind), [current, total, disabled, loading, size, spec.iconSize, theme, colors, hitSlop, onPageChange, testID]);
+  const summaryStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.medium), {
+    fontSize: spec.fontSize,
+    color: blocked ? colors.inactiveLabel : colors.label,
+    paddingHorizontal: theme.space[2],
+    opacity: summaryOpacity
+  }], [theme, spec.fontSize, blocked, colors, summaryOpacity]);
+  const rowStyle = useMemo(() => [paginationRowStructure(theme), style], [theme, style]);
+  const stripStyle = useMemo(() => [paginationStripRootStructure(), {
+    backgroundColor: floatingBackground(theme, "sm"),
+    ...floatingSurfaceStyle(theme, "sm")
+  }, style], [theme, style]);
+  if (variant === "loadMore") {
+    if (!hasMore && !loading) return null;
+    const inert = blocked || onLoadMore === undefined;
+    return /*#__PURE__*/_jsx(View, {
+      testID: testID,
+      accessibilityRole: "none",
+      style: rowStyle,
+      children: /*#__PURE__*/_jsx(LoadMoreButton, {
+        inert: inert,
+        loading: loading,
+        loadMoreLabel: loadMoreLabel,
+        onLoadMore: onLoadMore,
+        theme: theme,
+        colors: colors,
+        hitSlop: hitSlop,
+        size: size,
+        spec: spec,
+        testID: testID
+      })
+    });
+  }
+  if (total < 1) return null;
+  if (variant === "compact") {
+    return /*#__PURE__*/_jsxs(View, {
+      testID: testID,
+      accessibilityRole: "none",
+      style: rowStyle,
+      children: [showFirstLast && renderStep("first", "chevrons-left"), renderStep("previous", "chevron-left"), /*#__PURE__*/_jsx(Animated.Text, {
+        testID: testID ? `${testID}-summary` : undefined
+        // No `accessibilityLiveRegion` (deliberate): it's Android-only, and `useAnnounce` above
+        // already announces on both platforms — keeping both would double-announce on Android.
+        ,
+        numberOfLines: 1,
+        style: summaryStyle,
+        children: formatPageLabel(current, total)
+      }), renderStep("next", "chevron-right"), showFirstLast && renderStep("last", "chevrons-right")]
+    });
+  }
+  return /*#__PURE__*/_jsx(Reanimated.View, {
+    entering: FadeInDown.springify().reduceMotion(ReduceMotion.System),
+    testID: testID,
+    accessibilityRole: "none",
+    style: stripStyle,
+    children: /*#__PURE__*/_jsxs(ScrollView, {
+      horizontal: true,
+      bounces: false,
+      showsHorizontalScrollIndicator: false,
+      contentContainerStyle: paginationScrollContentStructure(theme),
+      children: [showFirstLast && renderStep("first", "chevrons-left"), renderStep("previous", "chevron-left"), items.map((item, index) => item === "ellipsis" ? /*#__PURE__*/_jsx(PaginationEllipsis, {
+        size: size,
+        fontSize: spec.fontSize,
+        theme: theme,
+        color: colors.inactiveLabel
+      }, `ellipsis-${index}`) : /*#__PURE__*/_jsx(PaginationPageControl, {
+        item: item,
+        page: current,
+        pageCount: total,
+        disabled: disabled,
+        loading: loading,
+        blocked: blocked,
+        size: size,
+        fontSize: spec.fontSize,
+        theme: theme,
+        colors: colors,
+        hitSlop: hitSlop,
+        onPageChange: onPageChange,
+        testID: testID ? `${testID}-page-${item}` : undefined
+      }, `page-${item}`)), renderStep("next", "chevron-right"), showFirstLast && renderStep("last", "chevrons-right")]
+    })
+  });
+}
+
+// A consumer's screen re-renders far more often than Pagination's own props change — memo is
+// near-free insurance for a design-system primitive (see CLAUDE.md "Performance" section).
+export const Pagination = /*#__PURE__*/memo(PaginationImpl);
+//# sourceMappingURL=Pagination.js.map