@instruments/materia-ui 0.1.0

package/dist/components/stagger/stagger-root.d.ts

@@ -0,0 +1,26 @@
+import * as m from "motion/react-m";
+import type { ComponentProps } from "react";
+export interface StaggerProps extends ComponentProps<typeof m.div> {
+    /** Initial delay before the first child starts animating (seconds). @default 0 */
+    delay?: number;
+    /** Delay between each child item animating in (seconds). @default 0.15 */
+    stagger?: number;
+}
+/**
+ * Orchestrates staggered entrance animations for child `StaggerItem` components.
+ * Uses Motion's `stagger()` for `delayChildren` internally.
+ *
+ * @example
+ * ```tsx
+ * <Stagger stagger={0.15}>
+ *   <StaggerItem animation="fadeScale">...</StaggerItem>
+ *   <StaggerItem>...</StaggerItem>
+ * </Stagger>
+ * ```
+ *
+ * @bestPractice Wrap `StaggerItem` children (not raw elements) - `Stagger` only drives the `hidden`→`visible` variant orchestration; the items own their actual entrance animation.
+ * @bestPractice Tune rhythm with `stagger` (gap between items) and `delay` (lead-in) on the parent, rather than hand-setting per-child transition delays.
+ * @bestPractice Needs `ReducedMotionProvider` in the tree so the orchestrated entrance both runs and honours the reduced-motion setting.
+ * @category motion
+ */
+export declare const Stagger: ({ stagger, delay, className, children, ...props }: StaggerProps) => import("react").JSX.Element;

package/dist/components/stagger/stagger-root.js

@@ -0,0 +1,32 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { stagger as staggerChildren } from "motion/react";
+import * as m from "motion/react-m";
+const containerVariants = {
+    hidden: {},
+    visible: (custom) => ({
+        transition: {
+            delayChildren: staggerChildren(custom.stagger, {
+                startDelay: custom.delay,
+            }),
+        },
+    }),
+};
+/**
+ * Orchestrates staggered entrance animations for child `StaggerItem` components.
+ * Uses Motion's `stagger()` for `delayChildren` internally.
+ *
+ * @example
+ * ```tsx
+ * <Stagger stagger={0.15}>
+ *   <StaggerItem animation="fadeScale">...</StaggerItem>
+ *   <StaggerItem>...</StaggerItem>
+ * </Stagger>
+ * ```
+ *
+ * @bestPractice Wrap `StaggerItem` children (not raw elements) - `Stagger` only drives the `hidden`→`visible` variant orchestration; the items own their actual entrance animation.
+ * @bestPractice Tune rhythm with `stagger` (gap between items) and `delay` (lead-in) on the parent, rather than hand-setting per-child transition delays.
+ * @bestPractice Needs `ReducedMotionProvider` in the tree so the orchestrated entrance both runs and honours the reduced-motion setting.
+ * @category motion
+ */
+export const Stagger = ({ stagger = 0.15, delay = 0, className, children, ...props }) => (_jsx(m.div, { animate: "visible", className: className, custom: { delay, stagger }, initial: "hidden", variants: containerVariants, ...props, children: children }));

package/dist/components/stagger.d.ts

@@ -0,0 +1,2 @@
+export { StaggerItem, type StaggerItemProps } from "./stagger/stagger-item.js";
+export { Stagger, type StaggerProps } from "./stagger/stagger-root.js";

package/dist/components/stagger.js

@@ -0,0 +1,2 @@
+export { StaggerItem } from "./stagger/stagger-item.js";
+export { Stagger } from "./stagger/stagger-root.js";

package/dist/components/stepper/stepper-context.d.ts

@@ -0,0 +1,29 @@
+import type { ResponsiveValue } from "../../tokens/responsive.js";
+import type { ComponentSize } from "../../tokens/size.js";
+/** Supported stepper sizes */
+export type StepperSize = Extract<ComponentSize, "sm" | "base" | "lg">;
+/**
+ * Stepper size - a single {@link StepperSize} or a per-breakpoint object like
+ * `{ base: "sm", md: "lg" }`. Children resolve their single-token needs (icon
+ * size, circle animation) via `resolveResponsiveBase` and layer `md:*`
+ * overrides via `getResponsiveSizeOverrides`.
+ */
+export type ResponsiveStepperSize = ResponsiveValue<StepperSize>;
+/** Context value for stepper state and configuration */
+export interface StepperContextValue {
+    /** Handler for step clicks */
+    onStepClick: (stepValue: number) => void;
+    /** Registers a mounted step so the root can size its progress track; returns the unregister cleanup */
+    registerStep: () => () => void;
+    /** Size variant (single token or per-breakpoint object) */
+    size: ResponsiveStepperSize;
+    /** Current completed step index */
+    value: number;
+}
+/**
+ * StepperContext UI component.
+ * Import from "@instruments/materia-ui/components/stepper".
+ */
+export declare const StepperContext: import("react").Context<StepperContextValue | null>;
+/** Hook to access stepper context */
+export declare const useStepperContext: () => StepperContextValue;

