yet_another_d_render

D-Render Guide

Overview

D-Render is a lightweight reactive UI library like Alpine.js, inspired by Vue and React. It provides a powerful component-based architecture with reactive state management and a comprehensive directive system.

The D-Render is built on three fundamental concepts:

• Components - Self-contained, reusable UI elements that:

  • Manage their own state and render lifecycle
  • Can be nested to create complex UIs
  • Are initialized with either d-component or d-state attributes
  • Can define custom directives and hooks
  • Can be extended through JavaScript classes
  • Support mixins for code reuse
  • Can proxy to parent components for shared state

• State Management - Reactive data model that:

  • Is defined using the d-state attribute or in component classes
  • Automatically triggers UI updates when modified
  • Can be accessed and modified through various directives
  • Supports transitions for animated state changes
  • Provides deep merging for complex state updates
  • Includes callback support for async operations

• Directives - HTML attributes that:

  • Begin with the d- prefix (e.g., d-click, d-show)
  • Connect the DOM with component state
  • Handle events, conditional rendering, and data binding
  • Can be component-specific or made globally available
  • Can be extended with custom functionality
  • Support modifiers for enhanced behavior

Core Concepts

Components

Components are initialized in two ways:

<!-- Using d-state -->
<div d-state="{ count: 0, displayed: true }">
  <!-- Component content -->
</div>

<!-- Using d-component -->
<div d-component="MyComponent">
  <!-- Component content -->
</div>

When D-Render initializes components, it attaches the component instance to DOM elements via a _dComponent property. You can get the component instance using element._dComponent.

// Access the component instance from a DOM element
const element = document.querySelector('[d-component="MyComponent"]');
const component = element._dComponent;

// Use component methods and properties
component.setState({ count: 5 });
console.log(component.state);

Component Classes

Define custom components with extended functionality:

class MyComponent extends DRender.Component {
  // Default state that merges with provided state
  defaultState(state) {
    return {
      count: 0,
      isVisible: true,
      ...state
    }
  }

  // Component-specific directives
  componentSpecificDirectives() {
    return {
      'd-custom': (component, node) => {
        // Custom directive implementation
      }
    }
  }

  // Mixins for code reuse
  mixins() {
    return [MyMixin, AnotherMixin];
  }

  // Lifecycle hooks
  afterInitialized() {
    // Setup after component initialization
    console.log('Component initialized');
  }

  stateChanged(prevState) {
    // Handle state changes
    console.log('State changed from', prevState, 'to', this.state);
  }

  childrenChanged(child) {
    // Handle child component changes
    console.log('Child component changed:', child);
  }

  unmounted() {
    // Cleanup when component is destroyed
    console.log('Component unmounted');
  }

  // State transitions for animations
  transistionOnStateChanging(prevState, newState) {
    // Return transition object for render() method
    return { animate: true };
  }

  // Control child component rendering
  shouldFollowRender(parent, transition) {
    // Return false to prevent child re-rendering
    return true;
  }

  // Custom methods
  increment() {
    this.setState({ count: this.state.count + 1 });
  }
}

Mixins System

Reuse code across components using mixins:

const CounterMixin = (component) => ({
  state: {
    count: 0
  },

  increment() {
    this.setState({ count: this.state.count + 1 });
  },

  decrement() {
    this.setState({ count: this.state.count - 1 });
  }
});

const LoggingMixin = (component) => ({
  stateChanged(prevState) {
    console.log('State changed:', prevState, '->', this.state);
  }
});

class MyComponent extends DRender.Component {
  mixins() {
    return [CounterMixin, LoggingMixin];
  }
}

State Management

• Declare state using d-state attribute
• Update state using Component#setState()
• Each setState triggers a render to update UI
• Changes trigger automatic DOM updates
• Supports deep merging and functional updates

// Simple state update
this.setState({ count: 5 });

// Functional state update
this.setState(prevState => ({ count: prevState.count + 1 }));

// With callback
this.setState({ count: 5 }, () => {
  console.log('State updated');
});

