@viibestack/ui 0.7.3 → 0.7.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@viibestack/ui",
-  "version": "0.7.3",
-  "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.",
+  "version": "0.7.7",
+  "description": "Dependency-free React UI kit -- icons, core components (Button, Card, Input, Modal, etc.), a TeamGrid/TeamMemberCard people-grid pattern, gamification primitives (PointsDisplay, StreakCounter, Achievements, Leaderboard, fireReward), a real per-app data client for browser code (listRows/listRowsPage/getRow/upsertRow/deleteRow/captureClientError) plus server-safe variants for Route Handlers/Server Components (listRowsServer/listRowsPageServer/getRowServer/upsertRowServer/deleteRowServer/resolveAppIdByHostname), 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",

package/src/auth.ts

@@ -20,12 +20,24 @@ export type ActionResult = { ok: true } | { ok: false; error: string };
 
 let appIdPromise: Promise<string | null> | null = null;
 
+// Caches only a successful resolution -- a failed one (network blip, timing
+// on very first page load) clears appIdPromise back to null so the NEXT
+// signUp()/logIn()/etc. call on this same page load retries instead of
+// being permanently stuck on one transient failure.
 function resolveAppId(): Promise<string | null> {
   if (!appIdPromise) {
     appIdPromise = fetch(`${window.location.origin}/api/apps/resolve?hostname=${window.location.hostname}`)
       .then((res) => (res.ok ? res.json() : null))
-      .then((data: { app_id?: string } | null) => data?.app_id ?? null)
-      .catch(() => null);
+      // Response.json() resolves to `unknown` under newer TS DOM lib
+      // versions (not `any`), so a typed callback param above rejects it --
+      // cast in the body instead, same as every other res.json() call site
+      // in this file.
+      .then((data) => (data as { app_id?: string } | null)?.app_id ?? null)
+      .catch(() => null)
+      .then((appId) => {
+        if (appId === null) appIdPromise = null;
+        return appId;
+      });
   }
   return appIdPromise;
 }
@@ -309,7 +321,15 @@ export async function createMonetizationCheckout(interval: "monthly" | "annual",
     const res = await fetch(`${window.location.origin}/api/apps/${appId}/monetization/checkout`, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${stored.jwt}` },
-      body: JSON.stringify({ billing_interval: interval, seats }),
+      // return_origin tells the server which origin to send Stripe back to --
+      // this app-auth session lives in localStorage (origin-scoped), so if
+      // the checkout's success_url ever pointed somewhere else (e.g. a BYOD
+      // custom domain's server-side deployed_url falling back to the
+      // platform's *.apps.sideblend.com dispatch hostname) the post-payment
+      // redirect would land the browser on a different origin than the one
+      // holding this session, and getMonetizationStatus() would report
+      // "not signed in" forever -- indistinguishable from "no subscription".
+      body: JSON.stringify({ billing_interval: interval, seats, return_origin: window.location.origin }),
     });
     const body = (await res.json().catch(() => ({}))) as { url?: string; error?: string };
     if (!res.ok || !body.url) return { ok: false, error: body.error ?? "failed to start checkout" };

package/src/badge.tsx

@@ -18,11 +18,16 @@ function resolveShowBadge(): Promise<boolean> {
   if (!showBadgePromise) {
     showBadgePromise = fetch(`${window.location.origin}/api/apps/resolve?hostname=${window.location.hostname}`)
       .then((res) => (res.ok ? res.json() : null))
-      .then((data: { app_id?: string } | null) => {
-        if (!data?.app_id) return true;
-        return fetch(`${window.location.origin}/api/apps/${data.app_id}/badge-status`)
+      // Response.json() resolves to `unknown` under newer TS DOM lib
+      // versions (not `any`), so a typed callback param above rejects it --
+      // cast in the body instead, same as every other res.json() call site
+      // in this package.
+      .then((data) => {
+        const appId = (data as { app_id?: string } | null)?.app_id;
+        if (!appId) return true;
+        return fetch(`${window.location.origin}/api/apps/${appId}/badge-status`)
           .then((res) => (res.ok ? res.json() : null))
-          .then((status: { show_badge?: boolean } | null) => status?.show_badge ?? true);
+          .then((status) => (status as { show_badge?: boolean } | null)?.show_badge ?? true);
       })
       .catch(() => true);
   }
@@ -32,7 +37,14 @@ function resolveShowBadge(): Promise<boolean> {
 const DISMISS_KEY = "viibestack_badge_dismissed";
 
 export function PoweredByBadge() {
-  const [show, setShow] = useState(false);
+  // null = badge-status still resolving. The badge (and its backlink to
+  // viibestack.ai) is in the DOM from first render but visibility:hidden
+  // until resolution -- previously the whole element only existed after a
+  // two-fetch chain settled, so a crawler snapshotting the rendered page
+  // before then never saw the platform's one organic backlink from every
+  // free-plan app. Hidden-not-absent keeps that link parseable the whole
+  // time without ever flashing the badge at a plan-waived tenant.
+  const [show, setShow] = useState<boolean | null>(null);
   const [dismissed, setDismissed] = useState(false);
 
   useEffect(() => {
@@ -50,14 +62,16 @@ export function PoweredByBadge() {
     };
   }, []);
 
-  if (!show || dismissed) return null;
+  if (show === false || dismissed) return null;
 
   return (
     <span
       style={{
+        visibility: show === null ? "hidden" : "visible",
         position: "fixed",
         bottom: "1rem",
-        right: "1rem",
+        left: "50%",
+        transform: "translateX(-50%)",
         zIndex: 9999,
         display: "flex",
         alignItems: "center",

package/src/components.tsx

@@ -447,12 +447,20 @@ export function Tbody(props: HTMLAttributes<HTMLTableSectionElement>) {
   return <tbody className="divide-y divide-gray-200 dark:divide-gray-800" {...props} />;
 }
 
-export function Tr(props: HTMLAttributes<HTMLTableRowElement>) {
-  return <tr {...props} />;
+export function Tr({ className, ...rest }: HTMLAttributes<HTMLTableRowElement>) {
+  return <tr className={cx("transition-colors hover:bg-gray-50 dark:hover:bg-gray-900/50", className)} {...rest} />;
 }
 
 export function Th({ className, ...rest }: ThHTMLAttributes<HTMLTableCellElement>) {
-  return <th className={cx("px-4 py-2.5 font-medium text-gray-500 dark:text-gray-400", className)} {...rest} />;
+  return (
+    <th
+      className={cx(
+        "px-4 py-2.5 text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400",
+        className,
+      )}
+      {...rest}
+    />
+  );
 }
 
 export function Td({ className, ...rest }: TdHTMLAttributes<HTMLTableCellElement>) {

package/src/dashboard.tsx

@@ -0,0 +1,444 @@
+"use client";
+
+// Admin-dashboard/AI-console building blocks -- StatCard, ProgressBar,
+// Breadcrumb, Pagination, Tooltip, Timeline, PricingTable, ChatBubble/
+// ChatPanel. Same conventions as components.tsx (plain Tailwind utility
+// classes, bg-primary/text-primary picking up this app's --primary CSS
+// custom property automatically, dark: variants throughout) -- these are
+// a separate file rather than additions to components.tsx because they're
+// a distinct, later-added vocabulary (dashboards, AI chat UIs, pricing
+// pages) rather than generic form/layout primitives. Visual patterns
+// (card shape, chat bubble layout, stat delta styling) are informed by
+// packages/design-library's catalog -- see that package's README for the
+// design source and licensing provenance.
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Avatar, Badge } from "./components";
+import { CheckIcon, ChevronLeftIcon, ChevronRightIcon, SendIcon, TrendDownIcon, TrendUpIcon } from "./icons";
+
+function cx(...parts: (string | false | null | undefined)[]): string {
+  return parts.filter(Boolean).join(" ");
+}
+
+// ── StatCard ────────────────────────────────────────────────────────────────
+
+export interface StatCardDelta {
+  value: string;
+  direction: "up" | "down" | "flat";
+}
+
+export interface StatCardProps {
+  label: ReactNode;
+  value: ReactNode;
+  icon?: ReactNode;
+  delta?: StatCardDelta;
+  className?: string;
+}
+
+const DELTA_COLOR: Record<StatCardDelta["direction"], string> = {
+  up: "text-green-600 dark:text-green-400",
+  down: "text-red-600 dark:text-red-400",
+  flat: "text-gray-500 dark:text-gray-400",
+};
+
+export function StatCard({ label, value, icon, delta, className }: StatCardProps) {
+  return (
+    <div className={cx("rounded-xl border border-gray-200 bg-white p-5 dark:border-gray-800 dark:bg-gray-900", className)}>
+      <div className="flex items-start justify-between gap-3">
+        <div>
+          <div className="text-sm font-medium text-gray-500 dark:text-gray-400">{label}</div>
+          <div className="mt-1.5 text-2xl font-semibold text-gray-900 dark:text-gray-100">{value}</div>
+        </div>
+        {icon && <div className="shrink-0 rounded-lg bg-primary/10 p-2 text-primary">{icon}</div>}
+      </div>
+      {delta && (
+        <div className={cx("mt-3 inline-flex items-center gap-1 text-xs font-medium", DELTA_COLOR[delta.direction])}>
+          {delta.direction === "up" && <TrendUpIcon size={14} />}
+          {delta.direction === "down" && <TrendDownIcon size={14} />}
+          <span>{delta.value}</span>
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ── ProgressBar ─────────────────────────────────────────────────────────────
+
+export type ProgressVariant = "primary" | "success" | "warning" | "danger";
+
+const PROGRESS_VARIANTS: Record<ProgressVariant, string> = {
+  primary: "bg-primary",
+  success: "bg-green-500",
+  warning: "bg-amber-500",
+  danger: "bg-red-500",
+};
+
+export interface ProgressBarProps {
+  /** 0-100, clamped. */
+  value: number;
+  variant?: ProgressVariant;
+  label?: ReactNode;
+  showValue?: boolean;
+  className?: string;
+}
+
+export function ProgressBar({ value, variant = "primary", label, showValue, className }: ProgressBarProps) {
+  const pct = Math.max(0, Math.min(100, value));
+  return (
+    <div className={className}>
+      {(label || showValue) && (
+        <div className="mb-1.5 flex items-center justify-between text-sm">
+          {label && <span className="font-medium text-gray-700 dark:text-gray-300">{label}</span>}
+          {showValue && <span className="text-gray-500 dark:text-gray-400">{Math.round(pct)}%</span>}
+        </div>
+      )}
+      <div className="h-2 w-full overflow-hidden rounded-full bg-gray-100 dark:bg-gray-800">
+        <div className={cx("h-full rounded-full transition-all", PROGRESS_VARIANTS[variant])} style={{ width: `${pct}%` }} />
+      </div>
+    </div>
+  );
+}
+
+// ── Breadcrumb ──────────────────────────────────────────────────────────────
+
+export interface BreadcrumbItem {
+  label: ReactNode;
+  href?: string;
+}
+
+export interface BreadcrumbProps {
+  items: BreadcrumbItem[];
+  /** Override how a non-final linked item renders, e.g. to use next/link. */
+  renderLink?: (item: BreadcrumbItem) => ReactNode;
+  className?: string;
+}
+
+export function Breadcrumb({ items, renderLink, className }: BreadcrumbProps) {
+  return (
+    <nav aria-label="Breadcrumb" className={cx("flex flex-wrap items-center gap-1.5 text-sm", className)}>
+      {items.map((item, i) => {
+        const last = i === items.length - 1;
+        return (
+          <span key={i} className="flex items-center gap-1.5">
+            {item.href && !last ? (
+              renderLink ? (
+                renderLink(item)
+              ) : (
+                <a href={item.href} className="text-gray-500 hover:text-gray-900 dark:text-gray-400 dark:hover:text-gray-100">
+                  {item.label}
+                </a>
+              )
+            ) : (
+              <span className={last ? "font-medium text-gray-900 dark:text-gray-100" : "text-gray-500 dark:text-gray-400"}>
+                {item.label}
+              </span>
+            )}
+            {!last && <ChevronRightIcon size={14} className="text-gray-300 dark:text-gray-700" />}
+          </span>
+        );
+      })}
+    </nav>
+  );
+}
+
+// ── Pagination ──────────────────────────────────────────────────────────────
+
+export interface PaginationProps {
+  /** 1-based current page. */
+  page: number;
+  totalPages: number;
+  onChange: (page: number) => void;
+  /** Page buttons kept on each side of the current page before collapsing to an ellipsis. */
+  siblingCount?: number;
+  className?: string;
+}
+
+function paginationRange(page: number, totalPages: number, siblingCount: number): (number | "ellipsis")[] {
+  const totalNumbers = siblingCount * 2 + 5;
+  if (totalPages <= totalNumbers) return Array.from({ length: totalPages }, (_, i) => i + 1);
+
+  const left = Math.max(page - siblingCount, 1);
+  const right = Math.min(page + siblingCount, totalPages);
+  const range: (number | "ellipsis")[] = [1];
+  if (left > 2) range.push("ellipsis");
+  for (let i = Math.max(left, 2); i <= Math.min(right, totalPages - 1); i++) range.push(i);
+  if (right < totalPages - 1) range.push("ellipsis");
+  if (totalPages > 1) range.push(totalPages);
+  return range;
+}
+
+const PAGE_BTN =
+  "inline-flex h-8 min-w-8 items-center justify-center rounded-lg px-2 text-sm font-medium transition-colors " +
+  "disabled:cursor-not-allowed disabled:opacity-40";
+
+export function Pagination({ page, totalPages, onChange, siblingCount = 1, className }: PaginationProps) {
+  if (totalPages <= 1) return null;
+  const range = paginationRange(page, totalPages, siblingCount);
+  return (
+    <nav aria-label="Pagination" className={cx("flex items-center gap-1", className)}>
+      <button
+        type="button"
+        onClick={() => onChange(page - 1)}
+        disabled={page <= 1}
+        aria-label="Previous page"
+        className={cx(PAGE_BTN, "text-gray-500 hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-gray-800")}
+      >
+        <ChevronLeftIcon size={16} />
+      </button>
+      {range.map((p, i) =>
+        p === "ellipsis" ? (
+          <span key={`e${i}`} className="px-1 text-gray-400 dark:text-gray-600">
+            …
+          </span>
+        ) : (
+          <button
+            key={p}
+            type="button"
+            onClick={() => onChange(p)}
+            aria-current={p === page ? "page" : undefined}
+            className={cx(
+              PAGE_BTN,
+              p === page ? "bg-primary text-white" : "text-gray-700 hover:bg-gray-100 dark:text-gray-300 dark:hover:bg-gray-800",
+            )}
+          >
+            {p}
+          </button>
+        ),
+      )}
+      <button
+        type="button"
+        onClick={() => onChange(page + 1)}
+        disabled={page >= totalPages}
+        aria-label="Next page"
+        className={cx(PAGE_BTN, "text-gray-500 hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-gray-800")}
+      >
+        <ChevronRightIcon size={16} />
+      </button>
+    </nav>
+  );
+}
+
+// ── Tooltip ─────────────────────────────────────────────────────────────────
+// CSS-only (group-hover/group-focus-within) -- no floating-ui/positioning
+// dependency, consistent with this package's zero-runtime-dependency goal.
+// Fine for short label-style tooltips; not meant for large rich content.
+
+export type TooltipSide = "top" | "bottom" | "left" | "right";
+
+const TOOLTIP_SIDE_CLASS: Record<TooltipSide, string> = {
+  top: "bottom-full left-1/2 -translate-x-1/2 mb-1.5",
+  bottom: "top-full left-1/2 -translate-x-1/2 mt-1.5",
+  left: "right-full top-1/2 -translate-y-1/2 mr-1.5",
+  right: "left-full top-1/2 -translate-y-1/2 ml-1.5",
+};
+
+export interface TooltipProps {
+  content: ReactNode;
+  children: ReactNode;
+  side?: TooltipSide;
+  className?: string;
+}
+
+export function Tooltip({ content, children, side = "top", className }: TooltipProps) {
+  return (
+    <span className={cx("group relative inline-flex", className)}>
+      {children}
+      <span
+        role="tooltip"
+        className={cx(
+          "pointer-events-none absolute z-50 whitespace-nowrap rounded-md bg-gray-900 px-2 py-1 text-xs font-medium text-white opacity-0 " +
+            "shadow-lg transition-opacity duration-150 group-hover:opacity-100 group-focus-within:opacity-100 dark:bg-gray-100 dark:text-gray-900",
+          TOOLTIP_SIDE_CLASS[side],
+        )}
+      >
+        {content}
+      </span>
+    </span>
+  );
+}
+
+// ── Timeline ────────────────────────────────────────────────────────────────
+
+export interface TimelineItem {
+  title: ReactNode;
+  description?: ReactNode;
+  timestamp?: ReactNode;
+  icon?: ReactNode;
+}
+
+export interface TimelineProps {
+  items: TimelineItem[];
+  className?: string;
+}
+
+export function Timeline({ items, className }: TimelineProps) {
+  return (
+    <ol className={cx("relative flex flex-col gap-6 border-l border-gray-200 pl-6 dark:border-gray-800", className)}>
+      {items.map((item, i) => (
+        <li key={i} className="relative">
+          <span className="absolute -left-[1.6rem] flex h-5 w-5 items-center justify-center rounded-full bg-primary/10 text-primary ring-4 ring-white dark:ring-gray-950">
+            {item.icon ?? <span className="h-1.5 w-1.5 rounded-full bg-primary" />}
+          </span>
+          <div className="flex items-baseline justify-between gap-3">
+            <div className="text-sm font-medium text-gray-900 dark:text-gray-100">{item.title}</div>
+            {item.timestamp && <div className="shrink-0 text-xs text-gray-400 dark:text-gray-500">{item.timestamp}</div>}
+          </div>
+          {item.description && <div className="mt-0.5 text-sm text-gray-500 dark:text-gray-400">{item.description}</div>}
+        </li>
+      ))}
+    </ol>
+  );
+}
+
+// ── PricingTable ────────────────────────────────────────────────────────────
+
+export interface PricingPlan {
+  name: ReactNode;
+  price: ReactNode;
+  interval?: ReactNode;
+  description?: ReactNode;
+  features: string[];
+  highlighted?: boolean;
+  /** Rendered under the feature list -- typically a Button. */
+  cta?: ReactNode;
+}
+
+export interface PricingTableProps {
+  plans: PricingPlan[];
+  className?: string;
+}
+
+export function PricingTable({ plans, className }: PricingTableProps) {
+  return (
+    <div className={cx("grid gap-6 sm:grid-cols-2 lg:grid-cols-3", className)}>
+      {plans.map((plan, i) => (
+        <div
+          key={i}
+          className={cx(
+            "flex flex-col rounded-xl border p-6",
+            plan.highlighted
+              ? "border-primary bg-primary/5 shadow-lg"
+              : "border-gray-200 bg-white dark:border-gray-800 dark:bg-gray-900",
+          )}
+        >
+          {plan.highlighted && (
+            <Badge variant="info" className="mb-3 w-fit">
+              Most popular
+            </Badge>
+          )}
+          <div className="text-lg font-semibold text-gray-900 dark:text-gray-100">{plan.name}</div>
+          {plan.description && <div className="mt-1 text-sm text-gray-500 dark:text-gray-400">{plan.description}</div>}
+          <div className="mt-4 flex items-baseline gap-1">
+            <span className="text-3xl font-bold text-gray-900 dark:text-gray-100">{plan.price}</span>
+            {plan.interval && <span className="text-sm text-gray-500 dark:text-gray-400">{plan.interval}</span>}
+          </div>
+          <ul className="mt-5 flex flex-1 flex-col gap-2.5">
+            {plan.features.map((f, fi) => (
+              <li key={fi} className="flex items-start gap-2 text-sm text-gray-700 dark:text-gray-300">
+                <CheckIcon size={16} className="mt-0.5 shrink-0 text-primary" />
+                {f}
+              </li>
+            ))}
+          </ul>
+          {plan.cta && <div className="mt-6">{plan.cta}</div>}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+// ── ChatBubble / ChatPanel ──────────────────────────────────────────────────
+// An AI chat surface is a first-class pattern on this platform (not a
+// generic "messaging app" widget) -- most apps built here either embed the
+// AI add-on directly or build a support/assistant panel around it.
+
+export interface ChatMessage {
+  id: string | number;
+  role: "user" | "assistant";
+  content: ReactNode;
+  timestamp?: ReactNode;
+  name?: string;
+}
+
+export interface ChatBubbleProps {
+  message: ChatMessage;
+  className?: string;
+}
+
+export function ChatBubble({ message, className }: ChatBubbleProps) {
+  const isUser = message.role === "user";
+  return (
+    <div className={cx("flex items-start gap-2.5", isUser && "flex-row-reverse", className)}>
+      <Avatar name={message.name ?? (isUser ? "You" : "AI")} size={28} className={isUser ? undefined : "bg-gray-700"} />
+      <div className={cx("flex max-w-[75%] flex-col gap-1", isUser && "items-end")}>
+        <div
+          className={cx(
+            "rounded-2xl px-3.5 py-2 text-sm",
+            isUser
+              ? "rounded-tr-sm bg-primary text-white"
+              : "rounded-tl-sm bg-gray-100 text-gray-900 dark:bg-gray-800 dark:text-gray-100",
+          )}
+        >
+          {message.content}
+        </div>
+        {message.timestamp && <div className="px-1 text-xs text-gray-400 dark:text-gray-500">{message.timestamp}</div>}
+      </div>
+    </div>
+  );
+}
+
+export interface ChatPanelProps {
+  messages: ChatMessage[];
+  onSend: (text: string) => void;
+  placeholder?: string;
+  disabled?: boolean;
+  className?: string;
+}
+
+// Uncontrolled input (owns its own draft-text state) -- the caller only
+// ever sees a finished message via onSend, same division of responsibility
+// as Modal owning its own open/close focus handling.
+export function ChatPanel({ messages, onSend, placeholder = "Type a message...", disabled, className }: ChatPanelProps) {
+  const [value, setValue] = useState("");
+
+  function submit() {
+    const text = value.trim();
+    if (!text || disabled) return;
+    onSend(text);
+    setValue("");
+  }
+
+  return (
+    <div className={cx("flex flex-col rounded-xl border border-gray-200 bg-white dark:border-gray-800 dark:bg-gray-900", className)}>
+      <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4">
+        {messages.map((m) => (
+          <ChatBubble key={m.id} message={m} />
+        ))}
+      </div>
+      <div className="flex items-center gap-2 border-t border-gray-200 p-3 dark:border-gray-800">
+        <input
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+          onKeyDown={(e) => {
+            if (e.key === "Enter" && !e.shiftKey) {
+              e.preventDefault();
+              submit();
+            }
+          }}
+          placeholder={placeholder}
+          disabled={disabled}
+          className="flex-1 rounded-lg border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 outline-none focus:border-primary focus:ring-1 focus:ring-primary disabled:opacity-50 dark:border-gray-700 dark:bg-gray-900 dark:text-gray-100"
+        />
+        <button
+          type="button"
+          onClick={submit}
+          disabled={disabled || !value.trim()}
+          aria-label="Send message"
+          className="inline-flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-primary text-white transition-colors hover:brightness-90 disabled:cursor-not-allowed disabled:opacity-50"
+        >
+          <SendIcon size={16} />
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/data-table.tsx

@@ -0,0 +1,224 @@
+"use client";
+
+// Admio-styled data table -- search, sortable columns, pagination, and
+// optional row selection, composed from the existing Table primitives and
+// Checkbox/Pagination/Spinner/EmptyState components rather than reinventing
+// any of them. Use this instead of hand-rolling search/sort/pagination
+// logic around the bare Table/Thead/Tbody/Tr/Th/Td primitives in
+// components.tsx -- those stay as the lightweight option for simple,
+// fully client-rendered data with no interactive chrome.
+import { useMemo, useState } from "react";
+import type { ReactNode } from "react";
+import { Checkbox, EmptyState, Spinner, Tbody, Td, Th, Thead, Tr } from "./components";
+import { Pagination } from "./dashboard";
+import { ChevronDownIcon, SearchIcon } from "./icons";
+
+function cx(...parts: (string | false | null | undefined)[]): string {
+  return parts.filter(Boolean).join(" ");
+}
+
+export interface DataTableColumn<T> {
+  key: string;
+  header: ReactNode;
+  render: (row: T) => ReactNode;
+  /** Enables click-to-sort on this column's header. Requires sortValue. */
+  sortable?: boolean;
+  /** Value to compare when sorting -- render() output isn't assumed to be sortable (e.g. a Badge). */
+  sortValue?: (row: T) => string | number;
+  className?: string;
+  headerClassName?: string;
+}
+
+export interface DataTableProps<T> {
+  columns: DataTableColumn<T>[];
+  data: T[];
+  getRowKey: (row: T) => string;
+  /** Optional card-header title, shown above the search box. */
+  title?: ReactNode;
+  searchable?: boolean;
+  searchPlaceholder?: string;
+  /** What to match search text against; defaults to every column's rendered text via a JSON.stringify(row) fallback. */
+  searchValue?: (row: T) => string;
+  selectable?: boolean;
+  selectedKeys?: string[];
+  onSelectionChange?: (keys: string[]) => void;
+  /** Row count per page. Omit or 0 to disable pagination. */
+  pageSize?: number;
+  onRowClick?: (row: T) => void;
+  loading?: boolean;
+  emptyState?: ReactNode;
+  className?: string;
+}
+
+export function DataTable<T>({
+  columns,
+  data,
+  getRowKey,
+  title,
+  searchable,
+  searchPlaceholder = "Search...",
+  searchValue,
+  selectable,
+  selectedKeys,
+  onSelectionChange,
+  pageSize = 0,
+  onRowClick,
+  loading,
+  emptyState,
+  className,
+}: DataTableProps<T>) {
+  const [search, setSearch] = useState("");
+  const [sort, setSort] = useState<{ key: string; dir: "asc" | "desc" } | null>(null);
+  const [page, setPage] = useState(1);
+  // Uncontrolled selection fallback -- same pattern as Tabs's activeKey/internalKey split.
+  const [internalSelected, setInternalSelected] = useState<string[]>([]);
+  const selected = selectedKeys ?? internalSelected;
+
+  function setSelected(keys: string[]) {
+    if (selectedKeys === undefined) setInternalSelected(keys);
+    onSelectionChange?.(keys);
+  }
+
+  const filtered = useMemo(() => {
+    if (!searchable || !search.trim()) return data;
+    const q = search.trim().toLowerCase();
+    return data.filter((row) => {
+      const haystack = searchValue ? searchValue(row) : JSON.stringify(row);
+      return haystack.toLowerCase().includes(q);
+    });
+  }, [data, search, searchable, searchValue]);
+
+  const sorted = useMemo(() => {
+    if (!sort) return filtered;
+    const col = columns.find((c) => c.key === sort.key);
+    if (!col?.sortValue) return filtered;
+    const withValues = filtered.map((row) => ({ row, v: col.sortValue!(row) }));
+    withValues.sort((a, b) => (a.v < b.v ? -1 : a.v > b.v ? 1 : 0));
+    if (sort.dir === "desc") withValues.reverse();
+    return withValues.map((w) => w.row);
+  }, [filtered, sort, columns]);
+
+  const totalPages = pageSize > 0 ? Math.max(1, Math.ceil(sorted.length / pageSize)) : 1;
+  const pageSafe = Math.min(page, totalPages);
+  const pageRows = pageSize > 0 ? sorted.slice((pageSafe - 1) * pageSize, pageSafe * pageSize) : sorted;
+
+  function toggleSort(key: string) {
+    setSort((prev) => {
+      if (prev?.key !== key) return { key, dir: "asc" };
+      if (prev.dir === "asc") return { key, dir: "desc" };
+      return null;
+    });
+  }
+
+  function toggleRow(key: string) {
+    setSelected(selected.includes(key) ? selected.filter((k) => k !== key) : [...selected, key]);
+  }
+
+  const allOnPageSelected = pageRows.length > 0 && pageRows.every((row) => selected.includes(getRowKey(row)));
+
+  function toggleAllOnPage() {
+    const pageKeys = pageRows.map(getRowKey);
+    if (allOnPageSelected) setSelected(selected.filter((k) => !pageKeys.includes(k)));
+    else setSelected([...new Set([...selected, ...pageKeys])]);
+  }
+
+  return (
+    <div className={cx("overflow-hidden rounded-xl border border-gray-200 bg-white dark:border-gray-800 dark:bg-gray-900", className)}>
+      {(title || searchable) && (
+        <div className="flex flex-wrap items-center justify-between gap-3 border-b border-gray-200 px-5 py-4 dark:border-gray-800">
+          {title && <div className="text-base font-semibold text-gray-900 dark:text-gray-100">{title}</div>}
+          {searchable && (
+            <div className="relative">
+              <SearchIcon size={16} className="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 text-gray-400" />
+              <input
+                type="text"
+                value={search}
+                onChange={(e) => { setSearch(e.target.value); setPage(1); }}
+                placeholder={searchPlaceholder}
+                className="w-full max-w-[220px] rounded-lg border border-gray-300 bg-white py-1.5 pl-9 pr-3 text-sm text-gray-900 outline-none focus:border-primary focus:ring-1 focus:ring-primary dark:border-gray-700 dark:bg-gray-900 dark:text-gray-100"
+              />
+            </div>
+          )}
+        </div>
+      )}
+
+      {loading ? (
+        <div className="flex items-center justify-center gap-2 p-10 text-gray-400">
+          <Spinner size={20} />
+        </div>
+      ) : pageRows.length === 0 ? (
+        <div className="p-6">
+          {emptyState ?? <EmptyState title="No results" description={search ? "Try a different search." : "Nothing here yet."} />}
+        </div>
+      ) : (
+        <div className="overflow-x-auto">
+          <table className="w-full text-left text-sm">
+            <Thead>
+              <Tr>
+                {selectable && (
+                  <Th className="w-10">
+                    <Checkbox checked={allOnPageSelected} onChange={toggleAllOnPage} aria-label="Select all rows on this page" />
+                  </Th>
+                )}
+                {columns.map((col) => (
+                  <Th key={col.key} className={col.headerClassName}>
+                    {col.sortable && col.sortValue ? (
+                      <button
+                        type="button"
+                        onClick={() => toggleSort(col.key)}
+                        className="inline-flex items-center gap-1 hover:text-gray-900 dark:hover:text-gray-100"
+                      >
+                        {col.header}
+                        <ChevronDownIcon
+                          size={12}
+                          className={cx(
+                            "transition-transform",
+                            sort?.key === col.key ? (sort.dir === "asc" ? "rotate-180" : "") : "opacity-30",
+                          )}
+                        />
+                      </button>
+                    ) : (
+                      col.header
+                    )}
+                  </Th>
+                ))}
+              </Tr>
+            </Thead>
+            <Tbody>
+              {pageRows.map((row) => {
+                const key = getRowKey(row);
+                return (
+                  <Tr
+                    key={key}
+                    onClick={onRowClick ? () => onRowClick(row) : undefined}
+                    className={onRowClick ? "cursor-pointer" : undefined}
+                  >
+                    {selectable && (
+                      <Td onClick={(e) => e.stopPropagation()}>
+                        <Checkbox checked={selected.includes(key)} onChange={() => toggleRow(key)} aria-label="Select row" />
+                      </Td>
+                    )}
+                    {columns.map((col) => (
+                      <Td key={col.key} className={col.className}>
+                        {col.render(row)}
+                      </Td>
+                    ))}
+                  </Tr>
+                );
+              })}
+            </Tbody>
+          </table>
+        </div>
+      )}
+
+      {pageSize > 0 && !loading && sorted.length > 0 && (
+        <div className="flex flex-wrap items-center justify-between gap-3 border-t border-gray-200 px-5 py-3 text-xs text-gray-500 dark:border-gray-800 dark:text-gray-400">
+          <span>
+            Showing {(pageSafe - 1) * pageSize + 1}-{Math.min(pageSafe * pageSize, sorted.length)} of {sorted.length}
+          </span>
+          <Pagination page={pageSafe} totalPages={totalPages} onChange={setPage} />
+        </div>
+      )}
+    </div>
+  );
+}

package/src/data.ts

@@ -21,14 +21,40 @@ function authHeaders(): Record<string, string> {
   return token ? { Authorization: `Bearer ${token}` } : {};
 }
 
+// Fixed platform origin for the *Server variants below (same value as the
+// generation prompt's own ${base}, i.e. env.PORTAL_REDIRECT_URL) -- NOT
+// window.location.origin. Two confirmed platform-side gaps forced this
+// (agent reports 25d63fe8/ed34d032/5d149c3f): (1) window doesn't exist in a
+// Next.js Route Handler/Server Component, so the browser-only functions
+// below throw ReferenceError there; (2) even a same-origin fetch from
+// inside a Worker back to its OWN public hostname (e.g. via
+// req.nextUrl.origin, reasoning "that's this app's origin too") reliably
+// hangs ~20s and returns Cloudflare 522 -- a same-zone Worker can't
+// self-fetch the hostname it's currently serving. Hitting this fixed
+// platform origin directly sidesteps both: no window read, and it's never
+// the same zone/Worker as the app's own deployed domain.
+const PLATFORM_ORIGIN = "https://viibestack.ai";
+
 let appIdPromise: Promise<string | null> | null = null;
 
+// Caches only a successful resolution -- a failed one (network blip, timing
+// on very first page load) clears appIdPromise back to null so the NEXT
+// listRows/upsertRow/etc. call on this same page load retries instead of
+// being permanently stuck on one transient failure.
 function resolveAppId(): Promise<string | null> {
   if (!appIdPromise) {
     appIdPromise = fetch(`${window.location.origin}/api/apps/resolve?hostname=${window.location.hostname}`)
       .then((res) => (res.ok ? res.json() : null))
-      .then((data: { app_id?: string } | null) => data?.app_id ?? null)
-      .catch(() => null);
+      // Response.json() resolves to `unknown` under newer TS DOM lib
+      // versions (not `any`), so a typed callback param above rejects it --
+      // cast in the body instead, same as every other res.json() call site
+      // in this file.
+      .then((data) => (data as { app_id?: string } | null)?.app_id ?? null)
+      .catch(() => null)
+      .then((appId) => {
+        if (appId === null) appIdPromise = null;
+        return appId;
+      });
   }
   return appIdPromise;
 }
@@ -94,6 +120,25 @@ export async function upsertRow<T extends { id: string }>(table: string, row: T)
   }
 }
 
+// Single-row fetch by id -- for a detail page or anything keyed by a URL
+// param, this beats paging through listRows()/listRowsPage() to find one
+// record (impractical past a few hundred rows). Returns null on a 404 or
+// any network failure, same "fail soft, let the caller show empty state"
+// convention as every other helper in this file.
+export async function getRow<T extends { id: string }>(table: string, id: string): Promise<T | null> {
+  const appId = await resolveAppId();
+  if (!appId) return null;
+  try {
+    const res = await fetch(`${window.location.origin}/api/apps/${appId}/data-public/${table}/${encodeURIComponent(id)}`, {
+      headers: authHeaders(),
+    });
+    if (!res.ok) return null;
+    return (await res.json()) as T;
+  } catch {
+    return null;
+  }
+}
+
 export async function deleteRow(table: string, id: string): Promise<void> {
   const appId = await resolveAppId();
   if (!appId) return;
@@ -131,3 +176,109 @@ export async function captureClientError(message: string, stack?: string): Promi
     // best-effort
   }
 }
+
+// ── Server-safe variants ────────────────────────────────────────────────
+// Everything above resolves this app's own id via window.location and
+// fetches window.location.origin -- correct for browser code, but a Next.js
+// Route Handler or Server Component has no window, and (see PLATFORM_ORIGIN
+// above) fetching the incoming request's own origin from inside a Worker
+// hangs and 522s even when window IS polyfilled. Use these instead from any
+// server-side code (Route Handlers, Server Components, server actions); the
+// browser functions above remain correct for client components.
+//
+// No app-id caching here (each function takes it explicitly) -- a Worker
+// request handler shouldn't assume module-level state survives or is safe
+// to share across concurrent requests the way a browser tab's single JS
+// context can.
+
+// Resolve this app's own id from its public hostname (e.g.
+// new URL(request.url).hostname inside a Route Handler, or the incoming
+// Host header) -- the server-side equivalent of the browser resolveAppId()
+// above. No auth required, same as the client version.
+export async function resolveAppIdByHostname(hostname: string): Promise<string | null> {
+  try {
+    const res = await fetch(`${PLATFORM_ORIGIN}/api/apps/resolve?hostname=${encodeURIComponent(hostname)}`);
+    if (!res.ok) return null;
+    const data = (await res.json()) as { app_id?: string } | null;
+    return data?.app_id ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function serverAuthHeaders(authToken?: string): Record<string, string> {
+  return authToken ? { Authorization: `Bearer ${authToken}` } : {};
+}
+
+// authToken is optional and passed explicitly -- getStoredAuthToken() reads
+// browser localStorage, which doesn't exist server-side. For a real_accounts
+// app, read the caller's own session token from the incoming request
+// (cookie/header) and pass it through here.
+export async function listRowsPageServer<T extends { id: string }>(
+  appId: string, table: string, opts?: { limit?: number; cursor?: string; authToken?: string },
+): Promise<RowsPage<T>> {
+  try {
+    const params = new URLSearchParams();
+    if (opts?.limit) params.set("limit", String(opts.limit));
+    if (opts?.cursor) params.set("cursor", opts.cursor);
+    const qs = params.toString();
+    const res = await fetch(`${PLATFORM_ORIGIN}/api/apps/${appId}/data-public/${table}${qs ? `?${qs}` : ""}`, {
+      headers: serverAuthHeaders(opts?.authToken),
+    });
+    if (!res.ok) return { rows: [], nextCursor: null };
+    const data = (await res.json()) as { rows: T[]; next_cursor: string | null };
+    return { rows: data.rows ?? [], nextCursor: data.next_cursor ?? null };
+  } catch {
+    return { rows: [], nextCursor: null };
+  }
+}
+
+// Same MAX_AUTO_PAGES auto-pagination as listRows() above -- see its own
+// comment for when to use listRowsPageServer() instead for a table headed
+// into the tens of thousands of rows.
+export async function listRowsServer<T extends { id: string }>(appId: string, table: string, authToken?: string): Promise<T[]> {
+  const all: T[] = [];
+  let cursor: string | undefined;
+  for (let page = 0; page < MAX_AUTO_PAGES; page++) {
+    const { rows, nextCursor } = await listRowsPageServer<T>(appId, table, { limit: 1000, cursor, authToken });
+    all.push(...rows);
+    if (!nextCursor) break;
+    cursor = nextCursor;
+  }
+  return all;
+}
+
+export async function upsertRowServer<T extends { id: string }>(appId: string, table: string, row: T, authToken?: string): Promise<void> {
+  try {
+    await fetch(`${PLATFORM_ORIGIN}/api/apps/${appId}/data/${table}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...serverAuthHeaders(authToken) },
+      body: JSON.stringify({ rows: [row] }),
+    });
+  } catch {
+    // best-effort -- a write failure shouldn't crash the handler calling this
+  }
+}
+
+export async function getRowServer<T extends { id: string }>(appId: string, table: string, id: string, authToken?: string): Promise<T | null> {
+  try {
+    const res = await fetch(`${PLATFORM_ORIGIN}/api/apps/${appId}/data-public/${table}/${encodeURIComponent(id)}`, {
+      headers: serverAuthHeaders(authToken),
+    });
+    if (!res.ok) return null;
+    return (await res.json()) as T;
+  } catch {
+    return null;
+  }
+}
+
+export async function deleteRowServer(appId: string, table: string, id: string, authToken?: string): Promise<void> {
+  try {
+    await fetch(`${PLATFORM_ORIGIN}/api/apps/${appId}/data-public/${table}/${encodeURIComponent(id)}`, {
+      method: "DELETE",
+      headers: serverAuthHeaders(authToken),
+    });
+  } catch {
+    // best-effort
+  }
+}

