@marianmeres/stuic 3.172.0 → 3.173.0

package/dist/components/Rating/README.md

@@ -0,0 +1,206 @@
+# Rating
+
+Star rating — an input and a display in one component. Input mode is an accessible
+`role="radiogroup"` of per-star (or per-half-star) radios with hover preview, roving
+keyboard navigation, click-again-to-clear, a hidden input for form participation and
+the stuic `validate` action (with `required` enforced). `readonly` turns it into a
+display (`role="img"`) that renders any fraction — 4.2 is a 20%-filled fifth star.
+
+Symbols are two stacked copies of an svg: the empty one underneath (muted) and the
+filled one on top clipped to the value, so any fill-based icon works as-is (stars by
+default; hearts, flames, anything drawn with `currentColor`). Adjacent but different:
+`FieldLikeButton` (a field that opens something), `Slider` (a continuous range).
+
+## Props
+
+| Prop                  | Type                              | Default    | Description                                                                                                             |
+| --------------------- | --------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `value`               | `number`                          | `0`        | Current value (bindable); 0 = no rating. Rendered clamped to `[0, max]`, snapped to whole/half symbols in input mode    |
+| `max`                 | `number`                          | `5`        | Number of symbols (integer ≥ 1)                                                                                         |
+| `allowHalf`           | `boolean`                         | `false`    | Half-symbol values: each symbol gets two hit zones, arrows step by 0.5                                                  |
+| `allowClear`          | `boolean`                         | `true`     | Clicking the selected symbol again, or Delete / Backspace, resets to 0                                                  |
+| `readonly`            | `boolean`                         | `false`    | Display variant: `role="img"`, no interaction, no hidden input, fractional values rendered as-is                        |
+| `disabled`            | `boolean`                         | `false`    | No interaction; the hidden input is disabled too (nothing submits)                                                      |
+| `size`                | `"sm" \| "md" \| "lg"`            | `"md"`     | Symbol size preset (`--stuic-rating-size` overrides any preset)                                                         |
+| `intent`              | `IntentColorKey`                  | -          | Theme color of the filled symbols; unset = the fixed "star amber" (`--stuic-rating-icon-color`)                         |
+| `icon`                | `string`                          | star       | Raw svg/html string of the filled symbol (e.g. an `@marianmeres/icons-fns` result); must draw with `currentColor`       |
+| `iconEmpty`           | `string`                          | = `icon`   | Raw svg/html string of the empty symbol (defaults to the same icon, muted — pass an outline for the outline-empty look) |
+| `label`               | `string`                          | `"Rating"` | Accessible name of the group (via `t("rating")` by default); in `readonly` it prefixes the value announcement           |
+| `name`                | `string`                          | -          | Form field name of the hidden input (input mode)                                                                        |
+| `required`            | `boolean`                         | `false`    | Require a non-zero value — enforced by the built-in validator (hidden inputs skip native constraint validation)         |
+| `t`                   | `TranslateFn`                     | English    | i18n translate function (see below)                                                                                     |
+| `onchange`            | `(value: number) => void`         | -          | Fires when the user changes the value (click, keyboard, clear)                                                          |
+| `validate`            | `boolean \| ValidateOptions`      | -          | Validation (stuic `validate` action): omitted/`true` = on, `false` = off, object = options (`customValidator`, …)       |
+| `setValidationResult` | `(res: ValidationResult) => void` | -          | Receives every validation result                                                                                        |
+| `unstyled`            | `boolean`                         | `false`    | Skip all default styling                                                                                                |
+| `class`               | `string`                          | -          | Additional CSS classes (merged via twMerge)                                                                             |
+| `classItem`           | `string`                          | -          | Class for every symbol wrapper                                                                                          |
+| `classIcon`           | `string`                          | -          | Class for the icon stack inside each symbol                                                                             |
+| `el`                  | `HTMLDivElement`                  | -          | Root element reference (bindable)                                                                                       |
+| `inputEl`             | `HTMLInputElement`                | -          | Hidden input reference (bindable; input mode)                                                                           |
+
+Other attributes (`id`, `style`, `data-*`, …) are passed to the root `div`.
+`onkeydown` and `onpointerleave` are reserved by the component.
+
+### Imperative API (via `bind:this`)
+
+| Method              | Description                                                          |
+| ------------------- | -------------------------------------------------------------------- |
+| `validate()`        | Trigger validation now; returns the `ValidationResult`               |
+| `clearValidation()` | Clear the stored result and the hidden input's custom validity       |
+| `getValidation()`   | The last validation result (also reported via `setValidationResult`) |
+
+## Usage
+
+### Input
+
+```svelte
+<script lang="ts">
+	import { Rating } from "@marianmeres/stuic";
+
+	let value = $state(0);
+</script>
+
+<Rating bind:value />
+<Rating bind:value allowHalf />
+<Rating bind:value max={10} size="sm" />
+<Rating bind:value allowClear={false} onchange={(v) => console.log("rated", v)} />
+```
+
+### Display
+
+```svelte
+<div class="flex items-center gap-2">
+	<Rating value={4.2} readonly label="Average rating" />
+	<span>4.2</span>
+	<span class="text-neutral-500">(128 reviews)</span>
+</div>
+```
+
+### In a form
+
+The hidden input submits `name=value`. `required` is enforced by the built-in
+validator; call `validate()` on submit so a never-touched field reports as well.
+
+```svelte
+<script lang="ts">
+	import { Rating, type ValidationResult } from "@marianmeres/stuic";
+
+	let rating: Rating;
+	let validation: ValidationResult | undefined = $state();
+
+	function onsubmit(e: SubmitEvent) {
+		if (!rating.validate()?.valid) e.preventDefault();
+	}
+</script>
+
+<form {onsubmit}>
+	<Rating
+		bind:this={rating}
+		name="score"
+		required
+		setValidationResult={(r) => (validation = r)}
+	/>
+	{#if validation && !validation.valid}
+		<p class="text-red-600">{validation.message}</p>
+	{/if}
+	<button>Submit</button>
+</form>
+```
+
+Custom rules go through the action's `customValidator` (it receives the value as a
+string; the built-in `required` check runs first):
+
+```svelte
+<Rating
+	name="score"
+	validate={{ customValidator: (v) => (Number(v) < 2 ? "Be kinder" : "") }}
+/>
+```
+
+### Custom symbols
+
+```svelte
+<script lang="ts">
+	import { Rating, iconStar } from "@marianmeres/stuic";
+	import { iconBsHeartFill } from "@marianmeres/icons-fns/bootstrap/iconBsHeartFill.js";
+	import { iconBsHeart } from "@marianmeres/icons-fns/bootstrap/iconBsHeart.js";
+</script>
+
+<!-- outline when empty, filled star when set -->
+<Rating value={3.5} readonly iconEmpty={iconStar()} />
+
+<!-- hearts -->
+<Rating
+	bind:value
+	icon={iconBsHeartFill()}
+	iconEmpty={iconBsHeart()}
+	intent="destructive"
+/>
+```
+
+Fill-based icons work best: the filled layer is clipped horizontally to the value, so
+the symbol has to be drawn with `currentColor` (stroke-only icons render as a colored
+outline — fine as `iconEmpty`, thin as `icon`).
+
+### i18n
+
+Built-in English; bundled Slovak (`RATING_MESSAGES_SK`) is opt-in. Localized: the
+group label (`rating`), the per-symbol radio / display announcement (`value_of_max`,
+"{value} of {max} stars") and the required message (`required`). With non-star
+symbols override `value_of_max` ("{value} of {max} hearts").
+
+```svelte
+<script lang="ts">
+	import { Rating, createRatingT, RATING_MESSAGES_SK } from "@marianmeres/stuic";
+	const t = createRatingT(RATING_MESSAGES_SK);
+</script>
+
+<Rating bind:value {t} />
+```
+
+## Accessibility
+
+- Input mode is a `role="radiogroup"` (named by `label` / `t("rating")`) of
+  `role="radio"` buttons, one per symbol (two per symbol with `allowHalf`), each
+  labeled "N of M stars" and `aria-checked` when selected. `aria-required`,
+  `aria-disabled` and `aria-invalid` (after a failed validation) are reflected on
+  the group.
+- Roving tabindex: the selected symbol is the single tab stop (the first one when
+  nothing is selected).
+- Keyboard: `→` / `↑` +1 step, `←` / `↓` −1 step (never below one step), `Home` /
+  `End` first / last, `Delete` / `Backspace` clear (when `allowClear`), `Space` /
+  `Enter` select the focused symbol (no toggle — clearing by re-clicking is
+  pointer-only, like native radios).
+- Display mode is a `role="img"` with the value announcement as its label; the
+  icons themselves are always `aria-hidden`.
+- The hover preview is pointer-only and never changes the value.
+
+## CSS Variables
+
+| Variable                          | Default                                             | Description                                                            |
+| --------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------- |
+| `--stuic-rating-size`             | unset (`sm` 1.125rem / `md` 1.5rem / `lg` 2rem)     | Symbol size; when set it overrides whichever `size` preset is on       |
+| `--stuic-rating-gap`              | `0.125rem`                                          | Gap between symbols                                                    |
+| `--stuic-rating-icon-color`       | `#f59e0b`                                           | Filled symbol color (theme-independent on purpose; `intent` overrides) |
+| `--stuic-rating-icon-color-empty` | `color-mix(in srgb, currentColor 20%, transparent)` | Empty symbol color (a tint of the surrounding text, so it adapts)      |
+| `--stuic-rating-icon-scale-hover` | `1.15`                                              | Scale of the hovered symbol                                            |
+| `--stuic-rating-ring-width`       | `3px`                                               | Focus ring width                                                       |
+| `--stuic-rating-ring-color`       | `--stuic-color-ring`                                | Focus ring color                                                       |
+| `--stuic-rating-radius`           | `--stuic-radius`                                    | Focus ring radius                                                      |
+| `--stuic-rating-transition`       | `--stuic-transition`                                | Fill / hover-scale transition duration                                 |
+| `--stuic-rating-opacity-disabled` | `0.5`                                               | Disabled opacity                                                       |
+
+`--stuic-rating-fill` (`0%`–`100%`) is **set by the component** inline on every
+symbol wrapper — an output, not an input. It survives `unstyled`, so a fully custom
+presentation can read it (e.g. a Tailwind `before:w-(--stuic-rating-fill)` bar).
+
+## Data Attributes
+
+- `data-size` - `"sm" | "md" | "lg"` (root)
+- `data-intent` - `IntentColorKey` (root, when set)
+- `data-readonly` / `data-disabled` - empty attributes (root)
+- `data-hover` - empty attribute (root while a symbol is hovered; and on the hovered symbol wrapper)
+- `data-state` - `"full" | "partial" | "empty"` (symbol wrapper, for the displayed — hovered or actual — value)
+- `data-value` - the zone's value, e.g. `"2.5"` (radio buttons)
+- `data-half` - `"start" | "end"` (radio buttons, with `allowHalf`)