// With transition and callback
this.setState({ count: 5 }, { animate: true }, () => {
  console.log('State updated with transition');
});

Basic Directives

1. Event Handlers

<!-- Simple state update -->
<button d-click="{ count: count + 1 }">Click</button>

<!-- Method calls -->
<input d-change="handleChange">
<form d-submit="handleSubmit">

<!-- Multiple statements -->
<button d-click="increment(); logAction()">Increment</button>

Available events:

• d-click
• d-change
• d-input
• d-keyup
• d-keypress
• d-submit
• d-focus
• d-blur

2. Event Modifiers

<!-- Prevent default and stop propagation -->
<button d-click.prevent.stop="handleClick">Click</button>

<!-- Debounced input (400ms default) -->
<input d-input.debounce="handleInput">

<!-- Custom debounce duration -->
<input d-input.debounce="handleInput" d-debounce-duration="1000">

3. Conditional Display

<!-- Simple show/hide -->
<div d-show="isVisible">Shows/hides based on state</div>

<!-- Debounced show/hide -->
<div d-debounce-show="isVisible" d-debounce-duration="300">
  Debounced visibility
</div>

4. Class Binding

<!-- Object syntax -->
<div d-class="{ active: isActive, 'text-danger': hasError }">

<!-- String syntax -->
<div d-class="dynamicClass">

<!-- Debounced class changes -->
<div d-debounce-class="{ active: isActive }" d-debounce-duration="200">

5. Style Binding

<div d-style="{ color: textColor, fontSize: size + 'px' }">

6. Text/HTML Content

<div d-text="message"></div>
<div d-html="htmlContent"></div>

7. Two-way Data Binding

<!-- Text input -->
<input d-model="message">

<!-- Checkbox -->
<input type="checkbox" d-model="isChecked">

<!-- Radio buttons -->
<input type="radio" d-model="selectedOption" value="option1">
<input type="radio" d-model="selectedOption" value="option2">

8. Props & Attributes

<!-- Set DOM properties -->
<input d-prop="{ value: inputValue, placeholder: 'Enter text' }">

<!-- Set HTML attributes -->
<img d-attr="{ src: imageUrl, alt: imageAlt }">

<!-- Disabled/Readonly states -->
<button d-disabled="!isValid">Submit</button>
<input d-readonly="isViewOnly">

Loops

<!-- Basic loop -->
<div d-loop="items" d-loop-var="item">
  <template>
    <div d-key="item.id">
      <p d-text="item.name"></p>
      <p d-text="itemIndex"></p>
    </div>
  </template>
</div>

<!-- Object loop -->
<div d-loop="userObject" d-loop-var="user">
  <template>
    <div d-key="userKey">
      <span d-text="userKey"></span>: <span d-text="user"></span>
    </div>
  </template>
</div>

Component Relationships

Parent-Child Relationships

<div d-component="ParentComponent">
  <div d-component="ChildComponent">
    <!-- ChildComponent can access ParentComponent via this.parent -->
  </div>
</div>

In the child component:

class ChildComponent extends DRender.Component {
  afterInitialized() {
    // Access parent component
    const parentState = this.parent.state;

    // Call methods on parent component
    this.parent.someMethod();

    // Update parent state
    this.parent.setState({ parentUpdated: true });

    // Access root component
    this.root.setState({ rootUpdated: true });
  }
}

Finding Child Components

class ParentComponent extends DRender.Component {
  afterInitialized() {
    // Get all child components
    const allChildren = this.children;

    // Filter children by component name
    const specificChildren = this.filterChildren('ChildComponent');

    // Access child state
    const childState = specificChildren[0].state;
  }
}

Shadow Components

Shadow components proxy to their parent for shared state:

<div d-component="ParentComponent" d-state="{ sharedCount: 0 }">
  <div d-component="ShadowComponent">
    <!-- This component shares state with parent -->
  </div>
</div>

Portal Elements

Portal elements allow you to render component content in different DOM locations:

<!-- Define portal targets -->
<div id="modal-container"></div>
<div id="notification-container"></div>

