pixelize-native-library 1.0.6

package/lib/module/modules/alert-dialog/MODULE.md

@@ -0,0 +1,81 @@
+# alert-dialog/ — a small confirm/alert dialog composed from Modal + Button
+
+`AlertDialog` is a focused confirm/alert dialog, DELIBERATELY built by composing this library's
+own, already-shipped `Modal` (backdrop, panel, dismissal, title contrast) and `Button` (tone,
+press feedback, touch target) rather than reimplementing either from scratch. This module owns
+exactly one thing of its own: which two actions appear and which tone the confirm action carries.
+
+## Files
+
+| File | Role |
+|------|------|
+| `AlertDialog.tsx` | The component. Composes `Modal` (title, dismissal) with a description `Text` and a two-`Button` action row. |
+| `AlertDialog.variants.ts` | Pure resolvers: `resolveAlertDialogConfirmTone` (`tone` → `ButtonTone`) + the themed action-row layout (`alertDialogActionsStructure`). No React, no lucide. |
+| `index.ts` | Public surface: `AlertDialog`, `AlertDialogProps`, `AlertDialogTone`. |
+| `__tests__/AlertDialog.test.ts` | Pure: the tone-mapping resolver, plus the description text/foreground pairing this module renders itself (`fg.muted` on `bg.surface`) — measured for all brands × modes. |
+| `__tests__/AlertDialog.render.test.tsx` | Render: visibility, labels (including the `"Cancel"` default), action wiring (`onConfirm`, `onCancel`/`onRequestClose` fallback, backdrop dismissal), that `tone` reaches the confirm Button's rendered fill, and the Cancel button's rendered outline/accent label + border clearing AA on `bg.surface` — measured off the mounted Cancel Button's actual style, for all brands × modes. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `visible` | `boolean` | — | Required. Forwarded to `Modal` — fully controlled, no internal open state. |
+| `onRequestClose` | `() => void` | — | Required. Forwarded to `Modal` (backdrop press, Android back, iOS VoiceOver escape). Also the default `onCancel`. |
+| `title` | `string` | — | Required. Forwarded to `Modal`'s `title` (rendered `accessibilityRole="header"` by Modal). |
+| `description` | `string` | — | Optional body text below the title, above the actions. |
+| `confirmLabel` | `string` | — | Required. Label of the confirm action. |
+| `cancelLabel` | `string` | `"Cancel"` | Label of the cancel action. |
+| `onConfirm` | `() => void` | — | Required. Wired to the confirm Button's `onPress`. |
+| `onCancel` | `() => void` | `onRequestClose` | Wired to the cancel Button's `onPress`. Cancelling and dismissing mean the same thing unless overridden. |
+| `tone` | `"default" \| "danger"` | `"default"` | Closed union. `"danger"` passes `tone="danger"` to the confirm `Button`, mirroring Button's own destructive-action tone; `"default"` maps to Button's own default (`"accent"`). |
+| `testID` | `string` | — | Forwarded to `Modal` (seeds `${testID}-backdrop`/`${testID}-panel`) and also seeds `${testID}-cancel` / `${testID}-confirm` on the two actions. |
+
+No `style` — same reasoning as `Modal` (see its "Why no `style`" section): there is no parent
+layout flow to place a full-screen dialog within.
+
+## Accessibility contract
+
+The confirm action's *fill* (both tones) and the title are entirely `Modal`'s and `Button`'s own
+already-measured surfaces (contrast, focus ring, touch targets, `busy`/`disabled` state — see their
+MODULE.md files) — `Button.test.ts` measures `resolveButtonTone`'s `onFill`/`fill` pairing directly,
+and that doesn't depend on what it's placed on. But the Cancel action is `variant="outline"`, whose
+label/border sit on whatever background surrounds it rather than on a fill of their own — `Button`
+only measures that pairing against `bg.canvas` (its own assumed resting background), while
+AlertDialog places Cancel on Modal's panel (`bg.surface`) instead. That specific pairing needed its
+own measurement, added here rather than assumed. What this module is responsible for, and tests:
+
+- **1.4.3** — the description text (`fg.muted` on the panel's `bg.surface`) clears 4.5:1 for every
+  brand × mode — measured directly in `AlertDialog.test.ts` (this exact pairing is also proven at
+  the shared role layer in `theme/tokens/roles/__tests__/roleColors.test.ts`).
+- **1.4.3 / 1.4.11** — the Cancel button's rendered label and border against the panel's `bg.surface`
+  clear 4.5:1 / 3:1 respectively, for every brand × mode — measured in `AlertDialog.render.test.tsx`
+  by mounting `<AlertDialog>` and reading `StyleSheet.flatten` off the actually-rendered Cancel
+  Button and its label `Text`, so a change to Button's tone mapping is caught here too, without this
+  module importing Button's internal `resolveButtonTone` resolver.
+- **Dismissal semantics** — every one of Modal's dismissal paths (backdrop press, Android hardware
+  back, iOS VoiceOver escape) still resolves to `onRequestClose`, since `AlertDialog` never
+  intercepts it; only the cancel *action* gets the `onCancel` override.
+- **Confirm vs. cancel are never confusable** — the confirm action is always `variant="solid"`
+  (filled, high-emphasis) and the cancel action is always `variant="outline"` (unfilled), so the
+  destructive/primary choice is never the visually quieter one.
+
+## Patterns
+
+1. **Compose, don't reimplement.** `Modal` and `Button` are stable, shipped modules; this component
+   is exactly the "compose existing exports" step the repo's component decision order describes —
+   no backdrop, panel, or press-feedback logic is duplicated here.
+2. **Pure, testable tone mapping.** `resolveAlertDialogConfirmTone` is the one piece of this
+   module's own logic, kept free of React/lucide so it is unit-tested like every other resolver in
+   the library.
+3. **Structure vs. colour split, even for a thin composing module.** The action row's layout lives
+   in `alertDialogActionsStructure` (`createThemedVariants`, registered once per theme); this module
+   applies no colour of its own beyond the one description-text lookup.
+
+## Known gaps
+
+- No built-in scrolling for a very long `description` — same known gap `Modal` documents for
+  `children` in general; a consumer with unusually long content composes `Modal` directly instead.
+
+## Performance
+
+Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). No `useCallback`/`useMemo` needed: `cancelPress`/`onConfirm` are forwarded straight through to `Modal`/`Button` as direct prop references, never a freshly-created closure.

