limitless-ui/README.md

# @limitless/ui

Limitless Layout 3 (Detached Layout) inspired Bootstrap 5 React UI kit for Remix and Next.js. No jQuery, all components are React-first with Bootstrap-compatible markup and a thin theming layer (light/dark/material).

## Layout 3 Structure

This framework implements the **Layout 3 (Detached Layout)** from Limitless template:

```
├── Navbar (full width, top)
├── PageHeader (outside page-content)
│   ├── breadcrumb-line
│   └── page-header-content
├── page-content pt-0
│   ├── Main Sidebar (detached, left)
│   ├── Secondary Sidebar (optional)
│   ├── content-wrapper
│   │   └── content
│   └── Right Sidebar (optional)
└── Footer (outside page-content, bottom)
```

Key characteristics:
- Sidebars appear as detached stand-alone components with shadows
- Page header is placed outside page-content container
- Footer is at the very bottom, outside page-content
- Supports material theme styling with user menu

## Quickstart

```bash
npm install @limitless/ui bootstrap
```

In your app entry (e.g., `root.tsx` in Remix, `_app.tsx` in Next):

```tsx
import 'bootstrap/dist/css/bootstrap.min.css';
import '@limitless/ui/dist/styles.css';

import { ThemeProvider, PageShell, Navbar, Sidebar, PageHeader, Footer } from '@limitless/ui';

export default function App() {
  return (
    <ThemeProvider theme="light">
      <PageShell
        navbar={
          <Navbar
            brand={<img src="/logo.png" alt="Logo" />}
            endItems={/* user menu, notifications */}
          />
        }
        pageHeader={
          <PageHeader
            title="Dashboard"
            breadcrumbs={[
              { label: 'Home', href: '/' },
              { label: 'Dashboard', active: true }
            ]}
          />
        }
        mainSidebar={
          <Sidebar
            variant="main"
            color="light"
            items={[
              { type: 'header', label: 'Main' },
              { label: 'Dashboard', href: '/', active: true },
              { label: 'Settings', href: '/settings' }
            ]}
          />
        }
        footer={
          <Footer
            copyright="2024 Your Company"
            navItems={[{ label: 'Support', href: '/support' }]}
          />
        }
      >
        {/* Page content */}
      </PageShell>
    </ThemeProvider>
  );
}
```

## Components

### Layout Components

- **PageShell**: Main layout wrapper implementing Layout 3 structure
- **Navbar**: Top navigation bar with mobile togglers and user menu support
- **Sidebar**: Detached sidebar with nav-sidebar navigation, user menu, submenus
- **Footer**: Bottom footer bar with collapsible navigation
- **PageHeader**: Page header with breadcrumb-line and header-elements

### UI Components

- **Card**: Cards with header-elements-inline support
- **Button, Badge, Alert**: Bootstrap-compatible basic elements
- **Tabs, Accordion, Collapse**: Interactive content panels
- **Modal, Toast, Tooltip, Popover**: Overlays and notifications
- **Table, DataTable**: Tables with TanStack support
- **Form components**: FormGroup, FormControl, FormCheck, InputGroup, Select
- **Advanced inputs**: DatePicker, ColorPicker, AdvancedSelect, DualListBox
- **Wizard**: Multi-step form wizard

## Sidebar Navigation

The Sidebar component supports Layout 3 navigation structure:

```tsx
<Sidebar
  variant="main"
  color="light"
  user={{
    name: 'John Doe',
    avatar: '/avatar.jpg',
    subtitle: 'Administrator',
    menuItems: [
      { label: 'Profile', href: '/profile' },
      { label: 'Logout', href: '/logout' }
    ]
  }}
  items={[
    { type: 'header', label: 'Navigation' },
    { label: 'Dashboard', icon: <i className="icon-home4" />, href: '/', active: true },
    {
      type: 'submenu',
      label: 'Settings',
      icon: <i className="icon-cog" />,
      children: [
        { label: 'General', href: '/settings/general' },
        { label: 'Security', href: '/settings/security' }
      ]
    },
    { type: 'divider' }
  ]}
/>
```

## Structure

- `src/theme`: theming utilities, CSS variables, `ThemeProvider`
- `src/layout`: Layout 3 components (PageShell, Navbar, Sidebar, Footer)
- `src/components`: Bootstrap-compatible UI components
- `src/hooks`: shared hooks (disclosure/toggles)
- `src/styles.css`: Layout 3 CSS including sidebar, navbar, page-header styles

## Conventions

- Bootstrap 5 tokens/classes, plus Limitless Layout 3 specific classes
- React-first: no jQuery. Interactive behaviors use hooks or modern React
- SSR-friendly: side effects live inside `useEffect`
- TypeScript: full type definitions included

## Development

```bash
npm run typecheck
npm run build
```

This repo uses `tsc` output. Consumers should tree-shake via their bundler.