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

package/src/traffic/components/TrafficTimeline.tsx

@@ -0,0 +1,289 @@
+import { useId, useState, type ReactNode } from 'react';
+import { useTrafficBuckets } from '../hooks/useTrafficBuckets.js';
+import type {
+  TimeWindow,
+  TrafficBucket,
+  UseTrafficBucketsResult,
+} from '../hooks/useTrafficBuckets.js';
+import type { TrafficEvent } from '../types.js';
+
+export interface TrafficTimelineProps {
+  /**
+   * Raw traffic events to bucket. Ignored when `buckets` is supplied
+   * (the consumer pre-bucketed). Exactly one of `events` / `buckets`
+   * should drive the histogram.
+   */
+  events?: TrafficEvent[];
+  /**
+   * Pre-bucketed counts — the escape hatch when the caller already
+   * ran {@link useTrafficBuckets} (or `bucketTraffic`) upstream, e.g.
+   * to share one bucketing pass across the timeline + a stats header.
+   * Takes precedence over `events`.
+   */
+  buckets?: UseTrafficBucketsResult;
+  /** The time range the histogram spans. */
+  window: TimeWindow;
+  /** Number of bars. Default 30. Only used on the `events` path. */
+  bucketCount?: number;
+  /**
+   * A brushed sub-range (`[start, end)`) drawn as an overlay over the
+   * bars. Position is derived from where it falls inside `window`, so
+   * a partly-out-of-window brush clamps to the chart edges.
+   */
+  brush?: TimeWindow;
+  /**
+   * Fired when a bar inside the brush region is clicked-through — the
+   * component itself is presentation-agnostic about drag, so the
+   * primary brush gesture is owned by the consumer. As a built-in
+   * affordance, clicking a bucket calls this with a one-bucket-wide
+   * window so a bare consumer still gets a working selection.
+   */
+  onBrush?: (window: TimeWindow) => void;
+  /**
+   * Direct annotation shown while a bucket is hovered or keyboard-focused.
+   * The timeline owns preview state and positioning; the consumer owns the
+   * words and number formatting.
+   */
+  renderBucketSummary?: (bucket: TrafficBucket) => ReactNode;
+  /**
+   * Where the live edge marker sits, in epoch-ms. Defaults to
+   * `window.end` (the right edge = "now"). Omit / pass `null` to hide
+   * the marker entirely (e.g. a frozen, non-live window).
+   */
+  liveAt?: number | null;
+  /**
+   * Header slot — title, deny summary, live label. Rendered above the
+   * bars inside `[data-pyric-timeline-header]`. The mock puts
+   * "142 requests · 16 denied · live" here.
+   */
+  header?: ReactNode;
+  /**
+   * Axis slot — tick labels below the bars inside
+   * `[data-pyric-timeline-axis]`. The mock puts "14m ago · 7m · now"
+   * here. Receives the resolved window so labels can be derived.
+   */
+  axis?: ReactNode | ((window: TimeWindow) => ReactNode);
+  emptyState?: ReactNode;
+  className?: string;
+}
+
+/** Clamp a 0..1 fraction. */
+function clamp01(n: number): number {
+  if (n < 0) return 0;
+  if (n > 1) return 1;
+  return n;
+}
+
+/** Fraction (0..1) of `t` across `[window.start, window.end)`. */
+function fraction(t: number, window: TimeWindow): number {
+  const span = window.end - window.start;
+  if (span <= 0) return 0;
+  return clamp01((t - window.start) / span);
+}
+
+/**
+ * Headless volume-over-time histogram — the time axis for the traffic
+ * lens. Buckets events into N bars; each bar stacks denies (dark, at
+ * the base) under the allow remainder, matching the Studio mock.
+ *
+ * Per-bucket styling channels (on `[data-pyric-bucket]`):
+ * - `data-pyric-bucket-count` / `-denies` — raw integers.
+ * - `--pyric-bucket-h` — full bar height, 0..1 of the tallest bucket.
+ * - `--pyric-bucket-deny-h` — deny sub-stack height, same scale.
+ * The deny segment (`[data-pyric-bucket-deny]`) and allow segment
+ * (`[data-pyric-bucket-allow]`) are separate children so the consumer
+ * colors them independently.
+ *
+ * A `[data-pyric-brush]` overlay marks a sub-range via
+ * `--pyric-brush-left` / `--pyric-brush-right` (0..1 fractions). The
+ * `[data-pyric-live]` edge marker sits at `--pyric-live-x`.
+ *
+ * Styling hooks: `[data-pyric-ui="traffic-timeline"]`,
+ * `[data-pyric-timeline-header]`, `[data-pyric-timeline-bars]`,
+ * `[data-pyric-bucket]` (with `data-pyric-bucket-index`,
+ * `data-pyric-has-denies`, `data-pyric-bucket-selected`),
+ * `[data-pyric-bucket-summary]`, `[data-pyric-brush]`, `[data-pyric-live]`,
+ * `[data-pyric-timeline-axis]`.
+ */
+export function TrafficTimeline({
+  events,
+  buckets: prebucketed,
+  window,
+  bucketCount = 30,
+  brush,
+  onBrush,
+  renderBucketSummary,
+  liveAt,
+  header,
+  axis,
+  emptyState,
+  className,
+}: TrafficTimelineProps) {
+  const summaryId = useId();
+  const [hoveredBucket, setHoveredBucket] = useState<number | null>(null);
+  const [focusedBucket, setFocusedBucket] = useState<number | null>(null);
+  // Hook is always called (rules of hooks); its result is discarded
+  // when the caller pre-bucketed.
+  const computed = useTrafficBuckets({
+    events: events ?? [],
+    window,
+    bucketCount,
+  });
+  const result = prebucketed ?? computed;
+  const { buckets, total } = result;
+  const activeBucketIndex = hoveredBucket ?? focusedBucket;
+  const activeBucket =
+    activeBucketIndex === null ? null : (buckets.find((bucket) => bucket.index === activeBucketIndex) ?? null);
+  const activeBucketSelected =
+    activeBucket !== null && brush?.start === activeBucket.start && brush.end === activeBucket.end;
+
+  if (buckets.length === 0) {
+    return (
+      <div
+        className={className}
+        data-pyric-ui="traffic-timeline"
+        data-pyric-empty=""
+      >
+        {emptyState}
+      </div>
+    );
+  }
+
+  const isEmpty = total === 0;
+  const livePoint = liveAt === undefined ? window.end : liveAt;
+  const liveX = livePoint == null ? null : fraction(livePoint, window);
+
+  const resolvedAxis = typeof axis === 'function' ? axis(window) : axis;
+
+  return (
+    <div
+      className={className}
+      data-pyric-ui="traffic-timeline"
+      data-pyric-empty={isEmpty ? '' : undefined}
+    >
+      {header !== undefined && (
+        <div data-pyric-timeline-header="">{header}</div>
+      )}
+
+      <div data-pyric-timeline-chart="">
+        <div
+          data-pyric-timeline-bars=""
+          role={onBrush ? 'group' : 'img'}
+          aria-label="request volume over time"
+        >
+          {buckets.map((bucket) => (
+            <Bar
+              key={bucket.index}
+              bucket={bucket}
+              window={window}
+              onBrush={onBrush}
+              onHover={renderBucketSummary ? setHoveredBucket : undefined}
+              onFocus={renderBucketSummary ? setFocusedBucket : undefined}
+              summaryId={
+                renderBucketSummary && !activeBucketSelected && activeBucket?.index === bucket.index
+                  ? summaryId
+                  : undefined
+              }
+              selected={brush?.start === bucket.start && brush.end === bucket.end}
+            />
+          ))}
+        </div>
+
+        {activeBucket && renderBucketSummary && !activeBucketSelected ? (
+          <div
+            id={summaryId}
+            role="tooltip"
+            data-pyric-bucket-summary=""
+            style={
+              {
+                '--pyric-bucket-summary-x': (activeBucket.index + 0.5) / Math.max(buckets.length, 1),
+              } as React.CSSProperties
+            }
+          >
+            {renderBucketSummary(activeBucket)}
+          </div>
+        ) : null}
+
+        {brush && (
+          <div
+            data-pyric-brush=""
+            aria-hidden="true"
+            style={
+              {
+                '--pyric-brush-left': fraction(brush.start, window),
+                '--pyric-brush-right': 1 - fraction(brush.end, window),
+              } as React.CSSProperties
+            }
+          />
+        )}
+
+        {liveX != null && (
+          <div
+            data-pyric-live=""
+            aria-hidden="true"
+            style={{ '--pyric-live-x': liveX } as React.CSSProperties}
+          />
+        )}
+      </div>
+
+      {resolvedAxis !== undefined && resolvedAxis !== null && (
+        <div data-pyric-timeline-axis="">{resolvedAxis}</div>
+      )}
+    </div>
+  );
+}
+
+function Bar({
+  bucket,
+  window,
+  onBrush,
+  onHover,
+  onFocus,
+  summaryId,
+  selected,
+}: {
+  bucket: TrafficBucket;
+  window: TimeWindow;
+  onBrush?: (window: TimeWindow) => void;
+  onHover?: (index: number | null) => void;
+  onFocus?: (index: number | null) => void;
+  summaryId?: string;
+  selected: boolean;
+}) {
+  const interactive = onBrush !== undefined;
+  const requestLabel = `${bucket.count} ${bucket.count === 1 ? 'request' : 'requests'}`;
+  const denyLabel = `${bucket.denies} denied`;
+  return (
+    <button
+      type="button"
+      data-pyric-bucket=""
+      data-pyric-bucket-index={bucket.index}
+      data-pyric-bucket-count={bucket.count}
+      data-pyric-bucket-denies={bucket.denies}
+      data-pyric-has-denies={bucket.denies > 0 ? '' : undefined}
+      data-pyric-bucket-selected={selected ? '' : undefined}
+      disabled={!interactive}
+      aria-label={`${requestLabel}, ${denyLabel}`}
+      aria-describedby={summaryId}
+      aria-pressed={interactive ? selected : undefined}
+      onPointerEnter={onHover ? () => onHover(bucket.index) : undefined}
+      onPointerLeave={onHover ? () => onHover(null) : undefined}
+      onFocus={onFocus ? () => onFocus(bucket.index) : undefined}
+      onBlur={onFocus ? () => onFocus(null) : undefined}
+      onClick={
+        interactive
+          ? () => onBrush?.({ start: bucket.start, end: bucket.end })
+          : undefined
+      }
+      style={
+        {
+          '--pyric-bucket-h': bucket.heightRatio,
+          '--pyric-bucket-deny-h': bucket.denyHeightRatio,
+        } as React.CSSProperties
+      }
+    >
+      <span data-pyric-bucket-allow="" aria-hidden="true" />
+      <span data-pyric-bucket-deny="" aria-hidden="true" />
+    </button>
+  );
+}

