@jcsoftdev/ui 0.1.6 → 0.2.0

package/src/ai/markdown/markdown.tsx

@@ -1,20 +1,41 @@
 import { Fragment, type ReactNode } from "react";
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
 import { CodeBlock } from "../code-block/code-block.js";
 import { AiKeyframes } from "../internal/keyframes.js";
 import { type Block, type Inline, parseMarkdown } from "./parse.js";
 
-function Caret() {
+export type MarkdownPart =
+  | "root"
+  | "heading"
+  | "paragraph"
+  | "list"
+  | "listItem"
+  | "inlineCode"
+  | "link"
+  | "quote"
+  | "rule"
+  | "tableWrapper"
+  | "table"
+  | "tableHead"
+  | "tableHeaderCell"
+  | "tableRow"
+  | "tableCell"
+  | "caret";
+
+type Cx = ClassNames<MarkdownPart>;
+
+function Caret({ cx }: { cx: Cx }) {
   return (
     <span
       aria-hidden
-      className="ml-0.5 inline-block h-[1em] w-[2px] translate-y-[2px] bg-current"
+      className={cn("ml-0.5 inline-block h-[1em] w-[2px] translate-y-[2px] bg-current", cx.caret)}
       style={{ animation: "ui-ai-caret 1s steps(1) infinite" }}
     />
   );
 }
 
-function renderInline(nodes: Inline[]): ReactNode {
+function renderInline(nodes: Inline[], cx: Cx): ReactNode {
   return nodes.map((node, index) => {
     const key = index;
     switch (node.t) {
@@ -26,15 +47,18 @@ function renderInline(nodes: Inline[]): ReactNode {
         return (
           <code
             key={key}
-            className="rounded-badge bg-surface-sunken px-1 py-0.5 font-mono text-[0.9em]"
+            className={cn(
+              "rounded-badge bg-surface-sunken px-1 py-0.5 font-mono text-[0.9em]",
+              cx.inlineCode,
+            )}
           >
             {node.v}
           </code>
         );
       case "strong":
-        return <strong key={key}>{renderInline(node.c)}</strong>;
+        return <strong key={key}>{renderInline(node.c, cx)}</strong>;
       case "em":
-        return <em key={key}>{renderInline(node.c)}</em>;
+        return <em key={key}>{renderInline(node.c, cx)}</em>;
       case "link":
         return node.href ? (
           <a
@@ -42,12 +66,15 @@ function renderInline(nodes: Inline[]): ReactNode {
             href={node.href}
             target="_blank"
             rel="noopener noreferrer nofollow"
-            className="text-accent-ink underline underline-offset-2 focus-visible:focus-ring"
+            className={cn(
+              "text-accent-ink underline underline-offset-2 focus-visible:focus-ring",
+              cx.link,
+            )}
           >
-            {renderInline(node.c)}
+            {renderInline(node.c, cx)}
           </a>
         ) : (
-          <span key={key}>{renderInline(node.c)}</span>
+          <span key={key}>{renderInline(node.c, cx)}</span>
         );
       default:
         return null;
@@ -66,22 +93,22 @@ const HEADINGS = {
 
 const ALIGN = { left: "text-left", center: "text-center", right: "text-right" } as const;
 
-function renderBlock(block: Block, key: number, caret: boolean): ReactNode {
-  const tail = caret ? <Caret /> : null;
+function renderBlock(block: Block, key: number, caret: boolean, cx: Cx): ReactNode {
+  const tail = caret ? <Caret cx={cx} /> : null;
   switch (block.t) {
     case "heading": {
       const Tag = `h${block.level}` as "h1";
       return (
-        <Tag key={key} className={HEADINGS[block.level]}>
-          {renderInline(block.c)}
+        <Tag key={key} className={cn(HEADINGS[block.level], cx.heading)}>
+          {renderInline(block.c, cx)}
           {tail}
         </Tag>
       );
     }
     case "p":
       return (
-        <p key={key}>
-          {renderInline(block.c)}
+        <p key={key} className={cx.paragraph}>
+          {renderInline(block.c, cx)}
           {tail}
         </p>
       );
@@ -91,18 +118,18 @@ function renderBlock(block: Block, key: number, caret: boolean): ReactNode {
         <Tag
           key={key}
           start={block.ordered && block.start !== 1 ? block.start : undefined}
-          className={cn("grid gap-1 pl-5", block.ordered ? "list-decimal" : "list-disc")}
+          className={cn("grid gap-1 pl-5", block.ordered ? "list-decimal" : "list-disc", cx.list)}
         >
           {block.items.map((item, index) => (
             // biome-ignore lint/suspicious/noArrayIndexKey: list items are positional
-            <li key={index} className="pl-1">
-              {renderInline(item.c)}
+            <li key={index} className={cn("pl-1", cx.listItem)}>
+              {renderInline(item.c, cx)}
               {caret && index === block.items.length - 1 && item.children.length === 0 ? (
-                <Caret />
+                <Caret cx={cx} />
               ) : null}
               {item.children.length > 0 ? (
                 <div className="mt-1 grid gap-1">
-                  {renderBlocks(item.children, caret && index === block.items.length - 1)}
+                  {renderBlocks(item.children, caret && index === block.items.length - 1, cx)}
                 </div>
               ) : null}
             </li>
@@ -119,17 +146,26 @@ function renderBlock(block: Block, key: number, caret: boolean): ReactNode {
       );
     case "quote":
       return (
-        <blockquote key={key} className="grid gap-2 border-l-2 border-accent-line pl-3 text-ink-2">
-          {renderBlocks(block.c, caret)}
+        <blockquote
+          key={key}
+          className={cn("grid gap-2 border-l-2 border-accent-line pl-3 text-ink-2", cx.quote)}
+        >
+          {renderBlocks(block.c, caret, cx)}
         </blockquote>
       );
     case "hr":
-      return <hr key={key} className="border-0 border-t-divider" />;
+      return <hr key={key} className={cn("border-0 border-t-divider", cx.rule)} />;
     case "table":
       return (
-        <div key={key} className="max-w-full overflow-x-auto rounded-card border-card shadow-card">
-          <table className="w-full border-collapse text-meta">
-            <thead className="bg-surface-sunken">
+        <div
+          key={key}
+          className={cn(
+            "max-w-full overflow-x-auto rounded-card border-card shadow-card",
+            cx.tableWrapper,
+          )}
+        >
+          <table className={cn("w-full border-collapse text-meta", cx.table)}>
+            <thead className={cn("bg-surface-sunken", cx.tableHead)}>
               <tr>
                 {block.head.map((cell, col) => (
                   <th
@@ -141,9 +177,10 @@ function renderBlock(block: Block, key: number, caret: boolean): ReactNode {
                       block.align[col]
                         ? ALIGN[block.align[col] as keyof typeof ALIGN]
                         : "text-left",
+                      cx.tableHeaderCell,
                     )}
                   >
-                    {renderInline(cell)}
+                    {renderInline(cell, cx)}
                   </th>
                 ))}
               </tr>
@@ -151,7 +188,7 @@ function renderBlock(block: Block, key: number, caret: boolean): ReactNode {
             <tbody>
               {block.rows.map((row, r) => (
                 // biome-ignore lint/suspicious/noArrayIndexKey: rows are positional
-                <tr key={r} className="border-t-divider">
+                <tr key={r} className={cn("border-t-divider", cx.tableRow)}>
                   {row.map((cell, col) => (
                     <td
                       // biome-ignore lint/suspicious/noArrayIndexKey: columns are positional
@@ -161,9 +198,10 @@ function renderBlock(block: Block, key: number, caret: boolean): ReactNode {
                         block.align[col]
                           ? ALIGN[block.align[col] as keyof typeof ALIGN]
                           : "text-left",
+                        cx.tableCell,
                       )}
                     >
-                      {renderInline(cell)}
+                      {renderInline(cell, cx)}
                     </td>
                   ))}
                 </tr>
@@ -175,9 +213,9 @@ function renderBlock(block: Block, key: number, caret: boolean): ReactNode {
   }
 }
 
-function renderBlocks(blocks: Block[], caret: boolean): ReactNode {
+function renderBlocks(blocks: Block[], caret: boolean, cx: Cx): ReactNode {
   return blocks.map((block, index) =>
-    renderBlock(block, index, caret && index === blocks.length - 1),
+    renderBlock(block, index, caret && index === blocks.length - 1, cx),
   );
 }
 
@@ -187,23 +225,30 @@ export interface MarkdownProps {
   /** Shows a blinking caret after the last character, for streaming answers. */
   streaming?: boolean;
   className?: string;
+  /** Per-element classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+  classNames?: ClassNames<MarkdownPart>;
 }
 
 /**
  * Safe Markdown renderer: headings, lists, emphasis, inline code, code fences, quotes, tables
  * and links. It builds React elements from a parsed AST, so no input ever reaches innerHTML.
  */
-export function Markdown({ children, streaming, className }: MarkdownProps) {
+export function Markdown({ children, streaming, className, classNames }: MarkdownProps) {
+  const cx: Cx = classNames ?? {};
   const blocks = parseMarkdown(children);
   return (
     <div
-      className={cn("grid min-w-0 gap-density break-words text-body leading-relaxed", className)}
+      className={cn(
+        "grid min-w-0 gap-density break-words text-body leading-relaxed",
+        className,
+        cx.root,
+      )}
     >
       {streaming ? <AiKeyframes /> : null}
-      {renderBlocks(blocks, Boolean(streaming))}
+      {renderBlocks(blocks, Boolean(streaming), cx)}
       {streaming && blocks.length === 0 ? (
         <p>
-          <Caret />
+          <Caret cx={cx} />
         </p>
       ) : null}
     </div>

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

@@ -1,7 +1,7 @@
 "use client";
 
-import { Check, Copy, RefreshCw, ThumbsDown, ThumbsUp } from "lucide-react";
 import { type ComponentPropsWithoutRef, useState } from "react";
+import { Check, Copy, RefreshCw, ThumbsDown, ThumbsUp } from "../../icons/index.js";
 import { cn } from "../../utils/cn.js";
 import { IconAction } from "../internal/icon-action.js";
 import { useCopy } from "../internal/use-copy.js";

package/src/ai/prompt-input/prompt-input.tsx

@@ -1,6 +1,5 @@
 "use client";
 
-import { ArrowUp, Square } from "lucide-react";
 import {
   type FormEvent,
   type KeyboardEvent,
@@ -9,9 +8,22 @@ import {
   useRef,
   useState,
 } from "react";
+import { ArrowUp, Square } from "../../icons/index.js";
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
 import { shouldSubmit } from "./keys.js";
 
+export type PromptInputPart =
+  | "root"
+  | "box"
+  | "attachments"
+  | "textarea"
+  | "toolbar"
+  | "actions"
+  | "send"
+  | "stop"
+  | "hint";
+
 export interface PromptInputProps {
   value?: string;
   defaultValue?: string;
@@ -34,6 +46,8 @@ export interface PromptInputProps {
   /** Hint line under the field. */
   hint?: ReactNode;
   className?: string;
+  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+  classNames?: ClassNames<PromptInputPart>;
 }
 
 /**
@@ -55,6 +69,7 @@ export function PromptInput({
   actions,
   hint,
   className,
+  classNames,
 }: PromptInputProps) {
   const [state, setState] = useState(defaultValue);
   const value = valueProp ?? state;
@@ -106,9 +121,21 @@ export function PromptInput({
   const canSend = value.trim().length > 0 && !disabled;
 
   return (
-    <form onSubmit={onFormSubmit} className={cn("@container/prompt grid min-w-0 gap-1", className)}>
-      <div className="grid gap-density-sm rounded-card bg-surface-control p-2 text-ink border-control shadow-control focus-within:focus-ring">
-        {attachments ? <div className="flex flex-wrap gap-density-sm">{attachments}</div> : null}
+    <form
+      onSubmit={onFormSubmit}
+      className={cn("@container/prompt grid min-w-0 gap-1", classNames?.root, className)}
+    >
+      <div
+        className={cn(
+          "grid gap-density-sm rounded-card bg-surface-control p-2 text-ink border-control shadow-control focus-within:focus-ring",
+          classNames?.box,
+        )}
+      >
+        {attachments ? (
+          <div className={cn("flex flex-wrap gap-density-sm", classNames?.attachments)}>
+            {attachments}
+          </div>
+        ) : null}
         <textarea
           ref={area}
           rows={1}
@@ -118,15 +145,25 @@ export function PromptInput({
           placeholder={placeholder}
           onChange={(event) => set(event.target.value)}
           onKeyDown={onKeyDown}
-          className="block max-h-none w-full min-w-0 resize-none bg-transparent px-1 py-1 text-body leading-normal text-ink outline-none placeholder:text-ink-3 disabled:cursor-not-allowed"
+          className={cn(
+            "block max-h-none w-full min-w-0 resize-none bg-transparent px-1 py-1 text-body leading-normal text-ink outline-none placeholder:text-ink-3 disabled:cursor-not-allowed",
+            classNames?.textarea,
+          )}
         />
-        <div className="flex items-center justify-between gap-density-sm">
-          <div className="flex min-w-0 items-center gap-density-sm">{actions}</div>
+        <div
+          className={cn("flex items-center justify-between gap-density-sm", classNames?.toolbar)}
+        >
+          <div className={cn("flex min-w-0 items-center gap-density-sm", classNames?.actions)}>
+            {actions}
+          </div>
           {streaming ? (
             <button
               type="submit"
               aria-label="Detener respuesta"
-              className="inline-grid size-8 shrink-0 cursor-pointer place-items-center rounded-button bg-ink text-bg pressable focus-visible:focus-ring"
+              className={cn(
+                "inline-grid size-8 shrink-0 cursor-pointer place-items-center rounded-button bg-ink text-bg pressable focus-visible:focus-ring",
+                classNames?.stop,
+              )}
             >
               <Square aria-hidden className="size-3.5 fill-current" />
             </button>
@@ -135,14 +172,17 @@ export function PromptInput({
               type="submit"
               aria-label="Enviar mensaje"
               disabled={!canSend}
-              className="inline-grid size-8 shrink-0 cursor-pointer place-items-center rounded-button bg-accent text-on-accent pressable focus-visible:focus-ring disabled:cursor-not-allowed disabled:opacity-45"
+              className={cn(
+                "inline-grid size-8 shrink-0 cursor-pointer place-items-center rounded-button bg-accent text-on-accent pressable focus-visible:focus-ring disabled:cursor-not-allowed disabled:opacity-45",
+                classNames?.send,
+              )}
             >
               <ArrowUp aria-hidden className="size-4" />
             </button>
           )}
         </div>
       </div>
-      {hint ? <p className="px-1 text-meta text-ink-3">{hint}</p> : null}
+      {hint ? <p className={cn("px-1 text-meta text-ink-3", classNames?.hint)}>{hint}</p> : null}
     </form>
   );
 }

package/src/ai/source/source.tsx

@@ -4,9 +4,19 @@ import {
   HoverCardContent,
   HoverCardTrigger,
 } from "../../overlays/hover-card/hover-card.js";
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
 import { safeHref } from "../markdown/parse.js";
 
+export type SourcePart =
+  | "root"
+  | "index"
+  | "host"
+  | "card"
+  | "cardHost"
+  | "cardTitle"
+  | "cardSnippet";
+
 export interface SourceProps extends Omit<ComponentPropsWithoutRef<"a">, "href" | "title"> {
   /** Citation number shown in the chip. */
   index?: number;
@@ -15,6 +25,8 @@ export interface SourceProps extends Omit<ComponentPropsWithoutRef<"a">, "href"
   url: string;
   /** Short excerpt shown in the hover preview. */
   snippet?: string;
+  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+  classNames?: ClassNames<SourcePart>;
 }
 
 function hostOf(url: string): string {
@@ -26,21 +38,35 @@ function hostOf(url: string): string {
 }
 
 /** Citation chip with a hover/focus preview of the source (title, host and excerpt). */
-export function Source({ index, title, url, snippet, className, ...props }: SourceProps) {
+export function Source({
+  index,
+  title,
+  url,
+  snippet,
+  className,
+  classNames,
+  ...props
+}: SourceProps) {
   const href = safeHref(url);
   const host = hostOf(url);
   const chipClass = cn(
     "inline-flex h-control-sm min-w-0 max-w-full items-center gap-1.5 rounded-badge bg-surface-control px-2 text-meta text-ink-2 no-underline border-control shadow-control pressable hover:text-ink focus-visible:focus-ring",
+    classNames?.root,
     className,
   );
   const chip = (
     <>
       {index != null ? (
-        <span className="grid size-4 shrink-0 place-items-center rounded-badge bg-accent-soft text-[10px] font-bold text-accent-ink">
+        <span
+          className={cn(
+            "grid size-4 shrink-0 place-items-center rounded-badge bg-accent-soft text-fs-100 font-bold text-accent-ink",
+            classNames?.index,
+          )}
+        >
           {index}
         </span>
       ) : null}
-      <span className="truncate">{host}</span>
+      <span className={cn("truncate", classNames?.host)}>{host}</span>
     </>
   );
 
@@ -63,10 +89,21 @@ export function Source({ index, title, url, snippet, className, ...props }: Sour
           </button>
         )}
       </HoverCardTrigger>
-      <HoverCardContent className="@container/source w-72 max-w-[calc(100vw-1rem)] rounded-popover bg-surface-overlay p-3 text-ink shadow-overlay border-control surface-overlay">
-        <p className="text-meta text-ink-3">{host}</p>
-        <p className="mt-0.5 line-clamp-2 text-body font-semibold">{title}</p>
-        {snippet ? <p className="mt-1 line-clamp-4 text-meta text-ink-2">{snippet}</p> : null}
+      <HoverCardContent
+        className={cn(
+          "@container/source w-72 max-w-[calc(100vw-1rem)] rounded-popover bg-surface-overlay p-3 text-ink shadow-overlay border-control surface-overlay",
+          classNames?.card,
+        )}
+      >
+        <p className={cn("text-meta text-ink-3", classNames?.cardHost)}>{host}</p>
+        <p className={cn("mt-0.5 line-clamp-2 text-body font-semibold", classNames?.cardTitle)}>
+          {title}
+        </p>
+        {snippet ? (
+          <p className={cn("mt-1 line-clamp-4 text-meta text-ink-2", classNames?.cardSnippet)}>
+            {snippet}
+          </p>
+        ) : null}
       </HoverCardContent>
     </HoverCard>
   );

package/src/ai/tool-call/tool-call.tsx

@@ -1,5 +1,6 @@
-import { Check, CircleAlert, Clock, LoaderCircle, Wrench } from "lucide-react";
 import { useMemo } from "react";
+import { Check, CircleAlert, Clock, LoaderCircle, Wrench } from "../../icons/index.js";
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
 import { CodeBlock } from "../code-block/code-block.js";
 import { Disclosure } from "../internal/disclosure.js";
@@ -21,6 +22,18 @@ function StatusIcon({ status }: { status: ToolCallStatus }) {
   return <Clock aria-hidden className={cls} />;
 }
 
+export type ToolCallPart =
+  | "root"
+  | "header"
+  | "body"
+  | "name"
+  | "status"
+  | "panel"
+  | "section"
+  | "sectionTitle"
+  | "code"
+  | "error";
+
 export interface ToolCallProps {
   /** Tool identifier, e.g. `buscar_turnos`. */
   name: string;
@@ -35,6 +48,8 @@ export interface ToolCallProps {
   duration?: string;
   defaultOpen?: boolean;
   className?: string;
+  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+  classNames?: ClassNames<ToolCallPart>;
 }
 
 const pretty = (value: unknown) =>
@@ -50,6 +65,7 @@ export function ToolCall({
   duration,
   defaultOpen = false,
   className,
+  classNames,
 }: ToolCallProps) {
   const info = STATUS[status];
   const argsText = useMemo(() => (args === undefined ? null : pretty(args)), [args]);
@@ -59,16 +75,28 @@ export function ToolCall({
     <div
       className={cn(
         "@container/tool min-w-0 rounded-card bg-surface-card p-2 text-ink border-card shadow-card",
+        classNames?.root,
         className,
       )}
     >
       <Disclosure
         defaultOpen={defaultOpen}
+        triggerClassName={classNames?.header}
         header={
           <>
             <Wrench aria-hidden className="size-3.5 shrink-0 text-ink-3" />
-            <span className="min-w-0 truncate font-mono text-meta font-medium">{name}</span>
-            <span className={cn("ml-auto flex shrink-0 items-center gap-1 text-meta", info.tone)}>
+            <span
+              className={cn("min-w-0 truncate font-mono text-meta font-medium", classNames?.name)}
+            >
+              {name}
+            </span>
+            <span
+              className={cn(
+                "ml-auto flex shrink-0 items-center gap-1 text-meta",
+                info.tone,
+                classNames?.status,
+              )}
+            >
               <StatusIcon status={status} />
               <span className="hidden @xs/tool:inline">{info.label}</span>
               <span className="sr-only @xs/tool:hidden">{info.label}</span>
@@ -78,27 +106,34 @@ export function ToolCall({
             </span>
           </>
         }
-        panelClassName="grid gap-density-sm"
+        panelClassName={cn("grid gap-density-sm", classNames?.panel)}
       >
-        <div className="grid gap-density-sm pt-density-sm">
+        <div className={cn("grid gap-density-sm pt-density-sm", classNames?.body)}>
           {argsText ? (
-            <section aria-label="Argumentos" className="grid gap-1">
-              <h4 className="text-meta font-semibold text-ink-2">Argumentos</h4>
-              <CodeBlock code={argsText} language="json" />
+            <section aria-label="Argumentos" className={cn("grid gap-1", classNames?.section)}>
+              <h4 className={cn("text-meta font-semibold text-ink-2", classNames?.sectionTitle)}>
+                Argumentos
+              </h4>
+              <CodeBlock code={argsText} language="json" className={classNames?.code} />
             </section>
           ) : null}
           {status === "error" && error ? (
             <p
               role="alert"
-              className="rounded-badge bg-danger-soft px-2 py-1 text-meta text-danger"
+              className={cn(
+                "rounded-badge bg-danger-soft px-2 py-1 text-meta text-danger",
+                classNames?.error,
+              )}
             >
               {error}
             </p>
           ) : null}
           {resultText ? (
-            <section aria-label="Resultado" className="grid gap-1">
-              <h4 className="text-meta font-semibold text-ink-2">Resultado</h4>
-              <CodeBlock code={resultText} language="json" />
+            <section aria-label="Resultado" className={cn("grid gap-1", classNames?.section)}>
+              <h4 className={cn("text-meta font-semibold text-ink-2", classNames?.sectionTitle)}>
+                Resultado
+              </h4>
+              <CodeBlock code={resultText} language="json" className={classNames?.code} />
             </section>
           ) : null}
         </div>