@multiplatform.one/forms 6.0.0

package/src/fieldLayout.tsx

@@ -0,0 +1,195 @@
+import type { FieldApi } from "@tanstack/form-core";
+import { Field as TanstackField } from "@tanstack/react-form";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import type { KnobProps } from "@multiplatform.one/theme";
+import type { ReactNode } from "react";
+import { createContext, useContext } from "react";
+import type { FontSizeTokens, LabelProps, SizeTokens, YStackProps } from "tamagui";
+import { Label, Paragraph, YStack } from "tamagui";
+import { formCommonColors } from "./shared/colorRamps";
+import type { AnyFormApi, SimpleFieldApi } from "./types";
+
+const FieldDescribedByContext = createContext<string | undefined>(undefined);
+export function useFieldDescribedBy() {
+  return useContext(FieldDescribedByContext);
+}
+
+// ── Helper ────────────────────────────────────────────────────────────────────
+
+function getHelperTextSize(size?: SizeTokens): FontSizeTokens {
+  if (!size) return "$1";
+  const sizeMap: Record<string, FontSizeTokens> = {
+    $1: "$1",
+    $2: "$1",
+    $3: "$2",
+    $4: "$3",
+    $5: "$4",
+    $6: "$5",
+    $7: "$6",
+    $8: "$7",
+    $9: "$8",
+    $10: "$9",
+    $11: "$10",
+    $12: "$11",
+    $13: "$12",
+    $14: "$13",
+    $15: "$14",
+    $16: "$15",
+    $17: "$16",
+  };
+  return sizeMap[size.toString()] || "$1";
+}
+
+// ── FieldLayout ──────────────────────────────────────────────────────────────
+
+export interface FieldLayoutProps {
+  id?: string;
+  label?: ReactNode;
+  labelProps?: Omit<LabelProps, "htmlFor" | "ref">;
+  error?: string | boolean;
+  field?: FieldApi<
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any
+  >;
+  helperText?: string;
+  required?: boolean;
+  size?: SizeTokens;
+  knobProps?: KnobProps;
+  onBlur?: (...args: any[]) => void;
+  /**
+   * Use compact spacing between field and helper/error text.
+   * Useful for inline-label fields (checkbox, switch) where the label
+   * is beside the control rather than above it.
+   */
+  compactSpacing?: boolean;
+  children: ReactNode;
+}
+
+export function FieldLayout({
+  id,
+  label,
+  labelProps,
+  error: propError,
+  field,
+  helperText,
+  required,
+  size,
+  knobProps: knobPropsProp,
+  onBlur,
+  compactSpacing,
+  children,
+}: FieldLayoutProps) {
+  const { knobProps: resolvedKnobs } = useResolvedKnobs();
+  const knobProps = knobPropsProp ?? resolvedKnobs;
+  const error = field?.state.meta.errors.length ? String(field.state.meta.errors[0]) : propError;
+  const errorMessage = typeof error === "string" && error.length > 0 ? error : undefined;
+  const hasErrorState = Boolean(error);
+  const helperSize = getHelperTextSize(size || knobProps.sizeToken);
+
+  // Use compact gap for inline-label fields (checkbox, switch) or when explicitly requested
+  const useCompact = compactSpacing || !label;
+  const gapProps = useCompact ? { gap: "$1" } : knobProps.gap;
+
+  const describedBy =
+    [
+      helperText && id ? `${id}-description` : undefined,
+      errorMessage && id ? `${id}-error` : undefined,
+    ]
+      .filter(Boolean)
+      .join(" ") || undefined;
+
+  return (
+    <FieldDescribedByContext.Provider value={describedBy}>
+      <YStack theme={hasErrorState ? "red" : undefined} {...gapProps} onBlur={onBlur}>
+        {label && (
+          <Label
+            htmlFor={id}
+            size={size || knobProps.sizeToken}
+            {...knobProps.heading}
+            color={hasErrorState ? formCommonColors.error : knobProps.textAccentColor}
+            {...labelProps}
+          >
+            {label}
+            {required && " *"}
+          </Label>
+        )}
+        {children}
+        {helperText && !errorMessage ? (
+          <Paragraph
+            id={id ? `${id}-description` : undefined}
+            size={helperSize}
+            {...knobProps.body}
+            color={formCommonColors.text}
+          >
+            {helperText}
+          </Paragraph>
+        ) : null}
+        {errorMessage ? (
+          <Paragraph
+            id={id ? `${id}-error` : undefined}
+            size={helperSize}
+            {...knobProps.body}
+            color={formCommonColors.error}
+            role="alert"
+            aria-live="polite"
+          >
+            {errorMessage}
+          </Paragraph>
+        ) : null}
+      </YStack>
+    </FieldDescribedByContext.Provider>
+  );
+}
+
+export type FormFieldProps<
+  _TParentData = Record<string, unknown>,
+  _TName extends string = string,
+  _TFieldValidator = unknown,
+  _TFormValidator = unknown,
+  _TData = unknown,
+> = FieldLayoutProps & Omit<YStackProps, keyof FieldLayoutProps>;
+
+// ── Field (typed TanStack Field wrapper) ──────────────────────────────────────
+
+export interface FieldProps<
+  _TParentData = Record<string, unknown>,
+  TName extends string = string,
+  TValue = unknown,
+> {
+  name: TName;
+  form?: AnyFormApi<any>;
+  defaultValue?: TValue;
+  mode?: "value" | "array";
+  preserveValue?: boolean;
+  validators?: Record<string, unknown>;
+  children: (field: SimpleFieldApi<TValue>) => ReactNode;
+}
+
+export const Field = TanstackField as <
+  TParentData = Record<string, unknown>,
+  TName extends string = string,
+  TValue = unknown,
+>(
+  props: FieldProps<TParentData, TName, TValue>,
+) => ReactNode;

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

