sh-ui-cli 0.14.0 → 0.21.0

package/data/registry/react/components/form/context.ts

@@ -0,0 +1,92 @@
+"use client";
+
+import * as React from "react";
+import { useSyncExternalStore } from "react";
+import type { FormStore, FieldState } from "./types";
+
+export const FormContext = React.createContext<FormStore<unknown> | null>(null);
+
+export const SectionContext = React.createContext<{ path: string }>({ path: "" });
+
+export const StepContext = React.createContext<{ id: string | null }>({ id: null });
+
+export const FieldContext = React.createContext<{
+  path: string;
+  id: string;
+  descId: string;
+  errorId: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+} | null>(null);
+
+export const DisabledContext = React.createContext<boolean>(false);
+
+export function useFormContext<T = unknown>(): FormStore<T> {
+  const ctx = React.useContext(FormContext);
+  if (!ctx) throw new Error("useFormContext must be used inside <Form>");
+  return ctx as FormStore<T>;
+}
+
+export function useFormState() {
+  const store = useFormContext();
+  return useSyncExternalStore(
+    store.subscribe,
+    () => store.getState(),
+    () => store.getState()
+  );
+}
+
+export function useFormField(name?: string): FieldState & { path: string } {
+  const store = useFormContext();
+  const fieldCtx = React.useContext(FieldContext);
+  const path = name ?? fieldCtx?.path;
+  if (!path) throw new Error("useFormField: name is required outside <Form.Field>");
+
+  useSyncExternalStore(
+    store.subscribe,
+    () => {
+      const s = store.getState();
+      return JSON.stringify([
+        s.values[path],
+        s.errors[path],
+        s.touched[path],
+        s.validatingFields.has(path),
+      ]);
+    },
+    () => ""
+  );
+  const snapshot = store.getFieldState(path);
+  return { ...snapshot, path };
+}
+
+export function useFormSection(name?: string): {
+  hasError: boolean;
+  errors: Record<string, { message: string }>;
+  isValid: boolean;
+  isDirty: boolean;
+} {
+  const store = useFormContext();
+  const sectionCtx = React.useContext(SectionContext);
+  const path = name ?? sectionCtx.path;
+
+  useSyncExternalStore(
+    store.subscribe,
+    () => JSON.stringify([store.getState().errors, store.getState().touched]),
+    () => ""
+  );
+
+  const state = store.getState();
+  const matching = Object.entries(state.errors).filter(
+    ([p, e]) => e && (p === path || p.startsWith(path + "."))
+  ) as Array<[string, { message: string }]>;
+  const touchedAny = Object.entries(state.touched).some(
+    ([p, t]) => t && (p === path || p.startsWith(path + "."))
+  );
+  return {
+    hasError: matching.length > 0,
+    errors: Object.fromEntries(matching),
+    isValid: matching.length === 0,
+    isDirty: touchedAny,
+  };
+}

package/data/registry/react/components/form/field.test.tsx

