import { AppShell } from '@/components';

const NAV_SECTIONS = [
  {
    id: 'modules',
    label: 'Modules',
    items: [
      { id: 'items', label: 'Items', href: '/items', shortcut: 'Alt+5' },
      { id: 'vendors', label: 'Vendors', href: '/vendors' },
    ],
  },
];

export default function Page() {
  return (
    <AppShell
      navSections={NAV_SECTIONS}
      currentPath="/items"
      breadcrumbs={[
        { label: 'Dashboard', href: '/' },
        { label: 'Items' }
      ]}
      user={{ name: 'Rahul Kumar', role: 'Manager' }}
      info="Items Module"
      mode="ITEMS"
    >
      {/* Page content here */}
    </AppShell>
  );
}

// Automatic flash behavior is enabled by default.
<AppShell
  loading={saving}
  loadingLabel="Saving purchase order"
  flashProgressOnAction
  progressFlashDuration={720}
>
  {children}
</AppShell>

// AppShell flashes progress for:
// - shell navigation
// - browser back/forward navigation
// - button/link clicks
// - shortcut-triggered Button and ActionTile clicks
// - form submits
// - explicit loading={true}

// For custom controls:
<div role="button" data-progress-action onClick={runImport}>Import</div>

// To suppress automatic flash:
<button data-progress-ignore="true">Local Toggle</button>

// Enabled by default for every AppShell screen.
<AppShell
  enableHealthRecovery
  healthCheckDelay={8000}
  autoReloadDelay={15000}
  responsivenessLagThreshold={5000}
>
  {children}
</AppShell>

// The shell watches for:
// - browser offline/online events
// - long loading={true} or navigation states
// - failed script and stylesheet chunks
// - unhandled application errors and promise failures
// - high browser JS memory pressure when the browser exposes it
// - main-thread stalls after the browser becomes responsive again

// Recoverable failures show a reason and reload automatically.
// Offline states wait for the connection to return instead of reloading in a loop.
// Auto reload is capped at two attempts per route/reason per minute.

import {
  Modal,
  Drawer,
  ConfirmDialog,
  EmptyState,
  LoadingState,
  ErrorState,
  PermissionDeniedState,
  useToast,
} from '@/components';

function Page() {
  const [modalOpen, setModalOpen] = useState(false);
  const [drawerOpen, setDrawerOpen] = useState(false);
  const [confirmOpen, setConfirmOpen] = useState(false);
  const { addToast } = useToast();

  return (
    <>
      <Button onClick={() => setModalOpen(true)}>Open Modal</Button>
      <Button onClick={() => setDrawerOpen(true)}>Open Drawer</Button>
      <Button onClick={() => setConfirmOpen(true)}>Delete</Button>
      <Button onClick={() => addToast({ title: 'Saved', variant: 'success' })}>
        Toast
      </Button>

      <Modal open={modalOpen} onClose={() => setModalOpen(false)} title="Edit Item">
        Modal content
      </Modal>

      <Drawer open={drawerOpen} onClose={() => setDrawerOpen(false)} title="Filters">
        Drawer content
      </Drawer>

      <ConfirmDialog
        open={confirmOpen}
        onClose={() => setConfirmOpen(false)}
        onConfirm={deleteRecord}
        title="Delete this record?"
        intent="danger"
      />

      <EmptyState />
      <LoadingState />
      <ErrorState />
      <PermissionDeniedState />
    </>
  );
}

// ThemeProvider wraps the app with ToastProvider, so useToast works anywhere.
// Modal, Drawer, and ConfirmDialog trap focus and close with Escape by default.

import { Card, CardHeader, CardBody, CardFooter } from '@/components';

// Default card
<Card>
  <CardHeader title="Card Title" subtitle="Optional subtitle" />
  <CardBody>Content here</CardBody>
</Card>

// Variants - colored left border
<Card variant="primary">...</Card>
<Card variant="success">...</Card>
<Card variant="warning">...</Card>
<Card variant="danger">...</Card>
<Card variant="info">...</Card>

// With actions
<Card>
  <CardHeader
    title="Title"
    action={<Button size="sm">Edit</Button>}
  />
  <CardBody>Content</CardBody>
</Card>

import { Button } from '@/components';

// Variants
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="danger">Danger</Button>
<Button variant="success">Success</Button>

// Sizes
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>

// States
<Button loading={true}>Loading...</Button>
<Button disabled>Disabled</Button>

