@multiplatform.one/forms 6.1.0 → 6.3.0

package/src/fieldLayout.dg.spec.tsx

@@ -0,0 +1,70 @@
+import { Input as TamaguiInput } from "tamagui";
+import { describe, expect, it } from "vitest";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { FieldLayout } from "./fieldLayout";
+import { RequiredMarkingContext } from "./requiredMarking";
+
+function labelText(container: HTMLElement): string {
+  const label = container.querySelector("label");
+  return label?.textContent ?? "";
+}
+
+describe("FieldLayout required marking (DG-FORM-05)", () => {
+  it("defaults to asterisk for required standalone fields", () => {
+    const { container } = renderWithProviders(
+      <FieldLayout id="a" label="Name" required>
+        <TamaguiInput id="a" />
+      </FieldLayout>,
+    );
+    expect(labelText(container)).toBe("Name *");
+  });
+
+  it("marks minority required via context", () => {
+    const { container } = renderWithProviders(
+      <RequiredMarkingContext.Provider value={{ mode: "required" }}>
+        <FieldLayout id="a" label="Code" required>
+          <TamaguiInput id="a" />
+        </FieldLayout>
+      </RequiredMarkingContext.Provider>,
+    );
+    expect(labelText(container)).toBe("Code (required)");
+  });
+
+  it("marks minority optional via context", () => {
+    const { container } = renderWithProviders(
+      <RequiredMarkingContext.Provider value={{ mode: "optional" }}>
+        <FieldLayout id="a" label="Notes" required={false}>
+          <TamaguiInput id="a" />
+        </FieldLayout>
+      </RequiredMarkingContext.Provider>,
+    );
+    expect(labelText(container)).toBe("Notes (optional)");
+  });
+
+  it("prop requiredMarking overrides context", () => {
+    const { container } = renderWithProviders(
+      <RequiredMarkingContext.Provider value={{ mode: "optional" }}>
+        <FieldLayout id="a" label="Name" required requiredMarking="asterisk">
+          <TamaguiInput id="a" />
+        </FieldLayout>
+      </RequiredMarkingContext.Provider>,
+    );
+    expect(labelText(container)).toBe("Name *");
+  });
+});
+
+describe("FieldLayout disabled labels (DG-FORM-12)", () => {
+  it("keeps label opacity at 1 when disabled", () => {
+    const { container } = renderWithProviders(
+      <FieldLayout id="d" label="Account" helperText="Locked" disabled>
+        <TamaguiInput id="d" disabled />
+      </FieldLayout>,
+    );
+    const label = container.querySelector("label") as HTMLElement | null;
+    expect(label).toBeTruthy();
+    expect(label?.textContent).toBe("Account");
+    // Contract: FieldLayout forces opacity=1 on wrapper + label (never inherits control dimming).
+    const labelOpacity = label?.style?.opacity || getComputedStyle(label!).opacity;
+    expect(Number(labelOpacity || "1")).toBe(1);
+  });
+});

package/src/fieldLayout.spec.tsx