@@ -0,0 +1,115 @@
+import { describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Form } from "../../Form";
+import { Barcode } from "./index";
+
+const barcodeIcon = <span data-testid="barcode-icon" />;
+const scanIcon = <span data-testid="scan-icon" />;
+const stopIcon = <span data-testid="stop-icon" />;
+
+describe("Barcode", () => {
+  describe("without form context", () => {
+    it("renders with label", () => {
+      const result = renderWithProviders(
+        <Barcode
+          label="Barcode"
+          name="code"
+          barcodeIcon={barcodeIcon}
+          scanIcon={scanIcon}
+          stopIcon={stopIcon}
+        />,
+      );
+      expect(result.findTextElement("Barcode")).toBeDefined();
+    });
+
+    it("renders required label with asterisk", () => {
+      const result = renderWithProviders(
+        <Barcode
+          label="Required"
+          name="req"
+          barcodeIcon={barcodeIcon}
+          scanIcon={scanIcon}
+          stopIcon={stopIcon}
+          required
+        />,
+      );
+      const label = result.container.querySelector("label");
+      expect(label?.textContent).toContain("*");
+    });
+
+    it("renders with helper text", () => {
+      const result = renderWithProviders(
+        <Barcode
+          label="Code"
+          name="c"
+          barcodeIcon={barcodeIcon}
+          scanIcon={scanIcon}
+          stopIcon={stopIcon}
+          helperText="Scan or type a code"
+        />,
+      );
+      expect(result.findTextElement("Scan or type a code")).toBeDefined();
+    });
+
+    it("renders skeleton placeholder", () => {
+      const result = renderWithProviders(
+        <Barcode
+          label="Loading"
+          name="l"
+          barcodeIcon={barcodeIcon}
+          scanIcon={scanIcon}
+          stopIcon={stopIcon}
+          skeleton
+        />,
+      );
+      expect(result.container.querySelector("input")).toBeNull();
+    });
+
+    it("renders disabled state", () => {
+      const result = renderWithProviders(
+        <Barcode
+          label="Disabled"
+          name="d"
+          barcodeIcon={barcodeIcon}
+          scanIcon={scanIcon}
+          stopIcon={stopIcon}
+          disabled
+        />,
+      );
+      const input = result.container.querySelector("input");
+      expect(input?.getAttribute("aria-disabled")).toBe("true");
+    });
+
+    it("renders readOnly — hides scan button", () => {
+      const result = renderWithProviders(
+        <Barcode
+          label="ReadOnly"
+          name="r"
+          barcodeIcon={barcodeIcon}
+          scanIcon={scanIcon}
+          stopIcon={stopIcon}
+          readOnly
+          value="12345"
+        />,
+      );
+      expect(result.container.querySelectorAll("[data-testid='scan-icon']").length).toBe(0);
+    });
+  });
+
+  describe("with form context", () => {
+    it("renders inside form", () => {
+      const result = renderWithProviders(
+        <Form formOptions={{ defaultValues: { code: "" } }} submitText="Submit">
+          <Barcode
+            name="code"
+            label="Barcode"
+            barcodeIcon={barcodeIcon}
+            scanIcon={scanIcon}
+            stopIcon={stopIcon}
+          />
+        </Form>,
+      );
+      expect(result.findTextElement("Barcode")).toBeDefined();
+    });
+  });
+});

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

