@dorsk/tsumikit 0.53.0 → 0.54.0

package/README.md

@@ -523,6 +523,14 @@ triggers, and `SegmentedControl`. Each renders an exact
 original ghost icon-button default. Use `control` on `Button` or `Popover` when
 the roomier shared `--control-height` composer contract is required.
 
+`Toolbar` implements the keyboard contract its `role="toolbar"` announces: the
+bar is a **single tab stop**, and `←`/`→` (plus `Home`/`End`) move between the
+controls that are actually visible — collapsed `data-overflow` children drop out
+of the ring and the `…` trigger is its last stop. Controls that own the arrow
+keys themselves (text inputs, `select`, sliders) keep them. Pass
+`roving={false}` to opt out; that drops the role along with the promise, leaving
+every child an ordinary tab stop.
+
 Button and Popover share the same semantic tones. For a confirmed positive
 action, `tone="success"` gives neutral controls a success tint; combine it with
 `variant="primary"` for a filled success action without consumer CSS.
@@ -610,7 +618,8 @@ label, copy, line numbers, wrap, scroll) and takes code three ways: plain
   `disabled` and native events pass through.
 - Visible `:focus-visible` rings; ARIA patterns implemented for switch, menu
   (`role=menu` + roving focus), tabs (`tablist` + arrow keys), radiogroup,
-  dialog; polite live region for toasts; `.sr-only`.
+  toolbar (`role=toolbar` + roving tabindex), dialog; polite live region for
+  toasts; `.sr-only`.
 - Mobile-first: one `min-width: 640px` breakpoint, bottom-sheet→centered-modal,
   safe-area insets, 16px-min inputs (no iOS zoom).
 - A verified color-blind-safe theme (Okabe-Ito); meaning never relies on hue

package/dist/components/layouts/Toolbar.svelte

@@ -3,10 +3,22 @@
 	// every child marked `data-overflow` is hidden and a `…` button opens a Menu
 	// with `items` (or the `overflow` snippet in a Popover) that stands in for
 	// them. `sticky` pins the bar under `stickyOffset`.
+	//
+	// `role="toolbar"` is a promise of keyboard behaviour, so the bar keeps it:
+	// roving tabindex makes it one tab stop and ←/→/Home/End move between the
+	// controls actually visible, the `…` trigger included. Children are arbitrary
+	// snippet content, so the ring is read from the DOM rather than a list prop.
 	import type { Snippet } from 'svelte';
 	import IconButton from '../molecules/IconButton.svelte';
 	import Menu, { type MenuItem } from '../molecules/Menu.svelte';
 	import Popover from '../molecules/Popover.svelte';
+	import {
+		consumesArrowKeys,
+		isToolbarNavKey,
+		nextToolbarStop,
+		TOOLBAR_STOP_ATTR,
+		toolbarStops
+	} from './toolbar-roving.js';
 
 	let {
 		children,
@@ -18,6 +30,7 @@
 		density = 'default',
 		overflowLabel = 'More',
 		label,
+		roving = true,
 		class: klass = '',
 		style: styleProp = ''
 	}: {
@@ -34,6 +47,10 @@
 		overflowLabel?: string;
 		/** Accessible name of the bar (`role="toolbar"`). */
 		label?: string;
+		/** Roving tabindex: the bar is one tab stop and ←/→ (plus Home/End) move
+		 *  between its controls. `false` drops `role="toolbar"` along with the
+		 *  keyboard contract it promises, leaving children as ordinary tab stops. */
+		roving?: boolean;
 		class?: string;
 		style?: string;
 	} = $props();
@@ -64,13 +81,77 @@
 	});
 
 	const hasOverflow = $derived(!!items?.length || !!overflow);
