Headed toolbar drawers and reusable component configuration editors

[einari]

Problem

Studio already uses the shared toolbar and category folders to insert UI components. The proposed screen-editor improvement keeps that toolbar, but needs its expanded categories to be immediately understandable: a visible heading such as Layout, followed by clear buttons showing both an icon and a title.

Parent interaction design: Cratis/StudioIssues#394

The current ToolbarFolder already has grid/list modes, direction, animated expansion, Escape dismissal/focus return, and a title used for tooltip/accessibility. Its grid uses compact fixed-size cells and it does not render a visible drawer heading. List labels are useful existing behavior; this request adds the richer palette presentation without replacing it.

Source inspected: ToolbarFolder.tsx.

Requested behavior

Extend the existing toolbar folder/button family, or compose an additive variant, to support:

• A visible category header, e.g. Layout, with an accessible close affordance.
• Labeled tiles/buttons with a prominent icon and always-visible title, e.g. Stack, Row, Grid, Container. The title must not depend on a tooltip or hover.
• A clear, consistently spaced grid with room for titles and localization; do not force the labeled variant into the existing icon-only cell dimensions.
• Dragging an item from the drawer onto a consumer's surface while preserving the item's identity/payload and drag lifecycle.
• Normal button activation as the non-drag alternative; the consumer decides the insertion target and handles the drop.
• Predictable drag, dismissal, cancellation, focus-return, and overlay behavior. Opening or dismissing the drawer must not swallow a drag/drop or accidentally activate the item.
• Placement that respects viewport edges and toolbar orientation, including a small screen and a toolbar near an edge.

The drawer should look and behave like part of the existing Cratis toolbar, using existing tokens, stable parts, and styling conventions. Studio owns which categories/items are supplied and what a dropped item creates; Components must remain independent of Scene and Studio business concepts.

Compatibility and related work

Preserve existing icon-only grid and labeled-list behavior by default. Make the richer presentation opt-in. Reuse the toolbar drag-and-drop work from #56, the section/group work from #18, and the keyboard/accessibility direction in #328 and #353; this is not a request to rebuild those capabilities.

Add stable styling parts for the header, item content, icon, and label where existing parts are insufficient. Keep visible strings supplied/localizable through the normal public contracts.

Acceptance criteria

• A Storybook example opens a Layout drawer with Stack/Row/Grid/Container as labeled icon tiles.
• Both grid/list existing consumers retain their behavior and default appearance.
• Tile drag-and-drop delivers the exact item/payload to a sample surface; click/keyboard activation supports equivalent insertion.
• Header, close action, labels, focus states, and expanded state are accessible; Escape and focus restoration work.
• Mouse, touch/pointer, canceled drag, outside dismissal, and edge placement have appropriate interaction coverage.
• Long/localized titles fit without hiding the essential label.
• Public types, styling parts, documentation, and examples describe the additive variant and the separation between palette presentation and consumer-owned drop behavior.

The Layout drawer is the first consumer, but the same treatment should work for data, controls, and content categories.

Additional scope: reusable component configuration editors

Alongside the headed insertion drawer, support components offering their own configuration experience. A navigation component is the representative case: an ordered item collection with labels, icon selection, destination selection, add/remove, and reorder. Configuration can be constrained by the host when the component belongs to a reusable template.

Shared control responsibilities

• Provide reusable ordered-item editing and icon-picker controls, or extend existing suitable controls. Use labeled actions and keyboard/button alternatives to drag reordering.
• Support a component-specific editor supplied/registered through an extension seam. Prefer existing descriptors and control contracts; do not require every component to fit a flat generic property grid.
• Accept current values, stable item identities, allowed fields/operations, validation feedback, and change callbacks from the host. Show fixed/inherited items separately from configurable local items.
• Respect per-operation restrictions: adding items must not imply editing/removing fixed items or changing structure/styles. Exposed label/icon/destination fields may be narrowed independently.
• Icon choices use the configured icon catalog and stable identifiers, with accessible names and unavailable-icon feedback. Destination choices are host-supplied; these controls do not implement routing, discover application hierarchies, or execute domain actions.
• Keep the actual configuration controls fully readable when the host dims a component's inherited preview. Communicate locked/configurable state through text and accessible state, not opacity alone.
• Emit validated edit proposals through the host contract, preserving controlled-value, cancellation, focus and undo integration. The host remains responsible for authoritative permission checks, persistence and template resolution.
• Apply normal public styling/localization conventions and cover empty collections, fixed items, narrow panels, long labels, icon choice, reordering and validation errors.

Independent example and acceptance criteria

Use an independently authored Example Project fixture with a fixed Home item and configurable Page A / Page B items; all identifiers and data are synthetic. Demonstrate one host allowing all item operations and a second restricting icon editing or collection operations. Do not embed a consuming application's screens or domain data in examples.

• Reusable item editor and icon picker accept capabilities and values through public contracts.
• Fixed items cannot be changed; allowed local items can be added, labeled, assigned an icon/host target, removed and reordered.
• Restricted fields/operations are enforced in the control and callbacks do not leak unauthorized changes.
• Pointer drag, keyboard/button reorder, focus restoration and validation have interaction coverage.
• Existing toolbar variants retain their behavior; the original headed Layout drawer remains a deliverable.
• Documentation explains component-provided editors versus host-owned template policy, persistence and binding semantics.

Layout palette and property controls must remain extensible

