pixelize-native-library 1.0.7 → 1.2.0

package/lib/module/modules/filter-sheet/MODULE.md

@@ -17,7 +17,7 @@ elsewhere — search stays outside the grouped panel, the same stance tickets-we
 | `FilterSheet.tsx` | The component. Owns `visible`/staged-edit state, wraps `Drawer`, wires Apply/Reset/quick-toggle/dimension-change. Data types (`FilterDimension`, `FilterOption`, `FilterValues`) live here, same precedent as `BottomNav`'s own data types. |
 | `FilterSheetBody.tsx` | PRIVATE (not exported) — the sheet's content: title header, per-dimension quick-chip rows, a single-open `Accordion` of facet controls, the Apply/Reset footer. Also hosts the private `DimensionControl` and `QuickChip` sub-components. |
 | `FilterChip.tsx` | Public. A small removable/locked chip for showing one currently-applied filter fact — see "FilterChip vs the quick chip" below. |
-| `FilterSheet.variants.ts` | Pure resolvers (`resolveFilterChipColors`, `resolveFilterChipAccessibility`, `resolveQuickChipColors`, `resolveFilterSheetBodyHeight`) + themed structural resolvers. No React, no lucide. |
+| `FilterSheet.variants.ts` | Pure resolvers (`resolveFilterChipColors`, `resolveFilterChipAccessibility`, `resolveQuickChipColors`, `resolveQuickChipAccessibility`, `resolveFilterSheetBodyHeight`) + themed structural resolvers. No React, no lucide. |
 | `filterSheet.helpers.ts` | Pure, framework-free: `countActiveFilters`, `normalizeFilterValues`, `resolveResetValues`, `applyQuickToggle`, `isOptionSelected`. No React, no `react-native` import at all. |
 | `index.ts` | Public surface: `FilterSheet`, `FilterSheetProps`, `FilterChip`, `FilterChipProps`, `FilterDimension`, `FilterDimensionKind`, `FilterOption`, `FilterValues`, `countActiveFilters`. |
 | `__tests__/FilterSheet.test.ts` | Pure: WCAG contrast (chip + quick-chip, all brands × modes), touch target, `resolveFilterChipAccessibility`, `resolveFilterSheetBodyHeight`. |
@@ -84,6 +84,21 @@ APPLIED filters elsewhere in its own UI (e.g. "Status: Open ✕" above a list)
 press-to-toggle AND a selected visual state, neither of which `FilterChip`'s contract supports — so
 it is a small, PRIVATE, unexported component (`QuickChip`), not a repurposed `FilterChip`.
 
+## Accessibility
+
+- **`FilterChip`'s remove-affordance label** now comes from the shared `removeAccessibilityLabel()`
+  (`core/a11y/labels`) — `"Remove ${label}"` — not a module-local phrasing. `chip` and `file-upload`
+  each independently invented their own wording for the same "remove this" affordance (a WCAG 3.2.4
+  Consistent Identification failure); this module now consumes the one shared constant instead of
+  adding a fourth phrasing.
+- **`QuickChip`'s selected state** (`resolveQuickChipAccessibility`) emits BOTH `aria-pressed` (web)
+  and `accessibilityState={{ selected }}` (native) — the one case in `docs/PLATFORM-A11Y-PROPS.md`
+  where the two vocabularies genuinely diverge for a toggle button, so both halves are always sent,
+  each inert on the platform it isn't aimed at. Never `aria-selected`: invalid ARIA on
+  `role="button"`. Before this fix the chip only ever emitted the `accessibilityState` object,
+  which `react-native-web` discards outright — a quick chip on web exposed `role="button"` with no
+  selected state at all.
+
 ## Controlled vs internal state
 
 | State | Owner | Mechanism |
@@ -113,3 +128,9 @@ never a migration.
 - `MultiSelect`'s own option sheet opens as a NESTED native `Modal` while `FilterSheet`'s `Drawer` is
   already showing — this is the library's existing, tested `MultiSelect` composed as-is (per
   CLAUDE.md's component decision order), not a new modal-stacking mechanism built for this module.
+
+## Modernization (v1.0.7)
+
+- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
+- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
+- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.

package/lib/module/modules/folder-row/FolderRow.js

