@salsita-ai/sdk 0.50.0-develop.03ef51a292 → 0.50.0-develop.08837efd9c

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 finalize button is disabled unless the spec configures `finalizeButton` or `finalizePage`, as in the built-in layout. A `finalizePage` is not shown by a project layout unless the layout renders it.
+- `LayoutSlots.DesktopSidebar` is the desktop sidebar. At phone width a project layout needs its own arrangement, for example the `Mobile*` members of `LayoutSlots` 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/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' */}

package/dist/docs/other-features/violation-messages.mdx

@@ -153,10 +153,10 @@ The `formatControlViolationMessage` function is where the magic happens. It rece
 3. **Actionable guidance**: Tell users exactly what values are valid or how to fix the problem
 4. **Consistent terminology**: Use the same terms and units throughout your application
 
-Implement violations with custom message formatting in your domain TypeScript file:
+Implement violations with custom message formatting in a file of `src/invariants/`:
 
 ```typescript
-// domain/index.ts
+// src/invariants/invariants.ts
 
 // Pre-define translatable labels for nested localization
 const colorLabels = {
@@ -166,60 +166,56 @@ const colorLabels = {
   yellow: msg`yellow`,
 } as const
 
-const violationExpressions = invariantBuilder
-  .withInvariants(
-    implementCustomInvariants({
-      Scene: {
-        itIsNotZero: s => {
-          if (s.x !== 0) {
-            return [
-              {
-                type: 'itIsNotZero',
-                severity: 'fatal',
-                message: 'Scene is not zero',
-                controlViolationPriority: 1,
-                formatControlViolationMessage: () => {
-                  return msg({
-                    message: `Scene is not zero: The position would be ${s.x} which is not equal to 0`,
-                  })
-                },
-              },
-            ]
-          }
-          return []
-        },
-        // ... tooMuchRight omitted for brevity ...
-
-        // Static violation: severity, message and controlViolationPriority
-        // are declared in YAML. Implementation only returns a boolean.
-        wayTooFarRight: s => s.x < 200,
-
-        colorPositionIncompatible: s => {
-          const compatibleColors = ['red', 'blue', 'green'] as const
-          if (s.x >= 200 && !compatibleColors.includes(s.color)) {
-            return [
-              {
-                type: 'colorPositionIncompatible',
-                severity: 'fatal',
-                message: 'Color is not compatible with far right position',
-                controlViolationPriority: 3,
-                formatControlViolationMessage: (_emission, { i18n }) => {
-                  const labels = new Intl.ListFormat(i18n.locale, {
-                    style: 'long',
-                    type: 'disjunction',
-                  }).format(compatibleColors.map(c => i18n.t(colorLabels[c])))
-
-                  return msg({ message: `Far right position is only available for ${labels}` })
-                },
-              },
-            ]
-          }
-          return []
-        },
-      },
-    })
-  )
-  .buildViolationExpressions()
+export default phx.domain.implementCustomInvariants({
+  Buckyball: {
+    itIsNotZero: s => {
+      if (s.x !== 0) {
+        return [
+          {
+            type: 'itIsNotZero',
+            severity: 'fatal',
+            message: 'Scene is not zero',
+            controlViolationPriority: 1,
+            formatControlViolationMessage: () => {
+              return msg({
+                message: `Scene is not zero: The position would be ${s.x} which is not equal to 0`,
+              })
+            },
+          },
+        ]
+      }
+      return []
+    },
+    // ... tooMuchRight omitted for brevity ...
+
+    // Static violation: severity, message and controlViolationPriority
+    // are declared in YAML. Implementation only returns a boolean.
+    wayTooFarRight: s => s.x < 200,
+
+    colorPositionIncompatible: s => {
+      const compatibleColors = ['red', 'blue', 'green'] as const
+      if (s.x >= 200 && !compatibleColors.includes(s.color)) {
+        return [
+          {
+            type: 'colorPositionIncompatible',
+            severity: 'fatal',
+            message: 'Color is not compatible with far right position',
+            controlViolationPriority: 3,
+            formatControlViolationMessage: (_emission, { i18n }) => {
+              const labels = new Intl.ListFormat(i18n.locale, {
+                style: 'long',
+                type: 'disjunction',
+              }).format(compatibleColors.map(c => i18n.t(colorLabels[c])))
+
+              return msg({ message: `Far right position is only available for ${labels}` })
+            },
+          },
+        ]
+      }
+      return []
+    },
+  },
+})
 ```
 
 ### Internationalization with Dynamic Content