@cloudflare/kumo 1.17.0 → 1.19.0

package/CHANGELOG.md

@@ -1,5 +1,148 @@
 # @cloudflare/kumo
 
+## 1.19.0
+
+### 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
+  - <Tooltip content="Save" asChild>
+  -   <Button>Save</Button>
+  - </Tooltip>
+  + <Tooltip content="Save" render={<Button>Save</Button>} />
+
+  - <Popover.Trigger asChild>
+  -   <Button>Open</Button>
+  - </Popover.Trigger>
+  + <Popover.Trigger render={<Button>Open</Button>} />
+
+  - <Popover.Close asChild>
+  -   <Button>Close</Button>
+  - </Popover.Close>
+  + <Popover.Close render={<Button>Close</Button>} />
+  ```
+
+  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 `<nav>` 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
+  <Select
+    placeholder="Select..."
+    value={value}
+    onValueChange={setValue} // value is T | null (works with strictNullChecks)
+    renderValue={(v) => 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
+
+## 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

package/ai/USAGE.md

@@ -73,46 +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-surface` | Page background |
-| `bg-kumo-base` | Component background |
-| `bg-kumo-elevated` | Slightly elevated surface |
-| `bg-kumo-recessed` | Recessed surface with a darker colour |
-| `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