@@ -0,0 +1,132 @@
+"use strict";
+
+/**
+ * FolderRow — file-browser style row with optional leading icon and trailing meta text.
+ *
+ * It is rendered AS a list cell at scale, so it carries no mount animation and no loop: press
+ * feedback is a plain pressed background colour. Colours and style arrays are memoized so a
+ * parent re-render with unchanged props costs nothing.
+ *
+ * Keyboard/AT focus draws an INSET ring (WCAG 2.4.7) rather than the gap-outside ring `Button` uses
+ * — a full-bleed row's outset ring is clipped by the list it sits in.
+ */
+
+import { memo, useCallback, useMemo, useState } from "react";
+import { Pressable, StyleSheet, Text, View } from "react-native";
+import { Icon } from "../../core/icon/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { folderRowFocusRingStructure, folderRowStructure, resolveFolderRowAccessibleName, resolveFolderRowColors } from "./FolderRow.variants.js";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+const ICON_STROKE = 2;
+const ICON_SIZE = 22;
+export const FolderRow = /*#__PURE__*/memo(function FolderRow({
+  title,
+  subtitle,
+  icon = "folder",
+  trailing,
+  onPress,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const colors = useMemo(() => resolveFolderRowColors(theme.colors), [theme.colors]);
+  const structure = useMemo(() => folderRowStructure(theme), [theme]);
+  // Keyboard / external-keyboard / assistive-tech focus (no-op on pure touch, correct everywhere else).
+  const [focused, setFocused] = useState(false);
+  const titleStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.medium), {
+    fontSize: theme.fontSizes.md,
+    color: colors.title
+  }], [theme, colors]);
+  const metaStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    fontSize: theme.fontSizes.sm,
+    color: colors.subtitle
+  }], [theme, colors]);
+  const accessibleName = useMemo(() => resolveFolderRowAccessibleName({
+    title,
+    subtitle,
+    trailing
+  }), [title, subtitle, trailing]);
+  const staticStyle = useMemo(() => [structure, {
+    backgroundColor: colors.background
+  }, style], [structure, colors, style]);
+  const rootStyle = useCallback(({
+    pressed
+  }) => [structure, {
+    backgroundColor: pressed ? colors.pressed : colors.background
+  }, style], [structure, colors, style]);
+  const handleFocus = useCallback(() => setFocused(true), []);
+  const handleBlur = useCallback(() => setFocused(false), []);
+  const focusRingStyle = useMemo(() => [folderRowFocusRingStructure(theme), {
+    borderColor: theme.colors.border.focus
+  }], [theme]);
+  const body = /*#__PURE__*/_jsx(FolderRowBody, {
+    icon: icon,
+    iconColor: theme.colors.accent.text,
+    title: title,
+    subtitle: subtitle,
+    trailing: trailing,
+    titleStyle: titleStyle,
+    metaStyle: metaStyle
+  });
+  if (onPress === undefined) {
+    return /*#__PURE__*/_jsx(View, {
+      testID: testID,
+      style: staticStyle,
+      children: body
+    });
+  }
+  return /*#__PURE__*/_jsxs(Pressable, {
+    testID: testID,
+    accessibilityRole: "button",
+    accessibilityLabel: accessibleName,
+    onPress: onPress,
+    onFocus: handleFocus,
+    onBlur: handleBlur,
+    style: rootStyle,
+    children: [focused && /*#__PURE__*/_jsx(View, {
+      pointerEvents: "none",
+      testID: testID === undefined ? undefined : `${testID}-focus-ring`,
+      style: focusRingStyle
+    }), body]
+  });
+});
+const FolderRowBody = /*#__PURE__*/memo(function FolderRowBody({
+  icon,
+  iconColor,
+  title,
+  subtitle,
+  trailing,
+  titleStyle,
+  metaStyle
+}) {
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsx(Icon, {
+      name: icon,
+      size: ICON_SIZE,
+      color: iconColor,
+      strokeWidth: ICON_STROKE
+    }), /*#__PURE__*/_jsxs(View, {
+      style: styles.textColumn,
+      children: [/*#__PURE__*/_jsx(Text, {
+        numberOfLines: 1,
+        style: titleStyle,
+        children: title
+      }), subtitle !== undefined && /*#__PURE__*/_jsx(Text, {
+        numberOfLines: 1,
+        style: metaStyle,
+        children: subtitle
+      })]
+    }), trailing !== undefined && /*#__PURE__*/_jsx(Text, {
+      numberOfLines: 1,
+      style: metaStyle,
+      children: trailing
+    })]
+  });
+});
+const styles = StyleSheet.create({
+  textColumn: {
+    flex: 1,
+    minWidth: 0
+  }
+});
+//# sourceMappingURL=FolderRow.js.map