@@ -0,0 +1,230 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import * as React from "react";
+import { Form } from "./form";
+import {
+  Field,
+  FormLabel,
+  FormDescription,
+  FormError,
+  FormControl,
+} from "./field";
+import { FieldContext, FormContext } from "./context";
+
+// ─────────────────────────────────────────────
+// Form.Field
+// ─────────────────────────────────────────────
+describe("Form.Field", () => {
+  it("registers and unregisters field by name", () => {
+    let capturedStore: any = null;
+    function StoreProbe() {
+      const ctx = React.useContext(FormContext);
+      React.useEffect(() => {
+        capturedStore = ctx;
+      }, [ctx]);
+      return null;
+    }
+    const { rerender } = render(
+      <Form>
+        <StoreProbe />
+        <Field name="email" />
+      </Form>
+    );
+    expect(capturedStore.getState().fieldValidators.has("email")).toBe(true);
+    rerender(
+      <Form>
+        <StoreProbe />
+      </Form>
+    );
+    expect(capturedStore.getState().fieldValidators.has("email")).toBe(false);
+  });
+
+  it("applies section namespace to path", () => {
+    let pathSeen = "";
+    function Probe() {
+      const ctx = React.useContext(FieldContext);
+      pathSeen = ctx?.path ?? "";
+      return null;
+    }
+    render(
+      <Form>
+        <Form.Section name="profile">
+          <Field name="name">
+            <Probe />
+          </Field>
+        </Form.Section>
+      </Form>
+    );
+    expect(pathSeen).toBe("profile.name");
+  });
+});
+
+// ─────────────────────────────────────────────
+// Form.Label
+// ─────────────────────────────────────────────
+describe("Form.Label", () => {
+  it("wires htmlFor to Field id", () => {
+    render(
+      <Form>
+        <Field name="email">
+          <FormLabel>Email</FormLabel>
+          <input data-testid="x" />
+        </Field>
+      </Form>
+    );
+    const label = screen.getByText("Email") as HTMLLabelElement;
+    expect(label.tagName).toBe("LABEL");
+    expect(label.htmlFor).toBeTruthy();
+  });
+});
+
+// ─────────────────────────────────────────────
+// Form.Description
+// ─────────────────────────────────────────────
+describe("Form.Description", () => {
+  it("renders with correct descId", () => {
+    render(
+      <Form>
+        <Field name="x">
+          <FormDescription>help</FormDescription>
+        </Field>
+      </Form>
+    );
+    const desc = screen.getByText("help");
+    expect(desc.id).toMatch(/-desc$/);
+  });
+});
+
+// ─────────────────────────────────────────────
+// Form.Error
+// ─────────────────────────────────────────────
+describe("Form.Error", () => {
+  it("does not render when no error", () => {
+    render(
+      <Form>
+        <Field name="x">
+          <FormError />
+        </Field>
+      </Form>
+    );
+    expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+  });
+});
+
+// ─────────────────────────────────────────────
+// Form.Control — value binding
+// ─────────────────────────────────────────────
+describe("Form.Control — value binding", () => {
+  it("injects id/value/onChange and updates store on change", async () => {
+    const user = userEvent.setup();
+    render(
+      <Form defaultValues={{ email: "" }}>
+        <Field name="email">
+          <FormLabel>Email</FormLabel>
+          <FormControl>
+            <input data-testid="i" />
+          </FormControl>
+        </Field>
+      </Form>
+    );
+    const input = screen.getByTestId("i") as HTMLInputElement;
+    expect(input.id).toBeTruthy();
+    expect(screen.getByText("Email")).toHaveAttribute("for", input.id);
+    await user.type(input, "abc");
+    expect(input.value).toBe("abc");
+  });
+
+  it("includes descId in aria-describedby", () => {
+    render(
+      <Form>
+        <Field name="x">
+          <FormDescription>help</FormDescription>
+          <FormControl>
+            <input data-testid="i" />
+          </FormControl>
+        </Field>
+      </Form>
+    );
+    const input = screen.getByTestId("i") as HTMLInputElement;
+    expect(input.getAttribute("aria-describedby")).toMatch(/-desc/);
+  });
+});
+
+// ─────────────────────────────────────────────
+// Form.Control — checked binding
+// ─────────────────────────────────────────────
+describe("Form.Control — checked binding", () => {
+  it("valueAs=checked with checkbox", async () => {
+    const user = userEvent.setup();
+    render(
+      <Form defaultValues={{ agree: false }}>
+        <Field name="agree">
+          <FormControl valueAs="checked">
+            <input type="checkbox" data-testid="cb" />
+          </FormControl>
+        </Field>
+      </Form>
+    );
+    const cb = screen.getByTestId("cb") as HTMLInputElement;
+    expect(cb.checked).toBe(false);
+    await user.click(cb);
+    expect(cb.checked).toBe(true);
+  });
+});
+
+// ─────────────────────────────────────────────
+// Form.Control — render prop
+// ─────────────────────────────────────────────
+describe("Form.Control — render prop", () => {
+  it("passes ControlProps to render callback", () => {
+    render(
+      <Form>
+        <Field name="color">
+          <FormControl
+            render={(ctrl) => (
+              <div
+                data-testid="wrap"
+                data-id={ctrl.id}
+                data-name={ctrl.name}
+              />
+            )}
+          />
+        </Field>
+      </Form>
+    );
+    const wrap = screen.getByTestId("wrap");
+    expect(wrap.getAttribute("data-name")).toBe("color");
+    expect(wrap.getAttribute("data-id")).toBeTruthy();
+  });
+});
+
+// ─────────────────────────────────────────────
+// validateOn blur → change on error
+// ─────────────────────────────────────────────
+describe("validateOn blur → change on error", () => {
+  it("once a field errors, subsequent onChange revalidates", async () => {
+    const user = userEvent.setup();
+    render(
+      <Form>
+        <Field
+          name="email"
+          validate={(v) =>
+            String(v).includes("@") ? undefined : "bad"
+          }
+        >
+          <FormControl>
+            <input data-testid="i" />
+          </FormControl>
+          <FormError />
+        </Field>
+      </Form>
+    );
+    const input = screen.getByTestId("i") as HTMLInputElement;
+    await user.type(input, "abc");
+    input.blur();
+    await screen.findByText("bad");
+    await user.type(input, "@x.com");
+    expect(screen.queryByText("bad")).not.toBeInTheDocument();
+  });
+});

