oem ^3.2.0

Abstract

OEM is an agent-first UI framework and toolkit engineered for human-AI collaboration. It provides a declarative syntax for composing reactive UIs in 100% TypeScript.

The following documentation describes the core concepts, libraries, and conventions of OEM. The sectsions in this document are normative unless otherwise specified.

GITHUB | NPM

Table of Contents

• Install
• Core Library

• Template - Core template engine for creating declarative and reactive UI applications
• State - Reactive event bus with publish-subscribe state management
• Util - Runtime helpers for working with State objects and Conditions

• Trait Library

• useScrollIntoViewTrait - Reactively scrolls an HTML element into view based on conditions
• useAnimationTrait - Applies Web Animations API keyframe animations to an HTML element with reactive state and condition support
• useDataAttributeTrait - Reactively sets data-* attributes on an HTML element via the dataset API
• useFocusTrait - Focuses an HTML element based on conditions
• useInputEventTrait - Handles input-related events on form elements
• useTextContentTrait - Sets the text content of an HTML element
• useAttributeTrait - Adds an attribute to an HTML element
• useStyleTrait - Applies CSS styles to an HTML element
• useInputValueTrait - Binds a value to an input or textarea element
• useEventTrait - Attaches event listeners to an HTML element
• useInnerHTMLTrait - Sets the innerHTML of an element with reactive children
• useAriaTrait - Reactively sets ARIA attributes and roles on an HTML element
• useClassNameTrait - Sets the class name of an HTML element
• useStyleOnEventTrait - Applies CSS styles to an element on a specific event

• State Library

• useUrlState - State Object to track the current URL in the application.
• useMediaQueryState - Reactive state for tracking media query matches based on viewport width and media type
• useThemeState - A simple State object of 'light' and 'dark'
• useOnlineState - Reactive state for tracking browser online/offline connectivity
• useWindowSizeState - Reactive state for tracking viewport width and height
• useTokenState - A simple State object to manage a single design token setting
• useIntersectionObserverState - Reactive state for tracking element visibility within the viewport
• useTimerState - Reactive interval-driven counter state with start, stop, and reset controls
• useFormState - Reactive form state with validation, dirty tracking, and field-level control

• Examples

• Theme Toggle Example - A theme toggle component built with OEM.
• Dynamic List Example - A dynamic list component built with OEM.
• Counter Example - A simple counter component built with OEM.
• Conditional Styling Example - A conditional styling component built with OEM.

Install

To get started with OEM, install the package from npm:

npm install @linttrap/oem

Quick Example

// define a template engine
const [tag, trait] = Template({
  style: useStyleTrait,
  event: useEventTrait,
  text: useTextTrait,
})

// define state
const count = State(0);

// define your dom
const counter = tag.div(
  trait.style('display', 'flex'),
  trait.style('alignItems', 'center'),
  trait.style('gap', '16px'),
  tag.span(
    trait.text(count.$val),
    trait.style('fontSize', '48px'),
    trait.style('fontWeight', '700'),
    trait.style('color', '#555555'),
  ),
  tag.button(
    trait.text('+'),
    trait.event('click', count.$reduce((n) => n + 1)),
    trait.style('fontSize', '24px'),
  ),
);

// that's it! You just defined: behavior, state, and presentation in one cohesive block of code. 

Core Library

Template

Overview

The template module allows you to create your own template engine. It is the core mechanism that supports OEM's unique approach to declarative, reactive applications that combine HTML, Styling, Logic and Behavior.

Key Exports

Template<P>

• Type: Function
• Signature: function Template<P extends Record<string, TemplateTraitFunc>>(config?: P): TemplateReturnType<P>
• Description: Creates a tuple of [tagProxy, traitProxy] for element creation and trait application
• Parameters:
  • config: Optional object mapping trait names to trait implementation functions
• Returns: A tuple [tagProxy, traitProxy] typically destructured as [tag, trait]
• Basic Example:

// Import Template and some traits from OEM
import { Template, useEventTrait, useTextContentTrait, useStyleTrait } from '@linttrap/oem';

// Create template and add traits
export const [tag, trait] = Template({
  event: useEventTrait,
  text: useTextContentTrait,
  style: useStyleTrait,
});

// Now you can generate elements with the tag proxy and apply available traits
const button = tag.button(
  trait.event('click', () => console.log('Clicked!')),
  trait.text('Click Me'),
  trait.style('backgroundColor', 'blue'),
);

Tag Proxy (First element of tuple)

• Type: Proxy object
• Description: Creates HTML or SVG elements using property access
• Usage: Access any valid HTML or SVG tag name as a property, which returns a function that creates that element

Supported Element Types

• HTML Elements: All standard HTML tags (div, span, button, input, etc.)
• SVG Elements: svg, g, rect, circle, ellipse, line, polyline, polygon, path, text, defs, use, mask, clipPath

Element Creation Function

• Signature: (...traits: Trait[]) => HTMLElement | SVGElement
• Parameters: Variable number of traits (TemplateTraitAppliers)
• Returns: The created element

Trait Proxy (Second element of tuple)

• Type: Proxy object
• Description: Creates trait applier functions from the config object
• Usage: Access trait names defined in config, which returns a function that creates a trait applier

Trait Applier Function

• Signature: (...args: Parameters<TraitFunc>) => (el: HTMLElement) => void
• Parameters: Arguments defined by the trait implementation (excluding the element parameter)
• Returns: A function that applies the trait to an element

Type Definitions

TemplateTraitFunc

• Type: Type alias
• Description: (...args: Args) => Return - Function type for trait implementations

TemplateTraitApplier

• Type: Type alias
• Description: (el: HTMLElement | SVGElement) => void - Function that applies a trait to an element

TemplateReturnType<P>

• Type: Type alias
• Description: Complex type defining the return value structure with proper TypeScript inference for element types

Implementation Details

Automatic Cleanup System

The template module uses a sophisticated cleanup system:

• WeakMap: Stores cleanup functions keyed by element reference
• MutationObserver: Watches for element removal from the DOM
• When an element is removed, all its cleanup functions are executed automatically
• This prevents memory leaks from event listeners and subscriptions

SVG Element Detection

SVG elements are created using createElementNS with the SVG namespace. The module maintains a hardcoded set of common SVG tag names for detection.

Traits

A trait is any function that takes an element as its first parameter, applies some behavior or configuration to it and returns a cleanup function. Traits can be defined in the config object passed to Template() and are accessed via the trait proxy.

Here's an example of the implementation of the Style Trait

export function useStyleTrait(
  el: HTMLElement,
  prop: keyof CSSStyleDeclaration | `--${string}`,
  val: (() => string | number | undefined) | (string | number | undefined),
  ...rest: (StateType<any> | Condition)[]
) {
  const states = extractStates(val, ...rest);
  const conditions = extractConditions(...rest);
  const apply = () => {
    const _val = typeof val === 'function' ? val() : val;
    const applies = conditions.every((i) => (typeof i === 'function' ? i() : i));
    if (applies) {
      (prop as string).startsWith('--')
        ? el.style.setProperty(prop as string, _val as string)
        : (el.style[prop as any] = _val as any);
    }
  };
  apply();
  const unsubs = states.map((state) => state.sub(apply));
  return () => unsubs.forEach((unsub) => unsub());
}

Conditional Patterns

IMPORTANT: OEM prescribes using explicit conditions rather than ternary expressions when applying traits.

Using Conditions (Preferred)

All traits accept ...rest: (StateType<any> | Condition)[] parameters. Use $test() from @/core/util to create conditions:

import { $test } from '@linttrap/oem';

// ✅ CORRECT: Use separate trait calls with conditions
trait.style('opacity', '0.6', $test(disabled)),
trait.style('opacity', '1', $test(!disabled)),

