basalt-ui 1.27.0 → 1.28.0

package/src/dashboard/stat-group.tsx

@@ -0,0 +1,74 @@
+/**
+ * StatGroup — the KPI row, and the second half of the column law `WidgetGrid` owns for widgets
+ * (audit B #6/#7). Same argument, different numbers: a KPI is a short pre-formatted string, so it
+ * packs tighter than a chart card and the law starts at TWO on a phone.
+ *
+ * **`cols` is the DESKTOP count** and the only number a consumer states; the law is
+ * `base 2 → sm min(cols, 3) → lg cols`. Five is the ceiling — past that the cells are narrower than
+ * a formatted currency value and the row is a table.
+ *
+ * **`lg` enters the package here and in `WidgetGrid`, nowhere else.** `sm` stays the only
+ * breakpoint a consumer writes (`docs/CONTROLS-SPEC.md` §2).
+ *
+ * `divided` swaps the column gap for a hairline rail between cells — the bare-metric-row look, for
+ * KPIs that are one reading split several ways rather than several independent cards. It draws the
+ * rule on the GROUP, so the cells stay whatever they are; on `StatCard`s (which carry their own
+ * panel and shadow ring) the rail reads as a second frame, so pair it with unadorned children.
+ *
+ * @example
+ * import { StatCard, StatGroup } from 'basalt-ui'
+ *
+ * <StatGroup cols={4}>
+ *   {kpis.map((kpi) => (
+ *     <StatCard key={kpi.key} title={kpi.title} value={kpi.value} delta={kpi.delta} />
+ *   ))}
+ * </StatGroup>
+ */
+import type { CSSProperties, ReactNode } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import classes from './stat-group.module.css'
+
+/** The desktop KPI column count. */
+export type StatGroupCols = 2 | 3 | 4 | 5
+
+export type StatGroupProps = BasaltProps & {
+  /** The DESKTOP column count (`lg` and up). Default `4`. `sm` gets `min(cols, 3)`, a phone gets 2.
+   * Never a responsive object — the law is basalt's, see the module docblock. */
+  cols?: StatGroupCols
+  /** Swap the column gap for a hairline rail between cells. Default `false`. */
+  divided?: boolean
+  /** The KPI cells — normally `StatCard`s. */
+  children: ReactNode
+}
+
+export function StatGroup({
+  cols = 4,
+  divided = false,
+  children,
+  className,
+  style,
+}: StatGroupProps) {
+  const smCols = Math.min(cols, 3)
+
+  return (
+    <div
+      className={cx(classes.root, className)}
+      data-cols={cols}
+      data-sm-cols={smCols}
+      // An ATTRIBUTE, not a second class: the rail's rules key off the resolved column count
+      // (`[data-cols]`/`[data-sm-cols]`) already, so one selector shape carries the whole law —
+      // same idiom `stat-card.module.css` uses for `[data-placement]`.
+      {...(divided && { 'data-divided': 'true' })}
+      style={
+        {
+          '--basalt-stat-group-cols-sm': smCols,
+          '--basalt-stat-group-cols-lg': cols,
+          ...style,
+        } as CSSProperties
+      }
+    >
+      {children}
+    </div>
+  )
+}

package/src/dashboard/widget-grid.module.css

@@ -0,0 +1,53 @@
+/*
+ * WidgetGrid's column law, in CSS (law C9 — a responsive swap belongs to the control, never to a JS
+ * media query). The two literals below are Mantine's own `--mantine-breakpoint-sm` (48em) and
+ * `--mantine-breakpoint-lg` (75em); a `@media` condition is resolved before custom properties
+ * exist, so the number has to be written — same standing constraint `content/article-layout.
+ * module.css` documents.
+ *
+ * The COUNTS are custom properties instead, set once per instance by the component: three
+ * hand-written `repeat()` blocks would have to enumerate every `cols` value, and the whole point of
+ * this primitive is that a consumer states one desktop number and basalt owns the rest.
+ */
+
+.root {
+  display: grid;
+  /* Below `sm` a widget column is always 1 — a dashboard card holds a chart, and two of them on a
+     phone is two unreadable charts. */
+  grid-template-columns: repeat(1, minmax(0, 1fr));
+  gap: var(--vx-space-stack-md);
+}
+
+@media (min-width: 48em) {
+  .root {
+    grid-template-columns: repeat(var(--basalt-widget-grid-cols-sm), minmax(0, 1fr));
+  }
+}
+
+@media (min-width: 75em) {
+  .root {
+    grid-template-columns: repeat(var(--basalt-widget-grid-cols-lg), minmax(0, 1fr));
+  }
+}
+
+/*
+ * `min-width: 0` on every cell: a grid track's default `min-width: auto` is its content's intrinsic
+ * width, so one wide `<table>` or one long unbroken value blows the whole row out instead of
+ * scrolling inside its own card.
+ */
+.item {
+  grid-column: span 1;
+  min-width: 0;
+}
+
+@media (min-width: 48em) {
+  .item {
+    grid-column: span var(--basalt-widget-grid-span-sm);
+  }
+}
+
+@media (min-width: 75em) {
+  .item {
+    grid-column: span var(--basalt-widget-grid-span-lg);
+  }
+}