package/data/registry/react/components/form/field.tsx

@@ -0,0 +1,236 @@
+"use client";
+
+import * as React from "react";
+import {
+  FormContext,
+  FieldContext,
+  SectionContext,
+  StepContext,
+  DisabledContext,
+  useFormField,
+} from "./context";
+import type { FieldValidate, ValidateOn } from "./types";
+import { scopedPath } from "./utils";
+
+// ─────────────────────────────────────────────
+// Field
+// ─────────────────────────────────────────────
+
+export interface FieldProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+  name: string;
+  validate?: FieldValidate;
+  validateOn?: ValidateOn;
+  required?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  children?: React.ReactNode;
+}
+
+export function Field({
+  name,
+  validate,
+  validateOn,
+  required,
+  disabled,
+  readOnly,
+  className,
+  children,
+  ...rest
+}: FieldProps) {
+  const store = React.useContext(FormContext);
+  if (!store) throw new Error("<Form.Field> must be inside <Form>");
+
+  const section = React.useContext(SectionContext);
+  const step = React.useContext(StepContext);
+  const formDisabled = React.useContext(DisabledContext);
+  const path = scopedPath(section.path, name);
+
+  const id = React.useId();
+  const descId = `${id}-desc`;
+  const errorId = `${id}-error`;
+
+  React.useEffect(() => {
+    return store.registerField(path, {
+      validate,
+      validateOn,
+      stepId: step.id ?? undefined,
+      sectionPath: section.path || undefined,
+      required,
+    });
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [store, path]);
+
+  const effectiveDisabled = disabled || formDisabled;
+
+  return (
+    <FieldContext.Provider
+      value={{
+        path,
+        id,
+        descId,
+        errorId,
+        disabled: effectiveDisabled,
+        readOnly,
+        required,
+      }}
+    >
+      <div
+        className={`sh-ui-form-field${className ? ` ${className}` : ""}`}
+        data-disabled={effectiveDisabled || undefined}
+        data-readonly={readOnly || undefined}
+        {...rest}
+      >
+        {children}
+      </div>
+    </FieldContext.Provider>
+  );
+}
+
+// ─────────────────────────────────────────────
+// Label
+// ─────────────────────────────────────────────
+
+export const FormLabel = React.forwardRef<
+  HTMLLabelElement,
+  React.LabelHTMLAttributes<HTMLLabelElement>
+>(({ className, ...props }, ref) => {
+  const ctx = React.useContext(FieldContext);
+  if (!ctx) throw new Error("<Form.Label> must be inside <Form.Field>");
+  return <label ref={ref} htmlFor={ctx.id} className={className} {...props} />;
+});
+FormLabel.displayName = "Form.Label";
+
+// ─────────────────────────────────────────────
+// Description
+// ─────────────────────────────────────────────
+
+export const FormDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => {
+  const ctx = React.useContext(FieldContext);
+  if (!ctx) throw new Error("<Form.Description> must be inside <Form.Field>");
+  return <p ref={ref} id={ctx.descId} className={className} {...props} />;
+});
+FormDescription.displayName = "Form.Description";
+
+// ─────────────────────────────────────────────
+// Error
+// ─────────────────────────────────────────────
+
+export interface FormErrorProps
+  extends Omit<React.HTMLAttributes<HTMLParagraphElement>, "children"> {
+  children?:
+    | React.ReactNode
+    | ((err: { message: string; type?: string }) => React.ReactNode);
+  matches?: string;
+}
+
+export function FormError({
+  children,
+  matches,
+  className,
+  ...rest
+}: FormErrorProps) {
+  const ctx = React.useContext(FieldContext);
+  if (!ctx) throw new Error("<Form.Error> must be inside <Form.Field>");
+  const field = useFormField(ctx.path);
+
+  const err = field.error;
+  if (!err) return null;
+  if (matches && err.type !== matches) return null;
+
+  const content =
+    typeof children === "function"
+      ? (children as (e: { message: string; type?: string }) => React.ReactNode)(err)
+      : children ?? err.message;
+
+  return (
+    <p
+      id={ctx.errorId}
+      className={`sh-ui-form-error${className ? ` ${className}` : ""}`}
+      role="alert"
+      aria-live="polite"
+      {...rest}
+    >
+      {content}
+    </p>
+  );
+}
+
+// ─────────────────────────────────────────────
+// Control
+// ─────────────────────────────────────────────
+
+export interface ControlProps {
+  id: string;
+  name: string;
+  value?: unknown;
+  checked?: boolean;
+  onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
+  onBlur: () => void;
+  "aria-invalid"?: true;
+  "aria-describedby"?: string;
+  "aria-required"?: true;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+}
+
+export interface FormControlProps {
+  children?: React.ReactElement;
+  valueAs?: "value" | "checked";
+  render?: (ctrl: ControlProps) => React.ReactElement;
+}
+
+export function FormControl({
+  children,
+  valueAs = "value",
+  render,
+}: FormControlProps) {
+  const ctx = React.useContext(FieldContext);
+  if (!ctx) throw new Error("<Form.Control> must be inside <Form.Field>");
+  const store = React.useContext(FormContext)!;
+  const field = useFormField(ctx.path);
+
+  const describedBy =
+    [ctx.descId, field.hasError ? ctx.errorId : null]
+      .filter(Boolean)
+      .join(" ") || undefined;
+
+  const ctrl: ControlProps = {
+    id: ctx.id,
+    name: ctx.path,
+    onChange: (e) => {
+      const target = e.target as HTMLInputElement;
+      const next = valueAs === "checked" ? target.checked : target.value;
+      store.setFieldValue(ctx.path, next);
+      if (store.getState().revalidateOnChange.has(ctx.path)) {
+        void store.validateField(ctx.path);
+      }
+    },
+    onBlur: () => {
+      store.setFieldTouched(ctx.path, true);
+      void store.validateField(ctx.path);
+    },
+    "aria-describedby": describedBy,
+    disabled: ctx.disabled,
+    readOnly: ctx.readOnly,
+    required: ctx.required,
+  };
+
+  if (field.hasError) ctrl["aria-invalid"] = true;
+  if (ctx.required) ctrl["aria-required"] = true;
+
+  if (valueAs === "checked") {
+    ctrl.checked = Boolean(field.value);
+  } else {
+    ctrl.value = field.value ?? "";
+  }
+
+  if (render) return render(ctrl);
+  if (!children) return null;
+  const child = React.Children.only(children);
+  return React.cloneElement(child, ctrl as unknown as Record<string, unknown>);
+}

