pixelize-native-library 1.0.6

package/lib/module/modules/slider/Slider.variants.js

@@ -0,0 +1,258 @@
+"use strict";
+
+/**
+ * Slider's pure math + style + accessibility resolution — the functions the component (and its
+ * tests) depend on, plus the themed structural variant resolvers. Same split as `Button.variants.ts`:
+ *
+ *  - STRUCTURE (row height, track height, thumb diameter, radii, border WIDTH) lives in the
+ *    `createThemedVariants` resolvers below — static per (brand, mode), registered once.
+ *  - COLOUR is resolved from the theme's ROLE colours (`resolveSliderTrackColors`,
+ *    `resolveSliderThumbColors`), never a raw ramp, never a hardcoded hex.
+ *  - DRAG MATH (`resolveSliderPositionValue`, `sliderValueToFraction`, `stepSliderValue`, …) is kept
+ *    free of React Native so it is unit-testable without a renderer or a real gesture.
+ *  - ACCESSIBILITY prop derivation is `resolveSliderAccessibility`.
+ *
+ * Free of `lucide` and of any React tree, so the WCAG + math tests import this directly (mocking
+ * only `react-native`'s `StyleSheet`, as `core/style` and `Button.variants.ts` do).
+ */
+
+import { createThemedVariants } from "../../core/style/index.js";
+/** Same touch-target floor as every other interactive control in this library (44dp, WCAG 2.5.5 AAA). */
+export const MIN_TOUCH_TARGET = 44;
+const slopFor = dimension => Math.max(0, Math.ceil((MIN_TOUCH_TARGET - dimension) / 2));
+export const SLIDER_SIZES = {
+  sm: {
+    trackHeight: 4,
+    thumbSize: 16,
+    hitSlop: slopFor(16)
+  },
+  md: {
+    trackHeight: 6,
+    thumbSize: 20,
+    hitSlop: slopFor(20)
+  }
+};
+
+/**
+ * The row's `hitSlop`, pre-built per size as a MODULE-LEVEL constant (not built inline in the
+ * component) so it's a stable object reference across renders, same discipline as every other
+ * inline style object in this library. Vertical-only (`left`/`right: 0`): the row already spans the
+ * component's full width, so only the short axis needs to grow to the 44dp floor.
+ */
+export const SLIDER_HIT_SLOP = {
+  sm: {
+    top: SLIDER_SIZES.sm.hitSlop,
+    bottom: SLIDER_SIZES.sm.hitSlop,
+    left: 0,
+    right: 0
+  },
+  md: {
+    top: SLIDER_SIZES.md.hitSlop,
+    bottom: SLIDER_SIZES.md.hitSlop,
+    left: 0,
+    right: 0
+  }
+};
+
+/**
+ * Clamps a value onto `[min, max]`. `NaN` (a caller's bad math) clamps to `min` rather than
+ * propagating into a `NaN%` width or an invalid `accessibilityValue.now`.
+ */
+export function clampSliderValue(value, min, max) {
+  if (Number.isNaN(value)) return min;
+  return Math.min(max, Math.max(min, value));
+}
+
+/**
+ * Snaps a value onto the nearest `step` multiple measured from `min`, then clamps onto `[min, max]`.
+ * A non-positive `step` (a caller error) falls back to `1` rather than dividing by zero.
+ */
+export function snapSliderValue(value, min, max, step) {
+  const safeStep = step > 0 ? step : 1;
+  const steps = Math.round((value - min) / safeStep);
+  return clampSliderValue(min + steps * safeStep, min, max);
+}
+
+/**
+ * The fraction (0–1) of the track the current value represents — what both the fill width and the
+ * thumb's `left` position render from. Clamped even for an out-of-range `value` a caller might pass
+ * directly (never drives a rendered width/position outside the track), and `max ≤ min` (a caller
+ * error) resolves to `0` rather than a division by zero.
+ */
+export function sliderValueToFraction(value, min, max) {
+  if (max <= min) return 0;
+  return Math.min(1, Math.max(0, (value - min) / (max - min)));
+}
+/**
+ * Converts a touch's x position within the measured track into a value: the position clamps onto
+ * the track bounds first (a touch past either end still resolves to `min`/`max`, not an out-of-range
+ * value), then the resulting value snaps onto `step`. Resolves to `min` when the track hasn't been
+ * measured yet (`trackWidth ≤ 0`) or `max ≤ min` (a caller error) — never `NaN`.
+ */
+export function resolveSliderPositionValue(input) {
+  const {
+    locationX,
+    trackWidth,
+    min,
+    max,
+    step
+  } = input;
+  if (trackWidth <= 0 || max <= min) return min;
+  const fraction = Math.min(1, Math.max(0, locationX / trackWidth));
+  return snapSliderValue(min + fraction * (max - min), min, max, step);
+}
+
+/**
+ * Adjusts `value` by one `step` in `direction`, clamped onto `[min, max]` — the pure core of the
+ * `increment`/`decrement` accessibility actions (WCAG 2.5.7's required non-drag alternative).
+ */
+export function stepSliderValue(value, direction, min, max, step) {
+  return clampSliderValue(value + direction * step, min, max);
+}
+/**
+ * Maps the track's two colours onto ROLE tokens — never a raw ramp or a hardcoded hex. `fill` is
+ * `accent.text`, NOT the seemingly-obvious `accent.solid`: measured, `accent.solid` against
+ * `bg.sunken` falls as low as ~1.6:1 on rosewood light — the exact class of gap `ProgressBar`
+ * documented and fixed (a `*.solid` role is only guaranteed to clear contrast against its own
+ * derived `onSolid` label, never against an arbitrary neutral surface). `accent.text` is the SAME
+ * role `Button`'s outline/ghost/link label uses specifically because it's engineered to read on a
+ * pale surface, and measured here at ≥ 4.4:1 against `bg.sunken` for all 8 brands × both modes
+ * (`Slider.test.ts`) — comfortably clearing the 3:1 floor this fill actually needs.
+ */
+export function resolveSliderTrackColors(colors) {
+  return {
+    track: colors.bg.sunken,
+    fill: colors.accent.text
+  };
+}
+/**
+ * The thumb can sit over either the resting track (`bg.sunken`) or the filled portion
+ * (`accent.text`), and no single flat colour clears 3:1 against both on every brand — measured:
+ * `bg.canvas` alone is as low as ~1:1 against `bg.sunken` (they're near-identical on some brands,
+ * the same trap `Switch` avoided by measuring against `border.interactive`/`accent.solid`, never
+ * `bg.sunken`), and a neutral `border.interactive` ring is as low as ~1:1 against a saturated
+ * `accent.text` fill on several brands. So the two boundaries are carried by DIFFERENT parts of the
+ * thumb, each measured against the surface it actually needs to clear (`Slider.test.ts`):
+ *  - `border` (`border.interactive`, the same proven neutral outline `Button`'s outline variant and
+ *    `Checkbox`'s unchecked box use) is the boundary against the RESTING track — ≥ 3.05:1 worst case.
+ *  - `fill` (`bg.canvas`, matching `Switch`'s thumb) is the boundary against the ACCENT fill — the
+ *    much larger fill area clears ≥ 4.6:1 worst case there even though the thin ring alone would not.
+ */
+export function resolveSliderThumbColors(colors) {
+  return {
+    fill: colors.bg.canvas,
+    border: colors.border.interactive
+  };
+}
+/**
+ * Derives the accessibility surface once, purely, so the contract is testable without a renderer.
+ * `now` is clamped onto `[min, max]` — a screen reader must never announce a value the track itself
+ * couldn't render. `accessibilityActions` declares BOTH `increment`/`decrement` explicitly: iOS's
+ * `adjustable` trait already offers these via the two-finger swipe-up/down gesture without them
+ * declared, but Android TalkBack has no native "adjustable" gesture and only surfaces custom actions
+ * that are declared here (WCAG 2.5.7 — a drag-only slider has no non-pointer alternative otherwise).
+ */
+export function resolveSliderAccessibility(input) {
+  return {
+    accessibilityRole: "adjustable",
+    accessibilityValue: {
+      min: input.min,
+      max: input.max,
+      now: clampSliderValue(input.value, input.min, input.max)
+    },
+    accessibilityState: {
+      disabled: input.disabled === true
+    },
+    accessibilityActions: [{
+      name: "increment"
+    }, {
+      name: "decrement"
+    }]
+  };
+}
+
+/**
+ * Structural row styles — the draggable node's own dimensions. Height is fixed to the size's
+ * `thumbSize` (not `trackHeight`): the row must be tall enough to contain the thumb, which is
+ * absolutely positioned within it and vertically centred purely by the row matching its diameter.
+ * No colour here — this node's `backgroundColor` is never set; only its children paint.
+ */
+export const sliderRowStructure = createThemedVariants(_theme => ({
+  base: {
+    justifyContent: "center"
+  },
+  variants: {
+    size: {
+      sm: {
+        height: SLIDER_SIZES.sm.thumbSize
+      },
+      md: {
+        height: SLIDER_SIZES.md.thumbSize
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+
+/** Structural track styles — full width, pill radius, clipped so the fill can't poke past it. */
+export const sliderTrackStructure = createThemedVariants(theme => ({
+  base: {
+    width: "100%",
+    borderRadius: theme.radii.full,
+    overflow: "hidden"
+  },
+  variants: {
+    size: {
+      sm: {
+        height: SLIDER_SIZES.sm.trackHeight
+      },
+      md: {
+        height: SLIDER_SIZES.md.trackHeight
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+
+/** The filled segment's own corner radius — matches the track's, same reasoning as `ProgressBar`. */
+export const sliderFillStructure = createThemedVariants(theme => ({
+  base: {
+    height: "100%",
+    borderRadius: theme.radii.full
+  }
+}));
+
+/**
+ * Structural thumb styles — size, pill radius, border WIDTH. No colour (fill/border colour is
+ * applied inline from `resolveSliderThumbColors`, same structure/colour split as `checkboxBoxStructure`).
+ * `top: 0` relies on the row's height exactly matching `thumbSize` (see `sliderRowStructure`) to
+ * centre vertically; `left`/`marginLeft` (the value-driven position) are applied inline per render.
+ */
+export const sliderThumbStructure = createThemedVariants(theme => ({
+  base: {
+    position: "absolute",
+    top: 0,
+    borderRadius: theme.radii.full,
+    borderWidth: theme.borderWidths.thick
+  },
+  variants: {
+    size: {
+      sm: {
+        width: SLIDER_SIZES.sm.thumbSize,
+        height: SLIDER_SIZES.sm.thumbSize
+      },
+      md: {
+        width: SLIDER_SIZES.md.thumbSize,
+        height: SLIDER_SIZES.md.thumbSize
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+}));
+//# sourceMappingURL=Slider.variants.js.map

package/lib/module/modules/slider/Slider.variants.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createThemedVariants","MIN_TOUCH_TARGET","slopFor","dimension","Math","max","ceil","SLIDER_SIZES","sm","trackHeight","thumbSize","hitSlop","md","SLIDER_HIT_SLOP","top","bottom","left","right","clampSliderValue","value","min","Number","isNaN","snapSliderValue","step","safeStep","steps","round","sliderValueToFraction","resolveSliderPositionValue","input","locationX","trackWidth","fraction","stepSliderValue","direction","resolveSliderTrackColors","colors","track","bg","sunken","fill","accent","text","resolveSliderThumbColors","canvas","border","interactive","resolveSliderAccessibility","accessibilityRole","accessibilityValue","now","accessibilityState","disabled","accessibilityActions","name","sliderRowStructure","_theme","base","justifyContent","variants","size","height","defaultVariants","sliderTrackStructure","theme","width","borderRadius","radii","full","overflow","sliderFillStructure","sliderThumbStructure","position","borderWidth","borderWidths","thick"],"sourceRoot":"../../../../src","sources":["modules/slider/Slider.variants.ts"],"mappings":"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","ignoreList":[]}

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

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

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

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

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

@@ -0,0 +1,97 @@
+# spinner/ — a thin themed wrapper around RN's own `<ActivityIndicator>`
+
+`Spinner` renders an indeterminate loading indicator. It takes no children and no interaction —
+mounting it always means work is in progress.
+
+## Files
+
+| File | Role |
+|------|------|
+| `Spinner.tsx` | The component. Wraps the glyph in a sized, centered box that carries the accessibility contract; the `ActivityIndicator` itself is decorative chrome. |
+| `Spinner.variants.ts` | Pure resolvers (`resolveSpinnerTone`, `resolveSpinnerAccessibility`, `SPINNER_SIZES`) + the untethered structural resolvers `spinnerBox` / `spinnerGlyphScale`. No React, no lucide. |
+| `index.ts` | Public surface: `Spinner`, `SpinnerProps`, `SpinnerSize`, `SpinnerTone`. No `icon` prop, so no `IconName` re-export. |
+| `__tests__/Spinner.test.ts` | Pure: WCAG 1.4.11 contrast (all brands × modes) + the size→box invariant + the accessibility contract. |
+| `__tests__/Spinner.render.test.tsx` | Render: name/busy, each size's resolved box, tone's resolved colour, reduced-motion freeze, glyph hidden from AT, consumer `style` last. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `size` | `sm \| md \| lg` | `md` | Closed union. 16 / 20 / 28 dp box — see "Sizing" below. |
+| `tone` | `accent \| neutral` | `accent` | Closed union — resolves to `colors.accent.solid` / `colors.fg.muted`. |
+| `accessibilityLabel` | `string` | `"Loading"` | A Spinner renders no visible text, so this is its only accessible name. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+| `testID` | `string` | — | Forwarded to the outermost box. The internal glyph gets `${testID}-glyph` (hidden from AT — see below). |
+
+## Sizing — why a box AND a scaled glyph
+
+RN's `<ActivityIndicator>` ships exactly two native sizes, `"small"` (20dp) and `"large"` (36dp) —
+no continuous control, and a numeric `size` is Android-only. Every `Spinner` size anchors on
+`"small"` and reaches `md`/`lg` with a `transform: scale`, so the glyph stays the same shape on
+both platforms rather than jumping to the fixed `"large"` asset partway through the scale.
+
+A `transform` alone repaints without touching layout — scaling the indicator up for `lg` without
+also correcting its reserved space would leave it visually overflowing a box a naive implementation
+still measured at 20dp. So the component renders **two nodes**: an outer `View` sized to the exact
+visually-scaled footprint (`spinnerBox` — 16 / 20 / 28 dp, `boxSize = 20 × scale`), centering an
+inner `ActivityIndicator` that carries the `transform: scale` (`spinnerGlyphScale`). One node can't
+both declare "I am 28dp" and "scale me 1.4×" without double-applying the enlargement — that's why
+the scale lives on the child, never the box.
+
+## Accessibility contract (WCAG)
+
+- **The OUTER box, not the glyph, carries the whole contract** — `accessibilityRole="progressbar"`,
+  the accessible name (`accessibilityLabel ?? "Loading"`), and `accessibilityState={{ busy: true }}`
+  (1.4.1 — the loading state is announced, not left to be inferred from a shape appearing on
+  screen). The inner `ActivityIndicator` is `accessibilityElementsHidden` +
+  `importantForAccessibility="no-hide-descendants"` — decorative chrome, exactly how `Button` treats
+  its own embedded loading spinner, so a screen reader announces ONE "Loading" node, never a nested
+  second element.
+- **1.4.11 (Graphical Objects)** — a spinner is a graphical object required to understand that work
+  is ongoing, so both tones are measured ≥ 3:1 against `bg.canvas`, `bg.surface`, AND `bg.raised` on
+  all 8 brands × both modes (`Spinner.test.ts`) — never eyeballed.
+- **2.3.3 (reduced motion)** — see "Reduced motion" below.
+- **Touch target (2.5.x)** — N/A. A Spinner is never interactive; there is no `hitSlop`.
+
+## Reduced motion — frozen, not removed
+
+`useReducedMotion()` gates `animating`: when the OS setting is on, the glyph stops spinning
+(`animating={false}`) rather than being conveyed through motion alone. `hidesWhenStopped={false}`
+(iOS otherwise defaults this to `true`) keeps a still-visible ring rather than the glyph vanishing —
+freezing the motion shouldn't also remove the only visual cue a sighted, non-AT user has that
+something is loading. The always-present `busy` state + accessible name on the outer box is the
+operative signal either way, same philosophy `Button` documents for its own embedded spinner
+("never the sole loading signal").
+
+RN's `<ActivityIndicator>` spin is native-platform-driven, not this library's own `Animated` API —
+there is no supported hook to slow or shorten its rotation, only to start/stop it, which is exactly
+what `animating` does here.
+
+## Why `tone` is a union, not a `color`
+
+Same reasoning as every other module: `color?: string` would hand the token system back to the app.
+`accent`/`neutral` map to ROLE colours (`resolveSpinnerTone`), so every colour a Spinner can show is
+guaranteed legible and inverts light↔dark for free.
+
+## Patterns copied from `button/` (the reference module) and `skeleton/`
+
+1. **Structure vs colour split**, but with no theme dependency: `spinnerBox`/`spinnerGlyphScale` use
+   the untethered `createVariants` (not `createThemedVariants`) since the dp constants aren't on the
+   theme's spacing scale — same reasoning `BUTTON_SIZES` documents for being a plain constant.
+   Colour is resolved from role tokens and applied inline via `useThemeColors()` (the raw-value
+   escape hatch `Switch` also uses, since `ActivityIndicator`'s `color` prop takes no token object).
+2. **Pure, testable resolvers** in `Spinner.variants.ts` (no React) so the WCAG + accessibility
+   contract is unit-tested against real palettes.
+3. **Closed unions only** (`size`/`tone`), `style: LayoutStyle` last and once, no `{...rest}`.
+4. **`progressbar` role + a default "Loading" name**, the same contract `skeleton/` uses when it
+   exposes itself — the two differ only in when the contract applies: Skeleton is decorative by
+   default and opts IN when given a label; Spinner's whole existence IS the loading signal, so it is
+   always on.
+
+## Known gaps
+
+None — no icon, no new theme token, no new core helper needed for this component.
+
+## Performance
+
+Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). Only child is `ActivityIndicator` (RN host primitive) receiving primitives/plain style values — nothing to memoize.

package/lib/module/modules/spinner/Spinner.js

@@ -0,0 +1,58 @@
+"use strict";
+
+/**
+ * Spinner — a thin themed wrapper around RN's own `<ActivityIndicator>`. The glyph itself is purely
+ * decorative chrome, hidden from assistive tech exactly how `Button` treats ITS embedded loading
+ * spinner: the OUTER box carries the `progressbar` role, the accessible name, and `busy` state, so a
+ * screen reader announces one "Loading" node — never the indicator as a second, redundant element.
+ */
+
+import { memo } from "react";
+import { ActivityIndicator, View } from "react-native";
+import { useReducedMotion } from "../../core/a11y/index.js";
+import { useThemeColors } from "../../theme/index.js";
+import { resolveSpinnerAccessibility, resolveSpinnerTone, spinnerBox, spinnerGlyphScale } from "./Spinner.variants.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+export const Spinner = /*#__PURE__*/memo(function Spinner({
+  size = "md",
+  tone = "accent",
+  style,
+  testID,
+  accessibilityLabel
+}) {
+  const colors = useThemeColors();
+  const reducedMotion = useReducedMotion();
+  const color = resolveSpinnerTone(colors, tone);
+  const a11y = resolveSpinnerAccessibility({
+    accessibilityLabel
+  });
+  return /*#__PURE__*/_jsx(View, {
+    testID: testID,
+    accessible: true,
+    accessibilityRole: a11y.accessibilityRole,
+    accessibilityLabel: a11y.accessibilityLabel,
+    accessibilityState: a11y.accessibilityState,
+    style: [spinnerBox({
+      size
+    }), style],
+    children: /*#__PURE__*/_jsx(ActivityIndicator, {
+      testID: testID === undefined ? undefined : `${testID}-glyph`,
+      size: "small",
+      color: color
+      // A frozen (non-spinning) glyph for a reduced-motion user (WCAG 2.3.3) — the box's own
+      // `busy` state + label above is the real signal, exactly how `Button` treats ITS embedded
+      // spinner as decoration on top of `accessibilityState.busy`. `hidesWhenStopped={false}`
+      // (iOS defaults this to `true`) keeps a still-visible ring rather than the glyph vanishing:
+      // freezing the motion shouldn't also remove the only visual cue a sighted, non-AT user has.
+      ,
+      animating: !reducedMotion,
+      hidesWhenStopped: false,
+      accessibilityElementsHidden: true,
+      importantForAccessibility: "no-hide-descendants",
+      style: spinnerGlyphScale({
+        size
+      })
+    })
+  });
+});
+//# sourceMappingURL=Spinner.js.map

package/lib/module/modules/spinner/Spinner.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["memo","ActivityIndicator","View","useReducedMotion","useThemeColors","resolveSpinnerAccessibility","resolveSpinnerTone","spinnerBox","spinnerGlyphScale","jsx","_jsx","Spinner","size","tone","style","testID","accessibilityLabel","colors","reducedMotion","color","a11y","accessible","accessibilityRole","accessibilityState","children","undefined","animating","hidesWhenStopped","accessibilityElementsHidden","importantForAccessibility"],"sourceRoot":"../../../../src","sources":["modules/spinner/Spinner.tsx"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,IAAI,QAAQ,OAAO;AAC5B,SAASC,iBAAiB,EAAEC,IAAI,QAAQ,cAAc;AAEtD,SAASC,gBAAgB,QAAQ,0BAAiB;AAElD,SAASC,cAAc,QAAQ,sBAAa;AAE5C,SACEC,2BAA2B,EAC3BC,kBAAkB,EAClBC,UAAU,EACVC,iBAAiB,QACZ,uBAAoB;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAa5B,OAAO,MAAMC,OAAO,gBAAGX,IAAI,CAAC,SAASW,OAAOA,CAAC;EAC3CC,IAAI,GAAG,IAAI;EACXC,IAAI,GAAG,QAAQ;EACfC,KAAK;EACLC,MAAM;EACNC;AACY,CAAC,EAAE;EACf,MAAMC,MAAM,GAAGb,cAAc,CAAC,CAAC;EAC/B,MAAMc,aAAa,GAAGf,gBAAgB,CAAC,CAAC;EAExC,MAAMgB,KAAK,GAAGb,kBAAkB,CAACW,MAAM,EAAEJ,IAAI,CAAC;EAC9C,MAAMO,IAAI,GAAGf,2BAA2B,CAAC;IAAEW;EAAmB,CAAC,CAAC;EAEhE,oBACEN,IAAA,CAACR,IAAI;IACHa,MAAM,EAAEA,MAAO;IACfM,UAAU;IACVC,iBAAiB,EAAEF,IAAI,CAACE,iBAAkB;IAC1CN,kBAAkB,EAAEI,IAAI,CAACJ,kBAAmB;IAC5CO,kBAAkB,EAAEH,IAAI,CAACG,kBAAmB;IAC5CT,KAAK,EAAE,CAACP,UAAU,CAAC;MAAEK;IAAK,CAAC,CAAC,EAAEE,KAAK,CAAE;IAAAU,QAAA,eAErCd,IAAA,CAACT,iBAAiB;MAChBc,MAAM,EAAEA,MAAM,KAAKU,SAAS,GAAGA,SAAS,GAAG,GAAGV,MAAM,QAAS;MAC7DH,IAAI,EAAC,OAAO;MACZO,KAAK,EAAEA;MACP;MACA;MACA;MACA;MACA;MAAA;MACAO,SAAS,EAAE,CAACR,aAAc;MAC1BS,gBAAgB,EAAE,KAAM;MACxBC,2BAA2B;MAC3BC,yBAAyB,EAAC,qBAAqB;MAC/Cf,KAAK,EAAEN,iBAAiB,CAAC;QAAEI;MAAK,CAAC;IAAE,CACpC;EAAC,CACE,CAAC;AAEX,CAAC,CAAC","ignoreList":[]}

package/lib/module/modules/spinner/Spinner.variants.js

@@ -0,0 +1,131 @@
+"use strict";
+
+/**
+ * Spinner's pure resolvers — colour, accessibility, and the size→box/scale mapping. No React, no
+ * lucide: same split as `Button.variants.ts`, so the WCAG + behaviour tests import these directly,
+ * measuring real palettes instead of eyeballing a hex.
+ */
+
+import { createVariants } from "../../core/style/index.js";
+/**
+ * RN's `<ActivityIndicator>` ships exactly two native sizes, `"small"` (20dp) and `"large"` (36dp)
+ * — no continuous control, and a numeric `size` is Android-only (iOS ignores it). Anchoring every
+ * size on `"small"` and reaching `md`/`lg` with a `transform: scale` keeps the rendered glyph the
+ * same shape on both platforms, rather than jumping to the fixed `"large"` asset partway through
+ * the scale. `boxSize` is `20 × scale`: it exists so the WRAPPING box (`spinnerBox` below) reserves
+ * exactly the visually-scaled footprint — a `transform` alone repaints the glyph without touching
+ * layout, which would leave `lg` overflowing a box a naive implementation still measured at 20dp.
+ */
+export const SPINNER_SIZES = {
+  sm: {
+    boxSize: 16,
+    scale: 0.8
+  },
+  md: {
+    boxSize: 20,
+    scale: 1
+  },
+  lg: {
+    boxSize: 28,
+    scale: 1.4
+  }
+};
+
+/**
+ * Maps `tone` onto ROLE colours — the reason the prop is a closed union and not `color?: string`.
+ * `accent` reads the same solid-fill rung `Button`'s solid variant uses; `neutral` is the muted
+ * foreground for secondary/inline loading states. Both are measured ≥ 3:1 (WCAG 1.4.11's
+ * "Graphical Objects" clause — a spinner is a graphical object required to understand that work is
+ * ongoing) against `bg.canvas`, `bg.surface`, AND `bg.raised` on all 8 brands × both modes — see
+ * `Spinner.test.ts`.
+ */
+export function resolveSpinnerTone(colors, tone) {
+  switch (tone) {
+    case "accent":
+      return colors.accent.solid;
+    case "neutral":
+      return colors.fg.muted;
+  }
+}
+/** A Spinner renders no visible text, so this is what AT announces absent an explicit override. */
+export const DEFAULT_SPINNER_LABEL = "Loading";
+
+/**
+ * Derives the accessibility surface once, purely, so the fallback label is testable without a
+ * renderer. There is no interaction to gate (a Spinner is never pressable) — unlike
+ * `resolveButtonAccessibility`, the only decision here is the label fallback; `busy` is always true
+ * because a mounted Spinner, by definition, means work is in progress.
+ */
+export function resolveSpinnerAccessibility(input) {
+  return {
+    accessibilityRole: "progressbar",
+    accessibilityLabel: input.accessibilityLabel ?? DEFAULT_SPINNER_LABEL,
+    accessibilityState: {
+      busy: true
+    }
+  };
+}
+
+/**
+ * The outer box's structural size — no theme dependency (the dimensions are the component's own
+ * fixed design constants, not on the theme's spacing scale), so this uses the untethered
+ * `createVariants` rather than `createThemedVariants` (the same reasoning `BUTTON_SIZES` documents
+ * for being a plain constant). Centers its child so the scaled glyph (`spinnerGlyphScale` below)
+ * sits in the middle of the reserved footprint.
+ */
+export const spinnerBox = createVariants({
+  base: {
+    alignItems: "center",
+    justifyContent: "center"
+  },
+  variants: {
+    size: {
+      sm: {
+        width: SPINNER_SIZES.sm.boxSize,
+        height: SPINNER_SIZES.sm.boxSize
+      },
+      md: {
+        width: SPINNER_SIZES.md.boxSize,
+        height: SPINNER_SIZES.md.boxSize
+      },
+      lg: {
+        width: SPINNER_SIZES.lg.boxSize,
+        height: SPINNER_SIZES.lg.boxSize
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+});
+
+/**
+ * The glyph's own visual scale, applied to the `ActivityIndicator` INSIDE `spinnerBox` — never to
+ * the box itself (one node can't both declare "I am 28dp" and "scale me 1.4×" without double-
+ * applying the enlargement). Registered once via `createVariants`, same reasoning as `spinnerBox`.
+ */
+export const spinnerGlyphScale = createVariants({
+  variants: {
+    size: {
+      sm: {
+        transform: [{
+          scale: SPINNER_SIZES.sm.scale
+        }]
+      },
+      md: {
+        transform: [{
+          scale: SPINNER_SIZES.md.scale
+        }]
+      },
+      lg: {
+        transform: [{
+          scale: SPINNER_SIZES.lg.scale
+        }]
+      }
+    }
+  },
+  defaultVariants: {
+    size: "md"
+  }
+});
+//# sourceMappingURL=Spinner.variants.js.map

package/lib/module/modules/spinner/Spinner.variants.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createVariants","SPINNER_SIZES","sm","boxSize","scale","md","lg","resolveSpinnerTone","colors","tone","accent","solid","fg","muted","DEFAULT_SPINNER_LABEL","resolveSpinnerAccessibility","input","accessibilityRole","accessibilityLabel","accessibilityState","busy","spinnerBox","base","alignItems","justifyContent","variants","size","width","height","defaultVariants","spinnerGlyphScale","transform"],"sourceRoot":"../../../../src","sources":["modules/spinner/Spinner.variants.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;;AAGA,SAASA,cAAc,QAAQ,2BAAkB;AAYjD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,aAAa,GAAG;EAC3BC,EAAE,EAAE;IAAEC,OAAO,EAAE,EAAE;IAAEC,KAAK,EAAE;EAAI,CAAC;EAC/BC,EAAE,EAAE;IAAEF,OAAO,EAAE,EAAE;IAAEC,KAAK,EAAE;EAAE,CAAC;EAC7BE,EAAE,EAAE;IAAEH,OAAO,EAAE,EAAE;IAAEC,KAAK,EAAE;EAAI;AAChC,CAAyD;;AAEzD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASG,kBAAkBA,CAACC,MAAkB,EAAEC,IAAiB,EAAU;EAChF,QAAQA,IAAI;IACV,KAAK,QAAQ;MACX,OAAOD,MAAM,CAACE,MAAM,CAACC,KAAK;IAC5B,KAAK,SAAS;MACZ,OAAOH,MAAM,CAACI,EAAE,CAACC,KAAK;EAC1B;AACF;AAYA;AACA,OAAO,MAAMC,qBAAqB,GAAG,SAAS;;AAE9C;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,2BAA2BA,CACzCC,KAAgC,EACL;EAC3B,OAAO;IACLC,iBAAiB,EAAE,aAAa;IAChCC,kBAAkB,EAAEF,KAAK,CAACE,kBAAkB,IAAIJ,qBAAqB;IACrEK,kBAAkB,EAAE;MAAEC,IAAI,EAAE;IAAK;EACnC,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,UAAU,GAAGrB,cAAc,CAAC;EACvCsB,IAAI,EAAE;IAAEC,UAAU,EAAE,QAAQ;IAAEC,cAAc,EAAE;EAAS,CAAC;EACxDC,QAAQ,EAAE;IACRC,IAAI,EAAE;MACJxB,EAAE,EAAE;QAAEyB,KAAK,EAAE1B,aAAa,CAACC,EAAE,CAACC,OAAO;QAAEyB,MAAM,EAAE3B,aAAa,CAACC,EAAE,CAACC;MAAQ,CAAC;MACzEE,EAAE,EAAE;QAAEsB,KAAK,EAAE1B,aAAa,CAACI,EAAE,CAACF,OAAO;QAAEyB,MAAM,EAAE3B,aAAa,CAACI,EAAE,CAACF;MAAQ,CAAC;MACzEG,EAAE,EAAE;QAAEqB,KAAK,EAAE1B,aAAa,CAACK,EAAE,CAACH,OAAO;QAAEyB,MAAM,EAAE3B,aAAa,CAACK,EAAE,CAACH;MAAQ;IAC1E;EACF,CAAC;EACD0B,eAAe,EAAE;IAAEH,IAAI,EAAE;EAAK;AAChC,CAAC,CAAC;;AAEF;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMI,iBAAiB,GAAG9B,cAAc,CAAC;EAC9CyB,QAAQ,EAAE;IACRC,IAAI,EAAE;MACJxB,EAAE,EAAE;QAAE6B,SAAS,EAAE,CAAC;UAAE3B,KAAK,EAAEH,aAAa,CAACC,EAAE,CAACE;QAAM,CAAC;MAAE,CAAC;MACtDC,EAAE,EAAE;QAAE0B,SAAS,EAAE,CAAC;UAAE3B,KAAK,EAAEH,aAAa,CAACI,EAAE,CAACD;QAAM,CAAC;MAAE,CAAC;MACtDE,EAAE,EAAE;QAAEyB,SAAS,EAAE,CAAC;UAAE3B,KAAK,EAAEH,aAAa,CAACK,EAAE,CAACF;QAAM,CAAC;MAAE;IACvD;EACF,CAAC;EACDyB,eAAe,EAAE;IAAEH,IAAI,EAAE;EAAK;AAChC,CAAC,CAAC","ignoreList":[]}

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

@@ -0,0 +1,11 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/spinner`. Value exports and type exports are split for
+ * `verbatimModuleSyntax`, mirroring `button/index.ts`. The resolvers (`resolveSpinnerTone`,
+ * `SPINNER_SIZES`, …) stay internal — a consumer configures a Spinner through its props only. No
+ * `icon` prop, so unlike `button/index.ts` there is no `IconName` re-export.
+ */
+
+export { Spinner } from "./Spinner.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["Spinner"],"sourceRoot":"../../../../src","sources":["modules/spinner/index.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,OAAO,QAAQ,cAAW","ignoreList":[]}