@salsita-ai/sdk 0.50.0-develop.b47f1774a2 → 0.50.0-develop.b5d443db78

package/dist/docs/phoenix/components.mdx

@@ -48,17 +48,18 @@ Here's how components are defined, showing both the YAML configuration and the u
 ```yaml
 components:
   Cabinet:
-    # Property page component with writable state
+    # Property page: the sidebar page shown when a cabinet is selected
     propertyPage:
       main:
-        title: 'Cabinet Configuration'
         children:
-          - kind: attributeSlider
+          - kind: propertyContainerItem
             props:
-              instanceName: width
-              label: Width
-              min: 100
-              max: 2000
+              title: 'Cabinet Configuration'
+            children:
+              - kind: distanceDimensionSlider
+                props:
+                  instanceName: width # The distanceDimension instance below, which sets min and max
+                  label: Width
 
     # Attribute selection with domain-bound writable state
     attributeSelection:
@@ -109,16 +110,15 @@ The component system provides full TypeScript support for both configuration and
 ```yaml
 components:
   Cabinet: # Component attached to Cabinet entity type
-    propertyPage:
+    detail: # The title, subtitle and description shown in the entity header above the property page
       main:
         title:
           $read: name # Read from Cabinet.name property
         subtitle:
-          $read: $area # Read from Cabinet.$area expression
-        visible:
-          $read: $isVisible # Read from Cabinet.$isVisible expression
+          $read: $areaLabel # Read from Cabinet.$areaLabel expression
+        description: 'Base cabinet'
 
-    attributeSlider:
+    distanceDimension:
       width:
         value:
           $bind: width # Bidirectional binding to Cabinet.width
@@ -132,6 +132,7 @@ components:
       main:
         title:
           $read: type # Read entity type (Chair/Table/Cabinet)
+        subtitle: 'Furniture'
         description:
           $read: $description # Read from common expression across all furniture
 ```
@@ -191,7 +192,7 @@ components:
 
 Phoenix provides three powerful binding mechanisms that connect components to your domain model data:
 
-> Note on `$codeRef`: it's evaluated without entity context and is meant for static math/constants (e.g., `4 * 25.4`, `Math.PI / 2 - 0.2`). If a value depends on entity state, expose it via an expression and reference it with `$read`. Don't attempt to read entity data inside `$codeRef`. This feature is experimental.
+> For inline math in a prop, such as `4 * 25.4` or `self.width / 2`, use `$eval` (described below). `$codeRef` with an inline `code:` block is not supported and reports `ENHANCED_JSON_VALUE_CODE_REF_NOT_SUPPORTED`.
 
 ### `$read` - Reading Values
 
@@ -219,18 +220,18 @@ components:
 
 ### `$write` - Writing Values
 
-`$write` allows components to modify entity properties directly. This creates a two-way binding where user interactions can update the domain state.
+`$write` allows components to modify entity properties directly. This creates a two-way binding where user interactions can update the domain state. `$write` is paired with `$read` or `$eval`, which supplies the value the component shows; `$bind: width` is the short form of `$read: width` with `$write: width`.
 
 ```yaml
 components:
   Cabinet:
-    attributeSlider:
+    distanceDimension:
       width:
         value:
+          $read: $clampedWidth # The control shows the value of an expression
           $write: width # User input directly updates the width property
         min: 100
         max: 2000
-        step: 50
 ```
 
 **Use cases for `$write`:**
@@ -338,7 +339,10 @@ components:
   Cabinet:
     propertyPage:
       main:
-        title: 'Cabinet Settings'
+        children:
+          - kind: distanceDimensionSlider
+            props:
+              instanceName: width
         $filter:
           # Static filter configuration
           navigationStates: ['design', 'configure']
@@ -348,13 +352,16 @@ components:
     detail:
       advanced:
         title: 'Advanced Options'
+        subtitle: 'Cabinet'
+        description: 'Fine-tune the cabinet'
         $filter:
           # Dynamic filter using expression
-          $read: $showAdvancedOptions
+          active:
+            $read: $showAdvancedOptions
 
-    contextualTools:
+    htmlHotspot:
       edit:
-        title: 'Edit Cabinet'
+        name: EditCabinetButton # A custom element shown next to the cabinet in the scene
         $filter:
           # Show only when this specific entity is selected
           selectedEntityIds:
@@ -490,14 +497,11 @@ components:
   Cabinet:
     propertyPage:
       main:
-        title: 'Cabinet Configuration'
         children:
-          - kind: attributeSlider
+          - kind: distanceDimensionSlider
             props:
               instanceName: width
               label: Width
-              min: 100
-              max: 2000
 ```
 
 **Generated TypeScript Code:**
