@iyulab/desktop-patterns 0.3.4 → 0.4.0

package/README.md

@@ -33,7 +33,7 @@ import '@iyulab/desktop-patterns'
 ## Usage
 
 ```html
-<dp-shell sidebar-open>
+<dp-shell>
   <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>
@@ -51,14 +51,23 @@ document.querySelector<HTMLElementTagNameMap['dp-sidebar']>('#nav')!.items = [
   { id: 'overview', icon: '■', label: 'Overview' },
 ]
 
+const shell = document.querySelector('dp-shell')!
 document.querySelector('dp-sidebar')!.addEventListener('dp-sidebar-select', (e) => {
   // consumer owns activeId / routing
+  shell.sidebarOpen = false // a drawer gives way to what was picked
 })
 document.querySelector('dp-toolbar')!.addEventListener('dp-toolbar-toggle', () => {
-  // consumer owns sidebar-open state on dp-shell
+  shell.sidebarOpen = !shell.sidebarOpen
 })
+shell.addEventListener('dp-shell-sidebar-close', () => (shell.sidebarOpen = false)) // backdrop, Escape
 ```
 
+Below the desktop breakpoint (1024px) the sidebar is a drawer over the content, open while
+`sidebar-open` is set; at and above it the sidebar always sits beside the content and `sidebar-open`
+changes nothing, and `dp-toolbar` hides its toggle there. The breakpoint is exported as
+`desktopMinWidth` (and `desktopMedia` for a component's styles). The consumer owns that state — start it closed, and close it when the shell asks
+(backdrop click, Escape) and when a place is picked, or a narrow window stays covered.
+
 ### Sidebar items: links, groups, icons, actions
 
 ```ts
@@ -125,9 +134,9 @@ dp-toolbar[drag-region]::part(drag-handle) {
 
 | Component | Description |
 |---|---|
-| `dp-page` | Scrollable content region with a centered, max-width column — the page-body every view renders into |
+| `dp-page` | Scrollable content region with a centered, max-width column — the page-body every view renders into. With `fill` it does not scroll and its column is as tall as the region, for a view that scrolls its own parts (a list beside the item open) |
 | `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-toolbar` | App-shell header bar — `heading`/`subtitle`, an optional sidebar drawer toggle (below the desktop breakpoint only), 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) |
 

package/dist/breakpoints-BjS_v3PV.js

@@ -0,0 +1,5 @@
+import { unsafeCSS as e } from "lit";
+//#region src/breakpoints.ts
+var t = 1024, n = e(`(min-width: ${t}px)`);
+//#endregion
+export { t as n, n as t };

package/dist/breakpoints.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The desktop breakpoint, in CSS pixels. Below it `dp-shell`'s sidebar is a drawer over the
+ * content; at and above it the sidebar always sits beside the content, so `dp-toolbar` hides the
+ * toggle that opens the drawer.
+ */
+export declare const desktopMinWidth = 1024;
+/** The media query for {@link desktopMinWidth}, for a component's styles. */
+export declare const desktopMedia: import('lit').CSSResult;

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

@@ -4,10 +4,17 @@ 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).
+ *
+ * With `fill`, the page does not scroll: its column fills the region's height
+ * (a flex column), for a view that divides its own scrolling — a list beside
+ * the item open, where the list scrolls and the item stays in view. The
+ * slotted view sizes itself within that height (e.g. `flex: 1; min-height: 0`).
  */
 export declare class DpPage extends LitElement {
     static styles: import('lit').CSSResult;
     maxWidth: PageMaxWidth;
+    /** Fill the region's height instead of scrolling: the view inside divides its own scrolling. */
+    fill: boolean;
     render(): import('lit-html').TemplateResult<1>;
 }
 declare global {

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

@@ -28,7 +28,16 @@ export declare class DpShellSidebarCloseEvent extends Event {
  */
 export declare class DpShell extends LitElement {
     static styles: import('lit').CSSResult;
+    /**
+     * Whether the sidebar is open as a drawer below the desktop breakpoint. Above it the sidebar is
+     * always shown beside the content and this changes nothing. The consumer owns it: start it closed,
+     * and set it back to false on `dp-shell-sidebar-close` (backdrop click or Escape) and after a
+     * place is picked in the drawer.
+     */
     sidebarOpen: boolean;
+    private readonly onKeydown;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     render(): import('lit-html').TemplateResult<1>;
 }
 declare global {

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

@@ -4,8 +4,9 @@ export declare class DpToolbarToggleEvent extends Event {
 }
 /**
  * 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.
+ * `subtitle`), an optional toggle for `dp-shell`'s sidebar drawer — shown
+ * only below the desktop breakpoint, where the sidebar is a drawer — 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
@@ -41,6 +42,7 @@ export declare class DpToolbar extends LitElement {
     static styles: import('lit').CSSResult;
     heading: string;
     subtitle: string;
+    /** Shows the sidebar drawer toggle. It is hidden at and above the desktop breakpoint. */
     showToggle: boolean;
     /** Accessible name of the sidebar toggle — supply one in the app's language. */
     toggleLabel: string;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from './breakpoints.js';
 export * from './components/page/dp-page.js';
 export * from './components/sidebar/dp-sidebar.js';
 export * from './components/toolbar/dp-toolbar.js';

package/dist/index.js

@@ -1,6 +1,7 @@
-import { DpPage as e } from "./page.js";
-import { DpSidebar as t, DpSidebarActionEvent as n, DpSidebarSelectEvent as r } from "./sidebar.js";
-import { DpToolbar as i, DpToolbarToggleEvent as a } from "./toolbar.js";
-import { DpShell as o, DpShellSidebarCloseEvent as s } from "./shell.js";
-import { DpShortcutOverlay as c, DpShortcutOverlayDismissEvent as l } from "./shortcut-overlay.js";
-export { e as DpPage, o as DpShell, s as DpShellSidebarCloseEvent, c as DpShortcutOverlay, l as DpShortcutOverlayDismissEvent, t as DpSidebar, n as DpSidebarActionEvent, r as DpSidebarSelectEvent, i as DpToolbar, a as DpToolbarToggleEvent };
+import { n as e, t } from "./breakpoints-BjS_v3PV.js";
+import { DpPage as n } from "./page.js";
+import { DpSidebar as r, DpSidebarActionEvent as i, DpSidebarSelectEvent as a } from "./sidebar.js";
+import { DpToolbar as o, DpToolbarToggleEvent as s } from "./toolbar.js";
+import { DpShell as c, DpShellSidebarCloseEvent as l } from "./shell.js";
+import { DpShortcutOverlay as u, DpShortcutOverlayDismissEvent as d } from "./shortcut-overlay.js";
+export { n as DpPage, c as DpShell, l as DpShellSidebarCloseEvent, u as DpShortcutOverlay, d as DpShortcutOverlayDismissEvent, r as DpSidebar, i as DpSidebarActionEvent, a as DpSidebarSelectEvent, o as DpToolbar, s as DpToolbarToggleEvent, t as desktopMedia, e as desktopMinWidth };

package/dist/page.js

@@ -10,7 +10,7 @@ var o = {
 	full: "none"
 }, s = class extends t {
 	constructor(...e) {
-		super(...e), this.maxWidth = "md";
+		super(...e), this.maxWidth = "md", this.fill = !1;
 	}
 	static {
 		this.styles = n`
@@ -25,6 +25,14 @@ var o = {
       padding: var(--dc-space-6, 24px);
       box-sizing: border-box;
     }
+    :host([fill]) {
+      overflow: hidden;
+    }
+    :host([fill]) .inner {
+      display: flex;
+      flex-direction: column;
+      height: 100%;
+    }
   `;
 	}
 	render() {
@@ -38,6 +46,9 @@ var o = {
 e([a({
 	attribute: "max-width",
 	reflect: !0
-})], s.prototype, "maxWidth", void 0), s = e([i("dp-page")], s);
+})], s.prototype, "maxWidth", void 0), e([a({
+	type: Boolean,
+	reflect: !0
+})], s.prototype, "fill", void 0), s = e([i("dp-page")], s);
 //#endregion
 export { s as DpPage };

package/dist/shell.js

@@ -1,20 +1,23 @@
-import { t as e } from "./decorate-CafwLXg5.js";
-import { LitElement as t, css as n, html as r, nothing as i } from "lit";
-import { customElement as a, property as o } from "lit/decorators.js";
+import { t as e } from "./breakpoints-BjS_v3PV.js";
+import { t } from "./decorate-CafwLXg5.js";
+import { LitElement as n, css as r, html as i, nothing as a } from "lit";
+import { customElement as o, property as s } from "lit/decorators.js";
 //#region src/components/shell/dp-shell.ts
-var s = class extends Event {
+var c = class extends Event {
 	constructor() {
 		super("dp-shell-sidebar-close", {
 			bubbles: !0,
 			composed: !0
 		});
 	}
-}, c = class extends t {
+}, l = class extends n {
 	constructor(...e) {
-		super(...e), this.sidebarOpen = !1;
+		super(...e), this.sidebarOpen = !1, this.onKeydown = (e) => {
+			e.key === "Escape" && !e.defaultPrevented && this.sidebarOpen && this.dispatchEvent(new c());
+		};
 	}
 	static {
-		this.styles = n`
+		this.styles = r`
     :host {
       display: flex;
       width: 100vw;
@@ -42,7 +45,7 @@ var s = class extends Event {
       inset-inline-start: 0;
       z-index: 40;
     }
-    @media (min-width: 1024px) {
+    @media ${e} {
       /* Must match (or exceed) \`:host([sidebar-open]) .sidebar-region\`'s
          specificity above (0,3,0) — a bare \`.sidebar-region\` here is only
          (0,1,0), so on equal-or-narrower cascades the desktop override would
@@ -77,9 +80,15 @@ var s = class extends Event {
     }
   `;
 	}
