@lvl99dotcom/paintcanvas 0.4.0 → 0.6.0

package/dist/ui/elements/PcDialogWindow/index.js

@@ -0,0 +1,385 @@
+import { PcElement, defineElement } from "../../base/index.js";
+import { css, html, nothing } from "lit";
+// src/ui/elements/PcDialogWindow/index.ts
+/** Event fired when the user asks to close a dialog window (detail: `{ reason }`); cancel it to keep the window open */
+var DIALOG_DISMISS_EVENT = "pc-dismiss";
+/** Header and footer slots, from start to end */
+var REGIONS = [
+	"start",
+	"middle",
+	"end"
+];
+/** Reads a boolean attribute that's on unless it's `"false"` (for options that are on by default) */
+var onUnlessFalse = {
+	fromAttribute: (value) => value !== null && value !== "false",
+	toAttribute: (value) => value ? "" : "false"
+};
+/** How many open modal windows are keeping the page from scrolling */
+var scrollLocks = 0;
+/** The page's own `overflow` while windows keep it from scrolling, to put back */
+var pageOverflow = "";
+/**
+* Keep the page from scrolling (or let it scroll again once every window that kept it from scrolling has closed).
+*/
+var lockPageScroll = (lock) => {
+	const root = document.documentElement;
+	if (lock && scrollLocks++ === 0) {
+		pageOverflow = root.style.overflow;
+		root.style.overflow = "hidden";
+	} else if (!lock && --scrollLocks === 0) root.style.overflow = pageOverflow;
+};
+/**
+* The element with keyboard focus, inside shadow roots too.
+*/
+var focusedElement = () => {
+	let focused = document.activeElement;
+	while (focused?.shadowRoot?.activeElement) focused = focused.shadowRoot.activeElement;
+	return focused;
+};
+/**
+* Whether a named slot has content (only elements can go in named slots).
+*/
+var hasContent = (slot) => slot.assignedElements({ flatten: true }).length > 0;
+/**
+* A window over the page, built on the browser's `<dialog>`: centred in the viewport, never bigger than it, with a
+* header, a body and a footer. While it's `open`, the rest of the page can't be used or scrolled and keyboard focus stays
+* in it (moving to its first control, and back to where it was once it closes).
+*
+* Content goes in its slots: `header-start`, `header-middle` (which names the window for screen readers, unless it has a
+* `label`; `description` describes it), `header-end`, `body` (or no slot), `footer-start`, `footer-middle` and `footer-end`. The body scrolls when
+* there's too much to fit, keeping the header and footer in view. The header and footer only show with content (or the
+* ⨉ button).
+*
+* Options:
+* - `closable` (on by default; `closable="false"` turns it off): a ⨉ button at the top right.
+* - `shaded`: shade the page under it.
+* - `dismissible` (on by default; `dismissible="false"` turns it off): a press outside it closes it.
+* - `inline`: cover only its nearest positioned ancestor instead of the whole page, which stays usable (and scrolls).
+*
+* The ⨉ button, a press outside it (while `dismissible`) and Escape (while `closable` or `dismissible`) fire a cancellable
+* `pc-dismiss` event (detail: `{ reason }`, one of `close`, `outside` or `escape`); unless it's cancelled, the window
+* closes (`open` becomes false). `--pc-dialog-width` sets its width (fitted to its content by default).
+*
+* @example
+* html`<pc-dialog-window open shaded label="Keyboard shortcuts" @pc-dismiss=${close}>
+*   <h2 slot="header-middle">Keyboard shortcuts</h2>
+*   <pc-shortcut-settings slot="body" .settings=${settings}></pc-shortcut-settings>
+*   <pc-button slot="footer-end" @click=${close}>Done</pc-button>
+* </pc-dialog-window>`
+*/
+var PcDialogWindow = class extends PcElement {
+	static properties = {
+		...PcElement.properties,
+		open: {
+			type: Boolean,
+			reflect: true
+		},
+		closable: {
+			converter: onUnlessFalse,
+			reflect: true
+		},
+		shaded: {
+			type: Boolean,
+			reflect: true
+		},
+		dismissible: {
+			converter: onUnlessFalse,
+			reflect: true
+		},
+		inline: {
+			type: Boolean,
+			reflect: true
+		},
+		label: { type: String },
+		description: { type: String },
+		filled: { state: true }
+	};
+	static styles = [PcElement.styles, css`
+      :host {
+        display: contents;
+        --pc-dialog-gutter: var(--pc-space-3);
+      }
+      /* Inline: over the nearest positioned ancestor, while open */
+      :host([inline]) {
+        position: absolute;
+        z-index: 20;
+        inset: 0;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        box-sizing: border-box;
+        padding: var(--pc-dialog-gutter);
+      }
+      :host([inline]:not([open])) {
+        display: none;
+      }
+      :host([inline][shaded]) {
+        background: var(--pc-backdrop);
+      }
+      dialog {
+        max-width: none;
+        max-height: none;
+        margin: auto;
+        padding: 0;
+        border: 0;
+        background: transparent;
+        color: var(--pc-text);
+        overflow: visible;
+      }
+      dialog[open] {
+        display: flex;
+      }
+      :host([inline]) dialog {
+        position: static;
+        max-height: 100%;
+        margin: 0;
+      }
+      dialog::backdrop {
+        background: transparent;
+      }
+      :host([shaded]) dialog::backdrop {
+        background: var(--pc-backdrop);
+      }
+      .window {
+        display: flex;
+        box-sizing: border-box;
+        flex-direction: column;
+        gap: var(--pc-space-2);
+        width: var(--pc-dialog-width, auto);
+        max-width: calc(100vw - 2 * var(--pc-dialog-gutter));
+        /* The visible viewport's height where browsers have it, so phones' toolbars don't cover the footer */
+        max-height: calc(100vh - 2 * var(--pc-dialog-gutter));
+        max-height: calc(100dvh - 2 * var(--pc-dialog-gutter));
+        padding: var(--pc-space-3);
+        border-radius: var(--pc-radius);
+        background: var(--pc-surface-raised);
+        color: var(--pc-text);
+        box-shadow: var(--pc-shadow);
+        font-family: var(--pc-font);
+        font-size: var(--pc-font-size);
+      }
+      :host([inline]) .window {
+        max-height: 100%;
+      }
+      header,
+      footer {
+        display: flex;
+        flex: none;
+        align-items: center;
+        gap: var(--pc-space-2);
+      }
+      [hidden] {
+        display: none !important;
+      }
+      .start,
+      .end {
+        display: flex;
+        flex: none;
+        align-items: center;
+        gap: var(--pc-space-2);
+      }
+      .middle {
+        display: flex;
+        flex: 1;
+        flex-direction: column;
+        gap: var(--pc-space-2);
+        min-width: 0;
+      }
+      .end {
+        margin-left: auto;
+      }
+      /* Scrolls when there's too much to fit; the padding keeps focus outlines in view */
+      .body {
+        flex: 1 1 auto;
+        min-height: 0;
+        margin: calc(-1 * var(--pc-space-1));
+        padding: var(--pc-space-1);
+        overflow: auto;
+        overscroll-behavior: contain;
+      }
+      button.close {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: var(--pc-control-size);
+        height: var(--pc-control-size);
+        padding: 0;
+        border: 0;
+        border-radius: var(--pc-radius-pill);
+        background: transparent;
+        color: var(--pc-text);
+        font: inherit;
+        font-size: 20px;
+        line-height: 1;
+        cursor: pointer;
+      }
+      button.close:hover {
+        background: var(--pc-surface-hover);
+      }
+      button.close:focus-visible {
+        outline: var(--pc-focus-width) solid var(--pc-focus);
+      }
+    `];
+	/** Whether it's keeping the page from scrolling */
+	scrollLocked = false;
+	/** What had focus before it opened, to give it back to if it's taken out of the page while open */
+	returnFocus = null;
+	/** Whether the `<dialog>` was last shown inline (not modal) */
+	shownInline = false;
+	/** Whether the press being made started outside the window */
+	pressedOutside = false;
+	constructor() {
+		super();
+		this.open = false;
+		this.closable = true;
+		this.shaded = false;
+		this.dismissible = true;
+		this.inline = false;
+		this.filled = /* @__PURE__ */ new Set();
+	}
+	/** The `<dialog>` it's built on */
+	get dialog() {
+		return this.renderRoot.querySelector("dialog");
+	}
+	/**
+	* Ask to close the window, as the user would: fires `pc-dismiss` (detail: `{ reason }`), and closes it unless that's
+	* cancelled.
+	*
+	* @example
+	* dialogWindow.requestClose("close");
+	*/
+	requestClose(reason) {
+		const event = new CustomEvent(DIALOG_DISMISS_EVENT, {
+			detail: { reason },
+			cancelable: true
+		});
+		if (this.dispatchEvent(event)) this.open = false;
+	}
+	connectedCallback() {
+		super.connectedCallback();
+		if (this.hasUpdated) this.syncOpen();
+	}
+	disconnectedCallback() {
+		super.disconnectedCallback();
+		const dialog = this.dialog;
+		if (dialog?.open) {
+			dialog.close();
+			if (this.returnFocus?.isConnected) this.returnFocus.focus();
+		}
+		this.syncScrollLock();
+	}
+	firstUpdated(changed) {
+		super.firstUpdated(changed);
+		this.updateRegions();
+	}
+	updated(changed) {
+		super.updated(changed);
+		if (changed.has("open") || changed.has("inline")) this.syncOpen();
+	}
+	/**
+	* Show or close the `<dialog>` to match `open` (modal unless `inline`), keeping the page from scrolling while a modal
+	* window is open.
+	*/
+	syncOpen() {
+		const dialog = this.dialog;
+		if (dialog.open && (!this.open || this.shownInline !== this.inline)) dialog.close();
+		if (this.open && !dialog.open && this.isConnected) {
+			this.shownInline = this.inline;
+			this.returnFocus = focusedElement();
+			if (this.inline) dialog.show();
+			else dialog.showModal();
+		}
+		this.syncScrollLock();
+	}
+	/** Keep the page from scrolling while a modal window is open in it, and let it scroll again otherwise */
+	syncScrollLock() {
+		const lock = this.open && !this.inline && this.isConnected;
+		if (lock === this.scrollLocked) return;
+		this.scrollLocked = lock;
+		lockPageScroll(lock);
+	}
+	/** Note which header and footer slots have content: only those (and the header and footer with them) are shown */
+	updateRegions() {
+		this.filled = new Set([...this.renderRoot.querySelectorAll("slot[name]")].filter(hasContent).map((slot) => slot.name));
+	}
+	/** Whether any of a header's or footer's slots have content */
+	hasRegion(region) {
+		return REGIONS.some((place) => this.filled.has(`${region}-${place}`));
+	}
+	onKeyDown = (event) => {
+		if (event.key !== "Escape" || event.defaultPrevented) return;
+		event.preventDefault();
+		if (this.closable || this.dismissible) this.requestClose("escape");
+	};
+	onCancel = (event) => {
+		event.preventDefault();
+		if (this.closable || this.dismissible) this.requestClose("escape");
+	};
+	onClose = () => {
+		if (this.isConnected && this.open && !this.dialog?.open) this.open = false;
+	};
+	onPointerDown = (event) => {
+		this.pressedOutside = event.target === event.currentTarget;
+	};
+	onClick = (event) => {
+		const outside = this.pressedOutside && event.target === event.currentTarget;
+		this.pressedOutside = false;
+		if (outside && this.dismissible) this.requestClose("outside");
+	};
+	/** A header or footer's start, middle and end slots */
+	renderRegion(region, end = nothing) {
+		return REGIONS.map((place) => html`<div
+          class=${place}
+          part="${region}-${place}"
+          ?hidden=${!this.filled.has(`${region}-${place}`) && (place !== "end" || end === nothing)}
+          id=${region === "header" && place === "middle" ? "title" : nothing}
+        >
+          <slot
+            name="${region}-${place}"
+            @slotchange=${this.updateRegions}
+          ></slot>
+          ${place === "end" ? end : nothing}
+        </div>`);
+	}
+	render() {
+		const closeButton = this.closable ? html`<button
+          type="button"
+          class="close"
+          part="close"
+          aria-label=${this.t("paintCanvas.common.close")}
+          title=${this.t("paintCanvas.common.close")}
+          @click=${() => this.requestClose("close")}
+        >
+          ⨉
+        </button>` : nothing;
+		return html`<dialog
+      part="dialog"
+      aria-label=${this.label || nothing}
+      aria-labelledby=${this.label ? nothing : "title"}
+      aria-description=${this.description || nothing}
+      @keydown=${this.onKeyDown}
+      @cancel=${this.onCancel}
+      @close=${this.onClose}
+      @pointerdown=${this.onPointerDown}
+      @click=${this.onClick}
+    >
+      <div class="window" part="window">
+        <header
+          part="header"
+          ?hidden=${!this.hasRegion("header") && !this.closable}
+        >
+          ${this.renderRegion("header", closeButton)}
+        </header>
+        <div class="body" part="body">
+          <slot name="body"></slot>
+          <slot></slot>
+        </div>
+        <footer part="footer" ?hidden=${!this.hasRegion("footer")}>
+          ${this.renderRegion("footer")}
+        </footer>
+      </div>
+    </dialog>`;
+	}
+};
+defineElement("pc-dialog-window", PcDialogWindow);
+export { DIALOG_DISMISS_EVENT, PcDialogWindow };

