@jungherz-de/notionkit-elements 1.0.0

package/src/components/page/nk-template-btn.js

@@ -0,0 +1,42 @@
+import { NkElement } from '../../base.js';
+
+// <nk-template-btn icon="📅" value="week-plan">Insert week plan</nk-template-btn>
+// → <button class="nk-template-btn">📅 Insert week plan</button>
+class NkTemplateBtn extends NkElement {
+  static get observedAttributes() { return ['icon', 'value', 'disabled']; }
+
+  render() {
+    this._btn = this.createElement('button', ['nk-template-btn'], { type: 'button' });
+    // One flex item: "📅 Insert week plan" is a single text run in the class
+    // markup, so icon, space and label must not become separate flex items.
+    const run = document.createElement('span');
+    this._icon = document.createElement('span');
+    this._space = document.createTextNode(' ');
+    run.append(this._icon, this._space, document.createElement('slot'));
+    this._btn.appendChild(run);
+    this._wrapper.appendChild(this._btn);
+    this._sync();
+  }
+
+  _sync() {
+    const icon = this.getAttribute('icon');
+    this._icon.textContent = icon || '';
+    this._space.data = icon ? ' ' : '';
+    this._btn.disabled = this.getBoolAttr('disabled');
+  }
+
+  setupEvents() {
+    this._onClick = () => this.emit('nk-select', { value: this.value, label: this.textContent.trim() });
+    this._btn.addEventListener('click', this._onClick);
+  }
+
+  teardownEvents() { this._btn?.removeEventListener('click', this._onClick); }
+  onAttributeChanged() { this._sync(); }
+  focus(o) { this._btn?.focus(o); }
+
+  get value() { return this.getAttribute('value') ?? this.textContent.trim(); }
+  set value(v) { this.setAttribute('value', v); }
+}
+
+customElements.define('nk-template-btn', NkTemplateBtn);
+export { NkTemplateBtn };

package/src/components/shell/nk-app.js

@@ -0,0 +1,22 @@
+import { NkElement } from '../../base.js';
+
+// <nk-app>
+//   <nk-sidebar slot="sidebar">…</nk-sidebar>
+//   <nk-topbar>…</nk-topbar>
+//   <nk-page>…</nk-page>
+// </nk-app>
+// → <div class="nk-app"><aside class="nk-sidebar">…</aside><main class="nk-main">…</main></div>
+// The outermost element of a workspace app: a full-height flex row.
+class NkApp extends NkElement {
+  render() {
+    const app = this.createElement('div', ['nk-app']);
+    app.appendChild(this.createElement('slot', [], { name: 'sidebar' }));
+    const main = this.createElement('main', ['nk-main']);
+    main.appendChild(document.createElement('slot'));
+    app.appendChild(main);
+    this._wrapper.appendChild(app);
+  }
+}
+
+customElements.define('nk-app', NkApp);
+export { NkApp };

package/src/components/shell/nk-breadcrumb.js

