openprompt-lang 0.3.0 → 0.4.0

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

@@ -0,0 +1,146 @@
+// @template
+// @id: hook-useForm
+// @category: ui/form
+// @purpose: form-state, validation, submission, async-submit
+// @framework: react
+// @style: generic
+// @variants: [controlled, uncontrolled]
+// @sizes: []
+// @darkMode: false
+// @responsive: false
+// @deps: []
+// @props: { initialValues: T, validate?: (values: T) => Partial<Record<keyof T, string>>, onSubmit: (values: T) => Promise<void> }
+// @states: [idle, validating, submitting, success, error]
+// @example: const { values, errors, handleChange, handleSubmit, isSubmitting } = useForm({ initialValues: { email: '' }, onSubmit: handleSave })
+// @teachMe
+//
+// ## Anatomy
+// Lightweight form state manager without external dependencies.
+// Handles field values, validation errors, touched state, and async submission.
+// Use `handleChange` for input onChange, `handleSubmit` for form onSubmit.
+// Validate function receives current values and returns error map.
+//
+// @goodPractice: Validate on blur (touched) + on submit — not on every keystroke
+// @goodPractice: Disable submit button while isSubmitting to prevent double-submit
+// @goodPractice: Set focus to first error field after validation for UX
+// @goodPractice: Use generic <T> for type-safe field names and values
+// @badPractice: Don't store entire form state in a single useState — use useReducer for complex forms
+// @badPractice: Don't call setValues for every keystroke on large forms — batch updates
+// @badPractice: Don't forget to reset form after successful submission
+
+import { useState, useCallback, type FormEvent, type ChangeEvent } from "react"
+
+type ValidationErrors<T> = Partial<Record<keyof T, string>>
+
+interface UseFormOptions<T extends Record<string, unknown>> {
+  initialValues: T
+  validate?: (values: T) => ValidationErrors<T>
+  onSubmit: (values: T) => Promise<void> | void
+}
+
+interface UseFormReturn<T> {
+  values: T
+  errors: ValidationErrors<T>
+  touched: Partial<Record<keyof T, boolean>>
+  isSubmitting: boolean
+  isDirty: boolean
+  handleChange: (field: keyof T) => (e: ChangeEvent<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>) => void
+  handleSubmit: (e: FormEvent) => Promise<void>
+  setFieldValue: (field: keyof T, value: unknown) => void
+  setFieldTouched: (field: keyof T) => void
+  resetForm: (newValues?: T) => void
+  setErrors: (errors: ValidationErrors<T>) => void
+}
+
+function useForm<T extends Record<string, unknown>>({
+  initialValues,
+  validate,
+  onSubmit,
+}: UseFormOptions<T>): UseFormReturn<T> {
+  const [values, setValues] = useState<T>(initialValues)
+  const [errors, setErrors] = useState<ValidationErrors<T>>({})
+  const [touched, setTouched] = useState<Partial<Record<keyof T, boolean>>>({})
+  const [isSubmitting, setIsSubmitting] = useState(false)
+
+  const isDirty = Object.keys(touched).length > 0
+
+  const handleChange = useCallback(
+    (field: keyof T) =>
+      (e: ChangeEvent<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>) => {
+        const { value, type, checked } = e.target
+        setValues((prev) => ({
+          ...prev,
+          [field]: type === "checkbox" ? checked : value,
+        }))
+      },
+    []
+  )
+
+  const handleSubmit = useCallback(
+    async (e: FormEvent) => {
+      e.preventDefault()
+
+      if (validate) {
+        const validationErrors = validate(values)
+        setErrors(validationErrors)
+        const allTouched = Object.keys(values).reduce(
+          (acc, key) => ({ ...acc, [key]: true }),
+          {} as Partial<Record<keyof T, boolean>>
+        )
+        setTouched(allTouched)
+
+        if (Object.keys(validationErrors).length > 0) {
+          const firstErrorField = Object.keys(validationErrors)[0] as keyof T
+          document.querySelector<HTMLElement>(`[name="${String(firstErrorField)}"]`)?.focus()
+          return
+        }
+      }
+
+      setIsSubmitting(true)
+      try {
+        await onSubmit(values)
+      } finally {
+        setIsSubmitting(false)
+      }
+    },
+    [values, validate, onSubmit]
+  )
+
+  const setFieldValue = useCallback((field: keyof T, value: unknown) => {
+    setValues((prev) => ({ ...prev, [field]: value as T[keyof T] }))
+  }, [])
+
+  const setFieldTouched = useCallback((field: keyof T) => {
+    setTouched((prev) => ({ ...prev, [field]: true }))
+    if (validate) {
+      setValues((current) => {
+        const validationErrors = validate(current)
+        setErrors((prev) => ({ ...prev, ...validationErrors }))
+        return current
+      })
+    }
+  }, [validate])
+
+  const resetForm = useCallback((newValues?: T) => {
+    setValues(newValues || initialValues)
+    setErrors({})
+    setTouched({})
+    setIsSubmitting(false)
+  }, [initialValues])
+
+  return {
+    values,
+    errors,
+    touched,
+    isSubmitting,
+    isDirty,
+    handleChange,
+    handleSubmit,
+    setFieldValue,
+    setFieldTouched,
+    resetForm,
+    setErrors,
+  }
+}
+
+export { useForm }

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

