@lvl99dotcom/paintcanvas 0.3.0 → 0.4.0

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

@@ -0,0 +1,93 @@
+import { type PropertyValues } from "lit";
+import { PcElement } from "../../base";
+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 */
+export interface MenuItem {
+    /** What `pc-select` gives when it's chosen */
+    value: string;
+    label: string;
+    disabled?: boolean;
+    /** Shown in the cancelling colour, e.g. for deleting */
+    danger?: boolean;
+    /** Makes the item a toggle, showing a checkmark on its left while on */
+    checked?: boolean;
+    /** Name of an icon to show on its left (see `icons`), when it isn't a toggle */
+    icon?: string;
+    /** The action's keyboard shortcut, shown on its right as symbols (e.g. ⌘S) when 3 characters or fewer */
+    shortcut?: KeyCombo;
+}
+/**
+ * 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.
+ * 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.
+ *
+ * @example
+ * html`<pc-menu open .x=${10} .y=${20} label="Layer actions" .items=${items}
+ *   @pc-select=${(e) => act(e.detail.value)} @pc-close=${close}></pc-menu>`
+ */
+export declare class PcMenu extends PcElement {
+    static properties: {
+        open: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        items: {
+            attribute: boolean;
+        };
+        label: {
+            type: StringConstructor;
+        };
+        x: {
+            type: NumberConstructor;
+        };
+        y: {
+            type: NumberConstructor;
+        };
+        anchor: {
+            attribute: boolean;
+        };
+        translations: {
+            attribute: boolean;
+        };
+        icons: {
+            attribute: boolean;
+        };
+        theme: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+    };
+    static styles: import("lit").CSSResultGroup[];
+    open: boolean;
+    items: readonly MenuItem[];
+    /** Names the menu for screen readers */
+    label: string;
+    x: number;
+    y: number;
+    /** The element that opens it (e.g. a `pc-context-menu`'s button): pressing it doesn't count as pressing outside */
+    anchor?: Element;
+    private readonly onPointerDown;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    updated(changed: PropertyValues<this>): void;
+    /** The enabled items' buttons */
+    private buttons;
+    /** Tell listeners the menu should close */
+    close(): void;
+    /** Choose an item, then close */
+    private choose;
+    /** Move focus between items, or close */
+    private onKeyDown;
+    /** An item's left side: a checkmark while a toggle is on, its icon, or empty space */
+    private renderStart;
+    /** An item's right side: its shortcut's label, if short enough */
+    private renderEnd;
+    render(): import("lit").TemplateResult<1>;
+}

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

