v0.0.2

Author: texodus

dist/common/calculate_intersect.d.ts

@@ -0,0 +1,18 @@
+import type { LayoutPath, LayoutDivider, Layout } from "./layout_config.ts";
+/**
+ * Determines which panel or divider is located at a given position in the
+ * layout.
+ *
+ * @param row - Vertical position as a fraction (0-1) of the container
+ * height
+ * @param column - Horizontal position as a fraction (0-1) of the
+ * container width
+ * @param layout - The layout tree to search
+ * @param check_dividers - Whether `LayoutDivider` intersection should be
+ * checked, which oyu may not want for e.g. `drop` actions.
+ * @returns The panel path if over a panel, a divider if over a resizable
+ * boundary, or null if outside all panels
+ */
+export declare function calculate_intersection(column: number, row: number, layout: Layout, check_dividers: false): LayoutPath;
+export declare function calculate_intersection(column: number, row: number, layout: Layout, check_dividers: true): LayoutPath | null | LayoutDivider;
+export declare function calculate_intersection(column: number, row: number, layout: Layout, check_dividers?: boolean): LayoutPath | null | LayoutDivider;

dist/common/calculate_split.d.ts

@@ -0,0 +1,15 @@
+import { type Layout, type LayoutPath } from "./layout_config";
+/**
+ * Calculates an insertion point (which may involve splitting a single
+ * `"child-panel"` into a new `"split-panel"`), based on the  cursor position.
+ * *
+ * @param col - The cursor column.
+ * @param row - The cursor row.
+ * @param panel - The `Layout` to insert into.
+ * @param slot - The slot identifier where the insert should occur
+ * @param drop_target - The `LayoutPath` (from `calculateIntersect`) of the
+ * panel to either insert next to, or split by.
+ * @returns A new `LayoutPath` reflecting the updated (maybe) `"split-panel"`,
+ * which is enough to draw the overlay.
+ */
+export declare function calculate_split(col: number, row: number, panel: Layout, slot: string, drop_target: LayoutPath): LayoutPath;

dist/common/flatten.d.ts

@@ -0,0 +1,13 @@
+import type { Layout } from "./layout_config.ts";
+/**
+ * Flattens the layout tree by merging parent and child split panels that have
+ * the same orientation and type.
+ *
+ * When a split panel contains a child split panel with the same orientation,
+ * they are merged into a single split panel. The sizes array is scaled
+ * correctly to maintain proportions.
+ *
+ * @param layout - The layout tree to flatten
+ * @returns A new flattened layout tree (original is not mutated).
+ */
+export declare function flatten(layout: Layout): Layout;

dist/common/generate_grid.d.ts

@@ -0,0 +1,32 @@
+import { type Layout } from "./layout_config.ts";
+/**
+ * Generates CSS Grid styles to render a layout tree.
+ * Creates grid-template-rows, grid-template-columns, and positioning rules for
+ * all child panels.
+ *
+ * @param layout - The layout tree to convert to CSS
+ * @param round - If true, rounds percentages to whole numbers. Useful for
+ * avoiding sub-pixel rendering issues. Defaults to false.
+ * @returns CSS string containing :host and ::slotted rules implementing the
+ * layout.
+ *
+ * @example
+ * ```typescript
+ * const layout = {
+ *   type: "split-panel",
+ *   orientation: "horizontal",
+ *   children: [
+ *     { type: "child-panel", child: "sidebar" },
+ *     { type: "child-panel", child: "main" }
+ *   ],
+ *   sizes: [0.25, 0.75]
+ * };
+ *
+ * const css = create_css_grid_layout(layout);
+ * // Returns CSS like:
+ * // :host { display: grid; grid-template-columns: 25% 75%; ... }
+ * // :host ::slotted([slot=sidebar]) { grid-column: 1; grid-row: 1; }
+ * // :host ::slotted([slot=main]) { grid-column: 2; grid-row: 1; }
+ * ```
+ */
+export declare function create_css_grid_layout(layout: Layout, round?: boolean, overlay?: [string, string]): string;

dist/common/generate_overlay.d.ts

@@ -0,0 +1,2 @@
+import type { LayoutPath } from "./layout_config";
+export declare function updateOverlaySheet({ view_window: { row_start, row_end, col_start, col_end }, box, }: LayoutPath<DOMRect>): string;

dist/common/insert_child.d.ts

@@ -0,0 +1,15 @@
+import type { Layout } from "./layout_config.ts";
+/**
+ * Inserts a new child panel into the layout tree at a specified location.
+ * Creates a split panel if necessary and redistributes sizes equally among all
+ * children.
+ *
+ * @param panel - The root layout tree to insert into
+ * @param child - Unique identifier for the new child panel
+ * @param path - Array of indices defining where to insert. Empty array inserts
+ * at root level.
+ * @param orientation - Orientation for newly created split panels. Defaults to
+ * "horizontal".
+ * @returns A new layout tree with the child inserted (original is not mutated).
+ */
+export declare function insert_child(panel: Layout, child: string, path: number[], orientation?: "horizontal" | "vertical", is_edge?: boolean): Layout;

