@spectral_labs/ui 1.1.2 → 1.2.0

package/dist/components/badge/badge.svelte

@@ -59,17 +59,25 @@
     color: var(--sp-comp-badge-filled-fg);
   }
 
-  /* ── Outlined ── */
+  /* ── Outlined ──
+   * Themes may override `--sp-comp-badge-outlined-color` from the outer
+   * cascade to replace the foreground without fighting the local
+   * `--sp-comp-badge-outline-fg` tokens declared on `.sp-badge` (custom
+   * property scope rules: ancestors can't override descendants that
+   * re-declare the same name). `carbon` dark uses this to ship a WCAG AA
+   * pair (#a4b4ff on #3c3c3c ≈ 5.5:1) without breaking the existing per-
+   * colour mapping (`secondary`, `tertiary`, …).
+   */
   .sp-badge.outlined {
     background-color: transparent;
     border: 1px solid var(--sp-comp-badge-outline-border);
-    color: var(--sp-comp-badge-outline-fg);
+    color: var(--sp-comp-badge-outlined-color, var(--sp-comp-badge-outline-fg));
   }
 
   /* ── Ghost ── */
   .sp-badge.ghost {
     background-color: transparent;
-    color: var(--sp-comp-badge-outline-fg);
+    color: var(--sp-comp-badge-outlined-color, var(--sp-comp-badge-outline-fg));
   }
 
   /* ── Tonal ── */

package/dist/components/context-menu/__tests__/ContextMenuNonInteractiveTest.svelte

@@ -0,0 +1,34 @@
+<script lang='ts'>
+  import DropdownMenuItem from '../../dropdown-menu/components/dropdown-menu-item.svelte'
+  import ContextMenuContent from '../components/context-menu-content.svelte'
+  import ContextMenuRoot from '../components/context-menu-root.svelte'
+  import ContextMenuTrigger from '../components/context-menu-trigger.svelte'
+
+  let {
+    open = $bindable(false),
+    onOpenChange,
+    portalTo,
+  }: {
+    open?: boolean
+    onOpenChange?: (open: boolean) => void
+    portalTo?: HTMLElement | string
+  } = $props()
+</script>
+
+<!--
+  Mirrors the Refero V2 CollectionTree pattern: a `Tree.Item`-like focusable
+  child (role="treeitem" + tabindex=0) is wrapped by ContextMenu.Trigger with
+  `nonInteractive`. The treeitem stays the only interactive node — the trigger
+  wrapper attaches event listeners but no role/tabindex/aria-disabled.
+-->
+<ContextMenuRoot bind:open {onOpenChange}>
+  <ContextMenuTrigger nonInteractive>
+    <div role='treeitem' tabindex='0' aria-level='1' data-testid='treeitem'>
+      Tree item
+    </div>
+  </ContextMenuTrigger>
+  <ContextMenuContent {portalTo}>
+    <DropdownMenuItem>Item 1</DropdownMenuItem>
+    <DropdownMenuItem>Item 2</DropdownMenuItem>
+  </ContextMenuContent>
+</ContextMenuRoot>

package/dist/components/context-menu/__tests__/context-menu.test.svelte.js

@@ -1,6 +1,7 @@
 import { flushSync, mount, unmount } from 'svelte';
-import { afterEach, describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import ContextMenuRoot from '../components/context-menu-root.svelte';
+import ContextMenuNonInteractiveTest from './ContextMenuNonInteractiveTest.svelte';
 import ContextMenuTest from './ContextMenuTest.svelte';
 describe('context-menu', () => {
     let target;
@@ -62,4 +63,76 @@ describe('context-menu', () => {
             localTarget.remove();
         }
     });
+    // -------------------------------------------------------------------------
+    // nonInteractive prop
+    //
+    // Use when the child is already focusable/interactive (e.g. a Tree.Item with
+    // role="treeitem" + tabindex=0). The trigger wrapper then attaches event
+    // listeners only, without role/tabindex/aria-disabled, so it does not nest a
+    // second interactive control inside its child — fixing axe `nested-interactive`
+    // + `aria-required-parent` when wrapping a treeitem.
+    // -------------------------------------------------------------------------
+    describe('nonInteractive prop', () => {
+        function setupNI(props = {}) {
+            target = document.createElement('div');
+            document.body.appendChild(target);
+            instance = mount(ContextMenuNonInteractiveTest, { target, props: { portalTo: target, ...props } });
+            flushSync();
+            return target;
+        }
+        it('wrapper has no role, no tabindex, no aria-disabled when nonInteractive', () => {
+            setupNI();
+            const trigger = target.querySelector('.sp-context-menu-trigger');
+            expect(trigger).toBeTruthy();
+            expect(trigger.getAttribute('role')).toBeNull();
+            expect(trigger.getAttribute('tabindex')).toBeNull();
+            expect(trigger.getAttribute('aria-disabled')).toBeNull();
+        });
+        it('treeitem child has no [role="button"] ancestor when nonInteractive', () => {
+            setupNI();
+            const treeitem = target.querySelector('[role="treeitem"]');
+            expect(treeitem).toBeTruthy();
+            // Structural ARIA assertion: the treeitem must be a direct interactive
+            // descendant of the tree (no role="button" wrapper between them) so axe's
+            // `nested-interactive` + `aria-required-parent` rules stop firing.
+            expect(treeitem.closest('[role="button"]')).toBeNull();
+        });
+        it('right-click on wrapper still opens menu when nonInteractive', () => {
+            const calls = [];
+            setupNI({ onOpenChange: (open) => calls.push(open) });
+            const trigger = target.querySelector('.sp-context-menu-trigger');
+            trigger.dispatchEvent(new MouseEvent('contextmenu', { bubbles: true, clientX: 100, clientY: 100 }));
+            flushSync();
+            expect(calls).toEqual([true]);
+        });
+        it('forwards Shift+F10 from focusable child to the wrapper handler when nonInteractive', () => {
+            const calls = [];
+            setupNI({ onOpenChange: (open) => calls.push(open) });
+            const child = target.querySelector('[data-testid="treeitem"]');
+            child.focus();
+            child.dispatchEvent(new KeyboardEvent('keydown', { key: 'F10', shiftKey: true, bubbles: true }));
+            flushSync();
+            expect(calls).toEqual([true]);
+        });
+        it('long-press (touchstart + 700ms hold) still opens menu when nonInteractive', () => {
+            vi.useFakeTimers();
+            try {
+                const calls = [];
+                setupNI({ onOpenChange: (open) => calls.push(open) });
+                const trigger = target.querySelector('.sp-context-menu-trigger');
+                // jsdom lacks TouchEvent constructor — synthesise a bubbling Event with a touches array.
+                const evt = new Event('touchstart', { bubbles: true });
+                Object.defineProperty(evt, 'touches', {
+                    value: [{ clientX: 100, clientY: 100 }],
+                });
+                trigger.dispatchEvent(evt);
+                vi.advanceTimersByTime(700);
+                flushSync();
+                expect(calls).toEqual([true]);
+            }
+            finally {
+                vi.useRealTimers();
+            }
+        });
+    });
 });

package/dist/components/context-menu/components/context-menu-trigger.svelte

@@ -2,7 +2,7 @@
   import type { ContextMenuTriggerProps } from '../types.js'
   import { getContextMenuContext } from '../context-menu.svelte.js'
 
-  const { disabled = false, class: className, children }: ContextMenuTriggerProps = $props()
+  const { disabled = false, nonInteractive = false, class: className, children }: ContextMenuTriggerProps = $props()
   const ctx = getContextMenuContext()
 
   let el: HTMLElement | undefined = $state()
@@ -52,9 +52,9 @@
 <div
   bind:this={el}
   class="sp-context-menu-trigger {className ?? ''}"
-  role='button'
-  tabindex={disabled ? -1 : 0}
-  aria-disabled={disabled || undefined}
+  role={nonInteractive ? undefined : 'button'}
+  tabindex={nonInteractive ? undefined : (disabled ? -1 : 0)}
+  aria-disabled={!nonInteractive && disabled ? true : undefined}
   {oncontextmenu}
   {ontouchstart}
   {ontouchend}

package/dist/components/context-menu/types.d.ts

@@ -9,6 +9,21 @@ export interface ContextMenuProps {
 }
 export interface ContextMenuTriggerProps {
     disabled?: boolean;
+    /**
+     * When `true`, the trigger renders a neutral wrapper (no `role`, no
+     * `tabindex`, no `aria-disabled`) and only attaches event listeners
+     * (`contextmenu`, `touchstart`, `keydown`). Use this when the child is
+     * itself focusable/interactive (e.g. a `Tree.Item` with `role="treeitem"`
+     * + `tabindex=0`) so the wrapper doesn't introduce a nested interactive
+     * control, which otherwise breaks ARIA `nested-interactive` and
+     * `aria-required-parent` invariants.
+     *
+     * The child remains the only focusable element — keyboard activation
+     * (Shift+F10 / ContextMenu key) bubbles from the child to the wrapper's
+     * `keydown` handler. If the child is **not** focusable, prefer the
+     * default (`nonInteractive: false`) so the wrapper stays keyboard-reachable.
+     */
+    nonInteractive?: boolean;
     class?: string;
     children?: Snippet;
 }

package/dist/components/context-menu/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/components/context-menu/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AACrC,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,wCAAwC,CAAA;AAEzE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,uFAAuF;IACvF,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAGD,YAAY,EAAE,6BAA6B,IAAI,4BAA4B,EAAE,qBAAqB,IAAI,oBAAoB,EAAE,sBAAsB,IAAI,qBAAqB,EAAE,0BAA0B,IAAI,yBAAyB,EAAE,MAAM,2BAA2B,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/components/context-menu/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AACrC,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,wCAAwC,CAAA;AAEzE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,uFAAuF;IACvF,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAGD,YAAY,EAAE,6BAA6B,IAAI,4BAA4B,EAAE,qBAAqB,IAAI,oBAAoB,EAAE,sBAAsB,IAAI,qBAAqB,EAAE,0BAA0B,IAAI,yBAAyB,EAAE,MAAM,2BAA2B,CAAA"}

package/dist/components/tabs/__tests__/TabsTest.svelte

@@ -1,5 +1,5 @@
 <script lang='ts'>
-  import type { TabsActivationMode } from '../types.js'
+  import type { TabsActivationMode, TabsListOverflow } from '../types.js'
   import TabsContent from '../components/tabs-content.svelte'
   import TabsList from '../components/tabs-list.svelte'
   import TabsRoot from '../components/tabs-root.svelte'
@@ -10,16 +10,18 @@
     activationMode = 'automatic' as TabsActivationMode,
     orientation = 'horizontal' as 'horizontal' | 'vertical',
     loop = true,
+    overflow,
   }: {
     value?: string
     activationMode?: TabsActivationMode
     orientation?: 'horizontal' | 'vertical'
     loop?: boolean
+    overflow?: TabsListOverflow
   } = $props()
 </script>
 
 <TabsRoot bind:value {activationMode} {orientation} {loop}>
-  <TabsList>
+  <TabsList {overflow}>
     <TabsTrigger value='tab1'>Tab 1</TabsTrigger>
     <TabsTrigger value='tab2'>Tab 2</TabsTrigger>
     <TabsTrigger value='tab3' disabled>Tab 3</TabsTrigger>

package/dist/components/tabs/__tests__/tabs.test.svelte.js

@@ -1,5 +1,5 @@
 import { flushSync, mount, unmount } from 'svelte';
