@mawaru/sdk 0.39.0 → 0.40.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/host.ts

@@ -0,0 +1,23 @@
+import { z } from "zod"
+import { VIEW_MESSAGE_TAG } from "./protocol.js"
+
+export { ApprovalActionsProvider } from "./_approvalActions.js"
+// ホスト（mawaru の画面）だけが使うもの（公開 API ではない）：sandbox iframe からのメッセージを確かめる形
+// （protocol.ts の型と同じ。iframe の中は信用できないコードなので、形を確かめてから使う）と、
+// ビューに頼む口を差す提供部品
+export { ViewBridgeProvider } from "./_bridge.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.string(),
+    args: z.unknown(),
+  }),
+])

package/views/human.ts

@@ -0,0 +1,91 @@
+import type { ReactNode } from "react"
+import type { JsonSchema } from "../_schemas/node.js"
+
+// human ノードの実装（nodes/human/<dir>/index.tsx）の約束（`@mawaru/sdk/human`）。承認画面（ビュー）は React の
+// コンポーネント1つで、承認画面の上の帯より下の全部（書類と承認バー）を描く。右上の閉じるボタン・差し戻し後の帯・
+// 差し戻しと追加の出口のダイアログ・認可・decision の POST・Broadcast の購読はホスト（mawaru の承認画面）に残る
+// （docs/tasks/wip/承認ビューの顧客repo配置.md の「承認バーもビューが描く」）。
+//
+// ctx に入るのは JSON で表現できる値だけ（React 要素・クラスインスタンス・ホストの関数は無い）。
+// 顧客 repo のビューは sandbox iframe の中で動き、ctx は postMessage で届く。
+// ホストに頼みたいこと（ファイルの URL・アップロード・コピー）は useViewBridge()、承認の操作は useApprovalActions() から
+//
+// TIn は実装が宣言（config.json の inputs.in）した形。宣言と型引数が食い違ってもコンパイルは通るので、
+// **一致はビュー実装の責任**（typegen の types.d.ts を使うと揃う）
+
+/** 承認画面の局面：承認待ち／承認済み／差し戻し後（AI 再実行待ち）／失敗／キャンセル */
+export type ApprovalPhase =
+  | "waiting"
+  | "approved"
+  | "rejected"
+  | "failed"
+  | "cancelled"
+
+/**
+ * 承認バーの材料。部品の `ApprovalBar` はこれをそのまま使う。承認バーを自分で書くときに読む。
+ */
+export type ApprovalDecisionContext = {
+  /** 見ている人が今決定できる（担当で承認待ち）。全員の承認が要るノードでも true（値を直せるかは `editable`） */
+  canDecide: boolean
+  /** 承認したあとに流れる先のノード名（つながっていなければ null） */
+  approveTargetName: string | null
+  /** 差し戻し先のノード名（無ければ差し戻せない） */
+  rejectTargetName: string | null
+  /** 承認・差し戻し以外の出口。`needsInput` は、今の値の型が出口と合わず、値を入れるダイアログが要るもの */
+  exits: { key: string; name: string; needsInput: boolean }[]
+  /** 担当でない人が開いたときの、担当の名前（担当なら null） */
+  otherAssignees: string[] | null
+  /** 全員の承認が要るときの進み具合（`approvedByMe` は自分がもう承認したか）。要らなければ null */
+  progress: { done: number; total: number; approvedByMe: boolean } | null
+  /** 失敗した step の理由（失敗していなければ null） */
+  failedReason: string | null
+}
+
+/** mawaru から承認ビューへ渡す材料 */
+export type ApprovalViewContext<TIn = unknown> = {
+  /** 届いた値（step の input そのもの）。ビューで直した値はビューの state に持つ */
+  output: TIn
+  /** `output` の型＝ human の in ポートの型（ビューの宣言が写っている）。`SchemaForm` に渡すとフォームになる */
+  outputSchema: JsonSchema | null
+  /** ループ変数（この step が始まった時点の写し）。予約キー `input` が run の起動入力 */
+  refs: unknown
+  /** この human ノードの名前 */
+  nodeName: string
+  /** 局面 */
+  phase: ApprovalPhase
+  /** 値を直してよい（承認待ちで、見ている人が担当。全員の承認が要るノードでは false） */
+  editable: boolean
+  /** 承認バーの材料 */
+  decision: ApprovalDecisionContext
+}
+
+/**
+ * 承認ビュー：ctx を受けて承認画面（上の帯より下の全部）を描く React コンポーネント。
+ * 承認バーは `<ApprovalBar ctx={ctx} />` を置く（置かなければ承認バーは出ない）。
+ */
+// 引数を双変にする（メソッドの形で宣言する）：どの TIn のビューも ApprovalView<unknown> として持てるようにするため
+export type ApprovalView<TIn = unknown> = {
+  bivariance(props: { ctx: ApprovalViewContext<TIn> }): ReactNode
+}["bivariance"]
+
+/** 承認ビューを定義する。型を付けるためだけの関数（値はそのまま返す） */
+export const defineApprovalView = <TIn = unknown>(
+  view: ApprovalView<TIn>,
+): ApprovalView<TIn> => view
+
+/** 手元プレビュー（npx mawaru preview human/<dir>）のケース。nodes/human/<dir>/cases.ts の export default */
+export type ApprovalViewCase = {
+  name: string
+  /** `ctx.output`（＝ step の input） */
+  input: unknown
+  refs?: unknown
+  /** 省略時は name */
+  nodeName?: string
+  /** 省略時は承認待ち */
+  phase?: ApprovalPhase
+}
+
+export { ApprovalBar } from "./_approval/ApprovalBar.js"
+export { type ApprovalActions, useApprovalActions } from "./_approvalActions.js"
+// 部品キット（土台）もここから import できる
+export * from "./index.js"

