@elabs-ai/components-ai 4.0.0

package/src/inline-citation.tsx

@@ -0,0 +1,314 @@
+"use client";
+
+import { Badge } from "@elabs-ai/components-ui";
+import type { CarouselApi } from "@elabs-ai/components-ui";
+import { Carousel, CarouselContent, CarouselItem } from "@elabs-ai/components-ui";
+import { HoverCard, HoverCardContent, HoverCardTrigger } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { useLocale } from "@elabs-ai/components-ui";
+import { ArrowLeftIcon, ArrowRightIcon, BadgeCheckIcon } from "lucide-react";
+import type { ComponentProps } from "react";
+import { createContext, useCallback, useContext, useEffect, useState } from "react";
+
+export type InlineCitationProps = ComponentProps<"span">;
+
+export const InlineCitation = ({ className, ...props }: InlineCitationProps) => (
+  <span className={cn("group inline items-center gap-1", className)} {...props} />
+);
+
+export type InlineCitationTextProps = ComponentProps<"span">;
+
+export const InlineCitationText = ({ className, ...props }: InlineCitationTextProps) => (
+  <span className={cn("transition-colors group-hover:bg-accent", className)} {...props} />
+);
+
+export type InlineCitationCardProps = ComponentProps<typeof HoverCard>;
+
+export const InlineCitationCard = (props: InlineCitationCardProps) => (
+  <HoverCard closeDelay={0} openDelay={0} {...props} />
+);
+
+/**
+ * A cited source: a bare string — a URL, or any opaque id / human label — or a
+ * labelled object.
+ *
+ * Non-URL sources are first-class. An agent citing a warehouse table, a document
+ * id, an uploaded file or a wiki page has no hostname to show, and must not have
+ * to synthesize a fake URL to satisfy the chip.
+ */
+export type InlineCitationSourceRef =
+  | string
+  | {
+      /** Opaque identifier, shown when there is no `label` and no `url`. */
+      id?: string;
+      /** Human-readable label — wins over any hostname derived from `url`. */
+      label?: string;
+      /** Optional link; its hostname is the fallback label. */
+      url?: string;
+    };
+
+/** The URL's hostname when `value` parses as one, else `value` itself. Never throws. */
+const hostnameOrRaw = (value: string): string => {
+  try {
+    return new URL(value).hostname || value;
+  } catch {
+    return value;
+  }
+};
+
+/**
+ * The chip label for a source ref. Exported so consumers can render the same
+ * label elsewhere (a footnote list, a tooltip) without re-deriving the rules.
+ */
+export const inlineCitationSourceLabel = (source: InlineCitationSourceRef): string => {
+  if (typeof source === "string") {
+    return hostnameOrRaw(source);
+  }
+  // `||` not `??` — an upstream field that is present but EMPTY (`label: ""`)
+  // must still fall through, or the chip renders with no label at all.
+  return source.label || (source.url ? hostnameOrRaw(source.url) : source.id || "unknown");
+};
+
+export type InlineCitationCardTriggerProps = ComponentProps<typeof Badge> & {
+  sources: InlineCitationSourceRef[];
+};
+
+export const InlineCitationCardTrigger = ({
+  sources,
+  className,
+  ...props
+}: InlineCitationCardTriggerProps) => (
+  <HoverCardTrigger asChild>
+    <Badge
+      // The 08 §C.1 evidence channel: the green wash marks "grounded" — green
+      // is reserved for evidence/answer/favourable (research 11 §B.4).
+      className={cn(
+        "ms-1 rounded-full border-success/40 bg-success/10 text-success-text",
+        className,
+      )}
+      variant="outline"
+      {...props}
+    >
+      <BadgeCheckIcon aria-hidden="true" className="size-3" />
+      {sources[0] ? (
+        <>
+          {inlineCitationSourceLabel(sources[0])} {sources.length > 1 && `+${sources.length - 1}`}
+        </>
+      ) : (
+        "unknown"
+      )}
+    </Badge>
+  </HoverCardTrigger>
+);
+
+export type EvidenceChipProps = InlineCitationCardTriggerProps;
+
+/**
+ * EvidenceChip — the named front door for the inline evidence interaction
+ * (research 11 §B.4): the re-skinned `InlineCitationCardTrigger` (green
+ * "grounded" wash). Use inside an `InlineCitationCard` (HoverCard) — it reuses
+ * the citation carousel wholesale; it is not a new primitive.
+ */
+export const EvidenceChip = InlineCitationCardTrigger;
+
+export type InlineCitationCardBodyProps = ComponentProps<"div">;
+
+export const InlineCitationCardBody = ({ className, ...props }: InlineCitationCardBodyProps) => (
+  <HoverCardContent className={cn("relative w-80 p-0", className)} {...props} />
+);
+
+const CarouselApiContext = createContext<CarouselApi | undefined>(undefined);
+
+const useCarouselApi = () => {
+  const context = useContext(CarouselApiContext);
+  return context;
+};
+
+export type InlineCitationCarouselProps = ComponentProps<typeof Carousel>;
+
+export const InlineCitationCarousel = ({
+  className,
+  children,
+  ...props
+}: InlineCitationCarouselProps) => {
+  const [api, setApi] = useState<CarouselApi>();
+
+  return (
+    <CarouselApiContext.Provider value={api}>
+      <Carousel className={cn("w-full", className)} setApi={setApi} {...props}>
+        {children}
+      </Carousel>
+    </CarouselApiContext.Provider>
+  );
+};
+
+export type InlineCitationCarouselContentProps = ComponentProps<"div">;
+
+export const InlineCitationCarouselContent = (props: InlineCitationCarouselContentProps) => (
+  <CarouselContent {...props} />
+);
+
+export type InlineCitationCarouselItemProps = ComponentProps<"div">;
+
+export const InlineCitationCarouselItem = ({
+  className,
+  ...props
+}: InlineCitationCarouselItemProps) => (
+  <CarouselItem className={cn("w-full space-y-2 p-4 ps-8", className)} {...props} />
+);
+
+export type InlineCitationCarouselHeaderProps = ComponentProps<"div">;
+
+export const InlineCitationCarouselHeader = ({
+  className,
+  ...props
+}: InlineCitationCarouselHeaderProps) => (
+  <div
+    className={cn(
+      "flex items-center justify-between gap-2 rounded-t-md bg-secondary p-2",
+      className,
+    )}
+    {...props}
+  />
+);
+
+export type InlineCitationCarouselIndexProps = ComponentProps<"div">;
+
+export const InlineCitationCarouselIndex = ({
+  children,
+  className,
+  ...props
+}: InlineCitationCarouselIndexProps) => {
+  const api = useCarouselApi();
+  const [current, setCurrent] = useState(0);
+  const [count, setCount] = useState(0);
+
+  const syncState = useCallback(() => {
+    if (!api) {
+      return;
+    }
+    setCount(api.scrollSnapList().length);
+    setCurrent(api.selectedScrollSnap() + 1);
+  }, [api]);
+
+  useEffect(() => {
+    if (!api) {
+      return;
+    }
+
+    syncState();
+
+    api.on("select", syncState);
+
+    return () => {
+      api.off("select", syncState);
+    };
+  }, [api, syncState]);
+
+  return (
+    <div
+      className={cn(
+        "flex flex-1 items-center justify-end px-3 py-1 text-muted-foreground text-xs",
+        className,
+      )}
+      {...props}
+    >
+      {children ?? `${current}/${count}`}
+    </div>
+  );
+};
+
+export type InlineCitationCarouselPrevProps = ComponentProps<"button">;
+
+export const InlineCitationCarouselPrev = ({
+  className,
+  ...props
+}: InlineCitationCarouselPrevProps) => {
+  const { t } = useLocale();
+  const api = useCarouselApi();
+
+  const handleClick = useCallback(() => {
+    if (api) {
+      api.scrollPrev();
+    }
+  }, [api]);
+
+  return (
+    <button
+      aria-label={t("previous")}
+      className={cn("shrink-0", className)}
+      onClick={handleClick}
+      type="button"
+      {...props}
+    >
+      <ArrowLeftIcon className="size-4 text-muted-foreground" data-rtl-flip />
+    </button>
+  );
+};
+
+export type InlineCitationCarouselNextProps = ComponentProps<"button">;
+
+export const InlineCitationCarouselNext = ({
+  className,
+  ...props
+}: InlineCitationCarouselNextProps) => {
+  const { t } = useLocale();
+  const api = useCarouselApi();
+
+  const handleClick = useCallback(() => {
+    if (api) {
+      api.scrollNext();
+    }
+  }, [api]);
+
+  return (
+    <button
+      aria-label={t("next")}
+      className={cn("shrink-0", className)}
+      onClick={handleClick}
+      type="button"
+      {...props}
+    >
+      <ArrowRightIcon className="size-4 text-muted-foreground" data-rtl-flip />
+    </button>
+  );
+};
+
+export type InlineCitationSourceProps = ComponentProps<"div"> & {
+  title?: string;
+  url?: string;
+  description?: string;
+};
+
+export const InlineCitationSource = ({
+  title,
+  url,
+  description,
+  className,
+  children,
+  ...props
+}: InlineCitationSourceProps) => (
+  <div className={cn("space-y-1", className)} {...props}>
+    {title && <h4 className="truncate font-medium text-sm leading-tight">{title}</h4>}
+    {url && <p className="truncate break-all text-muted-foreground text-xs">{url}</p>}
+    {description && (
+      <p className="line-clamp-3 text-muted-foreground text-sm leading-relaxed">{description}</p>
+    )}
+    {children}
+  </div>
+);
+
+export type InlineCitationQuoteProps = ComponentProps<"blockquote">;
+
+export const InlineCitationQuote = ({
+  children,
+  className,
+  ...props
+}: InlineCitationQuoteProps) => (
+  <blockquote
+    className={cn("border-muted border-s-2 ps-3 text-muted-foreground text-sm italic", className)}
+    {...props}
+  >
+    {children}
+  </blockquote>
+);

