@cntyclub/ui-react 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntyclub/ui-react",
-  "version": "0.9.0",
+  "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/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/index.ts

@@ -27,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";