@squadbase/vantage 0.7.0 → 0.7.1-dev1.0d13f9a

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"
@@ -176,6 +197,8 @@ export interface PageShellHeaderProps extends HTMLAttributes<HTMLDivElement> {
 }
 
 /**
+ * PageShellHeader — the page header band (title and update time, source / period, overall status); inside `PageShell` without `title`, with the title in `PageShellHeading`.
+ *
  * A wrapping flex row, not a two-column grid: when the heading cannot keep its
  * 20rem basis next to `PageShellHeaderEnd`, the end block drops below it. A
  * `1fr auto` grid would instead hand the heading whatever the end block leaves,

package/registry/ui/paired-chart.tsx

@@ -3,7 +3,7 @@
 "use client"
 
 /**
- * PairedChart — 量(棒)と率・単価(線)を、同じ期間軸の上下 2 段で見せる型付きグラフ。
+ * PairedChart — 量(棒)と率・単価(線)を、同じ期間軸の上下 2 段で見せる型付きグラフ（`DashboardCardPreset` の中に置く）。
  * 二重 Y 軸は持たない: 上段が棒の値軸、下段が線の値軸で、横軸(期間)とツールチップの位置は
  * 1 つの ECharts の中で揃っている(ホバーすると同じ期間の棒と線の値が 1 枚のツールチップに出る)。
  * 段ごとに `format`(件数・金額・%)を持ち、率を分子・分母から計算することはしない(呼び元が値を渡す)。
@@ -171,10 +171,25 @@ function useLocale(locale?: string | null): string {
 const CHART_OTHER_COLOR = "color-mix(in oklab, var(--neutral) 50%, var(--background))"
 
 /**
- * True inside `ChartFrame`. The frame's plot area carries the chart's single
- * `role="img"` and label, so `EChart` drops its own when it sees this.
+ * What a `ChartFrame` tells the plot inside it. A frame whose plot is an image
+ * (`image`) puts `role="img"` on its plot area, unless an `EChart` inside it
+ * `claim`s the image: then the canvas alone carries `role="img"` with this name
+ * and description (`claimed`), so the action buttons beside the canvas are not
+ * inside the image (an interactive control inside `role="img"` is a
+ * nested-interactive violation and is not exposed). A `group` frame never
+ * hands the role to the canvas. `false` outside a frame.
  */
-const ChartFrameContext = createContext(false)
+interface ChartFramePlot {
+  image: boolean
+  /** An `EChart` inside has taken over the `role="img"`. */
+  claimed: boolean
+  /** Take over the image role; returns the release. */
+  claim: () => () => void
+  ariaLabel?: string
+  ariaLabelledBy?: string
+  ariaDescribedBy?: string
+}
+const ChartFrameContext = createContext<ChartFramePlot | false>(false)
 
 /** Series palette, in order. Missing tokens are skipped, not defaulted. */
 const SERIES_TOKENS = ["--chart-1", "--chart-2", "--chart-3", "--chart-4", "--chart-5"] as const
@@ -398,6 +413,8 @@ function buildChartTheme(tokens: ChartTokens): Record<string, unknown> {
     tooltip: {
       // ECharts' default 0.4s transform lags the tooltip ~300ms behind the cursor.
       transitionDuration: 0,
+      // Stay inside the chart: cards are often narrow and overflow-hidden.
+      confine: true,
       backgroundColor: tokens.popover ?? undefined,
       borderColor: line,
       borderWidth: 1,
@@ -2273,6 +2290,10 @@ function legendLines(items: readonly string[], plotWidth?: number, reserve = 0):
 
 /** Width (px) kept free at the legend's right for the PNG action buttons (two 32px buttons + gaps). */
 const ACTIONS_RESERVE = 80
+/** Bars stay slim on wide cards (px); stacked segments round all corners and are parted by a hairline of the surface colour (px). */
+const BAR_MAX_WIDTH = 40
+const BAR_RADIUS = 3
+const STACK_GAP = 1.5
 
 /** Room (px) one time label (`2026年1月`) needs, gap included. */
 const TIME_LABEL_WIDTH = 80
@@ -2486,6 +2507,8 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
     const compared = cartesianSeriesValues(data, [categories[compIdx]!], "default")[0]!
     return categories.map((_, i) => (i === compIdx ? compared : main[mainIdx.indexOf(i)]!))
   })()
