@vvedantb/ui 0.17.0 → 0.18.0

package/src/ui/carousel.tsx

@@ -6,6 +6,12 @@ import useEmblaCarousel, {
 import { IconChevronLeft, IconChevronRight } from "@tabler/icons-react";
 import { cn } from "../utils/cn";
 import { Button } from "./button";
+import { useCn, useUiConfig } from "./ui-config";
+
+/** `UiConfig.Carousel`: `classes` replace the built-in `CarouselDots` part classes. */
+export interface CarouselConfig {
+  classes?: { dots?: string; dot?: string; dotActive?: string; dotInactive?: string };
+}
 type CarouselApi = UseEmblaCarouselType[1];
 type UseCarouselParameters = Parameters<typeof useEmblaCarousel>;
 type CarouselOptions = UseCarouselParameters[0];
@@ -23,6 +29,11 @@ type CarouselContextProps = {
   scrollNext: () => void;
   canScrollPrev: boolean;
   canScrollNext: boolean;
+  /** Index of the selected snap. */
+  selectedIndex: number;
+  /** Embla's snap positions, one per page. */
+  scrollSnaps: number[];
+  scrollTo: (index: number) => void;
 } & CarouselProps;
 const CarouselContext = React.createContext<CarouselContextProps | null>(null);
 function useCarousel() {
@@ -50,10 +61,18 @@ function Carousel({
   );
   const [canScrollPrev, setCanScrollPrev] = React.useState(false);
   const [canScrollNext, setCanScrollNext] = React.useState(false);
+  const [selectedIndex, setSelectedIndex] = React.useState(0);
+  const [scrollSnaps, setScrollSnaps] = React.useState<number[]>([]);
   const onSelect = (api: CarouselApi) => {
     if (!api) return;
     setCanScrollPrev(api.canScrollPrev());
     setCanScrollNext(api.canScrollNext());
+    setSelectedIndex(api.selectedScrollSnap());
+    // keep the old array when nothing moved, so this can run on every render
+    const next = api.scrollSnapList();
+    setScrollSnaps((prev) =>
+      prev.length === next.length && prev.every((snap, i) => snap === next[i]) ? prev : next,
+    );
   };
   const scrollPrev = () => {
     api?.scrollPrev();
@@ -61,6 +80,9 @@ function Carousel({
   const scrollNext = () => {
     api?.scrollNext();
   };
+  const scrollTo = (index: number) => {
+    api?.scrollTo(index);
+  };
   const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
     if (event.key === "ArrowLeft") {
       event.preventDefault();
@@ -95,6 +117,9 @@ function Carousel({
         scrollNext,
         canScrollPrev,
         canScrollNext,
+        selectedIndex,
+        scrollSnaps,
+        scrollTo,
       }}
     >
       <div
@@ -201,6 +226,39 @@ function CarouselNext({
     </Button>
   );
 }
+/** One dot per snap; the selected one is wider. Renders nothing for a single page. */
+function CarouselDots({ className }: { className?: string }) {
+  const { scrollSnaps, selectedIndex, scrollTo } = useCarousel();
+  const classes = useUiConfig("Carousel")?.classes;
+  const merge = useCn();
+
+  if (scrollSnaps.length <= 1) return null;
+
+  return (
+    <div
+      data-slot="carousel-dots"
+      className={merge(classes?.dots ?? "flex justify-center gap-1.5 pt-2", className)}
+    >
+      {scrollSnaps.map((_, index) => (
+        <button
+          key={index}
+          type="button"
+          className={merge(
+            classes?.dot ??
+              "h-1.5 cursor-pointer rounded-full transition-[background-color,transform] duration-150 ease-out active:scale-90",
+            index === selectedIndex
+              ? (classes?.dotActive ?? "w-4 bg-primary")
+              : (classes?.dotInactive ??
+                  "w-1.5 bg-muted-foreground/30 hover:bg-muted-foreground/50"),
+          )}
+          onClick={() => scrollTo(index)}
+          aria-label={`Go to slide ${index + 1}`}
+        />
+      ))}
+    </div>
+  );
+}
+
 export {
   type CarouselApi,
   Carousel,
@@ -208,4 +266,6 @@ export {
   CarouselItem,
   CarouselPrevious,
   CarouselNext,
+  CarouselDots,
+  useCarousel,
 };

package/src/ui/centered-spinner.tsx

@@ -0,0 +1,30 @@
+import { Spinner } from "./spinner";
+import { useCn } from "./ui-config";
+
+/**
+ * A loading state for a pane, list or page: {@link Spinner} (with the app's
+ * `UiConfig.Spinner` mark, if any), centred in whatever box it is given.
+ * `label` names the spinner for assistive tech.
+ *
+ * A spinner says "wait" as well as a skeleton does, and never has to be
+ * re-shaped when the content changes.
+ */
+export function CenteredSpinner({
+  label,
+  className,
+  ...props
+}: React.ComponentProps<"div"> & { label: string }) {
+  const merge = useCn();
+  return (
+    <div
+      aria-busy="true"
+      className={merge(
+        "flex min-h-0 w-full flex-1 items-center justify-center p-6",
+        className,
+      )}
+      {...props}
+    >
+      <Spinner aria-label={label} />
+    </div>
+  );
+}

package/src/ui/checkbox.tsx

@@ -2,26 +2,44 @@ import * as React from "react";
 import * as CheckboxPrimitive from "@radix-ui/react-checkbox";
 import { IconCheck } from "@tabler/icons-react";
 import { cn } from "../utils/cn";
+import { useCn, useUiConfig } from "./ui-config";
+
+/** `UiConfig.Checkbox`: `classes` replace built-in part classes; `icon` is the default for the prop. */
+export interface CheckboxConfig {
+  classes?: { root?: string; indicator?: string };
+  icon?: React.ReactNode;
+}
+
+type CheckboxProps = React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root> & {
+  /** Shown in the indicator while checked. Default a 14px check icon. */
+  icon?: React.ReactNode;
+};
 
 const Checkbox = React.forwardRef<
   React.ComponentRef<typeof CheckboxPrimitive.Root>,
-  React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>
->(({ className, ...props }, ref) => (
-  <CheckboxPrimitive.Root
-    ref={ref}
-    className={cn(
-      "peer relative h-4 w-4 shrink-0 rounded-[4px] border border-border bg-field-background transition-[background-color,border-color] duration-200 ease-smooth focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground before:absolute before:inset-[-12px] before:content-['']",
-      className,
-    )}
-    {...props}
-  >
-    <CheckboxPrimitive.Indicator
-      className={cn("flex items-center justify-center text-current")}
+  CheckboxProps
+>(({ className, icon, ...props }, ref) => {
+  const config = useUiConfig("Checkbox");
+  const merge = useCn();
+  return (
+    <CheckboxPrimitive.Root
+      ref={ref}
+      className={merge(
+        config?.classes?.root ??
+          "peer relative h-4 w-4 shrink-0 rounded-[4px] border border-border bg-field-background transition-[background-color,border-color] duration-200 ease-smooth focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground before:absolute before:inset-[-12px] before:content-['']",
+        className,
+      )}
+      {...props}
     >
-      <IconCheck className="h-3.5 w-3.5" />
-    </CheckboxPrimitive.Indicator>
-  </CheckboxPrimitive.Root>
-));
+      <CheckboxPrimitive.Indicator
+        className={config?.classes?.indicator ?? cn("flex items-center justify-center text-current")}
+      >
+        {icon ?? config?.icon ?? <IconCheck className="h-3.5 w-3.5" />}
+      </CheckboxPrimitive.Indicator>
+    </CheckboxPrimitive.Root>
+  );
+});
 Checkbox.displayName = CheckboxPrimitive.Root.displayName;
 
 export { Checkbox };
+export type { CheckboxProps };

package/src/ui/clear-input.alt.tsx

@@ -1,78 +1,36 @@
 "use client";
 import * as React from "react";
-import { IconX } from "@tabler/icons-react";
-import { cn } from "../utils/cn";
 import { fieldFocusClass } from "./_field-classes";
-export interface ClearInputProps
-  extends Omit<React.ComponentProps<"input">, "value" | "onChange"> {
-  value: string;
-  onChange: (value: string) => void;
-  wrapperClassName?: string;
-  /** Icon or adornment positioned in the field's left gutter. */
-  leading?: React.ReactNode;
-  clearLabel?: string;
-}
-const ClearInput = React.forwardRef<HTMLInputElement, ClearInputProps>(
-  (
-    {
-      value,
-      onChange,
-      wrapperClassName,
-      leading,
-      clearLabel = "Clear",
-      className,
-      placeholder,
-      ...props
-    },
-    ref,
-  ) => {
-    const inputRef = React.useRef<HTMLInputElement | null>(null);
-    const mergedRef = (node: HTMLInputElement | null) => {
-      inputRef.current = node;
-      if (typeof ref === "function") {
-        ref(node);
-      } else if (ref) {
-        ref.current = node;
-      }
-    };
-    const hasValue = value.length > 0;
-    return (
-      <div className={cn("relative", wrapperClassName)}>
-        {leading}
-        <input
-          ref={mergedRef}
-          type="text"
-          value={value}
-          onChange={(event) => {
-            onChange(event.target.value);
-          }}
-          placeholder={placeholder}
-          className={cn(
-            "flex h-10 w-full rounded-field border border-border bg-field-background px-3.5 py-2 text-sm transition-[border-color,background-color] duration-200 ease-smooth placeholder:text-field-placeholder disabled:cursor-not-allowed disabled:opacity-50",
-            fieldFocusClass,
-            "pr-9",
-            className,
-          )}
-          {...props}
-        />
-        <button
-          type="button"
-          tabIndex={hasValue ? 0 : -1}
-          className={cn(
-            "absolute right-2 top-1/2 inline-flex h-6 w-6 -translate-y-1/2 items-center justify-center rounded-md text-muted-foreground transition-[opacity,background-color,color,transform] duration-150 ease-out active:duration-100 active:ease-out active:scale-[0.97] hover:bg-surface-tertiary hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring before:absolute before:inset-[-8px] before:content-['']",
-            hasValue ? "opacity-100" : "pointer-events-none opacity-0",
-          )}
-          aria-hidden={!hasValue}
-          aria-label={clearLabel}
-          onClick={() => {
-            onChange("");
-            inputRef.current?.focus({ preventScroll: true });
-          }}
-        >
-          <IconX size={14} stroke={1.75} />
-        </button>
-      </div>
-    );
-  },
-);
-export { ClearInput };
+import { ClearInput, type ClearInputProps } from "./clear-input";
+
+const altClasses = {
+  wrapper: "relative",
+  input: `flex h-10 w-full rounded-field border border-border bg-field-background px-3.5 py-2 text-sm transition-[border-color,background-color] duration-200 ease-smooth placeholder:text-field-placeholder disabled:cursor-not-allowed disabled:opacity-50 ${fieldFocusClass}`,
+  button:
+    "absolute right-2 top-1/2 inline-flex h-6 w-6 -translate-y-1/2 items-center justify-center rounded-md text-muted-foreground transition-[opacity,background-color,color,transform] duration-150 ease-out active:duration-100 active:ease-out active:scale-[0.97] hover:bg-surface-tertiary hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring before:absolute before:inset-[-8px] before:content-['']",
+};
+
+/**
+ * The `Alt` look on `ClearInput`'s `animation="none"` path: the clear button
+ * stays mounted (`clearButton="always"`), per-instance `classes` replace the
+ * main classes (and any `UiConfig.ClearInput` entry), and an explicit
+ * `placeholder={undefined}` keeps the input free of the main `placeholder=""`.
+ *
+ * @deprecated Use `ClearInput`. Kept for existing consumers; removed in a later minor after they move.
+ */
+const ClearInputAlt = React.forwardRef<
+  HTMLInputElement,
+  Omit<ClearInputProps, "animation" | "clearButton" | "classes">
+>(({ placeholder, ...props }, ref) => (
+  <ClearInput
+    ref={ref}
+    animation="none"
+    clearButton="always"
+    classes={altClasses}
+    placeholder={placeholder}
+    {...props}
+  />
+));
+ClearInputAlt.displayName = "ClearInputAlt";
+
+export { ClearInputAlt };

package/src/ui/clear-input.tsx

@@ -2,9 +2,23 @@
 
 import * as React from "react";
 import { IconX } from "@tabler/icons-react";
-import { cn } from "../utils/cn";
+import { assignRef } from "../utils/ref";
 import { fieldFocusClass } from "./_field-classes";
 import { runClearInputDissolve } from "./clearInputDissolve";
+import { useCn, useUiConfig } from "./ui-config";
+
+type ClearInputAnimation = "dissolve" | "none";
+
+/**
+ * `UiConfig.ClearInput`: `animation` is the default for the prop. `classes`
+ * replace the built-in input and button classes, and the wrapper's `relative`
+ * in the `none` layout (the `dissolve` wrapper keeps its `t-clear` hooks and
+ * adds `classes.wrapper`). The `classes` prop wins over it key by key.
+ */
+export interface ClearInputConfig {
+  animation?: ClearInputAnimation;
+  classes?: { wrapper?: string; input?: string; button?: string };
+}
 
 export interface ClearInputProps extends Omit<
   React.ComponentProps<"input">,
@@ -16,9 +30,123 @@ export interface ClearInputProps extends Omit<
   /** Icon or adornment positioned in the field's left gutter. */
   leading?: React.ReactNode;
   clearLabel?: string;
+  /**
+   * `dissolve` (default): the text dissolves before the value clears (needs
+   * `clear-input.css`). `none`: clear at once, focus the input, and render
+   * only the wrapper, input and clear button.
+   */
+  animation?: ClearInputAnimation;
+  /**
+   * With `animation="none"` only. `"filled"` (default): the clear button
+   * mounts while there is a value. `"always"`: it stays mounted so the field
+   * never reflows; while empty it is hidden (`pointer-events-none opacity-0`,
+   * `tabIndex=-1`, `aria-hidden`), while filled it shows (`opacity-100`,
+   * `tabIndex=0`), and the input always reserves `pr-9`.
+   */
+  clearButton?: "filled" | "always";
+  /** Replaces the wrapper, input and button classes for this instance (each key wins over `UiConfig.ClearInput.classes`). */
+  classes?: ClearInputConfig["classes"];
 }
 
+const inputClasses =
+  "flex h-10 w-full rounded-field border border-border bg-field-background px-3.5 py-2 text-base sm:text-sm transition-[border-color,box-shadow,background-color] duration-200 ease-smooth placeholder:text-field-placeholder disabled:cursor-not-allowed disabled:opacity-50";
+
+const buttonClasses =
+  "absolute right-2 top-1/2 z-4 inline-flex h-6 w-6 -translate-y-1/2 items-center justify-center rounded-md text-muted-foreground transition-[background-color,color,transform] duration-100 ease-out active:scale-[0.92] hover:bg-surface-tertiary/50 hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring";
+
 const ClearInput = React.forwardRef<HTMLInputElement, ClearInputProps>(
+  ({ animation, clearButton, classes, ...props }, ref) => {
+    const config = useUiConfig("ClearInput");
+    const merged = { ...config?.classes, ...classes };
+    if ((animation ?? config?.animation) === "none") {
+      return <PlainClearInput ref={ref} classes={merged} clearButton={clearButton} {...props} />;
+    }
+    return <DissolveClearInput ref={ref} classes={merged} {...props} />;
+  },
+);
+ClearInput.displayName = "ClearInput";
+
+type ClearInputPartsProps = Omit<ClearInputProps, "animation" | "clearButton">;
+
+const PlainClearInput = React.forwardRef<
+  HTMLInputElement,
+  ClearInputPartsProps & Pick<ClearInputProps, "clearButton">
+>(
+  (
+    {
+      value,
+      onChange,
+      wrapperClassName,
+      leading,
+      clearLabel = "Clear",
+      className,
+      classes,
+      clearButton = "filled",
+      ...props
+    },
+    ref,
+  ) => {
+    const merge = useCn();
+    const filled = value.length > 0;
+    const always = clearButton === "always";
+    const inputRef = React.useRef<HTMLInputElement | null>(null);
+
+    const preventFocusSteal = (event: React.SyntheticEvent) => {
+      if (document.activeElement === inputRef.current) {
+        event.preventDefault();
+      }
+    };
+
+    return (
+      <div className={merge(classes?.wrapper ?? "relative", wrapperClassName)}>
+        {leading}
+        <input
+          ref={(node) => {
+            inputRef.current = node;
+            assignRef(ref, node);
+          }}
+          type="text"
+          value={value}
+          onChange={(event) => {
+            onChange(event.target.value);
+          }}
+          // A caller `placeholder` in `props` replaces this default in place;
+          // an explicit `undefined` drops the attribute.
+          placeholder=""
+          className={merge(
+            classes?.input ?? [inputClasses, fieldFocusClass],
+            (always || filled) && "pr-9",
+            className,
+          )}
+          {...props}
+        />
+        {always || filled ? (
+          <button
+            type="button"
+            {...(always ? { tabIndex: filled ? 0 : -1 } : null)}
+            className={
+              always
+                ? merge(classes?.button ?? buttonClasses, filled ? "opacity-100" : "pointer-events-none opacity-0")
+                : (classes?.button ?? buttonClasses)
+            }
+            {...(always ? { "aria-hidden": !filled } : null)}
+            aria-label={clearLabel}
+            onPointerDown={preventFocusSteal}
+            onMouseDown={preventFocusSteal}
+            onClick={() => {
+              onChange("");
+              inputRef.current?.focus();
+            }}
+          >
+            <IconX size={14} stroke={1.75} />
+          </button>
+        ) : null}
+      </div>
+    );
+  },
+);
+
+const DissolveClearInput = React.forwardRef<HTMLInputElement, ClearInputPartsProps>(
   (
     {
       value,
@@ -28,10 +156,12 @@ const ClearInput = React.forwardRef<HTMLInputElement, ClearInputProps>(
       clearLabel = "Clear",
       className,
       placeholder = "",
+      classes,
       ...props
     },
     ref,
   ) => {
+    const merge = useCn();
     const wrapRef = React.useRef<HTMLDivElement>(null);
     const inputRef = React.useRef<HTMLInputElement | null>(null);
     const mirrorRef = React.useRef<HTMLDivElement>(null);
@@ -42,11 +172,7 @@ const ClearInput = React.forwardRef<HTMLInputElement, ClearInputProps>(
 
     function mergedRef(node: HTMLInputElement | null) {
       inputRef.current = node;
-      if (typeof ref === "function") {
-        ref(node);
-      } else if (ref) {
-        ref.current = node;
-      }
+      assignRef(ref, node);
     }
 
     const hasValue = value.length > 0 || clearing;
@@ -104,15 +230,16 @@ const ClearInput = React.forwardRef<HTMLInputElement, ClearInputProps>(
       );
     };
 
-    const fieldClassName = cn(hasValue && "pr-9", className);
+    const fieldClassName = merge(hasValue && "pr-9", className);
 
     return (
       <div
         ref={wrapRef}
-        className={cn(
+        className={merge(
           "t-clear",
           hasValue && "has-value",
           clearing && "is-clearing",
+          classes?.wrapper,
           wrapperClassName,
         )}
       >
@@ -125,9 +252,8 @@ const ClearInput = React.forwardRef<HTMLInputElement, ClearInputProps>(
             onChange(event.target.value);
           }}
           placeholder={placeholder}
-          className={cn(
-            "flex h-10 w-full rounded-field border border-border bg-field-background px-3.5 py-2 text-base sm:text-sm transition-[border-color,box-shadow,background-color] duration-200 ease-smooth placeholder:text-field-placeholder disabled:cursor-not-allowed disabled:opacity-50",
-            fieldFocusClass,
+          className={merge(
+            classes?.input ?? [inputClasses, fieldFocusClass],
             fieldClassName,
           )}
           {...props}
@@ -135,14 +261,14 @@ const ClearInput = React.forwardRef<HTMLInputElement, ClearInputProps>(
         <div className="t-clear-clip" aria-hidden="true">
           <div
             ref={mirrorRef}
-            className={cn(
+            className={merge(
               "t-clear-mirror border-0 bg-transparent text-foreground shadow-none",
               fieldClassName,
             )}
           />
           <div
             ref={placeholderRef}
-            className={cn(
+            className={merge(
               "t-clear-placeholder border-0 bg-transparent text-field-placeholder shadow-none",
               fieldClassName,
             )}
@@ -154,7 +280,7 @@ const ClearInput = React.forwardRef<HTMLInputElement, ClearInputProps>(
         {value.length > 0 && !clearing ? (
           <button
             type="button"
-            className="t-clear-btn absolute right-2 top-1/2 z-4 inline-flex h-6 w-6 -translate-y-1/2 items-center justify-center rounded-md text-muted-foreground transition-[background-color,color,transform] duration-100 ease-out active:scale-[0.92] hover:bg-surface-tertiary/50 hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring"
+            className={classes?.button ? `t-clear-btn ${classes.button}` : `t-clear-btn ${buttonClasses}`}
             aria-label={clearLabel}
             onPointerDown={preventFocusSteal}
             onMouseDown={preventFocusSteal}
@@ -167,6 +293,5 @@ const ClearInput = React.forwardRef<HTMLInputElement, ClearInputProps>(
     );
   },
 );
-ClearInput.displayName = "ClearInput";
 
 export { ClearInput };

package/src/ui/collapsible.tsx

@@ -1,7 +1,45 @@
+import type * as React from "react";
 import * as CollapsiblePrimitive from "@radix-ui/react-collapsible";
+import { useCn, useUiConfig } from "./ui-config";
+
+/**
+ * `UiConfig.Collapsible`: classes for the trigger and the content (for
+ * example an app's open/close animation class). The parts have no built-in
+ * classes, so without an entry `className` passes through untouched.
+ */
+export interface CollapsibleConfig {
+  classes?: { trigger?: string; content?: string };
+}
 
 const Collapsible = CollapsiblePrimitive.Root;
-const CollapsibleTrigger = CollapsiblePrimitive.CollapsibleTrigger;
-const CollapsibleContent = CollapsiblePrimitive.CollapsibleContent;
+
+function CollapsibleTrigger({
+  className,
+  ...props
+}: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleTrigger>) {
+  const trigger = useUiConfig("Collapsible")?.classes?.trigger;
+  const cn = useCn();
+  return (
+    <CollapsiblePrimitive.CollapsibleTrigger
+      className={trigger === undefined ? className : cn(trigger, className)}
+      {...props}
+    />
+  );
+}
+
+export type CollapsibleContentProps = React.ComponentProps<
+  typeof CollapsiblePrimitive.CollapsibleContent
+>;
+
+function CollapsibleContent({ className, ...props }: CollapsibleContentProps) {
+  const content = useUiConfig("Collapsible")?.classes?.content;
+  const cn = useCn();
+  return (
+    <CollapsiblePrimitive.CollapsibleContent
+      className={content === undefined ? className : cn(content, className)}
+      {...props}
+    />
+  );
+}
 
 export { Collapsible, CollapsibleTrigger, CollapsibleContent };