useLocale API

Controls mandatory selection behavior: - `false` (default): No mandatory selection enforcement - `true`: Prevents deselecting the last selected item - `'force'`: Automatically selects the first non-disabled item on registration

adapter

LocaleAdapter | undefined

default

ID | undefined

fallback

ID | undefined

messages

Record<ID, Z> | undefined

Properties

collection

ReadonlyMap<ID, E>

The collection of tickets in the registry

size

number

The number of tickets in the registry

selectedIds

Reactive<Set<ID>>

Set of currently selected ticket IDs

selectedItems

ComputedRef<Set<E>>

Computed Set of selected ticket instances

selectedValues

ComputedRef<Set<E["value"] extends Ref<infer U, infer U> ? U : E["value"]>>

Computed Set of selected ticket values

disabled

MaybeRefOrGetter<boolean>

Disabled state for the entire model instance

multiple

MaybeRefOrGetter<boolean>

Whether the selection allows multiple selections

selectedId

Readonly<Ref<ID | undefined, ID | undefined>>

selectedIndex

Readonly<Ref<number, number>>

selectedItem

Readonly<Ref<E | undefined, E | undefined>>

selectedValue

Readonly<Ref<E["value"] | undefined, E["value"] | undefined>>

Methods

clear

() => void

Clear the entire registry

has

(id: ID) => boolean

Check if a ticket exists by ID

keys

() => readonly ID[]

Get all registered IDs

browse

(value: E["value"]) => readonly ID[] | undefined

Browse for an ID(s) by value

lookup

(index: number) => ID | undefined

Lookup a ticket by index number

get

(id: ID) => E | undefined

Get a ticket by ID

upsert

(id: ID, ticket?: Partial<Z>, event?: string) => E

Update or insert a ticket by ID

values

() => readonly E[]

Get all values of registered tickets

entries

() => readonly [ID, E][]

Get all entries of registered tickets

unregister

(id: ID) => void

Unregister a ticket by ID

reindex

() => void

Reset the index directory and update all tickets

move

(id: ID, toIndex: number) => E | undefined

Move a ticket to a new index position

reorder

(ids: ID[]) => void

Reorder the registry to match a canonical permutation of ids in one pass.

seek

(direction?: "first" | "last", from?: number, predicate?: (ticket) => boolean) => E | undefined

Seek for a ticket based on direction and optional predicate

on

<K extends Extensible<RegistryEventName>>(event: K, cb: RegistryEventCallback<E, K>) => void

Listen for registry events

off

<K extends Extensible<RegistryEventName>>(event: K, cb: RegistryEventCallback<E, K>) => void

Stop listening for registry events

emit

<K extends Extensible<RegistryEventName>>(event: K, data: EventPayload<E, K>) => void

Emit an event with data

dispose

() => void

Clears the registry and removes all listeners

offboard

(ids: ID[]) => Partial<Z>[]

Offboard multiple tickets at once, returning the input shapes that were removed.

batch

<R>(fn: () => R) => R

Execute operations in a batch, deferring cache invalidation and event emission until complete

reset

() => void

Reset selection state without destroying the registry

select

(id: ID) => void

Select a ticket by ID

unselect

(id: ID) => void

Unselect a ticket by ID

toggle

(id: ID) => void

Toggle a ticket's selection state

selected

(id: ID) => boolean

Check if a ticket is currently selected

apply

(values: unknown[], options?: { multiple?) => void

Apply external values to the model

mandate

() => void

Mandate selected ID based on "mandatory" option

onboard

(registrations: Partial<Z>[]) => E[]

Onboard multiple tickets at once

t

(key: string, ...params: unknown[]) => string

Translate a message key with optional parameters.

ti

(key: string, ...params: unknown[]) => string | undefined

Translate a message key only if it exists, otherwise return `undefined`. Unlike {@link t}, `ti` ("translate if exists") never echoes the raw key on a miss. This lets components supply their own inline English default with the nullish-coalescing operator instead of relying on bundled fallback messages.

n

(value: number) => string

register

(registration?: Partial<Z>) => E

Register a locale with optional messages. When `messages` is provided, flattens them to dot-notation tokens and onboards them into the token registry before registering the locale for selection.