From 07df1b48ba6393ad7a1c963f2616862a936c9364 Mon Sep 17 00:00:00 2001
From: mathuo <6710312+mathuo@users.noreply.github.com>
Date: Mon, 10 Jul 2023 21:57:03 +0100
Subject: [PATCH] feat: docs
---
README.md | 1 +
packages/dockview-core/README.md | 1 +
packages/dockview/README.md | 1 +
.../docs/blog/2023-08-01-dockview-1.8.0.md | 25 +++
packages/docs/docs/basics.mdx | 114 ------------
packages/docs/docs/components/dockview.mdx | 171 +++++++++++-------
packages/docs/docs/index.mdx | 148 +++++----------
packages/docs/docs/theme.mdx | 37 ++--
packages/docs/docusaurus.config.js | 8 +-
.../constraints-dockview/src/app.tsx | 5 +-
.../customheader-dockview/src/app.tsx | 6 +-
.../docs/sandboxes/demo-dockview/src/app.tsx | 16 +-
.../docs/sandboxes/dnd-dockview/src/app.tsx | 4 +-
.../docs/sandboxes/dockview-app/src/app.tsx | 4 +-
.../sandboxes/events-dockview/src/app.tsx | 5 +-
.../externaldnd-dockview/src/app.scss | 3 -
.../externaldnd-dockview/src/app.tsx | 5 +-
.../floatinggroup-dockview/src/app.tsx | 4 +-
.../fullwidthtab-dockview/src/app.tsx | 4 +-
.../headeractions-dockview/src/app.tsx | 4 +-
.../sandboxes/iframe-dockview/src/app.tsx | 4 +-
.../sandboxes/layout-dockview/src/app.tsx | 4 +-
.../sandboxes/nativeapp-dockview/src/app.tsx | 4 +-
.../sandboxes/nested-dockview/src/app.tsx | 6 +-
.../sandboxes/rendering-dockview/src/app.tsx | 9 +-
.../sandboxes/resize-dockview/src/app.tsx | 4 +-
.../resizecontainer-dockview/src/app.tsx | 4 +-
.../sandboxes/tabheight-dockview/src/app.tsx | 4 +-
.../updatetitle-dockview/src/app.tsx | 4 +-
.../sandboxes/watermark-dockview/src/app.tsx | 4 +-
.../src/components/HomepageFeatures/index.tsx | 37 +++-
.../HomepageFeatures/introduction.tsx | 44 +++++
packages/docs/src/components/ui/container.tsx | 114 +++++++-----
packages/docs/src/pages/index.tsx | 35 +---
packages/docs/static/img/dockview_grid_4.svg | 93 ++++++++++
packages/docs/static/img/splashscreen.gif | Bin 171942 -> 465612 bytes
36 files changed, 501 insertions(+), 435 deletions(-)
create mode 100644 packages/docs/blog/2023-08-01-dockview-1.8.0.md
delete mode 100644 packages/docs/docs/basics.mdx
delete mode 100644 packages/docs/sandboxes/externaldnd-dockview/src/app.scss
create mode 100644 packages/docs/src/components/HomepageFeatures/introduction.tsx
create mode 100644 packages/docs/static/img/dockview_grid_4.svg
diff --git a/README.md b/README.md
index cf7eece3a..0f26a8799 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,7 @@ Please see the website: https://dockview.dev
- Themable and customizable
- Serialization / deserialization support
- Tabular docking and Drag and Drop support
+- Floating groups, customized header bars and tab
- Documentation and examples
Want to inspect the latest deployment? Go to https://unpkg.com/browse/dockview@latest/
diff --git a/packages/dockview-core/README.md b/packages/dockview-core/README.md
index 57d14843e..509a183c0 100644
--- a/packages/dockview-core/README.md
+++ b/packages/dockview-core/README.md
@@ -25,6 +25,7 @@ Please see the website: https://dockview.dev
- Themable and customizable
- Serialization / deserialization support
- Tabular docking and Drag and Drop support
+- Floating groups, customized header bars and tab
- Documentation and examples
Want to inspect the latest deployment? Go to https://unpkg.com/browse/dockview-core@latest/
diff --git a/packages/dockview/README.md b/packages/dockview/README.md
index e96b3b5e3..ca2240286 100644
--- a/packages/dockview/README.md
+++ b/packages/dockview/README.md
@@ -25,6 +25,7 @@ Please see the website: https://dockview.dev
- Themable and customizable
- Serialization / deserialization support
- Tabular docking and Drag and Drop support
+- Floating groups, customized header bars and tab
- Documentation and examples
Want to inspect the latest deployment? Go to https://unpkg.com/browse/dockview@latest/
diff --git a/packages/docs/blog/2023-08-01-dockview-1.8.0.md b/packages/docs/blog/2023-08-01-dockview-1.8.0.md
new file mode 100644
index 000000000..535fc13fb
--- /dev/null
+++ b/packages/docs/blog/2023-08-01-dockview-1.8.0.md
@@ -0,0 +1,25 @@
+---
+slug: dockview-1.8.0-release
+title: Dockview 1.8.0
+tags: [release]
+---
+
+Preemptive documation for the upcoming `1.8.0` release.
+
+# Release Notes
+
+Please reference to docs @ [dockview.dev](https://dockview.dev).
+
+## 🚀 Features
+
+- Support for Floating Groups [#262](https://github.com/mathuo/dockview/pull/262)
+- Left hand header changes [#264](https://github.com/mathuo/dockview/pull/264)
+- Retain layout size [#285](https://github.com/mathuo/dockview/pull/285)
+- Expose `removePanel` [#293](https://github.com/mathuo/dockview/issues/293)
+- Additional themes
+
+## 🛠Miscs
+
+## 🔥 Breaking changes
+
+- `groupControlComponent` renamed to `rightHeaderActionsComponent` [#264](https://github.com/mathuo/dockview/pull/264)
diff --git a/packages/docs/docs/basics.mdx b/packages/docs/docs/basics.mdx
deleted file mode 100644
index b2c8ebcdb..000000000
--- a/packages/docs/docs/basics.mdx
+++ /dev/null
@@ -1,114 +0,0 @@
----
-sidebar_position: 1
-description: How to get started with Dockview
----
-
-import { SimpleSplitview } from '@site/src/components/simpleSplitview';
-import { SimpleSplitview2 } from '@site/src/components/simpleSplitview2';
-
-# Basics
-
-This section will take you through a number of concepts that can be applied to all dockview components.
-
-## Panels
-
-The below examples use `ReactSplitview` but the logic holds for `ReactPaneview`, `ReactGridview` and `ReactDockview` using their respective implementations and interfaces.
-All components require you to provide an `onReady` prop which you can use to build and control your component.
-
-### Adding a panel with parameters
-
-You can pass parameters to a panel through the `params` object
-
-```tsx
-const onReady = (event: SplitviewReadyEvent) => {
- event.api.addPanel({
- id: 'panel_1',
- component: 'myComponent',
- params: {
- title: 'My Title',
- },
- });
-};
-```
-
-and you can access those properties through the `props.params` object. The TypeScript interface accepts an optional generic type `T` that corresponds to the params objects type.
-
-```tsx
-const MyComponent = (props: ISplitviewPanelProps<{ title: string }>) => {
- return
{`My first panel has the title: ${props.params.title}`}
;
-};
-```
-
-## API
-
-There are two types of API you will interact with using `dockview`.
-
-- The `panel API` is accessible via `props.api` in user defined panels and via the `.api` variable found on panel instances. This API contains actions and variable related to the the individual panel.
-- The `container API` is accessible via `event.api` in the `onReady` events and `props.containerApi` in user defined panels. This API contains actions and variable related to the component as a whole.
-
-```tsx
-const MyComponent = (props: ISplitviewPanelProps<{ title: string }>) => {
- React.useEffect(() => {
- const disposable = props.api.onDidActiveChange((event) => {
- console.log(`is panel active: ${event.isActive}`);
- });
- return () => {
- disposable.dispose(); // remember to dispose of any subscriptions
- };
- }, [props.api]);
- const addAnotherPanel = React.useCallback(() => {
- props.containerApi.addPanel({
- id: 'another_id',
- component: 'anotherComponent',
- });
- }, [props.containerApi]);
- return (
-
- {`My first panel has the title: ${props.params.title}`}
-
-
- );
-};
-```
-
-### Serialization
-
-All components support `toJSON(): T` which returns a Typed object representation of the components state. This same Typed object can be used to deserialize a view using `fromJSON(object: T): void`.
-
-## Auto resizing
-
-`SplitviewReact`, `GridviewReact`, `PaneviewReact` and `DockviewReact` will all automatically resize to fill the size of their parent element.
-Internally this is achieved using a [ResizeObserver](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) which some users may need to polyfill.
-You can disable this by settings the `disableAutoResizing` prop to be `true`.
-
-You can manually resize a component using the API method `layout(width: number, height: number): void`.
-An advanced case may use this in conjunction with `disableAutoResizing=true` to allow a parent component to have ultimate control over the dimensions of the component.
-
-## Events
-
-Many API properties can be listened on using the `Event` pattern. For example `api.onDidFocusChange(() => {...})`.
-You should dispose of any event listeners you create cleaning up any listeners you would have created.
-
-```tsx
-React.useEffect(() => {
- const disposable = api.onDidFocusChange(() => {
- // write some code
- });
- return () => {
- disposable.dispose();
- };
-}, []);
-```
-
-## Proportional layout
-
-The `proportionalLayout` property indicates the expected behaviour of the component as it's container resizes, should all views resize equally or should just one view expand to fill the new space. `proportionalLayout` can be set as a property on `SplitviewReact` and `GridviewReact` components.
-Although not configurable on `DockviewReact` and `PaneviewReact` these both behave as if `proportionalLayout=true` was set for them.
-
-
-
-
-
-## Browser support
-
-dockview is intended to support all major browsers. Some users may require a polyfill for [ResizeObserver](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver).
diff --git a/packages/docs/docs/components/dockview.mdx b/packages/docs/docs/components/dockview.mdx
index 3f2f0f51c..c638dd371 100644
--- a/packages/docs/docs/components/dockview.mdx
+++ b/packages/docs/docs/components/dockview.mdx
@@ -2,10 +2,7 @@
description: Dockview Documentation
---
-import {
- Container,
- MultiFrameworkContainer,
-} from '@site/src/components/ui/container';
+import { MultiFrameworkContainer } from '@site/src/components/ui/container';
import Link from '@docusaurus/Link';
import useBaseUrl from '@docusaurus/useBaseUrl';
@@ -168,6 +165,25 @@ const MyComponent = (props: IDockviewPanelProps<{ title: string }>) => {
| close | `(): void` | |
| setTitle | `(title: string): void` | |
+## Theme
+
+As well as importing the `dockview` stylesheet you must provide a class-based theme somewhere in your application. For example.
+
+```tsx
+// Providing a theme directly through the DockviewReact component props
+
+
+// Providing a theme somewhere in the DOM tree
+
+
+ {/**... */}
+
+
+
+```
+
+You can find more details on theming here.
+
## Layout Persistance
Layouts are loaded and saved via to `fromJSON` and `toJSON` methods on the Dockview api.
@@ -220,9 +236,10 @@ const onReady = (event: DockviewReadyEvent) => {
Here is an example using the above code loading from and saving to localStorage.
If you refresh the page you should notice your layout is loaded as you left it.
-
-
-
+
## Resizing
@@ -251,17 +268,16 @@ props.api.group.api.setSize({
You can see an example invoking both approaches below.
-
-
-
+
### Container Resizing
The component will automatically resize to it's container.
-
-
-
+
## Watermark
@@ -269,9 +285,10 @@ When the dockview is empty you may want to display some fallback content, this i
By default there the watermark has no content but you can provide as a prop to `DockviewReact` a `watermarkComponent`
which will be rendered when there are no panels or groups.
-
-
-
+
## Drag And Drop
@@ -348,9 +365,7 @@ return (
);
```
-
-
-
+
### Third Party Dnd Libraries
@@ -358,9 +373,10 @@ This shows a simple example of a third-party library used inside a panel that re
and drop functionalities. This examples serves to show that `dockview` doesn't interfer with
any drag and drop logic for other controls.
-
-
-
+
## Floating Groups
@@ -385,9 +401,11 @@ Floating groups can be interacted with whilst holding the `shift` key activating
Floating groups can be programatically added through the dockview `api` method `api.addFloatingGroup(...)` and you can check whether
a group is floating via the `group.api.isFloating` property. See examples for full code.
-
-
-
+
## Panels
@@ -465,6 +483,23 @@ const panel2 = api.addPanel({
});
```
+To add a floating panel you should include the `floating` variable which can be either a `boolean` or an object defining it's bounds.
+These bounds are relative to the dockview component.
+
+```ts
+const panel1 = api.addPanel({
+ id: 'panel_2',
+ component: 'default',
+ floating: true,
+});
+
+const panel2 = api.addPanel({
+ id: 'panel_2',
+ component: 'default',
+ floating: { x: 10, y: 10, width: 300, height: 300 },
+});
+```
+
### Update Panel
You can programatically update the `params` passed through to the panel through the panal api using `api.updateParameters`.
@@ -514,6 +549,21 @@ const group = panel.api.group;
group.api.moveTo({ group, position });
```
+### Remove panel
+
+You can programatically remove a panel using the panel `api`.
+
+```ts
+panel.api.close();
+```
+
+Given a reference to the panel you can also use the component `api` to remove it.
+
+```ts
+const panel = api.getPanel('myPanel');
+api.removePanel(panel);
+```
+
### Panel Rendering
By default `DockviewReact` only adds to the DOM those panels that are visible,
@@ -568,9 +618,10 @@ const components = { default: RenderWhenVisible(MyComponent) };
Toggling the checkbox you can see that when you only render those panels which are visible the underling React component is destroyed when it becomes hidden and re-created when it becomes visible.
-
-
-
+
## Headers
@@ -624,9 +675,10 @@ As a simple example the below attaches a custom event handler for the context me
The below example uses a custom tab renderer to reigster a popover when the user right clicked on a tab.
This still makes use of the `DockviewDefaultTab` since it's only a minor change.
-
-
-
+
### Default Tab Title
@@ -649,9 +701,10 @@ api.setTitle('my_new_custom_title');
> Note this only works when using the default tab implementation.
-
-
-
+
### Custom Tab Title
@@ -764,9 +817,10 @@ const RightHeaderActionsComponent = (props: IDockviewHeaderActionsProps) => {
};
```
-
-
-
+
### Constraints
@@ -780,9 +834,11 @@ api.group.api.setConstraints(...)
> If you specific a constraint on a group and move a panel within that group to another group it will no
> longer be subject to those constraints since those constraints were on the group and not on the individual panel.
-
-
-
+
## iFrames
@@ -803,17 +859,21 @@ The visibility of these hoisted elements is then controlled through some exposed
You should open this example in CodeSandbox using the provided link to understand the code and make use of this implemention if required.
-
-
-
+
## Events
A simple example showing events fired by `dockviewz that can be interacted with.
-
-
-
+
## Advanced Examples
@@ -822,25 +882,8 @@ A simple example showing events fired by `dockviewz that can be interacted with.
You can safely create multiple dockview instances within one page and nest dockviews within other dockviews.
If you wish to interact with the drop event from one dockview instance in another dockview instance you can implement the `showDndOverlay` and `onDidDrop` props on `DockviewReact`.
-
-
-
+
### Window-like mananger with tabs
-
-## Vanilla JS
-
-> Note: This section is experimental and support for Vanilla JS is a work in progress.
-
-The `dockview` package contains `ReactJS` wrappers for the core library.
-The core library is published as an independant package under the name `dockview-core` which you can install standalone.
-
-> When using `dockview` there is no need to also install `dockview-core`.
-> `dockview-core` is a dependency of `dockview` and automatically installed during the installation process of `dockview` via `npm install dockview`.
-
-
diff --git a/packages/docs/docs/index.mdx b/packages/docs/docs/index.mdx
index 0e96a515f..9ea7f0923 100644
--- a/packages/docs/docs/index.mdx
+++ b/packages/docs/docs/index.mdx
@@ -1,23 +1,18 @@
---
sidebar_position: 0
-description: A zero dependency layout manager built for React
+description: A zero dependency layout manager supporting ReactJS and Vanilla TypeScript
---
import { SimpleSplitview } from '@site/src/components/simpleSplitview';
import { SimpleGridview } from '@site/src/components/simpleGridview';
import { SimplePaneview } from '@site/src/components/simplePaneview';
import SimpleDockview from '@site/sandboxes/simple-dockview/src/app';
+import Link from '@docusaurus/Link';
# Introduction
**dockview** is a zero dependency layout manager that supports tab, grids and splitviews.
-## Features
-
-- Themable and customizable
-- Support for the serialization and deserialization of layouts
-- Drag and drop support
-
## Quick start
`dockview` has a peer dependency on `react >= 16.8.0` and `react-dom >= 16.8.0`. To install `dockview` you can run:
@@ -33,53 +28,11 @@ depending on your solution this might be:
@import './node_modules/dockview/dist/styles/dockview.css';
```
-A dark and light theme are provided, one of these classes (or a custom theme) must be attached at any point above your components in the HTML tree. To cover the entire web page you might attach the class to the `body` component:
-
-```html
-
- ...
-
-
- ...
-
-```
-
There are 4 components you may want to use:
-Splitview
-
-
diff --git a/packages/docs/docs/theme.mdx b/packages/docs/docs/theme.mdx
index bd770f5d7..487683299 100644
--- a/packages/docs/docs/theme.mdx
+++ b/packages/docs/docs/theme.mdx
@@ -3,27 +3,29 @@ sidebar_position: 3
description: Theming Dockview Components
---
-import { CustomCSSDockview } from '@site/src/components/dockview/customCss';
-
# Theme
## Introduction
-`dockview` requires some css to work correctly.
-The css is exported as one file under [`dockview/dict/styles/dockview.css`](https://unpkg.com/browse/dockview@latest/dist/styles/dockview.css)
-and depending can be imported
+`dockview` requires some CSS to work correctly.
+The CSS is exported as one file under [`dockview/dict/styles/dockview.css`](https://unpkg.com/browse/dockview@latest/dist/styles/dockview.css)
+and should be imported at some point in your application
-```css
+```css title="Example import with .css file"
@import './node_modules/dockview/dist/styles/dockview.css';
```
## Provided themes
-The following are provided as classes that you can attached to your components for themeing
+`dockview` comes with a number of themes which are all CSS classes and can be found [here](https://github.com/mathuo/dockview/blob/master/packages/dockview-core/src/theme.scss).
+To use a `dockview` theme the CSS must encapsulate the component. The current list of themes is:
-- `.dockview-theme-light`
-- `.dockview-theme-dark`
-- `.dockview-theme-abyss`
+- `dockview-theme-dark`
+- `dockview-theme-light`
+- `dockview-theme-vs`
+- `dockview-theme-abyss`
+- `dockview-theme-dracula`
+- `dockview-theme-replit`
## Customizing Theme
@@ -60,9 +62,9 @@ and are free to build your own themes based on these css properties.
| --dv-paneview-header-border-color | |
You can further customise the theme through adjusting class properties but this is up you.
-As an example if you wanted to add a bottom border to the tab container for an active group in the `DockviewReact` component you could write:
+For example if you wanted to add a bottom border to the tab container for an active group in the `DockviewReact` component you could write:
-```css
+```css title="Additional CSS to show a bottom border on active groups"
.groupview {
&.active-group {
> .tabs-and-actions-container {
@@ -76,14 +78,3 @@ As an example if you wanted to add a bottom border to the tab container for an a
}
}
```
-
-
})
-
- Dockview Live Demos
-
-