@@ -0,0 +1,108 @@
+// @template
+// @id: hook-usePagination
+// @category: hook/general
+// @purpose: paginated-list, table-pagination, infinite-scroll
+// @framework: react
+// @style: generic
+// @variants: [client-side, server-side]
+// @sizes: []
+// @darkMode: false
+// @responsive: true
+// @deps: []
+// @props: { totalItems: number, pageSize?: number, initialPage?: number }
+// @states: [first-page, middle-page, last-page, single-page, loading]
+// @example: const { page, setPage, totalPages, pageButtons } = usePagination({ totalItems: 100 })
+// @teachMe
+//
+// ## Anatomy
+// Calculates pagination state given total items and page size. Returns page number, total pages,
+// and a `pageButtons` array for rendering pagination UI (with ellipsis for large page counts).
+// Server-side variant assumes totalItems is known from API response.
+//
+// @goodPractice: Show first + last page always, use ellipsis for gaps (1 ... 4 5 6 ... 20)
+// @goodPractice: Keep pageSize in URL search params for shareable URLs
+// @goodPractice: Disable prev on first page, next on last page
+// @badPractice: Don't render all page buttons for 100+ pages — use ellipsis
+// @badPractice: Don't reset page to 1 on every data change — breaks UX
+// @badPractice: Don't use client-side pagination for > 10k rows — use server-side
+
+import { useState, useMemo } from "react"
+
+interface UsePaginationOptions {
+  totalItems: number
+  pageSize?: number
+  initialPage?: number
+  siblingCount?: number
+}
+
+interface UsePaginationReturn {
+  page: number
+  setPage: (page: number) => void
+  totalPages: number
+  pageSize: number
+  hasPrev: boolean
+  hasNext: boolean
+  pageButtons: (number | "ellipsis")[]
+  from: number
+  to: number
+  nextPage: () => void
+  prevPage: () => void
+}
+
+function usePagination({
+  totalItems,
+  pageSize = 20,
+  initialPage = 1,
+  siblingCount = 1,
+}: UsePaginationOptions): UsePaginationReturn {
+  const [page, setPage] = useState(initialPage)
+  const totalPages = Math.max(1, Math.ceil(totalItems / pageSize))
+
+  const safePage = Math.min(page, totalPages)
+
+  const pageButtons = useMemo<(number | "ellipsis")[]>(() => {
+    const totalPageNumbers = siblingCount + 5
+    if (totalPages <= totalPageNumbers) {
+      return Array.from({ length: totalPages }, (_, i) => i + 1)
+    }
+
+    const leftSiblingIndex = Math.max(safePage - siblingCount, 1)
+    const rightSiblingIndex = Math.min(safePage + siblingCount, totalPages)
+    const showLeftEllipsis = leftSiblingIndex > 2
+    const showRightEllipsis = rightSiblingIndex < totalPages - 1
+
+    if (!showLeftEllipsis && showRightEllipsis) {
+      const leftCount = 3 + 2 * siblingCount
+      const leftRange = Array.from({ length: leftCount }, (_, i) => i + 1)
+      return [...leftRange, "ellipsis", totalPages]
+    }
+
+    if (showLeftEllipsis && !showRightEllipsis) {
+      const rightCount = 3 + 2 * siblingCount
+      const rightRange = Array.from({ length: rightCount }, (_, i) => totalPages - rightCount + i + 1)
+      return [1, "ellipsis", ...rightRange]
+    }
+
+    const middleRange = Array.from(
+      { length: rightSiblingIndex - leftSiblingIndex + 1 },
+      (_, i) => leftSiblingIndex + i
+    )
+    return [1, "ellipsis", ...middleRange, "ellipsis", totalPages]
+  }, [totalPages, safePage, siblingCount])
+
+  return {
+    page: safePage,
+    setPage: (p: number) => setPage(Math.max(1, Math.min(p, totalPages))),
+    totalPages,
+    pageSize,
+    hasPrev: safePage > 1,
+    hasNext: safePage < totalPages,
+    pageButtons,
+    from: (safePage - 1) * pageSize + 1,
+    to: Math.min(safePage * pageSize, totalItems),
+    nextPage: () => setPage((p) => Math.min(p + 1, totalPages)),
+    prevPage: () => setPage((p) => Math.max(p - 1, 1)),
+  }
+}
+
+export { usePagination }

