insertr/CLASSES.md

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.

<!-- 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

<!-- 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

<!-- 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

<!-- 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

<!-- 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:

<!-- 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.

<!-- 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.

<!-- 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

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

Styled Button in Corner

<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

<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

<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:

<!-- 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:

/* 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:

<!-- 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)

<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)

<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)

<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:

<!-- 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.