@lostgradient/cinder 0.6.0 → 0.8.0

package/src/components/carousel/carousel.svelte

@@ -0,0 +1,221 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+import { useReducedMotion } from '../../utilities/use-reduced-motion.svelte.ts';
+const reducedMotion = useReducedMotion();
+const descriptionId = $props.id();
+let { slides, activeIndex = $bindable(0), autoplay = false, autoplayInterval = 5000, label = 'Carousel', description, controlLabels, class: className, ...rest } = $props();
+let isHovered = $state(false);
+let hasFocusWithin = $state(false);
+let userPaused = $state(false);
+const clampedLength = $derived(slides.length);
+const currentIndex = $derived.by(() => {
+    if (clampedLength < 1)
+        return 0;
+    return Math.max(0, Math.min(clampedLength - 1, activeIndex));
+});
+$effect(() => {
+    if (clampedLength < 1) {
+        if (activeIndex !== 0)
+            activeIndex = 0;
+        return;
+    }
+    const normalizedIndex = Math.max(0, Math.min(clampedLength - 1, activeIndex));
+    if (activeIndex !== normalizedIndex)
+        activeIndex = normalizedIndex;
+});
+const shouldAutoplay = $derived(autoplay &&
+    clampedLength > 1 &&
+    autoplayInterval > 0 &&
+    !reducedMotion.current &&
+    !isHovered &&
+    !hasFocusWithin &&
+    !userPaused);
+const liveAnnouncement = $derived.by(() => {
+    if (!slides[currentIndex])
+        return '';
+    return `Slide ${currentIndex + 1} of ${clampedLength}: ${slides[currentIndex].label}`;
+});
+$effect(() => {
+    if (!shouldAutoplay)
+        return;
+    const timer = setInterval(() => {
+        if (clampedLength < 2)
+            return;
+        activeIndex = (currentIndex + 1) % clampedLength;
+    }, autoplayInterval);
+    return () => clearInterval(timer);
+});
+function goTo(index) {
+    if (clampedLength < 1)
+        return;
+    activeIndex = ((index % clampedLength) + clampedLength) % clampedLength;
+}
+function goPrevious() {
+    goTo(currentIndex - 1);
+}
+function goNext() {
+    goTo(currentIndex + 1);
+}
+function onKeydown(event) {
+    if (clampedLength < 2)
+        return;
+    if (event.key === 'ArrowLeft') {
+        event.preventDefault();
+        goPrevious();
+        return;
+    }
+    if (event.key === 'ArrowRight') {
+        event.preventDefault();
+        goNext();
+        return;
+    }
+    if (event.key === 'Home') {
+        event.preventDefault();
+        goTo(0);
+        return;
+    }
+    if (event.key === 'End') {
+        event.preventDefault();
+        goTo(clampedLength - 1);
+    }
+}
+function onFocusOut(event) {
+    const nextFocus = event.relatedTarget;
+    if (nextFocus instanceof Node && event.currentTarget instanceof HTMLElement) {
+        if (event.currentTarget.contains(nextFocus))
+            return;
+    }
+    hasFocusWithin = false;
+}
+</script>
+
+<section
+  {...rest}
+  class={classNames('cinder-carousel', className)}
+  role="region"
+  aria-roledescription="carousel"
+  aria-label={label}
+  aria-describedby={description ? descriptionId : undefined}
+  tabindex="0"
+  onkeydown={onKeydown}
+  onmouseenter={() => (isHovered = true)}
+  onmouseleave={() => (isHovered = false)}
+  onfocusin={() => (hasFocusWithin = true)}
+  onfocusout={onFocusOut}
+>
+  {#if description}
+    <p id={descriptionId} class="cinder-carousel__sr-only">{description}</p>
+  {/if}
+  <p
+    class="cinder-carousel__sr-only"
+    aria-live={shouldAutoplay ? 'off' : 'polite'}
+    aria-atomic="true"
+  >
+    {liveAnnouncement}
+  </p>
+
+  <div class="cinder-carousel__viewport">
+    {#if slides.length > 0}
+      {#each slides as slide, index (slide.id)}
+        {#if index === currentIndex}
+          <article
+            class="cinder-carousel__slide"
+            role="group"
+            aria-roledescription="slide"
+            aria-label={`${index + 1} of ${slides.length}: ${slide.label}`}
+          >
+            {#if slide.href}
+              <a class="cinder-carousel__link" href={slide.href}>
+                {#if slide.imageSrc}
+                  <img
+                    class="cinder-carousel__image"
+                    src={slide.imageSrc}
+                    alt={slide.imageAlt ?? slide.title ?? slide.label}
+                  />
+                {/if}
+                {#if slide.title}
+                  <h3 class="cinder-carousel__title">{slide.title}</h3>
+                {/if}
+                {#if slide.description}
+                  <p class="cinder-carousel__description">{slide.description}</p>
+                {/if}
+                {#if !slide.imageSrc && !slide.title && !slide.description}
+                  <p class="cinder-carousel__description">{slide.label}</p>
+                {/if}
+              </a>
+            {:else}
+              {#if slide.imageSrc}
+                <img
+                  class="cinder-carousel__image"
+                  src={slide.imageSrc}
+                  alt={slide.imageAlt ?? slide.title ?? slide.label}
+                />
+              {/if}
+              {#if slide.title}
+                <h3 class="cinder-carousel__title">{slide.title}</h3>
+              {/if}
+              {#if slide.description}
+                <p class="cinder-carousel__description">{slide.description}</p>
+              {/if}
+              {#if !slide.imageSrc && !slide.title && !slide.description}
+                <p class="cinder-carousel__description">{slide.label}</p>
+              {/if}
+            {/if}
+          </article>
+        {/if}
+      {/each}
+    {/if}
+  </div>
+
+  <div class="cinder-carousel__controls">
+    <div class="cinder-carousel__nav">
+      <button
+        type="button"
+        class="cinder-carousel__control"
+        onclick={goPrevious}
+        disabled={slides.length < 2}
+      >
+        {controlLabels?.previous ?? 'Previous'}
+      </button>
+      <button
+        type="button"
+        class="cinder-carousel__control"
+        onclick={goNext}
+        disabled={slides.length < 2}
+      >
+        {controlLabels?.next ?? 'Next'}
+      </button>
+    </div>
+
+    {#if autoplay && !reducedMotion.current}
+      <button
+        type="button"
+        class="cinder-carousel__control cinder-carousel__control--pause"
+        aria-pressed={userPaused}
+        onclick={() => (userPaused = !userPaused)}
+      >
+        {userPaused ? (controlLabels?.play ?? 'Play') : (controlLabels?.pause ?? 'Pause')}
+      </button>
+    {/if}
+
+    <div
+      class="cinder-carousel__dots"
+      role="group"
+      aria-label={controlLabels?.picker ?? 'Choose slide'}
+    >
+      {#each slides as slide, index (slide.id)}
+        <button
+          type="button"
+          class="cinder-carousel__dot"
+          aria-label={`Go to ${slide.label}`}
+          aria-current={index === currentIndex ? 'true' : undefined}
+          onclick={() => goTo(index)}
+        ></button>
+      {/each}
+    </div>
+  </div>
+</section>

package/src/components/carousel/carousel.types.ts

@@ -0,0 +1,47 @@
+import type { HTMLAttributes } from 'svelte/elements';
+
+export type CarouselSlideContent = {
+  /** Stable key used for keyed rendering and indicator targeting. */
+  id: string;
+  /** Short visible label announced in the slide picker. */
+  label: string;
+  /** Optional heading rendered inside the slide body. */
+  title?: string;
+  /** Optional body text rendered beneath the title. */
+  description?: string;
+  /** Optional image source rendered at the top of the slide. */
+  imageSrc?: string;
+  /** Optional alt text; falls back to `title` and then `label` when omitted. */
+  imageAlt?: string;
+  /** Optional destination URL for the slide body. */
+  href?: string;
+};
+
+export type CarouselSlide = CarouselSlideContent;
+
+export type CarouselControlLabel = {
+  previous?: string;
+  next?: string;
+  picker?: string;
+  pause?: string;
+  play?: string;
+};
+
+export type CarouselProps = Omit<HTMLAttributes<HTMLElement>, 'children' | 'class'> & {
+  /** Ordered list of slides. */
+  slides: CarouselSlide[];
+  /** Zero-based active index (bindable). */
+  activeIndex?: number;
+  /** Enables interval-based auto-advance. */
+  autoplay?: boolean;
+  /** Milliseconds between auto-advance ticks. */
+  autoplayInterval?: number;
+  /** Accessible name for the carousel region. */
+  label?: string;
+  /** Optional accessible description linked to the region. */
+  description?: string;
+  /** Override labels for controls and picker. */
+  controlLabels?: CarouselControlLabel;
+  /** Additional classes merged onto the root element. */
+  class?: string;
+};

package/src/components/carousel/carousel.variables.ts

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

package/src/components/carousel/index.ts

@@ -0,0 +1,11 @@
+import './carousel.css';
+import Carousel from './carousel.svelte';
+
+export default Carousel;
+export type {
+  CarouselControlLabel,
+  CarouselProps,
+  CarouselSlide,
+  CarouselSlideContent,
+} from './carousel.types.ts';
+export { Carousel };

package/src/components/chart.types.ts

@@ -0,0 +1,116 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+
+export type ChartXValue = string | number | Date;
+export type ChartNumericValue = number | null | undefined;
+export type ChartLegendPosition = 'top' | 'bottom' | 'none';
+export type ChartDataTableVisibility = 'screen-reader-only' | 'visible' | 'hidden';
+
+export type ChartFormatterContext = {
+  seriesId?: string;
+  seriesLabel?: string;
+  index: number;
+};
+
+export type ChartTickFormatter = (
+  value: string | number | Date,
+  context: ChartFormatterContext,
+) => string;
+
+export type ChartValueFormatter = (value: number, context: ChartFormatterContext) => string;
+
+export type ChartAxisConfiguration = {
+  label?: string;
+  tickCount?: number;
+  format?: ChartTickFormatter;
+};
+
+export type ChartPoint = {
+  x: ChartXValue;
+  y: ChartNumericValue;
+};
+
+export type ChartCartesianSeries = {
+  id: string;
+  label: string;
+  data: ChartPoint[];
+  color?: string;
+  valueFormatter?: ChartValueFormatter;
+};
+
+export type ChartSharedProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
+  /** Accessible label for the chart. Required for screen readers. */
+  label: string;
+  /** Optional description rendered below the label. */
+  description?: string;
+  /** Pixel height of the chart viewport. Default `280`. */
+  height?: number;
+  /** Configuration for the x-axis label and tick formatting. */
+  xAxis?: ChartAxisConfiguration;
+  /** Configuration for the y-axis label and tick formatting. */
+  yAxis?: ChartAxisConfiguration;
+  /** Where to render the series legend relative to the chart. Default `top`. */
+  legendPosition?: ChartLegendPosition;
+  /** IDs of series currently hidden from the chart. Can be two-way bound with `bind:hiddenSeriesIds`. */
+  hiddenSeriesIds?: string[];
+  /** Whether the chart is in a loading state. Default `false`. */
+  loading?: boolean;
+  /** Custom data table caption; falls back to `label`. */
+  dataTableCaption?: string;
+  /** Controls data table visibility. Default `screen-reader-only`. */
+  dataTableVisibility?: ChartDataTableVisibility;
+  /** Maximum number of interactive focus targets before keyboard navigation is disabled. Default `500`. */
+  maximumInteractivePoints?: number;
+  /** Custom class applied to the root element. */
+  class?: string;
+  empty?: Snippet;
+  loadingContent?: Snippet;
+};
+
+export type BarChartOrientation = 'vertical' | 'horizontal';
+export type BarChartMode = 'grouped' | 'stacked';
+export type AreaChartMode = 'single' | 'stacked';
+
+export type BarChartDatum = Record<string, string | number | Date | null | undefined>;
+
+export type BarChartSeries = {
+  id: string;
+  label: string;
+  valueKey: string;
+  color?: string;
+  valueFormatter?: ChartValueFormatter;
+};
+
+export type ChartJsonXValue = string | number;
+export type ChartJsonValue = string | number | null;
+
+/** @schemaObject */
+export type ChartAxisSchemaConfiguration = {
+  label?: string;
+  tickCount?: number;
+};
+
+/** @schemaObject */
+export type ChartSchemaPoint = {
+  x: ChartJsonXValue;
+  y?: number | null;
+};
+
+/** @schemaObject */
+export type ChartCartesianSchemaSeries = {
+  id: string;
+  label: string;
+  /** @schemaObject */
+  data: ChartSchemaPoint[];
+  color?: string;
+};
+
+export type BarChartSchemaDatum = Record<string, ChartJsonValue>;
+
+/** @schemaObject */
+export type BarChartSchemaSeries = {
+  id: string;
+  label: string;
+  valueKey: string;
+  color?: string;
+};

package/src/components/chat/adapter/chat-adapter.ts

@@ -0,0 +1,132 @@
+/**
+ * Optional adapter event/transport seam for the Chat component.
+ *
+ * `ChatAdapter` names the send / retry / edit / stop / tool-approval / history /
+ * real-time contract around the existing `conversation` prop WITHOUT coupling
+ * Chat to any transport. It is purely an event boundary — NOT a second
+ * conversation model. Every method parameter and every push payload uses the
+ * Conversationalist types from `../conversation-model.ts`, so a consumer whose
+ * authoritative transcript lives in `conversationalist` can pass a plain
+ * `ConversationHistory` snapshot to `<Chat>` and wire an adapter with zero
+ * adaptation. This module is TYPE-ONLY — it ships no runtime code and imports
+ * nothing at runtime, so it is trivially SSR-safe.
+ *
+ * The adapter is always optional. When omitted, Chat behaves exactly as it does
+ * with its plain callback props (`onsubmit` / `onretry` / `onedit` /
+ * `onstopgenerating`); the internal command dispatcher routes both paths
+ * identically (adapter method first, callback fallback).
+ *
+ * @module
+ */
+
+import type { Message, MessageInput, ToolCall, ToolResult } from '../conversation-model.ts';
+import type { ChatAttachment } from '../input/chat-attachment.ts';
+
+/**
+ * A read-receipt push event: a message was read at a point in time. The payload
+ * is an object (not positional args) so later tasks can extend it — e.g. with a
+ * participant id — without a breaking signature change.
+ */
+export type ChatReadReceiptEvent = {
+  /** The id of the message that was read. */
+  messageId: string;
+  /** ISO-8601 timestamp at which the message was read. */
+  readAt: string;
+  /**
+   * Optional list of reader display names. When present, the read receipt badge
+   * will show "Read by Alice, Bob" in its accessible label.
+   */
+  readBy?: string[];
+};
+
+/**
+ * Push handlers Chat hands to {@link ChatAdapter.subscribe}. The adapter invokes
+ * these as real-time transport events arrive.
+ *
+ * Streaming handlers drive Chat's own imperative streaming buffer
+ * (`onStreamBegin`/`onTokenPush`/`onStreamEnd` → `beginStreaming`/`pushToken`/
+ * `endStreaming`), so a push-driven stream is fully self-contained — the
+ * consumer does not also have to call the imperative API by hand.
+ *
+ * Transcript/peripheral handlers (`onMessage`/`onTypingChange`/`onReadReceipt`)
+ * concern state Chat does NOT own (the consumer owns `conversation`), so Chat
+ * forwards them verbatim to the matching pass-through callback props. It never
+ * mutates `conversation` in response.
+ */
+export type ChatPushHandlers = {
+  /** A new (or updated) message arrived. Forwarded to the consumer; Chat does not mutate the transcript. */
+  onMessage: (message: Message) => void;
+  /** A participant's typing state changed. Forwarded to the consumer. */
+  onTypingChange: (isTyping: boolean) => void;
+  /** A read receipt arrived. Forwarded to the consumer. */
+  onReadReceipt: (event: ChatReadReceiptEvent) => void;
+  /** Streaming began for a message — drives Chat's `beginStreaming(messageId)`. */
+  onStreamBegin: (messageId: string) => void;
+  /** A streaming token arrived — drives Chat's `pushToken(token)`. */
+  onTokenPush: (token: string) => void;
+  /** Streaming ended — drives Chat's `endStreaming()`. */
+  onStreamEnd: () => void;
+};
+
+/**
+ * Optional command/transport boundary around `<Chat conversation={…}>`.
+ *
+ * Only `sendMessage` is required; everything else is optional so an adapter can
+ * opt into exactly the capabilities its transport supports. Command methods
+ * return `Promise<void>` — Chat awaits them and routes any failure (a rejected
+ * promise OR a synchronous throw from the method) to `onadaptererror` rather
+ * than swallowing it.
+ *
+ * The optional `approveToolCall`/`denyToolCall` (consumed by the tool-approval
+ * task) and `loadOlderMessages` (consumed by the load-history task) are declared
+ * here so the seam is complete; their UI wiring lands with those tasks.
+ */
+export type ChatAdapter = {
+  /** Send a composed message with its attachments. */
+  sendMessage: (message: MessageInput, attachments: ChatAttachment[]) => Promise<void>;
+  /** Retry a previously-failed message by id. */
+  retryMessage?: (messageId: string) => Promise<void>;
+  /** Commit an edit to a user message. */
+  editMessage?: (event: { messageId: string; content: string }) => Promise<void>;
+  /** Stop an in-progress generation for a message. */
+  stopGenerating?: (messageId: string) => Promise<void>;
+  /**
+   * Load a page of older messages for the given conversation. Returns whether
+   * more remain. (UI wired by the load-history task.)
+   */
+  loadOlderMessages?: (conversationId: string) => Promise<{ hasMore: boolean }>;
+  /**
+   * Subscribe to real-time events for a conversation. Receives the conversation
+   * id (so the transport knows which channel to open) plus the push handlers,
+   * and returns an unsubscribe function Chat calls on teardown.
+   */
+  subscribe?: (conversationId: string, handlers: ChatPushHandlers) => () => void;
+  /** Approve an action-required tool call by id. (UI wired by the tool-approval task.) */
+  approveToolCall?: (toolCallId: string) => Promise<void>;
+  /** Reject an action-required tool call by id. (UI wired by the tool-approval task.) */
+  denyToolCall?: (toolCallId: string) => Promise<void>;
+};
+
+/**
+ * The set of commands the internal dispatcher routes. Used to tag an
+ * {@link ChatAdapterErrorEvent} so a consumer can tell which command failed.
+ */
+export type ChatCommand =
+  | 'sendMessage'
+  | 'retryMessage'
+  | 'editMessage'
+  | 'stopGenerating'
+  | 'loadOlderMessages'
+  | 'approveToolCall'
+  | 'denyToolCall';
+
+/** Error event surfaced when an adapter command fails (rejection or sync throw). */
+export type ChatAdapterErrorEvent = {
+  /** Which command's adapter method failed. */
+  command: ChatCommand;
+  /** The thrown value. */
+  error: unknown;
+};
+
+/** Re-export the mirror types an adapter author needs, from one place. */
+export type { Message, MessageInput, ToolCall, ToolResult };

package/src/components/chat/adapter/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Chat adapter seam — the optional event/transport boundary around `<Chat>`.
+ *
+ * Type-only; see `./chat-adapter.ts`.
+ *
+ * @module
+ */
+
+export type {
+  ChatAdapter,
+  ChatAdapterErrorEvent,
+  ChatCommand,
+  ChatPushHandlers,
+  ChatReadReceiptEvent,
+} from './chat-adapter.ts';

package/src/components/chat/artifact/artifact-panel.svelte

@@ -0,0 +1,112 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import X from 'lucide-svelte/icons/x';
+let { instanceId = 'artifact', title, onclose, children } = $props();
+const titleId = $derived(`${instanceId}-panel-title`);
+function focusOnMount(element) {
+    element.focus();
+}
+</script>
+
+<div class="artifact-panel" role="complementary" aria-label={title ?? 'Artifact panel'}>
+  <div class="artifact-panel-header">
+    <span class="artifact-panel-title" id={titleId}>
+      {title ?? 'Artifact'}
+    </span>
+
+    <button
+      type="button"
+      class="artifact-panel-close"
+      onclick={onclose}
+      aria-label="Close artifact panel"
+      {@attach focusOnMount}
+    >
+      <X class="cinder-icon-sm" />
+    </button>
+  </div>
+
+  <div class="artifact-panel-content">
+    {@render children()}
+  </div>
+</div>
+
+<style>
+  .artifact-panel {
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+    border-inline-start: 1px solid var(--cinder-border);
+    background: var(--cinder-surface);
+    min-width: 0;
+    overflow: hidden;
+  }
+
+  .artifact-panel-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: var(--cinder-space-3) var(--cinder-space-4);
+    border-bottom: 1px solid var(--cinder-border);
+    flex-shrink: 0;
+    gap: var(--cinder-space-2);
+  }
+
+  .artifact-panel-title {
+    font-size: var(--cinder-text-sm);
+    font-weight: var(--cinder-font-medium);
+    color: var(--cinder-text);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    flex: 1;
+  }
+
+  .artifact-panel-close {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: var(--cinder-touch-target-min);
+    height: var(--cinder-touch-target-min);
+    padding: 0;
+    background: transparent;
+    border: none;
+    border-radius: var(--cinder-radius-md);
+    color: var(--cinder-text-muted);
+    cursor: pointer;
+    flex-shrink: 0;
+    transition:
+      background var(--cinder-duration-fast) var(--cinder-ease-standard),
+      color var(--cinder-duration-fast) var(--cinder-ease-standard);
+  }
+
+  @media (hover: hover) {
+    .artifact-panel-close:hover {
+      background: var(--cinder-surface-hover);
+      color: var(--cinder-text);
+    }
+  }
+
+  /* Close button sits in the panel corner; an outset ring would overhang the
+     panel edge, so paint an INSET ring (Strategy B-inset). */
+  .artifact-panel-close:focus-visible {
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: inset 0 0 0 var(--cinder-ring-width)
+      var(--_cinder-artifact-panel-close-ring, var(--cinder-ring-color));
+  }
+
+  @media (forced-colors: active) {
+    .artifact-panel-close:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: calc(var(--cinder-ring-width) * -1);
+    }
+  }
+
+  .artifact-panel-content {
+    flex: 1;
+    overflow-y: auto;
+    overflow-x: hidden;
+  }
+</style>