index-knowledge

### Minor Changes - da41be5: Update the bundled Base UI dependency to version 1.8.0 and expose its Combobox item collection and functional Toast update APIs. - 9ad4c57: Add `ButtonGroup` component for joining a small set of tightly-coupled buttons into a single control — most commonly a split button (a primary action next to a dropdown trigger). Handles layout only: children keep their own variant, size, and shape while the group flattens inner corners and overlaps borders so the buttons share one seam. Renders `role="group"`. For grouping multiple independent buttons or inputs, use `Toolbar` instead. - d0b18d6: Add sidebar open-change completion callbacks. - cd119ab: Add the TagInput component for creating and removing free-form values. - 5d19dee: Add `InlineCopyText`, a compact borderless copy control for short values in dense interfaces and table cells. It accepts string or rich children, Text typography props excluding heading variants, an explicit copied value for rich content, localized accessible labels, inline success feedback, and hover or focus icon reveal. - 77489b5: Add an optional `yAxisMinInterval` prop to `TimeseriesChart` for discrete data. - 6989681: Add support for footer text below `TimeseriesChart` tooltip values. - 06321ce: Add a strict responsive LayerDialog component with automatic dismissal composition, alert-dialog semantics, mobile drawer behavior, and application-wide defaults for its built-in close and cancel copy through `KumoLocaleProvider`. - d4a3e71: Add `GlobeMap`, an SVG orthographic globe with boundary-free hatched land, horizon-faded geographic markers, optional geographic guides, pointer and keyboard rotation, automatic rotation, Kumo-themed tooltips, and no WebGL or ECharts requirement. ### Patch Changes - de80043: Reset the native fieldset padding in radio and checkbox groups. - 1175556: Refine Empty state typography and balance description text when it wraps. - 5b1e222: Support nested LayerDialog drawers with independently layered backdrops and responsive mobile actions. - 9c970e3: Add a plain CodeHighlighted variant for frameless, padding-free code blocks with a correctly positioned copy button. - cfffa4e: Document app-root CSS isolation for reliable stacking of portaled components. - 6e7bd82: Update formatting for Vite+ 0.3.1. - 78d05b6: Use the up/down double chevron in Combobox value and input triggers to match Select. - 86029e4: Add a visual regression contract for truncating text in default Tooltip triggers.

### Patch Changes - 36fc155: Add `scrollItemIntoView()` to preserve the position of visible sidebar items while honoring alignment for offscreen items.

### Patch Changes - 7d5241d: Allow default Tooltip trigger children to control their line height, preventing inherited text from being clipped.

### Minor Changes - 4066307: Add unknown-total pagination support through `hasNextPage`. - f74936f: Add `Toolbar.Link`, which renders a `LinkButton` with toolbar sizing, styling, and keyboard navigation. ### Patch Changes - d004940: Position dialogs near the top of the viewport instead of vertically centering them. - 8f0a1f0: Use the elevated surface color for even rows in the default Table variant. - 1ede8bf: fix(select): align the trigger surface with form controls Select triggers now use `bg-kumo-control`, including their open and disabled states, so they match Input, Combobox, and the rest of the form-control family. Consumer background classes can still override the default without using `!important`. The popup remains on the floating `bg-kumo-base` surface. - 8482c50: fix(select): anchor the popup below the trigger and expose placement props `Select.Positioner` relied on Base UI's `alignItemWithTrigger` default (`true`), which overlays the popup on the trigger so the selected option's text lands on the trigger's value text, emulating a native ``. Options always render at `text-base`, so on `xs`/`sm` triggers the popup was much taller than its anchor, and Base UI's compensating shift detached it from the trigger — on `xs` it overhung by 12.5px above and 45.5px below and sat 8px to the left, covering adjacent content. The popup now prefers `bottom` placement and is offset from the trigger, with Base UI's collision avoidance still flipping it automatically when the preferred side lacks space. Placement is configurable: | prop | default | notes | | ---------------------- | ---------- | ------------------------------------------------------------- | | `side` | `"bottom"` | preferred side; still flips automatically on collision | | `sideOffset` | `4` | gap between trigger and popup, matching Combobox/Autocomplete | | `align` | `"start"` | alignment along the trigger edge | | `alignOffset` | — | additional offset along the alignment axis | | `alignItemWithTrigger` | `false` | opt back in to the native `` overlay | The remaining Base UI Positioner controls are also forwarded unchanged: `anchor`, `arrowPadding`, `positionMethod`, `collisionAvoidance`, `collisionBoundary`, `collisionPadding`, `sticky`, and `disableAnchorTracking`. The popup also now tracks the trigger width via `min-w-(--anchor-width)` instead of `min-w-[calc(var(--anchor-width)+3px)]`, which existed to visually offset the old item-alignment shift. - 7526a6a: Allow non-heading Text variants to inherit line height from their surrounding context. - b094a5a: Make `Combobox.Input` sit flush with the top and sides of `Combobox.Content` and remove its bottom corner rounding. - 20b7880: Reduce the trailing inset for buttons inside large InputGroup addons.

### Minor Changes - 716e5b8: Add the `Text` `heading` variant with a 16px semibold default and a 20px `size="lg"` option. The variant defaults to a `span`, so callers choose heading semantics explicitly with `as`. Deprecate the numbered `heading1`, `heading2`, and `heading3` variants. ### Patch Changes - d7a7a35: `Collapsible.DefaultTrigger` now uses `text-kumo-default` (neutral) with `font-medium` instead of the blue `text-kumo-link` color. - 0db4f66: deprecate `MenuBar` in favor of segmented `Tabs` - mark the `MenuBar` component (and its exports) as `@deprecated`; it will be removed in a future release - new usage should prefer `Tabs` with `variant="segmented"` (the default `Tabs` variant) - the runtime behaviour of `MenuBar` is unchanged for existing consumers - remove the `MenuBar` documentation page and demos from the docs site - c64183b: Fix Toast background clipping the ring outline at the corners — the inner background layer's radius (11px) was smaller than the root's `rounded-xl` (12px), painting over the ring at the corners. Matched them up. - ef13cb4: Restore disabled and loading state handling for `Toolbar.Button` so disabled controls expose the correct semantics and cannot be activated. - 51d0f03: Normalize shadows and outlines on tip-style overlays (Popover, Tooltip, ClipboardText, Chart tooltip). - Drop the `shadow-kumo-tip-shadow` color override so shadows use Tailwind's default translucent black instead of an opaque light-gray in light mode. - Tune shadow sizes: Popover, Tooltip, ClipboardText tooltip, and Chart tooltip use `shadow-md`; ClipboardText's "Copied" toast keeps `shadow-lg` to match the Toast component. - Switch these overlays from `outline-kumo-fill` to `outline-kumo-line`, matching every other floating surface (Dropdown, Select, Combobox, Dialog, etc.). - Rename `kumo-tip-shadow` → `kumo-arrow-edge` and `kumo-tip-stroke` → `kumo-arrow-stroke`. The tokens draw the border on Popover/Tooltip arrow SVGs, not a box shadow. Both now resolve to `kumo-line`, so the arrow border aligns with the popup outline in both modes. - d586bf3: Add `scrollToItem(id, options?)` to `useSidebar()` for imperatively scrolling a nav item into the sidebar viewport. Tag items with the new `itemId` prop on `Sidebar.MenuButton` or `Sidebar.MenuItem`. Options: - `align`: `"start" | "center" | "end" | "auto"` (default `"auto"` — no-op if the item is already visible; otherwise scroll the minimum distance). - `behavior`: `"auto" | "smooth"` (default `"auto"` — instant, best for cross-app landings so users don't watch the sidebar animate on entry). `prefers-reduced-motion` forces `"auto"`. Scrolls only the sidebar viewport (never the document) and works with `Sidebar.SlidingViews`: items register with the provider via an internal map, so `scrollToItem` walks up from the target to find its owning viewport rather than querying the DOM.

### Minor Changes - aa6edff: Add icon support to filled Badge variants through the `icon` prop, add linked-badge hover styles, and use the base surface background for outline badges. ### Patch Changes - bba0f5e: Allow users to select and copy LinkButton text while preserving Button text selection behavior. - c2c8d42: Update Table rows to use borderless, alternating background styling. - 0ad1926: Fix hydration mismatch in the Sidebar's `useIsMobile` hook on SSR frameworks like Next.js. The hook now uses `useSyncExternalStore` with a desktop `getServerSnapshot`, so the server-rendered HTML (desktop ``) hydrates cleanly on mobile viewports before switching to the mobile overlay.

### Minor Changes - 4b9a4dc: Allow Select and Combobox triggers to compose directly with `Toolbar.Button` and `Toolbar.Input` through their `render` props, adding grouped styling and arrow-key focus management while preserving regular `Select.*` and `Combobox.*` APIs. Deprecate Toolbar's configurable `size` prop and size metadata exports. They remain functional for compatibility; omitting `size` continues to use the base size. ### Patch Changes - 65db2e6: Forward link-specific props in Tabs and Sidebar so link-rendered tabs can opt out of native button semantics, and Sidebar link buttons preserve attributes like `aria-current`. - 0c58325: Expose all positioner props on Combobox.Content (`anchor`, `positionMethod`, `collisionAvoidance`, `collisionBoundary`, `collisionPadding`, `sticky`, `disableAnchorTracking`). - 528d5ff: Populate InputArea props in component registry so the docs API reference table renders correctly - 75c3b14: Fix Sidebar peeking state during SlidingViews transitions. - 1d9b588: Fix Tabs overflow controls when tabs are removed and the remaining tabs fit.

### Patch Changes - 188a82c: Remove the elevated chip styling from Tabs overflow scroll controls. - c5ad709: Constrain Tabs overflow controls to segmented tabs and focus the caret target.

### Patch Changes - ff76f30: Update the default collapsible trigger and panel styling. `Collapsible.DefaultPanel` now uses an inner content wrapper so the outer panel can animate height smoothly while clipping overflow during the transition. Consumers applying custom layout or spacing classes directly to `DefaultPanel` may need to move those styles to their content, or use `Collapsible.Panel` for a fully custom layout. - 7468623: Fix `initCatalog` so it actually loads the validation schemas. Previously it triggered a synchronous validation whose "schemas not loaded" error was swallowed, so `await initCatalog(catalog)` could resolve while `hasComponent`, `componentNames`, and the other synchronous catalog APIs still reported no components. It now awaits `loadSchemas()` directly. A failed schema load is also no longer cached: retrying `initCatalog` (or `loadSchemas`) after a transient failure now re-attempts the import instead of returning the stale rejection. - d7639f2: Fix Shiki highlighter lifecycle in `ShikiProvider` and `CodeHighlighted`. `ShikiProvider` no longer re-creates the highlighter when a parent rerender passes an equivalent inline `languages` array — initialization is keyed on the normalized language set. Highlighters are now disposed on unmount and when the engine or language set changes, instead of leaking. `CodeHighlighted` memoizes the highlighted HTML so unrelated rerenders (such as copy-button state changes) no longer re-highlight unchanged code, and initialization errors are logged once instead of on every render. Reinitializing after a failed initialization now clears the stale error state instead of showing it during the retry. - c599590: Reset the Tabs overflow control background so host button styles do not show through the scrim gradient.

