Component Behavior Definitions & Hooks

[cjpillsbury]

Component Behavior Pattern

Executive Summary

Video.js 10 uses behavior hooks (useXAttrs) to transform component state into rendered DOM props and attributes. This transformation layer defines a component's semantic identity: paused: true becomes data-paused="" (for CSS styling) and aria-label="play" (for accessibility).

Key outputs: data-attributes (styling selectors), ARIA properties (accessibility), CSS variables (dynamic styling), and other DOM props (tabIndex, className, etc.). Event handlers and tooltip/label derivation are still being explored.

Open architectural questions: Should behavior hooks share actual code across frameworks or just patterns? How should event handlers be named and exposed? Who owns tooltip label derivation? How does i18n integrate?

Note on maturity: This architecture is in early exploration. The document presents transformation patterns, code sharing strategies, and tradeoffs rather than prescribing specific implementations.

---

Overview: The Component Identity Layer

Behavior hooks define what a component is and does, independent of how it's rendered or which framework presents it. While component state definitions act as a "lens" into the media store (selecting relevant media state), behavior hooks describe the component's own semantics and identity.

This is the first architectural abstraction focused on the component itself rather than its relationship to media state. A play button is a toggle-like button with play/pause semantics—this is true whether rendered in React, HTML, or React Native.

The Abstraction

Component state (from state definitions + hooks):

• What media state matters? (paused, volume, currentTime)
• What actions can be triggered? (requestPlay, requestSeek)
• Concern: Media state → component data (the lens)

Component behavior (from behavior hooks):

• What is this component's role? (button, slider)
• What are its accessibility semantics? (ARIA labels, values, states)
• What styling selectors does it expose? (data-attributes, CSS variables)
• How does it respond to interaction? (event handlers)
• Input: Component state + user-provided props (for customization/overrides)
• Concern: Component identity → framework/platform representation

The Transformation Flow

Media Store
    ↓
Component State (Definition + Hook) ← Lens into media state
    ↓ (media-relevant state + actions)
Behavior Hook (useXAttrs) ← Component identity layer
    ↓ (role, ARIA, data-attrs, handlers - what the component IS)
Render Function ← Framework-specific presentation
    ↓ (JSX, DOM, native components - HOW it looks)

Key insight: Behavior hooks bridge between "what the component needs from media" (state definitions) and "how the component is presented" (render functions). They describe the component's essential nature—its semantic identity—in a framework-agnostic way.

Why this layer exists:

• Accessibility: State alone isn't enough—need ARIA properties, semantic roles, labels. A key architectural principle: behavior hooks own accessibility so themes and consumers cannot break WCAG compliance.
• Styling: CSS needs selectors (data-attributes, CSS variables) to style based on state
• Interaction: DOM props (tabIndex, event handlers) enable user interaction
• Framework independence: Same component identity expressed differently per platform (DOM attributes vs React Native a11y props)
• SSR/Hydration: Synchronous attribute computation could enable deterministic server-side rendering and HTML streaming. Full SSR support depends on media store state propagation patterns (see Component State Pattern)

---

Behavior Hook Architecture: Code Sharing Strategy

A fundamental architectural question: Should behavior hooks share actual code across frameworks, or just share patterns and conventions?

Three Approaches Under Consideration

1. Shared Definitions

Framework-agnostic behavior hook definitions used by all platforms.

Conceptual example:

// @videojs/core/behaviors/play-button.ts
export const playButtonBehavior = {
  deriveAttrs: (state, props) => ({
    role: 'button',
    'aria-label': state.paused ? 'play' : 'pause',
    'data-paused': state.paused,
  }),
};

// React and HTML both use the same definition
const attrs = playButtonBehavior.deriveAttrs(state, props);

When this works: Simple components (buttons) where React and HTML behavior is nearly identical.

When this breaks down: Complex components with DOM-specific requirements (refs, callbacks), platform-specific APIs (React Native a11y props vs. DOM ARIA), framework idioms (hooks vs. mixins).

