eidotter 0.36.0 → 0.37.0

package/dist/components/TimelineContainer/components/TimelineEntryCard.js

@@ -0,0 +1,50 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import React from 'react';
+import { Button as AriaButton } from 'react-aria-components';
+import { cn } from '../../../utils/cn.js';
+import { TimelineEntryCardImage } from './variants/TimelineEntryCardImage.js';
+import { TimelineEntryCardGallery } from './variants/TimelineEntryCardGallery.js';
+/**
+ * Dispatcher for content-aware timeline entry rendering.
+ *
+ * Branches on `entry.kind`:
+ *  - `text`    — existing trigger+panel rendering with `entry.content`.
+ *  - `image`   — placeholder for now; filled in by Task 6.
+ *  - `gallery` — placeholder for now; filled in by Tasks 7–8.
+ *
+ * The card chrome (border, hover slide+glow, selected/expanded states)
+ * lives on the outer `.eidotter-timeline-card` element and applies to all
+ * kinds.
+ */
+export const TimelineEntryCard = React.memo(({ entry, isSelected, isExpanded = false, onSelect, footer, children, }) => {
+    return (_jsxs("div", { className: cn('eidotter-timeline-card', isSelected && 'eidotter-timeline-card--selected', isExpanded && 'eidotter-timeline-card--expanded'), children: [renderBranch(entry, isExpanded, onSelect, children), footer && _jsx("div", { className: "eidotter-timeline-card__footer", children: footer })] }));
+});
+TimelineEntryCard.displayName = 'TimelineEntryCard';
+/**
+ * Exhaustive switch over `entry.kind` so a future fourth kind triggers a
+ * compile-time error via `assertNever` rather than silently falling through.
+ */
+function renderBranch(entry, isExpanded, onSelect, children) {
+    switch (entry.kind) {
+        case 'text':
+            return (_jsx(TextBranch, { entry: entry, isExpanded: isExpanded, onSelect: onSelect, children: children }));
+        case 'image':
+            return _jsx(TimelineEntryCardImage, { entry: entry, isExpanded: isExpanded, onSelect: onSelect });
+        case 'gallery':
+            return _jsx(TimelineEntryCardGallery, { entry: entry, isExpanded: isExpanded, onSelect: onSelect });
+        default:
+            return assertNever(entry);
+    }
+}
+function assertNever(value) {
+    throw new Error(`TimelineEntryCard: unhandled entry kind: ${JSON.stringify(value)}`);
+}
+const TextBranch = ({ entry, isExpanded, onSelect, children }) => {
+    const hasStringContent = typeof entry.content === 'string';
+    const hasContent = entry.content != null;
+    return (_jsxs(_Fragment, { children: [_jsxs(AriaButton, { className: "eidotter-timeline-card__trigger", onPress: () => onSelect?.(entry.id), "aria-expanded": isExpanded, children: [_jsxs("div", { className: "eidotter-timeline-card__header", children: [entry.type && (_jsx("span", { className: "eidotter-timeline-card__type", children: entry.type.toUpperCase() })), entry.tags && entry.tags.length > 0 && (_jsx("span", { className: "eidotter-timeline-card__tags", children: entry.tags.map(t => `#${t}`).join(' ') }))] }), _jsx("p", { className: "eidotter-timeline-card__title", children: entry.title }), !isExpanded && hasStringContent && (() => {
+                        const text = String(entry.content);
+                        return (_jsxs("p", { className: "eidotter-timeline-card__preview", children: [text.slice(0, 80), text.length > 80 ? '...' : ''] }));
+                    })(), children] }), hasContent && (_jsx("div", { className: "eidotter-timeline-card__body", children: _jsx("div", { className: "eidotter-timeline-card__body-inner", inert: !isExpanded ? true : undefined, children: entry.content }) }))] }));
+};

package/dist/components/TimelineContainer/components/ZoomControls.d.ts

@@ -1,7 +1,6 @@
 import React from 'react';