// With click handler and functional shortcut
<Button shortcut="Alt+S" onClick={() => console.log('saved')}>Save</Button>
<Button shortcut="Esc" onClick={() => console.log('cancelled')}>Cancel</Button>

import { Icon, getNavIcon } from '@/components';
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';

// Use the theme registry for page and control icons.
<Icon.Search size={14} />
<Icon.Plus size={14} />
<Icon.ChartLine size={20} />

// Navigation and module cards use nav item ids.
<FontAwesomeIcon icon={getNavIcon('reports')} />

// Theme rule: use FontAwesome icons only.
// Do not use inline SVG, emoji icons, generated icon strings, or mixed icon libraries.

import { faListCheck, faPlus } from '@fortawesome/free-solid-svg-icons';
import { ActionTile } from '@/components';

// FontAwesome solid icons only, no emoji or generated icon strings.
// Light color variants: blue, emerald, amber, rose, violet, cyan, slate.
<ActionTile
  title="Items Master"
  description="View and manage all item records"
  icon={faListCheck}
  shortcut="Alt+M"
  color="blue"
  href="/items/master"
/>

<ActionTile
  title="New Item"
  description="Add a new item to the master list"
  icon={faPlus}
  shortcut="Alt+N"
  color="emerald"
  href="/items/new"
/>

import { ReportCard } from '@/components';

<ReportCard
  title="Sales Summary"
  description="Daily, weekly, and monthly sales overview"
  icon="ChartLine"
  shortcut="Alt+S"
  lastGenerated="08 May 2026"
  color="blue"
  href="/reports/sales-summary"
/>

// Put report cards in a normal responsive grid.
// Use one unique shortcut per report and include those shortcuts in AppShell.shortcuts.
// Avoid visually ambiguous or reserved keys like Alt+O/Alt+0, Alt+L ledger, and Alt+T trial balance.
// The page search input should use data-search-input so / focuses it.

import { Input, Select, Textarea } from '@/components';

<Input
  label="Name"
  placeholder="Enter name"
  value={value}
  onChange={e => setValue(e.target.value)}
  required
  error="This field is required"
  hint="Helpful information"
/>

<Select
  label="Country"
  value={country}
  onChange={e => setCountry(e.target.value)}
  options={[
    { value: 'in', label: 'India' },
    { value: 'us', label: 'United States' },
  ]}
/>

<Textarea
  label="Description"
  value={desc}
  onChange={e => setDesc(e.target.value)}
  rows={4}
/>

import { Badge } from '@/components';

<Badge variant="default">Default</Badge>
<Badge variant="primary">Primary</Badge>
<Badge variant="success">Success</Badge>
<Badge variant="warning">Warning</Badge>
<Badge variant="danger">Danger</Badge>
<Badge variant="info">Info</Badge>

import { KPIStrip } from '@/components';

const items = [
  { label: 'Total Revenue', value: '₹2.4L', change: '+12%', trend: 'up' },
  { label: 'Pending Orders', value: '8', trend: 'neutral' },
  { label: 'Low Stock', value: '3', trend: 'down' },
];

<KPIStrip items={items} />

import { Pagination, ViewTabs } from '@/components';

const [view, setView] = useState<'cards' | 'table'>('cards');
const [page, setPage] = useState(1);
const [pageSize, setPageSize] = useState(25);

<ViewTabs
  variant="segmented"
  value={view}
  onChange={setView}
  tabs={[
    { id: 'cards', label: 'Cards', count: 84 },
    { id: 'table', label: 'Table', count: 84 },
  ]}
/>

<Pagination
  page={page}
  pageSize={pageSize}
  totalItems={84}
  pageSizeOptions={[10, 25, 50, 100]}
  onPageChange={setPage}
  onPageSizeChange={setPageSize}
  onLoadMore={loadNextChunk}
  hasMore={hasMoreRows}
/>

// Use ViewTabs for cards/table/split/chart modes.
// Use Pagination directly for custom report cards and list pages.
// DataGrid can render Pagination internally with the pagination prop.

import { DataGrid, Column } from '@/components';

const columns: Column<Item>[] = [
  { key: 'id', header: '#', width: 60 },
  { key: 'name', header: 'Name', sortable: true },
  { key: 'category', header: 'Category', filter: 'select',
    filterOptions: [{ value: 'all', label: 'All' }, { value: 'food', label: 'Food' }] },
  { key: 'price', header: 'Price', sortable: true,
    render: (val) => <span style={{ color: 'green' }}>₹{val}</span> },
];

