table

Filterable structured reference

Install

docsloth component add @docsloth/table@1.0.0

Live package: sha256:9eb3021214ce7a962dd1650b424855f6f4467a94bfc42f929cb7a4dc82080094 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/table.schema.json.

Example props generated from this schema:

{
  "title": "example-title",
  "columns": [
    {
      "key": "example-key",
      "label": "example-label",
      "sortable": true
    }
  ],
  "rows": [
    {
      "key": "example-key",
      "cells": [
        "example-cells"
      ]
    }
  ],
  "filterable": true
}

Required props: columns, rows.

Example

Example document IR (the block the renderer consumes):

{
  "type": "table",
  "props": {
    "rows": [
      [
        "component",
        "trust class"
      ],
      [
        "prose",
        "pure"
      ],
      [
        "tabs",
        "interactive"
      ]
    ]
  }
}

Renderer HTML (entities decoded and wrapped for display):

<table class="ds-table">
<tr>
<td>component</td>
<td>trust class</td>
</tr>
<tr>
<td>prose</td>
<td>pure</td>
</tr>
<tr>
<td>tabs</td>
<td>interactive</td>
</tr>
</table>

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/table.md.

Contract

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

Accessible header cells; stable sort/filter and CSV export only audience-approved cells.

Official React implementation

Production { key, cells } rows render one cell under each declared column. Row keys and surplus cells are not displayed or searched. Array rows remain accepted for older hosts. title provides a caption; filterable: false removes filtering. Declared sortable columns expose ascending and descending natural text order through header buttons and aria-sort, retaining source order for ties. Filtering and sorting reset the initial 200-row view; **Show more rows** reveals each following group of 200. A live status announces the visible count or empty result.

These interactions are local and issue no capability or network requests. CSV export uses all filtered rows in the current sort order, including rows beyond the incremental display, and only the visible columns. The UTF-8 file includes a BOM, quoted fields and CRLF row separators; quotes inside fields are doubled. Formula-like values (including header labels, leading control/format characters and full-width formula markers) receive a visible Text: prefix. This deliberately changes those exported values rather than relying on escapes that spreadsheets may remove when re-saving (CSV injection considerations). The on-page note describes this behavior. Exports larger than 10 MiB are refused before creating a download; filtering can reduce the file. Temporary object URLs are revoked after use, and unsupported browser download APIs produce a visible error. Server-bound pagination remains outside this React implementation. Without JavaScript, its complete supplied data remains readable under plain column headings. Filtering, sorting and incremental display controls appear only after hydration; hydrated pages start with 200 rows. Server output includes all rows up to the production schema's 5000-row limit, so its size grows with the authorized data. This is a readable fallback, not server pagination or virtualization.

Failure and fallback

More than 5000 rows uses server pagination after explicit resource binding.

Required acceptance cases

Empty filter status announced; sorting stable and numerical columns declared. 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.

Package manifest

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

Sources