@flikk/ui 1.0.0-beta.1

package/dist/components/core/Tabs/TabsContext.d.ts

@@ -0,0 +1,10 @@
+import React from "react";
+import { TabsContextValue } from "./Tabs.types";
+/**
+ * Context for sharing state between Tabs container and child components
+ */
+export declare const TabsContext: React.Context<TabsContextValue | null>;
+/**
+ * Hook to consume TabsContext
+ */
+export declare const useTabsContext: () => TabsContextValue;

package/dist/components/core/Tabs/TabsContext.js

@@ -0,0 +1,18 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * Context for sharing state between Tabs container and child components
+ */
+const TabsContext = createContext(null);
+/**
+ * Hook to consume TabsContext
+ */
+const useTabsContext = () => {
+    const context = useContext(TabsContext);
+    if (!context) {
+        throw new Error("Tabs components must be used within a Tabs component");
+    }
+    return context;
+};
+
+export { TabsContext, useTabsContext };

package/dist/components/core/Tabs/TabsList.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+import { TabsListProps } from "./Tabs.types";
+/**
+ * TabsList component displays the tab headers container with sliding underline
+ */
+export declare const TabsList: React.ForwardRefExoticComponent<TabsListProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/core/Tabs/TabsList.js

@@ -0,0 +1,87 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import React__default, { useState, useRef, useMemo, useEffect } from 'react';
+import { useReducedMotion, motion } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+import { tabsTheme } from './Tabs.theme.js';
+import { useTabsContext } from './TabsContext.js';
+import { getUnderlineTransition } from './Tabs.animations.js';
+
+/**
+ * TabsList component displays the tab headers container with sliding underline
+ */
+const TabsList = React__default.forwardRef(({ children, className, ...props }, ref) => {
+    const { value: activeValue, orientation, size } = useTabsContext();
+    const shouldReduceMotion = useReducedMotion();
+    // State for underline position and visibility
+    const [underlinePosition, setUnderlinePosition] = useState(null);
+    const [showUnderline, setShowUnderline] = useState(false);
+    // Ref to access the list element for calculations
+    const listRef = useRef(null);
+    // Calculate underline position based on active tab
+    const updateUnderlinePosition = useMemo(() => {
+        return () => {
+            if (!activeValue || !listRef.current) {
+                setShowUnderline(false);
+                return;
+            }
+            // Find the active trigger element
+            const activeTrigger = listRef.current.querySelector(`[data-value="${activeValue}"]`);
+            if (!activeTrigger) {
+                setShowUnderline(false);
+                return;
+            }
+            // Get the position relative to the list container
+            const listRect = listRef.current.getBoundingClientRect();
+            const triggerRect = activeTrigger.getBoundingClientRect();
+            const left = triggerRect.left - listRect.left;
+            const width = triggerRect.width;
+            setUnderlinePosition({ left, width });
+            setShowUnderline(true);
+        };
+    }, [activeValue]);
+    // Update underline position when active value changes or on mount
+    useEffect(() => {
+        // Small delay to ensure DOM is updated
+        const timeoutId = setTimeout(updateUnderlinePosition, 0);
+        return () => clearTimeout(timeoutId);
+    }, [updateUnderlinePosition]);
+    // Handle window resize to recalculate positions
+    useEffect(() => {
+        const handleResize = () => {
+            updateUnderlinePosition();
+        };
+        window.addEventListener('resize', handleResize);
+        return () => window.removeEventListener('resize', handleResize);
+    }, [updateUnderlinePosition]);
+    // Animation configuration for underline
+    const underlineAnimation = useMemo(() => {
+        return {
+            initial: false,
+            animate: underlinePosition ? {
+                x: underlinePosition.left,
+                width: underlinePosition.width,
+            } : {
+                x: 0,
+                width: 0,
+            },
+            transition: getUnderlineTransition(shouldReduceMotion),
+        };
+    }, [underlinePosition, shouldReduceMotion]);
+    return (jsxs("div", { ref: (node) => {
+            listRef.current = node;
+            if (typeof ref === 'function') {
+                ref(node);
+            }
+            else if (ref) {
+                ref.current = node;
+            }
+        }, role: "tablist", "aria-orientation": orientation, className: cn(tabsTheme.listStyle, className), "data-orientation": orientation, "data-size": size, ...props, children: [children, showUnderline && underlinePosition && (jsx(motion.div, { className: cn(tabsTheme.underlineStyle, "pointer-events-none" // Prevent interference with tab interactions
+                ), style: {
+                    position: 'absolute',
+                    bottom: 0,
+                }, ...underlineAnimation, "aria-hidden": "true" // Decorative element
+             }))] }));
+});
+TabsList.displayName = "TabsList";
+
+export { TabsList };

