@emara/ui 1.1.0

package/components/ui/avatar.tsx

@@ -0,0 +1,257 @@
+"use client";
+
+import { createContext, forwardRef, useContext, useMemo } from "react";
+import * as AvatarPrimitive from "@radix-ui/react-avatar";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+// Per docs/emara-ui-phase-1-components.md §7.
+
+// ----------------------------------------------------------------------------
+// Sizing — single source of truth shared by Avatar root and SkeletonCircle-
+// style children.
+// ----------------------------------------------------------------------------
+
+type Size = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+
+const SIZE_TO_DIM: Record<Size, number> = {
+  xs: 24,
+  sm: 32,
+  md: 40,
+  lg: 48,
+  xl: 64,
+  "2xl": 96,
+};
+
+const avatarSizeClass: Record<Size, string> = {
+  xs: "size-6",
+  sm: "size-8",
+  md: "size-10",
+  lg: "size-12",
+  xl: "size-16",
+  "2xl": "size-24",
+};
+
+const statusDotSize: Record<Size, string> = {
+  xs: "size-1.5",
+  sm: "size-2",
+  md: "size-2.5",
+  lg: "size-3",
+  xl: "size-3.5",
+  "2xl": "size-4",
+};
+
+const fallbackTextSize: Record<Size, string> = {
+  xs: "text-[10px]",
+  sm: "text-xs",
+  md: "text-sm",
+  lg: "text-base",
+  xl: "text-lg",
+  "2xl": "text-2xl",
+};
+
+// ----------------------------------------------------------------------------
+// AvatarGroup context — children inherit a default `size` from their parent
+// group when no per-Avatar size is set.
+// ----------------------------------------------------------------------------
+
+interface AvatarGroupContextValue {
+  size: Size | undefined;
+}
+const AvatarGroupContext = createContext<AvatarGroupContextValue | null>(null);
+
+function useAvatarGroupSize(): Size | undefined {
+  return useContext(AvatarGroupContext)?.size;
+}
+
+// ----------------------------------------------------------------------------
+// Avatar (root)
+// ----------------------------------------------------------------------------
+
+const avatarVariants = cva(
+  "relative inline-flex shrink-0 overflow-hidden border-2 border-background bg-muted text-muted-foreground",
+  {
+    variants: {
+      shape: {
+        circle: "rounded-full",
+        rounded: "rounded-md",
+      },
+    },
+    defaultVariants: {
+      shape: "circle",
+    },
+  },
+);
+
+type Status = "online" | "offline" | "busy" | "away" | "none";
+
+const statusLabel: Record<Exclude<Status, "none">, string> = {
+  online: "Online",
+  offline: "Offline",
+  busy: "Busy",
+  away: "Away",
+};
+
+const statusBgClass: Record<Exclude<Status, "none">, string> = {
+  online: "bg-success",
+  offline: "bg-muted-foreground",
+  busy: "bg-destructive",
+  away: "bg-warning",
+};
+
+type AvatarProps = Omit<
+  React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Root>,
+  "asChild"
+> &
+  VariantProps<typeof avatarVariants> & {
+    size?: Size;
+    status?: Status;
+    statusPosition?: "top-end" | "bottom-end";
+  };
+
+const Avatar = forwardRef<
+  React.ElementRef<typeof AvatarPrimitive.Root>,
+  AvatarProps
+>(function Avatar(
+  {
+    className,
+    size,
+    shape,
+    status = "none",
+    statusPosition = "bottom-end",
+    children,
+    ...props
+  },
+  ref,
+) {
+  const groupSize = useAvatarGroupSize();
+  const resolvedSize: Size = size ?? groupSize ?? "md";
+
+  return (
+    <AvatarPrimitive.Root
+      ref={ref}
+      className={cn(avatarVariants({ shape }), avatarSizeClass[resolvedSize], className)}
+      {...props}
+    >
+      {children}
+      {status !== "none" ? (
+        <span
+          aria-hidden="true"
+          className={cn(
+            "absolute block rounded-full ring-2 ring-background",
+            statusBgClass[status],
+            statusDotSize[resolvedSize],
+            statusPosition === "top-end" ? "top-0 end-0" : "bottom-0 end-0",
+          )}
+        />
+      ) : null}
+      {status !== "none" ? <span className="sr-only">{statusLabel[status]}</span> : null}
+    </AvatarPrimitive.Root>
+  );
+});
+Avatar.displayName = "Avatar";
+
+// ----------------------------------------------------------------------------
+// AvatarImage / AvatarFallback — thin Radix wrappers with default classes.
+// ----------------------------------------------------------------------------
+
+const AvatarImage = forwardRef<
+  React.ElementRef<typeof AvatarPrimitive.Image>,
+  React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Image>
+>(function AvatarImage({ className, alt, ...props }, ref) {
+  return (
+    <AvatarPrimitive.Image
+      ref={ref}
+      alt={alt}
+      className={cn("aspect-square h-full w-full object-cover", className)}
+      {...props}
+    />
+  );
+});
+AvatarImage.displayName = "AvatarImage";
+
+type AvatarFallbackProps = React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Fallback> & {
+  size?: Size;
+};
+
+const AvatarFallback = forwardRef<
+  React.ElementRef<typeof AvatarPrimitive.Fallback>,
+  AvatarFallbackProps
+>(function AvatarFallback({ className, size, ...props }, ref) {
+  const groupSize = useAvatarGroupSize();
+  const resolved: Size = size ?? groupSize ?? "md";
+  return (
+    <AvatarPrimitive.Fallback
+      ref={ref}
+      className={cn(
+        "flex h-full w-full items-center justify-center bg-muted font-medium text-muted-foreground select-none",
+        fallbackTextSize[resolved],
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+AvatarFallback.displayName = "AvatarFallback";
+
+// ----------------------------------------------------------------------------
+// AvatarGroup — overlaps children, optionally truncates with a "+N" pill.
+// ----------------------------------------------------------------------------
+
+type AvatarGroupProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+  size?: Size;
+  spacing?: "tight" | "normal" | "loose";
+  max?: number;
+  children: React.ReactNode;
+};
+
+const spacingMargin: Record<"tight" | "normal" | "loose", string> = {
+  // Negative margin-inline-start — RTL flips automatically.
+  tight: "[&>*+*]:-ms-3",
+  normal: "[&>*+*]:-ms-2",
+  loose: "[&>*+*]:-ms-1",
+};
+
+const AvatarGroup = forwardRef<HTMLDivElement, AvatarGroupProps>(function AvatarGroup(
+  { className, size, spacing = "normal", max, children, ...props },
+  ref,
+) {
+  const ctx = useMemo<AvatarGroupContextValue>(() => ({ size }), [size]);
+
+  const items = (Array.isArray(children) ? children : [children]).filter(Boolean);
+  const visible = max !== undefined ? items.slice(0, max) : items;
+  const hidden = max !== undefined ? Math.max(0, items.length - max) : 0;
+  const dim = SIZE_TO_DIM[size ?? "md"];
+
+  return (
+    <AvatarGroupContext.Provider value={ctx}>
+      <div
+        ref={ref}
+        className={cn("inline-flex isolate", spacingMargin[spacing], className)}
+        {...props}
+      >
+        {visible}
+        {hidden > 0 ? (
+          <span
+            role="status"
+            aria-label={`${hidden} more`}
+            className={cn(
+              "relative inline-flex shrink-0 items-center justify-center rounded-full",
+              "border-2 border-background bg-muted text-muted-foreground font-medium",
+              avatarSizeClass[size ?? "md"],
+              fallbackTextSize[size ?? "md"],
+            )}
+            style={{ width: dim, height: dim }}
+          >
+            +{hidden}
+          </span>
+        ) : null}
+      </div>
+    </AvatarGroupContext.Provider>
+  );
+});
+AvatarGroup.displayName = "AvatarGroup";
+
+export { Avatar, AvatarImage, AvatarFallback, AvatarGroup };
+export type { AvatarProps, AvatarFallbackProps, AvatarGroupProps };

package/components/ui/badge.stories.tsx

@@ -0,0 +1,127 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { RiCheckLine, RiStarLine } from "@remixicon/react";
+
+import { Badge } from "./badge";
+
+const meta: Meta<typeof Badge> = {
+  title: "Foundations/Badge",
+  component: Badge,
+  parameters: { layout: "centered" },
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["default", "secondary", "destructive", "outline", "success", "warning", "info"],
+    },
+    size: { control: "select", options: ["xs", "sm", "md", "lg"] },
+    dot: { control: "boolean" },
+    pulse: { control: "boolean" },
+    removable: { control: "boolean" },
+  },
+  args: { children: "Badge" },
+};
+
+export default meta;
+type Story = StoryObj<typeof Badge>;
+
+export const Default: Story = {};
+
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-2">
+      <Badge variant="default">Default</Badge>
+      <Badge variant="secondary">Secondary</Badge>
+      <Badge variant="destructive">Destructive</Badge>
+      <Badge variant="outline">Outline</Badge>
+      <Badge variant="success">Success</Badge>
+      <Badge variant="warning">Warning</Badge>
+      <Badge variant="info">Info</Badge>
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-end gap-2">
+      <Badge size="xs">xs</Badge>
+      <Badge size="sm">sm</Badge>
+      <Badge size="md">md</Badge>
+      <Badge size="lg">lg</Badge>
+    </div>
+  ),
+};
+
+export const WithDot: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-2">
+      <Badge dot variant="default">
+        Default
+      </Badge>
+      <Badge dot variant="secondary">
+        Secondary
+      </Badge>
+      <Badge dot variant="destructive">
+        Destructive
+      </Badge>
+      <Badge dot variant="outline">
+        Outline
+      </Badge>
+      <Badge dot variant="success">
+        Success
+      </Badge>
+      <Badge dot variant="warning">
+        Warning
+      </Badge>
+      <Badge dot variant="info">
+        Info
+      </Badge>
+    </div>
+  ),
+};
+
+export const PulsingDot: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-2">
+      <Badge dot pulse variant="success">
+        Live
+      </Badge>
+      <Badge dot pulse variant="destructive">
+        Recording
+      </Badge>
+      <Badge dot pulse variant="info">
+        Streaming
+      </Badge>
+    </div>
+  ),
+};
+
+export const WithIcon: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-2">
+      <Badge icon={<RiCheckLine />} variant="success">
+        Verified
+      </Badge>
+      <Badge icon={<RiStarLine />} variant="warning">
+        Featured
+      </Badge>
+      <Badge icon={<RiCheckLine />} variant="outline">
+        Approved
+      </Badge>
+    </div>
+  ),
+};
+
+export const Removable: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-2">
+      <Badge removable onRemove={() => console.log("remove default")}>
+        Default
+      </Badge>
+      <Badge removable onRemove={() => console.log("remove tag")} variant="secondary">
+        TypeScript
+      </Badge>
+      <Badge removable onRemove={() => console.log("remove tag")} variant="outline">
+        Filter
+      </Badge>
+    </div>
+  ),
+};

package/components/ui/badge.tsx

@@ -0,0 +1,146 @@
+"use client";
+
+import { forwardRef } from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { RiCloseLine } from "@remixicon/react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+// Per docs/emara-ui-phase-1-components.md §6.
+
+const badgeVariants = cva(
+  [
+    "inline-flex items-center gap-1 font-medium select-none",
+    "rounded-full border whitespace-nowrap",
+    "transition-colors",
+  ].join(" "),
+  {
+    variants: {
+      variant: {
+        default: "border-transparent bg-primary text-primary-foreground",
+        secondary: "border-transparent bg-secondary text-secondary-foreground",
+        destructive: "border-transparent bg-destructive text-destructive-foreground",
+        outline: "border-border text-foreground",
+        success: "border-transparent bg-success text-primary-foreground",
+        warning: "border-transparent bg-warning text-primary-foreground",
+        info: "border-transparent bg-info text-primary-foreground",
+      },
+      size: {
+        xs: "h-4 px-1.5 text-[10px] leading-none",
+        sm: "h-5 px-2 text-xs leading-none",
+        md: "h-6 px-2.5 text-xs leading-none",
+        lg: "h-7 px-3 text-sm leading-none",
+      },
+    },
+    defaultVariants: { variant: "default", size: "md" },
+  },
+);
+
+// Per-variant dot color (the dot inherits the variant's foreground for
+// outline; otherwise uses currentColor at full opacity).
+const dotVariants = cva("inline-block size-1.5 rounded-full me-1", {
+  variants: {
+    variant: {
+      default: "bg-primary-foreground/90",
+      secondary: "bg-secondary-foreground/80",
+      destructive: "bg-destructive-foreground/90",
+      outline: "bg-foreground/80",
+      success: "bg-primary-foreground/90",
+      warning: "bg-primary-foreground/90",
+      info: "bg-primary-foreground/90",
+    },
+    size: {
+      xs: "size-1",
+      sm: "size-1.5",
+      md: "size-1.5",
+      lg: "size-2",
+    },
+  },
+  defaultVariants: { variant: "default", size: "md" },
+});
+
+type BadgeVariants = VariantProps<typeof badgeVariants>;
+
+type BadgeProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> &
+  BadgeVariants & {
+    asChild?: boolean;
+    dot?: boolean;
+    icon?: React.ReactNode;
+    removable?: boolean;
+    onRemove?: () => void;
+    pulse?: boolean;
+    children?: React.ReactNode;
+  };
+
+const Badge = forwardRef<HTMLSpanElement, BadgeProps>(function Badge(
+  {
+    className,
+    variant,
+    size,
+    asChild = false,
+    dot = false,
+    icon,
+    removable = false,
+    onRemove,
+    pulse = false,
+    children,
+    ...props
+  },
+  ref,
+) {
+  const Comp = asChild ? Slot : "span";
+
+  const innerContent = (
+    <>
+      {dot ? (
+        <span aria-hidden="true" className="relative inline-flex">
+          <span className={cn(dotVariants({ variant, size }))} />
+          {pulse ? (
+            <span
+              aria-hidden="true"
+              className={cn(
+                dotVariants({ variant, size }),
+                "absolute inset-0 me-0 animate-ping opacity-75",
+              )}
+            />
+          ) : null}
+        </span>
+      ) : null}
+      {icon ? (
+        <span aria-hidden="true" className="me-1 inline-flex [&_svg]:size-3.5 [&_svg]:shrink-0">
+          {icon}
+        </span>
+      ) : null}
+      <span>{children}</span>
+      {removable ? (
+        <button
+          type="button"
+          aria-label="Remove"
+          onClick={(e) => {
+            e.stopPropagation();
+            onRemove?.();
+          }}
+          className={cn(
+            "ms-1 inline-flex items-center justify-center rounded-full p-0.5",
+            "hover:bg-foreground/10",
+            "focus-visible:ring-ring focus-visible:ring-offset-background focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none",
+            "[&_svg]:size-3 [&_svg]:shrink-0",
+          )}
+        >
+          <RiCloseLine />
+        </button>
+      ) : null}
+    </>
+  );
+
+  return (
+    <Comp ref={ref} className={cn(badgeVariants({ variant, size }), className)} {...props}>
+      {asChild ? children : innerContent}
+    </Comp>
+  );
+});
+Badge.displayName = "Badge";
+
+export { Badge, badgeVariants };
+export type { BadgeProps };

package/components/ui/breadcrumb.stories.tsx

@@ -0,0 +1,92 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { RiFolderLine, RiHome4Line, RiSettings4Line } from "@remixicon/react";
+
+import {
+  Breadcrumb,
+  BreadcrumbEllipsis,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  Breadcrumbs,
+} from "./breadcrumb";
+
+const meta: Meta<typeof Breadcrumbs> = {
+  title: "Layout/Breadcrumb",
+  component: Breadcrumbs,
+  parameters: { layout: "padded" },
+  argTypes: {
+    size: { control: "select", options: ["sm", "md", "lg"] },
+    maxItems: { control: "number" },
+    itemsBeforeCollapse: { control: "number" },
+    itemsAfterCollapse: { control: "number" },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Breadcrumbs>;
+
+const ITEMS = [
+  { label: "Home", href: "/", icon: <RiHome4Line /> },
+  { label: "Settings", href: "/settings", icon: <RiSettings4Line /> },
+  { label: "Account" },
+];
+
+export const Default: Story = {
+  args: { items: ITEMS },
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="space-y-3">
+      <Breadcrumbs items={ITEMS} size="sm" />
+      <Breadcrumbs items={ITEMS} size="md" />
+      <Breadcrumbs items={ITEMS} size="lg" />
+    </div>
+  ),
+};
+
+const MANY = [
+  { label: "Home", href: "/", icon: <RiHome4Line /> },
+  { label: "Workspaces", href: "/workspaces" },
+  { label: "Acme", href: "/workspaces/acme" },
+  { label: "Projects", href: "/workspaces/acme/projects" },
+  { label: "Q3 launch", href: "/workspaces/acme/projects/q3", icon: <RiFolderLine /> },
+  { label: "Tasks" },
+];
+
+export const Collapsing: Story = {
+  args: { items: MANY, maxItems: 4, itemsBeforeCollapse: 1, itemsAfterCollapse: 2 },
+};
+
+export const CustomSeparator: Story = {
+  args: { items: ITEMS, separator: <span className="text-muted-foreground/60">/</span> },
+};
+
+/** Manual primitives — when you need full layout control. */
+export const Primitives: Story = {
+  render: () => (
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="/">
+            <RiHome4Line /> Home
+          </BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbLink href="/library">Library</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbEllipsis />
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>Components</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  ),
+};