@orizm/cli 3.1.0 → 3.3.0-beta.0

package/dist/docs/features/form/editor.md

@@ -0,0 +1,410 @@
+<!-- source: docs/src/app/features/form/editor/page.mdx -->
+
+# フォームエディター
+
+フォームエディターは、フォームを直感的に編集するためのツールです。フォームのパーツをドラッグ＆ドロップで配置し、設定をカスタマイズできます。編集画面上で実際のフォームをプレビューしながらフォームを作成できます。
+
+![フォームエディター](./features-form-editor.png)
+
+フォーム管理機能を使うには、フォームエディターを導入する必要があります。
+
+## インストール
+
+フォームエディターを導入するには `@orizm-private/orizm-form-editor` パッケージをインストールします。
+
+このパッケージは一般公開されておらず、アクセスするには一定の手順が必要です。インストールを実行する前に [プライベートレジストリ](../../resources/private-registry.md) を参照し、アクセスできるように設定してください。
+
+スターターでプロジェクトを開始する場合は最初からインストールされています。既存プロジェクトに導入する場合は、以下の手順でインストールしてください。エディターを提供するCMSと、ページを表示するWebサイトの両方でインストールする必要があります。
+
+以下のコマンドでパッケージをインストールします。
+
+```sh copy
+pnpm add @orizm-private/orizm-form-editor @orizm-private/orizm-editor
+```
+
+## 使い方
+
+ここでは Next.js 15 App Router
+を使用したアプリケーションを例に、フォームエディターをアプリケーションに組み込む方法を説明します。
+
+フォームエディターは、CMSとConsumerの両方に組み込む必要があります。CMSにはフォームを編集するためのエディターを実装し、Consumerにはフォームを表示するページを実装します。
+
+> [!WARNING]
+> CMS上のエディターでは、Consumer上のフォームをリアルタイムにプレビューしながら編集できます。プレビューは、CMS上にConsumerのプレビューページを
+> iframeで埋め込むことで実現します。そのため、Consumerが**iframeによる表示を許可**している必要があります。
+
+### CMSの実装
+
+CMSにフォームを編集するエディターを実装します。
+
+#### FormEditorコンポーネントの実装例
+
+`<OrizmFormEditorComposer>` コンポーネントを使用して、エディターを実装します。`previewSiteURL` プロパティに、ConsumerのプレビューページのURLを指定します。
+
+```tsx copy filename="components/form-editor.tsx"
+"use client";
+
+import "@orizm-private/orizm-editor/editor.css";
+import { type Block, isBlocks } from "@orizm-private/orizm-editor/common";
+import {
+  FormEditor as OrizmFormEditor,
+  OrizmFormEditorComposer,
+} from "@orizm-private/orizm-form-editor";
+import type { FormValidationRules } from "@orizm-private/orizm-form-editor/rules";
+import { useCallback, useState } from "react";
+import type { Form } from "@/orizm/cms";
+import { cmsClient } from "@/lib/cms-client";
+
+type Props = {
+  form: Form;
+};
+
+export function FormEditor(props: Props) {
+  const { id, key, displayName, body, formSchema } = props.form;
+
+  const [formState, setFormState] = useState<{
+    blocks: Block[];
+    rules: FormValidationRules;
+  }>(() => {
+    const blocksData = (body as { blocks: unknown } | null)?.blocks;
+    const blocks = isBlocks(blocksData) ? blocksData : [];
+    return {
+      blocks,
+      rules: formSchema,
+    };
+  });
+
+  // このハンドラ関数を OrizmFormEditorComposer の onChange プロパティに渡します
+  // フォームエディター上での変更を受け取り、stateを更新します
+  const onChangeEditor = useCallback(
+    (blocks: Block[], rules: FormValidationRules) => {
+      setFormState({ blocks, rules });
+    },
+    [],
+  );
+
+  const onClickSave = useCallback(async () => {
+    // CMS SDKを使用してフォームの構造をデータベースに保存します
+    await cmsClient.tables.form.update(id, {
+      formSchema: formState.rules,
+      body: { blocks: formState.blocks },
+    });
+  }, [id, formState]);
+
+  return (
+    <>
+      <button onClick={onClickSave}>フォームを保存</button>
+      <OrizmFormEditorComposer
+        initialBlocks={formState.blocks}
+        onChange={onChangeEditor}
+        pageSlug={key}
+        pageTitle={displayName}
+        previewSiteURL="https://consumer.example.com/form-preview"
+      >
+        <OrizmFormEditor />
+      </OrizmFormEditorComposer>
+    </>
+  );
+}
+```
+
+#### フォーム編集ページの実装例
+
+先に実装した `<FormEditor>` コンポーネントを使用して、フォームを編集するページを実装します。
+
+```tsx copy filename="page.tsx"
+import { notFound } from "next/navigation";
+import { FormEditor } from "@/components/form-editor";
+import { cmsClient } from "@/lib/cms-client";
+
+type Params = {
+  params: Promise<{
+    form_id: string;
+  }>;
+};
+
+export default async function FormEditPage(props: Params) {
+  const { form_id } = await props.params;
+
+  const form = await cmsClient.tables.form.get(form_id).catch(() => null);
+
+  if (!form) {
+    return notFound();
+  }
+
+  return <FormEditor form={form} />;
+}
+```
+
+### Consumerの実装
+
+Consumerにフォームをレンダリングするページを実装します。
+
+#### 本番ページの実装例
+
+`<FormComposer>` コンポーネントを使用して、フォームを表示します。`action` プロパティに、フォーム送信時のエンドポイントを指定します。
+
+```tsx copy filename="app/contact/page.tsx"
+import "@orizm-private/orizm-form-editor/forms.css";
+import { isBlocks } from "@orizm-private/orizm-editor/common";
+import {
+  Form,
+  FormComponentRenderer,
+  FormComposer,
+  SubmitButton,
+} from "@orizm-private/orizm-form-editor/renderer";
+import { notFound } from "next/navigation";
+import { cmsClient } from "@/lib/cms-client";
+
+export default async function ContactPage() {
+  // Consumer SDKを使用してフォームの構造を取得します
+  const form = await consumerClient.tables
+    .form({ key: "contact" })
+    .catch(() => null);
+
+  if (!form) {
+    return notFound();
+  }
+
+  const blocksData = (form.body as { blocks: unknown } | null)?.blocks;
+  const blocks = isBlocks(blocksData) ? blocksData : [];
+
+  return (
+    <FormComposer
+      formId={form.key}
+      blocks={blocks}
+      validationRules={form.formSchema}
+      isPreview={false}
+      hasConfirmation={false}
+      action="/contact/submit"
+    >
+      <Form>
+        <FormComponentRenderer />
+      </Form>
+      <SubmitButton>送信する</SubmitButton>
+    </FormComposer>
+  );
+}
+```
+
+#### プレビューページの実装例
+
+プレビューページは、CMSのフォームエディター上でプレビューを表示するために使用します。
+
+プレビューでは `<FormPreviewRenderer>` コンポーネントで `<FormComposer>` コンポーネントをラップします。`editorOrigin` プロパティに、CMSのオリジンを指定します。
+
+```tsx copy filename="app/form-preview/page.tsx"
+import "@orizm-private/orizm-form-editor/forms.css";
+
+import { blocksToRules } from "@orizm-private/orizm-form-editor/common";
+import { FormPreviewRenderer } from "@orizm-private/orizm-form-editor/preview";
+import {
+  Form,
+  FormComposer,
+  FormComponentRenderer,
+  SubmitButton,
+} from "@orizm-private/orizm-form-editor/renderer";
+
+export default function PreviewPage() {
+  return (
+    <FormPreviewRenderer
+      editorOrigin="https://cms.example.com"
+      initialBlocks={[]}
+      renderForm={(blocks) => (
+        <FormComposer
+          formId="preview"
+          blocks={blocks}
+          validationRules={blocksToRules(blocks)}
+          isPreview
+          action="/contact/submit"
+        >
+          <Form>
+            <FormComponentRenderer />
+          </Form>
+          <SubmitButton>送信する</SubmitButton>
+        </FormComposer>
+      )}
+    />
+  );
+}
+```
+
+#### 送信処理の実装例
+
+フォームの送信処理を行うAPIを実装します。リクエストは `POST` メソッドで受け取る必要があります。
+
+```tsx copy filename="app/contact/submit/route.ts"
+import { cmsClient } from "@/lib/cms-client";
+
+export async function POST(request: Request): Promise<Response> {
+  try {
+    const [formData, form] = await Promise.all([
+      request.formData(),
+      cmsClient.tables.form.getByUnique({ key: "contact" }),
+    ]);
+
+    // CMS SDKを使用して submitForm() でフォームデータを送信します
+    await cmsClient.tables.form.submitForm(form.id, formData);
+
+    // ここで必要に応じて送信者に送信完了メールを送ったり、問い合わせ先に通知する処理を実装します
+
+    return new Response("Success", { status: 200 });
+  } catch (error) {
+    console.error(error);
+    return new Response("Failed to submit", { status: 500 });
+  }
+}
+```
+
+## ブロック一覧
+
+フォームエディタでは、以下のブロックを使用してフォームを構築できます。
+
+- テキスト
+- 複数行テキスト
+- メールアドレス
+- 電話番号
+- URL
+- 数値
+- チェックボックス（複数選択）
+- チェックボックス（単一選択）
+- ドロップダウンリスト
+- 日付
+- 日時
+- 時刻
+- ラジオボタン
+- ファイル
+
+## ブロックのスタイル
+
+フォームエディタのブロックにはデフォルトのスタイルが適用されているため、そのまま使い始めることができます。もしくは、Webサイトのデザインに合わせてスタイルをカスタマイズできます。
+
+カスタマイズするには、 [コンシューマーの実装](#consumerの実装) で使用する `<FormComponentRenderer>` コンポーネントの `components` プロパティにカスタムコンポーネントを指定します。
+
+カスタムコンポーネントは必ず `<ComponentMarker>` コンポーネントでラップしてください。ラップしない場合、フォームエディタのプレビュー上でブロックを操作できません。
+
+```tsx copy filename="app/contact/page.tsx" {40-51}
+import "@orizm-private/orizm-form-editor/forms.css";
+
+import { isBlocks } from "@orizm-private/orizm-editor/common";
+import {
+  Form,
+  FormComponentRenderer,
+  FormComposer,
+  FormErrorMessage,
+  FormHelperText,
+  FormLabel,
+  FormTextInput,
+  SubmitButton,
+} from "@orizm-private/orizm-form-editor/renderer";
+import { notFound } from "next/navigation";
+import { cmsClient } from "@/lib/cms-client";
+
+export default async function ContactPage() {
+  const form = await consumerClient.tables
+    .form({ key: "contact" })
+    .catch(() => null);
+
+  if (!form) {
+    return notFound();
+  }
+
+  const blocksData = (form.body as { blocks: unknown } | null)?.blocks;
+  const blocks = isBlocks(blocksData) ? blocksData : [];
+
+  return (
+    <FormComposer
+      formId={form.key}
+      blocks={blocks}
+      validationRules={form.formSchema}
+      isPreview={false}
+      hasConfirmation={false}
+      action="/contact/submit"
+    >
+      <Form>
+        <FormComponentRenderer
+          components={{
+            TextInput: (
+              <ComponentMarker>
+                <div>
+                  <FormLabel />
+                  <FormTextInput />
+                  <FormHelperText />
+                  <FormErrorMessage />
+                </div>
+              </ComponentMarker>
+            ),
+          }}
+        />
+      </Form>
+      <SubmitButton>送信する</SubmitButton>
+    </FormComposer>
+  );
+}
+```
+
+## 確認ページを実装する
+
+フォームでデータを送信する前に、確認ページを表示してユーザーに入力内容を確認させることができます。
+
+`<FormComposer>` コンポーネントを以下のように設定します。
+
+- `hasConfirmation` プロパティに `true` を設定
+- `afterSubmit` プロパティに、確認ページへの遷移処理を設定
+
+```tsx copy {3-4}
+// その他のpropsは省略しています
+<FormComposer
+  hasConfirmation
+  afterSubmit={() => router.push("/contact/confirm")}
+>
+  <Form>
+    <FormComponentRenderer />
+  </Form>
+  <SubmitButton>送信する</SubmitButton>
+</FormComposer>
+```
+
+次に、確認ページを実装します。
+
+`useSavedFormData()` フックを使用して、フォームの入力内容を取得します。
+
+`<SubmitTemporaryDataButton>` コンポーネントを使用して、フォームの入力内容を送信します。`action` プロパティに送信処理を行うエンドポイントを指定します。`afterSubmit` プロパティを使用すると、サンクスページへの遷移を実装することも可能です。
+
+```tsx copy filename="app/contact/confirm/page.tsx"
+"use client";
+
+import {
+  SubmitTemporaryDataButton,
+  useSavedFormData,
+} from "@orizm-private/orizm-form-editor/renderer";
+import { redirect, useRouter } from "next/navigation";
+
+export default function ConfirmPage() {
+  const formId = "contact";
+
+  const router = useRouter();
+  const savedData = useSavedFormData(formId);
+
+  if (savedData.isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  if (savedData.data == null) {
+    redirect("/contact");
+  }
+
+  return (
+    <div>
+      <pre>{JSON.stringify(savedData, null, 2)}</pre>
+      <SubmitTemporaryDataButton
+        formId={formId}
+        action="/contact/submit"
+        afterSubmit={() => router.push("/contact/thanks")}
+      >
+        送信する
+      </SubmitTemporaryDataButton>
+    </div>
+  );
+}
+```

package/dist/docs/features/form/submission.md

@@ -0,0 +1,94 @@
+<!-- source: docs/src/app/features/form/submission/page.mdx -->
+
+# 受信データの管理
+
+フォーム管理機能では、フォームから送信されたデータ（以下、受信データ）を管理できます。
+
+## 受信データのリスト取得
+
+受信データのリストを取得するにはCMS SDKを使用します。
+
+フォーム管理機能が有効なテーブルに対して `submissions()` メソッドを呼び出します。これにより、そのフォームに紐づく受信データを扱うクライアントメソッドが使用できます。次に `list()` や `get()` メソッドを呼び出すことで、受信データのリストを取得できます。
+
+```ts copy
+const submissions = await cmsClient.tables.form.submissions(formId).list({
+  order: { createdAt: "desc" },
+});
+
+console.log(submissions);
+// {
+//   "contents": [
+//     {
+//       "id": "M3nIwgo21UAsZToo",
+//       "updatedAt": "2025-01-01T00:00:00.000Z",
+//       "createdAt": "2025-01-01T00:00:00.000Z",
+//       "_formId": "A8CE7NflEFVT70cK",
+//       "_content": {
+//         "lastName": "John",
+//         "firstName": "Doe",
+//         "email": "john.doe@example.com",
+//         "body": "This is a test message."
+//       },
+//       "_formSchema": {
+//         "lastName": {
+//           "type": "text",
+//           "required": true
+//         },
+//         "firstName": {
+//           "type": "text",
+//           "required": true
+//         },
+//         "email": {
+//           "type": "text",
+//           "required": true
+//         },
+//         "body": {
+//           "type": "textarea",
+//           "required": true
+//         }
+//       },
+//       "_attachments": [],
+//       "status": "in_progress",
+//       "memo": "This is a memo."
+//     }
+//   ],
+//   "totalCount": 1
+// }
+```
+
+以下、重要なプロパティを示します。
+
+### \_content
+
+受信データの内容です。書き換えることはできません。
+
+### \_formSchema
+
+受信時点でのフォームのスキーマです。書き換えることはできません。
+
+### \_attachments
+
+受信データに紐づく添付ファイルの情報です。書き換えることはできません。
+
+[storage型](../schema/database.md#storage) のデータです。ファイルにアクセスするためのURLが含まれています。
+
+## 受信データの更新
+
+受信データを更新するには、`update()` メソッドを使用します。
+
+スキーマの [submissionColumns](./about.md#submissioncolumns) で定義したカラムのみ更新できます。
+
+```ts copy
+await cmsClient.tables.form.submissions(formId).update(submissionId, {
+  status: "closed",
+  memo: "updated memo text",
+});
+```
+
+## 受信データの削除
+
+受信データを削除するには、`delete()` メソッドを使用します。
+
+```ts copy
+await cmsClient.tables.form.submissions(formId).delete(submissionId);
+```

package/dist/docs/features/full-text-search.md

@@ -0,0 +1,114 @@
+<!-- source: docs/src/app/features/full-text-search/page.mdx -->
+
+# 全文検索
+
+全文検索機能を使用すると、[テーブル](./schema/database.md#テーブル) 上のコンテンツに対してキーワード検索ができます。大量のテキストデータの中から、キーワードに関連するコンテンツを効率的に検索できます。
+
+全文検索機能の特徴は以下の通りです。
+
+- 日本語に対応
+- テーブルのデータをキーワードで検索
+- 複数キーワードでの検索に対応
+- Consumer向けの公開データのみを対象とした検索
+- CMS向けの下書きデータを含む検索
+
+## ユースケース例
+
+例えば、求人情報の検索に活用できます。「東京 エンジニア リモートワーク」のように地域名、職種、働き方などのキーワードで検索できます。求職者は希望条件に合った求人情報を直感的に探せます。
+
+他にも、ブログ記事や製品カタログの検索に活用できます。
+
+## 機能の有効化
+
+スキーマで [テーブル](./schema/database.md) ごとに有効化できます。`enableSearch` プロパティを `true` に設定します。
+
+```ts copy filename="orizm.config.ts" showLineNumbers {7}
+import { defineConfig } from "@orizm/cli/config";
+
+export default defineConfig({
+  tables: {
+    blog: {
+      columns: {},
+      enableSearch: true,
+    },
+  },
+});
+```
+
+## 検索可能なデータ型
+
+以下のデータ型のカラムに対して全文検索が可能です。
+
+- [string](./schema/database.md#string)
+- [json](./schema/database.md#json)
+- [module](./schema/database.md#module)
+- [module-array](./schema/database.md#module-array)
+
+## キーワードで検索する
+
+キーワード検索にはSDKの `search()` メソッドを使用します。
+
+`query` プロパティに検索キーワードを指定します。複数キーワードの場合は、スペースで区切ります。
+
+```ts copy
+await cmsClient.tables.blog.search({ query: "キーワード1 キーワード2" });
+```
+
+> [!NOTE]
+> `search()` では `filter` パラメータを使用した絞り込みに制約があります。`group`
+> による絞り込みのみ対応しています。
+
+このメソッドはCMS SDK、Consumer SDKのどちらでも利用できます。
+
+- **Consumer SDK**: 公開データのみ検索可能
+- **CMS SDK**: 下書きデータも検索可能（主にCMS上での管理用途）
+
+## 検索モード（セマンティック検索）
+
+`search()` の `mode` パラメータで検索方式を選択できます。
+
+| mode              | 説明                                                              |
+| ----------------- | ----------------------------------------------------------------- |
+| `keyword`（既定） | 従来の全文検索。`mode` を省略した場合もこの方式です               |
+| `semantic`        | 意味検索。クエリとコンテンツの埋め込みベクトルの近さで検索します  |
+| `hybrid`          | keyword と semantic の融合（RRF）。字面一致と意味の両方を拾います |
+
+```ts copy
+await cmsClient.tables.blog.search({ query: "経費の精算", mode: "hybrid" });
+```
+
+`semantic` / `hybrid` はプロジェクトでセマンティック検索が有効な場合のみ利用できます（無効なプロジェクトではエラーになります）。有効化は `orizm.config.ts` に `semanticSearch: { enabled: true }` を宣言して `orizm schema push` で反映します（無効に戻すときは `enabled: false` を明示します。宣言を省略した定義は現状維持です）。有効化の直後はベクトルインデックスの構築が完了するまで `semantic` / `hybrid` が 403 になります（構築が終わり次第利用できます）。`semantic` / `hybrid` で検索した場合は、検索結果の各行に `_semantic`（スコア・ヒットに寄与したチャンク・レーン別順位）が付与されます（`keyword` では付きません）。
+
+> [!WARNING]
+> セマンティック検索を利用できるかどうかは、プロジェクトの設定に加えてシステム側の設定でも決まります。システム側で有効になっていない環境では、`semanticSearch: { enabled: true }` の push は成功しますが `semantic` / `hybrid` の検索は利用できません（ベクトルインデックスが作られていない場合は 403 になり、過去に作られたインデックスが残っている場合は `keyword` の結果に劣化します）。利用中の環境で使えるかは管理者に確認してください。
+
+CMS SDK の `semantic` / `hybrid` では、プロジェクトの [検索辞書](./dictionary.md) に説明を付けた有効なエントリがあれば、検索結果に辞書のヒット（`_dictionary`）も付与されます（説明付きのエントリが無いプロジェクトではキー自体が付きません）。検索辞書に同義語を登録しておくと、`hybrid` の検索クエリに表記の言い換えが足され、社内の俗称や型番の表記ゆれでも目的のコンテンツに当たるようになります。
+
+フォーム投稿（submissions）の検索は `keyword` のみ対応です（`semantic` / `hybrid` を指定すると 403 になります）。
+
+ページングの制約は mode ごとに異なります（超過はいずれも 400 になります）。
+
+| mode       | `offset + limit` | `limit: 0`（件数だけ取る）       |
+| ---------- | ---------------- | -------------------------------- |
+| `keyword`  | 10000 まで       | 使えます（正確な件数が返ります） |
+| `semantic` | 100 まで         | 使えません                       |
+| `hybrid`   | 100 まで         | 使えません                       |
+
+`semantic` / `hybrid` の上限が小さいのは、`semantic` では近傍探索（ANN）の候補プールが深い窓を安定して裏付けられない（加えて窓の各行にチャンク本文を付けて返す）ため、`hybrid` では融合（RRF）が固定ランク窓の中でだけページ間の順序を安定して定義できるためです。深いページングや件数だけの取得が必要な場合は `keyword` を使ってください。`limit` / `offset` は mode を問わず整数かつ 0 以上のみ受け付けます。
+
+`query` は mode を問わず 512 文字までです（超過は 400 になります）。空文字や空白だけの `query` は検索せず、0 件（`contents: []`, `totalCount: 0`）を返します。
+
+> [!WARNING]
+> `semantic` / `hybrid` の `totalCount`
+> は正確な件数ではなく、**ページ数の計算には使えません**。 `semantic` の
+> `totalCount` は近傍探索（ANN）の候補プールの大きさで、`offset + limit`
+> に応じて増えます（ページを進めるほど値が大きくなります）。該当するコンテンツが無いクエリでも
+> 0 にはなりません（ANN は常に最も近いものを返すため）。`hybrid` の `totalCount`
+> は下界（2 レーンの大きい方。返した行数を下回ることはありません）です。`limit:
+> 0` が `keyword` 専用なのも同じ理由です。正確な件数やページ数が必要な場合は
+> `keyword` を使ってください。
+
+> [!NOTE]
+> 埋め込み基盤の一時的な障害時は、検索を失敗させる代わりに `keyword`
+> の結果に劣化して応答します（このとき `_semantic` と `_dictionary`
+> は付かず、`hybrid` で効いていた検索辞書によるクエリの言い換えも外れます）。