Skip to main content
View as Markdown

Search Components

Where tables declare what is searchable and engines declare how a query runs (see search-overview), components are where search appears on the page. Sovrium provides five complementary pieces: a searchInput that drives a query, a list that renders results, a pageSearch that indexes static page content, a command palette for keyboard-driven navigation, and toolbar search built into data components.

Component Purpose
searchInput Standalone search box that drives another component via dataSource.bindTo.
list Search-first result display with item templates, highlighting, and pagination.
pageSearch Site-wide static search over public page content (build/start-time index).
command Command palette (⌘K-style) for grouped, keyboard-driven actions.
toolbar search In-component search bar on data-table, kanban, calendar, etc.

searchInput

A standalone search box. On its own it renders an accessible input; bound to a data source it becomes the query driver for a sibling component. Pair it with a list (or data-table) whose data source sets bindTo to the input's id.

Property Description
id Identifier other components reference via dataSource.bindTo.
visibility Standard visibility controls (shared across components).
i18n Standard internationalization fields (translatable label/placeholder). 
components:
  # 1. The input drives the query
  - type: searchInput
    id: product-query

  # 2. The list consumes it via bindTo
  - type: list
    dataSource:
      table: products
      mode: search
      searchFields: [name, description]
      searchEngine: hybrid
      debounceMs: 300
      bindTo: product-query
    listDisplay:
      itemTemplate:
        title: '$record.name'
        subtitle: '$record.description'
      highlight: true

list — result display

The list component is designed as a search-first display: the natural companion for searchInput. It renders each record through an item template with optional highlighting, dividers, and load-more pagination.

Property Description
itemTemplate.title Primary text via a $record.* reference (e.g. $record.name).
itemTemplate.subtitle Secondary text (e.g. $record.description).
itemTemplate.image Image URL (e.g. $record.thumbnail).
itemTemplate.badge Badge text (e.g. $record.category).
itemTemplate.metadata Array of { field, format } shown in the item footer (currency, relative-date, badge, text, short-date).
emptyMessage Message shown when no results match.
loadMore button (Load More button) or infinite (load on scroll).
highlight Boolean. Highlight matched search terms in item text (default false).
divider Boolean. Show visual dividers between items (default false).
maxItems Maximum number of items to display (integer ≥ 1). 
- type: list
  dataSource:
    table: products
    mode: search
    searchFields: [name, description]
    bindTo: product-query
  listDisplay:
    itemTemplate:
      title: '$record.name'
      subtitle: '$record.description'
      image: '$record.thumbnail'
      badge: '$record.category'
      metadata:
        - field: price
          format: currency
    emptyMessage: No products found
    loadMore: infinite
    highlight: true
    divider: true
    maxItems: 50

pageSearch — static page index

A site-wide search component that indexes public pages (access missing or access: 'all') at sovrium build time and sovrium start boot. The index is a JSON file plus a tiny client runtime under <outputDir>/sovrium-search/, served by the public-dir route. This is a different layer from record search — it searches page content, not table rows.

Property Description
placeholder Placeholder text shown in the search input.
maxResults Maximum number of results to display (positive integer).
visibility Standard visibility controls.
i18n Standard internationalization fields. 
pages:
  - id: home
    name: home
    path: /
    components:
      - type: pageSearch
        placeholder: Search the site...
        maxResults: 10

command — command palette

A ⌘K-style command palette for keyboard-driven navigation and actions. Commands are organized into groups, each surfacing searchable entries the user filters by typing.

Property Description
commandGroups Array (≥ 1) of grouped commands shown in the palette.
visibility Standard visibility controls.
i18n Standard internationalization fields. 
- type: command
  commandGroups:
    - heading: Navigation
      commands:
        - label: Go to Dashboard
          href: /dashboard
        - label: Go to Settings
          href: /settings
    - heading: Actions
      commands:
        - label: New Product
          href: /products/new

Data components expose an in-component search bar through their toolbar. On a data-table, set toolbar.search: true to render a global search input over the bound rows — a quick filter without a separate searchInput.

Toolbar flag Description
search Show the global search input.
filters Show the filter builder.
sort Show the sort builder. 
- type: data-table
  dataSource:
    table: orders
    mode: search
    searchFields: [customer, reference]
  toolbar:
    search: true
    filters: true
    sort: true

Kanban and calendar components share a search configuration for their own in-component search bar via the same pattern.

Highlighting and debounce

  • Highlighting — set highlight: true on list (listDisplay.highlight) to wrap matched terms in result text. Off by default.
  • Debounce — set debounceMs on the data source (e.g. 300) so the query fires only after the user pauses typing, preventing a request per keystroke.

These work together: a searchInput emits keystrokes, the bound data source debounces and queries, and the list highlights matches in the rendered results.