@salsita-ai/sdk 0.50.0-develop.801a817d3f → 0.50.0-develop.9267bdc12e

package/dist/docs/layouts/custom-layout.mdx

@@ -0,0 +1,981 @@
+# Custom Layout
+
+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, the edge finishes as picture cards, the price in large type and one clear call to action, and the table in the space beside it. The project writes that page as one React component. Phoenix supplies the 3D scene, the product's state and a few hooks; every pixel around the scene is the project's own.
+
+- [Choose this approach](#choose-this-approach)
+- [Register the layout](#register-the-layout)
+- [What the layout has to do](#what-the-layout-has-to-do)
+- [Read and change the product](#read-and-change-the-product)
+- [Draw the choices](#draw-the-choices)
+- [Offer fullscreen](#offer-fullscreen)
+- [Serve read mode](#serve-read-mode)
+- [The spec the layout reads](#the-spec-the-layout-reads)
+- [Try the example](#try-the-example)
+- [Test cases](#test-cases)
+- [Known gaps](#known-gaps)
+- [Related pages](#related-pages)
+- [Complete Implementation](#complete-implementation)
+
+## Choose this approach
+
+Write your own layout when the configurator has to follow a design the built-in layout cannot take on: the brand's typography, controls and spacing, a panel on the left, a top bar with the price, an area the built-in layout has no place for.
+
+Stay with the built-in layout when its structure fits and only its parts change. [Universal](?path=/docs/layouts-universal--docs) demonstrates that layout, and the pages of its parts describe what the spec configures: [Header](?path=/docs/layouts-header-floating--docs), [Sidebar](?path=/docs/layouts-sidebar-general--docs), [Sidebar Footer](?path=/docs/layouts-sidebar-footer-basic--docs), [Toolbar](?path=/docs/layouts-toolbar--docs) and [View Controls](?path=/docs/layouts-view-controls--docs).
+
+A project layout replaces all of that. None of the built-in sidebar, footer, toolbar or property pages is rendered for it, so the layout builds every control the user needs. This example uses no SDK component that draws UI: only the scene, the safe-area hook and hooks that read and change the product's state. A layout may also mount the SDK's own pieces where it wants them, see [Configurator Interface → Loaded Configuration UI](?path=/docs/phoenix-configurator-interface--docs#loaded-configuration-ui).
+
+## Register the layout
+
+Create `src/elements/ConfiguratorLayout.tsx` with a default export made by `phx.frontend.createCustomPhoenixLayoutElement`. The name `ConfiguratorLayout` is what makes it the layout: Phoenix renders the element registered under that name for every loaded configuration, in owner and in read mode, whatever `layout` the spec sets. Nothing in the YAML refers to it.
+
+```tsx
+import { Box } from '@mui/material'
+
+import { LayoutSlots, useSceneSafeArea } from '@salsita-ai/sdk/configurator'
+
+import { phx } from '../../.phoenix/phx.js'
+import { FullscreenToggle } from '../_shared/FullscreenToggle.js'
+import { ProductPanel } from '../_shared/ProductPanel.js'
+
+const GUTTER = 24
+const PANEL_WIDTH = 380
+
+const ConfiguratorLayout = () => {
+  const { containerRef, safeAreaRef } = useSceneSafeArea()
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+
+  return (
+    <Box component="div" ref={containerRef} sx={{ position: 'absolute', inset: 0 }}>
+      <LayoutSlots.SharedCanvas />
+
+      {!isFullscreen && (
+        <Box
+          component="aside"
+          sx={{
+            position: 'absolute',
+            insetBlockStart: GUTTER,
+            insetInlineStart: GUTTER,
+            inlineSize: PANEL_WIDTH,
+            maxBlockSize: `calc(100% - ${2 * GUTTER}px)`,
+            display: 'flex',
+            flexDirection: 'column',
+            borderRadius: 5,
+            bgcolor: 'background.paper',
+            boxShadow: '0 12px 40px rgba(0, 0, 0, 0.12)',
+            overflow: 'hidden',
+          }}
+        >
+          <ProductPanel />
+        </Box>
+      )}
+
+      <Box
+        component="div"
+        ref={safeAreaRef}
+        sx={{
+          position: 'absolute',
+          insetBlock: 0,
+          insetInlineStart: isFullscreen ? 0 : PANEL_WIDTH + 2 * GUTTER,
+          insetInlineEnd: 0,
+          pointerEvents: 'none',
+        }}
+      >
+        <Box
+          component="div"
+          sx={{ position: 'absolute', insetBlockStart: GUTTER, insetInlineEnd: GUTTER, pointerEvents: 'auto' }}
+        >
+          <FullscreenToggle />
+        </Box>
+      </Box>
+    </Box>
+  )
+}
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+```
+
+The components it uses live in `src/_shared/`, which Phoenix does not import by convention, so the layout imports them itself. Application projects receive `phx` as a global. Storybook examples cannot rely on that project environment, so these files import it from `../../.phoenix/phx.js`; leave that import out in a project.
+
+## What the layout has to do
+
+- **Position the root and cover the page.** `LayoutSlots.SharedCanvas` is absolutely positioned and fills its nearest positioned ancestor. The root here is `position: absolute; inset: 0`.
+- **Mount the shared canvas.** The app loader stays on screen until the scene has loaded. A layout without `LayoutSlots.SharedCanvas` never gets past the loader unless the project sets `appLoader: legacy`.
+- **Put the UI above the canvas.** The canvas is opaque. Content that is positioned and comes after it in the markup is painted above it; unpositioned content is painted under it and cannot be seen.
+- **Tell the camera where the free area is.** `useSceneSafeArea()` returns two refs. `containerRef` goes on the element that covers the whole canvas, `safeAreaRef` on the region the product should stay visible in, here everything right of the panel. The camera then frames the product in that region. The hook measures again whenever either of the two elements resizes; for a change no resize reports, such as a `transform` on an ancestor settling at the end of an animation, it also returns `update` to call. Without the two refs the product is centred in the whole canvas and sits against the panel.
+- **Let the pointer through.** The safe-area element lies over the canvas, so it sets `pointerEvents: 'none'`; otherwise the scene cannot be orbited. The fullscreen button inside it switches pointer events back on.
+- **Honour fullscreen.** Fullscreen is a flag in the product's state, not a browser feature. The layout reads it with `phx.frontend.useIsFullscreenActive()`, removes the panel and lets the safe area start at the left edge, so the camera frames the product in the whole canvas.
+- **Serve read mode.** The same element renders a configuration shared for viewing, and the layout decides what a viewer sees.
+
+## Read and change the product
+
+The panel reads everything it shows from hooks and writes the customer's choice back through one of them. The table lists the hooks the whole layout uses:
+
+```tsx
+import { Box, Button, Typography } from '@mui/material'
+
+import { detailComponent } from '@salsita-ai/sdk/domain'
+import { useResolveLocalizable } from '@salsita-ai/sdk/react'
+
+import { phx } from '../../.phoenix/phx.js'
+import { EdgeFinishCards } from './EdgeFinishCards.js'
+
+export const ProductPanel = () => {
+  const resolve = useResolveLocalizable()
+  const detail = phx.frontend.useFirstRootComponent(detailComponent)
+  const price = phx.frontend.useRootEntityPrice()
+  const tableId = phx.frontend.useRootEntityId()
+  const edgeFinish = phx.frontend.useAttributeSelection(tableId, 'edgeFinish')
+  const { accessInfo } = phx.frontend.useAccessService()
+  const navigationState = phx.frontend.useActiveNavigationState()
+  const pushNavigate = phx.frontend.usePushNavigate()
+  const popNavigate = phx.frontend.usePopNavigate()
+
+  const isReadMode = accessInfo.viewMode
+  const isReview = isReadMode || navigationState === 'checkout'
+  const chosenEdge = edgeFinish.options.find(option => option.value === edgeFinish.value)
+
+  return (
+    <>
+      <Box component="header" sx={{ display: 'grid', gap: 1, padding: 3, paddingBlockEnd: 2 }}>
+        {isReadMode ? (
+          <Typography
+            variant="overline"
+            sx={{ justifySelf: 'start', paddingInline: 1.5, borderRadius: 999, bgcolor: 'action.selected' }}
+          >
+            View only
+          </Typography>
+        ) : (
+          <Typography variant="overline" color="text.secondary">
+            {resolve(detail?.state.subtitle)}
+          </Typography>
+        )}
+        <Typography variant="h5" component="h2" fontWeight={700}>
+          {resolve(detail?.state.title)}
+        </Typography>
+        <Typography variant="body2" color="text.secondary">
+          {resolve(detail?.state.description)}
+        </Typography>
+      </Box>
+
+      <Box component="div" sx={{ display: 'grid', gap: 1.5, paddingInline: 3, paddingBlockEnd: 3, overflowY: 'auto' }}>
+        <Typography variant="subtitle2" component="h3">
+          Edge finish
+        </Typography>
+        {isReview ? (
+          <Box component="div" sx={{ padding: 2, borderRadius: 3, bgcolor: 'action.hover' }}>
+            <Typography variant="body2" fontWeight={600}>
+              {resolve(chosenEdge?.title)}
+            </Typography>
+            <Typography variant="caption" color="text.secondary">
+              {resolve(chosenEdge?.description)}
+            </Typography>
+          </Box>
+        ) : (
+          <EdgeFinishCards selection={edgeFinish} />
+        )}
+      </Box>
+
+      <Box component="footer" sx={{ display: 'grid', gap: 2, padding: 3, borderTop: 1, borderColor: 'divider' }}>
+        <Box component="div" sx={{ display: 'flex', alignItems: 'baseline', justifyContent: 'space-between' }}>
+          <Typography variant="body2" color="text.secondary">
+            Total price
+          </Typography>
+          <Typography variant="h5" component="p" fontWeight={700}>
+            {price}
+          </Typography>
+        </Box>
+        {isReview && !isReadMode && (
+          <Typography variant="body2" color="text.secondary">
+            Your table is ready for a quote. A real shop collects the contact details here.
+          </Typography>
+        )}
+        {!isReadMode && (
+          <Button
+            size="large"
+            variant={isReview ? 'outlined' : 'contained'}
+            onClick={isReview ? popNavigate : () => pushNavigate('checkout')}
+            sx={{ minBlockSize: 48, borderRadius: 999, textTransform: 'none', fontWeight: 600 }}
+          >
+            {isReview ? 'Back to the configuration' : 'Review and request a quote'}
+          </Button>
+        )}
+      </Box>
+    </>
+  )
+}
+```
+
+| Hook                                                                         | What the layout uses it for                                                                                                                                                 |
+| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `phx.frontend.useFirstRootComponent(detailComponent)`                        | The `detail` component of the root entity: name, subtitle and description. `detailComponent` comes from `@salsita-ai/sdk/domain`; the hook returns `null` without one.      |
+| `phx.frontend.useRootEntityId()`                                             | The id of the table, which the control hooks take.                                                                                                                          |
+| `phx.frontend.useAttributeSelection(entityId, instanceName)`                 | The `attributeSelection` component named `edgeFinish`: the current `value` and the `options`, each with `title`, `description`, `value`, `disabled` and `onSelect`.         |
+| `phx.frontend.useRootEntityPrice()`                                          | The root entity's `price` component, formatted for the current locale and currency, or `null` without one.                                                                  |
+| `phx.frontend.useAccessService()`                                            | `accessInfo.viewMode` is `true` while a configuration shared for viewing is open, and also while the host sets the `readonly` property.                                     |
+| `phx.frontend.useActiveNavigationState()`                                    | The active navigation state; the panel shows its review step while it is `checkout`.                                                                                        |
+| `phx.frontend.usePushNavigate()` and `phx.frontend.usePopNavigate()`         | Enter the review step and leave it again.                                                                                                                                   |
+| `phx.frontend.useIsFullscreenActive()` and `phx.frontend.useSetFullscreen()` | Read the fullscreen flag, and set it from the layout's own button.                                                                                                          |
+| `useResolveLocalizable()` from `@salsita-ai/sdk/react`                       | Turns the localizable texts of the spec into strings in the current language. [Localization](?path=/docs/phoenix-localization--docs) describes it and `LocalizableMessage`. |
+
+Calling an option's `onSelect` is the whole write: it changes `edgeFinish` on the table, the scene morphs the edge and the price expression recalculates. The option fields are named for display: the spec's `label` arrives as `title`, its `img` as `imageSrc`.
+
+The review step is the layout's own: the button pushes the `checkout` navigation state, and the panel shows a summary instead of the cards. A real shop collects the contact details there and sends the request.
+
+## Draw the choices
+
+The edge finish is a visual choice, so the panel shows it as cards with a drawing of each profile, as [Choosing a Control](?path=/docs/ux-guidelines-choosing-a-control--docs) recommends for shapes. The selected card has a border in the theme's primary colour, a tinted background and a check mark, so the state does not depend on colour alone. The cards form a radio group: the group has `role="radiogroup"` and a label, each card `role="radio"` and `aria-checked`, only the selected card is in the tab order, and the arrow keys move the selection, skipping disabled options, as in a native radio group. Each card is at least 44 pixels high and shows a focus ring for keyboard users.
+
+```tsx
+import { Box, ButtonBase, type SxProps, type Theme, Typography } from '@mui/material'
+import type { KeyboardEvent } from 'react'
+
+import { type UseAttributeSelection, useResolveLocalizable } from '@salsita-ai/sdk/react'
+
+// Cross-sections of the tabletop's edge, keyed by the option values of the spec.
+const EDGE_PROFILES: Readonly<Record<string, string>> = {
+  None: 'M0 4H32V20H0Z',
+  Facet: 'M0 4H26L32 10V14L26 20H0Z',
+  Round: 'M0 4H24A8 8 0 0 1 24 20H0Z',
+  TreeTrunk: 'M0 4H27C33 5 28 9 34 11C29 13 34 17 27 20H0Z',
+}
+
+const CHECK_BADGE: SxProps<Theme> = {
+  position: 'absolute',
+  insetBlockStart: 10,
+  insetInlineEnd: 10,
+  display: 'grid',
+  placeItems: 'center',
+  inlineSize: 22,
+  blockSize: 22,
+  borderRadius: '50%',
+  bgcolor: 'primary.main',
+  color: 'primary.contrastText',
+  fontSize: 13,
+}
+
+// Arrow keys move the selection between the cards, as in a native radio group.
+const ARROW_STEPS: Readonly<Record<string, number | undefined>> = {
+  ArrowRight: 1,
+  ArrowDown: 1,
+  ArrowLeft: -1,
+  ArrowUp: -1,
+}
+
+interface EdgeFinishCardsProps {
+  readonly selection: ReturnType<UseAttributeSelection>
+}
+
+export const EdgeFinishCards = ({ selection }: EdgeFinishCardsProps) => {
+  const resolve = useResolveLocalizable()
+  const { options } = selection
+  // The card in the tab order: the selected one, or the first enabled one. Disabled cards are never in it.
+  const selectedIndex = options.findIndex(option => option.value === selection.value && !option.disabled)
+  const focusIndex = selectedIndex >= 0 ? selectedIndex : options.findIndex(option => !option.disabled)
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLElement>, index: number) => {
+    const step = ARROW_STEPS[event.key]
+
+    if (step === undefined) {
+      return
+    }
+
+    event.preventDefault()
+    // The next enabled option in the arrow's direction, wrapping around; disabled options are skipped.
+    const count = options.length
+    const next = Array.from(
+      { length: count - 1 },
+      (_, offset) => (((index + step * (offset + 1)) % count) + count) % count
+    ).find(candidate => !options[candidate]?.disabled)
+
+    if (next === undefined) {
+      return
+    }
+
+    options[next]?.onSelect()
+    event.currentTarget.parentElement?.querySelectorAll<HTMLElement>('[role="radio"]')[next]?.focus()
+  }
+
+  return (
+    <Box
+      component="div"
+      role="radiogroup"
+      aria-label="Edge finish"
+      sx={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 1.5 }}
+    >
+      {options.map((option, index) => {
+        const isSelected = option.value === selection.value
+
+        return (
+          <ButtonBase
+            key={String(option.value)}
+            role="radio"
+            aria-checked={isSelected}
+            tabIndex={index === focusIndex ? 0 : -1}
+            disabled={option.disabled}
+            onClick={option.onSelect}
+            onKeyDown={event => handleKeyDown(event, index)}
+            sx={{
+              position: 'relative',
+              display: 'grid',
+              justifyItems: 'start',
+              gap: 0.5,
+              padding: 2,
+              borderRadius: 3,
+              border: 2,
+              borderColor: isSelected ? 'primary.main' : 'divider',
+              bgcolor: isSelected ? 'action.hover' : 'transparent',
+              textAlign: 'start',
+              transition: 'border-color 150ms, background-color 150ms',
+              '&:hover': { borderColor: isSelected ? 'primary.main' : 'text.disabled' },
+              '&.Mui-focusVisible': { outline: 2, outlineColor: 'primary.main', outlineOffset: 2 },
+              '&.Mui-disabled': { opacity: 0.4 },
+            }}
+          >
+            {isSelected && (
+              <Box component="span" aria-hidden sx={CHECK_BADGE}>
+                ✓
+              </Box>
+            )}
+            <Box
+              component="svg"
+              viewBox="0 0 36 24"
+              aria-hidden
+              sx={{ inlineSize: 60, blockSize: 40, color: '#b98b5e' }}
+            >
+              <path d={EDGE_PROFILES[String(option.value)]} fill="currentColor" />
+            </Box>
+            <Typography variant="body2" fontWeight={600}>
+              {resolve(option.title)}
+            </Typography>
+            <Typography variant="caption" color="text.secondary">
+              {resolve(option.description)}
+            </Typography>
+          </ButtonBase>
+        )
+      })}
+    </Box>
+  )
+}
+```
+
+The drawings are keyed by the option values of the spec. A spec can carry a picture per option instead, as `img`, which the hook returns as `imageSrc`; [CardSelect](?path=/docs/controls-select-attribute-cardselect--docs) shows the SDK's own card control.
+
+## Offer fullscreen
+
+Fullscreen is a flag in the configurator's state, not the browser's fullscreen mode. `phx.frontend.useIsFullscreenActive()` reads it and `phx.frontend.useSetFullscreen()` returns a function that sets it: `setFullscreen(true)` turns it on, `setFullscreen(false)` off. The layout's own button flips it, and the layout decides what to hide.
+
+```tsx
+import { Button } from '@mui/material'
+
+import { phx } from '../../.phoenix/phx.js'
+
+const ENTER_ICON = 'M4 9V4h5M15 4h5v5M20 15v5h-5M9 20H4v-5'
+const EXIT_ICON = 'M9 4v5H4M15 4v5h5M15 20v-5h5M9 20v-5H4'
+
+export const FullscreenToggle = () => {
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+  const setFullscreen = phx.frontend.useSetFullscreen()
+
+  return (
+    <Button
+      onClick={() => setFullscreen(!isFullscreen)}
+      startIcon={
+        <svg viewBox="0 0 24 24" width={20} height={20} fill="none" stroke="currentColor" strokeWidth={2}>
+          <path d={isFullscreen ? EXIT_ICON : ENTER_ICON} />
+        </svg>
+      }
+      sx={{
+        minBlockSize: 44,
+        paddingInline: 2.5,
+        borderRadius: 999,
+        bgcolor: 'background.paper',
+        color: 'text.primary',
+        boxShadow: '0 4px 16px rgba(0, 0, 0, 0.12)',
+        textTransform: 'none',
+        fontWeight: 600,
+        '&:hover': { bgcolor: 'background.paper', boxShadow: '0 6px 20px rgba(0, 0, 0, 0.18)' },
+      }}
+    >
+      {isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}
+    </Button>
+  )
+}
+```
+
+The button stays in the free area in both states, so the way back is always where the user left it. [Interaction Modes](?path=/docs/ux-guidelines-interaction-modes--docs#full-screen-preview) describes what fullscreen hides.
+
+## Serve read mode
+
+While `accessInfo.viewMode` is `true` the panel marks the view as view only, replaces the cards with the chosen finish and shows the price without an action. The hooks do not hide or disable anything in read mode: what a viewer can change is decided by what the layout renders. Rotating and zooming the scene, and fullscreen, stay available, as [Interaction Modes](?path=/docs/ux-guidelines-interaction-modes--docs#view-only-mode) recommends.
+
+## The spec the layout reads
+
+The layout reads three components of the root entity and one navigation state; the scene components are in the complete implementation below.
+
+```yaml
+navigationStates:
+  - configure
+  - checkout
+
+components:
+  Table:
+    detail:
+      main:
+        title: Linden dining table
+        subtitle: Solid oak, seats six
+        description: A solid oak top on slender steel legs, finished with the edge profile of your choice.
+    price:
+      main:
+        price:
+          $read: $price
+    attributeSelection:
+      edgeFinish:
+        value:
+          $bind: edgeFinish
+        options:
+          - label: Square
+            description: Crisp and modern
+            value: None
+          - label: Facet
+            description: A light bevel
+            value: Facet
+          - label: Round
+            description: Soft to the touch
+            value: Round
+          - label: Tree trunk
+            description: The natural edge
+            value: TreeTrunk
+```
+
+`$price` is a custom expression in `src/expressions/table.ts` that adds a surcharge per finish. The example sets no `applicationConfig` and no layout components: `layout`, the header, the sidebar footer, the toolbar, `viewControls` and property pages configure the built-in layout and have no effect on this one.
+
+## Try the example
+
+To see read mode, open **Mocks** in the editor rail on the left and apply the **Read User** template.
+
+## Test cases
+
+- The panel is on the left and the table is centred in the area to the right of it, not in the whole canvas.
+- Choosing **Tree trunk** moves the check mark to that card, changes the edge of the tabletop and raises the price from $1,290.00 to $1,630.00.
+- Tab reaches the selected card, and the arrow keys move the selection to the next or previous card.
+- Dragging in the area to the right of the panel orbits the camera.
+- **Review and request a quote** replaces the cards with the chosen finish; **Back to the configuration** brings them back.
+- **Fullscreen** removes the panel and the table moves to the centre of the canvas; **Exit fullscreen** brings both back.
+- With the **Read User** mock the panel says **View only**, shows the chosen finish and the price, and has no button.
+
+## Known gaps
+
+A project layout has only what it renders. This one leaves out the following, each of which a product may need.
+
+- **Phone width.** The panel is written for desktop: on a narrow screen it covers the scene. A phone layout puts the panel in a bottom sheet and moves the safe area above it.
+- **Error, violation and side-effect messages.** The layout mounts nothing that shows them. `LayoutSlots.Services` raises invariant violations and side effects as snackbars, and shows "Oops, something went wrong" for an error thrown while the state is validated, for example by a custom expression, which any spec with custom expressions can hit, this one included; `LayoutSlots.DesktopSnackbarsRoot` is the element the snackbars are rendered into. A layout mounts both, or reads `phx.frontend.useStateValidity()` and shows them its own way.
+- **A finalize page from the spec.** The review step here is the layout's own and submits nothing. It does not show a `finalizePage` component and does not check `phx.frontend.useFinalizeViolations()`. [Finalization](?path=/docs/phoenix-finalization--docs) covers what a real flow does.
+- **Toolbar actions.** Undo and redo, camera reset, measurements, sharing and language switching are not offered. A layout can mount `LayoutSlots.DesktopToolbar` for the toolbar the spec configures, or build its own buttons.
+- **View controls, tool controls and leaving a tool mode.** A spec can configure view controls and tool controls, and a tool mode has a button that leaves it. The built-in layout places them with `LayoutSlots.DesktopViewControls`, `LayoutSlots.DesktopToolControls` and `LayoutSlots.DesktopCallToAction`; this layout mounts none of them, so they do not appear.
+- **A project's layout dialog.** A dialog the project registers with `phx.frontend.createLayoutDialog` is shown by `LayoutDialog`, which the built-in layout mounts. This layout does not; a layout that needs the dialog mounts `LayoutDialog` from `@salsita-ai/sdk/configurator`.
+- **Selection.** The table has no parts to select. A product with selectable parts reads `phx.frontend.useSelectedDomainEntityId()` and shows the controls of the selected part.
+- **Clone to edit in read mode.** With `shareCloneToEdit` set, the built-in layout's `LayoutSlots.DesktopReadonlyBanner` offers **Edit configuration** to a viewer; this layout's "View only" label offers nothing. A layout mounts the banner, or builds its own action with `LayoutSlots.useIsCloningAllowed()` and `LayoutSlots.CloneToEditDialog`.
+- **Back and close.** The built-in header's back button returns to the product choice, runs the host's close action or leaves the expanded view, whichever applies. This layout has none of them. `useCloseAction()` from `@salsita-ai/sdk/configurator` returns the host's close action, or `null` when there is none; the hook that chooses among the three is not exported.
+- **Analytics.** The built-in fullscreen and finalize buttons record `FullScreenModeToggled` and `FinalizeButtonClicked`; this layout's buttons record nothing. A layout that wants the events pushes `FrontendAnalyticsFactory.FullScreenModeToggled()` and the like, from `@salsita-ai/sdk/configurator`, with `phx.frontend.useAnalytics().push(...)`.
+- **Preview start screen.** The built-in layout shows a preview while `usePreview().isPreview` is set, which `preview: auto` does on phones without the project opting in. This layout ignores it and always renders the interface.
+- **Assistant panel.** It is not exported, so a project layout cannot show it.
+- **"Powered by Salsita" mark.** The built-in layout shows it; a project layout decides whether to mount `LayoutSlots.DesktopPoweredBy`, and this one does not.
+
+## Related pages
+
+- [Configurator Interface → Loaded Configuration UI](?path=/docs/phoenix-configurator-interface--docs#loaded-configuration-ui) is the reference for the element name, the minimal layout and the SDK pieces a layout can mount.
+- [Universal](?path=/docs/layouts-universal--docs) is the built-in layout this one replaces.
+- [Header / Custom](?path=/docs/layouts-header-custom--docs) replaces only the header, with the price from `useRootEntityPrice()`.
+- [Canvas Padding](?path=/docs/layouts-canvas-padding--docs) scales the gaps `useSceneSafeArea()` measures.
+- [Presets / Custom](?path=/docs/layouts-presets-custom--docs) replaces the preset screen the same way.
+
+## 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:
+  - configure
+  - checkout
+
+components:
+  Table:
+    detail:
+      main:
+        title: Linden dining table
+        subtitle: Solid oak, seats six
+        description: A solid oak top on slender steel legs, finished with the edge profile of your choice.
+    price:
+      main:
+        price:
+          $read: $price
+    attributeSelection:
+      edgeFinish:
+        value:
+          $bind: edgeFinish
+        options:
+          - label: Square
+            description: Crisp and modern
+            value: None
+          - label: Facet
+            description: A light bevel
+            value: Facet
+          - label: Round
+            description: Soft to the touch
+            value: Round
+          - label: Tree trunk
+            description: The natural edge
+            value: TreeTrunk
+    fitRootPerspectiveCamera:
+      main:
+        priority: 1
+        fov: 35
+        near: 100
+        far: 10000
+        minDistance: 1000
+        maxDistance: 9000
+        distance: 5000
+        azimuthAngle: 1.5
+        polarAngle: 1.1
+        fitMeshChanges: 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
+```
+
+### ./src/\_shared/EdgeFinishCards.tsx
+
+```tsx
+import { Box, ButtonBase, type SxProps, type Theme, Typography } from '@mui/material'
+import type { KeyboardEvent } from 'react'
+
+import { type UseAttributeSelection, useResolveLocalizable } from '@salsita-ai/sdk/react'
+
+// Cross-sections of the tabletop's edge, keyed by the option values of the spec.
+const EDGE_PROFILES: Readonly<Record<string, string>> = {
+  None: 'M0 4H32V20H0Z',
+  Facet: 'M0 4H26L32 10V14L26 20H0Z',
+  Round: 'M0 4H24A8 8 0 0 1 24 20H0Z',
+  TreeTrunk: 'M0 4H27C33 5 28 9 34 11C29 13 34 17 27 20H0Z',
+}
+
+const CHECK_BADGE: SxProps<Theme> = {
+  position: 'absolute',
+  insetBlockStart: 10,
+  insetInlineEnd: 10,
+  display: 'grid',
+  placeItems: 'center',
+  inlineSize: 22,
+  blockSize: 22,
+  borderRadius: '50%',
+  bgcolor: 'primary.main',
+  color: 'primary.contrastText',
+  fontSize: 13,
+}
+
+// Arrow keys move the selection between the cards, as in a native radio group.
+const ARROW_STEPS: Readonly<Record<string, number | undefined>> = {
+  ArrowRight: 1,
+  ArrowDown: 1,
+  ArrowLeft: -1,
+  ArrowUp: -1,
+}
+
+interface EdgeFinishCardsProps {
+  readonly selection: ReturnType<UseAttributeSelection>
+}
+
+export const EdgeFinishCards = ({ selection }: EdgeFinishCardsProps) => {
+  const resolve = useResolveLocalizable()
+  const { options } = selection
+  // The card in the tab order: the selected one, or the first enabled one. Disabled cards are never in it.
+  const selectedIndex = options.findIndex(option => option.value === selection.value && !option.disabled)
+  const focusIndex = selectedIndex >= 0 ? selectedIndex : options.findIndex(option => !option.disabled)
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLElement>, index: number) => {
+    const step = ARROW_STEPS[event.key]
+
+    if (step === undefined) {
+      return
+    }
+
+    event.preventDefault()
+    // The next enabled option in the arrow's direction, wrapping around; disabled options are skipped.
+    const count = options.length
+    const next = Array.from(
+      { length: count - 1 },
+      (_, offset) => (((index + step * (offset + 1)) % count) + count) % count
+    ).find(candidate => !options[candidate]?.disabled)
+
+    if (next === undefined) {
+      return
+    }
+
+    options[next]?.onSelect()
+    event.currentTarget.parentElement?.querySelectorAll<HTMLElement>('[role="radio"]')[next]?.focus()
+  }
+
+  return (
+    <Box
+      component="div"
+      role="radiogroup"
+      aria-label="Edge finish"
+      sx={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 1.5 }}
+    >
+      {options.map((option, index) => {
+        const isSelected = option.value === selection.value
+
+        return (
+          <ButtonBase
+            key={String(option.value)}
+            role="radio"
+            aria-checked={isSelected}
+            tabIndex={index === focusIndex ? 0 : -1}
+            disabled={option.disabled}
+            onClick={option.onSelect}
+            onKeyDown={event => handleKeyDown(event, index)}
+            sx={{
+              position: 'relative',
+              display: 'grid',
+              justifyItems: 'start',
+              gap: 0.5,
+              padding: 2,
+              borderRadius: 3,
+              border: 2,
+              borderColor: isSelected ? 'primary.main' : 'divider',
+              bgcolor: isSelected ? 'action.hover' : 'transparent',
+              textAlign: 'start',
+              transition: 'border-color 150ms, background-color 150ms',
+              '&:hover': { borderColor: isSelected ? 'primary.main' : 'text.disabled' },
+              '&.Mui-focusVisible': { outline: 2, outlineColor: 'primary.main', outlineOffset: 2 },
+              '&.Mui-disabled': { opacity: 0.4 },
+            }}
+          >
+            {isSelected && (
+              <Box component="span" aria-hidden sx={CHECK_BADGE}>
+                ✓
+              </Box>
+            )}
+            <Box
+              component="svg"
+              viewBox="0 0 36 24"
+              aria-hidden
+              sx={{ inlineSize: 60, blockSize: 40, color: '#b98b5e' }}
+            >
+              <path d={EDGE_PROFILES[String(option.value)]} fill="currentColor" />
+            </Box>
+            <Typography variant="body2" fontWeight={600}>
+              {resolve(option.title)}
+            </Typography>
+            <Typography variant="caption" color="text.secondary">
+              {resolve(option.description)}
+            </Typography>
+          </ButtonBase>
+        )
+      })}
+    </Box>
+  )
+}
+```
+
+### ./src/\_shared/FullscreenToggle.tsx
+
+```tsx
+import { Button } from '@mui/material'
+
+import { phx } from '../../.phoenix/phx.js'
+
+const ENTER_ICON = 'M4 9V4h5M15 4h5v5M20 15v5h-5M9 20H4v-5'
+const EXIT_ICON = 'M9 4v5H4M15 4v5h5M15 20v-5h5M9 20v-5H4'
+
+export const FullscreenToggle = () => {
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+  const setFullscreen = phx.frontend.useSetFullscreen()
+
+  return (
+    <Button
+      onClick={() => setFullscreen(!isFullscreen)}
+      startIcon={
+        <svg viewBox="0 0 24 24" width={20} height={20} fill="none" stroke="currentColor" strokeWidth={2}>
+          <path d={isFullscreen ? EXIT_ICON : ENTER_ICON} />
+        </svg>
+      }
+      sx={{
+        minBlockSize: 44,
+        paddingInline: 2.5,
+        borderRadius: 999,
+        bgcolor: 'background.paper',
+        color: 'text.primary',
+        boxShadow: '0 4px 16px rgba(0, 0, 0, 0.12)',
+        textTransform: 'none',
+        fontWeight: 600,
+        '&:hover': { bgcolor: 'background.paper', boxShadow: '0 6px 20px rgba(0, 0, 0, 0.18)' },
+      }}
+    >
+      {isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}
+    </Button>
+  )
+}
+```
+
+### ./src/\_shared/ProductPanel.tsx
+
+```tsx
+import { Box, Button, Typography } from '@mui/material'
+
+import { detailComponent } from '@salsita-ai/sdk/domain'
+import { useResolveLocalizable } from '@salsita-ai/sdk/react'
+
+import { phx } from '../../.phoenix/phx.js'
+import { EdgeFinishCards } from './EdgeFinishCards.js'
+
+export const ProductPanel = () => {
+  const resolve = useResolveLocalizable()
+  const detail = phx.frontend.useFirstRootComponent(detailComponent)
+  const price = phx.frontend.useRootEntityPrice()
+  const tableId = phx.frontend.useRootEntityId()
+  const edgeFinish = phx.frontend.useAttributeSelection(tableId, 'edgeFinish')
+  const { accessInfo } = phx.frontend.useAccessService()
+  const navigationState = phx.frontend.useActiveNavigationState()
+  const pushNavigate = phx.frontend.usePushNavigate()
+  const popNavigate = phx.frontend.usePopNavigate()
+
+  const isReadMode = accessInfo.viewMode
+  const isReview = isReadMode || navigationState === 'checkout'
+  const chosenEdge = edgeFinish.options.find(option => option.value === edgeFinish.value)
+
+  return (
+    <>
+      <Box component="header" sx={{ display: 'grid', gap: 1, padding: 3, paddingBlockEnd: 2 }}>
+        {isReadMode ? (
+          <Typography
+            variant="overline"
+            sx={{ justifySelf: 'start', paddingInline: 1.5, borderRadius: 999, bgcolor: 'action.selected' }}
+          >
+            View only
+          </Typography>
+        ) : (
+          <Typography variant="overline" color="text.secondary">
+            {resolve(detail?.state.subtitle)}
+          </Typography>
+        )}
+        <Typography variant="h5" component="h2" fontWeight={700}>
+          {resolve(detail?.state.title)}
+        </Typography>
+        <Typography variant="body2" color="text.secondary">
+          {resolve(detail?.state.description)}
+        </Typography>
+      </Box>
+
+      <Box component="div" sx={{ display: 'grid', gap: 1.5, paddingInline: 3, paddingBlockEnd: 3, overflowY: 'auto' }}>
+        <Typography variant="subtitle2" component="h3">
+          Edge finish
+        </Typography>
+        {isReview ? (
+          <Box component="div" sx={{ padding: 2, borderRadius: 3, bgcolor: 'action.hover' }}>
+            <Typography variant="body2" fontWeight={600}>
+              {resolve(chosenEdge?.title)}
+            </Typography>
+            <Typography variant="caption" color="text.secondary">
+              {resolve(chosenEdge?.description)}
+            </Typography>
+          </Box>
+        ) : (
+          <EdgeFinishCards selection={edgeFinish} />
+        )}
+      </Box>
+
+      <Box component="footer" sx={{ display: 'grid', gap: 2, padding: 3, borderTop: 1, borderColor: 'divider' }}>
+        <Box component="div" sx={{ display: 'flex', alignItems: 'baseline', justifyContent: 'space-between' }}>
+          <Typography variant="body2" color="text.secondary">
+            Total price
+          </Typography>
+          <Typography variant="h5" component="p" fontWeight={700}>
+            {price}
+          </Typography>
+        </Box>
+        {isReview && !isReadMode && (
+          <Typography variant="body2" color="text.secondary">
+            Your table is ready for a quote. A real shop collects the contact details here.
+          </Typography>
+        )}
+        {!isReadMode && (
+          <Button
+            size="large"
+            variant={isReview ? 'outlined' : 'contained'}
+            onClick={isReview ? popNavigate : () => pushNavigate('checkout')}
+            sx={{ minBlockSize: 48, borderRadius: 999, textTransform: 'none', fontWeight: 600 }}
+          >
+            {isReview ? 'Back to the configuration' : 'Review and request a quote'}
+          </Button>
+        )}
+      </Box>
+    </>
+  )
+}
+```
+
+### ./src/elements/ConfiguratorLayout.tsx
+
+```tsx
+import { Box } from '@mui/material'
+
+import { LayoutSlots, useSceneSafeArea } from '@salsita-ai/sdk/configurator'
+
+import { phx } from '../../.phoenix/phx.js'
+import { FullscreenToggle } from '../_shared/FullscreenToggle.js'
+import { ProductPanel } from '../_shared/ProductPanel.js'
+
+const GUTTER = 24
+const PANEL_WIDTH = 380
+
+const ConfiguratorLayout = () => {
+  const { containerRef, safeAreaRef } = useSceneSafeArea()
+  const isFullscreen = phx.frontend.useIsFullscreenActive()
+
+  return (
+    <Box component="div" ref={containerRef} sx={{ position: 'absolute', inset: 0 }}>
+      <LayoutSlots.SharedCanvas />
+
+      {!isFullscreen && (
+        <Box
+          component="aside"
+          sx={{
+            position: 'absolute',
+            insetBlockStart: GUTTER,
+            insetInlineStart: GUTTER,
+            inlineSize: PANEL_WIDTH,
+            maxBlockSize: `calc(100% - ${2 * GUTTER}px)`,
+            display: 'flex',
+            flexDirection: 'column',
+            borderRadius: 5,
+            bgcolor: 'background.paper',
+            boxShadow: '0 12px 40px rgba(0, 0, 0, 0.12)',
+            overflow: 'hidden',
+          }}
+        >
+          <ProductPanel />
+        </Box>
+      )}
+
+      <Box
+        component="div"
+        ref={safeAreaRef}
+        sx={{
+          position: 'absolute',
+          insetBlock: 0,
+          insetInlineStart: isFullscreen ? 0 : PANEL_WIDTH + 2 * GUTTER,
+          insetInlineEnd: 0,
+          pointerEvents: 'none',
+        }}
+      >
+        <Box
+          component="div"
+          sx={{ position: 'absolute', insetBlockStart: GUTTER, insetInlineEnd: GUTTER, pointerEvents: 'auto' }}
+        >
+          <FullscreenToggle />
+        </Box>
+      </Box>
+    </Box>
+  )
+}
+
+export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout', ConfiguratorLayout)
+```
+
+### ./src/expressions/table.ts
+
+```ts
+import { phx } from '../../.phoenix/phx.js'
+
+const EDGE_FINISH_SURCHARGE = { None: 0, Facet: 90, Round: 120, TreeTrunk: 340 }
+
+export default phx.domain.implementCustomExpressions({
+  Table: {
+    $price: s => {
+      return 1290 + EDGE_FINISH_SURCHARGE[s.edgeFinish]
+    },
+    $edgeFinishFacet: s => {
+      return s.edgeFinish === 'Facet' ? 1 : 0
+    },
+    $edgeFinishRound: s => {
+      return s.edgeFinish === 'Round' ? 1 : 0
+    },
+    $edgeFinishTreeTrunk: s => {
+      return s.edgeFinish === 'TreeTrunk' ? 1 : 0
+    },
+  },
+})
+```
+
+</details>