basalt-ui 1.41.0 → 2.0.0

package/src/controls/slider-control.tsx

@@ -1,159 +0,0 @@
-/**
- * `SliderControl` — a `field.number` as an inspector row (`docs/ASIDE-SPEC.md` §1 "Inspector", G7).
- * Bound like every other control on this subpath: it takes `field`, never `value`/`onChange`/`size`
- * (C2/C5), and `min`/`max`/`step` come off the HANDLE rather than the call site, so the track's
- * grain is the field's own declaration and not a second copy of it.
- *
- * **It is a ROW on every surface, and that is deliberate.** Unlike the filters it has no pill form:
- * a chip whose label is a number, opening a popover holding a track, is two presses to change a
- * value the row states and edits in place. So it renders {@link PanelRow} regardless of
- * `useFilterSurface()`, and it is not a filter — it registers no `{ isActive, reset }` with a
- * `FilterSet`, never counts toward `Filters (n)`, and never answers `Reset all`. Its home is an
- * aside body or a section body, not a bar row.
- *
- * **The write lands on drag END, not on every frame.** A slider emits a value per pointer move; on
- * the URL lane that is one navigation per pixel. The draft is local while dragging and commits
- * once — the same law `NumberFilter`'s stepper states for keystrokes.
- *
- * @example
- * // piCycle: field.number({ fallback: 1, min: 0, max: 2, step: 0.05 })
- * <SliderControl
- *   field={weights.field.piCycle}
- *   label="Pi Cycle Top"
- *   hint="The 111DMA / 350DMA×2 crossover."
- *   format={(v) => `${v.toFixed(2)}×`}
- * />
- *
- * @example
- * // A COMPOSITION row: the readout states the metric's own reading beside the weight, and the
- * // switch that governs the row rides the label line — neither is the field's value, so both are
- * // overrides rather than a `format`.
- * <SliderControl
- *   field={weights.field.piCycle}
- *   label="Pi Cycle Top"
- *   readout="0.35 · ×1.00"
- *   end={<Switch checked={on} onChange={toggle} aria-label="Include Pi Cycle Top" />}
- *   disabled={!on}
- * />
- */
-import { Slider } from '@mantine/core'
-import { useEffect, useRef, useState } from 'react'
-import type { ReactNode } from 'react'
-import type { BasaltProps } from '../common/props'
-import { assertRequiredProps } from '../common/validate'
-import type { FieldHandle, NumberField } from '../state'
-import { PanelRow } from './panel-row'
-
-export type SliderControlProps = BasaltProps & {
-  readonly field: FieldHandle<NumberField>
-  /** The row's label, and the thumb's accessible name. */
-  readonly label: string
-  /** Info glyph + tooltip beside the label — see {@link PanelRow}. */
-  readonly hint?: string
-  /**
-   * The mono readout on the label line. The raw number when omitted, so a unit, a precision or a
-   * ratio is one function rather than a second row.
-   *
-   * @default String(v)
-   */
-  readonly format?: (v: number) => string
-  /**
-   * Replaces the formatted value in the row's readout slot.
-   *
-   * `format` prints the FIELD; this prints whatever the row is actually about. The composition row
-   * that motivated it states a metric's reading beside its weight — `0.35 · ×1.00` — which is one
-   * mono string over two numbers, only one of which this control owns. Prefer `format` whenever the
-   * readout is the field's own value. A FUNCTION form receives the live drag value, so a composed
-   * readout tracks the thumb per frame instead of updating on drag end.
-   */
-  readonly readout?: ReactNode | ((value: number) => ReactNode)
-  /**
-   * A control riding the LABEL line, forwarded to {@link PanelRow.end} — a `Switch` and, by design,
-   * almost nothing else. The composition row's use case is enabling the metric the slider weights:
-   * the toggle governs the row, so it cannot live inside the track it disables.
-   */
-  readonly end?: ReactNode
-  readonly disabled?: boolean
-}
-
-export function SliderControl(props: SliderControlProps): ReactNode {
-  // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
-  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
-  assertRequiredProps('SliderControl', props, ['field'], {
-    field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
-  })
-  const { field, label, hint, format, readout, end, disabled, className, style } = props
-  const [value, setValue] = field.use()
-  const draft = useDraggedNumber(value, setValue)
-
-  return (
-    <PanelRow
-      label={label}
-      readout={
-        typeof readout === 'function'
-          ? readout(draft.value)
-          : (readout ?? (format ?? String)(draft.value))
-      }
-      {...(hint !== undefined && { hint })}
-      {...(end !== undefined && { end })}
-      {...(disabled === true && { disabled: true })}
-      {...(className !== undefined && { className })}
-      {...(style !== undefined && { style })}
-    >
-      <Slider
-        // The tier, stated by the control the way every control on this subpath does
-        // (`docs/CONTROLS-SPEC.md` §3) — `Slider` is deliberately absent from `CTL_THEME`, see
-        // `theme/ctl-theme.tsx`'s note, so the row's slot cannot supply it.
-        size="ctl"
-        // The drag tooltip is off: the row already prints the value, in mono, in a fixed place —
-        // a bubble that follows the thumb states the same number twice and jumps while reading.
-        label={null}
-        thumbLabel={label}
-        // The FIELD's declaration, straight off the handle. An undeclared bound leaves Mantine's own
-        // default (0..100) rather than passing `undefined` through as a bound.
-        {...(field.min !== undefined && { min: field.min })}
-        {...(field.max !== undefined && { max: field.max })}
-        {...(field.step !== undefined && { step: field.step })}
-        {...(disabled === true && { disabled: true })}
-        value={draft.value}
-        onChange={draft.set}
-        onChangeEnd={draft.commit}
-      />
-    </PanelRow>
-  )
-}
-
-/**
- * A local draft that follows the thumb and lands on the field once, on `onChangeEnd` — plus the
- * usual outside-change backstop (`Reset all`, a deep link, a back navigation, the codec's clamp).
- *
- * `seen` is what separates the two directions, exactly as in `SearchFilter`'s debounce and
- * `NumberFilter`'s commit: it holds the last value this hook itself committed, so an incoming change
- * it did not cause is the only thing that overwrites the draft mid-drag.
- */
-function useDraggedNumber(
-  value: number,
-  setValue: (next: number) => void,
-): { value: number; set: (next: number) => void; commit: (next: number) => void } {
-  const [draft, setDraft] = useState(value)
-  const seen = useRef(value)
-  const commitRef = useRef(setValue)
-  commitRef.current = setValue
-
-  useEffect(() => {
-    if (seen.current === value) return
-    seen.current = value
-    setDraft(value)
-  }, [value])
-
-  return {
-    value: draft,
-    set: setDraft,
-    commit: (next) => {
-      setDraft(next)
-      if (next === value) return
-      seen.current = next
-      commitRef.current(next)
-    },
-  }
-}

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

