@0001-labs/design-system-1 0.3.0-alpha.13 → 0.3.0-alpha.14

package/DS1/4-page/ds-footer.ts

@@ -0,0 +1,165 @@
+// ds-footer.ts
+// A site footer: the brand, columns of links, the language and theme, and the
+// copyright. Drawn by 1-root/footer.css, the same classes a page without
+// scripts writes.
+
+import { LitElement, html, nothing, unsafeCSS } from "lit";
+import { getText } from "../0-face/i18n";
+import { define } from "../0-face/define";
+import "../2-core/ds-cycle";
+import metrics from "../1-root/component-metrics.css?inline";
+import controls from "../1-root/controls.css?inline";
+import styles from "./styles/ds-footer.css?inline";
+
+/** A link in a footer column. */
+export interface FooterLink {
+  /** The words: a translation key, or as written with the footer's `literal`. */
+  label: string;
+  href: string;
+  /** Opens elsewhere: in a new tab, with no referrer. */
+  external?: boolean;
+  /** The page being read: `aria-current="page"`. */
+  current?: boolean;
+}
+
+/** A footer column: a heading and its links. */
+export interface FooterColumn {
+  heading?: string;
+  links: FooterLink[];
+}
+
+/** The settings a footer offers, each a `ds-cycle` of that type. */
+export type FooterPreference = "language" | "theme";
+const PREFERENCES: readonly FooterPreference[] = ["language", "theme"];
+
+/** The preferences named by an attribute: every one when it is present but empty. */
+export function footerPreferences(value: string | null | undefined): FooterPreference[] {
+  if (value == null || value === "false") return [];
+  const named = value.split(/[\s,]+/).filter(Boolean);
+  if (!named.length || named.includes("true")) return [...PREFERENCES];
+  return PREFERENCES.filter(name => named.includes(name));
+}
+
+/**
+ * @element ds-footer
+ * @prop {string} brand - The site's name, a link home: a translation key, or
+ *   the words as they stand with `literal`. The `brand` slot takes its place.
+ * @prop {string} href - Where the brand links. `/` by default.
+ * @prop {string} tagline - A line about the site under the brand.
+ * @prop {FooterColumn[]} columns - The columns of links, eight squares each.
+ * @prop {string} label - The columns' accessible name, as a navigation; without it they are plain lists.
+ * @prop {string} owner - Who holds the copyright: the brand by default.
+ * @prop {number} year - The copyright's year: this year by default.
+ * @prop {string} preferences - `language`, `theme` or both, as `ds-cycle`
+ *   buttons at the end of the last row; present but empty, both.
+ * @prop {boolean} literal - Show the words as written, never looked up.
+ *
+ * @slot brand - The brand, when it is more than words: a logo, a link of the page's own.
+ * @slot preferences - Controls of the page's own beside or in place of the cycles.
+ * @slot legal - The last line, in place of the copyright.
+ *
+ * @example
+ * <ds-footer brand="Name" tagline="What it does" preferences literal
+ *   columns='[{"heading":"Product","links":[{"label":"Download","href":"/download"}]}]'>
+ * </ds-footer>
+ */
+export class Footer extends LitElement {
+  static properties = {
+    brand: { type: String },
+    href: { type: String },
+    tagline: { type: String },
+    columns: { type: Array },
+    label: { type: String },
+    owner: { type: String },
+    year: { type: Number },
+    preferences: { type: String },
+    literal: { type: Boolean, reflect: true },
+  };
+
+  static styles = [unsafeCSS(metrics), unsafeCSS(controls), unsafeCSS(styles)];
+
+  declare brand: string | undefined;
+  declare href: string;
+  declare tagline: string | undefined;
+  declare columns: FooterColumn[];
+  declare label: string | undefined;
+  declare owner: string | undefined;
+  declare year: number | undefined;
+  declare preferences: string | null | undefined;
+  declare literal: boolean;
+
+  private readonly relabel = () => this.requestUpdate();
+
+  constructor() {
+    super();
+    this.href = "/";
+    this.columns = [];
+    this.literal = false;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    window.addEventListener("language-changed", this.relabel);
+    window.addEventListener("translations-loaded", this.relabel);
+  }
+
+  disconnectedCallback() {
+    window.removeEventListener("language-changed", this.relabel);
+    window.removeEventListener("translations-loaded", this.relabel);
+    super.disconnectedCallback();
+  }
+
+  private words(value: string | undefined): string {
+    if (!value) return "";
+    return this.literal ? value : getText(value) || value;
+  }
+
+  private slotted(name: string): boolean {
+    return [...this.children].some(node => node.getAttribute("slot") === name);
+  }
+
+  private link(link: FooterLink) {
+    return html`<li><a href=${link.href} aria-current=${link.current ? "page" : nothing}
+      target=${link.external ? "_blank" : nothing} rel=${link.external ? "noopener noreferrer" : nothing}>${this.words(link.label)}</a></li>`;
+  }
+
+  render() {
+    const columns = (Array.isArray(this.columns) ? this.columns : []).filter(column => column && Array.isArray(column.links));
+    const preferences = footerPreferences(this.preferences);
+    const hasPreferences = preferences.length > 0 || this.slotted("preferences");
+    const owner = this.owner ? this.words(this.owner) : this.words(this.brand);
+    const year = Number.isFinite(this.year) ? this.year : new Date().getFullYear();
+    const brandSlotted = this.slotted("brand");
+    const hasBrand = brandSlotted || Boolean(this.brand) || Boolean(this.tagline);
+    const list = columns.map(column => html`<div class="ds-footer__column" part="column">
+      ${column.heading ? html`<h2 class="ds-footer__heading" part="heading">${this.words(column.heading)}</h2>` : nothing}
+      <ul class="ds-footer__links">${column.links.map(link => this.link(link))}</ul>
+    </div>`);
+    return html`<footer class="ds-footer" part="footer">
+      <div class="ds-footer__brand" part="brand" ?hidden=${!hasBrand}>
+        <slot name="brand" @slotchange=${this.relabel}>${this.brand ? html`<a class="ds-footer__mark" href=${this.href || "/"}>${this.words(this.brand)}</a>` : nothing}</slot>
+        ${this.tagline ? html`<p class="ds-footer__tagline" part="tagline">${this.words(this.tagline)}</p>` : nothing}
+      </div>
+      ${columns.length
+        ? this.label
+          ? html`<nav class="ds-footer__columns" part="columns" aria-label=${this.words(this.label)}>${list}</nav>`
+          : html`<div class="ds-footer__columns" part="columns">${list}</div>`
+        : nothing}
+      <div class="ds-footer__base" part="base">
+        <p class="ds-footer__legal" part="legal"><slot name="legal" @slotchange=${this.relabel}>${owner ? `© ${year} ${owner}` : `© ${year}`}</slot></p>
+        <div class="ds-footer__preferences" part="preferences" ?hidden=${!hasPreferences}>
+          ${preferences.map(type => html`<ds-cycle type=${type}></ds-cycle>`)}
+          <slot name="preferences" @slotchange=${this.relabel}></slot>
+        </div>
+      </div>
+    </footer>`;
+  }
+}
+
+define("ds-footer", Footer);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-footer": Footer;
+  }
+}