package/lib/module/modules/alert-dialog/index.js

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

package/lib/module/modules/alert-dialog/index.js.map

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

package/lib/module/modules/avatar/Avatar.js

@@ -0,0 +1,57 @@
+"use strict";
+
+/**
+ * Avatar — a circular identity glyph: a remote image, initials, or (with neither) a plain neutral
+ * placeholder. No press handling, no loading spinner, no animation — the simplest module in the
+ * library, which is exactly why its accessibility default differs from every sibling: an avatar
+ * usually sits beside a visible name, so `accessibilityLabel` is optional, not a required trap (see
+ * `Avatar.variants.ts` → `resolveAvatarAccessibility`).
+ */
+
+import { memo } from "react";
+import { Image, StyleSheet, Text, View } from "react-native";
+import { useTheme } from "../../theme/index.js";
+import { AVATAR_SIZES, avatarStructure, resolveAvatarAccessibility, resolveAvatarColors } from "./Avatar.variants.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+export const Avatar = /*#__PURE__*/memo(function Avatar({
+  size = "md",
+  source,
+  initials,
+  accessibilityLabel,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const spec = AVATAR_SIZES[size];
+  const colors = resolveAvatarColors(theme.colors);
+  const a11y = resolveAvatarAccessibility({
+    accessibilityLabel
+  });
+  return /*#__PURE__*/_jsx(View, {
+    testID: testID,
+    accessible: a11y.accessible,
+    accessibilityRole: a11y.accessibilityRole,
+    accessibilityLabel: a11y.accessibilityLabel,
+    accessibilityElementsHidden: a11y.accessibilityElementsHidden,
+    importantForAccessibility: a11y.importantForAccessibility,
+    style: [avatarStructure(theme, {
+      size
+    }), {
+      backgroundColor: colors.containerBg
+    }, style],
+    children: source ? /*#__PURE__*/_jsx(Image, {
+      testID: testID === undefined ? undefined : `${testID}-image`,
+      source: source,
+      resizeMode: "cover",
+      style: StyleSheet.absoluteFill
+    }) : initials ? /*#__PURE__*/_jsx(Text, {
+      numberOfLines: 1,
+      style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+        fontSize: spec.fontSize,
+        color: colors.initialsText
+      }],
+      children: initials.slice(0, 2)
+    }) : null
+  });
+});
+//# sourceMappingURL=Avatar.js.map

