@multiplatform.one/forms 6.1.0 → 6.4.0

package/src/index.ts

@@ -1,11 +1,63 @@
 // ── Core Form ────────────────────────────────────────────────
-export { Form, useFormContext } from "./Form";
-export type { FormProps } from "./Form";
+export {
+  Form,
+  useFormContext,
+  useFormValidate,
+  useEffectiveValidateOn,
+  resolveEffectiveValidateOn,
+  remapValidatorsForTiming,
+  FormValidateContext,
+} from "./Form";
+export type {
+  FormProps,
+  FormValidateOn,
+  FormValidateContextValue,
+  EffectiveValidateOn,
+} from "./Form";
+
+// ── Error Summary (DG-VAL-02..04) ─────────────────────────────
+export {
+  ErrorSummary,
+  collectFormFieldErrors,
+  formatFieldError,
+  normalizeFieldError,
+  warnBannedErrorWords,
+} from "./ErrorSummary";
+export type {
+  ErrorSummaryProps,
+  ErrorSummaryItem,
+  FieldErrorMessage,
+  StructuredFieldError,
+} from "./ErrorSummary";
 
 // ── Field Layout & Infrastructure ────────────────────────────
 export { Field, FieldLayout } from "./fieldLayout";
 export type { FieldProps, FormFieldProps, FieldLayoutProps } from "./fieldLayout";
 
