entasis 0.11.0 → 0.12.0

package/dist/components/Form/PhoneInput/PhoneInputCountryPicker.svelte

@@ -9,6 +9,8 @@
 	import TextInput from '../TextInput/TextInput.svelte';
 	import type { Sizes } from '../../../types/theme.js';
 	import { useListNavigation } from '../../../utils/useListNavigation.svelte.js';
+	import { useLiveAnnouncer } from '../../../utils/useLiveAnnouncer.svelte.js';
+	import { untrack } from 'svelte';
 	import type { PhoneInputThemeProps } from './phoneInput.theme.js';
 	import { usePhoneInputTheme } from './phoneInput.theme.js';
 	import { filterPhoneCountryOptions, type PhoneCountryOption } from './phoneInputCountry.js';
@@ -44,7 +46,7 @@
 	const listboxId = $derived(`${id}-listbox`);
 	const classes = $derived(usePhoneInputTheme(theme));
 	const t = $derived(useI18n());
-	const filteredCountries = $derived(filterPhoneCountryOptions(countries, searchQuery));
+	const filteredCountries = $derived(filterPhoneCountryOptions(countries, searchQuery, t.locale));
 	const optionId = (iso2: string) => `${id}-option-${iso2}`;
 
 	const selectCountry = (iso2: string) => {
@@ -52,21 +54,34 @@
 		if (country) onSelectCountry(country);
 	};
 
+	// The selected country is highlighted when the picker opens and again when the search clears.
 	const nav = useListNavigation({
 		values: () => filteredCountries.map((country) => country.iso2),
 		optionId,
+		query: () => searchQuery,
+		anchor: () => selectedCountry?.iso2,
 		onSelect: selectCountry
 	});
 
-	const highlightSelectedCountry = () => {
-		const selectedIso2 = selectedCountry?.iso2;
-		if (selectedIso2 && filteredCountries.some((country) => country.iso2 === selectedIso2)) {
-			nav.highlight(selectedIso2);
-			return;
-		}
-
-		nav.first();
-	};
+	// Result counts and the empty state reach screen readers through one persistent region,
+	// announced after typing settles (a region that mounts already filled is skipped).
+	const announcer = useLiveAnnouncer(generatedId, 'live');
+	$effect(() => {
+		const message =
+			filteredCountries.length === 0
+				? t.noCountries
+				: searchQuery.trim()
+					? t.resultsCount(filteredCountries.length)
+					: '';
+		return untrack(() => {
+			if (!message) {
+				announcer.reset();
+				return;
+			}
+			const timer = setTimeout(() => announcer.announce(message), 250);
+			return () => clearTimeout(timer);
+		});
+	});
 
 	const attachSearchInput: Attachment<HTMLElement> = (node) => {
 		const input = node.querySelector<HTMLInputElement>('input');
@@ -75,17 +90,13 @@
 		searchInput = input;
 		input.setAttribute('role', 'combobox');
 		input.setAttribute('aria-autocomplete', 'list');
-		input.setAttribute('aria-expanded', 'true');
 		input.setAttribute('aria-haspopup', 'listbox');
 		input.setAttribute('autocomplete', 'off');
 		input.setAttribute('autocorrect', 'off');
 		input.setAttribute('autocapitalize', 'off');
 		input.setAttribute('spellcheck', 'false');
 
-		const focusTimeout = setTimeout(() => {
-			input.focus();
-			highlightSelectedCountry();
-		}, 0);
+		const focusTimeout = setTimeout(() => input.focus(), 0);
 		const removeKeydown = on(input, 'keydown', nav.onKeydown);
 
 		return () => {
@@ -109,6 +120,8 @@
 		if (!searchInput) return;
 
 		searchInput.setAttribute('aria-controls', listboxId);
+		// The listbox is hidden while the search matches nothing, so the combobox is collapsed.
+		searchInput.setAttribute('aria-expanded', String(filteredCountries.length > 0));
 		if (nav.activeDescendant) {
 			searchInput.setAttribute('aria-activedescendant', nav.activeDescendant);
 		} else {
@@ -121,6 +134,7 @@
 	<TextInput
 		{@attach attachSearchInput}
 		bind:value={searchQuery}
+		inputAttrs={{ 'data-1p-ignore': true }}
 		placeholder={searchPlaceholder}
 		{size}
 		class={classes.countrySearch({ class: theme?.countrySearch?.base })}
@@ -145,7 +159,23 @@
 		type="auto"
 		class={classes.countryList({ class: theme?.countryList?.base })}
 	>
-		<div id={listboxId} role="listbox" aria-label={t.countries} class={classes.countryListbox()}>
+		<!-- The empty message lives OUTSIDE the listbox: a listbox may only own options and groups
+		     (aria-required-children). The persistent live region announces it and the result counts:
+		     screen readers skip a live region that mounts already filled. -->
+		{#if filteredCountries.length === 0}
+			<div class={classes.countryEmpty({ size, class: theme?.countryEmpty?.base })}>
+				{t.noCountries}
+			</div>
+		{/if}
+		<span class="sr-only" {...announcer.regionAttrs}>{announcer.message}</span>
+		<!-- Kept mounted while empty (hidden) so the search input's aria-controls always resolves. -->
+		<div
+			id={listboxId}
+			role="listbox"
+			aria-label={t.countries}
+			hidden={filteredCountries.length === 0}
+			class={classes.countryListbox()}
+		>
 			{#each filteredCountries as country (country.iso2)}
 				{@const selected = country.iso2 === selectedCountry?.iso2}
 				{@const highlighted = nav.highlighted === country.iso2}
@@ -166,7 +196,7 @@
 						highlighted,
 						class: theme?.countryOption?.base
 					})}
-					onpointermove={() => nav.setHighlighted(country.iso2)}
+					onpointermove={(event) => nav.pointerHighlight(country.iso2, event)}
 					onclick={() => onSelectCountry(country)}
 				>
 					<span class={classes.countryFlag({ size, class: theme?.countryFlag?.base })}>
@@ -189,10 +219,6 @@
 						})}
 					{/if}
 				</Button>
-			{:else}
-				<div class={classes.countryEmpty({ size, class: theme?.countryEmpty?.base })}>
-					{t.noCountries}
-				</div>
 			{/each}
 		</div>
 	</ScrollArea>

package/dist/components/Form/PhoneInput/phoneInput-cdn.js

@@ -1,3 +1,4 @@
+import { applyCspNonce } from '../../../utils/cspNonce.js';
 const INTL_TEL_INPUT_CDN_VERSION = '29.1.1';
 const INTL_TEL_INPUT_SCRIPT_ID = 'entasis-intl-tel-input-script';
 const INTL_TEL_INPUT_SCRIPT_URL = `https://cdn.jsdelivr.net/npm/intl-tel-input@${INTL_TEL_INPUT_CDN_VERSION}/dist/js/intlTelInputWithUtils.min.js`;
