@cntyclub/ui-react 0.8.2 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntyclub/ui-react",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "description": "React component library for the Country Club UI Kit — Base UI primitives styled with the Country Club design system (Tailwind CSS v4)",
   "type": "module",
   "sideEffects": [
@@ -39,6 +39,7 @@
     "@tiptap/pm": "^3.26.1",
     "@tiptap/react": "^3.26.1",
     "@tiptap/starter-kit": "^3.26.1",
+    "canvas-confetti": "^1.9.3",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "date-fns": "^4.1.0",
@@ -64,6 +65,7 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
+    "@types/canvas-confetti": "^1.9.0",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "react": "^19.1.0",

package/src/components/ui/animated-counter.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import type * as React from "react";
+
+import { cn } from "../../lib/utils/css";
+
+interface AnimatedCounterProps extends Omit<React.ComponentProps<"span">, "children"> {
+  /** The target value to animate to. */
+  value: number;
+  /** Tween duration in ms (default 650). */
+  duration?: number;
+  /** Decimal places to render (default 0). */
+  decimals?: number;
+  /** Prefix rendered before the number, e.g. "$". */
+  prefix?: string;
+  /** Suffix rendered after the number, e.g. "%". */
+  suffix?: string;
+  /** Group digits with thousands separators (default true). */
+  separator?: boolean;
+}
+
+/**
+ * A number that tweens smoothly from its previous value to the next whenever
+ * `value` changes — e.g. dashboard stats re-counting when the time range
+ * switches. Dependency-free (requestAnimationFrame), so it stays tiny and works
+ * anywhere. Respects `prefers-reduced-motion` by snapping to the final value.
+ *
+ * The animation is purely visual; the accessible text is always the final
+ * value (via `aria-label`) so screen readers never read the intermediate tween.
+ */
+function AnimatedCounter({
+  value,
+  duration = 650,
+  decimals = 0,
+  prefix = "",
+  suffix = "",
+  separator = true,
+  className,
+  ...props
+}: AnimatedCounterProps) {
+  const [display, setDisplay] = useState(value);
+  const fromRef = useRef(value);
+  const rafRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    const from = fromRef.current;
+    const to = value;
+    if (from === to) return;
+
+    const reduce =
+      typeof window !== "undefined" &&
+      window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+    if (reduce || duration <= 0) {
+      fromRef.current = to;
+      setDisplay(to);
+      return;
+    }
+
+    let start: number | null = null;
+    const step = (ts: number) => {
+      if (start === null) start = ts;
+      const t = Math.min(1, (ts - start) / duration);
+      // easeOutCubic — quick then settles, matching a "count up" feel.
+      const eased = 1 - Math.pow(1 - t, 3);
+      const current = from + (to - from) * eased;
+      setDisplay(current);
+      if (t < 1) {
+        rafRef.current = requestAnimationFrame(step);
+      } else {
+        fromRef.current = to;
+      }
+    };
+    rafRef.current = requestAnimationFrame(step);
+    return () => {
+      if (rafRef.current !== null) cancelAnimationFrame(rafRef.current);
+    };
+  }, [value, duration]);
+
+  const rounded = Number(display.toFixed(decimals));
+  const formatted = separator
+    ? rounded.toLocaleString(undefined, {
+        minimumFractionDigits: decimals,
+        maximumFractionDigits: decimals,
+      })
+    : rounded.toFixed(decimals);
+
+  const finalLabel = `${prefix}${value.toLocaleString(undefined, {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  })}${suffix}`;
+
+  return (
+    <span
+      className={cn("tabular-nums", className)}
+      data-slot="animated-counter"
+      aria-label={finalLabel}
+      {...props}
+    >
+      <span aria-hidden>
+        {prefix}
+        {formatted}
+        {suffix}
+      </span>
+    </span>
+  );
+}
+
+export { AnimatedCounter, type AnimatedCounterProps };

package/src/components/ui/confetti.tsx

@@ -0,0 +1,196 @@
+"use client";
+
+import confetti from "canvas-confetti";
+import type {
+  GlobalOptions as ConfettiGlobalOptions,
+  CreateTypes as ConfettiInstance,
+  Options as ConfettiOptions,
+} from "canvas-confetti";
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from "react";
+import type * as React from "react";
+
+import { Button, type ButtonProps } from "./button";
+
+/** The brand celebration palette — soft violet / pink / peach / cream. */
+export const CONFETTI_COLORS = ["#a786ff", "#fd8bbc", "#eca184", "#f8deb1"] as const;
+
+function prefersReducedMotion(): boolean {
+  return (
+    typeof window !== "undefined" &&
+    !!window.matchMedia?.("(prefers-reduced-motion: reduce)").matches
+  );
+}
+
+export interface SideCannonsOptions {
+  /** How long the cannons keep firing, in ms (default 3000). */
+  durationMs?: number;
+  /** Confetti colors (default {@link CONFETTI_COLORS}). */
+  colors?: readonly string[];
+  /** Particles emitted per side per frame (default 2). */
+  particleCount?: number;
+  /** z-index of the confetti canvas (default 100). */
+  zIndex?: number;
+}
+
+/**
+ * Fires confetti from the left and right edges of the viewport for a few
+ * seconds — the "side cannons" celebration. Purely imperative, so it can be
+ * triggered from an effect (e.g. the first time a page loads) without rendering
+ * anything. No-ops on the server and when the user prefers reduced motion.
+ *
+ * @example
+ * useEffect(() => { sideCannons(); }, []);
+ */
+export function sideCannons(options: SideCannonsOptions = {}): void {
+  if (typeof window === "undefined" || prefersReducedMotion()) return;
+
+  const {
+    durationMs = 3000,
+    colors = CONFETTI_COLORS,
+    particleCount = 2,
+    zIndex = 100,
+  } = options;
+
+  const end = performance.now() + durationMs;
+  const shared = { particleCount, spread: 55, startVelocity: 60, colors: [...colors], zIndex };
+
+  const frame = () => {
+    if (performance.now() > end) return;
+    void confetti({ ...shared, angle: 60, origin: { x: 0, y: 0.5 } });
+    void confetti({ ...shared, angle: 120, origin: { x: 1, y: 0.5 } });
+    requestAnimationFrame(frame);
+  };
+
+  frame();
+}
+
+type ConfettiApi = {
+  /** Fire the confetti instance, merging `options` over the component's. */
+  fire: (options?: ConfettiOptions) => void;
+};
+
+export type ConfettiRef = ConfettiApi | null;
+
+export type ConfettiProps = React.ComponentPropsWithRef<"canvas"> & {
+  /** Per-shot options merged into every `fire()` call. */
+  options?: ConfettiOptions;
+  /** Global options passed to `confetti.create` (resize / worker). */
+  globalOptions?: ConfettiGlobalOptions;
+  /** Skip the automatic fire on mount — drive it via the ref instead. */
+  manualstart?: boolean;
+  children?: ReactNode;
+};
+
+const ConfettiContext = createContext<ConfettiApi>({} as ConfettiApi);
+
+/**
+ * A canvas-bound confetti emitter. Renders its own `<canvas>` and exposes an
+ * imperative `fire()` via ref (and to descendants through context). By default
+ * it fires once on mount; pass `manualstart` to control it yourself.
+ *
+ * For a full-screen, no-render celebration prefer {@link sideCannons}.
+ */
+const ConfettiComponent = forwardRef<ConfettiRef, ConfettiProps>((props, ref) => {
+  const {
+    options,
+    globalOptions = { resize: true, useWorker: true },
+    manualstart = false,
+    children,
+    ...rest
+  } = props;
+  const instanceRef = useRef<ConfettiInstance | null>(null);
+
+  const canvasRef = useCallback(
+    (node: HTMLCanvasElement | null) => {
+      if (node !== null) {
+        if (instanceRef.current) return;
+        instanceRef.current = confetti.create(node, { ...globalOptions, resize: true });
+      } else if (instanceRef.current) {
+        instanceRef.current.reset();
+        instanceRef.current = null;
+      }
+    },
+    [globalOptions],
+  );
+
+  const fire = useCallback(
+    async (opts: ConfettiOptions = {}) => {
+      if (prefersReducedMotion()) return;
+      try {
+        await instanceRef.current?.({ ...options, ...opts });
+      } catch (error) {
+        console.error("Confetti error:", error);
+      }
+    },
+    [options],
+  );
+
+  const api = useMemo<ConfettiApi>(() => ({ fire }), [fire]);
+
+  useImperativeHandle(ref, () => api, [api]);
+
+  useEffect(() => {
+    if (!manualstart) void fire();
+  }, [manualstart, fire]);
+
+  return (
+    <ConfettiContext.Provider value={api}>
+      <canvas data-slot="confetti" ref={canvasRef} {...rest} />
+      {children}
+    </ConfettiContext.Provider>
+  );
+});
+ConfettiComponent.displayName = "Confetti";
+
+export const Confetti = ConfettiComponent;
+
+/** Access the nearest {@link Confetti}'s imperative `fire()` from a child. */
+export function useConfetti(): ConfettiApi {
+  return useContext(ConfettiContext);
+}
+
+export interface ConfettiButtonProps extends ButtonProps {
+  /** Confetti options; origin defaults to the button's center. */
+  options?: ConfettiOptions & ConfettiGlobalOptions & { canvas?: HTMLCanvasElement };
+}
+
+/**
+ * A {@link Button} that bursts confetti from its own center on click. Handy for
+ * "Claim", "Done", or other one-off celebratory actions.
+ */
+function ConfettiButtonComponent({ options, children, onClick, ...props }: ConfettiButtonProps) {
+  const handleClick = async (event: React.MouseEvent<HTMLButtonElement>) => {
+    onClick?.(event);
+    if (prefersReducedMotion()) return;
+    try {
+      const rect = event.currentTarget.getBoundingClientRect();
+      const x = rect.left + rect.width / 2;
+      const y = rect.top + rect.height / 2;
+      await confetti({
+        ...options,
+        origin: { x: x / window.innerWidth, y: y / window.innerHeight },
+      });
+    } catch (error) {
+      console.error("Confetti button error:", error);
+    }
+  };
+
+  return (
+    <Button data-slot="confetti-button" onClick={handleClick} {...props}>
+      {children}
+    </Button>
+  );
+}
+ConfettiButtonComponent.displayName = "ConfettiButton";
+
+export const ConfettiButton = ConfettiButtonComponent;

package/src/components/ui/date-picker.tsx

@@ -0,0 +1,154 @@
+"use client";
+
+import { format } from "date-fns";
+import { CalendarIcon } from "lucide-react";
+import type { DateRange, Matcher } from "react-day-picker";
+
+import { Button } from "./button";
+import { Calendar } from "./calendar";
+import { Popover, PopoverContent, PopoverTrigger } from "./popover";
+import { cn } from "../../lib/utils/css";
+
+/** Build react-day-picker `disabled` matchers from optional min/max bounds. */
+function boundsMatcher(fromDate?: Date, toDate?: Date): Matcher[] | undefined {
+  const out: Matcher[] = [];
+  if (fromDate) out.push({ before: fromDate });
+  if (toDate) out.push({ after: toDate });
+  return out.length ? out : undefined;
+}
+
+interface DatePickerProps {
+  /** The selected date (controlled). */
+  value?: Date;
+  onValueChange?: (date: Date | undefined) => void;
+  placeholder?: string;
+  /** Trigger button `disabled`. */
+  disabled?: boolean;
+  /** Restrict selectable days (passed straight to react-day-picker). */
+  fromDate?: Date;
+  toDate?: Date;
+  /** date-fns format for the trigger label (default "LLL dd, y"). */
+  displayFormat?: string;
+  align?: "start" | "center" | "end";
+  className?: string;
+  id?: string;
+  "aria-label"?: string;
+}
+
+/**
+ * A single-date picker: a button that opens a calendar in a popover. The
+ * canonical way to take a date in this system — never a native `<input
+ * type="date">`. Controlled via `value` / `onValueChange`.
+ */
+function DatePicker({
+  value,
+  onValueChange,
+  placeholder = "Pick a date",
+  disabled,
+  fromDate,
+  toDate,
+  displayFormat = "LLL dd, y",
+  align = "start",
+  className,
+  id,
+  ...props
+}: DatePickerProps) {
+  return (
+    <Popover>
+      <PopoverTrigger
+        render={
+          <Button
+            className={cn("w-full justify-start font-normal", !value && "text-muted-foreground", className)}
+            disabled={disabled}
+            id={id}
+            variant="outline"
+            aria-label={props["aria-label"]}
+          />
+        }
+      >
+        <CalendarIcon aria-hidden />
+        {value ? format(value, displayFormat) : <span>{placeholder}</span>}
+      </PopoverTrigger>
+      <PopoverContent align={align} className="w-auto p-0">
+        <Calendar
+          autoFocus
+          disabled={boundsMatcher(fromDate, toDate)}
+          mode="single"
+          onSelect={(d) => onValueChange?.(d)}
+          selected={value}
+        />
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+interface DateRangePickerProps {
+  value?: DateRange;
+  onValueChange?: (range: DateRange | undefined) => void;
+  placeholder?: string;
+  disabled?: boolean;
+  fromDate?: Date;
+  toDate?: Date;
+  numberOfMonths?: number;
+  displayFormat?: string;
+  align?: "start" | "center" | "end";
+  className?: string;
+  id?: string;
+  "aria-label"?: string;
+}
+
+/**
+ * A date-range picker: pick a start and (optionally) end date. Controlled via
+ * `value` / `onValueChange` with react-day-picker's `{from, to}` shape.
+ */
+function DateRangePicker({
+  value,
+  onValueChange,
+  placeholder = "Pick a date range",
+  disabled,
+  fromDate,
+  toDate,
+  numberOfMonths = 2,
+  displayFormat = "LLL dd, y",
+  align = "start",
+  className,
+  id,
+  ...props
+}: DateRangePickerProps) {
+  const label = value?.from
+    ? value.to
+      ? `${format(value.from, displayFormat)} – ${format(value.to, displayFormat)}`
+      : format(value.from, displayFormat)
+    : null;
+
+  return (
+    <Popover>
+      <PopoverTrigger
+        render={
+          <Button
+            className={cn("w-full justify-start font-normal", !label && "text-muted-foreground", className)}
+            disabled={disabled}
+            id={id}
+            variant="outline"
+            aria-label={props["aria-label"]}
+          />
+        }
+      >
+        <CalendarIcon aria-hidden />
+        {label ?? <span>{placeholder}</span>}
+      </PopoverTrigger>
+      <PopoverContent align={align} className="w-auto p-0">
+        <Calendar
+          autoFocus
+          disabled={boundsMatcher(fromDate, toDate)}
+          mode="range"
+          numberOfMonths={numberOfMonths}
+          onSelect={(r) => onValueChange?.(r)}
+          selected={value}
+        />
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+export { DatePicker, DateRangePicker, type DatePickerProps, type DateRangePickerProps };

package/src/index.ts

@@ -11,11 +11,13 @@ export * from "./components/ui/aspect-ratio";
 export * from "./components/ui/autocomplete";
 export * from "./components/ui/avatar";
 export * from "./components/ui/avatar-group";
+export * from "./components/ui/animated-counter";
 export * from "./components/ui/badge";
 export * from "./components/ui/badge-group";
 export * from "./components/ui/breadcrumb";
 export * from "./components/ui/button";
 export * from "./components/ui/calendar";
+export * from "./components/ui/date-picker";
 export * from "./components/ui/card";
 export * from "./components/ui/carousel";
 export * from "./components/ui/chart";
@@ -25,6 +27,7 @@ export * from "./components/ui/checkbox-group";
 export * from "./components/ui/collapsible";
 export * from "./components/ui/combobox";
 export * from "./components/ui/command";
+export * from "./components/ui/confetti";
 export * from "./components/ui/credit-card";
 export * from "./components/ui/data-table-paged";
 export * from "./components/ui/drawer";