@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/components/home/FeaturedLedger.tsx

@@ -0,0 +1,149 @@
+import { useClient } from "@ic-reactor/react"
+import { useSuspenseQueries, useSuspenseQuery } from "@tanstack/react-query"
+import { Link } from "@tanstack/react-router"
+import type { ReactElement, ReactNode } from "react"
+import { formatTokens, groupDigits } from "../../lib/format.ts"
+import type { RegistryEntry } from "../../lib/registry.ts"
+import { Badge } from "../Badge.tsx"
+import { SectionBoundary } from "../SectionBoundary.tsx"
+import { Skeleton } from "../Spinner.tsx"
+import { ledgerReads, minterReads } from "./featured.ts"
+
+// Bitcoin amounts on the minter are satoshis.
+const BTC_DECIMALS = 8
+
+/** Whole tokens, grouped: the fraction of a supply is noise on a card. */
+function wholeTokens(units: bigint, decimals: number): string {
+  return groupDigits(units / 10n ** BigInt(decimals))
+}
+
+/**
+ * A featured canister (the three ledgers and the ckBTC minter) on the home
+ * page, with live numbers. The numbers stream from the server (the loader
+ * started their reads), each card suspends on its own, and a card that
+ * fails says so without taking the page down.
+ */
+export function FeaturedLedger({
+  entry,
+}: {
+  entry: RegistryEntry
+}): ReactElement {
+  const isMinter = entry.kind === "ckbtc-minter"
+  return (
+    <article className="card home-featured">
+      <div className="card-body">
+        <div className="row row-between row-nowrap">
+          <h3 className="card-title">
+            <Link
+              to="/canister/$canisterId"
+              params={{ canisterId: entry.id }}
+              className="home-featured-link"
+            >
+              {entry.name}
+            </Link>
+          </h3>
+          <Badge
+            tone="accent"
+            title="Generated at build time from a committed .did"
+          >
+            Typed
+          </Badge>
+        </div>
+        <p className="text-sm muted">{entry.description}</p>
+        <SectionBoundary
+          label={`${entry.name} numbers`}
+          fallback={<StatsSkeleton rows={3} />}
+        >
+          {isMinter ? (
+            <MinterStats id={entry.id} />
+          ) : (
+            <LedgerStats id={entry.id} />
+          )}
+        </SectionBoundary>
+        <p className="mono subtle text-xs break-all">{entry.id}</p>
+      </div>
+    </article>
+  )
+}
+
+function LedgerStats({ id }: { id: string }): ReactElement {
+  const client = useClient()
+  const reads = ledgerReads(client, id)
+  // Together, not one `useSuspenseQuery` after another: a card the browser
+  // renders itself (its server read failed) would otherwise read the four
+  // one at a time, each waiting for the one before to resume it.
+  const [
+    { data: symbol },
+    { data: decimals },
+    { data: supply },
+    { data: fee },
+  ] = useSuspenseQueries({
+    queries: [reads.symbol, reads.decimals, reads.totalSupply, reads.fee],
+  })
+  return (
+    <Stats>
+      <Stat
+        label="Total supply"
+        value={`${wholeTokens(supply, decimals)} ${symbol}`}
+        title={formatTokens(supply, decimals, symbol)}
+      />
+      <Stat label="Transfer fee" value={formatTokens(fee, decimals, symbol)} />
+      <Stat label="Decimals" value={String(decimals)} />
+    </Stats>
+  )
+}
+
+function MinterStats({ id }: { id: string }): ReactElement {
+  const client = useClient()
+  const info = useSuspenseQuery(minterReads(client, id).info).data
+  return (
+    <Stats>
+      <Stat
+        label="Min. withdrawal"
+        value={formatTokens(info.retrieve_btc_min_amount, BTC_DECIMALS, "BTC")}
+      />
+      <Stat
+        label="Check fee"
+        value={formatTokens(info.kyt_fee, BTC_DECIMALS, "BTC")}
+      />
+      <Stat label="Confirmations" value={String(info.min_confirmations)} />
+    </Stats>
+  )
+}
+
+function Stats({ children }: { children: ReactNode }): ReactElement {
+  return <dl className="home-stats">{children}</dl>
+}
+
+function Stat({
+  label,
+  value,
+  title,
+}: {
+  label: string
+  value: string
+  title?: string
+}): ReactElement {
+  return (
+    <div className="home-stat">
+      <dt className="text-xs muted">{label}</dt>
+      <dd className="tabular home-stat-value" title={title}>
+        {value}
+      </dd>
+    </div>
+  )
+}
+
+function StatsSkeleton({ rows }: { rows: number }): ReactElement {
+  return (
+    <div className="home-stats" aria-busy="true">
+      <span className="sr-only">Loading live numbers</span>
+      {Array.from({ length: rows }, (_, i) => (
+        <div key={i} className="home-stat">
+          <Skeleton width="35%" height="0.75em" />
+          <Skeleton width="40%" height="0.9em" />
+        </div>
+      ))}
+    </div>
+  )
+}

