@mawaru/sdk 0.39.0 → 0.41.0

package/views/_parts/fileRef.ts

@@ -0,0 +1,21 @@
+// ノード間を流れる file の値（storage path の参照。バイトや署名 URL は載らない）。
+// @mawaru/common の fileRefSchema（zod）と同じ形で、部品キットは依存を増やさないよう型と判定だけ持つ
+export type FileRef = {
+  path: string
+  name: string
+  mime_type?: string
+  size?: number
+}
+
+export const isFileRef = (value: unknown): value is FileRef => {
+  if (typeof value !== "object" || value === null) return false
+  const v = value as Record<string, unknown>
+  return (
+    typeof v.path === "string" &&
+    v.path !== "" &&
+    typeof v.name === "string" &&
+    v.name !== "" &&
+    (v.mime_type === undefined || typeof v.mime_type === "string") &&
+    (v.size === undefined || typeof v.size === "number")
+  )
+}

package/views/_parts/useNarrow.ts

@@ -0,0 +1,24 @@
+import { useEffect, useRef, useState } from "react"
+
+// 承認ビューの幅対応。判定は**ビューポートではなくコンテナの幅**で行う。
+//
+// 開発プレビュー（/dev/views/approval）は幅の確認を「狭いコンテナ」で再現するので、
+// media query で判定すると実機とプレビューで挙動がズレる（プレビューでは常に
+// デスクトップ扱いになる）。ResizeObserver でコンテナ自身を測れば両方で同じになる。
+
+export const NARROW_WIDTH = 560
+
+export const useNarrow = <T extends HTMLElement>() => {
+  const ref = useRef<T>(null)
+  const [narrow, setNarrow] = useState(false)
+  useEffect(() => {
+    const element = ref.current
+    if (!element) return
+    const observer = new ResizeObserver(([entry]) => {
+      if (entry) setNarrow(entry.contentRect.width < NARROW_WIDTH)
+    })
+    observer.observe(element)
+    return () => observer.disconnect()
+  }, [])
+  return { ref, narrow }
+}

package/views/components.ts

@@ -0,0 +1,16 @@
+// 共通の部品（`@mawaru/sdk/components`）。human ノードの約束（`@mawaru/sdk/human`）には依存しない。
+// mawaru の画面と顧客 repo の human ノードの実装が同じ部品を使う（mawaru が顧客 repo の実装をまとめるとき、
+// mawaru の今の版のこの部品を同梱する）。ファイルの表示・アップロードは、mawaru の画面ではホストの口、
+// sandbox iframe の中では mawaru の承認画面への頼みごととして裏で差し込まれる（_bridge.tsx）。
+// **公開 API**：部品の props は後方互換でしか変えない
+export { documentCardStyle } from "./_parts/DocumentCard.js"
+export { FilePreview } from "./_parts/FilePreview.js"
+export { type FileRef, isFileRef } from "./_parts/fileRef.js"
+export { isUrl, Linkify, linkify } from "./_parts/Linkify.js"
+export { isLongText, Markdown, useAutoGrow } from "./_parts/Markdown.js"
+export {
+  asFormSchema,
+  type JsonSchema as FormSchema,
+  SchemaForm,
+} from "./_parts/SchemaForm.js"
+export { NARROW_WIDTH, useNarrow } from "./_parts/useNarrow.js"

package/views/host.ts

@@ -0,0 +1,27 @@
+import { z } from "zod"
+import { VIEW_MESSAGE_TAG } from "./protocol.js"
+
+// ホスト（mawaru の画面）だけが使うもの（公開 API ではない）：sandbox iframe からのメッセージを確かめる形
+// （protocol.ts の型と同じ。iframe の中は信用できないコードなので、形を確かめてから使う）、
+// 部品が裏で使う口を差す提供部品、human ノードの実装に渡す props の組み立て（標準の承認画面も同じものを使う）
+export {
+  useViewBridge,
+  type ViewBridge,
+  ViewBridgeProvider,
+} from "./_bridge.js"
+export { type HumanOps, humanPropsOf } from "./_humanProps.js"
+export * from "./protocol.js"
+
+const tag = z.literal(VIEW_MESSAGE_TAG)
+
+export const viewToHostSchema = z.discriminatedUnion("type", [
+  z.object({ tag, type: z.literal("ready") }),
+  z.object({ tag, type: z.literal("error"), message: z.string() }),
+  z.object({
+    tag,
+    type: z.literal("request"),
+    id: z.number().int(),
+    method: z.enum(["out", "fetchFileUrl", "uploadFile", "writeText"]),
+    args: z.unknown(),
+  }),
+])

