@lapismd/design-core 0.1.0 → 0.2.0

package/src/shared/ai/message-list/MessageList.svelte

@@ -1,12 +1,14 @@
-<script lang="ts">
+<script lang="ts" generics="T extends { id: string }">
   import SparklesIcon from "@lucide/svelte/icons/sparkles";
   import { Spinner } from "@lapismd/design-core/shadcn/spinner";
   import { Button } from "@lapismd/design-core/shadcn/button";
   import * as Empty from "@lapismd/design-core/shadcn/empty";
-  import { tick, type Snippet } from "svelte";
+  import VirtualizedMessageRows from "./VirtualizedMessageRows.svelte";
+  import { tick, untrack, type Snippet } from "svelte";
   import type { HTMLAttributes } from "svelte/elements";
   import { setListContext, useLayoutContext } from "../context.svelte.js";
   import type { Density } from "../types.js";
+  import type { MessageListPosition } from "./position.js";
   import "../chat.css";
 
   let {
@@ -19,6 +21,19 @@
     scrollToTopAction,
     latestMessageId,
     children,
+    header,
+    footer,
+    items = [],
+    row,
+    virtualize = false,
+    overscan = 6,
+    estimateSize = 112,
+    conversationKey,
+    initialPosition,
+    onPositionChange,
+    retainRowIds = [],
+    hasOlder = true,
+    loading = false,
     "aria-label": ariaLabel = "Messages",
     ...restProps
   }: HTMLAttributes<HTMLDivElement> & {
@@ -30,13 +45,36 @@
     emptyState?: Snippet;
     scrollToTopAction?: () => Promise<void>;
     latestMessageId?: string;
-    children: Snippet;
+    children?: Snippet;
+    /** Content before and after the rows, including in a virtualized list. */
+    header?: Snippet;
+    footer?: Snippet;
+    items?: readonly T[];
+    row?: Snippet<[T, number]>;
+    /** Opt in to bounded row rendering and automatic older-page loading; defaults to false. */
+    virtualize?: boolean;
+    overscan?: number;
+    estimateSize?: number;
+    /** Scope restoration and arrivals to a conversation; existing unkeyed lists retain explicit arrival handling. */
+    conversationKey?: string;
+    initialPosition?: MessageListPosition;
+    onPositionChange?: (position: MessageListPosition) => void;
+    retainRowIds?: readonly string[];
+    hasOlder?: boolean;
+    loading?: boolean;
   } = $props();
 
   const layout = useLayoutContext();
+  const componentId = $props.id();
+  const errorId = `${componentId}-older-error`;
   let innerRef = $state<HTMLDivElement | null>(null);
   let loadingOlder = $state(false);
+  let loadVersion = 0;
   let loadError = $state<string | null>(null);
+  let arrivalKey: string | undefined;
+  let previousMessageId: string | undefined;
+  let historyKey: string | undefined;
+  let historyInitialized = false;
 
   setListContext({ getDensity: () => density });
 
@@ -44,28 +82,64 @@
     layout?.setContent(innerRef);
     return () => layout?.setContent(null);
   });