-import type { DrillDownEntry } from './useDrillDown';
-import type { ZoomLevel } from './types';
-import './ZoomControls.css';
+import type { DrillDownEntry } from './useDrillDown.js';
+import type { ZoomLevel } from './types.js';
 export interface ZoomControlsProps {
     zoomLevel: ZoomLevel;
     canZoomIn: boolean;

package/dist/components/TimelineContainer/components/ZoomControls.js

@@ -0,0 +1,16 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button as AriaButton } from 'react-aria-components';
+import { Button } from '../../Button/components/Button.js';
+import { Badge } from '../../Badge/components/Badge.js';
+import { Breadcrumb } from '../../Breadcrumb/components/Breadcrumb.js';
+export const ZoomControls = ({ zoomLevel, canZoomIn, canZoomOut, onZoomIn, onZoomOut, onReset, breadcrumbs = [], onBreadcrumbClick, }) => {
+    const hasBreadcrumbs = breadcrumbs.length > 0;
+    return (_jsxs("div", { className: "timeline-zoom-controls", role: "toolbar", "aria-label": "Timeline zoom controls", children: [_jsx(Button, { variant: "secondary", size: "small", onClick: onZoomOut, disabled: !canZoomOut, "aria-label": "Zoom out", children: "[-]" }), hasBreadcrumbs ? (_jsx(Breadcrumb, { trail: [
+                    { label: 'ALL', onClick: onReset },
+                    ...breadcrumbs.slice(0, -1).map((entry, index) => ({
+                        label: entry.label,
+                        onClick: () => onBreadcrumbClick?.(index),
+                    })),
+                ], currentLabel: breadcrumbs[breadcrumbs.length - 1].label, showBackArrow: false, separator: ">", className: "timeline-zoom-controls__breadcrumb" })) : (_jsx(AriaButton, { className: "timeline-zoom-controls__level", onPress: onReset, "aria-label": `Current zoom: ${zoomLevel}. Click to reset.`, children: _jsx(Badge, { variant: "accent", size: "medium", children: zoomLevel.toUpperCase() }) })), _jsx(Button, { variant: "secondary", size: "small", onClick: onZoomIn, disabled: !canZoomIn, "aria-label": "Zoom in", children: "[+]" })] }));
+};

package/dist/components/TimelineContainer/components/index.d.ts

@@ -1,5 +1,5 @@
-export { TimelineContainer } from './TimelineContainer';
-export type { TimelineContainerProps } from './TimelineContainer';
-export { ZOOM_LEVELS } from './types';
-export type { TimelineEntryData, TimelineEntry, TimelineEntryRenderContext, TimelineRenderEntry, TimelineImage, DateBucket, ZoomLevel, } from './types';
-export type { DrillDownEntry, UseDrillDownReturn } from './useDrillDown';
+export { TimelineContainer } from './TimelineContainer.js';
+export type { TimelineContainerProps } from './TimelineContainer.js';
+export { ZOOM_LEVELS } from './types.js';
+export type { TimelineEntryData, TimelineEntry, TimelineEntryRenderContext, TimelineRenderEntry, TimelineImage, DateBucket, ZoomLevel, } from './types.js';
+export type { DrillDownEntry, UseDrillDownReturn } from './useDrillDown.js';

package/dist/components/TimelineContainer/components/index.js

@@ -0,0 +1,2 @@
+export { TimelineContainer } from './TimelineContainer.js';
+export { ZOOM_LEVELS } from './types.js';

package/dist/components/TimelineContainer/components/timelineUtils.d.ts

@@ -2,7 +2,7 @@
  * Timeline utility functions for grouping entries and formatting dates.
  * Pure functions with zero external dependencies — uses only native Date/Intl.
  */
