@mostrom/app-shell 0.1.0

package/src/components/PageHeader.tsx

@@ -0,0 +1,160 @@
+import React from "react";
+import { cn } from "@/lib/utils";
+
+export interface PageHeaderProps {
+  /** The title text for the header */
+  title: React.ReactNode;
+  /** Optional description text below the title */
+  description?: React.ReactNode;
+  /** Optional counter to display next to the title (e.g., "(42)") */
+  counter?: string | number;
+  /** Optional info link/icon to display next to the title */
+  info?: React.ReactNode;
+  /** Action buttons/elements to display on the right side */
+  actions?: React.ReactNode;
+  /** Header variant controlling the heading level and styling */
+  variant?: "h1" | "h2" | "h3";
+  /** Whether the header should be sticky at the top */
+  sticky?: boolean;
+  /** Additional class name for the header container */
+  className?: string;
+  /** Content to render below the header (e.g., breadcrumbs) */
+  children?: React.ReactNode;
+}
+
+const variantStyles = {
+  h1: "text-2xl font-semibold",
+  h2: "text-xl font-semibold",
+  h3: "text-lg font-medium",
+};
+
+/**
+ * PageHeader - A flexible page header component with title, description, and actions
+ *
+ * Features:
+ * - Multiple heading variants (h1, h2, h3)
+ * - Optional description below title
+ * - Counter display next to title
+ * - Info link/icon slot
+ * - Actions slot for buttons
+ * - Optional sticky positioning
+ */
+export function PageHeader({
+  title,
+  description,
+  counter,
+  info,
+  actions,
+  variant = "h1",
+  sticky = false,
+  className,
+  children,
+}: PageHeaderProps) {
+  const titleContent = (
+    <>
+      {title}
+      {counter !== undefined && (
+        <span className="text-muted-foreground font-normal ml-2">
+          ({counter})
+        </span>
+      )}
+    </>
+  );
+
+  return (
+    <div
+      className={cn(
+        "flex flex-col gap-2",
+        sticky && "sticky top-0 z-10 bg-background py-4 border-b border-border",
+        className
+      )}
+    >
+      {children}
+      <div className="flex items-start justify-between gap-4">
+        <div className="flex flex-col gap-1 min-w-0">
+          <div className="flex items-center gap-2">
+            {variant === "h1" && (
+              <h1 className={cn("text-foreground", variantStyles.h1)}>
+                {titleContent}
+              </h1>
+            )}
+            {variant === "h2" && (
+              <h2 className={cn("text-foreground", variantStyles.h2)}>
+                {titleContent}
+              </h2>
+            )}
+            {variant === "h3" && (
+              <h3 className={cn("text-foreground", variantStyles.h3)}>
+                {titleContent}
+              </h3>
+            )}
+            {info && (
+              <span className="text-muted-foreground">{info}</span>
+            )}
+          </div>
+          {description && (
+            <p className="text-sm text-muted-foreground">{description}</p>
+          )}
+        </div>
+        {actions && (
+          <div className="flex items-center gap-2 shrink-0">
+            {actions}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * PageHeaderTitle - Standalone title component for more custom layouts
+ */
+export function PageHeaderTitle({
+  children,
+  className,
+  variant = "h1",
+}: {
+  children: React.ReactNode;
+  className?: string;
+  variant?: "h1" | "h2" | "h3";
+}) {
+  const classes = cn("text-foreground", variantStyles[variant], className);
+
+  if (variant === "h1") return <h1 className={classes}>{children}</h1>;
+  if (variant === "h2") return <h2 className={classes}>{children}</h2>;
+  return <h3 className={classes}>{children}</h3>;
+}
+
+/**
+ * PageHeaderDescription - Standalone description component
+ */
+export function PageHeaderDescription({
+  children,
+  className,
+}: {
+  children: React.ReactNode;
+  className?: string;
+}) {
+  return (
+    <p className={cn("text-sm text-muted-foreground", className)}>
+      {children}
+    </p>
+  );
+}
+
+/**
+ * PageHeaderActions - Container for action buttons
+ */
+export function PageHeaderActions({
+  children,
+  className,
+}: {
+  children: React.ReactNode;
+  className?: string;
+}) {
+  return (
+    <div className={cn("flex items-center gap-2", className)}>
+      {children}
+    </div>
+  );
+}

package/src/components/data-table/README.md

@@ -0,0 +1,447 @@
+# Data Table
+
+A feature-rich data table component built on TanStack Table with support for sorting, pagination, row selection, column resizing, column reordering (drag & drop), and column pinning.
+
+## Important: Button Placement
+
+**Create/Import/Export buttons should be placed OUTSIDE the table, not in the toolbar.**
+
+The table toolbar should only contain:
+- Search/filter input
+- Column visibility toggle
+- Selection-based bulk actions (e.g., "Delete Selected", "Archive Selected")
+
+Use `CreateButtonGroup` above the table for create/import/export actions:
+
+```tsx
+import {
+  DataGrid,
+  DataTableToolbar,
+  CreateButtonGroup,
+} from "@platform/app-shell/components/data-table"
+
+function MyPage() {
+  return (
+    <div className="space-y-4">
+      {/* Header with Create button OUTSIDE the table */}
+      <div className="flex items-center justify-between">
+        <h1 className="text-xl font-semibold">Items ({data.length})</h1>
+        <CreateButtonGroup
+          createLabel="Create Item"
+          onCreate={() => openCreateModal()}
+          onImport={() => openImportDialog()}
+          onExport={() => exportData()}
+        />
+      </div>
+
+      {/* Table with only table-specific controls */}
+      <DataGrid table={table}>
+        <DataTableToolbar
+          table={table}
+          filterValue={filterText}
+          onFilterChange={setFilterText}
+          bulkActions={
+            selectedCount > 0 && (
+              <Button variant="destructive" size="sm">
+                Delete Selected ({selectedCount})
+              </Button>
+            )
+          }
+        />
+        ...
+      </DataGrid>
+    </div>
+  )
+}
+```
+
+## Installation
+
+The data table components are part of `@platform/app-shell`. Import from the data-table module:
+
+```tsx
+import {
+  DataGrid,
+  DataGridTableDnd,
+  DataGridPagination,
+  DataGridColumnHeader,
+  DataGridTableRowSelect,
+  DataGridTableRowSelectAll,
+  useReactTable,
+  getCoreRowModel,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+} from "@platform/app-shell/components/data-table"
+
+import type {
+  ColumnDef,
+  ColumnOrderState,
+  PaginationState,
+  SortingState,
+  RowSelectionState,
+} from "@platform/app-shell/components/data-table"
+```
+
+For drag & drop functionality, also install:
+
+```bash
+bun add @dnd-kit/core @dnd-kit/sortable
+```
+
+## Basic Usage
+
+```tsx
+import * as React from "react"
+import {
+  DataGrid,
+  DataGridTableDnd,
+  DataGridPagination,
+  DataGridColumnHeader,
+  DataGridTableRowSelect,
+  DataGridTableRowSelectAll,
+  useReactTable,
+  getCoreRowModel,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+} from "@platform/app-shell/components/data-table"
+import type {
+  ColumnDef,
+  ColumnOrderState,
+  PaginationState,
+  SortingState,
+  RowSelectionState,
+} from "@platform/app-shell/components/data-table"
+import type { DragEndEvent } from "@dnd-kit/core"
+import { arrayMove } from "@dnd-kit/sortable"
+import { Card, CardFooter } from "@platform/app-shell/components/ui/card"
+import { ScrollArea, ScrollBar } from "@platform/app-shell/components/ui/scroll-area"
+
+interface DataRow {
+  id: string
+  name: string
+  email: string
+}
+
+export function MyTable({ data }: { data: DataRow[] }) {
+  // Table state
+  const [pagination, setPagination] = React.useState<PaginationState>({
+    pageIndex: 0,
+    pageSize: 10,
+  })
+  const [sorting, setSorting] = React.useState<SortingState>([])
+  const [rowSelection, setRowSelection] = React.useState<RowSelectionState>({})
+  const [columnOrder, setColumnOrder] = React.useState<ColumnOrderState>([
+    "select",
+    "name",
+    "email",
+  ])
+
+  // Handle column drag and drop
+  const handleDragEnd = (event: DragEndEvent) => {
+    const { active, over } = event
+    if (active && over && active.id !== over.id) {
+      setColumnOrder((columnOrder) => {
+        const oldIndex = columnOrder.indexOf(active.id as string)
+        const newIndex = columnOrder.indexOf(over.id as string)
+        return arrayMove(columnOrder, oldIndex, newIndex)
+      })
+    }
+  }
+
+  // Define columns
+  const columns = React.useMemo<ColumnDef<DataRow>[]>(
+    () => [
+      {
+        id: "select",
+        header: () => <DataGridTableRowSelectAll />,
+        cell: ({ row }) => <DataGridTableRowSelect row={row} />,
+        size: 40,
+        enableSorting: false,
+        enableHiding: false,
+        enableResizing: false,
+        enableColumnOrdering: false, // Disable dragging for this column
+      },
+      {
+        accessorKey: "name",
+        id: "name",
+        header: ({ column }) => (
+          <DataGridColumnHeader title="Name" column={column} />
+        ),
+        cell: ({ row }) => row.original.name,
+        size: 200,
+        enableSorting: true,
+        enableHiding: false,
+        enableResizing: true,
+        meta: {
+          headerTitle: "Name",
+        },
+      },
+      {
+        accessorKey: "email",
+        id: "email",
+        header: ({ column }) => (
+          <DataGridColumnHeader title="Email" column={column} />
+        ),
+        cell: ({ row }) => row.original.email,
+        size: 250,
+        enableSorting: true,
+        enableHiding: true,
+        enableResizing: true,
+        meta: {
+          headerTitle: "Email",
+        },
+      },
+    ],
+    []
+  )
+
+  // Create table instance
+  const table = useReactTable({
+    columns,
+    data,
+    pageCount: Math.ceil(data.length / pagination.pageSize),
+    getRowId: (row) => row.id,
+    state: {
+      pagination,
+      sorting,
+      rowSelection,
+      columnOrder,
+    },
+    enableRowSelection: true,
+    columnResizeMode: "onChange",
+    onPaginationChange: setPagination,
+    onSortingChange: setSorting,
+    onRowSelectionChange: setRowSelection,
+    onColumnOrderChange: setColumnOrder,
+    getCoreRowModel: getCoreRowModel(),
+    getFilteredRowModel: getFilteredRowModel(),
+    getPaginationRowModel: getPaginationRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+  })
+
+  return (
+    <DataGrid
+      table={table}
+      recordCount={data.length}
+      tableLayout={{
+        columnsResizable: true,
+        columnsMovable: true,
+        columnsDraggable: true,
+        columnsPinnable: true,
+        columnsVisibility: true,
+      }}
+    >
+      <Card className="w-full gap-3 py-3.5">
+        {/* Table */}
+        <div className="w-full border-y">
+          <ScrollArea>
+            <DataGridTableDnd handleDragEnd={handleDragEnd} />
+            <ScrollBar orientation="horizontal" />
+          </ScrollArea>
+        </div>
+
+        {/* Pagination */}
+        <CardFooter className="border-none bg-transparent px-3.5 py-0">
+          <DataGridPagination sizes={[10, 20, 50]} />
+        </CardFooter>
+      </Card>
+    </DataGrid>
+  )
+}
+```
+
+## Components
+
+### DataGrid
+
+The main wrapper component that provides context to all child components.
+
+```tsx
+<DataGrid
+  table={table}              // TanStack table instance
+  recordCount={data.length}  // Total number of records
+  tableLayout={{
+    dense: false,            // Compact row height
+    columnsResizable: true,  // Enable column resizing
+    columnsMovable: true,    // Enable column reordering via menu
+    columnsDraggable: true,  // Enable drag & drop column reordering
+    columnsPinnable: true,   // Enable column pinning
+    columnsVisibility: true, // Enable column visibility toggle
+  }}
+>
+  {children}
+</DataGrid>
+```
+
+### DataGridTableDnd
+
+The table component with drag & drop support for column reordering.
+
+```tsx
+<DataGridTableDnd handleDragEnd={handleDragEnd} />
+```
+
+### DataGridColumnHeader
+
+Column header with sorting controls and dropdown menu for column actions.
+
+```tsx
+<DataGridColumnHeader
+  title="Column Name"
+  column={column}
+  icon={<IconComponent />}  // Optional icon
+  pinnable={true}           // Enable pinning option in menu
+  visibility={true}         // Show column visibility in menu
+  filter={<FilterComponent />}  // Optional filter component
+/>
+```
+
+### DataGridTableRowSelect / DataGridTableRowSelectAll
+
+Row selection checkboxes.
+
+```tsx
+// In header
+header: () => <DataGridTableRowSelectAll />
+
+// In cell
+cell: ({ row }) => <DataGridTableRowSelect row={row} />
+```
+
+### DataGridPagination
+
+Pagination controls with page size selector.
+
+```tsx
+<DataGridPagination sizes={[10, 20, 50]} />
+```
+
+### CreateButtonGroup
+
+Button group for create/import/export actions. **Place this ABOVE the table, not in the toolbar.**
+
+```tsx
+<CreateButtonGroup
+  createLabel="Create Item"      // Primary button label
+  onCreate={() => {}}            // Primary action handler
+  importLabel="Import"           // Optional, defaults to "Import"
+  onImport={() => {}}            // Import action handler
+  exportLabel="Export"           // Optional, defaults to "Export"
+  onExport={() => {}}            // Export action handler
+  showDropdown={true}            // Show dropdown, defaults to true
+  additionalItems={[             // Optional extra dropdown items
+    {
+      id: "bulk-create",
+      label: "Bulk Create",
+      onClick: () => {},
+    },
+  ]}
+/>
+```
+
+### DataTableToolbar
+
+Toolbar for table-specific controls. The `bulkActions` prop is for selection-based actions only.
+
+```tsx
+<DataTableToolbar
+  table={table}
+  filterValue={filterText}
+  onFilterChange={setFilterText}
+  filterPlaceholder="Search items..."
+  showColumnVisibility={true}
+  selectedCount={selectedCount}
+  totalCount={data.length}
+  bulkActions={
+    selectedCount > 0 && (
+      <Button variant="destructive" size="sm">
+        Delete Selected ({selectedCount})
+      </Button>
+    )
+  }
+/>
+```
+
+## Column Definition Options
+
+```tsx
+{
+  id: "columnId",
+  accessorKey: "dataField",
+  header: ({ column }) => <DataGridColumnHeader title="Title" column={column} />,
+  cell: ({ row }) => row.original.field,
+  size: 200,                    // Column width in pixels
+  enableSorting: true,          // Allow sorting
+  enableHiding: true,           // Allow hiding via visibility toggle
+  enableResizing: true,         // Allow resizing
+  enableColumnOrdering: true,   // Allow drag reordering (default: true)
+  meta: {
+    headerTitle: "Display Name", // Used in column visibility menu
+    cellClassName: "custom-class",
+    headerClassName: "custom-class",
+  },
+}
+```
+
+## Table Layout Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `dense` | boolean | false | Use compact row height |
+| `columnsResizable` | boolean | false | Enable column resizing |
+| `columnsMovable` | boolean | false | Enable move left/right in column menu |
+| `columnsDraggable` | boolean | false | Enable drag & drop column reordering |
+| `columnsPinnable` | boolean | false | Enable column pinning (left/right) |
+| `columnsVisibility` | boolean | false | Enable column visibility toggle |
+| `rowBorder` | boolean | true | Show row borders |
+| `cellBorder` | boolean | false | Show cell borders |
+| `stripped` | boolean | false | Alternating row colors |
+| `headerSticky` | boolean | false | Sticky header on scroll |
+
+## Disabling Drag on Specific Columns
+
+To prevent a column from being draggable (e.g., selection checkbox column):
+
+```tsx
+{
+  id: "select",
+  enableColumnOrdering: false, // This column cannot be dragged
+  // ...
+}
+```
+
+## Selection Counter in Header
+
+Display selection count in the table header instead of a separate line:
+
+```tsx
+const selectedCount = Object.keys(rowSelection).length
+
+<div className="text-xl font-semibold">
+  Items
+  <span className="text-muted-foreground font-normal">
+    {" "}({selectedCount > 0 ? `${selectedCount}/${data.length}` : data.length})
+  </span>
+</div>
+```
+
+This shows:
+- `Items (10)` when no rows selected
+- `Items (3/10)` when 3 of 10 rows selected
+
+## Styling
+
+The table inherits from the app's theme. Common customizations:
+
+```tsx
+// Italic placeholder in search input
+<Input
+  placeholder="Search..."
+  className="placeholder:italic"
+/>
+
+// Custom badge sizes in cells
+<Badge variant="outline">{tag}</Badge>  // Uses default size (text-xs)
+```