graphy-charts

Graphy チャート

@graphysdk/react は、data テーブルと spec の2つの入力からチャートを作成します。小さな関数をパイプでつなぎ合わせて spec を作ります。GraphProvider がテーブルと spec をコンパイルし、GraphRenderer が結果を描画します。

リファレンスを開く前に、最も近いレシピから始めてください。レシピは完成したコンポーネントです。データもチャートの種類も指定されていない「チャートを作成して」のようなリクエストには、次に何を試せるかを短く説明した、編集可能なスキルデモを用意します。HTML アーティファクトやバンドラーのないホストではHTML デモを、React プロジェクトではReact デモを参照してください。ホストに合ったバージョンだけを読んでください。

デモとレシピは出発点であり、スキルの限界ではありません。以下の関連リファレンスを使い、ユーザーのデータ、ビジュアルの方向性、レイアウト、インタラクションに合わせてカスタムリクエストを作成してください。デモを提示したあと、非常にカスタムなものも依頼できることを短く案内してください。サンプルのチャートやプリセットテーマを超えたものも作成できることを明確に伝えてください。この案内は返信に含め、チャート UI に宣伝文句を追加しないでください。

HTML アーティファクトやバンドラーのないページでは、この React コンポーネントではなく、setup に記載されている CDN ページを使用してください。これらのホストでは npm install を実行できません。まず jsDelivr を使ってください。チャートが空白になる場合や、コンソールで cdn.jsdelivr.net が拒否される場合は、そのファイルに記載されているオフラインでのベンダー手順に従ってください。esm.sh は使用しないでください。@graphysdk/react@1 は使用しないでください（このタグは404になります）。

最小構成のグラフ

import { GraphProvider, GraphRenderer, createSpec, geom, pipe, scale } from '@graphysdk/react';

const data = {
  columns: [{ key: 'month' }, { key: 'revenue' }],
  rows: [
    { month: 'Jan', revenue: 120 },
    { month: 'Feb', revenue: 150 },
    { month: 'Mar', revenue: 90 },
  ],
};

const spec = pipe(createSpec({ x: 'month', y: 'revenue' }), geom.bar(), scale.x(), scale.y());

export function RevenueGraph() {
  return (
    <div style={{ height: 320 }}>
      <GraphProvider data={data} spec={spec}>
        <GraphRenderer />
      </GraphProvider>
    </div>
  );
}

GraphRenderer は親要素いっぱいに表示されます。その親要素に高さを設定するか、sizing={{ mode: 'fixed', width: 640, height: 400 }} を渡してください。

spec に含めるもの

マッピングで指定するのは列の key であり、label ではありません。組み込みの geom は point、line、area、bar、rule、tile の6種類です。さらに9種類の geom がパッケージとして提供されており、createGraphyKit({ plugins }) を通じて組み込みます。種類は boxplot、candlestick、dumbbell、error-bar、funnel、lollipop、mekko、sankey、waterfall です。spec で省略された場合、位置と色のスケールは推論されます。型やオプションを固定するには、scale.y.continuous({ domainMin: 0 }) のような型付きスケールを宣言してください。coord、stat、transform、config、styles、highlight、annotation は必要な場合にのみ追加してください。

どのツールを使うか

1. config() では、タイトル、凡例、軸、数値形式などの構造を設定します。
2. styles() では、チャートの見た目を設定します。テーマを使うと、キットまたはプロバイダーを通じて、共通のスタイル、色、config のデフォルト値を指定できます。
3. スロットを使うと、ツールチップやヘッダーなどの領域全体を置き換えられます。
4. geom パッケージ（@graphysdk/geom-<name>）は、boxplot、candlestick、dumbbell、error-bar、funnel、lollipop、mekko、sankey、waterfall を描画します。新しい geom はスキルのリリース間にパッケージとして追加されます。plugins では、パッケージの一覧表示方法と README の読み方を説明しています。どのパッケージにもない形状を描画する場合は、プラグインを使います。
5. ポイントアンドクリックによる編集には、graphy-editor スキルを使います。