-import type { TimelineEntryData, DateBucket, ZoomLevel } from './types';
+import type { TimelineEntryData, DateBucket, ZoomLevel } from './types.js';
 /** Format a full timestamp: "Mar 15, 2024 at 2:30pm" */
 export declare function formatTimestamp(iso: string): string;
 /**

package/dist/components/TimelineContainer/components/timelineUtils.js

@@ -0,0 +1,185 @@
+/**
+ * Timeline utility functions for grouping entries and formatting dates.
+ * Pure functions with zero external dependencies — uses only native Date/Intl.
+ */
+// ─── Date extraction ────────────────────────────────────────────────────────
+const MONTH_NAMES = [
+    'January', 'February', 'March', 'April', 'May', 'June',
+    'July', 'August', 'September', 'October', 'November', 'December',
+];
+const MONTH_ABBREVS = [
+    'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+    'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',
+];
+function getUTCYear(iso) {
+    return new Date(iso).getUTCFullYear();
+}
+function getUTCMonth(iso) {
+    return new Date(iso).getUTCMonth();
+}
+function getUTCDay(iso) {
+    return new Date(iso).getUTCDate();
+}
+function getUTCHour(iso) {
+    return new Date(iso).getUTCHours();
+}
+// ─── Date formatting ────────────────────────────────────────────────────────
+function formatYearLabel(year) {
+    return String(year);
+}
+function formatMonthLabel(year, month) {
+    return `${MONTH_NAMES[month]} ${year}`;
+}
+function formatDayLabel(_year, month, day) {
+    return `${MONTH_ABBREVS[month]} ${day}`;
+}
+function formatHourLabel(_year, month, day, hour) {
+    const period = hour >= 12 ? 'pm' : 'am';
+    const displayHour = hour === 0 ? 12 : hour > 12 ? hour - 12 : hour;
+    return `${MONTH_ABBREVS[month]} ${day}, ${displayHour}${period}`;
+}
+/** Format a full timestamp: "Mar 15, 2024 at 2:30pm" */
+export function formatTimestamp(iso) {
+    const d = new Date(iso);
+    const month = MONTH_ABBREVS[d.getUTCMonth()];
+    const day = d.getUTCDate();
+    const year = d.getUTCFullYear();
+    const hour = d.getUTCHours();
+    const minute = d.getUTCMinutes();
+    const period = hour >= 12 ? 'pm' : 'am';
+    const displayHour = hour === 0 ? 12 : hour > 12 ? hour - 12 : hour;
+    const minuteStr = minute > 0 ? `:${String(minute).padStart(2, '0')}` : '';
+    return `${month} ${day}, ${year} at ${displayHour}${minuteStr}${period}`;
+}
+// ─── Period start generators ────────────────────────────────────────────────
+function yearPeriodStart(year) {
+    return new Date(Date.UTC(year, 0, 1)).toISOString();
+}
+function monthPeriodStart(year, month) {
+    return new Date(Date.UTC(year, month, 1)).toISOString();
+}
+function dayPeriodStart(year, month, day) {
+    return new Date(Date.UTC(year, month, day)).toISOString();
+}
+function hourPeriodStart(year, month, day, hour) {
+    return new Date(Date.UTC(year, month, day, hour)).toISOString();
+}
+function groupBy(entries, keyFn, labelFn, periodStartFn, sortOrder) {
+    const map = new Map();
+    const keyOrder = [];
+    for (const entry of entries) {
+        const key = keyFn(entry);
+        const existing = map.get(key);
+        if (existing) {
+            existing.push(entry);
+        }
+        else {
+            map.set(key, [entry]);
+            keyOrder.push(key);
+        }
+    }
+    keyOrder.sort((a, b) => sortOrder === 'asc' ? a.localeCompare(b) : b.localeCompare(a));
+    for (const [, bucketEntries] of map) {
+        bucketEntries.sort((a, b) => {
+            const cmp = a.date.localeCompare(b.date);
+            return sortOrder === 'asc' ? cmp : -cmp;
+        });
+    }
+    return keyOrder.map(key => ({
+        label: labelFn(key),
+        periodStart: periodStartFn(key),
+        entries: map.get(key) ?? [],
+    }));
+}
+function yearKey(entry) {
+    return String(getUTCYear(entry.date));
+}
+function monthKey(entry) {
+    const y = getUTCYear(entry.date);
+    const m = getUTCMonth(entry.date);
+    return `${y}-${String(m).padStart(2, '0')}`;
+}
+function dayKey(entry) {
+    const y = getUTCYear(entry.date);
+    const m = getUTCMonth(entry.date);
+    const d = getUTCDay(entry.date);
+    return `${y}-${String(m).padStart(2, '0')}-${String(d).padStart(2, '0')}`;
+}
+function hourKey(entry) {
+    const y = getUTCYear(entry.date);
+    const m = getUTCMonth(entry.date);
+    const d = getUTCDay(entry.date);
+    const h = getUTCHour(entry.date);
+    return `${y}-${String(m).padStart(2, '0')}-${String(d).padStart(2, '0')}-${String(h).padStart(2, '0')}`;
+}
+function parseYearKey(key) {
+    return { year: parseInt(key) };
+}
+function parseMonthKey(key) {
+    const [y, m] = key.split('-');
+    return { year: parseInt(y), month: parseInt(m) };
+}
+function parseDayKey(key) {
+    const [y, m, d] = key.split('-');
+    return { year: parseInt(y), month: parseInt(m), day: parseInt(d) };
+}
+function parseHourKey(key) {
+    const [y, m, d, h] = key.split('-');
+    return { year: parseInt(y), month: parseInt(m), day: parseInt(d), hour: parseInt(h) };
+}
+// ─── Drill-down filtering ──────────────────────────────────────────────────
+/** Prefix lengths for ISO string matching by parent zoom level */
+const PERIOD_PREFIX_LENGTH = {
+    year: 4, // "2024"
+    month: 7, // "2024-03"
+    day: 10, // "2024-03-15"
+};
+/**
+ * Filter buckets to only those within a drilled-into period.
+ * Uses ISO string prefix matching: a year prefix "2024" matches
+ * any periodStart starting with "2024", etc.
+ *
+ * @param buckets - All buckets at the current zoom level
+ * @param periodStart - The parent period's periodStart, or null for no filter
+ * @param parentZoomLevel - The zoom level of the parent period
+ * @returns Filtered buckets (or all buckets if no filter applies)
+ */
+export function filterBucketsByPeriod(buckets, periodStart, parentZoomLevel) {
+    if (periodStart === null)
+        return buckets;
+    if (parentZoomLevel === 'hour')
+        return buckets;
+    const prefixLen = PERIOD_PREFIX_LENGTH[parentZoomLevel];
+    if (prefixLen === undefined)
+        return buckets;
+    const prefix = periodStart.slice(0, prefixLen);
+    return buckets.filter(b => b.periodStart.slice(0, prefixLen) === prefix);
+}
+// ─── Grouping ──────────────────────────────────────────────────────────────
+/**
+ * Group timeline entries into DateBuckets based on the current zoom level.
+ */
+export function groupEntriesByZoom(entries, zoomLevel, sortOrder = 'desc') {
+    if (entries.length === 0)
+        return [];
+    // Filter entries with invalid dates to prevent NaN bucket keys
+    const valid = entries.filter(e => !isNaN(new Date(e.date).getTime()));
+    if (valid.length === 0)
+        return [];
+    switch (zoomLevel) {
+        case 'year':
+            return groupBy(valid, yearKey, key => { const { year } = parseYearKey(key); return formatYearLabel(year); }, key => { const { year } = parseYearKey(key); return yearPeriodStart(year); }, sortOrder);
+        case 'month':
+            return groupBy(valid, monthKey, key => { const { year, month } = parseMonthKey(key); return formatMonthLabel(year, month); }, key => { const { year, month } = parseMonthKey(key); return monthPeriodStart(year, month); }, sortOrder);
+        case 'day':
+            return groupBy(valid, dayKey, key => { const { year, month, day } = parseDayKey(key); return formatDayLabel(year, month, day); }, key => { const { year, month, day } = parseDayKey(key); return dayPeriodStart(year, month, day); }, sortOrder);
+        case 'hour':
+            return groupBy(valid, hourKey, key => {
+                const { year, month, day, hour } = parseHourKey(key);
+                return formatHourLabel(year, month, day, hour);
+            }, key => {
+                const { year, month, day, hour } = parseHourKey(key);
+                return hourPeriodStart(year, month, day, hour);
+            }, sortOrder);
+    }
+}

