Sightmap Components: Selectors, Children, and References

A component is a named DOM subtree, identified by one or more CSS selectors. Names replace the generic accessibility role in enriched snapshots, so an agent reading the page sees DepartureDatePicker instead of group.

- name: DepartureDatePicker
  selector: '[data-picker="departure"]'
  source: src/components/DatePicker.tsx
  children:
    - name: date-input
      selector: input
    - name: day
      selector: '[role="gridcell"]'

name and selector are required. See Schema reference for the full field list, including description, source, memory, and properties.

Selectors

selector accepts a single CSS selector string or an array of strings:

# Single selector
- name: SubmitButton
  selector: 'button[type="submit"]'

# Array — alternatives tried in order, first match wins
- name: OriginAirportPicker
  selector:
    - '[data-picker="origin"]'
    - '#origin-combobox'

Use the array form to keep one name across UI variants, such as a redesigned page, a feature flag, or a third-party widget. Sightmap tries each selector in order and uses the first one that matches one or more elements. If a selector matches multiple elements, all matches get the name. Selectors are not required to be unique.

The `data-component` convention

The recommended pattern is to render a data-component="<Name>" attribute on the root element of each named component, then select on that attribute:

<nav data-component="Navigation">…</nav>

- name: Navigation
  selector: 'nav[data-component="Navigation"]'

This keeps the sightmap independent of class names, CSS modules, and styling changes. It adds one searchable attribute to each named component. The spec accepts any CSS selector; data-component is the recommended convention.

Children are scoped

Selectors inside children are evaluated within their parent’s matched subtree instead of against the whole document. Two card components can therefore each contain a child selected by button.primary without colliding.

- name: SearchCard
  selector: '[data-component="SearchCard"]'
  children:
    - name: submit
      selector: 'button.primary'   # only inside SearchCard's subtree

- name: BookingCard
  selector: '[data-component="BookingCard"]'
  children:
    - name: submit
      selector: 'button.primary'   # only inside BookingCard's subtree

Scoping inside views vs at file level

Components at the file root are global and match on every view. Components nested inside a view apply only to that view. Both forms are additive, except that a view-scoped $ref subsumes a global component with the same name. See Views for the full rule.

Quote attribute selectors so YAML parses them as strings: selector: '[data-component="X"]'. Unquoted, the brackets are read as a YAML flow sequence and the entry fails validation.

Referencing shared components

When a component such as a site header, persistent footer, or chat widget appears across views, a components: array can contain a reference object instead of another inline definition:

- $ref: SiteHeader

Before matching, the reference expands inline to a deep copy of the named component. Any $ref entries in its children: expand recursively. Names resolve against a registry built from the root-level components: arrays of all loaded files; nested children and view-scoped definitions are not addressable. For duplicate registry names, the first definition in source-file path order wins. Implementations SHOULD emit a merge-collision-component warning.

.sightmap/components.yaml

version: 1

components:
  - name: SiteHeader
    selector: '#site-header'
    children:
      - name: SearchBox
        selector: 'form#header-search'

.sightmap/views/plp.yaml

version: 1

views:
  - name: PLP
    route: /b/**
    components:
      - $ref: SiteHeader     # attests SiteHeader is expected on this view
      - name: ProductGrid    # view-specific
        selector: '[data-component="ProductGrid"]'

Use $ref for reuse and attestation:

Reuse. Update the header’s selector or memory entries in one definition; every referencing view receives the change.
Attestation. A view’s components: lists what it expects to contain. Drift-detection tools can report an attested component that matches zero elements separately from a component the view never referenced.

The conformance rules:

A $ref entry MUST contain exactly one key ($ref); overrides are not allowed in v1.
A $ref to a name that isn’t in the registry is a ref-unresolved error.
A self-referential chain (A → B → A) is a ref-circular error.
When a view-scoped $ref and a file-root global share a name, the view-scoped expansion subsumes the global for that view — implementations MUST NOT produce two matches.

See the schema reference for the full statement.

Properties

A component can declare properties: — named values pulled from its matched element and shown alongside the name in enriched snapshots, so an agent sees not just what matched but what state it is in:

- name: DateFilterButton
  selector: '[data-testid="date-filter-button"]'
  properties:
    - name: label
      extract: text          # → [DateFilterButton label="This Weekend"]
- name: ProductCard
  selector: '[data-testid="product-pod"]'
  properties:
    - name: price
      extract: '[data-testid="price"]'   # a CSS sub-selector, read from the child
      transform: first_dollar
    - name: sold_out
      extract: 'exists:[aria-label="Sold Out"]'   # boolean flag; omitted when absent

Each property has a name (the annotation key), an extract directive (text, inner_text, text_only, inner_html, attr=NAME, exists:SEL, or a CSS sub-selector), and an optional transform (first_word, last_word, first_number, first_dollar, number, slug). Extraction runs on the exact matched element, from the live DOM at snapshot time — offline tools omit the values. A value that comes back empty (or an exists:/sub-selector that finds nothing) is dropped silently. See the schema reference and SEP-0003.

Dependencies

A component can list supplementary files whose changes should prompt re-curation, such as style modules, hooks, or shared utilities:

- name: DepartureDatePicker
  selector: '[data-picker="departure"]'
  source: src/components/DatePicker.tsx
  dependencies:
    - src/components/DatePicker.module.css

dependencies is curation-time metadata. Each string is a project-root-anchored minimatch glob; prefix it with ! to negate it. Runtime consumers MUST NOT add page-load cost based on this field. See the schema reference for usage rules.

Requests for API endpoints. Memory for the freeform notes you can attach to any component.

​Selectors

​The data-component convention

​Children are scoped

​Scoping inside views vs at file level

​Referencing shared components

​Properties

​Dependencies

​Next

Selectors

The `data-component` convention

Children are scoped

Scoping inside views vs at file level

Referencing shared components

Properties

Dependencies

Next