+// ── Required marking (DG-FORM-05) ─────────────────────────────
+export {
+  RequiredMarkingContext,
+  useRequiredMarking,
+  computeRequiredMarkMode,
+  formatRequiredMarkSuffix,
+  mapHouseRequiredMarking,
+} from "./requiredMarking";
+export type {
+  RequiredMarkMode,
+  RequiredMarkStrategy,
+  RequiredMarkingContextValue,
+} from "./requiredMarking";
+
+// ── Field defaults (width-by-purpose, DG-FORM-07) ─────────────
+export {
+  FIELD_WIDTH_BY_PURPOSE,
+  resolveFieldPurpose,
+  resolveFieldWidth,
+  fieldWidthStyle,
+  isFieldPurpose,
+} from "./fieldDefaults";
+export type { FieldPurpose, FieldWidth, FieldWidthStyle } from "./fieldDefaults";
+
 // ── Types ────────────────────────────────────────────────────
 export type {
   AnyFormApi,
@@ -23,13 +75,20 @@ export type {
   ChildTableLinkResolver,
 } from "./types";
 
+// ── Action labels (DG-ACT-02 / DG-COPY-03) ────────────────────
+export { formatActionLabel } from "./actionLabel";
+export type { ActionLabelParts } from "./actionLabel";
+
 // ── Core Primitives ──────────────────────────────────────────
 export { Button } from "./Button";
-export type { ButtonProps } from "./Button";
+export type { ButtonProps, ButtonActionRole } from "./Button";
 
 export { Input } from "./fields/Input";
 export type { InputProps } from "./fields/Input";
 
+export { SearchInput } from "./fields/SearchInput";
+export type { SearchInputProps } from "./fields/SearchInput";
+
 export { TextArea } from "./fields/TextArea";
 export type { TextAreaProps } from "./fields/TextArea";
 
@@ -51,13 +110,13 @@ export { Switch } from "./fields/Switch";
 export type { SwitchProps } from "./fields/Switch";
 
 export { RadioGroup } from "./fields/RadioGroup";
-export type { RadioGroupProps } from "./fields/RadioGroup";
+export type { RadioGroupProps, RadioGroupOption } from "./fields/RadioGroup";
 
 export { Slider } from "./fields/Slider";
 export type { SliderProps } from "./fields/Slider";
 
 export { ToggleGroup } from "./fields/ToggleGroup";
-export type { ToggleGroupProps } from "./fields/ToggleGroup";
+export type { ToggleGroupOption, ToggleGroupProps } from "./fields/ToggleGroup";
 
 export { Label } from "./Label";
 
@@ -65,7 +124,7 @@ export { Spinner } from "./Spinner";
 export type { SpinnerProps } from "./Spinner";
 
 export { Progress } from "./fields/Progress";
-export type { ProgressProps } from "./fields/Progress";
+export type { ProgressIntent, ProgressProps } from "./fields/Progress";
 
 // ── Compound Components ──────────────────────────────────────
 export {
@@ -96,9 +155,11 @@ export type { PhoneInputProps } from "./fields/PhoneInput";
 
 export { ColorPicker } from "./fields/ColorPicker";
 export type { ColorPickerProps } from "./fields/ColorPicker";
+export { PresetSwatches } from "./fields/ColorPicker/parts";
+export type { PresetSwatchesProps, PresetSwatchEntry } from "./fields/ColorPicker/parts";
 
 export { MentionInput } from "./fields/MentionInput";
-export type { MentionInputProps } from "./fields/MentionInput";
+export type { MentionInputProps, MentionItem } from "./fields/MentionInput";
 
 export { Stepper } from "./fields/Stepper";
 export type { StepperProps } from "./fields/Stepper";
@@ -120,6 +181,8 @@ export type { SignatureProps } from "./fields/Signature";
 
 export { Barcode } from "./fields/Barcode";
 export type { BarcodeProps } from "./fields/Barcode";
+export { BarcodePreview } from "./fields/Barcode/BarcodePreview";
+export type { BarcodePreviewProps } from "./fields/Barcode/BarcodePreview";
 
 export { Geolocation } from "./fields/Geolocation";
 export type { GeolocationProps, GeolocationMapProps } from "./fields/Geolocation";
@@ -132,6 +195,8 @@ export { FieldDisplay } from "./FieldDisplay";
 export type { FieldDisplayProps, FieldDisplayType } from "./FieldDisplay";
 export { FIELD_EDIT_MODE, getEditMode } from "./FieldDisplay/editMode";
 export type { EditMode } from "./FieldDisplay/editMode";
+export { formatDateText, formatNumericText } from "./FieldDisplay/formatters";
+export type { DateFormatOptions, NumericFormatOptions } from "./FieldDisplay/formatters";
 
 // ── Table Primitives (re-exported from @multiplatform.one/table-primitives) ─
 export { Table } from "./Table";
@@ -171,8 +236,15 @@ export { ControlGroup } from "./ControlGroup";
 export type { ControlGroupProps } from "./ControlGroup";
 
 // ── Form Grid (multi-column layout with correct row-by-row tab order) ─────────
-export { FormGrid } from "./FormGrid";
-export type { FormGridProps } from "./FormGrid";
+export { FormGrid, FORM_GRID_COLLAPSE_WIDTH } from "./FormGrid";
+export type { FormGridProps, FormGridColumns } from "./FormGrid";
+
+// ── Field grouping / section rhythm (DG-FORM-01/06/08/09) ─────────────────────
+export { FieldGroup } from "./FieldGroup";
+export type { FieldGroupProps } from "./FieldGroup";
+export { FormSection, FormSectionStack, Fieldset } from "./FormSection";
+export type { FormSectionProps, FormSectionStackProps, FieldsetProps } from "./FormSection";
+export { formFieldGap, formSectionGap, formReadableMaxWidth } from "./formSpacing";
 
 // ── Input compound sub-components (for advanced composition) ─
 export {
@@ -191,7 +263,11 @@ export {
 export { useControlGrouped } from "./shared/groupContext";
 
 // ── Focus Management ─────────────────────────────────────────
-export { useFocusManagement } from "./hooks/useFocusManagement";
+export {
+  useFocusManagement,
+  focusFirstInvalid,
+  focusFieldTarget,
+} from "./hooks/useFocusManagement";
 export type { FocusManagementOptions, FocusManagementReturn } from "./hooks/useFocusManagement";
 
 // ── Shared Utilities ──────────────────────────────────────────
@@ -208,8 +284,11 @@ export {
 export { TableCellContext, useTableCellContext, useIsInTableCell } from "./shared/tableCellContext";
 export type { TableCellContextValue } from "./shared/tableCellContext";
 
+// ── Form color ramps (adapters must consume these, never raw tokens) ─
+export { formCommonColors } from "./shared/colorRamps";
+
 // ── Chip, Skeleton, Wheel (used by forms; re-exported for components consumers) ─
-export { Chip } from "./Chip";
+export { Chip, ChipFrame, ChipText, chipIconSize } from "./Chip";
 export type { ChipProps, ChipVariant, ChipColor, ChipSize, ChipFrameProps } from "./Chip";
 export { Skeleton, SkeletonText, SkeletonCircle } from "./Skeleton";
 export type { SkeletonProps, SkeletonVariant, SkeletonFrameProps } from "./Skeleton";

package/src/requiredMarking.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import {
+  computeRequiredMarkMode,
+  formatRequiredMarkSuffix,
+  mapHouseRequiredMarking,
+} from "./requiredMarking";
+
+describe("mapHouseRequiredMarking", () => {
+  it("maps asterisk and minority to asterisk (minority helper)", () => {
+    expect(mapHouseRequiredMarking("asterisk")).toBe("asterisk");
+    expect(mapHouseRequiredMarking("minority")).toBe("asterisk");
+  });
+
+  it("maps optional to optional", () => {
+    expect(mapHouseRequiredMarking("optional")).toBe("optional");
+  });
+});
+
+describe("computeRequiredMarkMode auto", () => {
+  it("marks required when required is the minority", () => {
+    expect(computeRequiredMarkMode([true, false, false], "auto")).toBe("required");
+  });
+});
+
+describe("formatRequiredMarkSuffix", () => {
+  it("asterisk marks required fields", () => {
+    expect(formatRequiredMarkSuffix(true, "asterisk")).toBe(" *");
+    expect(formatRequiredMarkSuffix(false, "asterisk")).toBe("");
+  });
+});

package/src/requiredMarking.ts

@@ -0,0 +1,82 @@
+/**
+ * Mark-the-minority required/optional labeling (DG-FORM-05).
+ *
+ * Compute once from the schema (or field list); FieldLayout reads the mode
+ * from context / props and never marks both required and optional.
+ */
+
+import { createContext, useContext } from "react";
+
+/** Concrete marking mode applied to labels. */
+export type RequiredMarkMode = "asterisk" | "required" | "optional" | "none";
+
+/** Strategy including schema-driven `"auto"`. */
+export type RequiredMarkStrategy = RequiredMarkMode | "auto";
+
+/**
+ * Map theme house knob `requiredMarking` → FieldLayout mark mode.
+ * `minority` starts as asterisk (mark-required helper) until a form
+ * supplies schema-driven auto via {@link computeRequiredMarkMode}.
+ */
+export function mapHouseRequiredMarking(house: string | undefined | null): RequiredMarkMode {
+  if (house === "optional") return "optional";
+  if (house === "asterisk" || house === "minority") return "asterisk";
+  return "asterisk";
+}
+
+export interface RequiredMarkingContextValue {
+  mode: RequiredMarkMode;
+}
+
+export const RequiredMarkingContext = createContext<RequiredMarkingContextValue | null>(null);
+
+export function useRequiredMarking(): RequiredMarkingContextValue | null {
+  return useContext(RequiredMarkingContext);
+}
+
+/**
+ * Resolve the marking mode from field `required` flags.
+ *
+ * - `"auto"`: mark whichever of required/optional is the minority; on a tie,
+ *   mark required. If every field shares the same requiredness, return
+ *   `"none"` (nothing to contrast).
+ * - Explicit strategies pass through unchanged.
+ */
+export function computeRequiredMarkMode(
+  requiredFlags: readonly boolean[],
+  strategy: RequiredMarkStrategy = "auto",
+): RequiredMarkMode {
+  if (strategy !== "auto") return strategy;
+  if (requiredFlags.length === 0) return "none";
+
+  let requiredCount = 0;
+  for (const flag of requiredFlags) {
+    if (flag) requiredCount += 1;
+  }
+  const optionalCount = requiredFlags.length - requiredCount;
+
+  if (requiredCount === 0 || optionalCount === 0) return "none";
+  return requiredCount <= optionalCount ? "required" : "optional";
+}
+
+/**
+ * Suffix appended to a field label for the given mode.
+ * Empty string when the field should not be marked.
+ */
+export function formatRequiredMarkSuffix(
+  required: boolean | undefined,
+  mode: RequiredMarkMode,
+): string {
+  switch (mode) {
+    case "asterisk":
+      return required ? " *" : "";
+    case "required":
+      return required ? " (required)" : "";
+    case "optional":
+      return required ? "" : " (optional)";
+    case "none":
+      return "";
+    default:
+      return "";
+  }
+}

package/src/shared/FloatingListScrollArrows.stories.tsx

@@ -0,0 +1,54 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { YStack } from "tamagui";
+import { Select } from "../fields/Select";
+
+const meta: Meta = {
+  title: "Forms/FloatingListScrollArrows",
+  parameters: { status: { type: "beta" } },
+};
+
+export default meta;
+type Story = StoryObj;
+
+const manyOptions = Array.from({ length: 60 }, (_, i) => ({
+  value: `option-${i + 1}`,
+  label: `Option ${i + 1}`,
+}));
+
+const fewOptions = Array.from({ length: 3 }, (_, i) => ({
+  value: `option-${i + 1}`,
+  label: `Option ${i + 1}`,
+}));
+
+/**
+ * Long option list: opening the dropdown overflows the floating list, so the
+ * sticky top/bottom scroll arrows (`shared/floatingList.tsx` ScrollArrow)
+ * should appear when more content exists in that direction.
+ */
+export const LongSelect: Story = {
+  render: () => (
+    <YStack maxWidth={320}>
+      <Select
+        id="fls-long"
+        label="Sixty options"
+        options={manyOptions}
+        defaultValue="option-30"
+        helperText="Open to see scroll arrows"
+      />
+    </YStack>
+  ),
+};
+
+/** Short list: content fits, no scroll arrows should ever be visible. */
+export const ShortSelect: Story = {
+  render: () => (
+    <YStack maxWidth={320}>
+      <Select
+        id="fls-short"
+        label="Three options"
+        options={fewOptions}
+        helperText="No arrows expected"
+      />
+    </YStack>
+  ),
+};

package/src/shared/capabilityPreflight.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared LC-19 CAPABILITY-PREFLIGHT primitives.
+ * Capability-specific checks (camera devices, geolocation API, …) stay next
+ * to their fields; only the result shape and Permissions API probe are shared.
+ */
+
+export type CapabilityPreflightResult = { ok: true } | { ok: false; reason: string };
+
+/**
+ * Query the Permissions API for a named capability.
+ * Returns `"unknown"` when the API is missing, the name is unsupported, or
+ * the query throws — callers treat that as "prompt inside the stable surface".
+ */
+export async function queryPermissionState(
+  name: PermissionName | (string & {}),
+): Promise<"granted" | "denied" | "prompt" | "unknown"> {
+  try {
+    const status = await navigator.permissions?.query?.({
+      name: name as PermissionName,
+    });
+    const state = status?.state;
+    if (state === "granted" || state === "denied" || state === "prompt") return state;
+  } catch {
+    // Permissions API unsupported for this name (Safari quirks, etc.)
+  }
+  return "unknown";
+}

package/src/shared/colorRamps.ts

@@ -9,27 +9,41 @@ export const formButtonColors = {
     hover: "$color6",
     active: "$color8",
   },
+  // Legibility floor (SB-R-01): low-accent labels clamp to the $color11
+  // tier — $color7 measured 1.29:1 on the button surface.
   textLow: {
-    base: "$color7",
-    hover: "$color7",
-    active: "$color10",
+    base: "$color11",
+    hover: "$color11",
+    active: "$color12",
   },
 } as const;
 
 export const formInputColors = {
   background: {
-    base: "$color3",
+    base: "$color2",
+    // Still the active/selected highlight for option lists (Combobox, Calendar,
+    // TimeColumn) -- inputs themselves no longer shift background on focus.
     focus: "$color4",
   },
   border: {
-    base: "$color7",
-    focus: "$color8",
+    base: "$borderColor",
+    hover: "$borderColorHover",
+    focus: "$borderColorFocus",
   },
 } as const;
 
 export const formControlColors = {
   background: "$color5",
   border: "$color7",
+  /**
+   * Control BOUNDARY tier (DF-06 / WCAG 1.4.11): the outline that must carry
+   * a control's shape against the page needs ≥3:1 — `border` ($color7)
+   * measured 1.52:1 light / 1.69:1 dark vs page, fine as an inner seam but
+   * invisible as the only edge. $color10 is the muted-ink tier (≥3:1 on
+   * color1/2 in both schemes). Radio rings use this; single-border controls
+   * that rely on their outline alone should too.
+   */
+  boundary: "$color10",
   thumb: {
     base: "$color10",
     hover: "$color9",
@@ -37,6 +51,19 @@ export const formControlColors = {
   },
 } as const;
 
+// Bento switch polarity: accent track when on, light thumb. Separate from
+// formControlColors.thumb, which Slider still uses with inverted polarity.
+// Checked state uses the accent solid so on/off reads at a glance and
+// matches the accent CTAs on the same screen (SB-D-19).
+export const formSwitchColors = {
+  track: {
+    on: "$accentBackground",
+    off: "$color5",
+  },
+  thumb: "$color1",
+  thumbBorder: "$borderColor",
+} as const;
+
 export const formCardColors = {
   background: {
     base: "$color2",
@@ -50,8 +77,15 @@ export const formCardColors = {
 } as const;
 
 export const formCommonColors = {
-  muted: "$color7",
+  // Placeholder/muted tier climbed the ramp again (SB-R-03/04 → interact
+  // resweep): $color7 measured 1.44-1.69:1 and $color10 3.95-4.36:1 as
+  // Select/FileUpload/AwesomeBar placeholder-tier text — under the 4.5:1
+  // AA floor for normal text. Step 11 is the lowest passing step; the muted
+  // tier now differentiates from `text` by weight/size, not color.
+  muted: "$color11",
   text: "$color11",
-  error: "$red10",
+  // Same AA reason as componentColors.semantic: $red10 is under 4.5:1 for
+  // small error text on color1/2 surfaces.
+  error: "$red11",
   divider: "$color8",
 } as const;

package/src/shared/devWarn.ts

@@ -0,0 +1,16 @@
+/**
+ * Forms re-export of blueprint §5 DEV guardrails (canonical: `@multiplatform.one/theme`).
+ */
+
+export {
+  __resetDevWarnSeen,
+  devWarn,
+  warnBannedErrorWords,
+  warnBareDisabled,
+  warnPlaceholderAsLabel,
+  warnPositiveTabIndex,
+  warnSelectTooFewOptions,
+  warnTooltipOnDisabled,
+  type DevWarnCode,
+  type DevWarnDetail,
+} from "@multiplatform.one/theme";

package/src/shared/focusManagement.ts

@@ -0,0 +1,139 @@
+/**
+ * Overlay focus management (DG-A11Y-04 / Axiom 7 AGENCY).
+ *
+ * Programmatically-opened overlays (ConfirmDialog-style `open` props, sheets,
+ * floating panels) get no focus restore from the Tamagui focus scope — it
+ * only remembers a `Dialog.Trigger` mounted inside the Dialog. These hooks
+ * close that gap:
+ *
+ * - `useReturnFocusOnClose(open)` — capture the focused element when `open`
+ *   flips true; when it flips false, return focus to it IF focus was dropped
+ *   (on body, or stranded inside a hidden/removed overlay). Never steals
+ *   focus the user deliberately moved elsewhere (outside-click onto another
+ *   control).
+ * - `useSheetModalFocus(open, frameRef)` — sheet-mode complement: also moves
+ *   focus INTO the sheet frame on open, keeps Tab cycling within it while
+ *   open (Tamagui Sheet has no focus scope), and treats focus left inside
+ *   the closed (offscreen-parked, still-mounted) frame as dropped.
+ *
+ * Capture happens during RENDER, not in an effect: child effects (the Dialog
+ * focus scope) run before parent effects, so an effect-time capture would
+ * read an element already inside the overlay. Reading document.activeElement
+ * in render is a side-effect-free read (StrictMode-safe: the double render
+ * sees the same value).
+ *
+ * NOT a duplicate of `hooks/useFocusManagement` (ErrorSummary's invalid-field
+ * focuser): that hook captures on MOUNT and restores on UNMOUNT via a
+ * containerRef. Overlay components here stay mounted while `open` flips (and
+ * tamagui Sheet parks its frame offscreen instead of unmounting), so the
+ * open-prop TRANSITION is the only usable boundary.
+ *
+ * Web-only; both are no-ops on native.
+ */
+
+import { useEffect, useRef, type RefObject } from "react";
+import { isWeb } from "tamagui";
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+const canUseDom = () => isWeb && typeof document !== "undefined";
+
+function focusIsDropped(insideEl?: HTMLElement | null): boolean {
+  const ae = document.activeElement;
+  if (!ae || ae === document.body || ae === document.documentElement) return true;
+  // Focus stranded inside a closed-but-mounted overlay (tamagui Sheet parks
+  // its frame offscreen instead of unmounting) counts as dropped.
+  if (insideEl?.contains(ae)) return true;
+  return false;
+}
+
+/** Render-phase capture of the element focused just before `open` flipped true. */
+function useCaptureOnOpen(open: boolean) {
+  const prevRef = useRef<HTMLElement | null>(null);
+  const wasOpenRef = useRef(false);
+  if (canUseDom()) {
+    if (open && !wasOpenRef.current) {
+      prevRef.current = document.activeElement as HTMLElement | null;
+    }
+    wasOpenRef.current = open;
+  }
+  return prevRef;
+}
+
+function restoreLater(
+  prevRef: RefObject<HTMLElement | null>,
+  insideRef?: RefObject<HTMLElement | null>,
+) {
+  const restore = () => {
+    const target = prevRef.current;
+    if (!target || !target.isConnected) return;
+    if (focusIsDropped(insideRef?.current ?? null)) target.focus();
+  };
+  // Exit animations unmount / park the overlay a few frames later; retry
+  // after the typical exit window. All calls are idempotent.
+  requestAnimationFrame(() => requestAnimationFrame(restore));
+  setTimeout(restore, 320);
+}
+
+/** Restore focus to the element focused at open time, on close (web only). */
+export function useReturnFocusOnClose(open: boolean) {
+  const prevRef = useCaptureOnOpen(open);
+  useEffect(() => {
+    if (!canUseDom() || !open) return;
+    return () => restoreLater(prevRef);
+  }, [open, prevRef]);
+}
+
+/**
+ * Sheet-mode modal focus: on open, move focus into the frame (frame itself is
+ * the target — it must carry `tabIndex={-1}`); while open, trap Tab inside;
+ * on close, return focus (focus left inside the parked frame counts as
+ * dropped).
+ */
+export function useSheetModalFocus(open: boolean, frameRef: RefObject<HTMLElement | null>) {
+  const prevRef = useCaptureOnOpen(open);
+  useEffect(() => {
+    if (!canUseDom() || !open) return;
+    const frame = frameRef.current;
+    if (!frame || typeof frame.addEventListener !== "function") {
+      return () => restoreLater(prevRef, frameRef);
+    }
+
+    // Focus moves in once the sheet has mounted its frame (spring start).
+    const focusIn = () => {
+      if (frame.contains(document.activeElement)) return;
+      const first = frame.querySelector<HTMLElement>(FOCUSABLE);
+      (first ?? frame).focus({ preventScroll: true });
+    };
+    const raf = requestAnimationFrame(() => requestAnimationFrame(focusIn));
+
+    // Light Tab trap: cycle within the frame (modal sheet owns focus).
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== "Tab") return;
+      const focusables = Array.from(frame.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(
+        (el) => el.offsetWidth > 0 || el.offsetHeight > 0,
+      );
+      if (!focusables.length) {
+        e.preventDefault();
+        return;
+      }
+      const first = focusables[0];
+      const last = focusables[focusables.length - 1];
+      const current = document.activeElement;
+      if (e.shiftKey && (current === first || current === frame)) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && current === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+    frame.addEventListener("keydown", onKeyDown);
+    return () => {
+      cancelAnimationFrame(raf);
+      frame.removeEventListener("keydown", onKeyDown);
+      restoreLater(prevRef, frameRef);
+    };
+  }, [open, frameRef, prevRef]);
+}