basalt-ui 1.30.1 → 1.31.0

package/src/charts/primitives/ChartCard.tsx

@@ -12,15 +12,43 @@
  * The header renders only when at least one of title/info/value/actions/icon/count is set — ending
  * the `''`-as-hidden-header sentinel a consumer used to reach for otherwise.
  */
+import { useCallback, useMemo, useRef, useState } from 'react'
 import type { CSSProperties, ReactNode } from 'react'
 import { cx } from '../../common/props'
 import type { BasaltProps, SlotStylesProps } from '../../common/props'
 import { VX } from '../../tokens'
 import { WidgetHeader } from '../../dashboard/widget-header'
 import type { DeltaPolarity } from '../../dashboard/delta-badge'
+import { useChartSize } from '../hooks/useChartSize'
+import { useHysteresis } from '../hooks/use-hysteresis'
+import { ChartCardContext } from './chart-card-context'
 import { ChartEmpty, ChartError, ChartPending, resolveChartState } from './ChartPending'
 import type { ChartState } from './ChartPending'
 
+/**
+ * Below this rendered height the header folds its subtitle regardless of width (wave 8's
+ * header-economy law, `docs/CHARTS-SPEC.md` §5) — a short-but-wide card (a KPI-style
+ * chart card) still needs the vertical space back. A `@container basalt-card` SIZE query would be
+ * the natural expression, but `container-type: size` on a box with no explicit height (the common,
+ * non-grid-stretched case) collapses it to 0 — CSS containment requires a definite size in the
+ * contained axis, and a ChartCard's height is ordinarily derived from its content (VERIFIED: making
+ * the root a size container drops `card-chrome.layout.test.ts`'s unstretched short-card fixture to
+ * a 0px box). `useChartSize` (the same measuring primitive `ChartFrame` uses) reads the rendered
+ * height instead, and `data-basalt-card-short` is the CSS hook `widget-header.module.css` reacts to
+ * with the same subtitle-fold declarations as the width query.
+ */
+const CARD_SHORT_HEIGHT = 280
+/**
+ * Hysteresis band on the flag above (`docs/waves/PLAN.md` wave 3, P0-1). `short` folds the header,
+ * which changes the card's OWN measured height by the fold delta — a card whose unfolded height
+ * lands in `[280, 280 + Δ)` is bistable, and the async RO → rAF → debounce → setState → commit path
+ * can sit one reading behind, which turned the bistability into a perpetual flip-flop on the
+ * "Sales by channel" dashboard card (27-52 times per 2s, every viewport). Entering short still
+ * happens below `CARD_SHORT_HEIGHT`; LEAVING it needs `CARD_SHORT_HEIGHT + SHORT_EXIT_SLACK`, sized
+ * to clear the largest fold delta (subtitle line + inset + value row) with headroom.
+ */
+const SHORT_EXIT_SLACK = 24
+
 // Surfaces resolve per theme via CSS vars, so the styles are static (no useMemo/isDark).
 // Depth = `shadow-card` (a whisper shadow + a 1px ring baked into the same value), never a
 // `border` property (docs/DESIGN-SPEC.md §5) — so a ChartCard reads IDENTICALLY to a Mantine
@@ -31,7 +59,16 @@ import type { ChartState } from './ChartPending'
 // `WidgetHeader`'s info bubble (`widget-header.module.css`'s `.infoBubble`, which is where the
 // tooltip this file used to own now lives) opens downward past the header's own box, and must be
 // able to overhang the card edge without being invisibly cut off.
+//
+// The root is a flex column and a `basalt-card` inline-size container (the card's own width drives
+// its header chrome, `docs/CHARTS-SPEC.md` §8): the body takes the row's spare height when a grid stretches
+// the card.
 const cardStyle: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  minHeight: 0,
+  containerType: 'inline-size',
+  containerName: 'basalt-card',
   borderRadius: VX.radiusCard,
   boxShadow: VX.shadowCard,
   backgroundColor: VX.surface.panel,
@@ -45,6 +82,11 @@ const bodyClipStyle: CSSProperties = {
   borderBottomLeftRadius: VX.radiusCard,
   borderBottomRightRadius: VX.radiusCard,
   overflow: 'hidden',
+  flex: '1 1 auto',
+  minHeight: 0,
+  // A column, so a `ChartFrame` inside can grow into the body a stretched grid row hands the card.
+  display: 'flex',
+  flexDirection: 'column',
   padding: '2px var(--vx-space-card-inset-x, 0.8125rem) var(--vx-space-card-inset-y, 0.6875rem)',
 }
 // Card inset = the `cardInsetY`/`cardInsetX` role tokens (vertical / horizontal), the SAME two
