OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

AI index

DataViewSpec Overview

DataViewSpec is the declarative contract for projecting entities into list/detail/table/grid experiences. Each spec ties to contract operations (source.primary, source.item) and describes how the UI should present, sort, filter, paginate, and pin records. Host applications use the spec to render UI with shared components (DataViewRenderer, DataViewList, DataViewTable, DataViewDetail) while keeping presentation logic in a single source of truth.

field.key.label
DataViewSpec Overview
field.version.label
field.type.label
field.title.label
DataViewSpec Overview
field.description.label

DataViewSpec is the declarative contract for projecting entities into list/detail/table/grid experiences. Each spec ties to contract operations (source.primary, source.item) and describes how the UI should present, sort, filter, paginate, and pin records. Host applications use the spec to render UI with shared components (DataViewRenderer, DataViewList, DataViewTable, DataViewDetail) while keeping presentation logic in a single source of truth.

field.tags.label
tech,contracts,data-views
field.owners.label
field.stability.label
public

Purpose

`DataViewSpec` is the declarative contract for projecting entities into list/detail/table/grid experiences. Each spec ties to contract operations (`source.primary`, `source.item`) and describes how the UI should present, sort, filter, paginate, and pin records. Host applications use the spec to render UI with shared components (`DataViewRenderer`, `DataViewList`, `DataViewTable`, `DataViewDetail`) while keeping presentation logic in a single source of truth.

Location

•

Type definitions and registry: `packages/libs/contracts/src/data-views.ts`

•

React renderers: `packages/libs/design-system/src/components/data-view`

•

CLI scaffolding: `contractspec create --type data-view`

Schema Highlights

export interface DataViewSpec {
  meta: DataViewMeta;       // ownership meta + { name, version, entity }
  source: DataViewSource;   // contract operations and refresh events
  view: DataViewConfig;     // union of list/detail/table/grid definitions
  states?: DataViewStates;  // optional empty/error/loading presentations
  policy?: { flags?: string[]; pii?: string[] };
}

•

**DataViewMeta**: `name`, `version`, `entity`, ownership metadata (title, description, domain, owners, tags, stability).

•

**DataViewSource**:

•

`primary`: required query operation (`OpRef`) for fetching collections.

•

`item`: optional operation used to fetch a single item (detail views).

•

`mutations`: optional create/update/delete operation refs.

•

`refreshEvents`: events that should trigger refresh.

•

**DataViewConfig** (union):

•

`list`: card/compact list, `primaryField`, `secondaryFields`.

•

`table`: column configuration plus execution mode, selection, column visibility, column resizing, column pinning, row expansion, overflow behavior, and initial state.

•

`detail`: sections of fields for record inspection.

•

`grid`: multi-column grid (rendered as card list today).

•

**DataViewField**: `key`, `label`, `dataPath`, formatting hints (`format`), sort/filter toggles, optional table overflow hint, optional presentation override.

•

**DataViewTableColumn**: per-table column metadata. Column `overflow` overrides field `overflow`, which overrides type-aware defaults. Supported overflow values are `truncate`, `wrap`, `expand`, `hideColumn`, and `none`.

•

**DataViewFilter**: describes filter inputs (search, enum, number, date, boolean).

•

**DataViewAction**: simple declarative actions (`navigation` or `operation`).

Registry Usage

import { DataViewRegistry } from '@lssm-tech/lib.contracts-spec/data-views';
import { ResidentsDataView } from './data-views/residents.data-view';

const registry = new DataViewRegistry();
registry.register(ResidentsDataView);

const listView = registry.get('residents.admin.list');

Registries guard against duplicate `(name, version)` pairs and make latest-version lookup trivial.

Rendering

import { DataViewRenderer } from '@lssm-tech/lib.design-system';
import { ResidentsDataView } from '../contracts/data-views/residents.data-view';

function ResidentsTable({ rows }: { rows: Record<string, unknown>[] }) {
  return (
    <DataViewRenderer
      spec={ResidentsDataView}
      items={rows}
      onRowClick={(row) => console.log('Selected', row)}
    />
  );
}

For more control, use specific components:

•

`DataViewList` – friendly cards/rows

•

`DataViewTable` – tabular presentation with shared sorting, pagination, visibility, pinning, resizing, expansion controls, and overflow handling

•

`DataViewDetail` – two-column grouped layout for record inspection

Renderers rely on the field definitions (`dataPath`, `format`) to extract values and render them consistently. Table overflow defaults are type-aware: markdown wraps; text, badges, numbers, currency, percentages, dates, times, durations, and booleans truncate. `expand` keeps the compact cell and adds the field to row expansion; `hideColumn` starts hidden when column visibility is enabled.

CLI Scaffolding

# Interactive wizard
contractspec create --type data-view

# Generates packages/.../data-views/<name>.data-view.ts

# Optional renderer scaffold
contractspec build path/to/<name>.data-view.ts
# → produces <name>.renderer.tsx that wraps DataViewRenderer with sensible props

Wizard prompts:

•

name (dot notation), version, entity

•

kind (`list`, `table`, `detail`, `grid`)

•

primary query operation (required) and optional item query

•

fields (label, data path, format, sorting/filtering)

Authoring Guidelines

1.

**Separation of data & presentation**: keep fetching logic inside contract operations; DataViewSpec only references them via `source`.

2.

**Versioning**: bump `meta.version` when field membership, ordering, or semantics change.

3.

**Consistency**: reuse common field keys across modules to enable shared renderers and filters.

4.

**States**: reference `PresentationRef` for empty/error/loader states to ensure consistent UX.

5.

**Actions**: prefer referencing contract operations instead of embedding business logic in the UI.

Roadmap

•

Derived filters from `fields.filterable` (auto-generated UI).

•

Policy-aware field visibility for table columns.

•

Automated docs/LLM sync via CLI.