@robr0/design-system 0.4.0 → 0.6.0

package/components/ChatThread/ChatThread.css

@@ -0,0 +1,171 @@
+/* ============================================
+   CHAT THREAD COMPONENT
+   Scrollable conversation column: edge fades,
+   send-to-top anchoring, subtle scrollbar.
+   ============================================ */
+
+/* Base — the root is the scroll container. Inline gutters live on
+   __content, so the scrollbar rides the component's far edge. */
+.ds-chat-thread {
+  position: relative;
+  overflow-y: auto;
+  min-height: 0;
+  /* The component owns anchoring; the browser's native scroll anchoring
+     otherwise latches onto the trailing spacer and drags the viewport
+     down while a response streams in. */
+  overflow-anchor: none;
+  /* Anchoring scrolls glide; the reduced-motion guard in tokens-motion.css
+     forces scroll-behavior back to auto. */
+  scroll-behavior: smooth;
+
+  /* Subtle scrollbar — invisible until the thread is actually scrolling.
+     The gutter is reserved permanently: on classic-scrollbar platforms a
+     scrollbar popping in (the first overflowing turn, or a rounding
+     flicker mid-animation) would otherwise reflow the content sideways. */
+  scrollbar-width: thin;
+  scrollbar-gutter: stable;
+  scrollbar-color: transparent transparent;
+  transition: scrollbar-color var(--motion-duration-base) var(--motion-ease-standard);
+
+  /* Edge fades — a CSS mask, not a scroll listener: content scrolling out
+     at either end passes through the fade.
+     ds-allow(color): mask alpha keywords (black/transparent), not palette colours */
+  -webkit-mask-image: linear-gradient(
+    to bottom,
+    transparent,
+    black var(--gap-lg),
+    black calc(100% - var(--gap-lg)),
+    transparent
+  );
+  mask-image: linear-gradient(
+    to bottom,
+    transparent,
+    black var(--gap-lg),
+    black calc(100% - var(--gap-lg)),
+    transparent
+  );
+}
+
+/* States */
+.ds-chat-thread--scrolling {
+  scrollbar-color: var(--color-divider) transparent;
+}
+
+.ds-chat-thread:focus-visible {
+  outline: 2px solid var(--color-action-primary-bg);
+  outline-offset: -2px;
+}
+
+/* Content — the turns. Consumers override the inline gutters (mobile
+   densities) through --ds-chat-thread-padding-inline, and can cap the
+   conversation column through --ds-chat-thread-content-max-width: the
+   column centres itself while the scroll container, its fades, and the
+   scrollbar keep spanning the full component width. */
+.ds-chat-thread__content {
+  display: flex;
+  flex-direction: column;
+  gap: var(--gap-xl);
+  max-width: var(--ds-chat-thread-content-max-width, none);
+  margin-inline: auto;
+  /* Roomy bottom padding: the end of a long response rests 40px clear of
+     the composer, so the last lines stay readable. The right padding
+     subtracts the measured scrollbar gutter (--ds-chat-thread-gutter, set
+     by the component) so the column stays symmetric and aligned with its
+     surroundings on classic-scrollbar platforms. */
+  padding: var(--padding-lg)
+    max(0px, calc(var(--ds-chat-thread-padding-inline, var(--padding-lg)) - var(--ds-chat-thread-gutter, 0px)))
+    var(--padding-xl) var(--ds-chat-thread-padding-inline, var(--padding-lg));
+  /* The first send into an empty thread floats up from composer level —
+     a transform glide, since no scroll distance exists yet. Later sends
+     glide via scroll instead; this transition only ever sees the
+     component-driven translateY. */
+  transition: transform var(--motion-duration-slower) var(--motion-ease-entrance);
+}
+
+/* The list scrolls; entries never shrink. Without this, children that clip
+   their own overflow collapse when the column overflows. */
+.ds-chat-thread__content > * {
+  flex-shrink: 0;
+}
+
+/* Trailing spacer — sized by the component so the newest turn can always
+   reach the top of the viewport, and holds no more room than that: it
+   shrinks away as a response grows into the space it was reserving. */
+.ds-chat-thread__spacer {
+  height: 0;
+}
+
+/* Scroll-to-bottom — a sticky, zero-height slot pinned just above the
+   bottom fade, so the control floats centred over the transcript right
+   on top of the composer. */
+.ds-chat-thread__jump-slot {
+  position: sticky;
+  bottom: var(--gap-lg);
+  height: 0;
+  display: flex;
+  justify-content: center;
+  /* Bottom-align against the zero-height line — the default stretch
+     would squash the circle flat. */
+  align-items: flex-end;
+  /* The slot spans the content box, which excludes the gutter; this
+     re-centres the control on the full component width. */
+  padding-left: var(--ds-chat-thread-gutter, 0px);
+  z-index: 1;
+}
+
+/* The passive ramp is a ghost family meant to paint over a surface, so
+   the floating pill supplies its own: container surface + border below,
+   the passive layer above stepping through rest, hover, and active. */
+.ds-chat-thread__jump {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  /* The send button's exact footprint — CircularButton's default size,
+     a raw value there too (icon-button sizes are not on a token scale). */
+  width: 40px;
+  height: 40px;
+  padding: 0;
+  border: var(--border-xs) solid var(--color-bg-container-border);
+  border-radius: var(--radius-full);
+  background-color: var(--color-bg-container-primary);
+  background-image: linear-gradient(
+    var(--color-action-passive-bg),
+    var(--color-action-passive-bg)
+  );
+  color: var(--color-action-passive-text);
+  box-shadow: var(--shadow-floating);
+  cursor: pointer;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity var(--motion-duration-base) var(--motion-ease-standard);
+}
+
+.ds-chat-thread__jump--visible {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.ds-chat-thread__jump:hover {
+  background-image: linear-gradient(
+    var(--color-action-passive-bg-hover),
+    var(--color-action-passive-bg-hover)
+  );
+}
+
+.ds-chat-thread__jump:active {
+  background-image: linear-gradient(
+    var(--color-action-passive-bg-active),
+    var(--color-action-passive-bg-active)
+  );
+}
+
+.ds-chat-thread__jump:focus-visible {
+  outline: 2px solid var(--color-action-primary-bg);
+  outline-offset: 2px;
+}
+
+/* The glyph matches the send button's: --icon-size-md in a 40px circle
+   (icon plus the padding ring), pointing the other way. */
+.ds-chat-thread__jump-icon {
+  --icon-size: var(--icon-size-md);
+}

package/components/ChatThread/ChatThread.d.ts

@@ -0,0 +1,41 @@
+import { default as React } from 'react';
+/** Props owned by ChatThread itself — everything else falls through to the root element. */
+type ChatThreadOwnProps = {
+    /**
+     * Scroll a newly appended turn to the top of the viewport, pushing the
+     * prior conversation upward. When a user turn and the agent's pending
+     * turn are appended in the same update, the first new child is the one
+     * anchored — the response streams in below it. Detection diffs the DOM
+     * child count, so replacing turns in place (a future regenerate or
+     * edit-last-turn) neither re-anchors nor resizes the spacer.
+     */
+    anchor?: boolean;
+    /** Accessible name for the scrollable conversation region. */
+    ariaLabel?: string;
+    /** Accessible name for the scroll-to-bottom control. */
+    jumpLabel?: string;
+    /** Additional CSS classes */
+    className?: string;
+    /** The conversation, in order: ChatMessages, ChatMarkers. */
+    children?: React.ReactNode;
+};
+export interface ChatThreadProps extends ChatThreadOwnProps, Omit<React.ComponentPropsWithoutRef<'div'>, keyof ChatThreadOwnProps> {
+}
+/**
+ * ChatThread is the scrollable conversation column: consistent gutters, a
+ * pure-CSS fade at either end so content scrolling out passes through it,
+ * and the send choreography — a newly appended turn floats to the top of
+ * the viewport while the prior conversation is pushed upward, leaving the
+ * response room to stream in below.
+ *
+ * A trailing spacer grows just enough that even a short newest exchange can
+ * reach the top, so the anchor position never depends on how much has been
+ * said. The scrollbar stays hidden until the thread is actually scrolling,
+ * and rides the component's far edge — the content gutters live on an inner
+ * wrapper, overridable via `--ds-chat-thread-padding-inline`.
+ *
+ * The smooth scroll respects reduced motion (the motion tokens' guard forces
+ * instant scrolling). Forwards a ref to the scrollable root element.
+ */
+export declare const ChatThread: React.ForwardRefExoticComponent<ChatThreadProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/components/ChatThread/ChatThread.js

@@ -0,0 +1,174 @@
+import { jsxs, jsx } from "react/jsx-runtime";
+import React, { useRef, useEffect, useState, useLayoutEffect } from "react";
+import "./ChatThread.css";
+import "../../fonts/material-symbols.css";
+const SCROLLBAR_SETTLE_MS = 600;
+const JUMP_THRESHOLD_PX = 24;
+const ChatThread = React.forwardRef(
+  ({
+    anchor = true,
+    ariaLabel = "Conversation",
+    jumpLabel = "Scroll to the latest message",
+    className = "",
+    children,
+    onScroll,
+    ...rest
+  }, ref) => {
+    const baseClass = "ds-chat-thread";
+    const scrollRef = useRef(null);
+    const contentRef = useRef(null);
+    const spacerRef = useRef(null);
+    const prevCount = useRef(0);
+    const mounted = useRef(false);
+    const anchorTop = useRef(null);
+    const sizeSpacer = () => {
+      const container = scrollRef.current;
+      const content = contentRef.current;
+      const spacer = spacerRef.current;
+      const top = anchorTop.current;
+      if (!container || !content || !spacer || top == null) return;
+      const needed = Math.max(0, top + container.clientHeight - content.offsetHeight);
+      if (Math.abs(needed - spacer.offsetHeight) > 1) spacer.style.height = `${needed}px`;
+    };
+    useEffect(() => {
+      const container = scrollRef.current;
+      const content = contentRef.current;
+      if (!container || !content) return;
+      const syncGutter = () => {
+        const gutter = container.offsetWidth - container.clientWidth;
+        container.style.setProperty("--ds-chat-thread-gutter", `${gutter}px`);
+      };
+      const observer = new ResizeObserver(() => {
+        syncGutter();
+        const top = anchorTop.current;
+        const wasClamped = top != null && container.scrollTop < top && container.scrollTop >= container.scrollHeight - container.clientHeight - 1;
+        sizeSpacer();
+        if (top != null && wasClamped) container.scrollTo({ top, behavior: "instant" });
+        updateJump();
+      });
+      observer.observe(container);
+      observer.observe(content);
+      return () => observer.disconnect();
+    }, []);
+    const [scrolling, setScrolling] = useState(false);
+    const settleTimer = useRef(void 0);
+    const [canScrollDown, setCanScrollDown] = useState(false);
+    const updateJump = () => {
+      const container = scrollRef.current;
+      const content = contentRef.current;
+      if (!container || !content) return;
+      const remaining = content.offsetHeight - container.scrollTop - container.clientHeight;
+      const next = remaining > JUMP_THRESHOLD_PX;
+      setCanScrollDown((prev) => prev === next ? prev : next);
+    };
+    const setRef = (node) => {
+      scrollRef.current = node;
+      if (typeof ref === "function") ref(node);
+      else if (ref) ref.current = node;
+    };
+    useLayoutEffect(() => {
+      const container = scrollRef.current;
+      const content = contentRef.current;
+      const spacer = spacerRef.current;
+      if (!container || !content || !spacer) return;
+      const childCount = content.children.length;
+      const previous = prevCount.current;
+      const isFirstRun = !mounted.current;
+      mounted.current = true;
+      if (childCount === previous) return;
+      prevCount.current = childCount;
+      if (childCount < previous) {
+        anchorTop.current = null;
+        spacer.style.height = "0px";
+        container.scrollTo({ top: 0 });
+        return;
+      }
+      if (isFirstRun) {
+        if (childCount > 0 && anchor) {
+          const target2 = Math.max(0, content.offsetHeight - container.clientHeight);
+          anchorTop.current = target2;
+          sizeSpacer();
+          container.scrollTo({ top: target2, behavior: "instant" });
+          updateJump();
+        }
+        return;
+      }
+      if (!anchor) return;
+      const contentStyle = getComputedStyle(content);
+      const paddingTop = parseFloat(contentStyle.paddingTop) || 0;
+      if (previous === 0) {
+        const target2 = content.children[0];
+        if (!target2) return;
+        anchorTop.current = 0;
+        sizeSpacer();
+        const paddingBottom = parseFloat(contentStyle.paddingBottom) || 0;
+        const rise = Math.max(
+          0,
+          container.clientHeight - target2.offsetHeight - paddingTop - paddingBottom
+        );
+        content.style.transition = "none";
+        content.style.transform = `translateY(${rise}px)`;
+        void content.offsetHeight;
+        content.style.transition = "";
+        content.style.transform = "";
+        return;
+      }
+      const target = content.children[previous];
+      if (!target) return;
+      const targetTop = target.offsetTop - paddingTop;
+      anchorTop.current = targetTop;
+      sizeSpacer();
+      container.scrollTo({ top: targetTop });
+    });
+    useEffect(updateJump);
+    const handleScroll = (e) => {
+      onScroll?.(e);
+      updateJump();
+      setScrolling(true);
+      window.clearTimeout(settleTimer.current);
+      settleTimer.current = window.setTimeout(
+        () => setScrolling(false),
+        SCROLLBAR_SETTLE_MS
+      );
+    };
+    const jumpToBottom = () => {
+      const container = scrollRef.current;
+      const content = contentRef.current;
+      if (!container || !content) return;
+      container.scrollTo({ top: content.offsetHeight - container.clientHeight });
+    };
+    useEffect(() => () => window.clearTimeout(settleTimer.current), []);
+    const classes = [baseClass, scrolling ? `${baseClass}--scrolling` : "", className].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ...rest,
+        ref: setRef,
+        className: classes,
+        role: "region",
+        "aria-label": ariaLabel,
+        tabIndex: 0,
+        onScroll: handleScroll,
+        children: [
+          /* @__PURE__ */ jsx("div", { ref: contentRef, className: `${baseClass}__content`, children }),
+          /* @__PURE__ */ jsx("div", { ref: spacerRef, className: `${baseClass}__spacer`, "aria-hidden": "true" }),
+          /* @__PURE__ */ jsx("div", { className: `${baseClass}__jump-slot`, "aria-hidden": !canScrollDown, children: /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              className: `${baseClass}__jump${canScrollDown ? ` ${baseClass}__jump--visible` : ""}`,
+              tabIndex: canScrollDown ? 0 : -1,
+              "aria-label": jumpLabel,
+              onClick: jumpToBottom,
+              children: /* @__PURE__ */ jsx("span", { className: `${baseClass}__jump-icon material-symbols-rounded`, "aria-hidden": "true", children: "arrow_downward" })
+            }
+          ) })
+        ]
+      }
+    );
+  }
+);
+ChatThread.displayName = "ChatThread";
+export {
+  ChatThread
+};

