@salsita-ai/sdk 0.50.0-develop.f101f4c3c9 → 0.50.0-develop.f354d3576d

package/dist/docs/complex-use-cases/navigation-guard.mdx

@@ -1,4 +1,4 @@
-# NavigationGuard
+# Navigation Guard
 
 - [Use case](#use-case)
 - [Guide](#guide)
@@ -8,40 +8,105 @@
 
 ## Use case
 
-Describe the use case for this story. What problem does it solve? When should this pattern be used?
+Ask the user to confirm a navigation before it happens, when it would cost them work. A stepped configurator, such as a kitchen planner whose first step picks the room shape and whose later steps place the cabinets, warns the user who goes back to the first step, and navigates only when they confirm.
 
-## Guide
+The guard is a hook that runs before every change is committed. It holds the navigation it wants confirmed, shows a dialog, and commits the held navigation when the user confirms.
+
+To reset something when the user arrives at a step instead of asking first, see [Navigation Reset Undo](?path=/docs/complex-use-cases-navigation-reset-undo--docs) and [Navigation Reset Selection](?path=/docs/complex-use-cases-navigation-reset-selection--docs).
 
-Provide a step-by-step guide on how to implement this pattern.
+## Guide
 
 ### Step 1 — Domain
 
-Explain the domain configuration needed:
+Declare the navigation states and a component the user navigates with:
 
 ```yaml
-# Add your domain YAML example here
+navigationStates:
+  - 'FirstStep'
+  - 'SecondStep'
+  - 'ThirdStep'
 ```
 
-### Step 2 — Frontend (if needed)
+The example attaches its `navigationSteps` component and the property pages in `src/components/components.tsx`; [Application States → Navigation States](?path=/docs/phoenix-application-states--docs#navigation-states) shows the same components in YAML. Nothing in the spec refers to the guard.
+
+### Step 2 — Frontend: a commit hook
 
-Explain any custom frontend components or hooks needed:
+Mount the guard in a provider that wraps the configurator, the default export of a file in `src/elements/`:
 
 ```tsx
-// Add your frontend code examples here
+// src/elements/OnConfiguratorReady.tsx
+export default phx.frontend.createOnConfiguratorReadyProvider(({ children }) => {
+  return (
+    <>
+      <NavigationGuard />
+      {children}
+    </>
+  )
+})
 ```
 
-## Example
+`NavigationGuard` takes the store system from `phx.frontend.useDomain()` and registers a hook with `storeSystem.onBeforeCommit(hook)`, which returns the function that unregisters it. The hook receives the change about to be committed, `emission`, and an `emit` callback:
+
+- Return `true`, or nothing, to let the change through.
+- Return `false` to hold it: nothing is committed, and the rendered state goes back to the committed one.
+- Call `emit()` later to commit the held change. Every hook runs again with the same `emission`, so the guard recognises it and lets it through.
+
+The guard holds a navigation to the first step and keeps the held emission in state until the user answers (abridged; the complete file is below):
 
-Interact with the example below:
+```tsx
+// src/elements/OnConfiguratorReady.tsx
+import { isNavigationUpdate } from '@salsita-ai/sdk/domain'
 
-- Describe what users should try in the example
-- List key interactions to test
+const { storeSystem } = phx.frontend.useDomain()
+
+useEffect(() => {
+  const unregister = storeSystem.onBeforeCommit((emission, emit) => {
+    // The held navigation, committed again by emit() after the user confirmed
+    if (emission === warningShown?.emission) {
+      return true
+    }
+
+    if (warningShown != null) {
+      return true
+    }
+
+    const updates = emission.updates
+    const update = updates[0]
+
+    if (update == null || updates.length > 1 || !isNavigationUpdate(update)) {
+      return true
+    }
+
+    if (update.writableState.activeState !== phx.applicationTypes.NavigationState.FirstStep) {
+      return true
+    }
+
+    setWarningShown({ emission, emit })
+
+    return false
+  })
+
+  return () => {
+    unregister()
+  }
+}, [storeSystem, warningShown])
+```
+
+The dialog's **Confirm** calls `warningShown.emit()` and clears the state; **Cancel** only clears it, so the navigation is dropped.
+
+- **One update per navigation.** The guard reads only an emission with a single navigation update. A navigation that arrives together with other updates goes through unguarded; a guard for that case looks through all of `emission.updates`.
+- **Guard what is lost.** When a transformer turns the navigation into a destructive change, the guard can look for that change in `emission.updates` instead of the navigation itself.
+
+## Example
+
+Go to **Second step** or **Third step**, then click **First step**: a dialog warns that you will lose your progress. **Cancel** keeps you on the current step; **Confirm** goes to the first step. Moving forward shows no dialog.
 
 ## Test cases
 
-- List specific test cases that validate this implementation
-- Include edge cases and expected behaviors
-- Cover error states and boundary conditions
+- From the second or third step, clicking **First step** opens the dialog and the step does not change.
+- **Cancel** closes the dialog and the current step stays active.
+- **Confirm** closes the dialog and the first step becomes active.
+- Navigating from the first step to the second or third, or between the second and third, shows no dialog.
 
 ## Complete Implementation
 
@@ -86,7 +151,6 @@ import { navigationStepsComponent, propertyPageComponent } from '@salsita-ai/sdk
 
 import { MockSidebarOne, MockSidebarTwo } from '../../../../common/MockSidebar.js'
 import { getMockChairComponents } from '../../../../common/mock-chair-model/mock-chair-model-components.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default [
   ...getMockChairComponents('Scene', phx.domain.attachComponent),
@@ -142,8 +206,6 @@ import { useCallback, useEffect, useState } from 'react'
 import type { $DomainEntity, DomainEntity, StateUpdateEmission } from '@salsita-ai/sdk/domain'
 import { isNavigationUpdate } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
-
 const NavigationGuard = () => {
   const [warningShown, setWarningShown] = useState<{
     emission: StateUpdateEmission<DomainEntity<string>, Record<string, $DomainEntity<DomainEntity<string>>>>

package/dist/docs/complex-use-cases/navigation-reset-selection.mdx

@@ -8,7 +8,7 @@
 
 ## Use case
 
-The `createResetSelectionOnNavigationTransformer` automatically deselects entities when the user navigates to specific steps. This clears the active selection when entering certain workflow phases, ensuring users start each step without inherited selections.
+A transformer built with `when.navigated({ to: [...] }).then.deselect()` automatically deselects entities when the user navigates to specific steps. This clears the active selection when entering certain workflow phases, ensuring users start each step without inherited selections.
 
 **Scenarios** - Use this transformer when you need:
 
@@ -18,30 +18,30 @@ The `createResetSelectionOnNavigationTransformer` automatically deselects entiti
 
 ## Guide
 
-The `createResetSelectionOnNavigationTransformer` is added as a file in `src/transformers/`. It automatically injects a deselect update when navigating to specified states.
+The transformer is added as a file in `src/transformers/`. It automatically deselects when navigating to specified states.
 
-### Step 1: Import the transformer
+### Step 1: Add the transformer to your project
 
-Import the transformer function from the domain package:
+Create the transformer in a file under `src/transformers/`:
 
 ```typescript
-import { createResetSelectionOnNavigationTransformer } from '@salsita-ai/sdk/domain'
+// src/transformers/reset-selection.ts
+export default phx.frontend.transformerBuilder.when
+  .navigated({
+    to: [phx.applicationTypes.NavigationState.SecondStep],
+  })
+  .then.deselect()
+  .build('reset-selection')
 ```
 
-### Step 2: Add the transformer to your project
-
-Create the transformer in a file under `src/transformers/`:
+The transformer has two parts:
 
-```typescript
-// src/transformers/reset-selection.ts
-import { createResetSelectionOnNavigationTransformer } from '@salsita-ai/sdk/domain'
+- `navigated({ to: [...] })` lists the navigation states that should trigger deselection
+- `then.deselect()` deselects the selected entity
 
-export default phx.frontend.createTransformer(ctx =>
-  createResetSelectionOnNavigationTransformer([phx.applicationTypes.NavigationState.SecondStep], ctx)
-)
-```
+### Step 2: Turn the transformer on in the spec
 
-Each file in `src/transformers/` default-exports one transformer and is picked up by its location. The `transformers` section of the spec turns it on by name. For a transformer made with `build(name)` that is the name passed to `build(...)`, which must match the file name with case and dashes ignored (`fix-finish.ts` and `fixFinish` match). For a plain-function export it is the file name:
+Each file in `src/transformers/` default-exports one transformer and is picked up by its location. The `transformers` section of the spec turns it on by the name passed to `build(...)`, spelled exactly; the name must also match the file name with case and dashes ignored (`fix-finish.ts` and `fixFinish` match):
 
 ```yaml
 # spec/application.yaml
@@ -49,12 +49,7 @@ transformers:
   - name: reset-selection
 ```
 
-The transformer takes two arguments:
-
-- An array of navigation state names that should trigger deselection
-- The domain context object (`ctx`)
-
-The `priority` value determines when this transformer runs relative to other transformers. Lower numbers run first. System transformers typically run at priority 100, so use values below 100 for custom transformers that should run before system logic.
+An entry without a `priority` runs after the SDK's built-in transformers, in the order of the `transformers` section. A `priority` value moves it: the pipeline runs lower numbers first, and the default is `Infinity`. See [Transformers](?path=/docs/other-features-transformers--docs#transformer-pipeline) for the built-in priorities.
 
 ### Step 3: Define navigation states in YAML
 
@@ -72,10 +67,9 @@ navigationStates:
 You can deselect at multiple navigation states by adding more state names to the array:
 
 ```typescript
-transformer: createResetSelectionOnNavigationTransformer(
-  [ApplicationTypes.NavigationState.SecondStep, ApplicationTypes.NavigationState.Summary],
-  ctx
-)
+.navigated({
+  to: [phx.applicationTypes.NavigationState.SecondStep, phx.applicationTypes.NavigationState.Summary],
+})
 ```
 
 This deselects when entering either the SecondStep or Summary navigation states.
@@ -86,39 +80,11 @@ The transformer intercepts update batches and:
 
 1. Checks if any update is a navigation update
 2. Verifies if the new active state matches one of the specified states
-3. Injects a deselect update into the update batch
+3. Adds a deselect update to the batch, in place of any selection update the batch holds
 4. Returns the modified batch with both the navigation and deselect updates
 
 When the transformer triggers, any selected entity is deselected automatically. Users see the selection clear when they navigate to the configured state.
 
-### Transformer signature
-
-```typescript
-/**
- * Creates a transformer that resets selection when navigating to specified states.
- *
- * The transformer monitors navigation updates and automatically injects a deselect
- * update when the active state matches any of the provided navigation states.
- * This ensures entities are deselected when entering specific workflow phases.
- *
- * @param navigationStates - Array of navigation state names that trigger deselection
- * @param ctx - Domain context providing access to the navigation system
- * @returns Update transformer to return from a transformer file in src/transformers/
- *
- * @example
- * // Deselect when entering the summary step
- * createResetSelectionOnNavigationTransformer(['Summary'], ctx)
- *
- * @example
- * // Deselect at multiple workflow phases
- * createResetSelectionOnNavigationTransformer(['ConfigComplete', 'Summary', 'Checkout'], ctx)
- */
-function createResetSelectionOnNavigationTransformer<NAVIGATION_STATES extends string>(
-  navigationStates: NAVIGATION_STATES[],
-  ctx: DomainContext
-): UpdateTransformer
-```
-
 ### Understanding transformers
 
 Transformers are functions that can modify update batches before they're committed to the store. They allow you to:
@@ -127,7 +93,7 @@ Transformers are functions that can modify update batches before they're committ
 - Modify existing updates (like changing values or constraints)
 - Prevent certain updates from being applied
 
-The `createResetSelectionOnNavigationTransformer` adds a deselect update whenever navigation matches configured states, keeping your workflow clean and predictable.
+The `reset-selection` transformer adds a deselect update whenever navigation matches configured states, keeping your workflow clean and predictable. [Transformers](?path=/docs/other-features-transformers--docs) covers the other triggers and actions of `phx.frontend.transformerBuilder`.
 
 ## Example
 
@@ -261,8 +227,6 @@ transformers:
 import { SelectionHotspot } from '@salsita-ai/sdk/configurator'
 import { htmlHotspotComponent, memoEval } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default [
   phx.domain.attachComponent
     .withComponent(htmlHotspotComponent, 'main')
@@ -285,13 +249,12 @@ export default [
 ### ./src/transformers/reset-selection.ts
 
 ```ts
-import { createResetSelectionOnNavigationTransformer } from '@salsita-ai/sdk/domain'
-
-import { phx } from '../../.phoenix/phx.js'
-
-export default phx.frontend.createTransformer(ctx =>
-  createResetSelectionOnNavigationTransformer([phx.applicationTypes.NavigationState.SecondStep], ctx)
-)
+export default phx.frontend.transformerBuilder.when
+  .navigated({
+    to: [phx.applicationTypes.NavigationState.SecondStep],
+  })
+  .then.deselect()
+  .build('reset-selection')
 ```
 
 </details>

package/dist/docs/complex-use-cases/navigation-reset-undo.mdx

@@ -18,7 +18,7 @@ The `ResetUndoListener` component clears the undo/redo history when the user nav
 
 ## Guide
 
-The `ResetUndoListener` is added to your configurator through the `OnLoadProvider` in the build configuration. It listens for navigation changes and clears the undo stack when entering specified states.
+The `ResetUndoListener` is mounted in a provider created with `phx.frontend.createOnConfiguratorReadyProvider`. It listens for navigation changes and clears the undo stack when entering specified states.
 
 ### Step 1: Import the component
 
@@ -28,20 +28,21 @@ Import `ResetUndoListener` from the configurator package:
 import { ResetUndoListener } from '@salsita-ai/sdk/configurator'
 ```
 
-### Step 2: Add the listener to your config
+### Step 2: Add the listener to your configurator
 
-Use the `OnLoadProvider` in your build configuration to mount the listener:
+Mount the listener in a provider that wraps the configurator, the default export of a file in `src/elements/`:
 
-```typescript
-const config = configuratorBuilder.buildConfig({
-  ui: {
-    OnLoadProvider: ({ children }) => (
-      <>
-        <ResetUndoListener navigationStates={[ApplicationTypes.NavigationState.SecondStep]} />
-        {children}
-      </>
-    ),
-  },
+```tsx
+// src/elements/OnConfiguratorReady.tsx
+import { ResetUndoListener } from '@salsita-ai/sdk/configurator'
+
+export default phx.frontend.createOnConfiguratorReadyProvider(({ children }) => {
+  return (
+    <>
+      <ResetUndoListener navigationStates={[phx.applicationTypes.NavigationState.SecondStep]} />
+      {children}
+    </>
+  )
 })
 ```
 
@@ -62,12 +63,9 @@ navigationStates:
 
 You can reset the undo stack at multiple navigation states by adding more state names to the array:
 
-```typescript
+```tsx
 <ResetUndoListener
-  navigationStates={[
-    ApplicationTypes.NavigationState.SecondStep,
-    ApplicationTypes.NavigationState.Summary
-  ]}
+  navigationStates={[phx.applicationTypes.NavigationState.SecondStep, phx.applicationTypes.NavigationState.Summary]}
 />
 ```
 
@@ -222,8 +220,6 @@ components:
 ```tsx
 import { ResetUndoListener } from '@salsita-ai/sdk/configurator'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createOnConfiguratorReadyProvider(({ children }) => {
   return (
     <>

package/dist/docs/complex-use-cases/sketching.mdx

@@ -626,7 +626,7 @@ const handles = ctx.sketchingProjections.getSketchingHandlePoints(state, s.$scen
 
 Rendering note: sketching doesn’t render shapes for you. In this example, visuals come from simple custom Three.js shapes attached to the entities; feel free to swap in your own renderer.
 
-Useful references in code: `sceneEntitySelectHotspot`, `sceneEntityDeleteFab`, `sceneEntityCustomObjectComponent`, `sketching-projections.ts` (cache + API), `sketching.ts` (connections/epsilon).
+Useful references in code: `sceneEntitySelectHotspot`, `sceneEntityDeleteFab`, `sceneEntityObjectComponent`, `sketching-projections.ts` (cache + API), `sketching.ts` (connections/epsilon).
 
 ## Common pitfalls
 
@@ -659,7 +659,7 @@ The example starts with two Stairs entities connected at a 90‑degree angle, fo
 import * as THREE from 'three'
 
 import { createConfiguratorInterface } from '@salsita-ai/sdk/configurator'
-import { isSelectUpdate, memoEval, sceneEntityCustomObjectComponent } from '@salsita-ai/sdk/domain'
+import { isSelectUpdate, memoEval, sceneEntityObjectComponent } from '@salsita-ai/sdk/domain'
 import { Editor } from '@salsita-ai/sdk/editor'
 
 import { FullscreenWCTemplate } from '../common/page-templates/FullscreenWCTemplate.js'
@@ -993,8 +993,6 @@ import * as THREE from 'three'
 
 import { distanceUnitToDefault, memoEval, sceneEntityObjectComponent } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
-
 const renderSurfaceDrawing = (length: number) => {
   const lineShape = new THREE.Shape()
 
@@ -1091,8 +1089,6 @@ export default [
 ```ts
 import { memoEval } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Scene: {
     $recipes: memoEval(
@@ -1189,8 +1185,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 interface Point {
   readonly x: number
   readonly y: number
@@ -1375,8 +1369,6 @@ export default phx.domain.implementCustomInvariants({
 ```ts
 import { isSelectUpdate } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.transformerBuilder.when
   .entity(phx.domain.model.AnyDomainEntity.types)
   .created()