@salsita-ai/sdk 0.50.0-develop.d6ed5efd42 → 0.50.0-develop.d7ce7f7857

package/dist/docs/layouts/header/fixed.mdx

@@ -145,7 +145,7 @@ interface HorizontalTab {
   /**
    * List of navigation states when the tab is active. First one will be used for activation.
    */
-  readonly navigationStates: string[]
+  readonly navigationStates: readonly string[]
 }
 ```
 
@@ -158,7 +158,7 @@ type HorizontalTabsComponentState = {
   /**
    * List of tabs in the horizontal tabs.
    */
-  readonly tabs: HorizontalTab[]
+  readonly tabs: readonly HorizontalTab[]
 }
 ```
 

package/dist/docs/layouts/header/floating.mdx

@@ -110,11 +110,11 @@ The configuration uses these component types:
 ```typescript
 export interface NavigationStep {
   readonly label: Localizable
-  readonly navigationStates: string[]
+  readonly navigationStates: readonly string[]
 }
 
 export type NavigationStepsComponentState = {
-  readonly steps: NavigationStep[]
+  readonly steps: readonly NavigationStep[]
 }
 ```
 

package/dist/docs/layouts/sidebar/in-a-custom-layout.mdx

@@ -0,0 +1,380 @@
+# Sidebar in a Custom Layout
+
+- [Use case](#use-case)
+- [Guide](#guide)
+- [Example](#example)
+- [Known gaps](#known-gaps)
+- [Test cases](#test-cases)
+- [Complete Implementation](#complete-implementation)
+
+## Use case
+
+A project wants the configurator arranged differently, for example with the sidebar on the left, but the sidebar itself is right as it is: the spec's tabs, property pages and sidebar footer, with their spacing, scrolling and empty states. The project writes its own layout, a `ConfiguratorLayout` element, and places the built-in sidebar in it as one piece, `LayoutSlots.DesktopSidebar`. The spec keeps describing what the sidebar shows; the layout only decides where it goes.
+
+Build the sidebar's controls yourself instead when they have to look like the brand's own, as [Custom Layout](?path=/docs/layouts-custom-layout--docs) does; [Configurator Interface → Loaded Configuration UI](?path=/docs/phoenix-configurator-interface--docs#loaded-configuration-ui) lists what a project layout can use. Stay with the built-in layout when its arrangement fits: [Sidebar - General](?path=/docs/layouts-sidebar-general--docs) describes what the spec configures in the sidebar.
+
+## Guide
+
+The layout registers itself under the name `ConfiguratorLayout` and mounts the scene, the safe area and the sidebar:
+
+```tsx
+// src/elements/ConfiguratorLayout.tsx
+import { LayoutSlots, useSceneSafeArea } from '@salsita-ai/sdk/configurator'
+
+import { phx } from '../../.phoenix/phx.js'
+
+const GUTTER = 24
+const SIDEBAR_WIDTH = 380
+
+const ConfiguratorLayout = () => {
+  const { containerRef, safeAreaRef } = useSceneSafeArea()
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+
+  return (
+    <div ref={containerRef} style={{ position: 'absolute', inset: 0 }}>
+      <LayoutSlots.Services />
+      <LayoutSlots.SharedCanvas />
+
+      {!isFullscreen && (
+        <aside
+          style={{
+            position: 'absolute',
+            insetBlock: GUTTER,
+            insetInlineStart: GUTTER,
+            inlineSize: SIDEBAR_WIDTH,
+          }}
+        >
+          <LayoutSlots.DesktopSidebar side="start" />
+        </aside>
+      )}
+
+      <div
+        ref={safeAreaRef}
+        style={{
+          position: 'absolute',
+          insetBlock: 0,
+          insetInlineStart: isFullscreen ? 0 : SIDEBAR_WIDTH + 2 * GUTTER,
+          insetInlineEnd: 0,
+          pointerEvents: 'none',
+        }}
+      >
+        <div style={{ position: 'absolute', insetBlockEnd: GUTTER, insetInlineStart: GUTTER, pointerEvents: 'auto' }}>
+          <LayoutSlots.DesktopToolbar />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+```
+
+- **Size the container.** Without `width`, `LayoutSlots.DesktopSidebar` fills the width and height of its container. The layout positions the container above the canvas and gives it a size, here a fixed width and the full height less a gutter. The sidebar's content scrolls inside that height and its footer stays at the bottom.
+- **Say which side it is on.** The sidebar's tabs sit outside it. With `side="start"` they sit on its right, toward the scene; the default, `side="end"`, puts them on its left, as in the built-in layout.
+- **Frame the scene beside it.** `useSceneSafeArea()` measures the free region right of the sidebar, so the camera frames the table there.
+- **Decide what fullscreen does.** In fullscreen the sidebar stays in place, transparent and inert. This layout removes it while `phx.frontend.useIsFullscreenActive()` is set and lets the safe area start at the left edge, so the table is framed in the whole canvas. The toolbar's fullscreen button sets the flag.
+- **Read mode.** The same element renders a configuration shared for viewing. The sidebar handles read mode itself: it applies the spec's `$filter.modes`, so the tabs, which the spec limits to owners, are gone and the footer shows the price only. The banner that offers **Edit configuration** to a viewer is the layout's to mount: the built-in layout shows `LayoutSlots.DesktopReadonlyBanner` in read mode outside fullscreen, and it renders only when the spec sets `shareCloneToEdit` and the viewer's role may create configurations. This spec does not set it, so this layout mounts no banner.
+
+`LayoutSlots.DesktopSidebar` takes two optional props:
+
+| Prop    | Type                 | Default | Meaning                                                                                                                                                          |
+| ------- | -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `width` | CSS width            | none    | Fixed inline size; the sidebar then takes its content's height unless its container stretches it. Without it the sidebar fills its container's width and height. |
+| `side`  | `'start'` \| `'end'` | `'end'` | The side of the layout the sidebar is on; its tabs sit on the other side of it.                                                                                  |
+
+Its look follows the theme component `PhxDesktopSidebar`, as in the built-in layout, see [Theming](?path=/docs/phoenix-theming--docs).
+
+## Example
+
+The spec is a table with one property, its edge finish, on a **Design** tab and a short text on a **Details** tab, and a price. Nothing in the YAML refers to the layout.
+
+## Known gaps
+
+- The footer is the basic sidebar footer, as in the built-in layout when the spec configures none. Its finalize button is disabled unless the spec configures the legacy `finalizeButton` or `finalizePage` components, which are declared only in TypeScript, and a project layout shows a `finalizePage` only if it renders it. New projects finalize over `finalizeAction` components, which the universal sidebar footer offers when the spec configures `universalSidebarFooter`.
+- `LayoutSlots.DesktopSidebar` is the desktop sidebar. At phone width a project layout needs its own arrangement, for example the `Mobile*` members of `LayoutSlots`, listed in [Layout Slots](?path=/docs/phoenix-layout-slots--docs#phone-layout), in a drawer.
+- The tabs overlap the scene beside the sidebar; the safe area in this example does not leave room for them.
+- `miniSidebar` does not shrink the sidebar: the built-in layout does that, and here the sidebar fills its container. A layout that honours it reads `LayoutSlots.useSidebarContent().hasMiniSidebar` and gives the container no fixed height, anchored at the bottom for example, so the sidebar takes its content's height.
+
+## Test cases
+
+- The sidebar sits on the left with its tabs on its right; the table is framed in the space right of the sidebar.
+- **Design** shows the edge finishes; choosing one changes the table. **Details** shows the text.
+- The footer shows the price and the finalize button.
+- Fullscreen removes the sidebar and frames the table in the whole canvas; leaving it brings the sidebar back.
+- With the **Read User** mock template the tabs are gone and the footer shows the price only.
+
+## Complete Implementation
+
+{/* AUTO-GENERATED SECTION: This section is automatically updated by 'phoenix story build' */}
+
+<details>
+<summary>Click to view the complete implementation files</summary>
+
+### ./spec/domain.yaml
+
+```yaml
+model:
+  latest:
+    entityTypes:
+      - Table
+    aliases:
+      RootEntity:
+        - Table
+    commonTypes:
+      EdgeFinish:
+        enum:
+          - None
+          - Facet
+          - Round
+          - TreeTrunk
+    shapes:
+      Table:
+        edgeFinish:
+          $ref: '#/model/latest/commonTypes/EdgeFinish'
+
+presets:
+  - rootEntityType: 'Table'
+    initialDomainEntities:
+      - id: 'Table-1'
+        type: 'Table'
+        edgeFinish: 'None'
+
+navigationStates:
+  - design
+  - details
+
+invariants:
+  Table:
+    trunkDisabled:
+      types:
+        - 'trunkDisabled'
+
+components:
+  Table:
+    propertyPage:
+      design:
+        $filter:
+          navigationStates:
+            - design
+        children:
+          - kind: propertyContainerGroup
+            props:
+              spacing: large
+            children:
+              - kind: propertyContainerItem
+                props:
+                  title: Edge Finish
+                  description: Select the edge finish for the table.
+                children:
+                  - kind: attributeCardSelector
+                    props:
+                      instanceName: edgeFinish
+      details:
+        $filter:
+          navigationStates:
+            - details
+        children:
+          - kind: propertyContainerItem
+            props:
+              title: Dimensions
+              description: 1600 × 800 mm, 750 mm high. Solid oak top on powder-coated steel legs.
+    sidebarTabs:
+      main:
+        $filter:
+          modes:
+            - owner
+        tabs:
+          - label: Design
+            navigationStates:
+              - design
+          - label: Details
+            navigationStates:
+              - details
+    price:
+      main:
+        price: 1200
+    fitRootPerspectiveCamera:
+      main:
+        priority: 1
+        fov: 35
+        near: 100
+        far: 10000
+        minDistance: 1000
+        maxDistance: 9000
+        distance: 5000
+        azimuthAngle: 1.5
+        polarAngle: 1.1
+        fitMeshChanges: true
+        animateOnLoad: true
+    sceneEntityRemoteObject:
+      top:
+        fileUrl: '/models/tables.gltf'
+        objectName: RECHTHOEK_RECTANGLE
+        dimensionUnit: m
+      leg:
+        fileUrl: '/models/tables.gltf'
+        objectName: AXL_LEG
+        dimensionUnit: m
+    sceneEntityObjectProperties:
+      top:
+        offsetY: 820
+        morphTargetInfluences:
+          Facet:
+            value:
+              $read: $edgeFinishFacet
+            scaleOne: 1
+            scaleZero: 0
+          Bol:
+            value:
+              $read: $edgeFinishRound
+            scaleOne: 1
+            scaleZero: 0
+          Boomstamrand:
+            value:
+              $read: $edgeFinishTreeTrunk
+            scaleOne: 1
+            scaleZero: 0
+      leg:
+        morphTargetInfluences:
+          Length:
+            value: 1000
+            scaleOne: 3000
+            scaleZero: 1400
+          Width:
+            value: 700
+            scaleOne: 1300
+            scaleZero: 600
+          Height:
+            value: 780
+            scaleOne: 780
+            scaleZero: 740
+    attributeSelection:
+      edgeFinish:
+        value:
+          $bind: edgeFinish
+        options:
+          $read: $edgeFinishOptions
+```
+
+### ./src/elements/ConfiguratorLayout.tsx
+
+```tsx
+import { LayoutSlots, useSceneSafeArea } from '@salsita-ai/sdk/configurator'
+
+import { phx } from '../../.phoenix/phx.js'
+
+const GUTTER = 24
+const SIDEBAR_WIDTH = 380
+
+const ConfiguratorLayout = () => {
+  const { containerRef, safeAreaRef } = useSceneSafeArea()
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+
+  return (
+    <div ref={containerRef} style={{ position: 'absolute', inset: 0 }}>
+      <LayoutSlots.Services />
+      <LayoutSlots.SharedCanvas />
+
+      {!isFullscreen && (
+        <aside
+          style={{
+            position: 'absolute',
+            insetBlock: GUTTER,
+            insetInlineStart: GUTTER,
+            inlineSize: SIDEBAR_WIDTH,
+          }}
+        >
+          <LayoutSlots.DesktopSidebar side="start" />
+        </aside>
+      )}
+
+      <div
+        ref={safeAreaRef}
+        style={{
+          position: 'absolute',
+          insetBlock: 0,
+          insetInlineStart: isFullscreen ? 0 : SIDEBAR_WIDTH + 2 * GUTTER,
+          insetInlineEnd: 0,
+          pointerEvents: 'none',
+        }}
+      >
+        <div style={{ position: 'absolute', insetBlockEnd: GUTTER, insetInlineStart: GUTTER, pointerEvents: 'auto' }}>
+          <LayoutSlots.DesktopToolbar />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+```
+
+### ./src/expressions/expressions.ts
+
+```ts
+import { phx } from '../../.phoenix/phx.js'
+
+export default phx.domain.implementCustomExpressions({
+  Table: {
+    $edgeFinishFacet: s => {
+      return s.edgeFinish === 'Facet' ? 1 : 0
+    },
+    $edgeFinishRound: s => {
+      return s.edgeFinish === 'Round' ? 1 : 0
+    },
+    $edgeFinishTreeTrunk: s => {
+      return s.edgeFinish === 'TreeTrunk' ? 1 : 0
+    },
+    $edgeFinishOptions: () => {
+      return [
+        {
+          label: 'None',
+          img: '/images/edge-none.png',
+          value: phx.domain.model.EdgeFinish.None,
+        },
+        {
+          label: 'Facet',
+          img: '/images/edge-facet.png',
+          value: phx.domain.model.EdgeFinish.Facet,
+        },
+        {
+          label: 'Round',
+          img: '/images/edge-round.png',
+          value: phx.domain.model.EdgeFinish.Round,
+        },
+        {
+          label: 'TreeTrunk',
+          img: '/images/edge-tree-trunk.png',
+          value: phx.domain.model.EdgeFinish.TreeTrunk,
+        },
+      ]
+    },
+  },
+})
+```
+
+### ./src/invariants/invariants.ts
+
+```ts
+import { phx } from '../../.phoenix/phx.js'
+
+export default phx.domain.implementCustomInvariants({
+  Table: {
+    trunkDisabled: s => {
+      if (s.edgeFinish === 'TreeTrunk') {
+        return [
+          {
+            type: 'trunkDisabled',
+            severity: 'fatal',
+            message: 'TreeTrunk finish is disabled because stuff!',
+          },
+        ]
+      }
+
+      return []
+    },
+  },
+})
+```
+
+</details>

package/dist/docs/layouts/sidebar-footer/basic.mdx

@@ -41,11 +41,11 @@ The basic sidebar footer adapts its layout based on what's available. The finali
 
 For more control over the sidebar footer, see these related examples:
 
-- **[Phoenix Handlers](../?path=/docs/layouts-phoenix-handlers)**: Learn how to create custom action handlers for sidebar footer buttons
-- **[Read Sidebar Footer](../?path=/docs/layouts-sidebar-footer-read)**: Display price in read-only mode without action buttons
-- **[Universal Sidebar Footer](../?path=/docs/layouts-sidebar-footer-universal)**: Add custom text and multiple action buttons while keeping the standard layout
-- **[Custom Sidebar Footer](../?path=/docs/layouts-sidebar-footer-custom)**: Replace the sidebar footer with your own React components for complete control
-- **[Hidden Sidebar Footer](../?path=/docs/layouts-sidebar-footer-hidden)**: Remove the sidebar footer entirely for embedded or immersive experiences
+- **[Phoenix Handlers](?path=/docs/layouts-phoenix-handlers--docs)**: Learn how to create custom action handlers for sidebar footer buttons
+- **[Read Sidebar Footer](?path=/docs/layouts-sidebar-footer-read--docs)**: Display price in read-only mode without action buttons
+- **[Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs)**: Add custom text and multiple action buttons while keeping the standard layout
+- **[Custom Sidebar Footer](?path=/docs/layouts-sidebar-footer-custom--docs)**: Replace the sidebar footer with your own React components for complete control
+- **[Hidden Sidebar Footer](?path=/docs/layouts-sidebar-footer-hidden--docs)**: Remove the sidebar footer entirely for embedded or immersive experiences
 
 ## Guide
 
@@ -98,84 +98,39 @@ This configuration gives you a fully functional sidebar footer with price displa
 
 ### Customizing finalize behavior
 
-The sidebar footer's finalize button can be customized using two different component types. These components let you either replace the button itself or define what happens when the user clicks finalize.
+New projects finalize with `finalizeAction` components and the [Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs), which runs the action's handler. The basic sidebar footer's own customization, the `finalizeButton` and `finalizePage` components, is legacy: the spec parser rejects both in YAML, so a project that keeps them declares them in TypeScript.
 
-#### Using finalizeButton component
+The basic sidebar footer checks for them in this order:
 
-The `finalizeButton` component replaces the default finalize button with your custom React component. This gives you complete control over the button's appearance and behavior.
+1. **finalizeButton**: if configured, its `button` React node is rendered instead of the finalize button, and implements the finalization and the disabled state itself
+2. **finalizePage**: if no custom button exists, a default button navigates to the first of the component's `finalizeNavigationStates`, and the built-in layout shows its `page` in a dialog while one of those states is active
+3. **No-op fallback**: if neither component is configured, a disabled button appears with the hint "Finalize feature is not configured"
 
-```yaml
-components:
-  Scene:
-    finalizeButton:
-      customFinalize:
-        button: <CustomFinalizeButtonComponent />
-```
-
-**TypeScript Interface**:
-
-```typescript
-/**
- * State for a custom finalize button component.
- */
-interface FinalizeButtonComponentState {
-  /**
-   * Custom React node to render as the finalize button.
-   * This completely replaces the default finalize button.
-   */
-  readonly button: ReactNode
-}
-```
+A legacy `finalizePage` is attached in TypeScript, as the [Universal](?path=/docs/layouts-universal--docs) example does in `src/components/components.tsx`:
 
-Your custom button component receives no special props. You must implement all the finalization logic yourself, including calling the appropriate handlers and managing the button's disabled state based on validation errors.
-
-#### Using finalizePage component
-
-The `finalizePage` component opens a modal page when the user clicks finalize. This is useful for multi-step checkout flows, order forms, or any scenario where you need to collect additional information before completing the order.
-
-```yaml
-components:
-  Scene:
-    finalizePage:
-      checkoutFlow:
-        finalizeNavigationStates: ['checkout', 'payment', 'confirmation']
-        page: <CheckoutFormComponent />
-```
+```tsx
+import { finalizePageComponent, memoEval } from '@salsita-ai/sdk/domain'
 
-**TypeScript Interface**:
+// CheckoutPage is the project's own React component
+import { CheckoutPage } from '../_shared/CheckoutPage.js'
 
-```typescript
-/**
- * State for a finalize page component that opens a modal.
- */
-interface FinalizePageComponentState {
-  /**
-   * The navigation states that are active when finalization is in progress.
-   * The first state in this array is used for initial navigation when the
-   * finalize button is clicked.
-   */
-  readonly finalizeNavigationStates: string[]
+// `phx` is a global in an application project; a Storybook example imports it from '../../.phoenix/phx.js'
 
-  /**
-   * React node to render as the page content in the finalize modal.
-   */
-  readonly page: ReactNode
-}
+export default phx.domain.attachComponent
+  .withComponent(finalizePageComponent, 'default')
+  .withEntity('Scene')
+  .attach(
+    memoEval(
+      () => [],
+      () => ({
+        finalizeNavigationStates: [phx.applicationTypes.NavigationState.finalize],
+        page: <CheckoutPage />,
+      })
+    )
+  )
 ```
 
-When the user clicks the finalize button, the system navigates to the first state in `finalizeNavigationStates`. Your page component can then navigate between these states to create a multi-step flow. All states must be defined in your navigation configuration.
-
-#### Priority and fallback behavior
-
-The sidebar footer checks for finalize components in this order:
-
-1. **finalizeButton**: If configured, this component is rendered as-is with no modifications
-2. **finalizePage**: If no custom button exists, a default button is shown that opens the specified page
-3. **No-op fallback**: If neither component is configured, a disabled button appears with the hint "Finalize feature is not configured"
-
-This priority system lets you customize either the button appearance or the finalization flow, but not both simultaneously. If you need both, use `finalizeButton` and implement the page navigation logic within your custom component.
-
-See the [Finalize Page Layout](../?path=/docs/layouts-simple-layout-finalize-page) example for a complete implementation of the finalize page pattern.
+The states in `finalizeNavigationStates` must be listed in the spec's `navigationStates`. The universal sidebar footer never opens a `finalizePage`.
 
 ### Navigation steps influence
 
@@ -278,7 +233,7 @@ Use `simpleSummary` for basic summaries that just need to display a list of conf
 
 Both component types require a `summaryNavigationState` that must exist in your navigation configuration. The sidebar footer checks the current navigation state against this property to determine whether the summary is currently active.
 
-See the [Summary Layout](../?path=/docs/layouts-simple-layout-summary) example for a complete summary implementation.
+See the [Sidebar Summary](?path=/docs/layouts-sidebar-summary--docs) example for a complete summary implementation.
 
 ### Custom price sidebar footer
 
@@ -317,11 +272,11 @@ When `customPriceSidebarFooter` is configured:
 - The sidebar footer layout remains unchanged - only the price display is replaced
 - Action buttons (finalize, next/previous, etc.) are not affected
 
-This component affects **only** the price display, not the overall sidebar footer structure. If you need to change the entire sidebar footer layout, use the [Universal Sidebar Footer](../?path=/docs/layouts-sidebar-footer-universal) or [Custom Sidebar Footer](../?path=/docs/layouts-sidebar-footer-custom) instead.
+This component affects **only** the price display, not the overall sidebar footer structure. If you need to change the entire sidebar footer layout, use the [Universal Sidebar Footer](?path=/docs/layouts-sidebar-footer-universal--docs) or [Custom Sidebar Footer](?path=/docs/layouts-sidebar-footer-custom--docs) instead.
 
 The custom price node receives no special props. You must access price data yourself through the configurator hooks like `useRootEntityPrice()` or by reading entity attributes directly.
 
-See the [Custom Price Sidebar Footer](../?path=/docs/layouts-custom-price) example for implementation details and best practices.
+See the [Custom Price Sidebar Footer](?path=/docs/layouts-custom-price--docs) example for implementation details and best practices.
 
 ## Example
 

package/dist/docs/other-features/client-side-rendering/declarative.mdx

@@ -229,7 +229,7 @@ export type ClientSideImageComponentState = {
   /** Output format: PNG (with transparency) or JPEG */
   readonly fileFormat: 'PNG' | 'JPEG'
   /** Optional background color (hex string) */
-  readonly backgroundColor?: string
+  readonly backgroundColor?: HexColor
 
   /** Tool state the image is rendered in (pins component filters keyed on tool state) */
   readonly toolState: string

package/dist/docs/other-features/side-effects.mdx

@@ -32,17 +32,14 @@ finishNotAvailable:
 ```
 
 ```ts
-const violationExpressions = invariantBuilder
-  .withInvariants(
-    implementCustomInvariants({
-      Plate: {
-        finishNotAvailable: s => {
-          return availableMaterials.some(state => state.material === s.material && state.finish === s.finish)
-        },
-      },
-    })
-  )
-  .buildViolationExpressions()
+// src/invariants/invariants.ts
+export default phx.domain.implementCustomInvariants({
+  Plate: {
+    finishNotAvailable: s => {
+      return availableMaterials.some(state => state.material === s.material && state.finish === s.finish)
+    },
+  },
+})
 ```
 
 With following control structure. The top input selects the material, the bottom one selects the finish.

package/dist/docs/other-features/transformers.mdx

@@ -433,6 +433,10 @@ The following sample application has all the above described transformers active
 - When the view changes to `Y`, the navigation state is changed to `C`.
 - When any entity is deselected in view `Z`, the view is changed to `X`.
 
+The example's own tests under `__tests__/` check these cases with `createMockDomainContext` on the config
+`createTestApplicationConfig` builds from the generated application; [Testing](?path=/docs/phoenix-testing--docs)
+shows how a project's test sets that up.
+
 ## Complete Implementation
 
 {/* AUTO-GENERATED SECTION: This section is automatically updated by 'phoenix story build' */}