@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/components/CanisterJump.tsx

@@ -0,0 +1,130 @@
+import { useNavigate } from "@tanstack/react-router"
+import {
+  useEffect,
+  useId,
+  useRef,
+  type FormEvent,
+  type ReactElement,
+} from "react"
+import { useCanisterIdInput } from "./canister-id-input.ts"
+import { KNOWN_CANISTERS } from "../lib/registry.ts"
+
+/**
+ * The header's "go to canister" box. Validates the id before navigating
+ * (the route validates it again), suggests known canisters, and takes focus
+ * on "/" from anywhere outside a text field.
+ */
+export function CanisterJump(): ReactElement {
+  const navigate = useNavigate()
+  const field = useCanisterIdInput()
+  const input = useRef<HTMLInputElement>(null)
+  const ids = useId()
+  const listId = `${ids}-known`
+  const problemId = `${ids}-problem`
+
+  useEffect(() => {
+    const onKey = (event: KeyboardEvent): void => {
+      if (event.key !== "/" || event.metaKey || event.ctrlKey || event.altKey)
+        return
+      const target = event.target
+      if (
+        target instanceof HTMLElement &&
+        (target.isContentEditable ||
+          target.closest("input, textarea, select") !== null)
+      )
+        return
+      event.preventDefault()
+      input.current?.focus()
+    }
+    window.addEventListener("keydown", onKey)
+    return () => window.removeEventListener("keydown", onKey)
+  }, [])
+
+  const submit = (event: FormEvent<HTMLFormElement>): void => {
+    event.preventDefault()
+    const id = field.attempt()
+    if (id === undefined) {
+      input.current?.focus()
+      return
+    }
+    field.reset()
+    input.current?.blur()
+    void navigate({ to: "/canister/$canisterId", params: { canisterId: id } })
+  }
+
+  return (
+    <form
+      className="canister-jump"
+      role="search"
+      aria-label="Open a canister"
+      onSubmit={submit}
+    >
+      <label htmlFor={`${ids}-input`} className="sr-only">
+        Canister id
+      </label>
+      <div className="canister-jump-field">
+        <SearchIcon />
+        <input
+          ref={input}
+          id={`${ids}-input`}
+          className="input mono canister-jump-input"
+          type="text"
+          inputMode="text"
+          autoComplete="off"
+          autoCapitalize="off"
+          autoCorrect="off"
+          spellCheck={false}
+          placeholder="Canister id…"
+          list={listId}
+          value={field.text}
+          onChange={(event) => field.setText(event.target.value)}
+          aria-invalid={field.showProblem}
+          aria-describedby={field.showProblem ? problemId : undefined}
+        />
+        <kbd className="kbd canister-jump-kbd" aria-hidden="true">
+          /
+        </kbd>
+      </div>
+      <datalist id={listId}>
+        {KNOWN_CANISTERS.map((known) => (
+          <option key={known.id} value={known.id}>
+            {known.name}
+          </option>
+        ))}
+      </datalist>
+      {field.showProblem && field.verdict.state === "invalid" && (
+        <p id={problemId} className="canister-jump-problem" role="alert">
+          {field.verdict.message}
+        </p>
+      )}
+    </form>
+  )
+}
+
+function SearchIcon(): ReactElement {
+  return (
+    <svg
+      className="canister-jump-icon"
+      viewBox="0 0 16 16"
+      width="14"
+      height="14"
+      aria-hidden="true"
+      focusable="false"
+    >
+      <circle
+        cx="7"
+        cy="7"
+        r="4.5"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.5"
+      />
+      <path
+        d="m10.5 10.5 3 3"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+      />
+    </svg>
+  )
+}

package/examples/canister-studio/src/components/Card.tsx

