@refraktor/core 0.0.1

package/src/components/timeline/timeline-item/timeline-item.tsx

@@ -0,0 +1,158 @@
+import { CSSProperties } from "react";
+import { useTheme } from "../../../theme";
+import { factory } from "../../../utils";
+import { useTimelineContext } from "../timeline.context";
+import { getConnector, getSize, getStatus } from "../timeline.styles";
+import { TimelineItemFactoryPayload } from "../timeline.types";
+
+const TimelineItem = factory<TimelineItemFactoryPayload>(
+    (
+        {
+            date,
+            title,
+            bullet,
+            line = true,
+            children,
+            className,
+            __timelineIndex,
+            __timelineCount,
+            ...props
+        },
+        ref
+    ) => {
+        const { cx, getRadius } = useTheme();
+        const { orientation, size, radius, lineVariant, active, getStyles } =
+            useTimelineContext();
+
+        const isActive =
+            typeof __timelineIndex === "number" &&
+            active >= 0 &&
+            __timelineIndex <= active;
+
+        const sizeStyles = getSize(size);
+        const statusStyles = getStatus(isActive);
+        const connectorStyles = getConnector(lineVariant, orientation);
+
+        const isLast =
+            typeof __timelineIndex === "number" &&
+            typeof __timelineCount === "number" &&
+            __timelineIndex === __timelineCount - 1;
+        const showConnector = line && !isLast;
+
+        const connectorColorStyle = {
+            "--refraktor-timeline-connector-color": statusStyles.connectorColor
+        } as CSSProperties;
+
+        return (
+            <div
+                ref={ref}
+                role="listitem"
+                data-active={isActive}
+                data-orientation={orientation}
+                className={cx(
+                    "min-w-0",
+                    orientation === "horizontal"
+                        ? "flex-1 flex flex-col"
+                        : "flex items-stretch last:pb-0",
+                    orientation === "vertical" && sizeStyles.itemSpacing,
+                    sizeStyles.itemGap,
+                    getStyles("item"),
+                    className
+                )}
+                {...props}
+            >
+                <div
+                    className={cx(
+                        "shrink-0",
+                        orientation === "horizontal"
+                            ? "w-full flex items-center"
+                            : "h-full self-stretch flex flex-col items-center",
+                        orientation === "vertical" && sizeStyles.bulletWrapper,
+                        getStyles("bulletWrapper")
+                    )}
+                >
+                    <span
+                        data-timeline-bullet="true"
+                        className={cx(
+                            "inline-flex items-center justify-center",
+                            "select-none",
+                            sizeStyles.bullet,
+                            getRadius(radius),
+                            statusStyles.bullet,
+                            getStyles("bullet")
+                        )}
+                    >
+                        {bullet && bullet}
+                    </span>
+
+                    {showConnector && (
+                        <span
+                            aria-hidden="true"
+                            data-timeline-connector="true"
+                            style={connectorColorStyle}
+                            className={cx(
+                                connectorStyles,
+                                orientation === "vertical" &&
+                                    sizeStyles.connectorExtend,
+                                getStyles("connector")
+                            )}
+                        />
+                    )}
+                </div>
+
+                <div
+                    className={cx(
+                        "min-w-0 flex flex-col",
+                        orientation === "horizontal" && "mt-1",
+                        sizeStyles.contentGap,
+                        getStyles("content")
+                    )}
+                >
+                    {date && (
+                        <div
+                            data-timeline-date="true"
+                            className={cx(
+                                "leading-none",
+                                sizeStyles.date,
+                                statusStyles.date,
+                                getStyles("date")
+                            )}
+                        >
+                            {date}
+                        </div>
+                    )}
+
+                    {title && (
+                        <div
+                            className={cx(
+                                "font-medium leading-tight",
+                                sizeStyles.title,
+                                statusStyles.title,
+                                getStyles("title")
+                            )}
+                        >
+                            {title}
+                        </div>
+                    )}
+
+                    {children !== undefined && children !== null && (
+                        <div
+                            className={cx(
+                                "leading-snug",
+                                sizeStyles.description,
+                                statusStyles.description,
+                                getStyles("description")
+                            )}
+                        >
+                            {children}
+                        </div>
+                    )}
+                </div>
+            </div>
+        );
+    }
+);
+
+TimelineItem.displayName = "@refraktor/core/Timeline.Item";
+
+export default TimelineItem;