package/DS1/4-page/ds-grid.ts

@@ -1,74 +1,54 @@
-// ds-grid.ts
-// Simple grid layout component
-
 import { LitElement, html, unsafeCSS } from "lit";
-import { detectMobileDevice } from "../0-face/device";
+import { styleMap } from "lit/directives/style-map.js";
+import { define } from "../0-face/define";
 import styles from "./styles/ds-grid.css?inline";
 
-declare global {
-  interface CustomElementRegistry {
-    define(name: string, constructor: typeof LitElement): void;
-  }
-  var customElements: CustomElementRegistry;
-}
+export type GridPattern = "grid" | "lines" | "columns" | "dots" | "none";
+const patterns = new Set<GridPattern>(["grid", "lines", "columns", "dots", "none"]);
 
+/** Decorative paper or an alignment overlay; never arranges or captures content. */
 export class Grid extends LitElement {
   static properties = {
-    align: { type: String },
+    align: { type: String, reflect: true },
+    pattern: { type: String, reflect: true },
+    size: { type: Number },
+    rowSize: { type: Number, attribute: "row-size" },
+    color: { type: String },
+    paper: { type: String },
+    contained: { type: Boolean, reflect: true },
   };
-
-  align?: string;
-  private resizeObserver?: () => void;
-  private resizeTimeout?: any;
-
+  declare align: "left" | "center" | "right";
+  declare pattern: GridPattern;
+  declare size: number;
+  declare rowSize: number | undefined;
+  declare color: string;
+  declare paper: string;
+  declare contained: boolean;
   static styles = unsafeCSS(styles);
 
-  connectedCallback() {
-    super.connectedCallback();
-    this.updateMobileClass();
-
-    // Listen for resize events to update mobile class
-    this.resizeObserver = () => {
-      if (this.resizeTimeout) {
-        clearTimeout(this.resizeTimeout);
-      }
-      this.resizeTimeout = setTimeout(() => {
-        this.updateMobileClass();
-      }, 100);
-    };
-    window.addEventListener("resize", this.resizeObserver);
-  }
-
-  disconnectedCallback() {
-    super.disconnectedCallback();
-    if (this.resizeObserver) {
-      window.removeEventListener("resize", this.resizeObserver);
-    }
-    if (this.resizeTimeout) {
-      clearTimeout(this.resizeTimeout);
-    }
-  }
-
-  private updateMobileClass() {
-    const isMobile = detectMobileDevice();
-    if (isMobile) {
-      this.classList.add("mobile");
-      this.classList.remove("desktop");
-    } else {
-      this.classList.add("desktop");
-      this.classList.remove("mobile");
-    }
+  constructor() {
+    super();
+    this.align = "center";
+    this.pattern = "grid";
+    this.size = 20;
+    this.rowSize = undefined;
+    this.color = "";
+    this.paper = "";
+    this.contained = false;
   }
 
   render() {
-    return html``;
+    const size = Number.isFinite(this.size) && this.size > 0 ? this.size : 20;
+    const row = Number.isFinite(this.rowSize) && this.rowSize! > 0 ? this.rowSize! : size;
+    return html`<div aria-hidden="true" class="paper" data-pattern=${patterns.has(this.pattern) ? this.pattern : "grid"}
+      style=${styleMap({
+        "--pitch-x": `${size}px`,
+        "--pitch-y": `${row}px`,
+        "--ink": this.color || "var(--ds-grid-color, color-mix(in srgb, var(--ds-text-color, var(--text-color, currentColor)) 12%, transparent))",
+        "--paper": this.paper || "var(--ds-grid-paper, transparent)",
+      })}></div>`;
   }
 }
 
-customElements.define("ds-grid", Grid);
-
-declare global {
-  interface HTMLElementTagNameMap {
-    "ds-grid": Grid;
-  }
-}
+define("ds-grid", Grid);
+declare global { interface HTMLElementTagNameMap { "ds-grid": Grid } }

package/DS1/4-page/ds-header.ts

@@ -0,0 +1,171 @@
+// ds-header.ts
+// A site header: the brand, the navigation with the page you are on, and the
+// actions, folding into a drawer on a narrow screen. Drawn by 1-root/header.css,
+// the same classes a page without scripts writes, and opened by 0-face/drawer.ts.
+
+import { LitElement, html, nothing, unsafeCSS, type PropertyValues } from "lit";
+import { getText } from "../0-face/i18n";
+import { define } from "../0-face/define";
+import { attachDrawer, type Drawer } from "../0-face/drawer";
+import { markCurrentLink } from "../0-face/header";
+import "../2-core/ds-icon";
+import metrics from "../1-root/component-metrics.css?inline";
+import controls from "../1-root/controls.css?inline";
+import styles from "./styles/ds-header.css?inline";
+
+/** The shared word that names the menu button and its drawer. */
+export const MENU_LABEL = "Menu";
+
+/**
+ * @element ds-header
+ * @prop {string} brand - The site's name, a link home: a translation key, or
+ *   the words as they stand with `literal`. The `brand` slot takes its place.
+ * @prop {string} href - Where the brand links. `/` by default.
+ * @prop {string} label - The navigation's accessible name, when a page has more than one.
+ * @prop {boolean} literal - Show `brand` as written, never looked up.
+ * @prop {boolean} sticky - Stay at the top of the page as it scrolls, on the paper.
+ *
+ * @slot - The navigation: `<a href>` links, one square high. The link to the
+ *   address being read gets `aria-current="page"` unless one is marked.
+ * @slot brand - The brand, when it is more than words: a logo, a link of the page's own.
+ * @slot actions - Buttons or links at the end of the row.
+ *
+ * @fires ds-header-menu - The drawer opened or closed; `detail.open` says which.
+ *
+ * Below thirty squares of width the navigation and actions fold away and a
+ * menu button (the shared word "Menu") opens them in a drawer over the page:
+ * focus stays inside it, Escape, its close button, a link or the screen
+ * widening close it, and the page holds its scroll meanwhile.
+ *
+ * @example
+ * <ds-header brand="Name" literal>
+ *   <a href="/">Home</a>
+ *   <a href="/help">Help</a>
+ *   <ds-button slot="actions" primary href="/download">Download</ds-button>
+ * </ds-header>
+ */
+export class Header extends LitElement {
+  static properties = {
+    brand: { type: String },
+    href: { type: String },
+    label: { type: String },
+    literal: { type: Boolean, reflect: true },
+    sticky: { type: Boolean, reflect: true },
+  };
+
+  static styles = [unsafeCSS(metrics), unsafeCSS(controls), unsafeCSS(styles)];
+
+  declare brand: string | undefined;
+  declare href: string;
+  declare label: string | undefined;
+  declare literal: boolean;
+  declare sticky: boolean;
+
+  private drawer: Drawer | null = null;
+  private readonly relabel = () => this.requestUpdate();
+
+  constructor() {
+    super();
+    this.href = "/";
+    this.literal = false;
+    this.sticky = false;
+  }
+
+  /** Whether the drawer is open. */
+  get menuOpen(): boolean {
+    return this.drawer?.isOpen ?? false;
+  }
+
+  /** Open the drawer (on a narrow screen, where the menu button shows). */
+  openMenu(): void { this.drawer?.open(); }
+
+  /** Close the drawer. */
+  closeMenu(): void { this.drawer?.close(); }
+
+  connectedCallback() {
+    super.connectedCallback();
+    window.addEventListener("language-changed", this.relabel);
+    window.addEventListener("translations-loaded", this.relabel);
+  }
+
+  disconnectedCallback() {
+    window.removeEventListener("language-changed", this.relabel);
+    window.removeEventListener("translations-loaded", this.relabel);
+    this.drawer?.destroy();
+    this.drawer = null;
+    super.disconnectedCallback();
+  }
+
+  protected firstUpdated() {
+    markCurrentLink(this.links());
+  }
+
+  protected updated(changed: PropertyValues<this>) {
+    super.updated(changed);
+    if (this.drawer) return;
+    const root = this.renderRoot;
+    const toggle = root.querySelector<HTMLElement>('[part="toggle"]');
+    const panel = root.querySelector<HTMLDialogElement>('[part="drawer"]');
+    if (!toggle || !panel) return;
+    this.drawer = attachDrawer({
+      toggle,
+      panel,
+      content: () => [...root.querySelectorAll(':is([part="nav"], [part="actions"]):not([hidden])')],
+      onToggle: open => this.dispatchEvent(new CustomEvent("ds-header-menu", { bubbles: true, composed: true, detail: { open } })),
+    });
+  }
+
+  private words(value: string | undefined): string {
+    if (!value) return "";
+    return this.literal ? value : getText(value) || value;
+  }
+
+  /** Light-DOM children that fill a slot: elements, or text that is not blank. */
+  private slotted(name: string): boolean {
+    return [...this.childNodes].some(node => name
+      ? node instanceof Element && node.getAttribute("slot") === name
+      : node instanceof Element ? !node.hasAttribute("slot") : node.nodeType === Node.TEXT_NODE && Boolean(node.textContent?.trim()));
+  }
+
+  private links(): HTMLAnchorElement[] {
+    return [...this.children].filter((child): child is HTMLAnchorElement => child instanceof HTMLAnchorElement && !child.hasAttribute("slot"));
+  }
+
+  private onNavChange = () => {
+    markCurrentLink(this.links());
+    this.requestUpdate();
+  };
+
+  render() {
+    const menu = getText(MENU_LABEL) || MENU_LABEL;
+    const close = getText("Close") || "Close";
+    const hasNav = this.slotted("");
+    const hasActions = this.slotted("actions");
+    const brand = this.slotted("brand")
+      ? html`<span class="ds-header__brand" part="brand"><slot name="brand" @slotchange=${this.relabel}></slot></span>`
+      : this.brand
+        ? html`<a class="ds-header__brand" part="brand" href=${this.href || "/"}>${this.words(this.brand)}</a>`
+        : html`<slot name="brand" @slotchange=${this.relabel}></slot>`;
+    return html`<header class="ds-header${this.sticky ? " ds-header--sticky" : ""}" part="header">
+      ${brand}
+      <nav class="ds-header__nav" part="nav" id="nav" aria-label=${this.label ? this.words(this.label) : nothing} ?hidden=${!hasNav}><slot @slotchange=${this.onNavChange}></slot></nav>
+      <div class="ds-header__actions" part="actions" ?hidden=${!hasActions}><slot name="actions" @slotchange=${this.relabel}></slot></div>
+      <button class="ds-button ds-button--icon ds-header__toggle" part="toggle" type="button" aria-label=${menu} aria-controls="drawer" ?hidden=${!hasNav && !hasActions}>
+        <ds-icon type="menu" size="large" aria-hidden="true"></ds-icon><ds-icon type="close" size="large" aria-hidden="true"></ds-icon>
+      </button>
+      <dialog class="ds-dialog ds-drawer" part="drawer" id="drawer" aria-label=${menu}>
+        <div class="ds-drawer__bar"><button class="ds-button ds-button--icon ds-drawer__close" part="close" type="button" aria-label=${close}>
+          <ds-icon type="close" size="large" aria-hidden="true"></ds-icon>
+        </button></div>
+      </dialog>
+    </header>`;
+  }
+}
+
+define("ds-header", Header);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-header": Header;
+  }
+}