// ✅ CORRECT: Multiple conditions
trait.style('backgroundColor', 'red', $test(isError && !disabled)),

// ✅ CORRECT: Conditional event handlers
trait.event('click', handleClick, $test(!disabled)),

// ✅ CORRECT: Conditional attributes
trait.attr('disabled', 'true', $test(disabled)),

Note: State objects come with a built-in $test method that creates a condition based on the state value (e.g. state.$test(true) creates a condition that checks if the state value is true). See State.md for more details.

#### Avoiding Ternary Expressions (Anti-pattern)

```typescript
// ❌ INCORRECT: Do not use ternary expressions
trait.style('opacity', disabled ? '0.6' : '1'),

// ❌ INCORRECT: Do not use conditional spreads
...(!disabled ? [trait.event('click', handleClick)] : []),

// ❌ INCORRECT: Do not use inline conditionals
trait.style('color', isError ? 'red' : 'blue'),

How Conditions Work

Traits extract conditions using extractConditions() (see @/core/util) and only apply when all conditions evaluate to true:

1. Condition Creation: $test(value, expected = true) creates a condition that checks if value === expected
2. Condition Extraction: Traits filter rest parameters for objects with type === '$test'
3. Condition Evaluation: All conditions must pass for the trait to apply
4. Reactive Updates: When states change, conditions are re-evaluated

This pattern ensures:

• Clarity: Each condition is explicit and separate
• Reactivity: Conditions can re-evaluate when states change
• Composability: Multiple conditions can be combined
• Type Safety: TypeScript can properly type-check each branch

State

Overview

The state function is an an event bus with reactive state management convention used by the OEM framework. It implements a publish-subscribe pattern with support for reducing, testing and augmenting with custom methods. State is designed to be simple and flexible, allowing you to manage reactive data in your applications without the overhead of more complex state management libraries.

Purpose

State solves the problem of managing reactive data in applications where UI components need to automatically update when data changes. It provides a lightweight alternative to more complex state management libraries, with built-in support for:

• Reactive subscriptions
• State transformations
• Predicate testing
• Deferred execution patterns

Use this module when you need to manage any state, especially with reactive data binding between your application state and UI components. State objects should live outside of function components to ensure they are shared across the application and not recreated on each render.

Key Exports

State<T, M>

• Type: Function
• Signature: function State<T, M>(param: T, customMethods?: M): StateType<T, M>
• Description: Creates a reactive state container that holds a value and notifies subscribers when it changes. Optionally accepts custom methods to extend state behavior.
• Parameters:
  • param: The initial value for the state
  • customMethods (optional): An object containing custom methods that receive the state object as their first parameter
• Returns: A StateType<T, M> object with methods for state management
• Usage Example:

// Basic usage
const count = State(0);
count.sub((value) => console.log('Count changed:', value));
count.set(5); // Logs: "Count changed: 5"

// With custom methods
const counter = State(
  { count: 0 },
  {
    increment: (state) => {
      state.reduce((prev) => ({ count: prev.count + 1 }));
    },
    incrementBy: (state, amount: number) => {
      state.reduce((prev) => ({ count: prev.count + amount }));
    },
  },
);

counter.increment(); // Increments count by 1
counter.incrementBy(5); // Increments count by 5
counter.$increment()(); // Deferred increment

Note: the $-prefixed methods (e.g. $increment) are automatically generated for each custom method and return a closure that can be used for deferred execution, such as in event handlers.

StateType<T>

• Type: Interface/Type
• Description: The return type of State() function, providing methods for state manipulation and observation

Methods

val()

• Returns: The current state value
• Usage: const currentValue = count.val();

set(atom: T)

• Description: Sets a new state value and notifies all subscribers
• Parameters: atom - The new value to set

reduce(cb: (prev: T) => T)

• Description: Updates state based on the previous value
• Parameters: cb - A function that receives the current value and returns the new value
• Usage: count.reduce(prev => prev + 1);

sub(cb: (atom: T) => any)

• Description: Subscribes to state changes
• Parameters: cb - Callback function called with new value on each change
• Returns: An unsubscribe function
• Usage:

const unsub = count.sub((value) => console.log(value));
// Later: unsub() to stop listening

test(predicate, checkFor?)

• Description: Tests the current state value against a predicate
• Parameters:
  • predicate: A RegExp, value, or function to test against
  • checkFor: Optional boolean (default true) to invert the test result
• Returns: Boolean indicating if the test passed
• Usage:

const isZero = count.test(0); // true if count is 0
const isPositive = count.test((v) => v > 0);

Deferred Execution Methods ($ prefix)

Each core method has a dollar-prefixed version ($val, $set, $reduce, $test, $call) that returns a closure for deferred execution. These closures include:

• A sub property for subscribing to changes
• A type property identifying the closure type

Usage Example:

const getDouble = count.$reduce((prev) => prev * 2);
// Later: getDouble() executes the reduction

Custom Methods

State supports extending functionality with custom methods via the second parameter. Custom methods:

• Receive the state object as their first parameter
• Can accept additional parameters
• Have automatic deferred execution versions ($ prefix)
• Provide full TypeScript intellisense and type safety

Usage Example:

type CounterState = { count: number; name: string };

const counter = State<CounterState>(
  { count: 0, name: 'MyCounter' },
  {
    increment: (state) => {
      state.reduce((prev) => ({ ...prev, count: prev.count + 1 }));
    },
    incrementBy: (state, amount: number) => {
      state.reduce((prev) => ({ ...prev, count: prev.count + amount }));
    },
    reset: (state) => {
      state.set({ count: 0, name: state.val().name });
    },
    getDisplayText: (state) => {
      const { count, name } = state.val();
      return `${name}: ${count}`;
    },
  },
);

// Direct execution
counter.increment();
counter.incrementBy(5);
console.log(counter.getDisplayText()); // "MyCounter: 6"

// Deferred execution with $ prefix
const incrementBtn = document.querySelector('#increment');
incrementBtn.addEventListener('click', counter.$increment());

const addFiveBtn = document.querySelector('#add-five');
addFiveBtn.addEventListener('click', counter.$incrementBy(5));

Because custom methods take the state object as their first parameter, they have access to all state methods:

• state.val() - Get current value
• state.set(newValue) - Set new value
• state.reduce(cb) - Update based on previous value
• state.sub(cb) - Subscribe to changes
• state.test(predicate) - Test current value

Implementation Details

The state module uses a closure-based approach to maintain private state:

• Internal value is stored in _internalVal
• Subscribers are stored in a Set<(atom: T) => any>
• When state changes via set() or reduce(), all subscribers are notified synchronously

Gotchas

• There is no pub method; state updates are published automatically when using set() or reduce()
• Custom methods must use the provided state object parameter to manipulate state; they cannot directly access internal variables
• Deferred execution methods (with $ prefix) return closures that are syntactic sugar for traits. Traits use them to get the current state value and subscribe to changes. Each trait is responsible for implementing the logic to re-run when the state changes. This design allows for flexible reactive patterns without coupling state directly to UI components.

Util

Overview

The util module provides utility functions for working with State objects and Conditions in the OEM framework. It offers runtime helpers for filtering, testing, and extracting reactive objects from mixed arrays.

Purpose

Util solves the problem of identifying and working with OEM's special object types (State, Condition) at runtime. Key features include:

• Creating conditional closures for reactive testing
• Extracting State objects from mixed parameter arrays
• Extracting Condition objects from mixed parameter arrays

Use this module when you need to programmatically work with State or Condition objects, particularly when processing variable argument lists that may contain a mix of different types.

Key Exports

$test()

• Type: Function
• Signature: function $test(val: (() => any) | any, expected: any = true): Condition
• Description: Creates a conditional closure that tests a value against an expected result
• Parameters:
  • val: Either a function that returns a value, or a static value
  • expected: The expected value to compare against (default: true)
• Returns: A Condition function with a type property set to '$test'
• Usage Example:

// Test a static value
const isTrue = $test(true); // () => true === true

// Test a function result
const count = State(5);
const isPositive = $test(() => count.val() > 0, true);

// Use in conditional rendering
const element = h.div(isPositive && h.span('Count is positive'));

// Custom expected value
const isFive = $test(count.val, 5);

• Behavior:
  • If val is a function, it's called on each evaluation
  • If val is a static value, it's compared directly
  • Returns true if val === expected, false otherwise
  • The returned closure includes a type property for runtime identification

extractStates()

• Type: Function
• Signature: function extractStates(...rest: any): StateType<any>[]
• Description: Filters an array of mixed values to extract only State objects
• Parameters:
  • ...rest: Variable number of arguments of any type
• Returns: An array containing only the State objects from the input
• Usage Example:

const count = State(0);
const name = State('Alice');
const regularValue = 42;
const regularFunc = () => 'hello';

const states = extractStates(count, regularValue, name, regularFunc);
// states = [count, name]

// Use case: Subscribing to all states in a component
states.forEach((state) => {
  state.sub((value) => {
    console.log('State changed:', value);
  });
});

• Detection Logic: Checks if objects have a sub property (characteristic of State objects)
• Use Cases:
  • Component lifecycle management
  • Batch subscription to multiple states
  • Analyzing dependencies

extractConditions()

• Type: Function
• Signature: function extractConditions(...rest: any[]): Condition[]
• Description: Filters an array of mixed values to extract only Condition objects
• Parameters:
  • ...rest: Variable number of arguments of any type
• Returns: An array containing only the Condition objects from the input
• Usage Example:

const isVisible = $test(true);
const isEnabled = $test(() => count.val() > 0);
const regularValue = 42;
const regularFunc = () => 'hello';

const conditions = extractConditions(isVisible, regularValue, isEnabled, regularFunc);
// conditions = [isVisible, isEnabled]

// Use case: Evaluating all conditions
const allTrue = conditions.every((condition) =>
  typeof condition === 'function' ? condition() : condition,
);

• Detection Logic: Checks if objects have a type property equal to '$test'
• Use Cases:
  • Conditional rendering logic
  • Form validation
  • Feature flag evaluation
  • Access control checks

Implementation Details

Object Type Detection

Both extractStates and extractConditions use runtime property checking to identify objects:

• State detection: Uses Object.hasOwn(i, 'sub') to check for the subscription method
• Condition detection: Uses i.type === '$test' to check for the type marker

This approach relies on duck typing rather than instanceof checks, making it flexible but requiring consistent object shapes.

$test Closure Structure

The $test function returns a closure with:

• Function body: Performs the comparison logic
• Type property: Marker for runtime identification (type: '$test')
• This structure allows Conditions to be both executable and identifiable

Type Safety Considerations

• extractStates returns StateType<any>[], losing specific type information
• extractConditions returns Condition[]
• Both functions use any types internally for flexibility with mixed arrays
• Type information should be managed at the call site when possible

Trait Library

useScrollIntoViewTrait

Reactively scrolls an element into the visible area of its scrollable ancestor when conditions are met. Supports smooth and instant scrolling via standard ScrollIntoViewOptions.

Signature

useScrollIntoViewTrait(
  el: HTMLElement,
  options?: ScrollIntoViewOptions,
  ...rest: (StateType<any> | Condition)[]
) => () => void

Parameters

Behavior

1. Checks all Conditions — if all are truthy, calls el.scrollIntoView(options).
2. Subscribes to every State in rest so the trait re-evaluates on state changes.
3. Scrolls on initialization if conditions are met.

Returns

A cleanup function that unsubscribes from all State listeners.

Template Usage

// Scroll when an item becomes active
trait.scrollIntoView(
  { behavior: 'smooth', block: 'center' },
  activeItem.$test((id) => id === itemId),
);

// Scroll to error field on validation failure
trait.scrollIntoView(
  { behavior: 'smooth', block: 'start' },
  form.$test((f) => !!f.errors.email && f.touched.email),
);

// Always scroll into view on mount (no conditions)
trait.scrollIntoView({ behavior: 'instant', block: 'start' });

Common Patterns

Chat auto-scroll

const messages = State<Message[]>([]);

// Scroll the last message into view when messages change
tag.div(
  trait.scrollIntoView(
    { behavior: 'smooth', block: 'end' },
    messages.$test(() => true),
  ),
);

Anchor navigation

const activeSection = State<string>('intro');

// Each section scrolls into view when it becomes active
['intro', 'features', 'pricing'].forEach((id) => {
  tag.section(
    trait.scrollIntoView({ behavior: 'smooth', block: 'start' }, activeSection.$test(id)),
  );
});

Focus first error

const form = useFormState({ name: '', email: '' }, validators);

tag.input(
  trait.scrollIntoView(
    { behavior: 'smooth', block: 'center' },
    form.$test((f) => !!f.errors.name && f.touched.name),
  ),
);

Notes

• Uses the standard Element.scrollIntoView() API
• Scrolls every time conditions become truthy after a state change — not just on the first occurrence
• For one-time scroll (e.g., on mount), pass no states and the scroll will fire only on initialization
• Consider using { behavior: 'smooth' } for user-visible navigation and { behavior: 'instant' } for programmatic repositioning

useAnimationTrait

Reactively plays a Web Animations API keyframe animation on an element. Supports conditional gating, state-driven re-triggering, and automatic cleanup.

Signature

useAnimationTrait(
  el: HTMLElement,
  keyframes:
    | Keyframe[]
    | PropertyIndexedKeyframes
    | (() => Keyframe[] | PropertyIndexedKeyframes),
  options:
    | number
    | KeyframeAnimationOptions
    | (() => number | KeyframeAnimationOptions),
  ...rest: (StateType<any> | Condition)[]
) => () => void

Parameters

Behavior

1. Evaluates keyframes and options (calls them if they are functions).
2. Checks all Conditions — if all are truthy, plays the animation via el.animate().
3. If a previous animation from this trait instance is still running, it is cancelled before the new one starts.
4. Subscribes to every State in rest so the animation re-triggers on state changes.
5. When a condition is false, the animation is not played but any previously running animation is not cancelled — the trait only gates new plays.
6. Cleanup cancels any running animation and unsubscribes from all States.

Returns

A cleanup function that cancels the running animation and unsubscribes from all State listeners.

Template Usage

Fade-in on creation

trait.animation([{ opacity: '0' }, { opacity: '1' }], {
  duration: 200,
  easing: 'ease-out',
  fill: 'forwards',
});

Slide-in from below

trait.animation(
  [
    { opacity: '0', transform: 'translateY(8px)' },
    { opacity: '1', transform: 'translateY(0)' },
  ],
  { duration: 250, easing: 'ease-out', fill: 'forwards' },
);

Enter/exit driven by state

const mode = State<'enter' | 'exit'>('enter');

// Enter animation — plays when mode is 'enter'
trait.animation(
  [
    { opacity: '0', transform: 'scale(0.95)' },
    { opacity: '1', transform: 'scale(1)' },
  ],
  { duration: 200, easing: 'ease-out', fill: 'forwards' },
  mode.$test('enter'),
  mode,
);

// Exit animation — plays when mode is 'exit'
trait.animation(
  [
    { opacity: '1', transform: 'scale(1)' },
    { opacity: '0', transform: 'scale(0.95)' },
  ],
  { duration: 150, easing: 'ease-in', fill: 'forwards' },
  mode.$test('exit'),
  mode,
);

Infinite spinner

trait.animation([{ transform: 'rotate(0deg)' }, { transform: 'rotate(360deg)' }], {
  duration: 800,
  iterations: Infinity,
  easing: 'linear',
});

Reactive duration from state

const speed = State<number>(300);

trait.animation(
  [{ opacity: '0' }, { opacity: '1' }],
  () => ({ duration: speed.val(), easing: 'ease-out', fill: 'forwards' as FillMode }),
  speed,
);

Conditional animation (only when visible)

const visible = State<boolean>(false);

trait.animation(
  [{ opacity: '0' }, { opacity: '1' }],
  { duration: 200, fill: 'forwards' },
  visible.$test(true),
  visible,
);

Attention pulse

trait.animation(
  [{ transform: 'scale(1)' }, { transform: 'scale(1.05)' }, { transform: 'scale(1)' }],
  { duration: 600, easing: 'ease-in-out', iterations: 2 },
);

Performance Notes

• The Web Animations API runs animations on the compositor thread when animating transform and opacity, delivering 60fps performance without layout thrashing.
• Never animate layout properties (width, height, top, left, margin, padding) — they force reflow on every frame. Use transform: translate/scale instead.
• Prefer fill: 'forwards' when the element should retain its final animated state.
• For looping animations, always provide a cleanup path (state condition or element removal) to avoid orphaned infinite loops.

Accessibility

• Always respect prefers-reduced-motion. When the user has reduced motion enabled, either skip the animation entirely (via a condition tied to a media query state) or use duration: 0 to apply the final state instantly.

const reducedMotion = useMediaQueryState('(prefers-reduced-motion: reduce)');

trait.animation(
  [{ opacity: '0' }, { opacity: '1' }],
  () => ({ duration: reducedMotion.test(true) ? 0 : 200, fill: 'forwards' as FillMode }),
  reducedMotion,
);

useDataAttributeTrait

Reactively sets or removes data-* attributes on an element using the dataset API. Accepts either bare names (e.g. 'active') or prefixed names (e.g. 'data-active'). When the value is undefined or conditions are falsy, the data attribute is removed.

Signature

useDataAttributeTrait(
  el: HTMLElement,
  name: string,
  val: (() => string | number | boolean | undefined) | (string | number | boolean | undefined),
  ...rest: (StateType<any> | Condition)[]
) => () => void

Parameters

Behavior

1. Normalizes the name — adds data- prefix if missing, converts to camelCase dataset key.
2. Evaluates val (calls it if it's a function).
3. Checks all Conditions — if any are falsy, removes the data attribute.
4. If all Conditions pass and val is undefined, removes the data attribute.
5. Otherwise, sets el.dataset[key] = String(val).
6. Subscribes to every State in rest so the trait re-runs on state changes.

Returns

A cleanup function that unsubscribes from all State listeners.

Template Usage

// Static data attribute
trait.data('id', '42');
// → el.dataset.id = '42' (renders as data-id="42")

// With data- prefix (also works)
trait.data('data-id', '42');
// → same result

// Reactive value
trait.data('active-tab', () => activeTab.val(), activeTab);
// → el.dataset.activeTab = 'home' (renders as data-active-tab="home")

// Conditional data attribute
trait.data(
  'selected',
  'true',
  item.$test((i) => i.selected),
);

// Remove when undefined
trait.data('tooltip', () => tooltipText.val() || undefined, tooltipText);

Common Patterns

Track element state for CSS selectors

// Set data-state for CSS-based styling or external queries
trait.data('state', () => panelState.val(), panelState);
// → [data-state="open"], [data-state="closed"]

Wire up delegation targets

items.forEach((item) =>
  tag.li(
    trait.data('id', item.id),
    trait.event('click', (e) => {
      const id = (e.target as HTMLElement).dataset.id;
      selectItem(id);
    }),
  ),
);

Flag elements for testing

trait.data('testid', 'submit-button');

Comparison with useAttributeTrait

Notes

• Names are automatically normalized: 'active-tab' → dataset.activeTab → renders as data-active-tab
• Uses the dataset API for setting/removing, which is the idiomatic way to work with data attributes
• Removal uses delete el.dataset[key] which fully removes the attribute from the DOM

useFocusTrait

Programmatically focuses an HTML element. Unlike most traits, Focus accepts conditions and states as explicit arrays rather than using the rest-parameter extraction pattern.

Signature

useFocusTrait(
  el: HTMLElement,
  conditions?: Condition[],
  states?: StateType<any>[]
) => () => void

Parameters

Behavior

1. Checks all Conditions — if all are truthy, calls el.focus().
2. Subscribes to every State so the trait re-runs on state changes.
3. Useful for auto-focusing inputs when a modal opens, a route changes, or a condition becomes true.

Returns

A cleanup function that unsubscribes from all State listeners.

Template Usage

trait.focus([modalState.$test((s) => s.open)], [modalState]);
trait.focus([], [routeState]);

useInputEventTrait

Attaches an input-related event listener that extracts the value from e.target.value and passes it to a setter function. Designed for binding form element changes directly to state updates.

Signature

useInputEventTrait(
  el: HTMLElement,
  evt: 'input' | 'change' | 'keyup' | 'keydown' | 'keypress' | 'beforeinput' | 'paste' | 'cut' | 'compositionstart' | 'compositionupdate' | 'compositionend',
  setter: (val: any) => void,
  ...rest: (StateType<any> | Condition)[]
) => () => void

Parameters

Behavior

1. Checks all Conditions — if all are truthy and the listener is not attached, adds the event listener.
2. When the event fires, calls setter(e.target.value).
3. If any Condition becomes falsy, removes the listener.
4. Tracks attachment state to prevent duplicate listeners.
5. Subscribes to every State so the trait re-evaluates on state changes.

Returns

A cleanup function that removes the event listener and unsubscribes from all State listeners.

Template Usage

trait.inputEvent('input', nameState.set);
trait.inputEvent('change', (val) => filterState.set(val));
trait.inputEvent('keydown', searchState.set, enabled.$test(true));

useTextContentTrait

Sets the text content of an element reactively. Supports single values, arrays of values (concatenated as text nodes), and function getters.

Signature

useTextContentTrait(
  el: HTMLElement,
  text: TextContent | TextContent[] | (() => TextContent | TextContent[]),
  ...rest: (StateType<any> | Condition)[]
) => () => void

Where TextContent = string | number | undefined | unknown.

Parameters

Behavior

1. Clears el.textContent.
2. Evaluates text (calls it if it's a function).
3. Checks all Conditions — if any are falsy, the element remains empty.
4. For arrays: filters out undefined values and appends each as a text node.
5. For single values: sets el.textContent to the stringified value.
6. Subscribes to every State in rest so the trait re-runs on state changes.

Returns

A cleanup function that unsubscribes from all State listeners.

Template Usage

trait.textContent('Hello, World!');
trait.textContent(counter.$val);
trait.textContent(() => `${items.val().length} items`, items);

useAttributeTrait

Sets or removes an HTML attribute on an element reactively. When the value is undefined or conditions evaluate to false, the attribute is removed from the element.

Signature

useAttributeTrait(
  el: HTMLElement,
  prop: string,
  val: (() => string | number | boolean | undefined) | (string | number | boolean | undefined),
  ...rest: (StateType<any> | Condition)[]
) => () => void

Parameters

Behavior

1. Evaluates val (calls it if it's a function).
2. Checks all Conditions — if any are falsy, removes the attribute.
3. If all Conditions pass and val is undefined, removes the attribute.
4. Otherwise, sets the attribute via el.setAttribute(prop, String(val)).
5. Subscribes to every State in rest so the trait re-runs on state changes.

Returns

A cleanup function that unsubscribes from all State listeners.

Template Usage

When used through a Template's trait proxy, the el parameter is supplied automatically:

trait.attribute(
  'disabled',
  'true',
  formState.$test((s) => !s.isValid),
);
trait.attribute('aria-label', 'Close dialog');
trait.attribute(
  'data-active',
  'true',
  tabState.$test((s) => s.active === id),
  visible.$test(true),
);

useStyleTrait

Reactively sets a single CSS style property on an element. Supports both standard CSSStyleDeclaration properties and CSS custom properties (--*).

Signature

useStyleTrait(
  el: HTMLElement,
  prop: keyof CSSStyleDeclaration | `--${string}`,
  val: (() => string | number | undefined) | (string | number | undefined),
  ...rest: (StateType<any> | Condition)[]
) => () => void

Parameters

Behavior

1. Evaluates val (calls it if it's a function).
2. Checks all Conditions — if all are truthy, applies the style.
3. For custom properties (--*): uses el.style.setProperty(prop, val).
4. For standard properties: assigns directly to el.style[prop].
5. Subscribes to every State in rest so the trait re-runs on state changes.

Returns

A cleanup function that unsubscribes from all State listeners.

Template Usage

// Token value (re-evaluates on theme change via $val)
trait.style('backgroundColor', surface_bg_primary.$val);
trait.style('padding', space_padding_md.$val);

// Conditional toggle — unconditional default + conditional override
// IMPORTANT: Never use two opposing $test conditions on the same property.
// Each conditional trait has its own saved-value slot, and opposing conditions
// will corrupt each other's snapshots, preventing the style from reverting.
trait.style('opacity', '0'); // default
trait.style('opacity', '1', visible.$test(true)); // override when true

// Custom CSS property
trait.style('--header-height', '64px');

// Conditional application
trait.style(
  'display',
  'none',
  someState.$test((s) => !s.visible),
);

useInputValueTrait

Reactively sets the value property of an <input> or <textarea> element. Pairs with useInputEventTrait for two-way data binding.

Signature

useInputValueTrait(
  el: HTMLInputElement | HTMLTextAreaElement,
  value: (() => string | number | undefined) | (string | number | undefined),
  ...rest: (StateType<any> | Condition)[]
) => () => void

Parameters

Behavior

1. Evaluates value (calls it if it's a function).
2. Checks all Conditions — if all are truthy, sets el.value.
3. Subscribes to every State in rest so the trait re-runs on state changes.
4. Typically used alongside useInputEventTrait to create a reactive loop: state → input value → user types → event → update state → input value updates.

Returns

A cleanup function that unsubscribes from all State listeners.

Template Usage

// Two-way binding pattern
tag.input(trait.inputValue(nameState.$val), trait.inputEvent('input', nameState.set));

// Conditional binding
tag.input(trait.inputValue(searchState.$val, isEditing.$test(true)));

useEventTrait

Attaches a DOM event listener to an element. The listener is added or removed reactively based on Conditions and State changes.

Signature

useEventTrait(
  el: HTMLElement,
  evt: keyof GlobalEventHandlersEventMap,
  cb: (evt?: GlobalEventHandlersEventMap[keyof GlobalEventHandlersEventMap]) => void,
  ...rest: (StateType<any> | Condition)[]
) => () => void

Parameters

Behavior

1. Checks all Conditions — if all are truthy and the listener is not already attached, calls el.addEventListener(evt, cb).
2. If any Condition becomes falsy, calls el.removeEventListener(evt, cb).
3. Tracks attachment state internally to prevent duplicate listeners.
4. Subscribes to every State in rest so the trait re-evaluates on state changes.

Returns

A cleanup function that removes the event listener and unsubscribes from all State listeners.

Template Usage

trait.event(
  'click',
  count.$reduce((prev) => prev + 1),
);
trait.event('submit', (e) => {
  e.preventDefault();
  save();
});
trait.event('mouseenter', showTooltip, enabled.$test(true));

useInnerHTMLTrait

Sets the inner content of an element by appending child elements or text nodes. Clears the element first, then appends children — making it safe for HTMLElement and SVGElement children (no serialization).

Signature

useInnerHTMLTrait(
  el: HTMLElement,
  children: Child | Child[] | (() => Child | Child[]),
  ...rest: (StateType<any> | Condition)[]
) => () => void

Where Child = string | number | HTMLElement | SVGElement | undefined | unknown.

Parameters

Behavior

1. Clears el.innerHTML.
2. Evaluates children (calls it if it's a function).
3. Checks all Conditions — if any are falsy, the element remains empty.
4. For arrays: filters out falsy values, appends HTMLElement/SVGElement children via appendChild, and wraps primitives in text nodes.
5. For single HTMLElement/SVGElement: appends directly.
6. For single primitives: sets el.innerHTML to the stringified value.
7. Subscribes to every State in rest so the trait re-runs on state changes.

Returns

A cleanup function that unsubscribes from all State listeners.

Template Usage

tag.div(
  trait.innerHTML(
    () => [tag.h1(trait.textContent('Hello')), tag.p(trait.textContent(message.$val))],
    message,
  ),
);

tag.ul(
  trait.innerHTML(() => items.val().map((item) => tag.li(trait.textContent(item.label))), items),
);

useAriaTrait

Reactively sets ARIA attributes and the role attribute on an element. When the value is undefined or conditions evaluate to false, the attribute is removed. Provides first-class accessibility support with typed ARIA property names.

Signature

useAriaTrait(
  el: HTMLElement,
  prop: 'role' | `aria-${string}`,
  val: (() => string | number | boolean | undefined) | (string | number | boolean | undefined),
  ...rest: (StateType<any> | Condition)[]
) => () => void

Parameters

Behavior

1. Evaluates val (calls it if it's a function).
2. Checks all Conditions — if any are falsy, removes the attribute.
3. If all Conditions pass and val is undefined, removes the attribute.
4. Otherwise, sets the attribute via el.setAttribute(prop, String(val)).
5. Subscribes to every State in rest so the trait re-runs on state changes.

Returns

A cleanup function that unsubscribes from all State listeners.

Template Usage

// Static ARIA label
trait.aria('aria-label', 'Close dialog');

// Role assignment
trait.aria('role', 'navigation');

// Reactive expanded state
trait.aria(
  'aria-expanded',
  () => String(menuOpen.val()),
  menuOpen,
);

// Conditional aria-hidden
trait.aria('aria-hidden', 'true', visible.$test(false));
trait.aria('aria-hidden', 'false', visible.$test(true));

// Reactive aria-live region
trait.aria('aria-live', 'polite');
trait.aria(
  'aria-label',
  () => `${notifications.val().length} new notifications`,
  notifications,
);

// Aria-current for navigation
trait.aria(
  'aria-current',
  'page',
  activeRoute.$test((r) => r === '/about'),
);

Common ARIA Patterns

Accessible toggle button

const expanded = State<boolean>(false);

tag.button(
  trait.aria('aria-expanded', () => String(expanded.val()), expanded),
  trait.aria('aria-controls', 'panel-1'),
  trait.event('click', expanded.$reduce((v) => !v)),
  trait.textContent(() => (expanded.val() ? 'Collapse' : 'Expand'), expanded),
);

Live region for status updates

tag.div(
  trait.aria('role', 'status'),
  trait.aria('aria-live', 'polite'),
  trait.textContent(() => statusMessage.val(), statusMessage),
);

Tab panel

tag.div(
  trait.aria('role', 'tabpanel'),
  trait.aria('aria-labelledby', 'tab-1'),
  trait.aria(
    'aria-hidden',
    () => String(activeTab.val() !== 'tab-1'),
    activeTab,
  ),
);

Comparison with useAttributeTrait

useAriaTrait is a semantic specialization — it constrains the prop parameter to valid ARIA attributes, making intent clearer and preventing accidental misuse.

Notes

• Follows the same reactive pattern as useAttributeTrait
• Removing the attribute (via undefined or failing conditions) is the correct way to "unset" ARIA properties
• Boolean ARIA attributes like aria-expanded must be set as string "true" or "false" — they are not boolean HTML attributes

useClassNameTrait

Sets the class attribute of an HTML element reactively. Replaces the entire class string — does not toggle individual classes.

Signature

useClassNameTrait(
  el: HTMLElement,
  className: string | (() => string),
  ...rest: (StateType<any> | Condition)[]
) => () => void

Parameters

Behavior

1. Evaluates className (calls it if it's a function).
2. Checks all Conditions — if all are truthy, sets the class attribute via el.setAttribute('class', ...).
3. If any Condition is falsy, the class is not applied (the previous value remains).
4. Subscribes to every State in rest so the trait re-runs on state changes.

Returns

A cleanup function that unsubscribes from all State listeners.

Template Usage

trait.className('btn btn-primary');
trait.className('tab active', isActive.$test(true));
trait.className('tab', isActive.$test(false));

useStyleOnEventTrait

Applies a CSS style property when a DOM event fires on the element. Unlike useStyleTrait, this trait does not subscribe to State objects — it runs the style application inside the event handler itself.

Signature

useStyleOnEventTrait(
  el: HTMLElement,
  evt: keyof HTMLElementEventMap,
  prop: keyof CSSStyleDeclaration | `--${string}`,
  val: (() => string | number | undefined) | (string | number | undefined),
  ...rest: Condition[]
) => () => void

Parameters

Behavior

1. Attaches an event listener for evt on el.
2. When the event fires: evaluates val, checks Conditions, and applies the style if all pass.
3. For custom properties (--*): uses el.style.setProperty(prop, val).
4. For standard properties: assigns directly to el.style[prop].
5. Does not subscribe to State objects — only re-evaluates when the event fires.

Returns

A cleanup function that removes the event listener.

Template Usage

// Hover highlight pattern
trait.styleOnEvent('mouseenter', 'backgroundColor', action_bg_hover.$val);
trait.styleOnEvent('mouseleave', 'backgroundColor', action_bg_primary.$val);

// Focus ring
trait.styleOnEvent('focus', 'outline', () => `2px solid ${focus_border_primary.val()}`);
trait.styleOnEvent('blur', 'outline', 'none');

State Library

UrlState

A reactive state hook that tracks the current URL, matching it against a set of defined routes and extracting params, query strings, and hash fragments.

Features

• Route matching: Matches the current pathname against Express-style route patterns (e.g. /user/:id)
• Param extraction: Automatically extracts named parameters from matched routes
• Query & hash parsing: Parses query string parameters and hash fragments from the URL
• Type-safe routes: Route handler signatures are inferred from the route pattern — routes with :param segments require a typed params object
• Reactive: Returns a State object that updates on popstate and hashchange events

Usage

import { useUrlState } from '@linttrap/oem';

const url = useUrlState<{
  '/': any;
  '/about': any;
  '/user/:id': any;
  '/user/:id/post/:postId': any;
}>({
  '/': () => '/',
  '/about': () => '/about',
  '/user/:id': ({ id }) => `/user/${id}`,
  '/user/:id/post/:postId': ({ id, postId }) => `/user/${id}/post/${postId}`,
});

// Read the current URL state
const { matchedRoute, params, query, hash } = url.val();

// Subscribe to URL changes
url.sub(({ matchedRoute, params, query, hash }) => {
  console.log('Route:', matchedRoute);
  console.log('Params:', params);
  console.log('Query:', query);
  console.log('Hash:', hash);
});

Signature

function useUrlState<T extends Record<string, any>>(routes: {
  [K in keyof T]: K extends string ? RouteHandler<K> : never;
}): StateType<UrlState<typeof routes>, {}>;

Parameters

Route Handler Signatures

Route handlers are type-inferred from the pattern string:

• Static routes (no params): () => string
• Dynamic routes (with :param): (params: { [K in ExtractRouteParams<Path>]: string }) => string

Return Value

Returns a State<UrlState> containing:

Behavior

• Parses document.location on initialization and returns the matched state
• Listens for popstate events (browser back/forward navigation)
• Listens for hashchange events (hash fragment changes)
• On each event, re-parses the location and updates the state, notifying all subscribers
• Route matching converts patterns like /user/:id to regex and tests against the current pathname
• If no route matches, matchedRoute is an empty string and params is an empty object

Common Patterns

Route-based rendering

const url = useUrlState<{
  '/': any;
  '/about': any;
  '/contact': any;
}>({
  '/': () => '/',
  '/about': () => '/about',
  '/contact': () => '/contact',
});

url.sub(({ matchedRoute }) => {
  switch (matchedRoute) {
    case '/':
      renderHome();
      break;
    case '/about':
      renderAbout();
      break;
    case '/contact':
      renderContact();
      break;
  }
});

Reading dynamic params

const url = useUrlState<{
  '/user/:id': any;
}>({
  '/user/:id': ({ id }) => `/user/${id}`,
});

// If current URL is /user/42
const { params } = url.val();
console.log(params.id); // "42"

Using with conditions

const url = useUrlState<{
  '/': any;
  '/about': any;
}>({
  '/': () => '/',
  '/about': () => '/about',
});

// Create a condition to test the matched route
const isHome = url.$test((s) => s.matchedRoute === '/');
const isAbout = url.$test((s) => s.matchedRoute === '/about');

Notes

• Event listeners (popstate, hashchange) are added globally and remain active for the lifetime of the page
• Route patterns support alphanumeric characters and hyphens in param values ([\w-]+)
• Query string parsing uses the standard URLSearchParams API
• The routes object is included in the state value for programmatic navigation via handler functions

MediaQueryState

A reactive state hook that tracks whether the current viewport matches specified media query conditions.

Features

• Responsive tracking: Automatically updates when window is resized
• Width-based queries: Support for min and max width constraints
• Media type support: Filter by screen, print, or all media types
• Reactive: Returns a State object that updates when conditions change

Usage

import { useMediaQueryState } from '@linttrap/oem';

// Track mobile viewport (max 768px)
const isMobile = useMediaQueryState({
  maxWidth: 768,
});

// Track tablet viewport (768px - 1024px)
const isTablet = useMediaQueryState({
  minWidth: 768,
  maxWidth: 1024,
});

// Track desktop viewport (min 1024px)
const isDesktop = useMediaQueryState({
  minWidth: 1024,
});

// Track print media
const isPrint = useMediaQueryState({
  type: 'print',
});

Props

Return Value

Returns a State<boolean> that is true when the media query matches and false otherwise.

Behavior

The state automatically:

• Evaluates the media query on initialization
• Adds a resize event listener to track viewport changes
• Updates the state value when conditions change
• Checks both width constraints AND media type (both must match)

Common Patterns

Responsive Breakpoints

// Define standard breakpoints
const isMobile = useMediaQueryState({ maxWidth: 639 });
const isTablet = useMediaQueryState({ minWidth: 640, maxWidth: 1023 });
const isDesktop = useMediaQueryState({ minWidth: 1024 });

Conditional Rendering

const isMobile = useMediaQueryState({ maxWidth: 768 });

if (isMobile.val()) {
  // Render mobile layout
} else {
  // Render desktop layout
}

Notes

• The resize listener is added globally and will remain active
• Consider cleanup if using in components that mount/unmount frequently
• Width boundaries are inclusive (>= minWidth, <= maxWidth)

ThemeState

A small state hook for managing the current theme as a reactive State value.

Features

• Typed themes: Constrains the theme to 'light' or 'dark'
• Reactive: Returns a State object that can be observed or updated
• Minimal: No side effects, no DOM reads, no global listeners

Usage

import { useThemeState } from '@linttrap/oem';

const theme = useThemeState('light');

// Read the current theme
const current = theme.val();

// Update the theme
theme.set('dark');

Signature

type Theme = 'light' | 'dark';

function useThemeState(theme: Theme): State<Theme>;

Parameters

Return Value

Returns a State<Theme> representing the current theme.

Behavior

• Initializes with the provided theme value
• Updates whenever set() is called
• Subscribers receive the latest theme value

Notes

• This hook does not persist to storage or read from the DOM
• Intended to be composed with other reactive state hooks

OnlineState

A reactive state hook that tracks whether the browser is currently online or offline.

Features

• Connectivity tracking: Automatically updates when the browser goes online or offline
• Immediate evaluation: Initializes to the current navigator.onLine value
• Reactive: Returns a State object that updates on online and offline window events

Usage

import { useOnlineState } from '@linttrap/oem';

const isOnline = useOnlineState();

// Read current connectivity
console.log(isOnline.val()); // true or false

// React to connectivity changes
isOnline.sub((online) => {
  console.log(online ? 'Back online' : 'Gone offline');
});

Signature

function useOnlineState(): StateType<boolean, {}>;

Parameters

None.

Return Value

Returns a State<boolean> that is true when the browser is online and false when offline.

Behavior

• Initializes to navigator.onLine
• Listens for the online window event and sets state to true
• Listens for the offline window event and sets state to false
• Notifies all subscribers on each change

Common Patterns

Conditional UI based on connectivity

const isOnline = useOnlineState();

// Show/hide an offline banner
trait.style('display', 'none', isOnline.$test(true));
trait.style('display', 'flex', isOnline.$test(false));

Gate network actions

const isOnline = useOnlineState();

trait.event(
  'click',
  () => fetchData(),
  isOnline.$test(true),
);

Notes

• Event listeners are added globally and remain active for the lifetime of the page
• Uses the standard navigator.onLine API and online/offline window events

WindowSizeState

A reactive state hook that tracks the current viewport dimensions.

Features

• Viewport tracking: Reports both width and height as numbers
• Immediate evaluation: Initializes to the current window size
• Reactive: Returns a State object that updates on window resize

Usage

import { useWindowSizeState } from '@linttrap/oem';

const windowSize = useWindowSizeState();

// Read current dimensions
const { width, height } = windowSize.val();

// Subscribe to size changes
windowSize.sub(({ width, height }) => {
  console.log(`${width}x${height}`);
});

Signature

function useWindowSizeState(): StateType<WindowSize, {}>;

Parameters

None.

Return Value

Returns a State<WindowSize> containing:

Behavior

• Initializes to { width: window.innerWidth, height: window.innerHeight }
• Listens for the resize window event
• Updates state with the new dimensions on every resize
• Notifies all subscribers on each change

Common Patterns

Dynamic canvas sizing

const windowSize = useWindowSizeState();

windowSize.sub(({ width, height }) => {
  canvas.width = width;
  canvas.height = height;
});

Computed column count

const windowSize = useWindowSizeState();

trait.style('gridTemplateColumns', () => {
  const cols = Math.floor(windowSize.val().width / 300);
  return `repeat(${cols}, 1fr)`;
}, windowSize);

Reactive dimension values

const windowSize = useWindowSizeState();

trait.style('height', () => `${windowSize.val().height - 64}px`, windowSize);

Comparison with useMediaQueryState

Use useMediaQueryState for breakpoint-gated trait conditions. Use useWindowSizeState when you need raw pixel values for calculations.

Notes

• The resize listener is added globally and remains active for the lifetime of the page
• For breakpoint-based boolean conditions, prefer useMediaQueryState instead

TokenState

A derived state hook that selects between two token values based on the current theme.

Features

• Theme-aware: Switches between light and dark values
• Derived state: Recomputes when the theme state changes
• Generic: Works with any token value type

Usage

import { useThemeState, useTokenState } from '@linttrap/oem';

const theme = useThemeState('light');
const primaryColor = useTokenState('#111827', '#f9fafb', theme);

// Read the current token value
const color = primaryColor.val();

// Switch theme and let token update
theme.set('dark');

Signature

function useTokenState<T>(lightVal: T, darkVal: T, themeState: StateType<Theme, {}>): State<T>;

Parameters

Return Value

Returns a State<T> whose value updates when the theme changes.

Behavior

• Initializes to lightVal or darkVal based on themeState.val()
• Subscribes to themeState and updates the token whenever the theme changes

Common Patterns

const theme = useThemeState('light');
const textColor = useTokenState('#111', '#eee', theme);
const bgColor = useTokenState('#fff', '#0b0f1a', theme);

Notes

• The subscription remains active as long as themeState exists
• Ensure the themeState is shared across tokens to keep updates consistent

IntersectionObserverState

A reactive state hook that tracks whether an element is visible within the viewport (or a specified root element) using the Intersection Observer API.

Features

• Visibility tracking: Knows when an element enters or leaves the viewport
• Intersection ratio: Reports how much of the element is visible (0 to 1)
• Bounding rect: Exposes the element's bounding client rect on each observation
• Configurable thresholds: Supports all standard IntersectionObserver options
• Reactive: Returns a State object that updates on every intersection change

Usage

import { useIntersectionObserverState } from '@linttrap/oem';

const section = document.getElementById('hero')!;
const visibility = useIntersectionObserverState(section);

// Check if element is visible
visibility.sub(({ isIntersecting }) => {
  console.log(isIntersecting ? 'Visible' : 'Hidden');
});

Signature

function useIntersectionObserverState(
  el: Element,
  options?: IntersectionObserverInit,
): StateType<IntersectionObserverStateValue, {}>;

Parameters

Return Value

Returns a State<IntersectionObserverStateValue> with the following shape:

Behavior

• Creates an IntersectionObserver and immediately begins observing the target element
• Updates state on every intersection change (entry/exit, ratio change at thresholds)
• Notifies all subscribers with the new intersection data

Common Patterns

Lazy loading content

const placeholder = document.getElementById('lazy-section')!;
const visibility = useIntersectionObserverState(placeholder, {
  threshold: 0.1,
});

visibility.sub(({ isIntersecting }) => {
  if (isIntersecting) loadContent();
});

Scroll-spy navigation

const sections = ['intro', 'features', 'pricing'].map((id) => ({
  id,
  visibility: useIntersectionObserverState(document.getElementById(id)!, {
    threshold: 0.5,
  }),
}));

sections.forEach(({ id, visibility }) => {
  visibility.sub(({ isIntersecting }) => {
    if (isIntersecting) activeSection.set(id);
  });
});

Animate on scroll

const el = document.getElementById('animate-me')!;
const visibility = useIntersectionObserverState(el, { threshold: 0.2 });

trait.style('opacity', '0');
trait.style(
  'opacity',
  '1',
  visibility.$test((v) => v.isIntersecting),
);
trait.style(
  'transition',
  'opacity 0.3s ease',
);

Notes

• The observer remains active for the lifetime of the page
• Use threshold option to control when intersection callbacks fire (e.g., [0, 0.25, 0.5, 0.75, 1] for granular tracking)
• Uses the standard IntersectionObserver API — supported in all modern browsers

TimerState

A reactive state hook that increments a counter at a fixed interval. Provides custom methods to start, stop, and reset the timer.

Features

• Interval counter: Increments a numeric value at a configurable interval
• Start/stop/reset: Custom methods for full timer lifecycle control
• Auto-start: Starts automatically by default (configurable)
• Deferred methods: $start, $stop, $reset for use in event handlers
• Reactive: Returns a State object that updates on every tick

Usage

import { useTimerState } from '@linttrap/oem';

// Tick every second, auto-starts
const timer = useTimerState(1000);

// Read current tick count
console.log(timer.val()); // 0, 1, 2, ...

// Control the timer
timer.stop();
timer.reset();
timer.start();

// Subscribe to ticks
timer.sub((count) => {
  console.log('Tick:', count);
});

Signature

function useTimerState(
  intervalMs: number,
  options?: { autoStart?: boolean },
): StateType<number, { start; stop; reset }>;

Parameters

Return Value

Returns a State<number> with these additional custom methods:

Each method also has a $-prefixed deferred version ($start, $stop, $reset) that returns () => void.

Behavior

• Initializes the counter to 0
• If autoStart is not explicitly false, starts the interval immediately
• Each tick increments the counter by 1 and notifies all subscribers
• start() is a no-op if the timer is already running (prevents double intervals)
• stop() clears the interval; start() can resume from the current count
• reset() clears the interval AND sets the counter back to 0

Common Patterns

Auto-save indicator

const timer = useTimerState(30000); // every 30 seconds

timer.sub(() => {
  saveDocument();
});

Countdown display

const DURATION = 60;
const timer = useTimerState(1000);

trait.textContent(() => `${DURATION - timer.val()}s remaining`);

Polling with deferred controls

const timer = useTimerState(5000, { autoStart: false });

timer.sub(() => fetchUpdates());

// Wire start/stop to buttons
trait.event('click', timer.$start());
trait.event('click', timer.$stop());

Session timeout

const idle = useTimerState(1000);

idle.sub((seconds) => {
  if (seconds >= 300) logout();
});

// Reset on user activity
document.addEventListener('mousemove', () => idle.reset());

Notes

• The interval uses setInterval under the hood
• Timer remains active until explicitly stopped or reset
• The counter is a simple incrementing integer — for elapsed time, multiply by intervalMs

FormState

A reactive state hook for managing form values, validation errors, touched fields, and dirty state.

Features

• Field-level control: Set individual field values with automatic re-validation
• Validation: Optional per-field validators that run on every field change
• Touched tracking: Track which fields have been interacted with
• Dirty tracking: Knows when any field has been modified from initial values
• Full validate: Validate all fields at once (e.g., on submit)
• Reset: Return to initial values and clear all state
• Deferred methods: $setField, $touch, $validate, $reset for event wiring

Usage

import { useFormState } from '@linttrap/oem';

const form = useFormState(
  { email: '', password: '' },
  {
    email: (val) => (!val ? 'Required' : undefined),
    password: (val) => (val.length < 8 ? 'Min 8 characters' : undefined),
  },
);

// Set a field value
form.setField('email', 'user@example.com');

// Touch a field
form.touch('email');

// Validate all fields
const isValid = form.validate();

// Read state
const { values, errors, touched, dirty, valid } = form.val();

// Reset to initial
form.reset();

Signature

function useFormState<T extends Record<string, any>>(
  initialValues: T,
  validators?: Partial<Record<keyof T, (value: T[keyof T], values: T) => string | undefined>>,
): StateType<FormStateValue<T>, { setField; setError; touch; validate; reset }>;

Parameters

Return Value

Returns a State<FormStateValue<T>> with shape:

Custom Methods

Each method also has a $-prefixed deferred version.

Behavior

• Initializes with the provided initialValues, no errors, no touched fields, dirty: false, valid: true
• On setField: updates the field value, runs all validators, updates errors and valid, sets dirty: true
• On touch: marks the field as touched (useful for showing errors only after interaction)
• On validate: runs all validators, marks all fields as touched, updates state, returns boolean
• On reset: returns to the exact initial state
• Validators receive both the field value and the full values object (for cross-field validation)

Common Patterns

Contact form

const form = useFormState(
  { name: '', email: '', message: '' },
  {
    name: (v) => (!v ? 'Name is required' : undefined),
    email: (v) => (!v.includes('@') ? 'Invalid email' : undefined),
    message: (v) => (v.length < 10 ? 'Too short' : undefined),
  },
);

Two-way binding with input traits

trait.inputValue(() => form.val().values.email, form);
trait.inputEvent('input', (val) => form.setField('email', val), form);
trait.event('blur', form.$touch('email'));

Show errors only for touched fields

trait.textContent(
  () => {
    const { errors, touched } = form.val();
    return touched.email ? errors.email || '' : '';
  },
  form,
);

Submit handler

trait.event('click', () => {
  if (form.validate()) {
    submitForm(form.val().values);
  }
});

Cross-field validation

const form = useFormState(
  { password: '', confirmPassword: '' },
  {
    confirmPassword: (val, values) =>
      val !== values.password ? 'Passwords must match' : undefined,
  },
);

Notes

• Validators run synchronously on every setField call
• The valid flag reflects the result of the most recent validation run
• validate() touches all fields so error messages become visible
• For async validation (e.g., server-side uniqueness checks), use setError manually after an async call

Examples

Theme Toggle Example

import { useThemeState, useTokenState } from '@linttrap/oem';

const theme = useThemeState('light');
const bg = useTokenState('#c7c7c7', '#222222', theme);
const fg = useTokenState('#222222', '#c7c7c7', theme);
const accent = useTokenState('#555555', '#999999', theme);

const app = tag.div(
  trait.style('backgroundColor', bg.$val),
  trait.style('color', fg.$val),
  trait.style('transition', 'all 0.3s ease'),
  tag.button(
    trait.text('☀️ Light', theme.$test('dark')),
    trait.text('🌙 Dark', theme.$test('light')),
    trait.event('click', () => theme.reduce((t) => (t === 'dark' ? 'light' : 'dark'))),
    trait.style('color', accent.$val),
  ),
);

Dynamic List Example

const items = State<string[]>([]);
const input = State('');

const list = tag.div(
  tag.div(
    trait.style('display', 'flex'),
    trait.style('gap', '8px'),
    tag.input(
      trait.inputValue(input.$val),
      trait.inputEvent('input', input.$set),
      trait.style('flex', '1'),
    ),
    tag.button(
      trait.text('Add'),
      trait.event('click', () => {
        items.reduce((prev) => [...prev, input.val()]);
        input.set('');
      }),
    ),
  ),
  tag.ul(trait.innerHTML(() => items.val().map((item) => tag.li(trait.text(item))), items)),
);

Counter Example

const count = State(0);

const counter = tag.div(
  trait.style('display', 'flex'),
  trait.style('alignItems', 'center'),
  trait.style('gap', '16px'),
  tag.button(
    trait.text('−'),
    trait.event(
      'click',
      count.$reduce((n) => n - 1),
    ),
    trait.style('fontSize', '24px'),
  ),
  tag.span(
    trait.text(count.$val),
    trait.style('fontSize', '48px'),
    trait.style('fontWeight', '700'),
    trait.style('color', '#555555'),
  ),
  tag.button(
    trait.text('+'),
    trait.event(
      'click',
      count.$reduce((n) => n + 1),
    ),
    trait.style('fontSize', '24px'),
  ),
);

Conditional Styling Example

const isActive = State(false);

tag.div(
  // Base styles — always applied
  trait.style('padding', '16px'),
  trait.style('borderRadius', '8px'),
  trait.style('cursor', 'pointer'),
  trait.style('transition', 'all 0.2s ease'),

  // Conditional branches — never ternaries
  trait.style('backgroundColor', '#555555', isActive.$test(true)),
  trait.style('backgroundColor', '#c7c7c7', isActive.$test(false)),
  trait.style('color', '#c7c7c7', isActive.$test(true)),
  trait.style('color', '#888888', isActive.$test(false)),
  trait.style('boxShadow', '0 0 20px rgba(80,80,80,0.3)', isActive.$test(true)),
  trait.style('boxShadow', 'none', isActive.$test(false)), isActive.$test(false)),
  trait.text('Active', isActive.$test(true)),
  trait.text('Inactive', isActive.$test(false)),
  trait.event('click', isActive.$reduce(v => !v)),
);