package/src/components/timeline/timeline.context.ts

@@ -0,0 +1,21 @@
+import { createSafeContext } from "@refraktor/utils";
+import { RefraktorRadius, RefraktorSize } from "../../theme";
+import {
+    TimelineClassNames,
+    TimelineLineVariant,
+    TimelineOrientation
+} from "./timeline.types";
+
+export interface TimelineContextValue {
+    orientation: TimelineOrientation;
+    size: RefraktorSize;
+    radius: RefraktorRadius;
+    lineVariant: TimelineLineVariant;
+    active: number;
+    getStyles: (part: keyof TimelineClassNames) => string | undefined;
+}
+
+export const [TimelineProvider, useTimelineContext] =
+    createSafeContext<TimelineContextValue>(
+        "Timeline component was not found in tree. Make sure Timeline.Item is wrapped with Timeline."
+    );

package/src/components/timeline/timeline.styles.ts

@@ -0,0 +1,135 @@
+import { RefraktorSize } from "../../theme";
+import { TimelineLineVariant, TimelineOrientation } from "./timeline.types";
+
+type TimelineSizeStyles = {
+    rootGap: string;
+    itemGap: string;
+    itemSpacing: string;
+    connectorExtend: string;
+    bulletWrapper: string;
+    bullet: string;
+    contentGap: string;
+    date: string;
+    title: string;
+    description: string;
+};
+
+type TimelineStatusStyles = {
+    bullet: string;
+    date: string;
+    title: string;
+    description: string;
+    connectorColor: string;
+};
+
+const sizes: Record<RefraktorSize, TimelineSizeStyles> = {
+    xs: {
+        rootGap: "gap-3",
+        itemGap: "gap-2",
+        itemSpacing: "pb-3",
+        connectorExtend: "-mb-3",
+        bulletWrapper: "w-4",
+        bullet: "size-4 text-[9px]",
+        contentGap: "gap-1",
+        date: "text-[10px]",
+        title: "text-xs",
+        description: "text-xs"
+    },
+    sm: {
+        rootGap: "gap-3",
+        itemGap: "gap-2.5",
+        itemSpacing: "pb-3",
+        connectorExtend: "-mb-3",
+        bulletWrapper: "w-5",
+        bullet: "size-4.5 text-[10px]",
+        contentGap: "gap-1",
+        date: "text-[11px]",
+        title: "text-xs",
+        description: "text-xs"
+    },
+    md: {
+        rootGap: "gap-4",
+        itemGap: "gap-3",
+        itemSpacing: "pb-4",
+        connectorExtend: "-mb-4",
+        bulletWrapper: "w-6",
+        bullet: "size-5 text-xs",
+        contentGap: "gap-1.5",
+        date: "text-xs",
+        title: "text-sm",
+        description: "text-xs"
+    },
+    lg: {
+        rootGap: "gap-4",
+        itemGap: "gap-3.5",
+        itemSpacing: "pb-4",
+        connectorExtend: "-mb-4",
+        bulletWrapper: "w-7",
+        bullet: "size-6 text-sm",
+        contentGap: "gap-1.5",
+        date: "text-sm",
+        title: "text-base",
+        description: "text-sm"
+    },
+    xl: {
+        rootGap: "gap-5",
+        itemGap: "gap-4",
+        itemSpacing: "pb-5",
+        connectorExtend: "-mb-5",
+        bulletWrapper: "w-8",
+        bullet: "size-7 text-base",
+        contentGap: "gap-2",
+        date: "text-base",
+        title: "text-lg",
+        description: "text-base"
+    }
+};
+
+const statuses = {
+    default: {
+        bullet: "border border-[var(--refraktor-border)] text-[var(--refraktor-text-secondary)]",
+        date: "text-[var(--refraktor-text-secondary)]",
+        title: "text-[var(--refraktor-text)]",
+        description: "text-[var(--refraktor-text-secondary)]",
+        connectorColor: "var(--refraktor-border)"
+    },
+    active: {
+        bullet: "border border-[var(--refraktor-primary)] text-[var(--refraktor-text)]",
+        date: "text-[var(--refraktor-text-secondary)]",
+        title: "text-[var(--refraktor-text)]",
+        description: "text-[var(--refraktor-text-secondary)]",
+        connectorColor: "var(--refraktor-primary)"
+    }
+} satisfies Record<"default" | "active", TimelineStatusStyles>;
+
+export const getSize = (size: RefraktorSize = "md") => sizes[size];
+
+export const getStatus = (active: boolean) =>
+    active ? statuses.active : statuses.default;
+
+export function getConnector(
+    lineVariant: TimelineLineVariant = "solid",
+    orientation: TimelineOrientation = "vertical"
+) {
+    if (orientation === "vertical") {
+        if (lineVariant === "dashed") {
+            return "w-0 flex-1 border-l border-dashed border-[var(--refraktor-timeline-connector-color)]";
+        }
+
+        if (lineVariant === "dotted") {
+            return "w-0 flex-1 border-l border-dotted border-[var(--refraktor-timeline-connector-color)]";
+        }
+
+        return "w-px flex-1 bg-[var(--refraktor-timeline-connector-color)]";
+    }
+
+    if (lineVariant === "dashed") {
+        return "ml-2 h-0 flex-1 border-t border-dashed border-[var(--refraktor-timeline-connector-color)]";
+    }
+
+    if (lineVariant === "dotted") {
+        return "ml-2 h-0 flex-1 border-t border-dotted border-[var(--refraktor-timeline-connector-color)]";
+    }
+
+    return "ml-2 h-px flex-1 bg-[var(--refraktor-timeline-connector-color)]";
+}

package/src/components/timeline/timeline.test.tsx

@@ -0,0 +1,150 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "../../vitest";
+import Timeline from "./timeline";
+
+describe("@refraktor/core/Timeline", () => {
+    it("renders timeline items with title and children description", async () => {
+        await render(
+            <Timeline>
+                <Timeline.Item title="Project started">Planning</Timeline.Item>
+                <Timeline.Item title="In progress">Building</Timeline.Item>
+            </Timeline>
+        );
+
+        expect(screen.getByRole("list")).toBeInTheDocument();
+        expect(screen.getAllByRole("listitem")).toHaveLength(2);
+        expect(screen.getByText("Project started")).toBeInTheDocument();
+        expect(screen.getByText("Building")).toBeInTheDocument();
+    });
+
+    it("renders date above title", async () => {
+        await render(
+            <Timeline>
+                <Timeline.Item date="Mar 2026" title="Project started">
+                    Planning
+                </Timeline.Item>
+            </Timeline>
+        );
+
+        const date = screen.getByText("Mar 2026");
+        const title = screen.getByText("Project started");
+
+        expect(date).toHaveAttribute("data-timeline-date", "true");
+        expect(
+            date.compareDocumentPosition(title) & Node.DOCUMENT_POSITION_FOLLOWING
+        ).toBeTruthy();
+    });
+
+    it("supports horizontal orientation", async () => {
+        const { container } = await render(
+            <Timeline orientation="horizontal">
+                <Timeline.Item title="Step 1" />
+                <Timeline.Item title="Step 2" />
+            </Timeline>
+        );
+
+        const root = container.firstElementChild as HTMLDivElement;
+        const item = screen.getAllByRole("listitem")[0];
+
+        expect(root).toHaveAttribute("data-orientation", "horizontal");
+        expect(item).toHaveAttribute("data-orientation", "horizontal");
+    });
+
+    it("hides the connector on the last item", async () => {
+        const { container } = await render(
+            <Timeline>
+                <Timeline.Item title="One" />
+                <Timeline.Item title="Two" />
+                <Timeline.Item title="Three" />
+            </Timeline>
+        );
+
+        const connectors = container.querySelectorAll(
+            '[data-timeline-connector="true"]'
+        );
+
+        expect(connectors).toHaveLength(2);
+    });
+
+    it("marks current and previous items active from root active prop", async () => {
+        const { container } = await render(
+            <Timeline lineVariant="dashed" active={1}>
+                <Timeline.Item title="Done" />
+                <Timeline.Item title="Now" />
+            </Timeline>
+        );
+
+        const items = screen.getAllByRole("listitem");
+        const connector = container.querySelector(
+            '[data-timeline-connector="true"]'
+        );
+
+        expect(items[0]).toHaveAttribute("data-active", "true");
+        expect(items[1]).toHaveAttribute("data-active", "true");
+        expect(connector).toHaveClass("border-dashed");
+    });
+
+    it("marks all items active when active exceeds the last index", async () => {
+        await render(
+            <Timeline active={10}>
+                <Timeline.Item title="One" />
+                <Timeline.Item title="Two" />
+            </Timeline>
+        );
+
+        const items = screen.getAllByRole("listitem");
+
+        expect(items[0]).toHaveAttribute("data-active", "true");
+        expect(items[1]).toHaveAttribute("data-active", "true");
+    });
+
+    it("marks no items active when active is -1", async () => {
+        await render(
+            <Timeline active={-1}>
+                <Timeline.Item title="One" />
+                <Timeline.Item title="Two" />
+            </Timeline>
+        );
+
+        const items = screen.getAllByRole("listitem");
+
+        expect(items[0]).toHaveAttribute("data-active", "false");
+        expect(items[1]).toHaveAttribute("data-active", "false");
+    });
+
+    it("supports root and slot class names", async () => {
+        const { container } = await render(
+            <Timeline
+                className="custom-root"
+                classNames={{
+                    item: "custom-item",
+                    bullet: "custom-bullet",
+                    connector: "custom-connector",
+                    date: "custom-date",
+                    title: "custom-title"
+                }}
+            >
+                <Timeline.Item date="Date" title="Entry">
+                    Desc
+                </Timeline.Item>
+                <Timeline.Item title="Entry 2" />
+            </Timeline>
+        );
+
+        const root = container.firstElementChild as HTMLDivElement;
+        const item = screen.getAllByRole("listitem")[0];
+        const bullet = container.querySelector('[data-timeline-bullet="true"]');
+        const connector = container.querySelector(
+            '[data-timeline-connector="true"]'
+        );
+        const date = screen.getByText("Date");
+        const title = screen.getByText("Entry");
+
+        expect(root).toHaveClass("custom-root");
+        expect(item).toHaveClass("custom-item");
+        expect(bullet).toHaveClass("custom-bullet");
+        expect(connector).toHaveClass("custom-connector");
+        expect(date).toHaveClass("custom-date");
+        expect(title).toHaveClass("custom-title");
+    });
+});

package/src/components/timeline/timeline.tsx

@@ -0,0 +1,124 @@
+import { useId } from "@refraktor/utils";
+import {
+    Children,
+    ReactElement,
+    ReactNode,
+    cloneElement,
+    isValidElement,
+    useCallback,
+    useMemo
+} from "react";
+import { useTheme } from "../../theme";
+import {
+    createClassNamesConfig,
+    createComponentConfig,
+    factory,
+    useClassNames,
+    useProps
+} from "../../utils";
+import { TimelineProvider } from "./timeline.context";
+import { getSize } from "./timeline.styles";
+import { TimelineItem } from "./timeline-item";
+import {
+    TimelineClassNames,
+    TimelineFactoryPayload,
+    TimelineItemProps,
+    TimelineProps
+} from "./timeline.types";
+
+const defaultProps = {
+    orientation: "vertical",
+    size: "md",
+    radius: "full",
+    lineVariant: "solid",
+    active: -1
+} satisfies Partial<TimelineProps>;
+
+const isTimelineItemElement = (
+    child: ReactNode
+): child is ReactElement<TimelineItemProps> =>
+    isValidElement(child) && child.type === TimelineItem;
+
+const Timeline = factory<TimelineFactoryPayload>((_props, ref) => {
+    const { cx } = useTheme();
+    const {
+        id,
+        children,
+        orientation,
+        size,
+        radius,
+        lineVariant,
+        active,
+        className,
+        classNames,
+        ...props
+    } = useProps("Timeline", defaultProps, _props);
+    const classes = useClassNames("Timeline", classNames);
+    const _id = useId(id);
+
+    const sizeStyles = getSize(size);
+
+    const resolvedChildren = useMemo(() => {
+        const items = Children.toArray(children);
+        const itemCount = items.filter(isTimelineItemElement).length;
+        let itemIndex = 0;
+
+        return items.map((child) => {
+            if (!isTimelineItemElement(child)) {
+                return child;
+            }
+
+            const nextChild = cloneElement(child, {
+                __timelineIndex: itemIndex,
+                __timelineCount: itemCount
+            });
+
+            itemIndex += 1;
+            return nextChild;
+        });
+    }, [children]);
+
+    const getStyles = useCallback(
+        (part: keyof TimelineClassNames) => classes[part],
+        [classes]
+    );
+
+    return (
+        <TimelineProvider
+            value={{
+                orientation,
+                size,
+                radius,
+                lineVariant,
+                active,
+                getStyles
+            }}
+        >
+            <div
+                ref={ref}
+                id={_id}
+                role="list"
+                data-orientation={orientation}
+                className={cx(
+                    "w-full",
+                    orientation === "horizontal"
+                        ? "flex items-start"
+                        : "flex flex-col",
+                    orientation === "horizontal" && sizeStyles.rootGap,
+                    classes.root,
+                    className
+                )}
+                {...props}
+            >
+                {resolvedChildren}
+            </div>
+        </TimelineProvider>
+    );
+});
+
+Timeline.displayName = "@refraktor/core/Timeline";
+Timeline.configure = createComponentConfig<TimelineProps>();
+Timeline.classNames = createClassNamesConfig<TimelineClassNames>();
+Timeline.Item = TimelineItem;
+
+export default Timeline;

package/src/components/timeline/timeline.types.ts

@@ -0,0 +1,91 @@
+import { ComponentPropsWithoutRef, ReactNode } from "react";
+import { RefraktorRadius, RefraktorSize } from "../../theme";
+import {
+    createClassNamesConfig,
+    createComponentConfig,
+    FactoryPayload
+} from "../../utils";
+import { TimelineItem } from "./timeline-item";
+
+export type TimelineOrientation = "vertical" | "horizontal";
+export type TimelineLineVariant = "solid" | "dashed" | "dotted";
+
+export type TimelineClassNames = {
+    root?: string;
+    item?: string;
+    bulletWrapper?: string;
+    bullet?: string;
+    connector?: string;
+    content?: string;
+    date?: string;
+    title?: string;
+    description?: string;
+};
+
+export interface TimelineProps extends ComponentPropsWithoutRef<"div"> {
+    /** Children containing timeline items */
+    children: ReactNode;
+
+    /** Timeline orientation @default `vertical` */
+    orientation?: TimelineOrientation;
+
+    /** Shared timeline size @default `md` */
+    size?: RefraktorSize;
+
+    /** Radius used for bullets @default `full` */
+    radius?: RefraktorRadius;
+
+    /** Connector style @default `solid` */
+    lineVariant?: TimelineLineVariant;
+
+    /** Active step index. Use `-1` for no active step @default `-1` */
+    active?: number;
+
+    /** Used for editing root class name */
+    className?: string;
+
+    /** Used for styling different parts of the component */
+    classNames?: TimelineClassNames;
+}
+
+export interface TimelineItemProps
+    extends Omit<ComponentPropsWithoutRef<"div">, "title"> {
+    /** Item date/timestamp displayed above title */
+    date?: ReactNode;
+
+    /** Item heading */
+    title?: ReactNode;
+
+    /** Custom bullet content */
+    bullet?: ReactNode;
+
+    /** Whether connector should be rendered @default `true` */
+    line?: boolean;
+
+    /** Item description/body */
+    children?: ReactNode;
+
+    /** Used for editing root class name */
+    className?: string;
+
+    /** @internal */
+    __timelineIndex?: number;
+
+    /** @internal */
+    __timelineCount?: number;
+}
+
+export interface TimelineFactoryPayload extends FactoryPayload {
+    props: TimelineProps;
+    ref: HTMLDivElement;
+    compound: {
+        configure: ReturnType<typeof createComponentConfig<TimelineProps>>;
+        classNames: ReturnType<typeof createClassNamesConfig<TimelineClassNames>>;
+        Item: typeof TimelineItem;
+    };
+}
+
+export interface TimelineItemFactoryPayload extends FactoryPayload {
+    props: TimelineItemProps;
+    ref: HTMLDivElement;
+}

package/src/components/tooltip/index.ts

@@ -0,0 +1,8 @@
+export { default as Tooltip } from "./tooltip";
+export type {
+    TooltipProps,
+    TooltipClassNames,
+    TooltipMiddlewares,
+    TooltipPositioning,
+    TooltipTrigger
+} from "./tooltip.types";