@orizm/cli 3.1.0 → 3.3.0-beta.0

package/dist/docs/features/consumer-sdk/migrate-to-v2.md

@@ -0,0 +1,43 @@
+<!-- source: docs/src/app/features/consumer-sdk/migrate-to-v2/page.mdx -->
+
+# CMS SDK v2 への移行
+
+このドキュメントでは、Consumer SDK v1 から v2 への移行手順と注意点について説明します。
+
+## 変更点の概要
+
+- CLI の廃止
+- `@orizm/common` 依存を peerDependency から削除
+
+## 移行手順
+
+### CLI の変更
+
+`@orizm/consumer-sdk` に含まれていた CLI コマンド (`orizm-consumer`) は廃止され、`@orizm/cli` パッケージに統合されました。コマンドを呼び出すプロジェクトで専用の CLI パッケージをインストールし、コマンドを修正してください。
+
+```sh npm2yarn copy
+npm install --save-dev @orizm/cli
+```
+
+```sh
+# 旧
+orizm-consumer generate
+# 新
+orizm codegen consumer
+```
+
+CLI の利用方法の詳細は [Orizm CLI](../cli.md) を参照してください。
+
+### `@orizm/common` のアンインストール
+
+`@orizm/common` を `@orizm/cms-sdk` の peer dependencies から dependencies に変更しました。`@orizm/common` をコードで利用していない場合は、アンインストールできます。
+
+```sh npm2yarn copy
+npm uninstall @orizm/common
+```
+
+ただし、`@orizm/common` をコードで利用している場合は、最新バージョンがリリースされているためアップデートしてください。
+
+```sh npm2yarn copy
+npm install @orizm/common@latest
+```

package/dist/docs/features/design-editor/about.md

@@ -0,0 +1,36 @@
+<!-- source: docs/src/app/features/design-editor/about/page.mdx -->
+
+# デザインエディターとは
+
+デザインエディターは、Webページを直感的に編集できるツールです。以下の操作が可能です。
+
+- コンポーネントをドラッグ＆ドロップで配置
+- コンポーネントのプロパティを直接編集
+
+編集画面はWebページのプレビューとして機能するため、別途プレビュー画面を開く必要がありません。
+
+![デザインエディター](./design-editor-overview.png)
+
+デザインエディターは、`@orizm-private/orizm-editor` パッケージとしてプライベートレジストリで配布されています。このライブラリはスタータープロジェクトに組み込まれていますが、必要に応じて既存プロジェクトにも導入できます。
+
+### デザインエディターの特徴
+
+デザインエディターには、以下の特徴があります。
+
+- Webページを直感的に編集可能
+- 編集画面のサイズを切り替え可能
+- コンポーネントをカテゴリーごとにグループ化
+- 開発者が独自のコンポーネントを作成可能
+- コンポーネントのプロパティを開発者が制御可能
+- コンポーネントの入れ子構造に対応
+- コンポーネントのサムネイルを自動生成
+
+デザインエディターは、CMSとWebサイトが連携して動作します。CMSはエディターを表示し、Webサイトはエディターの状態を受け取ってページを再描画します。そのため、CMSとWebサイトの両方でデザインエディターを利用する実装が必要です。
+
+### プレビューの仕組み
+
+デザインエディターは、CMSとWebサイトが連携することでリアルタイムプレビューを提供します。具体的には、デザインエディターがWebサイトを`iframe`で表示する仕組みです。
+
+Webサイトが`iframe`表示をブロックしている場合、デザインエディターは正しく動作しません。CMSから`iframe`経由でWebサイトを表示できるように設定してください。
+
+また、デザインエディターを安全に動作させるためには、CMSとWebサイトが互いのURLを認識している必要があります。この情報はReactコンポーネントの`props`として指定します。

package/dist/docs/features/design-editor/getting-started.md

