sh-ui-cli 0.14.0 → 0.21.0

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

@@ -0,0 +1,146 @@
+import { describe, it, expect, vi } from "vitest";
+import { render } from "@testing-library/react";
+import * as React from "react";
+import { Form } from "./form";
+import { useFormContext, FormContext } from "./context";
+
+function Probe({ onReady }: { onReady: (store: any) => void }) {
+  const store = useFormContext();
+  React.useEffect(() => {
+    onReady(store);
+  }, []);
+  return null;
+}
+
+describe("Form root", () => {
+  it("renders a <form> element", () => {
+    const { container } = render(
+      <Form>
+        <button type="submit">go</button>
+      </Form>
+    );
+    expect(container.querySelector("form")).toBeTruthy();
+  });
+
+  it("provides FormStore via context", () => {
+    const onReady = vi.fn();
+    render(
+      <Form>
+        <Probe onReady={onReady} />
+      </Form>
+    );
+    expect(onReady).toHaveBeenCalled();
+    expect(typeof onReady.mock.calls[0][0].subscribe).toBe("function");
+  });
+
+  it("accepts external form prop", async () => {
+    const { useShUiForm } = await import("./use-sh-ui-form");
+    let captured: any = null;
+    const probe = (s: any) => {
+      captured = s;
+    };
+    function Wrapper() {
+      const store = useShUiForm({ defaultValues: { a: 1 } });
+      return (
+        <Form form={store}>
+          <Probe onReady={probe} />
+        </Form>
+      );
+    }
+    render(<Wrapper />);
+    expect(captured).not.toBeNull();
+    expect(captured.getFieldState("a").value).toBe(1);
+  });
+
+  it("throws in dev mode when nested", () => {
+    const originalError = console.error;
+    console.error = vi.fn();
+    expect(() => {
+      render(
+        <Form>
+          <Form>
+            <div />
+          </Form>
+        </Form>
+      );
+    }).toThrow(/cannot be nested/i);
+    console.error = originalError;
+  });
+
+  it("focuses first errored field after submit", async () => {
+    const { screen } = await import("@testing-library/react");
+    const userEvent = (await import("@testing-library/user-event")).default;
+    const { Field } = await import("./field");
+    const { FormControl } = await import("./field");
+
+    const user = userEvent.setup();
+    render(
+      <Form>
+        <Field name="a" validate={(v) => (v ? undefined : "req")}>
+          <FormControl>
+            <input data-testid="a" />
+          </FormControl>
+        </Field>
+        <Field name="b" validate={(v) => (v ? undefined : "req")}>
+          <FormControl>
+            <input data-testid="b" />
+          </FormControl>
+        </Field>
+        <button type="submit">go</button>
+      </Form>
+    );
+    await user.click(screen.getByText("go"));
+    await new Promise((r) => setTimeout(r, 50));
+    expect(document.activeElement).toBe(screen.getByTestId("a"));
+  });
+});
+
+describe("Form-level states", () => {
+  it("sets aria-busy while submitting", async () => {
+    const { screen } = await import("@testing-library/react");
+    const userEvent = (await import("@testing-library/user-event")).default;
+    const { Field } = await import("./field");
+    const { FormControl } = await import("./field");
+
+    const user = userEvent.setup();
+    let resolveSubmit: () => void;
+    const blocker = new Promise<void>((r) => (resolveSubmit = r));
+
+    render(
+      <Form
+        onSubmit={async () => {
+          await blocker;
+        }}
+      >
+        <Field name="x" validate={() => undefined}>
+          <FormControl>
+            <input />
+          </FormControl>
+        </Field>
+        <button type="submit">go</button>
+      </Form>
+    );
+    const form = document.querySelector("form")!;
+    await user.click(screen.getByText("go"));
+    await new Promise((r) => setTimeout(r, 30));
+    expect(form.getAttribute("aria-busy")).toBe("true");
+    resolveSubmit!();
+  });
+
+  it("Form disabled disables all controls", async () => {
+    const { screen } = await import("@testing-library/react");
+    const { Field } = await import("./field");
+    const { FormControl } = await import("./field");
+
+    render(
+      <Form disabled>
+        <Field name="x">
+          <FormControl>
+            <input data-testid="i" />
+          </FormControl>
+        </Field>
+      </Form>
+    );
+    expect((screen.getByTestId("i") as HTMLInputElement).disabled).toBe(true);
+  });
+});

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

