surf-core 0.1.0

package/src/surf.js

@@ -0,0 +1,179 @@
+/**
+ * SURF - HTML-first, server-driven UI framework
+ * 
+ * Mental model: "Surface changes, Cell lives."
+ * 
+ * The server is the source of truth.
+ * The client handles only temporary, local interactions.
+ * HTML is the primary data format.
+ * UI changes happen through HTML patches, not JSON APIs.
+ */
+
+import * as Surface from './surface.js';
+import * as Cell from './cell.js';
+import * as Signal from './signal.js';
+import * as Pulse from './pulse.js';
+import * as Patch from './patch.js';
+import * as Echo from './echo.js';
+
+/**
+ * Global Surf object - the public API
+ */
+const Surf = {
+  /**
+   * Framework version
+   */
+  version: '0.1.0',
+  
+  /**
+   * Navigate to a URL
+   * @param {string} url - The URL to navigate to
+   * @param {Object} options - Optional settings (target, swap, etc)
+   */
+  go(url, options = {}) {
+    return Pulse.go(url, options);
+  },
+  
+  /**
+   * Refresh a surface's content from the server
+   * @param {string} selector - The surface selector to refresh
+   */
+  refresh(selector) {
+    return Pulse.refresh(selector);
+  },
+  
+  /**
+   * Subscribe to framework events
+   * @param {string} event - Event name: 'before:pulse', 'after:patch', 'error:network'
+   * @param {function} callback - Event handler
+   */
+  on(event, callback) {
+    Pulse.on(event, callback);
+  },
+  
+  /**
+   * Unsubscribe from framework events
+   * @param {string} event - Event name
+   * @param {function} callback - Event handler to remove
+   */
+  off(event, callback) {
+    Pulse.off(event, callback);
+  },
+  
+  /**
+   * Get cell state for an element
+   * @param {Element|string} cellOrSelector - Cell element or selector
+   * @returns {Object} The cell's current state
+   */
+  getState(cellOrSelector) {
+    const cell = typeof cellOrSelector === 'string' 
+      ? document.querySelector(cellOrSelector)
+      : cellOrSelector;
+    return Cell.getState(cell);
+  },
+  
+  /**
+   * Set cell state for an element
+   * @param {Element|string} cellOrSelector - Cell element or selector
+   * @param {Object} state - State to merge
+   */
+  setState(cellOrSelector, state) {
+    const cell = typeof cellOrSelector === 'string'
+      ? document.querySelector(cellOrSelector)
+      : cellOrSelector;
+    Cell.setState(cell, state);
+    Signal.updateBindings(cell);
+  },
+  
+  /**
+   * Manually apply a patch response
+   * @param {string} patchHtml - The patch HTML string
+   */
+  applyPatch(patchHtml) {
+    const patches = Patch.parse(patchHtml);
+    patches.forEach(({ target, content }) => {
+      const surface = Surface.getBySelector(target) || document.querySelector(target);
+      if (surface) {
+        Echo.withPreservation(surface, content, () => {
+          Surface.replace(target, content);
+          // Re-initialize signals and cells on the updated surface
+          Cell.initAll(surface);
+          Signal.initAll(surface);
+        });
+      }
+    });
+  },
+  
+  /**
+   * Register a module for signal expressions
+   * @param {string} name - Module namespace
+   * @param {Object} module - Object with methods
+   */
+  register(name, module) {
+    Signal.register(name, module);
+  },
+
+  /**
+   * Install a plugin
+   * @param {Object} plugin - Plugin object with install method
+   * @param {Object} options - Plugin options
+   */
+  use(plugin, options = {}) {
+    if (plugin && typeof plugin.install === 'function') {
+      plugin.install(this, options);
+    }
+    return this;
+  },
+
+
+  
+
+  
+  // Expose modules for advanced usage
+  _modules: {
+    Surface,
+    Cell,
+    Signal,
+    Pulse,
+    Patch,
+    Echo
+  }
+};
+
+/**
+ * Initialize SURF when the DOM is ready
+ */
+function init() {
+  // Initialize surfaces
+  Surface.init();
+  
+  // Initialize cells
+  Cell.initAll();
+  
+  // Initialize signals (reactive bindings)
+  Signal.initAll();
+  
+  // Initialize pulse (event interception)
+  Pulse.init();
+
+  // Register core modules for signals
+  Signal.register('Pulse', Pulse);
+  
+  console.log(`[Surf] Initialized v${Surf.version}`);
+}
+
+// Auto-initialize on DOMContentLoaded
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', init);
+} else {
+  init();
+}
+
+// Export for module usage
+export { Surface, Cell, Signal, Pulse, Patch, Echo };
+export default Surf;
+
+// Attach to window for script tag usage
+if (typeof window !== 'undefined') {
+  window.Surf = Surf;
+}

