@pyric/ui 0.1.0-alpha.11 → 0.1.0-alpha.13

package/src/events/hooks/useActivityStream.ts

@@ -0,0 +1,86 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { ActivitySource, AnyActivityEvent } from '../types.js';
+
+export interface UseActivityStreamOptions {
+  /**
+   * The subscription — `sandbox.onEvent` satisfies this directly. Pass
+   * a stable reference; the hook re-subscribes on identity change.
+   */
+  source: ActivitySource;
+  /**
+   * Seed the buffer with a snapshot before the live subscription
+   * attaches — typically `sandbox.history()`, so a late-attaching
+   * consumer sees the whole session, not just events from `subscribe`
+   * onward. Read once on mount.
+   */
+  initial?: readonly AnyActivityEvent[];
+  /**
+   * Ring-buffer cap. Once exceeded, the oldest events drop. Default
+   * 5000 (mirrors the traffic monitor's cap — a load-test session can
+   * emit 100k+ events).
+   */
+  bufferSize?: number;
+  /** Start paused — incoming events drop (not queued) while paused. */
+  paused?: boolean;
+}
+
+export interface UseActivityStreamResult {
+  /** The buffered events, oldest-first. Stable per emission — safe to
+   *  hand straight to {@link useActivityDigest}. */
+  events: AnyActivityEvent[];
+  isPaused: boolean;
+  pause: () => void;
+  resume: () => void;
+  /** Empty the buffer (does NOT re-seed from `initial`). */
+  clear: () => void;
+}
+
+/**
+ * Buffers the unified sandbox event stream into a capped ring buffer
+ * with optional history seeding + pause/resume/clear. Decoupled from
+ * `pyric` — `source` is just a `(cb) => unsubscribe`.
+ *
+ * Sibling to the traffic monitor's `useTrafficMonitor`; the difference
+ * is the wider event type (`AnyActivityEvent`, the full union) and the
+ * `initial` seed so `history()` + live compose into one buffer.
+ */
+export function useActivityStream({
+  source,
+  initial,
+  bufferSize = 5000,
+  paused = false,
+}: UseActivityStreamOptions): UseActivityStreamResult {
+  const [events, setEvents] = useState<AnyActivityEvent[]>(() =>
+    initial ? initial.slice(-bufferSize) : [],
+  );
+  const [isPaused, setIsPaused] = useState(paused);
+
+  const pausedRef = useRef(isPaused);
+  pausedRef.current = isPaused;
+  const bufferSizeRef = useRef(bufferSize);
+  bufferSizeRef.current = bufferSize;
+
+  useEffect(() => {
+    const unsubscribe = source((event) => {
+      if (pausedRef.current) return;
+      setEvents((prev) => {
+        const next =
+          prev.length >= bufferSizeRef.current ? prev.slice(1) : prev.slice();
+        next.push(event);
+        return next;
+      });
+    });
+    return unsubscribe;
+  }, [source]);
+
+  return useMemo(
+    () => ({
+      events,
+      isPaused,
+      pause: () => setIsPaused(true),
+      resume: () => setIsPaused(false),
+      clear: () => setEvents([]),
+    }),
+    [events, isPaused],
+  );
+}

package/src/events/index.ts

@@ -0,0 +1,39 @@
+/**
+ * `@pyric/ui/events` — headless activity view over the unified
+ * `SandboxEvent` stream (Pyric Studio's keystone). Aggregates the whole
+ * stream (Firestore request/write + the cross-service `service_mutation`
+ * envelope for auth/storage/rtdb) into category bands with per-row
+ * provenance — the activity grid. Sibling to `@pyric/ui/traffic` (which
+ * is per-request, not aggregated-by-category).
+ *
+ * Ships zero styling — Pyric Studio applies the `data-pyric-*` contract.
+ */
+export * from './hooks/index.js';
+export * from './components/index.js';
+
+export {
+  computeActivityDigest,
+  type ActivityDigest,
+  type ActivityDigestOptions,
+  type ActivityGroupBy,
+  type ActivityBand,
+  type ActivityBandWithGroups,
+  type ActivitySubgroup,
+  type ActivityBandKey,
+  type ActivityRow,
+} from './digest.js';
+
+export type {
+  ActivityEvent,
+  AnyActivityEvent,
+  ActivitySource,
+  ActivityRequestEvent,
+  ActivityWriteEvent,
+  ActivityServiceMutationEvent,
+  ActivityProvenance,
+  ActivityService,
+  ActivityActor,
+  ActivityLens,
+  ActivityResult,
+  ActivityAuthState,
+} from './types.js';