@@ -1,69 +0,0 @@
-/*
- * WidgetGrid's column law, in CSS (law C9 — a responsive swap belongs to the control, never to a JS
- * media query).
- *
- * **The law keys on the CONTAINER, not the viewport**, for the reason `stat-group.module.css`'s
- * header states in full: the shell moves the available width without moving the viewport (a
- * `PageAside` claiming 300px, the sidebar collapsing to its 48px rail, a consumer's split layout),
- * and `@media` is blind to all of it. `.container` — rendered by `WidgetGrid` around the grid —
- * is what makes the queries answerable and is always the box the grid actually fills; a query with
- * no container resolves to false, so leaning on the shell to establish one would have pinned every
- * non-shell consumer to a single column.
- *
- * `.item`'s span law is in the same blocks for the same reason: `grid-column: span <n>` must be
- * clamped against the count the ROOT is actually rendering, and the root's count now follows the
- * container. A span resolved against the viewport while the tracks follow the container is exactly
- * the phantom-track defect `WidgetGrid.Item`'s context clamp exists to prevent.
- *
- * The literals are the container-class law, as in `stat-group.module.css`: the `sm` count opens
- * at `wide` (800px); 1200px, where the full `cols` count opens, is the grid's own boundary above
- * the class table's top step. px, never `em` (an `em` condition resolves against the container's
- * font-size). A condition cannot read a custom property, so the numbers are written; the COUNTS
- * are custom properties, 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. No viewport fallback, for the
- * reason `stat-group.module.css` states: nothing that renders basalt lacks `@container`.
- */
-
-.container {
-  container-type: inline-size;
-  container-name: basalt-grid;
-}
-
-.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);
-}
-
-/*
- * `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;
-}
-
-@container basalt-grid (min-width: 800px) {
-  .root {
-    grid-template-columns: repeat(var(--basalt-widget-grid-cols-sm), minmax(0, 1fr));
-  }
-
-  .item {
-    grid-column: span var(--basalt-widget-grid-span-sm);
-  }
-}
-
-@container basalt-grid (min-width: 1200px) {
-  .root {
-    grid-template-columns: repeat(var(--basalt-widget-grid-cols-lg), minmax(0, 1fr));
-  }
-
-  .item {
-    grid-column: span var(--basalt-widget-grid-span-lg);
-  }
-}

package/src/dashboard/widget-grid.tsx

@@ -1,146 +0,0 @@
-/**
- * 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
- * `CONTAINER_CLASSES.regular`; 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.
- *
- * **The law keys on the CONTAINER, not the viewport.** `WidgetGrid` renders its own
- * `container-type: inline-size` box around the grid, so the counts follow the width the grid
- * ACTUALLY has. The shell moves that width without moving the viewport — a `PageAside` claiming its
- * 300px, the sidebar collapsing 256px → its 48px rail, a consumer's split pane — and a `@media`
- * query sees none of it: it kept three chart columns in a 956px content box and every chart in the
- * row went narrower than `CONTAINER_CLASSES.regular`, which is the exact condition the `lg` rung
- * exists to avoid. See `widget-grid.module.css`'s header for the fallback.
- *
- * **This is the sanctioned place `lg` enters the package.** A consumer never writes a
- * breakpoint — component layout keys on the container's own width
- * (`docs/DESIGN-CORE.md` § Layout, elevation, shapes); `WidgetGrid` and `StatGroup` own their `lg`
- * container rung 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}>
-      {/*
-        Two boxes, and the outer one is not decoration: a size container is a container for its
-        DESCENDANTS, never for itself, so the grid whose tracks the query decides has to sit inside
-        the box being measured. `className`/`style` land on the OUTER box because that is the root
-        element a consumer positions (`BasaltProps`) — and because measuring the box the consumer
-        sized is the whole point. `container-type: inline-size` contains the inline axis only, so
-        the wrapper's block size still comes from the grid: percentage heights resolve exactly as
-        before, and there is no paint containment, so nothing inside is clipped.
-      */}
-      <div className={cx(classes.container, className)} style={style}>
-        <div
-          className={classes.root}
-          data-cols={cols}
-          style={
-            {
-              '--basalt-widget-grid-cols-sm': resolved.sm,
-              '--basalt-widget-grid-cols-lg': resolved.lg,
-            } as CSSProperties
-          }
-        >
-          {children}
-        </div>
-      </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/table.ts