package/views/human.ts

@@ -0,0 +1,83 @@
+import type { ReactNode } from "react"
+import type { JsonSchema } from "../_schemas/node.js"
+import type { FileRef } from "./_parts/fileRef.js"
+
+// human ノードの実装（顧客 repo の nodes/human/<dir>/index.tsx）の約束（`@mawaru/sdk/human`）。
+// human ノードは「input を受け取り、人の操作で出口（approve・reject・追加の出口）に値を出す」。
+// program の run(input) が { <出口ポートのkey>: <データ> } を返すのと同じ形で、human はそれを人が画面で選ぶ。
+//
+// 実装は React のコンポーネント1つで、承認画面の上の帯より下を全部描く。mawaru が esbuild でまとめ、
+// sandbox iframe の中で動かす（mawaru のログイン・API・fetch には届かない）。
+// 局面・担当・全員承認の進み具合は mawaru の承認画面の帯が出し、実装が描かれるのは承認待ちのときだけ。
+//
+// 型は mawaru typegen が config.json から作る types.d.ts（Input / Outputs / Output / Refs。program と同じ）を使う：
+//   export default defineHuman<Input, Output, Refs>(({ input, out, ctx }) => …)
+
+export type HumanProps<
+  TInput = unknown,
+  TOutput = Record<string, unknown>,
+  TRefs = Record<string, unknown>,
+> = {
+  /** 届いた値（in ポートの値＝ step の input） */
+  input: TInput
+  /**
+   * 人の操作を mawaru に渡す。`{ <出口ポートのkey>: <データ> }`（program の run の戻り値と同じ1キーのオブジェクト）。
+   * 人がボタンを押した直後の呼び出しだけを受け付ける（開いただけで決定する画面は書けない）。
+   * 送れたら承認画面は run の画面へ戻る。断られたら（担当でない・もう決まっている など）理由つきで失敗する
+   */
+  out: (output: TOutput) => Promise<void>
+  /** input 以外の材料（program の run の ctx と同じ位置づけ） */
+  ctx: {
+    input: {
+      /** input の型（in ポートの JSON Schema） */
+      schema: JsonSchema
+      /** input に含まれるファイルを表示する URL を取る（sandbox の中からは mawaru のファイルを直接読めない） */
+      fetchFileUrl: (file: FileRef) => Promise<string>
+    }
+    output: {
+      /** 出口ごとの型（out ポートの key → JSON Schema。approve・reject・追加の出口） */
+      schema: Record<string, JsonSchema>
+      /** 出す値に入れるファイル（差し戻しの参考ファイルなど）を上げて、参照を受け取る */
+      uploadFile: (file: File) => Promise<FileRef>
+    }
+    clipboard: {
+      /** クリップボードに書く（sandbox の中では使えない navigator.clipboard.writeText の代わり） */
+      writeText: (text: string) => Promise<void>
+    }
+    /**
+     * ループ変数（この step が始まった時点の値。program の ctx.refs と同じ）。
+     * 予約キー `input` が run の起動入力
+     */
+    refs: TRefs
+    step: {
+      /** 見ている人がこの step の担当か（担当でなければ out は断られる） */
+      isAssignee: boolean
+      /**
+       * 値を直してよいか：担当で、全員承認のノードでないとき true
+       * （全員承認は全員が同じ値を承認するので、届いた値のまま決める）
+       */
+      editable: boolean
+    }
+  }
+}
+
+/** mawaru が承認画面に描く、human ノードの画面（React のコンポーネント） */
+export type HumanView<
+  TInput = unknown,
+  TOutput = Record<string, unknown>,
+  TRefs = Record<string, unknown>,
+> = (props: HumanProps<TInput, TOutput, TRefs>) => ReactNode
+
+/**
+ * human ノードの実装を定義する：input と out を受けて描く関数を渡すと、画面を返す。
+ * React では props を受けて描く関数がそのままコンポーネントなので、型を付けて返すだけ
+ */
+export const defineHuman = <
+  TInput = unknown,
+  TOutput = Record<string, unknown>,
+  TRefs = Record<string, unknown>,
+>(
+  render: (props: HumanProps<TInput, TOutput, TRefs>) => ReactNode,
+): HumanView<TInput, TOutput, TRefs> => render
+
+export type { FileRef }

