@smwb/ui-solid 0.12.1 → 0.14.0

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

@@ -0,0 +1,102 @@
+import { type JSX } from "solid-js";
+import type { TabCloseReason, TabProps } from "../../navigation/tabs/tab/tab";
+import { type Ref } from "../../../primitives/mergeRefs";
+import { type TabGroupsChange, type TabGroupsLabels, type TabGroupsLayout } from "./tabGroupsLayout";
+/**
+ * What a tab of `TabGroups` shows, answered by the app through `getTab`. Only the tab's id lives in
+ * the layout, so a stored arrangement survives renames and carries no content.
+ */
+export interface TabGroupsTab {
+    /** The tab's label. A tab id the app does not know is drawn as the id itself. */
+    label: JSX.Element;
+    /**
+     * Plain text for the announcements and for a screen reader that cannot read the label (markup,
+     * an icon). `label` when it is a string, else the tab id.
+     */
+    title?: string | undefined;
+    /** An icon drawn before the label. */
+    icon?: JSX.Element;
+    /**
+     * Draw a close button and let Delete or Backspace close the tab: true by default. `false` keeps
+     * the tab's item wrapper, so every tab has the same drag surface.
+     */
+    closable?: boolean | undefined;
+    /** Accessible label of the tab's close button ("Close Terminal 1"). */
+    closeLabel?: string | undefined;
+    /** Content after the tab, as `Tab`'s `actions`: a trigger with a `Menu`, or any control. */
+    actions?: TabProps["actions"];
+    /** Greys the tab out: it cannot be selected, moved or dragged. */
+    disabled?: boolean | undefined;
+}
+export interface TabGroupsProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "children" | "onChange" | "id"> {
+    /**
+     * The arrangement to draw: the split tree, every group's tabs and the selected one. Controlled
+     * while it is not `undefined` — the component then only reports changes through
+     * `onLayoutChange` and draws what the owner gives back.
+     */
+    layout?: TabGroupsLayout | undefined;
+    /** The arrangement to start from while uncontrolled: one empty group by default. */
+    defaultLayout?: TabGroupsLayout | undefined;
+    /**
+     * Called with the layout after a change and with what happened, in both the controlled and the
+     * uncontrolled mode. A controlled owner that does not apply the change simply sees nothing move.
+     */
+    onLayoutChange?: ((layout: TabGroupsLayout, change: TabGroupsChange) => void) | undefined;
+    /** What a tab shows, by its id; `undefined` draws the id as the label. */
+    getTab: (tabId: string) => TabGroupsTab | undefined;
+    /**
+     * The content of a tab's panel, by its id. It is called the first time the tab is selected and
+     * the panel stays mounted from then on, hidden while another tab is shown and kept through a
+     * move to another group: a form keeps what was typed, a terminal its scrollback. Its node stays
+     * where it is in the DOM, so an iframe in it does not reload either.
+     */
+    renderPanel: (tabId: string) => JSX.Element;
+    /**
+     * Asked before a tab closes, with what asked for it (its close button, Delete or Backspace, a
+     * middle click, its `actions`). Return `false` to keep the tab.
+     */
+    onTabClose?: ((tabId: string, event: Event, reason: TabCloseReason) => boolean | void) | undefined;
+    /** Drawn, centred, when the only group has no tabs left. */
+    empty?: JSX.Element;
+    /** The smallest a group can be resized to, in px of its split; 120 by default. */
+    minGroupSize?: number | undefined;
+    /** The arrow-key step of a separator, in percent of its split; 5 by default. */
+    keyboardStep?: number | undefined;
+    /** Draw each group's actions button and menu; true by default. */
+    groupActions?: boolean | undefined;
+    /** Compact tab rows, as `Tabs`' `dense`; false by default. */
+    dense?: boolean | undefined;
+    /** The texts of the component: its menus, labels and announcements. English by default. */
+    labels?: Partial<TabGroupsLabels> | undefined;
+    /** Base of the generated ids and the id of the root element. Generated by default. */
+    id?: string | undefined;
+    /** Test id of the root element; `tab-groups` unless given. */
+    "data-testid"?: string | undefined;
+    /** Class of the root element, added to the component's own. */
+    class?: string | undefined;
+    /** Inline style of the root element; the component's `grid-template-*` win over it. */
+    style?: JSX.HTMLAttributes<HTMLDivElement>["style"];
+    /** The root element. */
+    ref?: Ref<HTMLDivElement>;
+}
+/**
+ * Tab groups in a split area: one component draws every group, each a tab row with its panels.
+ *
+ * The area splits right or down into groups, a tab moves to another group by drag and drop or by
+ * keyboard, dropping it on a group's edge makes a new group there, and closing a group's last tab
+ * closes the group and collapses its split. The whole arrangement is a serialisable, versioned
+ * `layout` (`layout` / `defaultLayout` / `onLayoutChange`) that an app stores as JSON;
+ * `tabGroupsLayout.parseTabGroupsLayout` reads one back, and `tabGroupsLayout.addTab` /
+ * `syncTabs` keep it in step with the tabs the app has open.
+ *
+ * Everything is drawn on one CSS grid whose children are a flat, keyed list, so restructuring the
+ * tree re-places nodes instead of remounting them, and a panel's node never moves: it keeps its
+ * state, its scroll and the focus inside it when its tab moves to another group or the area splits.
+ *
+ * Without a mouse: Alt+Shift+Arrow moves the focused tab to the group that way (splitting there
+ * when the area ends), Mod+Shift+ArrowLeft/Right moves it along its row, each group's actions
+ * button opens a menu of the same actions, and each separator resizes with the arrow keys, Home
+ * and End. Every move is announced in a polite status region.
+ */
+export declare function TabGroups(props: TabGroupsProps): JSX.Element;
+export default TabGroups;