@@ -0,0 +1,77 @@
+import { NkElement } from '../../base.js';
+
+// <nk-breadcrumb>
+//   <a href="/overview">📊 Project overview</a>
+//   <span>🚀 NotionKit MVP</span>
+// </nk-breadcrumb>
+// → <nav class="nk-breadcrumb"><a class="crumb">…</a><span class="sep">/</span><span class="crumb current">…</span></nav>
+//
+// The children are *cloned* into the shadow tree so the separators can be
+// interleaved and `.crumb:hover` (no ::slotted twin) applies. A
+// MutationObserver keeps the copy in step. Clicking a clone fires nk-select
+// and, unless prevented, forwards the click to the original – so an <a>
+// navigates exactly once and framework listeners see it.
+class NkBreadcrumb extends NkElement {
+  static get observedAttributes() { return ['separator']; }
+  static get observesLightDom() { return true; }
+
+  render() {
+    this._nav = this.createElement('nav', ['nk-breadcrumb'], { 'aria-label': 'Breadcrumb' });
+    this._wrapper.appendChild(this._nav);
+    this.projectLightDom();
+  }
+
+  projectLightDom() {
+    if (!this._nav) return;
+    const originals = [...this.children];
+    const sep = this.getAttribute('separator') ?? '/';
+    const signature = originals.map(o => o.outerHTML).join('') + sep;
+    if (signature === this._signature) return;
+    this._signature = signature;
+    this._nav.innerHTML = '';
+    const explicitCurrent = originals.some(o => o.hasAttribute('current') || o.classList.contains('current'));
+    originals.forEach((original, i) => {
+      if (i > 0) {
+        const s = this.createElement('span', ['sep'], { 'aria-hidden': 'true' });
+        s.textContent = sep;
+        this._nav.appendChild(s);
+      }
+      const clone = original.cloneNode(true);
+      clone.removeAttribute('slot');
+      clone.classList.add('crumb');
+      const current = explicitCurrent ? (original.hasAttribute('current') || original.classList.contains('current')) : i === originals.length - 1;
+      clone.classList.toggle('current', current);
+      if (current) clone.setAttribute('aria-current', 'page');
+      clone.dataset.index = i;
+      this._nav.appendChild(clone);
+    });
+  }
+
+  setupEvents() {
+    this._onClick = (e) => {
+      const clone = e.target.closest('.crumb');
+      if (!clone) return;
+      e.preventDefault();
+      const index = Number(clone.dataset.index);
+      // Look the original up at click time: a framework may have replaced it.
+      const original = this.children[index];
+      const ok = this.emit('nk-select', {
+        index, label: clone.textContent.trim(), href: original?.getAttribute('href') ?? null,
+        value: original?.dataset.value ?? original?.getAttribute('href') ?? clone.textContent.trim(),
+        current: clone.classList.contains('current'),
+      });
+      if (ok) original?.click();
+    };
+    this._nav.addEventListener('click', this._onClick);
+  }
+
+  teardownEvents() { this._nav?.removeEventListener('click', this._onClick); }
+
+  onAttributeChanged() { this.projectLightDom(); }
+
+  get separator() { return this.getAttribute('separator') ?? '/'; }
+  set separator(v) { this.setAttribute('separator', v); }
+}
+
+customElements.define('nk-breadcrumb', NkBreadcrumb);
+export { NkBreadcrumb };

package/src/components/shell/nk-section-label.js

@@ -0,0 +1,41 @@
+import { NkElement } from '../../base.js';
+
+// <nk-section-label addable>Favourites</nk-section-label>
+// → <div class="nk-section-label">Favourites <span class="plus">＋</span></div>
+// The ＋ appears on hover (a hover-parent rule, so it lives in the same tree)
+// and fires nk-action { action: 'add' }.
+class NkSectionLabel extends NkElement {
+  static get observedAttributes() { return ['label', 'addable']; }
+
+  render() {
+    this._box = this.createElement('div', ['nk-section-label']);
+    this._text = document.createElement('span');
+    this._text.appendChild(document.createElement('slot'));
+    this._plus = this.createElement('span', ['plus'], { role: 'button', title: '+' });
+    this._plus.textContent = '＋';
+    this._box.append(this._text, this._plus);
+    this._wrapper.appendChild(this._box);
+    this._sync();
+  }
+
+  _sync() {
+    const label = this.getAttribute('label');
+    if (label !== null) this._text.textContent = label;
+    this._plus.style.display = this.getBoolAttr('addable') ? '' : 'none';
+  }
+
+  setupEvents() {
+    this._onPlus = (e) => { e.stopPropagation(); this.emit('nk-action', { action: 'add' }); };
+    this._plus.addEventListener('click', this._onPlus);
+  }
+
+  teardownEvents() { this._plus?.removeEventListener('click', this._onPlus); }
+
+  onAttributeChanged() { this._sync(); }
+
+  get addable() { return this.getBoolAttr('addable'); }
+  set addable(v) { this.setBoolAttr('addable', v); }
+}
+
+customElements.define('nk-section-label', NkSectionLabel);
+export { NkSectionLabel };

package/src/components/shell/nk-sidebar.js