@@ -0,0 +1,180 @@
+"use client";
+
+import * as React from "react";
+import { createFormStore, type CreateFormStoreOptions } from "./store";
+import {
+  FormContext,
+  SectionContext,
+  DisabledContext,
+  useFormState,
+} from "./context";
+import type { FormStore, StandardSchemaV1 } from "./types";
+import { scopedPath } from "./utils";
+import { focusFirstError } from "./focus-first-error";
+
+export interface FormProps<T = unknown>
+  extends Omit<React.FormHTMLAttributes<HTMLFormElement>, "onSubmit" | "onInvalid"> {
+  form?: FormStore<T>;
+  defaultValues?: CreateFormStoreOptions<T>["defaultValues"];
+  schema?: CreateFormStoreOptions<T>["schema"];
+  validateOn?: CreateFormStoreOptions<T>["validateOn"];
+  onSubmit?: CreateFormStoreOptions<T>["onSubmit"];
+  onInvalid?: CreateFormStoreOptions<T>["onInvalid"];
+  scrollToFirstError?: boolean;
+  focusFirstError?: boolean;
+  disabled?: boolean;
+}
+
+function FormInner<T>({
+  form: externalForm,
+  defaultValues,
+  schema,
+  validateOn,
+  onSubmit,
+  onInvalid,
+  scrollToFirstError,
+  focusFirstError: focusFirstErrorProp,
+  disabled,
+  children,
+  ...rest
+}: FormProps<T>) {
+  const parent = React.useContext(FormContext);
+  if (process.env.NODE_ENV !== "production" && parent) {
+    throw new Error(
+      "<Form> cannot be nested. For reusable field groups, use <Form.Section>-based components without a Form root."
+    );
+  }
+
+  const internalStoreRef = React.useRef<FormStore<T> | null>(null);
+  if (!externalForm && !internalStoreRef.current) {
+    internalStoreRef.current = createFormStore<T>({
+      defaultValues,
+      schema,
+      validateOn,
+      onSubmit,
+      onInvalid,
+      scrollToFirstError,
+      focusFirstError: focusFirstErrorProp,
+    });
+  }
+  const store = (externalForm ?? internalStoreRef.current) as FormStore<T>;
+
+  const formElRef = React.useRef<HTMLFormElement | null>(null);
+
+  const handleSubmit: React.FormEventHandler<HTMLFormElement> = (e) => {
+    e.preventDefault();
+    void (async () => {
+      await store.submit();
+      const s = store.getState();
+      const hasErrors = Object.values(s.errors).some(Boolean);
+      if (
+        hasErrors &&
+        store._config.focusFirstError &&
+        formElRef.current
+      ) {
+        focusFirstError(
+          store as unknown as FormStore<unknown>,
+          formElRef.current,
+          store._config.scrollToFirstError
+        );
+      }
+    })();
+  };
+
+  return (
+    <FormContext.Provider value={store as unknown as FormStore<unknown>}>
+      <DisabledContext.Provider value={disabled ?? false}>
+        <FormElement
+          formElRef={formElRef}
+          onSubmit={handleSubmit}
+          noValidate
+          {...rest}
+        >
+          {children}
+        </FormElement>
+      </DisabledContext.Provider>
+    </FormContext.Provider>
+  );
+}
+
+function FormElement({
+  formElRef,
+  children,
+  onSubmit,
+  className,
+  ...rest
+}: {
+  formElRef: React.RefObject<HTMLFormElement | null>;
+  children?: React.ReactNode;
+  onSubmit: React.FormEventHandler<HTMLFormElement>;
+} & Omit<React.FormHTMLAttributes<HTMLFormElement>, "onSubmit">) {
+  const state = useFormState();
+  return (
+    <form
+      ref={formElRef}
+      aria-busy={state.submitting || undefined}
+      onSubmit={onSubmit}
+      className={`sh-ui-form${className ? ` ${className}` : ""}`}
+      {...rest}
+    >
+      {children}
+    </form>
+  );
+}
+
+export interface FormSectionProps extends React.HTMLAttributes<HTMLElement> {
+  name?: string;
+  schema?: StandardSchemaV1;
+  as?: "div" | "fieldset";
+}
+
+function Section({
+  name,
+  schema,
+  as = "div",
+  className,
+  children,
+  ...rest
+}: FormSectionProps) {
+  const parent = React.useContext(SectionContext);
+  const store = React.useContext(FormContext);
+  const path = scopedPath(parent.path, name);
+
+  React.useEffect(() => {
+    if (!schema || !store || !path) return;
+    return store.registerSectionSchema(path, schema);
+  }, [schema, store, path]);
+
+  const Tag = as as any;
+  const role = as === "div" ? "group" : undefined;
+
+  return (
+    <SectionContext.Provider value={{ path }}>
+      <Tag
+        role={role}
+        className={`sh-ui-form-section${className ? ` ${className}` : ""}`}
+        {...rest}
+      >
+        {children}
+      </Tag>
+    </SectionContext.Provider>
+  );
+}
+
+function SectionTitle({
+  children,
+  ...rest
+}: React.HTMLAttributes<HTMLElement>) {
+  return <legend {...rest}>{children}</legend>;
+}
+
+type FormType = typeof FormInner & {
+  Section: typeof Section;
+  SectionTitle: typeof SectionTitle;
+};
+
+export const Form = FormInner as unknown as FormType;
+Form.Section = Section;
+Form.SectionTitle = SectionTitle;
+
+export { Section, SectionTitle };

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