package/lib/module/modules/avatar/Avatar.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["memo","Image","StyleSheet","Text","View","useTheme","AVATAR_SIZES","avatarStructure","resolveAvatarAccessibility","resolveAvatarColors","jsx","_jsx","Avatar","size","source","initials","accessibilityLabel","style","testID","theme","spec","colors","a11y","accessible","accessibilityRole","accessibilityElementsHidden","importantForAccessibility","backgroundColor","containerBg","children","undefined","resizeMode","absoluteFill","numberOfLines","fontStyleForWeight","fontWeights","semibold","fontSize","color","initialsText","slice"],"sourceRoot":"../../../../src","sources":["modules/avatar/Avatar.tsx"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,IAAI,QAAQ,OAAO;AAC5B,SAASC,KAAK,EAAEC,UAAU,EAAEC,IAAI,EAAEC,IAAI,QAAQ,cAAc;AAG5D,SAASC,QAAQ,QAAQ,sBAAa;AAEtC,SACEC,YAAY,EACZC,eAAe,EACfC,0BAA0B,EAC1BC,mBAAmB,QACd,sBAAmB;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAqB3B,OAAO,MAAMC,MAAM,gBAAGZ,IAAI,CAAC,SAASY,MAAMA,CAAC;EACzCC,IAAI,GAAG,IAAI;EACXC,MAAM;EACNC,QAAQ;EACRC,kBAAkB;EAClBC,KAAK;EACLC;AACW,CAAC,EAAE;EACd,MAAMC,KAAK,GAAGd,QAAQ,CAAC,CAAC;EACxB,MAAMe,IAAI,GAAGd,YAAY,CAACO,IAAI,CAAC;EAC/B,MAAMQ,MAAM,GAAGZ,mBAAmB,CAACU,KAAK,CAACE,MAAM,CAAC;EAChD,MAAMC,IAAI,GAAGd,0BAA0B,CAAC;IAAEQ;EAAmB,CAAC,CAAC;EAE/D,oBACEL,IAAA,CAACP,IAAI;IACHc,MAAM,EAAEA,MAAO;IACfK,UAAU,EAAED,IAAI,CAACC,UAAW;IAC5BC,iBAAiB,EAAEF,IAAI,CAACE,iBAAkB;IAC1CR,kBAAkB,EAAEM,IAAI,CAACN,kBAAmB;IAC5CS,2BAA2B,EAAEH,IAAI,CAACG,2BAA4B;IAC9DC,yBAAyB,EAAEJ,IAAI,CAACI,yBAA0B;IAC1DT,KAAK,EAAE,CAACV,eAAe,CAACY,KAAK,EAAE;MAAEN;IAAK,CAAC,CAAC,EAAE;MAAEc,eAAe,EAAEN,MAAM,CAACO;IAAY,CAAC,EAAEX,KAAK,CAAE;IAAAY,QAAA,EAEzFf,MAAM,gBACLH,IAAA,CAACV,KAAK;MACJiB,MAAM,EAAEA,MAAM,KAAKY,SAAS,GAAGA,SAAS,GAAG,GAAGZ,MAAM,QAAS;MAC7DJ,MAAM,EAAEA,MAAO;MACfiB,UAAU,EAAC,OAAO;MAClBd,KAAK,EAAEf,UAAU,CAAC8B;IAAa,CAChC,CAAC,GACAjB,QAAQ,gBACVJ,IAAA,CAACR,IAAI;MACH8B,aAAa,EAAE,CAAE;MACjBhB,KAAK,EAAE,CACLE,KAAK,CAACe,kBAAkB,CAACf,KAAK,CAACgB,WAAW,CAACC,QAAQ,CAAC,EACpD;QAAEC,QAAQ,EAAEjB,IAAI,CAACiB,QAAQ;QAAEC,KAAK,EAAEjB,MAAM,CAACkB;MAAa,CAAC,CACvD;MAAAV,QAAA,EAEDd,QAAQ,CAACyB,KAAK,CAAC,CAAC,EAAE,CAAC;IAAC,CACjB,CAAC,GACL;EAAI,CACJ,CAAC;AAEX,CAAC,CAAC","ignoreList":[]}

package/lib/module/modules/avatar/Avatar.variants.js

@@ -0,0 +1,127 @@
+"use strict";
+
+/**
+ * Avatar's style + colour resolution — the pure functions the component (and its tests) depend on,
+ * plus the themed structural variant resolver.
+ *
+ * The split every sibling module copies (see `Button.variants.ts`):
+ *  - STRUCTURE (box diameter, radius) lives in the `createThemedVariants` resolver below — static
+ *    per (brand, mode), registered once via `StyleSheet.create`.
+ *  - COLOUR is resolved from the theme's ROLE colours (`resolveAvatarColors`), never a raw ramp,
+ *    never a hardcoded hex. There is no `tone`/`color` prop to widen — an avatar has exactly one
+ *    neutral identity, so the resolver takes no selector argument (same reasoning as
+ *    `resolveCheckboxColors`).
+ *  - ACCESSIBILITY prop derivation is `resolveAvatarAccessibility`, kept pure so the "decorative
+ *    unless labelled" contract is unit-testable without rendering React Native.
+ *
+ * Free of React and of any lucide import, so the WCAG + behaviour tests import it directly (mocking
+ * only `react-native`'s `StyleSheet`, as `core/style` and `Button.variants.ts` do).
+ */
+
+import { createThemedVariants } from "../../core/style/index.js";
+/**
+ * Avatar-specific dimensions. Kept a plain constant — no theme dependency — same as `BUTTON_SIZES` /
+ * `CHECKBOX_SIZES`, so the render layer and tests share one source of truth for the diameter.
+ *
+ * Not a touch target: an avatar has no `onPress` in this contract, so the 44dp floor other
+ * interactive modules hold themselves to (see `Button`'s `MIN_TOUCH_TARGET`) does not apply here.
+ */
+export const AVATAR_SIZES = {
+  xs: {
+    box: 24,
+    fontSize: 12
+  },
+  sm: {
+    box: 32,
+    fontSize: 14
+  },
+  md: {
+    box: 40,
+    fontSize: 16
+  },
+  lg: {
+    box: 56,
+    fontSize: 20
+  },
+  xl: {
+    box: 72,
+    fontSize: 24
+  }
+};
+/**
+ * Maps the avatar's fallback states onto role colours. There is no `tone`/`color` prop to widen —
+ * every colour an avatar can show is one of these role lookups, guaranteed legible in both modes and
+ * never an off-palette value an app invented (same reasoning as `resolveCheckboxColors`).
+ */
+export function resolveAvatarColors(colors) {
+  return {
+    containerBg: colors.bg.sunken,
+    initialsText: colors.fg.default
+  };
+}
+/**
+ * Derives the accessibility surface once, purely, so the "decorative unless labelled" contract is
+ * testable without a renderer. Unlike `Button`'s icon-only shape or `Checkbox`'s unlabelled shape,
+ * `accessibilityLabel` is never required here (an avatar usually sits beside a visible name — see
+ * `AvatarProps`), so absence is a valid, common state, not a trap to close off:
+ *  - no label → the avatar (image or initials) is purely decorative, hidden from assistive tech so a
+ *    screen reader doesn't announce a bare, unexplained image/initials.
+ *  - a label → exposed as a single `"image"`-role element carrying it; `accessible: true` groups the
+ *    initials `Text` into that one element instead of letting it read separately.
+ */
+export function resolveAvatarAccessibility(input) {
+  const hasLabel = input.accessibilityLabel !== undefined && input.accessibilityLabel.length > 0;
+  return {
+    accessible: hasLabel,
+    accessibilityRole: hasLabel ? "image" : undefined,
+    accessibilityLabel: hasLabel ? input.accessibilityLabel : undefined,
+    accessibilityElementsHidden: !hasLabel,
+    importantForAccessibility: hasLabel ? "auto" : "no-hide-descendants"
+  };
+}
+
+/**
+ * Structural styles only — diameter + the circular radius. No colours (those are state-driven and
+ * applied inline over this), so this compiles once per theme identity via the `WeakMap`-cached
+ * themed resolver and never rebuilds per render.
+ *
+ * `radii.full` (a finite 9999, not `Infinity` — RN rejects non-finite style values) clips a square
+ * box to a perfect circle regardless of its side length, so one token covers every size instead of
+ * each variant computing its own `box / 2`.
+ */
+export const avatarStructure = createThemedVariants(theme => ({
+  base: {
+    alignItems: "center",
+    justifyContent: "center",
+    overflow: "hidden",
+    borderRadius: theme.radii.full
+  },
+  variants: {
+    size: {
+      xs: {
+        width: AVATAR_SIZES.xs.box,
+        height: AVATAR_SIZES.xs.box
+      },
+      sm: {
+        width: AVATAR_SIZES.sm.box,
+        height: AVATAR_SIZES.sm.box
+      },
+      md: {
+        width: AVATAR_SIZES.md.box,
+        height: AVATAR_SIZES.md.box
+      },
+      lg: {
+        width: AVATAR_SIZES.lg.box,
+        height: AVATAR_SIZES.lg.box
+      },
+      xl: {
+        width: AVATAR_SIZES.xl.box,
+        height: AVATAR_SIZES.xl.box
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+//# sourceMappingURL=Avatar.variants.js.map

package/lib/module/modules/avatar/Avatar.variants.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createThemedVariants","AVATAR_SIZES","xs","box","fontSize","sm","md","lg","xl","resolveAvatarColors","colors","containerBg","bg","sunken","initialsText","fg","default","resolveAvatarAccessibility","input","hasLabel","accessibilityLabel","undefined","length","accessible","accessibilityRole","accessibilityElementsHidden","importantForAccessibility","avatarStructure","theme","base","alignItems","justifyContent","overflow","borderRadius","radii","full","variants","size","width","height","defaultVariants"],"sourceRoot":"../../../../src","sources":["modules/avatar/Avatar.variants.ts"],"mappings":"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","ignoreList":[]}

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

@@ -0,0 +1,76 @@
+# avatar/ — a circular identity glyph (image, initials, or a plain placeholder)
+
+`Avatar` is the simplest module in the library — no press handling, no loading state, no
+animation — which is exactly why its accessibility default is the one place it deliberately
+diverges from `Button`/`Checkbox`: an avatar is almost always rendered beside a visible name, so
+`accessibilityLabel` is optional rather than a required trap.
+
+## Files
+
+| File | Role |
+|------|------|
+| `Avatar.tsx` | The component. Fallback precedence (image → initials → placeholder), a11y wiring. |
+| `Avatar.variants.ts` | Pure resolvers (`AVATAR_SIZES`, `resolveAvatarColors`, `resolveAvatarAccessibility`) + the themed structural variant resolver `avatarStructure`. No React. |
+| `index.ts` | Public surface: `Avatar`, `AvatarProps`, `AvatarSize`. |
+| `__tests__/Avatar.test.ts` | Pure: WCAG contrast (all brands × modes) + the size scale + the a11y contract. |
+| `__tests__/Avatar.render.test.tsx` | Render: fallback precedence, size scale, decorative-vs-labelled a11y. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `size` | `xs \| sm \| md \| lg \| xl` | `md` | Diameters 24 / 32 / 40 / 56 / 72 dp. |
+| `source` | `{ uri: string }` | — | A remote image. Wins over `initials` when present. |
+| `initials` | `string` | — | Shown when there is no `source`. Clipped to the first two characters. |
+| `accessibilityLabel` | `string` | — | **Optional** — see Accessibility contract below. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+| `testID` | `string` | — | The image (when `source` is set) also gets `${testID}-image`. |
+
+No `tone`/`color` prop: an avatar has exactly one neutral identity (`resolveAvatarColors`), the
+same reasoning as `Checkbox`'s colour resolver — there is nothing for an app to widen.
+
+## Accessibility contract (WCAG)
+
+- **1.4.3** — initials text is `fg.default` on `bg.sunken`; measured ≥ 4.5:1 for every brand × mode
+  (`resolveAvatarColors`, tested in `Avatar.test.ts`).
+- **Decorative by default, unlike `Button`'s icon-only shape.** `Button`/`Checkbox` make an
+  unlabelled interactive element a type error, because their label is the *only* carrier of
+  meaning for a screen-reader user. An avatar is not interactive and is almost always adjacent to
+  a visible name, so forcing a label here would just duplicate that name at every call site. When
+  `accessibilityLabel` is absent, the avatar (image, initials, or placeholder) is hidden from
+  assistive tech via `accessibilityElementsHidden` (iOS) + `importantForAccessibility="no-hide-
+  descendants"` (Android) — `resolveAvatarAccessibility` derives this purely, so the contract is
+  unit-tested without a renderer.
+- When `accessibilityLabel` **is** given, the avatar is exposed as one `accessibilityRole="image"`
+  element carrying it (`accessible={true}` groups the initials `Text` into that single element
+  instead of letting it read separately).
+- No touch target / focus-ring requirements: `Avatar` has no `onPress`, so the 44dp floor and
+  focus-ring pattern `Button`/`Checkbox` implement do not apply here.
+
+## Patterns copied from `Button`/`Checkbox`
+
+1. **Structure vs colour split.** Diameter + the circular radius → `createThemedVariants`
+   (`avatarStructure`, registered once per theme). Colour → resolved from role tokens
+   (`resolveAvatarColors`), applied inline.
+2. **Pure, testable resolvers** in `Avatar.variants.ts` (no React) so the WCAG + accessibility
+   contract is unit-tested by measuring real palettes — never eyeballed.
+3. **`radii.full` clips a circle for any diameter.** One token (a finite `9999`, not `Infinity` —
+   RN rejects non-finite style values) covers every size instead of each variant computing its own
+   `box / 2`.
+4. **`style: LayoutStyle` last and once, no `{...rest}`** — internals never receive consumer style.
+
+## Testing note — hidden elements and React Native Testing Library
+
+Most render-test cases mount an *unlabelled* (decorative) avatar, which is correctly hidden from
+assistive tech. RNTL's queries mirror a screen-reader user by default and skip hidden elements, so
+those assertions pass `{ includeHiddenElements: true }` to still inspect content that is present in
+the tree but intentionally unreachable by assistive tech — see `Avatar.render.test.tsx`.
+
+## Known gaps
+
+- No image-load-error / retry affordance in this v1 (not in the component's prop contract) — an
+  image that fails to load renders blank rather than falling back to initials.
+
+## Performance
+
+Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). No child library component receives a derived array/object/callback, so no `useCallback`/`useMemo` was needed.

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

@@ -0,0 +1,12 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/avatar`. Value exports and type exports are split for
+ * `verbatimModuleSyntax`. The resolvers (`resolveAvatarColors`, `AVATAR_SIZES`, …) stay internal — a
+ * consumer configures an Avatar through its props, never by importing its internals.
+ *
+ * No `IconName` re-export here: unlike `Button`, Avatar takes no `icon` prop.
+ */
+
+export { Avatar } from "./Avatar.js";
+//# sourceMappingURL=index.js.map

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

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

package/lib/module/modules/badge/Badge.js

@@ -0,0 +1,56 @@
+"use strict";
+
+/**
+ * Badge — a non-interactive status/label chip. A `View`, never a `Pressable`: it carries no press,
+ * focus, loading, or disabled state, so it skips every interaction concern Button/Input have (no
+ * `hitSlop`, no focus ring, no reduced-motion — there is no animation to suppress).
+ */
+
+import { memo } from "react";
+import { Text, View } from "react-native";
+import { Icon } from "../../core/icon/index.js";
+import { useTheme } from "../../theme/index.js";
+import { BADGE_SIZES, badgeStructure, resolveBadgeAccessibility, resolveBadgeTone } from "./Badge.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const ICON_STROKE = 2;
+export const Badge = /*#__PURE__*/memo(function Badge({
+  tone = "accent",
+  size = "md",
+  label,
+  icon,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const spec = BADGE_SIZES[size];
+  const toneColors = resolveBadgeTone(theme.colors, tone);
+  const a11y = resolveBadgeAccessibility({
+    label
+  });
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    accessible: a11y.accessible,
+    accessibilityRole: a11y.accessibilityRole,
+    accessibilityLabel: a11y.accessibilityLabel,
+    style: [badgeStructure(theme, {
+      size
+    }), {
+      backgroundColor: toneColors.fill,
+      borderColor: toneColors.border
+    }, style],
+    children: [icon && /*#__PURE__*/_jsx(Icon, {
+      name: icon,
+      size: spec.iconSize,
+      color: toneColors.text,
+      strokeWidth: ICON_STROKE
+    }), /*#__PURE__*/_jsx(Text, {
+      numberOfLines: 1,
+      style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+        fontSize: spec.fontSize,
+        color: toneColors.text
+      }],
+      children: label
+    })]
+  });
+});
+//# sourceMappingURL=Badge.js.map

package/lib/module/modules/badge/Badge.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["memo","Text","View","Icon","useTheme","BADGE_SIZES","badgeStructure","resolveBadgeAccessibility","resolveBadgeTone","jsx","_jsx","jsxs","_jsxs","ICON_STROKE","Badge","tone","size","label","icon","style","testID","theme","spec","toneColors","colors","a11y","accessible","accessibilityRole","accessibilityLabel","backgroundColor","fill","borderColor","border","children","name","iconSize","color","text","strokeWidth","numberOfLines","fontStyleForWeight","fontWeights","semibold","fontSize"],"sourceRoot":"../../../../src","sources":["modules/badge/Badge.tsx"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;;AAEA,SAASA,IAAI,QAAQ,OAAO;AAC5B,SAASC,IAAI,EAAEC,IAAI,QAAQ,cAAc;AAEzC,SAASC,IAAI,QAAQ,0BAAiB;AAGtC,SAASC,QAAQ,QAAQ,sBAAa;AAEtC,SAASC,WAAW,EAAEC,cAAc,EAAEC,yBAAyB,EAAEC,gBAAgB,QAAQ,qBAAkB;AAAC,SAAAC,GAAA,IAAAC,IAAA,EAAAC,IAAA,IAAAC,KAAA;AAa5G,MAAMC,WAAW,GAAG,CAAC;AAErB,OAAO,MAAMC,KAAK,gBAAGd,IAAI,CAAC,SAASc,KAAKA,CAAC;EACvCC,IAAI,GAAG,QAAQ;EACfC,IAAI,GAAG,IAAI;EACXC,KAAK;EACLC,IAAI;EACJC,KAAK;EACLC;AACU,CAAC,EAAE;EACb,MAAMC,KAAK,GAAGjB,QAAQ,CAAC,CAAC;EACxB,MAAMkB,IAAI,GAAGjB,WAAW,CAACW,IAAI,CAAC;EAC9B,MAAMO,UAAU,GAAGf,gBAAgB,CAACa,KAAK,CAACG,MAAM,EAAET,IAAI,CAAC;EACvD,MAAMU,IAAI,GAAGlB,yBAAyB,CAAC;IAAEU;EAAM,CAAC,CAAC;EAEjD,oBACEL,KAAA,CAACV,IAAI;IACHkB,MAAM,EAAEA,MAAO;IACfM,UAAU,EAAED,IAAI,CAACC,UAAW;IAC5BC,iBAAiB,EAAEF,IAAI,CAACE,iBAAkB;IAC1CC,kBAAkB,EAAEH,IAAI,CAACG,kBAAmB;IAC5CT,KAAK,EAAE,CACLb,cAAc,CAACe,KAAK,EAAE;MAAEL;IAAK,CAAC,CAAC,EAC/B;MAAEa,eAAe,EAAEN,UAAU,CAACO,IAAI;MAAEC,WAAW,EAAER,UAAU,CAACS;IAAO,CAAC,EACpEb,KAAK,CACL;IAAAc,QAAA,GAEDf,IAAI,iBAAIR,IAAA,CAACP,IAAI;MAAC+B,IAAI,EAAEhB,IAAK;MAACF,IAAI,EAAEM,IAAI,CAACa,QAAS;MAACC,KAAK,EAAEb,UAAU,CAACc,IAAK;MAACC,WAAW,EAAEzB;IAAY,CAAE,CAAC,eACpGH,IAAA,CAACT,IAAI;MACHsC,aAAa,EAAE,CAAE;MACjBpB,KAAK,EAAE,CACLE,KAAK,CAACmB,kBAAkB,CAACnB,KAAK,CAACoB,WAAW,CAACC,QAAQ,CAAC,EACpD;QAAEC,QAAQ,EAAErB,IAAI,CAACqB,QAAQ;QAAEP,KAAK,EAAEb,UAAU,CAACc;MAAK,CAAC,CACnD;MAAAJ,QAAA,EAEDhB;IAAK,CACF,CAAC;EAAA,CACH,CAAC;AAEX,CAAC,CAAC","ignoreList":[]}

package/lib/module/modules/badge/Badge.variants.js

@@ -0,0 +1,124 @@
+"use strict";
+
+/**
+ * Badge's style resolution — same split as Button/Input:
+ *  - STRUCTURE (height, padding, radius, border WIDTH) lives in the themed `badgeStructure`
+ *    resolver, static per (brand, mode), registered once via `StyleSheet.create`.
+ *  - COLOUR is `tone`-driven and resolved by `resolveBadgeTone` from the theme's ROLE colours,
+ *    never a raw ramp and never a hardcoded hex.
+ *
+ * Free of React and of `lucide`, so the WCAG tests import it directly (mocking only
+ * `react-native`'s `StyleSheet`, as `core/style` does).
+ */
+
+import { createThemedVariants } from "../../core/style/index.js";
+
+/** `accent`/`neutral` are brand-driven emphasis; the rest mirror the theme's status roles. */
+
+/**
+ * Badge-specific dimensions — a chip is never a touch target (Badge is a `View`, not a
+ * `Pressable`), so there is no `hitSlop`/44dp floor here, unlike Button/Input. `fontSize`/`iconSize`
+ * sit on the same +2 icon-over-label offset Button uses, one step down its scale (12/14 vs 14/16).
+ */
+export const BADGE_SIZES = {
+  sm: {
+    height: 20,
+    fontSize: 12,
+    iconSize: 14
+  },
+  md: {
+    height: 24,
+    fontSize: 14,
+    iconSize: 16
+  }
+};
+/**
+ * Maps a `tone` onto the theme's role colours — the reason the prop is a closed union and not
+ * `color?: string`. Every colour a Badge can show is one of these role lookups.
+ *
+ * `accent`/`neutral` mirror Button's tone shapes but always at the "subtle" emphasis (a badge is
+ * a passive label, never a filled call-to-action): `accent` tints toward the brand, `neutral` is
+ * the monochrome high-emphasis pairing (`bg.sunken` + `fg.default`), both bordered by the same
+ * `border.interactive` outline Button uses for its outline variant (measured ≥ 3:1 against the
+ * canvas AND against either subtle fill on all 8 brands × both modes — see `Badge.test.ts`).
+ *
+ * The four status tones deliberately do NOT read `StatusColors.border`: that field (`ramp[200]`)
+ * is documented as "decorative chip/badge outline", but measured, it clears neither 3:1 against
+ * the canvas nor against its own `subtle` fill on ANY brand × mode (as low as 1.26:1) — the same
+ * class of gap `Input.variants.ts` found and fixed for `danger` alone (reading `.solid` there
+ * instead). `.solid` does not generalise here: it clears 3:1 for `danger` but not for
+ * `success`/`warning`/`info` in light mode (as low as 1.84:1). `StatusColors.text` is the one
+ * field proven ≥ 3:1 against both the canvas and the subtle fill for EVERY status role, brand, and
+ * mode (it is picked by `readableOn` for ≥ 4.5:1 against `subtle`, which already implies ≥ 3:1,
+ * and measures ≥ 5.05:1 against the canvas incidentally) — so the border reuses it, giving a
+ * coloured outline that always matches the label, never an unreadable hairline.
+ */
+export function resolveBadgeTone(colors, tone) {
+  switch (tone) {
+    case "accent":
+      return {
+        fill: colors.accent.subtle,
+        text: colors.accent.text,
+        border: colors.border.interactive
+      };
+    case "neutral":
+      return {
+        fill: colors.bg.sunken,
+        text: colors.fg.default,
+        border: colors.border.interactive
+      };
+    default:
+      return statusTone(colors.status[tone]);
+  }
+}
+function statusTone(status) {
+  return {
+    fill: status.subtle,
+    text: status.text,
+    border: status.text
+  };
+}
+/**
+ * Derives the accessibility surface once, purely, so it's testable without a renderer. A Badge is
+ * never interactive, so unlike Button/Input there is no `disabled`/`busy` state to report — just
+ * the single accessible name a screen reader announces for the whole chip.
+ */
+export function resolveBadgeAccessibility(input) {
+  return {
+    accessible: true,
+    accessibilityRole: "text",
+    accessibilityLabel: input.label
+  };
+}
+
+/**
+ * Structural styles only — layout, height, padding, radius, border WIDTH. No colours (those are
+ * tone-driven and applied inline over this), so this compiles once per theme identity via the
+ * `WeakMap`-cached themed resolver and never rebuilds per render.
+ */
+export const badgeStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+    columnGap: theme.space[1],
+    borderRadius: theme.radii.base,
+    borderWidth: theme.borderWidths.thin
+  },
+  variants: {
+    size: {
+      sm: {
+        height: BADGE_SIZES.sm.height,
+        paddingHorizontal: theme.space[2]
+      },
+      md: {
+        height: BADGE_SIZES.md.height,
+        paddingHorizontal: theme.space[3]
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+//# sourceMappingURL=Badge.variants.js.map

package/lib/module/modules/badge/Badge.variants.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createThemedVariants","BADGE_SIZES","sm","height","fontSize","iconSize","md","resolveBadgeTone","colors","tone","fill","accent","subtle","text","border","interactive","bg","sunken","fg","default","statusTone","status","resolveBadgeAccessibility","input","accessible","accessibilityRole","accessibilityLabel","label","badgeStructure","theme","base","flexDirection","alignItems","justifyContent","columnGap","space","borderRadius","radii","borderWidth","borderWidths","thin","variants","size","paddingHorizontal","defaultVariants"],"sourceRoot":"../../../../src","sources":["modules/badge/Badge.variants.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA,SAASA,oBAAoB,QAAQ,2BAAkB;;AAGvD;;AAYA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,WAAW,GAAG;EACzBC,EAAE,EAAE;IAAEC,MAAM,EAAE,EAAE;IAAEC,QAAQ,EAAE,EAAE;IAAEC,QAAQ,EAAE;EAAG,CAAC;EAC9CC,EAAE,EAAE;IAAEH,MAAM,EAAE,EAAE;IAAEC,QAAQ,EAAE,EAAE;IAAEC,QAAQ,EAAE;EAAG;AAC/C,CAAqD;AAWrD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASE,gBAAgBA,CAACC,MAAkB,EAAEC,IAAe,EAAmB;EACrF,QAAQA,IAAI;IACV,KAAK,QAAQ;MACX,OAAO;QAAEC,IAAI,EAAEF,MAAM,CAACG,MAAM,CAACC,MAAM;QAAEC,IAAI,EAAEL,MAAM,CAACG,MAAM,CAACE,IAAI;QAAEC,MAAM,EAAEN,MAAM,CAACM,MAAM,CAACC;MAAY,CAAC;IACpG,KAAK,SAAS;MACZ,OAAO;QAAEL,IAAI,EAAEF,MAAM,CAACQ,EAAE,CAACC,MAAM;QAAEJ,IAAI,EAAEL,MAAM,CAACU,EAAE,CAACC,OAAO;QAAEL,MAAM,EAAEN,MAAM,CAACM,MAAM,CAACC;MAAY,CAAC;IAC/F;MACE,OAAOK,UAAU,CAACZ,MAAM,CAACa,MAAM,CAACZ,IAAI,CAAC,CAAC;EAC1C;AACF;AAEA,SAASW,UAAUA,CAACC,MAAoB,EAAmB;EACzD,OAAO;IAAEX,IAAI,EAAEW,MAAM,CAACT,MAAM;IAAEC,IAAI,EAAEQ,MAAM,CAACR,IAAI;IAAEC,MAAM,EAAEO,MAAM,CAACR;EAAK,CAAC;AACxE;AAaA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASS,yBAAyBA,CAACC,KAA8B,EAA2B;EACjG,OAAO;IAAEC,UAAU,EAAE,IAAI;IAAEC,iBAAiB,EAAE,MAAM;IAAEC,kBAAkB,EAAEH,KAAK,CAACI;EAAM,CAAC;AACzF;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,cAAc,GAAG5B,oBAAoB,CAAE6B,KAAY,KAAM;EACpEC,IAAI,EAAE;IACJC,aAAa,EAAE,KAAK;IACpBC,UAAU,EAAE,QAAQ;IACpBC,cAAc,EAAE,QAAQ;IACxBC,SAAS,EAAEL,KAAK,CAACM,KAAK,CAAC,CAAC,CAAC;IACzBC,YAAY,EAAEP,KAAK,CAACQ,KAAK,CAACP,IAAI;IAC9BQ,WAAW,EAAET,KAAK,CAACU,YAAY,CAACC;EAClC,CAAC;EACDC,QAAQ,EAAE;IACRC,IAAI,EAAE;MACJxC,EAAE,EAAE;QAAEC,MAAM,EAAEF,WAAW,CAACC,EAAE,CAACC,MAAM;QAAEwC,iBAAiB,EAAEd,KAAK,CAACM,KAAK,CAAC,CAAC;MAAE,CAAC;MACxE7B,EAAE,EAAE;QAAEH,MAAM,EAAEF,WAAW,CAACK,EAAE,CAACH,MAAM;QAAEwC,iBAAiB,EAAEd,KAAK,CAACM,KAAK,CAAC,CAAC;MAAE;IACzE;EACF,CAAC;EACDS,eAAe,EAAE;IAAEF,IAAI,EAAE;EAAK;AAChC,CAAC,CAAC,CAAC","ignoreList":[]}