### Minor Changes - ff8ad54: Improves Banner contrast and CTA colors, adds compact sizing, and keeps components that consume the updated status tokens visually balanced. - Updated status tokens to improve contrast between Banner backgrounds, text, and CTAs. - Rebalanced Badge status tints, Toast backgrounds, and Command Palette search highlights to correspond with the updated tokens. - Added a new `Banner.Action` CTA compound that builds on `Button` with banner-specific accent styling. It supports `primary` (filled), `secondary` (accent-hued outline on a transparent background), and `ghost` variants. - Added a `size` prop to `Banner` (`"base"` \| `"sm"`); the compact `"sm"` size suits dialogs and other tight spaces and sets its `Banner.Action` children to the `xs` size. - f919182: Improve chart loading states with a static, reduced-motion-aware `TimeseriesChart` skeleton (line and bar variants matching `type`) and a new `loading` prop for `ChartLegend.SmallItem` and `ChartLegend.LargeItem`. - 535d579: Add a `disabled` prop to `LinkButton`. When disabled, it renders a real disabled `` (dropping anchor-only attributes and event handlers) and supports `title` tooltips explaining why the action is unavailable. Also removes stale Storybook references from the README and drops `.stories.tsx` generation from the component scaffolder, since Storybook is no longer set up in this repo. - aae94f1: `LinkButton` now wraps in a Kumo `Tooltip` when a `title` is provided, matching `Button`'s behavior. Previously an enabled `LinkButton` only set a native `title` attribute; it now surfaces the same styled tooltip on hover and focus. - 9e083d2: Add `fullScreenOnMobile` prop to `Sidebar`. When set, the mobile navigation sheet expands to the full viewport instead of leaving a sliver of the page visible, giving nav items comfortable touch targets. The backdrop is suppressed and the divider border dropped, since neither has anything to separate. Defaults to `false`. Also adds `Sidebar.Close`, a ghost button that dismisses the mobile sheet. It is intended for `Sidebar.Header` in full-screen mobile layouts where the backdrop is hidden and there is no adjacent page content to tap. Also fixes `Breadcrumbs.Link` shrinking alongside the current crumb. Flexbox distributed truncation across every crumb, turning the trail into unreadable stubs; ancestors now hold their width so only the current page truncates. - 51aa44c: Add `Sidebar.Loading`, a nav loading skeleton so apps stop hand-rolling their own. It renders nav-item-shaped placeholder rows (icon + label) grouped like the real nav, composed from `SkeletonLine` and matching the `Sidebar.MenuButton` box model so there's no layout shift when the real nav swaps in. Collapse-aware (icon squares only when collapsed) and exposes `role="status"` with a configurable `label`. - 86ee08c: Add `useTableOfContentsActiveId` hook for `TableOfContents` scroll tracking. The `TableOfContents` component is presentational, so consumers had to wire up their own scroll-position tracking. This adds a shared hook: pass the section ids (in document order) and it returns the active section id plus a `selectSection` action for click handling. ```tsx const { activeId, selectSection } = useTableOfContentsActiveId({ ids: headings.map((h) => h.slug), offset: HEADER_HEIGHT, }); ``` - Highlights the topmost section actually in view (via `IntersectionObserver`), offset by an optional fixed-header `offset`; supports custom scroll containers via `root`. - Handles `location.hash` deep links on load and `hashchange` automatically (opt out with `trackHash: false`). - `selectSection` pins a clicked section until scrolling settles, so short sections stay highlighted after a jump. Works on browsers without `scrollend` support. - SSR-safe: all DOM access happens in effects, so it renders under Astro/Next SSR (`activeId` is `null` on the server). The docs site "On this page" table of contents now consumes this hook instead of its own bespoke observer. - 87d1ebc: Ship unminified `dist` output without sourcemaps or declaration maps Consumers' bundlers minify (and tree-shake) the library code anyway, so pre-minifying only obscured the shipped modules, and the declaration maps pointed at source files that aren't published. The package shrinks from ~13.9 MB to ~6.5 MB unpacked, and the code in `node_modules` is now readable. No API or behavior changes; final application bundle sizes are effectively unchanged. ### Patch Changes - fc5e222: Use a string or numeric Button title as the fallback accessible label when the button has no text children. - 8e71b38: Bump Prettier 3.6.2 → 3.9.5 and reformat (Prettier changed e.g. interface heritage-clause wrapping). No functional changes. - 2a463f7: Prevent TimeseriesChart tooltips from following the cursor outside the chart after a browser context menu interaction. - 0f0c44d: ClipboardText: keep the check icon until the last copy click settles, and bump the anchored "Copied" toast (without stacking) when the button is pressed again while it's open. - b171c71: Render Kumo Link actions inline in compact Banners while keeping CTA actions trailing. - 4f0ed75: Fix purple badge token fallback colors to use purple OKLCH values. - 5efe6dd: Add a lint rule that verifies custom components used with `Flow.Node`'s `render` prop forward refs and spread received props. - 32b2168: Keep TimeseriesChart brush-to-zoom active after replacing ECharts options. - b0870e1: Remove the subtle `shadow-xs` drop shadow from `InputGroup` `Root` and from nested `InputGroup.Button`, so the component matches the flat appearance of the standalone `Input` and other form controls (previously non-ghost button variants still had the base Button's `shadow-xs`). - 34e1672: Bundle the library with vp pack (tsdown) instead of Vite lib mode; declarations are now bundled per entry and export types paths follow the import paths - 2575f9c: Use muted chart colors for timeseries axes and horizontal gridlines. - 7c33107: One-time repo-wide format with the repo's own Prettier 3.6.2 (formatting was never enforced; drift accumulated). No functional changes. - ee6e569: Set default `text-base` and `text-lg` line heights to 1.5. - 927d19f: Remove inert Tailwind classes surfaced by class sorting: `ring` alongside `ring-2` (overridden — later stylesheet rule wins) and bare `outline` in three places (no such utility in Tailwind v4; `outline-1` already applies the default solid style). No visual changes. - 924f07a: Split Base UI across fine-grained chunks instead of one `vendor-base-ui` chunk Components now pull in only the Base UI modules they actually use, improving consumer tree-shaking: a single-Button app bundle drops from ~173 KB to ~129 KB minified (~57 KB to ~44 KB gzipped) compared to 2.8.0. - 7ef8c46: Add clearer edge affordances when Tabs overflow horizontally. - 86afc2b: Show Button title tooltips when the button is disabled or loading. - 5516c22: Fix command palette match highlight contrast in dark mode. - 24149b9: Normalize Tailwind class strings via Oxfmt class sorting (`sortTailwindcss`, canonical Tailwind order, duplicates removed). No functional changes. - 8de0551: Migrate the toolchain to Vite+ (`vp`): the library now builds with Vite 8 on Rolldown, tests run through `vp test` (Vitest), and linting/formatting run through `vp lint` (Oxlint) / `vp fmt` (Oxfmt, replacing Prettier). No API changes; published output is functionally identical, though entry files are now re-export facades whose source maps live in the shared chunks, and `use-sync-external-store` is now an explicit dependency instead of being bundled (bundling it left CJS `require("react")` calls that broke importing the package directly in Node). - 60f5bfa: Enable full type-checking in `vp check` / `vp lint` (typeAware + typeCheck) and fix the type issues it surfaced in files `tsc --noEmit` never covered. Only runtime-visible change: the CLI entrypoint explicitly voids its `main()` promise.

### Minor Changes - 8f2c40b: Rewrite `Flow` to use computed layout over relying on DOM layout. `Flow` now measures node sizes, reconstructs the flow tree, and computes node positions and connector paths from that derived state instead of chaining DOM rect reads. This keeps connectors aligned through resize and scroll changes, supports nested flow structures more predictably, and makes anchor-based connector placement follow the anchor midpoint. - fdeeb74: Add `target` prop to `Sidebar.MenuSubButton` for parity with `Sidebar.MenuButton` — forwarded to the link when `href` is set, so link sub-items can control where they open (e.g. same-tab cross-origin navigation). - b05ea3f: Add auto-resize support to InputArea and Textarea. - 33cb988: Add vertical reference markers to TimeseriesChart. - 0562dd1: Add horizontal threshold lines to TimeseriesChart. ### Patch Changes - a90dc83: Include chart components exported from multi-component barrel directories in the generated component registry, with complete props metadata for generic interfaces. - 0e440d4: Keep the mobile Sidebar open when focus moves to portaled interactive content. - 67061e1: Disable Sidebar.MenuButton tooltips while the sidebar is expanded or peeking.

### Minor Changes - 8f8f898: Add `ChoroplethMap`, a GeoJSON region choropleth chart component that joins data rows to features by `name`/`nameProperty` and shades regions with a continuous `visualMap` scale. Includes Kumo light/dark map colours, tooltip formatting, optional legend, hover/click callbacks, roam controls, docs, and demos. Both `BubbleMap` and `ChoroplethMap` now apply a d3-geo `projection` (latitude-clamped Mercator by default; pass another d3-geo projection or `null` for raw plotting) and size by `aspectRatio` so the map fills its container without letterboxing. The container height now derives from the projected window's aspect ratio by default; pass an explicit `height` to opt back into a fixed pixel height. Update `BubbleMap` viewport behavior to avoid resetting user pan and zoom while refreshing bubble data. `BubbleMap` now defaults `roam` to `false` to avoid accidental pan and zoom interactions. Consumers that want drag-to-pan or scroll-to-zoom can pass `roam={true}`. - 6d366d9: Add `orientation="vertical"` support to `Flow` for laying out nodes top-to-bottom. The `align` prop now controls cross-axis alignment in both orientations. - ebc5cf8: feat(chart): add `BubbleMap` chart component New `BubbleMap` component renders proportional bubbles over a registered geographic map using ECharts' scatter series. Includes value-based radius scaling, a `mapColors` palette addition to `ChartPalette`, and supporting types. Also extracts `escapeHtml` / `defaultValueFormat` tooltip helpers into a shared `tooltip-utils` module reused by `SankeyChart`. ### Patch Changes - dd1a0b5: Keep primary and destructive button active/focus rings matched to their variant color. - 8463c38: Use the Button component for Toast close controls and match the hover tint to the toast variant. - 3aa0d9a: Limit Dropdown content height to available viewport space to prevent overflow. - 25b2ab1: Replace the internal class merging implementation with cnfast. - 6232d34: fix(button): resolve Firefox rendering artifact when Turnstile is present Replace `translate-y-px` with `box-shadow: inset 0 1px 0 0 var(--kumo-button-emphasis-bg)` on the primary/destructive button emphasis overlay span. The transform triggered a rendering bug in Firefox on pages with Turnstile's `contain: strict` CSS. The box-shadow achieves the same visual depth effect without the rendering issue. - a74bd9c: Fix Dialog `size` prop to set a fixed width instead of only a minimum width. Previously, dialog content could stretch the dialog beyond its intended size. - 4dd1398: Update Base UI to 1.6.0.