package/dist/components/core/Tabs/TabsTrigger.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+import { TabsTriggerProps } from "./Tabs.types";
+/**
+ * TabsTrigger component displays individual tab headers with optional animations
+ */
+export declare const TabsTrigger: React.ForwardRefExoticComponent<TabsTriggerProps & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/core/Tabs/TabsTrigger.js

@@ -0,0 +1,141 @@
+import { jsx } from 'react/jsx-runtime';
+import React__default, { useMemo, useCallback, useEffect } from 'react';
+import { useReducedMotion, motion } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+import { tabsTheme } from './Tabs.theme.js';
+import { useTabsContext } from './TabsContext.js';
+import { getTabsTriggerVariants } from './Tabs.animations.js';
+
+/**
+ * TabsTrigger component displays individual tab headers with optional animations
+ */
+const TabsTrigger = React__default.forwardRef(({ value, disabled = false, children, className, onClick, onKeyDown, ...props }, ref) => {
+    const { value: selectedValue, onValueChange, orientation, size, disabled: contextDisabled, registerTrigger, unregisterTrigger } = useTabsContext();
+    const shouldReduceMotion = useReducedMotion();
+    // Check if we're in Storybook and should disable animations
+    const isInStorybook = typeof window !== 'undefined' && window.__STORYBOOK_DISABLE_ANIMATIONS__;
+    const shouldDisableAnimations = !!shouldReduceMotion || isInStorybook;
+    // Memoize derived state flags for performance
+    const derivedState = useMemo(() => ({
+        isSelected: value === selectedValue,
+        isDisabled: disabled || contextDisabled,
+    }), [value, selectedValue, disabled, contextDisabled]);
+    const { isSelected, isDisabled } = derivedState;
+    // Compute animation variants without a global cache (HMR-safe)
+    const triggerVariants = useMemo(() => getTabsTriggerVariants(shouldDisableAnimations), [shouldDisableAnimations]);
+    // Dev-time a11y warning for icon-only triggers without aria-label
+    if (process.env.NODE_ENV !== 'production') {
+        if (typeof children === 'object' && React__default.isValidElement(children) && !props["aria-label"]) {
+            // If children is just an icon element, warn about missing aria-label
+            const childType = children.type;
+            if (typeof childType === 'function' && childType.name && childType.name.includes('Icon')) {
+                // eslint-disable-next-line no-console
+                console.warn("TabsTrigger with icon-only content should have 'aria-label' for accessibility.");
+            }
+        }
+    }
+    // Safe onClick handler with error handling
+    const handleClick = useCallback((event) => {
+        if (isDisabled)
+            return;
+        try {
+            onValueChange(value);
+            onClick === null || onClick === void 0 ? void 0 : onClick(event);
+        }
+        catch (error) {
+            if (process.env.NODE_ENV !== 'production') {
+                // eslint-disable-next-line no-console
+                console.error("Error in tab trigger click handler:", error);
+            }
+        }
+    }, [isDisabled, onValueChange, value, onClick]);
+    // Enhanced keyboard navigation handler with error handling
+    const handleKeyDown = useCallback((event) => {
+        var _a, _b;
+        // Handle keyboard navigation for tabs
+        if (!isDisabled) {
+            try {
+                switch (event.key) {
+                    case "ArrowLeft":
+                    case "ArrowUp":
+                        event.preventDefault();
+                        // Move to previous tab - focus previous trigger
+                        const prevTrigger = event.currentTarget.previousElementSibling;
+                        if (prevTrigger && prevTrigger.tagName === 'BUTTON' && !prevTrigger.disabled) {
+                            prevTrigger.focus();
+                            prevTrigger.click();
+                        }
+                        break;
+                    case "ArrowRight":
+                    case "ArrowDown":
+                        event.preventDefault();
+                        // Move to next tab - focus next trigger
+                        const nextTrigger = event.currentTarget.nextElementSibling;
+                        if (nextTrigger && nextTrigger.tagName === 'BUTTON' && !nextTrigger.disabled) {
+                            nextTrigger.focus();
+                            nextTrigger.click();
+                        }
+                        break;
+                    case "Home":
+                        event.preventDefault();
+                        // Move to first tab
+                        const firstTrigger = (_a = event.currentTarget.parentElement) === null || _a === void 0 ? void 0 : _a.firstElementChild;
+                        if (firstTrigger && firstTrigger.tagName === 'BUTTON' && !firstTrigger.disabled) {
+                            firstTrigger.focus();
+                            firstTrigger.click();
+                        }
+                        break;
+                    case "End":
+                        event.preventDefault();
+                        // Move to last tab
+                        const lastTrigger = (_b = event.currentTarget.parentElement) === null || _b === void 0 ? void 0 : _b.lastElementChild;
+                        if (lastTrigger && lastTrigger.tagName === 'BUTTON' && !lastTrigger.disabled) {
+                            lastTrigger.focus();
+                            lastTrigger.click();
+                        }
+                        break;
+                }
+            }
+            catch (error) {
+                if (process.env.NODE_ENV !== 'production') {
+                    // eslint-disable-next-line no-console
+                    console.error("Error in tab trigger keyboard handler:", error);
+                }
+            }
+        }
+        onKeyDown === null || onKeyDown === void 0 ? void 0 : onKeyDown(event);
+    }, [isDisabled, onKeyDown]);
+    // Memoize theme classes to prevent recalculation on every render
+    const themeClasses = useMemo(() => {
+        return {
+            triggerStyle: tabsTheme.triggerStyle,
+            sizeStyle: tabsTheme.triggerSizes[size],
+        };
+    }, [size]);
+    // Generate default aria-label for icon-only triggers if not provided (fallback only)
+    const ariaLabel = props["aria-label"] || undefined;
+    // Register/unregister this trigger for underline positioning
+    useEffect(() => {
+        // Register with a slight delay to ensure DOM is ready
+        const timeoutId = setTimeout(() => {
+            if (ref && typeof ref === 'object' && ref.current) {
+                registerTrigger(value, ref.current);
+            }
+        }, 0);
+        return () => {
+            clearTimeout(timeoutId);
+            unregisterTrigger(value);
+        };
+    }, [value, registerTrigger, unregisterTrigger, ref]);
+    // Determine animation props (user props will override due to spread order)
+    const animationProps = shouldDisableAnimations ? {} : {
+        whileHover: !isDisabled ? "hover" : undefined,
+        whileTap: !isDisabled ? "tap" : undefined,
+        variants: triggerVariants,
+    };
+    return (jsx(motion.button, { ref: ref, type: "button", role: "tab", "aria-selected": isSelected, "aria-controls": `${value}-content`, id: `${value}-tab`, tabIndex: isSelected ? 0 : -1, disabled: isDisabled, className: cn(themeClasses.triggerStyle, themeClasses.sizeStyle, className // User overrides take precedence
+        ), onClick: handleClick, onKeyDown: handleKeyDown, "data-value": value, "data-state": isSelected ? "active" : "inactive", "data-disabled": isDisabled, "data-orientation": orientation, "aria-disabled": isDisabled || undefined, "aria-label": ariaLabel, ...animationProps, ...props, children: children }));
+});
+TabsTrigger.displayName = "TabsTrigger";
+
+export { TabsTrigger };

