@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/forms/fields/ListField.tsx

@@ -0,0 +1,256 @@
+import type { AnyFieldSchema } from "@meantjs/schema"
+import { useEffect, useRef, useState, type ReactNode } from "react"
+import { useFormContext, type EditorProps } from "../context.ts"
+import {
+  childPath,
+  displayLabel,
+  initialDraft,
+  isUninhabited,
+  newItemId,
+  typeName,
+  type Draft,
+} from "../engine.ts"
+import { Field } from "./Field.tsx"
+import { Group } from "./Group.tsx"
+
+/** Items shown at once; "Show more" reveals the next page. */
+const PAGE = 20
+/** The most items one "Add" adds. */
+const MAX_ADD = 1_000
+
+type Items = Extract<Draft, { k: "vec" }>["items"]
+
+/** Where the focus goes after an action removed or moved its own button. */
+type FocusTarget =
+  | { readonly item: number; readonly action: "up" | "down" | "remove" }
+  | { readonly item: number; readonly action: "first" }
+  | { readonly action: "add" }
+
+const FOCUSABLE = "input:not([type=hidden]), select, textarea, button"
+
+/**
+ * A vec: add (one or several), remove, move up and down, paged after
+ * {@link PAGE} items. Each item keeps a stable id, so moving one keeps its
+ * editor state. An item with a shown issue is never left on a hidden page.
+ */
+export function ListField(
+  props: EditorProps & { item: AnyFieldSchema }
+): ReactNode {
+  const form = useFormContext()
+  const { path, onChange, item, schema } = props
+  const items: Items = props.draft.k === "vec" ? props.draft.items : []
+  const [shown, setShown] = useState(PAGE)
+  const [count, setCount] = useState("5")
+  const name = displayLabel(props.label ?? props.a11yLabel ?? "item")
+  const set = (next: Items) => onChange({ k: "vec", items: next })
+  const fresh = () => ({ id: newItemId(), draft: initialDraft(item) })
+  // `vec Loop` with `Loop = record { x : Loop }`: only the empty list exists.
+  const onlyEmpty = isUninhabited(item)
+
+  // The summary names an issue in item 25 and a submit focuses it: the page
+  // then reaches it, or neither would find a field to show it at. Latched,
+  // so the item stays while the reader corrects it.
+  const needed = form.lastItemWithIssue(path) + 1
+  if (needed > shown) setShown(needed)
+  const reach = Math.max(shown, needed)
+  const visible = items.slice(0, reach)
+
+  // A button that disables or removes itself would drop the focus to the
+  // page: the focus goes to the same button of the item where it lands, the
+  // next item's Remove, or Add item.
+  const list = useRef<HTMLDivElement>(null)
+  const focusNext = useRef<FocusTarget | undefined>(undefined)
+  useEffect(() => {
+    const target = focusNext.current
+    const root = list.current
+    if (target === undefined || root === null) return
+    focusNext.current = undefined
+    const selector =
+      target.action === "add"
+        ? '[data-list-action="add"]'
+        : target.action === "first"
+          ? `[data-item="${target.item}"] > :last-child`
+          : `[data-item="${target.item}"] [data-list-action="${target.action}"]`
+    const el = root.querySelector<HTMLElement>(selector)
+    const focusable = el?.matches(FOCUSABLE)
+      ? el
+      : el?.querySelector<HTMLElement>(FOCUSABLE)
+    focusable?.focus()
+  })
+
+  const add = (n: number) => {
+    if (onlyEmpty) return
+    set([...items, ...Array.from({ length: n }, fresh)])
+    // A single item added at the end of a fully shown list stays in view.
+    if (n === 1 && items.length === reach) setShown(reach + 1)
+  }
+  const move = (from: number, to: number, action: "up" | "down") => {
+    if (to < 0 || to >= items.length) return
+    const next = [...items]
+    const [moved] = next.splice(from, 1)
+    if (moved !== undefined) next.splice(to, 0, moved)
+    // Moving the node can blur it; the focus follows the item.
+    focusNext.current = { item: to, action }
+    set(next)
+  }
+  const remove = (index: number, id: number) => {
+    const next = items.filter((x) => x.id !== id)
+    focusNext.current =
+      next.length === 0
+        ? { action: "add" }
+        : { item: Math.min(index, next.length - 1), action: "remove" }
+    set(next)
+  }
+  const countNumber = Number.parseInt(count, 10)
+  const addMany =
+    !onlyEmpty &&
+    Number.isInteger(countNumber) &&
+    countNumber >= 1 &&
+    countNumber <= MAX_ADD
+      ? countNumber
+      : undefined
+  const countId = `${form.idFor(path)}-count`
+
+  return (
+    <Group
+      path={path}
+      label={props.label}
+      a11yLabel={props.a11yLabel}
+      type={typeName(schema)}
+      note={
+        <span className="muted text-xs">
+          {items.length} {items.length === 1 ? "item" : "items"}
+        </span>
+      }
+      className="form-list"
+    >
+      <div ref={list} className="stack-sm">
+        {items.length === 0 && (
+          <p className="subtle text-sm">
+            {onlyEmpty
+              ? "Empty: the item type has no values, so no item can be added."
+              : "Empty: no items."}
+          </p>
+        )}
+        {visible.length > 0 && (
+          <ol className="list-plain form-list-items">
+            {visible.map((entry, i) => (
+              <li key={entry.id} className="form-list-item" data-item={i}>
+                <div className="form-list-item-head">
+                  <span className="mono text-xs muted">[{i}]</span>
+                  <div className="row-sm">
+                    {/* aria-disabled, not disabled: the item that moves to an
+                        end keeps the focus on its button. */}
+                    <button
+                      type="button"
+                      className="btn btn-ghost btn-sm btn-icon"
+                      data-list-action="up"
+                      aria-label={`Move ${name}[${i}] up`}
+                      aria-disabled={i === 0 || undefined}
+                      onClick={() => move(i, i - 1, "up")}
+                    >
+                      ↑
+                    </button>
+                    <button
+                      type="button"
+                      className="btn btn-ghost btn-sm btn-icon"
+                      data-list-action="down"
+                      aria-label={`Move ${name}[${i}] down`}
+                      aria-disabled={i === items.length - 1 || undefined}
+                      onClick={() => move(i, i + 1, "down")}
+                    >
+                      ↓
+                    </button>
+                    <button
+                      type="button"
+                      className="btn btn-ghost btn-sm"
+                      data-list-action="remove"
+                      aria-label={`Remove ${name}[${i}]`}
+                      onClick={() => remove(i, entry.id)}
+                    >
+                      Remove
+                    </button>
+                  </div>
+                </div>
+                <Field
+                  schema={item}
+                  draft={entry.draft}
+                  path={childPath(path, i)}
+                  a11yLabel={`${name}[${i}]`}
+                  onChange={(next) =>
+                    set(
+                      items.map((x) =>
+                        x.id === entry.id ? { id: x.id, draft: next } : x
+                      )
+                    )
+                  }
+                />
+              </li>
+            ))}
+          </ol>
+        )}
+        {items.length > reach && (
+          <button
+            type="button"
+            className="btn btn-sm"
+            onClick={() => {
+              // This button goes once every item shows: the focus moves to
+              // the first item it revealed, where reading goes on.
+              focusNext.current = { item: reach, action: "first" }
+              setShown(reach + PAGE)
+            }}
+          >
+            Show {Math.min(PAGE, items.length - reach)} more (
+            {items.length - reach} hidden)
+          </button>
+        )}
+        <div className="row-sm form-list-actions">
+          <button
+            type="button"
+            className="btn btn-sm"
+            data-list-action="add"
+            disabled={onlyEmpty}
+            onClick={() => add(1)}
+          >
+            Add item
+          </button>
+          <span className="row-sm">
+            <label className="sr-only" htmlFor={countId}>
+              Items to add
+            </label>
+            <input
+              id={countId}
+              className="input form-input-narrow"
+              type="number"
+              min={1}
+              max={MAX_ADD}
+              value={count}
+              disabled={onlyEmpty}
+              onChange={(e) => setCount(e.target.value)}
+            />
+            <button
+              type="button"
+              className="btn btn-sm"
+              disabled={addMany === undefined}
+              onClick={() => addMany !== undefined && add(addMany)}
+            >
+              Add {addMany ?? "N"}
+            </button>
+          </span>
+          {items.length > 0 && (
+            <button
+              type="button"
+              className="btn btn-ghost btn-sm"
+              onClick={() => {
+                focusNext.current = { action: "add" }
+                set([])
+              }}
+            >
+              Remove all
+            </button>
+          )}
+        </div>
+      </div>
+    </Group>
+  )
+}