package/dist/components/Rating/Rating.svelte

@@ -0,0 +1,355 @@
+<script lang="ts" module>
+	import type { HTMLAttributes } from "svelte/elements";
+	import type { TranslateFn } from "../../types.js";
+	import type { IntentColorKey } from "../../utils/design-tokens.js";
+	import type {
+		ValidateOptions,
+		ValidationResult,
+	} from "../../actions/validate.svelte.js";
+
+	export type RatingSize = "sm" | "md" | "lg";
+
+	/** Fill state of one symbol (its `data-state`). */
+	export type RatingItemState = "full" | "partial" | "empty";
+
+	export interface Props extends Omit<
+		HTMLAttributes<HTMLDivElement>,
+		| "children"
+		| "onchange"
+		// Reserved by the rating's own keyboard / hover machinery (compile-time
+		// guard against silently clobbering them via the rest spread).
+		| "onkeydown"
+		| "onpointerleave"
+	> {
+		/**
+		 * Current value (bindable), 0 = no rating. Rendered clamped to `[0, max]`;
+		 * in input mode also snapped to whole (or, with `allowHalf`, half) symbols.
+		 * Display mode (`readonly`) renders any fraction (4.2 → a 20% fifth star).
+		 */
+		value?: number;
+		/** Number of symbols (default 5; integer ≥ 1) */
+		max?: number;
+		/** Allow half-symbol values (each symbol gets two hit zones) */
+		allowHalf?: boolean;
+		/**
+		 * Clicking the currently selected symbol (or pressing Delete / Backspace)
+		 * resets the value to 0 (default true).
+		 */
+		allowClear?: boolean;
+		/**
+		 * Display variant: no interaction, no form participation, fractional
+		 * values rendered as-is. The root becomes `role="img"` with an accessible
+		 * "{value} of {max} stars" label.
+		 */
+		readonly?: boolean;
+		/** Disable interaction (the hidden input is disabled too, so nothing submits) */
+		disabled?: boolean;
+		/** Symbol size preset (default "md"); `--stuic-rating-size` overrides any preset */
+		size?: RatingSize;
+		/**
+		 * Semantic color of the filled symbols. Unset (default) uses the fixed
+		 * "star amber" (`--stuic-rating-icon-color`) regardless of theme.
+		 */
+		intent?: IntentColorKey;
+		/**
+		 * Raw svg/html string of the filled symbol (e.g. an `@marianmeres/icons-fns`
+		 * render result). Default: a filled star. Fill-based icons work best — the
+		 * fill layer is clipped to the value, so the symbol must draw with
+		 * `currentColor`.
+		 */
+		icon?: string;
+		/** Raw svg/html string of the empty symbol (default: same as `icon`, muted) */
+		iconEmpty?: string;
+		/**
+		 * Accessible name of the control (default `t("rating")`, "Rating"). In
+		 * `readonly` mode it prefixes the value announcement.
+		 */
+		label?: string;
+		/** Form field name (hidden input; input mode only) */
+		name?: string;
+		/** Require a non-zero value (enforced by the built-in validator) */
+		required?: boolean;
+		/** i18n translate function (see `createRatingT`) */
+		t?: TranslateFn;
+		/** Fires when the user changes the value (click, keyboard, clear) */
+		onchange?: (value: number) => void;
+		validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+		setValidationResult?: (res: ValidationResult) => void;
+		/** Skip all default styling */
+		unstyled?: boolean;
+		/** Additional CSS classes */
+		class?: string;
+		/** Class for every symbol wrapper */
+		classItem?: string;
+		/** Class for the icon stack inside each symbol */
+		classIcon?: string;
+		/** Bindable root element reference */
+		el?: HTMLDivElement;
+		/** Bindable hidden input reference (input mode only) */
+		inputEl?: HTMLInputElement;
+	}
+</script>
+
+<script lang="ts">
+	import { twMerge } from "../../utils/tw-merge.js";
+	import { validate as validateAction } from "../../actions/validate.svelte.js";
+	import { iconStarFill } from "../../icons/index.js";
+	import { t_default } from "./i18n.js";
+
+	let {
+		value = $bindable(0),
+		max = 5,
+		allowHalf = false,
+		allowClear = true,
+		readonly = false,
+		disabled = false,
+		size = "md",
+		intent,
+		icon,
+		iconEmpty,
+		label,
+		name,
+		required = false,
+		t = t_default,
+		onchange,
+		validate: validateProp,
+		setValidationResult,
+		unstyled = false,
+		class: classProp,
+		classItem: classItemProp,
+		classIcon: classIconProp,
+		el = $bindable(),
+		inputEl = $bindable(),
+		...rest
+	}: Props = $props();
+
+	const DEFAULT_ICON = iconStarFill();
+
+	let _max = $derived(Number.isFinite(max) && max >= 1 ? Math.floor(max) : 5);
+	let _step = $derived(allowHalf ? 0.5 : 1);
+
+	// The rendered (and submitted) value: clamped, and snapped to the step grid
+	// in input mode. External writes are NOT normalized back into the binding —
+	// what the consumer wrote stays theirs until the user interacts.
+	let _value = $derived.by(() => {
+		if (!Number.isFinite(value)) return 0;
+		const clamped = Math.min(Math.max(0, value), _max);
+		return readonly ? clamped : Math.round(clamped / _step) * _step;
+	});
+
+	let _interactive = $derived(!readonly && !disabled);
+
+	// Pointer hover preview (input mode only)
+	let _hover: number | null = $state(null);
+	let _display = $derived(_hover ?? _value);
+
+	let _icon = $derived(icon || DEFAULT_ICON);
+	let _iconEmpty = $derived(iconEmpty || _icon);
+
+	let _items = $derived(Array.from({ length: _max }, (_, i) => i + 1));
+
+	// Hit zones per symbol: one (whole) or two (half + whole)
+	function zonesOf(i: number): number[] {
+		return allowHalf ? [i - 0.5, i] : [i];
+	}
+
+	/** 0..1 fill ratio of the i-th (1-based) symbol for the displayed value */
+	function fillOf(i: number): number {
+		return Math.min(Math.max(_display - (i - 1), 0), 1);
+	}
+
+	function stateOf(fill: number): RatingItemState {
+		if (fill >= 1) return "full";
+		if (fill <= 0) return "empty";
+		return "partial";
+	}
+
+	// Format numbers without float noise (2.5, not 2.5000000000000004)
+	function fmt(n: number): string {
+		return String(Math.round(n * 100) / 100);
+	}
+
+	function valueText(v: number): string {
+		return t("value_of_max", { value: fmt(v), max: _max });
+	}
+
+	let _class = $derived(unstyled ? classProp : twMerge("stuic-rating", classProp));
+	let _classItem = $derived(
+		unstyled ? classItemProp : twMerge("stuic-rating-item", classItemProp)
+	);
+	let _classIcon = $derived(
+		unstyled ? classIconProp : twMerge("stuic-rating-icon", classIconProp)
+	);
+
+	// Roving tabindex: the selected zone is the tab stop (the first one when
+	// nothing is selected), arrows move between the others.
+	function tabindexOf(v: number, first: boolean): 0 | -1 {
+		if (_value === v) return 0;
+		return _value === 0 && first ? 0 : -1;
+	}
+
+	function commit(v: number, toggle = false) {
+		if (!_interactive) return;
+		const next = toggle && allowClear && v === _value ? 0 : v;
+		if (next === _value) return;
+		value = next;
+		// The hidden input's DOM value is only synced on the next flush, but the
+		// validate action reads it synchronously in its "change" listener — so
+		// write it by hand before dispatching. Svelte re-applies the same string
+		// later (a no-op).
+		if (inputEl) {
+			inputEl.value = String(next);
+			inputEl.dispatchEvent(new Event("change", { bubbles: true }));
+		}
+		onchange?.(next);
+	}
+
+	function focusZone(v: number) {
+		el?.querySelector<HTMLButtonElement>(`[data-value="${fmt(v)}"]`)?.focus();
+	}
+
+	function onkeydown(e: KeyboardEvent) {
+		if (!_interactive) return;
+		let next: number;
+		switch (e.key) {
+			case "ArrowRight":
+			case "ArrowUp":
+				next = Math.min(_max, _value + _step);
+				break;
+			case "ArrowLeft":
+			case "ArrowDown":
+				next = Math.max(_step, _value - _step);
+				break;
+			case "Home":
+				next = _step;
+				break;
+			case "End":
+				next = _max;
+				break;
+			case "Delete":
+			case "Backspace":
+				if (!allowClear) return;
+				next = 0;
+				break;
+			default:
+				return;
+		}
+		e.preventDefault();
+		commit(next);
+		if (next > 0) focusZone(next);
+	}
+
+	//
+	let _doValidate: (() => void) | undefined = $state();
+	// Local copy of the last validation result so getValidation() works even
+	// when no external setValidationResult was provided.
+	let _validation: ValidationResult | undefined = $state();
+
+	/** Trigger validation now. Reaches the parent via `setValidationResult`. */
+	export function validate(): ValidationResult | undefined {
+		_doValidate?.();
+		return _validation;
+	}
+
+	/** Clear the inline validation message and reset `setCustomValidity`. */
+	export function clearValidation(): void {
+		_validation = undefined;
+		inputEl?.setCustomValidity?.("");
+	}
+
+	/** Current validation state. */
+	export function getValidation(): ValidationResult | undefined {
+		return _validation;
+	}
+</script>
+
+<div
+	bind:this={el}
+	class={_class}
+	role={readonly ? "img" : "radiogroup"}
+	aria-label={readonly
+		? [label, valueText(_value)].filter(Boolean).join(", ")
+		: label || t("rating", null, "Rating")}
+	aria-required={!readonly && required ? "true" : undefined}
+	aria-disabled={!readonly && disabled ? "true" : undefined}
+	aria-invalid={_validation && !_validation.valid ? "true" : undefined}
+	data-size={!unstyled ? size : undefined}
+	data-intent={!unstyled ? intent : undefined}
+	data-readonly={!unstyled && readonly ? "" : undefined}
+	data-disabled={!unstyled && disabled ? "" : undefined}
+	data-hover={!unstyled && _hover !== null ? "" : undefined}
+	{onkeydown}
+	onpointerleave={() => (_hover = null)}
+	{...rest}
+>
+	{#each _items as i (i)}
+		{@const fill = fillOf(i)}
+		<span
+			class={_classItem}
+			style="--stuic-rating-fill: {Math.round(fill * 100)}%"
+			data-state={!unstyled ? stateOf(fill) : undefined}
+			data-hover={!unstyled && _hover !== null && Math.ceil(_hover) === i
+				? ""
+				: undefined}
+		>
+			<span class={_classIcon} aria-hidden="true">
+				<span class={unstyled ? undefined : "stuic-rating-icon-empty"}>
+					{@html _iconEmpty}
+				</span>
+				<span class={unstyled ? undefined : "stuic-rating-icon-fill"}>
+					{@html _icon}
+				</span>
+			</span>
+			{#if !readonly}
+				{#each zonesOf(i) as v, zi (v)}
+					<button
+						type="button"
+						role="radio"
+						class={unstyled ? undefined : "stuic-rating-zone"}
+						data-value={fmt(v)}
+						data-half={!unstyled && allowHalf ? (zi === 0 ? "start" : "end") : undefined}
+						aria-checked={_value === v}
+						aria-label={valueText(v)}
+						tabindex={tabindexOf(v, i === 1 && zi === 0)}
+						{disabled}
+						onclick={(e) => commit(v, e.detail !== 0)}
+						onpointerenter={() => {
+							if (_interactive) _hover = v;
+						}}
+					></button>
+				{/each}
+			{/if}
+		</span>
+	{/each}
+	{#if !readonly}
+		<input
+			bind:this={inputEl}
+			type="hidden"
+			{name}
+			value={_value}
+			{disabled}
+			use:validateAction={() => {
+				const customOpts =
+					typeof validateProp === "object" && validateProp ? validateProp : {};
+				const userValidator = customOpts.customValidator;
+				return {
+					enabled: validateProp !== false,
+					...customOpts,
+					// Hidden inputs are barred from native constraint validation, so
+					// `required` is enforced here, then the consumer's validator runs.
+					customValidator(val, ctx, input) {
+						if (required && !(Number(val) > 0)) {
+							return t("required", null, "Please select a rating");
+						}
+						return userValidator?.(val, ctx, input) || "";
+					},
+					setValidationResult: (res) => {
+						_validation = res;
+						setValidationResult?.(res);
+					},
+					setDoValidate: (fn) => (_doValidate = fn),
+				};
+			}}
+		/>
+	{/if}
+</div>

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

@@ -0,0 +1,82 @@
+import type { HTMLAttributes } from "svelte/elements";
+import type { TranslateFn } from "../../types.js";
+import type { IntentColorKey } from "../../utils/design-tokens.js";
+import type { ValidateOptions, ValidationResult } from "../../actions/validate.svelte.js";
+export type RatingSize = "sm" | "md" | "lg";
+/** Fill state of one symbol (its `data-state`). */
+export type RatingItemState = "full" | "partial" | "empty";
+export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "onchange" | "onkeydown" | "onpointerleave"> {
+    /**
+     * Current value (bindable), 0 = no rating. Rendered clamped to `[0, max]`;
+     * in input mode also snapped to whole (or, with `allowHalf`, half) symbols.
+     * Display mode (`readonly`) renders any fraction (4.2 → a 20% fifth star).
+     */
+    value?: number;
+    /** Number of symbols (default 5; integer ≥ 1) */
+    max?: number;
+    /** Allow half-symbol values (each symbol gets two hit zones) */
+    allowHalf?: boolean;
+    /**
+     * Clicking the currently selected symbol (or pressing Delete / Backspace)
+     * resets the value to 0 (default true).
+     */
+    allowClear?: boolean;
+    /**
+     * Display variant: no interaction, no form participation, fractional
+     * values rendered as-is. The root becomes `role="img"` with an accessible
+     * "{value} of {max} stars" label.
+     */
+    readonly?: boolean;
+    /** Disable interaction (the hidden input is disabled too, so nothing submits) */
+    disabled?: boolean;
+    /** Symbol size preset (default "md"); `--stuic-rating-size` overrides any preset */
+    size?: RatingSize;
+    /**
+     * Semantic color of the filled symbols. Unset (default) uses the fixed
+     * "star amber" (`--stuic-rating-icon-color`) regardless of theme.
+     */
+    intent?: IntentColorKey;
+    /**
+     * Raw svg/html string of the filled symbol (e.g. an `@marianmeres/icons-fns`
+     * render result). Default: a filled star. Fill-based icons work best — the
+     * fill layer is clipped to the value, so the symbol must draw with
+     * `currentColor`.
+     */
+    icon?: string;
+    /** Raw svg/html string of the empty symbol (default: same as `icon`, muted) */
+    iconEmpty?: string;
+    /**
+     * Accessible name of the control (default `t("rating")`, "Rating"). In
+     * `readonly` mode it prefixes the value announcement.
+     */
+    label?: string;
+    /** Form field name (hidden input; input mode only) */
+    name?: string;
+    /** Require a non-zero value (enforced by the built-in validator) */
+    required?: boolean;
+    /** i18n translate function (see `createRatingT`) */
+    t?: TranslateFn;
+    /** Fires when the user changes the value (click, keyboard, clear) */
+    onchange?: (value: number) => void;
+    validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+    setValidationResult?: (res: ValidationResult) => void;
+    /** Skip all default styling */
+    unstyled?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+    /** Class for every symbol wrapper */
+    classItem?: string;
+    /** Class for the icon stack inside each symbol */
+    classIcon?: string;
+    /** Bindable root element reference */
+    el?: HTMLDivElement;
+    /** Bindable hidden input reference (input mode only) */
+    inputEl?: HTMLInputElement;
+}
+declare const Rating: import("svelte").Component<Props, {
+    validate: () => ValidationResult | undefined;
+    clearValidation: () => void;
+    getValidation: () => ValidationResult | undefined;
+}, "el" | "value" | "inputEl">;
+type Rating = ReturnType<typeof Rating>;
+export default Rating;

package/dist/components/Rating/i18n-sk.d.ts

@@ -0,0 +1,17 @@
+import type { RatingMessages } from "./i18n.js";
+/**
+ * Slovak message catalog for `Rating`. Opt-in — English stays the built-in default,
+ * and this module is only pulled into a bundle when it is actually imported (the
+ * component itself never references it).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { Rating, createRatingT, RATING_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createRatingT(RATING_MESSAGES_SK);
+ * </script>
+ *
+ * <Rating bind:value {t} />
+ * ```
+ */
+export declare const RATING_MESSAGES_SK: RatingMessages;

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

@@ -0,0 +1,21 @@
+/**
+ * Slovak message catalog for `Rating`. Opt-in — English stays the built-in default,
+ * and this module is only pulled into a bundle when it is actually imported (the
+ * component itself never references it).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { Rating, createRatingT, RATING_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createRatingT(RATING_MESSAGES_SK);
+ * </script>
+ *
+ * <Rating bind:value {t} />
+ * ```
+ */
+export const RATING_MESSAGES_SK = {
+    rating: "Hodnotenie",
+    // "z {max}" governs the genitive plural, so the noun is right for any count
+    value_of_max: "{value} z {max} hviezdičiek",
+    required: "Prosím, vyberte hodnotenie",
+};