maestro-bundle 1.3.1 → 1.4.0

package/templates/bundle-frontend-spa/skills/react-patterns/SKILL.md

@@ -1,81 +1,140 @@
 ---
 name: react-patterns
-description: Implementar padrões React com TypeScript incluindo hooks customizados, composição, render props e HOCs. Use quando for criar componentes React, estruturar features, ou resolver problemas de arquitetura frontend.
+description: Implement React patterns with TypeScript including custom hooks, composition, container/presenter, error boundaries, and forms with validation. Use when you need to create React components, structure features, build forms, or solve frontend architecture problems.
+version: 1.0.0
+author: Maestro
 ---
 
 # React Patterns
 
-## 1. Custom Hooks — Extrair lógica reutilizável
+Apply proven React + TypeScript patterns for scalable, maintainable frontend code.
 
+## When to Use
+- User needs to create a custom hook for data fetching or shared logic
+- User wants to structure a feature using container/presenter pattern
+- User needs to build a form with validation (React Hook Form + Zod)
+- User wants to add error boundaries to catch rendering errors
+- User needs to compose components instead of using deep prop drilling
+
+## Available Operations
+1. Create custom hooks for data fetching with React Query
+2. Build components using composition pattern (slots, children)
+3. Implement container/presenter separation
+4. Add error boundaries with recovery
+5. Build validated forms with React Hook Form + Zod
+
+## Multi-Step Workflow
+
+### Step 1: Set Up Project Dependencies
+```bash
+npm install @tanstack/react-query react-hook-form @hookform/resolvers zod react-error-boundary
+npm install -D @types/react @types/react-dom typescript
+```
+
+### Step 2: Create Custom Hooks for Data Fetching
 ```tsx
-// hooks/useDemands.ts
-export function useDemands(filters?: DemandFilters) {
+// src/hooks/useItems.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { itemApi } from '../services/itemApi';
+import { toast } from 'sonner';
+
+export function useItems(filters?: ItemFilters) {
   return useQuery({
-    queryKey: ['demands', filters],
-    queryFn: () => demandApi.list(filters),
+    queryKey: ['items', filters],
+    queryFn: () => itemApi.list(filters),
     staleTime: 30_000,
   });
 }
 
-export function useCreateDemand() {
+export function useItem(id: string) {
+  return useQuery({
+    queryKey: ['items', id],
+    queryFn: () => itemApi.get(id),
+    enabled: !!id,
+  });
+}
+
+export function useCreateItem() {
   const queryClient = useQueryClient();
   return useMutation({
-    mutationFn: demandApi.create,
+    mutationFn: itemApi.create,
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['demands'] });
-      toast.success('Demanda criada');
+      queryClient.invalidateQueries({ queryKey: ['items'] });
+      toast.success('Item created');
     },
     onError: (err) => toast.error(err.message),
   });
 }
 ```
 
-## 2. Composição > Herança
-
+### Step 3: Build Components with Composition
 ```tsx
-// Compor componentes pequenos
-function DemandCard({ demand }: { demand: Demand }) {
-  return (
-    <Card>
-      <Card.Header>
-        <Card.Title>{demand.title}</Card.Title>
-        <StatusBadge status={demand.status} />
-      </Card.Header>
-      <Card.Content>
-        <AgentTeamList agents={demand.assignedAgents} />
-      </Card.Content>
-      <Card.Footer>
-        <TaskProgress tasks={demand.tasks} />
-      </Card.Footer>
-    </Card>
-  );
+// src/components/Card.tsx
+interface CardProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export function Card({ children, className }: CardProps) {
+  return <div className={cn('rounded-lg border bg-white shadow-sm', className)}>{children}</div>;
 }
-```
 