package/dist/components/core/Tabs/index.d.ts

@@ -0,0 +1,6 @@
+export { Tabs } from './Tabs';
+export { TabsList } from './TabsList';
+export { TabsTrigger } from './TabsTrigger';
+export { TabsContent } from './TabsContent';
+export { TabsContext, useTabsContext } from './TabsContext';
+export type { TabsProps, TabsListProps, TabsTriggerProps, TabsContentProps, TabsSize, TabsOrientation, TabsContextValue } from './Tabs.types';

package/dist/components/core/Tag/Tag.animations.d.ts

@@ -0,0 +1,3 @@
+import type { Variants, Transition } from "motion/react";
+export declare const tagVariants: Variants;
+export declare const tagLayoutTransition: Transition;

package/dist/components/core/Tag/Tag.animations.js

@@ -0,0 +1,31 @@
+const tagVariants = {
+    initial: {
+        scale: 0,
+        opacity: 0,
+    },
+    animate: {
+        scale: 1,
+        opacity: 1,
+        transition: {
+            type: "spring",
+            stiffness: 500,
+            damping: 25,
+        },
+    },
+    exit: {
+        scale: 0,
+        opacity: 0,
+        transition: {
+            type: "spring",
+            stiffness: 500,
+            damping: 30,
+        },
+    },
+};
+const tagLayoutTransition = {
+    type: "spring",
+    stiffness: 500,
+    damping: 30,
+};
+
+export { tagLayoutTransition, tagVariants };

