# Insertr Class Reference and Usage Guide
Complete definitions of Insertr's class-based functionality and editing behaviors.

## Philosophy
Insertr uses semantic CSS classes to declare editing intent, following the principle of **"just add a class"**. Each class provides specific editing capabilities while maintaining zero configuration and respecting developer design intent.

## .insertr
The basic insertr class makes an element editable. It preserves the context of the element and updates its inner HTML. The editing behavior is determined by the HTML element type, providing intuitive and predictable editing experiences.

### Style Preservation (Shared with .insertr-content)
**Automatic nested element detection**: Insertr automatically analyzes existing markup within `.insertr` elements and preserves styled nested elements as formatting options during editing.

```html
<!-- Developer creates styled content -->
<h1 class="insertr">Welcome to <span class="fancy">Our Company</span></h1>
<p class="insertr">Save up to <strong class="highlight-price">50%</strong> today</p>
<a href="/" class="insertr"><i class="icon-home"></i> Home</a>
```

**Editor Experience**:
- **Preserved Elements**: `<span class="fancy">`, `<strong class="highlight-price">`, `<i class="icon-home">`
- **Formatting Options**: Users can apply these styles to other text portions
- **Design Safety**: Users cannot accidentally remove developer-intended styling
- **Element Addition**: If a styled anchor exists, users can add more links with the same styling

### Style Detection Rules
- **One Layer Deep**: Only direct child elements are analyzed and preserved
- **All Elements Preserved**: Any nested element becomes a formatting option (spans, emphasis, icons, etc.)
- **Automatic Availability**: No configuration needed - styles are automatically detected and offered

### Practical Examples

#### **Branded Headings**
```html
<!-- Developer creates -->
<h1 class="insertr">Product <span class="brand-color">Launch</span> 2024</h1>

<!-- Editor experience -->
- Text: "Product Launch 2024"
- Style options: Normal text + "Brand color" style for spans
- User edits: "New Launch 2025" 
- Result: <h1>New <span class="brand-color">Launch</span> 2025</h1>
```

#### **Navigation with Icons**
```html
<!-- Developer creates -->
<a href="/" class="insertr"><i class="icon-home"></i> Home</a>

<!-- Editor experience -->
- Text field: "Home"
- URL field: "/"
- Icon preserved automatically in all edits
- User can add more nav items with same icon pattern
```

#### **Styled Emphasis in Content**
```html
<!-- Developer creates -->
<p class="insertr">Save up to <strong class="highlight-price">50%</strong> today</p>

<!-- Editor experience -->
- Text: "Save up to 50% today"
- Style options: Normal text + "Highlight price" style
- User edits: "Save 75% this week"
- Result: <p>Save <strong class="highlight-price">75%</strong> this week</p>
```

#### **Call-to-Action Buttons**
```html
<!-- Developer creates -->
<button class="insertr">Buy Now <span class="arrow">→</span></button>

<!-- Editor experience -->
- Text: "Buy Now →"
- Arrow styling preserved automatically
- User can change text while keeping arrow design
```

### Element Behavior Categories

**Text Elements**: Direct content editing with simple text input fields
**Interactive Elements**: Content plus relevant attributes (href, etc.)  
**Media Elements**: Asset management with metadata editing
**Container Elements**: Automatic expansion to edit viable children
**Structured Elements**: Smart handling of lists, tables, and hierarchical content

