@jcsoftdev/ui 0.1.6 → 0.2.0

package/src/forms/emoji-reaction-button/emoji-reaction-button.tsx

@@ -1,11 +1,14 @@
 "use client";
 
-import * as PopoverPrimitive from "@radix-ui/react-popover";
-import { SmilePlus } from "lucide-react";
 import { useState } from "react";
+import { SmilePlus } from "../../icons/index.js";
+import * as PopoverPrimitive from "../../primitives/popover/popover.js";
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
 import { EmojiPicker } from "../emoji-picker/emoji-picker.js";
 
+export type EmojiReactionButtonPart = "root" | "emoji" | "count";
+
 export interface EmojiReactionButtonProps {
   emoji: string;
   count: number;
@@ -14,6 +17,8 @@ export interface EmojiReactionButtonProps {
   onToggle?: (reacted: boolean) => void;
   disabled?: boolean;
   className?: string;
+  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+  classNames?: ClassNames<EmojiReactionButtonPart>;
 }
 
 /** Reaction chip: an emoji with its count, pressed when the current user reacted. */
@@ -24,6 +29,7 @@ export function EmojiReactionButton({
   onToggle,
   disabled,
   className,
+  classNames,
 }: EmojiReactionButtonProps) {
   return (
     <button
@@ -34,11 +40,16 @@ export function EmojiReactionButton({
       onClick={() => onToggle?.(!reacted)}
       className={cn(
         "pressable inline-flex h-control-sm items-center gap-1.5 rounded-badge border-control bg-surface-control px-2.5 text-control text-ink-2 tabular-nums hover:bg-surface-sunken focus-visible:focus-ring disabled:cursor-not-allowed disabled:opacity-50 aria-pressed:border-accent aria-pressed:bg-accent-soft aria-pressed:text-accent-ink",
+        classNames?.root,
         className,
       )}
     >
-      <span aria-hidden="true">{emoji}</span>
-      <span aria-hidden="true">{count}</span>
+      <span aria-hidden="true" className={classNames?.emoji}>
+        {emoji}
+      </span>
+      <span aria-hidden="true" className={classNames?.count}>
+        {count}
+      </span>
     </button>
   );
 }
@@ -49,6 +60,8 @@ export interface Reaction {
   reacted?: boolean;
 }
 
+export type EmojiReactionBarPart = "root" | "reaction" | "add" | "popover" | "picker";
+
 export interface EmojiReactionBarProps {
   reactions: Reaction[];
   /** Called with the emoji and the new reacted state, from a chip or from the picker. */
@@ -58,6 +71,8 @@ export interface EmojiReactionBarProps {
   addLabel?: string;
   disabled?: boolean;
   className?: string;
+  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+  classNames?: ClassNames<EmojiReactionBarPart>;
 }
 
 /** Row of reaction chips plus an "add reaction" button that opens an emoji picker. */
@@ -68,16 +83,22 @@ export function EmojiReactionBar({
   addLabel = "Añadir reacción",
   disabled,
   className,
+  classNames,
 }: EmojiReactionBarProps) {
   const [open, setOpen] = useState(false);
   return (
     <div
-      className={cn("@container/reactions flex flex-wrap items-center gap-density-sm", className)}
+      className={cn(
+        "@container/reactions flex flex-wrap items-center gap-density-sm",
+        classNames?.root,
+        className,
+      )}
     >
       {reactions.map((reaction) => (
         <EmojiReactionButton
           key={reaction.emoji}
           {...reaction}
+          className={classNames?.reaction}
           disabled={disabled}
           onToggle={(next) => onReact?.(reaction.emoji, next)}
         />
@@ -86,7 +107,10 @@ export function EmojiReactionBar({
         <PopoverPrimitive.Trigger
           disabled={disabled}
           aria-label={addLabel}
-          className="pressable grid aspect-square h-control-sm place-items-center rounded-badge border-control bg-surface-control text-ink-3 hover:text-ink focus-visible:focus-ring disabled:cursor-not-allowed disabled:opacity-50"
+          className={cn(
+            "pressable grid aspect-square h-control-sm place-items-center rounded-badge border-control bg-surface-control text-ink-3 hover:text-ink focus-visible:focus-ring disabled:cursor-not-allowed disabled:opacity-50",
+            classNames?.add,
+          )}
         >
           <SmilePlus aria-hidden="true" className="size-4" />
         </PopoverPrimitive.Trigger>
@@ -94,10 +118,13 @@ export function EmojiReactionBar({
           <PopoverPrimitive.Content
             sideOffset={6}
             collisionPadding={8}
-            className="z-85 w-72 max-w-(--radix-popover-content-available-width) rounded-popover shadow-overlay"
+            className={cn(
+              "z-85 w-72 max-w-(--ui-popper-available-width) rounded-popover shadow-overlay",
+              classNames?.popover,
+            )}
           >
             <EmojiPicker
-              className="max-w-none surface-overlay"
+              className={cn("max-w-none surface-overlay", classNames?.picker)}
               onSelect={(emoji) => {
                 const existing = reactions.find((r) => r.emoji === emoji);
                 onReact?.(emoji, !existing?.reacted);

package/src/forms/emoji-reaction-button/index.ts

@@ -1,7 +1,9 @@
 export {
   EmojiReactionBar,
+  type EmojiReactionBarPart,
   type EmojiReactionBarProps,
   EmojiReactionButton,
+  type EmojiReactionButtonPart,
   type EmojiReactionButtonProps,
   type Reaction,
 } from "./emoji-reaction-button.js";

package/src/forms/field/field.tsx

@@ -1,7 +1,14 @@
 "use client";
 
-import { cloneElement, isValidElement, type ReactElement, useId } from "react";
+import {
+  type ComponentPropsWithoutRef,
+  cloneElement,
+  isValidElement,
+  type ReactElement,
+  useId,
+} from "react";
 import { useUiStrings } from "../../i18n/index.js";
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
 import { Label } from "../label/index.js";
 
@@ -11,7 +18,9 @@ interface ControlProps {
   "aria-invalid"?: boolean;
 }
 
-export interface FieldProps {
+export type FieldPart = "root" | "label" | "optional" | "hint" | "error";
+
+export interface FieldProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "id"> {
   label: string;
   hint?: string;
   /** Message under the control; `null` and `undefined` mean no error. */
@@ -20,10 +29,21 @@ export interface FieldProps {
   optional?: boolean;
   id?: string;
   children: ReactElement<ControlProps>;
-  className?: string;
+  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+  classNames?: ClassNames<FieldPart>;
 }
 
-export function Field({ label, hint, error, optional, id, children, className }: FieldProps) {
+export function Field({
+  label,
+  hint,
+  error,
+  optional,
+  id,
+  children,
+  className,
+  classNames,
+  ...props
+}: FieldProps) {
   const strings = useUiStrings();
   const generatedId = useId();
   const controlId = id ?? generatedId;
@@ -40,19 +60,28 @@ export function Field({ label, hint, error, optional, id, children, className }:
     : children;
 
   return (
-    <div className={cn("flex min-w-0 flex-col gap-1.25", className)}>
-      <Label htmlFor={controlId}>
+    <div {...props} className={cn("flex min-w-0 flex-col gap-1.25", classNames?.root, className)}>
+      <Label htmlFor={controlId} className={classNames?.label}>
         {label}
-        {optional ? <span className="font-normal text-ink-3"> ({strings.optional})</span> : null}
+        {optional ? (
+          <span className={cn("font-normal text-ink-3", classNames?.optional)}>
+            {" "}
+            ({strings.optional})
+          </span>
+        ) : null}
       </Label>
       {control}
       {hint ? (
-        <p id={hintId} className="text-meta text-ink-3">
+        <p id={hintId} className={cn("text-meta text-ink-3", classNames?.hint)}>
           {hint}
         </p>
       ) : null}
       {error ? (
-        <p id={errorId} className="font-semibold text-danger text-meta" role="alert">
+        <p
+          id={errorId}
+          className={cn("font-semibold text-danger text-meta", classNames?.error)}
+          role="alert"
+        >
           {error}
         </p>
       ) : null}

package/src/forms/field/index.ts

@@ -1 +1 @@
-export { Field, type FieldProps } from "./field.js";
+export { Field, type FieldPart, type FieldProps } from "./field.js";

package/src/forms/inline-select/inline-select.tsx

@@ -1,5 +1,5 @@
-import { ChevronsUpDown } from "lucide-react";
 import type { ComponentPropsWithoutRef } from "react";
+import { ChevronsUpDown } from "../../icons/index.js";
 import { cn } from "../../utils/cn.js";
 
 export interface InlineSelectOption {

package/src/forms/input-icon/index.ts

@@ -1 +1 @@
-export { InputIcon, type InputIconProps } from "./input-icon.js";
+export { InputIcon, type InputIconPart, type InputIconProps } from "./input-icon.js";

package/src/forms/input-icon/input-icon.tsx

@@ -1,22 +1,30 @@
 import type { ReactNode } from "react";
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
 import { Input, type InputProps } from "../input/index.js";
 
+export type InputIconPart = "root" | "icon" | "input";
+
 export interface InputIconProps extends InputProps {
-  /** Leading icon element (e.g. a lucide-react icon). */
+  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the input and is merged last. */
+  classNames?: ClassNames<InputIconPart>;
+  /** Leading icon element (e.g. an `@jcsoftdev/ui/icons` icon). */
   icon: ReactNode;
 }
 
-export function InputIcon({ icon, className, ...props }: InputIconProps) {
+export function InputIcon({ icon, className, classNames, ...props }: InputIconProps) {
   return (
-    <span className="relative flex w-full items-center">
+    <span className={cn("relative flex w-full items-center", classNames?.root)}>
       <span
         aria-hidden="true"
-        className="pointer-events-none absolute left-2.5 flex text-ink-3 [&>svg]:size-4"
+        className={cn(
+          "pointer-events-none absolute left-2.5 flex text-ink-3 [&>svg]:size-4",
+          classNames?.icon,
+        )}
       >
         {icon}
       </span>
-      <Input className={cn("pl-8", className)} {...props} />
+      <Input className={cn("pl-8", classNames?.input, className)} {...props} />
     </span>
   );
 }

package/src/forms/internal/button-option.tsx

@@ -1,6 +1,9 @@
 import type { ReactNode } from "react";
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
 
+export type ButtonOptionPart = "option" | "icon" | "text" | "label" | "description";
+
 export interface ButtonOption {
   value: string;
   label: ReactNode;
@@ -17,28 +20,35 @@ interface OptionShellProps {
   /** Visually hidden native input: gives focus, keyboard and form semantics for free. */
   input: ReactNode;
   className?: string;
+  classNames?: ClassNames<ButtonOptionPart>;
 }
 
 /** Selectable card-button around a native checkbox/radio; `peer` styling reads its checked state. */
-export function OptionShell({ option, input, className }: OptionShellProps) {
+export function OptionShell({ option, input, className, classNames }: OptionShellProps) {
   return (
     // biome-ignore lint/a11y/noLabelWithoutControl: the native input is passed in through `input` and rendered inside this label
     <label
       className={cn(
         "pressable relative flex min-w-0 cursor-pointer items-center gap-2 rounded-button border-control bg-surface-control px-control-x py-2 text-control text-ink has-[:checked]:border-accent has-[:checked]:bg-accent-soft has-[:checked]:shadow-selected has-[:disabled]:cursor-not-allowed has-[:disabled]:opacity-50 has-[:focus-visible]:focus-ring",
+        classNames?.option,
         className,
       )}
     >
       {input}
       {option.icon ? (
-        <span aria-hidden="true" className="shrink-0 text-ink-2 [&_svg]:size-4">
+        <span
+          aria-hidden="true"
+          className={cn("shrink-0 text-ink-2 [&_svg]:size-4", classNames?.icon)}
+        >
           {option.icon}
         </span>
       ) : null}
-      <span className="flex min-w-0 flex-col [overflow-wrap:anywhere]">
-        <span className="font-semibold">{option.label}</span>
+      <span className={cn("flex min-w-0 flex-col [overflow-wrap:anywhere]", classNames?.text)}>
+        <span className={cn("font-semibold", classNames?.label)}>{option.label}</span>
         {option.description ? (
-          <span className="text-ink-3 text-meta">{option.description}</span>
+          <span className={cn("text-ink-3 text-meta", classNames?.description)}>
+            {option.description}
+          </span>
         ) : null}
       </span>
     </label>

package/src/forms/native-select/index.ts

@@ -2,5 +2,6 @@ export {
   NativeSelect,
   type NativeSelectGroup,
   type NativeSelectOption,
+  type NativeSelectPart,
   type NativeSelectProps,
 } from "./native-select.js";

package/src/forms/native-select/native-select.tsx

@@ -1,5 +1,6 @@
-import { ChevronDown } from "lucide-react";
 import type { ComponentPropsWithoutRef } from "react";
+import { ChevronDown } from "../../icons/index.js";
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
 
 export interface NativeSelectOption {
@@ -13,6 +14,8 @@ export interface NativeSelectGroup {
   options: NativeSelectOption[];
 }
 
+export type NativeSelectPart = "root" | "select" | "icon";
+
 export interface NativeSelectProps extends Omit<ComponentPropsWithoutRef<"select">, "size"> {
   /** Data-driven alternative to `<option>` children; groups render as `<optgroup>`. */
   options?: (NativeSelectOption | NativeSelectGroup)[];
@@ -20,6 +23,8 @@ export interface NativeSelectProps extends Omit<ComponentPropsWithoutRef<"select
   placeholder?: string;
   size?: "sm" | "md";
   invalid?: boolean;
+  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the `<select>` and is merged last. */
+  classNames?: ClassNames<NativeSelectPart>;
 }
 
 function isGroup(item: NativeSelectOption | NativeSelectGroup): item is NativeSelectGroup {
@@ -36,6 +41,7 @@ export function NativeSelect({
   size = "md",
   invalid,
   className,
+  classNames,
   children,
   defaultValue,
   value,
@@ -44,7 +50,7 @@ export function NativeSelect({
   const fallbackDefault =
     placeholder && value === undefined && defaultValue === undefined ? "" : defaultValue;
   return (
-    <span className="relative flex w-full min-w-0 items-center">
+    <span className={cn("relative flex w-full min-w-0 items-center", classNames?.root)}>
       <select
         value={value}
         defaultValue={fallbackDefault}
@@ -52,6 +58,7 @@ export function NativeSelect({
         className={cn(
           "w-full min-w-0 appearance-none rounded-input border-control bg-surface-control py-0 pl-3 text-control text-ink focus:border-transparent focus:outline-2 focus:outline-accent-ink focus:-outline-offset-1 disabled:cursor-not-allowed disabled:opacity-50 aria-[invalid=true]:border-danger",
           size === "sm" ? "h-control-sm pr-7" : "h-input pr-8",
+          classNames?.select,
           className,
         )}
         {...props}
@@ -80,7 +87,10 @@ export function NativeSelect({
       </select>
       <ChevronDown
         aria-hidden="true"
-        className="pointer-events-none absolute right-2.5 size-3.5 text-ink-3"
+        className={cn(
+          "pointer-events-none absolute right-2.5 size-3.5 text-ink-3",
+          classNames?.icon,
+        )}
       />
     </span>
   );

package/src/forms/number-stepper/index.ts

@@ -1 +1,5 @@
-export { NumberStepper, type NumberStepperProps } from "./number-stepper.js";
+export {
+  NumberStepper,
+  type NumberStepperPart,
+  type NumberStepperProps,
+} from "./number-stepper.js";

package/src/forms/number-stepper/number-stepper.tsx

@@ -1,10 +1,13 @@
 "use client";
 
-import { Minus, Plus } from "lucide-react";
 import { type ChangeEvent, type KeyboardEvent, useId, useState } from "react";
+import { Minus, Plus } from "../../icons/index.js";
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
 import { snapToStep } from "../slider/model.js";
 
+export type NumberStepperPart = "root" | "decrement" | "increment" | "input" | "unit";
+
 export interface NumberStepperProps {
   value?: number;
   defaultValue?: number;
@@ -19,6 +22,8 @@ export interface NumberStepperProps {
   "aria-label"?: string;
   "aria-labelledby"?: string;
   className?: string;
+  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+  classNames?: ClassNames<NumberStepperPart>;
 }
 
 /** Counter with minus/plus buttons and a typeable value; ArrowUp/ArrowDown step it, Home/End jump. */
@@ -33,6 +38,7 @@ export function NumberStepper({
   unit,
   name,
   className,
+  classNames,
   ...aria
 }: NumberStepperProps) {
   const id = useId();
@@ -71,6 +77,7 @@ export function NumberStepper({
       className={cn(
         "inline-flex h-input min-w-32 max-w-full items-stretch overflow-hidden rounded-input border-control bg-surface-control",
         disabled && "opacity-60",
+        classNames?.root,
         className,
       )}
     >
@@ -81,7 +88,7 @@ export function NumberStepper({
         aria-controls={id}
         disabled={disabled || value <= min}
         onClick={() => apply(value - step)}
-        className={cn(button, "pressable")}
+        className={cn(button, "pressable", classNames?.decrement)}
       >
         <Minus aria-hidden="true" className="size-3.5" />
       </button>
@@ -101,10 +108,16 @@ export function NumberStepper({
         onChange={(event: ChangeEvent<HTMLInputElement>) => setDraft(event.target.value)}
         onBlur={commitDraft}
         onKeyDown={onKeyDown}
-        className="w-14 min-w-0 flex-1 bg-transparent px-1 text-center text-control text-ink tabular-nums outline-none focus-visible:focus-ring"
+        className={cn(
+          "w-14 min-w-0 flex-1 bg-transparent px-1 text-center text-control text-ink tabular-nums outline-none focus-visible:focus-ring",
+          classNames?.input,
+        )}
       />
       {unit ? (
-        <span aria-hidden="true" className="flex items-center pr-2 text-ink-3 text-meta">
+        <span
+          aria-hidden="true"
+          className={cn("flex items-center pr-2 text-ink-3 text-meta", classNames?.unit)}
+        >
           {unit}
         </span>
       ) : null}
@@ -115,7 +128,7 @@ export function NumberStepper({
         aria-controls={id}
         disabled={disabled || value >= max}
         onClick={() => apply(value + step)}
-        className={cn(button, "pressable")}
+        className={cn(button, "pressable", classNames?.increment)}
       >
         <Plus aria-hidden="true" className="size-3.5" />
       </button>

package/src/forms/pin-input/index.ts

@@ -1 +1 @@
-export { PinInput, type PinInputProps } from "./pin-input.js";
+export { PinInput, type PinInputPart, type PinInputProps } from "./pin-input.js";

package/src/forms/pin-input/pin-input.tsx

@@ -1,8 +1,11 @@
 "use client";
 
 import { type ChangeEvent, useId, useState } from "react";
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
 
+export type PinInputPart = "root" | "dots" | "dot" | "input";
+
 export interface PinInputProps {
   length?: number;
   value?: string;
@@ -13,6 +16,8 @@ export interface PinInputProps {
   /** Builds the polite live-region announcement. */
   statusLabel?: (entered: number, length: number) => string;
   className?: string;
+  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+  classNames?: ClassNames<PinInputPart>;
 }
 
 const defaultStatusLabel = (entered: number, length: number) =>
@@ -30,6 +35,7 @@ export function PinInput({
   label = "PIN",
   statusLabel = defaultStatusLabel,
   className,
+  classNames,
 }: PinInputProps) {
   const statusId = useId();
   const [internal, setInternal] = useState(defaultValue);
@@ -42,9 +48,18 @@ export function PinInput({
   }
 
   return (
-    <div className={cn("@container/pin flex min-w-0 flex-col items-center gap-3", className)}>
+    <div
+      className={cn(
+        "@container/pin flex min-w-0 flex-col items-center gap-3",
+        classNames?.root,
+        className,
+      )}
+    >
       <div
-        className="flex max-w-full flex-wrap justify-center gap-2 @min-[240px]/pin:gap-3"
+        className={cn(
+          "flex max-w-full flex-wrap justify-center gap-2 @min-[240px]/pin:gap-3",
+          classNames?.dots,
+        )}
         aria-hidden="true"
       >
         {Array.from({ length }, (_, index) => (
@@ -56,12 +71,16 @@ export function PinInput({
             className={cn(
               "size-3 shrink-0 rounded-pill border-2 border-line-control @min-[240px]/pin:size-3.5",
               index < current.length && "border-ink bg-ink",
+              classNames?.dot,
             )}
           />
         ))}
       </div>
       <input
-        className="h-input w-full min-w-0 rounded-input border-control bg-surface-control px-2 text-center font-mono text-control text-ink tracking-[0.15em] @min-[240px]/pin:px-3 @min-[240px]/pin:tracking-[0.3em] focus:border-transparent focus:outline-2 focus:outline-accent-ink focus:-outline-offset-1"
+        className={cn(
+          "h-input w-full min-w-0 rounded-input border-control bg-surface-control px-2 text-center font-mono text-control text-ink tracking-[0.15em] @min-[240px]/pin:px-3 @min-[240px]/pin:tracking-[0.3em] focus:border-transparent focus:outline-2 focus:outline-accent-ink focus:-outline-offset-1",
+          classNames?.input,
+        )}
         type="password"
         inputMode="numeric"
         maxLength={length}

package/src/forms/radio-button-group/index.ts

@@ -1,5 +1,6 @@
 export {
   RadioButtonGroup,
+  type RadioButtonGroupPart,
   type RadioButtonGroupProps,
   type RadioButtonOption,
 } from "./radio-button-group.js";

package/src/forms/radio-button-group/radio-button-group.tsx

@@ -1,11 +1,19 @@
 "use client";
 
 import { useId, useState } from "react";
+import type { ClassNames } from "../../utils/class-names.js";
 import { cn } from "../../utils/cn.js";
-import { type ButtonOption, OptionShell, optionGridClass } from "../internal/button-option.js";
+import {
+  type ButtonOption,
+  type ButtonOptionPart,
+  OptionShell,
+  optionGridClass,
+} from "../internal/button-option.js";
 
 export type RadioButtonOption = ButtonOption;
 
+export type RadioButtonGroupPart = "root" | ButtonOptionPart;
+
 export interface RadioButtonGroupProps {
   options: RadioButtonOption[];
   value?: string;
@@ -16,6 +24,8 @@ export interface RadioButtonGroupProps {
   "aria-label"?: string;
   "aria-labelledby"?: string;
   className?: string;
+  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
+  classNames?: ClassNames<RadioButtonGroupPart>;
 }
 
 /**
@@ -31,6 +41,7 @@ export function RadioButtonGroup({
   name,
   disabled,
   className,
+  classNames,
   ...aria
 }: RadioButtonGroupProps) {
   const generated = useId();
@@ -40,13 +51,14 @@ export function RadioButtonGroup({
   return (
     <div
       role="radiogroup"
-      className={cn("@container/options", optionGridClass, className)}
+      className={cn("@container/options", optionGridClass, classNames?.root, className)}
       {...aria}
     >
       {options.map((option) => (
         <OptionShell
           key={option.value}
           option={option}
+          classNames={classNames}
           input={
             <input
               type="radio"

package/src/forms/rating/index.ts

@@ -1,2 +1,2 @@
 export { ratingFromPointer, ratingKey, roundRating, starFill } from "./model.js";
-export { Rating, type RatingProps } from "./rating.js";
+export { Rating, type RatingPart, type RatingProps } from "./rating.js";