@create-lft-app/nextjs 3.1.0 → 3.3.0

package/template/CLAUDE.md

@@ -1,279 +1,114 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+## Project Overview
 
-## 🚨 CRITICAL: MANDATORY ARCHITECTURAL PATTERN 🚨
+Next.js application with Supabase backend, following a feature-based modular architecture with mandatory Repository Pattern.
 
-**⚠️ BEFORE WRITING ANY CODE, YOU MUST READ AND FOLLOW THIS PATTERN ⚠️**
+## Tech Stack
 
-This section is **NON-NEGOTIABLE** and MUST be followed in **100% of cases** when creating or modifying features in this codebase.
-
-## ⚠️ The Most Common Mistake (DON'T DO THIS!)
-
-```typescript
-// ❌ WRONG - NEVER IMPORT MUTATIONS OR QUERIES DIRECTLY IN COMPONENTS
-import { useEntityMutations } from '@/modules/[entity]/hooks/useEntityMutations'
-import { useEntityQueries } from '@/modules/[entity]/hooks/useEntityQueries'
-
-export function MyComponent() {
-  const { createEntity } = useEntityMutations() // ❌ ARCHITECTURAL VIOLATION
-  const { entities } = useEntityQueries() // ❌ ARCHITECTURAL VIOLATION
-}
-
-// ✅ CORRECT - ALWAYS USE THE UNIFIED HOOK
-import { useEntity } from '@/modules/[entity]/hooks/useEntity'
-
-export function MyComponent() {
-  const { createEntity, entities } = useEntity() // ✅ CORRECT PATTERN
-}
-```
-
-## 🚨 MANDATORY Pattern: Store → Queries → Mutations → Unified Hook → Component
-
-**THIS IS THE ONLY ACCEPTABLE ARCHITECTURE FOR THIS CODEBASE.**
-
-Every module MUST follow this exact structure:
-
-```
-modules/
-└── [entity]/
-    ├── actions/
-    │   └── [entity]-actions.ts          # Server actions with RLS
-    ├── components/
-    │   ├── [entity]-list.tsx            # Component imports ONLY unified hook
-    │   ├── [entity]-form.tsx
-    │   └── [entity]-detail.tsx
-    ├── hooks/
-    │   ├── use[Entity]Queries.ts        # TanStack Query (read operations)
-    │   ├── use[Entity]Mutations.ts      # TanStack Mutations (write operations)
-    │   └── use[Entity].ts               # UNIFIED HOOK (components use THIS)
-    ├── stores/
-    │   └── use[Entity]Store.ts          # Zustand store (UI state only)
-    ├── schemas/
-    │   └── [entity].schema.ts           # Zod validation schemas
-    ├── columns.tsx                      # TanStack Table column definitions (if needed)
-    └── index.ts                         # Barrel export
-```
-
-## 📋 Mandatory Implementation Checklist
-
-Before writing ANY code, verify this checklist:
-
-- [ ] **Step 1**: Create Drizzle schema in `db/schema/[entity].ts`
-- [ ] **Step 2**: Create Zod schemas in `modules/[entity]/schemas/[entity].schema.ts`
-- [ ] **Step 3**: Create Server actions in `modules/[entity]/actions/[entity]-actions.ts`
-- [ ] **Step 4**: Create Zustand store with separate state/actions selectors using `useShallow` in `modules/[entity]/stores/`
-- [ ] **Step 5**: Create Queries hook in `modules/[entity]/hooks/use[Entity]Queries.ts`
-- [ ] **Step 6**: Create Mutations hook with cache invalidation in `modules/[entity]/hooks/use[Entity]Mutations.ts`
-- [ ] **Step 7**: Create Unified hook that combines store + queries + mutations in `modules/[entity]/hooks/use[Entity].ts`
-- [ ] **Step 8**: Components ONLY import the unified hook (NEVER queries/mutations directly)
-- [ ] **Step 9**: Test with `pnpm typecheck && pnpm lint` before committing
-
-## 🔴 NEVER DO THIS (Anti-Patterns)
-
-```typescript
-// ❌ NEVER: Import queries or mutations directly in components
-import { useEntityQueries } from '@/modules/[entity]/hooks/useEntityQueries'
-import { useEntityMutations } from '@/modules/[entity]/hooks/useEntityMutations'
-
-// ❌ NEVER: Consume entire store (causes re-renders)
-const store = useEntityStore()
-
-// ❌ NEVER: Manual data fetching in useEffect
-useEffect(() => {
-  fetch('/api/entities').then(setData)
-}, [])
+- **Framework**: Next.js 16 (App Router)
+- **State Management**: Zustand 5
+- **Data Fetching**: TanStack Query 5
+- **Tables**: TanStack Table 8
+- **Database**: Supabase + Drizzle ORM
+- **Auth**: Supabase Auth (with Admin API for user management)
+- **Validation**: Zod
+- **UI**: Radix UI + Tailwind CSS
+- **Forms**: React Hook Form + Zod resolver
+- **Excel**: xlsx (SheetJS)
+- **Dates**: dayjs
+- **Package Manager**: pnpm
 
-// ❌ NEVER: Server actions without authenticated user context (RLS won't work)
-export async function deleteEntity(id: string) {
-  const supabase = createClient() // Anonymous client - RLS will fail!
-  await supabase.from('entities').delete().eq('id', id)
-}
+## Commands
+
+```bash
+pnpm dev          # Start development server
+pnpm build        # Production build
+pnpm typecheck    # Run TypeScript type checking
+pnpm lint         # Run ESLint
+pnpm db:generate  # Generate Drizzle migrations after schema changes
+pnpm db:migrate   # Apply pending migrations
+pnpm db:push      # Dev only — sync schema directly
+pnpm db:studio    # Inspect data visually
+pnpm db:seed      # Populate database with seed data
 ```
 
-## ✅ ALWAYS DO THIS (Correct Patterns)
-
-```typescript
-// ✅ ALWAYS: Use the unified hook in components
-import { useEntity } from '@/modules/[entity]/hooks/useEntity'
-
-// ✅ ALWAYS: Use separate selectors with useShallow
-import { useEntityStore } from '@/modules/[entity]/stores/useEntityStore'
-import { useShallow } from 'zustand/react/shallow'
-
-const state = useEntityStore(useShallow((s) => s.state))
-const actions = useEntityStore(useShallow((s) => s.actions))
-
-// ✅ ALWAYS: Use TanStack Query for data fetching
-const { data } = useQuery({ queryKey: ['entities'], queryFn: fetchEntities })
-
-// ✅ ALWAYS: Use authenticated Supabase client in server actions (RLS enforced)
-'use server'
-
-import { createClient } from '@/lib/supabase/server'
-
-export async function deleteEntity(id: string) {
-  const supabase = await createClient() // Authenticated client with user context
-  const { data: { user } } = await supabase.auth.getUser()
+> **Always run `pnpm typecheck && pnpm lint` before committing.**
 
-  if (!user) throw new Error('Unauthorized')
-
-  // RLS policies will automatically enforce authorization
-  const { error } = await supabase.from('entities').delete().eq('id', id)
-
-  if (error) throw error
-}
-```
-
-## 📁 Complete Project Structure
+## Project Structure
 
 ```
 src/
 ├── app/
-│   ├── (auth)/                          # Rutas autenticadas
+│   ├── (auth)/                    # Authenticated routes (layout with Sidebar)
 │   │   ├── dashboard/
-│   │   │   └── page.tsx
+│   │   ├── users/                 # Each section: layout.tsx with SecondaryMenu
+│   │   ├── settings/
 │   │   └── layout.tsx
-│   ├── (public)/                        # Rutas públicas
-│   │   ├── login/
-│   │   │   └── page.tsx
-│   │   └── layout.tsx
-│   ├── api/
-│   │   └── webhooks/
-│   │       └── route.ts
+│   ├── (public)/                  # Public routes
+│   │   └── login/
+│   ├── api/webhooks/
 │   ├── layout.tsx
 │   ├── page.tsx
 │   └── providers.tsx
 │
-├── modules/                             # Feature-based modules
-│   ├── auth/
-│   │   ├── actions/
-│   │   │   └── auth-actions.ts
-│   │   ├── components/
-│   │   │   └── login-form.tsx
-│   │   ├── hooks/
-│   │   │   ├── useAuthQueries.ts
-│   │   │   ├── useAuthMutations.ts
-│   │   │   └── useAuth.ts
-│   │   ├── stores/
-│   │   │   └── useAuthStore.ts
-│   │   ├── schemas/
-│   │   │   └── auth.schema.ts
-│   │   └── index.ts
-│   └── users/
-│       ├── actions/
-│       │   └── users-actions.ts
-│       ├── components/
-│       │   ├── users-list.tsx
-│       │   ├── users-form.tsx
-│       │   └── users-detail.tsx
-│       ├── hooks/
-│       │   ├── useUsersQueries.ts
-│       │   ├── useUsersMutations.ts
-│       │   └── useUsers.ts
-│       ├── stores/
-│       │   └── useUsersStore.ts
-│       ├── schemas/
-│       │   └── users.schema.ts
-│       ├── columns.tsx
-│       └── index.ts
+├── modules/                       # Feature-based modules (see skill: module-architecture)
+│   ├── auth/                      # Auth module (login, session)
+│   └── users/                     # Users module (Supabase Admin API)
+│   # New modules follow: repository → actions → hooks → components
 │
 ├── components/
-│   ├── ui/                              # Radix custom components
-│   │   ├── button.tsx
-│   │   ├── dialog.tsx
-│   │   └── index.ts
-│   ├── tables/                          # TanStack Table components
-│   │   ├── data-table.tsx
-│   │   ├── data-table-pagination.tsx
-│   │   ├── data-table-toolbar.tsx
-│   │   ├── data-table-column-header.tsx
-│   │   └── index.ts
-│   ├── layout/
-│   │   ├── header.tsx
-│   │   └── sidebar.tsx
+│   ├── ui/                        # Radix custom components
+│   ├── tables/                    # TanStack Table (data-table, pagination, filters)
+│   ├── layout/                    # header, sidebar, secondary-menu, page-header
 │   └── shared/
-│       └── ...
-│
-├── stores/                              # Global Zustand stores
-│   ├── useUiStore.ts
-│   └── index.ts
 │
-├── hooks/                               # Global hooks
-│   ├── useMediaQuery.ts
-│   ├── useDebounce.ts
-│   └── useDataTable.ts
+├── stores/                        # Global Zustand stores
+├── hooks/                         # Global hooks (useMediaQuery, useDebounce, useDataTable)
 │
 ├── lib/
-│   ├── supabase/
-│   │   ├── client.ts
-│   │   ├── server.ts
-│   │   ├── proxy.ts
-│   │   └── types.ts
-│   ├── excel/
-│   │   ├── parser.ts
-│   │   ├── exporter.ts
-│   │   └── index.ts
-│   ├── date/
-│   │   ├── config.ts
-│   │   ├── formatters.ts
-│   │   └── index.ts
+│   ├── supabase/                  # client.ts, server.ts, admin.ts
+│   ├── excel/                     # parser.ts, exporter.ts
+│   ├── date/                      # config.ts (locale/timezone/currency), formatters.ts
 │   ├── validations/
-│   │   ├── common.ts
-│   │   └── index.ts
 │   ├── query-client.ts
 │   └── utils.ts
 │
-├── db/
-│   ├── schema/
-│   │   ├── users.ts
-│   │   └── index.ts
+├── db/                            # Drizzle ORM (see skill: drizzle-schema)
+│   ├── schema/                    # Schema per entity + barrel index.ts
 │   ├── migrations/
-│   ├── index.ts
+│   ├── index.ts                   # Exports `db` (Drizzle client)
 │   └── seed.ts
 │
 ├── types/
-│   ├── api.ts
-│   ├── table.ts
-│   └── index.ts
-│
 ├── config/
 │   ├── site.ts
-│   └── navigation.ts
+│   ├── navigation.ts              # Sidebar structure with children
+│   └── roles.ts                   # Single source of truth for roles
 │
 └── styles/
     └── globals.css
-
-supabase/
-├── functions/
-│   ├── process-excel/
-│   │   └── index.ts
-│   └── send-notification/
-│       └── index.ts
-├── migrations/
-└── config.toml
-
-# Root files
-├── .env.local
-├── .env.example
-├── drizzle.config.ts
-├── proxy.ts
-├── next.config.ts
-├── package.json
-├── tsconfig.json
-└── tailwind.config.ts
 ```
 
-## 🛠️ Tech Stack
-
-- **Framework**: Next.js 16 (App Router)
-- **State Management**: Zustand 5
-- **Data Fetching**: TanStack Query 5
-- **Tables**: TanStack Table 8
-- **Database**: Supabase + Drizzle ORM
-- **Validation**: Zod
-- **UI**: Radix UI + Tailwind CSS
-- **Forms**: React Hook Form + Zod resolver
-- **Excel**: xlsx (SheetJS)
-- **Dates**: dayjs
-- **Package Manager**: pnpm
+## Key Conventions
+
+- **Mandatory architecture**: `Repository → Actions → Queries → Mutations → Unified Hook → Component` (see skill: module-architecture)
+- **Components NEVER import queries or mutations directly** — they use the unified hook
+- **Server actions use `requireAuth()`** and call repositories, never `db` directly (see skill: supabase-server-actions)
+- **Repository Pattern is mandatory** for entities with own tables (see skill: drizzle-schema)
+- **Zustand stores = UI state only**, consumed with `useShallow` selectors
+- **No modals for CRUD** — use full pages (`/new`, `/[id]/edit`) (see skill: ui-patterns)
+- **Dates via `@/lib/date`**, numbers via `DEFAULT_LOCALE` (see skill: formatting)
+- **Roles centralized** in `config/roles.ts` (see skill: supabase-server-actions)
+- **See skill: anti-patterns** for common mistakes to avoid
+
+## Skills Reference
+
+| Skill | What it covers |
+|-------|---------------|
+| `module-architecture` | Module structure, layer architecture, implementation checklist, unified hook, Zustand store |
+| `anti-patterns` | All prohibited patterns with wrong/correct examples |
+| `supabase-server-actions` | Server actions, auth clients, Admin API, roles, mutations integration |
+| `drizzle-schema` | Schema conventions, repository pattern, commands, migration workflow |
+| `formatting` | dayjs date functions, number formatting, locale/currency config |
+| `ui-patterns` | Design philosophy, page architecture, navigation, SecondaryMenu, spacing |

package/template/src/components/layout/sidebar.tsx

@@ -24,11 +24,6 @@ const navItems: NavItem[] = [
 		name: 'Usuarios',
 		icon: 'Users',
 	},
-	{
-		path: '/settings',
-		name: 'Configuración',
-		icon: 'Settings',
-	},
 ]
 
 function MenuItem({
@@ -52,9 +47,9 @@ function MenuItem({
 					'mx-[10px] px-[10px]',
 					'rounded-md',
 					'transition-all duration-150',
-					!isActive && 'hover:bg-[#f7f7f7] dark:hover:bg-[#1a1a1a]',
+					!isActive && 'hover:bg-accent',
 					isActive && [
-						'bg-[#f7f7f7] dark:bg-[#131313]',
+						'bg-accent',
 						'border border-border',
 					]
 				)}
@@ -64,7 +59,7 @@ function MenuItem({
 						size={20}
 						className={cn(
 							'transition-colors',
-							isActive ? 'text-foreground' : 'text-[#878787]'
+							isActive ? 'text-foreground' : 'text-muted-foreground'
 						)}
 					/>
 				</div>
@@ -73,7 +68,7 @@ function MenuItem({
 						className={cn(
 							'text-sm whitespace-nowrap',
 							'transition-all duration-150',
-							isActive ? 'font-medium text-foreground' : 'text-[#878787]'
+							isActive ? 'font-medium text-foreground' : 'text-muted-foreground'
 						)}
 					>
 						{item.name}

package/template/src/components/tables/data-table-date-filter.tsx

@@ -0,0 +1,203 @@
+'use client'
+
+import * as React from 'react'
+import { Column } from '@tanstack/react-table'
+import { CalendarIcon, X } from 'lucide-react'
+import { DateRange } from 'react-day-picker'
+
+import { cn } from '@/lib/utils'
+import { formatDateShort } from '@/lib/date'
+import { Button } from '@/components/ui/button'
+import { Calendar } from '@/components/ui/calendar'
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from '@/components/ui/popover'
+
+interface DataTableDateFilterProps<TData> {
+  column?: Column<TData, unknown>
+  title?: string
+}
+
+export function DataTableDateFilter<TData>({
+  column,
+  title = 'Fecha',
+}: DataTableDateFilterProps<TData>) {
+  const filterValue = column?.getFilterValue() as DateRange | undefined
+  const [open, setOpen] = React.useState(false)
+
+  // Sincronizar estado local con el filtro de la columna
+  // Esto permite que "Limpiar" del toolbar resetee este filtro
+  React.useEffect(() => {
+    if (!filterValue) {
+      setDate(undefined)
+    }
+  }, [filterValue])
+
+  const [date, setDate] = React.useState<DateRange | undefined>(filterValue)
+
+  const handleSelect = (range: DateRange | undefined) => {
+    setDate(range)
+    // No aplicamos el filtro inmediatamente, esperamos al botón Aplicar
+  }
+
+  const handleApply = () => {
+    column?.setFilterValue(date)
+    setOpen(false)
+  }
+
+  const handleClear = () => {
+    setDate(undefined)
+    column?.setFilterValue(undefined)
+  }
+
+  const handleOpenChange = (isOpen: boolean) => {
+    if (!isOpen) {
+      // Al cerrar sin aplicar, resetear al valor actual del filtro
+      setDate(filterValue)
+    }
+    setOpen(isOpen)
+  }
+
+  const hasFilter = date?.from || date?.to
+
+  return (
+    <Popover open={open} onOpenChange={handleOpenChange}>
+      <PopoverTrigger asChild>
+        <Button
+          variant="outline"
+          size="sm"
+          className={cn(
+            'h-8 border-dashed',
+            hasFilter && 'border-solid'
+          )}
+        >
+          <CalendarIcon className="mr-2 h-4 w-4" />
+          {hasFilter ? (
+            <span className="flex items-center gap-1">
+              {date?.from && formatDateShort(date.from)}
+              {date?.to && ` - ${formatDateShort(date.to)}`}
+            </span>
+          ) : (
+            title
+          )}
+          {hasFilter && (
+            <span
+              role="button"
+              tabIndex={0}
+              onClick={(e) => {
+                e.stopPropagation()
+                handleClear()
+              }}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter' || e.key === ' ') {
+                  e.stopPropagation()
+                  handleClear()
+                }
+              }}
+              className="ml-2 rounded-full p-0.5 hover:bg-muted"
+            >
+              <X className="h-3 w-3" />
+            </span>
+          )}
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent
+        className="w-auto p-0"
+        side="bottom"
+        align="start"
+        sideOffset={4}
+      >
+        <div className="flex flex-col">
+          <div className="flex items-center gap-2 border-b border-border p-3">
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-7 text-xs"
+              onClick={() => {
+                const today = new Date()
+                setDate({ from: today, to: today })
+              }}
+            >
+              Hoy
+            </Button>
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-7 text-xs"
+              onClick={() => {
+                const today = new Date()
+                const weekAgo = new Date(today)
+                weekAgo.setDate(today.getDate() - 7)
+                setDate({ from: weekAgo, to: today })
+              }}
+            >
+              Última semana
+            </Button>
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-7 text-xs"
+              onClick={() => {
+                const today = new Date()
+                const monthAgo = new Date(today)
+                monthAgo.setMonth(today.getMonth() - 1)
+                setDate({ from: monthAgo, to: today })
+              }}
+            >
+              Último mes
+            </Button>
+          </div>
+          <Calendar
+            mode="range"
+            defaultMonth={date?.from}
+            selected={date}
+            onSelect={handleSelect}
+            numberOfMonths={2}
+          />
+          <div className="flex gap-2 border-t border-border p-3">
+            <Button
+              variant="outline"
+              size="sm"
+              className="flex-1"
+              onClick={handleClear}
+            >
+              Limpiar
+            </Button>
+            <Button
+              size="sm"
+              className="flex-1"
+              onClick={handleApply}
+            >
+              Aplicar
+            </Button>
+          </div>
+        </div>
+      </PopoverContent>
+    </Popover>
+  )
+}
+
+// Filter function para usar con TanStack Table
+export function dateRangeFilterFn<TData>(
+  row: { getValue: (id: string) => unknown },
+  columnId: string,
+  filterValue: DateRange | undefined
+): boolean {
+  if (!filterValue?.from) return true
+
+  const cellValue = row.getValue(columnId)
+  if (!cellValue) return false
+
+  const date = new Date(cellValue as string)
+  const from = filterValue.from
+  const to = filterValue.to || from
+
+  // Reset hours for comparison
+  const dateOnly = new Date(date.getFullYear(), date.getMonth(), date.getDate())
+  const fromOnly = new Date(from.getFullYear(), from.getMonth(), from.getDate())
+  const toOnly = new Date(to.getFullYear(), to.getMonth(), to.getDate())
+
+  return dateOnly >= fromOnly && dateOnly <= toOnly
+}