sveltelean
Version v0.18.0

The four tiers

TierNameBudget (ADR 0003)Meaning
0NativeNo runtime JavaScript, no instance listeners, no instance state objectsThe browser owns the behavior.
1Delegated micro-behaviorOne shared listener per required event type; no per-root listener; state in the DOMRegistered once per page; no controller per instance.
2Lazy scoped controllerWeakMap state created on first interaction; AbortController-scoped listeners; cleanupPer-instance state only once the instance is used.
3Application-controlledSvelte state owned by the application; never required by a default primitiveThe application owns the state, e.g. a sort in the URL.

Two questions, in order, decide the tier; two "no" answers mean a scoped controller.

How a primitive is assigned its runtime tierCan the browser do it? Yes: native, Tier 0, no Svelte Lean JavaScript. No: is one shared listener per event type enough? Yes: shared behavior, Tier 1. No: lazy scoped controller, Tier 2, with state created on first interaction.Can the browser do it?yesnoNative · Tier 0no Svelte Lean JavaScriptIs one shared listener perevent type enough?yesnoShared behavior · Tier 1one listener per event typeTier 2lazy scopedcontroller How a primitive is assigned its runtime tierCan the browser do it? Yes: native, Tier 0, no Svelte Lean JavaScript. No: is one shared listener per event type enough? Yes: shared behavior, Tier 1. No: lazy scoped controller, Tier 2, with state created on first interaction.Can the browser do it?yesnoNative · Tier 0no Svelte Lean JavaScriptIs one shared listener perevent type enough?yesnoShared behavior · Tier 1one listener per event typeLazy scoped controller · Tier 2state created on first interaction
Native before JavaScript. Every primitive declares its tier in its contract.

Tier 3 is not a primitive tier: it is how Svelte Lean Table works, one plain state object the application can bind, serialize and restore.

members.svelte
<script lang="ts">
	import { DataTable, type TableState } from '@svelte-lean/table';

	// Tier 3: the application owns the state and stores it wherever it wants.
	let state = $state<Partial<TableState>>({ sorting: [{ id: 'revenue', desc: true }] });
</script>

<DataTable {data} {columns} getRowId={(row) => row.id} bind:state />

Declaring a tier

The tier is a field of each primitive's contract constant; contract.md states and justifies it in its first line.

contract.ts
// packages/primitives/src/tabs/contract.ts: the static description of the protocol
export const tabsContract = {
	name: 'tabs',
	tier: 1,
	base: 'ARIA tabs markup (role=tablist, tab, tabpanel)',
	parts: ['list', 'trigger', 'panel', 'native'],
	options: {
		value: {},
		activation: { values: ['automatic', 'manual'], default: 'automatic' },
		orientation: { values: ['horizontal', 'vertical'], default: 'horizontal' },
		loop: { values: ['true', 'false'], default: 'true' },
		render: { values: ['app'] }
	},
	events: ['click', 'keydown'],
	emits: ['slean:change']
} as const satisfies BehaviorContract;

The root entry exposes the metadata and registers nothing; every tier on this site is read from it.

TypeScript
import { BEHAVIORS } from '@svelte-lean/primitives';

BEHAVIORS.dialog.tier; // 0
BEHAVIORS.dialog.module; // null: nothing to register
BEHAVIORS.tabs.tier; // 1
BEHAVIORS.tabs.events; // ['click', 'keydown']
BEHAVIORS.tabs.module; // '@svelte-lean/primitives/tabs/register'

Classification

