@tangible/ui 0.0.1

package/README.md

@@ -0,0 +1,100 @@
+# Tangible UI
+
+Design system for Tangible WordPress plugins. React components + CSS tokens + utility classes.
+
+**Live Storybook:** https://storybook-tangible-ui.pages.dev
+
+## Components
+
+- **Primitives:** Button, Chip, Icon, IconButton, Progress, Rating, Tooltip
+- **Layout:** Accordion, Card, Modal, Notice, DataTable
+- **Composites:** Chips (multi-select chip group), StepIndicator
+- **Form Inputs:** Text, textarea, select, checkbox, radio, toggle, file (CSS-only)
+
+## Getting Started
+
+### Install
+
+```bash
+npm install @tangible/ui
+```
+
+### Import styles
+
+```tsx
+// In your app entry point
+import '@tangible/ui/styles';
+```
+
+Or in SCSS:
+```scss
+@use '@tangible/ui/styles/scss';
+```
+
+### Wrap your app
+
+Components require the `.tui-interface` wrapper to access design tokens:
+
+```tsx
+function App() {
+  return (
+    <div className="tui-interface">
+      {/* Your UI here */}
+    </div>
+  );
+}
+```
+
+### Use components
+
+```tsx
+import { Button, Card, Tooltip, IconButton } from '@tangible/ui';
+
+function Example() {
+  return (
+    <Card>
+      <Card.Body>
+        <Button label="Click me" theme="primary" />
+
+        <IconButton icon="system/settings" label="Settings" showTooltip />
+
+        <Tooltip>
+          <Tooltip.Trigger asChild>
+            <Button label="Hover me" variant="outline" />
+          </Tooltip.Trigger>
+          <Tooltip.Content>Hello!</Tooltip.Content>
+        </Tooltip>
+      </Card.Body>
+    </Card>
+  );
+}
+```
+
+See the [Storybook](https://storybook-tangible-ui.pages.dev) for full component documentation and examples.
+
+## Development
+
+```bash
+npm install
+npm run storybook   # Dev server on port 6006
+```
+
+## Commands
+
+```bash
+npm run storybook      # Dev server
+npm run build:lib      # Build library (outputs to publish/)
+npm run lint           # ESLint
+npm run test           # Unit tests
+npm run test:storybook # Story tests (requires Playwright)
+```
+
+## Documentation
+
+- `CLAUDE.md` — Development guide (architecture, patterns, conventions)
+- `CONTEXT.md` — Project background and LMS requirements
+- `TIMELINE.md` — Development roadmap (Jan–Mar 2026)
+
+## Status
+
+Under active development for Course Viewer (LMS) and Quiz modules. Component APIs are stabilising but may change.

package/components/Accordion/Accordion.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import type { AccordionProps, AccordionItemProps, AccordionTriggerProps, AccordionPanelProps } from './types';
+type AccordionCompound = {
+    (props: AccordionProps): React.JSX.Element;
+    Item: typeof AccordionItem;
+    Trigger: typeof AccordionTrigger;
+    Panel: typeof AccordionPanel;
+};
+declare function AccordionItem({ value, disabled, headingLevel, children, className, }: AccordionItemProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AccordionItem {
+    var displayName: string;
+}
+declare function AccordionTrigger({ children, className }: AccordionTriggerProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AccordionTrigger {
+    var displayName: string;
+}
+declare function AccordionPanel({ children, className }: AccordionPanelProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AccordionPanel {
+    var displayName: string;
+}
+export declare const Accordion: AccordionCompound;
+export {};

package/components/Accordion/Accordion.js

@@ -0,0 +1,192 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useCallback, useId, useMemo, useRef, useState } from 'react';
+import { cx } from '../../utils/cx.js';
+import { Icon } from '../Icon/index.js';
+import { AccordionContext, AccordionItemContext, useAccordionContext, useAccordionItemContext } from './AccordionContext.js';
+function AccordionRoot(props) {
+    const { type, children, className } = props;
+    // Track trigger refs for keyboard navigation
+    const triggersRef = useRef(new Map());
+    const registerTrigger = useCallback((value, element) => {
+        if (element) {
+            triggersRef.current.set(value, element);
+        }
+        else {
+            triggersRef.current.delete(value);
+        }
+    }, []);
+    const getTriggers = useCallback(() => triggersRef.current, []);
+    // State management differs by type
+    if (type === 'single') {
+        return (_jsx(AccordionSingle, { ...props, registerTrigger: registerTrigger, getTriggers: getTriggers, className: className, children: children }));
+    }
+    return (_jsx(AccordionMultiple, { ...props, registerTrigger: registerTrigger, getTriggers: getTriggers, className: className, children: children }));
+}
+function AccordionSingle({ value: controlledValue, defaultValue, onValueChange, collapsible = false, children, className, registerTrigger, getTriggers, }) {
+    const [internalValue, setInternalValue] = useState(defaultValue);
+    const isControlled = controlledValue !== undefined;
+    const currentValue = isControlled ? controlledValue : internalValue;
+    const isOpen = useCallback((itemValue) => currentValue === itemValue, [currentValue]);
+    const toggle = useCallback((itemValue) => {
+        let newValue;
+        if (currentValue === itemValue) {
+            // Closing current item
+            newValue = collapsible ? undefined : itemValue;
+        }
+        else {
+            // Opening new item
+            newValue = itemValue;
+        }
+        if (!isControlled) {
+            setInternalValue(newValue);
+        }
+        onValueChange?.(newValue);
+    }, [currentValue, collapsible, isControlled, onValueChange]);
+    const contextValue = useMemo(() => ({
+        type: 'single',
+        collapsible,
+        isOpen,
+        toggle,
+        registerTrigger,
+        getTriggers,
+    }), [collapsible, isOpen, toggle, registerTrigger, getTriggers]);
+    return (_jsx(AccordionContext.Provider, { value: contextValue, children: _jsx("div", { className: cx('tui-accordion', className), "data-type": "single", children: children }) }));
+}
+function AccordionMultiple({ value: controlledValue, defaultValue, onValueChange, children, className, registerTrigger, getTriggers, }) {
+    const [internalValue, setInternalValue] = useState(defaultValue ?? []);
+    const isControlled = controlledValue !== undefined;
+    const currentValue = isControlled ? controlledValue : internalValue;
+    const isOpen = useCallback((itemValue) => currentValue.includes(itemValue), [currentValue]);
+    const toggle = useCallback((itemValue) => {
+        const newValue = currentValue.includes(itemValue)
+            ? currentValue.filter((v) => v !== itemValue)
+            : [...currentValue, itemValue];
+        if (!isControlled) {
+            setInternalValue(newValue);
+        }
+        onValueChange?.(newValue);
+    }, [currentValue, isControlled, onValueChange]);
+    const contextValue = useMemo(() => ({
+        type: 'multiple',
+        collapsible: true, // Multiple is always collapsible
+        isOpen,
+        toggle,
+        registerTrigger,
+        getTriggers,
+    }), [isOpen, toggle, registerTrigger, getTriggers]);
+    return (_jsx(AccordionContext.Provider, { value: contextValue, children: _jsx("div", { className: cx('tui-accordion', className), "data-type": "multiple", children: children }) }));
+}
+// =============================================================================
+// Accordion Item
+// =============================================================================
+function AccordionItem({ value, disabled = false, headingLevel, children, className, }) {
+    const baseId = useId();
+    const triggerId = `${baseId}-trigger`;
+    const panelId = `${baseId}-panel`;
+    const { isOpen } = useAccordionContext();
+    const open = isOpen(value);
+    const itemContext = useMemo(() => ({
+        value,
+        disabled,
+        headingLevel,
+        triggerId,
+        panelId,
+        isOpen: open,
+    }), [value, disabled, headingLevel, triggerId, panelId, open]);
+    const state = open ? 'open' : 'closed';
+    return (_jsx(AccordionItemContext.Provider, { value: itemContext, children: _jsx("div", { className: cx('tui-accordion__item', className), "data-state": state, "data-disabled": disabled || undefined, children: children }) }));
+}
+// =============================================================================
+// Accordion Trigger
+// =============================================================================
+function AccordionTrigger({ children, className }) {
+    const { toggle, registerTrigger, getTriggers } = useAccordionContext();
+    const { value, disabled, headingLevel, triggerId, panelId, isOpen } = useAccordionItemContext();
+    const buttonRef = useRef(null);
+    // Register trigger for keyboard navigation
+    React.useEffect(() => {
+        registerTrigger(value, buttonRef.current);
+        return () => registerTrigger(value, null);
+    }, [value, registerTrigger]);
+    const handleClick = () => {
+        if (!disabled) {
+            toggle(value);
+        }
+    };
+    const handleKeyDown = (event) => {
+        const triggers = getTriggers();
+        // Sort triggers by DOM order (not Map insertion order) to handle
+        // conditional rendering, async mounting, or reordered items
+        const sortedTriggers = Array.from(triggers.entries()).sort(([, a], [, b]) => {
+            if (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING) {
+                return -1;
+            }
+            return 1;
+        });
+        const currentIndex = sortedTriggers.findIndex(([v]) => v === value);
+        // Find next/prev non-disabled trigger
+        const findNextIndex = (start, direction) => {
+            let index = start;
+            const len = sortedTriggers.length;
+            for (let i = 0; i < len; i++) {
+                index = (index + direction + len) % len;
+                const [, triggerElement] = sortedTriggers[index];
+                if (triggerElement && !triggerElement.disabled) {
+                    return index;
+                }
+            }
+            return start; // No non-disabled trigger found
+        };
+        let targetIndex = null;
+        switch (event.key) {
+            case 'ArrowDown':
+                event.preventDefault();
+                targetIndex = findNextIndex(currentIndex, 1);
+                break;
+            case 'ArrowUp':
+                event.preventDefault();
+                targetIndex = findNextIndex(currentIndex, -1);
+                break;
+            case 'Home':
+                event.preventDefault();
+                targetIndex = findNextIndex(sortedTriggers.length - 1, 1); // Start from end, go forward
+                break;
+            case 'End':
+                event.preventDefault();
+                targetIndex = findNextIndex(0, -1); // Start from beginning, go backward
+                break;
+        }
+        if (targetIndex !== null && targetIndex !== currentIndex) {
+            const [, targetElement] = sortedTriggers[targetIndex];
+            targetElement?.focus();
+        }
+    };
+    const state = isOpen ? 'open' : 'closed';
+    const button = (_jsxs("button", { ref: buttonRef, type: "button", id: triggerId, className: cx('tui-accordion__trigger', className), "aria-expanded": isOpen, "aria-controls": panelId, disabled: disabled, "data-state": state, "data-disabled": disabled || undefined, onClick: handleClick, onKeyDown: handleKeyDown, children: [_jsx("span", { className: "tui-accordion__trigger-content", children: children }), _jsx(Icon, { name: "system/chevron-down", size: "sm", className: "tui-accordion__indicator", "aria-hidden": "true" })] }));
+    // Wrap in heading if headingLevel is specified
+    if (headingLevel) {
+        const Heading = `h${headingLevel}`;
+        return _jsx(Heading, { className: "tui-accordion__heading", children: button });
+    }
+    return button;
+}
+// =============================================================================
+// Accordion Panel
+// =============================================================================
+function AccordionPanel({ children, className }) {
+    const { triggerId, panelId, isOpen } = useAccordionItemContext();
+    const state = isOpen ? 'open' : 'closed';
+    return (_jsx("div", { id: panelId, role: "region", "aria-labelledby": triggerId, className: cx('tui-accordion__panel', className), "data-state": state, "aria-hidden": !isOpen, 
+        // Prevent keyboard focus into collapsed panels
+        inert: !isOpen || undefined, children: _jsx("div", { className: "tui-accordion__panel-content", children: children }) }));
+}
+// =============================================================================
+// Export Compound Component
+// =============================================================================
+AccordionItem.displayName = 'Accordion.Item';
+AccordionTrigger.displayName = 'Accordion.Trigger';
+AccordionPanel.displayName = 'Accordion.Panel';
+export const Accordion = AccordionRoot;
+Accordion.Item = AccordionItem;
+Accordion.Trigger = AccordionTrigger;
+Accordion.Panel = AccordionPanel;

package/components/Accordion/AccordionContext.d.ts

@@ -0,0 +1,5 @@
+import type { AccordionContextValue, AccordionItemContextValue } from './types';
+export declare const AccordionContext: import("react").Context<AccordionContextValue | null>;
+export declare function useAccordionContext(): AccordionContextValue;
+export declare const AccordionItemContext: import("react").Context<AccordionItemContextValue | null>;
+export declare function useAccordionItemContext(): AccordionItemContextValue;

package/components/Accordion/AccordionContext.js

@@ -0,0 +1,23 @@
+import { createContext, useContext } from 'react';
+// =============================================================================
+// Accordion Root Context
+// =============================================================================
+export const AccordionContext = createContext(null);
+export function useAccordionContext() {
+    const context = useContext(AccordionContext);
+    if (!context) {
+        throw new Error('Accordion compound components must be used within an Accordion');
+    }
+    return context;
+}
+// =============================================================================
+// Accordion Item Context
+// =============================================================================
+export const AccordionItemContext = createContext(null);
+export function useAccordionItemContext() {
+    const context = useContext(AccordionItemContext);
+    if (!context) {
+        throw new Error('Accordion.Trigger and Accordion.Panel must be used within an Accordion.Item');
+    }
+    return context;
+}

package/components/Accordion/index.d.ts

@@ -0,0 +1,2 @@
+export { Accordion } from './Accordion';
+export type { AccordionProps, AccordionSingleProps, AccordionMultipleProps, AccordionItemProps, AccordionTriggerProps, AccordionPanelProps, } from './types';

package/components/Accordion/index.js

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

package/components/Accordion/types.d.ts

@@ -0,0 +1,61 @@
+import type { ReactNode } from 'react';
+type AccordionBaseProps = {
+    children: ReactNode;
+    className?: string;
+};
+export type AccordionSingleProps = AccordionBaseProps & {
+    type: 'single';
+    /** Controlled: currently open item value */
+    value?: string;
+    /** Uncontrolled: initially open item */
+    defaultValue?: string;
+    /** Callback when open item changes (undefined when all closed in collapsible mode) */
+    onValueChange?: (value: string | undefined) => void;
+    /** Allow closing all items (otherwise one stays open) */
+    collapsible?: boolean;
+};
+export type AccordionMultipleProps = AccordionBaseProps & {
+    type: 'multiple';
+    /** Controlled: currently open item values */
+    value?: string[];
+    /** Uncontrolled: initially open items */
+    defaultValue?: string[];
+    /** Callback when open items change */
+    onValueChange?: (value: string[]) => void;
+};
+export type AccordionProps = AccordionSingleProps | AccordionMultipleProps;
+export type AccordionItemProps = {
+    /** Unique identifier for this item (required) */
+    value: string;
+    /** Prevent interaction */
+    disabled?: boolean;
+    /** Wrap trigger in heading element */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
+    children: ReactNode;
+    className?: string;
+};
+export type AccordionTriggerProps = {
+    children: ReactNode;
+    className?: string;
+};
+export type AccordionPanelProps = {
+    children: ReactNode;
+    className?: string;
+};
+export type AccordionContextValue = {
+    type: 'single' | 'multiple';
+    collapsible: boolean;
+    isOpen: (value: string) => boolean;
+    toggle: (value: string) => void;
+    registerTrigger: (value: string, element: HTMLButtonElement | null) => void;
+    getTriggers: () => Map<string, HTMLButtonElement>;
+};
+export type AccordionItemContextValue = {
+    value: string;
+    disabled: boolean;
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
+    triggerId: string;
+    panelId: string;
+    isOpen: boolean;
+};
+export {};

package/components/Accordion/types.js

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

package/components/Avatar/Avatar.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import type { AvatarProps } from './types';
+/**
+ * Avatar displays a user's profile image, initials, or a placeholder icon.
+ *
+ * - Loads image from `src` prop
+ * - Falls back to initials from `name` if image fails or isn't provided
+ * - Shows placeholder icon if neither `src` nor `name` provided
+ * - Colors for initials are derived from the name hash for consistency
+ */
+export declare const Avatar: React.ForwardRefExoticComponent<AvatarProps & React.RefAttributes<HTMLSpanElement>>;

package/components/Avatar/Avatar.js

@@ -0,0 +1,67 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useState, useMemo } from 'react';
+import { cx } from '../../utils/cx.js';
+import { Icon } from '../Icon/index.js';
+import { AVATAR_COLORS } from './types.js';
+/**
+ * Generate initials from a name.
+ * "Mary Ghen" → "MG", "Bob" → "B", "Jean-Luc Picard" → "JP"
+ */
+function getInitials(name) {
+    const parts = name.trim().split(/[\s-]+/).filter(Boolean);
+    if (parts.length === 0)
+        return '';
+    if (parts.length === 1)
+        return parts[0].charAt(0).toUpperCase();
+    return (parts[0].charAt(0) + parts[parts.length - 1].charAt(0)).toUpperCase();
+}
+/**
+ * Simple hash function for consistent color assignment.
+ * Same name always gets the same color.
+ */
+function hashString(str) {
+    if (!str)
+        return 0;
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash & hash; // Convert to 32-bit integer
+    }
+    return Math.abs(hash);
+}
+/**
+ * Get a consistent color for a name.
+ */
+function getColorFromName(name, colors) {
+    const hash = hashString(name.toLowerCase());
+    return colors[hash % colors.length];
+}
+/**
+ * Avatar displays a user's profile image, initials, or a placeholder icon.
+ *
+ * - Loads image from `src` prop
+ * - Falls back to initials from `name` if image fails or isn't provided
+ * - Shows placeholder icon if neither `src` nor `name` provided
+ * - Colors for initials are derived from the name hash for consistency
+ */
+export const Avatar = React.forwardRef(({ src, name, size = 'md', shape = 'circle', color, indicator, indicatorLabel, indicatorPosition = 'bottom-right', className, }, ref) => {
+    const [imgError, setImgError] = useState(false);
+    // Reset error state when src changes
+    React.useEffect(() => {
+        setImgError(false);
+    }, [src]);
+    const initials = useMemo(() => (name ? getInitials(name) : ''), [name]);
+    const derivedColor = useMemo(() => color ?? (name ? getColorFromName(name, AVATAR_COLORS) : 'slate'), [color, name]);
+    const showImage = src && !imgError;
+    const showInitials = !showImage && initials;
+    const showPlaceholder = !showImage && !initials;
+    // Placeholder avatars are decorative (no meaningful identity)
+    const isDecorative = showPlaceholder;
+    return (_jsxs("span", { ref: ref, className: cx('tui-avatar', `is-size-${size}`, `is-shape-${shape}`, !showImage && `is-color-${derivedColor}`, className), ...(isDecorative
+            ? { 'aria-hidden': true }
+            : { role: 'img', 'aria-label': name }), children: [_jsxs("span", { className: "tui-avatar__content", children: [showImage && (_jsx("img", { src: src, alt: "", className: "tui-avatar__image", onError: () => setImgError(true) })), showInitials && (_jsx("span", { className: "tui-avatar__initials", "aria-hidden": "true", children: initials })), showPlaceholder && (_jsx(Icon, { name: "system/user-circle-outline", className: "tui-avatar__placeholder" }))] }), indicator && (_jsx("span", { className: cx('tui-avatar__indicator', `is-position-${indicatorPosition}`), ...(indicatorLabel
+                    ? { role: 'img', 'aria-label': indicatorLabel }
+                    : { 'aria-hidden': true }), children: indicator }))] }));
+});
+Avatar.displayName = 'Avatar';

package/components/Avatar/AvatarGroup.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import type { AvatarGroupProps } from './types';
+/**
+ * AvatarGroup displays multiple avatars with optional overlap.
+ *
+ * - Shows up to `max` avatars, with "+N" overflow indicator
+ * - Overlap mode (default) uses OverlapStack with avatar-styled overflow
+ * - Non-overlap mode uses flex with gap
+ * - Override overlap amount via `--tui-avatar-group-overlap` CSS property
+ */
+export declare const AvatarGroup: React.ForwardRefExoticComponent<AvatarGroupProps & React.RefAttributes<HTMLDivElement>>;

package/components/Avatar/AvatarGroup.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { Children, isValidElement, cloneElement } from 'react';
+import { cx } from '../../utils/cx.js';
+import { OverlapStack } from '../OverlapStack/index.js';
+/**
+ * AvatarGroup displays multiple avatars with optional overlap.
+ *
+ * - Shows up to `max` avatars, with "+N" overflow indicator
+ * - Overlap mode (default) uses OverlapStack with avatar-styled overflow
+ * - Non-overlap mode uses flex with gap
+ * - Override overlap amount via `--tui-avatar-group-overlap` CSS property
+ */
+export const AvatarGroup = React.forwardRef(({ max, size, shape, overlap = true, children, className }, ref) => {
+    const childArray = Children.toArray(children).filter(isValidElement);
+    const total = childArray.length;
+    // Clone children to inject size/shape props if provided at group level
+    const clonedChildren = childArray.map((child) => {
+        if (isValidElement(child)) {
+            return cloneElement(child, {
+                size: size ?? child.props.size,
+                shape: shape ?? child.props.shape,
+            });
+        }
+        return child;
+    });
+    // Descriptive label for the group
+    const hasOverflow = max !== undefined && total > max;
+    const visibleCount = hasOverflow ? max : total;
+    const groupLabel = hasOverflow
+        ? `${total} users, showing ${visibleCount}`
+        : `${total} users`;
+    // Non-overlap mode: simple flex layout
+    if (!overlap) {
+        return (_jsx("div", { ref: ref, className: cx('tui-avatar-group', className), role: "group", "aria-label": groupLabel, children: clonedChildren }));
+    }
+    // Overlap mode: delegate to OverlapStack
+    // Note: We don't use OverlapStack's `frame` prop because its border-radius
+    // wouldn't match each avatar's shape. Instead, we apply ring styles via CSS
+    // directly to avatars inside .is-overlap groups.
+    return (_jsx(OverlapStack, { ref: ref, className: cx('tui-avatar-group', 'is-overlap', className), max: max, renderOverflow: (count) => (_jsx(AvatarOverflow, { count: count, size: size, shape: shape })), overflowLabel: (count) => `${count} more users`, "aria-label": groupLabel, children: clonedChildren }));
+});
+AvatarGroup.displayName = 'AvatarGroup';
+function AvatarOverflow({ count, size, shape }) {
+    return (_jsx("span", { className: cx('tui-avatar', 'tui-avatar--overflow', size && `is-size-${size}`, shape && `is-shape-${shape}`), role: "img", "aria-hidden": "true", children: _jsx("span", { className: "tui-avatar__content", children: _jsxs("span", { className: "tui-avatar__initials", children: ["+", count] }) }) }));
+}

package/components/Avatar/index.d.ts

@@ -0,0 +1,9 @@
+import { Avatar as AvatarBase } from './Avatar';
+import { AvatarGroup } from './AvatarGroup';
+export type { AvatarProps, AvatarGroupProps, AvatarSize, AvatarShape, AvatarColor, IndicatorPosition, } from './types';
+export { AVATAR_COLORS } from './types';
+type AvatarCompound = typeof AvatarBase & {
+    Group: typeof AvatarGroup;
+};
+export declare const Avatar: AvatarCompound;
+export { AvatarGroup };

package/components/Avatar/index.js

@@ -0,0 +1,7 @@
+import { Avatar as AvatarBase } from './Avatar.js';
+import { AvatarGroup } from './AvatarGroup.js';
+export { AVATAR_COLORS } from './types.js';
+export const Avatar = AvatarBase;
+Avatar.Group = AvatarGroup;
+// Named export for direct import
+export { AvatarGroup };

package/components/Avatar/types.d.ts

@@ -0,0 +1,44 @@
+import type { SizeExtended } from '../../types';
+export type AvatarSize = SizeExtended;
+export type AvatarShape = 'circle' | 'square';
+export type IndicatorPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+/**
+ * Avatar palette colors for initials backgrounds.
+ * These are not tied to semantic themes - they provide visual variety.
+ */
+export type AvatarColor = 'coral' | 'amber' | 'lime' | 'teal' | 'cyan' | 'blue' | 'violet' | 'pink' | 'slate' | 'emerald';
+export declare const AVATAR_COLORS: AvatarColor[];
+export type AvatarProps = {
+    /** Image source URL */
+    src?: string;
+    /** User's name - used for alt text and generating initials fallback */
+    name?: string;
+    /** Size of the avatar */
+    size?: AvatarSize;
+    /** Shape of the avatar */
+    shape?: AvatarShape;
+    /** Explicit color for initials background (otherwise derived from name) */
+    color?: AvatarColor;
+    /** Status indicator element (icon, badge, etc.) */
+    indicator?: React.ReactNode;
+    /** Accessible label for the indicator (e.g., "Online", "Verified", "3 notifications") */
+    indicatorLabel?: string;
+    /** Position of the indicator */
+    indicatorPosition?: IndicatorPosition;
+    /** Additional CSS class */
+    className?: string;
+};
+export type AvatarGroupProps = {
+    /** Maximum avatars to show before "+N" overflow */
+    max?: number;
+    /** Size for all avatars in the group */
+    size?: AvatarSize;
+    /** Shape for all avatars in the group */
+    shape?: AvatarShape;
+    /** Whether avatars overlap (default: true) */
+    overlap?: boolean;
+    /** Children (Avatar components) */
+    children: React.ReactNode;
+    /** Additional CSS class */
+    className?: string;
+};

package/components/Avatar/types.js

@@ -0,0 +1,12 @@
+export const AVATAR_COLORS = [
+    'coral',
+    'amber',
+    'lime',
+    'teal',
+    'cyan',
+    'blue',
+    'violet',
+    'pink',
+    'slate',
+    'emerald',
+];

package/components/Button/Button.d.ts

@@ -0,0 +1,4 @@
+import React from 'react';
+import type { ButtonProps } from './types';
+export type { ButtonProps } from './types';
+export declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;