[ @sdxc/ui/behaviors ]

SelectionModel

Selection state for list-shaped widgets.

View as Markdown Open in GitHub Open in ChatGPT Open in Claude

import { SelectionModel } from "@sdxc/ui/behaviors";

Usage

State model for list, grid, tree, and table row selection. Every mutating method dispatches a plain "change" event exactly once, and only when the selected-key set really changes, so a subscriber can re-render blindly.

Signature

new SelectionModel(options?: SelectionModel.Options)

Parameters

Parameter	Type	Description
`options?`	`SelectionModel.Options`	Initial mode, known key order, disabled keys, and pre-selected keys. All are optional and default to an empty, `"multiple"`-mode model with no known keys.

Properties

Property	Type	Description
`mode`	`SelectionModel.Mode`	Current selection cardinality.
`keys`	`readonly SelectionModel.Key[]`	Known selectable keys, in the order last provided to the constructor or setKeys.
`selectedKeys`	`ReadonlySet<SelectionModel.Key>`	Currently selected keys.
`disabledKeys`	`ReadonlySet<SelectionModel.Key>`	Keys excluded from selection.
`anchorKey`	`SelectionModel.Key \| null`	Key that anchors the next selectRange call, or `null` before any point interaction.
`size`	`number`	Number of currently selected keys.
`isEmpty`	`boolean`	`true` when no key is selected.
`isAll`	`boolean`	`true` when every non-disabled key in keys is selected. Always `false` when keys is empty, since there is nothing to select.

Methods

Method	Description
`setMode(mode: SelectionModel.Mode): void`	Replaces the selection mode. The current selection clamps to it (`"none"` empties it, `"single"` keeps at most the first selected key), dispatching `"change"` when that clamp shrinks the selected-key set.
`setKeys(keys: Iterable<SelectionModel.Key>): void`	Replaces the known universe of selectable keys, in order. Selected and anchor keys no longer present in `keys` are dropped, so removing a rendered row also removes it from the selection.
`setDisabledKeys(keys: Iterable<SelectionModel.Key>): void`	Replaces the set of keys excluded from selection. Any of those keys currently selected are dropped from the selection.
`isSelected(key: SelectionModel.Key): boolean`	Reports whether `key` is currently selected.
`isDisabled(key: SelectionModel.Key): boolean`	Reports whether `key` is excluded from selection.
`select(key: SelectionModel.Key): void`	Selects `key`, replacing the selection in `"single"` mode or adding to it in `"multiple"` mode. No-op for a disabled key or in `"none"` mode. Sets anchorKey to `key` on success.
`deselect(key: SelectionModel.Key): void`	Removes `key` from the selection, regardless of mode. Sets anchorKey to `key` when it was selected; no-op otherwise.
`toggle(key: SelectionModel.Key): void`	Flips whether `key` is selected, replacing the selection in `"single"` mode and staying a no-op for a disabled key or in `"none"` mode. Sets anchorKey on success; a plain click maps to this operation.
`selectRange(key: SelectionModel.Key): void`	Selects the contiguous span between anchorKey and `key` in keys order, skipping disabled keys; the anchor stays put so repeated shift-clicks re-span. Anchorless calls run toggle.
`selectAll(): void`	Selects every non-disabled key in keys. No-op outside `"multiple"` mode or when keys is empty.
`clear(): void`	Deselects every key, regardless of mode.

The events, constants and types its module publishes, each imported from @sdxc/ui/behaviors too.

Interface

SelectionModel.Options

Constructor options for SelectionModel.

Member	Type	Description
`mode?`	`Mode`	Selection cardinality; defaults to `"multiple"`.
`keys?`	`Iterable<Key>`	Ordered universe of selectable keys, backing SelectionModel.selectRange spans and the full set for SelectionModel.selectAll. Point selection works without it.
`disabledKeys?`	`Iterable<Key>`	Keys excluded from selection; any of them present in `selectedKeys` are dropped.
`selectedKeys?`	`Iterable<Key>`	Keys selected on construction, clamped to `mode` and `disabledKeys`.

Type

SelectionModel.Key

Identifier for a selectable item. Row/item identity is left to the consumer — a string slug and a numeric row id are both valid keys.

type SelectionModel.Key = string | number