@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/forms/MethodForm.tsx

@@ -0,0 +1,368 @@
+import {
+  useDeferredValue,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type FormEvent,
+  type JSX,
+  type Ref,
+} from "react"
+import type { MethodInfo } from "../interface/types.ts"
+import { formatByteSize } from "../lib/format.ts"
+import { KNOWN_CANISTERS } from "../lib/registry.ts"
+import { FormContext, type FormContextValue } from "./context.ts"
+import {
+  argLabel,
+  argPath,
+  checkCall,
+  isAtOrBelow,
+  issuesByPath,
+  pathLabel,
+  resolve,
+  type CallCheck,
+  type Draft,
+  type FieldIssue,
+} from "./engine.ts"
+import { Field } from "./fields/Field.tsx"
+import type { HintResolver } from "./hints.ts"
+import { JsonPanel } from "./JsonPanel.tsx"
+import { useMethodForm } from "./useMethodForm.ts"
+
+export interface MethodFormProps {
+  /**
+   * The method, with the .did's argument names where the interface knows
+   * them (`acknowledge_entries : (sequence_number : nat)`): they label the
+   * arguments; unnamed ones read "argument 1", "argument 2".
+   */
+  method: MethodInfo & { readonly argNames?: readonly (string | undefined)[] }
+  hints?: HintResolver
+  /** Prefill: history, a shared link, typed defaults. */
+  initialValues?: readonly unknown[]
+  submitLabel: string
+  /** Set to disable submitting, with the reason shown. */
+  disabledReason?: string
+  busy?: boolean
+  /** Issues from the last call (`issuesFromReactorError`). */
+  externalIssues?: readonly FieldIssue[]
+  onSubmit(call: { values: unknown[]; vars: unknown; bytes: Uint8Array }): void
+  onChange?(check: CallCheck): void
+  /** Offers "Use mine" on principal fields. */
+  callerPrincipal?: string
+  /**
+   * The submit button, for a parent that must hand the focus back to it
+   * (after a confirm step it opened is cancelled or sent).
+   */
+  submitRef?: Ref<HTMLButtonElement>
+}
+
+/** Issues listed in the summary after a failed submit, at most. */
+const SUMMARY_LIMIT = 8
+
+/**
+ * A DOM id for a path, unique within the form: every character outside
+ * [A-Za-z0-9] is escaped, so two paths never share an id.
+ */
+const pathSlug = (path: string): string =>
+  path.replace(/[^A-Za-z0-9]/g, (ch) => `-${ch.codePointAt(0)?.toString(16)}-`)
+
+const issueKey = (issues: readonly FieldIssue[] | undefined): string =>
+  (issues ?? [])
+    .map((i) => `${i.path}\u0000${i.code}\u0000${i.message}`)
+    .join("\u0001")
+
+/** The path one step up: `$args[0].to.owner` → `$args[0].to`. */
+function parentPath(path: string): string | undefined {
+  const match =
+    /^(.*?)(\.[A-Za-z_$][A-Za-z0-9_$]*|\[\d+\]|\["(?:[^"\\]|\\.)*"\])$/.exec(
+      path
+    )
+  return match?.[1] === undefined || match[1] === "$" ? undefined : match[1]
+}
+
+const FOCUSABLE = "input:not([type=hidden]), select, textarea, button"
+
+/**
+ * An automatic form for every argument of a method: one editor per Candid
+ * type, issues on the codec's paths (shown once a field is touched, or all of
+ * them after a submit attempt), and a submit that hands over the exact values,
+ * `vars` and Candid bytes it checked.
+ */
+export function MethodForm(props: MethodFormProps): JSX.Element {
+  const {
+    method,
+    hints,
+    initialValues,
+    submitLabel,
+    disabledReason,
+    busy = false,
+    externalIssues,
+    onSubmit,
+    onChange,
+    callerPrincipal,
+    submitRef,
+  } = props
+  const baseId = useId()
+  const form = useMethodForm(method, initialValues, hints)
+  const { state } = form
+  const args = method.args
+  const argCount = args.length
+  const names = method.argNames
+
+  // Typing in a big argument stays responsive: the check runs on a deferred
+  // copy (drafts and their schemas together), and submit re-checks the
+  // current drafts.
+  const deferred = useDeferredValue(state)
+  const check = useMemo(
+    () => checkCall(deferred.args, deferred.drafts),
+    [deferred.args, deferred.drafts]
+  )
+  const issues = useMemo(() => issuesByPath(check.issues), [check])
+
+  // The last call's issues show until the next edit, or until new ones come.
+  const externalKey = issueKey(externalIssues)
+  const [dismissedKey, setDismissedKey] = useState<string>()
+  const lastCall: readonly FieldIssue[] =
+    externalKey !== "" && externalKey !== dismissedKey
+      ? (externalIssues ?? [])
+      : []
+  const external = issuesByPath(lastCall)
+  const edit = (index: number, draft: Draft) => {
+    if (lastCall.length > 0) setDismissedKey(externalKey)
+    form.setArg(index, draft)
+  }
+
+  const onChangeRef = useRef(onChange)
+  useEffect(() => {
+    onChangeRef.current = onChange
+  })
+  useEffect(() => {
+    onChangeRef.current?.(check)
+  }, [check])
+
+  const idFor = (path: string) => `${baseId}${pathSlug(path)}`
+  const datalistId = `${baseId}-canisters`
+
+  const focusField = (path: string) => {
+    for (let p: string | undefined = path; p !== undefined; p = parentPath(p)) {
+      const el = document.getElementById(idFor(p))
+      const target = el?.matches(FOCUSABLE)
+        ? el
+        : el?.querySelector<HTMLElement>(FOCUSABLE)
+      if (target) {
+        target.focus()
+        return
+      }
+    }
+  }
+  useEffect(() => {
+    if (state.focusPath === undefined) return
+    focusField(state.focusPath)
+    form.focused()
+  })
+
+  const context: FormContextValue = {
+    idFor,
+    hint: ({ path, key, schema }) =>
+      hints?.({ path, key, schema, method: method.name }),
+    issuesAt(path) {
+      const own =
+        state.showAll || state.touched.has(path) ? (issues.get(path) ?? []) : []
+      const last = external.get(path) ?? []
+      return last.length === 0 ? own : [...own, ...last]
+    },
+    hasIssueBelow(path) {
+      for (const key of issues.keys())
+        if (isAtOrBelow(key, path) && (state.showAll || state.touched.has(key)))
+          return true
+      for (const key of external.keys()) if (isAtOrBelow(key, path)) return true
+      return false
+    },
+    lastItemWithIssue(path) {
+      let last = -1
+      const see = (key: string) => {
+        const index =
+          key.startsWith(path) && /^\[(\d+)\]/.exec(key.slice(path.length))
+        if (index) last = Math.max(last, Number(index[1]))
+      }
+      for (const key of issues.keys())
+        if (state.showAll || state.touched.has(key)) see(key)
+      for (const key of external.keys()) see(key)
+      return last
+    },
+    touch: form.touch,
+    showAll: state.showAll,
+    callerPrincipal,
+    datalistId,
+    isAutoNow: form.isAutoNow,
+    setAutoNow: form.setAutoNow,
+  }
+
+  const blocked =
+    busy || disabledReason !== undefined || check.uninhabited === true
+  // The button is aria-disabled, never disabled: a disabled button that has
+  // the focus (Enter on "Run query") drops it to the page.
+  const submitButton = useRef<HTMLButtonElement | null>(null)
+  const fields = useRef<HTMLFieldSetElement>(null)
+  const setSubmitButton = (el: HTMLButtonElement | null) => {
+    submitButton.current = el
+    if (typeof submitRef === "function") submitRef(el)
+    else if (submitRef) submitRef.current = el
+  }
+
+  const first = check.issues[0]
+  const reason =
+    disabledReason ??
+    (check.uninhabited === true
+      ? "This method cannot be called: an argument's type has no values."
+      : first !== undefined
+        ? `${pathLabel(first.path, argCount, names)}: ${first.message}${
+            check.issues.length > 1
+              ? ` (and ${check.issues.length - 1} more)`
+              : ""
+          }`
+        : check.bytes !== undefined
+          ? `Ready: ${formatByteSize(check.bytes.length)} of Candid arguments.`
+          : undefined)
+
+  const submit = (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault()
+    if (blocked) return
+    const result = form.submit()
+    if (
+      result.ok &&
+      result.values !== undefined &&
+      result.bytes !== undefined
+    ) {
+      // Enter in a field submits from it, and a call in flight disables the
+      // fields. The browser drops the focus of a field the moment its
+      // fieldset is disabled, before any effect could move it: it goes to
+      // the button now, where a click would have left it.
+      const active = document.activeElement
+      if (active !== null && fields.current?.contains(active))
+        submitButton.current?.focus()
+      onSubmit({
+        values: result.values,
+        vars: result.vars,
+        bytes: result.bytes,
+      })
+    }
+  }
+
+  const summary = state.showAll ? check.issues : []
+  const listed = [...summary, ...lastCall].slice(0, SUMMARY_LIMIT)
+
+  return (
+    <FormContext.Provider value={context}>
+      <form
+        className="form"
+        noValidate
+        aria-label={`Arguments of ${method.name}`}
+        onSubmit={submit}
+      >
+        <datalist id={datalistId}>
+          {KNOWN_CANISTERS.map(({ id, name }) => (
+            <option key={id} value={id}>
+              {name}
+            </option>
+          ))}
+        </datalist>
+        <fieldset ref={fields} className="form-fields" disabled={busy}>
+          {argCount === 0 && (
+            <p className="muted text-sm">This method takes no arguments.</p>
+          )}
+          {args.map((schema, i) => {
+            // Every argument is labelled, with its type beside the label; a
+            // lone unnamed record goes without a frame, as its fields are
+            // the labels.
+            const bare =
+              argCount === 1 &&
+              names?.[0] === undefined &&
+              resolve(schema).kind === "record"
+            return (
+              <Field
+                key={i}
+                schema={schema}
+                draft={state.drafts[i] ?? { k: "uninhabited" }}
+                path={argPath(i)}
+                label={bare ? undefined : argLabel(i, argCount, names)}
+                a11yLabel={bare ? "Argument" : undefined}
+                onChange={(draft) => edit(i, draft)}
+              />
+            )
+          })}
+        </fieldset>
+        {listed.length > 0 && (
+          <div className="notice notice-danger form-summary" role="alert">
+            <p className="notice-title">
+              {summary.length > 0
+                ? `${summary.length} ${summary.length === 1 ? "field needs" : "fields need"} attention`
+                : "The last call refused these arguments"}
+            </p>
+            <ul className="list-plain stack-xs">
+              {listed.map((issue, i) => (
+                <li key={i} className="text-sm">
+                  <button
+                    type="button"
+                    className="form-summary-link mono"
+                    onClick={() => form.focusOn(issue.path)}
+                  >
+                    {pathLabel(issue.path, argCount, names)}
+                  </button>
+                  : {issue.message}
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+        <div className="form-footer">
+          <div className="row form-submit-row">
+            <button
+              ref={setSubmitButton}
+              type="submit"
+              className="btn btn-primary"
+              aria-disabled={blocked || undefined}
+              aria-describedby={
+                reason === undefined ? undefined : `${baseId}-reason`
+              }
+            >
+              {busy && (
+                <span className="spinner spinner-sm" aria-hidden="true" />
+              )}
+              {submitLabel}
+            </button>
+            {reason !== undefined && (
+              <p
+                id={`${baseId}-reason`}
+                className={
+                  disabledReason !== undefined || check.ok
+                    ? "form-reason muted"
+                    : "form-reason form-reason-issue"
+                }
+              >
+                {reason}
+              </p>
+            )}
+          </div>
+          <div className="row-sm form-tools">
+            <JsonPanel
+              id={`${baseId}-json`}
+              args={args}
+              argNames={names}
+              drafts={state.drafts}
+              onLoad={form.load}
+            />
+            <button
+              type="button"
+              className="btn btn-ghost btn-sm"
+              onClick={form.reset}
+            >
+              Reset
+            </button>
+          </div>
+        </div>
+      </form>
+    </FormContext.Provider>
+  )
+}

package/examples/canister-studio/src/forms/TypedForm.tsx

@@ -0,0 +1,55 @@
+import type { Schema } from "@meantjs/schema"
+import { useMemo, type JSX, type Ref } from "react"
+import type { MethodInfo } from "../interface/types.ts"
+import type { CallCheck, FieldIssue } from "./engine.ts"
+import type { HintResolver } from "./hints.ts"
+import { MethodForm } from "./MethodForm.tsx"
+
+export interface TypedFormProps<T> {
+  /** The one argument's schema, from a generated module. */
+  schema: Schema<T>
+  label: string
+  hints?: HintResolver
+  initialValue?: T
+  submitLabel: string
+  disabledReason?: string
+  busy?: boolean
+  onSubmit(value: T, bytes: Uint8Array): void
+  /** Issues from the last call (`issuesFromReactorError`). */
+  externalIssues?: readonly FieldIssue[]
+  onChange?(check: CallCheck): void
+  /** Offers "Use mine" on principal fields. */
+  callerPrincipal?: string
+  /** The submit button, for a parent that hands the focus back to it. */
+  submitRef?: Ref<HTMLButtonElement>
+}
+
+/**
+ * A typed form for a one-argument method of a generated module, such as
+ * `TypedForm<TransferArg>` with `schema={TransferArg}`: the value handed to
+ * `onSubmit` is a `T`, and `bytes` is the method's exact Candid argument
+ * message.
+ */
+export function TypedForm<T>(props: TypedFormProps<T>): JSX.Element {
+  const { schema, label, initialValue, onSubmit, ...rest } = props
+  const method = useMemo<MethodInfo>(
+    () => ({ name: label, mode: "update", args: [schema], results: [] }),
+    [schema, label]
+  )
+  const initialValues = useMemo(
+    () => (initialValue === undefined ? undefined : [initialValue]),
+    [initialValue]
+  )
+  return (
+    <MethodForm
+      {...rest}
+      method={method}
+      initialValues={initialValues}
+      onSubmit={({ values, bytes }) =>
+        // checkCall validated values[0] against `schema`, a Schema<T>, and
+        // encoded it: it is a T.
+        onSubmit(values[0] as T, bytes)
+      }
+    />
+  )
+}

package/examples/canister-studio/src/forms/context.ts

@@ -0,0 +1,62 @@
+import type { AnyFieldSchema } from "@meantjs/schema"
+import { createContext, useContext } from "react"
+import type { Draft, FieldIssue } from "./engine.ts"
+import type { FieldHint } from "./hints.ts"
+
+/** What every field of one form shares: ids, hints, issues, touch state. */
+export interface FormContextValue {
+  /** The DOM id of the control at a path: the form's `useId()` plus the path. */
+  idFor(path: string): string
+  hint(at: {
+    path: string
+    key?: string
+    schema: AnyFieldSchema
+  }): FieldHint | undefined
+  /** The issues a field shows now: once touched or after a submit attempt, plus the last call's. */
+  issuesAt(path: string): readonly FieldIssue[]
+  /** Whether a shown issue sits at `path` or below it (collapsed sections). */
+  hasIssueBelow(path: string): boolean
+  /**
+   * The highest index of the vec at `path` whose item has a shown issue at
+   * or below it, or -1: a paged list keeps that item on screen.
+   */
+  lastItemWithIssue(path: string): number
+  touch(path: string): void
+  /** A submit was attempted: every issue shows, and sections holding one open. */
+  readonly showAll: boolean
+  readonly callerPrincipal?: string
+  /** The id of the form's datalist of known canisters, for principal inputs. */
+  readonly datalistId: string
+  /** Whether the time at `path` (or an ancestor) is refreshed when sending. */
+  isAutoNow(path: string): boolean
+  setAutoNow(path: string, on: boolean): void
+}
+
+export const FormContext = createContext<FormContextValue | null>(null)
+
+export function useFormContext(): FormContextValue {
+  const value = useContext(FormContext)
+  if (value === null) throw new Error("form fields render inside a MethodForm")
+  return value
+}
+
+/** The props every field component takes. */
+export interface FieldProps {
+  readonly schema: AnyFieldSchema
+  readonly draft: Draft
+  readonly onChange: (draft: Draft) => void
+  readonly path: string
+  /** The record key the field sits at, for hint lookup. */
+  readonly fieldKey?: string
+  /** The visible label; none for an opt's inner value or a lone argument. */
+  readonly label?: string
+  /** The accessible name when there is no visible label. */
+  readonly a11yLabel?: string
+  /** A hint the parent resolved (an opt's inner value shares its opt's). */
+  readonly inheritedHint?: FieldHint
+}
+
+/** What `Field` hands each editor: the props, with the hint resolved. */
+export interface EditorProps extends FieldProps {
+  readonly hint?: FieldHint
+}

package/examples/canister-studio/src/forms/convert.ts

@@ -0,0 +1,131 @@
+// Conversions behind the field widgets: token units, timestamps and
+// subaccounts. Pure and deterministic, except `nowNanos`, which reads the
+// clock and is called only from event handlers and effects, never in render.
+import { formatUnits, parseUnits } from "@ic-reactor/core"
+import { formatNanos, type TokenUnits } from "../lib/format.ts"
+import { fromHex } from "../lib/hex.ts"
+import { parseBigInt } from "./engine.ts"
+
+export type Parsed<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly message: string }
+
+// ic-reactor's messages name the function they come from; a field already
+// says what it is.
+const PREFIX = /^\[ic-reactor\] (?:parseUnits|formatUnits): /
+
+/**
+ * A decimal amount in a token's units as base units, exactly: "1.5" with 8
+ * decimals is 150000000n. More fraction digits than the token has, grouping
+ * separators and exponents are refused, never rounded (`parseUnits`).
+ */
+export function parseTokenAmount(
+  text: string,
+  units: TokenUnits,
+  signed = false
+): Parsed<bigint> {
+  if (text.trim() === "") return { ok: false, message: "required" }
+  try {
+    return { ok: true, value: parseUnits(text, units.decimals, { signed }) }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return { ok: false, message: message.replace(PREFIX, "") }
+  }
+}
+
+/**
+ * Base-units text (a leaf draft) as a decimal in the token's units, or
+ * `undefined` when the text is not a whole number. It reads the text as the
+ * engine does (`1,000,000`, `0x5f5e100`), so the decimal shown is the amount
+ * the call sends, never the raw text beside the token's symbol.
+ */
+export function tokenAmountText(
+  raw: string,
+  units: TokenUnits
+): string | undefined {
+  const value = parseBigInt(raw)
+  return typeof value === "bigint"
+    ? formatUnits(value, units.decimals)
+    : undefined
+}
+
+/** Now, in nanoseconds since the Unix epoch. Event handlers and effects only. */
+export function nowNanos(): bigint {
+  return BigInt(Date.now()) * 1_000_000n
+}
+
+const NANOS_PER_MILLI = 1_000_000n
+const UTC_TEXT =
+  /^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))? UTC$/
+
+/**
+ * Nanoseconds as the value of an `<input type="datetime-local">` read as
+ * UTC ("2026-10-12T02:31:05.123"), or `undefined` outside years 0000–9999.
+ * Computed from the bigint, so it is the same on the server and in every
+ * browser, whatever their time zone.
+ */
+export function nanosToUtcInput(ns: bigint): string | undefined {
+  const match = UTC_TEXT.exec(formatNanos(ns))
+  if (match === null) return undefined
+  const [, y, mo, d, h, mi, s, fraction = ""] = match
+  const millis = fraction.padEnd(3, "0").slice(0, 3)
+  return `${y}-${mo}-${d}T${h}:${mi}:${s}${millis === "000" ? "" : `.${millis}`}`
+}
+
+const INPUT_TEXT =
+  /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?$/
+
+/** A `datetime-local` value read as UTC, in nanoseconds; `undefined` if malformed. */
+export function utcInputToNanos(text: string): bigint | undefined {
+  const match = INPUT_TEXT.exec(text)
+  if (match === null) return undefined
+  const [, y, mo, d, h, mi, s = "0", ms = "0"] = match
+  const parts = [y, mo, d, h, mi, s, ms.padEnd(3, "0")].map(Number) as [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+  ]
+  const [year, month, day, hour, minute, second, milli] = parts
+  // Not Date.UTC: it reads years 0-99 as 1900-1999. The setters take the
+  // year as given, and the round trip refuses a day or time that rolls
+  // over (February 30, 24:00).
+  const date = new Date(0)
+  date.setUTCFullYear(year, month - 1, day)
+  date.setUTCHours(hour, minute, second, milli)
+  const millis = date.getTime()
+  if (
+    !Number.isFinite(millis) ||
+    date.getUTCFullYear() !== year ||
+    date.getUTCMonth() !== month - 1 ||
+    date.getUTCDate() !== day ||
+    date.getUTCHours() !== hour ||
+    date.getUTCMinutes() !== minute ||
+    date.getUTCSeconds() !== second
+  ) {
+    return undefined
+  }
+  return BigInt(millis) * NANOS_PER_MILLI
+}
+
+/** The bytes of a subaccount. */
+export const SUBACCOUNT_BYTES = 32
+
+/**
+ * A subaccount from a number: 32 bytes, big-endian, the convention ledgers
+ * and wallets use for "subaccount 1, 2, …".
+ */
+export function subaccountFromNumber(text: string): Parsed<Uint8Array> {
+  // The engine's reading: "1,5" is refused, not taken for subaccount 15.
+  const n = parseBigInt(text)
+  if (typeof n === "string" || n < 0n)
+    return { ok: false, message: "enter a whole number ≥ 0" }
+  const hex = n.toString(16).padStart(SUBACCOUNT_BYTES * 2, "0")
+  const bytes = hex.length === SUBACCOUNT_BYTES * 2 ? fromHex(hex) : undefined
+  if (bytes === undefined)
+    return { ok: false, message: "too large for 32 bytes" }
+  return { ok: true, value: bytes }
+}