@eifi1/ui-kit 0.10.0 → 0.11.0

package/dist/components/bulk-action-bar.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/bulk-action-bar.tsx"],"sourcesContent":["import { useEffect, useLayoutEffect, useRef, useState } from \"react\";\nimport type { ComponentPropsWithoutRef, CSSProperties, KeyboardEvent, ReactNode } from \"react\";\nimport { X } from \"lucide-react\";\n\nimport { cn } from \"../lib/cn\";\nimport { horizontalStep } from \"../lib/direction\";\nimport { useKitLabels } from \"../i18n/kit-labels\";\nimport { useAnnounce } from \"../hooks/use-announce\";\nimport { OVERLAY_EXIT_MS, prefersReducedMotion } from \"../hooks/use-close-transition\";\nimport { Button, IconButton } from \"./ui\";\n\nexport interface BulkActionBarLabels {\n  /** The count, shown in the bar, spoken by its live region and used as the toolbar's\n   *  name: \"3 selected\". */\n  selected: (count: number) => string;\n  /** The clear/cancel action's name — the X of the floating bar, the text button of the\n   *  others. */\n  clear: string;\n  /** Spoken when the selection empties and the bar goes. */\n  cleared: string;\n}\n\nexport const DEFAULT_BULK_ACTION_BAR_LABELS: BulkActionBarLabels = {\n  selected: (count) => `${count} selected`,\n  clear: \"Clear selection\",\n  cleared: \"Selection cleared\",\n};\n\n/**\n * `floating` — the phone's: fixed above `AppShell`'s bottom nav (`--app-nav-h`) and the\n * home indicator, inset from both sides, a rounded card with a shadow. `sticky` — the\n * desktop's: pinned to the top of its scroll container, over the rows it acts on.\n * `inline` — in the flow, where the caller places it.\n */\nexport type BulkActionBarVariant = \"floating\" | \"sticky\" | \"inline\";\n\nexport interface BulkActionBarProps extends Omit<ComponentPropsWithoutRef<\"div\">, \"role\" | \"children\"> {\n  /** How many items are selected. The bar shows only while this is above zero. */\n  count: number;\n  /** Clear the selection / leave selection mode. */\n  onClear: () => void;\n  /** The actions: buttons (`IconButton size=\"lg\"` on a phone, `Button` from md up),\n   *  in the caller's order. They are the toolbar's arrow-key stops, after the clear. */\n  children?: ReactNode;\n  /** Default `floating`. See {@link BulkActionBarVariant}. */\n  variant?: BulkActionBarVariant;\n  /** Default: `bulkActionBar` from the {@link UiKitProvider}, else English. */\n  labels?: Partial<BulkActionBarLabels>;\n}\n\n/** Where the floating bar sits: clear of the phone nav and of the home indicator,\n *  whichever reaches higher — `FloatingPanel`'s rule, plus the bar's own 0.5rem gap.\n *  Set as inline style, so reposition it through `style` (which is merged over this,\n *  e.g. `style={{ insetInline: \"auto 2rem\", width: \"24rem\" }}`), not `className`. */\nconst FLOATING_STYLE: CSSProperties = {\n  bottom: \"calc(max(var(--app-nav-h, 0px), env(safe-area-inset-bottom, 0px)) + 0.5rem)\",\n  // Both insets on both sides: a logical side has no one physical inset to name, and\n  // the bar is symmetric, so RTL needs nothing more.\n  insetInline: \"max(0.5rem, env(safe-area-inset-left, 0px), env(safe-area-inset-right, 0px))\",\n};\n\n/** What the arrow keys walk: the toolbar's enabled controls. Matched by element, not by\n *  `tabindex`, because the roving below sets every one but the current to `-1` — a\n *  custom control joins with `data-toolbar-item`. */\nconst ITEMS =\n  \"button:not([disabled]),a[href],input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[data-toolbar-item]\";\n\n/** Keys a text field needs for itself — the toolbar must not take its caret away. */\nfunction ownsArrows(el: Element): boolean {\n  if (el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) return true;\n  if (el instanceof HTMLInputElement) return ![\"button\", \"checkbox\", \"radio\", \"submit\", \"reset\"].includes(el.type);\n  return (el as HTMLElement).isContentEditable;\n}\n\n/**\n * The bar that appears while rows are selected: the count, a way out, and what can be\n * done to all of them at once.\n *\n * keksdose had written it three times — the transactions phone bar\n * (mobile-bulk-bar.tsx), the invoice lines' phone and desktop bars\n * (invoice-lines-bulk-bar.tsx) and the payees selection bar — and the copies had\n * drifted where it matters: two parked themselves with a guessed `bottom-16` that the\n * third had already found leaves a 24px gap (live #314: the nav is content-sized and\n * `AppShell` publishes its height as `--app-nav-h`), none of them announced the count,\n * and all three were `role=\"toolbar\"` without the arrow keys that role promises.\n *\n * ## Keep it mounted\n *\n * Render it unconditionally and let `count` decide. At zero it renders only its live\n * region — which must already be in the DOM for the first \"3 selected\" to be heard —\n * and when the count drops to zero it plays its exit before it goes, which a\n * `{count > 0 && <Bar/>}` gate would cut off.\n *\n * ## The toolbar\n *\n * One Tab stop: ←/→ (mirrored in RTL), Home and End move between the controls, and Tab\n * leaves — the WAI-ARIA toolbar pattern, since that is what `role=\"toolbar\"` tells a\n * screen reader to expect. The stop remembers the control last used. Arrow keys inside\n * a text field stay the field's.\n *\n * It is NOT a dialog: no focus trap, no scroll lock — the list behind stays live,\n * because tapping more rows is how a selection grows.\n */\nexport function BulkActionBar({\n  count,\n  onClear,\n  children,\n  variant = \"floating\",\n  labels: labelsProp,\n  className,\n  style,\n  onKeyDown,\n  onFocus,\n  ...rest\n}: BulkActionBarProps) {\n  const labels = useKitLabels(\"bulkActionBar\", DEFAULT_BULK_ACTION_BAR_LABELS, labelsProp);\n  const { announce, regionProps } = useAnnounce();\n  const barRef = useRef<HTMLDivElement>(null);\n  const shown = count > 0;\n\n  // The count the bar last SHOWED, so a bar lowering itself after \"clear\" still reads\n  // \"3 selected\" on its way out rather than \"0 selected\". Adjusted during render\n  // (`Collapse`'s pattern), as is the exit below.\n  const [shownCount, setShownCount] = useState(count);\n  const [leaving, setLeaving] = useState(false);\n  const [prevCount, setPrevCount] = useState(count);\n  if (count !== prevCount) {\n    setPrevCount(count);\n    if (shown) {\n      setShownCount(count);\n      setLeaving(false);\n    } else {\n      setLeaving(prevCount > 0 && !prefersReducedMotion());\n    }\n  }\n  useEffect(() => {\n    if (!leaving) return;\n    const timer = setTimeout(() => setLeaving(false), OVERLAY_EXIT_MS);\n    return () => clearTimeout(timer);\n  }, [leaving]);\n\n  // Spoken on every CHANGE, not on mount: a bar mounted with rows already selected\n  // was not the result of anything the user just did.\n  const spoken = useRef(count);\n  useEffect(() => {\n    if (spoken.current === count) return;\n    spoken.current = count;\n    announce(count > 0 ? labels.selected(count) : labels.cleared);\n  }, [count, labels, announce]);\n\n  // Roving tab stop. The controls are the caller's, so the stop is kept on the DOM\n  // rather than through props: after every render the remembered control (or the\n  // first) is the one with `tabindex=0`, every other one `-1`.\n  const active = useRef<HTMLElement | null>(null);\n  // Every render: the caller's controls come and go (a \"remove added\" that exists\n  // only while some are removable), and a stop on a control that left must move on.\n  useLayoutEffect(() => {\n    rove(barRef.current, active);\n  });\n\n  const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {\n    onKeyDown?.(e);\n    if (e.defaultPrevented || ownsArrows(e.target as Element)) return;\n    const list = itemsOf(barRef.current);\n    const at = list.indexOf(document.activeElement as HTMLElement);\n    if (at === -1 || list.length === 0) return;\n    const step = horizontalStep(e.key, barRef.current);\n    let next = -1;\n    if (step !== 0) next = (at + step + list.length) % list.length;\n    else if (e.key === \"Home\") next = 0;\n    else if (e.key === \"End\") next = list.length - 1;\n    if (next === -1) return;\n    e.preventDefault();\n    active.current = list[next];\n    rove(barRef.current, active);\n    list[next].focus();\n  };\n\n  if (!shown && !leaving) {\n    return <span {...regionProps} />;\n  }\n\n  const floating = variant === \"floating\";\n  const clear = floating ? (\n    <IconButton size=\"lg\" onClick={onClear} aria-label={labels.clear}>\n      <X />\n    </IconButton>\n  ) : (\n    <Button type=\"button\" variant=\"secondary\" size=\"sm\" onClick={onClear}>\n      {labels.clear}\n    </Button>\n  );\n\n  return (\n    <>\n      <span {...regionProps} />\n      <div\n        {...rest}\n        ref={barRef}\n        role=\"toolbar\"\n        aria-label={labels.selected(shownCount)}\n        aria-orientation=\"horizontal\"\n        data-bulk-action-bar={variant}\n        // Leaving: out of the tab order and the accessibility tree at once, while the\n        // bar still animates. The selection it acted on is already gone.\n        inert={!shown || undefined}\n        onKeyDown={handleKeyDown}\n        onFocus={(e) => {\n          onFocus?.(e);\n          // Clicking a control is using it: the stop follows the pointer too.\n          const hit = itemsOf(barRef.current).find((el) => el === e.target);\n          if (hit) {\n            active.current = hit;\n            rove(barRef.current, active);\n          }\n        }}\n        style={floating ? { ...FLOATING_STYLE, ...style } : style}\n        className={cn(\n          \"flex items-center\",\n          floating\n            ? cn(\n                \"fixed z-30 gap-1 rounded-2xl border border-[var(--border)] bg-[var(--bg-surface)] px-2 py-1 shadow-lg\",\n                shown ? \"animate-sheet\" : \"animate-sheet-out\",\n              )\n            : cn(\n                \"gap-2 px-3 py-2\",\n                variant === \"sticky\" &&\n                  \"sticky top-0 z-20 border-b border-[var(--border)] bg-[color-mix(in_srgb,var(--brand)_8%,var(--bg-surface))] backdrop-blur\",\n                shown ? \"animate-overlay\" : \"animate-overlay-out\",\n              ),\n          className,\n        )}\n      >\n        {floating && clear}\n        <span className=\"min-w-0 flex-1 truncate text-sm font-medium text-[var(--text-primary)]\">\n          {labels.selected(shownCount)}\n        </span>\n        {/* `contents`, so the caller's controls are flex items of the bar itself. */}\n        <div className=\"contents\">{children}</div>\n        {!floating && clear}\n      </div>\n    </>\n  );\n}\n\nfunction itemsOf(bar: HTMLElement | null): HTMLElement[] {\n  return bar ? Array.from(bar.querySelectorAll<HTMLElement>(ITEMS)) : [];\n}\n\n/** Put the one Tab stop on the remembered control — or the first, when that one has\n *  gone or was never set — and take it off every other. */\nfunction rove(bar: HTMLElement | null, active: { current: HTMLElement | null }): void {\n  const list = itemsOf(bar);\n  if (!active.current || !list.includes(active.current)) active.current = list[0] ?? null;\n  for (const el of list) el.tabIndex = el === active.current ? 0 : -1;\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/components/bulk-action-bar.tsx"],"sourcesContent":["import { useEffect, useLayoutEffect, useRef, useState } from \"react\";\nimport type { ComponentPropsWithoutRef, CSSProperties, KeyboardEvent, ReactNode } from \"react\";\nimport { X } from \"lucide-react\";\n\nimport { cn } from \"../lib/cn\";\nimport { horizontalStep } from \"../lib/direction\";\nimport { useKitLabels } from \"../i18n/kit-labels\";\nimport { useAnnounce } from \"../hooks/use-announce\";\nimport { useMediaQuery } from \"../hooks/use-media-query\";\nimport { OVERLAY_EXIT_MS, prefersReducedMotion } from \"../hooks/use-close-transition\";\nimport { Button, IconButton } from \"./ui\";\n\nexport interface BulkActionBarLabels {\n  /** The count, shown in the bar, spoken by its live region and used as the toolbar's\n   *  name: \"3 selected\". */\n  selected: (count: number) => string;\n  /** The clear/cancel action's name — the X of the floating bar, the text button of the\n   *  others. */\n  clear: string;\n  /** Spoken when the selection empties and the bar goes. */\n  cleared: string;\n}\n\nexport const DEFAULT_BULK_ACTION_BAR_LABELS: BulkActionBarLabels = {\n  selected: (count) => `${count} selected`,\n  clear: \"Clear selection\",\n  cleared: \"Selection cleared\",\n};\n\n/**\n * `floating` — the phone's: fixed above `AppShell`'s bottom nav (`--app-nav-h`) and the\n * home indicator, inset from both sides, a rounded card with a shadow. `sticky` — the\n * desktop's: pinned to the top of its scroll container, over the rows it acts on.\n * `inline` — in the flow, where the caller places it.\n */\nexport type BulkActionBarVariant = \"floating\" | \"sticky\" | \"inline\";\n\n/**\n * A variant per breakpoint, mobile first — `{ base: \"floating\", md: \"sticky\" }` is the\n * phone's floating card below 768px and the desktop's sticky bar from there up. The\n * breakpoints are Tailwind's (sm 640, md 768, lg 1024, xl 1280px), the ones the kit's\n * classes already use. keksdose's payees selection bar (payees-selection-bar.tsx)\n * computes exactly this with its own `useMediaQuery(\"(min-width: 768px)\")`; every bar\n * that is a card on a phone and a strip on a desktop would repeat it.\n *\n * Resolved in JS rather than with `md:` classes because the variants differ in more\n * than classes: the floating bar's clear is an icon at the start, the others' a text\n * button at the end, and the floating bar is positioned by inline style.\n */\nexport interface ResponsiveBulkActionBarVariant {\n  base: BulkActionBarVariant;\n  sm?: BulkActionBarVariant;\n  md?: BulkActionBarVariant;\n  lg?: BulkActionBarVariant;\n  xl?: BulkActionBarVariant;\n}\n\nconst BREAKPOINTS = [\n  [\"xl\", \"(min-width: 1280px)\"],\n  [\"lg\", \"(min-width: 1024px)\"],\n  [\"md\", \"(min-width: 768px)\"],\n  [\"sm\", \"(min-width: 640px)\"],\n] as const;\n\n/** The variant in force: the widest breakpoint that matches AND names one, else\n *  `base`. The four queries are subscribed unconditionally — hooks cannot be skipped —\n *  and a plain string variant simply ignores them. Without `matchMedia` (SSR, tests)\n *  every query is false, so the bar renders its `base`, the phone's, first. */\nfunction useResolvedVariant(variant: BulkActionBarVariant | ResponsiveBulkActionBarVariant): BulkActionBarVariant {\n  const matches = {\n    xl: useMediaQuery(BREAKPOINTS[0][1], false),\n    lg: useMediaQuery(BREAKPOINTS[1][1], false),\n    md: useMediaQuery(BREAKPOINTS[2][1], false),\n    sm: useMediaQuery(BREAKPOINTS[3][1], false),\n  };\n  if (typeof variant === \"string\") return variant;\n  for (const [key] of BREAKPOINTS) {\n    const v = variant[key];\n    if (matches[key] && v !== undefined) return v;\n  }\n  return variant.base;\n}\n\nexport interface BulkActionBarProps extends Omit<ComponentPropsWithoutRef<\"div\">, \"role\" | \"children\"> {\n  /** How many items are selected. The bar shows only while this is above zero —\n   *  unless {@link open} says otherwise. */\n  count: number;\n  /**\n   * Show the bar regardless of `count` — `true` for SELECTION MODE with nothing picked\n   * yet, `false` to hide it with rows still selected. Left out, `count > 0` decides, as\n   * before.\n   *\n   * keksdose's invoice lines (invoice-lines-bulk-bar.tsx) enter selection with a\n   * \"Select\" button, and the bar must be there at \"0 selected\" to hold the way out and\n   * a \"Select all\" (pass it as a child); gated on the count, the bar appeared only at\n   * the first tick, and the user who pressed \"Select\" saw nothing happen. The exit plays\n   * when it closes either way, and the count is still announced on every change.\n   */\n  open?: boolean;\n  /** Clear the selection / leave selection mode. */\n  onClear: () => void;\n  /** The actions: buttons (`IconButton size=\"lg\"` on a phone, `Button` from md up),\n   *  in the caller's order. They are the toolbar's arrow-key stops, after the clear. */\n  children?: ReactNode;\n  /** Default `floating`. See {@link BulkActionBarVariant}; an object picks one per\n   *  breakpoint, see {@link ResponsiveBulkActionBarVariant}. */\n  variant?: BulkActionBarVariant | ResponsiveBulkActionBarVariant;\n  /**\n   * Content BELOW the toolbar row, inside the same surface — the same floating card or\n   * sticky tinted strip — but OUTSIDE the toolbar: its fields keep their own Tab stops\n   * and arrow keys, and the toolbar's roving focus never walks into it. keksdose's\n   * desktop receipt-line bar (invoice-lines-bulk-bar.tsx) shows its `BulkFields` form —\n   * a category picker, an exclude checkbox, Apply — under the count and the clear; a\n   * form is not a toolbar's content (`role=\"toolbar\"` promises one arrow-key widget),\n   * and set beside the bar it lost the sticky tint and scrolled away from it.\n   *\n   * On the floating variant the panel scrolls within 60% of the viewport's height, so a\n   * long form on a phone cannot push the bar off the top of the screen.\n   */\n  panel?: ReactNode;\n  /** Default: `bulkActionBar` from the {@link UiKitProvider}, else English. */\n  labels?: Partial<BulkActionBarLabels>;\n}\n\n/** Where the floating bar sits: clear of the phone nav and of the home indicator,\n *  whichever reaches higher — `FloatingPanel`'s rule, plus the bar's own 0.5rem gap.\n *  Set as inline style, so reposition it through `style` (which is merged over this,\n *  e.g. `style={{ insetInline: \"auto 2rem\", width: \"24rem\" }}`), not `className`. */\nconst FLOATING_STYLE: CSSProperties = {\n  bottom: \"calc(max(var(--app-nav-h, 0px), env(safe-area-inset-bottom, 0px)) + 0.5rem)\",\n  // Both insets on both sides: a logical side has no one physical inset to name, and\n  // the bar is symmetric, so RTL needs nothing more.\n  insetInline: \"max(0.5rem, env(safe-area-inset-left, 0px), env(safe-area-inset-right, 0px))\",\n};\n\n/** What the arrow keys walk: the toolbar's enabled controls. Matched by element, not by\n *  `tabindex`, because the roving below sets every one but the current to `-1` — a\n *  custom control joins with `data-toolbar-item`. */\nconst ITEMS =\n  \"button:not([disabled]),a[href],input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[data-toolbar-item]\";\n\n/** Keys a text field needs for itself — the toolbar must not take its caret away. */\nfunction ownsArrows(el: Element): boolean {\n  if (el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) return true;\n  if (el instanceof HTMLInputElement) return ![\"button\", \"checkbox\", \"radio\", \"submit\", \"reset\"].includes(el.type);\n  return (el as HTMLElement).isContentEditable;\n}\n\n/**\n * The bar that appears while rows are selected: the count, a way out, and what can be\n * done to all of them at once.\n *\n * keksdose had written it three times — the transactions phone bar\n * (mobile-bulk-bar.tsx), the invoice lines' phone and desktop bars\n * (invoice-lines-bulk-bar.tsx) and the payees selection bar — and the copies had\n * drifted where it matters: two parked themselves with a guessed `bottom-16` that the\n * third had already found leaves a 24px gap (live #314: the nav is content-sized and\n * `AppShell` publishes its height as `--app-nav-h`), none of them announced the count,\n * and all three were `role=\"toolbar\"` without the arrow keys that role promises.\n *\n * ## Keep it mounted\n *\n * Render it unconditionally and let `count` decide. At zero it renders only its live\n * region — which must already be in the DOM for the first \"3 selected\" to be heard —\n * and when the count drops to zero it plays its exit before it goes, which a\n * `{count > 0 && <Bar/>}` gate would cut off.\n *\n * ## The toolbar\n *\n * One Tab stop: ←/→ (mirrored in RTL), Home and End move between the controls, and Tab\n * leaves — the WAI-ARIA toolbar pattern, since that is what `role=\"toolbar\"` tells a\n * screen reader to expect. The stop remembers the control last used. Arrow keys inside\n * a text field stay the field's.\n *\n * It is NOT a dialog: no focus trap, no scroll lock — the list behind stays live,\n * because tapping more rows is how a selection grows.\n */\nexport function BulkActionBar({\n  count,\n  onClear,\n  children,\n  variant: variantProp = \"floating\",\n  open,\n  panel,\n  labels: labelsProp,\n  className,\n  style,\n  onKeyDown,\n  onFocus,\n  ...rest\n}: BulkActionBarProps) {\n  const labels = useKitLabels(\"bulkActionBar\", DEFAULT_BULK_ACTION_BAR_LABELS, labelsProp);\n  const { announce, regionProps } = useAnnounce();\n  const barRef = useRef<HTMLDivElement>(null);\n  const variant = useResolvedVariant(variantProp);\n  const shown = open ?? count > 0;\n\n  // The count the bar last SHOWED, so a bar lowering itself after \"clear\" still reads\n  // \"3 selected\" on its way out rather than \"0 selected\". Adjusted during render\n  // (`Collapse`'s pattern), as is the exit below.\n  const [shownCount, setShownCount] = useState(count);\n  const [leaving, setLeaving] = useState(false);\n  const [prev, setPrev] = useState({ count, shown });\n  if (count !== prev.count || shown !== prev.shown) {\n    setPrev({ count, shown });\n    if (shown) {\n      setShownCount(count);\n      setLeaving(false);\n    } else if (prev.shown) {\n      setLeaving(!prefersReducedMotion());\n    }\n  }\n  useEffect(() => {\n    if (!leaving) return;\n    const timer = setTimeout(() => setLeaving(false), OVERLAY_EXIT_MS);\n    return () => clearTimeout(timer);\n  }, [leaving]);\n\n  // Spoken on every CHANGE, not on mount: a bar mounted with rows already selected\n  // was not the result of anything the user just did.\n  const spoken = useRef(count);\n  useEffect(() => {\n    if (spoken.current === count) return;\n    spoken.current = count;\n    // In selection mode the bar stays at zero, so zero is a count like any other.\n    announce(count > 0 || shown ? labels.selected(count) : labels.cleared);\n  }, [count, shown, labels, announce]);\n\n  // Roving tab stop. The controls are the caller's, so the stop is kept on the DOM\n  // rather than through props: after every render the remembered control (or the\n  // first) is the one with `tabindex=0`, every other one `-1`.\n  const active = useRef<HTMLElement | null>(null);\n  // Every render: the caller's controls come and go (a \"remove added\" that exists\n  // only while some are removable), and a stop on a control that left must move on.\n  useLayoutEffect(() => {\n    rove(barRef.current, active);\n  });\n\n  const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {\n    onKeyDown?.(e);\n    if (e.defaultPrevented || ownsArrows(e.target as Element)) return;\n    const list = itemsOf(barRef.current);\n    const at = list.indexOf(document.activeElement as HTMLElement);\n    if (at === -1 || list.length === 0) return;\n    const step = horizontalStep(e.key, barRef.current);\n    let next = -1;\n    if (step !== 0) next = (at + step + list.length) % list.length;\n    else if (e.key === \"Home\") next = 0;\n    else if (e.key === \"End\") next = list.length - 1;\n    if (next === -1) return;\n    e.preventDefault();\n    active.current = list[next];\n    rove(barRef.current, active);\n    list[next].focus();\n  };\n\n  if (!shown && !leaving) {\n    return <span {...regionProps} />;\n  }\n\n  const floating = variant === \"floating\";\n  const clear = floating ? (\n    <IconButton size=\"lg\" onClick={onClear} aria-label={labels.clear}>\n      <X />\n    </IconButton>\n  ) : (\n    <Button type=\"button\" variant=\"secondary\" size=\"sm\" onClick={onClear}>\n      {labels.clear}\n    </Button>\n  );\n\n  const hasPanel = panel !== undefined && panel !== null && panel !== false;\n  // The surface — where the bar sits and what it looks like — and the toolbar row's\n  // own layout. Without a panel they are one element, exactly as before 0.11.0; with\n  // one the surface wraps the row and the panel, so both share its tint and position.\n  const surfaceClass = floating\n    ? cn(\n        \"fixed z-30 rounded-2xl border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg\",\n        shown ? \"animate-sheet\" : \"animate-sheet-out\",\n      )\n    : cn(\n        variant === \"sticky\" &&\n          \"sticky top-0 z-20 border-b border-[var(--border)] bg-[color-mix(in_srgb,var(--brand)_8%,var(--bg-surface))] backdrop-blur\",\n        shown ? \"animate-overlay\" : \"animate-overlay-out\",\n      );\n  const rowClass = cn(\"flex items-center\", floating ? \"gap-1 px-2 py-1\" : \"gap-2 px-3 py-2\");\n  const surfaceStyle = floating ? { ...FLOATING_STYLE, ...style } : style;\n\n  const toolbar = (\n    <div\n      {...(hasPanel ? null : rest)}\n      ref={barRef}\n      role=\"toolbar\"\n      aria-label={labels.selected(shownCount)}\n      aria-orientation=\"horizontal\"\n      data-bulk-action-bar={hasPanel ? undefined : variant}\n      // Leaving: out of the tab order and the accessibility tree at once, while the\n      // bar still animates. The selection it acted on is already gone.\n      inert={(!hasPanel && !shown) || undefined}\n      onKeyDown={handleKeyDown}\n      onFocus={(e) => {\n        onFocus?.(e);\n        // Clicking a control is using it: the stop follows the pointer too.\n        const hit = itemsOf(barRef.current).find((el) => el === e.target);\n        if (hit) {\n          active.current = hit;\n          rove(barRef.current, active);\n        }\n      }}\n      style={hasPanel ? undefined : surfaceStyle}\n      className={hasPanel ? rowClass : cn(rowClass, surfaceClass, className)}\n    >\n      {floating && clear}\n      <span className=\"min-w-0 flex-1 truncate text-sm font-medium text-[var(--text-primary)]\">\n        {labels.selected(shownCount)}\n      </span>\n      {/* `contents`, so the caller's controls are flex items of the bar itself. */}\n      <div className=\"contents\">{children}</div>\n      {!floating && clear}\n    </div>\n  );\n\n  return (\n    <>\n      <span {...regionProps} />\n      {hasPanel ? (\n        <div\n          {...rest}\n          data-bulk-action-bar={variant}\n          inert={!shown || undefined}\n          style={surfaceStyle}\n          className={cn(\"flex flex-col\", surfaceClass, className)}\n        >\n          {toolbar}\n          <div\n            data-bulk-action-bar-panel=\"\"\n            className={cn(\n              \"border-t border-[var(--border)] px-3 py-3\",\n              floating && \"max-h-[60dvh] overflow-y-auto\",\n            )}\n          >\n            {panel}\n          </div>\n        </div>\n      ) : (\n        toolbar\n      )}\n    </>\n  );\n}\n\nfunction itemsOf(bar: HTMLElement | null): HTMLElement[] {\n  return bar ? Array.from(bar.querySelectorAll<HTMLElement>(ITEMS)) : [];\n}\n\n/** Put the one Tab stop on the remembered control — or the first, when that one has\n *  gone or was never set — and take it off every other. */\nfunction rove(bar: HTMLElement | null, active: { current: HTMLElement | null }): void {\n  const list = itemsOf(bar);\n  if (!active.current || !list.includes(active.current)) active.current = list[0] ?? null;\n  for (const el of list) el.tabIndex = el === active.current ? 0 : -1;\n}\n"],"mappings":"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","names":[]}

