@emara/ui 1.1.0

package/components/ui/app-shell.tsx

@@ -0,0 +1,491 @@
+"use client";
+
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+import { RiMenuLine } from "@remixicon/react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+import { Button } from "./button";
+import { Drawer, DrawerContent, DrawerOverlay, DrawerPortal } from "./drawer";
+import { TooltipProvider } from "./tooltip";
+
+// Per docs/emara-ui-phase-5-components.md §1.
+
+type AppShellVariant = "default" | "header-only" | "sidebar-only" | "minimal";
+type SidebarPosition = "start" | "end";
+type SidebarWidthToken = "sm" | "md" | "lg";
+type HeaderHeightToken = "sm" | "md" | "lg";
+type Breakpoint = "sm" | "md" | "lg";
+
+// Resolved px sizes (kept in TS so we can drive CSS variables for use in
+// transitions and Drawer fallback width).
+const SIDEBAR_WIDTH_PX = {
+  sm: 200,
+  md: 240,
+  lg: 280,
+} as const;
+
+const SIDEBAR_COLLAPSED_WIDTH_PX = 64;
+
+const HEADER_HEIGHT_PX = {
+  sm: 48,
+  md: 56,
+  lg: 64,
+} as const;
+
+// Tailwind class fragments for each breakpoint (typed to keep `min-w-` arbitrary
+// values out so the JIT only emits what we use).
+const BREAKPOINT_MIN_WIDTH_CLASS: Record<Breakpoint, string> = {
+  sm: "min-[640px]:flex",
+  md: "min-[768px]:flex",
+  lg: "min-[1024px]:flex",
+};
+
+const BREAKPOINT_HIDE_BELOW_CLASS: Record<Breakpoint, string> = {
+  sm: "max-[639px]:hidden",
+  md: "max-[767px]:hidden",
+  lg: "max-[1023px]:hidden",
+};
+
+const BREAKPOINT_SHOW_TRIGGER_BELOW_CLASS: Record<Breakpoint, string> = {
+  // Hamburger button appears below the breakpoint.
+  sm: "min-[640px]:hidden",
+  md: "min-[768px]:hidden",
+  lg: "min-[1024px]:hidden",
+};
+
+// ===========================================================================
+// Context
+// ===========================================================================
+
+interface AppShellContextValue {
+  variant: AppShellVariant;
+  sidebarPosition: SidebarPosition;
+  sidebarWidthPx: number;
+  collapsedWidthPx: number;
+  headerHeightPx: number;
+  sidebarBreakpoint: Breakpoint;
+  stickyHeader: boolean;
+  bordered: boolean;
+  /** True when inline sidebar is in icon-only mode (desktop). */
+  sidebarCollapsed: boolean;
+  setSidebarCollapsed: (collapsed: boolean) => void;
+  /** True when mobile drawer is open. */
+  sidebarOpen: boolean;
+  setSidebarOpen: (open: boolean) => void;
+  mainId: string;
+}
+
+const AppShellContext = createContext<AppShellContextValue | null>(null);
+
+/** Read AppShell state from any descendant. */
+function useAppShell(): AppShellContextValue {
+  const ctx = useContext(AppShellContext);
+  if (!ctx) throw new Error("useAppShell must be used inside <AppShell>");
+  return ctx;
+}
+
+// ===========================================================================
+// Skip link
+// ===========================================================================
+
+function SkipLink({
+  targetId,
+  label = "Skip to main content",
+}: {
+  targetId: string;
+  label?: string;
+}) {
+  return (
+    <a
+      href={`#${targetId}`}
+      className={cn(
+        "sr-only focus:not-sr-only",
+        "focus:z-overlay focus:fixed focus:inset-s-2 focus:top-2",
+        "focus:bg-primary focus:rounded-md focus:px-3 focus:py-2",
+        "focus:text-primary-foreground focus:shadow-md",
+        "focus:ring-ring focus:ring-offset-background focus:ring-2 focus:ring-offset-2 focus:outline-none",
+      )}
+    >
+      {label}
+    </a>
+  );
+}
+
+// ===========================================================================
+// Root
+// ===========================================================================
+
+const appShellRootVariants = cva("min-h-dvh w-full bg-background text-foreground", {
+  variants: {
+    bordered: { true: "", false: "" },
+  },
+  defaultVariants: { bordered: false },
+});
+
+type AppShellRootVariants = VariantProps<typeof appShellRootVariants>;
+
+type AppShellProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> &
+  AppShellRootVariants & {
+    variant?: AppShellVariant;
+    sidebarPosition?: SidebarPosition;
+    sidebarWidth?: SidebarWidthToken | number;
+    headerHeight?: HeaderHeightToken | number;
+    sidebarCollapsed?: boolean;
+    defaultSidebarCollapsed?: boolean;
+    onSidebarCollapsedChange?: (collapsed: boolean) => void;
+    sidebarBreakpoint?: Breakpoint;
+    stickyHeader?: boolean;
+    /** aria-label for the auto-injected hamburger button. Default "Open navigation". */
+    sidebarOpenLabel?: string;
+    /** Localized text for the skip link. Default "Skip to main content". */
+    skipLinkLabel?: string;
+    children?: ReactNode;
+  };
+
+const AppShell = forwardRef<HTMLDivElement, AppShellProps>(function AppShell(
+  {
+    className,
+    variant = "default",
+    sidebarPosition = "start",
+    sidebarWidth = "md",
+    headerHeight = "md",
+    sidebarCollapsed: controlledCollapsed,
+    defaultSidebarCollapsed = false,
+    onSidebarCollapsedChange,
+    sidebarBreakpoint = "md",
+    stickyHeader = true,
+    bordered = false,
+    sidebarOpenLabel = "Open navigation",
+    skipLinkLabel = "Skip to main content",
+    children,
+    ...props
+  },
+  ref,
+) {
+  const mainId = useId();
+
+  // Collapsed state (controlled / uncontrolled)
+  const [uncontrolledCollapsed, setUncontrolledCollapsed] = useState(defaultSidebarCollapsed);
+  const collapsedIsControlled = controlledCollapsed !== undefined;
+  const sidebarCollapsed = collapsedIsControlled ? controlledCollapsed : uncontrolledCollapsed;
+  const setSidebarCollapsed = useCallback(
+    (next: boolean) => {
+      if (!collapsedIsControlled) setUncontrolledCollapsed(next);
+      onSidebarCollapsedChange?.(next);
+    },
+    [collapsedIsControlled, onSidebarCollapsedChange],
+  );
+
+  // Mobile drawer open state
+  const [sidebarOpen, setSidebarOpen] = useState(false);
+
+  // Resolve widths/heights to px values
+  const sidebarWidthPx =
+    typeof sidebarWidth === "number" ? sidebarWidth : SIDEBAR_WIDTH_PX[sidebarWidth];
+  const headerHeightPx =
+    typeof headerHeight === "number" ? headerHeight : HEADER_HEIGHT_PX[headerHeight];
+
+  const ctx = useMemo<AppShellContextValue>(
+    () => ({
+      variant,
+      sidebarPosition,
+      sidebarWidthPx,
+      collapsedWidthPx: SIDEBAR_COLLAPSED_WIDTH_PX,
+      headerHeightPx,
+      sidebarBreakpoint,
+      stickyHeader,
+      bordered: Boolean(bordered),
+      sidebarCollapsed,
+      setSidebarCollapsed,
+      sidebarOpen,
+      setSidebarOpen,
+      mainId,
+    }),
+    [
+      variant,
+      sidebarPosition,
+      sidebarWidthPx,
+      headerHeightPx,
+      sidebarBreakpoint,
+      stickyHeader,
+      bordered,
+      sidebarCollapsed,
+      setSidebarCollapsed,
+      sidebarOpen,
+      mainId,
+    ],
+  );
+
+  // Auto-close the mobile drawer when the viewport widens above the breakpoint.
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+    const min = sidebarBreakpoint === "sm" ? 640 : sidebarBreakpoint === "md" ? 768 : 1024;
+    const mql = window.matchMedia(`(min-width: ${min}px)`);
+    const onChange = () => {
+      if (mql.matches) setSidebarOpen(false);
+    };
+    mql.addEventListener("change", onChange);
+    return () => mql.removeEventListener("change", onChange);
+  }, [sidebarBreakpoint]);
+
+  const hasSidebar = variant === "default" || variant === "sidebar-only";
+  const hasHeader = variant === "default" || variant === "header-only";
+
+  // Style: CSS variables for inline sidebar/header sizing so children can
+  // refer to them (e.g. drawer fallback width, content offset).
+  const style: React.CSSProperties = {
+    "--app-shell-sidebar-width": `${sidebarWidthPx}px`,
+    "--app-shell-sidebar-collapsed-width": `${SIDEBAR_COLLAPSED_WIDTH_PX}px`,
+    "--app-shell-header-height": `${headerHeightPx}px`,
+    ...(props.style as React.CSSProperties | undefined),
+  } as React.CSSProperties;
+
+  return (
+    <AppShellContext.Provider value={ctx}>
+      <TooltipProvider delayDuration={200}>
+        <div
+          ref={ref}
+          data-slot="app-shell"
+          data-variant={variant}
+          data-sidebar-position={hasSidebar ? sidebarPosition : undefined}
+          className={cn(appShellRootVariants({ bordered }), className)}
+          style={style}
+          {...props}
+        >
+          <SkipLink targetId={mainId} label={skipLinkLabel} />
+
+          {children}
+
+          {/*
+            Auto-injected hamburger button for narrow viewports. AppShellSidebar
+            renders the mobile Drawer that this button opens.
+          */}
+          {hasSidebar && hasHeader ? (
+            <Button
+              variant="ghost"
+              size="icon-sm"
+              aria-label={sidebarOpenLabel}
+              onClick={() => setSidebarOpen(true)}
+              className={cn(
+                "z-fixed fixed top-2",
+                sidebarPosition === "start" ? "inset-s-2" : "inset-e-2",
+                BREAKPOINT_SHOW_TRIGGER_BELOW_CLASS[sidebarBreakpoint],
+              )}
+            >
+              <RiMenuLine />
+            </Button>
+          ) : null}
+        </div>
+      </TooltipProvider>
+    </AppShellContext.Provider>
+  );
+});
+AppShell.displayName = "AppShell";
+
+// ===========================================================================
+// Slots
+// ===========================================================================
+
+const AppShellHeader = forwardRef<HTMLElement, React.HTMLAttributes<HTMLElement>>(
+  function AppShellHeader({ className, ...props }, ref) {
+    const { stickyHeader, bordered, headerHeightPx, variant } = useAppShell();
+    if (variant === "sidebar-only" || variant === "minimal") return null;
+    return (
+      <header
+        ref={ref}
+        role="banner"
+        data-slot="app-shell-header"
+        className={cn(
+          "bg-background z-sticky flex w-full items-center",
+          stickyHeader && "sticky top-0",
+          bordered && "border-border border-b",
+          className,
+        )}
+        style={{ height: headerHeightPx }}
+        {...props}
+      />
+    );
+  },
+);
+AppShellHeader.displayName = "AppShellHeader";
+
+const AppShellSidebar = forwardRef<HTMLElement, React.HTMLAttributes<HTMLElement>>(
+  function AppShellSidebar({ className, children, ...props }, ref) {
+    const {
+      variant,
+      sidebarPosition,
+      sidebarCollapsed,
+      sidebarBreakpoint,
+      bordered,
+      sidebarWidthPx,
+      collapsedWidthPx,
+      sidebarOpen,
+      setSidebarOpen,
+      headerHeightPx,
+      stickyHeader,
+    } = useAppShell();
+    if (variant === "header-only" || variant === "minimal") return null;
+
+    const widthPx = sidebarCollapsed ? collapsedWidthPx : sidebarWidthPx;
+    const showInlineAtClass = BREAKPOINT_MIN_WIDTH_CLASS[sidebarBreakpoint];
+    const hideBelowClass = BREAKPOINT_HIDE_BELOW_CLASS[sidebarBreakpoint];
+
+    return (
+      <>
+        {/* Inline sidebar (desktop) */}
+        <aside
+          ref={ref}
+          data-slot="app-shell-sidebar"
+          data-position={sidebarPosition}
+          className={cn(
+            "hidden flex-col",
+            // Show inline only above the breakpoint.
+            showInlineAtClass,
+            hideBelowClass,
+            // Pinned to the side; respects sticky header by offsetting top.
+            stickyHeader ? "sticky" : "",
+            bordered &&
+              (sidebarPosition === "start" ? "border-border border-e" : "border-border border-s"),
+            className,
+          )}
+          style={{
+            width: widthPx,
+            transition: "width var(--duration-normal)",
+            ...(stickyHeader
+              ? { top: headerHeightPx, height: `calc(100dvh - ${headerHeightPx}px)` }
+              : { height: "100dvh" }),
+            // Use logical order to put sidebar on the start/end side.
+            order: sidebarPosition === "start" ? 0 : 2,
+          }}
+          {...props}
+        >
+          {children}
+        </aside>
+
+        {/* Mobile portal: render the same children inside the drawer that AppShell already opens. */}
+        <MobileSidebarPortal
+          open={sidebarOpen}
+          onOpenChange={setSidebarOpen}
+          position={sidebarPosition}
+        >
+          {children}
+        </MobileSidebarPortal>
+      </>
+    );
+  },
+);
+AppShellSidebar.displayName = "AppShellSidebar";
+
+function MobileSidebarPortal({
+  open,
+  onOpenChange,
+  position,
+  children,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  position: SidebarPosition;
+  children: ReactNode;
+}) {
+  return (
+    <Drawer open={open} onOpenChange={onOpenChange}>
+      <DrawerPortal>
+        <DrawerOverlay />
+        <DrawerContent position={position} size="sm" aria-label="Navigation" className="p-0">
+          {children}
+        </DrawerContent>
+      </DrawerPortal>
+    </Drawer>
+  );
+}
+
+const AppShellMain = forwardRef<HTMLElement, React.HTMLAttributes<HTMLElement>>(
+  function AppShellMain({ className, ...props }, ref) {
+    const { mainId, sidebarPosition, variant } = useAppShell();
+    const hasSidebar = variant === "default" || variant === "sidebar-only";
+    return (
+      <main
+        ref={ref}
+        id={mainId}
+        role="main"
+        data-slot="app-shell-main"
+        className={cn("min-w-0 flex-1 overflow-x-hidden focus:outline-none", className)}
+        style={hasSidebar ? { order: sidebarPosition === "start" ? 1 : 1 } : undefined}
+        // Focus the main on programmatic navigation (skip link target).
+        tabIndex={-1}
+        {...props}
+      />
+    );
+  },
+);
+AppShellMain.displayName = "AppShellMain";
+
+const AppShellFooter = forwardRef<HTMLElement, React.HTMLAttributes<HTMLElement>>(
+  function AppShellFooter({ className, ...props }, ref) {
+    const { variant, bordered } = useAppShell();
+    if (variant === "minimal") {
+      // Minimal still allows a footer.
+    }
+    return (
+      <footer
+        ref={ref}
+        role="contentinfo"
+        data-slot="app-shell-footer"
+        className={cn("bg-background w-full", bordered && "border-border border-t", className)}
+        style={{ order: 3 }}
+        {...props}
+      />
+    );
+  },
+);
+AppShellFooter.displayName = "AppShellFooter";
+
+// ===========================================================================
+// Layout container (auto-injected: when AppShell variants need it, consumers
+// can wrap their Header+Sidebar+Main+Footer in <AppShellLayout> for proper
+// flex/grid composition).
+// ===========================================================================
+
+const AppShellLayout = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  function AppShellLayout({ className, ...props }, ref) {
+    const { variant } = useAppShell();
+    // For default/sidebar-only: lay out header on top + (sidebar | main) row.
+    // We use a simple flex column with header sticky and a row inside via order tricks.
+    // Easiest: grid template based on variant.
+    return (
+      <div
+        ref={ref}
+        data-slot="app-shell-layout"
+        className={cn(
+          "flex w-full",
+          variant === "header-only" || variant === "minimal" ? "min-h-dvh flex-col" : "min-h-dvh",
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+AppShellLayout.displayName = "AppShellLayout";
+
+export {
+  AppShell,
+  AppShellHeader,
+  AppShellSidebar,
+  AppShellMain,
+  AppShellFooter,
+  AppShellLayout,
+  useAppShell,
+};
+export type { AppShellProps, AppShellVariant, SidebarPosition, AppShellContextValue };

package/components/ui/avatar.stories.tsx

@@ -0,0 +1,174 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { Avatar, AvatarFallback, AvatarGroup, AvatarImage } from "./avatar";
+
+const SRC_VALID = "https://i.pravatar.cc/96?img=12";
+const SRC_BROKEN = "/__missing-avatar.png";
+
+const meta: Meta<typeof Avatar> = {
+  title: "Foundations/Avatar",
+  component: Avatar,
+  parameters: { layout: "centered" },
+  argTypes: {
+    size: { control: "select", options: ["xs", "sm", "md", "lg", "xl", "2xl"] },
+    shape: { control: "select", options: ["circle", "rounded"] },
+    status: { control: "select", options: ["none", "online", "offline", "busy", "away"] },
+    statusPosition: { control: "select", options: ["top-end", "bottom-end"] },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Avatar>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Avatar {...args}>
+      <AvatarImage src={SRC_VALID} alt="Alice" />
+      <AvatarFallback>AB</AvatarFallback>
+    </Avatar>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex items-end gap-3">
+      {(["xs", "sm", "md", "lg", "xl", "2xl"] as const).map((size) => (
+        <Avatar key={size} size={size}>
+          <AvatarImage src={SRC_VALID} alt="" />
+          <AvatarFallback>A</AvatarFallback>
+        </Avatar>
+      ))}
+    </div>
+  ),
+};
+
+export const Shapes: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <Avatar shape="circle" size="lg">
+        <AvatarImage src={SRC_VALID} alt="" />
+        <AvatarFallback>C</AvatarFallback>
+      </Avatar>
+      <Avatar shape="rounded" size="lg">
+        <AvatarImage src={SRC_VALID} alt="" />
+        <AvatarFallback>R</AvatarFallback>
+      </Avatar>
+    </div>
+  ),
+};
+
+export const FallbackOnly: Story = {
+  render: () => (
+    <div className="flex items-center gap-3">
+      <Avatar size="md">
+        <AvatarFallback>AB</AvatarFallback>
+      </Avatar>
+      <Avatar size="lg">
+        <AvatarFallback>JD</AvatarFallback>
+      </Avatar>
+    </div>
+  ),
+};
+
+export const FallbackOnError: Story = {
+  render: () => (
+    <Avatar size="lg">
+      <AvatarImage src={SRC_BROKEN} alt="" />
+      <AvatarFallback>ER</AvatarFallback>
+    </Avatar>
+  ),
+};
+
+export const Status: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      {(["online", "offline", "busy", "away"] as const).map((status) => (
+        <Avatar key={status} status={status} size="lg">
+          <AvatarImage src={SRC_VALID} alt="" />
+          <AvatarFallback>{status.charAt(0).toUpperCase()}</AvatarFallback>
+        </Avatar>
+      ))}
+    </div>
+  ),
+};
+
+export const StatusTopEnd: Story = {
+  render: () => (
+    <Avatar status="online" statusPosition="top-end" size="lg">
+      <AvatarImage src={SRC_VALID} alt="" />
+      <AvatarFallback>T</AvatarFallback>
+    </Avatar>
+  ),
+};
+
+export const Group: Story = {
+  render: () => (
+    <AvatarGroup size="md">
+      <Avatar>
+        <AvatarImage src="https://i.pravatar.cc/96?img=1" alt="A" />
+        <AvatarFallback>A</AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarImage src="https://i.pravatar.cc/96?img=2" alt="B" />
+        <AvatarFallback>B</AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarImage src="https://i.pravatar.cc/96?img=3" alt="C" />
+        <AvatarFallback>C</AvatarFallback>
+      </Avatar>
+    </AvatarGroup>
+  ),
+};
+
+export const GroupWithOverflow: Story = {
+  render: () => (
+    <AvatarGroup size="md" max={3}>
+      {Array.from({ length: 6 }).map((_, i) => (
+        <Avatar key={i}>
+          <AvatarImage src={`https://i.pravatar.cc/96?img=${i + 1}`} alt="" />
+          <AvatarFallback>{String(i + 1)}</AvatarFallback>
+        </Avatar>
+      ))}
+    </AvatarGroup>
+  ),
+};
+
+export const GroupSpacing: Story = {
+  render: () => (
+    <div className="space-y-3">
+      <div>
+        <p className="text-muted-foreground mb-2 text-xs">tight</p>
+        <AvatarGroup size="md" spacing="tight">
+          {Array.from({ length: 4 }).map((_, i) => (
+            <Avatar key={i}>
+              <AvatarImage src={`https://i.pravatar.cc/96?img=${i + 10}`} alt="" />
+              <AvatarFallback>{i}</AvatarFallback>
+            </Avatar>
+          ))}
+        </AvatarGroup>
+      </div>
+      <div>
+        <p className="text-muted-foreground mb-2 text-xs">normal</p>
+        <AvatarGroup size="md" spacing="normal">
+          {Array.from({ length: 4 }).map((_, i) => (
+            <Avatar key={i}>
+              <AvatarImage src={`https://i.pravatar.cc/96?img=${i + 10}`} alt="" />
+              <AvatarFallback>{i}</AvatarFallback>
+            </Avatar>
+          ))}
+        </AvatarGroup>
+      </div>
+      <div>
+        <p className="text-muted-foreground mb-2 text-xs">loose</p>
+        <AvatarGroup size="md" spacing="loose">
+          {Array.from({ length: 4 }).map((_, i) => (
+            <Avatar key={i}>
+              <AvatarImage src={`https://i.pravatar.cc/96?img=${i + 10}`} alt="" />
+              <AvatarFallback>{i}</AvatarFallback>
+            </Avatar>
+          ))}
+        </AvatarGroup>
+      </div>
+    </div>
+  ),
+};