@cratis/stage.runtime 4.203.0 → 4.205.0

package/dist/src/navigationTree.d.ts

@@ -8,6 +8,10 @@ export interface NavigationEntry {
     /** The module and features, outermost first, the entry was declared in. */
     hierarchy: string[];
     order?: number;
+    /** The authored identity of the entry: one entry per id, however many screens it arrives on. */
+    id?: string;
+    /** The section heading the entry is listed under within its feature. */
+    group?: string;
     /** The icon the entry was authored with. */
     icon?: string;
     /** How chrome shows the entry - `icon`, `text` or `both`; any other value is a hint the theme may read. */
@@ -18,6 +22,10 @@ export interface NavigationEntry {
 /** A node of the navigation tree: a group (module or feature) with children, or an entry that opens a screen. */
 export interface NavigationNode {
     label: string;
+    /** The authored identity of the entry; absent on a group. */
+    id?: string;
+    /** Whether the node is a heading made from an entry's `group`, rather than a module or feature. */
+    section?: true;
     /** The screen the node opens; absent on a group. */
     screen?: string;
     icon?: string;

package/dist/src/primereact.js

@@ -1,7 +1,7 @@
-import { t as e } from "../stageDarkSelector-DjqhPYDU.js";
+import { t as e } from "../stageDarkSelector-DAwb43-P.js";
 import { primeReactComponents as t, primeReactPackageManifest as n } from "@cratis/scene.primereact";
 import r from "@primeuix/themes/lara";
-//#region src/stageTheme.ts
+// src/stageTheme.ts
 var i = {
 	preset: r,
 	options: { darkModeSelector: e }
@@ -9,5 +9,4 @@ var i = {
 	components: t,
 	declared: n.components
 };
-//#endregion
 export { t as primeReactComponents, a as primeReactLibrary, n as primeReactPackageManifest, e as stageDarkSelector, i as stageTheme };

package/dist/src/stageItemChange.d.ts

@@ -0,0 +1,106 @@
+import type { BindingExpression, ExternalComponent } from '@cratis/scene.model';
+import { type ComponentBindingOutputs, type RegisteredComponentProps } from '@cratis/scene.react';
+/** The binding path `with <input> from value` reads: the value the item changed to. */
+export declare const changedValuePath = "value";
+/** The binding path `with <input> from previous` reads: the value the item had before it changed. */
+export declare const previousValuePath = "previous";
+/** What a component reports for one of its items. */
+export interface ReportedItem {
+    id: unknown;
+    column: unknown;
+}
+/** The item the user changed, as `item`, `value` and `previous` mean it to a binding. */
+export interface ItemChange {
+    /** The item's row, with the changed property already holding its new value. */
+    item: Record<string, unknown>;
+    /** The value the item changed to. */
+    value: unknown;
+    /** The value the item had before. */
+    previous: unknown;
+}
+/**
+ * Finds the one item whose value differs between two reports of a component's items.
+ *
+ * @param before What the component reported before.
+ * @param after What it reports now.
+ * @returns The changed item and the value it had, or `undefined` when nothing changed or the report is not a list of items.
+ */
+export declare function changedItem(before: unknown, after: unknown): {
+    item: ReportedItem;
+    previous: unknown;
+} | undefined;
+/**
+ * Builds the change a binding reads from the rows a component presents.
+ *
+ * The component's own report names an item by its identifier and the value it changed to. The row the component was
+ * given for that item is what the document binds to, so the row is found by `idField` and the property that holds
+ * the value (`valueField`) takes the new value.
+ *
+ * @param rows The rows the component was given.
+ * @param changed The item the component reported as changed.
+ * @param idField The row property that identifies an item.
+ * @param valueField The row property the user changes.
+ * @returns The change, or `undefined` when the component presents no row for the item.
+ */
+export declare function itemChangeOf(rows: unknown, changed: {
+    item: ReportedItem;
+    previous: unknown;
+}, idField: string, valueField: string): ItemChange | undefined;
+/**
+ * Resolves what a change's bindings read: `item.<field>` from the changed row, `value` and `previous` from the
+ * change, and a guarded `when ... otherwise` against the changed row. Everything else is the screen's own.
+ *
+ * @param change The change.
+ * @param fallback Resolves any other binding.
+ * @returns The resolver the interaction engine runs the bindings with.
+ */
+export declare function resolveChange(change: ItemChange, fallback: (binding: BindingExpression) => unknown): (binding: BindingExpression) => unknown;
+/** What a component that lets the user change its items needs to run the document's `on change`. */
+export interface ItemChangeBinding {
+    /** The element the bindings are attached to. */
+    element: ExternalComponent;
+    /** The property of the element that holds the rows the component presents. */
+    rowsProperty: string;
+    /** The row property that identifies an item. */
+    idField: string;
+    /** The row property the user changes. */
+    valueField: string;
+}
+/** What the wrapped component is given in place of its own handlers and outputs. */
+export interface ItemChangeHandlers {
+    /** Whether the document declares an `on change` for the component. */
+    declared: boolean;
+    /** Replaces the component's `onChange`: remembers that the next report is the user's. */
+    onChange: () => void;
+    /** Wraps the outputs the component publishes, running the bindings when the user's change is reported. */
+    outputs: ComponentBindingOutputs | undefined;
+    /** Changes whenever the component must be shown the data again, because the change was not applied. Use it as the component's `key`. */
+    revision: number;
+}
+/**
+ * Runs a component's `on change` for the item the user changed.
+ *
+ * A component that lets the user change an item (a card dropped in another column) says so through its `onChange`
+ * handler and then reports its items through its `value` output. The handler alone carries no item, so the change is
+ * the difference between the report before and after. A report that follows no `onChange` is the data changing
+ * under the component, which is not the user and so runs nothing.
+ *
+ * The bindings are the element's own, resolved and run by the Scene interaction engine - the same engine that runs
+ * every other interaction. Once they have run the data is read again. A change that no command applied (the
+ * `otherwise` branch only notified, or the command was refused) is shown as the data says it is rather than as the
+ * user left it: the `revision` changes, and the component, keyed by it, starts again from the data.
+ *
+ * @param binding What the component is and which of its row properties identify and change an item.
+ * @param outputs The outputs the component publishes.
+ * @returns The handlers to give the component.
+ */
+export declare function useItemChange(binding: ItemChangeBinding, outputs: ComponentBindingOutputs | undefined): ItemChangeHandlers;
+/**
+ * The default blueprint's kanban board, running the document's `on change` for the card the user moved.
+ *
+ * The board is the blueprint's own; this only gives it what the document's interaction needs: the card, as its row
+ * with the column it was dropped in, and that column as `value`.
+ */
+export declare function StageKanbanBoard(props: RegisteredComponentProps): import("react").JSX.Element;
+/** The registry key the default blueprint's kanban board is registered under, which the Stage's own board replaces. */
+export declare const kanbanBoardKey: string;

package/dist/src/stageScreenTables.d.ts

@@ -0,0 +1,27 @@
+import type { ReactNode } from 'react';
+import type { SceneElement } from '@cratis/scene.model';
+/**
+ * The table ids of one screen, including tables nested in its slots. An outlet belongs to another screen, so its children are not visited.
+ *
+ * @param element The composed screen.
+ * @returns The distinct table ids, in first-use order, matching the scopes under which tables publish their queries and selections.
+ */
+export declare function screenTablesOf(element: SceneElement): string[];
+/** Limits action selection and hidden form identifiers to the tables of this screen, independently of other screens on the page. */
+export declare function StageScreenTables({ element, children }: {
+    element: SceneElement;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Preserves the page-wide selection of a confirmation decision and its form after leaving the list screen. */
+export declare function StagePageRows({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * The rows a person could select and has selected in this screen's tables, each carrying the entity keys the command form recognizes.
+ * Queries published for `data:` declarations or `binding:` values and tables on other screens cannot gate an action or fill its identifier.
+ * Without a screen provider, direct consumers retain the page-wide behavior.
+ */
+export declare function useScreenRows(): {
+    selectableRows: Record<string, unknown>[];
+    selectedRows: Record<string, unknown>[];
+};

package/dist/{stageDarkSelector-DjqhPYDU.js → stageDarkSelector-DAwb43-P.js}

@@ -1,4 +1,3 @@
-//#region src/stageDarkSelector.ts
+// src/stageDarkSelector.ts
 var e = "[data-scene-color-scheme='dark']";
-//#endregion
 export { e as t };

package/dist/styledPrimeReact.js

@@ -1,5 +1,5 @@
 import { readFile as e } from "node:fs/promises";
-//#region styledPrimeReact.ts
+// styledPrimeReact.ts
 var t = /^primereact\/([a-z]+)$/, n = "\0stage-styled-primereact:";
 function r() {
 	return {
@@ -26,5 +26,4 @@ function i(e) {
 	}
 	return [...t];
 }
-//#endregion
 export { i as exportedNames, r as styledPrimeReact };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/stage.runtime",
-  "version": "4.203.0",
+  "version": "4.205.0",
   "description": "The Cratis Stage application runtime for Arc and Scene",
   "author": "Cratis",
   "type": "module",
@@ -57,7 +57,7 @@
     "primereact": "11.2.0",
     "react": "19.3.0",
     "react-dom": "19.3.0",
-    "vite": "8.3.2"
+    "vite": "8.3.5"
   },
   "peerDependenciesMeta": {
     "@cratis/scene.primereact": {

package/dist/src/standaloneScreenTemplates.d.ts

@@ -1,15 +0,0 @@
-import type { ScreenTemplate } from '@cratis/scene.model';
-/**
- * The blueprint templates with every template that fits a slot of another template placed in the shell's content instead.
- *
- * A blueprint template may declare that it sits inside another one - the default blueprint's `MasterDetailScreen` fits
- * `WorkspaceScreen.moduleContent` - and the shared composition then wraps the screen in that outer template with the outer
- * template's own seeded content. A screen written in Screenplay fills only the slots of the template it names, so in the Stage
- * the outer template only ever draws its seed: the workspace's module navigation, bound to a `ModuleSections` query no
- * application has, drew "Nothing here yet" beside the master/detail and squeezed it into three quarters of the page.
- * Placing the inner template in the content slot composes only the template the screen names, at the full content width.
- *
- * @param templates The blueprint templates in play.
- * @returns The same templates, with a template qualified to another template's slot fitting the shell's content slot.
- */
-export declare function standaloneScreenTemplates(templates: readonly ScreenTemplate[]): ScreenTemplate[];