@@ -60,6 +102,13 @@ const bodyClipStyle: CSSProperties = {
 const headerWrapStyle: CSSProperties = {
   padding: 'var(--vx-space-card-inset-y, 0.6875rem) var(--vx-space-card-inset-x, 0.8125rem) 4px',
 }
+// A short card (wave 8) trims the header's own top inset — the subtitle line and the wide-tier
+// value/delta row are both already gone by the time `short` is true, so the full card inset reads
+// as dead air rather than rhythm. Bottom stays 4px (unchanged) so the header-to-body seam matches
+// every other ChartCard.
+const headerWrapShortStyle: CSSProperties = {
+  padding: '4px var(--vx-space-card-inset-x, 0.8125rem) 4px',
+}
 
 /**
  * The three boxes a `ChartCard` paints, and therefore the slot set a consumer may class
@@ -143,6 +192,8 @@ export function ChartCard({
   style,
   children,
 }: ChartCardProps) {
+  const [legendSlot, setLegendSlot] = useState<HTMLDivElement | null>(null)
+  const { ref: sizeRef, height: measuredHeight } = useChartSize()
   const resolvedState = resolveChartState({ ...(state !== undefined && { state }) })
   const hasHeader =
     title !== undefined ||
@@ -151,59 +202,101 @@ export function ChartCard({
     actions !== undefined ||
     icon !== undefined ||
     count !== undefined
+  // Hysteresis (P0-1, `SHORT_EXIT_SLACK`'s own doc): which threshold applies depends on the
+  // PREVIOUS committed flag, so a card whose unfolded height sits in the bistable band settles
+  // instead of flip-flopping forever.
+  const short = useHysteresis(
+    (wasShort) =>
+      measuredHeight > 0 &&
+      measuredHeight < (wasShort ? CARD_SHORT_HEIGHT + SHORT_EXIT_SLACK : CARD_SHORT_HEIGHT),
+    false,
+  )
+
+  const legendOwnerRef = useRef<string | null>(null)
+  // Bumped on every release so a previously-denied sibling's claim effect (keyed on the context
+  // value it reads, see `chart-card-context.ts`) re-runs and gets a chance to re-claim the slot the
+  // owner just gave up — without it a frame told "no" once stayed denied even after the owner
+  // unmounted.
+  const [legendSlotVersion, setLegendSlotVersion] = useState(0)
+  const claimLegendSlot = useCallback((id: string) => {
+    if (legendOwnerRef.current === null) legendOwnerRef.current = id
+    return legendOwnerRef.current === id
+  }, [])
+  const releaseLegendSlot = useCallback((id: string) => {
+    if (legendOwnerRef.current === id) {
+      legendOwnerRef.current = null
+      setLegendSlotVersion((v) => v + 1)
+    }
+  }, [])
+  const context = useMemo(
+    () => ({
+      legendSlot,
+      inCard: true,
+      short,
+      claimLegendSlot,
+      releaseLegendSlot,
+      legendSlotVersion,
+    }),
+    [legendSlot, short, claimLegendSlot, releaseLegendSlot, legendSlotVersion],
+  )
 
   return (
-    <div
-      className={cx(classNames?.root, className)}
-      style={{ ...cardStyle, ...style }}
-      {...(resolvedState === 'pending' && { 'aria-busy': 'true' })}
-    >
-      {hasHeader && (
-        <div
-          {...(classNames?.header !== undefined && { className: classNames.header })}
-          style={headerWrapStyle}
-        >
-          <WidgetHeader
-            tier="widget"
-            title={title ?? ''}
-            {...(icon !== undefined && { icon })}
-            {...(subtitle !== undefined && { subtitle })}
-            {...(info !== undefined && { info })}
-            {...(value !== undefined && { value })}
-            {...(delta !== undefined && { delta })}
-            {...(deltaPeriod !== undefined && { deltaPeriod })}
-            {...(deltaPolarity !== undefined && { deltaPolarity })}
-            {...(count !== undefined && { count })}
-            {...(actions !== undefined && {
-              actions: <span data-basalt-tier="widget">{actions}</span>,
-            })}
-          />
-        </div>
-      )}
+    <ChartCardContext.Provider value={context}>
       <div
-        {...(classNames?.body !== undefined && { className: classNames.body })}
-        style={bodyClipStyle}
+        ref={sizeRef}
+        className={cx(classNames?.root, className)}
+        style={{ ...cardStyle, ...style }}
+        {...(resolvedState === 'pending' && { 'aria-busy': 'true' })}
+        {...(short && { 'data-basalt-card-short': '' })}
       >
-        {resolvedState === 'pending' ? (
-          <ChartPending width="100%" height={placeholderHeight} />
-        ) : resolvedState === 'error' ? (
-          <ChartError
-            width="100%"
-            height={placeholderHeight}
-            error={state?.error}
-            action={stateAction}
-          />
-        ) : resolvedState === 'empty' ? (
-          <ChartEmpty
-            width="100%"
-            height={placeholderHeight}
-            {...(typeof state?.empty === 'string' && { label: state.empty })}
-            action={stateAction}
-          />
-        ) : (
-          children
+        {hasHeader && (
+          <div
+            {...(classNames?.header !== undefined && { className: classNames.header })}
+            style={short ? headerWrapShortStyle : headerWrapStyle}
+          >
+            <WidgetHeader
+              tier="widget"
+              title={title ?? ''}
+              {...(icon !== undefined && { icon })}
+              {...(subtitle !== undefined && { subtitle })}
+              {...(info !== undefined && { info })}
+              {...(value !== undefined && { value })}
+              {...(delta !== undefined && { delta })}
+              {...(deltaPeriod !== undefined && { deltaPeriod })}
+              {...(deltaPolarity !== undefined && { deltaPolarity })}
+              {...(count !== undefined && { count })}
+              {...(actions !== undefined && {
+                actions: <span data-basalt-tier="widget">{actions}</span>,
+              })}
+            />
+            <div ref={setLegendSlot} data-basalt-legend-slot="" />
+          </div>
         )}
+        <div
+          {...(classNames?.body !== undefined && { className: classNames.body })}
+          style={bodyClipStyle}
+        >
+          {resolvedState === 'pending' ? (
+            <ChartPending width="100%" height={placeholderHeight} />
+          ) : resolvedState === 'error' ? (
+            <ChartError
+              width="100%"
+              height={placeholderHeight}
+              error={state?.error}
+              action={stateAction}
+            />
+          ) : resolvedState === 'empty' ? (
+            <ChartEmpty
+              width="100%"
+              height={placeholderHeight}
+              {...(typeof state?.empty === 'string' && { label: state.empty })}
+              action={stateAction}
+            />
+          ) : (
+            children
+          )}
+        </div>
       </div>
-    </div>
+    </ChartCardContext.Provider>
   )
 }