rift-ds 1.5.0 → 1.7.0

package/components/PromptSuggestions/PromptSuggestions.css

@@ -77,6 +77,224 @@
   align-items: flex-start;
 }
 
+/* ============================================
+   TILES and CARDS — blocks for a home screen
+   Where the chip layouts are a line of prompts,
+   these are a row of places to start: an even
+   grid that folds as the row's own width narrows,
+   so a docked panel folds while a full-width page
+   does not.
+   ============================================ */
+
+/* The column floor is stated on the icon scale, the one size both blocks
+   are drawn from: a tile is never narrower than three cover icons, a card
+   than four. Four tiles or three cards sit in one row on a conversation
+   column and fold to two columns and one on a phone, with no breakpoint. */
+.ds-prompt-suggestions--tiles,
+.ds-prompt-suggestions--cards {
+  display: grid;
+}
+
+.ds-prompt-suggestions--tiles {
+  grid-template-columns: repeat(auto-fit, minmax(calc(var(--icon-size-1200) * 3), 1fr));
+}
+
+.ds-prompt-suggestions--cards {
+  grid-template-columns: repeat(auto-fit, minmax(calc(var(--icon-size-1200) * 4), 1fr));
+}
+
+.ds-prompt-suggestions--tiles .ds-prompt-suggestions__item,
+.ds-prompt-suggestions--cards .ds-prompt-suggestions__item {
+  flex-shrink: 1;
+  min-width: 0;
+}
+
+/* One surface for both blocks: a hairline round a container that lets the
+   page through, blurred so text stays on a calm field over an ambient
+   background. The navigation-tile radius, per the radius scale. */
+.ds-prompt-suggestions__tile,
+.ds-prompt-suggestions__card {
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  width: 100%;
+  min-width: 0;
+  margin: 0;
+  border: var(--border-025) solid var(--color-bg-container-border);
+  border-radius: var(--radius-600);
+  background-color: var(--color-bg-container-primary-semi);
+  -webkit-backdrop-filter: blur(24px);
+  backdrop-filter: blur(24px);
+  color: inherit;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+/* A tile answers the pointer quietly, in place: the fill firms up to the
+   solid container and the hairline steps up to the tertiary text ink, so
+   the block reads as picked out without moving. */
+.ds-prompt-suggestions__tile {
+  transition:
+    background-color var(--motion-duration-fast) var(--motion-ease-standard),
+    border-color var(--motion-duration-fast) var(--motion-ease-standard);
+}
+
+.ds-prompt-suggestions__tile:hover {
+  background-color: var(--color-bg-container-primary);
+  border-color: var(--color-text-tertiary);
+}
+
+/* A card lifts: the Card component's own hover, the same rise and the same
+   sanctioned shadow, so a prompt card and a navigation tile answer the
+   pointer the same way. */
+.ds-prompt-suggestions__card {
+  transition:
+    transform var(--motion-duration-slow) var(--motion-ease-standard),
+    box-shadow var(--motion-duration-slow) var(--motion-ease-standard);
+  /* ds-allow(color): transparent resting state of the sanctioned Card
+     hover-lift shadow (see design.md — Do's and Don'ts). */
+  box-shadow: 0 0 0 rgba(0, 0, 0, 0);
+}
+
+.ds-prompt-suggestions__card:hover {
+  transform: translateY(-4px);
+  /* ds-allow(color): the sanctioned Card hover-lift shadow, restated so the
+     two tiles lift alike (see design.md — Do's and Don'ts). */
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.3);
+}
+
+/* The pending shells are not targets, so they neither lift nor light. */
+.ds-prompt-suggestions__tile--pending:hover {
+  background-color: var(--color-bg-container-primary-semi);
+  border-color: var(--color-bg-container-border);
+}
+
+.ds-prompt-suggestions__card--pending:hover {
+  transform: none;
+  box-shadow: none;
+}
+
+.ds-prompt-suggestions__tile:focus-visible,
+.ds-prompt-suggestions__card:focus-visible {
+  outline: 2px solid var(--color-action-primary-bg);
+  outline-offset: 2px;
+}
+
+.ds-prompt-suggestions__tile {
+  gap: var(--gap-300);
+  padding: var(--padding-400);
+}
+
+.ds-prompt-suggestions__card {
+  gap: var(--gap-200);
+  padding: var(--padding-200) var(--padding-200) var(--padding-400);
+}
+
+.ds-prompt-suggestions__text {
+  display: flex;
+  flex-direction: column;
+  gap: var(--gap-050);
+  min-width: 0;
+}
+
+.ds-prompt-suggestions__card .ds-prompt-suggestions__text {
+  padding-inline: var(--padding-200);
+}
+
+.ds-prompt-suggestions__label {
+  font-family: var(--font-paragraph-sm-emphasis-family);
+  font-size: var(--font-paragraph-sm-emphasis-size);
+  font-weight: var(--font-paragraph-sm-emphasis-weight);
+  line-height: var(--font-paragraph-sm-emphasis-line-height);
+  letter-spacing: var(--font-paragraph-sm-emphasis-letter-spacing);
+  color: var(--color-text-primary);
+}
+
+.ds-prompt-suggestions__description {
+  font-family: var(--font-caption-family);
+  font-size: var(--font-caption-size);
+  font-weight: var(--font-caption-weight);
+  line-height: var(--font-caption-line-height);
+  letter-spacing: var(--font-caption-letter-spacing);
+  color: var(--color-text-tertiary);
+}
+
+.ds-prompt-suggestions__icon {
+  display: inline-flex;
+  --icon-size: var(--icon-size-600);
+  color: var(--color-icon-secondary);
+}
+
+/* The card's cover: a wash of one pixel ink, strong at the top and nearly
+   gone by the floor, with the subject's icon standing in it in the same
+   ink. The inks cycle by position, so a row of cards is told apart by
+   colour as well as by title, and they are the theme-split set, so the icon
+   holds its contrast in both modes. */
+.ds-prompt-suggestions__cover {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  /* Twice the cover icon's own size: the icon scale sets the proportion. */
+  height: calc(var(--icon-size-1200) * 2);
+  border-radius: var(--radius-400);
+  background-image: linear-gradient(
+    to bottom,
+    color-mix(in srgb, var(--ds-prompt-suggestions-tint) 24%, transparent),
+    color-mix(in srgb, var(--ds-prompt-suggestions-tint) 6%, transparent)
+  );
+}
+
+.ds-prompt-suggestions__cover .ds-prompt-suggestions__icon {
+  --icon-size: var(--icon-size-1200);
+  color: var(--ds-prompt-suggestions-tint);
+}
+
+.ds-prompt-suggestions__item:nth-child(6n + 1) { --ds-prompt-suggestions-tint: var(--color-pixel-ink-4); }
+.ds-prompt-suggestions__item:nth-child(6n + 2) { --ds-prompt-suggestions-tint: var(--color-pixel-ink-1); }
+.ds-prompt-suggestions__item:nth-child(6n + 3) { --ds-prompt-suggestions-tint: var(--color-pixel-ink-2); }
+.ds-prompt-suggestions__item:nth-child(6n + 4) { --ds-prompt-suggestions-tint: var(--color-pixel-ink-5); }
+.ds-prompt-suggestions__item:nth-child(6n + 5) { --ds-prompt-suggestions-tint: var(--color-pixel-ink-6); }
+.ds-prompt-suggestions__item:nth-child(6n) { --ds-prompt-suggestions-tint: var(--color-pixel-ink-3); }
+
+/* Pending blocks: the real shell holding the label's bar, so the row keeps
+   its height when the suggestions land. */
+.ds-prompt-suggestions__tile--pending,
+.ds-prompt-suggestions__card--pending {
+  cursor: default;
+  font-size: var(--font-paragraph-sm-emphasis-size);
+}
+
+.ds-prompt-suggestions__tile--pending {
+  justify-content: flex-end;
+  min-height: calc(
+    var(--icon-size-600) + var(--gap-300) + var(--font-paragraph-sm-emphasis-line-height) +
+      var(--font-caption-line-height) + 2 * var(--padding-400)
+  );
+}
+
+/* A pending card stands as tall as the loaded one it holds room for: the
+   cover, the label line, and two lines of description (the longest a card's
+   question runs at this width), so the row does not grow when they land. */
+.ds-prompt-suggestions__card--pending {
+  min-height: calc(
+    var(--icon-size-1200) * 2 + var(--gap-200) + var(--font-paragraph-sm-emphasis-line-height) +
+      var(--gap-050) + 2 * var(--font-caption-line-height) + var(--padding-200) +
+      var(--padding-400) + 2 * var(--border-025)
+  );
+}
+
+.ds-prompt-suggestions__card--pending .ds-prompt-suggestions__skeleton-bar {
+  margin: var(--padding-150) var(--padding-200);
+  width: auto;
+}
+
+/* The chosen block takes the same press-and-spring the chips do. */
+.ds-prompt-suggestions__item--chosen .ds-prompt-suggestions__tile,
+.ds-prompt-suggestions__item--chosen .ds-prompt-suggestions__card {
+  animation: ds-prompt-suggestions-choose var(--motion-duration-slow) var(--motion-ease-spring);
+}
+
 /* ============================================
    ITEMS
    ============================================ */

