Components

Getting started

npm install affect-kit

Imports

Each component has its own entry point. Import only what you need:

import 'affect-kit/rater';   // registers <affect-kit-rater>
import 'affect-kit/result';  // registers <affect-kit-result>
import 'affect-kit/face';    // registers <affect-kit-face>
import 'affect-kit/compare'; // registers <affect-kit-compare>

// Or register all four at once:
import 'affect-kit';

TypeScript types

import type { Rating, EmotionLabel, EmotionName } from 'affect-kit';
import { createRating, averageRatings }           from 'affect-kit';

Quick wiring: rater → result

<affect-kit-rater id="rater"></affect-kit-rater>
<affect-kit-result id="result" show-face show-labels color-mode></affect-kit-result>

<script type="module">
  import 'affect-kit/rater';
  import 'affect-kit/result';

  const rater  = document.querySelector('affect-kit-rater');
  const result = document.querySelector('affect-kit-result');
  rater.addEventListener('change', e => result.rating = e.detail);
</script>

React

Custom elements work in React 19+ with native support, or React 18 with a thin ref wrapper. TypeScript types are available via the global HTMLElementTagNameMap augmentation shipped in each component entry point.

// React 19+
import 'affect-kit/rater';

function App() {
  return (
    <affect-kit-rater
      color-mode
      onchange={(e) => console.log(e.detail)}
    />
  );
}

2. <affect-kit-rater>

The primary capture interface. The user drags on a V/A pad to set a gut-feeling position — the face glyph and background color update in real time. On release, 55 emotion chips from the NRC VAD Lexicon rearrange by proximity to the pad position. The user taps chips to intensity-rate them at 1, 2, or 3. Every pad release and chip toggle after the first placement fires a change event with a Rating object.

Attributes / props

Events

Methods

CSS custom properties

3. <affect-kit-result>

A display panel for a captured Rating. Renders the selected emotion words scaled by intensity (level 3 is largest, level 1 is smallest), an optional face glyph, and an optional color tint. Designed to pair with <affect-kit-rater> but can also be driven from stored data. The face and color always follow rating.face (the pre-verbal pad gesture), not the composite label coordinates — preserving the visual signal of the gut feeling even when labels shift the V/A/D values.

Attributes / props

CSS custom properties

Layout custom properties

These pierce the shadow DOM and let a parent container (like <affect-kit-compare>) drive the inner face/words layout via container queries without JS:

4. <affect-kit-face>

A standalone animated face glyph driven directly by v (valence) and a (arousal) props. Runs a 60 fps animation loop by default — breath (subtle scale oscillation) and tremor (position noise scaled by arousal). Size is set via CSS; the SVG fills its container. Used internally by both <affect-kit-rater> and <affect-kit-result>.

Attributes / props

Methods

Default size

The element defaults to 120 × 120px (set via :host styles). Override freely with CSS — the SVG fills 100% of its container:

affect-kit-face { width: 80px; height: 80px; }
/* or inline: */
<affect-kit-face style="width:200px;height:200px"></affect-kit-face>

5. <affect-kit-compare>

A paired side-by-side display for two ratings or two rating arrays. When color-mode is on, the card background is a gradient from the left rating's V/A color to the right rating's V/A color — the color transition itself tells the story. Layout responds to host width via container queries: side-by-side when wide, stacked when narrow. Each half's face sits on the outer edge so the faces frame the gradient. The widget makes no claims about what the comparison means — interpretation belongs to the user.

Attributes / props

CSS custom properties

Comparing time series

For windowed comparisons (last month vs last week), call averageRatings() upstream and pass the result. Compare takes a single Rating per side — averaging on every render is a perf footgun for large arrays, and consumers have the windowing/memoization context the component doesn't.

import 'affect-kit/compare';
import { averageRatings } from 'affect-kit';

const cmp = document.querySelector('affect-kit-compare');
cmp.beforeRating = averageRatings(lastMonthRatings);
cmp.afterRating  = averageRatings(lastWeekRatings);

React consumers: useAverageRatings() in @affect-kit/react memoizes by array reference for free.

6. TypeScript types

import type { Rating, EmotionLabel, EmotionName } from 'affect-kit';
import { createRating, averageRatings }           from 'affect-kit';

Rating

The central data object. Emitted by change and commit events, consumed by result and compare. Two VAD sources are preserved separately so researchers can use either or both:

interface Rating {
  /** Unix timestamp (ms) at commit time. */
  timestamp: number;

