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

package/src/components/auto-complete/auto-complete.stories.tsx

@@ -0,0 +1,241 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import {
+  Archive,
+  Calendar,
+  FlameKindling,
+  Github,
+  Mail,
+  Settings,
+  Slack,
+  TicketPercent,
+  User,
+  UserPlus,
+} from "lucide-react";
+import React, { useState } from "react";
+import {
+  AutoComplete,
+  AutoCompleteDialog,
+  AutoCompleteEmpty,
+  AutoCompleteGroup,
+  AutoCompleteInput,
+  AutoCompleteItem,
+  AutoCompleteList,
+  AutoCompleteRoot,
+  AutoCompleteSeparator,
+  AutoCompleteShortcut,
+  Button,
+  MenuContent,
+  MenuGroup,
+  MenuRoot,
+  MenuSub,
+  MenuSubContent,
+  MenuSubTrigger,
+  MenuTrigger,
+  Popover,
+} from "../../components";
+import { useHotkey } from "../../hooks";
+
+const meta: Meta<typeof AutoComplete> = {
+  title: "Data entry/AutoComplete",
+  component: AutoComplete,
+};
+
+export default meta;
+type Story = StoryObj<typeof AutoComplete>;
+
+const items = [
+  { value: "apple", label: "Apple" },
+  { value: "banana", label: "Banana" },
+  { value: "cherry", label: "Cherry" },
+];
+
+export const Default: Story = {
+  args: {
+    items: items,
+    onSelect: console.log,
+    placeholder: "Search fruits",
+  },
+};
+
+/**
+ * Componente primitive AutoComplete que permite construir un campo de búsqueda con sugerencias.
+ * Filtra y ordena los elementos de una lista de sugerencias.
+ * ## Estructura
+ * ```tsx
+ * <AutocompleteRoot>
+ *   <AutocompleteInput placeholder="Buscar..." />
+ *   <AutocompleteList>
+ *     <AutocompleteEmpty>No Se Encontraron Resultados</AutocompleteEmpty>
+ *     <AutocompleteGroup>
+ *       <AutocompleteItem>Calendario</AutocompleteItem>
+ *       <AutocompleteItem>Eventos</AutocompleteItem>
+ *       <AutocompleteItem>Archivados</AutocompleteItem>
+ *     </AutocompleteGroup>
+ *   </AutocompleteList>
+ * </AutocompleteRoot>
+ *  ```
+ *  */
+export const Primitive: Story = {
+  render: () => {
+    return (
+      <AutoCompleteRoot className="border border-input">
+        <AutoCompleteInput placeholder="Buscar..." />
+        <AutoCompleteList>
+          <AutoCompleteEmpty>No se encontraron resultados</AutoCompleteEmpty>
+          <AutoCompleteGroup>
+            <AutoCompleteItem>Calendario</AutoCompleteItem>
+            <AutoCompleteItem>Eventos</AutoCompleteItem>
+            <AutoCompleteItem>Archivados</AutoCompleteItem>
+          </AutoCompleteGroup>
+          <AutoCompleteSeparator />
+        </AutoCompleteList>
+      </AutoCompleteRoot>
+    );
+  },
+};
+
+export const Dialog: Story = {
+  render: () => {
+    const [open, setOpen] = React.useState(false);
+    useHotkey("shift+/", () => setOpen((open) => !open), {
+      ignoreInputFields: false,
+    });
+
+    return (
+      <>
+        <p className="text-sm flex items-center gap-x-2">
+          Presiona
+          <kbd className="pointer-events-none inline-flex h-5 select-none items-center gap-1 rounded border bg-muted px-1.5 font-mono text-[10px] font-medium text-muted-foreground opacity-100">
+            /
+          </kbd>
+          para abrir el diálogo de comandos.
+        </p>
+        <AutoCompleteDialog open={open} onOpenChange={setOpen}>
+          <AutoCompleteInput placeholder="Busca una vista o escribe un comando..." />
+          <AutoCompleteList>
+            <AutoCompleteEmpty>No se encontraron resultados</AutoCompleteEmpty>
+            <AutoCompleteGroup heading="Sugerencias">
+              <AutoCompleteItem onSelect={(value) => console.log(value)}>
+                <Calendar />
+                <span>Calendario</span>
+              </AutoCompleteItem>
+              <AutoCompleteItem>
+                <TicketPercent />
+                <span>Eventos</span>
+              </AutoCompleteItem>
+              <AutoCompleteItem>
+                <Archive />
+                <span>Archivados</span>
+              </AutoCompleteItem>
+            </AutoCompleteGroup>
+            <AutoCompleteSeparator />
+            <AutoCompleteGroup heading="Configuraciones">
+              <AutoCompleteItem>
+                <User />
+                <span>Mi perfil</span>
+                <AutoCompleteShortcut>P</AutoCompleteShortcut>
+              </AutoCompleteItem>
+              <AutoCompleteItem>
+                <Settings />
+                <span>Configuración</span>
+                <AutoCompleteShortcut>C</AutoCompleteShortcut>
+              </AutoCompleteItem>
+            </AutoCompleteGroup>
+          </AutoCompleteList>
+        </AutoCompleteDialog>
+      </>
+    );
+  },
+};
+
+export const SearchableMenu = {
+  name: "Menu",
+  render: () => {
+    const [open, setOpen] = useState(false);
+
+    return (
+      <MenuRoot open={open} onOpenChange={setOpen}>
+        <MenuTrigger asChild>
+          <Button variant="outline">Open</Button>
+        </MenuTrigger>
+        <MenuContent className="w-56">
+          <MenuSub>
+            <MenuSubTrigger>
+              <UserPlus className="mr-2 h-4 w-4" />
+              Añadir usuario
+            </MenuSubTrigger>
+            <MenuGroup>
+              <MenuSubContent>
+                <AutoCompleteRoot>
+                  <AutoCompleteInput placeholder="Buscar..." autoFocus={true} />
+                  <AutoCompleteList>
+                    <AutoCompleteEmpty>No hay resultados</AutoCompleteEmpty>
+                    <AutoCompleteGroup heading="Medio de notificación">
+                      <AutoCompleteItem>
+                        <Mail />
+                        Correo electrónico
+                      </AutoCompleteItem>
+                      <AutoCompleteItem>
+                        <Slack />
+                        Slack
+                      </AutoCompleteItem>
+                      <AutoCompleteItem>
+                        <Github />
+                        Github
+                      </AutoCompleteItem>
+                      <AutoCompleteItem>
+                        <FlameKindling />
+                        Señal de humo
+                      </AutoCompleteItem>
+                    </AutoCompleteGroup>
+                  </AutoCompleteList>
+                </AutoCompleteRoot>
+              </MenuSubContent>
+            </MenuGroup>
+          </MenuSub>
+        </MenuContent>
+      </MenuRoot>
+    );
+  },
+};
+
+export const SearchablePopover = {
+  name: "Popover",
+  render: () => {
+    return (
+      <Popover
+        trigger={
+          <Button>
+            <UserPlus className="mr-2 h-4 w-4" />
+            Añadir usuario
+          </Button>
+        }
+      >
+        <AutoCompleteRoot>
+          <AutoCompleteInput placeholder="Buscar..." autoFocus={true} />
+          <AutoCompleteList>
+            <AutoCompleteEmpty>No hay resultados</AutoCompleteEmpty>
+            <AutoCompleteGroup heading="Medio de notificación">
+              <AutoCompleteItem>
+                <Mail />
+                Correo electrónico
+              </AutoCompleteItem>
+              <AutoCompleteItem>
+                <Slack />
+                Slack
+              </AutoCompleteItem>
+              <AutoCompleteItem>
+                <Github />
+                Github
+              </AutoCompleteItem>
+              <AutoCompleteItem>
+                <FlameKindling />
+                Señal de humo
+              </AutoCompleteItem>
+            </AutoCompleteGroup>
+          </AutoCompleteList>
+        </AutoCompleteRoot>
+      </Popover>
+    );
+  },
+};