| Element | Behaviour | Use Cases |
| -------------- | --------------- | --------- |
| **Text Elements** |-|-|
| `h1, h2, h3, h4, h5, h6` | Content + nested style preservation | Page titles, section headers, headlines |
| `p` | Content + nested style preservation | Simple paragraphs, descriptions |
| `span` | Content + nested style preservation | Inline text, labels, tags |
| `label` | Content + nested style preservation | Form labels, captions |
| `blockquote` | Content + nested style preservation | Quotes, testimonials |
| `code` | Content + nested style preservation | Code snippets, technical text |
| **Interactive Elements** |-|-|
| `a` | Content + href + nested style preservation | Navigation links, CTAs, external links |
| `button` | Content + nested style preservation | Buttons, CTAs, form actions |
| **Media Elements** |-|-|
| `img` | src + alt + title | Images, photos, illustrations |
| **Container Elements** |-|-|
| `div` | Container expansion | Generic containers, cards, sections |
| `section` | Container expansion | Page sections, content blocks |
| `article` | Container expansion | Blog posts, news articles |
| `header` | Container expansion | Page/section headers |
| `footer` | Container expansion | Page/section footers |
| `nav` | Container expansion | Navigation menus |
| **List Elements** |-|-|
| `li` | Content only | List items, menu items |
| `ul, ol` | Container expansion | Lists (expands to li elements) |
| **Table Elements** |-|-|
| `td, th` | Content only | Table cells and headers |
| `tr` | Container expansion | Table rows (expands to td/th) |
| `table` | Container expansion | Tables (expands to rows) |

### Special Considerations

**Attribute Preservation**: All elements preserve their existing classes, IDs, data attributes, and styling context during content updates.

**Content Type Detection**: 
- Simple elements (h1-h6, p, span) → Text input with style preservation
- Complex elements (a, img) → Multi-field editors with style preservation
- Containers (div, section) → Child element expansion
- Rich content containers → Suggested for `.insertr-content` class

**Nested Element Handling**:
- Container expansion stops at elements that already have `.insertr` class
- Styled nested elements (one layer deep) are preserved as formatting options
- Avoid infinite nesting by respecting existing editorial boundaries
- Preserve semantic HTML structure during content updates

**Fallback Behavior**: 
- Unknown/unsupported elements default to content-only editing
- Custom elements inherit behavior from their semantic role

## Shared Functionality: Style Preservation

All Insertr editing classes (`.insertr` and `.insertr-content`) share the same core style preservation system:

### **Unified Style Detection**
- **One Layer Analysis**: Examines direct child elements for styling
- **Automatic Preservation**: Styled elements become formatting options
- **Zero Configuration**: No setup required - works automatically
- **Design Safety**: Prevents users from breaking developer styling

### **Cross-Class Consistency**
- **`.insertr`**: Individual elements with style preservation
- **`.insertr-content`**: Rich text areas with style preservation  
- **Same Logic**: Both use identical style detection and preservation

### **Benefits**
- ✅ **Unified Experience**: Consistent behavior across all editing types
- ✅ **Design Integrity**: Developer styling always preserved
- ✅ **User Safety**: Cannot accidentally break carefully crafted designs
- ✅ **Zero Learning Curve**: Same formatting options everywhere

### Syntactic Sugar Transformation
**Container Convenience**: When developers add `.insertr` to container elements (div, section, article), Insertr automatically transforms this "syntactic sugar" into granular editing:

```html
<!-- Developer writes (syntactic sugar) -->
<section class="hero insertr">
  <h1>Hero Title</h1>
  <p>Hero description</p>
  <button>Call to Action</button>
</section>

<!-- System transforms to (granular editing) -->
<section class="hero">
  <h1 class="insertr">Hero Title</h1>
  <p class="insertr">Hero description</p>  
  <button class="insertr">Call to Action</button>
</section>
```

**Benefits**:
- **Developer convenience**: One class enables section-wide editing
- **Granular control**: Individual element editing rather than container editing
- **Predictable behavior**: Each element maintains its semantic editing behavior


## .insertr-content
Rich content editing for blog posts, articles, recipes, and complex nested content that requires formatting preservation.

### Purpose
The `.insertr-content` class enables rich text editing while maintaining the developer's original styling and design intent. Unlike basic `.insertr` elements that edit individual components, `.insertr-content` treats the entire container as a single rich content area.

### Developer Styles → Editor Options (Shared with .insertr)
**Zero-configuration style detection**: Insertr automatically analyzes the existing markup within `.insertr-content` elements and makes those styles available as formatting options in the rich text editor. This same functionality applies to all `.insertr` elements.

```html
<!-- Developer creates styled content -->
<article class="insertr-content blog-post">
  <h1>Blog Post Title</h1>
  <p>Introduction with <strong class="brand-highlight">branded emphasis</strong> and 
     <a href="#" class="fancy-link">styled links</a>.</p>
  <h2>Section Header</h2>
  <p>Regular content with <em>italic text</em> and more formatting.</p>
  <blockquote class="testimonial">Important quote with custom styling</blockquote>
</article>
```

**Automatic Editor Palette Generation**:
- **Headings**: h1, h2 (based on existing structure)
- **Text Formatting**: Bold (default + `.brand-highlight` style), Italic  
- **Links**: Default links + `.fancy-link` styled links
- **Blocks**: Paragraph, `.testimonial` blockquotes
- **All Nested Elements**: Any styled element becomes a formatting option

### Behavior
- **Rich Text Editor**: Opens a modal or inline editor with formatting toolbar
- **Style Preservation**: All developer-defined classes and styling preserved
- **HTML Storage**: Content stored as HTML to maintain full fidelity
- **Nested Handling**: Respects existing `.insertr` elements as editorial boundaries

### Content Type
- **Storage**: HTML format with complete attribute preservation
- **Enhancement**: Direct HTML injection into static files
- **Editor UI**: Rich text editor with developer-style-based formatting options

### Use Cases
- Blog post content
- Article bodies  
- Recipe instructions
- Product descriptions
- Documentation content
- Any complex content requiring rich formatting with design consistency

## .insertr-add
Dynamic content creation and management for repeatable elements like testimonials, team members, product cards, or any collection of similar items.

### Purpose
The `.insertr-add` class transforms a container into a dynamic collection where users can add, remove, and reorder similar items. The system automatically detects the template pattern from existing children and provides duplication capabilities.

### Template Detection
**Automatic Pattern Recognition**: Insertr analyzes the existing child elements to understand the template structure for new items.

```html
<!-- Testimonials collection -->
<div class="testimonials insertr-add">
  <div class="testimonial-item">
    <blockquote class="insertr">Not all that is gold does glitter</blockquote>
    <cite class="insertr">Tolkien</cite>
  </div>
  <div class="testimonial-item">  
    <blockquote class="insertr">The journey of a thousand miles begins with one step</blockquote>
    <cite class="insertr">Lao Tzu</cite>
  </div>
</div>
```

**Template Structure**: System recognizes the pattern:
- Container: `.testimonial-item`
- Editable fields: `blockquote.insertr` + `cite.insertr`
- Styling: All classes and structure preserved

### User Interface
- **Add Button**: Floating "+" button. 
- **Remove Controls**: Delete option for each item (with confirmation)
- **Reorder Capability**: Drag-and-drop or up/down controls
- **Duplication**: New items inherit the exact structure and styling

### Behavior
- **Template Preservation**: New items maintain exact HTML structure
- **Content Reset**: Editable fields cleared for new content entry
- **ID Generation**: Automatic unique IDs for new content items
- **Styling Inheritance**: All CSS classes and attributes preserved
- **Template Differnetiation**: If multiple templates are defined by the developer they are treated as variants available to the editor.

### Data Storage
- **Array Format**: Stored as array of item data
- **Template Storage**: Base template structure preserved
- **Individual Content**: Each item's editable content stored separately

### Use Cases
- Testimonial collections
- Team member grids
- Product catalogs
- FAQ sections
- Step-by-step instructions
- Portfolio items
- Feature lists
- Any repeating content pattern
## .insertr-gate
Authentication trigger that enables editing functionality when clicked.

### Purpose
The `.insertr-gate` class transforms any element into an authentication trigger - typically a button or link placed unobtrusively on the page (like in the footer). When clicked, it initiates the authentication flow, and once authenticated, all `.insertr` elements on the page become editable.

