cursedbelt 5.81.2 → 5.85.0

package/src/react/components/Heat.tsx

@@ -0,0 +1,249 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import { cn } from '../lib/cn.js';
+import type { ColDef } from './DataTable/types.js';
+import type { StatTileTone } from './StatTile.js';
+
+/**
+ * Heat — a value's standing against a BASELINE, as a quiet tint on the number.
+ *
+ * ── The ask (owner, 2026-10-20, forge task station-evolution) ───────────────
+ * *"for tables and charts that show good and bad or high and low values such as cost info I would
+ * like color coding to help me understand where the good and problem areas are … so anomalies or
+ * high overuse relative to a baseline or to other apps/models/etc is obvious from a glance."*
+ *
+ * ── What it is, and what it is not ──────────────────────────────────────────
+ * {@link ThresholdMeter} answers "how close to a LIMIT" — one value, one ceiling, two thresholds.
+ * Heat answers "how does this row compare to the OTHERS" — a column of costs, token counts or
+ * error rates, each scored against the column's baseline (its median by default, or a limit the
+ * caller names). Five bands, never a continuous gradient: a gradient makes every cell a slightly
+ * different colour and nothing stands out, which is the opposite of the ask. The bands ride the
+ * status tokens (FND-10, colour means status), so they re-theme and clear 4.5:1 in both modes:
+ *
+ *     good      well under the baseline       success tint
+ *     ok        about the baseline            no tint — the quiet default
+ *     notice    somewhat over                 faint warning tint
+ *     high      well over                     warning tint
+ *     critical  far over                      destructive tint
+ *
+ * The number stays the signal: the tint is added to it, never substituted for it, and the band's
+ * word rides along for assistive tech (`sr-only`), so colour is never the only channel (FND-9).
+ *
+ * ── Where it goes ───────────────────────────────────────────────────────────
+ * A `DataTable` column through {@link heatColumn}; any number through {@link HeatCell}; a tile's
+ * tone through {@link heatTileTone}; a bar's colour through {@link heatChartTone} and `BarChart`'s
+ * `colorBy`. One scale per column — two columns scored against each other's baselines would make
+ * the same number two colours.
+ */
+export type HeatBand = 'good' | 'ok' | 'notice' | 'high' | 'critical';
+
+export const HEAT_BANDS: readonly HeatBand[] = ['good', 'ok', 'notice', 'high', 'critical'];
+
+/** Where the bands turn, as RATIOS of the baseline. */
+export interface HeatSteps {
+  /** At or under this ratio the value is `good`. */
+  good: number;
+  /** From this ratio the value is `notice`. */
+  notice: number;
+  /** From this ratio the value is `high`. */
+  high: number;
+  /** From this ratio the value is `critical`. */
+  critical: number;
+}
+
+/**
+ * Comparing rows to each other: half the baseline is good, a quarter over is worth a glance,
+ * three-quarters over is high, two and a half times is the anomaly. Wide on purpose — a column of
+ * costs varies by nature, and a tint on half the rows highlights nothing.
+ */
+export const RELATIVE_STEPS: HeatSteps = { good: 0.5, notice: 1.25, high: 1.75, critical: 2.5 };
+
+/**
+ * Scoring against a LIMIT (`baseline` is the allowance): the same 85% / 95% turns as
+ * {@link ThresholdMeter}, so a quota reads the same colour as a number and as a bar.
+ */
+export const LIMIT_STEPS: HeatSteps = { good: 0.5, notice: 0.7, high: 0.85, critical: 0.95 };
+
+export interface HeatScale {
+  /** The value a ratio of `1` means — the column's median, a fleet average, or a limit. */
+  baseline: number;
+  /**
+   * Which direction is bad. `high` (default): more than the baseline is worse — cost, tokens,
+   * errors. `low`: less is worse — a cache hit rate, a success rate; the ratio is inverted.
+   */
+  worse?: 'high' | 'low';
+  /** Where the bands turn. Default {@link RELATIVE_STEPS}; {@link LIMIT_STEPS} for a quota. */
+  steps?: HeatSteps;
+}
+
+const ratioOf = (value: number, scale: HeatScale): number | null => {
+  if (!Number.isFinite(value) || !Number.isFinite(scale.baseline)) return null;
+  if (scale.worse === 'low') {
+    // A rate under the baseline is the problem: a 50% hit rate against a 90% baseline reads as
+    // 1.8× "bad". Zero is the worst a rate can be, and infinity would paint it the same.
+    if (value <= 0) return Number.POSITIVE_INFINITY;
+    return scale.baseline / value;
+  }
+  if (scale.baseline <= 0) return value > 0 ? Number.POSITIVE_INFINITY : 1;
+  return value / scale.baseline;
+};
+
+/**
+ * The band a value falls in — `null` for nothing to score (a missing value, a NaN baseline),
+ * which draws no tint rather than a false alarm.
+ */
+export function heatBandOf(value: number | null | undefined, scale: HeatScale): HeatBand | null {
+  if (value === null || value === undefined) return null;
+  const ratio = ratioOf(value, scale);
+  if (ratio === null) return null;
+  const steps = scale.steps ?? RELATIVE_STEPS;
+  if (ratio >= steps.critical) return 'critical';
+  if (ratio >= steps.high) return 'high';
+  if (ratio >= steps.notice) return 'notice';
+  if (ratio <= steps.good) return 'good';
+  return 'ok';
+}
+
+const median = (sorted: readonly number[]): number => {
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 1 ? (sorted[mid] as number) : ((sorted[mid - 1] as number) + (sorted[mid] as number)) / 2;
+};
+
+/**
+ * A scale whose baseline is the data's own — the MEDIAN by default, because one forty-minute
+ * agent in a column of two-minute ones should read as the anomaly, not drag the baseline up to
+ * meet it (a mean would). `max` makes the largest value the baseline, for a column where the
+ * question is "how far below the top is each" — a share, a hit rate. Zeros are left out of the
+ * baseline: a column of mostly-idle apps would otherwise paint every active one critical.
+ */
+export function heatScaleFrom(
+  values: readonly (number | null | undefined)[],
+  options: { anchor?: 'median' | 'mean' | 'max'; worse?: 'high' | 'low'; steps?: HeatSteps } = {},
+): HeatScale | null {
+  const present = values.filter((v): v is number => typeof v === 'number' && Number.isFinite(v) && v > 0).sort((a, b) => a - b);
+  if (present.length === 0) return null;
+  const anchor = options.anchor ?? 'median';
+  const baseline =
+    anchor === 'max'
+      ? (present[present.length - 1] as number)
+      : anchor === 'mean'
+        ? present.reduce((sum, v) => sum + v, 0) / present.length
+        : median(present);
+  return {
+    baseline,
+    ...(options.worse ? { worse: options.worse } : {}),
+    ...(options.steps ? { steps: options.steps } : {}),
+  };
+}
+
+/**
+ * The tint each band paints. `ok` paints nothing: the quiet default is most of any table, and a
+ * table where every cell is tinted says nothing. Text rides the `-strong` step of the hue so it
+ * clears 4.5:1 on its own tint (the same rule as `Badge`).
+ */
+export const HEAT_CLASS: Record<HeatBand, string> = {
+  good: 'bg-success/10 text-success-strong',
+  ok: '',
+  notice: 'bg-warning/10 text-foreground',
+  high: 'bg-warning/20 text-warning-strong',
+  critical: 'bg-destructive/15 text-destructive-strong',
+};
+
+/** The band in words, for the legend and for assistive tech. */
+export const HEAT_LABEL: Record<HeatBand, string> = {
+  good: 'well under the baseline',
+  ok: 'about the baseline',
+  notice: 'over the baseline',
+  high: 'well over',
+  critical: 'far over — an anomaly',
+};
+
+/** The band as a `StatTile` tone — only the two that mean something is wrong; the rest stay quiet. */
+export const heatTileTone = (band: HeatBand | null): StatTileTone | undefined =>
+  band === 'critical' ? 'danger' : band === 'high' ? 'warning' : undefined;
+
+/** The band as a chart tone, for `BarChart`'s `colorBy`: the quiet bands take the accent. */
+export const heatChartTone = (band: HeatBand | null): 'accent' | 'success' | 'warning' | 'danger' =>
+  band === 'critical' ? 'danger' : band === 'high' || band === 'notice' ? 'warning' : band === 'good' ? 'success' : 'accent';
+
+export interface HeatCellProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children'> {
+  /** The number scored. `null` draws the dash and no tint. */
+  value: number | null | undefined;
+  scale: HeatScale | null;
+  /** How the number is written. Default: `toLocaleString`. */
+  format?: (value: number) => string;
+  /** Draw this instead of the formatted number (the number is still what is scored). */
+  children?: ReactNode;
+}
+
+/**
+ * A number with its band's tint — right-aligned `tabular-nums`, as every number in a table is
+ * (DAT-1). The band's word is in the cell for a screen reader; sighted readers get the tint.
+ */
+export function HeatCell({ value, scale, format = (v) => v.toLocaleString(), children, className, ...rest }: HeatCellProps) {
+  const band = scale ? heatBandOf(value, scale) : null;
+  return (
+    <span
+      {...rest}
+      data-cb-heat={band ?? undefined}
+      className={cn('inline-flex min-w-0 items-baseline justify-end rounded-sm px-1.5 py-0.5 tabular-nums', band ? HEAT_CLASS[band] : null, className)}
+    >
+      {children ?? (value === null || value === undefined || !Number.isFinite(value) ? '—' : format(value))}
+      {band && band !== 'ok' ? <span className='sr-only'> ({HEAT_LABEL[band]})</span> : null}
+    </span>
+  );
+}
+
+/**
+ * A `DataTable` column scored by heat: the column's `render` becomes a {@link HeatCell} over
+ * `pick(row)`, and `type: 'number'` keeps the right alignment and the numeric sort. The scale is
+ * computed ONCE from the rows (`heatScaleFrom`), or passed when a limit is the baseline.
+ */
+export function heatColumn<TRow>(
+  col: Omit<ColDef<TRow>, 'render'>,
+  pick: (row: TRow) => number | null | undefined,
+  scale: HeatScale | null,
+  format?: (value: number) => string,
+): ColDef<TRow> {
+  return {
+    ...col,
+    type: col.type || 'number',
+    render: (row) => <HeatCell value={pick(row)} scale={scale} {...(format ? { format } : {})} />,
+  };
+}
+
+export interface HeatLegendProps extends HTMLAttributes<HTMLUListElement> {
+  scale: HeatScale;
+  format?: (value: number) => string;
+  /** What the baseline is — "fleet median", "the included 10 GB". */
+  baselineLabel?: string;
+}
+
+/**
+ * The five swatches with their turns in the data's own unit, so the tint is readable without
+ * decoding: "high from 1.2M" rather than "1.75×". One line, 12px, under or beside the table.
+ */
+export function HeatLegend({ scale, format = (v) => v.toLocaleString(), baselineLabel = 'baseline', className, ...rest }: HeatLegendProps) {
+  const steps = scale.steps ?? RELATIVE_STEPS;
+  const at = (ratio: number): string => format(scale.worse === 'low' ? scale.baseline / ratio : scale.baseline * ratio);
+  // "under 60k" for a rate that is worse low; "at 125k" (and above) for everything else.
+  const turn = scale.worse === 'low' ? 'under' : 'at';
+  const items: { band: HeatBand; text: string }[] = [
+    { band: 'good', text: scale.worse === 'low' ? `over ${at(steps.good)}` : `under ${at(steps.good)}` },
+    { band: 'ok', text: `${baselineLabel} ${format(scale.baseline)}` },
+    { band: 'notice', text: `${turn} ${at(steps.notice)}` },
+    { band: 'high', text: `${turn} ${at(steps.high)}` },
+    { band: 'critical', text: `${turn} ${at(steps.critical)}` },
+  ];
+  return (
+    <ul {...rest} data-cb-heat-legend='' className={cn('m-0 flex list-none flex-wrap items-center gap-x-4 gap-y-1 p-0 text-xs text-muted-foreground', className)}>
+      {items.map((item) => (
+        <li key={item.band} className='flex items-center gap-1.5'>
+          <span aria-hidden='true' className={cn('inline-block size-3 rounded-sm border border-border', HEAT_CLASS[item.band] || 'bg-transparent')} />
+          <span>
+            <span className='font-medium text-foreground'>{item.band}</span> · {item.text}
+          </span>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/react/components/HoverCard.tsx

@@ -39,6 +39,7 @@ export function HoverCard({
   openDelay = HOVER_HINT_DELAY_MS,
   closeDelay = 100,
   className,
+  ...rest
 }: HoverCardProps) {
   const hasHover = useHasHover();
   const container = useFloatingContainer();
@@ -52,6 +53,7 @@ export function HoverCard({
       <RHover.Trigger asChild>{trigger}</RHover.Trigger>
       <RHover.Portal container={container}>
         <RHover.Content
+          {...rest}
           align={align}
           side={side}
           sideOffset={4}

package/src/react/components/IconPicker.tsx

@@ -147,6 +147,7 @@ export function IconPicker({
   sets = ICON_SETS,
   fetcher,
   className,
+  ...rest
 }: IconPickerProps) {
   const [query, setQuery] = useState(initialQuery);
   const [typed, setTyped] = useState(false);
@@ -220,7 +221,7 @@ export function IconPicker({
   };
 
   return (
-    <div className={cn('cbfk-icons', className)}>
+    <div {...rest} className={cn('cbfk-icons', className)}>
       <SearchInput
         value={query}
         onChange={(next) => {

package/src/react/components/ImpactDialog.tsx

@@ -99,6 +99,7 @@ export function ImpactDialog<V extends string = string>({
   busyLabel = 'Applying…',
   size = 'md',
   children,
+  ...rest
 }: ImpactDialogProps<V>) {
   const groupName = useId();
   const preferred = choices.find((c) => c.recommended && !c.disabled)?.value ?? null;
@@ -121,6 +122,7 @@ export function ImpactDialog<V extends string = string>({
     // click the guard exists for, so an isDirty discard prompt would only add a
     // confirmation step in front of a choice that costs one click to remake.
     <Modal
+      {...rest}
       open={open}
       onClose={onClose}
       size={size}

package/src/react/components/InfoHintImpl.tsx

@@ -45,6 +45,7 @@ export default function InfoHintImpl({
   label = 'More info',
   initialOpen = false,
   initialFocus = false,
+  ...rest
 }: InfoHintImplProps) {
   const [open, setOpen] = useState(initialOpen);
   const hasHover = useHasHover();
@@ -103,6 +104,7 @@ export default function InfoHintImpl({
   return (
     <>
       <button
+        {...rest}
         // guardrails-ignore no-raw-action-button: presentational hover/click disclosure
         // trigger for the floating help panel — no destructive/mutating intent, and the
         // floating-ui ref/interaction wiring here doesn't fit the Button primitive.

package/src/react/components/InheritBadge.tsx

@@ -98,6 +98,7 @@ export function InheritBadge({
   disabled,
   title,
   className,
+  ...rest
 }: InheritBadgeProps) {
   const inherited = source === 'inherited';
   const Glyph = inherited ? CircleDashed : Pin;
@@ -121,7 +122,7 @@ export function InheritBadge({
   );
 
   return (
-    <span className={cn('group inline-flex items-center gap-1', className)}>
+    <span {...rest} className={cn('group inline-flex items-center gap-1', className)}>
       {/* DESIGN.md §4: the explanation goes through the design system's Tooltip, never
           a native `title` — that one is the OS's, appears after a second, cannot be
           themed, and does not exist on a phone at all. (unit 11) */}

package/src/react/components/InlineEditableText.tsx

@@ -59,6 +59,7 @@ export function InlineEditableText({
   trigger = 'text',
   wrap = true,
   ariaLabel,
+  ...rest
 }: InlineEditableTextProps) {
   const [editing, setEditing] = useState(false);
   const [draft, setDraft] = useState(value);
@@ -99,6 +100,7 @@ export function InlineEditableText({
     if (multiline) {
       return (
         <AutoGrowTextarea
+          {...rest}
           ref={focusOnMount}
           aria-label={ariaLabel}
           className={cn(editorClass, 'resize-none')}
@@ -119,6 +121,7 @@ export function InlineEditableText({
     }
     return (
       <Input
+        {...rest}
         ref={focusOnMount}
         aria-label={ariaLabel}
         className={editorClass}
@@ -143,13 +146,13 @@ export function InlineEditableText({
   if (!canEdit && !value) return null;
 
   // Read-only: plain text.
-  if (!canEdit) return <span className={className}>{value}</span>;
+  if (!canEdit) return <span {...rest} className={className}>{value}</span>;
 
   // Icon trigger: text is inert (rows where clicking the text means open/select);
   // the pencil is the explicit edit affordance.
   if (trigger === 'icon') {
     return (
-      <span className='inline-flex min-w-0 items-center gap-1'>
+      <span {...rest} className='inline-flex min-w-0 items-center gap-1'>
         <span className={cn('truncate', !value && 'italic text-muted-foreground', className)}>
           {value || placeholder}
         </span>
@@ -163,7 +166,7 @@ export function InlineEditableText({
   // Editable display: a real <button> so Enter/Space activation + focus come free,
   // styled to read as inline text.
   return (
-    <Tooltip content='Click to edit'>
+    <Tooltip {...rest} content='Click to edit'>
       <button
         // guardrails-ignore no-raw-action-button: click-to-edit display must render as
         // plain inline text (whitespace-pre-wrap/break-words, no button chrome) — Button's

package/src/react/components/IsolatedFrame.tsx

@@ -79,6 +79,7 @@ export function IsolatedFrame({
   className,
   frameRef,
   onFrameLoad,
+  ...rest
 }: IsolatedFrameProps) {
   const hasContent = Boolean(src || srcDoc);
   const sourceKey = src ?? srcDoc;
@@ -137,7 +138,7 @@ export function IsolatedFrame({
 
   if (mode === 'fullscreen') {
     return (
-      <Modal open onClose={() => onClose?.()} size='full' title={title} scrollBody={false}>
+      <Modal {...rest} open onClose={() => onClose?.()} size='full' title={title} scrollBody={false}>
         <div className={cn('min-h-0 flex-1', className)}>{frame}</div>
       </Modal>
     );
@@ -145,7 +146,7 @@ export function IsolatedFrame({
 
   if (mode === 'mobile') {
     return (
-      <ScrollArea className={cn('h-full w-full', className)}>
+      <ScrollArea {...rest} className={cn('h-full w-full', className)}>
         <div className='flex min-h-full w-full items-start justify-center p-4'>
           <div
             // The bezel: a rounded, overflow-hidden device frame at a fixed logical
@@ -165,5 +166,5 @@ export function IsolatedFrame({
   }
 
   // desktop
-  return <div className={cn('h-full w-full', className)}>{frame}</div>;
+  return <div {...rest} className={cn('h-full w-full', className)}>{frame}</div>;
 }

package/src/react/components/JsonEditor.tsx

@@ -82,6 +82,7 @@ export const JsonEditor = ({
   classNames,
   styles,
   unstyled,
+  ...rest
 }: JsonEditorProps) => {
   // Hold `parse`/`onResult` in refs so the memo + effect depend ONLY on `value`.
   // This keeps `result` referentially stable per `value` even when the parent
@@ -123,6 +124,7 @@ export const JsonEditor = ({
 
   return (
     <div
+      {...rest}
       className={resolveClass('flex flex-col gap-2', classNames?.root ?? className, unstyled)}
       style={resolveStyle({}, styles?.root ?? style, unstyled)}
     >

package/src/react/components/KanbanBoard.tsx

@@ -79,6 +79,7 @@ export function KanbanBoard<T>({
   emptyText = 'Nothing here yet',
   'aria-label': ariaLabel,
   className,
+  ...rest
 }: KanbanBoardProps<T>) {
   const containers = useMemo(() => columns.map((c) => ({ id: c.id, items: [...c.items] })), [columns]);
   const onDrop = useCallback(
@@ -133,7 +134,7 @@ export function KanbanBoard<T>({
   };
 
   return (
-    <ContainerContext>
+    <ContainerContext {...rest}>
       <div className={cn('flex min-h-0 min-w-0 flex-1 flex-col gap-2', className)} data-cb-kanban-frame>
         <nav aria-label={`${ariaLabel}: columns`} data-cb-kanban-tray className='min-w-0 md:hidden'>
           <ScrollArea

package/src/react/components/KeyBadge.tsx

@@ -33,19 +33,23 @@ export interface KeyBadgeProps {
  *
  * Plain stylesheet (`formKit.css`) — draws without Tailwind; `cursedbelt/react/form-kit`.
  */
-export function KeyBadge({ children, description, uppercase, className }: KeyBadgeProps) {
-  const badge = (
-    <span
-      className={cn('cbfk-key', description === undefined && className)}
-      data-uppercase={uppercase ? 'true' : undefined}
-    >
-      {children}
-    </span>
-  );
-  if (description === undefined) return badge;
+export function KeyBadge({ children, description, uppercase, className, ...rest }: KeyBadgeProps) {
+  if (description === undefined) {
+    return (
+      <span
+        {...rest}
+        className={cn('cbfk-key', className)}
+        data-uppercase={uppercase ? 'true' : undefined}
+      >
+        {children}
+      </span>
+    );
+  }
   return (
-    <p className={cn('cbfk-keyline', className)}>
-      {badge}
+    <p {...rest} className={cn('cbfk-keyline', className)}>
+      <span className='cbfk-key' data-uppercase={uppercase ? 'true' : undefined}>
+        {children}
+      </span>
       <span>{description}</span>
     </p>
   );

package/src/react/components/Lightbox.tsx

@@ -20,9 +20,10 @@ export interface LightboxProps {
  *
  * Outside-click and Escape both close (no discard guard — a lightbox is never dirty).
  */
-export function Lightbox({ open, onClose, children, caption }: LightboxProps) {
+export function Lightbox({ open, onClose, children, caption, ...rest }: LightboxProps) {
   return (
     <Dialog
+      {...rest}
       open={open}
       onOpenChange={(v) => {
         if (!v) onClose();

package/src/react/components/ListToolbar.tsx

@@ -114,6 +114,7 @@ export function ListToolbar({
   view,
   actions,
   className,
+  ...rest
 }: ListToolbarProps) {
   const showSearch = search !== undefined && onSearchChange !== undefined;
   const showChips = chips !== undefined && chips.length > 0 && onChipChange !== undefined;
@@ -121,6 +122,7 @@ export function ListToolbar({
 
   return (
     <div
+      {...rest}
       className={cn(
         'flex flex-wrap items-center gap-x-3 gap-y-2',
         // From `sm:` a row WITH chips never wraps: the chips are the one item that can give way

package/src/react/components/LogViewer.tsx

@@ -145,6 +145,7 @@ export function LogViewer({
   onSelectLine,
   selectedLine = null,
   className,
+  ...rest
 }: LogViewerProps) {
   const [filter, setFilter] = useState('');
   const [following, setFollowing] = useState(followDefault);
@@ -213,7 +214,7 @@ export function LogViewer({
     !hasStrip || title != null || (exitCode !== null && exitCode !== 0) || typeof durationMs === 'number' || filterable;
 
   return (
-    <div className={cn('flex flex-col gap-2', className)}>
+    <div {...rest} className={cn('flex flex-col gap-2', className)}>
       {toolbarRow && (
       <div className="flex flex-wrap items-center gap-2">
         {title && <span className="cb-meta-label">{title}</span>}

package/src/react/components/Menu.tsx

@@ -59,10 +59,10 @@ export function Menu({ children, className, ...rest }: MenuProps) {
   };
   return (
     <div
+      {...rest}
       role='menu'
       tabIndex={-1}
       data-cb-menu=''
-      aria-label={rest['aria-label']}
       onKeyDown={onKeyDown}
       className={cn('flex flex-col gap-px outline-none', className)}
     >
@@ -119,13 +119,14 @@ export function MenuItem({
   hint,
   className,
   children,
+  ...rest
 }: MenuItemProps) {
   const hintId = useId();
   const reason = unavailableReason?.trim() || undefined;
   const refused = reason !== undefined && !disabled;
   const choice = selected !== undefined;
   return (
-    <Tooltip content={reason ?? title} side='right' multiline>
+    <Tooltip {...rest} content={reason ?? title} side='right' multiline>
       {/* The role and aria-checked are one condition: "menuitem" pairs with no aria-checked and
           "menuitemradio" with a real boolean. The linter checks the union of both branches. */}
       {/* biome-ignore lint/a11y/useAriaPropsSupportedByRole: see the comment above */}
@@ -188,9 +189,10 @@ export function MenuItem({
 }
 
 /** A small uppercase heading over a group of items. */
-export function MenuLabel({ children, className }: { children: ReactNode; className?: string }) {
+export function MenuLabel({ children, className, ...rest }: { children: ReactNode; className?: string }) {
   return (
     <div
+      {...rest}
       data-cb-menu-label=''
       className={cn('px-2 pt-2 pb-1 font-bold text-muted-foreground text-xs uppercase tracking-wider', className)}
     >
@@ -199,7 +201,7 @@ export function MenuLabel({ children, className }: { children: ReactNode; classN
   );
 }
 
-export function MenuSeparator({ className }: { className?: string }) {
+export function MenuSeparator({ className, ...rest }: { className?: string }) {
   // biome-ignore lint/a11y/useSemanticElements: an <hr> inside role=menu is not a menu separator to AT; role=separator is.
-  return <div role='separator' className={cn('my-1 h-px bg-border', className)} />;
+  return <div {...rest} role='separator' className={cn('my-1 h-px bg-border', className)} />;
 }

package/src/react/components/MeterList.tsx

@@ -83,9 +83,9 @@ export interface MeterListProps {
  * On narrow screens the bar drops under the label block (two-line row) instead
  * of crushing the label — no horizontal scrolling, targets stay ≥44px tall.
  */
-export function MeterList({ items, flat = false, labelWidth = 'default', className }: MeterListProps) {
-  const list = (
-    <div className={cn('flex flex-col divide-y divide-border', className)}>
+export function MeterList({ items, flat = false, labelWidth = 'default', className, ...rest }: MeterListProps) {
+  const rows = (
+    <>
       {items.map((item) => {
         const interactive = item.onClick !== undefined;
         const pct =
@@ -160,12 +160,17 @@ export function MeterList({ items, flat = false, labelWidth = 'default', classNa
           </div>
         );
       })}
-    </div>
+    </>
   );
-  if (flat) return list;
+  if (flat)
+    return (
+      <div {...rest} className={cn('flex flex-col divide-y divide-border', className)}>
+        {rows}
+      </div>
+    );
   return (
-    <Surface level='flat' pad='sm' radius='lg'>
-      {list}
+    <Surface {...rest} level='flat' pad='sm' radius='lg'>
+      <div className={cn('flex flex-col divide-y divide-border', className)}>{rows}</div>
     </Surface>
   );
 }

package/src/react/components/Modal.tsx

@@ -173,6 +173,7 @@ export function Modal({
   aside,
   asideWidth = 'sm',
   className,
+  ...rest
 }: ModalProps) {
   const { guardedClose, discardOverlay, isConfirming, cancelDiscard } = useDiscardGuard({
     open,
@@ -191,6 +192,7 @@ export function Modal({
 
   return (
     <Dialog
+      {...rest}
       open={open}
       onOpenChange={(v) => {
         if (!v) guardedClose();

package/src/react/components/MultiSelectField.tsx

@@ -41,9 +41,11 @@ export function MultiSelectField({
   'aria-describedby': ariaDescribedBy,
   className,
   size = 'md',
+  ...rest
 }: MultiSelectFieldProps) {
   return (
     <ComboboxField
+      {...rest}
       multiple
       value={value}
       onChange={onChange}

package/src/react/components/OnlineDot.tsx

@@ -13,10 +13,10 @@ export interface OnlineDotProps {
  * A small presence dot: green (`bg-success`) when the user is online, muted gray
  * otherwise. Pair with the app's own presence/WebSocket hook to drive `online`.
  */
-export function OnlineDot({ online, className, label }: OnlineDotProps) {
+export function OnlineDot({ online, className, label, ...rest }: OnlineDotProps) {
   const text = label ?? (online ? 'Online' : 'Offline');
   return (
-    <Tooltip content={text}>
+    <Tooltip {...rest} content={text}>
       <span
         aria-label={text}
         role='img'