<DataGrid
  data={items}
  columns={columns}
  rowKey="id"
  compact
  searchable
  onRowClick={(row) => console.log(row)}
  pagination={{
    defaultPageSize: 25,
    pageSizeOptions: [10, 25, 50, 100],
  }}
/>

// Manual/server paging.
<DataGrid
  data={serverRows}
  columns={columns}
  rowKey="id"
  pagination={{
    mode: 'manual',
    page,
    pageSize,
    totalItems,
    loading,
    hasMore,
    onPageChange: fetchPage,
    onPageSizeChange: setPageSize,
    onLoadMore: loadNextChunk,
  }}
/>

// First cell is auto-focused on page load.
// Active row and active cell are both highlighted.
// Arrow keys move rows and columns.
// Enter opens the active row when onRowClick is set.
// Select cells keep native up/down option navigation.

import { EditableGrid, type ColumnDef } from '@/components';

const columns: ColumnDef[] = [
  { key: 'ingredient', header: 'Ingredient', editable: true },
  { key: 'qty', header: 'Qty', type: 'number', align: 'right', step: 0.1 },
  {
    key: 'unit',
    header: 'Unit',
    type: 'select',
    options: [
      { value: 'kg', label: 'kg' },
      { value: 'ltr', label: 'ltr' },
      { value: 'pcs', label: 'pcs' },
    ],
  },
  { key: 'cost', header: 'Cost', type: 'readonly',
    render: value => `Rs. ${value}` },
];

<EditableGrid
  data={bomRows}
  columns={columns}
  rowKey="id"
  addLabel="Add Ingredient"
  minRows={1}
  maxRows={100}
  onChange={setBomRows}
/>

// EditableGrid is built for spreadsheet-like ERP entry:
// - Tab moves across editable cells and creates a row at the end.
// - Arrow keys move between cells unless a select needs native option navigation.
// - Alt+A adds a row when the grid is focused.
// - Alt+Delete removes the active row.
// - active row and active cell are both highlighted.
// - set autoFocus={false} inside docs or preview surfaces.

import { MultiLevelGridView, type MultiLevelGridLevel } from '@/components';

const levels: MultiLevelGridLevel[] = [
  {
    id: 'brands',
    title: 'Ingredient Brands',
    rowKey: 'brandId',
    columns: brandColumns,
    getRows: context => brandStock[String(context.root?.ingredient ?? '')] ?? [],
    getRowLabel: row => String(row.brand ?? ''),
    next: { levelId: 'vendors', shortcut: 'Alt+V', label: 'Open vendors' },
  },
  {
    id: 'vendors',
    title: 'Vendors',
    rowKey: 'vendorId',
    columns: vendorColumns,
    getRows: context => vendorsByBrand[String(context.selectedRows.brands?.brandId ?? '')] ?? [],
    getRowLabel: row => String(row.vendor ?? ''),
    next: { levelId: 'ledger', shortcut: 'Alt+L', label: 'Open ledger' },
  },
  {
    id: 'ledger',
    title: 'Vendor Ledger',
    rowKey: 'ledgerId',
    columns: ledgerColumns,
    getRows: context => ledgerByVendor[String(context.selectedRows.vendors?.vendorId ?? '')] ?? [],
  },
];

<InlineGrid
  data={rows}
  columns={columns}
  rowKey="id"
  onActiveRowChange={row => setActiveIngredient(row)}
/>

<MultiLevelGridView
  title="Ingredient Drilldown"
  levels={levels}
  rootContext={activeIngredient}
  openShortcut="Alt+I"
  openLabel="Brands"
/>

// Example flow:
// 1. Select an ingredient row in the BOM grid.
// 2. Press Alt+I to open brand stock.
// 3. Select a brand and press Alt+V to open vendors.
// 4. Select a vendor and press Alt+L to open account ledger.
// 5. Press Alt+Backspace to move back one level.

The BOM module uses this pattern for editable recipes: Bill of Materials rows open `/bom/[id]`, ingredient rows remain editable in `InlineGrid`, and the selected ingredient drives the nested brand, vendor, and ledger grids.

import { ModuleGrid, type Module } from '@/components';

const modules: Module[] = [
  { id: 'items', name: 'Items', description: 'Manage items', shortcut: 'Alt+5', href: '/items' },
  { id: 'items-master', name: 'Items Master', description: 'Master data', shortcut: 'Alt+M', href: '/items/master' },
  { id: 'po', name: 'Purchase Orders', description: 'Procurement workflow', shortcut: 'Alt+9', href: '/po' },
  { id: 'reports', name: 'Reports', description: 'ERP analysis', shortcut: 'Alt+R', href: '/reports' },
];

const [focusedIndex, setFocusedIndex] = useState(0);

<ModuleGrid
  modules={modules}
  columns={4}
  focusedIndex={focusedIndex}
  onFocusChange={setFocusedIndex}
  onClick={module => router.push(module.href ?? `/${module.id}`)}
/>

// Keyboard behavior:
// - Arrow keys move between module cards.
// - Enter and Space trigger the focused module.
// - Home and End jump to first and last module.
// - Inputs and data grid cells keep their own keyboard behavior.

import { ActivityFeed } from '@/components';

const activities = [
  { id: '1', title: 'Order Created', description: 'PO/2025-26/48', time: '10:24', type: 'success' },
  { id: '2', title: 'Low Stock Alert', time: '09:00', type: 'warning' },
  { id: '3', title: 'Invoice Exported', time: '08:42', type: 'info' },
];

<ActivityFeed activities={activities} maxItems={5} />

import { KPICard } from '@/components';

<KPICard
  label="Revenue Today"
  value="Rs. 45,280"
  change="+12%"
  trend="up"
  color="success"
  icon={<Icon.MoneyTrend size={14} />}
/>

// Use KPIStrip for normal multi-card metric rows.
// Use KPICard directly when you need a custom dashboard grid,
// a sidebar metric, or a compact summary inside another component.

Invoice, GRN, and Purchase Order screens share the same document skeleton: toolbar actions, branded header, metadata grid, parties, item table, totals, supporting boxes, checklist cards, signatures, and print-safe CSS. Use ERPDocument to configure that structure instead of rebuilding each page manually.

import {
  ERPDocument,
  DocumentStatusBadge,
  type ERPDocumentParty,
  type ERPDocumentSection,
} from '@/components';

import { DashboardLayoutBuilder, type DashboardLayoutItem } from '@/components';

const [widgets, setWidgets] = useState<DashboardLayoutItem[]>([
  { id: 'sales', title: 'Sales Today', size: 'sm', metrics: [{ label: 'Sales', value: 'Rs. 8.4L' }] },
  { id: 'kitchen', title: 'Kitchen Load', size: 'md', metrics: [{ label: 'Open KOT', value: 48 }] },
]);

<DashboardLayoutBuilder
  items={widgets}
  onChange={setWidgets}
  columns={3}
/>;

// Persist widgets after onChange to save each user's dashboard layout.

import { EnterpriseChart } from '@/components';

<EnterpriseChart
  kind="composed"
  data={salesData}
  xKey="day"
  currency
  series={[
    { key: 'sales', label: 'Sales', type: 'bar' },
    { key: 'margin', label: 'Margin', type: 'area' },
    { key: 'orders', label: 'Orders', type: 'line' },
  ]}
/>;

// Supported kinds: line, bar, area, pie, composed.

import { FileUploadZone, type UploadedAsset } from '@/components';

const [assets, setAssets] = useState<UploadedAsset[]>([]);

<FileUploadZone
  accept="image/*,.pdf,.doc,.docx,.xls,.xlsx"
  maxFiles={8}
  maxSizeMb={10}
  onAssetsChange={setAssets}
/>;

// Use the returned asset metadata to upload to S3/R2, attach to GRN/PO/Invoice,
// or pass selected images into OCRCapturePanel.

import { OCRCapturePanel } from '@/components';

<OCRCapturePanel
  language="eng"
  onCapture={({ text, fields }) => {
    saveCapturedDocument({
      rawText: text,
      documentNo: fields.documentNo,
      gstin: fields.gstin,
      amount: fields.amount,
    });
  }}
/>;

// Built-in field hints: documentNo, date, GSTIN, amount, vendor.
// Keep validation in your ERP workflow before posting financial entries.

// Client
<CloudStoragePanel />

// Server route: POST /api/cloud-storage/presign
{
  "provider": "r2",
  "operation": "upload",
  "endpoint": "https://<account-id>.r2.cloudflarestorage.com",
  "region": "auto",
  "bucket": "atithios-documents",
  "accessKeyId": "...",
  "secretAccessKey": "...",
  "key": "grn/GRN-00042/invoice.pdf",
  "contentType": "application/pdf"
}

// The route uses @aws-sdk/client-s3 and @aws-sdk/s3-request-presigner.
// Store real credentials in a secure vault or server env for production flows.

import { RBACMatrix, type RBACPermissions } from '@/components';

const [permissions, setPermissions] = useState<RBACPermissions>(initialPermissions);

<RBACMatrix
  roles={roles}
  modules={erpModules}
  value={permissions}
  onChange={setPermissions}
/>;

// Standard actions: view, create, edit, approve, delete, export.
// Use module.actions to restrict actions per module, e.g. user management has no approve/export.

// Route: src/app/items/master/page.tsx
// Purpose: reusable ERP master-data screen pattern.

<AppShell
  mode="ITEMS MASTER"
  shortcuts={[
    { key: '/', label: 'Search' },
    { key: 'Alt+N', label: 'New Item' },
    { key: 'Alt+E', label: 'Edit Selected' },
    { key: 'Alt+D', label: 'Delete Selected' },
    { key: 'Alt+X', label: 'Export CSV' },
    { key: 'Enter', label: 'Open/Edit' },
    { key: 'Esc', label: 'Back' },
  ]}
>
  <Input data-search-input placeholder="Search code, item, category, HSN..." />
  <ViewTabs value={stockView} onChange={setStockView} tabs={stockTabs} />
  <DataGrid
    data={filteredItems}
    columns={columns}
    rowKey="id"
    selectedKey={activeItem?.id}
    onActiveRowChange={setActiveItem}
    onRowClick={openItemEditor}
    pagination={{ defaultPageSize: 10, pageSizeOptions: [10, 25, 50, 100] }}
  />
  <ConfirmDialog intent="danger" title="Delete item from master?" />
</AppShell>

// Included behavior:
// - category, search, and stock-state filters
// - active row context panel
// - keyboard row navigation and Enter edit
// - Alt+N, Alt+E, Alt+D, Alt+X actions
// - reusable DataGrid pagination
// - CSV export and delete confirmation

// Route-level error surfaces included in the theme:
src/app/error.tsx              // global runtime error boundary
src/app/not-found.tsx          // 404 route fallback
src/app/error/400/page.tsx     // bad request
src/app/error/403/page.tsx     // access forbidden
src/app/error/500/page.tsx     // server error
src/app/error/503/page.tsx     // service unavailable

// Use cases:
// - 400: invalid request or bad route payload
// - 403: permission issue; includes login recovery
// - 404: unknown route; auto returns to dashboard
// - 500: server/runtime failure with retry and dashboard fallback
// - 503: maintenance or overloaded service
// - AppShell health recovery: offline, slow operation, failed asset, memory pressure

// Rule for production apps:
// keep error pages branded, calm, keyboard-visible, and action-oriented.
// Always provide a primary recovery action and a dashboard fallback.

• AppShell: desktop layout, responsive mobile menu, status bar, loader, health recovery, and shortcuts are documented.
• Core components: cards, buttons, icons, forms, badges, KPIs, grids, editable grids, multilevel grids, pagination, tabs, modals, drawers, toasts, and state blocks are documented with previews.
• ERP documents: invoice, GRN, PO, parties, sections, totals, print, export, and reuse steps are documented.
• Enterprise features: DND layout builder, charts, file/image upload preview, OCR, S3/R2 signing, RBAC, and example pages are documented.
• Application screens: dashboard, Items Master, reports, documents, user management, lazy-load customer balances, and route-level error pages are represented.
• Keyboard system: reusable shortcuts, grid navigation, Mac Command/Option compatibility, Escape rules, and conflict rules are documented.
• Credits: developer credit is centralized in src/lib/credits.ts and shown globally in the status bar.
• Project graph: architecture, route, component, logic, data, and documentation graphs are included for final project handover.

// Visit the full graphified project map.
/project-graph

// Included graph maps:
// 1. Application Architecture
// 2. Route & Module Graph
// 3. Component Dependency Graph
// 4. Logic & Interaction Graph
// 5. Data, Document & Service Flow
// 6. Documentation Coverage Graph

// Each map has:
// - visual nodes
// - relationship edges
// - selected-node details
// - searchable node inventory
// - searchable relationship inventory
// - coverage matrix