package/examples/canister-studio/src/forms/fields/Segmented.tsx

@@ -0,0 +1,78 @@
+import { useRef, type KeyboardEvent, type ReactNode } from "react"
+
+export interface SegmentOption<T extends string> {
+  readonly value: T
+  readonly label: ReactNode
+  readonly disabled?: boolean
+  readonly title?: string
+}
+
+interface SegmentedProps<T extends string> {
+  readonly id?: string
+  readonly options: readonly SegmentOption<T>[]
+  readonly value: T
+  readonly onChange: (value: T) => void
+  /** The group's accessible name. */
+  readonly label: string
+}
+
+/**
+ * A radio group drawn as a segmented control: one tab stop (the checked
+ * option), arrow keys move the choice and skip disabled options.
+ */
+export function Segmented<T extends string>({
+  id,
+  options,
+  value,
+  onChange,
+  label,
+}: SegmentedProps<T>): ReactNode {
+  const buttons = useRef<(HTMLButtonElement | null)[]>([])
+  const checked = options.findIndex((o) => o.value === value)
+  // With nothing checked, the first enabled option keeps the group reachable.
+  const tabStop =
+    checked !== -1 ? checked : options.findIndex((o) => !o.disabled)
+
+  const onKeyDown = (event: KeyboardEvent, index: number) => {
+    const step =
+      event.key === "ArrowRight" || event.key === "ArrowDown"
+        ? 1
+        : event.key === "ArrowLeft" || event.key === "ArrowUp"
+          ? -1
+          : 0
+    if (step === 0) return
+    event.preventDefault()
+    for (let n = 1; n <= options.length; n++) {
+      const next = (index + step * n + options.length * n) % options.length
+      const option = options[next]
+      if (option !== undefined && option.disabled !== true) {
+        onChange(option.value)
+        buttons.current[next]?.focus()
+        return
+      }
+    }
+  }
+
+  return (
+    <div id={id} className="segmented" role="radiogroup" aria-label={label}>
+      {options.map((option, index) => (
+        <button
+          key={option.value}
+          ref={(el) => {
+            buttons.current[index] = el
+          }}
+          type="button"
+          role="radio"
+          aria-checked={option.value === value}
+          tabIndex={index === tabStop ? 0 : -1}
+          disabled={option.disabled}
+          title={option.title}
+          onClick={() => onChange(option.value)}
+          onKeyDown={(event) => onKeyDown(event, index)}
+        >
+          {option.label}
+        </button>
+      ))}
+    </div>
+  )
+}

