metrics

Display authorized aggregate metrics

Install

docsloth component add @docsloth/metrics@1.0.0

Live package: sha256:689a423f12cd771fdaf04d7594cc40c7d1637af313bb32b4d64830a20f2cbc35 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/metrics.schema.json.

Example props generated from this schema:

{
  "title": "example-title",
  "resource": {
    "resource_id": "00000000-0000-4000-8000-000000000000",
    "operation": "example-operation",
    "environment": "test"
  },
  "query_id": "example-query_id",
  "display": "number",
  "time_range": "24h"
}

Required props: resource, query_id, display, time_range.

Example

Example document IR (the block the renderer consumes):

{
  "type": "metrics",
  "props": {
    "title": "example-title",
    "resource": {
      "resource_id": "00000000-0000-4000-8000-000000000000",
      "operation": "example-operation",
      "environment": "test"
    },
    "query_id": "example-query_id",
    "display": "number",
    "time_range": "24h"
  }
}

Renderer HTML (entities decoded and wrapped for display):

<section class="ds-block ds-metrics" data-component="metrics" aria-labelledby="b-title">
<h3 class="ds-block-title" id="b-title">example-title</h3>
<dl class="ds-facts">
<div>
<dt>Metric query</dt>
<dd>
<code>example-query_id</code>
</dd>
</div>
<div>
<dt>Display</dt>
<dd>number</dd>
</div>
<div>
<dt>Time range</dt>
<dd>24h</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">Metric values are loaded on the live documentation site.</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/metrics.md.

Contract

Production props are normative in ../contracts/component-props/metrics.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

Authorized aggregates with explicit units, time bounds and coverage.

Failure and fallback

Partial data label retained; low-count privacy suppression.

Required acceptance cases

No unjustified conversion attribution or individual behavior leak. 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.

React aggregate binding

The host provides ComponentContentProvider.metricQueries, keyed with metricQueryKey(resource, query_id, time_range) from @docsloth/official-components/host. The resource ID, operation, environment, query and time range must all match. An available record also names the provider release ID, metric label, units, exact UTC window bounds, complete/partial coverage, privacy minimum count (at least five), and up to 2,000 timestamped aggregate buckets. Use { at, suppressed: true } for a suppressed bucket; otherwise supply { at, value, count }. Window durations are exactly 24 hours, seven days or thirty days, with an exclusive end.

The server must authorize the audience/resource/query and suppress private values **before** delivery. The renderer additionally hides low-count values, but client-side hiding cannot protect bytes already delivered to a browser. No individual identifiers, raw events or suppressed values belong in this binding. Differential privacy and protection against differencing across multiple queries remain server responsibilities. A resource prop or record is not an authorization grant.

Number mode shows the latest bucket, including an explicit suppressed state. Line and bar modes include a complete accessible table in a native disclosure; line plots do not bridge suppressed buckets. Table mode renders all approved buckets. Coverage, units and time bounds remain visible in every mode without JavaScript. Missing, restricted, loading, empty and invalid snapshots have explicit states. No arbitrary execution request, model call, browser persistence, conversion attribution or fabricated empty-series zero occurs. The host supplies updated snapshots; remote query authorization, approved budget reservation, delivery and constrained agent refresh remain integration work.

Package manifest

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

Sources