package/examples/canister-studio/src/components/home/OpenCanister.tsx

@@ -0,0 +1,99 @@
+import { Link, useNavigate } from "@tanstack/react-router"
+import { useId, useRef, type FormEvent, type ReactElement } from "react"
+import { CURATED } from "../../lib/registry.ts"
+import { useCanisterIdInput } from "../canister-id-input.ts"
+
+/**
+ * "Open any canister": an id box that explains what is wrong with the text
+ * as it is typed (principal text first, then a canister id), and the curated
+ * list of mainnet canisters worth opening.
+ */
+export function OpenCanister(): ReactElement {
+  const navigate = useNavigate()
+  const field = useCanisterIdInput()
+  const input = useRef<HTMLInputElement>(null)
+  const ids = useId()
+
+  const submit = (event: FormEvent<HTMLFormElement>): void => {
+    event.preventDefault()
+    const id = field.attempt()
+    if (id === undefined) {
+      input.current?.focus()
+      return
+    }
+    void navigate({ to: "/canister/$canisterId", params: { canisterId: id } })
+  }
+
+  const verdict = field.verdict
+  return (
+    <section className="card home-open" aria-labelledby={`${ids}-title`}>
+      <div className="card-body">
+        <div className="stack-xs">
+          <h2 id={`${ids}-title`} className="section-title">
+            Open any canister
+          </h2>
+          <p className="text-sm muted">
+            The studio reads its certified{" "}
+            <code className="code-inline">candid:service</code> metadata,
+            compiles it on the server and builds a form for every method.
+          </p>
+        </div>
+        <form className="stack-sm" onSubmit={submit} noValidate>
+          <label htmlFor={`${ids}-input`} className="field-label">
+            Canister id
+          </label>
+          <div className="input-group">
+            <input
+              ref={input}
+              id={`${ids}-input`}
+              className="input mono"
+              type="text"
+              autoComplete="off"
+              autoCapitalize="off"
+              autoCorrect="off"
+              spellCheck={false}
+              placeholder="rrkah-fqaaa-aaaaa-aaaaq-cai"
+              value={field.text}
+              onChange={(event) => field.setText(event.target.value)}
+              aria-invalid={field.showProblem}
+              aria-describedby={`${ids}-hint`}
+            />
+            <button type="submit" className="btn btn-primary">
+              Open
+            </button>
+          </div>
+          <p
+            id={`${ids}-hint`}
+            className={field.showProblem ? "field-error" : "field-hint"}
+            aria-live="polite"
+          >
+            {field.showProblem && verdict.state === "invalid"
+              ? verdict.message
+              : verdict.state === "ok"
+                ? "A canister id: press Enter to open it."
+                : "Principal text of a canister: 27 characters, five groups."}
+          </p>
+        </form>
+        <div className="stack-sm">
+          <h3 className="text-sm muted home-curated-title">
+            Interesting mainnet canisters
+          </h3>
+          <ul className="list-plain home-curated">
+            {CURATED.map((canister) => (
+              <li key={canister.id}>
+                <Link
+                  to="/canister/$canisterId"
+                  params={{ canisterId: canister.id }}
+                  className="home-curated-item"
+                >
+                  <span className="home-curated-name">{canister.name}</span>
+                  <span className="text-xs muted">{canister.note}</span>
+                </Link>
+              </li>
+            ))}
+          </ul>
+        </div>
+      </div>
+    </section>
+  )
+}

