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: <Select label="Country" /> (no changes needed if you were using hideLabel={false})
  • For hidden labels: Use <Select aria-label="Select a country" /> instead of <Select label="Country" hideLabel={true} />
• 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:

// Before (label hidden by default)
<Select label="Country" />                    // label was sr-only
<Select label="Country" hideLabel={false} />  // label was visible

// After (label visible by default, matching Input)
<Select label="Country" />                    // label is now visible
<Select aria-label="Country" />               // use aria-label for hidden labels

Add optional id prop to Flow.Node for stable node identification and connector test IDs

Avoid adding multiple toasts with the same ID. Use a subtle bump animation when a toast with an existing ID is added.

Fix theme token flicker by generating stable light/dark fallback variables with safer scope and layer precedence.

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 <Button variant="ghost" size="xs" shape="square"> 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.

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.

Fix Field error message line height by adding leading-snug for consistent text spacing

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.

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.

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.

chore(toast): replace inline XIcon with Phosphor icon

Prevent password managers autofilling Pagination input field

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

fix(Tabs): pass TabItem render prop through to Base UI for custom tab rendering (e.g., link-based tabs)

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)

feat(combobox): add size prop with xs, sm, base, lg variants matching Input component

feat(flow): make nested lists work inside parallel nodes

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:

// Standard dialog (default)
<Dialog.Root>
  <Dialog.Trigger render={(p) => <Button {...p}>Edit</Button>} />
  <Dialog>...</Dialog>
</Dialog.Root>

// Alert dialog for destructive actions
<Dialog.Root role="alertdialog">
  <Dialog.Trigger render={(p) => <Button variant="destructive" {...p}>Delete</Button>} />
  <Dialog>...</Dialog>
</Dialog.Root>

Add TimeseriesChart component with ECharts integration, supporting legends, gradient fills, custom axis formatting, loading skeleton state, and configurable color palettes.

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.

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.

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.

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.

fix(code): Fix CodeHighlighted dark mode, layout, and SSR issues

• Fix dark mode: Make <pre> 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

fix(CommandPalette): add explicit text-base class to Item component for consistent 14px font size

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.

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

fix(inputs): expand small control hit areas

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.

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.

fix(breadcrumbs): enhance mobile breadcrumb display for better readability

Add variant="compact" prop to Table.Header for a more condensed header style

Fix Combobox group label styling to use semantic token and correct padding

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.

feat(dropdown): add LinkItem for navigation links and fix icon rendering

New Features:

• Add DropdownMenu.LinkItem for navigation links (semantic <a> 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:

// Before (deprecated)
<DropdownMenu.Item href="https://example.com">Link</DropdownMenu.Item>

// After (recommended)
<DropdownMenu.LinkItem href="https://example.com" target="_blank">
  Link
</DropdownMenu.LinkItem>

DropdownMenu.LinkItem gives you full control over link attributes (target, rel, etc.) without the component making assumptions about your intent.

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".

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

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

Fix Checkbox ring color to use ring-kumo-contrast when checked or indeterminate

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).

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.

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

Prevented ClipboardText from overflowing with long text values.

chore(kumo): add test scripts to root package.json

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:

// Single date
<DatePicker mode="single" selected={date} onSelect={setDate} />

// Multiple dates
<DatePicker mode="multiple" selected={dates} onSelect={setDates} max={5} />

// Date range
<DatePicker mode="range" selected={range} onSelect={setRange} numberOfMonths={2} />

Composing with Popover:

<Popover>
  <Popover.Trigger asChild>
    <Button variant="outline" icon={CalendarDotsIcon}>
      Pick a date
    </Button>
  </Popover.Trigger>
  <Popover.Content className="p-3">
    <DatePicker mode="single" selected={date} onSelect={setDate} />
  </Popover.Content>
</Popover>

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)

feat(clipboard-text): add slide animation with tooltip on copy

Updated the MenuBar so its child buttons align with the container’s outer corners.

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:

import { Dialog, DialogRoot } from "@cloudflare/kumo";
import { Input } from "@cloudflare/kumo";
import { Button } from "@cloudflare/kumo";

Now it produces a single consolidated import:

import {
  Dialog,
  DialogRoot,
  Input,
  Button,
  type DialogProps,
} from "@cloudflare/kumo";

This satisfies ESLint's import/no-duplicates rule with prefer-inline: true.

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

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.

Changed ClipboardIcon to CopyIcon in ClipboardText component

Fix AI command USAGE.md path resolution to work correctly from bundled dist output

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.

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

fix: delete-resource shouldn't nest buttons within each other

support overwriting text in pagination component

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 <label> element with htmlFor support instead of <span> 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

fix: CLI commands now find component registry and run codegen:registry before publish

fix(cli): resolve registry path for docs and ls commands

Add CloudflareLogo component with glyph and full logo variants, color schemes (brand/black/white), and exported SVG path data for custom implementations

Replace .toSorted() with .sort() on spread copies to fix TypeError on Chrome <110