pixelize-native-library 1.0.6

package/lib/module/modules/empty-state/EmptyState.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["memo","StyleSheet","Text","View","Icon","useTheme","Button","EMPTY_STATE_ICON_SIZE","emptyStateStructure","resolveEmptyStateColors","jsx","_jsx","jsxs","_jsxs","ICON_STROKE","EmptyState","icon","title","description","action","style","testID","theme","colors","children","undefined","accessibilityElementsHidden","importantForAccessibility","name","size","color","strokeWidth","fontStyleForWeight","fontWeights","bold","styles","text","fontSize","fontSizes","lg","sm","label","onPress","tone","variant","create","textAlign"],"sourceRoot":"../../../../src","sources":["modules/empty-state/EmptyState.tsx"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,IAAI,QAAQ,OAAO;AAC5B,SAASC,UAAU,EAAEC,IAAI,EAAEC,IAAI,QAAQ,cAAc;AAErD,SAASC,IAAI,QAAQ,0BAAiB;AAGtC,SAASC,QAAQ,QAAQ,sBAAa;AACtC,SAASC,MAAM,QAAQ,oBAAW;AAElC,SAASC,qBAAqB,EAAEC,mBAAmB,EAAEC,uBAAuB,QAAQ,0BAAuB;AAAC,SAAAC,GAAA,IAAAC,IAAA,EAAAC,IAAA,IAAAC,KAAA;AAiB5G;AACA;AACA,MAAMC,WAAW,GAAG,GAAG;AAEvB,OAAO,MAAMC,UAAU,gBAAGf,IAAI,CAAC,SAASe,UAAUA,CAAC;EACjDC,IAAI;EACJC,KAAK;EACLC,WAAW;EACXC,MAAM;EACNC,KAAK;EACLC;AACe,CAAC,EAAE;EAClB,MAAMC,KAAK,GAAGjB,QAAQ,CAAC,CAAC;EACxB,MAAMkB,MAAM,GAAGd,uBAAuB,CAACa,KAAK,CAACC,MAAM,CAAC;EAEpD,oBACEV,KAAA,CAACV,IAAI;IAACkB,MAAM,EAAEA,MAAO;IAACD,KAAK,EAAE,CAACZ,mBAAmB,CAACc,KAAK,CAAC,EAAEF,KAAK,CAAE;IAAAI,QAAA,GAC9DR,IAAI,KAAKS,SAAS;IAAA;IACjB;IACA;IACA;IACAd,IAAA,CAACR,IAAI;MACHkB,MAAM,EAAEA,MAAM,KAAKI,SAAS,GAAGA,SAAS,GAAG,GAAGJ,MAAM,OAAQ;MAC5DK,2BAA2B;MAC3BC,yBAAyB,EAAC,qBAAqB;MAAAH,QAAA,eAE/Cb,IAAA,CAACP,IAAI;QAACwB,IAAI,EAAEZ,IAAK;QAACa,IAAI,EAAEtB,qBAAsB;QAACuB,KAAK,EAAEP,MAAM,CAACP,IAAK;QAACe,WAAW,EAAEjB;MAAY,CAAE;IAAC,CAC3F,CACP,eACDH,IAAA,CAACT,IAAI;MACHkB,KAAK,EAAE,CACLE,KAAK,CAACU,kBAAkB,CAACV,KAAK,CAACW,WAAW,CAACC,IAAI,CAAC,EAChDC,MAAM,CAACC,IAAI,EACX;QAAEC,QAAQ,EAAEf,KAAK,CAACgB,SAAS,CAACC,EAAE;QAAET,KAAK,EAAEP,MAAM,CAACN;MAAM,CAAC,CACrD;MAAAO,QAAA,EAEDP;IAAK,CACF,CAAC,EACNC,WAAW,KAAKO,SAAS,iBACxBd,IAAA,CAACT,IAAI;MAACkB,KAAK,EAAE,CAACe,MAAM,CAACC,IAAI,EAAE;QAAEC,QAAQ,EAAEf,KAAK,CAACgB,SAAS,CAACE,EAAE;QAAEV,KAAK,EAAEP,MAAM,CAACL;MAAY,CAAC,CAAE;MAAAM,QAAA,EACrFN;IAAW,CACR,CACP,EACAC,MAAM,KAAKM,SAAS,iBACnBd,IAAA,CAACL,MAAM;MAACmC,KAAK,EAAEtB,MAAM,CAACsB,KAAM;MAACC,OAAO,EAAEvB,MAAM,CAACuB,OAAQ;MAACC,IAAI,EAAC,QAAQ;MAACC,OAAO,EAAC;IAAO,CAAE,CACtF;EAAA,CACG,CAAC;AAEX,CAAC,CAAC;AAEF,MAAMT,MAAM,GAAGlC,UAAU,CAAC4C,MAAM,CAAC;EAC/BT,IAAI,EAAE;IAAEU,SAAS,EAAE;EAAS;AAC9B,CAAC,CAAC","ignoreList":[]}

package/lib/module/modules/empty-state/EmptyState.variants.js

@@ -0,0 +1,54 @@
+"use strict";
+
+/**
+ * EmptyState's style resolution — same split as `Card.variants` / `Divider.variants`:
+ *  - STRUCTURE (centring, padding, the vertical rhythm between icon / title / description /
+ *    action) lives in the themed `emptyStateStructure` resolver, static per (brand, mode),
+ *    registered once via `StyleSheet.create`. There is no `variant`/`size`/`tone` to select
+ *    between — one visual identity, same reasoning `Divider`/`Avatar` give for their own single
+ *    identity.
+ *  - COLOUR is resolved from the theme's ROLE colours by `resolveEmptyStateColors`, never a raw
+ *    ramp and never a hardcoded hex.
+ *
+ * Free of React and lucide, so the WCAG test imports this directly (mocking only `react-native`'s
+ * `StyleSheet`, as `core/style` and every sibling module's tests do).
+ */
+
+import { createThemedVariants } from "../../core/style/index.js";
+
+/**
+ * The icon glyph's rendered size, in dp. A component design constant — same status `Button`'s
+ * `ICON_STROKE` / `BUTTON_SIZES.*.iconSize` have — not on the theme's numeric scale: EmptyState
+ * takes no `size` prop, so there is exactly one icon size, deliberately large since it is the
+ * focal point of an otherwise mostly-empty layout.
+ */
+export const EMPTY_STATE_ICON_SIZE = 48;
+/**
+ * Maps EmptyState onto the theme's role colours. No `tone`/`color` prop to widen — every colour
+ * this component can show is one of these role lookups (same reasoning as `Divider`/`Avatar`), so
+ * it inverts light↔dark for free and can never be an off-palette value an app invented.
+ */
+export function resolveEmptyStateColors(colors) {
+  return {
+    icon: colors.fg.muted,
+    title: colors.fg.default,
+    description: colors.fg.muted
+  };
+}
+
+/**
+ * Structural styles only — centring, padding, and the vertical rhythm between children. No
+ * colours (those are resolved separately and applied inline over this) and no closed union to
+ * select, so this compiles once per theme identity via the `WeakMap`-cached themed resolver and
+ * never rebuilds per render.
+ */
+export const emptyStateStructure = createThemedVariants(theme => ({
+  base: {
+    alignItems: "center",
+    justifyContent: "center",
+    paddingHorizontal: theme.space[6],
+    paddingVertical: theme.space[8],
+    rowGap: theme.space[3]
+  }
+}));
+//# sourceMappingURL=EmptyState.variants.js.map

package/lib/module/modules/empty-state/EmptyState.variants.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createThemedVariants","EMPTY_STATE_ICON_SIZE","resolveEmptyStateColors","colors","icon","fg","muted","title","default","description","emptyStateStructure","theme","base","alignItems","justifyContent","paddingHorizontal","space","paddingVertical","rowGap"],"sourceRoot":"../../../../src","sources":["modules/empty-state/EmptyState.variants.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA,SAASA,oBAAoB,QAAQ,2BAAkB;;AAEvD;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,qBAAqB,GAAG,EAAE;AAWvC;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,uBAAuBA,CAACC,MAAkB,EAAoB;EAC5E,OAAO;IACLC,IAAI,EAAED,MAAM,CAACE,EAAE,CAACC,KAAK;IACrBC,KAAK,EAAEJ,MAAM,CAACE,EAAE,CAACG,OAAO;IACxBC,WAAW,EAAEN,MAAM,CAACE,EAAE,CAACC;EACzB,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMI,mBAAmB,GAAGV,oBAAoB,CAAEW,KAAY,KAAM;EACzEC,IAAI,EAAE;IACJC,UAAU,EAAE,QAAQ;IACpBC,cAAc,EAAE,QAAQ;IACxBC,iBAAiB,EAAEJ,KAAK,CAACK,KAAK,CAAC,CAAC,CAAC;IACjCC,eAAe,EAAEN,KAAK,CAACK,KAAK,CAAC,CAAC,CAAC;IAC/BE,MAAM,EAAEP,KAAK,CAACK,KAAK,CAAC,CAAC;EACvB;AACF,CAAC,CAAC,CAAC","ignoreList":[]}

package/lib/module/modules/empty-state/MODULE.md

@@ -0,0 +1,78 @@
+# empty-state/ — a centred placeholder for "nothing here yet" / zero-result states
+
+`EmptyState` groups an optional decorative icon, a required title, an optional description, and an
+optional call-to-action into one centred column. It takes no closed union of its own — one visual
+identity, same reasoning `Divider`/`Avatar` give for theirs.
+
+## Files
+
+| File | Role |
+|------|------|
+| `EmptyState.tsx` | The component. Resolves role colours + the themed structural style, composes the optional icon/description/action, `style` last. |
+| `EmptyState.variants.ts` | Pure resolver (`resolveEmptyStateColors`) + the themed structural variant resolver `emptyStateStructure` + the `EMPTY_STATE_ICON_SIZE` constant. No React, no lucide. |
+| `index.ts` | Public surface: `EmptyState`, `EmptyStateProps`, `EmptyStateAction`, `IconName` (re-exported from `core/icon`). |
+| `__tests__/EmptyState.test.ts` | Pure: WCAG 1.4.3 (title + description, all brands × modes), the icon's 3:1 non-text floor, the colour-mapping contract, `EMPTY_STATE_ICON_SIZE`. |
+| `__tests__/EmptyState.render.test.tsx` | Render: title/description compose, `testID` forwards, icon absent vs. hidden-from-AT, the composed action `Button` fires `onPress` and carries its label as the accessible name, consumer `style` applies last. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `icon` | `IconName` | — | A NAME from the closed 22-name catalogue, never a `ReactNode`. Decorative — hidden from assistive tech. |
+| `title` | `string` | — | Required. Rendered bold, `fg.default`, centred. |
+| `description` | `string` | — | Optional. Rendered `fg.muted`, centred, below the title. |
+| `action` | `{ label: string; onPress: () => void }` | — | Optional. Rendered via this library's own `Button` (`tone="accent" variant="solid"`) — a justified composition, same reasoning `AlertDialog` documents for its own footer buttons. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+| `testID` | `string` | — | Forwarded to the outermost `View`; the icon wrapper (when rendered) gets `${testID}-icon`. |
+
+`EmptyState` has no `variant`/`size`/`tone` — there is exactly one visual identity, so there is
+nothing to close a union over (same reasoning `Card`'s single-background siblings `Divider` and
+`Avatar` give for their own props that take no appearance union).
+
+## Why the action composes `Button` instead of a hand-rolled `Pressable`
+
+A call-to-action is a real interactive control — it needs press/focus feedback, a 44dp touch
+target, and disabled/busy affordances if the app ever needs them. Reimplementing that here would
+duplicate `Button`'s tested wiring for no benefit, so `EmptyState` imports the stable `../button`
+module and renders it with `tone="accent" variant="solid"`, matching `AlertDialog`'s footer-button
+composition and `Select`'s reuse of stable siblings.
+
+## Accessibility contract (WCAG)
+
+- **No `accessibilityRole` of its own.** Like `Card`, this is a plain grouping container — the
+  title and description read as their own `Text` elements, in document order, and the composed
+  `Button` carries its own role/state. There is nothing here for assistive tech to announce beyond
+  its children.
+- **Icon is decorative.** Redundant with the visible title, so its wrapper carries
+  `accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"` — the same
+  contract `Avatar`/`Skeleton` give their own decorative default — rather than being announced as
+  a second, unexplained element.
+- **1.4.3** — the title and description both clear ≥ 4.5:1 against `bg.canvas`, measured for all 8
+  brands × both modes (`EmptyState.test.ts`).
+- **1.4.11 / icon** — N/A: the icon is hidden from assistive tech, so 1.4.11 does not bind it
+  (same reasoning `Divider.test.ts` documents for its own decorative colour). Its ≥ 3:1 floor
+  against `bg.canvas` is still measured anyway, so a future edit can't silently regress it to
+  something illegible for sighted users.
+- **2.3.3 (reduced motion)** — N/A. `EmptyState` has no animation of its own; the composed
+  `Button` handles its own press-fade suppression.
+- **Touch target (2.5.x)** — N/A for `EmptyState` itself (not interactive); the composed `Button`
+  meets its own 44dp floor.
+
+## Patterns copied from `button/` (the reference module)
+
+1. **Structure vs colour split.** Static/theme-numeric structure (padding, the vertical rhythm
+   between icon/title/description/action) → `createThemedVariants` (registered once per theme).
+   Colour → resolved from role tokens by `resolveEmptyStateColors`, applied inline.
+2. **Pure, testable resolver** in `EmptyState.variants.ts` (no React/lucide) so the WCAG contract
+   is unit-tested by measuring real palettes — never eyeballed.
+3. **`icon` as a NAME**, `style: LayoutStyle` last and once, no `{...rest}`, internals never
+   receive consumer style.
+4. **Justified composition of a stable sibling** (`Button`), not a re-implementation.
+
+## Known gaps
+
+None — no new 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`). Its one library child, `Button`, receives `action.label`/`action.onPress` straight from the consumer's own `action` object, not a freshly-derived closure — nothing to memoize.

package/lib/module/modules/empty-state/index.js

@@ -0,0 +1,13 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/empty-state`. Value exports and type exports are split
+ * for `verbatimModuleSyntax`. The style/colour resolvers (`resolveEmptyStateColors`,
+ * `emptyStateStructure`) stay internal — a consumer configures an EmptyState through its props,
+ * never by importing its internals.
+ */
+
+export { EmptyState } from "./EmptyState.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/empty-state/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["EmptyState"],"sourceRoot":"../../../../src","sources":["modules/empty-state/index.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,UAAU,QAAQ,iBAAc;;AAGzC","ignoreList":[]}

package/lib/module/modules/file-upload/FileUpload.js

@@ -0,0 +1,132 @@
+"use strict";
+
+/**
+ * FileUpload — a trigger `Button` that opens a native picker and reports the picked LOCAL file back
+ * through the controlled `onChange`. No network upload logic lives here: turning the returned `uri`
+ * into a real upload is the consumer's job.
+ *
+ * The first module in this library with a genuine native-picker dependency. `expo-image-picker`/
+ * `expo-document-picker` are optional peers (see package.json) imported PLAIN at the top of
+ * `FileUpload.variants.ts` — the established `core/icon` pattern for an optional-peer native
+ * dependency (no lazy-loading gymnastics): per-component subpath exports already mean this module's
+ * code, and everything it imports, loads only when a consumer imports `pixelize-native-library/file-upload`
+ * at all. Because the import is unconditional, a consumer needs BOTH packages installed even if they
+ * only ever pass `source="document"` in their app — the same tradeoff `core/icon` already makes for
+ * `lucide-react-native` + `react-native-svg` (a Button that renders no icon still requires both).
+ *
+ * Composes the library's own `Button` for BOTH interactive elements (the trigger AND the "remove"
+ * control) rather than hand-rolling a `Pressable` — see MODULE.md "Why this module has no colour
+ * resolver" for why that's a deliberate departure from every sibling module's structure/colour split.
+ */
+
+import { memo, useCallback, useState } from "react";
+import { StyleSheet, Text, View } from "react-native";
+import { useTheme } from "../../theme/index.js";
+import { Button } from "../button/index.js";
+import { FILE_UPLOAD_PICK_ERROR_MESSAGE, fileUploadContainerStructure, fileUploadRowStructure, pickDocumentFile, pickImageFile, resolveFileUploadRemoveLabel, resolveFileUploadTriggerLabel } from "./FileUpload.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export const FileUpload = /*#__PURE__*/memo(function FileUpload(props) {
+  const {
+    source,
+    label,
+    value = null,
+    onChange,
+    size = "md",
+    disabled = false,
+    allowedMimeTypes,
+    allowsEditing = false,
+    style,
+    testID
+  } = props;
+  const theme = useTheme();
+  // Distinct from `value`: a pick attempt can fail (denied permission, or any other native error)
+  // independently of whether a file was already selected — see `openPicker`'s catch block.
+  const [pickError, setPickError] = useState(false);
+  const openPicker = useCallback(async () => {
+    if (disabled) return;
+    setPickError(false);
+    try {
+      const picked = source === "image" ? await pickImageFile(allowsEditing) : await pickDocumentFile(allowedMimeTypes);
+      // `picked` is `null` for a user cancel too — `onChange` must not fire then, or a voluntary
+      // "never mind" would wipe out whatever was already selected.
+      if (picked) onChange(picked);
+    } catch (error) {
+      // A rejection (denied/undetermined permission, or any other native failure) is the one case
+      // that DOES clear the value — the pick attempt genuinely failed, so the field can't claim to
+      // still hold whatever was selected before. Never crashes, never swallowed silently: the error
+      // row below announces it, and — mirroring `PixelizeProvider`'s own dev-warning convention,
+      // the only console usage in this codebase — a console warning names the likely cause for the
+      // developer. Gated the identical way: skipped only when `__DEV__` is DEFINITELY false.
+      onChange(null);
+      setPickError(true);
+      const isDefinitelyProd = typeof __DEV__ !== "undefined" && !__DEV__;
+      if (!isDefinitelyProd) {
+        console.warn("[pixelize-native-library] <FileUpload> couldn't open the picker — likely a denied " + "permission or missing platform config (Info.plist / AndroidManifest usage strings).", error);
+      }
+    }
+  }, [disabled, source, allowsEditing, allowedMimeTypes, onChange]);
+
+  // Stable wrapper so `Button`'s `onPress` reference doesn't churn every render — `openPicker`
+  // itself is async and can't be passed directly (the promise must be discarded).
+  const handlePick = useCallback(() => {
+    void openPicker();
+  }, [openPicker]);
+  const handleRemove = useCallback(() => {
+    setPickError(false);
+    onChange(null);
+  }, [onChange]);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: [fileUploadContainerStructure(theme), style],
+    children: [/*#__PURE__*/_jsx(Button, {
+      label: label,
+      icon: "upload",
+      onPress: handlePick,
+      disabled: disabled,
+      size: size,
+      accessibilityLabel: resolveFileUploadTriggerLabel(label, value),
+      testID: testID ? `${testID}-trigger` : undefined
+    }), value && /*#__PURE__*/_jsxs(View, {
+      testID: testID ? `${testID}-row` : undefined,
+      style: [fileUploadRowStructure(theme), {
+        borderColor: theme.colors.border.interactive,
+        backgroundColor: theme.colors.bg.surface
+      }],
+      children: [/*#__PURE__*/_jsx(Text, {
+        numberOfLines: 1,
+        style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
+          flex: 1,
+          fontSize: theme.fontSizes.md,
+          color: theme.colors.fg.default
+        }, disabled && styles.dimmedText],
+        children: value.name
+      }), /*#__PURE__*/_jsx(Button, {
+        icon: "trash",
+        accessibilityLabel: resolveFileUploadRemoveLabel(value.name),
+        onPress: handleRemove,
+        disabled: disabled,
+        size: "sm",
+        variant: "ghost",
+        tone: "neutral",
+        testID: testID ? `${testID}-remove` : undefined
+      })]
+    }), pickError && /*#__PURE__*/_jsx(Text, {
+      accessibilityLiveRegion: "polite",
+      style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
+        fontSize: theme.fontSizes.xs,
+        color: theme.colors.status.danger.text
+      }],
+      children: FILE_UPLOAD_PICK_ERROR_MESSAGE
+    })]
+  });
+});
+const styles = StyleSheet.create({
+  // A disabled control is exempt from the contrast minimum (WCAG 1.4.3) — same uniform dim every
+  // other module uses. Scoped to the filename `Text` alone, not the row: the row's own `Button`
+  // (remove) already dims itself when `disabled`, so dimming the row's container too would compound
+  // both opacities on that button.
+  dimmedText: {
+    opacity: 0.5
+  }
+});
+//# sourceMappingURL=FileUpload.js.map

