@multiplatform.one/forms 6.1.0 → 6.3.0

package/src/fields/Barcode/index.tsx

@@ -1,13 +1,15 @@
-import type { KnobProps } from "@multiplatform.one/theme";
+import type { ControlStateProps, KnobProps } from "@multiplatform.one/theme";
+import { ensureFocusVisibleRing } from "@multiplatform.one/theme";
+import { BarcodeIcon, CameraIcon, XIcon } from "@phosphor-icons/react";
 import type { ReactNode } from "react";
-import { useState } from "react";
+import { useRef, useState } from "react";
 import type { LabelProps, SizeTokens } from "tamagui";
 import { Text, View } from "tamagui";
 import { Button } from "../../Button";
 import { ControlGroup } from "../../ControlGroup";
 import { Skeleton } from "../../Skeleton";
 import { Field, FieldLayout } from "../../fieldLayout";
-import { Input as InputParts } from "../../InputParts";
+import { FocusContext, Input as InputParts } from "../../InputParts";
 import { formCommonColors } from "../../shared/colorRamps";
 import {
   getFieldError,
@@ -15,8 +17,17 @@ import {
   useFormField,
   useResolvedValidators,
 } from "../../shared/utils";
+import { t } from "../../shared/t";
 import type { AnyFormApi } from "../../types";
-import { BarcodeScanner } from "./BarcodeScanner";
+import { BarcodeScanner, preflightCamera } from "./BarcodeScanner";
+
+/**
+ * The knob focus ring must be CSS-driven on the focused input itself
+ * (DG-A11Y-01): Input.Box paints its ring from React `focused` state one
+ * frame after focus, which synchronous a11y probes never see. Same
+ * OTP/Stepper/Input template — Box ring suppressed, ring lives on the Area.
+ */
+const suppressBoxFocusRing = { focused: false, setFocused: (_val: boolean) => {} };
 
 function BarcodeInput({
   value,
@@ -25,11 +36,14 @@ function BarcodeInput({
   readOnly,
   enableScan,
   knobProps,
+  areaFocusRing,
   barcodeIcon,
   scanIcon,
   stopIcon,
   required,
   hasError,
+  id,
+  hasLabel,
 }: {
   value: string;
   onValueChange: (v: string) => void;
@@ -37,14 +51,43 @@ function BarcodeInput({
   readOnly: boolean;
   enableScan: boolean;
   knobProps: KnobProps;
-  barcodeIcon: ReactNode;
-  scanIcon: ReactNode;
-  stopIcon: ReactNode;
+  areaFocusRing: ControlStateProps;
+  barcodeIcon?: ReactNode;
+  scanIcon?: ReactNode;
+  stopIcon?: ReactNode;
   required?: boolean;
   hasError?: boolean;
+  id?: string;
+  hasLabel?: boolean;
 }) {
   const [isScanning, setIsScanning] = useState(false);
   const [scanError, setScanError] = useState<string | null>(null);
+  const preflightingRef = useRef(false);
+  const activeScanIcon = isScanning ? stopIcon : scanIcon;
+
+  // LC-19 CAPABILITY-PREFLIGHT: verify camera availability BEFORE presenting
+  // the scanner surface. Pre-flight failure renders an inline error at the
+  // field and the surface never mounts (no mount-fail-unmount flicker). The
+  // scan button stays enabled — pressing it again re-runs the pre-flight.
+  const handleScanPress = async () => {
+    if (isScanning) {
+      setIsScanning(false);
+      return;
+    }
+    if (preflightingRef.current) return;
+    preflightingRef.current = true;
+    try {
+      const result = await preflightCamera();
+      if (result.ok) {
+        setScanError(null);
+        setIsScanning(true);
+      } else {
+        setScanError(result.reason);
+      }
+    } finally {
+      preflightingRef.current = false;
+    }
+  };
 
   return (
     <>
@@ -52,27 +95,40 @@ function BarcodeInput({
         <ControlGroup>
           <View width={0} />
           <InputParts.Box>
-            <InputParts.Icon adornment="leading">{barcodeIcon}</InputParts.Icon>
-            <InputParts.Area
-              value={value}
-              onChangeText={readOnly ? undefined : onValueChange}
-              readOnly={readOnly}
-              aria-readonly={readOnly || undefined}
-              placeholder="Enter or scan barcode"
-              disabled={disabled}
-              aria-required={required || undefined}
-              aria-invalid={hasError || undefined}
-            />
+            {barcodeIcon ? (
+              <InputParts.Icon adornment="leading">{barcodeIcon}</InputParts.Icon>
+            ) : null}
+            <FocusContext.Provider {...suppressBoxFocusRing}>
+              <InputParts.Area
+                id={id}
+                value={value}
+                onChangeText={readOnly ? undefined : onValueChange}
+                readOnly={readOnly}
+                aria-readonly={readOnly || undefined}
+                placeholder={t("Enter or scan barcode")}
+                disabled={disabled}
+                focusStyle={areaFocusRing}
+                focusVisibleStyle={areaFocusRing}
+                aria-labelledby={hasLabel && id ? `${id}-label` : undefined}
+                aria-label={hasLabel ? undefined : t("Barcode")}
+                aria-required={required || undefined}
+                aria-invalid={hasError || undefined}
+              />
+            </FocusContext.Provider>
           </InputParts.Box>
           {enableScan && !readOnly ? (
+            // Icon when provided; otherwise a text label — an icon-less Button
+            // renders as a bare colored box (looks like a stuck skeleton).
             <Button
               size={knobProps.sizeToken}
               disabled={disabled}
-              onPress={() => setIsScanning((s) => !s)}
-              icon={isScanning ? stopIcon : scanIcon}
+              onPress={handleScanPress}
+              {...(activeScanIcon ? { icon: activeScanIcon } : undefined)}
               {...(isScanning ? { theme: "red" } : undefined)}
-              aria-label={isScanning ? "Stop scanning" : "Scan barcode"}
-            />
+              aria-label={isScanning ? t("Stop scanning") : t("Scan barcode")}
+            >
+              {activeScanIcon ? undefined : isScanning ? t("Stop") : t("Scan")}
+            </Button>
           ) : (
             <View width={0} />
           )}
@@ -113,15 +169,32 @@ export interface BarcodeProps {
   readOnly?: boolean;
   enableScan?: boolean;
   formats?: string[];
-  barcodeIcon: ReactNode;
-  scanIcon: ReactNode;
-  stopIcon: ReactNode;
+  /**
+   * Leading input adornment. Optional — bare use falls back to the package
+   * barcode glyph (Phosphor, the house icon set) so core affordances render
+   * without icon wiring (Axiom 13 ONE BODY). Pass `null` to opt out of the
+   * adornment slot entirely.
+   */
+  barcodeIcon?: ReactNode;
+  /**
+   * Scan/stop button icons. Optional — default to the package camera/close
+   * glyphs. Pass `null` to fall back to the text-label button.
+   */
+  scanIcon?: ReactNode;
+  stopIcon?: ReactNode;
   /** When true, renders a skeleton placeholder instead of the barcode field */
   skeleton?: boolean;
   /** When true, uses compact sizing */
   compact?: boolean;
 }
 
+// Package icon defaults (UX-010): React elements are immutable descriptors,
+// so module-level sharing is safe. `undefined` picks these up; explicit
+// `null` opts out (adornment slot / text-label button).
+const defaultBarcodeIcon = <BarcodeIcon size={18} />;
+const defaultScanIcon = <CameraIcon size={18} />;
+const defaultStopIcon = <XIcon size={18} />;
+
 export function Barcode({
   name,
   form: formProp,
@@ -140,14 +213,23 @@ export function Barcode({
   disabled,
   readOnly,
   enableScan = true,
-  barcodeIcon,
-  scanIcon,
-  stopIcon,
+  barcodeIcon = defaultBarcodeIcon,
+  scanIcon = defaultScanIcon,
+  stopIcon = defaultStopIcon,
   skeleton,
   compact,
 }: BarcodeProps) {
-  const { resolvedForm, knobProps, id } = useFormField({ form: formProp, id: idProp, compact });
+  const { resolvedForm, knobProps, control, id } = useFormField({
+    form: formProp,
+    id: idProp,
+    compact,
+  });
   const resolvedValidators = useResolvedValidators(required, validators, label, name);
+  // Inset (-2) keeps the ring inside the Box chrome (OTP/Stepper template).
+  const areaFocusRing = ensureFocusVisibleRing({
+    ...control.focusVisibleKnobProps,
+    outlineOffset: -2,
+  });
 
   const iconProps = { barcodeIcon, scanIcon, stopIcon };
 
@@ -172,6 +254,9 @@ export function Barcode({
         size={size}
         knobProps={knobProps}
         onBlur={onBlur}
+        // LC-40: FieldLayout owns the dimWhole assembly dim (keepLabel pins
+        // the sibling label/helper readable) — it needs the disabled state.
+        disabled={disabled}
       >
         <BarcodeInput
           value={value ?? (defaultValue as string) ?? ""}
@@ -182,8 +267,11 @@ export function Barcode({
           readOnly={!!readOnly}
           enableScan={enableScan}
           knobProps={knobProps}
+          areaFocusRing={areaFocusRing}
           required={required}
           hasError={!!error}
+          id={id}
+          hasLabel={Boolean(label)}
           {...iconProps}
         />
       </FieldLayout>
@@ -210,6 +298,8 @@ export function Barcode({
             size={size}
             knobProps={knobProps}
             onBlur={mergeFieldHandler(field, "handleBlur", onBlur)}
+            // LC-40: see standalone branch — FieldLayout carries dimWhole.
+            disabled={disabled}
           >
             <BarcodeInput
               value={(field.state.value as string) ?? ""}
@@ -222,8 +312,11 @@ export function Barcode({
               readOnly={!!readOnly}
               enableScan={enableScan}
               knobProps={knobProps}
+              areaFocusRing={areaFocusRing}
               required={required}
               hasError={!!resolvedError}
+              id={id}
+              hasLabel={Boolean(label)}
               {...iconProps}
             />
           </FieldLayout>

package/src/fields/Barcode/scannerTypes.ts

@@ -1,4 +1,5 @@
 import type { KnobProps } from "@multiplatform.one/theme";
+import type { CapabilityPreflightResult } from "../../shared/capabilityPreflight";
 
 export interface BarcodeScannerProps {
   /** When true, the camera scanner is active and rendered. */
@@ -7,7 +8,20 @@ export interface BarcodeScannerProps {
   onScan: (value: string) => void;
   /** Report a scanner error message (or null to clear). */
   onError: (message: string | null) => void;
-  /** Called after a successful scan or unrecoverable error to deactivate. */
+  /**
+   * Called after a successful scan or when the user closes the scanner.
+   * Never called by the scanner itself on error — init failures render
+   * INSIDE the still-open panel with Retry/Close (LC-19 CAPABILITY-PREFLIGHT).
+   */
   onClose: () => void;
   knobProps: KnobProps;
 }
+
+/**
+ * Result of the camera capability pre-flight (LC-19 CAPABILITY-PREFLIGHT).
+ * `ok: false` means the scanner surface must NOT be presented; `reason` is the
+ * user-facing message for the field's inline error slot. A passing pre-flight
+ * may still need to prompt for permission — that prompt happens INSIDE the
+ * stable scanner surface, never as a mount-fail-unmount.
+ */
+export type CameraPreflightResult = CapabilityPreflightResult;

package/src/fields/Checkbox/Checkbox.spec.tsx

@@ -44,6 +44,82 @@ describe("Checkbox", () => {
       if (checkbox) fireEvent.click(checkbox);
       expect(onCheckedChange).toHaveBeenCalledWith(true);
     });
+
+    it("fires canonical onChange and the deprecated onCheckedChange alias once each", () => {
+      const onChange = vi.fn();
+      const onCheckedChange = vi.fn();
+      const result = renderWithProviders(
+        <Checkbox
+          name="cb"
+          defaultValue={false}
+          onChange={onChange}
+          onCheckedChange={onCheckedChange}
+        />,
+      );
+      const checkbox = result.getCheckbox();
+      if (checkbox) fireEvent.click(checkbox);
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith(true);
+      expect(onCheckedChange).toHaveBeenCalledTimes(1);
+      expect(onCheckedChange).toHaveBeenCalledWith(true);
+    });
+  });
+
+  // Regression: the check glyph must actually render (and be visible) when
+  // checked — aria-checked alone is not enough. Guards against silent icon
+  // regressions (renamed/missing icon import rendering null) and
+  // stuck-hidden indicators. See p-results/fix-checkbox-glyph.md.
+  describe("check indicator glyph", () => {
+    /** Presence + computed visibility of the indicator glyph, not just mount. */
+    function expectVisibleGlyph(checkbox: Element) {
+      const svg = checkbox.querySelector("svg");
+      expect(svg, "indicator svg must render inside role=checkbox").toBeTruthy();
+      // phosphor icons draw with <path>; an empty svg means a broken icon import
+      expect(svg!.querySelector("path"), "indicator svg must have path content").toBeTruthy();
+      let node: Element | null = svg!;
+      while (node && node !== checkbox.parentElement) {
+        const style = getComputedStyle(node);
+        expect(style.display, "indicator ancestry must not be display:none").not.toBe("none");
+        expect(style.visibility, "indicator ancestry must not be hidden").not.toBe("hidden");
+        if (style.opacity !== "") {
+          expect(
+            Number(style.opacity),
+            "indicator ancestry must not be transparent",
+          ).toBeGreaterThan(0.05);
+        }
+        node = node.parentElement;
+      }
+    }
+
+    it("renders a visible check glyph when checked", () => {
+      const result = renderWithProviders(<Checkbox label="Checked" name="c" checked />);
+      const checkbox = result.getCheckbox();
+      expect(checkbox).toBeTruthy();
+      expectVisibleGlyph(checkbox!);
+    });
+
+    it("renders no glyph when unchecked", () => {
+      const result = renderWithProviders(<Checkbox label="Unchecked" name="u" checked={false} />);
+      const checkbox = result.getCheckbox();
+      expect(checkbox?.querySelector("svg")).toBeNull();
+    });
+
+    it("glyph appears after toggling via click", () => {
+      const result = renderWithProviders(<Checkbox label="Toggle" name="t" defaultValue={false} />);
+      const checkbox = result.getCheckbox();
+      expect(checkbox?.querySelector("svg")).toBeNull();
+      if (checkbox) fireEvent.click(checkbox);
+      expectVisibleGlyph(result.getCheckbox()!);
+    });
+
+    it("renders a visible glyph when indeterminate", () => {
+      const result = renderWithProviders(
+        <Checkbox label="Mixed" name="m" checked="indeterminate" />,
+      );
+      const checkbox = result.getCheckbox();
+      expect(checkbox?.getAttribute("aria-checked")).toBe("mixed");
+      expectVisibleGlyph(checkbox!);
+    });
   });
 
   describe("with form context", () => {
@@ -74,6 +150,27 @@ describe("CheckboxGroup", () => {
     expect(result.findTextElement("Option C")).toBeDefined();
   });
 
+  it("fires canonical onChange and the deprecated onValueChange alias once each", () => {
+    const onChange = vi.fn();
+    const onValueChange = vi.fn();
+    const result = renderWithProviders(
+      <CheckboxGroup
+        label="Pick options"
+        name="opts"
+        options={options}
+        onChange={onChange}
+        onValueChange={onValueChange}
+      />,
+    );
+    const checkbox = result.container.querySelector("[role='checkbox']");
+    expect(checkbox).toBeTruthy();
+    if (checkbox) fireEvent.click(checkbox);
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenCalledWith(["a"]);
+    expect(onValueChange).toHaveBeenCalledTimes(1);
+    expect(onValueChange).toHaveBeenCalledWith(["a"]);
+  });
+
   it("renders required label with asterisk", () => {
     const result = renderWithProviders(
       <CheckboxGroup label="Required" name="req" options={options} required />,
@@ -98,4 +195,65 @@ describe("CheckboxGroup", () => {
     );
     expect(result.findTextElement("Option A")).toBeDefined();
   });
+
+  describe("card mode (LC-22 SELECTION-CARD)", () => {
+    const cardOptions = [
+      { label: "Card A", value: "a", description: "Description for A" },
+      { label: "Card B", value: "b" },
+    ];
+
+    it("renders option descriptions in card mode", () => {
+      const result = renderWithProviders(
+        <CheckboxGroup label="Pick" name="opts" card options={cardOptions} />,
+      );
+      expect(result.findTextElement("Card A")).toBeDefined();
+      expect(result.findTextElement("Description for A")).toBeDefined();
+    });
+
+    it("does not render descriptions in plain mode", () => {
+      const result = renderWithProviders(
+        <CheckboxGroup label="Pick" name="opts" options={cardOptions} />,
+      );
+      expect(result.findTextElement("Card A")).toBeDefined();
+      expect(result.findTextElement("Description for A")).toBeUndefined();
+    });
+
+    it("labels the checkbox via aria-labelledby and aria-describedby", () => {
+      const result = renderWithProviders(
+        <CheckboxGroup label="Pick" name="opts" card options={cardOptions} />,
+      );
+      const checkbox = result.container.querySelector("[role='checkbox']");
+      const labelId = checkbox?.getAttribute("aria-labelledby");
+      const descId = checkbox?.getAttribute("aria-describedby");
+      expect(labelId).toBeTruthy();
+      expect(document.getElementById(labelId!)?.textContent).toBe("Card A");
+      expect(descId).toBeTruthy();
+      expect(document.getElementById(descId!)?.textContent).toBe("Description for A");
+    });
+
+    it("checkbox click in card mode emits onChange exactly once", () => {
+      const onChange = vi.fn();
+      const result = renderWithProviders(
+        <CheckboxGroup label="Pick" name="opts" card options={cardOptions} onChange={onChange} />,
+      );
+      const checkbox = result.container.querySelector("[role='checkbox']");
+      if (checkbox) fireEvent.click(checkbox);
+      expect(onChange).toHaveBeenCalledWith(["a"]);
+      // last emit wins and must be the toggled-on state (no double-fire revert)
+      expect(onChange.mock.calls[onChange.mock.calls.length - 1][0]).toEqual(["a"]);
+    });
+
+    it("keeps index-based ids unique for duplicate option values", () => {
+      const dupes = [
+        { label: "One", value: "same", description: "d1" },
+        { label: "Two", value: "same", description: "d2" },
+      ];
+      const result = renderWithProviders(
+        <CheckboxGroup label="Pick" name="opts" card options={dupes} />,
+      );
+      const boxes = [...result.container.querySelectorAll("[role='checkbox']")];
+      const ids = boxes.map((b) => b.id);
+      expect(new Set(ids).size).toBe(2);
+    });
+  });
 });

package/src/fields/Checkbox/Checkbox.stories.tsx

@@ -18,6 +18,10 @@ const meta: Meta<typeof Checkbox> = {
     error: { control: "text" },
     required: { control: "boolean" },
     disabled: { control: "boolean" },
+    readOnly: { control: "boolean" },
+    skeleton: { control: "boolean" },
+    compact: { control: "boolean" },
+    pointy: { control: "boolean" },
     size: { control: "select", options: ["$2", "$3", "$4"] },
     checked: { control: "boolean" },
   },
@@ -337,3 +341,8 @@ export const CheckboxGroupInteractive: StoryObj = {
     return <InteractiveExample />;
   },
 };
+
+/** Loading placeholder — the skeleton mirrors control + label anatomy (LC-20 / DG-ST-02). */
+export const SkeletonState: Story = {
+  args: { label: "Accept terms", skeleton: true },
+};