<!-- Component with portal support -->
<div d-component="ModalComponent" d-global-directives>
  <div class="modal-content">
    <!-- This will appear in original location -->
    <h2>Modal Title</h2>
    <p>Modal Content</p>
  </div>
</div>

<!-- Portal targets will receive component content -->
<div d-portal="ModalComponent"></div>

Global Directives

Components can make their directives available globally:

<!-- Component with global directives -->
<div d-component="ModalManager" d-global-directives d-state="{ isOpen: false }">
  <div class="modal" d-class="{ active: isOpen }">
    <div class="modal-content">
      <h2>Modal</h2>
      <button d-click="{ isOpen: false }">Close</button>
    </div>
  </div>
</div>

<!-- Use component directives globally -->
<button d-modal-manager-click="{ isOpen: true }">
  Open Modal
</button>

<!-- Global refs -->
<button d-modal-manager-ref="openButton">Open</button>

Lifecycle Hooks

State Change Hook

<div d-on-state-change="handleStateChange(prevState)">

Render Hook

<div d-on-render="handleRender(transition)">

Initialize Hook

<div d-after-initialized="handleInit">

References

Access DOM elements through refs:

<!-- Single ref -->
<input d-ref="usernameInput">

<!-- Array ref -->
<div d-ref="items[]">Item 1</div>
<div d-ref="items[]">Item 2</div>

<!-- Component-specific refs -->
<button d-my-component-ref="submitButton">Submit</button>

In component:

class MyComponent extends DRender.Component {
  afterInitialized() {
    // Access refs
    const input = this.refs.usernameInput;
    const items = this.refs.items; // Array
    const submitBtn = this.refs.submitButton;

    input.focus();
  }
}

Advanced Features

MutationObserver Integration

D-Render automatically detects DOM changes and updates components:

// Components are automatically created/destroyed when DOM changes
const newElement = document.createElement('div');
newElement.setAttribute('d-component', 'MyComponent');
document.body.appendChild(newElement); // Component automatically initialized

Debug Mode

Enable debug logging for development:

// Enable debug features
DRender.debug.logAllFuncStr = true;        // Log function compilation
DRender.debug.logCompiledFuncExecutionError = true;  // Log execution errors
DRender.debug.logAttributeChanges = true;  // Log attribute changes
DRender.debug.keepDirectives = true;       // Keep directives in DOM for inspection

Component Utilities

// Find components by name
const components = DRender.findComponents('MyComponent');

// Get component hierarchy
DRender.graphComponents(); // Console log component tree

// Access closest component to element
const component = element.closestComponent();

// Access component depth
const depth = component.depth;

// Get component name formats
const kebabName = component.kebabName;      // my-component
const kebabPrefix = component.kebabPrefix;  // d-my-component

Performance Optimization

// Debounced rendering
this.setState({ count: 5 }, {}, false); // Don't trigger render
this.setState({ count: 6 }, {}, true, true); // Immediate render

// Control child rendering
shouldFollowRender(parent, transition) {
  // Prevent unnecessary child re-renders
  return this.state.shouldUpdateChildren;
}

API Reference

Component API

Properties

• element - DOM element associated with component
• state - Component state object
• parent - Parent component instance
• children - Array of child components
• root - Root component instance
• refs - Object containing DOM element references
• depth - Component depth in hierarchy
• name - Component name
• kebabName - Kebab-case component name
• kebabPrefix - Directive prefix for global directives

Methods

• setState(state, transition, triggerRendering, immediateRendering) - Update component state
• destroy() - Clean up component and remove event listeners
• filterChildren(name) - Get child components by name
• findRefs() - Get all DOM element references
• closestComponent(element) - Get closest component to element

Lifecycle Methods

• defaultState(state) - Define default state values
• afterInitialized() - Called after component initialization
• stateChanged(prevState) - Called when state changes
• childrenChanged(child) - Called when child components change
• unmounted() - Called when component is destroyed
• transistionOnStateChanging(prevState, newState) - Define state transitions
• shouldFollowRender(parent, transition) - Control child rendering
• mixins() - Return array of mixins to apply
• componentSpecificDirectives() - Define custom directives