@@ -0,0 +1,244 @@
+<!-- source: docs/src/app/features/design-editor/getting-started/page.mdx -->
+
+# はじめに
+
+このドキュメントでは、Orizmデザインエディターを使用してコンポーネントを定義し、エディターを表示する方法、さらにWebサイト側でのコンポーネント実装やプレビュー機能の設定方法を説明します。以下の手順に従うことで、デザインエディターを活用した効率的な開発が可能になります。
+
+## コンポーネントの定義
+
+デザインエディターで使用するコンポーネントの名前やプロパティを定義します。この定義に基づき、エディターの編集UIが生成され、Webサイト側でコンポーネントの状態が認識されます。
+
+以下は、`Button`コンポーネントを定義する例です。このコンポーネントには、以下の4つのプロパティがあります。
+
+- `text`: ボタンのテキスト
+- `href`: リンク先URL
+- `variant`: デザインの種類
+- `size`: サイズ
+
+```ts
+import * as orizm from "@orizm-private/orizm-editor/schema";
+
+export const componentSchema = orizm.defineComponentSchema({
+  Button: orizm.component({
+    displayName: "ボタン",
+    category: "アイテム",
+    props: orizm.props({
+      text: orizm.string({
+        displayName: "テキスト",
+        default: "ボタン",
+      }),
+      href: orizm.string({
+        displayName: "リンク先URL",
+        default: "https://www.google.com",
+      }),
+      variant: orizm.picklist({
+        displayName: "デザイン",
+        options: {
+          default: { displayName: "デフォルト" },
+          secondary: { displayName: "セカンダリ" },
+          black: { displayName: "黒" },
+          white: { displayName: "白" },
+        },
+        default: "default",
+      }),
+      size: orizm.picklist({
+        displayName: "サイズ",
+        options: {
+          sm: { displayName: "小" },
+          md: { displayName: "中" },
+          lg: { displayName: "大" },
+        },
+        default: "md",
+      }),
+    }),
+  }),
+});
+```
+
+複数のコンポーネントを定義する場合は、`orizm.defineComponentSchema`関数に渡す`orizm.component`を増やしてください。必要に応じてコンポーネントを追加します。
+
+## エディターの表示
+
+デザインエディターをCMSで表示するには、`OrizmEditorComposer`と`OrizmEditor`を使用します。
+
+以下は、エディターを表示するReactコンポーネントの例です。
+
+```tsx
+import "@orizm-private/orizm-editor/editor.css";
+import { Block } from "@orizm-private/orizm-editor/common";
+import {
+  OrizmEditor,
+  OrizmEditorComposer,
+} from "@orizm-private/orizm-editor/editor";
+import { componentSchema } from "@repo/design-editor/component-schema";
+import { useState } from "react";
+import { ImageUpload } from "../image-upload";
+
+export const StaticPageEditor: React.FC = () => {
+  const [blocks, setBlocks] = useState<Block[]>([]);
+
+  return (
+    <OrizmEditorComposer
+      componentSchema={componentSchema}
+      initialBlocks={blocks}
+      onChange={setBlocks}
+      pageSlug="/my-page"
+      pageTitle="My Page"
+      previewSiteURL="http://localhost:3001"
+      customPropEditors={{
+        Image: {
+          image: ImageUpload,
+        },
+      }}
+    >
+      <OrizmEditor />
+    </OrizmEditorComposer>
+  );
+};
+```
+
+### 主なプロパティ
+
+- `componentSchema`: 定義したコンポーネントスキーマを指定します。
+- `initialBlocks`: 初期状態のブロックを指定します。
+- `onChange`: ブロックが変更された際に呼び出されるコールバック関数です。
+- `previewSiteURL`: プレビュー用のWebサイトURLを指定します。
+- `customPropEditors`: 独自の編集UIをReactコンポーネントとして指定します。
+
+これにより、エディターで編集したデータを`blocks`ステートに反映させ、データベースなどに保存できます。
+
+## Webサイト側でのコンポーネント実装
+
+定義したスキーマに基づき、Webサイト側でコンポーネントを実装します。以下は、`Button`コンポーネントの実装例です。
+
+```tsx
+import {
+  ComponentMarker,
+  type ComponentRenderers,
+} from "@orizm-private/orizm-editor/renderer";
+import { buttonVariants } from "@repo/ui";
+import Link from "next/link";
+import { cn } from "../../../ui/src/lib/utils";
+import type { componentSchema } from "../component-schema";
+
+type ButtonFC = ComponentRenderers<typeof componentSchema>["Button"];
+
+export const Button: ButtonFC = ({
+  text,
+  href = "#",
+  variant,
+  size,
+  width,
+  marginTop,
+  marginBottom,
+  isThumbnail,
+}) => {
+  return (
+    <ComponentMarker>
+      <Link
+        href={href}
+        data-orizm-text-property="text"
+        className={cn(
+          buttonVariants({
+            variant,
+            size,
+            marginTop,
+            marginBottom,
+          }),
+          width && "w-full",
+        )}
+      >
+        {isThumbnail ? "プレビュー中" : text}
+      </Link>
+    </ComponentMarker>
+  );
+};
+```
+
+### 実装のポイント
+
+- `ComponentMarker`をルートに設置することで、エディターがコンポーネントを認識します。
+- スキーマで定義したプロパティがReactコンポーネントの`props`として渡されます。
+- `isThumbnail`はサムネイル撮影中かどうかを示す予約済みの`props`です。
+- `data-orizm-text-property` 属性にプロパティ名を設定すると、プレビュー上でコンポーネントをダブルクリックすることでテキストプロパティを編集できます。
+
+  ![プレビュー上でテキスト編集のUIが表示されている様子](./data-orizm-text-property.png)
+
+## 本番用ページの表示
+
+本番用ページでは、`PageRenderer`を使用してコンテンツデータを表示します。
+
+```tsx
+import { Block } from "@orizm-private/orizm-editor/common";
+import { PageRenderer } from "@orizm-private/orizm-editor/renderer";
+import { componentSchema } from "../component-schema";
+import { components } from "../components";
+
+const Page: React.FC = async () => {
+  const blocks: Block[] = await fetchBlocksFromCMS();
+
+  return (
+    <PageRenderer
+      blocks={blocks}
+      components={components}
+      componentSchema={componentSchema}
+    />
+  );
+};
+
+export default Page;
+```
+
+### 必要なプロパティ
+
+- `blocks`: CMSから取得したコンテンツデータ。
+- `components`: 実装したコンポーネントのオブジェクト。
+- `componentSchema`: 定義したスキーマ。
+
+## プレビュー用ページの表示
+
+エディターから`iframe`経由で表示するプレビュー用ページを実装します。
+
+```tsx
+"use client";
+
+import { PreviewRenderer } from "@orizm-private/orizm-editor/preview";
+import { componentSchema } from "./component-schema";
+import { components } from "./components";
+import { PageRenderer } from "@orizm-private/orizm-editor/renderer";
+
+const Page: React.FC = () => {
+  return (
+    <PreviewRenderer
+      initialBlocks={[]}
+      componentSchema={componentSchema}
+      editorOrigin={
+        process.env.NODE_ENV === "development"
+          ? "http://localhost:3000"
+          : "https://design-editor-demo-cms.vercel.app"
+      }
+      renderPage={(blocks, isThumbnail) => (
+        <PageRenderer
+          blocks={blocks}
+          components={components}
+          componentSchema={componentSchema}
+          isThumbnail={isThumbnail}
+        />
+      )}
+    />
+  );
+};
+
+export default Page;
+```
+
+### 実装のポイント
+
+- `PreviewRenderer`はエディターから受信したステートを`PageRenderer`に渡します。
+- `editorOrigin`にはエディターが動作するURLを指定します。
+- 初期状態のステートがある場合は`initialBlocks`に渡します。
+
+## 起動方法
+
+1. CMS側とWebサイト側の開発サーバーを起動します。
+2. CMS側のエディターを開き、Webページを編集します。

