pug-tail 0.1.0-alpha.0

package/docs/COMPONENTS.md

@@ -0,0 +1,708 @@
+# Component DSL Reference
+
+This document provides a comprehensive reference for pug-tail's component DSL.
+
+## Table of Contents
+
+- [Component Definition](#component-definition)
+- [Component Calls](#component-calls)
+- [Named Slots](#named-slots)
+- [Props and Attrs](#props-and-attrs)
+- [Attribute Fallthrough](#attribute-fallthrough)
+- [Scope Isolation](#scope-isolation)
+- [Advanced Patterns](#advanced-patterns)
+- [Integration with Pug Features](#integration-with-pug-features)
+
+## Component Definition
+
+### Basic Syntax
+
+```pug
+component ComponentName()
+  // component body
+```
+
+**Rules**:
+- Component names must start with an uppercase letter
+- Components are defined using the `component` keyword
+- Component body can contain any valid Pug markup
+- Components are block-scoped (defined where declared)
+
+### Example
+
+```pug
+component Card()
+  .card
+    .card-header
+      h2 Default Title
+    .card-body
+      p Default content
+```
+
+## Component Calls
+
+### Basic Syntax
+
+```pug
+ComponentName()
+```
+
+**Rules**:
+- Component calls look like function calls with uppercase names
+- Arguments are passed as Pug attributes
+- Child content is provided via slots
+
+### With Arguments
+
+```pug
+component Button()
+  - const { label, type = "button" } = $props
+  button(type=type)= label
+
+Button(label="Click me", type="submit")
+Button(label="Cancel")  // Uses default type="button"
+```
+
+### With Slots
+
+```pug
+component Card()
+  .card
+    slot(header)
+    slot(body)
+
+Card()
+  slot(header)
+    h1 Title
+  slot(body)
+    p Content
+```
+
+## Named Slots
+
+### Defining Slots
+
+```pug
+component Layout()
+  header
+    slot(header)
+      p Default header
+  
+  main
+    slot(main)
+      p Default main content
+  
+  footer
+    slot(footer)
+      p Default footer
+```
+
+**Features**:
+- `slot(name)` defines a named slot
+- Content inside slot tag is the default (used if no content provided)
+- Slots can be nested
+
+### Using Slots
+
+```pug
+Layout()
+  slot(header)
+    h1 My Site
+  
+  slot(main)
+    article
+      p Main content
+  
+  slot(footer)
+    p Copyright 2026
+```
+
+**Rules**:
+- Slot names must match between definition and usage
+- Slots can be provided in any order
+- Unmatched slots use default content
+- Extra slots (not defined) are ignored
+
+### Nested Components and Slots
+
+```pug
+component Page()
+  Layout()
+    slot(header)
+      slot(pageHeader)  // Expose slot to parent
+    slot(main)
+      slot(pageMain)
+
+Page()
+  slot(pageHeader)
+    h1 Welcome
+  slot(pageMain)
+    p Content
+```
+
+## Props and Attrs
+
+### $props - Component Properties
+
+Props are explicitly declared properties that the component expects.
+
+```pug
+component Button()
+  - const { label, type = "button", disabled = false } = $props
+  button(type=type disabled=disabled)= label
+
+Button(label="Submit", type="submit")
+```
+
+**Features**:
+- Use JavaScript destructuring syntax
+- Support default values
+- Support renaming: `{ class: className }`
+- Type-safe (values are passed as-is)
+
+### $attrs - Additional Attributes
+
+Attrs are all other attributes not declared in `$props`.
+
+```pug
+component Card()
+  - const { title } = $props
+  - const { class: className = "card" } = $attrs
+  
+  .card(class=className)
+    h2= title
+
+Card(title="Hello", class="custom-card", data-id="123")
+// title → $props
+// class, data-id → $attrs
+```
+
+**Automatic Categorization**:
+
+pug-tail automatically splits component arguments:
+1. Analyzes `$props` destructuring
+2. Puts declared properties in `$props`
+3. Puts everything else in `$attrs`
+
+### Legacy attributes
+
+The traditional `attributes` object still works:
+
+```pug
+component Card()
+  - const { title, ...attrs } = attributes
+  .card&attributes(attrs)
+    h2= title
+
+Card(title="Hello", class="custom")
+```
+
+**Recommendation**: Use `$props`/`$attrs` for new code. It's more explicit and follows Vue/React conventions.
+
+## Attribute Fallthrough
+
+### Automatic Fallthrough
+
+By default, `$attrs` are automatically applied to the root element:
+
+```pug
+component Card()
+  .card
+    h2 Title
+
+Card(class="my-card", id="card-1", data-test="value")
+```
+
+**Output**:
+```html
+<div class="card my-card" id="card-1" data-test="value">
+  <h2>Title</h2>
+</div>
+```
+
+**Rules**:
+- Applies only to single root element
+- Classes are merged (not replaced)
+- Other attributes override component's attributes
+
+### Disabling Automatic Fallthrough
+
+Use `&attributes()` explicitly to control where attrs are applied:
+
+```pug
+component Input()
+  .wrapper
+    label Label
+    input.field&attributes(attributes)
+
+Input(type="text", class="primary")
+```
+
+**Output**:
+```html
+<div class="wrapper">
+  <label>Label</label>
+  <input class="field primary" type="text"/>
+</div>
+```
+
+The explicit `&attributes(attributes)` disables automatic fallthrough to `.wrapper`.
+
+### Using $attrs Explicitly
+
+```pug
+component Card()
+  - const { title } = $props
+  
+  .card&attributes($attrs)
+    h2= title
+
+Card(title="Test", class="my-card")
+```
+
+Using `&attributes($attrs)` also disables automatic fallthrough.
+
+### Multiple Root Elements
+
+Automatic fallthrough is disabled with multiple root elements:
+
+```pug
+component Split()
+  .left
+    slot(left)
+  .right
+    slot(right)
+
+Split(class="container")
+// class="container" is NOT applied (multiple roots)
+```
+
+**Workaround**:
+```pug
+component Split()
+  - const { class: className } = $attrs
+  .split(class=className)
+    .left
+      slot(left)
+    .right
+      slot(right)
+```
+
+## Scope Isolation
+
+### Strict Mode (Default)
+
+Components cannot access external variables:
+
+```pug
+- const message = 'Hello'
+
+component Card()
+  p= message  // ❌ Error: references external variable "message"
+
+Card()
+```
+
+**Fix**: Pass via props:
+```pug
+- const message = 'Hello'
+
+component Card()
+  - const { text } = $props
+  p= text
+
+Card(text=message)  // ✅ OK
+```
+
+### Allowed Identifiers
+
+These are always accessible:
+
+**JavaScript globals**:
+- `console`, `Math`, `Date`, `JSON`, `Object`, `Array`
+- `String`, `Number`, `Boolean`, `RegExp`, `Error`
+- `Promise`, `Set`, `Map`, `WeakSet`, `WeakMap`
+- `parseInt`, `parseFloat`, `isNaN`, `isFinite`
+- `encodeURI`, `decodeURI`, `encodeURIComponent`, `decodeURIComponent`
+
+**Pug built-ins**:
+- `attributes`, `block`
+
+**pug-tail keywords**:
+- `$props`, `$attrs`
+
+### Configuration
+
+Control validation mode in config file:
+
+```javascript
+// pugtail.config.js
+export default {
+  validation: {
+    scopeIsolation: 'error',  // 'error' | 'warn' | 'off'
+    allowedGlobals: ['myHelper', 'APP_VERSION']
+  }
+}
+```
+
+**Modes**:
+- `'error'` (default): Compilation fails on external references
+- `'warn'`: Logs warnings but compiles successfully
+- `'off'`: Disables validation (legacy compatibility)
+
+### Custom Allowed Globals
+
+Add project-specific globals:
+
+```javascript
+// pugtail.config.js
+export default {
+  validation: {
+    scopeIsolation: 'error',
+    allowedGlobals: [
+      'formatDate',    // Custom helper
+      'APP_CONFIG',    // Global config
+      '_',             // Lodash
+    ]
+  }
+}
+```
+
+## Advanced Patterns
+
+### Conditional Slots
+
+```pug
+component Card()
+  .card
+    if hasHeader
+      .card-header
+        slot(header)
+    .card-body
+      slot(body)
+
+- const hasHeader = true
+Card()
+  slot(header)
+    h1 Title
+  slot(body)
+    p Content
+```
+
+### Iterating with Slots
+
+```pug
+component List()
+  ul
+    each item in items
+      li= item
+
+- const items = ['A', 'B', 'C']
+List()
+```
+
+### Dynamic Attributes
+
+```pug
+component Button()
+  - const { variant = 'primary' } = $props
+  - const classes = `btn btn-${variant}`
+  button(class=classes)
+    slot(default)
+      | Click me
+
+Button(variant="secondary")
+  slot(default)
+    | Custom label
+```
+
+### Computed Properties
+
+```pug
+component Price()
+  - const { amount, currency = 'USD' } = $props
+  - const formatted = new Intl.NumberFormat('en', { style: 'currency', currency }).format(amount)
+  span.price= formatted
+
+Price(amount=99.99, currency="EUR")
+```
+
+### Wrapper Components
+
+```pug
+component Container()
+  - const { maxWidth = '1200px' } = $props
+  - const { class: className } = $attrs
+  .container(class=className style=`max-width: ${maxWidth}`)
+    slot(default)
+
+Container(maxWidth="800px", class="my-container")
+  p Content
+```
+
+## Integration with Pug Features
+
+### With Includes
+
+```pug
+// components/Button.pug
+component Button()
+  - const { label } = $props
+  button= label
+
+// pages/index.pug
+include ../components/Button.pug
+
+Button(label="Click")
+```
+
+### With Extends
+
+```pug
+// layouts/base.pug
+component Layout()
+  html
+    head
+      block head
+    body
+      slot(content)
+
+// pages/home.pug
+include ../layouts/base.pug
+
+extends ../layouts/base.pug
+
+block head
+  title Home
+
+Layout()
+  slot(content)
+    h1 Home Page
+```
+
+### With Mixins
+
+```pug
+mixin icon(name)
+  i(class=`icon-${name}`)
+
+component Button()
+  - const { icon } = $props
+  button
+    +icon(icon)
+    slot(default)
+
+Button(icon="star")
+  slot(default)
+    | Favorite
+```
+
+### With Filters
+
+```pug
+component Code()
+  pre
+    code
+      slot(default)
+
+Code()
+  slot(default)
+    :markdown-it
+      # Markdown content
+      This is **bold**
+```
+
+## Best Practices
+
+### 1. Keep Components Focused
+
+Each component should have a single, clear responsibility:
+
+```pug
+// ✅ Good - Focused component
+component Button()
+  button
+    slot(default)
+
+// ❌ Avoid - Too much responsibility
+component ButtonWithModalAndTooltip()
+  // ...
+```
+
+### 2. Use Props for Data, Attrs for Styling
+
+```pug
+component Card()
+  - const { title, description } = $props  // Data
+  - const { class: className } = $attrs     // Styling
+  
+  .card(class=className)
+    h2= title
+    p= description
+```
+
+### 3. Provide Sensible Defaults
+
+```pug
+component Button()
+  - const { type = "button", disabled = false } = $props
+  button(type=type disabled=disabled)
+    slot(default)
+      | Button
+```
+
+### 4. Document Complex Components
+
+```pug
+//- Button component
+//- @param {string} label - Button text
+//- @param {string} type - Button type (button|submit|reset)
+//- @param {boolean} disabled - Disabled state
+//- @param {string} class - Additional CSS classes
+component Button()
+  // ...
+```
+
+### 5. Use Descriptive Slot Names
+
+```pug
+// ✅ Clear intent
+component Card()
+  slot(header)
+  slot(body)
+  slot(footer)
+
+// ❌ Unclear
+component Card()
+  slot(a)
+  slot(b)
+  slot(c)
+```
+
+### 6. Avoid Deep Nesting
+
+Limit component nesting depth for maintainability:
+
+```pug
+// ✅ Reasonable depth
+Layout()
+  slot(main)
+    Card()
+      slot(body)
+        p Content
+
+// ❌ Too deep (hard to follow)
+A()
+  B()
+    C()
+      D()
+        E()
+          F()
+```
+
+## Common Patterns
+
+### Card with Optional Header/Footer
+
+```pug
+component Card()
+  - const { title } = $props
+  .card
+    if title
+      .card-header
+        h2= title
+    .card-body
+      slot(body)
+    .card-footer
+      slot(footer)
+
+// With all parts
+Card(title="Title")
+  slot(body)
+    p Content
+  slot(footer)
+    button OK
+
+// Body only
+Card()
+  slot(body)
+    p Content
+```
+
+### Modal Dialog
+
+```pug
+component Modal()
+  - const { isOpen = false } = $props
+  if isOpen
+    .modal-overlay
+      .modal
+        .modal-header
+          slot(header)
+          button.close ×
+        .modal-body
+          slot(body)
+        .modal-footer
+          slot(footer)
+
+Modal(isOpen=true)
+  slot(header)
+    h2 Confirm
+  slot(body)
+    p Are you sure?
+  slot(footer)
+    button Cancel
+    button OK
+```
+
+### Navigation Menu
+
+```pug
+component Nav()
+  - const { items = [] } = $props
+  nav
+    ul
+      each item in items
+        li
+          a(href=item.url)= item.label
+
+Nav(items=[{label: 'Home', url: '/'}, {label: 'About', url: '/about'}])
+```
+
+## Troubleshooting
+
+### Common Errors
+
+**Error**: `Component "X" not found`
+- **Cause**: Component not defined before use
+- **Fix**: Define component before calling it
+
+**Error**: `Component "X" references external variable "Y"`
+- **Cause**: Scope isolation violation
+- **Fix**: Pass variable via props or add to allowedGlobals
+
+**Error**: `Unexpected token in $props destructuring`
+- **Cause**: Invalid JavaScript syntax
+- **Fix**: Check destructuring syntax
+
+### Debugging
+
+Enable debug mode to see transformation details:
+
+```javascript
+// pugtail.config.js
+export default {
+  debug: true
+}
+```
+
+### Getting Help
+
+- Check [Configuration Guide](./CONFIGURATION.md) for settings
+- Review [Architecture](./ARCHITECTURE.md) for internals
+- See [Contributing](./CONTRIBUTING.md) for development setup
+- Open an issue on GitHub with a minimal reproduction
+
+---
+
+For more information, see the main [README](../README.md).