@@ -50,7 +51,7 @@ function createIntlTelInputScriptPromise() {
     });
 }
 function createIntlTelInputScript() {
-    const script = document.createElement('script');
+    const script = applyCspNonce(document.createElement('script'));
     script.id = INTL_TEL_INPUT_SCRIPT_ID;
     script.src = INTL_TEL_INPUT_SCRIPT_URL;
     script.async = true;

package/dist/components/Form/PhoneInput/phoneInput.mcp.d.ts

@@ -1 +1 @@
-export declare const phoneInputDescription = "\n# PhoneInput Component\n\nThe PhoneInput component provides a formatted input field for phone numbers with country code selection and automatic formatting. [intl-tel-input](https://intl-tel-input.com/) is loaded from a CDN at runtime and never bundled. A strict Content-Security-Policy must allow `cdn.jsdelivr.net` in `script-src`.\n\n## Basic Usage\n\n```svelte\n<script>\n\tlet phone = $state('');\n</script>\n\n<PhoneInput label=\"Phone Number\" bind:value={phone} />\n```\n\n## Props\n\nExtends all Field component props plus:\n\n### Core Props\n- **value**: string (bindable) - Phone number value\n- **country**: string (bindable, default: 'fr') - ISO country code selected in the country picker\n- **placeholder**: string - Placeholder text\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 input\n- **size**: 'small' | 'normal' | 'large'\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<Label />\n\t<Description />\n\t<InputContainer>\n\t\t<CountrySelector />\n\t\t<PhoneNumberInput />\n\t</InputContainer>\n\t<Error />\n</Field>\n```\n\n## Examples\n\n### Basic Phone Input\n```svelte\n<script>\n\tlet phone = $state('');\n</script>\n\n<PhoneInput \n\tlabel=\"Phone Number\"\n\tbind:value={phone}\n/>\n```\n\n### With Default Country\n```svelte\n<PhoneInput \n\tlabel=\"Phone Number\"\n\tbind:value={phone}\n\tcountry=\"gb\"\n/>\n```\n\n### Required Field\n```svelte\n<PhoneInput \n\tlabel=\"Contact Number\"\n\tbind:value={phone}\n\trequired\n/>\n```\n\n### With Description\n```svelte\n<PhoneInput \n\tlabel=\"Mobile Number\"\n\tdescription=\"We'll send verification code to this number\"\n\tbind:value={phone}\n/>\n```\n\n### Disabled State\n```svelte\n<PhoneInput \n\tlabel=\"Phone\"\n\tvalue=\"+1 234 567 8900\"\n\tdisabled\n/>\n```\n\n### Contact Form\n```svelte\n<script>\n\tlet contact = $state({\n\t\tname: '',\n\t\temail: '',\n\t\tphone: ''\n\t});\n</script>\n\n<form>\n\t<TextInput \n\t\tlabel=\"Name\"\n\t\tbind:value={contact.name}\n\t\trequired\n\t/>\n\t\n\t<TextInput \n\t\ttype=\"email\"\n\t\tlabel=\"Email\"\n\t\tbind:value={contact.email}\n\t\trequired\n\t/>\n\t\n\t<PhoneInput \n\t\tlabel=\"Phone\"\n\t\tbind:value={contact.phone}\n\t\trequired\n\t/>\n\t\n\t<Button type=\"submit\">Submit</Button>\n</form>\n```\n\n### Multiple Phone Numbers\n```svelte\n<script>\n\tlet phones = $state({\n\t\thome: '',\n\t\tmobile: '',\n\t\twork: ''\n\t});\n</script>\n\n<PhoneInput \n\tlabel=\"Home Phone\"\n\tbind:value={phones.home}\n/>\n\n<PhoneInput \n\tlabel=\"Mobile Phone\"\n\tbind:value={phones.mobile}\n\trequired\n/>\n\n<PhoneInput \n\tlabel=\"Work Phone\"\n\tbind:value={phones.work}\n/>\n```\n\n### With Validation\n```svelte\n<script>\n\tlet phone = $state('');\n\tlet error = $state('');\n\t\n\tfunction validatePhone(value) {\n\t\t// Simple validation - in production use a proper library\n\t\tif (!value) return '';\n\t\tif (value.length < 10) return 'Phone number is too short';\n\t\treturn '';\n\t}\n\t\n\t$effect(() => {\n\t\terror = validatePhone(phone);\n\t});\n</script>\n\n<PhoneInput \n\tlabel=\"Phone Number\"\n\tbind:value={phone}\n\terror={error}\n\trequired\n/>\n```\n\n### International Support\n```svelte\n<script>\n\tlet phoneNumbers = $state({\n\t\tus: '',\n\t\tuk: '',\n\t\tfr: ''\n\t});\n</script>\n\n<PhoneInput \n\tlabel=\"US Number\"\n\tbind:value={phoneNumbers.us}\n\tcountry=\"us\"\n/>\n\n<PhoneInput \n\tlabel=\"UK Number\"\n\tbind:value={phoneNumbers.uk}\n\tcountry=\"gb\"\n/>\n\n<PhoneInput \n\tlabel=\"France Number\"\n\tbind:value={phoneNumbers.fr}\n\tcountry=\"fr\"\n/>\n```\n\n### Delivery Information\n```svelte\n<script>\n\tlet delivery = $state({\n\t\taddress: '',\n\t\tphone: '',\n\t\tnotes: ''\n\t});\n</script>\n\n<form>\n\t<TextArea \n\t\tlabel=\"Delivery Address\"\n\t\tbind:value={delivery.address}\n\t\trequired\n\t/>\n\t\n\t<PhoneInput \n\t\tlabel=\"Contact Phone\"\n\t\tdescription=\"For delivery updates\"\n\t\tbind:value={delivery.phone}\n\t\trequired\n\t/>\n\t\n\t<TextArea \n\t\tlabel=\"Delivery Notes\"\n\t\tbind:value={delivery.notes}\n\t/>\n\t\n\t<Button type=\"submit\">Confirm Order</Button>\n</form>\n```\n\n## Formatting\n\nPhoneInput automatically formats numbers based on the selected country:\n- US: (123) 456-7890\n- UK: 07123 456789\n- International: +XX XXX XXX XXXX\n\n## Country Selection\n\n- Searchable dropdown of countries\n- Country flags displayed\n- International dialing codes shown\n- Detects country from phone number\n\n## Validation\n\nPhoneInput validates:\n- **required**: Non-empty phone number\n- **format**: Valid phone number format for selected country\n- **length**: Appropriate length for country\n\n## Accessibility\n\n- Proper label association\n- Country selector is keyboard accessible\n- ARIA attributes for required state\n- Error messages announced\n- Focus management between country and number\n\n## Notes\n\n- intl-tel-input loads from a CDN on first mount; nothing is bundled. A network connection is required for formatting and validation.\n- Automatically formats as user types\n- Supports international phone numbers\n- Country code is included in value\n- Validation depends on country format\n- Works with form libraries and validation schemas\n\n## Theme Customization\n\nThe PhoneInput component uses a theme object that can be customized using the `theme` prop or by setting a global theme. It shares the same theme structure as TextInput.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **input**: Input element styles\n- **inputContainer**: Input container wrapper styles\n\n### Available Variants\n\n**input**:\n- base: Base classes applied to the input element\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n  - disabled: boolean - Disabled state styling\n\n**inputContainer**:\n- base: Base classes for the input container (handles focus states, borders, padding)\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Size-based styling\n  - disabled: boolean - Disabled state styling\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<PhoneInput \n  label=\"Phone Number\"\n  bind:value={phone}\n  theme={{\n    inputContainer: {\n      base: 'border-2 rounded-lg',\n      size: {\n        normal: 'px-4 py-2'\n      }\n    },\n    input: {\n      size: {\n        normal: 'text-base'\n      }\n    }\n  }}\n/>\n```\n\n**Focus State Customization**:\n\nTo recolor every focus ring in the app at once, set `designTokens.focusColor` on `Theme`\ninstead of overriding per component. `ring-focus` is the focus state role and falls back to the\ncurrent role, so it never hard-pins a color.\n\n```svelte\n<PhoneInput \n  label=\"Contact Phone\"\n  bind:value={phone}\n  theme={{\n    inputContainer: {\n      base: 'focus-within:ring-2 focus-within:ring-focus/50 focus-within:border-focus'\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setPhoneInputTheme } from './index.ts';\n  \n  setPhoneInputTheme({\n    inputContainer: {\n      base: 'rounded-lg border-2 transition-all',\n      size: {\n        normal: 'px-4 py-2'\n      }\n    },\n    input: {\n      base: 'placeholder:text-gray-400'\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 phoneInputDescription = "\n# PhoneInput Component\n\nThe PhoneInput component provides a formatted input field for phone numbers with country code selection and automatic formatting. [intl-tel-input](https://intl-tel-input.com/) is loaded from a CDN at runtime and never bundled. A strict Content-Security-Policy must allow `cdn.jsdelivr.net` in `script-src`.\n\n## Basic Usage\n\n```svelte\n<script>\n\tlet phone = $state('');\n</script>\n\n<PhoneInput label=\"Phone Number\" bind:value={phone} />\n```\n\n## Props\n\nExtends all Field component props plus:\n\n### Core Props\n- **value**: string (bindable) - Phone number value\n- **country**: string (bindable, default: 'fr') - ISO country code selected in the country picker\n- **placeholder**: string - Placeholder text\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 input\n- **readOnly**: boolean - Make the input read-only: stays focusable and announced as read-only, refuses edits, and still validates and submits. A read-only Form, FormGroup or fieldset Field makes it read-only too\n- **size**: 'small' | 'normal' | 'large'\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<Label />\n\t<Description />\n\t<InputContainer>\n\t\t<CountrySelector />\n\t\t<PhoneNumberInput />\n\t</InputContainer>\n\t<Error />\n</Field>\n```\n\n## Examples\n\n### Basic Phone Input\n```svelte\n<script>\n\tlet phone = $state('');\n</script>\n\n<PhoneInput \n\tlabel=\"Phone Number\"\n\tbind:value={phone}\n/>\n```\n\n### With Default Country\n```svelte\n<PhoneInput \n\tlabel=\"Phone Number\"\n\tbind:value={phone}\n\tcountry=\"gb\"\n/>\n```\n\n### Required Field\n```svelte\n<PhoneInput \n\tlabel=\"Contact Number\"\n\tbind:value={phone}\n\trequired\n/>\n```\n\n### With Description\n```svelte\n<PhoneInput \n\tlabel=\"Mobile Number\"\n\tdescription=\"We'll send verification code to this number\"\n\tbind:value={phone}\n/>\n```\n\n### Disabled State\n```svelte\n<PhoneInput \n\tlabel=\"Phone\"\n\tvalue=\"+1 234 567 8900\"\n\tdisabled\n/>\n```\n\n### Contact Form\n```svelte\n<script>\n\tlet contact = $state({\n\t\tname: '',\n\t\temail: '',\n\t\tphone: ''\n\t});\n</script>\n\n<form>\n\t<TextInput \n\t\tlabel=\"Name\"\n\t\tbind:value={contact.name}\n\t\trequired\n\t/>\n\t\n\t<TextInput \n\t\ttype=\"email\"\n\t\tlabel=\"Email\"\n\t\tbind:value={contact.email}\n\t\trequired\n\t/>\n\t\n\t<PhoneInput \n\t\tlabel=\"Phone\"\n\t\tbind:value={contact.phone}\n\t\trequired\n\t/>\n\t\n\t<Button type=\"submit\">Submit</Button>\n</form>\n```\n\n### Multiple Phone Numbers\n```svelte\n<script>\n\tlet phones = $state({\n\t\thome: '',\n\t\tmobile: '',\n\t\twork: ''\n\t});\n</script>\n\n<PhoneInput \n\tlabel=\"Home Phone\"\n\tbind:value={phones.home}\n/>\n\n<PhoneInput \n\tlabel=\"Mobile Phone\"\n\tbind:value={phones.mobile}\n\trequired\n/>\n\n<PhoneInput \n\tlabel=\"Work Phone\"\n\tbind:value={phones.work}\n/>\n```\n\n### With Validation\n```svelte\n<script>\n\tlet phone = $state('');\n\tlet error = $state('');\n\t\n\tfunction validatePhone(value) {\n\t\t// Simple validation - in production use a proper library\n\t\tif (!value) return '';\n\t\tif (value.length < 10) return 'Phone number is too short';\n\t\treturn '';\n\t}\n\t\n\t$effect(() => {\n\t\terror = validatePhone(phone);\n\t});\n</script>\n\n<PhoneInput \n\tlabel=\"Phone Number\"\n\tbind:value={phone}\n\terror={error}\n\trequired\n/>\n```\n\n### International Support\n```svelte\n<script>\n\tlet phoneNumbers = $state({\n\t\tus: '',\n\t\tuk: '',\n\t\tfr: ''\n\t});\n</script>\n\n<PhoneInput \n\tlabel=\"US Number\"\n\tbind:value={phoneNumbers.us}\n\tcountry=\"us\"\n/>\n\n<PhoneInput \n\tlabel=\"UK Number\"\n\tbind:value={phoneNumbers.uk}\n\tcountry=\"gb\"\n/>\n\n<PhoneInput \n\tlabel=\"France Number\"\n\tbind:value={phoneNumbers.fr}\n\tcountry=\"fr\"\n/>\n```\n\n### Delivery Information\n```svelte\n<script>\n\tlet delivery = $state({\n\t\taddress: '',\n\t\tphone: '',\n\t\tnotes: ''\n\t});\n</script>\n\n<form>\n\t<TextArea \n\t\tlabel=\"Delivery Address\"\n\t\tbind:value={delivery.address}\n\t\trequired\n\t/>\n\t\n\t<PhoneInput \n\t\tlabel=\"Contact Phone\"\n\t\tdescription=\"For delivery updates\"\n\t\tbind:value={delivery.phone}\n\t\trequired\n\t/>\n\t\n\t<TextArea \n\t\tlabel=\"Delivery Notes\"\n\t\tbind:value={delivery.notes}\n\t/>\n\t\n\t<Button type=\"submit\">Confirm Order</Button>\n</form>\n```\n\n## Formatting\n\nPhoneInput automatically formats numbers based on the selected country:\n- US: (123) 456-7890\n- UK: 07123 456789\n- International: +XX XXX XXX XXXX\n\n## Country Selection\n\n- Searchable dropdown of countries: names are written, sorted and searched in the active I18n locale (`Intl.DisplayNames`), ignoring case and accents (\"cote\" finds \"C\u00F4te d\u2019Ivoire\"); the dial code (`+33`) and ISO code match too\n- The selected country is highlighted when the picker opens and again when the search is cleared\n- Country flags displayed\n- International dialing codes shown\n- Detects country from phone number\n\n## Validation\n\nPhoneInput validates:\n- **required**: Non-empty phone number\n- **format**: Valid phone number format for selected country\n- **length**: Appropriate length for country\n\n## Accessibility\n\n- Proper label association\n- Country selector is keyboard accessible: the search input is a `role=\"combobox\"` that drives the country `role=\"listbox\"` through `aria-activedescendant`\n- A persistent visually hidden `role=\"status\"` region inside the picker announces result counts (\"3 results available\") and \"No countries found\" after typing settles; the visible empty message is plain text outside the listbox, the empty listbox is hidden and the search combobox reports `aria-expanded=\"false\"`\n- ARIA attributes for required state\n- Error messages announced\n- Focus management between country and number\n\n## Notes\n\n- intl-tel-input loads from a CDN on first mount; nothing is bundled. A network connection is required for formatting and validation.\n- Automatically formats as user types\n- Supports international phone numbers\n- Country code is included in value\n- Validation depends on country format\n- Works with form libraries and validation schemas\n- Password managers and browser autofill are not blocked on the number input\n\n## Theme Customization\n\nThe PhoneInput component uses a theme object that can be customized using the `theme` prop or by setting a global theme. It shares the same theme structure as TextInput.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **input**: Input element styles\n- **inputContainer**: Input container wrapper styles\n\n### Available Variants\n\n**input**:\n- base: Base classes applied to the input element\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n  - disabled: boolean - Disabled state styling\n\n**inputContainer**:\n- base: Base classes for the input container (handles focus states, borders, padding)\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Size-based styling\n  - disabled: boolean - Disabled state styling\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<PhoneInput \n  label=\"Phone Number\"\n  bind:value={phone}\n  theme={{\n    inputContainer: {\n      base: 'border-2 rounded-lg',\n      size: {\n        normal: 'px-4 py-2'\n      }\n    },\n    input: {\n      size: {\n        normal: 'text-base'\n      }\n    }\n  }}\n/>\n```\n\n**Focus State Customization**:\n\nTo recolor every focus ring in the app at once, set `designTokens.focusColor` on `Theme`\ninstead of overriding per component. `ring-focus` is the focus state role and falls back to the\ncurrent role, so it never hard-pins a color.\n\n```svelte\n<PhoneInput \n  label=\"Contact Phone\"\n  bind:value={phone}\n  theme={{\n    inputContainer: {\n      base: 'focus-within:ring-2 focus-within:ring-focus/50 focus-within:border-focus'\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setPhoneInputTheme } from './index.ts';\n  \n  setPhoneInputTheme({\n    inputContainer: {\n      base: 'rounded-lg border-2 transition-all',\n      size: {\n        normal: 'px-4 py-2'\n      }\n    },\n    input: {\n      base: 'placeholder:text-gray-400'\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/PhoneInput/phoneInput.mcp.js

@@ -28,6 +28,7 @@ Extends all Field component props plus:
 - **error**: string - Error message
 - **required**: boolean - Mark as required
 - **disabled**: boolean - Disable input
+- **readOnly**: boolean - Make the input read-only: stays focusable and announced as read-only, refuses edits, and still validates and submits. A read-only Form, FormGroup or fieldset Field makes it read-only too
 - **size**: 'small' | 'normal' | 'large'
 
 ### Styling Props
@@ -256,7 +257,8 @@ PhoneInput automatically formats numbers based on the selected country:
 
 ## Country Selection
 
-- Searchable dropdown of countries
+- Searchable dropdown of countries: names are written, sorted and searched in the active I18n locale (\`Intl.DisplayNames\`), ignoring case and accents ("cote" finds "Côte d’Ivoire"); the dial code (\`+33\`) and ISO code match too
+- The selected country is highlighted when the picker opens and again when the search is cleared
 - Country flags displayed
 - International dialing codes shown
 - Detects country from phone number
@@ -271,7 +273,8 @@ PhoneInput validates:
 ## Accessibility
 
 - Proper label association
-- Country selector is keyboard accessible
+- Country selector is keyboard accessible: the search input is a \`role="combobox"\` that drives the country \`role="listbox"\` through \`aria-activedescendant\`
+- A persistent visually hidden \`role="status"\` region inside the picker announces result counts ("3 results available") and "No countries found" after typing settles; the visible empty message is plain text outside the listbox, the empty listbox is hidden and the search combobox reports \`aria-expanded="false"\`
 - ARIA attributes for required state
 - Error messages announced
 - Focus management between country and number
@@ -284,6 +287,7 @@ PhoneInput validates:
 - Country code is included in value
 - Validation depends on country format
 - Works with form libraries and validation schemas
+- Password managers and browser autofill are not blocked on the number input
 
 ## Theme Customization
 

package/dist/components/Form/PhoneInput/phoneInputCountry.d.ts

@@ -4,8 +4,14 @@ export type PhoneCountryOption = {
     name: string;
     dialCode: string;
     flag: string;
-    searchText: string;
 };
-export declare const createPhoneCountryOptions: (countries: PhoneCountry[]) => PhoneCountryOption[];
-export declare const filterPhoneCountryOptions: (countries: PhoneCountryOption[], searchQuery: string) => PhoneCountryOption[];
+/**
+ * The country list with names written in `locale` and sorted by that locale's alphabet.
+ */
+export declare const createPhoneCountryOptions: (countries: PhoneCountry[], locale?: string) => PhoneCountryOption[];
+/**
+ * The countries whose name, ISO code or dial code (`+33`) contains the search text, ignoring case
+ * and accents in `locale`.
+ */
+export declare const filterPhoneCountryOptions: (countries: PhoneCountryOption[], searchQuery: string, locale?: string) => PhoneCountryOption[];
 export declare const getPhoneCountryOption: (countries: PhoneCountryOption[], iso2?: string | null) => PhoneCountryOption | null;

package/dist/components/Form/PhoneInput/phoneInputCountry.js

@@ -1,42 +1,52 @@
-const normalizeSearchText = (value) => value
-    .normalize('NFD')
-    .replace(/[\u0300-\u036f]/g, '')
-    .toLowerCase();
-const getDisplayNames = () => {
+import { createListFilter } from '../../../utils/listFilter.js';
+const getDisplayNames = (locale) => {
     if (typeof Intl === 'undefined' || typeof Intl.DisplayNames !== 'function') {
         return null;
     }
     try {
-        return new Intl.DisplayNames('en', { type: 'region' });
+        return new Intl.DisplayNames(locale, { type: 'region' });
     }
     catch {
         return null;
     }
 };
+const getCollator = (locale) => {
+    try {
+        return new Intl.Collator(locale);
+    }
+    catch {
+        return new Intl.Collator();
+    }
+};
 const getCountryName = (iso2, displayNames) => displayNames?.of(iso2.toUpperCase()) || iso2.toUpperCase();
 const getCountryFlag = (iso2) => iso2.toUpperCase().replace(/./g, (letter) => String.fromCodePoint(127397 + letter.charCodeAt(0)));
-export const createPhoneCountryOptions = (countries) => {
-    const displayNames = getDisplayNames();
+/**
+ * The country list with names written in `locale` and sorted by that locale's alphabet.
+ */
+export const createPhoneCountryOptions = (countries, locale = 'en') => {
+    const displayNames = getDisplayNames(locale);
+    const collator = getCollator(locale);
     return countries
-        .map((country) => {
-        const name = getCountryName(country.iso2, displayNames);
-        const dialCode = `+${country.dialCode}`;
-        return {
-            iso2: country.iso2,
-            name,
-            dialCode: country.dialCode,
-            flag: getCountryFlag(country.iso2),
-            searchText: normalizeSearchText(`${name} ${country.iso2} ${dialCode}`)
-        };
-    })
-        .sort((firstCountry, secondCountry) => firstCountry.name.localeCompare(secondCountry.name));
+        .map((country) => ({
+        iso2: country.iso2,
+        name: getCountryName(country.iso2, displayNames),
+        dialCode: country.dialCode,
+        flag: getCountryFlag(country.iso2)
+    }))
+        .sort((firstCountry, secondCountry) => collator.compare(firstCountry.name, secondCountry.name));
 };
-export const filterPhoneCountryOptions = (countries, searchQuery) => {
-    const normalizedQuery = normalizeSearchText(searchQuery.trim());
-    if (!normalizedQuery) {
+/**
+ * The countries whose name, ISO code or dial code (`+33`) contains the search text, ignoring case
+ * and accents in `locale`.
+ */
+export const filterPhoneCountryOptions = (countries, searchQuery, locale = 'en') => {
+    const query = searchQuery.trim();
+    if (!query) {
         return countries;
     }
-    return countries.filter((country) => country.searchText.includes(normalizedQuery));
+    return createListFilter({ locale }).filter(countries, query, {
+        text: (country) => [country.name, country.iso2, `+${country.dialCode}`]
+    });
 };
 export const getPhoneCountryOption = (countries, iso2) => {
     if (!iso2) {

package/dist/components/Form/PinInput/PinInput.svelte

@@ -1,10 +1,15 @@
 <script lang="ts">
 	import { untrack } from 'svelte';
 	import Field from '../Field/Field.svelte';
-	import { createFieldState } from '../Field/field.state.svelte.js';
+	import { createFieldState, type FieldValidatorResult } from '../Field/field.state.svelte.js';
+	import { useI18n } from '../../../i18n/context.svelte.js';
 	import PinInputCells from './PinInputCells.svelte';
 	import type { PinInputProps } from './pinInput.props.js';
-	import { PIN_INPUT_DIGITS_PATTERN, PinInputState } from './pinInput.state.svelte.js';
+	import {
+		PIN_INPUT_DIGITS_PATTERN,
+		PIN_INPUT_TEXT_MARGIN,
+		PinInputState
+	} from './pinInput.state.svelte.js';
 	import { usePinInputTheme } from './pinInput.theme.js';
 
 	let {
@@ -18,9 +23,15 @@
 		inputMode = 'numeric',
 		autocomplete = 'one-time-code',
 		pasteTransformer,
+		normalizeValue,
+		onRejectInput,
+		submitOnComplete = false,
+		groups,
 		mask = false,
 		theme,
 		disabled,
+		readOnly,
+		messages,
 		name,
 		onValidate,
 		onValueChange,
@@ -30,6 +41,7 @@
 		description,
 		...rest
 	}: PinInputProps = $props();
+	const t = $derived(useI18n());
 	if (value === undefined) value = untrack(() => defaultValue);
 
 	const id = $props.id();
@@ -62,6 +74,12 @@
 		set disabled(v: boolean | undefined) {
 			disabled = v;
 		},
+		get readOnly() {
+			return readOnly;
+		},
+		get messages() {
+			return messages;
+		},
 		get required() {
 			return required;
 		},
@@ -71,9 +89,9 @@
 		set name(v: string | undefined) {
 			name = v;
 		},
-		onValidate: (currentValue) => {
+		onValidate: (currentValue): FieldValidatorResult => {
 			if (required && typeof currentValue === 'string' && currentValue.length < resolvedLength()) {
-				return true;
+				return field.messages.incomplete(resolvedLength());
 			}
 			return onValidate?.(currentValue) || false;
 		},
@@ -94,8 +112,18 @@
 		length: resolvedLength,
 		pattern: () => pattern,
 		pasteTransformer: () => pasteTransformer,
+		normalizeValue: () => normalizeValue,
+		onRejectInput: () => onRejectInput,
 		onComplete: () => onComplete,
-		disabled: () => field.disabled
+		// Inside a Form it validates first and keeps focus on an earlier invalid field; the code
+		// input never takes focus back. Outside one, the native form submits.
+		submit: () => () => {
+			if (field.form) void field.form.submit();
+			else (field.node as HTMLInputElement | null)?.form?.requestSubmit();
+		},
+		submitOnComplete: () => submitOnComplete,
+		disabled: () => field.disabled,
+		readOnly: () => field.readOnly
 	});
 
 	const classes = $derived(usePinInputTheme(theme));
@@ -118,10 +146,14 @@
 	}}
 	{...rest}
 >
+	<!-- Digits and codes read left to right in every document direction, so the cells and the
+	     native caret over the transparent input agree. -->
 	<div
+		dir="ltr"
 		data-slot="pin-input"
 		data-focused={state.isFocused}
 		data-disabled={field.disabled}
+		data-readonly={field.readOnly || undefined}
 		class={classes.root({ size: rest.size, disabled: field.disabled })}
 	>
 		<input
@@ -129,21 +161,24 @@
 			{@attach state.inputAttachment}
 			data-slot="pin-input-input"
 			type="text"
+			dir="ltr"
 			{id}
 			name={field.name}
 			value={state.value}
-			maxlength={state.length}
+			maxlength={state.length + PIN_INPUT_TEXT_MARGIN}
 			inputmode={inputMode}
 			{autocomplete}
 			disabled={field.disabled}
-			aria-label={label ? undefined : 'One-time code'}
-			class={classes.input()}
+			aria-label={label ? undefined : t.oneTimeCode}
+			class={classes.input({ composing: state.isComposing })}
 			data-pin-input-input
 			data-pin-input-input-mss={state.selectionStart}
 			data-pin-input-input-mse={state.selectionEnd}
 			onpointerdown={state.handlePointerDown}
 			onkeydown={state.handleKeydown}
 			oninput={state.handleInput}
+			oncompositionstart={state.handleCompositionStart}
+			oncompositionend={state.handleCompositionEnd}
 			onpaste={state.handlePaste}
 			onfocus={state.handleFocus}
 			onblur={state.handleBlur}
@@ -151,6 +186,6 @@
 			onkeyup={state.normalizeSelection}
 			onclick={state.normalizeSelection}
 		/>
-		<PinInputCells {state} {classes} size={rest.size} disabled={field.disabled} {mask} />
+		<PinInputCells {state} {classes} size={rest.size} disabled={field.disabled} {mask} {groups} />
 	</div>
 </Field>

package/dist/components/Form/PinInput/PinInputCells.svelte

@@ -10,15 +10,29 @@
 		classes,
 		size,
 		disabled,
-		mask = false
+		mask = false,
+		groups
 	}: {
 		state: PinInputState;
 		classes: PinInputClasses;
 		size?: Sizes;
 		disabled?: boolean;
 		mask?: boolean;
+		groups?: number[];
 	} = $props();
 
+	// Indexes of the cells a separator follows: the end of every group but the last cell's.
+	const separatorAfter = $derived.by(() => {
+		const after: number[] = [];
+		let end = 0;
+		for (const group of groups ?? []) {
+			if (!Number.isFinite(group) || group < 1) continue;
+			end += Math.floor(group);
+			if (end < state.length) after.push(end - 1);
+		}
+		return after;
+	});
+
 	const displayValue = (char: string | null) => (mask && char ? '•' : char);
 </script>
 
@@ -42,4 +56,11 @@
 			</span>
 		{/if}
 	</div>
+	{#if separatorAfter.includes(cell.index)}
+		<div
+			data-slot="pin-input-separator"
+			aria-hidden="true"
+			class={classes.separator({ size })}
+		></div>
+	{/if}
 {/each}

package/dist/components/Form/PinInput/PinInputCells.svelte.d.ts

@@ -8,6 +8,7 @@ type $$ComponentProps = {
     size?: Sizes;
     disabled?: boolean;
     mask?: boolean;
+    groups?: number[];
 };
 declare const PinInputCells: import("svelte").Component<$$ComponentProps, {}, "">;
 type PinInputCells = ReturnType<typeof PinInputCells>;

package/dist/components/Form/PinInput/index.d.ts

@@ -1,4 +1,4 @@
 export { default as PinInput } from './PinInput.svelte';
 export type { PinInputProps } from './pinInput.props.js';
-export { PIN_INPUT_ALPHANUMERIC_PATTERN, PIN_INPUT_CHARS_PATTERN, PIN_INPUT_DIGITS_PATTERN, type PinInputCell, type PinInputPattern } from './pinInput.state.svelte.js';
+export { PIN_INPUT_ALPHANUMERIC_PATTERN, PIN_INPUT_CHARS_PATTERN, PIN_INPUT_DIGITS_PATTERN, type PinInputCell, type PinInputPattern, type PinInputRejectDetail } from './pinInput.state.svelte.js';
 export { pinInputTheme, setPinInputTheme, usePinInputTheme, type PinInputTheme, type PinInputThemeProps } from './pinInput.theme.js';

package/dist/components/Form/PinInput/pinInput.mcp.d.ts

@@ -1 +1 @@
-export declare const pinInputDescription = "\n# PinInput Component\n\nPinInput is a one-time-code input built from one real text input plus visible cells. The real input owns focus, paste, autocomplete, form submission, and keyboard behavior; the cells are a derived display.\n\n## Basic Usage\n\n```svelte\n<script lang=\"ts\">\n\tlet code = $state('');\n</script>\n\n<PinInput label=\"Verification code\" bind:value={code} />\n```\n\n## Props\n\n### Core Props\n- **value**: string | null (bindable)\n  - Current code value.\n  - Clamped to the configured length.\n\n- **length**: number (default: 6)\n  - Number of visible cells and maximum input length.\n\n- **pattern**: string | RegExp (default: PIN_INPUT_DIGITS_PATTERN)\n  - Partial-value pattern used to accept typed and pasted values.\n  - Defaults to digits only.\n  - Exported constants: PIN_INPUT_DIGITS_PATTERN, PIN_INPUT_CHARS_PATTERN, PIN_INPUT_ALPHANUMERIC_PATTERN.\n\n- **pasteTransformer**: (text: string) => string\n  - Cleans pasted text before insertion.\n  - Use for values like \"123-456\" or \"123 456\".\n\n- **onComplete**: (value: string) => void\n  - Called once when the value reaches the configured length.\n\n- **onValueChange**: (value: string) => void\n  - Called when the value changes.\n\n### Input Props\n- **inputMode**: HTMLInputElement['inputMode'] (default: 'numeric')\n  - Mobile keyboard hint.\n\n- **autocomplete**: string (default: 'one-time-code')\n  - Enables OTP autofill where supported.\n\n- **mask**: boolean (default: false)\n  - Renders filled cells as bullets while preserving the real input value.\n\n### Field Props\nPinInput extends the standard field props:\n- **label**, **description**, **helper**, **error**, **errors**\n- **name**, **required**, **disabled**, **visible**\n- **size**: 'small' | 'normal' | 'large'\n- **theme** for field and pin input parts\n\n## Examples\n\n### Digits Only\n```svelte\n<PinInput\n\tlabel=\"Security code\"\n\tlength={6}\n\tbind:value={code}\n\tpasteTransformer={(text) => text.replace(/\\D/g, '')}\n/>\n```\n\n### Alphanumeric\n```svelte\n<PinInput\n\tlabel=\"Invite code\"\n\tlength={8}\n\tinputMode=\"text\"\n\tpattern={PIN_INPUT_ALPHANUMERIC_PATTERN}\n/>\n```\n\n### Masked\n```svelte\n<PinInput label=\"Recovery code\" bind:value={code} mask />\n```\n\n## Structure\n\n```\n<Field>\n  <InputContainer>\n    <div data-slot=\"pin-input\">\n      <input data-slot=\"pin-input-input\" />\n      <div data-slot=\"pin-input-cell\">\n        <span data-slot=\"pin-input-character\" />\n        <span data-slot=\"pin-input-caret\" />\n      </div>\n    </div>\n  </InputContainer>\n</Field>\n```\n\n## Accessibility\n\n- The label from Field is associated with the real input through `for/id`.\n- The visible cells are `aria-hidden`; assistive tech interacts with one text input.\n- The real input uses `autocomplete=\"one-time-code\"` by default.\n- Keyboard navigation, deletion, selection, and paste operate through the native input.\n\n## Notes\n\n- The pattern should accept partial values, not only the final full code. Use `^\\\\d+$`, not `^\\\\d{6}$`.\n- For pasted codes with spaces or hyphens, pass a `pasteTransformer`.\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 pinInputDescription = "\n# PinInput Component\n\nPinInput is a one-time-code input built from one real text input plus visible cells. The real input owns focus, paste, autocomplete, form submission, and keyboard behavior; the cells are a derived display.\n\n## Basic Usage\n\n```svelte\n<script lang=\"ts\">\n\tlet code = $state('');\n</script>\n\n<PinInput label=\"Verification code\" bind:value={code} />\n```\n\n## Props\n\n### Core Props\n- **value**: string | null (bindable)\n  - Current code value.\n  - Clamped to the configured length.\n\n- **length**: number (default: 6)\n  - Number of visible cells and maximum input length.\n\n- **pattern**: string | RegExp (default: PIN_INPUT_DIGITS_PATTERN)\n  - Partial-value pattern the code must match after normalization.\n  - Defaults to digits only.\n  - Text that fails it is refused whole (nothing changes) and reported to onRejectInput.\n  - Exported constants: PIN_INPUT_DIGITS_PATTERN, PIN_INPUT_CHARS_PATTERN, PIN_INPUT_ALPHANUMERIC_PATTERN.\n\n- **normalizeValue**: (text: string) => string\n  - Last step of the one normalization every typed, pasted, autofilled, composed and controlled code goes through. Before it: format controls and whitespace are removed, full-width characters and digits of other numeral systems (Arabic-Indic, Persian, Devanagari, Bengali, Thai, Han) become ASCII, and separators (dashes, dots, slashes, commas, colons) are removed unless the pattern accepts them. After it: the pattern check and the clamp to length.\n  - So \"123-456\", \"123 456\" and \"\u0664\u0665\u0666\" fill the default digits code with no setup, and `normalizeValue={(text) => text.toUpperCase()}` accepts lowercase typing in an alphanumeric code.\n  - Keep it idempotent: running it on its own output should change nothing.\n\n- **onRejectInput**: ({ text, source }) => void\n  - Called when the pattern refuses text; text is as it arrived and source is 'paste' or 'input' (typed or autofilled).\n\n- **pasteTransformer**: (text: string) => string\n  - A paste-only first step that runs before the shared normalization, for site-specific cleanup such as removing a prefix.\n  - A cleaned paste at least `length` characters long replaces the whole value, wherever the caret is; a shorter one is inserted at the caret.\n\n- **onComplete**: (value: string) => void\n  - Called when the value becomes complete, whether typed, pasted, autofilled, composed, or set by the parent.\n  - A paste or autofill that leaves the code complete calls it again, even when the code was already complete or unchanged, so re-pasting a code retries verification.\n  - Typing over one cell of a complete code does not call it.\n\n- **onValueChange**: (value: string) => void\n  - Called when the value changes.\n\n- **submitOnComplete**: boolean (default: false)\n  - Submits the owning form when the user types, pastes or autofills a complete code: through the surrounding Form (which validates first and focuses an earlier invalid field, so the code input does not take focus back), else the native form with requestSubmit(). A code set by the parent, a read-only input and a disabled input never submit.\n\n- **groups**: number[]\n  - Splits the cells into groups with a decorative separator between them: [3, 3] shows 123-456. Sizes that overshoot the length are ignored. The separator is aria-hidden and styled with the `separator` theme part.\n\n### Input Props\n- **inputMode**: HTMLInputElement['inputMode'] (default: 'numeric')\n  - Mobile keyboard hint.\n\n- **autocomplete**: string (default: 'one-time-code')\n  - Enables OTP autofill where supported.\n\n- **mask**: boolean (default: false)\n  - Renders filled cells as bullets while preserving the real input value.\n\n### Field Props\nPinInput extends the standard field props:\n- **label**, **description**, **helper**, **error**, **errors**\n- **name**, **required**, **disabled**, **visible**\n- **readOnly**: the code is focusable and announced as read-only; typing, paste, autofill and submitOnComplete are ignored, and the value still validates and submits\n- **size**: 'small' | 'normal' | 'large'\n- **theme** for field and pin input parts\n\n## Examples\n\n### Digits Only\n```svelte\n<PinInput\n\tlabel=\"Security code\"\n\tlength={6}\n\tbind:value={code}\n/>\n```\n\n### Alphanumeric\n```svelte\n<PinInput\n\tlabel=\"Invite code\"\n\tlength={8}\n\tinputMode=\"text\"\n\tpattern={PIN_INPUT_ALPHANUMERIC_PATTERN}\n/>\n```\n\n### Masked\n```svelte\n<PinInput label=\"Recovery code\" bind:value={code} mask />\n```\n\n## Structure\n\n```\n<Field>\n  <InputContainer>\n    <div data-slot=\"pin-input\">\n      <input data-slot=\"pin-input-input\" />\n      <div data-slot=\"pin-input-cell\">\n        <span data-slot=\"pin-input-character\" />\n        <span data-slot=\"pin-input-caret\" />\n      </div>\n      <div data-slot=\"pin-input-separator\" aria-hidden=\"true\" /> <!-- with groups -->\n    </div>\n  </InputContainer>\n</Field>\n```\n\n## Accessibility\n\n- The label from Field is associated with the real input through `for/id`.\n- The visible cells are `aria-hidden`; assistive tech interacts with one text input.\n- The real input uses `autocomplete=\"one-time-code\"` by default.\n- Without a label the input is named by the localized \"One-time code\" catalog message (`oneTimeCode`).\n- The cells and the input are `dir=\"ltr\"` in every document direction, so a code reads 123456 in right-to-left pages too and the caret agrees with the cells.\n- The component works inside a shadow root: focus and selection are read from the input's own root node.\n- Keyboard navigation, deletion, selection, and paste operate through the native input.\n- Input method (IME) composition, such as Japanese or Chinese input, is left to the input method: the cells show the in-progress text, and the text is checked and committed once when the composition ends. Full-width digits and letters (`\uFF11\uFF12\uFF13`) are committed as ASCII (`123`). While composing, the real input turns fully transparent (the `input` theme slot's `composing` variant, `opacity-0`), so the input method's underline or clause highlight does not cover the first cells.\n\n## Notes\n\n- The pattern should accept partial values, not only the final full code. Use `^\\\\d+$`, not `^\\\\d{6}$`.\n- Spaces, hyphens and other grouping separators in typed, pasted or autofilled codes are removed by the built-in normalization. Pass a `pasteTransformer` only for cleanup specific to your codes.\n- Composed text that the pattern rejects (for example hiragana in a digits-only field) is discarded, and the previous code and selection are restored.\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/PinInput/pinInput.mcp.js

@@ -24,20 +24,37 @@ PinInput is a one-time-code input built from one real text input plus visible ce
   - Number of visible cells and maximum input length.
 
 - **pattern**: string | RegExp (default: PIN_INPUT_DIGITS_PATTERN)
-  - Partial-value pattern used to accept typed and pasted values.
+  - Partial-value pattern the code must match after normalization.
   - Defaults to digits only.
+  - Text that fails it is refused whole (nothing changes) and reported to onRejectInput.
   - Exported constants: PIN_INPUT_DIGITS_PATTERN, PIN_INPUT_CHARS_PATTERN, PIN_INPUT_ALPHANUMERIC_PATTERN.
 
+- **normalizeValue**: (text: string) => string
+  - Last step of the one normalization every typed, pasted, autofilled, composed and controlled code goes through. Before it: format controls and whitespace are removed, full-width characters and digits of other numeral systems (Arabic-Indic, Persian, Devanagari, Bengali, Thai, Han) become ASCII, and separators (dashes, dots, slashes, commas, colons) are removed unless the pattern accepts them. After it: the pattern check and the clamp to length.
+  - So "123-456", "123 456" and "٤٥٦" fill the default digits code with no setup, and \`normalizeValue={(text) => text.toUpperCase()}\` accepts lowercase typing in an alphanumeric code.
+  - Keep it idempotent: running it on its own output should change nothing.
+
+- **onRejectInput**: ({ text, source }) => void
+  - Called when the pattern refuses text; text is as it arrived and source is 'paste' or 'input' (typed or autofilled).
+
 - **pasteTransformer**: (text: string) => string
-  - Cleans pasted text before insertion.
-  - Use for values like "123-456" or "123 456".
+  - A paste-only first step that runs before the shared normalization, for site-specific cleanup such as removing a prefix.
+  - A cleaned paste at least \`length\` characters long replaces the whole value, wherever the caret is; a shorter one is inserted at the caret.
 
 - **onComplete**: (value: string) => void
-  - Called once when the value reaches the configured length.
+  - Called when the value becomes complete, whether typed, pasted, autofilled, composed, or set by the parent.
+  - A paste or autofill that leaves the code complete calls it again, even when the code was already complete or unchanged, so re-pasting a code retries verification.
+  - Typing over one cell of a complete code does not call it.
 
 - **onValueChange**: (value: string) => void
   - Called when the value changes.
 
+- **submitOnComplete**: boolean (default: false)
+  - Submits the owning form when the user types, pastes or autofills a complete code: through the surrounding Form (which validates first and focuses an earlier invalid field, so the code input does not take focus back), else the native form with requestSubmit(). A code set by the parent, a read-only input and a disabled input never submit.
+
+- **groups**: number[]
+  - Splits the cells into groups with a decorative separator between them: [3, 3] shows 123-456. Sizes that overshoot the length are ignored. The separator is aria-hidden and styled with the \`separator\` theme part.
+
 ### Input Props
 - **inputMode**: HTMLInputElement['inputMode'] (default: 'numeric')
   - Mobile keyboard hint.
@@ -52,6 +69,7 @@ PinInput is a one-time-code input built from one real text input plus visible ce
 PinInput extends the standard field props:
 - **label**, **description**, **helper**, **error**, **errors**
 - **name**, **required**, **disabled**, **visible**
+- **readOnly**: the code is focusable and announced as read-only; typing, paste, autofill and submitOnComplete are ignored, and the value still validates and submits
 - **size**: 'small' | 'normal' | 'large'
 - **theme** for field and pin input parts
 
@@ -63,7 +81,6 @@ PinInput extends the standard field props:
 	label="Security code"
 	length={6}
 	bind:value={code}
-	pasteTransformer={(text) => text.replace(/\\D/g, '')}
 />
 \`\`\`
 
@@ -93,6 +110,7 @@ PinInput extends the standard field props:
         <span data-slot="pin-input-character" />
         <span data-slot="pin-input-caret" />
       </div>
+      <div data-slot="pin-input-separator" aria-hidden="true" /> <!-- with groups -->
     </div>
   </InputContainer>
 </Field>
@@ -103,12 +121,17 @@ PinInput extends the standard field props:
 - The label from Field is associated with the real input through \`for/id\`.
 - The visible cells are \`aria-hidden\`; assistive tech interacts with one text input.
 - The real input uses \`autocomplete="one-time-code"\` by default.
+- Without a label the input is named by the localized "One-time code" catalog message (\`oneTimeCode\`).
+- The cells and the input are \`dir="ltr"\` in every document direction, so a code reads 123456 in right-to-left pages too and the caret agrees with the cells.
+- The component works inside a shadow root: focus and selection are read from the input's own root node.
 - Keyboard navigation, deletion, selection, and paste operate through the native input.
+- Input method (IME) composition, such as Japanese or Chinese input, is left to the input method: the cells show the in-progress text, and the text is checked and committed once when the composition ends. Full-width digits and letters (\`１２３\`) are committed as ASCII (\`123\`). While composing, the real input turns fully transparent (the \`input\` theme slot's \`composing\` variant, \`opacity-0\`), so the input method's underline or clause highlight does not cover the first cells.
 
 ## Notes
 
 - The pattern should accept partial values, not only the final full code. Use \`^\\\\d+$\`, not \`^\\\\d{6}$\`.
-- For pasted codes with spaces or hyphens, pass a \`pasteTransformer\`.
+- Spaces, hyphens and other grouping separators in typed, pasted or autofilled codes are removed by the built-in normalization. Pass a \`pasteTransformer\` only for cleanup specific to your codes.
+- Composed text that the pattern rejects (for example hiragana in a digits-only field) is discarded, and the previous code and selection are restored.
 
 ## State contract