@lssm/lib.contracts-spec 17.3.2

package/dist/data-views/types.d.ts

@@ -0,0 +1,725 @@
+import type { EventRef, OpRef, PresentationRef } from '../features/index.js';
+import type { OwnerShipMeta } from '../ownership.js';
+import type { LayoutSpec } from './layout-spec.js';
+/**
+ * Supported data view kinds.
+ */
+export type DataViewKind = 'list' | 'detail' | 'table' | 'grid' | 'graph' | 'timeline' | 'timeline-graph';
+/**
+ * Metadata for a data view spec.
+ */
+export interface DataViewMeta extends OwnerShipMeta {
+    /** Canonical entity slug (e.g., "space", "resident"). */
+    entity: string;
+    /**
+     * Translation bundle key stamped by {@link defineDataView} (D1).
+     *
+     * Populated by the factory from `bundle.meta.key`; never hand-authored.
+     * The renderer qualifies each spec-field message key as
+     * `${translationKey}::${messageKey}` for the resolver's qualified path.
+     */
+    translationKey?: string;
+}
+export type DataViewDatabaseResourceKind = 'table' | 'view' | 'entity';
+export interface DataViewDatabaseResourceRef {
+    kind: DataViewDatabaseResourceKind;
+    name: string;
+    schema?: string;
+    version?: string;
+}
+export interface DataViewDatabaseFieldMapping {
+    fieldKey: string;
+    dataPath: string;
+    column: string;
+    select?: boolean;
+    filterable?: boolean;
+    sortable?: boolean;
+}
+export interface DataViewDatabasePaginationBinding {
+    mode: 'offset' | 'cursor';
+    defaultPageSize?: number;
+    maxPageSize?: number;
+    cursorField?: string;
+}
+export interface DataViewGraphMutationSafetyRequirement {
+    boundary: 'mutation' | 'order' | 'high-impact-order';
+    policyDecisionRef?: string;
+    authorityScopeRef?: string;
+    approvalOrRefusalRef?: string;
+    auditReceiptRef?: string;
+    redactionStatus?: 'pending' | 'applied' | 'blocked';
+    replayOrEvidenceRef?: string;
+    riskTier?: 'low' | 'medium' | 'high' | 'critical';
+    occurredAt?: string;
+}
+export interface DataViewGraphMutationRef extends OpRef {
+    /** Ontology edge/action ref affected by this graph mutation. */
+    ontologyRef?: string;
+    /** Fail-closed safety refs required before committing this graph mutation. */
+    safety?: DataViewGraphMutationSafetyRequirement;
+}
+export interface DataViewDatabaseBinding {
+    sourceKey: string;
+    dialect?: 'portable-sql' | 'postgresql' | 'sqlite' | 'mysql';
+    resource: DataViewDatabaseResourceRef;
+    fields: DataViewDatabaseFieldMapping[];
+    defaultFilters?: DataViewFilterClause[];
+    defaultSort?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    }[];
+    pagination?: DataViewDatabasePaginationBinding;
+    policyRefs?: {
+        key: string;
+        version: string;
+    }[];
+    provenance?: {
+        sourceRef?: string;
+        generatedBy?: string;
+        evidenceRef?: string;
+    };
+}
+/**
+ * Source configuration for fetching data in a data view.
+ */
+export interface DataViewSource {
+    /** Primary query used to fetch items for this view. */
+    primary: OpRef;
+    /** Optional operation used to fetch a single item (detail views). */
+    item?: OpRef;
+    /** Optional record mutation operations (used for inline editing or actions). */
+    mutations?: {
+        create?: OpRef;
+        update?: OpRef;
+        delete?: OpRef;
+        /**
+         * @stability experimental
+         * Add a new edge between two graph nodes. Only applicable to graph/timeline-graph views.
+         */
+        addEdge?: DataViewGraphMutationRef;
+        /**
+         * @stability experimental
+         * Remove an existing edge between two graph nodes. Only applicable to graph/timeline-graph views.
+         */
+        removeEdge?: DataViewGraphMutationRef;
+        /**
+         * @stability experimental
+         * Move a node to a new position within the graph layout. Only applicable to graph/timeline-graph views.
+         */
+        moveNode?: DataViewGraphMutationRef;
+    };
+    /** Events that should trigger refresh when emitted. */
+    refreshEvents?: EventRef[];
+    /** Optional portable database binding used by adapter packages. */
+    database?: DataViewDatabaseBinding;
+}
+/**
+ * Display formatting hints for data view fields.
+ */
+export type DataViewCurrencyCode = 'USD' | 'EUR' | 'GBP' | 'JPY' | 'CHF' | 'CAD' | 'AUD' | 'BTC' | 'ETH' | (string & {});
+export type DataViewNumberRoundingMode = 'ceil' | 'floor' | 'expand' | 'trunc' | 'halfCeil' | 'halfFloor' | 'halfExpand' | 'halfTrunc' | 'halfEven';
+export interface DataViewNumberFormatSpec {
+    type: 'number';
+    locale?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    notation?: 'standard' | 'scientific' | 'engineering' | 'compact';
+    signDisplay?: 'auto' | 'always' | 'exceptZero' | 'negative' | 'never';
+    rounding?: {
+        mode?: DataViewNumberRoundingMode;
+        increment?: number;
+    };
+}
+export interface DataViewPercentFormatSpec extends Omit<DataViewNumberFormatSpec, 'type'> {
+    type: 'percent';
+    /** `fraction` stores 0.42 as 42%; `whole` stores 42 as 42%. */
+    valueScale?: 'fraction' | 'whole';
+}
+export interface DataViewCurrencyFormatSpec extends Omit<DataViewNumberFormatSpec, 'type'> {
+    type: 'currency';
+    currency: DataViewCurrencyCode;
+    currencyDisplay?: 'symbol' | 'narrowSymbol' | 'code' | 'name';
+    /** Convenience signal for renderers that should use whole-unit display. */
+    rounded?: boolean;
+}
+export interface DataViewTemporalFormatSpec {
+    type: 'date' | 'time' | 'datetime';
+    locale?: string;
+    calendar?: string;
+    timeZone?: string;
+    dateStyle?: 'full' | 'long' | 'medium' | 'short';
+    timeStyle?: 'full' | 'long' | 'medium' | 'short';
+    hour12?: boolean;
+}
+export type DataViewDurationUnit = 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year';
+export interface DataViewDurationFormatSpec {
+    type: 'duration';
+    locale?: string;
+    unit?: DataViewDurationUnit;
+    display?: 'short' | 'narrow' | 'long' | 'digital';
+    maxUnit?: DataViewDurationUnit;
+    minUnit?: DataViewDurationUnit;
+    rounding?: {
+        mode?: DataViewNumberRoundingMode;
+        increment?: number;
+    };
+}
+export type DataViewStructuredFieldFormat = DataViewNumberFormatSpec | DataViewPercentFormatSpec | DataViewCurrencyFormatSpec | DataViewTemporalFormatSpec | DataViewDurationFormatSpec | {
+    type: 'text' | 'boolean' | 'markdown' | 'badge';
+};
+export type DataViewLegacyFieldFormat = 'text' | 'number' | 'currency' | 'percent' | 'percentage' | 'date' | 'time' | 'datetime' | 'dateTime' | 'duration' | 'boolean' | 'markdown' | 'badge';
+export type DataViewFieldFormat = DataViewLegacyFieldFormat | DataViewStructuredFieldFormat;
+export type DataViewTableOverflowBehavior = 'truncate' | 'wrap' | 'expand' | 'hideColumn' | 'none';
+export type DataViewCollectionMode = 'list' | 'grid' | 'table';
+export type DataViewDensity = 'comfortable' | 'compact';
+export type DataViewDataDepth = 'summary' | 'standard' | 'detailed' | 'exhaustive';
+export type DataViewManagementLayout = 'single-pane' | 'master-detail' | 'command-center' | 'split-pane' | 'split' | 'stacked' | 'drawer';
+export type DataViewFieldRole = 'title' | 'description' | 'icon' | 'status' | 'tag' | 'metric' | 'risk' | 'owner' | 'timestamp' | 'sensitive' | (string & {});
+export type DataViewActionPlacement = 'header' | 'toolbar' | 'row' | 'detail' | 'bulk' | 'empty' | 'context' | 'detail-header' | 'detail-section' | 'selection-toolbar' | 'empty-state' | 'overflow';
+export type DataViewActionIntent = 'primary' | 'secondary' | 'neutral' | 'destructive' | 'approval' | 'export' | 'create' | 'read' | 'update' | 'edit' | 'delete' | 'clone' | 'bulk' | 'activate' | 'pause' | 'refresh' | 'custom';
+export type DataViewActionSelectionScope = 'none' | 'single' | 'multiple' | 'all' | 'current-page';
+export type DataViewActionBoundary = 'allowed' | 'allowed_with_conditions' | 'requires_approval' | 'requires-approval' | 'blocked' | 'hidden';
+export interface DataViewCollectionViewModesConfig {
+    defaultMode?: DataViewCollectionMode;
+    allowedModes?: DataViewCollectionMode[];
+    labels?: Partial<Record<DataViewCollectionMode, string>>;
+}
+export interface DataViewCollectionPaginationConfig {
+    pageSize?: number;
+    pageSizeOptions?: number[];
+}
+export interface DataViewCollectionSearchConfig {
+    enabled?: boolean;
+    placeholder?: string;
+    debounceMs?: number;
+    filterKey?: string;
+}
+export interface DataViewCollectionToolbarConfig {
+    enabled?: boolean;
+    search?: boolean | DataViewCollectionSearchConfig;
+    viewMode?: boolean | DataViewCollectionViewModesConfig;
+    filters?: boolean;
+    density?: boolean;
+    dataDepth?: boolean;
+    actions?: 'start' | 'end' | 'both' | 'hidden';
+}
+export interface DataViewCollectionPersonalizationPersistConfig {
+    viewMode?: boolean;
+    density?: boolean;
+    dataDepth?: boolean;
+    pageSize?: boolean;
+    managementLayout?: boolean;
+}
+export interface DataViewCollectionPersonalizationConfig {
+    enabled?: boolean;
+    persist?: DataViewCollectionPersonalizationPersistConfig;
+}
+export interface DataViewCollectionConfig {
+    viewModes?: DataViewCollectionViewModesConfig;
+    toolbar?: DataViewCollectionToolbarConfig;
+    pagination?: DataViewCollectionPaginationConfig;
+    density?: DataViewDensity;
+    dataDepth?: DataViewDataDepth;
+    personalization?: DataViewCollectionPersonalizationConfig;
+}
+export interface DataViewFieldVisibility {
+    minDataDepth?: DataViewDataDepth;
+    roles?: DataViewFieldRole[];
+}
+/**
+ * Field definition within a data view.
+ */
+export interface DataViewField {
+    /** Unique identifier for the field within the view. */
+    key: string;
+    /** Human-friendly label for headers/tooltips. */
+    label: string;
+    /** Dot-path into the data item (e.g., "address.city"). */
+    dataPath: string;
+    /** Optional description surfaced in tooltips or docs. */
+    description?: string;
+    /** Optional formatting hint for renderers. */
+    format?: DataViewFieldFormat;
+    /** When true, the field can be used for sorting. */
+    sortable?: boolean;
+    /** When true, the field can be used for filtering. */
+    filterable?: boolean;
+    /** Optional width hint for table layouts. */
+    width?: 'auto' | 'xs' | 'sm' | 'md' | 'lg';
+    /** Optional table overflow behavior. Table columns can override this. */
+    overflow?: DataViewTableOverflowBehavior;
+    /** Optional presentation override (e.g., card component). */
+    presentation?: PresentationRef;
+    /** Optional singular semantic role kept for backwards compatibility. */
+    role?: DataViewFieldRole;
+    /** Optional semantic roles used by management shells and adaptive projections. */
+    roles?: DataViewFieldRole[];
+    /** Optional display-depth gates for preference-aware renderers. */
+    visibility?: DataViewFieldVisibility;
+}
+/**
+ * Filter definition for a data view.
+ */
+export interface DataViewFilter {
+    key: string;
+    label: string;
+    field: string;
+    type: 'search' | 'enum' | 'number' | 'percent' | 'currency' | 'date' | 'time' | 'datetime' | 'duration' | 'boolean';
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    operator?: DataViewFilterOperator;
+    valueMode?: 'single' | 'multi' | 'range' | 'composite';
+}
+export type DataViewFilterScalar = string | number | boolean;
+export type DataViewFilterComparable = string | number;
+export type DataViewFilterOperator = 'eq' | 'neq' | 'contains' | 'in' | 'notIn' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'isNull' | 'isNotNull';
+export type DataViewFilterValue = {
+    kind: 'single';
+    value: DataViewFilterScalar;
+} | {
+    kind: 'multi';
+    values: DataViewFilterScalar[];
+} | {
+    kind: 'range';
+    from?: DataViewFilterComparable;
+    to?: DataViewFilterComparable;
+    includeFrom?: boolean;
+    includeTo?: boolean;
+} | {
+    kind: 'composite';
+    mode: 'and' | 'or';
+    clauses: DataViewFilterClause[];
+};
+export interface DataViewFilterClause {
+    filterKey: string;
+    field: string;
+    operator: DataViewFilterOperator;
+    value?: DataViewFilterValue;
+}
+export type DataViewFilterSet = Record<string, DataViewFilterValue | undefined>;
+export interface DataViewFilterScope {
+    initial?: DataViewFilterSet;
+    locked?: DataViewFilterSet;
+    lockedChips?: 'visible-disabled' | 'hidden';
+}
+export interface DataViewActionBoundaryHint {
+    destructive?: boolean;
+    requiresApproval?: boolean;
+    confirmationRef?: PresentationRef;
+    policyRef?: string | {
+        key: string;
+        version?: string;
+    };
+}
+export interface DataViewActionStateRule {
+    boundary?: DataViewActionBoundary;
+    requiresApproval?: boolean;
+    disabled?: boolean;
+    hidden?: boolean;
+    hiddenWhen?: string;
+    disabledWhen?: string;
+    explanation?: string;
+    reason?: string;
+    policyRef?: {
+        key: string;
+        version: string;
+    };
+    roleMorphRef?: {
+        key: string;
+        version?: string;
+    };
+    when?: string;
+}
+export interface DataViewActionConfirmation {
+    required?: boolean;
+    title?: string;
+    description?: string;
+    presentation?: PresentationRef;
+}
+export interface DataViewActionState {
+    boundary?: DataViewActionBoundary;
+    disabled?: boolean;
+    hidden?: boolean;
+    reason?: string;
+    requiresApproval?: boolean;
+    roleMorphRef?: {
+        key: string;
+        version?: string;
+    };
+}
+export interface DataViewActionConfirmation {
+    required?: boolean;
+    title?: string;
+    description?: string;
+    presentation?: PresentationRef;
+}
+/**
+ * Action that can be triggered from a data view.
+ */
+export interface DataViewAction {
+    key: string;
+    label: string;
+    kind: 'navigation' | 'operation';
+    /** Operation invoked when kind === 'operation'. */
+    operation?: OpRef;
+    /** Optional feature flag gating the action. */
+    requiresFlag?: string;
+    /** Optional renderer placement for management shells. */
+    placement?: DataViewActionPlacement | DataViewActionPlacement[];
+    /** Optional semantic intent for styling, confirmation, and grouping. */
+    intent?: DataViewActionIntent;
+    /** Selection scope required before the action can run. */
+    selectionScope?: DataViewActionSelectionScope;
+    /** Icon hint for renderers; host decides the actual icon component. */
+    icon?: string;
+    /** Declarative safety hint before/after policy-adaptive resolution. */
+    boundary?: DataViewActionBoundaryHint;
+    /** Declarative safety state after policy/adaptive resolution. */
+    state?: DataViewActionState;
+    /** Optional confirmation metadata; host apps still own the dialog flow. */
+    confirmation?: {
+        required?: boolean;
+        title?: string;
+        description?: string;
+        confirmLabel?: string;
+    };
+}
+/**
+ * Relationship section primitive for detail views.
+ *
+ * Declares a related-record collection rendered inside an entity's detail
+ * panel (e.g. `Client` → one-to-many `ClientAddress`). The design-system
+ * performs no I/O: related records arrive either embedded on the item at
+ * {@link dataPath}, or via host-supplied data keyed by {@link key}. The
+ * declared {@link source} `OpRef` exists for discoverability/type-safety but
+ * is executed by the host, mirroring the `EntityWorkspace` query/side-effect
+ * pattern.
+ *
+ * `cardinality` is metadata-only in v1: all cardinalities render as a record
+ * collection identically (no join-table/dedupe semantics).
+ */
+export interface DataViewSectionRelationship {
+    /** Stable identifier for the relationship within the detail view. */
+    key: string;
+    /** Human-friendly label for the relationship section/switcher. */
+    label?: string;
+    /** Relationship cardinality. Metadata-only in v1 (renders identically). */
+    cardinality: 'one-to-one' | 'one-to-many' | 'many-to-many';
+    /** Dot-path to an embedded related-record array on the item ("all-in-one"). */
+    dataPath?: string;
+    /** Declared relation operation, executed by the host (DS performs no I/O). */
+    source?: OpRef;
+    /** Child `DataViewSpec` key for registry-resolved field/format/action reuse. */
+    specKey?: string;
+    /** Optional child-spec version for exact `${key}.v${version}` resolution. */
+    specVersion?: string;
+    /** Inline field definitions when no child spec is referenced. */
+    fields?: DataViewField[];
+    /** Render mode for the related rows. Defaults to `compact-list`. */
+    displayMode?: 'table' | 'list' | 'compact-list';
+    /** Optional foreign-key hint for host-side relation resolution. */
+    foreignKey?: string;
+    /** Optional cap on rendered related rows (host owns pagination). */
+    limit?: number;
+    /** Message shown when the relation resolves to no records. */
+    emptyState?: string;
+}
+/**
+ * Section configuration for detail views.
+ *
+ * Sections are discriminated by {@link kind} (default `'fields'`). A
+ * `'relationship'` section carries a {@link relationship} descriptor and
+ * renders a related-record collection instead of a field grid.
+ */
+export interface DataViewSections {
+    title?: string;
+    description?: string;
+    /**
+     * Field keys rendered in this section. Optional so a `'relationship'`
+     * section need not carry field keys; defaults to a `'fields'` section when
+     * {@link kind} is omitted.
+     */
+    fields?: string[];
+    key?: string;
+    role?: 'summary' | 'metrics' | 'details' | 'activity' | (string & {});
+    visibility?: DataViewFieldVisibility;
+    /** Section discriminant. Defaults to `'fields'` when omitted. */
+    kind?: 'fields' | 'relationship';
+    /** Relationship descriptor; required when {@link kind} is `'relationship'`. */
+    relationship?: DataViewSectionRelationship;
+}
+export interface DataViewManagementHeaderConfig {
+    title?: string;
+    description?: string;
+    sourceSummary?: string;
+    createAction?: string;
+    createActionKey?: string;
+}
+export interface DataViewManagementSearchConfig extends DataViewCollectionSearchConfig {
+    fields?: string[];
+}
+export interface DataViewManagementSortControl {
+    field: string;
+    direction?: 'asc' | 'desc';
+    label?: string;
+}
+export type DataViewManagementSortOption = DataViewManagementSortControl;
+export interface DataViewManagementActionGroupConfig {
+    key: string;
+    label?: string;
+    placement?: DataViewActionPlacement;
+    actionKeys: string[];
+}
+export interface DataViewManagementToolbarConfig {
+    search?: DataViewManagementSearchConfig;
+    searchFields?: string[];
+    filters?: boolean | string[];
+    filterKeys?: string[];
+    sort?: DataViewManagementSortControl[];
+    sortFields?: string[];
+    actionGroups?: Record<string, string[]> | Partial<Record<DataViewActionPlacement, string[]>>;
+    export?: boolean | 'csv' | 'json';
+    selectAll?: boolean;
+}
+export interface DataViewManagementLayoutConfig {
+    variant?: DataViewManagementLayout;
+    collapseDetailBelow?: 'sm' | 'md' | 'lg' | 'xl';
+}
+export interface DataViewManagementPaginationSummaryConfig {
+    enabled?: boolean;
+    itemLabel?: string;
+}
+export interface DataViewManagementMetricConfig {
+    field: string;
+    label?: string;
+    format?: DataViewFieldFormat;
+}
+export interface DataViewManagementSelectionConfig {
+    mode?: DataViewTableSelectionMode;
+    activeItem?: boolean;
+    activeItemKey?: string;
+    bulkActions?: string[];
+    bulkActionKeys?: string[];
+}
+export interface DataViewManagementRowCardConfig {
+    titleField?: string;
+    descriptionField?: string;
+    iconField?: string;
+    statusField?: string;
+    showFieldLabels?: boolean;
+    fieldLabelVisibility?: Record<string, boolean>;
+    tagFields?: string[];
+    metaFields?: string[];
+}
+export interface DataViewManagementEmptyDetailConfig {
+    title?: string;
+    description?: string;
+    actionKey?: string;
+    ctaAction?: string;
+    presentation?: PresentationRef;
+}
+export type DataViewManagementRichRowConfig = DataViewManagementRowCardConfig;
+export interface DataViewManagementDetailConfig {
+    sections?: DataViewSections[];
+    actionGroups?: Record<string, string[]>;
+    actionKeys?: string[];
+    titleField?: string;
+    badgeFields?: string[];
+    metricFields?: (string | DataViewManagementMetricConfig)[];
+    emptyState?: DataViewManagementEmptyDetailConfig;
+}
+export type DataViewManagementDetailPanelConfig = DataViewManagementDetailConfig;
+export interface DataViewManagementAdaptiveConfig {
+    preferenceKey?: string;
+    personalizationKey?: string;
+    rolemorphSurfaceKey?: string;
+    roleMorphSurfaceRef?: string | {
+        key: string;
+        version?: string;
+    };
+    fieldRoleMap?: Record<string, DataViewFieldRole | DataViewFieldRole[]>;
+    actionBoundaryMap?: Record<string, DataViewActionBoundary>;
+    defaultLayout?: DataViewManagementLayout;
+    defaultEmptyStateVariant?: 'select-first' | 'create-first' | (string & {});
+    formFlowVariant?: 'host-slot' | 'inline' | 'drawer' | (string & {});
+    guidance?: 'guided' | 'minimal' | (string & {});
+}
+export type DataViewManagementAdaptiveBindings = DataViewManagementAdaptiveConfig;
+export interface DataViewManagementConfig {
+    enabled?: boolean;
+    variant?: 'command-center' | 'master-detail' | 'crud' | (string & {});
+    layout?: DataViewManagementLayout | DataViewManagementLayoutConfig;
+    header?: DataViewManagementHeaderConfig;
+    toolbar?: DataViewManagementToolbarConfig;
+    paginationSummary?: boolean | DataViewManagementPaginationSummaryConfig;
+    selection?: DataViewManagementSelectionConfig;
+    richRow?: DataViewManagementRowCardConfig;
+    rowCard?: DataViewManagementRowCardConfig;
+    detail?: DataViewManagementDetailConfig;
+    detailPanel?: DataViewManagementDetailPanelConfig;
+    adaptive?: DataViewManagementAdaptiveConfig;
+}
+export interface DataViewBaseConfig {
+    kind: DataViewKind;
+    fields: DataViewField[];
+    primaryField?: string;
+    secondaryFields?: string[];
+    filters?: DataViewFilter[];
+    filterScope?: DataViewFilterScope;
+    actions?: DataViewAction[];
+    /** Optional entity-management shell metadata for command-center layouts. */
+    management?: DataViewManagementConfig;
+}
+/**
+ * List view configuration.
+ */
+export interface DataViewListConfig extends DataViewBaseConfig {
+    kind: 'list';
+    layout?: 'card' | 'compact';
+    collection?: DataViewCollectionConfig;
+}
+/**
+ * Detail view configuration.
+ */
+export interface DataViewDetailConfig extends DataViewBaseConfig {
+    kind: 'detail';
+    sections?: DataViewSections[];
+}
+/**
+ * Table column configuration.
+ */
+export interface DataViewTableColumn {
+    field: string;
+    label?: string;
+    width?: 'auto' | 'xs' | 'sm' | 'md' | 'lg';
+    align?: 'left' | 'center' | 'right';
+    sortable?: boolean;
+    hideable?: boolean;
+    resizable?: boolean;
+    pinned?: false | 'left' | 'right';
+    defaultWidth?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    overflow?: DataViewTableOverflowBehavior;
+}
+export type DataViewTableExecutionMode = 'client' | 'server';
+export type DataViewTableSelectionMode = 'none' | 'single' | 'multiple';
+export interface DataViewTableExpansionConfig {
+    fields: string[];
+}
+export interface DataViewTableSort {
+    field: string;
+    desc?: boolean;
+}
+export interface DataViewTablePinnedColumns {
+    left?: string[];
+    right?: string[];
+}
+export interface DataViewTableInitialState {
+    sorting?: DataViewTableSort[];
+    pageSize?: number;
+    hiddenColumns?: string[];
+    pinnedColumns?: DataViewTablePinnedColumns;
+    expandedRowIds?: string[];
+}
+/**
+ * Table view configuration.
+ */
+export interface DataViewTableConfig extends DataViewBaseConfig {
+    kind: 'table';
+    columns?: DataViewTableColumn[];
+    executionMode?: DataViewTableExecutionMode;
+    selection?: DataViewTableSelectionMode;
+    columnVisibility?: boolean;
+    columnResizing?: boolean;
+    columnPinning?: boolean;
+    rowExpansion?: DataViewTableExpansionConfig;
+    initialState?: DataViewTableInitialState;
+    rowSelectable?: boolean;
+    density?: DataViewDensity;
+    collection?: DataViewCollectionConfig;
+}
+/**
+ * Grid view configuration.
+ */
+export interface DataViewGridConfig extends DataViewBaseConfig {
+    kind: 'grid';
+    columns?: number;
+    collection?: DataViewCollectionConfig;
+}
+/**
+ * Graph view configuration.
+ *
+ * Renders nodes and edges as an interactive graph canvas.
+ * Layout, node-kind, and edge-kind fields are optional and drive
+ * how the renderer organises and colours the graph.
+ */
+export interface DataViewGraphConfig extends DataViewBaseConfig {
+    kind: 'graph';
+    /** Graph layout algorithm. M3 LayoutSpec discriminated union. */
+    layout?: LayoutSpec;
+    /** Field on each node record that holds the node kind/type discriminator. */
+    nodeKindField?: string;
+    /** Field on each edge record that holds the edge kind/type discriminator. */
+    edgeKindField?: string;
+    /** Optional collection config (pagination/sorting for large graphs). */
+    collection?: DataViewCollectionConfig;
+    /**
+     * Node inspector surface style.
+     * - 'panel'  — master-detail side panel (default, matches existing shell layout).
+     * - 'drawer' — sliding overlay drawer.
+     * - 'sheet'  — bottom sheet (mobile-friendly).
+     * - 'route'  — full-page navigation to node detail route.
+     */
+    inspector?: 'panel' | 'drawer' | 'sheet' | 'route';
+}
+/**
+ * Timeline view configuration.
+ *
+ * Projects records along a time axis. A required `timeField` drives the
+ * x-axis placement; an optional `endField` enables span/interval display.
+ */
+export interface DataViewTimelineConfig extends DataViewBaseConfig {
+    kind: 'timeline';
+    /** Field key whose value is an ISO 8601 string or epoch ms timestamp. */
+    timeField: string;
+    /** Optional field key for the end of a span/interval event. */
+    endField?: string;
+    /** Zoom range constraints for the timeline axis. */
+    zoom?: {
+        /** Minimum zoom level (e.g. 'day', 'week', 'month'). */
+        min?: string;
+        /** Maximum zoom level. */
+        max?: string;
+        /** Default zoom level on first render. */
+        default?: string;
+    };
+}
+/**
+ * Timeline-graph view configuration.
+ *
+ * Hybrid view: graph topology overlaid on a time axis so nodes can be
+ * positioned by time while edges show relationships between them.
+ */
+export interface DataViewTimelineGraphConfig extends DataViewBaseConfig {
+    kind: 'timeline-graph';
+    /** Field key whose value is an ISO 8601 string or epoch ms timestamp. */
+    timeField: string;
+    /** Field on each node record that holds the node kind/type discriminator. */
+    nodeKindField?: string;
+}
+/**
+ * Union of all data view configurations.
+ */
+export type DataViewConfig = DataViewListConfig | DataViewDetailConfig | DataViewTableConfig | DataViewGridConfig | DataViewGraphConfig | DataViewTimelineConfig | DataViewTimelineGraphConfig;
+/**
+ * Presentation references for different view states.
+ */
+export interface DataViewStates {
+    empty?: PresentationRef;
+    error?: PresentationRef;
+    loading?: PresentationRef;
+}