@lvl99dotcom/paintcanvas 0.4.0 → 0.5.0

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 {};

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

@@ -1,4 +1,5 @@
 import { PcElement, defineElement, emit } from "../../base/index.js";
+import { markDismissingPress } from "../../dismiss/index.js";
 import { ariaKeyShortcut, shortcutLabel } from "../../../lib/utils/shortcuts/index.js";
 import "../PcIcon/index.js";
 import { css, html, nothing } from "lit";
@@ -6,6 +7,14 @@ import { css, html, nothing } from "lit";
 /** Longest shortcut label shown on a menu item (characters); longer ones are left out */
 var MAX_SHORTCUT_LABEL_LENGTH = 3;
 /**
+* Whether a menu entry is an item that can be chosen.
+*
+* @example
+* isMenuItem({ value: "grid", label: "Grid" }); // true
+* isMenuItem({ type: "divider" }); // false
+*/
+var isMenuItem = (entry) => entry.type === void 0 || entry.type === "item";
+/**
 * Whether a menu item has something to show on its left: a checkmark or an icon.
 *
 * @example
@@ -13,10 +22,46 @@ var MAX_SHORTCUT_LABEL_LENGTH = 3;
 */
 var hasStart = (item) => item.checked !== void 0 || item.icon !== void 0;
 /**
+* A menu item's classes: `danger` and `selected`, when it is.
+*
+* @example
+* itemClasses({ value: "brush", label: "Brush", selected: true }); // "selected"
+*/
+var itemClasses = (item) => [item.danger && "danger", item.selected && "selected"].filter(Boolean).join(" ");
+/**
+* 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 }]
+*/
+var menuSections = (entries) => {
+	const sections = [{
+		items: [],
+		divided: false
+	}];
+	for (const entry of entries) {
+		const current = sections[sections.length - 1];
+		if (isMenuItem(entry)) current.items.push(entry);
+		else if (entry.type === "divider") sections.push({
+			items: [],
+			divided: true
+		});
+		else if (current.items.length === 0 && current.label === void 0) current.label = entry.label;
+		else sections.push({
+			label: entry.label,
+			items: [],
+			divided: false
+		});
+	}
+	return sections.filter((section) => section.divided || section.label !== void 0 || section.items.length);
+};
+/**
 * 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.
 *
@@ -42,6 +87,8 @@ var PcMenu = class extends PcElement {
         position: fixed;
         z-index: 10;
         display: none;
+        user-select: none;
+        -webkit-user-select: none;
       }
       :host([open]) {
         display: block;
@@ -80,6 +127,16 @@ var PcMenu = class extends PcElement {
       button.danger {
         color: var(--pc-dismiss-text);
       }
+      /* The current choice, e.g. the selected tool, like other selected buttons */
+      button.selected,
+      button.selected:hover:not(:disabled),
+      button.selected:focus-visible {
+        background: var(--pc-accent);
+        color: var(--pc-accent-text);
+      }
+      button.selected .end {
+        color: inherit;
+      }
       .start {
         /* Icons as tall as the text, so items with icons are no taller */
         --pc-icon-size: 1.2em;
@@ -102,10 +159,29 @@ var PcMenu = class extends PcElement {
         color: var(--pc-text-muted);
         cursor: default;
       }
+      [role="group"] {
+        display: flex;
+        flex-direction: column;
+      }
+      .heading {
+        padding: var(--pc-space-2) var(--pc-space-3) var(--pc-space-1);
+        color: var(--pc-text-muted);
+        font-family: var(--pc-font);
+        font-size: var(--pc-font-size-small);
+        font-weight: bold;
+        cursor: default;
+      }
+      [role="separator"] {
+        height: 1px;
+        margin: var(--pc-space-1) 0;
+        background: var(--pc-border);
+      }
     `];
 	onPointerDown = (event) => {
 		const path = event.composedPath();
-		if (this.open && !path.includes(this) && !(this.anchor && path.includes(this.anchor))) this.close();
+		if (!this.open || path.includes(this) || this.anchor && path.includes(this.anchor)) return;
+		markDismissingPress(event);
+		this.close();
 	};
 	constructor() {
 		super();
@@ -174,31 +250,47 @@ var PcMenu = class extends PcElement {
           >${label}</span
         >` : nothing;
 	}
