odac 0.9.0

package/docs/backend/07-views/08-backend-javascript.md

@@ -0,0 +1,398 @@
+## 💻 Backend JavaScript (Server-Side Execution)
+
+Backend JavaScript allows you to execute JavaScript code during template rendering on the server. This code runs **before** the HTML is sent to the browser.
+
+### Basic Usage
+
+```html
+<script:candy>
+  // This runs on the SERVER during template rendering
+  let total = 0;
+  for (let item of cart) {
+    total += item.price * item.quantity;
+  }
+</script:candy>
+
+<p>Total: $<candy var="total" /></p>
+```
+
+### Key Characteristics
+
+- ✅ Runs on the **server** during template rendering
+- ✅ Has access to all backend variables and Candy object
+- ✅ Perfect for calculations, data manipulation, filtering
+- ✅ Full IDE syntax highlighting and autocomplete
+- ❌ Does NOT run in the browser
+- ❌ Cannot access browser APIs (window, document, localStorage, etc.)
+
+### When to Use Backend JavaScript
+
+Use backend JavaScript for:
+- **Calculations**: Totals, averages, statistics
+- **Data transformation**: Filtering, sorting, mapping arrays
+- **Complex logic**: Logic that's too complex for inline conditions
+- **Variable preparation**: Creating temporary variables for display
+
+### Accessing Variables
+
+You have access to all variables set in the controller:
+
+```javascript
+// Controller
+module.exports = async function(Candy) {
+  Candy.set('products', [
+    { name: 'Laptop', price: 999, quantity: 2 },
+    { name: 'Mouse', price: 29, quantity: 5 }
+  ])
+  
+  Candy.View.skeleton('main').set('content', 'cart')
+}
+```
+
+```html
+<!-- View -->
+<script:candy>
+  let total = 0;
+  let itemCount = 0;
+  
+  for (let product of products) {
+    total += product.price * product.quantity;
+    itemCount += product.quantity;
+  }
+  
+  const avgPrice = total / itemCount;
+</script:candy>
+
+<div class="cart-summary">
+  <p>Total Items: <candy var="itemCount" /></p>
+  <p>Total Price: $<candy var="total" /></p>
+  <p>Average Price: $<candy var="avgPrice.toFixed(2)" /></p>
+</div>
+```
+
+### Accessing the Candy Object
+
+Full access to the Candy object and all its methods:
+
+```html
+<script:candy>
+  const isLoggedIn = Candy.Auth.check();
+  const currentUser = isLoggedIn ? Candy.Auth.user() : null;
+  const requestMethod = Candy.Request.method;
+  const currentUrl = Candy.Request.url;
+</script:candy>
+
+<candy:if condition="isLoggedIn">
+  <p>Welcome, <candy var="currentUser.name" />!</p>
+</candy:if>
+```
+
+### Practical Examples
+
+#### Shopping Cart Calculations
+
+```html
+<script:candy>
+  let subtotal = 0;
+  let totalItems = 0;
+  
+  for (let item of cart) {
+    subtotal += item.price * item.quantity;
+    totalItems += item.quantity;
+  }
+  
+  const tax = subtotal * 0.18; // 18% tax
+  const shipping = subtotal > 100 ? 0 : 10;
+  const total = subtotal + tax + shipping;
+</script:candy>
+
+<div class="cart-summary">
+  <h3>Order Summary</h3>
+  <p>Items (<candy var="totalItems" />): $<candy var="subtotal.toFixed(2)" /></p>
+  <p>Tax (18%): $<candy var="tax.toFixed(2)" /></p>
+  <p>Shipping: 
+    <candy:if condition="shipping === 0">
+      <span class="free">FREE</span>
+    <candy:else>
+      $<candy var="shipping.toFixed(2)" />
+    </candy:if>
+  </p>
+  <hr>
+  <p class="total">Total: $<candy var="total.toFixed(2)" /></p>
+</div>
+```
+
+#### Filtering and Sorting
+
+```html
+<script:candy>
+  // Filter active products
+  const activeProducts = products.filter(p => p.isActive && p.stock > 0);
+  
+  // Sort by price
+  activeProducts.sort((a, b) => a.price - b.price);
+  
+  // Get featured products
+  const featured = activeProducts.filter(p => p.featured).slice(0, 3);
+  
+  // Calculate statistics
+  const avgPrice = activeProducts.reduce((sum, p) => sum + p.price, 0) / activeProducts.length;
+  const maxPrice = Math.max(...activeProducts.map(p => p.price));
+  const minPrice = Math.min(...activeProducts.map(p => p.price));
+</script:candy>
+
+<div class="products-section">
+  <h2>Featured Products</h2>
+  <p>Showing <candy var="featured.length" /> of <candy var="activeProducts.length" /> products</p>
+  <p>Price range: $<candy var="minPrice" /> - $<candy var="maxPrice" /></p>
+  
+  <candy:for in="featured" value="product">
+    <div class="product">
+      <h3><candy var="product.name" /></h3>
+      <p>$<candy var="product.price" /></p>
+      
+      <candy:if condition="product.price < avgPrice">
+        <span class="badge">Great Deal!</span>
+      </candy:if>
+    </div>
+  </candy:for>
+</div>
+```
+
+#### Date and Time Formatting
+
+```html
+<script:candy>
+  const now = new Date();
+  const postDate = new Date(post.createdAt);
+  
+  // Calculate time difference
+  const diffMs = now - postDate;
+  const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+  const diffHours = Math.floor(diffMs / (1000 * 60 * 60));
+  const diffMinutes = Math.floor(diffMs / (1000 * 60));
+  
+  let timeAgo;
+  if (diffDays > 0) {
+    timeAgo = diffDays + ' days ago';
+  } else if (diffHours > 0) {
+    timeAgo = diffHours + ' hours ago';
+  } else if (diffMinutes > 0) {
+    timeAgo = diffMinutes + ' minutes ago';
+  } else {
+    timeAgo = 'Just now';
+  }
+  
+  const formattedDate = postDate.toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric'
+  });
+</script:candy>
+
+<div class="post">
+  <h2><candy var="post.title" /></h2>
+  <p class="meta">
+    Posted <candy var="timeAgo" /> (<candy var="formattedDate" />)
+  </p>
+</div>
+```
+
+#### Grouping Data
+
+```html
+<script:candy>
+  // Group products by category
+  const grouped = {};
+  for (let product of products) {
+    if (!grouped[product.category]) {
+      grouped[product.category] = [];
+    }
+    grouped[product.category].push(product);
+  }
+  
+  // Sort categories
+  const categories = Object.keys(grouped).sort();
+</script:candy>
+
+<div class="products-by-category">
+  <candy:for in="categories" value="category">
+    <div class="category-section">
+      <h2><candy var="category" /></h2>
+      <p><candy var="grouped[category].length" /> products</p>
+      
+      <candy:for in="grouped[category]" value="product">
+        <div class="product">
+          <h3><candy var="product.name" /></h3>
+          <p>$<candy var="product.price" /></p>
+        </div>
+      </candy:for>
+    </div>
+  </candy:for>
+</div>
+```
+
+#### Pagination Logic
+
+```html
+<script:candy>
+  const itemsPerPage = 10;
+  const currentPage = parseInt(Candy.Request.get('page')) || 1;
+  const totalItems = products.length;
+  const totalPages = Math.ceil(totalItems / itemsPerPage);
+  
+  const startIndex = (currentPage - 1) * itemsPerPage;
+  const endIndex = Math.min(startIndex + itemsPerPage, totalItems);
+  const currentItems = products.slice(startIndex, endIndex);
+  
+  const hasPrevious = currentPage > 1;
+  const hasNext = currentPage < totalPages;
+</script:candy>
+
+<div class="products">
+  <candy:for in="currentItems" value="product">
+    <div class="product">
+      <h3><candy var="product.name" /></h3>
+    </div>
+  </candy:for>
+</div>
+
+<div class="pagination">
+  <candy:if condition="hasPrevious">
+    <a href="?page=<candy var="currentPage - 1" />">Previous</a>
+  </candy:if>
+  
+  <span>Page <candy var="currentPage" /> of <candy var="totalPages" /></span>
+  
+  <candy:if condition="hasNext">
+    <a href="?page=<candy var="currentPage + 1" />">Next</a>
+  </candy:if>
+</div>
+```
+
+#### Complex Conditional Logic
+
+```html
+<script:candy>
+  const user = Candy.Auth.check() ? Candy.Auth.user() : null;
+  
+  const canEdit = user && (
+    user.role === 'admin' || 
+    user.id === post.authorId
+  );
+  
+  const canDelete = user && user.role === 'admin';
+  
+  const canComment = user && !user.isBanned && post.commentsEnabled;
+  
+  const showActions = canEdit || canDelete || canComment;
+</script:candy>
+
+<div class="post">
+  <h2><candy var="post.title" /></h2>
+  <p><candy var="post.content" /></p>
+  
+  <candy:if condition="showActions">
+    <div class="actions">
+      <candy:if condition="canEdit">
+        <a href="/posts/<candy var="post.id" />/edit">Edit</a>
+      </candy:if>
+      
+      <candy:if condition="canDelete">
+        <a href="/posts/<candy var="post.id" />/delete">Delete</a>
+      </candy:if>
+      
+      <candy:if condition="canComment">
+        <a href="#comments">Add Comment</a>
+      </candy:if>
+    </div>
+  </candy:if>
+</div>
+```
+
+### Multiple Script Blocks
+
+You can use multiple `<script:candy>` blocks in the same view:
+
+```html
+<script:candy>
+  let total = 0;
+</script:candy>
+
+<candy:for in="items" value="item">
+  <div><candy var="item.name" /></div>
+  
+  <script:candy>
+    total += item.price;
+  </script:candy>
+</candy:for>
+
+<p>Total: $<candy var="total" /></p>
+```
+
+### Comparison with Client-Side JavaScript
+
+**Backend JavaScript (`<script:candy>`):**
+```html
+<script:candy>
+  // Runs on SERVER during rendering
+  const total = products.reduce((sum, p) => sum + p.price, 0);
+</script:candy>
+<p>Total: $<candy var="total" /></p>
+```
+
+**Client-Side JavaScript (`<script>`):**
+```html
+<script>
+  // Runs in BROWSER after page loads
+  document.addEventListener('DOMContentLoaded', function() {
+    console.log('Page loaded');
+    
+    // Can access browser APIs
+    localStorage.setItem('visited', 'true');
+    
+    // Can manipulate DOM
+    document.querySelector('.button').addEventListener('click', function() {
+      alert('Clicked!');
+    });
+  });
+</script>
+```
+
+### Best Practices
+
+1. **Keep it simple**: Complex logic should be in controllers
+2. **Use for calculations**: Perfect for totals, averages, filtering
+3. **Avoid heavy operations**: Don't do database queries or API calls
+4. **Use meaningful variable names**: Make code self-documenting
+5. **Comment when necessary**: Explain complex calculations
+
+**Good:**
+```html
+<script:candy>
+  const discountedPrice = product.price * (1 - product.discount / 100);
+  const savings = product.price - discountedPrice;
+</script:candy>
+```
+
+**Avoid:**
+```html
+<script:candy>
+  // Don't do this - should be in controller
+  const users = await Candy.Mysql.query('SELECT * FROM users');
+  const apiData = await fetch('https://api.example.com/data');
+</script:candy>
+```
+
+### Common Use Cases
+
+- ✅ Calculate totals and subtotals
+- ✅ Filter and sort arrays
+- ✅ Format dates and numbers
+- ✅ Group and aggregate data
+- ✅ Create temporary display variables
+- ✅ Simple conditional logic
+- ❌ Database queries (use controller)
+- ❌ API calls (use controller)
+- ❌ File operations (use controller)
+- ❌ Heavy computations (use controller)

package/docs/backend/07-views/09-comments.md

@@ -0,0 +1,297 @@
+## 💬 Comments in Views
+
+CandyPack supports two types of comments in view files: backend comments (not rendered) and regular HTML comments (rendered).
+
+### Backend Comments (Not Rendered)
+
+Backend comments are removed during template rendering and never appear in the HTML output sent to the browser.
+
+#### Single-Line Backend Comments
+
+```html
+<!--candy This is a backend comment -->
+<p>This will be rendered</p>
+```
+
+#### Multi-Line Backend Comments
+
+```html
+<!--candy
+  This is a multi-line backend comment
+  It can span multiple lines
+  None of this will appear in the output
+candy-->
+
+<div class="content">
+  <p>This will be rendered</p>
+</div>
+```
+
+### Regular HTML Comments (Rendered)
+
+Standard HTML comments are preserved and sent to the browser:
+
+```html
+<!-- This is a regular HTML comment -->
+<!-- It will appear in the browser's HTML source -->
+<p>Content here</p>
+```
+
+### When to Use Each Type
+
+#### Use Backend Comments For:
+
+**Development Notes:**
+```html
+<!--candy TODO: Add pagination here -->
+<!--candy FIXME: This needs optimization -->
+<!--candy NOTE: This section is for admin users only -->
+```
+
+**Sensitive Information:**
+```html
+<!--candy 
+  Database query returns: id, name, email, password_hash
+  We only display: name, email
+candy-->
+
+<candy:for in="users" value="user">
+  <p><candy var="user.name" /> - <candy var="user.email" /></p>
+</candy:for>
+```
+
+**Debugging Information:**
+```html
+<!--candy Debug: user object structure -->
+<!--candy { id: 1, name: "John", role: "admin" } -->
+
+<candy:if condition="user.role === 'admin'">
+  <div class="admin-panel">Admin content</div>
+</candy:if>
+```
+
+**Temporary Code:**
+```html
+<!--candy
+  Old implementation - keeping for reference
+  <div class="old-layout">
+    <candy:for in="items" value="item">
+      <p><candy var="item.name" /></p>
+    </candy:for>
+  </div>
+candy-->
+
+<div class="new-layout">
+  <candy:for in="items" value="item">
+    <div class="item-card">
+      <h3><candy var="item.name" /></h3>
+    </div>
+  </candy:for>
+</div>
+```
+
+#### Use HTML Comments For:
+
+**Section Markers:**
+```html
+<!-- Header Section -->
+<header>
+  <nav>...</nav>
+</header>
+
+<!-- Main Content -->
+<main>
+  <article>...</article>
+</main>
+
+<!-- Footer Section -->
+<footer>
+  <p>Copyright 2024</p>
+</footer>
+```
+
+**Browser-Specific Hacks:**
+```html
+<!--[if IE]>
+  <p>You are using Internet Explorer</p>
+<![endif]-->
+```
+
+**Third-Party Integration Notes:**
+```html
+<!-- Google Analytics -->
+<script>
+  // Analytics code here
+</script>
+
+<!-- Facebook Pixel -->
+<script>
+  // Pixel code here
+</script>
+```
+
+### Practical Examples
+
+#### Documenting Complex Logic
+
+```html
+<!--candy
+  This section displays products based on user role:
+  - Admin: sees all products including inactive
+  - Regular user: sees only active products
+  - Guest: sees only featured products
+candy-->
+
+<script:candy>
+  let visibleProducts;
+  
+  if (Candy.Auth.check()) {
+    const user = Candy.Auth.user();
+    if (user.role === 'admin') {
+      visibleProducts = products;
+    } else {
+      visibleProducts = products.filter(p => p.isActive);
+    }
+  } else {
+    visibleProducts = products.filter(p => p.featured);
+  }
+</script:candy>
+
+<candy:for in="visibleProducts" value="product">
+  <div class="product">
+    <h3><candy var="product.name" /></h3>
+  </div>
+</candy:for>
+```
+
+#### Marking Sections for Developers
+
+```html
+<div class="dashboard">
+  <!--candy START: User Statistics Section -->
+  <div class="stats">
+    <h2>Statistics</h2>
+    <p>Total Users: <candy var="stats.totalUsers" /></p>
+    <p>Active Users: <candy var="stats.activeUsers" /></p>
+  </div>
+  <!--candy END: User Statistics Section -->
+  
+  <!--candy START: Recent Activity Section -->
+  <div class="activity">
+    <h2>Recent Activity</h2>
+    <candy:for in="activities" value="activity">
+      <p><candy var="activity.description" /></p>
+    </candy:for>
+  </div>
+  <!--candy END: Recent Activity Section -->
+</div>
+```
+
+#### Explaining Template Variables
+
+```html
+<!--candy
+  Available variables from controller:
+  - user: Current user object { id, name, email, role }
+  - posts: Array of post objects
+  - categories: Array of category objects
+  - settings: Site settings object
+candy-->
+
+<div class="profile">
+  <h1><candy var="user.name" /></h1>
+  <p><candy var="user.email" /></p>
+</div>
+```
+
+#### Temporary Disabling Code
+
+```html
+<div class="products">
+  <candy:for in="products" value="product">
+    <div class="product-card">
+      <h3><candy var="product.name" /></h3>
+      <p>$<candy var="product.price" /></p>
+      
+      <!--candy Temporarily disabled - waiting for API
+      <div class="reviews">
+        <candy var="product.averageRating" /> stars
+      </div>
+      candy-->
+    </div>
+  </candy:for>
+</div>
+```
+
+#### Version History
+
+```html
+<!--candy
+  Version History:
+  v1.0 - Initial implementation
+  v1.1 - Added sorting functionality
+  v1.2 - Added filtering by category
+  v2.0 - Complete redesign with new layout
+candy-->
+
+<div class="product-list">
+  <!-- Product list implementation -->
+</div>
+```
+
+### Best Practices
+
+1. **Use backend comments for sensitive info**: Never expose internal logic or data structures in HTML comments
+2. **Keep comments concise**: Don't over-comment obvious code
+3. **Update comments**: Remove or update outdated comments
+4. **Use meaningful descriptions**: Make comments helpful for other developers
+5. **Don't commit debug comments**: Remove debug comments before committing
+
+**Good:**
+```html
+<!--candy This query is cached for 5 minutes -->
+<candy:for in="products" value="product">
+  <div><candy var="product.name" /></div>
+</candy:for>
+```
+
+**Avoid:**
+```html
+<!--candy Loop through products -->
+<candy:for in="products" value="product">
+  <!--candy Display product name -->
+  <div><candy var="product.name" /></div>
+</candy:for>
+```
+
+### Security Considerations
+
+**Never expose sensitive information in HTML comments:**
+
+```html
+<!-- BAD: Visible in browser source -->
+<!-- Database password: secret123 -->
+<!-- API key: abc123xyz -->
+
+<!--candy GOOD: Not visible in output -->
+<!--candy Database password: secret123 -->
+<!--candy API key: abc123xyz -->
+```
+
+**Be careful with user data:**
+
+```html
+<!-- BAD: Exposes user data -->
+<!-- User ID: 12345, Email: user@example.com -->
+
+<!--candy GOOD: Hidden from output -->
+<!--candy User ID: 12345, Email: user@example.com -->
+```
+
+### Comment Syntax Summary
+
+| Type | Syntax | Rendered | Use Case |
+|------|--------|----------|----------|
+| Backend Single-Line | `<!--candy comment -->` | No | Development notes, TODOs |
+| Backend Multi-Line | `<!--candy ... candy-->` | No | Detailed explanations, disabled code |
+| HTML Comment | `<!-- comment -->` | Yes | Section markers, browser hacks |