@tangle-network/ui 11.40.2 → 11.42.0

package/src/primitives/breadcrumb.tsx

@@ -0,0 +1,126 @@
+import { ChevronRight } from "lucide-react";
+import { cn } from "../lib/utils";
+import * as React from "react";
+
+/**
+ * Where you are inside a nested surface — the workspace, its settings, the
+ * section you're in. Each crumb is a link except the last, which is the page.
+ *
+ * ```tsx
+ * <Breadcrumb>
+ *   <BreadcrumbList>
+ *     <BreadcrumbItem><BreadcrumbLink href="/workspaces/ws-1">Recenter demo</BreadcrumbLink></BreadcrumbItem>
+ *     <BreadcrumbSeparator />
+ *     <BreadcrumbItem><BreadcrumbLink href="/workspaces/ws-1/settings">Settings</BreadcrumbLink></BreadcrumbItem>
+ *     <BreadcrumbSeparator />
+ *     <BreadcrumbItem><BreadcrumbPage>Connections</BreadcrumbPage></BreadcrumbItem>
+ *   </BreadcrumbList>
+ * </Breadcrumb>
+ * ```
+ *
+ * On narrow viewports the list scrolls horizontally with a fade mask rather
+ * than wrapping — a crumb trail reads as one line, not a paragraph.
+ */
+const Breadcrumb = React.forwardRef<
+  HTMLElement,
+  React.HTMLAttributes<HTMLElement> & { separator?: React.ReactNode }
+>(({ className, ...props }, ref) => (
+  <nav ref={ref} aria-label="Breadcrumb" className={cn("relative", className)} {...props} />
+));
+Breadcrumb.displayName = "Breadcrumb";
+
+const BreadcrumbList = React.forwardRef<
+  HTMLOListElement,
+  React.OlHTMLAttributes<HTMLOListElement>
+>(({ className, ...props }, ref) => (
+  <ol
+    ref={ref}
+    className={cn(
+      "flex items-center gap-1.5 text-sm text-muted-foreground overflow-x-auto",
+      "[mask-image:linear-gradient(to_right,transparent,black_16px,black_calc(100%-16px),transparent)]",
+      "[-webkit-mask-image:linear-gradient(to_right,transparent,black_16px,black_calc(100%-16px),transparent)]",
+      "scrollbar-none",
+      className
+    )}
+    {...props}
+  />
+));
+BreadcrumbList.displayName = "BreadcrumbList";
+
+const BreadcrumbItem = React.forwardRef<
+  HTMLLIElement,
+  React.LiHTMLAttributes<HTMLLIElement>
+>(({ className, ...props }, ref) => (
+  <li ref={ref} className={cn("inline-flex items-center gap-1.5 shrink-0", className)} {...props} />
+));
+BreadcrumbItem.displayName = "BreadcrumbItem";
+
+const BreadcrumbLink = React.forwardRef<
+  HTMLAnchorElement,
+  React.AnchorHTMLAttributes<HTMLAnchorElement>
+>(({ className, ...props }, ref) => (
+  <a
+    ref={ref}
+    className={cn("transition-colors hover:text-foreground", className)}
+    {...props}
+  />
+));
+BreadcrumbLink.displayName = "BreadcrumbLink";
+
+const BreadcrumbPage = React.forwardRef<
+  HTMLSpanElement,
+  React.HTMLAttributes<HTMLSpanElement>
+>(({ className, ...props }, ref) => (
+  <span
+    ref={ref}
+    role="link"
+    aria-disabled="true"
+    aria-current="page"
+    className={cn("font-normal text-foreground", className)}
+    {...props}
+  />
+));
+BreadcrumbPage.displayName = "BreadcrumbPage";
+
+const BreadcrumbSeparator = React.forwardRef<
+  HTMLSpanElement,
+  React.HTMLAttributes<HTMLSpanElement>
+>(({ className, children, ...props }, ref) => (
+  <span
+    ref={ref}
+    role="presentation"
+    aria-hidden="true"
+    className={cn("shrink-0 text-muted-foreground/60", className)}
+    {...props}
+  >
+    {children ?? <ChevronRight className="size-3.5" aria-hidden />}
+  </span>
+));
+BreadcrumbSeparator.displayName = "BreadcrumbSeparator";
+
+const BreadcrumbEllipsis = React.forwardRef<
+  HTMLSpanElement,
+  React.HTMLAttributes<HTMLSpanElement>
+>(({ className, ...props }, ref) => (
+  <span
+    ref={ref}
+    role="presentation"
+    aria-hidden="true"
+    className={cn("flex size-6 items-center justify-center", className)}
+    {...props}
+  >
+    <span className="text-muted-foreground">…</span>
+    <span className="sr-only">More</span>
+  </span>
+));
+BreadcrumbEllipsis.displayName = "BreadcrumbEllipsis";
+
+export {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+};