+	/** An item's button */
+	renderItem(item, showStart) {
+		return html`<button
+      part="item"
+      type="button"
+      role=${item.checked === void 0 ? "menuitem" : "menuitemcheckbox"}
+      aria-checked=${item.checked === void 0 ? nothing : String(item.checked)}
+      aria-keyshortcuts=${item.shortcut ? ariaKeyShortcut(item.shortcut) : nothing}
+      class=${itemClasses(item) || nothing}
+      aria-current=${item.selected ? "true" : nothing}
+      ?disabled=${item.disabled}
+      data-value=${item.value}
+      @click=${() => this.choose(item)}
+    >
+      ${showStart ? this.renderStart(item) : nothing}<span class="label"
+        >${item.label}</span
+      >${this.renderEnd(item)}
+    </button>`;
+	}
+	/** A section: its divider and label, if any, and its items (grouped under the label for screen readers) */
+	renderSection(section, index, showStart) {
+		const items = section.items.map((item) => this.renderItem(item, showStart));
+		const id = `menu-label-${index}`;
+		return html`${section.divided ? html`<div part="divider" role="separator"></div>` : nothing}${section.label === void 0 ? items : html`<div role="group" aria-labelledby=${id}>
+            <div part="label" class="heading" id=${id} role="presentation">
+              ${section.label}
+            </div>
+            ${items}
+          </div>`}`;
+	}
 	render() {
-		const showStart = this.items.some(hasStart);
+		const showStart = this.items.some((entry) => isMenuItem(entry) && hasStart(entry));
 		return html`<div
       part="menu"
       role="menu"
       aria-label=${this.label}
       @keydown=${this.onKeyDown}
     >
-      ${this.items.map((item) => html`<button
-            part="item"
-            type="button"
-            role=${item.checked === void 0 ? "menuitem" : "menuitemcheckbox"}
-            aria-checked=${item.checked === void 0 ? nothing : String(item.checked)}
-            aria-keyshortcuts=${item.shortcut ? ariaKeyShortcut(item.shortcut) : nothing}
-            class=${item.danger ? "danger" : nothing}
-            ?disabled=${item.disabled}
-            data-value=${item.value}
-            @click=${() => this.choose(item)}
-          >
-            ${showStart ? this.renderStart(item) : nothing}<span class="label"
-              >${item.label}</span
-            >${this.renderEnd(item)}
-          </button>`)}
+      ${menuSections(this.items).map((section, index) => this.renderSection(section, index, showStart))}
     </div>`;
 	}
 };
 defineElement("pc-menu", PcMenu);
-export { MAX_SHORTCUT_LABEL_LENGTH, PcMenu };
+export { MAX_SHORTCUT_LABEL_LENGTH, PcMenu, isMenuItem, menuSections };

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

