@geomak/ui 5.5.3 → 5.7.0

package/dist/index.cjs

@@ -75,7 +75,7 @@ var FleetIcon = ({ color = "#fff", size = 30 }) => /* @__PURE__ */ jsxRuntime.js
   /* @__PURE__ */ jsxRuntime.jsx("defs", { children: /* @__PURE__ */ jsxRuntime.jsx("clipPath", { id: "clip0_327_836", children: /* @__PURE__ */ jsxRuntime.jsx("rect", { width: "30", height: "30", fill: color }) }) })
 ] });
 var Performance = ({ color = "#fff", size = 30 }) => /* @__PURE__ */ jsxRuntime.jsx("svg", { width: size, height: size, viewBox: "0 0 30 30", fill: "none", xmlns: "http://www.w3.org/2000/svg", children: /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M5.64 25.515H24.36C26.0709 23.3842 27.0024 20.7327 27 18C27 11.385 21.63 6 15 6C8.37 6 3 11.385 3 18C3 20.85 3.99 23.445 5.64 25.515ZM13.5 9C13.5 8.175 14.175 7.5 15 7.5C15.825 7.5 16.5 8.175 16.5 9C16.5 9.84 15.825 10.5 15 10.5C14.175 10.5 13.5 9.84 13.5 9ZM6 12C6 11.175 6.675 10.5 7.5 10.5C8.325 10.5 9 11.175 9 12C9 12.84 8.325 13.5 7.5 13.5C6.675 13.5 6 12.84 6 12ZM12.78 17.1C14.04 15.855 22.545 11.85 22.545 11.85C22.545 11.85 18.555 20.37 17.31 21.615C16.05 22.875 14.04 22.875 12.78 21.615C12.1819 21.016 11.8459 20.204 11.8459 19.3575C11.8459 18.511 12.1819 17.699 12.78 17.1ZM4.5 19.5C4.5 18.675 5.175 18 6 18C6.825 18 7.5 18.675 7.5 19.5C7.5 20.34 6.825 21 6 21C5.175 21 4.5 20.34 4.5 19.5ZM13.5 19.5C13.5 18.675 14.175 18 15 18C15.825 18 16.5 18.675 16.5 19.5C16.5 20.34 15.825 21 15 21C14.175 21 13.5 20.34 13.5 19.5ZM22.5 19.5C22.5 18.675 23.175 18 24 18C24.825 18 25.5 18.675 25.5 19.5C25.5 20.34 24.825 21 24 21C23.175 21 22.5 20.34 22.5 19.5Z", fill: color }) });
-var Map = ({ color = "#fff", size = 30 }) => /* @__PURE__ */ jsxRuntime.jsxs("svg", { width: size, height: size, viewBox: "0 0 34 30", fill: "none", xmlns: "http://www.w3.org/2000/svg", children: [
+var Map2 = ({ color = "#fff", size = 30 }) => /* @__PURE__ */ jsxRuntime.jsxs("svg", { width: size, height: size, viewBox: "0 0 34 30", fill: "none", xmlns: "http://www.w3.org/2000/svg", children: [
   /* @__PURE__ */ jsxRuntime.jsx("g", { clipPath: "url(#clip0_327_830)", children: /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M16.875 0C12.7975 0 9.49219 3.30527 9.49219 7.38281C9.49219 10.6793 14.3174 16.6875 16.166 18.8684C16.5404 19.3102 17.2102 19.3102 17.584 18.8684C19.4326 16.6875 24.2578 10.6793 24.2578 7.38281C24.2578 3.30527 20.9525 0 16.875 0ZM16.875 9.84375C15.5156 9.84375 14.4141 8.74219 14.4141 7.38281C14.4141 6.02344 15.5156 4.92188 16.875 4.92188C18.2344 4.92188 19.3359 6.02344 19.3359 7.38281C19.3359 8.74219 18.2344 9.84375 16.875 9.84375ZM1.17891 12.6533C0.830964 12.7925 0.532694 13.0327 0.322564 13.343C0.112435 13.6533 8.33325e-05 14.0194 0 14.3941L0 29.0613C0 29.7246 0.669727 30.1781 1.28555 29.932L9.375 26.25V12.593C8.85703 11.6566 8.4334 10.7449 8.12988 9.87305L1.17891 12.6533ZM16.875 21.0744C16.0506 21.0744 15.2707 20.7123 14.7357 20.0807C13.5838 18.7213 12.3586 17.1732 11.25 15.5854V26.2494L22.5 29.9994V15.5859C21.3914 17.1732 20.1668 18.7219 19.0143 20.0812C18.4793 20.7123 17.6994 21.0744 16.875 21.0744ZM32.4645 9.44297L24.375 13.125V30L32.5711 26.7217C32.9191 26.5826 33.2174 26.3424 33.4275 26.0321C33.6377 25.7218 33.75 25.3556 33.75 24.9809V10.3137C33.75 9.65039 33.0803 9.19688 32.4645 9.44297Z", fill: color }) }),
   /* @__PURE__ */ jsxRuntime.jsx("defs", { children: /* @__PURE__ */ jsxRuntime.jsx("clipPath", { id: "clip0_327_830", children: /* @__PURE__ */ jsxRuntime.jsx("rect", { width: "33.75", height: "30", fill: color }) }) })
 ] });
@@ -162,7 +162,7 @@ Icon.Minus = Minus;
 Icon.Dashboard = Dashboard;
 Icon.FleetIcon = FleetIcon;
 Icon.Performance = Performance;
-Icon.Map = Map;
+Icon.Map = Map2;
 Icon.CharterParty = CharterParty;
 Icon.Compliance = Compliance;
 Icon.Applications = Applications;
@@ -2179,6 +2179,51 @@ function fieldShell({
     "placeholder:text-foreground-muted"
   ].filter(Boolean).join(" ");
 }
+function FieldHelpIcon({ text }) {
+  return /* @__PURE__ */ jsxRuntime.jsx(Tooltip, { title: text, placement: "top", children: /* @__PURE__ */ jsxRuntime.jsx(
+    "button",
+    {
+      type: "button",
+      "aria-label": "More information",
+      className: "inline-flex items-center justify-center rounded-full text-foreground-muted transition-colors hover:text-foreground focus:outline-none focus-visible:text-accent",
+      children: /* @__PURE__ */ jsxRuntime.jsxs("svg", { viewBox: "0 0 16 16", className: "h-3.5 w-3.5", fill: "none", stroke: "currentColor", strokeWidth: 1.5, "aria-hidden": "true", children: [
+        /* @__PURE__ */ jsxRuntime.jsx("circle", { cx: "8", cy: "8", r: "6.25" }),
+        /* @__PURE__ */ jsxRuntime.jsx("path", { strokeLinecap: "round", d: "M8 7.4v3.4" }),
+        /* @__PURE__ */ jsxRuntime.jsx("circle", { cx: "8", cy: "5.1", r: "0.65", fill: "currentColor", stroke: "none" })
+      ] })
+    }
+  ) });
+}
+function FieldLabel({
+  label,
+  htmlFor,
+  required,
+  helperText,
+  horizontal = false,
+  style,
+  width,
+  className = ""
+}) {
+  if (label == null && helperText == null) return null;
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "div",
+    {
+      style: { width: horizontal ? width : void 0, ...style },
+      className: [
+        "flex items-center gap-1",
+        horizontal ? "mt-2 flex-shrink-0 whitespace-nowrap" : "",
+        className
+      ].filter(Boolean).join(" "),
+      children: [
+        label != null && /* @__PURE__ */ jsxRuntime.jsxs("label", { htmlFor, className: "text-sm font-medium text-foreground select-none", children: [
+          label,
+          required && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "text-status-error ml-0.5", "aria-hidden": "true", children: "*" })
+        ] }),
+        helperText != null && /* @__PURE__ */ jsxRuntime.jsx(FieldHelpIcon, { text: helperText })
+      ]
+    }
+  );
+}
 function Field({
   label,
   htmlFor,
@@ -2186,6 +2231,7 @@ function Field({
   errorMessage,
   layout = "vertical",
   required,
+  helperText,
   labelStyle,
   labelWidth,
   className = "",
@@ -2202,21 +2248,16 @@ function Field({
         className
       ].filter(Boolean).join(" "),
       children: [
-        label && /* @__PURE__ */ jsxRuntime.jsxs(
-          "label",
+        /* @__PURE__ */ jsxRuntime.jsx(
+          FieldLabel,
           {
+            label,
             htmlFor,
-            style: { width: horizontal ? labelWidth : void 0, ...labelStyle },
-            className: [
-              "text-sm font-medium text-foreground select-none",
-              // In horizontal layout the label must not wrap onto
-              // multiple lines (e.g. "Report date", "Select option").
-              horizontal ? "mt-2 flex-shrink-0 whitespace-nowrap" : ""
-            ].filter(Boolean).join(" "),
-            children: [
-              label,
-              required && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "text-status-error ml-0.5", "aria-hidden": "true", children: "*" })
-            ]
+            required,
+            helperText,
+            horizontal,
+            style: labelStyle,
+            width: labelWidth
           }
         ),
         /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex flex-col min-w-0 flex-1", children: [
@@ -2228,8 +2269,8 @@ function Field({
   );
 }
 var SearchIcon = /* @__PURE__ */ jsxRuntime.jsx("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", fill: "currentColor", className: "w-4 h-4", "aria-hidden": "true", children: /* @__PURE__ */ jsxRuntime.jsx("path", { fillRule: "evenodd", d: "M10.5 3.75a6.75 6.75 0 100 13.5 6.75 6.75 0 000-13.5zM2.25 10.5a8.25 8.25 0 1114.59 5.28l4.69 4.69a.75.75 0 11-1.06 1.06l-4.69-4.69A8.25 8.25 0 012.25 10.5z", clipRule: "evenodd" }) });
-var SearchInput = React8__default.default.forwardRef(function SearchInput2({ value, onChange, disabled, label, htmlFor, placeholder, name, inputStyle, style, layout = "vertical", size = "md", icon }, ref) {
-  return /* @__PURE__ */ jsxRuntime.jsx(Field, { label, htmlFor, layout, children: /* @__PURE__ */ jsxRuntime.jsxs(
+var SearchInput = React8__default.default.forwardRef(function SearchInput2({ value, onChange, disabled, label, htmlFor, placeholder, name, inputStyle, style, layout = "vertical", size = "md", icon, helperText }, ref) {
+  return /* @__PURE__ */ jsxRuntime.jsx(Field, { label, htmlFor, layout, helperText, children: /* @__PURE__ */ jsxRuntime.jsxs(
     "div",
     {
       className: `flex items-center ${fieldShell({ size, disabled, focusWithin: true })}`,
@@ -2276,6 +2317,90 @@ function Tag({ children, onRemove, removeLabel, disabled }) {
     )
   ] });
 }
+function MultiTagRow({
+  values,
+  disabled,
+  labelFor,
+  onRemove
+}) {
+  const wrapRef = React8.useRef(null);
+  const measureRef = React8.useRef(null);
+  const [visibleCount, setVisibleCount] = React8.useState(values.length);
+  const key = values.map(String).join("|");
+  React8.useLayoutEffect(() => {
+    const wrap = wrapRef.current;
+    const measure = measureRef.current;
+    if (!wrap || !measure) return;
+    const GAP = 6;
+    const recompute = () => {
+      const avail = wrap.clientWidth;
+      const tagEls = Array.from(measure.querySelectorAll("[data-mt]"));
+      const moreEl = measure.querySelector("[data-mm]");
+      const widths = tagEls.map((e) => e.offsetWidth);
+      const moreW = moreEl ? moreEl.offsetWidth : 0;
+      if (widths.length === 0) {
+        setVisibleCount(0);
+        return;
+      }
+      let used = 0;
+      let count = 0;
+      for (let i = 0; i < widths.length; i++) {
+        const w = widths[i] + (i > 0 ? GAP : 0);
+        if (used + w <= avail) {
+          used += w;
+          count++;
+        } else break;
+      }
+      if (count < widths.length) {
+        while (count > 0) {
+          let t = 0;
+          for (let i = 0; i < count; i++) t += widths[i] + (i > 0 ? GAP : 0);
+          t += GAP + moreW;
+          if (t <= avail) break;
+          count--;
+        }
+      }
+      setVisibleCount(count);
+    };
+    recompute();
+    const ro = new ResizeObserver(recompute);
+    ro.observe(wrap);
+    return () => ro.disconnect();
+  }, [key]);
+  const hidden = values.length - visibleCount;
+  const moreChip = (n) => /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "inline-flex items-center flex-shrink-0 rounded-md border border-border bg-surface-raised text-foreground-secondary text-xs px-2 py-0.5", children: [
+    "+",
+    n,
+    " more"
+  ] });
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { ref: wrapRef, className: "relative flex-1 min-w-0 flex flex-nowrap items-center gap-1.5 overflow-hidden", children: [
+    /* @__PURE__ */ jsxRuntime.jsxs(
+      "div",
+      {
+        ref: measureRef,
+        "aria-hidden": "true",
+        className: "absolute invisible pointer-events-none flex flex-nowrap items-center gap-1.5",
+        style: { left: -9999, top: -9999 },
+        children: [
+          values.map((val) => /* @__PURE__ */ jsxRuntime.jsx("span", { "data-mt": true, children: /* @__PURE__ */ jsxRuntime.jsx(Tag, { removeLabel: "x", onRemove: () => {
+          }, children: labelFor(val) }) }, `m-${val}`)),
+          /* @__PURE__ */ jsxRuntime.jsx("span", { "data-mm": true, children: moreChip(values.length) })
+        ]
+      }
+    ),
+    values.slice(0, visibleCount).map((val) => /* @__PURE__ */ jsxRuntime.jsx(
+      Tag,
+      {
+        disabled,
+        removeLabel: `Remove ${labelFor(val)}`,
+        onRemove: () => onRemove(val),
+        children: labelFor(val)
+      },
+      String(val)
+    )),
+    hidden > 0 && moreChip(hidden)
+  ] });
+}
 function Dropdown({
   isMultiselect = false,
   hasSearch = true,
@@ -2285,6 +2410,8 @@ function Dropdown({
   onChange,
   disabled,
   layout = "horizontal",
+  helperText,
+  required,
   errorMessage,
   style = {},
   htmlFor,
@@ -2345,13 +2472,15 @@ function Dropdown({
       {
         className: `flex ${layout === "vertical" ? "flex-col gap-1.5" : "flex-row items-start gap-3"}`,
         children: [
-          label && /* @__PURE__ */ jsxRuntime.jsx(
-            "label",
+          /* @__PURE__ */ jsxRuntime.jsx(
+            FieldLabel,
             {
-              className: `text-sm font-medium select-none text-foreground ${layout === "horizontal" ? "mt-2 flex-shrink-0 whitespace-nowrap" : ""}`,
+              label,
               htmlFor,
-              style: labelStyle,
-              children: label
+              required,
+              helperText,
+              horizontal: layout === "horizontal",
+              style: labelStyle
             }
           ),
           /* @__PURE__ */ jsxRuntime.jsxs(Popover__namespace.Root, { open: open && !disabled, onOpenChange: (o) => !disabled && setOpen(o), children: [
@@ -2364,8 +2493,8 @@ function Dropdown({
                 "aria-haspopup": "listbox",
                 "aria-invalid": hasError || void 0,
                 "aria-describedby": hasError ? errorId : void 0,
-                style,
-                className: `flex items-center justify-between gap-2 cursor-pointer select-none min-h-[36px] px-3 py-1.5 ${!style?.width ? "min-w-[200px]" : ""} ${fieldShell({ size, hasError, disabled, sized: false })}`,
+                style: { width: 240, ...style },
+                className: `flex items-center justify-between gap-2 cursor-pointer select-none min-h-[36px] px-3 py-1.5 ${fieldShell({ size, hasError, disabled, sized: false })}`,
                 tabIndex: disabled ? -1 : 0,
                 onKeyDown: (e) => {
                   if (disabled) return;
@@ -2375,16 +2504,15 @@ function Dropdown({
                   }
                 },
                 children: [
-                  /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex-1 min-w-0 flex flex-wrap items-center gap-1.5", children: !value || Array.isArray(value) && value.length === 0 ? /* @__PURE__ */ jsxRuntime.jsx("span", { className: "text-foreground-muted text-sm", children: placeholder }) : Array.isArray(value) ? value.map((val) => /* @__PURE__ */ jsxRuntime.jsx(
-                    Tag,
+                  !value || Array.isArray(value) && value.length === 0 ? /* @__PURE__ */ jsxRuntime.jsx("span", { className: "flex-1 min-w-0 truncate text-foreground-muted text-sm", children: placeholder }) : Array.isArray(value) ? /* @__PURE__ */ jsxRuntime.jsx(
+                    MultiTagRow,
                     {
+                      values: value,
                       disabled,
-                      removeLabel: `Remove ${labelFor(val)}`,
-                      onRemove: () => removeSelected(val),
-                      children: labelFor(val)
-                    },
-                    String(val)
-                  )) : /* @__PURE__ */ jsxRuntime.jsx(
+                      labelFor,
+                      onRemove: removeSelected
+                    }
+                  ) : /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex-1 min-w-0 flex items-center overflow-hidden", children: /* @__PURE__ */ jsxRuntime.jsx(
                     Tag,
                     {
                       disabled,
@@ -3324,6 +3452,7 @@ function TextInput({
   size = "md",
   onBlur,
   errorMessage,
+  helperText,
   required,
   prefix,
   suffix
@@ -3356,9 +3485,9 @@ function TextInput({
       htmlFor,
       errorId,
       errorMessage,
+      helperText,
       layout,
       required,
-      className: style ? void 0 : void 0,
       children: hasAdornment ? /* @__PURE__ */ jsxRuntime.jsxs(
         "div",
         {
@@ -3385,6 +3514,7 @@ function NumberInput({
   layout = "vertical",
   size = "md",
   errorMessage,
+  helperText,
   required,
   inputStyle,
   labelStyle,
@@ -3433,6 +3563,7 @@ function NumberInput({
       htmlFor,
       errorId,
       errorMessage,
+      helperText,
       layout,
       required,
       labelStyle,
@@ -3518,6 +3649,7 @@ function Password({
   size = "md",
   onBlur,
   errorMessage,
+  helperText,
   required,
   showIcon,
   hideIcon
@@ -3532,6 +3664,7 @@ function Password({
       htmlFor,
       errorId,
       errorMessage,
+      helperText,
       layout,
       required,
       children: /* @__PURE__ */ jsxRuntime.jsxs(
@@ -3586,10 +3719,14 @@ function Checkbox({
   errorMessage,
   disabled = false,
   layout = "horizontal",
-  labelPosition = "right"
+  labelPosition = "right",
+  helperText,
+  required
 }) {
   const isChecked = checked ?? value ?? false;
   const labelFirst = labelPosition === "left";
+  const errorId = React8.useId();
+  const hasError = errorMessage != null;
   const box = /* @__PURE__ */ jsxRuntime.jsx(
     CheckboxPrimitive__namespace.Root,
     {
@@ -3608,30 +3745,38 @@ function Checkbox({
         "disabled:cursor-not-allowed"
       ].join(" "),
       "aria-label": typeof label === "string" ? label : void 0,
+      "aria-invalid": hasError || void 0,
+      "aria-describedby": hasError ? errorId : void 0,
       children: /* @__PURE__ */ jsxRuntime.jsx(CheckboxPrimitive__namespace.Indicator, { className: "flex items-center justify-center data-[state=checked]:animate-check-pop", children: /* @__PURE__ */ jsxRuntime.jsx("svg", { width: "11", height: "9", viewBox: "0 0 11 9", fill: "none", "aria-hidden": "true", children: /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M1 4.5L4 7.5L10 1", stroke: "white", strokeWidth: "1.8", strokeLinecap: "round", strokeLinejoin: "round" }) }) })
     }
   );
-  const labelEl = label && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "text-sm text-foreground-secondary select-none leading-snug", children: label });
+  const labelEl = label && /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "text-sm text-foreground-secondary select-none leading-snug", children: [
+    label,
+    required && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "text-status-error ml-0.5", "aria-hidden": "true", children: "*" })
+  ] });
   return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex flex-col gap-1", children: [
-    /* @__PURE__ */ jsxRuntime.jsx(
-      "label",
-      {
-        htmlFor,
-        className: [
-          "inline-flex",
-          layout === "vertical" ? "flex-col items-start gap-1.5" : "flex-row items-center gap-2.5",
-          disabled ? "cursor-not-allowed opacity-50" : "cursor-pointer"
-        ].join(" "),
-        children: labelFirst ? /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
-          labelEl,
-          box
-        ] }) : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
-          box,
-          labelEl
-        ] })
-      }
-    ),
-    errorMessage && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "text-xs text-status-error mt-0.5", children: errorMessage })
+    /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center gap-1", children: [
+      /* @__PURE__ */ jsxRuntime.jsx(
+        "label",
+        {
+          htmlFor,
+          className: [
+            "inline-flex",
+            layout === "vertical" ? "flex-col items-start gap-1.5" : "flex-row items-center gap-2.5",
+            disabled ? "cursor-not-allowed opacity-50" : "cursor-pointer"
+          ].join(" "),
+          children: labelFirst ? /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+            labelEl,
+            box
+          ] }) : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+            box,
+            labelEl
+          ] })
+        }
+      ),
+      helperText != null && /* @__PURE__ */ jsxRuntime.jsx(FieldHelpIcon, { text: helperText })
+    ] }),
+    errorMessage && /* @__PURE__ */ jsxRuntime.jsx("span", { id: errorId, className: "text-xs text-status-error mt-0.5", children: errorMessage })
   ] });
 }
 var DOT_SIZE = {
@@ -3656,6 +3801,7 @@ function RadioGroup({
   size = "md",
   disabled,
   required,
+  helperText,
   errorMessage
 }) {
   const errorId = React8.useId();
@@ -3670,6 +3816,7 @@ function RadioGroup({
       errorId,
       errorMessage,
       required,
+      helperText,
       children: /* @__PURE__ */ jsxRuntime.jsx(
         RadioGroupPrimitive__namespace.Root,
         {
@@ -3720,7 +3867,8 @@ function RadioGroup({
                 ]
               }
             );
-            return /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex items-start gap-2.5", children: labelFirst ? /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+            const rowClass = labelFirst && layout === "vertical" ? "grid grid-cols-[1fr_auto] items-start gap-2.5" : "flex items-start gap-2.5";
+            return /* @__PURE__ */ jsxRuntime.jsx("div", { className: rowClass, children: labelFirst ? /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
               labelEl,
               dot
             ] }) : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
@@ -3734,28 +3882,73 @@ function RadioGroup({
   );
 }
 function Switch({
-  checked = false,
+  checked,
+  defaultChecked = false,
   onChange,
   checkedIcon,
-  uncheckedIcon
+  uncheckedIcon,
+  label,
+  layout = "horizontal",
+  helperText,
+  offLabel,
+  onLabel,
+  name,
+  required,
+  disabled,
+  errorMessage
 }) {
   const id = React8.useId();
-  return /* @__PURE__ */ jsxRuntime.jsx("div", { children: /* @__PURE__ */ jsxRuntime.jsx("label", { htmlFor: id, className: "flex items-center cursor-pointer select-none", children: /* @__PURE__ */ jsxRuntime.jsx(
-    SwitchPrimitive__namespace.Root,
+  const errorId = React8.useId();
+  const hasError = errorMessage != null;
+  const isControlled = checked !== void 0;
+  const [internal, setInternal] = React8.useState(defaultChecked);
+  const isOn = isControlled ? checked : internal;
+  const handle = (c) => {
+    if (!isControlled) setInternal(c);
+    onChange?.({ target: { checked: c, name } });
+  };
+  const stateLabel = (active) => [
+    "text-sm select-none transition-colors",
+    active ? "text-foreground font-medium" : "text-foreground-muted",
+    disabled ? "opacity-50" : "cursor-pointer"
+  ].filter(Boolean).join(" ");
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    Field,
     {
-      id,
-      checked,
-      onCheckedChange: (c) => onChange?.({ target: { checked: c } }),
-      className: "relative inline-flex h-6 w-11 flex-shrink-0 items-center rounded-full bg-foreground-secondary data-[state=checked]:bg-accent transition-colors focus:outline-none focus-visible:ring-[3px] focus-visible:ring-focus-ring",
-      children: /* @__PURE__ */ jsxRuntime.jsx(
-        SwitchPrimitive__namespace.Thumb,
-        {
-          className: "pointer-events-none flex h-5 w-5 items-center justify-center rounded-full bg-background text-foreground shadow transition-transform duration-200 data-[state=checked]:translate-x-[22px] data-[state=unchecked]:translate-x-[2px]",
-          children: checkedIcon && uncheckedIcon ? checked ? /* @__PURE__ */ jsxRuntime.jsx("span", { className: "flex items-center justify-center w-3 h-3", children: checkedIcon }) : /* @__PURE__ */ jsxRuntime.jsx("span", { className: "flex items-center justify-center w-3 h-3", children: uncheckedIcon }) : null
-        }
-      )
+      label,
+      htmlFor: id,
+      errorId,
+      errorMessage,
+      layout,
+      required,
+      helperText,
+      children: /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center gap-2.5", children: [
+        offLabel != null && /* @__PURE__ */ jsxRuntime.jsx("label", { htmlFor: id, className: stateLabel(!isOn), children: offLabel }),
+        /* @__PURE__ */ jsxRuntime.jsx(
+          SwitchPrimitive__namespace.Root,
+          {
+            id,
+            name,
+            checked: isOn,
+            onCheckedChange: handle,
+            disabled,
+            required,
+            "aria-invalid": hasError || void 0,
+            "aria-describedby": hasError ? errorId : void 0,
+            className: "relative inline-flex h-6 w-11 flex-shrink-0 items-center rounded-full bg-foreground-secondary data-[state=checked]:bg-accent transition-colors focus:outline-none focus-visible:ring-[3px] focus-visible:ring-focus-ring disabled:opacity-50 disabled:cursor-not-allowed",
+            children: /* @__PURE__ */ jsxRuntime.jsx(
+              SwitchPrimitive__namespace.Thumb,
+              {
+                className: "pointer-events-none flex h-5 w-5 items-center justify-center rounded-full bg-background text-foreground shadow transition-transform duration-200 data-[state=checked]:translate-x-[22px] data-[state=unchecked]:translate-x-[2px]",
+                children: checkedIcon && uncheckedIcon ? /* @__PURE__ */ jsxRuntime.jsx("span", { className: "flex items-center justify-center w-3 h-3", children: isOn ? checkedIcon : uncheckedIcon }) : null
+              }
+            )
+          }
+        ),
+        onLabel != null && /* @__PURE__ */ jsxRuntime.jsx("label", { htmlFor: id, className: stateLabel(isOn), children: onLabel })
+      ] })
     }
-  ) }) });
+  );
 }
 function AutoComplete({
   disabled,
@@ -3774,6 +3967,7 @@ function AutoComplete({
   size = "md",
   icon,
   errorMessage,
+  helperText,
   required,
   htmlFor
 }) {
@@ -3832,6 +4026,7 @@ function AutoComplete({
       htmlFor,
       errorId,
       errorMessage,
+      helperText,
       layout,
       required,
       children: /* @__PURE__ */ jsxRuntime.jsxs(Popover__namespace.Root, { open: open && !disabled, onOpenChange: (o) => !disabled && setOpen(o), children: [
@@ -3931,6 +4126,8 @@ function TreeSelect({
   onChange,
   disabled,
   layout = "horizontal",
+  helperText,
+  required,
   errorMessage,
   style,
   htmlFor,
@@ -4016,12 +4213,14 @@ function TreeSelect({
   };
   return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex flex-col gap-1", children: [
     /* @__PURE__ */ jsxRuntime.jsxs("div", { className: `flex ${layout === "vertical" ? "flex-col gap-1" : "flex-row items-center gap-2"}`, children: [
-      label && /* @__PURE__ */ jsxRuntime.jsx(
-        "label",
+      /* @__PURE__ */ jsxRuntime.jsx(
+        FieldLabel,
         {
-          className: "text-sm font-medium ml-1 max-content select-none text-foreground",
+          label,
           htmlFor,
-          children: label
+          required,
+          helperText,
+          horizontal: layout === "horizontal"
         }
       ),
       /* @__PURE__ */ jsxRuntime.jsxs(Popover__namespace.Root, { open: open && !disabled, onOpenChange: (o) => !disabled && setOpen(o), children: [
@@ -4183,6 +4382,7 @@ function FileInput({
   hint,
   maxSize,
   errorMessage,
+  helperText,
   disabled,
   required,
   icon
@@ -4229,6 +4429,7 @@ function FileInput({
       htmlFor,
       errorId,
       errorMessage: effectiveError,
+      helperText,
       required,
       children: [
         /* @__PURE__ */ jsxRuntime.jsxs(
@@ -4367,6 +4568,8 @@ function DatePicker({
   htmlFor,
   name: _name,
   layout = "horizontal",
+  helperText,
+  required,
   disabled,
   errorMessage,
   min,
@@ -4458,12 +4661,14 @@ function DatePicker({
   const displayValue = value ? format(value) : "";
   return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex flex-col gap-1", children: [
     /* @__PURE__ */ jsxRuntime.jsxs("div", { className: `flex ${layout === "vertical" ? "flex-col gap-1.5" : "flex-row items-start gap-3"}`, children: [
-      label && /* @__PURE__ */ jsxRuntime.jsx(
-        "label",
+      /* @__PURE__ */ jsxRuntime.jsx(
+        FieldLabel,
         {
-          className: `text-sm font-medium select-none text-foreground ${layout === "horizontal" ? "mt-2 flex-shrink-0 whitespace-nowrap" : ""}`,
+          label,
           htmlFor,
-          children: label
+          required,
+          helperText,
+          horizontal: layout === "horizontal"
         }
       ),
       /* @__PURE__ */ jsxRuntime.jsxs(Popover__namespace.Root, { open: open && !disabled, onOpenChange: (o) => !disabled && setOpen(o), children: [
@@ -4682,6 +4887,7 @@ function TextArea({
   showCount = false,
   resize,
   errorMessage,
+  helperText,
   required,
   style,
   inputStyle
@@ -4707,6 +4913,7 @@ function TextArea({
       htmlFor,
       errorId,
       errorMessage,
+      helperText,
       layout,
       required,
       children: [
@@ -4747,51 +4954,84 @@ function SegmentedControl({
   size = "md",
   fullWidth = false,
   disabled,
+  label,
+  layout = "vertical",
+  helperText,
+  name,
+  required,
+  errorMessage,
   "aria-label": ariaLabel
 }) {
   const sz = SIZE[size];
-  return /* @__PURE__ */ jsxRuntime.jsx(
-    ToggleGroup__namespace.Root,
+  const groupId = React8.useId();
+  const errorId = React8.useId();
+  const hasError = errorMessage != null;
+  const isControlled = value !== void 0;
+  const [internal, setInternal] = React8.useState(defaultValue);
+  const current = isControlled ? value : internal;
+  const handle = (v) => {
+    if (!v) return;
+    if (!isControlled) setInternal(v);
+    onChange?.(v);
+  };
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    Field,
     {
-      type: "single",
-      value,
-      defaultValue,
-      onValueChange: (v) => {
-        if (v) onChange?.(v);
-      },
-      disabled,
-      "aria-label": ariaLabel,
-      className: [
-        "inline-flex items-center gap-1 rounded-lg border border-border bg-surface-raised p-1",
-        sz.h,
-        fullWidth ? "flex w-full" : "",
-        disabled ? "opacity-60 cursor-not-allowed" : ""
-      ].filter(Boolean).join(" "),
-      children: options.map((opt) => /* @__PURE__ */ jsxRuntime.jsxs(
-        ToggleGroup__namespace.Item,
-        {
-          value: opt.value,
-          disabled: opt.disabled,
-          className: [
-            "inline-flex items-center justify-center gap-1.5 rounded-md select-none whitespace-nowrap",
-            "transition-colors duration-150 h-full",
-            sz.text,
-            sz.pad,
-            fullWidth ? "flex-1" : "",
-            // Resting: muted text, transparent. Hover lifts the text.
-            "text-foreground-secondary hover:text-foreground",
-            // Active: surface-white pill + accent text + subtle shadow.
-            "data-[state=on]:bg-surface data-[state=on]:text-accent data-[state=on]:shadow-sm",
-            "focus:outline-none focus-visible:ring-[3px] focus-visible:ring-focus-ring",
-            "disabled:opacity-40 disabled:cursor-not-allowed"
-          ].filter(Boolean).join(" "),
-          children: [
-            opt.icon && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "flex-shrink-0", children: opt.icon }),
-            opt.label
-          ]
-        },
-        opt.value
-      ))
+      label,
+      htmlFor: groupId,
+      errorId,
+      errorMessage,
+      layout,
+      required,
+      helperText,
+      children: [
+        name && /* @__PURE__ */ jsxRuntime.jsx("input", { type: "hidden", name, value: current ?? "" }),
+        /* @__PURE__ */ jsxRuntime.jsx(
+          ToggleGroup__namespace.Root,
+          {
+            id: groupId,
+            type: "single",
+            value: current,
+            onValueChange: handle,
+            disabled,
+            "aria-label": ariaLabel ?? (typeof label === "string" ? label : void 0),
+            "aria-invalid": hasError || void 0,
+            "aria-describedby": hasError ? errorId : void 0,
+            className: [
+              "inline-flex items-center gap-1 rounded-lg border bg-surface-raised p-1",
+              hasError ? "border-status-error" : "border-border",
+              sz.h,
+              fullWidth ? "flex w-full" : "w-fit",
+              disabled ? "opacity-60 cursor-not-allowed" : ""
+            ].filter(Boolean).join(" "),
+            children: options.map((opt) => /* @__PURE__ */ jsxRuntime.jsxs(
+              ToggleGroup__namespace.Item,
+              {
+                value: opt.value,
+                disabled: opt.disabled,
+                className: [
+                  "inline-flex items-center justify-center gap-1.5 rounded-md select-none whitespace-nowrap",
+                  "transition-colors duration-150 h-full",
+                  sz.text,
+                  sz.pad,
+                  fullWidth ? "flex-1" : "",
+                  // Resting: muted text, transparent. Hover lifts the text.
+                  "text-foreground-secondary hover:text-foreground",
+                  // Active: surface-white pill + accent text + subtle shadow.
+                  "data-[state=on]:bg-surface data-[state=on]:text-accent data-[state=on]:shadow-sm",
+                  "focus:outline-none focus-visible:ring-[3px] focus-visible:ring-focus-ring",
+                  "disabled:opacity-40 disabled:cursor-not-allowed"
+                ].filter(Boolean).join(" "),
+                children: [
+                  opt.icon && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "flex-shrink-0", children: opt.icon }),
+                  opt.label
+                ]
+              },
+              opt.value
+            ))
+          }
+        )
+      ]
     }
   );
 }
@@ -4814,6 +5054,8 @@ function Slider({
   size = "md",
   disabled,
   errorMessage,
+  helperText,
+  required,
   name,
   htmlFor
 }) {
@@ -4833,7 +5075,13 @@ function Slider({
   const valueText = current.map(formatValue).join(" \u2013 ");
   return /* @__PURE__ */ jsxRuntime.jsxs(Field, { label: void 0, errorId, errorMessage, children: [
     (label || showValue) && /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center justify-between mb-2", children: [
-      label && /* @__PURE__ */ jsxRuntime.jsx("label", { htmlFor, className: "text-sm font-medium text-foreground select-none", children: label }),
+      label && /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "flex items-center gap-1", children: [
+        /* @__PURE__ */ jsxRuntime.jsxs("label", { htmlFor, className: "text-sm font-medium text-foreground select-none", children: [
+          label,
+          required && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "text-status-error ml-0.5", "aria-hidden": "true", children: "*" })
+        ] }),
+        helperText != null && /* @__PURE__ */ jsxRuntime.jsx(FieldHelpIcon, { text: helperText })
+      ] }),
       showValue && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "text-sm text-foreground-secondary tabular-nums", children: valueText })
     ] }),
     /* @__PURE__ */ jsxRuntime.jsxs(
@@ -4905,6 +5153,7 @@ function TagsInput({
   size = "md",
   disabled,
   errorMessage,
+  helperText,
   required,
   maxTags,
   dedupe = true,
@@ -4972,6 +5221,7 @@ function TagsInput({
       htmlFor,
       errorId,
       errorMessage: errorText,
+      helperText,
       layout,
       required,
       children: /* @__PURE__ */ jsxRuntime.jsxs(
@@ -5039,6 +5289,8 @@ function OtpInput({
   disabled,
   errorMessage,
   required,
+  layout = "vertical",
+  helperText,
   groupAfter
 }) {
   const errorId = React8.useId();
@@ -5092,7 +5344,7 @@ function OtpInput({
     emit(valid.join(""));
     focusBox(valid.length);
   };
-  return /* @__PURE__ */ jsxRuntime.jsx(Field, { label, htmlFor, errorId, errorMessage, required, children: /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex items-center gap-2", role: "group", "aria-label": typeof label === "string" ? label : "One-time code", children: chars.map((char, idx) => /* @__PURE__ */ jsxRuntime.jsxs(React8__default.default.Fragment, { children: [
+  return /* @__PURE__ */ jsxRuntime.jsx(Field, { label, htmlFor, errorId, errorMessage, required, layout, helperText, children: /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex items-center gap-2", role: "group", "aria-label": typeof label === "string" ? label : "One-time code", children: chars.map((char, idx) => /* @__PURE__ */ jsxRuntime.jsxs(React8__default.default.Fragment, { children: [
     /* @__PURE__ */ jsxRuntime.jsx(
       "input",
       {
@@ -5144,7 +5396,10 @@ function Rating({
   disabled,
   icon = Star,
   errorMessage,
-  name
+  name,
+  layout = "vertical",
+  helperText,
+  required
 }) {
   const errorId = React8.useId();
   const [internal, setInternal] = React8.useState(defaultValue);
@@ -5174,7 +5429,7 @@ function Rating({
       commit(count);
     }
   };
-  return /* @__PURE__ */ jsxRuntime.jsx(Field, { label, errorId, errorMessage, children: /* @__PURE__ */ jsxRuntime.jsxs(
+  return /* @__PURE__ */ jsxRuntime.jsx(Field, { label, errorId, errorMessage, layout, required, helperText, children: /* @__PURE__ */ jsxRuntime.jsxs(
     "div",
     {
       role: interactive ? "slider" : "img",
@@ -5266,6 +5521,7 @@ function TimePicker({
   minuteStep = 1,
   disabled,
   errorMessage,
+  helperText,
   required,
   style
 }) {
@@ -5298,7 +5554,7 @@ function TimePicker({
     },
     n
   )) });
-  return /* @__PURE__ */ jsxRuntime.jsxs(Field, { label, htmlFor, errorId, errorMessage, layout, required, children: [
+  return /* @__PURE__ */ jsxRuntime.jsxs(Field, { label, htmlFor, errorId, errorMessage, helperText, layout, required, children: [
     /* @__PURE__ */ jsxRuntime.jsxs(Popover__namespace.Root, { open: open && !disabled, onOpenChange: (o) => !disabled && setOpen(o), children: [
       /* @__PURE__ */ jsxRuntime.jsx(Popover__namespace.Trigger, { asChild: true, children: /* @__PURE__ */ jsxRuntime.jsxs(
         "button",
@@ -5390,6 +5646,7 @@ function DateRangePicker({
   format = defaultFmt,
   disabled,
   errorMessage,
+  helperText,
   required,
   style
 }) {
@@ -5462,7 +5719,7 @@ function DateRangePicker({
       ] })
     ] });
   };
-  return /* @__PURE__ */ jsxRuntime.jsx(Field, { label, htmlFor, errorId, errorMessage, layout, required, children: /* @__PURE__ */ jsxRuntime.jsxs(Popover__namespace.Root, { open: open && !disabled, onOpenChange: (o) => {
+  return /* @__PURE__ */ jsxRuntime.jsx(Field, { label, htmlFor, errorId, errorMessage, helperText, layout, required, children: /* @__PURE__ */ jsxRuntime.jsxs(Popover__namespace.Root, { open: open && !disabled, onOpenChange: (o) => {
     if (!disabled) {
       setOpen(o);
       if (!o) {
@@ -5570,6 +5827,7 @@ function ColorPicker({
   allowCustom = true,
   disabled,
   errorMessage,
+  helperText,
   required,
   placeholder = "Pick a colour\u2026"
 }) {
@@ -5587,7 +5845,7 @@ function ColorPicker({
     setDraft(hex);
     if (HEX_RE.test(hex)) onChange?.(hex);
   };
-  return /* @__PURE__ */ jsxRuntime.jsxs(Field, { label, htmlFor, errorId, errorMessage, layout, required, children: [
+  return /* @__PURE__ */ jsxRuntime.jsxs(Field, { label, htmlFor, errorId, errorMessage, helperText, layout, required, children: [
     /* @__PURE__ */ jsxRuntime.jsxs(Popover__namespace.Root, { open: open && !disabled, onOpenChange: (o) => !disabled && setOpen(o), children: [
       /* @__PURE__ */ jsxRuntime.jsx(Popover__namespace.Trigger, { asChild: true, children: /* @__PURE__ */ jsxRuntime.jsxs(
         "button",
@@ -5662,6 +5920,438 @@ function ColorPicker({
   ] });
 }
 
+// src/form/path.ts
+function deepClone(v) {
+  if (v === null || typeof v !== "object") return v;
+  if (v instanceof Date) return new Date(v.getTime());
+  if (Array.isArray(v)) return v.map(deepClone);
+  const out = {};
+  for (const k in v) out[k] = deepClone(v[k]);
+  return out;
+}
+function getPath(obj, path) {
+  if (!path) return obj;
+  const parts = path.split(".");
+  let cur = obj;
+  for (const p of parts) {
+    if (cur == null || typeof cur !== "object") return void 0;
+    cur = cur[p];
+  }
+  return cur;
+}
+function setPath(obj, path, value) {
+  const parts = path.split(".");
+  const root = Array.isArray(obj) ? [...obj] : { ...obj ?? {} };
+  let cur = root;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const p = parts[i];
+    const nextIsIndex = /^\d+$/.test(parts[i + 1]);
+    const child = cur[p];
+    const next = Array.isArray(child) ? [...child] : child && typeof child === "object" ? { ...child } : nextIsIndex ? [] : {};
+    cur[p] = next;
+    cur = next;
+  }
+  cur[parts[parts.length - 1]] = value;
+  return root;
+}
+
+// src/form/validate.ts
+function isEmpty(v) {
+  return v == null || v === "" || v === false || Array.isArray(v) && v.length === 0;
+}
+var boundValue = (b) => typeof b === "number" ? b : b.value;
+var boundMessage = (b, fallback) => typeof b === "number" ? fallback : b.message ?? fallback;
+function isRequired(rules) {
+  if (!rules) return false;
+  const list = Array.isArray(rules) ? rules : [rules];
+  return list.some((r) => !!r.required);
+}
+async function runFieldRules(value, rules, values) {
+  if (!rules) return void 0;
+  const list = Array.isArray(rules) ? rules : [rules];
+  for (const rule of list) {
+    if (rule.required && isEmpty(value)) {
+      return typeof rule.required === "string" ? rule.required : rule.message ?? "This field is required";
+    }
+    if (isEmpty(value)) {
+      if (rule.validate) {
+        const res = await rule.validate(value, values);
+        if (res) return typeof res === "string" ? res : rule.message ?? "Invalid value";
+      }
+      continue;
+    }
+    if (rule.pattern) {
+      const re = rule.pattern instanceof RegExp ? rule.pattern : rule.pattern.value;
+      const msg = rule.pattern instanceof RegExp ? rule.message ?? "Invalid format" : rule.pattern.message ?? rule.message ?? "Invalid format";
+      if (typeof value === "string" && !re.test(value)) return msg;
+    }
+    if (rule.min != null && typeof value === "number") {
+      const m = boundValue(rule.min);
+      if (value < m) return boundMessage(rule.min, rule.message ?? `Must be at least ${m}`);
+    }
+    if (rule.max != null && typeof value === "number") {
+      const m = boundValue(rule.max);
+      if (value > m) return boundMessage(rule.max, rule.message ?? `Must be at most ${m}`);
+    }
+    if (rule.minLength != null) {
+      const len = value?.length;
+      const m = boundValue(rule.minLength);
+      if (typeof len === "number" && len < m)
+        return boundMessage(rule.minLength, rule.message ?? `Must be at least ${m} characters`);
+    }
+    if (rule.maxLength != null) {
+      const len = value?.length;
+      const m = boundValue(rule.maxLength);
+      if (typeof len === "number" && len > m)
+        return boundMessage(rule.maxLength, rule.message ?? `Must be at most ${m} characters`);
+    }
+    if (rule.validate) {
+      const res = await rule.validate(value, values);
+      if (res) return typeof res === "string" ? res : rule.message ?? "Invalid value";
+    }
+  }
+  return void 0;
+}
+var patterns = {
+  email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+  url: /^https?:\/\/[^\s/$.?#].[^\s]*$/i,
+  // Loose international phone: + and 7-15 digits, spaces/dashes allowed.
+  phone: /^\+?[\d\s-]{7,15}$/,
+  // Digits only.
+  digits: /^\d+$/
+};
+
+// src/form/store.ts
+var FormStore = class {
+  listeners = /* @__PURE__ */ new Set();
+  fieldCache = /* @__PURE__ */ new Map();
+  values;
+  errors = {};
+  touched = {};
+  submitted = false;
+  validating = false;
+  initialValues;
+  rules;
+  validateOn;
+  // Field-array key bookkeeping (stable React keys across reorder/removal).
+  keys = {};
+  keySeq = 1;
+  // Root snapshot — a new ref on every change, for form-level subscribers.
+  rootSnap = { v: 0 };
+  constructor(opts = {}) {
+    this.initialValues = deepClone(opts.initialValues ?? {});
+    this.values = deepClone(opts.initialValues ?? {});
+    this.rules = { ...opts.rules ?? {} };
+    this.validateOn = opts.validateOn ?? ["onChange", "onBlur", "onSubmit"];
+  }
+  // ── subscription ────────────────────────────────────────────────────────
+  subscribe = (l) => {
+    this.listeners.add(l);
+    return () => {
+      this.listeners.delete(l);
+    };
+  };
+  emit() {
+    this.rootSnap = { v: this.rootSnap.v + 1 };
+    this.listeners.forEach((l) => l());
+  }
+  getRootSnapshot = () => this.rootSnap;
+  getFieldSnapshot = (name) => {
+    const value = getPath(this.values, name);
+    const error = this.errors[name];
+    const showError = (!!this.touched[name] || this.submitted) && error != null;
+    const prev = this.fieldCache.get(name);
+    if (prev && Object.is(prev.value, value) && prev.error === error && prev.showError === showError) {
+      return prev.snap;
+    }
+    const snap = { value, error, showError };
+    this.fieldCache.set(name, { value, error, showError, snap });
+    return snap;
+  };
+  // ── rule registry (for dynamic / array fields) ──────────────────────────
+  setRule(name, rules) {
+    if (rules == null) delete this.rules[name];
+    else this.rules[name] = rules;
+  }
+  removeRule(name) {
+    delete this.rules[name];
+  }
+  getRule(name) {
+    return this.rules[name];
+  }
+  // ── reads ────────────────────────────────────────────────────────────────
+  getValues = () => this.values;
+  getValue = (name) => getPath(this.values, name);
+  get isValid() {
+    return Object.values(this.errors).every((e) => !e);
+  }
+  // ── writes ────────────────────────────────────────────────────────────────
+  setValue = (name, value, opts = {}) => {
+    this.values = setPath(this.values, name, value);
+    if (opts.touch) this.touched = { ...this.touched, [name]: true };
+    this.emit();
+    const shouldValidate = opts.validate ?? this.validateOn.includes("onChange");
+    if (shouldValidate) void this.validateField(name);
+  };
+  setValues = (patch, opts = {}) => {
+    for (const k of Object.keys(patch)) this.values = setPath(this.values, k, patch[k]);
+    this.emit();
+    if (opts.validate) void this.validateAll();
+  };
+  setError = (name, error) => {
+    if (this.errors[name] === error) return;
+    this.errors = { ...this.errors, [name]: error || void 0 };
+    this.emit();
+  };
+  touch = (name, opts = {}) => {
+    if (!this.touched[name]) {
+      this.touched = { ...this.touched, [name]: true };
+      this.emit();
+    }
+    if (opts.validate ?? this.validateOn.includes("onBlur")) void this.validateField(name);
+  };
+  setSubmitted = (v) => {
+    this.submitted = v;
+    this.emit();
+  };
+  // ── validation ─────────────────────────────────────────────────────────────
+  async validateField(name) {
+    const err = await runFieldRules(getPath(this.values, name), this.rules[name], this.values);
+    this.setError(name, err);
+    return err;
+  }
+  async validateAll() {
+    this.validating = true;
+    this.emit();
+    const names = Object.keys(this.rules);
+    const entries = await Promise.all(
+      names.map(async (n) => [n, await runFieldRules(getPath(this.values, n), this.rules[n], this.values)])
+    );
+    const errors = {};
+    for (const [n, e] of entries) errors[n] = e;
+    this.errors = errors;
+    this.validating = false;
+    this.emit();
+    return errors;
+  }
+  reset = (values) => {
+    this.values = deepClone(values ?? this.initialValues);
+    this.errors = {};
+    this.touched = {};
+    this.submitted = false;
+    this.keys = {};
+    this.fieldCache.clear();
+    this.emit();
+  };
+  // ── field arrays ───────────────────────────────────────────────────────────
+  getKeys(name) {
+    const arr = getPath(this.values, name) ?? [];
+    let keys = this.keys[name];
+    if (!keys || keys.length !== arr.length) {
+      keys = arr.map((_, i) => keys && keys[i] != null ? keys[i] : this.keySeq++);
+      this.keys[name] = keys;
+    }
+    return keys;
+  }
+  arrayAppend = (name, item = {}) => {
+    const arr = [...getPath(this.values, name) ?? []];
+    arr.push(item);
+    this.keys[name] = [...this.getKeys(name), this.keySeq++];
+    this.setValue(name, arr, { validate: false });
+  };
+  arrayRemove = (name, index) => {
+    const arr = [...getPath(this.values, name) ?? []];
+    arr.splice(index, 1);
+    const k = [...this.getKeys(name)];
+    k.splice(index, 1);
+    this.keys[name] = k;
+    this.clearBranch(name);
+    this.setValue(name, arr, { validate: false });
+  };
+  arrayMove = (name, from, to) => {
+    const arr = [...getPath(this.values, name) ?? []];
+    if (from < 0 || to < 0 || from >= arr.length || to >= arr.length) return;
+    const [moved] = arr.splice(from, 1);
+    arr.splice(to, 0, moved);
+    const k = [...this.getKeys(name)];
+    const [mk] = k.splice(from, 1);
+    k.splice(to, 0, mk);
+    this.keys[name] = k;
+    this.clearBranch(name);
+    this.setValue(name, arr, { validate: false });
+  };
+  /** Drop any errors/touched flags under `name.` — used when an array shifts. */
+  clearBranch(name) {
+    const prefix = name + ".";
+    const errors = {};
+    for (const k of Object.keys(this.errors)) if (!k.startsWith(prefix)) errors[k] = this.errors[k];
+    const touched = {};
+    for (const k of Object.keys(this.touched)) if (!k.startsWith(prefix)) touched[k] = this.touched[k];
+    this.errors = errors;
+    this.touched = touched;
+  }
+};
+
+// src/form/bindings.ts
+var getTarget = (arg) => {
+  const t = arg?.target;
+  return t && typeof t === "object" ? t : void 0;
+};
+var ADAPTERS = {
+  value: { prop: "value", toValue: (v) => v, applyEmpty: false, empty: void 0 },
+  native: { prop: "value", toValue: (e) => getTarget(e)?.value, applyEmpty: true, empty: "" },
+  checked: { prop: "checked", toValue: (e) => getTarget(e)?.checked, applyEmpty: true, empty: false },
+  target: { prop: "value", toValue: (e) => getTarget(e)?.value, applyEmpty: false, empty: void 0 }
+};
+function buildBindings(store, name, kind, snap) {
+  const a = ADAPTERS[kind];
+  const raw = snap.value;
+  const value = a.applyEmpty ? raw ?? a.empty : raw;
+  return {
+    name,
+    id: name,
+    htmlFor: name,
+    required: isRequired(store.getRule(name)) || void 0,
+    errorMessage: snap.showError ? snap.error : void 0,
+    [a.prop]: value,
+    onChange: (arg) => store.setValue(name, a.toValue(arg), { touch: true }),
+    onBlur: () => store.touch(name)
+  };
+}
+
+// src/form/useForm.ts
+function useForm(options = {}) {
+  const ref = React8.useRef(null);
+  if (ref.current === null) ref.current = new FormStore(options);
+  const store = ref.current;
+  React8.useSyncExternalStore(store.subscribe, store.getRootSnapshot, store.getRootSnapshot);
+  const make = React8.useCallback(
+    (kind) => (name, rules) => {
+      if (rules !== void 0) store.setRule(name, rules);
+      return buildBindings(store, name, kind, store.getFieldSnapshot(name));
+    },
+    [store]
+  );
+  return {
+    store,
+    values: store.values,
+    errors: store.errors,
+    touched: store.touched,
+    submitted: store.submitted,
+    isSubmitting: store.validating,
+    isValid: store.isValid,
+    getValue: store.getValue,
+    getValues: store.getValues,
+    setValue: (name, value) => store.setValue(name, value),
+    setValues: (patch) => store.setValues(patch),
+    setError: store.setError,
+    validateField: (name) => store.validateField(name),
+    validateAll: () => store.validateAll(),
+    reset: store.reset,
+    field: make("value"),
+    fieldNative: make("native"),
+    fieldChecked: make("checked"),
+    fieldTarget: make("target")
+  };
+}
+var FormContext = React8.createContext(null);
+function useFormStore() {
+  const store = React8.useContext(FormContext);
+  if (!store) {
+    throw new Error("useFormStore must be used within a <Form>. Did you forget to wrap your fields?");
+  }
+  return store;
+}
+function Form({
+  form,
+  onFinish,
+  onFinishFailed,
+  action,
+  children,
+  ...rest
+}) {
+  const ref = React8.useRef(null);
+  const bypass = React8.useRef(false);
+  const handleSubmit = async (e) => {
+    if (bypass.current) {
+      bypass.current = false;
+      return;
+    }
+    e.preventDefault();
+    const store = form.store;
+    store.setSubmitted(true);
+    const errors = await store.validateAll();
+    const hasError = Object.values(errors).some(Boolean);
+    if (hasError) {
+      onFinishFailed?.(errors, store.getValues());
+      focusFirstError(ref.current, errors);
+      return;
+    }
+    if (onFinish) {
+      await onFinish(store.getValues());
+      return;
+    }
+    if (typeof action === "function") {
+      action(new FormData(ref.current));
+      return;
+    }
+    if (typeof action === "string") {
+      bypass.current = true;
+      ref.current.requestSubmit();
+    }
+  };
+  return /* @__PURE__ */ jsxRuntime.jsx(FormContext.Provider, { value: form.store, children: /* @__PURE__ */ jsxRuntime.jsx(
+    "form",
+    {
+      ref,
+      noValidate: true,
+      action: typeof action === "string" ? action : void 0,
+      onSubmit: handleSubmit,
+      ...rest,
+      children
+    }
+  ) });
+}
+function focusFirstError(formEl, errors) {
+  if (!formEl) return;
+  const firstName = Object.keys(errors).find((k) => errors[k]);
+  if (!firstName) return;
+  const el = formEl.querySelector(`[name="${CSS.escape(firstName)}"], #${CSS.escape(firstName)}`);
+  el?.focus();
+}
+function useFormField(name, options = {}) {
+  const store = useFormStore();
+  const { kind = "value", rules } = options;
+  if (rules !== void 0 && store.getRule(name) !== rules) store.setRule(name, rules);
+  React8.useEffect(() => {
+    return () => {
+      if (rules !== void 0) store.removeRule(name);
+    };
+  }, [store, name]);
+  const snap = React8.useSyncExternalStore(
+    store.subscribe,
+    () => store.getFieldSnapshot(name)
+  );
+  return buildBindings(store, name, kind, snap);
+}
+function FormField({ name, kind, rules, children }) {
+  const field = useFormField(name, { kind, rules });
+  return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: children(field) });
+}
+function useFieldArray(name) {
+  const store = useFormStore();
+  React8.useSyncExternalStore(store.subscribe, store.getRootSnapshot, store.getRootSnapshot);
+  const arr = store.getValue(name) ?? [];
+  const keys = store.getKeys(name);
+  return {
+    fields: arr.map((_, i) => ({ key: keys[i], name: `${name}.${i}`, index: i })),
+    append: (item = {}) => store.arrayAppend(name, item),
+    remove: (index) => store.arrayRemove(name, index),
+    move: (from, to) => store.arrayMove(name, from, to),
+    replace: (items) => store.setValue(name, items, { validate: false })
+  };
+}
+
 Object.defineProperty(exports, "COLORS", {
   enumerable: true,
   get: function () { return chunk255PCZIW_cjs.colors_default; }
@@ -5694,8 +6384,14 @@ exports.Drawer = Drawer;
 exports.Dropdown = Dropdown;
 exports.FadingBase = FadingBase;
 exports.Field = Field;
+exports.FieldHelpIcon = FieldHelpIcon;
+exports.FieldLabel = FieldLabel;
 exports.FileInput = FileInput;
 exports.Flex = Flex;
+exports.Form = Form;
+exports.FormContext = FormContext;
+exports.FormField = FormField;
+exports.FormStore = FormStore;
 exports.Grid = Grid2;
 exports.GridCard = GridCard;
 exports.Icon = icons_default;
@@ -5738,6 +6434,13 @@ exports.TreeSelect = TreeSelect;
 exports.Typography = Typography;
 exports.Wizard = Wizard;
 exports.fieldShell = fieldShell;
+exports.isRequired = isRequired;
+exports.patterns = patterns;
+exports.runFieldRules = runFieldRules;
+exports.useFieldArray = useFieldArray;
+exports.useForm = useForm;
+exports.useFormField = useFormField;
+exports.useFormStore = useFormStore;
 exports.useNotification = useNotification;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map