[Traits](https://oods-foundry.com/traits) / LayoutFacet

# LayoutFacet

Repeats a normalized visualization spec across a governed facet grid so row and column groupings stay synchronized with shared color/scale semantics.

Generated from @oods/foundry 0.10.1

- Group

  viz.layout

- Maturity

  beta

- Contexts

  none listed

## 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
```