torch-glare 2.4.0 → 2.4.2

package/apps/lib/components/FormBuilder/form-builder.tsx

@@ -0,0 +1,292 @@
+"use client";
+
+import * as React from "react";
+import { ReactNode } from "react";
+import { useForm, type FieldValues } from "react-hook-form";
+
+import { cn } from "../../utils/cn";
+import { Form } from "../Form";
+import { SectionBlock, type SectionColor } from "../SectionBlock";
+import {
+  LoadingContext,
+  ModeContext,
+  DirectionContext,
+  StepperContext,
+  FormIdContext,
+} from "./context";
+import { Header } from "./header";
+import type { FormBuilderRootProps } from "./types";
+import {
+  TextField,
+  EmailField,
+  PasswordField,
+  NumberField,
+  CurrencyField,
+  TextareaField,
+  SelectField,
+  SearchableSelectField,
+  MultiSelectField,
+  CheckboxField,
+  RadioCardsField,
+  RadioListField,
+  CheckboxGroupField,
+  SwitchBoxField,
+  DateField,
+  OtpField,
+  TreeSelectField,
+  SliderField,
+  ColorField,
+  SignatureField,
+  PhoneField,
+  FieldArray,
+  TableField,
+  FileField,
+  RichTextField,
+  CustomField,
+} from "./fields";
+import {
+  Stepper,
+  Step,
+  Back,
+  Next,
+  StepperNav,
+  StepSlot,
+  useStepperState,
+  isStepElement,
+  isStepperElement,
+} from "./stepper";
+import { SubmitButton } from "./submit";
+
+// ─── Section ─────────────────────────────────────────────────────────────────
+
+export interface SectionProps {
+  title?: ReactNode;
+  color?: SectionColor;
+  icon?: ReactNode;
+  children: ReactNode;
+}
+
+/** `FormBuilder.Section` — a titled Glare SectionBlock grouping fields. */
+function Section({ title, color, icon, children }: SectionProps) {
+  return (
+    <SectionBlock title={title} color={color} icon={icon}>
+      {children}
+    </SectionBlock>
+  );
+}
+
+function isHeaderElement(node: React.ReactNode): node is React.ReactElement {
+  return (
+    React.isValidElement(node) &&
+    (node.type as { __isFormHeader?: boolean })?.__isFormHeader === true
+  );
+}
+
+// ─── Root ────────────────────────────────────────────────────────────────────
+
+function FormBuilderRoot<T extends FieldValues = FieldValues>({
+  children,
+  id,
+  form: formProp,
+  onSubmit,
+  onInvalid,
+  resolver,
+  defaultValues,
+  values,
+  loading = false,
+  mode = "edit",
+  fieldDirection,
+  resetOnSuccess,
+  conclusion,
+  className,
+}: FormBuilderRootProps<T>) {
+  // Hooks can't be conditional, so always create one; `formProp` wins when given
+  // (the caller hoisted `useForm` to share values with something outside the form).
+  const ownForm = useForm<T>({ resolver, defaultValues, values });
+  const form = formProp ?? ownForm;
+  // Don't force a direction — left undefined, FieldSection uses its responsive `flexible`
+  // layout (stacked on small screens, two-column at `lg`). Only a caller-set `fieldDirection`
+  // (e.g. vertical inside a drawer) pins it.
+  const direction = fieldDirection;
+
+  const handleValid = async (v: T) => {
+    await onSubmit(v);
+    if (resetOnSuccess) form.reset();
+  };
+
+  // Split out a FormBuilder.Header (renders absolutely) and detect a Stepper child.
+  const childArray = React.Children.toArray(children);
+  const header = childArray.find(isHeaderElement);
+  const rest = childArray.filter((n) => !isHeaderElement(n));
+
+  const isView = mode === "view";
+  const stepperEl = rest.find(isStepperElement);
+  const stepChildren = stepperEl ? React.Children.toArray(stepperEl.props.children) : [];
+  const steps = stepChildren.filter(isStepElement);
+  const stepExtras = stepChildren.filter((n) => !isStepElement(n));
+  const isStepper = !!stepperEl && !isView;
+
+  // Stepper state is lifted HERE so the nav can live in its own grid column, outside the
+  // `<form>`. Called unconditionally (inert when there are no steps) to keep hooks order stable.
+  const stepper = useStepperState(steps, form.trigger as Parameters<typeof useStepperState>[1]);
+
+  // The stepper nav is its own column beside the fields, inside the form surface.
+  const nav = isStepper ? <StepperNav /> : null;
+
+  // The fields the `<form>` wraps: the stepper's steps (+ any custom footer extras like
+  // Back/Next), or the plain children. The Submit itself lives outside the form (see FormRenderer).
+  const fields = isStepper ? (
+    <>
+      {steps.map((step, i) => (
+        <StepSlot key={i} index={i} active={i === stepper.currentStep}>
+          {step.props.children}
+        </StepSlot>
+      ))}
+      {stepExtras}
+    </>
+  ) : (
+    rest
+  );
+
+  // The fields column caps at 1200px and centers — as the middle column of the grid, and
+  // standalone.
+  const fieldsInner = (
+    <div className="mx-auto flex w-full max-w-[1100px] flex-col gap-4">{fields}</div>
+  );
+
+  const formEl = isView ? (
+    <div className="w-full min-w-0">{fieldsInner}</div>
+  ) : (
+    <form id={id} className="w-full min-w-0" onSubmit={form.handleSubmit(handleValid, onInvalid)}>
+      {fieldsInner}
+    </form>
+  );
+
+  // Inside the form surface: the stepper rail beside the fields. Columns never wrap — the
+  // layout stays side-by-side at every screen size (the fields column shrinks instead).
+  const bodyInner = nav ? (
+    <div className="grid w-full grid-cols-[1fr_minmax(0,1100px)_1fr] gap-8">
+      {nav}
+      {formEl}
+      {/* Empty third column — balances the rail's gutter so the middle column is centred. */}
+      <div />
+    </div>
+  ) : (
+    formEl
+  );
+
+  const surface = header ? (
+    // Scroll shell: the absolute header floats over the scrollable body. No fixed height — it
+    // fills whatever the parent gives it (like the drawer's panel fills its tray) and the body
+    // scrolls internally.
+    <div className="relative isolate flex h-full w-full flex-col overflow-hidden rounded-2xl bg-background-presentation-body-primary">
+      {header}
+      <div className="relative z-[1] flex min-h-0 w-full flex-1 flex-col overflow-y-auto px-6 py-6 pt-[72px] scrollbar-hide">
+        {bodyInner}
+      </div>
+    </div>
+  ) : (
+    bodyInner
+  );
+
+  // The conclusion lives OUTSIDE the form surface — its own panel beside it, exactly like the
+  // drawer's tray (`FormDrawer` puts the conclusion next to the form panel with a 6px gutter).
+  // It never wraps below the form: the two stay side-by-side at every screen size.
+  const body = conclusion ? (
+    <div className="flex h-full flex-row items-stretch gap-[6px]">
+      <div className="min-h-0 min-w-0 flex-1">{surface}</div>
+      <div className="flex min-h-0">{conclusion}</div>
+    </div>
+  ) : (
+    surface
+  );
+
+  // `className` lands on the OUTERMOST element — the one a parent lays out (e.g. `flex-1 min-h-0`
+  // to fill a flex column). `h-full` fills a parent that has a definite height.
+  const outerClassName = cn("h-full w-full", className);
+
+  const tree = (
+    <Form {...form}>
+      <div className={outerClassName}>{body}</div>
+    </Form>
+  );
+
+  return (
+    <FormIdContext.Provider value={id}>
+      <LoadingContext.Provider value={loading}>
+        <ModeContext.Provider value={mode}>
+          <DirectionContext.Provider value={direction}>
+            {isStepper ? (
+              <StepperContext.Provider value={stepper}>{tree}</StepperContext.Provider>
+            ) : (
+              tree
+            )}
+          </DirectionContext.Provider>
+        </ModeContext.Provider>
+      </LoadingContext.Provider>
+    </FormIdContext.Provider>
+  );
+}
+
+/**
+ * FormBuilder — a compound, composition-based form. Author a form as JSX:
+ *
+ * ```tsx
+ * <FormBuilder onSubmit={fn} resolver={r} defaultValues={d}>
+ *   <FormBuilder.Section title="Identity" color="Blue">
+ *     <FormBuilder.Text name="name" label="Name" required />
+ *   </FormBuilder.Section>
+ *   <FormBuilder.Submit>Save</FormBuilder.Submit>
+ * </FormBuilder>
+ * ```
+ *
+ * Steps are components (`FormBuilder.Stepper` + `FormBuilder.Step`) and
+ * `mode="view"` renders read-only. FormBuilder is drawer-unaware — to show a form
+ * in a drawer, wrap it in `FormRenderer`'s `FormDrawer` (or use `FormRenderer`
+ * with `display: "drawer"`).
+ */
+export const FormBuilder = Object.assign(FormBuilderRoot, {
+  // fields
+  Text: TextField,
+  Email: EmailField,
+  Password: PasswordField,
+  Number: NumberField,
+  Currency: CurrencyField,
+  Textarea: TextareaField,
+  Select: SelectField,
+  SearchableSelect: SearchableSelectField,
+  MultiSelect: MultiSelectField,
+  Tags: MultiSelectField,
+  RadioList: RadioListField,
+  RadioCards: RadioCardsField,
+  Checkbox: CheckboxField,
+  CheckboxGroup: CheckboxGroupField,
+  SwitchBox: SwitchBoxField,
+  Otp: OtpField,
+  TreeSelect: TreeSelectField,
+  Slider: SliderField,
+  Color: ColorField,
+  Signature: SignatureField,
+  Phone: PhoneField,
+  FieldArray: FieldArray,
+  Table: TableField,
+  Date: DateField,
+  DateRange: (props: Parameters<typeof DateField>[0]) => <DateField {...props} mode="range" />,
+  DateMultiple: (props: Parameters<typeof DateField>[0]) => (
+    <DateField {...props} mode="multiple" />
+  ),
+  DateTime: (props: Parameters<typeof DateField>[0]) => <DateField {...props} timePicker />,
+  File: FileField,
+  Image: (props: Parameters<typeof FileField>[0]) => <FileField {...props} image />,
+  RichText: RichTextField,
+  Custom: CustomField,
+  // layout
+  Section,
+  Header,
+  Submit: SubmitButton,
+  // stepper
+  Stepper,
+  Step,
+  Back,
+  Next,
+});

