@alneas/appkit-react 0.1.0 → 0.3.0

package/dist/ai/proposal/types.d.cts

@@ -1,58 +1,129 @@
 import { ApplyProposalPayload, CandidateValidationResult, FieldDecision, FieldKey, ProposalReviewStatus, RecordProposal, ReviewDecisions } from '@alneas/appkit-core/ai';
-/** Props for ProposalReviewCard. */
+/**
+ * Single-record review presentation and host apply inputs.
+ *
+ * @typeParam TRecord - Current record shape; defaults to a string-keyed record.
+ *
+ * @remarks These shared inputs are consumed by useProposalReview; persistence is host-owned.
+ *
+ * @see useProposalReview for a complete input example.
+ */
 export interface ProposalReviewCardProps<TRecord extends Record<string, any> = Record<string, any>> {
-    /** 変更提案オブジェクト（イミュータブル） */
+    /**
+     * Immutable validated change proposal; changing id resets the review decisions.
+     */
     proposal: RecordProposal<TRecord>;
-    /** 最新の元データレコード */
+    /**
+     * Latest host record used to compose accepted changes and detect conflicts.
+     */
     currentRecord: TRecord;
-    /** アプリケーションが保持する元データの現在バージョン */
+    /**
+     * Current host version compared with the proposal base version.
+     */
     currentVersion: string | number;
     /**
-     * レコード全体の業務検証関数（相関チェックやスキーマ検証）
-     * 候補レコード（現在値＋採用分）全体を検証します。
+     * Optional synchronous validation of the complete composed candidate; thrown errors propagate from render.
      */
     validateCandidate?: (candidate: TRecord) => CandidateValidationResult;
     /**
-     * 適用ハンドラ（フォームへの反映、またはサーバーへの永続化リクエスト）
+     * Optional host apply callback receiving a payload; await persistence before resolving. Rejection becomes saveError.
      */
     onApply?: (payload: ApplyProposalPayload<TRecord>) => void | Promise<void>;
-    /** 提案全体の破棄・スキップハンドラ */
+    /**
+     * Optional host dismissal callback; the headless hook does not call this member.
+     */
     onDismiss?: () => void;
-    /** 適用ボタンのラベル（デフォルト: "適用する"） */
+    /**
+     * Optional presentation label; not used by the headless hook.
+     */
     applyLabel?: string;
-    /** カードの見出し（デフォルト: proposal.targetName または "変更提案の確認"） */
+    /**
+     * Optional presentation title; not used by the headless hook.
+     */
     title?: string;
-    /** カスタムクラス名 */
+    /**
+     * Optional presentation classes; not used by the headless hook.
+     */
     className?: string;
-    /** テストID */
+    /**
+     * Optional presentation test marker; not used by the headless hook.
+     */
     testId?: string;
 }
-/** Return type of useProposalReview hook. */
+/**
+ * Derived review state and explicit field-decision/apply controls.
+ *
+ * @typeParam TRecord - Record shape retained by candidate composition; defaults to a string-keyed record.
+ *
+ * @see useProposalReview for usage.
+ */
 export interface UseProposalReviewReturn<TRecord extends Record<string, any> = Record<string, any>> {
-    /** 各フィールドの決定マップ */
+    /**
+     * Per-field pending/accepted/rejected choices; missing entries behave as pending.
+     */
     decisions: ReviewDecisions<TRecord>;
-    /** 特定フィールドの決定を更新 */
+    /**
+     * Set one field choice and clear the save error.
+     *
+     * @param field - Record key to decide.
+     *
+     * @param decision - Pending, accepted or rejected choice.
+     *
+     * @returns No value after scheduling state.
+     */
     setDecision: (field: FieldKey<TRecord>, decision: FieldDecision) => void;
-    /** 全フィールドを一括で採用 */
+    /**
+     * Mark every proposed change accepted.
+     *
+     * @returns No value after scheduling choices and clearing the save error.
+     */
     acceptAll: () => void;
-    /** 全フィールドを一括で却下 */
+    /**
+     * Mark every proposed change rejected.
+     *
+     * @returns No value after scheduling choices and clearing the save error.
+     */
     rejectAll: () => void;
-    /** 全フィールドの選択を初期状態（pending）にリセット */
+    /**
+     * Remove explicit choices so every change returns to pending.
+     *
+     * @returns No value after scheduling choices and clearing the save error.
+     */
     resetDecisions: () => void;
-    /** 合成された候補レコード */
+    /**
+     * Current record with accepted proposal changes composed into a new candidate.
+     */
     candidateRecord: TRecord;
-    /** 全体のレビュー決定状況 */
+    /**
+     * Derived aggregate decision status.
+     */
     reviewStatus: ProposalReviewStatus;
-    /** 現在値・バージョンとの整合性チェック結果 */
+    /**
+     * Current-value/version compatibility check for the selected changes.
+     */
     consistency: ReturnType<typeof import('@alneas/appkit-core/ai/proposal').verifyCurrentState<TRecord>>;
-    /** 候補レコード全体の検証結果 */
+    /**
+     * Optional complete-candidate validation result; undefined when no validator is supplied.
+     */
     candidateValidation?: CandidateValidationResult;
-    /** 適用可能かどうか */
+    /**
+     * Whether decisions/consistency/validation permit application and onApply exists.
+     */
     canApply: boolean;
-    /** 適用実行中フラグ */
+    /**
+     * Whether this displayed review is awaiting host apply completion.
+     */
     isSubmitting: boolean;
-    /** 保存/適用失敗時のエラーメッセージ */
+    /**
+     * Last current-generation apply failure message, or null.
+     */
     saveError: string | null;
-    /** 適用処理の実行関数 */
+    /**
+     * Apply a prepared payload through the host callback at most once concurrently per displayed generation.
+     *
+     * @returns True after current-generation success; false when blocked, failed or completed for an older generation.
+     *
+     * @remarks Errors from payload/application are caught as saveError; the host owns durable side effects and rollback.
+     */
     handleApply: () => Promise<boolean>;
 }