package/src/components/auto-complete/auto-complete.tsx

@@ -0,0 +1,82 @@
+import { ComponentProps } from "react";
+import { ClassName } from "@/models";
+import {
+  AutoCompleteEmpty,
+  AutoCompleteInput,
+  AutoCompleteItem,
+  AutoCompleteList,
+  AutoCompleteRoot,
+  AutoCompleteShortcut,
+} from "../../components";
+
+interface AutoCompleteItem {
+  value: string;
+  label: string;
+  shortcut?: string;
+}
+
+interface ExtendedProps {
+  containerClassName: ClassName;
+  inputClassName: ClassName;
+  listClassName: ClassName;
+  itemClassName: ClassName;
+  emptyClassName: ClassName;
+  containerProps: ComponentProps<typeof AutoCompleteRoot>;
+  inputProps: ComponentProps<typeof AutoCompleteInput>;
+  listProps: ComponentProps<typeof AutoCompleteList>;
+  itemProps: ComponentProps<typeof AutoCompleteItem>;
+  emptyProps: ComponentProps<typeof AutoCompleteEmpty>;
+}
+
+interface Props extends ExtendedProps {
+  items: AutoCompleteItem[];
+  placeholder?: string;
+  emptyMessage?: string;
+  onSelect?: (value: AutoCompleteItem["value"], item: AutoCompleteItem) => any;
+}
+
+export const AutoComplete = ({
+  items,
+  placeholder = "Buscar...",
+  emptyMessage = "No se encontraron resultados",
+  onSelect,
+  containerClassName,
+  containerProps,
+  inputClassName,
+  inputProps,
+  listClassName,
+  listProps,
+  itemClassName,
+  itemProps,
+  emptyClassName,
+  emptyProps,
+}: Props) => {
+  return (
+    <AutoCompleteRoot className={containerClassName} {...containerProps}>
+      <AutoCompleteInput
+        placeholder={placeholder}
+        className={inputClassName}
+        {...inputProps}
+      />
+      <AutoCompleteList className={listClassName} {...listProps}>
+        {(items as AutoCompleteItem[]).map((item) => (
+          <AutoCompleteItem
+            className={itemClassName}
+            key={item.value}
+            onSelect={() => onSelect?.(item.value, item)}
+            {...itemProps}
+          >
+            {item.label}
+            {item.shortcut && (
+              <AutoCompleteShortcut>{item.shortcut}</AutoCompleteShortcut>
+            )}
+          </AutoCompleteItem>
+        ))}
+      </AutoCompleteList>
+
+      <AutoCompleteEmpty className={emptyClassName} {...emptyProps}>
+        {emptyMessage}
+      </AutoCompleteEmpty>
+    </AutoCompleteRoot>
+  );
+};

package/src/components/auto-complete/index.ts

@@ -0,0 +1,2 @@
+export * from "./auto-complete";
+export * from "./auto-complete-primitives";

package/src/components/avatar/avatar.stories.tsx

@@ -0,0 +1,84 @@
+import { faker } from "@faker-js/faker";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { User } from "lucide-react";
+import { action } from "storybook/actions";
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  AvatarRoot,
+} from "../../components";
+
+/**
+ * Displays a user's profile image with automatic fallback to text initials derived from `alt`.
+ * Built on Base UI Avatar — image loading and fallback visibility are handled natively.
+ * Use `delay` to defer the fallback appearance and avoid a flash during image load.
+ * Exposes `AvatarRoot`, `AvatarImage`, `AvatarFallback` primitives for custom compositions.
+ */
+const meta: Meta<typeof Avatar> = {
+  title: "components/Avatar",
+  component: Avatar,
+  args: {
+    alt: faker.person.fullName(),
+    src: faker.image.avatar(),
+    delay: 1000,
+  },
+} satisfies Meta<typeof Avatar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/**
+ * When `src` is empty or the image fails to load, initials are extracted from `alt` automatically.
+ */
+export const FallbackText: Story = {
+  args: {
+    src: "",
+  },
+};
+
+export const CustomFallback: Story = {
+  args: {
+    src: "",
+    fallback: <User />,
+  },
+};
+
+export const Sizes: Story = {
+  render: (args) => (
+    <div className="flex items-center gap-4">
+      <Avatar {...args} size="xs" />
+      <Avatar {...args} size="sm" />
+      <Avatar {...args} size="md" />
+      <Avatar {...args} size="lg" />
+      <Avatar {...args} size="xl" />
+    </div>
+  ),
+};
+
+export const Shapes: Story = {
+  render: (args) => (
+    <div className="flex items-center gap-4">
+      <Avatar {...args} shape="circle" />
+      <Avatar {...args} shape="square" />
+    </div>
+  ),
+};
+
+export const Primitive: Story = {
+  render: () => (
+    <AvatarRoot shape="square" size="lg">
+      <AvatarImage src={faker.image.avatar()} alt="John Doe" />
+      <AvatarFallback delay={1000}>JD</AvatarFallback>
+    </AvatarRoot>
+  ),
+};
+
+export const Clickable: Story = {
+  args: {
+    onClick: action("avatar:click"),
+    className: "cursor-pointer",
+  },
+};

package/src/components/avatar/avatar.test.tsx

@@ -0,0 +1,61 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Avatar } from "../../components";
+import { extractInitials } from "../../utils";
+
+describe("Avatar component", () => {
+  const personName = "lorem ipsum";
+  const imageSrc = "https://i.pravatar.cc/300";
+
+  it("renders correctly", () => {
+    render(<Avatar alt={personName} src={imageSrc} />);
+    const image = screen.getByRole("img");
+
+    expect(image).toBeInTheDocument();
+    expect(image).toHaveAttribute("alt", personName);
+    expect(image).toHaveAttribute("src", imageSrc);
+  });
+
+  it("renders correctly without src", () => {
+    render(<Avatar alt={personName} src="" />);
+    const nameInitials = extractInitials(personName);
+
+    const image = screen.queryByRole("img");
+    const fallbackText = screen.getByText(nameInitials);
+
+    expect(image).not.toBeInTheDocument();
+    expect(fallbackText).toBeInTheDocument();
+  });
+
+  it("renders correctly with onError", () => {
+    render(<Avatar alt={personName} src="" />);
+
+    const nameInitials = extractInitials(personName);
+    const image = screen.queryByRole("img");
+    const fallbackText = screen.getByText(nameInitials);
+
+    expect(image).not.toBeInTheDocument();
+    expect(fallbackText).toBeInTheDocument();
+  });
+
+  it("renders correctly with imageProps", () => {
+    const testClassName = "test-class";
+    render(
+      <Avatar
+        alt={personName}
+        src={imageSrc}
+        imageProps={{ className: testClassName }}
+      />,
+    );
+
+    const image = screen.getByRole("img");
+    expect(image).toHaveClass(testClassName);
+  });
+
+  it("renders correctly with size variants", () => {
+    render(<Avatar alt={personName} src={imageSrc} size="sm" />);
+    const avatar = screen.getByRole("img").parentElement;
+
+    expect(avatar).toHaveClass("w-8 h-8");
+  });
+});

package/src/components/avatar/avatar.tsx

@@ -0,0 +1,104 @@
+import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar";
+import { cva, type VariantProps } from "class-variance-authority";
+import { type ReactNode } from "react";
+import { cn } from "../../lib";
+import { extractInitials } from "../../utils";
+
+const avatarVariants = cva(
+  "overflow-hidden aspect-square bg-muted grid place-items-center font-semibold shrink-0 select-none",
+  {
+    variants: {
+      shape: {
+        circle: "rounded-full",
+        square: "rounded-xl",
+      },
+      size: {
+        xs: "size-6 text-[10px]",
+        sm: "size-8 text-xs",
+        md: "size-10 text-sm",
+        lg: "size-14 text-base",
+        xl: "size-20 text-xl",
+      },
+    },
+    defaultVariants: {
+      shape: "circle",
+      size: "md",
+    },
+  },
+);
+
+export function AvatarRoot({
+  className,
+  shape,
+  size,
+  ...props
+}: AvatarPrimitive.Root.Props & VariantProps<typeof avatarVariants>) {
+  return (
+    <AvatarPrimitive.Root
+      className={cn(avatarVariants({ shape, size }), className)}
+      data-slot="avatar"
+      {...props}
+    />
+  );
+}
+
+export function AvatarImage({
+  className,
+  ...props
+}: AvatarPrimitive.Image.Props) {
+  return (
+    <AvatarPrimitive.Image
+      className={cn("size-full object-cover", className)}
+      data-slot="avatar-image"
+      {...props}
+    />
+  );
+}
+
+export function AvatarFallback({
+  className,
+  ...props
+}: AvatarPrimitive.Fallback.Props) {
+  return (
+    <AvatarPrimitive.Fallback
+      className={cn("flex size-full items-center justify-center", className)}
+      data-slot="avatar-fallback"
+      {...props}
+    />
+  );
+}
+
+interface AvatarProps extends Omit<AvatarPrimitive.Root.Props, "children"> {
+  src?: string;
+  alt: string;
+  fallback?: ReactNode;
+  delay?: AvatarPrimitive.Fallback.Props["delay"];
+  shape?: VariantProps<typeof avatarVariants>["shape"];
+  size?: VariantProps<typeof avatarVariants>["size"];
+  imageProps?: AvatarPrimitive.Image.Props;
+  fallbackProps?: AvatarPrimitive.Fallback.Props;
+}
+
+export function Avatar({
+  src,
+  alt,
+  fallback,
+  delay,
+  shape,
+  size,
+  className,
+  imageProps,
+  fallbackProps,
+  ...props
+}: AvatarProps) {
+  return (
+    <AvatarRoot shape={shape} size={size} className={className} {...props}>
+      <AvatarImage src={src} alt={alt} {...imageProps} />
+      <AvatarFallback delay={delay} {...fallbackProps}>
+        {fallback ?? extractInitials(alt)}
+      </AvatarFallback>
+    </AvatarRoot>
+  );
+}
+
+export { AvatarPrimitive };

package/src/components/avatar/index.ts

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

package/src/components/background-image/background-image.stories.tsx

@@ -0,0 +1,21 @@
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { BackgroundImage } from "../../components";
+
+/**
+ * Componente que facilita el manejo de imágenes de fondo.
+ */
+const meta: Meta<typeof BackgroundImage> = {
+  title: "Others/BackgroundImage",
+  component: BackgroundImage,
+  args: {
+    src: "https://m.media-amazon.com/images/I/81PgpygKwdL._AC_UF894,1000_QL80_.jpg",
+    children:
+      "Lorem Ipsum es simplemente el texto de relleno de las imprentas y archivos de texto. Lorem Ipsum ha sido el texto de relleno estándar de las industrias desde el año 1500, cuando un impresor (N. del T. persona que se dedica a la imprenta)",
+    className: "text-white w-[400px] h-[200px] rounded p-4",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/components/background-image/background-image.test.tsx

@@ -0,0 +1,29 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { BackgroundImage } from ".";
+
+describe("BackgroundImage component", () => {
+  const imageSrc = "https://source.unsplash.com/random";
+
+  it("should render the background image", () => {
+    render(<BackgroundImage src={imageSrc} data-testid="container" />);
+    const container = screen.getByTestId("container");
+
+    expect(container).toBeInTheDocument();
+    expect(container).toHaveStyle({
+      backgroundImage: `url(${imageSrc})`,
+    });
+  });
+
+  it("should render the children", () => {
+    const text = "Lorem Ipsum";
+    render(
+      <BackgroundImage src={imageSrc}>
+        <p>{text}</p>
+      </BackgroundImage>,
+    );
+    const paragraph = screen.getByText(text);
+
+    expect(paragraph).toBeInTheDocument();
+  });
+});

package/src/components/background-image/background-image.tsx

@@ -0,0 +1,23 @@
+import { HTMLProps } from "react";
+import { cn } from "../../lib";
+
+interface Props extends HTMLProps<HTMLDivElement> {
+  /**
+   * La URL de la imagen
+   */
+  src: string;
+}
+
+export const BackgroundImage = ({ src, ...props }: Props) => {
+  return (
+    <div
+      {...props}
+      data-slot="background-image"
+      className={cn("w-full block bg-cover bg-center", props.className)}
+      style={{
+        ...props.style,
+        backgroundImage: `url(${src})`,
+      }}
+    />
+  );
+};

package/src/components/background-image/index.ts

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