package/DS1/4-page/ds-page.ts

@@ -0,0 +1,184 @@
+import { LitElement, html, unsafeCSS, type PropertyValues } from "lit";
+import { ifDefined } from "lit/directives/if-defined.js";
+import { define } from "../0-face/define";
+import { attachDrawer, type Drawer } from "../0-face/drawer";
+import { getText } from "../0-face/i18n";
+import "../2-core/ds-icon";
+import controls from "../1-root/controls.css?inline";
+import styles from "./styles/ds-page.css?inline";
+
+export type PageLayout = "sidebar" | "split" | "inspector" | "column" | "centered" | "tiles";
+export const PAGE_LAYOUTS: readonly PageLayout[] = ["sidebar", "split", "inspector", "column", "centered", "tiles"];
+
+/**
+ * A standard page: where units stand on the grid. Every layout uses the same
+ * five areas, so content can move between layouts without being rewritten.
+ *
+ * - `slot="header"` runs along the top of the main area
+ * - `slot="nav"` is the leading column: navigation, or the list in `split`
+ * - the default slot is the main area
+ * - `slot="aside"` is the trailing column, shown by `inspector`
+ * - `slot="footer"` runs along the bottom of the main area
+ *
+ * Columns are whole squares: `sidebar` and `inspector` lead with 12, `split`
+ * with 16; `column` is 32 wide and `centered` 16, and `measure` sets either in
+ * whole squares. A centred column stands on a whole square: the room beside it
+ * is rounded down to squares, so the column never straddles a grid line.
+ * `tiles` places each main child in a 12-square tile. Below 30 squares of
+ * width every layout stacks.
+ *
+ * With `drawer`, the navigation folds away below 30 squares instead of
+ * standing above the work: a menu button one square wide stands before the
+ * header and opens it in a drawer over the page (0-face/drawer.ts, the
+ * header's), with focus kept inside, closed by Escape, its close button, a
+ * link or the page widening, and the page's scroll held behind it.
+ *
+ * @element ds-page
+ * @attr layout - `sidebar`, `split`, `inspector`, `column`, `centered` or `tiles`.
+ * @attr divided - Draws a hairline between the columns.
+ * @attr measure - Width of the `column` or `centered` column in whole squares.
+ * @attr fill - Takes its container's height; each column scrolls on its own.
+ * @attr view - Labels each area with its slot name, for inspection.
+ * @attr drawer - Folds the navigation into a drawer on a narrow page.
+ * @attr drawer-label - The menu button's and drawer's name: a translation key, the shared word "Menu" by default.
+ * @fires ds-page-drawer - The drawer opened or closed; `detail.open` says which.
+ *
+ * @example
+ * <ds-page layout="sidebar">
+ *   <ds-sidebar slot="nav" label="Projects"></ds-sidebar>
+ *   <ds-row slot="header" fill>…</ds-row>
+ *   <ds-list>…</ds-list>
+ * </ds-page>
+ */
+export class Page extends LitElement {
+  static properties = {
+    layout: { type: String, reflect: true },
+    divided: { type: Boolean, reflect: true },
+    measure: { type: Number, reflect: true },
+    fill: { type: Boolean, reflect: true },
+    view: { type: Boolean, reflect: true },
+    drawer: { type: Boolean, reflect: true },
+    drawerLabel: { type: String, attribute: "drawer-label" },
+  };
+
+  declare layout: PageLayout;
+  declare divided: boolean;
+  declare measure: number | undefined;
+  declare fill: boolean;
+  declare view: boolean;
+  declare drawer: boolean;
+  declare drawerLabel: string | undefined;
+
+  static styles = [unsafeCSS(controls), unsafeCSS(styles)];
+
+  private navigationDrawer: Drawer | null = null;
+  private readonly relabel = () => this.requestUpdate();
+
+  constructor() {
+    super();
+    this.layout = "sidebar";
+    this.divided = false;
+    this.fill = false;
+    this.view = false;
+    this.drawer = false;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    window.addEventListener("language-changed", this.relabel);
+    window.addEventListener("translations-loaded", this.relabel);
+  }
+
+  disconnectedCallback() {
+    window.removeEventListener("language-changed", this.relabel);
+    window.removeEventListener("translations-loaded", this.relabel);
+    this.navigationDrawer?.destroy();
+    this.navigationDrawer = null;
+    super.disconnectedCallback();
+  }
+
+  /** Whether the navigation drawer is open. */
+  get drawerOpen(): boolean {
+    return this.navigationDrawer?.isOpen ?? false;
+  }
+
+  /** Open the navigation drawer (on a narrow page with `drawer`). */
+  openDrawer(): void { this.navigationDrawer?.open(); }
+
+  /** Close the navigation drawer. */
+  closeDrawer(): void { this.navigationDrawer?.close(); }
+
+  protected updated(changed: PropertyValues<this>) {
+    super.updated(changed);
+    if (!changed.has("drawer")) return;
+    if (!this.drawer) {
+      this.navigationDrawer?.destroy();
+      this.navigationDrawer = null;
+      return;
+    }
+    const root = this.renderRoot;
+    const toggle = root.querySelector<HTMLElement>('[part="drawer-toggle"]');
+    const panel = root.querySelector<HTMLDialogElement>('[part="drawer"]');
+    const nav = root.querySelector('[part="nav"]');
+    if (!toggle || !panel || !nav || this.navigationDrawer) return;
+    this.navigationDrawer = attachDrawer({
+      toggle, panel, content: [nav],
+      onToggle: open => this.dispatchEvent(new CustomEvent("ds-page-drawer", { bubbles: true, composed: true, detail: { open } })),
+    });
+  }
+
+  render() {
+    const label = getText(this.drawerLabel || "Menu") || this.drawerLabel || "Menu";
+    const close = getText("Close") || "Close";
+    return html`
+      <div class="page" part="page" style=${ifDefined(measureStyle(this.measure))}>
+        <div class="bar" part="bar" ?hidden=${!this.drawer}>
+          <button class="ds-button ds-button--icon" part="drawer-toggle" type="button" aria-label=${label} aria-controls="drawer">
+            <ds-icon type="menu" size="large" aria-hidden="true"></ds-icon><ds-icon type="close" size="large" aria-hidden="true"></ds-icon>
+          </button>
+        </div>
+        <dialog class="ds-dialog ds-drawer" part="drawer" id="drawer" aria-label=${label}>
+          <div class="ds-drawer__bar"><button class="ds-button ds-button--icon ds-drawer__close" part="drawer-close" type="button" aria-label=${close}>
+            <ds-icon type="close" size="large" aria-hidden="true"></ds-icon>
+          </button></div>
+        </dialog>
+        <div class="area nav" part="nav" data-area="nav"><slot name="nav"></slot></div>
+        <div class="area header" part="header" data-area="header"><slot name="header"></slot></div>
+        <div class="area main" part="main" data-area="main"><slot></slot></div>
+        <div class="area aside" part="aside" data-area="aside"><slot name="aside"></slot></div>
+        <div class="area footer" part="footer" data-area="footer"><slot name="footer"></slot></div>
+      </div>
+    `;
+  }
+
+  firstUpdated() {
+    // An area with nothing in it takes no room, so a header or footer is optional.
+    this.renderRoot.querySelectorAll("slot").forEach(slot => {
+      const sync = () => slot.parentElement?.toggleAttribute("data-empty", slot.assignedNodes({ flatten: true }).every(empty));
+      slot.addEventListener("slotchange", sync);
+      sync();
+    });
+  }
+}
+
+/**
+ * A measure is a count of squares: 28 is 28 squares, never 28.5 or 28px. A
+ * fraction rounds to the nearest square, and anything that is not a positive
+ * number is ignored so the layout keeps its own width.
+ */
+export function measureStyle(measure: number | null | undefined): string | undefined {
+  const squares = Math.round(Number(measure));
+  return Number.isFinite(squares) && squares >= 1 ? `--ds-page-measure: calc(${squares} * var(--ds-unit))` : undefined;
+}
+
+function empty(node: Node): boolean {
+  return node.nodeType === Node.TEXT_NODE ? !node.textContent?.trim() : node.nodeType !== Node.ELEMENT_NODE;
+}
+
+define("ds-page", Page);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-page": Page;
+  }
+}

