@cratis/scene.react 4.15.0 → 4.16.0

package/navigation/createHashSceneHistory.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneBrowserWindow } from './createBrowserSceneHistory';
+import { SceneHistory } from './SceneHistory';
+import { SceneNavigationState } from './SceneNavigationState';
+
+const stateKey = 'sceneNavigation';
+
+/**
+ * A history kept in the URL fragment - `index.html#/WorkItemDetails?workItemId=B` - for hosts that are served
+ * as a single file or from a path they do not control, such as a generated runtime or a webview. It behaves
+ * like `createBrowserSceneHistory`: entries are pushed with their navigation state, back and forward restore
+ * them, and a typed or bookmarked fragment is matched by URL alone. A fragment changed by hand, which fires
+ * `hashchange` rather than `popstate`, is reported the same way.
+ */
+export function createHashSceneHistory(browser: SceneBrowserWindow = window): SceneHistory {
+    const location = () => {
+        const fragment = browser.location.hash.replace(/^#\/?/, '');
+        return fragment.length ? fragment : undefined;
+    };
+    const href = (url: string | undefined) => `${browser.location.pathname}${browser.location.search}#/${url ?? ''}`;
+    const stored = (value: unknown) => (value as Record<string, SceneNavigationState> | null)?.[stateKey];
+
+    return {
+        location,
+        state: () => stored(browser.history.state),
+        push: state => browser.history.pushState({ [stateKey]: state }, '', href(state.url)),
+        replace: state => browser.history.replaceState({ [stateKey]: state }, '', href(state.url)),
+        back: () => browser.history.back(),
+        listen: listener => {
+            const onPopState = (event: PopStateEvent) => listener(location(), stored(event.state));
+            const onHashChange = () => listener(location(), stored(browser.history.state));
+            browser.addEventListener('popstate', onPopState);
+            browser.addEventListener('hashchange', onHashChange);
+            return () => {
+                browser.removeEventListener('popstate', onPopState);
+                browser.removeEventListener('hashchange', onHashChange);
+            };
+        },
+    };
+}

package/navigation/index.ts

@@ -9,6 +9,7 @@ export * from './SceneNavigationHost';
 export * from './SceneNavigationState';
 export * from './SceneRoute';
 export * from './createBrowserSceneHistory';
+export * from './createHashSceneHistory';
 export * from './createMemorySceneHistory';
 export * from './diagnoseRenderedNavigation';
 export * from './identityRoute';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.react",
-    "version": "4.15.0",
+    "version": "4.16.0",
     "description": "The React renderer implementing Scene.Engine's Renderer contract against real React/DOM.",
     "keywords": [
         "cratis",
@@ -51,12 +51,12 @@
         "build-storybook": "storybook build"
     },
     "dependencies": {
-        "@cratis/scene.engine": "4.15.0",
-        "@cratis/scene.model": "4.15.0"
+        "@cratis/scene.engine": "4.16.0",
+        "@cratis/scene.model": "4.16.0"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "4.15.0",
-        "@cratis/scene.model": "4.15.0",
+        "@cratis/scene.engine": "4.16.0",
+        "@cratis/scene.model": "4.16.0",
         "@storybook/addon-links": "^10.6.1",
         "@storybook/react": "^10.6.1",
         "@storybook/react-vite": "^10.6.1",

package/renderer/index.ts

@@ -7,5 +7,7 @@ export * from './ComponentRegistry';
 export * from './RenderBindingScopeContext';
 export * from './UnresolvedComponent';
 export * from './useBoundQuery';
+export * from './useValueOutput';
+export * from './valueOutputProperty';
 export * from './createReactRenderer';
 export * from './InteractiveComponent';

package/renderer/useValueOutput.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useEffect, useRef } from 'react';
+import { ComponentBindingOutputs } from './BindingOutputContext';
+
+/** The output property an input widget publishes its current value under. */
+export const valueOutputName = 'value';
+
+/**
+ * Publishes an input widget's current value as its `value` output: once when it mounts, with the initial
+ * value, and again on every change. Other elements bind to it with a `componentProperty` binding, and a
+ * command action maps it as `component.<id>.value`. The renderer clears the output when the widget unmounts.
+ *
+ * Values are published as JSON-compatible data so both engines read the same thing: a `Date` is published
+ * as its ISO 8601 string, and `undefined` as `null`.
+ */
+export function useValueOutput(bindingOutputs: ComponentBindingOutputs | undefined, value: unknown): void {
+    const published = value instanceof Date ? value.toISOString() : value ?? null;
+    const key = JSON.stringify(published);
+    const latest = useRef(published);
+    latest.current = published;
+
+    // Published by value through `key`: a new array or object with the same content is not a change.
+    useEffect(() => {
+        bindingOutputs?.setOutput(valueOutputName, latest.current);
+    }, [bindingOutputs, key]);
+}

package/renderer/valueOutputProperty.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { BindingMode, PropertyDescriptor, PropertyValueType } from '@cratis/scene.model';
+import { valueOutputName } from './useValueOutput';
+
+/**
+ * The descriptor entry an input widget declares for the value it publishes with `useValueOutput`, so a
+ * designer can offer it as a binding source - for a detail component, a query argument or a command input.
+ *
+ * @param valueType The type of value the widget publishes.
+ * @param description What the value is, when the default sentence does not say enough.
+ */
+export function valueOutputProperty(valueType: PropertyValueType, description = 'What the user has entered, published as the input changes.'): PropertyDescriptor {
+    return {
+        path: valueOutputName,
+        label: 'Value',
+        group: 'Outputs',
+        valueType,
+        readOnly: true,
+        output: true,
+        bindingMode: BindingMode.OneWay,
+        description,
+    };
+}