@ic-reactor/mcp 0.0.0-stage → 0.0.0

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

@@ -0,0 +1,244 @@
+import type { MethodMode } from "@meantjs/schema"
+import { Link, useNavigate } from "@tanstack/react-router"
+import {
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type KeyboardEvent,
+  type ReactElement,
+} from "react"
+import { Segmented } from "../forms/fields/Segmented.tsx"
+import type { MethodInfo } from "../interface/types.ts"
+import { groupDigits } from "../lib/format.ts"
+import { Badge } from "./Badge.tsx"
+import { movesThisPage } from "./canister/workspace-key.ts"
+import { MODE_LABEL, MODE_ORDER } from "./modes.ts"
+
+export interface MethodListProps {
+  canisterId: string
+  methods: readonly MethodInfo[]
+  /** The selected method's name (`?method=`). */
+  selected?: string
+  /** Updates the registry offers as reads (`{ update: "idempotent" }`). */
+  idempotent?: readonly string[]
+  /** Kept in the links, so switching methods keeps the certified choice. */
+  certified?: boolean
+  /** Called as a method is picked in this page, before the page moves to it. */
+  onPick?(target: { method: string; certified?: boolean }): void
+}
+
+type ModeFilter = "all" | MethodMode
+
+const MODE_HEADING: Readonly<Record<MethodMode, string>> = {
+  query: "Queries",
+  composite_query: "Composite queries",
+  update: "Updates",
+  oneway: "Oneway",
+}
+
+/**
+ * The canister's methods, searchable, filterable by mode and grouped by it.
+ * One tab stop: arrow keys (and Home/End) move between methods, Enter in
+ * the search box opens the first match.
+ */
+export function MethodList({
+  canisterId,
+  methods,
+  selected,
+  idempotent = [],
+  certified,
+  onPick,
+}: MethodListProps): ReactElement {
+  const navigate = useNavigate()
+  const ids = useId()
+  const [query, setQuery] = useState("")
+  const [mode, setMode] = useState<ModeFilter>("all")
+  const listRef = useRef<HTMLDivElement>(null)
+
+  const presentModes = useMemo(
+    () => MODE_ORDER.filter((m) => methods.some((method) => method.mode === m)),
+    [methods]
+  )
+  const idempotentSet = useMemo(() => new Set(idempotent), [idempotent])
+
+  const needle = query.trim().toLowerCase()
+  const visible = methods.filter(
+    (method) =>
+      (mode === "all" || method.mode === mode) &&
+      (needle === "" || method.name.toLowerCase().includes(needle))
+  )
+  const groups = presentModes.flatMap((m) => {
+    const items = visible.filter((method) => method.mode === m)
+    return items.length === 0 ? [] : [{ mode: m, items }]
+  })
+  const ordered = groups.flatMap((group) => group.items)
+  // The one link reachable with Tab: the selected method, else the first.
+  const tabStop =
+    ordered.find((method) => method.name === selected)?.name ?? ordered[0]?.name
+
+  const links = (): HTMLAnchorElement[] =>
+    Array.from(
+      listRef.current?.querySelectorAll<HTMLAnchorElement>(
+        "a[data-method-link]"
+      ) ?? []
+    )
+
+  const moveFocus = (event: KeyboardEvent<HTMLDivElement>): void => {
+    const all = links()
+    if (all.length === 0) return
+    const index = all.findIndex((link) => link === document.activeElement)
+    let next: number | undefined
+    if (event.key === "ArrowDown") next = Math.min(index + 1, all.length - 1)
+    else if (event.key === "ArrowUp") next = Math.max(index - 1, 0)
+    else if (event.key === "Home") next = 0
+    else if (event.key === "End") next = all.length - 1
+    if (next === undefined) return
+    event.preventDefault()
+    all[next]?.focus()
+  }
+
+  // Picking a method keeps the page where it is (`resetScroll: false`): the
+  // workspace brings the method into view itself when it is not, as on a
+  // phone, where the list sits above it.
+  const open = (name: string): void => {
+    onPick?.({ method: name, certified })
+    void navigate({
+      to: "/canister/$canisterId",
+      params: { canisterId },
+      search: { method: name, certified },
+      resetScroll: false,
+    })
+  }
+
+  return (
+    <div className="method-list">
+      <div className="stack-sm method-list-controls">
+        <label htmlFor={`${ids}-search`} className="sr-only">
+          Search methods
+        </label>
+        <input
+          id={`${ids}-search`}
+          className="input"
+          type="search"
+          placeholder={`Search ${groupDigits(methods.length)} ${methods.length === 1 ? "method" : "methods"}`}
+          autoComplete="off"
+          spellCheck={false}
+          value={query}
+          onChange={(event) => setQuery(event.target.value)}
+          onKeyDown={(event) => {
+            const first = ordered[0]
+            if (event.key === "Enter" && first !== undefined) {
+              event.preventDefault()
+              open(first.name)
+            } else if (event.key === "ArrowDown") {
+              event.preventDefault()
+              links()[0]?.focus()
+            }
+          }}
+          aria-controls={`${ids}-list`}
+        />
+        {presentModes.length > 1 && (
+          <div className="method-list-modes">
+            <Segmented<ModeFilter>
+              label="Filter by mode"
+              options={[
+                { value: "all", label: "All" },
+                ...presentModes.map((m) => ({
+                  value: m,
+                  label: MODE_LABEL[m],
+                })),
+              ]}
+              value={mode}
+              onChange={setMode}
+            />
+          </div>
+        )}
+        <p className="sr-only" role="status" aria-live="polite">
+          {groupDigits(ordered.length)} of {groupDigits(methods.length)} methods
+          shown
+        </p>
+      </div>
+
+      <div
+        id={`${ids}-list`}
+        ref={listRef}
+        className="method-list-groups"
+        onKeyDown={moveFocus}
+      >
+        {groups.length === 0 && (
+          <p className="muted text-sm method-list-empty">
+            No method matches “{query.trim()}”.
+          </p>
+        )}
+        {groups.map((group) => (
+          <section
+            key={group.mode}
+            className="method-list-group"
+            aria-labelledby={`${ids}-${group.mode}`}
+          >
+            <h2 id={`${ids}-${group.mode}`} className="method-list-heading">
+              <span>{MODE_HEADING[group.mode]}</span>
+              <span className="subtle tabular">
+                {groupDigits(group.items.length)}
+              </span>
+            </h2>
+            <ul className="list-plain">
+              {group.items.map((method) => {
+                const isSelected = method.name === selected
+                const arity = `${method.args.length} ${method.args.length === 1 ? "argument" : "arguments"}, ${method.results.length} ${method.results.length === 1 ? "result" : "results"}`
+                return (
+                  <li key={method.name}>
+                    <Link
+                      to="/canister/$canisterId"
+                      params={{ canisterId }}
+                      search={{ method: method.name, certified }}
+                      resetScroll={false}
+                      onClick={(event) => {
+                        if (movesThisPage(event))
+                          onPick?.({ method: method.name, certified })
+                      }}
+                      className="method-list-item"
+                      data-method-link=""
+                      aria-current={isSelected ? "true" : undefined}
+                      tabIndex={method.name === tabStop ? 0 : -1}
+                      // The workspace's own page: never "active" by path.
+                      activeProps={{}}
+                    >
+                      {/* Cut to the column: the title shows a long name whole. */}
+                      <span
+                        className="mono truncate method-list-name"
+                        title={method.name}
+                      >
+                        {method.name}
+                      </span>
+                      <span className="row-sm row-nowrap shrink-0">
+                        {idempotentSet.has(method.name) && (
+                          <Badge
+                            tone="info"
+                            title="An update that changes nothing: offered as a read through { update: 'idempotent' }"
+                          >
+                            idempotent
+                          </Badge>
+                        )}
+                        {/* Read out as words, not "1 rightwards arrow 1". */}
+                        <span
+                          className="subtle text-xs tabular"
+                          title={arity}
+                          aria-hidden="true"
+                        >
+                          {method.args.length}→{method.results.length}
+                        </span>
+                        <span className="sr-only">, {arity}</span>
+                      </span>
+                    </Link>
+                  </li>
+                )
+              })}
+            </ul>
+          </section>
+        ))}
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,36 @@
+import type { ReactElement, ReactNode } from "react"
+
+export interface NoticeProps {
+  tone?: "neutral" | "info" | "warn" | "danger" | "success"
+  title?: ReactNode
+  /**
+   * `alert` interrupts a screen reader, `status` waits its turn. Defaults to
+   * `alert` for danger and `status` for the rest; `none` for static text.
+   */
+  role?: "alert" | "status" | "none"
+  className?: string
+  children?: ReactNode
+}
+
+/** A boxed message: an explanation, a warning, a failure. */
+export function Notice({
+  tone = "neutral",
+  title,
+  role,
+  className,
+  children,
+}: NoticeProps): ReactElement {
+  const resolvedRole = role ?? (tone === "danger" ? "alert" : "status")
+  const classes = ["notice"]
+  if (tone !== "neutral") classes.push(`notice-${tone}`)
+  if (className !== undefined) classes.push(className)
+  return (
+    <div
+      className={classes.join(" ")}
+      role={resolvedRole === "none" ? undefined : resolvedRole}
+    >
+      {title !== undefined && <p className="notice-title">{title}</p>}
+      {children}
+    </div>
+  )
+}

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

@@ -0,0 +1,44 @@
+import type { ReactElement } from "react"
+import type { InterfaceSource } from "../interface/types.ts"
+import { Badge } from "./Badge.tsx"
+import { provenanceText } from "./provenance.ts"
+
+/**
+ * Where an interface came from: Typed, Certified metadata, or an
+ * UNCERTIFIED fallback (labelled loudly, never hidden).
+ */
+export function ProvenanceBadge({
+  source,
+  size = "lg",
+}: {
+  source: InterfaceSource
+  size?: "md" | "lg"
+}): ReactElement {
+  const title = provenanceText(source)
+  switch (source.kind) {
+    case "typed":
+      return (
+        <Badge tone="accent" size={size} title={title} dot>
+          Typed
+        </Badge>
+      )
+    case "metadata":
+      return (
+        <Badge tone="certified" size={size} title={title} dot>
+          Certified metadata
+        </Badge>
+      )
+    case "tmp_hack":
+      return (
+        <Badge tone="err" size={size} title={title} dot>
+          UNCERTIFIED
+        </Badge>
+      )
+    case "pasted":
+      return (
+        <Badge tone="warn" size={size} title={title} dot>
+          Pasted .did
+        </Badge>
+      )
+  }
+}

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

@@ -0,0 +1,42 @@
+import {
+  Link,
+  useRouter,
+  type ErrorComponentProps,
+} from "@tanstack/react-router"
+import type { ReactElement } from "react"
+
+/**
+ * A route's `errorComponent`: the message, and a retry that reloads the
+ * route's loaders and resets the boundary. Only the message is shown: an
+ * error that crossed from the server is a plain `Error(message)` by then
+ * (the router's serializer keeps nothing else).
+ */
+export function RouteError({
+  error,
+  reset,
+  title = "Something went wrong",
+}: ErrorComponentProps & { title?: string }): ReactElement {
+  const router = useRouter()
+  const message = error instanceof Error ? error.message : String(error)
+  return (
+    <section className="empty-state" role="alert">
+      <h1>{title}</h1>
+      <pre className="code empty-state-detail">{message}</pre>
+      <div className="row">
+        <button
+          type="button"
+          className="btn btn-primary"
+          onClick={() => {
+            void router.invalidate()
+            reset()
+          }}
+        >
+          Try again
+        </button>
+        <Link to="/" className="btn">
+          Home
+        </Link>
+      </div>
+    </section>
+  )
+}

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

@@ -0,0 +1,76 @@
+import { QueryErrorResetBoundary } from "@tanstack/react-query"
+import { CatchBoundary } from "@tanstack/react-router"
+import { Suspense, type ReactElement, type ReactNode } from "react"
+
+export interface SectionBoundaryProps {
+  /** What failed, for the message: "ICP ledger stats". */
+  label: string
+  /** Shown while a `useSuspenseQuery` inside is loading (streamed on SSR). */
+  fallback: ReactNode
+  /** Remounts the boundary (and so retries) when it changes. */
+  resetKey?: unknown
+  children: ReactNode
+}
+
+/**
+ * A Suspense boundary with its own error boundary, so one failed read
+ * shows an inline message with a retry instead of failing the whole page.
+ *
+ * On the server, a read that fails inside, or that the router cancels at its
+ * deadline, leaves the section to the browser: React sends the fallback and
+ * renders the section there, where the read runs again (only successful
+ * reads are dehydrated). The error shows only if that read fails too, as the
+ * real ReactorError.
+ */
+export function SectionBoundary({
+  label,
+  fallback,
+  resetKey,
+  children,
+}: SectionBoundaryProps): ReactElement {
+  return (
+    <QueryErrorResetBoundary>
+      {({ reset: resetQueries }) => (
+        <CatchBoundary
+          getResetKey={() => resetKey}
+          errorComponent={({ error, reset }) => (
+            <SectionError
+              label={label}
+              error={error}
+              onRetry={() => {
+                // Lets the failed queries fetch again, then remounts.
+                resetQueries()
+                reset()
+              }}
+            />
+          )}
+        >
+          <Suspense fallback={fallback}>{children}</Suspense>
+        </CatchBoundary>
+      )}
+    </QueryErrorResetBoundary>
+  )
+}
+
+function SectionError({
+  label,
+  error,
+  onRetry,
+}: {
+  label: string
+  error: unknown
+  onRetry(): void
+}): ReactElement {
+  const message = error instanceof Error ? error.message : String(error)
+  return (
+    <div className="ui-section-error" role="alert">
+      <p className="text-sm">
+        <strong>{label} did not load.</strong>{" "}
+        <span className="muted break-all">{message}</span>
+      </p>
+      <button type="button" className="btn btn-sm" onClick={onRetry}>
+        Retry
+      </button>
+    </div>
+  )
+}

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

@@ -0,0 +1,33 @@
+import type { ReactElement } from "react"
+
+/** A spinner with a label for screen readers. */
+export function Spinner({
+  size = "md",
+  label = "Loading",
+}: {
+  size?: "sm" | "md"
+  label?: string
+}): ReactElement {
+  return (
+    <span className="row-sm row-nowrap" role="status">
+      <span
+        className={size === "sm" ? "spinner spinner-sm" : "spinner"}
+        aria-hidden="true"
+      />
+      <span className="sr-only">{label}</span>
+    </span>
+  )
+}
+
+/** A shimmering placeholder line, `width` as any CSS length. */
+export function Skeleton({
+  width = "100%",
+  height = "1em",
+}: {
+  width?: string
+  height?: string
+}): ReactElement {
+  return (
+    <span className="skeleton" style={{ width, height }} aria-hidden="true" />
+  )
+}

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

@@ -0,0 +1,96 @@
+import {
+  useId,
+  useRef,
+  type KeyboardEvent,
+  type ReactElement,
+  type ReactNode,
+} from "react"
+
+export interface TabItem<K extends string> {
+  key: K
+  label: ReactNode
+  /** Disabled tabs stay visible and say why (on hover). */
+  disabledReason?: string
+}
+
+export interface TabsProps<K extends string> {
+  tabs: readonly TabItem<K>[]
+  selected: K
+  onSelect(key: K): void
+  /** Names the tab list for screen readers. */
+  label: string
+  /** The selected tab's panel. */
+  children: ReactNode
+}
+
+/**
+ * WAI-ARIA tabs: one tab stop for the list, arrow keys (and Home/End) move
+ * between tabs and select them, the panel is labelled by its tab. Ids come
+ * from `useId`, so the server and the browser render the same markup.
+ */
+export function Tabs<K extends string>({
+  tabs,
+  selected,
+  onSelect,
+  label,
+  children,
+}: TabsProps<K>): ReactElement {
+  const base = useId()
+  const refs = useRef(new Map<K, HTMLButtonElement>())
+  const enabled = tabs.filter((tab) => tab.disabledReason === undefined)
+
+  const move = (event: KeyboardEvent<HTMLDivElement>): void => {
+    const index = enabled.findIndex((tab) => tab.key === selected)
+    let next: number | undefined
+    if (event.key === "ArrowRight") next = (index + 1) % enabled.length
+    else if (event.key === "ArrowLeft")
+      next = (index - 1 + enabled.length) % enabled.length
+    else if (event.key === "Home") next = 0
+    else if (event.key === "End") next = enabled.length - 1
+    const target = next === undefined ? undefined : enabled[next]
+    if (target === undefined) return
+    event.preventDefault()
+    onSelect(target.key)
+    refs.current.get(target.key)?.focus()
+  }
+
+  return (
+    <div className="ui-tabs">
+      <div className="tabs" role="tablist" aria-label={label} onKeyDown={move}>
+        {tabs.map((tab) => {
+          const isSelected = tab.key === selected
+          return (
+            <button
+              key={tab.key}
+              ref={(node) => {
+                if (node === null) refs.current.delete(tab.key)
+                else refs.current.set(tab.key, node)
+              }}
+              type="button"
+              role="tab"
+              className="tab"
+              id={`${base}-tab-${tab.key}`}
+              aria-selected={isSelected}
+              aria-controls={`${base}-panel`}
+              tabIndex={isSelected ? 0 : -1}
+              disabled={tab.disabledReason !== undefined}
+              title={tab.disabledReason}
+              onClick={() => onSelect(tab.key)}
+            >
+              {tab.label}
+            </button>
+          )
+        })}
+      </div>
+      <div
+        className="tab-panel"
+        role="tabpanel"
+        id={`${base}-panel`}
+        aria-labelledby={`${base}-tab-${selected}`}
+        tabIndex={0}
+      >
+        {children}
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,56 @@
+// What the page says when an interface did not load: the reason it names
+// must be the one that applies.
+import {
+  createMemoryHistory,
+  createRootRoute,
+  createRouter,
+  RouterProvider,
+} from "@tanstack/react-router"
+import { cleanup, render, screen } from "@testing-library/react"
+import { afterEach, describe, expect, it } from "vitest"
+import type { InterfacePayload } from "../../interface/types.ts"
+import { CanisterLoadFailure } from "./CanisterLoadFailure.tsx"
+
+afterEach(cleanup)
+
+type Failed = Extract<InterfacePayload, { ok: false }>
+
+async function renderFailure(payload: Omit<Failed, "ok" | "canisterId">) {
+  const failed: Failed = {
+    ok: false,
+    canisterId: "qoctq-giaaa-aaaaa-aaaea-cai",
+    ...payload,
+  }
+  const router = createRouter({
+    routeTree: createRootRoute({
+      component: () => <CanisterLoadFailure payload={failed} />,
+    }),
+    history: createMemoryHistory({ initialEntries: ["/"] }),
+  })
+  await router.load()
+  render(<RouterProvider router={router} />)
+}
+
+describe("CanisterLoadFailure", () => {
+  it("names the method cap as well as the size cap for an interface too large", async () => {
+    await renderFailure({
+      code: "too_large",
+      message: "The interface has 1204 methods; the studio loads at most 1000.",
+    })
+    await screen.findByText("The interface is too large")
+    const text = document.body.textContent ?? ""
+    expect(text).toContain("1,000 methods")
+    expect(text).not.toMatch(/up to 256 KiB on its server; this one is larger/)
+  })
+
+  it("never promises a cached second read after a compile ran past its deadline", async () => {
+    await renderFailure({
+      code: "timeout",
+      message: "The compile took longer than 2 s, so the server stopped it.",
+    })
+    await screen.findByText("Loading the interface took too long")
+    const text = document.body.textContent ?? ""
+    expect(text).not.toMatch(/usually cached/)
+    expect(text).toContain("refused for a short while")
+  })
+})