@@ -0,0 +1,221 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Preset } from "@multiplatform.one/theme";
+import { Input as TamaguiInput } from "tamagui";
+import { FieldLayout } from "./fieldLayout";
+import { __resetDevWarnSeen } from "./shared/devWarn";
+
+function classIncludes(container: HTMLElement, fragment: string): boolean {
+  return Array.from(container.querySelectorAll("[class]")).some((el) =>
+    (el.getAttribute("class") ?? "").includes(fragment),
+  );
+}
+
+describe("FieldLayout width-by-purpose", () => {
+  it("applies maxWidth from purpose", () => {
+    const { container } = renderWithProviders(
+      <FieldLayout id="zip" label="ZIP" purpose="postalCode">
+        <TamaguiInput id="zip" />
+      </FieldLayout>,
+    );
+    expect(classIncludes(container, "_maw-12ch")).toBe(true);
+  });
+
+  it("applies maxWidth from autoComplete when purpose omitted", () => {
+    const { container } = renderWithProviders(
+      <FieldLayout id="em" label="Email" autoComplete="email">
+        <TamaguiInput id="em" />
+      </FieldLayout>,
+    );
+    expect(classIncludes(container, "_maw-24ch")).toBe(true);
+  });
+
+  it("stretches description to full width", () => {
+    const { container } = renderWithProviders(
+      <FieldLayout id="desc" label="Notes" purpose="description">
+        <TamaguiInput id="desc" />
+      </FieldLayout>,
+    );
+    // Tamagui atomic classes: width/maxWidth 100% → `_w-100%` / `_maw-100%`
+    // (or a hashed sibling); match the shared `100` token.
+    expect(classIncludes(container, "_w-100")).toBe(true);
+    expect(classIncludes(container, "_maw-100")).toBe(true);
+  });
+
+  it("lets explicit maxWidth eject purpose defaults", () => {
+    const { container } = renderWithProviders(
+      <FieldLayout id="zip" label="ZIP" purpose="postalCode" maxWidth={200}>
+        <TamaguiInput id="zip" />
+      </FieldLayout>,
+    );
+    expect(classIncludes(container, "_maw-12ch")).toBe(false);
+    expect(classIncludes(container, "_maw-200px")).toBe(true);
+  });
+});
+
+describe("FieldLayout placeholder-as-label DEV warn", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    __resetDevWarnSeen();
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    __resetDevWarnSeen();
+  });
+
+  it("warns when placeholder is set without label or aria-label", () => {
+    renderWithProviders(
+      <FieldLayout id="x" placeholder="Your name">
+        <TamaguiInput id="x" placeholder="Your name" />
+      </FieldLayout>,
+    );
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("placeholder-as-label"));
+  });
+
+  it("does not warn when a visible label is present", () => {
+    renderWithProviders(
+      <FieldLayout id="x" label="Name" placeholder="Your name">
+        <TamaguiInput id="x" placeholder="Your name" />
+      </FieldLayout>,
+    );
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("does not warn when aria-label is present", () => {
+    renderWithProviders(
+      <FieldLayout id="x" placeholder="Search" aria-label="Search documents">
+        <TamaguiInput id="x" placeholder="Search" aria-label="Search documents" />
+      </FieldLayout>,
+    );
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("does not warn when placeholder is omitted", () => {
+    renderWithProviders(
+      <FieldLayout id="x">
+        <TamaguiInput id="x" />
+      </FieldLayout>,
+    );
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("FieldLayout disabledStyle house knob", () => {
+  it("keepLabel does not dim the field when disabled", () => {
+    const { container } = renderWithProviders(
+      <Preset overrides={{ disabledStyle: "keepLabel" }}>
+        <FieldLayout id="name" label="Name" disabled>
+          <TamaguiInput id="name" disabled />
+        </FieldLayout>
+      </Preset>,
+    );
+    const root = container.querySelector("[data-disabled-style='keepLabel']");
+    expect(root?.getAttribute("data-disabled-dimmed")).toBe("false");
+    expect(container.querySelector("label")?.textContent).toContain("Name");
+  });
+
+  it("dimWhole dims the whole field (including label) when disabled", () => {
+    const { container } = renderWithProviders(
+      <Preset overrides={{ disabledStyle: "dimWhole" }}>
+        <FieldLayout id="name" label="Name" disabled>
+          <TamaguiInput id="name" disabled />
+        </FieldLayout>
+      </Preset>,
+    );
+    const root = container.querySelector("[data-disabled-style='dimWhole']");
+    expect(root?.getAttribute("data-disabled-dimmed")).toBe("true");
+  });
+
+  it("does not dim when disabledStyle is dimWhole but control is enabled", () => {
+    const { container } = renderWithProviders(
+      <Preset overrides={{ disabledStyle: "dimWhole" }}>
+        <FieldLayout id="name" label="Name">
+          <TamaguiInput id="name" />
+        </FieldLayout>
+      </Preset>,
+    );
+    const root = container.querySelector("[data-disabled-style='dimWhole']");
+    expect(root?.getAttribute("data-disabled-dimmed")).toBe("false");
+  });
+});
+
+describe("FieldLayout error precedence (Axiom 5 eject-last)", () => {
+  function makeField(errors: string[]) {
+    return { state: { meta: { errors } } } as any;
+  }
+
+  it("explicit error prop wins over field-meta errors", () => {
+    const { container } = renderWithProviders(
+      <FieldLayout id="p" label="Name" error="Name is taken" field={makeField(["Enter a name"])}>
+        <TamaguiInput id="p" />
+      </FieldLayout>,
+    );
+    const alert = container.querySelector("[role='alert']");
+    expect(alert?.textContent).toBe("Name is taken");
+    expect(container.textContent).not.toContain("Enter a name");
+  });
+
+  it("falls back to field-meta errors when no error prop", () => {
+    const { container } = renderWithProviders(
+      <FieldLayout id="f" label="Name" field={makeField(["Enter a name"])}>
+        <TamaguiInput id="f" />
+      </FieldLayout>,
+    );
+    expect(container.querySelector("[role='alert']")?.textContent).toBe("Enter a name");
+  });
+
+  it("error={false} ejects: suppresses field-meta errors", () => {
+    const { container } = renderWithProviders(
+      <FieldLayout id="s" label="Name" error={false} field={makeField(["Enter a name"])}>
+        <TamaguiInput id="s" />
+      </FieldLayout>,
+    );
+    expect(container.querySelector("[role='alert']")).toBeNull();
+    expect(container.textContent).not.toContain("Enter a name");
+  });
+
+  it("error replaces helper in the reserved slot", () => {
+    const { container } = renderWithProviders(
+      <FieldLayout id="h" label="Name" helperText="Helper" error="Enter a name">
+        <TamaguiInput id="h" />
+      </FieldLayout>,
+    );
+    expect(container.querySelector("[role='alert']")?.textContent).toBe("Enter a name");
+    expect(container.textContent).not.toContain("Helper");
+  });
+});
+
+describe("FieldLayout banned-error-word DEV warn", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    __resetDevWarnSeen();
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    __resetDevWarnSeen();
+  });
+
+  it("warns when error copy uses banned wording", () => {
+    renderWithProviders(
+      <FieldLayout id="email" label="Email" error="Invalid email, please try again">
+        <TamaguiInput id="email" />
+      </FieldLayout>,
+    );
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("banned-error-word"));
+  });
+
+  it("is silent for clean error copy", () => {
+    renderWithProviders(
+      <FieldLayout id="email" label="Email" error="Enter an email address">
+        <TamaguiInput id="email" />
+      </FieldLayout>,
+    );
+    expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("banned-error-word"));
+  });
+});

package/src/fieldLayout.tsx

@@ -3,10 +3,19 @@ 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 { createContext, useContext, useEffect, useMemo } from "react";
+import { AccessibilityInfo } from "react-native";
 import type { FontSizeTokens, LabelProps, SizeTokens, YStackProps } from "tamagui";
-import { Label, Paragraph, YStack } from "tamagui";
+import { isWeb, Label, Paragraph, XStack, YStack } from "tamagui";
+import { fieldWidthStyle } from "./fieldDefaults";
+import {
+  formatRequiredMarkSuffix,
+  mapHouseRequiredMarking,
+  type RequiredMarkMode,
+  useRequiredMarking,
+} from "./requiredMarking";
 import { formCommonColors } from "./shared/colorRamps";
+import { warnBannedErrorWords, warnPlaceholderAsLabel } from "./shared/devWarn";
 import type { AnyFormApi, SimpleFieldApi } from "./types";
 
 const FieldDescribedByContext = createContext<string | undefined>(undefined);
@@ -14,6 +23,25 @@ export function useFieldDescribedBy() {
   return useContext(FieldDescribedByContext);
 }
 
+/**
+ * Accessible-name STRINGS for the current field. The id-based wiring above
+ * (`aria-labelledby` / `aria-describedby` / `htmlFor`) is web-only — iOS has
+ * no equivalent, so native controls consume these strings directly as
+ * `accessibilityLabel` / `accessibilityHint`.
+ */
+export interface FieldA11y {
+  /** Visible label text incl. required mark (only when the label is a string). */
+  label?: string;
+  /** Error message when present, else helper text — VoiceOver hint. */
+  description?: string;
+  required?: boolean;
+}
+
+const FieldA11yContext = createContext<FieldA11y | undefined>(undefined);
+export function useFieldA11y() {
+  return useContext(FieldA11yContext);
+}
+
 // ── Helper ────────────────────────────────────────────────────────────────────
 
 function getHelperTextSize(size?: SizeTokens): FontSizeTokens {
@@ -74,6 +102,16 @@ export interface FieldLayoutProps {
   >;
   helperText?: string;
   required?: boolean;
+  /**
+   * Required/optional mark mode (DG-FORM-05). Prefers form/schema context
+   * from {@link useRequiredMarking}; defaults to `"asterisk"` standalone.
+   */
+  requiredMarking?: RequiredMarkMode;
+  /**
+   * When true, the *control* is disabled — the Field label and helper stay
+   * fully opaque/readable (DG-FORM-12). Never dims the FieldLayout wrapper.
+   */
+  disabled?: boolean;
   size?: SizeTokens;
   knobProps?: KnobProps;
   onBlur?: (...args: any[]) => void;
@@ -83,6 +121,30 @@ export interface FieldLayoutProps {
    * is beside the control rather than above it.
    */
   compactSpacing?: boolean;
+  /**
+   * Semantic content purpose (DG-FORM-07). Drives default maxWidth in `ch`
+   * via `FIELD_WIDTH_BY_PURPOSE`. Explicit `maxWidth` / `width` eject.
+   */
+  purpose?: string;
+  /**
+   * HTML autocomplete token. When `purpose` is omitted, maps to a purpose
+   * (e.g. `postal-code` → postalCode) for default width.
+   */
+  autoComplete?: string;
+  /**
+   * Placeholder on the inner control — used only for the DEV
+   * placeholder-as-label guardrail (DG-FORM-02 / DG-FORM-11). Not rendered.
+   */
+  placeholder?: string;
+  /**
+   * Accessible name when there is no visible label. Suppresses the
+   * placeholder-as-label DEV warning when set.
+   */
+  "aria-label"?: string;
+  /** Eject: override purpose-derived maxWidth. */
+  maxWidth?: number | string;
+  /** Eject: override purpose-derived width. */
+  width?: number | string;
   children: ReactNode;
 }
 
@@ -94,23 +156,67 @@ export function FieldLayout({
   field,
   helperText,
   required,
+  requiredMarking: requiredMarkingProp,
+  disabled: _disabled,
   size,
   knobProps: knobPropsProp,
   onBlur,
   compactSpacing,
+  purpose,
+  autoComplete,
+  placeholder,
+  "aria-label": ariaLabel,
+  maxWidth,
+  width,
   children,
 }: FieldLayoutProps) {
-  const { knobProps: resolvedKnobs } = useResolvedKnobs();
+  const { knobProps: resolvedKnobs, disabledState } = useResolvedKnobs();
   const knobProps = knobPropsProp ?? resolvedKnobs;
-  const error = field?.state.meta.errors.length ? String(field.state.meta.errors[0]) : propError;
+  const markingCtx = useRequiredMarking();
+  const markMode: RequiredMarkMode =
+    requiredMarkingProp ?? markingCtx?.mode ?? mapHouseRequiredMarking(knobProps.requiredMarking);
+  const requiredSuffix = formatRequiredMarkSuffix(required, markMode);
+  // Axiom 5 eject-last: an explicit consumer `error` prop is an eject and wins
+  // over field-meta errors — same contract as getFieldError (shared/utils.ts).
+  const fieldError = field?.state.meta.errors.length
+    ? String(field.state.meta.errors[0])
+    : undefined;
+  const error = propError ?? fieldError;
   const errorMessage = typeof error === "string" && error.length > 0 ? error : undefined;
   const hasErrorState = Boolean(error);
   const helperSize = getHelperTextSize(size || knobProps.sizeToken);
+  const disabledStyle = knobProps.disabledStyle ?? "keepLabel";
+  const dimWhole = Boolean(_disabled) && disabledStyle === "dimWhole";
+  const keepLabelReadable = Boolean(_disabled) && disabledStyle !== "dimWhole";
+  const labelPlacement = knobProps.fieldLabelPlacement ?? "top";
+  const sideLabel = labelPlacement === "side" && Boolean(label) && !compactSpacing;
+
+  warnPlaceholderAsLabel({
+    placeholder,
+    label,
+    ariaLabel,
+    id,
+    component: "FieldLayout",
+  });
+  if (errorMessage) {
+    warnBannedErrorWords(errorMessage, { component: "FieldLayout", id });
+  }
 
   // Use compact gap for inline-label fields (checkbox, switch) or when explicitly requested
   const useCompact = compactSpacing || !label;
   const gapProps = useCompact ? { gap: "$1" } : knobProps.gap;
 
+  // Purpose / autocomplete → default width; explicit maxWidth/width win.
+  const purposeWidth =
+    maxWidth !== undefined || width !== undefined
+      ? undefined
+      : fieldWidthStyle(purpose, autoComplete);
+  const widthProps = {
+    ...purposeWidth,
+    ...(maxWidth !== undefined ? { maxWidth } : {}),
+    ...(width !== undefined ? { width } : {}),
+  };
+
   const describedBy =
     [
       helperText && id ? `${id}-description` : undefined,
@@ -119,45 +225,102 @@ export function FieldLayout({
       .filter(Boolean)
       .join(" ") || undefined;
 
+  const a11yLabel = typeof label === "string" ? `${label}${requiredSuffix}` : ariaLabel;
+  const a11yDescription = errorMessage ?? helperText;
+  const fieldA11y = useMemo<FieldA11y>(
+    () => ({ label: a11yLabel, description: a11yDescription, required }),
+    [a11yLabel, a11yDescription, required],
+  );
+
+  // iOS has no aria-live regions — speak new errors explicitly. Web keeps the
+  // role="alert" / aria-live wiring on the error Paragraph below.
+  useEffect(() => {
+    if (!isWeb && errorMessage) {
+      AccessibilityInfo.announceForAccessibility(errorMessage);
+    }
+  }, [errorMessage]);
+
+  const labelNode = label ? (
+    <Label
+      id={id ? `${id}-label` : undefined}
+      htmlFor={id}
+      size={size || knobProps.sizeToken}
+      {...knobProps.body}
+      color={hasErrorState ? formCommonColors.error : knobProps.textAccentColor}
+      opacity={keepLabelReadable ? 1 : undefined}
+      flexShrink={sideLabel ? 0 : undefined}
+      {...labelProps}
+    >
+      {label}
+      {requiredSuffix}
+    </Label>
+  ) : null;
+
+  const helperNode =
+    helperText && !errorMessage ? (
+      <Paragraph
+        id={id ? `${id}-description` : undefined}
+        size={helperSize}
+        {...knobProps.body}
+        color={formCommonColors.text}
+        opacity={keepLabelReadable ? 1 : undefined}
+      >
+        {helperText}
+      </Paragraph>
+    ) : null;
+
+  const errorNode = errorMessage ? (
+    <Paragraph
+      id={id ? `${id}-error` : undefined}
+      size={helperSize}
+      {...knobProps.body}
+      color={formCommonColors.error}
+      role="alert"
+      aria-live="polite"
+    >
+      {errorMessage}
+    </Paragraph>
+  ) : null;
+
+  const controlColumn = (
+    <YStack flex={sideLabel ? 1 : undefined} {...gapProps}>
+      {children}
+      {helperNode}
+      {errorNode}
+    </YStack>
+  );
+
   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>
+      <FieldA11yContext.Provider value={fieldA11y}>
+        <YStack
+          theme={hasErrorState ? "red" : undefined}
+          // LC-40: the assembly-wide dim (label included) rides the resolved
+          // recipe and is populated only under `dimWhole`; `keepLabel`
+          // treatment lives on the control chrome itself.
+          opacity={1}
+          {...(dimWhole ? disabledState.assemblyKnobProps : undefined)}
+          {...(sideLabel ? {} : gapProps)}
+          {...widthProps}
+          onBlur={onBlur}
+          data-disabled-style={disabledStyle}
+          data-disabled-dimmed={dimWhole ? "true" : "false"}
+        >
+          {sideLabel ? (
+            <XStack alignItems="flex-start" gap="$3" width="100%">
+              {labelNode}
+              {controlColumn}
+            </XStack>
+          ) : (
+            <>
+              {labelNode}
+              {children}
+              {helperNode}
+              {errorNode}
+            </>
+          )}
+        </YStack>
+      </FieldA11yContext.Provider>
     </FieldDescribedByContext.Provider>
   );
 }

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

@@ -1,6 +1,8 @@
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
+import { fireEvent, waitFor } from "@testing-library/react";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { Form } from "../../Form";
+import { preflightCamera } from "./BarcodeScanner";
 import { Barcode } from "./index";
 
 const barcodeIcon = <span data-testid="barcode-icon" />;
@@ -80,6 +82,27 @@ describe("Barcode", () => {
       expect(input?.getAttribute("aria-disabled")).toBe("true");
     });
 
+    it("bare use renders complete affordances via package icon defaults (UX-010)", () => {
+      const result = renderWithProviders(<Barcode label="No icons" name="ni" />);
+      // Scan button carries the default camera glyph (icon button, named).
+      const button = result.container.querySelector("[aria-label='Scan barcode']");
+      expect(button).not.toBeNull();
+      expect(button?.querySelector("svg")).not.toBeNull();
+      // Leading adornment slot renders the default barcode glyph.
+      const box = result.container.querySelector("input")?.closest("[class*='is_Input']");
+      expect(result.container.querySelectorAll("svg").length).toBeGreaterThanOrEqual(2);
+      expect(box).not.toBeNull();
+    });
+
+    it("explicit null icons fall back to a labeled text scan button (no bare box)", () => {
+      const result = renderWithProviders(
+        <Barcode label="No icons" name="ni" barcodeIcon={null} scanIcon={null} stopIcon={null} />,
+      );
+      const button = result.container.querySelector("[aria-label='Scan barcode']");
+      expect(button).not.toBeNull();
+      expect(button?.textContent).toContain("Scan");
+    });
+
     it("renders readOnly — hides scan button", () => {
       const result = renderWithProviders(
         <Barcode
@@ -96,6 +119,39 @@ describe("Barcode", () => {
     });
   });
 
+  describe("camera pre-flight (LC-19 CAPABILITY-PREFLIGHT)", () => {
+    it("preflightCamera fails when no camera capability exists", async () => {
+      // jsdom has no navigator.mediaDevices — pre-flight must fail, not throw
+      const result = await preflightCamera();
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.reason).toContain("Camera unavailable");
+    });
+
+    it("scan press without camera shows inline error and never mounts the scanner", async () => {
+      const result = renderWithProviders(
+        <Barcode
+          label="Scan"
+          name="s"
+          barcodeIcon={barcodeIcon}
+          scanIcon={scanIcon}
+          stopIcon={stopIcon}
+        />,
+      );
+      const button = result.container.querySelector("[aria-label='Scan barcode']");
+      expect(button).not.toBeNull();
+      fireEvent.click(button as Element);
+      await waitFor(() => {
+        expect(result.container.textContent).toContain("Camera unavailable");
+      });
+      // The scanner surface must never have mounted (no mount-fail-unmount)
+      expect(result.container.querySelector("[data-testid='barcode-scanner-popup']")).toBeNull();
+      // Manual entry stays usable and the scan button stays enabled
+      const input = result.container.querySelector("input");
+      expect(input).not.toBeNull();
+      expect((button as HTMLElement).getAttribute("aria-disabled")).not.toBe("true");
+    });
+  });
+
   describe("with form context", () => {
     it("renders inside form", () => {
       const result = renderWithProviders(