package/components/Chip/Chip.css

@@ -32,6 +32,33 @@
     color var(--motion-duration-base) var(--motion-ease-standard), opacity var(--motion-duration-base) var(--motion-ease-standard);
 }
 
+/* ============================================
+   SIZE — LARGE (40px tall)
+   The default Button's footprint and the body
+   paragraph scale, so a chip used as a primary
+   tap target reads at the same weight as the
+   text around it.
+   ============================================ */
+
+.ds-chip--large {
+  padding: var(--padding-sm) var(--padding-lg); /* 8px 20px */
+  font-family: var(--font-paragraph-em-family);
+  font-size: var(--font-paragraph-em-size);
+  font-weight: var(--font-paragraph-em-weight);
+  line-height: var(--font-paragraph-em-line-height);
+  letter-spacing: var(--font-paragraph-em-letter-spacing);
+}
+
+.ds-chip--large .ds-chip__icon,
+.ds-chip--large .ds-chip__remove .material-symbols-rounded {
+  --icon-size: var(--icon-size-md);
+}
+
+.ds-chip--large .ds-chip__icon svg {
+  width: 24px;
+  height: 24px;
+}
+
 /* ============================================
    SIZE — COMPACT (24px tall)
    ============================================ */

package/components/Chip/Chip.d.ts

