@weasel-js/select 0.0.0-stage → 1.8.1

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,43 @@
-# Temporary Holding Version
+# @weasel-js/select
 
-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.
+Selection as a value: which ids a press selects, under toggle, range and anchor rules a surface
+configures. 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/api/).
+
+## Install
+
+```sh
+npm install @weasel-js/select
+```
+
+## Usage
+
+```ts
+import { intentOf, select } from '@weasel-js/select';
+
+// A list's convention: Cmd/Ctrl toggles a row, shift ranges from the anchor.
+const policy = { mode: 'multi', toggle: ['meta', 'ctrl'], range: 'shift' } as const;
+
+let state = { ids: ['b'], anchor: 'b' };
+state = select(state, 'd', intentOf({ shift: true, meta: false, ctrl: false }, policy), {
+  order: ['a', 'b', 'c', 'd'],          // what a range walks
+  eligible: (id) => id !== 'c',         // locked rows never join a multi-selection
+});
+// → { ids: ['b', 'd'], anchor: 'b' }
+```
+
+| intent | ids | anchor |
+|---|---|---|
+| `replace` | `[id]` | `id` |
+| `toggle` | eligible ids, with `id` added or removed; `[id]` if `id` is ineligible | `id` |
+| `range` | eligible ids from anchor to `id` in `order`; unchanged if none is eligible; `[id]` if there is no anchor or either end is outside `order` | unchanged |
+
+`createSelectionStore` keeps ids outside a component, behind the `SelectionStore` contract that
+`@weasel-js/core`'s `Scene` also satisfies.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/** `single` always replaces; `multi` lets a policy's keys toggle and range. */
+type SelectionMode = 'single' | 'multi';
+/** A modifier key a policy can assign to toggling or ranging. */
+type SelectionExtendKey = 'shift' | 'meta' | 'ctrl';
+/** The modifiers held during a press. */
+type SelectModifiers = Readonly<Record<SelectionExtendKey, boolean>>;
+/** What a press does to the selection. */
+type SelectIntent = 'replace' | 'toggle' | 'range';
+/** Which keys toggle and which range, so a surface states its convention: a list usually
+ *  toggles on Cmd/Ctrl and ranges on shift, a canvas toggles on shift. */
+interface SelectPolicy {
+    readonly mode: SelectionMode;
+    readonly toggle?: SelectionExtendKey | readonly SelectionExtendKey[];
+    readonly range?: SelectionExtendKey;
+}
+/** What is selected, and the end a range extends from. */
+interface Selection<K> {
+    readonly ids: readonly K[];
+    readonly anchor: K | null;
+}
+interface SelectContext<K> {
+    /** The sequence a range walks. A range without one replaces. */
+    readonly order?: readonly K[];
+    /** Whether an id may join a multi-selection. Ineligible ids are skipped by a range, dropped
+     *  when the selection grows, and selected alone when pressed. Default: every id. */
+    readonly eligible?: (id: K) => boolean;
+}
+/** The intent a press carries under `policy`. A range key beats a toggle key. */
+declare function intentOf(modifiers: SelectModifiers, policy: SelectPolicy): SelectIntent;
+/** The eligible ids from `from` to `to` in `order`, ends included, in order. Empty when either
+ *  end is not in `order`. */
+declare function rangeOf<K>(order: readonly K[], from: K, to: K, eligible?: (id: K) => boolean): K[];
+/** The selection after pressing `id` with `intent`. Returns `state` itself when nothing changes
+ *  hands, so a caller can compare by reference. */
+declare function select<K>(state: Selection<K>, id: K, intent: SelectIntent, context?: SelectContext<K>): Selection<K>;
+
+/** Somewhere a selection can live outside the component that edits it. core's `Scene` satisfies
+ *  it, and so does any store with the same three methods. */
+interface SelectionStore<K> {
+    getSelection(): readonly K[];
+    setSelection(ids: readonly K[]): void;
+    subscribe(listener: () => void): () => void;
+}
+/** A {@link SelectionStore} holding the ids itself. A listener reads the new value. */
+declare function createSelectionStore<K>(initial?: readonly K[]): SelectionStore<K>;
+
+export { type SelectContext, type SelectIntent, type SelectModifiers, type SelectPolicy, type Selection, type SelectionExtendKey, type SelectionMode, type SelectionStore, createSelectionStore, intentOf, rangeOf, select };

