pixelize-native-library 1.0.6

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

@@ -0,0 +1,87 @@
+# button/ — the reference component
+
+`Button` is the most-repeated shape in the audited apps (81 raw `TouchableOpacity` in crm-mobile,
+**155** in ecommerce-mobile — with three different style-key sets for the *same* add-to-cart button —
+and 195 web usages). It is also the **reference module**: the other 16 components copy its structure.
+
+## Files
+
+| File | Role |
+|------|------|
+| `Button.tsx` | The component. Composition, a11y wiring, press feedback, focus ring, loading/disabled. |
+| `Button.variants.ts` | Pure resolvers (`BUTTON_SIZES`, `resolveButtonTone`, `resolveButtonAccessibility`) + the themed structural variant resolver `buttonStructure`. No React, no lucide. |
+| `index.ts` | Public surface: `Button`, `ButtonProps`, the closed unions, `IconName` (re-exported from `core/icon`). |
+| `__tests__/Button.test.ts` | Pure: WCAG contrast (all brands × modes) + touch target + a11y contract. |
+| `__tests__/Button.render.test.tsx` | Render: variants, press blocking, busy, icon-only name. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `variant` | `solid \| outline \| ghost \| link` | `solid` | Closed union. |
+| `size` | `sm \| md \| lg` | `md` | 32 / 40 / 48 dp; short sizes reach 44 via `hitSlop`. |
+| `tone` | `accent \| neutral \| danger` | `accent` | Closed union — see below. |
+| `label` | `string` | — | Required unless icon-only. |
+| `icon` | `IconName` | — | A NAME, never a `ReactNode`. Deep-imported lucide glyph. |
+| `iconPosition` | `leading \| trailing` | `leading` | |
+| `loading` | `boolean` | `false` | Spinner + `busy`; blocks press. |
+| `disabled` | `boolean` | `false` | Dimmed; blocks press. |
+| `fullWidth` | `boolean` | `false` | `alignSelf: stretch`. |
+| `onPress` | `() => void` | — | Gated off while disabled/loading. |
+| `accessibilityLabel` | `string` | `label` | **Required** when icon-only (type-enforced). |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+
+`ButtonProps` is a discriminated union: a labelled button OR an icon-only button (`label?: never` +
+required `accessibilityLabel`). It is impossible to ship an unlabelled icon button — web's single
+worst a11y trap (its tooltip was the only label on icon-only buttons in 22 files; tooltips don't
+exist on touch).
+
+## Accessibility contract (WCAG)
+
+- **2.5.x target size** — every size reaches ≥ 44 dp; short sizes keep their height and grow the
+  touch area with `hitSlop`. The target grows, the control never shrinks.
+- **1.4.3** — the label uses the DERIVED `accent.onSolid` / `status.*.onSolid` (the label lives with
+  its fill), never a hardcoded white. Measured ≥ 4.5:1 for every tone × variant × brand × mode.
+- **1.4.11** — the outline boundary is `border.interactive` (≥ 3:1), never the decorative
+  `border.default`.
+- **2.4.7 / 2.4.11** — a visible focus ring (`border.focus`) appears on keyboard / external-keyboard /
+  AT focus (`onFocus`/`onBlur`). It sits a small gap OUTSIDE the control, on the canvas, because
+  `border.focus` is the role token proven ≥ 3:1 against the canvas (over a solid fill it could fail).
+- **1.4.1** — `loading` is announced via `accessibilityState.busy`, not conveyed by the spinner alone
+  (the label stays visible; the spinner is hidden from AT).
+- **2.3.3** — the press fade is suppressed when the OS reduce-motion setting is on.
+- `accessibilityRole="button"`, `accessibilityState` for disabled/busy, `accessibilityLabel ?? label`.
+
+## Why `tone` is a union, not a `color`
+
+A `color?: string` prop hands the token system back to the app — the exact regression that put 618
+hardcoded hexes across 171 colours into crm-mobile. `tone` maps to ROLE colours
+(`resolveButtonTone`), so every colour a button can show is guaranteed legible in both modes and can
+never be an off-palette value. `neutral` is monochrome high-emphasis (`fg.default` fill, `bg.canvas`
+label); `accent`/`danger` map to the accent and danger roles.
+
+## Patterns the other 16 must copy
+
+1. **Structure vs colour split.** Static/theme-numeric structure (height, padding, radius, border
+   *width*) → `createThemedVariants` (registered once per theme). Colour → resolved from role tokens
+   per `tone`, applied inline. Press → one animated state-layer overlay; focus → one `border.focus`
+   ring offset onto the canvas (never over the fill, where its ≥ 3:1 isn't guaranteed).
+2. **Pure, testable resolvers** in `*.variants.ts` (no React/lucide) so the WCAG + behaviour contract
+   is unit-tested by measuring real palettes — never eyeballed.
+3. **Closed unions only** (`variant`/`size`/`tone`), `icon` as a NAME, `style: LayoutStyle` last and
+   once, no `{...rest}`, internals never receive consumer style.
+4. **Type-enforced a11y** — make the unlabelled-icon-button state unrepresentable.
+
+## Known gaps
+
+- Render tests need `@testing-library/react-native` + a react-native jest preset (dependency-pending).
+
+## Resolved (were orchestrator flags, now done)
+
+- Icon plumbing hoisted to `src/core/icon/` (deps `lucide-react-native` + `react-native-svg` added
+  as optional peers); `Button.tsx` and `index.ts` import from there.
+- `useReducedMotion` hoisted to `src/core/a11y/`.
+
+## Performance
+
+Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`) — renamed to `ButtonImpl` internally, exported as `Button = memo(ButtonImpl)`. Its one child, `Icon`, only ever receives primitives — nothing to memoize.

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

@@ -0,0 +1,12 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/button`. Value exports and type exports are split for
+ * `verbatimModuleSyntax`. The visual/behaviour resolvers (`resolveButtonTone`, `BUTTON_SIZES`, …)
+ * stay internal — a consumer configures a Button through its props, never by importing its internals.
+ */
+
+export { Button } from "./Button.js";
+
+// Re-exported so a caller can type an `icon` prop without a separate import from `core/icon`.
+//# sourceMappingURL=index.js.map

package/lib/module/modules/button/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Button"],"sourceRoot":"../../../../src","sources":["modules/button/index.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;;AAEA,SAASA,MAAM,QAAQ,aAAU;;AAKjC","ignoreList":[]}

package/lib/module/modules/button-group/ButtonGroup.js

@@ -0,0 +1,106 @@
+"use strict";
+
+/**
+ * ButtonGroup — a segmented single-choice control. Visually connected segments sharing one outer
+ * border and a divider line between adjacent segments, NOT a row of standalone `Button`s — that
+ * connected/segmented treatment is a different structural shape than Button's own pill/rect
+ * variants, so this is a standalone sibling (it never imports `../button`). The border/divider is
+ * drawn PER SEGMENT, not once on the container: every edge that touches the selected segment omits
+ * the stroke (see `resolveButtonGroupSegmentEdgeColors` — WCAG 1.4.11) and relies on the selected
+ * fill's own contrast against the canvas instead.
+ *
+ * One component owns the whole group, same as `RadioGroup`: each segment carries its own
+ * `accessibilityRole="radio"` + `accessibilityState.checked`, and the container carries
+ * `accessibilityRole="radiogroup"` so assistive tech announces the grouping without collapsing the
+ * individually-focusable segments into one.
+ *
+ * No animation anywhere (selection is a conditional fill, not a slide or a fade), so — like
+ * `RadioGroup` — there is nothing here for `useReducedMotion` (WCAG 2.3.3) to gate.
+ */
+
+import { memo } from "react";
+import { Pressable, StyleSheet, Text, View } from "react-native";
+import { useTheme } from "../../theme/index.js";
+import { BUTTON_GROUP_SIZES, buttonGroupSegmentStructure, buttonGroupStructure, resolveButtonGroupColors, resolveButtonGroupSegmentAccessibility, resolveButtonGroupSegmentEdgeColors, resolveButtonGroupSegmentHitSlop } from "./ButtonGroup.variants.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+function ButtonGroupImpl({
+  options,
+  value,
+  onValueChange,
+  size = "md",
+  disabled = false,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const colors = resolveButtonGroupColors(theme.colors);
+  const fontSize = BUTTON_GROUP_SIZES[size].fontSize;
+  const lastIndex = options.length - 1;
+  return /*#__PURE__*/_jsx(View, {
+    testID: testID,
+    accessibilityRole: "radiogroup",
+    style: [buttonGroupStructure(theme), style],
+    children: options.map((option, index) => {
+      const selected = option.value === value;
+      const isFirst = index === 0;
+      const isLast = index === lastIndex;
+      const nextSelected = !isLast && options[index + 1]?.value === value;
+      const a11y = resolveButtonGroupSegmentAccessibility({
+        selected,
+        disabled
+      });
+      const edges = resolveButtonGroupSegmentEdgeColors(colors, {
+        selected,
+        nextSelected
+      });
+      const hitSlop = resolveButtonGroupSegmentHitSlop(size, {
+        isFirst,
+        isLast
+      });
+      return /*#__PURE__*/_jsx(Pressable, {
+        testID: testID ? `${testID}-${option.value}` : undefined,
+        accessibilityRole: a11y.accessibilityRole,
+        accessibilityState: a11y.accessibilityState,
+        accessibilityLabel: option.label,
+        disabled: a11y.disabled,
+        onPress: disabled ? undefined : () => onValueChange(option.value),
+        hitSlop: hitSlop,
+        style: ({
+          pressed
+        }) => [buttonGroupSegmentStructure(theme, {
+          size,
+          first: isFirst ? "on" : "off",
+          last: isLast ? "on" : "off"
+        }), {
+          borderTopColor: edges.top,
+          borderBottomColor: edges.bottom,
+          borderLeftColor: edges.left,
+          borderRightColor: edges.right
+        }, selected ? {
+          backgroundColor: colors.selectedFill
+        } : pressed && !disabled && {
+          backgroundColor: colors.pressedFill
+        }, disabled && styles.dimmed],
+        children: /*#__PURE__*/_jsx(Text, {
+          numberOfLines: 1,
+          style: [theme.fontStyleForWeight(theme.fontWeights.medium), {
+            fontSize,
+            color: selected ? colors.onSelectedFill : colors.label
+          }],
+          children: option.label
+        })
+      }, option.value);
+    })
+  });
+}
+const styles = StyleSheet.create({
+  // A disabled segment is exempt from the contrast minimum (WCAG 1.4.3), so a uniform dim is correct.
+  dimmed: {
+    opacity: 0.5
+  }
+});
+
+// A consumer's screen re-renders far more often than ButtonGroup's own props change — memo is
+// near-free insurance for a design-system primitive (see CLAUDE.md "Performance" section).
+export const ButtonGroup = /*#__PURE__*/memo(ButtonGroupImpl);
+//# sourceMappingURL=ButtonGroup.js.map