### How It Works
- **Trigger Element**: Not a boundary, but a clickable authentication trigger
- **Unobtrusive Placement**: Designed to not interfere with page layout or content flow
- **Developer Styled**: Can be styled however the developer wishes (button, link, icon, etc.)
- **Single Responsibility**: Just triggers authentication, doesn't control content

### Implementation Examples

#### **Footer Login Link**
```html
<footer>
  <p>&copy; 2024 My Website</p>
  <a href="#" class="insertr-gate">Admin Login</a>
</footer>
```

#### **Styled Button in Corner**
```html
<button class="insertr-gate admin-btn">
  ✏️ Edit
</button>

<style>
.admin-btn {
  position: fixed;
  bottom: 20px;
  right: 20px;
  background: #4f46e5;
  color: white;
  border: none;
  padding: 8px 12px;
  border-radius: 6px;
  cursor: pointer;
}
</style>
```

#### **Discrete Text Link**
```html
<nav>
  <a href="/">Home</a>
  <a href="/about">About</a>
  <a href="#" class="insertr-gate" style="opacity: 0.5; font-size: 0.8em;">Edit</a>
</nav>
```

#### **Icon in Header**
```html
<header>
  <h1>My Blog</h1>
  <span class="insertr-gate edit-icon" title="Login to edit">⚙️</span>
</header>
```

### User Experience Flow
1. **Normal Visitor**: Sees the page normally, gate trigger is just a small button/link
2. **Editor Discovers**: Clicks the gate trigger (login link, edit button, etc.)
3. **Authentication**: Login flow initiates (popup, redirect, or modal)
4. **Authenticated**: All `.insertr` elements become editable, editing UI appears
5. **Editing**: User can edit any content marked with Insertr classes
6. **Logout**: Gate can also serve as logout trigger when authenticated

### Behavior and States
- **Unauthenticated**: Shows login trigger (styled by developer)
- **Authenticated**: Can show logout option or editing status
- **Loading**: Shows loading state during authentication process
- **Error**: Shows error state if authentication fails

### Multiple Gates
Multiple gates can exist on a page and will have identical functionality:
```html
<!-- Multiple triggers for convenience -->
<footer>
  <a href="#" class="insertr-gate">Login</a>
</footer>

<nav>
  <button class="insertr-gate admin-btn">Edit Site</button>
</nav>
```

### Styling and Placement
The gate is completely developer-controlled for styling and positioning:

```css
/* Discrete footer link */
.insertr-gate {
  color: #666;
  text-decoration: none;
  font-size: 0.8em;
}

/* Floating edit button */
.insertr-gate.floating {
  position: fixed;
  bottom: 20px;
  right: 20px;
  z-index: 1000;
}

/* Hidden until hover */
.insertr-gate.hidden {
  opacity: 0;
  transition: opacity 0.3s;
}
.insertr-gate.hidden:hover {
  opacity: 1;
}
```

### Authentication Integration
- **Provider Agnostic**: Works with configured auth providers (mock, Authentik, custom)
- **Session Management**: Respects existing authentication state
- **Token Based**: Supports JWT tokens and session-based authentication
- **Logout Support**: Same element can trigger logout when authenticated

### Benefits
- ✅ **Unobtrusive**: Doesn't interfere with page layout or content
- ✅ **Flexible**: Can be any element styled however developer wants
- ✅ **Simple**: Just triggers authentication, no complex logic
- ✅ **Discoverable**: Easy for editors to find when they need it
- ✅ **Secure**: All editing requires authentication through the gate

### Use Cases
- Footer login links for personal blogs
- Discrete admin buttons for marketing sites  
- Hidden edit triggers for client sites
- Branded login buttons for company sites
- Development access triggers for staging sites

**Design Philosophy**: The gate should feel natural to the site's design while providing clear access to editing capabilities for authorized users.

## Class Combinations and Strategy

### Combining Classes
Multiple Insertr classes can be used together to create sophisticated editing experiences with unified style preservation:

