LayoutFacet · Traits · OODS Foundry

Fields it adds

Field	Type	Required	Description
`viz_layout_type`	`string` (facet)	yes	Normalized layout identifier.
`viz_layout_rows_field`	`string`	no	Data field used to derive facet rows.
`viz_layout_columns_field`	`string`	no	Data field used to derive facet columns.
`viz_layout_wrap_direction`	`string` (row, column, auto)	no	How facets wrap when exceeding panel limits.
`viz_layout_max_panels`	`number`	no	Maximum panel count rendered simultaneously.
`viz_layout_shared_channels`	`string[]`	no	Channels whose domains remain shared across panels.
`viz_layout_projection`	`string` (cartesian, polar, radial)	no	Projection metadata forwarded to adapters and docs.
`viz_layout_gap`	`number`	no	Gap (px) between panels.

What it shows in each context

This trait places no component of its own.

Parameters

rowField string: Field used to create facet rows.
columnField string: Field used to create facet columns.
wrapDirection string: Direction to wrap when panels exceed the budget.
maxPanels number: Maximum panel count rendered simultaneously.
sharedChannels string[]: Encoding channels that remain synchronized across panels.
projection string: Projection hint consumed by downstream adapters.

Objects that use it

No shipped object uses this trait.

The trait file

traits/viz/layout-facet.trait.yaml

trait:
  name: LayoutFacet
  version: 0.2.0
  description: >
    Repeats a normalized visualization spec across a governed facet grid so row
    and column groupings stay synchronized with shared color/scale semantics.
  category: viz.layout
  tags:
    - viz
    - layout
    - facet
    - grid

parameters:
  - name: rowField
    type: string
    required: false
    description: Field used to create facet rows.
  - name: columnField
    type: string
    required: false
    description: Field used to create facet columns.
  - name: wrapDirection
    type: string
    required: false
    description: Direction to wrap when panels exceed the budget.
    default: row
    validation:
      enum: [row, column, auto]
  - name: maxPanels
    type: number
    required: false
    description: Maximum panel count rendered simultaneously.
    default: 6
    validation:
      minimum: 1
      maximum: 48
  - name: sharedChannels
    type: string[]
    required: false
    description: Encoding channels that remain synchronized across panels.
    default:
      - x
      - y
      - color
  - name: projection
    type: string
    required: false
    description: Projection hint consumed by downstream adapters.
    default: cartesian
    validation:
      enum: [cartesian, polar, radial]

schema:
  viz_layout_type:
    type: string
    required: true
    description: Normalized layout identifier.
    default: facet
    validation:
      enum: [facet]
  viz_layout_rows_field:
    type: string
    required: false
    description: Data field used to derive facet rows.
    defaultFromParameter: rowField
  viz_layout_columns_field:
    type: string
    required: false
    description: Data field used to derive facet columns.
    defaultFromParameter: columnField
  viz_layout_wrap_direction:
    type: string
    required: false
    description: How facets wrap when exceeding panel limits.
    defaultFromParameter: wrapDirection
    validation:
      enum: [row, column, auto]
  viz_layout_max_panels:
    type: number
    required: false
    description: Maximum panel count rendered simultaneously.
    defaultFromParameter: maxPanels
    validation:
      minimum: 1
      maximum: 48
  viz_layout_shared_channels:
    type: string[]
    required: false
    description: Channels whose domains remain shared across panels.
    defaultFromParameter: sharedChannels
  viz_layout_projection:
    type: string
    required: false
    description: Projection metadata forwarded to adapters and docs.
    defaultFromParameter: projection
    validation:
      enum: [cartesian, polar, radial]
  viz_layout_gap:
    type: number
    required: false
    description: Gap (px) between panels.
    default: 16
    validation:
      minimum: 0
      maximum: 64

semantics:
  viz_layout_type:
    semantic_type: viz.layout.type
    ui_hints:
      component: Badge
  viz_layout_rows_field:
    semantic_type: viz.layout.facet.rows
    ui_hints:
      component: Code
  viz_layout_columns_field:
    semantic_type: viz.layout.facet.columns
    ui_hints:
      component: Code
  viz_layout_wrap_direction:
    semantic_type: viz.layout.facet.wrap
    ui_hints:
      component: Badge
  viz_layout_max_panels:
    semantic_type: viz.layout.facet.panels
    ui_hints:
      component: NumericPreview
      unit: panels
  viz_layout_shared_channels:
    semantic_type: viz.layout.shared_channels
    ui_hints:
      component: ListSummary
  viz_layout_projection:
    semantic_type: viz.layout.projection
    ui_hints:
      component: Badge
  viz_layout_gap:
    semantic_type: viz.layout.spacing
    ui_hints:
      component: NumericPreview
      unit: px

tokens:
  viz.layout.facet.gap: var(--cmp-viz-layout-gap)

dependencies:
  - trait: MarkBar
    optional: true
  - trait: MarkLine
    optional: true
  - trait: MarkPoint
    optional: true
  - trait: MarkArea
    optional: true

metadata:
  created: '2025-11-16'
  updated: '2026-02-28'
  owners:
    - viz@oods.systems
  maturity: beta
  accessibility:
    keyboard: Facet panels are navigable via arrow keys. Each panel is a tab stop.
    screenreader: Announces facet field name and panel count (e.g., "Faceted by Region, 6 panels").
  examples:
    - SalesByRegionFaceted
    - ChurnByPlanType
    - TicketVolumeByCategoryAndMonth
  references:
    - objects/provenance.v1.json#/references/ref-c52ae10b7f25
    - Sprint 23 plan