@cratis/stage.runtime 4.204.0 → 4.205.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/stage.runtime",
-  "version": "4.204.0",
+  "version": "4.205.0",
   "description": "The Cratis Stage application runtime for Arc and Scene",
   "author": "Cratis",
   "type": "module",