package/examples/canister-studio/src/components/home/featured.test.tsx

@@ -0,0 +1,92 @@
+// @vitest-environment node
+// The home page's server render with one featured read that never answers:
+// the router's deadline must end the response (a bot gets nothing until the
+// whole page is ready) and leave that section to the browser.
+import { createTestClient } from "@ic-reactor/core/testing"
+import { ReactorProvider, useClient } from "@ic-reactor/react"
+import { useSuspenseQuery } from "@tanstack/react-query"
+import type { ReactElement } from "react"
+import { renderToReadableStream } from "react-dom/server"
+import { describe, expect, it } from "vitest"
+import {
+  actor as icrc1Actor,
+  type Actor as Ledger,
+} from "../../canisters/icrc1.ts"
+import { boundServerReads } from "../../router.tsx"
+import { SectionBoundary } from "../SectionBoundary.tsx"
+import { ledgerReads, startLedgerReads } from "./featured.ts"
+
+const LEDGER = "mxzaz-hqaaa-aaaar-qaada-cai"
+const DEADLINE_MS = 100
+
+function Supply(): ReactElement {
+  const client = useClient()
+  const supply = useSuspenseQuery(ledgerReads(client, LEDGER).totalSupply).data
+  return <p>supply {supply.toString()}</p>
+}
+
+function Symbol(): ReactElement {
+  const client = useClient()
+  const symbol = useSuspenseQuery(ledgerReads(client, LEDGER).symbol).data
+  return <p>symbol {symbol}</p>
+}
+
+async function readAll(stream: ReadableStream<Uint8Array>): Promise<string> {
+  const decoder = new TextDecoder()
+  let html = ""
+  for await (const chunk of stream)
+    html += decoder.decode(chunk, { stream: true })
+  return html + decoder.decode()
+}
+
+describe("a featured read that never answers on the server", () => {
+  it("is cancelled at the deadline, once, and its section is left to the browser", async () => {
+    const server = createTestClient({ network: "ic", signedIn: false })
+    server.mock<Ledger>(icrc1Actor, LEDGER, {
+      icrc1_symbol: () => "ckBTC",
+      icrc1_decimals: () => 8,
+      icrc1_fee: () => 10n,
+      icrc1_total_supply: () => new Promise<bigint>(() => undefined),
+    })
+    const { client } = server
+    const stop = boundServerReads(client.queryClient, DEADLINE_MS)
+    const errors: unknown[] = []
+    try {
+      startLedgerReads(client, client.queryClient, LEDGER)
+      const stream = await renderToReadableStream(
+        <ReactorProvider client={() => client}>
+          <SectionBoundary label="Supply" fallback={<p>loading supply</p>}>
+            <Supply />
+          </SectionBoundary>
+          <SectionBoundary label="Symbol" fallback={<p>loading symbol</p>}>
+            <Symbol />
+          </SectionBoundary>
+        </ReactorProvider>,
+        { onError: (error) => void errors.push(error) }
+      )
+      const html = await Promise.race([
+        readAll(stream),
+        new Promise<never>((_, reject) =>
+          setTimeout(
+            () => reject(new Error("the server render never ended")),
+            DEADLINE_MS * 30
+          )
+        ),
+      ])
+      // Rendered on the server: the read that answered.
+      expect(html).toContain("symbol <!-- -->ckBTC")
+      // Left to the browser: React marks the section to render there.
+      expect(html).not.toContain("supply 21")
+      expect(html).toContain("<!--$!-->")
+      expect(errors).toHaveLength(1)
+      // Cancelled where it stood, never started again by a re-render.
+      const supplyReads = server.requests.filter(
+        (r) => r.endpoint === "query" && r.methodName === "icrc1_total_supply"
+      )
+      expect(supplyReads).toHaveLength(1)
+    } finally {
+      stop()
+      client.dispose()
+    }
+  })
+})

