@jungherz-de/notionkit-elements 1.9.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jungherz-de/notionkit-elements",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Vanilla JavaScript Web Components wrapping the NotionKit CSS foundation – <nk-*> custom elements with Shadow DOM, automatic theme sync and native form participation.",
   "license": "MIT",
   "author": "Jungherz GmbH <info@jungherz.com> (https://www.jungherz.com)",
@@ -59,10 +59,10 @@
     "dark-mode"
   ],
   "peerDependencies": {
-    "@jungherz-de/notionkit": ">=1.9.0"
+    "@jungherz-de/notionkit": ">=1.10.0"
   },
   "devDependencies": {
-    "@jungherz-de/notionkit": "^1.9.0",
+    "@jungherz-de/notionkit": "^1.10.0",
     "@playwright/test": "^1.50.0",
     "@rollup/plugin-node-resolve": "^15.0.0",
     "@rollup/plugin-terser": "^0.4.0",

package/src/components/forms/nk-btn.js

@@ -5,7 +5,8 @@ import { NkElement } from '../../base.js';
 // <nk-btn variant="topbar">⭐</nk-btn>  →  <button class="nk-topbar-btn">
 // <nk-btn variant="tool" active>Filter</nk-btn>  →  <button class="nk-db-tool active">  (slot="tools" of nk-database)
 // <nk-btn variant="sidebar" aria-label="Menu">☰</nk-btn>  →  <button class="nk-topbar-btn nk-sidebar-toggle">:
-//   shown on phones only, it opens the page's <nk-sidebar> as a drawer.
+//   on a phone it opens the page's <nk-sidebar> as a drawer; on the desktop
+//   it shows while that sidebar is collapsed (.collapsed) and expands it.
 //
 // Modifier classes become attributes. A slotted <svg> is sized by the
 // `.nk-btn ::slotted(svg)` twin; pass the icon itself, never wrapped.
@@ -51,11 +52,17 @@ class NkBtn extends NkElement {
 
   /** The sidebar the ☰ opens: the one in its own app, else the page's. */
   _sidebar() { return this.closest('nk-app')?.querySelector('nk-sidebar') ?? document.querySelector('nk-sidebar'); }
+  _sidebarCollapsed() { return this.getAttribute('variant') === 'sidebar' && !!this._sidebar()?.hasAttribute('collapsed'); }
 
   setupEvents() {
     this._onClick = (e) => {
       if (this.getBoolAttr('disabled')) { e.preventDefault(); e.stopPropagation(); return; }
-      if (this.getAttribute('variant') === 'sidebar') { this._sidebar()?.toggle?.(); return; }
+      if (this.getAttribute('variant') === 'sidebar') {
+        const sidebar = this._sidebar();
+        if (sidebar?.hasAttribute('collapsed') && !matchMedia('(max-width: 860px)').matches) sidebar.expand?.();
+        else sidebar?.toggle?.();
+        return;
+      }
       // A button inside a shadow root is not a submit button of the outer
       // form; forward the intent to the form the host sits in.
       const type = this.getAttribute('type');
@@ -68,13 +75,20 @@ class NkBtn extends NkElement {
     this._onToggle = (e) => {
       if (this.getAttribute('variant') === 'sidebar' && e.target === this._sidebar()) this._btn.setAttribute('aria-expanded', e.detail.open ? 'true' : 'false');
     };
+    // On the desktop the ☰ shows while its sidebar is collapsed.
+    this._onCollapse = (e) => {
+      if (this.getAttribute('variant') === 'sidebar' && e.target === this._sidebar()) this._btn.classList.toggle('collapsed', e.detail.collapsed);
+    };
     this._btn.addEventListener('click', this._onClick);
     document.addEventListener('nk-toggle', this._onToggle);
+    document.addEventListener('nk-collapse', this._onCollapse);
+    if (this.getAttribute('variant') === 'sidebar') this._btn.className = this._computeClasses().join(' ');
   }
 
   teardownEvents() {
     this._btn?.removeEventListener('click', this._onClick);
     document.removeEventListener('nk-toggle', this._onToggle);
+    document.removeEventListener('nk-collapse', this._onCollapse);
   }
 
   onAttributeChanged(name) {
@@ -103,7 +117,7 @@ class NkBtn extends NkElement {
     const variant = this.getAttribute('variant');
     if (variant === 'topbar') return ['nk-topbar-btn'];
     if (variant === 'share') return ['nk-topbar-btn', 'nk-share-btn'];
-    if (variant === 'sidebar') return ['nk-topbar-btn', 'nk-sidebar-toggle'];
+    if (variant === 'sidebar') return this._sidebarCollapsed() ? ['nk-topbar-btn', 'nk-sidebar-toggle', 'collapsed'] : ['nk-topbar-btn', 'nk-sidebar-toggle'];
     if (variant === 'tool') return this.getBoolAttr('active') ? ['nk-db-tool', 'active'] : ['nk-db-tool'];
     const classes = ['nk-btn'];
     if (VARIANTS.includes(variant)) classes.push(variant);

package/src/components/overlays/nk-dialog.js

@@ -0,0 +1,148 @@
+import { NkElement } from '../../base.js';
+import { lockScroll, unlockScroll, inertOutside, firstFocusable, deepActiveElement } from '../../util/focus.js';
+
+// <nk-dialog id="trash" title="Move “Roadmap” to trash?" alert>
+//   The page and its sub-pages can be restored from Trash for 30 days.
+//   <nk-btn slot="actions" variant="secondary" value="">Cancel</nk-btn>
+//   <nk-btn slot="actions" variant="danger-solid" value="trash">Move to trash</nk-btn>
+// </nk-dialog>
+// → <div class="nk-dialog-backdrop open"><div class="nk-dialog" role="alertdialog">
+//     <div class="dl-title">…</div><div class="dl-body">…</div><div class="dl-actions">…</div></div></div>
+//
+// A question or a short form (NotionKit 1.10.0) with the contract of
+// <nk-modal> and <nk-sheet>: show(), close(), toggle(), nk-toggle; Escape –
+// captured, so it closes before a peek, a menu or a modal behind it – and
+// the backdrop close it; focus moves in, to an [autofocus] element or the
+// first field or button, and back out; the page behind is inert and
+// scroll-locked. It lies above the modal and the sheet, so a question can
+// come from either. 440px, `wide` 560px; below 860px a bottom sheet with the
+// buttons stacked, the confirming one on top.
+// A button in slot="actions" with a `value` closes it with that value; so
+// does the submit of a <form method="dialog"> inside, with its submitter's
+// value. Before it closes, nk-close { value } fires and can be cancelled –
+// the place to check an input dialog; Escape and the backdrop close with ''.
+// `returnValue` keeps the last value. `alert` makes it an alertdialog, named
+// and described by its title and text. `title` is the heading, never a
+// tooltip – see NkElement.takeTitle(). Put it directly under <body>.
+class NkDialog extends NkElement {
+  static get observedAttributes() { return ['open', 'title', 'wide', 'alert']; }
+
+  render() {
+    this.takeTitle();
+    this.returnValue = '';
+    this._backdrop = this.createElement('div', ['nk-dialog-backdrop']);
+    this._backdrop.inert = true;
+    this._box = this.createElement('div', ['nk-dialog'], { 'aria-modal': 'true', tabindex: '-1' });
+    this._heading = this.createElement('div', ['dl-title'], { id: 'title' });
+    const body = this.createElement('div', ['dl-body'], { id: 'body' });
+    body.appendChild(document.createElement('slot'));
+    this._actions = this.createElement('div', ['dl-actions']);
+    this._actionsSlot = this.createElement('slot', [], { name: 'actions' });
+    this._actions.appendChild(this._actionsSlot);
+    this._box.append(this._heading, body, this._actions);
+    this._backdrop.appendChild(this._box);
+    this._wrapper.appendChild(this._backdrop);
+    this._syncTitle();
+    this._syncMode();
+    this._syncOpen();
+  }
+
+  _syncTitle() {
+    const text = this._titleText || '';
+    this._heading.textContent = text;
+    this._heading.hidden = !text;
+    if (text) this._box.setAttribute('aria-labelledby', 'title');
+    else this._box.removeAttribute('aria-labelledby');
+  }
+
+  _syncMode() {
+    const alert = this.getBoolAttr('alert');
+    this._box.setAttribute('role', alert ? 'alertdialog' : 'dialog');
+    if (alert) this._box.setAttribute('aria-describedby', 'body'); else this._box.removeAttribute('aria-describedby');
+    this._box.classList.toggle('wide', this.getBoolAttr('wide'));
+  }
+
+  _syncOpen() {
+    const open = this.getBoolAttr('open');
+    this._backdrop.classList.toggle('open', open);
+    this._backdrop.inert = !open;
+    if (open === this._wasOpen) return;
+    this._wasOpen = open;
+    if (open) {
+      this._returnFocus = this._from ?? deepActiveElement();
+      this._from = null;
+      // An overlay behind – a modal – made this host inert; the dialog lifts that while it is open.
+      this._wasInert = this.inert;
+      this.inert = false;
+      lockScroll();
+      this._undoInert = inertOutside(this);
+      requestAnimationFrame(() => (this.querySelector('[autofocus]') || firstFocusable(this) || this._box).focus({ preventScroll: true }));
+    } else {
+      unlockScroll();
+      this._undoInert?.(); this._undoInert = null;
+      this.inert = this._wasInert;
+      const back = this._returnFocus;
+      this._returnFocus = null;
+      if (back?.isConnected && typeof back.focus === 'function') back.focus({ preventScroll: true });
+    }
+  }
+
+  setupEvents() {
+    this._onBackdrop = (e) => { if (e.target === this._backdrop) this.close(''); };
+    this._onKey = (e) => { if (e.key === 'Escape' && this.getBoolAttr('open')) { e.stopPropagation(); this.close(''); } };
+    // A button with a value closes it; a submit button is the form's.
+    this._onClick = (e) => {
+      const button = e.composedPath().find(n => n instanceof Element && n !== this && this.contains(n) && n.hasAttribute('value') && (n.localName === 'nk-btn' || n.localName === 'button'));
+      if (!button || button.getAttribute('type') === 'submit') return;
+      this.close(button.getAttribute('value'));
+    };
+    this._onSubmit = (e) => {
+      if ((e.target.getAttribute('method') || '').toLowerCase() !== 'dialog') return;
+      e.preventDefault();
+      this.close(e.submitter?.value || e.submitter?.getAttribute?.('value') || 'submit');
+    };
+    this._onSlot = () => { this._actions.hidden = !this._actionsSlot.assignedElements().length; };
+    this._backdrop.addEventListener('click', this._onBackdrop);
+    this.addEventListener('click', this._onClick);
+    this.addEventListener('submit', this._onSubmit);
+    this._actionsSlot.addEventListener('slotchange', this._onSlot);
+    document.addEventListener('keydown', this._onKey, true);
+    this._onSlot();
+  }
+
+  teardownEvents() {
+    this._backdrop?.removeEventListener('click', this._onBackdrop);
+    this.removeEventListener('click', this._onClick);
+    this.removeEventListener('submit', this._onSubmit);
+    this._actionsSlot?.removeEventListener('slotchange', this._onSlot);
+    document.removeEventListener('keydown', this._onKey, true);
+    if (this._wasOpen) { unlockScroll(); this._undoInert?.(); this._undoInert = null; this._wasOpen = false; }
+  }
+
+  onAttributeChanged(name, oldValue, value) {
+    if (name === 'title') { if (this.takeTitle(value)) this._syncTitle(); return; }
+    if (name !== 'open') { this._syncMode(); return; }
+    this._syncOpen();
+    this.emit('nk-toggle', { open: this.getBoolAttr('open') });
+  }
+
+  /** Opens it; focus goes back to `from` when it closes (default: what had focus – pass the ⋯ of a menu that closes). */
+  show(from) { this.returnValue = ''; this._from = from ?? null; this.setBoolAttr('open', true); }
+  /** Closes with `value`, unless an nk-close listener cancels it. Returns whether it closed. */
+  close(value = '') {
+    if (!this.getBoolAttr('open')) return false;
+    if (!this.emit('nk-close', { value })) return false;
+    this.returnValue = value;
+    this.setBoolAttr('open', false);
+    return true;
+  }
+  toggle() { this.getBoolAttr('open') ? this.close('') : this.show(); }
+
+  get open() { return this.getBoolAttr('open'); }
+  set open(v) { v ? this.show() : this.close(''); }
+  get title() { return this._titleText ?? ''; }
+  set title(v) { this._titleText = v == null ? '' : String(v); if (this._initialized) this._syncTitle(); }
+}
+
+customElements.define('nk-dialog', NkDialog);
+export { NkDialog };

package/src/components/overlays/nk-peek.js

@@ -20,17 +20,28 @@ import { lockScroll, unlockScroll, inertOutside, deepActiveElement } from '../..
 // the peek) leave it open. Below 860px it is a bottom sheet over a dimmed
 // page; there it is modal: the page is inert and scroll-locked, the dimmed
 // page takes the tap that closes it. Put it directly under <body>.
+//
+// `resizable` (NotionKit 1.10.0): the left edge takes the pointer – and the
+// arrow keys, 16px a step – to make the peek wider or narrower, as in
+// Notion: from `min` (380) to `max` (all but 320px of the window). The width
+// is the token --nk-peek-width, set on :root; `width` (px) sets it too, and
+// nk-resize { width } fires when a drag or a key ends – the moment to keep
+// it. resize-label names the edge (default "Resize").
+// `inset`: while it is open on the desktop, the page's <nk-app> gets
+// `peek-inset` – its main column makes room instead of lying under the peek.
 const CLOSE_ICON = '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="m6 17 5-5-5-5M13 17l5-5-5-5"/></svg>';
-const OVERLAYS = new Set(['nk-menu', 'nk-pop', 'nk-modal', 'nk-sheet', 'nk-cmdk', 'nk-toast']);
-const OVERLAY_CLASSES = ['nk-pop', 'nk-modal-backdrop', 'nk-sheet-backdrop', 'nk-cmdk-backdrop'];
+const OVERLAYS = new Set(['nk-menu', 'nk-pop', 'nk-modal', 'nk-sheet', 'nk-dialog', 'nk-cmdk', 'nk-toast']);
+const OVERLAY_CLASSES = ['nk-pop', 'nk-modal-backdrop', 'nk-sheet-backdrop', 'nk-dialog-backdrop', 'nk-cmdk-backdrop'];
 const phone = () => matchMedia('(max-width: 860px)').matches;
 
 class NkPeek extends NkElement {
-  static get observedAttributes() { return ['open', 'label', 'close-label']; }
+  static get observedAttributes() { return ['open', 'label', 'close-label', 'resizable', 'width', 'min', 'max', 'resize-label', 'inset']; }
 
   render() {
     this._backdrop = this.createElement('div', ['nk-peek-backdrop']);
     this._box = this.createElement('aside', ['nk-peek'], { role: 'dialog', tabindex: '-1' });
+    this._handle = this.createElement('div', ['pk-resize'], { role: 'separator', 'aria-orientation': 'vertical', tabindex: '0' });
+    this._box.appendChild(this._handle);
     const bar = this.createElement('div', ['pk-bar']);
     this._close = this.createElement('button', ['nk-topbar-btn'], { type: 'button' });
     this._close.innerHTML = CLOSE_ICON;
@@ -41,9 +52,41 @@ class NkPeek extends NkElement {
     this._backdrop.appendChild(this._box);
     this._wrapper.appendChild(this._backdrop);
     this._syncLabels();
+    this._syncResize();
+    if (this.hasAttribute('width')) this._setWidth(Number(this.getAttribute('width')));
     this._syncOpen();
   }
 
+  // ── width ──
+  get _min() { return Number(this.getAttribute('min')) || 380; }
+  get _max() { return Number(this.getAttribute('max')) || Math.max(this._min, innerWidth - 320); }
+  /** The peek's width in px – the token --nk-peek-width. */
+  get width() { return parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--nk-peek-width')) || 560; }
+  set width(v) { this._setWidth(Number(v)); }
+
+  _setWidth(w) {
+    if (!Number.isFinite(w)) return;
+    w = Math.round(Math.min(Math.max(w, this._min), Math.max(this._min, this._max)));
+    document.documentElement.style.setProperty('--nk-peek-width', `${w}px`);
+    this._handle.setAttribute('aria-valuenow', w);
+  }
+
+  _syncResize() {
+    this._handle.hidden = !this.getBoolAttr('resizable');
+    this._handle.setAttribute('aria-label', this.getAttribute('resize-label') || 'Resize');
+    this._handle.setAttribute('aria-valuemin', this._min);
+    this._handle.setAttribute('aria-valuenow', Math.round(this.width));
+  }
+
+  /** The app whose main column makes room: the peek's own, else the page's. */
+  _app() { return this.closest('nk-app') ?? document.querySelector('nk-app'); }
+  _syncInset() {
+    const on = this.getBoolAttr('inset') && this.getBoolAttr('open') && !phone();
+    if (on) this._app()?.setAttribute('peek-inset', '');
+    else if (this._insetApp) this._app()?.removeAttribute('peek-inset');
+    this._insetApp = on;
+  }
+
   _syncLabels() {
     const label = this.getAttribute('label');
     if (label) this._box.setAttribute('aria-label', label); else this._box.removeAttribute('aria-label');
@@ -53,6 +96,7 @@ class NkPeek extends NkElement {
   _syncOpen() {
     const open = this.getBoolAttr('open');
     this._backdrop.classList.toggle('open', open);
+    this._syncInset();
     if (open === this._wasOpen) return;
     this._wasOpen = open;
     if (open) {
@@ -87,23 +131,54 @@ class NkPeek extends NkElement {
       if (path.some(n => n.nodeType === 1 && (OVERLAYS.has(n.localName) || OVERLAY_CLASSES.some(c => n.classList.contains(c))))) return;
       this.close();
     };
+    // The left edge: a drag with pointer capture, or the arrow keys.
+    const resized = () => this.emit('nk-resize', { width: Math.round(this.width) });
+    this._onResizeStart = (e) => {
+      if (e.button !== 0) return;
+      e.preventDefault();
+      this._handle.setPointerCapture(e.pointerId);
+      this._handle.classList.add('active');
+    };
+    this._onResizeMove = (e) => { if (this._handle.hasPointerCapture(e.pointerId)) this._setWidth(innerWidth - e.clientX); };
+    this._onResizeEnd = () => { this._handle.classList.remove('active'); resized(); };
+    this._onResizeKey = (e) => {
+      const step = { ArrowLeft: 16, ArrowRight: -16 }[e.key];
+      if (!step) return;
+      e.preventDefault();
+      this._setWidth(this.width + step);
+      resized();
+    };
+    this._onViewport = () => this._syncInset();
     this._close.addEventListener('click', this._onClose);
     this._backdrop.addEventListener('click', this._onBackdrop);
+    this._handle.addEventListener('pointerdown', this._onResizeStart);
+    this._handle.addEventListener('pointermove', this._onResizeMove);
+    this._handle.addEventListener('lostpointercapture', this._onResizeEnd);
+    this._handle.addEventListener('keydown', this._onResizeKey);
     document.addEventListener('keydown', this._onKey);
     document.addEventListener('click', this._onOutside);
+    addEventListener('resize', this._onViewport);
   }
 
   teardownEvents() {
     this._close?.removeEventListener('click', this._onClose);
     this._backdrop?.removeEventListener('click', this._onBackdrop);
+    this._handle?.removeEventListener('pointerdown', this._onResizeStart);
+    this._handle?.removeEventListener('pointermove', this._onResizeMove);
+    this._handle?.removeEventListener('lostpointercapture', this._onResizeEnd);
+    this._handle?.removeEventListener('keydown', this._onResizeKey);
     document.removeEventListener('keydown', this._onKey);
     document.removeEventListener('click', this._onOutside);
+    removeEventListener('resize', this._onViewport);
+    if (this._insetApp) { this._app()?.removeAttribute('peek-inset'); this._insetApp = false; }
     if (this._modal) { this._modal = false; unlockScroll(); this._undoInert?.(); this._undoInert = null; }
     this._wasOpen = false;
   }
 
-  onAttributeChanged(name) {
-    if (name !== 'open') { this._syncLabels(); return; }
+  onAttributeChanged(name, _old, value) {
+    if (name === 'width') { this._setWidth(Number(value)); return; }
+    if (name === 'inset') { this._syncInset(); return; }
+    if (name !== 'open') { this._syncLabels(); this._syncResize(); return; }
     this._syncOpen();
     this.emit('nk-toggle', { open: this.getBoolAttr('open') });
   }

package/src/components/overlays/nk-tooltip.js

@@ -0,0 +1,136 @@
+import { NkElement } from '../../base.js';
+import { placeNear } from '../../util/floating.js';
+import { deepActiveElement } from '../../util/focus.js';
+
+// <nk-tooltip></nk-tooltip>                    one for the page: every [data-tooltip]
+//   <button data-tooltip="Close sidebar" data-tooltip-key="⌘\">«</button>
+// <nk-tooltip for="saveBtn" shortcut="⌘S">Save the page</nk-tooltip>
+// tip.show(barOrRect, 'Shell · 12.10.–30.11.'); tip.hide();
+// → <div class="nk-tooltip open" role="tooltip">Close sidebar<span class="tt-key">⌘\</span></div>
+//
+// Notion's hover hint (NotionKit 1.10.0). Without `for` it serves every
+// element with data-tooltip – and data-tooltip-key for a shortcut – on the
+// page, inside shadow roots too: the tooltips of a whole toolbar in one
+// element. With `for` it belongs to the element with that id and shows its
+// own content and `shortcut`. It appears after `delay` ms (400) under the
+// pointer and at once on keyboard focus, never on touch; leaving, a press,
+// blur, scrolling and Escape hide it. It sits 6px below its target and
+// centred, above it where the window ends – placement="top" prefers above –
+// and 8px inside the window (placeNear in util/floating.js). show(target,
+// text, shortcut) takes an element or a rect, for what has no element of
+// its own: the bars of a Gantt chart. While it shows, the target's
+// aria-describedby names it (in the same document or shadow root).
+const hostSheet = new CSSStyleSheet();
+hostSheet.replaceSync(`:host { display: block; position: fixed; top: 0; left: 0; z-index: 130; pointer-events: none; }`);
+let count = 0;
+
+class NkTooltip extends NkElement {
+  static get hostStyles() { return hostSheet; }
+  static get observedAttributes() { return ['for', 'shortcut']; }
+
+  render() {
+    this._bubble = this.createElement('div', ['nk-tooltip'], { role: 'tooltip' });
+    this._slot = document.createElement('slot');
+    this._text = document.createTextNode('');
+    this._key = this.createElement('span', ['tt-key']);
+    this._bubble.append(this._slot, this._text, this._key);
+    this._wrapper.appendChild(this._bubble);
+    this._fill(null);
+  }
+
+  get _delay() { const d = Number(this.getAttribute('delay')); return this.hasAttribute('delay') && d >= 0 ? d : 400; }
+
+  /** Own content (text null) or a given text and shortcut. */
+  _fill(text, key = this.getAttribute('shortcut')) {
+    this._slot.style.display = text == null ? '' : 'none';
+    this._text.data = text ?? '';
+    this._key.textContent = key || '';
+    this._key.hidden = !key;
+  }
+
+  /** Shows it at `target` – an element or a rect – with `text` (else its own content) and `shortcut`. */
+  show(target, text, shortcut) {
+    clearTimeout(this._timer);
+    if (!target) return;
+    this._fill(text ?? null, shortcut);
+    this._describe(target);
+    placeNear(this, target, this.getAttribute('placement') === 'top' ? 'top' : 'bottom');
+    this._bubble.classList.add('open');
+  }
+
+  hide() {
+    clearTimeout(this._timer);
+    this._bubble?.classList.remove('open');
+    this._describe(null);
+    this._target = null;
+  }
+
+  get open() { return !!this._bubble?.classList.contains('open'); }
+
+  _describe(target) {
+    if (this._described) {
+      const ids = (this._described.getAttribute('aria-describedby') || '').split(/\s+/).filter(id => id && id !== this.id);
+      ids.length ? this._described.setAttribute('aria-describedby', ids.join(' ')) : this._described.removeAttribute('aria-describedby');
+      this._described = null;
+    }
+    if (!(target instanceof Element) || target.getRootNode() !== this.getRootNode()) return;
+    this.id ||= `nk-tooltip-${++count}`;
+    const ids = (target.getAttribute('aria-describedby') || '').split(/\s+/).filter(Boolean);
+    if (!ids.includes(this.id)) target.setAttribute('aria-describedby', [...ids, this.id].join(' '));
+    this._described = target;
+  }
+
+  /** The element this tooltip serves for an event: its `for` target, or the nearest [data-tooltip]. */
+  _targetOf(e) {
+    const path = e.composedPath();
+    const own = this.getAttribute('for');
+    if (own) { const el = this.getRootNode().getElementById?.(own); return el && path.includes(el) ? el : null; }
+    return path.find(n => n instanceof Element && n.hasAttribute('data-tooltip')) ?? null;
+  }
+
+  _showFor(el) {
+    const own = this.hasAttribute('for');
+    this.show(el, own ? null : el.getAttribute('data-tooltip'), own ? this.getAttribute('shortcut') : el.getAttribute('data-tooltip-key'));
+  }
+
+  setupEvents() {
+    this._onOver = (e) => {
+      const el = e.pointerType === 'touch' ? null : this._targetOf(e);
+      if (el === this._target) return;
+      this.hide();
+      if (!el) return;
+      this._target = el;
+      this._timer = setTimeout(() => this._showFor(el), this._delay);
+    };
+    this._onFocus = (e) => {
+      const el = this._targetOf(e);
+      if (!el || !deepActiveElement()?.matches(':focus-visible')) return;
+      this.hide();
+      this._target = el;
+      this._showFor(el);
+    };
+    this._onHide = () => this.hide();
+    this._onKey = (e) => { if (e.key === 'Escape' && this.open) this.hide(); };
+    document.addEventListener('pointerover', this._onOver);
+    document.addEventListener('focusin', this._onFocus);
+    document.addEventListener('focusout', this._onHide);
+    document.addEventListener('pointerdown', this._onHide, true);
+    document.addEventListener('scroll', this._onHide, true);
+    document.addEventListener('keydown', this._onKey);
+  }
+
+  teardownEvents() {
+    document.removeEventListener('pointerover', this._onOver);
+    document.removeEventListener('focusin', this._onFocus);
+    document.removeEventListener('focusout', this._onHide);
+    document.removeEventListener('pointerdown', this._onHide, true);
+    document.removeEventListener('scroll', this._onHide, true);
+    document.removeEventListener('keydown', this._onKey);
+    this.hide();
+  }
+
+  onAttributeChanged(name) { if (name === 'shortcut' && !this._text.data) this._fill(null); if (name === 'for') this.hide(); }
+}
+
+customElements.define('nk-tooltip', NkTooltip);
+export { NkTooltip };

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

@@ -7,15 +7,22 @@ import { NkElement } from '../../base.js';
 // </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.
+// `peek-inset` (NotionKit 1.10.0) gives the main column a right padding as
+// wide as the side peek – <nk-peek inset> sets it while it is open.
 class NkApp extends NkElement {
+  static get observedAttributes() { return ['peek-inset']; }
+
   render() {
-    const app = this.createElement('div', ['nk-app']);
+    const app = this._app = this.createElement('div', ['nk-app']);
+    app.classList.toggle('peek-inset', this.getBoolAttr('peek-inset'));
     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);
   }
+
+  onAttributeChanged() { this._app.classList.toggle('peek-inset', this.getBoolAttr('peek-inset')); }
 }
 
 customElements.define('nk-app', NkApp);

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

@@ -1,4 +1,5 @@
 import { NkElement } from '../../base.js';
+import { deepActiveElement } from '../../util/focus.js';
 
 // <nk-sidebar slot="sidebar">
 //   <nk-workspace-switcher slot="workspace" name="Acme"></nk-workspace-switcher>
@@ -15,13 +16,28 @@ import { NkElement } from '../../base.js';
 // .open) – the sidebar slides and the scrim fades by the same rules as the
 // class markup; the element toggles the two classes. <nk-btn variant="sidebar">
 // in the topbar is the ☰ that opens it.
+//
+// `collapsible` (NotionKit 1.10.0): on the desktop Notion's « beside the
+// workspace row collapses the sidebar – it slides out to the left, the main
+// column takes the width, nothing in it takes focus – and the topbar's ☰
+// brings it back; ⌘\ or Ctrl+\ toggles it (on a phone the drawer).
+// `collapsed` is the state, collapse() / expand() / toggleCollapsed() the
+// API, nk-collapse { collapsed } the moment to keep it. collapse-label names
+// the « (default "Close sidebar") and is its tooltip for <nk-tooltip>.
+const COLLAPSE_ICON = '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="m18 17-5-5 5-5M11 17l-5-5 5-5"/></svg>';
+const phone = () => matchMedia('(max-width: 860px)').matches;
+
 class NkSidebar extends NkElement {
-  static get observedAttributes() { return ['open']; }
+  static get observedAttributes() { return ['open', 'collapsible', 'collapsed', 'collapse-label']; }
 
   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 head = this.createElement('div', ['nk-sidebar-head']);
+    this._collapse = this.createElement('button', ['nk-sidebar-collapse'], { type: 'button', 'data-tooltip-key': '⌘\\' });
+    this._collapse.innerHTML = COLLAPSE_ICON;
+    head.append(this.createElement('slot', [], { name: 'workspace' }), this._collapse);
+    this._aside.appendChild(head);
     const scroll = this.createElement('div', ['nk-sidebar-scroll']);
     scroll.appendChild(document.createElement('slot'));
     this._aside.appendChild(scroll);
@@ -33,6 +49,21 @@ class NkSidebar extends NkElement {
     this._wrapper.appendChild(this._aside);
     this._syncFooter();
     this._syncOpen();
+    this._syncCollapse();
+  }
+
+  _syncCollapse() {
+    const label = this.getAttribute('collapse-label') || 'Close sidebar';
+    this._collapse.hidden = !this.getBoolAttr('collapsible');
+    this._collapse.setAttribute('aria-label', label);
+    this._collapse.dataset.tooltip = label;
+    this._aside.classList.toggle('collapsed', this.getBoolAttr('collapsed'));
+  }
+
+  /** The ☰ that brings the sidebar back: the one in its own app, else the page's. */
+  _toggleButton() {
+    const sel = 'nk-btn[variant="sidebar"]';
+    return this.closest('nk-app')?.querySelector(sel) ?? document.querySelector(sel);
   }
 
   _syncOpen() {
@@ -52,22 +83,47 @@ class NkSidebar extends NkElement {
   setupEvents() {
     this._onSlot = () => this._syncFooter();
     this._onBackdrop = () => this.close();
-    this._onKey = (e) => { if (e.key === 'Escape' && this.getBoolAttr('open')) this.close(); };
+    this._onKey = (e) => {
+      if (e.key === 'Escape' && this.getBoolAttr('open')) this.close();
+      // Notion's ⌘\: the collapse on the desktop, the drawer on a phone.
+      if (e.key === '\\' && (e.metaKey || e.ctrlKey) && this.getBoolAttr('collapsible') && !e.defaultPrevented) {
+        e.preventDefault();
+        phone() ? this.toggle() : this.toggleCollapsed();
+      }
+    };
+    this._onCollapse = () => this.collapse();
     this._footerSlot.addEventListener('slotchange', this._onSlot);
     this._backdrop.addEventListener('click', this._onBackdrop);
+    this._collapse.addEventListener('click', this._onCollapse);
     document.addEventListener('keydown', this._onKey);
   }
 
   teardownEvents() {
     this._footerSlot?.removeEventListener('slotchange', this._onSlot);
     this._backdrop?.removeEventListener('click', this._onBackdrop);
+    this._collapse?.removeEventListener('click', this._onCollapse);
     document.removeEventListener('keydown', this._onKey);
   }
 
   onAttributeChanged(name) {
-    if (name !== 'open') return;
-    this._syncOpen();
-    this.emit('nk-toggle', { open: this.getBoolAttr('open') });
+    if (name === 'open') {
+      this._syncOpen();
+      this.emit('nk-toggle', { open: this.getBoolAttr('open') });
+      return;
+    }
+    // Focus follows to the control that is left: the ☰ after collapsing, the « after expanding.
+    const active = deepActiveElement();
+    const fromSidebar = active && (this.contains(active) || this._shadow.contains(active));
+    const fromToggle = active?.closest?.('.nk-sidebar-toggle');
+    this._syncCollapse();
+    if (name !== 'collapsed') return;
+    const collapsed = this.getBoolAttr('collapsed');
+    this.emit('nk-collapse', { collapsed });
+    // Two frames later: with reduced motion every nk- element transitions for
+    // .01ms, the inherited visibility included, so the « is focusable only then.
+    const later = fn => requestAnimationFrame(() => requestAnimationFrame(fn));
+    if (collapsed && fromSidebar) later(() => this._toggleButton()?.focus({ preventScroll: true }));
+    if (!collapsed && fromToggle && !this._collapse.hidden) later(() => this._collapse.focus({ preventScroll: true }));
   }
 
   show() { this.setBoolAttr('open', true); }
@@ -76,6 +132,12 @@ class NkSidebar extends NkElement {
 
   get open() { return this.getBoolAttr('open'); }
   set open(v) { this.setBoolAttr('open', v); }
+
+  collapse() { this.setBoolAttr('collapsed', true); }
+  expand() { this.setBoolAttr('collapsed', false); }
+  toggleCollapsed() { this.setBoolAttr('collapsed', !this.getBoolAttr('collapsed')); }
+  get collapsed() { return this.getBoolAttr('collapsed'); }
+  set collapsed(v) { this.setBoolAttr('collapsed', v); }
 }
 
 customElements.define('nk-sidebar', NkSidebar);