  /** Pad position that drives the face glyph and color. The pre-verbal gut gesture. */
  face: { v: number; a: number };

  /** Selected emotion words; each optionally carries its lexicon VAD coordinates. */
  labels: EmotionLabel[];

  /**
   * Intensity-weighted centroid of selected labels' VAD values.
   * Novel derivation grounded in affective theory — not independently validated.
   * null when no labels were selected.
   */
  composite: { v: number; a: number; d: number } | null;
}

// To get a single resolved VAD vector:
//   rating.composite ?? { v: rating.face.v, a: rating.face.a, d: 0 }

EmotionLabel

interface EmotionLabel {
  name:  EmotionName; // strict — must be in the validated vocabulary
  level: number;      // 1 | 2 | 3 from rater; widened to number for averaged data
  vad?:  { v: number; a: number; d: number };
  // ^ Optional per-word NRC VAD Lexicon coordinates (NRC v2.1, Mohammad 2025).
  //   The rater always emits with vad inline (Rating is a self-describing
  //   snapshot). For DB persistence, strip vad before insert — it's a
  //   deterministic function of `name`. Rehydrate on read via
  //   `rehydrate(rating)` or by reading `EMOTION_LABELS[name]`.
}

EMOTION_LABELS

Canonical V/A/D coordinates for every word in the vocabulary, as a plain Record keyed by name. Useful for rehydrating stripped Ratings from a database, or for any consumer code that needs the coordinate of a known emotion without going through the rater.

import { EMOTION_LABELS } from 'affect-kit';

const { v, a, d } = EMOTION_LABELS['joy'];
// → { v: 0.96, a: 0.65, d: 0.59 }  (NRC v2.1)

stripVad() / rehydrate()

Helpers for the DB-persistence flow. stripVad() drops the redundant coordinates before insert; rehydrate() fills them back on read.

import { stripVad, rehydrate } from 'affect-kit';

// Persist
const lean = stripVad(rating);          // labels: { name, level }
db.ratings.insert(lean);

// Read
const fromDb = await db.ratings.get(id);
result.rating = rehydrate(fromDb);      // labels: { name, level, vad }

createRating()

Construct a Rating from a face position and optional labels. Throws on any label name not in the validated vocabulary:

import { createRating } from 'affect-kit';

const r = createRating({
  face: { v: 0.5, a: 0.3 },  // pad position (required)
  labels: [                   // optional
    { name: 'calm',     level: 2 },
    { name: 'grateful', level: 1 },
  ],
});

averageRatings()

Average an array of Rating objects into a single Rating. Label levels are averaged continuously — the result widget renders averaged levels as continuous intermediate sizes:

import { averageRatings } from 'affect-kit';

const avg = averageRatings(sessionRatings); // Rating[] → Rating

7. React wrapper

@affect-kit/react wraps all four components using @lit/react. You get typed camelCase props, idiomatic onChange handlers, and correct property/attribute mapping — without writing any ref plumbing.

Install

npm install affect-kit @affect-kit/react

Import

import { Rater, Result, Face, Compare } from '@affect-kit/react';
import type { Rating } from 'affect-kit';

Usage

import { Rater, Result } from '@affect-kit/react';
import { useState } from 'react';
import type { Rating } from 'affect-kit';

export function RatingWidget() {
  const [rating, setRating] = useState<Rating | null>(null);

  return (
    <>
      <Rater colorMode onChange={(e) => setRating(e.detail)} />
      {rating && <Result rating={rating} showFace showLabels colorMode />}
    </>
  );
}

Props

All HTML attributes map to camelCase props (color-mode → colorMode, show-face → showFace, etc.). Complex properties (rating, beforeRating, afterRating) are passed directly as object props — no serialisation.

Events

useAverageRatings()

Hook that wraps averageRatings() with useMemo keyed by array reference. Useful when passing time-series data to <Compare>, which takes a single Rating per side — without memoization, a fresh inline array literal would re-average on every render.

import { Compare, useAverageRatings } from '@affect-kit/react';

function WeekComparison({ lastWeek, thisWeek }) {
  const before = useAverageRatings(lastWeek);
  const after  = useAverageRatings(thisWeek);
  return <Compare beforeRating={before} afterRating={after} showFace colorMode="background" />;
}

Refs

Pass a ref to access the underlying element and call instance methods:

import { useRef } from 'react';
import { Rater } from '@affect-kit/react';
import type { AffectKitRater } from 'affect-kit/rater';

const ref = useRef<AffectKitRater>(null);
// ref.current.reset() — clears pad + chip selection