package/src/traffic/components/format.ts

@@ -0,0 +1,22 @@
+/**
+ * Default `HH:MM:SS` timestamp formatter. Components accept a
+ * `formatTime` prop to override — this is just the fallback so the
+ * library has no hard locale dependency.
+ */
+export function defaultFormatTime(at: number): string {
+  const d = new Date(at);
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+/**
+ * Classifies a simulator debug line as a deny / allow / neutral
+ * verdict so consumers can tint reason rows via
+ * `[data-pyric-reason-verdict="…"]`.
+ */
+export function reasonVerdict(reason: string): 'deny' | 'allow' | 'neutral' {
+  const lower = reason.toLowerCase();
+  if (lower.includes('deny')) return 'deny';
+  if (lower.includes('allow')) return 'allow';
+  return 'neutral';
+}

package/src/traffic/components/index.ts

@@ -0,0 +1,22 @@
+export { TrafficRow, type TrafficRowProps } from './TrafficRow.js';
+export { TrafficLog, type TrafficLogProps } from './TrafficLog.js';
+export {
+  TrafficGroupRow,
+  type TrafficGroupRowProps,
+} from './TrafficGroupRow.js';
+export { TrafficDetail, type TrafficDetailProps } from './TrafficDetail.js';
+export { RuleHeatmap, type RuleHeatmapProps } from './RuleHeatmap.js';
+export { TrafficStats, type TrafficStatsProps } from './TrafficStats.js';
+export {
+  TrafficTimeline,
+  type TrafficTimelineProps,
+} from './TrafficTimeline.js';
+export { defaultFormatTime, reasonVerdict } from './format.js';
+export {
+  TrafficMetricCards,
+  type TrafficMetricCardsProps,
+} from './TrafficMetricCards.js';
+export {
+  TrafficLineChart,
+  type TrafficLineChartProps,
+} from './TrafficLineChart.js';

package/src/traffic/hooks/index.ts

@@ -0,0 +1,60 @@
+export {
+  useTrafficMonitor,
+  type UseTrafficMonitorOptions,
+  type UseTrafficMonitorResult,
+  type TrafficCounts,
+} from './useTrafficMonitor.js';
+export {
+  useTrafficFilter,
+  type UseTrafficFilterOptions,
+  type UseTrafficFilterResult,
+  type TrafficFilterState,
+  type TrafficOriginFilter,
+  type TrafficResultFilter,
+} from './useTrafficFilter.js';
+export {
+  useRuleHeatmap,
+  type UseRuleHeatmapOptions,
+  type UseRuleHeatmapResult,
+  type RuleHeatmapEntry,
+} from './useRuleHeatmap.js';
+export {
+  useTrafficStats,
+  type UseTrafficStatsOptions,
+  type TrafficStatsSummary,
+  type TrafficStatBucket,
+} from './useTrafficStats.js';
+export {
+  useTrafficGroups,
+  type UseTrafficGroupsOptions,
+  type UseTrafficGroupsResult,
+  type TrafficLogItem,
+  type TrafficGroup,
+  type TrafficSingle,
+  type TrafficGroupKind,
+} from './useTrafficGroups.js';
+export {
+  useTrafficBuckets,
+  bucketTraffic,
+  type UseTrafficBucketsOptions,
+  type UseTrafficBucketsResult,
+  type TrafficBucket,
+  type TimeWindow,
+} from './useTrafficBuckets.js';
+export {
+  useBillableMetrics,
+  useRulesMetrics,
+  bucketBillableMetrics,
+  bucketRulesMetrics,
+  classifyBillable,
+  classifyRules,
+  isAdminEvent,
+  BILLABLE_SERIES_DEFS,
+  RULES_SERIES_DEFS,
+  type UseTrafficMetricsOptions,
+  type TrafficMetricsResult,
+  type MetricPoint,
+  type MetricSeries,
+  type BillableSeriesKey,
+  type RulesSeriesKey,
+} from './useTrafficMetrics.js';

package/src/traffic/hooks/useRuleHeatmap.ts

@@ -0,0 +1,92 @@
+import { useMemo } from 'react';
+import type { TrafficEvent } from '../types.js';
+
+export interface RuleHeatmapEntry {
+  /** The rule's index in the rules file. */
+  ruleIndex: number;
+  /** Union of all operations seen matching this rule. */
+  operations: string[];
+  /** Total events that matched this rule. */
+  total: number;
+  allows: number;
+  denies: number;
+  unsupported: number;
+  /** `denies / total` — 0 when the rule never denied. */
+  denyRatio: number;
+}
+
+export interface UseRuleHeatmapOptions {
+  events: TrafficEvent[];
+}
+
+export interface UseRuleHeatmapResult {
+  /** Per-rule rollup, sorted by `total` descending (busiest first),
+   *  ties broken by `ruleIndex` ascending. */
+  entries: RuleHeatmapEntry[];
+  /** Events that matched no rule — counted here, not attributed to
+   *  any entry. */
+  unmatchedCount: number;
+}
+
+interface Accumulator {
+  ruleIndex: number;
+  operations: Set<string>;
+  total: number;
+  allows: number;
+  denies: number;
+  unsupported: number;
+}
+
+/**
+ * Rolls a traffic buffer up by `matchedRule.ruleIndex`: how often
+ * each rule fired, and how that split across allow / deny /
+ * unsupported. Pure derivation — feed it the filtered or full
+ * event list depending on what the heatmap should reflect.
+ */
+export function useRuleHeatmap({
+  events,
+}: UseRuleHeatmapOptions): UseRuleHeatmapResult {
+  return useMemo(() => {
+    const byRule = new Map<number, Accumulator>();
+    let unmatchedCount = 0;
+
+    for (const event of events) {
+      if (!event.matchedRule) {
+        unmatchedCount++;
+        continue;
+      }
+      const { ruleIndex, operations } = event.matchedRule;
+      let acc = byRule.get(ruleIndex);
+      if (!acc) {
+        acc = {
+          ruleIndex,
+          operations: new Set(),
+          total: 0,
+          allows: 0,
+          denies: 0,
+          unsupported: 0,
+        };
+        byRule.set(ruleIndex, acc);
+      }
+      for (const op of operations) acc.operations.add(op);
+      acc.total++;
+      if (event.result === 'allow') acc.allows++;
+      else if (event.result === 'deny') acc.denies++;
+      else acc.unsupported++;
+    }
+
+    const entries: RuleHeatmapEntry[] = [...byRule.values()]
+      .map((acc) => ({
+        ruleIndex: acc.ruleIndex,
+        operations: [...acc.operations],
+        total: acc.total,
+        allows: acc.allows,
+        denies: acc.denies,
+        unsupported: acc.unsupported,
+        denyRatio: acc.total === 0 ? 0 : acc.denies / acc.total,
+      }))
+      .sort((a, b) => b.total - a.total || a.ruleIndex - b.ruleIndex);
+
+    return { entries, unmatchedCount };
+  }, [events]);
+}

package/src/traffic/hooks/useTrafficBuckets.ts

@@ -0,0 +1,146 @@
+import { useMemo } from 'react';
+import type { TrafficEvent } from '../types.js';
+
+/**
+ * A half-open time window `[start, end)` in epoch-ms. The timeline
+ * buckets events whose `at` falls inside it; events outside are
+ * dropped from the histogram (but still counted in `outOfWindow`).
+ */
+export interface TimeWindow {
+  start: number;
+  end: number;
+}
+
+export interface TrafficBucket {
+  /** 0-based bucket index, left (oldest) to right (newest). */
+  index: number;
+  /** Half-open bounds of this bucket `[start, end)` in epoch-ms. */
+  start: number;
+  end: number;
+  /** Total events that fell in this bucket. */
+  count: number;
+  /** How many of `count` were denied. */
+  denies: number;
+  /** `count - denies` — allowed + unsupported. The "non-deny" stack. */
+  allows: number;
+  /**
+   * `count / maxCount` across all buckets — 0..1. The full bar
+   * height as a fraction of the tallest bucket. Drives
+   * `--pyric-bucket-h`.
+   */
+  heightRatio: number;
+  /**
+   * `denies / maxCount` — 0..1. The deny sub-stack height as a
+   * fraction of the tallest bucket, so the deny segment is drawn to
+   * the same scale as the full bar. Drives `--pyric-bucket-deny-h`.
+   */
+  denyHeightRatio: number;
+}
+
+export interface UseTrafficBucketsOptions {
+  events: TrafficEvent[];
+  /** The time range to bucket over. */
+  window: TimeWindow;
+  /** Number of buckets to divide the window into. Default 30. */
+  bucketCount?: number;
+}
+
+export interface UseTrafficBucketsResult {
+  buckets: TrafficBucket[];
+  /** Sum of `count` across buckets (events inside the window). */
+  total: number;
+  /** Sum of `denies` across buckets. */
+  denies: number;
+  /** The largest single-bucket `count` — the height-ratio divisor. */
+  maxCount: number;
+  /** Events whose `at` fell outside `[window.start, window.end)`. */
+  outOfWindow: number;
+}
+
+const EMPTY_RESULT: UseTrafficBucketsResult = {
+  buckets: [],
+  total: 0,
+  denies: 0,
+  maxCount: 0,
+  outOfWindow: 0,
+};
+
+/**
+ * Buckets a traffic buffer into `bucketCount` equal time slices over
+ * `window`, counting total + denied events per slice. Pure
+ * derivation — the histogram component renders the result, this hook
+ * (and `bucketTraffic` under it) owns the math.
+ *
+ * Each bucket carries a `heightRatio` and `denyHeightRatio`
+ * (0..1, scaled to the tallest bucket) so the consumer can map them
+ * straight onto a bar height without re-finding the max.
+ */
+export function useTrafficBuckets({
+  events,
+  window,
+  bucketCount = 30,
+}: UseTrafficBucketsOptions): UseTrafficBucketsResult {
+  return useMemo(
+    () => bucketTraffic(events, window, bucketCount),
+    [events, window.start, window.end, bucketCount],
+  );
+}
+
+/**
+ * The pure bucketing kernel behind {@link useTrafficBuckets} — usable
+ * outside React. Returns an empty result for a non-positive
+ * `bucketCount` or a zero/negative-width window.
+ */
+export function bucketTraffic(
+  events: TrafficEvent[],
+  window: TimeWindow,
+  bucketCount = 30,
+): UseTrafficBucketsResult {
+  const span = window.end - window.start;
+  if (bucketCount <= 0 || span <= 0) return EMPTY_RESULT;
+
+  const width = span / bucketCount;
+  const counts = new Array<number>(bucketCount).fill(0);
+  const denyCounts = new Array<number>(bucketCount).fill(0);
+
+  let total = 0;
+  let denies = 0;
+  let outOfWindow = 0;
+
+  for (const event of events) {
+    const at = event.at;
+    if (at < window.start || at >= window.end) {
+      outOfWindow++;
+      continue;
+    }
+    // Floor into a bucket; clamp the right edge so an `at` exactly at
+    // `window.end - epsilon` never spills past the last bucket.
+    let i = Math.floor((at - window.start) / width);
+    if (i >= bucketCount) i = bucketCount - 1;
+    counts[i]++;
+    total++;
+    if (event.result === 'deny') {
+      denyCounts[i]++;
+      denies++;
+    }
+  }
+
+  let maxCount = 0;
+  for (const c of counts) if (c > maxCount) maxCount = c;
+
+  const buckets: TrafficBucket[] = counts.map((count, index) => {
+    const denyCount = denyCounts[index];
+    return {
+      index,
+      start: window.start + index * width,
+      end: window.start + (index + 1) * width,
+      count,
+      denies: denyCount,
+      allows: count - denyCount,
+      heightRatio: maxCount === 0 ? 0 : count / maxCount,
+      denyHeightRatio: maxCount === 0 ? 0 : denyCount / maxCount,
+    };
+  });
+
+  return { buckets, total, denies, maxCount, outOfWindow };
+}