package/DS1/4-page/email.ts

@@ -40,9 +40,8 @@ export function gridText(content: string): string {
   return `<div class="ds-email-ink" style="display:block;position:relative;top:2px;padding-left:2px">${content}</div>`
 }
 
-/** Static equivalent of Ezo’s ezo-button[primary] containing ezo-text.
- * Ezo client/design/2-core/styles/ezo-button.css: 16px control, 0.5px horizontal inset.
- * Ezo client/design/2-core/styles/ezo-text.css: centered 15px line in a 16px text box.
+/** Static equivalent of a primary ds-button containing ds-text:
+ * a 16px control with a 0.5px horizontal inset, and a centered 15px line in a 16px text box.
  * Half-pixel vertical padding reproduces that centering without Lit or flexbox.
  */
 export function primaryEmailButton(

package/DS1/4-page/styles/ds-container.css

@@ -9,6 +9,7 @@
   background-color: var(--background-color);
   box-sizing: border-box;
 }
+:host([hidden]) { display: none !important; }
 
 /* Ensure children don't overflow */
 :host ::slotted(*) {

package/DS1/4-page/styles/ds-document.css

@@ -0,0 +1,18 @@
+/* ds-document.css */
+/* The element places the two columns; 1-root/document.css draws them, and the
+   writing in the page is drawn by prose.css, which the element brings. */
+
+:host {
+  display: block;
+  min-width: 0;
+}
+
+:host([hidden]),
+[hidden] {
+  display: none !important;
+}
+
+/* The page's own contents take the list's place. */
+::slotted([slot="contents"]) {
+  margin: 0;
+}