Reorganize RSpade directory structure for clarity
Improve Jqhtml_Integration.js documentation with hydration system explanation Add jqhtml-laravel integration packages for traditional Laravel projects 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
root
@@ -1,52 +1,104 @@
|
||||
/**
|
||||
* JQHTML Integration - Automatic component registration and binding
|
||||
* JQHTML Integration - Component Hydration System
|
||||
*
|
||||
* This module automatically:
|
||||
* 1. Registers component classes that extend Component
|
||||
* 2. Binds templates to component classes when names match
|
||||
* 3. Enables $(selector).component("Component_Name") syntax
|
||||
* This module bridges server-rendered HTML and client-side jqhtml components.
|
||||
*
|
||||
* == THE HYDRATION PROBLEM ==
|
||||
*
|
||||
* When PHP/Blade renders a page, jqhtml components appear as placeholder elements:
|
||||
*
|
||||
* Blade source: <User_Card $name="John" />
|
||||
* Rendered HTML: <div class="Component_Init"
|
||||
* data-component-init-name="User_Card"
|
||||
* data-component-args='{"name":"John"}'>
|
||||
* </div>
|
||||
*
|
||||
* These are just div tags - they have no behavior until JavaScript runs.
|
||||
* "Hydration" is the process of finding these placeholders and converting them
|
||||
* into live, interactive jqhtml components.
|
||||
*
|
||||
* == TWO-PHASE INITIALIZATION ==
|
||||
*
|
||||
* Phase 1: _on_framework_modules_define() - Component Registration
|
||||
* - Runs early in framework boot, before DOM is processed
|
||||
* - Registers all ES6 classes extending Component with jqhtml runtime
|
||||
* - After this phase, jqhtml knows: "User_Card" → UserCardClass
|
||||
*
|
||||
* Phase 2: _on_framework_modules_init() - DOM Hydration
|
||||
* - Runs after templates are loaded
|
||||
* - Finds all .Component_Init elements in the DOM
|
||||
* - Extracts component name and args from data attributes
|
||||
* - Calls $element.component(name, args) to hydrate each one
|
||||
* - Recursively processes nested components
|
||||
* - Triggers 'jqhtml_ready' when all components are initialized
|
||||
*
|
||||
* == THE TRANSFORMATION ==
|
||||
*
|
||||
* Before hydration:
|
||||
* <div class="Component_Init" data-component-init-name="User_Card" ...>
|
||||
*
|
||||
* After hydration:
|
||||
* <div class="User_Card"> ← Component_Init removed, component class added
|
||||
* [component template content] ← Template rendered into element
|
||||
* </div>
|
||||
*
|
||||
* The element is now a live component with event handlers, state, and lifecycle.
|
||||
*
|
||||
* == KEY PARTICIPANTS ==
|
||||
*
|
||||
* JqhtmlBladeCompiler.php - Transforms <Component /> tags into .Component_Init divs
|
||||
* jqhtml runtime - Maintains registry of component names → classes
|
||||
* This module - Orchestrates registration and hydration
|
||||
* $().component() - jQuery plugin that creates component instances
|
||||
*/
|
||||
class Jqhtml_Integration {
|
||||
/**
|
||||
* Compiled Jqhtml templates self-register. The developer (the framework in this case) is still
|
||||
* responsible for registering es6 component classes with jqhtml. This does so at an early stage
|
||||
* of framework init.
|
||||
* Phase 1: Register Component Classes
|
||||
*
|
||||
* Compiled .jqhtml templates self-register their render methods with jqhtml.
|
||||
* But the framework must separately register ES6 component classes (the ones
|
||||
* extending Component with lifecycle methods like on_create, on_load, etc).
|
||||
*
|
||||
* This runs during framework_modules_define, before any DOM processing.
|
||||
*/
|
||||
static _on_framework_modules_define() {
|
||||
// ─────────────────────────────────────────────────────────────────────
|
||||
// Register Component Classes with jqhtml Runtime
|
||||
//
|
||||
// The Manifest knows all classes extending Component. We register each
|
||||
// with jqhtml so it can instantiate them by name during hydration.
|
||||
// ─────────────────────────────────────────────────────────────────────
|
||||
let jqhtml_components = Manifest.get_extending('Component');
|
||||
|
||||
console_debug('JQHTML_INIT', 'Registering ' + jqhtml_components.length + ' Components');
|
||||
|
||||
for (let component of jqhtml_components) {
|
||||
jqhtml.register_component(component.class_name, component.class_object);
|
||||
}
|
||||
|
||||
// Assign unique cache IDs to all static methods for component caching
|
||||
// This enables JQHTML to generate deterministic cache keys when functions
|
||||
// are passed as component arguments (e.g., DataGrid data_source functions)
|
||||
// ─────────────────────────────────────────────────────────────────────
|
||||
// Tag Static Methods with Cache IDs
|
||||
//
|
||||
// jqhtml caches component output based on args. When a function is passed
|
||||
// as an arg (e.g., DataGrid's data_source), we need a stable string key.
|
||||
//
|
||||
// Without this: data_source: function() {...} → no cache (functions aren't serializable)
|
||||
// With this: function._jqhtml_cache_id = "My_DataGrid.fetch_data" → cacheable
|
||||
// ─────────────────────────────────────────────────────────────────────
|
||||
const all_classes = Manifest.get_all_classes();
|
||||
let methods_tagged = 0;
|
||||
|
||||
for (const class_info of all_classes) {
|
||||
const class_object = class_info.class_object;
|
||||
const class_name = class_info.class_name;
|
||||
|
||||
// Get all property names from the class object (static methods/properties)
|
||||
const property_names = Object.getOwnPropertyNames(class_object);
|
||||
|
||||
for (const property_name of property_names) {
|
||||
// Skip built-in properties and non-functions
|
||||
if (property_name === 'length' ||
|
||||
property_name === 'name' ||
|
||||
property_name === 'prototype') {
|
||||
if (property_name === 'length' || property_name === 'name' || property_name === 'prototype') {
|
||||
continue;
|
||||
}
|
||||
|
||||
const property_value = class_object[property_name];
|
||||
|
||||
// Only tag functions (static methods)
|
||||
if (typeof property_value === 'function') {
|
||||
// Assign unique cache ID: "ClassName.methodName"
|
||||
property_value._jqhtml_cache_id = `${class_name}.${property_name}`;
|
||||
methods_tagged++;
|
||||
}
|
||||
@@ -55,24 +107,57 @@ class Jqhtml_Integration {
|
||||
|
||||
console_debug('JQHTML_INIT', `Tagged ${methods_tagged} static methods with _jqhtml_cache_id`);
|
||||
|
||||
// Set the cache key for jqhtml to the application key to enable component caching in local storage.
|
||||
// Modifying the application or the user logging out modifies the scope_key and will invalidate jqhtml cache.
|
||||
// ─────────────────────────────────────────────────────────────────────
|
||||
// Configure jqhtml Caching
|
||||
//
|
||||
// scope_key() changes when: app code changes, user logs out, site changes.
|
||||
// This automatically invalidates cached component renders.
|
||||
// ─────────────────────────────────────────────────────────────────────
|
||||
jqhtml.set_cache_key(Rsx.scope_key());
|
||||
|
||||
// set this to true if we desire jqhtml verbose output (probably not necessary for end developers)
|
||||
window.jqhtml.debug.verbose = false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Framework modules init phase - Bind components and initialize DOM
|
||||
* This runs after templates are registered to bind component classes
|
||||
* @param {jQuery} [$scope] Optional scope to search within (defaults to body)
|
||||
* @returns {Array<Promise>|undefined} Array of promises for recursive calls, undefined for top-level
|
||||
* Phase 2: DOM Hydration
|
||||
*
|
||||
* Finds all .Component_Init placeholders and converts them into live components.
|
||||
*
|
||||
* == HYDRATION PROCESS ==
|
||||
*
|
||||
* For each .Component_Init element:
|
||||
*
|
||||
* 1. EXTRACT: Read data-component-init-name and data-component-args
|
||||
* 2. CLEANUP: Remove data attributes (prevents re-hydration, hides implementation)
|
||||
* 3. CAPTURE: Save innerHTML for slot/content() processing
|
||||
* 4. INSTANTIATE: Call $element.component(name, args)
|
||||
* 5. RECURSE: After render, hydrate any nested .Component_Init elements
|
||||
*
|
||||
* == NESTED COMPONENT HANDLING ==
|
||||
*
|
||||
* Components can contain other components in their Blade output:
|
||||
*
|
||||
* <User_Card> ← Parent hydrates first
|
||||
* <Avatar /> ← Child hydrates after parent renders
|
||||
* </User_Card>
|
||||
*
|
||||
* We skip nested .Component_Init elements on first pass (they're inside a parent
|
||||
* that hasn't rendered yet). After each component renders, we recursively scan
|
||||
* its content for children to hydrate.
|
||||
*
|
||||
* == ASYNC COMPLETION ==
|
||||
*
|
||||
* Hydration is async because components may have on_load() methods that fetch data.
|
||||
* We track all component promises and trigger 'jqhtml_ready' only when every
|
||||
* component (including nested ones) has completed its full lifecycle.
|
||||
*
|
||||
* @param {jQuery} [$scope] Scope to search (defaults to body). Recursive calls pass component.$
|
||||
* @returns {Array<Promise>|undefined} Promises for recursive calls; undefined for top-level
|
||||
*/
|
||||
static _on_framework_modules_init($scope) {
|
||||
const is_top_level = !$scope;
|
||||
const promises = [];
|
||||
const components_needing_init = ($scope || $('body')).find('.Component_Init');
|
||||
|
||||
if (components_needing_init.length > 0) {
|
||||
console_debug('JQHTML_INIT', `Initializing ${components_needing_init.length} DOM components`);
|
||||
}
|
||||
@@ -80,35 +165,27 @@ class Jqhtml_Integration {
|
||||
components_needing_init.each(function () {
|
||||
const $element = $(this);
|
||||
|
||||
// Skip if element is no longer attached to the document
|
||||
// (may have been removed by a parent component's .empty() call)
|
||||
// Guard: Element may have been removed by a parent component's render
|
||||
if (!document.contains($element[0])) {
|
||||
return;
|
||||
}
|
||||
|
||||
// Check if any parent has Component_Init class - skip nested components
|
||||
// Guard: Skip nested components - they'll be processed after their parent renders
|
||||
let parent = $element[0].parentElement;
|
||||
while (parent) {
|
||||
if (parent.classList.contains('Component_Init')) {
|
||||
return; // Skip this element, it's nested
|
||||
return;
|
||||
}
|
||||
parent = parent.parentElement;
|
||||
}
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────
|
||||
// STEP 1: Extract hydration data from placeholder element
|
||||
// ─────────────────────────────────────────────────────────────────
|
||||
const component_name = $element.attr('data-component-init-name');
|
||||
|
||||
// jQuery's .data() doesn't auto-parse JSON - we need to parse it manually
|
||||
let component_args = {};
|
||||
const args_string = $element.attr('data-component-args');
|
||||
|
||||
// Unset component- php side initialization args, it is no longer needed as a compionent attribute
|
||||
// Unsetting also prevents undesired access to this code in other parts of the program, prevening an
|
||||
// unwanted future dependency on this paradigm
|
||||
$element.removeAttr('data-component-init-name');
|
||||
$element.removeAttr('data-component-args');
|
||||
$element.removeData('component-init-name');
|
||||
$element.removeData('component-args');
|
||||
|
||||
let component_args = {};
|
||||
if (args_string) {
|
||||
try {
|
||||
component_args = JSON.parse(args_string);
|
||||
@@ -118,13 +195,22 @@ class Jqhtml_Integration {
|
||||
}
|
||||
}
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────
|
||||
// STEP 2: Remove hydration markers (cleanup)
|
||||
//
|
||||
// These attributes served their purpose. Removing them:
|
||||
// - Prevents accidental re-hydration
|
||||
// - Hides implementation details from DOM inspection
|
||||
// - Prevents other code from depending on this internal mechanism
|
||||
// ─────────────────────────────────────────────────────────────────
|
||||
$element.removeAttr('data-component-init-name');
|
||||
$element.removeAttr('data-component-args');
|
||||
$element.removeData('component-init-name');
|
||||
$element.removeData('component-args');
|
||||
|
||||
if (component_name) {
|
||||
// Transform $ prefixed keys to data- attributes
|
||||
let component_args_filtered = {};
|
||||
for (const [key, value] of Object.entries(component_args)) {
|
||||
// if (key.startsWith('$')) {
|
||||
// component_args_filtered[key.substring(1)] = value;
|
||||
// } else
|
||||
if (key.startsWith('data-')) {
|
||||
component_args_filtered[key.substring(5)] = value;
|
||||
} else {
|
||||
@@ -133,29 +219,41 @@ class Jqhtml_Integration {
|
||||
}
|
||||
|
||||
try {
|
||||
// Store inner HTML as string for nested component processing
|
||||
// ─────────────────────────────────────────────────────────
|
||||
// STEP 3: Capture innerHTML for slot/content() processing
|
||||
//
|
||||
// Blade content between <Component>...</Component> tags
|
||||
// becomes available to the template via content() function
|
||||
// ─────────────────────────────────────────────────────────
|
||||
component_args_filtered._inner_html = $element.html();
|
||||
$element.empty();
|
||||
|
||||
// Remove the init class before instantiation to prevent re-initialization
|
||||
// ─────────────────────────────────────────────────────────
|
||||
// STEP 4: Instantiate the component
|
||||
//
|
||||
// Remove .Component_Init first to prevent re-initialization
|
||||
// if this element is somehow scanned again
|
||||
// ─────────────────────────────────────────────────────────
|
||||
$element.removeClass('Component_Init');
|
||||
|
||||
// Create promise for this component's initialization
|
||||
const component_promise = new Promise((resolve) => {
|
||||
// Use jQuery component plugin to create the component
|
||||
// Plugin handles element internally, just pass args
|
||||
// Get the updated $element from
|
||||
// $().component(name, args) creates the component instance,
|
||||
// binds it to the element, and starts the lifecycle
|
||||
let component = $element.component(component_name, component_args_filtered).component();
|
||||
|
||||
// ─────────────────────────────────────────────────────
|
||||
// STEP 5: Recurse after render
|
||||
//
|
||||
// Component's template may contain nested .Component_Init
|
||||
// elements. We must wait for render before we can find them.
|
||||
//
|
||||
// Note: If the template changed the tag (e.g., tag="button"),
|
||||
// the original $element may have been replaced. Always use
|
||||
// component.$ to get the current element.
|
||||
// ─────────────────────────────────────────────────────
|
||||
component.on('render', function () {
|
||||
// Recursively collect promises from nested components
|
||||
|
||||
// Getting the updated component here - if the tag name was not div, the element would have been recreated, so we need to get the element set on the component, not from our earlier selector
|
||||
|
||||
const nested_promises = Jqhtml_Integration._on_framework_modules_init(component.$);
|
||||
promises.push(...nested_promises);
|
||||
|
||||
// Resolve this component's promise
|
||||
resolve();
|
||||
}).$;
|
||||
});
|
||||
@@ -168,7 +266,9 @@ class Jqhtml_Integration {
|
||||
}
|
||||
});
|
||||
|
||||
// Top-level call: spawn async handler to wait for all promises, then trigger event
|
||||
// ─────────────────────────────────────────────────────────────────────
|
||||
// COMPLETION: Top-level call waits for all components, then signals ready
|
||||
// ─────────────────────────────────────────────────────────────────────
|
||||
if (is_top_level) {
|
||||
(async () => {
|
||||
await Promise.all(promises);
|
||||
@@ -177,26 +277,23 @@ class Jqhtml_Integration {
|
||||
return;
|
||||
}
|
||||
|
||||
// Recursive call: return promises for parent to collect
|
||||
// Recursive calls return promises for parent to collect
|
||||
return promises;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all registered component names
|
||||
* @returns {Array<string>} Array of component names
|
||||
*/
|
||||
// ═══════════════════════════════════════════════════════════════════════
|
||||
// Utility Methods (pass-through to jqhtml runtime)
|
||||
// ═══════════════════════════════════════════════════════════════════════
|
||||
|
||||
/** Get all registered component names. Useful for debugging/introspection. */
|
||||
static get_component_names() {
|
||||
return jqhtml.get_component_names();
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a component is registered
|
||||
* @param {string} name Component name
|
||||
* @returns {boolean} True if component is registered
|
||||
*/
|
||||
/** Check if a component is registered by name. */
|
||||
static has_component(name) {
|
||||
return jqhtml.has_component(name);
|
||||
}
|
||||
}
|
||||
|
||||
// RSX manifest automatically makes classes global - no manual assignment needed
|
||||
// Class is automatically made global by RSX manifest - no window assignment needed
|
||||
|
||||
Reference in New Issue
Block a user