@peerbots/core 0.2.6 → 1.0.0

package/src/ui/layout/Card.stories.tsx

@@ -0,0 +1,151 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Card } from "./Card";
+import { Heading, Text } from "../foundations/Typography";
+import { Button } from "../forms/Button";
+import { Icon } from "../foundations/Icon";
+import React from "react";
+
+const meta: Meta<typeof Card> = {
+  title: "Layout/Card",
+  component: Card,
+  parameters: {
+    layout: "centered",
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Card>;
+
+export const Default: Story = {
+  args: {
+    variant: "default",
+    padding: "md",
+    hoverable: true,
+    children: (
+      <div className="pb:space-y-3 pb:w-80">
+        <Heading level={3}>Card Title</Heading>
+        <Text variant="muted">This is a standard card with elevation and rounded borders.</Text>
+        <Button variant="primary" size="sm">Action</Button>
+      </div>
+    ),
+  },
+};
+
+export const GlassInContext: Story = {
+  render: () => (
+    <div className="pb:flex pb:flex-col pb:gap-8 pb:max-w-4xl pb:p-6">
+      {/* 3D Canvas Viewport HUD Context */}
+      <div>
+        <h4 className="pb:text-xs pb:font-bold pb:text-gray-700 pb:uppercase pb:tracking-wider pb:mb-2">
+          Recommended Use: Floating Viewport HUD / Canvas Overlays
+        </h4>
+        <div className="pb:relative pb:w-full pb:h-80 pb:rounded-3xl pb:overflow-hidden pb:bg-gradient-to-tr pb:from-slate-900 pb:via-slate-800 pb:to-teal-950 pb:border pb:border-slate-700 pb:p-6 pb:flex pb:items-center pb:justify-center">
+          {/* Simulated 3D Model Center Graphic */}
+          <div className="pb:flex pb:flex-col pb:items-center pb:justify-center pb:text-center pb:opacity-80">
+            <div className="pb:w-28 pb:h-28 pb:rounded-2xl pb:bg-peerbots-teal/20 pb:border-2 pb:border-peerbots-teal/40 pb:flex pb:items-center pb:justify-center pb:shadow-lg pb:shadow-peerbots-teal/10 pb:animate-pulse">
+              <Icon name="face" className="pb:w-16 pb:h-16 pb:text-peerbots-teal" />
+            </div>
+            <span className="pb:text-xs pb:font-mono pb:text-teal-200 pb:mt-3">
+              WebGL 3D Robot Face Stage
+            </span>
+          </div>
+
+          {/* Floating HUD Camera Toolbar (Glass) */}
+          <div className="pb:absolute pb:left-6 pb:top-1/2 pb:-translate-y-1/2">
+            <Card variant="glass" padding="none" className="pb:p-1.5 pb:flex pb:flex-col pb:gap-2 pb:shadow-2xl">
+              <button aria-label="Zoom in" className="pb:w-9 pb:h-9 pb:flex pb:items-center pb:justify-center pb:rounded-xl pb:hover:bg-black/5 pb:text-gray-900 pb:font-bold pb:text-lg">
+                +
+              </button>
+              <div className="pb:w-full pb:h-px pb:bg-black/10" />
+              <button aria-label="Zoom out" className="pb:w-9 pb:h-9 pb:flex pb:items-center pb:justify-center pb:rounded-xl pb:hover:bg-black/5 pb:text-gray-900 pb:font-bold pb:text-lg">
+                -
+              </button>
+              <div className="pb:w-full pb:h-px pb:bg-black/10" />
+              <button aria-label="Reset camera" className="pb:w-9 pb:h-9 pb:flex pb:items-center pb:justify-center pb:rounded-xl pb:hover:bg-black/5 pb:text-gray-900">
+                <Icon name="arrowPath" className="pb:w-4 pb:h-4" />
+              </button>
+            </Card>
+          </div>
+
+          {/* Floating Parameter Overlay (Glass) */}
+          <div className="pb:absolute pb:right-6 pb:bottom-6 pb:max-w-xs">
+            <Card variant="glass" padding="sm" className="pb:shadow-2xl pb:space-y-2">
+              <div className="pb:flex pb:items-center pb:justify-between">
+                <span className="pb:text-xs pb:font-bold pb:text-gray-900">Head Rotation</span>
+                <span className="pb:text-[10px] pb:font-mono pb:text-teal-950 pb:bg-peerbots-teal/30 pb:px-1.5 pb:py-0.5 pb:rounded pb:font-bold">
+                  Yaw: 14°
+                </span>
+              </div>
+              <Text variant="small" className="pb:text-[11px] pb:text-gray-700 pb:block">
+                Glass surfaces maintain ambient visual depth without occluding the rendered model.
+              </Text>
+            </Card>
+          </div>
+        </div>
+      </div>
+
+      {/* When NOT to use: Comparison */}
+      <div>
+        <h4 className="pb:text-xs pb:font-bold pb:text-gray-700 pb:uppercase pb:tracking-wider pb:mb-2">
+          Standard Content vs Glass Comparison
+        </h4>
+        <div className="pb:grid pb:grid-cols-2 pb:gap-6 pb:p-6 pb:bg-gray-100 pb:rounded-2xl">
+          <Card variant="elevated" padding="md">
+            <span className="pb:text-[10px] pb:font-bold pb:uppercase pb:tracking-wider pb:text-gray-700">
+              Standard Opaque Surface (Recommended for forms & text)
+            </span>
+            <Heading level={4} className="pb:mt-1">Account & Settings</Heading>
+            <Text variant="muted" className="pb:text-xs pb:mt-1">
+              Solid white opaque cards ensure maximum readability, high contrast, and crisp text rendering on light backgrounds.
+            </Text>
+          </Card>
+          <Card variant="glass" padding="md">
+            <span className="pb:text-[10px] pb:font-bold pb:uppercase pb:tracking-wider pb:text-peerbots-darkteal">
+              Glass Surface (For visual layering & HUDs)
+            </span>
+            <Heading level={4} className="pb:mt-1">Floating Modal Panel</Heading>
+            <Text variant="muted" className="pb:text-xs pb:mt-1">
+              Translucent backdrop with subtle border blur creates a tactile glass feel over rich colored backgrounds.
+            </Text>
+          </Card>
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="pb:grid pb:grid-cols-2 pb:gap-6 pb:max-w-3xl pb:p-6 pb:bg-gray-100 pb:rounded-2xl">
+      <Card variant="default">
+        <Heading level={4}>Default</Heading>
+        <Text variant="muted">Default subtle shadow</Text>
+      </Card>
+      <Card variant="elevated">
+        <Heading level={4}>Elevated</Heading>
+        <Text variant="muted">Higher elevation shadow</Text>
+      </Card>
+      <Card variant="glass">
+        <Heading level={4}>Glass</Heading>
+        <Text variant="muted">Backdrop blur surface</Text>
+      </Card>
+      <Card variant="flat">
+        <Heading level={4}>Flat</Heading>
+        <Text variant="muted">Subtle background fill</Text>
+      </Card>
+      <Card variant="outline">
+        <Heading level={4}>Outline</Heading>
+        <Text variant="muted">Clean 2px border</Text>
+      </Card>
+      <Card variant="teal-tint">
+        <Heading level={4} variant="marketing-teal">Teal Tint</Heading>
+        <Text variant="muted">Brand teal tinted background</Text>
+      </Card>
+      <Card variant="pink-tint">
+        <Heading level={4} variant="marketing-pink">Pink Tint</Heading>
+        <Text variant="muted">Brand pink tinted background</Text>
+      </Card>
+    </div>
+  ),
+};

package/src/ui/layout/Card.tsx

@@ -0,0 +1,124 @@
+import React from "react";
+import { cn } from "../utils";
+import { ComponentSize, ComponentRadius, SurfaceVariant } from "../types";
+
+export interface CardProps extends React.HTMLAttributes<HTMLElement> {
+  children: React.ReactNode;
+  /**
+   * Surface treatment / fill style.
+   * @default "surface"
+   */
+  variant?: SurfaceVariant | "default" | "elevated";
+  /**
+   * Background color tinting.
+   * @default "default"
+   */
+  color?: "default" | "teal" | "pink";
+  /**
+   * Card padding scale.
+   * @default "md"
+   */
+  padding?: "none" | ComponentSize;
+  /**
+   * Border radius scale.
+   * @default "2xl"
+   */
+  radius?: ComponentRadius;
+  /** Whether the card shows interactive hover elevation */
+  hoverable?: boolean;
+  id?: string;
+  as?: React.ElementType;
+  href?: string;
+  target?: string;
+  rel?: string;
+}
+
+const variantStyles: Record<string, string> = {
+  surface: "pb:bg-white pb:border pb:border-gray-200 pb:shadow-md",
+  elevated: "pb:bg-white pb:border pb:border-gray-200 pb:shadow-md",
+  default: "pb:bg-white pb:border pb:border-gray-200 pb:shadow-xs",
+  glass:
+    "pb:bg-white/90 pb:backdrop-blur-xl pb:border pb:border-white/40 pb:shadow-xl",
+  flat: "pb:bg-gray-50/80 pb:border pb:border-gray-200",
+  outline: "pb:bg-transparent pb:border-2 pb:border-gray-300",
+};
+
+const tintStyles: Record<string, string> = {
+  default: "",
+  teal: "pb:bg-peerbots-teal/5 pb:border pb:border-peerbots-darkteal/30",
+  pink: "pb:bg-peerbots-pink/5 pb:border pb:border-rose-300",
+};
+
+const radiusClasses: Record<ComponentRadius, string> = {
+  none: "pb:rounded-none",
+  sm: "pb:rounded-md",
+  md: "pb:rounded-xl",
+  lg: "pb:rounded-2xl",
+  "2xl": "pb:rounded-2xl",
+  pill: "pb:rounded-full",
+};
+
+const paddingClasses: Record<string, string> = {
+  none: "",
+  xs: "pb:p-2.5",
+  sm: "pb:p-4",
+  md: "pb:p-6 sm:pb:p-8",
+  lg: "pb:p-8 sm:pb:p-10 md:pb:p-12",
+  xl: "pb:p-10 sm:pb:p-12 md:pb:p-16",
+};
+
+export const Card = React.forwardRef<HTMLElement, CardProps>(
+  (
+    {
+      children,
+      className,
+      variant = "surface",
+      color = "default",
+      padding = "md",
+      radius = "2xl",
+      hoverable = true,
+      id,
+      as: Component = "div",
+      href,
+      target,
+      rel,
+      ...rest
+    },
+    ref,
+  ) => {
+    const baseStyles = "pb:overflow-hidden pb:transition-all pb:duration-300";
+
+    const hoverStyles = hoverable
+      ? "pb:hover:shadow-lg pb:hover:-translate-y-0.5 pb:hover:border-peerbots-teal/30 pb:focus-within:ring-2 pb:focus-within:ring-peerbots-teal"
+      : "";
+
+    const isLink = Boolean(href) || Component === "a";
+    const TargetTag = href ? "a" : Component;
+
+    return (
+      <TargetTag
+        id={id}
+        href={href}
+        target={target}
+        rel={rel}
+        ref={ref as any}
+        className={cn(
+          baseStyles,
+          radiusClasses[radius] || radiusClasses["2xl"],
+          color === "default"
+            ? variantStyles[variant] || variantStyles.surface
+            : tintStyles[color],
+          hoverStyles,
+          paddingClasses[padding] || paddingClasses.md,
+          isLink && "pb:cursor-pointer pb:block",
+          className,
+        )}
+        {...(rest as any)}
+      >
+        {children}
+      </TargetTag>
+    );
+  },
+);
+
+Card.displayName = "Card";

package/src/ui/layout/Collapsible.stories.tsx

@@ -0,0 +1,54 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Collapsible } from "./Collapsible";
+import { Heading } from "../foundations/Typography";
+import { Input } from "../forms/Input";
+import { Button } from "../forms/Button";
+import React from "react";
+
+const meta: Meta<typeof Collapsible> = {
+  title: "Layout/Collapsible",
+  component: Collapsible,
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Collapsible>;
+
+export const Default: Story = {
+  args: {
+    title: "Click to expand",
+    children: (
+      <div className="pb:p-4 pb:bg-gray-50 pb:rounded-md">
+        This is the collapsible content. It can contain any elements.
+      </div>
+    ),
+  },
+};
+
+export const Variations: Story = {
+  render: () => (
+    <div className="pb:flex pb:flex-col pb:gap-8 pb:p-4 pb:max-w-xl">
+      <div className="pb:space-y-4">
+        <Heading level={4} className="pb:text-sm pb:font-medium pb:text-black pb:uppercase">
+          States & Styling
+        </Heading>
+        <div className="pb:space-y-4">
+          <Collapsible title="Initially Open" defaultOpen={true}>
+            <div className="pb:p-4 pb:bg-gray-50 pb:rounded-md pb:space-y-2">
+              <p>This content is visible by default.</p>
+              <Input placeholder="Settings value" />
+            </div>
+          </Collapsible>
+          <Collapsible
+            title={<span className="pb:font-bold pb:text-peerbots-darkteal">Styled Title Section</span>}
+          >
+            <div className="pb:p-4 pb:space-y-3">
+              <p>Custom styled title disclosure.</p>
+              <Button variant="primary" size="sm">Action</Button>
+            </div>
+          </Collapsible>
+        </div>
+      </div>
+    </div>
+  ),
+};

package/src/ui/layout/Collapsible.tsx

@@ -0,0 +1,54 @@
+import React, { useState } from "react";
+import { Accordion } from "./Accordion";
+import { ButtonProps } from "../forms/Button";
+
+export interface CollapsibleProps {
+  title: React.ReactNode;
+  children: React.ReactNode;
+  /** The variant of the trigger or panel */
+  variant?: ButtonProps["variant"] | "default" | "bordered" | "flat";
+  /** The size of the trigger button */
+  size?: ButtonProps["size"];
+  defaultOpen?: boolean;
+  isOpen?: boolean;
+  onToggle?: (open: boolean) => void;
+  className?: string;
+}
+
+export function Collapsible({
+  title,
+  children,
+  variant = "default",
+  defaultOpen = false,
+  isOpen: controlledIsOpen,
+  onToggle,
+  className,
+}: CollapsibleProps) {
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const isOpen = controlledIsOpen !== undefined ? controlledIsOpen : internalOpen;
+
+  const handleToggle = (nextOpen: boolean) => {
+    if (controlledIsOpen === undefined) {
+      setInternalOpen(nextOpen);
+    }
+    if (onToggle) {
+      onToggle(nextOpen);
+    }
+  };
+
+  const accordionVariant =
+    variant === "bordered" || variant === "flat" ? variant : "default";
+
+  return (
+    <Accordion
+      variant={accordionVariant}
+      title={title}
+      isOpen={isOpen}
+      onToggle={handleToggle}
+      defaultOpen={defaultOpen}
+      className={className}
+    >
+      {children}
+    </Accordion>
+  );
+}

package/src/ui/{Separator.stories.tsx → layout/Separator.stories.tsx}

@@ -1,9 +1,9 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { Separator } from "./Separator";
-import { Heading, Text } from "./Typography";
+import { Heading, Text } from "../foundations/Typography";
 
 const meta: Meta<typeof Separator> = {
-  title: "UI/Separator",
+  title: "Layout/Separator",
   component: Separator,
   tags: ["autodocs"],
   argTypes: {

package/src/ui/{Separator.tsx → layout/Separator.tsx}

@@ -1,6 +1,6 @@
 import * as React from "react";
 import { Separator as BaseSeparator } from "@base-ui/react/separator";
-import { cn } from "./utils";
+import { cn } from "../utils";
 
 export interface SeparatorProps extends React.ComponentPropsWithoutRef<
   typeof BaseSeparator

package/src/ui/{SettingsPanel.stories.tsx → layout/SettingsPanel.stories.tsx}

@@ -1,12 +1,12 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { SettingsPanel } from "./SettingsPanel";
-import { Button } from "./Button";
-import { Checkbox } from "./Checkbox";
-import { Heading, Text } from "./Typography";
-import { Label } from "./Label";
+import { Button } from "../forms/Button";
+import { Checkbox } from "../forms/Checkbox";
+import { Heading, Text } from "../foundations/Typography";
+import { Label } from "../forms/Label";
 
 const meta: Meta<typeof SettingsPanel> = {
-  title: "UI/SettingsPanel",
+  title: "Layout/SettingsPanel",
   component: SettingsPanel,
   tags: ["autodocs"],
   argTypes: {},

package/src/ui/{SettingsPanel.tsx → layout/SettingsPanel.tsx}

@@ -1,6 +1,7 @@
 import { ReactNode } from "react";
-import { Heading } from "./Typography";
-import { cn } from "./utils";
+import { Heading } from "../foundations/Typography";
+import { cn } from "../utils";
+import { Card } from "./Card";
 import { Collapsible } from "./Collapsible";
 
 export interface SettingsPanelProps {
@@ -22,7 +23,7 @@ export interface SettingsPanelProps {
 
 /**
  * A standardized panel for settings sections.
- * Provides a consistent look with white background, shadow, and rounded corners.
+ * Built on top of Card and Collapsible for design system consistency.
  */
 export function SettingsPanel({
   title,
@@ -34,48 +35,51 @@ export function SettingsPanel({
   headingLevel = 3,
 }: SettingsPanelProps) {
   const content = (
-    <div className={cn("pb:flex pb:flex-col", contentClassName)}>{children}</div>
+    <div className={cn("pb:flex pb:flex-col pb:gap-3", contentClassName)}>
+      {children}
+    </div>
   );
 
-  return (
-    <div
-      className={cn(
-        "pb:m-2 pb:p-4 pb:bg-white pb:shadow-xl pb:rounded-lg pb:flex pb:flex-1 pb:flex-col",
-        className,
-      )}
-    >
-      {collapsible ? (
+  if (collapsible) {
+    return (
+      <div className={cn("pb:w-full pb:mb-3", className)}>
         <Collapsible
           title={
             typeof title === "string" ? (
-              <Heading level={headingLevel} className="pb:text-gray-600">
+              <Heading level={headingLevel} className="pb:text-gray-800 pb:font-bold">
                 {title}
               </Heading>
             ) : (
               title
             )
           }
-          variant="ghost"
           defaultOpen={defaultOpen}
         >
           {content}
         </Collapsible>
-      ) : (
-        <>
-          {title && (
-            <div className="pb:flex pb:items-center pb:justify-between pb:mb-2 empty:hidden">
-              {typeof title === "string" ? (
-                <Heading level={headingLevel} className="pb:text-gray-600">
-                  {title}
-                </Heading>
-              ) : (
-                title
-              )}
-            </div>
+      </div>
+    );
+  }
+
+  return (
+    <Card
+      variant="elevated"
+      padding="sm"
+      hoverable={false}
+      className={cn("pb:w-full pb:mb-3 pb:flex pb:flex-col", className)}
+    >
+      {title && (
+        <div className="pb:flex pb:items-center pb:justify-between pb:mb-3 pb:pb-2 pb:border-b pb:border-gray-100 empty:hidden">
+          {typeof title === "string" ? (
+            <Heading level={headingLevel} className="pb:text-gray-800 pb:font-bold">
+              {title}
+            </Heading>
+          ) : (
+            title
           )}
-          {content}
-        </>
+        </div>
       )}
-    </div>
+      {content}
+    </Card>
   );
 }

package/src/ui/layout/index.ts

@@ -0,0 +1,5 @@
+export * from "./Card";
+export * from "./Accordion";
+export * from "./Collapsible";
+export * from "./Separator";
+export * from "./SettingsPanel";

package/src/ui/media/Avatar.stories.tsx

@@ -0,0 +1,89 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Avatar } from "./Avatar";
+import { Heading } from "../foundations/Typography";
+
+const meta: Meta<typeof Avatar> = {
+  title: "Media & Files/Avatar",
+  component: Avatar,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  argTypes: {
+    size: {
+      control: "select",
+      options: ["xs", "sm", "md", "lg", "xl"],
+    },
+    shape: {
+      control: "select",
+      options: ["circle", "rounded"],
+    },
+    name: { control: "text" },
+    src: { control: "text" },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Avatar>;
+
+export const Default: Story = {
+  args: {
+    name: "Ada Lovelace",
+    size: "md",
+    shape: "circle",
+  },
+};
+
+export const Variations: Story = {
+  render: () => (
+    <div className="pb:flex pb:flex-col pb:gap-6 pb:p-4">
+      <div className="pb:space-y-3">
+        <Heading level={4} className="pb:text-sm pb:font-medium pb:text-black">
+          Sizes with Image
+        </Heading>
+        <div className="pb:flex pb:flex-wrap pb:gap-3 pb:items-end">
+          <Avatar size="xs" src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?auto=format&fit=crop&w=120&q=80" />
+          <Avatar size="sm" src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?auto=format&fit=crop&w=120&q=80" />
+          <Avatar size="md" src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?auto=format&fit=crop&w=120&q=80" />
+          <Avatar size="lg" src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?auto=format&fit=crop&w=120&q=80" />
+          <Avatar size="xl" src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?auto=format&fit=crop&w=120&q=80" />
+        </div>
+      </div>
+
+      <div className="pb:space-y-3">
+        <Heading level={4} className="pb:text-sm pb:font-medium pb:text-black">
+          Initials Fallback (Dynamic Colors)
+        </Heading>
+        <div className="pb:flex pb:flex-wrap pb:gap-3 pb:items-center">
+          <Avatar name="Ada Lovelace" size="md" />
+          <Avatar name="BMO Bot" size="md" />
+          <Avatar name="Coraline Maker" size="md" />
+          <Avatar name="David Porfirio" size="md" />
+          <Avatar name="Frankenstein Robot" size="md" />
+          <Avatar name="Jacob Roberts" size="md" />
+        </div>
+      </div>
+
+      <div className="pb:space-y-3">
+        <Heading level={4} className="pb:text-sm pb:font-medium pb:text-black">
+          Shapes
+        </Heading>
+        <div className="pb:flex pb:flex-wrap pb:gap-3 pb:items-center">
+          <Avatar name="Circle Shape" shape="circle" size="lg" />
+          <Avatar name="Rounded Shape" shape="rounded" size="lg" />
+        </div>
+      </div>
+
+      <div className="pb:space-y-3">
+        <Heading level={4} className="pb:text-sm pb:font-medium pb:text-black">
+          Generic Icon Fallback
+        </Heading>
+        <div className="pb:flex pb:flex-wrap pb:gap-3 pb:items-center">
+          <Avatar size="sm" />
+          <Avatar size="md" />
+          <Avatar size="lg" />
+        </div>
+      </div>
+    </div>
+  ),
+};