entasis 0.11.0 → 0.12.0

package/dist/components/Form/RadioInput/RadioInput.svelte

@@ -1,10 +1,13 @@
-<script lang="ts" generics="Option extends RadioOption">
+<script lang="ts" generics="Option extends RadioOption, Value extends string = Option['value']">
 	import { untrack } from 'svelte';
 	import Field from '../Field/Field.svelte';
 	import { createFieldState } from '../Field/field.state.svelte.js';
 	import type { RadioOption, RadioInputProps } from './radioInput.props.js';
 	import { useRadioInputTheme } from './radioInput.theme.js';
 	import Slot from '../../Slot/Slot.svelte';
+	import FieldHiddenInputs from '../Field/FieldHiddenInputs.svelte';
+	import { continueFormFromChoice } from '../CheckboxesInput/choiceEnter.js';
+	import { useNavigation } from '../../../utils/useNavigation.svelte.js';
 
 	let {
 		defaultValue = null,
@@ -16,6 +19,8 @@
 		mode = 'normal',
 		theme,
 		disabled,
+		readOnly,
+		messages,
 		name,
 		onValidate,
 		visible,
@@ -24,8 +29,8 @@
 		fieldAttrs,
 		size = 'normal',
 		...rest
-	}: RadioInputProps<Option> = $props();
-	if (value === undefined) value = untrack(() => defaultValue);
+	}: RadioInputProps<Option, Value> = $props();
+	if (value === undefined) value = untrack(() => defaultValue) as Value | null;
 
 	const id = $props.id();
 
@@ -35,7 +40,7 @@
 			return value;
 		},
 		set value(v) {
-			value = v;
+			value = v as Value | null;
 		},
 		get errors() {
 			return errors;
@@ -49,13 +54,19 @@
 		set focused(v: boolean) {
 			focused = v;
 		},
-		onValueChange: (v) => onValueChange?.(v),
+		onValueChange: (v) => onValueChange?.(v as Value | null),
 		get disabled() {
 			return disabled;
 		},
 		set disabled(v: boolean | undefined) {
 			disabled = v;
 		},
+		get readOnly() {
+			return readOnly;
+		},
+		get messages() {
+			return messages;
+		},
 		get required() {
 			return required;
 		},
@@ -75,12 +86,59 @@
 	});
 
 	const componentTheme = $derived(useRadioInputTheme(theme));
+
+	// Option ids come from field.id, unique per instance, and the index, always a valid id
+	// token: name + value collides across instances that share a name and breaks on spaces.
+	const optionId = (index: number) => `${field.id}-option-${index}`;
+	const isOptionDisabled = (option: RadioOption) => Boolean(field.disabled || option.disabled);
+
+	const checkedIndex = $derived(items.findIndex((option) => option.value === field.value));
+	const firstEnabledIndex = $derived(items.findIndex((option) => !isOptionDisabled(option)));
+	// The one Tab stop: the checked option, else the first one that can take focus.
+	const tabStopIndex = $derived(
+		checkedIndex >= 0 && !isOptionDisabled(items[checkedIndex]) ? checkedIndex : firstEnabledIndex
+	);
+
+	const select = (index: number) => {
+		const option = items[index];
+		if (!option || isOptionDisabled(option)) return;
+		field.value = option.value;
+	};
+
+	const navigation = useNavigation({
+		id,
+		orientation: 'both',
+		loop: true,
+		focusableContainer: false,
+		enableHoverFocus: false,
+		// Enter belongs to the form (see continueFormFromChoice); Space selects.
+		enterActivates: false,
+		// Escape must reach the Dialog, Popover or Ask the group sits in; the arrows, Home, End and
+		// Space are still cancelled by the navigation itself.
+		preventKeyboardDefault: false,
+		enabled: () => !field.disabled,
+		defaultFocusedIndex: () => (tabStopIndex >= 0 ? tabStopIndex : null),
+		// Selection follows the keyboard, but only a deliberate key move (an arrow, Home or End)
+		// selects: tabbing in, a programmatic focus or a click never changes the value, and Alt,
+		// Ctrl or Meta with an arrow is left to the browser. A read-only group moves focus only.
+		onKeyboardMove: (index) => select(index)
+	});
+
+	// What a native <form> submits: a disabled selected option is left out, as a disabled native
+	// radio is, while the field's own value keeps it.
+	const submittedValue = $derived(
+		checkedIndex >= 0 && !isOptionDisabled(items[checkedIndex]) ? items[checkedIndex].value : null
+	);
 </script>
 
 <!-- Create own field wrapper (when used standalone) -->
 <Field
 	as="fieldset"
-	fieldAttrs={{ ...fieldAttrs, role: 'radiogroup', 'aria-labelledby': field.labelId }}
+	fieldAttrs={{
+		...fieldAttrs,
+		role: 'radiogroup',
+		'aria-labelledby': label ? field.labelId : undefined
+	}}
 	{field}
 	{label}
 	class={componentTheme.root({ mode })}
@@ -97,40 +155,40 @@
 			})
 		}
 	}}
+	{@attach navigation.containerReference}
 >
