@geomak/ui 5.7.1 → 5.7.2

package/dist/index.d.cts

@@ -1870,8 +1870,15 @@ interface FieldLabelProps {
     required?: boolean;
     /** Reveals an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
-    /** Apply horizontal-layout spacing (top margin, no-wrap, shrink). */
+    /** Apply horizontal-layout spacing (no-wrap, shrink). */
     horizontal?: boolean;
+    /**
+     * Vertical alignment of the label against the control in horizontal layout.
+     * `'start'` (default) nudges the label down to meet a standard ~36px input's
+     * first line; `'center'` removes that offset so the label centres against a
+     * short control (Switch, SegmentedControl).
+     */
+    align?: 'start' | 'center';
     style?: React__default.CSSProperties;
     /** Label column width in horizontal layout. */
     width?: string | number;
@@ -1885,7 +1892,7 @@ interface FieldLabelProps {
  *
  * Returns `null` when there's nothing to show (no label and no helperText).
  */
-declare function FieldLabel({ label, htmlFor, required, helperText, horizontal, style, width, className, }: FieldLabelProps): react_jsx_runtime.JSX.Element;
+declare function FieldLabel({ label, htmlFor, required, helperText, horizontal, align, style, width, className, }: FieldLabelProps): react_jsx_runtime.JSX.Element;
 interface FieldProps {
     label?: React__default.ReactNode;
     /** `id` of the control — links the `<label htmlFor>`. */
@@ -1899,6 +1906,12 @@ interface FieldProps {
     required?: boolean;
     /** Contextual help revealed via an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
+    /**
+     * Label alignment against the control in horizontal layout. `'start'`
+     * (default) for standard-height inputs; `'center'` for short controls
+     * (Switch) so the label lines up with the control's centre.
+     */
+    labelAlign?: 'start' | 'center';
     labelStyle?: React__default.CSSProperties;
     /** Width of the label column in horizontal layout (CSS length). */
     labelWidth?: string | number;
@@ -1921,7 +1934,7 @@ interface FieldProps {
  * medium weight so it reads as the anchor, while the input's placeholder is
  * muted — establishing hierarchy without making the label tiny.
  */
-declare function Field({ label, htmlFor, errorId, errorMessage, layout, required, helperText, labelStyle, labelWidth, className, children, }: FieldProps): react_jsx_runtime.JSX.Element;
+declare function Field({ label, htmlFor, errorId, errorMessage, layout, required, helperText, labelAlign, labelStyle, labelWidth, className, children, }: FieldProps): react_jsx_runtime.JSX.Element;
 
 interface TextInputProps {
     value?: string;
@@ -2110,8 +2123,9 @@ interface SearchInputProps {
 declare const SearchInput: React__default.ForwardRefExoticComponent<SearchInputProps & React__default.RefAttributes<HTMLInputElement>>;
 
 interface CheckboxProps {
-    /** Controlled checked state */
+    /** Controlled checked state. */
     checked?: boolean;
+    /** Fires `{ target: { checked, id, name } }` for form-handler compatibility. */
     onChange?: (e: {
         target: {
             checked: boolean;
@@ -2119,12 +2133,22 @@ interface CheckboxProps {
             name?: string;
         };
     }) => void;
+    /** Primary label text. */
     label?: React__default.ReactNode;
+    /** Secondary line rendered under the label (same affordance as RadioGroup options). */
+    description?: React__default.ReactNode;
+    /** Native form field name. */
     name?: string;
-    /** `id` for the hidden input and the `<label htmlFor>` link */
+    /** `id` for the control and the `<label htmlFor>` link. */
     htmlFor?: string;
+    /** Validation message — shown under the control; also flags the box red + `aria-invalid`. */
     errorMessage?: React__default.ReactNode;
+    /** Contextual help revealed via an info icon + tooltip beside the label. */
+    helperText?: React__default.ReactNode;
+    /** Disable interaction + dim the control. */
     disabled?: boolean;
+    /** Show a required asterisk after the label. */
+    required?: boolean;
     /**
      * Box + label arrangement.
      * - `'horizontal'` (default): box and label on one row.
@@ -2132,34 +2156,36 @@ interface CheckboxProps {
      */
     layout?: 'horizontal' | 'vertical';
     /**
-     * Where the label sits relative to the box.
-     * - In horizontal: `'right'` (default) → box then label; `'left'` → label then box.
-     * - In vertical: `'right'` (default) → box then label below; `'left'` → label above then box.
+     * Which side of the box the label sits on.
+     * - `'right'` (default): box then label.
+     * - `'left'`: label then box (the description always wraps under the label).
      */
     labelPosition?: 'left' | 'right';
-    /** Contextual help revealed via an info icon + tooltip beside the label. */
-    helperText?: React__default.ReactNode;
-    /** Show a required asterisk after the label. */
-    required?: boolean;
-    /** @deprecated Use `checked` */
+    /** @deprecated Use `checked`. Kept for API compatibility. */
     value?: boolean;
 }
 /**
  * Accessible checkbox powered by Radix Checkbox.
  *
- * Radix handles keyboard activation, focus ring, and `role="checkbox"` ARIA.
- * The check mark pops in with a spring animation on first check.
+ * Radix handles keyboard activation, focus ring, and `role="checkbox"` ARIA;
+ * the check mark pops in with a spring on first check. Supports a secondary
+ * `description`, `helperText` tooltip, left/right label placement, and the
+ * shared error treatment — so it lines up with every other input in a form.
+ *
+ * Emits `{ target: { checked, id, name } }` for drop-in use with existing
+ * change handlers.
  *
  * @example
  * <Checkbox
  *   htmlFor="agree"
  *   label="I agree to the terms"
+ *   description="You can revoke consent any time in settings."
  *   checked={form.agree}
  *   onChange={({ target }) => setField('agree', target.checked)}
  * />
  */
 declare function Checkbox({ checked, value, // legacy alias
-onChange, label, name, htmlFor, errorMessage, disabled, layout, labelPosition, helperText, required, }: CheckboxProps): react_jsx_runtime.JSX.Element;
+onChange, label, description, name, htmlFor, errorMessage, helperText, disabled, required, layout, labelPosition, }: CheckboxProps): react_jsx_runtime.JSX.Element;
 
 interface RadioOption {
     /** Stable value submitted / reported on change. */

package/dist/index.d.ts

@@ -1870,8 +1870,15 @@ interface FieldLabelProps {
     required?: boolean;
     /** Reveals an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
-    /** Apply horizontal-layout spacing (top margin, no-wrap, shrink). */
+    /** Apply horizontal-layout spacing (no-wrap, shrink). */
     horizontal?: boolean;
+    /**
+     * Vertical alignment of the label against the control in horizontal layout.
+     * `'start'` (default) nudges the label down to meet a standard ~36px input's
+     * first line; `'center'` removes that offset so the label centres against a
+     * short control (Switch, SegmentedControl).
+     */
+    align?: 'start' | 'center';
     style?: React__default.CSSProperties;
     /** Label column width in horizontal layout. */
     width?: string | number;
@@ -1885,7 +1892,7 @@ interface FieldLabelProps {
  *
  * Returns `null` when there's nothing to show (no label and no helperText).
  */
-declare function FieldLabel({ label, htmlFor, required, helperText, horizontal, style, width, className, }: FieldLabelProps): react_jsx_runtime.JSX.Element;
+declare function FieldLabel({ label, htmlFor, required, helperText, horizontal, align, style, width, className, }: FieldLabelProps): react_jsx_runtime.JSX.Element;
 interface FieldProps {
     label?: React__default.ReactNode;
     /** `id` of the control — links the `<label htmlFor>`. */
@@ -1899,6 +1906,12 @@ interface FieldProps {
     required?: boolean;
     /** Contextual help revealed via an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
+    /**
+     * Label alignment against the control in horizontal layout. `'start'`
+     * (default) for standard-height inputs; `'center'` for short controls
+     * (Switch) so the label lines up with the control's centre.
+     */
+    labelAlign?: 'start' | 'center';
     labelStyle?: React__default.CSSProperties;
     /** Width of the label column in horizontal layout (CSS length). */
     labelWidth?: string | number;
@@ -1921,7 +1934,7 @@ interface FieldProps {
  * medium weight so it reads as the anchor, while the input's placeholder is
  * muted — establishing hierarchy without making the label tiny.
  */
-declare function Field({ label, htmlFor, errorId, errorMessage, layout, required, helperText, labelStyle, labelWidth, className, children, }: FieldProps): react_jsx_runtime.JSX.Element;
+declare function Field({ label, htmlFor, errorId, errorMessage, layout, required, helperText, labelAlign, labelStyle, labelWidth, className, children, }: FieldProps): react_jsx_runtime.JSX.Element;
 
 interface TextInputProps {
     value?: string;
@@ -2110,8 +2123,9 @@ interface SearchInputProps {
 declare const SearchInput: React__default.ForwardRefExoticComponent<SearchInputProps & React__default.RefAttributes<HTMLInputElement>>;
 
 interface CheckboxProps {
-    /** Controlled checked state */
+    /** Controlled checked state. */
     checked?: boolean;
+    /** Fires `{ target: { checked, id, name } }` for form-handler compatibility. */
     onChange?: (e: {
         target: {
             checked: boolean;
@@ -2119,12 +2133,22 @@ interface CheckboxProps {
             name?: string;
         };
     }) => void;
+    /** Primary label text. */
     label?: React__default.ReactNode;
+    /** Secondary line rendered under the label (same affordance as RadioGroup options). */
+    description?: React__default.ReactNode;
+    /** Native form field name. */
     name?: string;
-    /** `id` for the hidden input and the `<label htmlFor>` link */
+    /** `id` for the control and the `<label htmlFor>` link. */
     htmlFor?: string;
+    /** Validation message — shown under the control; also flags the box red + `aria-invalid`. */
     errorMessage?: React__default.ReactNode;
+    /** Contextual help revealed via an info icon + tooltip beside the label. */
+    helperText?: React__default.ReactNode;
+    /** Disable interaction + dim the control. */
     disabled?: boolean;
+    /** Show a required asterisk after the label. */
+    required?: boolean;
     /**
      * Box + label arrangement.
      * - `'horizontal'` (default): box and label on one row.
@@ -2132,34 +2156,36 @@ interface CheckboxProps {
      */
     layout?: 'horizontal' | 'vertical';
     /**
-     * Where the label sits relative to the box.
-     * - In horizontal: `'right'` (default) → box then label; `'left'` → label then box.
-     * - In vertical: `'right'` (default) → box then label below; `'left'` → label above then box.
+     * Which side of the box the label sits on.
+     * - `'right'` (default): box then label.
+     * - `'left'`: label then box (the description always wraps under the label).
      */
     labelPosition?: 'left' | 'right';
-    /** Contextual help revealed via an info icon + tooltip beside the label. */
-    helperText?: React__default.ReactNode;
-    /** Show a required asterisk after the label. */
-    required?: boolean;
-    /** @deprecated Use `checked` */
+    /** @deprecated Use `checked`. Kept for API compatibility. */
     value?: boolean;
 }
 /**
  * Accessible checkbox powered by Radix Checkbox.
  *
- * Radix handles keyboard activation, focus ring, and `role="checkbox"` ARIA.
- * The check mark pops in with a spring animation on first check.
+ * Radix handles keyboard activation, focus ring, and `role="checkbox"` ARIA;
+ * the check mark pops in with a spring on first check. Supports a secondary
+ * `description`, `helperText` tooltip, left/right label placement, and the
+ * shared error treatment — so it lines up with every other input in a form.
+ *
+ * Emits `{ target: { checked, id, name } }` for drop-in use with existing
+ * change handlers.
  *
  * @example
  * <Checkbox
  *   htmlFor="agree"
  *   label="I agree to the terms"
+ *   description="You can revoke consent any time in settings."
  *   checked={form.agree}
  *   onChange={({ target }) => setField('agree', target.checked)}
  * />
  */
 declare function Checkbox({ checked, value, // legacy alias
-onChange, label, name, htmlFor, errorMessage, disabled, layout, labelPosition, helperText, required, }: CheckboxProps): react_jsx_runtime.JSX.Element;
+onChange, label, description, name, htmlFor, errorMessage, helperText, disabled, required, layout, labelPosition, }: CheckboxProps): react_jsx_runtime.JSX.Element;
 
 interface RadioOption {
     /** Stable value submitted / reported on change. */

package/dist/index.js

@@ -2165,6 +2165,7 @@ function FieldLabel({
   required,
   helperText,
   horizontal = false,
+  align = "start",
   style,
   width,
   className = ""
@@ -2176,7 +2177,10 @@ function FieldLabel({
       style: { width: horizontal ? width : void 0, ...style },
       className: [
         "flex items-center gap-1",
-        horizontal ? "mt-2 flex-shrink-0 whitespace-nowrap" : "",
+        horizontal ? "flex-shrink-0 whitespace-nowrap" : "",
+        // Only the 'start' alignment needs the top nudge; 'center' relies
+        // on the row's items-center to line up with a short control.
+        horizontal && align === "start" ? "mt-2" : "",
         className
       ].filter(Boolean).join(" "),
       children: [
@@ -2197,6 +2201,7 @@ function Field({
   layout = "vertical",
   required,
   helperText,
+  labelAlign = "start",
   labelStyle,
   labelWidth,
   className = "",
@@ -2209,7 +2214,7 @@ function Field({
     {
       className: [
         "flex",
-        horizontal ? "flex-row items-start gap-3" : "flex-col gap-1.5",
+        horizontal ? `flex-row gap-3 ${labelAlign === "center" ? "items-center" : "items-start"}` : "flex-col gap-1.5",
         className
       ].filter(Boolean).join(" "),
       children: [
@@ -2221,6 +2226,7 @@ function Field({
             required,
             helperText,
             horizontal,
+            align: labelAlign,
             style: labelStyle,
             width: labelWidth
           }
@@ -3679,14 +3685,15 @@ function Checkbox({
   // legacy alias
   onChange,
   label,
+  description,
   name,
   htmlFor,
   errorMessage,
+  helperText,
   disabled = false,
+  required,
   layout = "horizontal",
-  labelPosition = "right",
-  helperText,
-  required
+  labelPosition = "right"
 }) {
   const isChecked = checked ?? value ?? false;
   const labelFirst = labelPosition === "left";
@@ -3699,11 +3706,12 @@ function Checkbox({
       name,
       checked: isChecked,
       disabled,
+      required,
       onCheckedChange: (c) => onChange?.({ target: { checked: !!c, id: htmlFor, name } }),
       className: [
-        "relative flex h-[18px] w-[18px] flex-shrink-0 items-center justify-center",
+        "relative mt-0.5 flex h-[18px] w-[18px] flex-shrink-0 items-center justify-center",
         "rounded-sm border transition-colors duration-150",
-        "border-border-strong bg-surface",
+        hasError ? "border-status-error" : "border-border-strong",
         "data-[state=checked]:bg-accent data-[state=checked]:border-accent",
         // Focus halo matches the field tokens for a consistent look.
         "focus:outline-none focus-visible:ring-[3px] focus-visible:ring-focus-ring",
@@ -3715,33 +3723,60 @@ function Checkbox({
       children: /* @__PURE__ */ jsx(CheckboxPrimitive.Indicator, { className: "flex items-center justify-center data-[state=checked]:animate-check-pop", children: /* @__PURE__ */ jsx("svg", { width: "11", height: "9", viewBox: "0 0 11 9", fill: "none", "aria-hidden": "true", children: /* @__PURE__ */ jsx("path", { d: "M1 4.5L4 7.5L10 1", stroke: "white", strokeWidth: "1.8", strokeLinecap: "round", strokeLinejoin: "round" }) }) })
     }
   );
-  const labelEl = label && /* @__PURE__ */ jsxs("span", { className: "text-sm text-foreground-secondary select-none leading-snug", children: [
-    label,
-    required && /* @__PURE__ */ jsx("span", { className: "text-status-error ml-0.5", "aria-hidden": "true", children: "*" })
-  ] });
+  const labelText = label != null && /* @__PURE__ */ jsxs(
+    "label",
+    {
+      htmlFor,
+      className: ["block select-none text-sm text-foreground leading-snug", disabled ? "cursor-not-allowed opacity-50" : "cursor-pointer"].join(" "),
+      children: [
+        label,
+        required && /* @__PURE__ */ jsx("span", { className: "text-status-error ml-0.5", "aria-hidden": "true", children: "*" })
+      ]
+    }
+  );
+  const descriptionEl = description != null && /* @__PURE__ */ jsx(
+    "label",
+    {
+      htmlFor,
+      className: `block text-xs text-foreground-secondary mt-0.5 ${disabled ? "opacity-50 cursor-not-allowed" : "cursor-pointer"}`,
+      children: description
+    }
+  );
+  let content;
+  if (layout === "vertical") {
+    content = /* @__PURE__ */ jsxs("span", { className: "flex flex-col items-start gap-1.5", children: [
+      labelFirst ? /* @__PURE__ */ jsxs(Fragment, { children: [
+        labelText,
+        box
+      ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+        box,
+        labelText
+      ] }),
+      descriptionEl
+    ] });
+  } else if (labelFirst) {
+    content = /* @__PURE__ */ jsxs("span", { className: "flex flex-col", children: [
+      /* @__PURE__ */ jsxs("span", { className: "flex items-start gap-2.5", children: [
+        labelText,
+        box
+      ] }),
+      descriptionEl
+    ] });
+  } else {
+    content = /* @__PURE__ */ jsxs("span", { className: "flex items-start gap-2.5", children: [
+      box,
+      /* @__PURE__ */ jsxs("span", { className: "flex flex-col", children: [
+        labelText,
+        descriptionEl
+      ] })
+    ] });
+  }
   return /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-1", children: [
-    /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-1", children: [
-      /* @__PURE__ */ 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__ */ jsxs(Fragment, { children: [
-            labelEl,
-            box
-          ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
-            box,
-            labelEl
-          ] })
-        }
-      ),
+    /* @__PURE__ */ jsxs("div", { className: "flex items-start gap-1", children: [
+      content,
       helperText != null && /* @__PURE__ */ jsx(FieldHelpIcon, { text: helperText })
     ] }),
-    errorMessage && /* @__PURE__ */ jsx("span", { id: errorId, className: "text-xs text-status-error mt-0.5", children: errorMessage })
+    hasError && /* @__PURE__ */ jsx("span", { id: errorId, className: "text-xs text-status-error mt-0.5", children: errorMessage })
   ] });
 }
 var DOT_SIZE = {
@@ -3893,6 +3928,7 @@ function Switch({
       layout,
       required,
       helperText,
+      labelAlign: "center",
       children: /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2.5", children: [
         offLabel != null && /* @__PURE__ */ jsx("label", { htmlFor: id, className: stateLabel(!isOn), children: offLabel }),
         /* @__PURE__ */ jsx(
@@ -4182,19 +4218,17 @@ function TreeSelect({
       setOpen(false);
     }
   };
-  return /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-1", children: [
-    /* @__PURE__ */ jsxs("div", { className: `flex ${layout === "vertical" ? "flex-col gap-1" : "flex-row items-center gap-2"}`, children: [
-      /* @__PURE__ */ jsx(
-        FieldLabel,
-        {
-          label,
-          htmlFor,
-          required,
-          helperText,
-          horizontal: layout === "horizontal"
-        }
-      ),
-      /* @__PURE__ */ jsxs(Popover.Root, { open: open && !disabled, onOpenChange: (o) => !disabled && setOpen(o), children: [
+  return /* @__PURE__ */ jsx(
+    Field,
+    {
+      label,
+      htmlFor,
+      errorId,
+      errorMessage,
+      layout,
+      required,
+      helperText,
+      children: /* @__PURE__ */ jsx("div", { children: /* @__PURE__ */ jsxs(Popover.Root, { open: open && !disabled, onOpenChange: (o) => !disabled && setOpen(o), children: [
         /* @__PURE__ */ jsx(Popover.Trigger, { asChild: true, children: /* @__PURE__ */ jsxs(
           "button",
           {
@@ -4258,10 +4292,9 @@ function TreeSelect({
             )
           }
         ) })
-      ] })
-    ] }),
-    hasError && /* @__PURE__ */ jsx("div", { id: errorId, className: "text-xs text-status-error ml-1", children: errorMessage })
-  ] });
+      ] }) })
+    }
+  );
 }
 function TreeNodeRow({
   node,