@47stats/47maps-dashboard

47stats API を使った人口統計ダッシュボードを、React コンポーネントとして組み込めるライブラリです。

都道府県と市区町村の人口データ、人口推移、世帯数推移、年齢構成、転入転出、出生死亡などを、ダッシュボードや個別ウィジェットとして利用できます。

特徴

• React 18 / 19 対応
• TypeScript 対応
• ESM / CJS 両対応
• Recharts ベースのチャートコンポーネント
• Flowbite React ベースの UI
• ダークモード対応
• コンポーネント単位で再利用可能
• ConfigProvider で 47stats API 設定を一元化

想定用途

• 人口統計ダッシュボードの組み込み
• 都道府県 / 市区町村の比較レポート表示
• 47stats API を使った分析画面の素早い立ち上げ
• 既存 React アプリへの統計ウィジェット追加

インストール

npm install @47stats/47maps-dashboard @47stats/api

Peer Dependencies

• react >= 18.0.0 < 20.0.0
• react-dom >= 18.0.0 < 20.0.0
• @47stats/api >= 0.9.0 < 1.0.0

クイックスタート

最小構成

import { ConfigProvider, DemographicReport } from "@47stats/47maps-dashboard";
import "@47stats/47maps-dashboard/style.css";

export default function App() {
  return (
    <ConfigProvider
      userConfig={{
        statsApiUrl: "https://your-api.example.com",
        statsApiKey: "your-api-key",
      }}
    >
      <DemographicReport />
    </ConfigProvider>
  );
}

環境変数を使う場合

このライブラリ自身は環境変数を読み取りません。利用アプリ側で環境変数を読み取り、userConfig に渡してください。

このリポジトリのデモアプリでは、本番用の .env.production とローカル開発用の .env.development.local を使用します。npm run dev はdevelopment用、npm run build はproduction用の設定を読み込みます。

cp .env.example .env.production
cp .env.example .env.development.local

VITE_STATS_API_URL=https://your-api.example.com
VITE_STATS_API_KEY=your-api-key

import { ConfigProvider, DemographicReport } from "@47stats/47maps-dashboard";
import "@47stats/47maps-dashboard/style.css";

export default function App() {
  return (
    <ConfigProvider
      userConfig={{
        statsApiUrl: import.meta.env.VITE_STATS_API_URL,
        statsApiKey: import.meta.env.VITE_STATS_API_KEY,
      }}
    >
      <DemographicReport />
    </ConfigProvider>
  );
}

セキュリティと既知の制約

1. API キーは公開用に限定されます。 userConfig や VITE_* 環境変数に指定した値はブラウザへ配布され、利用者から参照できます。秘密鍵や管理者権限を持つキーは指定しないでください。API 側で許可リファラーを制限し、キーには必要最小限の権限とレート制限を設定してください。

2. API 設定は JavaScript 実行環境内で共有されます。 @47stats/api の API URL と API キーはプロセス内の共有設定です。同一のブラウザページや SSR サーバープロセスでは、すべての ConfigProvider に同じ設定を指定してください。異なる設定を同時に指定するとエラーになります。テナントごとに異なる設定が必要な SSR 構成では、テナントごとに実行環境を分離してください。

提供コンポーネント

ダッシュボード

• DemographicReport 都道府県選択から市区町村の詳細チャートまで含んだメインダッシュボードです。

• TabPanel レポート表示用のタブ UI です。

ウィジェット

• PrefPopulation
• CityPopulation
• PopulationTransition
• HouseholdTransition
• PercentagePopulation
• RatioPopulation
• AgeGroupPopulation
• InOutPopulation
• BirthDeathPopulation
• ScrollableContainer

チャート

• DataBarChart
• DataLineChart
• DataAreaChart
• DataPieChart

レイアウト / フック / 設定

• GridLayout
• ConfigProvider
• useConfig
• useChartTheme

利用例

個別ウィジェットを組み込む

import {
  ConfigProvider,
  PrefPopulation,
  CityPopulation,
  GridLayout,
} from "@47stats/47maps-dashboard";
import "@47stats/47maps-dashboard/style.css";

export default function DashboardPage() {
  return (
    <ConfigProvider
      userConfig={{
        statsApiUrl: "https://your-api.example.com",
        statsApiKey: "your-api-key",
      }}
    >
      <GridLayout className="grid-cols-1 lg:grid-cols-2">
        <PrefPopulation title="人口総数" />
        <CityPopulation area="13" name="東京都" title="人口総数・東京都" />
      </GridLayout>
    </ConfigProvider>
  );
}

スタイリング

このライブラリは Flowbite React と Tailwind CSS を前提にしたコンポーネントを含みます。

Tailwind を利用するアプリでは、必要に応じて content にライブラリの配下を追加してください。

export default {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/flowbite-react/**/*.js",
    "./node_modules/@47stats/47maps-dashboard/dist/**/*.js",
  ],
  darkMode: "class",
};

開発

npm ci
npm run dev
npm run typecheck
npm run lint
npm test
npm run test:coverage
npm run build:lib
npm run build:pkg

主なスクリプト

• npm run dev 開発サーバーを起動します。

• npm run build サンプルアプリをビルドします。

• npm run build:lib ライブラリをビルドします。

• npm run build:pkg npm 配布用パッケージを作成します。

• npm run typecheck TypeScript 型チェックを実行します。

• npm test ユニットテストを実行します。

• npm run test:coverage カバレッジ付きでテストを実行します。

品質状況

現状の確認結果は次のとおりです。

• テストファイル: 11 passed
• テストケース: 34 passed
• 総合カバレッジ（Statements）: 53.36%
• チャートコンポーネントのカバレッジ（Statements）: 80.72%

詳細は TEST_REPORT.md を参照してください。

公開前チェック

GitHub や npm に公開する前は、最低限次を実行してください。

npm run verify
npm run build:lib
npm pack --dry-run

verify では型チェック、Lint、テストを実行します。prepublishOnly では verify と build:lib が実行されます。

初回公開時を含め、このパッケージは publishConfig により npmjs.com のpublic packageとして公開されます。

npm publish

リポジトリ公開時にあるとよいもの

• GitHub Topics react, dashboard, statistics, demographics, recharts, typescript

• リポジトリ説明文 React dashboard components for 47stats demographic data visualization

• 公開後の追加候補

  • スクリーンショット
  • Storybook または docs サイト
  • API リファレンス
  • 使用例アプリへのリンク

ライセンス

MIT

Links

• Repository: https://github.com/47stats/47maps-dashboard
• Issues: https://github.com/47stats/47maps-dashboard/issues
• npm: https://www.npmjs.com/package/@47stats/47maps-dashboard