package/src/primitives/hover-card-breadcrumb.test.tsx

@@ -0,0 +1,92 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import * as React from "react";
+import { describe, expect, it, vi } from "vitest";
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from "./breadcrumb";
+import {
+  HoverCard,
+  HoverCardContent,
+  HoverCardDescription,
+  HoverCardHeader,
+  HoverCardTitle,
+  HoverCardTrigger,
+} from "./hover-card";
+
+describe("HoverCard", () => {
+  it("shows the trigger and hides content until hovered", () => {
+    render(
+      <HoverCard>
+        <HoverCardTrigger>@noa</HoverCardTrigger>
+        <HoverCardContent>
+          <HoverCardHeader>
+            <HoverCardTitle>Noa</HoverCardTitle>
+            <HoverCardDescription>Housekeeping · es</HoverCardDescription>
+          </HoverCardHeader>
+        </HoverCardContent>
+      </HoverCard>,
+    );
+    expect(screen.getByText("@noa")).toBeVisible();
+    // Portal content only renders when open
+    expect(screen.queryByText("Noa")).toBeNull();
+  });
+
+  it("renders with a custom className on content", () => {
+    render(
+      <HoverCard open>
+        <HoverCardTrigger>hover me</HoverCardTrigger>
+        <HoverCardContent className="w-80" data-testid="card">
+          <p>Content</p>
+        </HoverCardContent>
+      </HoverCard>,
+    );
+    const card = screen.getByTestId("card");
+    expect(card).toBeInTheDocument();
+    expect(card.className).toContain("w-80");
+  });
+});
+
+describe("Breadcrumb", () => {
+  it("renders a trail with links and a terminal page", () => {
+    render(
+      <Breadcrumb>
+        <BreadcrumbList>
+          <BreadcrumbItem>
+            <BreadcrumbLink href="/ws-1">Workspace</BreadcrumbLink>
+          </BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem>
+            <BreadcrumbLink href="/ws-1/settings">Settings</BreadcrumbLink>
+          </BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem>
+            <BreadcrumbPage>Connections</BreadcrumbPage>
+          </BreadcrumbItem>
+        </BreadcrumbList>
+      </Breadcrumb>,
+    );
+    expect(screen.getByRole("navigation", { name: "Breadcrumb" })).toBeVisible();
+    expect(screen.getByText("Workspace")).toHaveAttribute("href", "/ws-1");
+    expect(screen.getByText("Connections")).toHaveAttribute("aria-current", "page");
+  });
+
+  it("separates crumbs with chevrons by default", () => {
+    render(
+      <Breadcrumb>
+        <BreadcrumbList>
+          <BreadcrumbItem><BreadcrumbLink href="/a">A</BreadcrumbLink></BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem><BreadcrumbPage>B</BreadcrumbPage></BreadcrumbItem>
+        </BreadcrumbList>
+      </Breadcrumb>,
+    );
+    const separators = screen.getAllByRole("presentation", { hidden: true });
+    expect(separators.length).toBeGreaterThanOrEqual(1);
+  });
+});

