Initial version

2026-07-11 21:14:49 -05:00
commit e812fe8b72
8 changed files with 1226 additions and 0 deletions
@@ -0,0 +1,93 @@
+# Checkbox Tree
+
+A dependency-free, instance-based checkbox tree for browser ES modules. It
+supports cascading selection, indeterminate parent states, expandable branches,
+multiple independent instances, and optional local-storage persistence.
+
+## Install
+
+```sh
+npm install @aaronaxvig/checkbox-tree
+```
+
+The package is not published yet. During local development, install it by path:
+
+```sh
+npm install ../checkbox-tree
+```
+
+## Usage
+
+```js
+import { CheckboxTree } from "@aaronaxvig/checkbox-tree";
+import "@aaronaxvig/checkbox-tree/styles.css";
+
+const tree = new CheckboxTree(document.querySelector("#example-tree"), {
+  initiallySelected: true,
+  storageKey: "example-tree-state",
+  onSelectionChange({ selectedIds, selectedNodes }) {
+    console.log(selectedIds, selectedNodes);
+  },
+});
+
+tree.setData([
+  {
+    id: "fruit",
+    label: "Fruit",
+    children: [
+      { id: "apple", label: "Apple", metadata: { color: "red" } },
+      { id: "pear", label: "Pear", metadata: { color: "green" } },
+    ],
+  },
+]);
+```
+
+For applications without a bundler, serve or copy the two files in `src/` and
+use relative URLs:
+
+```html
+<link rel="stylesheet" href="./checkbox-tree.css">
+<script type="module">
+  import { CheckboxTree } from "./checkbox-tree.js";
+</script>
+```
+
+Every node requires unique string `id` and `label` properties. Nodes may also
+have `children`, application-owned `metadata`, and `selectable` or `disabled`
+flags.
+
+## API
+
+- `new CheckboxTree(container, options)` creates an independent instance.
+- `setData(nodes)` validates and renders nodes, then restores saved state.
+- `getSelectedIds()` returns selected node IDs.
+- `getSelectedNodes()` returns selected source node objects.
+- `setSelectedIds(ids, { notify })` replaces the selection.
+- `restoreState()` restores selection and expansion state.
+- `destroy()` removes listeners, markup, and the root CSS class.
+
+Options:
+
+- `initiallyCollapsed` defaults to `true`.
+- `initiallySelected` defaults to `false`.
+- `storageKey` defaults to `null`, which disables persistence.
+- `onSelectionChange` receives `{ selectedIds, selectedNodes }`.
+
+Styling is namespaced under `.checkbox-tree`. Override the custom properties
+`--checkbox-tree-indent`, `--checkbox-tree-toggle-size`, and
+`--checkbox-tree-hover-color` in the consuming application.
+
+## Development
+
+```sh
+npm install
+npm test
+npm run pack:check
+```
+
+## Future demo ideas
+
+- Add population metadata to the country, state, and county nodes and display the
+  total population represented by the current selection. Define the aggregation
+  rule carefully so checked ancestors and their checked descendants are not
+  counted twice; one option is to total only the most specific checked nodes.