@lp-labs/tree-selection 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Libin Prasanth
+
+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,102 @@
-# Temporary Holding Version
+# @lp-labs/tree-selection
 
-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.
+Dynamic hierarchical leaf selection with derived tri-state and disabled-subtree contracts.
+
+Standalone original implementation with zero runtime, peer or sibling dependencies.
+Library ID 440. ES2022, strict TypeScript, NodeNext ESM and CommonJS with declarations.
+
+## Install
+
+```bash
+npm install @lp-labs/tree-selection
+```
+
+CommonJS: `const { createTreeSelection } = require('@lp-labs/tree-selection')`.
+
+## Quickstart
+
+```js
+import { createTreeSelection } from '@lp-labs/tree-selection';
+
+const tree = createTreeSelection([
+  { id: 'root' },
+  { id: 'a', parent: 'root' },
+  { id: 'b', parent: 'root' },
+]);
+tree.toggle('a');
+if (tree.state('root') !== 'mixed') throw new Error('Tri-state failed');
+tree.toggle('root');
+if (tree.selected().join(',') !== 'a,b') throw new Error('Cascade failed');
+```
+
+## API, customization and contracts
+
+`createTreeSelection(nodes)` accepts a forest of unique nonempty IDs and optional parent
+IDs. Input order is not required to be topological. Missing parents and cycles are rejected.
+Limits: 10000 nodes and depth 128 including the root.
+
+Only enabled terminal leaves are stored as checked IDs. A disabled node excludes its entire
+subtree, even descendants not explicitly disabled. Aggregation ignores those excluded leaves.
+A node with zero eligible leaves has state 'disabled'; otherwise zero selected = 'unchecked',
+all selected = 'checked', partial = 'mixed'. A parent containing only disabled children
+does not become an independently selectable leaf.
+`toggle(id, selected?)` applies to eligible descendant leaves. Omitted selected fills an
+unchecked/mixed subtree and clears a checked subtree; explicit true/false sets all leaves.
+Toggling a disabled subtree is a no-op. `state(id)` returns the derived state.
+`selected()` returns a detached array of checked leaf IDs in node input order, not branch IDs.
+
+`replace(nodes)` validates and builds indexes atomically. Surviving eligible leaf IDs retain
+selection; removed, disabled or newly nonterminal IDs lose it. Newly inserted/re-enabled
+leaves start unchecked: a previously checked branch does not implicitly select new children.
+Inputs and outputs are detached. Unknown IDs, missing parents, cycles and duplicates throw
+TypeError; node/depth limits throw RangeError.
+
+Building/replacement O(N * depth), memory O(N * depth) for descendant indexes;
+toggle/state O(eligible descendants), selected O(N). The depth cap bounds this explicitly.
+This is an original hierarchical model separate from selection-model's flat selection and
+range semantics; neither package is imported or used as a renamed implementation.
+
+## Complete public declarations
+
+```ts
+export interface TreeNode {
+  id: string;
+  parent?: string;
+  disabled?: boolean;
+}
+export type CheckState = 'checked' | 'mixed' | 'unchecked' | 'disabled';
+export interface TreeSelection {
+  toggle(id: string, selected?: boolean): void;
+  state(id: string): CheckState;
+  selected(): string[];
+  replace(nodes: readonly TreeNode[]): void;
+}
+/** Only enabled terminal leaves are stored; a disabled ancestor excludes its subtree. */
+export declare function createTreeSelection(initial: readonly TreeNode[]): TreeSelection;
+```
+
+## Scope and performance
+
+Parent-linked forest selection, not flat range selection, a tree renderer, expansion model or DOM accessibility layer.
+
+Complexities and bounds above assume ordinary JavaScript number arithmetic and Map/Set
+average constant-time lookup. No runtime or peer dependencies, automatic browser adapters,
+global registries or hidden services are included. Importing the module has no browser effects.
+
+## Development
+
+```bash
+npm ci --offline --no-audit --no-fund
+npm run build
+npm run typecheck
+npm test
+npm run format:check
+```
+
+## Support
+
+If this library is useful to you, consider supporting its maintenance with a [donation via PayPal](https://www.paypal.me/LibinPrasanth).
+
+## Author
+
+Created by [Libin Prasanth](https://www.linkedin.com/in/libinprasanth/). Connect on LinkedIn for updates and discussion.

package/dist/cjs/index.d.ts

@@ -0,0 +1,14 @@
+export interface TreeNode {
+    id: string;
+    parent?: string;
+    disabled?: boolean;
+}
+export type CheckState = 'checked' | 'mixed' | 'unchecked' | 'disabled';
+export interface TreeSelection {
+    toggle(id: string, selected?: boolean): void;
+    state(id: string): CheckState;
+    selected(): string[];
+    replace(nodes: readonly TreeNode[]): void;
+}
+/** Only enabled terminal leaves are stored; a disabled ancestor excludes its subtree. */
+export declare function createTreeSelection(initial: readonly TreeNode[]): TreeSelection;

package/dist/cjs/index.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTreeSelection = createTreeSelection;
+/** Only enabled terminal leaves are stored; a disabled ancestor excludes its subtree. */
+function createTreeSelection(initial) {
+    let nodes = new Map();
+    let leaves = new Map();
+    let checked = new Set();
+    function replace(next) {
+        if (next.length > 10000)
+            throw new RangeError('Tree exceeds 10000 nodes');
+        const map = new Map();
+        for (const n of next) {
+            if (typeof n.id !== 'string' ||
+                !n.id ||
+                map.has(n.id) ||
+                (n.parent !== undefined && typeof n.parent !== 'string') ||
+                (n.disabled !== undefined && typeof n.disabled !== 'boolean'))
+                throw new TypeError('Invalid node ID');
+            map.set(n.id, { ...n });
+        }
+        const parents = new Set();
+        for (const n of map.values()) {
+            if (n.parent !== undefined) {
+                if (!map.has(n.parent))
+                    throw new TypeError('Unknown parent');
+                parents.add(n.parent);
+            }
+            const seen = new Set();
+            let current = n;
+            while (current) {
+                if (seen.has(current.id))
+                    throw new TypeError('Tree cycle');
+                seen.add(current.id);
+                if (seen.size > 128)
+                    throw new RangeError('Tree depth exceeds 128');
+                current = current.parent === undefined ? undefined : map.get(current.parent);
+            }
+        }
+        const index = new Map([...map.keys()].map((id) => [id, []]));
+        for (const n of map.values()) {
+            if (parents.has(n.id))
+                continue;
+            const chain = [];
+            let current = n;
+            while (current) {
+                chain.push(current);
+                current = current.parent === undefined ? undefined : map.get(current.parent);
+            }
+            if (chain.some((node) => node.disabled))
+                continue;
+            for (const node of chain)
+                index.get(node.id).push(n.id);
+        }
+        nodes = map;
+        leaves = index;
+        checked = new Set([...checked].filter((id) => index.get(id)?.includes(id)));
+    }
+    function eligible(id) {
+        if (!nodes.has(id))
+            throw new TypeError('Unknown node');
+        return leaves.get(id);
+    }
+    function state(id) {
+        const descendants = eligible(id);
+        if (!descendants.length)
+            return 'disabled';
+        const count = descendants.filter((leaf) => checked.has(leaf)).length;
+        return count === 0 ? 'unchecked' : count === descendants.length ? 'checked' : 'mixed';
+    }
+    replace(initial);
+    return {
+        replace,
+        state,
+        toggle(id, selected) {
+            if (selected !== undefined && typeof selected !== 'boolean')
+                throw new TypeError('Invalid selected state');
+            const descendants = eligible(id);
+            const value = selected ?? state(id) !== 'checked';
+            for (const leaf of descendants) {
+                if (value)
+                    checked.add(leaf);
+                else
+                    checked.delete(leaf);
+            }
+        },
+        selected: () => [...nodes.keys()].filter((id) => checked.has(id)),
+    };
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,14 @@
+export interface TreeNode {
+    id: string;
+    parent?: string;
+    disabled?: boolean;
+}
+export type CheckState = 'checked' | 'mixed' | 'unchecked' | 'disabled';
+export interface TreeSelection {
+    toggle(id: string, selected?: boolean): void;
+    state(id: string): CheckState;
+    selected(): string[];
+    replace(nodes: readonly TreeNode[]): void;
+}
+/** Only enabled terminal leaves are stored; a disabled ancestor excludes its subtree. */
+export declare function createTreeSelection(initial: readonly TreeNode[]): TreeSelection;

package/dist/esm/index.js

@@ -0,0 +1,86 @@
+/** Only enabled terminal leaves are stored; a disabled ancestor excludes its subtree. */
+export function createTreeSelection(initial) {
+    let nodes = new Map();
+    let leaves = new Map();
+    let checked = new Set();
+    function replace(next) {
+        if (next.length > 10000)
+            throw new RangeError('Tree exceeds 10000 nodes');
+        const map = new Map();
+        for (const n of next) {
+            if (typeof n.id !== 'string' ||
+                !n.id ||
+                map.has(n.id) ||
+                (n.parent !== undefined && typeof n.parent !== 'string') ||
+                (n.disabled !== undefined && typeof n.disabled !== 'boolean'))
+                throw new TypeError('Invalid node ID');
+            map.set(n.id, { ...n });
+        }
+        const parents = new Set();
+        for (const n of map.values()) {
+            if (n.parent !== undefined) {
+                if (!map.has(n.parent))
+                    throw new TypeError('Unknown parent');
+                parents.add(n.parent);
+            }
+            const seen = new Set();
+            let current = n;
+            while (current) {
+                if (seen.has(current.id))
+                    throw new TypeError('Tree cycle');
+                seen.add(current.id);
+                if (seen.size > 128)
+                    throw new RangeError('Tree depth exceeds 128');
+                current = current.parent === undefined ? undefined : map.get(current.parent);
+            }
+        }
+        const index = new Map([...map.keys()].map((id) => [id, []]));
+        for (const n of map.values()) {
+            if (parents.has(n.id))
+                continue;
+            const chain = [];
+            let current = n;
+            while (current) {
+                chain.push(current);
+                current = current.parent === undefined ? undefined : map.get(current.parent);
+            }
+            if (chain.some((node) => node.disabled))
+                continue;
+            for (const node of chain)
+                index.get(node.id).push(n.id);
+        }
+        nodes = map;
+        leaves = index;
+        checked = new Set([...checked].filter((id) => index.get(id)?.includes(id)));
+    }
+    function eligible(id) {
+        if (!nodes.has(id))
+            throw new TypeError('Unknown node');
+        return leaves.get(id);
+    }
+    function state(id) {
+        const descendants = eligible(id);
+        if (!descendants.length)
+            return 'disabled';
+        const count = descendants.filter((leaf) => checked.has(leaf)).length;
+        return count === 0 ? 'unchecked' : count === descendants.length ? 'checked' : 'mixed';
+    }
+    replace(initial);
+    return {
+        replace,
+        state,
+        toggle(id, selected) {
+            if (selected !== undefined && typeof selected !== 'boolean')
+                throw new TypeError('Invalid selected state');
+            const descendants = eligible(id);
+            const value = selected ?? state(id) !== 'checked';
+            for (const leaf of descendants) {
+                if (value)
+                    checked.add(leaf);
+                else
+                    checked.delete(leaf);
+            }
+        },
+        selected: () => [...nodes.keys()].filter((id) => checked.has(id)),
+    };
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@lp-labs/tree-selection",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Dynamic hierarchical leaf selection with derived tri-state and disabled-subtree contracts.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "npm run build && node scripts/check-types.mjs",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "format": "prettier --write src scripts tests *.json README.md",
+    "format:check": "prettier --check src scripts tests *.json README.md",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "prettier": "^3.6.2"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 100,
+    "endOfLine": "lf"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": {
+    "name": "Libin Prasanth",
+    "url": "https://www.linkedin.com/in/libinprasanth/"
+  },
+  "funding": {
+    "type": "paypal",
+    "url": "https://www.paypal.me/LibinPrasanth"
+  }
+}