package/src/primitives/hover-card.tsx

@@ -0,0 +1,89 @@
+import { cn } from "../lib/utils";
+import * as React from "react";
+
+/**
+ * A rich hover preview: the face of a person, product, or record that appears
+ * when you pause on its trigger. Radix HoverCard under the hood, styled on the
+ * md3 surface ladder — the card sits on `--md3-surface-container-highest`
+ * (L4, the overlay plane) so it reads as a floating layer above the page.
+ *
+ * ```tsx
+ * <HoverCard>
+ *   <HoverCardTrigger>@noa</HoverCardTrigger>
+ *   <HoverCardContent>
+ *     <HoverCardHeader>
+ *       <HoverCardTitle>Noa</HoverCardTitle>
+ *       <HoverCardDescription>Housekeeping · es</HoverCardDescription>
+ *     </HoverCardHeader>
+ *     <p>3 rooms today · 1 pending</p>
+ *   </HoverCardContent>
+ * </HoverCard>
+ * ```
+ *
+ * The content is **lazy** — it mounts only when hovered, so a page of 50
+ * triggers costs nothing until the person pauses on one.
+ */
+import * as HoverCardPrimitive from "@radix-ui/react-hover-card";
+
+const HoverCard = HoverCardPrimitive.Root;
+
+const HoverCardTrigger = React.forwardRef<
+  React.ElementRef<typeof HoverCardPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof HoverCardPrimitive.Trigger>
+>(({ className, ...props }, ref) => (
+  <HoverCardPrimitive.Trigger
+    ref={ref}
+    className={cn("cursor-pointer underline-offset-4 hover:underline", className)}
+    {...props}
+  />
+));
+HoverCardTrigger.displayName = HoverCardPrimitive.Trigger.displayName;
+
+const HoverCardContent = React.forwardRef<
+  React.ElementRef<typeof HoverCardPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof HoverCardPrimitive.Content> & {
+    /** Which edge the card prefers. Defaults to bottom. */
+    side?: "top" | "right" | "bottom" | "left";
+    /** Pixel gap from the trigger. Defaults to 6. */
+    alignOffset?: number;
+  }
+>(({ className, side = "bottom", alignOffset = 6, ...props }, ref) => (
+  <HoverCardPrimitive.Portal>
+    <HoverCardPrimitive.Content
+      ref={ref}
+      side={side}
+      alignOffset={alignOffset}
+      sideOffset={6}
+      className={cn(
+        "z-50 w-64 rounded-lg border border-border bg-popover p-4 text-popover-foreground shadow-md outline-none",
+        "data-[state=open]:animate-in data-[state=closed]:animate-out",
+        "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+        "data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
+        className
+      )}
+      {...props}
+    />
+  </HoverCardPrimitive.Portal>
+));
+HoverCardContent.displayName = HoverCardPrimitive.Content.displayName;
+
+function HoverCardHeader({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("flex flex-col gap-1 pb-2", className)} {...props} />;
+}
+
+function HoverCardTitle({ className, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
+  return <h4 className={cn("text-sm font-semibold leading-none", className)} {...props} />;
+}
+
+function HoverCardDescription({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>) {
+  return <p className={cn("text-sm text-muted-foreground", className)} {...props} />;
+}
+
+export {
+  HoverCard,
+  HoverCardTrigger,
+  HoverCardContent,
+  HoverCardHeader,
+  HoverCardTitle,
+  HoverCardDescription,
+};

package/src/primitives/index.ts

@@ -234,6 +234,9 @@ export { Chip } from "./chip";
 export type { ChipProps } from "./chip";
 
 export { Wizard, WizardStep } from "./wizard";
+export { HoverCard, HoverCardTrigger, HoverCardContent, HoverCardHeader, HoverCardTitle, HoverCardDescription } from "./hover-card";
+
+export { Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis } from "./breadcrumb";
 export type { WizardProps, WizardStepProps } from "./wizard";
 
 export { IconTile, initialsOf } from "./icon-tile";
@@ -245,5 +248,26 @@ export type { CategoryTone, Tone, ToneClasses } from "./tone";
 export { MetricStrip, Metric } from "./metric-strip";
 export type { MetricStripProps, MetricProps } from "./metric-strip";
 
+export { SeriesSparkline } from "./series-sparkline";
+export type { SeriesSparklineProps } from "./series-sparkline";
+export { MetricChart } from "./metric-chart";
+export type { ChartReferenceLine, MetricChartProps } from "./metric-chart";
+export {
+  normalizeSeries,
+  periodDelta,
+  seriesAreaPath,
+  seriesExtent,
+  seriesLinePath,
+  seriesMean,
+  seriesScale,
+} from "../lib/series";
+export type {
+  PeriodDelta,
+  SeriesExtent,
+  SeriesPoint,
+  SeriesPointInput,
+  SeriesScale,
+} from "../lib/series";
+
 export { Toolbar, FilterField } from "./toolbar";
 export type { ToolbarProps, FilterFieldProps } from "./toolbar";

package/src/primitives/metric-chart.stories.tsx

@@ -0,0 +1,55 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { MetricChart } from "./metric-chart";
+
+const meta = {
+  title: "Primitives/MetricChart",
+  component: MetricChart,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof MetricChart>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const DAY = 86_400_000;
+const t0 = Date.parse("2026-08-24T07:00:00.000Z");
+
+const bloodPressure = Array.from({ length: 12 }, (_, index) => ({
+  at: t0 + index * 5 * DAY,
+  value: 118 + ((index * 7) % 9),
+  value2: 74 + ((index * 5) % 8),
+}));
+
+const steps = Array.from({ length: 12 }, (_, index) => ({
+  at: t0 + index * 5 * DAY,
+  value: 6_200 + ((index * 1_937) % 4_800),
+}));
+
+export const DualSeries: Story = {
+  args: {
+    title: "Blood pressure",
+    unit: "mmHg",
+    decimals: 0,
+    points: bloodPressure,
+    referenceLines: [
+      { value: 120, label: "120 systolic" },
+      { value: 80, label: "80 diastolic", series: "secondary" },
+    ],
+  },
+};
+
+export const SingleSeries: Story = {
+  args: {
+    title: "Steps",
+    unit: "steps",
+    decimals: 0,
+    points: steps,
+  },
+};
+
+export const SingleReading: Story = {
+  args: {
+    title: "Weight",
+    unit: "kg",
+    decimals: 1,
+    points: [{ at: t0, value: 71.4 }],
+  },
+};

package/src/primitives/metric-chart.test.tsx

@@ -0,0 +1,118 @@
+import * as React from "react";
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { MetricChart } from "./metric-chart";
+
+afterEach(cleanup);
+
+const DAY = 86_400_000;
+const t0 = Date.parse("2026-09-01T07:00:00.000Z");
+const points = Array.from({ length: 10 }, (_, index) => ({
+  at: t0 + index * 5 * DAY,
+  value: 118 + (index % 3) * 4,
+  value2: 76 + (index % 2) * 4,
+}));
+
+describe("MetricChart", () => {
+  it("renders an accessible svg with a generated summary description", () => {
+    const { container } = render(
+      <MetricChart points={points} title="Blood pressure" unit="mmHg" decimals={0} />,
+    );
+    const svg = screen.getByRole("img", { name: "Blood pressure" });
+    expect(svg.querySelector("title")!.textContent).toBe("Blood pressure");
+    const desc = svg.querySelector("desc")!.textContent!;
+    expect(desc).toContain("10 readings");
+    expect(desc).toContain("min 118");
+    expect(desc).toContain("max 126");
+    expect(desc).toContain("mmHg");
+    // Primary line, area and dotted secondary series.
+    expect(container.querySelectorAll("path").length).toBeGreaterThanOrEqual(3);
+  });
+
+  it("honours a caller-provided description", () => {
+    const { container } = render(
+      <MetricChart points={points} title="Blood pressure" description="Custom summary." />,
+    );
+    expect(container.querySelector("desc")!.textContent).toBe("Custom summary.");
+  });
+
+  it("draws gridlines, date ticks and labelled reference lines on muted ink", () => {
+    const { container } = render(
+      <MetricChart
+        points={points}
+        title="Blood pressure"
+        referenceLines={[
+          { value: 120, label: "120 systolic" },
+          { value: 80, label: "80 diastolic", series: "secondary" },
+        ]}
+      />,
+    );
+    expect(screen.getByText("120 systolic")).toBeInTheDocument();
+    expect(screen.getByText("80 diastolic")).toBeInTheDocument();
+    // Four interior y ticks plus three x date ticks.
+    expect(screen.getByText("Sep 1")).toBeInTheDocument();
+    const dashed = Array.from(container.querySelectorAll("line")).filter(
+      (line) => line.getAttribute("stroke-dasharray") === "5 4",
+    );
+    expect(dashed).toHaveLength(2);
+    for (const line of dashed) expect(line.closest("g")!.getAttribute("class")).toContain("text-muted-foreground");
+  });
+
+  it("drops secondary reference lines when the series has no second reading", () => {
+    const single = points.map(({ at, value }) => ({ at, value }));
+    const { container } = render(
+      <MetricChart
+        points={single}
+        title="Heart rate"
+        referenceLines={[{ value: 80, label: "80 diastolic", series: "secondary" }]}
+      />,
+    );
+    expect(screen.queryByText("80 diastolic")).toBeNull();
+    expect(
+      Array.from(container.querySelectorAll("line")).filter(
+        (line) => line.getAttribute("stroke-dasharray") === "5 4",
+      ),
+    ).toHaveLength(0);
+  });
+
+  it("marks a single reading and renders axes only when data exists", () => {
+    const { container, rerender } = render(
+      <MetricChart points={[points[0]!]} title="Blood pressure" />,
+    );
+    expect(container.querySelectorAll("circle")).toHaveLength(1);
+    rerender(<MetricChart points={[]} title="Blood pressure" />);
+    expect(container.querySelectorAll("line")).toHaveLength(0);
+    expect(container.querySelectorAll("path")).toHaveLength(0);
+    expect(screen.getByRole("img", { name: "Blood pressure" })).toBeInTheDocument();
+  });
+
+  it("keeps every stroke and fill on currentColor", () => {
+    const { container } = render(<MetricChart points={points} title="Blood pressure" />);
+    for (const element of Array.from(container.querySelectorAll("[stroke], [fill]"))) {
+      const paint = element.getAttribute("stroke") ?? element.getAttribute("fill");
+      expect(["currentColor", "none"]).toContain(paint);
+    }
+  });
+
+  it("supports caller value and time formatting", () => {
+    render(
+      <MetricChart
+        points={points}
+        title="Blood pressure"
+        formatValue={(value) => `${value.toFixed(0)}!`}
+        formatTime={() => "sometime"}
+      />,
+    );
+    expect(screen.getAllByText("sometime")).toHaveLength(3);
+    expect(screen.getAllByText(/!$/).length).toBeGreaterThan(0);
+  });
+
+  it("preserves ref, caller attributes and caller classes", () => {
+    const ref = React.createRef<SVGSVGElement>();
+    const { container } = render(
+      <MetricChart ref={ref} points={points} title="Blood pressure" data-testid="bp" className="max-w-md" />,
+    );
+    expect(ref.current).toBe(container.querySelector("svg"));
+    expect(screen.getByTestId("bp").getAttribute("class")).toContain("max-w-md");
+  });
+});