From 250934276b552ec54befbf259155177703a149b1 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 8 Jul 2026 22:10:05 +0000 Subject: [PATCH] docs: humanize wording and remove AI-style em dashes (v8) Rework prose across the documentation site so it reads as human-written: replace em dashes with commas, colons, semicolons, parentheses or full stops as the sentence calls for, and drop stock phrasings ("comprehensive set of", "a wide variety of", "out of the box", "unlocks correct behaviour"). Update the renamed migration headings and the cross-reference anchor to keep links working. Also adds a Writing Style section to the docs AGENTS.md to deter the same phrasings in future. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01698iGKTFkcMr51WC1grrvT --- packages/docs/AGENTS.md | 19 ++++++++ packages/docs/docs/advanced/accessibility.mdx | 24 +++++----- .../docs/docs/advanced/focus-navigation.mdx | 8 ++-- packages/docs/docs/advanced/keyboard.mdx | 14 +++--- packages/docs/docs/api/dockview/groupApi.mdx | 8 ++-- packages/docs/docs/api/dockview/options.mdx | 6 +-- packages/docs/docs/api/dockview/overview.mdx | 8 ++-- packages/docs/docs/api/dockview/panelApi.mdx | 8 ++-- packages/docs/docs/api/gridview/api.mdx | 6 +-- packages/docs/docs/api/gridview/options.mdx | 4 +- packages/docs/docs/api/gridview/panelApi.mdx | 6 +-- packages/docs/docs/api/paneview/api.mdx | 6 +-- packages/docs/docs/api/paneview/options.mdx | 4 +- packages/docs/docs/api/paneview/panelApi.mdx | 6 +-- packages/docs/docs/api/splitview/api.mdx | 6 +-- packages/docs/docs/api/splitview/options.mdx | 4 +- packages/docs/docs/api/splitview/panelApi.mdx | 6 +-- packages/docs/docs/core/dnd/disable.mdx | 8 ++-- packages/docs/docs/core/dnd/dragAndDrop.mdx | 14 +++--- packages/docs/docs/core/dnd/dropGuide.mdx | 14 +++--- packages/docs/docs/core/dnd/dropPosition.mdx | 10 ++--- packages/docs/docs/core/dnd/external.mdx | 12 ++--- packages/docs/docs/core/dnd/overlay.mdx | 10 ++--- packages/docs/docs/core/dnd/overview.mdx | 12 ++--- packages/docs/docs/core/dnd/smartGuides.mdx | 20 ++++----- packages/docs/docs/core/dnd/strategy.mdx | 8 ++-- packages/docs/docs/core/dnd/thirdParty.mdx | 4 +- packages/docs/docs/core/events.mdx | 10 ++--- packages/docs/docs/core/groups/add.mdx | 6 +-- .../docs/docs/core/groups/autoEdgeGroups.mdx | 20 ++++----- .../docs/core/groups/autoHideEdgeGroups.mdx | 16 +++---- .../docs/docs/core/groups/constraints.mdx | 4 +- packages/docs/docs/core/groups/controls.mdx | 6 +-- packages/docs/docs/core/groups/edgeGroups.mdx | 12 ++--- .../docs/docs/core/groups/floatingGroups.mdx | 12 ++--- .../docs/docs/core/groups/maximizedGroups.mdx | 6 +-- packages/docs/docs/core/groups/move.mdx | 8 ++-- .../docs/docs/core/groups/popoutGroups.mdx | 16 +++---- packages/docs/docs/core/locked.mdx | 6 +-- packages/docs/docs/core/nested.mdx | 4 +- packages/docs/docs/core/overview.mdx | 2 +- packages/docs/docs/core/panels/add.mdx | 8 ++-- .../docs/docs/core/panels/headerPosition.mdx | 6 +-- packages/docs/docs/core/panels/move.mdx | 6 +-- .../docs/docs/core/panels/multiRowTabs.mdx | 12 ++--- packages/docs/docs/core/panels/pinnedTabs.mdx | 26 +++++------ packages/docs/docs/core/panels/register.mdx | 6 +-- packages/docs/docs/core/panels/remove.mdx | 6 +-- packages/docs/docs/core/panels/rendering.mdx | 26 +++++------ packages/docs/docs/core/panels/resizing.mdx | 12 ++--- packages/docs/docs/core/panels/tabGroups.mdx | 12 ++--- .../docs/docs/core/panels/tabOverflow.mdx | 6 +-- packages/docs/docs/core/panels/tabs.mdx | 12 ++--- packages/docs/docs/core/panels/update.mdx | 8 ++-- packages/docs/docs/core/security.mdx | 8 ++-- packages/docs/docs/core/sizing.mdx | 6 +-- packages/docs/docs/core/state/history.mdx | 28 ++++++------ packages/docs/docs/core/state/load.mdx | 4 +- packages/docs/docs/core/state/save.mdx | 4 +- packages/docs/docs/core/theming.mdx | 14 +++--- packages/docs/docs/index.mdx | 12 ++--- .../docs/docs/other/gridview/overview.mdx | 8 ++-- .../docs/docs/other/paneview/overview.mdx | 8 ++-- .../docs/docs/other/splitview/overview.mdx | 8 ++-- packages/docs/docs/overview/editions.mdx | 22 +++++----- packages/docs/docs/overview/features.mdx | 44 +++++++++---------- packages/docs/docs/overview/introduction.mdx | 2 +- .../releases/migrating/migrating-to-v7.mdx | 36 +++++++-------- .../releases/migrating/migrating-to-v8.mdx | 20 ++++----- .../docs/releases/whats-new/whats-new-v6.mdx | 18 ++++---- .../docs/releases/whats-new/whats-new-v7.mdx | 20 ++++----- .../docs/releases/whats-new/whats-new-v8.mdx | 16 +++---- 72 files changed, 413 insertions(+), 394 deletions(-) diff --git a/packages/docs/AGENTS.md b/packages/docs/AGENTS.md index 2a8bae253..3a301df29 100644 --- a/packages/docs/AGENTS.md +++ b/packages/docs/AGENTS.md @@ -2,6 +2,25 @@ Documentation website built with Docusaurus v3. +## Writing Style + +Documentation prose should read as though a person wrote it, not a language +model. When writing or editing docs: + +- Do not use em dashes (`—`). Rewrite the sentence with a comma, colon, + semicolon, parentheses, or a full stop, whichever fits. This is the single + most common tell; avoid it everywhere, including frontmatter `description` + fields, tables, and code comments. +- Drop filler and marketing words. Avoid "comprehensive", "a wide variety of", + "out of the box", "seamlessly", "powerful", "robust", "unlocks", "leverage", + "delve into", "first-class", "it's worth noting", "keep in mind". State the + concrete thing instead. +- Prefer short, direct sentences. Cut words that carry no meaning; don't hedge + or pad. +- Keep British spelling (behaviour, colour, localise) to match the existing + docs. +- An en dash in a numeric range (`v5.0–5.2`) is correct and fine to keep. + ## Build Commands - `build` - Build templates then build Docusaurus site diff --git a/packages/docs/docs/advanced/accessibility.mdx b/packages/docs/docs/advanced/accessibility.mdx index 9b7538145..494d16664 100644 --- a/packages/docs/docs/advanced/accessibility.mdx +++ b/packages/docs/docs/advanced/accessibility.mdx @@ -1,15 +1,15 @@ --- title: Accessibility -description: The ARIA semantics, keyboard support and screen-reader announcements Dockview ships out of the box. +description: The ARIA semantics, keyboard support and screen-reader announcements Dockview provides by default. sidebar_position: 1 --- import { DocRef } from '@site/src/components/ui/reference/docRef'; -Dockview ships a baseline of accessibility in core — WAI-ARIA roles and labels, +Dockview ships a baseline of accessibility in core: WAI-ARIA roles and labels, roving-tabindex navigation within the tab strip, screen-reader announcements of -layout changes, and keyboard-only focus indicators — included out of the box in -the `dockview` package and the framework packages. No configuration is required +layout changes, and keyboard-only focus indicators. These come with the +`dockview` package and the framework packages. No configuration is required for the semantics below; the options on this page tune the announcements and the opt-in keymap. @@ -28,7 +28,7 @@ technology can describe the layout: - Close buttons expose an accessible name that includes the panel title (e.g. "Close Orders"). -These roles are reactive — activating a tab, floating a group or calling +These roles are reactive: activating a tab, floating a group or calling `setTitle` updates the relevant attributes. ## Keyboard navigation @@ -38,8 +38,8 @@ stop, and the arrow keys move between tabs once the strip has focus. `Home` / `End` jump to the first / last tab, and `Enter` / `Space` activate the focused tab. This within-strip navigation is always on. -Broader keyboard operability — switching tabs, cycling groups with `F6`, jumping -focus to the tab strip, and keyboard-driven docking — is enabled with the +Broader keyboard operability (switching tabs, cycling groups with `F6`, jumping +focus to the tab strip, and keyboard-driven docking) is enabled with the `keyboardNavigation` option and is documented in full on the [Keyboard](/docs/advanced/keyboard) page, including the rebindable keymap. @@ -59,8 +59,8 @@ focused by keyboard. ## Screen-reader announcements -Dockview narrates layout changes — panels opening/closing, groups floating, -docking, popping out, maximising/restoring — through visually-hidden ARIA live +Dockview narrates layout changes (panels opening/closing, groups floating, +docking, popping out, maximising/restoring) through visually-hidden ARIA live regions (a polite region for routine status and an assertive one for cancellations). This is on by default. @@ -126,7 +126,7 @@ const options = { For full translations, provide a `messages` catalog. Each entry is a function that builds the string from the relevant context (e.g. the panel title); supply -any subset — unset entries keep the English defaults: +any subset; unset entries keep the English defaults: ```ts const options = { @@ -154,5 +154,5 @@ const options = { ## See also -- [Focus navigation](/docs/advanced/focus-navigation) — `DockviewApi` methods for moving focus between panels and groups -- [Keyboard](/docs/advanced/keyboard) — the opt-in keymap, `F6` group cycling and keyboard-driven docking +- [Focus navigation](/docs/advanced/focus-navigation): `DockviewApi` methods for moving focus between panels and groups +- [Keyboard](/docs/advanced/keyboard): the opt-in keymap, `F6` group cycling and keyboard-driven docking diff --git a/packages/docs/docs/advanced/focus-navigation.mdx b/packages/docs/docs/advanced/focus-navigation.mdx index 163c96c05..c028c48c8 100644 --- a/packages/docs/docs/advanced/focus-navigation.mdx +++ b/packages/docs/docs/advanced/focus-navigation.mdx @@ -6,7 +6,7 @@ sidebar_position: 2 `DockviewApi` exposes a small set of framework-agnostic methods for moving focus between panels and groups programmatically. They work in every framework -binding — useful for wiring up your own keyboard shortcut handlers. The rebindable keymap and keyboard docking are a separate, +binding, useful for wiring up your own keyboard shortcut handlers. The rebindable keymap and keyboard docking are a separate, enterprise feature covered in [Keyboard Navigation](/docs/advanced/keyboard). ## Programmatic focus navigation @@ -24,7 +24,7 @@ api.activatePrevious({ includePanel: true }); :::info Renamed in v8 These methods were previously called `moveToNext` / `moveToPrevious`. The old names still work as deprecated aliases but will be removed in a future major -release — the new names make it clear they advance the active panel/group +release; the new names make it clear they advance the active panel/group (focus) rather than relocating a panel. ::: @@ -65,5 +65,5 @@ const layout = api.groups.map((group) => ({ ## See also -- [Keyboard](/docs/advanced/keyboard) — the rebindable keymap and keyboard-driven docking built on top of these primitives -- [Accessibility](/docs/advanced/accessibility) — the ARIA semantics and within-strip keyboard navigation Dockview ships by default +- [Keyboard](/docs/advanced/keyboard): the rebindable keymap and keyboard-driven docking built on top of these primitives +- [Accessibility](/docs/advanced/accessibility): the ARIA semantics and within-strip keyboard navigation Dockview ships by default diff --git a/packages/docs/docs/advanced/keyboard.mdx b/packages/docs/docs/advanced/keyboard.mdx index d5f4071a3..cedc949bc 100644 --- a/packages/docs/docs/advanced/keyboard.mdx +++ b/packages/docs/docs/advanced/keyboard.mdx @@ -9,7 +9,7 @@ sidebar_custom_props: import { DocRef } from '@site/src/components/ui/reference/docRef'; -Dockview can be driven entirely from the keyboard — switching tabs, moving focus +Dockview can be driven entirely from the keyboard: switching tabs, moving focus between groups, and even docking a panel into a new position, all without a mouse. This page covers the built-in keymap and keyboard docking. For the accessibility semantics that back it (ARIA roles, screen-reader announcements, @@ -54,7 +54,7 @@ const options = { }; ``` -The keymap is rebindable — pass an object with a `keymap` to override individual +The keymap is rebindable: pass an object with a `keymap` to override individual keys. Unset keys keep their defaults: ```ts @@ -71,7 +71,7 @@ const options = { Each binding is a `+`-separated string, modifiers first. Recognised modifiers are `ctrl`, `shift`, `alt`, and `meta` (alias `cmd`); the final part is the [`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) -to match, case-insensitively — e.g. `'ctrl+]'`, `'shift+f6'`, `'ctrl+tab'`. +to match, case-insensitively, for example `'ctrl+]'`, `'shift+f6'`, `'ctrl+tab'`. ## Moving between tabs and groups @@ -85,11 +85,11 @@ to match, case-insensitively — e.g. `'ctrl+]'`, `'shift+f6'`, `'ctrl+tab'`. | Move focus to the group in a direction | `Ctrl+Shift+←/→/↑/↓` | `focusGroup{Left,Right,Up,Down}` | `F6` / `Shift+F6` cycle the groups in list order. `Ctrl+Shift+Arrows` jump to -the visually adjacent group instead — the same geometry used by the +the visually adjacent group instead, the same geometry used by the [`adjacentGroupInDirection`](/docs/advanced/focus-navigation) API, so mouse and keyboard agree on what "the group to the left" is. Once focus lands on the tab strip (via `Ctrl+Shift+\` or `F6`), -the strip's own arrow-key navigation takes over — see +the strip's own arrow-key navigation takes over. See [Accessibility](/docs/advanced/accessibility#keyboard-navigation). ## Keyboard docking @@ -98,9 +98,9 @@ Press `Ctrl+M` to dock the active panel somewhere new without dragging. A live drop preview follows the current selection, and each step is announced to screen readers: -1. **Pick a target group** — arrow keys cycle through the groups (including the +1. **Pick a target group**: arrow keys cycle through the groups (including the panel's own, so you can split a tab out of its group); `Enter` selects one. -2. **Pick an edge** — arrow keys choose a split edge (left / right / top / +2. **Pick an edge**: arrow keys choose a split edge (left / right / top / bottom), or the centre to tab into the group; `Enter` commits the move. `Esc` steps back a phase, or cancels the move entirely from the first phase. diff --git a/packages/docs/docs/api/dockview/groupApi.mdx b/packages/docs/docs/api/dockview/groupApi.mdx index 6cd2d1674..19aebea76 100644 --- a/packages/docs/docs/api/dockview/groupApi.mdx +++ b/packages/docs/docs/api/dockview/groupApi.mdx @@ -1,12 +1,12 @@ --- title: Group API sidebar_position: 3 -description: Reference for the Dockview Group API — methods and events for controlling individual groups. +description: Reference for the Dockview Group API: methods and events for controlling individual groups. --- import { DocRef } from '@site/src/components/ui/reference/docRef'; -The group API controls a single group of panels — its active panel, location, and header. +The group API controls a single group of panels: its active panel, location, and header. :::info Use the group API sparingly. As you move panels, groups change and if you don't track this correctly you may encounter unexpected @@ -17,5 +17,5 @@ behaviours. You should be able to achieve most things directly through the panel ## See also -- [Add a group](/docs/core/groups/add) — how groups are created and populated. -- [Add a panel](/docs/core/panels/add) — the panels a group contains. +- [Add a group](/docs/core/groups/add): how groups are created and populated. +- [Add a panel](/docs/core/panels/add): the panels a group contains. diff --git a/packages/docs/docs/api/dockview/options.mdx b/packages/docs/docs/api/dockview/options.mdx index 3db1308d8..78c7c643f 100644 --- a/packages/docs/docs/api/dockview/options.mdx +++ b/packages/docs/docs/api/dockview/options.mdx @@ -1,7 +1,7 @@ --- title: Options sidebar_position: 0 -description: Configuration options for the Dockview component — props and initialization settings. +description: Configuration options for the Dockview component: props and initialization settings. --- import { DocRef } from '@site/src/components/ui/reference/docRef'; @@ -26,5 +26,5 @@ The options available when creating a Dockview component. ## See also -- [Dockview overview](/docs/core/overview) — where these options fit in the bigger picture. -- [Panel rendering](/docs/core/panels/rendering) — the rendering behaviour several options control. +- [Dockview overview](/docs/core/overview): where these options fit in the bigger picture. +- [Panel rendering](/docs/core/panels/rendering): the rendering behaviour several options control. diff --git a/packages/docs/docs/api/dockview/overview.mdx b/packages/docs/docs/api/dockview/overview.mdx index 0601384f3..2902673bf 100644 --- a/packages/docs/docs/api/dockview/overview.mdx +++ b/packages/docs/docs/api/dockview/overview.mdx @@ -1,16 +1,16 @@ --- title: API sidebar_position: 1 -description: Full reference for the Dockview API — the primary interface for creating and managing panels and groups. +description: Full reference for the Dockview API: the primary interface for creating and managing panels and groups. --- import { DocRef } from '@site/src/components/ui/reference/docRef'; -The `DockviewApi` is the primary interface for controlling a Dockview instance — adding panels and groups, saving and restoring layouts, and subscribing to events. +The `DockviewApi` is the primary interface for controlling a Dockview instance: adding panels and groups, saving and restoring layouts, and subscribing to events. ## See also -- [Dockview overview](/docs/core/overview) — the concepts and setup behind Dockview. -- [Add a panel](/docs/core/panels/add) — how to populate the layout with content. +- [Dockview overview](/docs/core/overview): the concepts and setup behind Dockview. +- [Add a panel](/docs/core/panels/add): how to populate the layout with content. diff --git a/packages/docs/docs/api/dockview/panelApi.mdx b/packages/docs/docs/api/dockview/panelApi.mdx index 73454c8e8..dd9993501 100644 --- a/packages/docs/docs/api/dockview/panelApi.mdx +++ b/packages/docs/docs/api/dockview/panelApi.mdx @@ -1,16 +1,16 @@ --- title: Panel API sidebar_position: 2 -description: Reference for the Dockview Panel API — methods and events available within individual panels. +description: Reference for the Dockview Panel API: methods and events available within individual panels. --- import { DocRef } from '@site/src/components/ui/reference/docRef'; -The panel API controls a single Dockview panel — sizing, visibility, focus, and parameter updates. +The panel API controls a single Dockview panel: sizing, visibility, focus, and parameter updates. ## See also -- [Add a panel](/docs/core/panels/add) — how panels are created and referenced. -- [Panel rendering](/docs/core/panels/rendering) — how a panel's content is rendered. +- [Add a panel](/docs/core/panels/add): how panels are created and referenced. +- [Panel rendering](/docs/core/panels/rendering): how a panel's content is rendered. diff --git a/packages/docs/docs/api/gridview/api.mdx b/packages/docs/docs/api/gridview/api.mdx index 94518b90b..13beeec0e 100644 --- a/packages/docs/docs/api/gridview/api.mdx +++ b/packages/docs/docs/api/gridview/api.mdx @@ -1,15 +1,15 @@ --- title: API sidebar_position: 1 -description: Full reference for the Gridview API — methods and events for controlling the grid layout. +description: Full reference for the Gridview API: methods and events for controlling the grid layout. --- import { DocRef } from '@site/src/components/ui/reference/docRef'; -The `GridviewApi` is the primary interface for controlling a Gridview instance — adding and moving panels, saving and restoring layouts, and subscribing to events. +The `GridviewApi` is the primary interface for controlling a Gridview instance: adding and moving panels, saving and restoring layouts, and subscribing to events. ## See also -- [Gridview overview](/docs/other/gridview/overview) — concepts and a live example of the grid. +- [Gridview overview](/docs/other/gridview/overview): concepts and a live example of the grid. diff --git a/packages/docs/docs/api/gridview/options.mdx b/packages/docs/docs/api/gridview/options.mdx index bcdf6aad8..72a7d8282 100644 --- a/packages/docs/docs/api/gridview/options.mdx +++ b/packages/docs/docs/api/gridview/options.mdx @@ -1,7 +1,7 @@ --- title: Options sidebar_position: 0 -description: Configuration options for the Gridview component — props and initialization settings. +description: Configuration options for the Gridview component: props and initialization settings. --- import { DocRef } from '@site/src/components/ui/reference/docRef'; @@ -26,4 +26,4 @@ The options available when creating a Gridview component. ## See also -- [Gridview overview](/docs/other/gridview/overview) — concepts and a live example of the grid. +- [Gridview overview](/docs/other/gridview/overview): concepts and a live example of the grid. diff --git a/packages/docs/docs/api/gridview/panelApi.mdx b/packages/docs/docs/api/gridview/panelApi.mdx index e764d1657..b11cd28da 100644 --- a/packages/docs/docs/api/gridview/panelApi.mdx +++ b/packages/docs/docs/api/gridview/panelApi.mdx @@ -1,15 +1,15 @@ --- title: Panel API sidebar_position: 2 -description: Reference for the Gridview Panel API — methods and events available within individual grid panels. +description: Reference for the Gridview Panel API: methods and events available within individual grid panels. --- import { DocRef } from '@site/src/components/ui/reference/docRef'; -The panel API controls a single Gridview panel — sizing, visibility, focus, and parameter updates. +The panel API controls a single Gridview panel: sizing, visibility, focus, and parameter updates. ## See also -- [Gridview overview](/docs/other/gridview/overview) — concepts and a live example of the grid. +- [Gridview overview](/docs/other/gridview/overview): concepts and a live example of the grid. diff --git a/packages/docs/docs/api/paneview/api.mdx b/packages/docs/docs/api/paneview/api.mdx index a999de531..f0ba99d1f 100644 --- a/packages/docs/docs/api/paneview/api.mdx +++ b/packages/docs/docs/api/paneview/api.mdx @@ -1,15 +1,15 @@ --- title: API sidebar_position: 1 -description: Full reference for the Paneview API — methods and events for controlling the pane layout. +description: Full reference for the Paneview API: methods and events for controlling the pane layout. --- import { DocRef } from '@site/src/components/ui/reference/docRef'; -The `PaneviewApi` is the primary interface for controlling a Paneview instance — adding and moving panes, saving and restoring layouts, and subscribing to events. +The `PaneviewApi` is the primary interface for controlling a Paneview instance: adding and moving panes, saving and restoring layouts, and subscribing to events. ## See also -- [Paneview overview](/docs/other/paneview/overview) — concepts and a live example of the pane view. +- [Paneview overview](/docs/other/paneview/overview): concepts and a live example of the pane view. diff --git a/packages/docs/docs/api/paneview/options.mdx b/packages/docs/docs/api/paneview/options.mdx index d506fb6f4..985ae0e92 100644 --- a/packages/docs/docs/api/paneview/options.mdx +++ b/packages/docs/docs/api/paneview/options.mdx @@ -1,7 +1,7 @@ --- title: Options sidebar_position: 0 -description: Configuration options for the Paneview component — props and initialization settings. +description: Configuration options for the Paneview component: props and initialization settings. --- import { DocRef } from '@site/src/components/ui/reference/docRef'; @@ -26,4 +26,4 @@ The options available when creating a Paneview component. ## See also -- [Paneview overview](/docs/other/paneview/overview) — concepts and a live example of the pane view. +- [Paneview overview](/docs/other/paneview/overview): concepts and a live example of the pane view. diff --git a/packages/docs/docs/api/paneview/panelApi.mdx b/packages/docs/docs/api/paneview/panelApi.mdx index 971315a8e..0dcaf3dd2 100644 --- a/packages/docs/docs/api/paneview/panelApi.mdx +++ b/packages/docs/docs/api/paneview/panelApi.mdx @@ -1,15 +1,15 @@ --- title: Panel API sidebar_position: 2 -description: Reference for the Paneview Panel API — methods and events available within individual pane panels. +description: Reference for the Paneview Panel API: methods and events available within individual pane panels. --- import { DocRef } from '@site/src/components/ui/reference/docRef'; -The panel API controls a single Paneview pane — sizing, visibility, focus, and parameter updates. +The panel API controls a single Paneview pane: sizing, visibility, focus, and parameter updates. ## See also -- [Paneview overview](/docs/other/paneview/overview) — concepts and a live example of the pane view. +- [Paneview overview](/docs/other/paneview/overview): concepts and a live example of the pane view. diff --git a/packages/docs/docs/api/splitview/api.mdx b/packages/docs/docs/api/splitview/api.mdx index 301820dc2..0d3cb588a 100644 --- a/packages/docs/docs/api/splitview/api.mdx +++ b/packages/docs/docs/api/splitview/api.mdx @@ -1,15 +1,15 @@ --- title: API sidebar_position: 1 -description: Full reference for the Splitview API — methods and events for controlling the split layout. +description: Full reference for the Splitview API: methods and events for controlling the split layout. --- import { DocRef } from '@site/src/components/ui/reference/docRef'; -The `SplitviewApi` is the primary interface for controlling a Splitview instance — adding and moving views, saving and restoring layouts, and subscribing to events. +The `SplitviewApi` is the primary interface for controlling a Splitview instance: adding and moving views, saving and restoring layouts, and subscribing to events. ## See also -- [Splitview overview](/docs/other/splitview/overview) — concepts and a live example of the split view. +- [Splitview overview](/docs/other/splitview/overview): concepts and a live example of the split view. diff --git a/packages/docs/docs/api/splitview/options.mdx b/packages/docs/docs/api/splitview/options.mdx index 83d81ccc9..a8870b0c0 100644 --- a/packages/docs/docs/api/splitview/options.mdx +++ b/packages/docs/docs/api/splitview/options.mdx @@ -1,7 +1,7 @@ --- title: Options sidebar_position: 0 -description: Configuration options for the Splitview component — props and initialization settings. +description: Configuration options for the Splitview component: props and initialization settings. --- import { DocRef } from '@site/src/components/ui/reference/docRef'; @@ -26,4 +26,4 @@ The options available when creating a Splitview component. ## See also -- [Splitview overview](/docs/other/splitview/overview) — concepts and a live example of the split view. +- [Splitview overview](/docs/other/splitview/overview): concepts and a live example of the split view. diff --git a/packages/docs/docs/api/splitview/panelApi.mdx b/packages/docs/docs/api/splitview/panelApi.mdx index d0a03903d..71d01acde 100644 --- a/packages/docs/docs/api/splitview/panelApi.mdx +++ b/packages/docs/docs/api/splitview/panelApi.mdx @@ -1,15 +1,15 @@ --- title: Panel API sidebar_position: 2 -description: Reference for the Splitview Panel API — methods and events available within individual split panels. +description: Reference for the Splitview Panel API: methods and events available within individual split panels. --- import { DocRef } from '@site/src/components/ui/reference/docRef'; -The panel API controls a single Splitview panel — sizing, visibility, focus, and parameter updates. +The panel API controls a single Splitview panel: sizing, visibility, focus, and parameter updates. ## See also -- [Splitview overview](/docs/other/splitview/overview) — concepts and a live example of the split view. +- [Splitview overview](/docs/other/splitview/overview): concepts and a live example of the split view. diff --git a/packages/docs/docs/core/dnd/disable.mdx b/packages/docs/docs/core/dnd/disable.mdx index c67f38558..b44d8d86d 100644 --- a/packages/docs/docs/core/dnd/disable.mdx +++ b/packages/docs/docs/core/dnd/disable.mdx @@ -30,12 +30,12 @@ You may want to combine this with `locked={true}` to provide a locked grid with ## Building a tabview -Selectively restricting the default drag and drop behaviours turns a dock into a plain _tabview_ — a single group of tabs with no rearranging. The example below shows the effect: +Selectively restricting the default drag and drop behaviours turns a dock into a plain _tabview_: a single group of tabs with no rearranging. The example below shows the effect: ## See also -- [Drag and drop strategy](/docs/core/dnd/strategy) — `disableDnd` overrides whichever backend is selected. -- [Drag and drop](/docs/core/dnd/dragAndDrop) — the drag and drop behaviour you are switching off. -- [Tabs](/docs/core/panels/tabs) — customising how tabs are rendered. +- [Drag and drop strategy](/docs/core/dnd/strategy): `disableDnd` overrides whichever backend is selected. +- [Drag and drop](/docs/core/dnd/dragAndDrop): the drag and drop behaviour you are switching off. +- [Tabs](/docs/core/panels/tabs): customising how tabs are rendered. diff --git a/packages/docs/docs/core/dnd/dragAndDrop.mdx b/packages/docs/docs/core/dnd/dragAndDrop.mdx index 9a298f498..3aecb91a7 100644 --- a/packages/docs/docs/core/dnd/dragAndDrop.mdx +++ b/packages/docs/docs/core/dnd/dragAndDrop.mdx @@ -75,7 +75,7 @@ const api = createDockview(parentElement, { For interaction with the drag events directly the component exposes some methods to help determine whether external drag events should be interacted with or not. -The `onDidDrop` handler and `onUnhandledDragOver` registration use the same API across all frameworks — only the component wiring differs. +The `onDidDrop` handler and `onUnhandledDragOver` registration use the same API across all frameworks; only the component wiring differs. ```ts /** @@ -142,7 +142,7 @@ parentElement.addEventListener('drop', (e) => onDidDrop(e)); ## Customising the group drag ghost -When the user drags a whole group of panels by its empty header area, Dockview shows a small floating ghost that follows the cursor. By default it renders the text `Multiple Panels (N)` — to localise the label or replace the visual entirely, supply a `createGroupDragGhostComponent` factory. It receives the `DockviewGroupPanel` being dragged and must return an `IGroupDragGhostRenderer`. +When the user drags a whole group of panels by its empty header area, Dockview shows a small floating ghost that follows the cursor. By default it renders the text `Multiple Panels (N)`. To localise the label or replace the visual entirely, supply a `createGroupDragGhostComponent` factory. It receives the `DockviewGroupPanel` being dragged and must return an `IGroupDragGhostRenderer`. @@ -170,7 +170,7 @@ interface IGroupDragGhostRenderer { } ```` -The ghost is captured by the browser at drag start and removed shortly after, so the component is short-lived — render synchronously enough to be painted before the browser snapshots the element. +The ghost is captured by the browser at drag start and removed shortly after, so the component is short-lived; render synchronously enough to be painted before the browser snapshots the element. ```tsx @@ -233,8 +233,8 @@ createGroupDragGhostComponent: (group) => new MyGroupDragGhost(), ## See also -- [External drag and drop events](/docs/core/dnd/external) — intercept drops that originate outside Dockview. -- [Drag and drop strategy](/docs/core/dnd/strategy) — choose the HTML5 or pointer backend and tune touch gestures. -- [Third-party libraries](/docs/core/dnd/thirdParty) — using other drag and drop libraries inside a panel. -- [Disable drag and drop](/docs/core/dnd/disable) — turn dragging off for a fixed layout. +- [External drag and drop events](/docs/core/dnd/external): intercept drops that originate outside Dockview. +- [Drag and drop strategy](/docs/core/dnd/strategy): choose the HTML5 or pointer backend and tune touch gestures. +- [Third-party libraries](/docs/core/dnd/thirdParty): using other drag and drop libraries inside a panel. +- [Disable drag and drop](/docs/core/dnd/disable): turn dragging off for a fixed layout. ``` diff --git a/packages/docs/docs/core/dnd/dropGuide.mdx b/packages/docs/docs/core/dnd/dropGuide.mdx index 084be2903..8e2219807 100644 --- a/packages/docs/docs/core/dnd/dropGuide.mdx +++ b/packages/docs/docs/core/dnd/dropGuide.mdx @@ -45,9 +45,9 @@ const api = createDockview(element, { While dragging over an accepting group the compass shows: -- **Inner cells** (`top` / `bottom` / `left` / `right` / `center`) — split this group on that edge, or `center` to +- **Inner cells** (`top` / `bottom` / `left` / `right` / `center`): split this group on that edge, or `center` to tab into the group. These have the same result as today's cursor quadrants. -- **Outer cells** (`top` / `bottom` / `left` / `right`) — dock against the **whole layout** edge, even though the +- **Outer cells** (`top` / `bottom` / `left` / `right`): dock against the **whole layout** edge, even though the cursor is over a group. A cell is only shown when a drop there is actually possible, so the compass reflects exactly the legal drops for the @@ -69,12 +69,12 @@ const api = createDockview(element, { }); ``` -- `zones` — restrict which **inner** cells appear. For example `['center']` allows reorder / merge only. +- `zones`: restrict which **inner** cells appear. For example `['center']` allows reorder / merge only. Defaults to all zones the target accepts. -- `edges` — include the **outer** whole-layout-edge cells. Defaults to `true`; set `false` for group-only docking. +- `edges`: include the **outer** whole-layout-edge cells. Defaults to `true`; set `false` for group-only docking. ## See also -- [Smart Guides](/docs/core/dnd/smartGuides) — alignment snapping for floating groups. -- [Drop overlay](/docs/core/dnd/overlay) — customise the overlay that previews the resolved drop zone. -- [Drop Position Resolver](/docs/core/dnd/dropPosition) — a lower-level seam to override where a pointer maps to a drop position. +- [Smart Guides](/docs/core/dnd/smartGuides): alignment snapping for floating groups. +- [Drop overlay](/docs/core/dnd/overlay): customise the overlay that previews the resolved drop zone. +- [Drop Position Resolver](/docs/core/dnd/dropPosition): a lower-level seam to override where a pointer maps to a drop position. diff --git a/packages/docs/docs/core/dnd/dropPosition.mdx b/packages/docs/docs/core/dnd/dropPosition.mdx index 51cafac58..61eed80af 100644 --- a/packages/docs/docs/core/dnd/dropPosition.mdx +++ b/packages/docs/docs/core/dnd/dropPosition.mdx @@ -39,7 +39,7 @@ unaffected). When unset, the built-in cursor-quadrant behaviour is used, unchang /> -A `PositionResolver` maps the pointer location within a target to a drop `Position` — or `null` for no drop. Both drag +A `PositionResolver` maps the pointer location within a target to a drop `Position`, or `null` for no drop. Both drag backends consult the same resolver. It is read live, so it can be swapped at runtime via `api.updateOptions`. ```ts @@ -93,12 +93,12 @@ const api = createDockview(element, { :::info The visual aim-at-a-cell overlay is covered in [Drop Guide](/docs/core/dnd/dropGuide). That compass (`dndGuide`) -installs its own resolver, so enable one or the other — `dndGuide` when you want the built-in aim-at-a-cell affordance, +installs its own resolver, so enable one or the other: `dndGuide` when you want the built-in aim-at-a-cell affordance, `dropPositionResolver` when you want full control over the resolved position. ::: ## See also -- [Drop overlay](/docs/core/dnd/overlay) — shape the overlay that previews the resolved drop zone. -- [Drop guide](/docs/core/dnd/dropGuide) — the aim-at-a-cell compass built on top of this resolver. -- [Smart guides](/docs/core/dnd/smartGuides) — alignment snapping for floating groups. +- [Drop overlay](/docs/core/dnd/overlay): shape the overlay that previews the resolved drop zone. +- [Drop guide](/docs/core/dnd/dropGuide): the aim-at-a-cell compass built on top of this resolver. +- [Smart guides](/docs/core/dnd/smartGuides): alignment snapping for floating groups. diff --git a/packages/docs/docs/core/dnd/external.mdx b/packages/docs/docs/core/dnd/external.mdx index 19e0648ff..e9351a302 100644 --- a/packages/docs/docs/core/dnd/external.mdx +++ b/packages/docs/docs/core/dnd/external.mdx @@ -28,17 +28,17 @@ Narrow before reading `DragEvent`-only fields like `dataTransfer`: ```ts api.onWillDragPanel((event) => { if (!(event.nativeEvent instanceof DragEvent)) { - return; // touch / pen drag — no DataTransfer + return; // touch / pen drag, no DataTransfer } event.nativeEvent.dataTransfer?.setData('text/plain', '...'); }); ``` -Touch and pen drags cannot bridge to external HTML5 drop zones, so skipping them here is the intended behaviour — the drag still works inside Dockview. +Touch and pen drags cannot bridge to external HTML5 drop zones, so skipping them here is the intended behaviour; the drag still works inside Dockview. ## See also -- [Drag and drop](/docs/core/dnd/dragAndDrop) — the drag events and hooks these utilities build on. -- [Third-party libraries](/docs/core/dnd/thirdParty) — using other drag and drop libraries inside a panel. -- [Drag and drop strategy](/docs/core/dnd/strategy) — why `nativeEvent` can be a `PointerEvent`, and the touch / pen backend. -- [Disable drag and drop](/docs/core/dnd/disable) — turn drag and drop off entirely. +- [Drag and drop](/docs/core/dnd/dragAndDrop): the drag events and hooks these utilities build on. +- [Third-party libraries](/docs/core/dnd/thirdParty): using other drag and drop libraries inside a panel. +- [Drag and drop strategy](/docs/core/dnd/strategy): why `nativeEvent` can be a `PointerEvent`, and the touch / pen backend. +- [Disable drag and drop](/docs/core/dnd/disable): turn drag and drop off entirely. diff --git a/packages/docs/docs/core/dnd/overlay.mdx b/packages/docs/docs/core/dnd/overlay.mdx index a8f169353..ff2af27cb 100644 --- a/packages/docs/docs/core/dnd/overlay.mdx +++ b/packages/docs/docs/core/dnd/overlay.mdx @@ -6,7 +6,7 @@ description: Shape the drag-and-drop overlay per target with the dropOverlayMode When you drag a panel or group over Dockview, a highlighted overlay previews where it will land. The `dropOverlayModel` option lets you shape that overlay -**per drop target** — its size, the activation threshold, and the small-element +**per drop target**: its size, the activation threshold, and the small-element boundaries. :::info @@ -46,13 +46,13 @@ The returned model accepts: ## The outer edge overlay -`dropOverlayModel` does **not** dispatch the `'edge'` target — the overlay shown +`dropOverlayModel` does **not** dispatch the `'edge'` target, the overlay shown when dragging to the outer edges of the whole layout. That is configured separately via the `dndEdges` option. If you were using `rootOverlayModel` purely to size the outer edge overlay, use `dndEdges` instead. ## See also -- [Drop position resolver](/docs/core/dnd/dropPosition) — override where a pointer location maps to a drop position. -- [Drop guide](/docs/core/dnd/dropGuide) — the VS Code-style aim-at-a-cell compass overlay. -- [Smart guides](/docs/core/dnd/smartGuides) — alignment snapping and guides for floating groups. +- [Drop position resolver](/docs/core/dnd/dropPosition): override where a pointer location maps to a drop position. +- [Drop guide](/docs/core/dnd/dropGuide): the VS Code-style aim-at-a-cell compass overlay. +- [Smart guides](/docs/core/dnd/smartGuides): alignment snapping and guides for floating groups. diff --git a/packages/docs/docs/core/dnd/overview.mdx b/packages/docs/docs/core/dnd/overview.mdx index a16c6a846..c3a0b7e96 100644 --- a/packages/docs/docs/core/dnd/overview.mdx +++ b/packages/docs/docs/core/dnd/overview.mdx @@ -1,12 +1,12 @@ --- title: 'Overview' sidebar_position: 0 -description: Overview of built-in drag and drop capabilities in Dockview — tab reordering, group merging, and edge drop positions. +description: Overview of built-in drag and drop capabilities in Dockview: tab reordering, group merging, and edge drop positions. --- import useBaseUrl from '@docusaurus/useBaseUrl'; -Dockview supports a wide variety of built-in Drag and Drop possibilities. +Dockview supports a range of built-in drag and drop behaviours. #### Position a tab between two other tabs @@ -60,13 +60,13 @@ Dockview supports a wide variety of built-in Drag and Drop possibilities. ## Touch and pen input -Mouse drags use the browser's HTML5 drag-and-drop. Touch and pen drags are driven by a pointer-events backend with a long-press-to-drag gesture, so taps and native scroll still work on mobile. The backend is selected automatically and can be overridden — see [Dnd Strategy](./strategy) for the `dndStrategy` option and the full gesture table. +Mouse drags use the browser's HTML5 drag-and-drop. Touch and pen drags are driven by a pointer-events backend with a long-press-to-drag gesture, so taps and native scroll still work on mobile. The backend is selected automatically and can be overridden. See [Dnd Strategy](./strategy) for the `dndStrategy` option and the full gesture table. ## Advanced drag-and-drop hooks -Dockview exposes advanced drag-and-drop hooks — `onWillDragPanel`, `onWillDragGroup`, `onWillDrop` and `onWillShowOverlay` — for attaching metadata to drags, cancelling a drag, or customising the drop overlay. See [Dnd](./dragAndDrop) and [External Dnd Events](./external) for details. +Dockview exposes advanced drag-and-drop hooks (`onWillDragPanel`, `onWillDragGroup`, `onWillDrop` and `onWillShowOverlay`) for attaching metadata to drags, cancelling a drag, or customising the drop overlay. See [Dnd](./dragAndDrop) and [External Dnd Events](./external) for details. ## Going further -- [Drop Guide](./dropGuide) — show a VS Code-style aim-at-a-cell compass while dragging, or override where a drop lands with a pluggable position resolver. -- [Smart Guides](./smartGuides) — alignment snapping and guide overlays for floating groups. +- [Drop Guide](./dropGuide): show a VS Code-style aim-at-a-cell compass while dragging, or override where a drop lands with a pluggable position resolver. +- [Smart Guides](./smartGuides): alignment snapping and guide overlays for floating groups. diff --git a/packages/docs/docs/core/dnd/smartGuides.mdx b/packages/docs/docs/core/dnd/smartGuides.mdx index 4b5e4e475..da77c2a0c 100644 --- a/packages/docs/docs/core/dnd/smartGuides.mdx +++ b/packages/docs/docs/core/dnd/smartGuides.mdx @@ -54,7 +54,7 @@ const api = createDockview(element, { ### How snapping works - **Alignment.** As a floating group is dragged, its leading edge, center, and trailing edge on each axis are compared against the alignment lines contributed by the other floating groups and the container. When a probe lands within `snapDistance` of a line, the group snaps so the two align exactly, and a guide line is drawn. -- **Independent X and Y.** The horizontal and vertical axes are resolved independently — a group can snap horizontally to one neighbour and vertically to another at the same time, drawing a guide for each alignment. +- **Independent X and Y.** The horizontal and vertical axes are resolved independently; a group can snap horizontally to one neighbour and vertically to another at the same time, drawing a guide for each alignment. - **Hysteresis.** To avoid the group "sticking then jumping" at the snap boundary, a snap engages at `snapDistance` but only releases once the pointer moves past `snapDistance + releaseDistance`. This asymmetric threshold keeps snapping stable and stops oscillation. - **Guides.** Set `showGuides: false` to keep the magnetic snapping behaviour but hide the alignment lines. @@ -64,9 +64,9 @@ Choose which sources a dragged floating group aligns against with `snapTargets`: -- `floats` (default `true`) — align to the other floating groups' edges and centers. -- `container` (default `true`) — align to the container's edges and center. Set `containerInset` to also emit guide lines a fixed number of pixels inside the container edges (e.g. a content margin). -- `splitters` (default `false`) — align to the underlying grid's splitter (sash) positions, so a floating group can line up with the docked layout behind it. +- `floats` (default `true`): align to the other floating groups' edges and centers. +- `container` (default `true`): align to the container's edges and center. Set `containerInset` to also emit guide lines a fixed number of pixels inside the container edges (e.g. a content margin). +- `splitters` (default `false`): align to the underlying grid's splitter (sash) positions, so a floating group can line up with the docked layout behind it. ```ts const api = createDockview(element, { @@ -92,7 +92,7 @@ A drop preview is shown during the drag, and the dock/merge is committed on drop ### Disabling snapping mid-drag -Hold the configured modifier key while dragging to temporarily suspend snapping and hide the guides — the floating group then follows the pointer freely (Figma / Keynote parity). Snapping re-engages as soon as the modifier is released. +Hold the configured modifier key while dragging to temporarily suspend snapping and hide the guides; the floating group then follows the pointer freely (Figma / Keynote parity). Snapping re-engages as soon as the modifier is released. The modifier defaults to `Alt` and is configured via `disableSnapModifier` (`'alt' | 'ctrl' | 'meta' | 'shift'`, or `false` to remove the gate entirely). @@ -139,8 +139,8 @@ Two events fire when a drag commits on drop: methods={['onDidSnapFloat', 'onDidSnapTogether']} /> -- `onDidSnapFloat` — fires when a dragged floating group commits an **alignment** snap on drop, reporting which axes (`'x'` / `'y'`) were snapped. -- `onDidSnapTogether` — fires when a dragged floating group **docks or merges** into another on drop, reporting the `target` group and the `position` (`'left' | 'right' | 'top' | 'bottom' | 'center'`). +- `onDidSnapFloat`: fires when a dragged floating group commits an **alignment** snap on drop, reporting which axes (`'x'` / `'y'`) were snapped. +- `onDidSnapTogether`: fires when a dragged floating group **docks or merges** into another on drop, reporting the `target` group and the `position` (`'left' | 'right' | 'top' | 'bottom' | 'center'`). ```ts api.onDidSnapFloat((event) => { @@ -160,6 +160,6 @@ api.onDidSnapTogether((event) => { ## See also -- [Drop guide](/docs/core/dnd/dropGuide) — aim-at-a-cell compass for docking into groups. -- [Drop overlay](/docs/core/dnd/overlay) — shape the drop-preview overlay. -- [Floating groups](/docs/core/groups/floatingGroups) — the floating groups Smart Guides align and snap. +- [Drop guide](/docs/core/dnd/dropGuide): aim-at-a-cell compass for docking into groups. +- [Drop overlay](/docs/core/dnd/overlay): shape the drop-preview overlay. +- [Floating groups](/docs/core/groups/floatingGroups): the floating groups Smart Guides align and snap. diff --git a/packages/docs/docs/core/dnd/strategy.mdx b/packages/docs/docs/core/dnd/strategy.mdx index 0cffb2dd1..f50bd995f 100644 --- a/packages/docs/docs/core/dnd/strategy.mdx +++ b/packages/docs/docs/core/dnd/strategy.mdx @@ -12,7 +12,7 @@ import { DocRef } from '@site/src/components/ui/reference/docRef'; | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `'auto'` (default) | HTML5 drives mouse drags; pointer events drive touch and pen drags. | | `'pointer'` | Pointer events drive every input type. Useful where HTML5 drag-and-drop is unreliable (some Linux browsers, certain Safari versions, embedded webviews). Cross-window HTML5 drag and the native browser drag image are not available in this mode. | -| `'html5'` | HTML5 drag-and-drop only — touch and pen drags are disabled. | +| `'html5'` | HTML5 drag-and-drop only; touch and pen drags are disabled. | `disableDnd: true` overrides every strategy. The strategy can also be changed at runtime via `api.updateOptions({ dndStrategy: ... })`; the change propagates to every existing drag source. @@ -46,6 +46,6 @@ Under `'auto'` and `'pointer'`, touch drags use a long-press-then-drag gesture s ## See also -- [Drag and drop](/docs/core/dnd/dragAndDrop) — the drag events and hooks the backend drives. -- [External drag and drop events](/docs/core/dnd/external) — narrowing `nativeEvent` across the two backends. -- [Disable drag and drop](/docs/core/dnd/disable) — `disableDnd` overrides every strategy. +- [Drag and drop](/docs/core/dnd/dragAndDrop): the drag events and hooks the backend drives. +- [External drag and drop events](/docs/core/dnd/external): narrowing `nativeEvent` across the two backends. +- [Disable drag and drop](/docs/core/dnd/disable): `disableDnd` overrides every strategy. diff --git a/packages/docs/docs/core/dnd/thirdParty.mdx b/packages/docs/docs/core/dnd/thirdParty.mdx index 6241d1a07..64766182d 100644 --- a/packages/docs/docs/core/dnd/thirdParty.mdx +++ b/packages/docs/docs/core/dnd/thirdParty.mdx @@ -15,5 +15,5 @@ raise an issue. ## See also -- [Drag and drop](/docs/core/dnd/dragAndDrop) — Dockview's own drag and drop and the events it exposes. -- [External drag and drop events](/docs/core/dnd/external) — intercept drops entering the layout from outside. +- [Drag and drop](/docs/core/dnd/dragAndDrop): Dockview's own drag and drop and the events it exposes. +- [External drag and drop events](/docs/core/dnd/external): intercept drops entering the layout from outside. diff --git a/packages/docs/docs/core/events.mdx b/packages/docs/docs/core/events.mdx index 3d3a10fbe..38263fe1e 100644 --- a/packages/docs/docs/core/events.mdx +++ b/packages/docs/docs/core/events.mdx @@ -1,12 +1,12 @@ --- title: Events sidebar_position: 7 -description: Reference for Dockview events — subscribe to layout changes, panel lifecycle, focus changes, and more. +description: Reference for Dockview events: subscribe to layout changes, panel lifecycle, focus changes, and more. --- import { DocRef } from '@site/src/components/ui/reference/docRef'; -`DockviewApi` exposes a comprehensive set of events so your application can react to layout changes. All events follow the same subscription pattern and return a disposable that you should call when you no longer need the listener. +`DockviewApi` exposes events so your application can react to layout changes. All events follow the same subscription pattern and return a disposable that you should call when you no longer need the listener. ```ts const disposable = api.onDidAddPanel((panel) => { @@ -77,7 +77,7 @@ api.onDidMaximizedGroupChange((event: DockviewMaximizedGroupChangeEvent) => {}); ### Mutation boundary -`onWillMutateLayout` and `onDidMutateLayout` bracket each top-level structural change to the layout. Unlike `onDidLayoutChange` — which is coalesced and only fires _after_ a change — these provide an explicit before/after pair, so you can capture a snapshot of the layout _before_ the mutation runs. This makes them the right hook for autosave, dirty-tracking and undo/redo. +`onWillMutateLayout` and `onDidMutateLayout` bracket each top-level structural change to the layout. Unlike `onDidLayoutChange` (which is coalesced and only fires _after_ a change), these provide an explicit before/after pair, so you can capture a snapshot of the layout _before_ the mutation runs. This makes them the right hook for autosave, dirty-tracking and undo/redo. ```ts // Fires immediately before a structural mutation @@ -94,7 +94,7 @@ api.onDidMutateLayout((event: DockviewLayoutMutationEvent) => {}); A compound operation brackets as a **single** transaction: dragging a panel to a new group, or restoring a whole layout via `fromJSON`, fires exactly one before/after pair rather than one per internal step. -`event.origin` distinguishes _who_ caused the change — `'user'` for direct interaction (drag-and-drop, tab UI), `'api'` for a programmatic `DockviewApi` call made by your own code — so consumers such as an undo stack can choose to ignore the app's own programmatic mutations. +`event.origin` distinguishes _who_ caused the change: `'user'` for direct interaction (drag-and-drop, tab UI), `'api'` for a programmatic `DockviewApi` call made by your own code. Consumers such as an undo stack can use this to ignore the app's own programmatic mutations. ## Drag and drop @@ -141,7 +141,7 @@ api.onDidAddPopoutGroup((event: PopoutGroup) => { event.window.focus(); }); -// Fires when a popout group is removed — the user closed its window or it was +// Fires when a popout group is removed: the user closed its window or it was // docked back programmatically. Not fired during component disposal. api.onDidRemovePopoutGroup((event: PopoutGroup) => { // event.id, event.group diff --git a/packages/docs/docs/core/groups/add.mdx b/packages/docs/docs/core/groups/add.mdx index f50edc43b..f78fe3a87 100644 --- a/packages/docs/docs/core/groups/add.mdx +++ b/packages/docs/docs/core/groups/add.mdx @@ -91,6 +91,6 @@ api.fromJSON(layout, { reuseExistingPanels: true }); ## See also -- [Core concepts](/docs/core/overview) — how panels and groups fit together -- [Move group](/docs/core/groups/move) — reposition a group once it exists -- [Group controls](/docs/core/groups/controls) — add custom actions to a group header +- [Core concepts](/docs/core/overview): how panels and groups fit together +- [Move group](/docs/core/groups/move): reposition a group once it exists +- [Group controls](/docs/core/groups/controls): add custom actions to a group header diff --git a/packages/docs/docs/core/groups/autoEdgeGroups.mdx b/packages/docs/docs/core/groups/autoEdgeGroups.mdx index 9994d42c3..3cd5e9e96 100644 --- a/packages/docs/docs/core/groups/autoEdgeGroups.mdx +++ b/packages/docs/docs/core/groups/autoEdgeGroups.mdx @@ -48,7 +48,7 @@ const api = createDockview(element, { ``` -To enable dock-to-edge on only some edges, name them individually — `true`/`false` (or an omitted edge) toggles each of `top`, `bottom`, `left`, `right`: +To enable dock-to-edge on only some edges, name them individually; `true`/`false` (or an omitted edge) toggles each of `top`, `bottom`, `left`, `right`: ```ts const api = createDockview(element, { @@ -58,7 +58,7 @@ const api = createDockview(element, { }); ``` -Dock-to-edge is **off by default** — leaving `dockToEdgeGroups` unset (or `false`) keeps the standard behaviour, where an edge must be created explicitly with `addEdgeGroup` and an emptied edge collapses to a strip rather than disappearing. +Dock-to-edge is **off by default**; leaving `dockToEdgeGroups` unset (or `false`) keeps the standard behaviour, where an edge must be created explicitly with `addEdgeGroup` and an emptied edge collapses to a strip rather than disappearing. @@ -67,13 +67,13 @@ Dock-to-edge is **off by default** — leaving `dockToEdgeGroups` unset (or `fal While dragging a panel toward the layout edge there are two drop zones: - The **outer band**, hugging the true edge (marked by a coloured indicator line), docks the panel as a dedicated **edge group**. -- Just **inside** it, the panel splits the primary grid as usual — the standard `dndEdges` behaviour. +- Just **inside** it, the panel splits the primary grid as usual, the standard `dndEdges` behaviour. A newly revealed edge group is created **collapsed**: the drop adds a tab to its strip rather than popping the group open. Dropping onto an edge that already exists simply adds the panel to its tabs and leaves the group's collapsed/expanded state untouched. Combine with [auto-hide edge groups](/docs/core/groups/autoHideEdgeGroups) so a revealed edge peeks open on click. ## Zero footprint when empty -An edge group created by a drag reveal is flagged to **tear down to zero footprint** once its last panel leaves — the edge occupies no space and shows no strip until something is dragged back to it. This is the difference from a normal edge group, which collapses to a persistent strip when emptied. +An edge group created by a drag reveal is flagged to **tear down to zero footprint** once its last panel leaves: the edge occupies no space and shows no strip until something is dragged back to it. This is the difference from a normal edge group, which collapses to a persistent strip when emptied. Revealed edges still serialize and restore like any other edge group; a transient empty edge (mid-teardown) is never persisted. @@ -81,14 +81,14 @@ Revealed edges still serialize and restore like any other edge group; a transien If the [drop guide](/docs/core/dnd/dropGuide) compass is also enabled, the two compose rather than conflict. A drop can target **either**: -- the **grid layout edge** — the compass's outer ring, or -- an **edge group** — the true outer edge band (drag-reveal). +- the **grid layout edge**, the compass's outer ring, or +- an **edge group**, the true outer edge band (drag-reveal). The distinction is by pointer depth: the compass's outer ring sits well inside the edge band, and the edge-group indicator takes over at the very edge. ## Revealing programmatically -Reveal (create-or-fill) an edge group and move a dragged item into it — the primitive the drag affordance is built on: +Reveal (create-or-fill) an edge group and move a dragged item into it, the primitive the drag affordance is built on: @@ -105,6 +105,6 @@ Dock-to-edge groups require both the edge-group and drag-and-drop overlay functi ## See also -- [Edge groups](/docs/core/groups/edgeGroups) — creating, sizing, collapsing, and serializing edge groups -- [Auto-hide edge groups](/docs/core/groups/autoHideEdgeGroups) — peek a collapsed edge group open on click -- [Drag and drop](/docs/core/dnd/overview) — the `dndEdges` layout-edge drop zones +- [Edge groups](/docs/core/groups/edgeGroups): creating, sizing, collapsing, and serializing edge groups +- [Auto-hide edge groups](/docs/core/groups/autoHideEdgeGroups): peek a collapsed edge group open on click +- [Drag and drop](/docs/core/dnd/overview): the `dndEdges` layout-edge drop zones diff --git a/packages/docs/docs/core/groups/autoHideEdgeGroups.mdx b/packages/docs/docs/core/groups/autoHideEdgeGroups.mdx index 12449d599..5d85f7815 100644 --- a/packages/docs/docs/core/groups/autoHideEdgeGroups.mdx +++ b/packages/docs/docs/core/groups/autoHideEdgeGroups.mdx @@ -17,7 +17,7 @@ For the basics of creating, sizing, collapsing, and serializing edge groups, see The `autoHideEdgeGroups` option sets the per-edge default, but auto-hide is also resolved **per group**: pass `autoHide` to `addEdgeGroup`, or call `api.setAutoHide` at runtime, to opt a single edge group in or out. This lets a static always-docked edge group and an auto-hiding one co-exist in the same layout. -Enable it with the `autoHideEdgeGroups` option — pass `true` for all four edges, or an object to enable specific edges: +Enable it with the `autoHideEdgeGroups` option: pass `true` for all four edges, or an object to enable specific edges: ```tsx @@ -50,7 +50,7 @@ const api = createDockview(element, { ``` -To enable auto-hide on only some edges, name them individually — `true`/`false` (or an omitted edge) toggles each of `top`, `bottom`, `left`, `right`: +To enable auto-hide on only some edges, name them individually; `true`/`false` (or an omitted edge) toggles each of `top`, `bottom`, `left`, `right`: ```ts const api = createDockview(element, { @@ -60,15 +60,15 @@ const api = createDockview(element, { }); ``` -Auto-hide is **off by default** — leaving `autoHideEdgeGroups` unset (or `false`) keeps the plain collapse/expand behaviour, with no peek overlay. +Auto-hide is **off by default**; leaving `autoHideEdgeGroups` unset (or `false`) keeps the plain collapse/expand behaviour, with no peek overlay. ## The click-to-peek model -Auto-hide is entirely **click-driven** — there is no hover interaction. Once an edge group is auto-hidden (collapsed) it renders a strip of its tabs along the edge, and: +Auto-hide is entirely **click-driven**; there is no hover interaction. Once an edge group is auto-hidden (collapsed) it renders a strip of its tabs along the edge, and: -- **Click a tab** → that tab's panel **peeks** out as an overlay anchored to the strip's inner edge. The group stays logically collapsed, so **the grid is not reflowed** — the panel simply floats over your content. The overlay carries a **title bar** (the active panel's title on the left; a **pin** and a **close** button on the right). +- **Click a tab** → that tab's panel **peeks** out as an overlay anchored to the strip's inner edge. The group stays logically collapsed, so **the grid is not reflowed**; the panel simply floats over your content. The overlay carries a **title bar** (the active panel's title on the left; a **pin** and a **close** button on the right). - **Click the same tab again**, **click anywhere outside** the strip and peek, or press **Escape** → the peek hides. Clicking empty space inside the strip does nothing. - **Click a different tab** while peeking → the peek switches to that panel and retitles. - **Pin** → the group **docks** (expands) permanently. A docked group renders as a tool window: the title bar sits on top and the tab strip moves to the bottom. Pinning again auto-hides it back to the strip. @@ -92,7 +92,7 @@ const api = createDockview(element, { }); ``` -- `animate` — slide the peek overlay in. Default `true`; ignored when the OS requests reduced motion. +- `animate`: slide the peek overlay in. Default `true`; ignored when the OS requests reduced motion. ## API @@ -144,5 +144,5 @@ The peek overlay shares the same stacking context as floating and popout groups, ## See also -- [Edge groups](/docs/core/groups/edgeGroups) — creating, sizing, collapsing, and serializing edge groups -- [Group controls](/docs/core/groups/controls) — render controls specific to edge groups via the `location` prop +- [Edge groups](/docs/core/groups/edgeGroups): creating, sizing, collapsing, and serializing edge groups +- [Group controls](/docs/core/groups/controls): render controls specific to edge groups via the `location` prop diff --git a/packages/docs/docs/core/groups/constraints.mdx b/packages/docs/docs/core/groups/constraints.mdx index 2a7fbe573..8cd86542b 100644 --- a/packages/docs/docs/core/groups/constraints.mdx +++ b/packages/docs/docs/core/groups/constraints.mdx @@ -20,5 +20,5 @@ Constraints come with several caveats. They are not serialized with layouts and ## See also -- [Resizing](/docs/core/panels/resizing) — set a panel or group's exact height and width programmatically -- [Sizing and layout](/docs/core/sizing) — control initial and proportional sizing +- [Resizing](/docs/core/panels/resizing): set a panel or group's exact height and width programmatically +- [Sizing and layout](/docs/core/sizing): control initial and proportional sizing diff --git a/packages/docs/docs/core/groups/controls.mdx b/packages/docs/docs/core/groups/controls.mdx index 4994268f4..ed945a8f3 100644 --- a/packages/docs/docs/core/groups/controls.mdx +++ b/packages/docs/docs/core/groups/controls.mdx @@ -5,7 +5,7 @@ description: How to add custom actions and controls to the Dockview group header import { DocRef } from '@site/src/components/ui/reference/docRef'; -Header action components let you render your own controls — buttons, menus, or status indicators — into the left, right, and prefix regions of a group's header bar. Use them to add per-group actions such as split, close, or a context menu. +Header action components let you render your own controls (buttons, menus, or status indicators) into the left, right, and prefix regions of a group's header bar. Use them to add per-group actions such as split, close, or a context menu. @@ -181,5 +181,5 @@ panel.group.header.hidden = true; ## See also -- [Managing groups](/docs/core/groups/add) — create, remove, and clear groups -- [Edge groups](/docs/core/groups/edgeGroups) — use the `location` prop to show controls specific to edge groups +- [Managing groups](/docs/core/groups/add): create, remove, and clear groups +- [Edge groups](/docs/core/groups/edgeGroups): use the `location` prop to show controls specific to edge groups diff --git a/packages/docs/docs/core/groups/edgeGroups.mdx b/packages/docs/docs/core/groups/edgeGroups.mdx index 45b7db022..240ed5477 100644 --- a/packages/docs/docs/core/groups/edgeGroups.mdx +++ b/packages/docs/docs/core/groups/edgeGroups.mdx @@ -1,13 +1,13 @@ --- title: Edge groups -description: How to create and manage edge groups in Dockview — groups that are pinned to the edges of the layout, like a VS Code sidebar or panel. +description: How to create and manage edge groups in Dockview: groups that are pinned to the edges of the layout, like a VS Code sidebar or panel. --- 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`. +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`. @@ -135,11 +135,11 @@ Themes that set a custom `edgeGroupCollapsedSize`: When an edge group loses all of its panels it is automatically collapsed. Adding a new panel to it will expand it again. ::: -Collapsed edge groups can auto-hide and peek back on demand — see [Auto-hide Edge Groups](/docs/core/groups/autoHideEdgeGroups). +Collapsed edge groups can auto-hide and peek back on demand. See [Auto-hide Edge Groups](/docs/core/groups/autoHideEdgeGroups). ## Dock to edge groups -With the `dockToEdgeGroups` option an edge takes up **zero space** when empty and is revealed by dragging a panel to it, like a VS Code sidebar — see [Dock to edge groups](/docs/core/groups/autoEdgeGroups). +With the `dockToEdgeGroups` option an edge takes up **zero space** when empty and is revealed by dragging a panel to it, like a VS Code sidebar. See [Dock to edge groups](/docs/core/groups/autoEdgeGroups). ## Auto-hide co-existence @@ -254,5 +254,5 @@ api.fromJSON(state); // auto-creates and restores edge groups ## See also -- [Auto-hide edge groups](/docs/core/groups/autoHideEdgeGroups) — turn a collapsed edge group into a pinnable tool window -- [Group controls](/docs/core/groups/controls) — render controls specific to edge groups via the `location` prop +- [Auto-hide edge groups](/docs/core/groups/autoHideEdgeGroups): turn a collapsed edge group into a pinnable tool window +- [Group controls](/docs/core/groups/controls): render controls specific to edge groups via the `location` prop diff --git a/packages/docs/docs/core/groups/floatingGroups.mdx b/packages/docs/docs/core/groups/floatingGroups.mdx index adfc1e12a..6a26da546 100644 --- a/packages/docs/docs/core/groups/floatingGroups.mdx +++ b/packages/docs/docs/core/groups/floatingGroups.mdx @@ -1,12 +1,12 @@ --- title: Floating groups -description: How to create and manage floating groups in Dockview — groups that float freely over the layout. +description: How to create and manage floating groups in Dockview: groups that float freely over the layout. --- import useBaseUrl from '@docusaurus/useBaseUrl'; import { DocRef } from '@site/src/components/ui/reference/docRef'; -Floating groups sit above the grid in a free-floating, draggable container instead of being docked into it — useful for tool palettes, inspectors, or any panel you want to keep visible over the rest of the layout. +Floating groups sit above the grid in a free-floating, draggable container instead of being docked into it, useful for tool palettes, inspectors, or any panel you want to keep visible over the rest of the layout. :::info Floating groups **cannot** be maximized. Calling maximize function on groups in these states will have no effect. @@ -60,7 +60,7 @@ You can control the bounding box of floating groups through the optional `floati `floatingGroupDragHandle` selects which element moves a floating group when dragged: - `'titlebar'` (default): a dedicated, blank drag-handle bar is rendered above the group's tab bar. Dragging it moves the floating window; shift+drag (mouse) or long-press (touch) redocks the group back into the grid. Style it with the `--dv-floating-titlebar-*` theme variables. -- `'tabbar'`: the legacy behaviour — the empty space in the tab bar (the "void container") doubles as the move handle, with no dedicated bar rendered. +- `'tabbar'`: the legacy behaviour, where the empty space in the tab bar (the "void container") doubles as the move handle, with no dedicated bar rendered. ```ts const api = createDockview(element, { @@ -70,7 +70,7 @@ const api = createDockview(element, { ### Customising drag behaviour -`transformFloatingGroupDrag` lets you adjust a floating group's position while it is being dragged — for snapping to a grid, aligning to other floating groups, or constraining a group to a region. It runs on every pointer-move frame with the proposed top-left (before Dockview's container clamp) and returns an adjusted top-left, or nothing to leave it unchanged. It affects moving only — resizing is unaffected. +`transformFloatingGroupDrag` lets you adjust a floating group's position while it is being dragged, for snapping to a grid, aligning to other floating groups, or constraining a group to a region. It runs on every pointer-move frame with the proposed top-left (before Dockview's container clamp) and returns an adjusted top-left, or nothing to leave it unchanged. It affects moving only; resizing is unaffected. ```ts const api = createDockview(element, { @@ -142,5 +142,5 @@ You can check whether a group is floating via the `group.api.location` property. ## See also -- [Popout windows](/docs/core/groups/popoutGroups) — move a group into a separate browser window -- [Maximized groups](/docs/core/groups/maximizedGroups) — expand a group to fill the viewport +- [Popout windows](/docs/core/groups/popoutGroups): move a group into a separate browser window +- [Maximized groups](/docs/core/groups/maximizedGroups): expand a group to fill the viewport diff --git a/packages/docs/docs/core/groups/maximizedGroups.mdx b/packages/docs/docs/core/groups/maximizedGroups.mdx index e2ee71c95..3a998a686 100644 --- a/packages/docs/docs/core/groups/maximizedGroups.mdx +++ b/packages/docs/docs/core/groups/maximizedGroups.mdx @@ -5,7 +5,7 @@ description: How to maximize a group to fill the Dockview viewport and restore i import { DocRef } from '@site/src/components/ui/reference/docRef'; -Maximizing a group temporarily expands it to fill the entire Dockview viewport, hiding the other groups until you restore it — handy for focusing on a single panel without changing the underlying layout. +Maximizing a group temporarily expands it to fill the entire Dockview viewport, hiding the other groups until you restore it, handy for focusing on a single panel without changing the underlying layout. @@ -64,5 +64,5 @@ The methods exist on the panel `api` object for convenience. ## See also -- [Floating groups](/docs/core/groups/floatingGroups) — float a group above the grid -- [Popout windows](/docs/core/groups/popoutGroups) — move a group into a separate browser window +- [Floating groups](/docs/core/groups/floatingGroups): float a group above the grid +- [Popout windows](/docs/core/groups/popoutGroups): move a group into a separate browser window diff --git a/packages/docs/docs/core/groups/move.mdx b/packages/docs/docs/core/groups/move.mdx index 80b139c19..d1c1e55c3 100644 --- a/packages/docs/docs/core/groups/move.mdx +++ b/packages/docs/docs/core/groups/move.mdx @@ -6,7 +6,7 @@ description: How to move a group to a different position in the Dockview layout import { DocRef } from '@site/src/components/ui/reference/docRef'; -Moving a group repositions it within the layout — docking it against another group or panel, or against an absolute edge — through the [Group API](/docs/api/dockview/groupApi)'s `moveTo` method. +Moving a group repositions it within the layout (docking it against another group or panel, or against an absolute edge) through the [Group API](/docs/api/dockview/groupApi)'s `moveTo` method. ## Methods @@ -22,6 +22,6 @@ panel.group.api.moveTo({ group, position, index }); ## See also -- [Managing groups](/docs/core/groups/add) — create, remove, and clear groups -- [Group controls](/docs/core/groups/controls) — add custom actions to a group header -- [Locking](/docs/core/locked) — block drop interactions on a group or the whole layout +- [Managing groups](/docs/core/groups/add): create, remove, and clear groups +- [Group controls](/docs/core/groups/controls): add custom actions to a group header +- [Locking](/docs/core/locked): block drop interactions on a group or the whole layout diff --git a/packages/docs/docs/core/groups/popoutGroups.mdx b/packages/docs/docs/core/groups/popoutGroups.mdx index 503a383e4..1df88ee44 100644 --- a/packages/docs/docs/core/groups/popoutGroups.mdx +++ b/packages/docs/docs/core/groups/popoutGroups.mdx @@ -5,7 +5,7 @@ description: How to pop out a Dockview group into a separate browser window and import { DocRef } from '@site/src/components/ui/reference/docRef'; -Popout groups open a group in a separate native browser window while it stays part of the same Dockview layout — useful for spreading panels across multiple monitors. The group can be docked back into the grid at any time. +Popout groups open a group in a separate native browser window while it stays part of the same Dockview layout, useful for spreading panels across multiple monitors. The group can be docked back into the grid at any time. :::info Popout groups **cannot** be maximized. Calling maximize function on groups in these states will have no effect. @@ -20,7 +20,7 @@ as needed. The popout lifecycle is observable: `onDidAddPopoutGroup` / `onDidRemovePopoutGroup` fire as windows open and close (or dock back), and -`api.getPopouts()` enumerates the open popout windows — see +`api.getPopouts()` enumerates the open popout windows. See [Events](/docs/core/events#popout-window). Popout windows require your website to have a blank `.html` page that can be used, by default this is set to `/popout.html` but @@ -42,7 +42,7 @@ api.addPopoutGroup( :::warning Security: same-origin only -`popoutUrl` must point to a same-origin `http(s)` location. Dockview rejects `javascript:`, `data:`, `blob:`, and cross-origin URLs to prevent a malicious value — for example, from a layout JSON loaded from an untrusted source — from executing script in a context the browser still associates with your application via `window.opener`. The guard runs automatically when the popout is opened, including on layouts restored via `fromJSON()`. +`popoutUrl` must point to a same-origin `http(s)` location. Dockview rejects `javascript:`, `data:`, `blob:`, and cross-origin URLs to prevent a malicious value (for example, from a layout JSON loaded from an untrusted source) from executing script in a context the browser still associates with your application via `window.opener`. The guard runs automatically when the popout is opened, including on layouts restored via `fromJSON()`. ::: From within a panel you may say @@ -72,11 +72,11 @@ choose a new location. ## Overlays inside popout windows -Floating overlays — including drag-target indicators, the tab context menu, and tab group chip popovers (color picker, rename) — render inside the DOM of the window that hosts them. When a group lives in a popout window, those overlays render in the popout window's document, not the parent. This means: +Floating overlays, including drag-target indicators, the tab context menu, and tab group chip popovers (color picker, rename), render inside the DOM of the window that hosts them. When a group lives in a popout window, those overlays render in the popout window's document, not the parent. This means: - Custom chip components and context menu components are mounted in the popout window's DOM tree. - CSS that you load into the main page is automatically copied into popout windows; if you ship custom styles outside the standard import pipeline (for example, lazily injected stylesheets), make sure they are also available in the popout window. -- Event handlers and portals inside custom components should not assume the document is the main window — use the element's `ownerDocument` when you need a reference. +- Event handlers and portals inside custom components should not assume the document is the main window; use the element's `ownerDocument` when you need a reference. ## Popout window events @@ -101,6 +101,6 @@ api.onDidOpenPopoutWindowFail(() => { ## See also -- [Floating groups](/docs/core/groups/floatingGroups) — float a group above the grid without a separate window -- [Events](/docs/core/events#popout-window) — observe the popout window lifecycle -- [Security](/docs/core/security) — same-origin requirements and CSP for popout windows +- [Floating groups](/docs/core/groups/floatingGroups): float a group above the grid without a separate window +- [Events](/docs/core/events#popout-window): observe the popout window lifecycle +- [Security](/docs/core/security): same-origin requirements and CSP for popout windows diff --git a/packages/docs/docs/core/locked.mdx b/packages/docs/docs/core/locked.mdx index 1f05ebaaf..6a4a5aee3 100644 --- a/packages/docs/docs/core/locked.mdx +++ b/packages/docs/docs/core/locked.mdx @@ -34,6 +34,6 @@ Use `true` to keep the drop zones at the top, right, bottom and left of the grou ## See also -- [Disable drag and drop](/docs/core/dnd/disable) — turn off drag and drop per panel, group, or the whole layout -- [Managing groups](/docs/core/groups/add) — create, remove, and clear groups -- [Move group](/docs/core/groups/move) — reposition a group within the layout +- [Disable drag and drop](/docs/core/dnd/disable): turn off drag and drop per panel, group, or the whole layout +- [Managing groups](/docs/core/groups/add): create, remove, and clear groups +- [Move group](/docs/core/groups/move): reposition a group within the layout diff --git a/packages/docs/docs/core/nested.mdx b/packages/docs/docs/core/nested.mdx index f9298a952..86c5b8436 100644 --- a/packages/docs/docs/core/nested.mdx +++ b/packages/docs/docs/core/nested.mdx @@ -13,5 +13,5 @@ If you wish to interact with the drop event from one Dockview instance in anothe ## See also -- [Core concepts](/docs/core/overview) — how panels, groups, and the API fit together -- [Events](/docs/core/events) — `onUnhandledDragOver` and `onDidDrop` for bridging drops between instances +- [Core concepts](/docs/core/overview): how panels, groups, and the API fit together +- [Events](/docs/core/events): `onUnhandledDragOver` and `onDidDrop` for bridging drops between instances diff --git a/packages/docs/docs/core/overview.mdx b/packages/docs/docs/core/overview.mdx index 36a6372ac..f9d939910 100644 --- a/packages/docs/docs/core/overview.mdx +++ b/packages/docs/docs/core/overview.mdx @@ -1,7 +1,7 @@ --- title: Core concepts sidebar_position: 0 -description: Core concepts of Dockview — panels, groups, the API pattern, and how they fit together. +description: Core concepts of Dockview: panels, groups, the API pattern, and how they fit together. --- Dockview organises content into **panels** and **groups** arranged in a resizable grid. Understanding these primitives and the API pattern is all you need to get started. diff --git a/packages/docs/docs/core/panels/add.mdx b/packages/docs/docs/core/panels/add.mdx index 248c6e4ea..00bf32c8b 100644 --- a/packages/docs/docs/core/panels/add.mdx +++ b/packages/docs/docs/core/panels/add.mdx @@ -230,7 +230,7 @@ api.addPanel({ ## See also -- [Registering panels](/docs/core/panels/register) — register the components that `addPanel` instantiates by name. -- [Move panel](/docs/core/panels/move) — reposition a panel after it has been added. -- [Remove panel](/docs/core/panels/remove) — remove a panel from the layout. -- [Panel API](/docs/api/dockview/panelApi) — control an individual panel once it exists. +- [Registering panels](/docs/core/panels/register): register the components that `addPanel` instantiates by name. +- [Move panel](/docs/core/panels/move): reposition a panel after it has been added. +- [Remove panel](/docs/core/panels/remove): remove a panel from the layout. +- [Panel API](/docs/api/dockview/panelApi): control an individual panel once it exists. diff --git a/packages/docs/docs/core/panels/headerPosition.mdx b/packages/docs/docs/core/panels/headerPosition.mdx index a83f10834..e90e1a200 100644 --- a/packages/docs/docs/core/panels/headerPosition.mdx +++ b/packages/docs/docs/core/panels/headerPosition.mdx @@ -81,6 +81,6 @@ const onReady = (event: DockviewReadyEvent) => { ## See also -- [Tabs](/docs/core/panels/tabs) — customise how the tabs in the header are rendered. -- [Tab overflow](/docs/core/panels/tabOverflow) — how surplus tabs are handled when the header runs out of room. -- [Multi-row tabs](/docs/core/panels/multiRowTabs) — wrapping tabs, which applies to horizontal headers only. +- [Tabs](/docs/core/panels/tabs): customise how the tabs in the header are rendered. +- [Tab overflow](/docs/core/panels/tabOverflow): how surplus tabs are handled when the header runs out of room. +- [Multi-row tabs](/docs/core/panels/multiRowTabs): wrapping tabs, which applies to horizontal headers only. diff --git a/packages/docs/docs/core/panels/move.mdx b/packages/docs/docs/core/panels/move.mdx index 7bfa355ac..9bbe2be42 100644 --- a/packages/docs/docs/core/panels/move.mdx +++ b/packages/docs/docs/core/panels/move.mdx @@ -29,6 +29,6 @@ group.api.moveTo({ group, position }); ## See also -- [Move group](/docs/core/groups/move) — move a whole group rather than a single panel. -- [Adding panels](/docs/core/panels/add) — position a panel at creation time with the same `direction` semantics. -- [Panel API](/docs/api/dockview/panelApi) — the panel API surface that exposes `moveTo`. +- [Move group](/docs/core/groups/move): move a whole group rather than a single panel. +- [Adding panels](/docs/core/panels/add): position a panel at creation time with the same `direction` semantics. +- [Panel API](/docs/api/dockview/panelApi): the panel API surface that exposes `moveTo`. diff --git a/packages/docs/docs/core/panels/multiRowTabs.mdx b/packages/docs/docs/core/panels/multiRowTabs.mdx index f23b670f5..51821626b 100644 --- a/packages/docs/docs/core/panels/multiRowTabs.mdx +++ b/packages/docs/docs/core/panels/multiRowTabs.mdx @@ -20,7 +20,7 @@ is covered in [Tab Overflow](/docs/core/panels/tabOverflow). ## Multi-row (wrapping) tabs Set `overflow.mode: 'wrap'` and, instead of clipping the surplus tabs into the -dropdown, the tab strip wraps onto additional rows and the header grows to fit — a +dropdown, the tab strip wraps onto additional rows and the header grows to fit, a JetBrains-style layout where every tab stays visible at once. As tabs are added or removed, the header grows and shrinks by whole rows, and the panel content area resizes to match. @@ -79,7 +79,7 @@ api.updateOptions({ overflow: { mode: 'wrap' } }); `overflow.mode: 'wrap'` is provided by the multi-row tabs module, which is included in the default `dockview` bundle. If you assemble your own set of modules and omit it, `mode: 'wrap'` is ignored and the standard single-row strip with the dropdown is -used instead — no error, no regression. +used instead; no error, no regression. ::: ### `maxRows` @@ -114,13 +114,13 @@ switcher. :::warning These fields are reserved for a not-yet-shipped advanced overflow module and currently -have **no effect**. They are documented here only as forward-looking API surface — +have **no effect**. They are documented here only as forward-looking API surface; setting them today does nothing. Rely on `mode` and (once implemented) `maxRows`. ::: ## See also -- [Tab overflow](/docs/core/panels/tabOverflow) — the default single-row dropdown this mode replaces. -- [Pinned tabs](/docs/core/panels/pinnedTabs) — another way to keep important tabs visible. -- [Tab header position](/docs/core/panels/headerPosition) — wrapping applies to horizontal headers only. +- [Tab overflow](/docs/core/panels/tabOverflow): the default single-row dropdown this mode replaces. +- [Pinned tabs](/docs/core/panels/pinnedTabs): another way to keep important tabs visible. +- [Tab header position](/docs/core/panels/headerPosition): wrapping applies to horizontal headers only. ``` diff --git a/packages/docs/docs/core/panels/pinnedTabs.mdx b/packages/docs/docs/core/panels/pinnedTabs.mdx index 230f6d8a7..f6ebe20cf 100644 --- a/packages/docs/docs/core/panels/pinnedTabs.mdx +++ b/packages/docs/docs/core/panels/pinnedTabs.mdx @@ -1,6 +1,6 @@ --- title: Pinned tabs -description: Pin tabs so they render first, never overflow, and resist reordering — modelled on VS Code and Chrome. +description: Pin tabs so they render first, never overflow, and resist reordering, modelled on VS Code and Chrome. sidebar_position: 10 enterprise: true sidebar_custom_props: @@ -11,9 +11,9 @@ import { DocRef } from '@site/src/components/ui/reference/docRef'; Pinned tabs let you mark the tabs that matter so they stay put. Modelled on VS Code and Chrome, a pinned tab: -- **renders first** — pinned tabs always sort ahead of unpinned tabs in their group; -- **never overflows** — pinned tabs are excluded from the overflow dropdown, so they stay visible even as the strip fills up; -- **resists reordering** — you cannot drag an unpinned tab to the left of a pinned one (the pin boundary is enforced). +- **renders first**: pinned tabs always sort ahead of unpinned tabs in their group; +- **never overflows**: pinned tabs are excluded from the overflow dropdown, so they stay visible even as the strip fills up; +- **resists reordering**: you cannot drag an unpinned tab to the left of a pinned one (the pin boundary is enforced). The pinned order is stable: pinning appends a tab to the end of the pinned block, and unpinning returns it to the front of the unpinned block. @@ -49,11 +49,11 @@ const api = createDockview(element, { -- **`enabled`** — the master switch. Leave it unset (or `false`) to keep pinning dormant; the tab strip then behaves identically to the default. -- **`mode`** — `'inline'` (the default) keeps pinned tabs first within the existing tab strip. `'separate-row'` renders them on their own VS-Code-style row above the main strip; the row collapses when no tab in the group is pinned. -- **`compact`** — render pinned tabs icon-only (title and close button hidden), like VS Code and Chrome. Defaults to `false` because Dockview's default tab has no favicon, so pinned tabs stay labelled (with a pin glyph) unless you opt in. Best paired with a custom tab renderer that shows an icon. -- **`togglePinOnCrossBoundaryDrag`** — when `true`, dragging a tab across the pin boundary toggles its pinned state (VS-Code behaviour). Defaults to `false`: dragging across the boundary is clamped back, matching Chrome, where pinning is an explicit action. -- **`contextMenuItem`** — add a built-in "Pin"/"Unpin" item to the tab context menu. Defaults to `true`; requires the context menu to be available. +- **`enabled`**: the master switch. Leave it unset (or `false`) to keep pinning dormant; the tab strip then behaves identically to the default. +- **`mode`**: `'inline'` (the default) keeps pinned tabs first within the existing tab strip. `'separate-row'` renders them on their own VS-Code-style row above the main strip; the row collapses when no tab in the group is pinned. +- **`compact`**: render pinned tabs icon-only (title and close button hidden), like VS Code and Chrome. Defaults to `false` because Dockview's default tab has no favicon, so pinned tabs stay labelled (with a pin glyph) unless you opt in. Best paired with a custom tab renderer that shows an icon. +- **`togglePinOnCrossBoundaryDrag`**: when `true`, dragging a tab across the pin boundary toggles its pinned state (VS-Code behaviour). Defaults to `false`: dragging across the boundary is clamped back, matching Chrome, where pinning is an explicit action. +- **`contextMenuItem`**: add a built-in "Pin"/"Unpin" item to the tab context menu. Defaults to `true`; requires the context menu to be available. :::info `mode: 'separate-row'` renders pinned tabs in a dedicated row. In `'inline'` mode pinned and unpinned tabs share the single strip, with pinned tabs sorted to the front. @@ -127,11 +127,11 @@ api.fromJSON(state); // pinned tabs are restored, in their pinned order ``` :::info -Layouts saved before pinning was enabled — or restored into a component with `pinnedTabs` disabled — load as a normal, unpinned strip. The `pinned` key is simply ignored when pinning is off. +Layouts saved before pinning was enabled (or restored into a component with `pinnedTabs` disabled) load as a normal, unpinned strip. The `pinned` key is simply ignored when pinning is off. ::: ## See also -- [Tabs](/docs/core/panels/tabs) — custom tab renderers and the tab context menu that hosts the `'pin'` item. -- [Tab overflow](/docs/core/panels/tabOverflow) — the overflow dropdown that pinned tabs are excluded from. -- [Multi-row tabs](/docs/core/panels/multiRowTabs) — an alternative way to keep every tab visible as the strip fills up. +- [Tabs](/docs/core/panels/tabs): custom tab renderers and the tab context menu that hosts the `'pin'` item. +- [Tab overflow](/docs/core/panels/tabOverflow): the overflow dropdown that pinned tabs are excluded from. +- [Multi-row tabs](/docs/core/panels/multiRowTabs): an alternative way to keep every tab visible as the strip fills up. diff --git a/packages/docs/docs/core/panels/register.mdx b/packages/docs/docs/core/panels/register.mdx index 8883005d6..55a0eff67 100644 --- a/packages/docs/docs/core/panels/register.mdx +++ b/packages/docs/docs/core/panels/register.mdx @@ -85,7 +85,7 @@ const api = createDockview(parentElement, { Pass your panel components directly to `` via the `components` -prop. This is the recommended pattern and works with `