@@ -0,0 +1,157 @@
+import { action } from "@multiplatform.one/storybook";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { BarcodeIcon, CameraIcon, XIcon } from "@phosphor-icons/react";
+import { useForm } from "@tanstack/react-form";
+import { useState } from "react";
+import { Text, YStack } from "tamagui";
+import { Button } from "../../Button";
+import { Form } from "../../Form";
+import { Barcode } from "./index";
+
+const iconProps = {
+  barcodeIcon: <BarcodeIcon size={18} />,
+  scanIcon: <CameraIcon size={18} />,
+  stopIcon: <XIcon size={18} />,
+};
+
+const meta: Meta<typeof Barcode> = {
+  title: "Forms/Barcode",
+  component: Barcode,
+  parameters: {
+    docs: {
+      description: {
+        component: "A barcode input field with optional camera-based scanning via html5-qrcode.",
+      },
+    },
+  },
+  argTypes: {
+    label: { control: "text" },
+    helperText: { control: "text" },
+    error: { control: "text" },
+    required: { control: "boolean" },
+    disabled: { control: "boolean" },
+    size: { control: "select", options: ["$2", "$3", "$4"] },
+    value: { control: "text" },
+    enableScan: { control: "boolean", description: "Enable camera scanner" },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Barcode>;
+
+export const Main: Story = {
+  name: "Main",
+  render: () => {
+    const FormExample = () => {
+      const form = useForm({
+        defaultValues: {
+          barcode: "",
+        },
+        onSubmit: async ({ value }) => {
+          action("onSubmit")(value);
+        },
+      });
+
+      return (
+        <Form form={form} maxWidth={400}>
+          <YStack gap="$4">
+            <Barcode
+              label="Item Barcode"
+              name="barcode"
+              helperText="Scan or type the barcode"
+              enableScan
+              {...iconProps}
+            />
+            <Button action="submit">Look Up</Button>
+          </YStack>
+        </Form>
+      );
+    };
+    return <FormExample />;
+  },
+};
+
+export const Standalone: Story = {
+  args: {
+    label: "Barcode",
+    helperText: "Scan or enter barcode",
+    enableScan: true,
+  },
+  render: (args) => <Barcode {...args} {...iconProps} />,
+};
+
+export const Basic: Story = {
+  args: {
+    label: "Product Barcode",
+    helperText: "Enter or scan a barcode",
+    onChange: action("onChange"),
+  },
+  render: (args) => <Barcode {...args} {...iconProps} />,
+};
+
+export const Disabled: Story = {
+  args: {
+    label: "Product Barcode",
+    helperText: "This field is disabled",
+    disabled: true,
+    onChange: action("onChange"),
+  },
+  render: (args) => <Barcode {...args} {...iconProps} />,
+};
+
+export const WithError: Story = {
+  args: {
+    label: "Product Barcode",
+    helperText: "Enter or scan a barcode",
+    required: true,
+    error: "Barcode is required",
+    onChange: action("onChange"),
+  },
+  render: (args) => <Barcode {...args} {...iconProps} />,
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <YStack gap="$4" maxWidth={400}>
+      <Text fontWeight="bold">Size $2</Text>
+      <Barcode label="Small" size="$2" {...iconProps} onChange={action("onChange")} />
+      <Text fontWeight="bold">Size $3</Text>
+      <Barcode label="Medium" size="$3" {...iconProps} onChange={action("onChange")} />
+      <Text fontWeight="bold">Size $4</Text>
+      <Barcode label="Large" size="$4" {...iconProps} onChange={action("onChange")} />
+    </YStack>
+  ),
+};
+
+export const Interactive: Story = {
+  render: () => {
+    const InteractiveExample = () => {
+      const [value, setValue] = useState("");
+      return (
+        <YStack gap="$4" maxWidth={400}>
+          <Barcode
+            label="Scan Product"
+            helperText={value ? `Scanned: ${value}` : "Enter a barcode"}
+            value={value}
+            onChange={(v) => {
+              setValue(v);
+              action("onChange")(v);
+            }}
+            {...iconProps}
+          />
+          <Barcode
+            label="Without Camera"
+            enableScan={false}
+            value={value}
+            onChange={(v) => {
+              setValue(v);
+              action("onChange")(v);
+            }}
+            {...iconProps}
+          />
+        </YStack>
+      );
+    };
+    return <InteractiveExample />;
+  },
+};

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

@@ -0,0 +1,80 @@
+import { CameraView, useCameraPermissions } from "expo-camera";
+import { useEffect, useRef } from "react";
+import { StyleSheet } from "react-native";
+import { View, YStack } from "tamagui";
+import { formInputColors } from "../../shared/colorRamps";
+import type { BarcodeScannerProps } from "./scannerTypes";
+
+const barcodeTypes = [
+  "qr",
+  "ean13",
+  "ean8",
+  "code128",
+  "code39",
+  "code93",
+  "upc_a",
+  "upc_e",
+  "codabar",
+  "itf14",
+  "datamatrix",
+  "pdf417",
+  "aztec",
+] as const;
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+export function BarcodeScanner({
+  active,
+  onScan,
+  onError,
+  onClose,
+  knobProps,
+}: BarcodeScannerProps) {
+  const [permission, requestPermission] = useCameraPermissions();
+  const handledRef = useRef(false);
+
+  useEffect(() => {
+    if (!active) return;
+    handledRef.current = false;
+    onError(null);
+    if (permission && !permission.granted) {
+      requestPermission().then((res) => {
+        if (!res.granted) {
+          onError("Camera permission denied. Please allow camera access.");
+          onClose();
+        }
+      });
+    }
+  }, [active, permission?.granted]);
+
+  if (!active || !permission?.granted) return null;
+
+  return (
+    <YStack
+      {...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>
+    </YStack>
+  );
+}

package/src/fields/Barcode/BarcodeScanner.tsx

@@ -0,0 +1,96 @@
+import { useEffect, useRef } from "react";
+import { View, YStack } from "tamagui";
+import { formInputColors } from "../../shared/colorRamps";
+import type { BarcodeScannerProps } from "./scannerTypes";
+
+interface Html5QrcodeScanner {
+  start: (
+    cameraIdOrConfig: { facingMode: string },
+    config: { fps: number; qrbox: { width: number; height: number }; aspectRatio: number },
+    onSuccess: (decodedText: string) => void,
+    onError: () => void,
+  ) => Promise<void>;
+  stop: () => Promise<void>;
+  clear: () => void;
+  getState?: () => number;
+}
+
+/**
+ * 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.
+ */
+export function BarcodeScanner({
+  active,
+  onScan,
+  onError,
+  onClose,
+  knobProps,
+}: BarcodeScannerProps) {
+  const scannerRef = useRef<Html5QrcodeScanner | null>(null);
+  const containerId = useRef(`barcode-scanner-${Math.random().toString(36).slice(2, 9)}`);
+
+  useEffect(() => {
+    if (!active) return;
+    let cancelled = false;
+    onError(null);
+    (async () => {
+      try {
+        const { Html5Qrcode } = await import("html5-qrcode");
+        if (cancelled) return;
+        const scanner = new Html5Qrcode(containerId.current) as unknown as Html5QrcodeScanner;
+        scannerRef.current = scanner;
+        await scanner.start(
+          { facingMode: "environment" },
+          { fps: 10, qrbox: { width: 250, height: 150 }, aspectRatio: 1.5 },
+          (decodedText: string) => {
+            onScan(decodedText);
+            onClose();
+          },
+          () => {},
+        );
+      } 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();
+      }
+    })();
+    return () => {
+      cancelled = true;
+      const scanner = scannerRef.current;
+      if (scanner) {
+        try {
+          const state = scanner.getState?.();
+          if (state === 2 || state === undefined) scanner.stop().catch(() => {});
+        } catch {
+          /* ignore */
+        }
+        try {
+          scanner.clear();
+        } catch {
+          /* ignore */
+        }
+        scannerRef.current = null;
+      }
+    };
+  }, [active]);
+
+  if (!active) return null;
+
+  return (
+    <YStack
+      {...knobProps.borderRadius}
+      {...knobProps.inputSurface}
+      borderColor={formInputColors.border.base}
+      overflow="hidden"
+    >
+      <View id={containerId.current} width="100%" minHeight={250} />
+    </YStack>
+  );
+}