@@ -8,8 +8,8 @@ export interface ChipProps {
     selected?: boolean;
     /** Disabled state */
     disabled?: boolean;
-    /** Chip size */
-    size?: 'default' | 'compact';
+    /** Chip size — `large` matches the default Button and paragraph body scale, for pills that are a primary tap target rather than metadata */
+    size?: 'large' | 'default' | 'compact';
     /** Click handler — presence makes the chip an interactive <button> */
     onClick?: () => void;
     /** Remove handler — renders a trailing close button (input-style chips) */

package/components/CircularButton/CircularButton.d.ts

@@ -1,4 +1,6 @@
-export interface CircularButtonProps {
+import { default as React } from 'react';
+/** Props owned by CircularButton itself — everything else falls through to the DOM node. */
+type CircularButtonOwnProps = {
     /** Material Symbol icon name */
     icon: string;
     /** Visual treatment */
@@ -9,7 +11,18 @@ export interface CircularButtonProps {
      * @deprecated Use `variant` instead.
      */
     priority?: 'primary' | 'secondary' | 'tertiary';
-    /** Button state */
+    /** Whether the button is disabled */
+    disabled?: boolean;
+    /**
+     * Documentation-only interaction state.
+     *
+     * @deprecated Use `disabled` for the disabled state.
+     *
+     * Documentation-only affordance for rendering a *static* interaction state in
+     * Storybook and the showcase site. Real hover/active styling comes from CSS
+     * pseudo-classes and needs no prop — for docs, prefer
+     * `className="ds-circular-button--hover"`.
+     */
     state?: 'default' | 'hover' | 'active' | 'disabled';
     /** Button size */
     size?: 'default' | 'compact';
@@ -19,24 +32,26 @@ export interface CircularButtonProps {
      * the disabled state) and sets `aria-busy` on the rendered element.
      */
     loading?: boolean;
-    /** Accessible label */
+    /** Accessible label — required, because the button has no visible text */
     ariaLabel: string;
-    /** Optional click handler */
-    onClick?: () => void;
     /** Optional href — renders as <a> instead of <button> */
     href?: string;
     /** Optional target attribute for links */
     target?: string;
     /** Optional rel attribute for links */
     rel?: string;
-    /** Id of an element describing this button — set automatically by Tooltip */
-    'aria-describedby'?: string;
     /** Additional CSS classes */
     className?: string;
+};
+export interface CircularButtonProps extends CircularButtonOwnProps, Omit<React.ComponentPropsWithoutRef<'button'>, keyof CircularButtonOwnProps | 'type'> {
 }
 /**
  * Circular icon button component.
  * A round button containing a single icon, available in
  * primary, secondary and tertiary variants with default and compact sizes.
+ *
+ * Renders a `<button>`, or an `<a>` when `href` is supplied. Forwards a ref to
+ * whichever element it renders, and spreads unrecognised props onto it.
  */
-export declare const CircularButton: ({ icon, variant, priority, state, size, loading, ariaLabel, onClick, href, target, rel, "aria-describedby": ariaDescribedby, className, }: CircularButtonProps) => import("react").JSX.Element;
+export declare const CircularButton: React.ForwardRefExoticComponent<CircularButtonProps & React.RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;
+export {};

package/components/CircularButton/CircularButton.js

@@ -1,67 +1,69 @@
 import { jsx } from "react/jsx-runtime";
+import React from "react";
 import { Spinner } from "../Spinner/Spinner.js";
 import "./CircularButton.css";
 import "../../fonts/material-symbols.css";
-const CircularButton = ({
-  icon,
-  variant,
-  priority,
-  state = "default",
-  size = "default",
-  loading,
-  ariaLabel,
-  onClick,
-  href,
-  target,
-  rel,
-  "aria-describedby": ariaDescribedby,
-  className = ""
-}) => {
-  const baseClass = "ds-circular-button";
-  const resolvedVariant = variant ?? priority ?? "primary";
-  const variantClass = `${baseClass}--${resolvedVariant}`;
-  const stateClass = `${baseClass}--${state}`;
-  const sizeClass = `${baseClass}--${size}`;
-  const isLoading = Boolean(loading);
-  const classes = [
-    baseClass,
-    variantClass,
-    stateClass,
-    sizeClass,
-    isLoading && `${baseClass}--loading`,
-    className
-  ].filter(Boolean).join(" ");
-  const isDisabled = state === "disabled";
-  const children = isLoading ? /* @__PURE__ */ jsx("span", { className: `${baseClass}__icon`, "aria-hidden": "true", children: /* @__PURE__ */ jsx(Spinner, { size: size === "compact" ? "sm" : "md", variant: "inherit" }) }) : /* @__PURE__ */ jsx("span", { className: `${baseClass}__icon material-symbols-rounded`, "aria-hidden": "true", children: icon });
-  if (href && !isDisabled && !isLoading) {
+const CircularButton = React.forwardRef(
+  ({
+    icon,
+    variant,
+    priority,
+    disabled,
+    state,
+    size = "default",
+    loading,
+    ariaLabel,
+    href,
+    target,
+    rel,
+    className = "",
+    ...rest
+  }, ref) => {
+    const baseClass = "ds-circular-button";
+    const resolvedVariant = variant ?? priority ?? "primary";
+    const isDisabled = disabled ?? state === "disabled";
+    const resolvedState = state ?? (isDisabled ? "disabled" : "default");
+    const isLoading = Boolean(loading);
+    const classes = [
+      baseClass,
+      `${baseClass}--${resolvedVariant}`,
+      `${baseClass}--${resolvedState}`,
+      `${baseClass}--${size}`,
+      isLoading && `${baseClass}--loading`,
+      className
+    ].filter(Boolean).join(" ");
+    const children = isLoading ? /* @__PURE__ */ jsx("span", { className: `${baseClass}__icon`, "aria-hidden": "true", children: /* @__PURE__ */ jsx(Spinner, { size: size === "compact" ? "sm" : "md", variant: "inherit" }) }) : /* @__PURE__ */ jsx("span", { className: `${baseClass}__icon material-symbols-rounded`, "aria-hidden": "true", children: icon });
+    if (href && !isDisabled && !isLoading) {
+      return /* @__PURE__ */ jsx(
+        "a",
+        {
+          ...rest,
+          ref,
+          className: classes,
+          href,
+          target,
+          rel,
+          "aria-label": ariaLabel,
+          children
+        }
+      );
+    }
     return /* @__PURE__ */ jsx(
-      "a",
+      "button",
       {
+        ...rest,
+        ref,
+        type: "button",
         className: classes,
-        href,
-        target,
-        rel,
-        onClick,
+        disabled: isDisabled || isLoading,
+        "aria-busy": isLoading || void 0,
         "aria-label": ariaLabel,
-        "aria-describedby": ariaDescribedby,
         children
       }
     );
   }
-  return /* @__PURE__ */ jsx(
-    "button",
-    {
-      type: "button",
-      className: classes,
-      onClick,
-      disabled: isDisabled || isLoading,
-      "aria-busy": isLoading || void 0,
-      "aria-label": ariaLabel,
-      "aria-describedby": ariaDescribedby,
-      children
-    }
-  );
-};
+);
+CircularButton.displayName = "CircularButton";
 export {
   CircularButton
 };

package/components/CodeBlock/CodeBlock.css

@@ -80,7 +80,7 @@
 }
 
 .ds-code-block__filename {
-  font-family: ui-monospace, 'SF Mono', SFMono-Regular, Menlo, Consolas, monospace;
+  font-family: var(--font-family-code);
   font-size: var(--font-paragraph-sm-size);
   line-height: var(--font-paragraph-sm-line-height);
   color: var(--color-text-secondary);
@@ -172,7 +172,7 @@
 }
 
 .ds-code-block__code {
-  font-family: ui-monospace, 'SF Mono', SFMono-Regular, Menlo, Consolas, monospace;
+  font-family: var(--font-family-code);
   font-size: var(--font-paragraph-sm-size);
   line-height: var(--font-paragraph-sm-line-height);
   color: var(--color-text-primary);