@cratis/stage.runtime 4.228.0 → 5.0.0

package/dist/src/navigationTree.d.ts

@@ -60,7 +60,7 @@ export declare function navigationTree(entries: NavigationEntry[]): NavigationNo
  * @returns The labels from the outermost group to the entry, or an empty list when no entry opens the screen.
  */
 export declare function navigationPathTo(nodes: NavigationNode[], screen: string): string[];
-/** Whether an entry opens somewhere a plain link to its screen does not reach: an outlet, a dialog or an external route. */
+/** Whether an entry opens somewhere a plain link to its screen does not reach: a slot, a dialog or an external route. */
 export declare function opensElsewhere(destination: DestinationReference): boolean;
 /**
  * The hierarchy the screens declare, for the screens no navigation entry lists.

package/dist/src/stageComponents.d.ts

@@ -29,6 +29,8 @@ export declare function StageAction({ element, interactions, slots }: Registered
  * address or the session already supplies it; the form then submits what was not asked by the same rule.
  */
 export declare function StageSliceDialog(props: Partial<RegisteredProps>): import("react").JSX.Element;
+/** The component the Stage draws an outlet button that names a slice or a command with. */
+export declare const stageToolbarItemComponent = "core:toolbarItem";
 /**
  * The components the Stage renders a scene with: Scene's own core vocabulary, with the two that have to reach
  * this running application - the table that reads a modeled query, and the action that executes a modeled

package/dist/src/stageNavigationModel.d.ts

@@ -1,14 +1,18 @@
-import type { ApplicationStructure, NavigationModel, Screen } from '@cratis/scene.model';
+import { type ApplicationStructure, type NavigationModel, type Screen } from '@cratis/scene.model';
 import type { EffectiveNavItem } from '@cratis/scene.engine';
 import type { SceneNavigationModel } from '@cratis/scene.react';
-/** Whether the model declares navigation regions of its own - the application's or a module's. */
+/**
+ * Whether the model declares navigation items of its own - an application navigation outlet that lists items, or a module's refinement
+ * or contribution. An outlet that lists nothing only says where navigation goes: the entries the screens authored stay the menu.
+ */
 export declare function declaresRegions(navigation: NavigationModel | undefined): boolean;
 /**
  * The screen a navigation item opens: the screen declared in the feature the item resolves to (a screen's `path` is the modules and
  * features it was declared in), the first screen declared beneath it, or the screen named like the feature - which is how the
- * application structure names a feature's screen.
+ * application structure names a feature's screen. Only a screen that fits a page is a place to go: one that fits only a dialog, drawer,
+ * pane or panel is opened by an action, never navigated to.
  */
