themelia-react-ui 2.0.4 → 2.0.5

package/docs/consumer-skill/references/integration.md

@@ -33,6 +33,41 @@ the installed contract. Fix that app policy through its own review rather than
 compensating with card or field padding. Bounded AppSidebar instances use h-full
 inside the shell's constrained column; standalone sidebars may use viewport height.
 
+Use one LayoutSidebarProvider for AppLayout's primary and secondarySidebar
+slots. Named scopes infer each AppSidebar/LayoutSidebar panel ID. Keep
+desktop openPanels separate from mobilePanel, the single active undocked drawer;
+update controlled props from their matching callbacks. Controlled openPanels
+takes precedence over legacy primary open. Target essential supporting panels
+with SidebarTrigger panelId, and use navigationPanel for the ordinary navigation
+trigger/shortcut. The WorkspaceRegionsLayout recipe accepts primaryNavigation
+and sidebarPresentation="rail" for a SidebarNavigationRail beside contextual
+navigation, with grouped primary navigation as an alternative. It demonstrates
+named state without a router dependency or another UIProvider. Inset framing
+does not supply Page padding, and shell header slots take Header partials.
+An embedded provider with adaptTo="container" contains its drawer and backdrop.
+Use one explicit trigger for the inline full navigation beside the static left
+area rail. Choose the contextual AppSidebar/LayoutSidebar `collapsible`
+independently of the shell preset or sidebar skin: `icon` retains a second
+compact column, `offcanvas` hides that panel and leaves only the primary rail,
+and `none` keeps it expanded. Keep the static primary rail on its own `none`
+policy. Current examples default to `icon` with a preview selector, and
+standalone sidebars support the same choices. The copied
+WorkspaceRegionsLayout recipe exposes `contextualCollapsible` with an `icon`
+default; a secondarySidebar replacement owns its own mode. The app's
+area-selection callback opens the corresponding contextual panel.
+At narrow widths the inline cluster pans a minimum
+page canvas, with its area rail pinned, and preserves expansion state. Shared
+header, navigation and Page owners supply spacing. Dedicated area rails use the
+background surface and an adjacent divider; their width is independent of
+full-sidebar icon collapse.
+
+SidebarNavigationRail shares AppSidebar's header, beforeNavigation,
+afterNavigation and footer render slots. Header/footer stay pinned and
+before/after content scrolls. Searchable AppSidebar retains its search band in
+icon mode; its search button expands and focuses the field. Current
+matching chooses the most-specific href and exposes ancestor state separately
+to custom item renderers.
+
 For RTL, pair the native DOM direction with `DirectionProvider` from the same
 entrypoint. Native `dir` owns text flow and logical CSS geometry; the provider
 owns Base UI keyboard navigation and popup positioning. It does not set `dir`.

package/docs/consumer-skill/references/product-composition.md

