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

package/DS1/2-core/ds-empty.ts

@@ -0,0 +1,120 @@
+// ds-empty.ts
+// An empty state: a place with nothing in it yet, and what to do about it.
+// Drawn by 1-root/empty.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 "./ds-icon";
+import metrics from "../1-root/component-metrics.css?inline";
+import empty from "../1-root/empty.css?inline";
+import styles from "./styles/ds-empty.css?inline";
+
+/** The shared words' title for an empty place, in the current language. */
+export const EMPTY_HEADING = "Nothing here yet";
+
+/**
+ * @element ds-empty
+ * @prop {string} heading - The title: a translation key, or the words as they
+ *   stand with `literal`. Unset, the shared words' "Nothing here yet".
+ * @prop {string} text - The line under it: a translation key, or literal words.
+ * @prop {boolean} literal - Show `heading` and `text` as written, never looked up.
+ * @prop {string} icon - An icon from the library on the square above the title.
+ * @prop {boolean} centered - Centre the words in the space the element stands in.
+ * @prop {number} level - Make the title a heading of this level (1–6).
+ *
+ * @slot - The text, when it needs more than words: a link, a strong word.
+ * @slot heading - The title, as inline content.
+ * @slot icon - An icon of the page's own, in place of `icon`.
+ * @slot actions - The buttons or links that fill the place, on one row.
+ *
+ * @example
+ * <ds-empty icon="search" heading="No results" text="Try another word.">
+ *   <ds-button slot="actions" secondary>Clear the search</ds-button>
+ * </ds-empty>
+ */
+export class Empty extends LitElement {
+  static properties = {
+    heading: { type: String },
+    text: { type: String },
+    literal: { type: Boolean, reflect: true },
+    icon: { type: String },
+    centered: { type: Boolean, reflect: true },
+    level: { type: Number },
+  };
+
+  static styles = [unsafeCSS(metrics), unsafeCSS(empty), unsafeCSS(styles)];
+
+  declare heading: string | undefined;
+  declare text: string | undefined;
+  declare literal: boolean;
+  declare icon: string | undefined;
+  declare centered: boolean;
+  declare level: number | undefined;
+
+  private readonly relabel = () => this.requestUpdate();
+
+  constructor() {
+    super();
+    this.literal = false;
+    this.centered = 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;
+  }
+
+  /**
+   * Whether light-DOM content fills a slot: elements, or text that is not
+   * blank. The blank text between slotted children still counts as assigned
+   * to the default slot and hides its fallback, so `text` is drawn beside the
+   * slot rather than inside it.
+   */
+  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()));
+  }
+
+  render() {
+    const heading = this.heading ? this.words(this.heading) : getText(EMPTY_HEADING) || EMPTY_HEADING;
+    const text = this.words(this.text);
+    const hasIcon = Boolean(this.icon) || this.slotted("icon");
+    const slottedText = this.slotted("");
+    const hasText = Boolean(text) || slottedText;
+    const hasActions = this.slotted("actions");
+    const level = this.level && this.level >= 1 && this.level <= 6 ? Math.round(this.level) : undefined;
+    const changed = () => this.requestUpdate();
+    return html`<div class="ds-empty${this.centered ? " ds-empty--centered" : ""}" part="empty">
+      <div class="ds-empty__icon" part="icon" aria-hidden="true" ?hidden=${!hasIcon}>
+        <slot name="icon" @slotchange=${changed}>${this.icon ? html`<ds-icon size="large" .type=${this.icon}></ds-icon>` : nothing}</slot>
+      </div>
+      <div class="ds-empty__title" part="title" role=${level ? "heading" : nothing} aria-level=${level ?? nothing}>
+        <slot name="heading" @slotchange=${changed}>${heading}</slot>
+      </div>
+      <div class="ds-empty__text" part="text" ?hidden=${!hasText}><slot @slotchange=${changed}></slot>${slottedText ? nothing : text}</div>
+      <div class="ds-empty__actions" part="actions" ?hidden=${!hasActions}><slot name="actions" @slotchange=${changed}></slot></div>
+    </div>`;
+  }
+}
+
+define("ds-empty", Empty);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-empty": Empty;
+  }
+}