package/lib/module/modules/button-group/ButtonGroup.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["memo","Pressable","StyleSheet","Text","View","useTheme","BUTTON_GROUP_SIZES","buttonGroupSegmentStructure","buttonGroupStructure","resolveButtonGroupColors","resolveButtonGroupSegmentAccessibility","resolveButtonGroupSegmentEdgeColors","resolveButtonGroupSegmentHitSlop","jsx","_jsx","ButtonGroupImpl","options","value","onValueChange","size","disabled","style","testID","theme","colors","fontSize","lastIndex","length","accessibilityRole","children","map","option","index","selected","isFirst","isLast","nextSelected","a11y","edges","hitSlop","undefined","accessibilityState","accessibilityLabel","label","onPress","pressed","first","last","borderTopColor","top","borderBottomColor","bottom","borderLeftColor","left","borderRightColor","right","backgroundColor","selectedFill","pressedFill","styles","dimmed","numberOfLines","fontStyleForWeight","fontWeights","medium","color","onSelectedFill","create","opacity","ButtonGroup"],"sourceRoot":"../../../../src","sources":["modules/button-group/ButtonGroup.tsx"],"mappings":"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","ignoreList":[]}

package/lib/module/modules/button-group/ButtonGroup.variants.js

@@ -0,0 +1,220 @@
+"use strict";
+
+/**
+ * ButtonGroup's style + behaviour resolution — pure, React/lucide-free, same split as Button:
+ *  - STRUCTURE (segment height/padding, and — per segment — the top/bottom/left/right border
+ *    WIDTHS and corner radii) lives in the `createThemedVariants` resolvers below, registered once
+ *    per (theme, size) — never rebuilt per render.
+ *  - COLOUR is resolved from the theme's ROLE colours (`resolveButtonGroupColors`), never a raw hex:
+ *    the selected segment is always the accent role, the shared outline/divider is always the
+ *    neutral interactive outline (WCAG 1.4.11), same token used by Button's outline border.
+ *  - `resolveButtonGroupSegmentEdgeColors` decides, PER EDGE OF PER SEGMENT, whether that edge draws
+ *    the outline/divider stroke at all (see the WCAG 1.4.11 note on `resolveButtonGroupColors`).
+ *  - `resolveButtonGroupSegmentHitSlop` decides, PER EDGE OF PER SEGMENT, how far the touch target
+ *    expands (see the touch-target note below `BUTTON_GROUP_SIZES`).
+ *  - `resolveButtonGroupSegmentAccessibility` derives the per-segment a11y surface purely, mirroring
+ *    `resolveRadioRowAccessibility` — this is a single-choice value selector, not a set of tabs.
+ */
+
+import { compositeOver } from "../../theme/tokens/builders/color.js";
+import { createThemedVariants } from "../../core/style/index.js";
+/** Same floor as Button/RadioGroup/Tabs — 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));
+/**
+ * ButtonGroup-specific dimensions. Kept a plain constant — no theme dependency — so the hit-target
+ * test can assert `height + 2·hitSlop ≥ 44` without a provider, same as `BUTTON_SIZES`.
+ */
+export const BUTTON_GROUP_SIZES = {
+  sm: {
+    height: 32,
+    fontSize: 14,
+    hitSlop: slopFor(32)
+  },
+  md: {
+    height: 40,
+    fontSize: 16,
+    hitSlop: slopFor(40)
+  }
+};
+// Fixed-alpha overlay composited onto `bg.sunken`, using `bg.canvas` as the overlay colour — NOT
+// `fg.default` (Skeleton's pulse / Button's press-scrim precedent). `fg.default` was tried first and
+// measured BACKWARDS for this pairing: it exists to read at high contrast against a background, which
+// on every brand × mode puts it in the same luminance neighbourhood `accent.solid` already occupies
+// (dark-on-light in light mode, light-on-dark in dark mode) — compositing it onto `sunken` pulls the
+// result TOWARD `accent.solid`, monotonically lowering contrast at every alpha tried, never raising it.
+// `bg.canvas` is the correct direction because it is already the more extreme background rung in
+// exactly the direction that clears `accent.solid` — lighter than `sunken` in light mode, darker than
+// `sunken` in dark mode — the same relationship this module already relies on for `accent.solid`
+// clearing 3:1 against `bg.canvas` on all 16 brand × mode combinations (see `ButtonGroupColors.outline`
+// above). Nudging `sunken` toward `canvas` moves the boundary pairing toward that already-safe
+// relationship without an `if (dark)` branch. 0x4d / 0xff ≈ 30% — measured (see `ButtonGroup.test.ts`)
+// to clear the worst case (rosewood light, was 2.99:1) to 3.08:1, with every other combination well
+// clear and the unselected label still ≥ 4.5:1 on it (worst case 5.88:1, radiant light).
+const PRESSED_FILL_OVERLAY_ALPHA_HEX = "4d";
+
+/**
+ * Maps the group's fixed visual roles onto ROLE colours — never a hardcoded hex. There is no
+ * per-segment `tone`: the selected fill is always the accent role and the outline is always the
+ * neutral interactive outline, so — like `RadioGroup` — this is pure indirection, not a union to
+ * resolve.
+ */
+export function resolveButtonGroupColors(colors) {
+  return {
+    selectedFill: colors.accent.solid,
+    onSelectedFill: colors.accent.onSolid,
+    label: colors.fg.default,
+    // `bg.sunken` (a pale neutral tint), NOT `bg.hover`: measured, `bg.hover`'s saturated mid-tone
+    // drops the brand-tinted `fg.default` label below 4.5:1 on several brands — same class of bug
+    // Button's "neutral" tone and RadioGroup's pressed row document fixing the same way. Composited
+    // with a small `bg.canvas` overlay (see `PRESSED_FILL_OVERLAY_ALPHA_HEX` above) so it also clears
+    // 3:1 against `selectedFill` — the boundary a segment adjacent to the selected one actually draws
+    // while being pressed.
+    pressedFill: compositeOver(`${colors.bg.canvas}${PRESSED_FILL_OVERLAY_ALPHA_HEX}`, colors.bg.sunken),
+    outline: colors.border.interactive
+  };
+}
+
+/** The value RN treats as "draw nothing" for a border edge — 0 width would also work, but keeping
+ * the WIDTH constant (see `buttonGroupSegmentStructure`) and only swapping the COLOUR avoids a
+ * layout shift when a segment's selection changes. */
+const OMITTED_EDGE = "transparent";
+/**
+ * Per-edge, per-segment outline colour — the WCAG 1.4.11 fix. An edge draws the shared `outline`
+ * colour only when BOTH sides of it are unselected; any edge touching the selected segment is
+ * `transparent` instead, so the selected fill's own contrast against the canvas (or, for the
+ * divider case, against the neighbour's transparent/canvas background) is what marks the boundary.
+ */
+export function resolveButtonGroupSegmentEdgeColors(colors, input) {
+  const own = input.selected ? OMITTED_EDGE : colors.outline;
+  const right = input.selected || input.nextSelected ? OMITTED_EDGE : colors.outline;
+  return {
+    top: own,
+    bottom: own,
+    left: own,
+    right
+  };
+}
+/**
+ * Per-edge, per-segment hitSlop — the touch-target fix. Vertical expansion is symmetric and safe on
+ * every segment (nothing else in the group sits above/below a segment). Horizontal expansion is
+ * granted ONLY on a segment's TRUE outer edge — the group's own left edge on the first segment, its
+ * own right edge on the last — and is exactly 0 on every edge shared with a neighbour.
+ *
+ * Segments in this control render flush against each other (by design — "one connected control",
+ * see `ButtonGroup.tsx`), so a symmetric hitSlop on every segment would expand INTO the adjacent
+ * segment on every internal edge. React Native's own documented hitSlop behaviour never clips to a
+ * sibling's bounds and resolves overlapping siblings' hitSlop to whichever renders LATER (the higher
+ * `options` index), not whichever is visually closer to the tap — so a tap near an internal divider,
+ * still visually inside the earlier segment, would fire the LATER segment's `onValueChange`. Zeroing
+ * the internal edges removes the overlap entirely instead of merely shrinking it.
+ *
+ * Because horizontal hitSlop can no longer safely pad an internal segment's touch width, the ≥44dp
+ * floor for those segments is met by `buttonGroupSegmentStructure`'s own `minWidth`, not by hitSlop.
+ */
+export function resolveButtonGroupSegmentHitSlop(size, position) {
+  const slop = BUTTON_GROUP_SIZES[size].hitSlop;
+  return {
+    top: slop,
+    bottom: slop,
+    left: position.isFirst ? slop : 0,
+    right: position.isLast ? slop : 0
+  };
+}
+/**
+ * Derives one segment's accessibility surface purely, mirroring `resolveRadioRowAccessibility`:
+ * `accessibilityRole="radio"` + `accessibilityState.checked` (NOT `role="tab"`/`.selected` — a tab
+ * switches content panels, which this control does not do; it is the same single-choice value
+ * selector shape `RadioGroup` already uses, just drawn as connected segments instead of rows).
+ */
+export function resolveButtonGroupSegmentAccessibility(input) {
+  return {
+    accessibilityRole: "radio",
+    accessibilityState: {
+      checked: input.selected,
+      disabled: input.disabled
+    },
+    disabled: input.disabled
+  };
+}
+
+/**
+ * The container — a clipping rect only. `overflow: hidden` + `borderRadius` clips every segment's
+ * fill (and the outer segments' square corners) to this single rounded outline, so the selected
+ * segment never shows a corner poking past the shared shape — the visual mechanism that makes this
+ * read as ONE connected control rather than a row of standalone buttons. It carries NO border of its
+ * own: the outer border is drawn by the first/last segments themselves (see
+ * `buttonGroupSegmentStructure`), because only a per-segment border can be selectively omitted where
+ * it touches the selected segment (WCAG 1.4.11) — a single container-wide border is one colour for
+ * its entire perimeter and cannot vary by which segment it runs along.
+ */
+export const buttonGroupStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    borderRadius: theme.radii.base,
+    overflow: "hidden"
+  }
+}));
+
+/**
+ * One segment's layout. `minWidth: MIN_TOUCH_TARGET` is the real ≥44dp touch-target floor for the
+ * WIDTH axis — horizontal hitSlop can no longer safely pad an internal segment (see
+ * `resolveButtonGroupSegmentHitSlop`), so the rendered node itself must never shrink narrower than
+ * 44dp, for a realistic 2–4 option row at either size. `height` is fixed (not a minimum) so the
+ * vertical hitSlop math holds against what actually renders.
+ *
+ * Every segment structurally carries a top, bottom, and right border (thin width) — the right one is
+ * the divider on every segment except the last, where it is instead that segment's own outer right
+ * edge. Only the FIRST segment gets a left border and left-corner radii (the group's own outer left
+ * edge); only the LAST segment gets right-corner radii (matching the container's own `borderRadius`,
+ * so that segment's own border curves rather than being clipped into an L by the container). Border
+ * WIDTHS are structural and constant; COLOURS (drawn vs `transparent`) are resolved per render by
+ * `resolveButtonGroupSegmentEdgeColors` and applied inline over this.
+ */
+export const buttonGroupSegmentStructure = createThemedVariants(theme => ({
+  base: {
+    flex: 1,
+    minWidth: MIN_TOUCH_TARGET,
+    alignItems: "center",
+    justifyContent: "center",
+    borderTopWidth: theme.borderWidths.thin,
+    borderBottomWidth: theme.borderWidths.thin,
+    borderRightWidth: theme.borderWidths.thin
+  },
+  variants: {
+    size: {
+      sm: {
+        height: BUTTON_GROUP_SIZES.sm.height,
+        paddingHorizontal: theme.space[2]
+      },
+      md: {
+        height: BUTTON_GROUP_SIZES.md.height,
+        paddingHorizontal: theme.space[3]
+      }
+    },
+    first: {
+      on: {
+        borderLeftWidth: theme.borderWidths.thin,
+        borderTopLeftRadius: theme.radii.base,
+        borderBottomLeftRadius: theme.radii.base
+      },
+      off: {
+        borderLeftWidth: 0
+      }
+    },
+    last: {
+      on: {
+        borderTopRightRadius: theme.radii.base,
+        borderBottomRightRadius: theme.radii.base
+      },
+      off: {}
+    }
+  },
+  defaultVariants: {
+    size: "md",
+    first: "off",
+    last: "off"
+  }
+}));
+//# sourceMappingURL=ButtonGroup.variants.js.map