@@ -0,0 +1,64 @@
+import type { ReactElement, ReactNode } from "react"
+
+export interface CardProps {
+  /** Heading text; with `actions` it forms the card header. */
+  title?: ReactNode
+  subtitle?: ReactNode
+  /** Controls at the right of the header. */
+  actions?: ReactNode
+  footer?: ReactNode
+  /** A recessed card (nested panels, previews). */
+  inset?: boolean
+  /** The heading level of `title`, so a page keeps its outline. */
+  headingLevel?: 2 | 3 | 4
+  className?: string
+  /** Labels the card as a region when it has a title. */
+  id?: string
+  children?: ReactNode
+}
+
+/** The design system's card: optional header, body and footer. */
+export function Card({
+  title,
+  subtitle,
+  actions,
+  footer,
+  inset = false,
+  headingLevel = 3,
+  className,
+  id,
+  children,
+}: CardProps): ReactElement {
+  const Heading = `h${headingLevel}` as const
+  const headingId = id === undefined ? undefined : `${id}-title`
+  const classes = ["card"]
+  if (inset) classes.push("card-inset")
+  if (className !== undefined) classes.push(className)
+  const hasHeader =
+    title !== undefined || subtitle !== undefined || actions !== undefined
+  return (
+    <section
+      className={classes.join(" ")}
+      id={id}
+      aria-labelledby={title === undefined ? undefined : headingId}
+    >
+      {hasHeader && (
+        <div className="card-header">
+          <div className="stack-xs grow">
+            {title !== undefined && (
+              <Heading className="card-title" id={headingId}>
+                {title}
+              </Heading>
+            )}
+            {subtitle !== undefined && (
+              <p className="card-subtitle">{subtitle}</p>
+            )}
+          </div>
+          {actions !== undefined && <div className="row">{actions}</div>}
+        </div>
+      )}
+      {children !== undefined && <div className="card-body">{children}</div>}
+      {footer !== undefined && <div className="card-footer">{footer}</div>}
+    </section>
+  )
+}

package/examples/canister-studio/src/components/Code.tsx

