Searchable categorized icon-picker popout with centered labeled tiles

[einari]

Outcome

Provide a reusable icon chooser that opens as a popout from an icon property control. Replace a permanently expanded small icon grid with a searchable, categorized catalog.

Interaction and appearance

• The closed control shows the selected icon and its name.
• Opening shows a clear title, search field, categories and a close action. Browse compact category groups with Show all, or filter to a category.
• Each selectable tile has a visible border, an icon centered horizontally and vertically in a consistent icon area, and its readable name centered beneath it. Selection/focus are distinct; neither relies on color alone.
• Search names and supplied aliases/tags, case-insensitively. State the active category/library filter; support clearing search and show a useful no-results state.
• When several libraries are supplied, allow browsing/filtering by library and identify the provider so duplicate icon names are distinguishable.
• Selecting updates the controlled value, closes the popout and returns focus to its trigger. Escape, close and outside dismissal cancel without changing the current selection.
• Place the popout relative to its trigger, flipping/shifting at viewport edges. A narrow viewport can use a contained sheet; do not clip it inside an inspector or obscure required controls.
• Support keyboard opening, search, category navigation, tile selection, dismissal and focus return, plus touch targets and long/localized labels.

Public contract and boundaries

Receive the effective icon catalog from the host: qualified stable identity, display name, category/tags, library provenance, optional variants and renderable previews. Emit the selected qualified identity, not raw SVG, a CSS class, a display name or an array index. Do not hardcode a single icon provider or resolve application package dependencies in the picker.

Expose controlled selected value, allowed choices, read-only/disabled state, pending/error/empty catalog state, validation feedback and callbacks. Component-specific configuration editors can reuse it. A template may expose or restrict an icon property; the host enforces the effective exposure and supplies the allowed catalog.

Large libraries need efficient browsing/search and lazy preview rendering. Preserve accessible navigation and stable selection during incremental catalog loading. Missing/deprecated selections remain visible with diagnostics; never silently replace an icon with a same-named entry from another provider.

Display provider/attribution information when supplied by the catalog. Styling, localization and icon rendering use public extension contracts. This issue does not require an Images tab or a general image asset browser.

Acceptance criteria

• Bordered tiles have centered icons and always-visible centered names.
• Popout search, categories, Show all, provider filtering and selection work with a host-supplied catalog.
• Duplicate names across providers preserve distinct qualified identities.
• Keyboard/touch, edge placement, outside/Escape cancellation and focus return are covered.
• Loading, empty/no-results, missing selected icon and provider failure states are demonstrated.
• Read-only/restricted fields cannot emit unauthorized changes.
• An independently authored example uses synthetic icon libraries and identifiers, with no consuming-product data.
• Public documentation covers host catalog adapters, controlled values, accessibility and styling.
• The reusable configuration editors in Headed toolbar drawers and reusable component configuration editors #358 use this picker rather than maintaining another icon grid.

[einari]

Implementation plan

Orchestrated as part of the screen-editor programme. Wave 1 — no upstream dependencies. Consumed by #358 (configuration editors) and Cratis/StudioIssues#397.

Approach

1. Audit Source/Common/Icon*, CratisComponentsProvider icon registration, existing popover/overlay primitives (Dropdown, Dialogs, Toolbar panels) and the styling-parts / localisation conventions. Reuse the existing overlay/positioning and focus-management utilities rather than adding a new positioning library.
2. Public contract (new folder, e.g. Source/IconPicker/, exported from the package index and its own entry point like other components):
   • IconPickerLibrary { id; name; version?; attribution? }
   • IconPickerEntry { library; key; variant?; name; categories: string[]; tags?: string[]; renderPreview: () => ReactNode }
   • IconPickerValue { library; key; variant? } — identical field names to the canonical Scene icon reference (orchestrator contract C1/C2).
   • IconPickerCatalog { libraries; icons; status?: 'ready' | 'loading' | 'error'; error? }
   • IconPicker props: value, onChange(value), catalog, allowed? (predicate or list of values), readOnly, disabled, invalid/validationMessage, strings (localisable labels), placement?, plus the standard pt/parts styling API.
3. Closed trigger: selected glyph + name; missing selection (value not in catalog) shows the raw qualified identity with a warning state — never substitutes a same-named icon from another library.
4. Popout: title, search (name + tags, case-insensitive), category chips with Show all and compact per-category groups, library filter + provider label when >1 library, clear search, no-results / loading / empty / error states, close button. Tiles: visible border, fixed icon area with centered glyph, centered always-visible name, distinct selected and focus states not relying on colour alone.
5. Behaviour: select → onChange + close + focus back to trigger; Escape / close / outside click → cancel, no change. Viewport-aware placement (flip/shift); narrow viewport → contained sheet; render in a portal so inspectors do not clip it. Roving-focus grid keyboard navigation, touch target sizes.
6. Performance: lazy preview rendering (render only visible tiles via IntersectionObserver or windowing) and memoised search index; stable selection during incremental catalog loading.
7. Restrictions: readOnly/disabled never emit; entries outside allowed are not selectable (shown disabled with reason or hidden — document choice).
8. Stories: synthetic libraries "Example Glyphs" and "Sample Symbols" with an intentional duplicate name (e.g. both define home), loading/empty/error/missing-selection stories, narrow viewport story, read-only story.
9. Specs: search/filter/category, duplicate-name identity, select/cancel/focus return, keyboard navigation, read-only no-emit, missing selection.
10. Docs: Documentation/ page covering host catalog adapters, controlled value, accessibility, styling parts.

Out of scope

Package resolution, Scene types, Studio data. #358 consumes this picker after it merges.

[github-actions]

Closed by release v4.24.0.