Support external workspace root and translation context:

AlexeyMz · AlexeyMz · commit d5d4840cef5f · 2026-05-25T00:34:52.000+03:00
* Allow to define `WorkspaceRoot` and `TranslationProvider` as parent to the `Workspace` component so they can be shared between multiple workspaces or used outside the workspace itself.
* Deprecate `translations`, `useDefaultTranslation` and `selectLabelLanguage` props on `Workspace` component in favor of wrapping the workspace in `TranslationProvider` with `DefaultTranslation`.
* Remove deprecated `Translation.formatIri()` method (use `DataLocaleProvider.formatIri()` instead).
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -16,6 +16,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 - Fix canvas panning optimization not being applied due to incorrect `z-index` value.
 
 #### 💅 Polish
+- Allow to define `WorkspaceRoot` and `TranslationProvider` as parent to the `Workspace` component so they can be shared between multiple workspaces or used outside the workspace itself:
+  * Deprecate `translations`, `useDefaultTranslation` and `selectLabelLanguage` props on `Workspace` component in favor of wrapping the workspace in `TranslationProvider` with (newly) exported `DefaultTranslation`;
+  * Remove deprecated `Translation.formatIri()` method (use `DataLocaleProvider.formatIri()` instead).
 - Allow to configure `SearchResults` utility component with `isItemDisabled` and `multiSelection` props:
   * Remove `singleSelectOnClick` mode from `SearchResults` as it mostly superseded by `multiSelection`.
 - Extend `ListElementView` utility component to accept any other additional HTML props.
