@smwb/ui-react 2.8.0 → 2.9.0

package/dist/components/layout/tabGroups/tabGroupsLayout.d.ts

@@ -0,0 +1,250 @@
+/**
+ * The pure layout model of `TabGroups`: the split tree, every operation on it and the grid
+ * geometry drawn from it. There is no framework and no DOM here, so jsdom tests feed layouts
+ * and numbers straight in, and the server and the client compute the same markup. The file is
+ * a byte-identical copy in ui-react and ui-solid.
+ *
+ * Every operation is pure: it never mutates its input and returns the input object itself when
+ * nothing changes. Unknown ids are no-ops, never errors.
+ */
+/** The version of the layout JSON this model reads and writes. */
+export declare const TAB_GROUPS_LAYOUT_VERSION = 1;
+/** An edge of a group: a tab dropped or moved there gets a new group on that side. */
+export type TabGroupsEdge = "top" | "right" | "bottom" | "left";
+/** Where a drop over a group's body lands: into the group (`center`) or a new group at an edge. */
+export type TabGroupsDropZone = "center" | TabGroupsEdge;
+/** A group: one tab row and its panels. */
+export interface TabGroupsGroup {
+    type: "group";
+    /** Unique among all nodes. Generated ids are "g1", "g2", …; an app may use any string. */
+    id: string;
+    /** Tab ids in row order. A tab id appears in exactly one group. Empty only for the root group (nothing open). */
+    tabs: string[];
+    /** The selected tab: one of `tabs`; null only when `tabs` is empty. */
+    active: string | null;
+}
+/** A split of an area into side-by-side or stacked children. */
+export interface TabGroupsSplit {
+    type: "split";
+    /** Unique among all nodes. Generated ids are "s1", "s2", …. */
+    id: string;
+    /** "row": children side by side, left to right; "column": stacked, top to bottom. */
+    direction: "row" | "column";
+    /** At least two. Never a split of the same direction (it is flattened into this one). */
+    children: TabGroupsNode[];
+    /** Each child's share of this split in percent, same length as `children`, positive, summing to 100. */
+    sizes: number[];
+}
+/** A node of the split tree. */
+export type TabGroupsNode = TabGroupsGroup | TabGroupsSplit;
+/** The whole arrangement: what an app stores. Only ids and sizes, no labels or content. */
+export interface TabGroupsLayout {
+    version: 1;
+    root: TabGroupsNode;
+    /** The group the user last worked in: new tabs go there by default. Always an existing group id. */
+    activeGroup: string;
+}
+/** What a layout change did: the second argument of `onLayoutChange`. */
+export type TabGroupsChange = {
+    type: "select";
+    tab: string;
+    group: string;
+}
+/** Focus moved into another group. */
+ | {
+    type: "activate";
+    group: string;
+}
+/** Into an existing group, including a reorder within the same group. */
+ | {
+    type: "move";
+    tab: string;
+    from: string;
+    to: string;
+    index: number;
+    sourceClosed: boolean;
+}
+/** Into a new group at an edge; `to` is the new group. */
+ | {
+    type: "split";
+    tab: string;
+    from: string;
+    to: string;
+    edge: TabGroupsEdge;
+    sourceClosed: boolean;
+} | {
+    type: "close";
+    tab: string;
+    group: string;
+    groupClosed: boolean;
+} | {
+    type: "resize";
+    split: string;
+    sizes: number[];
+};
+/** Where `moveTab` puts a tab. */
+export type TabGroupsMoveTarget = 
+/** Into an existing group; `index` = the tab's final index (default: the end). */
+{
+    group: string;
+    index?: number;
+    edge?: undefined;
+}
+/** A new group at that edge of `group`. */
+ | {
+    group: string;
+    edge: TabGroupsEdge;
+};
+/** The CSS grid a layout is drawn on (see `computeTabGroupsGrid`). */
+export interface TabGroupsGrid {
+    /** Content column widths, percent, left to right. */
+    columns: number[];
+    /** Content row heights, percent, top to bottom. */
+    rows: number[];
+    /** Every group's content columns and rows, end-exclusive, in reading order. */
+    groups: {
+        id: string;
+        column: [number, number];
+        row: [number, number];
+    }[];
+    /**
+     * Every separator, in reading order (after the subtree of child `index` of its split). `line` is the
+     * content boundary it sits on (1..n-1); `span` its extent across the other axis, end-exclusive.
+     */
+    separators: {
+        split: string;
+        index: number;
+        orientation: "vertical" | "horizontal";
+        line: number;
+        span: [number, number];
+    }[];
+}
+/** The texts of `TabGroups`. Numbers passed in are 1-based, as they are read out. */
+export interface TabGroupsLabels {
+    /** The tab row's name: "Group 1 of 4"; "Tabs" when count is 1. */
+    group: (index: number, count: number) => string;
+    /** The group actions button: "Group actions". */
+    groupActions: string;
+    /** "Split right". */
+    splitRight: string;
+    /** "Split down". */
+    splitDown: string;
+    /** "Move to previous group". */
+    moveToPreviousGroup: string;
+    /** "Move to next group". */
+    moveToNextGroup: string;
+    /** "Move tab left". */
+    moveLeft: string;
+    /** "Move tab right". */
+    moveRight: string;
+    /** The separators: "Resize groups". */
+    resize: string;
+    /** "Terminal moved to group 2 of 3". */
+    movedToGroup: (tab: string, index: number, count: number) => string;
+    /** "Terminal moved to a new group on the right" (below, on the left, above). */
+    movedToNewGroup: (tab: string, edge: TabGroupsEdge) => string;
+    /** "Terminal moved to position 2 of 4". */
+    movedInGroup: (tab: string, position: number, count: number) => string;
+}
+/** The default (English) texts. */
+export declare const TAB_GROUPS_LABELS: TabGroupsLabels;
+/** A layout of one group "g1" holding `tabs`; `active` (when one of them) or the first is selected. */
+export declare function createTabGroupsLayout(tabs?: readonly string[], options?: {
+    active?: string;
+}): TabGroupsLayout;
+/**
+ * Reads a layout from untrusted JSON (storage, a URL, a file). `null` for a non-object, a version
+ * other than 1 or no valid root; anything else is repaired: non-string and duplicate tab ids
+ * dropped (the first in reading order wins), empty non-root groups removed and splits collapsed
+ * or flattened, an invalid `active` replaced by the first tab, unusable sizes replaced by equal
+ * shares and all sizes rescaled to 100, missing or duplicate node ids regenerated, an invalid
+ * `activeGroup` replaced by the first group. With `options.tabs` the layout is synced to that
+ * list (`syncTabs`). A layout produced by this model round-trips through JSON unchanged.
+ */
+export declare function parseTabGroupsLayout(raw: unknown, options?: {
+    tabs?: readonly string[];
+}): TabGroupsLayout | null;
+/** Makes the layout hold exactly `tabs`: unknown ids are closed, missing ones appended to `activeGroup`. */
+export declare function syncTabs(layout: TabGroupsLayout, tabs: readonly string[]): TabGroupsLayout;
+/** Every group in reading order (depth first): the order "Group n of N" counts in. */
+export declare function getGroups(layout: TabGroupsLayout): TabGroupsGroup[];
+/** The group holding `tabId`. */
+export declare function findGroupOfTab(layout: TabGroupsLayout, tabId: string): TabGroupsGroup | undefined;
+/**
+ * Adds a tab to `options.group` (default `activeGroup`) at `options.index` (default the end),
+ * selected unless `options.select` is false. An id already in the layout moves there instead.
+ */
+export declare function addTab(layout: TabGroupsLayout, tabId: string, options?: {
+    group?: string;
+    index?: number;
+    select?: boolean;
+}): TabGroupsLayout;
+/**
+ * Closes a tab. When it was its group's last tab the group goes too: its share passes to the
+ * previous sibling (else the next), a split left with one child is replaced by that child and
+ * `activeGroup` moves to the group that took the space. The last tab of the last group leaves
+ * an empty root group.
+ */
+export declare function removeTab(layout: TabGroupsLayout, tabId: string): TabGroupsLayout;
+/** Selects a tab in its group and makes that group `activeGroup`. */
+export declare function selectTab(layout: TabGroupsLayout, tabId: string): TabGroupsLayout;
+/** Makes an existing group `activeGroup`. */
+export declare function setActiveGroup(layout: TabGroupsLayout, groupId: string): TabGroupsLayout;
+/**
+ * Moves a tab. Into another group: inserted at `target.index` (its final index; default the end),
+ * selected there, and that group becomes `activeGroup`. Within its own group: a reorder, the
+ * selection stays. To an edge: a new group there holding the tab (see `TabGroupsEdge`); the own
+ * edge of a group with one tab is a no-op. A source group left empty closes as in `removeTab`.
+ */
+export declare function moveTab(layout: TabGroupsLayout, tabId: string, target: TabGroupsMoveTarget): TabGroupsLayout;
+/**
+ * The keyboard move (Alt+Shift+Arrow): into the neighbouring group at that edge (appended,
+ * selected); with no neighbour and at least two tabs in the group, a new group at that edge;
+ * otherwise nothing.
+ */
+export declare function moveTabInDirection(layout: TabGroupsLayout, tabId: string, edge: TabGroupsEdge): TabGroupsLayout;
+/**
+ * Moves separator `index` of a split (between children `index` and `index + 1`) by `delta`
+ * percent of the split (±Infinity: to the limit). Only that pair changes and the sizes still sum
+ * to 100. Every group on both sides keeps at least `min` percent of the split (default 0) — a
+ * nested split as a whole is held to what its groups need — and never so little that the grid
+ * could not draw it (a few hundredths of a percent of the root).
+ */
+export declare function resizeSplit(layout: TabGroupsLayout, splitId: string, index: number, delta: number, min?: number): TabGroupsLayout;
+/**
+ * The group touching `edge` of the group `groupId` with the largest overlap along that edge
+ * (ties: the first in reading order); undefined at the area's outer edge.
+ */
+export declare function neighbourGroup(layout: TabGroupsLayout, groupId: string, edge: TabGroupsEdge): string | undefined;
+/**
+ * The group that takes the space of `groupId` when it closes: the previous sibling's last group
+ * in reading order, else the next sibling's first group; undefined for the root group.
+ */
+export declare function adjacentGroup(layout: TabGroupsLayout, groupId: string): string | undefined;
+/**
+ * The drop zone under a point of a group's body (`x`, `y` relative to it, clamped into it): within
+ * `edgeSize` (a fraction, default 0.25) of an edge, that edge; the nearest edge wins where bands
+ * overlap (ties: top, right, bottom, left); else `center`.
+ */
+export declare function dropZoneAt(x: number, y: number, width: number, height: number, edgeSize?: number): TabGroupsDropZone;
+/**
+ * The grid a layout is drawn on: every group's rectangle in percent of the root, cut into
+ * content columns and rows at the distinct boundaries (closer than 0.05 percent snap together).
+ * Pure numbers, so the server and the client draw the same tracks.
+ */
+export declare function computeTabGroupsGrid(layout: TabGroupsLayout): TabGroupsGrid;
+/** `grid-template-columns`: a `minmax(0, <w>fr)` per content column, separator tracks between. */
+export declare function gridTemplateColumns(grid: TabGroupsGrid): string;
+/** `grid-template-rows`: per content row an `auto` header track and a `minmax(0, <h>fr)` body track, separators between. */
+export declare function gridTemplateRows(grid: TabGroupsGrid): string;
+/** The `grid-area` of a group's header (its tab row). */
+export declare function groupHeaderArea(group: TabGroupsGrid["groups"][number]): string;
+/** The `grid-area` of a group's panels. */
+export declare function groupBodyArea(group: TabGroupsGrid["groups"][number]): string;
+/** The `grid-area` of a separator. */
+export declare function separatorArea(separator: TabGroupsGrid["separators"][number]): string;
+/**
+ * The announcement of a change, read from the layout after it: "Terminal moved to group 2 of 3",
+ * "… to a new group on the right", "… to position 2 of 4"; "" for select, activate, close and resize.
+ */
+export declare function describeTabGroupsChange(change: TabGroupsChange, layout: TabGroupsLayout, title: (tabId: string) => string, labels?: TabGroupsLabels): string;