+  $effect(() => {
+    const key = conversationKey,
+      latest = latestMessageId;
+    if (
+      latest &&
+      (key === undefined ||
+        (arrivalKey === key && latest !== previousMessageId))
+    )
+      untrack(() => layout?.newMessages.notify(latest));
+    arrivalKey = key;
+    previousMessageId = latest;
+  });
 
   $effect(() => {
-    if (latestMessageId) layout?.newMessages.notify(latestMessageId);
+    const key = conversationKey;
+    if (historyInitialized && key === historyKey) return;
+    historyInitialized = true;
+    historyKey = key;
+    loadVersion++;
+    loadingOlder = false;
+    loadError = null;
   });
 
   async function loadOlder(): Promise<void> {
-    if (!scrollToTopAction || loadingOlder) return;
+    if (!scrollToTopAction || loadingOlder || loading || !hasOlder) return;
+    const key = conversationKey;
+    const version = loadVersion;
     loadingOlder = true;
     loadError = null;
-    const viewport = layout?.getScrollContainer() ?? null;
+    const viewport = layout?.getScrollContainer();
     const previousHeight = viewport?.scrollHeight ?? 0;
+    const revision = layout?.streamScroll.positionRevision;
+    const restore =
+      !virtualize && conversationKey !== undefined
+        ? layout?.streamScroll.captureAnchor?.()
+        : undefined;
     try {
       await scrollToTopAction();
       await tick();
-      if (viewport) {
-        viewport.scrollTop += viewport.scrollHeight - previousHeight;
+      if (key === conversationKey && version === loadVersion) {
+        if (restore) restore();
+        else if (
+          !virtualize &&
+          viewport &&
+          revision === layout?.streamScroll.positionRevision
+        )
+          layout?.streamScroll.scrollToOffset?.(
+            viewport.scrollTop + viewport.scrollHeight - previousHeight,
+            true,
+          );
       }
     } catch (error) {
-      loadError =
-        error instanceof Error ? error.message : "Could not load messages";
+      if (key === conversationKey && version === loadVersion)
+        loadError =
+          error instanceof Error ? error.message : "Could not load messages";
     } finally {
-      loadingOlder = false;
+      if (key === conversationKey && version === loadVersion)
+        loadingOlder = false;
     }
   }
 </script>
@@ -80,54 +154,60 @@
   aria-label={ariaLabel}
   aria-live="polite"
   aria-relevant="additions text"
-  aria-busy={isStreaming || loadingOlder}
+  aria-busy={isStreaming || loadingOlder || loading}
 >
   <div bind:this={innerRef} data-ui-part="list-inner" style:gap>
-    {#if scrollToTopAction}
+    {#if scrollToTopAction && hasOlder}
       <div data-ui-part="top-sentinel">
         <Button
           type="button"
           size="xs"
           variant="ghost"
-          disabled={loadingOlder}
-          aria-describedby={loadError ? "ai-chat-load-older-error" : undefined}
+          disabled={loadingOlder || loading}
+          aria-describedby={loadError ? errorId : undefined}
           onclick={loadOlder}
         >
-          {#if loadingOlder}
-            <Spinner />
-            Loading older messages
-          {:else}
-            Load older messages
-          {/if}
+          {#if loadingOlder || loading}<Spinner /> Loading older messages{:else if loadError}Retry
+            older messages{:else}Load older messages{/if}
         </Button>
       </div>
-      {#if loadError}
-        <p id="ai-chat-load-older-error" role="alert">{loadError}</p>
-      {/if}
+      {#if loadError}<p id={errorId} role="alert">{loadError}</p>{/if}
     {/if}
-
     <div data-ui-part="list-spacer" aria-hidden="true"></div>
-
+    {#if header}{@render header()}{/if}
     {#if isEmpty}
       <div data-ui-part="empty">
-        {#if emptyState}
-          {@render emptyState()}
-        {:else}
-          <Empty.Root>
-            <Empty.Header>
-              <Empty.Media variant="icon">
-                <SparklesIcon aria-hidden="true" />
-              </Empty.Media>
-              <Empty.Title>No messages yet</Empty.Title>
-              <Empty.Description>
-                The conversation will appear here.
-              </Empty.Description>
-            </Empty.Header>
-          </Empty.Root>
+        {#if emptyState}{@render emptyState()}{:else}
+          <Empty.Root
+            ><Empty.Header
+              ><Empty.Media variant="icon"
+                ><SparklesIcon aria-hidden="true" /></Empty.Media
+              ><Empty.Title>No messages yet</Empty.Title><Empty.Description
+                >The conversation will appear here.</Empty.Description
+              ></Empty.Header
+            ></Empty.Root
+          >
         {/if}
       </div>
-    {:else}
-      {@render children()}
-    {/if}
+    {:else if virtualize && row}
+      <VirtualizedMessageRows
+        {items}
+        {row}
+        {overscan}
+        {estimateSize}
+        conversationKey={conversationKey ?? ""}
+        {initialPosition}
+        {onPositionChange}
+        {retainRowIds}
+        {hasOlder}
+        loading={loadingOlder || loading}
+        onLoadOlder={loadOlder}
+      />
+    {:else if row}
+      {#each items as item, index (item.id)}<div data-message-id={item.id}>
+          {@render row(item, index)}
+        </div>{/each}
+    {:else if children}{@render children()}{/if}
+    {#if footer}{@render footer()}{/if}
   </div>
 </div>

package/src/shared/ai/message-list/MessageListHistoryFixture.svelte

@@ -0,0 +1,112 @@
+<script lang="ts">
+  import { Button } from "@lapismd/design-core/shadcn/button";
+  import Layout from "../layout/Layout.svelte";
+  import MessageList from "./MessageList.svelte";
+  import Message from "../message/Message.svelte";
+  import MessageBubble from "../message-bubble/MessageBubble.svelte";
+  import type { MessageListPosition } from "./position.js";
+  let items = $state(
+    Array.from({ length: 1000 }, (_, index) => ({
+      id: `message-${index}`,
+      text: `Message ${index}: ${"Variable-height cached conversation content. ".repeat((index % 7) + 1)}`,
+    })),
+  );
+  let unread = $state(false);
+  let expanded = $state(false);
+  let position = $state<MessageListPosition>();
+  let presentation = $state<{ key: string; position?: MessageListPosition }>({
+    key: "channel-a",
+  });
+  let loads = $state(0);
+  let key = $state("channel-a");
+  let delay = $state(false);
+  let statusUpdates = $state(0);
+  let positionReports = $state(0);
+  function append(incoming: boolean) {
+    items = [
+      ...items,
+      {
+        id: `message-${items.length}`,
+        text: incoming ? "Incoming message" : "My own message",
+      },
+    ];
+    if (incoming) unread = true;
+  }
+</script>
+
+<div data-story="history-controls">
+  <Button onclick={() => append(true)}>Receive message</Button>
+  <Button onclick={() => append(false)}>Send own message</Button>
+  <Button onclick={() => (expanded = !expanded)}>Resize content</Button>
+  <Button
+    onclick={() => (key = key === "channel-a" ? "channel-b" : "channel-a")}
+    >Switch conversation</Button
+  >
+  <Button onclick={() => (delay = !delay)}>Toggle delayed history</Button>
+  <Button onclick={() => statusUpdates++}>Update unrelated status</Button>
+  <output aria-label="Position reports">{positionReports}</output>
+  <output aria-label="History loads">{loads}</output>
+  <output aria-label="Reading anchor">{position?.messageId ?? "none"}</output>
+</div>
+<div
+  data-story="virtual-history-frame"
+  style:width={expanded ? "360px" : "640px"}
+  style="height: 420px; max-width: 100%; display: flex; flex-direction: column;"
+>
+  <Layout
+    scrollMode="history"
+    conversationKey={presentation.key === key ? presentation.key : key}
+    hasNewMessages={unread}
+    onViewportChange={({ atLatest, active }) => {
+      if (atLatest && active) unread = false;
+    }}
+  >
+    {#snippet composer()}<span>Conversation composer</span>{/snippet}
+    <MessageList
+      {...{
+        items,
+        overscan: 6,
+        estimateSize: 112,
+        retainRowIds: [],
+        "data-status": statusUpdates,
+        "data-position-reports": positionReports,
+      }}
+      virtualize
+      conversationKey={presentation.key === key ? presentation.key : key}
+      onPositionChange={(next) => {
+        positionReports++;
+        position = next;
+        if (
+          JSON.stringify(presentation.position) !== JSON.stringify(next) ||
+          presentation.key !== key
+        )
+          presentation = { key, position: next };
+      }}
+      scrollToTopAction={async () => {
+        loads++;
+        if (delay) await new Promise((resolve) => setTimeout(resolve, 250));
+        const prefix = `older-${loads}`;
+        items = [
+          ...Array.from({ length: 50 }, (_, index) => ({
+            id: `${prefix}-${index}`,
+            text: `Earlier message ${index}`,
+          })),
+          ...items,
+        ];
+      }}
+    >
+      {#snippet row(item)}
+        <Message sender="user"
+          ><MessageBubble>
+            <p>{item.text}</p>
+            {#if expanded}<p>
+                Additional image or expanded text changes this row's height
+                without adding a message.
+              </p>{/if}
+            <Button size="xs" variant="ghost">Action for {item.id}</Button>
+          </MessageBubble></Message
+        >
+      {/snippet}
+    </MessageList>
+  </Layout>
+</div>

package/src/shared/ai/message-list/MessageListLegacyFixture.svelte

@@ -0,0 +1,52 @@
+<script lang="ts">
+  import { Button } from "@lapismd/design-core/shadcn/button";
+  import Layout from "../layout/Layout.svelte";
+  import MessageList from "./MessageList.svelte";
+  import Message from "../message/Message.svelte";
+  import MessageBubble from "../message-bubble/MessageBubble.svelte";
+  let items = $state(
+    Array.from({ length: 100 }, (_, index) => ({
+      id: `legacy-${index}`,
+      text: `Existing message ${index}`,
+    })),
+  );
+  let loads = $state(0);
+  let expanded = $state(false);
+</script>
+
+<Button
+  onclick={() =>
+    (items = [...items, { id: "incoming", text: "New incoming message" }])}
+  >Receive explicit arrival</Button
+>
+<Button onclick={() => (expanded = !expanded)}>Reflow existing content</Button>
+<output aria-label="Legacy history requests">{loads}</output>
+<div
+  data-story="legacy-history-frame"
+  style="height: 420px; width: 540px; display: flex; flex-direction: column;"
+>
+  <Layout>
+    {#snippet composer()}<span>Existing composer snippet</span>{/snippet}
+    <MessageList
+      density="compact"
+      gap="8px"
+      latestMessageId={items.at(-1)?.id}
+      scrollToTopAction={async () => {
+        loads++;
+        items = [
+          { id: `earlier-${loads}`, text: `Earlier context ${loads}` },
+          ...items,
+        ];
+      }}
+    >
+      {#each items as item (item.id)}
+        <Message sender="user"
+          ><MessageBubble>
+            {item.text}
+            {#if expanded}<p>Reflow without a new message</p>{/if}
+          </MessageBubble></Message
+        >
+      {/each}
+    </MessageList>
+  </Layout>
+</div>

package/src/shared/ai/message-list/VirtualizedMessageRows.svelte

@@ -0,0 +1,299 @@
+<script lang="ts" generics="T extends { id: string }">
+  import {
+    createVirtualizer,
+    defaultRangeExtractor,
+  } from "@tanstack/svelte-virtual";
+  import { get } from "svelte/store";
+  import { onDestroy, tick, untrack, type Snippet } from "svelte";
+  import { useLayoutContext } from "../context.svelte.js";
+  import type { MessageListPosition } from "./position.js";
+
+  let {
+    items,
+    row,
+    overscan,
+    estimateSize,
+    conversationKey,
+    initialPosition,
+    onPositionChange,
+    retainRowIds,
+    hasOlder,
+    loading,
+    onLoadOlder,
+  }: {
+    items: readonly T[];
+    row: Snippet<[T, number]>;
+    overscan: number;
+    estimateSize: number;
+    conversationKey: string;
+    initialPosition?: MessageListPosition | undefined;
+    onPositionChange?: ((position: MessageListPosition) => void) | undefined;
+    retainRowIds: readonly string[];
+    hasOlder: boolean;
+    loading: boolean;
+    onLoadOlder?: () => Promise<void>;
+  } = $props();
+  const layout = useLayoutContext();
+  const stableKey = $derived(conversationKey);
+  const stableItems = $derived(items);
+  let virtualRef = $state<HTMLDivElement | null>(null);
+  let activeRowId = $state<string>();
+  let margin = $state(0);
+  let restoredKey: string | undefined;
+  let priorKey: string | undefined;
+  let priorItems: readonly T[] = [];
+  let paginationArmed = false;
+  let lastTop = 0;
+  let alive = true;
+  let priorConfiguration:
+    | {
+        key: string;
+        items: readonly T[];
+        margin: number;
+        size: number;
+        overscan: number;
+        retained: string;
+      }
+    | undefined;
+  onDestroy(() => {
+    alive = false;
+  });
+  const virtualizer = createVirtualizer<HTMLElement, HTMLDivElement>({
+    count: 0,
+    getScrollElement: () => layout?.getScrollContainer() ?? null,
+    estimateSize: () => estimateSize,
+    enabled: false,
+    useAnimationFrameWithResizeObserver: true,
+    scrollToFn: (offset, options) =>
+      layout?.streamScroll.scrollToOffset?.(
+        offset + (options.adjustments ?? 0),
+        true,
+      ),
+  });
+
+  $effect(() => {
+    layout?.setVirtualized?.(true);
+    return () => layout?.setVirtualized?.(false);
+  });
+
+  function readPosition(): MessageListPosition | undefined {
+    const instance = get(virtualizer);
+    const viewport = layout?.getScrollContainer();
+    if (!viewport || !items.length) return;
+    const first = instance
+      .getVirtualItems()
+      .find((item) => item.end > viewport.scrollTop);
+    const item = first && items[first.index];
+    if (!first || !item) return;
+    return {
+      messageId: item.id,
+      index: first.index,
+      offset: viewport.scrollTop - first.start,
+      atLatest: layout?.streamScroll.isLocked ?? false,
+    };
+  }
+
+  function reportPosition() {
+    if (
+      restoredKey !== conversationKey ||
+      document.visibilityState === "hidden"
+    )
+      return;
+    const position = readPosition();
+    if (position) untrack(() => onPositionChange?.(position));
+  }
+
+  function measure(node: HTMLDivElement) {
+    untrack(() => get(virtualizer).measureElement(node));
+    return {
+      destroy() {
+        untrack(() => get(virtualizer).measureElement(null));
+      },
+    };
+  }
+
+  // Inputs alone invalidate the virtualizer. Its returned ranges must never restart this effect.
+  $effect(() => {
+    const nextItems = stableItems,
+      key = stableKey,
+      enabled = true,
+      scrollMargin = margin;
+    const keep = [...retainRowIds, ...(activeRowId ? [activeRowId] : [])];
+    const extra = keep
+      .map((id) => nextItems.findIndex((item) => item.id === id))
+      .filter((index) => index >= 0);
+    const size = estimateSize,
+      scan = overscan;
+    untrack(() => {
+      const retained = JSON.stringify(extra);
+      if (
+        priorConfiguration?.key === key &&
+        priorConfiguration.items === nextItems &&
+        priorConfiguration.margin === scrollMargin &&
+        priorConfiguration.size === size &&
+        priorConfiguration.overscan === scan &&
+        priorConfiguration.retained === retained
+      )
+        return;
+      priorConfiguration = {
+        key,
+        items: nextItems,
+        margin: scrollMargin,
+        size,
+        overscan: scan,
+        retained,
+      };
+      const instance = get(virtualizer);
+      const viewport = layout?.getScrollContainer();
+      const oldRow = instance
+        .getVirtualItems()
+        .find((item) => item.end > (viewport?.scrollTop ?? 0));
+      const oldItem = oldRow && priorItems[oldRow.index];
+      const offset = oldRow ? (viewport?.scrollTop ?? 0) - oldRow.start : 0;
+      const revision = layout?.streamScroll.positionRevision;
+      const sameKey = priorKey === key;
+      const restore = restoredKey !== key ? initialPosition : undefined;
+      const preserve =
+        sameKey &&
+        nextItems !== priorItems &&
+        !layout?.streamScroll.isLocked &&
+        oldItem;
+      priorKey = key;
+      priorItems = nextItems;
+      if (!sameKey) {
+        restoredKey = undefined;
+        paginationArmed = false;
+        activeRowId = undefined;
+      }
+      instance.setOptions({
+        enabled,
+        count: nextItems.length,
+        scrollMargin,
+        getScrollElement: () => layout?.getScrollContainer() ?? null,
+        getItemKey: (index) => nextItems[index]!.id,
+        estimateSize: () => size,
+        overscan: scan,
+        rangeExtractor: (range) =>
+          [...new Set([...defaultRangeExtractor(range), ...extra])].sort(
+            (a, b) => a - b,
+          ),
+      });
+      void tick().then(() => {
+        if (!alive) return;
+        if (
+          key !== conversationKey ||
+          revision !== layout?.streamScroll.positionRevision
+        )
+          return;
+        if (enabled && nextItems.length) {
+          const position =
+            restore ??
+            (preserve
+              ? {
+                  messageId: oldItem.id,
+                  index: oldRow!.index,
+                  offset,
+                  atLatest: false,
+                }
+              : undefined);
+          if (position && !position.atLatest) {
+            const found = nextItems.findIndex(
+              (item) => item.id === position.messageId,
+            );
+            const index =
+              found < 0
+                ? Math.min(position.index ?? 0, nextItems.length - 1)
+                : found;
+            const start = get(virtualizer).getOffsetForIndex(
+              index,
+              "start",
+            )?.[0];
+            if (start !== undefined)
+              layout?.streamScroll.scrollToOffset?.(
+                start + position.offset,
+                Boolean(preserve),
+              );
+          } else if (!sameKey || layout?.streamScroll.isLocked)
+            layout?.streamScroll.scrollIfLocked();
+        }
+        if (nextItems.length) {
+          restoredKey = key;
+          reportPosition();
+        }
+      });
+    });
+  });
+  $effect(() => {
+    const content = virtualRef;
+    const viewport = layout?.getScrollContainer();
+    if (!content || !viewport) return;
+    const measureMargin = () => {
+      const next =
+        content.getBoundingClientRect().top -
+        viewport.getBoundingClientRect().top +
+        viewport.scrollTop;
+      if (Math.abs(next - margin) > 0.5) margin = next;
+    };
+    measureMargin();
+    const observer = new ResizeObserver(measureMargin);
+    observer.observe(content);
+    return () => observer.disconnect();
+  });
+  $effect(() => {
+    const viewport = layout?.getScrollContainer();
+    if (!viewport) return;
+    const onScroll = () => {
+      const top = viewport.scrollTop;
+      if (top > 600) paginationArmed = true;
+      if (
+        top <= 600 &&
+        top < lastTop &&
+        paginationArmed &&
+        hasOlder &&
+        !loading
+      ) {
+        paginationArmed = false;
+        void onLoadOlder?.();
+      }
+      lastTop = top;
+      reportPosition();
+    };
+    const rememberInteraction = (event: Event) => {
+      const target = event.target;
+      if (target instanceof Element)
+        activeRowId =
+          target.closest<HTMLElement>("[data-message-id]")?.dataset.messageId;
+    };
+    viewport.addEventListener("scroll", onScroll, { passive: true });
+    viewport.addEventListener("focusin", rememberInteraction);
+    viewport.addEventListener("pointerdown", rememberInteraction, {
+      passive: true,
+    });
+    return () => {
+      viewport.removeEventListener("scroll", onScroll);
+      viewport.removeEventListener("focusin", rememberInteraction);
+      viewport.removeEventListener("pointerdown", rememberInteraction);
+    };
+  });
+</script>
+
+<div
+  bind:this={virtualRef}
+  data-ui-part="virtual-content"
+  style:height={`${$virtualizer.getTotalSize()}px`}
+>
+  {#each $virtualizer.getVirtualItems() as virtualRow (virtualRow.key)}
+    {@const item = items[virtualRow.index]}
+    {#if item}
+      <div
+        data-ui-part="virtual-row"
+        data-message-id={item.id}
+        data-index={virtualRow.index}
+        style:transform={`translateY(${virtualRow.start - margin}px)`}
+        use:measure
+      >
+        {@render row(item, virtualRow.index)}
+      </div>
+    {/if}
+  {/each}
+</div>