package/dist/components/button-group.d.ts

@@ -1,10 +1,29 @@
 import * as react from 'react';
-import { ComponentPropsWithoutRef } from 'react';
+import { ComponentPropsWithoutRef, ReactNode, Ref, MouseEvent, ReactElement } from 'react';
+import { ButtonVariant, ButtonSize } from './ui.js';
+import './tooltip.js';
+import '../hooks/use-anchored-rect.js';
+import '../lib/clipping.js';
 
 interface ButtonGroupProps extends Omit<ComponentPropsWithoutRef<"div">, "role"> {
     /** `horizontal` (default): side by side, in reading order. `vertical`: stacked —
      *  the map's zoom + over −. */
     orientation?: "horizontal" | "vertical";
+    /**
+     * `joined` (default): one frame, hairline dividers, outer corners rounded. `gapped`:
+     * separate controls with a small gap, each keeping its own shape — the overlay
+     * discs of keksdose's receipt preview zoom (scan-file-preview.tsx:362, the − and +
+     * `IconButton variant="overlay"` in a hand-made `flex gap-1`), where a joined frame
+     * would be a box drawn over the photo.
+     */
+    variant?: "joined" | "gapped";
+    /**
+     * Float it: a surface with a shadow, for a toolbar that sits OVER content (a map's
+     * zoom, a photo's controls) rather than in the page's flow — keksdose adds
+     * `shadow-sm` to each disc on the receipt preview by hand. On a joined group the
+     * frame is filled and shadowed; on a gapped one, each member.
+     */
+    elevated?: boolean;
 }
 /**
  * Adjacent `Button`s or `IconButton`s drawn as one joined control: a single frame,
@@ -21,6 +40,42 @@ interface ButtonGroupProps extends Omit<ComponentPropsWithoutRef<"div">, "role">
  * roving, and every member keeps its own tab stop, as plain adjacent buttons do.
  * For one-of-many selection use `ToggleGroup`, which has the radio semantics.
  */
-declare function ButtonGroup({ orientation, className, ...rest }: ButtonGroupProps): react.JSX.Element;
+declare function ButtonGroup({ orientation, variant, elevated, className, ...rest }: ButtonGroupProps): react.JSX.Element;
+/** What {@link ButtonGroupLinkProps.renderLink} is handed. Spread it onto your router's
+ *  link, mapping `href` — `renderLink={({ href, ...p }) => <Link to={href} {...p} />}`. */
+interface ButtonGroupLinkRenderProps {
+    href: string;
+    /** The button look — keep it, or the member is a bare link in the frame. */
+    className: string;
+    children: ReactNode;
+    ref?: Ref<HTMLAnchorElement>;
+    "aria-current"?: "page";
+    onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+    [key: `aria-${string}`]: string | boolean | number | undefined;
+    [key: `data-${string}`]: unknown;
+}
+interface ButtonGroupLinkProps extends Omit<ComponentPropsWithoutRef<"a">, "href" | "className" | "children"> {
+    href: string;
+    /** The {@link Button} variant it looks like. Default `secondary`, the usual member. */
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    /** The member for the page you are on: `aria-current="page"` and the "on" look of a
+     *  pressed member, so a link row reads as a segmented switch between pages. */
+    current?: boolean;
+    /** Render through your router's `Link` — see {@link ButtonGroupLinkRenderProps}. */
+    renderLink?: (props: ButtonGroupLinkRenderProps) => ReactElement;
+    className?: string;
+    children: ReactNode;
+    ref?: Ref<HTMLAnchorElement>;
+}
+/**
+ * A {@link ButtonGroup} member that navigates: a link drawn as a {@link Button}, so it
+ * joins the frame like one. A group mixing actions and pages — "Export" beside "Open
+ * report" — had to either make the page a button with an `onClick` navigate (no
+ * middle-click, no "open in new tab", no link semantics) or style an `<a>` whose
+ * corners the group did not know about. Plain `<a>` by default; `renderLink` for the
+ * router's `Link`, the kit's usual shape (`Chip`, `MenuItem`, `StatTile`).
+ */
+declare function ButtonGroupLink({ href, variant, size, current, renderLink, className, children, ...rest }: ButtonGroupLinkProps): react.JSX.Element;
 