### Minor Changes - 1b04ee9: Add Toolbar for composing explicit toolbar controls into a shared grouped card. - 116e0de: feat(chart): add `enableLegendSelection` prop to `TimeseriesChart` Opt-in (default `false`) hidden ECharts legend that lets consumers drive series visibility imperatively via the `legendSelect` / `legendUnSelect` / `legendToggleSelect` actions — useful for building a custom interactive legend with `ChartLegend`. Series toggled off via the legend are also excluded from the tooltip. Requires registering ECharts' `LegendComponent` (`echarts.use([LegendComponent])`). When disabled, behaviour is unchanged. - 815628f: Extend LegendItems to take pointer events & timeseries merges forwardref to support those events ### Patch Changes - 430689b: Update the Button primary and destructive variants with token-derived gradient treatments. - 539e5bf: Fix horizontal scroll in `Sidebar.Content`: always apply `overflow-x: hidden` on the scroll viewport, not just when collapsed. Base UI's `ScrollArea.Viewport` sets `overflow: scroll` as an inline style, which allowed ~14px of horizontal overflow when consumer content (e.g. search buttons with keyboard shortcuts) exceeded the sidebar width. - 4378067: feat(radio): add generic value type support to Radio.Group and Radio.Item - fb5fed1: Fix the green Badge variant missing its background color token. - bdd890c: Keep generated component registry descriptions to JSDoc summaries before markdown sections or code examples.

### Patch Changes - 9a13576: fix(button): use ring-kumo-line for default secondary button ring - b18837c: Refine outline and secondary destructive button hover states. - 595d10e: fix(sidebar): correct GroupLabel top margin from mt-6 to mt-4

### Patch Changes - b06e35b: Allow unprefixed Dialog max-width classes to override the default viewport cap at desktop breakpoints.

### Minor Changes - 7401701: Sidebar: mobile rewrite, smooth collapse transitions, and new props **New features:** - `mobileBreakpoint` prop on Provider — configurable viewport width for mobile detection - `contentClassName` prop on Sidebar root — pass-through class for the inner content container - Controlled mobile state — `open` prop now controls the mobile sidebar too, not just desktop **Fixes:** - Replaced Base UI Dialog mobile sidebar with a plain `` + backdrop for simpler, more predictable transitions - Collapsible sections now animate closed smoothly when the sidebar collapses instead of snapping shut - Removed `hidden` class from `Sidebar.MenuSub` so sub-menus participate in collapse animations - Removed `inertValue` React-version helper — `SidebarSlidingView` now sets `inert` imperatively for React 18 compatibility - Restored `inert` on closed `SidebarCollapsibleContent` while removing its `data-open` attribute **Styling:** - `bg-kumo-tint` → `bg-(--sidebar-active-bg)` CSS variable for active/hover/focus backgrounds - Icon opacity `0.5` → `0.4`; chevron gains hover opacity transition - Header gains `shrink-0` and animated padding on collapse - Content scroll area gains animated `gap` transition and `tabIndex={-1}` on viewport - Sliding views container gains `max-w-(--sidebar-width)` to prevent overflow - Mobile sidebar uses `--sidebar-animation-duration` CSS variable for slide transition ### Patch Changes - f957dbc: Add React 18 and React 19 compatibility checks for Kumo tests. - ac46184: Fix `Chart` (and `SankeyChart`) rendering in dark mode. The chart canvas now stays transparent so the surrounding `bg-kumo-*` surface shows through symmetrically in both modes, and ECharts' built-in `"dark"` theme is applied when `isDarkMode` is true so the tooltip card, axes, splitLines, and legend text are themed correctly. - e25a3d6: fix(sidebar): add text truncation with ellipsis to Sidebar.MenuButton content Previously, `Sidebar.MenuButton` used `overflow-hidden` which clipped long text without showing an ellipsis. Now uses `truncate` to match `Sidebar.MenuSubButton`'s behavior. - d3feec0: Fix segmented `Tabs` scroll fade, scroll-into-view, and ring styling: - Rewrite CSS scroll-fade masking to use `@property`-animated custom properties, fixing proportional fade rendering across browsers. - Scroll the selected tab into view on click so it stays visible in overflowing tab lists. - Move `ring ring-kumo-hairline/70` from the inner list to the root container so the segmented variant ring wraps the entire component correctly. - f831482: Fix Flow connector rendering in Firefox by emitting valid SVG path data without array commas and setting visible overflow on the SVG element attribute. - 4a8b992: Restore React 18-compatible Sidebar inert attribute handling while keeping the full React compatibility CI suite.

### Patch Changes - 2daa237: Fix Combobox and Autocomplete rendering in React 18 by using the explicit context provider API.

### Minor Changes - b93d881: Update Banner to use borderless tinted styling by default and add a secondary variant. - a9a1526: Re-export `useFilter` from `Combobox` and `Autocomplete` namespaces. Use it to write custom `filter` props that preserve Base UI's default case- and accent-insensitive matching via `Intl.Collator`. - 3db8294: Sidebar: comprehensive modernization **Breaking changes:** - Removed `Sidebar.Input` — build custom search triggers inline - Removed `Sidebar.MenuAction` — unused in practice - Removed `Sidebar.GroupContent` and group-level collapsible props (`collapsible`, `defaultOpen`, `open`, `onOpenChange`) from `Sidebar.Group` — use `Sidebar.Collapsible` at the item level instead - Replaced Base UI Collapsible dependency with custom CSS grid-rows implementation - `SidebarState` type is now `"expanded" | "collapsed" | "peeking"` (was `"expanded" | "collapsed"`) **New features:** - `contained` prop on Provider — absolute positioning for embedded/demo sidebars - `peekable` prop on Provider — hover/focus collapsed sidebar to temporarily expand - `animationDuration` prop on Provider — configurable animation timing - `Sidebar.SlidingViews` + `Sidebar.SlidingView` — animated horizontal transitions between navigation surfaces - Animated `SidebarPanelIcon` replacing Phosphor `SidebarSimpleIcon` - Enhanced `Sidebar.Trigger` with `aria-expanded` and dynamic `aria-label` - Keyboard-accessible resize handle (arrow keys, Home, End) - Custom `Sidebar.Collapsible` with keyboard auto-expand on focus **Token/styling fixes:** - `border-kumo-hairline` → `border-kumo-line` throughout - Hardcoded `duration-250` → `--sidebar-animation-duration` CSS custom property - `bg-kumo-base` → `bg-(--sidebar-bg)` for theme overridability - Focus styles: `ring-2/ring-kumo-brand` → `outline-none/text-kumo-strong/bg-kumo-tint` - Icon opacity-50, updated spacing (header h-58px, footer h-12, menu gap-y-px) - `isolate` on sidebar root with low z-index (z-1, z-2) instead of z-20/z-50 - Mobile sidebar now has correct `data-state`/`data-side`/`data-variant`/`data-collapsible` attributes - 18f5e42: **TimeseriesChart: React tooltip with Base UI positioning** Replaces ECharts' HTML-string tooltip with a React component positioned by Base UI's Tooltip primitive: - Tooltip rendered as a React component with correct theme tokens — no more inline styles or `getComputedStyle` hacks - Positioning handled by Base UI Tooltip (Floating UI), with automatic collision avoidance and viewport flipping - New `tooltipFollowCursor` prop: `"both"` (default, free-following) or `"x"` (axis-locked, Recharts-style) - New `tooltipMode` prop: `"all"` (default) or `"single"` (nearest series to cursor) - New `tooltipMaxItems` prop: caps rows in `"all"` mode with `+N more` footer (default `10`) - Date formatted with `Intl.DateTimeFormat` (locale-aware) instead of ISO string - Values sorted descending; fallback formatter avoids scientific notation ### Patch Changes - ab273fe: Banner: replace `dark:` Tailwind variants with new `kumo-banner-info` and `kumo-banner-warning` semantic tokens so dark-mode opacity is baked into the design system. No visual change. - 351fac9: fix(styles): show pointer cursor on clickable Kumo elements by default Adds a global `cursor: pointer` rule scoped to elements rendered by Kumo components, identified by the new `data-kumo-component` and `data-kumo-part` attributes. Interactive component roots and parts now opt into the rule by setting these attributes, which gives the library a stable scoping primitive that doesn't couple to Tailwind class names. Components updated to set `data-kumo-component` / `data-kumo-part`: Button, LinkButton, Link, Checkbox, Radio, Switch, Select (trigger, option), DropdownMenu (item, link-item, checkbox-item, radio-item, submenu-trigger), Combobox (trigger, item, clear, chip-remove), Autocomplete (item), Dialog (trigger, close), Popover (trigger), Tabs (tab), Collapsible (trigger, default-trigger), Breadcrumbs (link), TableOfContents (item, group-link), Sidebar (menu-button, menu-sub-button, trigger, rail), MenuBar (option), Toast (close), SensitiveInput (toggle-visibility, copy, masked-container). - 3db8294: fix(sidebar): collapsed state styling, transitions, and sliding views - 6d5d9f0: Add `flex items-center` to `ComboboxBase.Icon` in `TriggerInput` for consistency with `TriggerValue` and `Select` - 5081d35: Fix `Select` placeholder not showing when `renderValue` is provided and the value is empty. - 9d4a2ff: Update semantic color tokens to better represent status icons and indicators: - Adjust status token values in the theme generator and refresh generated theme output - Update toast and badge status background treatments - Update docs to reflect new tint token usage - 1585bfe: Adjust toast visual styling for improved readability and emphasis: increase background tint intensity for success/warning/info variants, refine description text contrast, and update close-button icon contrast. - 6e9b524: Fixed vertical alignment of checkbox and radio indicators with multi-line labels. When label text wrapped to multiple lines, the indicators were vertically centered against the entire text block. They now align to the top, sitting next to the first line of text. - 729caa3: echarts is now an optional peer dependency. If you don't use Chart components (Chart, TimeseriesChart, SankeyChart), it will no longer be installed automatically. If you do use them, run npm install echarts (as documented).

### Minor Changes - b68caba: Added `Badge` dot styling as a new variant for indicators that need a subtle visual cue. Updated badge docs and demo examples to reflect the new badge variant and dot-style behavior. ### Patch Changes - a210c9c: Update Base UI to 1.5.0. - 64a4bda: Fix InputGroup focus ring thickness and color: container mode uses 1.5px ring (wraps entire group including buttons), hybrid container zone and individual mode use 1px ring (thin to avoid colliding with adjacent buttons), and all modes use `ring-kumo-focus/50` (50% opacity) to match the standalone Input component. - 0003bf5: Fix error state red border on Combobox, Select, Autocomplete, and SensitiveInput to match Input behavior - 4f2b47c: Add inline label layout and fix auto-assigned node colors in tooltips - 0e79214: Fix Tooltip popup overflowing viewport when content is wider than available space. The popup now constrains its width to `var(--available-width)`, a CSS variable provided by Base UI's Positioner that reflects the space between the trigger and the viewport edge.

