highsoft-ui 1.0.171 → 1.0.172

package/CLAUDE.md

@@ -222,6 +222,89 @@ const viewItems: ButtonGroupItem[] = [
 - In select mode each item exposes `aria-pressed` for its selected state; with `selectable={false}` the attribute is omitted entirely, so AT hears plain buttons, not toggles stuck "off".
 - Items are real `Button`s: native `disabled` semantics, brand `:focus-visible` ring, and a transform-only transition on the design tokens that respects `prefers-reduced-motion`. Icon-only items need `buttonProps={{ 'aria-label': … }}` — the icon alone names nothing.
 
+### Toggle
+On/off switch for settings that apply immediately. Sizes, label type and disabled treatment match `Button`.
+```tsx
+<Toggle label="Email notifications" checked={on} onChange={setOn} />
+<Toggle label="Animation" defaultChecked size={300} />
+
+// Settings row: label left, switch on the far edge, description under the label
+<Toggle fullWidth labelPosition="left" label="Credits"
+        description="Show the Highcharts.com credit in the chart corner." />
+
+// No visible label — the surrounding UI names it
+<Toggle aria-label="Show grid lines" />
+
+// In a form: submits name=value while on, nothing while off (like a checkbox)
+<Toggle label="Subscribe" name="subscribe" value="yes" />
+```
+- **`checked` / `defaultChecked` / `onChange(checked)`:** controlled or uncontrolled
+- **`size`:** `50`–`500` (default `200`) — the row is as tall as a Button of the same size and the label uses the same type, so a Toggle lines up next to Buttons; the track scales with it (18×32 at 200)
+- **`variant`:** `brand` (default) | `success` | `attention` | `danger` — the on-track colour, from the Button tokens of the same name. Keep `brand` for ordinary settings; use a status colour only when the on state itself means something (`danger` for "Maintenance mode"), and say it in the label — colour alone conveys nothing. **Exception:** light-mode `attention` uses `--primitives-attention-600` (hover 700), because the attention Button fill (attention-500) is only 2.15:1 against white, under WCAG 1.4.11's 3:1; dark follows the Button tokens.
+- **`label`**, **`description`**, **`labelPosition`** (`right` default | `left`), **`fullWidth`** (the label fills the row so the switch sits on the far edge)
+- **`name` / `value`** (default `'on'`) for native form submission; **`disabled`**; other props and the ref go to the `<button>`
+- Off track is `--HS-text-tertiary-default`, on is the brand button background; disabled uses the Button disabled neutrals for both states, so on/off differ by thumb position only. Like `ButtonGroup`, **colours are not transitioned** — only the thumb's `transform`/`width` (bounce-fast) and the focus ring animate.
+- Use a Toggle for an instant on/off setting; use `Checkbox` when the choice is submitted later or is one of several. For a bordered card where the whole card is the target, use `ToggleCard`.
+- The track and text block carry global `hsui-toggle__track` / `hsui-toggle__text` classes so a wrapper (ToggleCard, app CSS) can style it; the module classes are hashed.
+- **Disabled** is one neutral treatment for every variant (on/off differ by thumb position only). Light uses the disabled Button surface (neutral-300 track, white thumb). Dark has its own set — neutral-700 track with no edge (same shape as every other state; on background-100 it fades out and the thumb carries the state), neutral-500 thumb — because the Button's disabled text colour (neutral-400) made the thumb brighter than an *enabled* off thumb, and its neutral-1000 stroke drew a heavy black ring. Disabled controls are exempt from WCAG 1.4.11; the aim is recessive but recognisable.
+
+**Accessibility:**
+- A real `<button type="button" role="switch" aria-checked>`: Space and Enter flip it, it's in the tab order, and AT announces "Email notifications, switch, on". Disabled uses the native `disabled` attribute.
+- The visible `label` is a `<label for>` the button **and** its `aria-labelledby`, so the name is exactly the visible text (WCAG 2.5.3). The **whole text block** is a click target: label, description, and in a `fullWidth` row the free space up to the switch. A click outside the `<label>` is forwarded to the button with `.click()`; links or other controls inside the description keep their own click and don't toggle. Padding you put *around* a Toggle is not a target — if the whole row/card should be, use `ToggleCard`. Without `label`, pass `aria-label`. `description` is wired via `aria-describedby` (merged with any you pass).
+- State never rests on colour: the thumb position changes, and the off track (`--HS-text-tertiary-default`) clears 3:1 against every surface in both themes (WCAG 1.4.11).
+- `:focus-visible` draws the Button's two-tone ring (background gap + brand) around the pill; `data-hs-pointer-focus` suppresses it like on Button. The thumb is `aria-hidden`.
+- On touch (`pointer: coarse`) sizes 50/100 get an invisible hit area at least 24px tall (WCAG 2.5.8); the label is a click target at every size.
+- Under `prefers-reduced-motion: reduce` the thumb jumps instead of sliding.
+
+### ToggleCard
+A **switch card**: a bordered card around a `Toggle` where a click or tap anywhere on the card flips the switch. It wraps `Toggle`, so it takes the same props (`label`, `description`, `checked`/`defaultChecked`/`onChange`, `size`, `name`/`value`, `disabled`; the ref goes to the switch `<button>`).
+```tsx
+<ToggleCard label="Credits" description="Show the Highcharts.com credit." defaultChecked />
+
+// On a tinted surface, or next to transparent Buttons
+<ToggleCard transparent label="Animation" />
+
+// Status colour: only when "on" itself means something
+<ToggleCard variant="danger" label="Maintenance mode" description="The public site shows a maintenance page." />
+```
+- **`variant`:** `brand` (default) | `success` | `attention` | `danger` — passed to the Toggle, and colours the card's on state to match
+- **`transparent`:** no fill, the transparent Button's background + hairline tokens (the same chrome as ButtonGroup `transparent`); default is a background-0 card. A boolean rather than a variant, because `variant` is the colour.
+- **`labelPosition`** defaults to `left` (text left, switch on the right edge); the card is always full width. **`size`** `50`–`500` also scales the card padding (12/16px at 200).
+- Same resting stroke and corner as the other form controls (1px border-200, 8px), 2px on hover, 2px brand stroke when on. The default card adds a tint of the variant colour when on; `transparent` keeps no fill. Disabled keeps the card's own surface with a border-100 edge and muted text, on or off — not a background-50 fill, which in dark (neutral-800) is lighter than an enabled card and made the disabled one stand out most. Stroke changes are not transitioned (theme flips would fade).
+- **The on-state colours are primitives, as the component's own light/dark pair per variant** (`--toggle-card-background-checked`, `--toggle-card-stroke-checked[-hover]`, remapped under `[data-theme='dark']` like ButtonGroup's container tokens); the Toggle inside keeps the semantic Button tokens. Light: a `-50` wash, stroke matching the track. Dark: the darkest wash that still clears 3:1 against the 600 track — `-1000`, danger `-1100` (danger-1000 is 2.96:1) — stroke a step lighter than the track. Don't swap in `--HS-surface-brand-background-50`: it remaps to brand-600 in dark, the track's own fill, and the switch disappears into the card. `.card.transparent` is written at that specificity on purpose so it outranks the dark blocks.
+
+**Accessibility:**
+- **Hover previews, it never toggles.** Hovering highlights the card and the track; only a click, tap, Space or Enter changes the state — a setting that flips as the pointer passes over it fails WCAG 3.2.1/3.2.2 and doesn't exist on touch.
+- The card is a click target, not a second control: the `<button role="switch">` inside is the only focusable element, so AT hears one switch with the Toggle's name and description. The Toggle handles clicks on the switch and its text block (`.hsui-toggle__text`); the card forwards only the rest — its padding — so a description click never double-toggles.
+- The focus ring moves from the pill to the card edge (`:has(:focus-visible)`), since the card is what you click.
+
+### ToggleList
+A settings list: `ToggleCard` rows in one frame with hairline dividers, each a whole-row click target.
+```tsx
+<ToggleList aria-label="Chart options">
+  <ToggleCard label="Credits" description="Show the Highcharts.com credit…" defaultChecked />
+  <ToggleCard label="Animation" description="Animate series on first render…" />
+</ToggleList>
+
+// Named by a visible heading
+<Heading level={3} id="notif">Notifications</Heading>
+<ToggleList aria-labelledby="notif">…</ToggleList>
+
+// List-wide defaults; a row's own prop wins
+<ToggleList aria-label="Site status" size={300} transparent>
+  <ToggleCard label="Public search" />
+  <ToggleCard variant="danger" label="Maintenance mode" />
+</ToggleList>
+```
+- **Rows are `ToggleCard`s** — no separate row component. Inside a list a card picks up `size` / `variant` / `transparent` from the list (via `ToggleListContext`, in `ToggleList/context.ts` so ToggleCard can import it without a cycle) and its own prop overrides.
+- **Frame:** 1px border-200, 8px corners (like `FormGroup`), border-200 hairlines between rows; `transparent` uses the transparent Button's background + stroke. The list clips rows to its corners.
+- **Rows in a list differ from standalone cards:** no own stroke or corners; hover is a `--HS-surface-ui-background-50` wash (`transparent`: the transparent Button hover) rather than the 2px stroke, which would jitter between stacked rows; **no on-state tint** — the switch carries the state, a mostly-on list would otherwise become one tinted block, and a checked row's hover would vanish under its own tint; disabled rows stay on the list surface.
+
+**Accessibility:**
+- The list is a `role="group"` — always name it with `aria-label` or `aria-labelledby`, so AT announces "Chart options, group" before the switches. Each row is still one `role="switch"` named by its label and described by its description.
+- Every row is a whole-row click target (padding, description, label, switch), forwarded to the switch with `.click()`; links in a description navigate without toggling; disabled rows ignore clicks and leave the tab order.
+- Keyboard focus draws a 2px inset brand ring around the row — inset because the list clips anything outside it. Hover is pointer-only polish (WCAG doesn't require it); nothing depends on it.
+
 ### Heading
 ```tsx
 <Heading level={1}>Page title</Heading>

package/dist/Toggle-BHjptO7-.js

@@ -0,0 +1,88 @@
+"use client";
+import { t as e } from "./clsx-BWCAbrjV.js";
+import { forwardRef as t, useCallback as n, useId as r, useRef as i, useState as a } from "react";
+import { jsx as o, jsxs as s } from "react/jsx-runtime";
+var c = {
+	attention: "JOLtuG_attention",
+	brand: "JOLtuG_brand",
+	checked: "JOLtuG_checked",
+	danger: "JOLtuG_danger",
+	description: "JOLtuG_description",
+	disabled: "JOLtuG_disabled",
+	full: "JOLtuG_full",
+	label: "JOLtuG_label",
+	labelLeft: "JOLtuG_labelLeft",
+	"size-100": "JOLtuG_size-100",
+	"size-200": "JOLtuG_size-200",
+	"size-300": "JOLtuG_size-300",
+	"size-400": "JOLtuG_size-400",
+	"size-50": "JOLtuG_size-50",
+	"size-500": "JOLtuG_size-500",
+	success: "JOLtuG_success",
+	text: "JOLtuG_text",
+	thumb: "JOLtuG_thumb",
+	toggle: "JOLtuG_toggle",
+	track: "JOLtuG_track",
+	withDescription: "JOLtuG_withDescription"
+}, l = t(function({ label: t, description: l, checked: u, defaultChecked: d = !1, onChange: f, size: p = 200, variant: m = "brand", labelPosition: h = "right", fullWidth: g = !1, name: _, value: v = "on", disabled: y = !1, id: b, className: x, style: S, onClick: C, "aria-describedby": w, ...T }, E) {
+	let D = i(null), O = n((e) => {
+		D.current = e, typeof E == "function" ? E(e) : E && (E.current = e);
+	}, [E]), k = r(), A = b ?? `hsui-toggle-${k}`, j = `${A}-label`, M = `${A}-description`, [N, P] = a(d), F = u !== void 0, I = F ? u : N, L = (e) => {
+		if (C?.(e), e.defaultPrevented || y) return;
+		let t = !I;
+		F || P(t), f?.(t);
+	}, R = (e) => {
+		let t = D.current;
+		y || !t || e.target.closest("label, a, button, input, select, textarea") || t.click();
+	}, z = [l == null ? null : M, w].filter(Boolean).join(" ") || void 0, B = t != null || l != null;
+	return /* @__PURE__ */ s("span", {
+		className: e("hsui-toggle", c.toggle, c[`size-${p}`], c[m], {
+			[c.checked]: I,
+			[c.disabled]: y,
+			[c.labelLeft]: h === "left",
+			[c.full]: g,
+			[c.withDescription]: l != null
+		}, x),
+		style: S,
+		children: [
+			/* @__PURE__ */ o("button", {
+				ref: O,
+				id: A,
+				type: "button",
+				role: "switch",
+				"aria-checked": I,
+				"aria-labelledby": t == null ? void 0 : j,
+				"aria-describedby": z,
+				disabled: y,
+				className: e("hsui-toggle__track", c.track),
+				onClick: L,
+				...T,
+				children: /* @__PURE__ */ o("span", {
+					className: c.thumb,
+					"aria-hidden": "true"
+				})
+			}),
+			B && /* @__PURE__ */ s("span", {
+				className: e("hsui-toggle__text", c.text),
+				onClick: R,
+				children: [t != null && /* @__PURE__ */ o("label", {
+					id: j,
+					htmlFor: A,
+					className: c.label,
+					children: t
+				}), l != null && /* @__PURE__ */ o("span", {
+					id: M,
+					className: c.description,
+					children: l
+				})]
+			}),
+			_ && I && !y && /* @__PURE__ */ o("input", {
+				type: "hidden",
+				name: _,
+				value: v
+			})
+		]
+	});
+});
+//#endregion
+export { l as t };

package/dist/ToggleCard-kMpxzTnh.js

@@ -0,0 +1,57 @@
+"use client";
+import { t as e } from "./clsx-BWCAbrjV.js";
+import { t } from "./Toggle-BHjptO7-.js";
+import { useToggleList as n } from "./components/ToggleList/context.js";
+import { forwardRef as r, useCallback as i, useRef as a, useState as o } from "react";
+import { jsx as s } from "react/jsx-runtime";
+var c = {
+	attention: "AlVaOW_attention",
+	brand: "AlVaOW_brand",
+	card: "AlVaOW_card",
+	checked: "AlVaOW_checked",
+	danger: "AlVaOW_danger",
+	disabled: "AlVaOW_disabled",
+	inList: "AlVaOW_inList",
+	"size-100": "AlVaOW_size-100",
+	"size-200": "AlVaOW_size-200",
+	"size-300": "AlVaOW_size-300",
+	"size-400": "AlVaOW_size-400",
+	"size-50": "AlVaOW_size-50",
+	"size-500": "AlVaOW_size-500",
+	success: "AlVaOW_success",
+	transparent: "AlVaOW_transparent"
+}, l = r(function({ checked: r, defaultChecked: l = !1, onChange: u, size: d, labelPosition: f = "left", disabled: p = !1, variant: m, transparent: h, className: g, style: _, ...v }, y) {
+	let b = n(), x = b !== null, S = d ?? b?.size ?? 200, C = m ?? b?.variant ?? "brand", w = h ?? b?.transparent ?? !1, [T, E] = o(l), D = r !== void 0, O = D ? r : T, k = i((e) => {
+		D || E(e), u?.(e);
+	}, [D, u]), A = a(null), j = i((e) => {
+		A.current = e, typeof y == "function" ? y(e) : y && (y.current = e);
+	}, [y]), M = (e) => {
+		let t = A.current;
+		if (p || !t) return;
+		let n = e.target;
+		t.contains(n) || n.closest(".hsui-toggle__text") || t.click();
+	};
+	return /* @__PURE__ */ s("div", {
+		className: e("hsui-toggle-card", c.card, c[`size-${S}`], {
+			[c.checked]: O,
+			[c.disabled]: p,
+			[c.transparent]: w,
+			[c.inList]: x
+		}, c[C], g),
+		style: _,
+		onClick: M,
+		children: /* @__PURE__ */ s(t, {
+			...v,
+			ref: j,
+			checked: O,
+			onChange: k,
+			size: S,
+			labelPosition: f,
+			disabled: p,
+			variant: C,
+			fullWidth: !0
+		})
+	});
+});
+//#endregion
+export { l as t };

package/dist/ToggleList-Dh7wb2-W.js

@@ -0,0 +1,31 @@
+"use client";
+import { t as e } from "./clsx-BWCAbrjV.js";
+import { ToggleListContext as t } from "./components/ToggleList/context.js";
+import { forwardRef as n, useMemo as r } from "react";
+import { jsx as i } from "react/jsx-runtime";
+var a = {
+	list: "IfOx9W_list",
+	transparent: "IfOx9W_transparent"
+}, o = n(function({ children: n, size: o, variant: s, transparent: c = !1, className: l, ...u }, d) {
+	let f = r(() => ({
+		size: o,
+		variant: s,
+		transparent: c
+	}), [
+		o,
+		s,
+		c
+	]);
+	return /* @__PURE__ */ i(t.Provider, {
+		value: f,
+		children: /* @__PURE__ */ i("div", {
+			ref: d,
+			role: "group",
+			className: e("hsui-toggle-list", a.list, { [a.transparent]: c }, l),
+			...u,
+			children: n
+		})
+	});
+});
+//#endregion
+export { o as t };

package/dist/components/Toggle/index.js

@@ -0,0 +1,2 @@
+import { t as e } from "../../Toggle-BHjptO7-.js";
+export { e as Toggle };

package/dist/components/ToggleCard/index.js

@@ -0,0 +1,2 @@
+import { t as e } from "../../ToggleCard-kMpxzTnh.js";
+export { e as ToggleCard };

package/dist/components/ToggleList/context.js

@@ -0,0 +1,6 @@
+"use client";
+import { createContext as e, useContext as t } from "react";
+//#region lib/components/ToggleList/context.ts
+var n = e(null), r = () => t(n);
+//#endregion
+export { n as ToggleListContext, r as useToggleList };

package/dist/components/ToggleList/index.js

@@ -0,0 +1,2 @@
+import { t as e } from "../../ToggleList-Dh7wb2-W.js";
+export { e as ToggleList };