package/lib/module/modules/file-upload/FileUpload.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["memo","useCallback","useState","StyleSheet","Text","View","useTheme","Button","FILE_UPLOAD_PICK_ERROR_MESSAGE","fileUploadContainerStructure","fileUploadRowStructure","pickDocumentFile","pickImageFile","resolveFileUploadRemoveLabel","resolveFileUploadTriggerLabel","jsx","_jsx","jsxs","_jsxs","FileUpload","props","source","label","value","onChange","size","disabled","allowedMimeTypes","allowsEditing","style","testID","theme","pickError","setPickError","openPicker","picked","error","isDefinitelyProd","__DEV__","console","warn","handlePick","handleRemove","children","icon","onPress","accessibilityLabel","undefined","borderColor","colors","border","interactive","backgroundColor","bg","surface","numberOfLines","fontStyleForWeight","fontWeights","regular","flex","fontSize","fontSizes","md","color","fg","default","styles","dimmedText","name","variant","tone","accessibilityLiveRegion","xs","status","danger","text","create","opacity"],"sourceRoot":"../../../../src","sources":["modules/file-upload/FileUpload.tsx"],"mappings":"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","ignoreList":[]}

package/lib/module/modules/file-upload/FileUpload.variants.js

@@ -0,0 +1,179 @@
+"use strict";
+
+/**
+ * FileUpload's pure logic: the native-picker calls, the raw-result → `FileUploadResult` mapping,
+ * the accessible-name derivation, and the structural resolvers.
+ *
+ * This is the one module in the library whose "pure" file is NOT free of a native runtime import —
+ * every sibling's `*.variants.ts` header says "free of React and of any native/lucide import"
+ * because that module owns no native call of its own. FileUpload does: `pickImageFile`/
+ * `pickDocumentFile` call `expo-image-picker`/`expo-document-picker` directly, PLAIN top-level
+ * imports (no lazy-loading), the same established pattern `core/icon` uses for its optional-peer
+ * native deps. Colocating the call with its own result-mapping keeps both testable the same way —
+ * `FileUpload.test.ts` mocks the two packages at the module level and asserts on the real call
+ * (options forwarded, cancel vs success vs rejection) — rather than splitting "call" (untestable
+ * without mounting) from "map" (pure) across files. Both packages are already mandatory peers for
+ * this subpath regardless of which `source` a given instance uses (see `FileUpload.tsx`'s header),
+ * so this adds no new install requirement.
+ *
+ * Free of React, so this file (and `FileUpload.test.ts`) never needs `@testing-library/react-native`
+ * — only `react-native`'s `StyleSheet` is mocked to identity, same as every sibling's pure test.
+ */
+
+import * as DocumentPicker from "expo-document-picker";
+import * as ImagePicker from "expo-image-picker";
+import { createThemedVariants } from "../../core/style/index.js";
+/** Shown below the control when a pick attempt fails outright (see `FileUpload.tsx`'s `openPicker`). */
+export const FILE_UPLOAD_PICK_ERROR_MESSAGE = "Couldn't open the picker. Check that photo or file access is allowed, then try again.";
+
+/**
+ * Falls back to the URI's last path segment when a picker doesn't supply a name —
+ * `ImagePickerAsset.fileName` can be `null` "when the name is unavailable or the user gave limited
+ * permission to access the media library" (its own doc comment). Strips a query/fragment first (a
+ * content:// or blob-style URI can carry one), then decodes percent-escapes so the displayed name
+ * reads like a normal filename instead of `my%20photo.jpg`.
+ */
+export function fileNameFromUri(uri) {
+  const withoutQuery = uri.split(/[?#]/)[0] ?? uri;
+  const segments = withoutQuery.split("/");
+  const last = segments[segments.length - 1];
+  if (!last) return uri;
+  try {
+    return decodeURIComponent(last);
+  } catch {
+    // A malformed percent-escape (rare, but `decodeURIComponent` throws on one) — the raw segment
+    // is still a usable, if unprettified, name; never let a display-name fallback itself crash.
+    return last;
+  }
+}
+
+/**
+ * Maps `ImagePicker.launchImageLibraryAsync`'s result onto the public shape. `null` for a user
+ * cancellation (`canceled: true`) AND, defensively, for an empty `assets` array — the type allows
+ * it even though a single, non-multi-select call should never resolve that way. The caller (`
+ * FileUpload.tsx`) is the one that decides what a `null` MEANS (cancel → leave `value` alone,
+ * reject → clear it) by checking `result.canceled` itself; this function only normalizes the shape.
+ */
+export function resolveImagePickResult(result) {
+  if (result.canceled) return null;
+  const asset = result.assets[0];
+  if (!asset) return null;
+  return {
+    uri: asset.uri,
+    name: asset.fileName ?? fileNameFromUri(asset.uri),
+    size: asset.fileSize,
+    mimeType: asset.mimeType
+  };
+}
+
+/** Maps `DocumentPicker.getDocumentAsync`'s result onto the public shape — same `canceled`/empty-array handling as `resolveImagePickResult`. `DocumentPickerAsset.name` is always present, so no filename fallback is needed. */
+export function resolveDocumentPickResult(result) {
+  if (result.canceled) return null;
+  const asset = result.assets[0];
+  if (!asset) return null;
+  return {
+    uri: asset.uri,
+    name: asset.name,
+    size: asset.size,
+    mimeType: asset.mimeType
+  };
+}
+
+/**
+ * Opens the OS media-library picker and returns the normalized result, or `null` on cancel.
+ *
+ * Deliberately calls NO permission API first. Read directly from the installed `expo-image-picker`
+ * (v57)'s own native source: `launchImageLibraryAsync` with the default (non-editing) options never
+ * touches the media-library permission requester at all on either platform —
+ * `ImagePickerModule.swift`'s `launchImageLibraryAsync` goes straight to `launchMultiSelectPicker`
+ * (`PHPickerViewController`, permission-less by OS design) whenever `allowsEditing` is false, and
+ * `ImagePickerModule.kt`'s `launchImageLibraryAsync` never calls its permission helper either
+ * (unlike `launchCameraAsync`, which explicitly does on both platforms). So the "modern
+ * limited-access picker flow doesn't require an explicit permission request" is not a guess here —
+ * it's what the native module actually does for this call shape.
+ *
+ * `allowsEditing: true` is the one case that's genuinely uncertain: it routes iOS through the
+ * LEGACY `UIImagePickerController`, which (per Apple's own OS behaviour, outside this module's
+ * code) can trigger the native photo-library permission prompt on first use — see the "Known gaps"
+ * note in MODULE.md. Either way, this function does not special-case it: a rejection (denied
+ * permission, or any other native failure) simply propagates to the caller, which is the ONE place
+ * — `FileUpload.tsx`'s `openPicker` — that decides how to surface it (clear `value`, show the
+ * error row, warn in dev). A `canceled: true` resolution and a thrown rejection are the two
+ * possible "nothing was picked" outcomes; this function does not conflate them.
+ */
+export async function pickImageFile(allowsEditing) {
+  const result = await ImagePicker.launchImageLibraryAsync({
+    allowsEditing
+  });
+  return resolveImagePickResult(result);
+}
+
+/**
+ * Opens the OS document picker and returns the normalized result, or `null` on cancel.
+ * `expo-document-picker` exposes no permission API whatsoever — it's backed by the platform's own
+ * file-picker UI (iOS Files / Android Storage Access Framework), which is inherently
+ * permission-less: the user grants access to the one file they pick, not to a library.
+ */
+export async function pickDocumentFile(allowedMimeTypes) {
+  const result = await DocumentPicker.getDocumentAsync({
+    type: allowedMimeTypes
+  });
+  return resolveDocumentPickResult(result);
+}
+
+/**
+ * The trigger Button's accessible name — folds in the current selection so a screen-reader user
+ * learns the state without needing to reach the separate "selected file" row. Reuses Button's own
+ * `accessibilityLabel` prop (never a second, parallel a11y mechanism) — see MODULE.md.
+ */
+export function resolveFileUploadTriggerLabel(label, value) {
+  return value ? `${label}. Selected: ${value.name}` : label;
+}
+
+/**
+ * The remove control's accessible name — one announcement naming BOTH the target and the action,
+ * matching how a screen reader should read a removable chip (e.g. "Selected file: report.pdf,
+ * remove"). The filename `Text` next to it is decorative (hidden from the accessibility tree, same
+ * reasoning as `Input.tsx`'s visible label), so this is the only place that name reaches AT.
+ */
+export function resolveFileUploadRemoveLabel(fileName) {
+  return `Selected file: ${fileName}, remove`;
+}
+
+/**
+ * Root container — a vertical stack with a gap between the trigger, the optional "selected file"
+ * row, and the optional error message. `alignSelf: "flex-start"` is a deliberate, explicit default
+ * (not an omission): unlike `Select`/`MultiSelect`, which force `alignSelf: "stretch"` because they
+ * ARE an Input-box replica meant to span a form row, FileUpload's trigger is a plain `Button` (which
+ * hugs its own content width) — hard-coding a predictable "hug content" default here, rather than
+ * silently inheriting whatever `alignItems` the parent happens to have, means a consumer who DOES
+ * want it to span a row opts in explicitly via `style={{ alignSelf: "stretch" }}` (a `LayoutStyle`
+ * key), instead of the result depending on ambient parent layout.
+ */
+export const fileUploadContainerStructure = createThemedVariants(theme => ({
+  base: {
+    alignSelf: "flex-start",
+    rowGap: theme.space[2]
+  }
+}));
+
+/**
+ * The "selected file" row — a bordered chip below the trigger. `border.interactive`, NOT the
+ * decorative `border.default`: `Card.variants.ts` documents `border.default` as measuring
+ * ~1.0–1.4:1 against `bg.surface` on every brand × mode — nowhere near a legible boundary. This row
+ * is a real UI grouping (WCAG 1.4.11), so it makes the identical substitution `Card`'s `outline`
+ * variant and `Button`'s `outline` variant both make, for the identical reason — measured against
+ * `bg.canvas` in `FileUpload.test.ts`, the same backdrop `Card.test.ts` uses for its own border.
+ */
+export const fileUploadRowStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    columnGap: theme.space[2],
+    borderWidth: theme.borderWidths.thin,
+    borderRadius: theme.radii.base,
+    paddingHorizontal: theme.space[3],
+    paddingVertical: theme.space[2]
+  }
+}));
+//# sourceMappingURL=FileUpload.variants.js.map

