@spaethtech/svelte-ui 0.4.1-dev.21.2ccc703 → 0.4.1-dev.23.372ce0b

package/.claude/skills/svelte-ui/SKILL.md

@@ -98,6 +98,18 @@ control.
 surfaces through the **native validity tooltip** (shown on form submit); the controlled **`error`**
 prop is the inline row. Both flip the field's error border.
 
+**Groups:** for a set of radios/checkboxes/toggles under one legend, wrap them in **`FieldGroup`**
+(same `label`/`description`/`error`/`required` vocab on a `<fieldset>`, plus `orientation`). Inside a
+group, item labels render **inline** (right of the control). For a radio group, `bind:value` on the
+`FieldGroup` (+ optional `name`) and the child `<Radio>`s share it automatically — no `bind:group`:
+
+```svelte
+<FieldGroup label="Delivery" bind:value={method} name="method">
+  <Radio value="email" label="Email" />
+  <Radio value="sms" label="SMS" />
+</FieldGroup>
+```
+
 ## Icons — no `<Icon>` component
 
 Import an MDI icon component from `~icons/mdi/*` and render it into a component's **`icon` snippet**;
@@ -137,7 +149,8 @@ Mount `<Toaster />` once at the app root, then push from anywhere with `toast.su
 All from `@spaethtech/svelte-ui` (see the shipped `docs/components.md` + `docs/usage.md` for props +
 examples):
 
-- **Form:** `Button` `ButtonDropdown` `Input` `Select` `List` `TextArea` `Checkbox` `Toggle` `Rating`
+- **Form:** `Button` `ButtonDropdown` `Input` `Select` `List` `TextArea` `Checkbox` `Toggle` `Radio`
+  `Rating` · **`FieldGroup`** (fieldset wrapper for radio/checkbox/toggle sets)
 - **Specialized inputs:** `PasswordInput` `EmailInput` `SearchInput` `NumberInput`
 - **Date / time:** `DatePicker` `Calendar` `TimePicker` `TimeSpinner` `TimeRangeInput` `DateTimeInput`
 - **Data:** `DataTable` `Query` — driven by the headless layer at **`@spaethtech/svelte-ui/data`**

package/.claude/skills/themes/SKILL.md

@@ -33,11 +33,17 @@ These are the only palette colours a component references. The `variant` axis
 non-accent variants `neutral` and `ghost` → `--ui-color-text`). Canonical order:
 `neutral · primary · secondary · success · info · warning · danger · ghost`.
 
-- `ghost` — borderless, transparent, hover-tint only (the minimal control).
+- `ghost` — borderless, transparent, hover-tint only (the minimal control). For the box-shaped
+  **fields** (Input/Select/TextArea) this also drives the **field background**: `ghost` → transparent,
+  every other variant → `--ui-color-background` (so a field reads as a field on any surface).
 - `neutral` — the _uncoloured_ variant (mixes from `--ui-color-text`): **solid** in solid contexts
   (Button/Toggle/Banner → black-on-white / white-on-black), a **tint** in soft contexts (Badge/Alert).
 - (`plain` was removed — it's now `ghost`. Old bordered-`ghost` → `neutral`.)
 
+Field **help/error text** uses no new token: the muted `description` row is an inline
+`color-mix(in srgb, var(--ui-color-text) ~65%, transparent)`, and the `error` row uses
+`--ui-color-error`.
+
 ### Interactive-surface tints — `--ui-accent` + hover/surface/active
 
 One tint language for every hover / section / pressed surface, three steps of the SAME mix:

package/dist/components/Checkbox.svelte

@@ -1,21 +1,13 @@
 <!--
 /**
- * Checkbox — a themed multi-state box (unchecked / checked / indeterminate). Use this, NOT a Toggle,
- * for selection semantics: a row is / isn't selected, a rule does / doesn't apply, a filter is / isn't
- * active. A real `<input type=checkbox>` drives it — laid INVISIBLY over the whole control, so clicking
- * anywhere toggles it (naturally clickable + testable + accessible + form-friendly; `bind:checked`
- * works, and `onchange` fires a real event). Honours the shared {@link Variant} (the "checked" colour)
- * + {@link Size} axes.
+ * Checkbox — a themed multi-state box (unchecked / checked / indeterminate). A real invisible
+ * `<input type=checkbox>` drives it (native click/keyboard/a11y/forms). Shared {@link Variant} +
+ * {@link Size} axes.
  *
- * ALIGNMENT: same story as Toggle — the visible box is deliberately smaller than a text control, but
- * the Checkbox occupies a wrapper sized to the standard control HEIGHT for its `size` (sm 24 / md 32 /
- * lg 40px — same as Input), with the box centred inside. Drop it next to a `size`-matched Input/Select
- * and everything lines up on the same baseline; the full-height wrapper is the click target while the
- * box itself stays box-sized.
- *
- * FIELD CHROME: `label`/`aside`/`error`/`description` (see FieldChrome.spec.md). When any is set the
- * control is wrapped in the shared FieldChrome (label ABOVE, error/description below); with none set it
- * renders bare + inline exactly as before (zero-regression).
+ * LAYOUT: standalone, `label` follows the field-chrome rule (ABOVE the box, so mixed-control rows at
+ * the same `size` align). Inside a `FieldGroup`, the label sits inline to the RIGHT of the box
+ * (conventional list layout) and `size`/`variant`/`disabled` inherit from the group. With no chrome
+ * props (and no group) it renders bare + inline exactly as before (zero-regression).
  */
 -->
 <script lang="ts">
@@ -25,13 +17,14 @@
   import { responsiveClasses, type Responsive } from "../types/responsive.js";
   import { variantToken, type Variant } from "../types/variants.js";
   import FieldChrome, { nextFieldId } from "./FieldChrome.svelte";
+  import { getFieldGroup } from "./field-group.js";
 
   let {
     checked = $bindable(false),
     indeterminate = false,
     disabled = false,
-    size = "md",
-    variant = "primary",
+    size,
+    variant,
     class: cls = "",
     label = null,
     aside,
@@ -45,128 +38,106 @@
     indeterminate?: boolean;
     disabled?: boolean;
     size?: Responsive<Size>;
-    /** The colour of the "checked" state (default primary). */
+    /** The colour of the "checked" state (default primary; inherits the group's variant if unset). */
     variant?: Variant;
     class?: string;
-    /** Field chrome (see FieldChrome.spec.md). Label renders ABOVE. */
+    /** Field chrome. Inline (right of the box) in a FieldGroup; above when standalone. */
     label?: string | null;
     aside?: Snippet;
     error?: string | Snippet | null;
     description?: string | Snippet | null;
   } & Omit<HTMLInputAttributes, "size" | "type" | "class"> = $props();
 
-  // Per size: visible box dimension. Same scale as icons (14 / 16 / 20 px) so the box aligns with
-  // adjacent MDI icons at the matching size.
-  const dims: Record<Size, string> = {
-    sm: "size-3.5",
-    md: "size-4",
-    lg: "size-5",
-  };
-  const iconSize: Record<Size, string> = {
-    sm: "size-3",
-    md: "size-3.5",
-    lg: "size-4",
-  };
-  // Wrapper height matches Input's h-6/h-8/h-10 so the box centres on the same baseline as sibling
-  // controls at the same `size`.
+  const grp = getFieldGroup();
+  const inGroup = !!grp?.inGroup;
+  const effSize = $derived(size ?? grp?.size ?? "md");
+  const effVariant = $derived(variant ?? grp?.variant ?? "primary");
+  const effDisabled = $derived(disabled || !!grp?.disabled);
+
+  const dims: Record<Size, string> = { sm: "size-3.5", md: "size-4", lg: "size-5" };
+  const iconSize: Record<Size, string> = { sm: "size-3", md: "size-3.5", lg: "size-4" };
   const heightMap: Record<Size, string> = { sm: "h-6", md: "h-8", lg: "h-10" };
-  const heightClass = $derived(responsiveClasses(size, heightMap));
-  const boxSize = $derived(responsiveClasses(size, dims));
-  const iconSizeCls = $derived(responsiveClasses(size, iconSize));
+  const textMap: Record<Size, string> = { sm: "text-xs", md: "text-sm", lg: "text-base" };
+  const heightClass = $derived(responsiveClasses(effSize, heightMap));
+  const boxSize = $derived(responsiveClasses(effSize, dims));
+  const iconSizeCls = $derived(responsiveClasses(effSize, iconSize));
+  const labelText = $derived(responsiveClasses(effSize, textMap));
   const filled = $derived(checked || indeterminate);
-  const variantVar = $derived(`var(${variantToken[variant]})`);
+  const variantVar = $derived(`var(${variantToken[effVariant]})`);
   const boxStyle = $derived(
     filled
       ? `background-color: ${variantVar}; border-color: ${variantVar};`
       : `background-color: transparent; border-color: color-mix(in srgb, var(--ui-color-text) 40%, transparent);`,
   );
-  // Mark colour = the INVERTED text colour (`--ui-color-background`) with a hint of the variant mixed
-  // in — ONE rule for every variant, both themes (matches the Toggle knob). Light: near-white on the
-  // fill; dark: flips dark, which reads on the dark theme's brighter accent fills. The 80% background
-  // keeps it contrasting even on a neutral (`--ui-color-text`) fill.
   const markColor = $derived(
-    `color-mix(in srgb, var(--ui-color-background) 80%, var(${variantToken[variant]}))`,
+    `color-mix(in srgb, var(--ui-color-background) 80%, var(${variantToken[effVariant]}))`,
   );
 
-  // Field chrome wiring.
   const generatedId = nextFieldId();
   const controlId = $derived(id ?? generatedId);
   const isSnippet = (v: unknown): v is Snippet => typeof v === "function";
   const hasError = $derived(isSnippet(error) ? true : !!(error && String(error).trim()));
   const hasDesc = $derived(isSnippet(description) ? true : !!(description && String(description).trim()));
-  const hasChrome = $derived(!!label || !!aside || hasError || hasDesc);
+  // Standalone chrome (label ABOVE) only when NOT in a group and some chrome prop is set.
+  const hasChrome = $derived(!inGroup && (!!label || !!aside || hasError || hasDesc));
+  // Show an inline label to the right when in a group (or standalone-bare with a label).
+  const showInlineLabel = $derived((inGroup || !hasChrome) && !!label);
 
   let el = $state<HTMLInputElement>();
-  // `indeterminate` is a DOM property, not an attribute — sync it imperatively so the real
-  // checkbox reports the tri-state to a11y and form serialization.
   $effect(() => {
     if (el) el.indeterminate = indeterminate;
   });
 </script>
 
-{#snippet controlMarkup(cid: string | undefined, describedBy: string | undefined)}
+<!-- The box + invisible input. `wrap` = the click-target <label>; carries inline label text when set. -->
+{#snippet boxControl(cid: string | undefined, describedBy: string | undefined)}
+  <input
+    bind:this={el}
+    type="checkbox"
+    bind:checked
+    disabled={effDisabled}
+    {required}
+    id={cid}
+    aria-describedby={describedBy}
+    aria-invalid={hasError || undefined}
+    class="peer absolute inset-0 z-10 m-0 cursor-pointer opacity-0 disabled:cursor-not-allowed"
+    {...rest}
+  />
+  <span
+    class="relative inline-flex items-center justify-center rounded-[3px] border transition-colors duration-150 peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:[outline-color:var(--ui-color-primary)] {boxSize}"
+    style={boxStyle}
+  >
+    {#if indeterminate}
+      <svg viewBox="0 0 16 16" class={iconSizeCls} style="color: {markColor}" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round">
+        <line x1="4" y1="8" x2="12" y2="8" />
+      </svg>
+    {:else if checked}
+      <svg viewBox="0 0 16 16" class={iconSizeCls} style="color: {markColor}" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+        <polyline points="3.5,8.5 6.5,11.5 12.5,5" />
+      </svg>
+    {/if}
+  </span>
+{/snippet}
+
+{#snippet wrap(cid: string | undefined, describedBy: string | undefined, extra: string)}
   <label
-    class="relative inline-flex shrink-0 items-center justify-center {heightClass} {disabled
+    class="relative inline-flex shrink-0 items-center {showInlineLabel
+      ? 'gap-2'
+      : 'justify-center'} {heightClass} {effDisabled
       ? 'cursor-not-allowed opacity-50'
-      : 'cursor-pointer'} {hasChrome ? 'self-start' : cls}"
+      : 'cursor-pointer'} {extra}"
   >
-    <!-- Real checkbox — invisible, covering the whole control so a click anywhere toggles it and
-		     keyboard/focus/screen-reader behavior is native. -->
-    <input
-      bind:this={el}
-      type="checkbox"
-      bind:checked
-      {disabled}
-      {required}
-      id={cid}
-      aria-describedby={describedBy}
-      aria-invalid={hasError || undefined}
-      class="peer absolute inset-0 z-10 m-0 cursor-pointer opacity-0 disabled:cursor-not-allowed"
-      {...rest}
-    />
-    <span
-      class="relative inline-flex items-center justify-center rounded-[3px] border transition-colors duration-150 peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:[outline-color:var(--ui-color-primary)] {boxSize}"
-      style={boxStyle}
-    >
-      {#if indeterminate}
-        <!-- Dash for indeterminate — mid-line, contrasting mark on the filled background. -->
-        <svg
-          viewBox="0 0 16 16"
-          class={iconSizeCls}
-          style="color: {markColor}"
-          fill="none"
-          stroke="currentColor"
-          stroke-width="2.5"
-          stroke-linecap="round"
-        >
-          <line x1="4" y1="8" x2="12" y2="8" />
-        </svg>
-      {:else if checked}
-        <!-- Checkmark — sits inside the filled box. Stroke uses currentColor; `markColor` picks white
-			     on accent fills, the background colour on neutral/ghost (which are text-coloured). -->
-        <svg
-          viewBox="0 0 16 16"
-          class={iconSizeCls}
-          style="color: {markColor}"
-          fill="none"
-          stroke="currentColor"
-          stroke-width="2.5"
-          stroke-linecap="round"
-          stroke-linejoin="round"
-        >
-          <polyline points="3.5,8.5 6.5,11.5 12.5,5" />
-        </svg>
-      {/if}
-    </span>
+    {@render boxControl(cid, describedBy)}
+    {#if showInlineLabel}<span class="{labelText} [color:var(--ui-color-text)]">{label}</span>{/if}
   </label>
 {/snippet}
 
 {#if hasChrome}
-  <FieldChrome {label} {aside} {error} {description} required={!!required} {controlId} {size} class={cls}>
+  <FieldChrome {label} {aside} {error} {description} required={!!required} {controlId} size={effSize} class={cls}>
     {#snippet control({ describedBy })}
-      {@render controlMarkup(controlId, describedBy)}
+      {@render wrap(controlId, describedBy, "self-start")}
     {/snippet}
   </FieldChrome>
 {:else}
-  {@render controlMarkup(undefined, undefined)}
+  {@render wrap(controlId, undefined, cls)}
 {/if}

package/dist/components/Checkbox.svelte.d.ts

@@ -8,10 +8,10 @@ type $$ComponentProps = {
     indeterminate?: boolean;
     disabled?: boolean;
     size?: Responsive<Size>;
-    /** The colour of the "checked" state (default primary). */
+    /** The colour of the "checked" state (default primary; inherits the group's variant if unset). */
     variant?: Variant;
     class?: string;
-    /** Field chrome (see FieldChrome.spec.md). Label renders ABOVE. */
+    /** Field chrome. Inline (right of the box) in a FieldGroup; above when standalone. */
     label?: string | null;
     aside?: Snippet;
     error?: string | Snippet | null;

package/dist/components/FieldGroup.svelte

@@ -0,0 +1,80 @@
+<!--
+/**
+ * FieldGroup — one wrapper for a set of Radios, Checkboxes, or Toggles under a shared legend. Renders
+ * FieldsetChrome (legend + description/error + orientation) and shares a group context so child
+ * controls render their label INLINE (right of the control) and inherit `size`/`variant`/`disabled`.
+ *
+ * For a RADIO group, bind `value` (+ optional `name`): child `<Radio>`s pick up the shared value/name
+ * automatically — no per-radio `bind:group`. Checkboxes/Toggles stay independent (their own
+ * `bind:checked`); `value`/`name` are simply ignored by them.
+ */
+-->
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import type { Size } from "../types/sizes.js";
+  import type { Variant } from "../types/variants.js";
+  import type { Responsive } from "../types/responsive.js";
+  import FieldsetChrome from "./FieldsetChrome.svelte";
+  import { setFieldGroup } from "./field-group.js";
+
+  let {
+    value = $bindable(),
+    name,
+    label = null,
+    aside,
+    error = null,
+    description = null,
+    required = false,
+    orientation = "vertical",
+    size = "md",
+    variant,
+    disabled = false,
+    class: cls = "",
+    children,
+  }: {
+    /** Radio groups: the selected value (bindable). Ignored by checkbox/toggle children. */
+    value?: string | number;
+    /** Radio groups: `name` applied to every child radio (native single-select + form serialization). */
+    name?: string;
+    label?: string | null;
+    aside?: Snippet;
+    error?: string | Snippet | null;
+    description?: string | Snippet | null;
+    required?: boolean;
+    orientation?: "vertical" | "horizontal";
+    size?: Responsive<Size>;
+    variant?: Variant;
+    disabled?: boolean;
+    class?: string;
+    children: Snippet;
+  } = $props();
+
+  // Reactive context: getters keep size/variant/orientation/disabled live; getValue/select share the
+  // radio-group value. Set once (context is stable); the getters read current prop values.
+  setFieldGroup({
+    inGroup: true,
+    get orientation() {
+      return orientation;
+    },
+    get size() {
+      return size;
+    },
+    get variant() {
+      return variant;
+    },
+    get disabled() {
+      return disabled;
+    },
+    get name() {
+      return name;
+    },
+    getValue: () => value,
+    select: (v) => {
+      value = v;
+    },
+  });
+</script>
+
+<FieldsetChrome {label} {aside} {error} {description} {required} {orientation} {size} class={cls}>
+  {@render children()}
+</FieldsetChrome>

package/dist/components/FieldGroup.svelte.d.ts

@@ -0,0 +1,24 @@
+import type { Snippet } from "svelte";
+import type { Size } from "../types/sizes.js";
+import type { Variant } from "../types/variants.js";
+import type { Responsive } from "../types/responsive.js";
+type $$ComponentProps = {
+    /** Radio groups: the selected value (bindable). Ignored by checkbox/toggle children. */
+    value?: string | number;
+    /** Radio groups: `name` applied to every child radio (native single-select + form serialization). */
+    name?: string;
+    label?: string | null;
+    aside?: Snippet;
+    error?: string | Snippet | null;
+    description?: string | Snippet | null;
+    required?: boolean;
+    orientation?: "vertical" | "horizontal";
+    size?: Responsive<Size>;
+    variant?: Variant;
+    disabled?: boolean;
+    class?: string;
+    children: Snippet;
+};
+declare const FieldGroup: import("svelte").Component<$$ComponentProps, {}, "value">;
+type FieldGroup = ReturnType<typeof FieldGroup>;
+export default FieldGroup;

package/dist/components/FieldsetChrome.svelte

@@ -0,0 +1,81 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import type { Size } from "../types/sizes.js";
+  import { responsiveClasses, type Responsive } from "../types/responsive.js";
+
+  /**
+   * FieldsetChrome — the group counterpart of FieldChrome: a `<fieldset>` with a `<legend>` (the
+   * group label) plus the same error/description rows, and an orientation-controlled slot for its
+   * child controls. Used by `RadioGroup` / `FieldGroup`. Same prop vocabulary as FieldChrome.
+   */
+  interface Props {
+    label?: string | null;
+    aside?: Snippet;
+    error?: string | Snippet | null;
+    description?: string | Snippet | null;
+    required?: boolean;
+    orientation?: "vertical" | "horizontal";
+    size?: Responsive<Size>;
+    class?: string;
+    children: Snippet;
+  }
+
+  let {
+    label = null,
+    aside,
+    error = null,
+    description = null,
+    required = false,
+    orientation = "vertical",
+    size = "md",
+    class: cls = "",
+    children,
+  }: Props = $props();
+
+  const labelTextMap: Record<Size, string> = { sm: "text-xs", md: "text-sm", lg: "text-base" };
+  const subTextMap: Record<Size, string> = { sm: "text-[0.6875rem]", md: "text-xs", lg: "text-sm" };
+  const labelText = $derived(responsiveClasses(size, labelTextMap));
+  const subText = $derived(responsiveClasses(size, subTextMap));
+
+  const isSnippet = (v: unknown): v is Snippet => typeof v === "function";
+  const hasError = $derived(isSnippet(error) ? true : !!(error && String(error).trim()));
+  const hasDesc = $derived(isSnippet(description) ? true : !!(description && String(description).trim()));
+
+  const itemsClass = $derived(
+    orientation === "horizontal" ? "flex flex-wrap gap-x-6 gap-y-2" : "flex flex-col gap-2",
+  );
+</script>
+
+<fieldset class="m-0 flex min-w-0 flex-col gap-1 border-0 p-0 {cls}">
+  {#if label || aside}
+    <!-- legend stays a direct <fieldset> child (a11y); the row layout lives inside it -->
+    <legend class="flex w-full items-center justify-between gap-2 p-0">
+      {#if label}
+        <span class="{labelText} font-medium [color:var(--ui-color-text)]"
+          >{label}{#if required}<span aria-hidden="true" class="[color:var(--ui-color-error)]"> *</span
+            >{/if}</span
+        >
+      {:else}
+        <span></span>
+      {/if}
+      {#if aside}
+        <span class="{subText} flex shrink-0 items-center gap-2">{@render aside()}</span>
+      {/if}
+    </legend>
+  {/if}
+
+  <div class={itemsClass}>
+    {@render children()}
+  </div>
+
+  {#if hasError}
+    <div class="{subText} [color:var(--ui-color-error)]">
+      {#if isSnippet(error)}{@render error()}{:else}{@html error}{/if}
+    </div>
+  {/if}
+  {#if hasDesc}
+    <div class="{subText} [color:color-mix(in_srgb,var(--ui-color-text)_65%,transparent)]">
+      {#if isSnippet(description)}{@render description()}{:else}{@html description}{/if}
+    </div>
+  {/if}
+</fieldset>

package/dist/components/FieldsetChrome.svelte.d.ts

@@ -0,0 +1,22 @@
+import type { Snippet } from "svelte";
+import type { Size } from "../types/sizes.js";
+import { type Responsive } from "../types/responsive.js";
+/**
+ * FieldsetChrome — the group counterpart of FieldChrome: a `<fieldset>` with a `<legend>` (the
+ * group label) plus the same error/description rows, and an orientation-controlled slot for its
+ * child controls. Used by `RadioGroup` / `FieldGroup`. Same prop vocabulary as FieldChrome.
+ */
+interface Props {
+    label?: string | null;
+    aside?: Snippet;
+    error?: string | Snippet | null;
+    description?: string | Snippet | null;
+    required?: boolean;
+    orientation?: "vertical" | "horizontal";
+    size?: Responsive<Size>;
+    class?: string;
+    children: Snippet;
+}
+declare const FieldsetChrome: import("svelte").Component<Props, {}, "">;
+type FieldsetChrome = ReturnType<typeof FieldsetChrome>;
+export default FieldsetChrome;

package/dist/components/Radio.svelte

@@ -0,0 +1,142 @@
+<!--
+/**
+ * Radio — a themed single-selection control (mirrors Checkbox/Toggle). A real invisible
+ * `<input type=radio>` drives it (native keyboard/a11y/forms). Standalone it uses `bind:group`; inside
+ * a `FieldGroup` it discovers the shared `name` + value via context, so no `bind:group` is needed.
+ *
+ * LABEL: inside a `FieldGroup` (the common case) the label sits inline to the RIGHT of the dot
+ * (conventional radio-list layout). Standalone, it follows the field-chrome rule (label ABOVE via
+ * FieldChrome) — or renders bare (just the dot) with no chrome props.
+ */
+-->
+<script lang="ts">
+  import type { HTMLInputAttributes } from "svelte/elements";
+  import type { Snippet } from "svelte";
+  import type { Size } from "../types/sizes.js";
+  import { responsiveClasses, type Responsive } from "../types/responsive.js";
+  import { variantToken, type Variant } from "../types/variants.js";
+  import FieldChrome, { nextFieldId } from "./FieldChrome.svelte";
+  import { getFieldGroup } from "./field-group.js";
+
+  let {
+    group = $bindable(),
+    value,
+    disabled = false,
+    size,
+    variant,
+    class: cls = "",
+    label = null,
+    aside,
+    error = null,
+    description = null,
+    id,
+    name,
+    ...rest
+  }: {
+    /** Standalone group binding (`bind:group`). Ignored inside a FieldGroup (context drives it). */
+    group?: string | number;
+    /** This radio's value — assigned to the group when picked. */
+    value: string | number;
+    disabled?: boolean;
+    size?: Responsive<Size>;
+    /** Colour of the filled dot (default primary; inherits the group's variant if unset). */
+    variant?: Variant;
+    class?: string;
+    /** Field chrome. Inline (right of the dot) in a FieldGroup; above when standalone. */
+    label?: string | null;
+    aside?: Snippet;
+    error?: string | Snippet | null;
+    description?: string | Snippet | null;
+  } & Omit<HTMLInputAttributes, "size" | "type" | "class" | "value" | "group"> = $props();
+
+  const grp = getFieldGroup();
+  const inGroup = !!grp?.inGroup;
+  const effSize = $derived(size ?? grp?.size ?? "md");
+  const effVariant = $derived(variant ?? grp?.variant ?? "primary");
+  const effName = $derived(name ?? grp?.name);
+  const effDisabled = $derived(disabled || !!grp?.disabled);
+
+  // Checked = matches the group value (context-driven in a FieldGroup, else the local `group` binding).
+  const isChecked = $derived(grp?.getValue ? grp.getValue() === value : group === value);
+  function selectThis() {
+    if (grp?.select) grp.select(value);
+    else group = value;
+  }
+
+  const dims: Record<Size, string> = { sm: "size-3.5", md: "size-4", lg: "size-5" };
+  const dotDims: Record<Size, string> = { sm: "size-1.5", md: "size-2", lg: "size-2.5" };
+  const heightMap: Record<Size, string> = { sm: "h-6", md: "h-8", lg: "h-10" };
+  const textMap: Record<Size, string> = { sm: "text-xs", md: "text-sm", lg: "text-base" };
+  const heightClass = $derived(responsiveClasses(effSize, heightMap));
+  const boxSize = $derived(responsiveClasses(effSize, dims));
+  const dotSize = $derived(responsiveClasses(effSize, dotDims));
+  const labelText = $derived(responsiveClasses(effSize, textMap));
+  const variantVar = $derived(`var(${variantToken[effVariant]})`);
+  const ringStyle = $derived(
+    isChecked
+      ? `border-color: ${variantVar};`
+      : `border-color: color-mix(in srgb, var(--ui-color-text) 40%, transparent);`,
+  );
+
+  const generatedId = nextFieldId();
+  const controlId = $derived(id ?? generatedId);
+  const isSnippet = (v: unknown): v is Snippet => typeof v === "function";
+  const hasError = $derived(isSnippet(error) ? true : !!(error && String(error).trim()));
+  const hasDesc = $derived(isSnippet(description) ? true : !!(description && String(description).trim()));
+  // Standalone chrome (label above) only when NOT in a group and some chrome prop is set.
+  const hasChrome = $derived(!inGroup && (!!label || !!aside || hasError || hasDesc));
+</script>
+
+<!-- The dot control (invisible radio over a ring; filled centre dot when checked). -->
+{#snippet dot(cid: string | undefined, describedBy: string | undefined)}
+  <span
+    class="relative inline-flex shrink-0 items-center justify-center {heightClass} {effDisabled
+      ? 'cursor-not-allowed opacity-50'
+      : 'cursor-pointer'}"
+  >
+    <input
+      type="radio"
+      {value}
+      name={effName}
+      checked={isChecked}
+      disabled={effDisabled}
+      id={cid}
+      aria-describedby={describedBy}
+      onchange={selectThis}
+      class="peer absolute inset-0 z-10 m-0 cursor-pointer opacity-0 disabled:cursor-not-allowed"
+      {...rest}
+    />
+    <span
+      class="relative inline-flex items-center justify-center rounded-full border transition-colors duration-150 peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:[outline-color:var(--ui-color-primary)] {boxSize}"
+      style={ringStyle}
+    >
+      {#if isChecked}
+        <span class="rounded-full {dotSize}" style="background-color: {variantVar}"></span>
+      {/if}
+    </span>
+  </span>
+{/snippet}
+
+<!-- Inline layout (in a group): dot + label to the right. -->
+{#snippet inlineControl(cid: string | undefined, describedBy: string | undefined)}
+  <label
+    class="inline-flex items-center gap-2 {effDisabled
+      ? 'cursor-not-allowed opacity-50'
+      : 'cursor-pointer'} {cls}"
+  >
+    {@render dot(cid, describedBy)}
+    {#if label}<span class="{labelText} [color:var(--ui-color-text)]">{label}</span>{/if}
+  </label>
+{/snippet}
+
+{#if inGroup}
+  {@render inlineControl(controlId, undefined)}
+{:else if hasChrome}
+  <FieldChrome {label} {aside} {error} {description} controlId={controlId} size={effSize} class={cls}>
+    {#snippet control({ describedBy })}
+      {@render dot(controlId, describedBy)}
+    {/snippet}
+  </FieldChrome>
+{:else}
+  {@render inlineControl(controlId, undefined)}
+{/if}

package/dist/components/Radio.svelte.d.ts

@@ -0,0 +1,24 @@
+import type { HTMLInputAttributes } from "svelte/elements";
+import type { Snippet } from "svelte";
+import type { Size } from "../types/sizes.js";
+import { type Responsive } from "../types/responsive.js";
+import { type Variant } from "../types/variants.js";
+type $$ComponentProps = {
+    /** Standalone group binding (`bind:group`). Ignored inside a FieldGroup (context drives it). */
+    group?: string | number;
+    /** This radio's value — assigned to the group when picked. */
+    value: string | number;
+    disabled?: boolean;
+    size?: Responsive<Size>;
+    /** Colour of the filled dot (default primary; inherits the group's variant if unset). */
+    variant?: Variant;
+    class?: string;
+    /** Field chrome. Inline (right of the dot) in a FieldGroup; above when standalone. */
+    label?: string | null;
+    aside?: Snippet;
+    error?: string | Snippet | null;
+    description?: string | Snippet | null;
+} & Omit<HTMLInputAttributes, "size" | "type" | "class" | "value" | "group">;
+declare const Radio: import("svelte").Component<$$ComponentProps, {}, "group">;
+type Radio = ReturnType<typeof Radio>;
+export default Radio;

package/dist/components/Toggle.svelte

@@ -1,20 +1,11 @@
 <!--
 /**
- * Toggle — a sliding on/off switch (à la a physical switch). Use this, NOT a Checkbox, for binary
- * state: enabled/disabled, active/inactive, on/off. A real `<input type=checkbox>` drives it — laid
- * INVISIBLY over the whole control, so clicking anywhere toggles it (naturally clickable +
- * testable + accessible + form-friendly; `bind:checked` works, and `onchange` fires a real event).
- * Honours the shared {@link Variant} (the "on" colour) + {@link Size} axes. Self-contained: no external
- * label needed — pass an `aria-label` when there's no adjacent text.
+ * Toggle — a sliding on/off switch. A real invisible `<input type=checkbox>` drives it (native
+ * click/keyboard/a11y/forms). Shared {@link Variant} + {@link Size} axes.
  *
- * ALIGNMENT: the visible switch is deliberately shorter than a text control, but the Toggle occupies a
- * wrapper sized to the standard control HEIGHT for its `size` (sm 24 / md 32 / lg 40px — same as Input),
- * with the switch centred inside. So a Toggle dropped next to `size`-matched Inputs/Selects lines up on
- * the same baseline (and the full-height wrapper is the click target), while the switch itself stays
- * switch-sized rather than ballooning to the input height.
- *
- * FIELD CHROME: `label`/`aside`/`error`/`description` (see FieldChrome.spec.md). When any is set the
- * control is wrapped in the shared FieldChrome (label ABOVE, error/description below); with none set it
+ * LAYOUT: standalone, `label` follows the field-chrome rule (ABOVE the switch, so mixed-control rows
+ * at the same `size` align). Inside a `FieldGroup`, the label sits inline to the RIGHT of the switch
+ * and `size`/`variant`/`disabled` inherit from the group. With no chrome props (and no group) it
  * renders bare + inline exactly as before (zero-regression).
  */
 -->
@@ -25,12 +16,13 @@
   import { responsiveClasses, resolveScalar, type Responsive } from "../types/responsive.js";
   import { variantToken, type Variant } from "../types/variants.js";
   import FieldChrome, { nextFieldId } from "./FieldChrome.svelte";
+  import { getFieldGroup } from "./field-group.js";
 
   let {
     checked = $bindable(false),
     disabled = false,
-    size = "md",
-    variant = "primary",
+    size,
+    variant,
     class: cls = "",
     label = null,
     aside,
@@ -43,18 +35,22 @@
     checked?: boolean;
     disabled?: boolean;
     size?: Responsive<Size>;
-    /** The colour of the "on" state (default primary). */
+    /** The colour of the "on" state (default primary; inherits the group's variant if unset). */
     variant?: Variant;
     class?: string;
-    /** Field chrome (see FieldChrome.spec.md). Label renders ABOVE. */
+    /** Field chrome. Inline (right of the switch) in a FieldGroup; above when standalone. */
     label?: string | null;
     aside?: Snippet;
     error?: string | Snippet | null;
     description?: string | Snippet | null;
   } & Omit<HTMLInputAttributes, "size" | "type" | "class"> = $props();
 
-  // Per size: track w/h + knob size are CLASSES (responsive); knob travel is an inline-style transform
-  // (JS value → keys off the base tier). Knob sits 2px in, travels W − K − 4px.
+  const grp = getFieldGroup();
+  const inGroup = !!grp?.inGroup;
+  const effSize = $derived(size ?? grp?.size ?? "md");
+  const effVariant = $derived(variant ?? grp?.variant ?? "primary");
+  const effDisabled = $derived(disabled || !!grp?.disabled);
+
   const trackMap: Record<Size, string> = { sm: "h-4 w-7", md: "h-5 w-9", lg: "h-6 w-11" };
   const knobMap: Record<Size, string> = { sm: "size-3", md: "size-4", lg: "size-5" };
   const onMap: Record<Size, string> = {
@@ -63,72 +59,70 @@
     lg: "translateX(20px)",
   };
   const heightMap: Record<Size, string> = { sm: "h-6", md: "h-8", lg: "h-10" };
+  const textMap: Record<Size, string> = { sm: "text-xs", md: "text-sm", lg: "text-base" };
 
-  const trackCls = $derived(responsiveClasses(size, trackMap));
-  const knobCls = $derived(responsiveClasses(size, knobMap));
-  // Wrapper height = the standard control height for this size (matches Input's h-6/h-8/h-10), so the
-  // switch centres on the same baseline as sibling inputs without growing the switch itself.
-  const heightClass = $derived(responsiveClasses(size, heightMap));
+  const trackCls = $derived(responsiveClasses(effSize, trackMap));
+  const knobCls = $derived(responsiveClasses(effSize, knobMap));
+  const heightClass = $derived(responsiveClasses(effSize, heightMap));
+  const labelText = $derived(responsiveClasses(effSize, textMap));
   const trackStyle = $derived(
-    `background-color: ${checked ? `var(${variantToken[variant]})` : "color-mix(in srgb, var(--ui-color-text) 22%, transparent)"}`,
+    `background-color: ${checked ? `var(${variantToken[effVariant]})` : "color-mix(in srgb, var(--ui-color-text) 22%, transparent)"}`,
   );
-  // Knob colour = the INVERTED text colour (`--ui-color-background`) with a hint of the variant mixed
-  // in — ONE rule for every variant, both themes. Light: background is white → a near-white knob (as
-  // before). Dark: background is dark → the knob flips dark, and since the dark theme's accent fills
-  // are brighter, a dark knob still reads. The 20% variant tint keeps the knob on-theme; it never
-  // approaches the track colour (80% background), so it stays contrasting even on a neutral track.
   const knobColor = $derived(
-    `color-mix(in srgb, var(--ui-color-background) 80%, var(${variantToken[variant]}))`,
+    `color-mix(in srgb, var(--ui-color-background) 80%, var(${variantToken[effVariant]}))`,
   );
   const knobStyle = $derived(
-    `transform: ${checked ? onMap[resolveScalar(size, "md")] : "translateX(2px)"}; background-color: ${knobColor}`,
+    `transform: ${checked ? onMap[resolveScalar(effSize, "md")] : "translateX(2px)"}; background-color: ${knobColor}`,
   );
 
-  // Field chrome wiring.
   const generatedId = nextFieldId();
   const controlId = $derived(id ?? generatedId);
   const isSnippet = (v: unknown): v is Snippet => typeof v === "function";
   const hasError = $derived(isSnippet(error) ? true : !!(error && String(error).trim()));
   const hasDesc = $derived(isSnippet(description) ? true : !!(description && String(description).trim()));
-  const hasChrome = $derived(!!label || !!aside || hasError || hasDesc);
+  const hasChrome = $derived(!inGroup && (!!label || !!aside || hasError || hasDesc));
+  const showInlineLabel = $derived((inGroup || !hasChrome) && !!label);
 </script>
 
-{#snippet controlMarkup(cid: string | undefined, describedBy: string | undefined)}
+{#snippet switchControl(cid: string | undefined, describedBy: string | undefined)}
+  <input
+    type="checkbox"
+    bind:checked
+    disabled={effDisabled}
+    {required}
+    id={cid}
+    aria-describedby={describedBy}
+    aria-invalid={hasError || undefined}
+    class="peer absolute inset-0 z-10 m-0 cursor-pointer opacity-0 disabled:cursor-not-allowed"
+    {...rest}
+  />
+  <span
+    class="relative inline-flex items-center rounded-full transition-colors duration-150 peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:[outline-color:var(--ui-color-primary)] {trackCls}"
+    style={trackStyle}
+  >
+    <span class="inline-block rounded-full shadow transition-transform duration-150 {knobCls}" style={knobStyle}></span>
+  </span>
+{/snippet}
+
+{#snippet wrap(cid: string | undefined, describedBy: string | undefined, extra: string)}
   <label
-    class="relative inline-flex shrink-0 items-center {heightClass} {disabled
+    class="relative inline-flex shrink-0 items-center {showInlineLabel
+      ? 'gap-2'
+      : ''} {heightClass} {effDisabled
       ? 'cursor-not-allowed opacity-50'
-      : 'cursor-pointer'} {hasChrome ? 'self-start' : cls}"
+      : 'cursor-pointer'} {extra}"
   >
-    <!-- Real checkbox, invisible but covering the whole control so a click anywhere toggles it. -->
-    <input
-      type="checkbox"
-      bind:checked
-      {disabled}
-      {required}
-      id={cid}
-      aria-describedby={describedBy}
-      aria-invalid={hasError || undefined}
-      class="peer absolute inset-0 z-10 m-0 cursor-pointer opacity-0 disabled:cursor-not-allowed"
-      {...rest}
-    />
-    <span
-      class="relative inline-flex items-center rounded-full transition-colors duration-150 peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:[outline-color:var(--ui-color-primary)] {trackCls}"
-      style={trackStyle}
-    >
-      <span
-        class="inline-block rounded-full shadow transition-transform duration-150 {knobCls}"
-        style={knobStyle}
-      ></span>
-    </span>
+    {@render switchControl(cid, describedBy)}
+    {#if showInlineLabel}<span class="{labelText} [color:var(--ui-color-text)]">{label}</span>{/if}
   </label>
 {/snippet}
 
 {#if hasChrome}
-  <FieldChrome {label} {aside} {error} {description} required={!!required} {controlId} {size} class={cls}>
+  <FieldChrome {label} {aside} {error} {description} required={!!required} {controlId} size={effSize} class={cls}>
     {#snippet control({ describedBy })}
-      {@render controlMarkup(controlId, describedBy)}
+      {@render wrap(controlId, describedBy, "self-start")}
     {/snippet}
   </FieldChrome>
 {:else}
-  {@render controlMarkup(undefined, undefined)}
+  {@render wrap(controlId, undefined, cls)}
 {/if}

package/dist/components/Toggle.svelte.d.ts

@@ -7,10 +7,10 @@ type $$ComponentProps = {
     checked?: boolean;
     disabled?: boolean;
     size?: Responsive<Size>;
-    /** The colour of the "on" state (default primary). */
+    /** The colour of the "on" state (default primary; inherits the group's variant if unset). */
     variant?: Variant;
     class?: string;
-    /** Field chrome (see FieldChrome.spec.md). Label renders ABOVE. */
+    /** Field chrome. Inline (right of the switch) in a FieldGroup; above when standalone. */
     label?: string | null;
     aside?: Snippet;
     error?: string | Snippet | null;

package/dist/components/field-group.d.ts

@@ -0,0 +1,17 @@
+import type { Size } from "../types/sizes.js";
+import type { Variant } from "../types/variants.js";
+import type { Responsive } from "../types/responsive.js";
+export interface FieldGroupContext {
+    /** Present ⇒ the item is inside a group and renders its label inline (right of the control). */
+    inGroup: true;
+    orientation: "vertical" | "horizontal";
+    size?: Responsive<Size>;
+    variant?: Variant;
+    disabled?: boolean;
+    /** RadioGroup only — the shared radio-group name + controlled value. */
+    name?: string;
+    getValue?: () => string | number | undefined;
+    select?: (v: string | number) => void;
+}
+export declare function setFieldGroup(ctx: FieldGroupContext): void;
+export declare function getFieldGroup(): FieldGroupContext | undefined;

package/dist/components/field-group.js

@@ -0,0 +1,14 @@
+/**
+ * Shared context for grouped fields (`RadioGroup`, `FieldGroup`). A grouped item (Radio, Checkbox,
+ * Toggle) reads this to (a) switch its `label` from the standalone "above" layout to the conventional
+ * dot/box + label-to-the-right, and (b) inherit the group's `size`/`variant`. `RadioGroup` also shares
+ * the radio-group value + `name` so a child `<Radio>` needs no `bind:group`.
+ */
+import { getContext, setContext } from "svelte";
+const KEY = Symbol("svelte-ui-field-group");
+export function setFieldGroup(ctx) {
+    setContext(KEY, ctx);
+}
+export function getFieldGroup() {
+    return getContext(KEY);
+}

package/dist/index.d.ts

@@ -33,6 +33,8 @@ export { default as Popup } from "./components/Popup.svelte";
 export { default as Menu } from "./components/Menu.svelte";
 export { default as Checkbox } from "./components/Checkbox.svelte";
 export { default as Toggle } from "./components/Toggle.svelte";
+export { default as Radio } from "./components/Radio.svelte";
+export { default as FieldGroup } from "./components/FieldGroup.svelte";
 export { default as SideBarMenu } from "./components/SideBarMenu/SideBarMenu.svelte";
 export type { SideBarMenuItem, SideBarMenuBadge, SideBarMenuBadgeVariant, } from "./components/SideBarMenu/SideBarMenu.svelte";
 export { default as TabStrip } from "./components/TabStrip/TabStrip.svelte";

package/dist/index.js

@@ -38,6 +38,8 @@ export { default as Popup } from "./components/Popup.svelte";
 export { default as Menu } from "./components/Menu.svelte";
 export { default as Checkbox } from "./components/Checkbox.svelte";
 export { default as Toggle } from "./components/Toggle.svelte";
+export { default as Radio } from "./components/Radio.svelte";
+export { default as FieldGroup } from "./components/FieldGroup.svelte";
 // Navigation Components
 export { default as SideBarMenu } from "./components/SideBarMenu/SideBarMenu.svelte";
 export { default as TabStrip } from "./components/TabStrip/TabStrip.svelte";

package/docs/components.md

@@ -99,12 +99,40 @@ Multi-line text input with optional auto-resize.
 
 ### Checkbox
 
-Small themed checkbox (native control tinted via `accent-color`).
+Small themed checkbox (invisible native control over a themed box; multi-state).
 
 - **Location**: `src/lib/components/Checkbox.svelte`
-- **Axes**: `size`
+- **Axes**: `size`, `variant` + field chrome (see "Field chrome (shared)")
 - **Props**: `checked` (bindable), `indeterminate`, `disabled`, plus native input attributes
 
+### Toggle
+
+Sliding on/off switch (invisible native checkbox over a themed track/knob).
+
+- **Location**: `src/lib/components/Toggle.svelte`
+- **Axes**: `size`, `variant` + field chrome
+- **Props**: `checked` (bindable), `disabled`, plus native input attributes
+
+### Radio
+
+Themed single-select control mirroring Checkbox/Toggle (invisible `<input type=radio>`).
+
+- **Location**: `src/lib/components/Radio.svelte`
+- **Axes**: `size`, `variant` + field chrome
+- **Props**: `value` (this radio's value), `group` (bindable — standalone `bind:group`), `label`,
+  `disabled`, `name`. Inside a `FieldGroup` the label renders inline (right of the dot) and the shared
+  `name`/value come from group context (no `bind:group` needed).
+
+### FieldGroup
+
+One wrapper for a set of Radios, Checkboxes, or Toggles under a shared legend (a `<fieldset>`).
+
+- **Location**: `src/lib/components/FieldGroup.svelte`
+- **Props**: `label` (legend), `aside`, `description`, `error`, `required` (the shared field-chrome
+  vocabulary), `orientation` (`'vertical'` default | `'horizontal'`), `size`, `variant`, `disabled`
+  (propagate to children), and for radio groups `value` (bindable) + `name`. Children render their
+  label inline; radios auto-share the group value/name via context.
+
 ### Rating
 
 Read-only star-rating display (5-star, from a 10-point average).

package/docs/usage.md

@@ -116,6 +116,31 @@ Every field-shaped component renders its own label + help/error frame — don't
 `validate` (on `Input`/`TextArea`) is separate — it shows the **native** validity tooltip on submit;
 the `error` prop is the inline row. Both flip the error border.
 
+### Radio & groups
+
+`FieldGroup` wraps a set of Radios, Checkboxes, or Toggles under one legend; items render their label
+inline. For radios, bind the group `value` — children need no `bind:group`.
+
+```svelte
+<script>
+  import { FieldGroup, Radio, Checkbox } from "@spaethtech/svelte-ui";
+  let method = $state("email");
+  let caps = $state({ webhook: true, script: false });
+</script>
+
+<FieldGroup label="Delivery method" bind:value={method} name="method"
+            description="How you'll get updates.">
+  <Radio value="email" label="Email" />
+  <Radio value="sms" label="SMS" />
+  <Radio value="push" label="Push notification" />
+</FieldGroup>
+
+<FieldGroup label="Capabilities" orientation="horizontal">
+  <Checkbox label="Webhook triggers" bind:checked={caps.webhook} />
+  <Checkbox label="Script actions" bind:checked={caps.script} />
+</FieldGroup>
+```
+
 ### Button
 
 ```svelte

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.4.1-dev.21.2ccc703",
+  "version": "0.4.1-dev.23.372ce0b",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"