pixelize-native-library 1.0.7 → 1.2.1

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

@@ -0,0 +1,158 @@
+# chip/ — an interactive, selectable/removable pill
+
+`Chip` is the touchable counterpart to `../badge`: **`Badge` is a non-interactive `View`**, its own
+file-level comment says so explicitly ("no press, focus, loading, or disabled state — not
+interactive"). `Chip` is a `Pressable` — press to select/toggle (`onPress`), and optionally press a
+SEPARATE trailing "x" to remove it (`onRemove`), each with its own accessible name and its own 44dp
+touch target. Use `Badge` for a passive status/count label; use `Chip` for filter chips, selectable
+tags, and removable tokens.
+
+**Not the same chip as `../filter-sheet`'s `FilterChip`/`QuickChip`** — those are narrower shapes
+built for that module's own sheet (`FilterChip`'s `onRemove` is its ENTIRE interactivity switch, no
+independent select; `QuickChip` is select-only, unexported). `Chip` generalises both — independent
+`onPress` AND `onRemove` on the same chip — for every other consumer.
+
+## Files
+
+| File | Role |
+|------|------|
+| `Chip.tsx` | The component. Colour/structure resolution, press-feedback branching (filled vs non-filled), the leading `avatarUri`/`icon` precedence, and the sibling remove `Pressable` (plus the wrapper `View` a removable chip needs). |
+| `ChipGroup.tsx` | Public. A thin layout wrapper — wrap-onto-lines or horizontal-scroll a row of `Chip`s. Owns no chip state. |
+| `Chip.variants.ts` | Pure resolvers (`resolveChipColors`, `isChipFilled`, `resolveChipPressedBackground`, `resolveChipAccessibility`, `resolveChipGroupGap`) + the themed structural resolvers (`chipStructure`, `chipRemoveSlotStructure`, `chipRemoveTouchStructure`). No React, no lucide. |
+| `index.ts` | Public surface: `Chip`, `ChipProps`, `ChipGroup`, `ChipGroupProps`, the closed unions, `IconName`. |
+| `__tests__/Chip.test.ts` | Pure: WCAG contrast (6 tones × 3 variants × selected, all brands × modes), touch target, the a11y contract, `selected` overriding `variant`. |
+| `__tests__/Chip.render.test.tsx` | Render: press wiring, the remove affordance never firing `onPress`, the remove button being a SIBLING of the chip's press target (WCAG 4.1.2), `selected` a11y, disabled gating, `avatarUri`-over-`icon`, `ChipGroup` wrap/scrollable. |
+
+## Props
+
+### `ChipProps`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | `string` | — | Required. A chip is never icon-only. |
+| `variant` | `solid \| outline \| subtle` | `subtle` | |
+| `tone` | `accent \| neutral \| success \| warning \| danger \| info \| custom` | `neutral` | |
+| `customColors` | `{ bg, fg }` | — | Required when `tone="custom"`. Same contract as `Badge`. |
+| `size` | `sm \| md` | `md` | 28 / 32 dp visual height; both reach 44dp via `hitSlop`. |
+| `selected` | `boolean` | `false` | Renders the filled/accented look regardless of `variant`. Only exposed as toggle state (`aria-pressed` + `accessibilityState.selected`) when the caller passes it — see Accessibility contract. |
+| `onPress` | `() => void` | — | |
+| `onRemove` | `() => void` | — | Provided → a trailing "x" `Pressable` rendered as a SIBLING of the chip's press target (never inside it — see Accessibility contract), with its own `accessibilityLabel` from the shared `removeAccessibilityLabel()` (`core/a11y/labels`, `"Remove <label>"`) and its own 44dp hit target. Pressing it never fires `onPress`, and vice versa. Omitted → no remove affordance renders, and the chip's `Pressable` is the root node. |
+| `icon` | `IconName` | — | Leading glyph. Ignored when `avatarUri` is also given. |
+| `avatarUri` | `string` | — | Leading circular image (`core/media`'s `MediaImage`: `expo-image` when the app injected it, RN `Image` otherwise). Wins over `icon` when both are passed. |
+| `disabled` | `boolean` | `false` | Blocks both `onPress` and `onRemove`; uniform `opacity: 0.5` dim. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last — on the chip's `Pressable`, or on the wrapper `View` when `onRemove` makes one necessary. |
+| `testID` | `string` | — | On the chip's own press target (not the wrapper). Also seeds `${testID}-remove` and `${testID}-avatar`. |
+
+### `ChipGroupProps`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `children` | `ReactNode` | — | |
+| `wrap` | `boolean` | `true` | Ignored when `scrollable` is true. |
+| `gap` | `sm \| md` | `md` | `theme.space[1]` / `theme.space[2]`. |
+| `scrollable` | `boolean` | `false` | Horizontal `ScrollView`, no wrap — for a filter rail. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+| `testID` | `string` | — | |
+
+## Accessibility contract (WCAG)
+
+- **2.5.5 / 2.5.8 target size** — every chip size and the remove glyph reach ≥ 44dp via `hitSlop`
+  (`Chip.test.ts`); the remove `Pressable` is a genuinely separate node, not a sub-region of the
+  chip's own hit area, so the two touch targets don't require disambiguating a shared press. The
+  wrapper a removable chip renders repeats the chip's `hitSlop`: a touch outside a view's own hit
+  region is never dispatched into its children, so an un-slopped wrapper would silently clip the
+  chip's 44dp target back to its 32dp pill (`Chip.render.test.tsx`).
+- **4.1.2** — the chip is `accessibilityRole="button"` with flat `aria-disabled` (never
+  `accessibilityState={{…}}` — react-native-web discards the object form, see
+  `docs/PLATFORM-A11Y-PROPS.md`). `selected` is exposed ONLY when the caller passes the prop
+  (`resolveChipAccessibility`) — a plain removable-token chip that never supplies `selected` has no
+  toggle concept and shouldn't announce "not selected"; a controlled filter chip (even
+  `selected={false}`) gets full toggle semantics, as BOTH `aria-pressed` (web) AND
+  `accessibilityState={{ selected }}` (native — `aria-pressed` has no RN equivalent, and RNW discards
+  the object, so the two never collide). The remove glyph is its OWN `accessibilityRole="button"`
+  node with its own label — never folded into the chip's label — and it is a **sibling** of the
+  chip's `Pressable`, never a descendant, so a screen reader can actually reach it (see the design
+  decision below). Its label uses the library's one canonical "remove" phrasing
+  (`removeAccessibilityLabel`, `core/a11y/labels`) — `filter-sheet` and `file-upload` use the same
+  import (WCAG 3.2.4 Consistent Identification).
+- **1.4.3** — the label clears ≥ 4.5:1 against its own fill for every (tone × variant × selected)
+  combination, all 8 brands × both modes (`Chip.test.ts`). `outline` (transparent background) is
+  measured against `bg.canvas` — the same backdrop Select's field label and Badge's border are
+  measured against, since `accent.text`/`status.*.text` are only proven ≥ 4.5:1 against
+  `backgroundColor.main`/`subtle` by `roleColors()` itself, not against `bg.surface`. `subtle` — the
+  tinted-fill variant — is measured with the same rigor as every other cell; it is the combination
+  most likely to fail, so it is never skipped.
+- **1.4.11** — `outline`'s border clears ≥ 3:1 against the canvas. The leading icon and remove glyph
+  reuse the label's exact `text` colour (no separate lookup), so once the label clears the stricter
+  4.5:1 text minimum, both glyphs clear their looser 3:1 non-text minimum for free — the same
+  reasoning Menu's row icon and Select's active-row check glyph rely on.
+- Disabled is exempt from the contrast minimum (WCAG 1.4.3), signalled by a uniform `opacity: 0.5`
+  dim — same precedent Button/Select/Badge use.
+
+## Patterns copied from the reference modules
+
+1. **Structure vs colour split** (Button) — sizing/padding/radius/border WIDTH via
+   `createThemedVariants`; colour resolved from `RoleColors` per `(tone, variant, selected)`, applied
+   inline.
+2. **Pure, testable resolvers** (Button/Select) in `Chip.variants.ts` — the WCAG + a11y contract is
+   unit-tested against real palettes, never eyeballed.
+3. **Tone resolution + the `StatusColors.border` substitution** (Badge) — the four status tones read
+   `.text` for a boundary colour, never the decorative, contrast-failing `.border` field.
+4. **Pressed-row background** (Menu's `resolveMenuRowPressedBackground`) — non-filled chips
+   (`outline`/`subtle`, unselected) swap their whole background to `bg.sunken` on press, exactly
+   Menu's own row precedent, measured the same way (`Chip.test.ts`).
+5. **44dp via `hitSlop`, small visual size stays small** (Button/Select) — applied to both the chip
+   itself and, separately, the remove glyph.
+
+## Design decisions specific to this module
+
+- **A filled chip (`variant="solid"` or `selected`) dims on press instead of swapping to
+  `bg.sunken`.** Replacing a coloured fill with a flat neutral tint on every press would erase the
+  tone/selection cue for the moment a finger is down — the same "disabled is a uniform dim, exempt
+  from the contrast minimum" reasoning extended to a transient press. `isChipFilled` is the single
+  predicate both the colour resolver and the component's press branch key off.
+- **`avatarUri` renders inline via `core/media`'s `MediaImage`** (mirroring `Avatar.tsx`'s own
+  `contentFit="cover"`/`cachePolicy="memory-disk"` technique) rather than composing `../avatar`'s
+  `Avatar` component, keeping `chip` self-contained with no import-time coupling to a sibling module
+  under concurrent edit. `expo-image` is an existing **optional** peer — `MediaImage` degrades to
+  RN's `Image` when the app never called `setExpoImage`, so a chip never crashes on first render.
+- **`recyclingKey` is the avatar's `avatarUri`.** Without it a recycled row keeps painting the
+  previous subject's face until the new URI decodes — the bug `Avatar.tsx`'s header documents.
+- **`selected` reuses the exact `solid` colour pair**, never a fourth, separately-measured filled
+  look — verified by a dedicated pure test.
+- **The remove "x" is a SIBLING of the chip's `Pressable`, positioned over a slot the chip reserves.**
+  A `Pressable` defaults to `accessible={true}`, and an accessible node collapses its whole subtree
+  into ONE accessibility element: while the "x" was a *child* of the chip (up to and including
+  v1.0.7) it could be touched but never focused or activated by VoiceOver/TalkBack — WCAG 4.1.2 /
+  2.1.1, and this file claimed the opposite. The fix keeps the chip's own press target intact (it
+  still carries `testID`, the role, the name and the state, and still spans the whole pill, so its
+  background and pressed tint run underneath the "x" exactly as before) and moves only the "x" out,
+  into a plain, non-accessible wrapper `View` that also owns the disabled dim and the consumer
+  `style`. `chipRemoveSlotStructure` widens the pill's trailing gutter by `gutter + touch box +
+  columnGap` so the reserved space is byte-identical to the old in-flow layout, and
+  `chipRemoveTouchStructure` positions the control absolutely over it. Same rule `charts` states
+  for its pressable bars ("a pressable bar/segment is a SEPARATE sibling — nesting would trap focus
+  and make it unreachable") and the same shape `date-picker`'s `PickerField` uses for its clear
+  button. The structural property is pinned by `Chip.render.test.tsx` — RNTL cannot reproduce the
+  collapse itself (see the comment there).
+
+## Known gaps
+
+- No cross-fade `transition` on the leading `avatarUri` image, unlike `Avatar`'s motion-timed fade —
+  the recycling key itself is now handled (see above).
+- No keyboard/arrow-key roving focus across a `ChipGroup`'s chips — each chip is independently
+  focusable/pressable; group-level navigation is out of scope for a v1 "layout wrapper".
+
+## Performance
+
+Both `Chip` and `ChipGroup` are wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see
+root `CLAUDE.md`). Chip and its remove affordance both use `usePressState` (scale + state-layer
+overlay); filled chips also dim via `press.overlayStyle` instead of swapping to `bg.sunken`.
+
+## 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.
+- **Round 5 (Android parity)** — the remove control (icon-only, circular) now gets its own
+  `borderless: true` ripple, split from the pill's own `borderless: false` ripple.

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

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