package/dist/components/stepper/stepper-context.js

@@ -0,0 +1,15 @@
+"use client";
+import { createContext, use } from "react";
+/**
+ * StepperContext UI component.
+ * Import from "@instruments/materia-ui/components/stepper".
+ */
+export const StepperContext = createContext(null);
+/** Hook to access stepper context */
+export const useStepperContext = () => {
+    const context = use(StepperContext);
+    if (!context) {
+        throw new Error("Stepper components must be used within a Stepper");
+    }
+    return context;
+};

package/dist/components/stepper/stepper-item.d.ts

@@ -0,0 +1,16 @@
+import type { LucideIcon } from "lucide-react";
+import type * as React from "react";
+export type StepperItemProps = {
+    /** Step index (required, determines order and completion) */
+    value: number;
+    /** Label text below the step (optional) */
+    label?: string;
+    /** Whether this step is disabled */
+    disabled?: boolean;
+    /** Custom icon - defaults to Check */
+    icon?: LucideIcon;
+    /** Additional className */
+    className?: string;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "className">;
+/** Individual step in the stepper */
+export declare const StepperItem: ({ value, label, disabled, icon, className, ...rest }: StepperItemProps) => React.JSX.Element;

package/dist/components/stepper/stepper-item.js

@@ -0,0 +1,64 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { springs } from "@instruments/materia-ui/tokens/motion";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Check } from "lucide-react";
+import * as m from "motion/react-m";
+import { useEffect } from "react";
+import { getResponsiveSizeOverrides, resolveResponsiveBase, } from "../../tokens/responsive.js";
+import { Icon } from "../icon.js";
+import { useStepperContext } from "../stepper/stepper-context.js";
+import { DEFAULT_STEPPER_SIZE, STEPPER_CIRCLE_CONTAINER_SIZE_CLASSES, STEPPER_LABEL_SIZE_CLASSES, stepperCircleContainerVariants, stepperCircleVariants, stepperIconVariants, stepperLabelVariants, } from "../stepper/stepper-variants.js";
+/** Map component size to icon size (two levels smaller than component size) */
+const SIZE_TO_ICON_SIZE = { base: "2xs", lg: "xs", sm: "3xs" };
+/** Circle sizes in pixels for animation, keyed by component size and state */
+const CIRCLE_SIZES = {
+    // size-6, size-9
+    base: { completed: 24, default: 36 },
+    // size-8, size-11
+    lg: { completed: 32, default: 44 },
+    // size-5, size-7
+    sm: { completed: 20, default: 28 },
+};
+/** Individual step in the stepper */
+export const StepperItem = ({ value, label, disabled = false, icon = Check, className, ...rest }) => {
+    const { value: currentValue, size, onStepClick, registerStep, } = useStepperContext();
+    useEffect(() => registerStep(), [registerStep]);
+    // Icon-size Record lookups and the animated circle diameter are single-token,
+    // so they resolve to the base size; responsive `md:*` layout overrides are
+    // layered onto the size-keyed cvas below.
+    const baseSize = resolveResponsiveBase(size, DEFAULT_STEPPER_SIZE);
+    // Derive state from current value
+    const getState = () => {
+        if (disabled) {
+            return "disabled";
+        }
+        if (value < currentValue) {
+            return "completed";
+        }
+        if (value === currentValue) {
+            return "current";
+        }
+        return "upcoming";
+    };
+    const state = getState();
+    const isInteractive = !disabled;
+    const handleClick = () => {
+        if (isInteractive) {
+            onStepClick(value);
+        }
+    };
+    const handleKeyDown = (event) => {
+        if (isInteractive && (event.key === "Enter" || event.key === " ")) {
+            event.preventDefault();
+            onStepClick(value);
+        }
+    };
+    const iconSize = SIZE_TO_ICON_SIZE[baseSize];
+    const circleSize = state === "completed"
+        ? CIRCLE_SIZES[baseSize].completed
+        : CIRCLE_SIZES[baseSize].default;
+    return (_jsxs("div", { className: cn("relative", className), "data-slot": "stepper-item", "data-state": state, ...rest, children: [_jsx("div", { className: cn(stepperCircleContainerVariants({ size: baseSize }), getResponsiveSizeOverrides(size, STEPPER_CIRCLE_CONTAINER_SIZE_CLASSES)), children: _jsx(m.button, { "aria-current": state === "current" ? "step" : undefined, "aria-label": label !== undefined && label !== null && label !== ""
+                        ? `Step: ${label}`
+                        : `Step ${value + 1}`, className: cn(stepperCircleVariants({ size: baseSize, state }), isInteractive && "cursor-pointer", !isInteractive && "cursor-default"), disabled: disabled, layout: true, onClick: handleClick, onKeyDown: handleKeyDown, style: { borderRadius: 9999, height: circleSize, width: circleSize }, transition: springs.standard, type: "button", children: _jsx(m.span, { className: "flex", layout: true, children: _jsx(Icon, { className: stepperIconVariants({ size: baseSize, state }), icon: icon, size: iconSize }) }) }) }), label !== undefined && label !== null && label !== "" && (_jsx("span", { className: cn(stepperLabelVariants({ size: baseSize, state }), getResponsiveSizeOverrides(size, STEPPER_LABEL_SIZE_CLASSES)), children: label }))] }));
+};