@@ -0,0 +1,80 @@
+import { NkElement } from '../../base.js';
+
+// <nk-sidebar slot="sidebar">
+//   <nk-workspace-switcher slot="workspace" name="Acme"></nk-workspace-switcher>
+//   <nk-tree>…</nk-tree>
+//   <nk-tree-item slot="footer" icon="⚙️">Settings</nk-tree-item>
+// </nk-sidebar>
+// → <aside class="nk-sidebar"><div class="nk-workspace">…</div>
+//     <div class="nk-sidebar-scroll">…</div><div class="nk-sidebar-footer">…</div></aside>
+//
+// The host is display:contents so the <aside> is a direct flex child of
+// .nk-app, exactly like the class markup. Below 860px notionkit.css hides the
+// aside; `open` brings it back as an off-canvas drawer (position only – the
+// look is still the stylesheet's).
+const drawerSheet = new CSSStyleSheet();
+drawerSheet.replaceSync(`
+  @media (max-width: 860px) {
+    :host([open]) .nk-sidebar { display: flex; position: fixed; inset: 0 auto 0 0; z-index: 60; }
+    :host([open]) .nk-sidebar-backdrop { display: block; }
+  }
+  .nk-sidebar-backdrop { display: none; position: fixed; inset: 0; z-index: 59; background: var(--nk-scrim-soft); }
+`);
+
+class NkSidebar extends NkElement {
+  static get hostStyles() { return drawerSheet; }
+  static get observedAttributes() { return ['open']; }
+
+  render() {
+    this._backdrop = this.createElement('div', ['nk-sidebar-backdrop']);
+    this._aside = this.createElement('aside', ['nk-sidebar']);
+    this._aside.appendChild(this.createElement('slot', [], { name: 'workspace' }));
+    const scroll = this.createElement('div', ['nk-sidebar-scroll']);
+    scroll.appendChild(document.createElement('slot'));
+    this._aside.appendChild(scroll);
+    this._footer = this.createElement('div', ['nk-sidebar-footer']);
+    this._footerSlot = this.createElement('slot', [], { name: 'footer' });
+    this._footer.appendChild(this._footerSlot);
+    this._aside.appendChild(this._footer);
+    this._wrapper.appendChild(this._backdrop);
+    this._wrapper.appendChild(this._aside);
+    this._syncFooter();
+  }
+
+  _syncFooter() {
+    const nodes = this._footerSlot.assignedElements();
+    // The footer box carries padding and a border; only render it when used.
+    this._footer.style.display = nodes.length ? '' : 'none';
+    // Footer rows are 26px in the class version (.nk-sidebar-footer .nk-tree-item).
+    for (const el of nodes) if (el.localName === 'nk-tree-item') el.setAttribute('compact', '');
+  }
+
+  setupEvents() {
+    this._onSlot = () => this._syncFooter();
+    this._onBackdrop = () => this.close();
+    this._onKey = (e) => { if (e.key === 'Escape' && this.getBoolAttr('open')) this.close(); };
+    this._footerSlot.addEventListener('slotchange', this._onSlot);
+    this._backdrop.addEventListener('click', this._onBackdrop);
+    document.addEventListener('keydown', this._onKey);
+  }
+
+  teardownEvents() {
+    this._footerSlot?.removeEventListener('slotchange', this._onSlot);
+    this._backdrop?.removeEventListener('click', this._onBackdrop);
+    document.removeEventListener('keydown', this._onKey);
+  }
+
+  onAttributeChanged(name) {
+    if (name === 'open') this.emit('nk-toggle', { open: this.getBoolAttr('open') });
+  }
+
+  show() { this.setBoolAttr('open', true); }
+  close() { this.setBoolAttr('open', false); }
+  toggle() { this.setBoolAttr('open', !this.getBoolAttr('open')); }
+
+  get open() { return this.getBoolAttr('open'); }
+  set open(v) { this.setBoolAttr('open', v); }
+}
+
+customElements.define('nk-sidebar', NkSidebar);
+export { NkSidebar };

package/src/components/shell/nk-theme-toggle.js