@@ -0,0 +1,204 @@
+import { PcElement, defineElement, emit } from "../../base/index.js";
+import { ariaKeyShortcut, shortcutLabel } from "../../../lib/utils/shortcuts/index.js";
+import "../PcIcon/index.js";
+import { css, html, nothing } from "lit";
+// src/ui/elements/PcMenu/index.ts
+/** Longest shortcut label shown on a menu item (characters); longer ones are left out */
+var MAX_SHORTCUT_LABEL_LENGTH = 3;
+/**
+* Whether a menu item has something to show on its left: a checkmark or an icon.
+*
+* @example
+* hasStart({ value: "grid", label: "Grid", checked: false }); // true
+*/
+var hasStart = (item) => item.checked !== void 0 || item.icon !== void 0;
+/**
+* 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.
+* 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.
+*
+* @example
+* html`<pc-menu open .x=${10} .y=${20} label="Layer actions" .items=${items}
+*   @pc-select=${(e) => act(e.detail.value)} @pc-close=${close}></pc-menu>`
+*/
+var PcMenu = class extends PcElement {
+	static properties = {
+		...PcElement.properties,
+		open: {
+			type: Boolean,
+			reflect: true
+		},
+		items: { attribute: false },
+		label: { type: String },
+		x: { type: Number },
+		y: { type: Number },
+		anchor: { attribute: false }
+	};
+	static styles = [PcElement.styles, css`
+      :host {
+        position: fixed;
+        z-index: 10;
+        display: none;
+      }
+      :host([open]) {
+        display: block;
+      }
+      [role="menu"] {
+        display: flex;
+        min-width: 160px;
+        max-width: min(320px, calc(100vw - 2 * var(--pc-space-3)));
+        flex-direction: column;
+        padding: var(--pc-space-1) 0;
+        border-radius: var(--pc-radius);
+        background: var(--pc-surface-raised);
+        box-shadow: var(--pc-shadow);
+      }
+      button {
+        display: flex;
+        align-items: baseline;
+        gap: var(--pc-space-2);
+        padding: var(--pc-space-2) var(--pc-space-3);
+        border: 0;
+        background: transparent;
+        color: var(--pc-text);
+        font-family: var(--pc-font);
+        font-size: var(--pc-font-size);
+        text-align: start;
+        cursor: pointer;
+      }
+      button:hover:not(:disabled),
+      button:focus-visible {
+        background: var(--pc-surface-hover);
+        outline: none;
+      }
+      button:focus-visible {
+        box-shadow: inset 0 0 0 var(--pc-focus-width) var(--pc-focus);
+      }
+      button.danger {
+        color: var(--pc-dismiss-text);
+      }
+      .start {
+        /* Icons as tall as the text, so items with icons are no taller */
+        --pc-icon-size: 1.2em;
+        display: inline-flex;
+        width: var(--pc-icon-size);
+        flex: none;
+        align-self: center;
+        justify-content: center;
+      }
+      .label {
+        flex: 1;
+        overflow-wrap: anywhere;
+      }
+      .end {
+        flex: none;
+        color: var(--pc-text-muted);
+        white-space: nowrap;
+      }
+      button:disabled {
+        color: var(--pc-text-muted);
+        cursor: default;
+      }
+    `];
+	onPointerDown = (event) => {
+		const path = event.composedPath();
+		if (this.open && !path.includes(this) && !(this.anchor && path.includes(this.anchor))) this.close();
+	};
+	constructor() {
+		super();
+		this.open = false;
+		this.items = [];
+		this.label = "";
+		this.x = 0;
+		this.y = 0;
+	}
+	connectedCallback() {
+		super.connectedCallback();
+		document.addEventListener("pointerdown", this.onPointerDown, true);
+	}
+	disconnectedCallback() {
+		super.disconnectedCallback();
+		document.removeEventListener("pointerdown", this.onPointerDown, true);
+	}
+	updated(changed) {
+		this.style.left = `${this.x}px`;
+		this.style.top = `${this.y}px`;
+		if (changed.has("open") && this.open) this.buttons()[0]?.focus();
+	}
+	/** The enabled items' buttons */
+	buttons() {
+		return [...this.renderRoot.querySelectorAll("button")].filter((button) => !button.disabled);
+	}
+	/** Tell listeners the menu should close */
+	close() {
+		emit(this, "pc-close");
+	}
+	/** Choose an item, then close */
+	choose(item) {
+		emit(this, "pc-select", { value: item.value });
+		this.close();
+	}
+	/** Move focus between items, or close */
+	onKeyDown(event) {
+		const buttons = this.buttons();
+		const index = buttons.indexOf(this.renderRoot.activeElement);
+		const last = buttons.length - 1;
+		const target = {
+			ArrowDown: index >= last ? 0 : index + 1,
+			ArrowUp: index <= 0 ? last : index - 1,
+			Home: 0,
+			End: last
+		}[event.key];
+		if (target !== void 0) {
+			event.preventDefault();
+			buttons[target]?.focus();
+		} else if (event.key === "Escape" || event.key === "Tab") {
+			event.preventDefault();
+			this.close();
+		}
+	}
+	/** An item's left side: a checkmark while a toggle is on, its icon, or empty space */
+	renderStart(item) {
+		const content = item.checked !== void 0 ? item.checked ? "✔" : nothing : item.icon ? html`<pc-icon name=${item.icon}></pc-icon>` : nothing;
+		return html`<span part="item-start" class="start" aria-hidden="true"
+      >${content}</span
+    >`;
+	}
+	/** An item's right side: its shortcut's label, if short enough */
+	renderEnd(item) {
+		const label = item.shortcut && shortcutLabel(item.shortcut);
+		return label && [...label].length <= 3 ? html`<span part="item-end" class="end" aria-hidden="true"
+          >${label}</span
+        >` : nothing;
+	}
+	render() {
+		const showStart = this.items.some(hasStart);
+		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>`)}
+    </div>`;
+	}
+};
+defineElement("pc-menu", PcMenu);
+export { MAX_SHORTCUT_LABEL_LENGTH, PcMenu };

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

