@lvl99dotcom/paintcanvas 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,221 @@
+import { PcElement } from "../../base";
+import { BlendMode, type default as Layer } from "../../../lib/classes/Layer";
+import type LayerStack from "../../../lib/classes/LayerStack";
+import "../PcDialog";
+import { type DialogChoice } from "../PcDialog";
+import type BackgroundWork from "../../../lib/classes/BackgroundWork";
+/** Blend mode options shown in the layer's select input */
+export declare const BLEND_MODE_OPTIONS: readonly {
+    value: BlendMode;
+    label: string;
+}[];
+/** Actions in the reorder handle's context menu */
+export type LayerAction = "mask" | "duplicate" | "merge" | "clear" | "delete" | "up" | "top" | "down" | "bottom";
+/** Context menu options in display order, with the translation keys of their labels */
+export declare const LAYER_ACTIONS: readonly {
+    action: LayerAction;
+    label: string;
+}[];
+/** Context menu actions that ask first */
+export type ConfirmedAction = "merge" | "clear" | "delete";
+/**
+ * What the user is asked before each confirmed action: the dialog's heading and message, and its choices (the first
+ * does the action), as translation keys. The message is given the layer's `name`.
+ */
+export declare const CONFIRMATIONS: Readonly<Record<ConfirmedAction, {
+    heading: string;
+    message: string;
+    choices: readonly DialogChoice[];
+}>>;
+/** Thumbnail size in CSS pixels */
+export declare const THUMBNAIL_SIZE = 30;
+/** Checkerboard square size in thumbnail pixels */
+export declare const THUMBNAIL_CHECKER_SIZE = 5;
+/** Event a row dispatches when it opens its context menu, so other rows close theirs */
+export declare const LAYER_MENU_OPEN_EVENT = "pc-layer-menu-open";
+/** Event a row dispatches to ask for a mask from the layer's alpha (Cmd/Ctrl + click on the thumbnail or name, or "Create mask") */
+export declare const LAYER_ALPHA_MASK_EVENT = "pc-layer-alpha-mask";
+/** Details of an alpha mask request */
+export interface LayerAlphaMaskDetail {
+    layer: Layer;
+    shiftKey: boolean;
+    altKey: boolean;
+}
+/** How far (CSS pixels) the pointer moves on the reorder handle before it drags the layer, rather than opening the menu */
+export declare const DRAG_THRESHOLD = 4;
+/** Event a row dispatches while its layer is dragged by its reorder handle (detail: {@link LayerDragDetail}) */
+export declare const LAYER_DRAG_EVENT = "pc-layer-drag";
+/** What the layer being dragged would do if dropped where the pointer is */
+export type LayerDropAction = "move" | "duplicate" | "none";
+/** Details of a drag of a layer by its reorder handle */
+export interface LayerDragDetail {
+    layer: Layer;
+    /** The drag started, moved, ended (dropped) or was cancelled (Escape, or the browser cancelled the pointer) */
+    phase: "start" | "move" | "end" | "cancel";
+    /** The pointer's position in the viewport, in CSS pixels */
+    x: number;
+    y: number;
+}
+/** Space kept between the layer actions menu and the window's edges */
+export declare const MENU_MARGIN = 8;
+/**
+ * Where the layer actions menu's top goes: level with the handle, moved up as far as needed to stay in the window
+ * (but never above its top margin).
+ *
+ * @example
+ * menuTop(700, 300, 800); // 492 (moved up to fit)
+ * menuTop(100, 300, 800); // 100
+ */
+export declare const menuTop: (anchorTop: number, menuHeight: number, viewportHeight: number, margin?: number) => number;
+/**
+ * One row in the layers menu: reorder handle, thumbnail and name (then opacity and blend mode under them), alpha lock (padlock) and visibility (eye) icons.
+ * Dragging the handle (with mouse, pen or touch) reorders the layer: the row fires {@link LAYER_DRAG_EVENT} and the
+ * layers menu shows where it will land. Clicking or tapping the handle, pressing Enter or Space on it, or right-clicking
+ * it opens the layer's actions menu (which can also reorder it). Cmd/Ctrl + click on the thumbnail or name (or "Create
+ * mask" in the menu) makes a mask from the layer's pixels. "Merge down…" asks first, then merges the layer into the one
+ * under it (not offered for the bottom layer, or when either is hidden).
+ *
+ * @example
+ * html`<pc-layer-item .stack=${stack} .layer=${layer}></pc-layer-item>`
+ */
+export declare class PcLayerItem extends PcElement {
+    static properties: {
+        stack: {
+            attribute: boolean;
+        };
+        layer: {
+            attribute: boolean;
+        };
+        background: {
+            attribute: boolean;
+        };
+        menuOpen: {
+            state: boolean;
+        };
+        confirming: {
+            state: boolean;
+        };
+        dragging: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        dropAction: {
+            attribute: string;
+            reflect: boolean;
+        };
+        translations: {
+            attribute: boolean;
+        };
+        icons: {
+            attribute: boolean;
+        };
+        theme: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+    };
+    static styles: import("lit").CSSResultGroup[];
+    stack?: LayerStack;
+    layer?: Layer;
+    /** Waits for pauses in drawing to redraw the thumbnail; without it, the thumbnail redraws straight away */
+    background?: BackgroundWork;
+    /** Whether the reorder handle's context menu is open */
+    menuOpen: boolean;
+    /** The action the user is being asked to confirm, if any */
+    confirming?: ConfirmedAction;
+    /** Whether this row's layer is being dragged (set by the layers menu; the row floats with the pointer) */
+    dragging: boolean;
+    /** While this row's layer is dragged: what dropping it now would do (set by the layers menu; shown by the cursor) */
+    dropAction?: LayerDropAction | undefined;
+    /** The pointer pressed on the reorder handle, where it was pressed, and whether it has started dragging */
+    private press?;
+    /** Whether to ignore the next click on the handle (it ended a drag) */
+    private suppressClick;
+    private changes;
+    /** Device pixels per CSS pixel (replaceable for tests) */
+    pixelRatio: () => number;
+    constructor();
+    /**
+     * Run a context menu action. Merging down, clearing and deleting ask for confirmation first (see `confirmed`).
+     */
+    runAction(action: LayerAction): void;
+    /**
+     * Whether a context menu action can be done to the layer now: not merging down the bottom layer (or with a hidden
+     * layer), deleting the only layer, or moving a layer further up or down than it can go.
+     */
+    canRun(action: LayerAction): boolean;
+    /**
+     * Do an action the user confirmed.
+     */
+    confirmed(action: ConfirmedAction): void;
+    private readonly onOutsidePointer;
+    private readonly onKeyDown;
+    /**
+     * Open the context menu on right-click, or close it if open.
+     */
+    private onContextMenu;
+    /**
+     * Open the context menu on a click or tap on the handle (or Enter or Space), or close it if open; a click that ends a
+     * drag does nothing.
+     */
+    private onHandleClick;
+    /**
+     * Open the context menu (closing other rows' menus), or close it if open.
+     */
+    private toggleMenu;
+    disconnectedCallback(): void;
+    /** Tell the layers menu about a drag of this row's layer */
+    private emitDrag;
+    /**
+     * Press on the reorder handle: follow the pointer, which drags once it has moved far enough. The pointer is followed
+     * on the whole window, as browsers don't always grant pointer capture; it is asked for too, so a touch keeps dragging
+     * after leaving the handle.
+     */
+    private onHandlePointerDown;
+    /**
+     * Start dragging once the pointer has moved {@link DRAG_THRESHOLD} pixels, then report where it is.
+     */
+    private readonly onHandlePointerMove;
+    /**
+     * Drop the layer where the pointer is, if it was dragged (a press without dragging opens the menu, on its click).
+     */
+    private readonly onHandlePointerUp;
+    /**
+     * Cancel a drag when the browser cancels the pointer (e.g. a system gesture).
+     */
+    private readonly onHandlePointerCancel;
+    /** Escape cancels a drag, leaving the layer where it was */
+    private readonly onDragKeyDown;
+    /** Stop following the pointer pressed on the handle */
+    private endPress;
+    /**
+     * Start or stop listening for clicks outside and Escape while the menu is open.
+     */
+    private listenOutside;
+    private readonly onScroll;
+    /**
+     * Place the open layer actions menu beside the reorder handle, floating over the layers panel (so the panel's edges
+     * don't cut it off) and kept within the window.
+     */
+    private placeMenu;
+    /**
+     * Ask for a mask following the layer's alpha (Shift adds, Alt subtracts; otherwise it replaces the mask).
+     */
+    private requestMask;
+    /**
+     * Clicking the row selects the layer. Cmd/Ctrl + click on the thumbnail or name also makes a mask from the layer's alpha.
+     */
+    private onRowClick;
+    /**
+     * Rename a layer when the name input changes. Empty names are reverted.
+     */
+    private onRename;
+    updated(changed: Map<PropertyKey, unknown>): void;
+    /**
+     * Draw the layer's image, scaled to fit, on a checkerboard that shows transparency.
+     */
+    drawThumbnail(): void;
+    /** The dialog asking the user to confirm an action, while asking */
+    private renderConfirmation;
+    render(): import("lit").TemplateResult<1>;
+}