-	{#each items as option (option.value)}
-		{@const checked = field.value === option.value}
-		{@const optionId = `${field.name}-${option.value}`}
-		{@const optionDisabled = Boolean(field.disabled || option.disabled)}
+	{#each items as option, index (option.value)}
+		{@const checked = checkedIndex === index}
+		{@const optionDisabled = isOptionDisabled(option)}
+		{@const itemId = optionId(index)}
 		<button
+			id={itemId}
 			type="button"
 			role="radio"
 			aria-checked={checked}
+			aria-labelledby={option.label ? `${itemId}-label` : undefined}
+			aria-label={option.label ? undefined : option.value}
+			aria-describedby={option.description ? `${itemId}-description` : undefined}
 			disabled={optionDisabled}
-			aria-label={option.label}
-			class={componentTheme.radiosInputItem({ mode, checked, disabled: optionDisabled, size })}
+			tabindex={navigation.focusedIndex === index ||
+			(navigation.focusedIndex === null && tabStopIndex === index)
+				? 0
+				: -1}
+			data-readonly={field.readOnly ? '' : undefined}
+			class={componentTheme.radiosInputItem({
+				mode,
+				checked,
+				disabled: optionDisabled,
+				size,
+				readOnly: field.readOnly
+			})}
 			onclick={() => {
-				if (optionDisabled) return;
-				if (!field.value || field.value !== option.value) {
-					field.value = option.value;
-				}
+				select(index);
+				navigation.focusItem(index);
 			}}
+			onkeydown={(event) => continueFormFromChoice(event, field)}
+			{@attach navigation.itemReference}
 		>
-			<input
-				hidden
-				onchange={() => {
-					if (optionDisabled) return;
-					field.value = option.value;
-				}}
-				style="transform: scale(0); opacity: 0; pointer-events: none; margin: -1px; position: absolute;"
-				type="radio"
-				{checked}
-				name={field.name}
-				id={optionId}
-				value={option.value}
-				disabled={optionDisabled}
-			/>
-
 			<!-- Radio Button Track -->
 			<div
 				class={componentTheme.radiosInputItemTrack({
@@ -152,7 +210,7 @@
 			></div>
 
 			<!-- Label Content -->
-			<div class={componentTheme.radiosInputItemLabel({ size })}>
+			<div id="{itemId}-label" class={componentTheme.radiosInputItemLabel({ size })}>
 				{#if option.icon}
 					<Slot render={option.icon} class={componentTheme.radiosInputItemIcon()} />
 				{/if}
@@ -162,8 +220,12 @@
 			<!-- Description -->
 			<Slot
 				render={option.description}
+				attrs={{ id: `${itemId}-description` }}
 				class={componentTheme.radiosInputItemDescription({ mode, checked })}
 			/>
 		</button>
 	{/each}
+	<!-- Beside the options (a button may not contain inputs). A required group blocks a native
+	     submit while nothing is selected. -->
+	<FieldHiddenInputs {field} value={submittedValue} required={field.required && !field.value} />
 </Field>

package/dist/components/Form/RadioInput/RadioInput.svelte.d.ts

@@ -1,25 +1,25 @@
 import type { RadioOption, RadioInputProps } from './radioInput.props.js';
-declare function $$render<Option extends RadioOption>(): {
-    props: RadioInputProps<Option>;
+declare function $$render<Option extends RadioOption, Value extends string = Option['value']>(): {
+    props: RadioInputProps<Option, Value>;
     exports: {};
     bindings: "value" | "errors" | "focused";
     slots: {};
     events: {};
 };
-declare class __sveltets_Render<Option extends RadioOption> {
-    props(): ReturnType<typeof $$render<Option>>['props'];
-    events(): ReturnType<typeof $$render<Option>>['events'];
-    slots(): ReturnType<typeof $$render<Option>>['slots'];
+declare class __sveltets_Render<Option extends RadioOption, Value extends string = Option['value']> {
+    props(): ReturnType<typeof $$render<Option, Value>>['props'];
+    events(): ReturnType<typeof $$render<Option, Value>>['events'];
+    slots(): ReturnType<typeof $$render<Option, Value>>['slots'];
     bindings(): "value" | "errors" | "focused";
     exports(): {};
 }
 interface $$IsomorphicComponent {
-    new <Option extends RadioOption>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<Option>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<Option>['props']>, ReturnType<__sveltets_Render<Option>['events']>, ReturnType<__sveltets_Render<Option>['slots']>> & {
-        $$bindings?: ReturnType<__sveltets_Render<Option>['bindings']>;
-    } & ReturnType<__sveltets_Render<Option>['exports']>;
-    <Option extends RadioOption>(internal: unknown, props: ReturnType<__sveltets_Render<Option>['props']> & {}): ReturnType<__sveltets_Render<Option>['exports']>;
-    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+    new <Option extends RadioOption, Value extends string = Option['value']>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<Option, Value>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<Option, Value>['props']>, ReturnType<__sveltets_Render<Option, Value>['events']>, ReturnType<__sveltets_Render<Option, Value>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<Option, Value>['bindings']>;
+    } & ReturnType<__sveltets_Render<Option, Value>['exports']>;
+    <Option extends RadioOption, Value extends string = Option['value']>(internal: unknown, props: ReturnType<__sveltets_Render<Option, Value>['props']> & {}): ReturnType<__sveltets_Render<Option, Value>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any, any>['bindings']>;
 }
 declare const RadioInput: $$IsomorphicComponent;
-type RadioInput<Option extends RadioOption> = InstanceType<typeof RadioInput<Option>>;
+type RadioInput<Option extends RadioOption, Value extends string = Option['value']> = InstanceType<typeof RadioInput<Option, Value>>;
 export default RadioInput;

package/dist/components/Form/RadioInput/radioInput.mcp.d.ts

@@ -1 +1 @@
-export declare const radioInputDescription = "\n# RadioInput Component\n\nThe RadioInput component provides a group of radio buttons for single-selection from multiple options.\n\n## Basic Usage\n\n```svelte\n<script>\n\tlet selected = $state('');\n</script>\n\n<RadioInput \n\tlabel=\"Choose a plan\"\n\tbind:value={selected}\n\titems={[\n\t\t{ value: 'free', label: 'Free' },\n\t\t{ value: 'pro', label: 'Pro' },\n\t\t{ value: 'enterprise', label: 'Enterprise' }\n\t]}\n/>\n```\n\n## Props\n\nExtends all Field component props plus:\n\n### Core Props\n- **value**: string (bindable) - Selected value\n- **items**: Array<{ value: string, label: string, description?: string, disabled?: boolean }> (required)\n\n### Layout Props\n- **mode**: 'normal' | 'card' (default: 'normal') - Visual layout style of the options\n\n### Field Props (inherited)\n- **label**: string | Snippet - Field label\n- **description**: string | Snippet - Helper text for the entire group\n- **error**: string - Error message\n- **required**: boolean - Mark as required\n- **disabled**: boolean - Disable all options\n- **size**: 'small' | 'normal' | 'large'\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: RadioInputThemeProps & FieldThemeProps - Custom theme overrides\n\n## Structure\n\n```\n<Field>\n\t<Label />\n\t<Description />\n\t<RadioGroup mode=\"...\">\n\t\t<Radio>\n\t\t\t<RadioIndicator />\n\t\t\t<RadioLabel />\n\t\t\t<RadioDescription />\n\t\t</Radio>\n\t\t<Radio>...</Radio>\n\t</RadioGroup>\n\t<Error />\n</Field>\n```\n\n## Examples\n\n### Basic Radio Group\n```svelte\n<script>\n\tlet plan = $state('pro');\n</script>\n\n<RadioInput \n\tlabel=\"Select a plan\"\n\tbind:value={plan}\n\titems={[\n\t\t{ value: 'free', label: 'Free' },\n\t\t{ value: 'pro', label: 'Pro' },\n\t\t{ value: 'enterprise', label: 'Enterprise' }\n\t]}\n/>\n```\n\n### With Descriptions\n```svelte\n<RadioInput \n\tlabel=\"Subscription\"\n\tbind:value={subscription}\n\titems={[\n\t\t{ \n\t\t\tvalue: 'monthly', \n\t\t\tlabel: 'Monthly',\n\t\t\tdescription: '$10/month, cancel anytime'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'yearly', \n\t\t\tlabel: 'Yearly',\n\t\t\tdescription: '$100/year, save $20'\n\t\t}\n\t]}\n/>\n```\n\n### Horizontal Layout\n```svelte\n<RadioInput \n\tlabel=\"Gender\"\n\tbind:value={gender}\n\ttheme={{ inputContainer: { base: 'grid-cols-3' } }}\n\titems={[\n\t\t{ value: 'male', label: 'Male' },\n\t\t{ value: 'female', label: 'Female' },\n\t\t{ value: 'other', label: 'Other' }\n\t]}\n/>\n```\n\n### Required Field\n```svelte\n<RadioInput \n\tlabel=\"Shipping Method\"\n\tbind:value={shipping}\n\trequired\n\titems={[\n\t\t{ value: 'standard', label: 'Standard (5-7 days)' },\n\t\t{ value: 'express', label: 'Express (2-3 days)' },\n\t\t{ value: 'overnight', label: 'Overnight' }\n\t]}\n/>\n```\n\n### With Disabled Options\n```svelte\n<RadioInput \n\tlabel=\"Seat Selection\"\n\tbind:value={seat}\n\titems={[\n\t\t{ value: 'window', label: 'Window' },\n\t\t{ value: 'aisle', label: 'Aisle' },\n\t\t{ value: 'middle', label: 'Middle', disabled: true }\n\t]}\n/>\n```\n\n### All Disabled\n```svelte\n<RadioInput \n\tlabel=\"Account Type\"\n\tvalue=\"premium\"\n\tdisabled\n\titems={[\n\t\t{ value: 'free', label: 'Free' },\n\t\t{ value: 'premium', label: 'Premium' }\n\t]}\n/>\n```\n\n### Payment Method Selector\n```svelte\n<script>\n\tlet paymentMethod = $state('card');\n</script>\n\n<RadioInput \n\tlabel=\"Payment Method\"\n\tbind:value={paymentMethod}\n\trequired\n\titems={[\n\t\t{ \n\t\t\tvalue: 'card', \n\t\t\tlabel: 'Credit/Debit Card',\n\t\t\tdescription: 'Visa, Mastercard, Amex'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'paypal', \n\t\t\tlabel: 'PayPal',\n\t\t\tdescription: 'Pay with your PayPal account'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'bank', \n\t\t\tlabel: 'Bank Transfer',\n\t\t\tdescription: '2-3 business days processing'\n\t\t}\n\t]}\n/>\n\n{#if paymentMethod === 'card'}\n\t<TextInput label=\"Card Number\" />\n\t<TextInput label=\"CVV\" />\n{:else if paymentMethod === 'paypal'}\n\t<TextInput type=\"email\" label=\"PayPal Email\" />\n{/if}\n```\n\n### Size Options\n```svelte\n<RadioInput \n\tlabel=\"T-Shirt Size\"\n\tbind:value={size}\n\trequired\n\titems={[\n\t\t{ value: 'xs', label: 'XS' },\n\t\t{ value: 's', label: 'S' },\n\t\t{ value: 'm', label: 'M' },\n\t\t{ value: 'l', label: 'L' },\n\t\t{ value: 'xl', label: 'XL' }\n\t]}\n/>\n```\n\n### Delivery Options\n```svelte\n<script>\n\tlet delivery = $state('');\n\t\n\tconst deliveryOptions = [\n\t\t{ \n\t\t\tvalue: 'pickup', \n\t\t\tlabel: 'Store Pickup',\n\t\t\tdescription: 'Free - Ready in 2 hours'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'standard', \n\t\t\tlabel: 'Standard Delivery',\n\t\t\tdescription: '$5.99 - 5-7 business days'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'express', \n\t\t\tlabel: 'Express Delivery',\n\t\t\tdescription: '$12.99 - 2-3 business days'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'overnight', \n\t\t\tlabel: 'Overnight',\n\t\t\tdescription: '$24.99 - Next day delivery'\n\t\t}\n\t];\n</script>\n\n<RadioInput \n\tlabel=\"Delivery Method\"\n\tbind:value={delivery}\n\titems={deliveryOptions}\n\trequired\n/>\n```\n\n### Survey Question\n```svelte\n<RadioInput \n\tlabel=\"How satisfied are you with our service?\"\n\tbind:value={satisfaction}\n\trequired\n\titems={[\n\t\t{ value: '5', label: 'Very Satisfied' },\n\t\t{ value: '4', label: 'Satisfied' },\n\t\t{ value: '3', label: 'Neutral' },\n\t\t{ value: '2', label: 'Dissatisfied' },\n\t\t{ value: '1', label: 'Very Dissatisfied' }\n\t]}\n/>\n```\n\n### Settings Radio Group\n```svelte\n<RadioInput \n\tlabel=\"Notification Frequency\"\n\tbind:value={frequency}\n\tdescription=\"Choose how often you want to receive notifications\"\n\titems={[\n\t\t{ \n\t\t\tvalue: 'realtime', \n\t\t\tlabel: 'Real-time',\n\t\t\tdescription: 'Instant notifications'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'hourly', \n\t\t\tlabel: 'Hourly',\n\t\t\tdescription: 'Digest every hour'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'daily', \n\t\t\tlabel: 'Daily',\n\t\t\tdescription: 'Once per day'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'never', \n\t\t\tlabel: 'Never',\n\t\t\tdescription: 'Disable notifications'\n\t\t}\n\t]}\n/>\n```\n\n## Validation\n\nRadioInput automatically validates:\n- **required**: A value must be selected\n\n## Keyboard Navigation\n\n- **Arrow keys**: Navigate between options\n- **Space**: Select focused option\n- **Tab**: Move focus to next element\n\n## Accessibility\n\n- Proper radio group semantics\n- ARIA attributes for required state\n- Keyboard navigation support\n- Focus management\n- Screen reader announcements\n- Disabled options communicated properly\n\n## Notes\n\n- Only one option can be selected at a time\n- Each option can have its own description\n- Individual options can be disabled\n- Supports both vertical and horizontal layouts\n- Works seamlessly with Form component\n\n## Theme Customization\n\nThe RadioInput component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **root**: Main container styles\n- **radiosInputContainer**: Options grid container styles\n- **radiosInputItem**: Individual radio wrapper styles\n- **radiosInputItemTrack**: Radio button track/background styles\n- **radiosInputItemThumb**: Radio button indicator styles\n- **radiosInputItemLabel**: Label text styles\n- **radiosInputItemDescription**: Description text styles\n- **radiosInputItemIcon**: Icon styling\n\n### Available Variants\n\n**root**:\n- base: Base classes for main container\n- Variants:\n  - mode: 'card' | 'normal' - Layout mode\n\n**radiosInputContainer**:\n- base: Base classes for options grid container\n- Variants:\n  - mode: 'card' | 'normal' - Grid layout based on mode\n  - disabled: boolean - Disabled state styling\n\n**radiosInputItem**:\n- base: Base classes for individual radio wrapper\n- Variants:\n  - mode: 'card' | 'normal' - Item styling based on mode\n  - checked: boolean - Selected state styling\n  - disabled: boolean - Disabled state styling\n\n**radiosInputItemTrack**:\n- base: Base classes for radio track/background\n- Variants:\n  - checked: boolean - Track styling when checked\n  - mode: 'card' | 'normal' - Mode-based styling\n  - disabled: boolean - Disabled state styling\n\n**radiosInputItemThumb**:\n- base: Base classes for radio indicator\n- Variants:\n  - checked: boolean - Visibility and styling when checked\n  - mode: 'card' | 'normal' - Mode-based styling\n  - disabled: boolean - Disabled state styling\n\n**radiosInputItemLabel**:\n- base: Base classes for label text\n\n**radiosInputItemDescription**:\n- base: Base classes for description text\n\n**radiosInputItemIcon**:\n- base: Base classes for icon styling\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<RadioInput \n  label=\"Choose Option\"\n  bind:value={value}\n  items={items}\n  theme={{\n    // The option grid lays itself out against its OWN width, not the viewport: declare the\n    // container on the root and query it on the grid, so the columns follow the field's host\n    // (a sidebar, a split pane, a dialog) instead of the device.\n    root: { base: '@container' },\n    radiosInputContainer: {\n      base: 'grid-cols-1 @md:grid-cols-3 gap-lg'\n    },\n    radiosInputItem: {\n      mode: {\n        card: 'rounded-lg border-2'\n      }\n    }\n  }}\n/>\n```\n\n**Card Mode Customization**:\n```svelte\n<RadioInput \n  mode=\"card\"\n  label=\"Plan\"\n  bind:value={plan}\n  items={items}\n  theme={{\n    radiosInputItem: {\n      checked: {\n        true: 'ring-2 ring-primary bg-primary/10'\n      },\n      mode: {\n        card: 'rounded-xl raised-3 hover:raised-4'\n      }\n    },\n    radiosInputItemThumb: {\n      checked: {\n        true: 'bg-primary scale-[60%]'\n      }\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setRadioInputTheme } from './index.ts';\n  \n  setRadioInputTheme({\n    root: { base: '@container' },\n    radiosInputContainer: {\n      base: 'gap-lg',\n      mode: {\n        card: 'grid-cols-1 @2xl:grid-cols-2'\n      }\n    },\n    radiosInputItem: {\n      mode: {\n        card: 'rounded-lg transition-all'\n      }\n    }\n  });\n</script>\n```\n\n## State contract\n\n- **value**: current bindable editable value.\n- **defaultValue**: initial value used only when `value` is omitted.\n- **onValueChange**: called with the new value when the component changes it.\n\n";
+export declare const radioInputDescription = "\n# RadioInput Component\n\nThe RadioInput component provides a group of radio buttons for single-selection from multiple options.\n\n## Basic Usage\n\n```svelte\n<script>\n\tlet selected = $state('');\n</script>\n\n<RadioInput \n\tlabel=\"Choose a plan\"\n\tbind:value={selected}\n\titems={[\n\t\t{ value: 'free', label: 'Free' },\n\t\t{ value: 'pro', label: 'Pro' },\n\t\t{ value: 'enterprise', label: 'Enterprise' }\n\t]}\n/>\n```\n\n## Props\n\nExtends all Field component props plus:\n\n### Core Props\n- **value**: string | null (bindable) - Selected value. Typed from the options: with literal option values (for example `value: 'free'` and `value: 'pro'`) it is `'free' | 'pro' | null`, and `onValueChange` receives that union, or `null` when the group is cleared. A variable typed as plain `string` still binds\n- **items**: Array<{ value: string, label: string, description?: string, disabled?: boolean }> (required). A disabled option cannot be selected; when it is the selected one, a native `<form>` leaves it out of its submission (like a disabled native radio) while the field value, and so an entasis Form value, keeps it\n\n### Layout Props\n- **mode**: 'normal' | 'card' (default: 'normal') - Visual layout style of the options\n\n### Field Props (inherited)\n- **label**: string | Snippet - Field label\n- **description**: string | Snippet - Helper text for the entire group\n- **error**: string - Error message\n- **required**: boolean - Mark as required\n- **disabled**: boolean - Disable all options. A disabled group is left out of the submitted Form value and skips validation\n- **readOnly**: boolean - Keeps the group focusable and announced (`aria-readonly` on the radiogroup) while selecting does nothing: arrow keys move focus without checking, clicks are ignored. The value still validates and submits\n- **size**: 'small' | 'normal' | 'large'\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: RadioInputThemeProps & FieldThemeProps - Custom theme overrides\n\n## Structure\n\n```\n<Field>\n\t<Label />\n\t<Description />\n\t<RadioGroup mode=\"...\">\n\t\t<Radio>\n\t\t\t<RadioIndicator />\n\t\t\t<RadioLabel />\n\t\t\t<RadioDescription />\n\t\t</Radio>\n\t\t<Radio>...</Radio>\n\t</RadioGroup>\n\t<Error />\n</Field>\n```\n\n## Examples\n\n### Basic Radio Group\n```svelte\n<script>\n\tlet plan = $state('pro');\n</script>\n\n<RadioInput \n\tlabel=\"Select a plan\"\n\tbind:value={plan}\n\titems={[\n\t\t{ value: 'free', label: 'Free' },\n\t\t{ value: 'pro', label: 'Pro' },\n\t\t{ value: 'enterprise', label: 'Enterprise' }\n\t]}\n/>\n```\n\n### With Descriptions\n```svelte\n<RadioInput \n\tlabel=\"Subscription\"\n\tbind:value={subscription}\n\titems={[\n\t\t{ \n\t\t\tvalue: 'monthly', \n\t\t\tlabel: 'Monthly',\n\t\t\tdescription: '$10/month, cancel anytime'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'yearly', \n\t\t\tlabel: 'Yearly',\n\t\t\tdescription: '$100/year, save $20'\n\t\t}\n\t]}\n/>\n```\n\n### Horizontal Layout\n```svelte\n<RadioInput \n\tlabel=\"Gender\"\n\tbind:value={gender}\n\ttheme={{ inputContainer: { base: 'grid-cols-3' } }}\n\titems={[\n\t\t{ value: 'male', label: 'Male' },\n\t\t{ value: 'female', label: 'Female' },\n\t\t{ value: 'other', label: 'Other' }\n\t]}\n/>\n```\n\n### Required Field\n```svelte\n<RadioInput \n\tlabel=\"Shipping Method\"\n\tbind:value={shipping}\n\trequired\n\titems={[\n\t\t{ value: 'standard', label: 'Standard (5-7 days)' },\n\t\t{ value: 'express', label: 'Express (2-3 days)' },\n\t\t{ value: 'overnight', label: 'Overnight' }\n\t]}\n/>\n```\n\n### With Disabled Options\n```svelte\n<RadioInput \n\tlabel=\"Seat Selection\"\n\tbind:value={seat}\n\titems={[\n\t\t{ value: 'window', label: 'Window' },\n\t\t{ value: 'aisle', label: 'Aisle' },\n\t\t{ value: 'middle', label: 'Middle', disabled: true }\n\t]}\n/>\n```\n\n### All Disabled\n```svelte\n<RadioInput \n\tlabel=\"Account Type\"\n\tvalue=\"premium\"\n\tdisabled\n\titems={[\n\t\t{ value: 'free', label: 'Free' },\n\t\t{ value: 'premium', label: 'Premium' }\n\t]}\n/>\n```\n\n### Payment Method Selector\n```svelte\n<script>\n\tlet paymentMethod = $state('card');\n</script>\n\n<RadioInput \n\tlabel=\"Payment Method\"\n\tbind:value={paymentMethod}\n\trequired\n\titems={[\n\t\t{ \n\t\t\tvalue: 'card', \n\t\t\tlabel: 'Credit/Debit Card',\n\t\t\tdescription: 'Visa, Mastercard, Amex'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'paypal', \n\t\t\tlabel: 'PayPal',\n\t\t\tdescription: 'Pay with your PayPal account'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'bank', \n\t\t\tlabel: 'Bank Transfer',\n\t\t\tdescription: '2-3 business days processing'\n\t\t}\n\t]}\n/>\n\n{#if paymentMethod === 'card'}\n\t<TextInput label=\"Card Number\" />\n\t<TextInput label=\"CVV\" />\n{:else if paymentMethod === 'paypal'}\n\t<TextInput type=\"email\" label=\"PayPal Email\" />\n{/if}\n```\n\n### Size Options\n```svelte\n<RadioInput \n\tlabel=\"T-Shirt Size\"\n\tbind:value={size}\n\trequired\n\titems={[\n\t\t{ value: 'xs', label: 'XS' },\n\t\t{ value: 's', label: 'S' },\n\t\t{ value: 'm', label: 'M' },\n\t\t{ value: 'l', label: 'L' },\n\t\t{ value: 'xl', label: 'XL' }\n\t]}\n/>\n```\n\n### Delivery Options\n```svelte\n<script>\n\tlet delivery = $state('');\n\t\n\tconst deliveryOptions = [\n\t\t{ \n\t\t\tvalue: 'pickup', \n\t\t\tlabel: 'Store Pickup',\n\t\t\tdescription: 'Free - Ready in 2 hours'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'standard', \n\t\t\tlabel: 'Standard Delivery',\n\t\t\tdescription: '$5.99 - 5-7 business days'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'express', \n\t\t\tlabel: 'Express Delivery',\n\t\t\tdescription: '$12.99 - 2-3 business days'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'overnight', \n\t\t\tlabel: 'Overnight',\n\t\t\tdescription: '$24.99 - Next day delivery'\n\t\t}\n\t];\n</script>\n\n<RadioInput \n\tlabel=\"Delivery Method\"\n\tbind:value={delivery}\n\titems={deliveryOptions}\n\trequired\n/>\n```\n\n### Survey Question\n```svelte\n<RadioInput \n\tlabel=\"How satisfied are you with our service?\"\n\tbind:value={satisfaction}\n\trequired\n\titems={[\n\t\t{ value: '5', label: 'Very Satisfied' },\n\t\t{ value: '4', label: 'Satisfied' },\n\t\t{ value: '3', label: 'Neutral' },\n\t\t{ value: '2', label: 'Dissatisfied' },\n\t\t{ value: '1', label: 'Very Dissatisfied' }\n\t]}\n/>\n```\n\n### Settings Radio Group\n```svelte\n<RadioInput \n\tlabel=\"Notification Frequency\"\n\tbind:value={frequency}\n\tdescription=\"Choose how often you want to receive notifications\"\n\titems={[\n\t\t{ \n\t\t\tvalue: 'realtime', \n\t\t\tlabel: 'Real-time',\n\t\t\tdescription: 'Instant notifications'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'hourly', \n\t\t\tlabel: 'Hourly',\n\t\t\tdescription: 'Digest every hour'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'daily', \n\t\t\tlabel: 'Daily',\n\t\t\tdescription: 'Once per day'\n\t\t},\n\t\t{ \n\t\t\tvalue: 'never', \n\t\t\tlabel: 'Never',\n\t\t\tdescription: 'Disable notifications'\n\t\t}\n\t]}\n/>\n```\n\n## Validation\n\nRadioInput automatically validates:\n- **required**: A value must be selected\n\n## Keyboard Navigation\n\n- **Arrow keys**: Navigate between options\n- **Space**: Select focused option\n- **Tab**: Move focus to next element\n\n## Accessibility\n\n- The fieldset is the `radiogroup`: `aria-required` and `aria-readonly` sit on it (never on a radio), and `aria-labelledby` points at the label only when one is rendered\n- Each option is named by its label text (`aria-labelledby`, with the value as a fallback `aria-label` for an option without a label) and described by its description (`aria-describedby`)\n- Keyboard: the group is one Tab stop, on the checked option, or the first enabled one when nothing is checked. ArrowDown and ArrowRight move to the next enabled option and check it, ArrowUp and ArrowLeft go back, and Home and End jump to the ends; the keys wrap, and Left and Right swap in right-to-left layouts. Tabbing in, focusing or clicking never changes the selection beyond what was clicked, arrows held with Alt, Ctrl or Meta are left to the browser, and with `readOnly` focus moves without checking. Space checks the focused option\n- Enter does not select. Like a native radio it continues the form: inside an entasis Form it validates the field and moves focus to the next one (the last field submits), and inside a plain `<form>` it clicks the form's default submit button\n- Disabled options are skipped by the arrows and communicated as disabled\n- The submitted value is one hidden input beside the options (never inside a button); a required group blocks a native submit while nothing is selected and hands the browser's report to the Tab stop\n- Each option button gets an id unique to the instance (`<field id>-option-<index>`), so two fields with the same `name` or values containing spaces never produce duplicate or invalid ids\n- When an entasis Form finds the group invalid, it focuses the checked option\n\n## Notes\n\n- Only one option can be selected at a time\n- Each option can have its own description\n- Individual options can be disabled\n- Supports both vertical and horizontal layouts\n- Works seamlessly with Form component\n\n## Theme Customization\n\nThe RadioInput component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **root**: Main container styles\n- **radiosInputContainer**: Options grid container styles\n- **radiosInputItem**: Individual radio wrapper styles\n- **radiosInputItemTrack**: Radio button track/background styles\n- **radiosInputItemThumb**: Radio button indicator styles\n- **radiosInputItemLabel**: Label text styles\n- **radiosInputItemDescription**: Description text styles\n- **radiosInputItemIcon**: Icon styling\n\n### Available Variants\n\n**root**:\n- base: Base classes for main container\n- Variants:\n  - mode: 'card' | 'normal' - Layout mode\n\n**radiosInputContainer**:\n- base: Base classes for options grid container\n- Variants:\n  - mode: 'card' | 'normal' - Grid layout based on mode\n  - disabled: boolean - Disabled state styling\n\n**radiosInputItem**:\n- base: Base classes for individual radio wrapper\n- Variants:\n  - mode: 'card' | 'normal' - Item styling based on mode\n  - checked: boolean - Selected state styling\n  - disabled: boolean - Disabled state styling\n\n**radiosInputItemTrack**:\n- base: Base classes for radio track/background\n- Variants:\n  - checked: boolean - Track styling when checked\n  - mode: 'card' | 'normal' - Mode-based styling\n  - disabled: boolean - Disabled state styling\n\n**radiosInputItemThumb**:\n- base: Base classes for radio indicator\n- Variants:\n  - checked: boolean - Visibility and styling when checked\n  - mode: 'card' | 'normal' - Mode-based styling\n  - disabled: boolean - Disabled state styling\n\n**radiosInputItemLabel**:\n- base: Base classes for label text\n\n**radiosInputItemDescription**:\n- base: Base classes for description text\n\n**radiosInputItemIcon**:\n- base: Base classes for icon styling\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<RadioInput \n  label=\"Choose Option\"\n  bind:value={value}\n  items={items}\n  theme={{\n    // The option grid lays itself out against its OWN width, not the viewport: declare the\n    // container on the root and query it on the grid, so the columns follow the field's host\n    // (a sidebar, a split pane, a dialog) instead of the device.\n    root: { base: '@container' },\n    radiosInputContainer: {\n      base: 'grid-cols-1 @md:grid-cols-3 gap-lg'\n    },\n    radiosInputItem: {\n      mode: {\n        card: 'rounded-lg border-2'\n      }\n    }\n  }}\n/>\n```\n\n**Card Mode Customization**:\n```svelte\n<RadioInput \n  mode=\"card\"\n  label=\"Plan\"\n  bind:value={plan}\n  items={items}\n  theme={{\n    radiosInputItem: {\n      checked: {\n        true: 'ring-2 ring-primary bg-primary/10'\n      },\n      mode: {\n        card: 'rounded-xl raised-3 hover:raised-4'\n      }\n    },\n    radiosInputItemThumb: {\n      checked: {\n        true: 'bg-primary scale-[60%]'\n      }\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setRadioInputTheme } from './index.ts';\n  \n  setRadioInputTheme({\n    root: { base: '@container' },\n    radiosInputContainer: {\n      base: 'gap-lg',\n      mode: {\n        card: 'grid-cols-1 @2xl:grid-cols-2'\n      }\n    },\n    radiosInputItem: {\n      mode: {\n        card: 'rounded-lg transition-all'\n      }\n    }\n  });\n</script>\n```\n\n## State contract\n\n- **value**: current bindable editable value.\n- **defaultValue**: initial value used only when `value` is omitted.\n- **onValueChange**: called with the new value when the component changes it.\n\n";

package/dist/components/Form/RadioInput/radioInput.mcp.js

@@ -26,8 +26,8 @@ The RadioInput component provides a group of radio buttons for single-selection
 Extends all Field component props plus:
 
 ### Core Props
-- **value**: string (bindable) - Selected value
-- **items**: Array<{ value: string, label: string, description?: string, disabled?: boolean }> (required)
+- **value**: string | null (bindable) - Selected value. Typed from the options: with literal option values (for example \`value: 'free'\` and \`value: 'pro'\`) it is \`'free' | 'pro' | null\`, and \`onValueChange\` receives that union, or \`null\` when the group is cleared. A variable typed as plain \`string\` still binds
+- **items**: Array<{ value: string, label: string, description?: string, disabled?: boolean }> (required). A disabled option cannot be selected; when it is the selected one, a native \`<form>\` leaves it out of its submission (like a disabled native radio) while the field value, and so an entasis Form value, keeps it
 
 ### Layout Props
 - **mode**: 'normal' | 'card' (default: 'normal') - Visual layout style of the options
@@ -37,7 +37,8 @@ Extends all Field component props plus:
 - **description**: string | Snippet - Helper text for the entire group
 - **error**: string - Error message
 - **required**: boolean - Mark as required
-- **disabled**: boolean - Disable all options
+- **disabled**: boolean - Disable all options. A disabled group is left out of the submitted Form value and skips validation
+- **readOnly**: boolean - Keeps the group focusable and announced (\`aria-readonly\` on the radiogroup) while selecting does nothing: arrow keys move focus without checking, clicks are ignored. The value still validates and submits
 - **size**: 'small' | 'normal' | 'large'
 
 ### Styling Props
@@ -305,12 +306,14 @@ RadioInput automatically validates:
 
 ## Accessibility
 
-- Proper radio group semantics
-- ARIA attributes for required state
-- Keyboard navigation support
-- Focus management
-- Screen reader announcements
-- Disabled options communicated properly
+- The fieldset is the \`radiogroup\`: \`aria-required\` and \`aria-readonly\` sit on it (never on a radio), and \`aria-labelledby\` points at the label only when one is rendered
+- Each option is named by its label text (\`aria-labelledby\`, with the value as a fallback \`aria-label\` for an option without a label) and described by its description (\`aria-describedby\`)
+- Keyboard: the group is one Tab stop, on the checked option, or the first enabled one when nothing is checked. ArrowDown and ArrowRight move to the next enabled option and check it, ArrowUp and ArrowLeft go back, and Home and End jump to the ends; the keys wrap, and Left and Right swap in right-to-left layouts. Tabbing in, focusing or clicking never changes the selection beyond what was clicked, arrows held with Alt, Ctrl or Meta are left to the browser, and with \`readOnly\` focus moves without checking. Space checks the focused option
+- Enter does not select. Like a native radio it continues the form: inside an entasis Form it validates the field and moves focus to the next one (the last field submits), and inside a plain \`<form>\` it clicks the form's default submit button
+- Disabled options are skipped by the arrows and communicated as disabled
+- The submitted value is one hidden input beside the options (never inside a button); a required group blocks a native submit while nothing is selected and hands the browser's report to the Tab stop
+- Each option button gets an id unique to the instance (\`<field id>-option-<index>\`), so two fields with the same \`name\` or values containing spaces never produce duplicate or invalid ids
+- When an entasis Form finds the group invalid, it focuses the checked option
 
 ## Notes
 

package/dist/components/Form/RadioInput/radioInput.props.d.ts

@@ -1,23 +1,39 @@
 import type { Slot } from '../../Slot/slot.js';
 import type { InputProps } from '../Field/field.js';
 import type { RadioInputThemeProps } from './radioInput.theme.js';
-export type RadioOption = {
+export type RadioOption<Value extends string = string> = {
     /** Display text for the option, rendered inside the option button. */
     label?: string;
-    /** Unique value submitted when this option is selected. */
-    value: string;
+    /** Unique value of this option, committed when it is selected. */
+    value: Value;
     /** Optional icon snippet shown before the option label. */
     icon?: Slot;
     /** Supporting text rendered below the option label. */
     description?: string;
-    /** Prevents selecting this individual option. */
+    /**
+     * Prevents selecting this individual option. A native `<form>` leaves a disabled selected
+     * option out of its submission, while the field value (and so an entasis Form's value) keeps it.
+     */
     disabled?: boolean;
 };
-export type RadioInputProps<T extends RadioOption = RadioOption> = Omit<InputProps<'radio'>, 'theme'> & {
+export type RadioInputProps<T extends RadioOption = RadioOption, Value extends string = T['value']> = Omit<InputProps<'radio'>, 'theme' | 'value' | 'defaultValue' | 'onValueChange'> & {
     /** Visual layout style for the radio group (`normal` or `card`). */
     mode?: 'card' | 'normal';
     /** Items to render as radio choices. */
-    items: T[];
+    items: readonly (T & RadioOption<Value>)[];
+    /**
+     * Selected option value, bindable with `bind:value`; `null` while nothing is selected. Typed
+     * from the options' `value`s, so literal values (`items` declared `as const`, or with literal
+     * `value`s) give a union of them.
+     */
+    value?: Value | null;
+    /** Initial selected value when `value` is omitted. */
+    defaultValue?: Value | null;
+    /**
+     * Called when the value changes: with the selected option's value, or `null` when the group is
+     * cleared (for example through `field.setValue(null)`).
+     */
+    onValueChange?: (value: Value | null) => void;
     /**
      * Theme overrides for the radio group's own slots plus the Field parts (label,
      * inputContainer, error, ...) the group is wrapped in.

package/dist/components/Form/RadioInput/radioInput.theme.d.ts

@@ -24,6 +24,10 @@ export declare const radioInputTheme: {
             true: string;
             false: string;
         };
+        readOnly: {
+            true: string;
+            false: string;
+        };
     }> & import("../../../utils/cva/types.js").CVAClassProp) | undefined) => string;
     radiosInputItemLabel: (props?: (import("../../../utils/cva/types.js").CVAVariantSchema<{
         size: {
@@ -119,6 +123,10 @@ export declare const setRadioInputTheme: (theme: InferComponentTheme<{
             true: string;
             false: string;
         };
+        readOnly: {
+            true: string;
+            false: string;
+        };
     }> & import("../../../utils/cva/types.js").CVAClassProp) | undefined) => string;
     radiosInputItemLabel: (props?: (import("../../../utils/cva/types.js").CVAVariantSchema<{
         size: {
@@ -212,6 +220,10 @@ export declare const useRadioInputTheme: import("../../../utils/cva/theme.js").U
             true: string;
             false: string;
         };
+        readOnly: {
+            true: string;
+            false: string;
+        };
     }> & import("../../../utils/cva/types.js").CVAClassProp) | undefined) => string;
     radiosInputItemLabel: (props?: (import("../../../utils/cva/types.js").CVAVariantSchema<{
         size: {

package/dist/components/Form/RadioInput/radioInput.theme.js

@@ -10,11 +10,11 @@ const defaultRadioInput = cva({
     }
 });
 const defaultRadioInputItem = cva({
-    base: 'relative grid w-full cursor-pointer items-start gap-xs rounded-md text-left transition-[color,background-color,box-shadow,opacity] outline-none focus-visible:ring-2 focus-visible:ring-focus/50',
+    base: 'relative grid w-full cursor-pointer items-start gap-xs rounded-md text-start transition-[color,background-color,box-shadow,opacity] outline-none focus-visible:ring-2 focus-visible:ring-focus/50',
     variants: {
         mode: {
-            card: 'raised bg-surface-raised py-md pl-layout-lg',
-            normal: 'py-xs pl-layout-xl'
+            card: 'raised bg-surface-raised py-md ps-layout-lg',
+            normal: 'py-xs ps-layout-xl'
         },
         size: {
             small: 'min-h-row-sm',
@@ -28,6 +28,11 @@ const defaultRadioInputItem = cva({
         disabled: {
             true: 'cursor-not-allowed opacity-50',
             false: ''
+        },
+        // Focusable and announced, but not changeable: no pointer cursor promising a selection.
+        readOnly: {
+            true: 'cursor-default',
+            false: ''
         }
     },
     defaultVariants: {
@@ -55,7 +60,7 @@ const defaultRadioInputItemLabel = cva({
     }
 });
 const defaultRadioInputItemTrack = cva({
-    base: 'origin-center content-[""] bg-surface-raised border border-neutral-muted rounded-full absolute left-2',
+    base: 'origin-center content-[""] bg-surface-raised border border-neutral-muted rounded-full absolute start-2',
     variants: {
         checked: {
             true: '',
@@ -94,7 +99,7 @@ const defaultRadioInputItemTrack = cva({
     ]
 });
 const defaultRadioInputItemThumb = cva({
-    base: 'origin-center radio rounded-full transition-[background-color,opacity,scale] content-[""] absolute left-2 scale-[40%] opacity-0',
+    base: 'origin-center radio rounded-full transition-[background-color,opacity,scale] content-[""] absolute start-2 scale-[40%] opacity-0',
     variants: {
         checked: {
             true: 'bg-selected scale-[60%] opacity-100',

package/dist/components/Form/RatingInput/RatingInput.svelte

@@ -14,13 +14,15 @@
 		required = false,
 		theme,
 		disabled,
+		readOnly,
+		messages,
 		name,
 		onValidate,
 		onValueChange,
 		visible,
 		max = 5,
 		halfSteps = false,
-		readonly = false,
+		readonly,
 		clearable = true,
 		dir,
 		color = 'warning',
@@ -60,6 +62,13 @@
 		set disabled(v: boolean | undefined) {
 			disabled = v;
 		},
+		// `readonly` is the deprecated spelling, still honoured for one minor.
+		get readOnly() {
+			return readOnly ?? readonly;
+		},
+		get messages() {
+			return messages;
+		},
 		get required() {
 			return required;
 		},
@@ -100,7 +109,7 @@
 	let previewValue = $state<number | null>(null);
 	const displayValue = $derived(previewValue ?? field.value ?? 0);
 	const step = $derived(halfSteps ? 0.5 : 1);
-	const interactive = $derived(!readonly && !field.disabled);
+	const interactive = $derived(!field.readOnly && !field.disabled);
 
 	// Resolve the effective reading direction: explicit prop, else the ambient direction.
 	const isRtl = () => {
@@ -193,14 +202,14 @@
 		onclick={handleClick}
 		{id}
 		role="slider"
-		tabindex={readonly || field.disabled ? -1 : 0}
+		tabindex={field.disabled ? -1 : 0}
 		aria-label={label ? undefined : resolvedLabel}
 		aria-valuemin={0}
 		aria-valuemax={max}
 		aria-valuenow={field.value ?? 0}
 		aria-valuetext={`${field.value ?? 0} ${t.of} ${max}`}
 		aria-orientation="horizontal"
-		aria-readonly={readonly || undefined}
+		aria-readonly={field.readOnly || undefined}
 		aria-disabled={field.disabled || undefined}
 		onkeydown={handleKeydown}
 		onpointerleave={handlePointerLeave}

package/dist/components/Form/RatingInput/ratingInput.mcp.d.ts

@@ -1 +1 @@
-export declare const ratingInputDescription = "\n# RatingInput Component\n\nThe RatingInput component is a star rating field with optional half-star support, a configurable star count, and full RTL support. Its value is a number.\n\n## Basic Usage\n\n```svelte\n<script>\n\tlet rating = $state(3);\n</script>\n\n<RatingInput label=\"Rating\" bind:value={rating} />\n```\n\n## Props\n\nExtends all Field component props plus:\n\n### Core Props\n- **value**: number | null (bindable, default null) - Current rating; null (or 0) means \"no rating\"\n- **max**: number (default: 5) - Number of stars, which is also the maximum value\n- **halfSteps**: boolean (default: false) - When true the value snaps to 0.5 increments (half stars)\n- **readonly**: boolean (default: false) - Displays the value without allowing interaction (aria-readonly=true); still shows the stars\n- **clearable**: boolean (default: true) - When true, clicking the exact current value clears it back to null\n- **dir**: 'ltr' | 'rtl' - Reading direction override; inherits the ambient direction when omitted\n- **color**: Colors (default: 'warning') - Color of the filled stars (the classic gold/amber star)\n\n### Content Props (Slots)\n- **star**: Snippet<[{ index, fraction, layer }]> (optional) - Custom star icon, forwarded to the underlying Rating display component. Rendered twice per star: once for the muted outline (layer: 'base') and once for the colored fill overlay (layer: 'fill'). See the Rating component docs for an example.\n\n### Field Props (inherited)\n- **label**: string | Snippet - Field label\n- **description**: string | Snippet - Helper text\n- **required**: boolean - Mark as required (a required rating must be at least half a star)\n- **disabled**: boolean - Disable input\n- **size**: 'small' | 'normal' | 'large' - Star size\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n- **i18n**: Partial<Messages> - Per-instance i18n overrides\n\n## Examples\n\n### Basic Rating (integer)\n```svelte\n<RatingInput label=\"Rating\" bind:value={rating} max={5} />\n```\n\n### Half Steps\n```svelte\n<RatingInput label=\"Rating\" bind:value={rating} halfSteps />\n```\n\n### Half Steps in RTL (fills from the right)\n```svelte\n<RatingInput label=\"Rating\" bind:value={rating} halfSteps dir=\"rtl\" />\n```\n\n### Custom Star Count\n```svelte\n<RatingInput label=\"Score\" bind:value={score} max={10} />\n```\n\n### Readonly\n```svelte\n<RatingInput label=\"Average\" value={4.5} halfSteps readonly />\n```\n\n### Disabled\n```svelte\n<RatingInput label=\"Rating\" value={3} disabled />\n```\n\n### Required (inside a Form)\n```svelte\n<Form inputs={{ rating: { type: 'rating', label: 'Rating', required: true } }} />\n```\n\n## Keyboard Interactions\n\nThe rating row is a single tab stop with `role=\"slider\"`.\n\n- **Arrow Right / Arrow Up**: Increase the value by the step (0.5 when halfSteps, else 1)\n- **Arrow Left / Arrow Down**: Decrease the value by the step\n- **Home**: Clear the value (sets it to null)\n- **End**: Set the value to max\n\nValue semantics do NOT flip in RTL: Arrow Right always increases the numeric value. Only the visual fill is mirrored.\n\n## Accessibility\n\n- The row container carries `role=\"slider\"` and is the single focusable element (`tabindex` 0 when interactive, -1 when readonly/disabled)\n- ARIA: `aria-valuemin={0}`, `aria-valuemax={max}`, `aria-valuenow`, `aria-valuetext`, `aria-orientation=\"horizontal\"`, `aria-readonly`, `aria-disabled`\n- Individual stars are `aria-hidden` and not focusable; the pointer selects a value and half-star hits are computed from the pointer position within each star\n- Clicking a star focuses the slider container (native focus fixup), so arrow keys work immediately after a pointer selection and `focused` becomes true \u2014 same as clicking a text input\n\n## RTL\n\nWhen the effective direction is RTL (via the `dir` prop or the inherited ambient direction), the stars render right-to-left and the fill grows from the right. The fill uses the CSS logical property `inset-inline-start`, so the visual mirroring is automatic. Note again: the numeric value is unaffected by direction \u2014 only the visual fill mirrors.\n\n## Half Steps\n\nWith `halfSteps`, the left half of a star (in the reading direction) selects n-0.5 and the right half selects n. The fill is rendered with an overflow-hidden clip whose width is the star's fill fraction, giving exact 0.5 (and arbitrary partial) fills.\n\n## Theme Customization\n\nThe RatingInput component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **container**: The flex row of stars (gap + focus ring)\n- **star**: The fixed-size box wrapping one star (cursor-pointer when interactive)\n- **starBase**: The outline (empty) star color\n- **starFill**: The filled star, driven by the `color` variant\n\n### Available Variants\n\n**container**:\n- size: 'small' | 'normal' | 'large' - Gap between stars\n- disabled: boolean - Disabled state styling\n\n**star**:\n- size: 'small' | 'normal' | 'large' - Star box size\n- interactive: boolean - cursor-pointer when interactive\n\n**starFill**:\n- color: Colors - Fill color of the star (defaults to 'warning')\n\n### Global Theme Setting\n\nThe star rendering lives in the `Rating` display component, so the theme is shared: set it once and both `Rating` and `RatingInput` pick it up.\n\n```svelte\n<script>\n\timport { setRatingTheme } from 'entasis/rating-input'; // also exported from 'entasis/rating'\n\n\tsetRatingTheme({\n\t\tstarFill: {\n\t\t\tcolor: {\n\t\t\t\tprimary: 'text-primary'\n\t\t\t}\n\t\t}\n\t});\n</script>\n```\n\n## State contract\n\n- **value**: current bindable editable value.\n- **defaultValue**: initial value used only when `value` is omitted.\n- **onValueChange**: called with the new value when the component changes it.\n\n";
+export declare const ratingInputDescription = "\n# RatingInput Component\n\nThe RatingInput component is a star rating field with optional half-star support, a configurable star count, and full RTL support. Its value is a number.\n\n## Basic Usage\n\n```svelte\n<script>\n\tlet rating = $state(3);\n</script>\n\n<RatingInput label=\"Rating\" bind:value={rating} />\n```\n\n## Props\n\nExtends all Field component props plus:\n\n### Core Props\n- **value**: number | null (bindable, default null) - Current rating; null (or 0) means \"no rating\"\n- **max**: number (default: 5) - Number of stars, which is also the maximum value\n- **halfSteps**: boolean (default: false) - When true the value snaps to 0.5 increments (half stars)\n- **readOnly**: boolean (default: false) - Shows the value without letting the user change it: the stars stay focusable with aria-readonly=\"true\", pointer and keys change nothing, and the value still validates and submits. A read-only Form or FormGroup makes it read-only too. `readonly` is a deprecated alias kept for one minor\n- **clearable**: boolean (default: true) - When true, clicking the exact current value clears it back to null\n- **dir**: 'ltr' | 'rtl' - Reading direction override; inherits the ambient direction when omitted\n- **color**: Colors (default: 'warning') - Color of the filled stars (the classic gold/amber star)\n\n### Content Props (Slots)\n- **star**: Snippet<[{ index, fraction, layer }]> (optional) - Custom star icon, forwarded to the underlying Rating display component. Rendered twice per star: once for the muted outline (layer: 'base') and once for the colored fill overlay (layer: 'fill'). See the Rating component docs for an example.\n\n### Field Props (inherited)\n- **label**: string | Snippet - Field label\n- **description**: string | Snippet - Helper text\n- **required**: boolean - Mark as required (a required rating must be at least half a star)\n- **disabled**: boolean - Disable input\n- **size**: 'small' | 'normal' | 'large' - Star size\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n- **i18n**: Partial<Messages> - Per-instance i18n overrides\n\n## Examples\n\n### Basic Rating (integer)\n```svelte\n<RatingInput label=\"Rating\" bind:value={rating} max={5} />\n```\n\n### Half Steps\n```svelte\n<RatingInput label=\"Rating\" bind:value={rating} halfSteps />\n```\n\n### Half Steps in RTL (fills from the right)\n```svelte\n<RatingInput label=\"Rating\" bind:value={rating} halfSteps dir=\"rtl\" />\n```\n\n### Custom Star Count\n```svelte\n<RatingInput label=\"Score\" bind:value={score} max={10} />\n```\n\n### Readonly\n```svelte\n<RatingInput label=\"Average\" value={4.5} halfSteps readOnly />\n```\n\n### Disabled\n```svelte\n<RatingInput label=\"Rating\" value={3} disabled />\n```\n\n### Required (inside a Form)\n```svelte\n<Form inputs={{ rating: { type: 'rating', label: 'Rating', required: true } }} />\n```\n\n## Keyboard Interactions\n\nThe rating row is a single tab stop with `role=\"slider\"`.\n\n- **Arrow Right / Arrow Up**: Increase the value by the step (0.5 when halfSteps, else 1)\n- **Arrow Left / Arrow Down**: Decrease the value by the step\n- **Home**: Clear the value (sets it to null)\n- **End**: Set the value to max\n\nValue semantics do NOT flip in RTL: Arrow Right always increases the numeric value. Only the visual fill is mirrored.\n\n## Accessibility\n\n- The row container carries `role=\"slider\"` and is the single focusable element (`tabindex` 0 when interactive or read-only, -1 when disabled)\n- ARIA: `aria-valuemin={0}`, `aria-valuemax={max}`, `aria-valuenow`, `aria-valuetext`, `aria-orientation=\"horizontal\"`, `aria-readonly`, `aria-disabled`\n- Individual stars are `aria-hidden` and not focusable; the pointer selects a value and half-star hits are computed from the pointer position within each star\n- Clicking a star focuses the slider container (native focus fixup), so arrow keys work immediately after a pointer selection and `focused` becomes true \u2014 same as clicking a text input\n\n## RTL\n\nWhen the effective direction is RTL (via the `dir` prop or the inherited ambient direction), the stars render right-to-left and the fill grows from the right. The fill uses the CSS logical property `inset-inline-start`, so the visual mirroring is automatic. Note again: the numeric value is unaffected by direction \u2014 only the visual fill mirrors.\n\n## Half Steps\n\nWith `halfSteps`, the left half of a star (in the reading direction) selects n-0.5 and the right half selects n. The fill is rendered with an overflow-hidden clip whose width is the star's fill fraction, giving exact 0.5 (and arbitrary partial) fills.\n\n## Theme Customization\n\nThe RatingInput component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **container**: The flex row of stars (gap + focus ring)\n- **star**: The fixed-size box wrapping one star (cursor-pointer when interactive)\n- **starBase**: The outline (empty) star color\n- **starFill**: The filled star, driven by the `color` variant\n\n### Available Variants\n\n**container**:\n- size: 'small' | 'normal' | 'large' - Gap between stars\n- disabled: boolean - Disabled state styling\n\n**star**:\n- size: 'small' | 'normal' | 'large' - Star box size\n- interactive: boolean - cursor-pointer when interactive\n\n**starFill**:\n- color: Colors - Fill color of the star (defaults to 'warning')\n\n### Global Theme Setting\n\nThe star rendering lives in the `Rating` display component, so the theme is shared: set it once and both `Rating` and `RatingInput` pick it up.\n\n```svelte\n<script>\n\timport { setRatingTheme } from 'entasis/rating-input'; // also exported from 'entasis/rating'\n\n\tsetRatingTheme({\n\t\tstarFill: {\n\t\t\tcolor: {\n\t\t\t\tprimary: 'text-primary'\n\t\t\t}\n\t\t}\n\t});\n</script>\n```\n\n## State contract\n\n- **value**: current bindable editable value.\n- **defaultValue**: initial value used only when `value` is omitted.\n- **onValueChange**: called with the new value when the component changes it.\n\n";

package/dist/components/Form/RatingInput/ratingInput.mcp.js

@@ -21,7 +21,7 @@ Extends all Field component props plus:
 - **value**: number | null (bindable, default null) - Current rating; null (or 0) means "no rating"
 - **max**: number (default: 5) - Number of stars, which is also the maximum value
 - **halfSteps**: boolean (default: false) - When true the value snaps to 0.5 increments (half stars)
-- **readonly**: boolean (default: false) - Displays the value without allowing interaction (aria-readonly=true); still shows the stars
+- **readOnly**: boolean (default: false) - Shows the value without letting the user change it: the stars stay focusable with aria-readonly="true", pointer and keys change nothing, and the value still validates and submits. A read-only Form or FormGroup makes it read-only too. \`readonly\` is a deprecated alias kept for one minor
 - **clearable**: boolean (default: true) - When true, clicking the exact current value clears it back to null
 - **dir**: 'ltr' | 'rtl' - Reading direction override; inherits the ambient direction when omitted
 - **color**: Colors (default: 'warning') - Color of the filled stars (the classic gold/amber star)
@@ -65,7 +65,7 @@ Extends all Field component props plus:
 
 ### Readonly
 \`\`\`svelte
-<RatingInput label="Average" value={4.5} halfSteps readonly />
+<RatingInput label="Average" value={4.5} halfSteps readOnly />
 \`\`\`
 
 ### Disabled
@@ -91,7 +91,7 @@ Value semantics do NOT flip in RTL: Arrow Right always increases the numeric val
 
 ## Accessibility
 
-- The row container carries \`role="slider"\` and is the single focusable element (\`tabindex\` 0 when interactive, -1 when readonly/disabled)
+- The row container carries \`role="slider"\` and is the single focusable element (\`tabindex\` 0 when interactive or read-only, -1 when disabled)
 - ARIA: \`aria-valuemin={0}\`, \`aria-valuemax={max}\`, \`aria-valuenow\`, \`aria-valuetext\`, \`aria-orientation="horizontal"\`, \`aria-readonly\`, \`aria-disabled\`
 - Individual stars are \`aria-hidden\` and not focusable; the pointer selects a value and half-star hits are computed from the pointer position within each star
 - Clicking a star focuses the slider container (native focus fixup), so arrow keys work immediately after a pointer selection and \`focused\` becomes true — same as clicking a text input

package/dist/components/Form/RatingInput/ratingInput.props.d.ts

@@ -8,7 +8,7 @@ export type RatingInputProps = InputProps<'rating'> & {
     max?: number;
     /** When true the value snaps to 0.5 increments (half stars). */
     halfSteps?: boolean;
-    /** Displays the value without allowing interaction. */
+    /** @deprecated Use `readOnly`; `readonly` is kept as an alias until the next minor release. */
     readonly?: boolean;
     /** When true, clicking the current value clears it back to null. */
     clearable?: boolean;