sdc_client 0.158.9 → 0.159.0

package/docs/api-reference.rst

@@ -1,225 +0,0 @@
-API Reference
-=============
-
-Top-level exports
------------------
-
-The package entry point exports the following public API:
-
-``app``
-   Global runtime object.
-
-``AbstractSDC``
-   Base controller class.
-
-``SdcModel``
-   Model base export from ``sdc_model.js``.
-
-``SdcQuerySet``
-   QuerySet collection class for backend-backed models.
-
-``registerModel(name, classObj)``
-   Registers a model class in the global model registry.
-
-``on(name, controller)``
-   Registers a controller or object as a listener for an application event.
-
-``trigger(name, ...args)``
-   Emits an application event and returns a promise of listener results.
-
-``allOff(controller)``
-   Removes the controller from all application event subscriptions.
-
-``setEvent(name, functionName = name)``
-   Maps an application event name to a handler method name.
-
-``clearErrorsInForm($form)``
-   Removes form-level and field-level validation error markup.
-
-``setErrorsInForm($form, $resForm)``
-   Applies validation error markup from a response form fragment.
-
-``checkIfParamNumberBoolOrString(value, controller = null)``
-   Converts serialized DOM values into typed JavaScript values.
-
-``controllerFactory(parentController, $element, tagName, superTagNameList)``
-   Creates a controller instance for a registered tag.
-
-``runControlFlowFunctions(controller, process)``
-   Runs ``onLoad()``, child rendering, ``willShow()``, and refresh.
-
-``socketReconnect``
-   Alias of the server-call ``close()`` function.
-
-``test_utils``
-   Test helpers: ``get_controller()``, ``getCsrfToken()``,
-   ``controllerFromTestHtml()``.
-
-``app`` reference
------------------
-
-Bootstrap and registration
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``app.init_sdc()``
-   Initializes the runtime, scans the DOM, and instantiates registered
-   controllers.
-
-``app.register(Controller, overwrite = false)``
-   Registers a controller class and returns an object with ``addMixin(...)``.
-
-``app.registerGlobal(Controller)``
-   Registers a controller and marks it as global.
-
-``app.controllerToTag(Controller)``
-   Converts a controller class name to a tag name.
-
-DOM and controller helpers
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``app.getController($elem)``
-   Returns the controller bound to a DOM node or its closest controller parent.
-
-``app.refresh($dom, leafController = null)``
-   Refreshes the controller subtree rooted at the given node.
-
-``app.reloadController(controller)``
-   Reloads controller HTML from ``contentUrl`` and reconciles it into place.
-
-``app.reconcile(controller, $virtualNode, $realNode = null, process = null)``
-   Runs refresh and DOM reconciliation for a controller.
-
-``app.cleanCache()``
-   Clears cached HTML fragments loaded from controller ``contentUrl`` values.
-
-``app.updateJquery()``
-   Installs ``safeReplace()``, ``safeEmpty()``, and ``safeRemove()`` on jQuery.
-
-Safe DOM operations
-^^^^^^^^^^^^^^^^^^^
-
-``app.safeRemove($elem)``
-   Removes DOM nodes after cleanly removing any controllers contained in them.
-
-``app.safeEmpty($elem)``
-   Safely removes all children of a container.
-
-``app.safeReplace($elem, $new)``
-   Inserts ``$new`` before ``$elem`` and safely removes ``$elem``.
-
-HTTP and form helpers
-^^^^^^^^^^^^^^^^^^^^^
-
-``app.get(controller, url, args)``
-   GET request wrapper that refreshes the controller on success.
-
-``app.post(controller, url, args)``
-   POST request wrapper that refreshes the controller on success.
-
-``app.ajax(controller, url, args, method)``
-   Shared transport wrapper for ``get`` and ``post``.
-
-``app.submitFormAndUpdateView(controller, form, url, method)``
-   Submits a form, then refreshes the controller when successful.
-
-``app.submitForm(form, url, method)``
-   Submits a form without a controller refresh step.
-
-``AbstractSDC`` reference
--------------------------
-
-Tree and DOM
-^^^^^^^^^^^^
-
-``find(selector)``
-   Shortcut for ``this.$container.find(selector)``.
-
-``refresh()``
-   Refreshes the controller subtree.
-
-``reload()``
-   Reloads controller HTML from the backend.
-
-``reconcile($virtualNode, $realNode = null)``
-   Reconciles virtual HTML into the controller's real DOM.
-
-``iterateAllChildren()``
-   Recursively returns all descendant controllers.
-
-Lifecycle
-^^^^^^^^^
-
-``onInit(...args)``
-``onLoad(html)``
-``willShow()``
-``onRefresh(originController)``
-``onRemove()``
-
-Networking and models
-^^^^^^^^^^^^^^^^^^^^^
-
-``get(url, args)``
-``post(url, args)``
-``submitForm(form, url, method)``
-``serverCall(methodName, args)``
-``querySet(modelName, modelQuery = {})``
-``noOpenModelRequests()``
-
-Forms
-^^^^^
-
-``submitModelFormDistributor($form, event)``
-``defaultSubmitModelForm($form, event)``
-
-``SdcQuerySet`` reference
--------------------------
-
-Collection API
-^^^^^^^^^^^^^^
-
-``length``
-``[index]``
-``[Symbol.iterator]()``
-``getIds()``
-``setIds(ids)``
-``byId(id)``
-``new()``
-
-Query and transport
-^^^^^^^^^^^^^^^^^^^
-
-``setFilter(modelQuery)``
-``addFilter(modelQuery)``
-``load(modelQuery = null)``
-``update({ modelQuery = null, item = null })``
-``get(modelQuery = null)``
-``delete({ pk = null, elem = null })``
-``save({ pk = null, formName = "edit_form", data = null })``
-``create({ elem, data = null })``
-``isConnected()``
-``close()``
-``noOpenRequests()``
-
-View rendering
-^^^^^^^^^^^^^^
-
-``view({ viewName = "html_list_template", modelQuery = {}, cbResolve = null,
-cbReject = null, templateContext = {}, eventType = "named_view" })``
-
-``listView({ modelQuery = {}, cbResolve = null, cbReject = null,
-templateContext = {} })``
-
-``detailView({ pk, cbResolve = null, cbReject = null, templateContext = {} })``
-
-Test utilities
---------------
-
-``getCsrfToken()``
-   Reads the ``csrftoken`` cookie in test environments.
-
-``get_controller(tag_name, init_arguments = {}, origen_html = "")``
-   Creates a controller through the normal SDC lifecycle in a JSDOM test.
-
-``controllerFromTestHtml(html, afterLifecycle = null)``
-   Bootstraps controllers from arbitrary test HTML and returns the resulting
-   controller list.

package/docs/conf.py

@@ -1,11 +0,0 @@
-project = "SimpleDomControlClient"
-author = "Martin Starman"
-copyright = "2026, Martin Starman"
-release = "0.58.6"
-
-extensions = []
-templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-
-html_theme = "alabaster"
-html_static_path = ["_static"]

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.