rei-mirrors/dockview
1
0
Fork 0
mirror of https://github.com/mathuo/dockview synced 2025-03-09 07:22:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore: docs

Browse Source
This commit is contained in:
mathuo 2023-10-04 20:58:51 +01:00
parent e726b4ab02
commit 03235172a8
No known key found for this signature in database
GPG Key ID: C6EEDEFD6CA07281
16 changed files with 555 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.codesandbox/ci.json
View File

@ -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",

33
packages/docs/blog/2023-10-06-dockview-1.8.4.md Normal file
View File

@ -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

2
packages/docs/docs/components/dockview.mdx
View File

@ -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.

148
packages/docs/docs/components/gridview.mdx
View File

@ -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}
/>

5
packages/docs/docs/theme.mdx
View File

@ -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:

34
packages/docs/sandboxes/demo-dockview/src/app.tsx
View File

@ -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' },
});
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' },
position: { referencePanel: 'panel_3', direction: 'right' },
});
event.api.getPanel('panel_1')!.api.setActive();
console.log(event.api.toJSON());
};
return (

32
packages/docs/sandboxes/editor-gridview/package.json Normal file
View File

@ -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"
]
}

44
packages/docs/sandboxes/editor-gridview/public/index.html Normal file
View File

@ -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>

3
packages/docs/sandboxes/editor-gridview/src/app.scss Normal file
View File

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

213
packages/docs/sandboxes/editor-gridview/src/app.tsx Normal file
View File

@ -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;

20
packages/docs/sandboxes/editor-gridview/src/index.tsx Normal file
View File

@ -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>
);
}

16
packages/docs/sandboxes/editor-gridview/src/styles.css Normal file
View File

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

18
packages/docs/sandboxes/editor-gridview/tsconfig.json Normal file
View File

@ -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
}
}

3
packages/docs/sandboxes/simple-gridview/src/app.scss Normal file
View File

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

7
packages/docs/src/components/ui/codeSandboxButton.tsx
View File

@ -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' }}

7
packages/docs/src/components/ui/container.tsx
View File

@ -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>