@emara/ui 1.1.0

package/components/ui/form.tsx

@@ -0,0 +1,542 @@
+"use client";
+
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type FormHTMLAttributes,
+  type ReactNode,
+} from "react";
+import {
+  Controller,
+  FormProvider,
+  useFormContext,
+  type Control,
+  type FieldValues,
+  type Path,
+  type RegisterOptions,
+  type UseFormReturn,
+} from "react-hook-form";
+
+import { cn } from "@/lib/utils";
+
+// Per docs/emara-ui-phase-2-components.md §8.
+//
+// Two modes:
+//  - "plain"  → FormField owns its own state via useState + a small internal
+//                store. Zero RHF dependency in the consumer's tree.
+//  - "rhf"    → FormField wraps RHF's Controller; the consumer passes
+//                `form={useForm(...)}`.
+//
+// Components rendered inside (Input, Textarea, Select, etc.) only see the
+// render-prop API and don't know which mode they're in.
+
+// ----------------------------------------------------------------------------
+// Public render-prop API — shared by both modes.
+// ----------------------------------------------------------------------------
+
+export interface FormRenderField {
+  name: string;
+  value: unknown;
+  onChange: (value: unknown) => void;
+  onBlur: () => void;
+  /**
+   * Convenience prop bundle that can be spread directly onto Emara controls
+   * (Input, Textarea, Select, etc.). Maps `onChange` to the native event
+   * shape consumed by `<input>` / `<textarea>` / `<select>`.
+   */
+  inputProps: {
+    name: string;
+    value: string;
+    onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
+    onBlur: () => void;
+  };
+}
+
+export interface FormRenderFieldState {
+  invalid: boolean;
+  isDirty: boolean;
+  isTouched: boolean;
+  error: { message?: string } | undefined;
+}
+
+type FormFieldRender = (args: {
+  field: FormRenderField;
+  fieldState: FormRenderFieldState;
+}) => ReactNode;
+
+// ----------------------------------------------------------------------------
+// Form context — captures the current mode + a status bag for autoSave.
+// ----------------------------------------------------------------------------
+
+type AutoSaveStatus = "idle" | "saving" | "saved" | "error";
+
+interface FormContextValue {
+  mode: "plain" | "rhf";
+  loading: boolean;
+  autoSaveStatus: AutoSaveStatus;
+  /**
+   * Plain-mode value store. Only populated when `mode === "plain"`. Used by
+   * FormField to read/write values without a RHF Controller.
+   */
+  plainStore: {
+    getValues: () => Record<string, unknown>;
+    getValue: (name: string) => unknown;
+    setValue: (name: string, value: unknown) => void;
+    registerField: (name: string, defaultValue: unknown) => void;
+    subscribe: (listener: () => void) => () => void;
+    setError: (name: string, message: string | undefined) => void;
+    getError: (name: string) => string | undefined;
+    setTouched: (name: string) => void;
+    isTouched: (name: string) => boolean;
+    isDirty: (name: string) => boolean;
+  } | null;
+}
+
+const FormCtx = createContext<FormContextValue | null>(null);
+
+function useFormCtx(): FormContextValue {
+  const ctx = useContext(FormCtx);
+  if (!ctx) throw new Error("FormField must be used inside a <Form>.");
+  return ctx;
+}
+
+// ----------------------------------------------------------------------------
+// Plain-mode store — tiny pub/sub keyed by field name.
+// ----------------------------------------------------------------------------
+
+function createPlainStore() {
+  const values = new Map<string, unknown>();
+  const initials = new Map<string, unknown>();
+  const errors = new Map<string, string | undefined>();
+  const touched = new Set<string>();
+  const listeners = new Set<() => void>();
+
+  const emit = () => {
+    for (const fn of listeners) fn();
+  };
+
+  return {
+    getValues: () => Object.fromEntries(values),
+    getValue: (name: string) => values.get(name),
+    setValue: (name: string, value: unknown) => {
+      values.set(name, value);
+      emit();
+    },
+    registerField: (name: string, defaultValue: unknown) => {
+      if (!values.has(name)) {
+        values.set(name, defaultValue);
+        initials.set(name, defaultValue);
+      }
+    },
+    subscribe: (listener: () => void) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    setError: (name: string, message: string | undefined) => {
+      if (message) errors.set(name, message);
+      else errors.delete(name);
+      emit();
+    },
+    getError: (name: string) => errors.get(name),
+    setTouched: (name: string) => {
+      touched.add(name);
+      emit();
+    },
+    isTouched: (name: string) => touched.has(name),
+    isDirty: (name: string) => values.get(name) !== initials.get(name),
+  };
+}
+
+// ----------------------------------------------------------------------------
+// Form root
+// ----------------------------------------------------------------------------
+
+type AutoSaveOptions<T extends FieldValues = FieldValues> = {
+  delay: number;
+  onSave: (values: T) => Promise<void> | void;
+};
+
+type FormPlainProps = Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit"> & {
+  mode?: "plain";
+  onSubmit?: (values: Record<string, unknown>) => void | Promise<void>;
+  loading?: boolean;
+  confirmBeforeLeave?: boolean;
+  autoSave?: AutoSaveOptions;
+};
+
+type FormRhfProps<T extends FieldValues> = Omit<
+  FormHTMLAttributes<HTMLFormElement>,
+  "onSubmit"
+> & {
+  mode: "rhf";
+  form: UseFormReturn<T>;
+  onSubmit?: (values: T) => void | Promise<void>;
+  loading?: boolean;
+  confirmBeforeLeave?: boolean;
+  autoSave?: AutoSaveOptions<T>;
+};
+
+type FormProps<T extends FieldValues = FieldValues> =
+  | FormPlainProps
+  | FormRhfProps<T>;
+
+function Form<T extends FieldValues = FieldValues>(props: FormProps<T>) {
+  const { mode = "plain" } = props;
+  if (mode === "rhf") {
+    return <FormRhf {...(props as FormRhfProps<T>)} />;
+  }
+  return <FormPlain {...(props as FormPlainProps)} />;
+}
+
+// ----- Plain implementation --------------------------------------------------
+
+function FormPlain({
+  onSubmit,
+  loading = false,
+  confirmBeforeLeave = false,
+  autoSave,
+  className,
+  children,
+  ...formProps
+}: FormPlainProps) {
+  const store = useMemo(() => createPlainStore(), []);
+  const [autoSaveStatus, setAutoSaveStatus] = useState<AutoSaveStatus>("idle");
+
+  // confirmBeforeLeave — warn if any field is dirty.
+  useEffect(() => {
+    if (!confirmBeforeLeave) return;
+    const handler = (e: BeforeUnloadEvent) => {
+      const anyDirty = Object.keys(store.getValues()).some((n) => store.isDirty(n));
+      if (anyDirty) {
+        e.preventDefault();
+        e.returnValue = "";
+      }
+    };
+    window.addEventListener("beforeunload", handler);
+    return () => {
+      window.removeEventListener("beforeunload", handler);
+    };
+  }, [confirmBeforeLeave, store]);
+
+  // autoSave — debounce changes, call onSave.
+  useEffect(() => {
+    if (!autoSave) return;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const unsubscribe = store.subscribe(() => {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(async () => {
+        setAutoSaveStatus("saving");
+        try {
+          await autoSave.onSave(store.getValues() as FieldValues);
+          setAutoSaveStatus("saved");
+        } catch {
+          setAutoSaveStatus("error");
+        }
+      }, autoSave.delay);
+    });
+    return () => {
+      if (timer) clearTimeout(timer);
+      unsubscribe();
+    };
+  }, [autoSave, store]);
+
+  const ctxValue: FormContextValue = useMemo(
+    () => ({ mode: "plain", loading, autoSaveStatus, plainStore: store }),
+    [loading, autoSaveStatus, store],
+  );
+
+  return (
+    <FormCtx.Provider value={ctxValue}>
+      <form
+        noValidate
+        onSubmit={(e) => {
+          e.preventDefault();
+          onSubmit?.(store.getValues());
+        }}
+        {...formProps}
+      >
+        {/* `<fieldset disabled>` cascades the disabled state to all native
+          form controls inside. We strip the browser's default chrome and
+          carry the consumer's className here so layout utilities like
+          `space-y-*` apply to the fields (they would not on the <form>,
+          because the fieldset would be the only DOM child). */}
+        <fieldset
+          disabled={loading}
+          className={cn("min-w-0 m-0 p-0 border-0", className)}
+        >
+          {children}
+        </fieldset>
+      </form>
+    </FormCtx.Provider>
+  );
+}
+
+// ----- RHF implementation ----------------------------------------------------
+
+function FormRhf<T extends FieldValues>({
+  form,
+  onSubmit,
+  loading = false,
+  confirmBeforeLeave = false,
+  autoSave,
+  className,
+  children,
+  ...formProps
+}: FormRhfProps<T>) {
+  const [autoSaveStatus, setAutoSaveStatus] = useState<AutoSaveStatus>("idle");
+
+  useEffect(() => {
+    if (!confirmBeforeLeave) return;
+    const handler = (e: BeforeUnloadEvent) => {
+      if (form.formState.isDirty) {
+        e.preventDefault();
+        e.returnValue = "";
+      }
+    };
+    window.addEventListener("beforeunload", handler);
+    return () => {
+      window.removeEventListener("beforeunload", handler);
+    };
+  }, [confirmBeforeLeave, form]);
+
+  useEffect(() => {
+    if (!autoSave) return;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const subscription = form.watch((values) => {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(async () => {
+        setAutoSaveStatus("saving");
+        try {
+          await autoSave.onSave(values as T);
+          setAutoSaveStatus("saved");
+        } catch {
+          setAutoSaveStatus("error");
+        }
+      }, autoSave.delay);
+    });
+    return () => {
+      if (timer) clearTimeout(timer);
+      subscription.unsubscribe();
+    };
+  }, [autoSave, form]);
+
+  const ctxValue: FormContextValue = useMemo(
+    () => ({ mode: "rhf", loading, autoSaveStatus, plainStore: null }),
+    [loading, autoSaveStatus],
+  );
+
+  return (
+    <FormCtx.Provider value={ctxValue}>
+      <FormProvider {...(form as unknown as UseFormReturn<FieldValues>)}>
+        <form
+          noValidate
+          onSubmit={form.handleSubmit(async (values) => {
+            await onSubmit?.(values);
+          })}
+          {...formProps}
+        >
+          <fieldset
+            disabled={loading}
+            className={cn("min-w-0 m-0 p-0 border-0", className)}
+          >
+            {children}
+          </fieldset>
+        </form>
+      </FormProvider>
+    </FormCtx.Provider>
+  );
+}
+
+// ----------------------------------------------------------------------------
+// FormField
+// ----------------------------------------------------------------------------
+
+interface FormFieldProps {
+  name: string;
+  defaultValue?: unknown;
+  rules?: RegisterOptions;
+  /** Plain-mode only. Synchronous validator returning an error message. */
+  validate?: (value: unknown) => string | undefined;
+  render: FormFieldRender;
+}
+
+function FormField({ name, defaultValue, rules, validate, render }: FormFieldProps) {
+  const ctx = useFormCtx();
+  if (ctx.mode === "rhf") {
+    return rules !== undefined ? (
+      <FormFieldRhf name={name} defaultValue={defaultValue} rules={rules} render={render} />
+    ) : (
+      <FormFieldRhf name={name} defaultValue={defaultValue} render={render} />
+    );
+  }
+  return validate !== undefined ? (
+    <FormFieldPlain
+      name={name}
+      defaultValue={defaultValue}
+      validate={validate}
+      render={render}
+    />
+  ) : (
+    <FormFieldPlain name={name} defaultValue={defaultValue} render={render} />
+  );
+}
+
+// ----- Plain field -----------------------------------------------------------
+
+function FormFieldPlain({
+  name,
+  defaultValue,
+  validate,
+  render,
+}: Omit<FormFieldProps, "rules">) {
+  const ctx = useFormCtx();
+  const store = ctx.plainStore!;
+  const [, forceRender] = useState(0);
+  const registeredRef = useRef(false);
+
+  if (!registeredRef.current) {
+    store.registerField(name, defaultValue);
+    registeredRef.current = true;
+  }
+
+  useEffect(() => {
+    return store.subscribe(() => forceRender((n) => n + 1));
+  }, [store]);
+
+  const value = store.getValue(name);
+  const errorMsg = store.getError(name);
+  const isTouched = store.isTouched(name);
+  const isDirty = store.isDirty(name);
+
+  const field: FormRenderField = {
+    name,
+    value,
+    onChange: (next: unknown) => {
+      store.setValue(name, next);
+      const err = validate?.(next);
+      store.setError(name, err);
+    },
+    onBlur: () => {
+      store.setTouched(name);
+      const err = validate?.(store.getValue(name));
+      store.setError(name, err);
+    },
+    inputProps: {
+      name,
+      value: value == null ? "" : String(value),
+      onChange: (e) => {
+        const next = e.target.value;
+        store.setValue(name, next);
+        const err = validate?.(next);
+        store.setError(name, err);
+      },
+      onBlur: () => {
+        store.setTouched(name);
+        const err = validate?.(store.getValue(name));
+        store.setError(name, err);
+      },
+    },
+  };
+
+  const fieldState: FormRenderFieldState = {
+    invalid: Boolean(errorMsg),
+    isTouched,
+    isDirty,
+    error: errorMsg ? { message: errorMsg } : undefined,
+  };
+
+  return <>{render({ field, fieldState })}</>;
+}
+
+// ----- RHF field -------------------------------------------------------------
+
+function FormFieldRhf({
+  name,
+  defaultValue,
+  rules,
+  render,
+}: Omit<FormFieldProps, "validate">) {
+  const methods = useFormContext();
+  const controllerProps: Parameters<typeof Controller<FieldValues>>[0] = {
+    name: name as Path<FieldValues>,
+    control: methods.control as unknown as Control<FieldValues>,
+    defaultValue: defaultValue as never,
+    render: ({ field, fieldState }) => {
+      const f: FormRenderField = {
+        name: field.name,
+        value: field.value,
+        onChange: field.onChange,
+        onBlur: field.onBlur,
+        inputProps: {
+          name: field.name,
+          value:
+            field.value == null
+              ? ""
+              : typeof field.value === "string"
+                ? field.value
+                : String(field.value),
+          onChange: (e) => field.onChange(e.target.value),
+          onBlur: field.onBlur,
+        },
+      };
+      const s: FormRenderFieldState = {
+        invalid: fieldState.invalid,
+        isDirty: fieldState.isDirty,
+        isTouched: fieldState.isTouched,
+        error:
+          fieldState.error?.message !== undefined
+            ? { message: fieldState.error.message }
+            : fieldState.error
+              ? {}
+              : undefined,
+      };
+      return <>{render({ field: f, fieldState: s })}</>;
+    },
+  };
+  if (rules !== undefined) controllerProps.rules = rules;
+  return <Controller {...controllerProps} />;
+}
+
+// ----------------------------------------------------------------------------
+// FormError — top-level error slot with role="alert".
+// ----------------------------------------------------------------------------
+
+const FormError = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  function FormError({ className, ...props }, ref) {
+    return (
+      <div
+        ref={ref}
+        role="alert"
+        className={cn("text-sm text-destructive", className)}
+        {...props}
+      />
+    );
+  },
+);
+FormError.displayName = "FormError";
+
+// ----------------------------------------------------------------------------
+// useAutoSaveStatus — hook for consumers to react to autoSave state.
+// ----------------------------------------------------------------------------
+
+function useAutoSaveStatus(): AutoSaveStatus {
+  const ctx = useContext(FormCtx);
+  return ctx?.autoSaveStatus ?? "idle";
+}
+
+// Unused-import shim to keep useCallback / useId / useState in scope when
+// future passes wire them in. Removed when actually needed.
+void useCallback;
+void useId;
+
+export { Form, FormField, FormError, useAutoSaveStatus };
+export type { FormProps, FormFieldProps, AutoSaveStatus };

