@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.30

package/dist/components/data-display/Table/TablePagination.js

@@ -1,5 +1,6 @@
+"use client";
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
-import React__default from 'react';
+import React__default, { useMemo } from 'react';
 import { Pagination } from '../../core/Pagination/Pagination.js';
 import { Select } from '../../forms/Select/Select.js';
 import '../../forms/Select/Select.theme.js';
@@ -13,12 +14,8 @@ const TablePagination = React__default.forwardRef(({ currentPage, totalItems, pa
     const totalPages = Math.ceil(totalItems / pageSize);
     const startItem = (currentPage - 1) * pageSize + 1;
     const endItem = Math.min(currentPage * pageSize, totalItems);
-    const pageSizeSelectOptions = pageSizeOptions.map((option) => ({
-        id: option,
-        label: option.toString(),
-        value: option,
-    }));
-    return (jsxs("div", { ref: ref, className: cn("flex flex-col sm:flex-row items-start sm:items-center justify-between gap-3 px-4 py-3 border-t border-[var(--color-border)] bg-[var(--color-background)]", className), children: [jsxs("div", { className: "flex items-center gap-4", children: [showPageSizeSelector && (jsxs("div", { className: "flex items-center gap-2", children: [jsx("span", { className: "text-sm text-[var(--color-text-muted)]", children: "Rows per page:" }), jsx(Select, { value: pageSize, onChange: (value) => onPageSizeChange(value), options: pageSizeSelectOptions, size: "sm", className: "w-20" })] })), jsx("div", { className: "text-sm text-[var(--color-text-muted)]", children: totalItems > 0 ? (jsxs(Fragment, { children: ["Showing ", startItem.toLocaleString(), " to ", endItem.toLocaleString(), " of", " ", totalItems.toLocaleString(), " results"] })) : ("No results") })] }), totalPages > 1 && (jsx(Pagination, { currentPage: currentPage, totalPages: totalPages, onPageChange: onPageChange, showPrevNext: true, showFirstLast: false, siblingCount: 1 }))] }));
+    const pageSizeSelectOptions = useMemo(() => pageSizeOptions.map((option) => ({ id: option, label: option.toString(), value: option })), [pageSizeOptions]);
+    return (jsxs("div", { ref: ref, className: cn("flex flex-col sm:flex-row items-start sm:items-center justify-between gap-3 px-4 py-3 border-t border-[var(--color-border)] bg-[var(--color-background)]", className), children: [jsxs("div", { className: "flex items-center gap-4", children: [showPageSizeSelector && (jsxs("div", { className: "flex items-center gap-2", children: [jsx("span", { className: "text-base text-[var(--color-text-muted)]", children: "Rows per page:" }), jsx(Select, { value: pageSize, onChange: (value) => onPageSizeChange(value), options: pageSizeSelectOptions, size: "sm", className: "w-20" })] })), jsx("div", { className: "text-base text-[var(--color-text-muted)]", children: totalItems > 0 ? (jsxs(Fragment, { children: ["Showing ", startItem.toLocaleString(), " to ", endItem.toLocaleString(), " of", " ", totalItems.toLocaleString(), " results"] })) : ("No results") })] }), totalPages > 1 && (jsx(Pagination, { currentPage: currentPage, totalPages: totalPages, onPageChange: onPageChange, showPrevNext: true, showFirstLast: false, siblingCount: 1 }))] }));
 });
 TablePagination.displayName = "Table.Pagination";
 

package/dist/components/data-display/Table/TableRow.d.ts

@@ -1,5 +1,5 @@
 import { InternalTableRowProps } from "./Table.types";
-declare function TableRowComponent<T extends Record<string, any>>({ row, rowId, columns, expandedRowRender, isExpanded, onExpandChange, selectable, selectionType, isSelected, onSelectionChange, freezeFirstColumn, freezeLastColumn, theme, }: InternalTableRowProps<T>): import("react/jsx-runtime").JSX.Element;
+declare function TableRowComponent<T extends Record<string, any>>({ row, rowId, columns, onRowClick, expandedRowRender, isExpanded, onExpandChange, selectable, selectionType, isSelected, onSelectionChange, freezeFirstColumn, freezeLastColumn, theme, }: InternalTableRowProps<T>): import("react/jsx-runtime").JSX.Element;
 declare namespace TableRowComponent {
     var displayName: string;
 }

package/dist/components/data-display/Table/TableRow.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { AnimatePresence, motion } from 'motion/react';
@@ -7,21 +8,24 @@ import { Checkbox } from '../../forms/Checkbox/Checkbox.js';
 import { Radio } from '../../forms/Radio/Radio.js';
 import { MinusIcon, PlusIcon } from '@heroicons/react/24/outline';
 import { UTILITY_COLUMN_WIDTH, UTILITY_COLUMN_ID } from './Table.utils.js';
+import { cn } from '../../../utils/cn.js';
 import { tableExpandAnimations, tableExpandContentAnimations } from './Table.animations.js';
 
-function TableRowComponent({ row, rowId, columns, expandedRowRender, isExpanded = false, onExpandChange, selectable, selectionType, isSelected = false, onSelectionChange, freezeFirstColumn, freezeLastColumn, theme, }) {
-    const rowClasses = [
-        (theme === null || theme === void 0 ? void 0 : theme.rowStyle) || "",
-        isSelected ? (theme === null || theme === void 0 ? void 0 : theme.selectedRowStyle) || "" : "",
-    ]
-        .filter(Boolean)
-        .join(" ");
+function TableRowComponent({ row, rowId, columns, onRowClick, expandedRowRender, isExpanded = false, onExpandChange, selectable, selectionType, isSelected = false, onSelectionChange, freezeFirstColumn, freezeLastColumn, theme, }) {
+    const rowClasses = cn(theme === null || theme === void 0 ? void 0 : theme.rowStyle, isSelected && (theme === null || theme === void 0 ? void 0 : theme.selectedRowStyle));
     const handleExpandClick = (e) => {
         e.stopPropagation();
         onExpandChange === null || onExpandChange === void 0 ? void 0 : onExpandChange(!isExpanded);
     };
     const colSpan = columns.length + (selectable || !!expandedRowRender ? 1 : 0);
-    return (jsxs(Fragment, { children: [jsxs("tr", { className: rowClasses, "data-selected": isSelected, role: "row", "aria-selected": selectable ? isSelected : undefined, "aria-expanded": Boolean(expandedRowRender) ? isExpanded : undefined, children: [(selectable || expandedRowRender) && (jsx(TableCell, { column: {
+    return (jsxs(Fragment, { children: [jsxs("tr", { className: cn(rowClasses, onRowClick && "cursor-pointer"), "data-selected": isSelected, role: "row", "aria-selected": selectable ? isSelected : undefined, "aria-expanded": Boolean(expandedRowRender) ? isExpanded : undefined, tabIndex: onRowClick ? 0 : undefined, onClick: onRowClick ? () => onRowClick(row) : undefined, onKeyDown: onRowClick
+                    ? (e) => {
+                        if (e.target === e.currentTarget && (e.key === "Enter" || e.key === " ")) {
+                            e.preventDefault();
+                            onRowClick(row);
+                        }
+                    }
+                    : undefined, children: [(selectable || expandedRowRender) && (jsx(TableCell, { column: {
                             id: UTILITY_COLUMN_ID,
                             header: "",
                             accessor: () => "",

package/dist/components/data-display/Table/TableSelectionHeader.js

@@ -1,8 +1,10 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { XMarkIcon } from '@heroicons/react/24/outline';
 import { Button } from '../../core/Button/Button.js';
-import { cn } from '../../../utils/cn.js';
 import 'react';
+import { Link } from '../../core/Link/Link.js';
+import { cn } from '../../../utils/cn.js';
 
 /**
  * Selection header that appears when rows are selected
@@ -11,11 +13,11 @@ import 'react';
 const TableSelectionHeader = ({ selectedCount, totalCount, selectedRows, bulkActions = [], onClearSelection, className, }) => {
     if (selectedCount === 0)
         return null;
-    return (jsxs("div", { className: cn("flex items-center justify-between px-3 py-1 rounded-lg shadow-xl bg-[var(--color-background-secondary)] z-10", className), children: [jsxs("div", { className: "flex items-center gap-3", children: [jsx("span", { className: "text-[var(--color-text-muted)] text-sm border-r border-[var(--color-border)] pr-3", children: selectedCount === totalCount
+    return (jsxs("div", { className: cn("flex items-center justify-between px-3 py-1 rounded-lg shadow-xl bg-[var(--color-surface-raised)] z-10", className), children: [jsxs("div", { className: "flex items-center gap-3", children: [jsx("span", { className: "text-[var(--color-text-muted)] text-base border-r border-[var(--color-border)] pr-3", children: selectedCount === totalCount
                             ? `All ${selectedCount} selected`
                             : `${selectedCount} selected` }), bulkActions.length > 0 && (jsx("div", { className: "flex items-center gap-2", children: bulkActions.map((action) => {
                             return (jsx(Button, { color: "neutral", variant: "filled", onClick: () => action.onClick(selectedRows), className: "text-[var(--color-text-secondary)] hover:text-[var(--color-text-primary)]", size: "sm", children: action.label }, action.id));
-                        }) }))] }), jsxs(Button, { color: "primary", variant: "link", onClick: onClearSelection, "aria-label": "Clear selection", children: [jsx(XMarkIcon, { className: "size-4" }), "Clear"] })] }));
+                        }) }))] }), jsxs(Link, { color: "primary", onClick: onClearSelection, "aria-label": "Clear selection", children: [jsx(XMarkIcon, { className: "size-4" }), "Clear"] })] }));
 };
 
 export { TableSelectionHeader };

package/dist/components/data-display/Table/hooks/useTableColumns.js

@@ -1,3 +1,4 @@
+"use client";
 import { useState, useEffect, useCallback, useMemo } from 'react';
 
 function useTableColumns({ columns, initialVisibleColumns, onVisibleColumnsChange, onColumnReorder, }) {

package/dist/components/data-display/Table/hooks/useTableExpansion.js

@@ -1,3 +1,4 @@
+"use client";
 import { useCallback } from 'react';
 
 function useTableExpansion({ expandedRows = [], onExpandedRowsChange, }) {

package/dist/components/data-display/Table/hooks/useTableFilter.js

@@ -1,3 +1,4 @@
+"use client";
 import { useState, useCallback, useMemo } from 'react';
 import { filterData } from '../Table.filterUtils.js';
 

package/dist/components/data-display/Table/hooks/useTablePagination.js

@@ -1,3 +1,4 @@
+"use client";
 import { useMemo } from 'react';
 
 function useTablePagination({ data, pagination, }) {

package/dist/components/data-display/Table/hooks/useTableSelection.js

@@ -1,3 +1,4 @@
+"use client";
 import { useMemo, useCallback } from 'react';
 import { getRowId } from '../Table.utils.js';
 

package/dist/components/data-display/Table/index.d.ts

@@ -1,4 +1,4 @@
-import { TableProps, Column, SortConfig, FilterConfig, FilterOperator, FilterType, FilterLogic, FilterOption, TableThemeOverrides, TableVariant, TableAlignment, SelectionType, TableHeaderProps, TableBodyProps, TableRowProps, TableCellProps, TableHeaderCellProps, BulkAction, ActionItem, ActionVariant, ActionPriority, TableActionsProps, TableActionsMenuProps, TablePaginationProps, TableSelectionHeaderProps, TableColumnManagerProps, TableFilterProps } from './Table.types';
+import { TableProps, Column, SortConfig, FilterConfig, FilterOperator, FilterType, FilterLogic, FilterOption, TableThemeOverrides, TableVariant, TablePadding, TableAlignment, SelectionType, TableHeaderProps, TableBodyProps, TableRowProps, TableCellProps, TableHeaderCellProps, BulkAction, ActionItem, ActionVariant, ActionPriority, TableActionsProps, TableActionsMenuProps, TablePaginationProps, TableSelectionHeaderProps, TableColumnManagerProps, TableFilterProps } from './Table.types';
 import { TableActions } from './TableActions';
 import { TableActionsMenu } from './TableActionsMenu';
 import { TablePagination } from './TablePagination';
@@ -16,7 +16,7 @@ interface TableCompound {
 }
 declare const Table: TableCompound;
 export { Table };
-export type { TableProps, Column, SortConfig, FilterConfig, FilterOperator, FilterType, FilterLogic, FilterOption, TableThemeOverrides, TableVariant, TableAlignment, SelectionType, TableHeaderProps, TableBodyProps, TableRowProps, TableCellProps, TableHeaderCellProps, BulkAction, ActionItem, ActionVariant, ActionPriority, TableActionsProps, TableActionsMenuProps, TablePaginationProps, TableSelectionHeaderProps, TableColumnManagerProps, TableFilterProps, };
+export type { TableProps, Column, SortConfig, FilterConfig, FilterOperator, FilterType, FilterLogic, FilterOption, TableThemeOverrides, TableVariant, TablePadding, TableAlignment, SelectionType, TableHeaderProps, TableBodyProps, TableRowProps, TableCellProps, TableHeaderCellProps, BulkAction, ActionItem, ActionVariant, ActionPriority, TableActionsProps, TableActionsMenuProps, TablePaginationProps, TableSelectionHeaderProps, TableColumnManagerProps, TableFilterProps, };
 export { TableActions, TableActionsMenu, TablePagination, TableFilter };
 export { inferFilterType, getOperatorsForFilterType, getDefaultOperator, isUnaryOperator, isBetweenOperator, filterData, operatorLabels, } from './Table.filterUtils';
 export { useTableColumns, useTableSelection, useTableExpansion, useTablePagination, useTableFilter, } from './hooks';

package/dist/components/data-display/Table/index.js

@@ -2,9 +2,9 @@ import { Table as Table$1 } from './Table.js';
 import { HeaderCell, Cell, Row, Body, Header } from './TableDeclarative.js';
 import { TableActions } from './TableActions.js';
 import 'react/jsx-runtime';
-import 'clsx';
-import 'tailwind-merge';
+import '../../../utils/cn.js';
 import 'react';
+import '../../core/Button/Button.js';
 import { TablePagination } from './TablePagination.js';
 import { TableFilter } from './TableFilter.js';
 

package/dist/components/data-display/Timeline/Timeline.animations.d.ts

@@ -4,13 +4,6 @@ import { Variants } from "motion/react";
  * 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

package/dist/components/data-display/Timeline/Timeline.animations.js

@@ -1,3 +1,4 @@
+"use client";
 /**
  * Timeline item entry animation variants
  * Provides a fade + slide effect when items enter the viewport
@@ -20,32 +21,6 @@ const timelineItemVariants = {
         },
     },
 };
-/**
- * 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
@@ -89,4 +64,4 @@ const timelineMarkerVariants = {
     },
 };
 
-export { getDirectionalVariants, timelineHorizontalItemVariants, timelineItemVariants, timelineMarkerVariants };
+export { timelineHorizontalItemVariants, timelineItemVariants, timelineMarkerVariants };

package/dist/components/data-display/Timeline/Timeline.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
-import { TimelineProps, TimelineContextValue } from "./Timeline.types";
-export declare const useTimelineContext: () => TimelineContextValue;
+import { TimelineProps } from "./Timeline.types";
+export { useTimelineContext } from "./TimelineContext";
 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>>;

package/dist/components/data-display/Timeline/Timeline.js

@@ -1,20 +1,23 @@
-import { jsx } from 'react/jsx-runtime';
-import React__default, { useContext, createContext, useMemo } from 'react';
+"use client";
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import React__default, { useMemo } from 'react';
 import { cn } from '../../../utils/cn.js';
 import { timelineTheme } from './Timeline.theme.js';
+import { TimelineContext } from './TimelineContext.js';
+export { useTimelineContext } from './TimelineContext.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) => {
+/**
+ * Render a single data-driven item to the compound primitives. Keeps one
+ * rendering path: `items` and the compound API both produce `Timeline.Item`s.
+ */
+function renderItemData(item, index, theme) {
+    var _a, _b;
+    return (jsxs(TimelineItem, { status: item.status, className: item.className, children: [jsx(TimelineMarker, { icon: item.icon }), jsx(TimelineContent, { children: (_a = item.content) !== null && _a !== void 0 ? _a : (jsxs(Fragment, { children: [item.title != null && (jsx("p", { className: theme.titleStyle, children: item.title })), item.description != null && (jsx("p", { className: theme.descriptionStyle, children: item.description })), item.timestamp != null && (jsx("p", { className: theme.timestampStyle, children: item.timestamp }))] })) })] }, (_b = item.key) !== null && _b !== void 0 ? _b : index));
+}
+const TimelineRoot = React__default.forwardRef(({ children, items, className, layout = "vertical", theme: themeOverrides, ...props }, ref) => {
     // Merge theme with any overrides
     const theme = useMemo(() => ({
         ...timelineTheme,
@@ -24,17 +27,30 @@ const TimelineRoot = React__default.forwardRef(({ children, className, layout =
             ...((themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.markerStatuses) || {}),
         },
     }), [themeOverrides]);
-    // Count total children for index tracking
-    const totalItems = React__default.Children.count(children);
+    if (process.env.NODE_ENV !== "production" &&
+        items &&
+        React__default.Children.count(children) > 0) {
+        console.warn("[Timeline]: both `items` and children were provided — `items` takes precedence and children are ignored.");
+    }
+    // Data-driven path renders to the same compound primitives as the
+    // composition path, so everything downstream is identical.
+    const baseChildren = items
+        ? items.map((item, i) => renderItemData(item, i, theme))
+        : children;
+    // Inject each item's index from a single source of truth (the rendered
+    // children array) — no DOM measurement, no IntersectionObserver-derived order.
+    const indexedChildren = React__default.Children.map(baseChildren, (child, index) => React__default.isValidElement(child)
+        ? React__default.cloneElement(child, { _index: index })
+        : child);
+    const totalItems = React__default.Children.count(baseChildren);
     // Context value to be provided to children
     const contextValue = useMemo(() => ({
         layout,
-        align,
         theme,
         totalItems,
-    }), [layout, align, theme, totalItems]);
+    }), [layout, 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 }) }));
+    return (jsx(TimelineContext.Provider, { value: contextValue, children: jsx("div", { ref: ref, className: cn(isHorizontal ? theme.baseStyleHorizontal : theme.baseStyle, className), "data-layout": layout, role: "list", "aria-label": "Timeline", ...props, children: indexedChildren }) }));
 });
 TimelineRoot.displayName = "Timeline";
 // Attach compound subcomponents
@@ -44,4 +60,4 @@ const Timeline = Object.assign(TimelineRoot, {
     Content: TimelineContent,
 });
 
-export { Timeline, useTimelineContext };
+export { Timeline };

package/dist/components/data-display/Timeline/Timeline.theme.d.ts

@@ -1,19 +1,5 @@
-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;
-}
+import { TimelineTheme } from "./Timeline.types";
+export type { TimelineTheme } from "./Timeline.types";
 /**
  * Default theme for Timeline components
  * Uses CSS variables for design token integration

package/dist/components/data-display/Timeline/Timeline.theme.js

@@ -11,22 +11,28 @@ const timelineTheme = {
     itemStyle: "relative flex gap-4",
     // Individual timeline item - horizontal
     itemStyleHorizontal: "relative flex flex-col items-center flex-1 gap-3",
-    // Connector line - vertical (positioned on the marker column)
-    lineStyle: "absolute top-0 bottom-0 w-0.5 bg-[var(--color-border)]",
-    // Connector line - horizontal
-    lineStyleHorizontal: "absolute left-0 right-0 h-0.5 bg-[var(--color-border)]",
+    // Connector line - vertical (stretches down below the marker)
+    connectorStyle: "w-0.5 flex-1 min-h-4 bg-[var(--color-border)]",
+    // Connector line - horizontal (spans from this item's center to the next)
+    connectorStyleHorizontal: "absolute top-1/2 -translate-y-1/2 left-1/2 h-0.5 w-full bg-[var(--color-border)]",
+    // Completed connector color (overrides the base connector background)
+    connectorCompletedStyle: "bg-[var(--color-success)]",
     // Marker base styles (shared across statuses)
-    markerStyle: "relative z-10 flex items-center justify-center shrink-0 rounded-full border-2 transition-colors duration-200",
+    markerStyle: "relative z-10 flex items-center justify-center shrink-0 rounded-full border-2 transition-colors duration-200 ring-4 ring-[var(--color-surface)] backdrop-blur-sm",
     // Marker status-specific styles
     markerStatuses: {
-        completed: "w-8 h-8 bg-[var(--color-success)] border-[var(--color-success)] text-white",
-        active: "w-8 h-8 bg-[var(--color-primary)] border-[var(--color-primary)] text-white ring-4 ring-[var(--color-primary-100)]",
-        pending: "w-8 h-8 bg-[var(--color-background)] border-[var(--color-border)]",
+        completed: "size-8 bg-[var(--color-success)] border-[var(--color-success)] text-[var(--color-success-contrast)]",
+        active: "size-8 bg-[var(--color-primary)]/0 border-[var(--color-primary)] text-[var(--color-primary)] ",
+        pending: "size-8 bg-[var(--color-background)] border-[var(--color-border)] text-[var(--color-text-muted)]",
     },
     // Content area - vertical
     contentStyle: "pb-8 pt-0.5 min-w-0",
     // Content area - horizontal
     contentStyleHorizontal: "text-center px-2 min-w-0",
+    // Data-driven (`items`) content typography
+    titleStyle: "text-sm font-medium text-[var(--color-text-primary)]",
+    descriptionStyle: "text-sm text-[var(--color-text-secondary)] mt-1",
+    timestampStyle: "text-xs text-[var(--color-text-placeholder)] mt-1",
 };
 
 export { timelineTheme };

package/dist/components/data-display/Timeline/Timeline.types.d.ts

@@ -3,13 +3,6 @@ import React from "react";
  * Layout orientation for the Timeline
  */
 export type TimelineLayout = "vertical" | "horizontal";
-/**
- * Alignment mode for vertical timeline items
- * - left: all items on the left side of the line
- * - right: all items on the right side of the line
- * - alternate: items alternate between left and right
- */
-export type TimelineAlign = "left" | "right" | "alternate";
 /**
  * Status of an individual timeline item
  * - completed: item is finished (success color)
@@ -17,6 +10,31 @@ export type TimelineAlign = "left" | "right" | "alternate";
  * - pending: item has not started yet (neutral/muted)
  */
 export type TimelineItemStatus = "completed" | "active" | "pending";
+/**
+ * Theme structure for the Timeline component
+ * (declared here, not in Timeline.theme.ts, so types→theme imports never
+ * happen — keeps the theme/types import graph one-directional)
+ */
+export interface TimelineTheme {
+    baseStyle: string;
+    baseStyleHorizontal: string;
+    itemStyle: string;
+    itemStyleHorizontal: string;
+    /** Connector line between markers — vertical layout */
+    connectorStyle: string;
+    /** Connector line between markers — horizontal layout */
+    connectorStyleHorizontal: string;
+    /** Color override applied to the connector when the item is completed */
+    connectorCompletedStyle: string;
+    markerStyle: string;
+    markerStatuses: Record<TimelineItemStatus, string>;
+    contentStyle: string;
+    contentStyleHorizontal: string;
+    /** Default typography for the data-driven (`items`) API content */
+    titleStyle: string;
+    descriptionStyle: string;
+    timestampStyle: string;
+}
 /**
  * Theme overrides for Timeline
  */
@@ -25,12 +43,44 @@ export interface TimelineThemeOverrides {
     baseStyleHorizontal?: string;
     itemStyle?: string;
     itemStyleHorizontal?: string;
-    lineStyle?: string;
-    lineStyleHorizontal?: string;
+    connectorStyle?: string;
+    connectorStyleHorizontal?: string;
+    connectorCompletedStyle?: string;
     markerStyle?: string;
     markerStatuses?: Partial<Record<TimelineItemStatus, string>>;
     contentStyle?: string;
     contentStyleHorizontal?: string;
+    titleStyle?: string;
+    descriptionStyle?: string;
+    timestampStyle?: string;
+}
+/**
+ * A single timeline item for the data-driven (`items`) API.
+ * Maps internally to `Timeline.Item` → `Timeline.Marker` + `Timeline.Content`,
+ * so it stays fully serializable (no JSX composition required). This is the
+ * generative-UI / model-friendly entry path; the compound API remains for
+ * hand-authored timelines that need full control.
+ */
+export interface TimelineItemData {
+    /** @default 'pending' */
+    status?: TimelineItemStatus;
+    /** Heading line (rendered with the theme's `titleStyle`) */
+    title?: React.ReactNode;
+    /** Body line (rendered with the theme's `descriptionStyle`) */
+    description?: React.ReactNode;
+    /** Trailing meta line, e.g. a date (rendered with the theme's `timestampStyle`) */
+    timestamp?: React.ReactNode;
+    /** Icon element shown inside the marker. Pass a ReactNode (resolve name→icon upstream). */
+    icon?: React.ReactNode;
+    /**
+     * Escape hatch — when provided, replaces the default title/description/timestamp
+     * rendering with arbitrary content (matches the compound `Timeline.Content` body).
+     */
+    content?: React.ReactNode;
+    /** Optional className forwarded to the item wrapper */
+    className?: string;
+    /** Stable React key (falls back to the array index) */
+    key?: string | number;
 }
 /**
  * Timeline root component props
@@ -42,37 +92,25 @@ export interface TimelineProps extends React.HTMLAttributes<HTMLDivElement> {
      */
     layout?: TimelineLayout;
     /**
-     * Alignment of items relative to the timeline line (vertical only)
-     * @default 'left'
+     * Data-driven items. When provided, the timeline renders from this array and
+     * any `children` are ignored (dev-warns). Omit it to use the compound API.
      */
-    align?: TimelineAlign;
+    items?: TimelineItemData[];
     /**
      * Theme overrides for customizing styles
      */
     theme?: TimelineThemeOverrides;
     /**
-     * Children - should be Timeline.Item components
+     * Children — `Timeline.Item` components (compound API). Optional when `items` is used.
      */
-    children: React.ReactNode;
+    children?: React.ReactNode;
 }
 /**
  * Context value shared between Timeline compound components
  */
 export interface TimelineContextValue {
     layout: TimelineLayout;
-    align: TimelineAlign;
-    theme: TimelineThemeOverrides & {
-        baseStyle: string;
-        baseStyleHorizontal: string;
-        itemStyle: string;
-        itemStyleHorizontal: string;
-        lineStyle: string;
-        lineStyleHorizontal: string;
-        markerStyle: string;
-        markerStatuses: Record<TimelineItemStatus, string>;
-        contentStyle: string;
-        contentStyleHorizontal: string;
-    };
+    theme: TimelineTheme;
     totalItems: number;
 }
 /**
@@ -92,6 +130,11 @@ export interface TimelineItemProps extends React.HTMLAttributes<HTMLDivElement>
      * Item content - should include Timeline.Marker and Timeline.Content
      */
     children: React.ReactNode;
+    /**
+     * @internal Index within the timeline, injected by the root via cloneElement.
+     * Do not set this manually.
+     */
+    _index?: number;
 }
 /**
  * Context value for individual Timeline items

package/dist/components/data-display/Timeline/Timeline.utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Strip the DOM drag/animation handlers that collide with `motion.*` element
+ * props, so the remaining `...rest` can be safely spread onto a motion element.
+ * Shared by TimelineItem and TimelineMarker (both render a `motion.div`).
+ */
+export declare function stripMotionConflicts<T extends Record<string, unknown>>(props: T): Omit<T, "onDrag" | "onDragEnd" | "onDragStart" | "onAnimationStart" | "onAnimationEnd">;

package/dist/components/data-display/Timeline/Timeline.utils.js

@@ -0,0 +1,11 @@
+/**
+ * Strip the DOM drag/animation handlers that collide with `motion.*` element
+ * props, so the remaining `...rest` can be safely spread onto a motion element.
+ * Shared by TimelineItem and TimelineMarker (both render a `motion.div`).
+ */
+function stripMotionConflicts(props) {
+    const { onDrag: _onDrag, onDragEnd: _onDragEnd, onDragStart: _onDragStart, onAnimationStart: _onAnimationStart, onAnimationEnd: _onAnimationEnd, ...rest } = props;
+    return rest;
+}
+
+export { stripMotionConflicts };

package/dist/components/data-display/Timeline/TimelineContent.js

@@ -1,20 +1,17 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { cn } from '../../../utils/cn.js';
-import { useTimelineContext } from './Timeline.js';
+import { useTimelineContext } from './TimelineContext.js';
 import { useTimelineItemContext } from './TimelineItem.js';
 
 const TimelineContent = React__default.forwardRef(({ children, className, ...props }, ref) => {
-    const { theme, layout, align } = useTimelineContext();
-    const { isLast, index } = useTimelineItemContext();
+    const { theme, layout } = useTimelineContext();
+    const { isLast } = useTimelineItemContext();
     const isHorizontal = layout === "horizontal";
-    // For alternate layout, determine text alignment
-    const isAlternateRight = align === "alternate" && index % 2 !== 0;
     return (jsx("div", { ref: ref, className: cn(isHorizontal ? theme.contentStyleHorizontal : theme.contentStyle, 
         // Remove bottom padding on last item
-        !isHorizontal && isLast && "pb-0", 
-        // Align text based on side in alternate mode
-        !isHorizontal && isAlternateRight && "text-right", !isHorizontal && align === "right" && "text-right", className), ...props, children: children }));
+        !isHorizontal && isLast && "pb-0", className), ...props, children: children }));
 });
 TimelineContent.displayName = "TimelineContent";
 

package/dist/components/data-display/Timeline/TimelineContext.d.ts

@@ -0,0 +1,3 @@
+import { TimelineContextValue } from "./Timeline.types";
+export declare const TimelineContext: import("react").Context<TimelineContextValue | undefined>;
+export declare const useTimelineContext: () => TimelineContextValue;

package/dist/components/data-display/Timeline/TimelineContext.js

@@ -0,0 +1,16 @@
+"use client";
+import { createContext, useContext } from 'react';
+
+// Lives in its own module (not Timeline.tsx) so sub-components can consume the
+// context without importing Timeline.tsx, which imports them back (circular
+// dep). Timeline.tsx re-exports `useTimelineContext`, so existing import paths
+// keep working.
+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;
+};
+
+export { TimelineContext, useTimelineContext };