kumo-svelte 0.9.0 → 0.12.0

package/README.md

@@ -2,6 +2,10 @@
 
 Cloudflare's component library for building modern web applications, ported to Svelte.
 
+> This is an independent community package and is not affiliated with, sponsored by, or endorsed by Cloudflare.
+
+The expanded fidelity test coverage was contributed by [axel-rock](https://github.com/axel-rock/kumo-svelte).
+
 Kumo Svelte provides accessible, design-system-compliant UI components built on [Bits UI](https://bits-ui.com/). It handles keyboard navigation, focus management, and ARIA attributes so you can build accessible applications without thinking through every detail.
 
 <img width="2560" height="1456" alt="Kumo UI preview" src="https://github.com/user-attachments/assets/032f5a0e-b686-4440-b1ca-6182379479aa" />

package/ai/component-registry.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.9.0",
+  "version": "0.12.0",
   "components": {
     "Autocomplete": {
       "name": "Autocomplete",
@@ -75,6 +75,29 @@
           "type": "(open: boolean) => void",
           "optional": true,
           "description": "Called when open state changes."
+        },
+        "disabled": {
+          "type": "boolean",
+          "optional": true,
+          "default": "false",
+          "description": "Prevents interaction with the field."
+        },
+        "size": {
+          "type": "enum",
+          "optional": true,
+          "values": [
+            "xs",
+            "sm",
+            "base",
+            "lg"
+          ],
+          "default": "base",
+          "description": "Size preset."
+        },
+        "filter": {
+          "type": "((item: AutocompleteItem, query: string) => boolean) | null",
+          "optional": true,
+          "description": "Custom filter function. Set to null to disable filtering."
         }
       },
       "colors": [
@@ -320,6 +343,11 @@
           "optional": true,
           "description": "Additional classes merged onto the root element."
         },
+        "icon": {
+          "type": "Component",
+          "optional": true,
+          "description": "Icon rendered before the content on filled badges."
+        },
         "children": {
           "type": "Snippet",
           "optional": false,
@@ -337,6 +365,7 @@
         "bg-kumo-badge-red",
         "bg-kumo-badge-teal",
         "bg-kumo-badge-teal-subtle",
+        "bg-kumo-base",
         "bg-kumo-danger-tint",
         "bg-kumo-fill",
         "bg-kumo-info-tint",
@@ -1691,7 +1720,7 @@
       },
       "colors": [
         "border-kumo-fill",
-        "text-kumo-link"
+        "text-kumo-default"
       ],
       "subComponents": {
         "DefaultPanel": {
@@ -1938,6 +1967,27 @@
           "type": "(open: boolean) => void",
           "optional": true,
           "description": "Called when open state changes."
+        },
+        "disabled": {
+          "type": "boolean",
+          "optional": true,
+          "default": "false",
+          "description": "Prevents interaction with the field."
+        },
+        "defaultValue": {
+          "type": "unknown",
+          "optional": true,
+          "description": "Initial value."
+        },
+        "filter": {
+          "type": "((item: ComboboxItem, query: string) => boolean) | null",
+          "optional": true,
+          "description": "Custom filter function. Set to null to disable filtering."
+        },
+        "isItemEqualToValue": {
+          "type": "(item: unknown, value: unknown) => boolean",
+          "optional": true,
+          "description": "Custom value equality matcher function."
         }
       },
       "colors": [
@@ -2005,6 +2055,66 @@
               "optional": true,
               "default": "4",
               "description": "Offset between the popup and the trigger."
+            },
+            "customAnchor": {
+              "type": "string | HTMLElement | Measurable | null",
+              "optional": true,
+              "description": "Custom element or virtual anchor used to position the popup."
+            },
+            "strategy": {
+              "type": "enum",
+              "optional": true,
+              "values": [
+                "absolute",
+                "fixed"
+              ],
+              "description": "CSS positioning strategy used by the floating content."
+            },
+            "avoidCollisions": {
+              "type": "boolean",
+              "optional": true,
+              "default": "true",
+              "description": "Adjust placement to avoid crossing collision boundaries."
+            },
+            "collisionBoundary": {
+              "type": "Boundary | Boundary[]",
+              "optional": true,
+              "description": "Boundary elements used for collision detection."
+            },
+            "collisionPadding": {
+              "type": "number | Partial<Record<Side, number>>",
+              "optional": true,
+              "default": "8",
+              "description": "Padding kept between the popup and collision boundaries."
+            },
+            "sticky": {
+              "type": "enum",
+              "optional": true,
+              "values": [
+                "partial",
+                "always"
+              ],
+              "description": "How the popup remains attached when its anchor approaches a boundary."
+            },
+            "hideWhenDetached": {
+              "type": "boolean",
+              "optional": true,
+              "description": "Hide the popup when its anchor is fully clipped."
+            },
+            "updatePositionStrategy": {
+              "type": "enum",
+              "optional": true,
+              "values": [
+                "optimized",
+                "always"
+              ],
+              "default": "'optimized'",
+              "description": "How frequently floating position updates are calculated."
+            },
+            "container": {
+              "type": "HTMLElement | string",
+              "optional": true,
+              "description": "Portal target for the popup content."
             }
           }
         },
@@ -2111,11 +2221,9 @@
         "bg-kumo-elevated",
         "bg-kumo-overlay",
         "bg-kumo-warning",
-        "border-kumo-line",
         "ring-kumo-brand",
         "ring-kumo-hairline",
         "text-kumo-default",
-        "text-kumo-placeholder",
         "text-kumo-subtle"
       ],
       "subComponents": {
@@ -3611,8 +3719,6 @@
         "bg-kumo-base",
         "bg-kumo-elevated",
         "ring-kumo-fill",
-        "ring-kumo-hairline",
-        "ring-kumo-line",
         "text-kumo-subtle"
       ]
     },
@@ -3697,9 +3803,9 @@
       "name": "MenuBar",
       "type": "component",
       "category": "Navigation",
-      "description": "A horizontal menu bar with icon buttons, commonly used for text editors or toolbars.",
-      "importPath": "kumo-svelte/components/menubar",
-      "sourceFile": "components/menubar",
+      "description": "Deprecated horizontal menu bar. Use segmented Tabs for new work.",
+      "importPath": "kumo-svelte/components/menu-bar",
+      "sourceFile": "components/menu-bar",
       "props": {
         "class": {
           "type": "string",
@@ -3725,7 +3831,14 @@
           "description": "When true, each option's id is used for active matching instead of its array index."
         }
       },
-      "colors": []
+      "colors": [
+        "bg-kumo-base",
+        "bg-kumo-recessed",
+        "border-kumo-recessed",
+        "ring-kumo-brand",
+        "ring-kumo-focus",
+        "ring-kumo-line"
+      ]
     },
     "Meter": {
       "name": "Meter",
@@ -3981,9 +4094,10 @@
       },
       "colors": [
         "bg-kumo-base",
+        "fill-kumo-arrow-edge",
+        "fill-kumo-arrow-stroke",
         "fill-kumo-base",
-        "fill-kumo-tip-shadow",
-        "fill-kumo-tip-stroke",
+        "ring-kumo-line",
         "text-kumo-default",
         "text-kumo-subtle"
       ]
@@ -4529,10 +4643,14 @@
       },
       "colors": [
         "bg-kumo-base",
+        "bg-kumo-elevated",
+        "bg-kumo-hairline",
         "bg-kumo-tint",
+        "border-kumo-line",
         "ring-kumo-brand",
         "ring-kumo-danger",
         "ring-kumo-focus",
+        "ring-kumo-hairline",
         "ring-kumo-line",
         "text-kumo-default",
         "text-kumo-placeholder",
@@ -4816,6 +4934,11 @@
               "optional": true,
               "description": "Tooltip label shown when the sidebar is collapsed."
             },
+            "itemId": {
+              "type": "string",
+              "optional": true,
+              "description": "Anchor id used by useSidebar().scrollToItem()."
+            },
             "children": {
               "type": "Snippet",
               "optional": true,
@@ -4828,6 +4951,26 @@
             }
           }
         },