package/dist/components/core/Tag/Tag.d.ts

@@ -0,0 +1,14 @@
+import React from "react";
+import { TagProps } from "./Tag.types";
+/**
+ * Tag component for displaying removable labels or keywords.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Tag onRemove={() => handleRemove('tag1')}>JavaScript</Tag>
+ * <Tag size="sm" removable={false}>Read Only</Tag>
+ * <Tag disabled>Disabled Tag</Tag>
+ * ```
+ */
+export declare const Tag: React.ForwardRefExoticComponent<TagProps & React.RefAttributes<HTMLSpanElement>>;

package/dist/components/core/Tag/Tag.js

@@ -0,0 +1,44 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import React__default from 'react';
+import { motion } from 'motion/react';
+import { XMarkIcon } from '@heroicons/react/24/outline';
+import { cn } from '../../../utils/cn.js';
+import { tagTheme } from './Tag.theme.js';
+import { tagVariants, tagLayoutTransition } from './Tag.animations.js';
+
+/**
+ * Tag component for displaying removable labels or keywords.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Tag onRemove={() => handleRemove('tag1')}>JavaScript</Tag>
+ * <Tag size="sm" removable={false}>Read Only</Tag>
+ * <Tag disabled>Disabled Tag</Tag>
+ * ```
+ */
+const Tag = React__default.forwardRef(({ children, size = "md", removable = true, onRemove, disabled = false, className, theme: customTheme, ...props }, ref) => {
+    var _a, _b, _c;
+    // Merge default theme with custom theme overrides
+    const theme = {
+        baseStyle: (_a = customTheme === null || customTheme === void 0 ? void 0 : customTheme.baseStyle) !== null && _a !== void 0 ? _a : tagTheme.baseStyle,
+        sizes: { ...tagTheme.sizes, ...customTheme === null || customTheme === void 0 ? void 0 : customTheme.sizes },
+        disabledStyle: (_b = customTheme === null || customTheme === void 0 ? void 0 : customTheme.disabledStyle) !== null && _b !== void 0 ? _b : tagTheme.disabledStyle,
+        removeButtonStyle: (_c = customTheme === null || customTheme === void 0 ? void 0 : customTheme.removeButtonStyle) !== null && _c !== void 0 ? _c : tagTheme.removeButtonStyle,
+        removeIconSizes: {
+            ...tagTheme.removeIconSizes,
+            ...customTheme === null || customTheme === void 0 ? void 0 : customTheme.removeIconSizes,
+        },
+    };
+    const showRemoveButton = removable && onRemove && !disabled;
+    const handleRemove = (e) => {
+        e.stopPropagation();
+        if (!disabled && onRemove) {
+            onRemove();
+        }
+    };
+    return (jsxs(motion.span, { ref: ref, className: cn(theme.baseStyle, theme.sizes[size], showRemoveButton && "pr-0.5", disabled && theme.disabledStyle, className), layout: true, transition: tagLayoutTransition, variants: tagVariants, initial: "initial", animate: "animate", exit: "exit", "data-size": size, "data-disabled": disabled ? "true" : "false", "data-removable": removable ? "true" : "false", ...props, children: [children, showRemoveButton && (jsx("button", { type: "button", onClick: handleRemove, className: theme.removeButtonStyle, "aria-label": `Remove ${typeof children === "string" ? children : "tag"}`, children: jsx(XMarkIcon, { className: theme.removeIconSizes[size] }) }))] }));
+});
+Tag.displayName = "Tag";
+
+export { Tag };

package/dist/components/core/Tag/Tag.theme.d.ts

@@ -0,0 +1,2 @@
+import { TagTheme } from "./Tag.types";
+export declare const tagTheme: TagTheme;

package/dist/components/core/Tag/Tag.theme.js

@@ -0,0 +1,21 @@
+const tagTheme = {
+    baseStyle: "inline-flex items-center gap-0.5 font-medium rounded-full " +
+        "bg-white dark:bg-[var(--color-background-secondary)] border border-[var(--color-border)] " +
+        "text-[var(--color-text-primary)]",
+    sizes: {
+        sm: "text-xs px-2.5 py-0.5",
+        md: "text-sm px-2.5 py-0.5",
+    },
+    disabledStyle: "opacity-50 cursor-not-allowed",
+    removeButtonStyle: "inline-flex items-center justify-center rounded-full p-1 " +
+        "hover:bg-[var(--color-background-quaternary)] " +
+        "text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] " +
+        "transition-all duration-300 cursor-pointer focus:outline-none " +
+        "focus-visible:ring-2 focus-visible:ring-[var(--color-primary)]",
+    removeIconSizes: {
+        sm: "size-3",
+        md: "size-3.5",
+    },
+};
+
+export { tagTheme };

