Repository navigation
Description
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-partattributes 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
- Component identity markers. Every public component renders
data-cratis-component="<Name>"on its root, and optionallydata-cratis-component-idwhen the consumer passes anidor aname(form fields already have one). - 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', columnorder: number. Behavior and data props are left out. ComponentPicker(an overlay, plus auseComponentPicker()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
PickedComponentthat holds:{ component, id, part, element, rect }- its
presentationPropertieswith 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.
ComponentHighlight: a passive highlight of a given element orPickedComponent, used to show what a piece of feedback is about after picking.- 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-componenton 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.
-
PickedComponentincludes 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
resolvecallback can add context. - Storybook stories, specs, accessibility checks and documentation are added.
Related
- Expose the running application's context (module, feature, slice, screen, dialogs) from the Arc root Arc#3604: application context (optional slice markers resolvable from the DOM)
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
woksin commentedon Nov 3, 2026
We started work on this and have paused it. The code so far is on branch
components-478-filter-markers(commit021ac2e), in draft pull request #496. It is not merged and not part of any release.CheckboxListFilter,ColumnFilterMenu,FilterPanelandRangeHistogramFilterwithdata-cratis-componenton 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.componentMarkerCoverage.ts: Canvas, editors and display components, Chat, andAutoCommandForm.Nobody on our side is working on it now. Feel free to take it over, build on it or discard it.
woksin commentedon Nov 21, 2026
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.
woksin commentedon Nov 21, 2026
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.
woksin commentedon Nov 22, 2026
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: