@mind-fold/open-flow 0.1.17 → 0.2.2

package/dist/templates/markdown/structure/frontend/component-guidelines.md.txt

@@ -0,0 +1,335 @@
+# Component Guidelines
+
+> Component patterns, semantic HTML, and accessibility
+
+---
+
+## Component Structure
+
+### Basic Component
+
+```typescript
+import { type ComponentProps } from 'react';
+import { cn } from '@/lib/utils';
+
+interface UserCardProps {
+  user: User;
+  onClick?: () => void;
+  className?: string;
+}
+
+export function UserCard({ user, onClick, className }: UserCardProps) {
+  return (
+    <article 
+      className={cn('rounded-lg border p-4', className)}
+      onClick={onClick}
+    >
+      <h3>{user.name}</h3>
+      <p>{user.email}</p>
+    </article>
+  );
+}
+```
+
+### Component with Children
+
+```typescript
+interface CardProps {
+  title: string;
+  children: React.ReactNode;
+  footer?: React.ReactNode;
+}
+
+export function Card({ title, children, footer }: CardProps) {
+  return (
+    <article className="card">
+      <header>
+        <h2>{title}</h2>
+      </header>
+      <div className="card-content">
+        {children}
+      </div>
+      {footer && (
+        <footer className="card-footer">
+          {footer}
+        </footer>
+      )}
+    </article>
+  );
+}
+```
+
+---
+
+## Semantic HTML
+
+Use proper HTML elements for their intended purpose.
+
+### Interactive Elements
+
+```typescript
+// ✅ GOOD: Use button for actions
+<button onClick={handleClick}>Click me</button>
+
+// ❌ BAD: Don't use div as button
+<div role="button" onClick={handleClick}>Click me</div>
+```
+
+### Links vs Buttons
+
+```typescript
+// Button: triggers an action
+<button onClick={handleSubmit}>Submit</button>
+
+// Link: navigates to a URL
+<Link href="/about">About</Link>
+
+// ❌ BAD: Button that looks like a link but navigates
+<button onClick={() => router.push('/about')}>About</button>
+```
+
+### Headings
+
+```typescript
+// ✅ GOOD: Proper heading hierarchy
+<article>
+  <h1>Page Title</h1>
+  <section>
+    <h2>Section Title</h2>
+    <h3>Subsection</h3>
+  </section>
+</article>
+
+// ❌ BAD: Skipping heading levels
+<h1>Title</h1>
+<h3>Subsection</h3>  // Missing h2
+```
+
+### Lists
+
+```typescript
+// ✅ GOOD: Use list elements for lists
+<ul>
+  {items.map(item => (
+    <li key={item.id}>{item.name}</li>
+  ))}
+</ul>
+
+// ❌ BAD: Divs for list
+<div>
+  {items.map(item => (
+    <div key={item.id}>{item.name}</div>
+  ))}
+</div>
+```
+
+---
+
+## Image Optimization
+
+### Next.js Image Component
+
+```typescript
+import Image from 'next/image';
+
+// ✅ GOOD: Use Next.js Image
+<Image 
+  src="/avatar.png" 
+  alt="User avatar"
+  width={100}
+  height={100}
+/>
+
+// ❌ BAD: Native img tag
+<img src="/avatar.png" alt="User avatar" />
+```
+
+### External Images
+
+```typescript
+// next.config.js - configure allowed domains
+module.exports = {
+  images: {
+    remotePatterns: [
+      { protocol: 'https', hostname: '*.example.com' },
+    ],
+  },
+};
+
+// Component
+<Image
+  src="https://cdn.example.com/avatar.png"
+  alt="Avatar"
+  width={100}
+  height={100}
+/>
+```
+
+---
+
+## Accessibility
+
+### Labels for Inputs
+
+```typescript
+// ✅ GOOD: Associated label
+<label htmlFor="email">Email</label>
+<input id="email" type="email" />
+
+// ✅ GOOD: Implicit label
+<label>
+  Email
+  <input type="email" />
+</label>
+
+// ❌ BAD: No label
+<input type="email" placeholder="Email" />
+```
+
+### ARIA Attributes
+
+```typescript
+// Loading state
+<button disabled={isLoading} aria-busy={isLoading}>
+  {isLoading ? 'Loading...' : 'Submit'}
+</button>
+
+// Error state
+<input 
+  aria-invalid={!!error}
+  aria-describedby={error ? 'email-error' : undefined}
+/>
+{error && <span id="email-error">{error}</span>}
+
+// Modal dialog
+<dialog aria-modal="true" aria-labelledby="dialog-title">
+  <h2 id="dialog-title">Confirm Action</h2>
+</dialog>
+```
+
+### Keyboard Navigation
+
+```typescript
+// Handle keyboard events for custom interactive elements
+function Dropdown({ items }: { items: Item[] }) {
+  const [activeIndex, setActiveIndex] = useState(0);
+  
+  const handleKeyDown = (e: KeyboardEvent) => {
+    switch (e.key) {
+      case 'ArrowDown':
+        setActiveIndex(i => Math.min(i + 1, items.length - 1));
+        break;
+      case 'ArrowUp':
+        setActiveIndex(i => Math.max(i - 1, 0));
+        break;
+      case 'Enter':
+        selectItem(items[activeIndex]);
+        break;
+    }
+  };
+  
+  return (
+    <ul role="listbox" onKeyDown={handleKeyDown}>
+      {items.map((item, index) => (
+        <li 
+          key={item.id}
+          role="option"
+          aria-selected={index === activeIndex}
+        >
+          {item.name}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+---
+
+## Component Patterns
+
+### Compound Components
+
+```typescript
+// Card.tsx
+const CardContext = createContext<{ variant: string } | null>(null);
+
+function Card({ children, variant = 'default' }) {
+  return (
+    <CardContext.Provider value={{ variant }}>
+      <article className={cn('card', variant)}>
+        {children}
+      </article>
+    </CardContext.Provider>
+  );
+}
+
+Card.Header = function CardHeader({ children }) {
+  return <header className="card-header">{children}</header>;
+};
+
+Card.Body = function CardBody({ children }) {
+  return <div className="card-body">{children}</div>;
+};
+
+Card.Footer = function CardFooter({ children }) {
+  return <footer className="card-footer">{children}</footer>;
+};
+
+// Usage
+<Card variant="elevated">
+  <Card.Header>Title</Card.Header>
+  <Card.Body>Content</Card.Body>
+  <Card.Footer>Actions</Card.Footer>
+</Card>
+```
+
+### Controlled vs Uncontrolled
+
+```typescript
+interface InputProps {
+  value?: string;           // Controlled
+  defaultValue?: string;    // Uncontrolled
+  onChange?: (value: string) => void;
+}
+
+function Input({ value, defaultValue, onChange }: InputProps) {
+  const [internalValue, setInternalValue] = useState(defaultValue ?? '');
+  
+  const isControlled = value !== undefined;
+  const currentValue = isControlled ? value : internalValue;
+  
+  const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
+    if (!isControlled) {
+      setInternalValue(e.target.value);
+    }
+    onChange?.(e.target.value);
+  };
+  
+  return <input value={currentValue} onChange={handleChange} />;
+}
+```
+
+---
+
+## Best Practices
+
+### DO
+
+- Use semantic HTML elements
+- Include alt text for images
+- Associate labels with inputs
+- Handle loading and error states
+- Use TypeScript for props
+
+### DON'T
+
+- Use divs for everything
+- Use onClick on non-interactive elements
+- Forget keyboard accessibility
+- Skip heading levels
+- Use native img in Next.js
+
+---
+
+**Language**: All documentation must be written in **English**.

package/dist/templates/markdown/structure/frontend/directory-structure.md.txt

@@ -0,0 +1,172 @@
+# Directory Structure
+
+> Module organization and file layout for frontend development
+
+---
+
+## Standard Layout
+
+```
+src/
+├── app/                     # Next.js App Router (if using Next.js)
+│   ├── (marketing)/         # Marketing pages group
+│   ├── (app)/               # Application pages group
+│   └── api/                 # API routes
+│
+├── components/              # Shared components
+│   ├── ui/                  # Base UI components (Button, Input, etc.)
+│   └── common/              # Composite components (Header, Footer, etc.)
+│
+├── modules/                 # Feature modules
+│   └── {feature}/
+│       ├── components/      # Feature-specific components
+│       ├── hooks/           # Feature-specific hooks
+│       ├── context/         # Feature-specific context
+│       ├── lib/             # Feature-specific utilities
+│       └── types.ts         # Feature types
+│
+├── hooks/                   # Shared hooks
+│   ├── use-debounce.ts
+│   └── use-local-storage.ts
+│
+├── lib/                     # Shared utilities
+│   ├── api-client.ts        # API client setup
+│   ├── utils.ts             # Helper functions
+│   └── constants.ts         # Global constants
+│
+├── types/                   # Shared type definitions
+│   └── index.ts
+│
+└── styles/                  # Global styles
+    └── globals.css
+```
+
+---
+
+## Feature Module Structure
+
+Each feature module is self-contained:
+
+```
+modules/users/
+├── components/
+│   ├── user-card.tsx        # Display component
+│   ├── user-form.tsx        # Form component
+│   └── user-list.tsx        # List component
+│
+├── hooks/
+│   ├── use-user.ts          # Single user query
+│   ├── use-users.ts         # Users list query
+│   └── use-update-user.ts   # Update mutation
+│
+├── context/
+│   └── user-context.tsx     # Feature-level state
+│
+├── lib/
+│   └── user-utils.ts        # Feature-specific helpers
+│
+└── types.ts                 # Feature types (if not from API)
+```
+
+---
+
+## Component Organization
+
+### UI Components (Primitives)
+
+```
+components/ui/
+├── button.tsx               # Base button
+├── input.tsx                # Base input
+├── select.tsx               # Base select
+├── dialog.tsx               # Modal dialog
+├── dropdown-menu.tsx        # Dropdown menu
+└── index.ts                 # Barrel export
+```
+
+### Common Components (Composites)
+
+```
+components/common/
+├── header.tsx               # App header
+├── sidebar.tsx              # Navigation sidebar
+├── page-layout.tsx          # Page wrapper
+├── error-boundary.tsx       # Error boundary
+└── loading-spinner.tsx      # Loading state
+```
+
+---
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Files | kebab-case | `user-card.tsx` |
+| Components | PascalCase | `UserCard` |
+| Hooks | camelCase with `use` prefix | `useUser` |
+| Types | PascalCase | `UserData` |
+| Constants | SCREAMING_SNAKE | `MAX_FILE_SIZE` |
+
+---
+
+## Import Order
+
+Organize imports in this order:
+
+```typescript
+// 1. React and framework imports
+import { useState, useEffect } from 'react';
+import { useRouter } from 'next/navigation';
+
+// 2. Third-party libraries
+import { useQuery } from '@tanstack/react-query';
+import { z } from 'zod';
+
+// 3. Internal aliases (@/)
+import { Button } from '@/components/ui/button';
+import { useAuth } from '@/hooks/use-auth';
+
+// 4. Relative imports (same module)
+import { UserCard } from './user-card';
+import type { UserFormData } from './types';
+
+// 5. Styles
+import styles from './user-list.module.css';
+```
+
+---
+
+## Best Practices
+
+### DO
+
+- Keep feature modules self-contained
+- Use barrel exports (`index.ts`) for clean imports
+- Co-locate related files (component + hook + types)
+- Prefix hook files with `use-`
+
+### DON'T
+
+- Create deeply nested directories (max 3 levels)
+- Put feature-specific code in shared directories
+- Use generic names (`utils.ts`) in feature modules
+- Mix different features in one module
+
+---
+
+## Module Boundaries
+
+```
+✅ ALLOWED:
+- modules/users/ imports from components/ui/
+- modules/users/ imports from hooks/
+- modules/users/ imports from lib/
+
+❌ NOT ALLOWED:
+- modules/users/ imports from modules/orders/
+  (Use shared hooks or lift to common location)
+```
+
+---
+
+**Language**: All documentation must be written in **English**.