rift-ds 1.0.0

package/components/Stepper/Stepper.d.ts

@@ -0,0 +1,41 @@
+import { default as React } from 'react';
+/** A single step in a Stepper flow. */
+export type StepperStep = {
+    /** Step label shown beside or below the indicator */
+    label: string;
+    /** Optional supporting line rendered under the label */
+    description?: string;
+};
+/** Props owned by Stepper itself — everything else falls through to the `<ol>`. */
+type StepperOwnProps = {
+    /** Ordered list of steps in the flow */
+    steps: StepperStep[];
+    /**
+     * Index of the active step. Steps before it render as complete (check
+     * icon), steps after it as upcoming (step number). Pass `steps.length`
+     * to mark the whole flow complete.
+     */
+    activeStep: number;
+    /**
+     * Callback with the clicked step's index. When provided, completed steps
+     * and the active step become buttons so the reader can revisit an earlier
+     * stage; upcoming steps stay non-interactive either way.
+     */
+    onStepClick?: (index: number) => void;
+    /** Layout direction */
+    orientation?: 'horizontal' | 'vertical';
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface StepperProps extends StepperOwnProps, Omit<React.ComponentPropsWithoutRef<'ol'>, keyof StepperOwnProps> {
+}
+/**
+ * Stepper component — step-by-step progress indicator for wizards and
+ * multi-stage flows. Renders an ordered list of steps with CSS-drawn
+ * connectors: completed steps show a check, the active step carries
+ * `aria-current="step"`, and upcoming steps show their number.
+ *
+ * Forwards a ref to the `<ol>` and spreads unrecognised props onto it.
+ */
+export declare const Stepper: React.ForwardRefExoticComponent<StepperProps & React.RefAttributes<HTMLOListElement>>;
+export {};

package/components/Stepper/Stepper.js

@@ -0,0 +1,61 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import React from "react";
+import "./Stepper.css";
+import "../../fonts/material-symbols.css";
+const Stepper = React.forwardRef(
+  ({
+    steps,
+    activeStep,
+    onStepClick,
+    orientation = "horizontal",
+    className = "",
+    ...rest
+  }, ref) => {
+    const baseClass = "ds-stepper";
+    const classes = [
+      baseClass,
+      orientation === "vertical" && `${baseClass}--vertical`,
+      className
+    ].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsx("ol", { ...rest, ref, className: classes, children: steps.map((step, index) => {
+      const status = index < activeStep ? "complete" : index === activeStep ? "active" : "upcoming";
+      const interactive = Boolean(onStepClick) && status !== "upcoming";
+      const indicator = /* @__PURE__ */ jsx("span", { className: `${baseClass}__indicator`, "aria-hidden": "true", children: status === "complete" ? /* @__PURE__ */ jsx("span", { className: "material-symbols-rounded", children: "check" }) : index + 1 });
+      const text = /* @__PURE__ */ jsxs("span", { className: `${baseClass}__text`, children: [
+        /* @__PURE__ */ jsx("span", { className: `${baseClass}__label`, children: step.label }),
+        step.description && /* @__PURE__ */ jsx("span", { className: `${baseClass}__description`, children: step.description })
+      ] });
+      return /* @__PURE__ */ jsxs(
+        "li",
+        {
+          className: `${baseClass}__step ${baseClass}__step--${status}`,
+          "aria-current": status === "active" ? "step" : void 0,
+          children: [
+            interactive ? /* @__PURE__ */ jsxs(
+              "button",
+              {
+                type: "button",
+                className: `${baseClass}__content`,
+                onClick: () => onStepClick?.(index),
+                children: [
+                  indicator,
+                  text
+                ]
+              }
+            ) : /* @__PURE__ */ jsxs("span", { className: `${baseClass}__content`, children: [
+              indicator,
+              text
+            ] }),
+            index < steps.length - 1 && /* @__PURE__ */ jsx("span", { className: `${baseClass}__connector`, "aria-hidden": "true" })
+          ]
+        },
+        index
+      );
+    }) });
+  }
+);
+Stepper.displayName = "Stepper";
+export {
+  Stepper
+};

package/components/StreamingText/StreamingText.css

@@ -0,0 +1,40 @@
+/* ============================================
+   STREAMING TEXT COMPONENT
+   Progressive reveal for text arriving in
+   chunks, with a blinking cursor. Inherits the
+   surrounding typography — the reveal is not a
+   text style of its own.
+   ============================================ */
+
+/* Base */
+
+.ds-streaming-text {
+  white-space: pre-wrap;
+  overflow-wrap: break-word;
+}
+
+/* Cursor */
+
+.ds-streaming-text__cursor {
+  display: inline-block;
+  width: 0.55em;
+  height: 1em;
+  margin-left: 0.1em;
+  vertical-align: text-bottom;
+  border-radius: var(--radius-050);
+  background-color: currentColor;
+  animation: ds-streaming-text-blink var(--motion-duration-loop-spin) var(--motion-ease-standard)
+    infinite;
+}
+
+@keyframes ds-streaming-text-blink {
+  0%,
+  45% {
+    opacity: 1;
+  }
+
+  55%,
+  100% {
+    opacity: 0.15;
+  }
+}

package/components/StreamingText/StreamingText.d.ts

@@ -0,0 +1,62 @@
+import { default as React } from 'react';
+export type { StreamReveal, StreamRevealOptions, UseStreamRevealOptions, } from './useStreamReveal';
+export { createStreamReveal, useStreamReveal } from './useStreamReveal';
+/** Props owned by StreamingText itself — everything else falls through to the root span. */
+type StreamingTextOwnProps = {
+    /**
+     * The text received so far. Grow it across renders as chunks arrive; the
+     * reveal animates through the appended part. A value that does not extend
+     * the previous one is treated as a new message and reveals from the start.
+     */
+    text: string;
+    /**
+     * Whether the source is still producing text. Keeps the cursor visible
+     * between chunks, when the reveal has caught up but more may arrive.
+     */
+    streaming?: boolean;
+    /**
+     * Slowest the reveal ever runs, in characters per second — the pace a
+     * thin trickle of chunks types at. Defaults to MOTION_STREAM_FLOOR_CPS.
+     */
+    floorCps?: number;
+    /**
+     * However much text is waiting, it is fully on screen within this long,
+     * in milliseconds — the rate rises with the backlog. Defaults to
+     * MOTION_STREAM_DRAIN_MS.
+     */
+    drainMs?: number;
+    /**
+     * The retired interval between reveal steps; when set, its equivalent
+     * rate becomes the reveal's floor.
+     * @deprecated The reveal is frame-driven now — pace it with `floorCps`
+     * and `drainMs` instead.
+     */
+    charIntervalMs?: number;
+    /** Shows the blinking cursor while streaming or revealing. */
+    cursor?: boolean;
+    /**
+     * Fires once when the reveal catches up with `text` after `streaming` has
+     * ended — the moment the message is fully on screen.
+     */
+    onRevealComplete?: () => void;
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface StreamingTextProps extends StreamingTextOwnProps, Omit<React.ComponentPropsWithoutRef<'span'>, keyof StreamingTextOwnProps | 'children'> {
+}
+/**
+ * StreamingText — the reveal for text that arrives in chunks: an LLM
+ * response typing itself out, with a cursor that blinks while more is
+ * coming. Feed it the accumulated text on every render and it animates
+ * through what was appended from a frame loop that spends real elapsed
+ * time: a thin trickle types at the floor rate, and however much lands at
+ * once is on screen within the drain window. Under
+ * `prefers-reduced-motion` the reveal is skipped and each chunk appears
+ * whole. Announcement is the container's job — pair it with an
+ * `aria-live` region when the surrounding UI does not already announce
+ * the message. When the streamed text needs its own renderer (markdown
+ * through a parser), pace it with `useStreamReveal` or
+ * `createStreamReveal` from this folder instead — the same engine without
+ * the span.
+ */
+export declare const StreamingText: React.ForwardRefExoticComponent<StreamingTextProps & React.RefAttributes<HTMLSpanElement>>;

package/components/StreamingText/StreamingText.js

@@ -0,0 +1,49 @@
+"use client";
+import { jsxs, jsx } from "react/jsx-runtime";
+import React, { useRef, useEffect } from "react";
+import { useStreamReveal } from "./useStreamReveal.js";
+import { createStreamReveal } from "./useStreamReveal.js";
+import "./StreamingText.css";
+const StreamingText = React.forwardRef(
+  ({
+    text,
+    streaming = false,
+    floorCps,
+    drainMs,
+    charIntervalMs,
+    cursor = true,
+    onRevealComplete,
+    className = "",
+    ...rest
+  }, ref) => {
+    const baseClass = "ds-streaming-text";
+    const { visible, caughtUp } = useStreamReveal(text, {
+      // The legacy interval's equivalent rate: one character per step.
+      floorCps: charIntervalMs != null ? 1e3 / charIntervalMs : floorCps,
+      drainMs
+    });
+    const completed = useRef(false);
+    useEffect(() => {
+      if (!caughtUp) {
+        completed.current = false;
+        return;
+      }
+      if (!streaming && text.length > 0 && !completed.current) {
+        completed.current = true;
+        onRevealComplete?.();
+      }
+    }, [caughtUp, streaming, text, onRevealComplete]);
+    const showCursor = cursor && (streaming || !caughtUp);
+    const classes = [baseClass, className].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsxs("span", { ...rest, ref, className: classes, children: [
+      visible,
+      showCursor && /* @__PURE__ */ jsx("span", { className: `${baseClass}__cursor`, "aria-hidden": "true" })
+    ] });
+  }
+);
+StreamingText.displayName = "StreamingText";
+export {
+  StreamingText,
+  createStreamReveal,
+  useStreamReveal
+};

package/components/StreamingText/useStreamReveal.d.ts

@@ -0,0 +1,70 @@
+export interface StreamRevealOptions {
+    /** Receives the visible slice each time the reveal moves it. */
+    onUpdate: (visible: string) => void;
+    /**
+     * Slowest the reveal ever runs, in characters per second. Defaults to
+     * MOTION_STREAM_FLOOR_CPS.
+     */
+    floorCps?: number;
+    /**
+     * However much text is waiting, it is fully on screen within this long,
+     * in milliseconds. Defaults to MOTION_STREAM_DRAIN_MS.
+     */
+    drainMs?: number;
+    /**
+     * Whether appended text is paced at all. Pass false (or a function
+     * returning false — it is read on every append) to show each chunk
+     * whole: the reduced-motion path.
+     */
+    paced?: boolean | (() => boolean);
+}
+export interface StreamReveal {
+    /** Text the source produced since the last call — paced onto the screen. */
+    append: (chunk: string) => void;
+    /** Everything that has arrived, on screen now — for stops and aborts. */
+    flush: () => void;
+    /**
+     * Replace what has arrived wholesale and show it immediately, unpaced —
+     * for text that is not the stream speaking (a notice, an error), or to
+     * seed text that should not animate.
+     */
+    showWhole: (text: string) => void;
+    /** Drop everything and reveal `text` as a new message, from zero. */
+    restart: (text: string) => void;
+    /**
+     * Resolves once the reveal has caught up with everything that arrived —
+     * immediately when it already has.
+     */
+    drained: () => Promise<void>;
+    /** Stop the frame loop. Nothing more is revealed until the next append. */
+    cancel: () => void;
+}
+/**
+ * Create a reveal for one streamed message. The caller owns rendering:
+ * `onUpdate` fires with the visible slice, at most once per frame.
+ */
+export declare function createStreamReveal(options: StreamRevealOptions): StreamReveal;
+export interface UseStreamRevealOptions {
+    /**
+     * Slowest the reveal ever runs, in characters per second. Defaults to
+     * MOTION_STREAM_FLOOR_CPS.
+     */
+    floorCps?: number;
+    /**
+     * However much text is waiting, it is fully on screen within this long,
+     * in milliseconds. Defaults to MOTION_STREAM_DRAIN_MS.
+     */
+    drainMs?: number;
+}
+/**
+ * The declarative face of the engine, for React surfaces: feed it the
+ * accumulated text on every render and read back the paced slice. Text
+ * present on mount shows whole; a value that does not extend the previous
+ * one is a new message and reveals from zero. Checks
+ * `prefers-reduced-motion` itself, since no CSS guard can see a frame
+ * loop, and shows each chunk whole under it.
+ */
+export declare function useStreamReveal(text: string, { floorCps, drainMs }?: UseStreamRevealOptions): {
+    visible: string;
+    caughtUp: boolean;
+};

package/components/StreamingText/useStreamReveal.js

@@ -0,0 +1,121 @@
+"use client";
+import { useState, useRef, useEffect } from "react";
+import { MOTION_STREAM_FLOOR_CPS, MOTION_STREAM_DRAIN_MS } from "../../tokens/motion.js";
+function createStreamReveal(options) {
+  let arrived = "";
+  let revealed = 0;
+  let rafId = null;
+  let lastFrame = 0;
+  let resolvers = [];
+  const isPaced = () => {
+    const paced = options.paced;
+    return typeof paced === "function" ? paced() : paced !== false;
+  };
+  const settle = () => {
+    const pending = resolvers;
+    resolvers = [];
+    for (const resolve of pending) resolve();
+  };
+  const cancel = () => {
+    if (rafId != null) cancelAnimationFrame(rafId);
+    rafId = null;
+    lastFrame = 0;
+  };
+  const schedule = () => {
+    if (rafId == null) rafId = requestAnimationFrame(frame);
+  };
+  function frame(now) {
+    rafId = null;
+    const seconds = lastFrame === 0 ? 0 : (now - lastFrame) / 1e3;
+    lastFrame = now;
+    const backlog = arrived.length - revealed;
+    if (backlog > 0 && seconds > 0) {
+      const floorCps = options.floorCps ?? MOTION_STREAM_FLOOR_CPS;
+      const drainMs = options.drainMs ?? MOTION_STREAM_DRAIN_MS;
+      const cps = Math.max(floorCps, backlog / (drainMs / 1e3));
+      revealed = Math.min(arrived.length, revealed + Math.max(1, Math.round(cps * seconds)));
+      options.onUpdate(arrived.slice(0, revealed));
+    }
+    if (revealed < arrived.length) schedule();
+    else {
+      lastFrame = 0;
+      settle();
+    }
+  }
+  const flush = () => {
+    cancel();
+    if (revealed < arrived.length) {
+      revealed = arrived.length;
+      options.onUpdate(arrived);
+    }
+    settle();
+  };
+  return {
+    append: (chunk) => {
+      if (chunk === "") return;
+      arrived += chunk;
+      if (isPaced()) schedule();
+      else flush();
+    },
+    flush,
+    showWhole: (text) => {
+      cancel();
+      arrived = text;
+      revealed = text.length;
+      options.onUpdate(text);
+      settle();
+    },
+    restart: (text) => {
+      cancel();
+      arrived = text;
+      revealed = 0;
+      options.onUpdate("");
+      if (arrived === "") return;
+      if (isPaced()) schedule();
+      else flush();
+    },
+    drained: () => revealed >= arrived.length ? Promise.resolve() : new Promise((resolve) => {
+      resolvers.push(resolve);
+      schedule();
+    }),
+    cancel
+  };
+}
+function useStreamReveal(text, { floorCps, drainMs } = {}) {
+  const [revealedText, setRevealedText] = useState(text);
+  const engineRef = useRef(null);
+  const floorCpsRef = useRef(floorCps);
+  const drainMsRef = useRef(drainMs);
+  const previous = useRef(text);
+  useEffect(() => () => engineRef.current?.cancel(), []);
+  useEffect(() => {
+    floorCpsRef.current = floorCps;
+    drainMsRef.current = drainMs;
+  }, [floorCps, drainMs]);
+  useEffect(() => {
+    if (engineRef.current === null) {
+      engineRef.current = createStreamReveal({
+        onUpdate: setRevealedText,
+        paced: () => !window.matchMedia("(prefers-reduced-motion: reduce)").matches,
+        get floorCps() {
+          return floorCpsRef.current;
+        },
+        get drainMs() {
+          return drainMsRef.current;
+        }
+      });
+      engineRef.current.showWhole(previous.current);
+    }
+    if (text === previous.current) return;
+    const engine = engineRef.current;
+    if (text.startsWith(previous.current)) engine.append(text.slice(previous.current.length));
+    else engine.restart(text);
+    previous.current = text;
+  }, [text]);
+  const visible = text.startsWith(revealedText) ? revealedText : "";
+  return { visible, caughtUp: visible.length >= text.length };
+}
+export {
+  createStreamReveal,
+  useStreamReveal
+};

package/components/Swatch/Swatch.css

@@ -0,0 +1,52 @@
+/* ============================================
+   SWATCH COMPONENT
+   Clickable colour tile for palettes and pickers
+   ============================================ */
+
+/* Base */
+
+.ds-swatch {
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  border: none;
+  border-radius: var(--radius-pill);
+  background-color: var(--ds-swatch-color);
+  /* A hairline inset keeps very light colours visible on the white floor */
+  box-shadow: inset 0 0 0 var(--border-025) var(--color-bg-container-border);
+  cursor: pointer;
+  flex-shrink: 0;
+  transition: box-shadow var(--motion-duration-base) var(--motion-ease-standard);
+}
+
+/* Sizes */
+
+.ds-swatch--compact {
+  width: 20px;
+  height: 20px;
+}
+
+/* Shapes */
+
+.ds-swatch--square {
+  border-radius: var(--radius-200);
+}
+
+/* States */
+
+.ds-swatch--selected {
+  box-shadow:
+    inset 0 0 0 var(--border-025) var(--color-bg-container-border),
+    0 0 0 var(--border-050) var(--color-bg-page-primary),
+    0 0 0 calc(var(--border-050) * 2) var(--color-text-primary);
+}
+
+.ds-swatch:focus-visible {
+  outline: var(--border-050) solid var(--color-input-border-selected);
+  outline-offset: var(--border-050);
+}
+
+.ds-swatch--disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}

package/components/Swatch/Swatch.d.ts

@@ -0,0 +1,34 @@
+import { default as React } from 'react';
+/** Props owned by Swatch itself — everything else falls through to the <button>. */
+type SwatchOwnProps = {
+    /** The colour this swatch shows — any valid CSS colour, typically a hex value */
+    value: string;
+    /**
+     * Accessible name for the swatch. Defaults to the colour value, which is
+     * meaningful but terse — prefer a human name ("Teal 07") when you have one.
+     */
+    label?: string;
+    /** Selected state — renders the selection ring and sets aria-pressed */
+    selected?: boolean;
+    /** Swatch size */
+    size?: 'default' | 'compact';
+    /** Corner treatment — circle matches the site's preset grids; square suits picker triggers */
+    shape?: 'circle' | 'square';
+    /** Whether the swatch is disabled */
+    disabled?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface SwatchProps extends SwatchOwnProps, Omit<React.ComponentPropsWithoutRef<'button'>, keyof SwatchOwnProps | 'type'> {
+}
+/**
+ * A clickable colour tile — the building block for preset palettes and
+ * picker triggers. Renders a `<button>` whose background is the `value`
+ * colour; `selected` draws the theme-aware selection ring.
+ *
+ * Purely presentational (no hooks), so it can be rendered from a Server
+ * Component; interactivity arrives through the native `onClick` you pass.
+ * Forwards a ref to the `<button>` and spreads unrecognised props onto it.
+ */
+export declare const Swatch: React.ForwardRefExoticComponent<SwatchProps & React.RefAttributes<HTMLButtonElement>>;
+export {};

package/components/Swatch/Swatch.js

@@ -0,0 +1,44 @@
+import { jsx } from "react/jsx-runtime";
+import React from "react";
+import "./Swatch.css";
+const Swatch = React.forwardRef(
+  ({
+    value,
+    label,
+    selected = false,
+    size = "default",
+    shape = "circle",
+    disabled = false,
+    className = "",
+    style,
+    ...rest
+  }, ref) => {
+    const baseClass = "ds-swatch";
+    const classes = [
+      baseClass,
+      size === "compact" ? `${baseClass}--compact` : "",
+      shape === "square" ? `${baseClass}--square` : "",
+      selected ? `${baseClass}--selected` : "",
+      disabled ? `${baseClass}--disabled` : "",
+      className
+    ].filter(Boolean).join(" ");
+    const swatchStyle = { ...style, "--ds-swatch-color": value };
+    return /* @__PURE__ */ jsx(
+      "button",
+      {
+        ...rest,
+        ref,
+        type: "button",
+        className: classes,
+        style: swatchStyle,
+        disabled,
+        "aria-pressed": selected,
+        "aria-label": rest["aria-label"] ?? label ?? value
+      }
+    );
+  }
+);
+Swatch.displayName = "Swatch";
+export {
+  Swatch
+};