openprompt-lang 0.3.0 → 0.4.0

package/src/templates/langs/react/INDEX.json

@@ -0,0 +1,262 @@
+{
+  "language": "react",
+  "version": "1.0.0",
+  "updated": "2026-05-14",
+  "categories": {
+    "ui/button": {
+      "name": "Buttons",
+      "description": "Button components with variants and states"
+    },
+    "ui/modal": {
+      "name": "Modals",
+      "description": "Dialogs, confirmations, and popovers"
+    },
+    "ui/form": {
+      "name": "Forms",
+      "description": "Inputs, selects, and form utilities"
+    },
+    "ui/data-display": {
+      "name": "Data Display",
+      "description": "Tables, lists, cards, and data visualizers"
+    },
+    "auth": {
+      "name": "Authentication",
+      "description": "Auth hooks, providers, and guards"
+    },
+    "hook/general": {
+      "name": "General Hooks",
+      "description": "Reusable React hooks"
+    },
+    "service/api": {
+      "name": "API Services",
+      "description": "HTTP clients and API abstractions"
+    },
+    "util/date": {
+      "name": "Date Utilities",
+      "description": "Date formatting and manipulation"
+    },
+    "util/validation": {
+      "name": "Validation",
+      "description": "Input validation schemas and utilities"
+    },
+    "layout": {
+      "name": "Layout",
+      "description": "Page layout components (sidebar, navbar, shell)"
+    }
+  },
+  "templates": [
+    {
+      "id": "button-shadcn",
+      "name": "Button",
+      "description": "Versatile button with variants, loading state, and dark mode",
+      "category": "ui/button",
+      "purposes": ["primary-action", "confirmation", "danger", "navigation"],
+      "file": "templates/ui/Button.template.tsx",
+      "testFile": null,
+      "variants": ["primary", "secondary", "danger", "ghost", "outline"],
+      "sizes": ["sm", "default", "lg", "icon"],
+      "darkMode": true,
+      "responsive": true,
+      "dependencies": ["class-variance-authority", "lucide-react"],
+      "tags": ["button", "action", "form", "shadcn", "cva", "loading"],
+      "hasTeachMe": true,
+      "fixHistory": ["BUTTON-001"]
+    },
+    {
+      "id": "hook-useAuth",
+      "name": "useAuth",
+      "description": "Authentication hook with Supabase and Zustand session persistence",
+      "category": "auth",
+      "purposes": ["login", "register", "session", "logout", "protected-routes"],
+      "file": "templates/hooks/useAuth.template.ts",
+      "testFile": null,
+      "variants": [],
+      "sizes": [],
+      "darkMode": false,
+      "responsive": false,
+      "dependencies": ["@supabase/supabase-js", "zustand"],
+      "tags": ["auth", "supabase", "session", "hook", "rls"],
+      "hasTeachMe": true,
+      "fixHistory": ["AUTH-001", "AUTH-002"]
+    },
+    {
+      "id": "input-shadcn",
+      "name": "Input",
+      "description": "Form input with label, error state, helper text, and icon support",
+      "category": "ui/form",
+      "purposes": ["text-input", "search", "email", "password", "number"],
+      "file": "templates/ui/Input.template.tsx",
+      "testFile": null,
+      "variants": ["default", "error", "flushed"],
+      "sizes": ["sm", "default", "lg"],
+      "darkMode": true,
+      "responsive": true,
+      "dependencies": ["lucide-react"],
+      "tags": ["input", "form", "label", "error", "shadcn"],
+      "hasTeachMe": true,
+      "fixHistory": []
+    },
+    {
+      "id": "select-shadcn",
+      "name": "Select",
+      "description": "Custom styled select dropdown with label, error state, and placeholder",
+      "category": "ui/form",
+      "purposes": ["dropdown", "option-picker", "multi-select"],
+      "file": "templates/ui/Select.template.tsx",
+      "testFile": null,
+      "variants": ["default", "error", "multiple"],
+      "sizes": ["sm", "default", "lg"],
+      "darkMode": true,
+      "responsive": true,
+      "dependencies": ["lucide-react"],
+      "tags": ["select", "dropdown", "form", "shadcn"],
+      "hasTeachMe": true,
+      "fixHistory": []
+    },
+    {
+      "id": "card-shadcn",
+      "name": "Card",
+      "description": "Container card with title, subtitle, footer, and interactive variant",
+      "category": "ui/data-display",
+      "purposes": ["container", "summary", "feature-card", "dashboard-card"],
+      "file": "templates/ui/Card.template.tsx",
+      "testFile": null,
+      "variants": ["default", "bordered", "elevated", "interactive"],
+      "sizes": ["sm", "default", "full"],
+      "darkMode": true,
+      "responsive": true,
+      "dependencies": [],
+      "tags": ["card", "container", "dashboard", "shadcn"],
+      "hasTeachMe": true,
+      "fixHistory": []
+    },
+    {
+      "id": "modal-dialog",
+      "name": "Modal",
+      "description": "Accessible modal dialog with focus trap, portal rendering, and escape-to-close",
+      "category": "ui/modal",
+      "purposes": ["confirm-action", "form-dialog", "alert", "fullscreen"],
+      "file": "templates/ui/Modal.template.tsx",
+      "testFile": null,
+      "variants": ["dialog", "confirm-destructive", "fullscreen"],
+      "sizes": ["sm", "default", "lg", "xl", "fullscreen"],
+      "darkMode": true,
+      "responsive": true,
+      "dependencies": ["lucide-react"],
+      "tags": ["modal", "dialog", "overlay", "portal", "a11y"],
+      "hasTeachMe": true,
+      "fixHistory": []
+    },
+    {
+      "id": "datatable-shadcn",
+      "name": "DataTable",
+      "description": "Typed data table with sorting, loading skeleton, empty state, and keyboard a11y",
+      "category": "ui/data-display",
+      "purposes": ["data-table", "sortable-table", "paginated-list"],
+      "file": "templates/ui/DataTable.template.tsx",
+      "testFile": null,
+      "variants": ["default", "compact", "striped", "sortable"],
+      "sizes": ["default", "compact"],
+      "darkMode": true,
+      "responsive": true,
+      "dependencies": ["lucide-react"],
+      "tags": ["table", "data", "sortable", "shadcn"],
+      "hasTeachMe": true,
+      "fixHistory": []
+    },
+    {
+      "id": "hook-useDebounce",
+      "name": "useDebounce",
+      "description": "Debounce hook for input values, search delays, and resize throttling",
+      "category": "hook/general",
+      "purposes": ["input-debounce", "search-delay", "resize-throttle"],
+      "file": "templates/hooks/useDebounce.template.ts",
+      "testFile": null,
+      "variants": ["default", "leading", "trailing"],
+      "sizes": [],
+      "darkMode": false,
+      "responsive": false,
+      "dependencies": [],
+      "tags": ["debounce", "hook", "search", "throttle"],
+      "hasTeachMe": true,
+      "fixHistory": []
+    },
+    {
+      "id": "hook-usePagination",
+      "name": "usePagination",
+      "description": "Pagination hook with ellipsis logic, page buttons, and server-side support",
+      "category": "hook/general",
+      "purposes": ["paginated-list", "table-pagination", "infinite-scroll"],
+      "file": "templates/hooks/usePagination.template.ts",
+      "testFile": null,
+      "variants": ["client-side", "server-side"],
+      "sizes": [],
+      "darkMode": false,
+      "responsive": true,
+      "dependencies": [],
+      "tags": ["pagination", "hook", "table", "navigation"],
+      "hasTeachMe": true,
+      "fixHistory": []
+    },
+    {
+      "id": "hook-useForm",
+      "name": "useForm",
+      "description": "Lightweight form state manager with validation, async submit, and touched tracking",
+      "category": "ui/form",
+      "purposes": ["form-state", "validation", "async-submit"],
+      "file": "templates/hooks/useForm.template.ts",
+      "testFile": null,
+      "variants": ["controlled", "uncontrolled"],
+      "sizes": [],
+      "darkMode": false,
+      "responsive": false,
+      "dependencies": [],
+      "tags": ["form", "validation", "hook", "state"],
+      "hasTeachMe": true,
+      "fixHistory": []
+    },
+    {
+      "id": "service-api",
+      "name": "ApiClient",
+      "description": "Generic REST API client with typed responses, auth, timeout, and error handling",
+      "category": "service/api",
+      "purposes": ["crud", "rest-api", "http-client", "data-fetching"],
+      "file": "templates/services/apiService.template.ts",
+      "testFile": null,
+      "variants": ["rest", "supabase"],
+      "sizes": [],
+      "darkMode": false,
+      "responsive": false,
+      "dependencies": [],
+      "tags": ["api", "rest", "http", "client", "service"],
+      "hasTeachMe": true,
+      "fixHistory": ["AUTH-002"]
+    }
+  ],
+  "errorsLearned": [
+    {
+      "id": "BUTTON-001",
+      "template": "button-shadcn",
+      "problem": "Button without type='button' caused unintended form submission",
+      "solution": "Added type='button' as default to prevent browser submit behavior",
+      "date": "2026-04-15",
+      "category": "html-behavior"
+    },
+    {
+      "id": "AUTH-001",
+      "template": "hook-useAuth",
+      "problem": "Session not persisted on page refresh (Zustand store lost)",
+      "solution": "Added localStorage persistence middleware to Zustand store",
+      "date": "2026-04-18",
+      "category": "state-persistence"
+    },
+    {
+      "id": "AUTH-002",
+      "template": "hook-useAuth",
+      "problem": "Auth token exposed in client console.log during debug",
+      "solution": "Removed debug logs from production build using if(dev) guard",
+      "date": "2026-04-20",
+      "category": "security"
+    }
+  ]
+}

