# Blazor Dock Manager

URL: https://flexcoreui.com/demo/dock-manager  
Section: Components  
Controls: DockManagerControl, DockPanel, DockLayoutState  
Keywords: dock manager, docking panels, dockable layout, IDE layout, floating panes

IDE-style docking for Blazor apps: panes users split, float, unpin and close, with the whole arrangement saved as one JSON document.

## Documentation

### Params

| Name | Type | Default | Description |
|---|---|---|---|
| Panels | IReadOnlyList<DockPanel> | Array.Empty<DockPanel>() | The panes: unique, non-empty keys, a title, the content and the two permissions. When State is null, panes added later join the first group and removed ones leave the layout; when State is set, pass a State that places every current key, or the control throws. |
| State | DockLayoutState? | null | The starting arrangement. A new instance is validated against the keys and copied; null gives one group with every pane, the first active. |
| Height | string | "500px" | Height of the manager. |

### Panel

| Name | Type | Default | Description |
|---|---|---|---|
| Key | string |  | Unique, non-empty name of the pane; the methods and the saved layout refer to it. |
| Title | string |  | Text of the pane's tab, and of its window when floating. |
| Content | RenderFragment |  | What the pane shows, as a RenderFragment: a Razor template, or a builder such as b => b.AddMarkupContent(0, "…") as in the examples. |
| Closable | bool | true | False hides Close, drops the close icon and Escape from its floating window, and makes CloseAsync do nothing. |
| Floatable | bool | true | False hides Float and makes FloatAsync do nothing. |

### Events

| Name | Type | Description |
|---|---|---|
| StateChanged | DockLayoutState | After every change: tab click, split resize, dock, float, unpin, close, a floating pane moved or resized, or a restore. Carries a copy of the layout. |

### Methods

| Name | Type | Description |
|---|---|---|
| SaveLayout() | string | The current layout as JSON. |
| RestoreLayoutAsync(string json) | Task | Applies a saved layout after validating it against the current panes; ignored while disabled. |
| DockAsync(string key, string targetNodeId, DockPosition position = DockPosition.Tab) | Task | Moves a pane into a group, as a tab or by splitting it. The target must be a group, not a split; the pane may come from anywhere, including floating, unpinned or closed. |
| FloatAsync(string key) | Task | Floats a pane; ignored when it is not floatable. |
| UnpinAsync(string key) | Task | Moves a pane to the unpinned strip. |
| CloseAsync(string key) | Task | Closes a pane; ignored when it is not closable. |

### State

| Name | Type | Default | Description |
|---|---|---|---|
| Root | DockNode | new() | The tree of groups and splits. |
| Floating | List<DockFloatingPane> | [] | Panes shown as windows. |
| AutoHidden | List<string> | [] | Keys of the unpinned panes. |
| Closed | List<string> | [] | Keys of the closed panes. |

### State methods

| Name | Type | Description |
|---|---|---|
| Clone() | DockLayoutState | A deep copy, made through JSON. |
| ToJson() | string | Serializes the layout. |
| FromJson(string json) | DockLayoutState | Static; parses a layout and throws for null. |
| Nodes() | IEnumerable<DockNode> | Every node of the tree, root first. |
| Validate(IEnumerable<string> keys) | void | Throws unless the layout places exactly these keys once each and the tree is well formed; see the rules below. |

### Node

| Name | Type | Default | Description |
|---|---|---|---|
| Id | string | Guid.NewGuid().ToString("N") | Identifier used as the dock target. |
| Panels | List<string> | [] | Keys of the panes in this group, in tab order. Empty for a split. |
| ActivePanel | string? | null | The selected tab; must be one of Panels. |
| Children | List<DockNode> | [] | Empty for a group, exactly two for a split. |
| Vertical | bool | true | True puts the two children side by side, false stacks them. |
| Ratio | double | 50 | Percentage of the split given to the first child, 5 to 95. |

### Floating

| Name | Type | Default | Description |
|---|---|---|---|
| Panel | string | "" | The pane's key. |
| Width | string | "520px" | Window width. |
| Height | string | "360px" | Window height. |
| Position | DialogPosition | new(0,0) | Window position as DialogPosition(X, Y). |

### Css

| Name | Description |
|---|---|
| fx-dock-manager | The root element. |
| fx-dock-group | A tab group; fx-dock-tabs is its tab strip, fx-dock-actions the action bar of the active pane, fx-dock-targets the drop targets shown while dragging. |
| fx-dock-auto-hidden | The strip of unpinned panes; fx-dock-drawer is the drawer one of them opens. |

## Examples

### Workspace