+        "MenuItem": {
+          "description": "Sidebar.MenuItem",
+          "props": {
+            "itemId": {
+              "type": "string",
+              "optional": true,
+              "description": "Anchor id used by useSidebar().scrollToItem()."
+            },
+            "children": {
+              "type": "Snippet",
+              "optional": true,
+              "description": "Menu item content."
+            },
+            "class": {
+              "type": "string",
+              "optional": true,
+              "description": "Additional classes."
+            }
+          }
+        },
         "MenuSubButton": {
           "description": "Sidebar.MenuSubButton",
           "props": {
@@ -5740,7 +5883,6 @@
       "colors": [
         "bg-kumo-base",
         "bg-kumo-brand",
-        "bg-kumo-elevated",
         "bg-kumo-recessed",
         "bg-kumo-tint",
         "border-kumo-hairline",
@@ -5764,6 +5906,7 @@
           "type": "enum",
           "optional": true,
           "values": [
+            "heading",
             "heading1",
             "heading2",
             "heading3",
@@ -5775,7 +5918,7 @@
             "error"
           ],
           "default": "body",
-          "description": "Visual variant."
+          "description": "Visual variant. Numbered heading variants are deprecated; use heading with size and as."
         },
         "size": {
           "type": "enum",
@@ -5787,7 +5930,7 @@
             "lg"
           ],
           "default": "base",
-          "description": "Size preset."
+          "description": "Size preset. Heading accepts lg for a 20px heading; its default is 16px."
         },
         "bold": {
           "type": "boolean",
@@ -6030,7 +6173,7 @@
             "lg"
           ],
           "default": "base",
-          "description": "Locks every toolbar item to this size."
+          "description": "Deprecated. Sets every toolbar item to this size; omit it for the base size."
         },
         "class": {
           "type": "string",
@@ -6199,9 +6342,9 @@
       },
       "colors": [
         "bg-kumo-base",
+        "fill-kumo-arrow-edge",
+        "fill-kumo-arrow-stroke",
         "fill-kumo-base",
-        "fill-kumo-tip-shadow",
-        "fill-kumo-tip-stroke",
         "text-kumo-default"
       ]
     }

package/ai/component-registry.md

@@ -1,6 +1,6 @@
 # Kumo Svelte Component Registry
 
-Version: 0.9.0
+Version: 0.12.0
 
 ## Autocomplete
 
@@ -236,11 +236,11 @@ A loading spinner to indicate loading state.
 
 ## MenuBar
 
-A horizontal menu bar with icon buttons, commonly used for text editors or toolbars.
+Deprecated horizontal menu bar. Use segmented Tabs for new work.
 
 - Category: Navigation
-- Import: `import { MenuBar } from "kumo-svelte/components/menubar";`
-- Source: `components/menubar`
+- Import: `import { MenuBar } from "kumo-svelte/components/menu-bar";`
+- Source: `components/menu-bar`
 
 ## Meter
 

package/dist/components/autocomplete/Autocomplete.svelte

@@ -12,6 +12,7 @@
     type NormalizedAutocompleteItem
   } from './context';
   import { createKumoFilter } from '../filter';
+  import { Combobox as ComboboxPrimitive } from 'bits-ui';
 
   type FieldError = string | { message?: string; match?: boolean };
 
@@ -22,6 +23,7 @@
     value?: AutocompleteValue;
     defaultValue?: AutocompleteValue;
     open?: boolean;
+    disabled?: boolean;
     size?: AutocompleteSize;
     label?: string | Snippet;
     labelTooltip?: string | Snippet;
@@ -41,6 +43,7 @@
     defaultValue,
     value = $bindable(defaultValue ?? ''),
     open = $bindable(false),
+    disabled = false,
     size = 'base',
     label,
     labelTooltip,
@@ -73,6 +76,62 @@
     });
   });
 
+  const serializedOptions = $derived(
+    normalizedItems.map((item, index) => ({
+      ...item,
+      serializedValue: `kumo-autocomplete:${index}`
+    }))
+  );
+
+  function serializeSelectedValue(selectionValue: unknown) {
+    const option = serializedOptions.find((entry) => valuesEqual(entry.value, selectionValue as AutocompleteValue));
+    if (option) return option.serializedValue;
+    return typeof selectionValue === 'string' || typeof selectionValue === 'number' ? String(selectionValue) : undefined;
+  }
+
+  function deserializePrimitiveValue(primitiveValue: string) {
+    const option = serializedOptions.find((entry) => entry.serializedValue === primitiveValue);
+    return option ? option.value : primitiveValue;
+  }
+
+  const primitiveValue = $derived.by(() => {
+    if (Array.isArray(value)) {
+      return value.map(serializeSelectedValue).filter((v): v is string => v !== undefined);
+    }
+    const val = serializeSelectedValue(value);
+    return val !== undefined ? val : '';
+  });
+
+  function handleSingleValueChange(nextValue: string | undefined) {
+    if (nextValue === undefined) return;
+    const deserialized = deserializePrimitiveValue(nextValue);
+    value = deserialized;
+    const option = serializedOptions.find((entry) => entry.serializedValue === nextValue);
+    if (option) {
+      query = option.label;
+    }
+    open = false;
+    onValueChange?.(deserialized);
+    onOpenChange?.(false);
+  }
+
+  function handleMultipleValueChange(nextValue: string[]) {
+    const deserialized = nextValue.map(deserializePrimitiveValue).map(String);
+    value = deserialized;
+    onValueChange?.(deserialized);
+  }
+
+  $effect(() => {
+    if (!open) {
+      if (Array.isArray(value)) {
+        query = value.join(', ');
+      } else {
+        const option = serializedOptions.find((entry) => entry.value === value);
+        query = option ? option.label : String(value ?? '');
+      }
+    }
+  });
+
   function valuesEqual(itemValue: string | number, selectedValue: AutocompleteValue) {
     if (Array.isArray(selectedValue)) return selectedValue.some((selected) => itemValue === selected);
     return itemValue === selectedValue;
@@ -151,13 +210,39 @@
       onOpenChange?.(false);
     },
     isSelected,
