@sableui/react 0.6.2 → 0.7.1

package/dist/components/message-scroller/message-scroller.js

@@ -0,0 +1,300 @@
+"use client";
+
+// src/components/message-scroller/message-scroller.tsx
+import { useCallback, useEffect, useImperativeHandle, useRef, useState } from "react";
+import { Icon } from "../../icon/index.js";
+import { cn } from "../../lib/cn.js";
+import { useDensity } from "../../lib/density.js";
+import { useIsomorphicLayoutEffect } from "../../lib/use-isomorphic-layout-effect.js";
+import { useScrollActivity } from "../../lib/use-scroll-activity.js";
+import { useMotion } from "../../motion/MotionProvider.js";
+import { Button } from "../button/index.js";
+import { SimpleTooltip } from "../tooltip/index.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var DEFAULT_FOLLOW_THRESHOLD = 64;
+var GAP_CLASSES = {
+  comfortable: {
+    sm: "gap-2 [--message-gap:calc(var(--spacing)*2)]",
+    md: "gap-4 [--message-gap:calc(var(--spacing)*4)]",
+    lg: "gap-6 [--message-gap:calc(var(--spacing)*6)]"
+  },
+  compact: {
+    sm: "gap-1.5 [--message-gap:calc(var(--spacing)*1.5)]",
+    md: "gap-3 [--message-gap:calc(var(--spacing)*3)]",
+    lg: "gap-4 [--message-gap:calc(var(--spacing)*4)]"
+  }
+};
+function MessageScroller({
+  ref,
+  autoFollow = true,
+  followThreshold = DEFAULT_FOLLOW_THRESHOLD,
+  onFollowChange,
+  initialScroll = "bottom",
+  jumpToLatest = true,
+  jumpToLatestLabel = "Jump to latest",
+  gap = "md",
+  onVisibleMessagesChange,
+  className,
+  children,
+  onScroll,
+  ...props
+}) {
+  const viewportRef = useRef(null);
+  const contentRef = useRef(null);
+  const { enabled: motionEnabled } = useMotion();
+  const density = useDensity();
+  const trackActivity = useScrollActivity();
+  const setViewport = useCallback(
+    (node) => {
+      trackActivity(node);
+      viewportRef.current = node;
+    },
+    [trackActivity]
+  );
+  const [atBottom, setAtBottom] = useState(true);
+  const followingRef = useRef(autoFollow);
+  followingRef.current = autoFollow && atBottom;
+  const thresholdRef = useRef(followThreshold);
+  thresholdRef.current = followThreshold;
+  const scrollBehavior = useCallback(
+    (animate) => animate !== false && motionEnabled ? "smooth" : "auto",
+    [motionEnabled]
+  );
+  const anchor = useRef({
+    node: null,
+    top: 0
+  });
+  const captureAnchor = useCallback(() => {
+    const content = contentRef.current;
+    if (!content) return;
+    const node = content.querySelector("[data-message-id]") ?? content.firstElementChild;
+    anchor.current = { node, top: node ? node.offsetTop : 0 };
+  }, []);
+  const scrollToBottomNow = useCallback((behavior) => {
+    const viewport = viewportRef.current;
+    if (!viewport) return;
+    viewport.scrollTo({ top: viewport.scrollHeight, behavior });
+  }, []);
+  const observer = useRef(null);
+  const observed = useRef(/* @__PURE__ */ new Map());
+  const visible = useRef(/* @__PURE__ */ new Set());
+  const reported = useRef("");
+  const onVisibleRef = useRef(onVisibleMessagesChange);
+  onVisibleRef.current = onVisibleMessagesChange;
+  const reportVisible = useCallback(() => {
+    const content = contentRef.current;
+    const notify = onVisibleRef.current;
+    if (!content || !notify) return;
+    const ids = [];
+    for (const node of content.querySelectorAll("[data-message-id]")) {
+      const id = node.dataset.messageId;
+      if (id && visible.current.has(id)) ids.push(id);
+    }
+    const key = ids.join("\0");
+    if (key === reported.current) return;
+    reported.current = key;
+    notify(ids);
+  }, []);
+  const syncObservedMessages = useCallback(() => {
+    const io = observer.current;
+    const content = contentRef.current;
+    if (!io || !content) return;
+    const nodes = new Set(
+      content.querySelectorAll("[data-message-id]")
+    );
+    for (const [node, id] of observed.current) {
+      if (nodes.has(node)) continue;
+      io.unobserve(node);
+      observed.current.delete(node);
+      visible.current.delete(id);
+    }
+    for (const node of nodes) {
+      if (observed.current.has(node)) continue;
+      const id = node.dataset.messageId;
+      if (!id) continue;
+      observed.current.set(node, id);
+      io.observe(node);
+    }
+    reportVisible();
+  }, [reportVisible]);
+  const onContentChange = useCallback(() => {
+    const viewport = viewportRef.current;
+    const content = contentRef.current;
+    if (!viewport || !content) return;
+    if (followingRef.current) {
+      scrollToBottomNow("auto");
+    } else {
+      const { node, top } = anchor.current;
+      if (node?.isConnected && node.parentElement === content) {
+        const shift = node.offsetTop - top;
+        if (shift !== 0) viewport.scrollTop += shift;
+      }
+    }
+    captureAnchor();
+    syncObservedMessages();
+  }, [captureAnchor, scrollToBottomNow, syncObservedMessages]);
+  useEffect(() => {
+    const viewport = viewportRef.current;
+    const content = contentRef.current;
+    if (!viewport || !content) return;
+    const mutations = new MutationObserver(onContentChange);
+    mutations.observe(content, {
+      childList: true,
+      subtree: true,
+      characterData: true
+    });
+    const resizes = new ResizeObserver(onContentChange);
+    resizes.observe(content);
+    return () => {
+      mutations.disconnect();
+      resizes.disconnect();
+    };
+  }, [onContentChange]);
+  useEffect(() => {
+    if (!onVisibleMessagesChange) return;
+    const viewport = viewportRef.current;
+    if (!viewport) return;
+    observer.current = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          const id = entry.target.dataset.messageId;
+          if (!id) continue;
+          if (entry.isIntersecting) visible.current.add(id);
+          else visible.current.delete(id);
+        }
+        reportVisible();
+      },
+      { root: viewport }
+    );
+    syncObservedMessages();
+    return () => {
+      observer.current?.disconnect();
+      observer.current = null;
+      observed.current.clear();
+      visible.current.clear();
+      reported.current = "";
+    };
+  }, [onVisibleMessagesChange, reportVisible, syncObservedMessages]);
+  useIsomorphicLayoutEffect(() => {
+    const viewport = viewportRef.current;
+    if (!viewport) return;
+    if (typeof initialScroll === "object") {
+      const target = viewport.querySelector(
+        `[data-message-id="${CSS.escape(initialScroll.messageId)}"]`
+      );
+      if (target) {
+        target.scrollIntoView({ block: "center", behavior: "auto" });
+      } else {
+        viewport.scrollTop = viewport.scrollHeight;
+      }
+    } else if (initialScroll === "top") {
+      viewport.scrollTop = 0;
+    } else {
+      viewport.scrollTop = viewport.scrollHeight;
+    }
+    const distance = viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight;
+    setAtBottom(distance <= thresholdRef.current);
+    captureAnchor();
+  }, []);
+  const setFollowing = useCallback(
+    (next) => {
+      setAtBottom((prev) => {
+        if (prev === next) return prev;
+        onFollowChange?.(next && autoFollow);
+        return next;
+      });
+    },
+    [autoFollow, onFollowChange]
+  );
+  const handleScroll = useCallback(
+    (event) => {
+      const el = event.currentTarget;
+      const distance = el.scrollHeight - el.scrollTop - el.clientHeight;
+      setFollowing(distance <= thresholdRef.current);
+      captureAnchor();
+      onScroll?.(event);
+    },
+    [captureAnchor, onScroll, setFollowing]
+  );
+  useImperativeHandle(
+    ref,
+    () => ({
+      get element() {
+        return viewportRef.current;
+      },
+      scrollToBottom: (options) => {
+        scrollToBottomNow(scrollBehavior(options?.animate));
+      },
+      scrollToTop: (options) => {
+        viewportRef.current?.scrollTo({
+          top: 0,
+          behavior: scrollBehavior(options?.animate)
+        });
+      },
+      scrollToMessage: (id, options) => {
+        const viewport = viewportRef.current;
+        if (!viewport) return false;
+        const target = viewport.querySelector(
+          `[data-message-id="${CSS.escape(id)}"]`
+        );
+        if (!target) return false;
+        target.scrollIntoView({
+          block: options?.block ?? "center",
+          behavior: scrollBehavior(options?.animate)
+        });
+        return true;
+      },
+      isFollowing: () => followingRef.current
+    }),
+    [scrollBehavior, scrollToBottomNow]
+  );
+  const showJump = jumpToLatest && !atBottom;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref: setViewport,
+      onScroll: handleScroll,
+      className: cn(
+        // `relative` is load-bearing twice over: it makes the viewport the
+        // offsetParent the prepend anchor is measured against, and it is the
+        // containing block the jump control sticks inside.
+        "relative scrollbar-quiet overflow-y-auto overscroll-contain",
+        className
+      ),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            ref: contentRef,
+            className: cn("flex flex-col", GAP_CLASSES[density][gap]),
+            children
+          }
+        ),
+        showJump ? (
+          /* Sticky rather than absolutely positioned over a wrapper — that is
+             what lets `className` stay on the scrolling element instead of
+             moving to a wrapper the consumer then has to reach past. A
+             zero-height last child pins to the bottom edge while the reader is
+             scrolled up and costs no scroll height. */
+          /* @__PURE__ */ jsx("div", { className: "pointer-events-none sticky bottom-4 flex h-0 items-end justify-center", children: /* @__PURE__ */ jsx(SimpleTooltip, { content: jumpToLatestLabel, children: /* @__PURE__ */ jsx(
+            Button,
+            {
+              type: "button",
+              variant: "floating",
+              size: "icon-sm",
+              "aria-label": jumpToLatestLabel,
+              onClick: () => scrollToBottomNow(scrollBehavior(true)),
+              className: "pointer-events-auto animate-fade-up",
+              children: /* @__PURE__ */ jsx(Icon, { name: "chevron-down", className: "text-base" })
+            }
+          ) }) })
+        ) : null
+      ]
+    }
+  );
+}
+MessageScroller.displayName = "MessageScroller";
+export {
+  MessageScroller
+};

