data-display — wyrd.component.carousel

Carousel

Manual single-slide carousel with controlled or uncontrolled selection and accessible navigation controls.

Install @wyrd-company/react or the Flutter package and use it directly — your DESIGN.md does the styling.

catalog/contracts/carousel.yml source of truth · verbatim

$schema: https://thewyrdingway.dev/schemas/component-contract.schema.ymlcontractVersion: 0.1.0identity:  name: Carousel  tag: wyrd-carousel  package: wyrd.component.carousel  title: Carousel  summary: Manual single-slide carousel with controlled or uncontrolled selection and accessible navigation controls.relationships:  related-to:    - quality-parity-and-gates    - l10n-formatting-runtimeclassification:  category: data-display  composition: collection  interactive: truetarget-strategy:  react: required  flutter: requiredsurface:  properties:    - name: label      type:        kind: string      required: true      serializable: true      summary: Accessible name for the carousel region.    - name: value      type:        kind: string      required: false      controlled: true      serializable: true      summary: Controlled active slide value.    - name: default-value      type:        kind: string      required: false      serializable: true      summary: Initial uncontrolled active slide value; the first enabled item is used when absent.    - name: items      type:        kind: array        item:          kind: object          fields:            value:              kind: string            label:              kind: string            disabled:              kind: boolean      required: false      default: []      serializable: true      summary: Ordered slides; disabled slides remain mounted but are skipped by navigation.    - name: loop      type:        kind: boolean      required: false      default: false      reflects: true      serializable: true      summary: Allows previous and next navigation to wrap between the first and last enabled slides.  slots:    - name: content      content: true      required: true      cardinality: one-or-many      accepts:        - component        - content      summary: Index-matched slide content; the Nth child belongs to the Nth item.  events:    - name: value-change      payload:        value:          kind: string      bubbles: true      composed: true      cancelable: false      summary: Emitted when manual navigation activates a different enabled slide.  states:    - name: default      source: platform      summary: One slide is active and manual controls are available.    - name: active      source: property      summary: Active slide state derived from value or default-value.    - name: boundary      source: property      summary: A non-looping carousel is at its first or last enabled slide.    - name: focus-visible      source: platform      summary: Keyboard-visible focus on a navigation control.  parts:    - name: root      summary: Named carousel region.      slots:        - content    - name: viewport      summary: Visible slide viewport.    - name: slide      summary: Repeated index-matched slide container.      slots:        - content    - name: controls      summary: Previous, position, and next control row.    - name: previous      summary: Previous-slide button.    - name: position      summary: Localized active slide position.    - name: next      summary: Next-slide button.  tokens:    root:      gap: spacing.sm    viewport:      background: color.surface      foreground: color.on-surface      radius: rounded.md    control:      background: color.surface      foreground: color.on-surface      hover-background: color.secondary      radius: rounded.sm      padding-x: spacing.md      padding-y: spacing.sm    position:      foreground: color.on-surface-variant      text: typography.label-mdmessages:  - key: carousel.previous    description: Accessible label for moving to the previous slide.  - key: carousel.next    description: Accessible label for moving to the next slide.  - key: carousel.position    description: Announces the active slide position and total slide count.    params:      current: number      total: numberobligations:  accessibility:    role: region    name: Label property provides the carousel region's accessible name.    keyboard:      - Tab reaches the previous and next buttons in document order.      - Enter and Space activate a focused navigation button.      - ArrowLeft and ArrowRight move to the spatially previous and next enabled slides while focus is within the carousel.      - Spatial arrow direction reverses in right-to-left text direction.    semantics:      - Web projections expose a named region with aria-roledescription=carousel and each slide as a group with aria-roledescription=slide.      - Each slide uses its item label when present, otherwise the localized position message.      - Inactive slides stay mounted but are hidden visually and from assistive technology.      - Previous and next controls expose component-owned localized names and disabled boundary state.      - Flutter exposes an equivalent named container, active slide label, and button semantics.  behavior:    model: collection    interactions:      - value ?? default-value ?? first enabled item determines the active slide.      - Manual button and arrow-key navigation skips disabled slides.      - Navigation stops at boundaries unless loop is true.      - Carousel never advances automatically in v1.      - All slide children remain mounted so slide-local state survives navigation.    hostEffects:      - Dispatch value-change when manual navigation activates a different slide.      - Format component-owned previous, next, and position messages through the l10n runtime.  conditions:    - rtl    - reduced-motion    - cvd-deuteranopia    - density-compact    - text-expansion  sdui:    status: serializable    serializableProperties:      - label      - value      - default-value      - items      - loop    serializableSlots:      - content    eventBindings:      - value-change    notes: Carousel serializes ordered items and index-matched slide content; hosts preserve order and keep all slides mounted.examples:  - name: product-tour    state: active    properties:      label: Product tour      default-value: foundations      items:        - value: foundations          label: Foundations        - value: components          label: Components        - value: tooling          label: Tooling    slots:      content:        - Semantic foundations.        - Cross-target components.        - Authoring and validation tooling.  - name: looping    state: active    properties:      label: Featured components      default-value: date-time-picker      loop: true      items:        - value: date-time-picker          label: Date and time picker        - value: graph-viewer          label: Graph viewer    slots:      content:        - Locale-aware segmented entry and calendar selection.        - Read-only exploration of typed behavior graphs.  - name: disabled-slide    state: boundary    properties:      label: Release readiness      items:        - value: stable          label: Stable        - value: blocked          label: Blocked          disabled: true        - value: planned          label: Planned    slots:      content:        - Available to downstream applications.        - Waiting for a required runtime capability.        - Accepted for a future catalog increment.overrides:  react:    slots:      content: children  flutter:    slots:      content: child