DRender Global API

Methods

• run() - Initialize D-Render and scan DOM for components
• registerComponents(...components) - Register component classes
• defineComponent(name, ...mixins) - Define component with mixins
• findComponents(name, scopeNode) - Find components by name
• graphComponents(html, scopeNode) - Log component hierarchy
• closestComponent(node) - Get closest component to element
• addHelpers() - Add global helper methods to window
• createComponent(node, options) - Create component from element

Properties

• Component - Base component class
• Directives - Object containing all directive implementations
• Prefixes - Object containing event modifier implementations
• debug - Debug configuration object

Directives Reference

Event Directives

• d-click - Click event handler
• d-change - Change event handler
• d-input - Input event handler
• d-keyup - Keyup event handler
• d-keypress - Keypress event handler
• d-submit - Submit event handler
• d-focus - Focus event handler
• d-blur - Blur event handler

Event Modifiers

• .prevent - Call event.preventDefault()
• .stop - Call event.stopPropagation()
• .debounce - Debounce event handler

Conditional Directives

• d-show - Show/hide element based on condition
• d-debounce-show - Debounced show/hide
• d-disabled - Enable/disable element
• d-readonly - Make element read-only

Binding Directives

• d-model - Two-way data binding
• d-text - Set text content
• d-html - Set HTML content
• d-value - Set element value
• d-class - Bind CSS classes
• d-style - Bind inline styles
• d-prop - Set DOM properties
• d-attr - Set HTML attributes

Structural Directives

• d-loop - Loop over arrays/objects
• d-key - Unique key for loop items

Lifecycle Directives

• d-on-state-change - State change hook
• d-on-render - Render hook
• d-after-initialized - Initialize hook

Reference Directives

• d-ref - DOM element reference
• d-component-ref - Component-specific reference

Examples

Complete Todo Application

<div d-component="TodoApp" d-state="{
  todos: [
    { id: 1, text: 'Learn D-Render', completed: true },
    { id: 2, text: 'Build an app', completed: false }
  ],
  newTodo: '',
  filter: 'all'
}">
  <h1>Todo List</h1>

  <!-- Add new todo -->
  <div class="input-group">
    <input
      d-model="newTodo"
      d-keypress.enter="addTodo"
      placeholder="What needs to be done?"
      class="todo-input"
      d-ref="newTodoInput">
    <button d-click="addTodo">Add</button>
  </div>

  <!-- Todo filters -->
  <div class="filters">
    <button
      d-click="{ filter: 'all' }"
      d-class="{ active: filter === 'all' }">All</button>
    <button
      d-click="{ filter: 'active' }"
      d-class="{ active: filter === 'active' }">Active</button>
    <button
      d-click="{ filter: 'completed' }"
      d-class="{ active: filter === 'completed' }">Completed</button>
  </div>

  <!-- Todo list -->
  <ul class="todo-list">
    <div d-loop="filteredTodos()" d-loop-var="todo">
      <template>
        <li d-key="todo.id">
          <div d-class="{ completed: todo.completed }">
            <input
              type="checkbox"
              d-prop="{ checked: todo.completed }"
              d-change="toggleTodo(todo.id)">
            <span d-text="todo.text"></span>
            <button
              class="delete-btn"
              d-click="removeTodo(todo.id)">×</button>
          </div>
        </li>
      </template>
    </div>
  </ul>

  <!-- Status and bulk actions -->
  <div class="todo-footer" d-show="todos.length > 0">
    <span d-text="remainingCount() + ' items left'"></span>
    <button
      d-click="clearCompleted"
      d-show="todos.some(t => t.completed)">
      Clear completed
    </button>
  </div>

  <!-- Empty state -->
  <p d-show="todos.length === 0" class="empty-state">
    No todos yet! Add one above.
  </p>
</div>

