Update docs for @reactodia/workspace@0.30:

* Add pages for keyboard hotkeys, form input components;
* Add sections for command buses, element and link template customization, element decorations, exporting the canvas content;
* Add links to command bus topics from relevant components;
* Add `style-customization` example;
* Update feature screenshots, add separate screenshots for light/dark themes;

Author: AlexeyMz

.editorconfig

@@ -8,6 +8,6 @@ charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
 
-[*.{js,jsx,ts,tsx}]
+[*.{js,jsx,ts,tsx,md,mdx}]
 indent_style = space
 indent_size = 2

docs/components/canvas.md

@@ -6,6 +6,53 @@ title: <Canvas />
 
 [`<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.
 
+## Customizing element and link appearance {#customization}
+
+It is possible to customize how elements (nodes) and links (edges) are rendered on the canvas by providing `elementTemplateResolver` ([`TypedElementResolver`](/docs/api/workspace/type-aliases/TypedElementResolver.md)) and/or `linkTemplateResolver` ([`LinkTemplateResolver`](/docs/api/workspace/type-aliases/LinkTemplateResolver.md)) props to the `<Canvas />`.
+
+An element or link template is an object with rendering function (returning a React component to display it) and additional rendering settings such as element shape, link markers, etc.
+
+An **element template** is an [`ElementTemplate`](/docs/api/workspace/interfaces/ElementTemplate.md) object with rendering function (returning a React component to display the element) and additional settings, such as element shape (rectangular or elliptical).
+
+A **link template** is a [`LinkTemplate`](/docs/api/workspace/interfaces/LinkTemplate.md) object with rendering function (returning a React component to display the link) and additional settings, such as link markers (mini-shapes on its endpoints, e.g. arrowheads) and path spline type (straight or smooth).
+
+The library provides the following built-in templates:
+
+| Template             | Type | Description |
+|----------------------|------|-------------|
+| [`StandardTemplate`](/docs/api/workspace/variables/StandardTemplate.md) | element | Default (fallback) template for an element; supports single entity elements and [entity groups](/docs/concepts/graph-model.md#data-graph).<br />Uses [`StandardEntity`](/docs/api/workspace/functions/StandardEntity.md) and [`StandardEntityGroup`](/docs/api/workspace/functions/StandardEntityGroup.md) components to render elements. |
+| [`ClassicTemplate`](/docs/api/workspace/variables/ClassicTemplate.md) | element | Element template component with classic "look and feel" which was used for elements before v0.8; does not support entity groups.<br />Uses [`ClassicEntity`](/docs/api/workspace/functions/ClassicEntity.md) component to render elements. |
+| [`RoundTemplate`](/docs/api/workspace/variables/RoundTemplate.md) | element | Basic element template with an round (elliptical) shape; does not support entity groups.<br />Uses [`RoundEntity`](/docs/api/workspace/functions/RoundEntity.md) component to render elements. |
+| [`DefaultLinkTemplate`](/docs/api/workspace/variables/DefaultLinkTemplate.md) | link | Default (fallback) template for a link; supports single relation links and [relation groups](/docs/concepts/graph-model.md#data-graph).<br />Uses [`DefaultLink`](/docs/api/workspace/functions/DefaultLink.md) component to render links which uses [`LinkPath`](/docs/api/workspace/functions/LinkPath.md), [`LinkLabel`](/docs/api/workspace/functions/LinkLabel.md) and [`LinkVertices`](/docs/api/workspace/functions/LinkVertices.md) components inside to display the link connection itself, the labels and vertices (to change link geometry). |
+
+Additionally, it is possible to override how the link are routed (how default path geometry is computed) on the canvas by providing `linkRouter` ([`LinkRouter`](/docs/api/workspace/interfaces/LinkRouter.md)) prop to the `<Canvas />`. By default, the [`DefaultLinkRouter`](/docs/api/workspace/classes/DefaultLinkRouter.md) is used which moves apart multiple links between same elements and displays self-links (where target is equal to source) as loops.
+
+### Element decorations
+
+To further customize element rendering the library provides [`<ElementDecoration />`](/docs/api/workspace/functions/ElementDecoration.md) component to display a decoration over a canvas element. These decorations are rendered outside the element template content itself and does not contribute to the measured size of an element.
+
+All decorations for a specific entity are rendered as children of a DOM element with `reactodia-element-decorators` CSS class which immediately follows each target canvas element in the DOM. Such parent DOM elements for the decorations have `transform: translate(...)`, `width` and `height` set to the same values as the target element to be able to layout decoration content via CSS:
+
+```css
+/* Position decoration to the left of the target canvas element  */
+.my-custom-decoration {
+  position: absolute;
+  top: 50%;
+  left: -10px;
+  transform: translate(-100%,-50%);
+}
+
+/* Show decoration on hover over it or target canvas element */
+.reactodia-overlaid-element:hover + .reactodia-element-decorations .my-custom-decoration,
+.my-custom-decoration:hover {
+  opacity: 1;
+}
+```
+
+:::tip
+See complete [style customization example](/docs/examples/style-customization) with custom element and link templates, element decorations and more.
+:::
+
 ## Getting the canvas instance
 
 [`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:
@@ -99,6 +146,34 @@ function Example() {
 render(<Example />);
 ```
 
+## Exporting the canvas
+
+It is possible to export a "snapshot" of currently rendered canvas content into an SVG (with HTML parts) or a raster image:
+
+| Canvas API method | Description |
+|-------------------|-------------|
+| [`exportSvg()`](/docs/api/workspace/interfaces/CanvasApi.md#exportsvg) | Exports the diagram as a serialized into text SVG document with `<foreignObject>` HTML layers inside. (Can be opened by the browser but not with a pure SVG image editor.) |
+| [`exportRaster()`](/docs/api/workspace/interfaces/CanvasApi.md#exportraster) | Exports the diagram as a rendered raster image (e.g. PNG, JPEG, etc) serialized into base64-encoded [data URL](https://developer.mozilla.org/en-US/docs/Web/URI/Schemes/data). |
+
+:::note
+When exporting into an SVG, the resulting document would include all diagram content as well as every CSS rule which applies to any DOM element inside the diagram content.
+
+Diagram is always exported in the [light theme](/docs/concepts/design-system.mdx).
+:::
+
+To prevent being exported a DOM element can be marked with `data-reactodia-no-export` attribute or additional CSS selectors can be provided via `removeByCssSelectors` options to the export methods.
+
+Printing the diagram can be achieved by exporting an SVG, writing it into a newly opened window and printing it:
+```ts
+const printWindow = window.open('', undefined, 'width=1280,height=720')!;
+const svg = await canvas.exportSvg();
+printWindow.document.write(svg);
+printWindow.document.close();
+printWindow.print();
+```
+
+The library provides a built-in [`toolbar`](/docs/components/toolbar.md) action component [`<ToolbarActionExport />`](/docs/api/workspace/functions/ToolbarActionExport.md) as a convenient way to export or print the diagram from the UI.
+
 ## Styles
 
 The component look can be customized using the following CSS properties (see [design system](/docs/concepts/design-system.mdx) for more information):
@@ -111,3 +186,5 @@ The component look can be customized using the following CSS properties (see [de
 | `--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. |
+| `--reactodia-monochrome-icon-filter` | [CSS filter](https://developer.mozilla.org/en-US/docs/Web/CSS/filter) for the monochrome [type style](/docs/components/workspace.md#customize-type-styles) icons. |
+| `--reactodia-viewport-dock-margin` | Margin from the borders of the canvas for the viewport widgets. |

docs/components/connections-menu.md

@@ -6,6 +6,8 @@ title: <ConnectionsMenu />
 
 [`<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.
 
+The component observes [`ConnectionsMenuTopic`](/docs/api/workspace/variables/ConnectionsMenuTopic.md) [command bus topic](/docs/concepts/event-system.md#command-bus).
+
 ### Example: opening a connections menu on load
 
 ```tsx live

docs/components/form-input.md

@@ -0,0 +1,79 @@
+---
+title: <FormInput* />
+---
+
+# Form input components
+
+Reactodia provides basic built-in components to edit entity or relation properties in a form:
+
+| Form input component | Description |
+|----------------------|-------------|
+| [`<FormInputList />`](/docs/api/workspace/variables/FormInputList.md) | Form input to edit multiple values in a list of specified single value inputs. |
+| [`<FormInputText />`](/docs/api/workspace/functions/FormInputText.md) | Form input to edit a single value as a plain string with an optional language. |
+
+:::warning
+Currently form input components are considered **unstable** so there might be breaking changes in their API in the future.
+:::
+
+### Example: overriding input to a multiline text field
+
+```tsx live noInline
+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, editor, getCommandBus, 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});
+    const element = model.createElement('http://www.w3.org/ns/org#Organization');
+    await Promise.all([
+        model.requestElementData([element.iri]),
+        model.requestLinks(),
+    ]);
+    editor.setAuthoringMode(true);
+    getCommandBus(Reactodia.VisualAuthoringTopic)
+        .trigger('editEntity', {target: element});
+  }, []);
+
+  const RDF_COMMENT = 'http://www.w3.org/2000/01/rdf-schema#comment';
+
+  const [metadataProvider] = React.useState(() => new Reactodia.BaseMetadataProvider({
+    canModifyEntity: () => ({canEdit: true}),
+    getEntityShape: types => ({
+      properties: new Map([
+        [Reactodia.rdfs.label, {valueShape: {termType: 'Literal'}}],
+        [RDF_COMMENT, {valueShape: {termType: 'Literal'}}],
+      ])
+    }),
+  }));
+
+  return (
+    <div className='reactodia-live-editor'>
+      <Reactodia.Workspace ref={onMount}
+        metadataProvider={metadataProvider}
+        defaultLayout={defaultLayout}>
+          <Reactodia.DefaultWorkspace
+            search={null}
+            visualAuthoring={{
+              inputResolver: (property, inputProps) =>
+                property === RDF_COMMENT
+                  ? <Reactodia.FormInputList {...inputProps} valueInput={MultilineTextInput} />
+                  : undefined,
+            }}
+          />
+      </Reactodia.Workspace>
+    </div>
+  );
+}
+
+function MultilineTextInput(props: Reactodia.FormInputSingleProps) {
+  return <Reactodia.FormInputText {...props} multiline />;
+}
+
+render(<Example />);
+```

docs/components/instances-search.md

@@ -10,6 +10,8 @@ title: <InstancesSearch />
 The same functionality is also available as `<SearchSectionEntities />` [unified search section](/docs/components/unified-search.md).
 :::
 
+The component observes [`InstancesSearchTopic`](/docs/api/workspace/variables/InstancesSearchTopic.md) [command bus topic](/docs/concepts/event-system.md#command-bus).
+
 ```tsx live
 function Example() {
   const GRAPH_DATA = 'https://reactodia.github.io/resources/orgOntology.ttl';

docs/components/toolbar.md

@@ -21,6 +21,75 @@ There are several built-in toolbar actions that can be displayed as menu items o
 | [`<ToolbarActionLayout />`](/docs/api/workspace/functions/ToolbarActionLayout.md) | Performs the default [graph layout algorithm](/docs/concepts/graph-layout.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. |
 
+### Example: additional toolbars
+
+```tsx live
+function Example() {
+  const {defaultLayout} = Reactodia.useWorker(Layouts);
+
+  const {onMount, getContext} = Reactodia.useLoadedWorkspace(async ({context, signal}) => {
+    const {model, view, performLayout} = context;
+    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});
+  }, []);
+
+  return (
+    <div className='reactodia-live-editor'>
+      <Reactodia.Workspace ref={onMount}
+        defaultLayout={defaultLayout}>
+        <Reactodia.DefaultWorkspace
+          actions={null}
+          navigator={null}
+          canvasWidgets={[
+            <Reactodia.Toolbar key='bottom-left'
+              dock='sw'
+              menu={
+                <>
+                  <Reactodia.ToolbarActionClearAll />
+                  <Reactodia.ToolbarActionExport kind='print' />
+                </>
+              }>
+              <Reactodia.ToolbarActionUndo />
+              <Reactodia.ToolbarActionRedo />
+              <Reactodia.ToolbarActionLayout />
+            </Reactodia.Toolbar>,
+            <Reactodia.Toolbar key='top-right'
+              dock='ne'>
+              <Reactodia.ToolbarAction
+                onSelect={() => {
+                  const {overlay} = getContext();
+                  overlay.showDialog({content: <div>🎉</div>});
+                }}>
+                Show a dialog
+              </Reactodia.ToolbarAction>
+            </Reactodia.Toolbar>,
+            <Reactodia.Toolbar key='bottom-right'
+              dock='se'>
+              <Reactodia.ToolbarLanguageSelector
+                languages={[
+                  {code: 'de', label: 'Deutsch'},
+                  {code: 'en', label: 'english'},
+                  {code: 'es', label: 'español'},
+                  {code: 'ru', label: 'русский'},
+                  {code: 'zh', label: '汉语'},
+                ]}
+              />
+            </Reactodia.Toolbar>,
+          ]}
+        />
+      </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):

docs/components/unified-search.md

@@ -6,6 +6,8 @@ title: <UnifiedSearch />
 
 [`<UnifiedSearch />`](/docs/api/workspace/functions/UnifiedSearch.md) is a component to display a search input with a dropdown for results.
 
+The component observes [`UnifiedSearchTopic`](/docs/api/workspace/variables/UnifiedSearchTopic.md) [command bus topic](/docs/concepts/event-system.md#command-bus).
+
 ## Search sections
 
 One or many available search sections (providers) can be specified:
@@ -16,6 +18,8 @@ One or many available search sections (providers) can be specified:
 | [`<SearchSectionEntities />`](/docs/api/workspace/functions/SearchSectionEntities.md) | Allows to lookup entities using [data provider](/docs/concepts/data-provider.md). |
 | [`<SearchSectionLinkTypes />`](/docs/api/workspace/functions/SearchSectionLinkTypes.md) | Allows to lookup displayed link types and change their [visibility settings](/docs/api/workspace/classes/DiagramModel.md#getlinkvisibility). |
 
+`<SearchSectionEntities />` component observes [`InstancesSearchTopic`](/docs/api/workspace/variables/InstancesSearchTopic.md) [command bus topic](/docs/concepts/event-system.md#command-bus).
+
 ## Implement a custom search section
 
 [`useUnifiedSearchSection()`](/docs/api/workspace/functions/useUnifiedSearchSection.md) hook can be used to implement a custom search section:

docs/components/visual-authoring.md

@@ -9,3 +9,5 @@ title: <VisualAuthoring />
 :::important
 `<VisualAuthoring />` widget must be provided to the canvas to in order to display visual graph authoring UI.
 :::
+
+The component observes [`VisualAuthoringTopic`](/docs/api/workspace/variables/VisualAuthoringTopic.md) [command bus topic](/docs/concepts/event-system.md#command-bus).

docs/components/workspace.md

@@ -50,3 +50,27 @@ function Example() {
   );
 }
 ```
+
+## Customize type styles
+
+Reactodia displays [entities](/docs/concepts/graph-model.md) in different places throughout the workspace components. It is possible to customize overall style based on entity types (accent color and icon) by providing a custom [`TypeStyleResolver`](/docs/api/workspace/type-aliases/TypeStyleResolver.md) to the `<Workspace typeStyleResolver={...} />`:
+
+```tsx
+<Reactodia.Workspace
+  typeStyleResolver={types => {
+      if (types.includes('http://www.w3.org/2000/01/rdf-schema#Class')) {
+          return {icon: CERTIFICATE_ICON, iconMonochrome: true};
+      } else if (types.includes('http://www.w3.org/2002/07/owl#Class')) {
+          return {icon: CERTIFICATE_ICON, iconMonochrome: true};
+      } else if (types.includes('http://www.w3.org/2002/07/owl#ObjectProperty')) {
+          return {icon: COG_ICON, iconMonochrome: true};
+      } else if (types.includes('http://www.w3.org/2002/07/owl#DatatypeProperty')) {
+          return {color: '#00b9f2'};
+      } else {
+          return undefined;
+      }
+  }}
+  ...>
+```
+
+By default, the colors are assigned deterministically based on total hash of the types in the [entity data](/docs/api/workspace/interfaces/ElementModel.md).

docs/concepts/data-provider.md

@@ -89,8 +89,8 @@ function ExampleRdfProviderProvisionFromJGF() {
     } as const;
 
     const factory = Reactodia.Rdf.DefaultDataFactory;
-    const hasType = factory.namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#type');
-    const hasLabel = factory.namedNode('http://www.w3.org/2000/01/rdf-schema#label');
+    const hasType = factory.namedNode(Reactodia.rdf.type);
+    const hasLabel = factory.namedNode(Reactodia.rdfs.label);
 
     const triples: Reactodia.Rdf.Quad[] = [];
     for (const [id, node] of Object.entries(jsonGraph.graph.nodes)) {