package/src/templates/langs/react/MODULE.json

@@ -0,0 +1,166 @@
+{
+  "id": "react",
+  "name": "React + TypeScript (Vite)",
+  "version": "1.0.0",
+  "tags": {
+    "kind": {
+      "hook": {
+        "extends": "base",
+        "limit": 80,
+        "requires": ["contract"],
+        "forbids": ["props"],
+        "description": "Custom React hook"
+      },
+      "component": {
+        "extends": "base",
+        "limit": 120,
+        "suggests": ["props", "state"],
+        "forbids": ["contract"],
+        "description": "React UI component"
+      },
+      "page": {
+        "extends": "base",
+        "limit": 200,
+        "requires": ["compose"],
+        "description": "Full page component"
+      },
+      "service": {
+        "extends": "base",
+        "limit": 150,
+        "requires": ["contract"],
+        "forbids": ["props", "state"],
+        "description": "API service layer"
+      },
+      "store": {
+        "extends": "base",
+        "limit": 100,
+        "suggests": ["deps"],
+        "description": "Global state (Zustand)"
+      },
+      "util": {
+        "extends": "base",
+        "limit": 100,
+        "forbids": ["state"],
+        "description": "Utility function"
+      },
+      "type": {
+        "extends": "base",
+        "forbids": ["limit", "state"],
+        "description": "TypeScript type/interface"
+      },
+      "layout": { "extends": "base", "limit": 150, "description": "Layout wrapper component" },
+      "feature": {
+        "extends": "base",
+        "requires": ["compose"],
+        "description": "Feature module bundle"
+      }
+    },
+    "platforms": ["web", "mobile", "desktop"],
+    "forbidden": ["any", "css-modules", "class-components"]
+  },
+  "structure": {
+    "folders": [
+      "src/components/ui",
+      "src/components/layout",
+      "src/components/shared",
+      "src/features",
+      "src/hooks",
+      "src/services",
+      "src/store",
+      "src/types",
+      "src/utils",
+      "docs/COMMITS",
+      "docs/LOGS/ERRORES",
+      "docs/LOGS/ACTIVIDAD",
+      "docs/BACKLOG",
+      "docs/PROMPTS/PLANTILLAS",
+      "docs/PROMPTS/STACK",
+      "scripts"
+    ],
+    "scaffolds": ["prompt-lang.json", "AGENTS.md", ".gitignore", "tailwind.config.js"],
+    "deps": {
+      "base": {
+        "dev": [
+          "typescript",
+          "vite",
+          "@vitejs/plugin-react",
+          "tailwindcss",
+          "@tailwindcss/vite",
+          "vitest"
+        ]
+      },
+      "supabase": { "prod": ["@supabase/supabase-js", "@supabase/ssr"] },
+      "stripe": { "prod": ["@stripe/react-stripe-js", "@stripe/stripe-js"] },
+      "ionic": {
+        "prod": ["@ionic/react", "@ionic/react-router", "@capacitor/core"],
+        "dev": ["@capacitor/cli"]
+      },
+      "tauri": { "dev": ["@tauri-apps/cli"] },
+      "prisma": { "dev": ["prisma"], "prod": ["@prisma/client"] }
+    }
+  },
+  "projectTypes": {
+    "saas": {
+      "name": "SaaS / Dashboard",
+      "ui": true,
+      "description": "Multi-tenant SaaS with dashboard"
+    },
+    "web": { "name": "Corporate Website", "ui": true, "description": "Company landing + content" },
+    "landing": { "name": "Landing Page", "ui": true, "description": "Single product/service page" },
+    "portfolio": { "name": "Portfolio", "ui": true, "description": "Personal dev portfolio" },
+    "api": { "name": "API / Microservice", "ui": false, "description": "Backend-only service" },
+    "mobile": { "name": "Mobile App", "ui": true, "description": "Capacitor/Ionic mobile app" },
+    "desktop": { "name": "Desktop App", "ui": true, "description": "Tauri desktop app" }
+  },
+  "uiStyles": ["shadcn", "mantine", "chakra", "headless", "mui", "none"],
+  "extensions": [
+    {
+      "name": "Supabase (auth + DB)",
+      "value": "supabase",
+      "deps": ["@supabase/supabase-js", "@supabase/ssr"],
+      "description": "Backend as a service with auth"
+    },
+    {
+      "name": "Stripe (payments)",
+      "value": "stripe",
+      "deps": ["@stripe/react-stripe-js", "@stripe/stripe-js"],
+      "description": "Payment processing"
+    },
+    {
+      "name": "Prisma ORM",
+      "value": "prisma",
+      "deps": ["prisma", "@prisma/client"],
+      "description": "Type-safe database ORM"
+    },
+    {
+      "name": "Ionic (mobile)",
+      "value": "ionic",
+      "deps": ["@ionic/react", "@ionic/react-router", "@capacitor/core"],
+      "description": "Cross-platform mobile"
+    },
+    {
+      "name": "Tauri (desktop)",
+      "value": "tauri",
+      "deps": ["@tauri-apps/cli"],
+      "description": "Desktop application"
+    },
+    {
+      "name": "Next.js (SSR)",
+      "value": "next",
+      "deps": ["next", "react", "react-dom"],
+      "description": "Server-side rendering"
+    },
+    {
+      "name": "Auth0",
+      "value": "auth0",
+      "deps": ["@auth0/auth0-react"],
+      "description": "Authentication as a service"
+    },
+    {
+      "name": "Webpay CL",
+      "value": "webpay",
+      "deps": ["transbank-sdk"],
+      "description": "Chilean payment gateway"
+    }
+  ]
+}

