sdc_client 0.158.8 → 0.159.0

package/docs/controllers.rst

@@ -1,228 +0,0 @@
-Controllers
-===========
-
-Base class
-----------
-
-All controllers extend ``AbstractSDC``.
-
-Common properties
------------------
-
-``contentUrl``
-   Backend URL used to load the controller's HTML fragment.
-
-``contentReload``
-   If ``true``, the content is always reloaded instead of using the cached
-   HTML fragment.
-
-``events``
-   List of event definition objects merged into one event map.
-
-``load_async``
-   If ``true``, the controller lifecycle does not block parent initialization.
-
-``$container``
-   jQuery wrapper for the DOM element associated with the controller.
-
-``parentController`` / ``childController``
-   Accessors for the controller tree.
-
-Lifecycle
----------
-
-``onInit(...args)``
-   Runs immediately after the controller is created. Arguments are resolved
-   from DOM ``data-*`` attributes.
-
-``onLoad(html)``
-   Runs after the controller HTML has been fetched but before child controller
-   tags are replaced. This is a common place to mutate the loaded fragment.
-
-``willShow()``
-   Runs after child controller content has been prepared and before refresh.
-
-``onRefresh(originController)``
-   Runs after DOM updates and event wiring are complete.
-
-``onRemove()``
-   Runs when the controller is being removed. Return ``false`` to block
-   removal.
-
-Example lifecycle
------------------
-
-.. code-block:: javascript
-
-   class ProductList extends AbstractSDC {
-     constructor() {
-       super();
-       this.contentUrl = "/sdc_view/shop/product-list/";
-     }
-
-     onInit(categoryId) {
-       this.categoryId = categoryId;
-     }
-
-     onLoad(html) {
-       $(html).find(".title").text(`Category ${this.categoryId}`);
-       return super.onLoad(html);
-     }
-
-     willShow() {
-       this.loadedAt = Date.now();
-     }
-
-     onRefresh() {
-       console.log("ProductList refreshed");
-     }
-   }
-
-DOM events
-----------
-
-Controller events are delegated through the document window and stored as
-``sdc_<event-name>`` attributes on matching elements.
-
-Example:
-
-.. code-block:: javascript
-
-   class TodoList extends AbstractSDC {
-     constructor() {
-       super();
-       this.events.unshift({
-         click: {
-           ".add-button": "addItem",
-           ".delete-button": "deleteItem",
-         },
-         submit: {
-           "form": "saveForm",
-         },
-       });
-     }
-
-     addItem($element, event) {}
-     deleteItem($element, event) {}
-     saveForm($element, event) {}
-   }
-
-The handler receives:
-
-- the matched jQuery element
-- the original browser event
-
-You can also register events at runtime with ``addEvent(event, selector,
-handler)``.
-
-Mixins
-------
-
-Controllers can aggregate other registered controller classes as mixins.
-
-.. code-block:: javascript
-
-   app.register(BaseList);
-   app.register(Sortable);
-   app.register(Filterable);
-
-   app.register(ProductList)
-     .addMixin(Sortable, Filterable);
-
-Mixin methods and event definitions are merged into the controller instance.
-Lifecycle methods on mixins are invoked through ``AbstractSDC._runLifecycle()``.
-
-Refresh, reload, and reconciliation
------------------------------------
-
-``refresh()``
-   Re-runs nested controller replacement and handler-bound ``<this.*>`` DOM
-   fragments inside the controller container.
-
-``reload()``
-   Reloads the controller HTML from ``contentUrl`` and reconciles it into the
-   existing DOM tree.
-
-``reconcile($virtualNode, $realNode = null)``
-   Diffs the virtual and real DOM trees and preserves matching elements where
-   possible. This is used to keep elements such as form inputs stable across
-   updates.
-
-Safe DOM helpers
-----------------
-
-The runtime installs jQuery helpers:
-
-- ``$elem.safeReplace($new)``
-- ``$elem.safeEmpty()``
-- ``$elem.safeRemove()``
-
-These helpers call controller removal logic before modifying the DOM so child
-controllers can clean up sockets, events, and internal state.
-
-Rendering dynamic fragments with ``sdcDom`` and ``<this.*>``
-------------------------------------------------------------
-
-The global ``window.sdcDom()`` helper creates DOM fragments compatible with
-the controller refresh pipeline.
-
-When the tag name is a function, the runtime creates a ``<this.functionName>``
-placeholder that is rebound during refresh.
-
-This enables patterns like:
-
-.. code-block:: javascript
-
-   class Demo extends AbstractSDC {
-     onLoad(html) {
-       $(html).append("<this.listview></this.listview>");
-       return super.onLoad(html);
-     }
-
-     listview() {
-       return "<div>Dynamic content</div>";
-     }
-   }
-
-During ``refresh()``, the runtime resolves these placeholders by calling the
-matching controller method and reconciling the result into the current DOM.
-
-Backend method calls
---------------------
-
-Use ``serverCall(methodName, args)`` to invoke a backend controller method.
-
-.. code-block:: javascript
-
-   class InvoiceEditor extends AbstractSDC {
-     approve() {
-       return this.serverCall("approve", { approved: true });
-     }
-   }
-
-``serverCall()`` uses:
-
-- AJAX if ``window.SERVER_CALL_VIA_WEB_SOCKET`` is falsy
-- WebSockets if it is truthy
-
-For ``serverCall()`` to work, ``contentUrl`` must contain an ``sdc_view/<app>/``
-segment so the client can infer the backend app name.
-
-Model-aware forms
------------------
-
-``AbstractSDC`` includes a default model form submit pipeline.
-
-``submitModelFormDistributor($form, event)``
-   Dispatches to ``_submitModelForm()``, ``submitModelForm()``, or
-   ``defaultSubmitModelForm()``.
-
-``defaultSubmitModelForm($form, event)``
-   Reads the model from form metadata, submits ``save()`` or ``create()``,
-   clears validation errors on success, and reconciles returned error HTML on
-   failure.
-
-Controllers and their descendants can react to the result through:
-
-- ``submit_model_form_success(result)``
-- ``submit_model_form_error(errorData)``

