@salsita-ai/sdk 0.50.0-develop.a4dde5f252 → 0.50.0-develop.a8cf9ffd01

package/dist/docs/index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-10-13T19:13:10.084Z",
+  "generatedAt": "2026-10-24T05:47:45.258Z",
   "categories": [
     {
       "name": "Phoenix",
@@ -164,6 +164,16 @@
           ],
           "source": "storybook-root"
         },
+        {
+          "title": "Layout Slots",
+          "description": "A project layout registered as `ConfiguratorLayout` builds its UI from its own components and from the pieces of the built-in layout it wants to keep. Those pieces are the members of `LayoutSlots`,...",
+          "path": "docs/phoenix/layout-slots.mdx",
+          "category": [
+            "Phoenix",
+            "Layout Slots"
+          ],
+          "source": "storybook-root"
+        },
         {
           "title": "Localization",
           "description": "Phoenix provides a localization system built on **Lingui** that enables multi-language support across your configurator. The system handles React components and server-side webhook processing,...",
@@ -226,7 +236,7 @@
         },
         {
           "title": "SDK Builder Workflow",
-          "description": "An SDK-builder workspace lets you build one configurator from the application spec and develop and deploy it from your terminal. You don't need a repository, a CI pipeline, project keys or a...",
+          "description": "An SDK-builder workspace lets you build configurators from application specs and develop and deploy them from your terminal. You don't need a repository, a CI pipeline, project keys or a development...",
           "path": "docs/phoenix/sdk-builder-workflow.mdx",
           "category": [
             "Phoenix",
@@ -264,6 +274,16 @@
           ],
           "source": "storybook-root"
         },
+        {
+          "title": "Testing",
+          "description": "A project's tests check its own logic, such as an expression on a preset, a transformer that completes an edit, a Blender projection or a migration, against the application the project ships. They...",
+          "path": "docs/phoenix/testing.mdx",
+          "category": [
+            "Phoenix",
+            "Testing"
+          ],
+          "source": "storybook-root"
+        },
         {
           "title": "Webhook Membership",
           "description": "Build component controls with React and browser SDKs without pulling them into the server webhook bundle. Phoenix keeps user-authored components and handlers in the frontend unless a file explicitly...",
@@ -276,7 +296,7 @@
         },
         {
           "title": "Webhooks",
-          "description": "To support project specific finalization workflows, authentication and custom integrations, platform provides a way to define webhooks. These webhooks are deployed on aws lambda and can be triggered...",
+          "description": "To support project specific finalization workflows, authentication and custom integrations, the platform runs a project webhook: one bundle, deployed as a cloud function (AWS Lambda), that the...",
           "path": "docs/phoenix/webhooks.mdx",
           "category": [
             "Phoenix",
@@ -686,6 +706,16 @@
           ],
           "source": "storybook-example"
         },
+        {
+          "title": "Custom Layout",
+          "description": "Make the configurator look like the brand's own product page. A furniture shop wants its table configurator to read like the rest of its site: a floating panel on the left with the product's name,...",
+          "path": "docs/layouts/custom-layout.mdx",
+          "category": [
+            "Layouts",
+            "Custom Layout"
+          ],
+          "source": "storybook-example"
+        },
         {
           "title": "Custom Price",
           "description": "The custom price footer component replaces the standard price display in the sidebar footer with a fully customizable React component. This allows you to create custom pricing interfaces, add...",
@@ -804,6 +834,17 @@
               ],
               "source": "storybook-example"
             },
+            {
+              "title": "In a Custom Layout",
+              "description": "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...",
+              "path": "docs/layouts/sidebar/in-a-custom-layout.mdx",
+              "category": [
+                "Layouts",
+                "Sidebar",
+                "In a Custom Layout"
+              ],
+              "source": "storybook-example"
+            },
             {
               "title": "General",
               "description": "The sidebar is the primary navigation and control interface in Phoenix configurators. It provides a flexible container for property pages, tabs, summary views, and other interactive components that...",
@@ -840,6 +881,100 @@
           ],
           "subcategories": []
         },