@@ -1,39 +0,0 @@
-/**
- * ./data/table — BasaltDataTable: a sortable data table over @tanstack/react-table, rendered
- * with Mantine primitives. Opt-in chrome: a search/facet toolbar, a pagination bar (client-side
- * or server-driven), and sticky column pinning — see `BasaltDataTableProps` for the full surface.
- *
- * Optional peer: @tanstack/react-table >=8 <9.
- *
- * Use this fine subpath instead of the `./data` barrel when your app only needs the table — it
- * does NOT value-import @tanstack/react-virtual, so the virtual-list peer is never required.
- *
- * Install with:
- *   bun add @tanstack/react-table
- *
- * @example
- * import { BasaltDataTable, createColumnHelper } from 'basalt-ui/data/table'
- * type Row = { name: string; score: number }
- * const col = createColumnHelper<Row>()
- * const columns = [col.accessor('name', { header: 'Name' }), col.accessor('score', { header: 'Score' })]
- * <BasaltDataTable data={rows} columns={columns} enableGlobalFilter enablePagination />
- */
-
-// ── BasaltDataTable ───────────────────────────────────────────────────────────
-export { BasaltDataTable } from './data-table'
-export type {
-  BasaltDataTableProps,
-  BasaltDataTableSlot,
-  DataTableAlign,
-  DataTableColumnId,
-  DataTableColumnPinning,
-  DataTableFacet,
-  DataTableFacetOption,
-} from './data-table'
-
-// ── @tanstack/react-table convenience re-export ───────────────────────────────
-// `createColumnHelper` is the one raw TanStack symbol every `BasaltDataTable` call site needs to
-// build its `columns` array (C1 consolidation: every OTHER pass-through — `useReactTable`,
-// `flexRender`, the row-model builders, and the type re-exports — was unused by any consumer;
-// import TanStack directly for those).
-export { createColumnHelper } from '@tanstack/react-table'