@@ -0,0 +1,61 @@
+"use client";
+
+import "./styles.css";
+import { Form as FormRoot, Section, SectionTitle } from "./form";
+import {
+  Field,
+  FormLabel,
+  FormDescription,
+  FormError,
+  FormControl,
+} from "./field";
+import { Steps, Step } from "./steps";
+
+/**
+ * sh-ui Form의 compound 진입점. `Form.Field`, `Form.Label`, `Form.Description`,
+ * `Form.Error`, `Form.Control`, `Form.Section`, `Form.SectionTitle`, `Form.Steps`, `Form.Step` 으로
+ * 구조를 조립한다. 검증은 Standard Schema(yup/zod 등) 또는 inline 함수로 부착한다.
+ */
+type FormType = typeof FormRoot & {
+  Section: typeof Section;
+  SectionTitle: typeof SectionTitle;
+  Field: typeof Field;
+  Label: typeof FormLabel;
+  Description: typeof FormDescription;
+  Error: typeof FormError;
+  Control: typeof FormControl;
+  Steps: typeof Steps;
+  Step: typeof Step;
+};
+
+const Form = FormRoot as FormType;
+Form.Section = Section;
+Form.SectionTitle = SectionTitle;
+Form.Field = Field;
+Form.Label = FormLabel;
+Form.Description = FormDescription;
+Form.Error = FormError;
+Form.Control = FormControl;
+Form.Steps = Steps;
+Form.Step = Step;
+
+export { Form };
+export { useShUiForm } from "./use-sh-ui-form";
+export {
+  useFormContext,
+  useFormField,
+  useFormSection,
+  useFormState,
+} from "./context";
+export { useFormSteps } from "./steps";
+export { createFormStore } from "./store";
+export type {
+  FormStore,
+  FormStoreState,
+  FieldState,
+  FieldError,
+  FieldConfig,
+  FieldValidate,
+  ValidateOn,
+  StandardSchemaV1,
+} from "./types";

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