@@ -0,0 +1,94 @@
+# Product composition capability map
+
+Compare the product's actual tasks with these public contracts before writing
+JSX. A product view may combine existing owners and custom domain content; a new
+wrapper name or a similar screenshot does not establish a missing capability.
+Inspect exact types through `inspect-component.mjs`, including the prop/slot you
+intend to use. The app owns authoritative data, permissions and persistence.
+
+## Product view responsibilities
+
+| Task and input contract | Existing owner and supported seam | App responsibility / reason to extend |
+| --- | --- | --- |
+| Product identity, facts and optional supporting regions | `ProductOverview` from `themelia-react-ui/features/products`: `details`, `options`, `variants`, `readiness` and named `slots` | Choose only relevant regions. Page still owns route identity/commands/gutters. Add a domain subject through a region slot when its relationships need a different structure. |
+| Product imagery within identity | `ProductOverview.details.media`; a standalone region can use `slots.mainTop` | There is no top-level `ProductOverview.media` prop. `details.media` also supports a media-only subject; no dummy facts are required. |
+| Color/size definitions and their values, independently from a table | `ProductOptionsMatrix`: `optionGroups`, editing/collapse state, awaited `onSaveEditingOption`, `onError`, cancellation, `renderValue`, `renderOptionActions` | Preserve IDs, reconcile accepted changes with sellable variants and historical orders, and apply validation/transport. Do not replace this editor with custom buttons just to rename/remove values. |
+| Definitions and variant rows in one coordinated subject | `ProductVariantsManager`: `optionGroups`, `variants`, editing/grouping/selection state, row/bulk callbacks and render seams; `showGroupBy={false}` drops the Group by control for a short list. Each option's summary row is its edit button; `renderOptionActions` adds explicit commands | Its convenience arrangement is a choice. Supply accepted rows and real commands; it does not invent combinations or warehouse policy. Use separate matrix/table owners when placement needs to differ. |
+| Compare sellable SKUs, prices, availability and status | `ProductVariantsBulkTable`: `visibleColumns`, `groupByOptionId`, `cellDisplay`, `renderCell`, row and bulk callbacks. `ProductVariantsTable` supplies a simpler variant list. | Pass meaningful values and stable IDs. For one stock figure the inventory cell may suffice; keep per-location reservations or shortages as a richer related subject. |
+| Inspect the selected SKU and its chosen options | `ProductVariantDetails`: `variant`, `metadata`, `media`, `renderMetadata`, `renderOption`, `footerSlot` and action callbacks | Keep its identity/actions while adding warehouse, costing or allocation evidence through an appropriate slot or sibling region. A custom fact does not require rebuilding the whole variant subject. |
+| Edit ordinary variant fields and selected option choices | `ProductVariantEditor`: controlled/default values, `optionFields`, `statusOptions`, `visibleFields`, per-field `errors`, app-owned `children` fields, awaited `onSubmit`, `submitting`, `onError`, cancel and footer. Inside `ActionDrawer`, share one `formId` and set `showHeader={false}` so the drawer owns the title and commands | App validates and returns accepted state. Its inventory field is one string; hide it with `visibleFields={{ inventory: false }}` and add per-warehouse balances or unit cost as `children`, which render inside the form before its commands. |
+| Upload new local product images | `MediaGallery` from `themelia-react-ui/base/media-gallery`: controlled `File[]`, `onValueChange`, MIME/extension acceptance, file limit, previews, removal and keyboard/drag sorting | Transfer and persistence remain app-owned. The first file is the cover. This is not a persisted URL-record gallery. |
+| Existing images attached to a product | `MediaResourceGallery` from `themelia-react-ui/features/media-library`: `items`, typed `accessors`, `primaryId`, primary/remove/reorder callbacks, `onAdd`, `readOnly` and `renderItem` | Adapt existing IDs/URLs; accept attachment changes through app state/transport. Do not fetch remote URLs merely to manufacture `File` objects. |
+| Search/select reusable assets or upload into an asset catalogue | `MediaLibrary` or `MediaLibraryDialog`: item accessors, controlled selection, fetch/upload handlers and picker callbacks | The app owns catalogue requests and attachment persistence. A simple local file field does not require this complete workflow. |
+
+For a simple single-SKU product, omit option-definition/combination work that the
+model does not have. For an optioned product, definitions, sellable combinations
+and a selected variant are different jobs; they need not be three custom cards.
+The [products template](../../../templates/products-template.tsx) demonstrates
+the larger public workflow. Its data and callbacks are examples, not your
+product's business rules. Deprecated standalone product region-card exports are
+compatibility APIs; use ProductOverview regions or the dedicated active owners.
+
+## Media identity and lifecycle
+
+Ask whether the input is a new browser `File[]` or already stored asset records.
+Both can belong to a product gallery. The finder query `product media gallery`
+therefore exposes both owners; `local product images` and `existing product
+images` narrow the decision. Inspect their value and callback types before
+choosing one.
+
+MediaResourceGallery's accessors can read the app's own keys, filenames, image
+URLs and alt text. It owns its frame, title and insets; use it as the region
+surface instead of nesting it inside another Card. Choose `layout="grid"` or `"list"` to expose primary and
+move commands; the compact `"field"` layout focuses on attachment/removal.
+`onReorder` proposes IDs and records in the next order; these move controls differ
+from MediaGallery's drag/keyboard file sorting. `onAdd`
+usually opens the app's existing MediaLibraryDialog flow. Read-only presentation
+needs no attachment commands.
+
+`renderItem` replaces a complete gallery item, including its default controls.
+Use it for an actual media-representation requirement, such as a supplied sprite
+crop, while retaining the gallery's collection ownership. Reuse public buttons
+and the render context's permitted primary/remove/move actions if the custom
+item remains editable. A regular image URL needs no custom tile implementation.
+
+## Existing owners and domain-specific structure
+
+The comparison above is not a rule to force every product into ProductOverview
+or to forbid custom components. Record the required task, candidate, inspected
+prop/callback/render seam and remaining mismatch. For example, a warehouse
+comparison may extend ProductVariantDetails.renderMetadata or sit beside it;
+option name/value editing already has ProductOptionsMatrix. Keep controls,
+focus, action states and ordinary text roles with their public owners.
+
+Return the actual save Promise from ProductOptionsMatrix/Manager's
+`onSaveEditingOption`. The owner keeps the editor pending, retains a rejected
+draft with retry feedback, and requests closure through
+`onEditingOptionIdChange` after acceptance or cancellation. `onError` can report
+the failure to the app. Do not close/reset before the Promise settles or swallow
+the rejection in a fire-and-forget wrapper.
+
+Stock reservation arithmetic, option-to-variant reconciliation, unique SKU
+validation, accepted prices and publication policy belong to the app. Changing
+today's catalogue never rewrites a purchased order's selected options or prices.
+A thumbnail, a file picker, an attached-asset gallery and a selected variant's
+media slot have different contracts even if they show the same photograph.
+
+## Executable product parts
+
+The [product parts recipes](../examples/product-parts.tsx) show real option IDs,
+save/cancel editing, a variant comparison with SKU/price/availability values,
+the coordinated manager and a details/editor flow that retains a failed draft
+until the caller returns accepted values. The option-only example edits local
+definitions; it deliberately does not claim to reconcile a complete catalogue.
+
+The [product media recipes](../examples/product-media.tsx) contrast caller-owned
+File[] with typed persisted-asset accessors and attachment callbacks.
+`MediaOnlyProductOverview` uses the actual details.media slot without dummy
+metadata. No recipe changes a URL record into a File or imports private source.
+
+Verify the chosen configuration: edit then cancel/save an option, preserve its
+ID, select a different variant, inspect its media/stock, reject and retry a
+variant save, change a cover/remove/reorder assets when supported, and inspect
+narrow/wide light/dark output. Source typechecks, a retrieved symbol and the
+presence of a callback do not prove those interactions or useful composition.