docs(DockManager): add dockmanager documentation

[xristianstefanov]

closes: https://github.com/telerik/blazor/issues/10644

[yanisslav]

It might be helpful to explain the undocking process, as it’s quite specific. Undocking a content pane creates a floating split pane containing the pane. This can confuse clients when docking it, as the OnDock event triggers with the new split pane's ID.

Probably we can mention this as a note somewhere in the events article.

===

Another detail to mention is that when a split/tab group pane is not configured with AllowEmpty=true and has no child panes, it is disposed.

Other than that, IMO, the documentation looks great.🚀

[dimodi]

Consider adding a tip that the Dock manager is most suitable for desktop-like interfaces and larger screens.

[dimodi]

If you use tags, then use tags for the HeaderTemplate and Content too. Otherwise it may look like these are used differently.

[dimodi]

Consider the following improvements:

• Make the example simpler by removing the repetitive panes and long content. It may be overwhelming for first-time users.
• Make the configuration suitable to fit in small space in the docs.
• Set some pane parameters, which are most likely to be used, such as Size and Orientation.
• The HeaderTemplate is optional, so it can be spared in the basic example. Moreover, the header still requires the usage of HeaderText for unpinned scenarios.

For example:

<TelerikDockManager Height="90vh">
    <DockManagerPanes>

        <DockManagerSplitPane Orientation="@DockManagerPaneOrientation.Vertical"
                              Size="40%">
            <Panes>

                <DockManagerContentPane Size="55%" HeaderText="Pane 1.1">
                    <Content>
                        First Content Pane in Split configuration
                    </Content>
                </DockManagerContentPane>

                <DockManagerContentPane HeaderText="Pane 1.2">
                    <Content>
                        Second Content Pane in Split configuration
                    </Content>
                </DockManagerContentPane>

            </Panes>
        </DockManagerSplitPane>

        <DockManagerTabGroupPane>
            <Panes>

                <DockManagerContentPane HeaderText="Tab 2.1">
                    <Content>
                        First Tab Content
                    </Content>
                </DockManagerContentPane>

                <DockManagerContentPane HeaderText="Tab 2.2">
                    <Content>
                        Second Tab Content
                    </Content>
                </DockManagerContentPane>

            </Panes>
        </DockManagerTabGroupPane>
    </DockManagerPanes>

    <DockManagerFloatingPanes>
        <DockManagerSplitPane>
            <Panes>

                <DockManagerContentPane HeaderText="Floating Pane">
                    <Content>
                        Floating Pane Content
                    </Content>
                </DockManagerContentPane>

            </Panes>
        </DockManagerSplitPane>
    </DockManagerFloatingPanes>
</TelerikDockManager>

[dimodi]

"Dock Types" implies that "dock" is a noun, while it's a verb. Consider "Docking Types", similar to the heading in the linked article.

[dimodi]

Wrong link

[dimodi]

Is it "resizable sections with multiple panes" or is it "sections with multiple resizable panes" ?

[dimodi]

