entasis 0.11.0 → 0.12.0

package/dist/components/Form/Slider/slider.theme.js

@@ -118,6 +118,10 @@ const defaultTrack = cva({
             true: 'cursor-not-allowed opacity-50',
             false: 'cursor-pointer'
         },
+        readOnly: {
+            true: 'cursor-default',
+            false: ''
+        },
         variant: {
             default: '',
             thick: '',
@@ -129,6 +133,7 @@ const defaultTrack = cva({
         size: 'normal',
         color: 'neutral',
         disabled: false,
+        readOnly: false,
         variant: 'default'
     },
     compoundVariants: [
@@ -239,11 +244,14 @@ const defaultRange = cva({
         }
     ]
 });
+// Horizontal thumbs, hitboxes, contained ticks and marks sit at inset-inline-start, so in RTL their
+// centring translate flips. It flips on `:dir(rtl)`, the nearest `dir`, rather than on the `rtl:`
+// variant, which also matches inside an ltr slider placed in an rtl page.
 const defaultThumb = cva({
-    base: 'group absolute z-20 flex size-11 touch-none appearance-none items-center justify-center rounded-full border-0 bg-transparent p-0 outline-none',
+    base: 'group/slider-thumb absolute z-20 flex size-11 touch-none appearance-none items-center justify-center rounded-full border-0 bg-transparent p-0 outline-none',
     variants: {
         orientation: {
-            horizontal: 'top-1/2 -translate-x-1/2 -translate-y-1/2',
+            horizontal: 'top-1/2 -translate-x-1/2 -translate-y-1/2 [&:dir(rtl)]:translate-x-1/2',
             vertical: 'left-1/2 -translate-x-1/2 translate-y-1/2'
         },
         size: {
@@ -255,6 +263,10 @@ const defaultThumb = cva({
             true: 'cursor-not-allowed',
             false: 'cursor-grab active:cursor-grabbing'
         },
+        readOnly: {
+            true: 'cursor-default active:cursor-default',
+            false: ''
+        },
         color: {
             primary: '',
             secondary: '',
@@ -274,6 +286,7 @@ const defaultThumb = cva({
         orientation: 'horizontal',
         size: 'normal',
         disabled: false,
+        readOnly: false,
         color: 'neutral',
         variant: 'default'
     }
@@ -282,7 +295,7 @@ const defaultThumbHitbox = cva({
     base: 'absolute z-30 block touch-none rounded-full bg-transparent',
     variants: {
         orientation: {
-            horizontal: 'top-1/2 -translate-x-1/2 -translate-y-1/2',
+            horizontal: 'top-1/2 -translate-x-1/2 -translate-y-1/2 [&:dir(rtl)]:translate-x-1/2',
             vertical: 'left-1/2 -translate-x-1/2 translate-y-1/2'
         },
         size: {
@@ -294,6 +307,10 @@ const defaultThumbHitbox = cva({
             true: 'pointer-events-none cursor-not-allowed',
             false: 'cursor-grab active:cursor-grabbing'
         },
+        readOnly: {
+            true: 'cursor-default active:cursor-default',
+            false: ''
+        },
         variant: {
             default: 'hidden',
             thick: '',
@@ -304,11 +321,12 @@ const defaultThumbHitbox = cva({
         orientation: 'horizontal',
         size: 'normal',
         disabled: false,
+        readOnly: false,
         variant: 'default'
     }
 });
 const defaultThumbVisual = cva({
-    base: 'pointer-events-none rounded-full border-2 border-surface bg-current lift-1 ring-offset-surface transition-[box-shadow,transform] group-focus-visible:ring-2 group-focus-visible:ring-focus/50 group-focus-visible:ring-offset-2',
+    base: 'pointer-events-none rounded-full border-2 border-surface bg-current lift-1 ring-offset-surface transition-[box-shadow,transform] group-has-[:focus-visible]/slider-thumb:ring-2 group-has-[:focus-visible]/slider-thumb:ring-focus/50 group-has-[:focus-visible]/slider-thumb:ring-offset-2',
     variants: {
         orientation: {
             horizontal: '',
@@ -357,7 +375,7 @@ const defaultThumbVisual = cva({
         { orientation: 'vertical', variant: 'thick', size: 'large', class: 'h-9 w-5' },
         {
             variant: 'contained',
-            class: 'bg-neutral/45 scale-75 border-0 shadow-none transition-[background-color,transform] duration-normal ease-standard group-focus-visible:scale-100 group-focus-visible:bg-neutral/80'
+            class: 'bg-neutral/45 scale-75 border-0 shadow-none transition-[background-color,transform] duration-normal ease-standard group-has-[:focus-visible]/slider-thumb:scale-100 group-has-[:focus-visible]/slider-thumb:bg-neutral/80'
         },
         { orientation: 'horizontal', variant: 'contained', size: 'small', class: 'h-5 w-1' },
         { orientation: 'horizontal', variant: 'contained', size: 'normal', class: 'h-7 w-1.5' },
@@ -401,19 +419,19 @@ const defaultValueLabels = cva({
             orientation: 'horizontal',
             variant: 'contained',
             size: 'small',
-            class: 'pointer-events-none absolute top-0 right-3 z-30 h-8 flex-nowrap'
+            class: 'pointer-events-none absolute top-0 end-3 z-30 h-8 flex-nowrap'
         },
         {
             orientation: 'horizontal',
             variant: 'contained',
             size: 'normal',
-            class: 'pointer-events-none absolute top-0 right-4 z-30 h-10 flex-nowrap'
+            class: 'pointer-events-none absolute top-0 end-4 z-30 h-10 flex-nowrap'
         },
         {
             orientation: 'horizontal',
             variant: 'contained',
             size: 'large',
-            class: 'pointer-events-none absolute top-0 right-5 z-30 h-12 flex-nowrap'
+            class: 'pointer-events-none absolute top-0 end-5 z-30 h-12 flex-nowrap'
         },
         {
             orientation: 'horizontal',
@@ -483,15 +501,15 @@ const defaultValueLabel = cva({
     ]
 });
 const defaultContainedLabel = cva({
-    base: 'text-neutral/70 pointer-events-none absolute top-0 left-0 z-30 flex max-w-[55%] min-w-0 items-center truncate font-medium',
+    base: 'text-neutral/70 pointer-events-none absolute top-0 start-0 z-30 flex max-w-[55%] min-w-0 items-center truncate font-medium',
     variants: {
         size: {
-            small: 'h-8 pl-lg text-xs',
-            normal: 'h-10 pl-xl text-sm',
-            large: 'h-12 pl-layout-sm text-base'
+            small: 'h-8 ps-lg text-xs',
+            normal: 'h-10 ps-xl text-sm',
+            large: 'h-12 ps-layout-sm text-base'
         },
         required: {
-            true: "after:text-danger-readable after:ml-xs after:content-['*']",
+            true: "after:text-danger-readable after:ms-xs after:content-['*']",
             false: ''
         },
         hasError: {
@@ -521,7 +539,7 @@ const defaultContainedTick = cva({
     base: 'bg-current/10 absolute rounded-full',
     variants: {
         orientation: {
-            horizontal: 'top-1/2 w-px -translate-x-1/2 -translate-y-1/2',
+            horizontal: 'top-1/2 w-px -translate-x-1/2 -translate-y-1/2 [&:dir(rtl)]:translate-x-1/2',
             vertical: 'left-1/2 h-px -translate-x-1/2 translate-y-1/2'
         },
         size: {
@@ -548,7 +566,7 @@ const defaultMarks = cva({
     variants: {
         orientation: {
             horizontal: 'mt-sm h-5 w-full',
-            vertical: 'absolute inset-y-0 left-full ml-lg w-16'
+            vertical: 'absolute inset-y-0 start-full ms-lg w-16'
         },
         size: {
             small: 'text-xs',
@@ -565,8 +583,8 @@ const defaultMark = cva({
     base: 'absolute flex text-center',
     variants: {
         orientation: {
-            horizontal: 'top-0 -translate-x-1/2 flex-col items-center gap-xs',
-            vertical: 'left-0 -translate-y-1/2 items-center gap-md'
+            horizontal: 'top-0 -translate-x-1/2 [&:dir(rtl)]:translate-x-1/2 flex-col items-center gap-xs',
+            vertical: 'start-0 -translate-y-1/2 items-center gap-md'
         }
     },
     defaultVariants: {

package/dist/components/Form/Switch/Switch.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
 	import { untrack } from 'svelte';
 	import Field from '../Field/Field.svelte';
+	import FieldHiddenInputs from '../Field/FieldHiddenInputs.svelte';
 	import { useFieldTheme } from '../Field/field.theme.js';
 	import { createFieldState } from '../Field/field.state.svelte.js';
 	import type { SwitchProps } from './switch.props.js';
@@ -15,6 +16,8 @@
 		required = false,
 		theme,
 		disabled,
+		readOnly,
+		messages,
 		name,
 		onValidate,
 		visible,
@@ -22,11 +25,16 @@
 		label,
 		labelPosition,
 		onValueChange,
+		inputValue = 'true',
+		inputAttrs,
 		...rest
 	}: SwitchProps = $props();
 	if (value === undefined) value = untrack(() => defaultValue);
 
 	const id = $props.id();
+	// Field falls back to a generated name so Form wiring stays unique. Only a name the app gave,
+	// directly or through Form, is submitted: an unnamed switch submits nothing, like a checkbox.
+	let generatedName: string | undefined;
 
 	const field = createFieldState({
 		id,
@@ -57,17 +65,25 @@
 		set disabled(v: boolean | undefined) {
 			disabled = v;
 		},
+		get readOnly() {
+			return readOnly;
+		},
+		get messages() {
+			return messages;
+		},
 		get required() {
 			return required;
 		},
 		get name() {
-			return name;
+			return name || generatedName;
 		},
 		set name(v: string | undefined) {
-			name = v;
+			generatedName = v;
 		},
-		get onValidate() {
-			return onValidate;
+		// Required means the switch must be on, as for Checkbox: an off switch is not an answer.
+		onValidate: (checked) => {
+			if (required && !checked) return true;
+			return onValidate?.(checked) || false;
 		},
 		get visible() {
 			return visible;
@@ -77,24 +93,15 @@
 
 	const classes = $derived(useSwitchTheme(theme));
 	const fieldClasses = $derived(useFieldTheme(theme));
-	const onclick = () => {
-		if (disabled) return;
+	// A read-only or disabled switch refuses the edit inside setValue.
+	const toggle = () => {
 		field.value = !field.value;
 	};
-
-	const onKeydown = (e: KeyboardEvent) => {
-		if (disabled) return;
-		if (e.key === 'Enter' || e.key === ' ') {
-			e.preventDefault();
-			field.value = !field.value;
-		}
-	};
 </script>
 
 <Field
 	{field}
 	{labelPosition}
-	labelFor={false}
 	label={labelPosition ? label : undefined}
 	theme={{
 		...(theme || {}),
@@ -109,35 +116,51 @@
 	}}
 	{...rest}
 >
-	<input
-		onchange={onclick}
-		name={field.name}
-		id={'input-' + field.id}
-		{value}
-		hidden
-		disabled={field.disabled}
-		type="checkbox"
-	/>
-	<div
+	<!-- A native button: Enter and Space toggle once (Space on release), a disabled switch takes no
+	     focus, and the labels below are <label for>, so a click on one toggles it. The name comes
+	     from the label, or from an `aria-label` in inputAttrs. -->
+	<button
+		{...inputAttrs}
 		bind:this={field.node}
 		id={field.id}
-		data-checked={!!value}
-		aria-checked={!!value}
-		aria-labelledby={label ? field.labelId : undefined}
-		aria-disabled={field.disabled || undefined}
+		type="button"
 		role="switch"
-		tabindex={field.disabled ? -1 : 0}
-		class={classes.toggle({ checked: !!value, size, disabled })}
-		{onclick}
-		onkeydown={onKeydown}
-		onfocus={() => (field.focused = true)}
-		onblur={() => (field.focused = false)}
+		aria-checked={!!field.value}
+		disabled={field.disabled}
+		data-checked={!!field.value}
+		data-readonly={field.readOnly ? '' : undefined}
+		class={classes.toggle({
+			checked: !!field.value,
+			size,
+			disabled: field.disabled,
+			readOnly: field.readOnly
+		})}
+		onclick={(event) => {
+			inputAttrs?.onclick?.(event);
+			if (!event.defaultPrevented) toggle();
+		}}
+		onfocus={(event) => {
+			inputAttrs?.onfocus?.(event);
+			field.focused = true;
+		}}
+		onblur={(event) => {
+			inputAttrs?.onblur?.(event);
+			field.focused = false;
+		}}
 	>
-		<span class={classes.thumb({ checked: !!value, size })} data-checked={!!value}></span>
-	</div>
+		<span class={classes.thumb({ checked: !!field.value, size })} data-checked={!!field.value}
+		></span>
+	</button>
+	<!-- Beside the button, not inside it: a button may not contain interactive content. -->
+	<FieldHiddenInputs {field} checked={!!field.value} value={inputValue} />
 	{#snippet suffix()}
 		{#if !labelPosition}
-			<Slot as="span" attrs={{ id: field.labelId }} render={label} class={fieldClasses.label()} />
+			<Slot
+				as="label"
+				attrs={{ id: field.labelId, for: field.id }}
+				render={label}
+				class={fieldClasses.label({ required: field.required, disabled: field.disabled })}
+			/>
 		{/if}
 	{/snippet}
 </Field>

package/dist/components/Form/Switch/switch.mcp.d.ts

@@ -1 +1 @@
-export declare const switchDescription = "\n# Switch Component\n\nThe Switch component is a toggle control for boolean settings, providing a visual on/off state with smooth animations.\n\n## Basic Usage\n\n```svelte\n<script>\n\tlet enabled = $state(false);\n</script>\n\n<Switch label=\"Enable notifications\" bind:value={enabled} />\n```\n\n## Props\n\nExtends all Field component props plus:\n\n### Core Props\n- **value**: boolean | null (bindable) - Toggle state (bind with `bind:value`)\n- **defaultValue**: boolean | null (default: null) - Initial value when value is omitted\n\n### Field Props (inherited)\n- **label**: string | Snippet - Field label\n- **description**: string | Snippet - Helper text\n- **error**: string - Error message\n- **required**: boolean - Mark as required\n- **disabled**: boolean - Disable toggle\n- **size**: 'small' | 'normal' | 'large' - Switch size\n\n### Event Props\n- **onValueChange**: (value: boolean) => void - Called when toggled\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n\n## Structure\n\n```\n<Field>\n\t<InputContainer>\n\t\t<SwitchToggle>\n\t\t\t<SwitchThumb />\n\t\t</SwitchToggle>\n\t\t<Label />\n\t</InputContainer>\n\t<Description />\n\t<Error />\n</Field>\n```\n\n## Examples\n\n### Basic Switch\n```svelte\n<script>\n\tlet notifications = $state(false);\n</script>\n\n<Switch \n\tlabel=\"Enable Notifications\"\n\tbind:value={notifications}\n/>\n```\n\n### With Description\n```svelte\n<Switch \n\tlabel=\"Auto-save\"\n\tdescription=\"Automatically save your work every 5 minutes\"\n\tbind:value={autoSave}\n/>\n```\n\n### Required Switch\n```svelte\n<Switch \n\tlabel=\"I agree to the terms and conditions\"\n\tbind:value={agreedToTerms}\n\trequired\n/>\n```\n\n### Disabled Switch\n```svelte\n<Switch \n\tlabel=\"Premium Feature\"\n\tvalue={false}\n\tdisabled\n\tdescription=\"Upgrade to unlock this feature\"\n/>\n```\n\n### Different Sizes\n```svelte\n<Switch size=\"small\" label=\"Small Switch\" bind:value={val1} />\n<Switch size=\"normal\" label=\"Normal Switch\" bind:value={val2} />\n<Switch size=\"large\" label=\"Large Switch\" bind:value={val3} />\n```\n\n### With Change Handler\n```svelte\n<script>\n\tfunction handleToggle(checked) {\n\t\tconsole.log('Switch toggled:', checked);\n\t\t// Save to API, etc.\n\t}\n</script>\n\n<Switch \n\tlabel=\"Dark Mode\"\n\tbind:value={darkMode}\n\tonValueChange={handleToggle}\n/>\n```\n\n### Settings Panel\n```svelte\n<script>\n\tlet settings = $state({\n\t\tnotifications: true,\n\t\temailUpdates: false,\n\t\tautoPlay: false,\n\t\tshowPreview: true\n\t});\n</script>\n\n<div class=\"space-y-4\">\n\t<Switch \n\t\tlabel=\"Push Notifications\"\n\t\tdescription=\"Receive notifications on your device\"\n\t\tbind:value={settings.notifications}\n\t/>\n\t\n\t<Switch \n\t\tlabel=\"Email Updates\"\n\t\tdescription=\"Get weekly email summaries\"\n\t\tbind:value={settings.emailUpdates}\n\t/>\n\t\n\t<Switch \n\t\tlabel=\"Auto-play Videos\"\n\t\tdescription=\"Videos start playing automatically\"\n\t\tbind:value={settings.autoPlay}\n\t/>\n\t\n\t<Switch \n\t\tlabel=\"Show Preview\"\n\t\tdescription=\"Display content previews\"\n\t\tbind:value={settings.showPreview}\n\t/>\n</div>\n```\n\n### Privacy Settings\n```svelte\n<form>\n\t<Heading size=\"h3\">Privacy Settings</Heading>\n\t\n\t<Switch \n\t\tlabel=\"Profile Visibility\"\n\t\tdescription=\"Make your profile visible to other users\"\n\t\tbind:value={privacy.profileVisible}\n\t/>\n\t\n\t<Switch \n\t\tlabel=\"Show Email\"\n\t\tdescription=\"Display your email on your profile\"\n\t\tbind:value={privacy.showEmail}\n\t\tdisabled={!privacy.profileVisible}\n\t/>\n\t\n\t<Switch \n\t\tlabel=\"Activity Status\"\n\t\tdescription=\"Show when you're online\"\n\t\tbind:value={privacy.showActivity}\n\t/>\n\t\n\t<Button type=\"submit\">Save Settings</Button>\n</form>\n```\n\n### Feature Toggles\n```svelte\n<script>\n\tlet features = $state({\n\t\texperimental: false,\n\t\tbeta: false,\n\t\tanalytics: true\n\t});\n\t\n\t$effect(() => {\n\t\tif (features.experimental) {\n\t\t\tconsole.log('Experimental features enabled');\n\t\t}\n\t});\n</script>\n\n<div class=\"panel\">\n\t<Heading size=\"h4\">Feature Flags</Heading>\n\t\n\t<Switch \n\t\tlabel=\"Experimental Features\"\n\t\tdescription=\"\u26A0\uFE0F Use at your own risk\"\n\t\tbind:value={features.experimental}\n\t/>\n\t\n\t<Switch \n\t\tlabel=\"Beta Features\"\n\t\tdescription=\"Try new features before they're released\"\n\t\tbind:value={features.beta}\n\t/>\n\t\n\t<Switch \n\t\tlabel=\"Analytics\"\n\t\tdescription=\"Help us improve by sharing usage data\"\n\t\tbind:value={features.analytics}\n\t/>\n</div>\n```\n\n### Conditional Content\n```svelte\n<script>\n\tlet advancedMode = $state(false);\n</script>\n\n<Switch \n\tlabel=\"Advanced Mode\"\n\tdescription=\"Show advanced options\"\n\tbind:value={advancedMode}\n/>\n\n{#if advancedMode}\n\t<div class=\"advanced-options\">\n\t\t<!-- Advanced settings here -->\n\t</div>\n{/if}\n```\n\n### Form Integration\n```svelte\n<Form \n\tinputs={{\n\t\tname: { type: 'text', label: 'Name', required: true },\n\t\tnotifications: { \n\t\t\ttype: 'switch', \n\t\t\tlabel: 'Enable Notifications',\n\t\t\tdescription: 'Receive important updates'\n\t\t},\n\t\tmarketing: { \n\t\t\ttype: 'switch', \n\t\t\tlabel: 'Marketing Emails'\n\t\t}\n\t}}\n\tonSubmit={handleSubmit}\n/>\n```\n\n## Validation\n\nSwitch validates:\n- **required**: Must be checked (useful for terms acceptance)\n\n## Accessibility\n\n- Proper ARIA roles and attributes\n- Keyboard accessible (Space/Enter to toggle)\n- Focus states clearly visible\n- Label clickable to toggle\n- State changes announced to screen readers\n- Disabled state communicated properly\n\n## Notes\n\n- Smooth animated transitions between states\n- Visual feedback on hover and focus\n- Works standalone or within forms\n- Thumb slides with smooth animation\n- Toggle background changes color based on state\n- Supports all Field component features\n\n## Theme Customization\n\nThe Switch 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- **toggle**: Switch toggle track styles\n- **thumb**: Switch thumb/knob styles\n- **inputContainer**: Container wrapper styles\n\n### Available Variants\n\n**toggle**:\n- base: Base classes for the toggle track\n- Variants:\n  - checked: boolean - Background and border color based on checked state\n  - size: 'small' | 'normal' | 'large' - Toggle dimensions (height and width)\n  - disabled: boolean - Disabled state styling\n\n**thumb**:\n- base: Base classes for the thumb/knob\n- Variants:\n  - checked: boolean - Thumb position and styling based on checked state\n  - size: 'small' | 'normal' | 'large' - Thumb dimensions\n\n**inputContainer**:\n- base: Base classes for the container wrapper\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Gap spacing between label and toggle\n  - disabled: boolean - Disabled state styling\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Switch \n  label=\"Enable Feature\"\n  bind:value={enabled}\n  theme={{\n    toggle: {\n      base: 'rounded-full transition-all',\n      checked: {\n        true: 'bg-green-500 border-green-600'\n      },\n      size: {\n        normal: 'h-6 w-11'\n      }\n    },\n    thumb: {\n      size: {\n        normal: 'h-5 w-5'\n      }\n    }\n  }}\n/>\n```\n\n**Custom Colors**:\n```svelte\n<Switch \n  label=\"Custom Switch\"\n  bind:value={checked}\n  theme={{\n    toggle: {\n      checked: {\n        true: 'bg-purple-500 border-purple-600',\n        false: 'bg-gray-300 border-gray-400'\n      }\n    },\n    thumb: {\n      checked: {\n        true: 'bg-white border-purple-500',\n        false: 'bg-white border-gray-400'\n      }\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setSwitchTheme } from './index.ts';\n  \n  setSwitchTheme({\n    toggle: {\n      base: 'transition-all duration-300',\n      checked: {\n        true: 'bg-primary border-primary lift-3'\n      },\n      size: {\n        normal: 'h-6 w-12'\n      }\n    },\n    thumb: {\n      base: 'lift-4',\n      size: {\n        normal: 'h-5 w-5'\n      }\n    }\n  });\n</script>\n```\n";
+export declare const switchDescription = "\n# Switch Component\n\nThe Switch component is a toggle control for boolean settings, providing a visual on/off state with smooth animations.\n\n## Basic Usage\n\n```svelte\n<script>\n\tlet enabled = $state(false);\n</script>\n\n<Switch label=\"Enable notifications\" bind:value={enabled} />\n```\n\n## Props\n\nExtends all Field component props plus:\n\n### Core Props\n- **value**: boolean | null (bindable) - Toggle state (bind with `bind:value`)\n- **defaultValue**: boolean | null (default: null) - Initial value when value is omitted\n- **inputValue**: string (default: 'true') - Value a native `<form>` submits under `name` while the switch is on; an off switch, or one without a `name`, submits nothing\n- **inputAttrs**: FieldButtonAttributes - Native attributes for the switch control, such as `aria-label`, `title`, `data-*` and event handlers. An `aria-label` names the switch instead of its label; a handler that calls `preventDefault()` cancels the toggle\n\n### Field Props (inherited)\n- **label**: string | Snippet - Field label\n- **description**: string | Snippet - Helper text\n- **error**: string - Error message\n- **required**: boolean - The switch must be on to be valid (like Checkbox); off, it shows the catalog message asking to turn it on (override with `messages.required`)\n- **disabled**: boolean - Disable toggle\n- **readOnly**: boolean - Keeps the switch focusable with `aria-readonly` while clicks and keys change nothing; the value still validates and submits\n- **size**: 'small' | 'normal' | 'large' - Switch size\n\n### Event Props\n- **onValueChange**: (value: boolean) => void - Called when toggled\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n\n## Structure\n\n```\n<Field>\n\t<InputContainer>\n\t\t<SwitchToggle>\n\t\t\t<SwitchThumb />\n\t\t</SwitchToggle>\n\t\t<Label />\n\t</InputContainer>\n\t<Description />\n\t<Error />\n</Field>\n```\n\n## Examples\n\n### Basic Switch\n```svelte\n<script>\n\tlet notifications = $state(false);\n</script>\n\n<Switch \n\tlabel=\"Enable Notifications\"\n\tbind:value={notifications}\n/>\n```\n\n### With Description\n```svelte\n<Switch \n\tlabel=\"Auto-save\"\n\tdescription=\"Automatically save your work every 5 minutes\"\n\tbind:value={autoSave}\n/>\n```\n\n### Required Switch\nA required switch is valid only while it is on, so it fits consent and terms acceptance.\n```svelte\n<Switch \n\tlabel=\"I agree to the terms and conditions\"\n\tbind:value={agreedToTerms}\n\trequired\n/>\n```\n\n### Native Form Submission\nInside a plain `<form>` (for example a SvelteKit form action), the switch submits its `name` with\n`inputValue` while it is on and nothing while it is off, like a native checkbox. A switch without a\n`name` submits nothing. A required switch that is off blocks the submit; when it is the first invalid\ncontrol, the browser's report lands on the switch, which takes focus and shows its error. A silent\n`checkValidity()` changes nothing.\n```svelte\n<form method=\"POST\">\n\t<Switch name=\"marketing\" inputValue=\"yes\" label=\"Marketing emails\" />\n\t<Switch name=\"terms\" label=\"Accept the terms\" required />\n\t<button type=\"submit\">Save</button>\n</form>\n```\n\n### Disabled Switch\n```svelte\n<Switch \n\tlabel=\"Premium Feature\"\n\tvalue={false}\n\tdisabled\n\tdescription=\"Upgrade to unlock this feature\"\n/>\n```\n\n### Different Sizes\n```svelte\n<Switch size=\"small\" label=\"Small Switch\" bind:value={val1} />\n<Switch size=\"normal\" label=\"Normal Switch\" bind:value={val2} />\n<Switch size=\"large\" label=\"Large Switch\" bind:value={val3} />\n```\n\n### With Change Handler\n```svelte\n<script>\n\tfunction handleToggle(checked) {\n\t\tconsole.log('Switch toggled:', checked);\n\t\t// Save to API, etc.\n\t}\n</script>\n\n<Switch \n\tlabel=\"Dark Mode\"\n\tbind:value={darkMode}\n\tonValueChange={handleToggle}\n/>\n```\n\n### Settings Panel\n```svelte\n<script>\n\tlet settings = $state({\n\t\tnotifications: true,\n\t\temailUpdates: false,\n\t\tautoPlay: false,\n\t\tshowPreview: true\n\t});\n</script>\n\n<div class=\"space-y-4\">\n\t<Switch \n\t\tlabel=\"Push Notifications\"\n\t\tdescription=\"Receive notifications on your device\"\n\t\tbind:value={settings.notifications}\n\t/>\n\t\n\t<Switch \n\t\tlabel=\"Email Updates\"\n\t\tdescription=\"Get weekly email summaries\"\n\t\tbind:value={settings.emailUpdates}\n\t/>\n\t\n\t<Switch \n\t\tlabel=\"Auto-play Videos\"\n\t\tdescription=\"Videos start playing automatically\"\n\t\tbind:value={settings.autoPlay}\n\t/>\n\t\n\t<Switch \n\t\tlabel=\"Show Preview\"\n\t\tdescription=\"Display content previews\"\n\t\tbind:value={settings.showPreview}\n\t/>\n</div>\n```\n\n### Privacy Settings\n```svelte\n<form>\n\t<Heading size=\"h3\">Privacy Settings</Heading>\n\t\n\t<Switch \n\t\tlabel=\"Profile Visibility\"\n\t\tdescription=\"Make your profile visible to other users\"\n\t\tbind:value={privacy.profileVisible}\n\t/>\n\t\n\t<Switch \n\t\tlabel=\"Show Email\"\n\t\tdescription=\"Display your email on your profile\"\n\t\tbind:value={privacy.showEmail}\n\t\tdisabled={!privacy.profileVisible}\n\t/>\n\t\n\t<Switch \n\t\tlabel=\"Activity Status\"\n\t\tdescription=\"Show when you're online\"\n\t\tbind:value={privacy.showActivity}\n\t/>\n\t\n\t<Button type=\"submit\">Save Settings</Button>\n</form>\n```\n\n### Feature Toggles\n```svelte\n<script>\n\tlet features = $state({\n\t\texperimental: false,\n\t\tbeta: false,\n\t\tanalytics: true\n\t});\n\t\n\t$effect(() => {\n\t\tif (features.experimental) {\n\t\t\tconsole.log('Experimental features enabled');\n\t\t}\n\t});\n</script>\n\n<div class=\"panel\">\n\t<Heading size=\"h4\">Feature Flags</Heading>\n\t\n\t<Switch \n\t\tlabel=\"Experimental Features\"\n\t\tdescription=\"\u26A0\uFE0F Use at your own risk\"\n\t\tbind:value={features.experimental}\n\t/>\n\t\n\t<Switch \n\t\tlabel=\"Beta Features\"\n\t\tdescription=\"Try new features before they're released\"\n\t\tbind:value={features.beta}\n\t/>\n\t\n\t<Switch \n\t\tlabel=\"Analytics\"\n\t\tdescription=\"Help us improve by sharing usage data\"\n\t\tbind:value={features.analytics}\n\t/>\n</div>\n```\n\n### Conditional Content\n```svelte\n<script>\n\tlet advancedMode = $state(false);\n</script>\n\n<Switch \n\tlabel=\"Advanced Mode\"\n\tdescription=\"Show advanced options\"\n\tbind:value={advancedMode}\n/>\n\n{#if advancedMode}\n\t<div class=\"advanced-options\">\n\t\t<!-- Advanced settings here -->\n\t</div>\n{/if}\n```\n\n### Form Integration\n```svelte\n<Form \n\tinputs={{\n\t\tname: { type: 'text', label: 'Name', required: true },\n\t\tnotifications: { \n\t\t\ttype: 'switch', \n\t\t\tlabel: 'Enable Notifications',\n\t\t\tdescription: 'Receive important updates'\n\t\t},\n\t\tmarketing: { \n\t\t\ttype: 'switch', \n\t\t\tlabel: 'Marketing Emails'\n\t\t}\n\t}}\n\tonSubmit={handleSubmit}\n/>\n```\n\n## Validation\n\nSwitch validates:\n- **required**: Must be on (useful for terms acceptance); an off switch fails Form validation and native form submission\n\n## Accessibility\n\n- The control is a native `<button role=\"switch\">` with `aria-checked`; a required switch carries `aria-required` and a required marker on its label\n- Keyboard accessible: Enter toggles once on press and Space once on release (holding Space does not repeat), because the browser's own button handling does it\n- Focus states clearly visible\n- The label is a `<label for>` the switch, so it names the switch and clicking it toggles it exactly once; an `aria-label` in `inputAttrs` names the switch instead\n- A disabled switch is a disabled button and takes no focus; a read-only one stays focusable with `aria-readonly` and does not toggle\n- The native submission is a hidden checkbox beside the button, never inside it\n- State changes announced to screen readers\n- Disabled state communicated properly\n\n## Notes\n\n- Smooth animated transitions between states\n- Visual feedback on hover and focus\n- Works standalone or within forms\n- Thumb slides with smooth animation\n- Toggle background changes color based on state\n- Supports all Field component features\n\n## Theme Customization\n\nThe Switch 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- **toggle**: Switch toggle track styles\n- **thumb**: Switch thumb/knob styles\n- **inputContainer**: Container wrapper styles\n\n### Available Variants\n\n**toggle**:\n- base: Base classes for the toggle track\n- Variants:\n  - checked: boolean - Background and border color based on checked state\n  - size: 'small' | 'normal' | 'large' - Toggle dimensions (height and width)\n  - disabled: boolean - Disabled state styling\n\n**thumb**:\n- base: Base classes for the thumb/knob\n- Variants:\n  - checked: boolean - Thumb position and styling based on checked state\n  - size: 'small' | 'normal' | 'large' - Thumb dimensions\n\n**inputContainer**:\n- base: Base classes for the container wrapper\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Gap spacing between label and toggle\n  - disabled: boolean - Disabled state styling\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Switch \n  label=\"Enable Feature\"\n  bind:value={enabled}\n  theme={{\n    toggle: {\n      base: 'rounded-full transition-all',\n      checked: {\n        true: 'bg-green-500 border-green-600'\n      },\n      size: {\n        normal: 'h-6 w-11'\n      }\n    },\n    thumb: {\n      size: {\n        normal: 'h-5 w-5'\n      }\n    }\n  }}\n/>\n```\n\n**Custom Colors**:\n```svelte\n<Switch \n  label=\"Custom Switch\"\n  bind:value={checked}\n  theme={{\n    toggle: {\n      checked: {\n        true: 'bg-purple-500 border-purple-600',\n        false: 'bg-gray-300 border-gray-400'\n      }\n    },\n    thumb: {\n      checked: {\n        true: 'bg-white border-purple-500',\n        false: 'bg-white border-gray-400'\n      }\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setSwitchTheme } from './index.ts';\n  \n  setSwitchTheme({\n    toggle: {\n      base: 'transition-all duration-300',\n      checked: {\n        true: 'bg-primary border-primary lift-3'\n      },\n      size: {\n        normal: 'h-6 w-12'\n      }\n    },\n    thumb: {\n      base: 'lift-4',\n      size: {\n        normal: 'h-5 w-5'\n      }\n    }\n  });\n</script>\n```\n";

package/dist/components/Form/Switch/switch.mcp.js

@@ -20,13 +20,16 @@ Extends all Field component props plus:
 ### Core Props
 - **value**: boolean | null (bindable) - Toggle state (bind with \`bind:value\`)
 - **defaultValue**: boolean | null (default: null) - Initial value when value is omitted
+- **inputValue**: string (default: 'true') - Value a native \`<form>\` submits under \`name\` while the switch is on; an off switch, or one without a \`name\`, submits nothing
+- **inputAttrs**: FieldButtonAttributes - Native attributes for the switch control, such as \`aria-label\`, \`title\`, \`data-*\` and event handlers. An \`aria-label\` names the switch instead of its label; a handler that calls \`preventDefault()\` cancels the toggle
 
 ### Field Props (inherited)
 - **label**: string | Snippet - Field label
 - **description**: string | Snippet - Helper text
 - **error**: string - Error message
-- **required**: boolean - Mark as required
+- **required**: boolean - The switch must be on to be valid (like Checkbox); off, it shows the catalog message asking to turn it on (override with \`messages.required\`)
 - **disabled**: boolean - Disable toggle
+- **readOnly**: boolean - Keeps the switch focusable with \`aria-readonly\` while clicks and keys change nothing; the value still validates and submits
 - **size**: 'small' | 'normal' | 'large' - Switch size
 
 ### Event Props
@@ -75,6 +78,7 @@ Extends all Field component props plus:
 \`\`\`
 
 ### Required Switch
+A required switch is valid only while it is on, so it fits consent and terms acceptance.
 \`\`\`svelte
 <Switch 
 	label="I agree to the terms and conditions"
@@ -83,6 +87,20 @@ Extends all Field component props plus:
 />
 \`\`\`
 
+### Native Form Submission
+Inside a plain \`<form>\` (for example a SvelteKit form action), the switch submits its \`name\` with
+\`inputValue\` while it is on and nothing while it is off, like a native checkbox. A switch without a
+\`name\` submits nothing. A required switch that is off blocks the submit; when it is the first invalid
+control, the browser's report lands on the switch, which takes focus and shows its error. A silent
+\`checkValidity()\` changes nothing.
+\`\`\`svelte
+<form method="POST">
+	<Switch name="marketing" inputValue="yes" label="Marketing emails" />
+	<Switch name="terms" label="Accept the terms" required />
+	<button type="submit">Save</button>
+</form>
+\`\`\`
+
 ### Disabled Switch
 \`\`\`svelte
 <Switch 
@@ -262,14 +280,16 @@ Extends all Field component props plus:
 ## Validation
 
 Switch validates:
-- **required**: Must be checked (useful for terms acceptance)
+- **required**: Must be on (useful for terms acceptance); an off switch fails Form validation and native form submission
 
 ## Accessibility
 
-- Proper ARIA roles and attributes
-- Keyboard accessible (Space/Enter to toggle)
+- The control is a native \`<button role="switch">\` with \`aria-checked\`; a required switch carries \`aria-required\` and a required marker on its label
+- Keyboard accessible: Enter toggles once on press and Space once on release (holding Space does not repeat), because the browser's own button handling does it
 - Focus states clearly visible
-- Label clickable to toggle
+- The label is a \`<label for>\` the switch, so it names the switch and clicking it toggles it exactly once; an \`aria-label\` in \`inputAttrs\` names the switch instead
+- A disabled switch is a disabled button and takes no focus; a read-only one stays focusable with \`aria-readonly\` and does not toggle
+- The native submission is a hidden checkbox beside the button, never inside it
 - State changes announced to screen readers
 - Disabled state communicated properly
 

package/dist/components/Form/Switch/switch.props.d.ts

@@ -1,6 +1,19 @@
-import type { InputProps } from '../Field/field.js';
+import type { FieldButtonAttributes, InputProps } from '../Field/field.js';
 import type { SwitchThemeProps } from './switch.theme.js';
 export type SwitchProps = InputProps<'switch'> & {
+    /** A required switch is valid only while it is on, in a Form and in a native `<form>`. */
+    required?: boolean;
+    /**
+     * Value submitted with the switch's `name` by a native `<form>` while the switch is on; an
+     * off switch, or one without a `name`, submits nothing, like a native checkbox. Defaults to
+     * `'true'`.
+     */
+    inputValue?: string;
+    /**
+     * Native attributes for the switch control, such as `aria-label`, `title` or `data-*`. An
+     * `aria-label` names the switch instead of its label.
+     */
+    inputAttrs?: FieldButtonAttributes;
     /** Theme overrides for the switch toggle, thumb, input container, and field parts. */
     theme?: SwitchThemeProps & InputProps<'switch'>['theme'];
 };

package/dist/components/Form/Switch/switch.theme.d.ts

@@ -14,6 +14,10 @@ export declare const switchTheme: {
             true: string;
             false: string;
         };
+        readOnly: {
+            true: string;
+            false: string;
+        };
     }> & import("../../../utils/cva/types.js").CVAClassProp) | undefined) => string;
     thumb: (props?: (import("../../../utils/cva/types.js").CVAVariantSchema<{
         checked: {
@@ -55,6 +59,10 @@ export declare const setSwitchTheme: (theme: InferComponentTheme<{
             true: string;
             false: string;
         };
+        readOnly: {
+            true: string;
+            false: string;
+        };
     }> & import("../../../utils/cva/types.js").CVAClassProp) | undefined) => string;
     thumb: (props?: (import("../../../utils/cva/types.js").CVAVariantSchema<{
         checked: {
@@ -94,6 +102,10 @@ export declare const useSwitchTheme: import("../../../utils/cva/theme.js").UseCo
             true: string;
             false: string;
         };
+        readOnly: {
+            true: string;
+            false: string;
+        };
     }> & import("../../../utils/cva/types.js").CVAClassProp) | undefined) => string;
     thumb: (props?: (import("../../../utils/cva/types.js").CVAVariantSchema<{
         checked: {

package/dist/components/Form/Switch/switch.theme.js

@@ -15,6 +15,11 @@ const defaultSwitchToggle = cva({
         disabled: {
             true: 'cursor-not-allowed opacity-50',
             false: ''
+        },
+        // Focusable and announced, but not changeable: no pointer cursor promising a toggle.
+        readOnly: {
+            true: 'cursor-default',
+            false: ''
         }
     },
     defaultVariants: {
@@ -40,17 +45,17 @@ const defaultSwitchThumb = cva({
         {
             size: 'small',
             checked: true,
-            class: 'translate-x-4'
+            class: 'translate-x-4 rtl:-translate-x-4'
         },
         {
             size: 'normal',
             checked: true,
-            class: 'translate-x-5'
+            class: 'translate-x-5 rtl:-translate-x-5'
         },
         {
             size: 'large',
             checked: true,
-            class: 'translate-x-5'
+            class: 'translate-x-5 rtl:-translate-x-5'
         }
     ],
     defaultVariants: {

package/dist/components/Form/TagGroup/TagGroup.svelte

@@ -23,6 +23,8 @@
 		theme,
 		chipTheme,
 		disabled,
+		readOnly,
+		messages,
 		name,
 		label,
 		onValidate,
@@ -86,6 +88,12 @@
 		set disabled(nextDisabled: boolean | undefined) {
 			disabled = nextDisabled;
 		},
+		get readOnly() {
+			return readOnly;
+		},
+		get messages() {
+			return messages;
+		},
 		get required() {
 			return required;
 		},

package/dist/components/Form/TagGroup/tagGroup.mcp.d.ts

@@ -1 +1 @@
-export declare const tagGroupDescription = "\n# TagGroup Component\n\nTagGroup renders a finite set of selectable tags as chips. It is a form input for compact category, filter, or preference selection.\n\n## Basic Usage\n\n```svelte\n<script lang=\"ts\">\n\timport { TagGroup } from 'entasis/tag-group';\n\n\tlet value = $state('news');\n</script>\n\n<TagGroup\n\tlabel=\"Category\"\n\tbind:value\n\titems={[\n\t\t{ value: 'news', label: 'News' },\n\t\t{ value: 'travel', label: 'Travel' },\n\t\t{ value: 'gaming', label: 'Gaming' }\n\t]}\n/>\n```\n\n## Multiple Selection\n\n```svelte\n<script lang=\"ts\">\n\tlet selected = $state(['news', 'gaming']);\n</script>\n\n<TagGroup\n\tmultiple\n\tlabel=\"Topics\"\n\tbind:value={selected}\n\titems={[\n\t\t{ value: 'news', label: 'News' },\n\t\t{ value: 'travel', label: 'Travel' },\n\t\t{ value: 'gaming', label: 'Gaming' }\n\t]}\n/>\n```\n\n## Props\n\n### Core Props\n- **items**: TagGroupOption[] - Options rendered as selectable chips.\n- **value**: string | string[] | null - Bindable selection. Single mode writes string|null; multiple mode writes string[].\n- **defaultValue**: string | string[] | null - Initial selection used only when `value` is omitted.\n- **multiple**: boolean (default: false) - Enables selecting multiple tags.\n- **label**: Slot - Field label.\n- **name**: string - Form field name.\n- **required**: boolean (default: false) - Marks selection as required.\n- **disabled**: boolean (default: false) - Disables all tag buttons.\n\n### Option Props\n- **value**: string - Unique selection value.\n- **label**: string | Snippet - Visible chip label.\n- **icon**: string | Snippet - Optional icon rendered before the label.\n- **disabled**: boolean - Disables one option.\n- **color**: Colors - Per-option chip color override.\n- **variant**: 'solid' | 'outline' | 'soft' - Per-option chip variant override.\n\n### Style Props\n- **size**: 'small' | 'normal' | 'large' (default: 'normal') - Controls chip density.\n- **color**: Colors (default: 'primary') - Selected chip color.\n- **unselectedColor**: Colors (default: 'neutral') - Unselected chip color.\n- **selectedVariant**: 'solid' | 'outline' | 'soft' (default: 'soft') - Selected chip variant. The selected fill itself comes from the shared soft selected recipe on the item class.\n- **unselectedVariant**: 'solid' | 'outline' | 'soft' (default: 'outline') - Unselected chip variant. Outline by default so an unselected tag stays distinct from the soft selected fill at the neutral role.\n- **theme**: TagGroupThemeProps - Theme overrides for TagGroup and Field parts.\n- **chipTheme**: ChipThemeProps - Theme overrides forwarded to each Chip.\n\n### Events\n- **onValueChange**: (value: string | string[] | null) => void - Called when normalized selection changes.\n- **onValidate**: (value: string | string[] | null) => string[] | boolean - Custom validation.\n\n## Accessibility\n\n- Uses native button controls for each selectable chip.\n- Buttons expose aria-pressed for selected state.\n- The field is rendered as a fieldset through the shared Field wrapper.\n- Hidden inputs mirror selected values for native form submission.\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 tagGroupDescription = "\n# TagGroup Component\n\nTagGroup renders a finite set of selectable tags as chips. It is a form input for compact category, filter, or preference selection.\n\n## Basic Usage\n\n```svelte\n<script lang=\"ts\">\n\timport { TagGroup } from 'entasis/tag-group';\n\n\tlet value = $state('news');\n</script>\n\n<TagGroup\n\tlabel=\"Category\"\n\tbind:value\n\titems={[\n\t\t{ value: 'news', label: 'News' },\n\t\t{ value: 'travel', label: 'Travel' },\n\t\t{ value: 'gaming', label: 'Gaming' }\n\t]}\n/>\n```\n\n## Multiple Selection\n\n```svelte\n<script lang=\"ts\">\n\tlet selected = $state(['news', 'gaming']);\n</script>\n\n<TagGroup\n\tmultiple\n\tlabel=\"Topics\"\n\tbind:value={selected}\n\titems={[\n\t\t{ value: 'news', label: 'News' },\n\t\t{ value: 'travel', label: 'Travel' },\n\t\t{ value: 'gaming', label: 'Gaming' }\n\t]}\n/>\n```\n\n## Props\n\n### Core Props\n- **items**: TagGroupOption[] - Options rendered as selectable chips.\n- **value**: string | string[] | null - Bindable selection. Single mode writes string|null; multiple mode writes string[].\n- **defaultValue**: string | string[] | null - Initial selection used only when `value` is omitted.\n- **multiple**: boolean (default: false) - Enables selecting multiple tags.\n- **label**: Slot - Field label.\n- **name**: string - Form field name.\n- **required**: boolean (default: false) - Marks selection as required.\n- **disabled**: boolean (default: false) - Disables all tag buttons.\n- **readOnly**: boolean (default: false) - Tags stay focusable but pressing them changes nothing; the selection still validates and submits.\n\n### Option Props\n- **value**: string - Unique selection value.\n- **label**: string | Snippet - Visible chip label.\n- **icon**: string | Snippet - Optional icon rendered before the label.\n- **disabled**: boolean - Disables one option.\n- **color**: Colors - Per-option chip color override.\n- **variant**: 'solid' | 'outline' | 'soft' - Per-option chip variant override.\n\n### Style Props\n- **size**: 'small' | 'normal' | 'large' (default: 'normal') - Controls chip density.\n- **color**: Colors (default: 'primary') - Selected chip color.\n- **unselectedColor**: Colors (default: 'neutral') - Unselected chip color.\n- **selectedVariant**: 'solid' | 'outline' | 'soft' (default: 'soft') - Selected chip variant. The selected fill itself comes from the shared soft selected recipe on the item class.\n- **unselectedVariant**: 'solid' | 'outline' | 'soft' (default: 'outline') - Unselected chip variant. Outline by default so an unselected tag stays distinct from the soft selected fill at the neutral role.\n- **theme**: TagGroupThemeProps - Theme overrides for TagGroup and Field parts.\n- **chipTheme**: ChipThemeProps - Theme overrides forwarded to each Chip.\n\n### Events\n- **onValueChange**: (value: string | string[] | null) => void - Called when normalized selection changes.\n- **onValidate**: (value: string | string[] | null) => string[] | boolean - Custom validation.\n\n## Accessibility\n\n- Uses native button controls for each selectable chip.\n- Buttons expose aria-pressed for selected state.\n- The field is rendered as a fieldset through the shared Field wrapper.\n- Hidden inputs mirror selected values for native form submission.\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/TagGroup/tagGroup.mcp.js

@@ -53,6 +53,7 @@ TagGroup renders a finite set of selectable tags as chips. It is a form input fo
 - **name**: string - Form field name.
 - **required**: boolean (default: false) - Marks selection as required.
 - **disabled**: boolean (default: false) - Disables all tag buttons.
+- **readOnly**: boolean (default: false) - Tags stay focusable but pressing them changes nothing; the selection still validates and submits.
 
 ### Option Props
 - **value**: string - Unique selection value.