2. Shared Abstractions, Framework-Specific Definitions

Common patterns and conventions, separate implementations per framework.

Conceptual example:

// React version
function usePlayButtonAttrs(props, state) {
  return { role: 'button', 'aria-label': state.paused ? 'play' : 'pause', ...props };
}

// HTML version - same pattern, separate code
function usePlayButtonAttrs(props, state) {
  return { role: 'button', 'aria-label': state.paused ? 'play' : 'pause' };
}

Benefits: Each framework uses idiomatic patterns, no impedance mismatch.

Cost: Duplication—same logic written multiple times.

3. Hybrid: Sometimes Shared, Sometimes Not

Flexible approach based on component complexity and framework compatibility.

When to share:

• Simple ARIA derivation utilities
• Time/volume formatting functions
• Components where behavior is truly identical (simple buttons)
• Parts of compound component behavior (shared calculations)

When framework-specific:

• Complex compound components with DOM-specific requirements
• Platform-specific adaptations (React Native a11y props differ from DOM ARIA)
• Framework idioms (React hooks vs. Web Component mixins)

Sharing strategies:

• Partial sharing: Share utilities (formatTime, naming conventions), write framework-specific hooks
• Selective sharing: Some components share definitions, others use framework-specific implementations
• Platform grouping: Group by similarity (e.g., React + HTML for DOM ARIA, React Native separate for platform-specific a11y props)

Evaluating Against Goals

Code Size

Shared definitions: Potentially smaller if truly reused, but abstraction overhead can negate savings.

Framework-specific duplication: Unlikely developers use both React and HTML together, so duplication doesn't increase real-world bundle size. Small utility functions (case conversion like tabindex → tabIndex, class → className) add negligible overhead and may simplify architecture.

Consideration: Don't over-optimize for "statistical noise" code size. Prioritize clarity and maintainability unless bloat is significant.

Maintainability

Shared definitions: Single source of truth—fix once, fixed everywhere. But: harder to reason about (where/how does this run?), harder to predict what changes affect which platforms.

Framework-specific: Clear ownership, easier to understand what code does. But: must update in multiple places, risk of divergence.

AI/LLM context: Tests (unit, integration, regression) catch divergence. AI tools can help propagate changes across implementations. With small teams and AI assistance, duplication may be acceptable if it improves code clarity.

Consideration: Small teams need code that's easy to reason about. Complex abstractions can be harder to maintain than clear duplication with good tests.

Extensibility/Customization

Shared definitions: Users must understand the abstraction layer to customize. Override mechanisms must work across frameworks.

Framework-specific: Users customize using framework-native patterns. Want custom ARIA in React? Override the hook. Want custom behavior in Web Components? Extend the class. No need to understand cross-framework abstractions.

Customization scenario: User wants VJS's A11Y and i18n but with different UI. Framework-specific definitions let them extend using familiar patterns (React hooks, Web Component inheritance). Shared definitions require understanding the abstraction boundary and how to plug in across frameworks.

Consideration: Framework-native patterns may be more approachable for developers extending/customizing components.

Current State & Open Questions

Prototype approach: Framework-specific definitions with shared patterns. Simple components (buttons) have nearly identical code across React and HTML. Complex components may diverge based on framework-specific requirements.

As architecture evolves, the sharing strategy may shift based on:

• How much actual divergence emerges between React and HTML implementations
• Whether React Native follows React patterns (likely) or needs unique approaches
• Whether abstraction overhead justifies maintainability benefits
• What patterns prove to be truly common vs. framework-idiomatic
• Developer feedback on customization and extension experiences

This decision affects: Codebase organization, maintenance burden, customization patterns, and the learning curve for contributors and consumers extending Video.js.

---

Core Transformations

The following sections describe common transformation patterns found in behavior hooks. These are illustrative examples of how component state maps to DOM semantics, not prescriptive requirements.

1. State → data-attributes

Purpose: Provide styling selectors for CSS attribute selectors.