-    select
+    select,
+    serializeValue(itemValue: unknown): string {
+      const option = serializedOptions.find((entry) => entry.value === itemValue);
+      return option?.serializedValue ?? String(itemValue ?? '');
+    }
   });
 </script>
 
 {#snippet control()}
   <div bind:this={rootElement} class={cn('relative w-full', className)} {...rest}>
-    {@render children?.()}
+    {#if Array.isArray(value)}
+      <ComboboxPrimitive.Root
+        type="multiple"
+        value={Array.isArray(primitiveValue) ? primitiveValue : []}
+        onValueChange={handleMultipleValueChange}
+        bind:open={open}
+        disabled={disabled}
+        inputValue={query}
+      >
+        {@render children?.()}
+      </ComboboxPrimitive.Root>
+    {:else}
+      <ComboboxPrimitive.Root
+        type="single"
+        value={Array.isArray(primitiveValue) ? (primitiveValue[0] ?? '') : primitiveValue}
+        onValueChange={handleSingleValueChange}
+        bind:open={open}
+        disabled={disabled}
+        inputValue={query}
+      >
+        {@render children?.()}
+      </ComboboxPrimitive.Root>
+    {/if}
   </div>
 {/snippet}
 

package/dist/components/autocomplete/Autocomplete.svelte.d.ts

@@ -11,6 +11,7 @@ export interface Props {
     value?: AutocompleteValue;
     defaultValue?: AutocompleteValue;
     open?: boolean;
+    disabled?: boolean;
     size?: AutocompleteSize;
     label?: string | Snippet;
     labelTooltip?: string | Snippet;

package/dist/components/autocomplete/AutocompleteContent.svelte

@@ -2,6 +2,7 @@
   import type { Snippet } from 'svelte';
   import { getAutocompleteContext } from './context';
   import { cn } from '../../utils/cn';
+  import { Combobox as ComboboxPrimitive } from 'bits-ui';
 
   type AutocompleteContentAlign = 'start' | 'center' | 'end';
   type AutocompleteContentSide = 'top' | 'right' | 'bottom' | 'left';
@@ -30,49 +31,28 @@
   }: Props = $props();
   const context = getAutocompleteContext('Autocomplete.Content');
 
-  const horizontalAlignClasses: Record<AutocompleteContentAlign, string> = {
-    start: 'left-[var(--autocomplete-align-offset)]',
-    center: 'left-1/2 -translate-x-1/2',
-    end: 'right-[var(--autocomplete-align-offset)]'
-  };
-
-  const verticalAlignClasses: Record<AutocompleteContentAlign, string> = {
-    start: 'top-[var(--autocomplete-align-offset)]',
-    center: 'top-1/2 -translate-y-1/2',
-    end: 'bottom-[var(--autocomplete-align-offset)]'
-  };
-
-  const sideClasses: Record<AutocompleteContentSide, string> = {
-    top: 'bottom-full mb-[var(--autocomplete-side-offset)]',
-    right: 'left-full ml-[var(--autocomplete-side-offset)]',
-    bottom: 'top-full mt-[var(--autocomplete-side-offset)]',
-    left: 'right-full mr-[var(--autocomplete-side-offset)]'
-  };
-
-  function toCssUnit(value: Offset) {
-    return typeof value === 'number' ? `${value}px` : value;
+  function toNumberOffset(val: Offset): number {
+    if (typeof val === 'number') return val;
+    const parsed = parseFloat(val);
+    return isNaN(parsed) ? 0 : parsed;
   }
-
-  const positionStyle = $derived(
-    `--autocomplete-align-offset: ${toCssUnit(alignOffset)}; --autocomplete-side-offset: ${toCssUnit(sideOffset)};${style ? ` ${style}` : ''}`
-  );
-  const positionClass = $derived.by(() =>
-    side === 'top' || side === 'bottom'
-      ? cn(sideClasses[side], horizontalAlignClasses[align])
-      : cn(sideClasses[side], verticalAlignClasses[align])
-  );
 </script>
 
 {#if context.open && context.hasTypedSinceFocus && context.filteredItems.length}
-  <div
-    class={cn(
-      'absolute z-50 flex max-h-[min(24rem,calc(100vh-8rem))] min-w-full flex-col overflow-hidden rounded-lg bg-kumo-control py-1.5 text-kumo-default shadow-lg ring ring-kumo-line',
-      positionClass,
-      className
-    )}
-    style={positionStyle}
-    {...rest}
-  >
-    {@render children?.()}
-  </div>
+  <ComboboxPrimitive.Portal>
+    <ComboboxPrimitive.Content
+      class={cn(
+        'z-50 flex max-h-[min(24rem,calc(100vh-8rem))] min-w-[calc(var(--bits-select-anchor-width)+3px)] flex-col overflow-hidden rounded-lg bg-kumo-control py-1.5 text-kumo-default shadow-lg ring ring-kumo-line outline-none',
+        className
+      )}
+      side={side}
+      sideOffset={toNumberOffset(sideOffset)}
+      align={align}
+      alignOffset={toNumberOffset(alignOffset)}
+      style={style}
+      {...rest}
+    >
+      {@render children?.()}
+    </ComboboxPrimitive.Content>
+  </ComboboxPrimitive.Portal>
 {/if}

package/dist/components/autocomplete/AutocompleteFixture.svelte

@@ -0,0 +1,28 @@
+<script lang="ts">
+  import { Autocomplete } from './index';
+
+  interface Props {
+    items?: { label: string; value: string }[];
+    value?: string;
+    error?: string;
+    onValueChange?: (value: unknown) => void;
+  }
+
+  let {
+    items = [],
+    value = $bindable(''),
+    error,
+    onValueChange
+  }: Props = $props();
+</script>
+
+<Autocomplete bind:value {items} {error} {onValueChange} class="w-[220px]">
+  <Autocomplete.InputGroup placeholder="Search countries…" />
+  <Autocomplete.Content>
+    <Autocomplete.List>
+      {#snippet children(item)}
+        <Autocomplete.Item value={item}>{item.label}</Autocomplete.Item>
+      {/snippet}
+    </Autocomplete.List>
+  </Autocomplete.Content>
+</Autocomplete>

package/dist/components/autocomplete/AutocompleteFixture.svelte.d.ts

@@ -0,0 +1,12 @@
+interface Props {
+    items?: {
+        label: string;
+        value: string;
+    }[];
+    value?: string;
+    error?: string;
+    onValueChange?: (value: unknown) => void;
+}
+declare const AutocompleteFixture: import("svelte").Component<Props, {}, "value">;
+type AutocompleteFixture = ReturnType<typeof AutocompleteFixture>;
+export default AutocompleteFixture;

package/dist/components/autocomplete/AutocompleteInputGroup.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
   import { getAutocompleteContext, type AutocompleteSize } from './context';
   import { cn } from '../../utils/cn';
+  import { Combobox as ComboboxPrimitive } from 'bits-ui';
 
   export interface Props {
     class?: string;
@@ -28,17 +29,16 @@
   }
 </script>
 
-<input
+<ComboboxPrimitive.Input
   class={cn(
     'w-full border-0 bg-kumo-control text-kumo-default shadow-xs ring ring-kumo-line outline-none focus:outline-none',
     'placeholder:text-kumo-placeholder disabled:text-kumo-disabled',
     context.invalid
-      ? '!ring-kumo-danger focus:ring-kumo-danger/50 focus:ring-[1.5px]'
+      ? 'ring-kumo-danger! focus:ring-kumo-danger/50 focus:ring-[1.5px]'
       : 'focus:ring-kumo-focus/50 focus:ring-[1.5px]',
     sizes[size ?? context.size],
     className
   )}
-  value={context.query}
   {placeholder}
   aria-invalid={context.invalid || undefined}
   onbeforeinput={(event) => {