@@ -0,0 +1,118 @@
+import { nothing, type PropertyValues, type TemplateResult } from "lit";
+import { PcElement } from "../../base";
+import { PcPanel } from "../PcPanel";
+import type { SideMode } from "../../layout";
+/** Which way a pane's start, middle and end run */
+export type PaneOrientation = "vertical" | "horizontal";
+/** Which edge of the layout a pane is on: panels opened from its rail, and its floating box, go the other way */
+export type PaneEdge = "left" | "right" | "top" | "bottom";
+/** Event fired when a floating pane is shown or collapsed (detail: `{ collapsed }`) */
+export declare const PANE_COLLAPSE_EVENT = "pc-collapse";
+/**
+ * An area where buttons and panels are shown or docked, e.g. a side of the `<paint-canvas>` layout. Its content goes in
+ * its `start`, `middle` and `end` slots (content without a slot goes at the start), which run down a `vertical` pane
+ * (the default) or across a `horizontal` one; the middle takes the space left.
+ *
+ * Its `mode` sets how it shows its panels (`PcPanel`s, e.g. `<pc-panel-layers>`):
+ * - `docked`: as they are.
+ * - `rail`: as a column of buttons (with each panel's icon, name and badge) that open one panel at a time over the
+ *   canvas, beside the pane (away from its `edge`). Focus moves into the panel; Escape, a press outside it or its
+ *   button again closes it, and focus goes back to the button.
+ * - `floating`: the pane floats over the canvas as a box that collapses to a button (`collapsed`, named with its
+ *   `label`), firing `pc-collapse` when it's shown or collapsed.
+ *
+ * Panes made for one purpose extend it and put their own content in its regions (see `renderStart`, `renderMiddle`
+ * and `renderEnd`), e.g. `<pc-toolbar>`.
+ *
+ * @example
+ * html`<pc-pane edge="right" mode="rail" label="Panels"><pc-panel-layers .app=${app}></pc-panel-layers></pc-pane>`
+ */
+export declare class PcPane extends PcElement {
+    static properties: {
+        orientation: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        mode: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        edge: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        label: {
+            type: StringConstructor;
+        };
+        collapsed: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        openPanel: {
+            state: boolean;
+        };
+        translations: {
+            attribute: boolean;
+        };
+        icons: {
+            attribute: boolean;
+        };
+        theme: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+    };
+    static styles: import("lit").CSSResultGroup[];
+    /** Which way its start, middle and end run (`vertical` by default) */
+    orientation: PaneOrientation;
+    /** How it shows its panels (`docked` by default) */
+    mode: SideMode;
+    /** Which edge of the layout it's on (`left` by default) */
+    edge: PaneEdge;
+    /** Names it, e.g. on its button when floating and collapsed */
+    label: string;
+    /** Whether it's collapsed to a button while floating (true until opened) */
+    collapsed: boolean;
+    /** The panel open from its rail, if any */
+    openPanel?: PcPanel;
+    /** The panels in it */
+    private panels;
+    /** The rail button that opened the open panel, to return focus to */
+    private opener?;
+    private readonly panelObserver;
+    private readonly onDocumentPointerDown;
+    private readonly onKeyDown;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Open a panel over the canvas from its rail button (closing any other), or close it if it's open. Focus moves into
+     * the panel: to the first thing in it that takes focus, or the panel itself.
+     *
+     * @example
+     * pane.togglePanel(pane.querySelector("pc-panel-layers"));
+     */
+    togglePanel(panel: PcPanel, opener?: HTMLElement): void;
+    /**
+     * Close the panel open from the rail, moving focus back to its rail button if asked.
+     */
+    closePanel(returnFocus: boolean): void;
+    /** Show or collapse the floating pane, telling listeners */
+    private toggleCollapsed;
+    /** Follow the panels slotted into it */
+    private onSlotChange;
+    /** Show the panels for the mode: hidden behind the rail (except the open one, beside the pane) or as they are */
+    private syncPanels;
+    protected updated(changed: PropertyValues<this>): void;
+    /** Content of its own at its start, before what's slotted there */
+    protected renderStart(): TemplateResult | typeof nothing;
+    /** Content of its own in its middle, before what's slotted there */
+    protected renderMiddle(): TemplateResult | typeof nothing;
+    /** Content of its own at its end, before what's slotted there */
+    protected renderEnd(): TemplateResult | typeof nothing;
+    /** The rail: a button per panel */
+    private renderRail;
+    /** The button that shows or collapses a floating pane */
+    private renderCollapse;
+    render(): TemplateResult<1>;
+}