package/data/registry/react/components/form/focus-first-error.ts

@@ -0,0 +1,54 @@
+import type { FormStore } from "./types";
+
+function getPrefersReducedMotion(): boolean {
+  if (typeof window === "undefined") return false;
+  try {
+    return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  } catch {
+    return false;
+  }
+}
+
+export function focusFirstError(
+  store: FormStore,
+  formEl: HTMLFormElement,
+  scroll: boolean
+) {
+  const state = store.getState();
+  const errorPaths = Object.keys(state.errors).filter((p) => state.errors[p]);
+  if (errorPaths.length === 0) return;
+
+  const allInputs = formEl.querySelectorAll<HTMLElement>("[name]");
+  for (const el of Array.from(allInputs)) {
+    const name = el.getAttribute("name");
+    if (name && errorPaths.includes(name)) {
+      // Check if field is in a step and that step is inactive
+      for (const [stepId, fields] of state.fieldsByStep) {
+        if (fields.has(name) && stepId !== state.activeStepId) {
+          store.setActiveStep(stepId);
+          requestAnimationFrame(() => {
+            const retry = formEl.querySelector<HTMLElement>(`[name="${name}"]`);
+            retry?.focus({ preventScroll: true });
+            if (scroll && retry && typeof retry.scrollIntoView === "function") {
+              const reduce = getPrefersReducedMotion();
+              retry.scrollIntoView({
+                block: "center",
+                behavior: reduce ? "auto" : "smooth",
+              });
+            }
+          });
+          return;
+        }
+      }
+      el.focus({ preventScroll: true });
+      if (scroll && typeof el.scrollIntoView === "function") {
+        const reduce = getPrefersReducedMotion();
+        el.scrollIntoView({
+          block: "center",
+          behavior: reduce ? "auto" : "smooth",
+        });
+      }
+      return;
+    }
+  }
+}