package/src/dashboard/widget-grid.module.css.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly root: string
+  readonly item: string
+}
+export default classes

package/src/dashboard/widget-grid.tsx

@@ -0,0 +1,127 @@
+/**
+ * WidgetGrid — the dashboard's column law, owned once (audit B #6/#7).
+ *
+ * Every consumer hand-wrote it: `SimpleGrid cols={{ base: 1, md: 3 }}` on one page,
+ * `cols={{ base: 1, sm: 2, lg: 3 }}` on the next, `Grid.Col span={{ base: 12, md: 8 }}` on a third
+ * — three different breakpoint sets for the same shape, in one app. That is not a styling
+ * preference, it is a layout law nobody owned, and the cost is that a card is 2-up on one route and
+ * 3-up on another at the same viewport.
+ *
+ * **`cols` is the DESKTOP count, and it is the only number a consumer states.** The law is
+ * `base 1 → sm min(cols, 2) → lg cols`: a phone gets one column because a dashboard card holds a
+ * chart; a tablet gets at most two because a third makes every chart narrower than
+ * `VX.phoneChartWidth`; the full count lands at `lg`. Mantine's `cols={{ … }}` object is
+ * deliberately NOT forwarded — a responsive object on the public prop is exactly the seam that let
+ * five call sites disagree.
+ *
+ * **This is the sanctioned place `lg` enters the package.** `sm` is still the only breakpoint a
+ * consumer writes (`docs/CONTROLS-SPEC.md` §2); `WidgetGrid` and `StatGroup` own `lg` internally so
+ * nobody else has to.
+ *
+ * `WidgetGrid.Item` is for the one card that is wider than the rest — a hero chart beside two
+ * stacked panels. `span` is likewise the DESKTOP span and is CLAMPED to the live column count at
+ * each breakpoint, so a `span={3}` in a 2-up `sm` row cannot spill into an implicit third track.
+ * A child rendered WITHOUT an `Item` simply occupies one column; the wrapper is not required.
+ *
+ * @example
+ * import { WidgetGrid } from 'basalt-ui'
+ *
+ * <WidgetGrid cols={3}>
+ *   <ChartCard title="Revenue">…</ChartCard>
+ *   <ChartCard title="Sessions">…</ChartCard>
+ *   <ChartCard title="Errors">…</ChartCard>
+ * </WidgetGrid>
+ *
+ * @example
+ * // The 8/4 split every dashboard has, without a 12-column vocabulary.
+ * <WidgetGrid cols={3}>
+ *   <WidgetGrid.Item span={2}>
+ *     <ChartCard title="Total sales over time">…</ChartCard>
+ *   </WidgetGrid.Item>
+ *   <Section title="Top channels">…</Section>
+ * </WidgetGrid>
+ */
+import { createContext, useContext, useMemo } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import classes from './widget-grid.module.css'
+
+/** The desktop column count. Four is the ceiling: a fifth widget column is a KPI row — `StatGroup`. */
+export type WidgetGridCols = 1 | 2 | 3 | 4
+
+/** The resolved counts at the two breakpoints the law names. Base is always 1 and needs no member. */
+type ResolvedCols = { readonly sm: number; readonly lg: number }
+
+/**
+ * The live column count, published so `WidgetGrid.Item` can CLAMP its span against it. A context
+ * rather than a CSS `min()` because `grid-column: span <n>` takes an integer, not a calculation —
+ * and an unclamped span is the failure that looks like a bug: a `span={3}` inside a 2-up row opens
+ * a third, empty implicit track and every sibling below it goes out of alignment.
+ *
+ * The default is the component's own `cols` default, so an `Item` rendered outside a grid (a
+ * consumer's own wrapper, a test) behaves like one inside a default grid instead of throwing.
+ */
+const WidgetGridColsContext = createContext<ResolvedCols>({ sm: 2, lg: 2 })
+
+export type WidgetGridProps = BasaltProps & {
+  /** The DESKTOP column count (`lg` and up). Default `2`. Below that the law resolves it: `sm` gets
+   * `min(cols, 2)`, a phone gets 1. Never a responsive object — see the module docblock. */
+  cols?: WidgetGridCols
+  /** The widgets. A plain child takes one column; wrap it in `WidgetGrid.Item` to span more. */
+  children: ReactNode
+}
+
+export function WidgetGrid({ cols = 2, children, className, style }: WidgetGridProps) {
+  const resolved = useMemo<ResolvedCols>(() => ({ sm: Math.min(cols, 2), lg: cols }), [cols])
+
+  return (
+    <WidgetGridColsContext.Provider value={resolved}>
+      <div
+        className={cx(classes.root, className)}
+        data-cols={cols}
+        style={
+          {
+            '--basalt-widget-grid-cols-sm': resolved.sm,
+            '--basalt-widget-grid-cols-lg': resolved.lg,
+            ...style,
+          } as CSSProperties
+        }
+      >
+        {children}
+      </div>
+    </WidgetGridColsContext.Provider>
+  )
+}
+
+export type WidgetGridItemProps = BasaltProps & {
+  /** The DESKTOP span, clamped to the live column count at every narrower breakpoint. Default `1`. */
+  span?: WidgetGridCols
+  /** The one widget this cell holds. */
+  children: ReactNode
+}
+
+/**
+ * One cell of a {@link WidgetGrid}, spanning more than one column. Reached as `WidgetGrid.Item`.
+ */
+function WidgetGridItem({ span = 1, children, className, style }: WidgetGridItemProps) {
+  const cols = useContext(WidgetGridColsContext)
+
+  return (
+    <div
+      className={cx(classes.item, className)}
+      data-span={span}
+      style={
+        {
+          '--basalt-widget-grid-span-sm': Math.min(span, cols.sm),
+          '--basalt-widget-grid-span-lg': Math.min(span, cols.lg),
+          ...style,
+        } as CSSProperties
+      }
+    >
+      {children}
+    </div>
+  )
+}
+
+WidgetGrid.Item = WidgetGridItem

