@lostgradient/cinder 0.6.0 → 0.7.0

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

@@ -0,0 +1,212 @@
+import type { HTMLAttributes } from 'svelte/elements';
+
+/** Severity / tone of an event entry. */
+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`. */
+  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. */
+  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 and additive boundary entries to render in chronological order, oldest first. */
+  events: EventStreamEntry[];
+  /**
+   * Current connection state. When provided, renders a StatusDot connection preset 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
+   * 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
+   * 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;
+};

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

@@ -0,0 +1,3 @@
+const variables: readonly string[] = ['--cinder-event-stream-viewer-severity-color'];
+
+export default variables;

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

@@ -0,0 +1,17 @@
+import './event-stream-viewer.css';
+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/event-timeline/event-timeline.schema.ts

@@ -0,0 +1,99 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    start: {
+      anyOf: [
+        {
+          type: 'string',
+        },
+        {
+          type: 'number',
+        },
+      ],
+      description: 'Inclusive start of the displayed time range.',
+    },
+    end: {
+      anyOf: [
+        {
+          type: 'string',
+        },
+        {
+          type: 'number',
+        },
+      ],
+      description: 'Inclusive end of the displayed time range.',
+    },
+    now: {
+      anyOf: [
+        {
+          type: 'string',
+        },
+        {
+          type: 'number',
+        },
+      ],
+      description: 'Optional current time marker.',
+    },
+    items: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: {
+            type: 'string',
+            description: 'Stable key for repeated items. Pass an `id` when items can reorder.',
+          },
+          at: {
+            anyOf: [
+              {
+                type: 'string',
+              },
+              {
+                type: 'number',
+              },
+            ],
+            description: 'Event timestamp, accepted by the JavaScript Date constructor.',
+          },
+          label: {
+            type: 'string',
+            description: 'Primary visible label.',
+          },
+          sublabel: {
+            type: 'string',
+            description: 'Optional secondary timestamp label.',
+          },
+          state: {
+            enum: ['done', 'upcoming', 'failed'],
+            description: 'Visual event state. Defaults to `upcoming`.',
+          },
+        },
+        additionalProperties: false,
+        required: ['at', 'label'],
+      },
+      description: 'Events positioned proportionally between `start` and `end`.',
+    },
+    label: {
+      type: 'string',
+      description: 'Visible heading for the timeline.',
+    },
+    ariaLabel: {
+      type: 'string',
+      description: 'Accessible name override. Defaults to `label` or `Event timeline`.',
+    },
+    size: {
+      enum: ['sm', 'md'],
+      description: 'Timeline density. Default `md`.',
+    },
+    class: {
+      type: 'string',
+      description: 'Custom class merged with `.cinder-event-timeline`.',
+    },
+  },
+  additionalProperties: false,
+  required: ['end', 'items', 'start'],
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/event-timeline/event-timeline.svelte

@@ -0,0 +1,141 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+let { start, end, now, items, label, ariaLabel, size = 'md', class: customClassName, ...rest } = $props();
+function toTimestamp(value) {
+    if (value === undefined)
+        return undefined;
+    const timestamp = value instanceof Date ? value.getTime() : new Date(value).getTime();
+    return Number.isFinite(timestamp) ? timestamp : undefined;
+}
+function clampPercent(value) {
+    return Math.max(0, Math.min(100, value));
+}
+function stateLabelForItem(state) {
+    if (state === 'done')
+        return 'Done';
+    if (state === 'failed')
+        return 'Failed';
+    return 'Upcoming';
+}
+function keyForItem(item, index, timestamp) {
+    return `${item.id ?? `${item.label}-${new Date(timestamp).toISOString()}`}-${index}`;
+}
+function edgeForPosition(position) {
+    if (position <= 0)
+        return 'start';
+    if (position >= 100)
+        return 'end';
+    return 'middle';
+}
+const range = $derived.by(() => {
+    const startTimestamp = toTimestamp(start) ?? 0;
+    const endTimestamp = toTimestamp(end);
+    const safeEndTimestamp = endTimestamp !== undefined && endTimestamp > startTimestamp
+        ? endTimestamp
+        : startTimestamp + 1;
+    return {
+        startTimestamp,
+        endTimestamp: safeEndTimestamp,
+        duration: safeEndTimestamp - startTimestamp,
+    };
+});
+const positionedItems = $derived.by(() => {
+    const lanePositions = [];
+    return items
+        .map((item, index) => {
+        const timestamp = toTimestamp(item.at);
+        if (timestamp === undefined)
+            return undefined;
+        return {
+            item,
+            index,
+            timestamp,
+            position: clampPercent(((timestamp - range.startTimestamp) / range.duration) * 100),
+        };
+    })
+        .filter((item) => item !== undefined)
+        .sort((a, b) => a.position - b.position)
+        .map(({ item, index, timestamp, position }) => {
+        const availableLane = lanePositions.findIndex((lastPosition) => position - lastPosition >= 12);
+        const lane = availableLane === -1 ? lanePositions.length : availableLane;
+        lanePositions[lane] = position;
+        const isoDatetime = new Date(timestamp).toISOString();
+        const state = item.state ?? 'upcoming';
+        const stateLabel = stateLabelForItem(state);
+        const sublabel = item.sublabel?.trim() || undefined;
+        const timeLabel = sublabel ?? isoDatetime;
+        return {
+            ...item,
+            accessibleLabel: `${item.label}, ${timeLabel}, ${stateLabel}`,
+            edge: edgeForPosition(position),
+            key: keyForItem(item, index, timestamp),
+            lane,
+            position,
+            isoDatetime,
+            state,
+            stateLabel,
+            sublabel,
+        };
+    });
+});
+const laneCount = $derived(Math.max(3, ...positionedItems.map((item) => item.lane + 1), 0));
+const nowPosition = $derived.by(() => {
+    const timestamp = toTimestamp(now);
+    if (timestamp === undefined)
+        return undefined;
+    const position = ((timestamp - range.startTimestamp) / range.duration) * 100;
+    if (position < 0 || position > 100)
+        return undefined;
+    return position;
+});
+const normalizedLabel = $derived(label?.trim() || undefined);
+const normalizedAriaLabel = $derived(ariaLabel?.trim() || undefined);
+const accessibleName = $derived(normalizedAriaLabel ?? normalizedLabel ?? 'Event timeline');
+</script>
+
+<div {...rest} class={classNames('cinder-event-timeline', customClassName)} data-cinder-size={size}>
+  {#if normalizedLabel}
+    <div class="cinder-event-timeline__label">{normalizedLabel}</div>
+  {/if}
+  <div class="cinder-event-timeline__axis" aria-hidden="true">
+    {#if nowPosition !== undefined}
+      <div class="cinder-event-timeline__now" style:left="{nowPosition}%"></div>
+    {/if}
+  </div>
+  <div
+    class="cinder-event-timeline__items"
+    role="list"
+    aria-label={accessibleName}
+    style:--_cinder-event-timeline-lane-count={laneCount}
+  >
+    {#each positionedItems as item (item.key)}
+      <div
+        class="cinder-event-timeline__item"
+        role="listitem"
+        data-cinder-state={item.state}
+        data-cinder-lane={item.lane}
+        data-cinder-edge={item.edge}
+        aria-label={item.accessibleLabel}
+        style:left="{item.position}%"
+        style:--_cinder-event-timeline-lane={item.lane}
+      >
+        <span class="cinder-event-timeline__dot" aria-hidden="true"></span>
+        <span class="cinder-event-timeline__content">
+          <span class="cinder-event-timeline__item-label">{item.label}</span>
+          {#if item.sublabel}
+            <time class="cinder-event-timeline__item-sublabel" datetime={item.isoDatetime}
+              >{item.sublabel}</time
+            >
+          {:else}
+            <time class="cinder-sr-only" datetime={item.isoDatetime}>{item.isoDatetime}</time>
+          {/if}
+          <span class="cinder-sr-only">{item.stateLabel}</span>
+        </span>
+      </div>
+    {/each}
+  </div>
+</div>

package/src/components/event-timeline/event-timeline.types.ts

@@ -0,0 +1,80 @@
+import type { HTMLAttributes } from 'svelte/elements';
+
+export type EventTimelineDate = Date | number | string;
+export type EventTimelineSchemaDate = number | string;
+export type EventTimelineSize = 'sm' | 'md';
+export type EventTimelineState = 'done' | 'upcoming' | 'failed';
+
+export type EventTimelineItem = {
+  /**
+   * Stable key for repeated items. Defaults to `${label}-${atISOString}-${index}`;
+   * pass an `id` when items can reorder.
+   */
+  id?: string;
+  /** Event timestamp, accepted by the JavaScript Date constructor. */
+  at: EventTimelineDate;
+  /** Primary visible label. */
+  label: string;
+  /** Optional secondary label. */
+  sublabel?: string;
+  /** Visual event state. Defaults to `upcoming`. */
+  state?: EventTimelineState;
+};
+
+/**
+ * Schema-facing event item shape.
+ *
+ * @schemaObject
+ */
+export type EventTimelineSchemaItem = {
+  /** Stable key for repeated items. Pass an `id` when items can reorder. */
+  id?: string;
+  /** Event timestamp, accepted by the JavaScript Date constructor. */
+  at: EventTimelineSchemaDate;
+  /** Primary visible label. */
+  label: string;
+  /** Optional secondary timestamp label. */
+  sublabel?: string;
+  /** Visual event state. Defaults to `upcoming`. */
+  state?: EventTimelineState;
+};
+
+/** Props for the EventTimeline component. */
+export type EventTimelineProps = HTMLAttributes<HTMLDivElement> & {
+  /** Inclusive start of the displayed time range. */
+  start: EventTimelineDate;
+  /** Inclusive end of the displayed time range. */
+  end: EventTimelineDate;
+  /** Optional current time marker. */
+  now?: EventTimelineDate;
+  /** Events positioned proportionally between `start` and `end`. */
+  items: EventTimelineItem[];
+  /** Visible heading for the timeline. */
+  label?: string;
+  /** Accessible name override. Defaults to `label` or `Event timeline`. */
+  ariaLabel?: string;
+  /** Timeline density. Default `md`. */
+  size?: EventTimelineSize;
+  /** Custom class merged with `.cinder-event-timeline`. */
+  class?: string;
+};
+
+/** Schema generator surface for JSON-safe EventTimeline props. */
+export type EventTimelineSchemaProps = {
+  /** Inclusive start of the displayed time range. */
+  start: EventTimelineSchemaDate;
+  /** Inclusive end of the displayed time range. */
+  end: EventTimelineSchemaDate;
+  /** Optional current time marker. */
+  now?: EventTimelineSchemaDate;
+  /** Events positioned proportionally between `start` and `end`. */
+  items: EventTimelineSchemaItem[];
+  /** Visible heading for the timeline. */
+  label?: string;
+  /** Accessible name override. Defaults to `label` or `Event timeline`. */
+  ariaLabel?: string;
+  /** Timeline density. Default `md`. */
+  size?: EventTimelineSize;
+  /** Custom class merged with `.cinder-event-timeline`. */
+  class?: string;
+};

package/src/components/event-timeline/event-timeline.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/event-timeline/index.ts

@@ -0,0 +1,12 @@
+import './event-timeline.css';
+import EventTimeline from './event-timeline.svelte';
+
+export default EventTimeline;
+export type {
+  EventTimelineDate,
+  EventTimelineItem,
+  EventTimelineProps,
+  EventTimelineSize,
+  EventTimelineState,
+} from './event-timeline.types.ts';
+export { EventTimeline };

package/src/components/experimental/json-viewer/index.ts

@@ -0,0 +1,19 @@
+// Deprecated alias — do not edit by hand.
+//
+// `@lostgradient/cinder/experimental/json-viewer` moved to `@lostgradient/cinder/json-viewer` when the
+// component was promoted to stable. This shim re-exports the new location so
+// existing imports keep resolving during the deprecation window, and warns
+// once (dev only) so consumers migrate before the alias is removed in the
+// next major. Generated/managed by scripts/generate-exports.ts.
+
+import { devWarn } from '../../../utilities/dev-warn.ts';
+import JsonViewerComponent from '../../json-viewer/index.ts';
+
+devWarn(
+  "[cinder] '@lostgradient/cinder/experimental/json-viewer' is deprecated and will be removed in the next major. " +
+    "Import from '@lostgradient/cinder/json-viewer' instead.",
+);
+
+export default JsonViewerComponent;
+export type { JsonViewerProps } from '../../json-viewer/index.ts';
+export { JsonViewerComponent as JsonViewer };

package/src/components/experimental/message/index.ts

@@ -0,0 +1,19 @@
+// Deprecated alias — do not edit by hand.
+//
+// `@lostgradient/cinder/experimental/message` moved to `@lostgradient/cinder/message` when the component
+// was promoted to stable. This shim re-exports the new location so existing
+// imports keep resolving during the deprecation window, and warns once (dev
+// only) so consumers migrate before the alias is removed in the next major.
+// Generated/managed by scripts/generate-exports.ts.
+
+import { devWarn } from '../../../utilities/dev-warn.ts';
+import MessageComponent from '../../message/index.ts';
+
+devWarn(
+  "[cinder] '@lostgradient/cinder/experimental/message' is deprecated and will be removed in the next major. " +
+    "Import from '@lostgradient/cinder/message' instead.",
+);
+
+export default MessageComponent;
+export type { MessageProps, MessageRole } from '../../message/index.ts';
+export { MessageComponent as Message };

package/src/components/faceted-filter-bar/faceted-filter-bar.schema.ts

@@ -0,0 +1,71 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    'aria-label': {
+      type: 'string',
+      description: 'Defines a string value that labels the current element.',
+    },
+    searchQuery: {
+      type: 'string',
+      description: 'Current text search query. When provided, the search field is controlled.',
+    },
+    searchPlaceholder: {
+      type: 'string',
+      description: 'Placeholder text shown in the leading search field.',
+    },
+    searchAriaLabel: {
+      type: 'string',
+      description: "Accessible label for the search input. Defaults to 'Search'.",
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'When true, all filter controls and chips are disabled.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional CSS classes applied to the root element.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'appliedFilters',
+        reason: 'unknown-shape',
+        description:
+          'Applied filters displayed as removable chips below the controls row.\nControlled by the consumer; each entry is a key/value/label triple.',
+      },
+      {
+        name: 'facets',
+        reason: 'unknown-shape',
+        description:
+          'Facet definitions rendered as filter controls after the search field.\nEach entry is either a select-type facet or a custom snippet-driven facet.',
+      },
+      {
+        name: 'onclearall',
+        reason: 'function-or-snippet',
+        description: 'Fires when the clear-all button is clicked.',
+      },
+      {
+        name: 'onfacetchange',
+        reason: 'function-or-snippet',
+        description: 'Fires when a facet value changes, with the facet key and new value.',
+      },
+      {
+        name: 'onfilterremove',
+        reason: 'function-or-snippet',
+        description: 'Fires when a specific applied filter chip is removed.',
+      },
+      {
+        name: 'onsearchchange',
+        reason: 'function-or-snippet',
+        description: 'Fires when the search query changes.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;