@geomak/ui 5.5.2 → 5.6.0

package/dist/index.cjs

@@ -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-1 cursor-pointer select-none min-h-[36px] px-3 py-1.5 ${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,31 +2504,24 @@ function Dropdown({
                   }
                 },
                 children: [
-                  /* @__PURE__ */ jsxRuntime.jsx(
-                    "div",
+                  !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,
                     {
-                      className: `${!style?.width ? "min-w-[200px]" : ""} 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,
-                        {
-                          disabled,
-                          removeLabel: `Remove ${labelFor(val)}`,
-                          onRemove: () => removeSelected(val),
-                          children: labelFor(val)
-                        },
-                        String(val)
-                      )) : /* @__PURE__ */ jsxRuntime.jsx(
-                        Tag,
-                        {
-                          disabled,
-                          removeLabel: `Remove ${labelFor(value)}`,
-                          onRemove: () => removeSelected(value),
-                          children: labelFor(value)
-                        }
-                      )
+                      values: value,
+                      disabled,
+                      labelFor,
+                      onRemove: removeSelected
                     }
-                  ),
-                  /* @__PURE__ */ jsxRuntime.jsx("div", { className: `flex-shrink-0 ml-2 text-foreground-muted transition-transform duration-200 ${open ? "rotate-180" : "rotate-0"}`, "aria-hidden": "true", children: /* @__PURE__ */ jsxRuntime.jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, className: "h-4 w-4", children: /* @__PURE__ */ jsxRuntime.jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M19 9l-7 7-7-7" }) }) })
+                  ) : /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex-1 min-w-0 flex items-center overflow-hidden", children: /* @__PURE__ */ jsxRuntime.jsx(
+                    Tag,
+                    {
+                      disabled,
+                      removeLabel: `Remove ${labelFor(value)}`,
+                      onRemove: () => removeSelected(value),
+                      children: labelFor(value)
+                    }
+                  ) }),
+                  /* @__PURE__ */ jsxRuntime.jsx("div", { className: `flex-shrink-0 text-foreground-muted transition-transform duration-200 ${open ? "rotate-180" : "rotate-0"}`, "aria-hidden": "true", children: /* @__PURE__ */ jsxRuntime.jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, className: "h-4 w-4", children: /* @__PURE__ */ jsxRuntime.jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M19 9l-7 7-7-7" }) }) })
                 ]
               }
             ) }),
@@ -3330,6 +3452,7 @@ function TextInput({
   size = "md",
   onBlur,
   errorMessage,
+  helperText,
   required,
   prefix,
   suffix
@@ -3362,9 +3485,9 @@ function TextInput({
       htmlFor,
       errorId,
       errorMessage,
+      helperText,
       layout,
       required,
-      className: style ? void 0 : void 0,
       children: hasAdornment ? /* @__PURE__ */ jsxRuntime.jsxs(
         "div",
         {
@@ -3391,6 +3514,7 @@ function NumberInput({
   layout = "vertical",
   size = "md",
   errorMessage,
+  helperText,
   required,
   inputStyle,
   labelStyle,
@@ -3439,6 +3563,7 @@ function NumberInput({
       htmlFor,
       errorId,
       errorMessage,
+      helperText,
       layout,
       required,
       labelStyle,
@@ -3524,6 +3649,7 @@ function Password({
   size = "md",
   onBlur,
   errorMessage,
+  helperText,
   required,
   showIcon,
   hideIcon
@@ -3538,6 +3664,7 @@ function Password({
       htmlFor,
       errorId,
       errorMessage,
+      helperText,
       layout,
       required,
       children: /* @__PURE__ */ jsxRuntime.jsxs(
@@ -3592,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,
     {
@@ -3614,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 = {
@@ -3657,15 +3796,18 @@ function RadioGroup({
   onChange,
   name,
   label,
-  orientation = "vertical",
+  layout = "vertical",
+  labelPosition = "right",
   size = "md",
   disabled,
   required,
+  helperText,
   errorMessage
 }) {
   const errorId = React8.useId();
   const groupId = React8.useId();
   const hasError = errorMessage != null;
+  const labelFirst = labelPosition === "left";
   return /* @__PURE__ */ jsxRuntime.jsx(
     Field,
     {
@@ -3674,6 +3816,7 @@ function RadioGroup({
       errorId,
       errorMessage,
       required,
+      helperText,
       children: /* @__PURE__ */ jsxRuntime.jsx(
         RadioGroupPrimitive__namespace.Root,
         {
@@ -3686,44 +3829,52 @@ function RadioGroup({
           required,
           "aria-invalid": hasError || void 0,
           "aria-describedby": hasError ? errorId : void 0,
-          orientation,
-          className: orientation === "horizontal" ? "flex flex-row flex-wrap gap-5" : "flex flex-col gap-3",
+          orientation: layout,
+          className: layout === "horizontal" ? "flex flex-row flex-wrap gap-5" : "flex flex-col gap-3",
           children: options.map((opt) => {
             const itemId = `${groupId}-${opt.value}`;
-            return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-start gap-2.5", children: [
-              /* @__PURE__ */ jsxRuntime.jsx(
-                RadioGroupPrimitive__namespace.Item,
-                {
-                  id: itemId,
-                  value: opt.value,
-                  disabled: opt.disabled,
-                  className: [
-                    DOT_SIZE[size],
-                    "mt-0.5 flex-shrink-0 rounded-full border bg-surface transition-colors duration-150",
-                    "border-border-strong",
-                    "hover:border-accent",
-                    "data-[state=checked]:border-accent",
-                    "focus:outline-none focus-visible:ring-[3px] focus-visible:ring-focus-ring",
-                    "disabled:cursor-not-allowed disabled:opacity-50"
-                  ].join(" "),
-                  children: /* @__PURE__ */ jsxRuntime.jsx(RadioGroupPrimitive__namespace.Indicator, { className: "flex h-full w-full items-center justify-center", children: /* @__PURE__ */ jsxRuntime.jsx("span", { className: "block h-1/2 w-1/2 rounded-full bg-accent" }) })
-                }
-              ),
-              /* @__PURE__ */ jsxRuntime.jsxs(
-                "label",
-                {
-                  htmlFor: itemId,
-                  className: [
-                    "select-none",
-                    opt.disabled ? "cursor-not-allowed opacity-50" : "cursor-pointer"
-                  ].join(" "),
-                  children: [
-                    /* @__PURE__ */ jsxRuntime.jsx("span", { className: `block ${TEXT_SIZE[size]} text-foreground`, children: opt.label }),
-                    opt.description && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "block text-xs text-foreground-secondary mt-0.5", children: opt.description })
-                  ]
-                }
-              )
-            ] }, opt.value);
+            const dot = /* @__PURE__ */ jsxRuntime.jsx(
+              RadioGroupPrimitive__namespace.Item,
+              {
+                id: itemId,
+                value: opt.value,
+                disabled: opt.disabled,
+                className: [
+                  DOT_SIZE[size],
+                  "mt-0.5 flex-shrink-0 rounded-full border bg-surface transition-colors duration-150",
+                  "border-border-strong",
+                  "hover:border-accent",
+                  "data-[state=checked]:border-accent",
+                  // Border-only focus, consistent with the fields.
+                  "focus:outline-none focus-visible:border-accent",
+                  "disabled:cursor-not-allowed disabled:opacity-50"
+                ].join(" "),
+                children: /* @__PURE__ */ jsxRuntime.jsx(RadioGroupPrimitive__namespace.Indicator, { className: "flex h-full w-full items-center justify-center", children: /* @__PURE__ */ jsxRuntime.jsx("span", { className: "block h-1/2 w-1/2 rounded-full bg-accent" }) })
+              }
+            );
+            const labelEl = /* @__PURE__ */ jsxRuntime.jsxs(
+              "label",
+              {
+                htmlFor: itemId,
+                className: [
+                  "select-none",
+                  opt.disabled ? "cursor-not-allowed opacity-50" : "cursor-pointer",
+                  labelFirst ? "text-right" : ""
+                ].filter(Boolean).join(" "),
+                children: [
+                  /* @__PURE__ */ jsxRuntime.jsx("span", { className: `block ${TEXT_SIZE[size]} text-foreground`, children: opt.label }),
+                  opt.description && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "block text-xs text-foreground-secondary mt-0.5", children: opt.description })
+                ]
+              }
+            );
+            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: [
+              dot,
+              labelEl
+            ] }) }, opt.value);
           })
         }
       )
@@ -3731,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,
@@ -3771,6 +3967,7 @@ function AutoComplete({
   size = "md",
   icon,
   errorMessage,
+  helperText,
   required,
   htmlFor
 }) {
@@ -3829,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: [
@@ -3928,6 +4126,8 @@ function TreeSelect({
   onChange,
   disabled,
   layout = "horizontal",
+  helperText,
+  required,
   errorMessage,
   style,
   htmlFor,
@@ -4013,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: [
@@ -4180,6 +4382,7 @@ function FileInput({
   hint,
   maxSize,
   errorMessage,
+  helperText,
   disabled,
   required,
   icon
@@ -4226,6 +4429,7 @@ function FileInput({
       htmlFor,
       errorId,
       errorMessage: effectiveError,
+      helperText,
       required,
       children: [
         /* @__PURE__ */ jsxRuntime.jsxs(
@@ -4364,6 +4568,8 @@ function DatePicker({
   htmlFor,
   name: _name,
   layout = "horizontal",
+  helperText,
+  required,
   disabled,
   errorMessage,
   min,
@@ -4454,13 +4660,15 @@ 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" : "flex-row items-center gap-2"}`, children: [
-      label && /* @__PURE__ */ jsxRuntime.jsx(
-        "label",
+    /* @__PURE__ */ jsxRuntime.jsxs("div", { className: `flex ${layout === "vertical" ? "flex-col gap-1.5" : "flex-row items-start gap-3"}`, children: [
+      /* @__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: [
@@ -4679,6 +4887,7 @@ function TextArea({
   showCount = false,
   resize,
   errorMessage,
+  helperText,
   required,
   style,
   inputStyle
@@ -4704,6 +4913,7 @@ function TextArea({
       htmlFor,
       errorId,
       errorMessage,
+      helperText,
       layout,
       required,
       children: [
@@ -4744,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
+            ))
+          }
+        )
+      ]
     }
   );
 }
@@ -4811,6 +5054,8 @@ function Slider({
   size = "md",
   disabled,
   errorMessage,
+  helperText,
+  required,
   name,
   htmlFor
 }) {
@@ -4830,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(
@@ -4902,6 +5153,7 @@ function TagsInput({
   size = "md",
   disabled,
   errorMessage,
+  helperText,
   required,
   maxTags,
   dedupe = true,
@@ -4969,6 +5221,7 @@ function TagsInput({
       htmlFor,
       errorId,
       errorMessage: errorText,
+      helperText,
       layout,
       required,
       children: /* @__PURE__ */ jsxRuntime.jsxs(
@@ -5036,6 +5289,8 @@ function OtpInput({
   disabled,
   errorMessage,
   required,
+  layout = "vertical",
+  helperText,
   groupAfter
 }) {
   const errorId = React8.useId();
@@ -5089,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",
       {
@@ -5114,10 +5369,11 @@ function OtpInput({
         className: [
           BOX_SIZE[size],
           "text-center font-medium rounded-lg border bg-surface text-foreground",
-          "transition-[border-color,box-shadow] duration-150",
+          "transition-[border-color] duration-150",
           hasError ? "border-status-error" : "border-border",
           "hover:border-border-strong",
-          "focus:outline-none focus:border-accent focus:ring-[3px] focus:ring-focus-ring",
+          // Border-only focus, consistent with every field (no clip-prone ring).
+          "focus:outline-none focus:border-accent",
           "disabled:bg-surface-raised disabled:text-foreground-muted disabled:cursor-not-allowed"
         ].join(" ")
       }
@@ -5140,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);
@@ -5170,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",
@@ -5262,6 +5521,7 @@ function TimePicker({
   minuteStep = 1,
   disabled,
   errorMessage,
+  helperText,
   required,
   style
 }) {
@@ -5294,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",
@@ -5386,6 +5646,7 @@ function DateRangePicker({
   format = defaultFmt,
   disabled,
   errorMessage,
+  helperText,
   required,
   style
 }) {
@@ -5458,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) {
@@ -5566,6 +5827,7 @@ function ColorPicker({
   allowCustom = true,
   disabled,
   errorMessage,
+  helperText,
   required,
   placeholder = "Pick a colour\u2026"
 }) {
@@ -5583,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",