torch-glare 2.4.1 → 2.4.3

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

@@ -0,0 +1,101 @@
+"use client";
+
+import { ReactNode } from "react";
+
+import { cn } from "../../utils/cn";
+import { HeaderBar } from "../HeaderBar";
+
+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 = "new", children }: HeaderProps) {
+  return (
+    <FormHeaderBar title={title} label={label} variant={variant}>
+      {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,33 @@
+export { FormBuilder } from "./form-builder";
+export type { SectionProps } from "./form-builder";
+export { FormHeaderBar } from "./header";
+export type { HeaderProps, HeaderVariant, FormHeaderBarProps } from "./header";
+export { RichTextField } from "../TextEditor/RichTextField";
+export type { StepProps } from "./stepper";
+export type { 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,290 @@
+"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,
+  StepperContext,
+  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, completedSteps } = 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. A live error shows red; a step that has passed
+        // validation stays checked (success) even after navigating back to it.
+        const type = stepHasError(index)
+          ? "negative"
+          : completedSteps.has(index)
+            ? "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 chevron nav (the Figma header action bar) ───────────────────
+
+/**
+ * Shared chevron nav button, matching the Figma header action bar (Body-HeaderBar-1.0) — the
+ * Glare `Button` icon variant, the same control Select/SearchableSelect use for their chevrons.
+ */
+function StepNavButton({
+  dir,
+  onClick,
+  disabled,
+}: {
+  dir: "left" | "right";
+  onClick: () => void;
+  disabled: boolean;
+}) {
+  return (
+    <Button
+      type="button"
+      buttonType="icon"
+      size="M"
+      onClick={onClick}
+      disabled={disabled}
+      aria-label={dir === "left" ? "Previous step" : "Next step"}
+    >
+      <i
+        className={cn(
+          "text-[18px]",
+          dir === "left" ? "ri-arrow-left-s-line" : "ri-arrow-right-s-line",
+        )}
+      />
+    </Button>
+  );
+}
+
+/** `FormBuilder.Back` — chevron to the previous step; disabled on the first. */
+export function Back() {
+  const { goToPrevious, isFirstStep } = useStepper();
+  return <StepNavButton dir="left" onClick={goToPrevious} disabled={isFirstStep} />;
+}
+
+/** `FormBuilder.Next` — chevron to the next step (validates first); disabled on the last. */
+export function Next() {
+  const { goToNext, isLastStep } = useStepper();
+  return <StepNavButton dir="right" onClick={() => void goToNext()} disabled={isLastStep} />;
+}
+
+// ─── Stepper action bar (Back/Next + divider, then the Submit) ────────────────
+
+/**
+ * `FormRenderer` wraps its `actions` in this. When the form is a stepper it prepends the
+ * chevron `Back`/`Next` controls + a divider before the (user-provided) Submit — the Figma
+ * `Body-HeaderBar-1.0` layout. Outside a stepper there's no `StepperContext`, so it renders
+ * the actions untouched.
+ */
+export function StepperActions({ children }: { children?: React.ReactNode }) {
+  const stepper = React.useContext(StepperContext);
+  if (!stepper) return <>{children}</>;
+  return (
+    <div className="flex items-center gap-2">
+      <Back />
+      <Next />
+      {/* Divider — white-alpha hairline between the nav and the Submit. */}
+      <span aria-hidden className="mx-1 h-5 w-px rounded-[2px] bg-white-alpha-20" />
+      {children}
+    </div>
+  );
+}
+
+// ─── 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);
+  // Steps that have passed their last validation — kept so their checkmark persists when the
+  // user navigates back to an earlier step.
+  const [completedSteps, setCompletedSteps] = React.useState<Set<number>>(new Set());
+  const stepFieldsRef = React.useRef<Record<number, Set<string>>>({});
+  const titles = steps.map((s) => s.props.title);
+  const lastIndex = steps.length - 1;
+
+  const markStep = (step: number, passed: boolean) =>
+    setCompletedSteps((prev) => {
+      if (passed === prev.has(step)) return prev; // no change
+      const next = new Set(prev);
+      if (passed) next.add(step);
+      else next.delete(step);
+      return next;
+    });
+
+  const validateStep = async (step: number) => {
+    const names = [...(stepFieldsRef.current[step] ?? [])] as FieldPath<FieldValues>[];
+    const passed = names.length === 0 ? true : await trigger(names);
+    markStep(step, passed);
+    return passed;
+  };
+
+  // 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,
+    completedSteps,
+  };
+}
+
+export { StepperNav, StepSlot };

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

@@ -0,0 +1,38 @@
+"use client";
+
+import { ReactNode } from "react";
+
+import { Button } from "../Button";
+import { useFormId, useLoading } from "./context";
+
+export interface SubmitButtonProps {
+  children?: ReactNode;
+  className?: string;
+  loadingText?: ReactNode;
+  /**
+   * The form to submit, by `id`. Defaults to the enclosing FormBuilder's own form id (via
+   * context), so a bare `<FormBuilder.Submit>` works even in a header / action bar rendered
+   * **outside** the `<form>` element. Set it explicitly only to target a different form.
+   */
+  form?: string;
+}
+
+/** `FormBuilder.Submit` — a loading-aware submit button, hidden in view mode. */
+export function SubmitButton({ children, className, loadingText, form }: SubmitButtonProps) {
+  const loading = useLoading();
+  const ctxFormId = useFormId();
+
+  return (
+    <Button
+      type="submit"
+      // Defaults to the enclosing form's id, so a Save in the header (outside the `<form>`)
+      // still submits it via native form-association.
+      form={form ?? ctxFormId}
+      variant="PrimeStyle"
+      is_loading={loading}
+      className={className}
+    >
+      {loading ? (loadingText ?? children ?? "Saving…") : (children ?? "Save")}
+    </Button>
+  );
+}