@adlas/create-app 1.0.0

package/templates/docs/AI_QUICK_REFERENCE.md

@@ -0,0 +1,379 @@
+# AI Quick Reference Guide
+
+This is your go-to reference for implementing features in the Berndorf e-commerce project. Use this guide to quickly understand the critical rules, available components, and common patterns.
+
+## Critical Rules
+
+### DO
+
+- **ALWAYS use existing UI components** from `/src/components/ui/`
+- **ALWAYS use existing element components** from `/src/components/elements/`
+- **ALWAYS follow the service module pattern** for new features
+- **ALWAYS use react-hook-form** for forms
+- **ALWAYS use Zod** for validation
+- **ALWAYS use Zustand** for global state
+- **ALWAYS use React Query** (@tanstack/react-query) for data fetching
+- **ALWAYS use next-intl** for translations (English: `en.json`, German: `de.json`)
+- **ALWAYS use HeroUI components** as the base for UI
+- **ALWAYS use Tailwind CSS** for styling
+- **ALWAYS check existing patterns** before implementing new features
+
+### DON'T
+
+- **NEVER install new UI libraries** (we use HeroUI)
+- **NEVER install new state management libraries** (we use Zustand)
+- **NEVER install new form libraries** (we use react-hook-form)
+- **NEVER install new validation libraries** (we use Zod)
+- **NEVER create custom UI components** if HeroUI provides them
+- **NEVER use inline styles** (use Tailwind classes)
+- **NEVER hardcode strings** (use translations)
+- **NEVER fetch data without React Query**
+- **NEVER create global state without Zustand**
+
+## Available UI Components
+
+All components are from **HeroUI** and extended in `/src/components/ui/`:
+
+### Form Components
+- **Input** - Text input with label placement outside
+- **PasswordInput** - Password field with show/hide toggle
+- **Textarea** - Multi-line text input
+- **Select** - Dropdown selection
+- **Autocomplete** - Searchable dropdown
+- **Checkbox** - Single checkbox
+- **RadioGroup** - Radio button group
+- **NumberInput** - Numeric input
+- **FileInput** - File upload
+- **DocumentUpload** - Document upload with validation
+- **DatePicker** - Date selection
+
+### Display Components
+- **Button** - Action button with variants
+- **Chip** - Small badge/tag
+- **Modal** - Dialog/popup
+- **Tabs** - Tab navigation
+- **Breadcrumbs** - Breadcrumb navigation
+- **Carousel** - Image/content carousel
+- **Icon** - Icon component
+
+### Form System
+- **Form** - Form wrapper with validation
+- **FormItem** - Individual form field wrapper
+- **FormGenerator** - Dynamic form generation
+
+## Code Templates
+
+### 1. Service Module Structure
+
+```typescript
+// src/services/[feature]/index.ts
+export * from './api/[feature].api';
+export * from './queries/[feature].queries';
+export * from './hooks/use[Feature]';
+export * from './types/[feature].types';
+export * from './actions/[feature].actions';
+export * from './store/[feature].store';
+```
+
+### 2. API Client
+
+```typescript
+// src/services/[feature]/api/[feature].api.ts
+import { apiRequest } from '@/lib/apiRequest';
+import type { FeatureResponse } from '../types/[feature].types';
+
+export async function getFeatureData(): Promise<FeatureResponse> {
+  const response = await apiRequest<FeatureResponse>({
+    url: '/api/feature',
+    method: 'GET',
+  });
+  return response;
+}
+```
+
+### 3. React Query Hook
+
+```typescript
+// src/services/[feature]/queries/[feature].queries.ts
+import { useQuery } from '@tanstack/react-query';
+import { getFeatureData } from '../api/[feature].api';
+
+export function useFeatureQuery() {
+  return useQuery({
+    queryKey: ['feature'],
+    queryFn: getFeatureData,
+  });
+}
+```
+
+### 4. Zustand Store
+
+```typescript
+// src/services/[feature]/store/[feature].store.ts
+import { create } from 'zustand';
+
+interface FeatureStore {
+  data: string | null;
+  setData: (data: string) => void;
+  reset: () => void;
+}
+
+export const useFeatureStore = create<FeatureStore>((set) => ({
+  data: null,
+  setData: (data) => set({ data }),
+  reset: () => set({ data: null }),
+}));
+```
+
+### 5. Form with Validation
+
+```tsx
+// Component with form
+'use client';
+import { useForm } from 'react-hook-form';
+import { z } from 'zod';
+import { Form } from '@/components/ui/form/Form';
+import { Input } from '@/components/ui/Input';
+import { Button } from '@/components/ui/Button';
+
+const schema = z.object({
+  email: z.string().email('Errors.validation.email'),
+  name: z.string().min(1, 'Errors.validation.required'),
+});
+
+type FormData = z.infer<typeof schema>;
+
+export function MyForm() {
+  const form = useForm<FormData>({
+    resolver: zodResolver(schema),
+  });
+
+  const onSubmit = (data: FormData) => {
+    console.log(data);
+  };
+
+  return (
+    <Form form={form} validationSchema={schema}>
+      <Form.Item name="email">
+        {(props) => <Input {...props} label="Email" />}
+      </Form.Item>
+      <Form.Item name="name">
+        {(props) => <Input {...props} label="Name" />}
+      </Form.Item>
+      <Button onPress={form.handleSubmit(onSubmit)}>Submit</Button>
+    </Form>
+  );
+}
+```
+
+### 6. Server Action
+
+```typescript
+// src/services/[feature]/actions/[feature].actions.ts
+'use server';
+import { cookies } from 'next/headers';
+
+export async function featureAction(data: FormData) {
+  try {
+    const response = await fetch('https://api.example.com/feature', {
+      method: 'POST',
+      body: JSON.stringify(data),
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      return { success: false, error: 'Action failed' };
+    }
+
+    return { success: true };
+  } catch (error) {
+    return { success: false, error: 'Unexpected error' };
+  }
+}
+```
+
+### 7. Translation Usage
+
+```tsx
+// In a client component
+'use client';
+import { useTranslations } from 'next-intl';
+
+export function MyComponent() {
+  const t = useTranslations('MyNamespace');
+
+  return <h1>{t('title')}</h1>;
+}
+```
+
+Add to `/src/locales/en.json`:
+```json
+{
+  "MyNamespace": {
+    "title": "My Title"
+  }
+}
+```
+
+## Styling Quick Reference
+
+### Tailwind CSS Classes
+
+```tsx
+// Layout
+className="flex flex-col gap-4"
+className="grid grid-cols-2 gap-6"
+className="container mx-auto px-4"
+
+// Spacing
+className="p-4 m-4"          // padding & margin
+className="px-6 py-4"        // horizontal & vertical
+className="gap-4"            // gap between items
+
+// Typography
+className="text-sm font-medium leading-5"
+className="text-base font-semibold leading-6"
+className="text-xl font-bold"
+
+// Colors (HeroUI tokens)
+className="text-default-600"    // gray text
+className="bg-primary"          // primary background
+className="border-default-400"  // border color
+
+// Responsive
+className="max-sm:hidden"       // hide on small screens
+className="max-xs:col-span-10"  // full width on extra small
+```
+
+### HeroUI Color Tokens
+
+- **default** - Gray scale (50, 100, 200, ..., 900)
+- **primary** - Primary brand color
+- **secondary** - Secondary brand color
+- **success** - Green for success states
+- **warning** - Yellow for warnings
+- **danger** - Red for errors
+- **foreground** - Text color
+- **background** - Background color
+
+## Common Patterns
+
+### 1. Protected Route
+
+```tsx
+// Use middleware.ts for route protection
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get('auth-token');
+
+  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/auth/login', request.url));
+  }
+}
+```
+
+### 2. Mutation with Toast
+
+```tsx
+import { useMutation } from '@tanstack/react-query';
+import { toast } from 'sonner';
+
+const mutation = useMutation({
+  mutationFn: submitData,
+  onSuccess: () => {
+    toast.success('Success!');
+  },
+  onError: (error) => {
+    toast.error(error.message);
+  },
+});
+```
+
+### 3. Conditional Rendering
+
+```tsx
+// Using conditional
+{isLoading ? <Spinner /> : <Content />}
+
+// Using optional chaining
+{data?.items?.map(item => <Item key={item.id} {...item} />)}
+```
+
+### 4. Image Handling
+
+```tsx
+import Image from 'next/image';
+
+<Image
+  src="/images/logo.png"
+  alt="Logo"
+  width={200}
+  height={100}
+  className="object-cover"
+/>
+```
+
+## Implementation Workflow
+
+1. **Analyze Figma Design**
+   - Use Figma MCP Server to inspect design
+   - Map colors, spacing, typography to existing tokens
+   - Identify which UI components to use
+
+2. **Create Service Module**
+   - Create folder: `/src/services/[feature]/`
+   - Add: `api/`, `queries/`, `hooks/`, `types/`, `actions/`, `store/`
+   - Export all from `index.ts`
+
+3. **Add Translations**
+   - Add English keys to `/src/locales/en.json`
+   - Add German keys to `/src/locales/de.json`
+
+4. **Build Components**
+   - Use existing UI components from `/src/components/ui/`
+   - Use existing elements from `/src/components/elements/`
+   - Never install new UI libraries
+
+5. **Implement Forms**
+   - Use `react-hook-form` + `zod`
+   - Use `Form` and `Form.Item` from `/src/components/ui/form/`
+   - Add validation schemas
+
+6. **Test & Validate**
+   - Test form validation
+   - Test API calls
+   - Test translations
+   - Test responsive design
+
+## Quick Checklist
+
+Before implementing any feature:
+
+- [ ] Checked existing components in `/src/components/ui/`
+- [ ] Checked existing elements in `/src/components/elements/`
+- [ ] Checked existing patterns in `/src/services/`
+- [ ] Reviewed Figma design thoroughly
+- [ ] Mapped design tokens to existing values
+- [ ] Planned service module structure
+- [ ] Prepared translation keys
+- [ ] No new UI libraries needed
+
+## Common Pitfalls
+
+1. **Installing new libraries** - Use existing tech stack
+2. **Hardcoding strings** - Always use translations
+3. **Creating custom UI components** - Use HeroUI extended components
+4. **Direct fetch calls** - Use React Query
+5. **Untyped data** - Always define TypeScript types
+6. **Missing translations** - Add to both en.json and de.json
+7. **Inconsistent spacing** - Use Tailwind spacing scale
+8. **Ignoring responsive design** - Test on all screen sizes
+
+## Need More Details?
+
+- **UI Components** → See `UI_COMPONENTS_GUIDE.md`
+- **Architecture** → See `ARCHITECTURE_PATTERNS.md`
+- **Implementation Steps** → See `IMPLEMENTATION_GUIDE.md`
+- **Figma to Code** → See `FIGMA_TO_CODE_GUIDE.md`
+- **Documentation Index** → See `DOCUMENTATION_INDEX.md`