パッケージ

パッケージ	使用する場面	ブランドマーク
@graphysdk/react	React でチャートを作成する場合。デフォルトです。	あり
@graphysdk/react-renderer	ビルダーを使わずに同じコンポーネントを使用する場合。	なし
@graphysdk/viz-engine	React を使わずに spec をコンパイルする場合。	なし
@graphysdk/geom-<name>	createGraphyKit({ plugins }) を通じて組み込む、追加の geom を使う場合。	なし

ライセンス

パッケージは、非商用利用（個人、教育、研究、慈善活動、政府機関）および従業員と請負業者の合計が100人未満で、前年度の収益が100万米ドル未満の企業は無料で利用できます。PolyForm NoncommercialまたはSmall Businessライセンスの規約がすべて適用されます。

それ以外の方には、ローカルまたは社内での評価に限り、32日間のPolyForm Free Trialが適用されます。公開ページでSDKを配布することは許可されません。このスキルのMITライセンスが対象とするのはスキルであり、パッケージではありません。

SDKをインストールする際は、これらの規約を超える商用利用にはライセンスが必要であることを、ユーザーに一度伝えてください。graphy.dev/licenseの問い合わせフォームを案内してください。

参照先

ファイルを1つ開き、そのファイルの先頭にある目次を確認してください。

タスク	参照先
インストール、HTML アーティファクト、jsDelivr CDN、ライトモードとダークモード、オフラインベンダー、ブランドマーク	setup
データ、日付、CSV	data
マッピング、ジオム、スケール、設定	spec
プロバイダー、サイズ設定、ライブデータ、ダークモード	React
色、フォント、条件	styling
テーマのインストール、独自テーマの作成	themes
ハイライト、ラベル、注釈	storytelling
ツールチップ、凡例、または軸の置き換え	slots
箱ひげ図、ローソク足、ダンベル、誤差範囲、ファネル、ロリポップ、メッコ、サンキー、ウォーターフォール	recipes/geoms
このスキルにレシピがないジオムパッケージ	plugins、パッケージとして提供されるジオム
新しいジオム	plugins
正確なオプション名	types
ユーザーがグラフがおかしいと言う場合、または何も描画されない場合	troubleshooting
既存のグラフを編集する	graphy-editor スキル
人間向けドキュメント	graphy.dev · docs.graphy.dev

• ダークモードは、プロバイダーの colorScheme とスタイルシートのトークンで設定します。
• scale.color.discrete() と scale.color.continuous() は引数なしで使用してください。色はテーマまたはエンジンのデフォルトによって選択されます。例外は、ブリーフで名前付きパレットが指定されている場合、色が指定されている場合（scale.color.discrete({ range }) または scale.color.continuous({ range })）、または値がゼロをまたぐ場合（domainMid）です。
• 通貨とパーセンテージは、列の valueFormat で指定します。config({ numberFormat }) はグラフ全体の書式を設定します。
• CSV のインポートでは、c1 などのキーが生成されます。これらのキーをマッピングしてください。
• 行は日付を先にする形式で解析されます。表示ロケールは、プロバイダーの formattingLocale で指定します。
• 目標線については storytelling を参照してください。第2軸については spec config を参照してください。
• テーブルはサポートされていません。

レシピ

チャート	ファイル
データなしのリクエスト向けスキルデモ	HTML · React
棒、グループ化、積み上げ、割合、横向き	bar
折れ線、複数グループ、スムーズ、欠損、日付	line
面、積み上げ、割合	area
円、ドーナツ	pie
散布図、バブル	scatter
ヒートマップ	heatmap
複合、棒と折れ線、第二軸	combo
レーダー	radar
極座標棒グラフ	polar-bar
箱ひげ図	boxplot
ローソク足	candlestick
ダンベル	dumbbell
エラーバー、信頼区間	error-bar
ファネル	funnel
ロリポップ	lollipop
メッコ、マリメッコ	mekko
サンキー	sankey
ウォーターフォール	waterfall