package/lib/module/modules/folder-row/FolderRow.variants.js

@@ -0,0 +1,49 @@
+"use strict";
+
+import { createThemedVariants } from "../../core/style/index.js";
+export const folderRowStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    columnGap: theme.space[3],
+    paddingHorizontal: theme.space[3],
+    paddingVertical: theme.space[3],
+    borderRadius: theme.radii.base
+  }
+}));
+
+/**
+ * The keyboard/AT focus ring, drawn INSIDE the row's own bounds — not the gap-outside ring
+ * `Button`/`CopyButton` use. A folder row is a full-bleed list cell: an outset ring would be clipped
+ * by the enclosing list (or by the row's own rounded corners) on the very edges that carry it. Its
+ * colour is applied inline over this, never hardcoded here.
+ */
+export const folderRowFocusRingStructure = createThemedVariants(theme => ({
+  base: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    borderWidth: theme.borderWidths.thick,
+    borderRadius: theme.radii.base
+  }
+}));
+/**
+ * The pressable row's whole accessible name. A `Pressable` is an accessibility element, so its
+ * subtree collapses into ONE node and its own `accessibilityLabel` is all a screen reader hears —
+ * anything left out of this string (the trailing "12 items", the subtitle) is simply never
+ * announced. Kept pure so that contract is unit-testable without rendering React Native.
+ */
+export function resolveFolderRowAccessibleName(input) {
+  return [input.title, input.subtitle, input.trailing].filter(Boolean).join(", ");
+}
+export function resolveFolderRowColors(colors) {
+  return {
+    background: colors.bg.surface,
+    pressed: colors.bg.sunken,
+    title: colors.fg.default,
+    subtitle: colors.fg.muted
+  };
+}
+//# sourceMappingURL=FolderRow.variants.js.map

package/lib/module/modules/folder-row/MODULE.md

@@ -0,0 +1,71 @@
+# folder-row/
+
+A file-browser row. `FolderRow` renders ONE leaf row: leading icon, title, optional subtitle, optional trailing meta
+text. There is no internal list — consumers render hundreds of these inside their own
+`FlatList`/`VirtualList`, so every cost in this file is multiplied by the row count.
+
+With `onPress` the root is a `Pressable` (pressed state swaps the background to `bg.sunken`);
+without it the root is a plain `View`. That is the only branch in the component.
+
+## Files
+
+| File | Role |
+|------|------|
+| `FolderRow.tsx` | The component + a `React.memo`'d internal `FolderRowBody` shared by both branches. |
+| `FolderRow.variants.ts` | `folderRowStructure` (themed layout) and the pure `resolveFolderRowColors` / `resolveFolderRowAccessibleName` resolvers. No React. |
+| `index.ts` | Public surface: `FolderRow`, `FolderRowProps`. |
+| `__tests__/FolderRow.test.ts` | Pure: WCAG contrast over `resolveFolderRowColors` (all brands × modes) + the accessible-name composition. |
+| `__tests__/FolderRow.render.test.tsx` | Render: press fires `onPress`; the pressable row's single accessible name carries subtitle and trailing. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `title` | `string` | — | Required. `numberOfLines={1}`. |
+| `subtitle` | `string` | — | Second line; also folded into the accessible name. |
+| `icon` | `IconName` | `"folder"` | Name, never a node — per the API contract. |
+| `trailing` | `string` | — | Meta text (size/count/date), styled like the subtitle; also folded into the accessible name. |
+| `onPress` | `() => void` | — | Absent = plain `View`, no `accessibilityRole`. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, LAST in the root style array. |
+| `testID` | `string` | — | On the root node; a focused pressable row also seeds `` `${testID}-focus-ring` ``. |
+
+`onPress` takes no arguments deliberately. FolderRow renders a single row, so the per-row closure
+belongs to the caller's `renderItem`, not here — widening it to `(id) => void` would be a public API
+change that buys this component nothing.
+
+## Accessibility
+
+- **The accessible name folds in BOTH the subtitle and `trailing`** (`resolveFolderRowAccessibleName`):
+  `"Reports, Updated today, 12 items"` rather than a bare `"Reports"`. A `Pressable` is an
+  accessibility element, so the platform collapses its whole subtree into one node and the row's own
+  `accessibilityLabel` is all a screen reader ever hears — until this was fixed the label carried
+  only title + subtitle, so the trailing item count was announced nowhere (WCAG 4.1.2), even though
+  this file claimed `"Reports, 12 items"` as the example. The static (no-`onPress`) branch is a plain
+  `View` and collapses nothing, so its `<Text>` children keep announcing individually.
+- `accessibilityRole="button"` **only when `onPress` is set** — a non-pressable row is not a button
+  and must not announce as one.
+- **WCAG 1.4.3** — `title` on `background` is measured ≥ 4.5:1 on every brand × mode
+  (`FolderRow.test.ts`).
+- **WCAG 2.4.7** — a pressable row draws a `border.focus` ring (`${testID}-focus-ring`) while
+  focused. It is drawn **inside** the row's bounds, not at the `-(gap + width)` offsets
+  `Button`/`CopyButton` use: a full-bleed list cell's outset ring is clipped away by the enclosing
+  list on exactly the edges that carry it. A static (no-`onPress`) row is not focusable and draws
+  nothing.
+
+## Performance
+
+This row's per-render allocations are multiplied by the caller's row count, so:
+
+- `React.memo` on the export, plus a `React.memo`'d internal `FolderRowBody` — a parent re-render
+  with unchanged props re-renders nothing.
+- Colours (`resolveFolderRowColors`), the themed structure array, and every text style array are
+  `useMemo`'d on `theme` / `theme.colors`; the static text-column style lives in a module-level
+  `StyleSheet.create`. No style object is rebuilt per render.
+- **No internal list** — nothing here to virtualize. Windowing is the caller's `FlatList`.
+- **No mount animation, ever.** A per-row enter animation would run during the caller's scroll.
+  Press feedback stays a plain background-colour swap — no `usePressMotion`, no `Animated` value.
+
+## Known gaps
+
+- No trailing chevron, badge, or swipe actions — compose with `swipeable-row` if needed.
+- `trailing` is text only; a node would break the "internals never receive consumer style" rule.