package/dist/index.js

@@ -0,0 +1,54 @@
+// src/select.ts
+function intentOf(modifiers, policy) {
+  if (policy.mode === "single") return "replace";
+  if (policy.range && modifiers[policy.range]) return "range";
+  const toggle = typeof policy.toggle === "string" ? [policy.toggle] : policy.toggle ?? [];
+  return toggle.some((key) => modifiers[key]) ? "toggle" : "replace";
+}
+function rangeOf(order, from, to, eligible = always) {
+  const a = order.indexOf(from);
+  const b = order.indexOf(to);
+  if (a < 0 || b < 0) return [];
+  return order.slice(Math.min(a, b), Math.max(a, b) + 1).filter(eligible);
+}
+function select(state, id, intent, context = {}) {
+  const eligible = context.eligible ?? always;
+  if (intent === "toggle" && eligible(id)) {
+    const kept = state.ids.filter(eligible);
+    return { ids: kept.includes(id) ? kept.filter((x) => x !== id) : [...kept, id], anchor: id };
+  }
+  if (intent === "range" && state.anchor !== null && context.order) {
+    const { order } = context;
+    if (order.includes(state.anchor) && order.includes(id)) {
+      const ids = rangeOf(order, state.anchor, id, eligible);
+      return ids.length > 0 ? { ids, anchor: state.anchor } : state;
+    }
+  }
+  return { ids: [id], anchor: id };
+}
+function always() {
+  return true;
+}
+
+// src/store.ts
+function createSelectionStore(initial = []) {
+  let ids = initial;
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    getSelection: () => ids,
+    setSelection(next) {
+      ids = next;
+      for (const listener of listeners) listener();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    }
+  };
+}
+
+export { createSelectionStore, intentOf, rangeOf, select };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/select.ts","../src/store.ts"],"names":[],"mappings":";AAmCO,SAAS,QAAA,CAAS,WAA4B,MAAA,EAAoC;AACvF,EAAA,IAAI,MAAA,CAAO,IAAA,KAAS,QAAA,EAAU,OAAO,SAAA;AACrC,EAAA,IAAI,OAAO,KAAA,IAAS,SAAA,CAAU,MAAA,CAAO,KAAK,GAAG,OAAO,OAAA;AACpD,EAAA,MAAM,MAAA,GAAS,OAAO,MAAA,CAAO,MAAA,KAAW,QAAA,GAAW,CAAC,MAAA,CAAO,MAAM,CAAA,GAAK,MAAA,CAAO,MAAA,IAAU,EAAC;AACxF,EAAA,OAAO,MAAA,CAAO,KAAK,CAAC,GAAA,KAAQ,UAAU,GAAG,CAAC,IAAI,QAAA,GAAW,SAAA;AAC3D;AAIO,SAAS,OAAA,CAAW,KAAA,EAAqB,IAAA,EAAS,EAAA,EAAO,WAA+B,MAAA,EAAa;AAC1G,EAAA,MAAM,CAAA,GAAI,KAAA,CAAM,OAAA,CAAQ,IAAI,CAAA;AAC5B,EAAA,MAAM,CAAA,GAAI,KAAA,CAAM,OAAA,CAAQ,EAAE,CAAA;AAC1B,EAAA,IAAI,CAAA,GAAI,CAAA,IAAK,CAAA,GAAI,CAAA,SAAU,EAAC;AAC5B,EAAA,OAAO,KAAA,CAAM,KAAA,CAAM,IAAA,CAAK,GAAA,CAAI,GAAG,CAAC,CAAA,EAAG,IAAA,CAAK,GAAA,CAAI,GAAG,CAAC,CAAA,GAAI,CAAC,CAAA,CAAE,OAAO,QAAQ,CAAA;AACxE;AAIO,SAAS,OAAU,KAAA,EAAqB,EAAA,EAAO,MAAA,EAAsB,OAAA,GAA4B,EAAC,EAAiB;AACxH,EAAA,MAAM,QAAA,GAAW,QAAQ,QAAA,IAAY,MAAA;AACrC,EAAA,IAAI,MAAA,KAAW,QAAA,IAAY,QAAA,CAAS,EAAE,CAAA,EAAG;AACvC,IAAA,MAAM,IAAA,GAAO,KAAA,CAAM,GAAA,CAAI,MAAA,CAAO,QAAQ,CAAA;AACtC,IAAA,OAAO,EAAE,GAAA,EAAK,IAAA,CAAK,SAAS,EAAE,CAAA,GAAI,KAAK,MAAA,CAAO,CAAC,MAAM,CAAA,KAAM,EAAE,IAAI,CAAC,GAAG,MAAM,EAAE,CAAA,EAAG,QAAQ,EAAA,EAAG;AAAA,EAC7F;AACA,EAAA,IAAI,WAAW,OAAA,IAAW,KAAA,CAAM,MAAA,KAAW,IAAA,IAAQ,QAAQ,KAAA,EAAO;AAChE,IAAA,MAAM,EAAE,OAAM,GAAI,OAAA;AAClB,IAAA,IAAI,KAAA,CAAM,SAAS,KAAA,CAAM,MAAM,KAAK,KAAA,CAAM,QAAA,CAAS,EAAE,CAAA,EAAG;AACtD,MAAA,MAAM,MAAM,OAAA,CAAQ,KAAA,EAAO,KAAA,CAAM,MAAA,EAAQ,IAAI,QAAQ,CAAA;AACrD,MAAA,OAAO,GAAA,CAAI,SAAS,CAAA,GAAI,EAAE,KAAK,MAAA,EAAQ,KAAA,CAAM,QAAO,GAAI,KAAA;AAAA,IAC1D;AAAA,EACF;AACA,EAAA,OAAO,EAAE,GAAA,EAAK,CAAC,EAAE,CAAA,EAAG,QAAQ,EAAA,EAAG;AACjC;AAEA,SAAS,MAAA,GAAkB;AACzB,EAAA,OAAO,IAAA;AACT;;;AC9DO,SAAS,oBAAA,CAAwB,OAAA,GAAwB,EAAC,EAAsB;AACrF,EAAA,IAAI,GAAA,GAAM,OAAA;AACV,EAAA,MAAM,SAAA,uBAAgB,GAAA,EAAgB;AACtC,EAAA,OAAO;AAAA,IACL,cAAc,MAAM,GAAA;AAAA,IACpB,aAAa,IAAA,EAAM;AACjB,MAAA,GAAA,GAAM,IAAA;AACN,MAAA,KAAA,MAAW,QAAA,IAAY,WAAW,QAAA,EAAS;AAAA,IAC7C,CAAA;AAAA,IACA,UAAU,QAAA,EAAU;AAClB,MAAA,SAAA,CAAU,IAAI,QAAQ,CAAA;AACtB,MAAA,OAAO,MAAM;AAAE,QAAA,SAAA,CAAU,OAAO,QAAQ,CAAA;AAAA,MAAG,CAAA;AAAA,IAC7C;AAAA,GACF;AACF","file":"index.js","sourcesContent":["/** `single` always replaces; `multi` lets a policy's keys toggle and range. */\nexport type SelectionMode = 'single' | 'multi';\n\n/** A modifier key a policy can assign to toggling or ranging. */\nexport type SelectionExtendKey = 'shift' | 'meta' | 'ctrl';\n\n/** The modifiers held during a press. */\nexport type SelectModifiers = Readonly<Record<SelectionExtendKey, boolean>>;\n\n/** What a press does to the selection. */\nexport type SelectIntent = 'replace' | 'toggle' | 'range';\n\n/** Which keys toggle and which range, so a surface states its convention: a list usually\n *  toggles on Cmd/Ctrl and ranges on shift, a canvas toggles on shift. */\nexport interface SelectPolicy {\n  readonly mode: SelectionMode;\n  readonly toggle?: SelectionExtendKey | readonly SelectionExtendKey[];\n  readonly range?: SelectionExtendKey;\n}\n\n/** What is selected, and the end a range extends from. */\nexport interface Selection<K> {\n  readonly ids: readonly K[];\n  readonly anchor: K | null;\n}\n\nexport interface SelectContext<K> {\n  /** The sequence a range walks. A range without one replaces. */\n  readonly order?: readonly K[];\n  /** Whether an id may join a multi-selection. Ineligible ids are skipped by a range, dropped\n   *  when the selection grows, and selected alone when pressed. Default: every id. */\n  readonly eligible?: (id: K) => boolean;\n}\n\n/** The intent a press carries under `policy`. A range key beats a toggle key. */\nexport function intentOf(modifiers: SelectModifiers, policy: SelectPolicy): SelectIntent {\n  if (policy.mode === 'single') return 'replace';\n  if (policy.range && modifiers[policy.range]) return 'range';\n  const toggle = typeof policy.toggle === 'string' ? [policy.toggle] : (policy.toggle ?? []);\n  return toggle.some((key) => modifiers[key]) ? 'toggle' : 'replace';\n}\n\n/** The eligible ids from `from` to `to` in `order`, ends included, in order. Empty when either\n *  end is not in `order`. */\nexport function rangeOf<K>(order: readonly K[], from: K, to: K, eligible: (id: K) => boolean = always): K[] {\n  const a = order.indexOf(from);\n  const b = order.indexOf(to);\n  if (a < 0 || b < 0) return [];\n  return order.slice(Math.min(a, b), Math.max(a, b) + 1).filter(eligible);\n}\n\n/** The selection after pressing `id` with `intent`. Returns `state` itself when nothing changes\n *  hands, so a caller can compare by reference. */\nexport function select<K>(state: Selection<K>, id: K, intent: SelectIntent, context: SelectContext<K> = {}): Selection<K> {\n  const eligible = context.eligible ?? always;\n  if (intent === 'toggle' && eligible(id)) {\n    const kept = state.ids.filter(eligible);\n    return { ids: kept.includes(id) ? kept.filter((x) => x !== id) : [...kept, id], anchor: id };\n  }\n  if (intent === 'range' && state.anchor !== null && context.order) {\n    const { order } = context;\n    if (order.includes(state.anchor) && order.includes(id)) {\n      const ids = rangeOf(order, state.anchor, id, eligible);\n      return ids.length > 0 ? { ids, anchor: state.anchor } : state;\n    }\n  }\n  return { ids: [id], anchor: id };\n}\n\nfunction always(): boolean {\n  return true;\n}\n","/** Somewhere a selection can live outside the component that edits it. core's `Scene` satisfies\n *  it, and so does any store with the same three methods. */\nexport interface SelectionStore<K> {\n  getSelection(): readonly K[];\n  setSelection(ids: readonly K[]): void;\n  subscribe(listener: () => void): () => void;\n}\n\n/** A {@link SelectionStore} holding the ids itself. A listener reads the new value. */\nexport function createSelectionStore<K>(initial: readonly K[] = []): SelectionStore<K> {\n  let ids = initial;\n  const listeners = new Set<() => void>();\n  return {\n    getSelection: () => ids,\n    setSelection(next) {\n      ids = next;\n      for (const listener of listeners) listener();\n    },\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => { listeners.delete(listener); };\n    },\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@weasel-js/select",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.8.1",
+  "description": "Selection as a value: which ids a press selects, with toggle, range and anchor rules a surface configures. 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/select"
+  },
+  "bugs": {
+    "url": "https://github.com/orochi235/weasel/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}