diff --git a/src/data/visibility-tree-manifest.json b/src/data/visibility-tree-manifest.json new file mode 100644 index 0000000..f7a2ae8 --- /dev/null +++ b/src/data/visibility-tree-manifest.json @@ -0,0 +1,142 @@ +{ + "schema": 1, + "nodes": [ + "visibility:category:plants", + "visibility:category:plants>visibility:type:flower", + "visibility:category:plants>visibility:type:flower>visibility:feature:83", + "visibility:category:plants>visibility:type:flower>visibility:feature:84", + "visibility:category:plants>visibility:type:flower>visibility:feature:85", + "visibility:category:plants>visibility:type:flower>visibility:feature:86", + "visibility:category:plants>visibility:type:flower>visibility:feature:87", + "visibility:category:plants>visibility:type:flower>visibility:feature:88", + "visibility:category:plants>visibility:type:flower>visibility:feature:89", + "visibility:category:plants>visibility:type:flower>visibility:feature:90", + "visibility:category:plants>visibility:type:flower>visibility:feature:91", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:53", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:54", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:55", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:56", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:57", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:58", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:59", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:60", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:61", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:62", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:63", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:64", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:65", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:66", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:67", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:68", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:69", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:70", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:71", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:72", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:73", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:74", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:75", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:76", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:77", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:78", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:79", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:80", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:81", + "visibility:category:plants>visibility:type:flower>visibility:type:daylily>visibility:feature:82", + "visibility:category:plants>visibility:type:tree", + "visibility:category:plants>visibility:type:tree>visibility:feature:92", + "visibility:category:plants>visibility:type:tree>visibility:feature:93", + "visibility:category:plants>visibility:type:tree>visibility:feature:94", + "visibility:category:plants>visibility:type:tree>visibility:feature:95", + "visibility:category:plants>visibility:type:tree>visibility:feature:96", + "visibility:category:plants>visibility:type:tree>visibility:feature:97", + "visibility:category:plants>visibility:type:tree>visibility:feature:98", + "visibility:category:plants>visibility:type:tree>visibility:feature:99", + "visibility:category:plants>visibility:type:tree>visibility:feature:100", + "visibility:category:plants>visibility:type:tree>visibility:feature:101", + "visibility:category:plants>visibility:type:tree>visibility:feature:102", + "visibility:category:plants>visibility:type:tree>visibility:feature:103", + "visibility:category:plants>visibility:type:tree>visibility:feature:114", + "visibility:category:plants>visibility:type:tree>visibility:feature:115", + "visibility:category:plants>visibility:type:tree>visibility:feature:116", + "visibility:category:plants>visibility:type:tree>visibility:feature:117", + "visibility:category:plants>visibility:type:bush", + "visibility:category:plants>visibility:type:bush>visibility:feature:109", + "visibility:category:plants>visibility:type:bush>visibility:feature:110", + "visibility:category:plants>visibility:type:bush>visibility:feature:111", + "visibility:category:plants>visibility:type:bush>visibility:feature:112", + "visibility:category:plants>visibility:type:bush>visibility:feature:113", + "visibility:category:plants>visibility:type:bush>visibility:group:juniper-trees", + "visibility:category:plants>visibility:type:bush>visibility:group:juniper-trees>visibility:feature:104", + "visibility:category:plants>visibility:type:bush>visibility:group:juniper-trees>visibility:feature:105", + "visibility:category:plants>visibility:type:bush>visibility:group:juniper-trees>visibility:feature:106", + "visibility:category:plants>visibility:type:bush>visibility:group:juniper-trees>visibility:feature:107", + "visibility:category:plants>visibility:type:bush>visibility:group:juniper-trees>visibility:feature:108", + "visibility:category:structures", + "visibility:category:structures>visibility:type:fence", + "visibility:category:structures>visibility:type:fence>visibility:feature:1", + "visibility:category:structures>visibility:type:flowerBed", + "visibility:category:structures>visibility:type:flowerBed>visibility:feature:48", + "visibility:category:structures>visibility:type:flowerBed>visibility:feature:49", + "visibility:category:structures>visibility:type:flowerBed>visibility:feature:50", + "visibility:category:structures>visibility:type:flowerBed>visibility:feature:51", + "visibility:category:structures>visibility:type:flowerBed>visibility:feature:52", + "visibility:category:structures>visibility:group:buildings", + "visibility:category:structures>visibility:group:buildings>visibility:feature:40", + "visibility:category:structures>visibility:group:buildings>visibility:feature:41", + "visibility:category:structures>visibility:group:buildings>visibility:group:house-parts", + "visibility:category:structures>visibility:group:buildings>visibility:group:house-parts>visibility:feature:42", + "visibility:category:structures>visibility:group:buildings>visibility:group:house-parts>visibility:feature:43", + "visibility:category:structures>visibility:group:paved-surfaces", + "visibility:category:structures>visibility:group:paved-surfaces>visibility:feature:44", + "visibility:category:structures>visibility:group:paved-surfaces>visibility:feature:45", + "visibility:category:structures>visibility:group:paved-surfaces>visibility:feature:46", + "visibility:category:structures>visibility:group:paved-surfaces>visibility:feature:47", + "visibility:category:infrastructure", + "visibility:category:infrastructure>visibility:type:sprinkler", + "visibility:category:infrastructure>visibility:type:sprinkler>visibility:feature:118", + "visibility:category:infrastructure>visibility:type:sprinkler>visibility:feature:119", + "visibility:category:reference", + "visibility:category:reference>visibility:type:lotBoundary", + "visibility:category:reference>visibility:type:lotBoundary>visibility:feature:0", + "visibility:category:reference>visibility:group:yard-grid", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:2", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:3", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:4", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:5", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:6", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:7", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:8", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:9", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:10", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:11", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:12", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:13", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:14", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:15", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:16", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:17", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:18", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:19", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:20", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:21", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:22", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:23", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:24", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:25", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:26", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:27", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:28", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:29", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:30", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:31", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:32", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:33", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:34", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:35", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:36", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:37", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:38", + "visibility:category:reference>visibility:group:yard-grid>visibility:feature:39" + ] +} diff --git a/src/main.js b/src/main.js index 7ecd99d..5eb0ac2 100644 --- a/src/main.js +++ b/src/main.js @@ -1,5 +1,5 @@ import { yardGeoJSON } from "./data/yard.js"; -import { CheckboxTree } from "../vendor/checkbox-tree/checkbox-tree.js"; +import { CheckboxTree, loadManifest } from "../vendor/checkbox-tree/checkbox-tree.js"; import { resolveFeatureLinks, resolveFeatureStyle } from "./lib/feature-types.js"; const TILE_MAX_NATIVE_ZOOM = 19; @@ -51,7 +51,7 @@ let selectedFeatureIndexes = new Set(yardGeoJSON.features.map((_, index) => inde let yardLayer = null; const timelineButtons = new Map(); -initializeVisibilityTree(); +await initializeVisibilityTree(); renderYardForDate(selectedTimelineDate); addTimelineControl(); map.fitBounds(getGeoJSONBounds(yardGeoJSON).pad(0.2), { maxZoom: MAP_MAX_ZOOM }); @@ -129,19 +129,44 @@ function filterFeatureCollection(collection, date, visibleIndexes) { }; } -function initializeVisibilityTree() { - const tree = new CheckboxTree(document.getElementById("visibility-tree"), { +async function initializeVisibilityTree() { + const container = document.getElementById("visibility-tree"); + const manifest = loadManifest( + await fetch("./src/data/visibility-tree-manifest.json").then((response) => response.json()), + ); + const tree = new CheckboxTree(container, { initiallyCollapsed: true, initiallySelected: true, storageKey: "a-plot-of-plants:visibility:v1", + manifest, onSelectionChange: ({ selectedNodes }) => { selectedFeatureIndexes = getSelectedFeatureIndexes(selectedNodes); renderYardForDate(selectedTimelineDate); + pushTreeState(tree); }, }); tree.setData(buildVisibilityNodes(yardGeoJSON)); selectedFeatureIndexes = getSelectedFeatureIndexes(tree.getSelectedNodes()); + + container.addEventListener("click", (event) => { + if (event.target.closest(".checkbox-tree__toggle")) { + pushTreeState(tree); + } + }); + window.addEventListener("popstate", () => { + tree.restoreStateFromLocation(); + selectedFeatureIndexes = getSelectedFeatureIndexes(tree.getSelectedNodes()); + renderYardForDate(selectedTimelineDate); + }); +} + +function pushTreeState(tree) { + const url = new URL(window.location.href); + url.hash = tree.serializeStateToFragment(); + if (url.href !== window.location.href) { + history.pushState(null, "", url); + } } function getSelectedFeatureIndexes(nodes) { diff --git a/vendor/checkbox-tree/README.md b/vendor/checkbox-tree/README.md index 1b8b58f..a14d6f3 100644 --- a/vendor/checkbox-tree/README.md +++ b/vendor/checkbox-tree/README.md @@ -1,5 +1,125 @@ -# Checkbox Tree runtime snapshot +# Checkbox Tree -Vendored from `@aaronaxvig/checkbox-tree` version `0.1.0` while -`git.axvig.com` is unavailable. Do not edit these runtime files directly; update -the canonical `checkbox-tree` repository and refresh this snapshot. +A dependency-free, instance-based checkbox tree for browser ES modules. It +supports cascading selection, indeterminate parent states, expandable branches, +multiple independent instances, optional local-storage persistence, and compact +shareable URL state backed by an append-only node manifest. + +## 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 + + +``` + +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. +- `serializeStateToFragment(manifest)` returns `#v=1&c=...&x=...` state. +- `restoreStateFromLocation(manifest, location)` safely applies URL state. +- `validateManifest(manifest)` reports unregistered and missing paths. + +Options: + +- `initiallyCollapsed` defaults to `true`. +- `initiallySelected` defaults to `false`. +- `storageKey` defaults to `null`, which disables persistence. +- `onSelectionChange` receives `{ selectedIds, selectedNodes }`. +- `manifest` optionally supplies a parsed manifest and automatically restores + state from `window.location.hash` after `setData()`. + +## Shareable URL state + +Create a JSON manifest whose array positions are permanent slots. Canonical node +paths join ancestor IDs with `>`: + +```json +{ "schema": 1, "nodes": ["fruit", "fruit>apple", "fruit>pear", null] } +``` + +Import `loadManifest`, pass its result as the `manifest` option, and call +`tree.serializeStateToFragment()` when creating a share link. Existing entries +must never be reordered. Append new paths, replace removed paths with `null`, and +edit a path in place for a logical rename or move. Node IDs therefore cannot +contain `>`. + +The fragment adaptively encodes checked (`c`) and expanded (`x`) state using the +shortest of a dense bitset, sparse enabled slots, or sparse disabled slots. +Sparse slot numbers are delta-encoded variable-length integers. A coverage value +in the disabled-slot form ensures nodes appended later still default to unchecked +and collapsed. Malformed or unsupported state is ignored. +The helpers `encodeTreeState`, `decodeTreeState`, `applyTreeState`, and +`restoreStateFromLocation` are also exported for custom integrations. +Use `validateManifestEvolution(previous, next)` in a build check to reject +removed slots and tombstone reuse; path changes are reported for deliberate +rename/move review. + +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. diff --git a/vendor/checkbox-tree/checkbox-tree.js b/vendor/checkbox-tree/checkbox-tree.js index c470d48..4974fc6 100644 --- a/vendor/checkbox-tree/checkbox-tree.js +++ b/vendor/checkbox-tree/checkbox-tree.js @@ -2,9 +2,310 @@ const DEFAULT_OPTIONS = { initiallyCollapsed: true, initiallySelected: false, storageKey: null, - onSelectionChange: null + onSelectionChange: null, + manifest: null }; +const SERIALIZATION_VERSION = 1; +const PATH_DELIMITER = '>'; + +export function loadManifest(source) { + let records; + let schema = 1; + + if (typeof source === 'string') { + records = source.split(/\r?\n/) + .map(line => line.trim()) + .filter(line => line && !line.startsWith('#')) + .map(line => line === '!deleted' ? null : line); + } else if (source && typeof source === 'object' && Array.isArray(source.nodes)) { + schema = source.schema; + records = source.nodes; + } else if (source && Array.isArray(source.slots)) { + return normalizeManifest(source.schema, source.slots.map(slot => slot?.deleted ? null : slot?.path)); + } else { + throw new TypeError('CheckboxTree manifest must be text or an object with a nodes array.'); + } + + return normalizeManifest(schema, records); +} + +function normalizeManifest(schema, records) { + if (schema !== 1) { + throw new Error(`Unsupported CheckboxTree manifest schema: ${schema}`); + } + + const pathToSlot = new Map(); + const slots = records.map((record, index) => { + if (record === null || record === '!deleted') { + return { path: null, deleted: true }; + } + if (typeof record !== 'string' || !record || record.trim() !== record) { + throw new TypeError(`Invalid CheckboxTree manifest entry at slot ${index}.`); + } + if (pathToSlot.has(record)) { + throw new Error(`Duplicate CheckboxTree manifest path: ${record}`); + } + pathToSlot.set(record, index); + return { path: record, deleted: false }; + }); + + return { schema: 1, slots, pathToSlot }; +} + +export function setBit(bytes, bitIndex, value) { + const byteIndex = Math.floor(bitIndex / 8); + const mask = 1 << (bitIndex % 8); + if (value) bytes[byteIndex] |= mask; + else bytes[byteIndex] &= ~mask; +} + +export function getBit(bytes, bitIndex) { + const byteIndex = Math.floor(bitIndex / 8); + return byteIndex < bytes.length && (bytes[byteIndex] & (1 << (bitIndex % 8))) !== 0; +} + +export function bytesToBase64Url(bytes) { + let binary = ''; + for (const byte of bytes) binary += String.fromCharCode(byte); + return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, ''); +} + +export function base64UrlToBytes(value, maximumLength = Infinity) { + if (typeof value !== 'string' || !/^[A-Za-z0-9_-]*$/.test(value) || value.length % 4 === 1) { + throw new Error('Invalid Base64URL value.'); + } + if (Number.isFinite(maximumLength) && value.length > Math.ceil(maximumLength * 4 / 3) + 2) { + throw new Error('Encoded tree state exceeds the manifest size.'); + } + const base64 = value.replace(/-/g, '+').replace(/_/g, '/'); + const binary = atob(base64 + '='.repeat((4 - base64.length % 4) % 4)); + if (binary.length > maximumLength) throw new Error('Encoded tree state exceeds the manifest size.'); + return Uint8Array.from(binary, character => character.charCodeAt(0)); +} + +function trimTrailingZeroBytes(bytes) { + let end = bytes.length; + while (end && bytes[end - 1] === 0) end--; + return bytes.slice(0, end); +} + +function encodeUnsignedVarint(value) { + const bytes = []; + do { + let byte = value & 0x7f; + value = Math.floor(value / 128); + if (value) byte |= 0x80; + bytes.push(byte); + } while (value); + return bytes; +} + +function decodeUnsignedVarint(bytes, offset) { + let value = 0; + let multiplier = 1; + for (let index = offset; index < bytes.length && index < offset + 8; index++) { + const byte = bytes[index]; + value += (byte & 0x7f) * multiplier; + if ((byte & 0x80) === 0) return { value, offset: index + 1 }; + multiplier *= 128; + if (!Number.isSafeInteger(value) || !Number.isSafeInteger(multiplier)) break; + } + throw new Error('Invalid adaptive tree-state integer.'); +} + +function encodeSparseIndexes(indexes) { + const bytes = []; + let previous = -1; + for (const index of indexes) { + bytes.push(...encodeUnsignedVarint(index - previous - 1)); + previous = index; + } + return bytes; +} + +function decodeSparseIndexes(bytes, offset, limit) { + const indexes = new Set(); + let previous = -1; + while (offset < bytes.length) { + const decoded = decodeUnsignedVarint(bytes, offset); + const index = previous + decoded.value + 1; + if (index >= limit) throw new Error('Sparse tree state contains an out-of-range slot.'); + indexes.add(index); + previous = index; + offset = decoded.offset; + } + return indexes; +} + +export function encodeAdaptiveBitset(values, slotCount) { + const enabled = []; + const disabled = []; + const denseBytes = new Uint8Array(Math.ceil(slotCount / 8)); + for (const [slot, value] of values) { + (value ? enabled : disabled).push(slot); + setBit(denseBytes, slot, value); + } + enabled.sort((left, right) => left - right); + disabled.sort((left, right) => left - right); + if (enabled.length === 0) return new Uint8Array(); + + const candidates = [ + Uint8Array.from([0, ...trimTrailingZeroBytes(denseBytes)]), + Uint8Array.from([1, ...encodeSparseIndexes(enabled)]), + Uint8Array.from([2, ...encodeUnsignedVarint(slotCount), ...encodeSparseIndexes(disabled)]) + ]; + return candidates.reduce((shortest, candidate) => + candidate.length < shortest.length ? candidate : shortest + ); +} + +export function decodeAdaptiveBitset(bytes, slotCount) { + if (bytes.length === 0) return () => false; + const mode = bytes[0]; + if (mode === 0) { + const dense = bytes.slice(1); + if (dense.length > Math.ceil(slotCount / 8)) { + throw new Error('Dense tree state exceeds the manifest size.'); + } + return slot => getBit(dense, slot); + } + if (mode === 1) { + const enabled = decodeSparseIndexes(bytes, 1, slotCount); + return slot => enabled.has(slot); + } + if (mode === 2) { + const coverage = decodeUnsignedVarint(bytes, 1); + if (coverage.value > slotCount) throw new Error('Tree-state coverage exceeds the manifest size.'); + const disabled = decodeSparseIndexes(bytes, coverage.offset, coverage.value); + return slot => slot < coverage.value && !disabled.has(slot); + } + throw new Error('Unknown adaptive tree-state mode.'); +} + +function asManifest(manifest) { + return manifest?.pathToSlot instanceof Map ? manifest : loadManifest(manifest); +} + +export function validateManifest(manifest, tree) { + const normalized = asManifest(manifest); + const treePaths = new Set(tree.nodesByPath.keys()); + return { + valid: Array.from(treePaths).every(path => normalized.pathToSlot.has(path)), + unregisteredPaths: Array.from(treePaths).filter(path => !normalized.pathToSlot.has(path)), + missingPaths: normalized.slots + .filter(slot => !slot.deleted && !treePaths.has(slot.path)) + .map(slot => slot.path) + }; +} + +export function validateManifestEvolution(previous, next) { + const oldManifest = asManifest(previous); + const newManifest = asManifest(next); + const errors = []; + + if (newManifest.slots.length < oldManifest.slots.length) { + errors.push('Manifest slots cannot be removed; use tombstones.'); + } + oldManifest.slots.forEach((oldSlot, index) => { + const newSlot = newManifest.slots[index]; + if (!newSlot) return; + if (oldSlot.deleted && !newSlot.deleted) { + errors.push(`Tombstoned slot ${index} cannot be reused.`); + } + if (!oldSlot.deleted && !newSlot.deleted && oldSlot.path !== newSlot.path) { + errors.push(`Slot ${index} changed path; confirm this is a logical rename or move.`); + } + }); + + return { valid: errors.length === 0, errors }; +} + +export function encodeTreeState(tree, manifest) { + const normalized = asManifest(manifest); + const checkedValues = new Map(); + const expandedValues = new Map(); + + for (const [path, node] of tree.nodesByPath) { + const slot = normalized.pathToSlot.get(path); + if (slot === undefined) continue; + const item = tree.itemForNode(node.id); + const checkbox = item && tree.directCheckbox(item); + const toggle = item?.querySelector(':scope > .checkbox-tree__row > .checkbox-tree__toggle'); + checkedValues.set(slot, Boolean(checkbox?.checked)); + expandedValues.set(slot, toggle?.getAttribute('aria-expanded') === 'true'); + } + + const checkedValue = bytesToBase64Url(encodeAdaptiveBitset(checkedValues, normalized.slots.length)); + const expandedValue = bytesToBase64Url(encodeAdaptiveBitset(expandedValues, normalized.slots.length)); + return { version: SERIALIZATION_VERSION, checked: checkedValue || null, expanded: expandedValue || null }; +} + +export function decodeTreeState(fragment, manifest) { + const normalized = asManifest(manifest); + const value = fragment.startsWith('#') ? fragment.slice(1) : fragment; + const params = new URLSearchParams(value); + if (params.get('v') !== String(SERIALIZATION_VERSION)) { + return { applied: false, version: params.get('v'), warnings: ['Missing or unsupported serialization version.'] }; + } + const maximumLength = Math.max( + Math.ceil(normalized.slots.length / 8) + 1, + normalized.slots.length * 2 + 10 + ); + try { + const checked = base64UrlToBytes(params.get('c') ?? '', maximumLength); + const expanded = base64UrlToBytes(params.get('x') ?? '', maximumLength); + decodeAdaptiveBitset(checked, normalized.slots.length); + decodeAdaptiveBitset(expanded, normalized.slots.length); + return { + applied: true, + version: SERIALIZATION_VERSION, + checked, + expanded, + warnings: [] + }; + } catch (error) { + return { applied: false, version: SERIALIZATION_VERSION, warnings: [error.message] }; + } +} + +export function applyTreeState(tree, manifest, state) { + if (!state?.applied) return false; + const normalized = asManifest(manifest); + let isChecked; + let isExpanded; + try { + isChecked = decodeAdaptiveBitset(state.checked, normalized.slots.length); + isExpanded = decodeAdaptiveBitset(state.expanded, normalized.slots.length); + } catch { + return false; + } + for (const [path, node] of tree.nodesByPath) { + const slot = normalized.pathToSlot.get(path); + if (slot === undefined) continue; + const item = tree.itemForNode(node.id); + const checkbox = item && tree.directCheckbox(item); + if (checkbox && !checkbox.disabled) checkbox.checked = isChecked(slot); + tree.setExpanded(item, isExpanded(slot)); + } + tree.updateAllParentCheckboxes(); + return true; +} + +export function serializeStateToFragment(tree, manifest) { + const state = encodeTreeState(tree, manifest); + const params = new URLSearchParams({ v: String(state.version) }); + if (state.checked) params.set('c', state.checked); + if (state.expanded) params.set('x', state.expanded); + return `#${params}`; +} + +export function restoreStateFromLocation(tree, manifest, location = window.location) { + const state = decodeTreeState(location.hash ?? '', manifest); + if (state.applied) applyTreeState(tree, manifest, state); + return state; +} + export class CheckboxTree { constructor(container, options = {}) { if (!(container instanceof Element)) { @@ -14,6 +315,7 @@ export class CheckboxTree { this.container = container; this.options = { ...DEFAULT_OPTIONS, ...options }; this.nodesById = new Map(); + this.nodesByPath = new Map(); this.rootNodes = []; this.handleChange = this.handleChange.bind(this); this.handleClick = this.handleClick.bind(this); @@ -29,11 +331,13 @@ export class CheckboxTree { } this.nodesById.clear(); + this.nodesByPath.clear(); this.rootNodes = nodes; this.indexNodes(nodes); this.render(); this.updateAllParentCheckboxes(); this.restoreState(); + if (this.options.manifest) this.restoreStateFromLocation(); } getSelectedIds() { @@ -66,9 +370,10 @@ export class CheckboxTree { this.container.classList.remove('checkbox-tree'); this.container.replaceChildren(); this.nodesById.clear(); + this.nodesByPath.clear(); } - indexNodes(nodes) { + indexNodes(nodes, parentPath = '') { nodes.forEach(node => { if (!node || typeof node.id !== 'string' || !node.id || typeof node.label !== 'string') { throw new TypeError('Each CheckboxTree node requires non-empty string id and label properties.'); @@ -77,12 +382,18 @@ export class CheckboxTree { throw new Error(`Duplicate CheckboxTree node id: ${node.id}`); } + if (node.id.includes(PATH_DELIMITER)) { + throw new Error(`CheckboxTree node id cannot contain "${PATH_DELIMITER}": ${node.id}`); + } + this.nodesById.set(node.id, node); + const path = parentPath ? `${parentPath}${PATH_DELIMITER}${node.id}` : node.id; + this.nodesByPath.set(path, node); if (node.children !== undefined) { if (!Array.isArray(node.children)) { throw new TypeError(`CheckboxTree node children must be an array: ${node.id}`); } - this.indexNodes(node.children); + this.indexNodes(node.children, path); } }); } @@ -191,6 +502,7 @@ export class CheckboxTree { } setExpanded(item, expanded) { + if (!item) return; const toggle = item.querySelector(':scope > .checkbox-tree__row > .checkbox-tree__toggle'); const children = this.directChildrenContainer(item); if (!toggle || !children) { @@ -211,6 +523,11 @@ export class CheckboxTree { return item.querySelector(':scope > .checkbox-tree__row .checkbox-tree__checkbox'); } + itemForNode(id) { + return Array.from(this.container.querySelectorAll('.checkbox-tree__item')) + .find(item => item.dataset.nodeId === id) ?? null; + } + updateAncestorCheckboxes(item) { let parentItem = item.parentElement?.closest('.checkbox-tree__item'); while (parentItem && this.container.contains(parentItem)) { @@ -286,4 +603,16 @@ export class CheckboxTree { }); } } + + validateManifest(manifest = this.options.manifest) { + return validateManifest(manifest, this); + } + + serializeStateToFragment(manifest = this.options.manifest) { + return serializeStateToFragment(this, manifest); + } + + restoreStateFromLocation(manifest = this.options.manifest, location = window.location) { + return restoreStateFromLocation(this, manifest, location); + } }