@refraktor/core 0.0.1

package/src/components/popover/use-popover.ts

@@ -0,0 +1,218 @@
+import { useUncontrolled } from "@refraktor/utils";
+import {
+    PopoverMiddlewares,
+    PopoverPositioning,
+    PopoverTrigger
+} from "./popover.types";
+import {
+    arrow,
+    autoUpdate,
+    flip,
+    FloatingContext,
+    inline,
+    Middleware,
+    offset,
+    Placement,
+    safePolygon,
+    shift,
+    useClick,
+    useDismiss,
+    useFloating,
+    useFocus,
+    useHover,
+    useInteractions,
+    useRole
+} from "@floating-ui/react";
+import { useCallback, useMemo, useRef } from "react";
+
+interface UsePopoverProps {
+    opened?: boolean;
+    defaultOpened?: boolean;
+    onOpenedChange?: (opened: boolean) => void;
+    positioning?: PopoverPositioning;
+    middlewares?: PopoverMiddlewares;
+    disabled?: boolean;
+    trigger?: PopoverTrigger;
+    showArrow?: boolean;
+    closeOnClickOutside?: boolean;
+    closeOnEscape?: boolean;
+    openDelay?: number;
+    closeDelay?: number;
+}
+
+export interface UsePopoverReturn {
+    opened: boolean;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    context: FloatingContext;
+    refs: {
+        setReference: (node: HTMLElement | null) => void;
+        setFloating: (node: HTMLElement | null) => void;
+        reference: React.MutableRefObject<HTMLElement | null>;
+        floating: React.MutableRefObject<HTMLElement | null>;
+    };
+    floatingStyles: React.CSSProperties;
+    getReferenceProps: (
+        userProps?: React.HTMLAttributes<HTMLElement>
+    ) => Record<string, unknown>;
+    getFloatingProps: (
+        userProps?: React.HTMLAttributes<HTMLElement>
+    ) => Record<string, unknown>;
+    arrowRef: React.RefObject<SVGSVGElement | null>;
+    placement: Placement;
+}
+
+export function usePopover(options: UsePopoverProps = {}): UsePopoverReturn {
+    const {
+        opened,
+        defaultOpened,
+        onOpenedChange,
+        positioning = {
+            placement: "bottom",
+            offset: 8
+        },
+        middlewares = { flip: true, shift: true },
+        disabled = false,
+        trigger = "click",
+        showArrow = false,
+        closeOnClickOutside = true,
+        closeOnEscape = true,
+        openDelay = 0,
+        closeDelay = 0
+    } = options;
+
+    const arrowRef = useRef<SVGSVGElement>(null);
+
+    const [isOpen, setIsOpen] = useUncontrolled({
+        value: opened,
+        defaultValue: defaultOpened,
+        finalValue: false,
+        onChange: onOpenedChange
+    });
+
+    const middleware = useMemo(() => {
+        const middlewareList: Middleware[] = [];
+
+        middlewareList.push(offset(positioning.offset ?? 8));
+
+        if (middlewares.flip) {
+            middlewareList.push(
+                flip(
+                    typeof middlewares.flip === "boolean"
+                        ? undefined
+                        : middlewares.flip
+                )
+            );
+        }
+
+        if (middlewares.shift) {
+            middlewareList.push(
+                shift(
+                    typeof middlewares.shift === "boolean"
+                        ? undefined
+                        : middlewares.shift
+                )
+            );
+        }
+
+        if (middlewares.inline) {
+            middlewareList.push(
+                inline(
+                    typeof middlewares.inline === "boolean"
+                        ? undefined
+                        : middlewares.inline
+                )
+            );
+        }
+
+        if (arrowRef.current && showArrow) {
+            middlewareList.push(
+                arrow({
+                    element: arrowRef.current
+                })
+            );
+        }
+
+        return middlewareList;
+    }, [positioning.offset, middlewares, showArrow, arrowRef]);
+
+    const floating = useFloating({
+        placement: positioning.placement,
+        open: isOpen,
+        onOpenChange: setIsOpen,
+        middleware: middleware,
+        whileElementsMounted: autoUpdate
+    });
+
+    const click = useClick(floating.context, {
+        enabled: trigger === "click" && !disabled
+    });
+
+    const hover = useHover(floating.context, {
+        enabled: trigger === "hover" && !disabled,
+        handleClose: safePolygon(),
+        delay: {
+            open: openDelay,
+            close: closeDelay
+        }
+    });
+
+    const focus = useFocus(floating.context, {
+        enabled: trigger === "focus" && !disabled
+    });
+
+    const dismiss = useDismiss(floating.context, {
+        outsidePress: closeOnClickOutside,
+        escapeKey: closeOnEscape
+    });
+
+    const role = useRole(floating.context, {
+        role: "dialog"
+    });
+
+    const { getReferenceProps, getFloatingProps } = useInteractions([
+        click,
+        hover,
+        focus,
+        dismiss,
+        role
+    ]);
+
+    const open = useCallback(() => {
+        if (!disabled) {
+            setIsOpen(true);
+        }
+    }, [setIsOpen, disabled]);
+
+    const close = useCallback(() => {
+        setIsOpen(false);
+    }, [setIsOpen]);
+
+    const toggle = useCallback(() => {
+        if (!disabled) {
+            setIsOpen(!isOpen);
+        }
+    }, [setIsOpen, isOpen, disabled]);
+
+    return {
+        opened: isOpen,
+        open,
+        close,
+        toggle,
+        context: floating.context,
+        refs: {
+            setReference: floating.refs.setReference,
+            setFloating: floating.refs.setFloating,
+            reference: floating.refs
+                .reference as React.MutableRefObject<HTMLElement | null>,
+            floating: floating.refs
+                .floating as React.MutableRefObject<HTMLElement | null>
+        },
+        floatingStyles: floating.floatingStyles,
+        getReferenceProps,
+        getFloatingProps,
+        placement: floating.placement,
+        arrowRef
+    };
+}

package/src/components/portal/index.ts

@@ -0,0 +1,2 @@
+export { default as Portal } from "./portal";
+export type { PortalProps } from "./portal.types";

package/src/components/portal/portal.test.tsx

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "../../vitest";
+import Portal from "./portal";
+
+describe("@refraktor/core/Portal", () => {
+    it("renders into document.body by default", async () => {
+        await render(
+            <div data-testid="root">
+                <Portal>
+                    <div data-testid="content">Portal content</div>
+                </Portal>
+            </div>
+        );
+
+        const root = screen.getByTestId("root");
+        const content = await screen.findByTestId("content");
+
+        expect(document.body).toContainElement(content);
+        expect(root).not.toContainElement(content);
+    });
+
+    it("renders into custom target", async () => {
+        const target = document.createElement("div");
+        target.id = "portal-target";
+        document.body.appendChild(target);
+
+        await render(
+            <Portal target="#portal-target">
+                <div data-testid="content">Targeted content</div>
+            </Portal>
+        );
+
+        const content = await screen.findByTestId("content");
+
+        expect(target).toContainElement(content);
+
+        target.remove();
+    });
+});

package/src/components/portal/portal.tsx

@@ -0,0 +1,104 @@
+import { createPortal } from "react-dom";
+import { createComponentConfig, factory, useProps } from "../../utils";
+import { PortalFactoryPayload, PortalProps } from "./portal.types";
+import { ComponentPropsWithoutRef, useEffect, useRef, useState } from "react";
+
+function createPortalNode(props: ComponentPropsWithoutRef<"div">) {
+    const node = document.createElement("div");
+    node.setAttribute("data-portal", "true");
+    typeof props.className === "string" &&
+        node.classList.add(...props.className.split(" ").filter(Boolean));
+    typeof props.style === "object" && Object.assign(node.style, props.style);
+    typeof props.id === "string" && node.setAttribute("id", props.id);
+    return node;
+}
+
+function getTargetNode({
+    target,
+    reuseTargetNode,
+    ...others
+}: Omit<PortalProps, "children">): HTMLElement {
+    if (target) {
+        if (typeof target === "string") {
+            return (
+                document.querySelector<HTMLElement>(target) ||
+                createPortalNode(others)
+            );
+        }
+
+        return target;
+    }
+
+    if (reuseTargetNode) {
+        const existingNode = document.querySelector<HTMLElement>(
+            "[data-velra-shared-portal-node]"
+        );
+
+        if (existingNode) {
+            return existingNode;
+        }
+
+        const node = createPortalNode(others);
+        node.setAttribute("data-velra-shared-portal-node", "true");
+        document.body.appendChild(node);
+        return node;
+    }
+
+    return createPortalNode(others);
+}
+
+const Portal = factory<PortalFactoryPayload>((_props, ref) => {
+    const { children, target, reuseTargetNode, ...others } = useProps(
+        "Portal",
+        null,
+        _props
+    );
+
+    const [mounted, setMounted] = useState(false);
+    const nodeRef = useRef<HTMLElement | null>(null);
+
+    useEffect(() => {
+        setMounted(true);
+        nodeRef.current = getTargetNode({ target, reuseTargetNode, ...others });
+
+        if (ref) {
+            if (typeof ref === "function") {
+                ref(nodeRef.current as HTMLDivElement);
+            } else {
+                ref.current = nodeRef.current as HTMLDivElement;
+            }
+        }
+
+        if (target && nodeRef.current) {
+            const computedStyle = window.getComputedStyle(nodeRef.current);
+            if (computedStyle.position === "static") {
+                nodeRef.current.style.position = "relative";
+            }
+        }
+
+        if (!target && !reuseTargetNode && nodeRef.current) {
+            document.body.appendChild(nodeRef.current);
+        }
+
+        return () => {
+            if (!target && !reuseTargetNode && nodeRef.current) {
+                try {
+                    if (document.body.contains(nodeRef.current)) {
+                        document.body.removeChild(nodeRef.current);
+                    }
+                } catch (error) {}
+            }
+        };
+    }, [target, reuseTargetNode]);
+
+    if (!mounted || !nodeRef.current) {
+        return null;
+    }
+
+    return createPortal(<>{children}</>, nodeRef.current);
+});
+
+Portal.displayName = "@velra/core/Portal";
+Portal.configure = createComponentConfig<PortalProps>();
+
+export default Portal;

package/src/components/portal/portal.types.ts

@@ -0,0 +1,31 @@
+import { ComponentPropsWithoutRef, ReactNode } from "react";
+import {
+    createClassNamesConfig,
+    createComponentConfig,
+    FactoryPayload
+} from "../../utils";
+
+export interface BasePortalProps extends ComponentPropsWithoutRef<"div"> {
+    /** Target element to render the portal inside. Can be an HTMLElement or a CSS selector string. */
+    target?: HTMLElement | string;
+
+    /** Whether to reuse a shared portal node for all portals with this option enabled. @default false */
+    reuseTargetNode?: boolean;
+}
+
+export interface PortalProps extends BasePortalProps {
+    /** The content to render inside the portal */
+    children: ReactNode;
+}
+
+export type PortalClassNames = {
+    root?: string;
+};
+
+export interface PortalFactoryPayload extends FactoryPayload {
+    props: PortalProps;
+    ref: HTMLDivElement;
+    compound: {
+        configure: ReturnType<typeof createComponentConfig<PortalProps>>;
+    };
+}

package/src/components/progress/index.ts

@@ -0,0 +1,2 @@
+export { default as Progress } from "./progress";
+export type { ProgressProps, ProgressClassNames } from "./progress.types";

package/src/components/progress/progress.styles.ts

@@ -0,0 +1,25 @@
+import { RefraktorSize } from "../../theme";
+
+type ProgressSizeStyles = {
+    track: string;
+};
+
+const sizes: Record<RefraktorSize, ProgressSizeStyles> = {
+    xs: {
+        track: "h-1"
+    },
+    sm: {
+        track: "h-1.5"
+    },
+    md: {
+        track: "h-2"
+    },
+    lg: {
+        track: "h-2.5"
+    },
+    xl: {
+        track: "h-3"
+    }
+};
+
+export const getSize = (size: RefraktorSize = "md") => sizes[size];

package/src/components/progress/progress.test.tsx

@@ -0,0 +1,107 @@
+import { createRef } from "react";
+import { describe, expect, it } from "vitest";
+import { render, screen, waitFor } from "../../vitest";
+import Progress from "./progress";
+
+describe("@refraktor/core/Progress", () => {
+    it("renders with determinate values", async () => {
+        await render(<Progress value={45} aria-label="Upload progress" />);
+
+        const track = screen.getByRole("progressbar", {
+            name: "Upload progress"
+        });
+        const bar = track.firstElementChild as HTMLDivElement;
+
+        expect(track).toHaveAttribute("aria-valuemin", "0");
+        expect(track).toHaveAttribute("aria-valuemax", "100");
+        expect(track).toHaveAttribute("aria-valuenow", "45");
+        expect(bar).toHaveStyle({ width: "45%" });
+    });
+
+    it("forwards ref correctly", async () => {
+        const ref = createRef<HTMLDivElement>();
+
+        await render(<Progress ref={ref} aria-label="Progress" />);
+
+        expect(ref.current).toBeInstanceOf(HTMLDivElement);
+        expect(ref.current?.tagName).toBe("DIV");
+        expect(ref.current).toHaveAttribute("role", "progressbar");
+    });
+
+    it("clamps values outside range", async () => {
+        const { rerender } = await render(
+            <Progress value={-20} aria-label="Clamped progress" />
+        );
+
+        let track = screen.getByRole("progressbar", { name: "Clamped progress" });
+        let bar = track.firstElementChild as HTMLDivElement;
+        expect(track).toHaveAttribute("aria-valuenow", "0");
+        expect(bar).toHaveStyle({ width: "0%" });
+
+        rerender(<Progress value={180} aria-label="Clamped progress" />);
+
+        await waitFor(() => {
+            track = screen.getByRole("progressbar", { name: "Clamped progress" });
+            bar = track.firstElementChild as HTMLDivElement;
+            expect(track).toHaveAttribute("aria-valuenow", "100");
+            expect(bar).toHaveStyle({ width: "100%" });
+        });
+    });
+
+    it("supports custom min and max", async () => {
+        await render(
+            <Progress
+                value={25}
+                min={20}
+                max={40}
+                aria-label="Custom range progress"
+            />
+        );
+
+        const track = screen.getByRole("progressbar", {
+            name: "Custom range progress"
+        });
+        const bar = track.firstElementChild as HTMLDivElement;
+
+        expect(track).toHaveAttribute("aria-valuemin", "20");
+        expect(track).toHaveAttribute("aria-valuemax", "40");
+        expect(track).toHaveAttribute("aria-valuenow", "25");
+        expect(bar).toHaveStyle({ width: "25%" });
+    });
+
+    it("supports indeterminate mode", async () => {
+        await render(<Progress indeterminate aria-label="Loading progress" />);
+
+        const track = screen.getByRole("progressbar", {
+            name: "Loading progress"
+        });
+        const bar = track.firstElementChild as HTMLDivElement;
+
+        expect(track).not.toHaveAttribute("aria-valuemin");
+        expect(track).not.toHaveAttribute("aria-valuemax");
+        expect(track).not.toHaveAttribute("aria-valuenow");
+        expect(bar).toHaveClass("refraktor-progress-indeterminate");
+        expect(bar.style.width).toBe("");
+    });
+
+    it("supports root and slot class names", async () => {
+        const { container } = await render(
+            <Progress
+                aria-label="Styled progress"
+                className="custom-root"
+                classNames={{
+                    track: "custom-track",
+                    bar: "custom-bar"
+                }}
+            />
+        );
+
+        const root = container.firstElementChild as HTMLDivElement;
+        const track = screen.getByRole("progressbar", { name: "Styled progress" });
+        const bar = track.firstElementChild as HTMLDivElement;
+
+        expect(root).toHaveClass("custom-root");
+        expect(track).toHaveClass("custom-track");
+        expect(bar).toHaveClass("custom-bar");
+    });
+});

package/src/components/progress/progress.tsx

@@ -0,0 +1,93 @@
+import { clamp, useId } from "@refraktor/utils";
+import { useTheme } from "../../theme";
+import {
+    createClassNamesConfig,
+    createComponentConfig,
+    factory,
+    useClassNames,
+    useProps
+} from "../../utils";
+import {
+    ProgressClassNames,
+    ProgressFactoryPayload,
+    ProgressProps
+} from "./progress.types";
+import { getSize } from "./progress.styles";
+
+const defaultProps = {
+    value: 0,
+    min: 0,
+    max: 100,
+    indeterminate: false,
+    animated: true,
+    size: "md",
+    radius: "full"
+} satisfies Partial<ProgressProps>;
+
+const Progress = factory<ProgressFactoryPayload>((_props, ref) => {
+    const { cx, getRadius } = useTheme();
+    const {
+        id,
+        value,
+        min,
+        max,
+        indeterminate,
+        animated,
+        size,
+        radius,
+        className,
+        classNames,
+        ...props
+    } = useProps("Progress", defaultProps, _props);
+    const classes = useClassNames("Progress", classNames);
+
+    const _id = useId(id);
+    const sizeStyles = getSize(size);
+
+    const lowerBound = Math.min(min, max);
+    const upperBound = Math.max(min, max);
+    const clampedValue = clamp(value, lowerBound, upperBound);
+    const percentage =
+        upperBound === lowerBound
+            ? 0
+            : ((clampedValue - lowerBound) / (upperBound - lowerBound)) * 100;
+
+    return (
+        <div className={cx("w-full", classes.root, className)}>
+            <div
+                {...props}
+                ref={ref}
+                id={_id}
+                role="progressbar"
+                aria-valuemin={indeterminate ? undefined : lowerBound}
+                aria-valuemax={indeterminate ? undefined : upperBound}
+                aria-valuenow={indeterminate ? undefined : clampedValue}
+                className={cx(
+                    "relative w-full overflow-hidden bg-[var(--refraktor-bg)]",
+                    sizeStyles.track,
+                    getRadius(radius),
+                    classes.track
+                )}
+            >
+                <div
+                    className={cx(
+                        "h-full bg-[var(--refraktor-primary)]",
+                        getRadius(radius),
+                        indeterminate &&
+                            "absolute inset-y-0 left-0 refraktor-progress-indeterminate",
+                        animated && !indeterminate &&
+                            "transition-[width] duration-300 ease-out",
+                        classes.bar
+                    )}
+                    style={indeterminate ? undefined : { width: `${percentage}%` }}
+                />
+            </div>
+        </div>
+    );
+});
+
+Progress.displayName = "@refraktor/core/Progress";
+Progress.configure = createComponentConfig<ProgressProps>();
+Progress.classNames = createClassNamesConfig<ProgressClassNames>();
+
+export default Progress;

package/src/components/progress/progress.types.ts

@@ -0,0 +1,52 @@
+import { ComponentPropsWithoutRef } from "react";
+import { RefraktorRadius, RefraktorSize } from "../../theme";
+import {
+    createClassNamesConfig,
+    createComponentConfig,
+    FactoryPayload
+} from "../../utils";
+
+export type ProgressClassNames = {
+    root?: string;
+    track?: string;
+    bar?: string;
+};
+
+export interface ProgressProps
+    extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+    /** Current progress value @default `0` */
+    value?: number;
+
+    /** Minimum progress value @default `0` */
+    min?: number;
+
+    /** Maximum progress value @default `100` */
+    max?: number;
+
+    /** Whether progress is indeterminate @default `false` */
+    indeterminate?: boolean;
+
+    /** Whether width transitions are animated @default `true` */
+    animated?: boolean;
+
+    /** Track size @default `md` */
+    size?: RefraktorSize;
+
+    /** Track radius @default `full` */
+    radius?: RefraktorRadius;
+
+    /** Used for editing root class name */
+    className?: string;
+
+    /** Used for styling different parts of the component */
+    classNames?: ProgressClassNames;
+}
+
+export interface ProgressFactoryPayload extends FactoryPayload {
+    props: ProgressProps;
+    ref: HTMLDivElement;
+    compound: {
+        configure: ReturnType<typeof createComponentConfig<ProgressProps>>;
+        classNames: ReturnType<typeof createClassNamesConfig<ProgressClassNames>>;
+    };
+}

package/src/components/progress-circle/index.ts

@@ -0,0 +1,5 @@
+export { default as ProgressCircle } from "./progress-circle";
+export type {
+    ProgressCircleProps,
+    ProgressCircleClassNames
+} from "./progress-circle.types";