@@ -0,0 +1,66 @@
+import { NkElement, getCurrentTheme } from '../../base.js';
+
+// <nk-theme-toggle slot="actions"></nk-theme-toggle>
+// → <button class="nk-topbar-btn nk-theme-toggle">🌙</button>
+// Flips data-theme on <html> (the only theme source), remembers the choice in
+// localStorage (`storage-key`, default nk-theme), applies a stored or
+// system preference on first connect when <html> carries no theme yet, and
+// accepts postMessage({ nkTheme }) from a parent page (the landing page's
+// embedded demo uses that).
+class NkThemeToggle extends NkElement {
+  static get observedAttributes() { return ['storage-key', 'title'];
+
+  }
+
+  render() {
+    this._btn = this.createElement('button', ['nk-topbar-btn', 'nk-theme-toggle'], { type: 'button' });
+    this._btn.title = this.getAttribute('title') || 'Toggle light / dark';
+    this._wrapper.appendChild(this._btn);
+    const root = document.documentElement;
+    let stored = null;
+    try { stored = localStorage.getItem(this.storageKey); } catch {}
+    if (stored === 'light' || stored === 'dark') root.setAttribute('data-theme', stored);
+    else if (!root.hasAttribute('data-theme')) root.setAttribute('data-theme', matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
+    this._syncGlyph();
+  }
+
+  _syncGlyph() {
+    if (this._btn) this._btn.textContent = getCurrentTheme() === 'dark' ? '☀️' : '🌙';
+  }
+
+  _syncTheme(theme) {
+    super._syncTheme(theme);
+    this._syncGlyph();
+  }
+
+  setupEvents() {
+    this._onClick = () => this.apply(getCurrentTheme() === 'dark' ? 'light' : 'dark');
+    this._onMessage = (e) => { const t = e.data?.nkTheme; if (t === 'light' || t === 'dark') this.apply(t); };
+    this._btn.addEventListener('click', this._onClick);
+    window.addEventListener('message', this._onMessage);
+  }
+
+  teardownEvents() {
+    this._btn?.removeEventListener('click', this._onClick);
+    window.removeEventListener('message', this._onMessage);
+  }
+
+  onAttributeChanged(name) {
+    if (name === 'title' && this._btn) this._btn.title = this.getAttribute('title') || 'Toggle light / dark';
+  }
+
+  /** Sets the theme on <html>, persists it and reports it. */
+  apply(theme) {
+    document.documentElement.setAttribute('data-theme', theme);
+    try { localStorage.setItem(this.storageKey, theme); } catch {}
+    this._syncGlyph();
+    this.emit('nk-change', { value: theme });
+  }
+
+  get storageKey() { return this.getAttribute('storage-key') || 'nk-theme'; }
+  get value() { return getCurrentTheme(); }
+  set value(v) { this.apply(v); }
+}
+
+customElements.define('nk-theme-toggle', NkThemeToggle);
+export { NkThemeToggle };

package/src/components/shell/nk-topbar.js

@@ -0,0 +1,23 @@
+import { NkElement } from '../../base.js';
+
+// <nk-topbar>
+//   <nk-breadcrumb>…</nk-breadcrumb>
+//   <nk-btn slot="actions" variant="share">Share</nk-btn>
+//   <nk-theme-toggle slot="actions"></nk-theme-toggle>
+// </nk-topbar>
+// → <div class="nk-topbar">…<div class="nk-topbar-actions">…</div></div>
+// display:contents host, so the bar is a direct flex child of .nk-main.
+class NkTopbar extends NkElement {
+
+  render() {
+    const bar = this.createElement('div', ['nk-topbar']);
+    bar.appendChild(document.createElement('slot'));
+    const actions = this.createElement('div', ['nk-topbar-actions']);
+    actions.appendChild(this.createElement('slot', [], { name: 'actions' }));
+    bar.appendChild(actions);
+    this._wrapper.appendChild(bar);
+  }
+}
+
+customElements.define('nk-topbar', NkTopbar);
+export { NkTopbar };

package/src/components/shell/nk-tree-item.js

@@ -0,0 +1,154 @@
+import { NkElement } from '../../base.js';
+
+// <nk-tree-item icon="📊" value="overview" open>
+//   Project overview
+//   <nk-tree-item icon="🚀" value="mvp" active>NotionKit MVP</nk-tree-item>
+// </nk-tree-item>
+//
+// → <div class="nk-tree-item active"><span class="nk-toggle-arrow open">▸</span>
+//     <span class="icon">📊</span><span class="label">…</span>
+//     <span class="actions"><span>＋</span><span>⋯</span></span></div>
+//   <div class="nk-tree-children">…</div>
+//
+// Both halves – the row and the .nk-tree-children box that must be its next
+// sibling – are rendered here. Slots are assigned manually: text becomes the
+// label, nested <nk-tree-item>s become the children, `slot="icon"` /
+// `slot="end"` nodes go where they say. The hover actions are shadow-internal
+// (`.nk-tree-item:hover .actions` is a hover-parent rule) and report through
+// nk-action.
+class NkTreeItem extends NkElement {
+  static get slotAssignment() { return 'manual'; }
+  static get observedAttributes() { return ['label', 'icon', 'value', 'href', 'active', 'open', 'compact', 'no-actions']; }
+
+  render() {
+    this._row = this.createElement('div', ['nk-tree-item'], { role: 'treeitem', tabindex: '-1' });
+    this._arrow = this.createElement('span', ['nk-toggle-arrow'], { 'aria-hidden': 'true' });
+    this._arrow.textContent = '▸';
+    this._iconSlot = this.createElement('slot', [], { name: 'icon' });
+    this._icon = this.createElement('span', ['icon']);
+    this._iconSlot.appendChild(this._icon);
+    this._label = this.createElement('span', ['label']);
+    this._labelSlot = this.createElement('slot', [], { name: 'label' });
+    this._labelText = document.createTextNode('');
+    this._labelSlot.appendChild(this._labelText);
+    this._label.appendChild(this._labelSlot);
+    this._actions = this.createElement('span', ['actions']);
+    for (const [action, glyph, title] of [['add', '＋', 'Add'], ['more', '⋯', 'More']]) {
+      const b = this.createElement('span', [], { 'data-action': action, role: 'button', title });
+      b.textContent = glyph;
+      this._actions.appendChild(b);
+    }
+    this._endSlot = this.createElement('slot', [], { name: 'end' });
+    this._row.append(this._arrow, this._iconSlot, this._label, this._actions, this._endSlot);
+    this._children = this.createElement('div', ['nk-tree-children'], { role: 'group' });
+    this._childSlot = this.createElement('slot', [], { name: 'children' });
+    this._children.appendChild(this._childSlot);
+    this._wrapper.append(this._row, this._children);
+    this._sync();
+    this.closest('nk-tree')?.requestSync?.();
+  }
+
+  /** Routes light-DOM nodes: nested items → children, slot="icon"/"end" → there, the rest → label. */
+  assignSlots() {
+    if (!this._row) return;
+    const icon = [], end = [], children = [], label = [];
+    for (const node of this.childNodes) {
+      if (node.nodeType === Node.ELEMENT_NODE) {
+        const slot = node.getAttribute('slot');
+        if (slot === 'icon') icon.push(node);
+        else if (slot === 'end') end.push(node);
+        else if (node.localName === 'nk-tree-item') children.push(node);
+        else label.push(node);
+      } else if (node.nodeType === Node.TEXT_NODE && node.data.trim()) {
+        label.push(node);
+      }
+    }
+    this._iconSlot.assign(...icon);
+    this._endSlot.assign(...end);
+    this._childSlot.assign(...children);
+    this._labelSlot.assign(...(this.hasAttribute('label') ? [] : label));
+    this._hasChildren = children.length > 0;
+    this._hasEnd = end.length > 0;
+    this._sync();
+  }
+
+  _sync() {
+    const active = this.getBoolAttr('active'), open = this.getBoolAttr('open');
+    this._row.classList.toggle('active', active);
+    this._row.classList.toggle('compact', this.getBoolAttr('compact'));
+    this._row.setAttribute('aria-selected', active ? 'true' : 'false');
+    this._arrow.classList.toggle('open', open);
+    this._arrow.style.display = this._hasChildren ? '' : 'none';
+    if (this._hasChildren) this._row.setAttribute('aria-expanded', open ? 'true' : 'false');
+    else this._row.removeAttribute('aria-expanded');
+    this._children.classList.toggle('collapsed', !open || !this._hasChildren);
+    this._icon.textContent = this.getAttribute('icon') || '';
+    this._icon.style.display = this.getAttribute('icon') ? '' : 'none';
+    this._labelText.data = this.getAttribute('label') || '';
+    // .actions is display:none until hover (a hover-parent rule); `hidden`
+    // would lose to that rule, so the block is detached instead.
+    const wantActions = !this.getBoolAttr('no-actions') && !this._hasEnd;
+    if (wantActions && !this._actions.isConnected) this._row.insertBefore(this._actions, this._endSlot);
+    if (!wantActions && this._actions.isConnected) this._actions.remove();
+    const href = this.getAttribute('href');
+    href ? this._row.setAttribute('data-href', href) : this._row.removeAttribute('data-href');
+  }
+
+  setupEvents() {
+    this._onRowClick = (e) => {
+      const action = e.target.closest?.('[data-action]');
+      if (action) { e.stopPropagation(); this.emit('nk-action', { action: action.dataset.action, value: this.value, label: this.label }); return; }
+      if (e.target === this._arrow || this._arrow.contains(e.target)) { e.stopPropagation(); this.toggle(); return; }
+      this.select();
+    };
+    this._onKey = (e) => {
+      if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); this.select(); }
+    };
+    this._row.addEventListener('click', this._onRowClick);
+    this._row.addEventListener('keydown', this._onKey);
+  }
+
+  teardownEvents() {
+    this._row?.removeEventListener('click', this._onRowClick);
+    this._row?.removeEventListener('keydown', this._onKey);
+  }
+
+  onAttributeChanged(name) {
+    if (name === 'label') this.assignSlots();
+    else this._sync();
+    if (name === 'open') this.emit('nk-toggle', { open: this.getBoolAttr('open'), value: this.value });
+  }
+
+  /** Fires nk-select; a listener may preventDefault to keep the item from becoming active. */
+  select() {
+    const ok = this.emit('nk-select', { value: this.value, label: this.label, href: this.getAttribute('href'), item: this });
+    if (!ok) return;
+    const tree = this.closest('nk-tree');
+    if (tree) tree.setActive(this);
+    else this.setBoolAttr('active', true);
+    if (this.getAttribute('href')) location.assign(this.getAttribute('href'));
+  }
+
+  toggle() { this.setBoolAttr('open', !this.getBoolAttr('open')); }
+  focus(options) { this._row?.focus(options); }
+  /** Roving tabindex, managed by <nk-tree>. */
+  setTabbable(v) { if (this._row) this._row.tabIndex = v ? 0 : -1; }
+  get tabbable() { return this._row?.tabIndex === 0; }
+  get hasChildren() { return !!this._hasChildren; }
+
+  get label() { return this.getAttribute('label') ?? this._labelSlot?.assignedNodes().map(n => n.textContent).join('').trim() ?? ''; }
+  set label(v) { this.setAttribute('label', v); }
+  get value() { return this.getAttribute('value') ?? this.label; }
+  set value(v) { this.setAttribute('value', v); }
+  get icon() { return this.getAttribute('icon'); }
+  set icon(v) { v == null ? this.removeAttribute('icon') : this.setAttribute('icon', v); }
+  get active() { return this.getBoolAttr('active'); }
+  set active(v) { this.setBoolAttr('active', v); }
+  get open() { return this.getBoolAttr('open'); }
+  set open(v) { this.setBoolAttr('open', v); }
+  get compact() { return this.getBoolAttr('compact'); }
+  set compact(v) { this.setBoolAttr('compact', v); }
+}
+
+customElements.define('nk-tree-item', NkTreeItem);
+export { NkTreeItem };