package/examples/canister-studio/src/components/home/featured.ts

@@ -0,0 +1,64 @@
+import type { Client } from "@ic-reactor/core"
+import type { QueryClient } from "@tanstack/react-query"
+import {
+  actor as minterActor,
+  type Actor as MinterActor,
+} from "../../canisters/ckbtc_minter.ts"
+import {
+  actor as icrc1Actor,
+  type Actor as Icrc1Actor,
+} from "../../canisters/icrc1.ts"
+
+// The home page's reads, built the same way by the route's loader (to start
+// them on the server) and by the cards (to read them), so both use one key.
+//
+// Every ledger goes through the icrc1 module, the ICP ledger included: it is
+// an ICRC-1 ledger, and keys depend on the canister id and the argument
+// bytes only, so the canister page's own icp_ledger module reads the same
+// cache entries.
+
+export function ledgerReads(client: Client, id: string) {
+  const ledger = client.canister<Icrc1Actor>(icrc1Actor, { id })
+  return {
+    symbol: client.queryOptions(ledger, "icrc1_symbol"),
+    decimals: client.queryOptions(ledger, "icrc1_decimals"),
+    totalSupply: client.queryOptions(ledger, "icrc1_total_supply"),
+    fee: client.queryOptions(ledger, "icrc1_fee"),
+  }
+}
+
+export function minterReads(client: Client, id: string) {
+  const minter = client.canister<MinterActor>(minterActor, { id })
+  return { info: client.queryOptions(minter, "get_minter_info") }
+}
+
+// Starts a read without waiting for it, and never fails. On the server, a
+// read still in flight when the page renders streams in as it lands (its card
+// suspends). One that fails, or that the router cancels at its deadline
+// (SERVER_READ_DEADLINE_MS), is never sent: the browser renders that card,
+// reads again, and shows the real error only if its own read fails.
+const start = (pending: Promise<unknown>): void => {
+  pending.catch(() => undefined)
+}
+
+/** Starts the reads of a featured ledger's card (loader side). */
+export function startLedgerReads(
+  client: Client,
+  queryClient: QueryClient,
+  id: string
+): void {
+  const reads = ledgerReads(client, id)
+  start(queryClient.query(reads.symbol))
+  start(queryClient.query(reads.decimals))
+  start(queryClient.query(reads.totalSupply))
+  start(queryClient.query(reads.fee))
+}
+
+/** Starts the read of the featured minter's card (loader side). */
+export function startMinterReads(
+  client: Client,
+  queryClient: QueryClient,
+  id: string
+): void {
+  start(queryClient.query(minterReads(client, id).info))
+}

package/examples/canister-studio/src/components/interface/CandidTab.tsx

@@ -0,0 +1,38 @@
+import type { ReactElement } from "react"
+import type { CanisterInterface } from "../../interface/types.ts"
+import { Code } from "../Code.tsx"
+import { safeFileName } from "../download.ts"
+
+/** The canister's Candid, as the studio read it (server-rendered). */
+export function CandidTab({
+  iface,
+  did,
+}: {
+  iface: CanisterInterface
+  did: string
+}): ReactElement {
+  const source = iface.source
+  return (
+    <div className="stack">
+      <p className="text-sm muted">
+        {source.kind === "typed"
+          ? "The committed .did this canister’s typed module was generated from."
+          : source.kind === "metadata"
+            ? "The canister’s candid:service metadata, exactly as the certified read returned it."
+            : source.kind === "tmp_hack"
+              ? "What the canister’s __get_candid_interface_tmp_hack query answered. Not certified."
+              : "The pasted .did."}
+      </p>
+      <Code
+        text={did}
+        label="candid"
+        showSize
+        download={{
+          filename: `${safeFileName(iface.registry?.slug ?? iface.name)}.did`,
+        }}
+        maxHeight="70vh"
+        ariaLabel={`Candid interface of ${iface.name}`}
+      />
+    </div>
+  )
+}

