@blocklet/payment-react 1.20.16 → 1.20.18

package/docs/guides-theming.ja.md

@@ -0,0 +1,213 @@
+# テーマ設定
+
+組み込みのテーマプロバイダーとMaterial-UIのテーマオプションを使用して、支払いコンポーネントの外観をカスタマイズする方法を学びます。`@blocklet/payment-react`ライブラリはMaterial-UIを基盤に構築されており、支払いフローのルックアンドフィールを広範囲にわたって制御できます。
+
+## `PaymentThemeProvider`の概要
+
+このライブラリには、すべての支払いコンポーネントをラップする専用の`PaymentThemeProvider`が含まれています。このプロバイダーは、ArcBlock UXテーマ（`@arcblock/ux/lib/Theme`）から継承したデフォルトテーマを確立し、ArcBlockエコシステム内での視覚的な一貫性を保証します。また、特別な`chip`カラーパレットやさまざまなMUIコンポーネントのスタイルオーバーライドなど、独自のカスタマイズも追加します。
+
+`PaymentThemeProvider`の構造を簡略化したものを以下に示します：
+
+```tsx src/theme/index.tsx icon=logos:react
+import { createTheme, ThemeProvider } from '@mui/material/styles';
+import { create as createBlockletTheme, deepmerge } from '@arcblock/ux/lib/Theme';
+
+export function PaymentThemeProvider({ children, theme: customTheme = {} }) {
+  const parentTheme = useTheme();
+
+  const mergeTheme = useMemo(() => {
+    // Start with the base blocklet theme
+    const blockletTheme = parentTheme.themeName === 'ArcBlock' ? parentTheme : createBlockletTheme();
+
+    // Merge our custom payment theme options
+    let paymentThemeOptions = deepmerge(blockletTheme, {
+      // Custom palette extensions, e.g., for chips
+      palette: {
+        chip: { /* ... */ },
+      },
+      // Custom component style overrides
+      components: {
+        MuiButton: { /* ... */ },
+        MuiOutlinedInput: { /* ... */ },
+        // ... other components
+      },
+    });
+
+    // Merge any user-provided custom theme
+    paymentThemeOptions = deepmerge(paymentThemeOptions, customTheme);
+
+    return createTheme(paymentThemeOptions);
+  }, [parentTheme, customTheme]);
+
+  return (
+    <ThemeProvider theme={mergeTheme}>
+      <CssBaseline />
+      {children}
+    </ThemeProvider>
+  );
+}
+```
+
+## コンポーネントスタイルのカスタマイズ
+
+バージョン1.14.22以降、`theme`プロパティを渡すことで、個々の支払いコンポーネントのテーマを簡単にカスタマイズできます。このプロパティはMaterial-UIの`ThemeOptions`オブジェクトを受け入れ、カスタムスタイルを適用するための2つの主要な方法を提供します。
+
+### 1. `styleOverrides`の使用
+
+詳細な構造的変更を行うには、支払いコンポーネントのスコープ内で特定のMaterial-UIコンポーネントのスタイルをオーバーライドできます。これは、テーマ設定の標準的なMUIの方法です。
+
+```tsx プライマリーボタンのカスタマイズ icon=logos:react
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+import { useSessionContext } from '@/hooks/session-context'; // Assuming session context is defined here
+
+function CustomStyledCheckout() {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <CheckoutForm
+        id="plink_xxx"
+        onChange={console.info}
+        theme={{
+          components: {
+            MuiButton: {
+              styleOverrides: {
+                containedPrimary: {
+                  backgroundColor: '#1DC1C7',
+                  color: '#fff',
+                  '&:hover': {
+                    backgroundColor: 'rgb(20, 135, 139)',
+                  },
+                },
+              },
+            },
+          },
+        }}
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+この例では、プライマリーのcontainedボタン（`MuiButton.styleOverrides.containedPrimary`）をターゲットにし、その背景色とテキスト色を変更しています。
+
+### 2. `sx`プロパティの使用
+
+手早く、特定のCSS変更を行うには、`theme`プロパティ内に`sx`オブジェクトを渡すことができます。これにより、CSSセレクターを使用してコンポーネント内の特定の要素をターゲットにできます。
+
+```tsx sxプロパティでのカスタマイズ icon=logos:react
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+import { useSessionContext } from '@/hooks/session-context';
+
+function SxStyledCheckout() {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <CheckoutForm
+        id="plink_xxx"
+        showCheckoutSummary={false}
+        onChange={console.info}
+        theme={{
+          sx: {
+            // Target the submit button by its specific class name
+            '.cko-submit-button': {
+              backgroundColor: '#1DC1C7',
+              color: '#fff',
+              '&:hover': {
+                backgroundColor: 'rgb(20, 135, 139)',
+              },
+            },
+          },
+        }}
+      />
+    </PaymentProvider>
+  );
+}
+
+```
+
+この方法は、標準のコンポーネントスタイルオーバーライドでは簡単にアクセスできないスタイルをオーバーライドする必要がある場合に便利です。
+
+## デフォルトテーマの理解
+
+デフォルトテーマは、色、スペーシング、タイポグラフィのためのCSS変数（デザイントークン）のシステム上に構築されており、ライトモードとダークモードで一貫したスタイリングを可能にします。
+
+### カラーパレット
+
+このテーマは、標準のMaterial-UIパレットをカスタム`chip`オブジェクトで拡張し、ステータスインジケーターのスタイルを設定します。これらの色はカスタムテーマでオーバーライドできます。
+
+```ts src/theme/types.ts icon=mdi:language-typescript
+declare module '@mui/material/styles' {
+  interface Palette {
+    chip: {
+      success: { text: string; background: string; border: string; };
+      default: { text: string; background: string; border: string; };
+      secondary: { text: string; background: string; border: string; };
+      error: { text: string; background: string; border: string; };
+      warning: { text: string; background: string; border: string; };
+      info: { text: string; background: string; border: string; };
+    };
+  }
+  // ... PaletteOptions definition
+}
+```
+
+### デザイントークン（CSS変数）
+
+高度なグローバルカスタマイズを行うには、テーマを定義するCSS変数をオーバーライドできます。これらの変数は、ライト（`:root`）モードとダーク（`[data-theme='dark']`）モードの両方で定義されています。
+
+以下に、ターゲットにできる主要な変数をいくつか示します：
+
+```css src/theme/index.css icon=logos:css-3
+:root {
+  /* ライトテーマ */
+  --backgrounds-bg-base: #ffffff;
+  --backgrounds-bg-interactive: #3b82f6;
+  --foregrounds-fg-base: #030712;
+  --foregrounds-fg-interactive: #3b82f6;
+  --stroke-border-base: #eff1f5;
+  --radius-m: 0.5rem; /* 8px */
+}
+
+[data-theme='dark'] {
+  /* ダークテーマ */
+  --backgrounds-bg-base: #1b1b1f;
+  --backgrounds-bg-interactive: #60a5fa;
+  --foregrounds-fg-base: #edeef0;
+  --foregrounds-fg-interactive: #60a5fa;
+  --stroke-border-base: #2e3035;
+  --radius-m: 0.5rem;
+}
+```
+
+グローバルスタイルシートでこれらの変数をオーバーライドすると、すべての`@blocklet/payment-react`コンポーネントに変更が適用されます。
+
+### タイポグラフィ
+
+デフォルトのタイポグラフィ設定は`src/theme/typography.ts`にあります。アプリケーションのタイポグラフィに合わせて、これらの設定をカスタムテーマでオーバーライドできます。
+
+```ts src/theme/typography.ts icon=mdi:language-typescript
+export const typography = {
+  h1: {
+    fontSize: '1.5rem',
+    lineHeight: 1.2,
+    fontWeight: 800,
+  },
+  body1: {
+    fontSize: '0.875rem',
+    lineHeight: 1.75,
+  },
+  // ... other typography settings
+};
+```
+
+これらのカスタマイズのレイヤーを理解することで、支払いコンポーネントをアプリケーションに一貫性のある洗練されたデザインでシームレスに統合できます。
+
+---
+
+次に、データキャッシングや日付フォーマットなどのタスクに役立つさまざまなユーティリティ関数について見ていきましょう。
+
+<x-card data-title="次へ: ユーティリティ" data-icon="lucide:wrench" data-href="/guides/utilities" data-cta="続きを読む">
+  ライブラリが提供するユーティリティ関数のリファレンス。キャッシュされたリクエストや日付フォーマットなどが含まれます。
+</x-card>

package/docs/guides-theming.zh-TW.md

@@ -0,0 +1,213 @@
+# 主題化
+
+了解如何使用內建的主題提供者和 Material-UI 主題選項來自訂支付元件的外觀。`@blocklet/payment-react` 函式庫建立在 Material-UI 之上，讓您對支付流程的外觀和風格有廣泛的控制權。
+
+## `PaymentThemeProvider` 概覽
+
+該函式庫包含一個專用的 `PaymentThemeProvider`，它包裝了所有支付元件。此提供者建立了一個預設主題，該主題繼承自 ArcBlock UX 主題 (`@arcblock/ux/lib/Theme`)，確保在 ArcBlock 生態系統中的視覺一致性。它還添加了自己的自訂功能，例如特殊的 `chip` 調色盤和對各種 MUI 元件的樣式覆寫。
+
+以下是 `PaymentThemeProvider` 結構的簡化視圖：
+
+```tsx src/theme/index.tsx icon=logos:react
+import { createTheme, ThemeProvider } from '@mui/material/styles';
+import { create as createBlockletTheme, deepmerge } from '@arcblock/ux/lib/Theme';
+
+export function PaymentThemeProvider({ children, theme: customTheme = {} }) {
+  const parentTheme = useTheme();
+
+  const mergeTheme = useMemo(() => {
+    // Start with the base blocklet theme
+    const blockletTheme = parentTheme.themeName === 'ArcBlock' ? parentTheme : createBlockletTheme();
+
+    // Merge our custom payment theme options
+    let paymentThemeOptions = deepmerge(blockletTheme, {
+      // Custom palette extensions, e.g., for chips
+      palette: {
+        chip: { /* ... */ },
+      },
+      // Custom component style overrides
+      components: {
+        MuiButton: { /* ... */ },
+        MuiOutlinedInput: { /* ... */ },
+        // ... other components
+      },
+    });
+
+    // Merge any user-provided custom theme
+    paymentThemeOptions = deepmerge(paymentThemeOptions, customTheme);
+
+    return createTheme(paymentThemeOptions);
+  }, [parentTheme, customTheme]);
+
+  return (
+    <ThemeProvider theme={mergeTheme}>
+      <CssBaseline />
+      {children}
+    </ThemeProvider>
+  );
+}
+```
+
+## 自訂元件樣式
+
+自 1.14.22 版本起，您可以透過傳遞 `theme` 屬性輕鬆地為單個支付元件自訂主題。此屬性接受一個 Material-UI `ThemeOptions` 物件，為您提供了兩種主要方式來應用自訂樣式。
+
+### 1. 使用 `styleOverrides`
+
+對於深層的、結構性的變更，您可以在支付元件的範圍內覆寫特定 Material-UI 元件的樣式。這是標準的 MUI 主題化方式。
+
+```tsx Customizing the Primary Button icon=logos:react
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+import { useSessionContext } from '@/hooks/session-context'; // 假設 session context 在此定義
+
+function CustomStyledCheckout() {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <CheckoutForm
+        id="plink_xxx"
+        onChange={console.info}
+        theme={{
+          components: {
+            MuiButton: {
+              styleOverrides: {
+                containedPrimary: {
+                  backgroundColor: '#1DC1C7',
+                  color: '#fff',
+                  '&:hover': {
+                    backgroundColor: 'rgb(20, 135, 139)',
+                  },
+                },
+              },
+            },
+          },
+        }}
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+在此範例中，我們鎖定主要包含按鈕 (`MuiButton.styleOverrides.containedPrimary`) 並更改其背景和文字顏色。
+
+### 2. 使用 `sx` 屬性
+
+對於快速、有針對性的 CSS 變更，您可以在 `theme` 屬性中傳遞一個 `sx` 物件。這允許您使用 CSS 選擇器來鎖定元件內的特定元素。
+
+```tsx Customizing with the sx Prop icon=logos:react
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+import { useSessionContext } from '@/hooks/session-context';
+
+function SxStyledCheckout() {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <CheckoutForm
+        id="plink_xxx"
+        showCheckoutSummary={false}
+        onChange={console.info}
+        theme={{
+          sx: {
+            // Target the submit button by its specific class name
+            '.cko-submit-button': {
+              backgroundColor: '#1DC1C7',
+              color: '#fff',
+              '&:hover': {
+                backgroundColor: 'rgb(20, 135, 139)',
+              },
+            },
+          },
+        }}
+      />
+    </PaymentProvider>
+  );
+}
+
+```
+
+當您需要覆寫一個透過標準元件樣式覆寫不易存取的樣式時，此方法非常有用。
+
+## 理解預設主題
+
+預設主題建立在一套用於顏色、間距和排版的 CSS 變數（設計權杖）系統之上，允許在淺色和深色模式下實現一致的樣式。
+
+### 調色盤
+
+該主題擴展了標準的 Material-UI 調色盤，增加了一個自訂的 `chip` 物件來為狀態指示器設定樣式。您可以在您的自訂主題中覆寫這些顏色。
+
+```ts src/theme/types.ts icon=mdi:language-typescript
+declare module '@mui/material/styles' {
+  interface Palette {
+    chip: {
+      success: { text: string; background: string; border: string; };
+      default: { text: string; background: string; border: string; };
+      secondary: { text: string; background: string; border: string; };
+      error: { text: string; background: string; border: string; };
+      warning: { text: string; background: string; border: string; };
+      info: { text: string; background: string; border: string; };
+    };
+  }
+  // ... PaletteOptions definition
+}
+```
+
+### 設計權杖（CSS 變數）
+
+對於進階的全域自訂，您可以覆寫定義主題的 CSS 變數。這些變數為淺色（`:root`）和深色（`[data-theme='dark']`）模式都進行了定義。
+
+以下是您可以鎖定的一些關鍵變數：
+
+```css src/theme/index.css icon=logos:css-3
+:root {
+  /* 淺色主題 */
+  --backgrounds-bg-base: #ffffff;
+  --backgrounds-bg-interactive: #3b82f6;
+  --foregrounds-fg-base: #030712;
+  --foregrounds-fg-interactive: #3b82f6;
+  --stroke-border-base: #eff1f5;
+  --radius-m: 0.5rem; /* 8px */
+}
+
+[data-theme='dark'] {
+  /* 深色主題 */
+  --backgrounds-bg-base: #1b1b1f;
+  --backgrounds-bg-interactive: #60a5fa;
+  --foregrounds-fg-base: #edeef0;
+  --foregrounds-fg-interactive: #60a5fa;
+  --stroke-border-base: #2e3035;
+  --radius-m: 0.5rem;
+}
+```
+
+在您的全域樣式表中覆寫這些變數，將會對所有 `@blocklet/payment-react` 元件應用變更。
+
+### 排版
+
+預設的排版設定可以在 `src/theme/typography.ts` 中找到。您可以在您的自訂主題中覆寫任何這些設定，以匹配您應用程式的排版。
+
+```ts src/theme/typography.ts icon=mdi:language-typescript
+export const typography = {
+  h1: {
+    fontSize: '1.5rem',
+    lineHeight: 1.2,
+    fontWeight: 800,
+  },
+  body1: {
+    fontSize: '0.875rem',
+    lineHeight: 1.75,
+  },
+  // ... other typography settings
+};
+```
+
+透過理解這些自訂層次，您可以將支付元件無縫整合到您的應用程式中，並實現一致且精緻的設計。
+
+---
+
+接下來，探索各種實用工具函式，這些函式可以幫助您處理資料快取和日期格式化等任務。
+
+<x-card data-title="下一步：實用工具" data-icon="lucide:wrench" data-href="/guides/utilities" data-cta="閱讀更多">
+  該函式庫提供的實用工具函式參考，包括快取請求和日期格式化。
+</x-card>

package/docs/guides-theming.zh.md

@@ -0,0 +1,213 @@
+# 主题化
+
+了解如何使用内置的主题提供器和 Material-UI 主题选项来自定义支付组件的外观。`@blocklet/payment-react` 库基于 Material-UI 构建，让您能够广泛地控制支付流程的观感。
+
+## `PaymentThemeProvider` 概览
+
+该库包含一个专用的 `PaymentThemeProvider`，它包裹了所有支付组件。此提供器建立了一个默认主题，该主题继承自 ArcBlock UX 主题 (`@arcblock/ux/lib/Theme`)，以确保在 ArcBlock 生态系统内的视觉一致性。它还添加了自己的自定义项，例如一个特殊的 `chip` 调色板和对各种 MUI 组件的样式覆盖。
+
+以下是 `PaymentThemeProvider` 结构的简化示例：
+
+```tsx src/theme/index.tsx icon=logos:react
+import { createTheme, ThemeProvider } from '@mui/material/styles';
+import { create as createBlockletTheme, deepmerge } from '@arcblock/ux/lib/Theme';
+
+export function PaymentThemeProvider({ children, theme: customTheme = {} }) {
+  const parentTheme = useTheme();
+
+  const mergeTheme = useMemo(() => {
+    // 从基础 blocklet 主题开始
+    const blockletTheme = parentTheme.themeName === 'ArcBlock' ? parentTheme : createBlockletTheme();
+
+    // 合并我们的自定义支付主题选项
+    let paymentThemeOptions = deepmerge(blockletTheme, {
+      // 自定义调色板扩展，例如，用于 chip
+      palette: {
+        chip: { /* ... */ },
+      },
+      // 自定义组件样式覆盖
+      components: {
+        MuiButton: { /* ... */ },
+        MuiOutlinedInput: { /* ... */ },
+        // ... 其他组件
+      },
+    });
+
+    // 合并任何用户提供的自定义主题
+    paymentThemeOptions = deepmerge(paymentThemeOptions, customTheme);
+
+    return createTheme(paymentThemeOptions);
+  }, [parentTheme, customTheme]);
+
+  return (
+    <ThemeProvider theme={mergeTheme}>
+      <CssBaseline />
+      {children}
+    </ThemeProvider>
+  );
+}
+```
+
+## 自定义组件样式
+
+从 1.14.22 版本开始，您可以通过传递 `theme` 属性轻松地为单个支付组件自定义主题。该属性接受一个 Material-UI `ThemeOptions` 对象，为您提供了两种应用自定义样式的主要方法。
+
+### 1. 使用 `styleOverrides`
+
+对于深度的结构性更改，您可以在支付组件的作用域内覆盖特定 Material-UI 组件的样式。这是标准的 MUI 主题化方法。
+
+```tsx Customizing the Primary Button icon=logos:react
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+import { useSessionContext } from '@/hooks/session-context'; // 假设 session 上下文在此处定义
+
+function CustomStyledCheckout() {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <CheckoutForm
+        id="plink_xxx"
+        onChange={console.info}
+        theme={{
+          components: {
+            MuiButton: {
+              styleOverrides: {
+                containedPrimary: {
+                  backgroundColor: '#1DC1C7',
+                  color: '#fff',
+                  '&:hover': {
+                    backgroundColor: 'rgb(20, 135, 139)',
+                  },
+                },
+              },
+            },
+          },
+        }}
+      />
+    </PaymentProvider>
+  );
+}
+```
+
+在此示例中，我们针对主 contained 按钮 (`MuiButton.styleOverrides.containedPrimary`) 并更改其背景和文本颜色。
+
+### 2. 使用 `sx` 属性
+
+对于快速、有针对性的 CSS 更改，您可以在 `theme` 属性中传递一个 `sx` 对象。这允许您使用 CSS 选择器来定位组件内的特定元素。
+
+```tsx Customizing with the sx Prop icon=logos:react
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+import { useSessionContext } from '@/hooks/session-context';
+
+function SxStyledCheckout() {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connect={connectApi}>
+      <CheckoutForm
+        id="plink_xxx"
+        showCheckoutSummary={false}
+        onChange={console.info}
+        theme={{
+          sx: {
+            // 通过其特定的类名来定位提交按钮
+            '.cko-submit-button': {
+              backgroundColor: '#1DC1C7',
+              color: '#fff',
+              '&:hover': {
+                backgroundColor: 'rgb(20, 135, 139)',
+              },
+            },
+          },
+        }}
+      />
+    </PaymentProvider>
+  );
+}
+
+```
+
+当您需要覆盖一个通过标准组件样式覆盖不易访问的样式时，此方法非常有用。
+
+## 理解默认主题
+
+默认主题建立在颜色、间距和排版的 CSS 变量（设计令牌）系统之上，从而在亮色和暗色模式下实现一致的样式。
+
+### 调色板
+
+该主题通过一个自定义的 `chip` 对象扩展了标准的 Material-UI 调色板，用于设置状态指示器的样式。您可以在您的自定义主题中覆盖这些颜色。
+
+```ts src/theme/types.ts icon=mdi:language-typescript
+declare module '@mui/material/styles' {
+  interface Palette {
+    chip: {
+      success: { text: string; background: string; border: string; };
+      default: { text: string; background: string; border: string; };
+      secondary: { text: string; background: string; border: string; };
+      error: { text: string; background: string; border: string; };
+      warning: { text: string; background: string; border: string; };
+      info: { text: string; background: string; border: string; };
+    };
+  }
+  // ... PaletteOptions 定义
+}
+```
+
+### 设计令牌（CSS 变量）
+
+对于高级的全局自定义，您可以覆盖定义主题的 CSS 变量。这些变量为亮色模式 (`:root`) 和暗色模式 (`[data-theme='dark']`) 都进行了定义。
+
+以下是您可以作为目标的一些关键变量：
+
+```css src/theme/index.css icon=logos:css-3
+:root {
+  /* 亮色主题 */
+  --backgrounds-bg-base: #ffffff;
+  --backgrounds-bg-interactive: #3b82f6;
+  --foregrounds-fg-base: #030712;
+  --foregrounds-fg-interactive: #3b82f6;
+  --stroke-border-base: #eff1f5;
+  --radius-m: 0.5rem; /* 8px */
+}
+
+[data-theme='dark'] {
+  /* 暗色主题 */
+  --backgrounds-bg-base: #1b1b1f;
+  --backgrounds-bg-interactive: #60a5fa;
+  --foregrounds-fg-base: #edeef0;
+  --foregrounds-fg-interactive: #60a5fa;
+  --stroke-border-base: #2e3035;
+  --radius-m: 0.5rem;
+}
+```
+
+在您的全局样式表中覆盖这些变量，将会把更改应用到所有 `@blocklet/payment-react` 组件。
+
+### 排版
+
+默认的排版设置可以在 `src/theme/typography.ts` 中找到。您可以在您的自定义主题中覆盖任何这些设置，以匹配您应用程序的排版。
+
+```ts src/theme/typography.ts icon=mdi:language-typescript
+export const typography = {
+  h1: {
+    fontSize: '1.5rem',
+    lineHeight: 1.2,
+    fontWeight: 800,
+  },
+  body1: {
+    fontSize: '0.875rem',
+    lineHeight: 1.75,
+  },
+  // ... 其他排版设置
+};
+```
+
+通过理解这些自定义层次，您可以将支付组件无缝集成到您的应用程序中，并实现一致且精致的设计。
+
+---
+
+接下来，探索各种可以帮助您完成数据缓存和日期格式化等任务的实用工具函数。
+
+<x-card data-title="下一步：实用工具" data-icon="lucide:wrench" data-href="/guides/utilities" data-cta="阅读更多">
+  该库提供的实用工具函数参考，包括缓存请求和日期格式化。
+</x-card>