@k3-universe/react-kit 0.0.13 → 0.0.15

package/src/kit/builder/stack-dialog/provider.tsx

@@ -27,7 +27,8 @@ export function StackDialogContextProvider(props: PropsWithChildren) {
   const handleCloseDialog = useCallback((id?: string) => {
     setActiveDialogs(prev => {
       const clone = [...prev];
-      clone.splice(clone.findIndex(d => d.id === (id || '')));
+      if (!id) clone.splice(clone.length - 1, 1);
+      else clone.splice(clone.findIndex((d) => (d.id === id)));
       return clone;
     });
   }, [setActiveDialogs]);

package/src/kit/builder/stack-dialog/renderer.tsx

@@ -1,5 +1,4 @@
-import { DialogContent } from '@radix-ui/react-dialog';
-import { Dialog } from '../../../shadcn/ui/dialog';
+import { Dialog, DialogContent } from '../../../shadcn/ui/dialog';
 import { StackDialogInstance } from './types';
 
 export function StackDialogRenderer(props: {
@@ -10,19 +9,19 @@ export function StackDialogRenderer(props: {
     props.closeDialog(id)
   }
 
-  return props.dialogs.map((dialog) => (
+  return props.dialogs.map((dialog, i) => (
     (
       <Dialog
-        open
-        onOpenChange={(open) => (!open && handleCloseDialog(dialog.id))}
+        open={!!props.dialogs[i]}
+        onOpenChange={handleCloseDialog(dialog.id)}
         key={dialog.id}
       >
         <DialogContent
           onEscapeKeyDown={e => {
-            if (!dialog.closeOnEscapePressed) e.preventDefault();
+            if (dialog.closeOnEscapePressed === false) e.preventDefault();
           }}
           onInteractOutside={e => {
-            if (!dialog.closeOnInteractOutside) e.preventDefault();
+            if (dialog.closeOnInteractOutside === false) e.preventDefault();
           }}
         >
           {dialog.template}

package/src/kit/components/autocomplete/Autocomplete.tsx

@@ -32,10 +32,10 @@ import type {
 } from "./types";
 import { useDebounce } from "use-debounce";
 
-export type AutocompleteProps = {
+export type AutocompleteProps<T = unknown> = {
 	mode: AutocompleteMode;
-	options?: AutocompleteOption[];
-	fetcher?: AutocompleteFetcher;
+	options?: AutocompleteOption<T>[];
+	fetcher?: AutocompleteFetcher<T>;
 	pageSize?: number;
 	/**
 	 * Value can be a single primitive or an array when `multiple` is true
@@ -46,7 +46,8 @@ export type AutocompleteProps = {
 	 */
 	onChange?: (
 		value: string | number | null | Array<string | number>,
-		option: AutocompleteOption | AutocompleteOption[] | null,
+		option: AutocompleteOption<T> | AutocompleteOption<T>[] | null,
+		raw?: T | T[] | null,
 	) => void;
 	/** Enable selecting multiple values (shows chips) */
 	multiple?: boolean;
@@ -56,7 +57,7 @@ export type AutocompleteProps = {
 	className?: string;
 	emptyText?: string;
 	renderOption?: (
-		option: AutocompleteOption,
+		option: AutocompleteOption<T>,
 		selected: boolean,
 	) => React.ReactNode;
 	searchPlaceholder?: string;
@@ -79,21 +80,21 @@ export type AutocompleteProps = {
 	 * Optional: seed selected labels for edit pages. These options are only used to populate the
 	 * internal label map so labels render correctly when values are prefilled.
 	 */
-	initialSelectedOptions?: AutocompleteOption | AutocompleteOption[] | null;
+	initialSelectedOptions?: AutocompleteOption<T> | AutocompleteOption<T>[] | null;
 	/**
 	 * Optional: load labels/options for a list of values whose labels are unknown.
 	 * Useful for edit pages in server mode when only values are available.
 	 */
-	loadSelected?: (values: Array<string | number>) => Promise<AutocompleteOption[]>;
+	loadSelected?: (values: Array<string | number>) => Promise<AutocompleteOption<T>[]>;
 };
 
 const DEFAULT_PAGE_SIZE = 20;
 
 const EMPTY_OPTIONS: AutocompleteOption[] = [];
 
-export function Autocomplete({
+export function Autocomplete<T = unknown>({
 	mode,
-	options = EMPTY_OPTIONS,
+	options = EMPTY_OPTIONS as AutocompleteOption<T>[],
 	fetcher,
 	pageSize = DEFAULT_PAGE_SIZE,
 	value: controlledValue,
@@ -113,7 +114,7 @@ export function Autocomplete({
 	clearable = true,
 	initialSelectedOptions,
 	loadSelected,
-}: AutocompleteProps) {
+}: AutocompleteProps<T>) {
 	const [open, setOpen] = useState<boolean>(!!defaultOpen);
 	const [search, setSearch] = useState("");
 	const [debouncedSearch] = useDebounce(search, 250);
@@ -135,8 +136,12 @@ export function Autocomplete({
 	// Keep a map of value -> label to ensure we can render chips/labels even if the option
 	// is not present in the current page (especially in server mode or for custom values)
 	const labelMapRef = useRef<Map<string | number, string>>(new Map());
-	const addToLabelMap = useCallback((opt: AutocompleteOption) => {
+	const rawMapRef = useRef<Map<string | number, T>>(new Map());
+	const addToLabelMap = useCallback((opt: AutocompleteOption<T>) => {
 		labelMapRef.current.set(opt.value, opt.label);
+		if (Object.prototype.hasOwnProperty.call(opt, "raw") && (opt as AutocompleteOption<T>).raw !== undefined) {
+			rawMapRef.current.set(opt.value, (opt as AutocompleteOption<T>).raw as T);
+		}
 	}, []);
 	// Tick to force re-render when labels hydrate via async
 	const [labelTick, setLabelTick] = useState(0);
@@ -149,7 +154,7 @@ export function Autocomplete({
 	);
 
 	const handleSelect = useCallback(
-		(next: AutocompleteOption) => {
+		(next: AutocompleteOption<T>) => {
 			addToLabelMap(next);
 			if (isMultiple) {
 				const prevValues = Array.isArray(value) ? value : [];
@@ -159,16 +164,18 @@ export function Autocomplete({
 					: [...prevValues, next.value];
 
 				if (controlledValue === undefined) setValue(newValues);
-				const selectedOptions: AutocompleteOption[] = newValues.map((v) => ({
+				const selectedOptions: AutocompleteOption<T>[] = newValues.map((v) => ({
 					value: v,
 					label: getLabel(v),
+					raw: rawMapRef.current.get(v),
 				}));
-				onChange?.(newValues, selectedOptions);
+				const raws = selectedOptions.map((o) => o.raw as T);
+				onChange?.(newValues, selectedOptions, raws);
 				// Keep open for multi-select
 			} else {
 				const newValue = next.value;
 				if (controlledValue === undefined) setValue(newValue);
-				onChange?.(newValue, next);
+				onChange?.(newValue, next, (next as AutocompleteOption<T>).raw as T | undefined ?? null);
 				setOpen(false);
 			}
 		},
@@ -176,7 +183,7 @@ export function Autocomplete({
 	);
 
 	// Data state (shared for both modes)
-	const [items, setItems] = useState<AutocompleteOption[]>([]);
+	const [items, setItems] = useState<AutocompleteOption<T>[]>([]);
 	const [loading, setLoading] = useState(false);
 	const [hasMore, setHasMore] = useState(false);
 	const [nextCursor, setNextCursor] = useState<
@@ -197,7 +204,7 @@ export function Autocomplete({
 			if (!fetcher) return;
 			setLoading(true);
 			try {
-				const res: AutocompleteFetchResult = await fetcher({
+				const res: AutocompleteFetchResult<T> = await fetcher({
 					search: debouncedSearch,
 					cursor: nextCursor ?? null,
 					page,
@@ -334,24 +341,23 @@ export function Autocomplete({
 		return placeholder;
 	}, [isMultiple, mode, options, selectedOption, value, placeholder, labelTick]);
 
-
 	const selectedValues: Array<string | number> = useMemo(
 		() => (isMultiple && Array.isArray(value) ? value : []),
 		[isMultiple, value],
 	);
 	// biome-ignore lint/correctness/useExhaustiveDependencies: labelTick intentionally triggers recompute when labelMap hydrates
-	const selectedOptionsMulti: AutocompleteOption[] = useMemo(
-		() => selectedValues.map((v) => ({ value: v, label: getLabel(v) })),
+	const selectedOptionsMulti: AutocompleteOption<T>[] = useMemo(
+		() => selectedValues.map((v) => ({ value: v, label: getLabel(v), raw: rawMapRef.current.get(v) })),
 		[getLabel, selectedValues, labelTick],
 	);
 
 	const handleClear = useCallback(() => {
 		if (isMultiple) {
 			if (controlledValue === undefined) setValue([]);
-			onChange?.([], []);
+			onChange?.([], [], []);
 		} else {
 			if (controlledValue === undefined) setValue(null);
-			onChange?.(null, null);
+			onChange?.(null, null, null);
 		}
 	}, [controlledValue, isMultiple, onChange]);
 
@@ -360,7 +366,7 @@ export function Autocomplete({
 		(text: string) => {
 			const t = text.trim();
 			if (!t) return;
-			const created: AutocompleteOption = { value: t, label: t };
+			const created: AutocompleteOption<T> = { value: t, label: t };
 			addToLabelMap(created);
 			if (isMultiple) {
 				const prevValues = Array.isArray(value) ? value : [];
@@ -370,12 +376,14 @@ export function Autocomplete({
 				const newOptions = newValues.map((v) => ({
 					value: v,
 					label: getLabel(v),
+					raw: rawMapRef.current.get(v),
 				}));
-				onChange?.(newValues, newOptions);
+				const raws = newOptions.map((o) => o.raw as T);
+				onChange?.(newValues, newOptions, raws);
 				setSearch("");
 			} else {
 				if (controlledValue === undefined) setValue(created.value);
-				onChange?.(created.value, created);
+				onChange?.(created.value, created, (created.raw as T | undefined) ?? null);
 				setSearch("");
 				setOpen(false);
 			}
@@ -411,7 +419,7 @@ export function Autocomplete({
 						tabIndex={disabled ? -1 : 0}
 						aria-disabled={disabled || undefined}
 						className={cn(
-							"w-full inline-flex items-center justify-between rounded-md border bg-background px-3 py-2 text-sm shadow-sm transition-colors",
+							"w-full inline-flex items-center justify-between rounded-md border border-border bg-background px-3 py-2 text-sm shadow-sm transition-colors",
 							"hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
 							disabled && "opacity-50 pointer-events-none",
 							className,

package/src/kit/components/autocomplete/types.ts

@@ -1,6 +1,8 @@
-export type AutocompleteOption = {
+export type AutocompleteOption<T = unknown> = {
   value: string | number
   label: string
+  /** Optional original object returned by the fetcher/static source */
+  raw?: T
 }
 
 export type AutocompleteFetchParams = {
@@ -10,15 +12,15 @@ export type AutocompleteFetchParams = {
   pageSize: number
 }
 
-export type AutocompleteFetchResult = {
-  items: AutocompleteOption[]
+export type AutocompleteFetchResult<T = unknown> = {
+  items: AutocompleteOption<T>[]
   nextCursor?: string | number | null
   hasMore: boolean
   total?: number
 }
 
-export type AutocompleteFetcher = (
+export type AutocompleteFetcher<T = unknown> = (
   params: AutocompleteFetchParams,
-) => Promise<AutocompleteFetchResult>
+) => Promise<AutocompleteFetchResult<T>>
 
 export type AutocompleteMode = 'client' | 'server'

package/src/kit/themes/default.css

@@ -19,7 +19,7 @@
   --destructive: oklch(0.6368 0.2078 25.3313);
   --destructive-foreground: oklch(1.0000 0 0);
   --border: oklch(0.9197 0.0040 286.3202);
-  --input: oklch(0.9197 0.0040 286.3202);
+  --input: oklch(1.0000 0 0);
   --ring: oklch(0.5234 0.1347 144.1672);
   --chart-1: oklch(0.5234 0.1347 144.1672);
   --chart-2: oklch(0.6731 0.1624 144.2083);

package/src/shadcn/ui/button.tsx

@@ -14,7 +14,7 @@ const buttonVariants = cva(
         destructive:
           "bg-destructive text-white shadow-xs hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
         outline:
-          "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",
+          "border border-border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-border dark:hover:bg-input/50",
         secondary:
           "bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80",
         ghost:

package/src/shadcn/ui/command.tsx

@@ -67,7 +67,7 @@ function CommandInput({
   return (
     <div
       data-slot="command-input-wrapper"
-      className="flex h-9 items-center gap-2 border-b px-3"
+      className="flex h-9 items-center gap-2 border-b border-border px-3"
     >
       <SearchIcon className="size-4 shrink-0 opacity-50" />
       <CommandPrimitive.Input

package/src/shadcn/ui/input.tsx

@@ -8,7 +8,7 @@ function Input({ className, type, ...props }: React.ComponentProps<"input">) {
       type={type}
       data-slot="input"
       className={cn(
-        "file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground dark:bg-input/30 border-input flex h-9 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        "file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground dark:bg-input/30 border-border flex h-9 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
         "focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]",
         "aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
         className

package/src/shadcn/ui/popover.tsx

@@ -30,7 +30,7 @@ function PopoverContent({
         align={align}
         sideOffset={sideOffset}
         className={cn(
-          "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-72 origin-(--radix-popover-content-transform-origin) rounded-md border p-4 shadow-md outline-hidden",
+          "border-border bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-72 origin-(--radix-popover-content-transform-origin) rounded-md border p-4 shadow-md outline-hidden",
           className
         )}
         {...props}

package/src/shadcn/ui/select.tsx

@@ -37,7 +37,7 @@ function SelectTrigger({
       data-slot="select-trigger"
       data-size={size}
       className={cn(
-        "border-input data-[placeholder]:text-muted-foreground [&_svg:not([class*='text-'])]:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 dark:hover:bg-input/50 flex w-fit items-center justify-between gap-2 rounded-md border bg-transparent px-3 py-2 text-sm whitespace-nowrap shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 data-[size=default]:h-9 data-[size=sm]:h-8 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-2 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "border-border data-[placeholder]:text-muted-foreground [&_svg:not([class*='text-'])]:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 dark:hover:bg-input/50 flex w-fit items-center justify-between gap-2 rounded-md border bg-transparent px-3 py-2 text-sm whitespace-nowrap shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 data-[size=default]:h-9 data-[size=sm]:h-8 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-2 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
         className
       )}
       {...props}

package/src/shadcn/ui/textarea.tsx

@@ -7,7 +7,7 @@ function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
     <textarea
       data-slot="textarea"
       className={cn(
-        "border-input placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 flex field-sizing-content min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        "border-border placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 flex field-sizing-content min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
         className
       )}
       {...props}

package/src/stories/kit/builder/Form.MultipleFormBuilder.stories.tsx

@@ -0,0 +1,335 @@
+import { useMemo } from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { useForm } from 'react-hook-form'
+import { FormBuilder } from '../../../index'
+import type { FormBuilderSectionConfig } from '../../../kit/builder/form/types'
+
+interface SplitFormValues {
+  firstName: string
+  lastName: string
+  email: string
+  accountType: 'individual' | 'business'
+  companyName?: string
+  address: {
+    street: string
+    city: string
+    zip: string
+  }
+  marketingOptIn: boolean
+  preferredContactMethod: 'email' | 'phone'
+  phoneNumber?: string
+  newsletterTopics: string[]
+  complianceContactEmail?: string
+  eventsWebhookUrl?: string
+  smsOptIn: boolean
+  smsFrequency?: 'daily' | 'weekly' | 'monthly'
+  timezone: string
+}
+
+const generalInfoSections: FormBuilderSectionConfig<SplitFormValues>[] = [
+  {
+    title: 'Profile',
+    layout: 'grid',
+    grid: { cols: 2, gap: 'gap-4' },
+    fields: [
+      {
+        name: 'firstName',
+        label: 'First name',
+        type: 'text',
+        required: true,
+      },
+      {
+        name: 'lastName',
+        label: 'Last name',
+        type: 'text',
+        required: true,
+      },
+      {
+        name: 'email',
+        label: 'Email',
+        type: 'email',
+        required: true,
+        gridCols: 2,
+      },
+      {
+        name: 'accountType',
+        label: 'Account type',
+        type: 'radio',
+        options: [
+          { label: 'Individual', value: 'individual' },
+          { label: 'Business', value: 'business' },
+        ],
+        defaultValue: 'individual',
+        gridCols: 2,
+        description: 'Switch to Business to reveal additional company details.',
+      },
+      {
+        name: 'companyName',
+        label: 'Company name',
+        type: 'text',
+        placeholder: 'Acme Inc.',
+        dependencies: [
+          {
+            field: 'accountType',
+            condition: (value) => value === 'business',
+            action: 'show',
+          },
+        ],
+        gridCols: 2,
+      },
+    ],
+  },
+  {
+    title: 'Address',
+    layout: 'grid',
+    grid: { cols: 3, gap: 'gap-4' },
+    fields: [
+      {
+        name: 'address.street',
+        label: 'Street',
+        type: 'text',
+        required: true,
+        gridCols: 3,
+      },
+      {
+        name: 'address.city',
+        label: 'City',
+        type: 'text',
+        required: true,
+        gridCols: 2,
+      },
+      {
+        name: 'address.zip',
+        label: 'ZIP code',
+        type: 'text',
+        required: true,
+      },
+    ],
+  },
+]
+
+const preferencesSections: FormBuilderSectionConfig<SplitFormValues>[] = [
+  {
+    title: 'Preferences',
+    layout: 'grid',
+    grid: { cols: 2, gap: 'gap-4' },
+    fields: [
+      {
+        name: 'marketingOptIn',
+        label: 'Marketing emails',
+        type: 'switch',
+        defaultValue: true,
+        description: 'Receive occasional product updates and tips.',
+      },
+      {
+        name: 'newsletterTopics',
+        label: 'Topics of interest',
+        type: 'select',
+        options: [
+          { label: 'Product releases', value: 'product' },
+          { label: 'Best practices', value: 'best-practices' },
+          { label: 'Events', value: 'events' },
+          { label: 'Integrations', value: 'integrations' },
+        ],
+        multiple: true,
+        placeholder: 'Choose one or more topics',
+        dependencies: [
+          {
+            field: 'marketingOptIn',
+            condition: (value) => Boolean(value),
+            action: 'show',
+          },
+          {
+            field: 'marketingOptIn',
+            condition: (value) => !value,
+            action: 'setValue',
+            value: [],
+          },
+        ],
+      },
+      {
+        name: 'eventsWebhookUrl',
+        label: 'Events webhook URL',
+        type: 'text',
+        placeholder: 'https://example.com/webhooks/events',
+        description: 'Provide a webhook to receive notifications about upcoming events.',
+        dependencies: [
+          {
+            field: 'newsletterTopics',
+            condition: (value) => Array.isArray(value) && value.includes('events'),
+            action: 'show',
+          },
+        ],
+      },
+      {
+        name: 'preferredContactMethod',
+        label: 'Preferred contact method',
+        type: 'radio',
+        options: [
+          { label: 'Email', value: 'email' },
+          { label: 'Phone', value: 'phone' },
+        ],
+        defaultValue: 'email',
+      },
+      {
+        name: 'phoneNumber',
+        label: 'Phone number',
+        type: 'text',
+        placeholder: '(555) 123-4567',
+        dependencies: [
+          {
+            field: 'preferredContactMethod',
+            condition: (value) => value === 'phone',
+            action: 'show',
+          },
+        ],
+      },
+      {
+        name: 'smsOptIn',
+        label: 'SMS updates',
+        type: 'switch',
+        defaultValue: false,
+        description: 'Get real-time notifications via SMS.',
+        dependencies: [
+          {
+            field: 'preferredContactMethod',
+            condition: (value) => value === 'phone',
+            action: 'show',
+          },
+        ],
+      },
+      {
+        name: 'smsFrequency',
+        label: 'SMS frequency',
+        type: 'select',
+        options: [
+          { label: 'Daily recap', value: 'daily' },
+          { label: 'Weekly summary', value: 'weekly' },
+          { label: 'Monthly digest', value: 'monthly' },
+        ],
+        placeholder: 'Choose how often we should text you',
+        dependencies: [
+          {
+            field: 'smsOptIn',
+            condition: (value) => Boolean(value),
+            action: 'show',
+          },
+        ],
+      },
+      {
+        name: 'complianceContactEmail',
+        label: 'Compliance contact email',
+        type: 'email',
+        placeholder: 'compliance@company.com',
+        description: 'Required for business accounts to receive compliance updates.',
+        dependencies: [
+          {
+            field: 'accountType',
+            condition: (value) => value === 'business',
+            action: 'show',
+          },
+        ],
+        gridCols: 2,
+      },
+      {
+        name: 'timezone',
+        label: 'Timezone',
+        type: 'select',
+        options: [
+          { label: 'UTC−08:00 Pacific', value: 'America/Los_Angeles' },
+          { label: 'UTC−05:00 Eastern', value: 'America/New_York' },
+          { label: 'UTC+00:00 London', value: 'Europe/London' },
+          { label: 'UTC+07:00 Jakarta', value: 'Asia/Jakarta' },
+        ],
+        required: true,
+      },
+    ],
+  },
+]
+
+const SplitFormExample = () => {
+  const form = useForm<SplitFormValues>({
+    defaultValues: {
+      firstName: 'Jane',
+      lastName: 'Doe',
+      email: 'jane.doe@example.com',
+      accountType: 'individual',
+      companyName: '',
+      address: {
+        street: '123 Storybook Way',
+        city: 'Componentville',
+        zip: '90210',
+      },
+      marketingOptIn: true,
+      newsletterTopics: ['product'],
+      eventsWebhookUrl: '',
+      preferredContactMethod: 'email',
+      phoneNumber: '',
+      smsOptIn: false,
+      smsFrequency: undefined,
+      complianceContactEmail: '',
+      timezone: 'Asia/Jakarta',
+    },
+    mode: 'onSubmit',
+  })
+
+  const logSubmit = useMemo(
+    () =>
+      form.handleSubmit((values) => {
+        console.log('Story submit', values)
+      }),
+    [form],
+  )
+
+  return (
+    <div className="space-y-6">
+      <FormBuilder
+        form={form}
+        sections={generalInfoSections}
+        onSubmit={async () => {
+          /* handled by explicit button */
+        }}
+        showActions={false}
+      />
+
+      <FormBuilder
+        form={form}
+        sections={preferencesSections}
+        onSubmit={async () => {
+          /* handled by explicit button */
+        }}
+        customActions={(
+          <button
+            type="button"
+            className="px-4 py-2 text-sm font-medium text-white bg-primary rounded-md"
+            onClick={logSubmit}
+          >
+            Save all sections
+          </button>
+        )}
+      />
+    </div>
+  )
+}
+
+const meta: Meta<typeof SplitFormExample> = {
+  title: 'Kit/Builder/Form',
+  component: SplitFormExample,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Demonstrates sharing a single `react-hook-form` instance across multiple `FormBuilder` blocks using the new `form` prop.',
+      },
+    },
+  },
+}
+
+export default meta
+
+type Story = StoryObj<typeof SplitFormExample>
+
+export const SharedFormInstance: Story = {
+  name: 'Shared form instance across sections',
+  render: () => <SplitFormExample />,
+}