package/docs/events-and-dom.rst

@@ -1,120 +0,0 @@
-Events and DOM
-==============
-
-Application event bus
----------------------
-
-SimpleDomControlClient includes a small application-level event bus in addition
-to browser DOM events.
-
-Exports:
-
-- ``setEvent(name, functionName = name)``
-- ``on(name, controller)``
-- ``trigger(name, ...args)``
-- ``allOff(controller)``
-
-Usage:
-
-.. code-block:: javascript
-
-   import { setEvent, on, trigger } from "sdc_client";
-
-   setEvent("pushMsg", "handleMessage");
-
-   class Toasts {
-     handleMessage(title, message) {
-       console.log(title, message);
-     }
-   }
-
-   const toasts = new Toasts();
-   on("pushMsg", toasts);
-   trigger("pushMsg", "Saved", "The item was stored.");
-
-The server transport uses this event bus to emit:
-
-- ``pushMsg`` for non-error messages
-- ``pushErrorMsg`` for error messages
-- ``onNavLink`` for redirects
-
-DOM event delegation
---------------------
-
-The DOM event system listens on ``window`` for standard browser events and
-dispatches them to controller handlers declared on matching elements.
-
-The pipeline works as follows:
-
-1. ``initEvents()`` subscribes to standard browser events.
-2. When jQuery triggers a previously unseen custom event, the runtime adds it
-   to the watched event list automatically.
-3. ``windowEventHandler()`` walks from the event target upward through the DOM.
-4. For each element with a matching ``sdc_<event>`` attribute, the handler
-   resolves the owning controller.
-5. The handler name is matched either directly on the controller or through the
-   controller event map.
-
-Declarative event attributes
-----------------------------
-
-Elements can carry event attributes directly:
-
-.. code-block:: html
-
-   <button sdc_click="save">Save</button>
-
-If ``save`` exists on the current controller, it will be called with:
-
-- ``$element``: the matched jQuery element
-- ``event``: the native event object
-
-Controller event maps
----------------------
-
-A more maintainable pattern is to define events in the controller:
-
-.. code-block:: javascript
-
-   this.events.unshift({
-     click: {
-       ".save-button": "save",
-       ".delete-button": "removeItem",
-     },
-   });
-
-At refresh time, ``setControllerEvents()`` finds the matching selectors and
-adds internal ``sdc_<event>`` attributes to the corresponding DOM nodes.
-
-DOM reconciliation
-------------------
-
-The client contains a custom reconciliation step used by ``app.reconcile()``
-and controller refresh operations.
-
-Goals of reconciliation:
-
-- keep matching DOM branches when possible
-- update attributes and data bindings
-- preserve stable nodes such as input elements
-- remove and insert only what changed
-
-The implementation builds trees for the virtual and real DOM, computes a
-longest-common-branch style diff, then applies keep, delete, and insert
-operations in index order.
-
-This is the main reason refreshed content can preserve existing input elements
-instead of replacing them outright.
-
-Safe removal semantics
-----------------------
-
-Always prefer the SDC-safe helpers over direct jQuery removal when a subtree may
-contain controllers:
-
-- ``app.safeRemove($elem)``
-- ``app.safeEmpty($elem)``
-- ``app.safeReplace($elem, $new)``
-
-These helpers call controller ``remove()`` methods first so child controllers
-can unregister application events, close sockets, and clean up forms.