-export declare function stageScreenFor(screens: Screen[]): (item: EffectiveNavItem) => string | undefined;
+export declare function stageScreenFor(allScreens: Screen[]): (item: EffectiveNavItem) => string | undefined;
 /** The module a screen was declared in - the first of its `path` - which decides whose sidebar the page shows. */
 export declare function stageModuleOf(screens: Screen[]): (screen: string | undefined) => string | undefined;
 /**

package/dist/src/stageOutlets.d.ts

@@ -0,0 +1,40 @@
+import { type ReactNode } from 'react';
+import type { ApplicationStructure, Layout, NavigationModel, Screen, ScreenTemplate } from '@cratis/scene.model';
+import { type ActionSlice, type OutletLevel } from '@cratis/scene.engine';
+import { type SceneOutletsContextValue } from '@cratis/scene.react';
+/** The parts of a Stage application the outlets of a screen resolve through. */
+export interface StageOutletsSource {
+    layouts: Layout[];
+    screenTemplates: ScreenTemplate[];
+    screens: Screen[];
+    navigation?: NavigationModel;
+    outletLevels?: OutletLevel[];
+    structure?: ApplicationStructure;
+    commandSchemas?: Record<string, string>;
+}
+/**
+ * The slices the hooks of an application run, as placement and the slice invoker see them: each slice's command, its screen and where
+ * that screen fits, and the inputs its command takes - which an item or the route feed by name. The identifier the command acts on
+ * (`x-identity`) has the item or screen as its source, so a hook can run the slice directly; any other input needs the form.
+ *
+ * @param source The application.
+ * @returns The slices, by their qualified id.
+ */
+export declare function stageActionSlicesOf(source: StageOutletsSource): ActionSlice[];
+/**
+ * What the outlets of a screen resolve through: the levels from the layout down to the screen, the levels that contribute to them, the
+ * slices their hooks run, and the slots of the screen a hook can open in.
+ *
+ * @param source The application.
+ * @param screenName The screen.
+ * @returns The outlets' context.
+ */
+export declare function stageOutletsOf(source: StageOutletsSource, screenName: string | undefined): SceneOutletsContextValue;
+/**
+ * Gives the outlets of a screen what they resolve through (see {@link stageOutletsOf}).
+ */
+export declare function StageOutletsScope({ source, screen, children }: {
+    source: StageOutletsSource;
+    screen: string | undefined;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/src/stageSceneRouting.d.ts

@@ -0,0 +1,130 @@
+import { type Layout, type Screen, type ScreenTemplate } from '@cratis/scene.model';
+import { type OutletLevel } from '@cratis/scene.engine';
+import { type SceneHistory, type SceneRouter, type SceneRouteState, type SlotRoute } from '@cratis/scene.react';
+/**
+ * What the Stage needs to know of an application to put its routed slots, tabs and filters in the address.
+ */
+export interface StageRouteShape {
+    /** The routed slots - never a panel - by name, with the parameters each is routed by, in order. */
+    routedSlots: Record<string, string[]>;
+    /** The outlets of tabs that own a routed slot, with the slot each owns: the chosen tab is a segment of that slot. */
+    tabSlots: Record<string, string>;
+    /** The query parameter each filter writes, with the query it sets; undefined when it names none. */
+    filters: Record<string, string | undefined>;
+    /** Whether the page slot is routed, so the filters' values are in the address. */
+    pageRouted: boolean;
+    /** The screen a slot route's segment opens, by segment (`set-product-price`). */
+    segmentScreens: Record<string, string>;
+    /** The screen a slot shows for a selection (`show ProductDetails by sku from products.selection`), by slot. */
+    slotDefaults: Record<string, string>;
+}
+/** The parts of a Stage application the route shape is read from. */
+export interface StageRouteSource {
+    layouts?: Layout[];
+    screenTemplates?: ScreenTemplate[];
+    screens?: Screen[];
+    outletLevels?: OutletLevel[];
+}
+/** A shape with nothing routed: every slot, tab and filter stays in memory. */
+export declare const unroutedShape: StageRouteShape;
+/**
+ * Reads what is routed in an application: the routed slots of its layouts and templates, the outlets of tabs that own one, the parameters
+ * its filters write, whether its page slot is routed, and the screens a slot route can name.
+ *
+ * @param source The layouts, templates, screens and outlet levels of the application.
+ * @returns The route shape.
+ */
+export declare function stageRouteShapeOf(source: StageRouteSource): StageRouteShape;
+/** An address the Stage reads: the Scene navigation's part, and what the routed slots, tabs and filters say. */
+export interface StageAddress {
+    /** The part the Scene navigation host matches against its routes (`ProductCatalog?id=1`), or undefined when there is none. */
+    scene: string | undefined;
+    /** What the address says the routed slots, tabs and filters show. */
+    route: SceneRouteState;
+}
+/**
+ * Reads an address relative to the application (`ProductCatalog/@detail/NK-101/@detail.detailTabs/pricing?q=kettle`): the Scene
+ * navigation's part, then a group per routed slot (`@<slot>` with its route values and segment) and per chosen tab of a routed slot
+ * (`@<slot>.<outlet>` with the tab), and the filters' values among the query parameters when the page slot is routed.
+ *
+ * @param address The address, without a leading slash or hash.
+ * @param shape What is routed in the application.
+ * @returns The Scene navigation's part, and the route state.
+ */
+export declare function parseStageAddress(address: string, shape: StageRouteShape): StageAddress;
+/**
+ * Writes an address relative to the application from the Scene navigation's part and the route state - the reverse of
+ * {@link parseStageAddress}. Only what is routed is written: a slot that is not routed, a tab whose slot is not routed and, unless the
+ * page slot is routed, the filters' values stay out of the address.
+ *
+ * @param scene The Scene navigation's part.
+ * @param route The route state.
+ * @param shape What is routed in the application.
+ * @returns The address, without a leading slash or hash.
+ */
+export declare function stageAddress(scene: string | undefined, route: SceneRouteState, shape: StageRouteShape): string;
+/** How the Stage addresses screens: by the fragment (`#/Screen`) or by the path (`/Screen`). */
+export type StageRoutingMode = 'hash' | 'path';
+/** The browser the routing reads and writes the address of. */
+export type StageRoutingBrowser = Pick<Window, 'location' | 'history' | 'addEventListener' | 'removeEventListener'>;
+/**
+ * The Stage's router: one address for the Scene navigation host (its {@link SceneHistory}) and for the routed slots, tabs and filters
+ * (a {@link SceneRouter} through {@link useStageSceneRouter}).
+ */
+export interface StageSceneRouting {
+    /** The history the Scene navigation host reads and writes its part of the address through. */
+    history: SceneHistory;
+    /** The route state. */
+    getState(): SceneRouteState;
+    /** Listens for changes of the route state. */
+    subscribe(listener: () => void): () => void;
+    /** Opens a screen in a slot: a history entry when the slot is routed. */
+    openInSlot(slot: string, route: SlotRoute): void;
+    /** Empties a slot: a history entry when the slot is routed. */
+    closeSlot(slot: string): void;
+    /** Chooses a tab: a history entry when the slot the tabs own is routed. */
+    selectTab(outlet: string, tab: string): void;
+    /** Writes a filter's value: in the address, without a history entry, when the page slot is routed. */
+    setQueryParameter(name: string, value: string | undefined): void;
+    /** Stops listening to the browser. */
+    dispose(): void;
+}
+/**
+ * Creates the Stage's router over the browser's address.
+ *
+ * Only routed slot changes and chosen tabs are history entries, so back and forward move through them. A filter replaces the current
+ * entry. A dialog or drawer opened over the page does not change the address and is not a history entry either: the Scene navigation
+ * host's push of the same address replaces the entry, and closing it puts the page it opened over back.
+ *
+ * @param browser The browser.
+ * @param mode Whether screens are addressed by the fragment or by the path.
+ * @param shape What is routed in the application.
+ * @returns The routing.
+ */
+export declare function createStageSceneRouting(browser: StageRoutingBrowser, mode: StageRoutingMode, shape: StageRouteShape): StageSceneRouting;
+/**
+ * The {@link SceneRouter} of the Stage's routing, for `SceneRouterProvider`: a new one each time the route state changes, so what reads it
+ * draws again.
+ *
+ * @param routing The Stage's routing.
+ * @returns The router.
+ */
+export declare function useStageSceneRouter(routing: StageSceneRouting): SceneRouter;
+/** The route shape of the running application, for what reads the filters' values. */
+export declare const StageRouteShapeContext: import("react").Context<StageRouteShape>;
+/**
+ * The values the filters wrote for a query: those of the filters that set one of its parameters, and of those that name no query.
+ *
+ * @param shape What is routed in the application, and which query each filter sets.
+ * @param query The values the filters wrote, by query parameter.
+ * @param queryName The query.
+ * @returns The query's arguments from the filters.
+ */
+export declare function filterArgumentsFor(shape: StageRouteShape, query: Record<string, string>, queryName: string | undefined): Record<string, string>;
+/**
+ * The values the filters on the page wrote for a query.
+ *
+ * @param queryName The query.
+ * @returns The query's arguments from the filters.
+ */
+export declare function useStageFilterArguments(queryName: string | undefined): Record<string, string>;

package/dist/src/stageSlices.d.ts

@@ -12,7 +12,8 @@ export declare function sliceFieldsFrom(schemas: Record<string, string> | undefi
 /**
  * The invoker the running application submits a task dialog through: the command is posted to the route the Stage registered for
  * it, exactly as an action or a form posts it, and the application's own validation results come back to the dialog against the
- * fields they name. A successful command refreshes what the screen shows.
+ * fields they name. A successful command refreshes what the page shows. A hook that runs its slice directly (`runs`) comes through here
+ * too, once Scene has asked its confirmation, with the inputs the item and the route resolve.
  *
  * @param executeCommand Executes a registered Arc proxy with the host's configuration.
  * @param routesReady Whether the lookup has finished, so a command with no route is not-registered rather than not-yet.

package/dist/src/stageSlot.d.ts

@@ -0,0 +1,16 @@
+import { type RegisteredComponentProps } from '@cratis/scene.react';
+/**
+ * The `core:slot` the Stage renders, drawn inside the Stage's own data scope so the queries, selections and commands of the screen it
+ * shows work as they do on a primary screen.
+ *
+ * - A **routed** slot shows what the router says (the address, in the running application): a hook that opens a screen in it, or a
+ *   selection it shows, changes the address, and the address brings it back on a reload or a shared link. The screen it shows reads the
+ *   route values it was opened with - its own scope's parameters win over the page's - so `ProductDetails by sku` reads the row's sku.
+ * - A slot a `show <Screen> by <param> from <element>.selection` line stands in opens that screen, keyed by the selected row, whenever the
+ *   element's selection changes.
+ * - Otherwise it shows the screen the Scene navigation host placed in it (`navigate to … in slot side`).
+ *
+ * A panel is drawn as a landmark (`aside`), an optional slot is hidden until something fills it, and an optional pane or panel - like a
+ * slot the host put a screen in - can be closed.
+ */
+export declare function StageSlot({ element }: RegisteredComponentProps): import("react").JSX.Element | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/stage.runtime",
-  "version": "4.228.0",
+  "version": "5.0.0",
   "description": "The Cratis Stage application runtime for Arc and Scene",
   "author": "Cratis",
   "type": "module",
@@ -41,16 +41,16 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@cratis/arc": "22.168.0",
-    "@cratis/arc.react": "22.168.0",
+    "@cratis/arc": "22.176.0",
+    "@cratis/arc.react": "22.176.0",
     "@cratis/components": "4.40.0",
     "@cratis/fundamentals": "7.33.1",
-    "@cratis/scene.blueprint.default": "4.88.0",
-    "@cratis/scene.components": "4.88.0",
-    "@cratis/scene.engine": "4.88.0",
-    "@cratis/scene.model": "4.88.0",
-    "@cratis/scene.primereact": "4.88.0",
-    "@cratis/scene.react": "4.88.0",
+    "@cratis/scene.blueprint.default": "5.1.0",
+    "@cratis/scene.components": "5.1.0",
+    "@cratis/scene.engine": "5.1.0",
+    "@cratis/scene.model": "5.1.0",
+    "@cratis/scene.primereact": "5.1.0",
+    "@cratis/scene.react": "5.1.0",
     "@cratis/showrunner.notes": "1.0.0",
     "@cratis/showrunner.notes.react": "1.0.0",
     "@primereact/ui": "11.2.2",