PrimitiveTierNative baseShared listenersRegistration moduleBehavior JS (brotli)
accordion0<details> + <summary>, exclusive groups through namenonenone0 B
alert0<div> + live region roles (status, alert)nonenone0 B
avatar0<img> with initials behind itnonenone0 B
badge0<span> with an optional remove <button>nonenone0 B
breadcrumb0<nav> + <ol> + aria-current="page"nonenone0 B
button0<button type="button">nonenone0 B
button-group0buttons in role="group"nonenone0 B
card0<article>nonenone0 B
carousel0scroll-snap, ::scroll-button(), ::scroll-markernonenone0 B
checkbox0<input type="checkbox">, role="switch"nonenone0 B
descriptions0<dl> with <div> groups of <dt> and <dd>nonenone0 B
dialog0<dialog> + command/commandfornonenone0 B
empty0a heading, a paragraph and an optional actionnonenone0 B
field0<label for>, a control, aria-describedby; constraint validationnonenone0 B
kbd0<kbd>nonenone0 B
meter0<meter min max low high optimum value>nonenone0 B
nav0<nav> + <ul> of links + <details name> groups + aria-current="page"nonenone0 B
pagination0<nav> + links + aria-current="page"nonenone0 B
popover0[popover] + popovertarget or command/commandfornonenone0 B
progress0<progress value max>nonenone0 B
radio-group0<fieldset> + <input type="radio" name="…">nonenone0 B
rating0<fieldset> of <input type="radio"> sharing a namenonenone0 B
scroll-area0overflow: auto + tabindex="0" in role="region"nonenone0 B
separator0<hr>, role="separator"nonenone0 B
skeleton0aria-hidden placeholders in an aria-busy regionnonenone0 B
steps0<ol> + aria-current="step"nonenone0 B
timeline0<ol> of <li> events with <time datetime>nonenone0 B
calendar1role=grid of day buttons in a <table>click, keydown, change, reset, pointerover, pointerout@svelte-lean/primitives/calendar/register4594 B
checkbox-group1<fieldset> + <input type="checkbox">, indeterminatechange, focusin, reset@svelte-lean/primitives/checkbox-group/register1456 B
copy1navigator.clipboard.writeText + <button>click@svelte-lean/primitives/copy/register1291 B
file-drop1<input type="file"> stretched over a drop area; DataTransfer for the file listdragenter, dragleave, drop, paste, input, change, click, reset@svelte-lean/primitives/file-drop/register2983 B
findable1hidden="until-found" + beforematchbeforematch@svelte-lean/primitives/findable/register1887 B
hint1role="tooltip" + popover="manual" + aria-describedbypointerover, pointerout, pointerdown, focusin, focusout, keydown@svelte-lean/primitives/hint/register2687 B
hover-card1popover="hint" named by interestforpointerover, pointerout, focusin, focusout, keydown@svelte-lean/primitives/hover-card/register1985 B
input1<input> of any type, <textarea>; stepUp()/stepDown(), type="password"↔"text"click, pointerdown, pointerover, focusin@svelte-lean/primitives/input/register1808 B
listbox1ARIA listbox markup (role=listbox, option)click, keydown, change, reset@svelte-lean/primitives/listbox/register2357 B
menu1[popover] + ARIA menu (role=menu, menuitem)click, keydown, beforetoggle, toggle@svelte-lean/primitives/menu/register2771 B
menubar1role="menubar" of popovertarget menu buttonskeydown, focusin, pointerover@svelte-lean/primitives/menubar/register2063 B
slider1<input type="range">, one or two in a groupinput, reset@svelte-lean/primitives/slider/register1549 B
tabs1ARIA tabs markup (role=tablist, tab, tabpanel)click, keydown@svelte-lean/primitives/tabs/register1839 B
toggle1<button type="button" aria-pressed>click@svelte-lean/primitives/toggle-group/registernot measured
toggle-group1<button aria-pressed> items in role="group"click, keydown@svelte-lean/primitives/toggle-group/register1932 B
toolbar1role="toolbar"keydown, focusin@svelte-lean/primitives/toolbar/register1706 B
tree1role="tree", treeitem, group, aria-expandedclick, keydown@svelte-lean/primitives/tree/register2140 B
autocomplete2<input list> + <datalist>; owned: role=combobox input + [popover] + ARIA listboxclick, keydown, input, pointerdown, pointerover, focusin, focusout, toggle@svelte-lean/primitives/autocomplete/register3960 B
date-picker2<input type="date"> + role=combobox text input + [popover] + calendarclick, keydown, input, change, pointerdown, pointerover, focusin, focusout, toggle, reset@svelte-lean/primitives/date-picker/register9476 B
select2<select> + role=combobox trigger + [popover] + ARIA listbox (role=listbox, option)click, keydown, input, pointerdown, pointerover, focusout, change, toggle, reset, animationstart@svelte-lean/primitives/select/register5020 B
sortable2<ul>/<ol> + <button> handles; document order is the valuepointerdown, keydown, click@svelte-lean/primitives/sortable/register3833 B
splitter2role="separator" (WAI-ARIA window splitter) + CSS gridkeydown, pointerdown@svelte-lean/primitives/splitter/register1908 B
toast2popover="manual" region + aria-live listclick, pointerover, pointerout, focusin, focusout@svelte-lean/primitives/toast/register1616 B
Svelte Lean Table3<table>nonenone (a Svelte component)measured per entry point
  • Tier 0: the Svelte Lean chunk of the native-only production fixture.
  • Tier 1 and 2: the register module built with Vite in production mode, shared kernel included (method).
  • Each tier was decided, with the reason, in docs/catalog.md before the contract.