-export { ButtonGroup, type ButtonGroupProps };
+export { ButtonGroup, ButtonGroupLink, type ButtonGroupLinkProps, type ButtonGroupLinkRenderProps, type ButtonGroupProps };

package/dist/components/button-group.js

@@ -1,11 +1,13 @@
 "use client";
 import { jsx } from "react/jsx-runtime";
 import { cn } from "../lib/cn.js";
+import { buttonClasses } from "./ui.js";
 const JOINED_COMMON = cn(
   "inline-flex rounded-md border border-[var(--border)]",
   // The group draws the frame; each member gives up its own border, radius and shadow.
   "[&>*]:rounded-none [&>*]:border-0 [&>*]:shadow-none",
   "[&>*>button]:rounded-none [&>*>button]:border-0 [&>*>button]:shadow-none",
+  "[&>*>a]:rounded-none [&>*>a]:border-0 [&>*>a]:shadow-none",
   "[&>*]:border-[var(--border)]",
   // A focused member rises above its neighbours so its ring is not painted over by
   // the next one's background.
@@ -20,7 +22,8 @@ const JOINED = {
     "flex-row items-stretch",
     "[&>*:not(:first-child)]:border-s",
     "[&>:first-child]:rounded-s-md [&>:last-child]:rounded-e-md",
-    "[&>:first-child>button]:rounded-s-md [&>:last-child>button]:rounded-e-md"
+    "[&>:first-child>button]:rounded-s-md [&>:last-child>button]:rounded-e-md",
+    "[&>:first-child>a]:rounded-s-md [&>:last-child>a]:rounded-e-md"
   ),
   // The block axis is top-to-bottom in both reading directions, so top/bottom are
   // already the logical edges here.
@@ -29,21 +32,69 @@ const JOINED = {
     "flex-col items-stretch",
     "[&>*:not(:first-child)]:border-t",
     "[&>:first-child]:rounded-t-md [&>:last-child]:rounded-b-md",
-    "[&>:first-child>button]:rounded-t-md [&>:last-child>button]:rounded-b-md"
+    "[&>:first-child>button]:rounded-t-md [&>:last-child>button]:rounded-b-md",
+    "[&>:first-child>a]:rounded-t-md [&>:last-child>a]:rounded-b-md"
   )
 };