Examples

Generated from the contract's examples block. Previews are the published @wyrd-company/react component, themed by the brand's role tokens — flip the site's light/dark toggle and they follow.

Code target React Flutter Applies to every example on component pages.

product-tour state: active

Usage

import { WyrdCarousel } from "@wyrd-company/react";

<WyrdCarousel label="Product tour" defaultValue="foundations" items={[{"value":"foundations","label":"Foundations"},{"value":"components","label":"Components"},{"value":"tooling","label":"Tooling"}]}>
  Semantic foundations.
  Cross-target components.
  Authoring and validation tooling.
</WyrdCarousel>

// events: onValueChange

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdCarousel(
  label: 'Product tour',
  initialValue: 'foundations',
  items: [{"value":"foundations","label":"Foundations"},{"value":"components","label":"Components"},{"value":"tooling","label":"Tooling"}],
  child: Text('Semantic foundations. Cross-target components. Authoring and validation tooling.'),
)

// events: onChanged

looping state: active

Usage

import { WyrdCarousel } from "@wyrd-company/react";

<WyrdCarousel label="Featured components" defaultValue="date-time-picker" loop items={[{"value":"date-time-picker","label":"Date and time picker"},{"value":"graph-viewer","label":"Graph viewer"}]}>
  Locale-aware segmented entry and calendar selection.
  Read-only exploration of typed behavior graphs.
</WyrdCarousel>

// events: onValueChange

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdCarousel(
  label: 'Featured components',
  initialValue: 'date-time-picker',
  loop: true,
  items: [{"value":"date-time-picker","label":"Date and time picker"},{"value":"graph-viewer","label":"Graph viewer"}],
  child: Text('Locale-aware segmented entry and calendar selection. Read-only exploration of typed behavior graphs.'),
)

// events: onChanged

disabled-slide state: boundary

Usage

import { WyrdCarousel } from "@wyrd-company/react";

<WyrdCarousel label="Release readiness" items={[{"value":"stable","label":"Stable"},{"value":"blocked","label":"Blocked","disabled":true},{"value":"planned","label":"Planned"}]}>
  Available to downstream applications.
  Waiting for a required runtime capability.
  Accepted for a future catalog increment.
</WyrdCarousel>

// events: onValueChange

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdCarousel(
  label: 'Release readiness',
  items: [{"value":"stable","label":"Stable"},{"value":"blocked","label":"Blocked","disabled":true},{"value":"planned","label":"Planned"}],
  child: Text('Available to downstream applications. Waiting for a required runtime capability. Accepted for a future catalog increment.'),
)

// events: onChanged

Properties

Name	Type	Default	Summary
`label`	`string`	`undefined`	Accessible name for the carousel region.
`value`	`string`	`undefined`	Controlled active slide value.
`default-value`	`string`	`undefined`	Initial uncontrolled active slide value; the first enabled item is used when absent.
`items`	`array`		Ordered slides; disabled slides remain mounted but are skipped by navigation.
`loop`	`boolean`	`false`	Allows previous and next navigation to wrap between the first and last enabled slides.

Slots & events

Slot	Cardinality	Accepts	Summary
`content`	one-or-many	`component, content`	Index-matched slide content; the Nth child belongs to the Nth item.

Event	Payload	Summary
`value-change`	`value`	Emitted when manual navigation activates a different enabled slide.

Tokens

The contract's token bindings. Open the shared contextual sidebar from any example; primary swatches reflect the color you pick there. Error swatches show the active preset's values; editing any knob switches to custom and resets error to TWW · Ink.

Binding	Token
`root.gap`	`spacing.sm`
`viewport.background`	`color.surface`
`viewport.foreground`	`color.on-surface`
`viewport.radius`	`rounded.md`
`control.background`	`color.surface`
`control.foreground`	`color.on-surface`
`control.hover-background`	`color.secondary`
`control.radius`	`rounded.sm`
`control.padding-x`	`spacing.md`
`control.padding-y`	`spacing.sm`
`position.foreground`	`color.on-surface-variant`
`position.text`	`typography.label-md`

States

State	Source	Summary
`default`	platform	One slide is active and manual controls are available.
`active`	property	Active slide state derived from value or default-value.
`boundary`	property	A non-looping carousel is at its first or last enabled slide.
`focus-visible`	platform	Keyboard-visible focus on a navigation control.

SDUI

Status: serializable. Carousel serializes ordered items and index-matched slide content; hosts preserve order and keep all slides mounted.

Serializable	Members
Properties	`label, value, default-value, items, loop`
Slots	`content`
Events	`value-change`

  The Wyrding Way — a contract-first design system. © Wyrd Company 
   Pipeline demo
 Choose an example to inspect its pipeline context.
 Explore the shape of a brand's pipeline input: presets and knobs regenerate the illustrative excerpt below — not a compilable DESIGN.md (see the format reference). Primary swatches update live; accent, shape, density, and ground are excerpt-only; error swatches are preset-derived until any edit switches to custom (TWW · Ink errors). Component previews use the published brand package and the site's light/dark toggle.
 
  Start from
       
 * homages — shown for range, not affiliation.
 
  Tokens
 Primary updates live swatches. Accent, shape, density, and ground appear in the excerpt only. Error swatches follow the preset until you edit a knob — then they reset to TWW · Ink.
  color.primary   #26221A    color.accent   #9C7C14    rounded.md   2px    density   1.0×    ground     
 
   DESIGN.md excerpt illustrative

Examples

Properties

Slots & events

Tokens

States

Accessibility

SDUI