sdc_client 0.58.6 → 0.158.0

package/docs/events-and-dom.rst

@@ -0,0 +1,120 @@
+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

@@ -0,0 +1,143 @@
+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

@@ -0,0 +1,22 @@
+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

package/docs/models.rst

@@ -0,0 +1,351 @@
+Models
+======
+
+Overview
+--------
+
+Model support in SimpleDomControlClient is centered on two pieces:
+
+``SdcModel``
+   A client-side object representing one backend record.
+
+``SdcQuerySet``
+   A live collection wrapper that loads, updates, saves, deletes, and renders
+   model-backed content over the SDC model transport.
+
+The client expects the backend to expose the SDC model WebSocket protocol for:
+
+- connect handshakes
+- queryset loading
+- item updates
+- item creation
+- deletion
+- server-rendered views
+- server-rendered forms
+- chunked file uploads
+
+Registering model classes
+-------------------------
+
+Model classes must be registered by name so queryset responses can be turned
+into the correct JavaScript class.
+
+.. code-block:: javascript
+
+   import { registerModel } from "sdc_client";
+   import Author from "./models/Author.js";
+   import Book from "./models/Book.js";
+
+   registerModel("Author", Author);
+   registerModel("Book", Book);
+
+The registry is global. Once a class is registered, any queryset for that model
+name can construct typed instances.
+
+How controllers use models
+--------------------------
+
+Controllers usually create querysets through ``AbstractSDC.querySet()``:
+
+.. code-block:: javascript
+
+   class AuthorList extends AbstractSDC {
+     onInit() {
+       this.authors = this.querySet("Author", { active: true });
+     }
+
+     async onLoad(html) {
+       await this.authors.load();
+       return super.onLoad(html);
+     }
+   }
+
+This attaches the queryset to the controller so open sockets can be tracked and
+closed when the controller is removed.
+
+``SdcQuerySet`` as a collection
+-------------------------------
+
+``SdcQuerySet`` behaves like an array-like collection through a proxy.
+
+You can:
+
+- read ``queryset.length``
+- access ``queryset[0]``
+- iterate with ``for (const item of queryset)``
+- call ``queryset.getIds()`` to get the current primary keys
+- call ``queryset.byId(id)`` to look up a loaded instance
+
+Example:
+
+.. code-block:: javascript
+
+   await this.authors.load();
+
+   for (const author of this.authors) {
+     console.log(author.id, author.name);
+   }
+
+   const ada = this.authors.byId(1);
+
+Loading and refreshing data
+---------------------------
+
+There are two important ways to fetch queryset data:
+
+``load(modelQuery = null)``
+   Clears the current queryset cache and fetches matching rows from the server.
+   Use this when you want a fresh dataset and do not need to preserve the
+   current ``valuesList`` content.
+
+``update({ modelQuery = null, item = null })``
+   Refreshes server state as an alternative to ``load()``. Use this when the
+   queryset already exists and should be synchronized again. It can refresh:
+
+   - the active queryset filter
+   - a replacement filter passed through ``modelQuery``
+   - one specific item when ``item`` is provided
+
+Typical guidance:
+
+- use ``load()`` for the initial fetch
+- use ``update()`` when the queryset already exists and you want to re-sync it
+- use ``update({ item })`` when one known model may have changed and only that
+  record needs to be refreshed
+
+Example:
+
+.. code-block:: javascript
+
+   await this.authors.load({ active: true });
+
+   // Later, refresh the same queryset
+   await this.authors.update({});
+
+   // Refresh a specific item only
+   await this.authors.update({ item: this.authors.byId(1) });
+
+Filtering and identity helpers
+------------------------------
+
+``setFilter(modelQuery)``
+   Replaces the queryset filter.
+
+``addFilter(modelQuery)``
+   Merges additional constraints into the current filter.
+
+``setIds(ids)``
+   Rebuilds the queryset from ids, another queryset, a single model, or a list
+   of ids. This is mainly useful for relation fields and client-side relation
+   synchronization.
+
+``get(modelQuery = null)``
+   Loads and returns exactly one item. It throws when the result count is not
+   exactly one.
+
+Creating and saving models
+--------------------------
+
+``new()``
+   Creates a new empty registered model instance, binds it to the queryset, and
+   appends it to ``valuesList``.
+
+``save({ pk = null, formName = "edit_form", data = null })``
+   Saves one or more existing models. If ``pk`` is given, the queryset saves
+   that one item. Otherwise it saves the current queryset items. If ``data`` is
+   omitted, the client uses the model's ``serialize()`` output.
+
+``create({ elem, data = null })``
+   Creates a new backend record. If ``data`` is omitted, the payload is taken
+   from the model instance serialization.
+
+``delete({ pk = null, elem = null })``
+   Deletes a record by primary key or by model object.
+
+Example:
+
+.. code-block:: javascript
+
+   const author = this.authors.new();
+   author.name = "Ada Lovelace";
+   author.age = 36;
+
+   await this.authors.create({ elem: author });
+
+   author.age = 37;
+   await this.authors.save({ pk: author.id });
+
+Server-rendered model views
+---------------------------
+
+``SdcQuerySet`` can request server-rendered HTML and return it as a container
+that is automatically passed through ``app.refresh()`` when the response
+arrives.
+
+Available methods:
+
+``view({ viewName, modelQuery, cbResolve, cbReject, templateContext, eventType })``
+   Generic named view renderer.
+
+``listView({ modelQuery, cbResolve, cbReject, templateContext })``
+   Convenience wrapper for list-style rendering.
+
+``detailView({ pk, cbResolve, cbReject, templateContext })``
+   Convenience wrapper for a single object detail view.
+
+Example:
+
+.. code-block:: javascript
+
+   const $list = this.authors.listView({
+     modelQuery: { active: true },
+     templateContext: { compact: true },
+   });
+
+   this.$container.find(".results").append($list);
+
+Form synchronization and ``SdcModel`` state
+-------------------------------------------
+
+The most important rule for model forms is this:
+
+``SdcModel`` properties and form fields are expected to stay synchronized.
+
+The form is not treated as an independent data store. It is a view of the
+model object.
+
+That synchronization happens in both directions:
+
+``syncModelToForm($form)``
+   Copies model properties into the form.
+
+``syncForm($form)``
+   Reads values from the form back into the ``SdcModel`` object and returns the
+   data used for submission.
+
+This behavior matters because the default controller submit flow operates on the
+model instance associated with the form, not on a detached raw payload.
+
+Practical consequences:
+
+- when model properties change, the form should be updated from the model
+- when the user edits the form, the model should be updated from the form
+- hidden fields are parsed back into typed JavaScript values
+- file inputs become ``File`` objects on the model
+- relation fields are converted into related ids or queryset-backed relations
+
+The model object therefore remains the source of truth across:
+
+- initial form rendering
+- edits
+- create calls
+- save calls
+- validation error flows
+- later refreshes of the same object
+
+How queryset form rendering works
+---------------------------------
+
+The internal queryset form helper fetches server-rendered create or edit forms
+and attaches the metadata expected by controller form submission.
+
+When a form is prepared, the client:
+
+- renders the returned HTML into the target container
+- marks the form as create or edit
+- stores ``data("model", modelObj)``
+- stores ``data("model_pk", pk)``
+- stores ``data("form_name", formName)``
+- adds ``sdc_submit="submitModelFormDistributor"`` if missing
+- registers the form on the model via ``addForm($form)``
+
+This is why ``AbstractSDC.defaultSubmitModelForm()`` can read the bound model
+from the form and choose between ``create()`` and ``save()`` automatically.
+
+Validation errors and model-backed forms
+----------------------------------------
+
+On submit failure, the controller default form handler reconciles returned form
+HTML back into the existing DOM rather than replacing the entire subtree
+blindly.
+
+That allows the application to:
+
+- keep the controller tree intact
+- preserve more stable DOM nodes where possible
+- show backend validation errors in the rendered form
+- continue working with the same underlying ``SdcModel`` instance
+
+Even when the error HTML changes, the client-side model object still represents
+the active record being edited.
+
+Relationships
+-------------
+
+The test suite shows two important serialization conventions:
+
+- many-to-one relations are serialized as a single related primary key
+- one-to-many relations are serialized as a list of related primary keys
+
+This lets model instances expose richer client-side relation objects while
+sending backend-friendly payloads.
+
+Expected ``SdcModel`` capabilities
+----------------------------------
+
+The client code and tests imply that registered model classes should provide at
+least the following behavior:
+
+- scalar field properties such as ``id``, ``name``, ``title``, and similar
+- relation fields that can accept ids and queryset/model objects
+- ``serialize()`` for backend payload generation
+- ``syncModelToForm($form)`` for writing model state into form fields
+- ``syncForm($form)`` for reading form fields back into model state
+- ``addForm($form)`` for tracking rendered forms
+- queryset linkage so save/create operations know where the model belongs
+
+Connection lifecycle
+--------------------
+
+Each queryset manages its own WebSocket connection state.
+
+Important methods and callbacks:
+
+``isConnected()``
+   Ensures the socket is open and the backend handshake has completed.
+
+``close()``
+   Closes the queryset socket and disables automatic reconnect.
+
+``noOpenRequests()``
+   Resolves when all currently tracked socket requests have completed.
+
+``onUpdate``
+   Callback invoked when the server pushes an update event.
+
+``onCreate``
+   Callback invoked when the server pushes a create event.
+
+File uploads
+------------
+
+If a model contains ``File`` values, the queryset uploads them in chunks before
+issuing the final ``save()`` or ``create()`` request.
+
+This process is automatic:
+
+- file properties are detected on the model object
+- the file is split into chunks
+- upload metadata is sent with each chunk
+- the final save/create payload references the uploaded file data
+
+Summary
+-------
+
+Use the model layer when you need more than static controller HTML:
+
+- ``load()`` for initial queryset fetches
+- ``update()`` for re-synchronizing existing queryset state
+- ``new()``, ``create()``, ``save()``, and ``delete()`` for persistence
+- ``listView()`` and ``detailView()`` for server-rendered model fragments
+- synchronized forms where the ``SdcModel`` object remains the source of truth

