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

package/src/components/skeleton/skeleton.stories.tsx

@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Skeleton } from "./skeleton";
+
+/**
+ * Loading placeholder that fills the space of the expected content.
+ * Fully composable — apply size, shape, and spacing directly via `className`.
+ * Conditionally render it yourself; `Skeleton` does not manage loading state.
+ */
+const meta: Meta<typeof Skeleton> = {
+  title: "Components/Skeleton",
+  component: Skeleton,
+  args: {
+    className: "h-4 w-[200px]",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/**
+ * Compose multiple skeletons to sketch the loading state of a complex layout.
+ * Each skeleton maps 1:1 to a piece of real content it replaces.
+ */
+export const Composition: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <Skeleton className="size-10 shrink-0 rounded-full" />
+      <div className="flex flex-col gap-2">
+        <Skeleton className="h-4 w-[150px]" />
+        <Skeleton className="h-4 w-[100px]" />
+      </div>
+    </div>
+  ),
+};

package/src/components/skeleton/skeleton.test.tsx

@@ -0,0 +1,14 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Skeleton } from "../../components";
+
+describe("Skeleton component", () => {
+  const testId = "skeleton";
+
+  it("should render correctly", () => {
+    render(<Skeleton data-testid={testId} />);
+    const skeleton = screen.getByTestId(testId);
+
+    expect(skeleton).toBeInTheDocument();
+  });
+});

package/src/components/skeleton/skeleton.tsx

@@ -0,0 +1,15 @@
+import type { ComponentProps } from "react";
+import { cn } from "../../lib";
+
+export function Skeleton({ className, ...props }: ComponentProps<"div">) {
+  return (
+    <div
+      className={cn(
+        "animate-skeleton rounded-sm [--skeleton-highlight:--alpha(var(--color-white)/64%)] [background:linear-gradient(120deg,transparent_40%,var(--skeleton-highlight),transparent_60%)_var(--color-muted)_0_0/200%_100%_fixed] dark:[--skeleton-highlight:--alpha(var(--color-white)/4%)]",
+        className,
+      )}
+      data-slot="skeleton"
+      {...props}
+    />
+  );
+}

package/src/components/stack/index.ts

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

package/src/components/stack/stack.stories.tsx

@@ -0,0 +1,194 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Avatar } from "../avatar";
+import { Button } from "../button";
+import { Input } from "../input";
+import { Label } from "../label";
+import { Stack } from ".";
+
+/**
+ * Layout primitive that composes children along a horizontal or vertical axis using flexbox.
+ * Supports polymorphic rendering via `as` for semantic HTML (ul, nav, section, etc.).
+ * `reverse` inverts the flex direction without exposing raw CSS values.
+ * `grow` makes the container fill available space (`flex: 1`).
+ */
+const meta: Meta<typeof Stack> = {
+  title: "Components/Stack",
+  component: Stack,
+  args: {
+    gap: 8,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Stack>;
+
+export const Default: Story = {
+  args: {
+    align: "center",
+  },
+  render: (args) => (
+    <Stack {...args}>
+      <Avatar src="https://i.pravatar.cc/150?img=12" alt="Sara Lane" />
+      <span className="font-semibold text-lg">Sara Lane</span>
+    </Stack>
+  ),
+};
+
+export const Vertical: Story = {
+  args: {
+    direction: "vertical",
+  },
+  render: (args) => (
+    <Stack {...args}>
+      <Label>Username</Label>
+      <Input type="text" placeholder="Enter your username" />
+    </Stack>
+  ),
+};
+
+/**
+ * `reverse` flips the axis direction without needing to know the underlying CSS value
+ * (`row-reverse` or `column-reverse`).
+ */
+export const Reverse: Story = {
+  render: () => (
+    <Stack direction="vertical" gap={16}>
+      <Stack align="center" gap={8}>
+        <span className="text-sm text-muted-foreground w-24">horizontal</span>
+        <Stack gap={8}>
+          <Button>First</Button>
+          <Button variant="secondary">Second</Button>
+          <Button variant="outline">Third</Button>
+        </Stack>
+      </Stack>
+      <Stack align="center" gap={8}>
+        <span className="text-sm text-muted-foreground w-24">reverse</span>
+        <Stack reverse gap={8}>
+          <Button>First</Button>
+          <Button variant="secondary">Second</Button>
+          <Button variant="outline">Third</Button>
+        </Stack>
+      </Stack>
+    </Stack>
+  ),
+};
+
+/**
+ * `wrap` enables `flex-wrap` so children overflow onto the next line instead of shrinking.
+ * Useful for tag lists, badge groups, and responsive card grids.
+ */
+export const Wrap: Story = {
+  render: () => (
+    <Stack wrap="wrap" gap={8} className="max-w-[300px]">
+      {Array.from({ length: 10 }, (_, i) => (
+        <Button key={i} variant="outline" size="sm">
+          Tag {i + 1}
+        </Button>
+      ))}
+    </Stack>
+  ),
+};
+
+/**
+ * `grow` applies `flex: 1` to the Stack, making it fill the remaining space of its parent.
+ * Useful for sidebars, split panes, and full-height layouts.
+ */
+export const Grow: Story = {
+  render: () => (
+    <Stack className="h-[120px] border rounded p-2">
+      <div className="w-16 bg-muted rounded flex items-center justify-center text-xs">
+        Fixed
+      </div>
+      <Stack
+        grow
+        direction="vertical"
+        gap={4}
+        className="bg-muted/40 rounded p-2"
+      >
+        <span className="text-xs font-medium">Grows to fill</span>
+        <span className="text-xs text-muted-foreground">flex: 1</span>
+      </Stack>
+    </Stack>
+  ),
+};
+
+/**
+ * `as` renders the Stack as a different HTML element for semantic markup.
+ * Children of a `ul` stack should be `li` elements.
+ */
+export const As: Story = {
+  render: () => (
+    <Stack as="ul" direction="vertical" gap={4} className="list-none p-0 m-0">
+      <li>Item one</li>
+      <li>Item two</li>
+      <li>Item three</li>
+    </Stack>
+  ),
+};
+
+export const Justify: Story = {
+  render: () => (
+    <Stack direction="vertical" gap={12}>
+      {(
+        [
+          "flex-start",
+          "center",
+          "flex-end",
+          "space-between",
+          "space-evenly",
+        ] as const
+      ).map((value) => (
+        <Stack key={value} direction="vertical" gap={4}>
+          <span className="text-xs text-muted-foreground">{value}</span>
+          <Stack justify={value} className="border rounded p-2">
+            <Button size="sm">A</Button>
+            <Button size="sm" variant="secondary">
+              B
+            </Button>
+          </Stack>
+        </Stack>
+      ))}
+    </Stack>
+  ),
+};
+
+export const Align: Story = {
+  render: () => (
+    <Stack direction="vertical" gap={12} className="w-fit">
+      {(["flex-start", "center", "flex-end"] as const).map((value) => (
+        <Stack key={value} direction="vertical" gap={4}>
+          <span className="text-xs text-muted-foreground">{value}</span>
+          <Stack align={value} className="border rounded p-2 h-20">
+            <Button size="sm">A</Button>
+            <Button size="sm" variant="secondary">
+              B
+            </Button>
+          </Stack>
+        </Stack>
+      ))}
+    </Stack>
+  ),
+};
+
+export const Nested: Story = {
+  args: {
+    align: "center",
+    gap: 16,
+  },
+  render: (args) => (
+    <Stack {...args}>
+      <Avatar
+        className="w-16 h-16"
+        src="https://i.pravatar.cc/150?img=12"
+        alt="Sara Lane"
+      />
+      <Stack direction="vertical" gap={4}>
+        <span className="font-semibold text-lg">Sara Lane</span>
+        <span className="text-sm text-muted-foreground max-w-[360px]">
+          Senior product designer with 8 years of experience building design
+          systems and component libraries for cross-functional teams.
+        </span>
+      </Stack>
+    </Stack>
+  ),
+};

package/src/components/stack/stack.tsx

@@ -0,0 +1,52 @@
+import { ComponentProps, CSSProperties, ElementType } from "react";
+import { cn } from "../../lib";
+
+interface StackProps extends ComponentProps<"div"> {
+  as?: ElementType;
+  inline?: boolean;
+  direction?: "horizontal" | "vertical";
+  reverse?: boolean;
+  justify?: CSSProperties["justifyContent"];
+  align?: CSSProperties["alignItems"];
+  gap?: CSSProperties["gap"];
+  wrap?: CSSProperties["flexWrap"];
+  grow?: boolean;
+}
+
+export const Stack = ({
+  as: Tag = "div",
+  inline = false,
+  direction = "horizontal",
+  reverse = false,
+  justify,
+  align,
+  gap = 8,
+  wrap,
+  grow = false,
+  className,
+  style,
+  ...props
+}: StackProps) => {
+  const flexDirection =
+    `${direction === "vertical" ? "column" : "row"}${reverse ? "-reverse" : ""}` as CSSProperties["flexDirection"];
+
+  return (
+    <Tag
+      className={cn(
+        inline ? "inline-flex" : "flex",
+        grow && "flex-1",
+        className,
+      )}
+      style={{
+        flexDirection,
+        justifyContent: justify,
+        alignItems: align,
+        gap,
+        flexWrap: wrap,
+        ...style,
+      }}
+      data-slot="stack"
+      {...props}
+    />
+  );
+};

package/src/components/stepper/Stepper.tsx

@@ -0,0 +1,190 @@
+import { useControllableState } from "@radix-ui/react-use-controllable-state";
+import { HTMLProps, ReactNode } from "react";
+import { ClassNameValue } from "tailwind-merge";
+import { ClassName } from "@/models";
+import { cn } from "../../lib";
+import {
+  StepperContextProvider,
+  useStepperContext,
+} from "./context/stepper-context";
+
+interface StepperItemProps {
+  indicator?: ReactNode;
+  title: ReactNode;
+  content?: ReactNode;
+  disabled?: boolean;
+}
+
+interface StepperProps extends Omit<HTMLProps<HTMLDivElement>, "onChange"> {
+  items?: StepperItemProps[];
+  current?: number;
+  onChange?: (index: number) => void;
+  className?: ClassName;
+  classNameList?: ClassName;
+  classNameItem?: ClassName;
+  classNameButton?: ClassName;
+  classNameIndicator?: ClassName;
+  classNameContent?: ClassName;
+}
+export function Stepper({
+  items = [],
+  current,
+  onChange,
+  className,
+  classNameList,
+  classNameItem,
+  classNameButton,
+  classNameIndicator,
+  classNameContent,
+}: StepperProps) {
+  return (
+    <StepperContainer
+      className={className}
+      current={current}
+      onChange={onChange}
+    >
+      <StepperList className={classNameList}>
+        {items?.map((item, i) => (
+          <StepperTrigger
+            key={i}
+            value={i}
+            title={item?.title}
+            indicator={item?.indicator}
+            classNameItem={classNameItem}
+            classNameButton={classNameButton}
+            classNameIndicator={classNameIndicator}
+          />
+        ))}
+      </StepperList>
+
+      {items?.map((item, i) => (
+        <StepperContent className={classNameContent} key={i} value={i}>
+          {item?.content}
+        </StepperContent>
+      ))}
+    </StepperContainer>
+  );
+}
+
+interface StepperContainerProps
+  extends Omit<HTMLProps<HTMLDivElement>, "onChange"> {
+  current?: number;
+  onChange?: (index: number) => void;
+  className?: ClassName;
+}
+export function StepperContainer({
+  current: prop,
+  onChange,
+  className,
+  ...props
+}: StepperContainerProps) {
+  const [activeStep = 0, setActiveStep] = useControllableState<number>({
+    prop,
+    onChange,
+    defaultProp: 0,
+  });
+  return (
+    <StepperContextProvider value={{ activeStep, setActiveStep }}>
+      <div
+        data-slot="stepper"
+        className={cn(
+          "flex flex-col items-center w-full transition-all ease-in delay-150",
+          className,
+        )}
+        {...props}
+      />
+    </StepperContextProvider>
+  );
+}
+
+interface StepperListProps extends HTMLProps<HTMLUListElement> {}
+export function StepperList({
+  children,
+  className,
+  ...props
+}: StepperListProps) {
+  return (
+    <ul
+      data-slot="stepper-list"
+      className={cn(
+        "flex flex-col sm:flex-row sm:gap-0 gap-4 items-center w-full text-xs font-medium text-gray-900 sm:text-base mb-8",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </ul>
+  );
+}
+
+interface StepperTriggerProps {
+  indicator?: ReactNode;
+  title: ReactNode;
+  value: number;
+  disabled?: boolean;
+  classNameItem?: ClassNameValue;
+  classNameButton?: ClassNameValue;
+  classNameIndicator?: ClassNameValue;
+}
+export function StepperTrigger({
+  disabled,
+  value,
+  title,
+  indicator,
+  classNameItem,
+  classNameButton,
+  classNameIndicator,
+}: StepperTriggerProps) {
+  const { activeStep, setActiveStep } = useStepperContext();
+  return (
+    <li
+      data-slot="stepper-trigger"
+      className={cn(
+        "flex relative text-primary transition-all ease-in delay-150",
+        "last:w-full last:sm:w-auto last:after:hidden",
+        `w-full after:content-[''] sm:after:w-full after:h-full after:w-0.5 sm:after:h-0.5 ${activeStep > value ? "after:bg-primary" : "after:bg-gray-300"} after:inline-block after:absolute after:top-5 sm:after:top-5 after:left-4 sm:after:left-10`,
+        classNameItem,
+      )}
+    >
+      <button
+        onClick={() => !disabled && setActiveStep(value)}
+        className={cn(
+          "z-10 flex items-center justify-center sm:flex-col gap-3 flex-row whitespace-nowrap cursor-pointer group transition-color ease-in delay-150",
+          activeStep >= value ? "text-primary" : "text-gray-500",
+          disabled && "cursor-not-allowed",
+          classNameButton,
+        )}
+      >
+        <span
+          data-slot="stepper-trigger-indicator"
+          className={cn(
+            "flex items-center transition-all overflow-hidden ease-in justify-center group-hover:scale-105 sm:w-10 sm:h-10 mx-auto text-sm border-2 rounded-full w-8 h-8",
+            activeStep > value &&
+              "bg-primary border-primary text-primary-foreground",
+            activeStep === value && "bg-gray-100 text-primary border-primary",
+            activeStep < value && "bg-white text-gray-500 border-input",
+            disabled && "text-gray-300",
+            classNameIndicator,
+          )}
+        >
+          {activeStep > value ? "✓" : indicator || value + 1}
+        </span>
+        {title}
+      </button>
+    </li>
+  );
+}
+
+interface StepperContentProps extends HTMLProps<HTMLDivElement> {
+  value: number;
+}
+export function StepperContent({
+  value,
+  className = "w-full",
+  ...props
+}: StepperContentProps) {
+  const { activeStep } = useStepperContext();
+  const isActiveStep = activeStep === value;
+  if (!isActiveStep) return null;
+  return <div data-slot="stepper-content" className={className} {...props} />;
+}

package/src/components/stepper/context/stepper-context.tsx

@@ -0,0 +1,11 @@
+import { createSafeContext } from "../../../utils";
+
+interface StepperContextProps {
+  activeStep: number;
+  setActiveStep: (index: number) => void;
+}
+
+export const [useStepperContext, StepperContextProvider] =
+  createSafeContext<StepperContextProps>();
+
+export type { StepperContextProps };

package/src/components/stepper/index.ts

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

package/src/components/stepper/stepper.stories.tsx

@@ -0,0 +1,130 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { RectangleEllipsis, Settings, User } from "lucide-react";
+import {
+  Button,
+  Input,
+  Stepper,
+  StepperContainer,
+  StepperContent,
+  StepperList,
+  StepperTrigger,
+} from "../../components";
+import { useStep } from "../../hooks";
+
+const meta: Meta<typeof Stepper> = {
+  title: "Data display/Stepper",
+  component: Stepper,
+  args: {},
+};
+
+export default meta;
+type Story = StoryObj<typeof Stepper>;
+
+const AccountStep = () => {
+  return (
+    <>
+      <Input name="name" />
+      <Input name="lastname" />
+    </>
+  );
+};
+
+const PasswordStep = () => {
+  return (
+    <>
+      <Input name="password" type="password" />
+      <Input name="confirmation" type="password" />
+    </>
+  );
+};
+
+const FileStep = () => {
+  return (
+    <>
+      <Input name="file" type="file" />
+    </>
+  );
+};
+
+const steps = [
+  { title: "Cuenta", content: <AccountStep />, indicator: <User /> },
+  { title: "Configuracón", content: <FileStep />, indicator: <Settings /> },
+  {
+    title: "Contraseña",
+    content: <PasswordStep />,
+    indicator: <RectangleEllipsis />,
+  },
+];
+
+export const Default: Story = {
+  render: () => {
+    return <Stepper items={steps} />;
+  },
+};
+
+export const Disabled: Story = {
+  render: () => {
+    return (
+      <Stepper
+        items={[
+          { title: "Cuenta", content: <AccountStep /> },
+          { title: "Configuracón", content: <FileStep /> },
+          { title: "Contraseña", content: <PasswordStep />, disabled: true },
+        ]}
+      />
+    );
+  },
+};
+
+/**
+ * Se puede utilizar el hook `useStep` para facilitar el manejo de estado y validaciones
+ */
+export const Steps: Story = {
+  render: () => {
+    const { currentStepIndex, isFirstStep, isLastStep, next, back, goTo } =
+      useStep(steps);
+
+    return (
+      <div>
+        <Stepper
+          items={steps}
+          current={currentStepIndex}
+          onChange={(step: number) => goTo(step)}
+        />
+        <div className="flex justify-end gap-x-2 mt-2">
+          <Button variant="ghost" disabled={isFirstStep} onClick={back}>
+            Prev
+          </Button>
+          <Button disabled={isLastStep} onClick={next}>
+            Next
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const StepperWithPrimitives: Story = {
+  render: () => {
+    return (
+      <StepperContainer>
+        <StepperList>
+          {steps?.map((item, i) => (
+            <StepperTrigger
+              key={i}
+              value={i}
+              title={item?.title}
+              indicator={item?.indicator}
+            />
+          ))}
+        </StepperList>
+
+        {steps?.map((item, i) => (
+          <StepperContent key={i} value={i}>
+            {item?.content}
+          </StepperContent>
+        ))}
+      </StepperContainer>
+    );
+  },
+};