foldkit

Foldkit

Foldkit アプリを開発しています。Foldkit は Effect 上に構築され、Elm のような設計を採用した、TypeScript のフロントエンドフレームワークです。アーキテクチャはすでに整っています。状態、イベント、遷移、副作用、ストリーム、ルーティング、UI コンポーネント、バリデーション、テスト、開発ツールはすべてフレームワークに含まれており、サードパーティ製の選択肢から選ぶ必要はありません。あなたの役割は、ライブラリを選んだりアーキテクチャを考案したりすることではなく、アプリケーションの振る舞いをモデル化することです。

Foldkit は段階的に導入するフレームワークではありません。React との相互運用も、回避策も、「この部分だけ React のやり方で実装する」こともできません。フレームワークが提供する形は一つであり、ほとんどの処理には一つの方法があります。

作業の進め方

• Foldkit 自身のアプリをパターンとして参照してください。 ローカルのコードに答えがない場合（または初期段階の実装しかない場合）は、同梱された foldkit サブツリーを参照してください。フレームワークには、それ自体を使って構築された複数のアプリが含まれています。examples/ の機能に特化した小規模なアプリ、Foldkit アプリでもあるウェブサイト、そしてリアルタイムの本格的なアプリであるタイピングゲームです。これらが正式なリファレンスです。説明文や記憶から再構成した情報よりも、実際の実装を忠実に反映しています。
• アーキテクチャは任意ではありません。 単方向データフロー、純粋な update と view、ランタイムが用意する接点以外での副作用は禁止です。ミューテーション、双方向バインディング、命令型イベントハンドラー、命令的な Message 名へ導くプロンプトや考えには異議を唱えてください。Foldkit に沿った形を提案し、その理由を説明してください。
• Foldkit UI は一つではなく、二つのカテゴリに分かれています。 Stateful Submodel（Menu、Listbox、Combobox、Calendar、Disclosure、Dialog、Popover など）は、それぞれ独自の Model / Message / update / OutMessage を持ち、h.submodel を使って組み込みます。ステートレスなレンダー helper（Button、Input、Textarea、Select、Fieldset）は、ViewConfig と呼び出し元の h を直接渡して呼び出し、Html を返します。「一貫性」のためにレンダー helper を Submodel に移行しないでください。Submodel の意味するところは状態を持つことですが、これらの helper は状態を持ちません。正式な分類については、ウェブサイトにある Foldkit UI の概要ページを参照してください。
• Foldkit と Effect のスタックが提供する機能を使ってください。 Foldkit はアプリケーションアーキテクチャと、その上位のプリミティブ（ルーティング、副作用の接点、サブスクリプション、UI コンポーネント、フィールドのバリデーション、ファイルと日付の処理、キャンバス、テスト、開発ツールなど）をカバーします。Effect は、その基盤となる値、副作用の記述、並行処理のプリミティブを提供します。外部ライブラリを使う前に、スタックに必要な機能がすでに含まれていないか確認してください。
• modifyFields の setter にはフィールドを受け取らせてください。 modifyFields の setter が同じフィールドの現在値を変換するだけなら、変換関数を直接渡してください（entries: Array.map(f)、count: Number.increment、priceSlider: Slider.reflectRange({ min: minPrice, max: maxPrice })）。Message、子の更新、Command、またはほかの Model フィールドから取得した値で置き換える場合は、() => value を使ってください。
• このリポジトリの情報は記憶よりも信頼できます。 慣習、API、名前、パターンに迷ったら、推測せず、同梱された foldkit サブツリーを参照してください。ライブラリの型とサンプルコードが正しい根拠です。学習データではありません。

参照先

foldkit リポジトリは、プロジェクトルートから見て repos/foldkit/ に Git サブツリーとして取り込まれています。規約、フレームワークのソース、サンプル、品質基準など、あらゆる情報の正本です。直接参照してください。

安定したトップレベルの参照先：

• repos/foldkit/examples/：あらゆる複雑さの段階を網羅した、実行可能なサンプルアプリです。前例を探すときは、通常ここから確認します。
• repos/foldkit/AGENTS.md：プロジェクトの規約とコード品質基準
• repos/foldkit/README.md：フレームワークの概要と参照先
• repos/foldkit/skills/：標準的なアーキテクチャ、規約、品質基準の参照先をまとめた、タスク指向のスキル
• repos/foldkit/packages/：フレームワークのソースと本番用の参照アプリ（ウェブサイト、タイピングゲーム、フレームワーク自体）

トップレベルより下の名前（サブディレクトリや個別のファイル名）は、時間の経過とともに変わることがあります。このスキルに記載されたパスに頼るのではなく、必要なものを見つけるためにディレクトリの内容を一覧表示してください。

プロジェクトに repos/foldkit/ がない場合は、追加を強く推奨してください。このサブツリーがあれば、記憶に頼るのではなく、標準的な参照資料と照らし合わせてパターンを見つけられます。これがないと、支援の質は目に見えて低下します。インストール済みの foldkit パッケージに一致するリリースの Git タグに固定してください。そうすることで、現在の main にあるものではなく、プロジェクトがコンパイルする API を参照できます。必要であれば、最初に Git を初期化してください（サブツリーには少なくとも 1 つのコミットが必要です）。

git subtree add --prefix=repos/foldkit https://github.com/foldkit/foldkit.git "foldkit@$(node -p "require('./node_modules/foldkit/package.json').version")" --squash

Foldkit パッケージをアップグレードした後は、同じコマンドで add を pull に置き換えて、再度固定してください。カナリア版（node_modules/foldkit/package.json に x.y.z-canary.<commit> と記載されたもの）にはタグがありません。その場合は、バージョンに記載されたコミットの完全なハッシュに固定してください。このハッシュは GitHub の https://github.com/foldkit/foldkit/commit/<commit> で展開されます。

利用側プロジェクトの FOLDKIT.md はスキャフォルダーが生成したスナップショットであり、インストール済みのパッケージの内容より古くなっている場合があります。その場合は、repos/foldkit/packages/create-foldkit-app/templates/base/FOLDKIT.md からファイル全体を置き換えてください。そのプロジェクトの AGENTS.md は作成者のものなので、決して上書きしないでください。

利用側プロジェクトではなく foldkit リポジトリ自体で作業する場合は、repos/foldkit/ のプレフィックスを省略してください。同じパスがプロジェクトルートにあります。