-import { afterEach, describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import TabsRoot from '../components/tabs-root.svelte';
 import TabsTest from './TabsTest.svelte';
 describe('tabs', () => {
@@ -148,4 +148,77 @@ describe('tabs', () => {
         flushSync();
         expect(tabs[1]?.getAttribute('aria-selected')).toBe('true');
     });
+    // -------------------------------------------------------------------------
+    // overflow prop (mobile overflow strategy)
+    //
+    // Default is 'scroll' so long labels never silently truncate; consumers can
+    // opt into 'wrap' for multi-row pill layouts. When the active tab changes,
+    // the list scrolls it into view via `scrollIntoView` so the user is never
+    // looking at an out-of-viewport active tab.
+    // -------------------------------------------------------------------------
+    describe('overflow prop', () => {
+        it('default overflow="scroll" emits data-overflow="scroll" on tablist', () => {
+            setup();
+            const tablist = target.querySelector('[role="tablist"]');
+            expect(tablist.getAttribute('data-overflow')).toBe('scroll');
+        });
+        it('overflow="wrap" emits data-overflow="wrap" on tablist', () => {
+            setup({ overflow: 'wrap' });
+            const tablist = target.querySelector('[role="tablist"]');
+            expect(tablist.getAttribute('data-overflow')).toBe('wrap');
+        });
+        it('vertical + default overflow still emits data-overflow="scroll" alongside data-orientation', () => {
+            setup({ orientation: 'vertical' });
+            const tablist = target.querySelector('[role="tablist"]');
+            expect(tablist.getAttribute('data-overflow')).toBe('scroll');
+            expect(tablist.getAttribute('data-orientation')).toBe('vertical');
+        });
+        it('changing the active tab calls scrollIntoView on the newly active trigger when overflow="scroll"', () => {
+            // jsdom does not implement scrollIntoView — install a mock on the
+            // prototype so the component's call hits our spy instead of throwing.
+            const original = HTMLElement.prototype.scrollIntoView;
+            const spy = vi.fn();
+            HTMLElement.prototype.scrollIntoView = spy;
+            try {
+                setup({ value: 'tab1' });
+                const tabs = target.querySelectorAll('[role="tab"]');
+                spy.mockClear(); // ignore any call from the initial mount
+                tabs[1].click();
+                flushSync();
+                // The spy should have been called on the new active trigger with a
+                // sensible config that brings it into the viewport without scrolling
+                // the page vertically.
+                expect(spy).toHaveBeenCalled();
+                const lastCall = spy.mock.calls.at(-1);
+                const arg = lastCall?.[0];
+                expect(arg).toBeDefined();
+                expect(typeof arg).toBe('object');
+                expect(arg).toMatchObject({ inline: expect.stringMatching(/^(nearest|center|start|end)$/), block: 'nearest' });
+                // And the call target was the now-active trigger, not an arbitrary node.
+                const callTarget = spy.mock.contexts.at(-1);
+                expect(callTarget?.getAttribute('data-state')).toBe('active');
+            }
+            finally {
+                ;
+                HTMLElement.prototype.scrollIntoView = original;
+            }
+        });
+        it('overflow="wrap" does NOT call scrollIntoView on tab change (wrap layout shows all tabs)', () => {
+            const original = HTMLElement.prototype.scrollIntoView;
+            const spy = vi.fn();
+            HTMLElement.prototype.scrollIntoView = spy;
+            try {
+                setup({ value: 'tab1', overflow: 'wrap' });
+                const tabs = target.querySelectorAll('[role="tab"]');
+                spy.mockClear();
+                tabs[1].click();
+                flushSync();
+                expect(spy).not.toHaveBeenCalled();
+            }
+            finally {
+                ;
+                HTMLElement.prototype.scrollIntoView = original;
+            }
+        });
+    });
 });

package/dist/components/tabs/components/tabs-list.svelte

@@ -3,7 +3,7 @@
   import { RovingFocusGroup } from '../../../internal/roving-focus/index.js'
   import { getTabsContext } from '../tabs.svelte.js'
 
-  const { class: className, children }: TabsListProps = $props()
+  const { overflow = 'scroll', class: className, children }: TabsListProps = $props()
 
   const ctx = getTabsContext()
 
@@ -28,6 +28,31 @@
       }
     }
   }
+
+  // When `overflow="scroll"`, the active trigger may sit outside the visible
+  // viewport (especially on mobile after a tab is selected via list-restored
+  // state or via keyboard navigation). Re-run scrollIntoView on every value
+  // change so the user never looks at an out-of-viewport active tab. We use
+  // `inline: 'nearest'` + `block: 'nearest'` so the scroll is minimal and
+  // never moves the page vertically when the tablist is horizontal.
+  $effect(() => {
+    if (overflow !== 'scroll')
+      return
+    // Track ctx.value to retrigger on activation changes.
+    const _activeValue = ctx.value
+    if (!listEl)
+      return
+    const active = listEl.querySelector<HTMLElement>('[role="tab"][data-state="active"]')
+    if (!active)
+      return
+    // SSR-safe: $effect only runs in the browser, but scrollIntoView may still
+    // be undefined in jsdom-based tests — guard before calling.
+    if (typeof active.scrollIntoView !== 'function')
+      return
+    active.scrollIntoView({ inline: 'nearest', block: 'nearest' })
+    // `_activeValue` is read above strictly for the reactive subscription.
+    void _activeValue
+  })
 </script>
 
 <div
@@ -37,6 +62,7 @@
   aria-orientation={ctx.orientation}
   tabindex={0}
   data-orientation={ctx.orientation}
+  data-overflow={overflow}
   {onkeydown}
 >
   {#if children}{@render children()}{/if}
@@ -54,4 +80,36 @@
     border-bottom: none;
     border-right: 1px solid var(--sp-sys-color-outline-variant);
   }
+
+  /* `overflow="scroll"` (default): horizontal scroll on horizontal tablist,
+     vertical scroll on vertical tablist. Native scrollbar hidden — the
+     active trigger is brought into view programmatically via scrollIntoView.
+     The tablist itself keeps its tabindex={0}, so it remains keyboard-scrollable. */
+  .sp-tabs-list[data-overflow='scroll'][data-orientation='horizontal'] {
+    overflow-x: auto;
+    overflow-y: hidden;
+    scrollbar-width: none; /* Firefox */
+  }
+
+  .sp-tabs-list[data-overflow='scroll'][data-orientation='vertical'] {
+    overflow-x: hidden;
+    overflow-y: auto;
+    scrollbar-width: none;
+  }
+
+  .sp-tabs-list[data-overflow='scroll']::-webkit-scrollbar {
+    display: none; /* WebKit */
+  }
+
+  /* `overflow="wrap"`: triggers wrap onto multiple lines. We also unset
+     `white-space: nowrap` on every trigger (set in tabs-trigger.svelte) via
+     a scoped `:global` selector — without this the trigger labels would
+     still refuse to wrap inside their pill, defeating the point of wrap. */
+  .sp-tabs-list[data-overflow='wrap'] {
+    flex-wrap: wrap;
+  }
+
+  .sp-tabs-list[data-overflow='wrap'] :global(.sp-tabs-trigger) {
+    white-space: normal;
+  }
 </style>