package/dist/components/stepper/stepper-root.d.ts

@@ -0,0 +1,31 @@
+import type * as React from "react";
+import type { ResponsiveStepperSize } from "../stepper/stepper-context.js";
+export type StepperProps = {
+    /** Current completed step index (controlled) */
+    value?: number;
+    /**
+     * Initial step index (uncontrolled)
+     * @default 0
+     */
+    defaultValue?: number;
+    /** Callback when step changes */
+    onValueChange?: (value: number) => void;
+    /**
+     * Size variant - a single token or a per-breakpoint object like
+     * `{ base: "sm", md: "lg" }`.
+     * @default "base"
+     */
+    size?: ResponsiveStepperSize;
+    /** Additional className */
+    className?: string;
+    /** StepperItem children */
+    children: React.ReactNode;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "className">;
+/**
+ * Root stepper component that manages step state
+ *
+ * @bestPractice Give each step a `StepperItem` child in order - progress is derived from child index, so conditionally rendering steps shifts the fill.
+ * @bestPractice Control completion via `value`/`onValueChange` (or uncontrolled `defaultValue`); the fill reaches only the last *completed* step, not the current one.
+ * @category navigation
+ */
+export declare const Stepper: ({ value, defaultValue, onValueChange, size, className, children, ...rest }: StepperProps) => React.JSX.Element;

package/dist/components/stepper/stepper-root.js

@@ -0,0 +1,54 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { springs } from "@instruments/materia-ui/tokens/motion";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import * as m from "motion/react-m";
+import { useCallback, useMemo, useState } from "react";
+import { useControllableState } from "../../hooks/use-controllable-state.js";
+import { getResponsiveSizeOverrides, resolveResponsiveBase, } from "../../tokens/responsive.js";
+import { StepperContext } from "../stepper/stepper-context.js";
+import { DEFAULT_STEPPER_SIZE, STEPPER_TRACK_SIZE_CLASSES, stepperRootVariants, stepperTrackVariants, } from "../stepper/stepper-variants.js";
+/**
+ * Root stepper component that manages step state
+ *
+ * @bestPractice Give each step a `StepperItem` child in order - progress is derived from child index, so conditionally rendering steps shifts the fill.
+ * @bestPractice Control completion via `value`/`onValueChange` (or uncontrolled `defaultValue`); the fill reaches only the last *completed* step, not the current one.
+ * @category navigation
+ */
+export const Stepper = ({ value, defaultValue = 0, onValueChange, size = "base", className, children, ...rest }) => {
+    // Single-token base size for the empty-string root cva variant + memo key.
+    const baseSize = resolveResponsiveBase(size, DEFAULT_STEPPER_SIZE);
+    const [currentValue, setValue] = useControllableState({
+        defaultValue,
+        onChange: onValueChange,
+        value,
+    });
+    // Handle step click - toggles step completion
+    // If step is not completed: complete it (value = stepValue + 1)
+    // If step is completed: toggle it off (value = stepValue, making it current)
+    const handleStepClick = useCallback((stepValue) => {
+        const isCompleted = stepValue < currentValue;
+        setValue(isCompleted ? stepValue : stepValue + 1);
+    }, [currentValue, setValue]);
+    // Steps register themselves through context, so the root never inspects children
+    const [totalSteps, setTotalSteps] = useState(0);
+    const registerStep = useCallback(() => {
+        setTotalSteps((count) => count + 1);
+        return () => {
+            setTotalSteps((count) => count - 1);
+        };
+    }, []);
+    // Calculate progress percentage (0 to 100)
+    // Progress only extends to the last COMPLETED step (not the current one)
+    // So if currentValue is 1, step 0 is completed but line doesn't extend to step 1
+    const progressPercent = totalSteps > 1 && currentValue > 0
+        ? ((currentValue - 1) / (totalSteps - 1)) * 100
+        : 0;
+    const contextValue = useMemo(() => ({
+        onStepClick: handleStepClick,
+        registerStep,
+        size,
+        value: currentValue,
+    }), [handleStepClick, registerStep, size, currentValue]);
+    return (_jsx(StepperContext.Provider, { value: contextValue, children: _jsxs("nav", { "aria-label": "Progress steps", className: cn(stepperRootVariants({ size: baseSize }), className), "data-slot": "stepper", ...rest, children: [_jsx("div", { className: cn(stepperTrackVariants({ size: baseSize }), getResponsiveSizeOverrides(size, STEPPER_TRACK_SIZE_CLASSES)), children: _jsx(m.div, { animate: { scaleX: progressPercent / 100 }, className: "bg-affirmative-accent absolute inset-y-0 left-0 w-full origin-left", initial: { scaleX: 0 }, transition: springs.standard }) }), children] }) }));
+};

package/dist/components/stepper/stepper-variants.d.ts

@@ -0,0 +1,43 @@
+import type { StepperSize } from "../stepper/stepper-context.js";
+/** Default Stepper size. */
+export declare const DEFAULT_STEPPER_SIZE: StepperSize;
+/**
+ * Per-size track inset map. Exported so Stepper can layer per-breakpoint
+ * `md:*` overrides on top of the cva's base size via
+ * `getResponsiveSizeOverrides`. The cva still references this map as its `size`
+ * variant, so static output is unchanged.
+ */
+export declare const STEPPER_TRACK_SIZE_CLASSES: Record<StepperSize, string>;
+/** Per-size circle-container dimension map (see {@link STEPPER_TRACK_SIZE_CLASSES}). */
+export declare const STEPPER_CIRCLE_CONTAINER_SIZE_CLASSES: Record<StepperSize, string>;
+/** Per-size label offset map (see {@link STEPPER_TRACK_SIZE_CLASSES}). */
+export declare const STEPPER_LABEL_SIZE_CLASSES: Record<StepperSize, string>;
+/** Root container variants */
+export declare const stepperRootVariants: (props?: ({
+    size?: "base" | "lg" | "sm" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** Track line - absolute positioned behind circles */
+export declare const stepperTrackVariants: (props?: ({
+    size?: StepperSize | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** Circle container - fixed size with z-index to sit above track */
+export declare const stepperCircleContainerVariants: (props?: ({
+    size?: StepperSize | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** Step circle variants - absolutely positioned to prevent layout shift */
+export declare const stepperCircleVariants: (props?: ({
+    size?: "base" | "lg" | "sm" | null | undefined;
+    state?: "completed" | "current" | "disabled" | "upcoming" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** Step icon variants */
+export declare const stepperIconVariants: (props?: ({
+    size?: "base" | "lg" | "sm" | null | undefined;
+    state?: "completed" | "current" | "disabled" | "upcoming" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** Step label variants - absolutely positioned to not affect flex layout */
+export declare const stepperLabelVariants: (props?: ({
+    size?: StepperSize | null | undefined;
+    state?: "completed" | "current" | "disabled" | "upcoming" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** Step state type */
+export type StepState = "completed" | "current" | "upcoming" | "disabled";

package/dist/components/stepper/stepper-variants.js

@@ -0,0 +1,122 @@
+import { cva } from "class-variance-authority";
+/** Default Stepper size. */
+export const DEFAULT_STEPPER_SIZE = "base";
+/**
+ * Per-size track inset map. Exported so Stepper can layer per-breakpoint
+ * `md:*` overrides on top of the cva's base size via
+ * `getResponsiveSizeOverrides`. The cva still references this map as its `size`
+ * variant, so static output is unchanged.
+ */
+export const STEPPER_TRACK_SIZE_CLASSES = {
+    // base: size-9 (36px) → top 18px, inset 18px
+    base: "top-4.5 right-4.5 left-4.5",
+    // lg: size-11 (44px) → top 22px, inset 22px
+    lg: "top-5.5 right-5.5 left-5.5",
+    // sm: size-7 (28px) → top 14px, inset 14px
+    sm: "top-3.5 right-3.5 left-3.5",
+};
+/** Per-size circle-container dimension map (see {@link STEPPER_TRACK_SIZE_CLASSES}). */
+export const STEPPER_CIRCLE_CONTAINER_SIZE_CLASSES = {
+    // 36px
+    base: "size-9",
+    // 44px
+    lg: "size-11",
+    // 28px
+    sm: "size-7",
+};
+/** Per-size label offset map (see {@link STEPPER_TRACK_SIZE_CLASSES}). */
+export const STEPPER_LABEL_SIZE_CLASSES = {
+    // h-9 (36px) + 8px gap = 44px
+    base: "top-11",
+    // h-11 (44px) + 8px gap = 52px
+    lg: "top-13",
+    // h-7 (28px) + 8px gap = 36px
+    sm: "top-9",
+};
+/** Root container variants */
+export const stepperRootVariants = cva("relative flex w-full items-start justify-between", {
+    defaultVariants: {
+        size: "base",
+    },
+    variants: {
+        size: {
+            sm: "",
+            base: "",
+            lg: "",
+        },
+    },
+});
+/** Track line - absolute positioned behind circles */
+export const stepperTrackVariants = cva("bg-muted absolute h-px overflow-hidden", {
+    defaultVariants: {
+        size: "base",
+    },
+    variants: {
+        size: STEPPER_TRACK_SIZE_CLASSES,
+    },
+});
+/** Circle container - fixed size with z-index to sit above track */
+export const stepperCircleContainerVariants = cva("relative z-10", {
+    defaultVariants: {
+        size: "base",
+    },
+    variants: {
+        size: STEPPER_CIRCLE_CONTAINER_SIZE_CLASSES,
+    },
+});
+/** Step circle variants - absolutely positioned to prevent layout shift */
+export const stepperCircleVariants = cva("group absolute top-1/2 left-1/2 flex shrink-0 -translate-1/2 items-center justify-center rounded-full transition-colors", {
+    defaultVariants: {
+        size: "base",
+        state: "upcoming",
+    },
+    variants: {
+        size: {
+            sm: "",
+            base: "",
+            lg: "",
+        },
+        state: {
+            completed: "bg-affirmative-accent",
+            current: "bg-input hover:border-affirmative-border hover:bg-affirmative-soft border",
+            upcoming: "bg-input hover:border-affirmative-border hover:bg-affirmative-soft border",
+            disabled: "bg-input border opacity-50",
+        },
+    },
+});
+/** Step icon variants */
+export const stepperIconVariants = cva("transition-colors", {
+    defaultVariants: {
+        size: "base",
+        state: "upcoming",
+    },
+    variants: {
+        size: {
+            sm: "",
+            base: "",
+            lg: "",
+        },
+        state: {
+            completed: "text-white",
+            current: "text-muted-foreground group-hover:text-affirmative-accent",
+            upcoming: "text-muted-foreground group-hover:text-affirmative-accent",
+            disabled: "text-muted-foreground opacity-50",
+        },
+    },
+});
+/** Step label variants - absolutely positioned to not affect flex layout */
+export const stepperLabelVariants = cva("text-caption absolute left-1/2 -translate-x-1/2 text-center whitespace-nowrap", {
+    defaultVariants: {
+        size: "base",
+        state: "upcoming",
+    },
+    variants: {
+        size: STEPPER_LABEL_SIZE_CLASSES,
+        state: {
+            completed: "text-foreground",
+            current: "text-foreground",
+            disabled: "text-muted-foreground opacity-50",
+            upcoming: "text-muted-foreground",
+        },
+    },
+});

package/dist/components/stepper.d.ts

@@ -0,0 +1,5 @@
+export type { StepperSize } from "./stepper/stepper-context.js";
+export type { StepperItemProps } from "./stepper/stepper-item.js";
+export { StepperItem } from "./stepper/stepper-item.js";
+export type { StepperProps } from "./stepper/stepper-root.js";
+export { Stepper } from "./stepper/stepper-root.js";

package/dist/components/stepper.js

@@ -0,0 +1,2 @@
+export { StepperItem } from "./stepper/stepper-item.js";
+export { Stepper } from "./stepper/stepper-root.js";

package/dist/components/streaming-text/streaming-text-root.d.ts

@@ -0,0 +1,48 @@
+import type { ReactNode } from "react";
+/** One streamed token; optional inline citation marker. */
+export interface StreamingTextToken {
+    /** Stable identity for list rendering. */
+    id: string;
+    text: string;
+    cite?: boolean;
+}
+/** A cited source shown inline and in the sources disclosure. */
+export interface StreamingTextSource {
+    name: string;
+    domain: string;
+    href: string;
+    image: string;
+}
+export interface StreamingTextProps {
+    className?: string;
+    /** Tokens revealed so far (controlled). */
+    tokens: StreamingTextToken[];
+    /** Whether the stream is still open. */
+    streaming?: boolean;
+    /** Sources for the stacked avatars + disclosure. */
+    sources?: StreamingTextSource[];
+    /** Source count label (may exceed `sources.length`). */
+    sourceCount?: number;
+    /** Follow-up prompts revealed after settle. */
+    followUps?: string[];
+    /** Called when a follow-up is chosen. */
+    onFollowUp?: (text: string) => void;
+    /** Action controls (copy, retry, rating) rendered once the answer settles. */
+    actions?: ReactNode;
+    /** Heading above the follow-up prompts. Defaults to `"Follow-ups"`. */
+    followUpsLabel?: string;
+    /** Noun after the source count. Defaults to `"sources"`. */
+    sourcesLabel?: string;
+}
+/**
+ * Progressive streaming answer with settle-gated chrome.
+ *
+ * @example
+ * ```tsx
+ * <StreamingText tokens={visible} streaming={!done} followUps={["Tell me more"]} />
+ * ```
+ *
+ * @bestPractice Drive `tokens` from real stream deltas - don't fake a word clock in product code. Showcase demos may animate.
+ * @category feedback
+ */
+export declare const StreamingText: ({ className, tokens, streaming, sources, sourceCount, followUps, onFollowUp, actions, followUpsLabel, sourcesLabel, }: StreamingTextProps) => import("react").JSX.Element;

package/dist/components/streaming-text/streaming-text-root.js

@@ -0,0 +1,49 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * StreamingText - progressive answer with caret, sources, actions, follow-ups.
+ *
+ * Tokens stream in; action / source / follow-up chrome only becomes interactive
+ * after the answer settles.
+ *
+ * @module
+ */
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { Grid } from "@instruments/materia-ui/components/grid";
+import { Text } from "@instruments/materia-ui/components/text";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useState } from "react";
+const EMPTY_SOURCES = [];
+const EMPTY_FOLLOW_UPS = [];
+const SourceChip = ({ source }) => (_jsxs("a", { className: "animate-pop-in bg-muted text-2xs text-muted-foreground ring-border hover:bg-accent hover:text-foreground duration-quick mr-1 inline-flex h-4.5 translate-y-px items-center gap-1 rounded-sm pr-1.5 pl-0.5 align-middle font-mono ring-1 transition-colors motion-reduce:animate-none motion-reduce:transition-none", href: source.href, rel: "noreferrer", target: "_blank", children: [_jsx("img", { alt: "", className: "size-3 rounded-xs", height: 12, src: source.image, width: 12 }), _jsx("span", { children: source.domain })] }));
+const TokenSpan = ({ token, source, }) => {
+    if (token.cite === true && source !== undefined) {
+        return _jsx(SourceChip, { source: source });
+    }
+    return (_jsxs("span", { className: "animate-fade-in inline motion-reduce:animate-none", children: [token.text, " "] }));
+};
+const FollowUpList = ({ followUps, done, label, onFollowUp, }) => (_jsxs("div", { className: cn("duration-moderate mt-2.5 transition-opacity motion-reduce:transition-none", done ? "opacity-100" : "opacity-0"), inert: !done, children: [_jsx(Text, { as: "p", size: "caption", variant: "muted", weight: "medium", children: label }), _jsx(Flex, { className: "mt-0.5", direction: "column", children: followUps.map((text, index) => (_jsxs("button", { className: cn("border-border text-foreground hover:bg-accent duration-quick -mx-1.5 flex items-center gap-2 rounded-md border-b px-1.5 py-1.5 text-left transition-colors last:border-0 motion-reduce:animate-none motion-reduce:transition-none", done ? "animate-fade-up" : "opacity-0"), onClick: () => {
+                    onFollowUp?.(text);
+                }, style: { animationDelay: `${index * 90}ms` }, type: "button", children: [_jsxs("svg", { "aria-hidden": true, className: "text-muted-foreground/70 shrink-0", fill: "none", height: "11", stroke: "currentColor", strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: "2", viewBox: "0 0 24 24", width: "11", children: [_jsx("path", { d: "M9 10l-5 5 5 5" }), _jsx("path", { d: "M20 4v7a4 4 0 0 1-4 4H4" })] }), _jsx(Text, { as: "span", size: "caption", children: text })] }, text))) })] }));
+/**
+ * Progressive streaming answer with settle-gated chrome.
+ *
+ * @example
+ * ```tsx
+ * <StreamingText tokens={visible} streaming={!done} followUps={["Tell me more"]} />
+ * ```
+ *
+ * @bestPractice Drive `tokens` from real stream deltas - don't fake a word clock in product code. Showcase demos may animate.
+ * @category feedback
+ */
+export const StreamingText = ({ className, tokens, streaming = false, sources = EMPTY_SOURCES, sourceCount, followUps = EMPTY_FOLLOW_UPS, onFollowUp, actions, followUpsLabel = "Follow-ups", sourcesLabel = "sources", }) => {
+    const [sourcesOpen, setSourcesOpen] = useState(false);
+    const done = !streaming;
+    const countLabel = sourceCount ?? sources.length;
+    const [firstSource] = sources;
+    return (_jsxs("div", { className: cn("w-full", className), "data-testid": "streaming-text", children: [_jsxs(Text, { as: "p", className: "text-foreground", size: "paragraph-sm", children: [tokens.map((token) => (_jsx(TokenSpan, { source: firstSource, token: token }, token.id))), streaming ? (_jsx("span", { "aria-hidden": true, className: "animate-fade-in bg-foreground ml-0.5 inline-block h-3 w-0.5 translate-y-0.5 rounded-full motion-reduce:animate-none" })) : null] }), _jsxs(Flex, { align: "center", className: cn("duration-moderate mt-2 transition-opacity motion-reduce:transition-none", done ? "opacity-100" : "opacity-0"), gap: "3xs", inert: !done, children: [actions, sources.length > 0 ? (_jsxs("button", { "aria-expanded": sourcesOpen, className: "hover:bg-muted duration-quick ml-1.5 flex items-center gap-1.5 rounded-md px-1 py-0.5 text-left transition-colors motion-reduce:transition-none", onClick: () => {
+                            setSourcesOpen((current) => !current);
+                        }, type: "button", children: [_jsx(Flex, { as: "span", className: "-space-x-1", children: sources.map((source) => (_jsx("img", { alt: "", className: "bg-background ring-background size-3.5 rounded-full ring-2", height: 14, src: source.image, width: 14 }, source.domain))) }), _jsxs(Text, { as: "span", size: "caption", variant: "muted", children: [countLabel, " ", sourcesLabel] })] })) : null] }), _jsx(Grid, { className: cn("duration-normal transition-panel ease-out motion-reduce:transition-none", done && sourcesOpen
+                    ? "grid-rows-[1fr] opacity-100"
+                    : "grid-rows-[0fr] opacity-0"), columns: "none", gap: "none", inert: !(done && sourcesOpen), children: _jsx("div", { className: "overflow-hidden", children: _jsx(Flex, { className: "bg-muted ring-border mt-1.5 rounded-md p-1 ring-1", direction: "column", children: sources.map((source) => (_jsxs("a", { className: "text-muted-foreground hover:bg-accent hover:text-foreground duration-quick flex items-center gap-2 rounded-md px-1.5 py-1 transition-colors motion-reduce:transition-none", href: source.href, rel: "noreferrer", target: "_blank", children: [_jsx("img", { alt: "", className: "size-4 rounded", height: 16, src: source.image, width: 16 }), _jsx(Text, { as: "span", className: "underline-grow", size: "caption", children: source.name }), _jsx(Text, { as: "span", className: "ml-auto font-mono", size: "caption", children: source.domain })] }, source.domain))) }) }) }), followUps.length > 0 ? (_jsx(FollowUpList, { done: done, followUps: followUps, label: followUpsLabel, ...(onFollowUp === undefined ? {} : { onFollowUp }) })) : null] }));
+};

package/dist/components/streaming-text.d.ts

@@ -0,0 +1 @@
+export { StreamingText, type StreamingTextProps, type StreamingTextSource, type StreamingTextToken, } from "./streaming-text/streaming-text-root.js";

package/dist/components/streaming-text.js

@@ -0,0 +1 @@
+export { StreamingText, } from "./streaming-text/streaming-text-root.js";

package/dist/components/sub-navigation/sub-navigation-link.d.ts

@@ -0,0 +1,18 @@
+import type { LucideIcon } from "lucide-react";
+import type * as React from "react";
+export interface SubNavigationLinkProps extends Omit<React.ComponentProps<"a">, "children" | "href"> {
+    /** Marks the current page - applies active styling and sets `aria-current="page"`. @default false */
+    active?: boolean;
+    /** Link label, matching what `MenuItem` renders. */
+    children?: React.ReactElement | string | number | undefined;
+    href?: string;
+    /** Leading icon shown before the label. */
+    icon?: LucideIcon;
+    /** Element to render as the link instead of an `<a>` (e.g. a router `Link`). It carries its own props; the anchor props here apply only to the default `<a>`. */
+    render?: React.ReactElement;
+}
+/**
+ * A single link within a {@link SubNavigationList}, rendered as a `<MenuItem>`
+ * inside a presentational `<li>`.
+ */
+export declare const SubNavigationLink: ({ active, children, href, icon, render, ...props }: SubNavigationLinkProps) => React.JSX.Element;

package/dist/components/sub-navigation/sub-navigation-link.js

@@ -0,0 +1,13 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { MenuItem } from "../menu-item.js";
+const SUB_NAVIGATION_LINK_DATA = {
+    "data-component": "sub-navigation-link",
+    "data-slot": "sub-navigation-link",
+};
+/**
+ * A single link within a {@link SubNavigationList}, rendered as a `<MenuItem>`
+ * inside a presentational `<li>`.
+ */
+export const SubNavigationLink = ({ active = false, children, href, icon, render, ...props }) => (_jsx("li", { role: "presentation", children: _jsx(MenuItem, { ...(icon === undefined ? {} : { icon }), active: active, "aria-current": active ? "page" : undefined, radius: "full", render: render ??
+            ((menuProps) => (_jsx("a", { ...menuProps, href: href, ...props, children: menuProps.children }))), size: "base", variant: "input", ...SUB_NAVIGATION_LINK_DATA, children: children }) }));

package/dist/components/sub-navigation/sub-navigation-list.d.ts

@@ -0,0 +1,7 @@
+import type * as React from "react";
+export type SubNavigationListProps = React.ComponentProps<"ul">;
+/**
+ * Stacked `<ul>` grouping {@link SubNavigationLink} items within a
+ * {@link SubNavigation}.
+ */
+export declare const SubNavigationList: ({ className, children, ...props }: SubNavigationListProps) => React.JSX.Element;

package/dist/components/sub-navigation/sub-navigation-list.js

@@ -0,0 +1,8 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flex } from "@instruments/materia-ui/components/flex";
+/**
+ * Stacked `<ul>` grouping {@link SubNavigationLink} items within a
+ * {@link SubNavigation}.
+ */
+export const SubNavigationList = ({ className, children, ...props }) => (_jsx(Flex, { as: "ul", className: className, "data-component": "sub-navigation-list", "data-slot": "sub-navigation-list", direction: "column", gap: "2xs", ...props, children: children }));

package/dist/components/sub-navigation/sub-navigation-root.d.ts

@@ -0,0 +1,11 @@
+import type * as React from "react";
+export type SubNavigationProps = React.ComponentProps<"nav">;
+/**
+ * Vertical secondary navigation for page subsections and settings-like layouts;
+ * the `<nav>` landmark wrapping a {@link SubNavigationList} of links.
+ *
+ * @bestPractice Reach for `SubNavigation` for a vertical in-page section/settings menu; horizontal router tabs are `TabNavigation`, the app-chrome shell is `Sidebar`.
+ * @bestPractice Fill it with a `SubNavigationList` of links - it already renders the `<nav>` landmark, so don't nest it inside another `<nav>`.
+ * @category navigation
+ */
+export declare const SubNavigation: ({ className, children, ...props }: SubNavigationProps) => React.JSX.Element;