@cloudflare/kumo 1.16.0 → 1.18.0

package/CHANGELOG.md

@@ -1,5 +1,168 @@
 # @cloudflare/kumo
 
+## 1.18.0
+
+### 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`
+
+## 1.17.0
+
+### 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
+  <KumoPortalProvider container={shadowRoot}>
+    <App />
+  </KumoPortalProvider>
+  ```
+
+  Or override per component:
+
+  ```tsx
+  <Dialog container={customContainer}>
+    <Dialog.Title>Modal inside shadow DOM</Dialog.Title>
+  </Dialog>
+  ```
+
+  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)
+  <Surface as="section">...</Surface>
+
+  // Preferred going forward
+  <Surface render={<section />}>...</Surface>
+  ```
+
+- 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.
+
 ## 1.16.0
 
 ### Minor Changes

package/ai/USAGE.md

@@ -73,44 +73,52 @@ import { Button, Input, Dialog } from "@cloudflare/kumo";
 
 ## Semantic Token Reference
 
+### Surface Hierarchy
+| Token | Purpose |
+|-------|---------|
+| `bg-kumo-canvas` | The outermost page background — sits behind everything |
+| `bg-kumo-base` | Default component background |
+| `bg-kumo-elevated` | Slightly elevated surface, e.g. `LayerCard.Secondary` |
+| `bg-kumo-recessed` | Recessed surface with a subtly darker fill, e.g. segmented `Tabs` background |
+| `bg-kumo-tint` | Subtle tinted background for tables or hover states |
+| `bg-kumo-contrast` | High-contrast, inverted background |
+
+### Brand
+| Token | Purpose |
+|-------|---------|
+| `bg-kumo-brand` | Primary brand background |
+| `bg-kumo-brand-hover` | Hover state for brand backgrounds |
+
+### Semantic Status Colors
+| Token | Purpose |
+|-------|---------|
+| `bg-kumo-info` | Info indicator (icon, dot, bar) |
+| `bg-kumo-success` | Success indicator |
+| `bg-kumo-warning` | Warning indicator |
+| `bg-kumo-danger` | Error/destructive indicator |
+
+Use the solid token on icons, status dots, and progress fills. Banners and badges use the solid fills with a reduced opacity.
+
 ### Text Colors
 | Token | Purpose |
 |-------|---------|
-| `text-kumo-default` | Primary text |
-| `text-kumo-inverse` | Inverse text (on dark backgrounds) |
-| `text-kumo-strong` | Secondary/muted-strong text |
-| `text-kumo-subtle` | Muted/placeholder text |
+| `text-kumo-default` | Primary body text |
+| `text-kumo-strong` | Secondary text with slightly less contrast than default |
+| `text-kumo-subtle` | Muted text for descriptions, captions, or secondary labels |
+| `text-kumo-inactive` | Disabled or inactive text |
+| `text-kumo-placeholder` | Placeholder text in inputs |
+| `text-kumo-inverse` | Text intended for use on high-contrast or inverted backgrounds |
 | `text-kumo-link` | Link text |
+| `text-kumo-info` | Info-colored text |
+| `text-kumo-success` | Success-colored text |
+| `text-kumo-warning` | Warning-colored text |
 | `text-kumo-danger` | Error/destructive text |
-| `text-kumo-success` | Success text |
-| `text-kumo-warning` | Warning text |
-| `text-kumo-brand` | Brand-colored text |
 
-### Background Colors
-| Token | Purpose |
-|-------|---------|
-| `bg-kumo-base` | Page/card background |
-| `bg-kumo-elevated` | Slightly elevated surface |
-| `bg-kumo-overlay` | Overlay/hover background |
-| `bg-kumo-contrast` | High-contrast background (inverted) |
-| `bg-kumo-control` | Form control background |
-| `bg-kumo-fill` | Muted fill (borders, badges) |
-| `bg-kumo-fill-hover` | Hover state for fills |
-| `bg-kumo-tint` | Subtle tinted background |
-| `bg-kumo-interact` | Interactive element background |
-| `bg-kumo-brand` | Brand primary background |
-| `bg-kumo-brand-hover` | Brand hover background |
-| `bg-kumo-danger` | Error/destructive background |
-| `bg-kumo-success` | Success background |
-| `bg-kumo-warning` | Warning background |
-
-### Border/Ring Colors
+### Borders & Rings
 | Token | Purpose |
 |-------|---------|
-| `border-kumo-fill` | Default border |
-| `border-kumo-line` | Subtle separator line |
-| `ring-kumo-line` | Default ring (input borders) |
-| `ring-kumo-ring` | Focus ring |
+| `kumo-hairline` | A border/ring color to distinguish between flat surfaces where no shadow is present (i.e. `LayerCard`). |
+| `kumo-line` | A thicker border/ring color that defines the edge of an elevated surface alongside a shadow. |
 
 ## Icons