ruler-components 0.1.0

package/components/docs/avatar-doc-page.tsx

@@ -0,0 +1,424 @@
+"use client";
+
+import { useState } from "react";
+import { Check, CircleUserRound, Copy, Mail, UserPlus } from "lucide-react";
+import { Avatar, AvatarGroup, type AvatarProps } from "@/components/ui/avatar";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Tooltip } from "@/components/ui/tooltip";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import {
+  DocsAccessibility,
+  DocsApiSection,
+  DocsApiTable,
+  DocsDemoPanel,
+  DocsPage,
+  DocsPageHeader,
+  DocsSection,
+  DocsSectionGrid,
+} from "@/components/docs/docs-page";
+import { cn } from "@/lib/cn";
+
+const API_ROWS = [
+  { prop: "src", type: "string", default: "—", description: "Image URL for the avatar" },
+  { prop: "alt", type: "string", default: "—", description: "Accessible label for the image" },
+  { prop: "name", type: "string", default: "—", description: "Used for initials fallback and alt text" },
+  { prop: "size", type: '"sm" | "md" | "lg" | "xl"', default: '"md"', description: "The size of the avatar" },
+  { prop: "variant", type: '"default" | "outline"', default: '"default"', description: "Ring style for stacked groups" },
+  { prop: "status", type: '"online" | "offline" | "busy" | null', default: "null", description: "Optional presence indicator" },
+  { prop: "className", type: "string", default: "—", description: "Additional CSS classes" },
+];
+
+const GROUP_API_ROWS = [
+  { prop: "max", type: "number", default: "5", description: "Maximum avatars shown before +N overflow" },
+  { prop: "size", type: '"sm" | "md" | "lg" | "xl"', default: '"md"', description: "Size applied to overflow badge" },
+  { prop: "children", type: "ReactNode", default: "—", description: "Avatar elements to display" },
+];
+
+const ACCESSIBILITY_ITEMS = [
+  "Always provide alt text or a name for image avatars.",
+  "Use initials fallback when no image is available.",
+  "Status indicators are decorative — convey status in text when important.",
+  "Avatar groups should include a text label describing the group.",
+  "Ensure sufficient contrast for initials on fallback backgrounds.",
+];
+
+const TEAM = [
+  { name: "Zuhaib Khan", src: "https://i.pravatar.cc/150?img=11", role: "Lead Designer" },
+  { name: "Aisha Malik", src: "https://i.pravatar.cc/150?img=5", role: "Product Manager" },
+  { name: "James Chen", src: "https://i.pravatar.cc/150?img=12", role: "Engineer" },
+  { name: "Sara Patel", src: "https://i.pravatar.cc/150?img=9", role: "Research" },
+  { name: "Leo Martin", src: "https://i.pravatar.cc/150?img=15", role: "Marketing" },
+  { name: "Nina Rossi", src: "https://i.pravatar.cc/150?img=20", role: "Support" },
+];
+
+type Size = NonNullable<AvatarProps["size"]>;
+type Variant = NonNullable<AvatarProps["variant"]>;
+type Status = AvatarProps["status"];
+
+const SIZES: Size[] = ["sm", "md", "lg", "xl"];
+const VARIANTS: Variant[] = ["default", "outline"];
+const STATUSES: { value: Status; label: string }[] = [
+  { value: null, label: "None" },
+  { value: "online", label: "Online" },
+  { value: "busy", label: "Busy" },
+  { value: "offline", label: "Offline" },
+];
+
+function codeFor(size: Size, variant: Variant, status: Status, showPhoto: boolean) {
+  const lines = [
+    showPhoto ? `src="https://i.pravatar.cc/150?img=5"` : null,
+    `name="Aisha Malik"`,
+    size !== "md" ? `size="${size}"` : null,
+    variant !== "default" ? `variant="${variant}"` : null,
+    status ? `status="${status}"` : null,
+  ].filter(Boolean);
+  return `<Avatar\n  ${lines.join("\n  ")}\n/>`;
+}
+
+export function AvatarDocPage() {
+  const [size, setSize] = useState<Size>("xl");
+  const [variant, setVariant] = useState<Variant>("default");
+  const [status, setStatus] = useState<Status>("online");
+  const [showPhoto, setShowPhoto] = useState(true);
+  const [copied, setCopied] = useState(false);
+
+  const snippet = codeFor(size, variant, status, showPhoto);
+
+  function copySnippet() {
+    navigator.clipboard.writeText(snippet).catch(() => {});
+    setCopied(true);
+    setTimeout(() => setCopied(false), 1200);
+  }
+
+  return (
+    <DocsPage>
+      <DocsPageHeader
+        icon={CircleUserRound}
+        title="Avatar"
+        description="Represents a user or entity with a photo, initials fallback, and optional presence status."
+      />
+
+      <DocsSection
+        first
+        title="Playground"
+        description="Every size, variant, and status — live, with the exact markup to match."
+      >
+        <div className="overflow-hidden rounded-2xl border border-zinc-200 shadow-[0_2px_8px_rgba(0,0,0,0.04)] dark:border-zinc-800 dark:shadow-[0_2px_8px_rgba(0,0,0,0.2)]">
+          <div className="relative flex min-h-[11rem] items-center justify-center overflow-hidden bg-zinc-50 dark:bg-zinc-900/40">
+            <div
+              aria-hidden
+              className="pointer-events-none absolute inset-0 opacity-[0.4] dark:opacity-[0.15]"
+              style={{
+                backgroundImage:
+                  "linear-gradient(to right, rgb(161 161 170 / 0.35) 1px, transparent 1px), linear-gradient(to bottom, rgb(161 161 170 / 0.35) 1px, transparent 1px)",
+                backgroundSize: "24px 24px",
+              }}
+            />
+            <div key={`${size}-${variant}-${status}-${showPhoto}`} className="relative animate-[pagination-pop_0.25s_ease-out]">
+              <Avatar
+                src={showPhoto ? "https://i.pravatar.cc/150?img=5" : undefined}
+                name="Aisha Malik"
+                size={size}
+                variant={variant}
+                status={status}
+              />
+            </div>
+          </div>
+
+          <div className="flex flex-col gap-5 border-t border-zinc-200 p-5 dark:border-zinc-800">
+            <div className="flex flex-wrap items-start justify-between gap-6">
+              <div>
+                <p className="mb-2 text-xs font-medium uppercase tracking-wide text-zinc-400 dark:text-zinc-500">
+                  Size
+                </p>
+                <div className="flex flex-wrap items-center gap-1 rounded-lg border border-zinc-200 bg-zinc-50 p-1 dark:border-zinc-800 dark:bg-zinc-900/60">
+                  {SIZES.map((s) => (
+                    <button
+                      key={s}
+                      type="button"
+                      onClick={() => setSize(s)}
+                      className={cn(
+                        "rounded-md px-3 py-1.5 text-xs font-medium uppercase tracking-wide transition-colors",
+                        size === s
+                          ? "bg-white text-zinc-900 shadow-sm dark:bg-zinc-800 dark:text-white"
+                          : "text-zinc-500 hover:text-zinc-800 dark:text-zinc-400 dark:hover:text-zinc-200"
+                      )}
+                    >
+                      {s}
+                    </button>
+                  ))}
+                </div>
+              </div>
+
+              <div>
+                <p className="mb-2 text-xs font-medium uppercase tracking-wide text-zinc-400 dark:text-zinc-500">
+                  Status
+                </p>
+                <div className="flex flex-wrap items-center gap-1 rounded-lg border border-zinc-200 bg-zinc-50 p-1 dark:border-zinc-800 dark:bg-zinc-900/60">
+                  {STATUSES.map((s) => (
+                    <button
+                      key={s.label}
+                      type="button"
+                      onClick={() => setStatus(s.value)}
+                      className={cn(
+                        "rounded-md px-3 py-1.5 text-xs font-medium transition-colors",
+                        status === s.value
+                          ? "bg-white text-zinc-900 shadow-sm dark:bg-zinc-800 dark:text-white"
+                          : "text-zinc-500 hover:text-zinc-800 dark:text-zinc-400 dark:hover:text-zinc-200"
+                      )}
+                    >
+                      {s.label}
+                    </button>
+                  ))}
+                </div>
+              </div>
+
+              <div>
+                <p className="mb-2 text-xs font-medium uppercase tracking-wide text-zinc-400 dark:text-zinc-500">
+                  Variant
+                </p>
+                <div className="flex flex-wrap items-center gap-1 rounded-lg border border-zinc-200 bg-zinc-50 p-1 dark:border-zinc-800 dark:bg-zinc-900/60">
+                  {VARIANTS.map((v) => (
+                    <button
+                      key={v}
+                      type="button"
+                      onClick={() => setVariant(v)}
+                      className={cn(
+                        "rounded-md px-3 py-1.5 text-xs font-medium capitalize transition-colors",
+                        variant === v
+                          ? "bg-white text-zinc-900 shadow-sm dark:bg-zinc-800 dark:text-white"
+                          : "text-zinc-500 hover:text-zinc-800 dark:text-zinc-400 dark:hover:text-zinc-200"
+                      )}
+                    >
+                      {v}
+                    </button>
+                  ))}
+                </div>
+              </div>
+
+              <div>
+                <p className="mb-2 text-xs font-medium uppercase tracking-wide text-zinc-400 dark:text-zinc-500">
+                  Photo
+                </p>
+                <button
+                  type="button"
+                  onClick={() => setShowPhoto((v) => !v)}
+                  className={cn(
+                    "flex h-[2.125rem] items-center gap-2 rounded-lg border px-3 text-xs font-medium transition-colors",
+                    showPhoto
+                      ? "border-zinc-900 bg-zinc-900 text-white dark:border-white dark:bg-white dark:text-zinc-900"
+                      : "border-zinc-200 text-zinc-500 hover:border-zinc-300 dark:border-zinc-700 dark:text-zinc-400"
+                  )}
+                >
+                  {showPhoto ? "Photo" : "Initials"}
+                </button>
+              </div>
+            </div>
+
+            <div className="flex items-center justify-between gap-3 rounded-xl bg-zinc-900 px-4 py-3 dark:bg-black">
+              <pre className="overflow-x-auto font-mono text-[13px] leading-relaxed text-zinc-100">
+                <code>{snippet}</code>
+              </pre>
+              <Tooltip content={copied ? "Copied!" : "Copy code"}>
+                <button
+                  type="button"
+                  onClick={copySnippet}
+                  className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg text-zinc-400 transition-colors hover:bg-white/10 hover:text-white"
+                >
+                  {copied ? <Check className="h-4 w-4 text-emerald-400" /> : <Copy className="h-4 w-4" />}
+                </button>
+              </Tooltip>
+            </div>
+          </div>
+        </div>
+      </DocsSection>
+
+      <DocsSection
+        title="Team Directory"
+        description="Combine avatars, metadata, and actions in a single scannable surface."
+      >
+        <Card className="max-w-2xl">
+          <CardHeader className="border-b border-zinc-100 dark:border-zinc-800">
+            <div className="flex flex-wrap items-start justify-between gap-4">
+              <div>
+                <CardTitle>Design team</CardTitle>
+                <CardDescription>6 members · 4 active now</CardDescription>
+              </div>
+              <Badge variant="success">Collaborating</Badge>
+            </div>
+          </CardHeader>
+          <CardContent className="flex flex-col gap-6 pt-6 sm:flex-row sm:items-center sm:justify-between">
+            <div>
+              <AvatarGroup max={5} size="md">
+                {TEAM.map((member) => (
+                  <Tooltip key={member.name} content={`${member.name} · ${member.role}`}>
+                    <Avatar src={member.src} name={member.name} variant="outline" />
+                  </Tooltip>
+                ))}
+              </AvatarGroup>
+              <p className="mt-3 text-sm text-zinc-600 dark:text-zinc-300">
+                Zuhaib, Aisha, James, Sara, and 2 more
+              </p>
+            </div>
+            <Button size="sm">
+              <UserPlus className="h-4 w-4" />
+              Invite
+            </Button>
+          </CardContent>
+        </Card>
+      </DocsSection>
+
+      <DocsSection
+        title="Photos & Initials"
+        description="Gradient initials automatically match each name when no photo is available."
+      >
+        <DocsDemoPanel>
+          {[
+            { name: "Zuhaib Khan", src: "https://i.pravatar.cc/150?img=11", status: "online" as const },
+            { name: "Aisha Malik", status: "online" as const },
+            { name: "James Chen", status: null },
+            { name: "Sara Patel", status: "busy" as const },
+            { name: "Leo Martin", status: "offline" as const },
+          ].map((person) => (
+            <Tooltip key={person.name} content={person.name}>
+              <div className="flex flex-col items-center gap-2.5">
+                <Avatar src={person.src} name={person.name} size="lg" status={person.status} />
+                <span className="text-xs font-medium text-zinc-500 dark:text-zinc-400">
+                  {person.name.split(" ")[0]}
+                </span>
+              </div>
+            </Tooltip>
+          ))}
+        </DocsDemoPanel>
+      </DocsSection>
+
+      <DocsSection>
+        <DocsSectionGrid className="lg:grid-cols-2">
+          <Card>
+            <CardHeader>
+              <CardTitle className="text-base">Presence</CardTitle>
+              <CardDescription>Status dots with a soft pulse for active users.</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <div className="grid grid-cols-3 gap-4">
+                {[
+                  { label: "Online", status: "online" as const, src: "https://i.pravatar.cc/150?img=8", name: "Online" },
+                  { label: "Busy", status: "busy" as const, name: "Busy User" },
+                  { label: "Offline", status: "offline" as const, name: "Offline User" },
+                ].map((item) => (
+                  <div
+                    key={item.label}
+                    className="flex flex-col items-center gap-3 rounded-xl border border-zinc-100 bg-zinc-50/80 p-4 dark:border-zinc-800 dark:bg-zinc-900/40"
+                  >
+                    <Avatar src={item.src} name={item.name} size="lg" status={item.status} />
+                    <span className="text-xs font-medium text-zinc-600 dark:text-zinc-300">{item.label}</span>
+                  </div>
+                ))}
+              </div>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle className="text-base">Stacked Group</CardTitle>
+              <CardDescription>Hover avatars to preview — overflow shows +N count.</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <AvatarGroup max={4} size="lg">
+                {TEAM.map((member) => (
+                  <Tooltip key={member.name} content={`${member.name} · ${member.role}`}>
+                    <Avatar src={member.src} name={member.name} variant="outline" />
+                  </Tooltip>
+                ))}
+              </AvatarGroup>
+              <div className="mt-5 flex items-center justify-between rounded-xl border border-zinc-100 bg-zinc-50/80 px-4 py-3 dark:border-zinc-800 dark:bg-zinc-900/40">
+                <p className="text-sm font-medium text-zinc-800 dark:text-zinc-100">6 teammates</p>
+                <Badge variant="outline">+2 hidden</Badge>
+              </div>
+            </CardContent>
+          </Card>
+        </DocsSectionGrid>
+      </DocsSection>
+
+      <DocsSection
+        title="Profile Card"
+        description="Layer avatars over a header band for profile-style layouts."
+      >
+        <Card className="max-w-md overflow-hidden">
+          <div className="h-24 bg-gradient-to-br from-zinc-100 via-zinc-50 to-zinc-200 dark:from-zinc-800 dark:via-zinc-900 dark:to-zinc-950" />
+          <CardContent className="relative px-6 pb-6 pt-0">
+            <Avatar
+              src="https://i.pravatar.cc/150?img=11"
+              name="Zuhaib Khan"
+              size="xl"
+              status="online"
+              className="absolute -top-12 ring-4 ring-white dark:ring-zinc-900"
+            />
+            <div className="pt-14">
+              <div className="flex flex-wrap items-center gap-2">
+                <h3 className="text-lg font-semibold tracking-tight text-zinc-900 dark:text-white">
+                  Zuhaib Khan
+                </h3>
+                <Badge variant="success">Pro</Badge>
+              </div>
+              <p className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">Product Designer · San Francisco</p>
+              <div className="mt-4 flex flex-wrap gap-2">
+                <Button size="sm">View profile</Button>
+                <Button variant="ghost" size="sm">
+                  <Mail className="h-4 w-4" />
+                  Message
+                </Button>
+              </div>
+            </div>
+          </CardContent>
+        </Card>
+      </DocsSection>
+
+      <DocsSection
+        title="Member List"
+        description="Compact rows with hover states for settings and team management."
+      >
+        <Card className="max-w-md">
+          <CardHeader className="border-b border-zinc-100 pb-4 dark:border-zinc-800">
+            <CardTitle className="text-base">Workspace members</CardTitle>
+            <CardDescription>Manage roles and access levels.</CardDescription>
+          </CardHeader>
+          <CardContent className="p-0">
+            {TEAM.slice(0, 4).map((member) => (
+              <div
+                key={member.name}
+                className="flex items-center gap-3 border-b border-zinc-100 px-6 py-3.5 transition-colors last:border-0 hover:bg-zinc-50 dark:border-zinc-800 dark:hover:bg-zinc-900/50"
+              >
+                <Avatar src={member.src} name={member.name} size="md" status="online" />
+                <div className="min-w-0 flex-1">
+                  <p className="truncate text-sm font-medium text-zinc-900 dark:text-white">
+                    {member.name}
+                  </p>
+                  <p className="text-xs text-zinc-500 dark:text-zinc-400">{member.role}</p>
+                </div>
+                <Badge variant="outline">Editor</Badge>
+              </div>
+            ))}
+          </CardContent>
+          <CardFooter className="border-t border-zinc-100 dark:border-zinc-800">
+            <Button variant="ghost" size="sm" className="w-full">View all members</Button>
+          </CardFooter>
+        </Card>
+      </DocsSection>
+
+      <DocsApiSection>
+        <DocsApiTable title="API Reference — Avatar" rows={API_ROWS} />
+        <DocsApiTable title="API Reference — AvatarGroup" rows={GROUP_API_ROWS} />
+        <DocsAccessibility items={ACCESSIBILITY_ITEMS} />
+      </DocsApiSection>
+    </DocsPage>
+  );
+}