+        {
+          "name": "Gallery",
+          "docs": [
+            {
+              "title": "Ardent Compressor",
+              "description": "Quote an engineered product from a form, with no 3D model at all. An industrial compressor maker, Ardent Air, lets plant engineers size a rotary screw compressor and ask for a firm quote. The...",
+              "path": "docs/layouts/gallery/ardent-compressor.mdx",
+              "category": [
+                "Layouts",
+                "Gallery",
+                "Ardent Compressor"
+              ],
+              "source": "storybook-example"
+            },
+            {
+              "title": "Corvid Drone",
+              "description": "Build a pro tool in which an engineer configures a product and a client reads the result. A drone maker, Corvid Aero, has its engineers configure the K6 survey drone for each customer: the frame, the...",
+              "path": "docs/layouts/gallery/corvid-drone.mdx",
+              "category": [
+                "Layouts",
+                "Gallery",
+                "Corvid Drone"
+              ],
+              "source": "storybook-example"
+            },
+            {
+              "title": "Fenwick Window",
+              "description": "Show a made-to-measure product as the drawing a workshop would build it from. A joinery, Fenwick & Lowe, sells timber casement windows to order: the customer sets the overall size, the panes across,...",
+              "path": "docs/layouts/gallery/fenwick-window.mdx",
+              "category": [
+                "Layouts",
+                "Gallery",
+                "Fenwick Window"
+              ],
+              "source": "storybook-example"
+            },
+            {
+              "title": "Ferrule Bar Station",
+              "description": "Let a bar designer lay out a commercial bartender station and hand the result straight to the workshop. A fictional maker, Ferrule Barworks, sells stainless underbar stations built from modules: ice...",
+              "path": "docs/layouts/gallery/ferrule-bar-station.mdx",
+              "category": [
+                "Layouts",
+                "Gallery",
+                "Ferrule Bar Station"
+              ],
+              "source": "storybook-example"
+            },
+            {
+              "title": "Kestrel Kettle",
+              "description": "Sell a small product from one calm page that looks like the shop's own. A specialty-coffee shop, Aldermoor Coffee, sells its Kestrel pour-over kettle in three finishes, two handle woods and with or...",
+              "path": "docs/layouts/gallery/kestrel-kettle.mdx",
+              "category": [
+                "Layouts",
+                "Gallery",
+                "Kestrel Kettle"
+              ],
+              "source": "storybook-example"
+            },
+            {
+              "title": "Nightjar Guitar",
+              "description": "Walk a customer through a product one step at a time and end in an order. A custom guitar shop, Northfret, sells its Nightjar electric guitar through a five-step wizard: the body, the neck, the...",
+              "path": "docs/layouts/gallery/nightjar-guitar.mdx",
+              "category": [
+                "Layouts",
+                "Gallery",
+                "Nightjar Guitar"
+              ],
+              "source": "storybook-example"
+            },
+            {
+              "title": "Sunfold Solar",
+              "description": "Help a household decide on a system by showing what it would do for them. A solar installer, Sunfold, lets a homeowner plan panels and a battery for their roof: the roof's area and direction, the...",
+              "path": "docs/layouts/gallery/sunfold-solar.mdx",
+              "category": [
+                "Layouts",
+                "Gallery",
+                "Sunfold Solar"
+              ],
+              "source": "storybook-example"
+            },
+            {
+              "title": "Tidepool Aquascape",
+              "description": "Let a customer compose a product from pieces they add, change and take away, in a workspace that shows the result as they go. An aquascaping studio, Tidepool Studio, sells planted aquariums: the...",
+              "path": "docs/layouts/gallery/tidepool-aquascape.mdx",
+              "category": [
+                "Layouts",
+                "Gallery",
+                "Tidepool Aquascape"
+              ],
+              "source": "storybook-example"
+            }
+          ],
+          "subcategories": []
+        },
         {
           "name": "Header",
           "docs": [
@@ -1077,7 +1212,7 @@
         },
         {
           "title": "Text Input",
-          "description": "Describe the use case for this story. What problem does it solve? When should this pattern be used?",
+          "description": "Let the user type free text that becomes part of the configuration: a name for the design, an engraving on a heater panel, a signature on a guitar, a monogram on a bag. The text is stored in a string...",
           "path": "docs/controls/text-input.mdx",
           "category": [
             "Controls",
@@ -2744,7 +2879,7 @@
         },
         {
           "title": "Navigation Guard",
-          "description": "Describe the use case for this story. What problem does it solve? When should this pattern be used?",
+          "description": "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...",
           "path": "docs/complex-use-cases/navigation-guard.mdx",
           "category": [
             "Complex Use Cases",
@@ -2754,7 +2889,7 @@
         },
         {
           "title": "Navigation Reset Selection",
-          "description": "The `createResetSelectionOnNavigationTransformer` automatically deselects entities when the user navigates to specific steps. This clears the active selection when entering certain workflow phases,...",
+          "description": "A transformer built with `when.navigated({ to: [...] }).then.deselect()` automatically deselects entities when the user navigates to specific steps. This clears the active selection when entering...",
           "path": "docs/complex-use-cases/navigation-reset-selection.mdx",
           "category": [
             "Complex Use Cases",

package/dist/docs/integrations/lifecycle-providers.mdx

@@ -26,7 +26,6 @@ Read published data, authenticated session data, and web-component properties di
 ```tsx
 import { useWebComponentPropertyValue } from '@salsita-ai/sdk/react'
 
-import { phx } from '../../.phoenix/phx.js'
 import { webComponentProperties } from '../_shared/web-component-options.js'
 
 export default phx.frontend.createOnPublishedDataReadyProvider(({ children }) => {
@@ -49,8 +48,6 @@ The provider must render `children` when validation passes. Returning an empty f
 Use `createOnFrontendDataReadyProvider` to reject an unsupported combination of host inputs before Phoenix sends collected frontend data to the backend. Use `createOnBackendDataReadyProvider` to check a returned price list or permissions before the configurator initializes. Register each provider in its own `src/elements/` file, using the same `children` pattern as the published-data gate. The example's `LifecycleGate` is only a demonstration device; a real gate renders `children` as soon as its check passes.
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createOnFrontendDataReadyProvider(({ children }) => {
   const frontendData = phx.frontend.useFrontendData()
 
@@ -335,7 +332,6 @@ export const webComponentProperties = {
 ```tsx
 import { useState } from 'react'
 
-import { phx } from '../../.phoenix/phx.js'
 import { LifecycleGate } from '../_shared/LifecycleGate.js'
 import { LifecycleLogPanel } from '../_shared/LifecycleLogPanel.js'
 import { resetLifecycleLog } from '../_shared/lifecycle-log.js'
@@ -358,7 +354,6 @@ export default phx.frontend.createOnApplicationStartProvider(({ children }) => {
 ### ./src/elements/OnBackendDataReady.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { LifecycleGate } from '../_shared/LifecycleGate.js'
 
 export default phx.frontend.createOnBackendDataReadyProvider(({ children }) => {
@@ -379,7 +374,6 @@ export default phx.frontend.createOnBackendDataReadyProvider(({ children }) => {
 ### ./src/elements/OnConfiguratorReady.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { LifecycleGate } from '../_shared/LifecycleGate.js'
 
 export default phx.frontend.createOnConfiguratorReadyProvider(({ children }) => {
@@ -400,7 +394,6 @@ export default phx.frontend.createOnConfiguratorReadyProvider(({ children }) =>
 ### ./src/elements/OnFrontendDataReady.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { LifecycleGate } from '../_shared/LifecycleGate.js'
 
 export default phx.frontend.createOnFrontendDataReadyProvider(({ children }) => {
@@ -423,7 +416,6 @@ export default phx.frontend.createOnFrontendDataReadyProvider(({ children }) =>
 ```tsx
 import { useWebComponentPropertyValue } from '@salsita-ai/sdk/react'
 
-import { phx } from '../../.phoenix/phx.js'
 import { LifecycleGate } from '../_shared/LifecycleGate.js'
 import { webComponentProperties } from '../_shared/web-component-options.js'
 
@@ -455,7 +447,6 @@ export default phx.frontend.createOnPublishedDataReadyProvider(({ children }) =>
 ```tsx
 import { useRoutingState } from '@salsita-ai/sdk/react'
 
-import { phx } from '../../.phoenix/phx.js'
 import { LifecycleGate } from '../_shared/LifecycleGate.js'
 
 export default phx.frontend.createOnRoutingReadyProvider(({ children }) => {
@@ -472,7 +463,6 @@ export default phx.frontend.createOnRoutingReadyProvider(({ children }) => {
 ### ./src/elements/OnSessionReady.tsx
 
 ```tsx
-import { phx } from '../../.phoenix/phx.js'
 import { LifecycleGate } from '../_shared/LifecycleGate.js'
 
 export default phx.frontend.createOnSessionReadyProvider(({ children }) => {
@@ -493,7 +483,6 @@ export default phx.frontend.createOnSessionReadyProvider(({ children }) => {
 ### ./src/handlers/collect-frontend-data.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { appendLifecycleEntry } from '../_shared/lifecycle-log.js'
 
 export default phx.frontend.createCollectFrontendDataHandler(async () => {
@@ -506,7 +495,6 @@ export default phx.frontend.createCollectFrontendDataHandler(async () => {
 ### ./src/handlers/get-web-component-options.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { webComponentProperties } from '../_shared/web-component-options.js'
 
 export default phx.frontend.createGetWebComponentOptionsHandler(() => ({

package/dist/docs/integrations/onloadprovider.mdx

@@ -65,7 +65,6 @@ import { customSummaryPageComponent, memoEval, propertyPageComponent } from '@sa
 
 import { MockSidebarOne } from '../../../../common/MockSidebar.js'
 import { MockSummary } from '../../../../common/MockSummary.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default [
   phx.domain.attachComponent
@@ -103,8 +102,6 @@ import { useEffect, useState } from 'react'
 import { useRoutingState } from '@salsita-ai/sdk/react'
 import { Loader } from '@salsita-ai/sdk/ui'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createOnConfiguratorReadyProvider(({ children }) => {
   const [state, setState] = useState('loading')
 

package/dist/docs/integrations/webcomponent-api/basics.mdx

@@ -214,6 +214,8 @@ Properties use camelCase (`integrationMode`), while attributes use kebab-case (`
 
 Attributes are **write-only from the host's perspective**: setting an attribute (in HTML or via `setAttribute`) flows the value into the property, but the WC **never reflects property changes back to attributes**. To read the current value, always use the JavaScript property, not `getAttribute`.
 
+Boolean attributes (`readonly`, `expanded`, and a custom property whose `attributeParser` is `webComponentAttributeParsers.boolean`) follow the HTML convention: present without a value (`<salsita-configurator readonly>`, `setAttribute('readonly', '')`) or with their own name as the value (`readonly="readonly"`), they switch the property on. `"true"` and `"false"` work too; any other value is ignored with an error in the console. Removing the attribute resets the property to its default.
+
 Standard property to attribute mapping:
 
 | Property            | Attribute(s)                                               |
@@ -666,6 +668,8 @@ export const AddToCartButton = () => {
 }
 ```
 
+The example attaches this button as a legacy `finalizeButton` component; a new project declares `finalizeAction` components instead, see [Finalization](?path=/docs/phoenix-finalization--docs).
+
 ### Live preview
 
 ## Client-facing documentation
@@ -682,6 +686,10 @@ If you need a client-facing manual explaining how they can integrate the configu
 ### ./spec/domain.yaml
 
 ```yaml
+availableLocales:
+  - en
+  - cs
+
 model:
   latest:
     entityTypes:
@@ -788,7 +796,6 @@ import {
 import { MockSidebarOne } from '../../../../common/MockSidebar.js'
 import { MockSummary } from '../../../../common/MockSummary.js'
 import { getMockChairComponents } from '../../../../common/mock-chair-model/mock-chair-model-components.js'
-import { phx } from '../../.phoenix/phx.js'
 import { webComponentEvents, webComponentProperties } from '../_shared/web-component-optionts.js'
 
 const pushToECommerce = (_accessToken: string, _cartId: string, _name: string, _price: number) =>
@@ -881,7 +888,6 @@ export default [
 ### ./src/handlers/get-webcomponent-options.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { webComponentEvents, webComponentProperties } from '../_shared/web-component-optionts.js'
 
 export default phx.frontend.createGetWebComponentOptionsHandler(() => ({

package/dist/docs/integrations/webcomponent-api/preset-tags.mdx

@@ -71,6 +71,10 @@ Alternatively, the `presetTags` HTML attribute can be provided with a comma-sepa
 ### ./spec/domain.yaml
 
 ```yaml
+availableLocales:
+  - en
+  - cs
+
 model:
   latest:
     entityTypes:
@@ -139,7 +143,6 @@ presets:
 
 ```tsx
 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)]
 ```

package/dist/docs/integrations/woocommerce/overview.mdx

@@ -13,7 +13,7 @@ It is written in PHP and calls WordPress/WooCommerce helper functions.
 ## Store integration
 
 You will need a configurator web component build. For general information on how to embed the configurator
-into a host application, see [WebComponent API - Basics](/docs/integrations-webcomponent-api-basics--docs).
+into a host application, see [WebComponent API - Basics](?path=/docs/integrations-webcomponent-api-basics--docs).
 Additionally, due to the way WordPress works, there are a few specific steps you need to take to embed the
 configurator into WordPress.
 
@@ -41,7 +41,9 @@ but generally, at least the `session` and `add-to-cart-url` are required. The in
 the values as attributes on the configurator tag.
 
 When the user clicks the cart button in the configurator, the values `session` and `add-to-cart-url` are passed
-in a request to the finalization endpoint on the configurator server. During the finalization process, the cart item
+in a request to the finalization endpoint on the configurator server. The platform sends the plugin's API key to the cart endpoint,
+so the project's webhook builds the absolute URL from the shop's URL, kept in a webhook environment variable, and refuses any
+other origin; see the WooCommerceAddToCart task in [Webhooks](?path=/docs/phoenix-webhooks--docs). During the finalization process, the cart item
 data (eg. name, description, price) is calculated, and at the end a request is made to the plugin endpoint, to add
 the item to the cart.