package/components/PromptSuggestions/PromptSuggestions.d.ts

@@ -5,8 +5,10 @@ export interface PromptSuggestion {
     id: string;
     /** The suggestion text shown in the chip. */
     label: string;
-    /** Optional leading icon — Material Symbol name (string) or custom element (ReactNode). */
+    /** Optional leading icon — Material Symbol name (string) or custom element (ReactNode). In the `cards` layout it stands in the card's cover. */
     icon?: string | React.ReactNode;
+    /** A quiet second line under the label, drawn by the `tiles` and `cards` layouts: what the tile leads to, or the full question a card asks. The chip layouts have no room for it and leave it out. */
+    description?: string;
 }
 /** Props owned by PromptSuggestions itself — everything else falls through to the root element. */
 type PromptSuggestionsOwnProps = {
@@ -19,9 +21,14 @@ type PromptSuggestionsOwnProps = {
      * sideways behind edge fades. `wrap` runs them across as many lines as
      * they need, for empty-state hero placements. `stack` gives each one its
      * own line, for narrow columns where a wrapped row breaks unevenly and
-     * the ragged right edge reads as an accident.
+     * the ragged right edge reads as an accident. `tiles` and `cards` leave
+     * the chip behind for an empty-state home screen: `tiles` is an even row
+     * of quiet blocks, each an icon over a label and its `description`;
+     * `cards` gives each suggestion a tinted cover holding its icon, with the
+     * label and description beneath. Both fold to fewer columns as their own
+     * width narrows.
      */
-    layout?: 'scroll' | 'wrap' | 'stack';
+    layout?: 'scroll' | 'wrap' | 'stack' | 'tiles' | 'cards';
     /**
      * Legacy alias for `layout="wrap"`; ignored when `layout` is set.
      * @deprecated Use `layout` instead, which also covers `stack`.

package/components/PromptSuggestions/PromptSuggestions.js

@@ -1,9 +1,10 @@
 "use client";
-import { jsx } from "react/jsx-runtime";
+import { jsx, jsxs } from "react/jsx-runtime";
 import React from "react";
 import { Chip } from "../Chip/Chip.js";
 import { MOTION_EXIT_SYNC_MS } from "../../tokens/motion.js";
 import "./PromptSuggestions.css";
+import "../../fonts/material-symbols.css";
 const PromptSuggestions = React.forwardRef(
   ({
     suggestions,
@@ -37,6 +38,8 @@ const PromptSuggestions = React.forwardRef(
     };
     const arrangement = layout ?? (wrap ? "wrap" : "scroll");
     const chipSize = size === "compact" ? "default" : "large";
+    const block = arrangement === "tiles" ? "tile" : arrangement === "cards" ? "card" : null;
+    const renderIcon = (icon) => typeof icon === "string" ? /* @__PURE__ */ jsx("span", { className: `${baseClass}__icon material-symbols-rounded`, "aria-hidden": "true", children: icon }) : /* @__PURE__ */ jsx("span", { className: `${baseClass}__icon`, "aria-hidden": "true", children: icon });
     const classes = [
       baseClass,
       `${baseClass}--${size}`,
@@ -55,7 +58,13 @@ const PromptSuggestions = React.forwardRef(
         "aria-label": ariaLabel,
         "aria-busy": pending || void 0,
         "data-pending": pending || void 0,
-        children: pending ? Array.from({ length: pendingCount }, (_, index) => /* @__PURE__ */ jsx("div", { "aria-hidden": "true", className: `${baseClass}__item`, children: /* @__PURE__ */ jsx("span", { className: `${baseClass}__skeleton`, children: /* @__PURE__ */ jsx("span", { className: `${baseClass}__skeleton-bar` }) }) }, index)) : suggestions.map((suggestion) => /* @__PURE__ */ jsx(
+        children: pending ? Array.from({ length: pendingCount }, (_, index) => /* @__PURE__ */ jsx("div", { "aria-hidden": "true", className: `${baseClass}__item`, children: block ? (
+          /* The block's own shell, holding the label's bar. */
+          /* @__PURE__ */ jsxs("span", { className: `${baseClass}__${block} ${baseClass}__${block}--pending`, children: [
+            block === "card" && /* @__PURE__ */ jsx("span", { className: `${baseClass}__cover` }),
+            /* @__PURE__ */ jsx("span", { className: `${baseClass}__skeleton-bar` })
+          ] })
+        ) : /* @__PURE__ */ jsx("span", { className: `${baseClass}__skeleton`, children: /* @__PURE__ */ jsx("span", { className: `${baseClass}__skeleton-bar` }) }) }, index)) : suggestions.map((suggestion) => /* @__PURE__ */ jsx(
           "div",
           {
             role: "listitem",
@@ -65,7 +74,21 @@ const PromptSuggestions = React.forwardRef(
                 setChosenId(null);
               }
             },
-            children: /* @__PURE__ */ jsx(
+            children: block ? /* @__PURE__ */ jsxs(
+              "button",
+              {
+                type: "button",
+                className: `${baseClass}__${block}`,
+                onClick: () => choose(suggestion.id),
+                children: [
+                  block === "card" ? /* @__PURE__ */ jsx("span", { className: `${baseClass}__cover`, children: suggestion.icon != null && renderIcon(suggestion.icon) }) : suggestion.icon != null && renderIcon(suggestion.icon),
+                  /* @__PURE__ */ jsxs("span", { className: `${baseClass}__text`, children: [
+                    /* @__PURE__ */ jsx("span", { className: `${baseClass}__label`, children: suggestion.label }),
+                    suggestion.description && /* @__PURE__ */ jsx("span", { className: `${baseClass}__description`, children: suggestion.description })
+                  ] })
+                ]
+              }
+            ) : /* @__PURE__ */ jsx(
               Chip,
               {
                 label: suggestion.label,

package/components/ShaderField/ShaderField.d.ts

@@ -1,8 +1,5 @@
 import { default as React } from 'react';
 import { ShaderBlob, ShaderParams } from './useShaderField';
-export type { ShaderBlob, ShaderParams, ShaderFieldParams, ShaderFieldState, } from './useShaderField';
-export { useShaderField, DEFAULT_SHADER_BLOBS, DEFAULT_SHADER_PARAMS } from './useShaderField';
-export { BLOB_COUNT } from './field.glsl';
 /**
  * How the renderer has resolved.
  *
@@ -66,3 +63,6 @@ export interface ShaderFieldProps extends ShaderFieldOwnProps, Omit<React.Compon
  * the clipping and any mask.
  */
 export declare const ShaderField: React.ForwardRefExoticComponent<ShaderFieldProps & React.RefAttributes<HTMLCanvasElement>>;
+export type { ShaderBlob, ShaderParams, ShaderFieldParams, ShaderFieldState, } from './useShaderField';
+export { useShaderField, DEFAULT_SHADER_BLOBS, DEFAULT_SHADER_PARAMS } from './useShaderField';
+export { BLOB_COUNT } from './field.glsl';

package/components/SourceChip/SourceChip.css

@@ -9,10 +9,14 @@
   /* Layout */
   display: inline-flex;
   align-items: center;
-  gap: var(--gap-100); /* 4px */
+  gap: var(--gap-200); /* 8px */
 
-  /* Spacing */
-  padding: var(--padding-050) var(--padding-200); /* 2px 8px */
+  /* Spacing — the leading slot is tucked into the pill's start: the same
+     inset above, below and before it, so its circle is concentric with the
+     pill's end cap. */
+  --ds-source-chip-inset: var(--padding-100); /* 4px */
+  padding: var(--ds-source-chip-inset);
+  padding-inline-end: var(--padding-300); /* 12px */
 
   /* Shape — borderless pill on the secondary container */
   border-radius: var(--radius-pill);
@@ -45,8 +49,14 @@
   flex-shrink: 0;
   min-width: var(--icon-size-500);
   height: var(--icon-size-500);
-  border-radius: var(--radius-pill);
-  background-color: var(--color-bg-container-tertiary);
+  /* Concentric with the pill: its radius less the inset between them. A
+     squared theme squares the badge with it. */
+  border-radius: calc(var(--radius-pill) - var(--ds-source-chip-inset));
+  /* A solid inverse disc, so the numeral carries the weight a logo's
+     full-colour disc does: dark on light in dark mode, light on dark in
+     light mode. It holds through hover and press — the pill's wash moves
+     behind it. */
+  background-color: var(--color-bg-container-inverse);
 
   font-family: var(--font-paragraph-sm-emphasis-family);
   font-size: var(--font-paragraph-sm-emphasis-size);
@@ -54,7 +64,17 @@
   letter-spacing: var(--font-paragraph-sm-emphasis-letter-spacing);
   line-height: 1;
   font-variant-numeric: tabular-nums;
-  color: var(--color-text-tertiary);
+  color: var(--color-text-on-inverse);
+}
+
+/* Centre the digit, not its line box. A line box reserves room for
+   descenders a lining figure never uses, so centring the box sets the
+   numeral visibly high in a 20px disc. Trimming the box to cap height and
+   baseline leaves only the glyph for the disc to centre. Browsers without
+   text-box keep the line-box centring. */
+.ds-source-chip__numeral {
+  display: block;
+  text-box: trim-both cap alphabetic;
 }
 
 /* ============================================
@@ -62,12 +82,45 @@
    ============================================ */
 
 .ds-source-chip__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
   flex-shrink: 0;
+  width: var(--icon-size-500);
+  height: var(--icon-size-500);
   --icon-size: var(--icon-size-500);
   line-height: 1;
   color: var(--color-icon-primary);
 }
 
+/* ============================================
+   LOGO (leading, when no index; and the
+   preview's top line). The source's mark,
+   cropped to the badge's shape. An image
+   fills the box; a custom element is
+   stretched to it. The tertiary ground shows
+   through a transparent favicon, so it still
+   reads as a badge.
+   ============================================ */
+
+.ds-source-chip__logo {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: var(--icon-size-500);
+  height: var(--icon-size-500);
+  border-radius: calc(var(--radius-pill) - var(--ds-source-chip-inset));
+  background-color: var(--color-bg-container-tertiary);
+  overflow: hidden;
+}
+
+.ds-source-chip__logo > * {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
 /* ============================================
    TITLE — truncates with an ellipsis
    ============================================ */
@@ -80,15 +133,31 @@
 }
 
 /* ============================================
-   LINK (rendered as <a>)
+   INTERACTIVE (rendered as <a> or <button>)
+   The passive wash, as on Chip: one step on
+   hover, one more while pressed. A chip whose
+   preview is showing holds the hover step.
    ============================================ */
 
-.ds-source-chip--link {
+.ds-source-chip--interactive {
   cursor: pointer;
 }
 
-.ds-source-chip--link:hover {
-  background-color: var(--color-bg-container-tertiary);
+/* The <button> form: clear the UA chrome the anchor never had. */
+button.ds-source-chip {
+  border: 0;
+  margin: 0;
+  appearance: none;
+}
+
+.ds-source-chip--interactive:hover,
+.ds-source-chip--open {
+  background-color: var(--color-action-passive-bg-hover);
+  color: var(--color-text-primary);
+}
+
+.ds-source-chip--interactive:active {
+  background-color: var(--color-action-passive-bg-active);
   color: var(--color-text-primary);
 }
 
@@ -96,11 +165,142 @@
    FOCUS
    ============================================ */
 
-.ds-source-chip--link:focus-visible {
+.ds-source-chip--interactive:focus-visible {
   outline: 2px solid var(--color-action-primary-bg);
   outline-offset: 2px;
 }
 
+/* ============================================
+   PREVIEW
+   The source behind the chip, on the floating
+   surface (see HoverCard). The host is the
+   positioning box; the panel opens above the
+   chip, flush with its leading edge. The
+   component flips it below (data-side) and
+   slides it sideways (--ds-source-chip-shift)
+   when the space runs out.
+   ============================================ */
+
+.ds-source-chip-host {
+  position: relative;
+  display: inline-flex;
+  min-width: 0;
+}
+
+.ds-source-chip__preview {
+  position: absolute;
+  z-index: 50;
+  bottom: 100%;
+  left: var(--ds-source-chip-shift, 0px);
+  margin-block: var(--gap-200);
+  width: max-content;
+  max-width: min(320px, calc(100vw - var(--padding-400)));
+  padding: var(--padding-300) var(--padding-400);
+  flex-direction: column;
+  gap: var(--gap-100);
+
+  border-radius: var(--radius-300);
+  background-color: var(--color-bg-page-primary);
+  border: var(--border-025) solid var(--color-bg-container-border);
+  box-shadow: var(--shadow-floating);
+
+  font-family: var(--font-paragraph-sm-family);
+  font-size: var(--font-paragraph-sm-size);
+  font-weight: var(--font-paragraph-sm-weight);
+  line-height: var(--font-paragraph-sm-line-height);
+  letter-spacing: var(--font-paragraph-sm-letter-spacing);
+  color: var(--color-text-secondary);
+  text-align: start;
+  white-space: normal;
+  cursor: default;
+
+  /* display:none keeps the closed panel out of the tab order and the page's
+     scrollable overflow; the flip transitions discretely so the fade
+     survives (see HoverCard, which owns the explanation). */
+  display: none;
+  opacity: 0;
+  transform: translateY(4px);
+  transition-property: opacity, transform, display;
+  transition-duration: var(--motion-duration-fast);
+  transition-timing-function: var(--motion-ease-standard);
+  transition-behavior: allow-discrete;
+}
+
+.ds-source-chip__preview[data-side='bottom'] {
+  top: 100%;
+  bottom: auto;
+  transform: translateY(-4px);
+}
+
+.ds-source-chip__preview--visible,
+.ds-source-chip__preview--visible[data-side='bottom'] {
+  display: flex;
+  opacity: 1;
+  transform: translateY(0);
+}
+
+@starting-style {
+  .ds-source-chip__preview--visible {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+
+  .ds-source-chip__preview--visible[data-side='bottom'] {
+    opacity: 0;
+    transform: translateY(-4px);
+  }
+}
+
+/* Top line: where the source lives, a trailing fact, and the outbound
+   arrow when the chip is a link. */
+.ds-source-chip__preview-top {
+  display: flex;
+  align-items: center;
+  gap: var(--gap-200);
+  color: var(--color-text-tertiary);
+}
+
+.ds-source-chip__preview-source {
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.ds-source-chip__preview-meta {
+  flex-shrink: 0;
+}
+
+/* A middle dot between the two, drawn only when both are present. */
+.ds-source-chip__preview-source + .ds-source-chip__preview-meta::before {
+  content: '\00B7';
+  margin-inline-end: var(--gap-200);
+}
+
+.ds-source-chip__preview-open {
+  flex-shrink: 0;
+  margin-inline-start: auto;
+  --icon-size: var(--icon-size-500);
+}
+
+.ds-source-chip__preview-title {
+  font-family: var(--font-paragraph-sm-emphasis-family);
+  font-size: var(--font-paragraph-sm-emphasis-size);
+  font-weight: var(--font-paragraph-sm-emphasis-weight);
+  line-height: var(--font-paragraph-sm-emphasis-line-height);
+  letter-spacing: var(--font-paragraph-sm-emphasis-letter-spacing);
+  color: var(--color-text-primary);
+}
+
+/* The excerpt is a glance, not the document: four lines, then an ellipsis. */
+.ds-source-chip__preview-excerpt {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 4;
+  line-clamp: 4;
+  overflow: hidden;
+}
+
 /* Icons take the colour of the text around them. Explicit, not just
    inherited by default: a consumer stylesheet that sets a colour on
    .material-symbols-rounded itself (a common global default) would

package/components/SourceChip/SourceChip.d.ts

@@ -3,16 +3,34 @@ import { default as React } from 'react';
 type SourceChipOwnProps = {
     /** The source name, e.g. "Design tokens quarterly". Truncates with an ellipsis when long. */
     title: string;
-    /** Citation number, rendered as a leading numeral in its own small badge circle. */
+    /** Citation number, rendered as a leading numeral in its own small badge circle. Wins the leading slot over `logo` and `icon`. */
     index?: number;
     /**
-     * Leading icon — a Material Symbol name (string) or custom element (ReactNode).
-     * The icon and the index share the leading slot: when both are passed, `index` wins
-     * and the icon is not rendered.
+     * The glyph for a source with neither a number nor a logo — a Material Symbol
+     * name (string) or custom element (ReactNode). Defaults to a globe, so the
+     * leading slot is never empty.
      */
     icon?: string | React.ReactNode;
     /** Optional href — renders as an `<a>` instead of a `<span>`. */
     href?: string;
+    /**
+     * The passage the answer drew on. Setting it gives the chip a preview panel
+     * that opens on hover, focus or press: the full title over this excerpt.
+     * Without an `href` the chip then renders as a `<button>`, so the preview
+     * is reachable from the keyboard.
+     */
+    excerpt?: string;
+    /** Where the source lives, shown as the preview's top line, e.g. "docs.acme.com". Only rendered with `excerpt`. */
+    source?: string;
+    /**
+     * The source's logo or favicon — an image URL (string) or a custom element
+     * (ReactNode), cropped to a circle. It fills the chip's leading slot when
+     * there is no `index`, and always leads the preview's top line. Decorative:
+     * the title and `source` text carry the name.
+     */
+    logo?: string | React.ReactNode;
+    /** A short trailing fact for the preview's top line, e.g. "Updated 3 days ago". Only rendered with `excerpt`. */
+    meta?: string;
     /** Additional CSS classes */
     className?: string;
 };
@@ -21,12 +39,17 @@ export interface SourceChipProps extends SourceChipOwnProps, Omit<React.Componen
 /**
  * SourceChip is the numbered citation pill linking a claim to its source.
  * It renders inline after a sentence or in a sources row under an assistant
- * chat message: a leading citation number (or icon) beside a truncating
- * source title.
+ * chat message: a leading slot — the citation number, the source's logo in
+ * a circle, or a globe — beside a truncating source title.
+ *
+ * Renders an `<a>` when `href` is supplied, a `<button>` when it has a preview
+ * but nowhere to link, and a plain `<span>` otherwise. Forwards a ref to
+ * whichever element it renders, and spreads unrecognised props onto it —
+ * `target` and `rel` pass through as native anchor attributes.
  *
- * Renders an `<a>` when `href` is supplied, a plain `<span>` otherwise.
- * Forwards a ref to whichever element it renders, and spreads unrecognised
- * props onto it — `target` and `rel` pass through as native anchor attributes.
+ * With an `excerpt` the chip previews its source: a floating panel that opens
+ * above the chip on hover or focus, flips below when there is no room, and
+ * slides sideways to stay inside whatever clips it. Escape dismisses it.
  */
-export declare const SourceChip: React.ForwardRefExoticComponent<SourceChipProps & React.RefAttributes<HTMLSpanElement | HTMLAnchorElement>>;
+export declare const SourceChip: React.ForwardRefExoticComponent<SourceChipProps & React.RefAttributes<HTMLButtonElement | HTMLSpanElement | HTMLAnchorElement>>;
 export {};