```html
<!-- Styled individual elements -->
<header>
  <h1 class="insertr">Welcome to <span class="brand">Our Site</span></h1>
  <nav class="insertr">
    <a href="/"><i class="icon-home"></i> Home</a>
    <a href="/about"><i class="icon-info"></i> About</a>
  </nav>
</header>

<!-- Rich content with preserved styling -->
<article class="insertr-content">
  <h1>Blog Post Title</h1>
  <p>Introduction with <strong class="brand-highlight">branded emphasis</strong></p>
  <blockquote class="testimonial">Styled quote block</blockquote>
</article>

<!-- Dynamic collection with styled templates -->
<div class="testimonials insertr-add">
  <div class="testimonial-item">
    <blockquote class="insertr">Quote with <em class="author-emphasis">styling</em></blockquote>
    <cite class="insertr"><strong class="author-name">Author Name</strong></cite>
  </div>
</div>

<!-- Authentication gate -->
<footer>
  <a href="#" class="insertr-gate">Admin Login</a>
</footer>
```

### Content Architecture Patterns

#### **Simple Website** (Landing pages, marketing sites)
```html
<header class="insertr">
  <!-- Auto-expands to h1, nav links, etc. -->
</header>

<main class="insertr">
  <!-- Auto-expands to headings, paragraphs, buttons -->
</main>
```

#### **Blog/Publication** (Content-heavy sites)
```html
<article class="blog-post">
  <header class="insertr">
    <!-- Title, author, date editing -->
  </header>
  
  <div class="insertr-content">
    <!-- Rich text editing for article body -->
  </div>
  
  <footer class="insertr">
    <!-- Tags, share buttons, etc. -->
  </footer>
</article>
```

#### **Application Interface** (Dashboards, admin panels)
```html
<div class="dashboard insertr-gate" data-auth-role="admin">
  <section class="metrics insertr-add">
    <!-- Dynamic metric cards -->
  </section>
  
  <section class="announcements">
    <div class="insertr-content insertr-gate" data-auth-level="manager">
      <!-- Rich text announcements for managers+ -->
    </div>
  </section>
</div>
```

### Best Practices

#### **Start Simple, Add Complexity**
1. Begin with basic `.insertr` for individual elements
2. Add `.insertr-content` for areas needing rich formatting
3. Introduce `.insertr-add` for collections that need growth
4. Apply `.insertr-gate` for access control as needed

#### **Respect Content Hierarchy**
- Use container expansion (`.insertr`) for structural editing
- Use rich content (`.insertr-content`) for narrative content
- Use dynamic collections (`.insertr-add`) for repeatable patterns
- Use gates (`.insertr-gate`) for permission boundaries

#### **Design System Integration**
- Insertr automatically respects your existing CSS and design system
- All developer-defined nested styles become available formatting options
- Works consistently across individual elements (`.insertr`) and rich content (`.insertr-content`)
- No need to configure or duplicate styling information  
- Content editors work within design constraints naturally
- One-layer style detection ensures predictable behavior

## Migration and Adoption

### Progressive Enhancement
Insertr classes can be added incrementally to existing sites:

```html
<!-- Phase 1: Start with simple editing -->
<h1 class="insertr">Page Title</h1>

<!-- Phase 2: Add rich content areas -->
<div class="insertr-content">
  <!-- Complex content -->
</div>

<!-- Phase 3: Add dynamic capabilities -->
<div class="testimonials insertr-add">
  <!-- Repeatable content -->
</div>

<!-- Phase 4: Add access control -->
  <a href="#" class="insertr-gate">Admin Login</a>
```

### Framework Compatibility
Works seamlessly with all static site generators and frameworks:
- **Jekyll, Hugo, Gatsby**: Add classes to templates
- **Next.js, Nuxt**: Add classes to components  
- **WordPress, Drupal**: Add classes to themes
- **Plain HTML**: Add classes directly to markup

The class-based approach ensures Insertr integrates cleanly without requiring framework-specific implementations or build process changes.