entasis 0.10.2 → 0.12.0

package/dist/components/Avatar/avatar.mcp.js

@@ -14,14 +14,19 @@ The Avatar component displays a user's profile picture with fallback initials. I
 ### Core Props
 - **name**: string (required) - Display name; its initials are the fallback when no image renders
 - **src**: string - Image URL; omit it, or let it fail, to render the initials instead
-- **alt**: string - Alternative text for the image (defaults to \`name\`)
+- **alt**: string - Accessible name of the whole avatar (defaults to \`name\`). An empty string makes the avatar decorative: it is hidden from assistive technology
 - **size**: 'small' | 'normal' | 'large' (default: 'normal')
   - small: 24px (1.5rem)
   - normal: 32px (2rem)
   - large: 40px (2.5rem)
 
+### Image Props
+- **image**: { srcset, sizes, crossorigin, referrerpolicy, loading, decoding, fetchpriority } - Native attributes forwarded to the \`<img>\`. Use \`image={{ loading: 'lazy' }}\` to defer offscreen images: the initials stay on screen until the browser has fetched the picture. (The avatar's own \`loading\` prop is the bindable in-flight flag, not the \`<img>\` attribute.)
+
 ### Loading Props
-- **delay**: number (default: 0) - Delay in milliseconds before showing avatar
+- **fallbackDelay**: number (default: 0) - Delay in milliseconds before the initials render while the image is still loading. Until then the surface stays empty, so a fast image never flashes the fallback. A failed image or a missing \`src\` shows the initials immediately
+- **revealDelay**: number (default: 0) - Delay in milliseconds before a loaded image is revealed
+- **delay**: number - Deprecated alias of \`revealDelay\`; it never delays the initials
 - **loading**: boolean (default: false, bindable) - True while the image request is in flight; false with no \`src\`, and false once the image has loaded or failed. A failed image is reported by rendering the initials.
 
 ### Content Slots
@@ -49,6 +54,7 @@ The Avatar component displays a user's profile picture with fallback initials. I
 - **items**: Array<{ src?: string; alt?: string; name: string } & T> (required) - Avatar items
 - **max**: number - Maximum number of avatars to show before "+N" indicator
 - **size**: 'small' | 'normal' | 'large' (default: 'normal')
+- **image**, **fallbackDelay**, **revealDelay**, **loading**: forwarded to every avatar
 
 ### Content Slots
 - **avatar**: Snippet<{ item: T; index: number; avatarProps }> - Custom avatar rendering
@@ -203,9 +209,11 @@ The Avatar component displays a user's profile picture with fallback initials. I
 
 ## Accessibility
 
-- \`alt\` defaults to \`name\`, so the image always carries alt text
-- Fallback to initials when image fails to load
-- Proper foreground for initials display
+- The root is \`role="img"\` named by \`alt ?? name\`, so a loading, loaded or failed image and an avatar without \`src\` are all announced as one image with one name
+- The inner \`<img>\` has an empty \`alt\` and the initials are \`aria-hidden\`, so nothing is read twice
+- \`alt=""\` marks the avatar decorative (\`aria-hidden\` on the root), for an avatar next to its visible name
+- Because the root is an image, prefix and suffix content is presentational to assistive technology; keep interactive controls outside the avatar
+- The root carries \`data-status="idle | loading | loaded | error"\` (\`idle\` means no \`src\`). The default theme crossfades the image over the initials on it; style it with \`group-data-[status=loaded]/avatar:\` or \`[data-status=error]\`
 - The image loading flag is bindable
 
 ## Notes

package/dist/components/Avatar/avatar.props.d.ts

@@ -1,4 +1,5 @@
 import type { Sizes } from '../../types/index.js';
+import type { HTMLImgAttributes } from 'svelte/elements';
 import type { Slot } from '../Slot/slot.js';
 import type { WithAttachments } from '../../types/props.js';
 import type { AvatarThemeProps } from './avatar.theme.js';
@@ -6,21 +7,47 @@ import type { AvatarThemeProps } from './avatar.theme.js';
 export type AvatarItem = {
     /** Image URL. When omitted, or when the image fails, the initials render instead. */
     src?: string;
-    /** Alternative text for the image. Defaults to `name`. */
+    /**
+     * Accessible name of the avatar, announced once for the whole avatar. Defaults to `name`.
+     * An empty string marks the avatar decorative and hides it from assistive technology.
+     */
     alt?: string;
     /** Display name; its initials are the fallback when no image renders. */
     name: string;
 };
+/** Native `<img>` attributes an avatar forwards to its image. */
+export type AvatarImageAttributes = Pick<HTMLImgAttributes, 'srcset' | 'sizes' | 'crossorigin' | 'referrerpolicy' | 'loading' | 'decoding' | 'fetchpriority'>;
+/** Where the image is in its lifecycle; mirrored on the root as `data-status`. */
+export type AvatarStatus = 'idle' | 'loading' | 'loaded' | 'error';
 export type AvatarProps = WithAttachments<AvatarItem & {
     /**
      * The size of the avatar.
      * @default 'normal'
      */
     size?: Sizes;
+    /**
+     * Native attributes forwarded to the `<img>`: `srcset`, `sizes`, `crossorigin`,
+     * `referrerpolicy`, `loading`, `decoding` and `fetchpriority`. With `loading: 'lazy'` the
+     * initials stay on screen until the browser has fetched and decoded the image.
+     */
+    image?: AvatarImageAttributes;
+    /**
+     * The delay in milliseconds before the initials render while the image is still loading.
+     * Until it elapses the surface stays empty, so an image that arrives quickly never flashes
+     * the fallback. A failed image, or an avatar without `src`, shows the initials immediately.
+     * @default 0
+     */
+    fallbackDelay?: number;
     /**
      * The delay in milliseconds before a loaded image is revealed.
      * @default 0
      */
+    revealDelay?: number;
+    /**
+     * Deprecated alias of `revealDelay`: the delay in milliseconds before a loaded image is
+     * revealed. It never delays the initials (that is `fallbackDelay`).
+     * @deprecated Use `revealDelay`.
+     */
     delay?: number;
     /**
      * Whether the image is still loading. Bindable, so a parent can show its own

package/dist/components/Avatar/avatar.theme.js

@@ -1,7 +1,7 @@
 import { setComponentTheme, useComponentTheme } from '../../utils/cva/index.js';
 import { cva } from '../../utils/cva/index.js';
 const defaultAvatar = cva({
-    base: 'relative items-center border border-neutral-muted text-neutral aspect-ratio-1 rounded-full',
+    base: 'group/avatar relative items-center border border-neutral-muted text-neutral aspect-ratio-1 rounded-full',
     variants: {
         size: {
             normal: 'size-8',
@@ -14,7 +14,7 @@ const defaultAvatar = cva({
     }
 });
 const defaultAvatarImage = cva({
-    base: 'rounded-full absolute top-0 left-0 z-0 object-cover w-full max-w-full h-full max-h-full',
+    base: 'rounded-full absolute top-0 left-0 z-0 object-cover w-full max-w-full h-full max-h-full opacity-0 transition-opacity duration-normal motion-reduce:transition-none group-data-[status=loaded]/avatar:opacity-100',
     variants: {
         size: {
             normal: '',
@@ -55,7 +55,7 @@ const defaultAvatarSuffix = cva({
 // Small initials sit on the type scale's smallest step, so they tighten their tracking instead:
 // two bold capitals then fill the 24px circle in the same proportion the larger sizes do.
 const defaultAvatarInitials = cva({
-    base: 'absolute bg-surface-floating bottom-0 w-full h-full text-center left-0 rounded-full flex items-center justify-center uppercase font-bold text-sm',
+    base: 'absolute bg-surface-floating bottom-0 w-full h-full text-center left-0 rounded-full flex items-center justify-center uppercase font-bold text-sm transition-opacity duration-normal motion-reduce:transition-none group-data-[status=loaded]/avatar:opacity-0',
     variants: {
         size: {
             normal: 'text-sm',

package/dist/components/Avatar/index.d.ts

@@ -1,6 +1,6 @@
 export { default as Avatar } from './Avatar.svelte';
 export { default as AvatarGroup } from './AvatarGroup.svelte';
-export type { AvatarItem, AvatarProps } from './avatar.props.js';
+export type { AvatarImageAttributes, AvatarItem, AvatarProps, AvatarStatus } from './avatar.props.js';
 export type { AvatarGroupProps } from './avatarGroup.props.js';
 export { avatarTheme, setAvatarTheme, useAvatarTheme, type AvatarTheme, type AvatarThemeProps } from './avatar.theme.js';
 export { avatarGroupTheme, setAvatarGroupTheme, useAvatarGroupTheme, type AvatarGroupTheme, type AvatarGroupThemeProps } from './avatarGroup.theme.js';

package/dist/components/Breadcrumbs/breadcrumbs.mcp.d.ts

@@ -1 +1 @@
-export declare const breadcrumbsDescription = "\n# Breadcrumbs Component\n\nA navigation component that displays a hierarchical path of links, helping users understand their location within a website or application. Supports keyboard navigation, dropdown menus for nested items, customizable separators, and ellipsis for long paths. Uses semantic HTML structure (`<nav><ol><li>`) following accessibility best practices.\n\n## Basic Usage\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n  \n  const items = [\n    { label: 'Home', href: '/' },\n    { label: 'Products', href: '/products' },\n    { label: 'Electronics', href: '/products/electronics', active: true }\n  ];\n</script>\n\n<Breadcrumbs {items} />\n```\n\n## Props\n\n### Core Props\n\n- **items**: BreadcrumbItem[] (required)\n  - Array of breadcrumb items to display\n  - Each item is a config object with: label, href, active, disabled, onclick, icon, menu\n\n- **home**: Omit<BreadcrumbItem, 'menu' | 'label'> & { label?: string | Snippet } (optional)\n  - Optional home breadcrumb item to prepend to the items array\n  - If provided, it will be rendered as the first breadcrumb\n  - When `label` is omitted a house icon is rendered\n\n- **maxItems**: number (optional)\n  - Maximum number of items to show before using ellipsis\n  - When set, shows first item, ellipsis, and last N items\n  - Example: `maxItems={3}` shows first item + ellipsis + last 2 items\n  - If maxItems >= items.length, all items are shown (no ellipsis)\n\n- **showSeparator**: boolean (default: true)\n  - Whether to display separators between breadcrumb items\n\n- **class**: string\n  - Additional CSS classes for the breadcrumbs container\n\n- **theme**: BreadcrumbsThemeProps\n  - Custom theme overrides for styling\n\n### BreadcrumbItem Properties\n\n- **label**: string | Snippet (required)\n  - The text or snippet to display for the breadcrumb item\n  - Can be a string or a snippet without parameters\n\n- **href**: string (optional)\n  - URL to navigate to. If provided, renders as an anchor element\n\n- **active**: boolean (default: false)\n  - Whether this breadcrumb represents the current page\n  - Active items render as `<span>` with `font-normal` styling and `aria-current=\"page\"`\n\n- **disabled**: boolean (default: false)\n  - Whether the breadcrumb item is disabled\n  - Disabled items are not navigable and have reduced opacity\n\n- **onclick**: (event: MouseEvent) => void (optional)\n  - Native click event handler for the breadcrumb item\n\n- **icon**: string | Snippet (optional)\n  - Icon snippet or string to display before the label\n\n- **menu**: MenuItem[] (optional)\n  - Array of menu items for dropdown functionality\n  - If provided, the breadcrumb renders as a PopupMenu\n\n### Content Props (Slots)\n\n- **separator**: Snippet\n  - Custom separator between breadcrumb items\n  - Default: `arrowRightIcon` (chevron right icon)\n  - No parameters passed to the snippet\n\n- **ellipsis**: Snippet\n  - Custom rendering for the ellipsis indicator\n  - Default: `dotsThreeOutlineIcon` with \"More\" screen reader text\n  - No parameters passed to the snippet\n\n## Examples\n\n### Basic Breadcrumbs with Links\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n  \n  const items = [\n    { label: 'Home', href: '/' },\n    { label: 'About', href: '/about' },\n    { label: 'Team', href: '/about/team', active: true }\n  ];\n</script>\n\n<Breadcrumbs {items} />\n```\n\n### Breadcrumbs with Home Item\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n  \n  const items = [\n    { label: 'Products', href: '/products' },\n    { label: 'Electronics', href: '/products/electronics', active: true }\n  ];\n</script>\n\n<Breadcrumbs home={{ label: 'Home', href: '/' }} {items} />\n<!-- Or with the default house icon -->\n<Breadcrumbs home={{ href: '/' }} {items} />\n```\n\n### Breadcrumbs with Icons\n\n```svelte\n<script lang=\"ts\">\n  import { Breadcrumbs } from './index.ts';\n  import { houseIcon } from 'entasis/icons/house';\n  import { folderIcon } from 'entasis/icons/folder';\n  import { fileIcon } from 'entasis/icons/file';\n  \n  const items = [\n    { label: 'Home', href: '/', icon: houseIcon },\n    { label: 'Documents', href: '/docs', icon: folderIcon },\n    { label: 'Report.pdf', href: '/docs/report', icon: fileIcon, active: true }\n  ];\n</script>\n\n<Breadcrumbs {items} />\n```\n\n### Breadcrumbs with Dropdown Menus\n\n```svelte\n<script lang=\"ts\">\n  import { Breadcrumbs, type BreadcrumbItem } from './index.ts';\n  \n  const items: BreadcrumbItem[] = [\n    { label: 'Home', href: '/' },\n    { \n      label: 'Products', \n      menu: [\n        { type: 'option', children: 'All Products', href: '/products' },\n        { type: 'option', children: 'Electronics', href: '/products/electronics' },\n        { type: 'option', children: 'Clothing', href: '/products/clothing' }\n      ]\n    },\n    { label: 'Electronics', href: '/products/electronics', active: true }\n  ];\n</script>\n\n<Breadcrumbs {items} />\n```\n\n### Custom Separator\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n  \n  const items = [\n    { label: 'Home', href: '/' },\n    { label: 'Products', href: '/products' },\n    { label: 'Details', href: '/products/details', active: true }\n  ];\n</script>\n\n<Breadcrumbs {items}>\n  {#snippet separator()}\n    <span class=\"text-neutral/70\">\u203A</span>\n  {/snippet}\n</Breadcrumbs>\n```\n\n### Breadcrumbs with Ellipsis\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n  \n  const items = [\n    { label: 'Home', href: '/' },\n    { label: 'Category 1', href: '/cat1' },\n    { label: 'Category 2', href: '/cat2' },\n    { label: 'Category 3', href: '/cat3' },\n    { label: 'Category 4', href: '/cat4' },\n    { label: 'Current Page', href: '/current', active: true }\n  ];\n</script>\n\n<!-- Shows first item + ellipsis + last 2 items -->\n<Breadcrumbs {items} maxItems={3} />\n```\n\n### Inline Items\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n</script>\n\n<Breadcrumbs\n  items={[\n    { label: 'Home', href: '/' },\n    { label: 'Products', href: '/products' },\n    { label: 'Electronics', active: true }\n  ]}\n/>\n```\n\n### Items with Snippet Labels\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n</script>\n\n{#snippet productsLabel()}\n  <strong>Products</strong>\n{/snippet}\n\n<Breadcrumbs\n  items={[\n    { label: 'Home', href: '/' },\n    { label: productsLabel, href: '/products' },\n    { label: 'Details', href: '/products/details', active: true }\n  ]}\n/>\n```\n\n### Disabled Items\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n  \n  const items = [\n    { label: 'Home', href: '/' },\n    { label: 'Products', href: '/products', disabled: true },\n    { label: 'Details', href: '/products/details', active: true }\n  ];\n</script>\n\n<Breadcrumbs {items} />\n```\n\n\n### Without Separators\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n  \n  const items = [\n    { label: 'Home', href: '/' },\n    { label: 'Products', href: '/products' },\n    { label: 'Details', href: '/products/details', active: true }\n  ];\n</script>\n\n<Breadcrumbs {items} showSeparator={false} />\n```\n\n## BreadcrumbItem Type\n\nEach item in the `items` array is a config object with properties like `label`, `href`, `active`, etc.\n\nThe `label` property can be a string or a snippet without parameters.\n\n## Keyboard Navigation\n\nThe Breadcrumbs component supports full keyboard navigation via the `useNavigation` hook:\n\n- **Arrow Left**: Navigate to previous breadcrumb item\n- **Arrow Right**: Navigate to next breadcrumb item\n- **Home**: Navigate to first breadcrumb item\n- **End**: Navigate to last breadcrumb item\n- **Enter/Space**: Activate the focused breadcrumb item\n- **Escape**: Clear focus\n\nDisabled items are automatically skipped during keyboard navigation.\n\n## Accessibility\n\n- Uses semantic `<nav>` element with `aria-label=\"Breadcrumbs\"`\n- Active items use `aria-current=\"page\"` attribute\n- Disabled items use `aria-disabled` attribute\n- Proper focus management with roving tabindex pattern\n- Keyboard navigation support for all interactive elements\n- Screen reader friendly with proper ARIA attributes\n\n## Structure\n\nThe component uses semantic HTML structure:\n- `<nav>` element with `aria-label=\"Breadcrumbs\"`\n- `<ol>` (ordered list) for the breadcrumb list\n- `<li>` elements for each breadcrumb item\n- `<li>` elements for separators with `role=\"presentation\"` and `aria-hidden=\"true\"`\n- Active items render as `<span>` with `role=\"link\"`, `aria-disabled=\"true\"`, and `aria-current=\"page\"`\n- Non-active items render as links (`<a>`) or buttons (`<button>`)\n- Ellipsis indicator for long paths\n- PopupMenu integration for items with nested menus\n\n## Notes\n\n- Items with `href` render as anchor elements, others render as buttons\n- Active items render as `<span>` elements with `font-normal` styling (not bold)\n- Disabled items cannot be navigated and have reduced opacity\n- Separators are not shown after the last item\n- The default separator is `arrowRightIcon` (chevron right) but can be customized via the `separator` slot\n- Items with `menu` property automatically render as PopupMenu components\n- Ellipsis is shown when `maxItems` is set and there are more items than the limit\n- Uses semantic HTML structure (`<nav><ol><li>`) for better accessibility\n- Styling matches shadcn/ui breadcrumb component patterns\n- Items can be simple strings/snippets or full config objects\n- Labels and icons can be strings or snippets (no parameters)\n\n## Theme Customization\n\nThe Breadcrumbs component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **root**: Main breadcrumbs container styles\n- **item**: Individual breadcrumb item styles\n- **link**: Breadcrumb link/button styles\n- **separator**: Separator icon/styles\n- **ellipsis**: Ellipsis indicator styles\n- **icon**: Icon styles\n\n### Available Variants\n\n**root**:\n- base: Base classes for main container\n\n**item**:\n- base: Base classes for breadcrumb items\n- Variants:\n  - disabled: boolean - Disabled state styling\n  - active: boolean - Active/current page styling\n\n**link**:\n- base: Base classes for links/buttons\n- Variants:\n  - disabled: boolean - Disabled state styling\n  - active: boolean - Active state styling\n\n**separator**:\n- base: Base classes for separator icons\n\n**ellipsis**:\n- base: Base classes for ellipsis indicator\n\n**icon**:\n- base: Base classes for icons\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Breadcrumbs \n  items={items}\n  theme={{\n    root: {\n      base: 'flex items-center gap-2 text-sm'\n    },\n    item: {\n      active: {\n        true: 'text-primary font-semibold'\n      }\n    }\n  }}\n/>\n```\n\n**Custom Link Styling**:\n```svelte\n<Breadcrumbs \n  items={items}\n  theme={{\n    link: {\n      base: 'hover:text-primary transition-colors',\n      active: {\n        true: 'text-gray-900 font-semibold'\n      },\n      disabled: {\n        true: 'opacity-50 cursor-not-allowed'\n      }\n    },\n    separator: {\n      base: 'text-gray-400 mx-2'\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setBreadcrumbsTheme } from './index.ts';\n  \n  setBreadcrumbsTheme({\n    root: {\n      base: 'flex items-center gap-2 text-sm'\n    },\n    item: {\n      active: {\n        true: 'text-primary'\n      }\n    },\n    separator: {\n      base: 'text-gray-400'\n    }\n  });\n</script>\n```\n";
+export declare const breadcrumbsDescription = "\n# Breadcrumbs Component\n\nA navigation component that displays a hierarchical path of links, helping users understand their location within a website or application. Supports keyboard navigation, dropdown menus for nested items, customizable separators, and ellipsis for long paths. Uses semantic HTML structure (`<nav><ol><li>`) following accessibility best practices.\n\n## Basic Usage\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n  \n  const items = [\n    { label: 'Home', href: '/' },\n    { label: 'Products', href: '/products' },\n    { label: 'Electronics', href: '/products/electronics', active: true }\n  ];\n</script>\n\n<Breadcrumbs {items} />\n```\n\n## Props\n\n### Core Props\n\n- **items**: BreadcrumbItem[] (required)\n  - Array of breadcrumb items to display\n  - Each item is a config object with: label, href, active, disabled, onclick, icon, menu\n\n- **home**: Omit<BreadcrumbItem, 'menu' | 'label'> & { label?: string | Snippet } (optional)\n  - Optional home breadcrumb item to prepend to the items array\n  - If provided, it will be rendered as the first breadcrumb\n  - When `label` is omitted a house icon is rendered\n\n- **maxItems**: number (optional)\n  - Maximum number of items to show before using ellipsis\n  - When set, shows first item, ellipsis, and last N items\n  - Example: `maxItems={3}` shows first item + ellipsis + last 2 items\n  - If maxItems >= items.length, all items are shown (no ellipsis)\n\n- **showSeparator**: boolean (default: true)\n  - Whether to display separators between breadcrumb items\n\n- **class**: string\n  - Additional CSS classes for the breadcrumbs container\n\n- **theme**: BreadcrumbsThemeProps\n  - Custom theme overrides for styling\n\n### BreadcrumbItem Properties\n\n- **label**: string | Snippet (required)\n  - The text or snippet to display for the breadcrumb item\n  - Can be a string or a snippet without parameters\n\n- **href**: string (optional)\n  - URL to navigate to. If provided, renders as an anchor element\n\n- **active**: boolean (default: false)\n  - Whether this breadcrumb represents the current page\n  - Active items render as `<span>` with `font-normal` styling and `aria-current=\"page\"`\n\n- **disabled**: boolean (default: false)\n  - Whether the breadcrumb item is disabled\n  - Disabled items are not navigable and have reduced opacity\n\n- **onclick**: (event: MouseEvent) => void (optional)\n  - Native click event handler for the breadcrumb item\n\n- **icon**: string | Snippet (optional)\n  - Icon snippet or string to display before the label\n\n- **menu**: MenuItem[] (optional)\n  - Array of menu items for dropdown functionality\n  - If provided, the breadcrumb renders as a PopupMenu\n\n### Content Props (Slots)\n\n- **separator**: Snippet\n  - Custom separator between breadcrumb items\n  - Default: `arrowRightIcon` (chevron right icon)\n  - No parameters passed to the snippet\n\n- **ellipsis**: Snippet\n  - Custom rendering for the ellipsis indicator\n  - Default: `dotsThreeOutlineIcon` with \"More\" screen reader text\n  - No parameters passed to the snippet\n\n## Examples\n\n### Basic Breadcrumbs with Links\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n  \n  const items = [\n    { label: 'Home', href: '/' },\n    { label: 'About', href: '/about' },\n    { label: 'Team', href: '/about/team', active: true }\n  ];\n</script>\n\n<Breadcrumbs {items} />\n```\n\n### Breadcrumbs with Home Item\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n  \n  const items = [\n    { label: 'Products', href: '/products' },\n    { label: 'Electronics', href: '/products/electronics', active: true }\n  ];\n</script>\n\n<Breadcrumbs home={{ label: 'Home', href: '/' }} {items} />\n<!-- Or with the default house icon -->\n<Breadcrumbs home={{ href: '/' }} {items} />\n```\n\n### Breadcrumbs with Icons\n\n```svelte\n<script lang=\"ts\">\n  import { Breadcrumbs } from './index.ts';\n  import { houseIcon } from 'entasis/icons/house';\n  import { folderIcon } from 'entasis/icons/folder';\n  import { fileIcon } from 'entasis/icons/file';\n  \n  const items = [\n    { label: 'Home', href: '/', icon: houseIcon },\n    { label: 'Documents', href: '/docs', icon: folderIcon },\n    { label: 'Report.pdf', href: '/docs/report', icon: fileIcon, active: true }\n  ];\n</script>\n\n<Breadcrumbs {items} />\n```\n\n### Breadcrumbs with Dropdown Menus\n\n```svelte\n<script lang=\"ts\">\n  import { Breadcrumbs, type BreadcrumbItem } from './index.ts';\n  \n  const items: BreadcrumbItem[] = [\n    { label: 'Home', href: '/' },\n    { \n      label: 'Products', \n      menu: [\n        { type: 'option', children: 'All Products', href: '/products' },\n        { type: 'option', children: 'Electronics', href: '/products/electronics' },\n        { type: 'option', children: 'Clothing', href: '/products/clothing' }\n      ]\n    },\n    { label: 'Electronics', href: '/products/electronics', active: true }\n  ];\n</script>\n\n<Breadcrumbs {items} />\n```\n\n### Custom Separator\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n  \n  const items = [\n    { label: 'Home', href: '/' },\n    { label: 'Products', href: '/products' },\n    { label: 'Details', href: '/products/details', active: true }\n  ];\n</script>\n\n<Breadcrumbs {items}>\n  {#snippet separator()}\n    <span class=\"text-neutral/70\">\u203A</span>\n  {/snippet}\n</Breadcrumbs>\n```\n\n### Breadcrumbs with Ellipsis\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n  \n  const items = [\n    { label: 'Home', href: '/' },\n    { label: 'Category 1', href: '/cat1' },\n    { label: 'Category 2', href: '/cat2' },\n    { label: 'Category 3', href: '/cat3' },\n    { label: 'Category 4', href: '/cat4' },\n    { label: 'Current Page', href: '/current', active: true }\n  ];\n</script>\n\n<!-- Shows first item + ellipsis + last 2 items -->\n<Breadcrumbs {items} maxItems={3} />\n```\n\n### Inline Items\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n</script>\n\n<Breadcrumbs\n  items={[\n    { label: 'Home', href: '/' },\n    { label: 'Products', href: '/products' },\n    { label: 'Electronics', active: true }\n  ]}\n/>\n```\n\n### Items with Snippet Labels\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n</script>\n\n{#snippet productsLabel()}\n  <strong>Products</strong>\n{/snippet}\n\n<Breadcrumbs\n  items={[\n    { label: 'Home', href: '/' },\n    { label: productsLabel, href: '/products' },\n    { label: 'Details', href: '/products/details', active: true }\n  ]}\n/>\n```\n\n### Disabled Items\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n  \n  const items = [\n    { label: 'Home', href: '/' },\n    { label: 'Products', href: '/products', disabled: true },\n    { label: 'Details', href: '/products/details', active: true }\n  ];\n</script>\n\n<Breadcrumbs {items} />\n```\n\n\n### Without Separators\n\n```svelte\n<script>\n  import { Breadcrumbs } from './index.ts';\n  \n  const items = [\n    { label: 'Home', href: '/' },\n    { label: 'Products', href: '/products' },\n    { label: 'Details', href: '/products/details', active: true }\n  ];\n</script>\n\n<Breadcrumbs {items} showSeparator={false} />\n```\n\n## BreadcrumbItem Type\n\nEach item in the `items` array is a config object with properties like `label`, `href`, `active`, etc.\n\nThe `label` property can be a string or a snippet without parameters.\n\n## Keyboard Navigation\n\nThe Breadcrumbs component supports full keyboard navigation via the `useNavigation` hook:\n\n- **Arrow Left**: Navigate to previous breadcrumb item\n- **Arrow Right**: Navigate to next breadcrumb item\n- **Home**: Navigate to first breadcrumb item\n- **End**: Navigate to last breadcrumb item\n- **Enter/Space**: Activate the focused breadcrumb item\n- **Escape**: Clear focus\n\nDisabled items and items hidden with CSS (a `display: none` class, the `hidden` attribute or a media query) are automatically skipped during keyboard navigation. The `<nav>` element is not a Tab stop of its own: Tab reaches the breadcrumbs through their single roving tab stop. Keys pressed on content you render inside Breadcrumbs that is not an item (a custom `ellipsis` button) stay with that content, apart from the arrows and Home/End, which move into the trail.\n\n## Accessibility\n\n- Uses semantic `<nav>` element with `aria-label=\"Breadcrumbs\"`\n- Active items use `aria-current=\"page\"` attribute\n- Disabled items use `aria-disabled` attribute\n- Proper focus management with roving tabindex pattern\n- Keyboard navigation support for all interactive elements\n- Screen reader friendly with proper ARIA attributes\n\n## Structure\n\nThe component uses semantic HTML structure:\n- `<nav>` element with `aria-label=\"Breadcrumbs\"`\n- `<ol>` (ordered list) for the breadcrumb list\n- `<li>` elements for each breadcrumb item\n- `<li>` elements for separators with `role=\"presentation\"` and `aria-hidden=\"true\"`\n- Active items render as `<span>` with `role=\"link\"`, `aria-disabled=\"true\"`, and `aria-current=\"page\"`\n- Non-active items render as links (`<a>`) or buttons (`<button>`)\n- Ellipsis indicator for long paths\n- PopupMenu integration for items with nested menus\n\n## Notes\n\n- Items with `href` render as anchor elements, others render as buttons\n- Active items render as `<span>` elements with `font-normal` styling (not bold)\n- Disabled items cannot be navigated and have reduced opacity\n- Separators are not shown after the last item\n- The default separator is `arrowRightIcon` (chevron right) but can be customized via the `separator` slot\n- Items with `menu` property automatically render as PopupMenu components\n- Ellipsis is shown when `maxItems` is set and there are more items than the limit\n- Uses semantic HTML structure (`<nav><ol><li>`) for better accessibility\n- Styling matches shadcn/ui breadcrumb component patterns\n- Items can be simple strings/snippets or full config objects\n- Labels and icons can be strings or snippets (no parameters)\n\n## Theme Customization\n\nThe Breadcrumbs component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **root**: Main breadcrumbs container styles\n- **item**: Individual breadcrumb item styles\n- **link**: Breadcrumb link/button styles\n- **separator**: Separator icon/styles\n- **ellipsis**: Ellipsis indicator styles\n- **icon**: Icon styles\n\n### Available Variants\n\n**root**:\n- base: Base classes for main container\n\n**item**:\n- base: Base classes for breadcrumb items\n- Variants:\n  - disabled: boolean - Disabled state styling\n  - active: boolean - Active/current page styling\n\n**link**:\n- base: Base classes for links/buttons\n- Variants:\n  - disabled: boolean - Disabled state styling\n  - active: boolean - Active state styling\n\n**separator**:\n- base: Base classes for separator icons\n\n**ellipsis**:\n- base: Base classes for ellipsis indicator\n\n**icon**:\n- base: Base classes for icons\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Breadcrumbs \n  items={items}\n  theme={{\n    root: {\n      base: 'flex items-center gap-2 text-sm'\n    },\n    item: {\n      active: {\n        true: 'text-primary font-semibold'\n      }\n    }\n  }}\n/>\n```\n\n**Custom Link Styling**:\n```svelte\n<Breadcrumbs \n  items={items}\n  theme={{\n    link: {\n      base: 'hover:text-primary transition-colors',\n      active: {\n        true: 'text-gray-900 font-semibold'\n      },\n      disabled: {\n        true: 'opacity-50 cursor-not-allowed'\n      }\n    },\n    separator: {\n      base: 'text-gray-400 mx-2'\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setBreadcrumbsTheme } from './index.ts';\n  \n  setBreadcrumbsTheme({\n    root: {\n      base: 'flex items-center gap-2 text-sm'\n    },\n    item: {\n      active: {\n        true: 'text-primary'\n      }\n    },\n    separator: {\n      base: 'text-gray-400'\n    }\n  });\n</script>\n```\n";

package/dist/components/Breadcrumbs/breadcrumbs.mcp.js

@@ -289,7 +289,7 @@ The Breadcrumbs component supports full keyboard navigation via the \`useNavigat
 - **Enter/Space**: Activate the focused breadcrumb item
 - **Escape**: Clear focus
 
-Disabled items are automatically skipped during keyboard navigation.
+Disabled items and items hidden with CSS (a \`display: none\` class, the \`hidden\` attribute or a media query) are automatically skipped during keyboard navigation. The \`<nav>\` element is not a Tab stop of its own: Tab reaches the breadcrumbs through their single roving tab stop. Keys pressed on content you render inside Breadcrumbs that is not an item (a custom \`ellipsis\` button) stay with that content, apart from the arrows and Home/End, which move into the trail.
 
 ## Accessibility
 

package/dist/components/Button/Button.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import type { Attachment } from 'svelte/attachments';
 	import { spinnerOverlay } from '../../attachments/spinnerOverlay.svelte.js';
 	import Slot from '../Slot/Slot.svelte';
 	import type { ButtonInternalProps } from './button.props.js';
@@ -6,7 +7,6 @@
 	import { useDefaultColor } from '../Theme/theme.state.svelte.js';
 
 	let {
-		as,
 		loading = false,
 		onclick = null,
 		onpointerenter = null,
@@ -25,6 +25,7 @@
 		ref = $bindable(),
 		fullWidth = false,
 		disabled = false,
+		focusableWhenDisabled = false,
 		theme,
 		rel,
 		target,
@@ -45,7 +46,16 @@
 	const isSquared = $derived(
 		squared ?? !!((!children && prefix && !suffix) || (!children && !prefix && suffix))
 	);
-	const isAnchor = $derived(!!(as || href));
+	const isAnchor = $derived(!!href);
+	// Only a disabled <button> uses the native attribute, and only when it may leave the tab order.
+	// A loading button, or one that is `focusableWhenDisabled`, stays focusable, so a keyboard user
+	// keeps their place, and refuses activation through `aria-disabled` instead.
+	const nativeDisabled = $derived(!isAnchor && disabled && !focusableWhenDisabled);
+	const inactive = $derived(disabled || loading);
+	// A disabled anchor has no `href`, so only an explicit tabindex keeps it focusable.
+	const anchorTabindex = $derived(
+		isAnchor && disabled ? (focusableWhenDisabled ? (tabindex ?? 0) : -1) : tabindex
+	);
 
 	const resolvedColor = $derived(useDefaultColor(color));
 	// One set of variant values for every slot; the template reads `slots.x()`.
@@ -57,26 +67,34 @@
 			size,
 			loading,
 			disabled,
+			focusable: focusableWhenDisabled,
 			fullWidth
 		})
 	);
 
-	const handleClick: NonNullable<ButtonInternalProps['onclick']> = (event) => {
-		if (disabled) {
+	// Enter and Space still dispatch `click` on a focusable loading button. A capture listener on
+	// the element cancels that click before anything else sees it: listeners attached to the
+	// button itself (`{@attach popover.trigger}`), Svelte's delegated `onclick` handlers, and a
+	// router listening on <html>, which runs before them for content portaled outside the app
+	// root. Cancelling it also stops a submit button from submitting and an anchor from
+	// navigating. The listener is registered once and reads `inactive` on each click.
+	const refuseInactiveActivation: Attachment<HTMLElement> = (node) => {
+		const refuse = (event: MouseEvent) => {
+			if (!inactive) return;
 			event.preventDefault();
-			event.stopPropagation();
-			return;
-		}
-
-		onclick?.(event);
+			event.stopImmediatePropagation();
+		};
+		node.addEventListener('click', refuse, { capture: true });
+		return () => node.removeEventListener('click', refuse, { capture: true });
 	};
 
+	// A focusable disabled button keeps its pointer events, so hover callbacks (a tooltip) still fire.
 	const handlePointerEnter: NonNullable<ButtonInternalProps['onpointerenter']> = (event) => {
-		if (!disabled) onpointerenter?.(event);
+		if (!disabled || focusableWhenDisabled) onpointerenter?.(event);
 	};
 
 	const handlePointerLeave: NonNullable<ButtonInternalProps['onpointerleave']> = (event) => {
-		if (!disabled) onpointerleave?.(event);
+		if (!disabled || focusableWhenDisabled) onpointerleave?.(event);
 	};
 </script>
 
@@ -88,23 +106,25 @@
 	aria-controls={controls}
 	aria-selected={selected}
 	aria-pressed={pressed}
-	aria-disabled={isAnchor && disabled ? true : undefined}
+	aria-disabled={inactive && !nativeDisabled ? true : undefined}
+	aria-busy={loading ? true : undefined}
 	role={role ?? (isAnchor ? 'link' : 'button')}
 	href={isAnchor && !disabled ? href : undefined}
 	{rel}
 	{target}
 	{download}
 	{type}
-	tabindex={isAnchor && disabled ? -1 : tabindex}
+	tabindex={anchorTabindex}
 	bind:this={ref}
 	data-active={dataActive}
 	data-highlighted={dataHighlighted}
 	data-slot={dataSlot}
 	data-color={resolvedColor}
-	disabled={!isAnchor && disabled ? true : undefined}
+	disabled={nativeDisabled ? true : undefined}
 	class={slots.root({ className })}
+	{@attach refuseInactiveActivation}
 	{@attach spinnerOverlay({ loading, size })}
-	onclick={disabled || onclick ? handleClick : undefined}
+	{onclick}
 	onpointerenter={onpointerenter ? handlePointerEnter : undefined}
 	onpointerleave={onpointerleave ? handlePointerLeave : undefined}
 	{...attachments}

package/dist/components/Button/button.mcp.d.ts

@@ -1 +1 @@
-export declare const buttonDescription = "\n# Button Component\n\nThe Button component is a flexible and customizable button element that supports various variants, sizes, colors, and interactive states.\n\n## Basic Usage\n\n```svelte\n<Button>Click me</Button>\n<Button variant=\"outline\">Outline Button</Button>\n<Button color=\"primary\" size=\"large\">Large Primary Button</Button>\n```\n\n## Props\n\n### Core Props\n- **variant**: 'solid' | 'outline' | 'soft' | 'ghost' | 'link' (default: 'solid')\n  - solid: Filled background with color\n  - outline: Transparent background with colored border\n  - soft: Muted color background\n  - ghost: Transparent background with a transient state layer on hover and press\n  - link: Text-only styling with underline on hover\n\n- **color**: 'primary' | 'secondary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info' (default: 'neutral')\n  - Determines the color scheme of the button\n\n- **size**: 'small' | 'normal' | 'large' (default: 'normal')\n  - small: 28px height, smaller padding and text\n  - normal: 32px height, standard padding\n  - large: 36px height, larger padding and text\n\n### Layout Props\n- **fullWidth**: boolean (default: false) - Makes button take full width of container\n- **squared**: boolean - Makes button square (aspect-ratio 1:1), auto-determined if only prefix/suffix is provided\n- **disabled**: boolean (default: false) - Disables button interaction\n- **loading**: boolean (default: false) - Shows the Theme-configured loading spinner and disables interaction\n\n### State Props\nDescribe the meaning; the Button writes the ARIA. Never pass an aria-* attribute to a Button.\n- **pressed**: boolean - Toggle state of a button that stays on or off (a bold button in a toolbar, a \"show password\" eye). Rendered as aria-pressed\n- **selected**: boolean - Chosen state of a button acting as one option among several (a tab, a listbox option). Rendered as aria-selected\n- **expanded**: boolean - Whether the surface this button opens is showing. Rendered as aria-expanded. A entasis surface (Popover, PopupMenu, Select, Combobox) sets this on its own trigger, so pass it only for a surface you open yourself\n- **haspopup**: 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | true - What the surface this button opens contains. Rendered as aria-haspopup, and likewise set by a entasis surface on its own trigger\n\n### Link Props\n- **href**: string - Makes button render as anchor tag\n- **target**: string - Link target (e.g., \"_blank\")\n- **rel**: string - Link relationship\n\n### Event Props\n- **onclick**: (event: MouseEvent) => void - Native click event handler\n- **onpointerenter**: (event: PointerEvent) => void - Native pointer enter event handler\n- **onpointerleave**: (event: PointerEvent) => void - Native pointer leave event handler\n\n### Content Props (Slots)\n- **children**: Snippet - Main button content\n- **prefix**: Snippet - Content before main text (typically icons)\n- **suffix**: Snippet - Content after main text (typically icons)\n\n### Advanced Props\n- **label**: string - Accessible label applied as aria-label on the root element (required for icon-only buttons)\n- **ref**: HTMLElement - Reference to the button element\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n\n## Structure\n\nThe button follows this DOM structure:\n```\n<Button>\n\t<Prefix />    <!-- Optional prefix content -->\n\t<Children />  <!-- Main button content -->\n\t<Suffix />    <!-- Optional suffix content -->\n</Button>\n```\n\n## Examples\n\n### Basic Buttons\n```svelte\n<Button>Default Button</Button>\n<Button variant=\"outline\" color=\"primary\">Primary Outline</Button>\n<Button variant=\"soft\" color=\"danger\">Soft Danger</Button>\n<Button variant=\"ghost\">Ghost Button</Button>\n<Button variant=\"link\">Link Button</Button>\n```\n\n### With Icons\n```svelte\n<Button>\n\t{#snippet prefix()}\n\t\t{@render icon()}\n\t{/snippet}\n\tAdd Item\n</Button>\n\n<Button squared>\n\t{#snippet prefix()}\n\t\t{@render icon()}\n\t{/snippet}\n</Button>\n```\n\n### Interactive States\n```svelte\n<Button loading>Loading...</Button>\n<Button disabled>Disabled</Button>\n<Button fullWidth>Full Width Button</Button>\n```\n\n### As Link\n```svelte\n<Button href=\"/dashboard\" target=\"_blank\">Go to Dashboard</Button>\n```\n\n### With Event Handlers\n```svelte\n<script lang=\"ts\">\n\tfunction handleClick(event: MouseEvent) {\n\t\tconsole.log('Clicked:', event.currentTarget);\n\t}\n</script>\n\n<Button onclick={handleClick}>\n\tClick\n</Button>\n```\n\n### Custom Styling\n```svelte\n<Button class=\"lift-4 border-2\" color=\"primary\" variant=\"outline\">\n\tCustom Styled\n</Button>\n```\n\n## Accessibility\n\n- Automatically sets appropriate ARIA roles (button/link)\n- Supports keyboard navigation\n- Disabled state prevents interaction\n- Loading state provides visual feedback\n\n## Notes\n\n- When `href` is provided, renders as `<a>` tag, otherwise `<button>`\n- `squared` is automatically determined when only prefix or suffix is provided without children\n- All event handlers respect disabled state\n- Icon sizing is automatically adjusted based on button size\n\n## Theme Customization\n\nThe Button component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **root**: Main button container styles\n- **prefix**: Styles for prefix content (icons before text)\n- **suffix**: Styles for suffix content (icons after text)\n\n### Theme Type Definition\n\n```typescript\nimport type { ButtonThemeProps } from 'entasis/button';\n\n// Example theme customization\nconst customTheme: ButtonThemeProps = {\n  root: {\n    base: 'custom-base-classes',\n    size: {\n      small: 'custom-small-classes',\n      normal: 'custom-normal-classes',\n      large: 'custom-large-classes'\n    },\n    color: {\n      primary: 'bg-blue-500 text-white',\n      danger: 'bg-red-500 text-white'\n    },\n    variant: {\n      solid: 'bg-color text-color-contrast',\n      outline: 'border-2 border-color'\n    }\n  },\n  prefix: {\n    size: {\n      small: 'w-3 h-3',\n      normal: 'w-4 h-4',\n      large: 'w-5 h-5'\n    }\n  }\n};\n```\n\n### Available Variants\n\n**root**:\n- base: Base classes applied to all buttons\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Controls padding, text size, and height\n  - color: 'primary' | 'secondary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info' - Color scheme\n  - variant: 'solid' | 'outline' | 'soft' | 'ghost' | 'link' - Visual style variant\n  - loading: boolean - Loading state styling\n  - disabled: boolean - Disabled state styling\n  - squared: boolean - Square button styling\n  - fullWidth: boolean - Full width styling\n\n**prefix**:\n- base: Base classes for prefix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size based on button size\n\n**suffix**:\n- base: Base classes for suffix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size based on button size\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Button \n  theme={{\n    root: {\n      base: 'rounded-full lift-4',\n      size: {\n        large: 'px-8 py-4 text-xl'\n      }\n    }\n  }}\n>\n  Custom Styled Button\n</Button>\n```\n\n**Color Variant Customization**:\n```svelte\n<Button \n  color=\"primary\"\n  theme={{\n    root: {\n      color: {\n        primary: 'state-layer bg-linear-to-r from-blue-500 to-purple-500'\n      }\n    }\n  }}\n>\n  Gradient Button\n</Button>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setButtonTheme } from './index.ts';\n  \n  setButtonTheme({\n    root: {\n      variant: {\n        solid: 'state-layer bg-color text-color-contrast lift-3 hover:lift-4 transition-shadow',\n        outline: 'state-layer border-2 border-color'\n      }\n    },\n    prefix: {\n      size: {\n        normal: 'w-5 h-5'\n      }\n    }\n  });\n</script>\n```\n";
+export declare const buttonDescription = "\n# Button Component\n\nThe Button component is a flexible and customizable button element that supports various variants, sizes, colors, and interactive states.\n\n## Basic Usage\n\n```svelte\n<Button>Click me</Button>\n<Button variant=\"outline\">Outline Button</Button>\n<Button color=\"primary\" size=\"large\">Large Primary Button</Button>\n```\n\n## Props\n\n### Core Props\n- **variant**: 'solid' | 'outline' | 'soft' | 'ghost' | 'link' (default: 'solid')\n  - solid: Filled background with color\n  - outline: Transparent background with colored border\n  - soft: Muted color background\n  - ghost: Transparent background with a transient state layer on hover and press\n  - link: Text-only styling with underline on hover\n\n- **color**: 'primary' | 'secondary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info' (default: 'neutral')\n  - Determines the color scheme of the button\n\n- **size**: 'small' | 'normal' | 'large' (default: 'normal')\n  - small: 28px height, smaller padding and text\n  - normal: 32px height, standard padding\n  - large: 36px height, larger padding and text\n\n### Layout Props\n- **fullWidth**: boolean (default: false) - Makes button take full width of container\n- **squared**: boolean - Makes button square (aspect-ratio 1:1), auto-determined if only prefix/suffix is provided\n- **disabled**: boolean (default: false) - Disables button interaction. A `<button>` gets the native `disabled` attribute and leaves the tab order; an anchor drops its href, leaves the tab order and renders `aria-disabled=\"true\"`\n- **focusableWhenDisabled**: boolean (default: false) - Keeps a `disabled` button focusable: it renders `aria-disabled=\"true\"` instead of the native `disabled` attribute, stays in the tab order and still receives pointer events (so a tooltip can explain why it is unavailable), and refuses activation: clicks from the pointer, Enter and Space are cancelled before any other listener sees them, and a `type=\"submit\"` button does not submit. A disabled anchor drops its href and takes `tabindex=\"0\"`. Has no effect without `disabled`\n- **loading**: boolean (default: false) - Shows the Theme-configured loading spinner and refuses activation while staying focusable: renders `aria-busy=\"true\"` and `aria-disabled=\"true\"`, and cancels clicks (pointer, Enter and Space) before any other listener sees them, including attachments such as `popover.trigger`, as well as the form submission of a `type=\"submit\"` button and the navigation of an anchor. It never sets the native `disabled` attribute, so keyboard focus stays on the button while the work runs\n\n### State Props\nDescribe the meaning; the Button writes the ARIA. Never pass an aria-* attribute to a Button.\n- **pressed**: boolean - Toggle state of a button that stays on or off (a bold button in a toolbar, a \"show password\" eye). Rendered as aria-pressed\n- **selected**: boolean - Chosen state of a button acting as one option among several (a tab, a listbox option). Rendered as aria-selected\n- **expanded**: boolean - Whether the surface this button opens is showing. Rendered as aria-expanded. A entasis surface (Popover, PopupMenu, Select, Combobox) sets this on its own trigger, so pass it only for a surface you open yourself\n- **haspopup**: 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | true - What the surface this button opens contains. Rendered as aria-haspopup, and likewise set by a entasis surface on its own trigger\n\n### Link Props\n- **href**: string - Makes button render as anchor tag\n- **target**: string - Link target (e.g., \"_blank\")\n- **rel**: string - Link relationship\n\n### Event Props\n- **onclick**: (event: MouseEvent) => void - Native click event handler\n- **onpointerenter**: (event: PointerEvent) => void - Native pointer enter event handler\n- **onpointerleave**: (event: PointerEvent) => void - Native pointer leave event handler\n\n### Content Props (Slots)\n- **children**: Snippet - Main button content\n- **prefix**: Snippet - Content before main text (typically icons)\n- **suffix**: Snippet - Content after main text (typically icons)\n\n### Advanced Props\n- **label**: string - Accessible label applied as aria-label on the root element (required for icon-only buttons)\n- **ref**: HTMLElement - Reference to the button element\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n\n## Structure\n\nThe button follows this DOM structure:\n```\n<Button>\n\t<Prefix />    <!-- Optional prefix content -->\n\t<Children />  <!-- Main button content -->\n\t<Suffix />    <!-- Optional suffix content -->\n</Button>\n```\n\n## Examples\n\n### Basic Buttons\n```svelte\n<Button>Default Button</Button>\n<Button variant=\"outline\" color=\"primary\">Primary Outline</Button>\n<Button variant=\"soft\" color=\"danger\">Soft Danger</Button>\n<Button variant=\"ghost\">Ghost Button</Button>\n<Button variant=\"link\">Link Button</Button>\n```\n\n### With Icons\n```svelte\n<Button>\n\t{#snippet prefix()}\n\t\t{@render icon()}\n\t{/snippet}\n\tAdd Item\n</Button>\n\n<Button squared>\n\t{#snippet prefix()}\n\t\t{@render icon()}\n\t{/snippet}\n</Button>\n```\n\n### Interactive States\n```svelte\n<Button loading>Loading...</Button>\n<Button disabled>Disabled</Button>\n<Button fullWidth>Full Width Button</Button>\n```\n\n### As Link\n```svelte\n<Button href=\"/dashboard\" target=\"_blank\">Go to Dashboard</Button>\n```\n\n### With Event Handlers\n```svelte\n<script lang=\"ts\">\n\tfunction handleClick(event: MouseEvent) {\n\t\tconsole.log('Clicked:', event.currentTarget);\n\t}\n</script>\n\n<Button onclick={handleClick}>\n\tClick\n</Button>\n```\n\n### Custom Styling\n```svelte\n<Button class=\"lift-4 border-2\" color=\"primary\" variant=\"outline\">\n\tCustom Styled\n</Button>\n```\n\n## Accessibility\n\n- Automatically sets appropriate ARIA roles (button/link)\n- Supports keyboard navigation\n- Disabled state prevents interaction\n- Loading state keeps focus on the button and announces it busy (`aria-busy`) and unavailable (`aria-disabled`); clicks, Enter, Space and form submission are cancelled until it ends\n- Prefer `loading` over `disabled` for a button whose own action is running: `disabled` removes the button from the tab order and drops focus to the page body\n- Use `focusableWhenDisabled` for a button that stays in the tab order while unavailable (for example with a tooltip explaining why); it is announced with `aria-disabled` and refuses activation\n\n## Notes\n\n- When `href` is provided, renders as `<a>` tag, otherwise `<button>`\n- `squared` is automatically determined when only prefix or suffix is provided without children\n- All event handlers respect disabled state; `onclick` also stays silent while `loading`\n- Icon sizing is automatically adjusted based on button size\n\n## Theme Customization\n\nThe Button component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **root**: Main button container styles\n- **prefix**: Styles for prefix content (icons before text)\n- **suffix**: Styles for suffix content (icons after text)\n\n### Theme Type Definition\n\n```typescript\nimport type { ButtonThemeProps } from 'entasis/button';\n\n// Example theme customization\nconst customTheme: ButtonThemeProps = {\n  root: {\n    base: 'custom-base-classes',\n    size: {\n      small: 'custom-small-classes',\n      normal: 'custom-normal-classes',\n      large: 'custom-large-classes'\n    },\n    color: {\n      primary: 'bg-blue-500 text-white',\n      danger: 'bg-red-500 text-white'\n    },\n    variant: {\n      solid: 'bg-color text-color-contrast',\n      outline: 'border-2 border-color'\n    }\n  },\n  prefix: {\n    size: {\n      small: 'w-3 h-3',\n      normal: 'w-4 h-4',\n      large: 'w-5 h-5'\n    }\n  }\n};\n```\n\n### Available Variants\n\n**root**:\n- base: Base classes applied to all buttons\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Controls padding, text size, and height\n  - color: 'primary' | 'secondary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info' - Color scheme\n  - variant: 'solid' | 'outline' | 'soft' | 'ghost' | 'link' - Visual style variant\n  - loading: boolean - Loading state styling\n  - disabled: boolean - Disabled state styling\n  - focusable: boolean - Set with `focusableWhenDisabled`: a disabled button keeps its pointer events\n  - squared: boolean - Square button styling\n  - fullWidth: boolean - Full width styling\n\n**prefix**:\n- base: Base classes for prefix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size based on button size\n\n**suffix**:\n- base: Base classes for suffix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size based on button size\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Button \n  theme={{\n    root: {\n      base: 'rounded-full lift-4',\n      size: {\n        large: 'px-8 py-4 text-xl'\n      }\n    }\n  }}\n>\n  Custom Styled Button\n</Button>\n```\n\n**Color Variant Customization**:\n```svelte\n<Button \n  color=\"primary\"\n  theme={{\n    root: {\n      color: {\n        primary: 'state-layer bg-linear-to-r from-blue-500 to-purple-500'\n      }\n    }\n  }}\n>\n  Gradient Button\n</Button>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setButtonTheme } from './index.ts';\n  \n  setButtonTheme({\n    root: {\n      variant: {\n        solid: 'state-layer bg-color text-color-contrast lift-3 hover:lift-4 transition-shadow',\n        outline: 'state-layer border-2 border-color'\n      }\n    },\n    prefix: {\n      size: {\n        normal: 'w-5 h-5'\n      }\n    }\n  });\n</script>\n```\n";

package/dist/components/Button/button.mcp.js

@@ -32,8 +32,9 @@ The Button component is a flexible and customizable button element that supports
 ### Layout Props
 - **fullWidth**: boolean (default: false) - Makes button take full width of container
 - **squared**: boolean - Makes button square (aspect-ratio 1:1), auto-determined if only prefix/suffix is provided
-- **disabled**: boolean (default: false) - Disables button interaction
-- **loading**: boolean (default: false) - Shows the Theme-configured loading spinner and disables interaction
+- **disabled**: boolean (default: false) - Disables button interaction. A \`<button>\` gets the native \`disabled\` attribute and leaves the tab order; an anchor drops its href, leaves the tab order and renders \`aria-disabled="true"\`
+- **focusableWhenDisabled**: boolean (default: false) - Keeps a \`disabled\` button focusable: it renders \`aria-disabled="true"\` instead of the native \`disabled\` attribute, stays in the tab order and still receives pointer events (so a tooltip can explain why it is unavailable), and refuses activation: clicks from the pointer, Enter and Space are cancelled before any other listener sees them, and a \`type="submit"\` button does not submit. A disabled anchor drops its href and takes \`tabindex="0"\`. Has no effect without \`disabled\`
+- **loading**: boolean (default: false) - Shows the Theme-configured loading spinner and refuses activation while staying focusable: renders \`aria-busy="true"\` and \`aria-disabled="true"\`, and cancels clicks (pointer, Enter and Space) before any other listener sees them, including attachments such as \`popover.trigger\`, as well as the form submission of a \`type="submit"\` button and the navigation of an anchor. It never sets the native \`disabled\` attribute, so keyboard focus stays on the button while the work runs
 
 ### State Props
 Describe the meaning; the Button writes the ARIA. Never pass an aria-* attribute to a Button.
@@ -138,13 +139,15 @@ The button follows this DOM structure:
 - Automatically sets appropriate ARIA roles (button/link)
 - Supports keyboard navigation
 - Disabled state prevents interaction
-- Loading state provides visual feedback
+- Loading state keeps focus on the button and announces it busy (\`aria-busy\`) and unavailable (\`aria-disabled\`); clicks, Enter, Space and form submission are cancelled until it ends
+- Prefer \`loading\` over \`disabled\` for a button whose own action is running: \`disabled\` removes the button from the tab order and drops focus to the page body
+- Use \`focusableWhenDisabled\` for a button that stays in the tab order while unavailable (for example with a tooltip explaining why); it is announced with \`aria-disabled\` and refuses activation
 
 ## Notes
 
 - When \`href\` is provided, renders as \`<a>\` tag, otherwise \`<button>\`
 - \`squared\` is automatically determined when only prefix or suffix is provided without children
-- All event handlers respect disabled state
+- All event handlers respect disabled state; \`onclick\` also stays silent while \`loading\`
 - Icon sizing is automatically adjusted based on button size
 
 ## Theme Customization
@@ -201,6 +204,7 @@ const customTheme: ButtonThemeProps = {
   - variant: 'solid' | 'outline' | 'soft' | 'ghost' | 'link' - Visual style variant
   - loading: boolean - Loading state styling
   - disabled: boolean - Disabled state styling
+  - focusable: boolean - Set with \`focusableWhenDisabled\`: a disabled button keeps its pointer events
   - squared: boolean - Square button styling
   - fullWidth: boolean - Full width styling
 

package/dist/components/Button/button.props.d.ts

@@ -22,7 +22,7 @@ export type ButtonPrimitiveProps = WithAttachments<WithSlot<{
      */
     label?: string;
     /**
-     * ARIA role override. Defaults to `button` (or `link` when `href`/`as` is set).
+     * ARIA role override. Defaults to `button` (or `link` when `href` is set).
      * Pass `menuitem` when the button is an item inside a `menu`.
      */
     role?: string;
@@ -56,7 +56,13 @@ export type ButtonPrimitiveProps = WithAttachments<WithSlot<{
      */
     href?: string;
     /**
-     * When true, shows a spinner overlay and disables pointer events.
+     * When true, shows a spinner overlay and refuses activation while keeping the button
+     * focusable: it renders `aria-busy="true"` and `aria-disabled="true"`, and cancels clicks
+     * (pointer, Enter and Space) before any other listener sees them, including attachments
+     * such as `popover.trigger`, as well as the form submission of a `type="submit"` button
+     * and the navigation of an anchor. Unlike
+     * `disabled`, it never sets the native `disabled` attribute, so focus stays on the
+     * button while the work runs.
      */
     loading?: boolean;
     /**
@@ -80,9 +86,22 @@ export type ButtonPrimitiveProps = WithAttachments<WithSlot<{
      */
     fullWidth?: boolean;
     /**
-     * When true, prevents interaction and applies disabled styles.
+     * When true, prevents interaction and applies disabled styles. A `<button>` gets the
+     * native `disabled` attribute and leaves the tab order; an anchor drops its `href`,
+     * leaves the tab order and renders `aria-disabled="true"`. With `focusableWhenDisabled`
+     * the button stays in the tab order instead.
      */
     disabled?: boolean;
+    /**
+     * When true, a `disabled` button stays focusable: it renders `aria-disabled="true"`
+     * instead of the native `disabled` attribute, keeps its place in the tab order and still
+     * receives pointer events (so a tooltip can explain why it is unavailable), and refuses
+     * activation: clicks from the pointer, Enter and Space are cancelled before any other
+     * listener sees them, and a `type="submit"` button does not submit. An anchor drops its
+     * `href` and takes `tabindex="0"`. Has no effect without `disabled`.
+     * @default false
+     */
+    focusableWhenDisabled?: boolean;
     /**
      * The class name of the button. First element that the component outputs in the DOM.
      */
@@ -95,10 +114,6 @@ export type ButtonPrimitiveProps = WithAttachments<WithSlot<{
      * Link rel attribute when href is set.
      */
     rel?: string;
-    /**
-     * When set, renders the root element as an anchor instead of a button.
-     */
-    as?: 'string';
     /**
      * Theme overrides for button parts such as prefix and suffix.
      */
@@ -114,7 +129,7 @@ export type ButtonPrimitiveProps = WithAttachments<WithSlot<{
     /** Semantic part name used by composed components and theme tooling. */
     'data-slot'?: string;
 } & ButtonForwardedAttributes & ButtonForwardedAnchorAttributes & ButtonEventAttributes, 'suffix' | 'prefix' | 'children'>>;
-export type ButtonProps = Omit<ButtonPrimitiveProps, 'as'>;
+export type ButtonProps = ButtonPrimitiveProps;
 /**
  * Button props plus the id plumbing the library wires between a surface and its own trigger.
  * Deliberately absent from the package's public exports: `controls` is an element id the

package/dist/components/Button/button.theme.d.ts

@@ -30,6 +30,10 @@ export declare const buttonTheme: {
             true: string;
             false: null;
         };
+        focusable: {
+            true: null;
+            false: null;
+        };
         squared: {
             true: string;
             false: null;
@@ -86,6 +90,10 @@ export declare const setButtonTheme: (theme: InferComponentTheme<{
             true: string;
             false: null;
         };
+        focusable: {
+            true: null;
+            false: null;
+        };
         squared: {
             true: string;
             false: null;
@@ -140,6 +148,10 @@ export declare const useButtonTheme: import("../../utils/cva/theme.js").UseCompo
             true: string;
             false: null;
         };
+        focusable: {
+            true: null;
+            false: null;
+        };
         squared: {
             true: string;
             false: null;

package/dist/components/Button/button.theme.js

@@ -22,14 +22,23 @@ const defaultButton = cva({
             outline: 'state-layer bg-color/0 border border-color text-color-readable',
             soft: 'state-layer text-color-muted-readable bg-color-muted',
             ghost: 'state-layer text-color-readable bg-color/0',
-            link: 'bg-transparent text-color-readable hover:underline'
+            link: 'bg-transparent text-color-readable hover:not-aria-disabled:underline'
         },
+        // A loading button keeps receiving pointer events: pointer-events-none would let a second click
+        // fall through to the page beneath and drop keyboard focus to <body>. The click guard in
+        // Button.svelte refuses the activation instead.
         loading: {
-            true: 'cursor-default pointer-events-none',
+            true: 'cursor-default active:translate-y-0',
             false: null
         },
         disabled: {
-            true: 'opacity-50 cursor-not-allowed pointer-events-none',
+            true: 'opacity-50 cursor-not-allowed',
+            false: null
+        },
+        // Disabled but still focusable (`focusableWhenDisabled`): it renders `aria-disabled`, so it
+        // must keep its pointer events for the click guard and for hover tooltips.
+        focusable: {
+            true: null,
             false: null
         },
         squared: {
@@ -43,9 +52,13 @@ const defaultButton = cva({
     defaultVariants: {
         color: 'neutral',
         variant: 'solid',
-        size: 'normal'
+        size: 'normal',
+        focusable: false
     },
     compoundVariants: [
+        // A natively disabled button takes no pointer events; a focusable one keeps them.
+        { disabled: true, focusable: false, class: 'pointer-events-none' },
+        { disabled: true, focusable: true, class: 'active:translate-y-0' },
         // The neutral outline is toolbar chrome next to inputs and selects, which all draw a
         // `neutral-muted` hairline; a full-strength neutral border made it the odd one out.
         { color: 'neutral', variant: 'outline', class: 'border-neutral-muted' }

package/dist/components/ButtonGroup/buttonGroup.mcp.d.ts

@@ -1 +1 @@
-export declare const buttonGroupDescription = "\n# ButtonGroup Component\n\nThe ButtonGroup component displays a collection of related buttons as a cohesive group with shared styling properties.\n\n## Basic Usage\n\n```svelte\n<ButtonGroup \n\titems={[\n\t\t{ children: 'First' },\n\t\t{ children: 'Second' },\n\t\t{ children: 'Third' }\n\t]}\n/>\n```\n\n## Props\n\n### Core Props\nPass either `items` or `children`.\n- **items**: Array<ButtonProps> - Array of button configurations\n  - Each button can have all standard Button component props\n- **children**: Snippet - Buttons composed directly, for content an item object cannot describe\n  (a Tooltip or Popover trigger, a Button with a custom body). Each direct child is joined to its\n  neighbours; set size, color and variant on each Button, since the shared props below apply to\n  `items` only.\n- **label**: string - Accessible name of the group (the root has `role=\"group\"`)\n\n### Shared Button Props (items)\n- **size**: 'small' | 'normal' | 'large' - Applied to all buttons in the group\n- **color**: 'primary' | 'secondary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info' - Shared color for all buttons\n- **variant**: 'solid' | 'outline' | 'soft' | 'ghost' | 'link' - Shared variant for all buttons\n- **disabled**: boolean - Disables all buttons in the group, even one whose item sets `disabled: false`\n\n### Styling Props\n- **class**: string - Additional CSS classes for the group container\n- **theme**: ComponentTheme - Custom theme overrides\n\n## Structure\n\n```\n<ButtonGroup>\n\t<Button />\n\t<Button />\n\t<Button />\n</ButtonGroup>\n```\n\n## Examples\n\n### Composed Children\n```svelte\n<script lang=\"ts\">\n\timport { Button } from 'entasis/button';\n\timport { ButtonGroup } from 'entasis/button-group';\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<ButtonGroup label=\"History\">\n\t<Button variant=\"outline\">Undo</Button>\n\t<Tooltip content=\"Redo the last change\" trigger={{ content: 'Redo', variant: 'outline' }} />\n</ButtonGroup>\n```\n\n### Basic Button Group\n```svelte\n<ButtonGroup \n\titems={[\n\t\t{ children: 'Left' },\n\t\t{ children: 'Center' },\n\t\t{ children: 'Right' }\n\t]}\n/>\n```\n\n### With Shared Styling\n```svelte\n<ButtonGroup \n\tsize=\"large\"\n\tcolor=\"primary\"\n\tvariant=\"outline\"\n\titems={[\n\t\t{ children: 'Option 1' },\n\t\t{ children: 'Option 2' },\n\t\t{ children: 'Option 3' }\n\t]}\n/>\n```\n\n### With Icons\n```svelte\n<script lang=\"ts\">\n\timport { ButtonGroup } from 'entasis/button-group';\n\timport { textAlignLeftIcon } from 'entasis/icons/textAlignLeft';\n\timport { textAlignCenterIcon } from 'entasis/icons/textAlignCenter';\n\timport { textAlignRightIcon } from 'entasis/icons/textAlignRight';\n</script>\n\n<ButtonGroup \n\titems={[\n\t\t{ \n\t\t\tprefix: textAlignLeftIcon,\n\t\t\tchildren: 'Left' \n\t\t},\n\t\t{ \n\t\t\tprefix: textAlignCenterIcon,\n\t\t\tchildren: 'Center' \n\t\t},\n\t\t{ \n\t\t\tprefix: textAlignRightIcon,\n\t\t\tchildren: 'Right' \n\t\t}\n\t]}\n/>\n```\n\n### With Individual Click Handlers\n```svelte\n<script>\n\tfunction handleOption(option) {\n\t\tconsole.log(`Selected: ${option}`);\n\t}\n</script>\n\n<ButtonGroup \n\titems={[\n\t\t{ \n\t\t\tchildren: 'Save',\n\t\t\tonclick: () => handleOption('save')\n\t\t},\n\t\t{ \n\t\t\tchildren: 'Cancel',\n\t\t\tonclick: () => handleOption('cancel')\n\t\t}\n\t]}\n/>\n```\n\n### Disabled Group\n```svelte\n<ButtonGroup \n\tdisabled\n\titems={[\n\t\t{ children: 'Option 1' },\n\t\t{ children: 'Option 2' }\n\t]}\n/>\n```\n\n### Icon Only Buttons\n```svelte\n<script lang=\"ts\">\n\timport { ButtonGroup } from 'entasis/button-group';\n\timport { textBIcon } from 'entasis/icons/textB';\n\timport { textItalicIcon } from 'entasis/icons/textItalic';\n\timport { textUnderlineIcon } from 'entasis/icons/textUnderline';\n</script>\n\n<ButtonGroup \n\titems={[\n\t\t{ \n\t\t\tsquared: true,\n\t\t\tprefix: textBIcon\n\t\t},\n\t\t{ \n\t\t\tsquared: true,\n\t\t\tprefix: textItalicIcon\n\t\t},\n\t\t{ \n\t\t\tsquared: true,\n\t\t\tprefix: textUnderlineIcon\n\t\t}\n\t]}\n/>\n```\n\n### Mixed Button States\n```svelte\n<ButtonGroup \n\tvariant=\"outline\"\n\titems={[\n\t\t{ children: 'Active', color: 'primary' },\n\t\t{ children: 'Default', color: 'neutral' },\n\t\t{ children: 'Disabled', disabled: true }\n\t]}\n/>\n```\n\n### Segmented Control\n```svelte\n<script>\n\tlet selected = $state('week');\n</script>\n\n<ButtonGroup \n\titems={[\n\t\t{ \n\t\t\tchildren: 'Day',\n\t\t\tvariant: selected === 'day' ? 'solid' : 'ghost',\n\t\t\tonclick: () => selected = 'day'\n\t\t},\n\t\t{ \n\t\t\tchildren: 'Week',\n\t\t\tvariant: selected === 'week' ? 'solid' : 'ghost',\n\t\t\tonclick: () => selected = 'week'\n\t\t},\n\t\t{ \n\t\t\tchildren: 'Month',\n\t\t\tvariant: selected === 'month' ? 'solid' : 'ghost',\n\t\t\tonclick: () => selected = 'month'\n\t\t}\n\t]}\n/>\n```\n\n## Styling\n\nButtonGroup automatically:\n- Removes border-radius from middle buttons\n- Adjusts borders to prevent double borders\n- Creates a cohesive, connected appearance\n- Maintains consistent spacing\n\n## Accessibility\n\n- Each button maintains full keyboard accessibility\n- Focus styles are preserved\n- Disabled state cascades properly\n- Screen readers announce each button individually\n\n## Notes\n\n- Individual button props override shared props\n- Buttons are rendered in the order provided\n- The group container can be styled with the `class` prop\n- All Button component features are supported for individual buttons\n\n## Theme Customization\n\nThe ButtonGroup component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **root**: Main button group container styles\n\n### Available Variants\n\n**root**:\n- base: Base classes for button group container (handles border radius and border connections between buttons)\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<ButtonGroup \n  items={buttons}\n  theme={{\n    root: {\n      base: 'flex items-center rounded-lg overflow-hidden'\n    }\n  }}\n/>\n```\n\n**Custom Group Styling**:\n```svelte\n<ButtonGroup \n  items={buttons}\n  theme={{\n    root: {\n      base: 'flex items-center gap-0 border-2 border-primary rounded-lg overflow-hidden'\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setButtonGroupTheme } from './index.ts';\n  \n  setButtonGroupTheme({\n    root: {\n      base: 'flex items-center first-child:rounded-r-none last-child:rounded-l-none'\n    }\n  });\n</script>\n```\n";
+export declare const buttonGroupDescription = "\n# ButtonGroup Component\n\nThe ButtonGroup component displays a collection of related buttons as a cohesive group with shared styling properties.\n\n## Basic Usage\n\n```svelte\n<ButtonGroup \n\titems={[\n\t\t{ children: 'First' },\n\t\t{ children: 'Second' },\n\t\t{ children: 'Third' }\n\t]}\n/>\n```\n\n## Props\n\n### Core Props\nPass either `items` or `children`.\n- **items**: Array<ButtonProps> - Array of button configurations\n  - Each button can have all standard Button component props\n- **children**: Snippet - Buttons composed directly, for content an item object cannot describe\n  (a Tooltip or Popover trigger, a Button with a custom body). Each direct child is joined to its\n  neighbours; set size, color and variant on each Button, since the shared props below apply to\n  `items` only.\n- **label**: string - Accessible name of the group (the root has `role=\"group\"`)\n\n### Shared Button Props (items)\n- **size**: 'small' | 'normal' | 'large' - Applied to all buttons in the group\n- **color**: 'primary' | 'secondary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info' - Shared color for all buttons\n- **variant**: 'solid' | 'outline' | 'soft' | 'ghost' | 'link' - Shared variant for all buttons\n- **disabled**: boolean - Disables all buttons in the group, even one whose item sets `disabled: false`. An item that sets `focusableWhenDisabled` stays focusable and announces `aria-disabled` instead of leaving the tab order\n\n### Styling Props\n- **class**: string - Additional CSS classes for the group container\n- **theme**: ComponentTheme - Custom theme overrides\n\n## Structure\n\n```\n<ButtonGroup>\n\t<Button />\n\t<Button />\n\t<Button />\n</ButtonGroup>\n```\n\n## Examples\n\n### Composed Children\n```svelte\n<script lang=\"ts\">\n\timport { Button } from 'entasis/button';\n\timport { ButtonGroup } from 'entasis/button-group';\n\timport { Tooltip } from 'entasis/tooltip';\n</script>\n\n<ButtonGroup label=\"History\">\n\t<Button variant=\"outline\">Undo</Button>\n\t<Tooltip content=\"Redo the last change\" trigger={{ content: 'Redo', variant: 'outline' }} />\n</ButtonGroup>\n```\n\n### Basic Button Group\n```svelte\n<ButtonGroup \n\titems={[\n\t\t{ children: 'Left' },\n\t\t{ children: 'Center' },\n\t\t{ children: 'Right' }\n\t]}\n/>\n```\n\n### With Shared Styling\n```svelte\n<ButtonGroup \n\tsize=\"large\"\n\tcolor=\"primary\"\n\tvariant=\"outline\"\n\titems={[\n\t\t{ children: 'Option 1' },\n\t\t{ children: 'Option 2' },\n\t\t{ children: 'Option 3' }\n\t]}\n/>\n```\n\n### With Icons\n```svelte\n<script lang=\"ts\">\n\timport { ButtonGroup } from 'entasis/button-group';\n\timport { textAlignLeftIcon } from 'entasis/icons/textAlignLeft';\n\timport { textAlignCenterIcon } from 'entasis/icons/textAlignCenter';\n\timport { textAlignRightIcon } from 'entasis/icons/textAlignRight';\n</script>\n\n<ButtonGroup \n\titems={[\n\t\t{ \n\t\t\tprefix: textAlignLeftIcon,\n\t\t\tchildren: 'Left' \n\t\t},\n\t\t{ \n\t\t\tprefix: textAlignCenterIcon,\n\t\t\tchildren: 'Center' \n\t\t},\n\t\t{ \n\t\t\tprefix: textAlignRightIcon,\n\t\t\tchildren: 'Right' \n\t\t}\n\t]}\n/>\n```\n\n### With Individual Click Handlers\n```svelte\n<script>\n\tfunction handleOption(option) {\n\t\tconsole.log(`Selected: ${option}`);\n\t}\n</script>\n\n<ButtonGroup \n\titems={[\n\t\t{ \n\t\t\tchildren: 'Save',\n\t\t\tonclick: () => handleOption('save')\n\t\t},\n\t\t{ \n\t\t\tchildren: 'Cancel',\n\t\t\tonclick: () => handleOption('cancel')\n\t\t}\n\t]}\n/>\n```\n\n### Disabled Group\n```svelte\n<ButtonGroup \n\tdisabled\n\titems={[\n\t\t{ children: 'Option 1' },\n\t\t{ children: 'Option 2' }\n\t]}\n/>\n```\n\n### Icon Only Buttons\n```svelte\n<script lang=\"ts\">\n\timport { ButtonGroup } from 'entasis/button-group';\n\timport { textBIcon } from 'entasis/icons/textB';\n\timport { textItalicIcon } from 'entasis/icons/textItalic';\n\timport { textUnderlineIcon } from 'entasis/icons/textUnderline';\n</script>\n\n<ButtonGroup \n\titems={[\n\t\t{ \n\t\t\tsquared: true,\n\t\t\tprefix: textBIcon\n\t\t},\n\t\t{ \n\t\t\tsquared: true,\n\t\t\tprefix: textItalicIcon\n\t\t},\n\t\t{ \n\t\t\tsquared: true,\n\t\t\tprefix: textUnderlineIcon\n\t\t}\n\t]}\n/>\n```\n\n### Mixed Button States\n```svelte\n<ButtonGroup \n\tvariant=\"outline\"\n\titems={[\n\t\t{ children: 'Active', color: 'primary' },\n\t\t{ children: 'Default', color: 'neutral' },\n\t\t{ children: 'Disabled', disabled: true }\n\t]}\n/>\n```\n\n### Segmented Control\n```svelte\n<script>\n\tlet selected = $state('week');\n</script>\n\n<ButtonGroup \n\titems={[\n\t\t{ \n\t\t\tchildren: 'Day',\n\t\t\tvariant: selected === 'day' ? 'solid' : 'ghost',\n\t\t\tonclick: () => selected = 'day'\n\t\t},\n\t\t{ \n\t\t\tchildren: 'Week',\n\t\t\tvariant: selected === 'week' ? 'solid' : 'ghost',\n\t\t\tonclick: () => selected = 'week'\n\t\t},\n\t\t{ \n\t\t\tchildren: 'Month',\n\t\t\tvariant: selected === 'month' ? 'solid' : 'ghost',\n\t\t\tonclick: () => selected = 'month'\n\t\t}\n\t]}\n/>\n```\n\n## Styling\n\nButtonGroup automatically:\n- Removes border-radius from middle buttons\n- Adjusts borders to prevent double borders\n- Creates a cohesive, connected appearance\n- Maintains consistent spacing\n\n## Accessibility\n\n- Each button maintains full keyboard accessibility\n- Focus styles are preserved\n- Disabled state cascades properly\n- Screen readers announce each button individually\n\n## Notes\n\n- Individual button props override shared props\n- Buttons are rendered in the order provided\n- The group container can be styled with the `class` prop\n- All Button component features are supported for individual buttons\n\n## Theme Customization\n\nThe ButtonGroup component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **root**: Main button group container styles\n\n### Available Variants\n\n**root**:\n- base: Base classes for button group container (handles border radius and border connections between buttons)\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<ButtonGroup \n  items={buttons}\n  theme={{\n    root: {\n      base: 'flex items-center rounded-lg overflow-hidden'\n    }\n  }}\n/>\n```\n\n**Custom Group Styling**:\n```svelte\n<ButtonGroup \n  items={buttons}\n  theme={{\n    root: {\n      base: 'flex items-center gap-0 border-2 border-primary rounded-lg overflow-hidden'\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setButtonGroupTheme } from './index.ts';\n  \n  setButtonGroupTheme({\n    root: {\n      base: 'flex items-center first-child:rounded-r-none last-child:rounded-l-none'\n    }\n  });\n</script>\n```\n";

package/dist/components/ButtonGroup/buttonGroup.mcp.js

@@ -31,7 +31,7 @@ Pass either \`items\` or \`children\`.
 - **size**: 'small' | 'normal' | 'large' - Applied to all buttons in the group
 - **color**: 'primary' | 'secondary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info' - Shared color for all buttons
 - **variant**: 'solid' | 'outline' | 'soft' | 'ghost' | 'link' - Shared variant for all buttons
-- **disabled**: boolean - Disables all buttons in the group, even one whose item sets \`disabled: false\`
+- **disabled**: boolean - Disables all buttons in the group, even one whose item sets \`disabled: false\`. An item that sets \`focusableWhenDisabled\` stays focusable and announces \`aria-disabled\` instead of leaving the tab order
 
 ### Styling Props
 - **class**: string - Additional CSS classes for the group container

package/dist/components/ButtonGroup/buttonGroup.props.d.ts

@@ -24,7 +24,10 @@ export type ButtonGroupProps = WithAttachments<ButtonGroupContent & {
     color?: Colors;
     /** Visual variant applied to every item in the group. */
     variant?: ButtonVariant;
-    /** When true, disables every item in the group, whatever the item says. */
+    /**
+     * When true, disables every item in the group, whatever the item says. An item with
+     * `focusableWhenDisabled` stays focusable and announces `aria-disabled` instead.
+     */
     disabled?: boolean;
     /** Class name on the root group container element. */
     class?: string;