package/views/protocol.ts

@@ -0,0 +1,63 @@
+import type { JsonSchema } from "../_schemas/node.js"
+
+// sandbox iframe の中の実行部分（runtime.tsx）とホスト（mawaru の承認画面）とのメッセージの形。
+// **公開 API ではない**：iframe の中の実行部分とホストは同じデプロイの mawaru のコード（まとめるときに
+// その時点の版を同梱する）なので、いつ変えてもよい。
+// iframe に入る JS を小さく保つため、ここには型と定数だけを置く（ホストの検査は host.ts）
+
+export const VIEW_MESSAGE_TAG = "mawaru:view"
+
+export type ThemeMode = "light" | "dark"
+
+// human ノードの実装に渡す材料のうち、JSON で送れるもの（関数はホストへの頼みごととして iframe の中で組み立てる）
+export type HumanViewData = {
+  input: unknown
+  inputSchema: JsonSchema
+  outputSchema: Record<string, JsonSchema>
+  refs: unknown
+  isAssignee: boolean
+  editable: boolean
+}
+
+// ビューからホストへの頼みごと（HumanProps の関数と、部品が裏で使う口）
+export type HumanRequestMethod =
+  | "out"
+  | "fetchFileUrl"
+  | "uploadFile"
+  | "writeText"
+
+// ビュー → ホスト
+export type ViewToHost =
+  | { tag: typeof VIEW_MESSAGE_TAG; type: "ready" }
+  // 描画の例外（ホストはエラーと理由を出す）
+  | { tag: typeof VIEW_MESSAGE_TAG; type: "error"; message: string }
+  | {
+      tag: typeof VIEW_MESSAGE_TAG
+      type: "request"
+      id: number
+      method: HumanRequestMethod
+      args: unknown
+    }
+
+// ホスト → ビュー
+export type HostToView =
+  | {
+      tag: typeof VIEW_MESSAGE_TAG
+      type: "data"
+      data: HumanViewData
+      mode: ThemeMode
+    }
+  | {
+      tag: typeof VIEW_MESSAGE_TAG
+      type: "response"
+      id: number
+      ok: true
+      value: unknown
+    }
+  | {
+      tag: typeof VIEW_MESSAGE_TAG
+      type: "response"
+      id: number
+      ok: false
+      error: string
+    }

package/views/runtime.tsx