package/lib/module/modules/folder-row/index.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { FolderRow } from "./FolderRow.js";
+//# sourceMappingURL=index.js.map

package/lib/module/modules/form-field/FormField.js

@@ -0,0 +1,104 @@
+"use strict";
+
+/**
+ * FormField — the label/required-marker/description/helper-error wrapper every crm-mobile form
+ * hand-rolled per-field (`formInputs.tsx`, `baseForm.tsx`). It draws no box of its own: it wraps
+ * ANY control (Input, Select, DatePicker, Combobox, a bare TextInput, …) and hands that control
+ * back the accessibility props it needs (`resolveFormFieldAccessibility`) via a render-prop, so the
+ * control never has to duplicate label/required/error logic itself.
+ *
+ * The only motion here is the helper/error message's enter-exit — the wrapper has no focus surface
+ * and nothing pressable of its own.
+ */
+
+import { memo, useId, useMemo, useRef } from "react";
+import { Animated, Text, View } from "react-native";
+import { useAnnounce } from "../../core/a11y/index.js";
+import { useEnterExit } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { formFieldDescriptionId, formFieldMessageId, formFieldStructure, resolveFormFieldAccessibility, resolveFormFieldMessage, resolveFormFieldStatus } from "./FormField.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export const FormField = /*#__PURE__*/memo(function FormField({
+  label,
+  required = false,
+  description,
+  status = "default",
+  helperText,
+  errorText,
+  disabled = false,
+  children,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const colors = resolveFormFieldStatus(theme.colors, status);
+  const idPrefix = useId();
+
+  // Handed straight to the render-prop, so a fresh object every render would defeat a memoized control.
+  const control = useMemo(() => resolveFormFieldAccessibility({
+    label,
+    required,
+    disabled,
+    status,
+    errorText,
+    description,
+    helperText,
+    describedByIdPrefix: idPrefix
+  }), [label, required, disabled, status, errorText, description, helperText, idPrefix]);
+  const message = resolveFormFieldMessage({
+    status,
+    helperText,
+    errorText
+  });
+  useAnnounce(status === "error" ? message : undefined);
+  const messageMotion = useEnterExit(message !== undefined);
+  // Holds the text on screen while the exit tween runs.
+  const lastMessage = useRef(message);
+  if (message !== undefined) lastMessage.current = message;
+  const rootStyle = useMemo(() => [formFieldStructure(theme), style], [theme, style]);
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.medium), {
+    fontSize: theme.fontSizes.sm,
+    color: colors.label
+  }], [theme, colors.label]);
+  const requiredMarkStyle = useMemo(() => ({
+    color: colors.requiredMark
+  }), [colors.requiredMark]);
+  const descriptionStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    fontSize: theme.fontSizes.xs,
+    color: colors.description
+  }], [theme, colors.description]);
+  const messageStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    fontSize: theme.fontSizes.xs,
+    color: colors.message
+  }], [theme, colors.message]);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: rootStyle,
+    children: [/*#__PURE__*/_jsxs(Text, {
+      accessibilityElementsHidden: true,
+      importantForAccessibility: "no-hide-descendants",
+      style: labelStyle,
+      children: [label, required && /*#__PURE__*/_jsx(Text, {
+        style: requiredMarkStyle,
+        children: " *"
+      })]
+    }), description !== undefined && /*#__PURE__*/_jsx(Text, {
+      nativeID: formFieldDescriptionId(idPrefix),
+      style: descriptionStyle,
+      children: description
+    }), children(control), messageMotion.mounted && lastMessage.current !== undefined &&
+    /*#__PURE__*/
+    // No `accessibilityLiveRegion` (deliberate): it's Android-only, and `useAnnounce` above
+    // already announces on both platforms — keeping both would double-announce on Android.
+    // Hidden only once the message is gone: `lastMessage` outlives it for the exit tween, and a
+    // stale error must not sit in the a11y tree while it fades.
+    _jsx(Animated.Text, {
+      nativeID: formFieldMessageId(idPrefix),
+      accessibilityElementsHidden: message === undefined,
+      importantForAccessibility: message === undefined ? "no-hide-descendants" : undefined,
+      style: [messageStyle, messageMotion.style],
+      children: lastMessage.current
+    })]
+  });
+});
+//# sourceMappingURL=FormField.js.map