+
+	let activeStop: HTMLElement | null = null;
+
+	// Collapsed `data-overflow` children are `display: none`, so they have no box —
+	// that, not a class check, is what takes them out of the ring.
+	const stops = () => toolbarStops(el, (node) => node.getClientRects().length === 0);
+
+	function rove(list: HTMLElement[], index: number) {
+		activeStop = list[index] ?? null;
+		list.forEach((node, i) => {
+			node.setAttribute(TOOLBAR_STOP_ATTR, '');
+			node.tabIndex = i === index ? 0 : -1;
+		});
+	}
+
+	function sync() {
+		const list = stops();
+		if (!list.length) return;
+		const current = activeStop ? list.indexOf(activeStop) : -1;
+		rove(list, current < 0 ? 0 : current);
+	}
+
+	$effect(() => {
+		if (!roving || !el) return;
+		const node = el;
+		sync();
+		// Only attributes the caller owns are observed: writing tabindex and
+		// TOOLBAR_STOP_ATTR back must not re-enter this.
+		const mo = new MutationObserver(sync);
+		mo.observe(node, {
+			childList: true,
+			subtree: true,
+			attributes: true,
+			attributeFilter: ['disabled', 'hidden', 'aria-hidden', 'class', 'style']
+		});
+		return () => mo.disconnect();
+	});
+
+	function onKeydown(event: KeyboardEvent) {
+		if (!roving || event.defaultPrevented) return;
+		if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
+		if (!isToolbarNavKey(event.key)) return;
+		const target = event.target as HTMLElement | null;
+		if (consumesArrowKeys(target)) return;
+		const list = stops();
+		const next = nextToolbarStop(
+			list.length,
+			list.findIndex((node) => node.contains(target)),
+			event.key
+		);
+		if (next === undefined) return;
+		event.preventDefault();
+		rove(list, next);
+		list[next].focus();
+	}
+
+	function onFocusin(event: FocusEvent) {
+		if (!roving) return;
+		const list = stops();
+		const index = list.findIndex((node) => node.contains(event.target as Node));
+		if (index >= 0 && list[index] !== activeStop) rove(list, index);
+	}
 </script>
 
 <div
 	bind:this={el}
 	data-tsu="Toolbar"
-	role="toolbar"
-	aria-label={label}
+	role={roving ? 'toolbar' : undefined}
+	aria-label={roving ? label : undefined}
+	onkeydown={onKeydown}
+	onfocusin={onFocusin}
 	class="toolbar density-{density} {klass}"
 	class:sticky
 	class:collapsed

package/dist/components/layouts/Toolbar.svelte.d.ts

@@ -14,6 +14,10 @@ type $$ComponentProps = {
     overflowLabel?: string;
     /** Accessible name of the bar (`role="toolbar"`). */
     label?: string;
+    /** Roving tabindex: the bar is one tab stop and ←/→ (plus Home/End) move
+     *  between its controls. `false` drops `role="toolbar"` along with the
+     *  keyboard contract it promises, leaving children as ordinary tab stops. */
+    roving?: boolean;
     class?: string;
     style?: string;
 };

package/dist/components/layouts/toolbar-roving.d.ts

@@ -0,0 +1,53 @@
+/** @param {string} key */
+export function isToolbarNavKey(key: string): boolean;
+/**
+ * Controls that own the arrow keys themselves (caret, spinner, native listbox):
+ * the toolbar must not steal them.
+ *
+ * @param {{ tagName?: string; type?: string; isContentEditable?: boolean } | null | undefined} el
+ */
+export function consumesArrowKeys(el: {
+    tagName?: string;
+    type?: string;
+    isContentEditable?: boolean;
+} | null | undefined): boolean;
+/**
+ * @param {{
+ *   disabled?: boolean;
+ *   hidden?: boolean;
+ *   ariaHidden?: boolean;
+ *   inPopover?: boolean;
+ *   tabindex?: string | null;
+ *   claimed?: boolean;
+ * }} el
+ */
+export function acceptsRovingStop(el: {
+    disabled?: boolean;
+    hidden?: boolean;
+    ariaHidden?: boolean;
+    inPopover?: boolean;
+    tabindex?: string | null;
+    claimed?: boolean;
+}): boolean;
+/**
+ * The ring, in DOM order. `isHidden` is injected because "has no box" is the only
+ * honest test for a collapsed child and it cannot be computed without layout.
+ *
+ * @param {Element | null} container
+ * @param {(node: HTMLElement) => boolean} isHidden
+ * @returns {HTMLElement[]}
+ */
+export function toolbarStops(container: Element | null, isHidden: (node: HTMLElement) => boolean): HTMLElement[];
+/**
+ * Arrows wrap; Home/End jump to the ends. `undefined` means "not ours" — the
+ * caller must leave the event alone.
+ *
+ * @param {number} count
+ * @param {number} current
+ * @param {string} key
+ * @returns {number | undefined}
+ */
+export function nextToolbarStop(count: number, current: number, key: string): number | undefined;
+export const TOOLBAR_STOP_SELECTOR: "button, a[href], input, select, textarea, summary, [tabindex]";
+/** Marks a control the toolbar has taken over, so its `-1` reads as ours, not the author's. */
+export const TOOLBAR_STOP_ATTR: "data-toolbar-stop";