package/lib/module/modules/button-group/ButtonGroup.variants.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["compositeOver","createThemedVariants","MIN_TOUCH_TARGET","slopFor","height","Math","max","ceil","BUTTON_GROUP_SIZES","sm","fontSize","hitSlop","md","PRESSED_FILL_OVERLAY_ALPHA_HEX","resolveButtonGroupColors","colors","selectedFill","accent","solid","onSelectedFill","onSolid","label","fg","default","pressedFill","bg","canvas","sunken","outline","border","interactive","OMITTED_EDGE","resolveButtonGroupSegmentEdgeColors","input","own","selected","right","nextSelected","top","bottom","left","resolveButtonGroupSegmentHitSlop","size","position","slop","isFirst","isLast","resolveButtonGroupSegmentAccessibility","accessibilityRole","accessibilityState","checked","disabled","buttonGroupStructure","theme","base","flexDirection","borderRadius","radii","overflow","buttonGroupSegmentStructure","flex","minWidth","alignItems","justifyContent","borderTopWidth","borderWidths","thin","borderBottomWidth","borderRightWidth","variants","paddingHorizontal","space","first","on","borderLeftWidth","borderTopLeftRadius","borderBottomLeftRadius","off","last","borderTopRightRadius","borderBottomRightRadius","defaultVariants"],"sourceRoot":"../../../../src","sources":["modules/button-group/ButtonGroup.variants.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/modules/button-group/MODULE.md

@@ -0,0 +1,129 @@
+# button-group/ — a segmented single-choice control
+
+Visually connected segments sharing one outer border and a divider line between adjacent
+segments — NOT a row of standalone `Button`s. One component owns the whole group, same shape as
+`radio-group/`: each segment carries its own `accessibilityRole="radio"`; the container carries
+`accessibilityRole="radiogroup"` so assistive tech announces the grouping without collapsing the
+individually-focusable segments into one. The border/divider is drawn PER SEGMENT (never once on
+the container) so it can be selectively omitted where it touches the selected segment — see
+**1.4.11** below.
+
+## Files
+
+| File | Role |
+|------|------|
+| `ButtonGroup.tsx` | The component. Segment composition, press wiring, a11y wiring. |
+| `ButtonGroup.variants.ts` | Pure resolvers (`BUTTON_GROUP_SIZES`, `resolveButtonGroupColors`, `resolveButtonGroupSegmentEdgeColors`, `resolveButtonGroupSegmentHitSlop`, `resolveButtonGroupSegmentAccessibility`) + the themed structural resolvers (`buttonGroupStructure`, `buttonGroupSegmentStructure`). No React, no lucide. |
+| `index.ts` | Public surface: `ButtonGroup`, `ButtonGroupProps`, `ButtonGroupOption`, `ButtonGroupSize`. |
+| `__tests__/ButtonGroup.test.ts` | Pure: WCAG contrast (selected label, unselected label resting + pressed, every per-segment boundary pairing — all brands × modes × first/middle/last selected) + touch target (vertical hitSlop math + per-edge hitSlop decision) + a11y contract. |
+| `__tests__/ButtonGroup.render.test.tsx` | Render: selection, press blocking when disabled, per-segment a11y state, the ACTUAL rendered border colours per edge, the ACTUAL rendered hitSlop object, the ACTUAL rendered `minWidth`. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `options` | `{ label: string; value: string }[]` | — | Rendered in order, each `flex: 1` (equal width). |
+| `value` | `string` | — | The selected option's `value`. |
+| `onValueChange` | `(value: string) => void` | — | Fires with the pressed option's `value`; gated off while `disabled`. |
+| `disabled` | `boolean` | `false` | Dims every segment and blocks all presses (whole-group only — no per-option `disabled`). |
+| `size` | `sm \| md` | `md` | 32 / 40 dp fixed segment height (matches Button's `sm`/`md`); both reach 44dp via `hitSlop`. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost (the container `View`), applied exactly once, last. |
+| `testID` | `string` | — | Container's testID; each segment gets `` `${testID}-${option.value}` `` when set. |
+
+No `tone`/`variant` union and no `icon` — this is a single-purpose control, not a closed union of
+appearances. The selected fill is always `accent.solid`; the shared outline/divider is always
+`border.interactive`. That is the whole reason there is no `color`/`tone` prop to resolve.
+
+## Accessibility contract (WCAG)
+
+- **4.1.2** — `accessibilityRole="radio"` per segment, `accessibilityState={ checked, disabled }`
+  (NOT `role="tab"`/`.selected` — a tab switches content panels, which this control does not do; it
+  is the same single-choice value selector shape `RadioGroup` already uses, just drawn as connected
+  segments instead of rows); `accessibilityRole="radiogroup"` on the container.
+- **2.5.x target size** — every segment reaches ≥ 44dp on BOTH axes, but not through one flat
+  `hitSlop`:
+  - **Vertical** — symmetric `hitSlop` on every segment (32dp/40dp visual height + 6/2dp slop = 44dp).
+    Safe on every segment: nothing else in the group sits above/below it. `height` is fixed (not
+    `minHeight`) so the math matches what actually renders — the same class of bug that silently
+    broke Input's 44dp target in Wave 1.
+  - **Horizontal** — segments render flush against each other (no gap — that's what makes this read
+    as one connected control), so a symmetric hitSlop would expand INTO the neighbouring segment.
+    React Native never clips hitSlop to a sibling's bounds and resolves overlapping siblings' hitSlop
+    to whichever renders LATER (the higher `options` index), not whichever is visually closer to the
+    tap — so a flat hitSlop handed a tap near an internal divider, still visually inside the earlier
+    segment, to the WRONG segment. Fixed: `resolveButtonGroupSegmentHitSlop` gives horizontal
+    expansion ONLY to a segment's TRUE outer edge (the group's own left edge on the first segment,
+    its own right edge on the last) and exactly 0 on every edge shared with a neighbour — eliminating
+    the overlap instead of tuning it smaller. Because horizontal hitSlop can no longer pad an internal
+    segment's touch width, `buttonGroupSegmentStructure` gives every segment a structural
+    `minWidth: 44` so the ACTUAL rendered node clears the floor on its own, for a realistic 2–4 option
+    row at either size (verified in `ButtonGroup.render.test.tsx`, not just arithmetic).
+- **1.4.3** — selected label uses the DERIVED `accent.onSolid` (never a hardcoded white), measured
+  ≥ 4.5:1 against `accent.solid`. Unselected label is `fg.default`, measured ≥ 4.5:1 against both the
+  canvas (resting) and `bg.sunken` (pressed) — NOT `bg.hover`, whose saturated mid-tone was measured
+  to drop the brand-tinted label below 4.5:1 on several brands, the same class of bug Button's
+  "neutral" tone and RadioGroup's pressed row document fixing the same way.
+- **1.4.11** — the shared `outline` token (`border.interactive`) clears 3:1 against `bg.canvas` on
+  every brand × mode, but measured against a SELECTED segment's `accent.solid` fill it FAILS 3:1 on
+  15 of 16 brand × mode combinations (some catastrophically: slate light 1.00, emerald light 1.02).
+  Because `value` is required, some segment is always selected — that adjacency is every render, not
+  an edge case, and it previously went unmeasured (the shipped test only checked outline-vs-canvas).
+  Fixed: `resolveButtonGroupSegmentEdgeColors` computes, per edge of per segment, whether that edge
+  touches the selected segment; any edge that does gets `transparent` instead of `outline`, and the
+  boundary there is served instead by the selected fill's own contrast against the canvas —
+  `accent.solid` clears 3:1 against `bg.canvas` on all 16 brand × mode combinations (worst case
+  3.24:1, emerald light) — the same mechanism every other solid-fill component in this library
+  already relies on. `ButtonGroup.test.ts` measures every actually-rendered boundary pairing (not
+  just the easy outline-vs-canvas one) for first/middle/last selected × all 8 brands × both modes.
+- **2.3.3** — n/a: nothing here animates. Selection is a conditional fill (not a slide or a fade), so
+  there is no transition for `useReducedMotion` to gate — same as `RadioGroup`.
+- Disabled segments are exempt from the contrast minimum (WCAG 1.4.3), so the uniform `opacity: 0.5`
+  dim is correct, same as Button/RadioGroup.
+
+## Patterns (copied from Button / RadioGroup)
+
+1. **Structure vs colour split.** Segment height/padding/`minWidth` and every border's *width* are
+   `createThemedVariants` (registered once per `(theme, size)`); the container's `borderRadius` is a
+   theme-scaled constant in the same resolver family. Colour (`selectedFill`, `label`, `pressedFill`,
+   and — per edge, per segment — `outline` vs `transparent`) is resolved by `resolveButtonGroupColors`
+   / `resolveButtonGroupSegmentEdgeColors` from role tokens and applied inline over the structural
+   style.
+2. **One connected control, not N buttons — and the border lives on the segments, not the container.**
+   The container is only a clipping rect (`overflow: 'hidden'` + `borderRadius`, no border of its
+   own): it clips a filled end segment's square corner into the shared rounded shape. Every segment
+   structurally carries its own top/bottom/right border; the right one is the divider on every
+   segment except the last, where it is instead that segment's own outer right edge; only the FIRST
+   segment gets a left border + left-corner radii, only the LAST gets right-corner radii. A single
+   container-wide border could never be selectively omitted per segment (one colour for its whole
+   perimeter), which is exactly why 1.4.11 shipped broken the first time — moving the border onto the
+   segments is what makes the WCAG fix possible at all.
+3. **Pure, testable resolvers** in `ButtonGroup.variants.ts` (no React) so the WCAG + behaviour
+   contract is unit-tested against the real palettes — never eyeballed.
+4. **No `{...rest}`, `style` once on the outermost node**, no icon (per spec), no import from
+   `../button` — the connected/segmented visual treatment is a different structural shape than
+   Button's own pill/rect variants.
+5. **Defence-in-depth press gating** — `onPress` is `undefined` while `disabled`, on top of the
+   `Pressable` `disabled` prop.
+
+## Known gaps
+
+- No visible keyboard-focus ring (Button's `border.focus` ring pattern, WCAG 2.4.7) — left out of v1
+  for the same reason `RadioGroup` left it out: touch is the primary input surface for this control.
+  The same `onFocus`/`onBlur` + `border.focus` pattern from `Button.tsx` would extend cleanly here if
+  a future task needs it for external-keyboard / RN Web use.
+
+### Resolved — the adjacent-pressed-segment boundary (WCAG 1.4.11)
+
+The omitted-divider boundary (fill vs canvas) was originally verified only against the neighbour's
+RESTING background. When the segment immediately next to the selected one is actively pressed, the
+boundary that actually renders there is `selectedFill` vs that neighbour's `pressedFill`, not vs
+canvas — plain `bg.sunken` measured 2.99:1 against `selectedFill` on rosewood light, under the 3:1
+floor. Fixed: `pressedFill` is now `bg.sunken` composited with a small fixed-alpha `bg.canvas` overlay
+(`PRESSED_FILL_OVERLAY_ALPHA_HEX` in `ButtonGroup.variants.ts`) — nudging it toward the same
+already-proven-safe `bg.canvas` relationship `accent.solid` relies on elsewhere in this module, without
+an `if (dark)` branch. Worst case now 3.08:1 (rosewood light); the unselected label stays ≥ 4.5:1 on it
+(worst case 5.88:1). Measured for all 8 brands × both modes in `ButtonGroup.test.ts`.
+
+## Performance
+
+Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`) — renamed to `ButtonGroupImpl` internally, exported as `ButtonGroup = memo(ButtonGroupImpl)`. The `options.map()` hands every per-row prop to host elements (`Pressable`/`Text`/`View`), never a library child component, so no `useCallback`/`useMemo` was needed.

package/lib/module/modules/button-group/index.js

@@ -0,0 +1,11 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/button-group`. Value exports and type exports are split for
+ * `verbatimModuleSyntax`. The visual/behaviour resolvers (`resolveButtonGroupColors`,
+ * `BUTTON_GROUP_SIZES`, …) stay internal — a consumer configures a ButtonGroup through its props,
+ * never by importing its internals.
+ */
+
+export { ButtonGroup } from "./ButtonGroup.js";
+//# sourceMappingURL=index.js.map

package/lib/module/modules/button-group/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["ButtonGroup"],"sourceRoot":"../../../../src","sources":["modules/button-group/index.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,WAAW,QAAQ,kBAAe","ignoreList":[]}

package/lib/module/modules/card/Card.js

@@ -0,0 +1,39 @@
+"use strict";
+
+/**
+ * Card — a plain container for grouping content. No interaction, no text of its own: `children` is
+ * ordinary composition (a consumer places `Text`, `Button`, whatever it needs inside), so there is
+ * nothing here for `accessibilityRole` to announce — the container is intentionally invisible to
+ * assistive tech and its children carry their own semantics, exactly like a plain `View` would.
+ */
+
+import { memo } from "react";
+import { View } from "react-native";
+import { useTheme } from "../../theme/index.js";
+import { cardStructure, resolveCardVariant } from "./Card.variants.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+function CardImpl({
+  variant = "elevated",
+  children,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const variantColors = resolveCardVariant(theme.colors, variant);
+  return /*#__PURE__*/_jsx(View, {
+    testID: testID,
+    style: [cardStructure(theme, {
+      variant
+    }), {
+      backgroundColor: variantColors.background
+    }, variantColors.border !== undefined && {
+      borderColor: variantColors.border
+    }, variant === "elevated" && theme.elevation.md, style],
+    children: children
+  });
+}
+
+// A consumer's screen re-renders far more often than Card's own props change — memo is near-free
+// insurance for a design-system primitive (see CLAUDE.md "Performance" section).
+export const Card = /*#__PURE__*/memo(CardImpl);
+//# sourceMappingURL=Card.js.map

package/lib/module/modules/card/Card.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["memo","View","useTheme","cardStructure","resolveCardVariant","jsx","_jsx","CardImpl","variant","children","style","testID","theme","variantColors","colors","backgroundColor","background","border","undefined","borderColor","elevation","md","Card"],"sourceRoot":"../../../../src","sources":["modules/card/Card.tsx"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;;AAGA,SAASA,IAAI,QAAQ,OAAO;AAC5B,SAASC,IAAI,QAAQ,cAAc;AAGnC,SAASC,QAAQ,QAAQ,sBAAa;AAEtC,SAASC,aAAa,EAAEC,kBAAkB,QAAQ,oBAAiB;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAWpE,SAASC,QAAQA,CAAC;EAAEC,OAAO,GAAG,UAAU;EAAEC,QAAQ;EAAEC,KAAK;EAAEC;AAAkB,CAAC,EAAE;EAC9E,MAAMC,KAAK,GAAGV,QAAQ,CAAC,CAAC;EACxB,MAAMW,aAAa,GAAGT,kBAAkB,CAACQ,KAAK,CAACE,MAAM,EAAEN,OAAO,CAAC;EAE/D,oBACEF,IAAA,CAACL,IAAI;IACHU,MAAM,EAAEA,MAAO;IACfD,KAAK,EAAE,CACLP,aAAa,CAACS,KAAK,EAAE;MAAEJ;IAAQ,CAAC,CAAC,EACjC;MAAEO,eAAe,EAAEF,aAAa,CAACG;IAAW,CAAC,EAC7CH,aAAa,CAACI,MAAM,KAAKC,SAAS,IAAI;MAAEC,WAAW,EAAEN,aAAa,CAACI;IAAO,CAAC,EAC3ET,OAAO,KAAK,UAAU,IAAII,KAAK,CAACQ,SAAS,CAACC,EAAE,EAC5CX,KAAK,CACL;IAAAD,QAAA,EAEDA;EAAQ,CACL,CAAC;AAEX;;AAEA;AACA;AACA,OAAO,MAAMa,IAAI,gBAAGtB,IAAI,CAACO,QAAQ,CAAC","ignoreList":[]}