package/examples/canister-studio/src/components/interface/CompatReport.tsx

@@ -0,0 +1,92 @@
+import type { CompatibilityReport } from "@meantjs/cli"
+import type { ReactElement } from "react"
+import { groupDigits } from "../../lib/format.ts"
+import { Badge } from "../Badge.tsx"
+import { Notice } from "../Notice.tsx"
+
+/**
+ * A compatibility check's result: whether the live interface is still a
+ * Candid subtype of the written one, each finding by method and path, and
+ * the interface identities (equal ids: unchanged).
+ */
+export function CompatReport({
+  report,
+  writtenLabel,
+  liveLabel,
+}: {
+  report: CompatibilityReport
+  writtenLabel: string
+  liveLabel: string
+}): ReactElement {
+  const unchanged = report.written.interface_id === report.live.interface_id
+  const errors = report.diagnostics.filter((d) => d.severity === "error")
+  const warnings = report.diagnostics.filter((d) => d.severity === "warning")
+  return (
+    <div className="stack">
+      {report.compatible ? (
+        <Notice tone="success" title={unchanged ? "Unchanged" : "Compatible"}>
+          <p>
+            {unchanged
+              ? `The ${liveLabel} is the ${writtenLabel}: the same interface id.`
+              : `The ${liveLabel} differs (it may have more methods), but every method of the ${writtenLabel} still exists with the same mode and compatible types. Calls written against it keep working.`}
+          </p>
+        </Notice>
+      ) : (
+        <Notice tone="danger" title="Not compatible">
+          <p>
+            {groupDigits(errors.length)}{" "}
+            {errors.length === 1 ? "finding breaks" : "findings break"} calls
+            written against the {writtenLabel}.
+          </p>
+        </Notice>
+      )}
+
+      <dl className="kv kv-compact">
+        <dt>{writtenLabel}</dt>
+        <dd className="mono break-all">{report.written.interface_id}</dd>
+        <dt>{liveLabel}</dt>
+        <dd className="mono break-all">{report.live.interface_id}</dd>
+      </dl>
+
+      {report.diagnostics.length > 0 && (
+        <div className="table-wrap">
+          <table className="table table-compact">
+            <caption className="sr-only">
+              Compatibility findings: {groupDigits(errors.length)} errors,{" "}
+              {groupDigits(warnings.length)} warnings
+            </caption>
+            <thead>
+              <tr>
+                <th scope="col">Severity</th>
+                <th scope="col">Method</th>
+                <th scope="col">Where</th>
+                <th scope="col">Finding</th>
+              </tr>
+            </thead>
+            <tbody>
+              {report.diagnostics.map((diagnostic, i) => (
+                <tr
+                  key={`${diagnostic.method ?? ""}-${diagnostic.path ?? ""}-${i}`}
+                >
+                  <td>
+                    <Badge
+                      tone={diagnostic.severity === "error" ? "err" : "warn"}
+                    >
+                      {diagnostic.severity}
+                    </Badge>
+                  </td>
+                  <td className="mono break-all">{diagnostic.method ?? ""}</td>
+                  <td className="mono break-all">{diagnostic.path ?? ""}</td>
+                  <td className="break-all">
+                    <span className="mono subtle">{diagnostic.code}</span>{" "}
+                    {diagnostic.message}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </div>
+  )
+}