@joewinke/jatui 0.38.6 → 0.39.0

package/dist/selection/clickSelection.js

@@ -0,0 +1,152 @@
+/**
+ * Pointer-first multi-selection: the desktop-standard click rules, as pure
+ * functions over a plain `Set` (a `SvelteSet` is a `Set`, so the reactive
+ * controller in `createClickSelection.svelte.ts` runs exactly this code).
+ *
+ *   click            select only this one; it becomes the anchor
+ *   Ctrl/⌘ click     toggle this one; it becomes the anchor
+ *   Shift click      select the range anchor..this, in the current id order
+ *                    (replaces the selection; the anchor stays put)
+ *   Shift Ctrl/⌘     add the range anchor..this to the selection
+ *   Shift arrows     extend from the anchor (the caller says which id an
+ *                    arrow lands on, because only it knows the layout)
+ *   Ctrl/⌘ A         select every id
+ *   Esc              clear
+ *
+ * The selection is a set of ids, not of positions: re-sorting, filtering or
+ * live inserts keep it, and an id that is no longer in `ids` is simply not
+ * selected any more (`prune` drops it, the readers filter it out first).
+ *
+ * `head` is the moving end of the last range (the last id clicked or
+ * extended to), so Shift+arrows keep growing from where they left off.
+ *
+ * No DOM, no Svelte: unit-tested in tests/unit/clickSelection.test.ts.
+ */
+import { isTypingTarget } from '../utils/keyboardShortcutRegistry';
+/** Ctrl on Linux/Windows, ⌘ on macOS: either counts as "toggle / add". */
+export const isAdditive = (m) => !!(m.ctrlKey || m.metaKey);
+/** The ids from `a` to `b` inclusive, in `ids` order (either direction). Empty when either is missing. */
+export function rangeBetween(ids, a, b) {
+    const i = ids.indexOf(a);
+    const j = ids.indexOf(b);
+    if (i < 0 || j < 0)
+        return [];
+    return i <= j ? ids.slice(i, j + 1) : ids.slice(j, i + 1);
+}
+/** Select only `id` and make it the anchor (a plain click, or a plain arrow move). */
+export function selectOnly(s, id) {
+    s.selected.clear();
+    s.selected.add(id);
+    s.anchor = id;
+    s.head = id;
+}
+/** Toggle `id` and make it the anchor (Ctrl/⌘ click). */
+export function toggleOne(s, id) {
+    if (s.selected.has(id))
+        s.selected.delete(id);
+    else
+        s.selected.add(id);
+    s.anchor = id;
+    s.head = id;
+}
+/**
+ * Select the range from the anchor to `id` (Shift click / Shift arrows).
+ * `additive` keeps what was selected and adds the range (Shift+Ctrl/⌘).
+ * With no usable anchor (none yet, or it vanished) it behaves as a plain
+ * click on `id` (or a toggle-on when additive).
+ */
+export function extendTo(s, ids, id, additive = false) {
+    if (!ids.includes(id))
+        return;
+    const anchor = s.anchor !== null && ids.includes(s.anchor) ? s.anchor : null;
+    if (anchor === null) {
+        if (additive) {
+            s.selected.add(id);
+            s.anchor = id;
+            s.head = id;
+        }
+        else
+            selectOnly(s, id);
+        return;
+    }
+    const range = rangeBetween(ids, anchor, id);
+    if (!additive)
+        s.selected.clear();
+    for (const x of range)
+        s.selected.add(x);
+    s.head = id;
+}
+/** Apply one click on `id` with its modifiers. Ids not in `ids` are ignored. */
+export function applyClick(s, ids, id, m = {}) {
+    if (!ids.includes(id))
+        return;
+    prune(s, ids);
+    if (m.shiftKey)
+        return extendTo(s, ids, id, isAdditive(m));
+    if (isAdditive(m))
+        return toggleOne(s, id);
+    selectOnly(s, id);
+}
+/** Select every id (Ctrl/⌘ A). The anchor stays if it is still there, else the first id. */
+export function selectAll(s, ids) {
+    s.selected.clear();
+    for (const x of ids)
+        s.selected.add(x);
+    if (s.anchor === null || !ids.includes(s.anchor))
+        s.anchor = ids[0] ?? null;
+    s.head = ids.at(-1) ?? null;
+}
+/** Clear the selection and the range ends (Esc). */
+export function clearSelection(s) {
+    s.selected.clear();
+    s.anchor = null;
+    s.head = null;
+}
+/** Drop selected ids that are no longer in `ids` (and an anchor or head that vanished). True when anything changed. */
+export function prune(s, ids) {
+    const present = new Set(ids);
+    let changed = false;
+    for (const x of [...s.selected]) {
+        if (!present.has(x)) {
+            s.selected.delete(x);
+            changed = true;
+        }
+    }
+    if (s.anchor !== null && !present.has(s.anchor)) {
+        s.anchor = null;
+        changed = true;
+    }
+    if (s.head !== null && !present.has(s.head)) {
+        s.head = null;
+        changed = true;
+    }
+    return changed;
+}
+/** The selected ids that are still present, in `ids` order (what a range or a list shows). */
+export const inOrder = (selected, ids) => ids.filter((x) => selected.has(x));
+/** The selected ids that are still present, in the order they were selected (Set insertion order). */
+export function inPickOrder(selected, ids) {
+    const present = new Set(ids);
+    return [...selected].filter((x) => present.has(x));
+}
+export const ARROW_KEYS = ['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'];
+/**
+ * Which selection key this is, if any: Ctrl/⌘ A (select all), Esc (clear,
+ * only while something is selected, so Esc keeps its other meanings when
+ * nothing is), Shift+arrows (extend; with Ctrl/⌘ too, add the range).
+ * Never while typing in a field, never with Alt, never when already handled.
+ */
+export function selectionKey(e, hasSelection) {
+    if (e.defaultPrevented || e.altKey)
+        return null;
+    if (isTypingTarget(e.target ?? null))
+        return null;
+    const mod = isAdditive(e);
+    if (mod && !e.shiftKey && (e.key === 'a' || e.key === 'A'))
+        return { kind: 'selectAll' };
+    if (e.key === 'Escape' && !mod && !e.shiftKey)
+        return hasSelection ? { kind: 'clear' } : null;
+    if (e.shiftKey && ARROW_KEYS.includes(e.key))
+        return { kind: 'extend', key: e.key, additive: mod };
+    return null;
+}

