@mdxui/tremor 6.0.0

package/README.md

@@ -0,0 +1,255 @@
+# @mdxui/tremor
+
+Tremor template wrappers implementing the mdxui interface. This package provides adapters that wrap [Tremor](https://www.tremor.so/) template components to conform to the `SiteComponents` and `AppComponents` interfaces defined by mdxui.
+
+## What's Included
+
+This package exports five template modules, each implementing specific use cases:
+
+### Dashboard Template (`@mdxui/tremor/dashboard`)
+
+A general-purpose SaaS dashboard implementing the `AppComponents` interface. Features flexible shell layouts with sidebar navigation, workspace switchers, and settings pages.
+
+**Use for:** Admin dashboards, internal tools, SaaS applications
+
+**Key Components:**
+- `Shell` - Main layout container
+- `ShellSidebarLeft` - Left sidebar navigation variant
+- `ShellTopNav` - Top navigation variant
+- `Sidebar` - Navigation sidebar with workspace/user management
+- `Settings` - Settings page layout
+- `AppComponents` - Pre-configured interface object
+
+```typescript
+import { AppComponents, Shell, Sidebar } from '@mdxui/tremor/dashboard'
+
+// Use AppComponents interface with MDX
+<MDXProvider components={AppComponents}>
+  <App>
+    <Shell>
+      <Dashboard title="Analytics">
+        {content}
+      </Dashboard>
+    </Shell>
+  </App>
+</MDXProvider>
+```
+
+### Insights Template (`@mdxui/tremor/insights`)
+
+Analytics dashboard with charts, KPIs, and data tables. Optimized for displaying metrics, trends, and transaction data.
+
+**Use for:** Analytics dashboards, reporting, business intelligence
+
+**Key Components:**
+- `Shell` - Analytics dashboard container
+- `Sidebar` - Navigation for analytics sections
+- `KPICard` - Metric/KPI display
+- `AreaChart`, `BarChart`, `DonutChart`, `BarChartVariant`, `TransactionChart` - Data visualization
+- `TransactionsTable` - Data table with sorting/filtering
+- `components` - Pre-configured interface object
+
+```typescript
+import { components, Shell, Sidebar, KPICard } from '@mdxui/tremor/insights'
+
+// Use with MDX
+<MDXProvider components={components}>
+  <Shell sidebar={<Sidebar items={navItems} />}>
+    <KPICard title="Revenue" value="$25.5M" />
+    <AreaChart data={chartData} />
+    <TransactionsTable transactions={data} />
+  </Shell>
+</MDXProvider>
+```
+
+### Overview Template (`@mdxui/tremor/overview`)
+
+Multi-section dashboard for cross-functional views like Support, Retention, Workflow, and Agents. Implementing the `AppComponents` interface with specialized section components.
+
+**Use for:** Multi-team dashboards, operational overview, support platforms
+
+**Key Components:**
+- `Shell` - Top navigation shell layout
+- `Sidebar` - Secondary navigation
+- `Header` - Header bar
+- `Dashboard` - Dashboard page layout
+- `Settings` - Settings page
+- `AgentsSection`, `RetentionSection`, `SupportSection`, `WorkflowSection` - Specialized dashboard sections
+- `AppComponents` - Pre-configured interface object
+
+```typescript
+import { AppComponents } from '@mdxui/tremor/overview'
+
+// Use with mdxui
+<MDXProvider components={AppComponents}>
+  <App>
+    <Shell>
+      <Dashboard title="Support">
+        <SupportSection tickets={data} />
+      </Dashboard>
+    </Shell>
+  </App>
+</MDXProvider>
+```
+
+### Solar Template (`@mdxui/tremor/solar`)
+
+Minimal landing page template implementing the `SiteComponents` interface. Focused on marketing sites and landing pages with hero sections, features, and CTA components.
+
+**Use for:** Marketing sites, landing pages, product pages
+
+**Key Components:**
+- `Site` - Root site wrapper
+- `Header` - Navigation header
+- `Footer` - Site footer
+- `LandingPage` - Landing page layout
+- `Hero`, `HeroMinimal`, `HeroGradient` - Hero section variants
+- `Features` - Features section
+- `CTA` - Call-to-action section
+- `components` - Pre-configured interface object
+
+```typescript
+import { components, Site, Hero, Features } from '@mdxui/tremor/solar'
+
+// Use with mdxui
+<MDXProvider components={components}>
+  <Site name="My Product">
+    <Hero
+      headline="Build faster"
+      subheadline="Ship with confidence"
+      cta={{ primary: 'Get Started', primaryAction: '/signup' }}
+    />
+    <Features features={featureList} />
+  </Site>
+</MDXProvider>
+```
+
+### Database Template (`@mdxui/tremor/database`)
+
+Marketing site template implementing the `SiteComponents` interface. Provides core layout components for content-heavy marketing sites.
+
+**Use for:** Marketing sites, documentation, content sites, product homepages
+
+**Key Components:**
+- `Site` - Root site wrapper
+- `Header` - Navigation header
+- `Footer` - Site footer
+- `LandingPage` - Landing page layout
+- `Page` - Generic page layout
+- `components` - Pre-configured interface object
+
+```typescript
+import { components, Site, Page } from '@mdxui/tremor/database'
+
+// Use with mdxui
+<MDXProvider components={components}>
+  <Site name="My Product">
+    <Page title="About Us">
+      {content}
+    </Page>
+  </Site>
+</MDXProvider>
+```
+
+## Installation
+
+```bash
+npm install @mdxui/tremor @mdxui/primitives @tremor/react
+```
+
+## Usage
+
+### Basic Setup
+
+Import the template you need and use it with MDX:
+
+```typescript
+import { AppComponents } from '@mdxui/tremor/dashboard'
+import { MDXProvider } from '@mdx-js/react'
+
+export function App() {
+  return (
+    <MDXProvider components={AppComponents}>
+      {/* Your content */}
+    </MDXProvider>
+  )
+}
+```
+
+### Per-Template Imports
+
+Each template is exported as a separate entry point to avoid conflicts:
+
+```typescript
+// App templates (AppComponents interface)
+import { AppComponents as DashboardComponents } from '@mdxui/tremor/dashboard'
+import { AppComponents as OverviewComponents } from '@mdxui/tremor/overview'
+
+// Site templates (SiteComponents interface)
+import { components as SolarComponents } from '@mdxui/tremor/solar'
+import { components as DatabaseComponents } from '@mdxui/tremor/database'
+
+// Analytics template
+import { components as InsightsComponents } from '@mdxui/tremor/insights'
+```
+
+### Shared Utilities
+
+The `shared` export provides utilities available across all templates:
+
+```typescript
+import { /* shared utilities */ } from '@mdxui/tremor/shared'
+```
+
+## Component Variants
+
+Many components offer multiple visual variants. Check individual component stories in the package for variant examples and usage patterns.
+
+## Testing
+
+This package uses test-driven development (TDD) with:
+- **Unit tests** - Component behavior validation
+- **Visual tests** - Playwright snapshot testing
+- **Type checking** - TypeScript for prop validation
+
+Run tests with:
+
+```bash
+pnpm --filter @mdxui/tremor test          # Unit tests
+pnpm --filter @mdxui/tremor test:watch    # Watch mode
+pnpm --filter @mdxui/tremor test:visual   # Visual tests
+```
+
+## Architecture
+
+All templates in this package:
+
+1. **Wrap Tremor components** - Use Tremor's pre-built template patterns as the foundation
+2. **Implement mdxui interfaces** - Conform to `AppComponents` (for dashboards) or `SiteComponents` (for sites)
+3. **Provide type-safe props** - Use TypeScript for IDE autocomplete and compile-time validation
+4. **Support variant patterns** - Offer multiple visual and behavioral configurations
+5. **Maintain Tremor compatibility** - Work seamlessly with Tremor's ecosystem and styling
+
+## Type Safety
+
+The package provides full TypeScript support with exported prop types:
+
+```typescript
+import type {
+  ShellProps as DashboardShellProps,
+  SidebarProps as DashboardSidebarProps,
+  DashboardComponents
+} from '@mdxui/tremor/dashboard'
+```
+
+## Related Packages
+
+- [`mdxui`](https://github.com/dot-do/ui/tree/main/packages/mdxui) - Core interfaces and type contracts
+- [`@mdxui/primitives`](https://github.com/dot-do/ui/tree/main/packages/primitives) - Low-level UI components
+- [`@mdxui/widgets`](https://github.com/dot-do/ui/tree/main/packages/widgets) - Complex interactive widgets
+- [`@mdxui/beacon`](https://github.com/dot-do/ui/tree/main/packages/beacon) - Marketing site templates
+- [`@mdxui/cockpit`](https://github.com/dot-do/ui/tree/main/packages/cockpit) - Developer dashboard templates
+
+## License
+
+MIT

package/dist/dashboard/components/index.d.ts

@@ -0,0 +1,355 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ComponentType, SVGProps, ReactNode } from 'react';
+
+type ShellVariant = "sidebar-left" | "sidebar-right" | "top-nav" | "minimal";
+/**
+ * Navigation item configuration for the shell
+ */
+interface ShellNavItem {
+    /** Unique identifier */
+    id: string;
+    /** Display label */
+    label: string;
+    /** Link href */
+    href?: string;
+    /** Icon component */
+    icon?: ComponentType<SVGProps<SVGSVGElement>>;
+    /** Is currently active */
+    active?: boolean;
+    /** Is disabled */
+    disabled?: boolean;
+    /** Click handler */
+    onClick?: () => void;
+}
+/**
+ * Workspace configuration for workspace switcher
+ */
+interface ShellWorkspace {
+    /** Workspace identifier */
+    id: string;
+    /** Workspace name */
+    name: string;
+    /** Initials for avatar */
+    initials: string;
+    /** User role in workspace */
+    role: string;
+    /** Background color class */
+    color?: string;
+}
+/**
+ * User profile configuration
+ */
+interface ShellUser {
+    /** User display name */
+    name: string;
+    /** User email */
+    email?: string;
+    /** User initials for avatar */
+    initials: string;
+}
+interface ShellProps {
+    /** Shell variant determines layout structure */
+    variant?: ShellVariant;
+    /** Main content area */
+    children?: any;
+    /** Navigation items for sidebar */
+    navigation?: ShellNavItem[];
+    /** Shortcut items for sidebar */
+    shortcuts?: ShellNavItem[];
+    /** Current workspace */
+    workspace?: ShellWorkspace;
+    /** Available workspaces */
+    workspaces?: ShellWorkspace[];
+    /** Current user */
+    user?: ShellUser;
+    /** Is sidebar collapsed */
+    sidebarCollapsed?: boolean;
+    /** Sidebar collapse handler */
+    onSidebarCollapse?: (collapsed: boolean) => void;
+    /** Current pathname for active navigation state */
+    pathname?: string;
+    /** Link component for routing (e.g., Next.js Link) */
+    LinkComponent?: ComponentType<{
+        href: string;
+        className?: string;
+        children: ReactNode;
+    }>;
+    /** Custom sidebar content or boolean to show/hide default sidebar */
+    sidebar?: ReactNode | boolean;
+    /** Custom header content or boolean to show/hide default header */
+    header?: ReactNode | boolean;
+    /** Theme mode */
+    theme?: "light" | "dark" | "system";
+    /** Loading state */
+    loading?: boolean;
+    /** Additional className for the main content area */
+    className?: string;
+    /** Additional className for the shell container */
+    containerClassName?: string;
+}
+/**
+ * Shell - Flexible dashboard shell component with variant support
+ *
+ * A polymorphic shell component that renders different layouts based on the variant prop.
+ * Use the named exports (ShellSidebarLeft, ShellTopNav) for full control over layout props.
+ *
+ * Based on Tremor dashboard template layout patterns:
+ * - Fixed sidebar with workspace switcher and user profile
+ * - Mobile-responsive with drawer navigation
+ * - Support for collapsed sidebar state
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with default variant (sidebar-left)
+ * <Shell navigation={navItems} user={currentUser}>
+ *   <Dashboard />
+ * </Shell>
+ *
+ * // With top-nav variant
+ * <Shell variant="top-nav" header={<TopNav />}>
+ *   <Dashboard />
+ * </Shell>
+ *
+ * // With collapsed sidebar
+ * <Shell sidebarCollapsed={true}>
+ *   <Dashboard />
+ * </Shell>
+ * ```
+ */
+declare function Shell({ variant, children, navigation: _navigation, shortcuts: _shortcuts, workspace: _workspace, workspaces: _workspaces, user: _user, sidebarCollapsed, onSidebarCollapse: _onSidebarCollapse, pathname: _pathname, LinkComponent: _LinkComponent, sidebar, header, theme: _theme, loading, className, containerClassName, }: ShellProps): react_jsx_runtime.JSX.Element;
+
+interface ShellSidebarLeftProps {
+    /** Content to render in the sidebar (left side) - if not provided, uses built-in sidebar */
+    sidebar?: ReactNode;
+    /** Content to render in the mobile header (optional) */
+    mobileHeader?: ReactNode;
+    /** Main content area */
+    children: ReactNode;
+    /** Navigation items for built-in sidebar */
+    navigation?: ShellNavItem[];
+    /** Shortcut items for built-in sidebar */
+    shortcuts?: ShellNavItem[];
+    /** Current workspace */
+    workspace?: ShellWorkspace;
+    /** Available workspaces */
+    workspaces?: ShellWorkspace[];
+    /** Current user */
+    user?: ShellUser;
+    /** Is sidebar collapsed */
+    collapsed?: boolean;
+    /** Sidebar collapse handler */
+    onCollapse?: (collapsed: boolean) => void;
+    /** Current pathname for active navigation state */
+    pathname?: string;
+    /** Link component for routing (e.g., Next.js Link) */
+    LinkComponent?: ComponentType<{
+        href: string;
+        className?: string;
+        children: ReactNode;
+    }>;
+    /** Additional className for the main content area */
+    className?: string;
+    /** Additional className for the container */
+    containerClassName?: string;
+}
+/**
+ * ShellSidebarLeft - Dashboard shell with sidebar on the left
+ *
+ * A layout component that provides a sidebar-left dashboard shell structure
+ * based on the Tremor dashboard template:
+ * - Fixed sidebar (72px wide, or 16px when collapsed) on the left
+ * - Sticky mobile header with workspace switcher and user profile
+ * - Responsive layout with drawer navigation on mobile
+ * - Main content area with proper padding for sidebar
+ *
+ * @example
+ * ```tsx
+ * <ShellSidebarLeft
+ *   navigation={[
+ *     { id: 'overview', label: 'Overview', href: '/overview', icon: HomeIcon },
+ *     { id: 'details', label: 'Details', href: '/details', icon: ListIcon },
+ *   ]}
+ *   workspace={{ id: '1', name: 'Retail Analytics', initials: 'RA', role: 'Member' }}
+ *   user={{ name: 'Emma Stone', initials: 'ES' }}
+ *   pathname="/overview"
+ * >
+ *   <DashboardContent />
+ * </ShellSidebarLeft>
+ * ```
+ */
+declare function ShellSidebarLeft({ sidebar, mobileHeader, children, navigation: _navigation, shortcuts: _shortcuts, workspace: _workspace, workspaces: _workspaces, user: _user, collapsed, onCollapse: _onCollapse, pathname: _pathname, LinkComponent: _LinkComponent, className, containerClassName, }: ShellSidebarLeftProps): react_jsx_runtime.JSX.Element;
+
+interface ShellTopNavProps {
+    /** Content to render in the header/top nav */
+    header: ReactNode;
+    /** Content to render in the sidebar (optional) */
+    sidebar?: ReactNode;
+    /** Main content area */
+    children: ReactNode;
+    /** Additional className for the main content area */
+    className?: string;
+}
+/**
+ * ShellTopNav - Dashboard shell with top navigation
+ *
+ * A layout component that provides a top-nav dashboard shell structure:
+ * - Header/navigation at the top
+ * - Optional sidebar below header
+ * - Main content area
+ */
+declare function ShellTopNav({ header, sidebar, children, className, }: ShellTopNavProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Navigation item configuration for the sidebar
+ */
+interface SidebarNavItem {
+    /** Unique identifier */
+    id: string;
+    /** Display label */
+    label: string;
+    /** Link href */
+    href?: string;
+    /** Icon component */
+    icon?: ComponentType<SVGProps<SVGSVGElement>>;
+    /** Is currently active */
+    active?: boolean;
+    /** Is disabled */
+    disabled?: boolean;
+    /** Click handler */
+    onClick?: () => void;
+}
+/**
+ * Shortcut item configuration
+ */
+interface SidebarShortcutItem {
+    /** Display name */
+    name: string;
+    /** Link href */
+    href: string;
+    /** Icon component */
+    icon?: ComponentType<SVGProps<SVGSVGElement>>;
+}
+/**
+ * Workspace configuration for the workspace switcher
+ */
+interface SidebarWorkspace {
+    /** Workspace identifier */
+    id: string;
+    /** Workspace name */
+    name: string;
+    /** Initials for avatar */
+    initials: string;
+    /** User role in workspace */
+    role: string;
+    /** Background color class */
+    color?: string;
+}
+/**
+ * User profile configuration for the sidebar footer
+ */
+interface SidebarUser {
+    /** User display name */
+    name: string;
+    /** User email */
+    email?: string;
+    /** User initials for avatar */
+    initials: string;
+}
+/**
+ * Props for the Sidebar adapter component
+ */
+interface SidebarProps {
+    /** Navigation items */
+    items?: SidebarNavItem[];
+    /** Shortcut items */
+    shortcuts?: SidebarShortcutItem[];
+    /** Current workspace */
+    workspace?: SidebarWorkspace;
+    /** Available workspaces for switching */
+    workspaces?: SidebarWorkspace[];
+    /** Current user */
+    user?: SidebarUser;
+    /** Is sidebar collapsed */
+    collapsed?: boolean;
+    /** Collapse toggle handler */
+    onCollapse?: (collapsed: boolean) => void;
+    /** Custom header content */
+    header?: ReactNode;
+    /** Custom footer content */
+    footer?: ReactNode;
+    /** Additional className */
+    className?: string;
+    /** Current pathname for active state detection */
+    pathname?: string;
+    /** Link component for routing (e.g., Next.js Link) */
+    LinkComponent?: ComponentType<{
+        href: string;
+        className?: string;
+        children: ReactNode;
+    }>;
+}
+/**
+ * Sidebar - Navigation sidebar with workspace switcher and user profile
+ *
+ * A vertical navigation bar featuring:
+ * - Workspace dropdown at the top
+ * - Primary navigation links
+ * - Shortcuts section
+ * - User profile at the bottom
+ *
+ * Based on Tremor dashboard template sidebar design.
+ */
+declare function Sidebar({ items, shortcuts, workspace, workspaces, user, collapsed, onCollapse: _onCollapse, header, footer, className, pathname, LinkComponent, }: SidebarProps): react_jsx_runtime.JSX.Element;
+/**
+ * Workspace Switcher component
+ */
+interface WorkspaceSwitcherProps {
+    workspace: SidebarWorkspace;
+    workspaces?: SidebarWorkspace[];
+    collapsed?: boolean;
+}
+declare function WorkspaceSwitcher({ workspace, workspaces: _workspaces, collapsed, }: WorkspaceSwitcherProps): react_jsx_runtime.JSX.Element;
+/**
+ * User Profile component for sidebar footer
+ */
+interface UserProfileProps {
+    user: SidebarUser;
+    collapsed?: boolean;
+}
+declare function UserProfile({ user, collapsed }: UserProfileProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Link component props
+ */
+interface LinkProps {
+    href: string;
+    className?: string;
+    children: ReactNode;
+    onClick?: () => void;
+}
+/**
+ * Props for the MobileSidebar component
+ */
+interface MobileSidebarProps {
+    /** Navigation items */
+    items?: SidebarNavItem[];
+    /** Shortcut items */
+    shortcuts?: SidebarShortcutItem[];
+    /** Title for the mobile drawer */
+    title?: string;
+    /** Current pathname for active state detection */
+    pathname?: string;
+    /** Link component for routing (e.g., Next.js Link) */
+    LinkComponent?: ComponentType<LinkProps>;
+    /** Additional className */
+    className?: string;
+}
+/**
+ * Mobile Sidebar - Drawer-based navigation for smaller screens
+ *
+ * A slide-out drawer that displays navigation on mobile devices.
+ * Features a hamburger menu button and animated drawer transition.
+ */
+declare function MobileSidebar({ items, shortcuts, title, pathname, LinkComponent, className, }: MobileSidebarProps): react_jsx_runtime.JSX.Element;
+
+export { MobileSidebar, type MobileSidebarProps, Shell, type ShellNavItem, type ShellProps, ShellSidebarLeft, type ShellSidebarLeftProps, ShellTopNav, type ShellTopNavProps, type ShellUser, type ShellVariant, type ShellWorkspace, Sidebar, type SidebarNavItem, type SidebarProps, type SidebarShortcutItem, type SidebarUser, type SidebarWorkspace, UserProfile, WorkspaceSwitcher };