sdc_client 0.158.9 → 0.160.0

package/docs/models.rst

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

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

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

package/eslint.config.js

@@ -1,43 +0,0 @@
-import js from "@eslint/js";
-import globals from "globals";
-
-export default [
-  {
-    ignores: ["dist/**", "node_modules/**"],
-  },
-  {
-    files: ["src/**/*.js"],
-    languageOptions: {
-      sourceType: "module",
-      ecmaVersion: "latest",
-      globals: {
-        ...globals.browser,
-        ...globals.node,
-      },
-    },
-    rules: {
-      ...js.configs.recommended.rules,
-      "no-console": "off",
-      "comma-dangle": ["warn", "only-multiline"],
-      "prefer-destructuring": ["error", { object: true, array: false }],
-      "no-restricted-imports": [
-        "error",
-        {
-          patterns: [
-            {
-              group: ["./*", "../*"],
-              message: "import statements should have an absolute path",
-            },
-          ],
-        },
-      ],
-      "max-len": [
-        "error",
-        {
-          code: 120,
-          ignoreComments: true,
-        },
-      ],
-    },
-  },
-];

package/gulpfile.cjs

@@ -1,30 +0,0 @@
-'use strict'
-
-const gulp = require('gulp');
-const webpack = require('webpack');
-
-function javascript(done) {
-    const webpack_config = (process.env.NODE_ENV === 'development' ? './webpack.config/webpack.development.config.cjs' : './webpack.config/webpack.production.config.cjs');
-
-    const config = Object.assign({entry: {index: './src/index.js'}}, require(webpack_config));
-
-    webpack(config, (err, stats) => {
-        if (err) {
-            return done(err);
-        }
-
-        console.log(stats.toString({colors: true, chunks: false}));
-        return done(stats.hasErrors() ? new Error('webpack build failed') : undefined);
-    });
-}
-
-
-gulp.task('development', gulp.series((done) => {
-    process.env.NODE_ENV = 'development'
-    done();
-}, javascript));
-
-gulp.task('build', gulp.series((done) => {
-    process.env.NODE_ENV = 'production'
-    done();
-}, javascript));

package/jest.config.mjs

