@smwb/ui-react 2.8.0 → 2.9.0

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

@@ -0,0 +1,94 @@
+import React from "react";
+import { type TabCloseReason, type TabProps } from "../../navigation/tabs";
+import { type TabGroupsChange, type TabGroupsLabels, type TabGroupsLayout } from "./tabGroupsLayout";
+/** What one tab of `TabGroups` shows. The layout stores ids only; the app answers for the rest. */
+export interface TabGroupsTab {
+    /** The tab's label, as `Tab`'s own. */
+    label: React.ReactNode;
+    /**
+     * Plain text for the announcements: what a screen reader says the tab is called. `label` when it
+     * is a string, the tab id otherwise.
+     */
+    title?: string;
+    /** Content before the label: a status marker. Decorative, as in `Tab`. */
+    icon?: React.ReactNode;
+    /**
+     * Draw a close button and let Delete or Backspace close the tab; true by default. Pass `false`
+     * to keep the tab's item wrapper — and so the same drag surface — without a close button.
+     */
+    closable?: boolean;
+    /** Accessible label of the close button. English by default; set it to localise. */
+    closeLabel?: string;
+    /** Content after the tab: a trigger with a `Menu`, as `Tab`'s own `actions`. */
+    actions?: TabProps["actions"];
+    /** Shown and focusable, but not selectable, not closable and not draggable. */
+    disabled?: boolean;
+}
+/**
+ * A container of tab groups: the area splits right or down into groups, each group is a tab row
+ * with its panels, tabs move between groups by drag and drop or by keyboard, and the whole
+ * arrangement is a serialisable, versioned layout.
+ *
+ * The layout is controlled while `layout` is given and uncontrolled otherwise (seeded from
+ * `defaultLayout`); `onLayoutChange` is called in both modes with the new layout and what changed.
+ * Only ids and sizes are stored: `getTab` says what a tab shows and `renderPanel` what it contains,
+ * so the JSON stays small and survives a label rename. A panel is rendered from the first time its
+ * tab is selected and then stays mounted while hidden, so a tab keeps its state when it moves to
+ * another group. A move only changes where a panel is drawn — its node stays where it is in the
+ * DOM — so its scroll, an iframe in it and the focus inside it survive the move too.
+ *
+ * Everything is reachable without a mouse. In a tab row: the arrows, Home and End move focus,
+ * Enter or Space selects, Delete or Backspace and Mod+W close, Mod+Shift+[ and Mod+Shift+] switch
+ * (all of that is `Tabs`). On the focused tab: Alt+Shift+Arrow moves it into the group that way, or
+ * splits a new group there when the area ends, and Mod+Shift+ArrowLeft/Right moves it along the row.
+ * Each group's actions button opens a menu with the same actions, and each separator takes the
+ * arrow keys along its axis plus Home and End. Every move is announced in a status region.
+ *
+ * Dropping a tab on a group's body puts it in that group; dropping it within a quarter of the
+ * body's edge splits a new group there. The zones are drawn while dragging.
+ */
+export interface TabGroupsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "onChange"> {
+    /**
+     * The arrangement to draw: the split tree, the tabs of every group and which of them is
+     * selected. Controlled while it is not `undefined` — the component then draws what it is given
+     * and an owner that ignores `onLayoutChange` sees nothing move.
+     */
+    layout?: TabGroupsLayout | undefined;
+    /** The layout of the uncontrolled mode's first render: one empty group by default. */
+    defaultLayout?: TabGroupsLayout | undefined;
+    /**
+     * Called with the new layout and what changed (`select`, `activate`, `move`, `split`, `close`,
+     * `resize`) in the controlled and the uncontrolled mode alike. Store the layout here; the
+     * `change` says which of them are worth writing (an `activate` is a focus move, not an edit).
+     */
+    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. Called from the first time the tab is selected and
+     * kept mounted after that, so a panel keeps its state while hidden and while its tab moves.
+     */
+    renderPanel: (tabId: string) => React.ReactNode;
+    /**
+     * Asked before a tab closes (its close button, Delete or Backspace, a middle press or its
+     * `actions`), with what asked for it. Return `false` to keep the tab; anything else closes it.
+     */
+    onTabClose?: ((tabId: string, event: React.SyntheticEvent<HTMLElement>, reason: TabCloseReason) => boolean | void) | undefined;
+    /** Drawn, centred, when nothing is open: the only group has no tabs. */
+    empty?: React.ReactNode;
+    /** The smallest a group can be resized to, in px of its split; 120 by default. */
+    minGroupSize?: number;
+    /** A separator's arrow-key step, in percent of its split; 5 by default, as `ScreenDivider`. */
+    keyboardStep?: number;
+    /** Draw each group's actions button and its menu; true by default. */
+    groupActions?: boolean;
+    /** Compact tab rows (`Tabs`' `dense`); false by default. */
+    dense?: boolean;
+    /** The component's texts, to localise them. English by default. */
+    labels?: Partial<TabGroupsLabels> | undefined;
+    /** Base of the generated ids and the root's own id. Generated by default. */
+    id?: string;
+    /** Test id of the root element; "tab-groups" by default. */
+    "data-testid"?: string;
+}
+export declare const TabGroups: React.ForwardRefExoticComponent<TabGroupsProps & React.RefAttributes<HTMLDivElement>>;