@weasel-js/headless 0.0.0-stage → 1.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 orochi235
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @weasel-js/headless
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Component behavior with no substrate: what a DOM component and a canvas-drawn widget both run,
+each drawing it its own way. Today that is a list's roving highlight and typeahead, and keyboard
+focus as one contract. No React, no DOM.
+
+Part of [weasel](https://github.com/orochi235/weasel), a domain-agnostic 2D
+scene-graph canvas kit for React. See the
+[API reference](https://orochi235.github.io/weasel/#pkg/headless).
+
+## Install
+
+```sh
+npm install @weasel-js/headless
+```
+
+## Usage
+
+```ts
+import { EMPTY_TYPEAHEAD, rovingKey, typeaheadStep } from '@weasel-js/headless';
+
+type Row = { name: string; heading?: boolean };
+const shape = { canStop: (r: Row) => !r.heading, label: (r: Row) => r.name };
+
+let at: number | null = null;
+let typed = EMPTY_TYPEAHEAD;
+
+function onKey(rows: readonly Row[], key: string): void {
+  const r = rovingKey(rows, at, key, shape);      // arrows, Home, End
+  if (r.handled) { at = r.at; return; }
+  if (key.length === 1) {
+    const t = typeaheadStep(rows, at, typed, key, Date.now(), shape);
+    typed = t.buffer;
+    if (t.hit !== null) at = t.hit;
+  }
+}
+```
+
+A list's shape says which items the highlight can land on (`canStop`), which arrows move it
+(`orientation`, vertical by default, or `'both'` for all four), whether Left and Right swap for a
+right-to-left layout (`dir`), and whether it wraps at the ends (`wrap`, on by default).
+`@weasel-js/menu` runs every menu level on these.
+
+## Focus
+
+`FocusScope<T>` is keyboard focus over a set of targets, whatever draws them: which one is
+focused, whether its ring shows, `focus`, `moveFocus` through a `tabOrder`, and
+`subscribeFocus`. A `@weasel-js/hud` HUD is one over its widgets, and `@weasel-js/ui`'s
+`domFocusScope(root)` is one over the elements under `root`, so code that moves focus is
+written once for both. `tabSort` and `tabStep` are the order and the step both use.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+/** How a list's items are read: which ones the highlight can land on, and which way its arrows run. */
+interface ListShape<T> {
+    /** Whether the highlight can land on `item`. A separator or a heading can't. Default: every item. */
+    canStop?(item: T): boolean;
+    /** Which arrow keys move the highlight. `'both'` answers to all four, the way a radio group does. Default `'vertical'`. */
+    orientation?: 'vertical' | 'horizontal' | 'both';
+    /** The inline direction the items are laid out in. Under `'rtl'` Left steps forward and Right back. Default `'ltr'`. */
+    dir?: 'ltr' | 'rtl';
+    /** An arrow past either end comes round to the other. Default true. */
+    wrap?: boolean;
+}
+/** Index of the first item the highlight can land on, or null for a list with none. */
+declare function firstStop<T>(items: readonly T[], shape?: ListShape<T>): number | null;
+/** The next item the highlight can land on from `from` in direction `dir`; from `null`, the first or last.
+ *  Without wrap, an end stays where it is. Null for a list with no such item. */
+declare function stepStop<T>(items: readonly T[], from: number | null, dir: 1 | -1, shape?: ListShape<T>): number | null;
+/** What one key does to a list's highlight. `handled` false for a key that is not the list's to move. */
+type RovingResult = {
+    handled: false;
+} | {
+    handled: true;
+    at: number | null;
+};
+/** Move the highlight `at` by one key: the arrows along the list's orientation, Home and End. */
+declare function rovingKey<T>(items: readonly T[], at: number | null, key: string, shape?: ListShape<T>): RovingResult;
+
+/** How typeahead reads a list: its shape, and the text each item is found by. */
+interface TypeaheadShape<T> extends Pick<ListShape<T>, 'canStop'> {
+    label(item: T): string;
+}
+/** How long typing can pause before the typeahead buffer starts over, in milliseconds. */
+declare const TYPEAHEAD_RESET_MS = 500;
+/** What has been typed so far, and when the last key came. */
+interface TypeaheadBuffer {
+    text: string;
+    at: number;
+}
+/** A buffer nothing has been typed into. */
+declare const EMPTY_TYPEAHEAD: TypeaheadBuffer;
+/** The item a typed `query` lands on, searching forward from `from` with
+ *  wrap. A one-letter query starts after the highlight so repeating a letter
+ *  cycles; a longer one starts at it so typing on keeps the match. */
+declare function typeaheadMatch<T>(items: readonly T[], from: number | null, query: string, shape: TypeaheadShape<T>): number | null;
+/** One typed character: the new buffer and the item it lands on. A key that
+ *  repeats the whole buffer searches that one letter, so it cycles. */
+declare function typeaheadStep<T>(items: readonly T[], from: number | null, buffer: TypeaheadBuffer, key: string, now: number, shape: TypeaheadShape<T>, resetMs?: number): {
+    buffer: TypeaheadBuffer;
+    hit: number | null;
+};
+
+/** How a focus change came about. */
+interface FocusScopeOptions {
+    /** Whether the target shows its focus ring: the scope's `:focus-visible`. Keyboard moves show one, a press does
+     *  not. Default `false` for {@link FocusScope.focus}, `true` for {@link FocusScope.moveFocus}. */
+    readonly visible?: boolean;
+}
+/**
+ * Keyboard focus over a set of targets, whatever draws them: a HUD's widgets and a DOM subtree's elements both
+ * answer it, so code that moves or reads focus is written once for either.
+ */
+interface FocusScope<T> {
+    /** The target holding keyboard focus, or null. One per scope. */
+    readonly focused: T | null;
+    /** Whether the focused target shows its focus ring. */
+    readonly focusVisible: boolean;
+    /** Focus `target`, or blur with `null`. Returns whether `target` now holds focus: false when it is not in this
+     *  scope or cannot take focus, and focus is then unchanged. */
+    focus(target: T | null, options?: FocusScopeOptions): boolean;
+    /** Move focus one step through {@link tabOrder}. From nothing, `'next'` lands on the first target and `'prev'` on
+     *  the last; past either end the scope blurs and returns null, which is where focus leaves it. */
+    moveFocus(direction: 'next' | 'prev', options?: FocusScopeOptions): T | null;
+    /** The targets Tab visits, in order. */
+    tabOrder(): T[];
+    /** Run `fn` whenever the focused target changes. Returns an unsubscribe. */
+    subscribeFocus(fn: (focused: T | null) => void): () => void;
+}
+/** Tab order: targets that declare a place come first, ascending, then the rest in the order given. In the DOM a
+ *  positive `tabindex` declares one and `0` does not. */
+declare function tabSort<T>(targets: readonly T[], declared: (target: T) => number | undefined): T[];
+/** The target one Tab step from `from` through `order`, or null past either end. From nothing, `'next'` is the
+ *  first and `'prev'` the last. A `from` that is out of the order (hidden since it took focus, say) steps from where
+ *  it sits, which `isBefore` says; without it, such a `from` steps as nothing does. */
+declare function tabStep<T>(order: readonly T[], from: T | null, direction: 'next' | 'prev', isBefore?: (a: T, b: T) => boolean): T | null;
+
+export { EMPTY_TYPEAHEAD, type FocusScope, type FocusScopeOptions, type ListShape, type RovingResult, TYPEAHEAD_RESET_MS, type TypeaheadBuffer, type TypeaheadShape, firstStop, rovingKey, stepStop, tabSort, tabStep, typeaheadMatch, typeaheadStep };

package/dist/index.js

@@ -0,0 +1,85 @@
+// src/list.ts
+var always = () => true;
+function firstStop(items, shape = {}) {
+  const i = items.findIndex(shape.canStop ?? always);
+  return i < 0 ? null : i;
+}
+function stepStop(items, from, dir, shape = {}) {
+  const canStop = shape.canStop ?? always;
+  const wrap = shape.wrap ?? true;
+  const n = items.length;
+  let i = from ?? (dir === 1 ? -1 : n);
+  for (let k = 0; k < n; k++) {
+    i += dir;
+    if (i < 0 || i >= n) {
+      if (!wrap) break;
+      i = (i + n) % n;
+    }
+    if (canStop(items[i])) return i;
+  }
+  return !wrap && from !== null && canStop(items[from]) ? from : null;
+}
+function arrowDir(key, shape) {
+  const orientation = shape.orientation ?? "vertical";
+  if (orientation !== "horizontal") {
+    if (key === "ArrowDown") return 1;
+    if (key === "ArrowUp") return -1;
+  }
+  if (orientation !== "vertical") {
+    const forward = shape.dir === "rtl" ? -1 : 1;
+    if (key === "ArrowRight") return forward;
+    if (key === "ArrowLeft") return -forward;
+  }
+  return 0;
+}
+function rovingKey(items, at, key, shape = {}) {
+  if (key === "Home") return { handled: true, at: stepStop(items, null, 1, shape) };
+  if (key === "End") return { handled: true, at: stepStop(items, null, -1, shape) };
+  const dir = arrowDir(key, shape);
+  return dir === 0 ? { handled: false } : { handled: true, at: stepStop(items, at, dir, shape) };
+}
+
+// src/typeahead.ts
+var TYPEAHEAD_RESET_MS = 500;
+var EMPTY_TYPEAHEAD = { text: "", at: -Infinity };
+function typeaheadMatch(items, from, query, shape) {
+  const q = query.toLowerCase();
+  const n = items.length;
+  const start = from == null ? 0 : q.length === 1 ? from + 1 : from;
+  for (let k = 0; k < n; k++) {
+    const i = (start + k) % n;
+    const item = items[i];
+    if ((shape.canStop?.(item) ?? true) && shape.label(item).toLowerCase().startsWith(q)) return i;
+  }
+  return null;
+}
+function typeaheadStep(items, from, buffer, key, now, shape, resetMs = TYPEAHEAD_RESET_MS) {
+  const prev = now - buffer.at < resetMs ? buffer.text : "";
+  const k = key.toLowerCase();
+  const cycling = prev !== "" && [...prev].every((c) => c.toLowerCase() === k);
+  const text = cycling ? key : prev + key;
+  return { buffer: { text, at: now }, hit: typeaheadMatch(items, from, text, shape) };
+}
+
+// src/focus.ts
+function tabSort(targets, declared) {
+  const key = (t) => declared(t) ?? Number.POSITIVE_INFINITY;
+  return [...targets].sort((a, b) => key(a) - key(b));
+}
+function tabStep(order, from, direction, isBefore) {
+  const forward = direction === "next";
+  const here = from === null ? -1 : order.indexOf(from);
+  let at;
+  if (here !== -1) at = here + (forward ? 1 : -1);
+  else if (from === null || !isBefore) at = forward ? 0 : order.length - 1;
+  else {
+    const after = order.findIndex((t) => isBefore(from, t));
+    const end = after === -1 ? order.length : after;
+    at = forward ? end : end - 1;
+  }
+  return order[at] ?? null;
+}
+
+export { EMPTY_TYPEAHEAD, TYPEAHEAD_RESET_MS, firstStop, rovingKey, stepStop, tabSort, tabStep, typeaheadMatch, typeaheadStep };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/list.ts","../src/typeahead.ts","../src/focus.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/** How a list's items are read: which ones the highlight can land on, and which way its arrows run. */\nexport interface ListShape<T> {\n  /** Whether the highlight can land on `item`. A separator or a heading can't. Default: every item. */\n  canStop?(item: T): boolean;\n  /** Which arrow keys move the highlight. `'both'` answers to all four, the way a radio group does. Default `'vertical'`. */\n  orientation?: 'vertical' | 'horizontal' | 'both';\n  /** The inline direction the items are laid out in. Under `'rtl'` Left steps forward and Right back. Default `'ltr'`. */\n  dir?: 'ltr' | 'rtl';\n  /** An arrow past either end comes round to the other. Default true. */\n  wrap?: boolean;\n}\n\nconst always = () => true;\n\n/** Index of the first item the highlight can land on, or null for a list with none. */\nexport function firstStop<T>(items: readonly T[], shape: ListShape<T> = {}): number | null {\n  const i = items.findIndex(shape.canStop ?? always);\n  return i < 0 ? null : i;\n}\n\n/** The next item the highlight can land on from `from` in direction `dir`; from `null`, the first or last.\n *  Without wrap, an end stays where it is. Null for a list with no such item. */\nexport function stepStop<T>(\n  items: readonly T[], from: number | null, dir: 1 | -1, shape: ListShape<T> = {},\n): number | null {\n  const canStop = shape.canStop ?? always;\n  const wrap = shape.wrap ?? true;\n  const n = items.length;\n  let i = from ?? (dir === 1 ? -1 : n);\n  for (let k = 0; k < n; k++) {\n    i += dir;\n    if (i < 0 || i >= n) {\n      if (!wrap) break;\n      i = (i + n) % n;\n    }\n    if (canStop(items[i]!)) return i;\n  }\n  return !wrap && from !== null && canStop(items[from]!) ? from : null;\n}\n\n/** What one key does to a list's highlight. `handled` false for a key that is not the list's to move. */\nexport type RovingResult = { handled: false } | { handled: true; at: number | null };\n\n/** Which way an arrow key steps a list of `shape`: 1, -1, or 0 for a key that is not one of its arrows. */\nfunction arrowDir(key: string, shape: ListShape<unknown>): 1 | -1 | 0 {\n  const orientation = shape.orientation ?? 'vertical';\n  if (orientation !== 'horizontal') {\n    if (key === 'ArrowDown') return 1;\n    if (key === 'ArrowUp') return -1;\n  }\n  if (orientation !== 'vertical') {\n    const forward = shape.dir === 'rtl' ? -1 : 1;\n    if (key === 'ArrowRight') return forward;\n    if (key === 'ArrowLeft') return -forward as 1 | -1;\n  }\n  return 0;\n}\n\n/** Move the highlight `at` by one key: the arrows along the list's orientation, Home and End. */\nexport function rovingKey<T>(items: readonly T[], at: number | null, key: string, shape: ListShape<T> = {}): RovingResult {\n  if (key === 'Home') return { handled: true, at: stepStop(items, null, 1, shape) };\n  if (key === 'End') return { handled: true, at: stepStop(items, null, -1, shape) };\n  const dir = arrowDir(key, shape as ListShape<unknown>);\n  return dir === 0 ? { handled: false } : { handled: true, at: stepStop(items, at, dir, shape) };\n}\n","import type { ListShape } from './list';\n\n/** How typeahead reads a list: its shape, and the text each item is found by. */\nexport interface TypeaheadShape<T> extends Pick<ListShape<T>, 'canStop'> {\n  label(item: T): string;\n}\n\n/** How long typing can pause before the typeahead buffer starts over, in milliseconds. */\nexport const TYPEAHEAD_RESET_MS = 500;\n\n/** What has been typed so far, and when the last key came. */\nexport interface TypeaheadBuffer {\n  text: string;\n  at: number;\n}\n\n/** A buffer nothing has been typed into. */\nexport const EMPTY_TYPEAHEAD: TypeaheadBuffer = { text: '', at: -Infinity };\n\n/** The item a typed `query` lands on, searching forward from `from` with\n *  wrap. A one-letter query starts after the highlight so repeating a letter\n *  cycles; a longer one starts at it so typing on keeps the match. */\nexport function typeaheadMatch<T>(\n  items: readonly T[], from: number | null, query: string, shape: TypeaheadShape<T>,\n): number | null {\n  const q = query.toLowerCase();\n  const n = items.length;\n  const start = from == null ? 0 : q.length === 1 ? from + 1 : from;\n  for (let k = 0; k < n; k++) {\n    const i = (start + k) % n;\n    const item = items[i]!;\n    if ((shape.canStop?.(item) ?? true) && shape.label(item).toLowerCase().startsWith(q)) return i;\n  }\n  return null;\n}\n\n/** One typed character: the new buffer and the item it lands on. A key that\n *  repeats the whole buffer searches that one letter, so it cycles. */\nexport function typeaheadStep<T>(\n  items: readonly T[],\n  from: number | null,\n  buffer: TypeaheadBuffer,\n  key: string,\n  now: number,\n  shape: TypeaheadShape<T>,\n  resetMs: number = TYPEAHEAD_RESET_MS,\n): { buffer: TypeaheadBuffer; hit: number | null } {\n  const prev = now - buffer.at < resetMs ? buffer.text : '';\n  const k = key.toLowerCase();\n  const cycling = prev !== '' && [...prev].every((c) => c.toLowerCase() === k);\n  const text = cycling ? key : prev + key;\n  return { buffer: { text, at: now }, hit: typeaheadMatch(items, from, text, shape) };\n}\n","/** How a focus change came about. */\nexport interface FocusScopeOptions {\n  /** Whether the target shows its focus ring: the scope's `:focus-visible`. Keyboard moves show one, a press does\n   *  not. Default `false` for {@link FocusScope.focus}, `true` for {@link FocusScope.moveFocus}. */\n  readonly visible?: boolean;\n}\n\n/**\n * Keyboard focus over a set of targets, whatever draws them: a HUD's widgets and a DOM subtree's elements both\n * answer it, so code that moves or reads focus is written once for either.\n */\nexport interface FocusScope<T> {\n  /** The target holding keyboard focus, or null. One per scope. */\n  readonly focused: T | null;\n  /** Whether the focused target shows its focus ring. */\n  readonly focusVisible: boolean;\n  /** Focus `target`, or blur with `null`. Returns whether `target` now holds focus: false when it is not in this\n   *  scope or cannot take focus, and focus is then unchanged. */\n  focus(target: T | null, options?: FocusScopeOptions): boolean;\n  /** Move focus one step through {@link tabOrder}. From nothing, `'next'` lands on the first target and `'prev'` on\n   *  the last; past either end the scope blurs and returns null, which is where focus leaves it. */\n  moveFocus(direction: 'next' | 'prev', options?: FocusScopeOptions): T | null;\n  /** The targets Tab visits, in order. */\n  tabOrder(): T[];\n  /** Run `fn` whenever the focused target changes. Returns an unsubscribe. */\n  subscribeFocus(fn: (focused: T | null) => void): () => void;\n}\n\n/** Tab order: targets that declare a place come first, ascending, then the rest in the order given. In the DOM a\n *  positive `tabindex` declares one and `0` does not. */\nexport function tabSort<T>(targets: readonly T[], declared: (target: T) => number | undefined): T[] {\n  const key = (t: T) => declared(t) ?? Number.POSITIVE_INFINITY;\n  // Array.prototype.sort is stable, so ties and the undeclared keep the given order.\n  return [...targets].sort((a, b) => key(a) - key(b));\n}\n\n/** The target one Tab step from `from` through `order`, or null past either end. From nothing, `'next'` is the\n *  first and `'prev'` the last. A `from` that is out of the order (hidden since it took focus, say) steps from where\n *  it sits, which `isBefore` says; without it, such a `from` steps as nothing does. */\nexport function tabStep<T>(\n  order: readonly T[], from: T | null, direction: 'next' | 'prev', isBefore?: (a: T, b: T) => boolean,\n): T | null {\n  const forward = direction === 'next';\n  const here = from === null ? -1 : order.indexOf(from);\n  let at: number;\n  if (here !== -1) at = here + (forward ? 1 : -1);\n  else if (from === null || !isBefore) at = forward ? 0 : order.length - 1;\n  else {\n    const after = order.findIndex((t) => isBefore(from, t));\n    const end = after === -1 ? order.length : after;\n    at = forward ? end : end - 1;\n  }\n  return order[at] ?? null;\n}\n"]}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@weasel-js/headless",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.13.0",
+  "description": "Headless components: list behavior (roving highlight, typeahead) that a DOM component and a canvas-drawn widget share. No React, no DOM.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "author": "orochi235",
+  "homepage": "https://orochi235.github.io/weasel/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orochi235/weasel.git",
+    "directory": "packages/headless"
+  },
+  "bugs": {
+    "url": "https://github.com/orochi235/weasel/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}