package/dist/components/tabs/components/tabs-list.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tabs-list.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/components/tabs/components/tabs-list.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AA4ChD,QAAA,MAAM,QAAQ,mDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"tabs-list.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/components/tabs/components/tabs-list.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAqEhD,QAAA,MAAM,QAAQ,mDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}

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

@@ -2,5 +2,5 @@ export { default as Content } from './components/tabs-content.svelte';
 export { default as List } from './components/tabs-list.svelte';
 export { default as Root } from './components/tabs-root.svelte';
 export { default as Trigger } from './components/tabs-trigger.svelte';
-export type { TabsActivationMode, TabsContentProps, TabsListProps, TabsOrientation, TabsProps, TabsTriggerProps, } from './types.js';
+export type { TabsActivationMode, TabsContentProps, TabsListOverflow, TabsListProps, TabsOrientation, TabsProps, TabsTriggerProps, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/components/tabs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/components/tabs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,kCAAkC,CAAA;AACrE,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,+BAA+B,CAAA;AAC/D,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,+BAA+B,CAAA;AAC/D,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,kCAAkC,CAAA;AACrE,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,SAAS,EACT,gBAAgB,GACjB,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/components/tabs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,kCAAkC,CAAA;AACrE,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,+BAA+B,CAAA;AAC/D,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,+BAA+B,CAAA;AAC/D,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,kCAAkC,CAAA;AACrE,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,SAAS,EACT,gBAAgB,GACjB,MAAM,YAAY,CAAA"}

package/dist/components/tabs/types.d.ts

@@ -1,6 +1,27 @@
 import type { Snippet } from 'svelte';
 export type TabsOrientation = 'horizontal' | 'vertical';
 export type TabsActivationMode = 'automatic' | 'manual';
+/**
+ * Strategy used by `Tabs.List` when its triggers exceed the available space.
+ *
+ * - `'scroll'` (default): the tablist becomes horizontally (or vertically, when
+ *   `orientation="vertical"`) scrollable, hides its native scrollbar, and
+ *   programmatically scrolls the newly active trigger into view via
+ *   `scrollIntoView({ inline: 'nearest', block: 'nearest' })` on every value
+ *   change. Suited to narrow viewports (mobile) and to surfaces with an
+ *   unknown number of tabs.
+ * - `'wrap'`: the tablist wraps its triggers onto multiple lines and unsets
+ *   `white-space: nowrap` on the trigger labels so long labels remain
+ *   readable on multi-row. No `scrollIntoView` is performed because every
+ *   trigger is already visible.
+ *
+ * The previous behaviour (no overflow handling at all — long labels silently
+ * truncated and the user had no scroll affordance) is intentionally not
+ * exposed in the API: consumers who need it can still use `class` to override
+ * the styling locally, but the design system does not offer a mode whose
+ * documented behaviour is "silently broken on narrow viewports".
+ */
+export type TabsListOverflow = 'scroll' | 'wrap';
 export interface TabsProps {
     /** The currently active tab value. */
     value?: string;
@@ -20,6 +41,11 @@ export interface TabsProps {
     children?: Snippet;
 }
 export interface TabsListProps {
+    /**
+     * Strategy used when triggers exceed the available space. Defaults to
+     * `'scroll'`. See {@link TabsListOverflow}.
+     */
+    overflow?: TabsListOverflow;
     /** Additional CSS class. */
     class?: string;
     /** Content snippet. */

package/dist/components/tabs/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/components/tabs/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AAErC,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,UAAU,CAAA;AACvD,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,QAAQ,CAAA;AAEvD,MAAM,WAAW,SAAS;IACxB,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,2CAA2C;IAC3C,WAAW,CAAC,EAAE,eAAe,CAAA;IAC7B,2CAA2C;IAC3C,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;;OAIG;IACH,cAAc,CAAC,EAAE,kBAAkB,CAAA;IACnC,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uBAAuB;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uBAAuB;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,sBAAsB;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uBAAuB;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAA;IACb,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uBAAuB;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/components/tabs/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AAErC,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,UAAU,CAAA;AACvD,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,QAAQ,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEhD,MAAM,WAAW,SAAS;IACxB,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,2CAA2C;IAC3C,WAAW,CAAC,EAAE,eAAe,CAAA;IAC7B,2CAA2C;IAC3C,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;;OAIG;IACH,cAAc,CAAC,EAAE,kBAAkB,CAAA;IACnC,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uBAAuB;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAA;IAC3B,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uBAAuB;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,sBAAsB;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uBAAuB;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAA;IACb,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uBAAuB;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB"}

package/dist/components/tree/components/tree-item.svelte

@@ -140,16 +140,24 @@
     );
   }
 
+  /*
+   * Selected row colours. Themes may override
+   * `--sp-comp-tree-item-selected-{bg,fg}` to ship a WCAG AA-compliant
+   * combination — `carbon` dark does, because the default
+   * `--sp-sys-color-primary` / `--sp-sys-color-on-primary` pair fails
+   * 4.5:1 in that theme (#fff on #5c7cfa ≈ 3.67:1). Other themes keep
+   * the previous default via the var() fallback chain.
+   */
   .sp-tree-item[data-selected] > .sp-tree-item-row {
-    background: var(--sp-sys-color-primary);
-    color: var(--sp-sys-color-on-primary);
+    background: var(--sp-comp-tree-item-selected-bg, var(--sp-sys-color-primary));
+    color: var(--sp-comp-tree-item-selected-fg, var(--sp-sys-color-on-primary));
   }
 
   .sp-tree-item[data-selected] > .sp-tree-item-row:hover {
     background: color-mix(
       in oklch,
-      var(--sp-sys-color-primary) 90%,
-      var(--sp-sys-color-on-primary)
+      var(--sp-comp-tree-item-selected-bg, var(--sp-sys-color-primary)) 90%,
+      var(--sp-comp-tree-item-selected-fg, var(--sp-sys-color-on-primary))
     );
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spectral_labs/ui",
   "type": "module",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"

package/src/themes/__tests__/carbon-dark-contrast.test.ts

@@ -0,0 +1,169 @@
+/*
+ * Carbon dark — WCAG AA color-contrast regression test.
+ *
+ * The hand-tuned dark block of `themes/carbon.css` previously had three
+ * surfaces that failed WCAG 2.0 AA (≥ 4.5:1 for normal text):
+ *
+ *   - Tree.Item selected: `--sp-sys-color-on-primary` (#fff) on
+ *     `--sp-sys-color-primary` (#5c7cfa) ≈ 3.67:1
+ *   - Tabs.Trigger active: `--sp-sys-color-primary` (#5c7cfa) on
+ *     `--sp-sys-color-surface-container` (#3c3c3c) ≈ 3.00:1
+ *   - Badge outlined primary: `--sp-sys-color-primary` (#5c7cfa) on
+ *     surface (~3c3c3c) ≈ 3.00:1
+ *
+ * Fix surfaces these via three carbon-dark-specific comp tokens, expected
+ * to be ≥ 4.5:1 against their relevant background. This test asserts the
+ * tokens exist and the ratios pass — running purely on hex values read
+ * back from a live `[data-theme="carbon"].dark` element through
+ * `getComputedStyle().getPropertyValue(...)`, which jsdom resolves
+ * correctly for hex-valued custom properties (unlike rendered `color:`,
+ * which axe-core needs and jsdom cannot provide).
+ *
+ * Badge tonal secondary (#166) is intentionally not covered here: a
+ * theoretical OKLCH ratio puts it at ~16:1; we keep the existing ref-palette
+ * mapping until a runtime repro lands.
+ */
+
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterEach, beforeAll, describe, expect, it } from 'vitest'
+
+// jsdom + Vitest does not actually evaluate `import "../carbon.css"` against
+// the DOM (CSS modules become inert objects), so we inject the theme as a
+// <style> tag instead — that path *is* understood by jsdom's CSS engine and
+// makes the custom properties below resolve via getComputedStyle().
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const CARBON_CSS = readFileSync(resolve(__dirname, '../carbon.css'), 'utf-8')
+
+function hexToRgb(hex: string): [number, number, number] {
+  const clean = hex.replace(/^#/, '')
+  if (clean.length !== 6)
+    throw new Error(`Expected 6-digit hex, got "${hex}"`)
+  return [
+    Number.parseInt(clean.slice(0, 2), 16),
+    Number.parseInt(clean.slice(2, 4), 16),
+    Number.parseInt(clean.slice(4, 6), 16),
+  ]
+}
+
+function relativeLuminance([r, g, b]: [number, number, number]): number {
+  const transform = (v: number) => {
+    const u = v / 255
+    return u <= 0.03928 ? u / 12.92 : ((u + 0.055) / 1.055) ** 2.4
+  }
+  return 0.2126 * transform(r) + 0.7152 * transform(g) + 0.0722 * transform(b)
+}
+
+function wcagRatio(hexA: string, hexB: string): number {
+  const lA = relativeLuminance(hexToRgb(hexA))
+  const lB = relativeLuminance(hexToRgb(hexB))
+  const max = Math.max(lA, lB)
+  const min = Math.min(lA, lB)
+  return (max + 0.05) / (min + 0.05)
+}
+
+describe('carbon dark — WCAG AA color-contrast', () => {
+  let host: HTMLElement
+  let cs: CSSStyleDeclaration
+
+  beforeAll(() => {
+    const style = document.createElement('style')
+    style.textContent = CARBON_CSS
+    document.head.appendChild(style)
+    host = document.createElement('div')
+    host.setAttribute('data-theme', 'carbon')
+    host.classList.add('dark')
+    document.body.appendChild(host)
+    cs = getComputedStyle(host)
+  })
+
+  afterEach(() => {
+    // Each test reads from the same host; nothing to clean per-test.
+  })
+
+  function readToken(name: string): string {
+    const v = cs.getPropertyValue(name).trim()
+    if (!v)
+      throw new Error(`Custom property "${name}" is not set on the carbon dark host. Either the token is missing from themes/carbon.css or the CSS import did not load.`)
+    return v
+  }
+
+  it('tree-item selected pair (--sp-comp-tree-item-selected-bg vs -fg) passes AA (≥ 4.5)', () => {
+    const bg = readToken('--sp-comp-tree-item-selected-bg')
+    const fg = readToken('--sp-comp-tree-item-selected-fg')
+    expect(bg).toMatch(/^#[0-9a-f]{6}$/i)
+    expect(fg).toMatch(/^#[0-9a-f]{6}$/i)
+    const ratio = wcagRatio(bg, fg)
+    expect(ratio).toBeGreaterThanOrEqual(4.5)
+  })
+
+  it('tabs-trigger active label (--sp-comp-tabs-active-label-color on --sp-sys-color-surface-container) passes AA (≥ 4.5)', () => {
+    const fg = readToken('--sp-comp-tabs-active-label-color')
+    const bg = readToken('--sp-sys-color-surface-container')
+    expect(fg).toMatch(/^#[0-9a-f]{6}$/i)
+    expect(bg).toMatch(/^#[0-9a-f]{6}$/i)
+    const ratio = wcagRatio(bg, fg)
+    expect(ratio).toBeGreaterThanOrEqual(4.5)
+  })
+
+  it('badge outlined primary (--sp-comp-badge-outlined-color on --sp-sys-color-surface-container) passes AA (≥ 4.5)', () => {
+    // `--sp-comp-badge-outlined-color` is an outer-cascade override token
+    // applied by themes (here carbon dark) and read with a fallback inside
+    // `.sp-badge.outlined { color: var(--sp-comp-badge-outlined-color,
+    //   var(--sp-comp-badge-outline-fg)) }`. It lets the theme replace the
+    // outlined-foreground without fighting the local `--sp-comp-badge-*`
+    // tokens declared on `.sp-badge` itself (custom-property scope rules).
+    const fg = readToken('--sp-comp-badge-outlined-color')
+    const bg = readToken('--sp-sys-color-surface-container')
+    expect(fg).toMatch(/^#[0-9a-f]{6}$/i)
+    expect(bg).toMatch(/^#[0-9a-f]{6}$/i)
+    const ratio = wcagRatio(bg, fg)
+    expect(ratio).toBeGreaterThanOrEqual(4.5)
+  })
+
+  it('none of the carbon-dark comp tokens resolves to the legacy primary #5c7cfa', () => {
+    // Sanity check: none of the "fixed" surfaces should resolve to the
+    // legacy #5c7cfa fallback. If they do, the fix didn't actually replace
+    // the cascade — most likely the comp token landed in carbon.css but the
+    // component file still reads the system token directly.
+    expect(readToken('--sp-comp-tree-item-selected-bg').toLowerCase()).not.toBe('#5c7cfa')
+    expect(readToken('--sp-comp-tabs-active-label-color').toLowerCase()).not.toBe('#5c7cfa')
+    expect(readToken('--sp-comp-badge-outlined-color').toLowerCase()).not.toBe('#5c7cfa')
+    expect(readToken('--sp-comp-button-filled-container-color').toLowerCase()).not.toBe('#5c7cfa')
+    expect(readToken('--sp-comp-button-outlined-label-color').toLowerCase()).not.toBe('#5c7cfa')
+    expect(readToken('--sp-comp-button-text-label-color').toLowerCase()).not.toBe('#5c7cfa')
+  })
+
+  it('button filled primary (--sp-comp-button-filled-container-color vs label-color) passes AA (≥ 4.5)', () => {
+    const bg = readToken('--sp-comp-button-filled-container-color')
+    const fg = readToken('--sp-comp-button-filled-label-color')
+    expect(bg).toMatch(/^#[0-9a-f]{6}$/i)
+    expect(fg).toMatch(/^#[0-9a-f]{6}$/i)
+    const ratio = wcagRatio(bg, fg)
+    expect(ratio).toBeGreaterThanOrEqual(4.5)
+  })
+
+  it('button outlined primary (--sp-comp-button-outlined-label-color on --sp-sys-color-surface-container) passes AA (≥ 4.5)', () => {
+    // .sp-button.outlined renders with `background-color: transparent` by
+    // default, so the relevant background for the contrast check is the
+    // ancestor surface a typical button sits on — that's surface-container
+    // (#3c3c3c) in the carbon dark hand-tuned block.
+    const fg = readToken('--sp-comp-button-outlined-label-color')
+    const bg = readToken('--sp-sys-color-surface-container')
+    expect(fg).toMatch(/^#[0-9a-f]{6}$/i)
+    expect(bg).toMatch(/^#[0-9a-f]{6}$/i)
+    const ratio = wcagRatio(bg, fg)
+    expect(ratio).toBeGreaterThanOrEqual(4.5)
+  })
+
+  it('button text primary (--sp-comp-button-text-label-color on --sp-sys-color-surface-container) passes AA (≥ 4.5)', () => {
+    const fg = readToken('--sp-comp-button-text-label-color')
+    const bg = readToken('--sp-sys-color-surface-container')
+    expect(fg).toMatch(/^#[0-9a-f]{6}$/i)
+    expect(bg).toMatch(/^#[0-9a-f]{6}$/i)
+    const ratio = wcagRatio(bg, fg)
+    expect(ratio).toBeGreaterThanOrEqual(4.5)
+  })
+})

package/src/themes/carbon.css

@@ -294,5 +294,37 @@
   --sp-sys-color-success: #28a745;
   --sp-sys-color-warning: #ffc107;
   --sp-sys-color-error: #dc3545;
+
+  /*
+   * WCAG AA color-contrast — carbon dark
+   *
+   * `--sp-sys-color-primary` (#5c7cfa) is kept for branding consistency,
+   * but it fails AA in several documented carbon-dark surfaces because
+   * white-on-#5c7cfa ≈ 3.67:1 and #5c7cfa-on-#3c3c3c ≈ 3.00:1, both below
+   * the 4.5:1 normal-text threshold:
+   *
+   *   Tree.Item selected:    white on #5c7cfa  ≈ 3.67:1
+   *   Tabs.Trigger active:   #5c7cfa on #3c3c3c ≈ 3.00:1
+   *   Badge outlined:        #5c7cfa on #3c3c3c ≈ 3.00:1
+   *   Button filled primary: white on #5c7cfa  ≈ 3.67:1
+   *   Button outlined/text:  #5c7cfa on #3c3c3c ≈ 3.00:1
+   *
+   * Each surface gets a dedicated comp token here so the fix is scoped
+   * to carbon dark — other themes keep their existing tokens and visuals
+   * unchanged. Targets ≥ 4.5:1 (normal text). Two paired values reused
+   * across surfaces for visual coherence:
+   *
+   *   #3949ab on #ffffff  ≈ 7.8:1  (filled / selected surfaces: darker indigo bg + white fg)
+   *   #a4b4ff on #3c3c3c  ≈ 5.5:1  (label-on-dark-surface: lighter indigo fg)
+   */
+  --sp-comp-tree-item-selected-bg: #3949ab;
+  --sp-comp-tree-item-selected-fg: #ffffff;
+  --sp-comp-tabs-active-label-color: #a4b4ff;
+  --sp-comp-badge-outlined-color: #a4b4ff;
+  --sp-comp-button-filled-container-color: #3949ab;
+  --sp-comp-button-filled-label-color: #ffffff;
+  --sp-comp-button-outlined-label-color: #a4b4ff;
+  --sp-comp-button-outlined-outline-color: #a4b4ff;
+  --sp-comp-button-text-label-color: #a4b4ff;
 }