package/dist/components/message-scroller/message-scroller.meta.js

@@ -0,0 +1,172 @@
+// src/components/message-scroller/message-scroller.meta.ts
+var messageScrollerMeta = {
+  name: "MessageScroller",
+  summary: "Scroll container for a conversation. Auto-follows new messages until the reader scrolls away, holds position when older history is prepended, and exposes scroll commands and visibility tracking through its ref.",
+  status: "stable",
+  keywords: [
+    "chat",
+    "conversation",
+    "messages",
+    "thread",
+    "transcript",
+    "stick to bottom",
+    "auto scroll",
+    "streaming",
+    "infinite scroll",
+    "inbox",
+    "ai chat",
+    "support chat"
+  ],
+  usage: {
+    description: "The scroll region a conversation lives in. It owns the scrolling and nothing else \u2014 not your messages, not your AI state, not your transport or persistence \u2014 so you bring the content renderer and it handles the behaviors that make streaming chat feel right: pinning to the newest message, releasing when the reader scrolls up, keeping the view still when older history loads above, jumping to a specific message, restoring a saved read position, and reporting what is actually on screen.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Bound it the way you would bound any scroll box \u2014 `flex-1 min-h-0` inside a flex column, or `max-h-96`. `className` lands on the element that actually scrolls, so the obvious bound is the correct one (same contract as Scroller)."
+      },
+      {
+        guidance: "do",
+        description: "Give every Message a `messageId`. It is the handle for `scrollToMessage`, `initialScroll`, and `onVisibleMessagesChange` \u2014 a message without one is invisible to all three."
+      },
+      {
+        guidance: "do",
+        description: "Prepend older history directly into `children` when the reader reaches the top. The scroller anchors on the first rendered message and re-adds the height that appeared above it, so the view does not jump."
+      },
+      {
+        guidance: "do",
+        description: "Set the rhythm between messages with the `gap` prop, not with a flex class on `className` \u2014 the messages are laid out in a column inside the scroll region, not directly on it."
+      },
+      {
+        guidance: "do",
+        description: "Restore a reopened thread with `initialScroll={{ messageId: lastRead }}` instead of dropping the reader at the bottom of a conversation they have not finished."
+      },
+      {
+        guidance: "do",
+        description: 'Wrap a docked agent panel in `<Density value="compact">`. The scroller tightens its rhythm and every message inside it drops to the workspace type tier \u2014 one attribute for the whole conversation, no per-component sizing.'
+      },
+      {
+        guidance: "dont",
+        description: "Do not call `scrollToBottom` on every incoming token. Auto-follow already does it, and doing it yourself fights the reader who scrolled up to read something."
+      },
+      {
+        guidance: "dont",
+        description: "Do not expect `ref` to be the DOM node \u2014 it is a command handle (`scrollToBottom`, `scrollToMessage`, `isFollowing`). Reach for `ref.current.element` when you genuinely need the element."
+      },
+      {
+        guidance: "dont",
+        description: "Do not wrap it in a positioned div to place a jump-to-latest button. It ships one, stuck to the bottom edge from inside the scroll region, which is why `className` gets to stay on the scrolling element."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it for an ordinary long list. That is `Scroller` \u2014 this one's follow-the-bottom behavior is wrong for content the reader is browsing rather than receiving."
+      }
+    ],
+    anatomy: [
+      {
+        name: "Scroll region",
+        required: true,
+        description: "The element that scrolls. Carries `className`: sizing, padding, and background."
+      },
+      {
+        name: "Message column",
+        required: true,
+        description: "The flex column holding the children, spaced by `gap`. Publishes `--message-gap` so `<Message grouped>` can close it."
+      },
+      {
+        name: "Jump to latest",
+        required: false,
+        description: "A control stuck to the bottom edge, shown only while the reader is scrolled away from the newest message."
+      }
+    ]
+  },
+  related: {
+    components: ["Message", "Bubble", "Marker", "Attachment", "Scroller"]
+  },
+  props: [
+    {
+      name: "ref",
+      type: "Ref<MessageScrollerHandle>",
+      description: "Imperative commands, not the DOM node: `scrollToBottom(opts)`, `scrollToTop(opts)`, `scrollToMessage(id, opts)` (returns false when the message is not rendered), `isFollowing()`, and `element` for the scrolling node itself."
+    },
+    {
+      name: "autoFollow",
+      type: "boolean",
+      default: "true",
+      description: "Keep the newest message in view as content arrives, until the reader scrolls away from the bottom. Set false for a transcript that must never move under the reader."
+    },
+    {
+      name: "followThreshold",
+      type: "number",
+      default: "64",
+      description: "Distance from the bottom, in px, that still counts as following. A band rather than a pixel, so a token arriving mid-frame does not flicker the state."
+    },
+    {
+      name: "onFollowChange",
+      type: "(following: boolean) => void",
+      description: "Notified when the viewport pins to, or releases from, the newest message."
+    },
+    {
+      name: "initialScroll",
+      type: '"bottom" | "top" | { messageId: string }',
+      default: '"bottom"',
+      description: "Where a freshly mounted thread lands. Pass a messageId to restore a saved read position. Applied once, on mount \u2014 changing it later will not yank a reader mid-conversation."
+    },
+    {
+      name: "jumpToLatest",
+      type: "boolean",
+      default: "true",
+      description: "Show the jump-to-latest control while the reader is scrolled away from the newest message."
+    },
+    {
+      name: "jumpToLatestLabel",
+      type: "string",
+      default: '"Jump to latest"',
+      description: "Accessible label and tooltip for that control."
+    },
+    {
+      name: "gap",
+      type: '"sm" | "md" | "lg"',
+      default: '"md"',
+      description: "Vertical rhythm between messages. Also published as `--message-gap`, which `<Message grouped>` reads to collapse the gap within a run."
+    },
+    {
+      name: "onVisibleMessagesChange",
+      type: "(ids: string[]) => void",
+      description: "Ids of the messages currently intersecting the viewport, in DOM order. The hook for read receipts, mark-as-seen, and unread counters."
+    },
+    {
+      name: "...div props",
+      type: 'Omit<ComponentPropsWithRef<"div">, "ref">',
+      description: "Spread onto the scrolling element. `className` bounds and pads the scroll region; `onScroll` composes with the component's own."
+    }
+  ],
+  variants: { gap: ["sm", "md", "lg"] },
+  tokensUsed: ["border", "secondary", "secondary-foreground", "ring"],
+  a11y: [
+    "Native overflow, so keyboard scrolling (arrows, Page Up/Down, Home/End) and the OS scrollbar work unchanged; the scrollbar is styled thin, not replaced.",
+    "Overscroll is contained, so a wheel gesture that runs out of conversation does not start scrolling the page behind it.",
+    "The jump-to-latest control is a real button with an accessible label, reachable by keyboard, and only present when there is somewhere to jump to.",
+    "Smooth scrolling is used only when motion is enabled \u2014 `prefers-reduced-motion` and <MotionProvider> off both collapse every scroll command to an instant jump."
+  ],
+  examples: [
+    {
+      label: "Streaming conversation",
+      code: '<MessageScroller className="flex-1 min-h-0 px-4 py-6">{messages.map((m) => (<Message key={m.id} messageId={m.id} align={m.mine ? "end" : "start"}><Bubble variant={m.mine ? "primary" : "muted"} align={m.mine ? "end" : "start"}>{m.body}</Bubble></Message>))}{pending ? <Marker icon="spinner" spin shimmer>Thinking\u2026</Marker> : null}</MessageScroller>'
+    },
+    {
+      label: "Scroll to a message on demand",
+      code: 'function Thread({ messages, replyTo }) {\n	const thread = useRef(null)\n	return (\n		<>\n			<Button onClick={() => thread.current?.scrollToMessage(replyTo)}>Show original</Button>\n			<MessageScroller ref={thread} className="max-h-96">\n				{messages.map((m) => (<Message key={m.id} messageId={m.id}><Bubble>{m.body}</Bubble></Message>))}\n			</MessageScroller>\n		</>\n	)\n}'
+    },
+    {
+      label: "Restore a saved read position and track receipts",
+      code: '<MessageScroller className="h-96" initialScroll={{ messageId: lastRead }} onVisibleMessagesChange={(ids) => markSeen(ids)}>{messages.map((m) => (<Message key={m.id} messageId={m.id}><Bubble>{m.body}</Bubble></Message>))}</MessageScroller>'
+    },
+    {
+      label: "Prepend older history without moving the view",
+      code: '<MessageScroller className="h-96" gap="sm">{hasMore ? <Button variant="secondary" loadingLabel="Loading\u2026" onClick={loadOlder}>Load earlier messages</Button> : null}{messages.map((m) => (<Message key={m.id} messageId={m.id}><Bubble>{m.body}</Bubble></Message>))}</MessageScroller>'
+    }
+  ]
+};
+export {
+  messageScrollerMeta
+};

