Merge pull request #1171 from mathuo/docs/tab-groups-and-edge-groups-documentation

docs: complete tab groups and edge groups documentation

Author: mathuo

packages/dockview-core/src/dockview/options.ts

@@ -159,9 +159,10 @@ export interface DockviewOptions {
     /**
      * Return the items to display in the tab group chip context menu on right-click.
      *
-     * Use built-in string shortcuts (`'separator'`, `'colorPicker'`) or provide a
+     * Use built-in string shortcuts (`'separator'`, `'colorPicker'`, `'rename'`) or provide a
      * `ContextMenuItemConfig` object for custom items.
      * `'colorPicker'` renders a native grid of color swatches for the tab group.
+     * `'rename'` renders an inline text input to rename the tab group.
      *
      * If omitted, no context menu is shown on chip right-click.
      * Return an empty array to suppress the menu for specific cases.

packages/docs/docs/core/groups/edgeGroups.mdx

@@ -5,12 +5,20 @@ description: How to create and manage edge groups in Dockview — groups that ar
 
 import { DocRef } from '@site/src/components/ui/reference/docRef';
 
+import { CodeRunner } from '@site/src/components/ui/codeRunner';
+
 Edge groups are `DockviewGroupPanel` instances pinned to one of the four edges of the layout (`'left'`, `'right'`, `'top'`, `'bottom'`). They support tabs, drag-and-drop, overflow, and the full group panel API — and their state is included in `toJSON` / `fromJSON`.
 
+<CodeRunner id="dockview/edge-groups" height={500}/>
+
 :::info
 Edge groups **cannot** be maximized or converted into floating/popout windows. They are structural elements of the layout.
 :::
 
+:::tip
+The `dndEdges` prop controls the drag-and-drop overlay that appears when dragging panels to the far edges of the layout. See [Drag and Drop](/docs/core/dnd/dragAndDrop#drag-and-drop) for configuration details.
+:::
+
 ## Adding Edge Groups
 
 Call `addEdgeGroup` in your `onReady` handler (or any time after initialization):
@@ -113,20 +121,101 @@ const isCollapsed = groupApi?.isCollapsed(); // boolean
 
 The `collapsedSize` (the pixel height/width of the header when collapsed) defaults to 35px and can be configured per-group via `EdgeGroupOptions.collapsedSize`, or per-theme via `DockviewTheme.edgeGroupCollapsedSize`.
 
+Themes that set a custom `edgeGroupCollapsedSize`:
+
+| Theme | `edgeGroupCollapsedSize` |
+| --- | --- |
+| `themeVisualStudio` | `22` |
+| `themeAbyssSpaced` | `44` |
+| `themeGithubLightSpaced` | `44` |
+| All other themes | `35` (default) |
+
+:::tip
+When an edge group loses all of its panels it is automatically collapsed. Adding a new panel to it will expand it again.
+:::
+
 ## Custom Header Actions
 
-The `location` prop in `rightHeaderActionsComponent`, `leftHeaderActionsComponent`, and `prefixHeaderActionsComponent` updates reactively when a group moves. Use it to show controls specific to edge groups:
+The `location` prop in `rightHeaderActionsComponent`, `leftHeaderActionsComponent`, and `prefixHeaderActionsComponent` updates reactively when a group moves. Use it to show controls specific to edge groups.
+
+The `DockviewGroupLocation` type is a discriminated union:
+
+```ts
+type DockviewGroupLocation =
+    | { type: 'grid' }
+    | { type: 'floating' }
+    | { type: 'popout'; getWindow: () => Window }
+    | { type: 'edge'; position: EdgeGroupPosition }; // 'top' | 'bottom' | 'left' | 'right'
+```
+
+Check `location.type` to distinguish edge groups, and `location.position` to know which edge:
 
+<FrameworkSpecific framework="React">
 ```tsx
-// React: show a collapse button only in edge groups
-const MyRightActions = (props: IDockviewGroupHeaderActionsProps) => {
-    if (props.location.type !== 'fixed') return null;
-    return <button onClick={() => props.api.collapse()}>Collapse</button>;
+const MyRightActions = (props: IDockviewHeaderActionsProps) => {
+    if (props.location?.type !== 'edge') return null;
+
+    const position = props.location.position; // 'left' | 'right' | 'top' | 'bottom'
+    return <button onClick={() => props.api.collapse()}>Collapse {position}</button>;
 };
+
+<DockviewReact rightHeaderActionsComponent={MyRightActions} />
+```
+</FrameworkSpecific>
+
+<FrameworkSpecific framework="Vue">
+```vue
+<template>
+    <button v-if="params?.location?.type === 'edge'" @click="params.api.collapse()">
+        Collapse {{ params.location.position }}
+    </button>
+</template>
+```
+</FrameworkSpecific>
+
+<FrameworkSpecific framework="Angular">
+```ts
+@Component({
+    selector: 'my-right-actions',
+    template: `
+        <button *ngIf="location?.type === 'edge'" (click)="api.collapse()">
+            Collapse {{ location.position }}
+        </button>
+    `,
+})
+export class MyRightActionsComponent {
+    @Input() api: DockviewGroupPanelApi;
+    @Input() location: DockviewGroupLocation;
+}
+```
+</FrameworkSpecific>
+
+<FrameworkSpecific framework="JavaScript">
+```ts
+const api = createDockview(parentElement, {
+    createRightHeaderActionsElement: (group) => {
+        const element = document.createElement('div');
+        return {
+            element,
+            init(params) {
+                if (params.location?.type === 'edge') {
+                    const btn = document.createElement('button');
+                    btn.textContent = `Collapse ${params.location.position}`;
+                    btn.addEventListener('click', () => params.api.collapse());
+                    element.appendChild(btn);
+                }
+            },
+            dispose() {},
+        };
+    },
+});
 ```
+</FrameworkSpecific>
 
 `DockviewGroupLocation` is exported from all framework packages.
 
+> See [Group Controls](/docs/core/groups/controls) for the full header actions reference.
+
 ## Serialization
 
 Edge group state (size, visibility, collapsed state, and panel contents) is included in `toJSON` / `fromJSON` automatically.

packages/docs/docs/core/panels/tabs.mdx

@@ -675,6 +675,13 @@ api.dissolveTabGroup({
     groupId: 'group-1',
     tabGroupId: tabGroup.id,
 });
+
+// Move a tab group to a new position in the tab bar
+api.moveTabGroup({
+    groupId: 'group-1',
+    tabGroupId: tabGroup.id,
+    index: 0, // move to the beginning
+});
 ```
 
 ### Querying Tab Groups
@@ -743,6 +750,150 @@ tabGroup.onDidDestroy(() => { });
 
 > See [Events](/docs/core/events#tab-groups) for the full event reference.
 
+### Chip Context Menu
+
+Right-clicking a tab group chip can show a context menu. This is opt-in — no menu is shown unless
+`getTabGroupChipContextMenuItems` is provided. Return an empty array to suppress the menu for specific chips.
+
+<FrameworkSpecific framework="React">
+  <DocRef declaration="IDockviewReactProps" methods={['getTabGroupChipContextMenuItems']} />
+</FrameworkSpecific>
+
+<FrameworkSpecific framework="Vue">
+  <DocRef declaration="IDockviewVueProps" methods={['getTabGroupChipContextMenuItems']} />
+</FrameworkSpecific>
+
+<FrameworkSpecific framework="Angular">
+  <DocRef declaration="IDockviewAngularProps" methods={['getTabGroupChipContextMenuItems']} />
+</FrameworkSpecific>
+
+<FrameworkSpecific framework="JavaScript">
+  <DocRef declaration="DockviewComponentOptions" methods={['getTabGroupChipContextMenuItems']} />
+</FrameworkSpecific>
+
+#### Built-in items
+
+Pass string shortcuts to render standard menu entries without any extra code:
+
+| Value | Behaviour |
+| --- | --- |
+| `'rename'` | An inline text input to rename the tab group |
+| `'colorPicker'` | A grid of color swatches to change the tab group color |
+| `'separator'` | Render a visual divider |
+
+#### Custom label items
+
+Provide an object with a `label` and `action` to add a simple clickable entry:
+
+```ts
+getTabGroupChipContextMenuItems: (params) => [
+    'rename',
+    'colorPicker',
+    'separator',
+    { label: 'Dissolve group', action: () => params.api.dissolveTabGroup({ groupId: params.group.id, tabGroupId: params.tabGroup.id }) },
+]
+```
+
+### Custom Chip Renderer
+
+To fully customize how tab group chips look, provide a `createTabGroupChipComponent` factory. It receives the `ITabGroup` and must return an `ITabGroupChipRenderer`.
+
+<FrameworkSpecific framework="React">
+  <DocRef declaration="IDockviewReactProps" methods={['createTabGroupChipComponent']} />
+</FrameworkSpecific>
+
+<FrameworkSpecific framework="Vue">
+  <DocRef declaration="IDockviewVueProps" methods={['createTabGroupChipComponent']} />
+</FrameworkSpecific>
+
+<FrameworkSpecific framework="Angular">
+  <DocRef declaration="IDockviewAngularProps" methods={['createTabGroupChipComponent']} />
+</FrameworkSpecific>
+
+<FrameworkSpecific framework="JavaScript">
+  <DocRef declaration="DockviewComponentOptions" methods={['createTabGroupChipComponent']} />
+</FrameworkSpecific>
+
+The renderer must implement:
+
+```ts
+interface ITabGroupChipRenderer {
+    readonly element: HTMLElement;   // the chip DOM element
+    init(params: { tabGroup: ITabGroup; api: DockviewApi }): void;
+    update?(params: { tabGroup: ITabGroup }): void; // called when label or color changes
+    dispose(): void;
+}
+```
+
+<FrameworkSpecific framework="JavaScript">
+```ts
+class MyChipRenderer {
+    readonly element = document.createElement('div');
+
+    init({ tabGroup, api }) {
+        this.element.className = 'my-chip';
+        this.element.textContent = tabGroup.label;
+    }
+
+    update({ tabGroup }) {
+        this.element.textContent = tabGroup.label;
+    }
+
+    dispose() {}
+}
+
+const api = createDockview(parentElement, {
+    createTabGroupChipComponent: (tabGroup) => new MyChipRenderer(),
+});
+```
+</FrameworkSpecific>
+
+### Styling
+
+Tab group appearance can be customized through CSS custom properties:
+
+| Property | Default | Description |
+| --- | --- | --- |
+| `--dv-tab-group-color-grey` | `#5f6368` | Color for grey chips |
+| `--dv-tab-group-color-blue` | `#1a73e8` | Color for blue chips |
+| `--dv-tab-group-color-red` | `#d93025` | Color for red chips |
+| `--dv-tab-group-color-yellow` | `#f9ab00` | Color for yellow chips |
+| `--dv-tab-group-color-green` | `#188038` | Color for green chips |
+| `--dv-tab-group-color-pink` | `#d01884` | Color for pink chips |
+| `--dv-tab-group-color-purple` | `#a142f4` | Color for purple chips |
+| `--dv-tab-group-color-cyan` | `#007b83` | Color for cyan chips |
+| `--dv-tab-group-color-orange` | `#e8710a` | Color for orange chips |
+| `--dv-tab-group-chip-padding` | `4px 8px` | Chip padding |
+| `--dv-tab-group-chip-border-radius` | `6px` | Chip border radius |
+| `--dv-tab-group-chip-font-size` | `11px` | Chip font size |
+| `--dv-tab-group-line-height` | `2px` | Height of the colored underline beneath grouped tabs |
+| `--dv-tab-group-line-opacity` | `0.6` | Opacity of the colored underline |
+
+### Serialization
+
+Tab groups are included in `toJSON` / `fromJSON` automatically. Each tab group is serialized as:
+
+```ts
+interface SerializedTabGroup {
+    id: string;
+    label?: string;
+    color: DockviewTabGroupColor;
+    collapsed: boolean;
+    panelIds: string[];
+}
+```
+
+### Utilities
+
+Use `isValidTabGroupColor` to validate a string as a tab group color at runtime:
+
+```ts
+import { isValidTabGroupColor } from 'dockview';
+
+isValidTabGroupColor('blue');   // true
+isValidTabGroupColor('foo');    // false — type narrows to never
+```
+
 ## Tab Height
 
 Tab height can be controlled through CSS.