@lostgradient/cinder 0.3.0 → 0.4.0

package/src/components/event-stream-viewer/event-stream-viewer.svelte

@@ -2,7 +2,7 @@
   /**
    * @cinder
    * @category data-display
-   * @status beta
+   * @status stable
    * @purpose Dense append-only log of timestamped events with follow-latest scrolling, severity tones, expandable JSON details, and copy actions.
    * @tag log
    * @tag stream
@@ -11,27 +11,75 @@
    * @useWhen Showing an append-only diagnostic stream with filtering, copy, and structured detail expansion.
    * @avoidWhen Showing a social activity feed or notification timeline — use feed instead.
    * @avoidWhen Rendering paginated historical records with sorting — use data-table instead.
-   * @related feed, timeline, json-viewer, connection-indicator, copy-button
+   * @related feed, timeline, json-viewer, status-dot, copy-button
    */
   export type {
     EventSeverity,
+    EventStreamEntry,
+    EventStreamSchemaDetailValue,
+    EventStreamSchemaEntry,
+    EventStreamSchemaEvent,
     EventStreamState,
+    EventStreamViewerSchemaProps,
     EventStreamViewerProps,
     StreamEvent,
+    StreamReconnectedBoundary,
   } from './event-stream-viewer.types.ts';
 </script>
 
 <script lang="ts">
-  import type { EventStreamViewerProps, StreamEvent } from './event-stream-viewer.types.ts';
+  import { SvelteSet } from 'svelte/reactivity';
+  import type {
+    EventStreamEntry,
+    EventStreamViewerProps,
+    StreamEvent,
+    StreamReconnectedBoundary,
+  } from './event-stream-viewer.types.ts';
   import { classNames } from '../../utilities/class-names.ts';
-  import ConnectionIndicator from '../connection-indicator/connection-indicator.svelte';
   import CopyButton from '../copy-button/copy-button.svelte';
   import JsonViewer from '../json-viewer/json-viewer.svelte';
+  import StatusDot from '../status-dot/status-dot.svelte';
+  import {
+    detailsIdForKey,
+    reconnectedBoundaryKey,
+    sequenceGapKey,
+    streamEventKey,
+    uniqueRenderedKey,
+  } from './event-stream-viewer-keys.ts';
+
+  type RenderedEventEntry = {
+    type: 'event';
+    key: string;
+    detailsId: string;
+    event: StreamEvent;
+  };
+
+  type RenderedReconnectedBoundary = {
+    type: 'reconnected';
+    key: string;
+    boundary: StreamReconnectedBoundary;
+    label: string;
+    datetime: string | undefined;
+  };
+
+  type RenderedSequenceGap = {
+    type: 'sequence-gap';
+    key: string;
+    expectedSequence: number;
+    actualSequence: number;
+    label: string;
+  };
+
+  type RenderedEntry = RenderedEventEntry | RenderedReconnectedBoundary | RenderedSequenceGap;
+
+  function isValidSequence(value: unknown): value is number {
+    return Number.isInteger(value);
+  }
 
   // Stable per-instance id namespace for generated DOM ids (details panels).
   // Event ids are consumer-supplied and may contain spaces, punctuation, or
   // duplicates across composed viewers, so we never use them directly in an
-  // `id`/`aria-controls` — we scope by this instance id plus the row index.
+  // `id`/`aria-controls` — we scope by this instance id plus the stable row key.
   const instanceId = $props.id();
 
   let {
@@ -41,6 +89,7 @@
     truncated = false,
     loading = false,
     label = 'Event stream',
+    detectSequenceGaps = false,
     oncopyvisible,
     onfilter,
     filterQuery = '',
@@ -48,8 +97,10 @@
     ...rest
   }: EventStreamViewerProps = $props();
 
