Update docs for v0.28: (#1)

* Write a proper "concept" pages for graph model, data provider,
event system, command history and workspace context;
* Add "concept" pages for the design system and i18n;
* Provide info on styling in the "component" doc pages;
* Add example for getting a `CanvasApi` instance;
* Add example for opening the `ConnectionsMenu``;
* Add example for the `InstancesSearch``;
* Add example for the `Navigator``;
* Add example for custom search section for `UnifiedSearch`;
* Separate `Rdf` playground into `RDF Explorer` and `Graph Authoring`;
* Fix styles for layout panels;
* Change docs status sign from alpha to beta;
* Update `ExampleMetadata` for the next version;
* Use "reactodia.github.io" to fetch example graph (org ontology);
* Use source map loader to include resolve Reactodia source in the debugger;
* Update dependency to @reactodia/[email protected].

Author: AlexeyMz

docs/components/canvas.md

@@ -2,31 +2,63 @@
 title: Canvas
 ---
 
-# Canvas Components
+# Canvas and widgets
 
 [Canvas](/docs/api/workspace/functions/Canvas) is a main component to display a scrollable canvas for the diagram with [elements](/docs/concepts/graph-model.md), [links](/docs/concepts/graph-model.md) and additional widgets.
 
-## Hooks
+## Getting the canvas instance
 
-[useCanvas()](/docs/api/workspace/functions/useCanvas) hook called from a canvas widget, [SharedCanvasState.findAnyCanvas()](/docs/api/workspace/classes/SharedCanvasState.md#findanycanvas) or [SharedCanvasState.findAllCanvases()](/docs/api/workspace/classes/SharedCanvasState.md#findallcanvases) methods can be used to get the [CanvasApi](/docs/api/workspace/interfaces/CanvasApi) instance to read or subscribe to the canvas state or perform viewport-related effects.
+[useCanvas()](/docs/api/workspace/functions/useCanvas) hook called from a canvas widget can be used to get the [CanvasApi](/docs/api/workspace/interfaces/CanvasApi) instance from a context to read or subscribe to the canvas state or perform viewport-related effects:
+
+```ts
+function MyWidget() {
+  const {canvas} = Reactodia.useCanvas();
+  // Use canvas here
+}
+```
+
+Alternatively, with [SharedCanvasState.findAnyCanvas()](/docs/api/workspace/classes/SharedCanvasState.md#findanycanvas) or [SharedCanvasState.findAllCanvases()](/docs/api/workspace/classes/SharedCanvasState.md#findallcanvases) methods it is possible to get canvas instance outside the canvas component:
+
+```ts
+function NonWidgetComponent {
+  const {view} = React.useWorkspace();
+
+  const canvas = view.findAnyCanvas();
+  if (canvas) {
+    // Use canvas here (could be any if there are several of them)
+  }
+
+  for (const canvas of view.findAllCanvases()) {
+    // Use each canvas mounted in the workspace
+  }
+}
+```
 
 ## Canvas widgets
 
-To define a custom canvas widget, the target React component should be marked by [defineCanvasWidget()](/docs/api/workspace/functions/defineCanvasWidget) function to define its attachment layer.
+Canvas widget is an instance of any React component type which is marked by [defineCanvasWidget()](/docs/api/workspace/functions/defineCanvasWidget) function with metadata such as its attachment layer i.e. where the component should be displayed in relation to other canvas content.
+
+There are multiple canvas layers to place widgets on, from top one to the bottom:
+
+| Layer name     | [Coordinate type](/docs/concepts/canvas-coordinates.md) | Description |
+|----------------|-------------------|-------------|
+| `viewport`     | client (viewport) | Topmost layer, does not scale or scroll with the diagram. |
+| `overElements` | paper             | Displayed over both elements and links, scales and scrolls with the diagram. |
+| `overLinks`    | paper             | Displayed under elements but over links, scales and scrolls with the diagram. |
 
 ### Example: custom viewport widget
 
 ```tsx live noInline
 function CustomSelectAllWidget() {
   const {model} = Reactodia.useWorkspace();
   return (
-    <div style={{position: 'absolute', right: '10px', top: '10px'}}>
+    <Reactodia.ViewportDock dock='ne'>
       <button type='button'
         className='reactodia-btn reactodia-btn-default'
         onClick={() => model.setSelection([...model.elements])}>
         Select All
       </button>
-    </div>
+    </Reactodia.ViewportDock>
   );
 }
 
@@ -40,10 +72,14 @@ function Example() {
 
   const {onMount} = Reactodia.useLoadedWorkspace(async ({context, signal}) => {
     const {model, view, performLayout} = context;
-    const dataProvider = new Reactodia.EmptyDataProvider();
-    await model.createNewDiagram({dataProvider, signal});
     model.createElement('http://example.com/entity1');
     model.createElement('http://example.com/entity2');
+    model.createLinks({
+      sourceId: 'http://example.com/entity1',
+      targetId: 'http://example.com/entity2',
+      linkTypeId: 'http://example.com/connectedTo',
+      properties: {},
+    });
     await performLayout({signal});
   }, []);
 
@@ -62,3 +98,16 @@ function Example() {
 
 render(<Example />);
 ```
+
+## Styles
+
+The component look can be customized using the following CSS properties (see [design system](/docs/concepts/design-system.mdx) for more information):
+
+| Property | Description |
+|----------|-------------|
+| `--reactodia-canvas-background-color` | Background color for the canvas. |
+| `--reactodia-canvas-box-shadow` | Box shadow for the UI components layered on top of the canvas. |
+| `--reactodia-canvas-overlay-color` | Semi-transparent color to place over canvas content when displaying a modal on top. |
+| `--reactodia-canvas-underlay-color` | Semi-transparent color to place under components for improved readability when they are placed on the canvas. |
+| `--reactodia-element-background-color` | Default background color for the graph elements displayed on the canvas. |
+| `--reactodia-link-stroke-color` | Default stroke color for the graph links displayed on the canvas. |

docs/components/class-tree.md

@@ -7,16 +7,12 @@ Element type graph is loaded from [data provider](/docs/concepts/data-provider.m
 In [graph authoring](/docs/concepts/graph-authoring.md) mode, the class tree can be used to create entity elements that are instances of the displayed types.
 
 :::tip
-
 The same functionality is also available as `SearchSectionElementTypes` [unified search section](/docs/components/unified-search.md).
-
 :::
 
 ```tsx live
 function Example() {
-  const GRAPH_DATA =
-    'https://raw.githubusercontent.com/reactodia/reactodia-workspace/' +
-    'master/examples/resources/orgOntology.ttl';
+  const GRAPH_DATA = 'https://reactodia.github.io/resources/orgOntology.ttl';
 
   const {defaultLayout} = Reactodia.useWorker(Layouts);
 
@@ -41,3 +37,14 @@ function Example() {
   );
 }
 ```
+
+## Styles
+
+The component look can be customized using the following CSS properties (see [design system](/docs/concepts/design-system.mdx) for more information):
+
+| Property | Description |
+|----------|-------------|
+| `--reactodia-tree-background-color-active`  | Background color for a selected tree item. |
+| `--reactodia-tree-background-color-focus`   | Background color for a hovered over tree item. |
+| `--reactodia-tree-border-color-active`      | Border color for a selected tree item. |
+| `--reactodia-tree-border-color-focus`       | Border color for a hovered over tree item. |

docs/components/connections-menu.md

@@ -1,3 +1,44 @@
 # Connections Menu
 
 [ConnectionsMenu](/docs/api/workspace/functions/ConnectionsMenu) component is a [canvas widget](/docs/components/canvas.md) to explore and navigate the graph by adding connected entities to the diagram.
+
+### Example: opening a connections menu on load
+
+```tsx live
+function Example() {
+  const GRAPH_DATA = 'https://reactodia.github.io/resources/orgOntology.ttl';
+
+  const {defaultLayout} = Reactodia.useWorker(Layouts);
+
+  const [connectionsMenuCommands] = React.useState(() =>
+    new Reactodia.EventSource<ConnectionsMenuCommands>()
+  );
+
+  const {onMount} = Reactodia.useLoadedWorkspace(async ({context, signal}) => {
+    const {model, view, performLayout} = context;
+
+    const response = await fetch(GRAPH_DATA, {signal});
+    const graphData = new N3.Parser().parse(await response.text());
+    const dataProvider = new Reactodia.RdfDataProvider({acceptBlankNodes: false});
+    dataProvider.addGraph(graphData);
+    await model.importLayout({dataProvider, signal});
+
+    const target = model.createElement('http://www.w3.org/ns/org#Organization');
+    await model.requestElementData([target.iri]);
+
+    connectionsMenuCommands.trigger('show', {targets: [target]});
+  }, []);
+
+  return (
+    <div className='reactodia-live-editor'>
+      <Reactodia.Workspace ref={onMount}
+        defaultLayout={defaultLayout}>
+        <Reactodia.DefaultWorkspace
+          search={null}
+          connectionsMenuCommands={connectionsMenuCommands}
+        />
+      </Reactodia.Workspace>
+    </div>
+  );
+}
+```

docs/components/dialog.md

@@ -6,6 +6,8 @@ title: Dialog
 
 It is possible to show a dialog either attached to target [element](/docs/concepts/graph-model.md), [link](/docs/concepts/graph-model.md) or as a modal over the canvas viewport itself.
 
+## Showing a dialog
+
 The following methods and properties from [OverlayController](/docs/api/workspace/classes/OverlayController) (accessible from [workspace context](/docs/concepts/workspace-context.md)) provide means to interact with the dialogs:
 
 | Method or property | Description |
@@ -53,3 +55,13 @@ function Example() {
   );
 }
 ```
+
+## Styles
+
+The component look can be customized using the following CSS properties (see [design system](/docs/concepts/design-system.mdx) for more information):
+
+| Property | Description |
+|----------|-------------|
+| `--reactodia-dialog-border-color`  | Border color for the dialog (uses the base border color if not set). |
+| `--reactodia-dialog-border-radius` | Border radius for the dialog (uses the base border radius if not set). |
+| `--reactodia-dialog-border-width`  | Border width for the dialog (uses the base border width if not set). |

docs/components/drop-on-canvas.md

@@ -1,3 +1,3 @@
 # Drop on Canvas
 
-[DropOnCanvas](/docs/api/workspace/functions/DropOnCanvas) component is a [canvas widget](/docs/components/canvas.md) to allow creating entity elements on the diagram by dragging then dropping a URL (IRI) to the canvas.
+[DropOnCanvas](/docs/api/workspace/functions/DropOnCanvas) component is a [canvas widget](/docs/components/canvas.md) to allow creating entity elements on the diagram by dragging then dropping a [URL (IRI)](/docs/concepts/data-provider.md#iri-and-rdf) to the canvas.

docs/components/instances-search.md

@@ -3,7 +3,45 @@
 [InstancesSearch](/docs/api/workspace/functions/InstancesSearch.md) is a component to search for entities by various filter criteria using [data provider lookup](/docs/concepts/data-provider.md) and add them as elements to the diagram.
 
 :::tip
-
 The same functionality is also available as `SearchSectionEntities` [unified search section](/docs/components/unified-search.md).
-
 :::
+
+```tsx live
+function Example() {
+  const GRAPH_DATA = 'https://reactodia.github.io/resources/orgOntology.ttl';
+
+  const {defaultLayout} = Reactodia.useWorker(Layouts);
+
+  const [instancesSearchCommands] = React.useState(() =>
+    new Reactodia.EventSource<InstancesSearchCommands>()
+  );
+
+  const {onMount} = Reactodia.useLoadedWorkspace(async ({context, signal}) => {
+    const {model, performLayout} = context;
+
+    const response = await fetch(GRAPH_DATA, {signal});
+    const graphData = new N3.Parser().parse(await response.text());
+    const dataProvider = new Reactodia.RdfDataProvider({acceptBlankNodes: false});
+    dataProvider.addGraph(graphData);
+    await model.createNewDiagram({dataProvider, signal});
+
+    instancesSearchCommands.trigger('setCriteria', {
+        criteria: {
+            refElement: 'http://www.w3.org/ns/org#Organization',
+            refElementLink: 'http://www.w3.org/2000/01/rdf-schema#domain',
+        }
+    });
+  }, []);
+
+  return (
+    <div className='reactodia-live-editor'>
+      <Reactodia.Workspace ref={onMount}
+        defaultLayout={defaultLayout}>
+          <Reactodia.WorkspaceRoot>
+            <Reactodia.InstancesSearch commands={instancesSearchCommands} />
+          </Reactodia.WorkspaceRoot>
+      </Reactodia.Workspace>
+    </div>
+  );
+}
+```

docs/components/layout-panels.md

@@ -17,7 +17,7 @@ Reactodia provides layout panel components to display a row or a column of resiz
 ```tsx live
 function SomeLayout() {
   return (
-    <div style={{height: '300px'}}>
+    <Reactodia.WorkspaceRoot style={{height: '300px'}}>
       <Reactodia.WorkspaceLayoutRow>
         <Reactodia.WorkspaceLayoutColumn>
           <Reactodia.WorkspaceLayoutItem heading='First'>
@@ -39,7 +39,7 @@ function SomeLayout() {
           </Reactodia.WorkspaceLayoutItem>
         </Reactodia.WorkspaceLayoutColumn>
       </Reactodia.WorkspaceLayoutRow>
-    </div>
+    </Reactodia.WorkspaceRoot>
   )
 }
 ```

docs/components/link-types-toolbox.md

@@ -3,7 +3,5 @@
 [LinkTypesToolbox](/docs/api/workspace/functions/LinkTypesToolbox.md) is a component to display incoming and outgoing [link types](/docs/api/workspace/type-aliases/LinkTypeIri.md) from selected elements, toggle their visibility and initiate the [lookup](/docs/components/instances-search.md) for connected entities.
 
 :::tip
-
 The same functionality is also available as `SearchSectionLinkTypes` [unified search section](/docs/components/unified-search.md).
-
 :::

docs/components/navigator.md

@@ -1,3 +1,63 @@
 # Navigator
 
 [Navigator](/docs/api/workspace/functions/Navigator) component is a [canvas widget](/docs/components/canvas.md) to display a minimap of the diagram contents.
+
+```tsx live
+function Example() {
+  const GRAPH_DATA = 'https://reactodia.github.io/resources/orgOntology.ttl';
+
+  const {defaultLayout} = Reactodia.useWorker(Layouts);
+
+  const {onMount} = Reactodia.useLoadedWorkspace(async ({context, signal}) => {
+    const {model, view, performLayout} = context;
+
+    const response = await fetch(GRAPH_DATA, {signal});
+    const graphData = new N3.Parser().parse(await response.text());
+    const dataProvider = new Reactodia.RdfDataProvider({acceptBlankNodes: false});
+    dataProvider.addGraph(graphData);
+    await model.importLayout({dataProvider, signal});
+
+    const first = model.createElement('http://www.w3.org/ns/org#Organization');
+    const second = model.createElement('http://www.w3.org/ns/org#FormalOrganization');
+    await Promise.all([
+        model.requestElementData([first.iri, second.iri]),
+        model.requestLinks(),
+    ]);
+    await performLayout({signal});
+  }, []);
+
+  return (
+    <div className='reactodia-live-editor'>
+      <Reactodia.Workspace ref={onMount}
+        defaultLayout={defaultLayout}>
+        <Reactodia.DefaultWorkspace
+            menu={null}
+            search={null}
+            actions={null}
+            navigator={{
+                expanded: true,
+                viewportFill: 'lightgreen',
+                viewportStroke: {color: 'green'},
+            }}
+        />
+      </Reactodia.Workspace>
+    </div>
+  );
+}
+```
+
+## Styles
+
+The component look can be customized using the following CSS properties (see [design system](/docs/concepts/design-system.mdx) for more information):
+
+| Property | Description |
+|----------|-------------|
+| `--reactodia-navigator-background-fill` | Background color on the minimap outside the scrollable pane area. |
+| `--reactodia-navigator-scrollable-pane-fill` | Background color on the minimap for the scrollable pane area. |
+| `--reactodia-navigator-viewport-fill` | Background color on the minimap for the viewport area. |
+| `--reactodia-navigator-viewport-stroke-color` | Stroke color for the viewport area border. |
+| `--reactodia-navigator-viewport-stroke-width` | Stroke width for the viewport area border. |
+| `--reactodia-navigator-viewport-stroke-dash` | Stroke dash for the viewport area border. |
+| `--reactodia-navigator-overflow-stroke-color` | Stroke color for the viewport area overflow border (displayed when the viewport is cutoff at the minimap border). |
+| `--reactodia-navigator-overflow-stroke-width` | Stroke width for the viewport area overflow border (displayed when the viewport is cutoff at the minimap border). |
+| `--reactodia-navigator-overflow-stroke-dash` | Stroke dash for the viewport area overflow border (displayed when the viewport is cutoff at the minimap border). |

docs/components/selection.md

@@ -36,3 +36,13 @@ There are several built-in link actions that can be used:
 | [LinkActionDelete](/docs/api/workspace/functions/LinkActionDelete.md) | Deletes [the relation](/docs/concepts/graph-authoring.md). |
 | [LinkActionMoveEndpoint](/docs/api/workspace/functions/LinkActionMoveEndpoint.md) | Displays a handle which allows to [change the relation](/docs/concepts/graph-authoring.md) by moving its endpoint (source or target) to another entity. |
 | [LinkActionRename](/docs/api/workspace/functions/LinkActionRename.md) | Starts [renaming a link](/docs/api/workspace/interfaces/RenameLinkProvider.md) (change the label on the diagram only). |
+
+## Styles
+
+The component look can be customized using the following CSS properties (see [design system](/docs/concepts/design-system.mdx) for more information):
+
+| Property | Description |
+|----------|-------------|
+| `--reactodia-selection-icon-filter`  | [CSS filter](https://developer.mozilla.org/en-US/docs/Web/CSS/filter) for the element selection action icons. |
+| `--reactodia-selection-multiple-box-shadow` | Box shadow for the selection rectangle with multiple elements. |
+| `--reactodia-selection-single-box-shadow`  | Box shadow for the selection rectangle with a single element. |

docs/components/toolbar.md

@@ -2,6 +2,8 @@
 
 [Toolbar](/docs/api/workspace/functions/Toolbar) component is a [canvas widget](/docs/components/canvas.md) to display a simple toolbar with a an optional dropdown menu.
 
+## Toolbar actions
+
 There are several built-in toolbar actions that can be displayed as menu items or quick action buttons:
 | Action component | Description |
 |------------------|-------------|
@@ -14,3 +16,11 @@ There are several built-in toolbar actions that can be displayed as menu items o
 | [ToolbarActionRedo](/docs/api/workspace/functions/ToolbarActionRedo.md) | Performs a [redo](/docs/api/workspace/interfaces/CommandHistory.md#redo) for a command from the [command history](/docs/concepts/command-history.md). |
 | [ToolbarActionLayout](/docs/api/workspace/functions/ToolbarActionLayout.md) | Performs the default [graph layout algorithm](/docs/concepts/layout-workers.md) on the diagram content. |
 | [ToolbarLanguageSelector](/docs/api/workspace/functions/ToolbarLanguageSelector.md) | Displays a [data language](/docs/api/workspace/classes/DiagramModel.md#language) selector for the workspace. |
+
+## Styles
+
+The component look can be customized using the following CSS properties (see [design system](/docs/concepts/design-system.mdx) for more information):
+
+| Property | Description |
+|----------|-------------|
+| `--reactodia-toolbar-height` | Default height for the toolbar and the menu toggle. |