package/dist/ai/proposal/types.d.ts

@@ -1,58 +1,129 @@
 import { ApplyProposalPayload, CandidateValidationResult, FieldDecision, FieldKey, ProposalReviewStatus, RecordProposal, ReviewDecisions } from '@alneas/appkit-core/ai';
-/** Props for ProposalReviewCard. */
+/**
+ * Single-record review presentation and host apply inputs.
+ *
+ * @typeParam TRecord - Current record shape; defaults to a string-keyed record.
+ *
+ * @remarks These shared inputs are consumed by useProposalReview; persistence is host-owned.
+ *
+ * @see useProposalReview for a complete input example.
+ */
 export interface ProposalReviewCardProps<TRecord extends Record<string, any> = Record<string, any>> {
-    /** 変更提案オブジェクト（イミュータブル） */
+    /**
+     * Immutable validated change proposal; changing id resets the review decisions.
+     */
     proposal: RecordProposal<TRecord>;
-    /** 最新の元データレコード */
+    /**
+     * Latest host record used to compose accepted changes and detect conflicts.
+     */
     currentRecord: TRecord;
-    /** アプリケーションが保持する元データの現在バージョン */
+    /**
+     * Current host version compared with the proposal base version.
+     */
     currentVersion: string | number;
     /**
-     * レコード全体の業務検証関数（相関チェックやスキーマ検証）
-     * 候補レコード（現在値＋採用分）全体を検証します。
+     * Optional synchronous validation of the complete composed candidate; thrown errors propagate from render.
      */
     validateCandidate?: (candidate: TRecord) => CandidateValidationResult;
     /**
-     * 適用ハンドラ（フォームへの反映、またはサーバーへの永続化リクエスト）
+     * Optional host apply callback receiving a payload; await persistence before resolving. Rejection becomes saveError.
      */
     onApply?: (payload: ApplyProposalPayload<TRecord>) => void | Promise<void>;
-    /** 提案全体の破棄・スキップハンドラ */
+    /**
+     * Optional host dismissal callback; the headless hook does not call this member.
+     */
     onDismiss?: () => void;
-    /** 適用ボタンのラベル（デフォルト: "適用する"） */
+    /**
+     * Optional presentation label; not used by the headless hook.
+     */
     applyLabel?: string;
-    /** カードの見出し（デフォルト: proposal.targetName または "変更提案の確認"） */
+    /**
+     * Optional presentation title; not used by the headless hook.
+     */
     title?: string;
-    /** カスタムクラス名 */
+    /**
+     * Optional presentation classes; not used by the headless hook.
+     */
     className?: string;
-    /** テストID */
+    /**
+     * Optional presentation test marker; not used by the headless hook.
+     */
     testId?: string;
 }
-/** Return type of useProposalReview hook. */
+/**
+ * Derived review state and explicit field-decision/apply controls.
+ *
+ * @typeParam TRecord - Record shape retained by candidate composition; defaults to a string-keyed record.
+ *
+ * @see useProposalReview for usage.
+ */
 export interface UseProposalReviewReturn<TRecord extends Record<string, any> = Record<string, any>> {
-    /** 各フィールドの決定マップ */
+    /**
+     * Per-field pending/accepted/rejected choices; missing entries behave as pending.
+     */
     decisions: ReviewDecisions<TRecord>;
-    /** 特定フィールドの決定を更新 */
+    /**
+     * Set one field choice and clear the save error.
+     *
+     * @param field - Record key to decide.
+     *
+     * @param decision - Pending, accepted or rejected choice.
+     *
+     * @returns No value after scheduling state.
+     */
     setDecision: (field: FieldKey<TRecord>, decision: FieldDecision) => void;
-    /** 全フィールドを一括で採用 */
+    /**
+     * Mark every proposed change accepted.
+     *
+     * @returns No value after scheduling choices and clearing the save error.
+     */
     acceptAll: () => void;
-    /** 全フィールドを一括で却下 */
+    /**
+     * Mark every proposed change rejected.
+     *
+     * @returns No value after scheduling choices and clearing the save error.
+     */
     rejectAll: () => void;
-    /** 全フィールドの選択を初期状態（pending）にリセット */
+    /**
+     * Remove explicit choices so every change returns to pending.
+     *
+     * @returns No value after scheduling choices and clearing the save error.
+     */
     resetDecisions: () => void;
-    /** 合成された候補レコード */
+    /**
+     * Current record with accepted proposal changes composed into a new candidate.
+     */
     candidateRecord: TRecord;
-    /** 全体のレビュー決定状況 */
+    /**
+     * Derived aggregate decision status.
+     */
     reviewStatus: ProposalReviewStatus;
-    /** 現在値・バージョンとの整合性チェック結果 */
+    /**
+     * Current-value/version compatibility check for the selected changes.
+     */
     consistency: ReturnType<typeof import('@alneas/appkit-core/ai/proposal').verifyCurrentState<TRecord>>;
-    /** 候補レコード全体の検証結果 */
+    /**
+     * Optional complete-candidate validation result; undefined when no validator is supplied.
+     */
     candidateValidation?: CandidateValidationResult;
-    /** 適用可能かどうか */
+    /**
+     * Whether decisions/consistency/validation permit application and onApply exists.
+     */
     canApply: boolean;
-    /** 適用実行中フラグ */
+    /**
+     * Whether this displayed review is awaiting host apply completion.
+     */
     isSubmitting: boolean;
-    /** 保存/適用失敗時のエラーメッセージ */
+    /**
+     * Last current-generation apply failure message, or null.
+     */
     saveError: string | null;
-    /** 適用処理の実行関数 */
+    /**
+     * Apply a prepared payload through the host callback at most once concurrently per displayed generation.
+     *
+     * @returns True after current-generation success; false when blocked, failed or completed for an older generation.
+     *
+     * @remarks Errors from payload/application are caught as saveError; the host owns durable side effects and rollback.
+     */
     handleApply: () => Promise<boolean>;
 }

