@emara/ui 1.1.0

package/components/ui/sidebar.tsx

@@ -0,0 +1,623 @@
+"use client";
+
+import {
+  Children,
+  cloneElement,
+  createContext,
+  forwardRef,
+  isValidElement,
+  useContext,
+  useMemo,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import * as CollapsiblePrimitive from "@radix-ui/react-collapsible";
+import { Slot } from "@radix-ui/react-slot";
+import { RiArrowDownSLine, RiArrowLeftSLine, RiArrowRightSLine } from "@remixicon/react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+import { Popover, PopoverContent, PopoverTrigger } from "./popover";
+import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip";
+
+// Per docs/emara-ui-phase-5-components.md §2.
+
+// ---- Context ---------------------------------------------------------------
+
+type SidebarVariant = "filled" | "outline" | "floating";
+
+interface SidebarContextValue {
+  variant: SidebarVariant;
+  collapsed: boolean;
+}
+
+const SidebarContext = createContext<SidebarContextValue | null>(null);
+
+function useSidebar(): SidebarContextValue {
+  const ctx = useContext(SidebarContext);
+  if (!ctx) throw new Error("Sidebar subcomponents must be used inside <Sidebar>");
+  return ctx;
+}
+
+// ---- Root ------------------------------------------------------------------
+
+// Width is driven by tokens (--sidebar-w-{sm,md,lg,collapsed}) defined in
+// design-tokens §11b.3. Collapsed width is fixed across sizes.
+const sidebarVariants = cva(
+  "flex h-full flex-col text-foreground transition-[width] duration-normal",
+  {
+    variants: {
+      variant: {
+        filled: "bg-muted",
+        outline: "bg-background border-e border-border",
+        floating: "bg-card rounded-lg shadow-md m-2",
+      },
+      size: {
+        sm: "",
+        md: "",
+        lg: "",
+      },
+      collapsed: {
+        true: "w-sidebar-collapsed",
+        false: "",
+      },
+    },
+    compoundVariants: [
+      // Expanded width — driven by `size` only when not collapsed.
+      { collapsed: false, size: "sm", class: "w-sidebar-sm" },
+      { collapsed: false, size: "md", class: "w-sidebar-md" },
+      { collapsed: false, size: "lg", class: "w-sidebar-lg" },
+    ],
+    defaultVariants: {
+      variant: "filled",
+      size: "md",
+      collapsed: false,
+    },
+  },
+);
+
+type SidebarVariants = VariantProps<typeof sidebarVariants>;
+
+type SidebarProps = React.HTMLAttributes<HTMLElement> &
+  SidebarVariants & {
+    asChild?: boolean;
+  };
+
+const Sidebar = forwardRef<HTMLElement, SidebarProps>(function Sidebar(
+  { className, variant = "filled", size = "md", collapsed = false, asChild = false, ...props },
+  ref,
+) {
+  const Comp = (asChild ? Slot : "aside") as React.ElementType;
+  const ctx = useMemo<SidebarContextValue>(
+    () => ({
+      variant: variant ?? "filled",
+      collapsed: collapsed ?? false,
+    }),
+    [variant, collapsed],
+  );
+  return (
+    <SidebarContext.Provider value={ctx}>
+      <Comp
+        ref={ref}
+        data-collapsed={collapsed || undefined}
+        data-variant={variant}
+        data-size={size}
+        className={cn(sidebarVariants({ variant, size, collapsed }), className)}
+        {...props}
+      />
+    </SidebarContext.Provider>
+  );
+});
+Sidebar.displayName = "Sidebar";
+
+// ---- Brand / Header / Body / Footer ---------------------------------------
+
+const SidebarBrand = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  function SidebarBrand({ className, ...props }, ref) {
+    const { collapsed } = useSidebar();
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "text-foreground flex h-14 shrink-0 items-center gap-2 px-3 font-semibold",
+          "[&_svg]:size-6 [&_svg]:shrink-0",
+          collapsed && "justify-center",
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+SidebarBrand.displayName = "SidebarBrand";
+
+const SidebarHeader = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  function SidebarHeader({ className, ...props }, ref) {
+    return <div ref={ref} className={cn("shrink-0 px-3 pb-2", className)} {...props} />;
+  },
+);
+SidebarHeader.displayName = "SidebarHeader";
+
+const SidebarBody = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  function SidebarBody({ className, ...props }, ref) {
+    return (
+      <div
+        ref={ref}
+        className={cn("flex-1 space-y-3 overflow-x-hidden overflow-y-auto px-2 py-2", className)}
+        {...props}
+      />
+    );
+  },
+);
+SidebarBody.displayName = "SidebarBody";
+
+const SidebarFooter = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  function SidebarFooter({ className, ...props }, ref) {
+    return (
+      <div
+        ref={ref}
+        className={cn("border-border/60 shrink-0 border-t px-2 py-2", className)}
+        {...props}
+      />
+    );
+  },
+);
+SidebarFooter.displayName = "SidebarFooter";
+
+// ---- Group -----------------------------------------------------------------
+
+const SidebarGroup = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  function SidebarGroup({ className, ...props }, ref) {
+    return <div ref={ref} className={cn("space-y-1", className)} {...props} />;
+  },
+);
+SidebarGroup.displayName = "SidebarGroup";
+
+const SidebarGroupLabel = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  function SidebarGroupLabel({ className, ...props }, ref) {
+    const { collapsed } = useSidebar();
+    if (collapsed) {
+      return <div ref={ref} aria-hidden="true" className="h-2" />;
+    }
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "text-muted-foreground px-3 pb-1 text-xs font-medium tracking-wider uppercase",
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+SidebarGroupLabel.displayName = "SidebarGroupLabel";
+
+// ---- Item visual ----------------------------------------------------------
+
+const itemVariants = cva(
+  [
+    "group flex w-full items-center gap-2 rounded-md ps-3 pe-2 text-sm cursor-pointer",
+    "text-foreground transition-colors select-none",
+    "hover:bg-accent hover:text-accent-foreground",
+    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+    "[&_svg]:size-4 [&_svg]:shrink-0",
+    "data-[active=true]:bg-accent data-[active=true]:text-accent-foreground data-[active=true]:font-medium",
+    "data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50",
+  ].join(" "),
+  {
+    variants: {
+      collapsed: {
+        true: "justify-center px-0 h-10 w-10 mx-auto",
+        false: "h-9",
+      },
+    },
+    defaultVariants: { collapsed: false },
+  },
+);
+
+// Inner item content — used by both flat Items and the trigger of expandable Items
+function ItemContent({
+  icon,
+  label,
+  badge,
+  kbd,
+  expandable,
+  expanded,
+  collapsed,
+}: {
+  icon?: ReactNode;
+  label: ReactNode;
+  badge?: ReactNode;
+  kbd?: string[];
+  expandable?: boolean;
+  expanded?: boolean;
+  collapsed: boolean;
+}) {
+  return (
+    <>
+      {icon ? <span className="shrink-0">{icon}</span> : null}
+      <span className={cn("flex-1 truncate text-start", collapsed && "sr-only")}>{label}</span>
+      {!collapsed && badge ? <span className="ms-1 shrink-0">{badge}</span> : null}
+      {!collapsed && kbd && kbd.length > 0 ? (
+        <kbd className="border-border bg-muted text-muted-foreground ms-1 inline-flex items-center gap-0.5 rounded border px-1.5 py-0.5 text-[10px] font-medium">
+          {kbd.map((k, i) => (
+            <span key={i}>{k}</span>
+          ))}
+        </kbd>
+      ) : null}
+      {!collapsed && expandable ? (
+        <span
+          aria-hidden="true"
+          className={cn(
+            "text-muted-foreground ms-1 shrink-0 transition-transform",
+            expanded && "rotate-180",
+          )}
+        >
+          <RiArrowDownSLine />
+        </span>
+      ) : null}
+    </>
+  );
+}
+
+// ---- Item ------------------------------------------------------------------
+
+type SidebarItemBaseProps = React.HTMLAttributes<HTMLElement> & {
+  icon?: ReactNode;
+  label?: ReactNode;
+  badge?: ReactNode;
+  kbd?: string[];
+  tooltip?: string;
+  active?: boolean;
+  disabled?: boolean;
+  asChild?: boolean;
+};
+
+type SidebarItemFlatProps = SidebarItemBaseProps & {
+  expandable?: false;
+  /** Required for expandable=true. Ignored when flat. */
+  defaultExpanded?: boolean;
+  children?: ReactNode;
+};
+
+type SidebarItemExpandableProps = SidebarItemBaseProps & {
+  expandable: true;
+  defaultExpanded?: boolean;
+  /** Nested SidebarSubItems. */
+  children?: ReactNode;
+};
+
+type SidebarItemProps = SidebarItemFlatProps | SidebarItemExpandableProps;
+
+const SidebarItem = forwardRef<HTMLElement, SidebarItemProps>(function SidebarItem(
+  {
+    className,
+    icon,
+    label,
+    badge,
+    kbd,
+    tooltip,
+    active = false,
+    disabled = false,
+    asChild = false,
+    children,
+    ...rest
+  },
+  ref,
+) {
+  const expandable = "expandable" in rest && rest.expandable === true;
+  const defaultExpanded =
+    "defaultExpanded" in rest && rest.defaultExpanded ? Boolean(rest.defaultExpanded) : false;
+  // Strip discriminator keys before spreading onto DOM.
+  const domProps: Record<string, unknown> = { ...rest };
+  delete domProps.expandable;
+  delete domProps.defaultExpanded;
+
+  const { collapsed } = useSidebar();
+
+  // Use label as accessible tooltip text when none provided + collapsed mode.
+  const tooltipText = tooltip ?? (typeof label === "string" ? label : undefined);
+
+  // --- Expandable ----------------------------------------------------------
+  if (expandable) {
+    return (
+      <ExpandableItem
+        ref={ref as React.Ref<HTMLDivElement>}
+        defaultExpanded={defaultExpanded}
+        active={active}
+        disabled={disabled}
+        collapsed={collapsed}
+        {...(icon !== undefined ? { icon } : {})}
+        label={label}
+        {...(badge !== undefined ? { badge } : {})}
+        {...(kbd !== undefined ? { kbd } : {})}
+        {...(tooltipText !== undefined ? { tooltip: tooltipText } : {})}
+        {...(className !== undefined ? { className } : {})}
+        {...(domProps as React.HTMLAttributes<HTMLDivElement>)}
+      >
+        {children}
+      </ExpandableItem>
+    );
+  }
+
+  // --- Flat item -----------------------------------------------------------
+  const sharedProps = {
+    "data-active": active || undefined,
+    "data-disabled": disabled || undefined,
+    ...(disabled ? { "aria-disabled": true, tabIndex: -1 } : {}),
+    ...(active ? { "aria-current": "page" as const } : {}),
+    className: cn(itemVariants({ collapsed }), className),
+    ...domProps,
+  };
+  const itemContent = (
+    <ItemContent
+      {...(icon !== undefined ? { icon } : {})}
+      label={label}
+      {...(badge !== undefined ? { badge } : {})}
+      {...(kbd !== undefined ? { kbd } : {})}
+      collapsed={collapsed}
+    />
+  );
+
+  let triggerEl: ReactNode;
+  if (asChild) {
+    // Clone the consumer's single child (an `<a>`, Next `<Link>`, etc.),
+    // merge our props onto it, and inject ItemContent as its body. Any
+    // existing children on the consumer's element are preserved before
+    // ItemContent so consumers can compose if they want.
+    const child = Children.only(children) as ReactElement<{
+      className?: string;
+      ref?: React.Ref<unknown>;
+      children?: ReactNode;
+    }>;
+    if (!isValidElement(child)) {
+      throw new Error("SidebarItem with asChild expects a single valid React element.");
+    }
+    triggerEl = cloneElement(
+      child,
+      {
+        ...sharedProps,
+        className: cn(sharedProps.className, child.props.className),
+        ref,
+      },
+      child.props.children ?? itemContent,
+    );
+  } else {
+    triggerEl = (
+      <button ref={ref as React.Ref<HTMLButtonElement>} type="button" {...sharedProps}>
+        {itemContent}
+      </button>
+    );
+  }
+
+  if (collapsed && tooltipText) {
+    // `side="right"` is correct for a start-positioned sidebar in both
+    // LTR (toward content on the right) and RTL (Radix auto-flips to
+    // "left", which is toward content). For an end-positioned sidebar
+    // the tooltip would point off-screen — a known limitation tracked
+    // for v1.x once Sidebar can read its parent AppShell's position.
+    return (
+      <Tooltip>
+        <TooltipTrigger asChild>{triggerEl}</TooltipTrigger>
+        <TooltipContent side="right">{tooltipText}</TooltipContent>
+      </Tooltip>
+    );
+  }
+
+  return triggerEl;
+});
+SidebarItem.displayName = "SidebarItem";
+
+// ---- ExpandableItem (internal) --------------------------------------------
+
+const ExpandableItem = forwardRef<
+  HTMLDivElement,
+  Omit<SidebarItemBaseProps, "tooltip"> & {
+    defaultExpanded: boolean;
+    tooltip?: string;
+    collapsed: boolean;
+    children?: ReactNode;
+  }
+>(function ExpandableItem(
+  {
+    defaultExpanded,
+    icon,
+    label,
+    badge,
+    kbd,
+    tooltip,
+    active,
+    disabled,
+    className,
+    collapsed,
+    children,
+    ...props
+  },
+  ref,
+) {
+  const [open, setOpen] = useState(defaultExpanded);
+
+  // Collapsed mode: open as a popover instead of inline collapsible.
+  if (collapsed) {
+    return (
+      <Popover>
+        <PopoverTrigger asChild>
+          <button
+            ref={ref as unknown as React.Ref<HTMLButtonElement>}
+            type="button"
+            data-active={active || undefined}
+            data-disabled={disabled || undefined}
+            {...(disabled ? { "aria-disabled": true, tabIndex: -1 } : {})}
+            className={cn(itemVariants({ collapsed: true }), className)}
+          >
+            <ItemContent
+              {...(icon !== undefined ? { icon } : {})}
+              label={label}
+              {...(badge !== undefined ? { badge } : {})}
+              {...(kbd !== undefined ? { kbd } : {})}
+              expandable
+              collapsed
+            />
+          </button>
+        </PopoverTrigger>
+        <PopoverContent side="right" align="start" className="w-56 p-1">
+          {tooltip ? (
+            <div className="text-muted-foreground px-2 py-1.5 text-xs font-medium">{tooltip}</div>
+          ) : null}
+          <div className="space-y-0.5">{children}</div>
+        </PopoverContent>
+      </Popover>
+    );
+  }
+
+  return (
+    <CollapsiblePrimitive.Root open={open} onOpenChange={setOpen} asChild>
+      <div ref={ref} className="contents">
+        <CollapsiblePrimitive.Trigger asChild>
+          <button
+            type="button"
+            data-active={active || undefined}
+            data-disabled={disabled || undefined}
+            {...(disabled ? { "aria-disabled": true, tabIndex: -1 } : {})}
+            className={cn(itemVariants({ collapsed: false }), className)}
+            {...props}
+          >
+            <ItemContent
+              {...(icon !== undefined ? { icon } : {})}
+              label={label}
+              {...(badge !== undefined ? { badge } : {})}
+              {...(kbd !== undefined ? { kbd } : {})}
+              expandable
+              expanded={open}
+              collapsed={false}
+            />
+          </button>
+        </CollapsiblePrimitive.Trigger>
+        <CollapsiblePrimitive.Content
+          className={cn(
+            "overflow-hidden",
+            "data-[state=open]:animate-[collapse-down_var(--duration-fast,150ms)_var(--ease-out,ease-out)]",
+            "data-[state=closed]:animate-[collapse-up_var(--duration-fast,150ms)_var(--ease-in,ease-in)]",
+            "[--collapsible-content-height:var(--radix-collapsible-content-height)]",
+          )}
+        >
+          <div className="border-border ms-3 mt-0.5 space-y-0.5 border-s ps-3">{children}</div>
+        </CollapsiblePrimitive.Content>
+      </div>
+    </CollapsiblePrimitive.Root>
+  );
+});
+ExpandableItem.displayName = "ExpandableItem";
+
+// ---- SubItem ---------------------------------------------------------------
+
+type SidebarSubItemProps = Omit<SidebarItemBaseProps, "tooltip"> & {
+  children?: ReactNode;
+};
+
+const SidebarSubItem = forwardRef<HTMLElement, SidebarSubItemProps>(function SidebarSubItem(
+  {
+    className,
+    icon,
+    label,
+    badge,
+    kbd,
+    active = false,
+    disabled = false,
+    asChild = false,
+    ...rest
+  },
+  ref,
+) {
+  const Comp = (asChild ? Slot : "button") as React.ElementType;
+  return (
+    <Comp
+      ref={ref}
+      data-active={active || undefined}
+      data-disabled={disabled || undefined}
+      {...(disabled ? { "aria-disabled": true, tabIndex: -1 } : {})}
+      {...(active ? { "aria-current": "page" } : {})}
+      {...(!asChild ? { type: "button" as const } : {})}
+      className={cn(
+        // Slightly smaller indent; reuses item variants for color logic.
+        "group flex h-8 w-full cursor-pointer items-center gap-2 rounded-md ps-3 pe-2 text-sm",
+        "text-muted-foreground transition-colors select-none",
+        "hover:bg-accent hover:text-accent-foreground",
+        "focus-visible:ring-ring focus-visible:ring-2 focus-visible:outline-none",
+        "[&_svg]:size-4 [&_svg]:shrink-0",
+        "data-[active=true]:bg-accent data-[active=true]:text-accent-foreground data-[active=true]:font-medium",
+        "data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50",
+        className,
+      )}
+      {...rest}
+    >
+      {icon ? <span className="shrink-0">{icon}</span> : null}
+      <span className="flex-1 truncate text-start">{label}</span>
+      {badge ? <span className="ms-1 shrink-0">{badge}</span> : null}
+      {kbd && kbd.length > 0 ? (
+        <kbd className="border-border bg-muted text-muted-foreground ms-1 inline-flex items-center gap-0.5 rounded border px-1.5 py-0.5 text-[10px] font-medium">
+          {kbd.map((k, i) => (
+            <span key={i}>{k}</span>
+          ))}
+        </kbd>
+      ) : null}
+    </Comp>
+  );
+});
+SidebarSubItem.displayName = "SidebarSubItem";
+
+// ---- CollapseToggle --------------------------------------------------------
+
+interface SidebarCollapseToggleProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Override the auto-injected aria-label. */
+  expandLabel?: string;
+  collapseLabel?: string;
+}
+
+const SidebarCollapseToggle = forwardRef<HTMLButtonElement, SidebarCollapseToggleProps>(
+  function SidebarCollapseToggle(
+    { className, expandLabel = "Expand sidebar", collapseLabel = "Collapse sidebar", ...props },
+    ref,
+  ) {
+    const { collapsed } = useSidebar();
+    return (
+      <button
+        ref={ref}
+        type="button"
+        aria-label={collapsed ? expandLabel : collapseLabel}
+        className={cn(
+          "inline-flex h-8 w-full cursor-pointer items-center justify-center rounded-md",
+          "text-muted-foreground hover:bg-accent hover:text-accent-foreground",
+          "focus-visible:ring-ring focus-visible:ring-2 focus-visible:outline-none",
+          "[&_svg]:size-4 [&_svg]:shrink-0",
+          className,
+        )}
+        {...props}
+      >
+        {collapsed ? (
+          <RiArrowRightSLine className="rtl-mirror" />
+        ) : (
+          <RiArrowLeftSLine className="rtl-mirror" />
+        )}
+      </button>
+    );
+  },
+);
+SidebarCollapseToggle.displayName = "SidebarCollapseToggle";
+
+export {
+  Sidebar,
+  SidebarBrand,
+  SidebarHeader,
+  SidebarBody,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupLabel,
+  SidebarItem,
+  SidebarSubItem,
+  SidebarCollapseToggle,
+  sidebarVariants,
+};
+export type { SidebarProps, SidebarItemProps, SidebarSubItemProps, SidebarCollapseToggleProps };