package/apps/lib/components/FormBuilder/header.tsx

@@ -0,0 +1,105 @@
+"use client";
+
+import { ReactNode } from "react";
+
+import { cn } from "../../utils/cn";
+import { HeaderBar } from "../HeaderBar";
+import { useMode } from "./context";
+
+export type HeaderVariant = "new" | "edit" | "detail";
+
+const DEFAULT_LABEL: Record<HeaderVariant, string> = {
+  new: "New",
+  edit: "Edit",
+  detail: "View",
+};
+
+export interface FormHeaderBarProps {
+  /** Plain title text (uppercased), e.g. the entity label or SKU. */
+  title: string;
+  /** Badge text — defaults from `variant` (New / Edit / View). */
+  label?: string;
+  /** Colored badge variant. */
+  variant?: HeaderVariant;
+  /** Action buttons shown in the right-hand action pill. */
+  children?: ReactNode;
+  className?: string;
+}
+
+/**
+ * The floating form header: a `HeaderBar` title pill on the left and a dark action
+ * pill on the right, absolutely positioned over the scrollable body.
+ *
+ * Shared by **both** form surfaces — `FormBuilder.Header` (page) and `FormDrawer`
+ * (drawer) — so a form's title looks identical wherever it is rendered.
+ *
+ * Per the design both pills are 44px tall, reached differently: the title pill is
+ * 6px padding + 32px content, the action pill 8px + 28px.
+ */
+export function FormHeaderBar({
+  title,
+  label,
+  variant = "new",
+  children,
+  className,
+}: FormHeaderBarProps) {
+  return (
+    <div
+      className={cn(
+        "absolute inset-x-0 top-0 z-[2] flex w-full items-start justify-between gap-2 p-1",
+        className,
+      )}
+    >
+      <HeaderBar
+        variant={variant}
+        label={label ?? DEFAULT_LABEL[variant]}
+        title={title}
+        theme="dark"
+      />
+
+      {children && (
+        <div
+          data-theme="dark"
+          className="flex flex-col items-start rounded-[14px] border border-border-presentation-global-primary bg-background-presentation-form-base shadow-[0_0_32px_0_rgba(0,0,0,0.15)]"
+        >
+          <div className="sticky top-0 flex w-full items-center justify-between p-2">
+            <div className="flex h-7 items-center justify-center gap-2">{children}</div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export interface HeaderProps {
+  /** Plain title text (uppercased), e.g. the entity label or SKU. */
+  title: string;
+  /** Badge text — defaults from `variant` (New / Edit / View). */
+  label?: string;
+  /** Colored badge variant. Defaults from the form `mode` (view → detail). */
+  variant?: HeaderVariant;
+  /** Action buttons shown in the right-hand action pill (e.g. FormBuilder.Submit). */
+  children?: ReactNode;
+}
+
+/**
+ * `FormBuilder.Header` — the page form's title + action bar. A thin, mode-aware
+ * wrapper over `FormHeaderBar`: it defaults the badge variant from the form `mode`
+ * (view → detail).
+ *
+ * Place it as a direct child of `<FormBuilder>`; the root then switches to the
+ * scroll-shell layout that reserves space beneath the floating header.
+ */
+export function Header({ title, label, variant, children }: HeaderProps) {
+  const mode = useMode();
+  const v: HeaderVariant = variant ?? (mode === "view" ? "detail" : "new");
+
+  return (
+    <FormHeaderBar title={title} label={label} variant={v}>
+      {children}
+    </FormHeaderBar>
+  );
+}
+
+// Marker so the FormBuilder root can detect the header among its children.
+(Header as unknown as { __isFormHeader: boolean }).__isFormHeader = true;

package/apps/lib/components/FormBuilder/index.ts

@@ -0,0 +1,37 @@
+export { FormBuilder } from "./form-builder";
+export type { SectionProps } from "./form-builder";
+export { FormHeaderBar } from "./header";
+export type { HeaderProps, HeaderVariant, FormHeaderBarProps } from "./header";
+export { DisplayField } from "./DisplayField";
+export type { DisplayFieldProps } from "./DisplayField";
+export { RichTextField } from "../TextEditor/RichTextField";
+export { formatFieldView } from "./viewFormat";
+export type { FieldView, ViewKind, ViewFormatOptions } from "./viewFormat";
+export type { StepProps } from "./stepper";
+export type { FormBuilderMode, FieldDirection } from "./context";
+export type {
+  BaseFieldProps,
+  OptionItem,
+  SelectFieldProps,
+  SearchableSelectFieldProps,
+  OptionsFieldProps,
+  CurrencyFieldProps,
+  FileFieldProps,
+  CustomFieldProps,
+  DateFieldProps,
+  OtpFieldProps,
+  RadioCardOption,
+  RadioCardsFieldProps,
+  SwitchBoxFieldProps,
+  CheckboxFieldProps,
+  TreeSelectFieldProps,
+  PasswordFieldProps,
+  SliderFieldProps,
+  ColorFieldProps,
+  SignatureFieldProps,
+  PhoneFieldProps,
+  FieldArrayProps,
+  TableColumn,
+  TableFieldProps,
+  FormBuilderRootProps,
+} from "./types";

package/apps/lib/components/FormBuilder/numberFormat.ts

@@ -0,0 +1,16 @@
+const nf = new Intl.NumberFormat("en-US", { maximumFractionDigits: 20 });
+
+/** Format a number with thousands separators (e.g. 1299 → "1,299"). Blank for empty. */
+export function formatNumber(value: unknown): string {
+  if (value == null || value === "") return "";
+  const n = typeof value === "number" ? value : Number(String(value).replace(/,/g, ""));
+  return Number.isNaN(n) ? "" : nf.format(n);
+}
+
+/** Parse a possibly comma-formatted string to a number (or undefined when blank). */
+export function parseNumber(raw: string): number | undefined {
+  const cleaned = raw.replace(/,/g, "").trim();
+  if (cleaned === "" || cleaned === "-" || cleaned === ".") return undefined;
+  const n = Number(cleaned);
+  return Number.isNaN(n) ? undefined : n;
+}

package/apps/lib/components/FormBuilder/stepper.tsx

@@ -0,0 +1,217 @@
+"use client";
+
+import * as React from "react";
+import { useFormState, type FieldPath, type FieldValues } from "react-hook-form";
+
+import { cn } from "../../utils/cn";
+import { Button } from "../Button";
+import { FormStepper, FormStep, FormStepIndicator, FormStepLabel } from "../FormStepper";
+import { StepContext, useStepper, type StepperContextValue, type StepRegistry } from "./context";
+
+// ─── Step (declaration only — the Stepper reads its props) ───────────────────
+
+export interface StepProps {
+  title: string;
+  description?: string;
+  children: React.ReactNode;
+}
+
+/**
+ * Declares a wizard step. It renders nothing itself — `FormBuilder.Stepper`
+ * collects Step elements as an array and renders every step's fields (so the
+ * **whole form is registered**), toggling visibility per the active step.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- props are read by Stepper, not rendered here
+export function Step(_props: StepProps) {
+  return null;
+}
+(Step as unknown as { __isFormStep: boolean }).__isFormStep = true;
+
+export function isStepElement(node: React.ReactNode): node is React.ReactElement<StepProps> {
+  return (
+    React.isValidElement(node) && (node.type as { __isFormStep?: boolean })?.__isFormStep === true
+  );
+}
+
+// ─── StepSlot — mounts one step's fields; hidden when not active ─────────────
+
+function StepSlot({
+  index,
+  active,
+  children,
+}: {
+  index: number;
+  active: boolean;
+  children: React.ReactNode;
+}) {
+  const stepper = useStepper();
+  const registry: StepRegistry = React.useMemo(
+    () => ({
+      register: (name) => {
+        (stepper.stepFields[index] ??= new Set()).add(name);
+      },
+      unregister: (name) => {
+        stepper.stepFields[index]?.delete(name);
+      },
+    }),
+    [stepper, index],
+  );
+
+  // Always mounted (fields stay registered); CSS hides inactive steps.
+  return (
+    <div className={cn("flex flex-col gap-4", !active && "hidden")}>
+      <StepContext.Provider value={registry}>{children}</StepContext.Provider>
+    </div>
+  );
+}
+
+// ─── Stepper navigation (style only) ─────────────────────────────────────────
+
+/**
+ * Vertical step rail (matches `Tabs.svg`): the numbered state badges stacked top
+ * to bottom, joined by a short vertical connector between consecutive steps.
+ */
+function StepperNav() {
+  const { titles, currentStep, goToStep, stepFields } = useStepper();
+  const { errors } = useFormState();
+
+  const stepHasError = (index: number) =>
+    [...(stepFields[index] ?? [])].some((name) => name in errors);
+
+  return (
+    <FormStepper activeStep={currentStep} className="shrink-0 flex-col items-start gap-[4px]">
+      {titles.map((title, index) => {
+        // The step buttons ARE the navigation: click to move. Backward is free;
+        // clicking forward validates the steps in between (goToStep) and stops at
+        // the first one with errors. Errored steps show a red indicator.
+        const type = stepHasError(index) ? "negative" : index < currentStep ? "success" : "default";
+        return (
+          <React.Fragment key={title}>
+            <FormStep index={index} type={type} onClick={() => void goToStep(index)}>
+              <FormStepIndicator />
+              <FormStepLabel>{title}</FormStepLabel>
+            </FormStep>
+            {/* Connector between steps — a 3×16 rounded bar centred under the badge. */}
+            {index < titles.length - 1 && (
+              <div
+                aria-hidden
+                className="ms-[12.5px] mt-[2px] h-[16px] w-[3px] rounded-full bg-[#A0A0A0]"
+              />
+            )}
+          </React.Fragment>
+        );
+      })}
+    </FormStepper>
+  );
+}
+
+// ─── Back / Next / default footer ────────────────────────────────────────────
+
+export function Back({ children }: { children?: React.ReactNode }) {
+  const { goToPrevious, isFirstStep } = useStepper();
+  return (
+    <Button type="button" variant="BorderStyle" disabled={isFirstStep} onClick={goToPrevious}>
+      {children ?? "Back"}
+    </Button>
+  );
+}
+
+export function Next({ children }: { children?: React.ReactNode }) {
+  const { goToNext, isLastStep } = useStepper();
+  if (isLastStep) return null;
+  return (
+    <Button type="button" variant="PrimeStyle" onClick={() => void goToNext()}>
+      {children ?? "Next"}
+    </Button>
+  );
+}
+
+// ─── Stepper root (marker) + state hook ──────────────────────────────────────
+
+export interface StepperProps {
+  children: React.ReactNode;
+}
+
+/**
+ * `FormBuilder.Stepper` — declares a wizard. It renders **nothing itself**: the
+ * FormBuilder root detects it, lifts its state (so the nav can live in its own
+ * grid column *outside* the `<form>`), and renders `[nav | active step's fields]`.
+ * Children are `FormBuilder.Step`s (plus an optional custom footer).
+ *
+ * Every step's fields stay registered with react-hook-form at all times — the
+ * stepper only controls which step is *visible*. **Navigation is the step buttons
+ * themselves**: click a step to move there. Backward is free; clicking forward
+ * validates every step in between and stops at the first with errors (which shows a
+ * red indicator). Only the last step shows the Submit button.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- children are read by the FormBuilder root
+export function Stepper(_props: StepperProps) {
+  return null;
+}
+(Stepper as unknown as { __isFormStepper: boolean }).__isFormStepper = true;
+
+export function isStepperElement(node: React.ReactNode): node is React.ReactElement<StepperProps> {
+  return (
+    React.isValidElement(node) &&
+    (node.type as { __isFormStepper?: boolean })?.__isFormStepper === true
+  );
+}
+
+type TriggerFn = (names?: FieldPath<FieldValues>[]) => Promise<boolean>;
+
+/**
+ * Stepper state — lifted to the FormBuilder root so the nav (rail) and the step
+ * fields can render in separate grid columns while sharing one state. `trigger` is
+ * the form's `trigger` (passed in — no `useFormContext` needed). Inert when
+ * `steps` is empty (a form without a stepper still calls this, for hooks order).
+ */
+export function useStepperState(
+  steps: React.ReactElement<StepProps>[],
+  trigger: TriggerFn,
+): StepperContextValue {
+  const [currentStep, setCurrentStep] = React.useState(0);
+  const stepFieldsRef = React.useRef<Record<number, Set<string>>>({});
+  const titles = steps.map((s) => s.props.title);
+  const lastIndex = steps.length - 1;
+
+  const validateStep = async (step: number) => {
+    const names = [...(stepFieldsRef.current[step] ?? [])] as FieldPath<FieldValues>[];
+    return names.length === 0 ? true : trigger(names);
+  };
+
+  // Navigation runs through the step buttons. Backward is free; going forward
+  // validates every step between the current one and the target, and stops at
+  // the first step that has errors (so you can't skip past an invalid step).
+  const goToStep = async (index: number) => {
+    const target = Math.max(0, Math.min(index, Math.max(0, lastIndex)));
+    if (target <= currentStep) {
+      setCurrentStep(target);
+      return;
+    }
+    for (let s = currentStep; s < target; s++) {
+      if (!(await validateStep(s))) {
+        setCurrentStep(s);
+        return;
+      }
+    }
+    setCurrentStep(target);
+  };
+
+  const goToNext = async () => {
+    if (await validateStep(currentStep)) setCurrentStep((s) => Math.min(s + 1, lastIndex));
+  };
+
+  return {
+    currentStep,
+    totalSteps: steps.length,
+    titles,
+    isFirstStep: currentStep === 0,
+    isLastStep: currentStep === lastIndex,
+    goToNext,
+    goToPrevious: () => setCurrentStep((s) => Math.max(s - 1, 0)),
+    goToStep,
+    stepFields: stepFieldsRef.current,
+  };
+}
+
+export { StepperNav, StepSlot };