@@ -0,0 +1,123 @@
+import { Component, type ReactNode } from "react"
+import { createRoot } from "react-dom/client"
+import { ViewBridgeProvider } from "./_bridge.js"
+import { type HumanOps, humanPropsOf } from "./_humanProps.js"
+import type { FileRef } from "./_parts/fileRef.js"
+import type { HumanView } from "./human.js"
+import {
+  type HostToView,
+  type HumanRequestMethod,
+  type HumanViewData,
+  VIEW_MESSAGE_TAG,
+  type ViewToHost,
+} from "./protocol.js"
+
+// sandbox iframe の中の実行部分。mawaru が顧客 repo の human ノードの実装をまとめるとき、
+// 入口から runHumanView を呼ぶ。ホストとのメッセージの形は protocol.ts（公開 API ではない）
+
+// union のまま tag だけを外す（Omit は union を潰す）
+type WithoutTag<T> = T extends unknown ? Omit<T, "tag"> : never
+
+const post = (message: WithoutTag<ViewToHost>) =>
+  // 受け手は親（ホスト）の window だけ。不透明オリジンの iframe からは親のオリジンを指定できない
+  window.parent.postMessage({ tag: VIEW_MESSAGE_TAG, ...message }, "*")
+
+const messageOf = (err: unknown) =>
+  err instanceof Error ? err.message : String(err)
+
+let nextRequestId = 1
+const pending = new Map<
+  number,
+  { resolve: (value: unknown) => void; reject: (err: Error) => void }
+>()
+const dataListeners = new Set<(data: HumanViewData) => void>()
+
+const onHostMessage = (event: MessageEvent) => {
+  if (event.source !== window.parent) return
+  const message = event.data as HostToView | undefined
+  if (message?.tag !== VIEW_MESSAGE_TAG) return
+  if (message.type === "response") {
+    const waiting = pending.get(message.id)
+    if (!waiting) return
+    pending.delete(message.id)
+    if (message.ok) waiting.resolve(message.value)
+    else waiting.reject(new Error(message.error))
+    return
+  }
+  if (message.type === "data") {
+    document.documentElement.dataset.mode = message.mode
+    for (const listener of dataListeners) listener(message.data)
+  }
+}
+
+// ホストに頼む（返事が来るまで待つ）
+const requestHost = <T,>(
+  method: HumanRequestMethod,
+  args: unknown,
+): Promise<T> =>
+  new Promise<T>((resolve, reject) => {
+    const id = nextRequestId++
+    pending.set(id, {
+      resolve: resolve as (value: unknown) => void,
+      reject,
+    })
+    post({ type: "request", id, method, args })
+  })
+
+const ops: HumanOps = {
+  out: (output) => requestHost<void>("out", { output }),
+  fetchFileUrl: (file: FileRef) =>
+    requestHost<string>("fetchFileUrl", { file }),
+  uploadFile: (file: File) => requestHost<FileRef>("uploadFile", { file }),
+  writeText: (text: string) => requestHost<void>("writeText", { text }),
+}
+
+// 部品（FilePreview・SchemaForm のファイル欄）が裏で使う口も、同じ頼みごとにつなぐ
+const bridge = {
+  fileUrl: ops.fetchFileUrl,
+  uploadFile: ops.uploadFile,
+  copyText: ops.writeText,
+}
+
+// 描画の例外をホストへ知らせる（ホストはエラーと理由を出す）
+class ReportErrors extends Component<
+  { children: ReactNode },
+  { failed: boolean }
+> {
+  state = { failed: false }
+  static getDerivedStateFromError() {
+    return { failed: true }
+  }
+  componentDidCatch(error: unknown) {
+    post({ type: "error", message: messageOf(error) })
+  }
+  render() {
+    return this.state.failed ? null : this.props.children
+  }
+}
+
+// 実装はコンポーネント1つ。状態（直した値など）は実装が useState で持ち、材料が届き直しても
+// 同じコンポーネントとして描き直すので保たれる
+export const runHumanView = (View: HumanView) => {
+  window.addEventListener("message", onHostMessage)
+  window.addEventListener("error", (event) =>
+    post({ type: "error", message: event.message }),
+  )
+  window.addEventListener("unhandledrejection", (event) =>
+    post({ type: "error", message: messageOf(event.reason) }),
+  )
+  const container = document.getElementById("root")
+  if (!container) throw new Error("#root がありません")
+  const root = createRoot(container)
+  dataListeners.add((data) => {
+    const props = humanPropsOf(data, ops)
+    root.render(
+      <ViewBridgeProvider bridge={bridge}>
+        <ReportErrors>
+          <View {...props} />
+        </ReportErrors>
+      </ViewBridgeProvider>,
+    )
+  })
+  post({ type: "ready" })
+}

package/views/sample.tsx