package/lib/module/modules/form-field/FormField.variants.js

@@ -0,0 +1,88 @@
+"use strict";
+
+/**
+ * FormField's colour + behaviour resolution. There is no `structure` split here of the kind
+ * Button/Input have: a field wrapper draws no box of its own — it is pure vertical rhythm around
+ * whatever control the caller puts inside — so the only themed structure is spacing.
+ *
+ * Free of `lucide` and of any React tree, so the WCAG + contract tests import it directly
+ * (mocking only `react-native`'s `StyleSheet`, as `core/style` does).
+ */
+
+import { createThemedVariants } from "../../core/style/index.js";
+
+/** A state, not a brand tone — a field's colour reports validity. Mirrors `InputStatus`. */
+
+/**
+ * Maps `status` onto role colours. The required marker reads `status.danger.text` (not `.solid`):
+ * it is TEXT, so it owes 4.5:1 against the canvas, and `.text` is the rung picked for exactly that
+ * — `.solid` is a fill rung and only guarantees the looser 3:1.
+ */
+export function resolveFormFieldStatus(colors, status) {
+  return {
+    label: colors.fg.default,
+    requiredMark: colors.status.danger.text,
+    description: colors.fg.muted,
+    message: status === "error" ? colors.status.danger.text : colors.fg.muted
+  };
+}
+/** Node ids the wrapper stamps and `aria-describedby` refers to. Derived once, never interpolated
+ *  at a call site where a typo would be a dangling reference no compiler catches. */
+export function formFieldDescriptionId(prefix) {
+  return `${prefix}-description`;
+}
+export function formFieldMessageId(prefix) {
+  return `${prefix}-message`;
+}
+
+/**
+ * Derives what the control inside needs, purely.
+ *
+ * WCAG 3.3.2 — the red `*` is a *visual* convention a screen reader does not convey, so "required"
+ * is appended to the accessible name. WCAG 3.3.1 — in the error state the message is appended too,
+ * so a reader landing on the control hears WHY it is invalid instead of only that something is
+ * wrong; the visible message is separately announced when it appears.
+ *
+ * WCAG 1.3.1 — `description`/`helperText` are visible lines with no programmatic link to the control,
+ * so they ride `accessibilityHint` on native and `aria-describedby` on web (`accessibilityHint` has
+ * no web equivalent at all — `react-native-web` never reads it). `description` wins the hint: it
+ * explains what to enter, where `helperText` only qualifies it. `errorText` stays in the NAME, not
+ * the hint — a hint is advisory and some readers suppress it, which a validity message must never be
+ * — and the same state sets `aria-invalid`, so the error is never carried by border colour alone.
+ *
+ * `aria-describedby` deliberately omits the message node in the error state: that string is already
+ * in the accessible name, and listing it twice announces it twice.
+ */
+export function resolveFormFieldAccessibility(input) {
+  const status = input.status ?? "default";
+  const isError = status === "error";
+  const parts = [input.label, input.required === true ? "required" : undefined, isError ? input.errorText : undefined].filter(part => part !== undefined && part !== "");
+  const prefix = input.describedByIdPrefix;
+  const describedBy = prefix === undefined ? [] : [input.description === undefined ? undefined : formFieldDescriptionId(prefix), !isError && input.helperText !== undefined ? formFieldMessageId(prefix) : undefined].filter(id => id !== undefined);
+  return {
+    accessibilityLabel: parts.length > 0 ? parts.join(", ") : undefined,
+    accessibilityHint: input.description ?? input.helperText,
+    "aria-describedby": describedBy.length > 0 ? describedBy.join(" ") : undefined,
+    "aria-invalid": isError,
+    "aria-disabled": input.disabled === true,
+    status
+  };
+}
+
+/** The message a field shows — one at a time, error winning over helper (same rule as Input). */
+export function resolveFormFieldMessage(input) {
+  return (input.status ?? "default") === "error" ? input.errorText : input.helperText;
+}
+
+/**
+ * Vertical rhythm only — no colours, no box. Compiles once per theme identity via the
+ * `WeakMap`-cached themed resolver.
+ */
+export const formFieldStructure = createThemedVariants(theme => ({
+  base: {
+    rowGap: theme.space[1]
+  },
+  variants: {},
+  defaultVariants: {}
+}));
+//# sourceMappingURL=FormField.variants.js.map

