@iyulab/desktop-patterns 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iyulab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# desktop-patterns
+
+App-shell and structural layout patterns assembled on top of
+[`desktop-compact`](https://github.com/iyulab/desktop-compact)'s primitives. Framework-neutral custom
+elements ([Lit](https://lit.dev)), zero built-in strings, every content region a slot.
+
+Structure only — atomic controls (buttons, inputs, dialogs) belong in `desktop-compact`; native
+platform integration (file dialogs, tray, window control) belongs in
+[`electron-kit`](https://github.com/iyulab/electron-kit). This package doesn't call any platform API
+itself, and knows nothing about any specific consuming application.
+
+## Install
+
+Requires Node ≥22.
+
+```bash
+npm install @iyulab/desktop-patterns @iyulab/desktop-compact
+```
+
+Import only the components you use — each ships as its own subpath for tree-shaking:
+
+```ts
+import '@iyulab/desktop-patterns/shell'
+import '@iyulab/desktop-patterns/sidebar'
+```
+
+Or import everything via the barrel:
+
+```ts
+import '@iyulab/desktop-patterns'
+```
+
+## Usage
+
+```html
+<dp-shell sidebar-open>
+  <dp-sidebar slot="sidebar" active-id="overview" header="My App" id="nav"></dp-sidebar>
+  <dp-toolbar slot="toolbar" heading="My App" show-toggle></dp-toolbar>
+  <dp-page>
+    <h2>Overview</h2>
+    <p>Main content.</p>
+  </dp-page>
+</dp-shell>
+```
+
+`items`/`bottomItems` are arrays, so they're set as JS properties (not plain HTML attributes) — same
+as any Lit custom element:
+
+```ts
+document.querySelector<HTMLElementTagNameMap['dp-sidebar']>('#nav')!.items = [
+  { id: 'overview', icon: '■', label: 'Overview' },
+]
+
+document.querySelector('dp-sidebar')!.addEventListener('dp-sidebar-select', (e) => {
+  // consumer owns activeId / routing
+})
+document.querySelector('dp-toolbar')!.addEventListener('dp-toolbar-toggle', () => {
+  // consumer owns sidebar-open state on dp-shell
+})
+```
+
+Every component takes its user-facing text as a plain attribute/property or slot — there is no
+built-in i18n layer. See each component's Storybook story (`npm run storybook`) for its full API.
+
+## Theming
+
+Import both token sheets once in your app's global stylesheet:
+
+```ts
+import '@iyulab/desktop-compact/tokens.css'
+import '@iyulab/desktop-patterns/tokens.css'
+```
+
+Color/spacing/radius/typography all come from `desktop-compact`'s `--dc-*` tokens — this package adds
+only the structural dimensions `desktop-compact` has no concept of (`--dp-sidebar-width`,
+`--dp-sidebar-width-collapsed`, `--dp-header-height`). Every component ships with sane fallback
+values, so it still renders correctly even without either stylesheet.
+
+## Platform boundary — drag regions
+
+`dp-toolbar` exposes a neutral `drag-region` flag (not the native `draggable`, which already means
+something else) but never emits any platform-specific CSS itself. The flag reflects to the host
+attribute, but the actual drag surface is a dedicated `part="drag-handle"` spacer between the start
+group and the `actions` slot — never the whole host — so the mapping can never reach the toggle
+button or slotted actions. Mapping that part to an actual window-drag behavior (e.g.
+`-webkit-app-region: drag` in Electron/Chromium-based webviews) is `electron-kit`'s job:
+
+```css
+dp-toolbar[drag-region]::part(drag-handle) {
+  -webkit-app-region: drag;
+}
+```
+
+`dp-shell` does not mark any drag region of its own — it has no opinion on what's slotted into
+`toolbar`, so ownership of the drag handle stays entirely with whatever renders there (typically
+`dp-toolbar`).
+
+## Components (v1 — complete, 5/5)
+
+| Component | Description |
+|---|---|
+| `dp-page` | Scrollable content region with a centered, max-width column — the page-body every view renders into |
+| `dp-sidebar` | App-shell navigation rail — expanded/collapsed states, an optional pinned bottom group, a `footer` slot for whatever a consumer wants to anchor there |
+| `dp-toolbar` | App-shell header bar — `heading`/`subtitle`, an optional collapse toggle, a right-side `actions` slot |
+| `dp-shell` | Top-level layout composing `sidebar`/`toolbar`/`banner`/main-content regions, with a responsive drawer (backdrop + overlay sidebar) below a 1024px breakpoint |
+| `dp-shortcut-overlay` | Display-only keyboard-shortcuts help panel — a `shortcuts` list + `open` flag; no registration/binding infrastructure (that stays the consumer's) |
+
+Run `npm run storybook` to browse every component interactively, including `dp-shell` composing real
+`dp-sidebar`+`dp-toolbar`+`dp-page` together.
+
+## Accessibility
+
+Every component ships with an axe accessibility test as part of its test suite (`npm test`). Landmarks
+follow ARIA APG conventions — `dp-sidebar` uses a semantic `<nav>` (no redundant host-level role),
+`dp-shortcut-overlay` uses `role="dialog"` with `aria-labelledby` pointing at its visible heading.
+
+## Development
+
+```bash
+npm install
+npm test              # @web/test-runner, real Chromium
+npm run typecheck
+npm run guard          # forge-ignorance + platform-agnosticism scan (this package must stay domain-neutral and platform-neutral)
+npm run build          # per-component ESM output, type declarations
+npm run storybook      # interactive component browser
+```
+
+Until `@iyulab/desktop-compact` publishes its first npm release, this package resolves it via
+`file:../desktop-compact` for local development (a sibling checkout at that relative path) — this
+switches to a registry semver range once `desktop-compact` publishes.
+
+## License
+
+MIT

package/dist/components/page/dp-page.d.ts

@@ -0,0 +1,17 @@
+import { LitElement } from 'lit';
+export type PageMaxWidth = 'sm' | 'md' | 'lg' | 'xl' | 'full';
+/**
+ * Scrollable content region with a centered, max-width column — the page-body
+ * pattern every view in an app shell renders into. Pure layout: it has no
+ * opinion on what it contains (default slot only).
+ */
+export declare class DpPage extends LitElement {
+    static styles: import('lit').CSSResult;
+    maxWidth: PageMaxWidth;
+    render(): import('lit-html').TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'dp-page': DpPage;
+    }
+}

package/dist/components/shell/dp-shell.d.ts

@@ -0,0 +1,38 @@
+import { LitElement } from 'lit';
+export declare class DpShellSidebarCloseEvent extends Event {
+    constructor();
+}
+/**
+ * Top-level app-shell layout: a responsive sidebar region (a fixed
+ * backdrop-covered drawer below the desktop breakpoint, static beside the
+ * content above it), a toolbar row, an optional banner row, and the main
+ * content area. Pure composition — every region is a slot, this component
+ * has no opinion on what's inside any of them.
+ *
+ * The original component this generalizes rendered a fixed status banner
+ * unconditionally above its `banner` slot; that hardcoded element is gone
+ * here — the existing `banner` slot alone is enough for a consumer to put
+ * anything there, and this repo has no business knowing what that banner
+ * should be.
+ *
+ * Drag region: this component does not mark any drag region of its own.
+ * The `toolbar-row` wrapper is sized exactly to whatever is slotted into
+ * `toolbar` — it has no empty space that is safely distinct from the
+ * slotted content's own interactive children, so a wrapper-level flag here
+ * could only ever mark the same box `dp-toolbar` already marks (redundant)
+ * or, worse, extend the drag region across content this component has no
+ * visibility into (unsafe — this component "has no opinion on what's
+ * inside any [slot]", per the class doc above). Drag-region ownership
+ * belongs entirely to whatever renders into the `toolbar` slot — see
+ * `dp-toolbar`'s own `part="drag-handle"`.
+ */
+export declare class DpShell extends LitElement {
+    static styles: import('lit').CSSResult;
+    sidebarOpen: boolean;
+    render(): import('lit-html').TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'dp-shell': DpShell;
+    }
+}

package/dist/components/shortcut-overlay/dp-shortcut-overlay.d.ts

@@ -0,0 +1,37 @@
+import { LitElement, nothing } from 'lit';
+export interface ShortcutEntry {
+    combo: string;
+    description: string;
+}
+export declare class DpShortcutOverlayDismissEvent extends Event {
+    constructor();
+}
+/**
+ * Display-only keyboard-shortcuts help panel: a `shortcuts` list + an `open`
+ * flag, nothing else. This component owns no registry and no trigger
+ * keybinding — the original component this generalizes bound its own
+ * `shift+/` shortcut and read from a module-level, framework-hook-specific
+ * registry; both are the consumer's responsibility here (see
+ * docs/superpowers/specs/2026-09-02-desktop-patterns-design.md, the
+ * dp-shortcut-overlay row). This component only dismisses itself (outside
+ * click / Escape) by asking — it dispatches `dp-shortcut-overlay-dismiss`
+ * rather than setting its own `open` to false, since `open` is the
+ * consumer's state to own, not this component's.
+ */
+export declare class DpShortcutOverlay extends LitElement {
+    #private;
+    static styles: import('lit').CSSResult;
+    shortcuts: ShortcutEntry[];
+    open: boolean;
+    heading: string;
+    emptyMessage: string;
+    private headingId;
+    updated(changed: Map<string, unknown>): void;
+    disconnectedCallback(): void;
+    render(): import('lit-html').TemplateResult<1> | typeof nothing;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'dp-shortcut-overlay': DpShortcutOverlay;
+    }
+}

package/dist/components/sidebar/dp-sidebar.d.ts

@@ -0,0 +1,31 @@
+import { LitElement } from 'lit';
+export interface SidebarItem {
+    id: string;
+    icon: string;
+    label: string;
+}
+export declare class DpSidebarSelectEvent extends Event {
+    readonly itemId: string;
+    constructor(itemId: string);
+}
+/**
+ * App-shell navigation rail: an icon+label list with an expanded/collapsed
+ * state, an optional pinned bottom group, and a `footer` slot for whatever
+ * the consumer wants to anchor at the bottom — a status badge, a version
+ * string, anything; this repo doesn't know what.
+ */
+export declare class DpSidebar extends LitElement {
+    #private;
+    static styles: import('lit').CSSResult;
+    items: SidebarItem[];
+    bottomItems: SidebarItem[];
+    activeId: string;
+    header: string;
+    collapsed: boolean;
+    render(): import('lit-html').TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'dp-sidebar': DpSidebar;
+    }
+}

package/dist/components/toolbar/dp-toolbar.d.ts

@@ -0,0 +1,52 @@
+import { LitElement } from 'lit';
+export declare class DpToolbarToggleEvent extends Event {
+    constructor();
+}
+/**
+ * App-shell header bar: a `heading` (optionally overridden per-view by
+ * `subtitle`), an optional collapse/expand toggle, and a right-side
+ * `actions` slot. Pure layout — this repo does not call any platform API.
+ *
+ * Named `heading`, not `title` — matches dc-section-heading's own
+ * established convention for this kind of headline text, and avoids
+ * shadowing the native HTMLElement.prototype.title (tooltip) accessor with
+ * an unrelated meaning, the same reasoning already applied to `drag-region`
+ * below.
+ *
+ * Drag region: the `drag-region` attribute reflects intent only, mirroring
+ * dp-shell — this repo never emits any platform-specific CSS itself (see
+ * docs/superpowers/specs/2026-09-02-desktop-patterns-design.md, "플랫폼 API
+ * 경계"). Named `drag-region`, not the native `draggable` — the platform HTML5
+ * Drag-and-Drop attribute already owns that name/IDL property with unrelated
+ * semantics (HTMLElement.prototype.draggable); reusing it here would shadow
+ * the native accessor on this custom element for a completely different
+ * concept (a window-chrome drag handle, not drag-and-drop). This component's
+ * original source also hardcoded extra end-padding to reserve room for
+ * native window-chrome controls — a platform assumption this repo can't make
+ * either. `--dp-toolbar-inset-start`/`--dp-toolbar-inset-end` (default 0)
+ * generalize that into a neutral extension point a platform-adapter layer
+ * can set.
+ *
+ * The drag CSS a consumer maps onto `drag-region` must never target the host
+ * itself — the host also contains the `.toggle` button and the `actions`
+ * slot, both interactive, and neither carries any no-drag exception. Instead
+ * a dedicated `part="drag-handle"` spacer sits between the start group and
+ * the actions group; it renders no content of its own (nothing is ever
+ * slotted into it), so it is structurally impossible for it to overlap an
+ * interactive child. Consumers scope the platform CSS to that one part, not
+ * to `dp-toolbar[drag-region]` alone — see this package's README (platform
+ * boundary — drag regions) for the exact selector.
+ */
+export declare class DpToolbar extends LitElement {
+    static styles: import('lit').CSSResult;
+    heading: string;
+    subtitle: string;
+    showToggle: boolean;
+    dragRegion: boolean;
+    render(): import('lit-html').TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'dp-toolbar': DpToolbar;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './components/page/dp-page.js';
+export * from './components/sidebar/dp-sidebar.js';
+export * from './components/toolbar/dp-toolbar.js';
+export * from './components/shell/dp-shell.js';
+export * from './components/shortcut-overlay/dp-shortcut-overlay.js';

package/dist/index.js

@@ -0,0 +1,16 @@
+import { DpPage as o } from "./page.js";
+import { DpSidebar as t, DpSidebarSelectEvent as l } from "./sidebar.js";
+import { DpToolbar as a, DpToolbarToggleEvent as S } from "./toolbar.js";
+import { DpShell as v, DpShellSidebarCloseEvent as b } from "./shell.js";
+import { DpShortcutOverlay as i, DpShortcutOverlayDismissEvent as x } from "./shortcut-overlay.js";
+export {
+  o as DpPage,
+  v as DpShell,
+  b as DpShellSidebarCloseEvent,
+  i as DpShortcutOverlay,
+  x as DpShortcutOverlayDismissEvent,
+  t as DpSidebar,
+  l as DpSidebarSelectEvent,
+  a as DpToolbar,
+  S as DpToolbarToggleEvent
+};

package/dist/page.js

@@ -0,0 +1,48 @@
+import { css as a, LitElement as m, html as x } from "lit";
+import { property as d, customElement as c } from "lit/decorators.js";
+var h = Object.defineProperty, u = Object.getOwnPropertyDescriptor, n = (l, e, s, r) => {
+  for (var t = r > 1 ? void 0 : r ? u(e, s) : e, p = l.length - 1, i; p >= 0; p--)
+    (i = l[p]) && (t = (r ? i(e, s, t) : i(t)) || t);
+  return r && t && h(e, s, t), t;
+};
+const b = {
+  sm: "672px",
+  md: "768px",
+  lg: "896px",
+  xl: "1152px",
+  full: "none"
+};
+let o = class extends m {
+  constructor() {
+    super(...arguments), this.maxWidth = "md";
+  }
+  render() {
+    return x`
+      <div class="inner" style="max-width: ${b[this.maxWidth]}">
+        <slot></slot>
+      </div>
+    `;
+  }
+};
+o.styles = a`
+    :host {
+      display: block;
+      height: 100%;
+      overflow-y: auto;
+      box-sizing: border-box;
+    }
+    .inner {
+      margin: 0 auto;
+      padding: var(--dc-space-6, 24px);
+      box-sizing: border-box;
+    }
+  `;
+n([
+  d({ attribute: "max-width", reflect: !0 })
+], o.prototype, "maxWidth", 2);
+o = n([
+  c("dp-page")
+], o);
+export {
+  o as DpPage
+};

package/dist/shell.js

@@ -0,0 +1,93 @@
+import { css as c, LitElement as p, nothing as b, html as a } from "lit";
+import { property as f, customElement as m } from "lit/decorators.js";
+var v = Object.defineProperty, u = Object.getOwnPropertyDescriptor, d = (r, o, t, s) => {
+  for (var e = s > 1 ? void 0 : s ? u(o, t) : o, l = r.length - 1, n; l >= 0; l--)
+    (n = r[l]) && (e = (s ? n(o, t, e) : n(e)) || e);
+  return s && e && v(o, t, e), e;
+};
+class h extends Event {
+  constructor() {
+    super("dp-shell-sidebar-close", { bubbles: !0, composed: !0 });
+  }
+}
+let i = class extends p {
+  constructor() {
+    super(...arguments), this.sidebarOpen = !1;
+  }
+  render() {
+    return a`
+      ${this.sidebarOpen ? a`<div class="backdrop" @click=${() => this.dispatchEvent(new h())}></div>` : b}
+      <div class="sidebar-region"><slot name="sidebar"></slot></div>
+      <div class="main-column">
+        <div class="toolbar-row">
+          <slot name="toolbar"></slot>
+        </div>
+        <slot name="banner"></slot>
+        <main><slot></slot></main>
+      </div>
+    `;
+  }
+};
+i.styles = c`
+    :host {
+      display: flex;
+      width: 100vw;
+      height: 100vh;
+      overflow: hidden;
+      box-sizing: border-box;
+      background: var(--dc-color-bg, #ffffff);
+      color: var(--dc-color-text, #1a1a1e);
+      font-family: var(--dc-font-family, system-ui, sans-serif);
+    }
+    .backdrop {
+      position: fixed;
+      inset: 0;
+      z-index: 30;
+      background: var(--dc-color-backdrop, rgba(0, 0, 0, 0.4));
+    }
+    .sidebar-region {
+      flex-shrink: 0;
+      display: none;
+    }
+    :host([sidebar-open]) .sidebar-region {
+      display: block;
+      position: fixed;
+      inset-block: 0;
+      inset-inline-start: 0;
+      z-index: 40;
+    }
+    @media (min-width: 1024px) {
+      .sidebar-region {
+        display: block;
+        position: relative;
+        inset: auto;
+        z-index: auto;
+      }
+      .backdrop {
+        display: none;
+      }
+    }
+    .main-column {
+      display: flex;
+      flex-direction: column;
+      flex: 1;
+      min-width: 0;
+    }
+    .toolbar-row {
+      flex-shrink: 0;
+    }
+    main {
+      flex: 1;
+      overflow: auto;
+    }
+  `;
+d([
+  f({ type: Boolean, reflect: !0, attribute: "sidebar-open" })
+], i.prototype, "sidebarOpen", 2);
+i = d([
+  m("dp-shell")
+], i);
+export {
+  i as DpShell,
+  h as DpShellSidebarCloseEvent
+};

package/dist/shortcut-overlay.js

@@ -0,0 +1,172 @@
+import { css as x, LitElement as b, nothing as w, html as d } from "lit";
+import { property as l, state as _, customElement as k } from "lit/decorators.js";
+var $ = Object.defineProperty, E = Object.getOwnPropertyDescriptor, g = (e) => {
+  throw TypeError(e);
+}, a = (e, t, r, c) => {
+  for (var s = c > 1 ? void 0 : c ? E(t, r) : t, h = e.length - 1, v; h >= 0; h--)
+    (v = e[h]) && (s = (c ? v(t, r, s) : v(s)) || s);
+  return c && s && $(t, r, s), s;
+}, m = (e, t, r) => t.has(e) || g("Cannot " + r), u = (e, t, r) => (m(e, t, "read from private field"), t.get(e)), y = (e, t, r) => t.has(e) ? g("Cannot add the same private member more than once") : t instanceof WeakSet ? t.add(e) : t.set(e, r), f = (e, t, r) => (m(e, t, "access private method"), r), i, n, p;
+class z extends Event {
+  constructor() {
+    super("dp-shortcut-overlay-dismiss", { bubbles: !0, composed: !0 });
+  }
+}
+let C = 0, o = class extends b {
+  constructor() {
+    super(...arguments), y(this, n), this.shortcuts = [], this.open = !1, this.heading = "Keyboard shortcuts", this.emptyMessage = "No shortcuts registered.", this.headingId = `dp-shortcut-overlay-heading-${++C}`, y(this, i, (e) => {
+      e.key === "Escape" && (e.preventDefault(), f(this, n, p).call(this));
+    });
+  }
+  updated(e) {
+    e.has("open") && (this.open ? window.addEventListener("keydown", u(this, i)) : window.removeEventListener("keydown", u(this, i)));
+  }
+  disconnectedCallback() {
+    super.disconnectedCallback(), window.removeEventListener("keydown", u(this, i));
+  }
+  render() {
+    return this.open ? d`
+      <div class="backdrop" @click=${() => f(this, n, p).call(this)}>
+        <div
+          class="panel"
+          role="dialog"
+          aria-modal="true"
+          aria-labelledby=${this.headingId}
+          @click=${(e) => e.stopPropagation()}
+        >
+          <div class="header">
+            <h2 id=${this.headingId}>${this.heading}</h2>
+            <button class="close" aria-label="Close" @click=${() => f(this, n, p).call(this)}>×</button>
+          </div>
+          <div class="body">
+            ${this.shortcuts.length === 0 ? d`<p class="empty">${this.emptyMessage}</p>` : d`
+                  <ul>
+                    ${this.shortcuts.map(
+      (e) => d`
+                        <li>
+                          <span>${e.description}</span>
+                          <kbd>${e.combo}</kbd>
+                        </li>
+                      `
+    )}
+                  </ul>
+                `}
+          </div>
+        </div>
+      </div>
+    ` : w;
+  }
+};
+i = /* @__PURE__ */ new WeakMap();
+n = /* @__PURE__ */ new WeakSet();
+p = function() {
+  this.dispatchEvent(new z());
+};
+o.styles = x`
+    :host {
+      display: contents;
+      font-family: var(--dc-font-family, system-ui, sans-serif);
+    }
+    .backdrop {
+      position: fixed;
+      inset: 0;
+      z-index: 100;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      background: var(--dc-color-backdrop, rgba(0, 0, 0, 0.4));
+    }
+    .panel {
+      width: 420px;
+      max-height: 70vh;
+      overflow-y: auto;
+      background: var(--dc-color-surface, #f7f7f8);
+      border: 1px solid var(--dc-color-border, #e2e2e4);
+      border-radius: var(--dc-radius-lg, 10px);
+      box-shadow: 0 20px 40px rgba(0, 0, 0, 0.2);
+    }
+    .header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: var(--dc-space-3, 12px) var(--dc-space-4, 16px);
+      border-bottom: 1px solid var(--dc-color-border, #e2e2e4);
+    }
+    h2 {
+      margin: 0;
+      font-size: var(--dc-font-size-sm, 12px);
+      font-weight: var(--dc-font-weight-semibold, 600);
+      color: var(--dc-color-text, #1a1a1e);
+    }
+    .close {
+      appearance: none;
+      background: none;
+      border: none;
+      padding: 0;
+      font-size: var(--dc-font-size-lg, 15px);
+      line-height: 1;
+      color: var(--dc-color-text-muted, #8a8a92);
+      cursor: pointer;
+    }
+    .close:hover {
+      color: var(--dc-color-text, #1a1a1e);
+    }
+    .close:focus-visible {
+      outline: 2px solid var(--dc-color-accent, #2563eb);
+      outline-offset: 2px;
+    }
+    .body {
+      padding: var(--dc-space-3, 12px) var(--dc-space-4, 16px);
+    }
+    .empty {
+      margin: 0;
+      font-size: var(--dc-font-size-xs, 11px);
+      color: var(--dc-color-text-muted, #8a8a92);
+    }
+    ul {
+      list-style: none;
+      margin: 0;
+      padding: 0;
+      display: flex;
+      flex-direction: column;
+      gap: var(--dc-space-1, 4px);
+    }
+    li {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: var(--dc-space-3, 12px);
+      font-size: var(--dc-font-size-xs, 11px);
+    }
+    kbd {
+      padding: 2px 6px;
+      border-radius: var(--dc-radius-sm, 4px);
+      background: var(--dc-color-surface-hover, #ececed);
+      border: 1px solid var(--dc-color-border, #e2e2e4);
+      color: var(--dc-color-text-secondary, #55555c);
+      font-family: ui-monospace, monospace;
+      font-size: 10px;
+    }
+  `;
+a([
+  l({ type: Array })
+], o.prototype, "shortcuts", 2);
+a([
+  l({ type: Boolean, reflect: !0 })
+], o.prototype, "open", 2);
+a([
+  l()
+], o.prototype, "heading", 2);
+a([
+  l({ attribute: "empty-message" })
+], o.prototype, "emptyMessage", 2);
+a([
+  _()
+], o.prototype, "headingId", 2);
+o = a([
+  k("dp-shortcut-overlay")
+], o);
+export {
+  o as DpShortcutOverlay,
+  z as DpShortcutOverlayDismissEvent
+};

package/dist/sidebar.js

@@ -0,0 +1,154 @@
+import { css as m, LitElement as x, nothing as c, html as i } from "lit";
+import { property as n, customElement as g } from "lit/decorators.js";
+var y = Object.defineProperty, _ = Object.getOwnPropertyDescriptor, b = (e) => {
+  throw TypeError(e);
+}, s = (e, t, r, p) => {
+  for (var a = p > 1 ? void 0 : p ? _(t, r) : t, l = e.length - 1, h; l >= 0; l--)
+    (h = e[l]) && (a = (p ? h(t, r, a) : h(a)) || a);
+  return p && a && y(t, r, a), a;
+}, w = (e, t, r) => t.has(e) || b("Cannot " + r), I = (e, t, r) => t.has(e) ? b("Cannot add the same private member more than once") : t instanceof WeakSet ? t.add(e) : t.set(e, r), v = (e, t, r) => (w(e, t, "access private method"), r), d, f, u;
+class $ extends Event {
+  constructor(t) {
+    super("dp-sidebar-select", { bubbles: !0, composed: !0 }), this.itemId = t;
+  }
+}
+let o = class extends x {
+  constructor() {
+    super(...arguments), I(this, d), this.items = [], this.bottomItems = [], this.activeId = "", this.header = "", this.collapsed = !1;
+  }
+  render() {
+    return i`
+      <div class="header">
+        <slot name="icon"></slot>
+        ${!this.collapsed && this.header ? i`<span class="header-label">${this.header}</span>` : c}
+      </div>
+      <nav>${this.items.map((e) => v(this, d, f).call(this, e))}</nav>
+      ${this.bottomItems.length > 0 ? i`<div class="bottom-group">${this.bottomItems.map((e) => v(this, d, f).call(this, e))}</div>` : c}
+      <div class="footer"><slot name="footer"></slot></div>
+    `;
+  }
+};
+d = /* @__PURE__ */ new WeakSet();
+f = function(e) {
+  const t = e.id === this.activeId;
+  return i`
+      <button
+        title=${this.collapsed ? e.label : c}
+        aria-current=${t ? "page" : c}
+        @click=${() => v(this, d, u).call(this, e.id)}
+      >
+        <span class="icon" aria-hidden="true">${e.icon}</span>
+        ${this.collapsed ? c : i`<span>${e.label}</span>`}
+      </button>
+    `;
+};
+u = function(e) {
+  e !== this.activeId && (this.activeId = e, this.dispatchEvent(new $(e)));
+};
+o.styles = m`
+    :host {
+      display: flex;
+      flex-direction: column;
+      height: 100%;
+      box-sizing: border-box;
+      width: var(--dp-sidebar-width, 220px);
+      background: var(--dc-color-surface, #f7f7f8);
+      border-right: 1px solid var(--dc-color-border, #e2e2e4);
+      font-family: var(--dc-font-family, system-ui, sans-serif);
+    }
+    :host([collapsed]) {
+      width: var(--dp-sidebar-width-collapsed, 52px);
+    }
+    .header {
+      height: var(--dp-header-height, 52px);
+      display: flex;
+      align-items: center;
+      gap: var(--dc-space-3, 12px);
+      padding: 0 var(--dc-space-3, 12px);
+      border-bottom: 1px solid var(--dc-color-border, #e2e2e4);
+      box-sizing: border-box;
+      flex-shrink: 0;
+    }
+    :host([collapsed]) .header {
+      justify-content: center;
+      padding: 0;
+    }
+    .header-label {
+      font-size: var(--dc-font-size-xs, 11px);
+      font-weight: var(--dc-font-weight-medium, 500);
+      color: var(--dc-color-text-secondary, #55555c);
+      text-transform: uppercase;
+      letter-spacing: 0.02em;
+    }
+    nav {
+      flex: 1;
+      overflow-y: auto;
+      padding: var(--dc-space-1, 4px) 0;
+    }
+    .bottom-group {
+      border-top: 1px solid var(--dc-color-border, #e2e2e4);
+      padding: var(--dc-space-1, 4px) 0;
+    }
+    button {
+      appearance: none;
+      background: none;
+      border: none;
+      border-left: 2px solid transparent;
+      width: 100%;
+      display: flex;
+      align-items: center;
+      gap: var(--dc-space-3, 12px);
+      padding: var(--dc-space-2, 8px) var(--dc-space-3, 12px);
+      font: inherit;
+      font-size: var(--dc-font-size-sm, 12px);
+      color: var(--dc-color-text-secondary, #55555c);
+      text-align: left;
+      cursor: pointer;
+    }
+    :host([collapsed]) button {
+      justify-content: center;
+      padding: var(--dc-space-3, 12px) 0;
+    }
+    button[aria-current='page'] {
+      border-left-color: var(--dc-color-accent, #2563eb);
+      color: var(--dc-color-accent, #2563eb);
+      font-weight: var(--dc-font-weight-medium, 500);
+    }
+    button:hover {
+      background: var(--dc-color-surface-hover, #ececed);
+    }
+    button:focus-visible {
+      outline: 2px solid var(--dc-color-accent, #2563eb);
+      outline-offset: -2px;
+    }
+    .icon {
+      flex-shrink: 0;
+      width: 1.25em;
+      text-align: center;
+    }
+    .footer {
+      border-top: 1px solid var(--dc-color-border, #e2e2e4);
+    }
+  `;
+s([
+  n({ type: Array })
+], o.prototype, "items", 2);
+s([
+  n({ type: Array, attribute: "bottom-items" })
+], o.prototype, "bottomItems", 2);
+s([
+  n({ attribute: "active-id" })
+], o.prototype, "activeId", 2);
+s([
+  n()
+], o.prototype, "header", 2);
+s([
+  n({ type: Boolean, reflect: !0 })
+], o.prototype, "collapsed", 2);
+o = s([
+  g("dp-sidebar")
+], o);
+export {
+  o as DpSidebar,
+  $ as DpSidebarSelectEvent
+};

package/dist/toolbar.js

@@ -0,0 +1,108 @@
+import { css as p, LitElement as g, nothing as h, html as d } from "lit";
+import { property as s, customElement as v } from "lit/decorators.js";
+var f = Object.defineProperty, b = Object.getOwnPropertyDescriptor, o = (i, r, l, a) => {
+  for (var e = a > 1 ? void 0 : a ? b(r, l) : r, n = i.length - 1, c; n >= 0; n--)
+    (c = i[n]) && (e = (a ? c(r, l, e) : c(e)) || e);
+  return a && e && f(r, l, e), e;
+};
+class u extends Event {
+  constructor() {
+    super("dp-toolbar-toggle", { bubbles: !0, composed: !0 });
+  }
+}
+let t = class extends g {
+  constructor() {
+    super(...arguments), this.heading = "", this.subtitle = "", this.showToggle = !1, this.dragRegion = !1;
+  }
+  render() {
+    return d`
+      <div class="start">
+        ${this.showToggle ? d`<button
+              class="toggle"
+              aria-label="Toggle sidebar"
+              @click=${() => this.dispatchEvent(new u())}
+            >
+              ☰
+            </button>` : h}
+        <span class="title">${this.subtitle || this.heading}</span>
+      </div>
+      <div class="drag-handle" part="drag-handle"></div>
+      <div class="actions"><slot name="actions"></slot></div>
+    `;
+  }
+};
+t.styles = p`
+    :host {
+      display: flex;
+      align-items: center;
+      height: var(--dp-header-height, 52px);
+      box-sizing: border-box;
+      padding: 0 var(--dc-space-4, 16px);
+      padding-inline-start: calc(var(--dc-space-4, 16px) + var(--dp-toolbar-inset-start, 0px));
+      padding-inline-end: calc(var(--dc-space-4, 16px) + var(--dp-toolbar-inset-end, 0px));
+      background: var(--dc-color-surface, #f7f7f8);
+      border-bottom: 1px solid var(--dc-color-border, #e2e2e4);
+      font-family: var(--dc-font-family, system-ui, sans-serif);
+      flex-shrink: 0;
+    }
+    .start {
+      display: flex;
+      align-items: center;
+      gap: var(--dc-space-4, 16px);
+      min-width: 0;
+    }
+    .title {
+      font-size: var(--dc-font-size-sm, 12px);
+      font-weight: var(--dc-font-weight-medium, 500);
+      color: var(--dc-color-text, #1a1a1e);
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+    .toggle {
+      appearance: none;
+      background: none;
+      border: none;
+      padding: 0;
+      font-size: var(--dc-font-size-lg, 15px);
+      color: var(--dc-color-text-secondary, #55555c);
+      cursor: pointer;
+      line-height: 1;
+    }
+    .toggle:hover {
+      color: var(--dc-color-text, #1a1a1e);
+    }
+    .toggle:focus-visible {
+      outline: 2px solid var(--dc-color-accent, #2563eb);
+      outline-offset: 2px;
+    }
+    .drag-handle {
+      flex: 1;
+      align-self: stretch;
+      min-width: var(--dc-space-4, 16px);
+    }
+    .actions {
+      display: flex;
+      align-items: center;
+      gap: var(--dc-space-3, 12px);
+    }
+  `;
+o([
+  s()
+], t.prototype, "heading", 2);
+o([
+  s()
+], t.prototype, "subtitle", 2);
+o([
+  s({ type: Boolean, attribute: "show-toggle" })
+], t.prototype, "showToggle", 2);
+o([
+  s({ type: Boolean, reflect: !0, attribute: "drag-region" })
+], t.prototype, "dragRegion", 2);
+t = o([
+  v("dp-toolbar")
+], t);
+export {
+  t as DpToolbar,
+  u as DpToolbarToggleEvent
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@iyulab/desktop-patterns",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "tokens.css"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./page": {
+      "types": "./dist/components/page/dp-page.d.ts",
+      "import": "./dist/page.js"
+    },
+    "./tokens.css": "./tokens.css"
+  },
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "web-test-runner \"src/**/*.test.ts\"",
+    "test:watch": "web-test-runner \"src/**/*.test.ts\" --watch",
+    "guard": "node scripts/check-forge-tokens.mjs",
+    "guard:test": "node --test scripts/*.test.mjs",
+    "storybook": "storybook dev -p 6007",
+    "build-storybook": "storybook build"
+  },
+  "dependencies": {
+    "@iyulab/desktop-compact": "^0.1.0",
+    "lit": "^3.2.1"
+  },
+  "devDependencies": {
+    "@open-wc/testing": "^4.0.0",
+    "@storybook/addon-essentials": "^8.3.0",
+    "@storybook/web-components": "^8.3.0",
+    "@storybook/web-components-vite": "^8.3.0",
+    "@types/mocha": "^10.0.10",
+    "@web/dev-server-esbuild": "^1.0.2",
+    "@web/test-runner": "^0.19.0",
+    "storybook": "^8.3.0",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.10",
+    "vite-plugin-dts": "^4.2.4"
+  }
+}

package/tokens.css

@@ -0,0 +1,14 @@
+/*
+ * Structural tokens for @iyulab/desktop-patterns.
+ *
+ * This file adds ONLY the dimensions this layer introduces that
+ * @iyulab/desktop-compact has no concept of (sidebar/header sizing). Color,
+ * spacing-scale, radius, and typography tokens are NOT duplicated here —
+ * import @iyulab/desktop-compact/tokens.css alongside this file; every
+ * desktop-patterns component consumes --dc-* directly.
+ */
+:root {
+  --dp-sidebar-width: 220px;
+  --dp-sidebar-width-collapsed: 52px;
+  --dp-header-height: 52px;
+}