@checkstack/ui 0.0.2

package/src/components/Markdown.tsx

@@ -0,0 +1,206 @@
+import ReactMarkdown from "react-markdown";
+import type { Components } from "react-markdown";
+import { cn } from "../utils";
+
+export interface MarkdownProps {
+  /** The markdown content to render */
+  children: string;
+  /** Additional CSS classes for the container */
+  className?: string;
+  /** Size variant affecting text size */
+  size?: "sm" | "base" | "lg";
+}
+
+/**
+ * Styled markdown renderer using Tailwind.
+ *
+ * Renders markdown content with consistent styling that matches
+ * the application's design system.
+ *
+ * @example
+ * ```tsx
+ * <Markdown>**Bold** and *italic* text</Markdown>
+ * <Markdown size="sm">Small text with [links](url)</Markdown>
+ * ```
+ */
+export function Markdown({
+  children,
+  className,
+  size = "base",
+}: MarkdownProps) {
+  const sizeClasses = {
+    sm: "text-sm",
+    base: "text-base",
+    lg: "text-lg",
+  };
+
+  const components: Components = {
+    // Paragraphs - no extra margin for inline use
+    p: ({ children }) => <span>{children}</span>,
+
+    // Bold text
+    strong: ({ children }) => (
+      <strong className="font-semibold text-foreground">{children}</strong>
+    ),
+
+    // Italic text
+    em: ({ children }) => <em className="italic">{children}</em>,
+
+    // Links
+    a: ({ href, children }) => (
+      <a
+        href={href}
+        className="text-primary hover:underline"
+        target="_blank"
+        rel="noopener noreferrer"
+      >
+        {children}
+      </a>
+    ),
+
+    // Inline code
+    code: ({ children }) => (
+      <code className="px-1 py-0.5 rounded bg-muted font-mono text-[0.9em]">
+        {children}
+      </code>
+    ),
+
+    // Strikethrough
+    del: ({ children }) => (
+      <del className="line-through text-muted-foreground">{children}</del>
+    ),
+  };
+
+  return (
+    <span className={cn(sizeClasses[size], className)}>
+      <ReactMarkdown components={components}>{children}</ReactMarkdown>
+    </span>
+  );
+}
+
+export interface MarkdownBlockProps extends MarkdownProps {
+  /** Whether to show as a prose block with proper spacing */
+  prose?: boolean;
+}
+
+/**
+ * Styled markdown block renderer for longer content.
+ *
+ * Unlike `Markdown`, this renders full blocks with proper paragraph
+ * spacing, headers, lists, and other block-level elements.
+ *
+ * @example
+ * ```tsx
+ * <MarkdownBlock>
+ *   # Heading
+ *
+ *   Paragraph with **bold** text.
+ *
+ *   - List item 1
+ *   - List item 2
+ * </MarkdownBlock>
+ * ```
+ */
+export function MarkdownBlock({
+  children,
+  className,
+  size = "base",
+  prose = true,
+}: MarkdownBlockProps) {
+  const sizeClasses = {
+    sm: "text-sm",
+    base: "text-base",
+    lg: "text-lg",
+  };
+
+  const components: Components = {
+    // Paragraphs with proper spacing
+    p: ({ children }) => <p className="mb-4 last:mb-0">{children}</p>,
+
+    // Headers
+    h1: ({ children }) => (
+      <h1 className="text-2xl font-bold mb-4 text-foreground">{children}</h1>
+    ),
+    h2: ({ children }) => (
+      <h2 className="text-xl font-semibold mb-3 text-foreground">{children}</h2>
+    ),
+    h3: ({ children }) => (
+      <h3 className="text-lg font-semibold mb-2 text-foreground">{children}</h3>
+    ),
+
+    // Bold text
+    strong: ({ children }) => (
+      <strong className="font-semibold text-foreground">{children}</strong>
+    ),
+
+    // Italic text
+    em: ({ children }) => <em className="italic">{children}</em>,
+
+    // Links
+    a: ({ href, children }) => (
+      <a
+        href={href}
+        className="text-primary hover:underline"
+        target="_blank"
+        rel="noopener noreferrer"
+      >
+        {children}
+      </a>
+    ),
+
+    // Lists
+    ul: ({ children }) => (
+      <ul className="list-disc list-inside mb-4 space-y-1">{children}</ul>
+    ),
+    ol: ({ children }) => (
+      <ol className="list-decimal list-inside mb-4 space-y-1">{children}</ol>
+    ),
+    li: ({ children }) => <li>{children}</li>,
+
+    // Blockquotes
+    blockquote: ({ children }) => (
+      <blockquote className="border-l-4 border-muted pl-4 italic text-muted-foreground mb-4">
+        {children}
+      </blockquote>
+    ),
+
+    // Code blocks
+    pre: ({ children }) => (
+      <pre className="bg-muted p-4 rounded-lg overflow-x-auto mb-4 font-mono text-sm">
+        {children}
+      </pre>
+    ),
+    code: ({ children, className }) => {
+      // Check if this is a code block (has language class)
+      const isBlock = className?.includes("language-");
+      if (isBlock) {
+        return <code>{children}</code>;
+      }
+      return (
+        <code className="px-1 py-0.5 rounded bg-muted font-mono text-[0.9em]">
+          {children}
+        </code>
+      );
+    },
+
+    // Horizontal rule
+    hr: () => <hr className="border-border my-6" />,
+
+    // Strikethrough
+    del: ({ children }) => (
+      <del className="line-through text-muted-foreground">{children}</del>
+    ),
+  };
+
+  return (
+    <div
+      className={cn(
+        sizeClasses[size],
+        prose && "prose prose-neutral dark:prose-invert max-w-none",
+        className
+      )}
+    >
+      <ReactMarkdown components={components}>{children}</ReactMarkdown>
+    </div>
+  );
+}

package/src/components/NavItem.tsx

@@ -0,0 +1,112 @@
+import React, { useState, useRef, useEffect } from "react";
+import { NavLink } from "react-router-dom";
+import { ChevronDown } from "lucide-react";
+import { cn } from "../utils";
+import { useApi, permissionApiRef } from "@checkstack/frontend-api";
+
+export interface NavItemProps {
+  to?: string;
+  label: string;
+  icon?: React.ReactNode;
+  permission?: string;
+  children?: React.ReactNode;
+  className?: string;
+}
+
+export const NavItem: React.FC<NavItemProps> = ({
+  to,
+  label,
+  icon,
+  permission,
+  children,
+  className,
+}) => {
+  const [isOpen, setIsOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // Always call hooks at top level
+  // We assume permissionApi is available if we use it. Safe fallback?
+  // ApiProvider guarantees it if registered. App.tsx registers a default.
+  const permissionApi = useApi(permissionApiRef);
+  const { allowed, loading } = permissionApi.usePermission(permission || "");
+  const hasAccess = permission ? allowed : true;
+
+  // Handle click outside for dropdown
+  useEffect(() => {
+    const handleClickOutside = (event: MouseEvent) => {
+      if (
+        containerRef.current &&
+        !containerRef.current.contains(event.target as Node)
+      ) {
+        setIsOpen(false);
+      }
+    };
+    document.addEventListener("mousedown", handleClickOutside);
+    return () => document.removeEventListener("mousedown", handleClickOutside);
+  }, []);
+
+  if (loading || !hasAccess) return <></>;
+
+  const baseClasses = cn(
+    "flex items-center gap-2 px-3 py-2 rounded-md text-sm font-medium transition-colors cursor-pointer",
+    "text-foreground hover:bg-accent hover:text-accent-foreground",
+    "focus:outline-none focus:ring-2 focus:ring-ring/50",
+    className
+  );
+
+  const activeClasses = "bg-accent text-accent-foreground";
+
+  // Dropdown / Parent Item
+  if (children) {
+    // Check if any child is active to highlight parent
+    // This is naive; normally we'd check paths.
+    // For now, let's just rely on click state or strict path matching if 'to' is present on parent.
+
+    return (
+      <div className="relative group" ref={containerRef}>
+        <button
+          onClick={() => setIsOpen(!isOpen)}
+          className={cn(baseClasses, isOpen && activeClasses)}
+          aria-expanded={isOpen}
+        >
+          {icon && <span className="w-4 h-4">{icon}</span>}
+          <span>{label}</span>
+          <ChevronDown
+            className={cn(
+              "w-4 h-4 transition-transform",
+              isOpen ? "rotate-180" : ""
+            )}
+          />
+        </button>
+
+        {isOpen && (
+          <div className="absolute left-0 mt-1 w-48 rounded-md shadow-lg bg-popover ring-1 ring-border z-50 animate-in fade-in zoom-in-95 duration-100">
+            <div className="py-1 flex flex-col p-1 gap-1">{children}</div>
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  // Leaf Item (Link)
+  if (to) {
+    return (
+      <NavLink
+        to={to}
+        className={({ isActive }) => cn(baseClasses, isActive && activeClasses)}
+        end
+      >
+        {icon && <span className="w-4 h-4">{icon}</span>}
+        <span>{label}</span>
+      </NavLink>
+    );
+  }
+
+  // Fallback (just a label?)
+  return (
+    <div className={baseClasses}>
+      {icon && <span className="w-4 h-4">{icon}</span>}
+      <span>{label}</span>
+    </div>
+  );
+};

package/src/components/Page.tsx

@@ -0,0 +1,58 @@
+import React from "react";
+import { cn } from "../utils";
+
+interface PageProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+export const Page = React.forwardRef<HTMLDivElement, PageProps>(
+  ({ className, children, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn("flex flex-col w-full h-full", className)}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+);
+Page.displayName = "Page";
+
+interface PageHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
+  title: string;
+  subtitle?: string;
+  actions?: React.ReactNode;
+}
+
+export const PageHeader = React.forwardRef<HTMLDivElement, PageHeaderProps>(
+  ({ className, title, subtitle, actions, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(
+        "flex flex-col md:flex-row items-center justify-between p-6 pb-2",
+        className
+      )}
+      {...props}
+    >
+      <div className="space-y-1">
+        <h2 className="text-2xl font-bold tracking-tight">{title}</h2>
+        {subtitle && <p className="text-muted-foreground">{subtitle}</p>}
+      </div>
+      {actions && <div className="flex items-center space-x-2">{actions}</div>}
+    </div>
+  )
+);
+PageHeader.displayName = "PageHeader";
+
+interface PageContentProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+export const PageContent = React.forwardRef<HTMLDivElement, PageContentProps>(
+  ({ className, children, ...props }, ref) => (
+    <div ref={ref} className={cn("flex-1 p-6 pt-2", className)} {...props}>
+      {children}
+    </div>
+  )
+);
+PageContent.displayName = "PageContent";

package/src/components/PageLayout.tsx

@@ -0,0 +1,83 @@
+import React from "react";
+import {
+  Page,
+  PageHeader,
+  PageContent,
+  LoadingSpinner,
+  PermissionDenied,
+} from "..";
+
+interface PageLayoutProps {
+  title: string;
+  subtitle?: string;
+  actions?: React.ReactNode;
+  loading?: boolean;
+  allowed?: boolean;
+  children: React.ReactNode;
+  maxWidth?:
+    | "sm"
+    | "md"
+    | "lg"
+    | "xl"
+    | "2xl"
+    | "3xl"
+    | "4xl"
+    | "5xl"
+    | "6xl"
+    | "7xl"
+    | "full";
+}
+
+export const PageLayout: React.FC<PageLayoutProps> = ({
+  title,
+  subtitle,
+  actions,
+  loading,
+  allowed,
+  children,
+  maxWidth = "3xl",
+}) => {
+  // If loading is explicitly true, show loading state
+  // If loading is undefined and allowed is false, also show loading state
+  // (this prevents "Access Denied" flash when permissions are still being fetched)
+  const isLoading =
+    loading === true || (loading === undefined && allowed === false);
+
+  if (isLoading) {
+    return (
+      <Page>
+        <PageHeader title={title} subtitle={subtitle} actions={actions} />
+        <PageContent>
+          <div className="flex justify-center py-12">
+            <LoadingSpinner />
+          </div>
+        </PageContent>
+      </Page>
+    );
+  }
+
+  // Only show permission denied when loading is explicitly false and allowed is false
+  if (allowed === false) {
+    return (
+      <Page>
+        <PageHeader title={title} subtitle={subtitle} actions={actions} />
+        <PageContent>
+          <PermissionDenied />
+        </PageContent>
+      </Page>
+    );
+  }
+
+  return (
+    <Page>
+      <PageHeader title={title} subtitle={subtitle} actions={actions} />
+      <PageContent>
+        <div
+          className={maxWidth === "full" ? "" : `max-w-${maxWidth} space-y-6`}
+        >
+          {children}
+        </div>
+      </PageContent>
+    </Page>
+  );
+};

package/src/components/PaginatedList.tsx

@@ -0,0 +1,135 @@
+import * as React from "react";
+import {
+  usePagination,
+  type UsePaginationOptions,
+  type PaginationState,
+} from "../hooks/usePagination";
+import { Pagination } from "./Pagination";
+import { cn } from "../utils";
+
+export interface PaginatedListProps<TResponse, TItem, TExtraParams = object>
+  extends UsePaginationOptions<TResponse, TItem, TExtraParams> {
+  /**
+   * Render function for the items
+   */
+  children: (
+    items: TItem[],
+    loading: boolean,
+    pagination: PaginationState
+  ) => React.ReactNode;
+
+  /**
+   * Show loading spinner
+   * @default true
+   */
+  showLoadingSpinner?: boolean;
+
+  /**
+   * Content to show when no items
+   */
+  emptyContent?: React.ReactNode;
+
+  /**
+   * Show pagination controls
+   * @default true
+   */
+  showPagination?: boolean;
+
+  /**
+   * Show page size selector
+   * @default true
+   */
+  showPageSize?: boolean;
+
+  /**
+   * Show total items count
+   * @default true
+   */
+  showTotal?: boolean;
+
+  /**
+   * Available page sizes
+   */
+  pageSizes?: number[];
+
+  /**
+   * Container class name
+   */
+  className?: string;
+
+  /**
+   * Pagination container class name
+   */
+  paginationClassName?: string;
+}
+
+/**
+ * All-in-one paginated list component with automatic data fetching.
+ *
+ * @example
+ * ```tsx
+ * <PaginatedList
+ *   fetchFn={(p) => client.getNotifications(p)}
+ *   getItems={(r) => r.notifications}
+ *   getTotal={(r) => r.total}
+ *   extraParams={{ unreadOnly: true }}
+ * >
+ *   {(items, loading) =>
+ *     loading ? null : items.map((item) => <Card key={item.id} {...item} />)
+ *   }
+ * </PaginatedList>
+ * ```
+ */
+export function PaginatedList<TResponse, TItem, TExtraParams = object>({
+  children,
+  showLoadingSpinner = true,
+  emptyContent,
+  showPagination = true,
+  showPageSize = true,
+  showTotal = true,
+  pageSizes,
+  className,
+  paginationClassName,
+  ...paginationOptions
+}: PaginatedListProps<TResponse, TItem, TExtraParams>) {
+  const { items, loading, pagination } = usePagination(paginationOptions);
+
+  const showEmpty = !loading && items.length === 0 && emptyContent;
+
+  return (
+    <div className={cn("space-y-4", className)}>
+      {/* Loading state */}
+      {loading && showLoadingSpinner && (
+        <div className="flex justify-center py-8 text-muted-foreground">
+          Loading...
+        </div>
+      )}
+
+      {/* Empty state */}
+      {showEmpty && (
+        <div className="flex justify-center py-8 text-muted-foreground">
+          {emptyContent}
+        </div>
+      )}
+
+      {/* Content */}
+      {!showEmpty && children(items, loading, pagination)}
+
+      {/* Pagination controls */}
+      {showPagination && pagination.totalPages > 1 && (
+        <Pagination
+          page={pagination.page}
+          totalPages={pagination.totalPages}
+          onPageChange={pagination.setPage}
+          limit={pagination.limit}
+          onPageSizeChange={pagination.setLimit}
+          total={showTotal ? pagination.total : undefined}
+          showPageSize={showPageSize}
+          showTotal={showTotal}
+          pageSizes={pageSizes}
+          className={paginationClassName}
+        />
+      )}
+    </div>
+  );
+}