Typical patterns: Boolean state as presence/absence (data-paused), enum state as attribute values (data-volume-level="low"), numeric state as stringified values.

Example: paused: true → data-paused="", volumeLevel: 'low' → data-volume-level="low"

Animation states: Some explorations include exposing animation/transition state attributes (e.g., data-state="open|closed", data-starting-style, data-ending-style, data-direction="ltr|rtl") to enable CSS transitions, keyframes, and JS animation libraries like Framer Motion or React Native Reanimated.

Framework differences: React uses empty string '' for boolean presence; HTML uses truthy/falsy with setAttribute.

2. State → ARIA Properties

Purpose: Enable screen readers and assistive technologies to understand component purpose and state.

Typical patterns: role (component type), aria-label (state-dependent accessible name), aria-valuemin/max/now/text (for sliders), aria-orientation (directional components).

Button example: paused: true → role="button", aria-label="play"

Slider example: volume: 0.5 → role="slider", aria-valuenow="50", aria-valuetext="50%"

Framework differences: None—ARIA properties are identical across platforms.

3. State → Tooltips/Labels (Open Question)

Purpose: Provide human-readable feedback about component state and available actions.

Open architectural questions:

• Should tooltip label derivation be owned by the component, by a component-specific tooltip, or by a "smart" tooltip component?
• If component-owned, does this belong in behavior hooks or elsewhere?
• How does i18n integration affect this?

Current prototype: Components may set data-tooltip attributes (e.g., data-tooltip="Play" when paused), but ownership and patterns are still being explored.

4. State → CSS Variables

Purpose: Enable dynamic styling without JavaScript. Used primarily for sliders and components with dynamic visual properties.

Typical pattern: Computed percentages for fill/pointer positions.

Example: fillWidth: 50 → --slider-fill: "50%", pointerWidth: 0.5 → --slider-pointer: "50%"

Framework differences: React uses style objects; HTML uses element.style.setProperty().

5. Other DOM Props

Purpose: Standard DOM properties for interaction and presentation.

Typical patterns: tabIndex (keyboard navigation), className/class (styling), aria-disabled (disabled state), user-provided prop spreading (overrides).

Example: Interactive component → tabIndex="0", disabled → aria-disabled="true" + tabIndex="-1"

Framework differences: React uses className, HTML uses class; otherwise conceptually identical.

6. State → Event Handlers (Open Question)

Purpose: Define how components respond to user interaction (clicks, pointer events, keyboard).

Architectural question: Should behavior hooks define event handlers, and if so, how?

Three Approaches Under Consideration

A. Semantic callbacks (framework-agnostic):

const behaviorDef = {
  // ...
  // Generic semantic names
  callbacks: {
    onButtonPress: () => state.requestPlay(),
  }
}

Pros: Framework-agnostic contract, clear semantics

Cons: Burden on render layer to map onButtonPress → onClick/onPointerUp/etc. Harder to share across frameworks.

B. Framework-specific callbacks:

const behaviorDef = {
  // ...
  // DOM-specific names
  callbacks: {
    onClick: () => state.requestPlay(),
    onPointerDown: () => handlePointerDown(),
    onPointerUp: () => handlePointerUp(),
  }
}

Pros: Directly spreadable in React and similar frameworks

Cons: Less intuitive for customization—developers may add their own onMouseDown and be confused when onPointerDown also fires. Debugging which handlers are active becomes harder.

C. Defer event handlers (current):

// No event handlers in behavior hooks
// Render functions handle events directly

Pros: Avoids premature decisions, treats handlers as one-offs for now (mainly needed for compound components), no assumptions about naming or sharing

Cons: Eventually may need a strategy as patterns emerge

Current state: Prototype primarily handles events in render functions. Event handler patterns in behavior hooks are being deferred until clear use cases and conventions emerge.

---

How This Achieves Architectural Goals

The behavior hook layer contributes to Video.js's architectural goals, though the specific implementation strategy (shared code vs. shared patterns) affects how these goals are realized.