package/dist/docs/features/design-editor/install.md

@@ -0,0 +1,17 @@
+<!-- source: docs/src/app/features/design-editor/install/page.mdx -->
+
+# インストール
+
+[プライベートレジストリ](../../resources/private-registry.md)を参照して、`@orizm-private`スコープの取得先がOrizmプライベートレジストリに設定されていることを確認してください。
+
+スターターでプロジェクトを開始する場合は最初からインストールされています。既存プロジェクトに導入する場合は、以下の手順でインストールしてください。エディターを提供するCMSと、ページを表示するWebサイトの両方でインストールする必要があります。
+
+```bash copy
+pnpm add @orizm-private/orizm-editor
+```
+
+次に、以下のようにアプリケーションで CSS を読み込んでください。
+
+```ts copy
+import "@orizm-private/orizm-editor/editor.css";
+```

package/dist/docs/features/design-editor/prop-editor.md

@@ -0,0 +1,83 @@
+<!-- source: docs/src/app/features/design-editor/prop-editor/page.mdx -->
+
+# プロパティエディター
+
+デザインエディターは、プロパティの型に基づいてデフォルトの編集UI（プロパティエディター）を提供します。
+
+![見出しブロックのプロパティであるIDと見出しがデフォルトの編集UIで表示されている様子](./default-prop-editor-sample.jpeg)
+
+ただし、デフォルトのプロパティエディターでは対応できないユースケースもあります。たとえば、画像選択ダイアログを使用してユーザーが選択した画像をプロパティとして設定する場合です。
+
+このような場合、プロパティエディターをカスタマイズする必要があります。
+
+### プロパティエディターをカスタマイズする
+
+プロパティエディターをカスタマイズするには、`OrizmEditorComposer`コンポーネントの`customPropEditors`プロパティを使用します。以下はその具体例です。
+
+```tsx
+import "@orizm-private/orizm-editor/editor.css";
+import {
+  OrizmEditor,
+  OrizmEditorComposer,
+} from "@orizm-private/orizm-editor/editor";
+
+const Page: React.FC = () => {
+  return (
+    <OrizmEditorComposer
+      // other props...
+
+      customPropEditors={{
+        Image: {
+          image: ImageUpload,
+        },
+      }}
+    >
+      <OrizmEditor />
+    </OrizmEditorComposer>
+  );
+};
+```
+
+#### コードの説明
+
+- `Image`: 対象となるコンポーネントを表します。
+- `image`: プロパティ名を表します。
+- `ImageUpload`: カスタムプロパティエディターとして使用するReactコンポーネントです。
+
+---
+
+### カスタムプロパティエディターの要件
+
+カスタムプロパティエディターとして使用するコンポーネントは、以下のインターフェイスを満たす必要があります。
+
+```ts
+export interface PropEditorProps<T> {
+  value: T;
+  onChange: (newValue: T) => void;
+}
+```
+
+#### 実装のポイント
+
+- `value`: 現在のプロパティ値を受け取ります。
+- `onChange`: ユーザー操作に応じて新しい値を渡します。
+
+### 注意点
+
+無名関数をそのまま渡すような書き方は避けてください。具体的には次のような書き方です。
+
+```tsx
+<OrizmEditorComposer
+  // other props...
+
+  customPropEditors={{
+    Image: {
+      image: (props) => <ImageUpload {...props} />,
+    },
+  }}
+>
+  <OrizmEditor />
+</OrizmEditorComposer>
+```
+
+プロパティエディターの関数インスタンスは変わらないことが期待されます。この書き方はレンダリングのたびに新しい関数インスタンスを生成するため、意図しないタイミングでフォーカスが外れるなどの不具合の原因となります。