package/examples/canister-studio/src/forms/fields/TimestampField.tsx

@@ -0,0 +1,108 @@
+import type { ReactNode } from "react"
+import { formatNanos } from "../../lib/format.ts"
+import { useFormContext, type EditorProps } from "../context.ts"
+import { nanosToUtcInput, nowNanos, utcInputToNanos } from "../convert.ts"
+import { FieldShell } from "./FieldShell.tsx"
+import { filterIntegerText } from "./leaves.tsx"
+
+/**
+ * A time in nanoseconds since the Unix epoch (nat64): the raw number, a UTC
+ * date and time picker, a "Now" button, and a switch that sets it to the
+ * time of sending (on by default for `created_at_time`). The picker reads
+ * and writes UTC, never the reader's zone, so the server's HTML and the
+ * browser's agree.
+ */
+export function TimestampField(
+  props: EditorProps & { primitive: string }
+): ReactNode {
+  const form = useFormContext()
+  const { path, hint, onChange, primitive } = props
+  const text = props.draft.k === "leaf" ? props.draft.text : ""
+  const auto = form.isAutoNow(path)
+  const ns = /^\d+$/.test(text.trim()) ? BigInt(text.trim()) : undefined
+  const pickerValue = ns === undefined ? "" : (nanosToUtcInput(ns) ?? "")
+
+  const setNow = () => onChange({ k: "leaf", text: nowNanos().toString() })
+
+  return (
+    <FieldShell
+      path={path}
+      label={props.label}
+      a11yLabel={props.a11yLabel}
+      type={primitive}
+      description={hint?.description}
+      meta={
+        ns === undefined ? (
+          auto ? (
+            "Set when you send"
+          ) : undefined
+        ) : (
+          <>
+            <span className="mono">{formatNanos(ns)}</span>
+            {auto && " · set again when you send"}
+          </>
+        )
+      }
+    >
+      {(a11y) => (
+        <div className="stack-xs">
+          <div className="input-group">
+            <input
+              {...a11y}
+              className="input mono"
+              inputMode="numeric"
+              autoComplete="off"
+              spellCheck={false}
+              readOnly={auto}
+              value={text}
+              placeholder="Nanoseconds since 1970-01-01 UTC"
+              onChange={(e) =>
+                onChange({ k: "leaf", text: filterIntegerText(e.target.value) })
+              }
+              onBlur={() => form.touch(path)}
+            />
+            <button
+              type="button"
+              className="btn"
+              disabled={auto}
+              onClick={setNow}
+            >
+              Now
+            </button>
+          </div>
+          <div className="row-sm form-timestamp-row">
+            <label className="text-xs muted" htmlFor={`${a11y.id}-utc`}>
+              UTC
+            </label>
+            <input
+              id={`${a11y.id}-utc`}
+              className="input form-datetime"
+              type="datetime-local"
+              step="0.001"
+              readOnly={auto}
+              value={pickerValue}
+              onChange={(e) => {
+                const picked = utcInputToNanos(e.target.value)
+                if (picked !== undefined)
+                  onChange({ k: "leaf", text: picked.toString() })
+              }}
+            />
+            <label className="switch-label text-xs">
+              <input
+                type="checkbox"
+                role="switch"
+                className="switch"
+                checked={auto}
+                onChange={(e) => {
+                  form.setAutoNow(path, e.target.checked)
+                  if (e.target.checked) setNow()
+                }}
+              />
+              Time of sending
+            </label>
+          </div>
+        </div>
+      )}
+    </FieldShell>
+  )
+}