package/src/interactive-terminal.stories.tsx

@@ -0,0 +1,165 @@
+import { useEffect, useRef } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, waitFor, within } from "storybook/test";
+import { Button } from "@elabs-ai/components-ui";
+import { InteractiveTerminal, type InteractiveTerminalHandle } from "./interactive-terminal";
+
+const meta = {
+  title: "AI/InteractiveTerminal",
+  component: InteractiveTerminal,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "A token-themed **xterm.js** terminal — a real interactive PTY surface (ANSI " +
+          "output, typed input incl. paste, resize). `Terminal` stays the presentational " +
+          "read-only log; this is the wrapper for an actual running process. The " +
+          "PTY/process is consumer-owned (D5) — this component only renders ANSI output " +
+          "and emits `onData`/`onResize`; it never spawns anything. Press **Escape** or " +
+          "**Tab**/**Shift+Tab** at any time to move focus out of the terminal — there is " +
+          "no keyboard trap.",
+      },
+    },
+  },
+} satisfies Meta<typeof InteractiveTerminal>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Exercises all 8 base ANSI colors + their bright variants, so a cross-theme
+// audit can confirm every swatch stays legible in light/dark.
+const ANSI_PALETTE =
+  "\x1b[30mblack\x1b[0m \x1b[31mred\x1b[0m \x1b[32mgreen\x1b[0m \x1b[33myellow\x1b[0m " +
+  "\x1b[34mblue\x1b[0m \x1b[35mmagenta\x1b[0m \x1b[36mcyan\x1b[0m \x1b[37mwhite\x1b[0m\r\n" +
+  "\x1b[1;30mblack\x1b[0m \x1b[1;31mred\x1b[0m \x1b[1;32mgreen\x1b[0m \x1b[1;33myellow\x1b[0m " +
+  "\x1b[1;34mblue\x1b[0m \x1b[1;35mmagenta\x1b[0m \x1b[1;36mcyan\x1b[0m \x1b[1;37mwhite\x1b[0m " +
+  "(bright)\r\n";
+
+async function waitForXtermTextarea(root: HTMLElement): Promise<HTMLTextAreaElement> {
+  let textarea: HTMLTextAreaElement | null = null;
+  await waitFor(
+    () => {
+      textarea = root.querySelector("textarea");
+      if (!textarea) throw new Error("xterm textarea not mounted yet");
+    },
+    { timeout: 10000 },
+  );
+  return textarea!;
+}
+
+/**
+ * A minimal fake "shell": echoes typed characters back and, on Enter, prints a
+ * canned response — standing in for the real PTY a consumer (e.g. the
+ * agent seam in a consuming workbench app) would drive via `onData`/`write()`.
+ */
+function EchoDemo() {
+  const ref = useRef<InteractiveTerminalHandle>(null);
+  const lineRef = useRef("");
+  const lastCommandRef = useRef<HTMLParagraphElement>(null);
+
+  useEffect(() => {
+    ref.current?.write(ANSI_PALETTE);
+    ref.current?.write("Type a command and press Enter (try “hello”).\r\n$ ");
+  }, []);
+
+  const handleData = (data: string) => {
+    if (data === "\r") {
+      const command = lineRef.current;
+      lineRef.current = "";
+      ref.current?.write("\r\n");
+      if (command.trim().length > 0) {
+        ref.current?.write(`\x1b[32m✓\x1b[0m ran: ${command}\r\n`);
+        if (lastCommandRef.current) {
+          lastCommandRef.current.textContent = `Last command: “${command}”`;
+        }
+      }
+      ref.current?.write("$ ");
+      return;
+    }
+    if (data === "\x7f") {
+      if (lineRef.current.length > 0) {
+        lineRef.current = lineRef.current.slice(0, -1);
+        ref.current?.write("\b \b");
+      }
+      return;
+    }
+    lineRef.current += data;
+    ref.current?.write(data);
+  };
+
+  return (
+    <div className="flex h-[360px] w-full flex-col gap-2">
+      <div className="min-h-0 flex-1">
+        <InteractiveTerminal
+          ref={ref}
+          aria-label="Demo interactive shell"
+          className="h-full w-full"
+          onData={handleData}
+        />
+      </div>
+      <p ref={lastCommandRef} className="text-caption text-muted-foreground" data-testid="status">
+        No command run yet.
+      </p>
+      <Button size="sm" variant="outline" className="self-start">
+        Next focusable control
+      </Button>
+    </div>
+  );
+}
+
+export const Default: Story = {
+  render: () => <EchoDemo />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const textarea = await waitForXtermTextarea(canvasElement);
+
+    // Type a command and press Enter — proves onData receives keystrokes and
+    // that write() renders the echoed ANSI response.
+    textarea.focus();
+    await userEvent.keyboard("hello{enter}");
+    await expect(canvas.getByTestId("status")).toHaveTextContent("Last command: “hello”");
+
+    // No keyboard trap (#285): Tab must move focus OFF the terminal onto the
+    // next control, not be swallowed as terminal input.
+    await userEvent.tab();
+    await expect(canvas.getByRole("button", { name: /next focusable control/i })).toHaveFocus();
+  },
+};
+
+/**
+ * `readOnly` degrades the terminal to the existing log use case: `write()`
+ * still renders ANSI output, but stdin is disabled and no `onData` fires.
+ */
+export const ReadOnly: Story = {
+  name: "Read-only (log)",
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`readOnly` disables stdin (xterm's `disableStdin`) — `write()` still renders, " +
+          "so this covers the same append-only log use case as `Terminal`, with real ANSI " +
+          "cursor/color handling.",
+      },
+    },
+  },
+  render: function ReadOnlyStory() {
+    const ref = useRef<InteractiveTerminalHandle>(null);
+
+    useEffect(() => {
+      ref.current?.write("$ pnpm build\r\n");
+      ref.current?.write(ANSI_PALETTE);
+      ref.current?.write("\x1b[32m✓\x1b[0m Build complete in 4.2s\r\n");
+    }, []);
+
+    return (
+      <div className="h-[280px] w-full">
+        <InteractiveTerminal ref={ref} aria-label="Build log" className="h-full w-full" readOnly />
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    await waitForXtermTextarea(canvasElement);
+  },
+};