diff --git a/packages/docs/blog/2022-10-04-dockview-1.5.2.mdx b/packages/docs/blog/2022-10-04-dockview-1.5.2.mdx new file mode 100644 index 000000000..8d5cfbedb --- /dev/null +++ b/packages/docs/blog/2022-10-04-dockview-1.5.2.mdx @@ -0,0 +1,18 @@ +--- +slug: dockview-1.5.2-release +title: Dockview 1.5.2 +tags: [release] +--- + +import Link from '@docusaurus/Link'; + +# Release Notes + +## 🚀 Features + +## 🛠 Miscs + +- Fix resizing panels via api methods [#157](https://github.com/mathuo/dockview/pull/157) +- Various doc enhancements @ [dockview.dev](https://dockview.dev) + +## 🔥 Breaking changes diff --git a/packages/docs/versioned_docs/version-1.5.2/basics.mdx b/packages/docs/versioned_docs/version-1.5.2/basics.mdx new file mode 100644 index 000000000..91fdcbfd9 --- /dev/null +++ b/packages/docs/versioned_docs/version-1.5.2/basics.mdx @@ -0,0 +1,119 @@ +--- +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 + +asd +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/versioned_docs/version-1.5.2/components/_category_.json b/packages/docs/versioned_docs/version-1.5.2/components/_category_.json new file mode 100644 index 000000000..366718010 --- /dev/null +++ b/packages/docs/versioned_docs/version-1.5.2/components/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Components", + "collapsible": true, + "collapsed": false, + "link": { + "type": "generated-index", + "title": "Components" + } +} \ No newline at end of file diff --git a/packages/docs/versioned_docs/version-1.5.2/components/dockview.mdx b/packages/docs/versioned_docs/version-1.5.2/components/dockview.mdx new file mode 100644 index 000000000..0faa319cf --- /dev/null +++ b/packages/docs/versioned_docs/version-1.5.2/components/dockview.mdx @@ -0,0 +1,377 @@ +--- +description: Dockview Documentation +--- + +import { SimpleDockview } from '@site/src/components/simpleDockview'; +import { + RenderingDockview, + Checkbox, +} from '@site/src/components/dockview/rendering'; +import { DndDockview } from '@site/src/components/dockview/dnd'; +import { EventsDockview } from '@site/src/components/dockview/events'; +import { ContextMenuDockview } from '@site/src/components/dockview/contextMenu'; +import { NestedDockview } from '@site/src/components/dockview/nested'; +import { CustomHeadersDockview } from '@site/src/components/dockview/customHeaders'; +import { ResizeDockview } from '@site/src/components/dockview/resize'; +import Link from '@docusaurus/Link'; + +# Dockview + +## Introduction + +Dockview is an abstraction built on top of [Gridviews](./gridview) where each view is a container of many tabbed panels. + +
+ +
+ +You can access the panels associated group through the `panel.group` variable. +The group will always be defined and will change if a panel is moved into another group. + +## DockviewReact Component + +You can create a Dockview through the use of the `ReactDockview` component. + +```tsx +import { ReactDockview } from 'dockview'; +``` + +| Property | Type | Optional | Default | Description | +| ------------------- | ------------------------------------ | -------- | ------- | ------------------------------------------------------------ | +| onReady | (event: SplitviewReadyEvent) => void | No | | | +| components | object | No | | | +| tabComponents | object | Yes | | | +| watermarkComponent | object | Yes | | | +| hideBorders | boolean | Yes | false | | +| className | string | Yes | '' | | +| disableAutoResizing | boolean | Yes | false | See Auto Resizing | +| onDidDrop | Event | Yes | false | | +| showDndOverlay | Event | Yes | false | | + +## Dockview API + +The Dockview API is exposed both at the `onReady` event and on each panel through `props.containerApi`. +Through this API you can control general features of the component and access all added panels. + +```tsx title="Dockview API via Panel component" +const MyComponent = (props: IDockviewPanelProps<{ title: string }>) => { + // props.containerApi... + + return
{`My first panel has the title: ${props.params.title}`}
; +}; +``` + +```tsx title="Dockview API via the onReady callback" +const onReady = (event: DockviewReadyEvent) => { + // event.api... +}; +``` + +| Property | Type | Description | +| ---------------------- | ---------------------------------------------------- | -------------------------------------------------------- | +| height | `number` | Component pixel height | +| width | `number` | Component pixel width | +| minimumHeight | `number` | | +| maximumHeight | `number` | | +| maximumWidth | `number` | | +| maximumWidth | `number` | | +| length | `number` | Number of panels | +| size | `number` | Number of Groups | +| panels | `IDockviewPanel[]` | | +| groups | `GroupPanel[]` | | +| activePanel | `IDockviewPanel \| undefined` | | +| activeGroup | `IDockviewPanel \| undefined` | | +| | | | +| onDidLayoutChange | `Event` | | +| onDidLayoutFromJSON | `Event` | | +| onDidAddGroup | `Event` | | +| onDidRemoveGroup | `Event` | | +| onDidActiveGroupChange | `Event` | | +| onDidAddPanel | `Event` | | +| onDidRemovePanel | `Event` | | +| onDidActivePanelChange | `Event` | | +| onDidDrop | `EventAuto Resizing | +| fromJSON | `(data: SerializedDockview): void` | Serialization | +| toJSON | `(): SerializedDockview` | Serialization | +| clear | `(): void` | Clears the current layout | + +## Dockview Panel API + +```tsx +const MyComponent = (props: IDockviewPanelProps<{ title: string }>) => { + // props.api... + + return
{`My first panel has the title: ${props.params.title}`}
; +}; +``` + +| Property | Type | Description | +| ---------------------- | ----------------------------------------------------------- | --------------- | +| id | `string` | Panel id | +| isFocused | `boolean` | Is panel focsed | +| isActive | `boolean` | Is panel active | +| width | `number` | Panel width | +| height | `number` | Panel height | +| onDidDimensionsChange | `Event` | | +| onDidFocusChange | `Event` | | +| onDidVisibilityChange | `Event` | | +| onDidActiveChange | `Event` | | +| setActive | `(): void` | | +| | | | +| onDidConstraintsChange | `onDidConstraintsChange: Event` | | +| setConstraints | `(value: PanelConstraintChangeEvent2): void;` | | +| setSize | `(event: SizeEvent): void` | | +| | | | +| group | `GroupPanel | undefined` | +| isGroupActive | `boolean` | | +| title | `string` | | +| suppressClosable | `boolean` | | +| close | `(): void` | | +| setTitle | `(title: string): void` | | + +## Advanced Features + +### Resizing via API + +Each Dockview is comprised of a number of groups, each of which have a number of panels. +Logically most people would want to resize a panel but practically this really translates to resizing the group to which the panel belongs. + +From the api you can access the panels group object (`props.group`) which exposes it's own api object (`props.groups.api`). +This api is largly similar to the Gridview API. + +To resize an individual panel you could create a snippet similar to below. + +```tsx +const onResizePanel = () => { + props.api.group.api.setSize({ + height: 100, + }); +}; +``` + +```tsx +const onResizePanel = () => { + props.api.group.api.setSize({ + width: 100, + }); +}; +``` + +Here is a working example of resizing panels via these API methods. + + + +### Locked group + +Locking a group will disable all drop events for this group ensuring a user can not add additional panels to the group. +You can still add groups to a locked panel programatically using the API. + +```tsx +panel.group.locked = true; +``` + +### Group header + +You may wish to hide the header section of a group. This can achieved through setting the `hidden` variable on `panel.group.header`. + +```tsx +panel.group.header.hidden = true; +``` + +### Custom Tab Headers + +You can provide custom renderers for your tab headers. +A default implementation of `DockviewDefaultTab` is provided should you only wish to attach minor +changes and events that do not alter the default behaviour, for example to add a custom context menu event +handler. + +You are also free to define a custom renderer entirely from scratch and not make use of the `DockviewDefaultTab` component. + +```tsx title="Attaching a custom context menu event handlers to a custom header" +import { IDockviewPanelHeaderProps, DockviewDefaultTab } from 'dockview'; + +const MyCustomheader = (props: IDockviewPanelHeaderProps) => { + const onContextMenu = (event: React.MouseEvent) => { + event.preventDefault(); + alert('context menu'); + }; + return ; +}; +``` + +To use a custom renderer you can must register a collection of tab components + +```tsx +const tabComponents = { + myCustomHeader: MyCustomHeader, +}; + +return ; +``` + +```tsx +api.addPanel({ + id: 'panel_1', + component: 'default', + tabComponent: 'myCustomHeader', // <-- + title: 'Panel 1', +}); +``` + +You can also override the default tab renderer which will be used when no `tabComponent` is provided to the `addPanel` function. + +```tsx +; +``` + +As a simple example the below attachs a custom event handler for the context menu on all tabs as a default tab renderer + + + +### Rendering + +Although `DockviewReact` will only add those tabs that are visible to the DOM all associated React Components for each tab including those that +are not initially visible will be created. +This will mean that any hooks in those components will run and if you running expensive operations in the tabs you may end up doing a lot of initial +work for what are hidden tabs. + +This is the default behaviour to ensure the greatest flexibility for the user but you can create a Higher-Order component wrapping your components that +will ensure the component is only created if the tab is visible as below: + +```tsx +import { PanelApi } from 'dockview'; +import * as React from 'react'; + +function RenderWhenVisible< + T extends { api: Pick } +>(component: React.FunctionComponent) { + const HigherOrderComponent = (props: T) => { + const [visible, setVisible] = React.useState( + props.api.isVisible + ); + + React.useEffect(() => { + const disposable = props.api.onDidVisibilityChange((event) => + setVisible(event.isVisible) + ); + + return () => { + disposable.dispose(); + }; + }, [props.api]); + + if (!visible) { + return null; + } + + return React.createElement(component, props); + }; + return HigherOrderComponent; +} +``` + +```tsx +const component = RenderWhenVisible(MyComponent); +``` + +Through 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. + + +
+ +
+ +### Drag And Drop + +The component exposes some method to help determine whether external drag events should be interacted with or not. + +```tsx +/** + * called when an ondrop event which does not originate from the dockview libray and + * passes the showDndOverlay condition occurs + **/ +const onDidDrop = (event: DockviewDropEvent) => { + const { group } = event; + + event.api.addPanel({ + id: 'test', + component: 'default', + position: { + referencePanel: group.activePanel.id, + direction: 'within', + }, + }); +}; + +/** + * called for drag over events which do not originate from the dockview library + * allowing the developer to decide where the overlay should be shown for a + * particular drag event + **/ +const showDndOverlay = (event: DockviewDndOverlayEvent) => { + return true; +}; + +return ( + +); +``` + + + +### Events + + + +### Nested Dockviews + +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`. + + + +### Group Controls Panel + +`DockviewReact` accepts a prop `groupControlComponent` which expects a React component whos props are `IDockviewGroupControlProps`. +This control will be rendered inside the header bar on the right hand side for each group of tabs. + +```tsx +const Component: React.FunctionComponent = () => { + return
{'...'}
; +}; + +return ; +``` diff --git a/packages/docs/versioned_docs/version-1.5.2/components/gridview.mdx b/packages/docs/versioned_docs/version-1.5.2/components/gridview.mdx new file mode 100644 index 000000000..d531f7fdc --- /dev/null +++ b/packages/docs/versioned_docs/version-1.5.2/components/gridview.mdx @@ -0,0 +1,120 @@ +--- +description: Gridview Documentation +--- + +import { SimpleGridview } from '@site/src/components/simpleGridview'; +import { EventsGridview } from '@site/src/components/gridview/events'; +import Link from '@docusaurus/Link'; + +# Gridview + +## Introduction + +
+ +
+ +## GridviewReact Component + +```tsx +import { ReactGridview } from 'dockview'; +``` + +| Property | Type | Optional | Default | Description | +| ------------------- | ------------------------------------ | -------- | ---------------------- | ------------------------------------------------------------------------ | +| onReady | (event: SplitviewReadyEvent) => void | No | | | +| components | object | No | | | +| orientation | Orientation | Yes | Orientation.HORIZONTAL | | +| proportionalLayout | boolean | Yes | true | See Proportional layout | +| hideBorders | boolean | Yes | false | | +| className | string | Yes | '' | | +| disableAutoResizing | boolean | Yes | false | See Auto Resizing | + +## Gridview API + +```tsx +const MyComponent = (props: IGridviewPanelProps<{ title: string }>) => { + // props.containerApi... + + return
{`My first panel has the title: ${props.params.title}`}
; +}; +``` + +```tsx +const onReady = (event: GridviewReadyEvent) => { + // event.api... +}; +``` + +| Property | Type | Description | +| ---------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| height | `number` | Component pixel height | +| width | `number` | Component pixel width | +| minimumHeight | `number` | | +| maximumHeight | `number` | | +| maximumWidth | `number` | | +| maximumWidth | `number` | | +| length | `number` | Number of panels | +| panels | `ISplitviewPanel[]` | all panels | +| orientation | `Orientation` | | +| | | | +| onDidLayoutChange | `Event` | Fires on layout change | +| onDidLayoutFromJSON | `Event` | Fires of layout change caused by a fromJSON deserialization call | +| onDidAddPanel | `Event` | Fires when a view is added | +| onDidRemovePanel | `Event` | Fires when a view is removed | +| onDidActivePanelChange | `Event` | Fires when the active group changes | +| | | | +| addPanel | `addPanel(options: AddComponentOptions): IGridviewPanel` | | +| removePanel | `(panel: IGridviewPanel, sizing?: Sizing): void` | | +| movePanel | `(panel: IGridviewPanel, options: {direction: Direction, refernece:string, size?: number}): void` | | +| getPanel | `(id: string) \| IGridviewPanel \| undefined` | | +| | | | +| updateOptions | `(options:SplitviewComponentUpdateOptions): void` | | +| focus | `(): void` | Focus the active panel, if exists | +| layout | `(width: number, height:number): void` | Auto Resizing | +| fromJSON | `(data: SerializedGridview): void` | Serialization | +| toJSON | `(): SerializedGridview` | Serialization | +| clear | `(): void` | Clears the current layout | + +## Gridview Panel API + +```tsx +const MyComponent = (props: IGridviewPanelProps<{ title: string }>) => { + // props.api... + + return
{`My first panel has the title: ${props.params.title}`}
; +}; +``` + +| Property | Type | Description | +| ---------------------- | ----------------------------------------------------------- | ---------------- | +| id | `string` | Panel id | +| isFocused | `boolean` | Is panel focsed | +| isActive | `boolean` | Is panel active | +| isVisible | `boolean` | Is panel visible | +| width | `number` | Panel width | +| height | `number` | Panel height | +| | | | +| onDidDimensionsChange | `Event` | | +| onDidFocusChange | `Event` | | +| onDidVisibilityChange | `Event` | | +| onDidActiveChange | `Event` | | +| onDidConstraintsChange | `onDidConstraintsChange: Event` | | +| | | | +| setVisible | `(isVisible: boolean): void` | | +| setActive | `(): void` | | +| setConstraints | `(value: PanelConstraintChangeEvent2): void;` | | +| setSize | `(event: SizeEvent): void` | | + +## Events + +`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. + + diff --git a/packages/docs/versioned_docs/version-1.5.2/components/paneview.mdx b/packages/docs/versioned_docs/version-1.5.2/components/paneview.mdx new file mode 100644 index 000000000..87efc8eaa --- /dev/null +++ b/packages/docs/versioned_docs/version-1.5.2/components/paneview.mdx @@ -0,0 +1,285 @@ +--- +description: Paneview Documentation +--- + +import { SimplePaneview } from '@site/src/components/simplePaneview'; +import { CustomHeaderPaneview } from '@site/src/components/paneview/customHeader'; +import { DragAndDropPaneview } from '@site/src/components/paneview/dragAndDrop'; +import { SideBySidePaneview } from '@site/src/components/paneview/sideBySide'; +import Link from '@docusaurus/Link'; + +# Paneview + +A paneview is a collapsed collection of vertically stacked panels and panel headers. +The panel header will always remain visible however the panel will only be visible when the panel is expanded. + +:::info + +Paneview panels can be re-ordered by dragging and dropping the panel headers. + +::: + +--- + +# Introduction + +
+ +
+ +```tsx title="Simple Paneview example" +import { + IPaneviewPanelProps, + PaneviewReact, + PaneviewReadyEvent, +} from 'dockview'; + +const components = { + default: (props: IPaneviewPanelProps<{ title: string }>) => { + return ( +
+ {props.params.title} +
+ ); + }, +}; + +SimplePaneview = () => { + const onReady = (event: PaneviewReadyEvent) => { + event.api.addPanel({ + id: 'panel_1', + component: 'default', + params: { + title: 'Panel 1', + }, + title: 'Panel 1', + }); + + event.api.addPanel({ + id: 'panel_2', + component: 'default', + params: { + title: 'Panel 2', + }, + title: 'Panel 2', + }); + + event.api.addPanel({ + id: 'panel_3', + component: 'default', + params: { + title: 'Panel 3', + }, + title: 'Panel 3', + }); + }; + + return ( + + ); +}; +``` + +## PaneviewReact Component + +You can create a Paneview through the use of the `ReactPaneview` component. + +```tsx +import { ReactPaneview } from 'dockview'; +``` + +| Property | Type | Optional | Default | Description | +| ------------------- | ------------------------------------ | -------- | ------- | -------------------------------------------------------- | +| onReady | (event: SplitviewReadyEvent) => void | No | | | +| components | object | No | | | +| headerComponents | object | Yes | | | +| className | string | Yes | '' | | +| disableAutoResizing | boolean | Yes | false | Auto Resizing | +| disableDnd | boolean | Yes | false | | +| onDidDrop | Event | Yes | | | + +## Paneview API + +The Paneview API is exposed both at the `onReady` event and on each panel through `props.containerApi`. +Through this API you can control general features of the component and access all added panels. + +```tsx title="Paneview API via Panel component" +const MyComponent = (props: IGridviewPanelProps<{ title: string }>) => { + // props.containerApi... + + return
{`My first panel has the title: ${props.params.title}`}
; +}; +``` + +```tsx title="Paneview API via the onReady callback" +const onReady = (event: GridviewReadyEvent) => { + // event.api... +}; +``` + +| Property | Type | Description | +| ------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| height | `number` | Component pixel height | +| width | `number` | Component pixel width | +| minimumSize | `number` | The sum of the `minimumSize` property for each panel | +| maximumSize | `number` | The sum of the `maximumSize` property for each panel | +| length | `number` | Number of panels | +| panels | `IPaneviewPanel[]` | All panels | +| | | | +| onDidLayoutChange | `Event` | Fires on layout change | +| onDidLayoutFromJSON | `Event` | Fires of layout change caused by a fromJSON deserialization call | +| onDidAddView | `Event` | Fires when a view is added | +| onDidRemoveView | `Event` | Fires when a view is removed | +| onDidDrop | `EventDrag and Drop) | +| | | | +| addPanel | `addPanel(options: AddPaneviewComponentOptions): IPaneviewPanel` | | +| removePanel | `(panel: IPaneviewPanel): void` | | +| movePanel | `(from: number, to: number): void` | | +| getPanel | `(id:string): IPaneviewPanel \| undefined` | | +| | | | +| focus | `(): void` | Focus the active panel, if exists | +| layout | `(width: number, height:number): void` | See Auto Resizing | +| fromJSON | `(data: SerializedPaneview): void` | Serialization | +| toJSON | `(): SerializedPaneview` | Serialization | +| clear | `(): void` | Clears the current layout | + +## Paneview Panel API + +```tsx +const MyComponent = (props: IGridviewPanelProps<{ title: string }>) => { + // props.api... + + return
{`My first panel has the title: ${props.params.title}`}
; +}; +``` + +| Property | Type | Description | +| ---------------------- | ----------------------------------------------------------- | ---------------- | +| id | `string` | Panel id | +| isFocused | `boolean` | Is panel focsed | +| isActive | `boolean` | Is panel active | +| isVisible | `boolean` | Is panel visible | +| width | `number` | Panel width | +| height | `number` | Panel height | +| | | +| onDidDimensionsChange | `Event` | | +| onDidFocusChange | `Event` | | +| onDidVisibilityChange | `Event` | | +| onDidActiveChange | `Event` | | +| onDidConstraintsChange | `onDidConstraintsChange: Event` | | +| | | +| setVisible | `(isVisible: boolean): void` | | +| setActive | `(): void` | | +| setConstraints | `(value: PanelConstraintChangeEvent2): void;` | | +| setSize | `(event: SizeEvent): void` | | + +## Advanced Features + +### Custom Header + +You can provide a custom component to render an alternative header. + +
+ +
+ +You can provide a `headerComponent` option when creating a panel to tell the library to use a custom header component. + +```tsx +const onReady = (event: PaneviewReadyEvent) => { + event.api.addPanel({ + id: 'panel_1', + component: 'default', + headerComponent: 'myHeaderComponent', + params: { + valueA: 'A', + }, + title: 'Panel 1', + }); +}; +``` + +This header must be defined in the collection of components provided to the `headerComponents` props for `ReactPaneivew` + +```tsx +import { IPaneviewPanelProps } from 'dockview'; + +const MyHeaderComponent = (props: IPaneviewPanelProps<{ title: string }>) => { + const [expanded, setExpanded] = React.useState( + props.api.isExpanded + ); + + React.useEffect(() => { + const disposable = props.api.onDidExpansionChange((event) => { + setExpanded(event.isExpanded); + }); + + return () => { + disposable.dispose(); + }; + }, []); + + const onClick = () => { + props.api.setExpanded(!expanded); + }; + + return ( + + ); +}; + +const headerComponents = { myHeaderComponent: MyHeaderComponent }; +``` + +### Drag And Drop + +If you provide the `PaneviewReact` component with the prop `onDidDrop` you will be able to interact with custom drop events. + + + +### Interactions + +You can safely create multiple paneview instances within one page. They will not interact with each other by default. + +If you wish to interact with the drop event from one paneview instance in another paneview instance you can implement the `showDndOverlay` and `onDidDrop` props on `PaneviewReact`. + +As an example see how dragging a header from one control to another will only trigger an interactable event for the developer if the checkbox is enabled. + + diff --git a/packages/docs/versioned_docs/version-1.5.2/components/splitview.mdx b/packages/docs/versioned_docs/version-1.5.2/components/splitview.mdx new file mode 100644 index 000000000..a32e6d5a2 --- /dev/null +++ b/packages/docs/versioned_docs/version-1.5.2/components/splitview.mdx @@ -0,0 +1,246 @@ +--- +description: Splitview Documentation +--- + +import { SimpleSplitview } from '@site/src/components/simpleSplitview'; +import { SplitviewExample1 } from '@site/src/components/splitview/active'; +import Link from '@docusaurus/Link'; + +# Splitview + +## Introduction + +A Splitview is a collection of resizable horizontally or vertically stacked panels. + +
+ +
+ +```tsx title="Simple Splitview example" +import { + ISplitviewPanelProps, + Orientation, + SplitviewReact, + SplitviewReadyEvent, +} from 'dockview'; + +const components = { + default: (props: ISplitviewPanelProps<{ title: string }>) => { + return
{props.params.title}
; + }, +}; + +export const SimpleSplitview = () => { + const onReady = (event: SplitviewReadyEvent) => { + event.api.addPanel({ + id: 'panel_1', + component: 'default', + params: { + title: 'Panel 1', + }, + }); + + event.api.addPanel({ + id: 'panel_2', + component: 'default', + params: { + title: 'Panel 2', + }, + }); + + event.api.addPanel({ + id: 'panel_3', + component: 'default', + params: { + title: 'Panel 3', + }, + }); + }; + + return ( + + ); +}; +``` + +## SplitviewReact Component + +You can create a Splitview through the use of the `ReactSplitview` component. + +```tsx +import { ReactSplitview } from 'dockview'; +``` + +Using the `onReady` prop you can access to the component `api` and add panels either through deserialization or the individual addition of panels. + +| Property | Type | Optional | Default | Description | +| ------------------- | -------------------------------------- | -------- | ------------------------ | ------------------------------------------------------------------------ | +| onReady | `(event: SplitviewReadyEvent) => void` | No | | Function | +| components | `Record` | No | | Panel renderers | +| orientation | `Orientation` | Yes | `Orientation.HORIZONTAL` | Orientation of the Splitview | +| proportionalLayout | `boolean` | Yes | `true` | See Proportional layout | +| hideBorders | `boolean` | Yes | `false` | Hide the borders between panels | +| className | `string` | Yes | `''` | Attaches a classname | +| disableAutoResizing | `boolean` | Yes | `false` | See Auto Resizing | + +## Splitview API + +The Splitview API is exposed both at the `onReady` event and on each panel through `props.containerApi`. +Through this API you can control general features of the component and access all added panels. + +```tsx title="Splitview API via Panel component" +const MyComponent = (props: ISplitviewPanelProps<{ title: string }>) => { + // props.containerApi... + + return
{`My first panel has the title: ${props.params.title}`}
; +}; +``` + +```tsx title="Splitview API via the onReady callback" +const onReady = (event: SplitviewReadyEvent) => { + // event.api... +}; +``` + +| Property | Type | Description | +| ------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------- | +| height | `number` | Component pixel height | +| width | `number` | Component pixel width | +| minimumSize | `number` | The sum of the `minimumSize` property for each panel | +| maximumSize | `number` | The sum of the `maximumSize` property for each panel | +| length | `number` | Number of panels | +| panels | `ISplitviewPanel[]` | All panels | +| | | | +| onDidLayoutChange | `Event` | Fires on layout change | +| onDidLayoutFromJSON | `Event` | Fires of layout change caused by a fromJSON deserialization call | +| onDidAddView | `Event` | Fires when a view is added | +| onDidRemoveView | `Event` | Fires when a view is removed | +| | | | +| addPanel | `addPanel(options: AddSplitviewComponentOptions): ISplitviewPanel` | | +| removePanel | `(panel: ISplitviewPanel, sizing?: Sizing): void` | | +| getPanel | `(id:string): ISplitviewPanel \| undefined` | | +| movePanel | `(from: number, to: number): void` | | +| | | +| updateOptions | `(options: SplitviewComponentUpdateOptions): void` | | +| focus | `(): void` | Focus the active panel, if exists | +| layout | `(width: number, height:number): void` | See Auto Resizing | +| fromJSON | `(data: SerializedSplitview): void` | Serialization | +| toJSON | `(): SerializedSplitview` | Serialization | +| clear | `(): void` | Clears the current layout | + +## Splitview Panel API + +The Splitview panel API is exposed on each panel containing actions and variables specific to that panel. + +```tsx title="Splitview panel API via Panel component" +const MyComponent = (props: ISplitviewPanelProps<{ title: string }>) => { + // props.api... + + return
{`My first panel has the title: ${props.params.title}`}
; +}; +``` + +| Property | Type | Description | +| ---------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | +| id | `string` | Panel id | +| isFocused | `boolean` | Is panel focsed | +| isActive | `boolean` | Is panel active | +| isVisible | `boolean` | Is panel visible | +| width | `number` | Panel width | +| height | `number` | Panel height | +| | | | +| onDidDimensionsChange | `Event` | Fires when panel dimensions change | +| onDidFocusChange | `Event` | Fire when panel is focused and blurred | +| onDidVisibilityChange | `Event` | Fires when the panels visiblity property is changed (see Panel Visibility) | +| onDidActiveChange | `Event` | Fires when the panels active property is changed (see Active Panel) | +| onDidConstraintsChange | `onDidConstraintsChange: Event` | Fires when the panels size contrainsts change (see Panel Constraints) | +| | | | +| setVisible | `(isVisible: boolean): void` | | +| setActive | `(): void` | | +| | | | +| setConstraints | `(value: PanelConstraintChangeEvent2): void;` | | +| setSize | `(event: PanelSizeEvent): void` | | + +## Advanced Features + +Listed below are some functionalities avalaible through both the panel and component APIs. The live demo shows examples of these in real-time. + +
+ +
+ +### Visibility + +A panels visibility can be controlled and monitored through the following code. +A panel with visibility set to `false` will remain as a part of the components list of panels but will not be rendered. + +```tsx +const disposable = props.api.onDidVisibilityChange(({ isVisible }) => { + // +}); +``` + +```tsx +api.setVisible(true); +``` + +### Active + +Only one panel in the `splitview` can be the active panel at any one time. +Setting a panel as active will set all the others as inactive. +A focused panel is always the active panel but an active panel is not always focused. + +```tsx +const disposable = props.api.onDidActiveChange(({ isActive }) => { + // +}); +``` + +```tsx +api.setActive(); +``` + +### Contraints + +When adding a panel you can specify pixel size contraints + +```tsx +event.api.addPanel({ + id: 'panel_3', + component: 'default', + minimumSize: 100, + maximumSize: 1000, +}); +``` + +These contraints can be updated throughout the lifecycle of the `splitview` using the panel API + +```tsx +props.api.onDidConstraintsChange(({ maximumSize, minimumSize }) => { + // +}); +``` + +```tsx +api.setConstraints({ + maximumSize: 200, + minimumSize: 400, +}); +``` diff --git a/packages/docs/versioned_docs/version-1.5.2/examples.mdx b/packages/docs/versioned_docs/version-1.5.2/examples.mdx new file mode 100644 index 000000000..e608a2378 --- /dev/null +++ b/packages/docs/versioned_docs/version-1.5.2/examples.mdx @@ -0,0 +1,25 @@ +--- +sidebar_position: 4 +description: Dockview examples +--- + +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/src/components/simpleDockview'; + +# Examples + + diff --git a/packages/docs/versioned_docs/version-1.5.2/index.mdx b/packages/docs/versioned_docs/version-1.5.2/index.mdx new file mode 100644 index 000000000..12068f080 --- /dev/null +++ b/packages/docs/versioned_docs/version-1.5.2/index.mdx @@ -0,0 +1,149 @@ +--- +sidebar_position: 0 +description: A zero dependency layout manager built for React +--- + +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/src/components/simpleDockview'; + +# 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: + +```shell +npm install dockview +``` + +You must also import the dockview stylesheet found under [`dockview/dict/styles/dockview.css`](https://unpkg.com/browse/dockview@latest/dist/styles/dockview.css), +depending on your solution this might be: + +```css +@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 + +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +```tsx +import { + DockviewReact, + DockviewReadyEvent, + PanelCollection, + IDockviewPanelProps, + IDockviewPanelHeaderProps, +} from 'dockview'; + +const components: PanelCollection = { + default: (props: IDockviewPanelProps<{ someProps: string }>) => { + return
{props.params.someProps}
; + }, +}; + +const headers: PanelCollection = { + customTab: (props: IDockviewPanelHeaderProps) => { + return ( +
+ {props.api.title} + props.api.close()}>{'[x]'} +
+ ); + }, +}; + +const Component = () => { + const onReady = (event: DockviewReadyEvent) => { + event.api.addPanel({ + id: 'panel1', + component: 'default', + tabComponent: 'customTab', // optional custom header + params: { + someProps: 'Hello', + }, + }); + event.api.addPanel({ + id: 'panel2', + component: 'default', + params: { + someProps: 'World', + }, + position: { referencePanel: 'panel1', direction: 'below' }, + }); + }; + + return ( + + ); +}; +``` diff --git a/packages/docs/versioned_docs/version-1.5.2/theme.mdx b/packages/docs/versioned_docs/version-1.5.2/theme.mdx new file mode 100644 index 000000000..bd770f5d7 --- /dev/null +++ b/packages/docs/versioned_docs/version-1.5.2/theme.mdx @@ -0,0 +1,89 @@ +--- +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 + +```css +@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-theme-light` +- `.dockview-theme-dark` +- `.dockview-theme-abyss` + +## Customizing Theme + +`dockview` supports theming through the use of css properties. +You can view the built-in themes at [`dockview/src/theme.scss`](https://github.com/mathuo/dockview/blob/master/packages/dockview/src/theme.scss) +and are free to build your own themes based on these css properties. + +| CSS Property | Description | +| ---------------------------------------------------- | ----------- | +| --dv-paneview-active-outline-color | | +| --dv-tabs-and-actions-container-font-size | | +| --dv-tabs-and-actions-container-height | | +| --dv-tab-close-icon | | +| --dv-drag-over-background-color | | +| --dv-drag-over-border-color | | +| --dv-tabs-container-scrollbar-color | | +| | | +| --dv-group-view-background-color | | +| | | +| --dv-tabs-and-actions-container-background-color | | +| | | +| --dv-activegroup-visiblepanel-tab-background-color | | +| --dv-activegroup-hiddenpanel-tab-background-color | | +| --dv-inactivegroup-visiblepanel-tab-background-color | | +| --dv-inactivegroup-hiddenpanel-tab-background-color | | +| --dv-tab-divider-color | | +| | | +| --dv-activegroup-visiblepanel-tab-color | | +| --dv-activegroup-hiddenpanel-tab-color | | +| --dv-inactivegroup-visiblepanel-tab-color | | +| --dv-inactivegroup-hiddenpanel-tab-color | | +| | | +| --dv-separator-border | | +| --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: + +```css +.groupview { + &.active-group { + > .tabs-and-actions-container { + border-bottom: 2px solid var(--dv-activegroup-visiblepanel-tab-background-color); + } + } + &.inactive-group { + > .tabs-and-actions-container { + border-bottom: 2px solid var(--dv-inactivegroup-visiblepanel-tab-background-color); + } + } +} +``` + +
+ +
diff --git a/packages/docs/versioned_sidebars/version-1.5.2-sidebars.json b/packages/docs/versioned_sidebars/version-1.5.2-sidebars.json new file mode 100644 index 000000000..caea0c03b --- /dev/null +++ b/packages/docs/versioned_sidebars/version-1.5.2-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/packages/docs/versions.json b/packages/docs/versions.json index c61065a6c..038f63a4a 100644 --- a/packages/docs/versions.json +++ b/packages/docs/versions.json @@ -1,4 +1,5 @@ [ + "1.5.2", "1.5.1", "1.5.0", "1.4.3"