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

# EncodingPositionX

Binds a data field to the horizontal axis.

Generated from @oods/foundry 0.10.1

- Group

  viz.encoding

- Maturity

  alpha

- Contexts

  detail, form, list

Declares allowed data types, scale defaults, and accessibility metadata to satisfy Normalized Viz Spec requirements.

## Fields it adds

| Field | Type | Required | Description |
| - | - | - | - |
| `viz_encoding_x_field` | `string` | yes | Name of the data field bound to the X axis. |
| `viz_encoding_x_field_kind` | `string` | yes | Data classification used for heuristics and validation. |
| `viz_encoding_x_scale` | `string` (linear, temporal) | yes | Scale identifier applied to values (linear or temporal). |
| `viz_encoding_x_include_zero` | `boolean` | no | Indicates whether zero baseline enforcement is active. |
| `viz_encoding_x_axis_title` | `string` | no | Default axis title used in UI and fallback descriptions. |
| `viz_encoding_x_sort` | `string` (none, ascending, descending) | no | Default sort direction for discrete axes. |

## What it shows in each context

- [detail](https://oods-foundry.com/contexts/detail)

  `VizAxisSummary`

- [form](https://oods-foundry.com/contexts/form)

  `VizAxisControls`

- [list](https://oods-foundry.com/contexts/list)

  `VizEncodingBadge`

## Parameters

- `renderIntent` `string`

  JSON-encoded Cartesian viz.render input fragment for the governed authoring recipes. Data rows remain a consumer operand.

- `fieldKinds` `string[]`, required

  Data categories that can map to the X axis.

- `defaultScale` `string`, required

  Default scale used when none is specified by the spec author.

- `includeZero` `boolean`

  Whether quantitative mappings force a zero baseline.

- `axisTitle` `string`

  Default title surfaced in axis + a11y description.

- `sorting` `string`

  Default sort applied to discrete categories.

## Objects that use it

No shipped object uses this trait.

## The trait file

`traits/viz/encoding-position-x.trait.yaml`

```
trait:
  name: EncodingPositionX
  version: 0.2.0
  description: |
    Binds a data field to the horizontal axis. Declares allowed data types,
    scale defaults, and accessibility metadata to satisfy Normalized Viz Spec
    requirements.
  category: viz.encoding
  tags:
    - viz
    - encoding
    - x-axis
    - position

parameters:
  - {"name": "renderIntent", "type": "string", "required": false, "default": "{}", "description": "JSON-encoded Cartesian viz.render input fragment for the governed authoring recipes. Data rows remain a consumer operand."}
  - name: fieldKinds
    type: string[]
    required: true
    description: Data categories that can map to the X axis.
    default:
      - nominal
      - ordinal
      - quantitative
      - temporal
  - name: defaultScale
    type: string
    required: true
    description: Default scale used when none is specified by the spec author.
    default: linear
    validation:
      enum:
        - linear
        - temporal
  - name: includeZero
    type: boolean
    required: false
    description: Whether quantitative mappings force a zero baseline.
    default: true
  - name: axisTitle
    type: string
    required: false
    description: Default title surfaced in axis + a11y description.
    default: X Axis
  - name: sorting
    type: string
    required: false
    description: Default sort applied to discrete categories.
    default: none
    validation:
      enum:
        - none
        - ascending
        - descending

schema:
  viz_encoding_x_field:
    type: string
    required: true
    description: Name of the data field bound to the X axis.
  viz_encoding_x_field_kind:
    type: string
    required: true
    description: Data classification used for heuristics and validation.
    validation:
      enumFromParameter: fieldKinds
  viz_encoding_x_scale:
    type: string
    required: true
    description: Scale identifier applied to values (linear or temporal).
    defaultFromParameter: defaultScale
    validation:
      enum:
        - linear
        - temporal
  viz_encoding_x_include_zero:
    type: boolean
    required: false
    description: Indicates whether zero baseline enforcement is active.
    defaultFromParameter: includeZero
  viz_encoding_x_axis_title:
    type: string
    required: false
    description: Default axis title used in UI and fallback descriptions.
    defaultFromParameter: axisTitle
  viz_encoding_x_sort:
    type: string
    required: false
    description: Default sort direction for discrete axes.
    defaultFromParameter: sorting
    validation:
      enum:
        - none
        - ascending
        - descending

semantics:
  viz_encoding_x_field:
    semantic_type: viz.encoding.field
    token_mapping: tokenMap(viz.encoding.field)
    ui_hints:
      component: FieldReference
  viz_encoding_x_field_kind:
    semantic_type: viz.encoding.field_kind
    token_mapping: tokenMap(viz.encoding.field_kind)
    ui_hints:
      component: TextBadge
  viz_encoding_x_scale:
    semantic_type: viz.encoding.scale
    token_mapping: tokenMap(viz.scale.type)
    ui_hints:
      component: TextBadge
  viz_encoding_x_axis_title:
    semantic_type: viz.encoding.axis_title
    token_mapping: tokenMap(viz.axis.title)
    ui_hints:
      component: TextField
  viz_encoding_x_include_zero:
    semantic_type: viz.encoding.zero_baseline
    token_mapping: tokenMap(viz.scale.zero)
    ui_hints:
      component: BooleanBadge

view_extensions:
  detail:
    - component: VizAxisSummary
      position: sidebar
      props:
        intentParameter: renderIntent
        channel: x
        axis: x
        titleField: viz_encoding_x_axis_title
        scaleField: viz_encoding_x_scale
        zeroField: viz_encoding_x_include_zero
  form:
    - component: VizAxisControls
      position: top
      props:
        intentParameter: renderIntent
        channel: x
        axis: x
        fieldField: viz_encoding_x_field
        kindField: viz_encoding_x_field_kind
        scaleField: viz_encoding_x_scale
        titleField: viz_encoding_x_axis_title
        zeroField: viz_encoding_x_include_zero
        sortField: viz_encoding_x_sort

  list:
    - component: VizEncodingBadge
      props:
        intentParameter: renderIntent
        channel: x
        axis: x
        fieldField: viz_encoding_x_field

tokens:
  viz.encoding.x.axis.title: "var(--cmp-text-strong)"
  viz.encoding.x.axis.tick: "var(--cmp-viz-axis-tick)"
  viz.encoding.x.axis.line: "var(--cmp-viz-axis-line)"

dependencies:
  - ScaleLinear
  - trait: ScaleTemporal
    optional: true

metadata:
  created: "2025-11-15"
  updated: "2026-02-28"
  owners:
    - viz@oods.systems
    - engineering@oods.systems
  maturity: alpha
  accessibility:
    rule_reference: A11Y-R-05
    notes: Provide axis titles + descriptions for assistive tech fallbacks.
  regionsUsed:
    - detail
    - form
    - list
  allows:
    - MarkBar
    - MarkLine
    - MarkPoint
    - MarkArea
  references:
    - RDS.7 Trait-Driven Visualization System Specification (v0.1)
```