package/dist/docs/features/design-editor/schema.md

@@ -0,0 +1,279 @@
+<!-- source: docs/src/app/features/design-editor/schema/page.mdx -->
+
+# スキーマ定義ガイド
+
+このドキュメントでは、デザインエディターで使用するスキーマの定義方法を説明します。スキーマを正しく設定することで、エディターでのプロパティ編集やWebサイトでのコンポーネント表示を効率的に管理できます。
+
+## スキーマの基本構造
+
+スキーマは以下のように定義します。
+
+```ts
+import * as orizm from "@orizm-private/orizm-editor/schema";
+
+export const componentSchema = orizm.defineComponentSchema({
+  Button: orizm.component({
+    displayName: "ボタン",
+    category: "アイテム",
+    props: orizm.props({
+      text: orizm.string({
+        displayName: "テキスト",
+        default: "ボタン",
+      }),
+      href: orizm.string({
+        displayName: "リンク先URL",
+        default: "https://www.google.com",
+      }),
+      variant: orizm.picklist({
+        displayName: "デザイン",
+        options: {
+          default: { displayName: "デフォルト" },
+          secondary: { displayName: "セカンダリ" },
+          black: { displayName: "黒" },
+          white: { displayName: "白" },
+        },
+        default: "default",
+      }),
+      size: orizm.picklist({
+        displayName: "サイズ",
+        options: {
+          sm: { displayName: "小" },
+          md: { displayName: "中" },
+          lg: { displayName: "大" },
+        },
+        default: "md",
+      }),
+    }),
+  }),
+});
+```
+
+- `orizm.component` にはコンポーネントの基本情報を設定します。
+- `orizm.props` にはコンポーネントが受け取るプロパティを定義します。
+
+## プロパティ型の詳細
+
+以下に、`orizm.props` で使用可能なプロパティ型を説明します。
+
+### `orizm.string`
+
+文字列型のプロパティを定義します。
+
+```ts
+orizm.string({
+  displayName: "テキスト",
+  default: "ボタン",
+  inputType: "textarea",
+});
+```
+
+- **`inputType`**: `"text" | "textarea" | "color"` のいずれかを指定します。
+  - `"textarea"`: テキストエリアを表示します。
+  - `"color"`: カラーピッカーを表示します。
+- **型**: CMSとWebサイトの両方で `string` 型を使用します。
+
+### `orizm.picklist`
+
+選択肢から1つを選ぶプロパティを定義します。
+
+```ts
+orizm.picklist({
+  displayName: "サイズ",
+  options: {
+    sm: { displayName: "小" },
+    md: { displayName: "中" },
+    lg: { displayName: "大" },
+  },
+  default: "md",
+  inputType: "radio",
+});
+```
+
+- **`inputType`**: `"select" | "radio"` のいずれかを指定します。
+  - `"radio"`: ラジオボタンを表示します。
+  - `"select"`: ドロップダウンリストを表示します。
+- **型**: CMSとWebサイトの両方で `keyof typeof options` 型。
+
+### `orizm.richText`
+
+リッチテキスト型のプロパティを定義します。
+
+```ts
+orizm.richText({
+  displayName: "説明",
+  useInlineStyles: false,
+  inputType: "multiline",
+  default: "",
+});
+```
+
+- **`inputType`**: `"singleline" | "multiline"` を指定します。
+- **`useInlineStyles`**: インライン装飾の有効化を指定します。
+- **型**:
+  - CMS側: raw HTML を含む `string` 型。
+  - Webサイト側: サニタイズされた `React.ReactElement` 型。
+
+### `orizm.number`
+
+数値型のプロパティを定義します。
+
+```ts
+orizm.number({
+  default: 1,
+  displayName: "数値",
+  inputType: "number",
+  min: 1,
+  max: 10,
+});
+```
+
+- **`inputType`**: `"number" | "range"` を指定します。
+  - `"range"`: スライダーを表示します。
+- **`min` / `max`**: 数値の範囲を指定します。
+- **型**: CMSとWebサイトの両方で `number` 型。
+
+### `orizm.boolean`
+
+真偽値型のプロパティを定義します。
+
+```ts
+orizm.boolean({
+  displayName: "表示する",
+  default: false,
+});
+```
+
+- **型**: CMSとWebサイトの両方で `boolean` 型。
+
+### `orizm.array`
+
+配列型のプロパティを定義します。
+
+```ts
+orizm.array({
+  displayName: "箇条書き",
+  default: ["項目1", "項目2"],
+  element: orizm.string({
+    displayName: "項目",
+    default: "",
+  }),
+});
+```
+
+- **`element`**: 配列要素の型を指定します。
+- **型**: `T[]`（例: `string[]`）。
+
+### `orizm.object`
+
+オブジェクト型のプロパティを定義します。
+
+```ts
+orizm.object({
+  displayName: "画像",
+  schema: {
+    heading: orizm.string({
+      displayName: "見出し",
+      default: "",
+    }),
+    paragraph: orizm.string({
+      displayName: "説明",
+      default: "",
+    }),
+  },
+});
+```
+
+- **`schema`**: オブジェクトの構造を定義します。
+- **型**: `T`（例: `{ heading: string; paragraph: string }`）。
+
+### `null` 許容プロパティ
+
+すべてのプロパティ型はデフォルトで `null` を許容しません。`nullable` を指定することで許容可能になります。
+
+```ts
+orizm.string({
+  displayName: "テキスト",
+  default: null,
+  nullable: true,
+});
+```
+
+- **型**: `T | null`。
+
+## スロット
+
+スロット（slot）は、コンポーネントの中に他のコンポーネントを配置できる領域です。Reactの `children` プロパティと同様の役割を果たします。
+
+### スロットの定義
+
+スロットは以下のように定義します。
+
+```ts {13-34}
+import * as orizm from "@orizm-private/orizm-editor/schema";
+
+const TwoColumns = orizm.component({
+  displayName: "2カラム",
+  category: "レイアウト",
+  props: orizm.props({
+    gap: orizm.number({
+      default: 8,
+      displayName: "間隔",
+      min: 0,
+    }),
+  }),
+  slots: orizm.slots({
+    column1: orizm.slot({
+      displayName: "カラム1",
+      default: [
+        {
+          type: "Paragraph",
+          props: { text: "Column 1" },
+          slots: {},
+        },
+      ],
+    }),
+    column2: orizm.slot({
+      displayName: "カラム2",
+      default: [
+        {
+          type: "Paragraph",
+          props: { text: "Column 2" },
+          slots: {},
+        },
+      ],
+    }),
+  }),
+});
+```
+
+### `orizm.slot`
+
+スロットを定義するための関数です。以下のプロパティを指定できます。
+
+- **`default`**: スロットのデフォルトコンテンツ。
+- **型**: `React.ReactNode`
+
+### スロットの使用方法
+
+スロットはコンポーネントの中で以下のように使用します。
+
+```tsx
+import {
+  ComponentMarker,
+  type ComponentRenderers,
+} from "@orizm-private/orizm-editor/renderer";
+import type { componentSchema } from "../component-schema";
+
+type TwoColumnsFC = ComponentRenderers<typeof componentSchema>["TwoColumns"];
+
+export const TwoColumns: TwoColumnsFC = ({ gap, column1, column2 }) => {
+  return (
+    <ComponentMarker>
+      <div className="grid grid-cols-2" style={{ gap }}>
+        <div>{column1}</div>
+        <div>{column2}</div>
+      </div>
+    </ComponentMarker>
+  );
+};
+```