The sample Stack/Row/Grid/Container tiles are illustrative, not an exhaustive built-in list. The drawer and configuration controls must accept the host's complete supported layout catalog and type-specific capabilities through public inputs.

• Preserve each supplied type's stable identity and payload through drag/drop and click/keyboard insertion. Do not normalize unknown supplied types to Stack or Grid.

• Support distinct property editors for host-defined ordered-flow, grid-placement and freeform-placement capabilities without embedding a layout engine or type registry in these shared controls.

• Allow the host to supply supported options, constraints, responsive settings and availability/validation explanations. Structural or template-owned restrictions remain host policy.

• Adding a layout type through supported host descriptors must not require editing a hardcoded list inside the drawer.

• An independently authored example supplies an additional synthetic layout type and renders its labeled tile and configuration controls without modifying drawer internals.

• The correct identity/payload is preserved through all insertion paths; unsupported operations remain unavailable with an explanation.

• Existing variants, localized labels, focus behavior and narrow-drawer layouts remain compatible as the catalog grows.

Icon chooser implementation dependency

Use #359 for the reusable icon property control: a popout with search, categories and provider-aware choices, with centered glyphs and visible centered names inside bordered tiles. The initial small permanently expanded grid is only an earlier illustration and is superseded by that interaction.

Configuration editors receive a qualified selected icon reference and host-supplied effective catalog/constraints. Reuse the shared picker rather than implementing another icon browser; preserve field restrictions and controlled callbacks. Icon-library package resolution stays outside these generic controls.

[einari]

Implementation plan

Orchestrated as part of the screen-editor programme. Wave 1, runs in parallel with #359. Consumed by Cratis/StudioIssues#394.

Phase A — headed drawer (start immediately)

1. Audit Source/Toolbar/ToolbarFolder.tsx, ToolbarButton, ToolbarDragContext, ToolbarFolderContext, ToolbarSection/ToolbarGroup (Add support for sections in the toolbar #18), drag work (Add support for drag&drop elements from the Toolbar onto a surface #56) and keyboard work (Make toolbar and filter controls keyboard- and screen-reader-accessible #328/Make toolbars a single Tab stop by default in the next major #353). Extend, don't fork.
2. Add an opt-in presentation to ToolbarFolder (e.g. presentation="drawer" or a composed ToolbarDrawer built from the same context) with:
   • Visible header (title) + accessible close button; aria-expanded/aria-controls on the trigger; Escape and close return focus to the trigger.
   • Labeled tiles: prominent icon + always-visible title; own grid dimensions (not the icon-only cell size), wrapping/ellipsis-with-full-title handling for long/localised labels.
   • Items are data-driven: accept a catalogue items: { id, title, icon, payload, disabled?, disabledReason? }[] (contract C4) and children for composition. Never hardcode Stack/Row/Grid/Container; never normalise unknown items.
   • Drag: use the existing toolbar drag context/HTML5 drag so the exact payload arrives at the consumer's drop handler; drawer must not close mid-drag in a way that cancels the drag; cancelled drags restore state; activation via click/Enter/Space calls onActivate(item) — consumer decides the insertion target.
   • Placement respects toolbar orientation and viewport edges (flip/shift, max-height + scroll).
   • New stable styling parts: drawerHeader, drawerTitle, drawerClose, tile, tileIcon, tileLabel (follow existing parts naming).
3. Existing icon-only grid and list modes keep identical defaults (add regression specs).
4. Story: Layout drawer with Stack/Row/Grid/Container + an extra synthetic "Masonry" type, dropping onto a sample surface that logs the payload; click insertion path; edge-placement story.

Phase B — reusable configuration editors

5. OrderedItemEditor (generic, controlled): items with stable ids, fixedItems shown separately and locked, capabilities { add, remove, reorder, fields: { label?, icon?, destination?, … } }, per-field editors, validation messages per item, onChange(proposal) emitting validated proposals only. Reorder via pointer drag and move-up/down buttons + keyboard. Locked/configurable state expressed by text + aria, not opacity.
6. Extension seam for component-specific editors: a small registry/context (e.g. ConfigurationEditorRegistry keyed by host-defined component type) that hosts use to look up a specialised editor, falling back to generic property controls. Keep it generic — no Scene types.
7. Destination field: host-supplied options ({ id, label, group? }[]), no routing.
8. Icon field: use the IconPicker from Searchable categorized icon-picker popout with centered labeled tiles #359. Searchable categorized icon-picker popout with centered labeled tiles #359 is being built in parallel; implement the icon field behind a narrow prop (renderIconField / iconCatalog) now and finish by wiring IconPicker as the default once Searchable categorized icon-picker popout with centered labeled tiles #359 is merged into main — the orchestrator will tell you to rebase. If Searchable categorized icon-picker popout with centered labeled tiles #359 has merged before you reach this step, rebase onto main and use it directly.
9. Layout property controls: generic, host-described controls for flow (gap, padding, alignment, grow), grid placement (columns, span) and freeform placement, driven by host descriptors (no layout engine inside Components).
10. Stories: "Example Project" fixture — fixed Home, configurable Page A/B; host A allows everything, host B restricts icon edits and collection ops. Synthetic data only.
11. Specs: fixed items immutable, restricted ops/fields never emitted, reorder by drag and by keyboard, validation, focus restoration, existing toolbar variants unchanged.
12. Docs: drawer variant + separation of palette presentation and consumer-owned drop; component-provided editors vs host-owned template policy.

[github-actions]

Closed by release v4.25.0.