Core theory

@sectile/core does not render UI. It represents item relationships and interaction state as values, then computes the next state and ordered commands from the current state and a semantic event.

A command requests an effect such as focus or scrolling; it does not perform that effect. DOM, terminal, and Vue interpret commands in their own environments, so the Core calculation remains host-independent and directly testable.

Core calculates results without running effectsGive a pure transition the current state and a semantic event; it returns the next state and commands for a host to interpret.

Values read by the transition

Model

Item relationships and valid valuesSequence · Range · Grid · Tree

Current state

Facts remembered by the interactionCursor · Selection · Expansion · Text

Semantic event

The change the user intendsMove · Select · Expand · Edit

Policies

Eligibility and boundary behaviorEligibility · Boundary · Activation

applyEventDeterministic transitionsame input · same result · no external effects

Values returned by the transition

Next stateA new immutable snapshot

Ordered commandsfocus · scroll · announce · activate

Typed failureA failure preserves the old state and empty commands

One input trace

current = item:2+event = move-nextcurrent = item:3+focus(item:3)

Core boundaryCommands are data. A host executes them and sends the next semantic event back to Core.@sectile/dom · @sectile/terminal · @sectile/vue

Models define item relationships and valid values. State records facts such as cursor, selection, expansion, and text. Events express user intent, while policies make product choices such as eligibility and boundary behavior explicit.

A successful transition returns a new immutable state and its commands together. A failed transition returns a typed error without changing the old state or command list.

Canonical vocabulary

Core uses sequence, range, grid, and tree as its canonical item relationships. It composes them with independent cursor, selection, expansion, and text state. Because each model owns one fact, a component policy can explicitly decide whether moving the cursor preserves selection or moves it too.

Components combine those ingredients through a deterministic transition. Date and calendar arithmetic belongs to @sectile/temporal, tabular data interaction to @sectile/tabular, and viewport layout to @sectile/virtual.

Reading a public specification

A Core specification is more than a list of API names. It defines valid values, available operations and observable results together with the laws, failures, and resource bounds an implementation must preserve.

A public contract answers six questionsTwo implementations are observably equivalent when these six answers remain the same.

Surface available to consumers

ValuesWhich values are valid?

Defines state and model shapes, identity, and allowed ranges.

OperationsWhat can be done?

Defines construction, queries, and event-driven transitions.

ObservationsWhat can a consumer observe?

Names verifiable state, commands, and query results.

Boundaries the implementation must keep

LawsWhat must always remain true?

States the invariants for every valid value and transition.

FailuresWhat can fail, and why?

Keeps invalid input distinct from an ordinary absent result.

CostsHow much resource may it use?

Makes time, memory, and input ceilings part of the contract.

Two implementations are observably equivalent when the same public input trace produces the same state, commands, query results, and failures while preserving every law and cost ceiling.

Composition is the primitive

A listbox combines a sequence with cursor and selection. A combobox adds text and popup state. A tree grid combines tree and grid relationships with expansion, cursor, selection, and editing state. See Composition for how each component owns facts and updates them atomically.