@lapismd/design-core 0.1.2 → 0.2.0

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>

package/src/shared/ai/message-list/position.ts

@@ -0,0 +1,7 @@
+/** A consumer-owned reading position, relative to a stable message row. */
+export interface MessageListPosition {
+  messageId: string;
+  index?: number;
+  offset: number;
+  atLatest: boolean;
+}

package/src/shared/ai/new-messages.svelte.ts

@@ -1,6 +1,10 @@
 export type NewMessagesOptions = {
   isLocked: () => boolean;
   onResize?: () => void;
+  /** Opt in to coalescing geometry work outside the ResizeObserver delivery. */
+  deferResize?: boolean | (() => boolean);
+  requestAnimationFrame?: typeof globalThis.requestAnimationFrame;
+  cancelAnimationFrame?: typeof globalThis.cancelAnimationFrame;
   createResizeObserver?: (
     callback: ResizeObserverCallback,
   ) => Pick<ResizeObserver, "observe" | "disconnect">;
@@ -19,8 +23,8 @@ export function createNewMessages(
 ): NewMessagesController {
   let element: HTMLElement | null = null;
   let observer: Pick<ResizeObserver, "observe" | "disconnect"> | null = null;
-  let initialized = false;
   let hasNewMessages = $state(false);
+  let resizeFrame = 0;
   const seenMessageIds = new Set<string>();
 
   const makeObserver =
@@ -44,20 +48,35 @@ export function createNewMessages(
 
     observer = makeObserver((entries) => {
       if (!entries.some((entry) => entry.target === element)) return;
-      if (!initialized) {
-        initialized = true;
+      const deferred =
+        typeof options.deferResize === "function"
+          ? options.deferResize()
+          : options.deferResize;
+      if (!deferred) {
+        options.onResize?.();
         return;
       }
-      markNew();
+      if (resizeFrame) return;
+      const current = element;
+      resizeFrame = (options.requestAnimationFrame ?? requestAnimationFrame)(
+        () => {
+          resizeFrame = 0;
+          if (element === current) options.onResize?.();
+        },
+      );
     });
     observer?.observe(element);
   }
 
   function cleanup(): void {
+    if (resizeFrame)
+      (options.cancelAnimationFrame ?? cancelAnimationFrame)(resizeFrame);
+    resizeFrame = 0;
     observer?.disconnect();
     observer = null;
     element = null;
-    initialized = false;
+    hasNewMessages = false;
+    seenMessageIds.clear();
   }
 
   return {