-function ButtonGroup({ orientation = "horizontal", className, ...rest }) {
+const GAPPED = {
+  horizontal: "inline-flex flex-row items-center gap-1",
+  vertical: "inline-flex flex-col items-center gap-1"
+};
+const ELEVATED_JOINED = "bg-[var(--bg-surface)] shadow-lg";
+const ELEVATED_GAPPED = "[&>button]:shadow-md [&>a]:shadow-md [&>*>button]:shadow-md [&>*>a]:shadow-md";
+function ButtonGroup({
+  orientation = "horizontal",
+  variant = "joined",
+  elevated = false,
+  className,
+  ...rest
+}) {
+  const joined = variant === "joined";
   return /* @__PURE__ */ jsx(
     "div",
     {
       ...rest,
       role: "group",
       "data-orientation": orientation,
-      className: cn(JOINED[orientation], className)
+      "data-variant": variant,
+      className: cn(
+        joined ? JOINED[orientation] : GAPPED[orientation],
+        elevated && (joined ? ELEVATED_JOINED : ELEVATED_GAPPED),
+        className
+      )
     }
   );
 }
+const LINK_CURRENT = "bg-[var(--brand-bg)] text-[var(--brand)] hover:bg-[var(--brand-bg-hover)]";
+function ButtonGroupLink({
+  href,
+  variant = "secondary",
+  size,
+  current = false,
+  renderLink,
+  className,
+  children,
+  ...rest
+}) {
+  const props = {
+    ...rest,
+    href,
+    "aria-current": current ? "page" : void 0,
+    className: buttonClasses(variant, { size, className: cn(current && LINK_CURRENT, className) }),
+    children
+  };
+  if (renderLink) return /* @__PURE__ */ jsx(RenderedGroupLink, { render: renderLink, ...props });
+  const { children: content, ...anchor } = props;
+  return /* @__PURE__ */ jsx("a", { ...anchor, children: content });
+}
+function RenderedGroupLink({
+  render,
+  ...props
+}) {
+  return render(props);
+}
 export {
-  ButtonGroup
+  ButtonGroup,
+  ButtonGroupLink
 };
 //# sourceMappingURL=button-group.js.map

package/dist/components/button-group.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/button-group.tsx"],"sourcesContent":["import type { ComponentPropsWithoutRef } from \"react\";\nimport { cn } from \"../lib/cn\";\n\n// Every class below is spelled out in full rather than assembled from parts: the\n// consumer's Tailwind build finds classes by scanning this package's source as text,\n// and a class that exists only after a template literal runs is never generated.\n//\n// Each rule is written twice, once for a direct child and once for a `<button>` one\n// level down. The second is for a Tooltip-wrapped IconButton — the map zoom's + and −\n// both carry a tooltip — where the direct child is the tooltip's wrapper span and the\n// button that draws the border and the corners sits inside it.\nconst JOINED_COMMON = cn(\n  \"inline-flex rounded-md border border-[var(--border)]\",\n  // The group draws the frame; each member gives up its own border, radius and shadow.\n  \"[&>*]:rounded-none [&>*]:border-0 [&>*]:shadow-none\",\n  \"[&>*>button]:rounded-none [&>*>button]:border-0 [&>*>button]:shadow-none\",\n  \"[&>*]:border-[var(--border)]\",\n  // A focused member rises above its neighbours so its ring is not painted over by\n  // the next one's background.\n  \"[&>*]:relative [&>*:focus-within]:z-10\",\n);\n\nconst JOINED: Record<\"horizontal\" | \"vertical\", string> = {\n  // Logical edges and corners throughout (`border-s`, `rounded-s-*`), so in RTL the\n  // first member sits on the right with the right-hand corners rounded — the physical\n  // pair would round the outside of the last button and square off the first.\n  horizontal: cn(\n    JOINED_COMMON,\n    \"flex-row items-stretch\",\n    \"[&>*:not(:first-child)]:border-s\",\n    \"[&>:first-child]:rounded-s-md [&>:last-child]:rounded-e-md\",\n    \"[&>:first-child>button]:rounded-s-md [&>:last-child>button]:rounded-e-md\",\n  ),\n  // The block axis is top-to-bottom in both reading directions, so top/bottom are\n  // already the logical edges here.\n  vertical: cn(\n    JOINED_COMMON,\n    \"flex-col items-stretch\",\n    \"[&>*:not(:first-child)]:border-t\",\n    \"[&>:first-child]:rounded-t-md [&>:last-child]:rounded-b-md\",\n    \"[&>:first-child>button]:rounded-t-md [&>:last-child>button]:rounded-b-md\",\n  ),\n};\n\nexport interface ButtonGroupProps extends Omit<ComponentPropsWithoutRef<\"div\">, \"role\"> {\n  /** `horizontal` (default): side by side, in reading order. `vertical`: stacked —\n   *  the map's zoom + over −. */\n  orientation?: \"horizontal\" | \"vertical\";\n}\n\n/**\n * Adjacent `Button`s or `IconButton`s drawn as one joined control: a single frame,\n * hairline dividers between the members, rounded only at the outer corners.\n *\n * keksdose asked for it twice — \"collapse all / expand all\" above its category\n * tree, and the + and − of its map zoom — both hand-built with negative margins and\n * physical `rounded-l` / `rounded-r`, which came out inside-out under `dir=\"rtl\"`.\n *\n * `role=\"group\"` with a name: a reader then introduces the pair as \"Zoom, group\"\n * before reading \"Zoom in\", which is what tells a listener that the next button\n * belongs with this one. Pass `aria-label` (or `aria-labelledby`); a group with no\n * name is one more unlabelled wrapper. It is NOT a toolbar — it adds no arrow-key\n * roving, and every member keeps its own tab stop, as plain adjacent buttons do.\n * For one-of-many selection use `ToggleGroup`, which has the radio semantics.\n */\nexport function ButtonGroup({ orientation = \"horizontal\", className, ...rest }: ButtonGroupProps) {\n  return (\n    <div\n      {...rest}\n      role=\"group\"\n      data-orientation={orientation}\n      className={cn(JOINED[orientation], className)}\n    />\n  );\n}\n"],"mappings":";AAmEI;AAlEJ,SAAS,UAAU;AAUnB,MAAM,gBAAgB;AAAA,EACpB;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA,EAGA;AACF;AAEA,MAAM,SAAoD;AAAA;AAAA;AAAA;AAAA,EAIxD,YAAY;AAAA,IACV;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA;AAAA;AAAA,EAGA,UAAU;AAAA,IACR;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAuBO,SAAS,YAAY,EAAE,cAAc,cAAc,WAAW,GAAG,KAAK,GAAqB;AAChG,SACE;AAAA,IAAC;AAAA;AAAA,MACE,GAAG;AAAA,MACJ,MAAK;AAAA,MACL,oBAAkB;AAAA,MAClB,WAAW,GAAG,OAAO,WAAW,GAAG,SAAS;AAAA;AAAA,EAC9C;AAEJ;","names":[]}
+{"version":3,"sources":["../../src/components/button-group.tsx"],"sourcesContent":["import type { ComponentPropsWithoutRef, MouseEvent, ReactElement, ReactNode, Ref } from \"react\";\nimport { cn } from \"../lib/cn\";\nimport { buttonClasses, type ButtonSize, type ButtonVariant } from \"./ui\";\n\n// Every class below is spelled out in full rather than assembled from parts: the\n// consumer's Tailwind build finds classes by scanning this package's source as text,\n// and a class that exists only after a template literal runs is never generated.\n//\n// Each rule is written twice, once for a direct child and once for a `<button>` one\n// level down. The second is for a Tooltip-wrapped IconButton — the map zoom's + and −\n// both carry a tooltip — where the direct child is the tooltip's wrapper span and the\n// button that draws the border and the corners sits inside it. The same again for an\n// `<a>` one level down: a router link member (see {@link ButtonGroupLink}) under a\n// tooltip. A bare link is a direct child and needs nothing extra.\nconst JOINED_COMMON = cn(\n  \"inline-flex rounded-md border border-[var(--border)]\",\n  // The group draws the frame; each member gives up its own border, radius and shadow.\n  \"[&>*]:rounded-none [&>*]:border-0 [&>*]:shadow-none\",\n  \"[&>*>button]:rounded-none [&>*>button]:border-0 [&>*>button]:shadow-none\",\n  \"[&>*>a]:rounded-none [&>*>a]:border-0 [&>*>a]:shadow-none\",\n  \"[&>*]:border-[var(--border)]\",\n  // A focused member rises above its neighbours so its ring is not painted over by\n  // the next one's background.\n  \"[&>*]:relative [&>*:focus-within]:z-10\",\n);\n\nconst JOINED: Record<\"horizontal\" | \"vertical\", string> = {\n  // Logical edges and corners throughout (`border-s`, `rounded-s-*`), so in RTL the\n  // first member sits on the right with the right-hand corners rounded — the physical\n  // pair would round the outside of the last button and square off the first.\n  horizontal: cn(\n    JOINED_COMMON,\n    \"flex-row items-stretch\",\n    \"[&>*:not(:first-child)]:border-s\",\n    \"[&>:first-child]:rounded-s-md [&>:last-child]:rounded-e-md\",\n    \"[&>:first-child>button]:rounded-s-md [&>:last-child>button]:rounded-e-md\",\n    \"[&>:first-child>a]:rounded-s-md [&>:last-child>a]:rounded-e-md\",\n  ),\n  // The block axis is top-to-bottom in both reading directions, so top/bottom are\n  // already the logical edges here.\n  vertical: cn(\n    JOINED_COMMON,\n    \"flex-col items-stretch\",\n    \"[&>*:not(:first-child)]:border-t\",\n    \"[&>:first-child]:rounded-t-md [&>:last-child]:rounded-b-md\",\n    \"[&>:first-child>button]:rounded-t-md [&>:last-child>button]:rounded-b-md\",\n    \"[&>:first-child>a]:rounded-t-md [&>:last-child>a]:rounded-b-md\",\n  ),\n};\n\n// `gapped`: the members keep their own shape — round overlay discs, each its own\n// border and radius — and sit apart. Nothing is stripped, so there is nothing to\n// restore per edge, and the gap is logical by nature.\nconst GAPPED: Record<\"horizontal\" | \"vertical\", string> = {\n  horizontal: \"inline-flex flex-row items-center gap-1\",\n  vertical: \"inline-flex flex-col items-center gap-1\",\n};\n\n// `elevated`, joined: the frame itself floats — a filled surface under the members (a\n// ghost member would otherwise show the content through it) and the shadow of a\n// control lifted over the page.\nconst ELEVATED_JOINED = \"bg-[var(--bg-surface)] shadow-lg\";\n// `elevated`, gapped: there is no frame, so each disc carries the shadow. Aimed at the\n// control, not the tooltip's square wrapper span, whose shadow would be a box round a\n// round disc.\nconst ELEVATED_GAPPED =\n  \"[&>button]:shadow-md [&>a]:shadow-md [&>*>button]:shadow-md [&>*>a]:shadow-md\";\n\nexport interface ButtonGroupProps extends Omit<ComponentPropsWithoutRef<\"div\">, \"role\"> {\n  /** `horizontal` (default): side by side, in reading order. `vertical`: stacked —\n   *  the map's zoom + over −. */\n  orientation?: \"horizontal\" | \"vertical\";\n  /**\n   * `joined` (default): one frame, hairline dividers, outer corners rounded. `gapped`:\n   * separate controls with a small gap, each keeping its own shape — the overlay\n   * discs of keksdose's receipt preview zoom (scan-file-preview.tsx:362, the − and +\n   * `IconButton variant=\"overlay\"` in a hand-made `flex gap-1`), where a joined frame\n   * would be a box drawn over the photo.\n   */\n  variant?: \"joined\" | \"gapped\";\n  /**\n   * Float it: a surface with a shadow, for a toolbar that sits OVER content (a map's\n   * zoom, a photo's controls) rather than in the page's flow — keksdose adds\n   * `shadow-sm` to each disc on the receipt preview by hand. On a joined group the\n   * frame is filled and shadowed; on a gapped one, each member.\n   */\n  elevated?: boolean;\n}\n\n/**\n * Adjacent `Button`s or `IconButton`s drawn as one joined control: a single frame,\n * hairline dividers between the members, rounded only at the outer corners.\n *\n * keksdose asked for it twice — \"collapse all / expand all\" above its category\n * tree, and the + and − of its map zoom — both hand-built with negative margins and\n * physical `rounded-l` / `rounded-r`, which came out inside-out under `dir=\"rtl\"`.\n *\n * `role=\"group\"` with a name: a reader then introduces the pair as \"Zoom, group\"\n * before reading \"Zoom in\", which is what tells a listener that the next button\n * belongs with this one. Pass `aria-label` (or `aria-labelledby`); a group with no\n * name is one more unlabelled wrapper. It is NOT a toolbar — it adds no arrow-key\n * roving, and every member keeps its own tab stop, as plain adjacent buttons do.\n * For one-of-many selection use `ToggleGroup`, which has the radio semantics.\n */\nexport function ButtonGroup({\n  orientation = \"horizontal\",\n  variant = \"joined\",\n  elevated = false,\n  className,\n  ...rest\n}: ButtonGroupProps) {\n  const joined = variant === \"joined\";\n  return (\n    <div\n      {...rest}\n      role=\"group\"\n      data-orientation={orientation}\n      data-variant={variant}\n      className={cn(\n        joined ? JOINED[orientation] : GAPPED[orientation],\n        elevated && (joined ? ELEVATED_JOINED : ELEVATED_GAPPED),\n        className,\n      )}\n    />\n  );\n}\n\n/** What {@link ButtonGroupLinkProps.renderLink} is handed. Spread it onto your router's\n *  link, mapping `href` — `renderLink={({ href, ...p }) => <Link to={href} {...p} />}`. */\nexport interface ButtonGroupLinkRenderProps {\n  href: string;\n  /** The button look — keep it, or the member is a bare link in the frame. */\n  className: string;\n  children: ReactNode;\n  ref?: Ref<HTMLAnchorElement>;\n  \"aria-current\"?: \"page\";\n  onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;\n  [key: `aria-${string}`]: string | boolean | number | undefined;\n  [key: `data-${string}`]: unknown;\n}\n\nexport interface ButtonGroupLinkProps extends Omit<ComponentPropsWithoutRef<\"a\">, \"href\" | \"className\" | \"children\"> {\n  href: string;\n  /** The {@link Button} variant it looks like. Default `secondary`, the usual member. */\n  variant?: ButtonVariant;\n  size?: ButtonSize;\n  /** The member for the page you are on: `aria-current=\"page\"` and the \"on\" look of a\n   *  pressed member, so a link row reads as a segmented switch between pages. */\n  current?: boolean;\n  /** Render through your router's `Link` — see {@link ButtonGroupLinkRenderProps}. */\n  renderLink?: (props: ButtonGroupLinkRenderProps) => ReactElement;\n  className?: string;\n  children: ReactNode;\n  ref?: Ref<HTMLAnchorElement>;\n}\n\nconst LINK_CURRENT = \"bg-[var(--brand-bg)] text-[var(--brand)] hover:bg-[var(--brand-bg-hover)]\";\n\n/**\n * A {@link ButtonGroup} member that navigates: a link drawn as a {@link Button}, so it\n * joins the frame like one. A group mixing actions and pages — \"Export\" beside \"Open\n * report\" — had to either make the page a button with an `onClick` navigate (no\n * middle-click, no \"open in new tab\", no link semantics) or style an `<a>` whose\n * corners the group did not know about. Plain `<a>` by default; `renderLink` for the\n * router's `Link`, the kit's usual shape (`Chip`, `MenuItem`, `StatTile`).\n */\nexport function ButtonGroupLink({\n  href,\n  variant = \"secondary\",\n  size,\n  current = false,\n  renderLink,\n  className,\n  children,\n  ...rest\n}: ButtonGroupLinkProps) {\n  const props: ButtonGroupLinkRenderProps = {\n    ...rest,\n    href,\n    \"aria-current\": current ? \"page\" : undefined,\n    className: buttonClasses(variant, { size, className: cn(current && LINK_CURRENT, className) }),\n    children,\n  };\n  if (renderLink) return <RenderedGroupLink render={renderLink} {...props} />;\n  const { children: content, ...anchor } = props;\n  return <a {...anchor}>{content}</a>;\n}\n\n/** Calls `renderLink` as a component, so the router link's hooks are its own. */\nfunction RenderedGroupLink({\n  render,\n  ...props\n}: ButtonGroupLinkRenderProps & { render: (props: ButtonGroupLinkRenderProps) => ReactElement }) {\n  return render(props);\n}\n"],"mappings":";AAiHI;AAhHJ,SAAS,UAAU;AACnB,SAAS,qBAA0D;AAYnE,MAAM,gBAAgB;AAAA,EACpB;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA,EAGA;AACF;AAEA,MAAM,SAAoD;AAAA;AAAA;AAAA;AAAA,EAIxD,YAAY;AAAA,IACV;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA;AAAA;AAAA,EAGA,UAAU;AAAA,IACR;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAKA,MAAM,SAAoD;AAAA,EACxD,YAAY;AAAA,EACZ,UAAU;AACZ;AAKA,MAAM,kBAAkB;AAIxB,MAAM,kBACJ;AAsCK,SAAS,YAAY;AAAA,EAC1B,cAAc;AAAA,EACd,UAAU;AAAA,EACV,WAAW;AAAA,EACX;AAAA,EACA,GAAG;AACL,GAAqB;AACnB,QAAM,SAAS,YAAY;AAC3B,SACE;AAAA,IAAC;AAAA;AAAA,MACE,GAAG;AAAA,MACJ,MAAK;AAAA,MACL,oBAAkB;AAAA,MAClB,gBAAc;AAAA,MACd,WAAW;AAAA,QACT,SAAS,OAAO,WAAW,IAAI,OAAO,WAAW;AAAA,QACjD,aAAa,SAAS,kBAAkB;AAAA,QACxC;AAAA,MACF;AAAA;AAAA,EACF;AAEJ;AA+BA,MAAM,eAAe;AAUd,SAAS,gBAAgB;AAAA,EAC9B;AAAA,EACA,UAAU;AAAA,EACV;AAAA,EACA,UAAU;AAAA,EACV;AAAA,EACA;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAAyB;AACvB,QAAM,QAAoC;AAAA,IACxC,GAAG;AAAA,IACH;AAAA,IACA,gBAAgB,UAAU,SAAS;AAAA,IACnC,WAAW,cAAc,SAAS,EAAE,MAAM,WAAW,GAAG,WAAW,cAAc,SAAS,EAAE,CAAC;AAAA,IAC7F;AAAA,EACF;AACA,MAAI,WAAY,QAAO,oBAAC,qBAAkB,QAAQ,YAAa,GAAG,OAAO;AACzE,QAAM,EAAE,UAAU,SAAS,GAAG,OAAO,IAAI;AACzC,SAAO,oBAAC,OAAG,GAAG,QAAS,mBAAQ;AACjC;AAGA,SAAS,kBAAkB;AAAA,EACzB;AAAA,EACA,GAAG;AACL,GAAiG;AAC/F,SAAO,OAAO,KAAK;AACrB;","names":[]}

