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

package/src/__doc__/Types.mdx

@@ -0,0 +1,252 @@
+import {
+  Canvas,
+  ColorItem,
+  ColorPalette,
+  Meta,
+  Source,
+} from "@storybook/addon-docs/blocks";
+import { BorderRadius } from "./Examples";
+
+<Meta title="Documentation/Types" />
+
+# Types
+
+## Extender interfaces de componentes
+
+```ts
+// Se puede inferir utilizando la utilidad ComponentProps
+import { Input } from "../../components";
+type InputProps = ComponentProps<typeof Input>;
+```
+
+## Generic types
+
+### GenericObject
+
+Interfaz de objeto genérico
+
+```ts
+// Definición
+type GenericObject<T = any> = { [key: string]: T };
+
+const myObj: GenericObject = {
+  test: "TEST",
+};
+
+const myObj: GenericObject<number> = {
+  test: "TEST", // TS-Error
+  prop: 4,
+};
+```
+
+### Nullable
+
+Permite manejar valores que pueden ser null
+
+```ts
+// Definición
+type Nullable<T> = T | null;
+
+const [myState, setMyState] = useState<Nullable<number>>(null);
+setState(4);
+```
+
+### Maybe
+
+Permite manejar valores que pueden ser undefined o null
+
+```ts
+// Definición
+type Maybe<T> = T | undefined | null;
+
+interface APIResponse {
+  data: Maybe<string>; // string | undefined | null
+  error: Maybe<string>; // string | undefined | null
+}
+```
+
+### State
+
+Interfaz de hook `useState`
+
+```ts
+// Definición
+type SetState<T> = Dispatch<SetStateAction<T>>;
+type State<T> = [T, SetState<T>];
+
+interface MyComponentProps {
+  value: string;
+  setValue: SetState<string>;
+  otherState: State<boolean>;
+}
+
+function MyComponent({ value, setValue, otherState }: MyComponentProps) {
+   ...
+}
+```
+
+### ClassName
+
+interfaz simple para clases
+
+```ts
+// Definición
+type ClassName = string | undefined;
+
+interface MyComponentProps {
+    className: ClassName
+    ...
+}
+```
+
+### ID
+
+interfaz para ids
+
+```ts
+// Definición
+type ID = string | number;
+
+interface User {
+  id: ID;
+}
+```
+
+### OverrideProps
+
+Interfaz que sobrescribe las propiedades de un componente por la interfaz que se pase
+
+```ts
+// Definición
+type OverrideProps<T, TOverridden> = Omit<T, keyof TOverridden> & TOverridden;
+
+type InputExtension = ComponentProps<"input">;
+type MyCustomProps = { onChange: (value: string) => any };
+type MyComponentProps = OverrideProps<InputExtension, MyCustomProps>; // onChange: (value: string) => any
+```
+
+### SafeOmit
+
+Permite hacer omit de ciertas propiedades de una interfaz brindando autocompletado
+
+```ts
+// Definición
+type SafeOmit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
+
+interface User {
+  name: string;
+  email: string;
+  age: number;
+  gender?: string;
+}
+
+type UserMetadata = Omit<User, "age" | "gender">;
+```
+
+### AtLeastOne
+
+Define un array que debe contener al menos 1 elemento
+
+```ts
+// Definición
+type AtLeastOne<T> = [T, ...T[]];
+
+const myArray: AtLeastOne<number> = []; // ❌ TS-ERROR
+const myArray: AtLeastOne<number> = [1]; // ✅
+```
+
+### Loose
+
+Autocompletado de ciertas opciones con la posibilidad de pasar cualquier string
+
+```ts
+// Definición
+type Loose<T> = T | (string & {});
+
+type Size = "xs" | "md" | "xl";
+type LooseSize = Loose<Size>;
+
+// Autocompleta 'xs', 'md' y 'xl'
+// Permite cualquier string
+const IconSizes: LooseSize[] = ["xs", "md", "xl", "10px", "100px"];
+```
+
+### Controllable
+
+Interfaz que sobrescribe las propiedades de un HTMLElement para hacerlo controlado
+
+```ts
+// Definición
+type Controllable<C, T extends {}> = OverrideProps<
+  HTMLProps<C>,
+  ControllableState<T>
+>;
+
+// ❌ sin usar interfaz
+interface TabsProps
+  extends Omit<
+    HTMLProps<HTMLDivElement>,
+    "value" | "defaultValue" | "onChange"
+  > {
+  value?: string;
+  onChange?: (tab: string) => void;
+  defaultValue?: string;
+}
+
+// ✅ usando interfaz
+type TabsProps = Controllable<HTMLDivElement, string>;
+```
+
+### ArrayUnion
+
+Obtiene una unión de todos los elementos de un array
+
+```ts
+// Definición
+type ArrayUnion<V, T extends ReadonlyArray<V>> = T[number];
+
+const routes = ["dashboard", "login", "settings"] as const;
+type Route = ArrayUnion<string, typeof routes>; // "dashboard" | "login" | "settings"
+```
+
+### ValuesUnion
+
+Obtiene una unión de todos los valores de un objeto
+
+Las claves se pueden obtener con `keyof T`
+
+```ts
+// Definición
+type ValuesUnion<T extends Record<string, any>> = T[keyof T];
+
+const methods = {
+  GET: "get",
+  POST: "post",
+} as const;
+
+type Method = ValuesUnion<typeof methods>; // "get" | "post"
+```
+
+### Entity
+
+Representa una entidad en una base de datos
+
+```ts
+// Definición
+export type BaseEntity = {
+  id: string;
+  createdAt: number;
+};
+
+export type Entity<T> = {
+  [K in keyof T]: T[K];
+} & BaseEntity;
+
+// Uso
+type User = Entity<{
+  firstName: string;
+  lastName: string;
+  email: string;
+  role: "ADMIN" | "USER";
+}>;
+```

package/src/components/alert/alert.stories.tsx

@@ -0,0 +1,142 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import {
+  AlertCircleIcon,
+  CheckCircle2Icon,
+  InfoIcon,
+  TriangleAlert,
+} from "lucide-react";
+import { Button } from "../button";
+import {
+  Alert,
+  AlertAction,
+  AlertDescription,
+  AlertRoot,
+  AlertTitle,
+} from "./index";
+
+/**
+ * Displays a contextual message to the user. Supports five semantic variants —
+ * `default`, `error`, `success`, `warning`, and `info` — each with matching border,
+ * background tint, and icon color.
+ *
+ * Accepts `title`, `description`, `icon`, and `action` as props for the common case.
+ * For full layout control, compose the primitives directly: `AlertRoot`, `AlertTitle`,
+ * `AlertDescription`, and `AlertAction`. Each prop also has an escape-hatch counterpart
+ * (`titleProps`, `descriptionProps`, `actionProps`) to override a specific primitive
+ * without rebuilding the whole structure.
+ */
+const meta: Meta<typeof Alert> = {
+  title: "Components/Alert",
+  component: Alert,
+  subcomponents: {
+    AlertRoot: AlertRoot,
+    AlertTitle: AlertTitle,
+    AlertDescription: AlertDescription,
+    AlertAction: AlertAction,
+  },
+  args: {
+    title: "Heads up",
+    description: "You can change this in your account settings.",
+    variant: "default",
+  },
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["default", "error", "success", "warning", "info"],
+    },
+    title: { control: "text" },
+    description: { control: "text" },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Alert>;
+
+export const Default: Story = {};
+
+/**
+ * Use `variant="error"` for validation failures or destructive outcomes.
+ * Pair with an icon to reinforce the severity.
+ */
+export const Error: Story = {
+  args: {
+    variant: "error",
+    title: "Something went wrong",
+    description: "Your session has expired. Please sign in again.",
+    icon: <AlertCircleIcon className="size-4" />,
+  },
+};
+
+/**
+ * Use `variant="success"` to confirm a completed action.
+ */
+export const Success: Story = {
+  args: {
+    variant: "success",
+    title: "Changes saved",
+    description: "Your profile has been updated successfully.",
+    icon: <CheckCircle2Icon className="size-4" />,
+  },
+};
+
+export const Warning: Story = {
+  args: {
+    variant: "warning",
+    title: "Storage almost full",
+    description:
+      "You've used 90% of your storage quota. Free up space to avoid disruptions.",
+    icon: <TriangleAlert className="size-4" />,
+  },
+};
+
+export const Info: Story = {
+  args: {
+    variant: "info",
+    title: "Scheduled maintenance",
+    description:
+      "The service will be unavailable on Saturday from 2:00 to 4:00 AM UTC.",
+    icon: <InfoIcon className="size-4" />,
+  },
+};
+
+/**
+ * The `action` prop renders inside `AlertAction`, positioned to the right.
+ * Useful for inline CTAs like "Retry", "Undo", or "Dismiss".
+ */
+export const WithAction: Story = {
+  args: {
+    variant: "error",
+    title: "Connection failed",
+    description: "Unable to reach the server.",
+    icon: <AlertCircleIcon className="size-4" />,
+    action: (
+      <Button size="sm" variant="error">
+        Retry
+      </Button>
+    ),
+  },
+};
+
+/**
+ * Use the primitives directly when you need full control over layout or content structure.
+ * `AlertRoot` accepts `variant` and all standard div props.
+ */
+export const Primitive: Story = {
+  render: () => (
+    <AlertRoot variant="error">
+      <AlertCircleIcon className="size-4" />
+      <AlertTitle>Payment failed</AlertTitle>
+      <AlertDescription>
+        Your card was declined. Check your billing details and try again.
+      </AlertDescription>
+      <AlertAction>
+        <Button size="sm" variant="outline">
+          Dismiss
+        </Button>
+        <Button size="sm" variant="error">
+          Update billing
+        </Button>
+      </AlertAction>
+    </AlertRoot>
+  ),
+};

package/src/components/alert/alert.tsx

@@ -0,0 +1,109 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import { type ComponentProps, type ReactNode } from "react";
+import { cn } from "../../lib";
+
+const alertVariants = cva(
+  "relative grid w-full items-start gap-x-2 gap-y-0.5 rounded-xl border px-3 py-3 text-card-foreground text-sm has-[>svg]:has-data-[slot=alert-action]:grid-cols-[calc(var(--spacing)*4)_1fr_auto] has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] has-data-[slot=alert-action]:grid-cols-[1fr_auto] has-[>svg]:gap-x-2 [&>svg]:h-lh [&>svg]:w-4",
+  {
+    defaultVariants: {
+      variant: "default",
+    },
+    variants: {
+      variant: {
+        default: "bg-transparent [&>svg]:text-muted-foreground",
+        error: "border-error/32 bg-error/4 [&>svg]:text-error",
+        success: "border-success/32 bg-success/4 [&>svg]:text-success",
+        warning: "border-warning/32 bg-warning/4 [&>svg]:text-warning",
+        info: "border-info/32 bg-info/4 [&>svg]:text-info",
+      },
+    },
+  },
+);
+
+export function AlertRoot({
+  className,
+  variant,
+  ...props
+}: ComponentProps<"div"> & VariantProps<typeof alertVariants>) {
+  return (
+    <div
+      className={cn(alertVariants({ variant }), className)}
+      data-slot="alert"
+      role="alert"
+      {...props}
+    />
+  );
+}
+
+export function AlertTitle({ className, ...props }: ComponentProps<"div">) {
+  return (
+    <div
+      className={cn("font-medium [svg~&]:col-start-2", className)}
+      data-slot="alert-title"
+      {...props}
+    />
+  );
+}
+
+export function AlertDescription({
+  className,
+  ...props
+}: ComponentProps<"div">) {
+  return (
+    <div
+      className={cn(
+        "flex flex-col gap-2.5 text-muted-foreground [svg~&]:col-start-2",
+        className,
+      )}
+      data-slot="alert-description"
+      {...props}
+    />
+  );
+}
+
+export function AlertAction({ className, ...props }: ComponentProps<"div">) {
+  return (
+    <div
+      className={cn(
+        "flex gap-1 max-sm:col-start-2 max-sm:mt-2 sm:row-start-1 sm:row-end-3 sm:self-center sm:[[data-slot=alert-description]~&]:col-start-2 sm:[[data-slot=alert-title]~&]:col-start-2 sm:[svg~&]:col-start-2 sm:[svg~[data-slot=alert-description]~&]:col-start-3 sm:[svg~[data-slot=alert-title]~&]:col-start-3",
+        className,
+      )}
+      data-slot="alert-action"
+      {...props}
+    />
+  );
+}
+
+interface AlertProps extends Omit<ComponentProps<typeof AlertRoot>, "title"> {
+  title?: ReactNode;
+  description?: ReactNode;
+  icon?: ReactNode;
+  action?: ReactNode;
+  titleProps?: ComponentProps<typeof AlertTitle>;
+  descriptionProps?: ComponentProps<typeof AlertDescription>;
+  actionProps?: ComponentProps<typeof AlertAction>;
+}
+
+export function Alert({
+  title,
+  description,
+  icon,
+  action,
+  titleProps,
+  descriptionProps,
+  actionProps,
+  children,
+  ...props
+}: AlertProps) {
+  return (
+    <AlertRoot {...props}>
+      {icon}
+      {title && <AlertTitle {...titleProps}>{title}</AlertTitle>}
+      {description && (
+        <AlertDescription {...descriptionProps}>{description}</AlertDescription>
+      )}
+      {action && <AlertAction {...actionProps}>{action}</AlertAction>}
+      {children}
+    </AlertRoot>
+  );
+}

package/src/components/alert/index.ts

@@ -0,0 +1,7 @@
+export {
+  Alert,
+  AlertAction,
+  AlertDescription,
+  AlertRoot,
+  AlertTitle,
+} from "./alert";

package/src/components/alert-dialog/alert-dialog.stories.tsx

@@ -0,0 +1,173 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Trash2 } from "lucide-react";
+import { action } from "storybook/actions";
+import {
+  AlertDialog,
+  AlertDialogClose,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogPopup,
+  AlertDialogRoot,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+  Button,
+  Tooltip,
+} from "../../components";
+
+/**
+ * Accessible confirmation dialog that requires the user to explicitly acknowledge
+ * a destructive or irreversible action before proceeding.
+ *
+ * The `trigger` prop uses Base UI's `render` prop — no DOM wrapper is added —
+ * so it composes cleanly with `<Tooltip>` via the primitive API (see **WithTooltip**).
+ *
+ * Use `open` + `onOpenChange` for programmatic control when there is no static trigger.
+ * For anything beyond the two-button layout, drop down to the exported primitives.
+ */
+const meta: Meta<typeof AlertDialog> = {
+  title: "Components/AlertDialog",
+  component: AlertDialog,
+  parameters: {
+    layout: "centered",
+  },
+  args: {
+    trigger: <Button variant="outline">Open dialog</Button>,
+    title: "Are you sure?",
+    description: "This action cannot be undone.",
+    onClose: action("onClose"),
+    onAction: action("onAction"),
+  },
+  argTypes: {
+    trigger: { control: false },
+    title: { control: "text" },
+    description: { control: "text" },
+    closeText: { control: "text" },
+    actionText: { control: "text" },
+    variant: {
+      control: "select",
+      options: ["default", "error", "secondary", "outline", "ghost"],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof AlertDialog>;
+
+export const Default: Story = {};
+
+/**
+ * Use `variant="error"` for irreversible actions like deletes.
+ * The error button signals danger — reserve it for data loss scenarios.
+ */
+export const Error: Story = {
+  args: {
+    trigger: <Button variant="error">Delete account</Button>,
+    title: "Delete account?",
+    description:
+      "Your account and all associated data will be permanently removed. This cannot be undone.",
+    variant: "error",
+    actionText: "Delete",
+    closeText: "Keep account",
+  },
+};
+
+/**
+ * `children` renders between the description and the footer buttons.
+ * Use it for detail lists, warnings, or any custom content that belongs
+ * inside the dialog body without replacing the standard header/footer layout.
+ */
+export const WithBody: Story = {
+  args: {
+    trigger: <Button variant="outline">Transfer ownership</Button>,
+    title: "Transfer workspace ownership",
+    description:
+      "Transferring ownership will immediately revoke your admin access.",
+    children: (
+      <ul className="rounded-md border bg-muted/50 p-4 text-sm space-y-1.5 text-muted-foreground">
+        <li>• You will become a regular member</li>
+        <li>• Billing responsibility transfers to the new owner</li>
+        <li>• Active integrations will be re-authenticated</li>
+      </ul>
+    ),
+    actionText: "Transfer",
+  },
+};
+
+/**
+ * Use `open` and `onOpenChange` when the dialog is triggered programmatically —
+ * from a table row action, a keyboard shortcut, or a side-effect — without a
+ * static trigger element rendered next to the content.
+ */
+export const Controlled: Story = {
+  render: (args) => {
+    return (
+      <div className="flex items-center gap-4">
+        <AlertDialog {...args} />
+        <span className="text-sm text-muted-foreground">
+          Dialog is controlled externally
+        </span>
+      </div>
+    );
+  },
+  args: {
+    trigger: <Button variant="outline">Open (controlled)</Button>,
+    title: "Controlled dialog",
+    description:
+      "This dialog's open state is managed by the parent. Useful for programmatic flows.",
+  },
+};
+
+/**
+ * Pass a `<Tooltip>` as the `trigger` to show a tooltip on hover and open the dialog
+ * on click — both bound to the same DOM element, no wrapper added.
+ *
+ * This works because `Tooltip` forwards unknown props to its internal trigger,
+ * so Base UI can chain the dialog's click handler through into the `<Button>`.
+ */
+export const WithTooltip: Story = {
+  args: {
+    trigger: (
+      <Tooltip content="Permanently delete this item">
+        <Button variant="error">
+          <Trash2 className="size-4" />
+          Delete
+        </Button>
+      </Tooltip>
+    ),
+    title: "Delete item?",
+    description: "This action cannot be undone.",
+    variant: "error",
+    actionText: "Delete",
+  },
+};
+
+/**
+ * Direct composition with primitives for full structural control.
+ * Use this when the composite layout doesn't fit — custom headers, async actions,
+ * forms, or multi-step flows.
+ */
+export const Primitive: Story = {
+  render: () => (
+    <AlertDialogRoot>
+      <AlertDialogTrigger>
+        <Button variant="outline">Open</Button>
+      </AlertDialogTrigger>
+      <AlertDialogPopup>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Built with primitives</AlertDialogTitle>
+        </AlertDialogHeader>
+        <p className="text-sm text-muted-foreground">
+          Any layout is possible — forms, lists, custom footers.
+        </p>
+        <AlertDialogFooter>
+          <AlertDialogClose>
+            <Button variant="secondary">Cancel</Button>
+          </AlertDialogClose>
+          <AlertDialogClose>
+            <Button>Confirm</Button>
+          </AlertDialogClose>
+        </AlertDialogFooter>
+      </AlertDialogPopup>
+    </AlertDialogRoot>
+  ),
+};