-  // IDs for expanded details panels — keyed by event id
-  let expandedIds = $state(new Set<string>());
+  // IDs for expanded details panels — keyed by rendered row identity. The row
+  // identity is derived from stable event fields so retained streams can drop
+  // older entries without collapsing details for unchanged visible events.
+  const expandedIds = new SvelteSet<string>();
 
   // Track the scroll container element for auto-scroll
   let scrollContainerEl = $state<HTMLElement | null>(null);
@@ -68,14 +119,99 @@
   const eventCount = $derived(events.length);
   const latestEvent = $derived(events.at(-1));
 
-  function toggleDetails(id: string) {
-    const next = new Set(expandedIds);
-    if (next.has(id)) {
-      next.delete(id);
+  const renderedEntries = $derived.by<RenderedEntry[]>(() => {
+    const entries: RenderedEntry[] = [];
+    const keyOccurrences = new Map<string, number>();
+    let previousSequence: number | undefined;
+    let previousEventId: string | undefined;
+    const shouldDetectSequenceGaps = detectSequenceGaps && filterQuery.trim() === '';
+
+    for (const entry of events) {
+      if (isReconnectedBoundary(entry)) {
+        const key = uniqueRenderedKey(reconnectedBoundaryKey(entry), keyOccurrences);
+        entries.push({
+          type: 'reconnected',
+          key,
+          boundary: entry,
+          label: formatReconnectedBoundaryLabel(entry),
+          datetime: boundaryDateTime(entry),
+        });
+        previousSequence = undefined;
+        previousEventId = undefined;
+        continue;
+      }
+
+      const currentSequence = entry.sequence;
+      if (
+        shouldDetectSequenceGaps &&
+        isValidSequence(previousSequence) &&
+        isValidSequence(currentSequence)
+      ) {
+        const expectedSequence = previousSequence + 1;
+        if (currentSequence !== expectedSequence) {
+          const key = uniqueRenderedKey(
+            sequenceGapKey(previousEventId, entry, expectedSequence, currentSequence),
+            keyOccurrences,
+          );
+          entries.push({
+            type: 'sequence-gap',
+            key,
+            expectedSequence,
+            actualSequence: currentSequence,
+            label: formatSequenceGapLabel(expectedSequence, currentSequence),
+          });
+        }
+      }
+
+      if (isValidSequence(currentSequence)) {
+        previousSequence = currentSequence;
+        previousEventId = entry.id;
+      } else {
+        previousSequence = undefined;
+        previousEventId = undefined;
+      }
+
+      const key = uniqueRenderedKey(streamEventKey(entry), keyOccurrences);
+      entries.push({
+        type: 'event',
+        key,
+        detailsId: detailsIdForKey(instanceId, key),
+        event: entry,
+      });
+    }
+
+    return entries;
+  });
+
+  function toggleDetails(rowKey: string) {
+    if (expandedIds.has(rowKey)) {
+      expandedIds.delete(rowKey);
     } else {
-      next.add(id);
+      expandedIds.add(rowKey);
     }
-    expandedIds = next;
+  }
+
+  function isReconnectedBoundary(entry: EventStreamEntry): entry is StreamReconnectedBoundary {
+    return (
+      'kind' in entry &&
+      entry.kind === 'reconnected' &&
+      'replayedCount' in entry &&
+      Number.isInteger(entry.replayedCount) &&
+      entry.replayedCount >= 0
+    );
+  }
+
+  function formatReconnectedBoundaryLabel(boundary: StreamReconnectedBoundary): string {
+    const eventWord = boundary.replayedCount === 1 ? 'event' : 'events';
+    return `Reconnected — ${boundary.replayedCount} ${eventWord} replayed`;
+  }
+
+  function formatSequenceGapLabel(expectedSequence: number, actualSequence: number): string {
+    return `Sequence gap — expected ${expectedSequence}, received ${actualSequence}`;
+  }
+
+  function boundaryDateTime(boundary: StreamReconnectedBoundary): string | undefined {
+    return boundary.datetime;
   }
 
   function formatEventAsText(event: StreamEvent): string {
@@ -94,11 +230,27 @@
     return parts.join(' ');
   }
 
+  function formatReconnectedBoundaryAsText(boundary: StreamReconnectedBoundary): string {
+    const timeLabel = boundary.timestamp ?? boundary.datetime;
+    const markerText = formatReconnectedBoundaryLabel(boundary);
+    return timeLabel ? `[${timeLabel}] ${markerText}` : markerText;
+  }
+
+  function formatRenderedEntryAsText(entry: RenderedEntry): string {
+    if (entry.type === 'event') return formatEventAsText(entry.event);
+    if (entry.type === 'reconnected') return formatReconnectedBoundaryAsText(entry.boundary);
+    return entry.label;
+  }
+
+  function formatCopyVisibleAnnouncement(entryCount: number): string {
+    return `${entryCount} stream ${entryCount === 1 ? 'entry' : 'entries'} sent to copy handler`;
+  }
+
   function handleCopyVisible() {
-    const text = events.map(formatEventAsText).join('\n');
+    const text = renderedEntries.map(formatRenderedEntryAsText).join('\n');
     if (!oncopyvisible) return;
     oncopyvisible(text);
-    liveMessage = `${events.length} event${events.length !== 1 ? 's' : ''} sent to copy handler`;
+    liveMessage = formatCopyVisibleAnnouncement(renderedEntries.length);
     setTimeout(() => {
       liveMessage = '';
     }, 2000);
@@ -154,7 +306,7 @@
   <div class="cinder-event-stream-viewer__toolbar" role="group" aria-label="Stream controls">
     <div class="cinder-event-stream-viewer__toolbar-start">
       {#if connectionState}
-        <ConnectionIndicator state={connectionState} />
+        <StatusDot {connectionState} />
       {/if}
       {#if !followLatest}
         <button
@@ -222,66 +374,107 @@
       </div>
     {:else}
       <ol class="cinder-event-stream-viewer__list">
-        {#each events as event, eventIndex (event.id)}
-          {@const isExpanded = expandedIds.has(event.id)}
-          {@const detailsId = `${instanceId}-details-${eventIndex}`}
-          <li
-            class="cinder-event-stream-viewer__event"
-            data-cinder-severity={event.severity ?? 'info'}
-          >
-            <div class="cinder-event-stream-viewer__event-bar" aria-hidden="true"></div>
-            <div class="cinder-event-stream-viewer__event-body">
-              <div class="cinder-event-stream-viewer__event-meta">
-                <time
-                  class="cinder-event-stream-viewer__event-time"
-                  datetime={event.datetime}
-                  title={event.datetime}
-                >
-                  {event.timestamp ?? event.datetime}
-                </time>
-                {#if event.severity}
-                  <span
-                    class="cinder-event-stream-viewer__event-severity"
-                    aria-label={`Severity: ${event.severity}`}
+        {#each renderedEntries as entry (entry.key)}
+          {#if entry.type === 'reconnected'}
+            <li class="cinder-event-stream-viewer__boundary-marker">
+              <div
+                class="cinder-event-stream-viewer__marker-content"
+                role="separator"
+                aria-label={entry.label}
+              >
+                {#if entry.boundary.datetime}
+                  <time
+                    class="cinder-event-stream-viewer__marker-time"
+                    datetime={entry.boundary.datetime}
+                    title={entry.boundary.datetime}
                   >
-                    {event.severity}
-                  </span>
-                {/if}
-                {#if event.source}
-                  <span class="cinder-event-stream-viewer__event-source">
-                    {event.source}
+                    {entry.boundary.timestamp ?? entry.boundary.datetime}
+                  </time>
+                {:else if entry.boundary.timestamp}
+                  <span class="cinder-event-stream-viewer__marker-time">
+                    {entry.boundary.timestamp}
                   </span>
                 {/if}
+                <span>{entry.label}</span>
               </div>
-              <p class="cinder-event-stream-viewer__event-summary">{event.summary}</p>
-              {#if event.details !== undefined}
-                <div class="cinder-event-stream-viewer__event-details-section">
-                  <button
-                    type="button"
-                    class="cinder-event-stream-viewer__details-toggle"
-                    aria-expanded={isExpanded}
-                    aria-controls={isExpanded ? detailsId : undefined}
-                    onclick={() => toggleDetails(event.id)}
+            </li>
+          {:else if entry.type === 'sequence-gap'}
+            <li class="cinder-event-stream-viewer__sequence-gap-marker">
+              <div
+                class="cinder-event-stream-viewer__marker-content"
+                role="note"
+                aria-label={entry.label}
+              >
+                <span>{entry.label}</span>
+              </div>
+            </li>
+          {:else}
+            {@const event = entry.event}
+            {@const isExpanded = expandedIds.has(entry.key)}
+            {@const detailsId = entry.detailsId}
+            <li
+              class="cinder-event-stream-viewer__event"
+              data-cinder-severity={event.severity ?? 'info'}
+            >
+              <div class="cinder-event-stream-viewer__event-bar" aria-hidden="true"></div>
+              <div class="cinder-event-stream-viewer__event-body">
+                <div class="cinder-event-stream-viewer__event-meta">
+                  <time
+                    class="cinder-event-stream-viewer__event-time"
+                    datetime={event.datetime}
+                    title={event.datetime}
                   >
-                    {isExpanded ? 'Hide details' : 'Show details'}
-                  </button>
-                  {#if isExpanded}
-                    <div id={detailsId} class="cinder-event-stream-viewer__event-details">
-                      <JsonViewer value={event.details} />
-                    </div>
+                    {event.timestamp ?? event.datetime}
+                  </time>
+                  {#if event.severity}
+                    <span
+                      class="cinder-event-stream-viewer__event-severity"
+                      aria-label={`Severity: ${event.severity}`}
+                    >
+                      {event.severity}
+                    </span>
+                  {/if}
+                  {#if event.source}
+                    <span class="cinder-event-stream-viewer__event-source">
+                      {event.source}
+                    </span>
                   {/if}
                 </div>
-              {/if}
-            </div>
-            <div class="cinder-event-stream-viewer__event-actions">
-              <CopyButton
-                value={formatEventAsText(event)}
-                label={`Copy event: ${event.summary}`}
-                copiedLabel="Event copied"
-                class="cinder-event-stream-viewer__copy-event-button"
-              />
-            </div>
-          </li>
+                <p class="cinder-event-stream-viewer__event-summary">{event.summary}</p>
+                {#if event.details !== undefined}
+                  <div class="cinder-event-stream-viewer__event-details-section">
+                    <button
+                      type="button"
+                      class="cinder-event-stream-viewer__details-toggle"
+                      aria-expanded={isExpanded}
+                      aria-controls={detailsId}
+                      aria-label={`${isExpanded ? 'Hide' : 'Show'} details for ${event.severity ? `${event.severity}: ` : ''}${event.summary}`}
+                      onclick={() => toggleDetails(entry.key)}
+                    >
+                      {isExpanded ? 'Hide details' : 'Show details'}
+                    </button>
+                    <div
+                      id={detailsId}
+                      class="cinder-event-stream-viewer__event-details"
+                      hidden={!isExpanded}
+                    >
+                      {#if isExpanded}
+                        <JsonViewer value={event.details} />
+                      {/if}
+                    </div>
+                  </div>
+                {/if}
+              </div>
+              <div class="cinder-event-stream-viewer__event-actions">
+                <CopyButton
+                  value={formatEventAsText(event)}
+                  label={`Copy event: ${event.summary}`}
+                  copiedLabel="Event copied"
+                  class="cinder-event-stream-viewer__copy-event-button"
+                />
+              </div>
+            </li>
+          {/if}
         {/each}
       </ol>
     {/if}

package/src/components/event-stream-viewer/event-stream-viewer.types.ts

@@ -6,16 +6,23 @@ export type EventSeverity = 'debug' | 'info' | 'success' | 'warning' | 'error';
 /** Connection state for the event stream source. */
 export type EventStreamState = 'connected' | 'connecting' | 'disconnected' | 'error';
 
+/** Schema-facing event detail value. Kept permissive to match the runtime `unknown` prop. */
+export type EventStreamSchemaDetailValue = unknown;
+
 /**
  * A single event entry in the stream.
  *
  * `id` must be stable and unique across the lifetime of the viewer — it drives
  * React-style keyed reconciliation. Use a server-assigned ID or a deterministic
  * hash, not `Math.random()`.
+ *
+ * @schemaObject
  */
 export type StreamEvent = {
   /** Stable unique identifier used as the keyed list identity. */
   id: string;
+  /** Optional monotonically increasing integer stream sequence used to detect missed events. */
+  sequence?: number;
   /** Machine-readable ISO 8601 datetime string rendered into `<time datetime>`. */
   datetime: string;
   /** Human-readable timestamp label (e.g. "12:04:32", "2m ago"). Falls back to `datetime`. */
@@ -30,14 +37,65 @@ export type StreamEvent = {
   details?: unknown;
 };
 
+/** @schemaObject */
+export type EventStreamSchemaEvent = {
+  /** Stable unique identifier used as the keyed list identity. */
+  id: string;
+  /** Optional monotonically increasing integer stream sequence used to detect missed events. */
+  sequence?: number;
+  /** Machine-readable ISO 8601 datetime string rendered into `<time datetime>`. */
+  datetime: string;
+  /** Human-readable timestamp label (e.g. "12:04:32", "2m ago"). Falls back to `datetime`. */
+  timestamp?: string;
+  /** Severity tone that drives visual styling and the accessible label prefix. */
+  severity?: EventSeverity;
+  /** Origin label identifying which service, worker, or activity produced the event. */
+  source?: string;
+  /** One-line summary of the event. */
+  summary: string;
+  /**
+   * Optional structured JSON payload. Rendered in a collapsible JsonViewer.
+   *
+   * @schemaPermissive
+   */
+  details?: EventStreamSchemaDetailValue;
+};
+
+/**
+ * Boundary entry that marks a successful reconnect and how many retained events
+ * were replayed into the stream.
+ *
+ * @schemaObject
+ */
+export type StreamReconnectedBoundary = {
+  /** Stable unique identifier used as the keyed list identity. */
+  id: string;
+  /** Discriminator for reconnect boundary entries. */
+  kind: 'reconnected';
+  /** Optional machine-readable ISO 8601 datetime string for the reconnect moment. */
+  datetime?: string;
+  /** Optional human-readable timestamp label. Falls back to `datetime` when rendered. */
+  timestamp?: string;
+  /** Non-negative integer count of events replayed after the connection resumed. */
+  replayedCount: number;
+};
+
+/** A renderable stream item: either a normal event or a stream boundary marker. */
+export type EventStreamEntry = StreamEvent | StreamReconnectedBoundary;
+
+/**
+ * Schema-facing stream item shape for JSON Schema consumers.
+ */
+export type EventStreamSchemaEntry = EventStreamSchemaEvent | StreamReconnectedBoundary;
+
 /**
  * Props for the EventStreamViewer component.
  */
 export type EventStreamViewerProps = Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'> & {
-  /** Events to render in chronological order, oldest first. */
-  events: StreamEvent[];
+  /** Events and additive boundary entries to render in chronological order, oldest first. */
+  events: EventStreamEntry[];
   /**
-   * Current connection state. When provided, renders a ConnectionIndicator in
+   * Current connection state. When provided, renders a StatusDot connection preset in
    * the toolbar. Omit when the stream has no live transport.
    */
   connectionState?: EventStreamState;
@@ -64,6 +122,75 @@ export type EventStreamViewerProps = Omit<HTMLAttributes<HTMLDivElement>, 'class
    * Defaults to "Event stream".
    */
   label?: string;
+  /**
+   * Enables sequence-gap markers when `events` is the complete, unfiltered
+   * stream. Leave false for retained windows, severity-filtered subsets, search
+   * results, or any other caller-trimmed event array.
+   */
+  detectSequenceGaps?: boolean;
+  /**
+   * Callback fired when the user clicks the "Copy visible" toolbar action.
+   * Receives the text of all currently visible events. When omitted the copy
+   * action is hidden.
+   */
+  oncopyvisible?: (text: string) => void;
+  /**
+   * Callback fired when the user updates the filter query in the toolbar's
+   * search field. The consumer is responsible for filtering `events` in
+   * response. When omitted the filter input is hidden.
+   */
+  onfilter?: (query: string) => void;
+  /**
+   * Current filter query value, for controlled usage. Pairs with `onfilter`.
+   */
+  filterQuery?: string;
+  /** Additional CSS classes applied to the root element. */
+  class?: string;
+};
+
+/**
+ * Cinder-specific schema surface for EventStreamViewer.
+ *
+ * Callback props are documented but marked unsupported because functions cannot
+ * be represented as JSON Schema controls.
+ */
+export type EventStreamViewerSchemaProps = {
+  /** Events and additive boundary entries to render in chronological order, oldest first. */
+  events: EventStreamSchemaEntry[];
+  /**
+   * Current connection state. When provided, renders a StatusDot in the toolbar.
+   * Omit when the stream has no live transport.
+   */
+  connectionState?: EventStreamState;
+  /**
+   * When true, new events automatically scroll the list to the bottom.
+   * Set to false to pause follow-latest (e.g. while the user reads earlier events).
+   * Bindable so the parent can read the paused state the component sets internally.
+   */
+  followLatest?: boolean;
+  /**
+   * Whether to show the "events were truncated" notice. This is a boolean flag,
+   * not a count: the viewer never slices `events` itself. Set it to `true` when
+   * you have already trimmed the array (e.g. capped retention) and want users to
+   * know earlier events are not shown.
+   */
+  truncated?: boolean;
+  /**
+   * Show a loading skeleton instead of the event list. Use while the first
+   * batch of events is in flight.
+   */
+  loading?: boolean;
+  /**
+   * Accessible label for the event list region. Required for accessibility.
+   * Defaults to "Event stream".
+   */
+  label?: string;
+  /**
+   * Enables sequence-gap markers when `events` is the complete, unfiltered
+   * stream. Leave false for retained windows, severity-filtered subsets, search
+   * results, or any other caller-trimmed event array.
+   */
+  detectSequenceGaps?: boolean;
   /**
    * Callback fired when the user clicks the "Copy visible" toolbar action.
    * Receives the text of all currently visible events. When omitted the copy

package/src/components/event-stream-viewer/index.ts

@@ -4,8 +4,14 @@ import EventStreamViewer from './event-stream-viewer.svelte';
 export default EventStreamViewer;
 export type {
   EventSeverity,
+  EventStreamEntry,
+  EventStreamSchemaDetailValue,
+  EventStreamSchemaEntry,
+  EventStreamSchemaEvent,
   EventStreamState,
   EventStreamViewerProps,
+  EventStreamViewerSchemaProps,
   StreamEvent,
+  StreamReconnectedBoundary,
 } from './event-stream-viewer.types.ts';
 export { EventStreamViewer };

package/src/components/faceted-filter-bar/faceted-filter-bar.css

@@ -29,9 +29,18 @@
     position: relative;
     display: inline-flex;
     align-items: center;
+    gap: var(--cinder-space-1);
     flex-shrink: 0;
   }
 
+  .cinder-faceted-filter-bar__facet-label {
+    color: var(--cinder-text-muted);
+    font-size: var(--cinder-text-xs);
+    font-weight: var(--cinder-font-medium);
+    line-height: var(--cinder-leading-tight);
+    white-space: nowrap;
+  }
+
   /* Native select styled to match cinder input frame */
   .cinder-faceted-filter-bar__select {
     appearance: none;