package/src/icons.tsx

@@ -333,3 +333,73 @@ export function StarIcon(props: IconProps = {}) {
     </svg>
   );
 }
+
+export function TrendUpIcon(props: IconProps = {}) {
+  return (
+    <svg {...svgProps(props)}>
+      <polyline points="23 6 13.5 15.5 8.5 10.5 1 18" />
+      <polyline points="17 6 23 6 23 12" />
+    </svg>
+  );
+}
+
+export function TrendDownIcon(props: IconProps = {}) {
+  return (
+    <svg {...svgProps(props)}>
+      <polyline points="23 18 13.5 8.5 8.5 13.5 1 6" />
+      <polyline points="17 18 23 18 23 12" />
+    </svg>
+  );
+}
+
+export function ChevronRightIcon(props: IconProps = {}) {
+  return (
+    <svg {...svgProps(props)}>
+      <polyline points="9 6 15 12 9 18" />
+    </svg>
+  );
+}
+
+export function ChevronLeftIcon(props: IconProps = {}) {
+  return (
+    <svg {...svgProps(props)}>
+      <polyline points="15 6 9 12 15 18" />
+    </svg>
+  );
+}
+
+export function SendIcon(props: IconProps = {}) {
+  return (
+    <svg {...svgProps(props)}>
+      <line x1="22" y1="2" x2="11" y2="13" />
+      <polygon points="22 2 15 22 11 13 2 9 22 2" />
+    </svg>
+  );
+}
+
+export function EyeIcon(props: IconProps = {}) {
+  return (
+    <svg {...svgProps(props)}>
+      <path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z" />
+      <circle cx="12" cy="12" r="3" />
+    </svg>
+  );
+}
+
+export function CopyIcon(props: IconProps = {}) {
+  return (
+    <svg {...svgProps(props)}>
+      <rect x="9" y="9" width="13" height="13" rx="2" />
+      <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+    </svg>
+  );
+}
+
+export function BanIcon(props: IconProps = {}) {
+  return (
+    <svg {...svgProps(props)}>
+      <circle cx="12" cy="12" r="10" />
+      <line x1="4.93" y1="4.93" x2="19.07" y2="19.07" />
+    </svg>
+  );
+}

package/src/index.ts

@@ -6,3 +6,6 @@ export * from "./auth";
 export * from "./badge";
 export * from "./gamification";
 export * from "./reward";
+export * from "./dashboard";
+export * from "./data-table";
+export * from "./team";

package/src/nav.tsx

@@ -23,7 +23,56 @@
 //      here by never using flex-wrap for this layout at all.
 import { createPortal } from "react-dom";
 import { useEffect, useState, type ReactNode } from "react";
-import { MenuIcon, CloseIcon, ChevronDownIcon } from "./icons";
+import { MenuIcon, CloseIcon, ChevronDownIcon, SunIcon, MoonIcon } from "./icons";
+
+// Same data-theme/localStorage convention the platform's injected theme
+// scripts use (services/deploy/src/template-patches.ts) -- reading through
+// that shared contract, not a separate one, keeps this in sync with
+// whichever mechanism (the ?theme= query param bridge, the standalone
+// floating fallback button) touches the same page.
+function isDark(): boolean {
+  const attr = document.documentElement.getAttribute("data-theme");
+  if (attr === "dark") return true;
+  if (attr === "light") return false;
+  return typeof window.matchMedia === "function" && window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+
+function setTheme(next: "dark" | "light") {
+  document.documentElement.setAttribute("data-theme", next);
+  try {
+    localStorage.setItem("vs_theme", next);
+  } catch {
+    // localStorage unavailable (private mode, etc.) -- the attribute change alone still repaints this tab
+  }
+}
+
+// Deliberately marked with the SAME data-vs="viibestack-theme-toggle"
+// attribute the platform's standalone fallback script looks for (see that
+// script's own comment in template-patches.ts) -- an app using AppShell
+// gets a real toggle integrated into its own nav by default, and the
+// fallback's MutationObserver detects this one and removes itself instead
+// of adding a second, floating, duplicate button.
+function ThemeToggleItem() {
+  const [dark, setDark] = useState(false);
+
+  useEffect(() => setDark(isDark()), []);
+
+  return (
+    <button
+      type="button"
+      data-vs="viibestack-theme-toggle"
+      onClick={() => {
+        const next = dark ? "light" : "dark";
+        setTheme(next);
+        setDark(!dark);
+      }}
+      className={LINK_CLASS}
+    >
+      {dark ? <SunIcon /> : <MoonIcon />}
+      {dark ? "Light mode" : "Dark mode"}
+    </button>
+  );
+}
 
 function cx(...parts: (string | false | null | undefined)[]): string {
   return parts.filter(Boolean).join(" ");
@@ -65,10 +114,23 @@ export interface AppShellProps {
   renderLink?: (item: NavLinkItem, active: boolean) => ReactNode;
   /** Rendered at the bottom of the sidebar/drawer -- e.g. a user menu, sign-out button. */
   footer?: ReactNode;
+  /**
+   * Set true to render a dark/light toggle as a normal row in the nav.
+   * Off by default -- AppShell doesn't presume every app wants this
+   * specific row in this specific place; the platform's own dark/light
+   * requirement (every app must support both and let the end user switch)
+   * is satisfied independently by the floating fallback toggle every app
+   * gets at build time (see template-patches.ts's THEME_TOGGLE_SCRIPT)
+   * unless the app supplies its own. Pass true here for a nav-integrated
+   * toggle instead of that floating button -- it shares the exact same
+   * data-vs="viibestack-theme-toggle" marker, so the fallback detects it
+   * and backs off rather than adding a second, floating, duplicate one.
+   */
+  showThemeToggle?: boolean;
   children: ReactNode;
 }
 
-export function AppShell({ brand, nav, activeHref, renderLink, footer, children }: AppShellProps) {
+export function AppShell({ brand, nav, activeHref, renderLink, footer, showThemeToggle, children }: AppShellProps) {
   const [mobileOpen, setMobileOpen] = useState(false);
   const [mounted, setMounted] = useState(false);
 
@@ -136,6 +198,7 @@ export function AppShell({ brand, nav, activeHref, renderLink, footer, children
         <div className="px-4 py-4 text-lg font-semibold text-gray-900 dark:text-gray-100">{brand}</div>
         <nav className="flex flex-col gap-1 overflow-y-auto px-3 pb-3">
           {nav.map((item, i) => renderItem(item, i))}
+          {showThemeToggle && mounted && <ThemeToggleItem />}
         </nav>
         {footer && <div className="mt-auto border-t border-gray-200 p-3 dark:border-gray-800">{footer}</div>}
       </aside>
@@ -180,6 +243,7 @@ export function AppShell({ brand, nav, activeHref, renderLink, footer, children
               </div>
               <nav className="flex flex-col gap-1 px-3 pb-3">
                 {nav.map((item, i) => renderItem(item, i, () => setMobileOpen(false)))}
+                {showThemeToggle && <ThemeToggleItem />}
               </nav>
               {footer && <div className="mt-auto border-t border-gray-200 p-3 dark:border-gray-800">{footer}</div>}
             </div>

package/src/team.tsx

@@ -0,0 +1,91 @@
+"use client";
+
+// Team/people-grid building block -- TeamMemberCard, TeamGrid. A distinct,
+// later-added vocabulary (same rationale as dashboard.tsx) for "who's on
+// this" pages: about pages, staff directories, contributor/leaderboard-
+// adjacent listings. Original implementation -- conceptually informed by
+// the general "avatar + name + role + optional bio + optional links" shape
+// common to team-showcase page sections, not copied markup/CSS from any
+// one source (see packages/design-library's README for this platform's
+// design-provenance conventions). Deliberately no baked-in social-network
+// icon set -- `links` is a generic {label, href, icon?} array so this
+// doesn't force which platforms (or how many) a member's links cover.
+import type { ReactNode } from "react";
+import { Avatar } from "./components";
+
+function cx(...parts: (string | false | null | undefined)[]): string {
+  return parts.filter(Boolean).join(" ");
+}
+
+export interface TeamMemberLink {
+  label: string;
+  href: string;
+  icon?: ReactNode;
+}
+
+export interface TeamMember {
+  name: string;
+  role?: ReactNode;
+  avatarSrc?: string;
+  bio?: ReactNode;
+  links?: TeamMemberLink[];
+}
+
+export interface TeamMemberCardProps {
+  member: TeamMember;
+  className?: string;
+}
+
+export function TeamMemberCard({ member, className }: TeamMemberCardProps) {
+  return (
+    <div
+      className={cx(
+        "flex flex-col items-center gap-3 rounded-xl border border-gray-200 bg-white p-6 text-center dark:border-gray-800 dark:bg-gray-900",
+        className,
+      )}
+    >
+      <Avatar src={member.avatarSrc} name={member.name} size={72} />
+      <div>
+        <div className="text-base font-semibold text-gray-900 dark:text-gray-100">{member.name}</div>
+        {member.role && <div className="text-sm text-gray-500 dark:text-gray-400">{member.role}</div>}
+      </div>
+      {member.bio && <p className="text-sm text-gray-600 dark:text-gray-300">{member.bio}</p>}
+      {member.links && member.links.length > 0 && (
+        <div className="flex items-center gap-2">
+          {member.links.map((link, i) => (
+            <a
+              key={i}
+              href={link.href}
+              target="_blank"
+              rel="noopener noreferrer"
+              aria-label={link.label}
+              title={link.label}
+              className="flex h-8 w-8 items-center justify-center rounded-full bg-gray-100 text-gray-600 hover:bg-primary/10 hover:text-primary dark:bg-gray-800 dark:text-gray-300"
+            >
+              {link.icon ?? link.label[0]?.toUpperCase()}
+            </a>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export interface TeamGridProps {
+  members: TeamMember[];
+  className?: string;
+}
+
+// 1/2/3-column responsive grid -- the columns step follows this package's
+// existing breakpoint convention (md for tablet, lg for desktop) rather
+// than a 4th column, since a wider member card reads better than a
+// cramped one on very large screens.
+export function TeamGrid({ members, className }: TeamGridProps) {
+  return (
+    <div className={cx("grid grid-cols-1 gap-5 sm:grid-cols-2 lg:grid-cols-3", className)}>
+      {members.map((member, i) => (
+        <TeamMemberCard key={i} member={member} />
+      ))}
+    </div>
+  );
+}