package/src/templates/langs/react/templates/services/apiService.template.ts

@@ -0,0 +1,123 @@
+// @template
+// @id: service-api
+// @category: service/api
+// @purpose: crud, rest-api, http-client, data-fetching
+// @framework: react
+// @style: generic
+// @variants: [rest, supabase]
+// @sizes: []
+// @darkMode: false
+// @responsive: false
+// @deps: []
+// @props: { baseUrl: string, headers?: Record<string, string> }
+// @states: [idle, loading, success, error]
+// @example: const api = createApiClient('/api/users'); const users = await api.getAll()
+// @teachMe
+//
+// ## Anatomy
+// Generic API client for RESTful services. Supports CRUD operations with typed responses.
+// Built on fetch() with automatic JSON parsing, error handling, and auth header injection.
+// Request interceptor for adding tokens, response interceptor for 401 handling.
+// Use with services/domain files that wrap specific endpoints.
+//
+// @goodPractice: Centralize fetch configuration — base URL, timeout, headers
+// @goodPractice: Handle 401 globally — redirect to login, don't retry
+// @goodPractice: Type all responses — never use `any` for API data
+// @goodPractice: Use AbortController for cancelling requests on unmount
+// @badPractice: Don't catch errors silently — always surface to UI or error boundary
+// @badPractice: Don't store tokens in localStorage without httpOnly cookie fallback
+// @badPractice: Don't retry 4xx errors — only retry 5xx (server) errors
+// @fixHistory: AUTH-002 — removed debug console.log exposing auth tokens
+
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
+
+interface ApiResponse<T> {
+  data: T | null
+  error: ApiError | null
+  status: number
+}
+
+interface ApiError {
+  message: string
+  status: number
+  code?: string
+}
+
+interface ApiClientConfig {
+  baseUrl: string
+  headers?: Record<string, string>
+  getToken?: () => string | null
+  onUnauthorized?: () => void
+  timeout?: number
+}
+
+function createApiClient(config: ApiClientConfig) {
+  const { baseUrl, headers = {}, getToken, onUnauthorized, timeout = 15000 } = config
+
+  async function request<T>(method: HttpMethod, path: string, body?: unknown): Promise<ApiResponse<T>> {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeout)
+
+    try {
+      const token = getToken?.()
+      const response = await fetch(`${baseUrl}${path}`, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          ...(token ? { Authorization: `Bearer ${token}` } : {}),
+          ...headers,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      })
+
+      clearTimeout(timer)
+
+      if (response.status === 401) {
+        onUnauthorized?.()
+        return {
+          data: null,
+          error: { message: "Unauthorized", status: 401, code: "UNAUTHORIZED" },
+          status: 401,
+        }
+      }
+
+      const json = await response.json().catch(() => null)
+
+      if (!response.ok) {
+        return {
+          data: null,
+          error: {
+            message: json?.message || json?.error || `Request failed with status ${response.status}`,
+            status: response.status,
+            code: json?.code,
+          },
+          status: response.status,
+        }
+      }
+
+      return { data: json as T, error: null, status: response.status }
+    } catch (err) {
+      clearTimeout(timer)
+      if (err instanceof DOMException && err.name === "AbortError") {
+        return { data: null, error: { message: "Request timed out", status: 408, code: "TIMEOUT" }, status: 408 }
+      }
+      return {
+        data: null,
+        error: { message: err instanceof Error ? err.message : "Network error", status: 0, code: "NETWORK_ERROR" },
+        status: 0,
+      }
+    }
+  }
+
+  return {
+    get: <T>(path: string) => request<T>("GET", path),
+    post: <T>(path: string, body: unknown) => request<T>("POST", path, body),
+    put: <T>(path: string, body: unknown) => request<T>("PUT", path, body),
+    patch: <T>(path: string, body: unknown) => request<T>("PATCH", path, body),
+    del: <T>(path: string) => request<T>("DELETE", path),
+  }
+}
+
+export { createApiClient }
+export type { ApiResponse, ApiError, ApiClientConfig }

