@blocklet/ui-react/docs/components-layout-dashboard.ja.md

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

# Dashboard

`Dashboard` コンポーネントは、blocklet アプリケーション向けに、レスポンシブなレイアウトを事前に構築して提供します。これは通常、管理インターフェースやユーザー中心のビューに使用されます。blocklet のメタデータを解釈することで、サイドバー、ヘッダー、およびメインコンテンツエリアを持つ標準的なダッシュボードを自動的に構築します。このコンポーネントにより、一般的なアプリケーション構造を構築するための定型的なコードが大幅に削減されます。

レイアウトは、ナビゲーション用の永続的なサイドバー、グローバルなアクションとユーザー情報用のヘッダー、そしてページ固有のコンテンツがレンダリングされるメインコンテンツエリアの3つの主要なセクションで構成されています。

<!-- DIAGRAM_IMAGE_START:architecture:16:9:1765962229 -->
![Dashboard](assets/diagram/dashboard-diagram-0.ja.jpg)
<!-- DIAGRAM_IMAGE_END -->

## 基本的な使用方法

`Dashboard` コンポーネントを使用するには、ページのコンテンツをそれでラップするだけです。コンポーネントは自動的にコンテンツの周りにヘッダーとサイドバーをレンダリングします。

```javascript MyDashboard.jsx icon=logos:react
import Dashboard from '@arcblock/blocklet-ui-react/lib/Dashboard';

export default function MyDashboardPage() {
  return (
    <Dashboard>
      <h1>Welcome to the Dashboard</h1>
      <p>This is your main content area.</p>
    </Dashboard>
  );
}
```

`Dashboard` コンポーネントに渡された children は、メインコンテンツエリアに表示されます。

## Props

`Dashboard` コンポーネントは、その動作と外観をカスタマイズするために、以下の props を受け入れます。

<x-field-group>
  <x-field data-name="children" data-type="React.ReactNode" data-required="true">
    <x-field-desc markdown>ダッシュボードレイアウトのメインコンテンツエリア内にレンダリングされるコンテンツ。</x-field-desc>
  </x-field>
  <x-field data-name="meta" data-type="object" data-required="false">
    <x-field-desc markdown>blocklet メタデータオブジェクト。指定された場合、デフォルトの `window.blocklet` メタデータとマージされ、上書きされます。これは、テストや blocklet 情報を動的に変更する場合に便利です。</x-field-desc>
  </x-field>
  <x-field data-name="fallbackUrl" data-type="string" data-required="false" data-default="publicPath">
    <x-field-desc markdown>現在の認証済みユーザーがその役割に基づいてどのナビゲーションリンクにもアクセスできない場合にリダイレクトする URL。この自動リダイレクトを無効にするには `null` に設定します。</x-field-desc>
  </x-field>
  <x-field data-name="invalidPathFallback" data-type="function" data-required="false">
    <x-field-desc markdown>現在の URL パスが利用可能なナビゲーションリンクのいずれとも一致しない場合に実行されるコールバック関数。デフォルトの動作は、利用可能な最初のリンクにリダイレクトすることです。</x-field-desc>
  </x-field>
  <x-field data-name="headerAddons" data-type="React.ReactNode | function" data-required="false">
    <x-field-desc markdown>ヘッダーの右側のアドオンのカスタマイズを可能にします。ノードが提供された場合、すべてのデフォルトアドオンを置き換えます。関数が提供された場合、デフォルトのアドオン配列を引数として受け取り、それらを追加、削除、または並べ替えることができます。</x-field-desc>
  </x-field>
  <x-field data-name="sessionManagerProps" data-type="object" data-required="false">
    <x-field-desc markdown>ヘッダー内の基盤となる `SessionUser` コンポーネントに直接渡される Props。これにより、`showRole` やカスタムの `onLogout` ハンドラの定義など、ユーザーセッションメニューのカスタマイズが可能になります。</x-field-desc>
  </x-field>
  <x-field data-name="links" data-type="array | function" data-required="false">
    <x-field-desc markdown>サイドバーのナビゲーションリンクをプログラムで変更できるようにします。配列が提供された場合、そのアイテムはメタデータから生成されたリンクに追加されます。関数が提供された場合、メタデータから生成されたリンクを引数として受け取り、新しいリンクの配列を返す必要があります。</x-field-desc>
  </x-field>
  <x-field data-name="showDomainWarningDialog" data-type="boolean" data-required="false" data-default="true">
    <x-field-desc markdown>`true` の場合、信頼できないドメインからアプリケーションにアクセスされた場合に警告ダイアログを表示します。</x-field-desc>
  </x-field>
</x-field-group>

## 仕組み

`Dashboard` コンポーネントは、「設定駆動型」で設計されており、その構造とコンテンツは主に blocklet のメタデータファイル (`blocklet.yml`) から派生します。

### メタデータからのナビゲーション