@@ -514,15 +518,12 @@ export default [
       memoEval(
         cabinet => [cabinet.id], // Dependencies
         () => ({
-          title: 'Cabinet Configuration',
           children: [
             {
-              kind: 'attributeSlider',
+              kind: 'distanceDimensionSlider',
               props: {
                 instanceName: 'width',
                 label: 'Width',
-                min: 100,
-                max: 2000,
               },
             },
           ],
@@ -731,7 +732,6 @@ phx.domain.attachComponent
         primaryButton: canManufacture ?
           <ManufactureButton entityId={entityId} status={status} /> : null,
         secondaryButton: <QualityCheckButton entityId={entityId} />,
-        page: <ManufacturingDetails entityId={entityId} />,
       })
     )
   )
@@ -768,14 +768,17 @@ Custom components in `src/components/` are automatically collected by Phoenix an
 export default [customRenderingComponent, advancedUIComponent, specializedToolComponent]
 ```
 
-**When to Use Custom Components:**
+**When to Attach Components in Code:**
+
+A file in `src/components/` attaches a component from TypeScript instead of YAML. Use it when the component's state needs more than YAML can express:
 
-- **Custom 3D Rendering**: Complex Three.js scenes that can't be achieved with standard components
-- **Advanced UI Logic**: React components with complex state management or business logic
-- **Specialized Tools**: Custom interaction modes or editing tools
-- **External Integrations**: Components that integrate with external APIs or services
-- **Performance Optimizations**: Highly optimized rendering for specific use cases
-- **Domain-Specific Behavior**: Functionality unique to your particular domain
+- **Custom 3D Rendering**: a `customSceneEntity` node built from React and Three.js
+- **Computed State**: component values that need TypeScript logic beyond `$read`, `$eval` and expressions
+- **Many Instances**: one instance per item of a collection, with `attachMany` (see [Advanced: Dynamic Components](#advanced-dynamic-components))
+- **Programmatic Filters**: `withGradualFilter` predicates written as functions
+- **Performance Optimizations**: hand-tuned `memoEval` dependencies for expensive state
+
+A custom control or panel in the sidebar does not need a component attachment. Build it as a React element with `phx.frontend.createCustomPhoenixEntityElement('Name', ...)`, default-exported from a file in `src/elements/`, and place it in the YAML property page as a `customElement` with `props.name` set to that name; see [Custom Controls](?path=/docs/controls-custom--docs).
 
 Custom component attachments provide the flexibility to extend Phoenix's capabilities while maintaining the performance benefits of the component system and seamless integration with your domain model.
 
@@ -793,7 +796,7 @@ Dynamic components are attached programmatically using the `phx.domain.attachCom
 
 **Key Use Cases:**
 
-- Creating component instances for each item in a collection (e.g., one control per cabinet door)
+- Creating component instances for each item in a collection (e.g., one door model per cabinet door)
 - Conditionally showing components based on complex business logic
 - Generating UI elements that depend on dynamic entity relationships
 - Building adaptive interfaces that change based on configuration complexity
@@ -801,24 +804,28 @@ Dynamic components are attached programmatically using the `phx.domain.attachCom
 **Example Pattern:**
 
 ```typescript
-// Dynamic component that creates controls for each door
+// Dynamic component that loads one door model for each door of the cabinet
+import { memoEval, sceneEntityRemoteObjectComponent } from '@salsita-ai/sdk/domain'
+
 phx.domain.attachComponent
   .withEntity('Cabinet')
-  .withComponent(customControlComponent, 'doors')
+  .withComponent(sceneEntityRemoteObjectComponent, 'door')
   .attachMany(
     memoEval(
-      cabinet => [cabinet.$doors],
-      doors =>
-        doors.map(door => ({
-          key: door.id,
-          label: `Door ${door.id}`,
-          doorId: door.id,
-          isOpen: door.isOpen,
+      cabinet => [cabinet.doorCount],
+      doorCount =>
+        Array.from({ length: doorCount }, (_, index) => ({
+          key: String(index), // Unique per instance
+          fileUrl: '/models/cabinet.gltf',
+          objectName: 'Door',
+          dimensionUnit: 'm',
         }))
     )
   )
 ```
 
+The `attachMany` callback returns an array of component states, each with a unique `key`. To position each door, also attach `sceneEntityObjectPropertiesComponent` with the same instance name and keys, as the example linked below does. A custom control is not a component: for custom UI in the sidebar, use a `customElement` as described in [Custom Component Attachments](#custom-component-attachments).
+
 For comprehensive examples and implementation details, see the [Dynamic Component Attachments](?path=/docs/other-features-dynamic-component-attachments--docs) documentation.
 
 ## What We Learned