@pokit/reporter-web 0.0.1

package/dist/hooks.js

@@ -0,0 +1,201 @@
+/**
+ * Reporter Web React Hooks
+ *
+ * React hooks for subscribing to reporter state using useSyncExternalStore.
+ * Provides full state subscription and selective subscriptions for individual
+ * activities and groups.
+ */
+import { useSyncExternalStore, useCallback, useRef } from 'react';
+/**
+ * Subscribe to the full reporter state
+ *
+ * @param store - The reporter store
+ * @returns Current reporter state
+ *
+ * @example
+ * ```tsx
+ * const state = useReporterState(store);
+ * return <div>Status: {state.root.status}</div>;
+ * ```
+ */
+export function useReporterState(store) {
+    return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
+}
+/**
+ * Subscribe to a single activity by ID
+ * Returns undefined if activity doesn't exist
+ *
+ * @param store - The reporter store
+ * @param id - Activity ID to subscribe to
+ * @returns Activity state or undefined
+ *
+ * @example
+ * ```tsx
+ * const activity = useActivity(store, 'task-1');
+ * if (!activity) return null;
+ * return <div>{activity.label}: {activity.status}</div>;
+ * ```
+ */
+export function useActivity(store, id) {
+    // Track the previous activity reference for shallow comparison
+    const prevActivityRef = useRef(undefined);
+    const getSnapshot = useCallback(() => {
+        const state = store.getSnapshot();
+        const activity = state.activities.get(id);
+        // Return same reference if activity hasn't changed (shallow comparison)
+        if (prevActivityRef.current === activity) {
+            return prevActivityRef.current;
+        }
+        // Check if activity content is the same (for Map recreation scenarios)
+        if (prevActivityRef.current &&
+            activity &&
+            prevActivityRef.current.id === activity.id &&
+            prevActivityRef.current.status === activity.status &&
+            prevActivityRef.current.progress === activity.progress &&
+            prevActivityRef.current.message === activity.message &&
+            prevActivityRef.current.justStarted === activity.justStarted &&
+            prevActivityRef.current.justCompleted === activity.justCompleted &&
+            prevActivityRef.current.justFailed === activity.justFailed &&
+            prevActivityRef.current.completedAt === activity.completedAt) {
+            return prevActivityRef.current;
+        }
+        prevActivityRef.current = activity;
+        return activity;
+    }, [store, id]);
+    const getServerSnapshot = useCallback(() => {
+        return store.getServerSnapshot().activities.get(id);
+    }, [store, id]);
+    return useSyncExternalStore(store.subscribe, getSnapshot, getServerSnapshot);
+}
+/**
+ * Subscribe to a single group by ID
+ * Returns undefined if group doesn't exist
+ *
+ * @param store - The reporter store
+ * @param id - Group ID to subscribe to
+ * @returns Group state or undefined
+ *
+ * @example
+ * ```tsx
+ * const group = useGroup(store, 'checks');
+ * if (!group) return null;
+ * return <div>{group.label} ({group.activityIds.length} tasks)</div>;
+ * ```
+ */
+export function useGroup(store, id) {
+    // Track the previous group reference for shallow comparison
+    const prevGroupRef = useRef(undefined);
+    const getSnapshot = useCallback(() => {
+        const state = store.getSnapshot();
+        const group = state.groups.get(id);
+        // Return same reference if group hasn't changed
+        if (prevGroupRef.current === group) {
+            return prevGroupRef.current;
+        }
+        // Check if group content is the same (for Map recreation scenarios)
+        if (prevGroupRef.current &&
+            group &&
+            prevGroupRef.current.id === group.id &&
+            prevGroupRef.current.label === group.label &&
+            prevGroupRef.current.hasFailure === group.hasFailure &&
+            prevGroupRef.current.justStarted_group === group.justStarted_group &&
+            prevGroupRef.current.justEnded === group.justEnded &&
+            prevGroupRef.current.endedAt === group.endedAt &&
+            prevGroupRef.current.activityIds.length === group.activityIds.length &&
+            prevGroupRef.current.childGroupIds.length === group.childGroupIds.length) {
+            return prevGroupRef.current;
+        }
+        prevGroupRef.current = group;
+        return group;
+    }, [store, id]);
+    const getServerSnapshot = useCallback(() => {
+        return store.getServerSnapshot().groups.get(id);
+    }, [store, id]);
+    return useSyncExternalStore(store.subscribe, getSnapshot, getServerSnapshot);
+}
+/**
+ * Subscribe to root state only
+ * More efficient than useReporterState when you only need root info
+ *
+ * @param store - The reporter store
+ * @returns Root state
+ *
+ * @example
+ * ```tsx
+ * const root = useRootState(store);
+ * return <div>App: {root.appName} - {root.status}</div>;
+ * ```
+ */
+export function useRootState(store) {
+    const prevRootRef = useRef(undefined);
+    const getSnapshot = useCallback(() => {
+        const state = store.getSnapshot();
+        const root = state.root;
+        // Return same reference if root hasn't changed
+        if (prevRootRef.current &&
+            prevRootRef.current.status === root.status &&
+            prevRootRef.current.appName === root.appName &&
+            prevRootRef.current.exitCode === root.exitCode) {
+            return prevRootRef.current;
+        }
+        prevRootRef.current = root;
+        return root;
+    }, [store]);
+    const getServerSnapshot = useCallback(() => {
+        return store.getServerSnapshot().root;
+    }, [store]);
+    return useSyncExternalStore(store.subscribe, getSnapshot, getServerSnapshot);
+}
+/**
+ * Subscribe to logs
+ * Returns the full log array
+ *
+ * @param store - The reporter store
+ * @returns Array of log entries
+ *
+ * @example
+ * ```tsx
+ * const logs = useLogs(store);
+ * return (
+ *   <ul>
+ *     {logs.map(log => <li key={log.id}>{log.message}</li>)}
+ *   </ul>
+ * );
+ * ```
+ */
+export function useLogs(store) {
+    const prevLogsRef = useRef(undefined);
+    const getSnapshot = useCallback(() => {
+        const state = store.getSnapshot();
+        const logs = state.logs;
+        // Return same reference if logs haven't changed
+        if (prevLogsRef.current && prevLogsRef.current.length === logs.length) {
+            // Quick check - if lengths match and last item is same, assume unchanged
+            if (logs.length === 0 ||
+                prevLogsRef.current[logs.length - 1]?.id === logs[logs.length - 1]?.id) {
+                return prevLogsRef.current;
+            }
+        }
+        prevLogsRef.current = logs;
+        return logs;
+    }, [store]);
+    const getServerSnapshot = useCallback(() => {
+        return store.getServerSnapshot().logs;
+    }, [store]);
+    return useSyncExternalStore(store.subscribe, getSnapshot, getServerSnapshot);
+}
+/**
+ * Subscribe to suspended state
+ *
+ * @param store - The reporter store
+ * @returns Whether reporter is suspended
+ */
+export function useSuspended(store) {
+    const getSnapshot = useCallback(() => {
+        return store.getSnapshot().suspended;
+    }, [store]);
+    const getServerSnapshot = useCallback(() => {
+        return store.getServerSnapshot().suspended;
+    }, [store]);
+    return useSyncExternalStore(store.subscribe, getSnapshot, getServerSnapshot);
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @pokit/reporter-web
+ *
+ * Web/React implementation of the ReporterAdapter interface.
+ * Provides a store for state management and React hooks for subscription.
+ */
+export { createReporterStore } from './store';
+export type { CreateReporterStoreOptions, ReporterStoreWithHandler } from './store';
+export { createWebReporterAdapter } from './adapter';
+export { useReporterState, useActivity, useGroup, useRootState, useLogs, useSuspended, } from './hooks';
+export type { RootStatus, ActivityStatus, TemporalMarkers, ActivityState, GroupState, LogEntry, RootState, ReporterState, StateListener, ReporterStore, } from './types';
+export { TutorialStep, FilePreview, CommandBlock, ProgressIndicator, ContentBox, } from './components';
+export type { TutorialStepProps, TutorialStepStatus, FilePreviewProps, FilePreviewStatus, FilePreviewActionProps, CommandBlockProps, CommandBlockStatus, CommandBlockActionProps, ProgressIndicatorProps, ContentBoxProps, ContentBoxVariant, } from './components';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAC9C,YAAY,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAGpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAGrD,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,OAAO,EACP,YAAY,GACb,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,UAAU,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,UAAU,EACV,QAAQ,EACR,SAAS,EACT,aAAa,EACb,aAAa,EACb,aAAa,GACd,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,EACtB,eAAe,EACf,iBAAiB,GAClB,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @pokit/reporter-web
+ *
+ * Web/React implementation of the ReporterAdapter interface.
+ * Provides a store for state management and React hooks for subscription.
+ */
+// Store
+export { createReporterStore } from './store';
+// Adapter
+export { createWebReporterAdapter } from './adapter';
+// Hooks
+export { useReporterState, useActivity, useGroup, useRootState, useLogs, useSuspended, } from './hooks';
+// Components
+export { TutorialStep, FilePreview, CommandBlock, ProgressIndicator, ContentBox, } from './components';

package/dist/store.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Reporter Web Store
+ *
+ * Creates an external store for React integration.
+ * Handles all CLIEvent types and maintains normalized state.
+ */
+import type { CLIEvent } from '@pokit/core';
+import type { ReporterStore } from './types';
+/**
+ * Options for creating a reporter store
+ */
+export type CreateReporterStoreOptions = {
+    /** Custom delay for clearing temporal markers (default: 600ms) */
+    temporalMarkerDelay?: number;
+    /** Disable temporal marker auto-clearing (useful for testing) */
+    disableTemporalMarkerClearing?: boolean;
+};
+/**
+ * Type for the store with internal event handler exposed
+ */
+export type ReporterStoreWithHandler = ReporterStore & {
+    _handleEvent: (event: CLIEvent) => void;
+};
+/**
+ * Create a reporter store for React integration
+ *
+ * @param options - Optional configuration
+ * @returns Store compatible with useSyncExternalStore
+ */
+export declare function createReporterStore(options?: CreateReporterStoreOptions): ReporterStoreWithHandler;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAuB,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EAEV,aAAa,EAKd,MAAM,SAAS,CAAC;AAuBjB;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,kEAAkE;IAClE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iEAAiE;IACjE,6BAA6B,CAAC,EAAE,OAAO,CAAC;CACzC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,aAAa,GAAG;IACrD,YAAY,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;CACzC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,0BAA0B,GAAG,wBAAwB,CAgWlG"}

package/dist/store.js

@@ -0,0 +1,345 @@
+/**
+ * Reporter Web Store
+ *
+ * Creates an external store for React integration.
+ * Handles all CLIEvent types and maintains normalized state.
+ */
+/** Default delay for clearing temporal markers (ms) */
+const TEMPORAL_MARKER_DELAY = 600;
+/** Counter for generating unique log IDs */
+let logIdCounter = 0;
+/**
+ * Create initial reporter state
+ */
+function createInitialState() {
+    return {
+        root: {
+            status: 'idle',
+        },
+        groups: new Map(),
+        activities: new Map(),
+        logs: [],
+        suspended: false,
+    };
+}
+/**
+ * Create a reporter store for React integration
+ *
+ * @param options - Optional configuration
+ * @returns Store compatible with useSyncExternalStore
+ */
+export function createReporterStore(options) {
+    const temporalMarkerDelay = options?.temporalMarkerDelay ?? TEMPORAL_MARKER_DELAY;
+    const disableTemporalMarkerClearing = options?.disableTemporalMarkerClearing ?? false;
+    let state = createInitialState();
+    const listeners = new Set();
+    /**
+     * Notify all listeners of state change
+     */
+    function notifyListeners() {
+        for (const listener of listeners) {
+            listener();
+        }
+    }
+    /**
+     * Schedule clearing of temporal markers for an activity
+     */
+    function scheduleActivityMarkerClear(activityId, markers) {
+        if (disableTemporalMarkerClearing)
+            return;
+        setTimeout(() => {
+            const activity = state.activities.get(activityId);
+            if (!activity)
+                return;
+            // Check if any markers are still set
+            const hasMarkers = markers.some((marker) => activity[marker]);
+            if (!hasMarkers)
+                return;
+            // Create new state with cleared markers
+            const updatedActivity = { ...activity };
+            for (const marker of markers) {
+                delete updatedActivity[marker];
+            }
+            const newActivities = new Map(state.activities);
+            newActivities.set(activityId, updatedActivity);
+            state = {
+                ...state,
+                activities: newActivities,
+            };
+            notifyListeners();
+        }, temporalMarkerDelay);
+    }
+    /**
+     * Schedule clearing of temporal markers for a group
+     */
+    function scheduleGroupMarkerClear(groupId, markers) {
+        if (disableTemporalMarkerClearing)
+            return;
+        setTimeout(() => {
+            const group = state.groups.get(groupId);
+            if (!group)
+                return;
+            // Check if any markers are still set
+            const hasMarkers = markers.some((marker) => group[marker]);
+            if (!hasMarkers)
+                return;
+            // Create new state with cleared markers
+            const updatedGroup = { ...group };
+            for (const marker of markers) {
+                delete updatedGroup[marker];
+            }
+            const newGroups = new Map(state.groups);
+            newGroups.set(groupId, updatedGroup);
+            state = {
+                ...state,
+                groups: newGroups,
+            };
+            notifyListeners();
+        }, temporalMarkerDelay);
+    }
+    /**
+     * Handle a CLI event and update state
+     */
+    function handleEvent(event) {
+        switch (event.type) {
+            case 'root:start': {
+                state = {
+                    ...state,
+                    root: {
+                        status: 'running',
+                        appName: event.appName,
+                        version: event.version,
+                        startedAt: Date.now(),
+                    },
+                };
+                notifyListeners();
+                break;
+            }
+            case 'root:end': {
+                state = {
+                    ...state,
+                    root: {
+                        ...state.root,
+                        status: event.exitCode === 0 ? 'complete' : 'error',
+                        exitCode: event.exitCode,
+                        endedAt: Date.now(),
+                    },
+                };
+                notifyListeners();
+                break;
+            }
+            case 'group:start': {
+                const newGroup = {
+                    id: event.id,
+                    parentId: event.parentId,
+                    label: event.label,
+                    layout: event.layout,
+                    activityIds: [],
+                    childGroupIds: [],
+                    hasFailure: false,
+                    startedAt: Date.now(),
+                    justStarted_group: true,
+                };
+                const newGroups = new Map(state.groups);
+                newGroups.set(event.id, newGroup);
+                // Add to parent's childGroupIds if parent exists
+                if (event.parentId) {
+                    const parent = state.groups.get(event.parentId);
+                    if (parent) {
+                        newGroups.set(event.parentId, {
+                            ...parent,
+                            childGroupIds: [...parent.childGroupIds, event.id],
+                        });
+                    }
+                }
+                state = {
+                    ...state,
+                    groups: newGroups,
+                };
+                notifyListeners();
+                scheduleGroupMarkerClear(event.id, ['justStarted_group']);
+                break;
+            }
+            case 'group:end': {
+                const group = state.groups.get(event.id);
+                if (!group)
+                    break;
+                const newGroups = new Map(state.groups);
+                newGroups.set(event.id, {
+                    ...group,
+                    endedAt: Date.now(),
+                    justEnded: true,
+                });
+                state = {
+                    ...state,
+                    groups: newGroups,
+                };
+                notifyListeners();
+                scheduleGroupMarkerClear(event.id, ['justEnded']);
+                break;
+            }
+            case 'activity:start': {
+                const newActivity = {
+                    id: event.id,
+                    parentId: event.parentId,
+                    label: event.label,
+                    status: 'running',
+                    meta: event.meta,
+                    startedAt: Date.now(),
+                    justStarted: true,
+                };
+                const newActivities = new Map(state.activities);
+                newActivities.set(event.id, newActivity);
+                // Add to parent group's activityIds if parent is a group
+                const newGroups = new Map(state.groups);
+                if (event.parentId) {
+                    const parentGroup = state.groups.get(event.parentId);
+                    if (parentGroup) {
+                        newGroups.set(event.parentId, {
+                            ...parentGroup,
+                            activityIds: [...parentGroup.activityIds, event.id],
+                        });
+                    }
+                }
+                state = {
+                    ...state,
+                    activities: newActivities,
+                    groups: newGroups,
+                };
+                notifyListeners();
+                scheduleActivityMarkerClear(event.id, ['justStarted']);
+                break;
+            }
+            case 'activity:update': {
+                const activity = state.activities.get(event.id);
+                if (!activity)
+                    break;
+                const { progress, message, ...rest } = event.payload;
+                const newActivities = new Map(state.activities);
+                newActivities.set(event.id, {
+                    ...activity,
+                    progress: progress ?? activity.progress,
+                    message: message ?? activity.message,
+                    payload: {
+                        ...activity.payload,
+                        ...rest,
+                    },
+                });
+                state = {
+                    ...state,
+                    activities: newActivities,
+                };
+                notifyListeners();
+                break;
+            }
+            case 'activity:success': {
+                const activity = state.activities.get(event.id);
+                if (!activity)
+                    break;
+                const newActivities = new Map(state.activities);
+                newActivities.set(event.id, {
+                    ...activity,
+                    status: 'success',
+                    completedAt: Date.now(),
+                    justCompleted: true,
+                });
+                state = {
+                    ...state,
+                    activities: newActivities,
+                };
+                notifyListeners();
+                scheduleActivityMarkerClear(event.id, ['justCompleted']);
+                break;
+            }
+            case 'activity:failure': {
+                const activity = state.activities.get(event.id);
+                if (!activity)
+                    break;
+                const errorMessage = event.error instanceof Error ? event.error.message : String(event.error);
+                const newActivities = new Map(state.activities);
+                newActivities.set(event.id, {
+                    ...activity,
+                    status: 'failure',
+                    completedAt: Date.now(),
+                    justFailed: true,
+                    error: {
+                        message: errorMessage,
+                        remediation: event.remediation,
+                        documentationUrl: event.documentationUrl,
+                    },
+                });
+                // Mark parent group as having failure
+                const newGroups = new Map(state.groups);
+                if (activity.parentId) {
+                    const parentGroup = state.groups.get(activity.parentId);
+                    if (parentGroup) {
+                        newGroups.set(activity.parentId, {
+                            ...parentGroup,
+                            hasFailure: true,
+                        });
+                    }
+                }
+                state = {
+                    ...state,
+                    activities: newActivities,
+                    groups: newGroups,
+                };
+                notifyListeners();
+                scheduleActivityMarkerClear(event.id, ['justFailed']);
+                break;
+            }
+            case 'log': {
+                const logEntry = {
+                    id: `log-${++logIdCounter}`,
+                    activityId: event.activityId,
+                    level: event.level,
+                    message: event.message,
+                    timestamp: Date.now(),
+                };
+                state = {
+                    ...state,
+                    logs: [...state.logs, logEntry],
+                };
+                notifyListeners();
+                break;
+            }
+            case 'reporter:suspend': {
+                state = {
+                    ...state,
+                    suspended: true,
+                };
+                notifyListeners();
+                break;
+            }
+            case 'reporter:resume': {
+                state = {
+                    ...state,
+                    suspended: false,
+                };
+                notifyListeners();
+                break;
+            }
+        }
+    }
+    return {
+        getState() {
+            return state;
+        },
+        getSnapshot() {
+            return state;
+        },
+        getServerSnapshot() {
+            return state;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        /**
+         * Internal method to handle events - exposed for adapter use
+         */
+        _handleEvent: handleEvent,
+    };
+}