package/dist/ai/proposal/use-proposal-batch-review.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-proposal-batch-review.cjs","names":["createExecutionSession","useState","useRef","useSyncExternalStore","prepareProposalBatch","react","_alneas_appkit_core_ai","initial","useProposalBatchReview","key","options","item","stored","setStored","state","session","live","latest","current","history","busy","record","update","change","entries","items","applied","preparation","editable","id","next","value","selected","field","decision","planned","outcome","context","completed","payload","checked","fraction","progress"],"sources":["../../../src/ai/proposal/use-proposal-batch-review.ts"],"sourcesContent":["import { useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';\nimport { createExecutionSession, type ExecutionContext, type ExecutionRecord, type ExecutionSession } from \"@alneas/appkit-core/ai\";\nimport {\n  prepareProposalBatch,\n  type ApplyProposalPayload,\n  type FieldDecision,\n  type FieldKey,\n  type PreparedProposalBatch,\n  type ProposalBatchEntry,\n  type ProposalBatchItem,\n  type ProposalBatchValidator,\n  type ReviewDecisions,\n} from \"@alneas/appkit-core/ai\";\n\n/** Multi-record review. Each item must have a unique validated immutable proposal. */\nexport interface UseProposalBatchReviewOptions<TRecord extends Record<string, any> = Record<string, any>> {\n  /** Change for a new review session, including an intentional replay of the same proposals. */\n  batchId: string;\n  items: readonly ProposalBatchItem<TRecord>[];\n  validateCandidate?: ProposalBatchValidator<TRecord>;\n  /** Called sequentially. Resolve only when this row is applied; reject to stop the batch. */\n  onApply?: (payload: ApplyProposalPayload<TRecord>, context: ExecutionContext) => void | Promise<void>;\n}\n\n/** Headless controller shared by batch lists and custom application layouts. */\nexport interface UseProposalBatchReviewReturn<TRecord extends Record<string, any> = Record<string, any>> {\n  selectedIds: ReadonlySet<string>;\n  appliedIds: ReadonlySet<string>;\n  decisions: ReadonlyMap<string, ReviewDecisions<TRecord>>;\n  preparation: PreparedProposalBatch<TRecord>;\n  canApply: boolean;\n  isSubmitting: boolean;\n  activeProposalId: string | null;\n  error: string | null;\n  history: readonly ExecutionRecord[];\n  setSelected(id: string, selected: boolean): void;\n  selectAll(selected: boolean): void;\n  setDecision(id: string, field: FieldKey<TRecord>, decision: FieldDecision): void;\n  decideAll(id: string, decision: FieldDecision): void;\n  apply(): Promise<boolean>;\n  cancel(): void;\n  clearHistory(): void;\n}\n\ninterface ReviewState<TRecord extends Record<string, any>> {\n  key: string;\n  session: ExecutionSession;\n  selected: ReadonlySet<string>;\n  applied: ReadonlySet<string>;\n  decisions: ReadonlyMap<string, ReviewDecisions<TRecord>>;\n  running: boolean;\n  active: string | null;\n  error: string | null;\n}\n\nfunction initial<TRecord extends Record<string, any>>(key: string): ReviewState<TRecord> {\n  return {\n    key,\n    session: createExecutionSession(),\n    selected: new Set(),\n    applied: new Set(),\n    decisions: new Map(),\n    running: false,\n    active: null,\n    error: null,\n  };\n}\n\n/**\n * Reviews multiple records without implicit field acceptance. Preflights the entire\n * selection, then rechecks each latest committed record immediately before applying it.\n * Stops on first failure or cancellation; confirmed successes are never retried within\n * this session.\n */\nexport function useProposalBatchReview<TRecord extends Record<string, any> = Record<string, any>>(\n  options: UseProposalBatchReviewOptions<TRecord>\n): UseProposalBatchReviewReturn<TRecord> {\n  const key = JSON.stringify([options.batchId, options.items.map(item => JSON.stringify(item.proposal)).sort()]);\n  const [stored, setStored] = useState(() => initial<TRecord>(key));\n  let state = stored;\n  if (state.key !== key) {\n    state = initial<TRecord>(key);\n    setStored(state);\n  }\n  const session = state.session;\n  const live = useRef<{ session: ExecutionSession; applied: Set<string> } | null>(null);\n  const latest = useRef(options);\n  useLayoutEffect(() => {\n    latest.current = options;\n  });\n  useLayoutEffect(() => {\n    const current = { session, applied: new Set<string>() };\n    live.current = current;\n    return () => {\n      session.cancel();\n      if (live.current === current) live.current = null;\n    };\n  }, [session]);\n\n  const history = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);\n  const busy = () => session.getSnapshot().some(record => record.status === 'running' || record.status === 'cancelling');\n  const update = (change: (current: ReviewState<TRecord>) => ReviewState<TRecord>) => {\n    setStored(current => (current.session === session ? change(current) : current));\n  };\n\n  const entries = (\n    items: readonly ProposalBatchItem<TRecord>[],\n    applied: ReadonlySet<string>\n  ): ProposalBatchEntry<TRecord>[] =>\n    items.map(item => ({\n      ...item,\n      decisions: state.decisions.get(item.proposal.id) ?? ({} as ReviewDecisions<TRecord>),\n      selected: state.selected.has(item.proposal.id) && !applied.has(item.proposal.id),\n    }));\n\n  const preparation = prepareProposalBatch(entries(options.items, state.applied), options.validateCandidate);\n  const editable = (id: string) =>\n    live.current?.session === session && !busy() && !live.current.applied.has(id) && options.items.some(item => item.proposal.id === id);\n\n  const apply = async (): Promise<boolean> => {\n    const current = live.current;\n    if (!current || current.session !== session || busy() || !latest.current.onApply) return false;\n    const planned = prepareProposalBatch(entries(latest.current.items, current.applied), latest.current.validateCandidate);\n    if (!planned.canApply) return false;\n    update(value => ({ ...value, running: true, error: null }));\n    const outcome = await session.run(`一括適用 ${planned.payloads.length} 件`, async context => {\n      context.reportProgress({ completed: 0, total: planned.payloads.length });\n      let completed = 0;\n      for (const payload of planned.payloads) {\n        context.signal.throwIfAborted();\n        if (live.current !== current) throw new DOMException('Review session changed', 'AbortError');\n        const item = latest.current.items.find(value => value.proposal.id === payload.proposalId);\n        if (!item) throw new Error('対象の提案が見つかりません。再確認してください。');\n        const checked = prepareProposalBatch(\n          [{ ...item, selected: true, decisions: state.decisions.get(payload.proposalId) ?? ({} as ReviewDecisions<TRecord>) }],\n          latest.current.validateCandidate\n        );\n        if (!checked.canApply || !latest.current.onApply) {\n          throw new Error('適用前にデータが変更されたため停止しました。再確認してください。');\n        }\n        update(value => ({ ...value, active: payload.proposalId }));\n        await latest.current.onApply(checked.payloads[0], {\n          signal: context.signal,\n          reportProgress(progress) {\n            const fraction =\n              progress.total && Number.isFinite(progress.total) && Number.isFinite(progress.completed)\n                ? Math.max(0, Math.min(1, progress.completed / progress.total))\n                : 0;\n            context.reportProgress({\n              completed: completed + fraction,\n              total: planned.payloads.length,\n              message: progress.message,\n            });\n          },\n        });\n        if (live.current !== current) throw new DOMException('Review session changed', 'AbortError');\n        current.applied.add(payload.proposalId);\n        update(value => ({ ...value, applied: new Set(current.applied) }));\n        context.reportProgress({ completed: ++completed, total: planned.payloads.length });\n      }\n    });\n    if (live.current !== current) return false;\n    update(value => ({\n      ...value,\n      running: false,\n      active: null,\n      error: outcome.status === 'failed' ? '適用に失敗しました。成功済みの提案を除いて再試行できます。' : null,\n    }));\n    return outcome.status === 'succeeded';\n  };\n\n  return {\n    selectedIds: state.selected,\n    appliedIds: state.applied,\n    decisions: state.decisions,\n    preparation,\n    canApply: !!options.onApply && preparation.canApply && !state.running,\n    isSubmitting: state.running,\n    activeProposalId: state.active,\n    error: state.error,\n    history,\n    setSelected(id, selected) {\n      if (!editable(id)) return;\n      update(value => {\n        const next = new Set(value.selected);\n        if (selected) next.add(id);\n        else next.delete(id);\n        return { ...value, selected: next, error: null };\n      });\n    },\n    selectAll(selected) {\n      if (busy()) return;\n      update(value => ({\n        ...value,\n        selected: new Set(selected ? options.items.map(item => item.proposal.id) : value.applied),\n        error: null,\n      }));\n    },\n    setDecision(id, field, decision) {\n      if (!editable(id) || !options.items.find(item => item.proposal.id === id)?.proposal.changes.some(change => change.field === field)) return;\n      update(value => ({\n        ...value,\n        decisions: new Map(value.decisions).set(id, {\n          ...value.decisions.get(id),\n          [field]: decision,\n        } as ReviewDecisions<TRecord>),\n        error: null,\n      }));\n    },\n    decideAll(id, decision) {\n      if (!editable(id)) return;\n      const item = options.items.find(value => value.proposal.id === id)!;\n      update(value => ({\n        ...value,\n        decisions: new Map(value.decisions).set(\n          id,\n          Object.fromEntries(item.proposal.changes.map(change => [change.field, decision])) as ReviewDecisions<TRecord>\n        ),\n        error: null,\n      }));\n    },\n    apply,\n    cancel: session.cancel,\n    clearHistory: session.clearHistory,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"use-proposal-batch-review.cjs","names":["createExecutionSession","useState","useRef","useSyncExternalStore","prepareProposalBatch","react","_alneas_appkit_core_ai","initial","useProposalBatchReview","key","options","item","stored","setStored","state","session","live","latest","current","history","busy","record","update","change","entries","items","applied","preparation","editable","id","next","value","selected","field","decision","planned","outcome","context","completed","payload","checked","fraction","progress"],"sources":["../../../src/ai/proposal/use-proposal-batch-review.ts"],"sourcesContent":["import { useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';\nimport { createExecutionSession, type ExecutionContext, type ExecutionRecord, type ExecutionSession } from \"@alneas/appkit-core/ai\";\nimport {\n  prepareProposalBatch,\n  type ApplyProposalPayload,\n  type FieldDecision,\n  type FieldKey,\n  type PreparedProposalBatch,\n  type ProposalBatchEntry,\n  type ProposalBatchItem,\n  type ProposalBatchValidator,\n  type ReviewDecisions,\n} from \"@alneas/appkit-core/ai\";\n\n/**\n * Host inputs for reviewing unique immutable proposals across multiple records.\n *\n * @typeParam TRecord - Record shape; defaults to a string-keyed record.\n *\n * @see useProposalBatchReview for usage.\n */\nexport interface UseProposalBatchReviewOptions<TRecord extends Record<string, any> = Record<string, any>> {\n  /** Change for a new review session, including an intentional replay of the same proposals. */\n  batchId: string;\n  /**\n   * Validated proposals and latest records/versions; proposal IDs must be unique.\n   */\n  items: readonly ProposalBatchItem<TRecord>[];\n  /**\n   * Optional synchronous validator passed to Core batch preparation; thrown errors become invalid_candidate issues.\n   */\n  validateCandidate?: ProposalBatchValidator<TRecord>;\n    /**\n     * Sequential host callback receiving one prepared payload and cooperative abort/progress context.\n     *\n     * @param payload - Validated candidate and decisions for one proposal.\n     *\n     * @param context - Abort signal and fractional-progress reporting for this row.\n     *\n     * @returns No value after the host confirms application; reject to stop later rows.\n     */\n  onApply?: (payload: ApplyProposalPayload<TRecord>, context: ExecutionContext) => void | Promise<void>;\n}\n\n/**\n * Batch selection/decision state and explicit execution controls.\n *\n * @typeParam TRecord - Shared record shape; defaults to a string-keyed record.\n *\n * @see useProposalBatchReview for usage.\n */\nexport interface UseProposalBatchReviewReturn<TRecord extends Record<string, any> = Record<string, any>> {\n  /**\n   * Current selected proposal IDs; applied IDs are excluded from preparation.\n   */\n  selectedIds: ReadonlySet<string>;\n  /**\n   * Host-confirmed successes in this review session.\n   */\n  appliedIds: ReadonlySet<string>;\n  /**\n   * Per-proposal field decisions; absent choices remain pending.\n   */\n  decisions: ReadonlyMap<string, ReviewDecisions<TRecord>>;\n  /**\n   * Core batch preflight result for current selection and latest input props.\n   */\n  preparation: PreparedProposalBatch<TRecord>;\n  /**\n   * Whether a handler exists, preparation passes and state is not submitting.\n   */\n  canApply: boolean;\n  /**\n   * Whether the displayed batch is currently running.\n   */\n  isSubmitting: boolean;\n  /**\n   * Current row being applied, or null outside active row work.\n   */\n  activeProposalId: string | null;\n  /**\n   * Generic current-session batch failure message, or null; raw host exceptions are not exposed.\n   */\n  error: string | null;\n  /**\n   * Read-only execution history for this batch session.\n   */\n  history: readonly ExecutionRecord[];\n  /**\n   * Select or deselect an editable known proposal.\n   *\n   * @param id - Proposal identifier.\n   *\n   * @param selected - Desired selection state.\n   *\n   * @returns No value; unknown/applied/busy proposals are ignored.\n   */\n  setSelected(id: string, selected: boolean): void;\n  /**\n   * Change selection for the current items when idle.\n   *\n   * @param selected - True selects all current IDs; false retains only applied IDs in the selection set.\n   *\n   * @returns No value; calls while execution is busy are ignored.\n   */\n  selectAll(selected: boolean): void;\n  /**\n   * Change one existing proposed field while editable.\n   *\n   * @param id - Proposal identifier.\n   *\n   * @param field - Field present in that proposal.\n   *\n   * @param decision - Pending, accepted or rejected choice.\n   *\n   * @returns No value; invalid IDs/fields and busy/applied proposals are ignored.\n   */\n  setDecision(id: string, field: FieldKey<TRecord>, decision: FieldDecision): void;\n  /**\n   * Change every proposed field choice for one editable proposal.\n   *\n   * @param id - Proposal identifier.\n   *\n   * @param decision - Choice applied to all its changes.\n   *\n   * @returns No value; unknown/applied/busy proposals are ignored.\n   */\n  decideAll(id: string, decision: FieldDecision): void;\n  /**\n   * Preflight the selection, then apply rows sequentially with latest-record rechecks.\n   *\n   * @returns True only for current-session complete success; false when blocked, failed, cancelled or superseded.\n   *\n   * @remarks Confirmed successes are retained and skipped on retry; unconfirmed backend effects may still exist.\n   */\n  apply(): Promise<boolean>;\n  /**\n   * Request cooperative cancellation of current execution.\n   *\n   * @returns No value; does not roll back previously applied rows or force host work to stop.\n   */\n  cancel(): void;\n  /**\n   * Clear settled execution history using the session policy.\n   *\n   * @returns No value; does not clear review choices or confirmed applied IDs.\n   */\n  clearHistory(): void;\n}\n\ninterface ReviewState<TRecord extends Record<string, any>> {\n  key: string;\n  session: ExecutionSession;\n  selected: ReadonlySet<string>;\n  applied: ReadonlySet<string>;\n  decisions: ReadonlyMap<string, ReviewDecisions<TRecord>>;\n  running: boolean;\n  active: string | null;\n  error: string | null;\n}\n\nfunction initial<TRecord extends Record<string, any>>(key: string): ReviewState<TRecord> {\n  return {\n    key,\n    session: createExecutionSession(),\n    selected: new Set(),\n    applied: new Set(),\n    decisions: new Map(),\n    running: false,\n    active: null,\n    error: null,\n  };\n}\n\n/**\n * Reviews a batch with explicit field decisions and sequential host application.\n *\n * @typeParam TRecord - Record shape; defaults to a string-keyed record.\n *\n * @param options - Batch identity, unique immutable proposals/latest records, validation and optional host apply callback.\n *\n * @returns Selection/decision controls, preflight state, bounded execution history and cooperative cancellation.\n *\n * @remarks Requires React; no context/styles. Changing batchId or serialized proposal\n * content starts a new session; unmount/session changes request cancellation. Each row\n * is rechecked against latest committed host inputs before apply. Stops at the first\n * failure/cancellation; successes remain excluded from retries. Cancellation cannot\n * undo host effects, so persist idempotently and enforce concurrency/authorization in\n * the backend. A row that changed the backend before rejecting has an uncertain outcome.\n * Keep the ref/layout-effect bridge for latest host inputs: the returned apply control\n * can be called by UI event handlers and other host code outside Effect logic.\n * useEffectEvent is restricted to Effect-originated callbacks and cannot replace this\n * externally callable execution path. The ref is not a React 18 compatibility shim.\n *\n * @example\n * ```tsx\n * import { useProposalBatchReview, type UseProposalBatchReviewOptions } from '@alneas/appkit-react/ai/proposal';\n * type RecordData = { title: string };\n * export function Batch({ options }: { options: UseProposalBatchReviewOptions<RecordData> }) {\n *   const review = useProposalBatchReview(options);\n *   return <button disabled={!review.canApply} onClick={() => { void review.apply(); }}>Apply selected records</button>;\n * }\n * ```\n */\nexport function useProposalBatchReview<TRecord extends Record<string, any> = Record<string, any>>(\n  options: UseProposalBatchReviewOptions<TRecord>\n): UseProposalBatchReviewReturn<TRecord> {\n  const key = JSON.stringify([options.batchId, options.items.map(item => JSON.stringify(item.proposal)).sort()]);\n  const [stored, setStored] = useState(() => initial<TRecord>(key));\n  let state = stored;\n  if (state.key !== key) {\n    state = initial<TRecord>(key);\n    setStored(state);\n  }\n  const session = state.session;\n  const live = useRef<{ session: ExecutionSession; applied: Set<string> } | null>(null);\n  const latest = useRef(options);\n  useLayoutEffect(() => {\n    latest.current = options;\n  });\n  useLayoutEffect(() => {\n    const current = { session, applied: new Set<string>() };\n    live.current = current;\n    return () => {\n      session.cancel();\n      if (live.current === current) live.current = null;\n    };\n  }, [session]);\n\n  const history = useSyncExternalStore(session.subscribe, session.getSnapshot, session.getSnapshot);\n  const busy = () => session.getSnapshot().some(record => record.status === 'running' || record.status === 'cancelling');\n  const update = (change: (current: ReviewState<TRecord>) => ReviewState<TRecord>) => {\n    setStored(current => (current.session === session ? change(current) : current));\n  };\n\n  const entries = (\n    items: readonly ProposalBatchItem<TRecord>[],\n    applied: ReadonlySet<string>\n  ): ProposalBatchEntry<TRecord>[] =>\n    items.map(item => ({\n      ...item,\n      decisions: state.decisions.get(item.proposal.id) ?? ({} as ReviewDecisions<TRecord>),\n      selected: state.selected.has(item.proposal.id) && !applied.has(item.proposal.id),\n    }));\n\n  const preparation = prepareProposalBatch(entries(options.items, state.applied), options.validateCandidate);\n  const editable = (id: string) =>\n    live.current?.session === session && !busy() && !live.current.applied.has(id) && options.items.some(item => item.proposal.id === id);\n\n  const apply = async (): Promise<boolean> => {\n    const current = live.current;\n    if (!current || current.session !== session || busy() || !latest.current.onApply) return false;\n    const planned = prepareProposalBatch(entries(latest.current.items, current.applied), latest.current.validateCandidate);\n    if (!planned.canApply) return false;\n    update(value => ({ ...value, running: true, error: null }));\n    const outcome = await session.run(`一括適用 ${planned.payloads.length} 件`, async context => {\n      context.reportProgress({ completed: 0, total: planned.payloads.length });\n      let completed = 0;\n      for (const payload of planned.payloads) {\n        context.signal.throwIfAborted();\n        if (live.current !== current) throw new DOMException('Review session changed', 'AbortError');\n        const item = latest.current.items.find(value => value.proposal.id === payload.proposalId);\n        if (!item) throw new Error('対象の提案が見つかりません。再確認してください。');\n        const checked = prepareProposalBatch(\n          [{ ...item, selected: true, decisions: state.decisions.get(payload.proposalId) ?? ({} as ReviewDecisions<TRecord>) }],\n          latest.current.validateCandidate\n        );\n        if (!checked.canApply || !latest.current.onApply) {\n          throw new Error('適用前にデータが変更されたため停止しました。再確認してください。');\n        }\n        update(value => ({ ...value, active: payload.proposalId }));\n        await latest.current.onApply(checked.payloads[0], {\n          signal: context.signal,\n          reportProgress(progress) {\n            const fraction =\n              progress.total && Number.isFinite(progress.total) && Number.isFinite(progress.completed)\n                ? Math.max(0, Math.min(1, progress.completed / progress.total))\n                : 0;\n            context.reportProgress({\n              completed: completed + fraction,\n              total: planned.payloads.length,\n              message: progress.message,\n            });\n          },\n        });\n        if (live.current !== current) throw new DOMException('Review session changed', 'AbortError');\n        current.applied.add(payload.proposalId);\n        update(value => ({ ...value, applied: new Set(current.applied) }));\n        context.reportProgress({ completed: ++completed, total: planned.payloads.length });\n      }\n    });\n    if (live.current !== current) return false;\n    update(value => ({\n      ...value,\n      running: false,\n      active: null,\n      error: outcome.status === 'failed' ? '適用に失敗しました。成功済みの提案を除いて再試行できます。' : null,\n    }));\n    return outcome.status === 'succeeded';\n  };\n\n  return {\n    selectedIds: state.selected,\n    appliedIds: state.applied,\n    decisions: state.decisions,\n    preparation,\n    canApply: !!options.onApply && preparation.canApply && !state.running,\n    isSubmitting: state.running,\n    activeProposalId: state.active,\n    error: state.error,\n    history,\n    setSelected(id, selected) {\n      if (!editable(id)) return;\n      update(value => {\n        const next = new Set(value.selected);\n        if (selected) next.add(id);\n        else next.delete(id);\n        return { ...value, selected: next, error: null };\n      });\n    },\n    selectAll(selected) {\n      if (busy()) return;\n      update(value => ({\n        ...value,\n        selected: new Set(selected ? options.items.map(item => item.proposal.id) : value.applied),\n        error: null,\n      }));\n    },\n    setDecision(id, field, decision) {\n      if (!editable(id) || !options.items.find(item => item.proposal.id === id)?.proposal.changes.some(change => change.field === field)) return;\n      update(value => ({\n        ...value,\n        decisions: new Map(value.decisions).set(id, {\n          ...value.decisions.get(id),\n          [field]: decision,\n        } as ReviewDecisions<TRecord>),\n        error: null,\n      }));\n    },\n    decideAll(id, decision) {\n      if (!editable(id)) return;\n      const item = options.items.find(value => value.proposal.id === id)!;\n      update(value => ({\n        ...value,\n        decisions: new Map(value.decisions).set(\n          id,\n          Object.fromEntries(item.proposal.changes.map(change => [change.field, decision])) as ReviewDecisions<TRecord>\n        ),\n        error: null,\n      }));\n    },\n    apply,\n    cancel: session.cancel,\n    clearHistory: session.clearHistory,\n  };\n}\n"],"mappings":"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"}

