chore: docs

Author: mathuo

packages/docs/docs/core/overview.mdx

@@ -5,9 +5,7 @@ sidebar_position: 0
 
 This section provided a core overview.
 
-
-After creating an instance of the component you will want to obtain a reference to the [API](/docs/api/dockview/overview)
-object which will facilitate further interactions with the component.
+Once you have created an dock you will want to store a reference to the [API](/docs/api/dockview/overview).
 
 <FrameworkSpecific framework='React'>
 ```tsx

packages/docs/docs/core/panels/add.mdx

@@ -3,8 +3,18 @@ title: Add Panel
 sidebar_position: 1
 ---
 
+import { DocRef } from '@site/src/components/ui/reference/docRef';
+
 This section describes how to add a new panel.
 
+## API
+
+The API associated with opening a panel
+
+<DocRef declaration="DockviewApi" methods={['addPanel']} />
+
+## Open a panel
+
 Using the dockview API you can access the `addPanel` method which returns an instance of the created panel.
 The minimum method signature is:
 

packages/docs/docs/core/panels/register.mdx

@@ -3,19 +3,30 @@ title: Register A Panel
 sidebar_position: 0
 ---
 
-This section describes how to register a panel for later use.
+This section describes how to register a panel.
 
-The render implementation of the panel is linked to a key that can be referenced later on.
-A collection of panels can be provided through the `components` option.
+You can register panes through the `components` option.
 
 <FrameworkSpecific framework='React'>
-```tsx
-const components = {
-  my_component: (props: IDockviewPanelProps) => {
+```jsx
+<DockviewReact components={{
+  component_1: (props: IDockviewPanelProps) => {
+    const api: DockviewPanelApi  = props.api;
+    const containerApi: DockviewApi  = props.containerApi;
+
+    return <div>{/** logic */}</div>
+  },
+  component_2: (props: IDockviewPanelProps) => {
     return <div>{/** logic */}</div>
   }
-}
-
-<DockviewReact components={components}/>
+}}/>
 ```
 </FrameworkSpecific>
+
+
+Each panel has an [API](/docs/api/dockview/panelApi) which can be used to control the panel and you can
+also has access the dock [API](/docs/api/dockview/overview) directly from the panel.
+
+It is expected you should be able to achieve everything you need through these two APIs. If you find yourself
+building work-arounds to accommodate requires please raise an [Issue](https://github.com/mathuo/dockview/issues)
+to see if it's something that could be added.

packages/docs/docs/core/panels/update.mdx

@@ -3,6 +3,20 @@ title: Update Panel
 sidebar_position: 2
 ---
 
+import { DocRef } from '@site/src/components/ui/reference/docRef';
+
+This section describes how to update the parameters of a panel.
+
+:::warning
+**Use this feature sparingly**: Anything you assign to the `params` options of a panel will be persisted.
+Only use this to store small amounts of static view data.
+**Do not** use this to pass application state.
+:::
+
+## Panel API
+
+<DocRef declaration="DockviewPanelApi" methods={['updateParameters']} />
+
 ## Update Panel
 
 You can programatically update the `params` passed through to the panel through the panal api using `api.updateParameters`.

packages/docs/src/components/ui/reference/docRef.tsx

@@ -4,6 +4,7 @@ import './docRef.scss';
 
 export interface DocRefProps {
     declaration: string;
+    methods?: string[];
 }
 
 import docsJson from '../../../generated/api.output.json';
@@ -87,6 +88,10 @@ export const DocRef = (props: DocRefProps) => {
         <table className="doc-ref-table">
             <tbody>
                 {docs.map((doc) => {
+                    if (props.methods && !props.methods.includes(doc.name)) {
+                        return null;
+                    }
+
                     return (
                         <tr>
                             <th

packages/docs/src/css/custom.scss

@@ -13,6 +13,9 @@
 :root {
     --ifm-font-weight-bold: 600;
 
+    --ifm-alert-padding-vertical: 8px;
+    --ifm-alert-padding-horizontal: 8px;
+
     --ifm-color-primary: #21222c;
     --ifm-color-primary-dark: #1e1f28;
     --ifm-color-primary-darker: #1c1d25;
@@ -112,6 +115,22 @@
 
         tr {
             background-color: inherit !important;
+
+            &:last-child {
+                border-bottom: var(--ifm-table-border-width) solid
+                    var(--ifm-table-border-color);
+            }
+        }
+    }
+
+    code {
+        .token {
+            &.maybe-class-name {
+                color: #cf8cff;
+            }
+            &.keyword {
+                color: rgb(130, 170, 255);
+            }
         }
     }
 }
@@ -211,3 +230,19 @@
             var(--ifm-transition-timing-default);
     }
 }
+
+.toc-display {
+    display: none;
+}
+
+@media (min-width: 1500px) {
+    .toc-display {
+        display: block;
+    }
+}
+
+.theme-admonition {
+    border: none;
+    display: flex;
+    padding: 8px 16px;
+}

packages/docs/src/theme/Admonition/Icon/Danger.js

@@ -0,0 +1,11 @@
+import React from 'react';
+export default function AdmonitionIconDanger(props) {
+  return (
+    <svg viewBox="0 0 12 16" {...props}>
+      <path
+        fillRule="evenodd"
+        d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"
+      />
+    </svg>
+  );
+}

packages/docs/src/theme/Admonition/Icon/Info.js

@@ -0,0 +1,11 @@
+import React from 'react';
+export default function AdmonitionIconInfo(props) {
+  return (
+    <svg viewBox="0 0 14 16" {...props}>
+      <path
+        fillRule="evenodd"
+        d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"
+      />
+    </svg>
+  );
+}

packages/docs/src/theme/Admonition/Icon/Note.js

@@ -0,0 +1,11 @@
+import React from 'react';
+export default function AdmonitionIconNote(props) {
+  return (
+    <svg viewBox="0 0 14 16" {...props}>
+      <path
+        fillRule="evenodd"
+        d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"
+      />
+    </svg>
+  );
+}

packages/docs/src/theme/Admonition/Icon/Tip.js

@@ -0,0 +1,11 @@
+import React from 'react';
+export default function AdmonitionIconTip(props) {
+  return (
+    <svg viewBox="0 0 12 16" {...props}>
+      <path
+        fillRule="evenodd"
+        d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"
+      />
+    </svg>
+  );
+}

packages/docs/src/theme/Admonition/Icon/Warning.js

@@ -0,0 +1,11 @@
+import React from 'react';
+export default function AdmonitionIconCaution(props) {
+  return (
+    <svg viewBox="0 0 16 16" {...props}>
+      <path
+        fillRule="evenodd"
+        d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"
+      />
+    </svg>
+  );
+}

packages/docs/src/theme/Admonition/Layout/index.js

@@ -0,0 +1,40 @@
+import React from 'react';
+import clsx from 'clsx';
+import { ThemeClassNames } from '@docusaurus/theme-common';
+import styles from './styles.module.css';
+function AdmonitionContainer({ type, className, children }) {
+    return (
+        <div
+            className={clsx(
+                ThemeClassNames.common.admonition,
+                ThemeClassNames.common.admonitionType(type),
+                styles.admonition,
+                className
+            )}
+        >
+            {children}
+        </div>
+    );
+}
+function AdmonitionHeading({ icon, title }) {
+    return (
+        <div className={styles.admonitionHeading}>
+            <span className={styles.admonitionIcon}>{icon}</span>
+            {/* {title} */}
+        </div>
+    );
+}
+function AdmonitionContent({ children }) {
+    return children ? (
+        <div className={styles.admonitionContent}>{children}</div>
+    ) : null;
+}
+export default function AdmonitionLayout(props) {
+    const { type, icon, title, children, className } = props;
+    return (
+        <AdmonitionContainer type={type} className={className}>
+            <AdmonitionHeading title={title} icon={icon} />
+            <AdmonitionContent>{children}</AdmonitionContent>
+        </AdmonitionContainer>
+    );
+}

packages/docs/src/theme/Admonition/Layout/styles.module.css

@@ -0,0 +1,35 @@
+.admonition {
+  margin-bottom: 1em;
+}
+
+.admonitionHeading {
+  font: var(--ifm-heading-font-weight) var(--ifm-h5-font-size) /
+    var(--ifm-heading-line-height) var(--ifm-heading-font-family);
+  text-transform: uppercase;
+}
+
+/* Heading alone without content (does not handle fragment content) */
+.admonitionHeading:not(:last-child) {
+  margin-bottom: 0.3rem;
+}
+
+.admonitionHeading code {
+  text-transform: none;
+}
+
+.admonitionIcon {
+  display: inline-block;
+  vertical-align: middle;
+  margin-right: 0.4em;
+}
+
+.admonitionIcon svg {
+  display: inline-block;
+  height: 1.6em;
+  width: 1.6em;
+  fill: var(--ifm-alert-foreground-color);
+}
+
+.admonitionContent > :last-child {
+  margin-bottom: 0;
+}

packages/docs/src/theme/Admonition/Type/Caution.js

@@ -0,0 +1,28 @@
+import React from 'react';
+import clsx from 'clsx';
+import Translate from '@docusaurus/Translate';
+import AdmonitionLayout from '@theme/Admonition/Layout';
+import IconWarning from '@theme/Admonition/Icon/Warning';
+const infimaClassName = 'alert alert--warning';
+const defaultProps = {
+  icon: <IconWarning />,
+  title: (
+    <Translate
+      id="theme.admonition.caution"
+      description="The default label used for the Caution admonition (:::caution)">
+      caution
+    </Translate>
+  ),
+};
+// TODO remove before v4: Caution replaced by Warning
+// see https://github.com/facebook/docusaurus/issues/7558
+export default function AdmonitionTypeCaution(props) {
+  return (
+    <AdmonitionLayout
+      {...defaultProps}
+      {...props}
+      className={clsx(infimaClassName, props.className)}>
+      {props.children}
+    </AdmonitionLayout>
+  );
+}

packages/docs/src/theme/Admonition/Type/Danger.js

@@ -0,0 +1,26 @@
+import React from 'react';
+import clsx from 'clsx';
+import Translate from '@docusaurus/Translate';
+import AdmonitionLayout from '@theme/Admonition/Layout';
+import IconDanger from '@theme/Admonition/Icon/Danger';
+const infimaClassName = 'alert alert--danger';
+const defaultProps = {
+  icon: <IconDanger />,
+  title: (
+    <Translate
+      id="theme.admonition.danger"
+      description="The default label used for the Danger admonition (:::danger)">
+      danger
+    </Translate>
+  ),
+};
+export default function AdmonitionTypeDanger(props) {
+  return (
+    <AdmonitionLayout
+      {...defaultProps}
+      {...props}
+      className={clsx(infimaClassName, props.className)}>
+      {props.children}
+    </AdmonitionLayout>
+  );
+}

packages/docs/src/theme/Admonition/Type/Info.js

@@ -0,0 +1,26 @@
+import React from 'react';
+import clsx from 'clsx';
+import Translate from '@docusaurus/Translate';
+import AdmonitionLayout from '@theme/Admonition/Layout';
+import IconInfo from '@theme/Admonition/Icon/Info';
+const infimaClassName = 'alert alert--info';
+const defaultProps = {
+  icon: <IconInfo />,
+  title: (
+    <Translate
+      id="theme.admonition.info"
+      description="The default label used for the Info admonition (:::info)">
+      info
+    </Translate>
+  ),
+};
+export default function AdmonitionTypeInfo(props) {
+  return (
+    <AdmonitionLayout
+      {...defaultProps}
+      {...props}
+      className={clsx(infimaClassName, props.className)}>
+      {props.children}
+    </AdmonitionLayout>
+  );
+}