```razor
@using Fx.ControlKit
@using Fx.ControlKit.Docking

<ButtonControl CssClass="btn-sm" OnClick="() => _json = _dock!.SaveLayout()">Save layout</ButtonControl>
<ButtonControl CssClass="btn-sm" OnClick="() => _dock!.RestoreLayoutAsync(_json!)" Disabled="@(_json is null)">Restore layout</ButtonControl>
<ButtonControl CssClass="btn-sm" OnClick="() => { _state = Workspace(); _summary = Summarize(_state); }">Reset layout</ButtonControl>

<div class="desk">
    <DockManagerControl @ref="_dock" Panels="@_panels" State="@_state" StateChanged="s => _summary = Summarize(s)" Height="460px" />
    <p class="result">@_summary</p>
    @if (_json is not null)
    {
        <details class="json"><summary>Saved layout, @_json.Length characters of JSON</summary><pre>@_json</pre></details>
    }
</div>
```

```csharp
private DockManagerControl? _dock;

private DockLayoutState _state = Workspace();

private string _summary = "No changes yet.";

private string? _json;

private readonly IReadOnlyList<DockPanel> _panels =
[
    new("tickets", "Tickets", b => b.AddMarkupContent(0, "<ul><li>TKT-1042 Router keeps restarting</li><li>TKT-1043 Charged twice in October</li><li>TKT-1044 Cannot reset password</li><li>TKT-1045 Slow connection in the evenings</li></ul>")),
    new("conversation", "Conversation", b => b.AddMarkupContent(0, "<p><strong>TKT-1042 Router keeps restarting</strong></p><p>Customer: the router has restarted every evening since Monday. Agent: please unplug it for 30 seconds and plug it back in. Customer: no change. Can a technician come on Saturday?</p><p>The conversation pane cannot be closed, so its action bar has no Close button.</p>"), Closable: false),
    new("customer", "Customer", b => b.AddMarkupContent(0, "<dl><dt>Name</dt><dd>Albus Door</dd><dt>Channel</dt><dd>Phone</dd><dt>Status</dt><dd>Open, High priority</dd></dl>")),
    new("notes", "Notes", b => b.AddMarkupContent(0, "<p>Prefers a callback in the morning. The router is still under warranty.</p><p>The notes pane cannot float.</p>"), Floatable: false),
];

private static DockLayoutState Workspace() => new()
{
    Root = new()
    {
        Vertical = true, Ratio = 25,
        Children =
        [
            new() { Panels = ["tickets"], ActivePanel = "tickets" },
            new()
            {
                Vertical = true, Ratio = 70,
                Children =
                [
                    new() { Panels = ["conversation", "notes"], ActivePanel = "conversation" },
                    new() { Panels = ["customer"], ActivePanel = "customer" },
                ],
            },
        ],
    },
};

private static string Summarize(DockLayoutState s) =>
    $"Groups: {s.Nodes().Count(n => n.Children.Count == 0)}, floating: {s.Floating.Count}, unpinned: {s.AutoHidden.Count}, closed: {s.Closed.Count}.";
```

### Methods

```razor
@using Fx.ControlKit
@using Fx.ControlKit.Docking

<ButtonControl CssClass="btn-sm" OnClick='() => _tools!.FloatAsync("reply")'>Float Reply</ButtonControl>
<ButtonControl CssClass="btn-sm" OnClick='() => _tools!.UnpinAsync("thread")'>Unpin Conversation</ButtonControl>
<ButtonControl CssClass="btn-sm" OnClick='() => _tools!.CloseAsync("calls")'>Close Call notes</ButtonControl>
<ButtonControl CssClass="btn-sm" OnClick='() => _tools!.CloseAsync("thread")'>Close Conversation</ButtonControl>
<ButtonControl CssClass="btn-sm" OnClick="DockAllAsync">Dock everything back</ButtonControl>

<div class="desk">
    <DockManagerControl @ref="_tools" Panels="@_toolPanels" StateChanged="s => _toolSummary = Summarize(s)" Height="320px" />
    <p class="result">@_toolSummary</p>
</div>
```

```csharp
private DockManagerControl? _tools;

private string _toolSummary = "No changes yet.";

private readonly IReadOnlyList<DockPanel> _toolPanels =
[
    new("reply", "Reply", b => b.AddMarkupContent(0, "<p>To Hermione Ranger on TKT-1043: the duplicate $59 charge is refunded within five business days.</p><p>This pane can float.</p>")),
    new("thread", "Conversation", b => b.AddMarkupContent(0, "<p>Customer: my October bill of $59 was charged to the same card twice on October 3.</p><p>This pane cannot be closed, so Close Conversation is ignored.</p>"), Closable: false),
    new("calls", "Call notes", b => b.AddMarkupContent(0, "<p>The customer called to ask whether the $15 late fee is refunded too.</p><p>This pane can be closed and floated.</p>")),
];

private async Task DockAllAsync()
{
    foreach (var key in new[] { "reply", "thread", "calls" })
    {
        var layout = DockLayoutState.FromJson(_tools!.SaveLayout());
        var group = layout.Nodes().First(n => n.Children.Count == 0).Id;
        await _tools.DockAsync(key, group, DockPosition.Tab);
    }
}

private static string Summarize(DockLayoutState s) =>
    $"Groups: {s.Nodes().Count(n => n.Children.Count == 0)}, floating: {s.Floating.Count}, unpinned: {s.AutoHidden.Count}, closed: {s.Closed.Count}.";
```