9つのジオムレシピは公開パッケージをインストールします。それぞれが完全なコンポーネントです。プラグインはrecipes/pluginsに1ファイルずつあり、小さな例から完全なレイアウトまで揃っています。

注意点

• ラベルではなく、列のkeyをマッピングしてください。
• 円グラフ用のジオムはありません。円グラフとドーナツグラフは極座標棒グラフです。
• createGraphyKit({ theme })またはプロバイダーのthemeプロパティにテーマを渡してください。テーマはスペックの外側に置きます。
• pluginsとthemeはマウント時に一度だけ読み込まれます。どちらかを変更するには、新しいkeyを指定してプロバイダーを再マウントしてください。
• 列でdateFormatを設定していない場合、日付文字列は日を先にして読み込まれます。
• スペックは一度だけ作成するか、メモ化してください。新しいスペックオブジェクトを渡すとチャートが再コンパイルされ、取り消し履歴がクリアされます。
• 親の高さが指定されていないレスポンシブチャートの高さは0ピクセルになります。
• スペックでconfig.content.brandMark.enabledを設定しない場合、@graphysdk/reactにはブランドマークが表示されます。
• jsDelivrのインポートマップなしで@graphysdk/reactをインポートするHTMLアーティファクトは読み込まれません。セットアップのCDNページを使用してください。パネルが空白のままの場合、ホストがCDNをブロックしている可能性があります。その場合は、同ページのオフラインでのベンダー導入手順を使用してください。
• esm.shからReactやGraphyを読み込まないでください。jsDelivrのみを使用してください。
• @graphysdk/react@1はjsDelivrで404になります。セットアップに記載されたGraphyのURLをそのまま使用してください。
• 点またはバブルにマッピングしたsizeとlabelは、デフォルトのツールチップには表示されません。見出しはx、行には色とyが表示されます。レイヤーのtooltipオプションで行を追加してください。例：geom.point({ tooltip: { size: { title: 'Population' } } })。カスタムのTooltipスロットを使うと、全体が置き換えられます。
• Waterfall、funnel、boxplot、candlestick、dumbbell、error-bar、lollipop、mekko、sankeyはパッケージです。@graphysdk/geom-<name>をインストールしてください。これらのためのプラグインを書かないでください。
• ここでは表はチャートの種類ではありません。その旨を伝えて終了してください。表用のプラグインを書かないでください。

spec の検証

validate-spec.mjs は、ブラウザーを使わずにデータに対して spec をコンパイルし、エラーと警告を出力します。spec の作成や変更、プラグインの作成、サンプルデータの置き換え、原因不明の失敗の調査を行うときや、ユーザーから検証を求められたときに使用してください。変更していないデモやレシピを元のデータで通常どおりコンパイルする必要はありません。独自のコンパイルループを書く代わりに、このスクリプトを使用してください。npm が使えないホストでは、レンダリングされたページを確認してください。

このスクリプトは、実行元のフォルダーから @graphysdk/viz-engine を解決します。@graphysdk/viz-engine が直接の依存関係である場合は、プロジェクトのルートから実行してください。pnpm は @graphysdk/react から依存関係をホイストしません。それ以外の場合は、ページのインポートマップまたはインストール済みの @graphysdk/react/package.json に記載された正確なバージョンで、スクラッチフォルダーにインストールしてください。2つのパッケージのバージョンは常に同じです。

mkdir graphy-check && cd graphy-check
npm init -y
npm install @graphysdk/viz-engine@<exact-version>
node <skill-path>/scripts/validate-spec.mjs <path-to-my-spec.mjs>

各モジュールは data と spec をエクスポートし、必要に応じて plugins と colorScheme もエクスポートします。ビルダーは @graphysdk/react または @graphysdk/viz-engine からインポートしてください。このスクリプトは React のインポートをエンジンにリダイレクトします。チャートごとに1つのモジュールを使用してください。