package/src/data/data-table.module.css

@@ -0,0 +1,64 @@
+/*
+ * BasaltDataTable — the two boxes the base Mantine `Table` cannot paint from a prop: an activatable
+ * row, and the bulk-action bar a selection raises.
+ */
+
+/*
+ * `onRowActivate` — the row → detail hook that pairs with `PageAside`. The row keeps its native
+ * `<tr>` semantics and takes `tabIndex=0` + `data-activatable` rather than `role="button"`: a role
+ * swap would take the row OUT of the table's own row/cell semantics, so a screen reader would stop
+ * announcing the column headers with each cell — which is the whole reason the data is in a table.
+ * The affordance is therefore the cursor and the focus ring, not a role.
+ */
+.activatable {
+  cursor: pointer;
+}
+
+.activatable:focus-visible {
+  outline: 2px solid var(--vx-accent);
+  outline-offset: -2px;
+}
+
+/*
+ * The bulk bar. It sits between the header row and the table, and it is a SURFACE rather than a
+ * bare row: it appears and disappears with the selection, so without a background it reads as the
+ * table jumping. `--vx-surface-subtle` is the same one-step-up fill the sheet rows and the sidebar
+ * use, so nothing new is introduced to the page's surface ladder.
+ */
+.bulkBar {
+  padding: var(--vx-space-row-inset-y, 0.375rem) var(--vx-space-row-inset-x, 0.5rem);
+  border: 1px solid var(--vx-surface-hairline);
+  border-radius: var(--vx-radius-ctrl);
+  background: var(--vx-surface-subtle);
+}
+
+/*
+ * The count. Mono/micro, the same numeric readout idiom the pagination bar's range label uses
+ * (`docs/DESIGN-SPEC.md` §3) — a selection count is a figure, and reading it in the proportional
+ * body font beside proportional button labels made the bar read as a sentence.
+ */
+.bulkCount {
+  font-family: var(--mantine-font-family-monospace);
+  font-size: var(--vx-text-xs);
+  font-variant-numeric: tabular-nums;
+  color: var(--vx-muted);
+}
+
+/*
+ * The measured containment wrapper — `stickyHeader` with neither `maxHeight` nor `minWidth`, the
+ * one shape whose overflow mode cannot be decided statically. `useMeasuredContainment`
+ * (`data-table.tsx`) writes `data-contained`; the two states are declared here rather than as an
+ * inline style so the flip is a single attribute write and a reader can see both at once.
+ *
+ * `[data-contained='false']` is deliberately NOT `overflow: visible` — it is the absence of any
+ * overflow declaration, because `overflow-x: visible` beside a computed `overflow-y` is exactly
+ * the pairing the browser rewrites to `auto`. `min-width: 0` is the flex/grid floor every
+ * containing chain in this library needs and none of them get by default.
+ */
+.containment {
+  min-width: 0;
+}
+
+.containment[data-contained='true'] {
+  overflow-x: auto;
+}

package/src/data/data-table.module.css.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly activatable: string
+  readonly bulkBar: string
+  readonly bulkCount: string
+  readonly containment: string
+}
+export default classes