@woosh/meep-engine 2.169.6 → 2.170.0

package/src/view/layout/FloatingPanelView.js

@@ -0,0 +1,251 @@
+import Signal from "../../core/events/signal/Signal.js";
+import { clamp } from "../../core/math/clamp.js";
+import { PointerEvents } from "../../engine/input/devices/events/PointerEvents.js";
+import { DraggableAspect } from "../../engine/ui/DraggableAspect.js";
+import { CSS_ABSOLUTE_POSITIONING } from "../CSS_ABSOLUTE_POSITIONING.js";
+import EmptyView from "../elements/EmptyView.js";
+import View from "../View.js";
+
+/**
+ * Height of the window's title bar, px
+ * @type {number}
+ */
+export const FLOAT_HEADER_SIZE = 26;
+
+/**
+ * Side of the square resize grip in the bottom-right corner, px
+ * @type {number}
+ */
+const RESIZE_GRIP_SIZE = 16;
+
+/**
+ * @type {number}
+ */
+const MIN_WIDTH = 140;
+
+/**
+ * @type {number}
+ */
+const MIN_HEIGHT = FLOAT_HEADER_SIZE + 60;
+
+/**
+ * A window frame for an undocked panel: a title bar over the panel's content, with a grip
+ * to resize it by.
+ *
+ * The title bar carries two gestures, because it answers two questions. The panel's own
+ * handle sits at the left of it, and dragging *that* asks where the panel should go — the
+ * dock takes it over and offers to put the panel back in the layout. The rest of the bar
+ * asks nothing: dragging it moves the window and only moves it, following the cursor with
+ * no docking and no snapping. That handle is the same view the panel wears as a tab when
+ * docked, which is what makes docking a window and docking a tab one gesture rather than
+ * two implementations of one.
+ *
+ * The frame borrows both views it is handed; {@link FloatingPanelView#release} gives them
+ * back when the panel moves on.
+ */
+export class FloatingPanelView extends View {
+    /**
+     * @type {EmptyView}
+     */
+    #header;
+
+    /**
+     * @type {View}
+     */
+    #handle;
+
+    /**
+     * @type {EmptyView}
+     */
+    #content_host;
+
+    /**
+     * @type {View}
+     */
+    #content;
+
+    /**
+     * @type {EmptyView}
+     */
+    #grip;
+
+    /**
+     * @type {DraggableAspect}
+     */
+    #grip_drag;
+
+    /**
+     * @type {DraggableAspect}
+     */
+    #header_drag;
+
+    /**
+     * Frame geometry when the current gesture began, px
+     * @type {number}
+     */
+    #gesture_start_width = 0;
+
+    /**
+     * @type {number}
+     */
+    #gesture_start_height = 0;
+
+    /**
+     * @type {number}
+     */
+    #gesture_start_x = 0;
+
+    /**
+     * @type {number}
+     */
+    #gesture_start_y = 0;
+
+    el = document.createElement('div');
+
+    /**
+     *
+     * @param {View} handle the panel's handle, shown at the left of the title bar
+     * @param {View} content the panel's content
+     */
+    constructor({ handle, content }) {
+        super();
+
+        this.addClass('meep-dock-window');
+
+        // a window stands over the layout at a place of its own; it is never in anyone's flow
+        this.css(CSS_ABSOLUTE_POSITIONING);
+
+        /**
+         * Raised once per gesture that moved the frame — a user action, as opposed to the
+         * reflows a host performs constantly.
+         * @type {Signal}
+         */
+        this.on.moved = new Signal();
+
+        /**
+         * Raised once per gesture that resized the frame.
+         * @type {Signal}
+         */
+        this.on.resized = new Signal();
+
+        /**
+         * Raised when the author reaches into the window, which is them asking for it — the
+         * host decides what standing in front means among the windows it keeps.
+         * @type {Signal}
+         */
+        this.on.raiseRequested = new Signal();
+
+        // in the capture phase: a press on the title bar is swallowed by the gesture that
+        // owns it before it could ever bubble back up to here
+        this.el.addEventListener(PointerEvents.Down, () => this.on.raiseRequested.send0(), true);
+
+        this.#handle = handle;
+        this.#content = content;
+
+        this.#header = new EmptyView({ classList: ['meep-dock-window-header'] });
+        this.#header.css(CSS_ABSOLUTE_POSITIONING);
+        this.#header.addChild(handle);
+
+        this.#content_host = new EmptyView({ classList: ['meep-dock-window-content'] });
+        this.#content_host.css(CSS_ABSOLUTE_POSITIONING);
+
+        content.css(CSS_ABSOLUTE_POSITIONING);
+        this.#content_host.addChild(content);
+
+        this.#grip = new EmptyView({ classList: ['meep-dock-window-grip'] });
+        this.#grip.css(CSS_ABSOLUTE_POSITIONING);
+
+        this.addChild(this.#header);
+        this.addChild(this.#content_host);
+        this.addChild(this.#grip);
+
+        // Moving the window, from the part of the bar the handle does not cover. The handle
+        // swallows its own presses, so a drag that starts on it never reaches this.
+        this.#header_drag = new DraggableAspect({
+            el: this.#header.el,
+            dragStart: () => {
+                this.#gesture_start_x = this.position.x;
+                this.#gesture_start_y = this.position.y;
+            },
+            drag: (position, origin) => {
+                const room = this.parent.size;
+
+                this.position.set(
+                    clamp(this.#gesture_start_x + position.x - origin.x, 0, Math.max(0, room.x - this.size.x)),
+                    clamp(this.#gesture_start_y + position.y - origin.y, 0, Math.max(0, room.y - this.size.y))
+                );
+            },
+            dragEnd: () => {
+                if (this.position.x === this.#gesture_start_x && this.position.y === this.#gesture_start_y) {
+                    return;
+                }
+
+                this.on.moved.send0();
+            }
+        });
+
+        this.#grip_drag = new DraggableAspect({
+            el: this.#grip.el,
+            dragStart: () => {
+                this.#gesture_start_width = this.size.x;
+                this.#gesture_start_height = this.size.y;
+            },
+            drag: (position, origin) => {
+                // a frame is always laid out by a host, and that host is what says how much
+                // room there is to claim — a window resized past it could not be reached again
+                const room = this.parent.size;
+
+                this.size.set(
+                    clamp(this.#gesture_start_width + position.x - origin.x, MIN_WIDTH, Math.max(MIN_WIDTH, room.x - this.position.x)),
+                    clamp(this.#gesture_start_height + position.y - origin.y, MIN_HEIGHT, Math.max(MIN_HEIGHT, room.y - this.position.y))
+                );
+            },
+            dragEnd: () => {
+                if (this.size.x === this.#gesture_start_width && this.size.y === this.#gesture_start_height) {
+                    return;
+                }
+
+                this.on.resized.send0();
+            }
+        });
+
+        this.on.linked.add(this.#header_drag.start, this.#header_drag);
+        this.on.unlinked.add(this.#header_drag.stop, this.#header_drag);
+
+        this.on.linked.add(this.#grip_drag.start, this.#grip_drag);
+        this.on.unlinked.add(this.#grip_drag.stop, this.#grip_drag);
+
+        this.layout();
+
+        this.bindSignal(this.size.onChanged, this.layout, this);
+        this.on.linked.add(this.layout, this);
+    }
+
+    /**
+     * Give back the handle and the content, leaving the frame empty. Called when the panel
+     * moves on to another placement; the frame is finished at that point.
+     */
+    release() {
+        this.#header.removeChild(this.#handle);
+        this.#content_host.removeChild(this.#content);
+    }
+
+    layout() {
+        const width = this.size.x;
+        const height = this.size.y;
+
+        this.#header.position.set(0, 0);
+        this.#header.size.set(width, FLOAT_HEADER_SIZE);
+
+        const content_height = Math.max(0, height - FLOAT_HEADER_SIZE);
+
+        this.#content_host.position.set(0, FLOAT_HEADER_SIZE);
+        this.#content_host.size.set(width, content_height);
+
+        this.#content.position.set(0, 0);
+        this.#content.size.set(width, content_height);
+
+        this.#grip.position.set(width - RESIZE_GRIP_SIZE, height - RESIZE_GRIP_SIZE);
+        this.#grip.size.set(RESIZE_GRIP_SIZE, RESIZE_GRIP_SIZE);
+    }
+}

package/src/view/layout/SplitView.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Two-pane split container with a draggable divider.
+ *
+ * Sizing model: the divider sits at a px offset ({@link SplitView#split}) measured as the
+ * extent of the anchored child ({@link SplitView#anchor}); on container resize the anchored
+ * child keeps its px extent and the other child flexes. A fraction may be supplied as an
+ * initializer ({@link SplitView#fraction}, {@link SplitView.from}) and is converted to px on
+ * the first layout with a usable size.
+ */
+export class SplitView extends EmptyView {
+    /**
+     *
+     * @param {View} a
+     * @param {View} b
+     * @param {'x'|'y'} [type]
+     * @param {number} [fraction] child A's initial share of the main axis
+     * @returns {SplitView}
+     */
+    static from({ a, b, type, fraction }: View): SplitView;
+    constructor();
+    set split(arg: number);
+    /**
+     * The divider offset the last layout actually applied, px (the setter records the
+     * desired offset; reads report what is on screen)
+     * @returns {number}
+     */
+    get split(): number;
+    set direction(arg: "x" | "y");
+    /**
+     * @returns {'x'|'y'}
+     */
+    get direction(): "x" | "y";
+    set anchor(arg: "a" | "b");
+    /**
+     * @returns {'a'|'b'}
+     */
+    get anchor(): "a" | "b";
+    /**
+     * Child A's share of the main axis. Initializer only: converted to a px divider offset
+     * on the next layout with a usable size.
+     * @param {number} v
+     */
+    set fraction(arg: number);
+    set resizable(arg: boolean);
+    /**
+     * @returns {boolean}
+     */
+    get resizable(): boolean;
+    set minA(arg: number);
+    /**
+     * @returns {number}
+     */
+    get minA(): number;
+    set minB(arg: number);
+    /**
+     * @returns {number}
+     */
+    get minB(): number;
+    set childA(arg: View);
+    /**
+     * @returns {View}
+     */
+    get childA(): View;
+    set childB(arg: View);
+    /**
+     * @returns {View}
+     */
+    get childB(): View;
+    layout(): void;
+    #private;
+}
+import EmptyView from "../elements/EmptyView.js";
+//# sourceMappingURL=SplitView.d.ts.map

package/src/view/layout/SplitView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SplitView.d.ts","sourceRoot":"","sources":["../../../../src/view/layout/SplitView.js"],"names":[],"mappings":"AAYA;;;;;;;;GAQG;AACH;IA+EI;;;;;;;OAOG;IACH,6CAFa,SAAS,CAWrB;IAED,cAmDC;IAuDD,uBAKC;IAdD;;;;OAIG;IACH,oBAEC;IApCD,8BAUC;IAjBD;;OAEG;IACH,2BAEC;IAqBD,2BAQC;IAfD;;OAEG;IACH,wBAEC;IA4BD;;;;OAIG;IACH,0BAIC;IASD,4BAIC;IAXD;;OAEG;IACH,yBAEC;IAeD,sBAIC;IAXD;;OAEG;IACH,mBAEC;IAeD,sBAIC;IAXD;;OAEG;IACH,mBAEC;IAeD,sBAQC;IAfD;;OAEG;IACH,mBAEC;IAmBD,sBAQC;IAfD;;OAEG;IACH,mBAEC;IAYD,eA+CC;;CACJ;sBAxWqB,0BAA0B"}

package/src/view/layout/SplitView.js

@@ -0,0 +1,365 @@
+import Signal from "../../core/events/signal/Signal.js";
+import { clamp } from "../../core/math/clamp.js";
+import { DraggableAspect } from "../../engine/ui/DraggableAspect.js";
+import { CSS_ABSOLUTE_POSITIONING } from "../CSS_ABSOLUTE_POSITIONING.js";
+import EmptyView from "../elements/EmptyView.js";
+
+/**
+ * Thickness of the divider bar, px
+ * @type {number}
+ */
+const DIVIDER_THICKNESS = 6;
+
+/**
+ * Two-pane split container with a draggable divider.
+ *
+ * Sizing model: the divider sits at a px offset ({@link SplitView#split}) measured as the
+ * extent of the anchored child ({@link SplitView#anchor}); on container resize the anchored
+ * child keeps its px extent and the other child flexes. A fraction may be supplied as an
+ * initializer ({@link SplitView#fraction}, {@link SplitView.from}) and is converted to px on
+ * the first layout with a usable size.
+ */
+export class SplitView extends EmptyView {
+    /**
+     * 'x' = children side by side, 'y' = stacked
+     * @type {'x'|'y'}
+     */
+    #direction = 'x';
+
+    /**
+     * Which child the divider offset is measured from. That child keeps its px extent
+     * when the container resizes.
+     * @type {'a'|'b'}
+     */
+    #anchor = 'a';
+
+    /**
+     * Desired extent of the anchored child along the main axis, px. Layout clamps this
+     * against the min extents and the available size without overwriting it, so a
+     * transient small container size does not destroy the divider position.
+     * @type {number}
+     */
+    #split = 0;
+
+    /**
+     * The clamped extent the last layout actually applied, px
+     * @type {number}
+     */
+    #applied_split = 0;
+
+    /**
+     * Whether the divider responds to dragging; a host pins the split by turning this off
+     * @type {boolean}
+     */
+    #resizable = true;
+
+    /**
+     * Child A's share of the main axis, applied on the first layout with a non-zero size,
+     * then cleared to -1
+     * @type {number}
+     */
+    #pending_fraction = 0.5;
+
+    /**
+     * Minimum extent of child A along the main axis, px
+     * @type {number}
+     */
+    #min_a = 0;
+
+    /**
+     * Minimum extent of child B along the main axis, px
+     * @type {number}
+     */
+    #min_b = 0;
+
+    /**
+     * @type {View}
+     */
+    #child_a = new EmptyView();
+
+    /**
+     * @type {View}
+     */
+    #child_b = new EmptyView();
+
+    /**
+     * @type {EmptyView}
+     */
+    #divider;
+
+    /**
+     * @type {DraggableAspect}
+     */
+    #divider_drag;
+
+    /**
+     * {@link #split} value at the start of the current divider drag
+     * @type {number}
+     */
+    #drag_start_split = 0;
+
+    /**
+     *
+     * @param {View} a
+     * @param {View} b
+     * @param {'x'|'y'} [type]
+     * @param {number} [fraction] child A's initial share of the main axis
+     * @returns {SplitView}
+     */
+    static from({ a, b, type = 'x', fraction = 0.5 }) {
+        const r = new SplitView();
+
+        r.direction = type;
+        r.fraction = fraction;
+        r.childA = a;
+        r.childB = b;
+
+        return r;
+    }
+
+    constructor() {
+        super({ classList: ['meep-split-view'] });
+
+        /**
+         * Raised once per divider drag that actually moved the split — a user action, as
+         * opposed to the reflows {@link SplitView#layout} performs constantly. A host that
+         * persists its arrangement listens here.
+         * @type {Signal<number>} the new divider offset, px
+         */
+        this.on.resized = new Signal();
+
+        this.#divider = new EmptyView({ classList: ['meep-split-divider'] });
+        this.#divider.css(CSS_ABSOLUTE_POSITIONING);
+
+        this.#stampChild(this.#child_a);
+        this.#stampChild(this.#child_b);
+
+        this.addChild(this.#child_a);
+        this.addChild(this.#child_b);
+        this.addChild(this.#divider);
+
+        this.#divider_drag = new DraggableAspect({
+            el: this.#divider.el,
+            dragStart: () => {
+                this.#drag_start_split = this.#applied_split;
+            },
+            drag: (position, origin) => {
+                if (!this.#resizable) {
+                    return;
+                }
+
+                const delta = this.#direction === 'x' ? position.x - origin.x : position.y - origin.y;
+
+                this.split = this.#anchor === 'a' ? this.#drag_start_split + delta : this.#drag_start_split - delta;
+            },
+            dragEnd: () => {
+                if (this.#applied_split === this.#drag_start_split) {
+                    return;
+                }
+
+                this.on.resized.send1(this.#applied_split);
+            }
+        });
+
+        this.on.linked.add(this.#divider_drag.start, this.#divider_drag);
+        this.on.unlinked.add(this.#divider_drag.stop, this.#divider_drag);
+
+        this.layout();
+
+        this.bindSignal(this.size.onChanged, this.layout, this);
+        this.on.linked.add(this.layout, this);
+    }
+
+    /**
+     *
+     * @param {View} child
+     */
+    #stampChild(child) {
+        child.css(CSS_ABSOLUTE_POSITIONING);
+    }
+
+    /**
+     * @returns {'x'|'y'}
+     */
+    get direction() {
+        return this.#direction;
+    }
+
+    set direction(v) {
+        if (!['x', 'y'].includes(v)) {
+            throw new Error(`Invalid direction '${v}', valid values are 'x' and 'y'`);
+        }
+
+        this.#direction = v;
+
+        this.#divider.setClass('meep-split-divider-y', v === 'y');
+
+        this.layout();
+    }
+
+    /**
+     * @returns {'a'|'b'}
+     */
+    get anchor() {
+        return this.#anchor;
+    }
+
+    set anchor(v) {
+        if (!['a', 'b'].includes(v)) {
+            throw new Error(`Invalid anchor '${v}', valid values are 'a' and 'b'`);
+        }
+
+        this.#anchor = v;
+
+        this.layout();
+    }
+
+    /**
+     * The divider offset the last layout actually applied, px (the setter records the
+     * desired offset; reads report what is on screen)
+     * @returns {number}
+     */
+    get split() {
+        return this.#applied_split;
+    }
+
+    set split(v) {
+        this.#split = v;
+        this.#pending_fraction = -1;
+
+        this.layout();
+    }
+
+    /**
+     * Child A's share of the main axis. Initializer only: converted to a px divider offset
+     * on the next layout with a usable size.
+     * @param {number} v
+     */
+    set fraction(v) {
+        this.#pending_fraction = v;
+
+        this.layout();
+    }
+
+    /**
+     * @returns {boolean}
+     */
+    get resizable() {
+        return this.#resizable;
+    }
+
+    set resizable(v) {
+        this.#resizable = v;
+
+        this.#divider.setClass('meep-split-divider-locked', !v);
+    }
+
+    /**
+     * @returns {number}
+     */
+    get minA() {
+        return this.#min_a;
+    }
+
+    set minA(v) {
+        this.#min_a = v;
+
+        this.layout();
+    }
+
+    /**
+     * @returns {number}
+     */
+    get minB() {
+        return this.#min_b;
+    }
+
+    set minB(v) {
+        this.#min_b = v;
+
+        this.layout();
+    }
+
+    /**
+     * @returns {View}
+     */
+    get childA() {
+        return this.#child_a;
+    }
+
+    set childA(v) {
+        this.removeChild(this.#child_a);
+
+        this.#child_a = v;
+        this.#stampChild(v);
+        this.addChild(v);
+
+        this.layout();
+    }
+
+    /**
+     * @returns {View}
+     */
+    get childB() {
+        return this.#child_b;
+    }
+
+    set childB(v) {
+        this.removeChild(this.#child_b);
+
+        this.#child_b = v;
+        this.#stampChild(v);
+        this.addChild(v);
+
+        this.layout();
+    }
+
+    layout() {
+        const size = this.size;
+
+        const horizontal = this.#direction === 'x';
+
+        const main = horizontal ? size.x : size.y;
+        const cross = horizontal ? size.y : size.x;
+
+        const available = Math.max(0, main - DIVIDER_THICKNESS);
+
+        if (this.#pending_fraction >= 0 && main > 0) {
+            const a_extent = Math.round(available * this.#pending_fraction);
+
+            this.#split = this.#anchor === 'a' ? a_extent : available - a_extent;
+            this.#pending_fraction = -1;
+        }
+
+        const min_anchored = this.#anchor === 'a' ? this.#min_a : this.#min_b;
+        const min_other = this.#anchor === 'a' ? this.#min_b : this.#min_a;
+
+        this.#applied_split = clamp(Math.round(this.#split), min_anchored, Math.max(min_anchored, available - min_other));
+
+        const anchored_extent = Math.min(this.#applied_split, available);
+        const flexible_extent = available - anchored_extent;
+
+        const a_extent = this.#anchor === 'a' ? anchored_extent : flexible_extent;
+        const b_extent = this.#anchor === 'a' ? flexible_extent : anchored_extent;
+
+        if (horizontal) {
+            this.#child_a.size.set(a_extent, cross);
+            this.#child_a.position.set(0, 0);
+
+            this.#divider.size.set(DIVIDER_THICKNESS, cross);
+            this.#divider.position.set(a_extent, 0);
+
+            this.#child_b.size.set(b_extent, cross);
+            this.#child_b.position.set(a_extent + DIVIDER_THICKNESS, 0);
+        } else {
+            this.#child_a.size.set(cross, a_extent);
+            this.#child_a.position.set(0, 0);
+
+            this.#divider.size.set(cross, DIVIDER_THICKNESS);
+            this.#divider.position.set(0, a_extent);
+
+            this.#child_b.size.set(cross, b_extent);
+            this.#child_b.position.set(0, a_extent + DIVIDER_THICKNESS);
+        }
+    }
+}