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

package/src/components/heading/heading.tsx

@@ -0,0 +1,28 @@
+import { VariantProps } from "class-variance-authority";
+import { cn } from "../../lib";
+import { HeadingVariants } from "./heading.variants";
+
+type Props<C extends React.ElementType> = VariantProps<
+  typeof HeadingVariants
+> & {
+  as?: C;
+} & Omit<React.ComponentPropsWithoutRef<C>, "as">;
+
+export const Heading = <C extends React.ElementType = "h2">({
+  className,
+  size,
+  weight,
+  as,
+  ...props
+}: Props<C>) => {
+  const Comp = as || "h2";
+  return (
+    <Comp
+      className={cn(HeadingVariants({ size, weight }), className)}
+      {...props}
+      data-slot="heading"
+      data-size={size}
+      data-weight={weight}
+    />
+  );
+};

package/src/components/heading/heading.variants.ts

@@ -0,0 +1,27 @@
+import { cva } from "class-variance-authority";
+
+export const HeadingVariants = cva([], {
+  variants: {
+    size: {
+      sm: "text-[14px]",
+      md: "text-[16px]",
+      lg: "text-[18px]",
+      xl: "text-[20px]",
+      "2xl": "text-[24px]",
+      "3xl": "text-[28px]",
+      "4xl": "text-[32px]",
+      "5xl": "text-[36px]",
+      "6xl": "text-[40px]",
+    },
+    weight: {
+      normal: "font-normal",
+      medium: "font-medium",
+      semibold: "font-semibold",
+      bold: "font-bold",
+    },
+  },
+  defaultVariants: {
+    size: "xl",
+    weight: "semibold",
+  },
+});

package/src/components/heading/index.ts

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

package/src/components/index.ts

@@ -0,0 +1,46 @@
+export * from "./alert-dialog";
+export * from "./auto-complete";
+export * from "./avatar";
+export * from "./background-image";
+export * from "./button";
+export * from "./calendar";
+export * from "./card";
+export * from "./center";
+export * from "./checkbox";
+export * from "./checkbox-group";
+export * from "./combobox";
+export * from "./date-picker";
+export * from "./dialog";
+export * from "./divider";
+export * from "./dropzone";
+export * from "./empty-state";
+export * from "./field";
+export * from "./form";
+export * from "./heading";
+export * from "./input";
+export * from "./kbd";
+export * from "./label";
+export * from "./loader";
+export * from "./menu";
+export * from "./multi-select";
+export * from "./number-input";
+export * from "./pagination";
+export * from "./password";
+export * from "./popover";
+export * from "./progress";
+export * from "./scroll-area";
+export * from "./select";
+export * from "./show";
+export * from "./skeleton";
+export * from "./stack";
+export * from "./stepper";
+export * from "./switch";
+export * from "./table";
+export * from "./table-pagination";
+export * from "./tabs";
+export * from "./tag";
+export * from "./textarea";
+export * from "./timeline";
+export * from "./toast";
+export * from "./tooltip";
+export * from "./tree";

package/src/components/input/index.ts

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

package/src/components/input/input.stories.tsx

@@ -0,0 +1,104 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Input, InputPrimitive } from "./input";
+
+/**
+ * Single-line text input built on Base UI. Styles applied directly to the
+ * `<input>` element — no wrapper. `aria-invalid` drives error styling;
+ * `nativeInput` swaps Base UI for a plain `<input>`.
+ */
+const meta: Meta<typeof Input> = {
+  title: "Components/Input",
+  component: Input,
+  parameters: { layout: "centered" },
+  args: {
+    placeholder: "Placeholder...",
+  },
+  argTypes: {
+    onChange: { control: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Input>;
+
+export const Default: Story = {};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+};
+
+/**
+ * `aria-invalid="true"` applies error border and ring — no Field wrapper needed.
+ */
+export const Invalid: Story = {
+  args: { "aria-invalid": "true" },
+};
+
+/**
+ * Hides browser spinner arrows via webkit pseudo-elements and `-moz-appearance`.
+ */
+export const NumberType: Story = {
+  args: { type: "number", placeholder: "0" },
+};
+
+/**
+ * Hides webkit search decoration buttons injected by the browser.
+ */
+export const SearchType: Story = {
+  args: { type: "search", placeholder: "Search..." },
+};
+
+/**
+ * Applies `file:` variant styles — font, spacing, and transparent background
+ * on the browser's file-picker button.
+ */
+export const FileType: Story = {
+  args: { type: "file" },
+};
+
+/**
+ * `onChange` fires with `(value: string, event)` — the string value is the first argument,
+ * so no `event.target.value` needed.
+ */
+export const Controlled: Story = {
+  render: () => {
+    const [value, setValue] = useState("");
+    return (
+      <div className="flex flex-col gap-2">
+        <Input
+          value={value}
+          onChange={setValue}
+          placeholder="Type something..."
+          aria-label="Controlled input"
+        />
+        <span className="text-sm text-muted-foreground">Value: "{value}"</span>
+      </div>
+    );
+  },
+};
+
+/**
+ * `nativeInput` swaps Base UI for a plain `<input>`. Identical appearance —
+ * use when you need native input APIs without Base UI overhead.
+ */
+export const NativeInput: Story = {
+  args: { nativeInput: true },
+};
+
+/**
+ * Raw Base UI Input with no styles applied. Use when you need Base UI's field
+ * context wiring with full style control.
+ *
+ * ```tsx
+ * <InputPrimitive className="..." />
+ * ```
+ */
+export const Primitive: Story = {
+  render: () => (
+    <InputPrimitive
+      className="w-full rounded-md border border-input px-3 py-2 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+      placeholder="Raw Base UI Input"
+    />
+  ),
+};

package/src/components/input/input.tsx

@@ -0,0 +1,75 @@
+import { Input as BaseInput } from "@base-ui/react/input";
+import { type ChangeEvent, type ComponentPropsWithoutRef } from "react";
+import { cn } from "../../lib";
+
+export const inputBaseClasses =
+  "h-10 w-full px-3 py-2 rounded-md border border-input bg-background text-sm outline-none transition-shadow placeholder:text-muted-foreground";
+
+// ── Composite ─────────────────────────────────────────────────────────────────
+
+export type InputProps = Omit<BaseInput.Props, "size" | "onChange"> & {
+  onChange?: (value: string, event: ChangeEvent<HTMLInputElement>) => void;
+  nativeInput?: boolean;
+};
+
+export function Input({
+  className,
+  nativeInput = false,
+  onChange,
+  ...props
+}: InputProps) {
+  const classes = cn(
+    inputBaseClasses,
+    "focus-visible:border-ring",
+    "aria-invalid:border-error focus-visible:aria-invalid:ring-error/20",
+    "has-aria-invalid:border-error has-focus-visible:has-aria-invalid:ring-error/20",
+    "disabled:cursor-not-allowed disabled:opacity-50",
+    props.type === "number" && [
+      "[&::-webkit-outer-spin-button]:appearance-none",
+      "[&::-webkit-inner-spin-button]:appearance-none",
+      "[-moz-appearance:textfield]",
+    ],
+    props.type === "search" && [
+      "[&::-webkit-search-cancel-button]:appearance-none",
+      "[&::-webkit-search-decoration]:appearance-none",
+      "[&::-webkit-search-results-button]:appearance-none",
+      "[&::-webkit-search-results-decoration]:appearance-none",
+    ],
+    props.type === "file" && [
+      "text-muted-foreground",
+      "file:me-3 file:border-0 file:bg-transparent file:font-medium file:text-foreground file:text-sm",
+    ],
+    className,
+  );
+
+  const handleChange = onChange
+    ? (event: ChangeEvent<HTMLInputElement>) =>
+        onChange(event.target.value, event)
+    : undefined;
+
+  if (nativeInput) {
+    return (
+      <input
+        autoComplete="off"
+        className={classes}
+        data-slot="input"
+        onChange={handleChange}
+        {...(props as ComponentPropsWithoutRef<"input">)}
+      />
+    );
+  }
+
+  return (
+    <BaseInput
+      autoComplete="off"
+      className={classes}
+      data-slot="input"
+      onChange={handleChange}
+      {...props}
+    />
+  );
+}
+
+// ── Primitive escape hatch ────────────────────────────────────────────────────
+
+export { BaseInput as InputPrimitive };

package/src/components/kbd/index.ts

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

package/src/components/kbd/kbd.stories.tsx

@@ -0,0 +1,40 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Kbd, KbdGroup } from "../../components";
+
+/**
+ * Keyboard key representation. Use `KbdGroup` to compose multiple `Kbd` keys
+ * into a combination — no separator needed between them.
+ */
+const meta: Meta<typeof Kbd> = {
+  title: "Components/Kbd",
+  component: Kbd,
+  args: {
+    children: "K",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Kbd>;
+
+export const Default: Story = {};
+
+export const Group: Story = {
+  render: () => (
+    <div className="flex gap-2">
+      <KbdGroup>
+        <Kbd>⌘</Kbd>
+        <Kbd>K</Kbd>
+      </KbdGroup>
+      <KbdGroup>
+        <Kbd>⌘</Kbd>
+        <Kbd>Shift</Kbd>
+        <Kbd>P</Kbd>
+      </KbdGroup>
+      <KbdGroup>
+        <Kbd>Ctrl</Kbd>
+        <Kbd>Alt</Kbd>
+        <Kbd>Delete</Kbd>
+      </KbdGroup>
+    </div>
+  ),
+};

package/src/components/kbd/kbd.tsx

@@ -0,0 +1,31 @@
+import type * as React from "react";
+import { cn } from "../../lib";
+
+export function Kbd({
+  className,
+  ...props
+}: React.ComponentProps<"kbd">): React.ReactElement {
+  return (
+    <kbd
+      className={cn(
+        "pointer-events-none inline-flex h-5 min-w-5 select-none items-center justify-center gap-1 rounded bg-muted px-1 font-medium font-sans text-muted-foreground text-xs [&_svg:not([class*='size-'])]:size-3",
+        className,
+      )}
+      data-slot="kbd"
+      {...props}
+    />
+  );
+}
+
+export function KbdGroup({
+  className,
+  ...props
+}: React.ComponentProps<"kbd">): React.ReactElement {
+  return (
+    <kbd
+      className={cn("inline-flex items-center gap-1", className)}
+      data-slot="kbd-group"
+      {...props}
+    />
+  );
+}

package/src/components/kbd/kbd.variants.ts

@@ -0,0 +1,26 @@
+import { cva } from "class-variance-authority";
+
+export const KbdVariants = cva(
+  [
+    "inline-flex select-none items-center gap-1 rounded border bg-muted px-1.5 font-medium text-muted-foreground",
+  ],
+  {
+    variants: {
+      variant: {
+        default: "border-transparent bg-secondary text-secondary-foreground",
+        secondary: "border-transparent bg-primary text-primary-foreground",
+        error: "border-transparent bg-error text-error-foreground",
+        outline: "text-foreground",
+      },
+      size: {
+        default: "px-1.5 py-0.5 text-xs",
+        sm: "px-2 py-0.5 text-sm",
+        lg: "px-4 py-1 text-lg",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);

package/src/components/label/index.ts

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

package/src/components/label/label.stories.tsx

@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Input, Label } from "../../components";
+
+/**
+ * Semantic `<label>` element for form fields.
+ * Supports the `render` prop for polymorphic rendering.
+ * Pass `tooltip` to render an inline info icon that reveals a tooltip on hover.
+ */
+const meta: Meta<typeof Label> = {
+  title: "Components/Label",
+  component: Label,
+  args: {
+    children: "First name",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Label>;
+
+export const Default: Story = {};
+
+/**
+ * Primary use case: associate a label with a form control via `htmlFor`.
+ * Clicking the label moves focus to the linked input.
+ */
+export const WithInput: Story = {
+  render: (args) => (
+    <div className="flex flex-col gap-2">
+      <Label {...args} htmlFor="name" />
+      <Input id="name" placeholder="Enter your name" />
+    </div>
+  ),
+};
+
+export const Required: Story = {
+  args: {
+    required: true,
+  },
+};
+
+/**
+ * Pass any `ReactNode` as `tooltip` to render an info icon next to the label text.
+ * Hovering the icon shows the tooltip content.
+ */
+export const WithTooltip: Story = {
+  args: {
+    tooltip: "This field is required for billing purposes.",
+  },
+};
+
+/**
+ * The `render` prop replaces the root element while preserving all
+ * merged props and children. Useful for custom wrappers or non-label contexts.
+ */
+export const Render: Story = {
+  render: (args) => (
+    <Label {...args} render={({ children }) => <span>{children}</span>} />
+  ),
+  parameters: {
+    docs: {
+      source: {
+        code: `<Label render={({ children }) => <span>{children}</span>}>
+  First name
+</Label>`,
+      },
+    },
+  },
+};

package/src/components/label/label.test.tsx

@@ -0,0 +1,61 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Label } from "../../components";
+
+describe("Label component", () => {
+  it("should render correctly", () => {
+    render(<Label data-testid="Label" />);
+    const component = screen.getByTestId("Label");
+
+    expect(component).toBeInTheDocument();
+  });
+
+  it("should render as a label element", () => {
+    render(<Label>Text</Label>);
+    const label = screen.getByText("Text");
+
+    expect(label.tagName).toBe("LABEL");
+  });
+
+  it("should render children correctly", () => {
+    render(<Label>First name</Label>);
+
+    expect(screen.getByText("First name")).toBeInTheDocument();
+  });
+
+  it("should have data-slot attribute", () => {
+    render(<Label data-testid="label" />);
+    const label = screen.getByTestId("label");
+
+    expect(label).toHaveAttribute("data-slot", "label");
+  });
+
+  it("should accept className prop", () => {
+    const TEST_CLASS = "custom-label";
+    render(<Label data-testid="label" className={TEST_CLASS} />);
+    const label = screen.getByTestId("label");
+
+    expect(label).toHaveClass(TEST_CLASS);
+  });
+
+  it("should accept htmlFor prop", () => {
+    render(<Label data-testid="label" htmlFor="input-id" />);
+    const label = screen.getByTestId("label");
+
+    expect(label).toHaveAttribute("for", "input-id");
+  });
+
+  it("should render as a different element via render prop", () => {
+    render(
+      <Label
+        render={({ children }) => <span data-testid="label">{children}</span>}
+      >
+        Custom render
+      </Label>,
+    );
+    const label = screen.getByTestId("label");
+
+    expect(label.tagName).toBe("SPAN");
+    expect(label).toHaveTextContent("Custom render");
+  });
+});

package/src/components/label/label.tsx

@@ -0,0 +1,62 @@
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+import { Info } from "lucide-react";
+import type React from "react";
+import { ReactNode } from "react";
+import { cn } from "../../lib";
+import { Tooltip } from "../tooltip";
+
+interface LabelProps extends useRender.ComponentProps<"label"> {
+  required?: boolean;
+  tooltip?: ReactNode;
+}
+
+export function Label({
+  className,
+  render,
+  required,
+  tooltip,
+  children,
+  ...props
+}: LabelProps): React.ReactElement {
+  const content =
+    required || tooltip ? (
+      <>
+        {children}
+        {required && (
+          <span aria-hidden className="text-error">
+            *
+          </span>
+        )}
+        {tooltip && (
+          <Tooltip content={tooltip}>
+            <button
+              type="button"
+              aria-label="More information"
+              className="inline-flex cursor-default items-center text-muted-foreground hover:text-foreground transition-all ml-1"
+            >
+              <Info className="size-3.5" />
+            </button>
+          </Tooltip>
+        )}
+      </>
+    ) : (
+      children
+    );
+
+  const baseProps = {
+    className: cn(
+      "inline-flex items-center font-medium text-sm leading-none",
+      "peer-data-disabled:cursor-not-allowed peer-data-disabled:opacity-70",
+      className,
+    ),
+    "data-slot": "label",
+    children: content,
+  };
+
+  return useRender({
+    defaultTagName: "label",
+    props: mergeProps<"label">(baseProps, props),
+    render,
+  });
+}

package/src/components/loader/index.ts

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

package/src/components/loader/loader.stories.tsx

@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Loader, Stack } from "../../components";
+
+/**
+ * Spinner that signals an in-progress operation. Accepts all native SVG props
+ * via `LucideProps` — use `color`, `strokeWidth`, or `className` for one-off overrides.
+ * `center` positions the loader fixed at the viewport center.
+ */
+const meta: Meta<typeof Loader> = {
+  title: "Components/Loader",
+  component: Loader,
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const Variants: Story = {
+  render: () => (
+    <Stack>
+      <Loader variant="primary" />
+      <Loader variant="secondary" />
+      <Loader variant="ghost" />
+      <Loader variant="error" />
+      <Loader variant="success" />
+    </Stack>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <Stack>
+      <Loader size="xs" />
+      <Loader size="sm" />
+      <Loader size="default" />
+      <Loader size="lg" />
+      <Loader size="xl" />
+    </Stack>
+  ),
+};
+
+/**
+ * `center` uses `fixed inset-0` — it covers the full viewport.
+ * Pair it with a backdrop when used inside a modal or overlay.
+ */
+export const Centered: Story = { args: { center: true } };
+
+/**
+ * `color` and `strokeWidth` come from `LucideProps` and bypass the variant system.
+ * Useful for one-off cases without adding a new variant.
+ */
+export const Custom: Story = {
+  args: {
+    size: "lg",
+    color: "tomato",
+    strokeWidth: 1,
+    className: "duration-200",
+  },
+};

package/src/components/loader/loader.test.tsx

@@ -0,0 +1,26 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Loader } from "../../components";
+
+describe("Loader component", () => {
+  it("should render", () => {
+    render(<Loader data-testid="loader" />);
+
+    const loader = screen.getByTestId("loader");
+    expect(loader).toBeInTheDocument();
+  });
+
+  it("should receive custom styles", () => {
+    render(<Loader color="red" data-testid="loader" />);
+
+    const loader = screen.getByTestId("loader");
+    expect(loader).toHaveAttribute("stroke", "red");
+  });
+
+  it("should receive custom size", () => {
+    render(<Loader size="lg" data-testid="loader" />);
+
+    const loader = screen.getByTestId("loader");
+    expect(loader).toHaveClass("w-10 h-10");
+  });
+});