-## 3. Container/Presenter
+Card.Header = function CardHeader({ children }: { children: React.ReactNode }) {
+  return <div className="flex items-center justify-between p-4 border-b">{children}</div>;
+};
+
+Card.Content = function CardContent({ children }: { children: React.ReactNode }) {
+  return <div className="p-4">{children}</div>;
+};
+
+Card.Footer = function CardFooter({ children }: { children: React.ReactNode }) {
+  return <div className="p-4 border-t bg-gray-50">{children}</div>;
+};
+
+// Usage:
+<Card>
+  <Card.Header>
+    <h3>{item.title}</h3>
+    <StatusBadge status={item.status} />
+  </Card.Header>
+  <Card.Content>
+    <p>{item.description}</p>
+  </Card.Content>
+  <Card.Footer>
+    <ProgressBar value={item.progress} />
+  </Card.Footer>
+</Card>
+```
 
+### Step 4: Implement Container/Presenter Pattern
 ```tsx
-// Container — lógica e estado
-function DemandListContainer() {
-  const { data, isLoading, error } = useDemands();
+// Container: owns data fetching and state
+function ItemListContainer() {
+  const { data, isLoading, error } = useItems();
   const [selected, setSelected] = useState<string | null>(null);
 
   if (isLoading) return <Skeleton />;
   if (error) return <ErrorState message={error.message} />;
 
-  return <DemandList demands={data!} selected={selected} onSelect={setSelected} />;
+  return <ItemList items={data!} selected={selected} onSelect={setSelected} />;
+}
+
+// Presenter: pure rendering, easy to test
+interface ItemListProps {
+  items: Item[];
+  selected: string | null;
+  onSelect: (id: string) => void;
 }
 
-// Presenter — apenas renderização
-function DemandList({ demands, selected, onSelect }: DemandListProps) {
+function ItemList({ items, selected, onSelect }: ItemListProps) {
   return (
     <div className="grid gap-4">
-      {demands.map(d => (
-        <DemandCard
-          key={d.id}
-          demand={d}
-          isSelected={d.id === selected}
-          onClick={() => onSelect(d.id)}
+      {items.map((item) => (
+        <ItemCard
+          key={item.id}
+          item={item}
+          isSelected={item.id === selected}
+          onClick={() => onSelect(item.id)}
         />
       ))}
     </div>
@@ -83,48 +142,114 @@ function DemandList({ demands, selected, onSelect }: DemandListProps) {
 }
 ```
 
-## 4. Error Boundary
-
+### Step 5: Add Error Boundaries
 ```tsx
-function AppErrorBoundary({ children }: { children: React.ReactNode }) {
+// src/components/AppErrorBoundary.tsx
+import { ErrorBoundary } from 'react-error-boundary';
+
+function ErrorFallback({ error, resetErrorBoundary }: { error: Error; resetErrorBoundary: () => void }) {
   return (
-    <ErrorBoundary
-      fallback={({ error, resetErrorBoundary }) => (
-        <div className="p-8 text-center">
-          <h2>Algo deu errado</h2>
-          <p>{error.message}</p>
-          <Button onClick={resetErrorBoundary}>Tentar novamente</Button>
-        </div>
-      )}
-    >
-      {children}
-    </ErrorBoundary>
+    <div className="p-8 text-center">
+      <h2 className="text-xl font-bold text-red-600">Something went wrong</h2>
+      <p className="mt-2 text-gray-600">{error.message}</p>
+      <button onClick={resetErrorBoundary} className="mt-4 px-4 py-2 bg-blue-600 text-white rounded">
+        Try again
+      </button>
+    </div>
   );
 }
-```
 
-## 5. Formulários com React Hook Form + Zod
+export function AppErrorBoundary({ children }: { children: React.ReactNode }) {
+  return <ErrorBoundary FallbackComponent={ErrorFallback}>{children}</ErrorBoundary>;
+}
+```
 
+### Step 6: Build Validated Forms
 ```tsx
-const demandSchema = z.object({
-  title: z.string().min(3, 'Mínimo 3 caracteres'),
-  description: z.string().min(10),
+// src/features/items/CreateItemForm.tsx
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+
+const itemSchema = z.object({
+  title: z.string().min(3, 'Title must be at least 3 characters'),
+  description: z.string().min(10, 'Description must be at least 10 characters'),
   priority: z.enum(['low', 'medium', 'high']),
 });
 
-function CreateDemandForm() {
-  const { register, handleSubmit, formState: { errors } } = useForm({
-    resolver: zodResolver(demandSchema),
+type ItemFormData = z.infer<typeof itemSchema>;
+
+export function CreateItemForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm<ItemFormData>({
+    resolver: zodResolver(itemSchema),
   });
-  const createDemand = useCreateDemand();
+  const createItem = useCreateItem();
 
   return (
-    <form onSubmit={handleSubmit(data => createDemand.mutate(data))}>
-      <Input {...register('title')} error={errors.title?.message} />
-      <Textarea {...register('description')} error={errors.description?.message} />
-      <Select {...register('priority')} options={['low', 'medium', 'high']} />
-      <Button type="submit" loading={createDemand.isPending}>Criar</Button>
+    <form onSubmit={handleSubmit((data) => createItem.mutate(data))}>
+      <div>
+        <label htmlFor="title">Title</label>
+        <input id="title" {...register('title')} className="border rounded p-2 w-full" />
+        {errors.title && <p className="text-red-500 text-sm">{errors.title.message}</p>}
+      </div>
+
+      <div>
+        <label htmlFor="description">Description</label>
+        <textarea id="description" {...register('description')} className="border rounded p-2 w-full" />
+        {errors.description && <p className="text-red-500 text-sm">{errors.description.message}</p>}
+      </div>
+
+      <div>
+        <label htmlFor="priority">Priority</label>
+        <select id="priority" {...register('priority')} className="border rounded p-2 w-full">
+          <option value="low">Low</option>
+          <option value="medium">Medium</option>
+          <option value="high">High</option>
+        </select>
+      </div>
+
+      <button type="submit" disabled={createItem.isPending} className="mt-4 px-4 py-2 bg-blue-600 text-white rounded">
+        {createItem.isPending ? 'Creating...' : 'Create'}
+      </button>
     </form>
   );
 }
 ```
+
+### Step 7: Verify the Pattern Works
+```bash
+npm run dev
+# Open http://localhost:5173 and test the feature
+
+npm run type-check
+# or: npx tsc --noEmit
+```
+
+## Resources
+- `references/hook-patterns.md` - Custom hook patterns and anti-patterns
+- `references/component-checklist.md` - Quality checklist for React components
+
+## Examples
+### Example 1: Create a Data Fetching Hook
+User asks: "Create a hook to fetch and cache user profiles"
+Response approach:
+1. Create `useUser(id)` and `useUsers(filters)` hooks using React Query
+2. Add `useCreateUser()` mutation with cache invalidation
+3. Add toast notifications for success/error states
+4. Show usage in a container component
+
+### Example 2: Build a Feature Module
+User asks: "Create the orders feature with list, detail, and create form"
+Response approach:
+1. Create `useOrders()` and `useCreateOrder()` hooks
+2. Build `OrderList` presenter and `OrderListContainer`
+3. Build `CreateOrderForm` with Zod validation
+4. Wrap in `ErrorBoundary`
+5. Add route entries and test with `npm run dev`
+
+## Notes
+- Prefer composition (children, render props) over configuration (boolean props)
+- Never duplicate API data in Zustand -- use React Query for server state
+- Keep presenters pure: no hooks, no side effects, just props and JSX
+- Always type props with TypeScript interfaces, not `any`
+- Use `enabled: !!id` in useQuery to prevent fetching with empty IDs

package/templates/bundle-frontend-spa/skills/react-patterns/references/component-checklist.md

@@ -0,0 +1,22 @@
+# Component Quality Checklist
+
+## Before Shipping a Component
+- [ ] Props are typed with a TypeScript interface (not `any`)
+- [ ] Component has a single, clear responsibility
+- [ ] Loading, error, and empty states are handled
+- [ ] Accessible: has aria-labels, keyboard navigation where needed
+- [ ] No business logic in presenter components
+- [ ] Uses composition (children/slots) over boolean prop flags
+- [ ] All event handlers are properly typed
+- [ ] No inline styles -- uses Tailwind classes or CSS modules
+
+## Performance
+- [ ] Lists use unique `key` props (not array index)
+- [ ] Heavy computations wrapped in `useMemo`
+- [ ] Callbacks passed to children wrapped in `useCallback` when needed
+- [ ] Large components are code-split with `React.lazy()`
+
+## Testing
+- [ ] Presenter components have unit tests with React Testing Library
+- [ ] Custom hooks have tests using `renderHook`
+- [ ] Edge cases tested: empty data, error states, loading states

package/templates/bundle-frontend-spa/skills/react-patterns/references/hook-patterns.md

@@ -0,0 +1,63 @@
+# Custom Hook Patterns
+
+## Data Fetching Hook (React Query)
+```tsx
+export function useItems(filters?: Filters) {
+  return useQuery({
+    queryKey: ['items', filters],
+    queryFn: () => api.list(filters),
+    staleTime: 30_000,         // cache for 30s
+    retry: 2,                  // retry failed requests twice
+    enabled: filters !== undefined, // conditional fetching
+  });
+}
+```
+
+## Mutation Hook with Cache Invalidation
+```tsx
+export function useCreateItem() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: api.create,
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: ['items'] });
+      toast.success('Created');
+    },
+    onError: (err) => toast.error(err.message),
+  });
+}
+```
+
+## Debounced Value Hook
+```tsx
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+  return debounced;
+}
+```
+
+## Local Storage Hook
+```tsx
+export function useLocalStorage<T>(key: string, initial: T) {
+  const [value, setValue] = useState<T>(() => {
+    const stored = localStorage.getItem(key);
+    return stored ? JSON.parse(stored) : initial;
+  });
+
+  useEffect(() => {
+    localStorage.setItem(key, JSON.stringify(value));
+  }, [key, value]);
+
+  return [value, setValue] as const;
+}
+```
+
+## Anti-Patterns to Avoid
+1. Do NOT call hooks conditionally (`if (x) useEffect(...)`)
+2. Do NOT duplicate server state in useState -- use React Query
+3. Do NOT create hooks that do too many things -- split them
+4. Do NOT forget cleanup in useEffect return functions

package/templates/bundle-frontend-spa/skills/responsive-layout/SKILL.md

@@ -1,19 +1,55 @@
 ---
 name: responsive-layout
-description: Criar layouts responsivos com Tailwind CSS incluindo sidebar, dashboard grid e mobile-first design. Use quando for criar layouts de página, dashboards, ou interfaces responsivas.
+description: Create responsive layouts with Tailwind CSS including sidebar navigation, dashboard grids, and mobile-first design. Use when you need to build page layouts, dashboards, responsive grids, or navigation structures.
+version: 1.0.0
+author: Maestro
 ---
 
 # Responsive Layout
 
-## Layout Principal do Maestro
+Build mobile-first responsive layouts using Tailwind CSS with sidebar navigation, dashboard grids, and adaptive content areas.
 
+## When to Use
+- User needs to create a page layout with sidebar and header
+- User wants to build a responsive dashboard with metric cards
+- User needs a mobile-first grid that adapts to screen sizes
+- User wants to add responsive navigation (sidebar + mobile menu)
+- User needs to structure a page with proper spacing and overflow handling
+
+## Available Operations
+1. Create a full app layout (sidebar + header + main content)
+2. Build responsive dashboard grids with metric cards
+3. Implement collapsible sidebar with mobile drawer
+4. Set up responsive content grids
+5. Add proper scroll areas and overflow handling
+
+## Multi-Step Workflow
+
+### Step 1: Install Dependencies
+```bash
+npm install clsx tailwind-merge lucide-react
+```
+
+Verify Tailwind is configured:
+```bash
+npx tailwindcss --help
+# If not installed: npm install -D tailwindcss postcss autoprefixer && npx tailwindcss init -p
+```
+
+### Step 2: Create the App Shell Layout
 ```tsx
-function AppLayout({ children }: { children: React.ReactNode }) {
-  const { sidebarOpen } = useAppStore();
+// src/layouts/AppLayout.tsx
+import { useAppStore } from '@/stores/useAppStore';
+
+export function AppLayout({ children }: { children: React.ReactNode }) {
+  const sidebarOpen = useAppStore((s) => s.sidebarOpen);
 
   return (
     <div className="flex h-screen bg-gray-50">
+      {/* Sidebar */}
       <Sidebar open={sidebarOpen} />
+
+      {/* Main area */}
       <div className="flex-1 flex flex-col overflow-hidden">
         <Header />
         <main className="flex-1 overflow-y-auto p-4 md:p-6 lg:p-8">
@@ -25,41 +61,145 @@ function AppLayout({ children }: { children: React.ReactNode }) {
 }
 ```
 
-## Dashboard Grid
+### Step 3: Build the Sidebar
+```tsx
+// src/components/Sidebar.tsx
+import { NavLink } from 'react-router-dom';
+import { Home, List, Users, Settings, X } from 'lucide-react';
+import { useAppStore } from '@/stores/useAppStore';
+
+const navItems = [
+  { to: '/dashboard', label: 'Dashboard', icon: Home },
+  { to: '/items', label: 'Items', icon: List },
+  { to: '/team', label: 'Team', icon: Users },
+  { to: '/settings', label: 'Settings', icon: Settings },
+];
+
+export function Sidebar({ open }: { open: boolean }) {
+  const toggleSidebar = useAppStore((s) => s.toggleSidebar);
+
+  return (
+    <>
+      {/* Mobile overlay */}
+      {open && (
+        <div className="fixed inset-0 bg-black/50 z-40 lg:hidden" onClick={toggleSidebar} />
+      )}
+
+      {/* Sidebar */}
+      <aside
+        className={cn(
+          'fixed lg:static inset-y-0 left-0 z-50 w-64 bg-white border-r transform transition-transform lg:translate-x-0',
+          open ? 'translate-x-0' : '-translate-x-full'
+        )}
+      >
+        <div className="flex items-center justify-between p-4 border-b">
+          <h1 className="text-xl font-bold">App Name</h1>
+          <button onClick={toggleSidebar} className="lg:hidden">
+            <X className="w-5 h-5" />
+          </button>
+        </div>
 
+        <nav className="p-4 space-y-1">
+          {navItems.map((item) => (
+            <NavLink
+              key={item.to}
+              to={item.to}
+              className={({ isActive }) =>
+                cn('flex items-center gap-3 px-3 py-2 rounded-lg text-sm',
+                  isActive ? 'bg-blue-50 text-blue-700 font-medium' : 'text-gray-600 hover:bg-gray-100'
+                )
+              }
+            >
+              <item.icon className="w-5 h-5" />
+              {item.label}
+            </NavLink>
+          ))}
+        </nav>
+      </aside>
+    </>
+  );
+}
+```
+
+### Step 4: Build a Dashboard Grid
 ```tsx
-function Dashboard() {
+// src/pages/Dashboard.tsx
+import { Activity, Users, Shield, CheckCircle } from 'lucide-react';
+
+export function Dashboard() {
   return (
     <div className="space-y-6">
-      {/* Métricas top-level */}
+      {/* Metric cards: 1 col mobile, 2 cols tablet, 4 cols desktop */}
       <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
-        <MetricCard title="Demands Ativas" value={12} icon={<Activity />} />
-        <MetricCard title="Agentes Online" value={8} icon={<Bot />} />
-        <MetricCard title="Compliance Rate" value="94%" icon={<Shield />} />
-        <MetricCard title="Tasks Hoje" value={47} icon={<CheckCircle />} />
+        <MetricCard title="Active Items" value={12} icon={<Activity className="w-5 h-5" />} />
+        <MetricCard title="Team Members" value={8} icon={<Users className="w-5 h-5" />} />
+        <MetricCard title="Compliance" value="94%" icon={<Shield className="w-5 h-5" />} />
+        <MetricCard title="Tasks Today" value={47} icon={<CheckCircle className="w-5 h-5" />} />
       </div>
 
-      {/* Conteúdo principal */}
+      {/* Two-column layout: 2/3 + 1/3 on desktop, stacked on mobile */}
       <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
         <div className="lg:col-span-2">
-          <AgentActivityFeed />
+          <ActivityFeed />
         </div>
         <div>
-          <ActiveDemandsList />
+          <RecentItemsList />
         </div>
       </div>
     </div>
   );
 }
+
+function MetricCard({ title, value, icon }: { title: string; value: string | number; icon: React.ReactNode }) {
+  return (
+    <div className="bg-white rounded-lg border p-4">
+      <div className="flex items-center justify-between">
+        <span className="text-sm text-gray-600">{title}</span>
+        <span className="text-gray-400">{icon}</span>
+      </div>
+      <p className="mt-2 text-2xl font-bold">{value}</p>
+    </div>
+  );
+}
 ```
 
-## Breakpoints Tailwind
+### Step 5: Verify Responsive Behavior
+```bash
+npm run dev
+# Open http://localhost:5173
+
+# Test responsive breakpoints:
+# 1. Resize browser window through breakpoints (640px, 768px, 1024px, 1280px)
+# 2. Use browser DevTools device toolbar (Ctrl+Shift+M / Cmd+Shift+M)
+# 3. Check sidebar collapses on mobile and shows overlay
+# 4. Check grid columns adjust at each breakpoint
+```
+
+## Resources
+- `references/breakpoint-guide.md` - Tailwind breakpoints and responsive patterns
+
+## Examples
+### Example 1: Create a Dashboard Layout
+User asks: "Build a dashboard page with stats cards and an activity feed"
+Response approach:
+1. Create AppLayout with sidebar and header
+2. Build MetricCard component for stats
+3. Use responsive grid: 1->2->4 columns
+4. Add two-column section for feed + sidebar content
+5. Test at all breakpoints with `npm run dev`
 
-| Prefix | Min-width | Uso |
-|---|---|---|
-| `sm:` | 640px | Mobile landscape |
-| `md:` | 768px | Tablet |
-| `lg:` | 1024px | Desktop |
-| `xl:` | 1280px | Desktop wide |
+### Example 2: Add Mobile Navigation
+User asks: "Make the sidebar work on mobile devices"
+Response approach:
+1. Make sidebar fixed/absolute on mobile with transform transition
+2. Add overlay backdrop that closes sidebar on tap
+3. Add hamburger menu button in Header (visible only on mobile: `lg:hidden`)
+4. Connect to Zustand toggleSidebar action
+5. Test on mobile viewport in DevTools
 
-Sempre **mobile-first**: escrever para mobile, depois adicionar breakpoints maiores.
+## Notes
+- Always design mobile-first: write base styles for mobile, then add `sm:`, `md:`, `lg:` overrides
+- Use `overflow-hidden` on the app shell and `overflow-y-auto` on scrollable content areas
+- Use `fixed` positioning for mobile sidebar/drawer, `static` for desktop
+- Add `transition-transform` for smooth sidebar open/close animations
+- Test at every Tailwind breakpoint: 640px, 768px, 1024px, 1280px