@blocklet/ui-react/docs/components-utilities.ja.md

Some useful front-end web components that can be used in Blocklets.

# ユーティリティ

このセクションでは、ヘルパーコンポーネント、高階コンポーネント (HOC)、およびユーティリティ関数のコレクションに関するドキュメントを提供します。これらのツールは、一般的な開発タスクを簡素化し、アプリケーションのテーマを管理し、複雑なデータ構造を処理するように設計されています。

利用可能な主なユーティリティは次のとおりです。

<x-cards data-columns="2">
  <x-card data-title="アイコンコンポーネント" data-icon="lucide:image" data-href="/components/utilities/icon">
    Iconify、画像 URL、またはレターアバターなど、さまざまなソースからアイコンを表示するための多用途なコンポーネント。
  </x-card>
  <x-card data-title="OverridableThemeProvider" data-icon="lucide:palette">
    開発者が独自のテーマオブジェクトを提供して、デフォルトの Blocklet UI テーマを上書きできるようにするテーマプロバイダー。
  </x-card>
  <x-card data-title="withHideWhenEmbed HOC" data-icon="lucide:eye-off">
    アプリケーションが埋め込みモードの場合にコンポーネントを条件付きでレンダリングし、非表示にする高階コンポーネント。
  </x-card>
  <x-card data-title="JavaScript ヘルパー" data-icon="lucide:function-square">
    再帰的な配列操作、URL 検証、パスのマッチングなどのタスクのためのスタンドアロン関数のスイート。
  </x-card>
</x-cards>

`Icon` コンポーネントの詳細なガイドについては、専用のドキュメントページを参照してください。その他のユーティリティについては、以下で説明します。

## OverridableThemeProvider

このコンポーネントは、Material-UI の `ThemeProvider` のラッパーです。これにより、その子コンポーネントに一貫したテーマを適用できます。デフォルトでは、標準の Blocklet UI テーマを使用しますが、`theme` プロパティを介してカスタムテーマオブジェクトを提供することで、デフォルトのスタイルを上書きできます。

### 使用方法

カスタムテーマを適用するには、`theme` プロパティにテーマオブジェクトを渡します。コンポーネントは、あなたのオーバーライドをデフォルトテーマとマージします。

```javascript テーマプロバイダーの例 icon=logos:javascript
import OverridableThemeProvider from '@blocklet/ui-react/lib/common/overridable-theme-provider';
import { Button } from '@mui/material';

const customTheme = {
  palette: {
    primary: {
      main: '#ff5722',
    },
  },
};

function App() {
  return (
    <OverridableThemeProvider theme={customTheme}>
      <Button color="primary" variant="contained">
        Custom Themed Button
      </Button>
    </OverridableThemeProvider>
  );
}
```

## withHideWhenEmbed

`withHideWhenEmbed` は、アプリケーションが「埋め込みモード」の場合にコンポーネントのレンダリングを防ぐ高階コンポーネント (HOC) です。セッションストレージキー (`EMBED_MODE_KEY`) をチェックして現在のモードを判断します。値が `1` の場合、ラップされたコンポーネントは `null` を返します。

これは、ヘッダーやフッターなど、不要な埋め込みコンテキストで要素を非表示にするのに役立ちます。

### 使用方法

条件付きで非表示にしたいコンポーネントを `withHideWhenEmbed` HOC でラップします。

```javascript HOC の例 icon=logos:javascript
import withHideWhenEmbed from '@blocklet/ui-react/lib/libs/with-hide-when-embed';

function PageHeader() {
  return (
    <header>
      <h1>My Application</h1>
    </header>
  );
}

const MaybeHiddenHeader = withHideWhenEmbed(PageHeader);

function App() {
  return (
    <div>
      <MaybeHiddenHeader />
      <main>
        {/* Main content goes here */}
      </main>
    </div>
  );
}
```

## ヘルパー関数

一般的なデータ操作および検証タスクのために、一連の純粋な JavaScript 関数が利用可能です。これらは、ライブラリのユーティリティモジュールから直接インポートできます。

### 配列操作

これらの関数は、ナビゲーションメニューやファイルツリーなど、ネストされたオブジェクトの配列を扱うように設計されています。

| 関数 | 説明 |
| --- | --- |
| `mapRecursive(array, fn, childrenKey = 'children')` | ネストされた配列の各項目に再帰的に関数を適用します。 |
| `flatRecursive(array, childrenKey = 'children')` | ネストされた配列を単一レベルの配列にフラット化します。 |
| `countRecursive(array, childrenKey = 'children')` | ネストされた配列内の項目の総数を数えます。 |
| `filterRecursive(array, predicate, childrenKey = 'children')` | 述語関数に基づいてネストされた配列を再帰的にフィルタリングし、子が一致する場合は親の構造を保持します。 |

### 文字列と URL の検証

文字列形式をチェックするためのシンプルなヘルパーです。

| 関数 | 説明 |
| --- | --- |
| `isUrl(str)` | 文字列が `http://` または `https://` で始まる場合に `true` を返します。 |
| `isMailProtocol(str)` | 文字列が `mailto:` で始まる場合に `true` を返します。 |

### ルーティング

クライアント側のルーティングロジックを支援するユーティリティです。

| 関数 | 説明 |
| --- | --- |
| `matchPath(path)` | 指定されたパスが現在の `window.location.pathname` と一致するかどうかをチェックします。 |
| `matchPaths(paths)` | パスの配列から、現在のロケーションに対して最も一致するパスを見つけます。 |

### レイアウト

| 関数 | 説明 |
| --- | --- |
| `splitNavColumns(items, options)` | ナビゲーション項目のリストを指定された数の列に分割します。メガメニューの作成に便利です。 |

---

### まとめ

このセクションでは、ライブラリに含まれる汎用ユーティリティの概要を説明しました。より強力で専門的な機能については、個々のコンポーネントの詳細なドキュメントに進んでください。

柔軟な `Icon` コンポーネントの使用に関する包括的なガイドについては、次のセクションを参照してください。
- **[アイコン](./components-utilities-icon.md)**