package/examples/canister-studio/src/forms/fields/UnitsField.tsx

@@ -0,0 +1,119 @@
+import { useState, type ReactNode } from "react"
+import { formatTokens, groupDigits, type TokenUnits } from "../../lib/format.ts"
+import { useFormContext, type EditorProps } from "../context.ts"
+import { parseTokenAmount, tokenAmountText } from "../convert.ts"
+import { parseBigInt } from "../engine.ts"
+import { FieldShell } from "./FieldShell.tsx"
+import { filterIntegerText } from "./leaves.tsx"
+import { Segmented } from "./Segmented.tsx"
+
+type Mode = "units" | "raw"
+
+interface Shown {
+  /** The draft text this display was made for. */
+  readonly raw: string
+  /** What the input shows. */
+  readonly text: string
+  /** Why the typed amount was refused. */
+  readonly error?: string
+}
+
+const shownFor = (raw: string, units: TokenUnits): Shown => ({
+  raw,
+  text: tokenAmountText(raw, units) ?? raw,
+})
+
+/**
+ * A token amount: typed as a decimal in the token's units ("1.5 ckBTC"), held
+ * in the draft as base units ("150000000"), exactly, through parseUnits. An
+ * amount it cannot hold exactly is refused, never rounded; until it is fixed
+ * the draft is empty, so no other amount can be sent. A toggle edits the base
+ * units directly.
+ */
+export function UnitsField(
+  props: EditorProps & { units: TokenUnits; primitive: string; signed: boolean }
+): ReactNode {
+  const form = useFormContext()
+  const { path, hint, onChange, units, primitive, signed } = props
+  const raw = props.draft.k === "leaf" ? props.draft.text : ""
+  const [mode, setMode] = useState<Mode>("units")
+  const [shown, setShown] = useState<Shown>(() => shownFor(raw, units))
+  // The draft changed from outside (reset, prefill, JSON): show it.
+  let current = shown
+  if (shown.raw !== raw) {
+    current = shownFor(raw, units)
+    setShown(current)
+  }
+
+  const typeUnits = (text: string) => {
+    if (text.trim() === "") {
+      setShown({ raw: "", text })
+      onChange({ k: "leaf", text: "" })
+      return
+    }
+    const parsed = parseTokenAmount(text, units, signed)
+    const next = parsed.ok ? parsed.value.toString() : ""
+    setShown({ raw: next, text, error: parsed.ok ? undefined : parsed.message })
+    onChange({ k: "leaf", text: next })
+  }
+
+  const value = parseBigInt(raw)
+  const symbol = units.symbol === "" ? undefined : units.symbol
+  const meta =
+    mode === "units"
+      ? typeof value === "bigint"
+        ? `= ${groupDigits(value)} base units (${primitive}, ${units.decimals} decimals)`
+        : `${units.decimals} decimals; more digits are refused, never rounded`
+      : typeof value === "bigint"
+        ? `= ${formatTokens(value, units.decimals, symbol)}`
+        : `${primitive} in base units`
+
+  return (
+    <FieldShell
+      path={path}
+      label={props.label}
+      a11yLabel={props.a11yLabel}
+      type={primitive}
+      description={hint?.description}
+      meta={meta}
+      parseMessage={mode === "units" ? current.error : undefined}
+      aside={
+        <Segmented<Mode>
+          label="Amount in"
+          value={mode}
+          onChange={setMode}
+          options={[
+            { value: "units", label: symbol ?? "tokens" },
+            { value: "raw", label: "base units" },
+          ]}
+        />
+      }
+    >
+      {(a11y) => (
+        <div className="input-group">
+          <input
+            {...a11y}
+            className="input mono"
+            inputMode={mode === "units" ? "decimal" : "numeric"}
+            autoComplete="off"
+            spellCheck={false}
+            value={mode === "units" ? current.text : raw}
+            placeholder={hint?.placeholder ?? (mode === "units" ? "0.0" : "0")}
+            onChange={(e) =>
+              mode === "units"
+                ? typeUnits(e.target.value)
+                : onChange({
+                    k: "leaf",
+                    text: filterIntegerText(e.target.value),
+                  })
+            }
+            onBlur={() => form.touch(path)}
+          />
+          <span className="input-addon">
+            {mode === "units" ? (symbol ?? "tokens") : "base units"}
+          </span>
+        </div>
+      )}
+    </FieldShell>
+  )
+}