package/src/surface.js

@@ -0,0 +1,160 @@
+/**
+ * Surface Module
+ * 
+ * A Surface is a DOM region that can be replaced by server responses.
+ * Defined with: d-surface
+ */
+
+const SURFACE_ATTR = 'd-surface';
+
+/**
+ * Find all surface elements in the document
+ * @returns {NodeListOf<Element>}
+ */
+export function findAll() {
+  return document.querySelectorAll(`[${SURFACE_ATTR}]`);
+}
+
+/**
+ * Get a surface element by its ID
+ * @param {string} id - The surface ID (without #)
+ * @returns {Element|null}
+ */
+export function getById(id) {
+  const cleanId = id.startsWith('#') ? id.slice(1) : id;
+  const element = document.getElementById(cleanId);
+  
+  if (element && element.hasAttribute(SURFACE_ATTR)) {
+    return element;
+  }
+  
+  return null;
+}
+
+/**
+ * Get a surface element by selector
+ * @param {string} selector - CSS selector
+ * @returns {Element|null}
+ */
+export function getBySelector(selector) {
+  const element = document.querySelector(selector);
+  
+  if (element && element.hasAttribute(SURFACE_ATTR)) {
+    return element;
+  }
+  
+  return null;
+}
+
+/**
+ * Replace surface content with new HTML
+ * @param {string|Element} selectorOrElement - Target surface selector or element
+ * @param {string} html - New HTML content
+ * @returns {Element|null} - The updated surface element
+ */
+export function replace(selectorOrElement, html) {
+  // Handle both selector strings and element references
+  let surface;
+  if (typeof selectorOrElement === 'string') {
+    surface = getBySelector(selectorOrElement) || document.querySelector(selectorOrElement);
+  } else {
+    surface = selectorOrElement;
+  }
+  
+  if (!surface) {
+    console.warn(`[Surf] Surface not found: ${selectorOrElement}`);
+    return null;
+  }
+  
+  // Create a template to parse the HTML
+  const template = document.createElement('template');
+  template.innerHTML = html.trim();
+  
+  // Replace inner content, preserving the surface element itself
+  surface.innerHTML = '';
+  
+  // Append all children from the template
+  while (template.content.firstChild) {
+    surface.appendChild(template.content.firstChild);
+  }
+  
+  return surface;
+}
+
+/**
+ * Append content to surface
+ * @param {string|Element} selectorOrElement 
+ * @param {string} html 
+ * @returns {Element|null}
+ */
+export function append(selectorOrElement, html) {
+  return inject(selectorOrElement, html, 'beforeend');
+}
+
+/**
+ * Prepend content to surface
+ * @param {string|Element} selectorOrElement 
+ * @param {string} html 
+ * @returns {Element|null}
+ */
+export function prepend(selectorOrElement, html) {
+  return inject(selectorOrElement, html, 'afterbegin');
+}
+
+/**
+ * Inject content into surface at position
+ * @param {string|Element} selectorOrElement 
+ * @param {string} html 
+ * @param {string} position - 'beforeend' or 'afterbegin'
+ * @returns {Element|null}
+ */
+function inject(selectorOrElement, html, position) {
+  let surface;
+  if (typeof selectorOrElement === 'string') {
+    surface = getBySelector(selectorOrElement) || document.querySelector(selectorOrElement);
+  } else {
+    surface = selectorOrElement;
+  }
+  
+  if (!surface) {
+    console.warn(`[Surf] Surface not found: ${selectorOrElement}`);
+    return null;
+  }
+  
+  const template = document.createElement('template');
+  template.innerHTML = html.trim();
+  
+  // Use DocumentFragment for efficient insertion
+  const fragment = document.createDocumentFragment();
+  while (template.content.firstChild) {
+    fragment.appendChild(template.content.firstChild);
+  }
+  
+  if (position === 'beforeend') {
+    surface.appendChild(fragment);
+  } else {
+    surface.insertBefore(fragment, surface.firstChild);
+  }
+  
+  return surface;
+}
+
+/**
+ * Initialize surfaces - mark them as ready
+ */
+export function init() {
+  const surfaces = findAll();
+  surfaces.forEach(surface => {
+    surface.setAttribute('data-surf-ready', 'true');
+  });
+}
+
+export default {
+  findAll,
+  getById,
+  getBySelector,
+  replace,
+  append,
+  prepend,
+  init
+};