dist/common/layout_config.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The percentage of the maximum resize distance that will be clamped.
+ *
+ */
+export declare const MINIMUM_REDISTRIBUTION_SIZE_THRESHOLD = 0.15;
+/**
+ * Threshold from panel edge that is considered a split vs drop action.
+ */
+export declare const SPLIT_EDGE_TOLERANCE = 0.25;
+/**
+ * Tolerance threshold for considering two grid track positions as identical.
+ *
+ * When collecting and deduplicating track positions, any positions closer than
+ * this value are treated as the same position to avoid redundant grid tracks.
+ */
+export declare const GRID_TRACK_COLLAPSE_TOLERANCE = 0.001;
+/**
+ * The overlay default behavior.
+ */
+export declare const OVERLAY_DEFAULT: OverlayMode;
+/**
+ * The overlay behavior type.
+ */
+export type OverlayMode = "grid" | "absolute" | "interactive";
+/**
+ * The representation of a CSS grid, in JSON form.
+ */
+export type Layout = SplitLayout | TabLayout;
+/**
+ * The orientation (of a `SplitPanel`).
+ */
+export type Orientation = "horizontal" | "vertical";
+/**
+ * A logical rectange in percent-coordinates (of a (1, 1) square).
+ */
+export interface ViewWindow {
+    row_start: number;
+    row_end: number;
+    col_start: number;
+    col_end: number;
+}
+/**
+ * A split panel that divides space among multiple child layouts
+ * .
+ * Child panels are arranged either horizontally (side by side) or vertically
+ * (stacked), via the `orientation` property `"horizzontal"` and `"vertical"`
+ * (respectively).
+ */
+export interface SplitLayout {
+    type: "split-panel";
+    children: Layout[];
+    sizes: number[];
+    orientation: Orientation;
+}
+/**
+ * A leaf panel node that contains a single named child element.
+ */
+export interface TabLayout {
+    type: "child-panel";
+    child: string[];
+    selected?: number;
+}
+/**
+ * Represents a draggable divider between two panels in the layout.
+ *
+ * Used for hit detection.
+ */
+export interface LayoutDivider {
+    path: number[];
+    view_window: ViewWindow;
+    type: Orientation;
+}
+/**
+ * Represents a panel location result from hit detection.
+ *
+ * Contains both the panel identifier and its grid position in relative units.
+ * The generic parameter `T` allows DOM-only properties (e.g. `DOMRect`) to be
+ * shared in this cross-platform module.
+ */
+export interface LayoutPath<T = undefined> {
+    type: "layout-path";
+    slot: string;
+    panel: TabLayout;
+    path: number[];
+    view_window: ViewWindow;
+    column_offset: number;
+    row_offset: number;
+    orientation: Orientation;
+    is_edge: boolean;
+    box: T;
+}
+/**
+ * Recursively iterates over all child panel names in the layout tree, yielding
+ * panel names in depth-first order.
+ *
+ * @param panel - The layout tree to iterate over
+ * @returns Generator yielding child panel names
+ */
+export declare function iter_panel_children(panel: Layout): Generator<string>;
+/**
+ * An empty `Layout` with no panels.
+ */
+export declare const EMPTY_PANEL: Layout;

dist/common/redistribute_panel_sizes.d.ts

@@ -0,0 +1,19 @@
+import { type Layout } from "./layout_config.ts";
+/**
+ * Adjusts panel sizes during a drag operation on a divider.
+ *
+ * The `delta` is distributed proportionally among affected panels, maintaining
+ * the sum:
+ *
+ * - Panels before and including the path index shrink by delta.
+ * - Panels after the path index grow by delta.
+ *
+ * @param panel - The root layout tree to modify.
+ * @param path - Path to the divider being dragged (identifies which split panel
+ * to resize).
+ * @param delta - Amount to resize, as a fraction (0-1). Positive values grow
+ * panels before the divider, negative values shrink them.
+ * @returns A new layout tree with updated sizes (original is not mutated).
+ * ```
+ */
+export declare function redistribute_panel_sizes(panel: Layout, path: number[], delta: number): Layout;

dist/common/remove_child.d.ts

@@ -0,0 +1,13 @@
+import type { Layout } from "./layout_config.ts";
+/**
+ * Removes a child panel from the layout tree by its name.
+ *
+ * Redistributes the removed panel's space proportionally among remaining
+ * siblings. Automatically collapses split panels when only one child remains.
+ *
+ * @param panel - The root layout tree to remove from.
+ * @param child - Name of the child panel to remove.
+ * @returns A new layout tree with the child removed (original is not mutated).
+ * Returns `EMPTY_PANEL` if the last panel is removed.
+ */
+export declare function remove_child(panel: Layout, child: string): Layout;

dist/extensions.d.ts

@@ -0,0 +1,31 @@
+import { RegularLayout } from "./regular-layout.ts";
+import { RegularLayoutFrame } from "./regular-layout-frame.ts";
+import { Layout } from "./common/layout_config.ts";
+declare global {
+    interface Document {
+        createElement(tagName: "regular-layout", options?: ElementCreationOptions): RegularLayout;
+        createElement(tagName: "regular-layout-frame", options?: ElementCreationOptions): RegularLayoutFrame;
+        querySelector<E extends Element = Element>(selectors: string): E | null;
+        querySelector(selectors: "regular-layout"): RegularLayout | null;
+        querySelector(selectors: "regular-layout-frame"): RegularLayoutFrame | null;
+    }
+    interface CustomElementRegistry {
+        get(tagName: "regular-layout"): typeof RegularLayout;
+        get(tagName: "regular-layout-frame"): typeof RegularLayoutFrame;
+    }
+    interface HTMLElement {
+        addEventListener(name: "regular-layout-update", cb: (e: RegularLayoutEvent) => void, options?: {
+            signal: AbortSignal;
+        }): void;
+        removeEventListener(name: "regular-layout-update", cb: any): void;
+    }
+}
+export interface RegularLayoutEvent extends CustomEvent {
+    detail: Layout;
+}
+export interface PerspectiveViewerElementExt {
+    addEventListener(name: "regular-layout-update", cb: (e: RegularLayoutEvent) => void, options?: {
+        signal: AbortSignal;
+    }): void;
+    removeEventListener(name: "regular-layout-update", cb: any): void;
+}