Addressable

trait:
  name: Addressable
  version: 1.0.0
  description: |
    Canonical multi-role address trait with validation metadata, geocoding, and international formatting hooks.
    Provides a single, reusable capability for billing, shipping, warehouse, and office addresses.
  category: core
  tags:
    - address
    - location
    - validation
    - delivery

parameters:
  - name: roles
    type: string[]
    required: true
    description: Ordered list of supported address roles (billing, shipping, warehouse, etc.).
    default:
      - billing
      - shipping
    validation:
      minItems: 1
      maxItems: 16
      uniqueItems: true
      items:
        pattern: "^[a-z0-9._-]+$"
        minLength: 2
        maxLength: 32
  - name: defaultRole
    type: string
    required: false
    description: Preferred role returned when consumers omit a role argument.
    validation:
      enumFromParameter: roles
  - name: allowDynamicRoles
    type: boolean
    required: false
    description: Allow runtime creation of roles that are not pre-declared in roles.
    default: false

schema:
  address_roles:
    type: string[]
    required: true
    description: Ordered list of roles that currently have address entries.
    default: []
  default_address_role:
    type: string
    required: false
    description: Role surfaced in UI contexts when one address must be highlighted.
    validation:
      enumFromParameter: roles
  addresses:
    type: AddressableEntry[]
    required: false
    description: Collection of { role, address, metadata } entries keyed by role.
    default: []

semantics:
  addresses:
    semantic_type: location.address.collection
    token_mapping: tokenMap(location.address.collection)
    ui_hints:
      component: AddressCollection
      roleParameter: roles
      defaultRoleField: default_address_role
  default_address_role:
    semantic_type: location.address.default_role
    token_mapping: tokenMap(location.address.default_role)
    ui_hints:
      component: AddressRoleBadge
      parameterSource: defaultRole
  address_roles:
    semantic_type: location.address.roles
    token_mapping: tokenMap(location.address.roles)
    ui_hints:
      component: AddressRolePills

view_extensions:
  list:
    - component: AddressSummaryBadge
      position: after
      props:
        field: default_address_role
  detail:
    - component: AddressCollectionPanel
      position: main
      priority: 60
      props:
        field: addresses
        roleField: address_roles
        defaultRoleField: default_address_role
        roleParameter: roles
  form:
    - component: AddressEditor
      position: top
      props:
        field: addresses
        roleParameter: roles
        allowDynamicParameter: allowDynamicRoles
        defaultRoleField: default_address_role

tokens:
  location.address.card.bg: "var(--sys-surface-raised)"
  location.address.card.border: "var(--sys-border-subtle)"
  location.address.role.text: "var(--sys-text-muted)"

dependencies: []

metadata:
  created: "2025-11-17"
  owners:
    - core@oods.systems
    - platform@oods.systems
  maturity: experimental
  accessibility:
    keyboard: "AddressEditor respects standard focus order and announces role changes."
    screenreader: "AddressCollection surfaces headings per role and announces validation status."
  regionsUsed:
    - list
    - detail
    - form
  examples:
    - User
    - Organization
  references:
    - "R21.1 Canonical Model for Address/Location Systems"