package/dist/selection/createClickSelection.d.ts

@@ -0,0 +1,79 @@
+/**
+ * createClickSelection: a reactive multi-selection for grids and lists that are
+ * used with the mouse (Shift-click ranges, Ctrl/⌘-click toggles) and the
+ * keyboard (Shift+arrows, Ctrl/⌘ A, Esc). The rules live in `clickSelection.ts`
+ * (pure, unit-tested); this wraps them in a `SvelteSet` plus `$state` ends so a
+ * component re-renders when the selection changes.
+ *
+ * Usage:
+ *
+ *     const sel = createClickSelection({ ids: () => items.map((i) => i.id) });
+ *
+ *     {#each items as item (item.id)}
+ *       <button class:selected={sel.has(item.id)} onclick={(e) => sel.click(item.id, e)}>…</button>
+ *     {/each}
+ *
+ *     <svelte:window onkeydown={(e) => sel.handleKeydown(e, { next: (from, key) => neighbour(from, key) })} />
+ *
+ *     <BulkActionBar selection={sel.ordered} actions={…} onClear={() => sel.clear()} />
+ *
+ * `ids()` is read on every call, in display order, so ranges always follow
+ * what is on screen; ids that left it are never reported (`ordered`,
+ * `picked`, `count`) and are dropped from the set on the next change.
+ *
+ * With listNav: listNav is the keyboard-only list motion (j/k, vim counts) and
+ * has its own opt-in selection (x, V, Shift+J/K). Give a surface ONE selection
+ * owner. A pointer-first grid uses clickSelection; a keyboard-first list uses
+ * listNav's. To have both, run listNav with `selectable: false` for focus
+ * motion and let clickSelection own the set: call `sel.click(id, e)` from the
+ * click handler and `sel.extendTo(id)` from your own Shift+J/K.
+ */
+import { SvelteSet } from 'svelte/reactivity';
+import { type ArrowKey, type SelectionKeyEvent, type SelectionModifiers } from './clickSelection';
+export interface ClickSelectionOptions<Id = string> {
+    /** Every selectable id, in the order shown. Read lazily on each call. */
+    ids: () => readonly Id[];
+    /** Called after every change, with the selection in display order. */
+    onChange?: (ordered: Id[]) => void;
+}
+export interface ClickSelectionKeyOptions<Id = string> {
+    /**
+     * Where an arrow lands from `from` (null: the selection has no moving end
+     * yet). Return null to do nothing (an edge). Only the caller knows the
+     * layout (a grid's row above, a list's next item), so it decides.
+     */
+    next?: (from: Id | null, key: ArrowKey) => Id | null;
+}
+export interface ClickSelection<Id = string> {
+    /** The raw set (may briefly hold an id that just left `ids`; prefer `ordered`). */
+    readonly selected: SvelteSet<Id>;
+    /** The fixed end of a range: the last plain or Ctrl/⌘ click. */
+    readonly anchor: Id | null;
+    /** The moving end: the last id clicked or extended to. */
+    readonly head: Id | null;
+    /** Selected and still present, in display order. */
+    readonly ordered: Id[];
+    /** Selected and still present, in the order they were picked. */
+    readonly picked: Id[];
+    /** How many are selected and present. */
+    readonly count: number;
+    has(id: Id): boolean;
+    /** Apply a click with its modifiers (MouseEvent works as is). */
+    click(id: Id, mods?: SelectionModifiers): void;
+    /** Select only this one (a plain click or a plain arrow move). */
+    only(id: Id): void;
+    /** Toggle one (Ctrl/⌘ click, or an "x" key). */
+    toggle(id: Id): void;
+    /** Range from the anchor to `id`; `additive` keeps the rest. */
+    extendTo(id: Id, additive?: boolean): void;
+    selectAll(): void;
+    clear(): void;
+    /** Drop ids no longer in `ids()`. Every other method does this first. */
+    prune(): void;
+    /**
+     * Ctrl/⌘ A, Esc (while something is selected) and Shift+arrows (with
+     * `next`). Returns true and prevents the default when it handled the key.
+     */
+    handleKeydown(e: KeyboardEvent | SelectionKeyEvent, opts?: ClickSelectionKeyOptions<Id>): boolean;
+}
+export declare function createClickSelection<Id = string>(options: ClickSelectionOptions<Id>): ClickSelection<Id>;