<script>
class TodoApp extends DRender.Component {
  filteredTodos() {
    if (this.state.filter === 'active') {
      return this.state.todos.filter(todo => !todo.completed);
    } else if (this.state.filter === 'completed') {
      return this.state.todos.filter(todo => todo.completed);
    } else {
      return this.state.todos;
    }
  }

  remainingCount() {
    return this.state.todos.filter(todo => !todo.completed).length;
  }

  addTodo() {
    const text = this.state.newTodo.trim();
    if (text) {
      this.setState({
        todos: [...this.state.todos, {
          id: Date.now(),
          text,
          completed: false
        }],
        newTodo: ''
      }, () => {
        // Focus input after adding
        this.refs.newTodoInput.focus();
      });
    }
  }

  toggleTodo(id) {
    this.setState({
      todos: this.state.todos.map(todo =>
        todo.id === id ? { ...todo, completed: !todo.completed } : todo
      )
    });
  }

  removeTodo(id) {
    this.setState({
      todos: this.state.todos.filter(todo => todo.id !== id)
    });
  }

  clearCompleted() {
    this.setState({
      todos: this.state.todos.filter(todo => !todo.completed)
    });
  }
}

DRender.registerComponents(TodoApp);
DRender.run();
</script>

Modal Component with Global Directives

<!-- Modal manager component -->
<div d-component="ModalManager" d-global-directives d-state="{
  isOpen: false,
  title: '',
  content: ''
}">
  <div class="modal-backdrop" d-class="{ active: isOpen }" d-click="{ isOpen: false }">
    <div class="modal" d-click.stop>
      <div class="modal-header">
        <h3 d-text="title"></h3>
        <button d-click="{ isOpen: false }}">&times;</button>
      </div>
      <div class="modal-body" d-html="content"></div>
      <div class="modal-footer">
        <button d-click="{ isOpen: false }">Close</button>
      </div>
    </div>
  </div>
</div>

<!-- Using modal globally -->
<button d-modal-manager-click="{
  isOpen: true,
  title: 'Hello World',
  content: '<p>This is a modal!</p>'
}">
  Open Modal
</button>

<!-- Modal with component-specific ref -->
<button d-modal-manager-ref="openModalBtn">Open Modal</button>

Best Practices

• State Management

  • Always use setState() to update state
  • Keep state simple and focused
  • Use functional updates for complex state changes
  • Leverage deep merging for nested objects

• Component Design

  • Keep components focused and reusable
  • Use mixins for shared functionality
  • Implement proper cleanup in unmounted()
  • Use lifecycle hooks for setup/teardown

• Performance

  • Use shouldFollowRender() to optimize child rendering
  • Implement debouncing for frequent events
  • Avoid unnecessary state updates
  • Use refs instead of queries when possible

• Directives

  • Create custom directives for reusable behavior
  • Use global directives for cross-component functionality
  • Leverage event modifiers for common patterns
  • Keep directive logic simple and focused

Debugging

• Enable Debug Mode

DRender.debug.logAllFuncStr = true;
DRender.debug.logCompiledFuncExecutionError = true;
DRender.debug.logAttributeChanges = true;
DRender.debug.keepDirectives = true;

• Component Inspection

// View component tree
DRender.graphComponents();

// Find components
const components = DRender.findComponents('MyComponent');

// Access component from element
const component = element._dComponent;

// Use global helpers
graphComponents();
findComponents();
$0.closestComponent;

• State Debugging

// Log state changes
class MyComponent extends DRender.Component {
  stateChanged(prevState) {
    console.log('State changed:', prevState, '->', this.state);
  }
}

Tips

• Always use setState() to update state - never modify state directly
• Use transitions for temporary UI states and animations
• Keep components small and focused on single responsibilities
• Use refs to access DOM elements directly when needed
• Leverage lifecycle hooks for proper setup and cleanup
• Use mixins to share common functionality across components
• Implement shouldFollowRender() for performance optimization
• Use global directives for cross-component communication
• Enable debug mode during development for better visibility
• Use the component graph to visualize your application structure