package/dist/ai/proposal/use-proposal-batch-review.d.cts

@@ -1,36 +1,166 @@
 import { ExecutionContext, ExecutionRecord, ApplyProposalPayload, FieldDecision, FieldKey, PreparedProposalBatch, ProposalBatchItem, ProposalBatchValidator, ReviewDecisions } from '@alneas/appkit-core/ai';
-/** Multi-record review. Each item must have a unique validated immutable proposal. */
+/**
+ * Host inputs for reviewing unique immutable proposals across multiple records.
+ *
+ * @typeParam TRecord - Record shape; defaults to a string-keyed record.
+ *
+ * @see useProposalBatchReview for usage.
+ */
 export interface UseProposalBatchReviewOptions<TRecord extends Record<string, any> = Record<string, any>> {
     /** Change for a new review session, including an intentional replay of the same proposals. */
     batchId: string;
+    /**
+     * Validated proposals and latest records/versions; proposal IDs must be unique.
+     */
     items: readonly ProposalBatchItem<TRecord>[];
+    /**
+     * Optional synchronous validator passed to Core batch preparation; thrown errors become invalid_candidate issues.
+     */
     validateCandidate?: ProposalBatchValidator<TRecord>;
-    /** Called sequentially. Resolve only when this row is applied; reject to stop the batch. */
+    /**
+     * Sequential host callback receiving one prepared payload and cooperative abort/progress context.
+     *
+     * @param payload - Validated candidate and decisions for one proposal.
+     *
+     * @param context - Abort signal and fractional-progress reporting for this row.
+     *
+     * @returns No value after the host confirms application; reject to stop later rows.
+     */
     onApply?: (payload: ApplyProposalPayload<TRecord>, context: ExecutionContext) => void | Promise<void>;
 }
