@emara/ui 1.1.0

package/components/ui/field-group.tsx

@@ -0,0 +1,276 @@
+"use client";
+
+import {
+  createContext,
+  forwardRef,
+  isValidElement,
+  cloneElement,
+  useContext,
+  useId,
+  Children,
+  type ReactElement,
+} from "react";
+
+import { cn } from "@/lib/utils";
+import { Label } from "./label";
+
+// Per docs/emara-ui-phase-2-components.md §7.
+// FieldGroup is a pure-composition primitive — no Radix, no behavior of its
+// own. It centralizes a11y wiring (label↔control, aria-describedby for help,
+// aria-errormessage for error) so callers don't have to repeat boilerplate.
+
+// ----------------------------------------------------------------------------
+// Context — propagates id/required/optional/invalid/disabled to sub-parts.
+// ----------------------------------------------------------------------------
+
+interface FieldGroupContextValue {
+  id: string;
+  helpId: string | undefined;
+  errorId: string | undefined;
+  required: boolean;
+  optional: boolean;
+  invalid: boolean;
+  disabled: boolean;
+  orientation: "vertical" | "horizontal";
+  /** Override for the horizontal-layout label column width (CSS length).
+   *  Undefined → use the `--field-label-min-w` token default. */
+  labelWidth: string | undefined;
+}
+
+const FieldGroupContext = createContext<FieldGroupContextValue | null>(null);
+
+function useFieldGroup(): FieldGroupContextValue {
+  const ctx = useContext(FieldGroupContext);
+  if (!ctx) {
+    throw new Error("FieldGroup sub-component must be rendered inside a <FieldGroup>.");
+  }
+  return ctx;
+}
+
+// ----------------------------------------------------------------------------
+// Root
+// ----------------------------------------------------------------------------
+
+interface FieldGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "id"> {
+  id?: string;
+  required?: boolean;
+  optional?: boolean;
+  invalid?: boolean;
+  disabled?: boolean;
+  orientation?: "vertical" | "horizontal";
+  /** When `orientation="horizontal"`, override the label column width.
+   *  Accepts any CSS length (e.g. `"10rem"`, `"180px"`, `"min(20%, 12rem)"`).
+   *  Default: `--field-label-min-w` token (7rem). */
+  labelWidth?: string;
+}
+
+const FieldGroupRoot = forwardRef<HTMLDivElement, FieldGroupProps>(function FieldGroup(
+  {
+    className,
+    id,
+    required = false,
+    optional = false,
+    invalid = false,
+    disabled = false,
+    orientation = "vertical",
+    labelWidth,
+    children,
+    ...props
+  },
+  ref,
+) {
+  if (required && optional) {
+    throw new Error("FieldGroup: `required` and `optional` are mutually exclusive.");
+  }
+
+  const reactId = useId();
+  const fieldId = id ?? reactId;
+  const helpId = `${fieldId}-help`;
+  const errorId = `${fieldId}-error`;
+
+  // First pass: detect whether HelpText/ErrorText are actually rendered. This
+  // is what lets us decide whether to wire `aria-describedby`/`aria-errormessage`.
+  let hasHelp = false;
+  let hasError = false;
+  Children.forEach(children, (child) => {
+    if (!isValidElement(child)) return;
+    if (child.type === FieldHelpText) hasHelp = true;
+    if (child.type === FieldErrorText && invalid) hasError = true;
+  });
+
+  const value: FieldGroupContextValue = {
+    id: fieldId,
+    required,
+    optional,
+    invalid,
+    disabled,
+    orientation,
+    helpId: hasHelp ? helpId : undefined,
+    errorId: hasError ? errorId : undefined,
+    labelWidth,
+  };
+
+  return (
+    <FieldGroupContext.Provider value={value}>
+      <div
+        ref={ref}
+        data-disabled={disabled || undefined}
+        className={cn(
+          "group/field",
+          orientation === "vertical" ? "space-y-1.5" : "flex items-start gap-4",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </div>
+    </FieldGroupContext.Provider>
+  );
+});
+FieldGroupRoot.displayName = "FieldGroup";
+
+// ----------------------------------------------------------------------------
+// FieldGroup.Label — wraps the Emara Label, forwards required/optional from the
+// parent FieldGroup so the consumer doesn't have to set them twice.
+// ----------------------------------------------------------------------------
+
+const FieldLabel = forwardRef<
+  HTMLLabelElement,
+  Omit<React.ComponentProps<typeof Label>, "htmlFor" | "required" | "optional">
+>(function FieldGroupLabel({ className, style, ...props }, ref) {
+  const ctx = useFieldGroup();
+  const horizontal = ctx.orientation === "horizontal";
+  // When a labelWidth override is set, drive min-width via inline style so it
+  // wins over the token default. Otherwise the `min-w-field-label` class
+  // applies the token.
+  const horizontalStyle =
+    horizontal && ctx.labelWidth !== undefined ? { minWidth: ctx.labelWidth } : undefined;
+  return (
+    <Label
+      ref={ref}
+      htmlFor={ctx.id}
+      required={ctx.required}
+      optional={ctx.optional}
+      style={horizontalStyle ? { ...horizontalStyle, ...style } : style}
+      className={cn(
+        horizontal && "pt-1.5",
+        horizontal && ctx.labelWidth === undefined && "min-w-field-label",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+FieldLabel.displayName = "FieldGroup.Label";
+
+// ----------------------------------------------------------------------------
+// FieldGroup.Control — clones the single child and injects `id`,
+// `aria-invalid`, `aria-describedby`, `aria-errormessage`, and `disabled`.
+// ----------------------------------------------------------------------------
+
+type ControlInjectedProps = {
+  id?: string | undefined;
+  "aria-invalid"?: boolean | "true" | "false" | undefined;
+  "aria-describedby"?: string | undefined;
+  "aria-errormessage"?: string | undefined;
+  disabled?: boolean | undefined;
+  required?: boolean | undefined;
+  invalid?: boolean | undefined;
+};
+
+interface FieldControlProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+  children: ReactElement;
+}
+
+const FieldControl = forwardRef<HTMLDivElement, FieldControlProps>(function FieldGroupControl(
+  { className, children, ...props },
+  ref,
+) {
+  const ctx = useFieldGroup();
+
+  const describedBy = [ctx.helpId, ctx.errorId].filter(Boolean).join(" ") || undefined;
+
+  const childProps = (children.props ?? {}) as ControlInjectedProps;
+  const injected: ControlInjectedProps = {
+    id: childProps.id ?? ctx.id,
+    "aria-invalid": ctx.invalid || undefined,
+    "aria-describedby":
+      [childProps["aria-describedby"], describedBy].filter(Boolean).join(" ").trim() || undefined,
+    "aria-errormessage": ctx.errorId,
+    disabled: childProps.disabled ?? ctx.disabled,
+  };
+  // Some Emara controls have their own `invalid` / `required` props that drive
+  // styling; pass them through so the FieldGroup is the source of truth.
+  if (ctx.invalid && childProps.invalid === undefined) injected.invalid = true;
+  if (ctx.required && childProps.required === undefined) injected.required = true;
+
+  const cloned = cloneElement(children, injected);
+
+  return (
+    <div ref={ref} className={cn("flex-1", className)} {...props}>
+      {cloned}
+    </div>
+  );
+});
+FieldControl.displayName = "FieldGroup.Control";
+
+// ----------------------------------------------------------------------------
+// FieldGroup.HelpText
+// ----------------------------------------------------------------------------
+
+const FieldHelpText = forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(
+  function FieldGroupHelpText({ className, ...props }, ref) {
+    const ctx = useFieldGroup();
+    return (
+      <p
+        ref={ref}
+        id={ctx.helpId}
+        className={cn("text-muted-foreground text-xs", className)}
+        {...props}
+      />
+    );
+  },
+);
+FieldHelpText.displayName = "FieldGroup.HelpText";
+
+// ----------------------------------------------------------------------------
+// FieldGroup.ErrorText — renders only when the FieldGroup is invalid.
+// ----------------------------------------------------------------------------
+
+const FieldErrorText = forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(
+  function FieldGroupErrorText({ className, ...props }, ref) {
+    const ctx = useFieldGroup();
+    if (!ctx.invalid) return null;
+    return (
+      <p
+        ref={ref}
+        id={ctx.errorId}
+        role="alert"
+        className={cn("text-destructive text-xs", className)}
+        {...props}
+      />
+    );
+  },
+);
+FieldErrorText.displayName = "FieldGroup.ErrorText";
+
+// ----------------------------------------------------------------------------
+// Compose the dotted-namespace API while keeping each part exportable on its
+// own (useful for tests and re-exports).
+// ----------------------------------------------------------------------------
+
+type FieldGroupNamespace = typeof FieldGroupRoot & {
+  Label: typeof FieldLabel;
+  Control: typeof FieldControl;
+  HelpText: typeof FieldHelpText;
+  ErrorText: typeof FieldErrorText;
+};
+
+const FieldGroup = FieldGroupRoot as FieldGroupNamespace;
+FieldGroup.Label = FieldLabel;
+FieldGroup.Control = FieldControl;
+FieldGroup.HelpText = FieldHelpText;
+FieldGroup.ErrorText = FieldErrorText;
+
+export { FieldGroup, FieldLabel, FieldControl, FieldHelpText, FieldErrorText };
+export type { FieldGroupProps, FieldControlProps };

package/components/ui/form.stories.tsx

@@ -0,0 +1,219 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { useForm } from "react-hook-form";
+
+import { Button } from "./button";
+import { FieldGroup } from "./field-group";
+import { Form, FormError, FormField } from "./form";
+import { Input } from "./input";
+import { Textarea } from "./textarea";
+import { TooltipProvider } from "./tooltip";
+
+const meta: Meta<typeof Form> = {
+  title: "Forms/Form",
+  component: Form,
+  parameters: { layout: "centered" },
+  decorators: [
+    (Story) => (
+      <TooltipProvider delayDuration={200}>
+        <div className="w-96">
+          <Story />
+        </div>
+      </TooltipProvider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Form>;
+
+// ----------------------------------------------------------------------------
+// Plain mode — no react-hook-form, FormField owns its own state.
+// ----------------------------------------------------------------------------
+
+export const PlainMode: Story = {
+  render: () => {
+    const Wrapper = () => {
+      const [submitted, setSubmitted] = useState<Record<string, unknown> | null>(null);
+      return (
+        <Form
+          className="space-y-4"
+          onSubmit={(values) => {
+            setSubmitted(values);
+          }}
+        >
+          <FormField
+            name="name"
+            defaultValue=""
+            render={({ field, fieldState }) => (
+              <FieldGroup required invalid={fieldState.invalid}>
+                <FieldGroup.Label>Full name</FieldGroup.Label>
+                <FieldGroup.Control>
+                  <Input placeholder="Alice Bouchaib" {...field.inputProps} />
+                </FieldGroup.Control>
+                <FieldGroup.ErrorText>{fieldState.error?.message}</FieldGroup.ErrorText>
+              </FieldGroup>
+            )}
+          />
+          <FormField
+            name="email"
+            defaultValue=""
+            validate={(v) =>
+              typeof v === "string" && /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(v)
+                ? undefined
+                : "Enter a valid email."
+            }
+            render={({ field, fieldState }) => (
+              <FieldGroup required invalid={fieldState.invalid}>
+                <FieldGroup.Label>Email</FieldGroup.Label>
+                <FieldGroup.Control>
+                  <Input type="email" placeholder="alice@example.com" {...field.inputProps} />
+                </FieldGroup.Control>
+                <FieldGroup.HelpText>We&apos;ll never share this.</FieldGroup.HelpText>
+                <FieldGroup.ErrorText>{fieldState.error?.message}</FieldGroup.ErrorText>
+              </FieldGroup>
+            )}
+          />
+          <FormField
+            name="bio"
+            defaultValue=""
+            render={({ field }) => (
+              <FieldGroup optional>
+                <FieldGroup.Label>Bio</FieldGroup.Label>
+                <FieldGroup.Control>
+                  <Textarea placeholder="Tell us a bit about yourself…" {...field.inputProps} />
+                </FieldGroup.Control>
+              </FieldGroup>
+            )}
+          />
+          <Button type="submit">Save</Button>
+          {submitted ? (
+            <pre className="border-border bg-muted rounded-md border p-3 text-xs">
+              {JSON.stringify(submitted, null, 2)}
+            </pre>
+          ) : null}
+        </Form>
+      );
+    };
+    return <Wrapper />;
+  },
+};
+
+// ----------------------------------------------------------------------------
+// RHF mode — consumer provides `useForm()` result.
+// ----------------------------------------------------------------------------
+
+type RhfValues = { name: string; email: string };
+
+export const RhfMode: Story = {
+  render: () => {
+    const Wrapper = () => {
+      const form = useForm<RhfValues>({
+        defaultValues: { name: "", email: "" },
+        mode: "onBlur",
+      });
+      const [submitted, setSubmitted] = useState<RhfValues | null>(null);
+
+      return (
+        <Form
+          mode="rhf"
+          form={form}
+          className="space-y-4"
+          onSubmit={(values) => {
+            setSubmitted(values);
+          }}
+        >
+          <FormField
+            name="name"
+            rules={{ required: "Name is required" }}
+            render={({ field, fieldState }) => (
+              <FieldGroup required invalid={fieldState.invalid}>
+                <FieldGroup.Label>Full name</FieldGroup.Label>
+                <FieldGroup.Control>
+                  <Input placeholder="Alice Bouchaib" {...field.inputProps} />
+                </FieldGroup.Control>
+                <FieldGroup.ErrorText>{fieldState.error?.message}</FieldGroup.ErrorText>
+              </FieldGroup>
+            )}
+          />
+          <FormField
+            name="email"
+            rules={{
+              required: "Email is required",
+              pattern: { value: /^[^@\s]+@[^@\s]+\.[^@\s]+$/, message: "Invalid email" },
+            }}
+            render={({ field, fieldState }) => (
+              <FieldGroup required invalid={fieldState.invalid}>
+                <FieldGroup.Label>Email</FieldGroup.Label>
+                <FieldGroup.Control>
+                  <Input type="email" placeholder="alice@example.com" {...field.inputProps} />
+                </FieldGroup.Control>
+                <FieldGroup.ErrorText>{fieldState.error?.message}</FieldGroup.ErrorText>
+              </FieldGroup>
+            )}
+          />
+          <Button type="submit">Save</Button>
+          {submitted ? (
+            <pre className="border-border bg-muted rounded-md border p-3 text-xs">
+              {JSON.stringify(submitted, null, 2)}
+            </pre>
+          ) : null}
+        </Form>
+      );
+    };
+    return <Wrapper />;
+  },
+};
+
+export const Loading: Story = {
+  render: () => (
+    <Form className="space-y-4" loading onSubmit={() => {}}>
+      <FormField
+        name="name"
+        defaultValue=""
+        render={({ field }) => (
+          <FieldGroup>
+            <FieldGroup.Label>Name</FieldGroup.Label>
+            <FieldGroup.Control>
+              <Input placeholder="Submitting…" {...field.inputProps} />
+            </FieldGroup.Control>
+          </FieldGroup>
+        )}
+      />
+      <Button type="submit">Save</Button>
+    </Form>
+  ),
+};
+
+export const TopLevelError: Story = {
+  render: () => (
+    <Form className="space-y-4" onSubmit={() => {}}>
+      <FormError>Sign-in failed. Check your password and try again.</FormError>
+      <FormField
+        name="email"
+        defaultValue=""
+        render={({ field }) => (
+          <FieldGroup>
+            <FieldGroup.Label>Email</FieldGroup.Label>
+            <FieldGroup.Control>
+              <Input {...field.inputProps} />
+            </FieldGroup.Control>
+          </FieldGroup>
+        )}
+      />
+      <FormField
+        name="password"
+        defaultValue=""
+        render={({ field }) => (
+          <FieldGroup>
+            <FieldGroup.Label>Password</FieldGroup.Label>
+            <FieldGroup.Control>
+              <Input type="password" {...field.inputProps} />
+            </FieldGroup.Control>
+          </FieldGroup>
+        )}
+      />
+      <Button type="submit">Sign in</Button>
+    </Form>
+  ),
+};