@@ -0,0 +1,101 @@
+import type { ReactElement, ReactNode } from "react"
+import { formatByteSize } from "../lib/format.ts"
+import { CopyButton } from "./CopyButton.tsx"
+import { downloadText } from "./download.ts"
+
+export interface CodeProps {
+  /** The text, rendered as text (never as HTML). */
+  text: string
+  /** A label above the block ("candid", "typescript"). */
+  label?: ReactNode
+  /** Shows the UTF-8 size next to the label. */
+  showSize?: boolean
+  copy?: boolean
+  /** Offers a download of exactly `text`. */
+  download?: { filename: string; type?: string }
+  /** Wrap long lines instead of scrolling sideways. */
+  wrap?: boolean
+  /** A CSS length; the block scrolls past it. */
+  maxHeight?: string
+  /** Accessible name of the block, for long code a reader can skip. */
+  ariaLabel?: string
+}
+
+const encoder = new TextEncoder()
+
+/** A code block with an optional toolbar: label, size, copy, download. */
+export function Code({
+  text,
+  label,
+  showSize = false,
+  copy = true,
+  download,
+  wrap = false,
+  maxHeight,
+  ariaLabel,
+}: CodeProps): ReactElement {
+  const hasToolbar =
+    label !== undefined || showSize || copy || download !== undefined
+  return (
+    <div className="ui-code">
+      {hasToolbar && (
+        <div className="ui-code-toolbar">
+          <span className="row-sm">
+            {label !== undefined && (
+              <span className="ui-code-label">{label}</span>
+            )}
+            {showSize && (
+              <span className="subtle text-xs tabular">
+                {formatByteSize(encoder.encode(text).length)}
+              </span>
+            )}
+          </span>
+          <span className="row-sm">
+            {copy && <CopyButton text={text} />}
+            {download !== undefined && (
+              <button
+                type="button"
+                className="btn btn-ghost btn-sm"
+                onClick={() =>
+                  downloadText(download.filename, text, download.type)
+                }
+              >
+                <DownloadIcon />
+                <span>Download</span>
+              </button>
+            )}
+          </span>
+        </div>
+      )}
+      <pre
+        className={wrap ? "code code-wrap" : "code"}
+        style={maxHeight === undefined ? undefined : { maxHeight }}
+        tabIndex={0}
+        aria-label={ariaLabel}
+      >
+        {text}
+      </pre>
+    </div>
+  )
+}
+
+function DownloadIcon(): ReactElement {
+  return (
+    <svg
+      viewBox="0 0 16 16"
+      width="14"
+      height="14"
+      aria-hidden="true"
+      focusable="false"
+    >
+      <path
+        d="M8 2.5v8m0 0 3-3m-3 3-3-3M3 13.5h10"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}

package/examples/canister-studio/src/components/CopyButton.tsx

@@ -0,0 +1,126 @@
+import { useEffect, useRef, useState, type ReactElement } from "react"
+
+export interface CopyButtonProps {
+  /** The exact text put on the clipboard, or a function computing it on click (large values). */
+  text: string | (() => string)
+  /** Visible label; with `iconOnly` it becomes the accessible name. */
+  label?: string
+  /** The accessible name when the visible label alone is too short ("Copy principal"). */
+  a11yLabel?: string
+  iconOnly?: boolean
+  size?: "sm" | "md"
+  className?: string
+}
+
+type CopyState = "idle" | "copied" | "failed"
+
+const RESET_AFTER_MS = 1600
+
+/**
+ * Copies `text` to the clipboard and says so for a moment. The result is
+ * announced politely to screen readers.
+ */
+export function CopyButton({
+  text,
+  label = "Copy",
+  a11yLabel,
+  iconOnly = false,
+  size = "sm",
+  className,
+}: CopyButtonProps): ReactElement {
+  const [state, setState] = useState<CopyState>("idle")
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+
+  useEffect(() => () => clearTimeout(timer.current), [])
+
+  const copy = async (): Promise<void> => {
+    clearTimeout(timer.current)
+    try {
+      await navigator.clipboard.writeText(
+        typeof text === "function" ? text() : text
+      )
+      setState("copied")
+    } catch {
+      // No clipboard permission (an insecure origin, a denied prompt).
+      setState("failed")
+    }
+    timer.current = setTimeout(() => setState("idle"), RESET_AFTER_MS)
+  }
+
+  const classes = ["btn", "btn-ghost"]
+  if (size === "sm") classes.push("btn-sm")
+  if (iconOnly) classes.push("btn-icon")
+  if (className !== undefined) classes.push(className)
+  const status =
+    state === "copied" ? "Copied" : state === "failed" ? "Copy failed" : ""
+  const name = iconOnly ? label : a11yLabel
+
+  return (
+    <>
+      <button
+        type="button"
+        className={classes.join(" ")}
+        onClick={() => void copy()}
+        aria-label={name}
+        title={name}
+      >
+        {state === "copied" ? <CheckIcon /> : <CopyIcon />}
+        {!iconOnly && <span>{state === "idle" ? label : status}</span>}
+      </button>
+      <span className="sr-only" role="status" aria-live="polite">
+        {status}
+      </span>
+    </>
+  )
+}
+
+function CopyIcon(): ReactElement {
+  return (
+    <svg
+      viewBox="0 0 16 16"
+      width="14"
+      height="14"
+      aria-hidden="true"
+      focusable="false"
+    >
+      <rect
+        x="5"
+        y="5"
+        width="8.5"
+        height="8.5"
+        rx="1.5"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.4"
+      />
+      <path
+        d="M10.5 3.2V3a1.5 1.5 0 0 0-1.5-1.5H3.5A1.5 1.5 0 0 0 2 3v5.5A1.5 1.5 0 0 0 3.5 10h.3"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.4"
+        strokeLinecap="round"
+      />
+    </svg>
+  )
+}
+
+function CheckIcon(): ReactElement {
+  return (
+    <svg
+      viewBox="0 0 16 16"
+      width="14"
+      height="14"
+      aria-hidden="true"
+      focusable="false"
+    >
+      <path
+        d="m3.5 8.5 3 3 6-7"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.6"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}

package/examples/canister-studio/src/components/Disclosure.tsx

@@ -0,0 +1,34 @@
+import type { ReactElement, ReactNode } from "react"
+
+export interface DisclosureProps {
+  summary: ReactNode
+  /** Text after the summary, muted (a count, a size). */
+  meta?: ReactNode
+  defaultOpen?: boolean
+  className?: string
+  children: ReactNode
+}
+
+/** A native `<details>`: keyboard and screen-reader support for free. */
+export function Disclosure({
+  summary,
+  meta,
+  defaultOpen = false,
+  className,
+  children,
+}: DisclosureProps): ReactElement {
+  return (
+    <details
+      className={
+        className === undefined ? "disclosure" : `disclosure ${className}`
+      }
+      open={defaultOpen}
+    >
+      <summary>
+        <span className="grow">{summary}</span>
+        {meta !== undefined && <span className="muted text-xs">{meta}</span>}
+      </summary>
+      <div className="disclosure-body">{children}</div>
+    </details>
+  )
+}

package/examples/canister-studio/src/components/EmptyState.tsx

@@ -0,0 +1,34 @@
+import type { ReactElement, ReactNode } from "react"
+
+export interface EmptyStateProps {
+  /** A short code above the title ("404"). */
+  code?: string
+  title: ReactNode
+  children?: ReactNode
+  actions?: ReactNode
+  /** `h1` on a page of its own (not found), `h2` inside a page. */
+  headingLevel?: 1 | 2 | 3
+  role?: "alert" | "status"
+}
+
+/** A centered, dashed panel for "nothing here (yet)" and "not found". */
+export function EmptyState({
+  code,
+  title,
+  children,
+  actions,
+  headingLevel = 2,
+  role,
+}: EmptyStateProps): ReactElement {
+  const Heading = `h${headingLevel}` as const
+  return (
+    <section className="empty-state" role={role}>
+      {code !== undefined && <p className="empty-state-code mono">{code}</p>}
+      <Heading>{title}</Heading>
+      {children !== undefined && (
+        <div className="muted stack-sm">{children}</div>
+      )}
+      {actions !== undefined && <div className="row">{actions}</div>}
+    </section>
+  )
+}

package/examples/canister-studio/src/components/MethodList.test.tsx

@@ -0,0 +1,137 @@
+import {
+  createMemoryHistory,
+  createRootRoute,
+  createRouter,
+  RouterProvider,
+} from "@tanstack/react-router"
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  within,
+} from "@testing-library/react"
+import type { ReactElement } from "react"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { CKBTC_LEDGER, typedInterface } from "../calls/testing/fixtures.ts"
+import type { MethodInfo } from "../interface/types.ts"
+import { MethodList } from "./MethodList.tsx"
+
+const ledger = typedInterface(CKBTC_LEDGER)
+
+afterEach(() => {
+  cleanup()
+  vi.restoreAllMocks()
+})
+
+/** Renders `ui` in a router that restores scroll, as the app's does. */
+async function renderInApp(ui: ReactElement) {
+  const router = createRouter({
+    routeTree: createRootRoute({ component: () => ui }),
+    history: createMemoryHistory({ initialEntries: ["/"] }),
+    scrollRestoration: true,
+  })
+  await router.load()
+  render(<RouterProvider router={router} />)
+  return router
+}
+
+describe("MethodList", () => {
+  it("filters by mode as a radio group: one tab stop, arrow keys move the choice", async () => {
+    await renderInApp(
+      <MethodList canisterId={CKBTC_LEDGER} methods={ledger.methods} />
+    )
+    const group = screen.getByRole("radiogroup", { name: "Filter by mode" })
+    const [all, query, update] = within(group).getAllByRole("radio")
+    if (all === undefined || query === undefined || update === undefined) {
+      throw new Error("expected All, query and update")
+    }
+    expect([all.tabIndex, query.tabIndex, update.tabIndex]).toEqual([0, -1, -1])
+    act(() => all.focus())
+    fireEvent.keyDown(all, { key: "ArrowRight" })
+    expect(query.getAttribute("aria-checked")).toBe("true")
+    expect(document.activeElement).toBe(query)
+    expect(query.tabIndex).toBe(0)
+    // Only queries are listed now.
+    expect(screen.queryByRole("link", { name: /icrc1_transfer/ })).toBeNull()
+    expect(screen.getByRole("link", { name: /icrc1_symbol/ })).toBeTruthy()
+  })
+
+  it("says how many methods it searches, in the singular for one", async () => {
+    const one = ledger.methods.filter((m) => m.name === "icrc1_symbol")
+    await renderInApp(<MethodList canisterId={CKBTC_LEDGER} methods={one} />)
+    expect(screen.getByRole("searchbox").getAttribute("placeholder")).toBe(
+      "Search 1 method"
+    )
+  })
+
+  it("names each method whole, and its arity in words", async () => {
+    const long: MethodInfo = {
+      name: "get_most_recent_monthly_node_provider_rewards",
+      mode: "query",
+      args: [],
+      results: ledger.method("icrc1_symbol")?.results ?? [],
+    }
+    await renderInApp(<MethodList canisterId={CKBTC_LEDGER} methods={[long]} />)
+    const link = screen.getByRole("link", {
+      name: "get_most_recent_monthly_node_provider_rewards, 0 arguments, 1 result",
+    })
+    // Cut to the column on screen: the title shows the whole name.
+    expect(within(link).getByTitle(long.name).textContent).toBe(long.name)
+  })
+
+  it("keeps the page where it is when a method is picked, and says it was picked", async () => {
+    const scrollTo = vi.spyOn(window, "scrollTo").mockImplementation(() => {})
+    const onPick = vi.fn()
+    const router = await renderInApp(
+      <MethodList
+        canisterId={CKBTC_LEDGER}
+        methods={ledger.methods}
+        onPick={onPick}
+      />
+    )
+    scrollTo.mockClear()
+    fireEvent.click(screen.getByRole("link", { name: /^icrc1_fee/ }))
+    await vi.waitFor(() => {
+      expect(router.state.location.search).toEqual({ method: "icrc1_fee" })
+    })
+    expect(onPick).toHaveBeenCalledTimes(1)
+    expect(onPick).toHaveBeenLastCalledWith({
+      method: "icrc1_fee",
+      certified: undefined,
+    })
+    expect(scrollTo).not.toHaveBeenCalled()
+
+    // Enter in the search box opens the first match the same way.
+    const search = screen.getByRole("searchbox")
+    fireEvent.change(search, { target: { value: "symbol" } })
+    fireEvent.keyDown(search, { key: "Enter" })
+    await vi.waitFor(() => {
+      expect(router.state.location.search).toEqual({ method: "icrc1_symbol" })
+    })
+    expect(onPick).toHaveBeenCalledTimes(2)
+    expect(scrollTo).not.toHaveBeenCalled()
+  })
+
+  it("says nothing was picked here when a click opens the method in another tab", async () => {
+    const onPick = vi.fn()
+    await renderInApp(
+      <MethodList
+        canisterId={CKBTC_LEDGER}
+        methods={ledger.methods}
+        onPick={onPick}
+      />
+    )
+    const link = screen.getByRole("link", { name: /^icrc1_fee/ })
+    for (const init of [
+      { ctrlKey: true },
+      { metaKey: true },
+      { shiftKey: true },
+      { button: 1 },
+    ]) {
+      fireEvent.click(link, init)
+    }
+    expect(onPick).not.toHaveBeenCalled()
+  })
+})