package/dist/components/layouts/toolbar-roving.js

@@ -0,0 +1,104 @@
+export const TOOLBAR_STOP_SELECTOR =
+	'button, a[href], input, select, textarea, summary, [tabindex]';
+
+/** Marks a control the toolbar has taken over, so its `-1` reads as ours, not the author's. */
+export const TOOLBAR_STOP_ATTR = 'data-toolbar-stop';
+
+const NAV_KEYS = new Set(['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End']);
+
+const ARROW_CONSUMING_INPUTS = new Set([
+	'text',
+	'search',
+	'email',
+	'url',
+	'tel',
+	'password',
+	'number',
+	'date',
+	'datetime-local',
+	'month',
+	'week',
+	'time',
+	'range',
+]);
+
+/** @param {string} key */
+export function isToolbarNavKey(key) {
+	return NAV_KEYS.has(key);
+}
+
+/**
+ * Controls that own the arrow keys themselves (caret, spinner, native listbox):
+ * the toolbar must not steal them.
+ *
+ * @param {{ tagName?: string; type?: string; isContentEditable?: boolean } | null | undefined} el
+ */
+export function consumesArrowKeys(el) {
+	if (!el) return false;
+	if (el.isContentEditable) return true;
+	const tag = (el.tagName ?? '').toLowerCase();
+	if (tag === 'textarea' || tag === 'select') return true;
+	if (tag !== 'input') return false;
+	return ARROW_CONSUMING_INPUTS.has((el.type ?? 'text').toLowerCase());
+}
+
+/**
+ * @param {{
+ *   disabled?: boolean;
+ *   hidden?: boolean;
+ *   ariaHidden?: boolean;
+ *   inPopover?: boolean;
+ *   tabindex?: string | null;
+ *   claimed?: boolean;
+ * }} el
+ */
+export function acceptsRovingStop(el) {
+	if (el.disabled || el.hidden || el.ariaHidden || el.inPopover) return false;
+	return el.claimed === true || el.tabindex !== '-1';
+}
+
+/**
+ * The ring, in DOM order. `isHidden` is injected because "has no box" is the only
+ * honest test for a collapsed child and it cannot be computed without layout.
+ *
+ * @param {Element | null} container
+ * @param {(node: HTMLElement) => boolean} isHidden
+ * @returns {HTMLElement[]}
+ */
+export function toolbarStops(container, isHidden) {
+	if (!container) return [];
+	return [
+		.../** @type {NodeListOf<HTMLElement>} */ (container.querySelectorAll(TOOLBAR_STOP_SELECTOR)),
+	].filter((node) =>
+		acceptsRovingStop({
+			disabled: /** @type {HTMLButtonElement} */ (node).disabled,
+			hidden: node.hidden || isHidden(node),
+			ariaHidden: node.getAttribute('aria-hidden') === 'true',
+			inPopover: node.closest('[popover]') !== null,
+			tabindex: node.getAttribute('tabindex'),
+			claimed: node.hasAttribute(TOOLBAR_STOP_ATTR),
+		}),
+	);
+}
+
+/**
+ * Arrows wrap; Home/End jump to the ends. `undefined` means "not ours" — the
+ * caller must leave the event alone.
+ *
+ * @param {number} count
+ * @param {number} current
+ * @param {string} key
+ * @returns {number | undefined}
+ */
+export function nextToolbarStop(count, current, key) {
+	if (count <= 0 || current < 0 || current >= count) return undefined;
+	if (key === 'Home') return 0;
+	if (key === 'End') return count - 1;
+
+	let direction;
+	if (key === 'ArrowRight' || key === 'ArrowDown') direction = 1;
+	else if (key === 'ArrowLeft' || key === 'ArrowUp') direction = -1;
+	else return undefined;
+
+	return (((current + direction) % count) + count) % count;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dorsk/tsumikit",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "Minimal, dependency-free Svelte 5 + pure-CSS UI kit. Token-driven atoms, molecules & layouts with theming out of the box.",
   "type": "module",
   "license": "MIT",
@@ -73,6 +73,7 @@
     "@sveltejs/kit": "^2.22.0",
     "@sveltejs/package": "^2.3.0",
     "@sveltejs/vite-plugin-svelte": "^6.0.0",
+    "@types/jsdom": "^30.0.0",
     "@types/node": "^25.9.3",
     "esbuild": "^0.28.2",
     "esbuild-svelte": "^0.9.5",