@tangible/ui 0.0.1 → 0.0.3

package/components/Card/Card.d.ts

@@ -11,6 +11,7 @@ type CommonProps = {
 };
 export type CardRootProps<TAs extends RootAs = 'article'> = CommonProps & {
     as?: TAs;
+    /** @deprecated Use Card.Link for interactive cards. onClick without Card.Link has no keyboard/screen-reader semantics. */
     onClick?: React.MouseEventHandler<HTMLElement>;
     children?: React.ReactNode;
 };

package/components/Card/Card.js

@@ -1,29 +1,26 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import React, { forwardRef, useCallback } from 'react';
+import React, { forwardRef, useRef, useEffect } from 'react';
 import { cx } from '../../utils/cx.js';
+import { isDev } from '../../utils/is-dev.js';
 export const Card = forwardRef(function Card({ as = 'article', inline, elevated, interactive, disabled, className, style, onClick, children, ...rest }, ref) {
     const Tag = as;
-    // Determine if this card is clickable (needs button semantics)
-    const isClickable = (interactive || onClick) && !disabled;
-    // Keyboard handler for interactive cards
-    const handleKeyDown = useCallback((e) => {
-        if (!isClickable || !onClick)
-            return;
-        if (e.key === 'Enter' || e.key === ' ') {
-            e.preventDefault();
-            onClick(e);
+    const hasCardLinkChild = React.Children.toArray(children).some((child) => {
+        if (!React.isValidElement(child))
+            return false;
+        const type = child.type;
+        return child.type === CardLink || type.displayName === 'Card.Link';
+    });
+    // Dev warning: suggest Card.Link for interactive cards
+    const warnedRef = useRef(false);
+    useEffect(() => {
+        if (isDev() && !warnedRef.current && (interactive || onClick) && !hasCardLinkChild) {
+            warnedRef.current = true;
+            console.warn('[TUI Card] Interactive cards should use <Card.Link> for accessible click targets. ' +
+                '`interactive` and `onClick` provide visual hover styles but no keyboard/screen-reader semantics.');
         }
-    }, [isClickable, onClick]);
+    }, [interactive, onClick, hasCardLinkChild]);
     const classes = cx('tui-card', inline && 'is-layout-inline', elevated && 'is-style-elevated', interactive && 'has-interaction', className);
-    // Button semantics for clickable cards
-    const buttonProps = isClickable
-        ? {
-            role: 'button',
-            tabIndex: 0,
-            onKeyDown: handleKeyDown,
-        }
-        : {};
-    return (_jsx(Tag, { ref: ref, className: classes, style: style, "aria-disabled": disabled || undefined, onClick: disabled ? undefined : onClick, ...buttonProps, ...rest, children: _jsx("div", { className: "tui-card__inner", children: children }) }));
+    return (_jsx(Tag, { ref: ref, className: classes, style: style, "aria-disabled": disabled || undefined, onClick: disabled ? undefined : onClick, ...rest, children: _jsx("div", { className: "tui-card__inner", children: children }) }));
 });
 function CardHead({ className, children, ...rest }) {
     return (_jsx("div", { className: cx('tui-card__head', className), ...rest, children: children }));

package/components/Checkbox/Checkbox.d.ts

@@ -0,0 +1,9 @@
+export declare const Checkbox: import("react").ForwardRefExoticComponent<Omit<import("react").InputHTMLAttributes<HTMLInputElement>, "role" | "type" | "defaultChecked" | "onChange" | "checked"> & {
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    indeterminate?: boolean;
+    label?: import("react").ReactNode;
+    disabled?: boolean;
+    className?: string;
+} & import("react").RefAttributes<HTMLInputElement>>;

package/components/Checkbox/Checkbox.js

@@ -0,0 +1,92 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useEffect, useRef } from 'react';
+import { cx } from '../../utils/cx.js';
+import { composeRefs } from '../../utils/compose-refs.js';
+import { useControllableState } from '../../utils/use-controllable-state.js';
+import { isDev } from '../../utils/is-dev.js';
+// =============================================================================
+// Checkbox Component
+// =============================================================================
+//
+// Native <input type="checkbox"> with accent-color, reusing tui-inline-choice CSS.
+//
+// Bare (no label): returns <input> directly for Field.Control cloneElement.
+// With label: wraps in <label class="tui-inline-choice">.
+//
+// CSS token API (inherited from input styles):
+//   --tui-input-accent    Accent color for checked state
+//
+// =============================================================================
+// Props that should route to the <input>, not the wrapper label
+const INPUT_PROPS = new Set([
+    'id',
+    'name',
+    'value',
+    'aria-describedby',
+    'aria-invalid',
+    'aria-required',
+    'aria-label',
+    'aria-labelledby',
+    'form',
+    'required',
+    'tabIndex',
+    'autoFocus',
+    'onFocus',
+    'onBlur',
+]);
+export const Checkbox = forwardRef(function Checkbox({ checked: controlledChecked, defaultChecked = false, onCheckedChange, indeterminate = false, label, disabled, className, ...rest }, externalRef) {
+    const internalRef = useRef(null);
+    const [checked, setChecked] = useControllableState({
+        value: controlledChecked,
+        defaultValue: defaultChecked,
+        onChange: onCheckedChange,
+    });
+    // Sync indeterminate DOM property (not available as HTML attribute)
+    useEffect(() => {
+        if (internalRef.current) {
+            internalRef.current.indeterminate = indeterminate;
+        }
+    }, [indeterminate]);
+    // Dev-only: warn if bare checkbox has no accessible name (fire once)
+    const hasWarnedRef = useRef(false);
+    useEffect(() => {
+        if (hasWarnedRef.current)
+            return;
+        if (isDev() && !label) {
+            const ariaLabel = rest['aria-label'];
+            const ariaLabelledBy = rest['aria-labelledby'];
+            // Check explicit ARIA props, then fall back to native <label> association
+            // (e.g. Field.Label htmlFor wiring via Field.Control id injection)
+            const hasName = (typeof ariaLabel === 'string' && ariaLabel.trim() !== '') ||
+                (typeof ariaLabelledBy === 'string' && ariaLabelledBy.trim() !== '') ||
+                (internalRef.current?.labels && internalRef.current.labels.length > 0);
+            if (!hasName) {
+                console.warn('Checkbox: Missing accessible name. Provide label prop, aria-label, or aria-labelledby.');
+                hasWarnedRef.current = true;
+            }
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const handleChange = () => {
+        // Clicking an indeterminate checkbox produces checked=true (native behaviour)
+        setChecked((prev) => !prev);
+    };
+    const isChecked = checked ?? false;
+    // Bare: no label — Field.Control can inject id/aria-* directly
+    if (!label) {
+        return (_jsx("input", { ref: composeRefs(internalRef, externalRef), type: "checkbox", checked: isChecked, disabled: disabled, className: className, "data-indeterminate": indeterminate || undefined, "aria-checked": indeterminate ? 'mixed' : undefined, onChange: handleChange, ...rest }));
+    }
+    // Split rest props: some go on input, some on wrapper
+    const inputProps = {};
+    const wrapperProps = {};
+    for (const [key, val] of Object.entries(rest)) {
+        if (INPUT_PROPS.has(key)) {
+            inputProps[key] = val;
+        }
+        else {
+            wrapperProps[key] = val;
+        }
+    }
+    // With label: wrap in tui-inline-choice
+    return (_jsxs("label", { className: cx('tui-inline-choice', disabled && 'is-disabled', className), ...wrapperProps, children: [_jsx("input", { ref: composeRefs(internalRef, externalRef), type: "checkbox", checked: isChecked, disabled: disabled, "data-indeterminate": indeterminate || undefined, "aria-checked": indeterminate ? 'mixed' : undefined, onChange: handleChange, ...inputProps }), _jsx("span", { children: label })] }));
+});

package/components/Checkbox/index.d.ts

@@ -0,0 +1,2 @@
+export { Checkbox } from './Checkbox';
+export type { CheckboxProps } from './types';

package/components/Checkbox/index.js

@@ -0,0 +1 @@
+export { Checkbox } from './Checkbox.js';

package/components/Checkbox/types.d.ts

@@ -0,0 +1,10 @@
+import type { InputHTMLAttributes, ReactNode } from 'react';
+export type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'checked' | 'defaultChecked' | 'onChange' | 'role'> & {
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    indeterminate?: boolean;
+    label?: ReactNode;
+    disabled?: boolean;
+    className?: string;
+};

package/components/Checkbox/types.js

@@ -0,0 +1 @@
+export {};

package/components/Chip/Chip.d.ts

@@ -1,4 +1,5 @@
 import * as React from 'react';
+import type { OptionValue } from '../../utils/value-key';
 import type { SizeCompact, Theme as ThemeFull } from '../../types';
 type Size = SizeCompact;
 type Theme = ThemeFull;
@@ -19,6 +20,8 @@ export type ChipProps = {
     leftIcon?: React.ReactNode;
     rightIcon?: React.ReactNode;
     onClick?: React.MouseEventHandler<HTMLElement>;
+    /** When inside ChipGroup, identifies this chip for selection tracking */
+    value?: OptionValue;
 } & Omit<React.HTMLAttributes<HTMLSpanElement>, 'onClick'>;
-export declare function Chip({ as, href, target, rel, children, size, theme, variant, selected, disabled, interactive, className, leftIcon, rightIcon, onClick, ...rest }: ChipProps): import("react/jsx-runtime").JSX.Element;
+export declare function Chip({ as, href, target, rel, children, size, theme, variant, selected: selectedProp, disabled: disabledProp, interactive, className, leftIcon, rightIcon, onClick: onClickProp, value, ...rest }: ChipProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/components/Chip/Chip.js

@@ -1,11 +1,31 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from 'react';
-import { useCallback } from 'react';
+import { useCallback, useEffect } from 'react';
 import { cx } from '../../utils/cx.js';
-export function Chip({ as = 'span', href, target, rel, children, size = 'md', theme = 'secondary', variant = 'default', selected, disabled, interactive, className, leftIcon, rightIcon, onClick, ...rest }) {
+import { toKey } from '../../utils/value-key.js';
+import { isDev } from '../../utils/is-dev.js';
+import { useChipGroupContext } from '../ChipGroup/ChipGroupContext.js';
+export function Chip({ as = 'span', href, target, rel, children, size = 'md', theme = 'secondary', variant = 'default', selected: selectedProp, disabled: disabledProp, interactive, className, leftIcon, rightIcon, onClick: onClickProp, value, ...rest }) {
+    const groupContext = useChipGroupContext();
+    // Dev warning: inside ChipGroup without value
+    useEffect(() => {
+        if (isDev() && groupContext && value === undefined) {
+            console.warn('Chip: Inside a ChipGroup but missing `value` prop. This chip will not be managed by the group.');
+        }
+    }, [groupContext, value]);
+    // Derive from group context when applicable
+    const isManaged = groupContext !== null && value !== undefined;
+    const selected = isManaged ? groupContext.selectedValues.has(toKey(value)) : selectedProp;
+    const disabled = (isManaged ? groupContext.disabled : false) || disabledProp;
+    const managedClick = useCallback(() => {
+        if (groupContext && value !== undefined) {
+            groupContext.onSelect(value);
+        }
+    }, [groupContext, value]);
+    const onClick = isManaged ? managedClick : onClickProp;
     const Tag = (as === 'a' ? 'a' : as);
     // Determine if this chip is clickable (needs button semantics)
-    const isClickable = (interactive || onClick) && !disabled;
+    const isClickable = (interactive || onClick || isManaged) && !disabled;
     // Keyboard handler for interactive chips
     const handleKeyDown = useCallback((e) => {
         if (!isClickable || !onClick)
@@ -15,7 +35,7 @@ export function Chip({ as = 'span', href, target, rel, children, size = 'md', th
             onClick(e);
         }
     }, [isClickable, onClick]);
-    const classes = cx('tui-chip', size && `is-size-${size}`, theme && `is-theme-${theme}`, variant !== 'default' && `is-style-${variant}`, selected && 'is-selected', interactive && 'is-interactive', className);
+    const classes = cx('tui-chip', size && `is-size-${size}`, theme && `is-theme-${theme}`, variant !== 'default' && `is-style-${variant}`, selected && 'is-selected', (interactive || isManaged) && 'is-interactive', className);
     const anchorProps = as === 'a'
         ? {
             href: disabled ? undefined : href ?? '#',
@@ -25,12 +45,17 @@ export function Chip({ as = 'span', href, target, rel, children, size = 'md', th
             tabIndex: disabled ? -1 : undefined,
         }
         : { 'aria-disabled': disabled || undefined };
-    // Button semantics for non-anchor clickable chips
-    const buttonProps = as !== 'a' && isClickable
+    // Button semantics for clickable chips.
+    // Non-anchor clickable chips always need role="button".
+    // Managed anchor chips also get role="button" — toggle semantics
+    // take priority over link semantics inside a ChipGroup.
+    const needsButtonRole = isClickable && (as !== 'a' || isManaged);
+    const buttonProps = needsButtonRole
         ? {
             role: 'button',
-            tabIndex: 0,
+            tabIndex: as !== 'a' ? 0 : undefined, // anchors are natively focusable
             onKeyDown: handleKeyDown,
+            'aria-pressed': isManaged ? (selected ?? false) : undefined,
         }
         : {};
     return (_jsxs(Tag, { className: classes, ...anchorProps, ...buttonProps, onClick: disabled ? undefined : onClick, ...rest, children: [leftIcon && leftIcon, _jsx("span", { className: "tui-chip__text", children: children }), rightIcon && rightIcon] }));

package/components/ChipGroup/ChipGroup.d.ts

@@ -0,0 +1,5 @@
+import type { ChipGroupProps } from './types';
+export declare function ChipGroup(props: ChipGroupProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ChipGroup {
+    var displayName: string;
+}

package/components/ChipGroup/ChipGroup.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo } from 'react';
+import { cx } from '../../utils/cx.js';
+import { useControllableState } from '../../utils/use-controllable-state.js';
+import { toKey } from '../../utils/value-key.js';
+import { ChipGroupContext } from './ChipGroupContext.js';
+import { isDev } from '../../utils/is-dev.js';
+// =============================================================================
+// ChipGroup Component
+// =============================================================================
+//
+// Selection group for Chip components. Provides context to managed Chips.
+// Chips with a `value` prop derive selected/onClick from context.
+//
+// Single mode: one selection at a time (toggleable — clicking selected deselects)
+// Multiple mode: toggle individual chips on/off
+//
+// =============================================================================
+export function ChipGroup(props) {
+    const { multiple = false, disabled = false, density = 'sm', direction = 'inline', alignment, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, children, } = props;
+    // --- Single mode ---
+    // isControlled override: 'value' in props detects explicit value={undefined}
+    // (deselection) vs prop not passed at all (uncontrolled).
+    const [singleValue, setSingleValue] = useControllableState({
+        value: !multiple ? props.value : undefined,
+        defaultValue: !multiple ? props.defaultValue : undefined,
+        onChange: !multiple ? props.onValueChange : undefined,
+        isControlled: !multiple && 'value' in props,
+    });
+    // --- Multiple mode ---
+    const [multiValue, setMultiValue] = useControllableState({
+        value: multiple ? props.value : undefined,
+        defaultValue: multiple ? (props.defaultValue ?? []) : undefined,
+        onChange: multiple ? props.onValueChange : undefined,
+        isControlled: multiple && 'value' in props,
+    });
+    // Build Set of toKey'd values for efficient lookup in Chip
+    const selectedValues = useMemo(() => {
+        if (multiple) {
+            return new Set((multiValue ?? []).map(toKey));
+        }
+        return singleValue !== undefined ? new Set([toKey(singleValue)]) : new Set();
+    }, [multiple, singleValue, multiValue]);
+    const onSelect = useCallback((value) => {
+        if (multiple) {
+            setMultiValue((prev) => {
+                const current = prev ?? [];
+                const key = toKey(value);
+                return current.some((v) => toKey(v) === key)
+                    ? current.filter((v) => toKey(v) !== key)
+                    : [...current, value];
+            });
+        }
+        else {
+            // Toggle: clicking selected chip deselects
+            setSingleValue((prev) => prev !== undefined && toKey(prev) === toKey(value) ? undefined : value);
+        }
+    }, [multiple, setSingleValue, setMultiValue]);
+    const contextValue = useMemo(() => ({ selectedValues, multiple, disabled, onSelect }), [selectedValues, multiple, disabled, onSelect]);
+    // Dev-only: warn if group has no accessible name
+    useEffect(() => {
+        if (isDev() && !ariaLabel && !ariaLabelledBy) {
+            console.warn('ChipGroup: Missing accessible name. Provide aria-label or aria-labelledby.');
+        }
+    }, [ariaLabel, ariaLabelledBy]);
+    return (_jsx(ChipGroupContext.Provider, { value: contextValue, children: _jsx("div", { role: "group", "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className: cx('tui-chip-group', `is-density-${density}`, direction === 'stack' && 'is-direction-stack', alignment && `is-align-${alignment}`, className), children: children }) }));
+}
+ChipGroup.displayName = 'ChipGroup';

package/components/ChipGroup/ChipGroupContext.d.ts

@@ -0,0 +1,3 @@
+import type { ChipGroupContextValue } from './types';
+export declare const ChipGroupContext: import("react").Context<ChipGroupContextValue | null>;
+export declare function useChipGroupContext(): ChipGroupContextValue | null;

package/components/ChipGroup/ChipGroupContext.js

@@ -0,0 +1,5 @@
+import { createContext, useContext } from 'react';
+export const ChipGroupContext = createContext(null);
+export function useChipGroupContext() {
+    return useContext(ChipGroupContext);
+}

package/components/ChipGroup/index.d.ts

@@ -0,0 +1,3 @@
+export { ChipGroup } from './ChipGroup';
+export { useChipGroupContext } from './ChipGroupContext';
+export type { ChipGroupProps, ChipGroupSingleProps, ChipGroupMultipleProps } from './types';

package/components/ChipGroup/index.js

@@ -0,0 +1,2 @@
+export { ChipGroup } from './ChipGroup.js';
+export { useChipGroupContext } from './ChipGroupContext.js';

package/components/ChipGroup/types.d.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react';
+import type { OptionValue } from '../../utils/value-key';
+type ChipGroupBaseProps = {
+    disabled?: boolean;
+    /** Gap between chips. Default 'sm'. */
+    density?: 'xs' | 'sm' | 'md';
+    /** Layout direction. Default 'inline' (row wrap). */
+    direction?: 'inline' | 'stack';
+    /** Alignment along main axis. */
+    alignment?: 'start' | 'center' | 'end';
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    className?: string;
+    children: ReactNode;
+};
+export type ChipGroupSingleProps = ChipGroupBaseProps & {
+    multiple?: false;
+    value?: OptionValue;
+    defaultValue?: OptionValue;
+    onValueChange?: (value: OptionValue | undefined) => void;
+};
+export type ChipGroupMultipleProps = ChipGroupBaseProps & {
+    multiple: true;
+    value?: OptionValue[];
+    defaultValue?: OptionValue[];
+    onValueChange?: (value: OptionValue[]) => void;
+};
+export type ChipGroupProps = ChipGroupSingleProps | ChipGroupMultipleProps;
+export type ChipGroupContextValue = {
+    /** Set of toKey'd values for efficient lookup */
+    selectedValues: Set<string>;
+    multiple: boolean;
+    disabled: boolean;
+    onSelect: (value: OptionValue) => void;
+};
+export {};

package/components/ChipGroup/types.js

@@ -0,0 +1 @@
+export {};

package/components/Chips/Chips.d.ts

@@ -4,6 +4,8 @@ type Size = SizeCompact;
 type Theme = ThemeFull;
 type Variant = 'default' | 'outline' | 'ghost' | 'solid' | 'flush';
 export type ChipOption = {
+    /** Stable identifier used as React key. Falls back to href, then label string. */
+    id?: string;
     label: React.ReactNode;
     as?: 'a' | 'span' | 'div';
     href?: string;

package/components/Chips/Chips.js

@@ -17,5 +17,5 @@ export function Chips({ name, options, density = 'sm', direction = 'inline', ali
         alignItems: !isInline && alignment ? alignment : undefined,
         marginBlockEnd: 'var(--tui-spacing-sm)',
     };
-    return (_jsx("div", { role: role, className: className, "data-chips-name": name, style: style, children: options.map((o) => (_jsx(Chip, { as: o.as ?? (o.href ? 'a' : 'span'), href: o.href, target: o.target, rel: o.rel, size: o.size, theme: o.theme, variant: o.variant, disabled: o.disabled, className: o.className, leftIcon: o.leftIcon, rightIcon: o.rightIcon, children: o.label }))) }));
+    return (_jsx("div", { role: role, className: className, "data-chips-name": name, style: style, children: options.map((o, index) => (_jsx(Chip, { as: o.as ?? (o.href ? 'a' : 'span'), href: o.href, target: o.target, rel: o.rel, size: o.size, theme: o.theme, variant: o.variant, disabled: o.disabled, className: o.className, leftIcon: o.leftIcon, rightIcon: o.rightIcon, children: o.label }, o.id ?? o.href ?? (typeof o.label === 'string' ? o.label : `chip-${index}`)))) }));
 }

package/components/Combobox/Combobox.d.ts

@@ -0,0 +1,33 @@
+import type { ComboboxProps, ComboboxContentProps, ComboboxOptionProps, ComboboxGroupProps, ComboboxLabelProps } from './types';
+declare function ComboboxRoot({ value: controlledValue, defaultValue, onValueChange, inputValue: controlledInputValue, onInputChange, open: controlledOpen, defaultOpen, onOpenChange, disabled, placeholder, size, openOnFocus, filterMode, onQueryChange, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, inputClassName, children, }: ComboboxProps): import("react/jsx-runtime").JSX.Element;
+declare namespace ComboboxRoot {
+    var displayName: string;
+}
+declare function ComboboxContentComponent({ className, children }: ComboboxContentProps): import("react/jsx-runtime").JSX.Element;
+declare namespace ComboboxContentComponent {
+    var displayName: string;
+}
+declare function ComboboxOptionComponent({ value: optionValue, disabled, textValue: explicitTextValue, className, children, }: ComboboxOptionProps): import("react/jsx-runtime").JSX.Element;
+declare namespace ComboboxOptionComponent {
+    var displayName: string;
+}
+declare function ComboboxGroupComponent({ className, children }: ComboboxGroupProps): import("react/jsx-runtime").JSX.Element;
+declare namespace ComboboxGroupComponent {
+    var displayName: string;
+}
+declare function ComboboxLabelComponent({ className, children }: ComboboxLabelProps): import("react/jsx-runtime").JSX.Element;
+declare namespace ComboboxLabelComponent {
+    var displayName: string;
+}
+type ComboboxCompound = typeof ComboboxRoot & {
+    Content: typeof ComboboxContentComponent;
+    Option: typeof ComboboxOptionComponent;
+    Group: typeof ComboboxGroupComponent;
+    Label: typeof ComboboxLabelComponent;
+};
+export declare const Combobox: ComboboxCompound;
+export declare const ComboboxContent: typeof ComboboxContentComponent;
+export declare const ComboboxOption: typeof ComboboxOptionComponent;
+export declare const ComboboxGroup: typeof ComboboxGroupComponent;
+export declare const ComboboxLabel: typeof ComboboxLabelComponent;
+export { useComboboxContext as useCombobox } from './ComboboxContext';