@ttt-productions/ui-core 0.11.14 → 0.11.15

package/src/react/components/list-pagination.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useState } from "react";
 import { ChevronLeft, ChevronRight } from "lucide-react";
 import { Button } from "./button.js";
 import { cn } from "../../lib/utils.js";
@@ -43,6 +44,17 @@ export function ListPagination({ pagination, busy = false, className }: ListPagi
   const { currentPage, totalPages, canPreviousPage, canNextPage, goToPreviousPage, goToNextPage } =
     pagination;
 
+  // The control that started the in-flight page shows the spinner. Cleared when `busy`
+  // ends — a render-phase adjustment, so there is no effect and no stale frame.
+  const [clicked, setClicked] = useState<"previous" | "next" | null>(null);
+  const [wasBusy, setWasBusy] = useState(busy);
+  if (busy !== wasBusy) {
+    setWasBusy(busy);
+    if (!busy) setClicked(null);
+  }
+  const previousPending = busy && clicked === "previous";
+  const nextPending = busy && clicked === "next";
+
   // One visibility rule for both flavors. For a known total this is exactly
   // `totalPages > 1`: page state is clamped into `1..totalPages`, so a
   // single-page list has no reachable neighbour in either direction, and a
@@ -56,11 +68,15 @@ export function ListPagination({ pagination, busy = false, className }: ListPagi
       <Button
         variant="outline"
         size="sm"
-        onClick={goToPreviousPage}
+        onClick={() => {
+          setClicked("previous");
+          goToPreviousPage();
+        }}
         disabled={busy || !canPreviousPage}
+        pending={previousPending}
+        icon={<ChevronLeft className="icon-xs" />}
         className="h-11 min-w-11"
       >
-        <ChevronLeft className="icon-xs mr-1" />
         Previous
       </Button>
       <span className="text-counter" role="status">
@@ -69,12 +85,16 @@ export function ListPagination({ pagination, busy = false, className }: ListPagi
       <Button
         variant="outline"
         size="sm"
-        onClick={goToNextPage}
+        onClick={() => {
+          setClicked("next");
+          goToNextPage();
+        }}
         disabled={busy || !canNextPage}
+        pending={nextPending}
         className="h-11 min-w-11"
       >
         Next
-        <ChevronRight className="icon-xs ml-1" />
+        {nextPending ? null : <ChevronRight className="icon-xs" />}
       </Button>
     </div>
   );

package/src/react/components/search-dropdown.tsx

@@ -3,7 +3,8 @@
 import { useState, useRef, useEffect } from 'react';
 import { Input } from './input.js';
 import { Label } from './label.js';
-import { Loader2, X, Search } from 'lucide-react';
+import { X, Search } from 'lucide-react';
+import { Spinner } from './spinner.js';
 import { cn } from "../../lib/utils.js";
 
 export interface SearchDropdownProps<T> {
@@ -173,7 +174,7 @@ export function SearchDropdown<T>({
 
         <div className="absolute right-3 top-1/2 -translate-y-1/2">
           {isLoading ? (
-            <Loader2 className="h-4 w-4 animate-spin text-muted-foreground" />
+            <Spinner size="xs" className="text-muted-foreground" />
           ) : value ? (
             <button
               type="button"
@@ -195,7 +196,7 @@ export function SearchDropdown<T>({
             </div>
           ) : isLoading ? (
             <div className="px-3 py-2 text-sm text-muted-foreground flex items-center gap-2">
-              <Loader2 className="h-4 w-4 animate-spin" />
+              <Spinner size="xs" />
               Searching...
             </div>
           ) : results.length === 0 ? (

package/src/react/components/select.tsx

@@ -5,6 +5,7 @@ import * as SelectPrimitive from "@radix-ui/react-select"
 import { Check, ChevronDown, ChevronUp } from "lucide-react"
 
 import { cn } from "../../lib/utils.js"
+import { Spinner } from "./spinner.js"
 
 const Select = SelectPrimitive.Root
 const SelectGroup = SelectPrimitive.Group
@@ -12,8 +13,15 @@ const SelectValue = SelectPrimitive.Value
 
 const SelectTrigger = React.forwardRef<
   React.ElementRef<typeof SelectPrimitive.Trigger>,
-  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger>
->(({ className, children, ...props }, ref) => (
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger> & {
+    /**
+     * The change this select started is in flight: the trigger disables itself, sets
+     * `aria-busy`, and shows the spinner in place of its chevron. It keeps showing the
+     * COMMITTED value — the caller changes `value` only once the write lands.
+     */
+    pending?: boolean
+  }
+>(({ className, children, pending = false, disabled, ...props }, ref) => (
   <SelectPrimitive.Trigger
     ref={ref}
     className={cn(
@@ -21,11 +29,17 @@ const SelectTrigger = React.forwardRef<
       className
     )}
     {...props}
+    {...(pending ? { "aria-busy": true, "data-pending": "" } : {})}
+    disabled={disabled || pending || undefined}
   >
     {children}
-    <SelectPrimitive.Icon asChild>
-      <ChevronDown className="h-4 w-4 opacity-50" />
-    </SelectPrimitive.Icon>
+    {pending ? (
+      <Spinner size="xs" />
+    ) : (
+      <SelectPrimitive.Icon asChild>
+        <ChevronDown className="h-4 w-4 opacity-50" />
+      </SelectPrimitive.Icon>
+    )}
   </SelectPrimitive.Trigger>
 ))
 SelectTrigger.displayName = SelectPrimitive.Trigger.displayName

package/src/react/components/spinner.tsx

@@ -0,0 +1,49 @@
+"use client"
+
+import { Loader2 } from "lucide-react"
+
+import { cn } from "../../lib/utils.js"
+
+export type SpinnerSize = "xs" | "sm" | "md" | "lg" | "xl"
+
+export interface SpinnerProps {
+  /** Maps onto the theme-core `spinner-*` classes. Defaults to `xs` (the in-control size). */
+  size?: SpinnerSize
+  /**
+   * Screen-reader text. When set, the spinner becomes a `status` live region that
+   * announces it. Omit it for a spinner inside a control that already carries its
+   * own busy state (`aria-busy`) — the control speaks for it.
+   */
+  label?: string
+  className?: string
+}
+
+const SIZE_CLASS: Record<SpinnerSize, string> = {
+  xs: "spinner-xs",
+  sm: "spinner-sm",
+  md: "spinner-md",
+  lg: "spinner-lg",
+  xl: "spinner-xl",
+}
+
+/**
+ * The ONE loading spinner. Every in-progress indicator renders through this
+ * component (or through a control's `pending` prop, which renders it), so the
+ * spinner's look, size scale, and color rule have one change point. The
+ * theme-core `spinner-*` classes own size, animation, and color — including the
+ * `button .spinner-*` rule that makes an in-button spinner inherit the button's
+ * text color so it is never primary-on-primary.
+ */
+function Spinner({ size = "xs", label, className }: SpinnerProps) {
+  if (!label) {
+    return <Loader2 className={cn(SIZE_CLASS[size], className)} aria-hidden="true" />
+  }
+  return (
+    <span role="status" className={cn("inline-flex items-center justify-center", className)}>
+      <Loader2 className={SIZE_CLASS[size]} aria-hidden="true" />
+      <span className="sr-only">{label}</span>
+    </span>
+  )
+}
+
+export { Spinner }

package/src/react/components/switch.tsx

@@ -4,24 +4,36 @@ import * as React from "react"
 import * as SwitchPrimitives from "@radix-ui/react-switch"
 
 import { cn } from "../../lib/utils.js"
+import { Spinner } from "./spinner.js"
 
 const Switch = React.forwardRef<
   React.ElementRef<typeof SwitchPrimitives.Root>,
-  React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root>
->(({ className, ...props }, ref) => (
+  React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root> & {
+    /**
+     * The change this switch started is in flight: the switch disables itself, sets
+     * `aria-busy`, and spins inside its thumb. It keeps showing the COMMITTED state —
+     * the caller flips `checked` only once the write lands.
+     */
+    pending?: boolean
+  }
+>(({ className, pending = false, disabled, ...props }, ref) => (
   <SwitchPrimitives.Root
     className={cn(
       "peer inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent transition-colors focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input",
       className
     )}
     {...props}
+    {...(pending ? { "aria-busy": true, "data-pending": "" } : {})}
+    disabled={disabled || pending || undefined}
     ref={ref}
   >
     <SwitchPrimitives.Thumb
       className={cn(
-        "pointer-events-none block h-5 w-5 rounded-full bg-background shadow-lg ring-0 transition-transform data-[state=checked]:translate-x-5 data-[state=unchecked]:translate-x-0"
+        "pointer-events-none flex h-5 w-5 items-center justify-center rounded-full bg-background shadow-lg ring-0 transition-transform data-[state=checked]:translate-x-5 data-[state=unchecked]:translate-x-0"
       )}
-    />
+    >
+      {pending ? <Spinner size="xs" /> : null}
+    </SwitchPrimitives.Thumb>
   </SwitchPrimitives.Root>
 ))
 Switch.displayName = SwitchPrimitives.Root.displayName

package/src/react/hooks/use-async-action.ts

@@ -0,0 +1,63 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+
+export interface UseAsyncActionOptions {
+  /**
+   * Receives anything the action throws. REQUIRED, so every call site decides what a
+   * failure means (surface it, capture it, or accept that another layer already did):
+   * `run` itself never rejects, so a fire-and-forget `onClick={() => void run()}` can
+   * never become an unhandled rejection.
+   */
+  onError: (error: unknown) => void;
+}
+
+export interface AsyncAction<TArgs extends unknown[]> {
+  /**
+   * Starts the action unless one is already in flight — a repeat call while pending is
+   * ignored. Resolves once the action settles: `true` when it completed, `false` when it
+   * was ignored or threw. Never rejects.
+   */
+  run: (...args: TArgs) => Promise<boolean>;
+  /** True from the moment `run` starts the action until it settles. */
+  pending: boolean;
+}
+
+/**
+ * Pending state + repeat guard for async work that is NOT a React Query mutation
+ * (a local media step, a sign-out, an awaited navigation). Feed `pending` to the
+ * control's own `pending` prop. Server writes stay mutations — this hook does not
+ * replace the data layer's one mutation path.
+ *
+ * The guard is a ref, not the state, so two clicks inside one frame cannot both start
+ * the action.
+ */
+export function useAsyncAction<TArgs extends unknown[]>(
+  action: (...args: TArgs) => Promise<unknown>,
+  options: UseAsyncActionOptions,
+): AsyncAction<TArgs> {
+  const [pending, setPending] = useState(false);
+  const inFlightRef = useRef(false);
+  const actionRef = useRef(action);
+  const onErrorRef = useRef(options.onError);
+  actionRef.current = action;
+  onErrorRef.current = options.onError;
+
+  const run = useCallback(async (...args: TArgs): Promise<boolean> => {
+    if (inFlightRef.current) return false;
+    inFlightRef.current = true;
+    setPending(true);
+    try {
+      await actionRef.current(...args);
+      return true;
+    } catch (error) {
+      onErrorRef.current(error);
+      return false;
+    } finally {
+      inFlightRef.current = false;
+      setPending(false);
+    }
+  }, []);
+
+  return { run, pending };
+}

package/src/react/index.ts

@@ -2,6 +2,8 @@
 
 export type { ButtonProps } from "./components/button.js";
 export { Button, buttonVariants } from "./components/button.js";
+export type { SpinnerProps, SpinnerSize } from "./components/spinner.js";
+export { Spinner } from "./components/spinner.js";
 export { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent } from "./components/card.js";
 export { Label } from "./components/label.js";
 export { Textarea } from "./components/textarea.js";
@@ -49,6 +51,9 @@ export { ScreenAdaptiveView } from "./components/layout/screen-adaptive-view.js"
 
 export { useMediaQuery } from "./hooks/use-media-query.js";
 
+export { useAsyncAction } from "./hooks/use-async-action.js";
+export type { AsyncAction, UseAsyncActionOptions } from "./hooks/use-async-action.js";
+
 // Shared building blocks
 export { RelativeTime } from "./components/relative-time.js";
 export type { RelativeTimeProps } from "./components/relative-time.js";