team-cocoon

A comprehensive collection of reusable, generic data view components for React/Next.js applications. Built with TypeScript, TanStack Table, and Tailwind CSS.

Features

• Multiple View Types: Grid, Table, Calendar, Pivot Table, Charts, Map
• Advanced Filtering: Faceted filters, custom filters, quick filters, date range filters
• Grouping & Aggregation: Multi-level grouping, nested tables, pivot tables with transforms
• Row Actions: Edit, Delete, Favorite, Custom actions
• Bulk Operations: Selection toolbar with configurable bulk actions
• Infinite Scroll: Optional infinite scrolling for grid views
• Responsive Design: Mobile-first, fully responsive components
• Type-Safe: Full TypeScript support with generic types
• Customizable: Extensive configuration options and render props
• Accessible: Built on Radix UI primitives

Installation

npm install team-cocoon

Peer Dependencies

This package requires the following peer dependencies:

npm install react react-dom next @tanstack/react-table @tanstack/react-query tailwindcss

Tailwind Configuration

Add the package to your Tailwind CSS configuration:

// tailwind.config.js
module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx}",
    "./components/**/*.{js,ts,jsx,tsx}",
    "./node_modules/team-cocoon/dist/**/*.{js,mjs}",
  ],
  theme: {
    extend: {
      // Your custom theme
    },
  },
  plugins: [],
};

Quick Start

import { GenericView } from "team-cocoon";
import type { ColumnConfig, BaseEntity } from "team-cocoon";

interface Project extends BaseEntity {
  id: string;
  name: string;
  status: string;
  priority: string;
  createdAt: Date;
}

export default function ProjectsPage() {
  const { data, isLoading } = useProjects(); // Your data fetching

  const columns: ColumnConfig<Project>[] = [
    {
      id: "name",
      header: "Project Name",
      accessorKey: "name",
      type: "text",
    },
    {
      id: "status",
      header: "Status",
      accessorKey: "status",
      type: "badge",
    },
    {
      id: "priority",
      header: "Priority",
      accessorKey: "priority",
      type: "badge",
    },
  ];

  return (
    <GenericView
      data={data || []}
      isLoading={isLoading}
      columns={columns}
      renderCard={(project) => (
        <div className="p-4 border rounded-lg">
          <h3 className="font-semibold">{project.name}</h3>
          <p className="text-sm text-muted-foreground">{project.status}</p>
        </div>
      )}
      defaultView="grid"
      enabledViews={["grid", "list"]}
    />
  );
}

Components

GenericView

The main orchestrator component that manages all view types and toolbar interactions.

<GenericView
  data={items}
  isLoading={isLoading}
  columns={columns}
  filters={filters}
  actions={actions}
  renderCard={renderCard}
  defaultView="grid"
  enabledViews={["grid", "list", "calendar", "pivot"]}
  toolbar={{
    primaryAction: {
      label: "Add Project",
      onClick: handleAdd,
    },
  }}
/>

GenericGrid

Grid view with optional infinite scroll.

<GenericGrid
  data={items}
  renderCard={renderCard}
  columns={3}
  gap={4}
  enableInfiniteScroll
  initialCount={12}
  loadIncrement={12}
/>

GenericTable

Advanced table with sorting, filtering, and column management.

<GenericTable
  data={items}
  columns={columns}
  filters={filters}
  actions={actions}
  showRowSelection
  enableBulkActions
/>

GenericCalendarView

Calendar view with event management.

<GenericCalendarView
  items={items}
  calendarConfig={{
    enabled: true,
    getEventDate: (item) => new Date(item.startDate),
    getEventTitle: (item) => item.title,
    getEventColor: (item) => item.color,
  }}
/>

GenericPivotView

Interactive pivot table with drag-and-drop field configuration.

<GenericPivotView
  items={items}
  pivotConfig={{
    enabled: true,
    defaultRows: ["category"],
    defaultColumns: ["status"],
    defaultValues: ["amount"],
    aggregation: "sum",
  }}
/>

Type Definitions

BaseEntity

All data items must extend BaseEntity:

interface BaseEntity {
  id: string | number;
  [key: string]: any;
}

ColumnConfig

Define columns with rich configuration:

interface ColumnConfig<T extends BaseEntity> {
  id: string;
  header: string;
  accessorKey: keyof T;
  type?: "text" | "number" | "date" | "badge" | "boolean" | "link";
  cell?: (value: any, item: T) => React.ReactNode;
  enableSorting?: boolean;
  enableColumnFilter?: boolean;
  meta?: {
    width?: string;
    className?: string;
  };
}

ActionConfig

Configure row actions:

interface ActionConfig<T extends BaseEntity> {
  edit?: {
    enabled: boolean;
    onEdit: (item: T) => void;
    label?: string;
  };
  delete?: {
    enabled: boolean;
    onDelete: (item: T) => Promise<void>;
    label?: string;
  };
  favorite?: {
    enabled: boolean;
    fieldName: keyof T;
    onToggle: (item: T) => Promise<void>;
  };
  custom?: Array<{
    label: string;
    icon?: React.ComponentType;
    onClick: (item: T) => void;
    variant?: "default" | "destructive";
  }>;
}

Advanced Features

Grouping

Enable multi-level grouping:

<GenericView
  data={items}
  columns={columns}
  groupByOptions={[
    { value: "status", label: "Status" },
    { value: "priority", label: "Priority" },
    { value: "assignee", label: "Assignee" },
  ]}
/>

Custom Filters

Add custom filter fields:

<GenericView
  data={items}
  columns={columns}
  customFilterFields={[
    {
      id: "dateRange",
      label: "Date Range",
      type: "dateRange",
      apply: (items, value) =>
        items.filter(
          (item) =>
            item.date >= value.from && item.date <= value.to
        ),
    },
  ]}
/>

Bulk Actions

Enable bulk operations on selected rows:

<GenericView
  data={items}
  columns={columns}
  enableBulkActions
  advancedToolbar={{
    bulkActions: [
      {
        label: "Delete Selected",
        icon: Trash,
        onClick: async (items) => {
          await deleteMultiple(items);
        },
        variant: "destructive",
      },
    ],
  }}
/>

Sheet Integration

Add/Edit forms in a side sheet:

<GenericView
  data={items}
  columns={columns}
  sheetConfig={{
    addTitle: "Add Project",
    editTitle: "Edit Project",
    viewTitle: "View Project",
    renderForm: (entity, mode) => (
      <ProjectForm
        project={entity}
        mode={mode}
        onSave={handleSave}
      />
    ),
  }}
/>

Hooks

useEntityModal

Manage modal/sheet state:

const { isOpen, selectedEntity, mode, openAddModal, openEditModal, closeModal } =
  useEntityModal<Project>();

useGenericGrouping

Handle data grouping:

const groupedData = useGenericGrouping({
  table,
  groupBy: ["status", "priority"],
  lang: "en",
});

usePivotData

Generate pivot table data:

const { pivotData, isLoading } = usePivotData({
  items,
  rowFields: ["category"],
  columnFields: ["status"],
  valueField: "amount",
  aggregation: "sum",
});

Styling

The package uses Tailwind CSS for styling. Ensure your project has the required CSS variables defined:

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --card: 0 0% 100%;
    --card-foreground: 222.2 84% 4.9%;
    --popover: 0 0% 100%;
    --popover-foreground: 222.2 84% 4.9%;
    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96.1%;
    --secondary-foreground: 222.2 47.4% 11.2%;
    --muted: 210 40% 96.1%;
    --muted-foreground: 215.4 16.3% 46.9%;
    --accent: 210 40% 96.1%;
    --accent-foreground: 222.2 47.4% 11.2%;
    --destructive: 0 84.2% 60.2%;
    --destructive-foreground: 210 40% 98%;
    --border: 214.3 31.8% 91.4%;
    --input: 214.3 31.8% 91.4%;
    --ring: 222.2 84% 4.9%;
    --radius: 0.5rem;
  }
}

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Support

For issues and questions, please open an issue on GitHub.