サイドバーのナビゲーションは、`blocklet.yml` の `navigation` 配列から自動的に生成されます。コンポーネントは、`section` プロパティに `dashboard` を含むナビゲーション項目を具体的に探します。

以下は、ダッシュボードナビゲーションを定義する方法の例です。

```yaml blocklet.yml icon=mdi:file-document
navigation:
  - title: 'Home'
    link: '/'
    section: 'dashboard'
    icon: 'mdi:home'
    role: ['owner', 'admin', 'guest']
  - title: 'Analytics'
    link: '/analytics'
    section: 'dashboard'
    icon: 'mdi:chart-bar'
    role: ['owner', 'admin']
  - title: 'Settings'
    link: '/settings'
    section: 'dashboard'
    icon: 'mdi:cog'
    role: ['owner']
    items:
      - title: 'Profile'
        link: '/settings/profile'
      - title: 'Billing'
        link: '/settings/billing'
```

### ロールベースのアクセス制御

`Dashboard` コンポーネントは、ナビゲーションリンクに対してロールベースのアクセス制御 (RBAC) を強制します。各ナビゲーション項目は `role` プロパティを持つことができ、これはリンクを見ることが許可されているロールの配列です。

- ナビゲーション項目に `role` プロパティがない場合、それは誰にでも表示されます。
- 現在のユーザーが認証されていない場合、`guest` ロールを含む項目のみを見ることができます。
- 現在のユーザーが認証されている場合、コンポーネントは彼らの `user.role` を各ナビゲーション項目の `role` 配列と比較します。一致がある場合にのみ項目が表示されます。
- 親ナビゲーション項目は、その子の少なくとも1つが表示される場合にのみ表示されます。

上記の `blocklet.yml` の例を使用すると：
- `guest` ロールのユーザーは「Home」リンクのみを見ることができます。
- `admin` ロールのユーザーは「Home」と「Analytics」を見ることができます。
- `owner` ロールのユーザーは、「Settings」の下にあるネストされた「Profile」と「Billing」リンクを含むすべてのリンクを見ることができます。

### アイコン

ナビゲーション項目の `icon` プロパティは、[Iconify](https://icon-sets.iconify.design/) ライブラリのアイコン名に対応する文字列（例：`mdi:home`）である必要があります。画像ファイルへの完全な URL を提供することもできます。

## カスタマイズ

`Dashboard` はメタデータですぐに使えるように設計されていますが、より高度なカスタマイズのためのいくつかの props を提供しています。

### ヘッダーアドオンのカスタマイズ

`headerAddons` prop を使用して、デフォルトのヘッダーアドオン（例：テーマ切り替え、ロケールセレクター、セッションマネージャー）を変更できます。関数を渡すことで、新しい要素を追加したり、既存の要素を並べ替えたりすることができます。

```javascript CustomHeader.jsx icon=logos:react
import Dashboard from '@arcblock/blocklet-ui-react/lib/Dashboard';
import Button from '@mui/material/Button';

function MyCustomButton() {
  return <Button color="inherit" onClick={() => alert('Help!')}>Help</Button>;
}

export default function CustomDashboard() {
  return (
    <Dashboard
      headerAddons={(existingAddons) => {
        const customAddon = <MyCustomButton key="custom-help" />;
        // Add the custom button before the other addons
        return [customAddon, ...existingAddons];
      }}
    >
      <p>Dashboard with a custom header button.</p>
    </Dashboard>
  );
}
```

### リンクのプログラムによる追加

`links` prop を使用すると、コードから動的にサイドバーのナビゲーションリンクを追加または変更できます。これは、アプリケーションの状態に依存するリンクに便利です。

```javascript DynamicLinks.jsx icon=logos:react
import Dashboard from '@arcblock/blocklet-ui-react/lib/Dashboard';
import Icon from '@arcblock/ux/lib/Icon';

const useFeatureFlag = () => {
  // 実際のアプリでは、ここでフィーチャーフラグサービスをチェックします
  return true;
};

export default function DynamicDashboard() {
  const isBetaFeatureEnabled = useFeatureFlag();

  return (
    <Dashboard
      links={(existingLinks) => {
        if (isBetaFeatureEnabled) {
          const betaLink = {
            id: 'beta-feature',
            title: 'Beta Feature',
            url: '/beta',
            icon: <Icon name="mdi:test-tube" />,
            external: true, // クライアントサイドのルーティングに必要
          };
          return [...existingLinks, betaLink];
        }
        return existingLinks;
      }}
    >
      <p>This dashboard may have dynamic links.</p>
    </Dashboard>
  );
}

```

## まとめ

`Dashboard` コンポーネントは、アプリケーションのレイアウトを迅速に構築するための強力なツールです。blocklet メタデータを活用することで、構造化され、ロールを認識するナビゲーションシステムをすぐに提供します。より基本的なレイアウトコンポーネントについては、[Header](./components-layout-header.md) と [Footer](./components-layout-footer.md) のドキュメントを参照してください。