@squadbase/vantage 0.7.0 → 0.7.1-dev1.01a6413

package/registry/ui/funnel-steps.tsx

@@ -3,7 +3,7 @@
 "use client"
 
 /**
- * FunnelSteps — proportional bars for a conversion funnel. Bars are sized
+ * FunnelSteps — proportional bars for a conversion funnel; put no parts inside it. Bars are sized
  * against the first step, so pass the steps in descending order. Set
  * `showConversion` to print the step-to-step rate between them; the lowest
  * rate is then the only one emphasised (in the `--negative` colour). Pass

package/registry/ui/kpi-card.tsx

@@ -3,7 +3,9 @@
 "use client"
 
 /**
- * KpiCard — one metric in five tiers, following shadcn dashboard-01 SectionCards:
+ * KpiCard — one metric as a card of its own (label, value, delta, target, history), so do not put it in `DashboardCardPreset`.
+ *
+ * Five tiers, following shadcn dashboard-01 SectionCards:
  *
  *   1. label            (CardDescription, muted)
  *   2. value            (CardTitle, tabular-nums; text-4xl once the card is ≥ 320px wide (a comparison label is ~180px, so narrower cards would overlap the value))

package/registry/ui/metric-value.tsx

@@ -3,8 +3,8 @@
 "use client"
 
 /**
- * MetricValue / MetricUnit — the large number in a dashboard tile and its
- * trailing unit, sized as a pair so the unit stays subordinate at every size.
+ * MetricValue — the large number in a dashboard tile (with `MetricUnit`, its
+ * trailing unit, sized as a pair so the unit stays subordinate at every size).
  *
  * @deprecated KPI の数字は KpiCard を使う。KpiCard は書式（`format`、単位は
  * `{ type: "number", unit: "社" }`）・比較ラベル・増減を値から計算するので、

package/registry/ui/page-shell.tsx

@@ -3,7 +3,9 @@
 "use client"
 
 /**
- * PageShell — the standard page frame: a bordered header band (title,
+ * PageShell — the outermost frame of a page; every other part goes inside it.
+ *
+ * It is the standard page frame: a bordered header band (title,
  * description, meta, actions), an optional summary card row, and the content
  * area. Composed from parts so a page can use only what it needs.
  */
@@ -149,11 +151,30 @@ function useLocale(locale?: string | null): string {
 
 /* ---------- end of inlined code ---------- */
 
-export interface PageShellProps extends HTMLAttributes<HTMLDivElement> {}
+export interface PageShellProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+  /** The page heading. When given, the header (title and `description`) and the content area are drawn for you; `children` go in the content area. */
+  title?: string
+  /** One line under the title. Used only with `title`. */
+  description?: string
+}
 
 export const PageShell = forwardRef<HTMLDivElement, PageShellProps>(
-  ({ className, ...props }, ref) => (
-    <div ref={ref} data-slot="page-shell" className={cn("flex flex-col", className)} {...props} />
+  ({ className, title, description, children, ...props }, ref) => (
+    <div ref={ref} data-slot="page-shell" className={cn("flex flex-col", className)} {...props}>
+      {title === undefined ? (
+        children
+      ) : (
+        <>
+          <PageShellHeader>
+            <PageShellHeading>
+              <PageShellTitle>{title}</PageShellTitle>
+              {description ? <PageShellDescription>{description}</PageShellDescription> : null}
+            </PageShellHeading>
+          </PageShellHeader>
+          <PageShellContent>{children}</PageShellContent>
+        </>
+      )}
+    </div>
   ),
 )
 PageShell.displayName = "PageShell"

package/registry/ui/paired-chart.tsx

@@ -3,7 +3,7 @@
 "use client"
 
 /**
- * PairedChart — 量(棒)と率・単価(線)を、同じ期間軸の上下 2 段で見せる型付きグラフ。
+ * PairedChart — 量(棒)と率・単価(線)を、同じ期間軸の上下 2 段で見せる型付きグラフ（`DashboardCardPreset` の中に置く）。
  * 二重 Y 軸は持たない: 上段が棒の値軸、下段が線の値軸で、横軸(期間)とツールチップの位置は
  * 1 つの ECharts の中で揃っている(ホバーすると同じ期間の棒と線の値が 1 枚のツールチップに出る)。
  * 段ごとに `format`(件数・金額・%)を持ち、率を分子・分母から計算することはしない(呼び元が値を渡す)。