@inkra/react 0.3.0 → 0.5.0

package/dist/tabs/index.d.ts

@@ -1,5 +1,7 @@
 import * as Primitive from '@radix-ui/react-tabs';
 import { type ReactNode } from 'react';
+import { type TabsOverflow } from './useOverflow.js';
+export type { TabsOverflow } from './useOverflow.js';
 export interface TabsProps extends Primitive.TabsProps {
     size?: 'sm' | 'md' | 'lg';
     animated?: boolean;
@@ -8,10 +10,17 @@ export interface TabsListProps extends Primitive.TabsListProps {
     align?: 'start' | 'center' | 'end';
     fullWidth?: boolean;
     divided?: boolean;
+    /** Horizontal overflow interaction. Vertical lists retain native scrolling. */
+    overflow?: TabsOverflow;
+    moreLabel?: string;
+    scrollPreviousLabel?: string;
+    scrollNextLabel?: string;
 }
 export interface TabsTriggerProps extends Omit<Primitive.TabsTriggerProps, 'asChild'> {
     startIcon?: ReactNode;
     endIcon?: ReactNode;
+    /** Plain text used by the overflow menu for a custom trigger label. */
+    overflowLabel?: string;
 }
 export type TabsContentProps = Primitive.TabsContentProps;
 export declare const Tabs: {

package/dist/tabs/index.js

@@ -1,39 +1,92 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useInkraLocale } from '../i18n/index.js';
 import * as Primitive from '@radix-ui/react-tabs';
-import { createContext, forwardRef, useContext, useRef, useState } from 'react';
+import { createContext, forwardRef, useCallback, useContext, useMemo, useRef, useState } from 'react';
+import { __iconData as chevronLeft } from 'lucide-react/dist/esm/icons/chevron-left.mjs';
+import { __iconData as chevronRight } from 'lucide-react/dist/esm/icons/chevron-right.mjs';
+import { Button } from '../Button.js';
+import { DropdownMenu } from '../dropdown-menu/index.js';
+import { PencilIcon } from '../PencilIcon.js';
 import { PencilSurface } from '../PencilSurface.js';
 import { PencilText } from '../PencilText.js';
 import { PencilLine } from '../PencilLine.js';
 import { useSelectionDrawing } from '../internal/useSelectionDrawing.js';
+import { revealTab, useTabsOverflow } from './useOverflow.js';
+const leftPaths = chevronLeft.node.flatMap(([, attributes]) => attributes.d ? [{ d: attributes.d }] : []);
+const rightPaths = chevronRight.node.flatMap(([, attributes]) => attributes.d ? [{ d: attributes.d }] : []);
+function OverflowIcon({ left = false, down = false }) {
+    const paths = left ? leftPaths : rightPaths;
+    return _jsxs("span", { className: "inkra-tabs__overflow-icon", "data-down": down || undefined, "aria-hidden": "true", children: [_jsx(PencilIcon, { size: 32, sourceSize: 24, paths: paths }), _jsx("svg", { viewBox: "0 0 40 40", focusable: "false", children: _jsx("g", { transform: "translate(8 8)", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", children: paths.map((path, index) => _jsx("path", { d: path.d }, index)) }) })] });
+}
 const ValueContext = createContext(undefined);
 const AnimatedContext = createContext(true);
 const OrientationContext = createContext('horizontal');
 const DividedContext = createContext(false);
+const ChangeContext = createContext(() => { });
+const HiddenContext = createContext(new Set());
 const Root = forwardRef(function TabsRoot({ value, defaultValue, onValueChange, className, size = 'md', animated = true, orientation = 'horizontal', ...props }, ref) {
     const [internal, setInternal] = useState(defaultValue);
     const current = value === undefined ? internal : value;
-    const lastChange = useRef(current);
-    lastChange.current = current;
-    return _jsx(ValueContext.Provider, { value: current, children: _jsx(AnimatedContext.Provider, { value: animated, children: _jsx(OrientationContext.Provider, { value: orientation, children: _jsx(Primitive.Root, { ...props, orientation: orientation, ref: ref, "data-size": size, className: ['inkra-tabs', className].filter(Boolean).join(' '), value: current ?? '', onValueChange: next => {
-                        // Pointer focus and pointer down can request the same tab before React renders.
-                        if (lastChange.current === next)
-                            return;
-                        lastChange.current = next;
-                        if (value === undefined)
-                            setInternal(next);
-                        onValueChange?.(next);
-                    } }) }) }) });
+    const pendingRequest = useRef(null);
+    const change = (next) => {
+        // Radix pointer activation can request once from focus and once from pointer down.
+        // Deduplicate only that synchronous interaction so a rejected controlled value can retry.
+        if (pendingRequest.current === next)
+            return;
+        pendingRequest.current = next;
+        queueMicrotask(() => {
+            if (pendingRequest.current === next)
+                pendingRequest.current = null;
+        });
+        if (value === undefined)
+            setInternal(next);
+        onValueChange?.(next);
+    };
+    return _jsx(ValueContext.Provider, { value: current, children: _jsx(ChangeContext.Provider, { value: change, children: _jsx(AnimatedContext.Provider, { value: animated, children: _jsx(OrientationContext.Provider, { value: orientation, children: _jsx(Primitive.Root, { ...props, orientation: orientation, ref: ref, "data-size": size, className: ['inkra-tabs', className].filter(Boolean).join(' '), value: current ?? '', onValueChange: change }) }) }) }) });
 });
-const List = forwardRef(function TabsList({ className, align = 'start', fullWidth = false, divided = false, ...props }, ref) {
-    return _jsx(DividedContext.Provider, { value: divided, children: _jsx(Primitive.List, { ...props, ref: ref, "data-align": align, "data-full-width": fullWidth || undefined, "data-divided": divided || undefined, className: ['inkra-tabs__list', className].filter(Boolean).join(' ') }) });
+const List = forwardRef(function TabsList(inkraProps, ref) {
+    const { t } = useInkraLocale();
+    const { className, align = 'start', fullWidth = false, divided = false, overflow = 'scroll', moreLabel = t('tabs.more'), scrollPreviousLabel = t('tabs.previous'), scrollNextLabel = t('tabs.next'), onFocusCapture, ...props } = inkraProps;
+    const current = useContext(ValueContext);
+    const change = useContext(ChangeContext);
+    const mode = useContext(OrientationContext) === 'horizontal' ? overflow : 'scroll';
+    const state = useTabsOverflow(mode, current);
+    const { listRef } = state;
+    const hidden = useMemo(() => new Set(mode === 'menu' ? state.items.map(item => item.value) : []), [mode, state.items]);
+    const selectionPending = useRef(false);
+    const setRef = useCallback((node) => {
+        listRef.current = node;
+        if (typeof ref === 'function')
+            ref(node);
+        else if (ref)
+            ref.current = node;
+    }, [listRef, ref]);
+    const list = _jsx(Primitive.List, { ...props, ref: setRef, "data-overflow": mode, "data-align": align, "data-full-width": fullWidth || undefined, "data-divided": divided || undefined, className: ['inkra-tabs__list', className].filter(Boolean).join(' '), onFocusCapture: event => {
+            onFocusCapture?.(event);
+            if (!event.defaultPrevented && mode !== 'menu')
+                revealTab(listRef.current, event.target.closest('[data-tabs-value]'));
+        } });
+    const directionIcon = (previous) => _jsx(OverflowIcon, { left: previous !== state.rtl });
+    return _jsx(DividedContext.Provider, { value: divided, children: _jsx(HiddenContext.Provider, { value: hidden, children: mode === 'scroll' ? list : _jsxs("div", { className: "inkra-tabs__overflow", "data-overflow": mode, "data-has-overflow": state.overflowing || undefined, ref: state.containerRef, children: [mode === 'buttons' && state.overflowing && _jsx(Button, { size: "icon", variant: "ghost", className: "inkra-tabs__scroll-button", "aria-label": scrollPreviousLabel, title: scrollPreviousLabel, disabled: !state.previous, onClick: () => state.scroll(-1), children: directionIcon(true) }), list, mode === 'buttons' && state.overflowing && _jsx(Button, { size: "icon", variant: "ghost", className: "inkra-tabs__scroll-button", "aria-label": scrollNextLabel, title: scrollNextLabel, disabled: !state.next, onClick: () => state.scroll(1), children: directionIcon(false) }), mode === 'menu' && state.overflowing && _jsxs(DropdownMenu.Root, { dir: state.rtl ? 'rtl' : 'ltr', children: [_jsx(DropdownMenu.Trigger, { asChild: true, children: _jsx(Button, { ref: state.moreRef, size: "icon", variant: "ghost", className: "inkra-tabs__more", "aria-label": moreLabel, title: moreLabel, children: _jsx(OverflowIcon, { down: true }) }) }), _jsx(DropdownMenu.Portal, { children: _jsx(DropdownMenu.Content, { align: "end", "aria-label": moreLabel, onCloseAutoFocus: event => {
+                                        if (!selectionPending.current)
+                                            return;
+                                        selectionPending.current = false;
+                                        const selected = Array.from(listRef.current?.querySelectorAll('[data-tabs-value]') ?? [])
+                                            .find(node => node.dataset.tabsValue === current && !node.hasAttribute('data-overflow-hidden') && !node.disabled);
+                                        if (selected) {
+                                            event.preventDefault();
+                                            selected.focus({ preventScroll: true });
+                                        }
+                                    }, children: _jsx(DropdownMenu.RadioGroup, { value: current ?? '', onValueChange: next => { selectionPending.current = true; change(next); }, children: state.items.map(item => _jsx(DropdownMenu.RadioItem, { value: item.value, disabled: item.disabled, children: item.label }, item.value)) }) }) })] })] }) }) });
 });
-const Trigger = forwardRef(function TabsTrigger({ value, className, children, startIcon, endIcon, ...props }, ref) {
+const Trigger = forwardRef(function TabsTrigger({ value, className, children, startIcon, endIcon, overflowLabel, ...props }, ref) {
     const current = useContext(ValueContext);
     const divided = useContext(DividedContext);
     const orientation = useContext(OrientationContext);
+    const hidden = useContext(HiddenContext).has(value);
     const surface = useRef(null);
     useSelectionDrawing(surface, current === value, useContext(AnimatedContext));
-    return _jsxs(Primitive.Trigger, { ...props, value: value, ref: ref, className: ['inkra-tabs__trigger', className].filter(Boolean).join(' '), children: [divided && _jsx(PencilLine, { className: "inkra-tabs__divider", orientation: orientation === 'horizontal' ? 'vertical' : 'horizontal', seed: `tab-divider-${value}` }), _jsx(PencilSurface, { as: "span", "aria-hidden": "true", className: "inkra-tabs__selection", variant: "selection", seed: `tab-${value}`, ref: surface }), _jsx(PencilSurface, { as: "span", "aria-hidden": "true", className: "inkra-tabs__focus-ring", variant: "outline", seed: `tab-${value}-focus` }), startIcon && _jsx("span", { className: "inkra-tabs__icon", "aria-hidden": "true", children: startIcon }), _jsx("span", { className: "inkra-tabs__label", children: typeof children === 'string' ? _jsx(PencilText, { children: children }) : children }), endIcon && _jsx("span", { className: "inkra-tabs__icon", "aria-hidden": "true", children: endIcon })] });
+    return _jsxs(Primitive.Trigger, { ...props, value: value, ref: ref, "data-tabs-value": value, "data-overflow-label": overflowLabel, "data-overflow-hidden": hidden || undefined, "aria-hidden": hidden || props['aria-hidden'], inert: hidden || undefined, className: ['inkra-tabs__trigger', className].filter(Boolean).join(' '), children: [divided && _jsx(PencilLine, { className: "inkra-tabs__divider", orientation: orientation === 'horizontal' ? 'vertical' : 'horizontal', seed: `tab-divider-${value}` }), _jsx(PencilSurface, { as: "span", "aria-hidden": "true", className: "inkra-tabs__selection", variant: "selection", seed: `tab-${value}`, ref: surface }), _jsx(PencilSurface, { as: "span", "aria-hidden": "true", className: "inkra-tabs__focus-ring", variant: "outline", seed: `tab-${value}-focus` }), startIcon && _jsx("span", { className: "inkra-tabs__icon", "aria-hidden": "true", children: startIcon }), _jsx("span", { className: "inkra-tabs__label", children: typeof children === 'string' ? _jsx(PencilText, { children: children }) : children }), endIcon && _jsx("span", { className: "inkra-tabs__icon", "aria-hidden": "true", children: endIcon })] });
 });
 const Content = forwardRef(function TabsContent({ className, value, ...props }, ref) {
     const current = useContext(ValueContext);

package/dist/tabs/useOverflow.d.ts

@@ -0,0 +1,20 @@
+export type TabsOverflow = 'scroll' | 'menu' | 'buttons';
+interface OverflowItem {
+    value: string;
+    label: string;
+    disabled: boolean;
+}
+export declare function revealTab(list: HTMLDivElement | null, tab: HTMLElement | null): void;
+export declare function useTabsOverflow(mode: TabsOverflow, current: string | undefined): {
+    listRef: import("react").RefObject<HTMLDivElement | null>;
+    containerRef: import("react").RefObject<HTMLDivElement | null>;
+    moreRef: import("react").RefObject<HTMLButtonElement | null>;
+    scroll: (direction: -1 | 1) => void;
+    measure: () => void;
+    overflowing: boolean;
+    previous: boolean;
+    next: boolean;
+    rtl: boolean;
+    items: OverflowItem[];
+};
+export {};

package/dist/tabs/useOverflow.js

@@ -0,0 +1,145 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useBrowserLayoutEffect } from '../internal/useBrowserLayoutEffect.js';
+import { calculateOverflowListLayout } from '../overflow-list/layout.js';
+const initialState = { overflowing: false, previous: false, next: false, rtl: false, items: [] };
+function triggers(list) {
+    return Array.from(list.querySelectorAll('[data-tabs-value]'))
+        .filter(node => node.closest('[role="tablist"]') === list);
+}
+export function revealTab(list, tab) {
+    if (!list || !tab || tab.hasAttribute('data-overflow-hidden'))
+        return;
+    const view = list.getBoundingClientRect();
+    const item = tab.getBoundingClientRect();
+    const delta = item.left < view.left ? item.left - view.left : item.right > view.right ? item.right - view.right : 0;
+    if (delta)
+        list.scrollBy({ left: delta, behavior: 'instant' });
+}
+export function useTabsOverflow(mode, current) {
+    const listRef = useRef(null);
+    const containerRef = useRef(null);
+    const moreRef = useRef(null);
+    const focusAfterLayout = useRef(null);
+    const [state, setState] = useState(initialState);
+    const measure = useCallback(() => {
+        const list = listRef.current;
+        const container = containerRef.current;
+        if (mode === 'scroll' || !list || !container || container.clientWidth <= 0)
+            return;
+        const nodes = triggers(list);
+        const rtl = getComputedStyle(list).direction === 'rtl';
+        let next;
+        if (mode === 'menu') {
+            const gap = parseFloat(getComputedStyle(list).columnGap) || 0;
+            const controlWidth = moreRef.current?.getBoundingClientRect().width || 44;
+            // Use the layout box, not scrollWidth: pencil canvases include decorative paint bleed.
+            const items = nodes.map(node => {
+                const style = getComputedStyle(node);
+                const label = node.querySelector('.inkra-tabs__label');
+                const labelWidth = label ? parseFloat(getComputedStyle(label).width) || label.offsetWidth : 0;
+                const icons = Array.from(node.querySelectorAll(':scope > .inkra-tabs__icon'));
+                const width = Math.max(parseFloat(style.minWidth) || 44, labelWidth + icons.reduce((sum, icon) => sum + icon.offsetWidth, 0)
+                    + icons.length * (parseFloat(style.columnGap) || 0)
+                    + (parseFloat(style.paddingLeft) || 0) + (parseFloat(style.paddingRight) || 0));
+                return { key: node.dataset.tabsValue, width, priority: node.dataset.tabsValue === current ? 1 : 0 };
+            });
+            const layout = calculateOverflowListLayout({ items, containerWidth: container.clientWidth, gap, strategy: 'priority', triggerWidth: controlWidth });
+            const hidden = new Set(layout.overflowKeys);
+            next = {
+                overflowing: hidden.size > 0, previous: false, next: false, rtl,
+                items: nodes.filter(node => hidden.has(node.dataset.tabsValue)).map(node => ({
+                    value: node.dataset.tabsValue,
+                    label: node.dataset.overflowLabel ?? node.getAttribute('aria-label') ?? node.querySelector('.inkra-tabs__label')?.textContent ?? '',
+                    disabled: node.disabled,
+                })),
+            };
+        }
+        else {
+            const max = Math.max(0, list.scrollWidth - list.clientWidth);
+            const position = Math.min(max, Math.max(0, rtl ? -list.scrollLeft : list.scrollLeft));
+            next = { overflowing: list.scrollWidth > container.clientWidth + 1, previous: position > 1, next: position < max - 1, rtl, items: [] };
+        }
+        const active = list.ownerDocument.activeElement;
+        if (mode === 'menu' && active && nodes.some(node => node === active && next.items.some(item => item.value === node.dataset.tabsValue))) {
+            focusAfterLayout.current = 'more';
+        }
+        else if (!next.overflowing && moreRef.current && (active === moreRef.current || moreRef.current.getAttribute('aria-expanded') === 'true')) {
+            focusAfterLayout.current = 'selected';
+        }
+        setState(previous => JSON.stringify(previous) === JSON.stringify(next) ? previous : next);
+    }, [mode, current]);
+    useBrowserLayoutEffect(measure);
+    useBrowserLayoutEffect(() => {
+        if (!focusAfterLayout.current || !listRef.current)
+            return;
+        const nodes = triggers(listRef.current);
+        const target = focusAfterLayout.current === 'more' ? moreRef.current
+            : nodes.find(node => node.dataset.tabsValue === current && !node.disabled) ?? nodes.find(node => !node.disabled);
+        if (target) {
+            target.focus({ preventScroll: true });
+            focusAfterLayout.current = null;
+        }
+    }, [state, current]);
+    useEffect(() => {
+        const list = listRef.current;
+        if (!list || mode === 'scroll')
+            return;
+        let frame = 0;
+        const schedule = () => {
+            if (!frame)
+                frame = requestAnimationFrame(() => { frame = 0; measure(); });
+        };
+        const resize = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(schedule);
+        const observe = () => {
+            resize?.disconnect();
+            resize?.observe(list);
+            if (containerRef.current)
+                resize?.observe(containerRef.current);
+            for (const node of triggers(list)) {
+                resize?.observe(node);
+                const label = node.querySelector('.inkra-tabs__label');
+                if (label)
+                    resize?.observe(label);
+            }
+        };
+        observe();
+        const mutation = new MutationObserver(records => {
+            if (records.some(record => record.type === 'childList'))
+                observe();
+            schedule();
+        });
+        mutation.observe(list, { childList: true, subtree: true, characterData: true, attributes: true, attributeFilter: ['disabled', 'data-tabs-value', 'data-overflow-label'] });
+        const direction = new MutationObserver(schedule);
+        for (let node = list; node; node = node.parentElement) {
+            direction.observe(node, { attributes: true, attributeFilter: ['dir', 'style', 'class'] });
+        }
+        list.addEventListener('scroll', schedule, { passive: true });
+        if (!resize)
+            window.addEventListener('resize', schedule);
+        document.fonts?.addEventListener('loadingdone', schedule);
+        return () => {
+            cancelAnimationFrame(frame);
+            resize?.disconnect();
+            mutation.disconnect();
+            direction.disconnect();
+            list.removeEventListener('scroll', schedule);
+            window.removeEventListener('resize', schedule);
+            document.fonts?.removeEventListener('loadingdone', schedule);
+        };
+    }, [measure, mode]);
+    useBrowserLayoutEffect(() => {
+        const list = listRef.current;
+        if (list && mode !== 'menu')
+            revealTab(list, triggers(list).find(node => node.dataset.tabsValue === current) ?? null);
+    }, [current, mode]);
+    const scroll = (direction) => {
+        const list = listRef.current;
+        if (!list)
+            return;
+        list.scrollBy({
+            left: direction * (state.rtl ? -1 : 1) * Math.max(44, list.clientWidth * 0.8),
+            behavior: matchMedia('(prefers-reduced-motion: reduce)').matches ? 'instant' : 'smooth',
+        });
+    };
+    return { ...state, listRef, containerRef, moreRef, scroll, measure };
+}

package/dist/tag-input/index.d.ts

@@ -1,6 +1,6 @@
 import type { HTMLAttributes, InputHTMLAttributes } from 'react';
 import type { FieldControlSize, FieldControlStateProps } from '../form/types.js';
-import { createDefaultTag, defaultTagInputDelimiters, defaultTagValueKey, hasTagValue, normalizeTagInputValue, splitTagInputValue } from './model.js';
+import { createDefaultTag, defaultTagInputDelimiters, defaultTagValueKey, normalizeTagInputValue, splitTagInputValue } from './model.js';
 import type { TagInputIdentity } from './model.js';
 export interface TagInputTag extends TagInputIdentity {
     label?: string;
@@ -51,6 +51,10 @@ export interface TagInputProps extends Omit<HTMLAttributes<HTMLDivElement>, 'chi
     getTagValueKey?: (value: string) => string;
     delimiters?: readonly string[];
     maxTags?: number;
+    /** Opt-in initial display bound. Every value remains submitted and can be expanded. */
+    maxVisibleTags?: number;
+    showAllTagsLabel?: (count: number) => string;
+    showFewerTagsLabel?: string;
     disabled?: boolean;
     readOnly?: boolean;
     required?: boolean;
@@ -65,5 +69,6 @@ export interface TagInputProps extends Omit<HTMLAttributes<HTMLDivElement>, 'chi
     classNames?: TagInputClassNames;
 }
 export declare const TagInput: import("react").ForwardRefExoticComponent<TagInputProps & import("react").RefAttributes<HTMLInputElement>>;
-export { createDefaultTag, defaultTagInputDelimiters, defaultTagValueKey, hasTagValue, normalizeTagInputValue, splitTagInputValue, };
+export { createDefaultTag, defaultTagInputDelimiters, defaultTagValueKey, normalizeTagInputValue, splitTagInputValue, };
+export { hasTagValue } from './model.js';
 export type { FieldControlSize, TagInputIdentity };

package/dist/tag-input/index.js

@@ -1,34 +1,28 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, useEffect, useId, useImperativeHandle, useMemo, useRef, useState, } from 'react';
+import { useInkraLocale } from '../i18n/index.js';
+import { forwardRef, memo, useCallback, useEffect, useId, useImperativeHandle, useMemo, useRef, useState, } from 'react';
 import { PencilIcon } from '../PencilIcon.js';
+import { Button } from '../Button.js';
 import { PencilLine } from '../PencilLine.js';
 import { PencilSurface } from '../PencilSurface.js';
 import { PencilText } from '../PencilText.js';
 import { useResolvedControlProps } from '../form/controlProps.js';
-import { createDefaultTag, defaultTagInputDelimiters, defaultTagValueKey, hasTagValue, normalizeTagInputValue, splitTagInputValue, } from './model.js';
+import { createDefaultTag, defaultTagInputDelimiters, defaultTagValueKey, normalizeTagInputValue, splitTagInputValue, } from './model.js';
 const removePaths = [{ d: 'M18 6 6 18' }, { d: 'm6 6 12 12' }];
 const clearPaths = [{ d: 'M4 7h16' }, { d: 'M9 7V4h6v3' }, { d: 'm7 7 1 13h8l1-13' }];
 const classes = (...values) => values.filter(Boolean).join(' ');
-const defaultLabels = {
-    tagList: 'Selected tags',
-    removeTag: tag => `Remove ${tag.label ?? tag.value}`,
-    clearAll: 'Clear all tags',
-    duplicate: candidate => `${candidate} is already added.`,
-    maxTags: maximum => `You can add up to ${maximum} tags.`,
-    invalid: candidate => `${candidate} is not a valid tag.`,
-};
 function joinAriaIds(...values) {
     const ids = values.flatMap(value => value?.split(/\s+/).filter(Boolean) ?? []);
     return [...new Set(ids)].join(' ') || undefined;
 }
-function resolvedLabels(labels) {
+function resolvedLabels(labels, t) {
     return {
-        tagList: labels?.tagList ?? defaultLabels.tagList,
-        removeTag: labels?.removeTag ?? defaultLabels.removeTag,
-        clearAll: labels?.clearAll ?? defaultLabels.clearAll,
-        duplicate: labels?.duplicate ?? defaultLabels.duplicate,
-        maxTags: labels?.maxTags ?? defaultLabels.maxTags,
-        invalid: labels?.invalid ?? defaultLabels.invalid,
+        tagList: labels?.tagList ?? t('tagInput.list'),
+        removeTag: labels?.removeTag ?? (tag => t('tagInput.remove', { label: tag.label ?? tag.value })),
+        clearAll: labels?.clearAll ?? t('tagInput.clear'),
+        duplicate: labels?.duplicate ?? (label => t('tagInput.duplicate', { label })),
+        maxTags: labels?.maxTags ?? (count => t('tagInput.maximum', { count })),
+        invalid: labels?.invalid ?? (label => t('tagInput.invalid', { label })),
     };
 }
 function validationText(result, fallback) {
@@ -38,7 +32,30 @@ function validationText(result, fallback) {
         return fallback;
     return undefined;
 }
-export const TagInput = forwardRef(function TagInput({ 'aria-describedby': ariaDescribedBy, 'aria-errormessage': ariaErrorMessage, 'aria-invalid': ariaInvalid, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, classNames = {}, clearable = true, createTag, defaultInputValue = '', defaultValue = [], delimiters = defaultTagInputDelimiters, disabled, form, fullWidth = true, getTagValueKey = defaultTagValueKey, id, inputProps = {}, inputValue, invalid = false, labels, maxTags, name, onClick, onInputValueChange, onValidationError, onValueChange, placeholder, readOnly, required, seed, size = 'md', validationMessage, validateTag, value, variant = 'outline', ...rootProps }, forwardedRef) {
+// Rows contain only their own display/ref inputs. Events bubble to the list,
+// whose current handlers own selection, callbacks, guards and tag positions.
+const TagInputTagRow = memo(function TagInputTagRow({ tag, index, disabled, readOnly, className, seed, removeLabel, removeRefs, }) {
+    const removeText = readOnly ? undefined : removeLabel(tag);
+    return _jsxs(PencilSurface, { as: "li", className: classes('inkra-tag-input__tag', className), "data-tag-id": tag.id, radius: 6, seed: `${seed}-tag-${tag.id}`, variant: "quiet", children: [_jsx("span", { className: "inkra-tag-input__tag-label", children: tag.label ?? tag.value }), !readOnly ? _jsx("button", { "aria-label": removeText, className: "inkra-tag-input__remove", "data-inkra-tag-index": index, disabled: disabled, ref: node => {
+                    if (node)
+                        removeRefs.current.set(tag.id, node);
+                    else
+                        removeRefs.current.delete(tag.id);
+                }, title: removeText, type: "button", children: _jsx(PencilIcon, { decorative: true, paths: removePaths, seed: `${seed}-remove-${tag.id}`, size: 18, sourceSize: 24 }) }) : null] });
+});
+function tagRemoveTarget(event, length) {
+    const target = event.target;
+    const button = typeof target.closest === 'function'
+        ? target.closest('button.inkra-tag-input__remove[data-inkra-tag-index]')
+        : null;
+    if (!button || !event.currentTarget.contains(button))
+        return undefined;
+    const index = Number(button.getAttribute('data-inkra-tag-index'));
+    return Number.isInteger(index) && index >= 0 && index < length ? { button, index } : undefined;
+}
+export const TagInput = forwardRef(function TagInput(inkraProps, forwardedRef) {
+    const { t } = useInkraLocale();
+    const { 'aria-describedby': ariaDescribedBy, 'aria-errormessage': ariaErrorMessage, 'aria-invalid': ariaInvalid, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, classNames = {}, clearable = true, createTag, defaultInputValue = '', defaultValue = [], delimiters = defaultTagInputDelimiters, disabled, form, fullWidth = true, getTagValueKey = defaultTagValueKey, id, inputProps = {}, inputValue, invalid = false, labels, maxTags, maxVisibleTags, showAllTagsLabel = count => t('tagInput.all', { count }), showFewerTagsLabel = t('tagInput.fewer'), name, onClick, onInputValueChange, onValidationError, onValueChange, placeholder, readOnly, required, seed, size = 'md', validationMessage, validateTag, value, variant = 'outline', ...rootProps } = inkraProps;
     const generatedId = useId();
     const inputRef = useRef(null);
     const removeRefs = useRef(new Map());
@@ -50,11 +67,13 @@ export const TagInput = forwardRef(function TagInput({ 'aria-describedby': ariaD
     const [localValidationMessage, setLocalValidationMessage] = useState();
     const [focusWithin, setFocusWithin] = useState(false);
     const [pendingFocus, setPendingFocus] = useState(null);
+    const [expandedTags, setExpandedTags] = useState(false);
+    const tagDisplayLimit = maxVisibleTags !== undefined && Number.isFinite(maxVisibleTags) ? Math.max(0, Math.floor(maxVisibleTags)) : Infinity;
     const tagsControlled = value !== undefined;
     const draftControlled = inputValue !== undefined;
     const currentTags = tagsControlled ? value : uncontrolledTags;
     const currentDraft = draftControlled ? inputValue : uncontrolledDraft;
-    const copy = useMemo(() => resolvedLabels(labels), [labels]);
+    const copy = useMemo(() => resolvedLabels(labels, t), [labels, t]);
     const activeValidationMessage = validationMessage ?? localValidationMessage;
     const messageId = activeValidationMessage ? `inkra-tag-input-${generatedId}-message` : undefined;
     const state = useResolvedControlProps({
@@ -86,12 +105,16 @@ export const TagInput = forwardRef(function TagInput({ 'aria-describedby': ariaD
     useEffect(() => {
         if (!pendingFocus)
             return;
+        if ('tagId' in pendingFocus && !expandedTags && currentTags.findIndex(tag => tag.id === pendingFocus.tagId) >= tagDisplayLimit) {
+            setExpandedTags(true);
+            return;
+        }
         const target = 'input' in pendingFocus
             ? inputRef.current
             : removeRefs.current.get(pendingFocus.tagId) ?? inputRef.current;
         target?.focus({ preventScroll: true });
         setPendingFocus(null);
-    }, [currentTags, pendingFocus]);
+    }, [currentTags, pendingFocus, expandedTags, tagDisplayLimit]);
     useEffect(() => {
         const input = inputRef.current;
         const ownerForm = input?.form;
@@ -121,11 +144,11 @@ export const TagInput = forwardRef(function TagInput({ 'aria-describedby': ariaD
             setUncontrolledDraft(next);
         onInputValueChange?.(next, details);
     };
-    const commitTags = (next, details) => {
+    const commitTags = useCallback((next, details) => {
         if (!tagsControlled)
             setUncontrolledTags([...next]);
         onValueChange?.(next, details);
-    };
+    }, [tagsControlled, onValueChange]);
     const reportValidation = (candidate, reason, code, message, tags) => {
         setLocalValidationMessage(message);
         onValidationError?.(message, { candidate, code, reason, tags });
@@ -134,6 +157,8 @@ export const TagInput = forwardRef(function TagInput({ 'aria-describedby': ariaD
         if (!canEdit)
             return false;
         const working = [...currentTags];
+        const valueKeys = new Set(currentTags.map(tag => getTagValueKey(tag.value)));
+        const ids = new Set(currentTags.map(tag => tag.id));
         const added = [];
         let rejected;
         for (const rawCandidate of candidates) {
@@ -144,7 +169,7 @@ export const TagInput = forwardRef(function TagInput({ 'aria-describedby': ariaD
                 rejected = { candidate, code: 'max-tags', message: copy.maxTags(limit) };
                 break;
             }
-            if (hasTagValue(working, candidate, getTagValueKey)) {
+            if (valueKeys.has(getTagValueKey(candidate))) {
                 rejected = { candidate, code: 'duplicate', message: copy.duplicate(candidate) };
                 break;
             }
@@ -159,11 +184,13 @@ export const TagInput = forwardRef(function TagInput({ 'aria-describedby': ariaD
                 rejected = { candidate, code: 'invalid', message: copy.invalid(candidate) };
                 break;
             }
-            if (working.some(current => current.id === tag.id) || hasTagValue(working, tag.value, getTagValueKey)) {
+            if (ids.has(tag.id) || valueKeys.has(getTagValueKey(tag.value))) {
                 rejected = { candidate, code: 'duplicate', message: copy.duplicate(candidate) };
                 break;
             }
             working.push(tag);
+            ids.add(tag.id);
+            valueKeys.add(getTagValueKey(tag.value));
             added.push(tag);
         }
         if (added.length > 0)
@@ -183,7 +210,7 @@ export const TagInput = forwardRef(function TagInput({ 'aria-describedby': ariaD
         const parsed = splitTagInputValue(currentDraft, delimiters);
         return commitCandidates(parsed.parts, reason);
     };
-    const removeTag = (index, focus = null) => {
+    const removeTag = useCallback((index, focus = null) => {
         if (!canEdit)
             return;
         const tag = currentTags[index];
@@ -198,7 +225,7 @@ export const TagInput = forwardRef(function TagInput({ 'aria-describedby': ariaD
         setLocalValidationMessage(undefined);
         commitTags(next, { reason: 'remove', tags: [tag] });
         setPendingFocus(nextFocus);
-    };
+    }, [canEdit, currentTags, commitTags]);
     const clearAll = () => {
         if (!canEdit || currentTags.length === 0)
             return;
@@ -208,11 +235,15 @@ export const TagInput = forwardRef(function TagInput({ 'aria-describedby': ariaD
         updateDraft('', { reason: 'clear' });
         setPendingFocus({ input: true });
     };
-    const focusRemoveButton = (index) => {
+    const focusRemoveButton = useCallback((index) => {
         const tag = currentTags[index];
-        if (tag)
-            removeRefs.current.get(tag.id)?.focus({ preventScroll: true });
-    };
+        if (tag) {
+            if (!expandedTags && index >= tagDisplayLimit)
+                setPendingFocus({ tagId: tag.id });
+            else
+                removeRefs.current.get(tag.id)?.focus({ preventScroll: true });
+        }
+    }, [currentTags, expandedTags, tagDisplayLimit]);
     const handleInputChange = (event) => {
         inputProps.onChange?.(event);
         if (event.defaultPrevented)
@@ -265,10 +296,10 @@ export const TagInput = forwardRef(function TagInput({ 'aria-describedby': ariaD
             commitDraft('delimiter');
         }
     };
-    const handleTagKeyDown = (event, index) => {
+    const handleTagKeyDown = useCallback((event, index, button) => {
         if (event.defaultPrevented || !canEdit)
             return;
-        const direction = getComputedStyle(event.currentTarget).direction;
+        const direction = getComputedStyle(button).direction;
         const previousKey = direction === 'rtl' ? 'ArrowRight' : 'ArrowLeft';
         const nextKey = direction === 'rtl' ? 'ArrowLeft' : 'ArrowRight';
         if (event.key === previousKey) {
@@ -294,8 +325,12 @@ export const TagInput = forwardRef(function TagInput({ 'aria-describedby': ariaD
             event.preventDefault();
             removeTag(index);
         }
-    };
-    return (_jsxs("div", { ...rootProps, className: classes('inkra-field-control-hit', 'inkra-tag-input', className, classNames.root), "data-disabled": state.disabled || undefined, "data-focus-within": focusWithin || undefined, "data-full-width": fullWidth, "data-invalid": state.invalid || undefined, "data-max-reached": atLimit || undefined, "data-readonly": state.readOnly || undefined, "data-size": size, "data-variant": variant, onBlurCapture: event => {
+    }, [canEdit, currentTags.length, focusRemoveButton, removeTag]);
+    // Stable rows survive immutable edits to other tags. Parent event handlers
+    // remain fresh instead of hiding a changing callback behind a memo comparator.
+    const tagRows = useMemo(() => (expandedTags || tagDisplayLimit >= currentTags.length ? currentTags : currentTags.slice(0, tagDisplayLimit)).map((tag, index) => _jsx(TagInputTagRow, { className: classNames.tag, disabled: state.disabled, index: index, readOnly: state.readOnly, removeLabel: copy.removeTag, removeRefs: removeRefs, seed: resolvedSeed, tag: tag }, `${tag.id}-${index}`)), [currentTags, state.disabled, state.readOnly, copy.removeTag, classNames.tag, resolvedSeed, expandedTags, tagDisplayLimit]);
+    const formValues = useMemo(() => name ? currentTags.map((tag, index) => (_jsx("input", { disabled: state.disabled, form: form, name: name, type: "hidden", value: tag.value }, `${tag.id}-${index}`))) : null, [currentTags, state.disabled, form, name]);
+    return (_jsxs("div", { ...rootProps, className: classes('inkra-field-control-hit', 'inkra-tag-input', className, classNames.root), "data-disabled": state.disabled || undefined, "data-draft-empty": currentDraft.length === 0 || undefined, "data-focus-within": focusWithin || undefined, "data-full-width": fullWidth, "data-has-placeholder": Boolean(placeholder) || undefined, "data-has-tags": currentTags.length > 0 || undefined, "data-invalid": state.invalid || undefined, "data-max-reached": atLimit || undefined, "data-readonly": state.readOnly || undefined, "data-size": size, "data-variant": variant, onBlurCapture: event => {
             if (!event.currentTarget.contains(event.relatedTarget))
                 setFocusWithin(false);
             rootProps.onBlurCapture?.(event);
@@ -309,17 +344,21 @@ export const TagInput = forwardRef(function TagInput({ 'aria-describedby': ariaD
         }, onFocusCapture: event => {
             setFocusWithin(true);
             rootProps.onFocusCapture?.(event);
-        }, children: [_jsxs(PencilSurface, { as: "div", className: classes('inkra-field-control', 'inkra-tag-input__control', classNames.control), radius: 8, seed: resolvedSeed, variant: surfaceVariant, children: [_jsx("ul", { "aria-label": copy.tagList, className: classes('inkra-tag-input__list', classNames.list), children: currentTags.map((tag, index) => (_jsxs(PencilSurface, { as: "li", className: classes('inkra-tag-input__tag', classNames.tag), clipContent: true, "data-tag-id": tag.id, radius: 6, seed: `${resolvedSeed}-tag-${tag.id}`, variant: "quiet", children: [_jsx("span", { className: "inkra-tag-input__tag-label", children: tag.label ?? tag.value }), !state.readOnly ? (_jsx("button", { "aria-label": copy.removeTag(tag), className: "inkra-tag-input__remove", disabled: state.disabled, onClick: () => removeTag(index), onKeyDown: event => handleTagKeyDown(event, index), ref: node => {
-                                        if (node)
-                                            removeRefs.current.set(tag.id, node);
-                                        else
-                                            removeRefs.current.delete(tag.id);
-                                    }, title: copy.removeTag(tag), type: "button", children: _jsx(PencilIcon, { decorative: true, paths: removePaths, seed: `${resolvedSeed}-remove-${tag.id}`, size: 18, sourceSize: 24 }) })) : null] }, `${tag.id}-${index}`))) }), _jsx("input", { ...inputProps, "aria-describedby": state.describedBy, "aria-errormessage": state.errorMessage, "aria-invalid": state.ariaInvalid, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-readonly": state.readOnly || undefined, "aria-required": state.required || undefined, autoComplete: inputProps.autoComplete ?? 'off', className: classes('inkra-input', 'inkra-tag-input__input', inputProps.className, classNames.input), disabled: state.disabled, form: form, id: state.id, onChange: handleInputChange, onCompositionEnd: event => {
+        }, children: [_jsxs(PencilSurface, { as: "div", className: classes('inkra-field-control', 'inkra-tag-input__control', classNames.control), radius: 8, seed: resolvedSeed, variant: surfaceVariant, children: [_jsxs("ul", { "aria-label": copy.tagList, className: classes('inkra-tag-input__list', classNames.list), onClick: event => {
+                            const target = tagRemoveTarget(event, currentTags.length);
+                            if (target)
+                                removeTag(target.index);
+                        }, onKeyDown: event => {
+                            const target = tagRemoveTarget(event, currentTags.length);
+                            if (target)
+                                handleTagKeyDown(event, target.index, target.button);
+                        }, children: [tagRows, currentTags.length > tagDisplayLimit && _jsx("li", { children: _jsx(Button, { type: "button", size: "sm", variant: "ghost", "aria-expanded": expandedTags, onClick: () => setExpandedTags(current => !current), children: expandedTags ? showFewerTagsLabel : showAllTagsLabel(currentTags.length) }) })] }), _jsx("input", { ...inputProps, "aria-describedby": state.describedBy, "aria-errormessage": state.errorMessage, "aria-invalid": state.ariaInvalid, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-readonly": state.readOnly || undefined, "aria-required": state.required || undefined, autoComplete: inputProps.autoComplete ?? 'off', className: classes('inkra-input', 'inkra-tag-input__input', inputProps.className, classNames.input), disabled: state.disabled, form: form, id: state.id, onChange: handleInputChange, onCompositionEnd: event => {
                             composingRef.current = false;
                             inputProps.onCompositionEnd?.(event);
                         }, onCompositionStart: event => {
                             composingRef.current = true;
                             inputProps.onCompositionStart?.(event);
-                        }, onKeyDown: handleInputKeyDown, onPaste: handleInputPaste, placeholder: placeholder, readOnly: state.readOnly, ref: inputRef, required: state.required && currentTags.length === 0, spellCheck: inputProps.spellCheck ?? false, type: "text", value: currentDraft }), clearable && currentTags.length > 0 && !state.readOnly ? (_jsx("button", { "aria-label": copy.clearAll, className: classes('inkra-tag-input__clear', classNames.clear), disabled: state.disabled, onClick: clearAll, onPointerDown: (event) => event.preventDefault(), title: copy.clearAll, type: "button", children: _jsx(PencilIcon, { decorative: true, paths: clearPaths, seed: `${resolvedSeed}-clear`, size: 20, sourceSize: 24 }) })) : null, variant === 'underline' ? (_jsx(PencilLine, { className: "inkra-tag-input__underline", seed: `${resolvedSeed}-underline`, weight: (focusWithin ? 1.5 : 1) + (state.invalid ? 0.1 : 0) })) : null] }), name ? currentTags.map((tag, index) => (_jsx("input", { disabled: state.disabled, form: form, name: name, type: "hidden", value: tag.value }, `${tag.id}-${index}`))) : null, activeValidationMessage ? (_jsx(PencilText, { as: "span", className: classes('inkra-tag-input__message', classNames.message), id: messageId, role: "alert", seed: `${resolvedSeed}-message`, children: activeValidationMessage })) : null] }));
+                        }, onKeyDown: handleInputKeyDown, onPaste: handleInputPaste, placeholder: placeholder, readOnly: state.readOnly, ref: inputRef, required: state.required && currentTags.length === 0, spellCheck: inputProps.spellCheck ?? false, type: "text", value: currentDraft }), clearable && currentTags.length > 0 && !state.readOnly ? (_jsx("button", { "aria-label": copy.clearAll, className: classes('inkra-tag-input__clear', classNames.clear), disabled: state.disabled, onClick: clearAll, onPointerDown: (event) => event.preventDefault(), title: copy.clearAll, type: "button", children: _jsx(PencilIcon, { decorative: true, paths: clearPaths, seed: `${resolvedSeed}-clear`, size: 20, sourceSize: 24 }) })) : null, variant === 'underline' ? (_jsx(PencilLine, { className: "inkra-tag-input__underline", seed: `${resolvedSeed}-underline`, weight: (focusWithin ? 1.5 : 1) + (state.invalid ? 0.1 : 0) })) : null] }), formValues, activeValidationMessage ? (_jsx(PencilText, { as: "span", className: classes('inkra-tag-input__message', classNames.message), id: messageId, role: "alert", seed: `${resolvedSeed}-message`, children: activeValidationMessage })) : null] }));
 });
-export { createDefaultTag, defaultTagInputDelimiters, defaultTagValueKey, hasTagValue, normalizeTagInputValue, splitTagInputValue, };
+export { createDefaultTag, defaultTagInputDelimiters, defaultTagValueKey, normalizeTagInputValue, splitTagInputValue, };
+export { hasTagValue } from './model.js';

package/dist/theme/index.d.ts

@@ -0,0 +1,11 @@
+import type { HTMLAttributes } from 'react';
+export type InkraTheme = 'light' | 'dark' | 'auto';
+export type InkraThemeTokens = Partial<Record<`--inkra-${string}`, string | number>>;
+export interface ThemeProviderProps extends HTMLAttributes<HTMLDivElement> {
+    /** Omit to inherit the surrounding theme. auto follows the system through CSS. */
+    theme?: InkraTheme;
+    /** Scoped CSS variables. Lengths must include units, for example "1.5px". */
+    tokens?: InkraThemeTokens;
+}
+/** A CSS scope: never modifies document attributes, storage or sibling themes. */
+export declare const ThemeProvider: import("react").ForwardRefExoticComponent<ThemeProviderProps & import("react").RefAttributes<HTMLDivElement>>;