package/src/templates/langs/react/templates/hooks/useAuth.template.ts

@@ -0,0 +1,134 @@
+// @template
+// @id: hook-useAuth
+// @category: auth
+// @purpose: login, register, session, logout
+// @framework: react
+// @style: none
+// @darkMode: false
+// @responsive: false
+// @deps: [@supabase/supabase-js, zustand]
+// @props: {}
+// @states: [loading, authenticated, unauthenticated, error]
+// @example: const { user, login, logout, loading } = useAuth()
+// @teachMe
+//
+// ## Anatomy
+// This hook combines Supabase auth with Zustand for client-side session persistence.
+// The Zustand store uses localStorage middleware to survive page refreshes.
+// Auth state is derived from both the Supabase session and the local store.
+//
+// @goodPractice: Use Zustand middleware for localStorage persistence
+// @goodPractice: Derive auth state from supabase.getSession() on mount
+// @goodPractice: Wrap login/register in try/catch with typed errors
+// @badPractice: Don't store raw passwords or tokens in localStorage (see AUTH-002)
+// @badPractice: Don't rely only on Supabase session — it resets on refresh without persistence
+// @badPractice: Don't expose internal state setters outside the hook
+// @fixHistory: AUTH-001 — added Zustand persistence for page refresh
+// @fixHistory: AUTH-002 — removed console.log of auth token in production
+
+import { create } from "zustand"
+import { persist } from "zustand/middleware"
+import { useEffect, useState } from "react"
+import { createClient, type User, type Session } from "@supabase/supabase-js"
+
+const supabase = createClient(
+  import.meta.env.VITE_SUPABASE_URL,
+  import.meta.env.VITE_SUPABASE_ANON_KEY
+)
+
+interface AuthState {
+  user: User | null
+  session: Session | null
+  setAuth: (user: User | null, session: Session | null) => void
+  clearAuth: () => void
+}
+
+const useAuthStore = create<AuthState>()(
+  persist(
+    (set) => ({
+      user: null,
+      session: null,
+      setAuth: (user, session) => set({ user, session }),
+      clearAuth: () => set({ user: null, session: null }),
+    }),
+    {
+      name: "auth-storage",
+      partialize: (state) => ({ user: state.user }),
+    }
+  )
+)
+
+interface AuthResult {
+  user: User | null
+  loading: boolean
+  error: string | null
+  login: (email: string, password: string) => Promise<void>
+  register: (email: string, password: string) => Promise<void>
+  logout: () => Promise<void>
+}
+
+export function useAuth(): AuthResult {
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+  const { user, setAuth, clearAuth } = useAuthStore()
+
+  useEffect(() => {
+    supabase.auth.getSession().then(({ data: { session } }) => {
+      if (session?.user) {
+        setAuth(session.user, session)
+      }
+      setLoading(false)
+    })
+
+    const {
+      data: { subscription },
+    } = supabase.auth.onAuthStateChange((_event, session) => {
+      if (session?.user) {
+        setAuth(session.user, session)
+      } else {
+        clearAuth()
+      }
+    })
+
+    return () => subscription?.unsubscribe()
+  }, [])
+
+  const login = async (email: string, password: string) => {
+    setLoading(true)
+    setError(null)
+    const { error: authError } = await supabase.auth.signInWithPassword({
+      email,
+      password,
+    })
+    if (authError) {
+      setError(authError.message)
+      setLoading(false)
+      throw authError
+    }
+    setLoading(false)
+  }
+
+  const register = async (email: string, password: string) => {
+    setLoading(true)
+    setError(null)
+    const { error: authError } = await supabase.auth.signUp({
+      email,
+      password,
+    })
+    if (authError) {
+      setError(authError.message)
+      setLoading(false)
+      throw authError
+    }
+    setLoading(false)
+  }
+
+  const logout = async () => {
+    setLoading(true)
+    await supabase.auth.signOut()
+    clearAuth()
+    setLoading(false)
+  }
+
+  return { user, loading, error, login, register, logout }
+}