@@ -1,197 +0,0 @@
-/*
- * For a detailed explanation regarding each configuration property, visit:
- * https://jestjs.io/docs/configuration
- */
-
-export default {
-  // All imported modules in your tests should be mocked automatically
-  // automock: false,
-
-  // Stop running tests after `n` failures
-  // bail: 0,
-
-  // The directory where Jest should store its cached dependency information
-  // cacheDirectory: "/tmp/jest_rs",
-
-  // Automatically clear mock calls, instances, contexts and results before every test
-  // clearMocks: false,
-
-  // Indicates whether the coverage information should be collected while executing the test
-  collectCoverage: true,
-
-  // An array of glob patterns indicating a set of files for which coverage information should be collected
-  // collectCoverageFrom: undefined,
-
-  // The directory where Jest should output its coverage files
-  coverageDirectory: "coverage",
-
-  // An array of regexp pattern strings used to skip coverage collection
-  // coveragePathIgnorePatterns: [
-  //   "/node_modules/"
-  // ],
-
-  // Indicates which provider should be used to instrument code for coverage
-  coverageProvider: "v8",
-
-  // A list of reporter names that Jest uses when writing coverage reports
-  // coverageReporters: [
-  //   "json",
-  //   "text",
-  //   "lcov",
-  //   "clover"
-  // ],
-
-  // An object that configures minimum threshold enforcement for coverage results
-  // coverageThreshold: undefined,
-
-  // A path to a custom dependency extractor
-  // dependencyExtractor: undefined,
-
-  // Make calling deprecated APIs throw helpful error messages
-  // errorOnDeprecated: false,
-
-  // The default configuration for fake timers
-  // fakeTimers: {
-  //   "enableGlobally": false
-  // },
-
-  // Force coverage collection from ignored files using an array of glob patterns
-  // forceCoverageMatch: [],
-
-  // A path to a module which exports an async function that is triggered once before all test suites
-  // globalSetup: undefined,
-
-  // A path to a module which exports an async function that is triggered once after all test suites
-  // globalTeardown: undefined,
-
-  // A set of global variables that need to be available in all test environments
-  // globals: {},
-
-  // The maximum amount of workers used to run your tests. Can be specified as % or a number. E.g. maxWorkers: 10% will use 10% of your CPU amount + 1 as the maximum worker number. maxWorkers: 2 will use a maximum of 2 workers.
-  // maxWorkers: "50%",
-
-  // An array of directory names to be searched recursively up from the requiring module's location
-  // moduleDirectories: [
-  //   "node_modules"
-  // ],
-
-  // An array of file extensions your modules use
-  // moduleFileExtensions: [
-  //   "js",
-  //   "mjs",
-  //   "cjs",
-  //   "jsx",
-  //   "ts",
-  //   "tsx",
-  //   "json",
-  //   "node"
-  // ],
-
-  // A map from regular expressions to module names or to arrays of module names that allow to stub out resources with a single module
-  // moduleNameMapper: {},
-
-  // An array of regexp pattern strings, matched against all module paths before considered 'visible' to the module loader
-  // modulePathIgnorePatterns: [],
-
-  // Activates notifications for test results
-  // notify: false,
-
-  // An enum that specifies notification mode. Requires { notify: true }
-  // notifyMode: "failure-change",
-
-  // A preset that is used as a base for Jest's configuration
-  // preset: undefined,
-
-  // Run tests from one or more projects
-  // projects: undefined,
-
-  // Use this configuration option to add custom reporters to Jest
-  // reporters: undefined,
-
-  // Automatically reset mock state before every test
-  // resetMocks: false,
-
-  // Reset the module registry before running each individual test
-  // resetModules: false,
-
-  // A path to a custom resolver
-  // resolver: undefined,
-
-  // Automatically restore mock state and implementation before every test
-  // restoreMocks: false,
-
-  // The root directory that Jest should scan for tests and modules within
-  // rootDir: undefined,
-
-  // A list of paths to directories that Jest should use to search for files in
-  // roots: [
-  //   "<rootDir>"
-  // ],
-
-  // Allows you to use a custom runner instead of Jest's default test runner
-  // runner: "jest-runner",
-
-  // The paths to modules that run some code to configure or set up the testing environment before each test
-  setupFiles: [
-    "<rootDir>/test-setup.js"
-  ],
-
-  // A list of paths to modules that run some code to configure or set up the testing framework before each test
-  // setupFilesAfterEnv: [],
-
-  // The number of seconds after which a test is considered as slow and reported as such in the results.
-  // slowTestThreshold: 5,
-
-  // A list of paths to snapshot serializer modules Jest should use for snapshot testing
-  // snapshotSerializers: [],
-
-  // The test environment that will be used for testing
-  testEnvironment: "jsdom",
-
-  // Options that will be passed to the testEnvironment
-  // testEnvironmentOptions: {},
-
-  // Adds a location field to test results
-  // testLocationInResults: false,
-
-  // The glob patterns Jest uses to detect test files
-  // testMatch: [
-  //   "**/__tests__/**/*.[jt]s?(x)",
-  //   "**/?(*.)+(spec|test).[tj]s?(x)"
-  // ],
-
-  // An array of regexp pattern strings that are matched against all test paths, matched tests are skipped
-  // testPathIgnorePatterns: [
-  //   "/node_modules/"
-  // ],
-
-  // The regexp pattern or array of patterns that Jest uses to detect test files
-  // testRegex: [],
-
-  // This option allows the use of a custom results processor
-  // testResultsProcessor: undefined,
-
-  // This option allows use of a custom test runner
-  // testRunner: "jest-circus/runner",
-
-  // A map from regular expressions to paths to transformers
-  // transform: undefined,
-
-  // An array of regexp pattern strings that are matched against all source file paths, matched files will skip transformation
-  // transformIgnorePatterns: [
-  //   "/node_modules/",
-  //   "\\.pnp\\.[^\\/]+$"
-  // ],
-
-  // An array of regexp pattern strings that are matched against all modules before the module loader will automatically return a mock for them
-  // unmockedModulePathPatterns: undefined,
-
-  // Indicates whether each individual test should be reported during the run
-  // verbose: undefined,
-
-  // An array of regexp patterns that are matched against all source file paths before re-running tests in watch mode
-  // watchPathIgnorePatterns: [],
-
-  // Whether to use watchman for file crawling
-  // watchman: true,
-};