package/lib/module/modules/file-upload/FileUpload.variants.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DocumentPicker","ImagePicker","createThemedVariants","FILE_UPLOAD_PICK_ERROR_MESSAGE","fileNameFromUri","uri","withoutQuery","split","segments","last","length","decodeURIComponent","resolveImagePickResult","result","canceled","asset","assets","name","fileName","size","fileSize","mimeType","resolveDocumentPickResult","pickImageFile","allowsEditing","launchImageLibraryAsync","pickDocumentFile","allowedMimeTypes","getDocumentAsync","type","resolveFileUploadTriggerLabel","label","value","resolveFileUploadRemoveLabel","fileUploadContainerStructure","theme","base","alignSelf","rowGap","space","fileUploadRowStructure","flexDirection","alignItems","columnGap","borderWidth","borderWidths","thin","borderRadius","radii","paddingHorizontal","paddingVertical"],"sourceRoot":"../../../../src","sources":["modules/file-upload/FileUpload.variants.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/modules/file-upload/MODULE.md

@@ -0,0 +1,130 @@
+# file-upload/ — a trigger Button that opens a native image/document picker
+
+`FileUpload` opens `expo-image-picker`'s `launchImageLibraryAsync` (`source="image"`) or
+`expo-document-picker`'s `getDocumentAsync` (`source="document"`) and reports the picked LOCAL file
+back through the controlled `onChange`. No network upload logic lives here — turning the returned
+`uri` into a real upload is the consumer's job. First module with a genuine native-picker dependency,
+and the first that composes a sibling module (`Button`) instead of hand-rolling its own `Pressable`.
+
+## Files
+
+| File | Role |
+|------|------|
+| `FileUpload.tsx` | The component. Composes `Button` for BOTH the trigger and the "remove" control; owns the `pickError` state and the try/catch around the pick attempt. |
+| `FileUpload.variants.ts` | The native-picker calls (`pickImageFile`, `pickDocumentFile`), the raw-result → `FileUploadResult` mappers, `fileNameFromUri`, the accessible-name resolvers, and the structural resolvers. Free of React, but — deliberately, unlike every sibling — NOT free of a native runtime import (see below). |
+| `index.ts` | Public surface: `FileUpload`, `FileUploadProps`, `FileUploadResult`, `FileUploadSource`, `FileUploadSize`. |
+| `__tests__/FileUpload.test.ts` | Pure: the native-picker calls (mocked `expo-image-picker`/`expo-document-picker`), result-mapping, `fileNameFromUri`, accessible-name resolvers, WCAG contrast (all brands × modes). |
+| `__tests__/FileUpload.render.test.tsx` | Render: trigger press → picker → `onChange`, cancel leaves `value` untouched, the "selected file" row + remove control, `disabled`, a pick failure's error row + dev warning, `style` application. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `source` | `"image" \| "document"` | — | Required, closed union — which native picker this instance uses. |
+| `label` | `string` | — | Required. Trigger's visible label (e.g. `"Upload photo"`). Constant regardless of selection — pressing it again re-opens the picker and replaces the file; the "selected file" row communicates state, not the label. |
+| `value` | `FileUploadResult \| null` | — | Controlled — the currently selected file, or none. |
+| `onChange` | `(result: FileUploadResult \| null) => void` | — | Required. See "Three `onChange` outcomes" below. |
+| `size` | `sm \| md \| lg` | `md` | Forwarded straight to the trigger `Button`'s own `size`. |
+| `disabled` | `boolean` | `false` | Forwarded to both `Button`s (trigger and remove). |
+| `allowedMimeTypes` | `string[]` | — | Document-only — forwarded as `DocumentPicker.getDocumentAsync`'s `type`. Ignored when `source` is `"image"`. |
+| `allowsEditing` | `boolean` | `false` | Image-only — forwarded as `ImagePicker.launchImageLibraryAsync`'s `allowsEditing`. Ignored when `source` is `"document"`. `false` keeps the default permission-less picker flow — see "Permissions." |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last — the root `View` is the outermost node. |
+| `testID` | `string` | — | Roots `${testID}-trigger`, `${testID}-row`, `${testID}-remove`. |
+
+`FileUploadResult`: `{ uri: string; name: string; size?: number; mimeType?: string }`.
+
+## Three `onChange` outcomes
+
+| Outcome | `onChange` called? | Why |
+|---|---|---|
+| User picks a file | Yes, with the mapped result | Normal path. |
+| User cancels the picker | **No** | A voluntary "never mind" must not wipe out whatever was already selected. |
+| Remove control pressed | Yes, with `null` | Explicit clear. |
+| Pick attempt rejects (denied permission or any other native error) | Yes, with `null` | The attempt genuinely failed, so the field can't claim to still hold the prior selection. Also sets `pickError` (an error row + dev warning — see "Permissions"). |
+
+`resolveImagePickResult`/`resolveDocumentPickResult` return `null` for both a cancel and an
+(unexpected) empty `assets` array — they only normalize the shape. `openPicker` is the one place
+that decides what `null` means: it calls `onChange` only when a file was actually picked
+(`if (picked) onChange(picked)`), so a resolved cancel never reaches `onChange`.
+
+## Permissions — no upfront check/request, and why that's correct here
+
+`FileUpload` calls **no** `requestMediaLibraryPermissionsAsync`/`getMediaLibraryPermissionsAsync`
+before opening the image picker — read directly from the installed `expo-image-picker` (v57)'s own
+native source, not assumed from docs:
+
+- **iOS** (`ImagePickerModule.swift`): the default (non-editing) `launchImageLibraryAsync` presents a
+  `PHPickerViewController` (Apple's modern, permission-less picker). The permission-requester code is
+  wired only to the explicit permission calls and to `launchCameraAsync` — never to
+  `launchImageLibraryAsync`.
+- **Android** (`ImagePickerModule.kt`): `launchImageLibraryAsync` launches the system Photo Picker
+  activity contract directly, with no permission check in between.
+- `expo-document-picker` exposes **no permission API at all** — it's backed by the platform's own
+  file picker (iOS Files / Android SAF), inherently permission-less.
+
+So for the default flow, "denied/undetermined permission" isn't a state to query in advance — it's
+handled reactively: any rejection from `pickImageFile`/`pickDocumentFile` is caught in `openPicker`,
+which clears `value` (`onChange(null)`), sets `pickError` (renders a `status.danger.text` message
+with `accessibilityLiveRegion="polite"`, same pattern `Input.tsx`'s `errorText` uses), and warns via
+`console.warn` — gated the same way `PixelizeProvider.tsx` gates its own dev-only warning (the only
+other `console` usage in this codebase, reused rather than inventing a second convention).
+
+**Known gap:** `allowsEditing: true` routes iOS through the LEGACY `UIImagePickerController`, which
+can (per Apple's own OS behaviour, outside this module's code) trigger the native permission prompt
+on first use. Whether a denial there surfaces as a rejection (→ caught) or `{ canceled: true }` (→
+indistinguishable from a voluntary cancel) can't be observed without a device-level test;
+`pickImageFile` does not special-case it. The default, non-editing flow never reaches this ambiguity.
+
+## Two departures from every sibling module
+
+1. **The native call lives in `.variants.ts`, not `.tsx`.** Every sibling's `*.variants.ts` header
+   says "free of React and of any native/lucide import" because that module owns no native call —
+   `pickImageFile`/`pickDocumentFile` genuinely call `expo-image-picker`/`expo-document-picker`.
+   Colocating the call with its result-mapping keeps both testable the same way: `FileUpload.test.ts`
+   mocks the two packages at the module level (the same technique used for `core/icon`/RN's own
+   `Modal` elsewhere) and asserts on the real call. The import is still PLAIN and top-level — no
+   lazy-loading — matching `core/icon`'s established pattern for an optional-peer native dependency;
+   moving it from `.tsx` to `.variants.ts` doesn't change loading semantics, both files ship in the
+   same subpath entry. A consumer needs BOTH packages installed once they import this subpath at all,
+   even if they only use one `source` — the identical tradeoff `core/icon` makes for
+   `lucide-react-native` + `react-native-svg`.
+2. **No colour resolver.** Every sibling has a `resolveXxxTone`/`resolveXxxStatus` mapping a closed
+   union onto `RoleColors`. FileUpload doesn't need one: **both** interactive elements it renders —
+   trigger and remove control — are the library's own `Button` (composed, not reimplemented, per the
+   project brief), which already owns its tone→role mapping, focus ring, and ≥44dp touch target.
+   The only colours FileUpload itself renders are non-branching single-role lookups — filename text
+   (`fg.default`), the row border (`border.interactive`, the same substitution `Card`'s `outline`
+   variant makes for `border.default`'s sub-3:1 problem), and the error message
+   (`status.danger.text`) — read directly in the component, same as `Input.tsx`'s label `Text`, and
+   measured directly (no resolver) in `FileUpload.test.ts`.
+
+## Accessibility contract (WCAG)
+
+- **4.1.2** — trigger and remove control reuse `Button`'s own contract in full (role, state,
+  disabled/press gating, focus ring). Trigger's `accessibilityLabel` folds in the selection
+  (`"Upload photo. Selected: report.pdf"`); remove control's names target + action in one
+  announcement (`"Selected file: report.pdf, remove"`) since icon-only `Button` needs exactly one
+  accessible name.
+- **1.3.1** — the filename `Text` is purely visual; the composed name above is the only place a
+  screen reader hears it, avoiding a double announcement.
+- **1.4.3** — filename text and the error message measured ≥ 4.5:1 against `bg.canvas`, all 8
+  brands × both modes.
+- **1.4.11** — the row's border (`border.interactive`) measured ≥ 3:1 against `bg.canvas`.
+- **2.5.5 / 2.5.8** — both interactive elements are `Button` instances, inheriting its ≥44dp
+  guarantee directly — this module defines no touch-target arithmetic of its own.
+- **4.1.3** — the error message carries `accessibilityLiveRegion="polite"`.
+- Disabled dims the filename `Text` only (`opacity: 0.5`), not the row container — the row's own
+  remove `Button` already dims itself, and dimming the container too would compound both opacities.
+
+## Known gaps
+
+- Single-file only — `allowsMultipleSelection`/`multiple` aren't exposed; a future
+  `multiple?: boolean` would need `FileUploadResult[]`, a real API change, not a quiet bolt-on.
+- The `allowsEditing: true` legacy-picker permission-prompt ambiguity — see "Permissions" above.
+- No upload progress/state — out of scope by design; the consumer composes that around the `uri`.
+- No thumbnail/preview of a selected image — the row shows only the file name, matching how
+  `Input`/`Select` show text, not media. A future `previewImage?: boolean` is a reasonable v2.
+
+## Performance
+
+Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). `openPicker` is `useCallback`'d; a new `handlePick` wrapper replaces the old inline `onPress={() => void openPicker()}` so the trigger `Button`'s `onPress` reference stays stable, and `handleRemove` is `useCallback`'d for the "remove" `Button` — both are this library's own `Button` instances, so stabilizing these closures is what keeps `Button`'s memo from being defeated.

package/lib/module/modules/file-upload/index.js

@@ -0,0 +1,10 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/file-upload`. Value exports and type exports are split for
+ * `verbatimModuleSyntax`. The picker calls, result resolvers, and structural resolvers stay
+ * internal — a consumer configures a FileUpload through its props, never by importing its internals.
+ */
+
+export { FileUpload } from "./FileUpload.js";
+//# sourceMappingURL=index.js.map