@jcsoftdev/ui 0.1.6 → 0.2.0

package/src/ai/chat-list/chat-list.tsx

@@ -1,8 +1,9 @@
 "use client";
 
-import { Plus, Trash2 } from "lucide-react";
 import { useMemo } from "react";
 import { Button } from "../../atoms/button/button.js";
+import { Plus, Trash2 } from "../../icons/index.js";
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
 import { IconAction } from "../internal/icon-action.js";
 import { groupByDate } from "./group.js";
@@ -16,6 +17,19 @@ export interface ChatListItem {
   unread?: boolean;
 }
 
+export type ChatListPart =
+  | "root"
+  | "newButton"
+  | "empty"
+  | "group"
+  | "groupTitle"
+  | "list"
+  | "item"
+  | "row"
+  | "title"
+  | "preview"
+  | "delete";
+
 export interface ChatListProps {
   items: ChatListItem[];
   activeId?: string;
@@ -29,6 +43,8 @@ export interface ChatListProps {
   label?: string;
   emptyText?: string;
   className?: string;
+  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+  classNames?: ClassNames<ChatListPart>;
 }
 
 /** Sidebar list of conversations grouped by date (Hoy, Ayer, Últimos 7 días…). */
@@ -42,34 +58,53 @@ export function ChatList({
   label = "Conversaciones",
   emptyText = "Aún no hay conversaciones.",
   className,
+  classNames,
 }: ChatListProps) {
   const groups = useMemo(() => groupByDate(items, now ?? Date.now()), [items, now]);
 
   return (
     <nav
       aria-label={label}
-      className={cn("@container/chatlist grid min-w-0 content-start gap-density", className)}
+      className={cn(
+        "@container/chatlist grid min-w-0 content-start gap-density",
+        classNames?.root,
+        className,
+      )}
     >
       {onNew ? (
-        <Button variant="primary" size="sm" onClick={onNew} className="w-full">
+        <Button
+          variant="primary"
+          size="sm"
+          onClick={onNew}
+          className={cn("w-full", classNames?.newButton)}
+        >
           <Plus aria-hidden />
           Nueva conversación
         </Button>
       ) : null}
-      {groups.length === 0 ? <p className="px-2 text-meta text-ink-3">{emptyText}</p> : null}
+      {groups.length === 0 ? (
+        <p className={cn("px-2 text-meta text-ink-3", classNames?.empty)}>{emptyText}</p>
+      ) : null}
       {groups.map((group) => (
-        <section key={group.id} aria-labelledby={`chat-group-${group.id}`} className="grid gap-0.5">
+        <section
+          key={group.id}
+          aria-labelledby={`chat-group-${group.id}`}
+          className={cn("grid gap-0.5", classNames?.group)}
+        >
           <h3
             id={`chat-group-${group.id}`}
-            className="px-2 text-overline font-semibold uppercase text-ink-3"
+            className={cn(
+              "px-2 text-overline font-semibold uppercase text-ink-3",
+              classNames?.groupTitle,
+            )}
           >
             {group.label}
           </h3>
-          <ul className="grid gap-0.5">
+          <ul className={cn("grid gap-0.5", classNames?.list)}>
             {group.items.map((item) => {
               const active = item.id === activeId;
               return (
-                <li key={item.id} className="group/row relative">
+                <li key={item.id} className={cn("group/row relative", classNames?.item)}>
                   <button
                     type="button"
                     aria-current={active ? "true" : undefined}
@@ -80,6 +115,7 @@ export function ChatList({
                       active
                         ? "bg-accent-soft text-ink"
                         : "text-ink-2 hover:bg-surface-2 hover:text-ink",
+                      classNames?.row,
                     )}
                   >
                     <span className="flex min-w-0 items-center gap-1.5">
@@ -93,13 +129,19 @@ export function ChatList({
                         className={cn(
                           "truncate text-body",
                           item.unread || active ? "font-semibold" : "font-medium",
+                          classNames?.title,
                         )}
                       >
                         {item.title}
                       </span>
                     </span>
                     {item.preview ? (
-                      <span className="hidden truncate text-meta text-ink-3 @xs/chatlist:block">
+                      <span
+                        className={cn(
+                          "hidden truncate text-meta text-ink-3 @xs/chatlist:block",
+                          classNames?.preview,
+                        )}
+                      >
                         {item.preview}
                       </span>
                     ) : null}
@@ -108,7 +150,10 @@ export function ChatList({
                     <IconAction
                       label={`Eliminar ${item.title}`}
                       onClick={() => onDelete(item.id)}
-                      className="absolute right-1 top-1/2 -translate-y-1/2 opacity-0 focus-visible:opacity-100 group-hover/row:opacity-100 group-focus-within/row:opacity-100"
+                      className={cn(
+                        "absolute right-1 top-1/2 -translate-y-1/2 opacity-0 focus-visible:opacity-100 group-hover/row:opacity-100 group-focus-within/row:opacity-100",
+                        classNames?.delete,
+                      )}
                     >
                       <Trash2 aria-hidden />
                     </IconAction>

package/src/ai/chat-message/chat-message.tsx

@@ -1,6 +1,7 @@
-import { CircleAlert } from "lucide-react";
 import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import { Avatar } from "../../atoms/avatar/avatar.js";
+import { CircleAlert } from "../../icons/index.js";
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
 import { Loader } from "../loader/loader.js";
 import { Markdown } from "../markdown/markdown.js";
@@ -8,6 +9,8 @@ import { Markdown } from "../markdown/markdown.js";
 export type ChatRole = "user" | "assistant" | "system";
 export type ChatMessageStatus = "sending" | "streaming" | "done" | "error";
 
+export type ChatMessagePart = "root" | "avatar" | "content" | "bubble" | "error" | "time";
+
 export interface ChatMessageProps extends Omit<ComponentPropsWithoutRef<"article">, "content"> {
   author: ChatRole;
   /** Display name, also the avatar's accessible name. */
@@ -25,6 +28,8 @@ export interface ChatMessageProps extends Omit<ComponentPropsWithoutRef<"article
   footer?: ReactNode;
   /** Text of the failure line when `status` is `error`. */
   errorText?: string;
+  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+  classNames?: ClassNames<ChatMessagePart>;
 }
 
 /** One chat turn: avatar, bubble, status, streaming caret and an optional footer slot. */
@@ -39,6 +44,7 @@ export function ChatMessage({
   footer,
   errorText = "No se pudo enviar el mensaje.",
   className,
+  classNames,
   ...props
 }: ChatMessageProps) {
   const streaming = status === "streaming";
@@ -46,11 +52,16 @@ export function ChatMessage({
   if (author === "system") {
     return (
       <article
-        className={cn("flex justify-center", className)}
+        className={cn("flex justify-center", classNames?.root, className)}
         aria-label={name ?? "Sistema"}
         {...props}
       >
-        <p className="max-w-full rounded-badge bg-surface-sunken px-3 py-1 text-center text-meta text-ink-3">
+        <p
+          className={cn(
+            "max-w-full rounded-badge bg-surface-sunken px-3 py-1 text-center text-meta text-ink-3",
+            classNames?.bubble,
+          )}
+        >
           {children ?? content}
         </p>
       </article>
@@ -74,6 +85,7 @@ export function ChatMessage({
       className={cn(
         "@container/message flex min-w-0 gap-density-sm",
         user ? "flex-row-reverse" : "flex-row",
+        classNames?.root,
         className,
       )}
       {...props}
@@ -82,12 +94,13 @@ export function ChatMessage({
         name={name ?? (user ? "Tú" : "Asistente")}
         src={avatarSrc}
         highlighted={!user}
-        className="mt-0.5"
+        className={cn("mt-0.5", classNames?.avatar)}
       />
       <div
         className={cn(
           "grid min-w-0 max-w-[92%] gap-1 @md/message:max-w-[80%]",
           user && "justify-items-end",
+          classNames?.content,
         )}
       >
         <div
@@ -96,18 +109,24 @@ export function ChatMessage({
             user ? "bg-accent-soft text-ink" : "bg-surface-card text-ink border-card shadow-card",
             status === "error" && "bg-danger-soft",
             status === "sending" && "opacity-70",
+            classNames?.bubble,
           )}
         >
           {waiting ? <Loader size="sm" label="El asistente está escribiendo" /> : body}
         </div>
         {status === "error" ? (
-          <p role="alert" className="flex items-center gap-1 text-meta text-danger">
+          <p
+            role="alert"
+            className={cn("flex items-center gap-1 text-meta text-danger", classNames?.error)}
+          >
             <CircleAlert aria-hidden className="size-3.5 shrink-0" />
             {errorText}
           </p>
         ) : null}
         {time || status === "sending" ? (
-          <p className="text-meta text-ink-3">{status === "sending" ? "Enviando…" : time}</p>
+          <p className={cn("text-meta text-ink-3", classNames?.time)}>
+            {status === "sending" ? "Enviando…" : time}
+          </p>
         ) : null}
         {footer}
       </div>

package/src/ai/code-block/code-block.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import { Check, Copy } from "lucide-react";
 import { useMemo } from "react";
+import { Check, Copy } from "../../icons/index.js";
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
 import { IconAction } from "../internal/icon-action.js";
 import { useCopy } from "../internal/use-copy.js";
@@ -29,6 +30,8 @@ const LABELS = {
   sql: "SQL",
 };
 
+export type CodeBlockPart = "root" | "header" | "title" | "actions" | "pre" | "code";
+
 export interface CodeBlockProps {
   code: string;
   /** `ts`, `js`, `json`, `bash`, `go` or `sql` (aliases like `typescript` work); anything else is plain. */
@@ -38,10 +41,19 @@ export interface CodeBlockProps {
   /** Wrap long lines instead of scrolling horizontally. */
   wrap?: boolean;
   className?: string;
+  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+  classNames?: ClassNames<CodeBlockPart>;
 }
 
 /** Code with a language label, a copy button and a dependency-free syntax highlighter. */
-export function CodeBlock({ code, language, filename, wrap, className }: CodeBlockProps) {
+export function CodeBlock({
+  code,
+  language,
+  filename,
+  wrap,
+  className,
+  classNames,
+}: CodeBlockProps) {
   const { copied, copy } = useCopy();
   const tokens = useMemo(() => tokenize(code, language), [code, language]);
   const resolved = resolveLanguage(language);
@@ -51,12 +63,20 @@ export function CodeBlock({ code, language, filename, wrap, className }: CodeBlo
     <figure
       className={cn(
         "@container/code m-0 min-w-0 max-w-full overflow-hidden rounded-card bg-surface-sunken text-ink border-card shadow-card",
+        classNames?.root,
         className,
       )}
     >
-      <figcaption className="flex items-center justify-between gap-density-sm border-b-divider px-3 py-1">
-        <span className="min-w-0 truncate font-mono text-meta text-ink-3">{title}</span>
-        <span aria-live="polite" className="flex items-center gap-1">
+      <figcaption
+        className={cn(
+          "flex items-center justify-between gap-density-sm border-b-divider px-3 py-1",
+          classNames?.header,
+        )}
+      >
+        <span className={cn("min-w-0 truncate font-mono text-meta text-ink-3", classNames?.title)}>
+          {title}
+        </span>
+        <span aria-live="polite" className={cn("flex items-center gap-1", classNames?.actions)}>
           {copied ? <span className="text-meta text-success">Copiado</span> : null}
           <IconAction
             label={copied ? "Código copiado" : "Copiar código"}
@@ -70,11 +90,12 @@ export function CodeBlock({ code, language, filename, wrap, className }: CodeBlo
         // biome-ignore lint/a11y/noNoninteractiveTabindex: scrollable region must be keyboard reachable
         tabIndex={0}
         className={cn(
-          "m-0 p-3 font-mono text-[12.5px] leading-relaxed focus-visible:focus-ring",
+          "m-0 p-3 font-mono text-fs-125 leading-relaxed focus-visible:focus-ring",
           wrap ? "whitespace-pre-wrap break-words" : "overflow-x-auto",
+          classNames?.pre,
         )}
       >
-        <code>
+        <code className={classNames?.code}>
           {tokens.map((token, index) => (
             <span
               // biome-ignore lint/suspicious/noArrayIndexKey: tokens are positional and never reorder

package/src/ai/conversation/conversation.tsx

@@ -1,16 +1,21 @@
 "use client";
 
-import { ArrowDown } from "lucide-react";
 import { type ComponentPropsWithoutRef, useCallback, useEffect, useRef, useState } from "react";
+import { ArrowDown } from "../../icons/index.js";
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
 import { usePrefersReducedMotion } from "../../utils/reduced-motion.js";
 import { nextStuck, showJumpToLatest } from "./stick.js";
 
+export type ConversationPart = "root" | "scroller" | "content" | "jump";
+
 export interface ConversationProps extends Omit<ComponentPropsWithoutRef<"div">, "role"> {
   /** Accessible name of the message log. */
   label?: string;
   /** Label of the "jump to latest" button. */
   jumpLabel?: string;
+  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+  classNames?: ClassNames<ConversationPart>;
 }
 
 /**
@@ -21,6 +26,7 @@ export function Conversation({
   label = "Conversación",
   jumpLabel = "Ir al último mensaje",
   className,
+  classNames,
   children,
   ...props
 }: ConversationProps) {
@@ -59,8 +65,12 @@ export function Conversation({
 
   return (
     <div
-      className={cn("@container/conversation relative h-full min-h-0 min-w-0", className)}
       {...props}
+      className={cn(
+        "@container/conversation relative h-full min-h-0 min-w-0",
+        classNames?.root,
+        className,
+      )}
     >
       <div
         ref={scroller}
@@ -71,9 +81,15 @@ export function Conversation({
         // biome-ignore lint/a11y/noNoninteractiveTabindex: scrollable log must be keyboard reachable
         tabIndex={0}
         onScroll={onScroll}
-        className="h-full overflow-y-auto overscroll-contain focus-visible:focus-ring"
+        className={cn(
+          "h-full overflow-y-auto overscroll-contain focus-visible:focus-ring",
+          classNames?.scroller,
+        )}
       >
-        <div ref={content} className="mx-auto grid w-full max-w-3xl gap-density-lg p-card">
+        <div
+          ref={content}
+          className={cn("mx-auto grid w-full max-w-3xl gap-density-lg p-card", classNames?.content)}
+        >
           {children}
         </div>
       </div>
@@ -86,7 +102,10 @@ export function Conversation({
             setJump(false);
             toBottom(!reduced);
           }}
-          className="absolute bottom-3 left-1/2 inline-flex h-control-sm -translate-x-1/2 cursor-pointer items-center gap-1.5 rounded-button bg-surface-overlay px-3 text-meta text-ink shadow-overlay border-control surface-overlay pressable focus-visible:focus-ring"
+          className={cn(
+            "absolute bottom-3 left-1/2 inline-flex h-control-sm -translate-x-1/2 cursor-pointer items-center gap-1.5 rounded-button bg-surface-overlay px-3 text-meta text-ink shadow-overlay border-control surface-overlay pressable focus-visible:focus-ring",
+            classNames?.jump,
+          )}
         >
           <ArrowDown aria-hidden className="size-3.5" />
           <span className="truncate">Más reciente</span>

package/src/ai/internal/disclosure.tsx

@@ -1,7 +1,7 @@
 "use client";
 
-import { ChevronDown } from "lucide-react";
 import { type ReactNode, useId, useState } from "react";
+import { ChevronDown } from "../../icons/index.js";
 import { cn } from "../../utils/cn.js";
 
 export interface DisclosureProps {
@@ -13,6 +13,8 @@ export interface DisclosureProps {
   onOpenChange?: (open: boolean) => void;
   className?: string;
   panelClassName?: string;
+  /** Classes for the header button. */
+  triggerClassName?: string;
 }
 
 /** Header button + animated panel. Closed content is `inert`, so it leaves the tab order. */
@@ -24,6 +26,7 @@ export function Disclosure({
   onOpenChange,
   className,
   panelClassName,
+  triggerClassName,
 }: DisclosureProps) {
   const [state, setState] = useState(defaultOpen);
   const open = openProp ?? state;
@@ -39,7 +42,10 @@ export function Disclosure({
         aria-expanded={open}
         aria-controls={panelId}
         onClick={toggle}
-        className="flex w-full min-w-0 cursor-pointer items-center gap-density-sm rounded-button text-left focus-visible:focus-ring"
+        className={cn(
+          "flex w-full min-w-0 cursor-pointer items-center gap-density-sm rounded-button text-left focus-visible:focus-ring",
+          triggerClassName,
+        )}
       >
         <span className="flex min-w-0 flex-1 items-center gap-density-sm">{header}</span>
         <ChevronDown

package/src/ai/loader/loader.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
 import { usePrefersReducedMotion } from "../../utils/reduced-motion.js";
 import { AiKeyframes } from "../internal/keyframes.js";
@@ -7,6 +8,8 @@ import { AiKeyframes } from "../internal/keyframes.js";
 export type LoaderVariant = "dots" | "typing";
 export type LoaderSize = "sm" | "md";
 
+export type LoaderPart = "root" | "dots" | "dot" | "label";
+
 export interface LoaderProps {
   /** `dots` is the bare indicator; `typing` wraps it in a bubble with a label. */
   variant?: LoaderVariant;
@@ -14,6 +17,8 @@ export interface LoaderProps {
   /** Spoken label (`role="status"`); shown as text in the `typing` variant. */
   label?: string;
   className?: string;
+  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+  classNames?: ClassNames<LoaderPart>;
 }
 
 const dotSize: Record<LoaderSize, string> = { sm: "size-1", md: "size-1.5" };
@@ -24,14 +29,15 @@ export function Loader({
   size = "md",
   label = "Escribiendo…",
   className,
+  classNames,
 }: LoaderProps) {
   const reduced = usePrefersReducedMotion();
   const dots = (
-    <span aria-hidden className="inline-flex items-center gap-1">
+    <span aria-hidden className={cn("inline-flex items-center gap-1", classNames?.dots)}>
       {[0, 1, 2].map((n) => (
         <span
           key={n}
-          className={cn("rounded-full bg-current opacity-60", dotSize[size])}
+          className={cn("rounded-full bg-current opacity-60", dotSize[size], classNames?.dot)}
           style={
             reduced
               ? undefined
@@ -49,12 +55,17 @@ export function Loader({
         "inline-flex items-center gap-density-sm text-ink-3",
         variant === "typing" &&
           "rounded-card bg-surface-card px-control-x py-2 text-meta shadow-card border-card",
+        classNames?.root,
         className,
       )}
     >
       <AiKeyframes />
       {dots}
-      {variant === "typing" ? <span>{label}</span> : <span className="sr-only">{label}</span>}
+      {variant === "typing" ? (
+        <span className={classNames?.label}>{label}</span>
+      ) : (
+        <span className={cn("sr-only", classNames?.label)}>{label}</span>
+      )}
     </span>
   );
 }