### Patch Changes - 94d0c22: Fix language alias normalization in ShikiProvider - Add `normalizeLanguage()` function that maps common language aliases (js, ts, sh, yml, py, md, gql) to their canonical SupportedLanguage names - Normalize language aliases in `ShikiProvider` when preloading grammars, so passing `['js', 'ts']` works the same as `['javascript', 'typescript']` - Normalize language aliases in `highlight()` hook at runtime, so code fences using `js` or `ts` highlight correctly without warnings - Export `normalizeLanguage` from `@cloudflare/kumo/code` for consumers who need to normalize aliases themselves - Intentionally omit `mdx` alias since MDX has a distinct grammar that would lose JSX highlighting if mapped to `markdown`

### Patch Changes - 57bbe62: fix(banner): remove variant selection background for legibility Selected text inside `Banner` now uses the browser default selection color instead of a same-hue variant-tinted background. The previous `selection:bg-kumo-{info,warning,danger}` utilities produced low contrast between the selection background and the variant text color (most notably in light mode for the `error` and `alert` variants), making selected text hard to read. - 3d80fe7: Add `left` and `right` props to SankeyChart for controlling series layout padding - 194aea8: Fix tooltip popup exit transitions by animating the Tailwind `scale` property alongside opacity.

### Minor Changes - 228a9c4: Add `passwordManagerIgnore` to Input for suppressing password manager overlays on non-credential fields. - da502ce: Add scroll fade to segmented tabs. When tabs overflow, gradient masks appear on the edges based on scroll position via scroll-driven animations (Chrome 115+, degrades gracefully). Scrollbar is hidden; the fade is the scroll affordance. - 59b6590: Add `size="sm"` variant to Tabs component (h-6.5 / 26px, matching Input sm) - 798c2da: Forward `toastManager` prop on `` so code outside the React tree (timers, query-cache listeners, module-load callbacks) can dispatch toasts via a manager created by `createKumoToastManager()`. Also surface `createKumoToastManager` on the top-level package export (previously only available via the deep `@cloudflare/kumo/components/toast` path). ### Patch Changes - bccc684: Add transparent background to SankeyChart component - 974277f: Expose `optionUpdateBehavior` prop on `TimeseriesChart` to control how ECharts applies option updates - 8d43b8b: Add `hideLabel` prop to Field so components can skip the native `` while keeping description/error wiring. Use it in Select with Base UI's `Select.Label` to fix hover/focus coupling between the label text and trigger. - 93d04bd: fix(input): render error and description props without requiring a label - 862389a: fix(radio): prevent radio button distortion with long labels by adding `shrink-0` to the default appearance radio indicator - 1bfbc0e: Fix overflowing segmented Tabs drag-to-scroll interactions so mouse and touch drags reliably scroll while normal tab clicks still activate tabs.

### Minor Changes - 8a33813: Create Sankey Chart component ### Patch Changes - a21cc3a: Fix CommandPalette List bottom ring being clipped by Footer background. Add scroll padding to prevent items from clipping behind rounded corners. - 0414c54: Deprecate `to` prop on Link in favor of `href`. The `to` prop is a routing-framework concept that doesn't belong on a presentational component. Use `href` for all link destinations and configure a `LinkProvider` wrapper to bridge to your router. `to` continues to work but emits a dev-mode deprecation warning. - 8b12a4c: Allow `LayerCard.Primary` and `LayerCard.Secondary` to accept all standard HTML div attributes, including `data-testid` for testing. - 7d8ec27: Set `cursor-default` on Tooltip triggers so disclosure buttons don't appear clickable. Overridable via `className`.

### Patch Changes - 8f8a55d: Export `Combobox.Trigger`, `Combobox.Value`, and `Combobox.Icon` — the raw Base UI primitives for building custom combobox triggers. Use these when you need full control over the trigger's visual treatment (e.g. a sidebar account switcher that renders as a plain button instead of an input-like control).

### Patch Changes - 8926ee7: fix(CloudflareLogo): remove registered trademark symbol from full logo variant - 75d4f4d: Fix Google Translate DOM mutation crash in Button - f2d356d: Remove z-50 from mobile Sidebar Dialog backdrop and panel. The z-50 caused portaled floating elements (Popover, DropdownMenu, Select, Combobox) opened from inside the Sidebar to render behind the Dialog backdrop. Matches the pattern used by Kumo's own Dialog component, which relies on DOM order for stacking with no explicit z-index. Also adds `data-sidebar-backdrop` and `data-sidebar-popup` attributes as stable CSS hooks.

### Patch Changes - 3b36e21: fix(combobox): forward all props from TriggerValue to ComboboxBase.Value, enabling placeholder support and styled placeholder text via data-[placeholder]:text-kumo-placeholder - 5d5d810: fix(registry): correct Select component metadata for AI-generated code The component registry metadata was incorrectly typing Select's `value`, `defaultValue`, and `onValueChange` props as `string`, causing AI agents to produce broken code when implementing Select with object values (e.g., rendering `object.value` in the trigger instead of the label). Changes: - `value` type: `string` → `T` (generic, matches actual component interface) - `defaultValue` type: `string` → `T` - `onValueChange` type: `(value: string) => void` → `(value: T) => void` - Added missing `renderValue` prop: `(value: T) => ReactNode` — required for object values - Added missing `items` prop: supports both `Record` and `Array` forms - Added missing `isItemEqualToValue` prop: required for object equality comparison - 62e093c: Gracefully fall back to default variant instead of crashing when an invalid variant prop is passed at runtime. Previously 22 of 25 components would throw `TypeError` on unknown variant values; all 25 now use a shared `resolveVariant()` utility that returns the default config and logs a dev warning.

### Patch Changes - fbf3eef: Forward all Base UI Panel props (including `keepMounted` and `hiddenUntilFound`) through `Collapsible.DefaultPanel`. Previously these were silently dropped because `DefaultPanel` used a standalone props interface instead of extending `BasePanelProps`. - 40491c2: Fix registry codegen to match demo examples when component export name differs from directory name (e.g. DropdownMenu vs dropdown). This restores missing examples for DropdownMenu and other affected components. - 3427221: TooltipProvider props (`delay`, `closeDelay`, `timeout`) are now shown in the Tooltip component's API Reference on the docs site.

### Patch Changes - e53bd68: Rebalanced semantic text token usage to improve hierarchy and consistency across components, docs, and generated Figma output. - Updated theme token definitions so `text-kumo-strong` represents high-emphasis text and `text-kumo-inactive` is lighter/inactive in both light and dark modes. - Migrated affected UI surfaces from `text-kumo-strong` to `text-kumo-subtle` where content is supportive metadata, labels, or secondary text. - Synced token usage in docs and Figma code generators with the updated semantic text mapping.

### Major Changes - bf68ac0: **BREAKING:** Checkbox `onCheckedChange` now receives event details as second argument The `onCheckedChange` callback signature now matches Base UI, providing access to the underlying event: ```tsx // Before onCheckedChange={(checked) => console.log(checked)} // After (event details available as optional second arg) onCheckedChange={(checked, eventDetails) => { console.log(checked); console.log(eventDetails.event); // native event }} ``` **Removed deprecated props:** - `onChange` - use `onCheckedChange` instead - `onValueChange` on individual checkboxes - use `onCheckedChange` instead - `onClick` - was redundant, use standard React event handling via spread props **Migration:** ```tsx // Before (deprecated) console.log(e.target.checked)} /> setChecked(checked)} /> // After setChecked(checked)} /> ``` Note: `Checkbox.Group`'s `onValueChange` prop is unchanged - it still accepts `(values: string[]) => void`. - f9ba3f9: feat(Collapsible)!: refactor to compound component API **Breaking change:** Collapsible now uses a compound component pattern matching other Kumo components like Popover and Dialog. ### Before ```tsx Content here ``` ### After ```tsx Show details Content here ``` ### Migration For the quickest migration, use the new `DefaultTrigger` and `DefaultPanel` components which preserve the previous styling: ```tsx Show details Content here ``` ### New Sub-components | Component | Description | | ---------------------------- | ----------------------------------------------------------- | | `Collapsible.Root` | Manages open state | | `Collapsible.Trigger` | Composable trigger with `render` prop support | | `Collapsible.Panel` | Content container | | `Collapsible.DefaultTrigger` | Pre-styled trigger with caret icon (migration helper) | | `Collapsible.DefaultPanel` | Pre-styled panel with border-left accent (migration helper) | - 3256a7b: feat(Text): decouple visual heading variants from semantic HTML elements **Breaking change:** `heading1`, `heading2`, `heading3` variants no longer auto-render ``, ``, `` tags. They now render as `` by default. Use the `as` prop to set the appropriate semantic heading level for your document outline. Before: ```tsx Title // rendered ``` After: ```tsx Title // explicit semantic element ``` The `as` prop is now restricted to valid text elements: `"h1"` through `"h6"`, `"p"`, and `"span"`. - 267ba7a: **BREAKING (v2):** `Text` requires an explicit `as` prop when `variant` is a heading (`"heading1"`, `"heading2"`, `"heading3"`). The previous major bump ([#393](https://github.com/cloudflare/kumo/pull/393)) decoupled heading variants from semantic HTML — heading variants render as `` unless an `as` prop is provided. That made the library more flexible but introduced a silent accessibility footgun: forgetting `as` on a real section heading produced a ``, excluding it from the document outline without any type-level feedback. This change makes `as` **required** for heading variants via a discriminated union. Body and monospace variants are unchanged (`as` remains optional; defaults to `` and `` respectively). ### Migration Every ``, ``, `` must now pass `as`. TypeScript will flag each call site: ```tsx // Before (compiled, silently produced a ) Page Title // After (required) Page Title // Still allowed — decorative heading-styled text that is NOT a section heading: Big bold card label ``` For each heading call site, decide whether it's a real section heading (use `as="h1"`/`"h2"`/etc.) or decorative (use `as="span"`). Codemod cannot make this choice mechanically — it is a semantic judgment per usage. Body and monospace variants: no changes required. ### Minor Changes - 1954aa8: feat(radio, checkbox, switch): add composable Legend sub-component for group components - Add `Radio.Legend`, `Checkbox.Legend`, and `Switch.Legend` sub-components - Accepts `className` for full styling control (e.g. `className="sr-only"` to visually hide) - Make `legend` string prop optional when using the sub-component instead - Useful when a parent Field already provides a visible label and the legend would be redundant - **Breaking:** `Switch.Group` no longer renders a visible border/padding/rounded container — now consistent with `Radio.Group` and `Checkbox.Group`. Use `className` to add a border if needed. - 1eee41a: Add `InputGroup` compound component for composing decorated inputs Compound structure: `InputGroup`, `InputGroup.Input`, `InputGroup.Addon`, `InputGroup.Suffix`, `InputGroup.Button`. - Field integration — pass `label`, `description`, `error`, `required`, and `labelTooltip` directly to `InputGroup` - Size variants (`xs`, `sm`, `base`, `lg`) propagate to all sub-components via context, including icon sizing in addons - `InputGroup.Addon` — positions icons, text, or buttons at `align="start"` (default) or `align="end"` of the input - `InputGroup.Suffix` — inline text suffix (e.g. `.workers.dev`) - `InputGroup.Button` — ghost button for secondary actions with tooltip support - Deprecated `InputGroup.Label` — use `InputGroup.Addon` instead - Deprecated `InputGroup.Description` — use `InputGroup.Suffix` instead ```tsx { /* Reveal / hide password */ } setShow(!show)} > {show ? : } ; ``` ```tsx { /* Search input */ } ; ``` - 353faea: Adds Autocomplete component. A free-form text input with an optional filtered suggestion list. Unlike Combobox, the value is not constrained to the items list. - 431de04: feat(radio): accept ReactNode for `Radio.Item` label and honor `controlPosition` on card appearance - `Radio.Item`'s `label` prop now accepts `ReactNode`, allowing icons, badges, or other markup alongside text. - `Radio.Group`'s `controlPosition` prop now takes effect on `appearance="card"`. Card appearance continues to default to `"end"` (radio on the right); pass `controlPosition="start"` to render the radio on the left of the label and description. - f9d8b76: Polish TableOfContents indicator and semantic HTML - Replace pill/background-tint hover with left-border indicator pattern - Switch to semantic `ul`/`li` HTML structure - Add `href` and `active` props to `TableOfContents.Group` for clickable labels - 07426f6: feat(table): add `onCheckedChange` prop to `Table.CheckCell` and `Table.CheckHead`, aligning with the `Checkbox` component's signature. The new prop exposes an optional second argument with event details, matching Base UI's idiom: ```tsx { toggle(row.id); eventDetails?.event.stopPropagation(); }} /> ``` The existing `onValueChange` prop still works but is now deprecated and flagged by the `no-deprecated-props` lint rule. It will be removed in a future major version. Migrate by renaming the prop — the single-argument callback shape is preserved. This change is additive and does not require consumer code changes at this time. - c1c60c8: Expand `Text` component's `as` prop to accept additional HTML text elements: `label`, `dt`, `dd`, `li`, `figcaption`, `legend`, `pre`, `code`, `em`, `strong`, `small`, `abbr`, and `time`. This unblocks downstream usage in Stratus where `Text` needs to render as definition list terms, labels, and code elements. ### Patch Changes - ac6df5f: Remove invalid hover border utility from secondary button variants to keep hover styling consistent and avoid unintended class output. - ec73bc5: Update chart color docs and demos, including sequential heatmap/CVD coverage and improved chart demo behavior. - 7d12918: `Combobox.Item` now renders a visible disabled state when the `disabled` prop is set. Previously the prop was forwarded to Base UI (so click/keyboard selection were correctly blocked) but the row looked identical to an enabled one. Adds `data-[disabled]:*` Tailwind classes for muted text, `cursor-not-allowed`, reduced opacity, and suppresses the highlight background on disabled rows during keyboard navigation. Also fixes `className` passthrough — user-supplied classes are now merged via `cn()` instead of being overridden. - 69bfc53: Improve focus ring consistency and clipping behavior across inputs and related controls. - Move the command palette focus ring to the input header container with `focus-within` and remove duplicate input-level ring styles. - Update `Select` trigger and option focus styles to use inset focus rings to prevent clipping in rounded/overflow contexts. - Fix clipboard copy button focus ring clipping by using inset focus-visible ring, matching border-radius inheritance, and isolated stacking. - Align `InputGroup` and `InputGroup.Button` focus ring color to `ring-kumo-focus`, including hybrid container-zone focus ring classes. - Update InputGroup tests to match inline focus ring class changes. - Set DatePicker (`react-day-picker`) focus ring token to `var(--color-kumo-brand)`. - Update InputGroup container and hybrid keyboard outlines in `kumo-binding.css` to use `var(--color-kumo-focus)` at 1px weight. - 30bfd82: Allow `CommandPalette.Input` to accept standard HTML input attributes (`autoComplete`, `autoCorrect`, `autoCapitalize`, `spellCheck`, `data-*`, etc.) by extending its props type with `InputHTMLAttributes`. Export new `CommandPaletteInputProps` type. - b923281: Fix `InputGroup` hover state incorrectly propagating to the first child button (e.g. in `Pagination.Controls`). Root now renders as `` instead of `` when it contains multiple labelable controls. - 06b8852: Fix Table body cells rendering at 16px. The Table root now sets text-base (14px) so cells match Kumo's default body font-size instead of inheriting the browser default. Also replaces an arbitrary text-[14px] in Empty with text-base. - c019b41: Improved focus and keyboard accessibility styles across Kumo components and docs navigation. - Added the `kumo-focus` semantic token to the theme generator config and generated `theme-kumo.css` output. - Updated focus ring behavior across interactive components (including `Button`, `Input`, `InputGroup`, `Select`, `Checkbox`, `Radio`, `Switch`, `Sidebar`, `Tabs`, `Menubar`, and related controls) for more consistent and visible keyboard focus visibility. - Text-entry controls use a lighter opacity `kumo-focus` ring to keep pointer and keyboard focus visually consistent where browsers apply `:focus-visible` heuristics to typed-input controls. - Refined `Select` and `Input` styling/state combinations to align focus visuals with current semantic token usage. - Updated docs `SidebarNav` keyboard-focus affordances (links, section toggles, search trigger) and adjusted collapsible list overflow so focus rings remain visible. - Replace raw colors in `Select` with kumo semantic tokens. - 21ed1a1: Fix `InputGroup` container className to enforce `mb-0`, ensuring all container variants (not just the standalone `` mode) reset inherited bottom margin. - fa991d9: Fix `InputGroup` label wrappers to enforce `mb-0`, preventing inherited label margins from shifting layout and click-target overlays. - 6765526: chore: update @base-ui/react to v1.4.0 Bugfix release with improvements to Popover hover state, Checkbox/Switch readOnly mode, Select touch handling, Tabs activation direction, Toast timers, and various other fixes. No breaking changes.

### Minor Changes - da6eee1: feat(chart): rename `formatter` to `dangerousHtmlFormatter` for XSS awareness BREAKING CHANGE: The `formatter` property in `KumoChartOption['tooltip']` has been renamed to `dangerousHtmlFormatter`. This change makes the security implications of using HTML formatters more explicit to developers. The API remains identical—only the name has changed. Migration: Replace `formatter` with `dangerousHtmlFormatter` in your chart tooltip configurations. - 4785c43: feat(tooltip, popover): deprecate `asChild` in favor of `render` prop Unifies composition patterns across the library by adopting Base UI's `render` prop pattern. The `asChild` prop is now deprecated on: - `Tooltip` - `Popover.Trigger` - `Popover.Close` **Migration:** ```diff - - Save - + <Tooltip content="Save" render={Save} /> - - Open - + <Popover.Trigger render={Open} /> - - Close - + <Popover.Close render={Close} /> ``` The `asChild` prop remains functional for backward compatibility but will be removed in a future major version. - a0f2b18: feat(popover): expose `anchor` prop on `Popover.Content` for virtual positioning Forwards Base UI's `anchor` prop through `Popover.Content` to the underlying `Positioner`, enabling popover positioning against custom elements, refs, or virtual points (e.g., a `DOMRect` from `getBoundingClientRect()`). This is useful when the popover trigger and the desired anchor are in different component trees, or when anchoring to a coordinate rather than a DOM element. - 58b5777: Convert Table of Contents to exported Kumo component - 0cae077: feat(Select): add size prop (xs/sm/base/lg) matching Input and Combobox heights ### Patch Changes - 1e7ba10: feat(layer-card): support simple card usage and deprecate Surface - allow `LayerCard` to be used directly without `LayerCard.Primary` for simple single-layer card layouts - keep `LayerCard.Secondary` and `LayerCard.Primary` supported for the existing layered card pattern - deprecate `Surface` in favor of `LayerCard` while keeping the old API working as a compatibility wrapper - update docs and examples to prefer `LayerCard`, including table examples that no longer need a nested `LayerCard.Primary` - 2682319: fix(pagination): add ARIA attributes for screen reader accessibility - Wrap pagination controls in `` for proper landmark navigation - Add `aria-live="polite"` and `aria-atomic="true"` to status text for page change announcements - Add `navigation` to `PaginationLabels` for i18n customization of the nav aria-label - 9eb1306: fix(chart): escape HTML in tooltip series name and values Escapes HTML entities in TimeseriesChart tooltip series names and values before rendering. - 4565baa: fix(combobox): make TriggerInput caret button clickable for Playwright tests - 4dfdc3f: fix(dropdown): pass children through when render prop is provided on DropdownMenu.Trigger - 98e3170: fix(Select): TypeScript inference with `strictNullChecks` and `renderValue`/`placeholder` interaction **TypeScript fix:** Under `strictNullChecks`, using `value={objectOrNull}` would cause `T` to be inferred as `never`, making callbacks like `onValueChange` and `renderValue` unusable. This is now fixed. **Runtime fix:** `renderValue` is now only called with non-null values. When value is null, the `placeholder` is shown instead. Previously, `renderValue` would receive `null` at runtime despite being typed as `(value: T) => ReactNode`. ```tsx // Recommended pattern v.name} // v is T (non-null), no defensive coding needed /> ``` - 9c3cdbf: Fix sidebar collapsible content snapping shut instead of animating smoothly when closing. - 27bcd59: fix(table): align sticky column colors with compact header variant - a8adf02: fix(tokens): correct text-kumo-subtle dark mode value to provide visible contrast - 547c7fa: Updated the token value for `kumo-line` and `kumo-hairline` in dark mode so they are more visible. - replace `kumo-line` usages with `kumo-hairline` across Kumo components and docs UI/content styles - use `ring-kumo-line` for shadowed surfaces (for example combobox, dialog, select, dropdown, toast, and related surface wrappers) - adjust theme token configuration and generated styles to support updated neutral/hairline appearance - 460a603: fix(a11y): add accessible labels to icon-only controls

### Minor Changes - b1e51a8: Add Enter key navigation to Pagination page number input and new `pageSelector` prop for dropdown mode - The page number input in `Pagination.Controls` now navigates on Enter key press (previously only on blur) - New `pageSelector` prop on `Pagination.Controls`: set to `"dropdown"` to render a Select dropdown instead of a text input for page selection - e676f0b: Add disabled option support, groups, group labels, and separators to Select - `Select.Option` now accepts `disabled` and `className` props - New `Select.Group` and `Select.GroupLabel` sub-components for organizing options under labeled headers - New `Select.Separator` sub-component for visual dividers between groups - The `items` object-map prop now accepts `SelectItemDescriptor` values with `disabled` metadata - a685953: Expose `delay` and `closeDelay` props on Tooltip component to control open and close timing. These props are forwarded to the underlying Base UI Trigger component. ### Patch Changes - dacf445: Input and InputArea now automatically apply error styling when the `error` prop is truthy. You no longer need to set `variant="error"` separately - just pass an error message and the styling is applied automatically. The `variant="error"` prop is now deprecated but still works for backwards compatibility. - 44c26f5: Adjust semantic tint usage for status/error ring styles across core form and feedback components. - Update background styles in `Badge` and `Banner` components to use `*-tint` tokens. - Update `kumo-danger` to a darker token to improve a11y contrast. - Update error ring styling in form components to use semantic tokens (now darker with token swap). - Removed `text-color-badge-red-subtle` token in replacement of the `danger` token. - Update theme generator color mappings used by these tints to improve visual consistency. - 2bb8628: Fix CodeBlock crash when an unsupported `lang` value is passed at runtime. The `codeVariants()` function now uses optional chaining with a nullish coalescing fallback to the default language, matching the defensive pattern already used by `switchVariants()` and `badgeVariants()`. - e8bcf6f: fix(select): use ring-kumo-hairline token in Select popup (missed in PR #355) - c3beded: Fix Select popup scrolling and height behavior; align popup/list structure with Base UI. Split popup into frame (Popup) and scroll container (List) to match Combobox pattern and fix touch scroll on long lists. - 4a2fb02: fix(loader): add ARIA attributes for screen reader accessibility Added `role="status"` and `aria-label="Loading"` to the Loader SVG component to make it accessible to screen readers. This resolves a WCAG 2.1 SC 4.1.3 (Status Messages) violation where assistive technology users received no indication that content was loading. - 5e4c7b1: Refine badge semantics/fill styling and banner tone updates - Rework `Badge` variant model to prioritize semantic variants (`primary`, `secondary`, `error`, `warning`, `success`, `info`) with updated descriptions and `primary` as default. - Keep token color variants for product-specific use cases while updating class mappings so semantic and token variants are distinct. - Slight updates to token color variants to meet a11y contrast requirements. - Update token color variants by replacing `yellow` with `purple` since `yellow` doesn't meet a11y contrast requirements, and keeping docs/demo examples in sync. - Update badge docs demos/content to focus on primary semantic badges and a consolidated "other variants" section. - Adjust banner variant surfaces (`default`, `alert`, `error`) to stronger tinted backgrounds and borders. - Update theme generator badge/semantic token mappings and regenerate `theme-kumo.css` to match the new badge color system. - 6458fae: Fix Switch label click not toggling when a custom `id` prop is provided The `id` was not being forwarded to Base UI's `Switch.Root`, causing a mismatch between the label's `htmlFor` and the button's actual `id`. - cf6b917: Align semantic token documentation and docs presentation updates. - Update `colors.mdx` token documentation structure. - Replaced `kumo-ring` with `kumo-hairline` for border/ring colors and all its instances in kumo components and docs. - Sync `packages/kumo/ai/USAGE.md` token reference categories and descriptions with the docs token guide. - Adjust the typo in the recessed dark token value in theme generator config and regenerate `theme-kumo.css`. - Updated `kumo-fill-hover` token value from `neutral-700` to `neutral-800`

### Minor Changes - 355a1b5: Badge: add color-based variants and deprecate semantic variants - Add color variants: `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `neutral`, `inverted` - Add subtle variants for each color (`red-subtle`, `orange-subtle`, etc.) with lighter backgrounds and darker text - Retain `outline` and `beta` variants unchanged - Deprecate `primary` (use `inverted`), `secondary` (use `neutral`), `destructive` (use `red`), `success` (use `green`) - Dark mode support: subtle variants flip to dark backgrounds with light text, regular color variants darken slightly, inverted flips to white bg with black text - Default variant changed from `primary` to `neutral` - 250a6dd: Add `action` prop to Banner for rendering CTA buttons alongside structured title/description content without resorting to the `children` prop. - 8c244d2: Refresh semantic surface color tokens and component surface usage. - Add and adopt `kumo-canvas` as the page-level surface token in theme output and docs usage. - Rebalance neutral token values in `kumo-binding.css` and generated theme variables for improved light/dark surface hierarchy. - Update surface-related component styling (`LayerCard`, `MenuBar`, `Tabs`) to align with the refreshed `canvas`/`elevated`/`recessed` layering model. - Update token usage guidance in `ai/USAGE.md` to reflect page vs component background roles. - ef15662: Make timeseries' highlighted on hovering a data point - cd0c22f: Add Shadow DOM support via `KumoPortalProvider` and `container` prop on all portal-based components All overlay components (Dialog, DropdownMenu, Combobox, Select, Tooltip, Popover, CommandPalette, Toast) now support rendering inside Shadow DOM or custom containers. **New exports:** - `KumoPortalProvider` - Context provider to set default portal container for all overlays - `PortalContainer` - Type for portal container (HTMLElement, ShadowRoot, or ref) **Component updates:** All portal-based components now accept an optional `container` prop: - `Dialog` - `container` prop on Dialog component - `DropdownMenu.Content` - `container` prop - `Combobox.Content` - `container` prop - `Select` - `container` prop - `Tooltip` - `container` prop - `Popover.Content` - `container` prop - `CommandPalette.Root` and `CommandPalette.Dialog` - `container` prop - `Toasty` (Toast provider) - `container` prop **Usage:** Set once at the app level: ```tsx ``` Or override per component: ```tsx Modal inside shadow DOM ``` When no provider or prop is set, components default to `document.body` (existing behavior). - 17f21f3: SkeletonLine: add `blockHeight` prop to set a container height and vertically center the skeleton line within it - d1f697b: Table: add `sticky` prop to `Table.Head` and `Table.Cell` for pinning columns to left/right edges, and `sticky` prop to `Table.Header` for sticky header rows. Uses `isolate` stacking context with `z-0`/`z-1`/`z-2` layering. - 56e3640: Add `toml` as a supported language for syntax highlighting in the Code component - f0c8952: Add `title` prop to `Button` — wraps the button in a `Tooltip` when provided. ### Patch Changes - 7721bc5: Checkbox.Group & Radio.Group: remove fieldset border box and simplify styling - Remove `rounded-lg border border-kumo-line p-4` wrapper from both group fieldsets - Downsize legend from `text-lg` to `text-base` with inline-flex layout - Drop `font-medium` from Checkbox.Item and Radio.Item labels - 6c21970: Fix missing disabled styling on Combobox triggers. `TriggerValue` and `TriggerMultipleWithInput` now apply `opacity-50` and `cursor-not-allowed` when disabled, matching the behaviour of the `Select` component. - 0e4247a: Update dialog backdrop overlay to use `bg-kumo-recessed` token - 0060bb9: Remove `ai/schemas.ts` from version control (now fully generated at build time) - 04a1f07: Fix LayerCard.Primary stacking order when sandwiched between LayerCard.Secondary elements - 94d50e2: Fix SensitiveInput focus ring and global CSS pollution - Fix focus ring not showing on container when inner input is focused (focus-within:outline) - Add defensive styles to eye toggle and copy buttons to prevent global CSS pollution - Fix inputVariants parentFocusIndicator using wrong selector ([&:has(:focus-within)] → focus-within:) - db75c51: SkeletonLine: move `.skeleton-line` styles into `@layer base` so Tailwind utility classes (e.g. `className="h-6"`) can override the default height - eb68b35: Tabs indicator now uses `translate-x` for its transition animation, replacing the CSS `left` transition with a GPU-accelerated transform. - e21a6df: fix flow component not reflecting padding prop - 29c56fd: `Surface`: replace `as` prop with Base UI `render` prop for polymorphism The `as` prop used a hand-rolled generic `forwardRef` pattern (with `as any` casts) that conflicted with how the rest of the library handles polymorphism via Base UI's `useRender` hook. `Surface` now accepts a `render` prop, consistent with `Link` and other components. The old `as` prop is kept as a deprecated alias and continues to work unchanged — no migration required. ```tsx // Still works (deprecated) ... // Preferred going forward <Surface render={}>... ``` - 9272b4a: Switch: polish squircle styling - Use `ring-inset` on thumb to prevent border protruding beyond the track - Make thumb ring transparent to remove visible border outline - Switch focus indicator from `ring` to `outline` with `outline-offset-2` to avoid clashing with the track's own ring border - 6b15bac: fix(Tabs): update segmented tab spacing and track styling - Adjust segmented `Tabs` list styling colour to `bg-kumo-recessed` and added `ring` to make the Tabs background more visible - Remove extra edge spacing and keep the segmented track/indicator alignment consistent - cfe814d: update toast styling to use a subtle ring and background that reflect each state. - 7ac73d2: update status text token values for info and danger to improve a11y contrast ratio on banners. - dcbf185: Add `truncate` prop to `Text` component. When `true`, applies `truncate min-w-0` classes to clip overflowing text with an ellipsis.

### Minor Changes - c5f69b9: Make Chart components keyboard focusable with tabindex. Timeseries adds `ariaDescription` prop ### Patch Changes - b3c44f1: Generate component-registry files at build time, remove from git Eliminates contributor friction by generating component-registry.json, component-registry.md, and schemas.ts during the build process instead of tracking them in git. Contributors will no longer see stale diffs or need to manually regenerate these files. - Add ai/component-registry.json and ai/component-registry.md to .gitignore - Convert ai/schemas.ts to a stub file for TypeScript compilation - Add codegen:registry to build script for deterministic generation - 759f4e8: feat(code): add HCL (HashiCorp Configuration Language) as a supported syntax highlighting language - a67fac7: fix(flow): connector lines no longer misalign when the page scrolls or a sidebar shifts the layout `getBoundingClientRect` values were stored in React state per node and later subtracted against a freshly-read container rect at connector-draw time. Any layout shift (sidebar open/close, page scroll, inner container scroll) between those two reads produced stale coordinates, causing connector lines to jump out of place or disappear entirely. Fix: add `scroll` and `resize` listeners (capture phase) at the `FlowNode`, `FlowParallelNode`, and `FlowNodeList` levels so all rects are remeasured after any layout shift. Connector computation in `FlowNodeList` and `FlowParallelNode` is also moved from the render phase into `useLayoutEffect` so the container rect and node rects are always read in the same synchronous pass. - 15a344e: Add missing HCL language import to server-side Shiki bundle The HCL language was added to SupportedLanguage type and the client-side provider in a previous commit, but the server.tsx BUNDLED_LANGS object was missed. This caused typecheck failures when building. - 5d8d3a9: Sidebar: polish animations, fix separator reflow bug, improve header spacing - 7e82920: Fix connector alignment and spacing between adjacent parallel nodes in Flow diagrams

### Minor Changes - 73f554a: Add success and info toast variants with semantic token styling. Migrate error/warning variants from raw CSS to semantic tokens for consistent theming. ### Patch Changes - 9fbf3a8: Fix Radio compound component to use Object.assign pattern, enabling sub-component detection (Radio.Group, Radio.Item) in the component registry. - 3430785: Revert outline button variant ring width from `ring-2` (2px) back to `ring` (1px) to restore visual consistency with existing dashboard usage.

### Patch Changes - 839b0cb: fix: update styling for mostly-used components with new greyscale tokens (combobox, dialog, input, layerCard, select & tabs) as well as homegrid and component preview backgrounds. - 7083a17: Remove es2022 build target that caused Jest/babel-jest test failures in stratus

### Minor Changes - 8b2d6a0: Add radio card appearance via `appearance="card"` prop on Radio.Group and Radio.Item. Cards display a bordered, selectable container with title and description. Also adds `description` prop to Radio.Item for helper text. Supports vertical and horizontal orientations, error state, and disabled state. - abbf586: Expose Chart `optionUpdateBehavior` to control how ECharts applies option updates; `notMerge` now defaults to `false`. - c6aa554: Add neutral variant to Switch component and improve accessibility - New `variant="neutral"` option: monochrome switch with squircle shape, matching the design from stratus - Improved off-state visibility for default variant with darker background/ring colors - Removed `error` variant (not useful for toggle switches) - Added defensive fallback so invalid variant values don't cause runtime crashes ### Patch Changes - f2e17d7: removed `outline-none` to bring back focus states on all buttons - eba693e: Fix flaky vitest "Closing rpc while fetch was pending" error in deep-imports test - db91f50: Fix InputArea label click not focusing textarea. Use FieldBase.Control with render callback to properly associate the label with the textarea element. - 80afd4d: Fix TypeScript return types for ShikiProvider and CodeHighlighted components. Changed return type from `ReactNode` to `React.JSX.Element` to resolve JSX compatibility errors. This fixes issues when consuming these components in projects with stricter TypeScript configurations (e.g., `skipLibCheck: false`), where `ReactNode` was incorrectly inferred as a valid JSX element return type. - dc9742d: Fix table header font size to ensure consistent rendering across dashboards with different default font sizes - f94fee7: Add dedicated `kumo-placeholder` text color token and use it for Input, InputArea, SensitiveInput, and CommandPalette placeholder text. The new token provides better visual distinction between placeholder and active text in both light and dark modes. - 66012b7: Replace the package-level ESLint pass with Oxlint JS plugin coverage for the remaining jsx-a11y rules, and pin the library build to `es2022` with a post-build browser-compat test that blocks newer runtime APIs from shipping in `dist`. - e8acdd8: fix(Select): prevent chevron overflow with long multi-select values Added `min-w-0 truncate` to the value element and `shrink-0` to the chevron icon so that long option names truncate gracefully instead of pushing the chevron outside the select bounds.

### Patch Changes - c272f6a: Fix combobox caret icon to use text-kumo-subtle with fill-current instead of invalid fill-kumo-subtle token - 5e12c15: fix TimeseriesChart brush cursor not activating when loading prop transitions from true to false

### Minor Changes - 56a8b35: add xAxisTickFormat, yAxisTickFormat, and tooltipValueFormat props to TimeseriesChart; deprecate yAxisTickLabelFormat ## Deprecation: yAxisTickLabelFormat is deprecated If you were using `yAxisTickLabelFormat` to customize tooltip output, switch to `tooltipValueFormat`. **Before:** ```tsx `${v} req/s`} /> ``` **After:** ```tsx `${v} req/s`} /> ```

### Patch Changes - eda8362: Fix combobox caret icon visibility by using fill-kumo-subtle instead of fill-kumo-ring

### Minor Changes - 4d6de27: reorganize greyscale tokens and update color preferences ### Patch Changes - 2ff49b7: updated button styles for outline and secondary - 59f7935: Fix Jest module resolution failures and reduce Shiki bundle size **Jest Fix:** - Add `chunkFileNames` config to prevent double-dash filenames (e.g., `combobox--ec3iibR.js`) that Jest cannot resolve - Move chunks to `dist/chunks/` subdirectory for cleaner structure **Bundle Size Reduction:** - Switch from full Shiki bundle to fine-grained imports via `shiki/core` - Reduce from ~300 language/theme chunks to ~16 bundled languages - Total JS files reduced from 358 to ~163 (54% reduction) **Supported Languages:** `javascript`, `typescript`, `jsx`, `tsx`, `json`, `jsonc`, `html`, `css`, `python`, `yaml`, `markdown`, `graphql`, `sql`, `bash`, `shell`, `diff` **Breaking Change:** - `BundledLanguage` type is now deprecated, use `SupportedLanguage` instead - Only the languages listed above are bundled; other Shiki languages are no longer available out of the box - 9eaf584: Fix npm publish failure by removing cross-package dependency from prepublish hook

### Minor Changes - 140f4ab: **Select: Improved label API to match Input component pattern** - `hideLabel` is now deprecated. When `label` is provided, the label is **visible by default** (previously hidden by default). - For visible labels: `` (no changes needed if you were using `hideLabel={false}`) - For hidden labels: Use `` instead of `` - **Bug fix**: Placeholder text now displays correctly when using object map `items` format (e.g., `items={{ a: "Option A" }}`). Previously, placeholders only worked with array format items. **Backward compatibility**: `hideLabel={true}` still works but shows a deprecation warning in development. Existing code using `hideLabel={false}` requires no changes. **Migration guide:** ```tsx // Before (label hidden by default) // label was sr-only // label was visible // After (label visible by default, matching Input) // label is now visible // use aria-label for hidden labels ``` - f1c6392: Add optional `id` prop to `Flow.Node` for stable node identification and connector test IDs - da03394: Avoid adding multiple toasts with the same ID. Use a subtle bump animation when a toast with an existing ID is added. ### Patch Changes - a53ec1b: Fix theme token flicker by generating stable light/dark fallback variables with safer scope and layer precedence. - cb121bc: fix: add defensive styles to prevent global CSS pollution ## Problem When Kumo components are used in applications with aggressive global styles (e.g., Stratus's `cfBaseStyles` layer), certain elements get polluted: - `label { margin-bottom: 1rem }` adds unwanted margins to all labels - `button { background: gray }` affects unstyled button wrappers (e.g., tooltip triggers) - `a { color: var(--text-color-primary) }` can override link colors if the consuming app defines `--text-color-primary` differently ## Solution Add defensive Tailwind utility classes directly to components. These: 1. Reset commonly-polluted properties to safe defaults 2. Use `cn()` (tailwind-merge) so consumer styles via `className` still override them 3. Are no-ops in clean CSS environments (no visual change in Kumo docs) ## Changes ### Label margins (`m-0`) - **Label**: `labelVariants()` now includes `m-0` - **Field**: `FieldBase.Label` gets `m-0` - **Checkbox**: label wrapper gets `m-0` - **Radio**: label wrapper gets `m-0` - **Switch**: label wrapper gets `m-0` ### Button trigger resets - **Tooltip trigger** (when `!asChild`): `bg-transparent border-none shadow-none p-0 m-0 h-auto min-h-0 leading-[0] inline-flex items-center` - **Collapsible trigger**: `bg-transparent border-none shadow-none p-0 m-0` ### Link color namespace fix - **Link**: Changed from `text-primary` to `text-kumo-link` to avoid collision with consuming apps that define `--text-color-primary` differently ### Label tooltip composition - **Label**: Tooltip trigger now uses `` with `asChild`, leveraging composition instead of relying on defensive resets ## Docs Added "Custom Trigger" section to Tooltip docs demonstrating that `className` can fully override defensive styles when not using `asChild`. - c6a3fb3: fix(dropdown): use Base UI CheckboxItemIndicator for proper accessibility Replace custom Checkbox component with Base UI's CheckboxItemIndicator in DropdownMenuCheckboxItem. The previous implementation nested an interactive Checkbox inside the menuitemcheckbox role, causing duplicate accessibility labels. CheckboxItemIndicator is automatically aria-hidden and only renders when checked, following the standard Base UI pattern. - 1bfffaa: Fix Field error message line height by adding `leading-snug` for consistent text spacing - 5d16fdb: Improve info banner dark mode contrast for WCAG AA compliance. Changes `kumo-info` from `blue-700` (L=48.8%) to `blue-400` (L=70.7%), achieving 7.97:1 contrast ratio against the banner background. - 8b964f5: Fix Combobox.TriggerValue icon misalignment caused by inherited line-height The caret icon span was inheriting `line-height` from the parent button's `text-base` class, causing the span's height to exceed the icon's height (e.g., 21.5px vs 16px). The icon sits at the top of the span by default, so when the span is centered via `top-1/2 -translate-y-1/2`, the icon appears offset. Added `flex items-center` to the icon wrapper to ensure proper vertical centering regardless of inherited styles. This matches the pattern used in TriggerInput. - 529274d: fix(Pagination): use aria-label instead of label for PageSize select The Select component now shows visible labels by default. Since Pagination.PageSize already displays "Per page:" text next to the select, the internal Select should use `aria-label` for accessibility without showing a duplicate visible label. - 2f0e572: chore(toast): replace inline XIcon with Phosphor icon - ee1099d: Prevent password managers autofilling Pagination input field - 6dc952f: fix(tabs): improve focus ring and hover styling - Fixed focus ring to use proper `ring-kumo-ring` token instead of browser default blue - Segmented variant: inset focus ring to avoid overlap with adjacent tabs, hidden on active tab - Underline variant: added padding for better focus ring spacing around text - Added subtle hover states for both variants - 2352344: fix(Tabs): pass TabItem render prop through to Base UI for custom tab rendering (e.g., link-based tabs)

### Minor Changes - 5505610: Add Shiki-powered `CodeHighlighted` component for syntax highlighting - **New entry point**: `@cloudflare/kumo/code` - keeps Shiki out of main bundle - **ShikiProvider**: Lazy-loads Shiki on first render, shares instance across all children - **CodeHighlighted**: Syntax highlighting with line numbers, line highlighting, copy button - **Server utilities**: `@cloudflare/kumo/code/server` for SSR/static highlighting - **Themes**: Ships with `github-light` and `vesper` defaults, supports any Shiki theme - **i18n**: Customizable labels via provider or per-component - **CSS customization**: `--kumo-code-highlight-bg` variable for highlight color - **Deprecates**: Legacy `Code` and `CodeBlock` components (will be removed in v2) - 003128b: feat(combobox): add size prop with xs, sm, base, lg variants matching Input component - 1cad157: feat(flow): make nested lists work inside parallel nodes - 9d89256: Add `role` prop to Dialog component supporting both `"dialog"` (default) and `"alertdialog"` ARIA roles **New Feature:** - `Dialog.Root` now accepts a `role` prop to specify the dialog's ARIA semantics - When `role="alertdialog"` is used, the dialog uses Base UI's AlertDialog primitives for proper accessibility - This provides correct screen reader announcements for confirmation and destructive action dialogs **When to use `role="alertdialog"`:** - Destructive actions (delete, discard, remove) - Confirmation flows requiring explicit user acknowledgment - Actions that cannot be undone - Critical warnings or errors **Example:** ```tsx // Standard dialog (default) Edit} /> ... // Alert dialog for destructive actions Delete} /> ... ``` - e6218d2: Add TimeseriesChart component with ECharts integration, supporting legends, gradient fills, custom axis formatting, loading skeleton state, and configurable color palettes. - a7eb061: feat(select): auto-render options from items prop when children omitted The Select component now automatically renders Select.Option elements from the items prop when children are not explicitly provided. ### Patch Changes - 5943e77: Add missing `success` background and tint semantic color tokens (`bg-kumo-success`, `bg-kumo-success-tint`) for parity with `info`, `warning`, and `danger`. Fix `text-kumo-success` dark mode contrast by using `green-400` instead of `green-500`. Add new `success` Badge variant for positive state indicators. - 35d5c42: fix(breadcrumbs): improve mobile breadcrumb readability breadcrumbs now render a compact mobile trail for deeper hierarchies by collapsing early levels to `...` and keeping the trailing path visible. labels in breadcrumb links and the current page now truncate correctly to prevent stacking or overlap on narrow viewports. - 02d0d65: fix(badge): prevent crash when unknown variant is passed Add defensive fallback to primary variant when an unrecognized variant string is provided to Badge component. This prevents "Cannot read properties of undefined (reading 'classes')" errors when consumers use a variant that doesn't exist in their installed version. - 3170d65: fix(code): Fix CodeHighlighted dark mode, layout, and SSR issues - Fix dark mode: Make `` background transparent so container's `bg-kumo-base` handles theming and border-radius is respected - Fix layout: Wrap Shiki output in overflow container to prevent line highlight negative margins from being clipped - Fix width: Add `w-full` to container for proper full-width display - Fix SSR: Remove `"use client"` directive from `@cloudflare/kumo/code/server` entry point so server utilities work in RSC/SSR contexts - 31ce577: fix(CommandPalette): add explicit text-base class to Item component for consistent 14px font size - ee5a632: Fix Select to render description and error when hideLabel is true Previously, the `description` and `error` props were silently ignored when `hideLabel` was `true` (the default). Now, helper text and error messages display correctly even when the label is visually hidden. - 409d32b: Fix TypeScript errors when consumers type-check their projects with kumo installed. Previously, TypeScript would attempt to type-check raw `.tsx` and `.ts` source files shipped in the package (block sources in `dist/src/blocks/`, `ai/schemas.ts`, and `scripts/theme-generator/*.ts`), causing build failures in downstream projects. This change: - Moves block source files to a separate `dist/blocks-source/` directory - Compiles `ai/schemas.ts` and `scripts/theme-generator/*.ts` to JavaScript - Updates package exports to point to compiled `.js` files with proper `.d.ts` types - 7816318: fix(inputs): expand small control hit areas - e7f0c80: Fix pagination component to properly wrap numbers in `tabular-nums` class for consistent number alignment. Both the page range and total count now use tabular numerals. - c0341b4: Simplify Select placeholder implementation by using Base UI's native placeholder prop on SelectBase.Value instead of manually injecting placeholder items into the items array. This provides a cleaner, more intuitive API that aligns with standard HTML select behavior while maintaining backward compatibility with the null-value placeholder pattern. - 35d5c42: fix(breadcrumbs): enhance mobile breadcrumb display for better readability - abb7f8c: Add `variant="compact"` prop to Table.Header for a more condensed header style - 8972cc4: Fix Combobox group label styling to use semantic token and correct padding - bb49d4b: Standardize z-index usage with isolation containment - Add `isolation: isolate` to components with internal stacking (Tabs, MenuBar, InputGroup, Flow/Parallel) - Simplify internal z-index values to `z-0`/`z-1`/`z-2` instead of arbitrary values like `z-10`/`z-20` - Remove superfluous `z-10` from CommandPalette List - Update Toast viewport to `z-1` (matching Base UI's documented pattern) - Update ClipboardText viewport to use `isolate` instead of `z-50` This prevents z-index values from leaking outside component boundaries.

### Minor Changes - 23865db: feat(dropdown): add LinkItem for navigation links and fix icon rendering **New Features:** - Add `DropdownMenu.LinkItem` for navigation links (semantic `` element with proper menu item behavior) - Upgrade `@base-ui/react` from 1.0.0 to 1.2.0 - Add new primitives: `csp-provider` and `drawer` from Base UI 1.2.0 **Bug Fixes:** - Fix `icon` prop not rendering on `DropdownMenu.Item` when no `href` is provided **Deprecations:** - `href` prop on `DropdownMenu.Item` is deprecated. Use `DropdownMenu.LinkItem` instead. **Migration:** ```tsx // Before (deprecated) Link // After (recommended) Link ``` `DropdownMenu.LinkItem` gives you full control over link attributes (`target`, `rel`, etc.) without the component making assumptions about your intent. - 68c2f0d: Add `positionMethod` prop to `Popover.Content` to control CSS positioning strategy. Use `"fixed"` when the popover needs to escape stacking contexts (e.g., inside sticky headers). Defaults to `"absolute"`. ### Patch Changes - 89cb5ec: Improve Flow diagram components with disabled node support and better connector rendering: - Add `disabled` prop to FlowNode for greying out connectors - Add `align` prop to FlowParallelNode for start/end alignment - Improve connector path rendering with smarter junction detection - Fix panning behavior to not interfere with node interactions

### Minor Changes - cf4ff38: Refactor Banner component with softer styling and i18n-friendly props - Added `title` and `description` props for structured content with i18n support - Softened visual appearance: reduced background opacity (20% -> 10%), muted border colors - Text now uses `text-kumo-default` for readability, with colored icons for variant indication - Added `iconClasses` to variant config for per-variant icon coloring - Component now uses `forwardRef` and sets `displayName` per conventions - Deprecated `children` and `text` props in favor of `title`/`description` - Legacy `children` prop still works for backwards compatibility ### Patch Changes - 0ca3b05: Fix Checkbox ring color to use `ring-kumo-contrast` when checked or indeterminate - f69df6d: Fix Combobox dropdown scrolling regression and improve scroll behavior. **Bug fix:** The `overflow-hidden` class was accidentally re-introduced during a semantic color token migration, which overrode `overflow-y-auto` and caused dropdown content to be clipped instead of scrollable. **Improvement:** Restructured Combobox.Content to use flexbox layout so that when using `Combobox.Input` inside the dropdown (searchable popup pattern), the input stays fixed at the top while only the list scrolls. Previously, the entire popup content would scroll together. **Scrollbar fix:** Moved horizontal padding from the popup container to individual child components, so the scrollbar renders flush with the popup edge instead of being inset (which was clipping the checkmark indicators).

### Minor Changes - d9b6498: feat(flow): add FlowDiagram components for building directed flow diagrams New components for visualizing workflows and data flows: - `FlowDiagram` - Root container with pan/scroll support for large diagrams - `FlowNode` - Individual node with automatic connector points - `FlowNode.Anchor` - Custom attachment points for connectors within nodes - `FlowParallelNode` - Container for parallel branches with junction connectors Adds `motion` as a new dependency for smooth panning interactions. ### Patch Changes - 835a7c0: Deprecate DateRangePicker in favor of DatePicker with `mode="range"` - Added `@deprecated` JSDoc comments to DateRangePicker component and its exports - IDEs will now show deprecation warnings guiding users to use DatePicker instead - 391f13a: Prevented ClipboardText from overflowing with long text values. - d0e1d29: chore(kumo): add test scripts to root package.json

### Minor Changes - 50d4251: Add DatePicker component built on react-day-picker v9 **New Component: DatePicker** - Three selection modes: `single`, `multiple`, and `range` - Forwards all react-day-picker props for maximum flexibility - Styled with Kumo tokens (no external CSS import needed) - Supports localization via date-fns locales - Supports timezone via `timeZone` prop - Custom modifiers for highlighting specific dates - Footer prop for messages/usage limits - Accessible keyboard navigation with Kumo-styled focus rings **Usage:** ```tsx // Single date // Multiple dates // Date range ``` **Composing with Popover:** ```tsx Pick a date ``` **Note:** Consider using `DatePicker` with `mode="range"` instead of `DateRangePicker` for new projects - it offers more flexibility and a smaller bundle size. **Internal changes:** - Added `react-day-picker` v9 as a dependency - Updated lint rule to allow components without KUMO\_\*\_VARIANTS exports - Updated component registry codegen to handle variant-less components - Disabled `jsx-a11y/no-autofocus` rule (intentional prop forwarding) - 93361ed: feat(clipboard-text): add slide animation with tooltip on copy ### Patch Changes - c71bd9b: Updated the MenuBar so its child buttons align with the container’s outer corners. - 46ecf42: Fix `kumo add` to consolidate imports from `@cloudflare/kumo` into a single statement using inline `type` syntax. Previously, running `kumo add DeleteResource` would produce non-conformant code with duplicate imports: ```typescript import { Dialog, DialogRoot } from "@cloudflare/kumo"; import { Input } from "@cloudflare/kumo"; import { Button } from "@cloudflare/kumo"; ``` Now it produces a single consolidated import: ```typescript import { Dialog, DialogRoot, Input, Button, type DialogProps, } from "@cloudflare/kumo"; ``` This satisfies ESLint's `import/no-duplicates` rule with `prefer-inline: true`. - a9167fa: Fix z-index stacking issues with nested portaled components (e.g., Select inside Dialog) - Remove unnecessary z-index values from Dialog, Select, Combobox, and Dropdown - Delete `.z-modal { z-index: 9999 }` - DOM order now handles stacking naturally - Components opened later correctly appear on top without z-index wars - f02494d: fix(dropdown): improve external link detection to handle http:// and protocol-relative urls updated the external link check to use a regex that matches `https://`, `http://`, and protocol-relative URLs (`//`). previously only `https://` links opened in a new tab.

### Patch Changes - 2c8a5ad: Changed ClipboardIcon to CopyIcon in ClipboardText component - 31cc2e1: Fix AI command USAGE.md path resolution to work correctly from bundled dist output - 1ae7dfd: fix(cli): include block source files in build for `kumo add` command The `kumo add` command was failing because block source files (`.tsx`) were not being copied to `dist/` during the build process. This adds copying of block source files from `src/blocks/` to `dist/src/blocks/` so the CLI can install them into user projects. - fa3eba3: fix(Table): Add indeterminate prop and fix checkbox click handling - Added `indeterminate` prop to `Table.CheckHead` and `Table.CheckCell` components to support indeterminate checkbox state (shows minus icon when some but not all rows are selected) - Fixed checkbox click handling - clicking directly on the checkbox now works correctly (previously only clicking the cell area next to the checkbox worked) - Updated Table demos (`TableSelectedRowDemo` and `TableFullDemo`) with proper React state management for interactive row selection - 3bc976e: fix: delete-resource shouldn't nest buttons within each other - 752fdf1: support overwriting text in pagination component

### Minor Changes - d7a6da3: fix(cli): resolve broken doc/docs/ls commands by fixing registry path from catalog/ to ai/ fix(dialog): wrap sub-components to isolate @base-ui/react type references from downstream consumers fix(label): render as `` element with htmlFor support instead of `` feat(input): add Textarea alias for InputArea feat(toast): add ToastProvider alias for Toasty feat(button): require aria-label on icon-only buttons (shape="square" | "circle") via discriminated union fix(docs): add Tailwind 4 @source directive to usage example, add confirmation dialog recipe, update Select basic example, document icon-only button aria-label pattern

### Patch Changes - b64847d: fix: CLI commands now find component registry and run codegen:registry before publish - ea583d8: fix(cli): resolve registry path for docs and ls commands

### Minor Changes - 71d667b: Add CloudflareLogo component with glyph and full logo variants, color schemes (brand/black/white), and exported SVG path data for custom implementations ### Patch Changes - 262e0e6: Replace `.toSorted()` with `.sort()` on spread copies to fix TypeError on Chrome <110