package/data/registry/react/components/form/form.section.test.tsx

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import * as React from "react";
+import { Form } from "./form";
+import { FormContext } from "./context";
+
+describe("Form.Section", () => {
+  it("renders as role=group by default", () => {
+    render(
+      <Form>
+        <Form.Section name="profile" aria-labelledby="p-title">
+          <h2 id="p-title">Profile</h2>
+        </Form.Section>
+      </Form>
+    );
+    expect(screen.getByRole("group")).toBeInTheDocument();
+  });
+
+  it("renders as fieldset when as=fieldset", () => {
+    const { container } = render(
+      <Form>
+        <Form.Section name="x" as="fieldset">
+          <Form.SectionTitle>Title</Form.SectionTitle>
+        </Form.Section>
+      </Form>
+    );
+    expect(container.querySelector("fieldset")).toBeTruthy();
+    expect(container.querySelector("legend")?.textContent).toBe("Title");
+  });
+
+  it("registers section schema when provided", async () => {
+    const schema = {
+      "~standard": {
+        version: 1 as const,
+        vendor: "test",
+        validate: (_v: unknown) => ({ issues: [{ path: ["x"], message: "bad" }] }),
+      },
+    };
+
+    let captured: any = null;
+    function Probe() {
+      const store = React.useContext(FormContext);
+      captured = store;
+      return null;
+    }
+
+    render(
+      <Form>
+        <Form.Section name="profile" schema={schema}>
+          <Probe />
+        </Form.Section>
+      </Form>
+    );
+
+    // schema should be registered under "profile"
+    expect(captured.getState().sectionSchemas.has("profile")).toBe(true);
+  });
+});