package/dist/components/core/Tag/Tag.types.d.ts

@@ -0,0 +1,40 @@
+import React from "react";
+/**
+ * Tag component props
+ */
+export interface TagProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "onRemove" | "onDrag" | "onDragEnd" | "onDragStart" | "onAnimationStart"> {
+    /** The content of the tag */
+    children: React.ReactNode;
+    /** The size of the tag */
+    size?: TagSize;
+    /** Whether to show the remove button (default: true) */
+    removable?: boolean;
+    /** Callback when the remove button is clicked */
+    onRemove?: () => void;
+    /** Whether the tag is disabled */
+    disabled?: boolean;
+    /** Additional class name for the tag */
+    className?: string;
+    /** Theme overrides */
+    theme?: TagThemeOverrides;
+}
+export type TagSize = "sm" | "md";
+export interface TagTheme {
+    /** Base styles for the tag container */
+    baseStyle: string;
+    /** Size-specific styles */
+    sizes: Record<TagSize, string>;
+    /** Disabled state style */
+    disabledStyle: string;
+    /** Remove button style */
+    removeButtonStyle: string;
+    /** Remove icon sizes for each tag size */
+    removeIconSizes: Record<TagSize, string>;
+}
+export interface TagThemeOverrides {
+    baseStyle?: string;
+    sizes?: Partial<Record<TagSize, string>>;
+    disabledStyle?: string;
+    removeButtonStyle?: string;
+    removeIconSizes?: Partial<Record<TagSize, string>>;
+}

package/dist/components/core/Tag/index.d.ts

@@ -0,0 +1,3 @@
+export { Tag } from "./Tag";
+export type { TagProps, TagSize, TagTheme, TagThemeOverrides } from "./Tag.types";
+export { tagTheme } from "./Tag.theme";

package/dist/components/core/Timeline/Timeline.animations.d.ts

@@ -0,0 +1,23 @@
+import { Variants } from "motion/react";
+/**
+ * Timeline item entry animation variants
+ * Provides a fade + slide effect when items enter the viewport
+ */
+export declare const timelineItemVariants: Variants;
+/**
+ * Get directional slide variants based on alignment side
+ * Items slide in from the opposite direction of their placement
+ *
+ * @param side - 'left' slides from left, 'right' slides from right
+ */
+export declare const getDirectionalVariants: (side: "left" | "right") => Variants;
+/**
+ * Horizontal layout item entry animation
+ * Items fade in from below
+ */
+export declare const timelineHorizontalItemVariants: Variants;
+/**
+ * Marker scale-in animation
+ * Markers pop in with a slight scale effect
+ */
+export declare const timelineMarkerVariants: Variants;

package/dist/components/core/Timeline/Timeline.animations.js

@@ -0,0 +1,92 @@
+/**
+ * Timeline item entry animation variants
+ * Provides a fade + slide effect when items enter the viewport
+ */
+const timelineItemVariants = {
+    hidden: {
+        opacity: 0,
+        y: 20,
+        transition: {
+            duration: 0.3,
+            ease: "easeOut",
+        },
+    },
+    visible: {
+        opacity: 1,
+        y: 0,
+        transition: {
+            duration: 0.5,
+            ease: [0.04, 0.62, 0.23, 0.98],
+        },
+    },
+};
+/**
+ * Get directional slide variants based on alignment side
+ * Items slide in from the opposite direction of their placement
+ *
+ * @param side - 'left' slides from left, 'right' slides from right
+ */
+const getDirectionalVariants = (side) => ({
+    hidden: {
+        opacity: 0,
+        x: side === "left" ? -30 : 30,
+        y: 10,
+        transition: {
+            duration: 0.3,
+            ease: "easeOut",
+        },
+    },
+    visible: {
+        opacity: 1,
+        x: 0,
+        y: 0,
+        transition: {
+            duration: 0.5,
+            ease: [0.04, 0.62, 0.23, 0.98],
+        },
+    },
+});
+/**
+ * Horizontal layout item entry animation
+ * Items fade in from below
+ */
+const timelineHorizontalItemVariants = {
+    hidden: {
+        opacity: 0,
+        y: 15,
+        transition: {
+            duration: 0.3,
+            ease: "easeOut",
+        },
+    },
+    visible: {
+        opacity: 1,
+        y: 0,
+        transition: {
+            duration: 0.4,
+            ease: [0.04, 0.62, 0.23, 0.98],
+        },
+    },
+};
+/**
+ * Marker scale-in animation
+ * Markers pop in with a slight scale effect
+ */
+const timelineMarkerVariants = {
+    hidden: {
+        scale: 0,
+        opacity: 0,
+    },
+    visible: {
+        scale: 1,
+        opacity: 1,
+        transition: {
+            type: "spring",
+            stiffness: 300,
+            damping: 20,
+            delay: 0.1,
+        },
+    },
+};
+
+export { getDirectionalVariants, timelineHorizontalItemVariants, timelineItemVariants, timelineMarkerVariants };