-/** Headless controller shared by batch lists and custom application layouts. */
+/**
+ * Batch selection/decision state and explicit execution controls.
+ *
+ * @typeParam TRecord - Shared record shape; defaults to a string-keyed record.
+ *
+ * @see useProposalBatchReview for usage.
+ */
 export interface UseProposalBatchReviewReturn<TRecord extends Record<string, any> = Record<string, any>> {
+    /**
+     * Current selected proposal IDs; applied IDs are excluded from preparation.
+     */
     selectedIds: ReadonlySet<string>;
+    /**
+     * Host-confirmed successes in this review session.
+     */
     appliedIds: ReadonlySet<string>;
+    /**
+     * Per-proposal field decisions; absent choices remain pending.
+     */
     decisions: ReadonlyMap<string, ReviewDecisions<TRecord>>;
+    /**
+     * Core batch preflight result for current selection and latest input props.
+     */
     preparation: PreparedProposalBatch<TRecord>;
+    /**
+     * Whether a handler exists, preparation passes and state is not submitting.
+     */
     canApply: boolean;
+    /**
+     * Whether the displayed batch is currently running.
+     */
     isSubmitting: boolean;
+    /**
+     * Current row being applied, or null outside active row work.
+     */
     activeProposalId: string | null;
+    /**
+     * Generic current-session batch failure message, or null; raw host exceptions are not exposed.
+     */
     error: string | null;
+    /**
+     * Read-only execution history for this batch session.
+     */
     history: readonly ExecutionRecord[];
+    /**
+     * Select or deselect an editable known proposal.
+     *
+     * @param id - Proposal identifier.
+     *
+     * @param selected - Desired selection state.
+     *
+     * @returns No value; unknown/applied/busy proposals are ignored.
+     */
     setSelected(id: string, selected: boolean): void;
+    /**
+     * Change selection for the current items when idle.
+     *
+     * @param selected - True selects all current IDs; false retains only applied IDs in the selection set.
+     *
+     * @returns No value; calls while execution is busy are ignored.
+     */
     selectAll(selected: boolean): void;
+    /**
+     * Change one existing proposed field while editable.
+     *
+     * @param id - Proposal identifier.
+     *
+     * @param field - Field present in that proposal.
+     *
+     * @param decision - Pending, accepted or rejected choice.
+     *
+     * @returns No value; invalid IDs/fields and busy/applied proposals are ignored.
+     */
     setDecision(id: string, field: FieldKey<TRecord>, decision: FieldDecision): void;
+    /**
+     * Change every proposed field choice for one editable proposal.
+     *
+     * @param id - Proposal identifier.
+     *
+     * @param decision - Choice applied to all its changes.
+     *
+     * @returns No value; unknown/applied/busy proposals are ignored.
+     */
     decideAll(id: string, decision: FieldDecision): void;
+    /**
+     * Preflight the selection, then apply rows sequentially with latest-record rechecks.
+     *
+     * @returns True only for current-session complete success; false when blocked, failed, cancelled or superseded.
+     *
+     * @remarks Confirmed successes are retained and skipped on retry; unconfirmed backend effects may still exist.
+     */
     apply(): Promise<boolean>;
+    /**
+     * Request cooperative cancellation of current execution.
+     *
+     * @returns No value; does not roll back previously applied rows or force host work to stop.
+     */
     cancel(): void;
+    /**
+     * Clear settled execution history using the session policy.
+     *
+     * @returns No value; does not clear review choices or confirmed applied IDs.
+     */
     clearHistory(): void;
 }
 /**
- * Reviews multiple records without implicit field acceptance. Preflights the entire
- * selection, then rechecks each latest committed record immediately before applying it.
- * Stops on first failure or cancellation; confirmed successes are never retried within
- * this session.
+ * Reviews a batch with explicit field decisions and sequential host application.
+ *
+ * @typeParam TRecord - Record shape; defaults to a string-keyed record.
+ *
+ * @param options - Batch identity, unique immutable proposals/latest records, validation and optional host apply callback.
+ *
+ * @returns Selection/decision controls, preflight state, bounded execution history and cooperative cancellation.
+ *
+ * @remarks Requires React; no context/styles. Changing batchId or serialized proposal
+ * content starts a new session; unmount/session changes request cancellation. Each row
+ * is rechecked against latest committed host inputs before apply. Stops at the first
+ * failure/cancellation; successes remain excluded from retries. Cancellation cannot
+ * undo host effects, so persist idempotently and enforce concurrency/authorization in
+ * the backend. A row that changed the backend before rejecting has an uncertain outcome.
+ * Keep the ref/layout-effect bridge for latest host inputs: the returned apply control
+ * can be called by UI event handlers and other host code outside Effect logic.
+ * useEffectEvent is restricted to Effect-originated callbacks and cannot replace this
+ * externally callable execution path. The ref is not a React 18 compatibility shim.
+ *
+ * @example
+ * ```tsx
+ * import { useProposalBatchReview, type UseProposalBatchReviewOptions } from '@alneas/appkit-react/ai/proposal';
+ * type RecordData = { title: string };
+ * export function Batch({ options }: { options: UseProposalBatchReviewOptions<RecordData> }) {
+ *   const review = useProposalBatchReview(options);
+ *   return <button disabled={!review.canApply} onClick={() => { void review.apply(); }}>Apply selected records</button>;
+ * }
+ * ```
  */
 export declare function useProposalBatchReview<TRecord extends Record<string, any> = Record<string, any>>(options: UseProposalBatchReviewOptions<TRecord>): UseProposalBatchReviewReturn<TRecord>;