package/components/ui/input.stories.tsx

@@ -0,0 +1,154 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { RiMailLine, RiSearchLine } from "@remixicon/react";
+
+import { Input } from "./input";
+
+const meta: Meta<typeof Input> = {
+  title: "Foundations/Input",
+  component: Input,
+  parameters: { layout: "centered" },
+  argTypes: {
+    size: { control: "select", options: ["xs", "sm", "md", "lg", "xl"] },
+    type: {
+      control: "select",
+      options: ["text", "email", "password", "number", "tel", "url", "search"],
+    },
+    invalid: { control: "boolean" },
+    clearable: { control: "boolean" },
+    loading: { control: "boolean" },
+    disabled: { control: "boolean" },
+    readOnly: { control: "boolean" },
+  },
+  args: { placeholder: "Type something…" },
+};
+
+export default meta;
+type Story = StoryObj<typeof Input>;
+
+export const Default: Story = {
+  render: (args) => (
+    <div className="w-72">
+      <Input {...args} />
+    </div>
+  ),
+};
+
+/**
+ * One row per `type`, each pre-filled so the type-specific browser behavior is
+ * visible: password masks, number rejects letters, search shows the native
+ * clear-X chrome, etc. Placeholder text is always plain regardless of type.
+ */
+export const Types: Story = {
+  render: () => (
+    <div className="grid w-96 grid-cols-[5rem_1fr] items-center gap-x-4 gap-y-3">
+      <span className="text-sm font-medium">text</span>
+      <Input type="text" defaultValue="plain text 123" />
+
+      <span className="text-sm font-medium">email</span>
+      <Input type="email" defaultValue="alice@example.com" />
+
+      <span className="text-sm font-medium">password</span>
+      <Input type="password" defaultValue="secret123" />
+
+      <span className="text-sm font-medium">number</span>
+      <Input type="number" defaultValue="42" />
+
+      <span className="text-sm font-medium">tel</span>
+      <Input type="tel" defaultValue="+212 6 12 34 56 78" />
+
+      <span className="text-sm font-medium">url</span>
+      <Input type="url" defaultValue="https://example.com" />
+
+      <span className="text-sm font-medium">search</span>
+      <Input type="search" defaultValue="cats" />
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  render: (args) => (
+    <div className="w-72 space-y-2">
+      <Input {...args} size="xs" placeholder="xs" />
+      <Input {...args} size="sm" placeholder="sm" />
+      <Input {...args} size="md" placeholder="md" />
+      <Input {...args} size="lg" placeholder="lg" />
+      <Input {...args} size="xl" placeholder="xl" />
+    </div>
+  ),
+};
+
+export const Invalid: Story = {
+  args: { invalid: true, defaultValue: "not-an-email" },
+  render: (args) => (
+    <div className="w-72">
+      <Input {...args} />
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  args: { disabled: true, defaultValue: "Read this" },
+  render: (args) => (
+    <div className="w-72">
+      <Input {...args} />
+    </div>
+  ),
+};
+
+export const ReadOnly: Story = {
+  args: { readOnly: true, defaultValue: "Read-only value" },
+  render: (args) => (
+    <div className="w-72">
+      <Input {...args} />
+    </div>
+  ),
+};
+
+export const WithStartAdornment: Story = {
+  args: { startAdornment: <RiSearchLine />, placeholder: "Search" },
+  render: (args) => (
+    <div className="w-72">
+      <Input {...args} />
+    </div>
+  ),
+};
+
+export const WithEndAdornment: Story = {
+  args: { endAdornment: <span className="text-xs">MAD</span>, placeholder: "0.00", type: "number" },
+  render: (args) => (
+    <div className="w-72">
+      <Input {...args} />
+    </div>
+  ),
+};
+
+export const BothAdornments: Story = {
+  args: {
+    startAdornment: <RiMailLine />,
+    endAdornment: <span className="text-xs">@example.com</span>,
+    placeholder: "alice",
+  },
+  render: (args) => (
+    <div className="w-72">
+      <Input {...args} />
+    </div>
+  ),
+};
+
+export const Clearable: Story = {
+  args: { clearable: true, defaultValue: "Erase me" },
+  render: (args) => (
+    <div className="w-72">
+      <Input {...args} />
+    </div>
+  ),
+};
+
+export const Loading: Story = {
+  args: { loading: true, defaultValue: "Loading…" },
+  render: (args) => (
+    <div className="w-72">
+      <Input {...args} />
+    </div>
+  ),
+};