package/src/events/types.ts

@@ -0,0 +1,152 @@
+/**
+ * The events/activity domain types. These are a local, structurally-
+ * compatible mirror of `pyric`'s unified `SandboxEvent` union (and its
+ * `EventProvenance`) — the `@pyric/ui` packages never import `pyric` so
+ * the headless layer stays decoupled from the sandbox impl (the same
+ * stance the sibling `traffic/` area takes with `RequestEvent`).
+ *
+ * `sandbox.onEvent` / `sandbox.history()` are assignable as an
+ * `ActivitySource` / `ActivityEvent[]` with zero adapter code: every
+ * field here is a subset (by name + shape) of the matching field on the
+ * sandbox type. A production audit feed satisfying the same shape works
+ * too.
+ *
+ * Unlike `traffic/` (which models only Firestore `request` events, one
+ * row per evaluated op), the events area aggregates the FULL stream —
+ * Firestore `request`/`write` plus the cross-service `service_mutation`
+ * envelope (auth / storage / rtdb) — into category bands. So the local
+ * types cover the union members the digest reads, not just one kind.
+ */
+
+/** Which sandbox service emitted an event. Absent ⇒ `'firestore'`. */
+export type ActivityService = 'firestore' | 'auth' | 'storage' | 'rtdb';
+
+/** Who initiated the op behind an event. Absent ⇒ the served app. */
+export type ActivityActor =
+  | { kind: 'app' }
+  | { kind: 'studio' }
+  | { kind: 'agent'; name: string }
+  | { kind: 'app-builder' };
+
+/**
+ * The auth lens an op ran under. `admin` bypasses rules, `as` evaluates
+ * rules as a specific uid (impersonation), `app-session` is the app's
+ * own signed-in user. Absent ⇒ `app-session`.
+ */
+export type ActivityLens =
+  | { mode: 'admin' }
+  | { mode: 'as'; uid: string }
+  | { mode: 'app-session' };
+
+/** Identity in effect for an op. `null` is anonymous / signed out. */
+export interface ActivityAuthState {
+  uid: string;
+  token?: Record<string, unknown>;
+}
+
+/**
+ * Provenance carried by every event. All optional + additive — pre-
+ * provenance emitters omit them (read as firestore / app / app-session).
+ */
+export interface ActivityProvenance {
+  service?: ActivityService;
+  actor?: ActivityActor;
+  authLens?: ActivityLens;
+  /** Set when the op is part of an agent plan (dry-run / accept). */
+  planId?: string;
+}
+
+/** Firestore op outcome — present on `request` events only. */
+export type ActivityResult = 'allow' | 'deny' | 'unsupported';
+
+/**
+ * A Firestore `request` event — one per evaluated op. The digest reads
+ * these for denials (`result === 'deny'`) and, when no `write` event is
+ * present, for the allow trail. Structurally a subset of `RequestEvent`.
+ */
+export interface ActivityRequestEvent extends ActivityProvenance {
+  kind: 'request';
+  id: string;
+  at: number;
+  method: 'get' | 'list' | 'create' | 'update' | 'set' | 'delete';
+  path: string;
+  auth: ActivityAuthState | null;
+  result: ActivityResult;
+  /** Simulator debug trail. Used to surface the deciding rule on denials. */
+  reasons: string[];
+  request?: { resourceData?: Record<string, unknown> };
+  resourceBefore?: { data: Record<string, unknown> | null; exists: boolean };
+  resourceAfter?: { data: Record<string, unknown> | null; exists: boolean };
+  matchedRule?: { ruleIndex: number; operations: string[] };
+  origin: 'user' | 'listener' | 'transaction' | 'batch';
+  groupId?: string;
+  triggeredBy?: { method: string; path: string };
+}
+
+/**
+ * A committed Firestore write — `create`/`update`/`set`/`delete` that
+ * the rule engine allowed and the keyspace applied. The digest leads
+ * with these for the added/updated/removed bands (richer than `request`:
+ * carries prior/next state for the change summary). Subset of
+ * `WriteSandboxEvent`.
+ */
+export interface ActivityWriteEvent extends ActivityProvenance {
+  kind: 'write';
+  id: string;
+  at: number;
+  method: 'create' | 'update' | 'set' | 'delete';
+  path: string;
+  auth: ActivityAuthState | null;
+  data?: Record<string, unknown>;
+  priorState: Record<string, unknown> | null;
+  nextState: Record<string, unknown> | null;
+  groupId?: string;
+}
+
+/**
+ * Cross-service mutation — the unified envelope auth / storage / rtdb
+ * emit. The digest maps `service` + `op` to a band (signed-in, added,
+ * updated, removed, …). Subset of `ServiceMutationEvent`.
+ */
+export interface ActivityServiceMutationEvent extends ActivityProvenance {
+  kind: 'service_mutation';
+  id: string;
+  at: number;
+  service: 'auth' | 'storage' | 'rtdb';
+  op: string;
+  path?: string;
+  auth: ActivityAuthState | null;
+  before?: unknown;
+  after?: unknown;
+  detail?: Record<string, unknown>;
+}
+
+/**
+ * The union members the activity digest aggregates. This is a SUBSET of
+ * `pyric`'s `SandboxEvent` — the listener-lifecycle / snapshot-delivery /
+ * session-boundary kinds carry no user-visible mutation, so the digest
+ * ignores them. The reducer accepts any object with a `kind` and skips
+ * the kinds it doesn't model, so a full `SandboxEvent[]` passes through
+ * cleanly (the extra kinds fall into the "unknown ⇒ skipped" branch).
+ */
+export type ActivityEvent =
+  | ActivityRequestEvent
+  | ActivityWriteEvent
+  | ActivityServiceMutationEvent;
+
+/**
+ * The widened input the reducer accepts: any `ActivityEvent`, plus a
+ * permissive escape for unmodelled `SandboxEvent` kinds carrying a
+ * string `kind` (skipped). Lets `sandbox.history()` flow in unfiltered.
+ */
+export type AnyActivityEvent =
+  | ActivityEvent
+  | { kind: string; [k: string]: unknown };
+
+/**
+ * A subscription: register a callback, get an unsubscribe.
+ * `sandbox.onEvent` matches this signature.
+ */
+export type ActivitySource = (
+  cb: (event: AnyActivityEvent) => void,
+) => () => void;

