@viibestack/ui 0.6.4 → 0.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@viibestack/ui",
-  "version": "0.6.4",
-  "description": "Dependency-free React UI kit -- icons, core components (Button, Card, Input, Modal, etc.), a real per-app data client (listRows/upsertRow/deleteRow/captureClientError), a real per-app end-user auth client (signUp/logIn/logOut/getCurrentUser/reportError), and a self-gating PoweredByBadge component -- backed by ViibeStack's own platform-managed data store.",
+  "version": "0.7.0",
+  "description": "Dependency-free React UI kit -- icons, core components (Button, Card, Input, Modal, etc.), gamification primitives (PointsDisplay, StreakCounter, Achievements, Leaderboard, fireReward), a real per-app data client (listRows/upsertRow/deleteRow/captureClientError), a real per-app end-user auth client (signUp/logIn/logOut/getCurrentUser/reportError), and a self-gating PoweredByBadge component -- backed by ViibeStack's own platform-managed data store.",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -13,6 +13,7 @@
     "react-dom": ">=18"
   },
   "devDependencies": {
+    "@types/canvas-confetti": "^1.9.0",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "react": "^19",
@@ -24,6 +25,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/ext-apps": "^1.7.4"
+    "@modelcontextprotocol/ext-apps": "^1.7.4",
+    "canvas-confetti": "^1.9.4"
   }
 }

package/src/auth.ts

@@ -171,6 +171,39 @@ export async function logOut(): Promise<void> {
   await callAppAuth("/logout", { method: "POST", body: JSON.stringify({ session_id: stored.sessionId }) });
 }
 
+// Single-flight guard for the refresh call below -- without this, calling
+// getCurrentUser() from more than one place on the same page load (a nav
+// component AND a page component each checking auth in their own
+// useEffect, a completely normal shape for a generated app) fires two
+// concurrent /session/refresh calls with the SAME still-stored session_id.
+// The auth service rotates that id on every refresh (see services/auth's
+// own comment on that route), so only the first of the two UPDATEs
+// actually matches a row -- the second gets back "session expired" even
+// though the first one just succeeded, and its `saveStoredSession(null)`
+// then wipes out the perfectly valid session the first call just saved,
+// logging a real signed-in user out. Confirmed as the root cause of a
+// real_accounts logout report (2026-07-19) -- funneling every concurrent
+// caller through the SAME in-flight promise means only one refresh request
+// is ever sent for a given expiring token, regardless of how many
+// components independently call getCurrentUser() at once. Does not cover
+// two separate browser TABS refreshing at once (each has its own module
+// state) -- that's a rarer trigger and would need cross-tab coordination
+// this fix doesn't attempt.
+let refreshInFlight: Promise<AppUser | null> | null = null;
+
+async function refreshCurrentSession(sessionId: string): Promise<AppUser | null> {
+  const result = await callAppAuth<SessionResponse>("/session/refresh", {
+    method: "POST",
+    body: JSON.stringify({ session_id: sessionId }),
+  });
+  if (!result.ok) {
+    saveStoredSession(null);
+    return null;
+  }
+  saveStoredSession(result.body);
+  return result.body.user;
+}
+
 // The one function generated app code is expected to call on every page
 // load to find out "is anyone logged in" -- returns null if there's no
 // session, or if the session has expired/been revoked server-side (in
@@ -183,16 +216,12 @@ export async function getCurrentUser(): Promise<AppUser | null> {
   const needsRefresh = exp == null || exp - Math.floor(Date.now() / 1000) < 120;
   if (!needsRefresh) return stored.user;
 
-  const result = await callAppAuth<SessionResponse>("/session/refresh", {
-    method: "POST",
-    body: JSON.stringify({ session_id: stored.sessionId }),
-  });
-  if (!result.ok) {
-    saveStoredSession(null);
-    return null;
+  if (!refreshInFlight) {
+    refreshInFlight = refreshCurrentSession(stored.sessionId).finally(() => {
+      refreshInFlight = null;
+    });
   }
-  saveStoredSession(result.body);
-  return result.body.user;
+  return refreshInFlight;
 }
 
 export async function requestPasswordReset(email: string): Promise<ActionResult> {

package/src/gamification.tsx

@@ -0,0 +1,174 @@
+"use client";
+
+// Data-agnostic gamification UI -- points/streaks/achievements/leaderboard
+// display components plus a confetti reward helper. Deliberately NOT tied to
+// any specific data table or backend: the generated app owns its own points/
+// badges/streak data (via this package's own listRows/upsertRow, same as any
+// other entity) and just passes the current values in as props. Styled with
+// the same Tailwind utility classes + --primary CSS custom property as
+// components.tsx, so these read as part of the same design system rather
+// than a bolted-on plugin.
+import type { ReactNode } from "react";
+import { TrophyIcon, FlameIcon, StarIcon, type IconProps } from "./icons";
+import { Avatar } from "./components";
+
+function cx(...parts: (string | false | null | undefined)[]): string {
+  return parts.filter(Boolean).join(" ");
+}
+
+// ── Points ──────────────────────────────────────────────────────────────────
+
+export interface PointsDisplayProps {
+  points: number;
+  label?: string;
+  icon?: ReactNode;
+  className?: string;
+}
+
+export function PointsDisplay({ points, label = "points", icon, className }: PointsDisplayProps) {
+  return (
+    <div className={cx("inline-flex items-center gap-1.5 rounded-full bg-primary/10 px-3 py-1 text-sm font-semibold text-primary", className)}>
+      {icon ?? <StarIcon size={16} />}
+      <span>{points.toLocaleString()}</span>
+      {label && <span className="font-normal opacity-75">{label}</span>}
+    </div>
+  );
+}
+
+// ── Streak ──────────────────────────────────────────────────────────────────
+
+export interface StreakCounterProps {
+  days: number;
+  // True when today's activity hasn't happened yet and the streak will
+  // reset if the user doesn't act -- lets the app nudge urgency without
+  // this component needing to know what "activity" even means for it.
+  atRisk?: boolean;
+  className?: string;
+}
+
+export function StreakCounter({ days, atRisk, className }: StreakCounterProps) {
+  return (
+    <div
+      className={cx(
+        "inline-flex items-center gap-1.5 rounded-full px-3 py-1 text-sm font-semibold",
+        atRisk ? "bg-amber-100 text-amber-700 dark:bg-amber-900/40 dark:text-amber-400" : "bg-orange-100 text-orange-700 dark:bg-orange-900/40 dark:text-orange-400",
+        className,
+      )}
+      title={atRisk ? "Streak at risk -- act today to keep it going" : undefined}
+    >
+      <FlameIcon size={16} />
+      <span>{days.toLocaleString()}</span>
+      <span className="font-normal opacity-75">day{days === 1 ? "" : "s"}</span>
+    </div>
+  );
+}
+
+// ── Achievements ────────────────────────────────────────────────────────────
+
+export interface Achievement {
+  id: string;
+  label: string;
+  description?: string;
+  icon?: ReactNode;
+  unlocked: boolean;
+  unlockedAt?: string;
+}
+
+export interface AchievementBadgeProps {
+  achievement: Achievement;
+  size?: number;
+  className?: string;
+}
+
+// Locked badges render at reduced opacity + grayscale rather than being
+// hidden entirely -- seeing what's still to unlock is part of what makes a
+// badge collection motivating, same reasoning most achievement systems use.
+export function AchievementBadge({ achievement, size = 56, className }: AchievementBadgeProps) {
+  const iconProps: IconProps = { size: Math.round(size * 0.45) };
+  return (
+    <div className={cx("flex flex-col items-center gap-1 text-center", className)} title={achievement.description}>
+      <div
+        className={cx(
+          "flex items-center justify-center rounded-full border-2",
+          achievement.unlocked
+            ? "border-primary bg-primary/10 text-primary"
+            : "border-gray-200 bg-gray-50 text-gray-300 grayscale dark:border-gray-800 dark:bg-gray-900 dark:text-gray-700",
+        )}
+        style={{ width: size, height: size }}
+      >
+        {achievement.icon ?? <TrophyIcon {...iconProps} />}
+      </div>
+      <span className={cx("max-w-[6rem] truncate text-xs font-medium", !achievement.unlocked && "text-gray-400 dark:text-gray-600")}>
+        {achievement.label}
+      </span>
+    </div>
+  );
+}
+
+export interface AchievementListProps {
+  achievements: Achievement[];
+  size?: number;
+  className?: string;
+}
+
+export function AchievementList({ achievements, size, className }: AchievementListProps) {
+  return (
+    <div className={cx("flex flex-wrap gap-4", className)}>
+      {achievements.map((a) => (
+        <AchievementBadge key={a.id} achievement={a} size={size} />
+      ))}
+    </div>
+  );
+}
+
+// ── Leaderboard ─────────────────────────────────────────────────────────────
+
+export interface LeaderboardEntry {
+  id: string;
+  name: string;
+  score: number;
+  avatarUrl?: string;
+}
+
+export interface LeaderboardProps {
+  entries: LeaderboardEntry[];
+  // Highlights the current viewer's own row (by id) so they can find
+  // themselves in a long list instead of having to count ranks.
+  highlightId?: string;
+  scoreLabel?: string;
+  className?: string;
+}
+
+// Ranks by array order (caller sorts however it wants -- points this week,
+// all-time, etc.) rather than re-sorting by score here, so a leaderboard can
+// legitimately be ordered by something other than raw score if the app
+// wants that.
+export function Leaderboard({ entries, highlightId, scoreLabel = "pts", className }: LeaderboardProps) {
+  return (
+    <div className={cx("flex flex-col divide-y divide-gray-200 rounded-lg border border-gray-200 dark:divide-gray-800 dark:border-gray-800", className)}>
+      {entries.map((entry, i) => {
+        const rank = i + 1;
+        const mine = entry.id === highlightId;
+        return (
+          <div
+            key={entry.id}
+            className={cx(
+              "flex items-center gap-3 px-3 py-2",
+              mine && "bg-primary/5",
+            )}
+          >
+            <span className={cx("w-6 shrink-0 text-right text-sm font-semibold", rank <= 3 ? "text-primary" : "text-gray-400 dark:text-gray-600")}>
+              {rank}
+            </span>
+            <Avatar name={entry.name} src={entry.avatarUrl} size={28} />
+            <span className={cx("flex-1 truncate text-sm", mine ? "font-semibold" : "font-medium")}>{entry.name}</span>
+            <span className="text-sm font-semibold text-gray-700 dark:text-gray-300">
+              {entry.score.toLocaleString()} <span className="font-normal opacity-60">{scoreLabel}</span>
+            </span>
+          </div>
+        );
+      })}
+      {entries.length === 0 && <p className="px-3 py-4 text-center text-sm text-gray-500 dark:text-gray-500">No scores yet.</p>}
+    </div>
+  );
+}

package/src/icons.tsx

@@ -305,3 +305,31 @@ export function SearchIcon(props: IconProps = {}) {
     </svg>
   );
 }
+
+export function TrophyIcon(props: IconProps = {}) {
+  return (
+    <svg {...svgProps(props)}>
+      <path d="M8 21h8" />
+      <path d="M12 17v4" />
+      <path d="M7 4h10v6a5 5 0 0 1-10 0V4z" />
+      <path d="M17 5h3a2 2 0 0 1-2 4h-1" />
+      <path d="M7 5H4a2 2 0 0 0 2 4h1" />
+    </svg>
+  );
+}
+
+export function FlameIcon(props: IconProps = {}) {
+  return (
+    <svg {...svgProps(props)}>
+      <path d="M12 2s-6 6.5-6 11a6 6 0 0 0 12 0c0-1.5-.5-3-1.5-4 0 1.5-1 2.5-1.5 2.5C15.5 8 12 6 12 2z" />
+    </svg>
+  );
+}
+
+export function StarIcon(props: IconProps = {}) {
+  return (
+    <svg {...svgProps(props)}>
+      <polygon points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2" />
+    </svg>
+  );
+}

package/src/index.ts

@@ -4,3 +4,5 @@ export * from "./nav";
 export * from "./data";
 export * from "./auth";
 export * from "./badge";
+export * from "./gamification";
+export * from "./reward";

package/src/reward.ts

@@ -0,0 +1,34 @@
+// Celebratory-moment helper for gamification.tsx's components (a level-up,
+// an unlocked achievement, a completed streak) -- thin wrapper around
+// canvas-confetti, the standard for this since it's tiny (~4kB), framework-
+// agnostic, and handles the canvas lifecycle itself. This is the one real
+// runtime dependency in an otherwise dependency-free package -- worth it
+// here since hand-rolling particle physics would be strictly worse for
+// exactly the same result.
+"use client";
+
+import confetti from "canvas-confetti";
+
+export interface RewardOptions {
+  // Anchors the burst to a specific element (e.g. the button just clicked)
+  // instead of firing from the center of the screen -- pass the element's
+  // getBoundingClientRect() origin, or omit for a centered burst.
+  originElement?: HTMLElement | null;
+  particleCount?: number;
+  colors?: string[];
+}
+
+export function fireReward(opts: RewardOptions = {}) {
+  const { originElement, particleCount = 120, colors } = opts;
+  let origin: { x: number; y: number } | undefined;
+  if (originElement) {
+    const rect = originElement.getBoundingClientRect();
+    origin = { x: (rect.left + rect.width / 2) / window.innerWidth, y: (rect.top + rect.height / 2) / window.innerHeight };
+  }
+  confetti({
+    particleCount,
+    spread: 70,
+    origin: origin ?? { y: 0.6 },
+    colors,
+  });
+}