package/dist/components/TimelineContainer/components/types.js

@@ -0,0 +1,7 @@
+/**
+ * Shared type definitions for TimelineContainer.
+ * Extracted to a separate file to avoid circular imports between
+ * the component, hooks, and view sub-components.
+ */
+/** Ordered zoom levels from least to most detail */
+export const ZOOM_LEVELS = ['year', 'month', 'day', 'hour'];

package/dist/components/TimelineContainer/components/useDrillDown.d.ts

@@ -1,4 +1,4 @@
-import type { ZoomLevel } from './types';
+import type { ZoomLevel } from './types.js';
 export interface DrillDownEntry {
     /** ISO period start for this drill-down level */
     periodStart: string;

package/dist/components/TimelineContainer/components/useDrillDown.js

@@ -0,0 +1,83 @@
+'use client';
+import { useState, useCallback, useEffect, useRef } from 'react';
+import { ZOOM_LEVELS } from './types.js';
+/**
+ * Manages drill-down navigation with a breadcrumb stack.
+ * When zoom is uncontrolled, maintains its own zoom state so that
+ * reset() can go directly to 'year' (the outermost level).
+ * When zoom is controlled externally, drill-down is disabled.
+ */
+export function useDrillDown({ zoomLevel: controlledLevel, defaultZoomLevel = 'month', onZoomChange, } = {}) {
+    const isDrillDownEnabled = controlledLevel === undefined;
+    const [internalLevel, setInternalLevel] = useState(defaultZoomLevel);
+    const [breadcrumbs, setBreadcrumbs] = useState([]);
+    // Clear breadcrumbs when transitioning from uncontrolled to controlled mode
+    const prevEnabledRef = useRef(isDrillDownEnabled);
+    useEffect(() => {
+        if (prevEnabledRef.current && !isDrillDownEnabled) {
+            setBreadcrumbs([]);
+        }
+        prevEnabledRef.current = isDrillDownEnabled;
+    }, [isDrillDownEnabled]);
+    const currentLevel = controlledLevel ?? internalLevel;
+    const currentIndex = ZOOM_LEVELS.indexOf(currentLevel);
+    const canZoomIn = currentIndex < ZOOM_LEVELS.length - 1;
+    const canZoomOut = currentIndex > 0;
+    const currentPeriod = breadcrumbs.length > 0
+        ? breadcrumbs[breadcrumbs.length - 1].periodStart
+        : null;
+    // Refs for stable callbacks
+    const isDrillDownEnabledRef = useRef(isDrillDownEnabled);
+    const canZoomInRef = useRef(canZoomIn);
+    const currentIndexRef = useRef(currentIndex);
+    const breadcrumbsRef = useRef(breadcrumbs);
+    const onZoomChangeRef = useRef(onZoomChange);
+    useEffect(() => {
+        isDrillDownEnabledRef.current = isDrillDownEnabled;
+        canZoomInRef.current = canZoomIn;
+        currentIndexRef.current = currentIndex;
+        breadcrumbsRef.current = breadcrumbs;
+        onZoomChangeRef.current = onZoomChange;
+    });
+    const updateLevel = useCallback((level) => {
+        if (isDrillDownEnabledRef.current) {
+            setInternalLevel(level);
+        }
+        onZoomChangeRef.current?.(level);
+    }, []);
+    const drillDown = useCallback((periodStart, label) => {
+        if (!isDrillDownEnabledRef.current || !canZoomInRef.current)
+            return;
+        const nextLevel = ZOOM_LEVELS[currentIndexRef.current + 1];
+        if (nextLevel !== undefined) {
+            setBreadcrumbs(prev => [...prev, { periodStart, label }]);
+            updateLevel(nextLevel);
+        }
+    }, [updateLevel]);
+    const drillUp = useCallback(() => {
+        if (!isDrillDownEnabledRef.current || breadcrumbsRef.current.length === 0)
+            return;
+        const prevLevel = ZOOM_LEVELS[currentIndexRef.current - 1];
+        if (prevLevel !== undefined) {
+            setBreadcrumbs(prev => prev.slice(0, -1));
+            updateLevel(prevLevel);
+        }
+    }, [updateLevel]);
+    const reset = useCallback(() => {
+        if (!isDrillDownEnabledRef.current)
+            return;
+        setBreadcrumbs([]);
+        updateLevel('year');
+    }, [updateLevel]);
+    return {
+        zoomLevel: currentLevel,
+        canZoomIn,
+        canZoomOut,
+        breadcrumbs,
+        currentPeriod,
+        isDrillDownEnabled,
+        drillDown,
+        drillUp,
+        reset,
+    };
+}

package/dist/components/TimelineContainer/components/useSelection.js

@@ -0,0 +1,51 @@
+'use client';
+import { useState, useCallback, useEffect, useRef } from 'react';
+/**
+ * Manages entry selection with controlled/uncontrolled pattern.
+ */
+export function useSelection({ selectedEntryId: controlledId, defaultSelectedEntryId = null, onSelectEntry, } = {}) {
+    const [internalId, setInternalId] = useState(defaultSelectedEntryId);
+    // Inline narrowing — undefined means uncontrolled, null means controlled-with-nothing-selected
+    const isControlled = controlledId !== undefined;
+    const currentId = controlledId !== undefined ? controlledId : internalId;
+    // Refs for stable toggle callback
+    const currentIdRef = useRef(currentId);
+    const isControlledRef = useRef(isControlled);
+    const onSelectEntryRef = useRef(onSelectEntry);
+    useEffect(() => {
+        currentIdRef.current = currentId;
+        isControlledRef.current = isControlled;
+        onSelectEntryRef.current = onSelectEntry;
+    });
+    const updateSelection = useCallback((id) => {
+        if (!isControlledRef.current) {
+            setInternalId(id);
+        }
+        onSelectEntryRef.current?.(id);
+    }, []);
+    const select = useCallback((entryId) => {
+        updateSelection(entryId);
+    }, [updateSelection]);
+    const deselect = useCallback(() => {
+        updateSelection(null);
+    }, [updateSelection]);
+    // Stable toggle — uses ref to avoid closing over currentId
+    const toggle = useCallback((entryId) => {
+        if (isControlledRef.current) {
+            onSelectEntryRef.current?.(currentIdRef.current === entryId ? null : entryId);
+        }
+        else {
+            setInternalId(prev => {
+                const newId = prev === entryId ? null : entryId;
+                onSelectEntryRef.current?.(newId);
+                return newId;
+            });
+        }
+    }, []);
+    return {
+        selectedEntryId: currentId,
+        select,
+        deselect,
+        toggle,
+    };
+}

package/dist/components/TimelineContainer/components/useZoom.d.ts

@@ -1,4 +1,4 @@
-import type { ZoomLevel } from './types';
+import type { ZoomLevel } from './types.js';
 export interface UseZoomOptions {
     zoomLevel?: ZoomLevel;
     defaultZoomLevel?: ZoomLevel;

package/dist/components/TimelineContainer/components/useZoom.js

@@ -0,0 +1,54 @@
+'use client';
+import { useState, useCallback, useEffect, useRef } from 'react';
+import { ZOOM_LEVELS } from './types.js';
+/**
+ * Manages zoom level with controlled/uncontrolled pattern.
+ * Zoom "in" means more detail (year -> month -> day -> hour).
+ */
+export function useZoom({ zoomLevel: controlledLevel, defaultZoomLevel = 'month', onZoomChange, } = {}) {
+    const [internalLevel, setInternalLevel] = useState(defaultZoomLevel);
+    // Inline narrowing — TS cannot narrow through an extracted boolean variable
+    const currentLevel = controlledLevel ?? internalLevel;
+    const isControlled = controlledLevel !== undefined;
+    const currentIndex = ZOOM_LEVELS.indexOf(currentLevel);
+    const canZoomIn = currentIndex < ZOOM_LEVELS.length - 1;
+    const canZoomOut = currentIndex > 0;
+    // Store current values in refs for stable callbacks (prevents listener churn)
+    const currentIndexRef = useRef(currentIndex);
+    const isControlledRef = useRef(isControlled);
+    const onZoomChangeRef = useRef(onZoomChange);
+    useEffect(() => {
+        currentIndexRef.current = currentIndex;
+        isControlledRef.current = isControlled;
+        onZoomChangeRef.current = onZoomChange;
+    });
+    const updateLevel = useCallback((level) => {
+        if (!isControlledRef.current) {
+            setInternalLevel(level);
+        }
+        onZoomChangeRef.current?.(level);
+    }, []);
+    const zoomIn = useCallback(() => {
+        const nextLevel = ZOOM_LEVELS[currentIndexRef.current + 1];
+        if (nextLevel !== undefined) {
+            updateLevel(nextLevel);
+        }
+    }, [updateLevel]);
+    const zoomOut = useCallback(() => {
+        const prevLevel = ZOOM_LEVELS[currentIndexRef.current - 1];
+        if (prevLevel !== undefined) {
+            updateLevel(prevLevel);
+        }
+    }, [updateLevel]);
+    const reset = useCallback(() => {
+        updateLevel(defaultZoomLevel);
+    }, [defaultZoomLevel, updateLevel]);
+    return {
+        zoomLevel: currentLevel,
+        zoomIn,
+        zoomOut,
+        reset,
+        canZoomIn,
+        canZoomOut,
+    };
+}

package/dist/components/TimelineContainer/components/variants/TimelineEntryCardGallery.d.ts

@@ -1,6 +1,5 @@
 import React from 'react';
-import type { TimelineEntryData } from '../types';
-import './TimelineEntryCardGallery.css';
+import type { TimelineEntryData } from '../types.js';
 type GalleryEntry = Extract<TimelineEntryData, {
     kind: 'gallery';
 }>;

package/dist/components/TimelineContainer/components/variants/TimelineEntryCardGallery.js

@@ -0,0 +1,67 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { Button as AriaButton } from 'react-aria-components';
+import { Lightbox } from '../../../Lightbox/index.js';
+import { cn } from '../../../../utils/cn.js';
+import { isSafeHref } from '../../../../utils/isSafeHref.js';
+/**
+ * Gallery variant of TimelineEntryCard. iOS Photos two-stage interaction:
+ * grid → focused (grow-in-place) → lightbox. Resets to grid on parent
+ * collapse via useEffect on `isExpanded`.
+ */
+export const TimelineEntryCardGallery = ({ entry, isExpanded, onSelect, }) => {
+    const [state, setState] = useState({ phase: 'grid' });
+    // Reset when the parent card collapses, so re-expanding starts at grid.
+    useEffect(() => {
+        if (!isExpanded)
+            setState({ phase: 'grid' });
+    }, [isExpanded]);
+    // Re-validate state.index when entry.images shrinks — otherwise a stale
+    // index can feed an out-of-range value into the Lightbox below.
+    useEffect(() => {
+        setState((prev) => {
+            if (prev.phase === 'grid')
+                return prev;
+            if (prev.index >= entry.images.length)
+                return { phase: 'grid' };
+            return prev;
+        });
+    }, [entry.images.length]);
+    if (entry.images.length === 0) {
+        if (process.env.NODE_ENV !== 'production') {
+            console.error(`[eidotter] TimelineEntryCard kind="gallery" entry "${entry.id}" has no images.`);
+        }
+        return (_jsxs(_Fragment, { children: [_jsx("p", { className: "eidotter-timeline-card__title", children: entry.title }), _jsx("p", { className: "eidotter-timeline-card-gallery__empty", children: "No images." })] }));
+    }
+    const handleThumbClick = (index, image) => {
+        // Only short-circuit when the link will actually render as a navigable
+        // anchor — unsafe schemes are stripped by GalleryThumb, in which case
+        // the thumb falls back to the focus/lightbox interaction.
+        if (image.link && isSafeHref(image.link))
+            return;
+        setState((prev) => {
+            if (prev.phase === 'focused' && prev.index === index) {
+                return { phase: 'lightbox', index };
+            }
+            return { phase: 'focused', index };
+        });
+    };
+    const focusedIndex = state.phase === 'focused' || state.phase === 'lightbox' ? state.index : null;
+    return (_jsxs(_Fragment, { children: [_jsx(AriaButton, { className: "eidotter-timeline-card__trigger", onPress: () => onSelect?.(entry.id), "aria-expanded": isExpanded, children: _jsx("p", { className: "eidotter-timeline-card__title", children: entry.title }) }), _jsx("div", { className: "eidotter-timeline-card-gallery__grid", role: "list", children: entry.images.map((img, i) => (_jsx(GalleryThumb, { image: img, isFocused: focusedIndex === i, onClick: () => handleThumbClick(i, img) }, i))) }), _jsx(Lightbox, { images: entry.images, isOpen: state.phase === 'lightbox', initialIndex: state.phase === 'lightbox' ? state.index : 0, onClose: () => {
+                    setState((prev) => prev.phase === 'lightbox' ? { phase: 'focused', index: prev.index } : prev);
+                }, onIndexChange: (idx) => {
+                    setState((prev) => prev.phase === 'lightbox' ? { phase: 'lightbox', index: idx } : prev);
+                } })] }));
+};
+const GalleryThumb = ({ image, isFocused, onClick }) => {
+    const src = image.thumbnail || image.src;
+    const linkHref = image.link && isSafeHref(image.link) ? image.link : undefined;
+    // Outer listitem wraps either an anchor (link mode) or a button (interactive
+    // focus/lightbox mode). The listitem semantics live on the outer wrapper so
+    // both modes participate in the parent role="list" consistently.
+    if (linkHref) {
+        return (_jsx("div", { role: "listitem", className: "eidotter-timeline-card-gallery__cell eidotter-timeline-card-gallery__cell--link", children: _jsx("a", { className: "eidotter-timeline-card-gallery__link", href: linkHref, rel: "noopener noreferrer", children: _jsx("img", { className: "eidotter-timeline-card-gallery__img", src: src, alt: image.alt, width: image.width, height: image.height }) }) }));
+    }
+    return (_jsx("div", { role: "listitem", className: cn('eidotter-timeline-card-gallery__cell', isFocused && 'eidotter-timeline-card-gallery__cell--focused'), children: _jsx(AriaButton, { className: "eidotter-timeline-card-gallery__button", onPress: onClick, "aria-label": image.alt || 'Image', "aria-pressed": isFocused, children: _jsx("img", { className: "eidotter-timeline-card-gallery__img", src: src, alt: image.alt, width: image.width, height: image.height }) }) }));
+};

package/dist/components/TimelineContainer/components/variants/TimelineEntryCardImage.d.ts

@@ -1,6 +1,5 @@
 import React from 'react';
-import type { TimelineEntryData } from '../types';
-import './TimelineEntryCardImage.css';
+import type { TimelineEntryData } from '../types.js';
 type ImageEntry = Extract<TimelineEntryData, {
     kind: 'image';
 }>;

package/dist/components/TimelineContainer/components/variants/TimelineEntryCardImage.js

@@ -0,0 +1,31 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { Button as AriaButton } from 'react-aria-components';
+import { Lightbox } from '../../../Lightbox/index.js';
+import { isSafeHref } from '../../../../utils/isSafeHref.js';
+/**
+ * Image variant of TimelineEntryCard.
+ *
+ * Collapsed: title + thumbnail. Expanded: title + full-width image. Click on
+ * the expanded image opens a Lightbox. If `entry.image.link` is set and uses
+ * a safe scheme (http/https/mailto/relative), the thumbnail is wrapped in a
+ * plain anchor and clicks navigate out — no expansion, no lightbox.
+ */
+export const TimelineEntryCardImage = ({ entry, isExpanded, onSelect, }) => {
+    const [lightboxOpen, setLightboxOpen] = useState(false);
+    const { image } = entry;
+    const thumbSrc = image.thumbnail || image.src;
+    const linkHref = image.link && isSafeHref(image.link) ? image.link : undefined;
+    // Reset lightbox state when the parent card collapses, mirroring Gallery's
+    // useEffect — otherwise the modal stays mounted detached from a collapsed card.
+    useEffect(() => {
+        if (!isExpanded)
+            setLightboxOpen(false);
+    }, [isExpanded]);
+    // link mode — render as a plain anchor and exit early.
+    if (linkHref) {
+        return (_jsxs("a", { className: "eidotter-timeline-card-image eidotter-timeline-card-image--link", href: linkHref, rel: "noopener noreferrer", children: [_jsx("p", { className: "eidotter-timeline-card__title", children: entry.title }), _jsx("img", { className: "eidotter-timeline-card-image__media", src: thumbSrc, alt: image.alt, width: image.width, height: image.height })] }));
+    }
+    return (_jsxs(_Fragment, { children: [_jsx(AriaButton, { className: "eidotter-timeline-card__trigger", onPress: () => onSelect?.(entry.id), "aria-expanded": isExpanded, children: _jsx("p", { className: "eidotter-timeline-card__title", children: entry.title }) }), _jsx("div", { className: "eidotter-timeline-card-image", children: isExpanded ? (_jsx(AriaButton, { className: "eidotter-timeline-card-image__media-button", onPress: () => setLightboxOpen(true), "aria-label": image.alt ? `Open ${image.alt} in lightbox` : 'Open image in lightbox', children: _jsx("img", { className: "eidotter-timeline-card-image__media eidotter-timeline-card-image__media--expanded", src: image.src, alt: image.alt, width: image.width, height: image.height }) })) : (_jsx("img", { className: "eidotter-timeline-card-image__media eidotter-timeline-card-image__media--thumb", src: thumbSrc, alt: image.alt, width: image.width, height: image.height })) }), _jsx(Lightbox, { images: [image], isOpen: lightboxOpen, onClose: () => setLightboxOpen(false) })] }));
+};

package/dist/components/TimelineContainer/components/views/DayView.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import type { TimelineViewProps } from '../types';
+import type { TimelineViewProps } from '../types.js';
 /**
  * Day-level zoom view: shows day labels with entry cards and content preview.
  */