package/dist/components/calculator.d.ts

@@ -2,6 +2,7 @@ import * as react from 'react';
 import { CalculatorLabels } from '../i18n/kit-labels.js';
 import './data-table-labels.js';
 import './mini-calendar.js';
+import './calendar-heatmap.js';
 import './popover.js';
 import './chip.js';
 import 'lucide-react';
@@ -9,6 +10,7 @@ import './field-sync.js';
 import './ui.js';
 import './tooltip.js';
 import '../hooks/use-anchored-rect.js';
+import '../lib/clipping.js';
 import '../wizard/types.js';
 import '../tour/tour.js';
 import '../search/command-palette.js';

package/dist/components/calendar-heatmap.d.ts

@@ -0,0 +1,124 @@
+import * as react from 'react';
+import { ComponentPropsWithoutRef, ReactNode } from 'react';
+import { WeekDay } from './mini-calendar.js';
+
+/**
+ * Every string the heatmap speaks — the `calendarHeatmap` namespace of
+ * `<UiKitProvider labels>`, overridable per instance through `labels`. Dates and
+ * values arrive already formatted (in `locale`, and through `formatValue`), so the
+ * functions only arrange them.
+ */
+interface CalendarHeatmapLabels {
+    /** Accessible name of the grid. */
+    grid: string;
+    /**
+     * One day: its accessible name, and the tooltip unless `tooltip` is given. `date`
+     * is the whole date in `locale` ("Monday, 14 September 2026"), `value` the day's
+     * figure through `formatValue`.
+     */
+    day: (date: string, value: string) => string;
+    /** The two ends of the legend's scale. */
+    less: string;
+    more: string;
+    /** `maxDays` cut the window: how many of its earliest days are not drawn. */
+    truncated: (count: number) => string;
+}
+/** English defaults, exported as the `calendarHeatmap` namespace of `UiKitLabels`. */
+declare const DEFAULT_CALENDAR_HEATMAP_LABELS: CalendarHeatmapLabels;
+/** One day's figure. Several entries for one date are added up. */
+interface CalendarHeatmapDatum {
+    /** "YYYY-MM-DD". */
+    date: string;
+    value: number;
+}
+/** What `tooltip` is told about the day under the pointer. */
+interface CalendarHeatmapDay {
+    iso: string;
+    date: Date;
+    /** The day's figure; `0` when `data` has no entry for it (see `hasData`). */
+    value: number;
+    hasData: boolean;
+    /** `0` = empty … `levels` = the busiest. */
+    level: number;
+    /** The whole date in `locale`. */
+    formattedDate: string;
+    /** `value` through `formatValue`. */
+    formattedValue: string;
+}
+/**
+ * `onSelect` is omitted from the `<div>` attributes for the reason `MiniCalendar` gives:
+ * the DOM event of that name is a text-selection event, and this one answers with a date.
+ */
+interface CalendarHeatmapProps extends Omit<ComponentPropsWithoutRef<"div">, "onSelect"> {
+    data: readonly CalendarHeatmapDatum[];
+    /** The window, inclusive, as "YYYY-MM-DD". */
+    from: string;
+    to: string;
+    /**
+     * `"weeks"` (default): the contribution-graph shape — one COLUMN per week, the
+     * weekdays down the side, month names along the top; a year fits in ~53 small
+     * squares and scrolls sideways where it does not. `"month"`: a 7-column calendar
+     * with day numbers in large square cells, for a single month on a phone (switch on
+     * `useMediaQuery` and narrow `from`/`to` to the month).
+     */
+    layout?: "weeks" | "month";
+    /** The day shown as selected ("YYYY-MM-DD"). */
+    selected?: string;
+    /** Makes each day a button: a click (or Enter/Space) selects it — a drill-down into
+     *  that day's rows, a day panel. Without it the days are focusable but inert. */
+    onSelect?: (iso: string) => void;
+    /** How a value is written in the tooltip and the day's name. Default: `Intl.NumberFormat`
+     *  in `locale`. Pass a currency formatter for money. */
+    formatValue?: (value: number) => string;
+    /** Tooltip content for a day. Default: `labels.day(date, value)`. */
+    tooltip?: (day: CalendarHeatmapDay) => ReactNode;
+    /**
+     * Tag each tooltip `data-private`, so the host's demo-mode rule blurs it (the
+     * attribute `Tooltip redact` and `StatTile sensitive` carry). ON by default: a heatmap
+     * is almost always the user's own figures, and a missing tag is silent — the grid
+     * looks anonymous and the bubble spells the amount out on hover.
+     */
+    sensitive?: boolean;
+    /** The value that reaches the top of the scale. Default: the largest value ON SCREEN,
+     *  so a peak outside the window does not wash the drawn days out to empty. */
+    max?: number;
+    /** How many non-empty intensity steps. Default 4. */
+    levels?: number;
+    /** The scale's colour, as any CSS colour. Default `var(--brand)`; each step is this
+     *  mixed into `--bg-surface`, so the ramp follows the theme. */
+    color?: string;
+    /**
+     * The most days to draw. A longer window keeps its LATEST `maxDays` and says how many
+     * it left out (`labels.truncated`) rather than silently ending. Default: no cap.
+     */
+    maxDays?: number;
+    /** Draw the Less … More legend. Default `true`. */
+    legend?: boolean;
+    /** BCP 47 tag for the dates, month and weekday names and numbers. */
+    locale?: string;
+    /** `0` = Sunday … `6` = Saturday. Default: the provider's, else the locale's. */
+    weekStartsOn?: WeekDay;
+    labels?: Partial<CalendarHeatmapLabels>;
+    className?: string;
+}
+/** The step a value falls on: 0 for nothing, else 1…levels by its share of `max`. */
+declare function heatmapLevel(value: number, max: number, levels: number): number;
+/**
+ * Days as a grid of shaded squares — how much happened on each, at a glance
+ * (a contribution graph, a spending calendar).
+ *
+ * **Every day is a cell you can reach.** The grid is a `role="grid"` with ONE tab
+ * stop (the roving tabindex, as in `MiniCalendar`); the arrows move by the grid's own
+ * geometry — in `"weeks"` ↑/↓ are the previous/next day and ←/→ a week, in `"month"`
+ * the other way round, mirrored in RTL — PageUp/PageDown move a month and Home/End go
+ * to the window's first/last day. Each cell is named with its whole date AND its value,
+ * because the colour is not something a screen reader can say, and carries
+ * `data-day="YYYY-MM-DD"` as its identity for tests and for the host.
+ *
+ * The tooltip is portalled (a year of squares always sits in a sideways scroller) and
+ * `data-private` unless `sensitive={false}`. Cell size in `"weeks"` is the CSS variable
+ * `--heatmap-cell` (default `0.75rem`): `style={{ "--heatmap-cell": "1rem" }}`.
+ */
+declare function CalendarHeatmap({ data, from, to, layout, selected, onSelect, formatValue: formatValueProp, tooltip, sensitive, max: maxProp, levels, color, maxDays, legend, locale: localeProp, weekStartsOn, labels: labelsProp, className, "aria-label": ariaLabel, ...rest }: CalendarHeatmapProps): react.JSX.Element;
+
+export { CalendarHeatmap, type CalendarHeatmapDatum, type CalendarHeatmapDay, type CalendarHeatmapLabels, type CalendarHeatmapProps, DEFAULT_CALENDAR_HEATMAP_LABELS, heatmapLevel };