package/docs/getting-started.rst

@@ -1,143 +0,0 @@
-Getting Started
-===============
-
-Requirements
-------------
-
-SimpleDomControlClient is designed to be used together with the Django package
-``simpledomcontrol``. The backend is expected to provide:
-
-- Controller content endpoints referenced by ``contentUrl``.
-- Optional server controller methods for ``serverCall()``.
-- Model WebSocket endpoints for ``SdcQuerySet`` and ``SdcModel`` usage.
-- Global values such as ``window.CSRF_TOKEN`` and optionally
-  ``window.SERVER_CALL_VIA_WEB_SOCKET``.
-
-Installation
-------------
-
-Install the package in a frontend project:
-
-.. code-block:: bash
-
-   yarn add sdc_client
-
-or:
-
-.. code-block:: bash
-
-   npm install sdc_client
-
-Basic bootstrap
----------------
-
-Import the runtime, define a controller, register it, and call ``init_sdc()``.
-
-.. code-block:: javascript
-
-   import { app, AbstractSDC } from "sdc_client";
-
-   class HelloWorld extends AbstractSDC {
-     constructor() {
-       super();
-       this.contentUrl = "/sdc_view/demo/hello-world/";
-       this.events.unshift({
-         click: {
-           ".reload-button": "handleReload",
-         },
-       });
-     }
-
-     onInit(name = "World") {
-       this.name = name;
-     }
-
-     handleReload() {
-       return this.reload();
-     }
-   }
-
-   app.register(HelloWorld);
-   app.init_sdc();
-
-In the HTML:
-
-.. code-block:: html
-
-   <hello-world data-name='"Ada"'></hello-world>
-
-Tag name mapping
-----------------
-
-Controller classes are mapped to tag names automatically.
-
-- ``HelloWorld`` becomes ``<hello-world>``.
-- A class ending in ``Controller`` has the suffix removed.
-- ``UserListController`` becomes ``<user-list>``.
-
-The mapping is implemented by ``app.controllerToTag()``.
-
-Controller content loading
---------------------------
-
-If a controller sets ``contentUrl``, the runtime fetches HTML for that
-controller before rendering nested child controllers.
-
-Important behavior:
-
-- ``contentUrl = ""`` means no remote HTML is fetched.
-- URLs containing placeholder values such as ``"%(user_id)s"`` are re-parsed
-  from DOM data attributes and force ``contentReload = true``.
-- Responses are cached per controller tag unless ``contentReload`` is true.
-
-Using ``data-*`` parameters
----------------------------
-
-``onInit()`` arguments are populated from the DOM element's ``data-*``
-attributes. The final argument is always an object with the remaining data
-values.
-
-Example:
-
-.. code-block:: html
-
-   <user-card
-     data-user-id="7"
-     data-title='"Admin"'
-     data-active="true">
-   </user-card>
-
-.. code-block:: javascript
-
-   class UserCard extends AbstractSDC {
-     onInit(userId, title, active, rest) {
-       this.userId = userId;   // 7
-       this.title = title;     // "Admin"
-       this.active = active;   // true
-       this.rest = rest;       // remaining data attributes
-     }
-   }
-
-The parameter parser converts:
-
-- integers to ``number``
-- floats to ``number``
-- ``true`` and ``false`` to ``boolean``
-- ``none`` to ``null``
-- ``undefined`` to ``undefined``
-- quoted strings to plain strings
-- controller property names to the corresponding controller value or method
-
-Global controllers
-------------------
-
-Register a controller as global when it should be instantiated once and exposed
- through the global controller tree rather than repeated per matching DOM
-container.
-
-.. code-block:: javascript
-
-   app.registerGlobal(NotificationsController);
-
-Global controllers are created during ``app.init_sdc()`` before regular body
-controllers are resolved.

package/docs/index.rst

@@ -1,22 +0,0 @@
-SimpleDomControlClient
-======================
-
-SimpleDomControlClient is the browser-side runtime for the Django package
-``simpledomcontrol``. It scans the DOM for registered custom tags, creates
-controller instances, loads HTML fragments from the server, binds DOM events,
-and synchronizes model data through AJAX and WebSockets.
-
-This documentation is organized around the way the library is used in a real
-application: bootstrap the runtime, register controllers, render content,
-handle events, and talk to server-backed models.
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents
-
-   overview
-   getting-started
-   controllers
-   models
-   events-and-dom
-   api-reference