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

package/dist/docs/performance/fast-highlight.mdx

@@ -177,7 +177,6 @@ import { SelectionHotspot } from '@salsita-ai/sdk/configurator'
 import { htmlHotspotComponent, memoEval } from '@salsita-ai/sdk/domain'
 
 import { getConsoleRenderingComponents } from '../../../../common/console-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default [
   ...getConsoleRenderingComponents('ConsoleUnit', phx.domain.attachComponent),
@@ -211,8 +210,6 @@ export default [
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   ConsoleUnit: {
     $x: s => s.x,
@@ -224,7 +221,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { isConsoleOverlapping } from '../_shared/overlap.js'
 
 export default phx.domain.implementCustomInvariants({
@@ -254,7 +250,6 @@ export default phx.domain.implementCustomInvariants({
 import { type DomainEntityId } from '@salsita-ai/sdk/domain'
 
 import type * as EnhancedModel from '../../.phoenix/application-types.js'
-import { phx } from '../../.phoenix/phx.js'
 import { CONSOLE_DEPTH, CONSOLE_WIDTH, type Coords, isConsoleOverlapping } from '../_shared/overlap.js'
 
 const distance = (a: Coords, b: Coords) => Math.sqrt((a.x - b.x) ** 2 + (a.z - b.z) ** 2)
@@ -330,8 +325,6 @@ export default phx.frontend.transformerBuilder.when
 ### ./src/transformers/initial.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.transformerBuilder.always.then
   .applySideEffect(ctx => {
     const $root = ctx.getNew$Root()

package/dist/docs/performance/general.mdx

@@ -208,7 +208,6 @@ import { SelectionHotspot } from '@salsita-ai/sdk/configurator'
 import { htmlHotspotComponent, memoEval } from '@salsita-ai/sdk/domain'
 
 import { getConsoleRenderingComponents } from '../../../../common/console-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default [
   ...getConsoleRenderingComponents('ConsoleUnit', phx.domain.attachComponent),
@@ -242,8 +241,6 @@ export default [
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   ConsoleUnit: {
     $x: s => s.x,
@@ -255,7 +252,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { isConsoleOverlapping } from '../_shared/overlap.js'
 
 export default phx.domain.implementCustomInvariants({
@@ -285,7 +281,6 @@ export default phx.domain.implementCustomInvariants({
 import { type DomainEntityId } from '@salsita-ai/sdk/domain'
 
 import type * as EnhancedModel from '../../.phoenix/application-types.js'
-import { phx } from '../../.phoenix/phx.js'
 import { CONSOLE_DEPTH, CONSOLE_WIDTH, type Coords, isConsoleOverlapping } from '../_shared/overlap.js'
 
 const distance = (a: Coords, b: Coords) => Math.sqrt((a.x - b.x) ** 2 + (a.z - b.z) ** 2)
@@ -361,8 +356,6 @@ export default phx.frontend.transformerBuilder.when
 ### ./src/transformers/initial.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.transformerBuilder.always.then
   .applySideEffect(ctx => {
     const $root = ctx.getNew$Root()

package/dist/docs/performance/render-isolation.mdx

@@ -409,7 +409,6 @@ export const RenderFlash = ({ overlayRef, size: [width, height, depth], position
 import type { IdSequence } from '@salsita-ai/sdk/domain'
 
 import type * as Model from '../../.phoenix/application-types.js'
-import { phx } from '../../.phoenix/phx.js'
 
 // All distances are in millimetres, the default data unit of the application.
 export const ROOM_WIDTH = 2000
@@ -509,7 +508,6 @@ export const createBatchUpdates = ({ $scene, sequence, roomCount }: BatchContext
 ```tsx
 import { Text } from '@react-three/drei'
 
-import { phx } from '../../.phoenix/phx.js'
 import { RenderFlash, useRenderFlash } from '../_shared/RenderFlash.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('BoxMesh', ({ entityId }) => {
@@ -564,7 +562,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('BoxMesh', ({ entit
 ```tsx
 import { Box, Button, Stack, Typography } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { ROOMS_PER_CLICK, createBatchUpdates } from '../_shared/layout.js'
 
 export default phx.frontend.createCustomPhoenixLayoutElement('PerformancePanel', () => {
@@ -609,7 +606,6 @@ import { Billboard, Text } from '@react-three/drei'
 import { useEffect, useMemo } from 'react'
 import { BoxGeometry, EdgesGeometry } from 'three'
 
-import { phx } from '../../.phoenix/phx.js'
 import { RenderFlash, useRenderFlash } from '../_shared/RenderFlash.js'
 import { ROOM_HEIGHT } from '../_shared/layout.js'
 
@@ -681,7 +677,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('RoomFrame', ({ ent
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { isInsideRoom, roomColor } from '../_shared/layout.js'
 
 interface RoomFloor {
@@ -765,7 +760,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/transformers/initial.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { INITIAL_ROOM_COUNT, createBatchUpdates } from '../_shared/layout.js'
 
 export default phx.frontend.transformerBuilder.always.then

package/dist/docs/phoenix/admin.mdx

@@ -240,123 +240,85 @@ Phoenix provides a built-in navigation system for admin interfaces that automati
 
 ### Navigation Components
 
-**Built-in Admin Pages**: The `createAdminPages` function generates common admin functionality:
+**Built-in Admin Pages**: Declare the admin pages in the `$adminPages` section of an admin spec file. Phoenix generates each page, its sidebar, the navigation states it uses and the admin navigation menu:
 
-```typescript
-// src/admin/components/admin-components.tsx
-import {
-  createAdminPages,
-  adminSidebarComponent,
-  memoEval,
-  navigationPageComponent,
-  navigationPanelListComponent,
-  attachAdminComponent,
-} from '.phoenix/domain.js'
-import { ApplicationTypes } from '.phoenix/domain.js'
-
-// Create common admin pages (presets, recipes)
-const { commonComponents: commonAdminComponents, commonPages } = createAdminPages({
-  presets: {
-    categoryNavigationState: ApplicationTypes.AdminNavigationState.PresetCategories,
-    presetNavigationState: ApplicationTypes.AdminNavigationState.Presets,
-  },
-  recipes: {
-    collections: [
-      {
-        name: 'Hoods',
-        navigationState: ApplicationTypes.AdminNavigationState.HoodRecipes,
-      },
-      {
-        name: 'Modules',
-        navigationState: ApplicationTypes.AdminNavigationState.ModuleRecipes,
-      },
-    ],
-  },
-})
+```yaml
+# spec/admin/pages.yaml
+$admin: true
 
-export const customAdminOptics = [
-  ...commonAdminComponents, // Include built-in admin components
+$adminPages:
+  presets: true
+  recipes:
+    - name: Hoods
+    - name: Modules
+  pages:
+    - key: customMaterials
+      title: Materials
+      icon: PaletteBold
+      entity: CustomMaterial
+      component: MaterialsPage
+      actionsComponent: MaterialActions
+      sidebar:
+        title: Edit Material
+        component: MaterialSidebar
+```
 
-  // Create navigation page for custom content
-  attachAdminComponent
-    .withEntity('Admin')
-    .withComponent(navigationPageComponent, 'customMaterials')
-    .withGradualFilter({
-      navigationStates: [ApplicationTypes.AdminNavigationState.Other],
-    })
-    .attach(
-      memoEval(
-        () => [],
-        () => ({
-          title: 'Materials',
-          breadcrumbs: [
-            {
-              label: 'Materials',
-              navigationState: ApplicationTypes.AdminNavigationState.Other,
-            },
-          ],
-          content: <MaterialsPage />,
-          actions: <MaterialActions />,
-        })
-      )
-    ),
+- `presets: true` adds the preset category and preset pages on the `PresetCategories` and `Presets` navigation states; an object with `categoryNavigationState` and `presetNavigationState` names the states instead.
+- Each `recipes` entry adds a page for that recipe collection on the `<name>Recipes` navigation state, or on its `navigationState`; the menu groups them under **Recipes**.
+- Each `pages` entry adds a custom page on the navigation state named by its `key`, or by its `navigationState`. `component` and `actionsComponent` name the layout elements rendered as the page content and its actions; `sidebar.component` names the entity element shown in the sidebar when an entity of type `entity` is selected on the page.
+
+Phoenix adds the generated navigation states to the admin spec, so they are not listed under `navigationStates` as well; listing one there is an error. Only one admin spec file can declare `$adminPages`.
+
+The page content and actions are layout elements, and the sidebar is an entity element, each the default export of a file in `src/admin/elements/`:
+
+```tsx
+// src/admin/elements/MaterialsPage.tsx
+export default phx.frontend.createCustomPhoenixLayoutElement('MaterialsPage', () => {
+  const materials = phx.frontend.admin.useStoreSelector(
+    emission => emission.state.entities.filter(phx.domain.admin.model.CustomMaterial.is),
+    []
+  )
+  const select = phx.frontend.admin.useSelectEntity()
+
+  return (
+    <ul>
+      {materials.map(material => (
+        <li key={material.id}>
+          <button onClick={() => select(material.id)}>{material.name}</button>
+        </li>
+      ))}
+    </ul>
+  )
+})
+```
 
-  // Create sidebar for editing entities
-  attachAdminComponent
-    .withEntity('CustomMaterial')
-    .withComponent(adminSidebarComponent, 'customMaterialsSidebar')
-    .withGradualFilter({
-      navigationStates: [ApplicationTypes.AdminNavigationState.Other],
-      selectedEntityIds: s => [s.id],
-    })
-    .attach(
-      memoEval(
-        s => [s.id],
-        id => ({
-          title: 'Edit Material',
-          page: <MaterialSidebar id={id} />,
-        })
-      )
-    ),
+```tsx
+// src/admin/elements/MaterialSidebar.tsx
+import { TextValueInput } from '@salsita-ai/sdk/react'
 
-  // Create navigation panel with menu items
-  attachAdminComponent
-    .withEntity('Admin')
-    .withComponent(navigationPanelListComponent, 'main')
-    .attach(
-      memoEval(
-        () => [],
-        () => ({
-          items: [
-            ...commonPages, // Include built-in pages
-            {
-              label: 'Materials',
-              icon: 'PaletteBold',
-              navigationStates: [ApplicationTypes.AdminNavigationState.Other],
-            },
-          ],
-        })
-      )
-    ),
-]
+export default phx.frontend.createCustomPhoenixEntityElement('MaterialSidebar', ({ entityId }) => (
+  <TextValueInput entityId={entityId} instanceName="name" label="Name" />
+))
 ```
 
+`MaterialActions` is a layout element like `MaterialsPage`. The Catalog Builder demo (`packages/demos/demo-catalog-builder/src/admin/elements/`) has complete pages, actions and sidebars.
+
 ### Navigation Component Types
 
 - **`navigationPageComponent`**: Creates full pages with title, breadcrumbs, content, and actions
 - **`adminSidebarComponent`**: Creates sidebars for editing selected entities
 - **`navigationPanelListComponent`**: Creates the main navigation menu with items and icons
-- **`createAdminPages`**: Generates common admin functionality for presets and recipes
+- **`$adminPages`**: Generates these components for presets, recipes and custom pages; attach them yourself with `phx.domain.admin.attachComponent` only for a page the section does not describe
 
 ### Optional Admin Modules
 
-The `createAdminPages` function provides optional built-in modules:
+The `$adminPages` section provides optional built-in modules:
 
 **Presets Module**: Allows admins to create and manage preset configurations that users can select as starting points in the configurator. Presets can be organized into categories and include thumbnails, descriptions, and predefined entity configurations. Each preset also accepts free-form `tags` that the host can filter on at runtime via the `presetTags` WC attribute — see [Preset Tags](?path=/docs/phoenix-integration-preset-tags-external--docs).
 
 **Recipes Module**: Enables admins to define recipes that control how entities are created and configured. Recipes can be organized into collections (like "Hoods" and "Modules") and define the logic for automatically generating complex entity structures.
 
-Both modules are entirely optional - you can use one, both, or neither depending on your admin needs. If you don't need preset management or recipe functionality, simply omit them from the `createAdminPages` configuration or don't call the function at all.
+Both modules are entirely optional - you can use one, both, or neither depending on your admin needs. If you don't need preset management or recipe functionality, simply omit `presets` or `recipes` from `$adminPages`.
 
 ## Publishing Workflow
 
@@ -432,13 +394,26 @@ Admin functionality is part of the same application as the configurator and need
 ### Registering Admin Components
 
 The frontend entry is generated into `.phoenix/`, so a project never calls the configurator builder itself. Every file
-in `src/admin/components/` is picked up by its location and its default export is registered as admin components:
+in `src/admin/components/` is picked up by its location and its default export is registered as admin components. This
+one adds a Settings item beside the navigation menu that `$adminPages` generates:
 
 ```typescript
 // src/admin/components/admin-components.tsx
-// ... customAdminOptics as defined in the example above
+import { memoEval, navigationPanelListComponent } from '@salsita-ai/sdk/domain'
 
-export default customAdminOptics
+export default [
+  phx.domain.admin.attachComponent
+    .withEntity('Admin')
+    .withComponent(navigationPanelListComponent, 'settings')
+    .attach(
+      memoEval(
+        () => [],
+        () => ({
+          items: [{ label: 'Settings', navigationStates: ['Settings'] }],
+        })
+      )
+    ),
+]
 ```
 
 The page shown to a user who is not authenticated is an element. Create it with

package/dist/docs/phoenix/application-states.mdx

@@ -77,7 +77,7 @@ navigationStates:
 
 Navigation states in Phoenix are controlled by navigation system that manages state transitions and coordinates with the component system. The navigation system handles state changes and maintains consistency across navigation transitions.
 
-Phoenix provides built-in components to visualize and control navigation, eg.
+Phoenix provides built-in components to visualize and control navigation, eg. `navigationSteps` for a step indicator and `horizontalTabs` (or `sidebarTabs` for tabs in the sidebar):
 
 ```yaml
 components:
@@ -86,31 +86,27 @@ components:
       main:
         steps:
           - label: 'Design'
-            description: 'Configure your space'
             navigationStates:
               - design
           - label: 'Preview'
-            description: 'Review your design'
             navigationStates:
               - preview
           - label: 'Summary'
-            description: 'Order details'
             navigationStates:
               - summary
           - label: 'Checkout'
-            description: 'Complete your order'
             navigationStates:
               - finalize
 
-    navigationTabs:
+    horizontalTabs:
       main:
         tabs:
           - label: 'Design'
-            icon: 'edit'
+            icon: 'PencilSimpleBold'
             navigationStates:
               - design
           - label: 'Preview'
-            icon: 'eye'
+            icon: 'EyeBold'
             navigationStates:
               - preview
 ```
@@ -122,39 +118,56 @@ components:
   Room:
     propertyPage:
       design:
-        title: 'Room Configuration'
+        children:
+          - kind: propertyContainerItem
+            props:
+              title: 'Room Configuration'
         $filter:
           navigationStates: ['design'] # Only active during design phase
 
       summary:
-        title: 'Room Summary'
+        children:
+          - kind: propertyContainerItem
+            props:
+              title: 'Room Summary'
         $filter:
           navigationStates: ['summary', 'finalize'] # Show during review phases
 
     toolControls:
       designTools:
-        tools: ['select', 'move', 'rotate', 'resize']
+        items:
+          - label: 'Select'
+            value: 'select'
+            icon: 'CursorClick'
+          - label: 'Move'
+            value: 'move'
+            icon: 'ArrowsOutCardinal'
         $filter:
           navigationStates: ['design'] # Design tools only available in design mode
 
       previewControls:
-        tools: ['zoom', 'pan', 'measure']
+        items:
+          - label: 'Measure'
+            value: 'measure'
+            icon: 'ArrowsHorizontal'
         $filter:
           navigationStates: ['preview'] # Different tools for preview mode
 
   Cabinet:
     detail:
-      editable:
+      design:
         title: 'Cabinet Settings'
-        editable: true
+        subtitle: 'Adjust the size and finish'
+        description: 'Change the cabinet width, height and material.'
         $filter:
-          navigationStates: ['design'] # Editable only in design mode
+          navigationStates: ['design'] # Shown in design mode
 
-      readonly:
+      review:
         title: 'Cabinet Details'
-        editable: false
+        subtitle: 'Your chosen cabinet'
+        description: 'The size and finish you configured.'
         $filter:
-          navigationStates: ['preview', 'summary', 'finalize'] # Read-only in other states
+          navigationStates: ['preview', 'summary', 'finalize'] # Shown in the other states
 ```
 
 **Advanced Filtering**: Filters support combining multiple conditions. Multiple conditions in the same filter are AND-ed together. Use `$or` for OR logic:
@@ -162,16 +175,15 @@ components:
 ```yaml
 components:
   Scene:
-    # AND condition: show only when BOTH conditions are true
     sceneEntitySelectHotspot:
+      # AND condition: show only when BOTH conditions are true
       designAndTopView:
         title: 'Design in Top View'
         $filter:
           navigationStates: ['design']
           viewStates: ['top']
 
-    # OR condition: show when EITHER condition is true
-    sceneEntitySelectHotspot:
+      # OR condition: show when EITHER condition is true
       step2OrFrontView:
         title: 'Step 2 OR Front View'
         $filter:
@@ -216,7 +228,7 @@ components:
             icon: 'Cube'
           - label: 'Close Up'
             value: 'closeup'
-            icon: 'MagnifyingGlass'
+            icon: 'MagnifyingGlassBold'
           - label: 'Blueprint'
             value: 'blueprint'
             icon: 'GridFour'
@@ -248,11 +260,14 @@ components:
     detail:
       overview:
         title: 'Cabinet'
+        subtitle: ''
+        description: ''
         $filter:
           viewStates: ['overview', 'blueprint']
 
       detailed:
         title: 'Cabinet Details'
+        subtitle: 'Close-up view'
         description: 'Full cabinet configuration options'
         $filter:
           viewStates: ['closeup']
@@ -285,27 +300,30 @@ components:
             icon: 'CursorClick'
           - label: 'Draw'
             value: 'sketch'
-            icon: 'PencilSimple'
+            icon: 'PencilSimpleBold'
           - label: 'Move'
             value: 'move'
             icon: 'ArrowsOutCardinal'
           - label: 'Measure'
             value: 'measure'
-            icon: 'Ruler'
+            icon: 'ArrowsHorizontal'
 
-    sketching:
+    # `key` matches the `key` of the `sketching` component that holds the drawing surface and recipes
+    sketchingDraw:
       drawing:
-        enabled: true
+        key: sketching
         $filter:
           toolStates: ['sketch']
 
     sketchingEdit:
       editing:
-        enabled: true
+        key: sketching
         $filter:
           toolStates: ['select']
 ```
 
+The [Sketching](?path=/docs/complex-use-cases-sketching--docs) example shows the complete setup, including the `sketching` component these refer to.
+
 ## What We Learned
 
 In this guide, we explored Phoenix's application state management: