@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.20

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

@@ -0,0 +1,432 @@
+"use client";
+
+import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
+import { ChevronsUpDownIcon, XIcon } from "lucide-react";
+import type React from "react";
+import { cn } from "../../lib";
+import { inputBaseClasses } from "../input";
+import { ScrollArea } from "../scroll-area";
+
+export const AutocompleteRoot = AutocompletePrimitive.Root;
+
+export function AutocompleteInput({
+  className,
+  adornment,
+  startAddon,
+  triggerProps,
+  clearProps,
+  ...props
+}: AutocompletePrimitive.Input.Props & {
+  adornment?: "trigger" | "clear";
+  startAddon?: React.ReactNode;
+  ref?: React.Ref<HTMLInputElement>;
+  triggerProps?: AutocompletePrimitive.Trigger.Props;
+  clearProps?: AutocompletePrimitive.Clear.Props;
+}): React.ReactElement {
+  return (
+    <AutocompletePrimitive.InputGroup
+      className="relative not-has-[>*.w-full]:w-fit w-full text-foreground has-disabled:opacity-64"
+      data-slot="autocomplete-input-group"
+    >
+      {startAddon && (
+        <div
+          aria-hidden="true"
+          className="pointer-events-none absolute inset-y-0 start-px z-10 flex items-center ps-[calc(--spacing(3)-1px)] opacity-80 [&_svg:not([class*='size-'])]:size-4 [&_svg]:-mx-0.5"
+          data-slot="autocomplete-start-addon"
+        >
+          {startAddon}
+        </div>
+      )}
+      <AutocompletePrimitive.Input
+        className={cn(
+          inputBaseClasses,
+          "focus-visible:border-ring",
+          "aria-invalid:border-error focus-visible:aria-invalid:ring-error/20",
+          "disabled:cursor-not-allowed disabled:opacity-50",
+          startAddon && "ps-9",
+          adornment && "pe-9",
+          className,
+        )}
+        data-slot="autocomplete-input"
+        render={<input autoComplete="off" data-slot="input" />}
+        {...props}
+      />
+      {adornment === "clear" ? (
+        <AutocompleteClear {...clearProps} />
+      ) : adornment === "trigger" ? (
+        <AutocompleteTrigger {...triggerProps} />
+      ) : null}
+    </AutocompletePrimitive.InputGroup>
+  );
+}
+
+export function AutocompletePopup({
+  className,
+  children,
+  side = "bottom",
+  sideOffset = 4,
+  alignOffset,
+  align = "start",
+  anchor,
+  portalProps,
+  ...props
+}: AutocompletePrimitive.Popup.Props & {
+  align?: AutocompletePrimitive.Positioner.Props["align"];
+  sideOffset?: AutocompletePrimitive.Positioner.Props["sideOffset"];
+  alignOffset?: AutocompletePrimitive.Positioner.Props["alignOffset"];
+  side?: AutocompletePrimitive.Positioner.Props["side"];
+  anchor?: AutocompletePrimitive.Positioner.Props["anchor"];
+  portalProps?: AutocompletePrimitive.Portal.Props;
+}): React.ReactElement {
+  return (
+    <AutocompletePrimitive.Portal {...portalProps}>
+      <AutocompletePrimitive.Positioner
+        align={align}
+        alignOffset={alignOffset}
+        anchor={anchor}
+        className="z-50 select-none"
+        data-slot="autocomplete-positioner"
+        side={side}
+        sideOffset={sideOffset}
+      >
+        <AutocompletePrimitive.Popup
+          className={cn(
+            "relative flex max-h-[min(var(--available-height),23rem)] min-w-(--anchor-width) max-w-(--available-width) origin-(--transform-origin) flex-1 flex-col rounded-lg border bg-popover text-foreground shadow-lg/5",
+            "duration-100 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+            "data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2",
+            className,
+          )}
+          data-slot="autocomplete-popup"
+          {...props}
+        >
+          {children}
+        </AutocompletePrimitive.Popup>
+      </AutocompletePrimitive.Positioner>
+    </AutocompletePrimitive.Portal>
+  );
+}
+
+export function AutocompleteList({
+  className,
+  ...props
+}: AutocompletePrimitive.List.Props): React.ReactElement {
+  return (
+    <ScrollArea scrollbarGutter scrollFade>
+      <AutocompletePrimitive.List
+        className={cn(
+          "not-empty:scroll-py-1 not-empty:p-1 in-data-has-overflow-y:pe-3",
+          className,
+        )}
+        data-slot="autocomplete-list"
+        {...props}
+      />
+    </ScrollArea>
+  );
+}
+
+export function AutocompleteItem({
+  className,
+  children,
+  ...props
+}: AutocompletePrimitive.Item.Props): React.ReactElement {
+  return (
+    <AutocompletePrimitive.Item
+      className={cn(
+        "flex min-h-8 cursor-default select-none items-center rounded-sm px-2 py-1 text-base outline-none data-disabled:pointer-events-none data-highlighted:bg-accent data-highlighted:text-accent-foreground data-disabled:opacity-64 sm:min-h-7 sm:text-sm",
+        className,
+      )}
+      data-slot="autocomplete-item"
+      {...props}
+    >
+      {children}
+    </AutocompletePrimitive.Item>
+  );
+}
+
+export function AutocompleteSeparator({
+  className,
+  ...props
+}: AutocompletePrimitive.Separator.Props): React.ReactElement {
+  return (
+    <AutocompletePrimitive.Separator
+      className={cn("mx-2 my-1 h-px bg-border last:hidden", className)}
+      data-slot="autocomplete-separator"
+      {...props}
+    />
+  );
+}
+
+export function AutocompleteGroup({
+  className,
+  ...props
+}: AutocompletePrimitive.Group.Props): React.ReactElement {
+  return (
+    <AutocompletePrimitive.Group
+      className={cn("[[role=group]+&]:mt-1.5", className)}
+      data-slot="autocomplete-group"
+      {...props}
+    />
+  );
+}
+
+export function AutocompleteGroupLabel({
+  className,
+  ...props
+}: AutocompletePrimitive.GroupLabel.Props): React.ReactElement {
+  return (
+    <AutocompletePrimitive.GroupLabel
+      className={cn(
+        "px-2 py-1.5 font-medium text-muted-foreground text-xs",
+        className,
+      )}
+      data-slot="autocomplete-group-label"
+      {...props}
+    />
+  );
+}
+
+export function AutocompleteEmpty({
+  className,
+  ...props
+}: AutocompletePrimitive.Empty.Props): React.ReactElement {
+  return (
+    <AutocompletePrimitive.Empty
+      className={cn(
+        "p-2 text-center text-base text-muted-foreground sm:text-sm empty:hidden",
+        className,
+      )}
+      data-slot="autocomplete-empty"
+      {...props}
+    />
+  );
+}
+
+export function AutocompleteTrigger({
+  className,
+  children,
+  ...props
+}: AutocompletePrimitive.Trigger.Props): React.ReactElement {
+  return (
+    <AutocompletePrimitive.Trigger
+      className={cn(
+        "absolute end-0.5 top-1/2 inline-flex size-8 shrink-0 -translate-y-1/2 cursor-pointer items-center justify-center rounded-md border border-transparent opacity-80 outline-none transition-colors pointer-coarse:after:absolute pointer-coarse:after:min-h-11 pointer-coarse:after:min-w-11 hover:opacity-100 sm:size-7 [&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+        className,
+      )}
+      data-slot="autocomplete-trigger"
+      {...props}
+    >
+      {children ?? (
+        <AutocompletePrimitive.Icon data-slot="autocomplete-icon">
+          <ChevronsUpDownIcon />
+        </AutocompletePrimitive.Icon>
+      )}
+    </AutocompletePrimitive.Trigger>
+  );
+}
+
+export function AutocompleteClear({
+  className,
+  children,
+  ...props
+}: AutocompletePrimitive.Clear.Props): React.ReactElement {
+  return (
+    <AutocompletePrimitive.Clear
+      className={cn(
+        "absolute end-0.5 top-1/2 inline-flex size-8 shrink-0 -translate-y-1/2 cursor-pointer items-center justify-center rounded-md border border-transparent opacity-80 outline-none transition-[color,background-color,box-shadow,opacity] pointer-coarse:after:absolute pointer-coarse:after:min-h-11 pointer-coarse:after:min-w-11 hover:opacity-100 sm:size-7 [&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+        className,
+      )}
+      data-slot="autocomplete-clear"
+      {...props}
+    >
+      {children ?? <XIcon />}
+    </AutocompletePrimitive.Clear>
+  );
+}
+
+/**
+ * Groups items into a horizontal row within the list.
+ * Use to create multi-column grid layouts (color swatches, icon grids, emoji pickers).
+ * Each `AutocompleteItem` inside the row remains fully keyboard-navigable.
+ *
+ * ```tsx
+ * <AutocompleteList>
+ *   {(row) => (
+ *     <AutocompleteRow key={row.id}>
+ *       {row.items.map((item) => (
+ *         <AutocompleteItem key={item.value} value={item}>
+ *           {item.label}
+ *         </AutocompleteItem>
+ *       ))}
+ *     </AutocompleteRow>
+ *   )}
+ * </AutocompleteList>
+ * ```
+ */
+export function AutocompleteRow({
+  className,
+  ...props
+}: AutocompletePrimitive.Row.Props): React.ReactElement {
+  return (
+    <AutocompletePrimitive.Row
+      className={className}
+      data-slot="autocomplete-row"
+      {...props}
+    />
+  );
+}
+
+/**
+ * Renders the selected value's label outside the input element.
+ * Useful when building custom trigger-style layouts where the selected item
+ * must be displayed independently — e.g., inside a badge, a button, or a custom
+ * trigger that replaces the input entirely.
+ * Renders nothing when no item is selected.
+ */
+export function AutocompleteValue({
+  ...props
+}: AutocompletePrimitive.Value.Props): React.ReactElement {
+  return (
+    <AutocompletePrimitive.Value data-slot="autocomplete-value" {...props} />
+  );
+}
+
+export function AutocompleteStatus({
+  className,
+  ...props
+}: AutocompletePrimitive.Status.Props): React.ReactElement {
+  return (
+    <AutocompletePrimitive.Status
+      className={cn(
+        "px-3 py-2 font-medium text-muted-foreground text-xs empty:m-0 empty:p-0",
+        className,
+      )}
+      data-slot="autocomplete-status"
+      {...props}
+    />
+  );
+}
+
+export function AutocompleteCollection({
+  ...props
+}: AutocompletePrimitive.Collection.Props): React.ReactElement {
+  return (
+    <AutocompletePrimitive.Collection
+      data-slot="autocomplete-collection"
+      {...props}
+    />
+  );
+}
+
+export const useAutocompleteFilter: typeof AutocompletePrimitive.useFilter =
+  AutocompletePrimitive.useFilter;
+
+// ─── Composite ───────────────────────────────────────────────────────────────
+export interface AutocompleteOption {
+  value: string;
+  label: string;
+}
+
+interface AutocompleteProps<
+  TOption extends AutocompleteOption = AutocompleteOption,
+> {
+  items: TOption[];
+  value?: TOption | null;
+  defaultValue?: TOption | null;
+  onValueChange?: (value: TOption | null) => void;
+  disabled?: boolean;
+  readOnly?: boolean;
+  isLoading?: boolean;
+  filter?: AutocompletePrimitive.Root.Props<TOption>["filter"];
+  autoHighlight?: boolean | "always";
+  placeholder?: string;
+  emptyMessage?: string;
+  loadingMessage?: string;
+  renderOption?: (option: TOption) => React.ReactNode;
+  adornment?: "trigger" | "clear";
+  startAddon?: React.ReactNode;
+  /** Styles the input field. */
+  className?: string;
+  /** Styles applied to each internal slot. */
+  classNames?: {
+    /** Dropdown popup container. */
+    popup?: string;
+    /** Scrollable list inside the popup. */
+    list?: string;
+    /** Each option item. */
+    item?: string;
+    /** Empty state message. */
+    empty?: string;
+    /** Status row (e.g. loading message). */
+    status?: string;
+  };
+}
+
+export function Autocomplete<
+  TOption extends AutocompleteOption = AutocompleteOption,
+>({
+  items,
+  value,
+  defaultValue,
+  onValueChange,
+  disabled,
+  readOnly,
+  isLoading = false,
+  filter,
+  autoHighlight,
+  placeholder = "Buscar...",
+  emptyMessage = "Sin resultados",
+  loadingMessage = "Cargando...",
+  renderOption,
+  adornment,
+  startAddon,
+  className,
+  classNames,
+}: AutocompleteProps<TOption>): React.ReactElement {
+  return (
+    <AutocompleteRoot
+      items={items}
+      value={value?.label}
+      defaultValue={defaultValue?.label}
+      onValueChange={(opt) =>
+        onValueChange?.((opt as unknown as TOption | undefined) ?? null)
+      }
+      disabled={disabled}
+      readOnly={readOnly}
+      filter={filter}
+      autoHighlight={autoHighlight}
+      itemToStringValue={(opt) => (opt as TOption).label}
+    >
+      <AutocompleteInput
+        adornment={adornment}
+        startAddon={startAddon}
+        placeholder={placeholder}
+        className={className}
+      />
+      <AutocompletePopup className={classNames?.popup}>
+        <AutocompleteStatus className={classNames?.status}>
+          {isLoading ? loadingMessage : undefined}
+        </AutocompleteStatus>
+        <AutocompleteList className={classNames?.list}>
+          {(option) => (
+            <AutocompleteItem
+              key={(option as TOption).value}
+              value={option}
+              className={classNames?.item}
+            >
+              {renderOption
+                ? renderOption(option as TOption)
+                : (option as TOption).label}
+            </AutocompleteItem>
+          )}
+        </AutocompleteList>
+        {!isLoading && (
+          <AutocompleteEmpty className={classNames?.empty}>
+            {emptyMessage}
+          </AutocompleteEmpty>
+        )}
+      </AutocompletePopup>
+    </AutocompleteRoot>
+  );
+}
+
+export { AutocompletePrimitive };

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

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

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

@@ -0,0 +1,225 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Check, User } from "lucide-react";
+import { action } from "storybook/actions";
+import {
+  Avatar,
+  AvatarBadge,
+  AvatarFallback,
+  AvatarGroup,
+  AvatarGroupCount,
+  AvatarImage,
+  AvatarRoot,
+} from "../../components";
+
+/**
+ * Circular user 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.
+ * Pass `badge` to render a status/notification dot via `AvatarBadge`.
+ * Exposes `AvatarRoot`, `AvatarImage`, `AvatarFallback`, `AvatarBadge`,
+ * `AvatarGroup`, `AvatarGroupCount` primitives for custom compositions.
+ */
+const meta: Meta<typeof Avatar> = {
+  title: "components/Avatar",
+  component: Avatar,
+  parameters: { layout: "centered" },
+  args: {
+    alt: "Sara Lane",
+    src: "https://i.pravatar.cc/150?img=47",
+    delay: 1000,
+  },
+} satisfies Meta<typeof Avatar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/**
+ * `className` styles the avatar root. `classNames` exposes the `image`,
+ * `fallback`, and `badge` slots for fine-grained styling without dropping
+ * to primitives.
+ */
+export const WithClassNames: Story = {
+  args: {
+    badge: <Check />,
+    className: "ring-2 ring-ring",
+    classNames: {
+      fallback: "bg-primary text-primary-foreground",
+      badge: "bg-emerald-500",
+    },
+  },
+};
+
+/**
+ * When `src` is empty or the image fails to load, initials are extracted from `alt` automatically.
+ */
+export const FallbackText: Story = {
+  args: {
+    src: "",
+  },
+};
+
+/**
+ * Pass any node to `fallback` to override the default initials — useful for generic
+ * placeholders, icons, or branded glyphs.
+ */
+export const CustomFallback: Story = {
+  args: {
+    src: "",
+    fallback: <User className="size-1/2" />,
+  },
+};
+
+export const Sizes: Story = {
+  render: (args) => (
+    <div className="flex items-end gap-6">
+      {(["xs", "sm", "md", "lg", "xl"] as const).map((size) => (
+        <div key={size} className="flex flex-col items-center gap-2">
+          <Avatar {...args} size={size} />
+          <span className="text-xs text-muted-foreground font-mono">
+            {size}
+          </span>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+/**
+ * `badge` mounts an `AvatarBadge` inside the root. The badge auto-scales with the
+ * avatar's `size` via `group-data-[size=*]/avatar` selectors and clips icons on
+ * the smallest sizes to keep the dot legible.
+ *
+ * For a plain status indicator, leave the badge empty (`<span />`) and override
+ * its color via `className`.
+ */
+export const Badge: Story = {
+  render: () => (
+    <div className="flex items-end gap-6">
+      {(["sm", "md", "lg", "xl"] as const).map((size) => (
+        <div key={size} className="flex flex-col items-center gap-2">
+          <Avatar
+            src="https://i.pravatar.cc/150?img=47"
+            alt="Sara Lane"
+            size={size}
+            badge={<Check />}
+          />
+          <span className="text-xs text-muted-foreground font-mono">
+            {size}
+          </span>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+/**
+ * Status pattern via `AvatarBadge` on the primitive. The badge's color comes
+ * from `className`, the position and ring from the primitive itself.
+ */
+export const Status: Story = {
+  render: () => (
+    <div className="flex items-center gap-6">
+      {(
+        [
+          { label: "online", color: "bg-emerald-500" },
+          { label: "away", color: "bg-amber-500" },
+          { label: "offline", color: "bg-zinc-400" },
+        ] as const
+      ).map(({ label, color }) => (
+        <div key={label} className="flex flex-col items-center gap-2">
+          <AvatarRoot size="lg">
+            <AvatarImage
+              src={`https://i.pravatar.cc/150?u=${label}`}
+              alt={label}
+            />
+            <AvatarFallback>{label.slice(0, 2).toUpperCase()}</AvatarFallback>
+            <AvatarBadge className={color} />
+          </AvatarRoot>
+          <span className="text-xs text-muted-foreground font-mono">
+            {label}
+          </span>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+/**
+ * `AvatarGroup` clusters avatars with negative spacing and applies a background
+ * ring to every direct `Avatar` child so they read as overlapping discs.
+ * Combine with `AvatarGroupCount` for the trailing `+N` slot. Match `size`
+ * across children and the count to scale the cluster.
+ */
+export const Group: Story = {
+  render: () => (
+    <AvatarGroup>
+      <Avatar src="https://i.pravatar.cc/150?img=47" alt="Sara Lane" />
+      <Avatar src="https://i.pravatar.cc/150?img=12" alt="John Doe" />
+      <Avatar src="https://i.pravatar.cc/150?img=32" alt="Alex Kim" />
+      <Avatar src="https://i.pravatar.cc/150?img=68" alt="Mia Chen" />
+      <AvatarGroupCount>+12</AvatarGroupCount>
+    </AvatarGroup>
+  ),
+};
+
+/**
+ * Direct composition with `AvatarRoot`, `AvatarImage`, `AvatarFallback`,
+ * `AvatarBadge` for full structural control. Use when the composite API
+ * doesn't expose what you need — custom children inside the fallback,
+ * layered overlays, etc.
+ *
+ * ```tsx
+ * <AvatarRoot size="lg">
+ *   <AvatarImage src={src} alt="John Doe" />
+ *   <AvatarFallback delay={1000}>JD</AvatarFallback>
+ *   <AvatarBadge className="bg-emerald-500" />
+ * </AvatarRoot>
+ * ```
+ */
+export const Primitive: Story = {
+  render: () => (
+    <AvatarRoot size="lg">
+      <AvatarImage src="https://i.pravatar.cc/150?img=13" alt="John Doe" />
+      <AvatarFallback delay={1000}>JD</AvatarFallback>
+      <AvatarBadge className="bg-emerald-500" />
+    </AvatarRoot>
+  ),
+};
+
+/**
+ * Avatars accept any `div` prop including `onClick`. Pair with `cursor-pointer`
+ * and a ring/hover style for interactive profile triggers.
+ */
+export const Clickable: Story = {
+  args: {
+    onClick: action("avatar:click"),
+    className:
+      "cursor-pointer ring-2 ring-transparent hover:ring-ring transition-shadow",
+  },
+};
+
+/**
+ * Real-world usage: avatar paired with name, role, and an `AvatarBadge`
+ * showing online status — canonical card layout for user lists, mentions,
+ * and team rosters.
+ */
+export const UserCard: Story = {
+  render: () => (
+    <div className="flex items-center gap-3 rounded-lg border bg-background p-4 shadow-sm">
+      <AvatarRoot size="lg">
+        <AvatarImage src="https://i.pravatar.cc/150?img=47" alt="Sara Lane" />
+        <AvatarFallback>SL</AvatarFallback>
+        <AvatarBadge className="bg-emerald-500" />
+      </AvatarRoot>
+      <div className="flex flex-col">
+        <span className="font-semibold leading-tight">Sara Lane</span>
+        <span className="text-sm text-muted-foreground leading-tight">
+          Senior Product Designer
+        </span>
+        <span className="text-xs text-muted-foreground mt-1">Active now</span>
+      </div>
+    </div>
+  ),
+};