Skip to content

Component picker: highlight a component on screen, resolve what it is and expose its editable presentation properties #478

Open

Description

@einari

Problem

Some features let a user point at a part of the screen and say something about it: an inspector, a guided tour editor, or in-app feedback ("this column header is confusing", "this button should be called Save draft"). Each of them needs the same primitive: pick a component, highlight it, and know what it is.

Cratis Components has none of this today:

  • No picker, inspector or highlight overlay exists.
  • About 878 data-cratis-part attributes mark the parts inside components (header, title, close, root). Nothing marks a component root with its component name.
  • Nothing lists which of a component's props are presentational and safe to suggest changes to (label, placeholder, visibility, order, width, variant).

Proposal

  1. Component identity markers. Every public component renders data-cratis-component="<Name>" on its root, and optionally data-cratis-component-id when the consumer passes an id or a name (form fields already have one).
  2. A presentation-property descriptor per component: a static, typed list of the props that change presentation, with type and allowed values. Examples: label: string, hidden: boolean, variant: 'primary' | 'secondary', column order: number. Behavior and data props are left out.
  3. ComponentPicker (an overlay, plus a useComponentPicker() hook):
    • Starts and stops imperatively.
    • Highlights the component root under the pointer, or under keyboard focus, which moves between components with arrow keys.
    • Shows the component name in a tooltip, and confirms with click or Enter (Escape cancels).
    • Returns a PickedComponent that holds:
      • { component, id, part, element, rect }
      • its presentationProperties with current values, read from the rendered props through a registry, not from the DOM
      • ancestors, the list of enclosing components, so a user can move to the parent or child
    • Honors the dialog stack and overlay layering (renderer/dialogStack.ts, overlayEnvironment.ts), so picking works inside open dialogs.
    • Lets the host pass a resolve(element) callback to add context from outside the library. Examples are the slice markers from Expose the running application's context (module, feature, slice, screen, dialogs) from the Arc root Arc#3604 or a host's screen identity.
  4. ComponentHighlight: a passive highlight of a given element or PickedComponent, used to show what a piece of feedback is about after picking.
  5. A property editor for a PickedComponent, built from its descriptor (text, toggle, select and number inputs). It returns the proposed changes as { property, from, to } without applying them. A host can preview them live by applying them through the same registry, and revert them afterwards.

Acceptance criteria

  • Every public component renders data-cratis-component on its root. A conformance spec fails when a new component lacks it.
  • The picker highlights, names and returns components with the mouse and with the keyboard, including inside open dialogs.
  • PickedComponent includes presentation properties with their current values, and its ancestors.
  • The property editor returns proposed changes without changing the app, and the optional preview reverts cleanly.
  • The host resolve callback can add context.
  • Storybook stories, specs, accessibility checks and documentation are added.

Related

Status

State: Open, partly delivered (narrowed by triage 2026-11-15)
Delivered: Picker, hook, highlight and property editor (#479), plus markers for CommandForm fields (#494), Toolbar (#495) and filter roots (#498).
Remaining: Add data-cratis-component root markers to the 27 components still pending in Source/for_component_identity/componentMarkerCoverage.ts, and complete presentation-descriptor coverage (today only seven component types have descriptors).

Activity

  1. self-assigned this
    on Nov 3, 2026
  2. woksin commented on Nov 3, 2026

    @woksin
    Contributor

    We started work on this and have paused it. The code so far is on branch components-478-filter-markers (commit 021ac2e), in draft pull request #496. It is not merged and not part of any release.

    • What it does: marks CheckboxListFilter, ColumnFilterMenu, FilterPanel and RangeHistogramFilter with data-cratis-component on their root element, so the component picker can identify them, and lowers the pending-marker ceiling from 31 to 27. Two earlier slices, the CommandForm fields (Mark the CommandForm fields for the component picker #494) and the Toolbar components (Mark the Toolbar components for the component picker #495), are already released.
    • State: implemented with specs; review passed and the pull request checks were green.
    • What remains: 27 public components are still pending in componentMarkerCoverage.ts: Canvas, editors and display components, Chat, and AutoCommandForm.

    Nobody on our side is working on it now. Feel free to take it over, build on it or discard it.

  3. assigned and unassigned on Nov 3, 2026
  4. self-assigned this
    on Nov 21, 2026
  5. woksin commented on Nov 21, 2026

    @woksin
    Contributor

    First marker batch delivered in #569, released in v4.55.1: 13 more components now carry component markers, so 14 entries remain pending (GlyphMenu and ChatSidebarForObservableQueries were deferred). Remaining work: the other 14 markers and the presentation-descriptor coverage, delivered in further batches.

  6. woksin commented on Nov 21, 2026

    @woksin
    Contributor

    Second marker batch released in v4.56.0 (#571): Canvas, CanvasMinimap, Toaster, ObjectContentEditor, ObjectNavigationalBar, PivotViewer, SchemaEditor and EventsView now carry component markers. AutoCommandForm, CanvasOverlay and ConfigurationEditor are recorded as exempt (no root element of their own), and ChatSidebarForObservableQueries delegates to ChatSidebar. Two entries remain pending, Region and GlyphMenu, because neither has a single existing root element. The presentation-descriptor coverage is still open.

  7. woksin commented on Nov 22, 2026

    @woksin
    Contributor

    Third batch released in v4.57.0 (#573): Badge, Chip, Avatar, Tag, Skeleton and ProgressSpinner now publish presentation descriptors through useComponentPresentation, and a spec keeps the descriptor count from regressing.

    Still open:

    • Region and GlyphMenu identity markers (neither has a single root element).
    • Descriptors for Breadcrumbs, FormElement, Message and Toolbar primitives.
    • Delegated primitives (ProgressBar, Surface, Tooltip, number inputs, Checkbox, Switch, Radio, Tabs, ToggleGroup, ComboBox, DatePickerInput), which need the registry owner and renderer slot traced first.
    • CommandForm field wrappers, where command-bound value and validation state must stay out of the presentation descriptor.
    • Data and composite surfaces (tables, navigation, editors), which need a decision on static presentation versus model-driven content.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions