@create-lft-app/nextjs 3.2.0 → 3.3.0

package/template/.claude/skills/supabase-server-actions.md

@@ -0,0 +1,199 @@
+# Supabase Server Actions & Auth
+
+## Supabase Clients
+
+```
+lib/supabase/
+├── client.ts    → Browser client (anon key) - for UI
+├── server.ts    → Server client (anon key + cookies) - for verifying auth
+└── admin.ts     → Admin client (secret key) - for managing users
+```
+
+### When to use each client
+
+| Operation | Client | Reason |
+|-----------|--------|--------|
+| Login/Logout | `server.ts` | Needs cookies |
+| Verify session | `server.ts` | Needs cookies |
+| Create user | `admin.ts` | Requires admin privileges |
+| List/Update/Delete users | `admin.ts` | Requires admin privileges |
+| Queries on own tables | `server.ts` | RLS based on user |
+
+## Standard Server Action Template (Own Tables)
+
+For entities with their own database tables, server actions use the repository pattern:
+
+```typescript
+'use server'
+
+import { createClient } from '@/lib/supabase/server'
+import { entityRepository } from '../repositories/entity.repository'
+import { entityInsertSchema, entityUpdateSchema } from '../schemas/entity.schema'
+
+// Helper: verify authenticated user or throw
+async function requireAuth() {
+  const supabase = await createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) throw new Error('Unauthorized')
+  return user
+}
+
+// CREATE
+export async function createEntity(raw: unknown) {
+  await requireAuth()
+  const data = entityInsertSchema.parse(raw)
+  return entityRepository.create(data)
+}
+
+// READ
+export async function getEntities() {
+  await requireAuth()
+  return entityRepository.findAll()
+}
+
+// UPDATE
+export async function updateEntity(id: string, raw: unknown) {
+  await requireAuth()
+  const data = entityUpdateSchema.parse(raw)
+  return entityRepository.update(id, data)
+}
+
+// DELETE
+export async function deleteEntity(id: string) {
+  await requireAuth()
+  return entityRepository.delete(id)
+}
+```
+
+## Server Action Template (auth.users with Admin API)
+
+For managing Supabase Auth users (not own tables):
+
+```typescript
+'use server'
+
+import { createClient } from '@/lib/supabase/server'
+import { createAdminClient } from '@/lib/supabase/admin'
+import { mapAuthUserToUser } from '../utils/user-mapper'
+
+export async function createUser(input: CreateAuthUserInput) {
+  // 1. Verify current user is authenticated
+  const supabase = await createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) throw new Error('Unauthorized')
+
+  // 2. Use admin client for privileged operations
+  const adminClient = createAdminClient()
+  const { data, error } = await adminClient.auth.admin.createUser({
+    email: input.email,
+    app_metadata: { role: input.role },
+    user_metadata: { name: input.name },
+  })
+
+  if (error) throw error
+  return mapAuthUserToUser(data.user)
+}
+```
+
+## Roles Configuration
+
+Roles are centralized in `config/roles.ts`. Single source of truth:
+
+```typescript
+// config/roles.ts
+export const USER_ROLES = ['admin', 'user', 'viewer'] as const
+export type UserRole = (typeof USER_ROLES)[number]
+export const DEFAULT_ROLE: UserRole = 'user'
+
+export const ROLE_LABELS: Record<UserRole, string> = {
+  admin: 'Administrador',
+  user: 'Usuario',
+  viewer: 'Visualizador',
+}
+
+export const ROLE_OPTIONS = USER_ROLES.map((role) => ({
+  value: role,
+  label: ROLE_LABELS[role],
+}))
+```
+
+Usage:
+- Zod schemas: `import { USER_ROLES, DEFAULT_ROLE } from '@/config/roles'`
+- Columns/UI: `import { ROLE_LABELS, ROLE_OPTIONS } from '@/config/roles'`
+- Types: `import type { UserRole } from '@/config/roles'`
+
+If the system does NOT need roles, simplify to `['user']` or remove `config/roles.ts` entirely.
+
+## User Architecture
+
+Users live in `auth.users` (Supabase Auth), NOT in a `public.users` table:
+
+```
+auth.users (Supabase Auth)
+├── id: uuid
+├── email: string
+├── app_metadata: { role: UserRole }     ← Role here
+├── user_metadata: { name, avatar_url }  ← Extra data here
+├── created_at: timestamp
+└── updated_at: timestamp
+```
+
+The users module includes a mapper: `modules/users/utils/user-mapper.ts`.
+
+## Integration with TanStack Mutations
+
+Server actions are called from the mutations hook, which handles cache invalidation:
+
+```typescript
+// modules/[entity]/hooks/use[Entity]Mutations.ts
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { createEntity, updateEntity, deleteEntity } from '../actions/entity-actions'
+
+export function useEntityMutations() {
+  const qc = useQueryClient()
+
+  const create = useMutation({
+    mutationFn: createEntity,
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['entities'] }),
+  })
+
+  const update = useMutation({
+    mutationFn: ({ id, data }: { id: string; data: EntityUpdate }) =>
+      updateEntity(id, data),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['entities'] }),
+  })
+
+  const remove = useMutation({
+    mutationFn: deleteEntity,
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['entities'] }),
+  })
+
+  return {
+    createEntity: create.mutateAsync,
+    updateEntity: update.mutateAsync,
+    deleteEntity: remove.mutateAsync,
+    isCreating: create.isPending,
+    isUpdating: update.isPending,
+    isDeleting: remove.isPending,
+  }
+}
+```
+
+## Key Rules
+
+1. **Always `'use server'`** at the top of the file.
+2. **Always verify the user** with `requireAuth()` before any operation.
+3. **Never expose the service-role key** to server actions called from the client.
+4. **Let RLS do the authorization** — after verifying the user exists, RLS policies handle what they can access.
+5. **Validate inputs with Zod** — always `schema.parse(raw)` before passing data to the repository.
+6. **Do NOT use `revalidatePath`** — cache invalidation is handled by TanStack Query's `invalidateQueries` in the mutations hook. Only add `revalidatePath` if a Server Component also consumes the same data outside TanStack Query.
+7. **Use repository for own tables, Admin API for auth.users** — never mix them.
+
+## Environment Variables
+
+```env
+NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
+NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=sb_publishable_...
+SUPABASE_SECRET_DEFAULT_KEY=sb_secret_...          # Required for admin client
+DATABASE_URL=postgresql://user:pass@host:5432/db   # Required for Drizzle
+```

package/template/.claude/skills/ui-patterns.md

@@ -0,0 +1,161 @@
+# UI Patterns & Page Architecture
+
+## Design Philosophy (Midday style)
+
+- **Minimalism**: Wide spacing, clear typography
+- **Dark mode first**: Dark theme as primary experience
+- **No modals for CRUD**: Use full pages instead of dialogs
+- **Hierarchical navigation**: Sidebar > SecondaryMenu (tabs) > Content
+- **Constrained containers**: `max-w-[800px]` for forms
+
+## Pages vs Modals
+
+| Action | DO NOT use | MUST use |
+|--------|-----------|----------|
+| Create entity | Dialog with form | `/entity/new` (full page) |
+| Edit entity | Sheet with form | `/entity/[id]/edit` (full page) |
+| View detail | Expand row | `/entity/[id]` (full page) |
+| Confirm deletion | — | AlertDialog (only exception) |
+| Complex filters | Modal | Collapsible panel or page |
+
+## Route Structure Pattern
+
+```
+app/(auth)/
+├── layout.tsx                    # Layout with Sidebar
+├── dashboard/
+│   └── page.tsx
+├── [entity]/
+│   ├── layout.tsx                # SecondaryMenu for this section
+│   ├── page.tsx                  # List
+│   ├── new/
+│   │   └── page.tsx              # Create (full page)
+│   ├── [id]/
+│   │   ├── page.tsx              # Detail
+│   │   └── edit/
+│   │       └── page.tsx          # Edit (full page)
+│   └── [sub-section]/
+│       └── page.tsx              # Additional section pages
+```
+
+## SecondaryMenu Pattern
+
+When a section has subpages, MUST add a `layout.tsx` with SecondaryMenu:
+
+```typescript
+// app/(auth)/settings/layout.tsx
+import { SecondaryMenu } from '@/components/layout/secondary-menu'
+
+export default function SettingsLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="max-w-[800px]">
+      <SecondaryMenu
+        items={[
+          { path: '/settings', label: 'General' },
+          { path: '/settings/billing', label: 'Billing' },
+          { path: '/settings/members', label: 'Members' },
+          { path: '/settings/notifications', label: 'Notifications' },
+        ]}
+      />
+      <main className="mt-8">{children}</main>
+    </div>
+  )
+}
+```
+
+## Navigation Configuration
+
+Sidebar navigation is defined in `config/navigation.ts` with support for children (submenus):
+
+```typescript
+// config/navigation.ts
+export type NavItem = {
+  title: string
+  href: string
+  icon?: keyof typeof Icons
+  disabled?: boolean
+  badge?: string
+  children?: NavItem[]
+}
+
+export type NavSection = {
+  title?: string
+  items: NavItem[]
+}
+
+export const sidebarNav: NavSection[] = [
+  {
+    items: [
+      { title: 'Dashboard', href: '/dashboard', icon: 'dashboard' },
+      {
+        title: 'Users', href: '/users', icon: 'users',
+        children: [
+          { title: 'All Users', href: '/users' },
+          { title: 'Create New', href: '/users/new' },
+        ],
+      },
+    ],
+  },
+]
+```
+
+## Container Widths
+
+```typescript
+// Forms and settings
+<div className="max-w-[800px]">
+
+// Tables and lists
+<div className="w-full">
+
+// Dashboards with metrics
+<div className="max-w-[1200px]">
+```
+
+## Spacing
+
+```typescript
+// Between form sections
+<div className="space-y-12">
+
+// Between form fields
+<div className="space-y-6">
+
+// Between small elements
+<div className="space-y-4">
+```
+
+## Page Header
+
+Always use the `PageHeader` component for page headers:
+
+```typescript
+import { PageHeader } from '@/components/layout/page-header'
+
+<PageHeader
+  title="Products"
+  description="Manage your product catalog"
+  actions={<Button onClick={() => router.push('/products/new')}>Create</Button>}
+/>
+```
+
+## Table Row Actions
+
+Row actions MUST navigate to pages, NOT open modals:
+
+```typescript
+const actions = [
+  { label: 'Edit', onClick: (row) => router.push(`/users/${row.id}/edit`) },
+  { label: 'View', onClick: (row) => router.push(`/users/${row.id}`) },
+  { label: 'Delete', onClick: (row) => setDeleteId(row.id) }, // AlertDialog only
+]
+```
+
+## Checklist for New Pages
+
+- Has subpages? Create `layout.tsx` with SecondaryMenu
+- Is a form? Use `max-w-[800px]`
+- Is a list/table? Use `w-full`
+- Needs create/edit? Create `/new` and `/[id]/edit` routes
+- Has parent navigation? Add to `navigation.ts` with children
+- Sidebar needs update? Add icon and route