search

Published content search with static fallback

Install

docsloth component add @docsloth/search@1.0.0

Live package: sha256:17cff85734c8002817e16d0b9d54ada0d5242f55eea5cb1d3cfa06c2ff91ae4a with 2 file digest(s); the catalog entry is generated from the built package, not a placeholder.

Props

The prop schema is normative in packages/contracts/component-props/search.schema.json.

Example props generated from this schema:

{
  "title": "example-title",
  "index_ref": "example-index_ref",
  "mode": "static",
  "placeholder": "example-placeholder",
  "max_results": 1,
  "resource": {
    "resource_id": "00000000-0000-4000-8000-000000000000",
    "operation": "example-operation",
    "environment": "test"
  }
}

Required props: index_ref, mode, placeholder, max_results.

Example

Example document IR (the block the renderer consumes):

{
  "type": "search",
  "props": {
    "title": "example-title",
    "index_ref": "example-index_ref",
    "mode": "static",
    "placeholder": "example-placeholder",
    "max_results": 1,
    "resource": {
      "resource_id": "00000000-0000-4000-8000-000000000000",
      "operation": "example-operation",
      "environment": "test"
    }
  }
}

Renderer HTML (entities decoded and wrapped for display):

<section class="ds-block ds-search" data-component="search" aria-labelledby="b-title">
<h3 class="ds-block-title" id="b-title">example-title</h3>
<p>example-placeholder</p>
<dl class="ds-facts">
<div>
<dt>Index</dt>
<dd>
<code>example-index_ref</code>
</dd>
</div>
<div>
<dt>Mode</dt>
<dd>static</dd>
</div>
<div>
<dt>Results per search</dt>
<dd>1</dd>
</div>
<div>
<dt>Runs</dt>
<dd>
<code>example-operation</code> in the test environment</dd>
</div>
</dl>
<p class="ds-live-note" role="note">Interactive search requires an authorized index supplied by the publication host. No search index is attached to this static view.</p>
</section>

Preview (interface-only; the markup above is the same output):

The renderer resolves this component as a native block; the preview above is its real HTML output, and Markdown parity for native blocks is covered by the renderer test suite.

Specification

Generated from packages/contracts/component-specs/search.md.

Contract

Production props are normative in ../contracts/component-props/search.schema.json. The corresponding component-fixtures manifest is only a minimal protocol fixture; use the production props schema when building the published package. The packaged artifact ships exactly its generated component-package.json manifest plus props.schema.json (the production props schema, copied byte-for-byte) and spec.md (this spec, copied byte-for-byte); it contains no executable payload, fallback implementation, Storybook, test suite, SSR harness or README. Rendering behavior and the acceptance cases below belong to the renderer and the repository tests, not to the package. Installation pins the package version and the digest of every shipped byte.

Intended behavior

Version/audience filtered search with keyboard shortcuts and no-result feedback.

Failure and fallback

Managed unavailable falls back to public static index only, never mixed private cache.

Required acceptance cases

Empty/long/Unicode queries safe and match highlighted text. Also test empty data, loading, denied access, browser without JS, mobile 360px, keyboard navigation, dark mode and an explicit constrained agent tool call. The server independently authorizes capability requests; a package manifest cannot grant authority.

Data and maintenance

Data bindings resolve from a specific publication/release vector and permitted fact/evidence graph. Configuration edits create versioned component patches. Update invalidation uses dependency IDs, never indiscriminate whole-page regeneration. Human-owned props survive automatic updates unless invalidated with an explicit conflict. Missing optional resources leave an honest inert/readable fallback, not a broken page or fake success.

Cost and tools

Pure/local interaction must never invoke a model by accident. Any model, remote query or executor call must reserve approved budget before dispatch. Public visitors do not inherit owner resources. The component may call only named tools in its signed manifest with valid typed inputs. A cancelled job stops polling and closes resources. No component gets platform administration, raw credentials or an unlimited execution loop.

Current React host binding

ComponentContentProvider.searchIndexes is a readonly map keyed by production index_ref. Each available record declares visibility: public | authorized and readonly documents with id, title, optional text, and optional href. The host supplies only bytes and destinations already authorized for this audience and release, and replaces immutable snapshots when they change. These display types do not implement access control. Restricted records contain only access: restricted; no private index metadata is rendered.

Static mode performs literal, case-insensitive Unicode text search locally after form submission. Every whitespace-separated term must match; title matches rank first, ties retain index order, and max_results bounds displayed matches. Results use escaped text/highlights and validated navigation links. Queries are bounded to 256 UTF-16 units and 20 distinct terms. Indexes accept up to 1,000 unique documents, 500 units per title, 20,000 per body, 4,096 per URL and 2,000,000 total title/body units; invalid or oversized indexes show unavailable instead of silently truncating.

Initial results and a native disclosure containing every document title/link render without JavaScript. Filtering enables after hydration; Enter submits, Escape clears, and / from a focused result focuses the query input. Changing release or index resets the query. No browser storage, remote fetch, resource execution, embedding or model call occurs. Managed/external modes are explicitly unconnected and fall back only to a host record marked public; an authorized-only index cannot become their fallback. Live services, host-side ACLs and budgeted tool dispatch remain separate integrations.

Package manifest

Protocol fixture: packages/contracts/component-fixtures/search.json.

Sources