package/src/firestore/components/CollectionList.tsx

@@ -0,0 +1,78 @@
+import type { ReactNode } from 'react';
+import type { CollectionReference } from 'pyric/firestore';
+
+export interface CollectionListProps {
+  collections: CollectionReference[];
+  isLoading?: boolean;
+  error?: Error;
+  /** Fired when a list item is clicked. Consumer wires navigation. */
+  onSelect?: (collection: CollectionReference) => void;
+  /** Optional empty-state node. Rendered when `collections.length`
+   *  is 0 and the list isn't loading. */
+  emptyState?: ReactNode;
+  className?: string;
+}
+
+/**
+ * Headless collection list. Takes a pre-fetched array of references
+ * (from `useCollectionList`) plus a select callback. Renders one
+ * row per collection with `data-pyric-collection-id` for styling
+ * and testing. The library does not own the data fetch — the hook
+ * does — so this component is a thin presentational layer.
+ */
+export function CollectionList({
+  collections,
+  isLoading,
+  error,
+  onSelect,
+  emptyState,
+  className,
+}: CollectionListProps) {
+  if (error) {
+    return (
+      <div
+        className={className}
+        data-pyric-ui="collection-list"
+        data-pyric-error=""
+        role="alert"
+      >
+        {error.message}
+      </div>
+    );
+  }
+  if (isLoading && collections.length === 0) {
+    return (
+      <div
+        className={className}
+        data-pyric-ui="collection-list"
+        data-pyric-loading=""
+      />
+    );
+  }
+  if (collections.length === 0) {
+    return (
+      <div className={className} data-pyric-ui="collection-list" data-pyric-empty="">
+        {emptyState}
+      </div>
+    );
+  }
+  return (
+    <ul className={className} data-pyric-ui="collection-list">
+      {collections.map((coll) => (
+        <li
+          key={coll.path}
+          data-pyric-collection-entry
+          data-pyric-collection-id={coll.id}
+        >
+          <button
+            type="button"
+            onClick={() => onSelect?.(coll)}
+            data-pyric-collection-select
+          >
+            {coll.id}
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/firestore/components/DeleteWithConfirm.tsx

@@ -0,0 +1,88 @@
+import { type ReactNode } from 'react';
+import type {
+  CollectionReference,
+  DocumentReference,
+} from 'pyric/firestore';
+import { useConfirm } from '../../primitives/useConfirm.js';
+import {
+  useRecursiveDelete,
+  type RecursiveDeleteImpl,
+} from '../hooks/useRecursiveDelete.js';
+
+export interface DeleteWithConfirmProps {
+  /** The doc / collection to delete. */
+  target: DocumentReference | CollectionReference;
+  /** Implementation that walks the tree + deletes. Consumer-supplied.
+   *  Sandbox-backed apps usually wire `pyric/sandbox` introspection;
+   *  production apps usually call a Cloud Function. */
+  impl: RecursiveDeleteImpl;
+  /** Confirm-dialog title. Defaults to a sensible derivation from
+   *  the target's path. */
+  title?: string;
+  /** Confirm-dialog body. */
+  body?: ReactNode;
+  /** Label on the destructive button. */
+  confirmLabel?: string;
+  /** Fired after the delete iterator finishes successfully. */
+  onDeleted?: () => void;
+  /** Optional render override for the trigger button. */
+  renderTrigger?: (props: {
+    onClick: () => void;
+    isRunning: boolean;
+    progress: number;
+  }) => ReactNode;
+  /** Class forwarded to the default trigger button. */
+  className?: string;
+}
+
+/**
+ * Composition that wires `useConfirm` + `useRecursiveDelete`. Requires
+ * a `<ConfirmProvider>` ancestor.
+ *
+ * The default trigger renders a plain `<button>` carrying the
+ * destructive intent (the consumer styles via `[data-pyric-destructive]`).
+ * Consumers wanting different chrome pass `renderTrigger`.
+ */
+export function DeleteWithConfirm({
+  target,
+  impl,
+  title,
+  body,
+  confirmLabel = 'Delete',
+  onDeleted,
+  renderTrigger,
+  className,
+}: DeleteWithConfirmProps) {
+  const confirm = useConfirm();
+  const { delete: runDelete, isRunning, progress, error } = useRecursiveDelete(impl);
+
+  const handleClick = async () => {
+    const ok = await confirm({
+      title: title ?? `Delete ${target.path}?`,
+      body,
+      destructive: true,
+      confirmLabel,
+    });
+    if (!ok) return;
+    await runDelete(target);
+    if (!error) onDeleted?.();
+  };
+
+  if (renderTrigger) {
+    return <>{renderTrigger({ onClick: handleClick, isRunning, progress })}</>;
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      className={className}
+      disabled={isRunning}
+      data-pyric-ui="delete-with-confirm"
+      data-pyric-destructive=""
+      data-pyric-running={isRunning ? '' : undefined}
+    >
+      {isRunning ? `Deleting… (${progress})` : confirmLabel}
+    </button>
+  );
+}