basalt-ui 1.41.0 → 2.0.0

package/src/charts/primitives/ChartCard.tsx

@@ -1,280 +0,0 @@
-/**
- * Standard wrapper for every visx chart (docs/CONTROLS-SPEC.md §2.2) — card with a `WidgetHeader
- * tier="widget"` title row (icon/info/value/delta/count/actions) plus an optional subtitle, over a
- * clipped chart body. Do not wrap visx charts in bare divs.
- *
- * `WidgetHeader` lives in `src/dashboard/` and is itself Mantine-free, so composing it here
- * keeps `./charts` resolving with no `@mantine/*` installed (`check-dist-layering.mjs`,
- * `basalt/token-layer-boundary`). The `actions` slot cannot mount `CtlSlot` (Mantine-coupled) for
- * the same reason — it carries only `data-basalt-tier="widget"`; a basalt control placed there
- * sizes itself (`size="ctl"` internally), and a raw Mantine element is not auto-tiered.
- *
- * 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 { useMemo, useReducer, 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, legendSlotReducer } 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
-// Card/Paper (same shadow token, same radius token, no intrinsic margin; outer spacing comes
-// from the parent Stack/SimpleGrid gap). Shadow + panel background + card radius all live on
-// this OUTER box, which is never clipped — only the chart body below clips its own bottom
-// corners (`bodyClipStyle`). The header is a direct, unclipped child of this box on purpose:
-// `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,
-}
-const bodyClipStyle: CSSProperties = {
-  // Clip the chart body to the card's bottom corners — a chart with its own square edges would
-  // otherwise poke past the card's border-radius. Only the bottom corners: the body's top edge is
-  // interior, sitting under the (unclipped) header. Trade-off: a chart tooltip that overflows the
-  // card bounds is clipped too; the kinds keep tooltips inside the plot area, so this is fine in
-  // practice — a consumer rendering an oversized/edge tooltip should portal it out of the card.
-  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
-// vars `StatCard` reads — a ChartCard and a StatCard in one grid row must not disagree about their
-// inset, which is why the pair is one named role rather than two files each spelling `xs`/`sm`.
-// They used to read `--mantine-spacing-xs`/`-sm`; the `--vx-*` pair carries the same numbers off
-// the same owned scale, is emitted by the same stylesheet at a retuned density, and — unlike the
-// Mantine vars — steps a rung down below `sm` (the mobile inset ladder, `spaceMobileDecls` in
-// `tokens/index.ts`). The rem fallbacks are unchanged and keep a `./charts`-only consumer with
-// neither MantineProvider nor BasaltProvider padded identically. No header/body divider — the
-// title block and the plot read as one continuous surface; a rule here only doubled the card's
-// shadow-embedded ring and made the header feel heavier.
-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
- * (`SlotStylesProps`). `root` is the card itself (shadow, radius, panel background), `header` the
- * unclipped title band, `body` the clipped chart well. There is deliberately no slot for
- * `WidgetHeader`'s own internals — that component owns its own contract.
- */
-export type ChartCardSlot = 'root' | 'header' | 'body'
-
-/**
- * The props below are a HAND-CUT subset of `WidgetHeaderProps`, and that is the open half of audit
- * B #2: `widget-header` now publishes named slices (`WidgetHeaderTitleProps`,
- * `WidgetHeaderMetricProps`, `WidgetHeaderDeltaProps`) precisely so a composer's omissions are
- * declared rather than accidental, and `StatCard`/`SettingsSection` already compose them.
- *
- * `ChartCard` cannot yet: it lives inside the Mantine-free `charts/` boundary, and every prop here
- * is spelled out so a `./charts`-only consumer reads the whole contract without following a type
- * into another module. What that costs is visible in the omissions — no `unit`, no `deltaFormat`,
- * no `deltaGlyph`, no `sparkline` — so a KPI moved from a `StatCard` into a `ChartCard` loses them
- * silently. Compose the slices here next time this file is open; the ledger of which composer takes
- * which is `docs/CONTROLS-SPEC.md` §2.2.
- */
-export type ChartCardProps = BasaltProps &
-  SlotStylesProps<ChartCardSlot> & {
-    /** Optional — the header renders only when this or one of info/value/actions/icon/count is set. */
-    title?: string
-    /** Optional leading icon, forwarded to `WidgetHeader`. */
-    icon?: ReactNode
-    /** Optional muted line rendered below the title row — does NOT by itself trigger the header. */
-    subtitle?: string
-    /** Renders `WidgetHeader`'s info glyph beside the title — a `More information` button whose
-     * bubble opens on hover, focus and click. Never part of the heading's accessible name. */
-    info?: string
-    /** Pre-formatted metric value, on the hero-metric row with `delta`. */
-    value?: string
-    /** Signed delta rendered via `DeltaBadge`, alongside `value`. */
-    delta?: number
-    /** Comparison timeframe forwarded to `DeltaBadge` (e.g. `MoM`). */
-    deltaPeriod?: string
-    /** Which sign reads as the good verdict on the delta chip — forwarded to `DeltaBadge`'s
-     * `polarity`. Defaults to `'up-good'` (today's behaviour). */
-    deltaPolarity?: DeltaPolarity
-    /** Mono count tag after the title. */
-    count?: number
-    /** Right-aligned slot — carries `data-basalt-tier="widget"` (no `CtlSlot`; see module doc). */
-    actions?: ReactNode
-    /**
-     * Any resolved state (pending → error → empty, same precedence `resolveChartState` gives
-     * every chart kind) REPLACES `children` with its placeholder at `placeholderHeight` — the
-     * header still renders unchanged, so a card's title never reflows through the pending → drawn
-     * transition. `state={{}}` (or an all-falsy state) renders `children`, same as omitting the
-     * prop.
-     */
-    state?: ChartState
-    /** Body height while a placeholder shows. Default 240 (`ChartFrame`'s own default height). */
-    placeholderHeight?: number
-    /** Affordance under a pending/empty/error label — a retry button, a "clear filters" link.
-     * Forwarded to whichever placeholder resolves. */
-    stateAction?: ReactNode
-    /** Optional so a title-less pending card can BE a route's `<Suspense>` fallback
-     * (`<ChartCard state={{ pending: true }} placeholderHeight={320} />`, no `children` at all). */
-    children?: ReactNode
-  }
-
-export function ChartCard({
-  title,
-  icon,
-  subtitle,
-  info,
-  value,
-  delta,
-  deltaPeriod,
-  deltaPolarity,
-  count,
-  actions,
-  state,
-  placeholderHeight = 240,
-  stateAction,
-  className,
-  classNames,
-  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 ||
-    info !== undefined ||
-    value !== undefined ||
-    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 [legendClaimants, dispatchLegendSlot] = useReducer(legendSlotReducer, [])
-  const context = useMemo(
-    () => ({ legendSlot, inCard: true, short, legendClaimants, dispatchLegendSlot }),
-    [legendSlot, short, legendClaimants],
-  )
-
-  return (
-    <ChartCardContext.Provider value={context}>
-      <div
-        ref={sizeRef}
-        className={cx(classNames?.root, className)}
-        style={{ ...cardStyle, ...style }}
-        {...(resolvedState === 'pending' && { 'aria-busy': 'true' })}
-        {...(short && { 'data-basalt-card-short': '' })}
-      >
-        {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>
-    </ChartCardContext.Provider>
-  )
-}