@marianmeres/stuic 3.164.0 → 3.166.0

package/API.md

@@ -582,11 +582,13 @@ Closeable message banner with intent styling.
 
 #### `Progress`
 
-Progress bar.
+Progress bar or circle.
 
-| Prop    | Type     | Default | Description              |
-| ------- | -------- | ------- | ------------------------ |
-| `value` | `number` | `0`     | Current progress (0-100) |
+| Prop       | Type                | Default | Description                       |
+| ---------- | ------------------- | ------- | --------------------------------- |
+| `progress` | `number`            | `0`     | Current progress (0-100, clamped) |
+| `type`     | `"bar" \| "circle"` | `"bar"` | Rendering variant                 |
+| `classBar` | `string`            | -       | Classes for the inner fill (bar)  |
 
 #### `Spinner`
 
@@ -1206,12 +1208,26 @@ Responsive wrapper around Book that intelligently switches between book mode (du
 
 #### `Circle`
 
-SVG-based circular progress indicator with configurable stroke width and rotation.
+SVG-based circular progress indicator (a Svelte wrapper around the [`svgCircle`](#svgcircleoptions)
+utility). The svg fills its container over a fixed `100x100` viewBox, so the container
+sets the size and `strokeWidth` is in viewBox units. The stroke is `currentColor`.
+
+| Prop                    | Type      | Default | Description                                                      |
+| ----------------------- | --------- | ------- | ---------------------------------------------------------------- |
+| `completeness`          | `number`  | `1`     | Progress from 0 to 1 (clamped)                                   |
+| `strokeWidth`           | `number`  | `10`    | Stroke width in viewBox units (radius = `50 - strokeWidth / 2`)  |
+| `strokeWidthRatio`      | `number`  | `0`     | Caps `strokeWidth` at this fraction of the radius (`0` = no cap) |
+| `bgStrokeColor`         | `string`  | -       | CSS color of the background ring behind the arc                  |
+| `roundedEdges`          | `boolean` | `true`  | Rounded (vs butt) stroke line caps                               |
+| `rotate`                | `number`  | `0`     | Rotation in degrees (arc starts at 3 o'clock; `-90` = top)       |
+| `animateCompletenessMs` | `number`  | `0`     | CSS transition duration on `stroke-dashoffset` (ms)              |
+| `class` / `style`       | `string`  | -       | Container div class / inline style                               |
+| `circleClass`           | `string`  | -       | Classes for the `<svg>` element                                  |
+| `circleStyle`           | `string`  | -       | Inline styles for the `<circle>` element                         |
 
-| Prop          | Type     | Default | Description            |
-| ------------- | -------- | ------- | ---------------------- |
-| `value`       | `number` | `0`     | Progress value (0-100) |
-| `strokeWidth` | `number` | `8`     | Stroke width           |
+```svelte
+<Circle completeness={0.75} rotate={-90} bgStrokeColor="#e5e5e5" class="size-16" />
+```
 
 #### `H`
 
@@ -1935,9 +1951,48 @@ Generate deterministic avatar colors from a name string.
 
 HSL color generation.
 
-#### `svgCircle(radius, strokeWidth)`
+#### `svgCircle(options?)`
+
+Build an SVG ring as a plain DOM node, with setters to update it in place. Framework
+agnostic - it returns the element, mounting it is up to the caller. Used by `Circle` and
+`Progress` internally.
+
+The svg is `width/height: 100%` over a fixed `100x100` viewBox, so the container decides
+the rendered size; `strokeWidth` is in viewBox units and the radius is derived from it
+(`50 - strokeWidth / 2`).
+
+**Options** (all optional):
+
+| Option             | Type      | Default | Description                                                      |
+| ------------------ | --------- | ------- | ---------------------------------------------------------------- |
+| `completeness`     | `number`  | `1`     | Arc length from 0 to 1 (clamped)                                 |
+| `strokeWidth`      | `number`  | `10`    | Stroke width in viewBox units                                    |
+| `strokeWidthRatio` | `number`  | `0`     | Caps `strokeWidth` at this fraction of the radius (`0` = no cap) |
+| `rotate`           | `number`  | `0`     | Rotation in degrees, modulo 360 (arc starts at 3 o'clock)        |
+| `roundedEdges`     | `boolean` | `true`  | Rounded (vs butt) line caps                                      |
+| `bgStrokeColor`    | `string`  | -       | CSS color of a full background ring behind the arc               |
+| `class`            | `string`  | -       | Classes for the `<svg>` element                                  |
+| `circleStyle`      | `string`  | -       | Inline styles for the `<circle>` element                         |
+| `radius`           | `number`  | -       | Currently ignored (derived from the viewBox and stroke width)    |
 
-Generate SVG circle path data.
+**Returns:** `{ svg: SVGSVGElement, setCompleteness(v: number): void, setRotate(deg: number): void }`
+
+The setters mutate the existing element - reach for them instead of rebuilding when only
+the progress or rotation changes.
+
+```ts
+import { svgCircle } from "@marianmeres/stuic";
+
+const { svg, setCompleteness } = svgCircle({
+	completeness: 0.75,
+	strokeWidth: 8,
+	rotate: -90,
+	bgStrokeColor: "#e5e5e5",
+});
+container.appendChild(svg);
+
+setCompleteness(0.9); // no rebuild
+```
 
 #### `oscillate(min, max, step)`
 

package/dist/components/Circle/Circle.svelte

@@ -1,5 +1,24 @@
+<script lang="ts" module>
+	import type { SvgCircleOptions } from "../../utils/svg-circle.js";
+
+	export interface Props extends Partial<SvgCircleOptions> {
+		/** Inline styles for the container element */
+		style?: string;
+		/**
+		 * CSS classes for the `<svg>` element (forwarded to the helper's `class`
+		 * option). Since the stroke is `currentColor`, a text color utility here
+		 * colors the ring.
+		 */
+		circleClass?: string;
+		/** Inline styles for the `<circle>` element */
+		circleStyle?: string;
+		/** Transition duration in ms on the stroke-dashoffset */
+		animateCompletenessMs?: number;
+	}
+</script>
+
 <script lang="ts">
-	import { svgCircle, type SvgCircleOptions } from "../../utils/svg-circle.js";
+	import { svgCircle } from "../../utils/svg-circle.js";
 	import { twMerge } from "../../utils/tw-merge.js";
 
 	let {
@@ -14,13 +33,7 @@
 		circleClass,
 		circleStyle = "",
 		animateCompletenessMs = 0,
-	}: Partial<SvgCircleOptions> & {
-		style?: string;
-		circleClass?: string;
-		circleStyle?: string;
-		// transition duration in ms on the stroke-dashoffset
-		animateCompletenessMs?: number;
-	} = $props();
+	}: Props = $props();
 
 	let container: HTMLDivElement = $state()!;
 
@@ -42,10 +55,12 @@
 	);
 
 	$effect(() => {
-		container.appendChild(circle.svg);
-		return () => {
-			circle.svg.remove();
-		};
+		// Capture the current instance: `circle` is a derived, so reading it again in the
+		// teardown would resolve to the freshly rebuilt svg and leave the previous node
+		// behind (stacking one <svg> per structural prop change).
+		const { svg } = circle;
+		container.appendChild(svg);
+		return () => svg.remove();
 	});
 
 	$effect(() => {

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

@@ -1,10 +1,18 @@
-import { type SvgCircleOptions } from "../../utils/svg-circle.js";
-type $$ComponentProps = Partial<SvgCircleOptions> & {
+import type { SvgCircleOptions } from "../../utils/svg-circle.js";
+export interface Props extends Partial<SvgCircleOptions> {
+    /** Inline styles for the container element */
     style?: string;
+    /**
+     * CSS classes for the `<svg>` element (forwarded to the helper's `class`
+     * option). Since the stroke is `currentColor`, a text color utility here
+     * colors the ring.
+     */
     circleClass?: string;
+    /** Inline styles for the `<circle>` element */
     circleStyle?: string;
+    /** Transition duration in ms on the stroke-dashoffset */
     animateCompletenessMs?: number;
-};
-declare const Circle: import("svelte").Component<$$ComponentProps, {}, "">;
+}
+declare const Circle: import("svelte").Component<Props, {}, "">;
 type Circle = ReturnType<typeof Circle>;
 export default Circle;

package/dist/components/Circle/README.md

@@ -1,22 +1,31 @@
 # Circle
 
-An SVG circle progress indicator with configurable stroke, rotation, and animated transitions.
+An SVG circle progress indicator with configurable stroke, rotation, and animated
+transitions. A thin Svelte wrapper around the [`svgCircle`](../../utils/svg-circle.ts)
+utility.
+
+The svg is rendered at `width/height: 100%` over a fixed `100x100` viewBox, so **the
+container decides the size** (default `size-6`) and `strokeWidth` is expressed in viewBox
+units - i.e. it scales with the box. The stroke defaults to `currentColor`.
 
 ## Props
 
-| Prop                    | Type      | Default | Description                                   |
-| ----------------------- | --------- | ------- | --------------------------------------------- |
-| `completeness`          | `number`  | `1`     | Progress value from 0 to 1                    |
-| `strokeWidth`           | `number`  | `10`    | Stroke width in SVG units                     |
-| `bgStrokeColor`         | `string`  | -       | Background circle stroke color                |
-| `roundedEdges`          | `boolean` | `true`  | Use rounded stroke line caps                  |
-| `rotate`                | `number`  | `0`     | Rotation in degrees                           |
-| `strokeWidthRatio`      | `number`  | `0`     | Ratio for background stroke width             |
-| `animateCompletenessMs` | `number`  | `0`     | Transition duration for progress changes (ms) |
-| `class`                 | `string`  | -       | CSS for container div                         |
-| `style`                 | `string`  | -       | Inline styles for container                   |
-| `circleClass`           | `string`  | -       | CSS for SVG circle element                    |
-| `circleStyle`           | `string`  | -       | Inline styles for circle                      |
+| Prop                    | Type      | Default | Description                                                            |
+| ----------------------- | --------- | ------- | ---------------------------------------------------------------------- |
+| `completeness`          | `number`  | `1`     | Progress from 0 to 1 (clamped)                                         |
+| `strokeWidth`           | `number`  | `10`    | Stroke width in viewBox units (radius = `50 - strokeWidth / 2`)        |
+| `strokeWidthRatio`      | `number`  | `0`     | Caps `strokeWidth` at this fraction of the radius; `0` means no cap    |
+| `bgStrokeColor`         | `string`  | -       | Any CSS color; adds a full background ring behind the arc              |
+| `roundedEdges`          | `boolean` | `true`  | Rounded (vs butt) stroke line caps                                     |
+| `rotate`                | `number`  | `0`     | Rotation in degrees; the arc starts at 3 o'clock, so use `-90` for top |
+| `animateCompletenessMs` | `number`  | `0`     | CSS transition duration on `stroke-dashoffset` (ms)                    |
+| `class`                 | `string`  | -       | CSS classes for the container div                                      |
+| `style`                 | `string`  | -       | Inline styles for the container div                                    |
+| `circleClass`           | `string`  | -       | CSS classes for the `<svg>` element                                    |
+| `circleStyle`           | `string`  | -       | Inline styles for the `<circle>` element                               |
+
+`completeness` and `rotate` are applied through the helper's setters, so changing them
+only rewrites two attributes. Every other prop rebuilds the svg.
 
 ## Usage
 
@@ -24,17 +33,17 @@ An SVG circle progress indicator with configurable stroke, rotation, and animate
 
 ```svelte
 <script lang="ts">
-	import { Circle } from "stuic";
+	import { Circle } from "@marianmeres/stuic";
 </script>
 
-<Circle completeness={0.75} class="size-16" />
+<Circle completeness={0.75} rotate={-90} class="size-16" />
 ```
 
 ### Animated Progress
 
 ```svelte
 <script lang="ts">
-	import { Circle } from "stuic";
+	import { Circle } from "@marianmeres/stuic";
 
 	let progress = $state(0);
 
@@ -54,13 +63,40 @@ An SVG circle progress indicator with configurable stroke, rotation, and animate
 
 ### Custom Styling
 
+The ring's stroke is `currentColor`, so a text color on the container (or on the svg via
+`circleClass`) colors it. To set the stroke directly, use `circleStyle` - it lands on the
+`<circle>` element, which is the only place that beats the `stroke="currentColor"`
+presentation attribute.
+
 ```svelte
+<!-- via currentColor -->
 <Circle
 	completeness={0.5}
 	strokeWidth={8}
 	rotate={-90}
 	bgStrokeColor="rgba(0,0,0,0.1)"
+	class="size-24 text-blue-500"
+/>
+
+<!-- or explicitly on the circle element -->
+<Circle
+	completeness={0.5}
+	rotate={-90}
 	class="size-24"
-	circleClass="stroke-blue-500"
+	circleStyle="stroke: var(--stuic-color-primary);"
 />
 ```
+
+### Content Inside the Ring
+
+```svelte
+<div class="relative size-24">
+	<Circle
+		completeness={0.62}
+		rotate={-90}
+		bgStrokeColor="#e5e5e5"
+		class="absolute inset-0"
+	/>
+	<div class="absolute inset-0 flex items-center justify-center">62%</div>
+</div>
+```

package/dist/components/Circle/index.d.ts

@@ -0,0 +1 @@
+export { default as Circle, type Props as CircleProps } from "./Circle.svelte";

package/dist/components/Circle/index.js

@@ -0,0 +1 @@
+export { default as Circle } from "./Circle.svelte";

package/dist/components/FieldsBuilder/FieldsBuilder.svelte

@@ -420,11 +420,35 @@
 		syncToValue();
 	}
 
-	function setExtra(row: Row, key: string, checked: boolean) {
-		row.def.extras = { ...(row.def.extras ?? {}), [key]: checked };
+	// `undefined` REMOVES the key (and an emptied bag removes `extras` itself):
+	// "no value" must have exactly one representation downstream — a consumer
+	// reading `extras.unit` to decide whether to render a suffix should never
+	// have to special-case `""`, nor a `{}` that means nothing.
+	function setExtra(row: Row, key: string, value: unknown) {
+		const next = { ...(row.def.extras ?? {}) };
+		if (value === undefined) delete next[key];
+		else next[key] = value;
+		row.def.extras = Object.keys(next).length ? next : undefined;
 		syncToValue();
 	}
 
+	/** Display value of a string/select extra (a non-string is shown, not eaten). */
+	function extraText(row: Row, key: string): string {
+		const v = row.def.extras?.[key];
+		return v == null ? "" : String(v);
+	}
+
+	// while typing, the RAW value is stored (trimming here would fight the
+	// caret: a written-back trimmed value makes a trailing space untypable) —
+	// only the emptiness test is trimmed; `onchange` normalizes on commit
+	function onExtraStringInput(row: Row, key: string, raw: string) {
+		setExtra(row, key, raw.trim() ? raw : undefined);
+	}
+
+	function onExtraStringChange(row: Row, key: string, raw: string) {
+		setExtra(row, key, raw.trim() || undefined);
+	}
+
 	function typeChanged(row: Row): boolean {
 		return !!row.initialType && row.def.type !== row.initialType;
 	}
@@ -642,6 +666,8 @@
 						".fb-options .fb-option-value, .fb-options .fb-add-option-btn"
 					)
 					?.focus?.();
+			} else if (errs.extras) {
+				rowEls[row.rid]?.querySelector<HTMLElement>(".fb-extra-input")?.focus?.();
 			}
 		});
 	}
@@ -734,6 +760,7 @@
 							{@const showLabelError = !!(attempted && errs?.label)}
 							{@const showKeyError = !!(errs?.key && (attempted || row.keyEdited))}
 							{@const showOptionsError = !!(attempted && errs?.options)}
+							{@const showExtrasError = !!(attempted && errs?.extras)}
 							{@const canDrag =
 								!disabled && !row.deleted && !row.def.lock?.reorder && rows.length > 1}
 							<div
@@ -807,7 +834,7 @@
 												{getLocalizedText(entry.label, _defaultLanguage)}
 											</span>
 										{/if}
-										{#if (showLabelError || showKeyError || showOptionsError) && !row.deleted}
+										{#if (showLabelError || showKeyError || showOptionsError || showExtrasError) && !row.deleted}
 											<span class="fb-error-text shrink-0">
 												<span aria-hidden="true"
 													>{@html iconAlertWarning({ size: 14 })}</span
@@ -1035,36 +1062,120 @@
 											{/if}
 
 											{#if entry.extras?.length}
-												<div class="fb-field flex flex-col gap-1.5">
-													{#each entry.extras as ex (ex.key)}
-														<label
-															class="stuic-checkbox flex items-start gap-2 cursor-pointer"
-														>
-															<!--
-																Display the ACTUAL def value only (no `?? ex.default`
-																fallback): defaults are materialized into `extras` on
-																add/type-change, but a def loaded without the key must
-																not render checked while emitting nothing — the
-																checkbox must always match what `value` says.
-															-->
-															<input
-																type="checkbox"
-																checked={!!row.def.extras?.[ex.key]}
-																onchange={(e) =>
-																	setExtra(row, ex.key, e.currentTarget.checked)}
-																{disabled}
-																{tabindex}
-															/>
-															<span class="text-sm">
-																{getLocalizedText(ex.label, _defaultLanguage)}
+												<!--
+													Every arm displays the ACTUAL def value only (no
+													`?? ex.default` fallback): defaults are materialized into
+													`extras` on add/type-change, but a def loaded without the
+													key must not render as if it held the default while
+													emitting nothing — the control must always match what
+													`value` says.
+												-->
+												<div class="fb-extras fb-field flex flex-col gap-2.5">
+													{#each entry.extras as ex, exIdx (ex.key)}
+														{#if ex.type === "string" || ex.type === "select"}
+															{@const exId = `${id}-extra-${row.rid}-${exIdx}`}
+															{@const exValue = extraText(row, ex.key)}
+															<div class="fb-extra">
+																<label class="fb-sub-label" for={exId}>
+																	{getLocalizedText(ex.label, _defaultLanguage)}
+																</label>
+																{#if ex.type === "string"}
+																	<input
+																		id={exId}
+																		type="text"
+																		class={twMerge(INPUT_CLS, "fb-extra-input w-full")}
+																		value={exValue}
+																		maxlength={ex.maxlength}
+																		placeholder={getLocalizedText(
+																			ex.placeholder,
+																			_defaultLanguage
+																		) || undefined}
+																		oninput={(e) =>
+																			onExtraStringInput(
+																				row,
+																				ex.key,
+																				e.currentTarget.value
+																			)}
+																		onchange={(e) =>
+																			onExtraStringChange(
+																				row,
+																				ex.key,
+																				e.currentTarget.value
+																			)}
+																		{disabled}
+																		{tabindex}
+																		aria-invalid={showExtrasError || undefined}
+																		aria-describedby={showExtrasError
+																			? `${id}-extras-err-${row.rid}`
+																			: undefined}
+																	/>
+																{:else}
+																	<select
+																		id={exId}
+																		class={twMerge(INPUT_CLS, "fb-extra-input w-full")}
+																		value={exValue}
+																		onchange={(e) =>
+																			setExtra(
+																				row,
+																				ex.key,
+																				e.currentTarget.value || undefined
+																			)}
+																		{disabled}
+																		{tabindex}
+																	>
+																		<option value="">
+																			{getLocalizedText(ex.placeholder, _defaultLanguage)}
+																		</option>
+																		{#each ex.options as opt (opt.value)}
+																			<option value={opt.value}>
+																				{getLocalizedText(opt.label, _defaultLanguage)}
+																			</option>
+																		{/each}
+																		<!-- a stored value outside the declared list stays
+																		     visible and round-trips (same stance as an
+																		     unknown field type) -->
+																		{#if exValue && !ex.options.some((o) => o.value === exValue)}
+																			<option value={exValue}>{exValue}</option>
+																		{/if}
+																	</select>
+																{/if}
 																{#if ex.description}
-																	<span class="fb-hint block text-xs">
+																	<div class="fb-hint text-xs mt-0.5">
 																		{getLocalizedText(ex.description, _defaultLanguage)}
-																	</span>
+																	</div>
 																{/if}
-															</span>
-														</label>
+															</div>
+														{:else}
+															<label
+																class="stuic-checkbox fb-extra flex items-start gap-2 cursor-pointer"
+															>
+																<input
+																	type="checkbox"
+																	checked={!!row.def.extras?.[ex.key]}
+																	onchange={(e) =>
+																		setExtra(row, ex.key, e.currentTarget.checked)}
+																	{disabled}
+																	{tabindex}
+																/>
+																<span class="text-sm">
+																	{getLocalizedText(ex.label, _defaultLanguage)}
+																	{#if ex.description}
+																		<span class="fb-hint block text-xs">
+																			{getLocalizedText(ex.description, _defaultLanguage)}
+																		</span>
+																	{/if}
+																</span>
+															</label>
+														{/if}
 													{/each}
+													{#if showExtrasError}
+														<div
+															id="{id}-extras-err-{row.rid}"
+															class="fb-error-text text-sm"
+														>
+															{errs?.extras}
+														</div>
+													{/if}
 												</div>
 											{/if}
 

package/dist/components/FieldsBuilder/README.md

@@ -60,8 +60,9 @@ Value membership rules:
   **retained** on the def (switching back restores them); consumers compiling the list
   should ignore `options` on non-choice types.
 - Palette `extras` defaults are materialized into `def.extras` when a field is added
-  or its type changes; a def loaded _without_ an extra's key renders unchecked — the
-  checkbox always reflects what `value` actually contains, never a phantom default.
+  or its type changes; a def loaded _without_ an extra's key renders empty/unchecked —
+  the control always reflects what `value` actually contains, never a phantom default.
+  Extras are **retained** across a type change too (same rule as `options`).
 
 ## The palette
 
@@ -72,17 +73,69 @@ interface FieldTypeDef {
 	description?: LocalizedText;
 	icon?: string | Snippet; // html string or snippet, shown in the row's type chip
 	supportsOptions?: boolean; // renders the option editor
-	extras?: {
-		key: string;
-		label: LocalizedText;
-		description?: LocalizedText;
-		type: "boolean"; // v1: booleans only (a checkbox per extra)
-		default?: boolean;
-	}[];
+	extras?: FieldTypeExtraDef[]; // per-type controls, see below
 	preview?: Snippet<[FieldDef]>; // per-type preview of a single field
 }
 ```
 
+## Extras
+
+`extras` declares extra per-field controls, each stored under `FieldDef.extras[key]`.
+The component never interprets the values — it renders a control per declaration and
+round-trips whatever is there. Discriminated by `type`:
+
+```ts
+type FieldTypeExtraDef =
+	| { key; label; description?; type: "boolean"; default?: boolean }
+	| {
+			key;
+			label;
+			description?;
+			type: "string";
+			default?: string;
+			placeholder?: LocalizedText;
+			maxlength?: number;
+	  }
+	| {
+			key;
+			label;
+			description?;
+			type: "select";
+			default?: string;
+			placeholder?: LocalizedText;
+			options: { value: string; label: LocalizedText }[];
+	  };
+```
+
+```ts
+{
+	type: "number",
+	label: "Number",
+	extras: [
+		// rendered after the number on the consumer's own page: "12.5 % vol"
+		{ key: "unit", label: "Unit", type: "string", placeholder: "e.g. % vol", maxlength: 16 },
+		{ key: "group", label: "Group", type: "select", placeholder: "— none —",
+		  options: [{ value: "nutrition", label: "Nutrition declaration" }] },
+	],
+}
+```
+
+- **Empty means absent.** Emptying a `string` extra or picking a `select`'s blank entry
+  **removes the key** (and removes `extras` itself once the bag is empty) rather than
+  storing `""` — "no unit" has exactly one representation downstream. Consequence worth
+  knowing: a `default` becomes eligible for re-seeding again, so a cleared extra
+  reappears if the field's type is changed away and back.
+- **Whitespace is trimmed on commit, not while typing** — trimming on every keystroke
+  would make a trailing space untypable.
+- **`maxlength` is checked twice** — the input's attribute bounds typing, and
+  `validateFieldDefs` re-checks the stored value (the attribute does not constrain a
+  programmatically seeded or imported one) and reports it as a row error.
+- **A `select` value outside the declared `options` is preserved** and rendered as its
+  own entry, the same stance the component takes on an unknown field `type` — it stays
+  visible and round-trips instead of being silently coerced to blank.
+- Extras have **no per-extra lock**; `FieldLock` does not cover them (the whole editor
+  still honours `disabled`).
+
 `FIELDS_BUILDER_DEFAULT_TYPES` ships a small general-purpose palette
 (text / longtext / number / checkbox / select / date) for demos and unopinionated
 consumers — `types` is still a required prop, so nobody gets it by accident.

package/dist/components/FieldsBuilder/i18n-sk.js

@@ -59,6 +59,7 @@ export const FIELDS_BUILDER_MESSAGES_SK = {
     err_options_required: "Pridajte aspoň jednu možnosť",
     err_option_value_required: "Každá možnosť musí mať hodnotu",
     err_option_value_duplicate: "Hodnoty možností musia byť jedinečné",
+    err_extra_maxlength: "{{label}} — hodnota je príliš dlhá (max. {{max}} znakov)",
     err_max_fields: "Maximálny počet polí je {{max}}",
 };
 /**

package/dist/components/FieldsBuilder/i18n.d.ts

@@ -53,6 +53,7 @@ export declare const FIELDS_BUILDER_MESSAGES_EN: {
     err_options_required: string;
     err_option_value_required: string;
     err_option_value_duplicate: string;
+    err_extra_maxlength: string;
     err_max_fields: string;
 };
 /** Every message key `FieldsBuilder` (and its internals) may look up. */

package/dist/components/FieldsBuilder/i18n.js

@@ -54,6 +54,7 @@ export const FIELDS_BUILDER_MESSAGES_EN = {
     err_options_required: "Add at least one choice",
     err_option_value_required: "Every choice needs a value",
     err_option_value_duplicate: "Choice values must be unique",
+    err_extra_maxlength: "{{label}} is too long (max {{max}} characters)",
     err_max_fields: "Maximum number of fields is {{max}}",
 };
 /**

package/dist/components/FieldsBuilder/index.d.ts

@@ -1,5 +1,5 @@
 export { default as FieldsBuilder, type Props as FieldsBuilderProps, } from "./FieldsBuilder.svelte";
-export type { FieldDef, FieldLock, FieldOptionDef, FieldTypeDef, FieldTypeExtraDef, LocalizedText, } from "./types.js";
+export type { FieldDef, FieldLock, FieldOptionDef, FieldTypeDef, FieldTypeExtraBaseDef, FieldTypeExtraBooleanDef, FieldTypeExtraDef, FieldTypeExtraSelectDef, FieldTypeExtraStringDef, LocalizedText, } from "./types.js";
 export { DEFAULT_FIELD_TYPES as FIELDS_BUILDER_DEFAULT_TYPES, DEFAULT_KEY_PATTERN as FIELDS_BUILDER_DEFAULT_KEY_PATTERN, getLocalizedText, slugifyKey, uniqueKey, validateFieldDefs, type FieldDefRowErrors, type FieldDefsValidationResult, type ValidateFieldDefsOptions, } from "./utils.js";
 export { createFieldsBuilderT, FIELDS_BUILDER_MESSAGES_EN, type FieldsBuilderMessageKey, type FieldsBuilderMessages, } from "./i18n.js";
 export { FIELDS_BUILDER_MESSAGES_SK, FIELDS_BUILDER_DEFAULT_TYPES_SK, } from "./i18n-sk.js";

package/dist/components/FieldsBuilder/types.d.ts

@@ -40,24 +40,60 @@ export interface FieldDef {
      */
     options?: FieldOptionDef[];
     /**
-     * Per-type extra flags, driven by the palette entry's `extras`. An open bag
+     * Per-type extra values, driven by the palette entry's `extras`. An open bag
      * on purpose — the component never interprets these, it only renders a
-     * control per declared extra and round-trips the value.
+     * control per declared extra and round-trips the value. Like `options`,
+     * extras of a previous type are RETAINED when the type changes.
      */
     extras?: Record<string, unknown>;
     /** What the user may NOT change. Absent = fully editable. */
     lock?: FieldLock;
 }
-/** An extra per-field control declared by a palette entry (v1: booleans only). */
-export interface FieldTypeExtraDef {
+/** Shared shape of every extra per-field control declared by a palette entry. */
+export interface FieldTypeExtraBaseDef {
     /** Stored under `FieldDef.extras[key]`. */
     key: string;
     label: LocalizedText;
     description?: LocalizedText;
-    /** v1: booleans only (rendered as a checkbox). */
+}
+/** A yes/no extra — rendered as a checkbox. */
+export interface FieldTypeExtraBooleanDef extends FieldTypeExtraBaseDef {
     type: "boolean";
     default?: boolean;
 }
+/**
+ * A short free-text extra (a unit, a suffix, a format hint...) — rendered as a
+ * single-line text input. An emptied value REMOVES `extras[key]` rather than
+ * storing `""`, so "no value" has exactly one representation downstream.
+ */
+export interface FieldTypeExtraStringDef extends FieldTypeExtraBaseDef {
+    type: "string";
+    default?: string;
+    placeholder?: LocalizedText;
+    /**
+     * Enforced by the input's `maxlength` attribute AND re-checked by
+     * `validateFieldDefs` (the attribute does not bound a programmatically
+     * seeded value).
+     */
+    maxlength?: number;
+}
+/**
+ * One of a fixed list of values — rendered as a select. Selecting the empty
+ * entry REMOVES `extras[key]`. A stored value that is not among `options` is
+ * kept and rendered as-is (never silently coerced away).
+ */
+export interface FieldTypeExtraSelectDef extends FieldTypeExtraBaseDef {
+    type: "select";
+    default?: string;
+    options: FieldOptionDef[];
+    /** Label of the "nothing selected" entry. Default: blank. */
+    placeholder?: LocalizedText;
+}
+/**
+ * An extra per-field control declared by a palette entry, rendered into
+ * `FieldDef.extras[key]`. Discriminated by `type`.
+ */
+export type FieldTypeExtraDef = FieldTypeExtraBooleanDef | FieldTypeExtraStringDef | FieldTypeExtraSelectDef;
 /** One entry of the type palette (the `types` prop). */
 export interface FieldTypeDef {
     /** Stored in `FieldDef.type`. */

package/dist/components/FieldsBuilder/utils.d.ts

@@ -26,6 +26,8 @@ export interface FieldDefRowErrors {
     label?: string;
     key?: string;
     options?: string;
+    /** First offending extra of the row (its label is in the message). */
+    extras?: string;
 }
 export interface FieldDefsValidationResult {
     valid: boolean;
@@ -41,7 +43,7 @@ export interface ValidateFieldDefsOptions {
      * must never block the rest of the list), but their keys still count toward
      * uniqueness.
      */
-    types?: Pick<FieldTypeDef, "type" | "supportsOptions">[];
+    types?: Pick<FieldTypeDef, "type" | "supportsOptions" | "extras">[];
     keyPattern?: RegExp;
     keyMaxLength?: number;
     reservedKeys?: string[] | ((key: string) => boolean);
@@ -53,7 +55,7 @@ export interface ValidateFieldDefsOptions {
 /**
  * Validate a list of field defs: label non-empty, key present/pattern/length/
  * unique/not-reserved, choice types have at least one option with non-empty
- * unique values, `maxFields` not exceeded.
+ * unique values, string extras within `maxlength`, `maxFields` not exceeded.
  *
  * This is client-side convenience only — a consumer persisting the list MUST
  * re-validate server-side; this function is not a security boundary.

package/dist/components/FieldsBuilder/utils.js

@@ -65,7 +65,7 @@ export function isKeyReserved(key, reservedKeys) {
 /**
  * Validate a list of field defs: label non-empty, key present/pattern/length/
  * unique/not-reserved, choice types have at least one option with non-empty
- * unique values, `maxFields` not exceeded.
+ * unique values, string extras within `maxlength`, `maxFields` not exceeded.
  *
  * This is client-side convenience only — a consumer persisting the list MUST
  * re-validate server-side; this function is not a security boundary.
@@ -125,6 +125,19 @@ export function validateFieldDefs(defs, opts = {}) {
                 put(i, "options", t("err_option_value_duplicate"));
             }
         }
+        // `maxlength` is re-checked here on purpose: the input's attribute stops
+        // typing, it does not bound a seeded or pasted-then-mutated value
+        for (const ex of typeMap?.get(d.type)?.extras ?? []) {
+            if (ex.type !== "string" || !ex.maxlength)
+                continue;
+            const v = d.extras?.[ex.key];
+            if (typeof v === "string" && v.length > ex.maxlength) {
+                put(i, "extras", t("err_extra_maxlength", {
+                    label: getLocalizedText(ex.label, opts.defaultLanguage),
+                    max: ex.maxlength,
+                }));
+            }
+        }
     });
     let message = rowErrors.find(Boolean)
         ? Object.values(rowErrors.find(Boolean))[0]

package/dist/components/Input/FieldSwitch.svelte

@@ -1,6 +1,7 @@
 <script lang="ts" module>
 	import type { Snippet } from "svelte";
 	import type { ValidateOptions } from "../../actions/validate.svelte.js";
+	import type { SwitchIntent } from "../Switch/Switch.svelte";
 	import type { THC } from "../Thc/Thc.svelte";
 	import type { InputWrapClassProps } from "./types.js";
 
@@ -32,6 +33,25 @@
 		classInput?: string;
 		style?: string;
 		renderValue?: (rawValue: any) => string;
+		//
+		// Below: forwarded as-is to the underlying <Switch>.
+		//
+		/** Semantic color intent of the switch */
+		intent?: SwitchIntent;
+		/**
+		 * Size of the switch itself. Deliberately separate from `renderSize`, which sizes
+		 * the InputWrap shell (label, description, spacing) around it.
+		 */
+		switchSize?: "xs" | "sm" | "md" | "lg" | string;
+		/** Classes for the switch's toggle dot/knob element */
+		dotClass?: string;
+		/** Snippet to render inside the dot when checked */
+		on?: Snippet;
+		/** Snippet to render inside the dot when unchecked */
+		off?: Snippet;
+		/** Async validation before toggle - return false to prevent change */
+		preHook?: (current: boolean) => Promise<false | any>;
+		onclick?: (event: MouseEvent) => void;
 	}
 </script>
 
@@ -72,6 +92,15 @@
 		labelLeftBreakpoint = 480,
 		//
 		classInput,
+		//
+		intent,
+		switchSize = "md",
+		dotClass,
+		on,
+		off,
+		preHook,
+		onclick,
+		//
 		classLabel,
 		classLabelBox,
 		classInputBox,
@@ -150,13 +179,30 @@
 	classInputBoxWrap={twMerge("input-wrap-transparent", classInputBoxWrap)}
 	{style}
 >
+	<!--
+		`aria-labelledby` (not the InputWrap's `for={id}`) is what names the switch: the
+		<Switch> root is itself a <label>, so a `for` pointing at it would not associate,
+		and its inner checkbox is aria-hidden. Matches InputWrap's own `{id}-label`, and
+		only when there is a label to point at.
+	-->
 	<Switch
 		bind:this={switchRef}
 		bind:checked
 		{name}
 		{required}
 		{disabled}
+		{intent}
+		{dotClass}
+		{on}
+		{off}
+		{preHook}
+		{onclick}
+		{tabindex}
+		size={switchSize}
+		class={classInput}
+		aria-labelledby={label ? `${id}-label` : undefined}
 		validate={validateProp}
 		{setValidationResult}
+		{...rest}
 	/>
 </InputWrap>

package/dist/components/Input/FieldSwitch.svelte.d.ts

@@ -1,5 +1,6 @@
 import type { Snippet } from "svelte";
 import type { ValidateOptions } from "../../actions/validate.svelte.js";
+import type { SwitchIntent } from "../Switch/Switch.svelte";
 import type { THC } from "../Thc/Thc.svelte";
 import type { InputWrapClassProps } from "./types.js";
 type SnippetWithId = Snippet<[{
@@ -31,6 +32,22 @@ export interface Props extends InputWrapClassProps, Record<string, any> {
     classInput?: string;
     style?: string;
     renderValue?: (rawValue: any) => string;
+    /** Semantic color intent of the switch */
+    intent?: SwitchIntent;
+    /**
+     * Size of the switch itself. Deliberately separate from `renderSize`, which sizes
+     * the InputWrap shell (label, description, spacing) around it.
+     */
+    switchSize?: "xs" | "sm" | "md" | "lg" | string;
+    /** Classes for the switch's toggle dot/knob element */
+    dotClass?: string;
+    /** Snippet to render inside the dot when checked */
+    on?: Snippet;
+    /** Snippet to render inside the dot when unchecked */
+    off?: Snippet;
+    /** Async validation before toggle - return false to prevent change */
+    preHook?: (current: boolean) => Promise<false | any>;
+    onclick?: (event: MouseEvent) => void;
 }
 import type { ValidationResult } from "../../actions/validate.svelte.js";
 declare const FieldSwitch: import("svelte").Component<Props, {

package/dist/components/Input/README.md

@@ -148,6 +148,38 @@ Component-specific targets (e.g. `classInput` for the inner `<input>`/`<select>`
 <FieldCheckbox label="I agree to the terms" bind:checked={agreed} required />
 ```
 
+### Switch
+
+`FieldSwitch` wraps a [`Switch`](../Switch/README.md) in the standard field scaffolding
+(label, description, validation box) and forwards the switch's own props to it.
+
+```svelte
+<script lang="ts">
+	import { FieldSwitch } from "stuic";
+
+	let published = $state(false);
+</script>
+
+<FieldSwitch
+	label="Published"
+	description="Whether the public page resolves."
+	intent="success"
+	bind:checked={published}
+/>
+```
+
+| Prop                                                                | Goes to                                                              |
+| ------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `intent`, `dotClass`, `on`, `off`, `preHook`, `onclick`, `tabindex` | the inner `<Switch>`                                                 |
+| `classInput`                                                        | the inner `<Switch>`'s class                                         |
+| `switchSize`                                                        | the switch's own size (`"xs" \| "sm" \| "md" \| "lg"`, default `md`) |
+| `renderSize`                                                        | the surrounding field shell only — it does **not** size the switch   |
+| everything else unrecognized (`...rest`)                            | the inner `<Switch>`                                                 |
+
+The visible label names the control via `aria-labelledby` (the switch is announced as
+`switch, on/off` with that name). Clicking the label text does not toggle — the switch's
+own root is a `<label>`, so an HTML `for` association is not possible; click the switch.
+
 ### Input with Addons
 
 ```svelte

package/dist/components/Input/_internal/InputWrap.svelte

@@ -117,8 +117,13 @@
 		)}
 	>
 		{#if label}
+			<!--
+				The `{id}-label` id is what controls that cannot be reached by `for`
+				(e.g. FieldSwitch's <Switch>) point their `aria-labelledby` at.
+			-->
 			<label
 				for={id}
+				id="{id}-label"
 				class={twMerge(
 					"block flex-1 px-2 mb-1 text-base",
 					required && "after:content-['*'] after:opacity-40 after:pl-1",

package/dist/components/Switch/README.md

@@ -10,7 +10,7 @@ A toggle switch component with size variants, semantic intents, keyboard support
 | `size`     | `"sm" \| "md" \| "lg" \| "xl" \| string`                           | `"lg"`  | Switch size                                  |
 | `intent`   | `"primary" \| "accent" \| "success" \| "warning" \| "destructive"` | -       | Semantic color intent                        |
 | `name`     | `string`                                                           | -       | Form field name for hidden checkbox          |
-| `label`    | `string`                                                           | -       | Screen reader label (visually hidden)        |
+| `label`    | `string`                                                           | -       | Accessible name (rendered as `aria-label`)   |
 | `required` | `boolean`                                                          | `false` | Mark as required                             |
 | `disabled` | `boolean`                                                          | `false` | Disable toggle                               |
 | `tabindex` | `number`                                                           | `0`     | Tab index                                    |
@@ -142,3 +142,30 @@ A toggle switch component with size variants, semantic intents, keyboard support
 
 - **Space**: Toggle switch
 - **Enter**: Toggle switch
+
+## Accessibility
+
+The interactive element is the switch track itself (the root `<label class="stuic-switch">`):
+it is focusable, keyboard operable, and carries `role="switch"` plus the state - `aria-checked`,
+and `aria-disabled` / `aria-required` / `aria-invalid` when they apply.
+
+**Always give it a name.** `role="switch"` takes its accessible name from the author only, never
+from its content, so a switch without one is announced as an unnamed control:
+
+```svelte
+<!-- name it directly … -->
+<Switch label="Published" bind:checked={published} />
+
+<!-- … or point at existing visible text -->
+<span id="pub-label">Published</span>
+<Switch aria-labelledby="pub-label" bind:checked={published} />
+```
+
+An explicit `aria-label` / `aria-labelledby` wins over the `label` prop.
+[`FieldSwitch`](../Input/README.md#switch) wires its own visible label up automatically.
+
+The inner `<input type="checkbox">` is the form value carrier only (submission, `name`,
+`required`, native validation) and is `aria-hidden` so that the switch is the single announced
+control. It is therefore **not** reachable via role-based queries - locate it structurally
+(`container.querySelector('input[type="checkbox"]')`) and use `getByRole("switch")` for the
+control itself.

package/dist/components/Switch/Switch.svelte

@@ -19,7 +19,12 @@
 		class?: string;
 		/** Classes for the toggle dot/knob element */
 		dotClass?: string;
-		/** Screen reader label (visually hidden) */
+		/**
+		 * Accessible name for the switch, rendered as `aria-label` on the interactive
+		 * element. An explicit `aria-label`/`aria-labelledby` passed by the caller wins.
+		 * Required unless the switch is named some other way - `role="switch"` takes its
+		 * name from the author only, never from its content.
+		 */
 		label?: string;
 		required?: boolean;
 		disabled?: boolean;
@@ -125,11 +130,27 @@
 	}
 </script>
 
+<!--
+	The <label> is the interactive element here: it is focusable, keyboard operable and
+	carries the whole toggle interaction, so it - not the hidden checkbox - is what must
+	be announced. Hence `role="switch"` + the aria state below. The inner checkbox stays
+	as the form value carrier only (aria-hidden, see there).
+
+	Note that `role` on a <label> is not allowed by ARIA-in-HTML (the element maps to no
+	role); it is nevertheless honoured by browsers/AT and is the least invasive way to
+	name and announce this control without restructuring the markup.
+-->
 <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
 <!-- svelte-ignore a11y_no_noninteractive_element_interactions  -->
 <label
 	bind:this={wrap}
 	class={twMerge("stuic-switch m-2", _preset.size[size], classProp)}
+	role="switch"
+	aria-checked={!!checked}
+	aria-disabled={disabled || undefined}
+	aria-required={required || undefined}
+	aria-invalid={_validation && !_validation.valid ? "true" : undefined}
+	aria-label={label}
 	data-checked={checked}
 	data-disabled={disabled}
 	data-intent={intent}
@@ -165,11 +186,18 @@
 			{@render off?.()}
 		{/if}
 	</span>
+	<!--
+		Value carrier only: it holds the checked state for form submission and native
+		validation. `aria-hidden` keeps it out of the a11y tree so the switch above is
+		the single announced control (it is never focused - `tabindex="-1"` and every
+		focus() call targets the wrapper).
+	-->
 	<input
 		bind:checked
 		bind:this={checkbox}
 		type="checkbox"
 		class="opacity-0 size-0"
+		aria-hidden="true"
 		{disabled}
 		{required}
 		{name}

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

@@ -13,7 +13,12 @@ export interface Props extends Omit<HTMLLabelAttributes, "children" | "onchange"
     class?: string;
     /** Classes for the toggle dot/knob element */
     dotClass?: string;
-    /** Screen reader label (visually hidden) */
+    /**
+     * Accessible name for the switch, rendered as `aria-label` on the interactive
+     * element. An explicit `aria-label`/`aria-labelledby` passed by the caller wins.
+     * Required unless the switch is named some other way - `role="switch"` takes its
+     * name from the author only, never from its content.
+     */
     label?: string;
     required?: boolean;
     disabled?: boolean;

package/dist/index.d.ts

@@ -35,6 +35,7 @@ export * from "./components/Cart/index.js";
 export * from "./components/Card/index.js";
 export * from "./components/Carousel/index.js";
 export * from "./components/Checkout/index.js";
+export * from "./components/Circle/index.js";
 export * from "./components/Collapsible/index.js";
 export * from "./components/ColorScheme/index.js";
 export * from "./components/CommandMenu/index.js";

package/dist/index.js

@@ -36,6 +36,7 @@ export * from "./components/Cart/index.js";
 export * from "./components/Card/index.js";
 export * from "./components/Carousel/index.js";
 export * from "./components/Checkout/index.js";
+export * from "./components/Circle/index.js";
 export * from "./components/Collapsible/index.js";
 export * from "./components/ColorScheme/index.js";
 export * from "./components/CommandMenu/index.js";

package/docs/domains/utils.md

@@ -110,7 +110,7 @@ const search = debounce((query: string) => {
 | `colors`       | Color manipulation              |
 | `avatarColors` | Deterministic avatar colors     |
 | `paint`        | HSL color generation            |
-| `svgCircle`    | SVG circle path                 |
+| `svgCircle`    | SVG progress ring (DOM node)    |
 | `oscillate`    | Value oscillation for animation |
 
 ### Example: Class Merging

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.164.0",
+	"version": "3.166.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",