package/views/index.ts

@@ -0,0 +1,16 @@
+// ビューの部品キット（`@mawaru/sdk/views`）。種類（承認・…）に依らない土台：部品・ホストに頼む口。
+// mawaru が顧客 repo のビューをまとめるとき、mawaru の今の版のこのキットを同梱する。
+// **公開 API**：部品の props とホストに頼む口は後方互換でしか変えない
+// （docs/tasks/wip/承認ビューの顧客repo配置.md の「互換の管理」）
+export { useViewBridge, type ViewBridge } from "./_bridge.js"
+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/protocol.ts

@@ -0,0 +1,40 @@
+// sandbox iframe の中の実行部分（runtime.tsx）とホスト（mawaru の画面）とのメッセージの形。
+// **公開 API ではない**：iframe の中の実行部分とホストは同じデプロイの mawaru のコード（まとめるときに
+// その時点の版を同梱する）なので、いつ変えてもよい（docs/tasks/wip/承認ビューの顧客repo配置.md の「互換の管理」）。
+// iframe に入る JS を小さく保つため、ここには型と定数だけを置く（ホストの検査は host.ts）
+
+export const VIEW_MESSAGE_TAG = "mawaru:view"
+
+export type ThemeMode = "light" | "dark"
+
+// ビュー → ホスト
+export type ViewToHost =
+  | { tag: typeof VIEW_MESSAGE_TAG; type: "ready" }
+  // 描画の例外（ホストは標準ビューに差し替える）
+  | { tag: typeof VIEW_MESSAGE_TAG; type: "error"; message: string }
+  // ホストに頼む（fileUrl / uploadFile / copyText、承認ビューは decide / openRejectDialog / openExitDialog / close も）
+  | {
+      tag: typeof VIEW_MESSAGE_TAG
+      type: "request"
+      id: number
+      method: string
+      args: unknown
+    }
+
+// ホスト → ビュー
+export type HostToView =
+  | { tag: typeof VIEW_MESSAGE_TAG; type: "ctx"; ctx: unknown; 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,132 @@
+import { Component, type ReactNode } from "react"
+import { createRoot } from "react-dom/client"
+import {
+  type ApprovalActions,
+  ApprovalActionsProvider,
+} from "./_approvalActions.js"
+import { ViewBridgeProvider } from "./_bridge.js"
+import type { FileRef } from "./_parts/fileRef.js"
+import type { ApprovalView, ApprovalViewContext } from "./human.js"
+import {
+  type HostToView,
+  type ThemeMode,
+  VIEW_MESSAGE_TAG,
+  type ViewToHost,
+} from "./protocol.js"
+
+// sandbox iframe の中の実行部分（docs/tasks/wip/承認ビューの顧客repo配置.md の「隔離」）。
+// mawaru が顧客 repo のビューをまとめるとき、入口からここの runXxxView を呼ぶ。
+// ホストとのメッセージの形は protocol.ts（公開 API ではない）
+
+// ---- iframe の中 ----
+
+// 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 ctxListeners = new Set<(ctx: unknown, mode: ThemeMode) => 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 === "ctx") {
+    document.documentElement.dataset.mode = message.mode
+    for (const listener of ctxListeners) listener(message.ctx, message.mode)
+  }
+}
+
+// ホストに頼む（返事が来るまで待つ）
+export const requestHost = <T,>(method: string, 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 bridge = {
+  fileUrl: (file: FileRef) => requestHost<string>("fileUrl", { file }),
+  uploadFile: (file: File) => requestHost<FileRef>("uploadFile", { file }),
+  copyText: (text: string) => requestHost<void>("copyText", { text }),
+}
+
+// 描画の例外をホストへ知らせる（ホストは標準ビューに差し替える）
+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
+  }
+}
+
+// iframe の中の共通の準備：ホストからのメッセージ・例外の報告。
+// 最初の ctx が届いたら render を呼ぶ（以降の ctx も同じ render に渡す）
+const startView = (render: (ctx: unknown) => ReactNode) => {
+  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)
+  ctxListeners.add((ctx) =>
+    root.render(
+      <ViewBridgeProvider bridge={bridge}>
+        <ReportErrors>{render(ctx)}</ReportErrors>
+      </ViewBridgeProvider>,
+    ),
+  )
+  post({ type: "ready" })
+}
+
+// ---- 承認ビュー ----
+
+const actions: ApprovalActions = {
+  decide: (port, value) => requestHost<void>("decide", { port, value }),
+  openRejectDialog: () => requestHost<void>("openRejectDialog", {}),
+  openExitDialog: (key, value) =>
+    requestHost<void>("openExitDialog", { key, value }),
+  close: () => requestHost<void>("close", {}),
+}
+
+// ビューはコンポーネント1つ。状態（直した値・選択など）はビューが useState で持ち、ctx が変わっても
+// （局面・担当の更新）同じコンポーネントとして描き直すので保たれる
+export const runApprovalView = (View: ApprovalView) =>
+  startView((ctx) => (
+    <ApprovalActionsProvider value={actions}>
+      <View ctx={ctx as ApprovalViewContext} />
+    </ApprovalActionsProvider>
+  ))

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 で使うビューはこれを見てボタンを描くか決める