@@ -0,0 +1,94 @@
+import { useState } from "react"
+import { defineHuman } from "./human.js"
+
+// サンプル：AI が下書きした返信を、人が直してから送る（approve）か、理由を書いて差し戻す（reject）。
+// 顧客 repo では Input / Outputs / Output は typegen が config.json から作る（nodes/human/<dir>/types.d.ts）。
+// ここでは同じものを手で書いている
+
+type Input = { subject: string; body: string }
+
+type Outputs = {
+  approve: { subject: string; body: string }
+  reject: { prompt: string }
+}
+
+type Output =
+  | { approve: Outputs["approve"]; reject?: never }
+  | { reject: Outputs["reject"]; approve?: never }
+
+export default defineHuman<Input, Output>(({ input, out }) => {
+  const [reply, setReply] = useState(input)
+  const [prompt, setPrompt] = useState("")
+  return (
+    <div
+      style={{
+        maxWidth: "720px",
+        margin: "0 auto",
+        padding: "var(--space-8) var(--space-6)",
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--space-3)",
+      }}
+    >
+      <input
+        value={reply.subject}
+        onChange={(e) => setReply({ ...reply, subject: e.target.value })}
+        style={{
+          padding: "var(--space-2) var(--space-3)",
+          border: "var(--border-w) solid var(--border)",
+          borderRadius: "var(--radius-s)",
+          background: "var(--surface)",
+          color: "var(--ink)",
+          font: "inherit",
+        }}
+      />
+      <textarea
+        value={reply.body}
+        onChange={(e) => setReply({ ...reply, body: e.target.value })}
+        style={{
+          minHeight: "16em",
+          padding: "var(--space-2) var(--space-3)",
+          border: "var(--border-w) solid var(--border)",
+          borderRadius: "var(--radius-s)",
+          background: "var(--surface)",
+          color: "var(--ink)",
+          font: "inherit",
+        }}
+      />
+      <div style={{ display: "flex", justifyContent: "flex-end" }}>
+        <button
+          type="button"
+          className="primary"
+          disabled={reply.body.trim() === ""}
+          onClick={() => out({ approve: reply })}
+        >
+          この内容で送信
+        </button>
+      </div>
+      <div style={{ display: "flex", gap: "var(--space-2)" }}>
+        <input
+          value={prompt}
+          placeholder="差し戻しの理由"
+          onChange={(e) => setPrompt(e.target.value)}
+          style={{
+            flex: 1,
+            padding: "var(--space-2) var(--space-3)",
+            border: "var(--border-w) solid var(--border)",
+            borderRadius: "var(--radius-s)",
+            background: "var(--surface)",
+            color: "var(--ink)",
+            font: "inherit",
+          }}
+        />
+        <button
+          type="button"
+          className="ghost"
+          disabled={prompt.trim() === ""}
+          onClick={() => out({ reject: { prompt } })}
+        >
+          差し戻す
+        </button>
+      </div>
+    </div>
+  )
+})

package/views/slack.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest"
+import {
+  decisionActionId,
+  decisionFormActionId,
+  parseDecisionActionId,
+} from "./slack.js"
+
+// 決定ボタンのプロトコル：ビューは action_id だけで「どの出口ポートへ流すか」を宣言し、
+// ホストは押下を action_id から読み戻す。両者が同じ関数を使うので、往復で一致することを固定する
+
+describe("決定ボタンの action_id", () => {
+  it("そのまま確定は decision:<port_key>", () => {
+    expect(decisionActionId("approve")).toBe("decision:approve")
+    expect(parseDecisionActionId("decision:approve")).toEqual({
+      port_key: "approve",
+      form: false,
+    })
+  })
+
+  it("フォームで確定は decision-form:<port_key>", () => {
+    expect(decisionFormActionId("reject")).toBe("decision-form:reject")
+    expect(parseDecisionActionId("decision-form:reject")).toEqual({
+      port_key: "reject",
+      form: true,
+    })
+  })
+
+  it("port_key に区切り文字を含んでも往復で一致する", () => {
+    expect(parseDecisionActionId(decisionActionId("a:b"))).toEqual({
+      port_key: "a:b",
+      form: false,
+    })
+  })
+
+  it("決定ボタン以外の action_id は null", () => {
+    expect(parseDecisionActionId("approve")).toBeNull()
+    expect(parseDecisionActionId(undefined)).toBeNull()
+    expect(parseDecisionActionId("other:approve")).toBeNull()
+  })
+})

package/{slack-view.ts → views/slack.ts}

@@ -1,6 +1,6 @@
-import type { JsonSchema, NodeKind } from "./_schemas/node.js"
+import type { JsonSchema, NodeKind } from "../_schemas/node.js"
 
-// Slack ビューの契約（`@mawaru/sdk/slack-view`）。ノードの Slack ビュー
+// Slack ビューの契約（`@mawaru/sdk/views/slack`）。ノードの Slack ビュー
 // （nodes.slack_view_key）が実装する関数と、ホスト（mawaru）が渡す ctx の形の正。
 // mawaru 内蔵のビュー（backend の _helpers/slackViews/）と、顧客の実行 repo の
 // views/slack/<name>/ のビューが同じ契約で書く
@@ -43,7 +43,7 @@ export type SlackViewMaterial<TIn = unknown, TOut = unknown> = {
 }
 
 // 実行中メッセージの ctx（全 kind 共通）。TIn は in ポートの型
-// （human なら承認ビューの宣言が転写されたポートの型）
+// （human なら実装（nodes/human/）の宣言が転写されたポートの型）
 export type SlackViewContext<TIn = unknown> = {
   // ノードの kind。決定ボタン（承認・差し戻し）は human のときだけ意味を持つので、
   // 複数の kind で使うビューはこれを見てボタンを描くか決める