@squadbase/vantage 0.7.1-dev1.01a6413 → 0.7.1-dev1.0d13f9a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squadbase/vantage",
-  "version": "0.7.1-dev1.01a6413",
+  "version": "0.7.1-dev1.0d13f9a",
   "description": "Data dashboard framework for Squadbase Editor. Vite-powered, config-free, one-file first.",
   "type": "module",
   "license": "MIT",
@@ -152,7 +152,7 @@
     "vitest": "^5.0.5",
     "@squadbase/squadkit": "0.0.0"
   },
-  "gitHead": "01a6413cae8e306d317219583aeca54b09ff1576",
+  "gitHead": "0d13f9a25b7bd5007320dfadec959dc531180e2d",
   "scripts": {
     "build": "node scripts/build-docs.mjs && node scripts/build.mjs",
     "build:js": "tsup --no-dts",

package/registry/parts.json

@@ -2130,10 +2130,10 @@
         },
         {
           "name": "color",
-          "type": "string | undefined",
+          "type": "ChartColor | undefined",
           "required": false,
           "json": true,
-          "doc": "Tailwind text-colour class; drives both stroke and fill via `currentColor`."
+          "doc": "Line / bar colour: a theme series token (`\"chart-1\"`〜`\"chart-5\"`), a meaning colour (`\"positive\"` / `\"negative\"` / `\"warning\"` / `\"neutral\"` / `\"info\"`), or any CSS colour (`\"#16a34a\"`, `\"var(--destr…"
         },
         {
           "name": "area",
@@ -4830,6 +4830,17 @@
           "json": true,
           "doc": "年度の開始月（1-12）。"
         },
+        {
+          "name": "comparison",
+          "type": "\"previous-period\" | \"previous-year\" | undefined",
+          "required": false,
+          "json": true,
+          "values": [
+            "previous-period",
+            "previous-year"
+          ],
+          "doc": "比較期間。"
+        },
         {
           "name": "maxDate",
           "type": "Date | undefined",
@@ -5134,6 +5145,13 @@
           "required": false,
           "json": true
         },
+        {
+          "name": "headline",
+          "type": "ReactNode",
+          "required": false,
+          "json": true,
+          "doc": "One headline number or status at the right end of the header (\"212 tasks\", a `StatusBadge`)."
+        },
         {
           "name": "actions",
           "type": "ReactNode",
@@ -5144,7 +5162,8 @@
           "name": "footer",
           "type": "ReactNode",
           "required": false,
-          "json": true
+          "json": true,
+          "doc": "One line at the bottom of the card: a summary fact on the left, an action or hint on the right."
         },
         {
           "name": "headerClassName",
@@ -5216,6 +5235,85 @@
           "json": true
         }
       ]
+    },
+    {
+      "name": "PageShellHeader",
+      "module": "components/page-shell",
+      "doc": "PageShellHeader — the page header band (title and update time, source / period, overall status); inside `PageShell` without `title`, with the title in `PageShellHeading`.",
+      "props": [
+        {
+          "name": "updatedAt",
+          "type": "string | number | Date | undefined",
+          "required": false,
+          "json": true,
+          "doc": "When the data was last updated."
+        },
+        {
+          "name": "updatedAtVariant",
+          "type": "\"relative\" | \"absolute-first\" | undefined",
+          "required": false,
+          "json": true,
+          "values": [
+            "relative",
+            "absolute-first"
+          ],
+          "doc": "`\"relative\"` (default) or `\"absolute-first\"` (\"16:41 更新（23 分前）\") for pages where \"now\" matters."
+        },
+        {
+          "name": "timeZone",
+          "type": "string | undefined",
+          "required": false,
+          "json": true,
+          "doc": "IANA time zone for the absolute time of `updatedAt`."
+        },
+        {
+          "name": "source",
+          "type": "string | undefined",
+          "required": false,
+          "json": true,
+          "doc": "Where the data comes from."
+        },
+        {
+          "name": "period",
+          "type": "{ start: string | number | Date; end: string | number | Date; } | undefined",
+          "required": false,
+          "json": true,
+          "doc": "The period the data covers."
+        },
+        {
+          "name": "status",
+          "type": "ReactNode",
+          "required": false,
+          "json": true,
+          "doc": "The page's overall state (an alert, a status badge)."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "json": true
+        }
+      ]
+    },
+    {
+      "name": "SampleData",
+      "module": "components/sample-data",
+      "doc": "SampleData — marks the values inside it as a sample: they are not connected to real data yet (a draft laid out before its queries are wired, a screen built from column definitions only).",
+      "props": [
+        {
+          "name": "label",
+          "type": "string | undefined",
+          "required": false,
+          "json": true,
+          "doc": "印の文言。"
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "json": true
+        }
+      ]
     }
   ]
 }

package/registry/ui/area-chart.tsx

@@ -170,10 +170,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.
- */
-const ChartFrameContext = createContext(false)
+ * 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.
+ */
+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
@@ -397,6 +412,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,
@@ -2272,6 +2289,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
@@ -2485,6 +2506,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 */
@@ -2694,15 +2717,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) => {
@@ -2998,6 +3023,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
@@ -3143,6 +3176,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,
@@ -3245,7 +3280,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",

package/registry/ui/bar-chart.tsx

@@ -7,7 +7,7 @@
  * (`index`) and the series keys (`categories`) instead of an ECharts option.
  * Grouped, stacked or 100%-stacked; vertical or horizontal bars. Colours are the
  * `--chart-1..5` tokens in fixed order (more than 5 series fold into「その他」)
- * and follow light/dark. The value axis always starts at 0. A horizontal bar chart of one
+ * and follow light/dark. The value axis always reaches 0 (negative values add a solid zero line on their own). A horizontal bar chart of one
  * series (`barOptions.layout: "vertical"`) is a light tint by default, like BarList; `barOptions.highlight`
  * names the one bar the page is about, drawn in the full colour.
  * Renders inside `ChartFrame` (title, summary, loading skeleton, empty state).
@@ -173,10 +173,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
@@ -400,6 +415,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,
@@ -2275,6 +2292,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
@@ -2488,6 +2509,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 */
@@ -2697,15 +2720,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) => {
@@ -3001,6 +3026,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
@@ -3146,6 +3179,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,
@@ -3248,7 +3283,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",

package/registry/ui/bar-list.tsx

@@ -186,10 +186,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.
- */
-const ChartFrameContext = createContext(false)
+ * 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.
+ */
+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
@@ -413,6 +428,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,
@@ -2288,6 +2305,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
@@ -2501,6 +2522,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 */
@@ -2710,15 +2733,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) => {
@@ -3014,6 +3039,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
@@ -3159,6 +3192,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,
@@ -3261,7 +3296,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",

package/registry/ui/box-plot-chart.tsx

@@ -174,10 +174,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
@@ -401,6 +416,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,
@@ -1437,6 +1454,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
@@ -1650,6 +1671,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 */
@@ -1859,15 +1882,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) => {
@@ -2163,6 +2188,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
@@ -2308,6 +2341,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,
@@ -2410,7 +2445,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",