package/dist/components/meter/index.js

@@ -0,0 +1,20 @@
+// src/components/meter/index.ts
+import {
+  Meter,
+  MeterIndicator,
+  MeterLabel,
+  MeterTrack,
+  MeterValue
+} from "./meter.js";
+import { meterIndicatorVariants, meterTrackVariants } from "./meter.variants.js";
+import { meterMeta } from "./meter.meta.js";
+export {
+  Meter,
+  MeterIndicator,
+  MeterLabel,
+  MeterTrack,
+  MeterValue,
+  meterIndicatorVariants,
+  meterMeta,
+  meterTrackVariants
+};

package/dist/components/meter/meter.js

@@ -0,0 +1,112 @@
+// src/components/meter/meter.tsx
+import { Meter as Base } from "@base-ui/react/meter";
+import { createContext, useContext } from "react";
+import { cn } from "../../lib/cn.js";
+import {
+  meterIndicatorVariants,
+  meterRingValueVariants,
+  meterRingVariants,
+  meterTrackVariants
+} from "./meter.variants.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var ToneContext = createContext("primary");
+var SizeContext = createContext(void 0);
+var RING_TONE_STROKE = {
+  primary: "var(--primary)",
+  standard: "var(--tone-standard)",
+  success: "var(--success)",
+  warning: "var(--tone-warning)",
+  destructive: "var(--destructive)"
+};
+function MeterRing({
+  value,
+  min = 0,
+  max = 100,
+  strokeWidth,
+  showValue,
+  tone,
+  size
+}) {
+  const ratio = value == null || max === min ? 0 : Math.min(1, Math.max(0, (value - min) / (max - min)));
+  const radius = 50 - strokeWidth;
+  const circumference = 2 * Math.PI * radius;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs("svg", { viewBox: "0 0 100 100", className: "size-full", "aria-hidden": "true", focusable: "false", children: [
+      /* @__PURE__ */ jsx("circle", { cx: 50, cy: 50, r: radius, fill: "none", strokeWidth, style: { stroke: "var(--secondary)" } }),
+      /* @__PURE__ */ jsx(
+        "circle",
+        {
+          cx: 50,
+          cy: 50,
+          r: radius,
+          fill: "none",
+          strokeWidth,
+          strokeLinecap: "round",
+          strokeDasharray: circumference,
+          strokeDashoffset: circumference * (1 - ratio),
+          transform: "rotate(-90 50 50)",
+          className: "transition-[stroke-dashoffset] duration-(--motion-duration-slow) ease-decelerate",
+          style: { stroke: RING_TONE_STROKE[tone] }
+        }
+      )
+    ] }),
+    showValue ? /* @__PURE__ */ jsx(MeterValue, { className: meterRingValueVariants({ size }) }) : null
+  ] });
+}
+function Meter({ className, children, tone = "primary", shape = "bar", size, strokeWidth = 6, showValue, ...props }) {
+  if (shape === "ring") {
+    return /* @__PURE__ */ jsx(ToneContext.Provider, { value: tone, children: /* @__PURE__ */ jsx(Base.Root, { className: cn(meterRingVariants({ size }), className), ...props, children: children ?? /* @__PURE__ */ jsx(MeterRing, { value: props.value ?? null, min: props.min, max: props.max, strokeWidth, showValue, tone, size }) }) });
+  }
+  return /* @__PURE__ */ jsx(ToneContext.Provider, { value: tone, children: /* @__PURE__ */ jsx(SizeContext.Provider, { value: size, children: /* @__PURE__ */ jsx(Base.Root, { className: cn("w-full", className), ...props, children: children ?? /* @__PURE__ */ jsx(MeterTrack, {}) }) }) });
+}
+Meter.displayName = "Meter";
+function MeterTrack({ className, children, size, ...props }) {
+  const inherited = useContext(SizeContext);
+  return /* @__PURE__ */ jsx(
+    Base.Track,
+    {
+      className: cn(meterTrackVariants({ size: size ?? inherited }), className),
+      ...props,
+      children: children ?? /* @__PURE__ */ jsx(MeterIndicator, {})
+    }
+  );
+}
+MeterTrack.displayName = "MeterTrack";
+function MeterIndicator({ className, tone, ...props }) {
+  const inherited = useContext(ToneContext);
+  return /* @__PURE__ */ jsx(
+    Base.Indicator,
+    {
+      className: cn(meterIndicatorVariants({ tone: tone ?? inherited }), className),
+      ...props
+    }
+  );
+}
+MeterIndicator.displayName = "MeterIndicator";
+function MeterLabel({ className, ...props }) {
+  return /* @__PURE__ */ jsx(
+    Base.Label,
+    {
+      className: cn("text-label-md text-foreground", className),
+      ...props
+    }
+  );
+}
+MeterLabel.displayName = "MeterLabel";
+function MeterValue({ className, ...props }) {
+  return /* @__PURE__ */ jsx(
+    Base.Value,
+    {
+      className: cn("text-mono-sm text-muted-foreground", className),
+      ...props
+    }
+  );
+}
+MeterValue.displayName = "MeterValue";
+export {
+  Meter,
+  MeterIndicator,
+  MeterLabel,
+  MeterTrack,
+  MeterValue
+};