@iyulab/desktop-patterns 0.3.4 → 0.5.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,40 @@ document.querySelector<HTMLElementTagNameMap['dp-sidebar']>('#nav')!.items = [
   { id: 'overview', icon: '■', label: 'Overview' },
 ]
 
-document.querySelector('dp-sidebar')!.addEventListener('dp-sidebar-select', (e) => {
+import { desktopMinWidth } from '@iyulab/desktop-patterns'
+
+const shell = document.querySelector('dp-shell')!
+const sidebar = document.querySelector('dp-sidebar')!
+const toolbar = document.querySelector('dp-toolbar')!
+const wide = matchMedia(`(min-width: ${desktopMinWidth}px)`)
+let collapsed = false // the consumer's own state: a wide window's sidebar folded to its rail
+
+function sync() {
+  sidebar.collapsed = collapsed && wide.matches // a drawer always shows the whole sidebar
+  toolbar.expanded = wide.matches ? !collapsed : shell.sidebarOpen
+}
+wide.addEventListener('change', sync)
+sidebar.addEventListener('dp-sidebar-select', () => {
   // consumer owns activeId / routing
+  shell.sidebarOpen = false // a drawer gives way to what was picked
+  sync()
 })
-document.querySelector('dp-toolbar')!.addEventListener('dp-toolbar-toggle', () => {
-  // consumer owns sidebar-open state on dp-shell
+toolbar.addEventListener('dp-toolbar-toggle', () => {
+  if (wide.matches) collapsed = !collapsed
+  else shell.sidebarOpen = !shell.sidebarOpen
+  sync()
 })
+shell.addEventListener('dp-shell-sidebar-close', () => { shell.sidebarOpen = false; sync() }) // backdrop, Escape
 ```
 
+Below the desktop breakpoint (`desktopMinWidth`, 1024px — `desktopMedia` for a component's styles)
+the sidebar is a drawer over the content, open while `sidebar-open` is set; at and above it the
+sidebar sits beside the content and `sidebar-open` changes nothing. The same toolbar toggle serves
+both widths: in a narrow window it opens the drawer, in a wide one it folds the sidebar to its
+collapsed rail (`dp-sidebar` `collapsed`). Give the toggle `expanded` so assistive technology hears
+which state it is in. The consumer owns both states — start the drawer closed, 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 +151,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 toggle (drawer in a narrow window, collapse in a wide one), 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.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 sits beside the content, where a consumer may fold
+ * `dp-sidebar` to its collapsed rail instead.
+ */
+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 sidebar toggle — the consumer decides what it does
+ * (open `dp-shell`'s drawer in a narrow window, fold `dp-sidebar` to its rail
+ * in a wide one) — 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
@@ -42,6 +43,8 @@ export declare class DpToolbar extends LitElement {
     heading: string;
     subtitle: string;
     showToggle: boolean;
+    /** Whether the sidebar the toggle controls is shown in full — announced as the toggle's `aria-expanded`. */
+    expanded: boolean;
     /** Accessible name of the sidebar toggle — supply one in the app's language. */
     toggleLabel: string;
     dragRegion: boolean;

package/dist/dp-shell-CvV92B8B.js

@@ -0,0 +1,108 @@
+import { t as e } from "./decorate-CafwLXg5.js";
+import { LitElement as t, css as n, html as r, nothing as i, unsafeCSS as a } from "lit";
+import { customElement as o, property as s } from "lit/decorators.js";
+//#region src/breakpoints.ts
+var c = 1024, l = a(`(min-width: ${c}px)`), u = class extends Event {
+	constructor() {
+		super("dp-shell-sidebar-close", {
+			bubbles: !0,
+			composed: !0
+		});
+	}
+}, d = class extends t {
+	constructor(...e) {
+		super(...e), this.sidebarOpen = !1, this.onKeydown = (e) => {
+			e.key === "Escape" && !e.defaultPrevented && this.sidebarOpen && this.dispatchEvent(new u());
+		};
+	}
+	static {
+		this.styles = n`
+    :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 ${l} {
+      /* 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
+         lose to the sidebar-open rule regardless of this media query
+         matching, leaving the sidebar permanently \`position: fixed\` (full-
+         height overlay) at any width once \`sidebar-open\` is set. Repeating
+         the \`:host([sidebar-open])\` prefix here, rather than only the bare
+         selector, is what actually lets desktop width win. */
+      :host([sidebar-open]) .sidebar-region,
+      .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;
+    }
+  `;
+	}
+	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 u())}></div>` : i}
+      <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>
+    `;
+	}
+};
+e([s({
+	type: Boolean,
+	reflect: !0,
+	attribute: "sidebar-open"
+})], d.prototype, "sidebarOpen", void 0), d = e([o("dp-shell")], d);
+//#endregion
+export { c as i, u as n, l as r, d as t };

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,6 @@
-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 { i as e, n as t, r as n, t as r } from "./dp-shell-CvV92B8B.js";
+import { DpPage as i } from "./page.js";
+import { DpSidebar as a, DpSidebarActionEvent as o, DpSidebarSelectEvent as s } from "./sidebar.js";
+import { DpToolbar as c, DpToolbarToggleEvent as l } from "./toolbar.js";
+import { DpShortcutOverlay as u, DpShortcutOverlayDismissEvent as d } from "./shortcut-overlay.js";
+export { i as DpPage, r as DpShell, t as DpShellSidebarCloseEvent, u as DpShortcutOverlay, d as DpShortcutOverlayDismissEvent, a as DpSidebar, o as DpSidebarActionEvent, s as DpSidebarSelectEvent, c as DpToolbar, l as DpToolbarToggleEvent, n 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,100 +1,2 @@
-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";
-//#region src/components/shell/dp-shell.ts
-var s = class extends Event {
-	constructor() {
-		super("dp-shell-sidebar-close", {
-			bubbles: !0,
-			composed: !0
-		});
-	}
-}, c = class extends t {
-	constructor(...e) {
-		super(...e), this.sidebarOpen = !1;
-	}
-	static {
-		this.styles = n`
-    :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) {
-      /* 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
-         lose to the sidebar-open rule regardless of this media query
-         matching, leaving the sidebar permanently \`position: fixed\` (full-
-         height overlay) at any width once \`sidebar-open\` is set. Repeating
-         the \`:host([sidebar-open])\` prefix here, rather than only the bare
-         selector, is what actually lets desktop width win. */
-      :host([sidebar-open]) .sidebar-region,
-      .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;
-    }
-  `;
-	}
-	render() {
-		return r`
-      ${this.sidebarOpen ? r`<div class="backdrop" @click=${() => this.dispatchEvent(new s())}></div>` : i}
-      <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>
-    `;
-	}
-};
-e([o({
-	type: Boolean,
-	reflect: !0,
-	attribute: "sidebar-open"
-})], c.prototype, "sidebarOpen", void 0), c = e([a("dp-shell")], c);
-//#endregion
-export { c as DpShell, s as DpShellSidebarCloseEvent };
+import { n as e, t } from "./dp-shell-CvV92B8B.js";
+export { t as DpShell, e as DpShellSidebarCloseEvent };

package/dist/toolbar.js

@@ -11,7 +11,7 @@ var s = class extends Event {
 	}
 }, c = class extends t {
 	constructor(...e) {
-		super(...e), this.heading = "", this.subtitle = "", this.showToggle = !1, this.toggleLabel = "Toggle sidebar", this.dragRegion = !1;
+		super(...e), this.heading = "", this.subtitle = "", this.showToggle = !1, this.expanded = !1, this.toggleLabel = "Toggle sidebar", this.dragRegion = !1;
 	}
 	static {
 		this.styles = n`
@@ -80,6 +80,7 @@ var s = class extends Event {
         ${this.showToggle ? r`<button
               class="toggle"
               aria-label=${this.toggleLabel}
+              aria-expanded=${this.expanded ? "true" : "false"}
               @click=${() => this.dispatchEvent(new s())}
             >
               ☰
@@ -94,7 +95,7 @@ var s = class extends Event {
 e([o()], c.prototype, "heading", void 0), e([o()], c.prototype, "subtitle", void 0), e([o({
 	type: Boolean,
 	attribute: "show-toggle"
-})], c.prototype, "showToggle", void 0), e([o({ attribute: "toggle-label" })], c.prototype, "toggleLabel", void 0), e([o({
+})], c.prototype, "showToggle", void 0), e([o({ type: Boolean })], c.prototype, "expanded", void 0), e([o({ attribute: "toggle-label" })], c.prototype, "toggleLabel", void 0), e([o({
 	type: Boolean,
 	reflect: !0,
 	attribute: "drag-region"

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@iyulab/desktop-patterns",
-  "version": "0.3.4",
+  "version": "0.5.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",