diff --git a/examples/i18n.tsx b/examples/i18n.tsx
@@ -15,6 +15,33 @@ const Layouts = Reactodia.defineLayoutWorker(() => new Worker(
 function I18nExample() {
     const {defaultLayout} = Reactodia.useWorker(Layouts);
 
+    const translation = React.useMemo(() => new Reactodia.DefaultTranslation({
+        bundles: [
+            {
+                'default_workspace': {
+                    'search_section_entities.label': 'Nodes',
+                    'search_section_entities.title': 'Graph Nodes Lookup',
+                    'search_section_entity_types.label': 'Node Types',
+                    'search_section_entity_types.title': 'Graph Node Type Hierarchy',
+                    'search_section_link_types.label': 'Edge Types',
+                    'search_section_link_types.title': 'Graph Edge Types on the diagram'
+                },
+                'search_defaults': {
+                    'input_term_too_short': 'Minimum search term length is {{termLength}}',
+                },
+                'search_entities': {
+                    'criteria_connected_to_source':
+                        '{{sourceIcon}}\u00A0{{entity}} (source) via {{relationType}}',
+                    'criteria_connected_to_target':
+                        '{{targetIcon}}\u00A0{{entity}} (target) via {{relationType}}',
+                },
+                'toolbar_action': {
+                    'layout.label': 'Layout the graph',
+                },
+            }
+        ]
+    }), []);
+
     const {onMount} = Reactodia.useLoadedWorkspace(async ({context, signal}) => {
         const {model} = context;
 
@@ -31,36 +58,14 @@ function I18nExample() {
     }, []);
 
     return (
-        <Reactodia.Workspace ref={onMount}
-            translations={[
-                {
-                    'default_workspace': {
-                        'search_section_entities.label': 'Nodes',
-                        'search_section_entities.title': 'Graph Nodes Lookup',
-                        'search_section_entity_types.label': 'Node Types',
-                        'search_section_entity_types.title': 'Graph Node Type Hierarchy',
-                        'search_section_link_types.label': 'Edge Types',
-                        'search_section_link_types.title': 'Graph Edge Types on the diagram'
-                    },
-                    'search_defaults': {
-                        'input_term_too_short': 'Minimum search term length is {{termLength}}',
-                    },
-                    'search_entities': {
-                        'criteria_connected_to_source':
-                            '{{sourceIcon}}\u00A0{{entity}} (source) via {{relationType}}',
-                        'criteria_connected_to_target':
-                            '{{targetIcon}}\u00A0{{entity}} (target) via {{relationType}}',
-                    },
-                    'toolbar_action': {
-                        'layout.label': 'Layout the graph',
-                    },
-                }
-            ]}
-            defaultLayout={defaultLayout}>
-            <Reactodia.DefaultWorkspace
-                menu={<ExampleToolbarMenu />}
-            />
-        </Reactodia.Workspace>
+        <Reactodia.TranslationProvider translation={translation}>
+            <Reactodia.Workspace ref={onMount}
+                defaultLayout={defaultLayout}>
+                <Reactodia.DefaultWorkspace
+                    menu={<ExampleToolbarMenu />}
+                />
+            </Reactodia.Workspace>
+        </Reactodia.TranslationProvider>
     );
 }
 
diff --git a/src/coreUtils/colorScheme.tsx b/src/coreUtils/colorScheme.tsx
@@ -2,7 +2,7 @@ import * as React from 'react';
 
 export type ColorScheme = 'light' | 'dark';
 
-export const ColorSchemeContext = React.createContext<ColorScheme>('light');
+export const ColorSchemeContext = React.createContext<ColorScheme | null>(null);
 
 /**
  * React hook to get currently active color scheme for the UI components.
@@ -11,13 +11,15 @@ export const ColorSchemeContext = React.createContext<ColorScheme>('light');
  * @see {@link WorkspaceRootProps.colorScheme}
  */
 export function useColorScheme(): 'light' | 'dark' {
-    return React.useContext(ColorSchemeContext);
+    return React.useContext(ColorSchemeContext) ?? 'light';
 }
 
 export interface ColorSchemeApi {
+    readonly defined: boolean;
     readonly actInColorScheme: (scheme: ColorScheme, action: () => void) => void;
 }
 
 export const ColorSchemeApi = React.createContext<ColorSchemeApi>({
+    defined: false,
     actInColorScheme: () => {/* nothing */},
 });
diff --git a/src/coreUtils/i18n.tsx b/src/coreUtils/i18n.tsx
@@ -136,15 +136,6 @@ export interface Translation<K extends string = TranslationKey> {
         fallbackIri: string,
         language: string
     ): string;
-
-    /**
-     * Formats IRI to display in the UI:
-     *   - usual IRIs are enclosed in `<IRI>`;
-     *   - anonymous element IRIs displayed as `(blank node)`.
-     *
-     * @deprecated Use {@link DataLocaleProvider.formatIri} instead.
-     */
-    formatIri(iri: string): string;
 }
 
 /**
@@ -180,6 +171,30 @@ export interface TranslatedProperty<Iri> {
 
 export const TranslationContext = React.createContext<Translation | null>(null);
 
+/**
+ * Provides i18n (translation) context for the UI elements.
+ *
+ * @category Components
+ * @see {@link useTranslation}
+ */
+export function TranslationProvider(props: {
+    /**
+     * Provided i18n implementation.
+     */
+    translation: Translation;
+    /**
+     * Component children to render with provided i18n context.
+     */
+    children: React.ReactNode;
+}) {
+    const {translation, children} = props;
+    return (
+        <TranslationContext.Provider value={translation}>
+            {children}
+        </TranslationContext.Provider>
+    );
+}
+
 /**
  * Gets current translation data for the UI elements.
  *
@@ -188,7 +203,7 @@ export const TranslationContext = React.createContext<Translation | null>(null);
 export function useTranslation(): Translation {
     const translation = React.useContext(TranslationContext);
     if (!translation) {
-        throw new Error('Reactodia: missing translation context');
+        throw new Error('Reactodia: missing <TranslationProvider> context');
     }
     return translation;
 }
@@ -209,7 +224,7 @@ type DeepPath<T> = T extends object ? (
  * Represents a lazily-resolved simple or formatted translation string.
  *
  * @category Core
- * @see Translation
+ * @see {@link Translation}
  */
 export class TranslatedText {
     private constructor(
diff --git a/src/diagram/locale.tsx b/src/diagram/locale.tsx
@@ -3,19 +3,55 @@ import * as React from 'react';
 import DefaultBundle from '../../i18n/translations/en.reactodia-translation.json';
 
 import {
-    LabelLanguageSelector, Translation, TranslationKey, TranslationBundle, TranslationContext,
+    LabelLanguageSelector, Translation, TranslationKey, TranslationBundle,
 } from '../coreUtils/i18n';
 
-import { isEncodedBlank } from '../data/model';
 import * as Rdf from '../data/rdf/rdfModel';
 
 export const DefaultTranslationBundle: TranslationBundle = DefaultBundle;
 
+/**
+ * Default built-in implementation for i18n strings interpolation and other
+ * methods from {@link Translation} interface.
+ */
 export class DefaultTranslation implements Translation {
-    constructor(
-        protected readonly bundles: ReadonlyArray<Partial<TranslationBundle>>,
-        protected readonly selectLabelLanguage: LabelLanguageSelector = defaultSelectLabel
-    ) {}
+    protected readonly bundles: ReadonlyArray<Partial<TranslationBundle>>;
+
+    private readonly _selectLabel: LabelLanguageSelector;
+
+    constructor(options: {
+        /**
+         * Additional translation bundles for UI text strings in the workspace
+         * in order from higher to lower priority.
+         *
+         * @default []
+         * @see {@link useDefaultTranslation}
+         */
+        bundles?: ReadonlyArray<Partial<TranslationBundle>>;
+        /**
+         * If set, disables translation fallback which (with default `en` language).
+         *
+         * @default true
+         * @see {@link translations}
+         */
+        useDefaultBundle?: boolean;
+        /**
+         * Overrides how a single label gets selected from multiple of them based on target language.
+         */
+        selectLabel?: LabelLanguageSelector;
+    }) {
+        const {
+            bundles = [],
+            useDefaultBundle = true,
+            selectLabel = defaultSelectLabel,
+        } = options;
+        const translationBundles: Partial<TranslationBundle>[] = [...bundles];
+        if (useDefaultBundle) {
+            translationBundles.push(DefaultTranslationBundle);
+        }
+        this.bundles = translationBundles;
+        this._selectLabel = selectLabel;
+    }
 
     private getString(key: TranslationKey): string | undefined {
         const dotIndex = key.indexOf('.');
@@ -57,8 +93,8 @@ export class DefaultTranslation implements Translation {
         labels: ReadonlyArray<Rdf.Literal>,
         language: string
     ): Rdf.Literal | undefined {
-        const {selectLabelLanguage} = this;
-        return selectLabelLanguage(labels, language);
+        const {_selectLabel} = this;
+        return _selectLabel(labels, language);
     }
 
     selectValues(
@@ -80,13 +116,6 @@ export class DefaultTranslation implements Translation {
         const label = labels ? this.selectLabel(labels, language) : undefined;
         return resolveLabel(label, fallbackIri);
     }
-
-    formatIri(iri: string): string {
-        if (isEncodedBlank(iri)) {
-            return '(blank node)';
-        }
-        return `<${iri}>`;
-    }
 }
 
 function lookupString(
@@ -185,15 +214,3 @@ function resolveLabel(label: Rdf.Literal | undefined, fallbackIri: string): stri
     if (label) { return label.value; }
     return Rdf.getLocalName(fallbackIri) || fallbackIri;
 }
-
-export function TranslationProvider(props: {
-    translation: Translation;
-    children: React.ReactNode;
-}) {
-    const {translation, children} = props;
-    return (
-        <TranslationContext.Provider value={translation}>
-            {children}
-        </TranslationContext.Provider>
-    );
-}
diff --git a/src/workspace.ts b/src/workspace.ts
@@ -15,7 +15,7 @@ export {
 export type { HotkeyString } from './coreUtils/hotkey';
 export {
     type LabelLanguageSelector, type TranslatedProperty, TranslatedText, type Translation,
-    useTranslation,
+    TranslationProvider, useTranslation,
 } from './coreUtils/i18n';
 export { KeyedObserver, type KeyedSyncStore, useKeyedSyncStore } from './coreUtils/keyedObserver';
 export { Debouncer } from './coreUtils/scheduler';
@@ -102,6 +102,7 @@ export {
     LinkVertices, type LinkVerticesProps,
 } from './diagram/linkLayer';
 export { DefaultLinkRouter, type DefaultLinkRouterOptions } from './diagram/linkRouter';
+export { DefaultTranslation } from './diagram/locale';
 export { type DiagramModel, type DiagramModelEvents, type GraphStructure } from './diagram/model';
 export { CanvasPlaceAt, type CanvasPlaceAtLayer } from './diagram/placeLayer';
 export {
diff --git a/src/workspace/workspace.tsx b/src/workspace/workspace.tsx
diff --git a/src/workspace/workspaceRoot.tsx b/src/workspace/workspaceRoot.tsx