Use Cases - Simple to Complex

The transformation pattern scales from simple (buttons with basic ARIA and data-attributes) to complex (interactive components with CSS variables, value formatting, orientation handling). Whether this scaling is achieved through shared code or consistent patterns across frameworks is still being explored.

Platform Permutations

Pattern consistency: React and HTML behavior hooks follow identical transformation patterns—same component state produces the same semantic meaning (ARIA roles, data-attributes, etc.), even if the mechanism differs (prop objects vs. setAttribute).

Implementation strategy open question: Whether transformation logic is actually shared (utilities, common code) or just conceptually aligned (same patterns, separate implementations) depends on the code sharing strategy discussion above.

Resilience

Clear layer separation: Behavior transformation is independent of state selection (component state definitions) and independent of rendering (render functions). Can refactor any layer without affecting others.

Override-friendly: Behavior hooks receive user-provided props for customization. Props spread pattern allows consumers to override derived props (e.g., custom aria-label). Framework adapters can extend or replace behavior hooks for custom behavior.

Customization

Framework-native customization: Developers override or extend behavior hooks using their framework's patterns:

// Custom play button with different ARIA label
function getCustomPlayButtonProps(props, state) {
  const baseProps = getPlayButtonProps(props, state);
  return {
    ...baseProps,
    'aria-label': state.paused ? 'Start playback' : 'Stop playback',
  };
}

Or provide props at component instance level:

<PlayButton aria-label="Play video" /> // Overrides default

---

Framework Integration

Behavior hooks return prop/attribute objects that must be applied by framework adapters. The integration patterns and challenges are similar to those for component state definitions.

React/React Native: Hooks provide reactivity—behavior hooks return props, React's rendering system automatically applies them when state changes.

HTML/Web Components: Require explicit subscription management and manual DOM updates—behavior hooks return attributes, adapter must subscribe to state changes and call update methods.

For detailed discussion of framework integration patterns, subscription strategies, and HTML/Web Component challenges, see the Component State Pattern discussion.

---

Open Questions & Future Directions

1. i18n integration: How should tooltip/label text be localized? Centralized registry? Per-component overrides? Context-based?

2. Attribute override patterns: Should user props override derived props or vice versa? Currently inconsistent (spread before vs. after).

3. Formatting logic location: Should time/volume formatting live in behavior hooks, core utilities, or separate formatting layer?

4. Shared utilities vs. duplication: How much transformation logic should be extracted to shared utilities vs. duplicated between React/HTML for clarity?

5. CSS variable naming conventions: Should variable names be standardized across components or component-specific?

6. ARIA value text formatting: Should this use the same formatters as display text, or separate?

7. Default event handlers: Should behavior hooks provide default onClick/onKeyDown handlers, or leave entirely to render functions?

---

Connection to Component State Pattern

Behavior hooks are the next layer after component state definitions:

Component State Definition (core)
    ↓ Selects: ['paused']
    ↓ Transforms: { paused: true }
    ↓ Creates methods: { requestPlay, requestPause }
Behavior Hook (framework-specific)
    ↓ Derives semantic props: { role, aria-label, data-paused }
Render Function (framework-specific)
    ↓ Creates actual DOM/JSX

Separation of concerns:

• State definitions: What data does the component need?
• Behavior hooks: What does that data mean for the DOM?
• Render functions: How should the DOM be structured?

This layering enables independent evolution: can change how props are derived without touching state definitions, can change rendering without touching props derivation.

---

Influences & References

The behavior hook architecture and many of the concepts discussed in this document are influenced by discussions, documentation, and writeups from:

• Rahim Alwer (@mihar-22)
• Wesley Luyten (@luwes)

Framework References:

• React ARIA - Accessibility-first component behavior patterns
• Base UI - Component behavior abstractions, particularly behavior hooks like useButton

These influences have shaped the thinking around framework-agnostic behavior definitions, accessibility ownership, and the separation between component identity and presentation.