package/dist/ui/elements/PcInputSettings/index.d.ts

@@ -1,6 +1,7 @@
 import { nothing } from "lit";
 import { PcElement } from "../../base";
 import { type InputSettingsData } from "../../../lib/classes/InputSettings";
+import type { UiSettingsLike } from "../../../lib/classes/UiSettings";
 /** Settings `pc-input-settings` can change: PaintCanvas's `InputSettings`, or anything with the same data and `update` */
 export interface InputSettingsLike extends EventTarget {
     readonly data: Readonly<InputSettingsData>;
@@ -12,6 +13,9 @@ export interface InputSettingsLike extends EventTarget {
  * and the language. Changes apply straight away. Hide focus pen mode or the language with `focusPen` and `languages`
  * set to false. Fires `pc-language-change` (with the locale) when the user picks a language.
  *
+ * With `ui` (e.g. the canvas's `ui`), the picked language is kept there, and used whenever it changes (e.g. when
+ * restored), so it's kept with the other app settings.
+ *
  * @example
  * html`<pc-input-settings .settings=${canvas.input}></pc-input-settings>`
  */
@@ -20,6 +24,9 @@ export declare class PcInputSettings extends PcElement {
         settings: {
             attribute: boolean;
         };
+        ui: {
+            attribute: boolean;
+        };
         focusPen: {
             type: BooleanConstructor;
         };
@@ -46,6 +53,8 @@ export declare class PcInputSettings extends PcElement {
     static styles: import("lit").CSSResultGroup[];
     /** The settings shown and changed */
     settings?: InputSettingsLike;
+    /** Where the language is kept, if anywhere (e.g. the canvas's `ui`) */
+    ui?: UiSettingsLike;
     /** Whether to show focus pen mode (default true) */
     focusPen: boolean;
     /** Whether to show the language (default true) */
@@ -55,7 +64,11 @@ export declare class PcInputSettings extends PcElement {
     /** Name of the zoom modifier key ("Cmd" or "Ctrl", detected by default) */
     modifier: string;
     private changes;
+    /** The kept language last used, so it's only switched to once */
+    private usedLocale?;
     constructor();
+    /** Use the kept language when it changes */
+    protected willUpdate(): void;
     /** A checkbox for an on/off setting */
     private toggle;
     /**

package/dist/ui/elements/PcInputSettings/index.js

@@ -18,6 +18,9 @@ var ACTION_KEYS = {
 * and the language. Changes apply straight away. Hide focus pen mode or the language with `focusPen` and `languages`
 * set to false. Fires `pc-language-change` (with the locale) when the user picks a language.
 *
+* With `ui` (e.g. the canvas's `ui`), the picked language is kept there, and used whenever it changes (e.g. when
+* restored), so it's kept with the other app settings.
+*
 * @example
 * html`<pc-input-settings .settings=${canvas.input}></pc-input-settings>`
 */
@@ -25,6 +28,7 @@ var PcInputSettings = class extends PcElement {
 	static properties = {
 		...PcElement.properties,
 		settings: { attribute: false },
+		ui: { attribute: false },
 		focusPen: { type: Boolean },
 		languages: { type: Boolean },
 		touch: { type: Boolean },
@@ -67,7 +71,9 @@ var PcInputSettings = class extends PcElement {
         outline-offset: 2px;
       }
     `];
-	changes = new ChangeController(this, () => [this.settings]);
+	changes = new ChangeController(this, () => [this.settings, this.ui]);
+	/** The kept language last used, so it's only switched to once */
+	usedLocale;
 	constructor() {
 		super();
 		this.focusPen = true;
@@ -75,6 +81,13 @@ var PcInputSettings = class extends PcElement {
 		this.touch = isTouchDevice();
 		this.modifier = zoomModifierName();
 	}
+	/** Use the kept language when it changes */
+	willUpdate() {
+		const locale = this.ui?.data.locale;
+		if (locale === void 0 || locale === this.usedLocale) return;
+		this.usedLocale = locale;
+		if (locale !== this.translations.locale) this.translations.setLocale(locale);
+	}
 	/** A checkbox for an on/off setting */
 	toggle(data, key, label) {
 		return html`<label class="toggle">
@@ -123,6 +136,8 @@ var PcInputSettings = class extends PcElement {
         name="language"
         @change=${(e) => {
 			const locale = e.target.value;
+			this.usedLocale = locale;
+			this.ui?.update({ locale });
 			translations.setLocale(locale).then(() => emit(this, "pc-language-change", { locale }));
 		}}
       >

package/dist/ui/elements/PcMenu/index.d.ts

@@ -4,8 +4,10 @@ import { type KeyCombo } from "../../../lib/utils/shortcuts";
 import "../PcIcon";
 /** Longest shortcut label shown on a menu item (characters); longer ones are left out */
 export declare const MAX_SHORTCUT_LABEL_LENGTH = 3;
-/** An item in a context menu */
+/** An item in a menu that can be chosen */
 export interface MenuItem {
+    /** Optional; items are the default kind of menu entry */
+    type?: "item";
     /** What `pc-select` gives when it's chosen */
     value: string;
     label: string;
@@ -18,12 +20,49 @@ export interface MenuItem {
     icon?: string;
     /** The action's keyboard shortcut, shown on its right as symbols (e.g. ⌘S) when 3 characters or fewer */
     shortcut?: KeyCombo;
+    /** Marks the current choice (e.g. the selected tool) with the `selected` class and a purple background */
+    selected?: boolean;
 }
+/** A non-interactive label naming the items after it (up to the next label or divider), e.g. "Tools" */
+export interface MenuLabel {
+    type: "label";
+    label: string;
+}
+/** A non-interactive line between items */
+export interface MenuDivider {
+    type: "divider";
+}
+/** Anything a menu can show: an item, a label or a divider */
+export type MenuEntry = MenuItem | MenuLabel | MenuDivider;
+/** A run of items, with the label before them if there is one */
+interface MenuSection {
+    label?: string;
+    items: MenuItem[];
+    /** Whether a divider comes before it */
+    divided: boolean;
+}
+/**
+ * Whether a menu entry is an item that can be chosen.
+ *
+ * @example
+ * isMenuItem({ value: "grid", label: "Grid" }); // true
+ * isMenuItem({ type: "divider" }); // false
+ */
+export declare const isMenuItem: (entry: MenuEntry) => entry is MenuItem;
+/**
+ * Split menu entries into sections: a label or divider starts a new one.
+ *
+ * @example
+ * menuSections([{ type: "label", label: "Tools" }, { value: "brush", label: "Brush" }]);
+ * // [{ label: "Tools", items: [{ value: "brush", label: "Brush" }], divided: false }]
+ */
+export declare const menuSections: (entries: readonly MenuEntry[]) => MenuSection[];
 /**
  * A list of menu items, e.g. a layer's actions (see `pc-context-menu` for a button that opens one). While `open`, it shows its items at `x`, `y` (in the page's viewport) and takes
  * keyboard focus: arrow keys, Home and End move between items, Enter or Space chooses one, and Escape or Tab closes it.
  * Items can show a checkmark (toggles) or an icon on their left, and their keyboard shortcut on their right; long
- * labels wrap.
+ * labels wrap. Non-interactive labels (`{ type: "label", label }`, small bold text naming the items after them) and
+ * dividers (`{ type: "divider" }`) can go between items; keyboard focus skips them.
  * Fires `pc-select` with the chosen item's value, and `pc-close` when it should close (after choosing, Escape, Tab, or a
  * press outside it and its `anchor`). The implementer sets `open` to false in response.
  *
@@ -65,7 +104,8 @@ export declare class PcMenu extends PcElement {
     };
     static styles: import("lit").CSSResultGroup[];
     open: boolean;
-    items: readonly MenuItem[];
+    /** Items, labels and dividers, in order */
+    items: readonly MenuEntry[];
     /** Names the menu for screen readers */
     label: string;
     x: number;
@@ -89,5 +129,10 @@ export declare class PcMenu extends PcElement {
     private renderStart;
     /** An item's right side: its shortcut's label, if short enough */
     private renderEnd;
+    /** An item's button */
+    private renderItem;
+    /** A section: its divider and label, if any, and its items (grouped under the label for screen readers) */
+    private renderSection;
     render(): import("lit").TemplateResult<1>;
 }
+export {};