@@ -0,0 +1,106 @@
+import { describe, it, expect } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import * as React from "react";
+import { Form } from "./form";
+import { Field } from "./field";
+import { FormControl } from "./field";
+import { Steps, Step, useFormSteps } from "./steps";
+
+function Nav() {
+  const { next, prev, activeStepId, isLastStep } = useFormSteps();
+  return (
+    <>
+      <span data-testid="active">{activeStepId}</span>
+      <button onClick={prev} type="button">prev</button>
+      <button onClick={() => void next()} type="button">
+        {isLastStep ? "done" : "next"}
+      </button>
+    </>
+  );
+}
+
+describe("Form.Steps", () => {
+  it("renders only active step", () => {
+    render(
+      <Form>
+        <Steps defaultStep="a">
+          <Step id="a"><div data-testid="a">A</div></Step>
+          <Step id="b"><div data-testid="b">B</div></Step>
+        </Steps>
+      </Form>
+    );
+    expect(screen.queryByTestId("a")).toBeInTheDocument();
+    expect(screen.queryByTestId("b")).not.toBeInTheDocument();
+  });
+
+  it("next() moves to next step when current is valid", async () => {
+    const user = userEvent.setup();
+    render(
+      <Form>
+        <Steps defaultStep="a">
+          <Step id="a"><div data-testid="a">A</div></Step>
+          <Step id="b"><div data-testid="b">B</div></Step>
+        </Steps>
+        <Nav />
+      </Form>
+    );
+    await user.click(screen.getByText("next"));
+    // next() is fired-and-forgotten from onClick (void next()) so await the async chain
+    await waitFor(() =>
+      expect(screen.getByTestId("active").textContent).toBe("b")
+    );
+    expect(screen.queryByTestId("b")).toBeInTheDocument();
+  });
+
+  it("next() blocks when current step has invalid fields", async () => {
+    const user = userEvent.setup();
+    render(
+      <Form>
+        <Steps defaultStep="a">
+          <Step id="a">
+            <Field name="email" validate={(v) => (v ? undefined : "required")}>
+              <FormControl><input data-testid="i" /></FormControl>
+            </Field>
+          </Step>
+          <Step id="b"><div data-testid="b">B</div></Step>
+        </Steps>
+        <Nav />
+      </Form>
+    );
+    await user.click(screen.getByText("next"));
+    // Give next()'s async chain a chance to settle, then assert it stayed on "a"
+    await new Promise((r) => setTimeout(r, 0));
+    expect(screen.getByTestId("active").textContent).toBe("a");
+  });
+});
+
+describe("value persistence across step navigation", () => {
+  it("keeps value when navigating away and back", async () => {
+    // Store keeps field values even when Step unmounts — values live in FormStore, not DOM
+    const user = userEvent.setup();
+    render(
+      <Form defaultValues={{ email: "" }}>
+        <Steps defaultStep="a">
+          <Step id="a">
+            <Field name="email">
+              <FormControl><input data-testid="i" /></FormControl>
+            </Field>
+          </Step>
+          <Step id="b"><div>B</div></Step>
+        </Steps>
+        <Nav />
+      </Form>
+    );
+    const input = screen.getByTestId("i") as HTMLInputElement;
+    await user.type(input, "a@b.com");
+    await user.click(screen.getByText("next"));
+    // next() fires async — wait for step b to mount
+    await waitFor(() =>
+      expect(screen.getByTestId("active").textContent).toBe("b")
+    );
+    await user.click(screen.getByText("prev"));
+    await waitFor(() => expect(screen.queryByTestId("i")).toBeInTheDocument());
+    expect((screen.getByTestId("i") as HTMLInputElement).value).toBe("a@b.com");
+  });
+});

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