package/docs/overview.rst

@@ -0,0 +1,66 @@
+Overview
+========
+
+What the project does
+---------------------
+
+SimpleDomControlClient provides a lightweight component system built around
+custom HTML tags and controller classes.
+
+The client is responsible for:
+
+- Registering controller classes against tag names such as ``<user-list>``.
+- Finding those tags in the DOM and instantiating controller objects.
+- Loading controller HTML from the backend through ``contentUrl``.
+- Running controller lifecycle hooks such as ``onInit()``, ``onLoad()``,
+  ``willShow()``, and ``onRefresh()``.
+- Delegating browser events to controller methods.
+- Refreshing and reconciling DOM updates without discarding matching existing
+  elements.
+- Calling backend controller methods through AJAX or WebSockets.
+- Loading and saving server-backed model data through ``SdcQuerySet`` and
+  ``SdcModel``.
+
+Architecture at a glance
+------------------------
+
+The main exported building blocks are:
+
+``app``
+   Global runtime object. It boots the library, registers controllers,
+   refreshes content, and exposes DOM-safe helper methods.
+
+``AbstractSDC``
+   Base class for all controllers. It provides lifecycle hooks, parent/child
+   relationships, event configuration, server calls, and model/query helpers.
+
+``SdcQuerySet`` and ``SdcModel``
+   Client-side model abstractions used to query, create, update, delete, and
+   render model-backed content.
+
+``on()``, ``trigger()``, ``allOff()``, ``setEvent()``
+   A small application event bus separate from browser DOM events.
+
+Runtime flow
+------------
+
+At startup, ``app.init_sdc()`` performs the following steps:
+
+1. Initializes DOM event delegation.
+2. Ensures the transport layer is ready when server calls use WebSockets.
+3. Builds root controllers for the page body and global controllers.
+4. Scans the DOM for all registered controller tags.
+5. Creates controller instances and binds them to their DOM containers.
+6. Resolves tag parameters from ``data-*`` attributes and calls ``onInit()``.
+7. Loads controller HTML from the backend when ``contentUrl`` is defined.
+8. Replaces nested registered tags recursively.
+9. Wires configured DOM events and triggers ``onRefresh()``.
+
+How this differs from common SPA frameworks
+-------------------------------------------
+
+SimpleDomControlClient is not a virtual-DOM-first SPA framework. The server
+still produces much of the HTML, and controllers are thin client-side objects
+that coordinate DOM behavior around that HTML. The library keeps enough client
+state to support dynamic updates, forms, and model synchronization without
+requiring a full frontend build architecture.

package/docs/requirements.txt

@@ -0,0 +1 @@
+sphinx>=7,<9