@salsita-ai/sdk 0.50.0-develop.b7caacb493 → 0.50.0-develop.b929a82a82

package/dist/docs/3d-scene/rendering/scene-entity-object.mdx

@@ -39,8 +39,6 @@ components:
 Create the element using `createCustomPhoenixEntityElement()`:
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createCustomPhoenixEntityElement('HouseElement', () => (
   <group>
     <mesh position={[0, 40, 0]} castShadow>
@@ -174,7 +172,6 @@ export function Tree({ isWinter, foliageColors, scale }: TreeProps) {
 
 ```tsx
 // elements/SmallSummerTreeElement.tsx
-import { phx } from '../../.phoenix/phx.js'
 import { Tree } from '../_library/Tree.js'
 
 const SUMMER_FOLIAGE = ['#228b22', '#2e8b2e', '#32cd32']
@@ -1921,8 +1918,6 @@ import { useFrame } from '@react-three/fiber'
 import { useMemo, useRef } from 'react'
 import * as THREE from 'three'
 
-import { phx } from '../../.phoenix/phx.js'
-
 function Snowflakes() {
   const particlesRef = useRef<THREE.InstancedMesh>(null)
   const particleCount = 100
@@ -2079,7 +2074,6 @@ export default phx.frontend.createCustomPhoenixLayoutElement('CanvasEnvironment'
 ### ./src/elements/CircularSummerGardenElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { CircularGarden } from '../_library/Garden.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('CircularSummerGardenElement', () => (
@@ -2090,7 +2084,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('CircularSummerGard
 ### ./src/elements/CircularWinterGardenElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { CircularGarden } from '../_library/Garden.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('CircularWinterGardenElement', () => (
@@ -2101,7 +2094,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('CircularWinterGard
 ### ./src/elements/ClassicSummerHouseElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { ClassicHouse } from '../_library/ClassicHouse.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('ClassicSummerHouseElement', () => (
@@ -2112,7 +2104,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('ClassicSummerHouse
 ### ./src/elements/ClassicWinterHouseElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { ClassicHouse } from '../_library/ClassicHouse.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('ClassicWinterHouseElement', () => (
@@ -2123,7 +2114,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('ClassicWinterHouse
 ### ./src/elements/CottageSummerHouseElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { CottageHouse } from '../_library/CottageHouse.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('CottageSummerHouseElement', () => (
@@ -2134,7 +2124,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('CottageSummerHouse
 ### ./src/elements/CottageWinterHouseElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { CottageHouse } from '../_library/CottageHouse.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('CottageWinterHouseElement', () => (
@@ -2145,7 +2134,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('CottageWinterHouse
 ### ./src/elements/HexagonalSummerGardenElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { HexagonalGarden } from '../_library/Garden.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('HexagonalSummerGardenElement', () => (
@@ -2162,7 +2150,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('HexagonalSummerGar
 ### ./src/elements/HexagonalWinterGardenElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { HexagonalGarden } from '../_library/Garden.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('HexagonalWinterGardenElement', () => (
@@ -2173,7 +2160,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('HexagonalWinterGar
 ### ./src/elements/LargeSummerTreeElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { Tree } from '../_library/Tree.js'
 
 const SUMMER_FOLIAGE = ['#228b22', '#2e8b2e', '#32cd32']
@@ -2186,7 +2172,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('LargeSummerTreeEle
 ### ./src/elements/LargeWinterTreeElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { Tree } from '../_library/Tree.js'
 
 const WINTER_FOLIAGE = ['#f0f0f0', '#e8e8e8', '#ffffff']
@@ -2199,7 +2184,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('LargeWinterTreeEle
 ### ./src/elements/MediumSummerTreeElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { Tree } from '../_library/Tree.js'
 
 const SUMMER_FOLIAGE = ['#228b22', '#2e8b2e', '#32cd32']
@@ -2212,7 +2196,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('MediumSummerTreeEl
 ### ./src/elements/MediumWinterTreeElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { Tree } from '../_library/Tree.js'
 
 const WINTER_FOLIAGE = ['#f0f0f0', '#e8e8e8', '#ffffff']
@@ -2225,7 +2208,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('MediumWinterTreeEl
 ### ./src/elements/ModernCircularSummerFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { ModernFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('ModernCircularSummerFenceElement', () => (
@@ -2236,7 +2218,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('ModernCircularSumm
 ### ./src/elements/ModernCircularWinterFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { ModernFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('ModernCircularWinterFenceElement', () => (
@@ -2247,7 +2228,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('ModernCircularWint
 ### ./src/elements/ModernHexagonalSummerFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { ModernFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('ModernHexagonalSummerFenceElement', () => (
@@ -2258,7 +2238,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('ModernHexagonalSum
 ### ./src/elements/ModernHexagonalWinterFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { ModernFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('ModernHexagonalWinterFenceElement', () => (
@@ -2269,7 +2248,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('ModernHexagonalWin
 ### ./src/elements/ModernSquareSummerFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { ModernFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('ModernSquareSummerFenceElement', () => (
@@ -2280,7 +2258,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('ModernSquareSummer
 ### ./src/elements/ModernSquareWinterFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { ModernFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('ModernSquareWinterFenceElement', () => (
@@ -2291,7 +2268,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('ModernSquareWinter
 ### ./src/elements/ModernSummerHouseElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { ModernHouse } from '../_library/ModernHouse.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('ModernSummerHouseElement', () => (
@@ -2302,7 +2278,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('ModernSummerHouseE
 ### ./src/elements/ModernWinterHouseElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { ModernHouse } from '../_library/ModernHouse.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('ModernWinterHouseElement', () => (
@@ -2313,7 +2288,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('ModernWinterHouseE
 ### ./src/elements/PicketCircularSummerFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { PicketFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('PicketCircularSummerFenceElement', () => (
@@ -2324,7 +2298,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('PicketCircularSumm
 ### ./src/elements/PicketCircularWinterFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { PicketFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('PicketCircularWinterFenceElement', () => (
@@ -2335,7 +2308,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('PicketCircularWint
 ### ./src/elements/PicketHexagonalSummerFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { PicketFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('PicketHexagonalSummerFenceElement', () => (
@@ -2346,7 +2318,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('PicketHexagonalSum
 ### ./src/elements/PicketHexagonalWinterFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { PicketFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('PicketHexagonalWinterFenceElement', () => (
@@ -2357,7 +2328,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('PicketHexagonalWin
 ### ./src/elements/PicketSquareSummerFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { PicketFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('PicketSquareSummerFenceElement', () => (
@@ -2368,7 +2338,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('PicketSquareSummer
 ### ./src/elements/PicketSquareWinterFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { PicketFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('PicketSquareWinterFenceElement', () => (
@@ -2379,7 +2348,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('PicketSquareWinter
 ### ./src/elements/SmallSummerTreeElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { Tree } from '../_library/Tree.js'
 
 const SUMMER_FOLIAGE = ['#228b22', '#2e8b2e', '#32cd32']
@@ -2392,7 +2360,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('SmallSummerTreeEle
 ### ./src/elements/SmallWinterTreeElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { Tree } from '../_library/Tree.js'
 
 const WINTER_FOLIAGE = ['#f0f0f0', '#e8e8e8', '#ffffff']
@@ -2405,7 +2372,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('SmallWinterTreeEle
 ### ./src/elements/SquareSummerGardenElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { SquareGarden } from '../_library/Garden.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('SquareSummerGardenElement', () => (
@@ -2416,7 +2382,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('SquareSummerGarden
 ### ./src/elements/SquareWinterGardenElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { SquareGarden } from '../_library/Garden.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('SquareWinterGardenElement', () => (
@@ -2427,7 +2392,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('SquareWinterGarden
 ### ./src/elements/StoneCircularSummerFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { StoneFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('StoneCircularSummerFenceElement', () => (
@@ -2438,7 +2402,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('StoneCircularSumme
 ### ./src/elements/StoneCircularWinterFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { StoneFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('StoneCircularWinterFenceElement', () => (
@@ -2449,7 +2412,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('StoneCircularWinte
 ### ./src/elements/StoneHexagonalSummerFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { StoneFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('StoneHexagonalSummerFenceElement', () => (
@@ -2460,7 +2422,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('StoneHexagonalSumm
 ### ./src/elements/StoneHexagonalWinterFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { StoneFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('StoneHexagonalWinterFenceElement', () => (
@@ -2471,7 +2432,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('StoneHexagonalWint
 ### ./src/elements/StoneSquareSummerFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { StoneFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('StoneSquareSummerFenceElement', () => (
@@ -2482,7 +2442,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('StoneSquareSummerF
 ### ./src/elements/StoneSquareWinterFenceElement.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { StoneFence } from '../_library/Fence.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('StoneSquareWinterFenceElement', () => (
@@ -2495,8 +2454,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('StoneSquareWinterF
 ```ts
 import { match } from 'ts-pattern'
 
-import { phx } from '../../.phoenix/phx.js'
-
 const SMOKE_POSITIONS = {
   classic: { x: 25, y: 125, z: -10 },
   modern: { x: -45, y: 85, z: 25 },

package/dist/docs/3d-scene/rendering/smma.mdx

@@ -192,7 +192,6 @@ export const SmaaControls = () => {
 import { memoEval, propertyPageComponent } from '@salsita-ai/sdk/domain'
 
 import { getConsoleRenderingComponents } from '../../../../common/console-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 import { SmaaControls } from '../_shared/SmaaControls.js'
 
 export default [
@@ -221,7 +220,6 @@ import { useObservableEagerState } from 'observable-hooks'
 
 import { Postprocessing } from '@salsita-ai/sdk/configurator'
 
-import { phx } from '../../.phoenix/phx.js'
 import { smaaState$ } from '../_shared/SmaaControls.js'
 
 export default phx.frontend.createCustomPhoenixLayoutElement('CanvasEnvironment', () => {

package/dist/docs/3d-scene/rendering/soft-shadows.mdx

@@ -196,8 +196,6 @@ components:
 ```tsx
 import { Environment } from '@react-three/drei'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createCustomPhoenixLayoutElement('CanvasEnvironment', () => {
   return (
     <>

package/dist/docs/3d-scene/rendering/transformer.mdx

@@ -227,7 +227,6 @@ import { PropertyContainer } from '@salsita-ai/sdk/ui'
 
 import { EGemCut, isGemUserData } from '../../../../common/gem-rendering/gem.js'
 import { renderGem } from '../../../../common/gem-rendering/render-gem.js'
-import { phx } from '../../.phoenix/phx.js'
 import { GemColorSwatchMap } from '../_shared/swatches.js'
 
 export default [
@@ -307,7 +306,6 @@ export default [
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { GemColorSwatchMap } from '../_shared/swatches.js'
 
 export default phx.domain.implementCustomExpressions({

package/dist/docs/complex-use-cases/custom-ui-on-root-level.mdx

@@ -81,7 +81,6 @@ import { propertyPageComponent } from '@salsita-ai/sdk/domain'
 
 import { MockSidebarOne } from '../../../../common/MockSidebar'
 import { getMockChairComponents } from '../../../../common/mock-chair-model/mock-chair-model-components'
-import { phx } from '../../.phoenix/phx.js'
 
 export default [
   phx.domain.attachComponent

package/dist/docs/complex-use-cases/filtered-controls-with-fix-dialog.mdx

@@ -24,7 +24,7 @@ Here is an example of several dependent options.
 The solution here is that the attributes higher in the UI are always changable independent of lower selection.
 This is achieved by setting a default value if invariant would be broken.
 
-If the change would break the countersink invariant, there is `FilteredControls` shown prompting user to make a decision.
+If the change would break the countersink invariant, there is a `FixDialog` shown prompting user to make a decision.
 
 ### Code #1
 
@@ -64,9 +64,12 @@ export default phx.domain.implementCustomInvariants({
 })
 ```
 
-With following control structure. Note the hierarchy of `fixableViolations`. The top input "fixes" all violations as it should never be disabled.
-The next one may be disabled if the material violation is active, etc...
-All inputs include countersinkNotAvailable, as that is fixable by auto fix dialog separately.
+With following control structure. The transformers below keep the upper inputs enabled: when a material or finish
+change would break a lower invariant, the transformer changes the lower properties in the same change, so the dry run
+of that option has no violation. `fixableViolations` does not enable anything: it only leaves the listed violation
+types out of the input's hint text, and an option whose change still causes a `fatal` violation stays disabled.
+The hierarchy of `fixableViolations` follows the selection order: each input leaves out the violations below it, which
+its transformer repairs. All inputs leave out `countersinkNotAvailable`, which the fix dialog presents separately.
 
 ```tsx
 <PropertyContainer.Item title="Material" description="Select one of the available materials for the plate.">
@@ -189,15 +192,17 @@ transformers:
   - name: fix-material
 ```
 
-And FilteredControls
+And the `FixDialog` in `src/elements/LayoutDialog.tsx`, shown when the first violation of the last attempted
+commit in the `potentiallyInvalid` slice is `countersinkNotAvailable`
 
 ```tsx
-<FilteredControls
+<FixDialog
+  open={potentiallyInvalid !== suppressed}
   title="Autofix"
   onFix={() => {
-    const plate = potentiallyInvalid.state.domainState.entities.find(Plate.is)!
+    const plate = potentiallyInvalid.state.entities.find(phx.domain.model.Plate.is)!
 
-    const update = updateFactory.DomainEntityModification({
+    const update = phx.frontend.updates.DomainEntityModification({
       entityId: plate.id,
       updateTag: 'fix.removeCountersink',
       stateDelta: {
@@ -209,9 +214,14 @@ And FilteredControls
 
     setSuppressed(potentiallyInvalid)
   }}
+  onClose={() => {
+    setSuppressed(potentiallyInvalid)
+  }}
+  cancelButtonTitle="Cancel"
+  fixButtonTitle="Fix"
 >
   Counter sinks are only available for plates with thickness of 40mm. Countersinks will be removed!
-</FilteredControls>
+</FixDialog>
 ```
 
 ## Use case #2
@@ -474,8 +484,6 @@ transformers:
 ### ./src/\_shared/available-materials.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export const availableMaterials = [
   {
     material: phx.domain.model.MaterialType.Brass,
@@ -517,8 +525,6 @@ import {
 } from '@salsita-ai/sdk/react'
 import { PropertyContainer } from '@salsita-ai/sdk/ui'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default [
   phx.domain.attachComponent
     .withComponent(propertyPageComponent, 'main')
@@ -587,7 +593,6 @@ import type { StateUpdateEmission } from '@salsita-ai/sdk/domain'
 import { FixDialog } from '@salsita-ai/sdk/ui'
 
 import type * as Model from '../../.phoenix/application-types.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default phx.frontend.createLayoutDialog(() => {
   const [suppressed, setSuppressed] = useState<null | StateUpdateEmission<Model.AnyDomainEntity, Model.$Map>>(null)
@@ -652,8 +657,6 @@ export default phx.frontend.createLayoutDialog(() => {
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 const swatches = {
   [phx.domain.model.MaterialType.Brass]: {
     swatchName: 'Brass',
@@ -695,7 +698,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { availableMaterials } from '../_shared/available-materials.js'
 
 const counterSinkThicknesses = [40]
@@ -720,7 +722,6 @@ export default phx.domain.implementCustomInvariants({
 ### ./src/transformers/fix-finish.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { availableMaterials } from '../_shared/available-materials.js'
 
 export default phx.frontend.transformerBuilder.when
@@ -762,7 +763,6 @@ export default phx.frontend.transformerBuilder.when
 ### ./src/transformers/fix-material.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { availableMaterials } from '../_shared/available-materials.js'
 
 export default phx.frontend.transformerBuilder.when

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>>>>