+	connectedCallback() {
+		super.connectedCallback(), document.addEventListener("keydown", this.onKeydown);
+	}
+	disconnectedCallback() {
+		document.removeEventListener("keydown", this.onKeydown), super.disconnectedCallback();
+	}
 	render() {
-		return r`
-      ${this.sidebarOpen ? r`<div class="backdrop" @click=${() => this.dispatchEvent(new s())}></div>` : i}
+		return i`
+      ${this.sidebarOpen ? i`<div class="backdrop" @click=${() => this.dispatchEvent(new c())}></div>` : a}
       <div class="sidebar-region"><slot name="sidebar"></slot></div>
       <div class="main-column">
         <div class="toolbar-row">
@@ -91,10 +100,10 @@ var s = class extends Event {
     `;
 	}
 };
-e([o({
+t([s({
 	type: Boolean,
 	reflect: !0,
 	attribute: "sidebar-open"
-})], c.prototype, "sidebarOpen", void 0), c = e([a("dp-shell")], c);
+})], l.prototype, "sidebarOpen", void 0), l = t([o("dp-shell")], l);
 //#endregion
-export { c as DpShell, s as DpShellSidebarCloseEvent };
+export { l as DpShell, c as DpShellSidebarCloseEvent };

package/dist/toolbar.js

@@ -1,20 +1,21 @@
-import { t as e } from "./decorate-CafwLXg5.js";
-import { LitElement as t, css as n, html as r, nothing as i } from "lit";
-import { customElement as a, property as o } from "lit/decorators.js";
+import { t as e } from "./breakpoints-BjS_v3PV.js";
+import { t } from "./decorate-CafwLXg5.js";
+import { LitElement as n, css as r, html as i, nothing as a } from "lit";
+import { customElement as o, property as s } from "lit/decorators.js";
 //#region src/components/toolbar/dp-toolbar.ts
-var s = class extends Event {
+var c = class extends Event {
 	constructor() {
 		super("dp-toolbar-toggle", {
 			bubbles: !0,
 			composed: !0
 		});
 	}
-}, c = class extends t {
+}, l = class extends n {
 	constructor(...e) {
 		super(...e), this.heading = "", this.subtitle = "", this.showToggle = !1, this.toggleLabel = "Toggle sidebar", this.dragRegion = !1;
 	}
 	static {
-		this.styles = n`
+		this.styles = r`
     :host {
       display: flex;
       align-items: center;
@@ -59,6 +60,13 @@ var s = class extends Event {
       outline: 2px solid var(--dc-color-accent, #2563eb);
       outline-offset: 2px;
     }
+    /* At desktop width dp-shell's sidebar is always beside the content: a drawer toggle there
+       would do nothing. */
+    @media ${e} {
+      .toggle {
+        display: none;
+      }
+    }
     .drag-handle {
       flex: 1;
       align-self: stretch;
@@ -75,15 +83,15 @@ var s = class extends Event {
 		super.connectedCallback(), this.setAttribute("role", "banner");
 	}
 	render() {
-		return r`
+		return i`
       <div class="start">
-        ${this.showToggle ? r`<button
+        ${this.showToggle ? i`<button
               class="toggle"
               aria-label=${this.toggleLabel}
-              @click=${() => this.dispatchEvent(new s())}
+              @click=${() => this.dispatchEvent(new c())}
             >
               ☰
-            </button>` : i}
+            </button>` : a}
         <span class="title">${this.subtitle || this.heading}</span>
       </div>
       <div class="drag-handle" part="drag-handle"></div>
@@ -91,13 +99,13 @@ var s = class extends Event {
     `;
 	}
 };