@@ -0,0 +1,193 @@
+"use client";
+
+import * as React from "react";
+import { FormContext, StepContext, useFormState } from "./context";
+
+export interface StepsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
+  defaultStep?: string;
+  activeStep?: string;
+  onStepChange?: (id: string) => void;
+  children: React.ReactNode;
+}
+
+// ─── Internal store backdoor types ────────────────────────────────────────────
+
+interface StepsNav {
+  activeStepId: string | null;
+  order: string[];
+  setActive: (id: string) => void;
+}
+
+type StoreWithSteps = {
+  __stepsNav?: StepsNav;
+  __stepConfig?: Record<string, { skipValidationOnNext?: boolean }>;
+};
+
+// ─── StepsContext — only used within the Steps subtree ────────────────────────
+
+interface StepsContextValue {
+  activeStepId: string | null;
+  setActive: (id: string) => void;
+  order: string[];
+  registerStepId: (id: string) => () => void;
+}
+
+const StepsContext = React.createContext<StepsContextValue | null>(null);
+
+// ─── Steps ────────────────────────────────────────────────────────────────────
+
+export function Steps({
+  defaultStep,
+  activeStep,
+  onStepChange,
+  children,
+  ...rest
+}: StepsProps) {
+  const store = React.useContext(FormContext);
+  if (!store) throw new Error("<Form.Steps> must be inside <Form>");
+
+  const [internal, setInternal] = React.useState<string | null>(
+    defaultStep ?? null
+  );
+  const [order, setOrder] = React.useState<string[]>([]);
+
+  const active = activeStep ?? internal;
+
+  const setActive = React.useCallback(
+    (id: string) => {
+      if (activeStep === undefined) setInternal(id);
+      onStepChange?.(id);
+    },
+    [activeStep, onStepChange]
+  );
+
+  const registerStepId = React.useCallback((id: string) => {
+    setOrder((prev) => (prev.includes(id) ? prev : [...prev, id]));
+    return () => {
+      setOrder((prev) => prev.filter((x) => x !== id));
+    };
+  }, []);
+
+  // Activate first step when order becomes available and no step is active
+  React.useEffect(() => {
+    if (!active && order.length > 0) setInternal(order[0]);
+  }, [active, order]);
+
+  // Sync active step to form store
+  React.useEffect(() => {
+    store.setActiveStep(active);
+  }, [store, active]);
+
+  // Publish nav API onto store backdoor so useFormSteps can access it
+  // from anywhere in the Form tree (not just inside Steps subtree)
+  React.useEffect(() => {
+    (store as unknown as StoreWithSteps).__stepsNav = {
+      activeStepId: active,
+      order,
+      setActive,
+    };
+  });
+
+  const ctxValue = React.useMemo(
+    () => ({ activeStepId: active, setActive, order, registerStepId }),
+    [active, setActive, order, registerStepId]
+  );
+
+  return (
+    <StepsContext.Provider value={ctxValue}>
+      <div {...rest}>{children}</div>
+    </StepsContext.Provider>
+  );
+}
+
+// ─── Step ─────────────────────────────────────────────────────────────────────
+
+export interface StepProps {
+  id: string;
+  skipValidationOnNext?: boolean;
+  children?: React.ReactNode;
+}
+
+export function Step({ id, skipValidationOnNext, children }: StepProps) {
+  const ctx = React.useContext(StepsContext);
+  const store = React.useContext(FormContext);
+  if (!ctx || !store) throw new Error("<Form.Step> must be inside <Form.Steps>");
+
+  const { registerStepId } = ctx;
+  React.useEffect(() => registerStepId(id), [registerStepId, id]);
+
+  React.useEffect(() => {
+    const s = store as unknown as StoreWithSteps;
+    const current = s.__stepConfig ?? {};
+    s.__stepConfig = { ...current, [id]: { skipValidationOnNext } };
+  }, [store, id, skipValidationOnNext]);
+
+  if (ctx.activeStepId !== id) return null;
+
+  return (
+    <StepContext.Provider value={{ id }}>{children}</StepContext.Provider>
+  );
+}
+
+// ─── useFormSteps ─────────────────────────────────────────────────────────────
+
+export function useFormSteps() {
+  const store = React.useContext(FormContext);
+  if (!store) throw new Error("useFormSteps must be used inside <Form>");
+
+  // Subscribe to store so we re-render on step changes
+  useFormState();
+
+  // Read nav from backdoor — set synchronously by Steps on every render
+  const nav = (store as unknown as StoreWithSteps).__stepsNav;
+
+  const activeStepId = nav?.activeStepId ?? store.getState().activeStepId;
+  const order = nav?.order ?? [];
+  const setActive = nav?.setActive ?? (() => {});
+
+  const idx = activeStepId ? order.indexOf(activeStepId) : -1;
+  const isLastStep = order.length > 0 ? idx === order.length - 1 : false;
+  const isFirstStep = idx === 0;
+
+  return {
+    activeStepId,
+    isLastStep,
+    isFirstStep,
+    next: async () => {
+      // Read nav fresh at call time so stale closures don't bite us
+      const currentNav = (store as unknown as StoreWithSteps).__stepsNav;
+      const currentActiveStepId = currentNav?.activeStepId ?? store.getState().activeStepId;
+      if (!currentActiveStepId) return false;
+      const stepConfig = (store as unknown as StoreWithSteps).__stepConfig;
+      const cfg = stepConfig?.[currentActiveStepId];
+      const ok = cfg?.skipValidationOnNext
+        ? true
+        : await store.validateStep(currentActiveStepId);
+      if (!ok) return false;
+      // Re-read nav after async operation in case it changed
+      const latestNav = (store as unknown as StoreWithSteps).__stepsNav;
+      const latestOrder = latestNav?.order ?? [];
+      const latestSetActive = latestNav?.setActive ?? (() => {});
+      const latestIdx = latestOrder.indexOf(currentActiveStepId);
+      const latestIsLast = latestIdx === latestOrder.length - 1;
+      if (latestIsLast) {
+        await store.submit();
+        return true;
+      }
+      latestSetActive(latestOrder[latestIdx + 1]);
+      return true;
+    },
+    prev: () => {
+      if (isFirstStep) return;
+      setActive(order[idx - 1]);
+    },
+    goTo: (id: string) => {
+      if (order.includes(id)) setActive(id);
+    },
+    isStepValid: (id: string) => {
+      const storeState = store.getState();
+      const fields = storeState.fieldsByStep.get(id) ?? new Set();
+      return !Array.from(fields).some((f) => storeState.errors[f]);
+    },
+  };
+}