package/src/components/shell/nk-tree.js

@@ -0,0 +1,122 @@
+import { NkElement } from '../../base.js';
+
+// <nk-tree>
+//   <nk-section-label addable>Favourites</nk-section-label>
+//   <nk-tree-item icon="📊" open>Project overview
+//     <nk-tree-item icon="🚀" active>NotionKit MVP</nk-tree-item>
+//   </nk-tree-item>
+// </nk-tree>
+//
+// A container for tree items: keeps a single `active` item (listening to
+// nk-select from any depth), gives the group one tab stop with arrow-key
+// navigation, and can render items from data:
+//   tree.data = [{ label, icon, value, href, open, active, children: [...] }]
+const KEYS = new Set(['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End']);
+
+class NkTree extends NkElement {
+  static get observedAttributes() { return ['manual']; }
+
+  render() {
+    const box = this.createElement('div', [], { role: 'tree' });
+    box.appendChild(document.createElement('slot'));
+    this._wrapper.appendChild(box);
+    this._box = box;
+  }
+
+  /** Makes `item` the single active item (called by the item after nk-select was not cancelled). */
+  setActive(item) {
+    if (this.getBoolAttr('manual')) return;
+    for (const other of this.querySelectorAll('nk-tree-item[active]')) if (other !== item) other.removeAttribute('active');
+    item.setAttribute('active', '');
+    this._syncTabIndex(item);
+  }
+
+  setupEvents() {
+    this._onKey = (e) => {
+      if (!KEYS.has(e.key) || e.ctrlKey || e.metaKey || e.altKey) return;
+      const item = e.target.closest?.('nk-tree-item');
+      if (!item) return;
+      const visible = this.visibleItems();
+      const i = visible.indexOf(item);
+      if (i < 0) return;
+      let next = null;
+      switch (e.key) {
+        case 'ArrowDown': next = visible[i + 1]; break;
+        case 'ArrowUp': next = visible[i - 1]; break;
+        case 'Home': next = visible[0]; break;
+        case 'End': next = visible[visible.length - 1]; break;
+        case 'ArrowRight':
+          if (item.hasChildren && !item.open) item.open = true;
+          else if (item.hasChildren) next = item.querySelector('nk-tree-item');
+          break;
+        case 'ArrowLeft':
+          if (item.hasChildren && item.open) item.open = false;
+          else next = item.parentElement?.closest('nk-tree-item');
+          break;
+      }
+      e.preventDefault();
+      if (next) { this._syncTabIndex(next); next.focus(); }
+    };
+    this._onSlot = () => this._syncTabIndex();
+    this.addEventListener('keydown', this._onKey);
+    this._box.querySelector('slot').addEventListener('slotchange', this._onSlot);
+    this._syncTabIndex();
+  }
+
+  teardownEvents() {
+    this.removeEventListener('keydown', this._onKey);
+    this._box?.querySelector('slot').removeEventListener('slotchange', this._onSlot);
+  }
+
+  /** Items whose every ancestor item inside this tree is open – i.e. rendered. */
+  visibleItems() {
+    return [...this.querySelectorAll('nk-tree-item')].filter(item => {
+      for (let p = item.parentElement?.closest('nk-tree-item'); p && this.contains(p); p = p.parentElement?.closest('nk-tree-item')) {
+        if (!p.open) return false;
+      }
+      return true;
+    });
+  }
+
+  /** Items upgrade after the tree; each one asks for a resync once rendered. */
+  requestSync() {
+    if (this._syncQueued) return;
+    this._syncQueued = true;
+    queueMicrotask(() => { this._syncQueued = false; this._syncTabIndex(); });
+  }
+
+  _syncTabIndex(focusable) {
+    const items = [...this.querySelectorAll('nk-tree-item')];
+    if (!items.length) return;
+    const visible = this.visibleItems();
+    const target = focusable || visible.find(i => i.active) || visible[0];
+    // A method call, not a property write: assigning a property to an element
+    // that has not been upgraded yet would create an own property that shadows
+    // the accessor forever.
+    for (const item of items) item.setTabbable?.(item === target);
+  }
+
+  /** Renders items from data into the light DOM (replacing existing items). */
+  set data(list) {
+    this._data = list;
+    const build = (nodes) => nodes.map(n => {
+      const item = document.createElement('nk-tree-item');
+      if (n.icon) item.setAttribute('icon', n.icon);
+      if (n.value != null) item.setAttribute('value', n.value);
+      if (n.href) item.setAttribute('href', n.href);
+      if (n.open) item.setAttribute('open', '');
+      if (n.active) item.setAttribute('active', '');
+      item.append(document.createTextNode(n.label ?? ''), ...build(n.children || []));
+      return item;
+    });
+    for (const old of this.querySelectorAll(':scope > nk-tree-item')) old.remove();
+    this.append(...build(list || []));
+  }
+  get data() { return this._data; }
+
+  get activeItem() { return this.querySelector('nk-tree-item[active]'); }
+  get value() { return this.activeItem?.value ?? null; }
+}
+
+customElements.define('nk-tree', NkTree);
+export { NkTree };