package/dist/components/core/Timeline/Timeline.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+import { TimelineProps, TimelineContextValue } from "./Timeline.types";
+export declare const useTimelineContext: () => TimelineContextValue;
+export declare const Timeline: React.ForwardRefExoticComponent<TimelineProps & React.RefAttributes<HTMLDivElement>> & {
+    Item: React.ForwardRefExoticComponent<import("./Timeline.types").TimelineItemProps & React.RefAttributes<HTMLDivElement>>;
+    Marker: React.ForwardRefExoticComponent<import("./Timeline.types").TimelineMarkerProps & React.RefAttributes<HTMLDivElement>>;
+    Content: React.ForwardRefExoticComponent<import("./Timeline.types").TimelineContentProps & React.RefAttributes<HTMLDivElement>>;
+};

package/dist/components/core/Timeline/Timeline.js

@@ -0,0 +1,47 @@
+import { jsx } from 'react/jsx-runtime';
+import React__default, { useContext, createContext, useMemo } from 'react';
+import { cn } from '../../../utils/cn.js';
+import { timelineTheme } from './Timeline.theme.js';
+import { TimelineItem } from './TimelineItem.js';
+import { TimelineMarker } from './TimelineMarker.js';
+import { TimelineContent } from './TimelineContent.js';
+
+// Create context for the main Timeline component
+const TimelineContext = createContext(undefined);
+const useTimelineContext = () => {
+    const ctx = useContext(TimelineContext);
+    if (!ctx)
+        throw new Error("Timeline compound components must be used within <Timeline>");
+    return ctx;
+};
+const TimelineRoot = React__default.forwardRef(({ children, className, layout = "vertical", align = "left", theme: themeOverrides, ...props }, ref) => {
+    // Merge theme with any overrides
+    const theme = useMemo(() => ({
+        ...timelineTheme,
+        ...(themeOverrides || {}),
+        markerStatuses: {
+            ...timelineTheme.markerStatuses,
+            ...((themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.markerStatuses) || {}),
+        },
+    }), [themeOverrides]);
+    // Count total children for index tracking
+    const totalItems = React__default.Children.count(children);
+    // Context value to be provided to children
+    const contextValue = useMemo(() => ({
+        layout,
+        align,
+        theme,
+        totalItems,
+    }), [layout, align, theme, totalItems]);
+    const isHorizontal = layout === "horizontal";
+    return (jsx(TimelineContext.Provider, { value: contextValue, children: jsx("div", { ref: ref, className: cn(isHorizontal ? theme.baseStyleHorizontal : theme.baseStyle, className), "data-layout": layout, "data-align": align, role: "list", "aria-label": "Timeline", ...props, children: children }) }));
+});
+TimelineRoot.displayName = "Timeline";
+// Attach compound subcomponents
+const Timeline = Object.assign(TimelineRoot, {
+    Item: TimelineItem,
+    Marker: TimelineMarker,
+    Content: TimelineContent,
+});
+
+export { Timeline, useTimelineContext };

package/dist/components/core/Timeline/Timeline.theme.d.ts

@@ -0,0 +1,21 @@
+import { TimelineItemStatus } from "./Timeline.types";
+/**
+ * Theme structure for the Timeline component
+ */
+export interface TimelineTheme {
+    baseStyle: string;
+    baseStyleHorizontal: string;
+    itemStyle: string;
+    itemStyleHorizontal: string;
+    lineStyle: string;
+    lineStyleHorizontal: string;
+    markerStyle: string;
+    markerStatuses: Record<TimelineItemStatus, string>;
+    contentStyle: string;
+    contentStyleHorizontal: string;
+}
+/**
+ * Default theme for Timeline components
+ * Uses CSS variables for design token integration
+ */
+export declare const timelineTheme: TimelineTheme;