package/src/templates/langs/react/templates/hooks/useDebounce.template.ts

@@ -0,0 +1,45 @@
+// @template
+// @id: hook-useDebounce
+// @category: hook/general
+// @purpose: input-debounce, search-delay, resize-throttle
+// @framework: react
+// @style: generic
+// @variants: [default, leading, trailing]
+// @sizes: []
+// @darkMode: false
+// @responsive: false
+// @deps: []
+// @props: { value: T, delay?: number }
+// @states: [pending, settled]
+// @example: const debouncedSearch = useDebounce(searchTerm, 300)
+// @teachMe
+//
+// ## Anatomy
+// Returns a debounced version of the input value that only updates after `delay` ms of inactivity.
+// Uses useEffect + setTimeout to track the last change. Cleanup on unmount prevents stale updates.
+// Leading variant fires immediately then debounces; trailing (default) waits for pause.
+//
+// @goodPractice: Clean up timeout on unmount to prevent memory leaks and state updates
+// @goodPractice: Use 300ms for search, 150ms for resize, 500ms for API saves
+// @goodPractice: Pair with useMemo for derived data that depends on debounced value
+// @badPractice: Don't debounce form submission — debounce only the input value
+// @badPractice: Don't use debounce for animation frames — use requestAnimationFrame
+// @badPractice: Don't set delay < 100ms — defeats the purpose of debouncing
+
+import { useState, useEffect } from "react"
+
+function useDebounce<T>(value: T, delay: number = 300): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value)
+
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      setDebouncedValue(value)
+    }, delay)
+
+    return () => clearTimeout(timer)
+  }, [value, delay])
+
+  return debouncedValue
+}
+
+export { useDebounce }