@boxcustodia/library 2.0.0-alpha.11 → 2.0.0-alpha.12

package/src/components/popover/popover.tsx

@@ -0,0 +1,203 @@
+"use client";
+
+import { Popover as PopoverPrimitive } from "@base-ui/react/popover";
+import type React from "react";
+import { type ReactNode } from "react";
+import { cn } from "../../lib";
+
+// --- Primitives ---
+
+export const PopoverCreateHandle: typeof PopoverPrimitive.createHandle =
+  PopoverPrimitive.createHandle;
+
+export const PopoverRoot: typeof PopoverPrimitive.Root = PopoverPrimitive.Root;
+
+export function PopoverTrigger({
+  className,
+  children,
+  ...props
+}: PopoverPrimitive.Trigger.Props): React.ReactElement {
+  return (
+    <PopoverPrimitive.Trigger
+      className={className}
+      data-slot="popover-trigger"
+      {...props}
+    >
+      {children}
+    </PopoverPrimitive.Trigger>
+  );
+}
+
+export function PopoverPopup({
+  children,
+  className,
+  side = "bottom",
+  align = "center",
+  sideOffset = 4,
+  alignOffset = 0,
+  tooltipStyle = false,
+  matchTriggerWidth = false,
+  anchor,
+  portalProps,
+  ...props
+}: PopoverPrimitive.Popup.Props & {
+  portalProps?: PopoverPrimitive.Portal.Props;
+  side?: PopoverPrimitive.Positioner.Props["side"];
+  align?: PopoverPrimitive.Positioner.Props["align"];
+  sideOffset?: PopoverPrimitive.Positioner.Props["sideOffset"];
+  alignOffset?: PopoverPrimitive.Positioner.Props["alignOffset"];
+  tooltipStyle?: boolean;
+  matchTriggerWidth?: boolean;
+  anchor?: PopoverPrimitive.Positioner.Props["anchor"];
+}): React.ReactElement {
+  return (
+    <PopoverPrimitive.Portal {...portalProps}>
+      <PopoverPrimitive.Positioner
+        align={align}
+        alignOffset={alignOffset}
+        anchor={anchor}
+        className="z-50 h-(--positioner-height) w-(--positioner-width) max-w-(--available-width) transition-[top,left,right,bottom,transform] data-instant:transition-none"
+        data-slot="popover-positioner"
+        side={side}
+        sideOffset={sideOffset}
+        style={matchTriggerWidth ? { width: "var(--anchor-width)" } : undefined}
+      >
+        <PopoverPrimitive.Popup
+          className={cn(
+            "relative flex h-(--popup-height,auto) origin-(--transform-origin) rounded-lg border bg-popover not-dark:bg-clip-padding text-popover-foreground shadow-lg/5 outline-none transition-[width,height,scale,opacity] before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-lg)-1px)] before:shadow-[0_1px_--theme(--color-black/4%)] has-data-[slot=calendar]:rounded-xl has-data-[slot=calendar]:before:rounded-[calc(var(--radius-xl)-1px)] data-starting-style:scale-98 data-starting-style:opacity-0 dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
+            matchTriggerWidth ? "w-full" : "w-(--popup-width,auto) max-w-72",
+            tooltipStyle &&
+              "w-fit text-balance rounded-md text-xs shadow-md/5 before:rounded-[calc(var(--radius-md)-1px)]",
+            className,
+          )}
+          data-slot="popover-popup"
+          {...props}
+        >
+          <PopoverPrimitive.Viewport
+            className={cn(
+              "relative size-full max-h-(--available-height) overflow-clip px-(--viewport-inline-padding) py-4 [--viewport-inline-padding:--spacing(4)] has-data-[slot=calendar]:p-2 data-instant:transition-none **:data-current:data-ending-style:opacity-0 **:data-current:data-starting-style:opacity-0 **:data-previous:data-ending-style:opacity-0 **:data-previous:data-starting-style:opacity-0 **:data-current:w-[calc(var(--popup-width)-2*var(--viewport-inline-padding)-2px)] **:data-previous:w-[calc(var(--popup-width)-2*var(--viewport-inline-padding)-2px)] **:data-current:opacity-100 **:data-previous:opacity-100 **:data-current:transition-opacity **:data-previous:transition-opacity",
+              tooltipStyle
+                ? "py-1 [--viewport-inline-padding:--spacing(2)]"
+                : "not-data-transitioning:overflow-y-auto",
+            )}
+            data-slot="popover-viewport"
+          >
+            {children}
+          </PopoverPrimitive.Viewport>
+        </PopoverPrimitive.Popup>
+      </PopoverPrimitive.Positioner>
+    </PopoverPrimitive.Portal>
+  );
+}
+
+export function PopoverClose({
+  ...props
+}: PopoverPrimitive.Close.Props): React.ReactElement {
+  return <PopoverPrimitive.Close data-slot="popover-close" {...props} />;
+}
+
+export function PopoverTitle({
+  className,
+  ...props
+}: PopoverPrimitive.Title.Props): React.ReactElement {
+  return (
+    <PopoverPrimitive.Title
+      className={cn("font-semibold text-lg leading-none", className)}
+      data-slot="popover-title"
+      {...props}
+    />
+  );
+}
+
+export function PopoverDescription({
+  className,
+  ...props
+}: PopoverPrimitive.Description.Props): React.ReactElement {
+  return (
+    <PopoverPrimitive.Description
+      className={cn("text-muted-foreground text-sm", className)}
+      data-slot="popover-description"
+      {...props}
+    />
+  );
+}
+
+export { PopoverPrimitive, PopoverPopup as PopoverContent };
+
+// --- Composite ---
+
+type PopoverPopupOverrideProps = Omit<
+  React.ComponentPropsWithoutRef<typeof PopoverPopup>,
+  | "children"
+  | "side"
+  | "align"
+  | "sideOffset"
+  | "alignOffset"
+  | "tooltipStyle"
+  | "matchTriggerWidth"
+  | "anchor"
+>;
+
+interface PopoverProps extends Omit<PopoverPrimitive.Root.Props, "children"> {
+  trigger?: React.ReactElement;
+  children: ReactNode;
+  title?: ReactNode;
+  description?: ReactNode;
+  side?: PopoverPrimitive.Positioner.Props["side"];
+  align?: PopoverPrimitive.Positioner.Props["align"];
+  sideOffset?: PopoverPrimitive.Positioner.Props["sideOffset"];
+  alignOffset?: PopoverPrimitive.Positioner.Props["alignOffset"];
+  tooltipStyle?: boolean;
+  matchTriggerWidth?: boolean;
+  anchor?: PopoverPrimitive.Positioner.Props["anchor"];
+  popupClassName?: string;
+  triggerProps?: Omit<PopoverPrimitive.Trigger.Props, "render" | "children">;
+  popupProps?: PopoverPopupOverrideProps;
+}
+
+export function Popover({
+  trigger,
+  children,
+  title,
+  description,
+  side,
+  align,
+  sideOffset,
+  alignOffset,
+  tooltipStyle,
+  matchTriggerWidth,
+  anchor,
+  popupClassName,
+  triggerProps,
+  popupProps,
+  ...rootProps
+}: PopoverProps): React.ReactElement {
+  return (
+    <PopoverRoot {...rootProps}>
+      {trigger !== undefined && (
+        <PopoverTrigger render={trigger} {...triggerProps} />
+      )}
+      <PopoverPopup
+        {...popupProps}
+        side={side}
+        align={align}
+        sideOffset={sideOffset}
+        alignOffset={alignOffset}
+        tooltipStyle={tooltipStyle}
+        matchTriggerWidth={matchTriggerWidth}
+        anchor={anchor}
+        className={cn(popupProps?.className, popupClassName)}
+      >
+        {(title ?? description) && (
+          <div className="mb-2">
+            {title && <PopoverTitle>{title}</PopoverTitle>}
+            {description && (
+              <PopoverDescription>{description}</PopoverDescription>
+            )}
+          </div>
+        )}
+        {children}
+      </PopoverPopup>
+    </PopoverRoot>
+  );
+}

package/src/components/progress/index.ts

@@ -0,0 +1 @@
+export * from "./progress";

package/src/components/progress/progress.stories.tsx

@@ -0,0 +1,124 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useEffect, useState } from "react";
+import {
+  Progress,
+  ProgressIndicator,
+  ProgressLabel,
+  ProgressRoot,
+  ProgressTrack,
+  ProgressValue,
+} from "../../components";
+
+/**
+ * Progress bar built on Base UI. Renders a filled track that scales with
+ * `value` (0–100, or `null` for indeterminate). Supports `size` for track
+ * height and `variant` for indicator color. Use `ProgressRoot`, `ProgressTrack`,
+ * `ProgressIndicator`, `ProgressLabel`, and `ProgressValue` for full composition control.
+ */
+const meta: Meta<typeof Progress> = {
+  title: "Components/Progress",
+  component: Progress,
+  args: {
+    value: 60,
+    "aria-label": "Loading",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Progress>;
+
+export const Default: Story = {};
+
+export const Animated: Story = {
+  render: () => {
+    const [value, setValue] = useState(0);
+    const [status, setStatus] = useState<"loading" | "complete">("loading");
+
+    useEffect(() => {
+      if (status === "complete") {
+        const timeout = setTimeout(() => {
+          setValue(0);
+          setStatus("loading");
+        }, 2000);
+        return () => clearTimeout(timeout);
+      }
+
+      const interval = setInterval(() => {
+        setValue((prev) => {
+          const next = Math.min(100, prev + Math.floor(Math.random() * 20) + 5);
+          if (next === 100) setStatus("complete");
+          return next;
+        });
+      }, 800);
+
+      return () => clearInterval(interval);
+    }, [status]);
+
+    return (
+      <ProgressRoot value={value} className="w-80">
+        <div className="flex items-center justify-between">
+          <ProgressLabel>
+            {status === "complete" ? "Upload complete" : "Uploading files..."}
+          </ProgressLabel>
+          <ProgressValue />
+        </div>
+        <ProgressTrack>
+          <ProgressIndicator
+            variant={status === "complete" ? "success" : "default"}
+          />
+        </ProgressTrack>
+      </ProgressRoot>
+    );
+  },
+};
+
+export const Sizes: Story = {
+  render: (args) => (
+    <div className="flex w-80 flex-col gap-4">
+      <Progress {...args} size="sm" />
+      <Progress {...args} size="md" />
+      <Progress {...args} size="lg" />
+    </div>
+  ),
+};
+
+export const Success: Story = {
+  args: { variant: "success" },
+};
+
+export const Error: Story = {
+  args: { variant: "error" },
+};
+
+/**
+ * Combine `ProgressLabel` and `ProgressValue` with `ProgressTrack` inside
+ * `ProgressRoot` for labeled progress bars. `ProgressValue` renders the
+ * current value as formatted text using the `getAriaValueText` render prop.
+ */
+export const WithLabel: Story = {
+  render: (args) => (
+    <ProgressRoot value={args.value} className="w-80">
+      <div className="flex justify-between">
+        <ProgressLabel>Uploading files</ProgressLabel>
+        <ProgressValue />
+      </div>
+      <ProgressTrack>
+        <ProgressIndicator />
+      </ProgressTrack>
+    </ProgressRoot>
+  ),
+};
+
+/**
+ * Use `ProgressRoot`, `ProgressTrack`, and `ProgressIndicator` directly
+ * for layouts that need full control over composition.
+ */
+export const Primitive: Story = {
+  render: () => (
+    <ProgressRoot value={40} className="w-80">
+      <ProgressTrack size="lg">
+        <ProgressIndicator variant="success" />
+      </ProgressTrack>
+    </ProgressRoot>
+  ),
+};

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

@@ -0,0 +1,25 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Progress } from "../../components";
+
+describe("Progress component", () => {
+  it("renders a progressbar", () => {
+    render(<Progress value={50} aria-label="Loading" />);
+    expect(screen.getByRole("progressbar")).toBeTruthy();
+  });
+
+  it("exposes the current value via aria-valuenow", () => {
+    render(<Progress value={75} aria-label="Loading" />);
+    expect(screen.getByRole("progressbar")).toHaveAttribute(
+      "aria-valuenow",
+      "75",
+    );
+  });
+
+  it("renders as indeterminate when value is null", () => {
+    render(<Progress value={null} aria-label="Loading" />);
+    expect(screen.getByRole("progressbar").hasAttribute("aria-valuenow")).toBe(
+      false,
+    );
+  });
+});

package/src/components/progress/progress.tsx

@@ -0,0 +1,124 @@
+import { Progress as ProgressPrimitive } from "@base-ui/react/progress";
+import { cva, type VariantProps } from "class-variance-authority";
+import type * as React from "react";
+import { cn } from "../../lib";
+
+const progressTrackVariants = cva(
+  "block w-full overflow-hidden rounded-full bg-input",
+  {
+    variants: {
+      size: {
+        sm: "h-1",
+        md: "h-1.5",
+        lg: "h-2.5",
+      },
+    },
+    defaultVariants: { size: "md" },
+  },
+);
+
+const progressIndicatorVariants = cva("transition-all duration-500", {
+  variants: {
+    variant: {
+      default: "bg-primary",
+      success: "bg-success",
+      error: "bg-error",
+      warning: "bg-warning",
+      info: "bg-info",
+    },
+  },
+  defaultVariants: { variant: "default" },
+});
+
+export function ProgressRoot({
+  className,
+  ...props
+}: ProgressPrimitive.Root.Props): React.ReactElement {
+  return (
+    <ProgressPrimitive.Root
+      className={cn("flex w-full flex-col gap-2", className)}
+      data-slot="progress"
+      {...props}
+    />
+  );
+}
+
+export function ProgressLabel({
+  className,
+  ...props
+}: ProgressPrimitive.Label.Props): React.ReactElement {
+  return (
+    <ProgressPrimitive.Label
+      className={cn("font-medium text-sm", className)}
+      data-slot="progress-label"
+      {...props}
+    />
+  );
+}
+
+export function ProgressTrack({
+  className,
+  size,
+  ...props
+}: ProgressPrimitive.Track.Props &
+  VariantProps<typeof progressTrackVariants>): React.ReactElement {
+  return (
+    <ProgressPrimitive.Track
+      className={cn(progressTrackVariants({ size }), className)}
+      data-slot="progress-track"
+      {...props}
+    />
+  );
+}
+
+export function ProgressIndicator({
+  className,
+  variant,
+  ...props
+}: ProgressPrimitive.Indicator.Props &
+  VariantProps<typeof progressIndicatorVariants>): React.ReactElement {
+  return (
+    <ProgressPrimitive.Indicator
+      className={cn(progressIndicatorVariants({ variant }), className)}
+      data-slot="progress-indicator"
+      {...props}
+    />
+  );
+}
+
+export function ProgressValue({
+  className,
+  ...props
+}: ProgressPrimitive.Value.Props): React.ReactElement {
+  return (
+    <ProgressPrimitive.Value
+      className={cn("text-sm tabular-nums", className)}
+      data-slot="progress-value"
+      {...props}
+    />
+  );
+}
+
+interface ProgressProps extends Omit<ProgressPrimitive.Root.Props, "children"> {
+  size?: VariantProps<typeof progressTrackVariants>["size"];
+  variant?: VariantProps<typeof progressIndicatorVariants>["variant"];
+  trackProps?: ProgressPrimitive.Track.Props;
+  indicatorProps?: ProgressPrimitive.Indicator.Props;
+}
+
+export function Progress({
+  size,
+  variant,
+  className,
+  trackProps,
+  indicatorProps,
+  ...props
+}: ProgressProps): React.ReactElement {
+  return (
+    <ProgressRoot className={className} {...props}>
+      <ProgressTrack size={size} {...trackProps}>
+        <ProgressIndicator variant={variant} {...indicatorProps} />
+      </ProgressTrack>
+    </ProgressRoot>
+  );
+}

package/src/components/scroll-area/index.ts

@@ -0,0 +1 @@
+export * from "./scroll-area.tsx";

package/src/components/scroll-area/scroll-area.stories.tsx

@@ -0,0 +1,166 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { ScrollArea, ScrollAreaPrimitive, ScrollBar } from "./scroll-area";
+
+const verticalItems = Array.from({ length: 24 }, (_, index) => ({
+  id: index + 1,
+  label: `Item ${index + 1}`,
+  description: `Scrollable content row ${index + 1}.`,
+}));
+
+const horizontalItems = Array.from({ length: 18 }, (_, index) => ({
+  id: index + 1,
+  label: `Column ${index + 1}`,
+}));
+
+/**
+ * Native scroll container built on Base UI with custom scrollbar styling.
+ *
+ * `scrollFade` uses viewport edge masks tied to overflow variables, so the fade
+ * appears only where more content exists. `scrollbarGutter` reserves room in
+ * the viewport to avoid layout shifts when overflow state toggles.
+ *
+ * Reference: [Scroll Area - Base UI](https://base-ui.com/react/components/scroll-area.md)
+ */
+const meta: Meta<typeof ScrollArea> = {
+  title: "Components/Scroll Area",
+  component: ScrollArea,
+  parameters: { layout: "centered" },
+  args: {
+    className: "h-72 w-96 rounded-md border",
+  },
+  argTypes: {
+    children: { control: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ScrollArea>;
+
+export const Default: Story = {
+  render: (args) => (
+    <ScrollArea {...args}>
+      <div className="space-y-3 p-4">
+        {verticalItems.map((item) => (
+          <div key={item.id} className="rounded-md border bg-background p-3">
+            <p className="text-sm font-medium">{item.label}</p>
+            <p className="text-sm text-muted-foreground">{item.description}</p>
+          </div>
+        ))}
+      </div>
+    </ScrollArea>
+  ),
+};
+
+/**
+ * `scrollFade` masks each viewport edge based on current overflow values.
+ * The fade appears only on edges where hidden content remains.
+ */
+export const ScrollFade: Story = {
+  args: {
+    scrollFade: true,
+  },
+  render: (args) => (
+    <ScrollArea {...args}>
+      <div className="space-y-3 p-4">
+        {verticalItems.map((item) => (
+          <div key={item.id} className="rounded-md border bg-background p-3">
+            <p className="text-sm font-medium">{item.label}</p>
+            <p className="text-sm text-muted-foreground">{item.description}</p>
+          </div>
+        ))}
+      </div>
+    </ScrollArea>
+  ),
+};
+
+export const HorizontalScroll: Story = {
+  render: (args) => (
+    <ScrollArea {...args} className="h-44 w-96 rounded-md border">
+      <div className="flex w-max gap-3 p-4 h-full">
+        {horizontalItems.map((item) => (
+          <div
+            key={item.id}
+            className="flex w-32 shrink-0 items-center justify-center rounded-md border bg-muted text-sm font-medium"
+          >
+            {item.label}
+          </div>
+        ))}
+      </div>
+    </ScrollArea>
+  ),
+};
+
+/**
+ * `scrollbarGutter` keeps consistent content padding when scrollbars appear.
+ * This prevents text and cards from shifting as overflow transitions.
+ */
+export const ScrollbarGutter: Story = {
+  args: {
+    scrollbarGutter: true,
+  },
+  render: (args) => (
+    <ScrollArea {...args}>
+      {verticalItems.map((item) => (
+        <div key={item.id} className="rounded-md border bg-background p-3 m-1">
+          <p className="text-sm font-medium">{item.label}</p>
+          <p className="text-sm text-muted-foreground">{item.description}</p>
+        </div>
+      ))}
+    </ScrollArea>
+  ),
+};
+
+export const BothScrollbars: Story = {
+  render: (args) => (
+    <ScrollArea {...args} className="h-64 w-96 rounded-md border">
+      <div className="w-3xl space-y-3 p-4">
+        {verticalItems.map((item) => (
+          <div
+            key={item.id}
+            className="flex items-center justify-between rounded-md border bg-background p-3"
+          >
+            <p className="text-sm font-medium">{item.label}</p>
+            <p className="text-sm text-muted-foreground">
+              Extra content width for horizontal overflow
+            </p>
+          </div>
+        ))}
+      </div>
+    </ScrollArea>
+  ),
+};
+
+/**
+ * Direct composition with Base UI primitives for full structural control.
+ * Useful when the composite wrapper is not enough for custom subtree order.
+ *
+ * ```tsx
+ * <ScrollAreaPrimitive.Root>
+ *   <ScrollAreaPrimitive.Viewport>{children}</ScrollAreaPrimitive.Viewport>
+ *   <ScrollBar orientation="vertical" />
+ *   <ScrollBar orientation="horizontal" />
+ *   <ScrollAreaPrimitive.Corner />
+ * </ScrollAreaPrimitive.Root>
+ * ```
+ */
+export const Primitive: Story = {
+  render: () => (
+    <ScrollAreaPrimitive.Root className="h-72 w-96 rounded-md border">
+      <ScrollAreaPrimitive.Viewport className="h-full rounded-[inherit] p-4">
+        <div className="space-y-3">
+          {verticalItems.map((item) => (
+            <div key={item.id} className="rounded-md border bg-background p-3">
+              <p className="text-sm font-medium">{item.label}</p>
+              <p className="text-sm text-muted-foreground">
+                {item.description}
+              </p>
+            </div>
+          ))}
+        </div>
+      </ScrollAreaPrimitive.Viewport>
+      <ScrollBar orientation="vertical" />
+      <ScrollBar orientation="horizontal" />
+      <ScrollAreaPrimitive.Corner />
+    </ScrollAreaPrimitive.Root>
+  ),
+};