+  // Any negative bar: the part lays out the diverging view itself (a solid zero line, category labels kept at the axis end).
+  const diverging = kind === "bar" && values.some((s) => s.some((v) => typeof v === "number" && v < 0))
   const comparisonColor = guideColor ? withAlpha(guideColor, COMPARISON_OPACITY) : undefined
 
   /* -- x labels: the actual rows, then the forecast rows that extend them */
@@ -2695,15 +2718,17 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
     const seriesData = pad(values[c]!)
     if (kind === "bar") {
       const rounded = horizontalBars ? [0, 4, 4, 0] : [4, 4, 0, 0]
-      // Stacked: only the topmost segment is rounded.
-      const radius = stacked && c !== categories.length - 1 ? 0 : rounded
+      // Stacked: every segment is rounded, with a hairline of the surface colour between segments (the gap).
+      const radius = stacked ? BAR_RADIUS : rounded
+      const gapStyle = stacked && labelBackground ? { borderColor: labelBackground, borderWidth: STACK_GAP } : {}
       return {
         id: SERIES_ID_PREFIX + category,
         type: "bar" as const,
         name: category,
         stack: stacked ? "total" : undefined,
         barCategoryGap,
-        itemStyle: { color, borderRadius: radius },
+        barMaxWidth: BAR_MAX_WIDTH,
+        itemStyle: { color, borderRadius: radius, ...gapStyle },
         markPoint: markPointFor(c, solid),
         markLine: undefined,
         data: seriesData.map((value, i) => {
@@ -2999,6 +3024,14 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
       },
     })
   }
+  if (diverging) {
+    markLines.push({
+      name: "zero",
+      [horizontalBars ? "xAxis" : "yAxis"]: 0,
+      lineStyle: { type: "solid", width: 1, color: guideColor },
+      label: { show: false },
+    })
+  }
   if (forecast) {
     const forecastSpan =
       plotWidth && labels.length > 1
@@ -3144,6 +3177,8 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
     show: horizontalBars ? showYAxis : showXAxis,
     boundaryGap: kind === "bar",
     inverse: horizontalBars,
+    // Diverging: the axis stays at the plot's edge (not at 0, where labels would hit the negative bars); the zero line is a mark line.
+    axisLine: diverging ? { show: false, onZero: false } : undefined,
     axisTick: { show: false },
     axisLabel: {
       hideOverlap: true,
@@ -3246,7 +3281,7 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
       // Narrow: left-aligned and wrapping above the plot, so nothing is cut off at the right edge.
       ...(plotWidth !== undefined && plotWidth < NARROW_PLOT_WIDTH
         ? { left: 0, right: 0 }
-        : { right: reserveActions ? ACTIONS_RESERVE : 0 }),
+        : { left: 0, right: reserveActions ? ACTIONS_RESERVE : 0 }),
       // Plain wraps onto a second line at narrow widths instead of hiding items behind arrows.
       type: "plain",
       icon: "circle",
@@ -3939,7 +3974,7 @@ export function buildPairedOption(cfg: PairedOptionConfig): EChartsOption {
 
   const option: AnyRecord = {
     ...barOpt,
-    legend: { ...barOpt.legend, show: showLegend, data: legendNames, right: cfg.reserveActions ? 80 : 0 },
+    legend: { ...barOpt.legend, show: showLegend, data: legendNames, left: 0, right: cfg.reserveActions ? 80 : 0 },
     grid: [
       { top, height: upper, left: gridLeft, right, containLabel: true },
       { top: top + upper + PANEL_GAP, bottom: 4, left: gridLeft, right, containLabel: true },