-e([o()], c.prototype, "heading", void 0), e([o()], c.prototype, "subtitle", void 0), e([o({
+t([s()], l.prototype, "heading", void 0), t([s()], l.prototype, "subtitle", void 0), t([s({
 	type: Boolean,
 	attribute: "show-toggle"
-})], c.prototype, "showToggle", void 0), e([o({ attribute: "toggle-label" })], c.prototype, "toggleLabel", void 0), e([o({
+})], l.prototype, "showToggle", void 0), t([s({ attribute: "toggle-label" })], l.prototype, "toggleLabel", void 0), t([s({
 	type: Boolean,
 	reflect: !0,
 	attribute: "drag-region"
-})], c.prototype, "dragRegion", void 0), c = e([a("dp-toolbar")], c);
+})], l.prototype, "dragRegion", void 0), l = t([o("dp-toolbar")], l);
 //#endregion
-export { c as DpToolbar, s as DpToolbarToggleEvent };
+export { l as DpToolbar, c as DpToolbarToggleEvent };

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@iyulab/desktop-patterns",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iyulab/desktop-patterns.git"
+  },
+  "homepage": "https://github.com/iyulab/desktop-patterns#readme",
+  "bugs": "https://github.com/iyulab/desktop-patterns/issues",
   "engines": {
     "node": ">=22"
   },
@@ -48,6 +54,7 @@
   },
   "scripts": {
     "build": "vite build",
+    "prepack": "npm run build",
     "typecheck": "tsc --noEmit",
     "test": "web-test-runner \"src/**/*.test.ts\"",
     "test:watch": "web-test-runner \"src/**/*.test.ts\" --watch",
@@ -63,7 +70,7 @@
     "@iyulab/desktop-compact": "^0.2.0 || ^0.3.0 || ^0.4.0 || ^0.5.0 || ^0.6.0 || ^0.7.0 || ^0.8.0"
   },
   "devDependencies": {
-    "@iyulab/desktop-compact": "^0.8.0",
+    "@iyulab/desktop-compact": "^0.8.2",
     "@open-wc/testing": "^5.0.0",
     "@storybook/web-components": "^10.6.0",
     "@storybook/web-components-vite": "^10.6.0",