package/DS1/2-core/ds-icon.ts

@@ -7,6 +7,15 @@ import { define } from "../0-face/define";
 
 const iconNameToSvgMap: Record<string, string> = { ...immediateIcons }
 const deferred = new Set<string>(deferredIconNames)
+
+/**
+ * Make library drawings available at once, outside the immediate set: a
+ * component that always draws one icon (ds-avatar's person) ships that
+ * drawing with itself, so it never waits for the deferred chunk.
+ */
+export function provideIcons(icons: Readonly<Record<string, string>>): void {
+  for (const [name, svg] of Object.entries(icons)) iconNameToSvgMap[name.toLowerCase()] ??= svg
+}
 let extraReady = false
 let extraLoading: Promise<void> | undefined
 function loadExtraIcons(): Promise<void> {
@@ -30,8 +39,8 @@ function loadExtraIcons(): Promise<void> {
  * one-colour icon is turned over to `currentColor` here, where the component
  * puts it on the page, so it takes the colour of the text around it.
  *
- * An icon with colours of its own is left exactly as drawn. Consistency's block
- * and pattern tiles set dark ink on a coloured ground, and a brand mark keeps
+ * An icon with colours of its own is left exactly as drawn. The block and
+ * pattern tiles set dark ink on a coloured ground, and a brand mark keeps
  * the colours that make it that brand. `white` never counts as a colour: in
  * this set it is the rectangle inside a `<clipPath>`.
  */

package/DS1/2-core/ds-input.ts

@@ -3,10 +3,11 @@
 
 import { LitElement, html, unsafeCSS, type CSSResultGroup, type PropertyDeclarations } from "lit";
 import { live } from "lit/directives/live.js";
+import { styleMap } from "lit/directives/style-map.js";
 import { ifDefined } from "lit/directives/if-defined.js";
 import { define } from "../0-face/define";
-import seeIcon from "../x-icon/ezo-password-visibility-see.svg?url";
-import unseeIcon from "../x-icon/ezo-password-visibility-unsee.svg?url";
+import seeIcon from "../x-icon/password-see.svg?url";
+import unseeIcon from "../x-icon/password-unsee.svg?url";
 import { getText, currentLanguage } from "../0-face/i18n";
 import "./ds-text";
 import styles from "./styles/ds-input.css?inline";
@@ -20,7 +21,16 @@ export class Input extends LitElement {
   private initialValue: string | undefined;
   static properties: PropertyDeclarations = {
     type: { type: String, reflect: true },
+    // A text area: the same field across whole rows.
+    multiline: { type: Boolean, reflect: true },
+    rows: { type: Number },
+    maxRows: { type: Number, attribute: "max-rows" },
+    autoGrow: { type: Boolean, attribute: "auto-grow", reflect: true },
+    wrap: { type: String },
     inputMode: { type: String, attribute: "inputmode" },
+    enterKeyHint: { type: String, attribute: "enterkeyhint" },
+    list: { type: String },
+    suggestions: { attribute: false },
     ariaLabel: { type: String, attribute: "aria-label" },
     ariaLabelledBy: { type: String, attribute: "aria-labelledby" },
     ariaDescribedBy: { type: String, attribute: "aria-describedby" },
@@ -64,9 +74,30 @@ export class Input extends LitElement {
     | "url"
     | "search"
     | "date"
+    | "month"
+    | "week"
     | "time"
     | "datetime-local";
+  declare multiline: boolean;
+  declare rows: number;
+  declare maxRows: number;
+  declare autoGrow: boolean;
+  declare wrap: "soft" | "hard" | "off";
+  private resizeFrame = 0;
+  private measuredWidth = 0;
+  private resizeObserver?: ResizeObserver;
+  private readonly fontsChanged = () => this.resizeToContent();
   declare inputMode: string;
+  /** The return key's label on a touch keyboard: enter, done, go, next, previous, search or send. */
+  declare enterKeyHint: string;
+  /**
+   * The id of a `<datalist>` beside the field. A shadow root keeps the inner
+   * input from reaching it, so its options are mirrored inside, and kept in step.
+   */
+  declare list: string;
+  /** Suggestions offered while typing, as a datalist would. Wins over `list`. */
+  declare suggestions: readonly (string | { value: string; label?: string })[];
+  private listObserver?: MutationObserver;
   declare ariaLabel: string;
   declare ariaLabelledBy: string;
   declare ariaDescribedBy: string;
@@ -104,7 +135,15 @@ export class Input extends LitElement {
   constructor() {
     super();
     this.type = "text";
+    this.multiline = false;
+    this.rows = 3;
+    this.maxRows = 10;
+    this.autoGrow = false;
+    this.wrap = "soft";
     this.inputMode = "";
+    this.enterKeyHint = "";
+    this.list = "";
+    this.suggestions = [];
     this.ariaLabel = "";
     this.ariaLabelledBy = "";
     this.ariaDescribedBy = "";
@@ -161,6 +200,18 @@ export class Input extends LitElement {
 
     // Also listen for translations loaded event
     window.addEventListener("translations-loaded", this.boundHandlers.languageChanged);
+    if (typeof ResizeObserver !== "undefined") {
+      this.resizeObserver = new ResizeObserver((entries) => {
+        if (this.clientWidth !== this.measuredWidth || entries.some(entry => entry.target !== this)) {
+          this.measuredWidth = this.clientWidth;
+          this.resizeToContent();
+        }
+      });
+      this.resizeObserver.observe(this);
+      const metric = this.shadowRoot?.querySelector(".row-metric");
+      if (metric) this.resizeObserver.observe(metric);
+    }
+    document.fonts?.addEventListener("loadingdone", this.fontsChanged);
   }
 
   disconnectedCallback() {
@@ -168,10 +219,24 @@ export class Input extends LitElement {
     this.removeEventListener("click", this.focusFromLabel);
     window.removeEventListener("language-changed", this.boundHandlers.languageChanged);
     window.removeEventListener("translations-loaded", this.boundHandlers.languageChanged);
+    this.listObserver?.disconnect();
+    this.listObserver = undefined;
+    this.resizeObserver?.disconnect();
+    document.fonts?.removeEventListener("loadingdone", this.fontsChanged);
+    cancelAnimationFrame(this.resizeFrame);
   }
 
   firstUpdated(): void {
     if (this.autofocus) this.focus();
+    // A fixed-width field can change scale without changing its width. Measure
+    // one shared row separately from the content height that we set ourselves.
+    const metric = this.shadowRoot?.querySelector(".row-metric");
+    if (metric) this.resizeObserver?.observe(metric);
+  }
+
+  willUpdate(changed: Map<string, unknown>): void {
+    // A multiline field stands on its own by default, in the field treatment.
+    if (changed.has("multiline") && this.multiline && this.variant === "default" && !this.hasAttribute("variant")) this.variant = "field";
   }
 
   updated(changedProperties: Map<string, unknown>) {
@@ -182,14 +247,45 @@ export class Input extends LitElement {
     }
     if (this.initialValue === undefined) this.initialValue = this.value;
     if (changedProperties.has("type") && this.type !== "password") this._passwordVisible = false;
+    if (this.multiline) this.resizeToContent();
+    if (changedProperties.has("list")) this.observeList();
     this.syncForm();
   }
 
+  private listSource(): HTMLDataListElement | null {
+    if (!this.list) return null;
+    const root = this.getRootNode() as Document | ShadowRoot;
+    const source = root.getElementById?.(this.list);
+    return source instanceof HTMLDataListElement ? source : null;
+  }
+
+  private observeList(): void {
+    this.listObserver?.disconnect();
+    this.listObserver = undefined;
+    const source = this.listSource();
+    if (!source || typeof MutationObserver === "undefined") return;
+    this.listObserver = new MutationObserver(() => this.requestUpdate());
+    this.listObserver.observe(source, { childList: true, subtree: true, attributes: true, characterData: true });
+  }
+
+  /** The options the field offers, from `suggestions` or the named datalist. */
+  protected suggestionOptions(): { value: string; label?: string }[] {
+    if (this.suggestions?.length) return this.suggestions.map((option) => (typeof option === "string" ? { value: option } : option));
+    const source = this.listSource();
+    return source ? [...source.options].map((option) => ({ value: option.value, label: option.label !== option.value ? option.label : undefined })) : [];
+  }
+
+  protected renderSuggestions(options: { value: string; label?: string }[]) {
+    return options.length
+      ? html`<datalist id="suggestions">${options.map((option) => html`<option value=${option.value} label=${ifDefined(option.label)}></option>`)}</datalist>`
+      : null;
+  }
+
   protected get input(): HTMLInputElement | HTMLTextAreaElement | null {
     return this.shadowRoot?.querySelector("input, textarea") ?? null;
   }
   protected get isMultiline(): boolean {
-    return false;
+    return this.multiline;
   }
   get selectionStart(): number | null {
     return this.input?.selectionStart ?? null;
@@ -411,7 +507,68 @@ export class Input extends LitElement {
     this.input?.select();
   }
 
+  /** Grow on the row grid, bounded by maxRows; the remainder scrolls. */
+  private resizeToContent(): void {
+    cancelAnimationFrame(this.resizeFrame);
+    const control = this.input;
+    if (!control || !this.multiline) return;
+    if (!this.autoGrow) {
+      control.style.height = "";
+      control.style.overflowY = "";
+      return;
+    }
+    this.resizeFrame = requestAnimationFrame(() => {
+      if (!this.isConnected) return;
+      const computed = getComputedStyle(control);
+      const row =
+        parseFloat(computed.getPropertyValue("--ds-row-height")) ||
+        20 * (parseFloat(computed.getPropertyValue("--ds-sf")) || 1);
+      const minimum = Math.max(1, Math.floor(this.rows || 1)) * row;
+      const maximum = Math.max(minimum, Math.floor(this.maxRows || this.rows || 1) * row);
+      control.style.height = "0px";
+      const border = parseFloat(computed.borderTopWidth) + parseFloat(computed.borderBottomWidth);
+      const needed = Math.ceil((control.scrollHeight + border) / row) * row;
+      control.style.height = `${Math.max(minimum, Math.min(maximum, needed))}px`;
+      control.style.overflowY = needed > maximum ? "auto" : "hidden";
+    });
+  }
+
+  /** The multiline field: a native textarea across whole rows. */
+  protected renderMultiline(hasError: boolean, description: string) {
+    const rows = Math.max(1, Math.floor(this.rows || 1));
+    return html`<span class="row-metric" aria-hidden="true"></span><textarea
+      id="input"
+      part="input"
+      aria-label=${ifDefined(this.accessibleLabel())}
+      aria-invalid=${ifDefined(this.ariaInvalid || (hasError ? "true" : undefined))}
+      aria-describedby=${ifDefined([description ? "description" : "", hasError ? "error" : ""].filter(Boolean).join(" ") || undefined)}
+      inputmode=${ifDefined(this.inputMode || undefined)}
+      enterkeyhint=${ifDefined(this.enterKeyHint || undefined)}
+      spellcheck=${ifDefined(this.spellcheckHint || undefined)}
+      .name=${this.name}
+      .value=${live(this.value)}
+      .placeholder=${this._placeholder || this.placeholder}
+      ?disabled=${this.disabled || this._formDisabled}
+      ?readonly=${this.readonly}
+      ?required=${this.required}
+      ?autofocus=${this.autofocus}
+      autocomplete=${this.autocomplete}
+      minlength=${ifDefined(this.minlength || undefined)}
+      maxlength=${ifDefined(this.maxlength >= 0 ? this.maxlength : undefined)}
+      rows=${rows}
+      wrap=${this.wrap || "soft"}
+      style=${styleMap({ "--ds-textarea-rows": String(rows) })}
+      class=${hasError ? "has-error" : ""}
+      @input=${this._handleInput}
+      @change=${this.handleChange}
+      @focus=${this._handleFocus}
+      @blur=${this._handleBlur}
+    ></textarea>`;
+  }
+
   protected renderControl(hasError: boolean, description: string) {
+    if (this.multiline) return this.renderMultiline(hasError, description);
+    const suggestions = this.suggestionOptions();
     return html`<input
       id="input"
       part="input"
@@ -420,6 +577,8 @@ export class Input extends LitElement {
       aria-invalid=${ifDefined(this.ariaInvalid || (hasError ? "true" : undefined))}
       aria-describedby=${ifDefined([description ? "description" : "", hasError ? "error" : ""].filter(Boolean).join(" ") || undefined)}
       inputmode=${ifDefined(this.inputMode || undefined)}
+      enterkeyhint=${ifDefined(this.enterKeyHint || undefined)}
+      list=${ifDefined(suggestions.length ? "suggestions" : undefined)}
       spellcheck=${ifDefined(this.spellcheckHint || undefined)}
       .name=${this.name}
       .value=${live(this.value)}
@@ -441,7 +600,7 @@ export class Input extends LitElement {
       @keydown=${this.handleKeyDown}
       @focus=${this._handleFocus}
       @blur=${this._handleBlur}
-    />`;
+    />${this.renderSuggestions(suggestions)}`;
   }
 
   render() {
@@ -455,7 +614,7 @@ export class Input extends LitElement {
       .join(" ");
 
     return html`
-      <div class="input-wrapper">
+      <div class=${hasError ? "input-wrapper has-error" : "input-wrapper"}>
         ${
           this.label || this.labelText
             ? html`
@@ -499,7 +658,7 @@ export class Input extends LitElement {
           hasError
             ? html`
                 <div id="error" class="error-message" role="status">
-                  ${this.errorText ? html`<ds-text .text=${this.errorText}></ds-text>` : this.error}
+                  ${this.errorText ? html`<ds-text wrap .text=${this.errorText}></ds-text>` : this.error}
                 </div>
               `
             : null

package/DS1/2-core/ds-kbd.ts

@@ -0,0 +1,78 @@
+// ds-kbd.ts
+// A keyboard shortcut's hint: the shortcut written as the platform writes it
+// (⇧⌘D on Apple platforms, Ctrl+Shift+D elsewhere), drawn by 1-root/kbd.css,
+// the same class a page without scripts puts on a native <kbd>.
+
+import { LitElement, html, unsafeCSS } from "lit";
+import { define } from "../0-face/define";
+import { shortcutLabel, type KeyPlatform } from "../0-face/keys";
+import metrics from "../1-root/component-metrics.css?inline";
+import kbd from "../1-root/kbd.css?inline";
+import styles from "./styles/ds-kbd.css?inline";
+
+/**
+ * @element ds-kbd
+ * @prop {string} shortcut - The shortcut, written once for every platform:
+ *   `mod+shift+d`, `mod+enter`, `escape`, `?`. Unset, the slotted words show
+ *   as written.
+ * @prop {boolean} plain - The words alone in the title grey, with no fill, as
+ *   a menu entry writes its shortcut.
+ * @prop {"apple" | "other"} platform - Write it for this platform rather than
+ *   the device's own (a help page showing both).
+ *
+ * @slot - Words of the page's own, when there is no `shortcut`.
+ *
+ * @example
+ * <ds-kbd shortcut="mod+k"></ds-kbd>
+ */
+export class Kbd extends LitElement {
+  static properties = {
+    shortcut: { type: String },
+    plain: { type: Boolean, reflect: true },
+    platform: { type: String },
+  };
+
+  static styles = [unsafeCSS(metrics), unsafeCSS(kbd), unsafeCSS(styles)];
+
+  declare shortcut: string | undefined;
+  declare plain: boolean;
+  declare platform: KeyPlatform | undefined;
+
+  private readonly relabel = () => this.requestUpdate();
+
+  constructor() {
+    super();
+    this.plain = false;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    // Ctrl, Shift and the other words follow the page's language.
+    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();
+  }
+
+  /** The words the hint shows: the shortcut's label, or empty when it shows its slot. */
+  get label(): string {
+    if (!this.shortcut) return "";
+    try {
+      return shortcutLabel(this.shortcut, this.platform ? { platform: this.platform } : undefined);
+    } catch {
+      return this.shortcut;
+    }
+  }
+
+  render() {
+    const label = this.label;
+    return html`<kbd part="kbd" class=${this.plain ? "ds-kbd ds-kbd--plain" : "ds-kbd"}>${label || html`<slot></slot>`}</kbd>`;
+  }
+}
+
+define("ds-kbd", Kbd);
+declare global { interface HTMLElementTagNameMap { "ds-kbd": Kbd } }

package/DS1/2-core/ds-loading.ts

@@ -0,0 +1,72 @@
+import { LitElement, html, unsafeCSS } from "lit";
+import { define } from "../0-face/define";
+import { getText } from "../0-face/i18n";
+import styles from "./styles/ds-loading.css?inline";
+
+/** The shared word a busy indicator reads without a label of its own. */
+export const LOADING_LABEL = "Loading";
+
+/**
+ * The controls a spinner can stand in: buttons and fields. Inside one, the
+ * spinner is one control high, the size of the icon it stands in for.
+ * `ds-loading.css` names the same controls for the light-DOM markup.
+ */
+export const LOADING_CONTROLS =
+  "button, [role='button'], ds-button, .ds-button, ds-input, ds-select, .ds-field, .ds-input, .ds-select";
+
+/** Whether an element stands in a control, across shadow roots. */
+export function inLoadingControl(element: Element): boolean {
+  let node: Element | null = element.parentElement ?? hostOf(element);
+  while (node) {
+    if (node.closest(LOADING_CONTROLS)) return true;
+    node = hostOf(node);
+  }
+  return false;
+}
+
+function hostOf(element: Element): Element | null {
+  const root = element.getRootNode();
+  return root instanceof ShadowRoot ? root.host : null;
+}
+
+/** @internal Automatic pending-state feedback, not user-insertable content.
+ * Label must describe the current operation; unset, it is the shared word
+ * "Loading" in the page's language. The containing app controls mounting.
+ * A spinner in a button or field is one control high (16px), elsewhere one
+ * square; `--ds-loading-size` sets it outright.
+ * --ds-loading-width/fill/duration preserve the surrounding brand. */
+export class LoadingIndicator extends LitElement {
+  static properties = {
+    label: { type: String },
+    variant: { type: String },
+    inControl: { state: true },
+  };
+  static styles = unsafeCSS(styles);
+  // Declared, not class fields, so Lit's reactive accessors are not shadowed.
+  declare label: string;
+  declare variant: string;
+  declare inControl: boolean;
+  constructor() {
+    super();
+    this.label = "";
+    this.variant = "bar";
+    this.inControl = false;
+  }
+  private readonly relabel = () => this.requestUpdate();
+  connectedCallback() {
+    super.connectedCallback();
+    this.inControl = inLoadingControl(this);
+    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();
+  }
+  render() {
+    const label = this.label || getText(LOADING_LABEL) || LOADING_LABEL;
+    return html`<span class="ds-loading" data-variant=${this.variant} data-context=${this.inControl ? "control" : "page"} role="status" aria-label=${label} aria-busy="true"><span class="ds-loading__fill" aria-hidden="true"></span></span>`;
+  }
+}
+define("ds-loading", LoadingIndicator);