chore: docs

.codesandbox/ci.json

@@ -9,6 +9,7 @@
     "/packages/docs/sandboxes/demo-dockview",
     "/packages/docs/sandboxes/dnd-dockview",
     "/packages/docs/sandboxes/dockview-app",
+    "/packages/docs/sandboxes/editor-gridview",
     "/packages/docs/sandboxes/events-dockview",
     "/packages/docs/sandboxes/externaldnd-dockview",
     "/packages/docs/sandboxes/floatinggroup-dockview",
@@ -26,6 +27,7 @@
     "/packages/docs/sandboxes/resize-dockview",
     "/packages/docs/sandboxes/resizecontainer-dockview",
     "/packages/docs/sandboxes/simple-dockview",
+    "/packages/docs/sandboxes/simple-gridview",
     "/packages/docs/sandboxes/simple-paneview",
     "/packages/docs/sandboxes/tabheight-dockview",
     "/packages/docs/sandboxes/updatetitle-dockview",

packages/docs/blog/2023-10-06-dockview-1.8.4.md

@@ -0,0 +1,33 @@
+---
+slug: dockview-1.8.4-release
+title: Dockview 1.8.4
+tags: [release]
+---
+
+# Release Notes
+
+Please reference to docs @ [dockview.dev](https://dockview.dev).
+
+## 🚀 Features
+
+-   Optional header actions before tabs list [#338](https://github.com/mathuo/dockview/issues/338)
+
+## 🛠 Miscs
+
+-   Bug: Recover from corrupted layouts gracefully [#341](https://github.com/mathuo/dockview/issues/341)
+
+-   Bug: Fix floating group resizing within nested tabs [#344](https://github.com/mathuo/dockview/issues/344)
+
+-   Bug: Progmatic resizing priority [#350](https://github.com/mathuo/dockview/issues/350)
+
+-   Bug: Incorrect disposal of deeply nested gridview [#356](https://github.com/mathuo/dockview/issues/356)
+
+-   Splitview separator stlye restored on deserialize step [#358](https://github.com/mathuo/dockview/issues/358)
+
+-   Docs: Additional Docs [#347](https://github.com/mathuo/dockview/issues/347)
+
+-   Docs: Additional Docs [#336](https://github.com/mathuo/dockview/issues/336)
+
+-   Docs: Additional Docs [#352](https://github.com/mathuo/dockview/issues/352)
+
+## 🔥 Breaking changes

packages/docs/docs/components/dockview.mdx

@@ -426,7 +426,7 @@ Finally `addPanel` accepts a `position` object which tells dockview where to pla
 -   This object accepts a `direction` property which dictates where,
     relative to the provided reference the new panel will be placed.
 
-> If neither a `referencePanel` or `referenceGroup` then the provided `direction` will be treated as absolute.
+> If neither a `referencePanel` or `referenceGroup` is provided then the `direction` will be treated as absolute.
 
 > If no `direction` is provided the library will place the new panel in a pre-determined position.
 

packages/docs/docs/components/gridview.mdx

@@ -4,6 +4,7 @@ description: Gridview Documentation
 
 import { MultiFrameworkContainer } from '@site/src/components/ui/container';
 import SimpleGridview from '@site/sandboxes/simple-gridview/src/app';
+import EditorGridview from '@site/sandboxes/editor-gridview/src/app';
 // import SimpleGridview from '@site/sandboxes/simple-gridview/src/app';
 import { EventsGridview } from '@site/src/components/gridview/events';
 // import IDEExample from '@site/sandboxes/ide-example/src/app';
@@ -61,6 +62,144 @@ const MyComponent = (props: IGridviewPanelProps<{ title: string }>) => {
 
 <DocRef declaration="GridviewPanelApi" />
 
+## Resizing
+
+### Panel Resizing
+
+You can set the size of a panel using `props.api.setSize(...)`.
+
+```tsx
+// it's mandatory to provide either a height or a width, providing both is optional
+props.api.setSize({
+    height: 100,
+    width: 200,
+});
+```
+
+You can update any constraints on the panel. All parameters are optional.
+
+```tsx
+props.api.setConstraints({
+    minimumHeight: 100,
+    maximumHeight: 1000
+    minimumWidth: 100,
+    maximumWidth: 1000
+});
+```
+
+You can hide a panel by setting it's visibility to `false`. Hidden panels retain their size
+at the point of being hidden, if made visible again they will try to resize to the remembered size.
+
+```tsx
+props.api.setVisible(false);
+```
+
+## Panels
+
+### Add Panel
+
+Using the gridview API you can access the `addPanel` method which returns an instance of the created panel.
+The minimum method signature is:
+
+```ts
+const panel = api.addPanel({
+    id: 'my_unique_panel_id',
+    component: 'my_component',
+});
+```
+
+where `id` is the unique id of the panel and `component` is the implenentation which
+will be used to render the panel. You will have registered this using the `components` prop of the `GridviewReactComponent` component.
+
+You can pass bounding constraints to limit the size of the panel.
+
+```ts
+const panel = api.addPanel({
+    id: 'my_unique_panel_id',
+    component: 'my_component',
+    minimumHeight: 100,
+    maximumHeight: 1000,
+    minimumWidth: 100,
+    maximumWidth: 1000,
+});
+```
+
+You can pass a `snap` parameter which will hide the panel when an attempt is made to move it beyond a minimum width or height if one exists.
+
+```ts
+const panel = api.addPanel({
+    id: 'my_unique_panel_id',
+    component: 'my_component',
+    minimumHeight: 100,
+    snap: true,
+});
+```
+
+You can pass a `priority` parameter which will keep the panel a certain priority when being resized. This is useful when you know you want this
+panel to always take the first available or last available space. The default is `LayoutPriority.Normal` which defers space allocations to the libraries discression.
+
+```ts
+const panel = api.addPanel({
+    id: 'my_unique_panel_id',
+    component: 'my_component',
+    minimumHeight: 100,
+    priority: LayoutPriority.High,
+});
+```
+
+You can pass properties to the panel using the `params` key.
+You can update these properties through the panels `api` object and its `updateParameters` method.
+
+```ts
+const panel = api.addPanel({
+    id: 'my_unique_panel_id',
+    component: 'my_component',
+    params: {
+        myCustomKey: 'my_custom_value',
+    },
+});
+```
+
+```tsx
+panel.api.updateParameters({
+    myCustomKey: 'my_custom_value',
+    myOtherCustomKey: 'my_other_custom_key',
+});
+```
+
+> Note `updateParameters` does not accept partial parameter updates, you should call it with the entire set of parameters
+> you want the panel to receive.
+
+Finally `addPanel` accepts a `position` object which tells dockview where to place the panel.
+
+-   This object accepts a `referencePanel` which can be the associated id as a string
+    or the panel object reference.
+-   This object accepts a `direction` property which dictates where,
+    relative to the provided reference the new panel will be placed.
+
+> If a `referencePanel` is not passed then the `direction` will be treated as absolute.
+
+> If no `direction` is provided the library will place the new panel in a pre-determined position.
+
+```ts
+const panel = api.addPanel({
+    id: 'panel_1',
+    component: 'default',
+});
+
+const panel2 = api.addPanel({
+    id: 'panel_2',
+    component: 'default',
+    position: {
+        referencePanel: panel1,
+        direction: 'right',
+    },
+});
+```
+
+> Note `updateParameters` does not accept partial parameter updates, you should call it with the entire set of parameters
+> you want the panel to receive.
+
 ## Theme
 
 As well as importing the `dockview` stylesheet you must provide a class-based theme somewhere in your application. For example.
@@ -85,3 +224,12 @@ You can find more details on theming <Link to="../theme">here</Link>.
 `GridviewReact` exposes a number of events that the developer can listen to and below is a simple example with a log panel showing those events that occur.
 
 <EventsGridview />
+
+## Complex Example
+
+<MultiFrameworkContainer
+    height={600}
+    sandboxId="editor-gridview"
+    react={EditorGridview}
+    hideThemePicker={true}
+/>

packages/docs/docs/theme.mdx

@@ -60,6 +60,11 @@ and are free to build your own themes based on these css properties.
 |                                                      |             |
 | --dv-separator-border                                |             |
 | --dv-paneview-header-border-color                    |             |
+|                                                      |             |
+| --dv-icon-hover-background-color                     |             |
+| --dv-floating-box-shadow                             |             |
+| --dv-active-sash-color                               |             |
+| --dv-background-color                                |             |
 
 You can further customise the theme through adjusting class properties but this is up you.
 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:

packages/docs/sandboxes/demo-dockview/src/app.tsx

@@ -219,11 +219,13 @@ const DockviewDemo = (props: { theme?: string }) => {
             id: 'panel_2',
             component: 'default',
             title: 'Panel 2',
+            position: { referencePanel: 'panel_1', direction: 'right' },
         });
         event.api.addPanel({
             id: 'panel_3',
             component: 'default',
             title: 'Panel 3',
+            position: { referencePanel: 'panel_2', direction: 'below' },
         });
         event.api.addPanel({
             id: 'panel_4',
@@ -235,42 +237,18 @@ const DockviewDemo = (props: { theme?: string }) => {
             id: 'panel_5',
             component: 'default',
             title: 'Panel 5',
-            position: { referencePanel: 'panel_4', direction: 'within' },
+            position: { referencePanel: 'panel_3', direction: 'below' },
         });
         event.api.addPanel({
             id: 'panel_6',
             component: 'default',
             title: 'Panel 6',
-            position: { referencePanel: 'panel_4', direction: 'below' },
+            position: { referencePanel: 'panel_3', direction: 'right' },
-        });
-        event.api.addPanel({
-            id: 'panel_7',
-            component: 'default',
-            title: 'Panel 7',
-            position: { referencePanel: 'panel_6', direction: 'right' },
-        });
-        event.api.addPanel({
-            id: 'panel_8',
-            component: 'default',
-            title: 'Panel 8',
-            position: { referencePanel: 'panel_7', direction: 'within' },
-        });
-
-        event.api.addPanel({
-            id: 'panel_9',
-            component: 'default',
-            title: 'Panel 9',
-            floating: { width: 450, height: 250 },
-        });
-
-        event.api.addPanel({
-            id: 'panel_10',
-            component: 'default',
-            title: 'Panel 10',
-            position: { referencePanel: 'panel_9' },
         });
 
         event.api.getPanel('panel_1')!.api.setActive();
+
+        console.log(event.api.toJSON());
     };
 
     return (

packages/docs/sandboxes/editor-gridview/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "editor-gridview",
+  "description": "",
+  "keywords": [
+    "dockview"
+  ],
+  "version": "1.0.0",
+  "main": "src/index.tsx",
+  "dependencies": {
+    "dockview": "*",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.28",
+    "@types/react-dom": "^18.0.11",
+    "typescript": "^4.9.5",
+    "react-scripts": "*"
+  },
+  "scripts": {
+    "start": "react-scripts start",
+    "build": "react-scripts build",
+    "test": "react-scripts test --env=jsdom",
+    "eject": "react-scripts eject"
+  },
+  "browserslist": [
+    ">0.2%",
+    "not dead",
+    "not ie <= 11",
+    "not op_mini all"
+  ]
+}

packages/docs/sandboxes/editor-gridview/public/index.html

@@ -0,0 +1,44 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+	<meta charset="utf-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+	<meta name="theme-color" content="#000000">
+	<!--
+      manifest.json provides metadata used when your web app is added to the
+      homescreen on Android. See https://developers.google.com/web/fundamentals/engage-and-retain/web-app-manifest/
+    -->
+	<link rel="manifest" href="%PUBLIC_URL%/manifest.json">
+	<link rel="shortcut icon" href="%PUBLIC_URL%/favicon.ico">
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200" />
+	<!--
+      Notice the use of %PUBLIC_URL% in the tags above.
+      It will be replaced with the URL of the `public` folder during the build.
+      Only files inside the `public` folder can be referenced from the HTML.
+
+      Unlike "/favicon.ico" or "favicon.ico", "%PUBLIC_URL%/favicon.ico" will
+      work correctly both with client-side routing and a non-root public URL.
+      Learn how to configure a non-root public URL by running `npm run build`.
+    -->
+	<title>React App</title>
+</head>
+
+<body>
+	<noscript>
+		You need to enable JavaScript to run this app.
+	</noscript>
+	<div id="root"></div>
+	<!--
+      This HTML file is a template.
+      If you open it directly in the browser, you will see an empty page.
+
+      You can add webfonts, meta tags, or analytics to this file.
+      The build step will place the bundled scripts into the <body> tag.
+
+      To begin the development, run `npm start` or `yarn start`.
+      To create a production bundle, use `npm run build` or `yarn build`.
+    -->
+</body>
+
+</html>

packages/docs/sandboxes/editor-gridview/src/app.scss

@@ -0,0 +1,3 @@
+.simple-gridview-example {
+    --dv-active-sash-color: #007acc;
+}

packages/docs/sandboxes/editor-gridview/src/app.tsx

@@ -0,0 +1,213 @@
+import {
+    GridviewApi,
+    GridviewReact,
+    GridviewReadyEvent,
+    IGridviewPanelProps,
+    LayoutPriority,
+    Orientation,
+    SerializedGridviewComponent,
+} from 'dockview';
+import * as React from 'react';
+import './app.scss';
+
+const components = {
+    default: (props: IGridviewPanelProps<{ title: string }>) => {
+        return (
+            <div style={{ padding: '20px', color: 'white' }}>
+                {props.params.title}
+            </div>
+        );
+    },
+    header: (props: IGridviewPanelProps) => {
+        return (
+            <div style={{ backgroundColor: '#3C3C3C', height: '100%' }}></div>
+        );
+    },
+    footer: (props: IGridviewPanelProps) => {
+        return (
+            <div style={{ backgroundColor: '#007ACC', height: '100%' }}></div>
+        );
+    },
+    sidebar: (props: IGridviewPanelProps) => {
+        return (
+            <div style={{ backgroundColor: '#333333', height: '100%' }}></div>
+        );
+    },
+    'left-expander': (props: IGridviewPanelProps) => {
+        return (
+            <div style={{ backgroundColor: '#252526', height: '100%' }}></div>
+        );
+    },
+    'right-expander': (props: IGridviewPanelProps) => {
+        return (
+            <div style={{ backgroundColor: '#252526', height: '100%' }}></div>
+        );
+    },
+    main: (props: IGridviewPanelProps) => {
+        return (
+            <div
+                style={{
+                    backgroundColor: '#1E1E1E',
+                    height: '100%',
+                    color: 'white',
+                    display: 'flex',
+                    justifyContent: 'center',
+                    flexDirection: 'column',
+                    fontSize: '0.8em',
+                    padding: '10px',
+                }}
+            >
+                <div>{'This entire mockup is built using a gridview.'}</div>
+
+                <div>{`Press 'Ctrl+B' to toggle the left sidebar and 'Ctrl+Alt+B' to toggle the right sidebar or manually resize them.`}</div>
+            </div>
+        );
+    },
+};
+
+const serializedGridview: SerializedGridviewComponent = {
+    grid: {
+        root: {
+            type: 'branch',
+            data: [
+                {
+                    type: 'leaf',
+                    data: {
+                        id: 'header-id',
+                        component: 'header',
+                        minimumHeight: 30,
+                        maximumHeight: 30,
+                    },
+                },
+                {
+                    type: 'branch',
+                    data: [
+                        {
+                            type: 'leaf',
+                            data: {
+                                id: 'sidebar-id',
+                                component: 'sidebar',
+                                minimumWidth: 30,
+                                maximumWidth: 30,
+                            },
+                        },
+                        {
+                            type: 'leaf',
+                            data: {
+                                id: 'left-expander-id',
+                                component: 'left-expander',
+                                minimumWidth: 100,
+                                snap: true,
+                            },
+                        },
+                        {
+                            type: 'leaf',
+                            size: 100,
+                            data: {
+                                id: 'main-id',
+                                component: 'main',
+                                minimumWidth: 100,
+                                minimumHeight: 100,
+                                /**
+                                 * it's important to give the main content a high layout priority as we want
+                                 * the main layout to have priority when allocating new space
+                                 */
+                                priority: LayoutPriority.High,
+                            },
+                        },
+                        {
+                            type: 'leaf',
+                            data: {
+                                id: 'right-expander-id',
+                                component: 'right-expander',
+                                snap: true,
+                                minimumWidth: 100,
+                            },
+                        },
+                    ],
+                },
+                {
+                    type: 'leaf',
+                    data: {
+                        id: 'footer-id',
+                        component: 'footer',
+                        minimumHeight: 30,
+                        maximumHeight: 30,
+                    },
+                },
+            ],
+        },
+        width: 1000,
+        height: 1000,
+        orientation: Orientation.VERTICAL,
+    },
+};
+
+export const App: React.FC = (props: { theme?: string }) => {
+    const [api, setApi] = React.useState<GridviewApi>();
+
+    const onReady = (event: GridviewReadyEvent) => {
+        event.api.fromJSON(serializedGridview);
+
+        setApi(event.api);
+    };
+
+    const onKeyDown = (event: React.KeyboardEvent) => {
+        if (!api) {
+            return;
+        }
+
+        console.log(event);
+
+        const leftExpander = api.getPanel('left-expander-id');
+        const rightExpander = api.getPanel('right-expander-id');
+
+        if (!leftExpander || !rightExpander) {
+            return;
+        }
+
+        switch (event.key) {
+            case 'b':
+                if (event.ctrlKey) {
+                    if (event.altKey) {
+                        // toggle right
+                        rightExpander.api.setVisible(
+                            !rightExpander.api.isVisible
+                        );
+                        if (rightExpander.api.width === 0) {
+                            rightExpander.api.setSize({ width: 150 });
+                        }
+                    } else {
+                        // toggle left
+                        leftExpander.api.setVisible(
+                            !leftExpander.api.isVisible
+                        );
+                        if (leftExpander.api.width === 0) {
+                            leftExpander.api.setSize({ width: 150 });
+                        }
+                    }
+                }
+        }
+    };
+
+    return (
+        <div
+            tabIndex={-1}
+            className="simple-gridview-example"
+            onKeyDown={onKeyDown}
+            style={{ height: '100%', display: 'flex', flexDirection: 'column' }}
+        >
+            <div style={{ flexGrow: 1 }}>
+                <GridviewReact
+                    components={components}
+                    onReady={onReady}
+                    hideBorders={true}
+                    orientation={Orientation.VERTICAL}
+                    className={props.theme || 'dockview-theme-abyss'}
+                />
+            </div>
+        </div>
+    );
+};
+
+export default App;

packages/docs/sandboxes/editor-gridview/src/index.tsx

@@ -0,0 +1,20 @@
+import { StrictMode } from 'react';
+import * as ReactDOMClient from 'react-dom/client';
+import './styles.css';
+import 'dockview/dist/styles/dockview.css';
+
+import App from './app';
+
+const rootElement = document.getElementById('root');
+
+if (rootElement) {
+    const root = ReactDOMClient.createRoot(rootElement);
+
+    root.render(
+        <StrictMode>
+            <div className="app">
+                <App />
+            </div>
+        </StrictMode>
+    );
+}

packages/docs/sandboxes/editor-gridview/src/styles.css

@@ -0,0 +1,16 @@
+body {
+  margin: 0px;
+  color: white;
+  font-family: sans-serif;
+  text-align: center;
+}
+
+#root {
+  height: 100vh;
+  width: 100vw;
+}
+
+.app {
+  height: 100%;
+
+}

packages/docs/sandboxes/editor-gridview/tsconfig.json

@@ -0,0 +1,18 @@
+{
+    "compilerOptions": {
+        "outDir": "build/dist",
+        "module": "esnext",
+        "target": "es5",
+        "lib": ["es6", "dom"],
+        "sourceMap": true,
+        "allowJs": true,
+        "jsx": "react-jsx",
+        "moduleResolution": "node",
+        "rootDir": "src",
+        "forceConsistentCasingInFileNames": true,
+        "noImplicitReturns": true,
+        "noImplicitThis": true,
+        "noImplicitAny": true,
+        "strictNullChecks": true
+    }
+}

packages/docs/sandboxes/simple-gridview/src/app.scss

@@ -0,0 +1,3 @@
+.simple-gridview-example {
+    --dv-active-sash-color: #007acc;
+}

packages/docs/src/components/ui/codeSandboxButton.tsx

@@ -32,7 +32,10 @@ const CloseButton = () =>
         path: 'M22.5581 50.9938V30.1717L4.65116 19.869V31.7386L12.8536 36.4939V45.4198L22.5581 50.9938ZM27.2093 51.1162L37.0931 45.4226V36.2851L45.3488 31.501V19.7801L27.2093 30.2529V51.1162ZM42.9633 15.7867L33.4288 10.2615L25.0571 15.1193L16.6219 10.2567L7.00237 15.8557L24.9542 26.1842L42.9633 15.7867ZM0 43.4008V14.5498L24.9974 0L50 14.4887V43.3552L24.9969 57.7584L0 43.4008Z',
     });
 
-export const CodeSandboxButton = (props: { id: string }) => {
+export const CodeSandboxButton = (props: {
+    id: string;
+    hideThemePicker?: boolean;
+}) => {
     const url = React.useMemo(() => {
         if (!props.id) {
             return '';
@@ -42,7 +45,7 @@ export const CodeSandboxButton = (props: { id: string }) => {
 
     return (
         <>
-            <ThemePicker />
+            {!props.hideThemePicker && <ThemePicker />}
             <span
                 className="codesandbox-button"
                 style={{ display: 'flex', alignItems: 'center' }}

packages/docs/src/components/ui/container.tsx

@@ -149,6 +149,7 @@ export const MultiFrameworkContainer2 = (props: {
     typescript?: (parent: HTMLElement) => { dispose: () => void };
     sandboxId: string;
     height?: number;
+    hideThemePicker?: boolean;
 }) => {
     const ref = React.useRef<HTMLDivElement>(null);
 
@@ -266,7 +267,10 @@ export const MultiFrameworkContainer2 = (props: {
                     )}
                 </div>
                 <span style={{ flexGrow: 1 }} />
-                <CodeSandboxButton id={sandboxId} />
+                <CodeSandboxButton
+                    id={sandboxId}
+                    hideThemePicker={props.hideThemePicker}
+                />
             </div>
         </>
     );
@@ -277,6 +281,7 @@ export const MultiFrameworkContainer = (props: {
     typescript?: (parent: HTMLElement) => { dispose: () => void };
     sandboxId: string;
     height?: number;
+    hideThemePicker?: boolean;
 }) => {
     return (
         <BrowserOnly>