Suggested change

	The [Dock Manager allows getting and setting its state](slug://dockmanager-state). The DockManager state contains information about the panes hierarchy, a collection of all the floating panes, and all the DockManager configurations, such as its orientation.
	The [Dock Manager allows getting and setting its state](slug://dockmanager-state). The DockManager state contains information about the pane hierarchy, floating panes, current pane settings, and the DockManager configuration, such as its orientation.

[dimodi]

Suggested change

	<TelerikDockManager @ref="@DockRef" />
	<TelerikButton OnClick="@GetDockManagerState">Get DockManager State</TelerikButton>
	@code{
	private TelerikDockManager DockRef { get; set; }
	private async Task GetDockManagerState()
	{
	var dockState = DockRef.GetState();
	}
	}
	<TelerikDockManager @ref="@DockManagerRef" />
	<TelerikButton OnClick="@GetDockManagerState">Get DockManager State</TelerikButton>
	@code{
	private TelerikDockManager? DockManagerRef { get; set; }
	private void GetDockManagerState()
	{
	var dockState = DockManagerRef?.GetState();
	}
	}

[dimodi]

Since these are "steps", use action verbs here, similar to https://www.telerik.com/blazor-ui/documentation/components/listbox/overview#next-steps

[dimodi]

The state is a more complex concept, so it should come after the articles about panes and dock types. The customer should first know how to configure the component declaratively, and then how to use the state.

[dimodi]

Follow correct heading hierarchy. Actually, you can:

• Remove "Panes Nested Tags Settings"
• Use human readable headings such as "Content Pane", "TabGroup Pane", etc.

[dimodi]

Think of a second list item, so that a list makes sense. For example, confirm that the content pane cannot have child panes.

[dimodi]

Currently this example is very similar to the basic one in Overview. It should either provide some unique value, which the other examples don't or otherwise it can be removed for simplicity.

[dimodi]

This example can be simpler and more engaging and interactive to facilitate understanding.

<TelerikDockManager Height="80vh">
    <DockManagerPanes>

        <DockManagerSplitPane>
            <Panes>

                <DockManagerContentPane HeaderText="Pane 1" Dockable="@Pane1Dockable">
                    <Content>
                        <TelerikToggleButton @bind-Selected="@Pane1Dockable">Enable Docking Over Pane 1</TelerikToggleButton>
                    </Content>
                </DockManagerContentPane>

                <DockManagerContentPane HeaderText="Pane 2" Dockable="Pane2Dockable">
                    <Content>
                        <TelerikToggleButton @bind-Selected="@Pane2Dockable">Enable Docking Over Pane 2</TelerikToggleButton>
                    </Content>
                </DockManagerContentPane>

            </Panes>
        </DockManagerSplitPane>
    </DockManagerPanes>

    <DockManagerFloatingPanes>
        <DockManagerSplitPane>
            <Panes>

                <DockManagerContentPane HeaderText="Floating Pane">
                    <Content>
                        Floating Pane Content
                    </Content>
                </DockManagerContentPane>

            </Panes>
        </DockManagerSplitPane>
    </DockManagerFloatingPanes>
</TelerikDockManager>

@code {
    private bool Pane1Dockable { get; set; } = true;
    private bool Pane2Dockable { get; set; } = true;
}

[dimodi]

Maybe Pane Types should come before Docking Types in the left navigation.

[dimodi]

Suggested change

	tags: telerik,blazor,dockmanager,pane,types
	tags: telerik, blazor, dockmanager, panes

[dimodi]

Suggested change

	tags: telerik,blazor,dockmanager,dock,types
	tags: telerik, blazor, dockmanager, docking

[dimodi]

VisibleChanged and SizeChanged for the panes are missing. SizeChanged is similar to OnPaneResize - it depends if you want to monitor all panes or just one.

[dimodi]

The example may not be convenient to use the small REPL frame in the docs. Also, I am not sure the simulated real use case makes sense. Why would you place tasks and assigned people in separate dock panes?

Consider simplifying and making the example more self-explanatory:

<TelerikDockManager @ref="@DockManagerRef"
                    Height="70vh"
                    Width="90vw"
                    OnDock="@OnPaneDock"
                    OnUndock="@OnPaneUndock"
                    OnPin="@OnPanePin"
                    OnPaneResize="@OnPaneResize"
                    OnUnpin="@OnPaneUnpin">
    <DockManagerPanes>

        <DockManagerSplitPane Orientation="@DockManagerPaneOrientation.Vertical"
                              Size="40%"
                              Id="SplitPane">
            <Panes>

                <DockManagerContentPane HeaderText="Pane 1"
                                        Id="Pane1"
                                        Size="50%"
                                        Closeable="false">
                    <Content>
                        Pane 1. Undocking is allowed. Docking over it is cancelled.
                    </Content>
                </DockManagerContentPane>

                <DockManagerContentPane HeaderText="Pane 2"
                                        Id="Pane2"
                                        Size="50%"
                                        Closeable="false">
                    <Content>
                        Pane 2. Docking over it is allowed. Undocking is cancelled.
                        <br />
                        <TelerikButton ThemeColor="@ThemeConstants.Button.ThemeColor.Primary"
                                       Enabled="@( !Pane4Visible || !FloatingPaneVisible )"
                                       OnClick="@( () => { Pane4Visible = true; FloatingPaneVisible = true; DockManagerRef?.Refresh(); })">
                            Restore Closed Panes
                        </TelerikButton>
                    </Content>
                </DockManagerContentPane>

            </Panes>
        </DockManagerSplitPane>

        <DockManagerTabGroupPane Id="TabGroupPane">
            <Panes>

                <DockManagerContentPane HeaderText="Pane 3"
                                        Id="Pane3"
                                        Closeable="false">
                    <Content>
                        Pane 3. Unpinning is possible, but pinning is cancelled.
                    </Content>
                </DockManagerContentPane>

                <DockManagerContentPane HeaderText="Pane 4"
                                        Id="Pane4"
                                        Visible="@Pane4Visible"
                                        VisibleChanged="OnPane4VisibleChanged">
                    <Content>
                        Pane 4. Can be closed. Unpinning is cancelled.
                    </Content>
                </DockManagerContentPane>

            </Panes>
        </DockManagerTabGroupPane>
    </DockManagerPanes>

    <DockManagerFloatingPanes>
        <DockManagerSplitPane Id="FloatingSplitPane">
            <Panes>

                <DockManagerContentPane HeaderText="Floating Pane"
                                        Id="FloatingPane"
                                        Visible="@FloatingPaneVisible"
                                        VisibleChanged="OnFloatingPaneVisibleChanged">
                    <Content>
                        Floating Pane. Can be closed.
                    </Content>
                </DockManagerContentPane>

            </Panes>
        </DockManagerSplitPane>
    </DockManagerFloatingPanes>
</TelerikDockManager>

<p style="color: var(--kendo-color-primary)">DockManager Events (latest on top):</p>

<div style="height: 20vh; border:1px solid var(--kendo-color-border); overflow: auto;">
    @foreach (var item in DockManagetEventLog)
    {
        <div>@( (MarkupString)item )</div>
    }
</div>

@code {
    private TelerikDockManager? DockManagerRef { get; set; }

    private bool Pane4Visible { get; set; } = true;
    private bool FloatingPaneVisible { get; set; } = true;

    private List<string> DockManagetEventLog { get; set; } = new();

    private void OnPaneDock(DockManagerDockEventArgs args)
    {
        if (args.TargetPaneId == "Pane1")
        {
            args.IsCancelled = true;
            DockManagetEventLog.Insert(0, $"Pane <strong>{args.PaneId}</strong> was about to dock to pane <strong>{args.TargetPaneId}</strong>. Event cancelled.");
        }
        else
        {
            DockManagetEventLog.Insert(0, $"Pane <strong>{args.PaneId}</strong> was docked to pane <strong>{args.TargetPaneId}.");
        }
    }

    private void OnPaneUndock(DockManagerUndockEventArgs args)
    {
        if (args.PaneId == "Pane2")
        {
            args.IsCancelled = true;
            DockManagetEventLog.Insert(0, $"Pane <strong>{args.PaneId}</strong> was about to undock. Event cancelled.");
        }
        else
        {
            DockManagetEventLog.Insert(0, $"Pane <strong>{args.PaneId}</strong> was undocked.");
        }
    }

    private void OnPanePin(DockManagerPinEventArgs args)
    {
        if (args.PaneId == "Pane3")
        {
            args.IsCancelled = true;
            DockManagetEventLog.Insert(0, $"Pane <strong>{args.PaneId}</strong> was about to pin. Event cancelled.");
        }
        else
        {
            DockManagetEventLog.Insert(0, $"Pane <strong>{args.PaneId}</strong> was pinned.");
        }
    }

    private void OnPaneResize(DockManagerPaneResizeEventArgs args)
    {
        DockManagetEventLog.Insert(0, $"Pane <strong>{args.PaneId}</strong> was resized to {args.Size}.");
    }

    private void OnPaneUnpin(DockManagerUnpinEventArgs args)
    {
        if (args.PaneId == "Pane4")
        {
            args.IsCancelled = true;
            DockManagetEventLog.Insert(0, $"Pane <strong>{args.PaneId}</strong> was about to unpin. Event cancelled.");
        }
        else
        {
            DockManagetEventLog.Insert(0, $"Pane <strong>{args.PaneId}</strong> was unpinned.");
        }
    }

    private void OnPane4VisibleChanged(bool newVisible)
    {
        Pane4Visible = newVisible;

        DockManagetEventLog.Insert(0, $"Pane <strong>Pane4</strong> was closed.");
    }

    private void OnFloatingPaneVisibleChanged(bool newVisible)
    {
        FloatingPaneVisible = newVisible;

        DockManagetEventLog.Insert(0, $"Pane <strong>FloatingPane</strong> was closed.");
    }
}