wip
This commit is contained in:
191
README.md
191
README.md
@@ -1,89 +1,148 @@
|
||||
# tp-tree-nav
|
||||
|
||||
`tp-tree-nav` is a low-level, virtualized tree renderer for Lit. It is intentionally “dumb”: it only renders what it is given and emits events. Parents own all state (expanded/selected/custom), perform mutations, and pass updated data back in. This makes it a flexible foundation for building higher-level trees (e.g., VS Code–style explorer, Git ignore/selected indicators, custom icon trees).
|
||||
`tp-tree-nav` is a low-level, virtualized tree renderer for Lit. It renders what it is given and emits events; parents own state. You can wrap it directly or extend it to add opinionated behavior (selection, expansion, inline actions, empty states, etc.).
|
||||
|
||||
## Key ideas
|
||||
- **Multiple roots**: pass a `roots` array; each node may have `children`.
|
||||
- **Virtualized list**: uses `@lit-labs/virtualizer` to render a flat, indented list for large trees.
|
||||
- **Events only**: emits `node-click`, `node-context`, and `node-action` (for chevron toggle and context menu actions). Every event includes `originalEvent` so parents can cancel or coordinate.
|
||||
- **Opt-in actions**: provide `defaultActions` (array of action objects), and per-node `actions`; node actions override defaults on the same `action` key. Use `beforeContextMenu(node, actions)` to modify or block the menu.
|
||||
- **Custom render**: `renderNode(node, meta)` lets you override row rendering (e.g., icons per node type, state-based styling). Common states like `expanded`/`collapsed` are parent-managed via `node.states`.
|
||||
- **Helper methods (pure)**: `getNodesWithState`, `clearState`, `applyStateIf` return data; they don’t mutate internal state—parents update `roots`.
|
||||
- **Events only**: emits `node-click`, `node-context`, and `node-action` (for chevron toggle, inline actions, and context menu actions). Each event carries `originalEvent` so parents can cancel or coordinate.
|
||||
- **Opt-in actions**: provide `defaultActions` and per-node `actions`; node actions override defaults on the same `action` key. Use `beforeContextMenu(node, actions)` to modify or block the menu.
|
||||
- **Custom render**: `renderNode(node, meta)` lets you override row rendering (icons per node type, state-based styling). Common states like `expanded`/`selected` are parent-managed via `node.states` or managed mode.
|
||||
- **Helpers (pure)**: `getNodesWithState`, `clearState`, `applyStateIf` return new data; parents reassign `roots`.
|
||||
- **Default icons**: `chevron`, `folder`, `file` are available via `tp-icon`; pass string keys or custom icons.
|
||||
|
||||
## Usage example
|
||||
## Quick example (wrap directly)
|
||||
```js
|
||||
import './tp-tree-nav.js';
|
||||
|
||||
const tree = document.querySelector('tp-tree-nav');
|
||||
|
||||
const roots = [
|
||||
{
|
||||
label: 'Project A',
|
||||
slug: 'project-a',
|
||||
states: ['expanded'],
|
||||
icon: 'folder',
|
||||
children: [
|
||||
{ label: 'main.js', slug: 'main-js', icon: 'file', states: [] },
|
||||
{
|
||||
label: 'src',
|
||||
slug: 'src',
|
||||
icon: 'folder',
|
||||
states: ['expanded'],
|
||||
children: [
|
||||
{ label: 'index.js', slug: 'index-js', icon: 'file', states: [] },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
tree.roots = [
|
||||
{
|
||||
label: 'Project A',
|
||||
slug: 'project-a',
|
||||
states: ['expanded'],
|
||||
icon: 'folder',
|
||||
children: [
|
||||
{ label: 'main.js', slug: 'main-js', icon: 'file', states: [] },
|
||||
{
|
||||
label: 'src',
|
||||
slug: 'src',
|
||||
icon: 'folder',
|
||||
states: ['expanded'],
|
||||
children: [
|
||||
{ label: 'index.js', slug: 'index-js', icon: 'file', states: [] },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
tree.roots = roots;
|
||||
tree.defaultActions = [
|
||||
{ label: 'Rename', action: 'rename', icon: 'pencil' },
|
||||
{ label: 'Delete', action: 'delete', icon: 'delete' },
|
||||
{ label: 'Rename', action: 'rename', icon: 'pencil' },
|
||||
{ label: 'Delete', action: 'delete', icon: 'delete' },
|
||||
];
|
||||
|
||||
tree.beforeContextMenu = (node, actions) => {
|
||||
// Example: hide delete on roots
|
||||
if (node.slug === 'project-a') {
|
||||
return actions.filter((a) => a.action !== 'delete');
|
||||
}
|
||||
return actions;
|
||||
};
|
||||
tree.beforeContextMenu = (node, actions) =>
|
||||
node.slug === 'project-a' ? actions.filter((a) => a.action !== 'delete') : actions;
|
||||
|
||||
tree.renderNode = (node, { depth, states, path, hasChildren }) => {
|
||||
const selected = states.includes('selected');
|
||||
return html`
|
||||
<div
|
||||
class="row ${selected ? 'selected' : ''}"
|
||||
style="--depth: ${depth}"
|
||||
@click=${(e) => tree.dispatchEvent(new CustomEvent('node-click', { detail: { node, path, originalEvent: e }, bubbles: true, composed: true, cancelable: true }))}
|
||||
>
|
||||
<div class="indent"></div>
|
||||
${hasChildren
|
||||
? html`<tp-icon class="icon" .icon=${TpTreeNav.chevron}></tp-icon>`
|
||||
: html`<span class="icon" aria-hidden="true"></span>`}
|
||||
<tp-icon class="icon" .icon=${tree._resolveIcon(node.icon)}></tp-icon>
|
||||
<div class="label">${node.label}</div>
|
||||
</div>
|
||||
`;
|
||||
};
|
||||
|
||||
// Listen to actions (toggle, context menu items, etc.)
|
||||
// simple toggle handler
|
||||
const targetPath = (path) => path.join('/');
|
||||
tree.addEventListener('node-action', (e) => {
|
||||
const { action, node, path } = e.detail;
|
||||
if (action === 'toggle') {
|
||||
// Parent mutates data: flip expanded state and reassign roots
|
||||
const next = tree.applyStateIf('expanded', (n, p) => p.join('/') === path.join('/'));
|
||||
tree.roots = next;
|
||||
}
|
||||
if (e.detail.action !== 'toggle') return;
|
||||
const target = targetPath(e.detail.path);
|
||||
tree.roots = tree.applyStateIf('expanded', (_n, p) => targetPath(p) === target);
|
||||
});
|
||||
```
|
||||
|
||||
## Building higher-level trees
|
||||
Wrap `tp-tree-nav` in a specialized component (e.g., file explorer) that:
|
||||
- Tracks expansion/selection state on nodes.
|
||||
- Supplies icons per node type via `renderNode` or `icon` strings.
|
||||
- Defines default/context actions relevant to the domain.
|
||||
- Handles action events to mutate the source data and pass updated `roots` back.
|
||||
## Two ways to use it
|
||||
|
||||
### A) Wrap directly (keep tp-tree-nav “dumb”)
|
||||
- Manage all state yourself; set `roots` and optional `defaultActions`/`actions`.
|
||||
- Listen to `node-action` (chevron/double-click toggles, inline actions, context actions) and `node-click`, mutate your data, then reassign `roots`.
|
||||
- Use `renderNode` for custom rows; `renderEmpty` for empty states.
|
||||
- Use helpers (`applyStateIf`, `clearState`, `getNodesWithState`) for immutable transforms/queries.
|
||||
|
||||
### B) Extend tp-tree-nav (add opinionated behavior)
|
||||
Leverage managed mode and hooks in a subclass:
|
||||
|
||||
```js
|
||||
import { TpTreeNav } from './tp-tree-nav.js';
|
||||
|
||||
class MyTree extends TpTreeNav {
|
||||
constructor() {
|
||||
super();
|
||||
this.manageState = true; // base tracks expand/select
|
||||
this.autoExpandNew = false; // set true to auto-expand unseen paths
|
||||
this.selectionState = 'selected'; // state name for selection
|
||||
this.expandOnDoubleClick = true; // toggle expand via double-click
|
||||
this.multiSelect = false; // enable multi-select if needed
|
||||
this.showActions = true; // render inline actions when present
|
||||
this.renderEmpty = () => html`<div class="empty">No items</div>`;
|
||||
}
|
||||
|
||||
set data(items) {
|
||||
this.items = items; // raw items with slug/label/icon/children/actions
|
||||
}
|
||||
|
||||
_renderRow(item, meta) {
|
||||
const { node } = item;
|
||||
const selected = meta.states.includes(this.selectionState);
|
||||
return html`
|
||||
<div
|
||||
class="row ${selected ? 'selected' : ''}"
|
||||
style="--depth:${meta.depth}"
|
||||
@click=${(e) => this._onRowClick(item, e)}
|
||||
>
|
||||
<div class="indent"></div>
|
||||
<div
|
||||
class="chevron-btn ${meta.expanded ? 'expanded' : ''}"
|
||||
?hidden=${!meta.hasChildren}
|
||||
@click=${(e) => this._onChevronClick(item, e)}
|
||||
>
|
||||
<tp-icon class="icon" .icon=${TpTreeNav.chevron}></tp-icon>
|
||||
</div>
|
||||
<tp-icon class="icon" .icon=${this._resolveIcon(node.icon)}></tp-icon>
|
||||
<div class="label">${node.label}</div>
|
||||
${node.actions?.length
|
||||
? html`<div class="actions">${node.actions.map((action) => html`
|
||||
<tp-icon
|
||||
class="action-icon"
|
||||
.icon=${this._resolveIcon(action.icon)}
|
||||
@click=${(e) => this._onInlineAction(item, action, e)}
|
||||
></tp-icon>
|
||||
`)}</div>`
|
||||
: null}
|
||||
</div>
|
||||
`;
|
||||
}
|
||||
}
|
||||
|
||||
customElements.define('my-tree', MyTree);
|
||||
```
|
||||
|
||||
### Key props when extending
|
||||
- `items`: raw data (`slug`, `label`, `icon`, `children`, optional `actions`).
|
||||
- `manageState`: base manages expand/select when true.
|
||||
- `expandedPaths` / `selectedPaths`: arrays or Sets to seed/restore state.
|
||||
- `selectionState`: state name for selection (default `'selected'`).
|
||||
- `multiSelect`: allow multiple selections.
|
||||
- `expandOnDoubleClick`: toggle expansion on double-click (uses click detail).
|
||||
- `autoExpandNew`: auto-expand unseen nodes when first seen (default false).
|
||||
- `applyStates`: `(node, pathParts, states) => extraStates[]` to add custom states.
|
||||
- `applySelection`: override selection logic `(node, pathParts, states, originalEvent) => nextStates`.
|
||||
- `applyToggle`: override expand/collapse logic `(node, pathParts, states, originalEvent) => nextStates`.
|
||||
- `showActions`: render inline actions if provided.
|
||||
- `renderEmpty`: custom empty renderer.
|
||||
|
||||
### Events (both modes)
|
||||
- `node-click`: emitted on row click.
|
||||
- `node-action`: emitted for toggles (`action: 'toggle'`, source chevron/double-click), inline actions, and context menu actions.
|
||||
- `node-context`: before showing context menu; `preventDefault` to cancel.
|
||||
|
||||
### Helpers (both modes)
|
||||
- `TpTreeNav.buildTree(items, { expandedPaths, selectedPaths, selectionState, applyStates, knownPaths, autoExpandNew })` — pure helper used by managed mode; can be used externally.
|
||||
- `applyStateIf(state, predicate)`, `clearState(state)`, `getNodesWithState(state)` for immutable transforms/queries.
|
||||
|
||||
### Data shape
|
||||
- `slug` (unique per sibling), `label`, `icon` (string key or icon data), `children` (array), optional `actions` (`{ action, label?, icon?, tooltip? }`).
|
||||
|
||||
Reference in New Issue
Block a user