@@ -0,0 +1,137 @@
+import { type PropertyValues } from "lit";
+import { PcElement } from "../../base";
+/**
+ * A number kept within `min` and `max` and rounded to a multiple of `step` (from `min`).
+ *
+ * @example
+ * fitNumber(300, 1, 256, 1); // 256
+ * fitNumber(12.4, 0, 100, 5); // 10
+ * fitNumber(45.678, -360, 360, 0.01); // 45.68
+ */
+export declare const fitNumber: (value: number, min: number, max: number, step: number) => number;
+/**
+ * A number shown as text that changes when pressed and dragged: right or up raises it, left or down lowers it, a step
+ * per pixel (or `drag-step`), within `min` and `max`. A press that barely moves (a tap or click) turns it into a field to type a value
+ * in: Enter or leaving the field keeps the value, Escape cancels.
+ *
+ * With keyboard focus, the arrow keys change it by `step`, Page Up and Page Down by `pageStep`, Home and End go to
+ * `min` and `max`, and Enter or F2 starts typing.
+ *
+ * Fires `pc-change` (detail: `{ value }`) when the value changes, after changing `value` itself. Bind a value that
+ * may be changed by others with `live()`, e.g. `.value=${live(brush.width)}`, so it's shown again if a listener keeps
+ * it the same.
+ *
+ * @example
+ * html`<pc-number-slider label="Opacity" min="0" max="100" unit="%" .value=${live(50)}
+ *   @pc-change=${(e) => setOpacity(e.detail.value)}></pc-number-slider>`
+ */
+export declare class PcNumberSlider extends PcElement {
+    static properties: {
+        value: {
+            type: NumberConstructor;
+        };
+        min: {
+            type: NumberConstructor;
+        };
+        max: {
+            type: NumberConstructor;
+        };
+        step: {
+            type: NumberConstructor;
+        };
+        pageStep: {
+            type: NumberConstructor;
+            attribute: string;
+        };
+        dragStep: {
+            type: NumberConstructor;
+            attribute: string;
+        };
+        unit: {
+            type: StringConstructor;
+        };
+        text: {
+            type: StringConstructor;
+        };
+        label: {
+            type: StringConstructor;
+        };
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        editing: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        translations: {
+            attribute: boolean;
+        };
+        icons: {
+            attribute: boolean;
+        };
+        theme: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+    };
+    static styles: import("lit").CSSResultGroup[];
+    /** The number */
+    value: number;
+    /** Lowest value (0 by default) */
+    min: number;
+    /** Highest value (100 by default) */
+    max: number;
+    /** How much a pixel of dragging or an arrow key changes it (1 by default) */
+    step: number;
+    /** How much Page Up and Page Down change it (10 steps by default) */
+    pageStep?: number;
+    /** How much a pixel of dragging changes it (`step` by default), e.g. 1 for an angle typed to 0.01 */
+    dragStep?: number;
+    /** Shown after the value, e.g. "%" */
+    unit: string;
+    /** Shown instead of the value and unit, e.g. "30 × 10" */
+    text: string;
+    /** Its name for screen readers, e.g. "Opacity" */
+    label: string;
+    disabled: boolean;
+    /** Whether it's a field being typed in */
+    editing: boolean;
+    /** Whether focus goes back to the slider when typing ends (it doesn't when the field lost focus) */
+    private refocus;
+    private readonly drag;
+    constructor();
+    /** The value as shown: `text`, or the value and unit */
+    get displayText(): string;
+    /**
+     * Set the value (fitted within `min` and `max`, to a multiple of `step`) and tell listeners if it changed.
+     *
+     * @example
+     * slider.change(40); // fires pc-change with { value: 40 }
+     */
+    change(value: number): void;
+    /**
+     * Turn into a field to type a value in, with its text selected.
+     */
+    startEditing(): void;
+    /**
+     * Stop typing, keeping the typed value (if it's a number) unless cancelled.
+     */
+    private stopEditing;
+    /** Start a press, unless disabled */
+    private onPointerDown;
+    /** End a press: one that didn't become a drag starts typing */
+    private onPointerUp;
+    /** Change the value with the arrow keys, Page Up and Page Down, Home and End, or start typing (Enter, F2) */
+    private onSliderKeyDown;
+    /** Keep the typed value with Enter, or cancel with Escape (neither reaches the rest of the page) */
+    private onInputKeyDown;
+    /**
+     * Keep the typed value when the field loses focus, leaving focus where it went. Ignored once typing has ended (some
+     * browsers blur the field as it's removed).
+     */
+    private onInputBlur;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    protected updated(changed: PropertyValues<this>): void;
+    render(): import("lit").TemplateResult<1>;
+}