package/src/templates/langs/react/templates/ui/Button.template.tsx

@@ -0,0 +1,87 @@
+// @template
+// @id: button-shadcn
+// @category: ui/button
+// @purpose: primary-action, confirmation, danger
+// @framework: react
+// @style: shadcn
+// @variants: [primary, secondary, danger, ghost, outline]
+// @sizes: [sm, default, lg, icon]
+// @darkMode: true
+// @responsive: true
+// @deps: [class-variance-authority, lucide-react]
+// @props: { variant: string, size: string, disabled?: boolean, loading?: boolean, children: ReactNode }
+// @states: [idle, loading, disabled, hover, active, focus-visible]
+// @example: <Button variant="primary" size="default" loading>Save</Button>
+// @teachMe
+//
+// ## Anatomy
+// This Button uses `cva` (class-variance-authority) for type-safe variant management.
+// The loading state renders a spinner icon and disables interaction.
+// Dark mode is handled via Tailwind's `dark:` modifier on the variant classes.
+//
+// @goodPractice: Use cva for variant props — gives autocomplete and runtime safety
+// @goodPractice: Spread remaining props via ...rest for HTML attribute passthrough
+// @goodPractice: Use pointer-events-none during loading to prevent double-clicks
+// @badPractice: Don't omit type="button" — causes unintended form submissions (see BUTTON-001)
+// @badPractice: Don't inline variant styles — breaks dark mode consistency
+// @badPractice: Don't use isLoading boolean alone — use a state machine for complex flows
+// @fixHistory: BUTTON-001 — added type="button" default to prevent form submit
+
+import { cva, type VariantProps } from "class-variance-authority"
+import { Loader2 } from "lucide-react"
+import { memo } from "react"
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 rounded-lg text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        primary:
+          "bg-blue-600 text-white hover:bg-blue-700 dark:bg-blue-500 dark:hover:bg-blue-600",
+        secondary:
+          "bg-gray-100 text-gray-900 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-100 dark:hover:bg-gray-700",
+        danger:
+          "bg-red-600 text-white hover:bg-red-700 dark:bg-red-500 dark:hover:bg-red-600",
+        ghost:
+          "hover:bg-gray-100 hover:text-gray-900 dark:hover:bg-gray-800 dark:hover:text-gray-100",
+        outline:
+          "border border-gray-300 hover:bg-gray-100 dark:border-gray-600 dark:hover:bg-gray-800",
+      },
+      size: {
+        sm: "h-8 px-3 text-xs",
+        default: "h-10 px-4 py-2",
+        lg: "h-12 px-6 text-base",
+        icon: "h-10 w-10",
+      },
+    },
+    defaultVariants: {
+      variant: "primary",
+      size: "default",
+    },
+  }
+)
+
+interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  loading?: boolean
+}
+
+const Button = memo<ButtonProps>(
+  ({ className, variant, size, loading = false, disabled, children, ...rest }) => {
+    return (
+      <button
+        type="button"
+        className={buttonVariants({ variant, size, className })}
+        disabled={disabled || loading}
+        {...rest}
+      >
+        {loading && <Loader2 className="h-4 w-4 animate-spin" />}
+        {children}
+      </button>
+    )
+  }
+)
+Button.displayName = "Button"
+
+export { Button, buttonVariants }

