pixelize-native-library 1.2.1 → 1.3.0

package/lib/module/modules/tabs/Tabs.js

@@ -16,14 +16,16 @@
  */
 
 import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { Animated, Pressable, StyleSheet, Text, View } from "react-native";
-import Reanimated from "react-native-reanimated";
+import { Pressable, StyleSheet, Text, View } from "react-native";
+import Reanimated, { useAnimatedStyle } from "react-native-reanimated";
 import { Icon } from "../../core/icon/index.js";
-import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { motionParallel, useMotion, useAnimatedValue } from "../../core/motion/index.js";
 import { useHaptics } from "../../core/haptics/index.js";
 import { usePressState } from "../../core/motion/usePressState.js";
+import { renderNodeSlot } from "../../core/slot/index.js";
 import { stateLayerScrim } from "../../theme/platform/stateLayer.native.js";
 import { useTheme } from "../../theme/hooks.js";
+import { Badge } from "../badge/index.js";
 import { resolveTabAccessibility, resolveTabsColors, tabItemStructure, tabsFocusRingStructure, tabsIndicatorStructure, tabsStripStructure, TABS_INDICATOR_UNIT_WIDTH, TABS_SIZES } from "./Tabs.variants.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const ICON_STROKE = 2;
@@ -56,7 +58,7 @@ const TabStripItem = /*#__PURE__*/memo(function TabStripItem({
   const handleLayout = useCallback(event => {
     press.onLayout(event);
     onLayout(item.value, event);
-  }, [onLayout, item.value, press.onLayout]);
+  }, [onLayout, item.value, press]);
   const handleFocus = useCallback(() => setFocused(true), []);
   const handleBlur = useCallback(() => setFocused(false), []);
   const focusRingStyle = useMemo(() => [tabsFocusRingStructure(theme), {
@@ -90,13 +92,15 @@ const TabStripItem = /*#__PURE__*/memo(function TabStripItem({
     hitSlop: hitSlop,
     style: itemStyle,
     children: [/*#__PURE__*/_jsx(Reanimated.View, {
-      pointerEvents: "none",
       testID: testID ? `${testID}-press-overlay` : undefined,
-      style: [StyleSheet.absoluteFill, overlayStaticStyle, press.overlayStyle]
+      style: [StyleSheet.absoluteFill, overlayStaticStyle, press.overlayStyle, {
+        pointerEvents: 'none'
+      }]
     }), focused && /*#__PURE__*/_jsx(View, {
-      pointerEvents: "none",
       testID: testID ? `${testID}-focus-ring` : undefined,
-      style: focusRingStyle
+      style: [focusRingStyle, {
+        pointerEvents: 'none'
+      }]
     }), item.icon !== undefined && /*#__PURE__*/_jsx(Icon, {
       name: item.icon,
       size: iconSize,
@@ -106,7 +110,11 @@ const TabStripItem = /*#__PURE__*/memo(function TabStripItem({
       numberOfLines: 1,
       style: labelStyle,
       children: item.label
-    })]
+    }), item.count !== undefined && item.count > 0 ? /*#__PURE__*/_jsx(Badge, {
+      label: String(item.count),
+      size: "sm",
+      tone: "neutral"
+    }) : null]
   });
 });
 export const Tabs = /*#__PURE__*/memo(function Tabs({
@@ -114,6 +122,8 @@ export const Tabs = /*#__PURE__*/memo(function Tabs({
   value,
   onValueChange,
   size = "md",
+  panels,
+  lazyPanels = true,
   style,
   testID
 }) {
@@ -150,46 +160,81 @@ export const Tabs = /*#__PURE__*/memo(function Tabs({
     const toX = activeLayout.x + activeLayout.width / 2 - INDICATOR_ORIGIN;
     const toScaleX = activeLayout.width / TABS_INDICATOR_UNIT_WIDTH;
     if (!motion.enabled) {
-      indicatorX.setValue(toX);
-      indicatorScaleX.setValue(toScaleX);
+      indicatorX.value = toX;
+      indicatorScaleX.value = toScaleX;
       return;
     }
-    running.current = Animated.parallel([motion.timing(indicatorX, toX), motion.timing(indicatorScaleX, toScaleX)]);
+    running.current = motionParallel(motion.timing(indicatorX, toX), motion.timing(indicatorScaleX, toScaleX));
     running.current.start();
     return () => running.current?.stop();
   }, [activeLayout, motion, indicatorX, indicatorScaleX]);
   useEffect(() => () => running.current?.stop(), []);
-  const indicatorStyle = useMemo(() => [tabsIndicatorStructure(theme), {
-    backgroundColor: colors.indicator,
+  const indicatorStatic = useMemo(() => [tabsIndicatorStructure(theme), {
+    backgroundColor: colors.indicator
+  }], [theme, colors.indicator]);
+  const indicatorMotion = useAnimatedStyle(() => ({
     transform: [{
-      translateX: indicatorX
+      translateX: indicatorX.value
     }, {
-      scaleX: indicatorScaleX
+      scaleX: indicatorScaleX.value
     }]
-  }], [theme, colors.indicator, indicatorX, indicatorScaleX]);
-  const rootStyle = useMemo(() => [tabsStripStructure(theme), style], [theme, style]);
+  }));
+  const rootStyle = useMemo(() => [tabsStripStructure(theme)], [theme]);
+  const outerStyle = useMemo(() => [style], [style]);
+  const [mountedPanelKeys, setMountedPanelKeys] = useState(() => new Set([value]));
+  useEffect(() => {
+    if (panels === undefined) return;
+    if (!lazyPanels) return;
+    setMountedPanelKeys(prev => {
+      if (prev.has(value)) return prev;
+      const next = new Set(prev);
+      next.add(value);
+      return next;
+    });
+  }, [value, panels, lazyPanels]);
+  const panelKeys = useMemo(() => {
+    if (panels === undefined) return [];
+    if (!lazyPanels) return [value];
+    return [...mountedPanelKeys];
+  }, [panels, lazyPanels, value, mountedPanelKeys]);
+  const panelTextStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    color: theme.colors.fg.default,
+    fontSize: theme.fontSizes.md
+  }], [theme]);
   return /*#__PURE__*/_jsxs(View, {
-    testID: testID,
-    accessibilityRole: "tablist",
-    style: rootStyle,
-    children: [/*#__PURE__*/_jsx(Animated.View, {
-      pointerEvents: "none",
-      testID: testID ? `${testID}-indicator` : undefined,
-      style: indicatorStyle
-    }), items.map(item => /*#__PURE__*/_jsx(TabStripItem, {
-      item: item,
-      selected: item.value === value,
-      size: size,
-      theme: theme,
-      labelColor: item.value === value ? colors.activeLabel : colors.inactiveLabel,
-      hitSlop: spec.hitSlop,
-      fontSize: spec.fontSize,
-      iconSize: spec.iconSize,
-      onPress: onValueChange,
-      onLayout: handleTabLayout,
-      hapticsSelection: haptics.selection,
-      testID: testID ? `${testID}-${item.value}` : undefined
-    }, item.value))]
+    style: outerStyle,
+    children: [/*#__PURE__*/_jsxs(View, {
+      testID: testID,
+      accessibilityRole: "tablist",
+      style: rootStyle,
+      children: [/*#__PURE__*/_jsx(Reanimated.View, {
+        testID: testID ? `${testID}-indicator` : undefined,
+        style: [indicatorStatic, indicatorMotion, {
+          pointerEvents: 'none'
+        }]
+      }), items.map(item => /*#__PURE__*/_jsx(TabStripItem, {
+        item: item,
+        selected: item.value === value,
+        size: size,
+        theme: theme,
+        labelColor: item.value === value ? colors.activeLabel : colors.inactiveLabel,
+        hitSlop: spec.hitSlop,
+        fontSize: spec.fontSize,
+        iconSize: spec.iconSize,
+        onPress: onValueChange,
+        onLayout: handleTabLayout,
+        hapticsSelection: haptics.selection,
+        testID: testID ? `${testID}-${item.value}` : undefined
+      }, item.value))]
+    }), panels !== undefined ? /*#__PURE__*/_jsx(View, {
+      testID: testID ? `${testID}-panels` : undefined,
+      children: panelKeys.map(key => /*#__PURE__*/_jsx(View, {
+        testID: testID ? `${testID}-panel-${key}` : undefined,
+        accessibilityElementsHidden: key !== value,
+        importantForAccessibility: key !== value ? "no-hide-descendants" : undefined,
+        children: renderNodeSlot(panels[key], panelTextStyle)
+      }, key))
+    }) : null]
   });
 });
 //# sourceMappingURL=Tabs.js.map

package/lib/module/modules/tabs/Tabs.variants.js

@@ -11,11 +11,9 @@
  *    is unit-testable without rendering React Native.
  */
 
+import { MIN_TOUCH_TARGET, slopFor } from "../../core/a11y/touchTarget.js";
 import { createThemedVariants } from "../../core/style/index.js";
-/** Same floor as Button/RadioGroup — 44dp (WCAG 2.5.5 / HIG). Duplicated, not imported: modules
- * stay isolated. */
-export const MIN_TOUCH_TARGET = 44;
-const slopFor = height => Math.max(0, Math.ceil((MIN_TOUCH_TARGET - height) / 2));
+export { MIN_TOUCH_TARGET };
 /**
  * Tabs-specific dimensions. Kept a plain constant — no theme dependency — so the hit-target test
  * can assert `height + 2·hitSlop ≥ 44` without a provider, same as `BUTTON_SIZES`.

package/lib/module/modules/tabs/TabsProps.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=TabsProps.js.map

package/lib/module/modules/text/MODULE.md

@@ -1,4 +1,4 @@
-# text
+# text/ — the Text and Heading typography primitives
 
 Typography primitives — `Text` and `Heading` with closed `variant` unions. The base primitive most
 other modules compose, so a colour defect here is a defect everywhere.
@@ -16,26 +16,34 @@ import { Text, Heading } from 'pixelize-native-library/text';
 
 | `Text` variant | size | weight | colour role |
 |---|---|---|---|
-| `body` | 17 iOS / 16 Android | regular | `fg.default` |
+| `display` | `4xl` | bold | `fg.default` |
+| `title` | `2xl` | bold | `fg.default` |
+| `heading` | `xl` | bold | `fg.default` |
+| `subheading` | `lg` | semibold | `fg.default` |
+| `body` | 17 iOS / `md` elsewhere | regular | `fg.default` |
 | `body-sm` | `sm` | regular | `fg.default` |
-| `caption` | `xs` | regular | `fg.muted` |
-| `label` | `md` | semibold | `fg.default` |
-| `label-sm` | `sm` | semibold | `fg.default` |
-| `overline` | `xs` | bold | `fg.muted` | uppercase + wider tracking |
-
-Optional props (additive): `color` (`fg` role or `status` role), `align`, `weight`, `numberOfLines`.
-Every variant resolves `lineHeight` (size + 5) and `letterSpacing` from theme tokens.
-
-`Heading` reuses `label` / `label-sm` and overrides only the font size (`h1` `3xl` → `h4` `lg`). It
-renders with `accessibilityRole="header"` **and `aria-level` derived 1:1 from `variant`**
-(`HEADING_LEVELS` in `Text.variants.ts`) — `react-native-web` renders every `header` role as `<h1>`
-unless `aria-level` is set, so without this every `Heading` variant rendered the same DOM tag
-regardless of size (see `core/heading/MODULE.md`). `Text` carries neither prop.
+| `caption` | `xs` | medium | `fg.muted` |
+| `label` | `sm` | semibold | `fg.default` |
+| `label-sm` | `xs` | semibold | `fg.default` |
+| `overline` | `xs` | bold | `fg.muted` — uppercase, `letterSpacing: 1.2` |
+
+Optional props (additive): `color` (an `fg` role or a `status` role), `align`, `weight`,
+`numberOfLines`. Each variant carries its own `lineHeight` (`body` alone derives it as size + 6) and
+its own `letterSpacing`; a variant configured at `0` falls back to `opticalLetterSpacing`, which
+tightens from the `letterSpacings` tokens at 20 / 30 / 48 dp.
+
+`Heading` maps onto the `Text` variants (`h1`→`title`, `h2`→`heading`, `h3`→`subheading`,
+`h4`→`label`) and overrides font size (`3xl` → `lg`), line height and letter spacing. It renders with
+`accessibilityRole="header"` **and `aria-level` derived 1:1 from `variant`** (`HEADING_LEVELS` in
+`Text.variants.ts`) — `react-native-web` renders every `header` role as `<h1>` unless `aria-level` is
+set, so without this every `Heading` variant rendered the same DOM tag regardless of size (see
+`core/heading/MODULE.md`). `Text` carries neither prop.
 
 ## Colour
 
-A variant may bind to **`fg.default` or `fg.muted` only** — the union is closed at the type level
-(`TextColorRole`), and `Text.test.ts` measures both roles across all 9 brands × both modes against
+A **variant** may bind to `fg.default` or `fg.muted` only — that internal union is closed, and the
+wider `color` prop (`TextColorRole` = those two plus a `status` role, resolved through
+`status[role].text`) is the only way past it. `Text.test.ts` measures both `fg` roles across all 9 brands × both modes against
 `bg.canvas`, `bg.surface` and `bg.raised`. Measured minimums: `fg.default` 6.10 / 6.65 / 6.31,
 `fg.muted` 6.52 / 6.99 / 6.71 — all clear WCAG 1.4.3's 4.5:1.
 

package/lib/module/modules/text/Text.variants.js

@@ -1,6 +1,7 @@
 "use strict";
 
 import { Platform } from 'react-native';
+import letterSpacings from "../../theme/tokens/primitives/letterSpacings.js";
 export const HEADING_LEVELS = {
   h1: 1,
   h2: 2,
@@ -111,6 +112,13 @@ function variantFontSize(theme, variant) {
   }
   return theme.fontSizes[config.fontSize];
 }
+function opticalLetterSpacing(fontSize, configured) {
+  if (configured !== 0) return configured;
+  if (fontSize >= 48) return fontSize * letterSpacings.tighter;
+  if (fontSize >= 30) return fontSize * letterSpacings.tight;
+  if (fontSize >= 20) return fontSize * letterSpacings.tight * 0.5;
+  return 0;
+}
 function variantLineHeight(_theme, variant, fontSize) {
   const config = VARIANT_CONFIG[variant];
   if (config.lineHeight === 'body') {
@@ -136,7 +144,7 @@ export function resolveTextStyle(theme, variant, options) {
     ...theme.fontStyleForWeight(theme.fontWeights[weight]),
     fontSize,
     lineHeight: variantLineHeight(theme, variant, fontSize),
-    letterSpacing: config.letterSpacing,
+    letterSpacing: opticalLetterSpacing(fontSize, config.letterSpacing),
     color
   };
   if (options?.align !== undefined) {

package/lib/module/modules/text/TextProps.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=TextProps.js.map

package/lib/module/modules/textarea/MODULE.md

@@ -1,7 +1,7 @@
 # textarea/ — multiline text entry
 
-`Textarea` is `Input`'s multiline sibling (Input is built in parallel; this module has no dependency
-on it). Same closed-prop shape as every other module: `size` / `status` are closed unions, colour is
+`Textarea` is `Input`'s multiline sibling — it shares `Input`'s prop names by convention but imports
+nothing from it. Same closed-prop shape as every other module: `size` / `status` are closed unions, colour is
 resolved from `RoleColors`, and `containerStyle` is the one documented `LayoutStyle` exception for a
 component wrapping a native `TextInput` (CLAUDE.md).
 
@@ -27,7 +27,7 @@ component wrapping a native `TextInput` (CLAUDE.md).
 | `status` | `default \| error` | `default` | Closed union — drives the field boundary + message colour. |
 | `disabled` | `boolean` | `false` | `editable={false}` + dimmed; blocks `changeText`. |
 | `label` | `string` | — | Rendered above the field; falls back into the field's `accessibilityLabel`. |
-| `accessibilityLabel` | `string` | `label` | Overrides the label fallback — needed when the visible label lives elsewhere (e.g. a `FormField` wrapper). Previously absent: `label` was the only way in. |
+| `accessibilityLabel` | `string` | `label` | Overrides the label fallback — needed when the visible label lives elsewhere (e.g. a `FormField` wrapper). |
 | `helperText` | `string` | — | Shown when `status` is `default`, or as the `error` fallback (see below). |
 | `errorText` | `string` | — | Shown instead of `helperText` when `status` is `error` and it's provided. |
 | `maxLength` | `number` | — | Passed straight to `TextInput`. |
@@ -55,7 +55,7 @@ No `icon` prop: multiline fields don't carry a leading/trailing icon in this cat
   which would otherwise double up visibly with the themed ring above. Native is untouched, since
   `outlineWidth` also drives TV remote-control focus there.
 - **2.3.3** — two things animate, both `opacity` only, on the native driver: the always-mounted focus
-  ring crossfades (`Textarea.tsx:99`, `fast`) and the helper/error message fades in and out
+  ring crossfades (`fast`) and the helper/error message fades in and out
   (`useEnterExit`). Both are guarded by `if (!motion.enabled) { …setValue(to); return; }`, so under
   reduce motion the ring is at its final opacity on the very next render and the message is removed
   outright rather than faded — pinned by `Textarea.motion.test.tsx`.
@@ -64,10 +64,9 @@ No `icon` prop: multiline fields don't carry a leading/trailing icon in this cat
   `textbox` value to assign.
 - `aria-disabled` tracks the same flag `editable` uses — flat, not `accessibilityState={{…}}`:
   react-native-web drops the object form entirely.
-- **3.3.1 — CORRECTED to match `FormField`'s own stated rule.** `errorText` now joins the accessible
-  NAME and sets `aria-invalid`, instead of riding `accessibilityHint` — a hint is advisory and some
-  readers suppress it, which a validity message must never be (same fix as `Input`). `helperText`
-  (genuinely advisory) stays on `accessibilityHint` for native.
+- **3.3.1** — `errorText` joins the accessible NAME and sets `aria-invalid`; it never rides
+  `accessibilityHint`, which is advisory and suppressed by some readers. `helperText` (genuinely
+  advisory) stays on `accessibilityHint` for native. Matches `FormField` and `Input`.
 - The label `Text` is hidden from assistive tech on native
   (`accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"`) — its content
   is carried by the field's own `accessibilityLabel`. The helper/error `Text` is hidden the same way
@@ -92,18 +91,13 @@ Same reasoning as Button's `tone`: every colour a field boundary or message can
 
 ## Known gaps
 
-- No `Input` module exists yet to diff this against (built in parallel) — the "same contract as
-  Input" note in the spec is honoured by prop-name convention (`value`/`onChangeText`/`status`/
-  `disabled`/`label`/`helperText`/`errorText`/`maxLength`/`containerStyle`), not by a shared import.
+- The "same contract as `Input`" guarantee is prop-name convention
+  (`value`/`onChangeText`/`status`/`disabled`/`label`/`helperText`/`errorText`/`maxLength`/
+  `containerStyle`), not a shared import or a shared type — the two can drift without a compile error.
 
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). Renders only host elements (`View`/`Text`/`TextInput`) — nothing to memoize.
 
-## Modernization (v1.0.7)
-
-- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
-- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
-- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.
-
-- **Round 2 visual** — radii retarget (`radii.md`/`lg`/`xl`/`full`), `borderCurve: continuous` on md+ corners; floating surfaces wire platform elevation/highlight where applicable.
+The field uses `radii.md`+ with `borderCurve: "continuous"`; theme access goes through
+`theme/hooks`, and reanimated loads at runtime as an optional peer.

package/lib/module/modules/textarea/Textarea.js

@@ -11,16 +11,16 @@
  */
 
 import { memo, useCallback, useEffect, useId, useMemo, useRef } from "react";
-import { Animated, Platform, StyleSheet, Text, TextInput, View } from "react-native";
-import { useAnimatedValue, useEnterExit, useMotion } from "../../core/motion/index.js";
+import { Platform, StyleSheet, Text, TextInput, View } from "react-native";
+import Reanimated, { useAnimatedStyle } from "react-native-reanimated";
+import { AnimatedText, useAnimatedValue, useEnterExit, useMotion } from "../../core/motion/index.js";
+import { FOCUS_RING_GAP, FOCUS_RING_WIDTH } from "../../core/style/focusRing.js";
 import { useTheme } from "../../theme/hooks.js";
 import { resolveTextareaAccessibility, resolveTextareaStatus, textareaFieldStructure, textareaLayout, TEXTAREA_SIZES } from "./Textarea.variants.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Matches Button's own focus ring exactly: a small gap OUTSIDE the field, on the canvas, because
 // `border.focus` is the role token proven ≥ 3:1 against the canvas (drawn over the field's own
 // boundary colour its ≥ 3:1 isn't guaranteed for every `status`).
-const FOCUS_RING_WIDTH = 2;
-const FOCUS_RING_GAP = 2;
 export const Textarea = /*#__PURE__*/memo(function Textarea(props) {
   const {
     value,
@@ -58,11 +58,14 @@ export const Textarea = /*#__PURE__*/memo(function Textarea(props) {
   if (message !== undefined) lastMessage.current = message;
   const ringOpacity = useAnimatedValue(0);
   const ringAnimation = useRef(null);
+  const ringAnimatedStyle = useAnimatedStyle(() => ({
+    opacity: ringOpacity.value
+  }));
   const setRingVisible = useCallback(visible => {
     ringAnimation.current?.stop();
     const to = visible ? 1 : 0;
     if (!motion.enabled) {
-      ringOpacity.setValue(to);
+      ringOpacity.value = to;
       return;
     }
     ringAnimation.current = motion.timing(ringOpacity, to, {
@@ -138,11 +141,10 @@ export const Textarea = /*#__PURE__*/memo(function Textarea(props) {
         onFocus: handleFocus,
         onBlur: handleBlur,
         style: inputTextStyle
-      }), /*#__PURE__*/_jsx(Animated.View, {
-        pointerEvents: "none",
+      }), /*#__PURE__*/_jsx(Reanimated.View, {
         testID: "textarea-focus-ring",
-        style: [focusRingStyle, {
-          opacity: ringOpacity
+        style: [focusRingStyle, ringAnimatedStyle, {
+          pointerEvents: 'none'
         }]
       })]
     }), messageMotion.mounted && lastMessage.current !== undefined &&
@@ -151,7 +153,7 @@ export const Textarea = /*#__PURE__*/memo(function Textarea(props) {
     // the field's `accessibilityHint` (helper) or its `accessibilityLabel` (error), so a second
     // stop here would repeat it. On web `accessibilityElementsHidden` is not forwarded, and this
     // node is instead what the field's `aria-describedby` points at.
-    _jsx(Animated.Text, {
+    _jsx(AnimatedText, {
       nativeID: hintId,
       accessibilityElementsHidden: true,
       importantForAccessibility: "no-hide-descendants",

package/lib/module/modules/textarea/Textarea.variants.js

@@ -14,13 +14,16 @@
  * only `react-native`'s `StyleSheet`, as `core/style` does).
  */
 
+import { MIN_TOUCH_TARGET } from "../../core/a11y/touchTarget.js";
 import { createThemedVariants } from "../../core/style/index.js";
+export { MIN_TOUCH_TARGET };
+
 /**
  * A multiline field is already well past the 44dp floor at every size (unlike a compact control such
  * as Button), so the touch target is met structurally — no `hitSlop` needed here. Kept local (not
  * imported from a sibling module) per the library's module-isolation rule.
  */
-export const MIN_TOUCH_TARGET = 44;
+
 export const TEXTAREA_SIZES = {
   sm: {
     minHeight: 72,

package/lib/module/modules/textarea/TextareaProps.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=TextareaProps.js.map

package/lib/module/modules/timeline/MODULE.md

@@ -1,15 +1,15 @@
 # timeline/ — a vertical list of dated/ordered events
 
 `Timeline` renders a vertical stack of events, each a marker (a plain dot, or an icon in a filled
-circle) connected to the next row's marker by a line. Purely informational — no press handling, no
-per-item emphasis, no animation.
+circle) connected to the next row's marker by a line. Optional per-item notes and note actions
+compose `Button` controls; the container may run a one-shot decorative reveal when motion allows.
 
 ## Files
 
 | File | Role |
 |------|------|
 | `Timeline.tsx` | The component + the private memo'd `TimelineRow`. Row models, virtualization threshold, the container reveal, and the decorative connector's hidden-from-AT props. |
-| `Timeline.variants.ts` | Pure resolver (`resolveTimelineColors`) + the structural variant resolvers (`timelineRowStructure`, `timelineConnectorStructure`, `timelineMarkerStructure`, `timelineConnectorLineStructure`, `timelineContentStructure`) and the `TIMELINE_MARKER` size constants. No React, no lucide. |
+| `Timeline.variants.ts` | Pure resolvers (`resolveTimelineColors`, `resolveTimelineItemAccessibility`) + the structural variant resolvers (`timelineRowStructure`, `timelineConnectorStructure`, `timelineMarkerStructure`, `timelineConnectorLineStructure`, `timelineContentStructure`) and the `TIMELINE_MARKER` size constants. No React, no lucide. |
 | `index.ts` | Public surface: `Timeline`, `TimelineProps`, `TimelineItem`, `IconName` (re-exported from `core/icon`). |
 | `__tests__/Timeline.test.ts` | Pure: WCAG contrast (all brands × modes) for title/description/timestamp and the icon-on-marker pairing, plus the decorative-connector colour-mapping regression guard (mirrors `Divider.test.ts`). |
 | `__tests__/Timeline.render.test.tsx` | Render: item order, description/timestamp omission, marker sizing per kind, connector line present on every row but the last, decorative hide vs exposed text, consumer `style` applies last. |
@@ -19,7 +19,11 @@ per-item emphasis, no animation.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `items` | `{ title: string; description?: string; timestamp?: string; icon?: IconName; leading?: ReactNode }[]` | — | Rendered top to bottom, in array order. `leading` (added 2026-07, additive) replaces the default marker for that item — see below. |
+| `items` | `TimelineItem[]` | — | `{ id?, title, description?, timestamp?, icon?, leading?, notes? }` — `notes` are rows under the item. `leading` replaces the default marker; `id` keys the row. |
+| `onAddNote` | `() => void` | — | When set, shows an add-note affordance on items that support notes. |
+| `onEditNote` | `(noteId: string) => void` | — | Edit handler per note row. |
+| `onDeleteNote` | `(noteId: string) => void` | — | Delete handler per note row. |
+| `notesLoading` | `boolean` | `false` | Shows loading on note actions when true. |
 | `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
 | `testID` | `string` | — | Forwarded to the outermost `View`; per-row/marker/connector/line nodes get `${testID}-item-<i>[-marker\|-connector\|-line]` when set. |
 
@@ -98,14 +102,6 @@ marker is a composition slot, not an icon choice.
 None — no icon, no new theme token, and no new core helper needed for this component. All markers
 use the closed 22-name `IconName` set already in `core/icon`.
 
-## Resolved (were WCAG bugs caught by the measured test suite, now fixed)
-
-- `timestamp` originally mapped to `fg.subtle`, which measured below 4.5:1 against `bg.canvas` on
-  5 of 8 brands in light mode (lavender/meadow/radiant/emerald/rosewood; as low as 3.19:1 on
-  emerald) — caught by `Timeline.test.ts`'s real `it.each` measurement, never eyeballed. Remapped to
-  `fg.muted` (the `readableOn()`-derived role every other module already trusts on `bg.canvas`),
-  which clears AA on all 8 brands × both modes.
-
 ## Reveal motion (decorative, one value for the whole list)
 
 A single `Animated.Value` on the outer container drives an opacity + `translateY` reveal
@@ -129,8 +125,3 @@ slightly less precise — the same call `markdown/` and `more-items/` make. The
 `item.id` when given, else a positional `timeline-index-<i>` — never one derived from `title`, which
 would remount a row on a text edit.
 
-## Modernization (v1.0.7)
-
-- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
-- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
-- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.