package/dist/selection/createClickSelection.js

@@ -0,0 +1,134 @@
+/* createClickSelection.svelte.js generated by Svelte v5.53.11 */
+import * as $ from 'svelte/internal/client';
+import { SvelteSet } from 'svelte/reactivity';
+
+import {
+	applyClick,
+	clearSelection,
+	extendTo,
+	inOrder,
+	inPickOrder,
+	prune,
+	selectAll,
+	selectionKey,
+	selectOnly,
+	toggleOne
+} from './clickSelection';
+
+export function createClickSelection(options) {
+	const selected = new SvelteSet();
+	let anchor = $.state(null);
+	let head = $.state(null);
+
+	const state = {
+		selected,
+		get anchor() {
+			return $.get(anchor);
+		},
+
+		set anchor(v) {
+			$.set(anchor, v, true);
+		},
+
+		get head() {
+			return $.get(head);
+		},
+
+		set head(v) {
+			$.set(head, v, true);
+		}
+	};
+
+	const ids = () => options.ids();
+	const changed = () => options.onChange?.(inOrder(selected, ids()));
+
+	return {
+		selected,
+		get anchor() {
+			return $.get(anchor);
+		},
+
+		get head() {
+			return $.get(head);
+		},
+
+		get ordered() {
+			return inOrder(selected, ids());
+		},
+
+		get picked() {
+			return inPickOrder(selected, ids());
+		},
+
+		get count() {
+			return inOrder(selected, ids()).length;
+		},
+		has: (id) => selected.has(id) && ids().includes(id),
+		click(id, mods = {}) {
+			applyClick(state, ids(), id, mods);
+			changed();
+		},
+
+		only(id) {
+			prune(state, ids());
+			selectOnly(state, id);
+			changed();
+		},
+
+		toggle(id) {
+			prune(state, ids());
+			toggleOne(state, id);
+			changed();
+		},
+
+		extendTo(id, additive = false) {
+			const all = ids();
+
+			prune(state, all);
+			extendTo(state, all, id, additive);
+			changed();
+		},
+
+		selectAll() {
+			selectAll(state, ids());
+			changed();
+		},
+
+		clear() {
+			clearSelection(state);
+			changed();
+		},
+
+		prune() {
+			if (prune(state, ids())) changed();
+		},
+
+		handleKeydown(e, opts = {}) {
+			const all = ids();
+			const action = selectionKey(e, inOrder(selected, all).length > 0);
+
+			if (!action) return false;
+
+			if (action.kind === 'extend') {
+				if (!opts.next) return false;
+
+				prune(state, all);
+
+				const to = opts.next($.get(head) ?? $.get(anchor), action.key);
+
+				if (to === null || to === undefined) {
+					e.preventDefault?.();
+
+					return true;
+				}
+
+				extendTo(state, all, to, action.additive);
+			} else if (action.kind === 'selectAll') selectAll(state, all); else clearSelection(state);
+
+			e.preventDefault?.();
+			changed();
+
+			return true;
+		}
+	};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.38.6",
+  "version": "0.39.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",
@@ -84,7 +84,8 @@
     "dist",
     "CLAUDE.md",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "scripts": {
     "dev": "npm run package && vite dev --port 5180",