package/src/templates/langs/react/templates/ui/Card.template.tsx

@@ -0,0 +1,85 @@
+// @template
+// @id: card-shadcn
+// @category: ui/data-display
+// @purpose: container, summary, feature-card, dashboard-card
+// @framework: react
+// @style: shadcn
+// @variants: [default, bordered, elevated, interactive]
+// @sizes: [sm, default, full]
+// @darkMode: true
+// @responsive: true
+// @deps: []
+// @props: { title?: string, subtitle?: string, footer?: ReactNode, padding?: boolean }
+// @states: [default, hover, loading]
+// @example: <Card title="Revenue" subtitle="Last 30 days"><p>$12,400</p></Card>
+// @teachMe
+//
+// ## Anatomy
+// Card is a container component with optional header (title + subtitle) and footer.
+// `interactive` variant adds hover elevation and cursor pointer for clickable cards.
+// Can show a Skeleton placeholder when loading.
+//
+// @goodPractice: Use semantic padding scale (p-4, p-6) — never fixed widths
+// @goodPractice: Interactive cards need role="button" + onKeyDown for keyboard a11y
+// @goodPractice: Keep card content self-contained — no external margin dependencies
+// @badPractice: Don't nest cards more than 2 levels deep — reduces readability
+// @badPractice: Don't hard-code min-height on cards — let content determine size
+// @badPractice: Don't use cards for simple text — they add visual noise
+
+import { type ReactNode } from "react"
+
+interface CardProps {
+  title?: string
+  subtitle?: string
+  footer?: ReactNode
+  children: ReactNode
+  variant?: "default" | "bordered" | "elevated" | "interactive"
+  padding?: boolean
+  className?: string
+  onClick?: () => void
+}
+
+const variantStyles: Record<string, string> = {
+  default: "bg-white dark:bg-gray-900 shadow-sm",
+  bordered: "border border-gray-200 dark:border-gray-700",
+  elevated: "bg-white dark:bg-gray-900 shadow-md",
+  interactive: "bg-white dark:bg-gray-900 shadow-sm hover:shadow-md cursor-pointer transition-shadow",
+}
+
+function Card({
+  title,
+  subtitle,
+  footer,
+  children,
+  variant = "default",
+  padding = true,
+  className = "",
+  onClick,
+}: CardProps) {
+  const Tag = onClick ? "button" : "div"
+
+  return (
+    <Tag
+      className={`rounded-xl ${variantStyles[variant]} ${padding ? "p-6" : ""} ${className}`}
+      onClick={onClick}
+      {...(onClick ? { type: "button" as const } : {})}
+    >
+      {(title || subtitle) && (
+        <div className="mb-4">
+          {title && (
+            <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100">{title}</h3>
+          )}
+          {subtitle && (
+            <p className="mt-1 text-sm text-gray-500 dark:text-gray-400">{subtitle}</p>
+          )}
+        </div>
+      )}
+      <div>{children}</div>
+      {footer && (
+        <div className="mt-4 border-t border-gray-100 pt-4 dark:border-gray-800">{footer}</div>
+      )}
+    </Tag>
+  )
+}
+
+export { Card }