Documentation
Concepts

Typed data

Declare what each tab component holds once, in a Types registry, and the JSON, the commands and the render functions are all typed by it, with no casts.

A tab names a component (what it shows), has a label (its name, a string) and carries data (its state: a file path, a chart's series). Dockable never reads the data: it is yours. You declare its type once, in a registry, and everything that touches a tab is typed by it: the layout JSON, the command payloads, the queries and the functions you render with.

The registry

A registry maps each tab component to the type of its data. It can also type the optional data of tabsets, borders and rows:

type Types = {
    tabs: {
        editor: { path: string; dirty: boolean };
        chart: { series: string[] };
        log: undefined;
    };
    tabset: { name?: string };
};

That is all a registry is: a type, with nothing to register at runtime. An interface works as well as a type literal. It satisfies DockableTypes; without one, the default is AnyTypes (any component name, unknown data).

Typing the model

Pass the registry to createModel, and the layout JSON is checked against it:

import { createModel, type LayoutJson } from "@fragiola/dockable-react";

const json: LayoutJson<Types> = {
    version: 1,
    root: {
        type: "row",
        children: [
            {
                type: "tabset",
                id: "main",
                data: { name: "Editors" },
                children: [{ component: "editor", label: "a.ts", data: { path: "/a.ts", dirty: false } }],
            },
        ],
    },
};

const model = createModel<Types>(json); // Model<Types>

A tab whose data does not match its component, or a component the registry does not name, is a compile error. data is required on a tab whose data type does not accept undefined, and optional otherwise.

Narrowing tab.data

A tab of the registry is a TabOf<Types>: a union with one member per component, discriminated by component. Checking the component narrows the data:

import type { TabOf } from "@fragiola/dockable-react";

function title(tab: TabOf<Types>): string {
    switch (tab.component) {
        case "editor":
            return tab.data.dirty ? `${tab.label} •` : tab.label; // the editor's data
        case "chart":
            return `${tab.label} (${tab.data.series.length})`; // the chart's data
        case "log":
            return tab.label;
    }
}

Every query returns typed tabs (model.get("all-tabs"), model.get("selected-tab-by", { tabsetId }), a tabset's children), and so does every children function of the React parts. A tab of one known component is a TabNode<K, D>: TabNode<"editor", Types["tabs"]["editor"]>.

The same switch is the component factory: it picks what a panel renders.

function TabContent({ tab }: { tab: TabOf<Types> }) {
    switch (tab.component) {
        case "editor":
            return <Editor path={tab.data.path} />;
        case "chart":
            return <Chart series={tab.data.series} />;
        case "log":
            return <Log />;
    }
}

Typed payloads

The commands are typed by the same registry. tab.add takes a component and its data:

model.run("tab.add", { component: "chart", label: "Sales", data: { series: [] }, to: "main" });

// @ts-expect-error: `path` is not in the chart's data
model.run("tab.add", { component: "chart", label: "Sales", data: { path: "/x" }, to: "main" });

tab.set-data changes some of an existing tab's data: data is a shallow patch, whose top-level keys replace the tab's while the others stay. A patch is typed as some keys of a component's data (DataPatchOf<Types>), so a key no component has, or a value of the wrong type, does not compile. The tab's id does not say its component, so the model checks the merged data against the tab's component at runtime (with dataSchemas, below). tab.set-component switches a tab to another component, and its data is the whole new value, typed by that component:

const tab = model.get("selected-tab-by", { tabsetId: "main" });
if (tab?.component === "editor") {
    model.run("tab.set-data", { tabId: tab.id, data: { dirty: true } }); // the path stays
}

// a switch takes the whole data of the new component
model.run("tab.set-component", { tabId: "t1", component: "chart", data: { series: ["a"] } });

// @ts-expect-error: no component has `colour` in its data
model.run("tab.set-data", { tabId: "t1", data: { colour: "red" } });

A patch never removes a key: set an optional one to its empty value (false, null, ""), or replace the whole data with tab.set-component (its current component, to keep it). Renaming is not a data change: it is tab.rename with a new label.

A toolbar outside the layout can drive the tab the user is looking at this way: it narrows the selected tab of the active tabset on component, then writes the chart's new kind into its data.

Active tab controls
Gallery

tabset.configure, border.configure and row.configure take data typed by the registry's tabset, border and row entries. The types behind them are exported for your own helpers: PayloadOf<Types, "tab.add"> is a command's payload, ResultOf<Types, "tab.add"> its result, and TabInitOf<Types> a new tab (a component and its data), handy for templates:

import type { TabInitOf } from "@fragiola/dockable-react";

const newChart: TabInitOf<Types> = { component: "chart", label: "Chart", data: { series: [] } };

model.run("tab.add", { ...newChart, to: "main", select: true });

Validating data at runtime

Types vanish at runtime. A layout restored from storage, a payload from a server or a tool call from an AI assistant is untrusted: its data may not match what your components expect. Register a JSON Schema per component with dataSchemas, and the model validates data wherever it enters:

import { createModel, type JsonSchema } from "@fragiola/dockable-react";

// the log has no data, so no schema
const dataSchemas: { [K in keyof Types["tabs"]]?: JsonSchema } = {
    editor: {
        type: "object",
        properties: { path: { type: "string", minLength: 1 }, dirty: { type: "boolean" } },
        required: ["path"],
    },
    chart: {
        type: "object",
        properties: { series: { type: "array", items: { type: "string" } } },
        required: ["series"],
    },
};

const model = createModel<Types>(json, { dataSchemas });
  • createModel throws a LayoutValidationError listing every tab whose data fails, with its JSON path (validateLayout(json, { dataSchemas }) returns the same issues without throwing).
  • tab.add, tab.set-data, tab.set-component and layout.load return invalid_payload, with the path of the offending data. Nothing changes. A patch is validated once merged, so the keys it keeps count.

The schemas use the JSON Schema subset the model's validator supports (type, properties, required, items, enum, const, anyOf, oneOf, minimum, minLength, …).

The label, and why icons and class names live in data

The model holds the layout: which tabs exist, where they are, what they allow, and what each tab is called. Every tab has a name, so the name is a field of the tab, its label: a raw string the model stores and returns, and never translates or renders. Your markup renders it (and translates it, when it is a key). The model holds no styling: an icon, a help text or a class name is how your app draws the tab. So those are fields of your data, typed by your registry, and your markup reads them:

<Dockable.TabList<Types> aria-label={tabset.data?.name ?? "Tabs"}>
    {(tab) => (
        <Dockable.Tab node={tab} className={tab.component === "log" ? "tab tab-log" : "tab"}>
            <TabIcon component={tab.component} />
            {tab.label}
        </Dockable.Tab>
    )}
</Dockable.TabList>

The same goes for UI permissions the model does not enforce: whether a tab shows a pin item in its menu is a field of its data (showPin: true). Permissions the model does enforce (closable, draggable, poppable, renamable, pinned, a tabset's droppable, …) are node fields, because the commands check them: tab.rename refuses a tab that is not renamable.

The type argument on children functions

Dockable.Root takes a Model<Types>, but a child cannot infer the root's registry through React context. The parts that hand nodes to a children function take it as a type argument:

<Dockable.Root model={model}>
    <Dockable.Row<Types>>{renderNode}</Dockable.Row>
    <Dockable.Panels<Types>>
        {(tab) => (
            <Dockable.Panel node={tab}>
                <TabContent tab={tab} />
            </Dockable.Panel>
        )}
    </Dockable.Panels>
    <Dockable.Popout<Types>>{() => <Dockable.Row<Types>>{renderNode}</Dockable.Row>}</Dockable.Popout>
</Dockable.Root>

The same holds for Dockable.TabList<Types>, Dockable.Borders<Types>, and the hooks: useDockable<Types>() returns a Model<Types> (its run typed), and useModelState<Types, S>(selector) a typed state. Without the argument, a part uses AnyTypes: it still works, and tab.data is unknown.

Zero casts

With a registry, a layout needs no as anywhere:

  • the JSON is a LayoutJson<Types>, checked where you write it;
  • tab.data narrows on tab.component, in queries, children functions and listeners;
  • command payloads are checked against the command and the component, and a middleware's ctx.payload narrows on ctx.command;
  • the render prop's ref is a callback ref that fits any element, so render={(props) => <section {...props} />} needs no cast either.

When data comes from outside your code, validate it (dataSchemas, validateLayout, model.dispatch) instead of casting it: the check is then real at runtime too.

See it

Component factory
Gallery