@multiplatform.one/forms 6.1.0 → 6.3.0

package/src/fields/Barcode/Barcode.stories.tsx

@@ -80,6 +80,19 @@ export const Standalone: Story = {
   render: (args) => <Barcode {...args} {...iconProps} />,
 };
 
+/**
+ * Bare contract (UX-010 / Axiom 13 ONE BODY): no icon props — the package
+ * defaults render the barcode adornment and the camera scan button.
+ */
+export const Bare: Story = {
+  args: {
+    label: "Barcode",
+    helperText: "No icon props — package default icons",
+    enableScan: true,
+    onChange: action("onChange"),
+  },
+};
+
 export const Basic: Story = {
   args: {
     label: "Product Barcode",
@@ -155,3 +168,9 @@ export const Interactive: Story = {
     return <InteractiveExample />;
   },
 };
+
+/** Loading placeholder — the skeleton mirrors the field's anatomy (LC-20 / DG-ST-02). */
+export const SkeletonState: Story = {
+  args: { label: "Product Barcode", skeleton: true },
+  render: (args) => <Barcode {...args} {...iconProps} />,
+};

package/src/fields/Barcode/BarcodePreview.spec.tsx

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { BarcodePreview } from "./BarcodePreview";
+import { countModules, encodeCode128B } from "./code128";
+
+/** Rebuild the module string ("1" = bar) from the encoder's runs. */
+function toModuleString(value: string): string | null {
+  const runs = encodeCode128B(value);
+  if (!runs) return null;
+  return runs.map((run) => (run.bar ? "1" : "0").repeat(run.modules)).join("");
+}
+
+describe("encodeCode128B", () => {
+  it('encodes "A" as start B + data + checksum + stop (exact modules)', () => {
+    // Sequence: START_B(104), "A"(33), check (104 + 33*1) % 103 = 34, STOP(106)
+    expect(toModuleString("A")).toBe(
+      "11010010000" + "10100011000" + "10001011000" + "1100011101011",
+    );
+  });
+
+  it('computes the published check symbol 88 for "Wikipedia"', () => {
+    const modules = toModuleString("Wikipedia");
+    expect(modules).not.toBeNull();
+    // 12 symbols: start + 9 data + check + stop → 11*11 + 13 modules
+    expect(modules!.length).toBe(11 * 11 + 13);
+    // Check symbol sits at index 10; BARS[88] = 11110010010
+    expect(modules!.slice(110, 121)).toBe("11110010010");
+  });
+
+  it("always starts and ends with a bar and alternates runs", () => {
+    const runs = encodeCode128B("SKU-001234")!;
+    expect(runs[0].bar).toBe(true);
+    expect(runs[runs.length - 1].bar).toBe(true);
+    for (let i = 1; i < runs.length; i++) {
+      expect(runs[i].bar).toBe(!runs[i - 1].bar);
+    }
+    // (start + data + check) symbols × 11 modules + 13-module stop
+    expect(countModules(runs)).toBe(("SKU-001234".length + 2) * 11 + 13);
+  });
+
+  it("returns null for empty and non-ASCII values", () => {
+    expect(encodeCode128B("")).toBeNull();
+    expect(encodeCode128B("héllo")).toBeNull();
+    expect(encodeCode128B("日本")).toBeNull();
+  });
+});
+
+describe("BarcodePreview", () => {
+  it("draws bars for an encodable value (labeled image, real content)", () => {
+    const result = renderWithProviders(<BarcodePreview value="SKU-001234" />);
+    const preview = result.container.querySelector('[data-testid="barcode-preview"]');
+    expect(preview).not.toBeNull();
+    expect(preview?.getAttribute("aria-label")).toContain("SKU-001234");
+    // Actual bar runs render — not an empty block
+    expect(preview!.firstElementChild!.children.length).toBeGreaterThan(10);
+  });
+
+  it("renders nothing for an empty value (host owns the empty state)", () => {
+    const result = renderWithProviders(<BarcodePreview value="" />);
+    expect(result.container.querySelector('[data-testid="barcode-preview"]')).toBeNull();
+  });
+
+  it("falls back to honest text for values Code 128 B cannot encode", () => {
+    const result = renderWithProviders(<BarcodePreview value="héllo" />);
+    expect(result.container.querySelector('[data-testid="barcode-preview"]')).toBeNull();
+    expect(result.container.textContent).toContain("héllo");
+  });
+});

package/src/fields/Barcode/BarcodePreview.tsx

@@ -0,0 +1,86 @@
+/**
+ * BarcodePreview — draws a value as a real Code 128 symbol using plain Views
+ * (cross-platform: no canvas/svg/web-only dependency). Bars use the theme ink
+ * on the theme surface, so a scheme flip restyles the preview with the rest
+ * of the screen.
+ *
+ * Containment contract (LC-10): the strip never exceeds its host — width is
+ * capped at 100% and bars shrink proportionally (preserving relative module
+ * widths) instead of painting past the frame. Hosts bound the height via the
+ * `height` prop (table cells keep it under the row height).
+ *
+ * Honest states: an empty value renders nothing (hosts show their own empty
+ * marker); a value Code 128 B cannot encode falls back to the raw value as
+ * mono text — never a fake or truncated symbol.
+ */
+
+import { Text, View, XStack } from "tamagui";
+import { t } from "../../shared/t";
+import { encodeCode128B } from "./code128";
+
+export interface BarcodePreviewProps {
+  value?: string;
+  /** Bar strip height in px — content geometry, bounded by the host. */
+  height?: number;
+  /** Width of one barcode module in px. */
+  moduleWidth?: number;
+  /** Render the human-readable value under the bars. */
+  showText?: boolean;
+}
+
+export function BarcodePreview({
+  value,
+  height = 18,
+  moduleWidth = 1,
+  showText = false,
+}: BarcodePreviewProps) {
+  if (!value) return null;
+  const runs = encodeCode128B(value);
+  if (!runs) {
+    return (
+      <Text fontFamily="$mono" fontSize="$2" numberOfLines={1} color="$color" flexShrink={1}>
+        {value}
+      </Text>
+    );
+  }
+  const quietZone = moduleWidth * 10;
+  return (
+    <View
+      role="img"
+      aria-label={t("Barcode: {{value}}", { value })}
+      testID="barcode-preview"
+      flexDirection="column"
+      alignItems="center"
+      maxWidth="100%"
+      minWidth={0}
+      flexShrink={1}
+      overflow="hidden"
+    >
+      <XStack
+        height={height}
+        maxWidth="100%"
+        minWidth={0}
+        flexShrink={1}
+        overflow="hidden"
+        paddingHorizontal={quietZone}
+        backgroundColor="$background"
+        aria-hidden
+      >
+        {runs.map((run, index) => (
+          <View
+            key={index}
+            width={run.modules * moduleWidth}
+            height="100%"
+            flexShrink={1}
+            backgroundColor={run.bar ? "$color" : "transparent"}
+          />
+        ))}
+      </XStack>
+      {showText && (
+        <Text fontFamily="$mono" fontSize="$2" numberOfLines={1} color="$color" flexShrink={1}>
+          {value}
+        </Text>
+      )}
+    </View>
+  );
+}

package/src/fields/Barcode/BarcodeScanner.native.tsx

@@ -1,9 +1,11 @@
-import { CameraView, useCameraPermissions } from "expo-camera";
-import { useEffect, useRef } from "react";
+import { Camera, CameraView, useCameraPermissions } from "expo-camera";
+import { useEffect, useRef, useState } from "react";
 import { StyleSheet } from "react-native";
-import { View, YStack } from "tamagui";
-import { formInputColors } from "../../shared/colorRamps";
-import type { BarcodeScannerProps } from "./scannerTypes";
+import { Text, View, XStack, YStack } from "tamagui";
+import { Button } from "../../Button";
+import { formCommonColors, formInputColors } from "../../shared/colorRamps";
+import { t } from "../../shared/t";
+import type { BarcodeScannerProps, CameraPreflightResult } from "./scannerTypes";
 
 const barcodeTypes = [
   "qr",
@@ -21,11 +23,41 @@ const barcodeTypes = [
   "aztec",
 ] as const;
 
+/**
+ * Camera capability pre-flight (LC-19 CAPABILITY-PREFLIGHT), native mirror.
+ * Checks the expo-camera permission BEFORE the scanner surface is presented.
+ * Hard-denied (denied + !canAskAgain) fails pre-flight → the field shows an
+ * inline error and the surface never presents. An askable `undetermined` /
+ * `denied but canAskAgain` state passes — the system prompt happens over the
+ * stable scanner surface, never as a present-fail-dismiss flash.
+ */
+export async function preflightCamera(): Promise<CameraPreflightResult> {
+  try {
+    const status = await Camera.getCameraPermissionsAsync();
+    if (!status.granted && !status.canAskAgain) {
+      return {
+        ok: false,
+        reason: t(
+          "Camera unavailable: permission denied. Enable camera access in system settings.",
+        ),
+      };
+    }
+  } catch {
+    // Permission module unavailable — the surface reports the failure inline.
+  }
+  return { ok: true };
+}
+
 /**
  * Native barcode scanner — `expo-camera`'s `CameraView` with built-in barcode
  * scanning (bundled in Expo Go SDK 55). Replaces the web `html5-qrcode`, so no
  * `getUserMedia` / DOM browser code reaches the Hermes bundle.
  *
+ * LC-19 CAPABILITY-PREFLIGHT: only mounts after a passing `preflightCamera()`.
+ * While the permission prompt is pending the surface shows a stable
+ * "Requesting camera…" state; a denial renders the error INSIDE the still-open
+ * surface with Retry + Close — it never self-dismisses on error.
+ *
  * Note: the iOS simulator has no camera, so live scanning can only be verified
  * on a physical device; in the simulator the camera surface renders empty.
  */
@@ -38,43 +70,79 @@ export function BarcodeScanner({
 }: BarcodeScannerProps) {
   const [permission, requestPermission] = useCameraPermissions();
   const handledRef = useRef(false);
+  const [denied, setDenied] = useState(false);
 
   useEffect(() => {
     if (!active) return;
     handledRef.current = false;
+    setDenied(false);
     onError(null);
-    if (permission && !permission.granted) {
-      requestPermission().then((res) => {
-        if (!res.granted) {
-          onError("Camera permission denied. Please allow camera access.");
-          onClose();
-        }
-      });
-    }
+  }, [active]);
+
+  useEffect(() => {
+    if (!active || !permission || permission.granted) return;
+    let stale = false;
+    requestPermission().then((res) => {
+      // Surface stays OPEN on denial: error renders inside with Retry + Close.
+      if (!stale && !res.granted) setDenied(true);
+    });
+    return () => {
+      stale = true;
+    };
   }, [active, permission?.granted]);
 
-  if (!active || !permission?.granted) return null;
+  if (!active) return null;
 
   return (
     <YStack
+      testID="barcode-scanner-popup"
       {...knobProps.borderRadius}
       {...knobProps.inputSurface}
       borderColor={formInputColors.border.base}
       overflow="hidden"
     >
-      <View width="100%" height={250}>
-        <CameraView
-          style={StyleSheet.absoluteFill}
-          facing="back"
-          barcodeScannerSettings={{ barcodeTypes: [...barcodeTypes] }}
-          onBarcodeScanned={({ data }) => {
-            if (handledRef.current) return;
-            handledRef.current = true;
-            onScan(data);
-            onClose();
-          }}
-        />
-      </View>
+      {denied ? (
+        <YStack padding="$4" gap="$3" alignItems="center" minHeight={120} justifyContent="center">
+          <Text {...knobProps.body} color={formCommonColors.error} textAlign="center">
+            {t("Camera permission denied. Please allow camera access.")}
+          </Text>
+          <XStack gap="$2">
+            <Button
+              size={knobProps.sizeToken}
+              onPress={() => {
+                setDenied(false);
+                requestPermission().then((res) => {
+                  if (!res.granted) setDenied(true);
+                });
+              }}
+              aria-label={t("Retry camera")}
+            >
+              {t("Retry")}
+            </Button>
+            <Button size={knobProps.sizeToken} onPress={onClose} aria-label={t("Close scanner")}>
+              {t("Close")}
+            </Button>
+          </XStack>
+        </YStack>
+      ) : !permission?.granted ? (
+        <Text {...knobProps.body} padding="$3" textAlign="center" opacity={0.7}>
+          {t("Requesting camera…")}
+        </Text>
+      ) : (
+        <View width="100%" height={250}>
+          <CameraView
+            style={StyleSheet.absoluteFill}
+            facing="back"
+            barcodeScannerSettings={{ barcodeTypes: [...barcodeTypes] }}
+            onBarcodeScanned={({ data }) => {
+              if (handledRef.current) return;
+              handledRef.current = true;
+              onScan(data);
+              onClose();
+            }}
+          />
+        </View>
+      )}
     </YStack>
   );
 }

package/src/fields/Barcode/BarcodeScanner.tsx

@@ -1,7 +1,10 @@
-import { useEffect, useRef } from "react";
-import { View, YStack } from "tamagui";
-import { formInputColors } from "../../shared/colorRamps";
-import type { BarcodeScannerProps } from "./scannerTypes";
+import { useEffect, useRef, useState } from "react";
+import { Text, View, XStack, YStack } from "tamagui";
+import { Button } from "../../Button";
+import { queryPermissionState } from "../../shared/capabilityPreflight";
+import { formCommonColors, formInputColors } from "../../shared/colorRamps";
+import { t } from "../../shared/t";
+import type { BarcodeScannerProps, CameraPreflightResult } from "./scannerTypes";
 
 interface Html5QrcodeScanner {
   start: (
@@ -15,10 +18,66 @@ interface Html5QrcodeScanner {
   getState?: () => number;
 }
 
+function mapCameraError(err: unknown): string {
+  const message = err instanceof Error ? err.message : String(err);
+  if (message.includes("Permission") || message.includes("NotAllowed")) {
+    return t("Camera permission denied. Please allow camera access.");
+  }
+  if (message.includes("NotFound") || message.includes("no camera")) {
+    return t("No camera found on this device.");
+  }
+  if (message.includes("NotReadable") || message.includes("in use")) {
+    return t("Camera is in use by another application.");
+  }
+  return t("Scanner error: {{message}}", { message });
+}
+
+/**
+ * Camera capability pre-flight (LC-19 CAPABILITY-PREFLIGHT). Runs BEFORE the
+ * scanner surface is presented: checks secure context, getUserMedia support,
+ * that a videoinput device exists, and that permission is not hard-denied.
+ * A `prompt` permission state passes — the prompt happens inside the stable
+ * scanner surface, never as a mount-fail-unmount flicker.
+ */
+export async function preflightCamera(): Promise<CameraPreflightResult> {
+  if (typeof navigator === "undefined" || !navigator.mediaDevices?.getUserMedia) {
+    const insecure = typeof window !== "undefined" && window.isSecureContext === false;
+    return {
+      ok: false,
+      reason: insecure
+        ? t("Camera unavailable: insecure context (HTTPS required).")
+        : t("Camera unavailable: not supported in this browser."),
+    };
+  }
+  try {
+    const devices = await navigator.mediaDevices.enumerateDevices();
+    if (!devices.some((d) => d.kind === "videoinput")) {
+      return {
+        ok: false,
+        reason: t("Camera unavailable: no camera found on this device."),
+      };
+    }
+  } catch {
+    // enumerateDevices unavailable — let the permission check below decide.
+  }
+  const permission = await queryPermissionState("camera");
+  if (permission === "denied") {
+    return {
+      ok: false,
+      reason: t("Camera unavailable: permission denied. Allow camera access in browser settings."),
+    };
+  }
+  return { ok: true };
+}
+
 /**
  * Web barcode scanner — the browser `html5-qrcode` camera (getUserMedia +
- * a DOM container). This file is `.web.tsx`, so it is never bundled on native;
- * the Hermes graph gets `BarcodeScanner.native.tsx` (expo-camera) instead.
+ * a DOM container). Native gets `BarcodeScanner.native.tsx` (expo-camera).
+ *
+ * LC-19 CAPABILITY-PREFLIGHT: this surface only mounts after a passing
+ * `preflightCamera()`. If init still fails after that (device grabbed
+ * mid-flight, prompt declined), the error renders INSIDE the still-open
+ * panel with Retry + Close — the panel never self-closes on error.
  */
 export function BarcodeScanner({
   active,
@@ -29,10 +88,15 @@ export function BarcodeScanner({
 }: BarcodeScannerProps) {
   const scannerRef = useRef<Html5QrcodeScanner | null>(null);
   const containerId = useRef(`barcode-scanner-${Math.random().toString(36).slice(2, 9)}`);
+  const [attempt, setAttempt] = useState(0);
+  const [status, setStatus] = useState<"starting" | "streaming" | "error">("starting");
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
 
   useEffect(() => {
     if (!active) return;
     let cancelled = false;
+    setStatus("starting");
+    setErrorMessage(null);
     onError(null);
     (async () => {
       try {
@@ -49,16 +113,12 @@ export function BarcodeScanner({
           },
           () => {},
         );
+        if (!cancelled) setStatus("streaming");
       } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        if (message.includes("Permission") || message.includes("NotAllowed")) {
-          onError("Camera permission denied. Please allow camera access.");
-        } else if (message.includes("NotFound") || message.includes("no camera")) {
-          onError("No camera found on this device.");
-        } else {
-          onError(`Scanner error: ${message}`);
-        }
-        onClose();
+        if (cancelled) return;
+        // The panel stays OPEN: error renders inside with Retry + Close.
+        setStatus("error");
+        setErrorMessage(mapCameraError(err));
       }
     })();
     return () => {
@@ -79,18 +139,52 @@ export function BarcodeScanner({
         scannerRef.current = null;
       }
     };
-  }, [active]);
+  }, [active, attempt]);
 
   if (!active) return null;
 
   return (
     <YStack
+      testID="barcode-scanner-popup"
       {...knobProps.borderRadius}
       {...knobProps.inputSurface}
       borderColor={formInputColors.border.base}
       overflow="hidden"
     >
-      <View id={containerId.current} width="100%" minHeight={250} />
+      {status === "error" ? (
+        <YStack padding="$4" gap="$3" alignItems="center" minHeight={120} justifyContent="center">
+          <Text {...knobProps.body} color={formCommonColors.error} textAlign="center">
+            {errorMessage}
+          </Text>
+          <XStack gap="$2">
+            <Button
+              size={knobProps.sizeToken}
+              onPress={() => setAttempt((a) => a + 1)}
+              aria-label={t("Retry camera")}
+            >
+              {t("Retry")}
+            </Button>
+            <Button size={knobProps.sizeToken} onPress={onClose} aria-label={t("Close scanner")}>
+              {t("Close")}
+            </Button>
+          </XStack>
+        </YStack>
+      ) : (
+        <>
+          {status === "starting" && (
+            <Text {...knobProps.body} padding="$3" textAlign="center" opacity={0.7}>
+              {t("Requesting camera…")}
+            </Text>
+          )}
+          {/* LC-10: the camera video renders at its natural aspect (portrait
+              feeds exceed 1000px tall) — pin it to the panel with object-fit
+              cover so the surface never paints past its frame. */}
+          <style>
+            {`#${containerId.current} video { width: 100%; height: 100%; object-fit: cover; }`}
+          </style>
+          <View id={containerId.current} width="100%" height={320} overflow="hidden" />
+        </>
+      )}
     </YStack>
   );
 }

package/src/fields/Barcode/code128.ts

@@ -0,0 +1,74 @@
+/**
+ * Minimal Code 128 (set B) encoder — turns a printable-ASCII string into the
+ * bar/space run lengths of a valid, scannable symbol (start code, checksum,
+ * stop pattern included). Used by BarcodePreview to draw honest previews
+ * without a canvas/svg barcode dependency.
+ */
+
+/**
+ * Code 128 symbol patterns (ISO/IEC 15417). Index = symbol value 0–106; each
+ * entry is the 11-module bar/space pattern written as a binary number
+ * (1 = bar, 0 = space). The final entry is the 13-module stop pattern.
+ */
+const BARS = [
+  11011001100, 11001101100, 11001100110, 10010011000, 10010001100, 10001001100, 10011001000,
+  10011000100, 10001100100, 11001001000, 11001000100, 11000100100, 10110011100, 10011011100,
+  10011001110, 10111001100, 10011101100, 10011100110, 11001110010, 11001011100, 11001001110,
+  11011100100, 11001110100, 11101101110, 11101001100, 11100101100, 11100100110, 11101100100,
+  11100110100, 11100110010, 11011011000, 11011000110, 11000110110, 10100011000, 10001011000,
+  10001000110, 10110001000, 10001101000, 10001100010, 11010001000, 11000101000, 11000100010,
+  10110111000, 10110001110, 10001101110, 10111011000, 10111000110, 10001110110, 11101110110,
+  11010001110, 11000101110, 11011101000, 11011100010, 11011101110, 11101011000, 11101000110,
+  11100010110, 11101101000, 11101100010, 11100011010, 11101111010, 11001000010, 11110001010,
+  10100110000, 10100001100, 10010110000, 10010000110, 10000101100, 10000100110, 10110010000,
+  10110000100, 10011010000, 10011000010, 10000110100, 10000110010, 11000010010, 11001010000,
+  11110111010, 11000010100, 10001111010, 10100111100, 10010111100, 10010011110, 10111100100,
+  10011110100, 10011110010, 11110100100, 11110010100, 11110010010, 11011011110, 11011110110,
+  11110110110, 10101111000, 10100011110, 10001011110, 10111101000, 10111100010, 11110101000,
+  11110100010, 10111011110, 10111101110, 11101011110, 11110101110, 11010000100, 11010010000,
+  11010011100, 1100011101011,
+] as const;
+
+const START_B = 104;
+const STOP = 106;
+const MODULO = 103;
+
+export interface Code128Run {
+  /** true = ink bar, false = space */
+  bar: boolean;
+  /** run length in barcode modules */
+  modules: number;
+}
+
+/**
+ * Encode a string as Code 128 set B (printable ASCII 32–126). Returns the
+ * bar/space runs of the complete symbol, or null when the value is empty or
+ * contains characters set B cannot represent.
+ */
+export function encodeCode128B(value: string): Code128Run[] | null {
+  if (!value) return null;
+  const codes: number[] = [];
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i) - 32;
+    if (code < 0 || code > 94) return null;
+    codes.push(code);
+  }
+  let checksum = START_B;
+  for (let i = 0; i < codes.length; i++) checksum += codes[i] * (i + 1);
+  const sequence = [START_B, ...codes, checksum % MODULO, STOP];
+
+  const moduleString = sequence.map((symbol) => String(BARS[symbol])).join("");
+  const runs: Code128Run[] = [];
+  for (const char of moduleString) {
+    const bar = char === "1";
+    const last = runs[runs.length - 1];
+    if (last && last.bar === bar) last.modules += 1;
+    else runs.push({ bar, modules: 1 });
+  }
+  return runs;
+}
+
+/** Total module count of an encoded symbol (for width math in previews). */
+export function countModules(runs: Code128Run[]): number {
+  return runs.reduce((sum, run) => sum + run.modules, 0);
+}