Targets and measurements

ADR 0003 initial targets next to the CI budget and the measured value; the status is computed.

SubjectTarget (ADR 0003)Enforced budgetMeasuredStatus
Tabs registration including the shared kernelTabs < 1 kB brotli1900 B brotli1839 B brotliabove target
Basic menu registration including the shared kernelbasic Menu ~1–2 kB2800 B brotli2771 B brotliabove target
Every behavior that exists today, on one page, with one kernelentire common behavior set < 5 kB—4600 B brotliwithin target
  • The enforced number is the budget in the size file, ten to fifteen percent above the measured value, so a regression fails CI. The ADR figure is an intent, not a claim.
  • Values come from packages/primitives/artifacts/size.json and fixtures/results.json.

Where state lives

First match wins:

  1. Browser-owned (checked, disabled, open, focus, validity, popover open): the browser state.
  2. DOM or ARIA representation (aria-selected, tabindex, hidden): the DOM (Tier 1).
  3. Ephemeral (typeahead buffer, pointer origin, open session): a lazy WeakMap entry. Menu and listbox share one typeahead buffer per page; the select and the autocomplete keep one entry per used root and delete it when focus leaves.
  4. Application state: Svelte and the application (Tier 3).

Example

Tier 1: these tabs and the frame's source tabs share one click and one keydown listener on the document.

Tabs · Tier 1
Account settings.
Code
<script lang="ts">
	// With @svelte-lean/vite the register import is injected for the static
	// data-slean="tabs" marker. Without the plugin, write it yourself once:
	// import '@svelte-lean/primitives/tabs/register';
	import '@svelte-lean/styles/tabs.css';
	import { tabsParts } from '@svelte-lean/primitives/tabs';

	// Roles, ids, aria-controls, aria-labelledby, selection and the tab stop.
	const t = tabsParts('settings');
</script>

<div id="settings" data-slean="tabs" data-slean-value="account">
	<div {...t.list} aria-label="Settings">
		<button {...t.tab('account', 'account')}>Account</button>
		<button {...t.tab('security', 'account')}>Security</button>
	</div>
	<div {...t.panel('account', 'account')} tabindex="0">Account settings.</div>
	<div {...t.panel('security', 'account')} tabindex="0">Security settings.</div>
</div>
Arrow keys, Home and End move between triggers; state is written to aria-selected, tabindex and hidden.

Tier 2: the autocomplete gets a WeakMap entry on first use and a scoped pointerdown listener while open; both go when it closes and focus leaves.

Autocomplete · Tier 2
Code
<script lang="ts">
	// With @svelte-lean/vite the register import is injected for the static
	// data-slean="autocomplete" marker.
	import '@svelte-lean/styles/control.css';
	import '@svelte-lean/styles/autocomplete.css';
	import { autocompleteParts } from '@svelte-lean/primitives/autocomplete';

	const p = autocompleteParts('city');
</script>

<label {...p.label}>City</label>
<div id="city" data-slean="autocomplete">
	<input {...p.input} name="city" placeholder="Select a city" />
	<datalist {...p.datalist}>
		<option value="Ankara"></option>
		<option value="Berlin"></option>
		<option value="Cairo" disabled></option>
		<option value="Lisbon"></option>
		<option value="Oslo"></option>
	</datalist>
</div>
Focus, type or press ArrowDown: the controller is created then, the popup is created from the datalist, and both are released when focus leaves.

The live reading of this page; the proof page repeats it with 1, 100 and 1000 roots.

Runtime
Read from the page after it loads; requires JavaScript.

Source