package/lib/module/modules/form-field/MODULE.md

@@ -0,0 +1,103 @@
+# form-field/ — the label/required/description/error wrapper around any control
+
+Every crm-mobile form hand-rolls this same wrapper per field (`components/formInputs/formInputs.tsx`,
+`components/baseForm.tsx`): a label, an optional red `*`, an optional description line, the control
+itself, then a helper-or-error message. `FormField` is that wrapper, generalized to wrap **any**
+control — `Input`, `Select`, `DatePicker`, `Combobox`, or a bare `TextInput` — via a render-prop,
+instead of being married to one field type.
+
+## Files
+
+| File | Role |
+|------|------|
+| `FormField.tsx` | The component. Label/marker/description/message composition; hands the control its derived accessibility props via a render-prop child. |
+| `FormField.variants.ts` | Pure resolvers (`resolveFormFieldStatus`, `resolveFormFieldAccessibility`, `resolveFormFieldMessage`) + the themed `formFieldStructure` (vertical rhythm only — no box). No React. |
+| `index.ts` | Public surface: `FormField`, `FormFieldProps`, `FormFieldStatus`, `FormFieldControlProps`. |
+| `__tests__/FormField.test.ts` | Pure: WCAG contrast (all brands × modes), message-priority, and accessibility-string contract. |
+| `__tests__/FormField.render.test.tsx` | Render: label/marker/description, the render-prop payload, and the helper↔error message swap. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | `string` | — | Required. |
+| `required` | `boolean` | `false` | Shows a visible `*`; also appends "required" to the accessible name. |
+| `description` | `string` | — | Optional line between the label and the control. |
+| `status` | `default \| error` | `default` | Drives which message shows and what the control receives. |
+| `helperText` | `string` | — | Shown when `status` is `"default"`. |
+| `errorText` | `string` | — | Shown (and announced) when `status` is `"error"`; also appended to the control's accessible NAME. |
+| `disabled` | `boolean` | `false` | Forwarded into the render-prop's `aria-disabled`. |
+| `children` | `(control: FormFieldControlProps) => ReactNode` | — | Required. Render-prop — see below. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+| `testID` | `string` | — | On the root `View`. |
+
+### The render-prop, not a fixed slot
+
+`children` receives one `FormFieldControlProps` object: `{ accessibilityLabel, accessibilityHint,
+"aria-describedby", "aria-invalid", "aria-disabled", status }`. This is deliberate — a **fixed** `control: ReactNode` prop would leave every consumer to
+independently recompute the same "does this control need the error border, what's its accessible
+name" logic that `Input.variants.ts` already solves for `Input` alone. Passing the derived props
+back lets any control opt in with zero duplicated logic, e.g. `<Input status={control.status}
+accessibilityLabel={control.accessibilityLabel} />`.
+
+## Accessibility contract (WCAG)
+
+- **3.3.2** — the red `*` is a visual convention a screen reader does not convey, so `"required"` is
+  appended to `accessibilityLabel` when `required` is true.
+- **3.3.1** — in the error state, the error text is appended to the SAME accessible name, so a
+  reader landing on the control hears why it's invalid in one pass, not two.
+- **1.3.1 / 3.3.2** — `description` (falling back to `helperText`) rides the control's
+  `accessibilityHint` for native. On web, `accessibilityHint` reaches nothing at all (zero
+  occurrences in `react-native-web`'s dist) — the wrapper stamps real `nativeID`s on the rendered
+  description/message nodes and hands the control `"aria-describedby"` pointing at them, so the same
+  link exists on both platforms. `description` wins the tie: it says what to enter, where
+  `helperText` only qualifies it. `errorText` deliberately stays in the accessible NAME, not the
+  hint or the description link: a hint is advisory and some readers suppress it, which a validity
+  message must never be, and `"aria-invalid"` is now also set alongside it.
+- **1.4.3** — label, description, and message are all measured ≥ 4.5:1 against the canvas, for every
+  status, across all brands × both modes.
+- **4.1.2** — the visible label `Text` (and its `*` marker) is hidden from the accessibility tree
+  with `accessibilityElementsHidden` / `importantForAccessibility="no-hide-descendants"`. Its exact
+  content is already copied into the control's `accessibilityLabel` ("Email, required"), so leaving
+  it in the tree announced the field's name twice — once as a standalone stop, once at the control.
+  Same idiom `Input` and `Textarea` use for their own label. Hiding the wrapper's label is safe
+  *because* the render-prop guarantees the name reaches the control; a consumer who ignores
+  `control.accessibilityLabel` leaves the field unnamed, which is the documented contract.
+- **4.1.3** — an appearing error is announced with `useAnnounce` (`core/a11y`), i.e.
+  `AccessibilityInfo.announceForAccessibility`, so it reaches VoiceOver **and** TalkBack. The message
+  row carries **no** `accessibilityLiveRegion`: that prop is Android-only, so it left iOS silent, and
+  keeping it alongside the announcement would announce twice on Android. A helper message is never
+  announced — only an error interrupts. While the message is leaving (its exit tween keeps it
+  mounted) it is hidden from the tree, so a stale error can't be read.
+
+## Patterns copied from the reference modules
+
+1. **Structure vs colour split**, same as Button/Input/Badge — though here "structure" is just
+   `rowGap`, since a field wrapper draws no box.
+2. **Pure, testable resolvers** — the accessibility-string contract is unit-tested directly, the
+   same way `Banner.variants.ts`'s label-collapsing is.
+3. **One message shown at a time, error winning** — the exact rule `Input` already uses; kept
+   consistent so a form built from `FormField` + `Input` never shows two conflicting states.
+
+## Design decisions specific to this module
+
+- **Render-prop instead of a fixed `control` slot** — see above.
+- **No built-in `TextInput`.** `form-field` is control-agnostic on purpose; pairing it with `Input`
+  by default would make every non-text field (a `Select`, a `DatePicker`) fight the wrapper's
+  assumptions instead of just consuming the props it hands back.
+
+## Known gaps
+
+- No multi-error list — one `errorText` at a time, matching `Input`. A field needing several
+  simultaneous rules should join them into one string upstream.
+
+## Performance
+
+Wrapped in `React.memo`. `formFieldStructure` is a themed resolver, so it compiles once per theme
+identity, not per render.
+
+## Modernization (v1.0.7)
+
+- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
+- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
+- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.

package/lib/module/modules/form-field/index.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { FormField } from "./FormField.js";
+//# sourceMappingURL=index.js.map