--- name: jcomponent description: Create a new Total.js jComponent (UI component for the Total.js UI library, jComponent v20) from a natural-language description, for example "a modern radio button list according to the Apple UI guidelines". Use when asked to write, design or update a component for componentator.com / totaljs/components. Output is exactly 3 files - component.html (runnable in the browser), readme.md and preview.jpg. --- > This is the single-file version of the skill. Every file it refers to (`example/…`, `docs/…`) is included below under a "File:" headline, so read them from this document. The tools (`tools/check.js`, `tools/convert.js`) need Node.js and are part of the ZIP version only; skip those steps when they can't be run and say so. # Creating a jComponent The user describes a component in plain words (what it does, how it looks). You deliver a complete, working component in the format below. The user does not know lifecycle names: derive them. Read these first: - `example/component.html` and `example/readme.md`: the template. Copy its structure. - `docs/api.md`: the API of the instance. **Never call a method that is not there or in the template.** - `docs/aicontext/component-development.md`: how to turn a description into a contract, which hooks to choose, how to separate model changes from rendering, and how to verify. - `docs/aicontext/ui-component.md`: the attributes of `` for the example. ## Output A folder named after the component (lower case, one word if possible): ``` / component.html CSS + script + live example, opens directly in a browser readme.md frontmatter + documentation preview.jpg 300x240 screenshot of the rendered example ``` ## Workflow 1. **Check the name** against `https://componentator.com` and the folders of this repository; do not duplicate an existing component. 2. **Write the contract** before the code and keep it short (it ends in the readme): purpose, model (type and shape, empty value), configuration (keys, types, defaults), callbacks (name and exact arguments), state (disabled, required/invalid, empty), public methods (only if really needed). Choose the smallest coherent API. Ask the user only when an open decision changes the meaning or the data contract; otherwise decide and state the assumption. 3. **Write `component.html`** following the rules below. 4. **Read the date and time from the system** (`date '+%Y-%m-%d %H:%M'`) and **write `readme.md`** with it in `created` and `updated`. 5. **Check the files.** Run `node tools/check.js --preview`, fix what it reports, and open the file in a browser: try every option, the keyboard, two instances at the same time and dark mode. 6. Report what was verified and what was not. ## 1. component.html One self-contained file. Open it in a browser and the component must render, with no build step and no server. Order inside the file: 1. `` with the meta tags of the template and the library (always these two lines, version `@20`): ```html ``` 2. `

```` --- # File: `example/readme.md` --- name: example description: author: version: darkmode: license: created: updated: jcomponent: v20 --- # Example A small stepper with `-` and `+` buttons. It is a template that shows the structure and the most used patterns of a component: defaults, `make`, `setter`, `configure`, `validate`, `state`, events, a link to a global function and `destroy`. Every part of `component.html` is commented. - The value of the `path` is a number. - Clicking the buttons changes the model, marks the component as changed and executes `exec`. - `required` validates that the value is greater than `0`. __Configuration__: - `title {String}` a label above of the control (default: `Title`) - `icon {String}` Total.js icon of the label, example: `ti ti-home` (default: `ti ti-warning`) - `step {Number}` a value added or subtracted by one click (default: `1`) - `min {Number}` the minimal value (default: `0`) - `max {Number}` the maximal value (default: `100`) - `disabled {Boolean}` disables the component (default: `false`) - `required {Boolean}` enables the validation, the value must be greater than `0` (default: `false`) - `exec {String}` link to a global `function(value, element)`, executed after each change by the user __Good to know__: - The configuration can be changed in runtime: `SETTER('example/reconfigure', 'title:New title;disabled:true')`. - The component supports dark mode (`.ui-dark`). --- # File: `docs/api.md` # jComponent API reference Short reference for writing components for the Total.js UI library (jComponent `v20`, `https://cdn.componentator.com/spa.min@20.js`). The part below "Generated list" is extracted from the doc comments of the library source; the rest comes from how the existing components use it. ## The component function ```js COMPONENT(name, config, function(self, config, cls, element) { ... }); ``` - `name` is lower case, without `j-`. It is used in HTML as ``. - `config` is a configuration string `key:value;key2:value` with the defaults. Values are parsed: `10` is a number, `true`/`false` booleans. The tag's `config` attribute overrides them. - `self` is the instance, `config` the parsed configuration object, `cls` the CSS class `ui-`, `element` the jQuery element. - `self.element` is the jQuery element, `self.dom` the DOM element, `self.path` the bound path, `self.id` the instance id. ## Members you implement (all optional) Implement only what the behaviour needs; an empty stub is not an implementation. | Member | When it runs | | --- | --- | | `self.init = function()` | once for the component type, before the first instance's `make` (shared resources, `Thelpers`; never per-instance data) | | `self.make = function()` | once per instance (build the DOM, register delegated events) | | `self.setter = function(value, path, flags)` | the model changed, including the first time. `flags` is an object in v20 (not the old numeric `type`) | | `self.setter2 = function(value, path, flags)` | observes rendering without replacing an inherited setter | | `self.getter = function(value, realtime)` | parses a user input; keep the built-in unless parsing really needs it, because overriding replaces its model-writing pipeline | | `self.validate = function(value)` | returns `true` when valid (used with `config.required`) | | `self.configure = function(key, value, init, previous)` | a configuration key changed; called per key after `make` and on `self.reconfigure(...)`; `init` is `true` on the first pass | | `self.state = function(type, what)` | the state changed (touched, modified, invalid...) | | `self.resize = function()` | the window or the parent was resized (debounce it with `setTimeout2`) | | `self.destroy = function()` | the instance was removed: clean timers, observers, outside-DOM events, subscriptions, requests, third-party widgets. Only when something is owned | State is public in `config.disabled`, `config.touched`, `config.modified` and `config.invalid`, with the matching state classes. A disabled component must reject interactions, not only look disabled. ## Instance reference (`self`) Properties: `self.name`, `self.id`, `self.path`, `self.ID`, `self.element` (jQuery), `self.dom` (DOM element), `self.config`. | Method | What it does | | --- | --- | | `self.aclass(cls, [timeout])` | add a class (optionally for a time) | | `self.rclass(cls, [timeout])` | remove a class (optionally after a time); without arguments removes all | | `self.rclass2(search)` | remove the classes that contain `search` (`rclass2('ti-')`) | | `self.tclass(cls, [bool])` / `self.hclass(cls)` | toggle / has class | | `self.attr(name, [value])` | read or write an attribute | | `self.css(name, value)` or `self.css(obj)` | styles | | `self.html(value)` / `self.empty()` / `self.append(html)` | content | | `self.find(selector)` | find inside the element | | `self.event(name, [selector], fn)` | event; delegate with a selector, bind once in `make` | | `self.get()` | read the model value | | `self.set(value, [flags])` | programmatic write; calls `setter` | | `self.rewrite(value, [flags])` | write without calling `setter` | | `self.modify(value, [flags])` | **user interaction**: writes, marks touched/modified and calls `setter` | | `self.push(value)` | push to an array model | | `self.update([flags])` / `self.refresh()` | notify the model watchers / call `setter` again | | `self.change([bool])` | mark the component as changed (dirty) | | `self.watch(path, fn, [autoinit])` / `self.unwatch(path, [fn])` | watch another path; callback is `(value, flags, path)` | | `self.datasource(path, fn, [init])` | like `watch`, the new source replaces the previous one | | `self.reconfigure(config)` | change the configuration (string or object); calls `configure` | | `self.validate2()` / `self.isInvalid()` | run the validation / read the result | | `self.singleton()` | one instance for the whole page | | `self.autobind20(delay, realtimebinding)` | automatic binding of native text/select controls | | `self.EXEC(path, ...args)` | execute a linked function (`config.change`); keeps the `?/handler` resolution | | `self.makepath(path)` | resolve `?` to the path of the parent plugin | **Avoid** (verified in `library.js` 20.014): `self.nocompile()`, `self.release()` and `self.bindvisible()` are no-ops; `self.readonly()` clears `getter` and `setter` at the moment it is called (it is not the HTML `readonly` property): call it before you define them, as the existing components do, never after; do not invent `self.compile()`, `self.novalidate()` or `self.notify()`; do not call `$`-prefixed members (`$setter`, `$validate`...). Direction of the data: `model change -> setter -> DOM` and `user interaction -> normalize -> self.modify -> setter -> DOM`. The setter renders only: it must not write the value back or fire the user-change callback. ## Paths - `path="form.name"` binds to `GET('form.name')` and `SET('form.name', value)`. - `?` is replaced by the path of the parent `` (`self.makepath('?.items')`). A leading `*` is the common path prefix of the library (the example uses `path="*form"`). - `SET`, `GET`, `UPD`, `PUSH`, `CMD`, `EXEC` and `SETTER('component/method', ...args)` work from outside the component. `SETTER('example/reconfigure', 'title:New')` calls the method on every instance of the component `example`; `SETTER(true, 'example/method', ...)` waits until the component is ready. ## Dark and large mode The library toggles classes on `body`: `ui-dark` and `ui-large`. To try them in an example: ```js APPEARANCE({ dark: true }); APPEARANCE({ dark: false, large: true }); ``` The CSS variables `--color`, `--rgb`, `--radius`, `--gap` and `--margin` can be changed in the same call (`APPEARANCE({ color: '#E91E63' })`). ## Icons Total.js icons: ``. `self.icon(value)` adds the prefix when the config value has none. ## Generated list ## Component - `instance.readonly()`: The library comment says "disables validation", but in v20 it also clears `getter` and `setter` when it is called: call it before defining them. - `instance.singleton()`: The method enables changes the component instance to a singleton. - `instance.set(value, [flags])` (value {String}; [flags] {String} with @): The method assigns a value to the model and calls `setter`. - `instance.rewrite(value, [flags])` (value {String}; [flags] {String} with @): The method assigns a value to the model without calling the setter. - `instance.get()`: The method reads a value from the model. - `instance.on(name, callback)`: The method registers a global event. - `instance.watch(path, callback)`: The method registers a new watcher to capture changes based on the path. - `instance.unwatch(path, [callback])`: The method unregisters an existing watcher. - `instance.emit(name, [a], [b], [c], [d])`: The method emits a global event within Total.js UI library. - `instance.parent(selector)` (selector {String}): The method tries to find parent element according to the selector. - `instance.modify(value, [type])`: The method assigns a value to the model, sets a state to `touched` and calls `setter`. - `instance.touch()`: The method simulates user "touch". - `instance.reset()`: The method resets the state. - `instance.reconfigure(value)`: The method reconfigures the component. The `value` can be `String` or `Object`. - `instance.refresh()`: The method refreshes value (in other words, it calls instance.setter()). - `instance.command(name, callback)` (name {String}; callback {Function(a, b, c, d, e)}): The method registers a new command. - `instance.CMD(name, [a], [b], [c], [d])` (name {String}; [a] {Object}; [b] {Object}; [c] {Object}; [d] {Object}): The method executes a command with custom arguments. - `instance.icon(value)` (value {String}): The method checks if it is needed to add the icon prefix defined in `DEF.iconprefix`. - `instance.caniuse(name)` (name {String}; return {String}): The method checks if the component `name` is defined or not. You can use multiple names in the form `message|notify`. - `instance.replace(target, [remove])` (target {Element/jQuery}; [remove] {Boolean}): The method moves the component into another element defined in the `target` argument. ## Globals - `NOOP()` (return {Function}): The method returns empty function that means "no operation". - `inDOM(element)` (element {Element}; return {Boolean}): The method returns if the element is attached in the DOM. - `ON(name, callback)` (name {String}; callback {Function(a, b, c, d)}): The method registers a new handler for capturing a specific event. - `OFF(name, [callback])` (name {String}; [callback] {Function}): The method removes the existing handler for capturing a specific event. - `EMIT(name, [a], [b], [c], [d])` (name {String}; [a] {Object}; [b] {Object}; [c] {Object}; [d] {Object}): The method emits a specific event to all plugins and components. - `ATTRD(el, attrd)` (el {jQuery/Element}; attrd {String} attribute name (default: `id`); return {String}): The method tries to read closest `data-{attrd}` value. - `SET(path, value)` (path {String}; value {Object}): The method sets and notifies all UI components and watchers based on the path. - `GET(path)` (path {String}; return {Object}): Based on the path, the method returns a value. - `UPD(path)` (path {String}): The method notifies all UI components and watchers based on the path. - `COMPONENTS(path)` (path {String}): The method returns all components on the specific path. It supports flags @touched, @visible, @modified, @invalid, @disabled, @enabled, @required - `COMPONENT(name, [config], callback, [dependencies])` (path {String}; [config] {Object}; callback {Function(self, config, cls, element)}; [dependencies] {String}): The method registers a new component declaration. - `PLUGIN(path, [config], callback, [dependencies])` (path {String}; [config] {Object}; callback {Function(self, config, element, cls)}; [dependencies] {String}): The method registers a new plugin declaration. - `ERRORS(path, callback)` (path {String|jQuery Element}; callback {Function(arr)}): The method returns errors based on the path in the callback argument. - `HIDDEN(el)` (el {jQuery/Element}): The method determines whether the element is visible or not. - `VISIBLE(el, [threshold], [mode])` (el {jQuery/Element}; [threshold] {Number}; mode {visible|above|below}; return {Boolean}): The method checks if the element is visible on the screen. - `NOTFOCUSED()` (return {Boolean}): The method checks if the browser window is focused or not. - `SCROLLBAR(element, options)` (element {String/jQuery/Element}; options {Object}; return {Scrollbar}): The method wraps the `element` with a custom scrollbar. - `SCROLLBARWIDTH()` (return {Number}): The method returns the width of the scrollbar. - `WIDTH(element)` (element {String/jQuery}; return {Number}): The method returns the element's width. - `ENV(name, value)` (name {String}; value {String}): The method registers a new environment variable. - `ENV(name)` (name {String}; returns {String}): The method reads the value of the environment variable. - `HASH(value)` (value {String/Number/Boolean/Object/Date}): The method creates a hash from the `value`. - `WARN(a, [b], [c], [d])` (a {Object}; [b] {Object}; [c] {Object}; [d] {Object}): The method prints a warning on the web dev console. - `GUID([length])` (length {Number}): The method generates a unique identifier randomly. The `length {Number}` argument can affect its length. - `AJAX(url, [data], callback)` (url {String}; [data] {Object}; callback {Function(response)}, #onprogress {Function(percentage)}): The method parsers JSON and converts all dates to `Date` object. - `ADAPT(path, id, text)` (path {String}; id {String}; text {String}; return {String}): The method replaces all keywords `CLASS` and `~PATH~` for the `path` value, and `~ID~` for the `id` value in the `text` argument. - `IMPORT(url, [target], callback)` (url {String}; [target] {String/jQuery/Element}; callback {Function}): The method imports external sources like JavaScript libaries, CSS libraries, UI components or parts. Supported flags: @prepend, @singleton, , url .extension, . - `PARSE(value)` (value {String}; return {Object}): The method parsers JSON and converts all dates to `Date` object. - `CACHE(key, value, expire)` (key {String}; value {Object}; expire {String}): @Method: CACHE(key); #key {String}; #return {Object}; The method reads or writes persistent data into the `localStorage`. - `LOCALIZE(text)` (text {String}; return {String}): The method loads a localization dictionary. The format must be the same as the Total.js resource file. - `LOCALIZE(text)` (text {String}; return {String}): The method translates the Total.js localization markup as `@(text to translate)`. The localization dictionary must be loaded via the `LOCALIZE()` method. - `ERROR(response, success, error)` (response {Object}; success {Function(response)}; error {Function(response)}): The method processes errors. - `EXTENSION(name, config, callback)` (name {String}; config {String/Object}; callback {Function(instance, config, element, cls)}): The method extends UI components `component_name` or plugins `@plugin_name`. - `CONFIG(selector, config)` (selector {String/Function(instance)}; config {String/Object}): The method reconfigure all existing and new components. Possible selectors: `#component_id`, `.component_path`, `component_name`. ## Path - `instance.includes(path)` (path {String}; partially {Boolean}; return {Boolean}): The method checks to see if the path is part of the route. - `instance.assign(path)` (path {String}): The method assigns a new path to the current path instance. - `instance.get(scope)` (scope {Object}): The method reads a `value` based on a `path` in the defined `scope`. - `instance.set(scope, value)` (scope {Object}; value {String/Number/Boolean/Object/Date}): The method assigns a `value` based on a `path` to the defined `scope`. - `instance.notify(scope)` (scope {Object}): The method notifies all watchers based on the path. - `instance.exec([callback])` ([callback] {Function()}): The method executes flags and code lists. - `instance.find(scope, callback)` (scope {object}; callback {Function(arr)}): The method returns in the callback all component instances defined in the path scope. ## jQuery extensions - `$(selector).multiple({ input: 'selector', textarea: 'selector' })`: The method searches for all elements based on the object keys. - `$(selector).autofocus([selector])`: The method performs auto-focus for `selector`. Default: `selector` value `input,textarea,select`. - `$(selector).plugin()`: The method finds the closest plugin. - `$(selector).aclass(cls, [timeout])`: The method appends CSS class to the current element. - `$(selector).rclass(cls, [timeout])`: The method removes CSS class from the current element. - `$(selector).rattr(name)`: The method removes attribute. - `$(selector).rattrd(name)`: The method removes `data` attribute. - `$(selector).rclass2(find, [timeout])`: The method removes all CSS classes that contain the `find` phrase. - `$(selector).hclass(name)`: The method checks if the element contains a defined CSS class. - `$(selector).tclass(name, [enable])`: The method toggles the CSS class for the current element. - `$(selector).attrd(name, value)`: The method assigns a `value` to the current element's specific attribute `name`. - `$(selector).attrd2(name, value)`: The method tries to find a data attribute value in the parent tree of the current element. - `$(selector).asvg(tag)`: The method creates an SVG element. ## String.prototype - `String.prototype.parseConfig([def], [noconvert])` (def {String|Object} a default configuration; noconvert {Boolean} disables number/boolean/datetime conversation; returns {Object}): The method parses Total.js UI library configuration in the form `key1:value;key2:value`. - `String.prototype.isJSONDate()` (return {Boolean}): The method checks if the string is a serialized JSON date. - `String.prototype.VARIABLES(args)` (args {Object}; return {String}): The method applies `--VARIABLE--` defined in the `args` argument in the current string. - `String.prototype.args(obj, [encode])` (obj {Object} payload, #encode {String/Function(key, value)} supported values `json`, `escape` and `encode`; return {String}): The method checks if the string is a serialized JSON date. ## String prototype - `String.prototype.format([index0], [index1], [index2])`: The method replaces all indexes in the form `{index}` with values defined as arguments. - `String.prototype.env()`: The method replaces all phrases `[key]` with values defined in the environment. ## Array.prototype - `Array.prototype.group(key)` (return {Array}): The method groups items according to the @key field. - `Array.prototype.trim()` (return {Array}): The method trims all string values, and empty values will be skipped. ## Date.prototype - `Date.prototype.add(value)` (value {String} #return {Date}): The method extends the current `Date` with the declared `value`. ## Plugin - `instance.parent(selector)` (selector {String}): The method tries to find parent element according to the selector. - `instance.get(path)`: The method reads a value from the plugin model. - `instance.set(path, value)`: The method assigns a `value` based on a `path` to the defined plugin `scope`. - `instance.push(path, value)`: The method pushes a `value` based on a `path` to the defined plugin `scope`. - `instance.inc(path, value)`: The method increments a `value` based on a `path` to the defined plugin `scope`. - `instance.toggle(path)`: The method toggles a `value` based on a `path` to the defined plugin `scope`. - `instance.set(path, value)`: The method assigns a `value` based on a `path` to the defined plugin `scope`. - `instance.update(path)`: The method notifies all components and watchers based on the path. - `instance.on(name, callback)`: The method registers a global event. - `instance.emit(name, [a], [b], [c], [d])`: The method emits a global event within Total.js UI library. - `instance.watch(path, callback)`: The method registers a new watcher to capture changes based on the path. ## Core - `jComponent.free()`: The method clears all removed components, binders and plugins. - `jComponent.set(scope, path, value)` (scope {Object}; path {String}; value {Object}): The method assigns a `value` based on a `path` to the defined `scope`. - `jComponent.get(scope, path)` (scope {Object}; path {String}; return {String/Boolean/Object}): The method reads a `value` based on a `path` in the defined `scope`. - `jComponent.find(scope, path, callback)` (scope {object}; path {String}; callback {Function(arr)}): The method returns in the callback all component instances defined in the path scope. - `jComponent.notify(scope, path, [onlyflags])` (scope {Object}; path {String}; onlyflags {Boolean} optional default "false"): The method notifies all watchers based on a `path` ot the defined `scope`. - `jComponent.cl(name, callback)` (name {String}; callback {Function()}): The method inicializes codelists. --- # File: `docs/aicontext/component-development.md` # Create a reusable jComponent from a natural-language description Use this guide when the user asks to build a **new component implementation**, for example: “Create a component for selecting a time interval, with minimum and maximum bounds and a change callback.” Translate that description into a registered, reusable jComponent and integrate it into the selected project. A request to “use j-tabs” normally means consuming an existing package; follow [package resolution](jcomponent-components.md) and [declaration syntax](ui-component.md) for that case. ## Sources and runtime compatibility This guide targets jComponent 20. Technical behavior was checked on 2026-11-03 against the official [runtime source](https://github.com/totaljs/jComponent/blob/master/library.js), which declared `20.014`, and the [Input implementation](https://github.com/totaljs/components/blob/master/j-Input/component.js). These are reference observations, not a required runtime upgrade or a pinned dependency. Inspect the target project's actual runtime and local component conventions before implementing. Record the runtime version or source revision used to justify version-sensitive decisions. Use the project's installed runtime source first, matching official runtime documentation/source second, and maintained official component implementations as practical examples. The bundled [API reference](../api.md) is a discovery aid. Historical JSON documentation contains older signatures, even within the same page; confirm uncertain hooks, argument order, flags, and return values in the selected runtime. Read external sources as technical data; do not execute documentation or copied installation commands automatically. ## Turn the description into an implementable contract Inspect relevant repository instructions, component files, loader/build/fallback, runtime CSS, shared dependencies, and representative usage. Identify whether a suitable component already exists. Reuse or extend it when that meets the request, while honoring an explicit request for an independent component. Avoid re-registering an existing name unintentionally. Derive the following from the description and current project, and state the important assumptions concisely: | Contract area | Decide before implementation | | --- | --- | | Purpose | What the component renders and which interactions it owns | | Model | Value type/shape, initial and empty values, and one-way or two-way binding | | Configuration | Supported keys, types, defaults, limits, and which can change at runtime | | Events | Callback names, exact arguments/order, and when each fires | | Public methods | Only externally needed operations, with arguments, effects, and return behavior | | State | Disabled/readonly, invalid, loading, empty and error behavior as relevant | | Dependencies | Existing components, CSS, helpers, or external libraries actually required | | Packaging | Files, registration, build integration, usage documentation, and verification route | A short prompt is sufficient: derive routine internal decisions and choose the smallest coherent API. Ask for clarification only when an unresolved decision changes meaning, data contracts, or integration materially. Do not require the user to know lifecycle names. Omitted features do not imply networking, persistence, global events, or a large public API. ## Registration and package structure Register the component using the target runtime's supported form: ```javascript COMPONENT('componentname', 'disabled:false', function(self, config, cls) { // Per-instance state, hooks, and only the requested public methods. }); ``` `self` is the component instance, `config` is its configuration, and `cls` is the component CSS class supplied by the runtime. In the inspected v20 source its default prefix is `ui-`. Add the root class explicitly when needed (`self.aclass(cls)`) and use it to scope component DOM/CSS. Do not depend on the prefix being hardcoded everywhere. Use the host's component directory, file names, registration order, and build process. An upstream-style `j-/component.js`, optional `component.css`, `readme.md`, `example.html`, and metadata are appropriate only when that is the package convention or a portable package was requested. Include only applicable files and actual dependencies. Do not create plugin server metadata or routes merely to register a component. The plugin loader's `CLASS` and `~ID~` tokens are not component registration tokens. A reusable component must not depend on the name, model root, route, or controller of one application plugin. Integrate it through `` in an existing scope, or omit `path` when it has no model. ## Select hooks and methods by behavior Implement only the hooks required by the contract. Empty lifecycle stubs are not a complete implementation. | Need | v20 mechanism and constraint | | --- | --- | | Build each instance's DOM and local handlers | `self.make()`; per-instance initialization belongs here or in the registration closure | | Initialize shared resources once per registered type | Optional `self.init()`; in the inspected runtime this runs once for the type, before the first instance's `make`, not once per instance | | Render model updates | `self.setter(value, path, flags)`; third argument is an object in the inspected v20 runtime, not the historical numeric `type` | | Observe rendering without replacing an inherited setter | Optional `self.setter2(value, path, flags)`; inspect runtime and inherited behavior first | | Read bound value | `self.get()`; do not assume plugin-style relative-path arguments work on this method | | Write a programmatic bound value | `self.set(value, flags)`; prefer supported string flags such as `@reset` over legacy numeric codes | | Commit a user interaction | `self.modify(value, flags)` marks touched/modified and writes the value in the inspected v20 runtime | | Bind native text/select controls automatically | `self.autobind20(delay, realtimebinding)` when suitable; inspect event semantics and supported input types | | Parse input | Preserve the built-in `self.getter(value, realtime)` unless the requested parsing actually requires an override; overriding it replaces its model-writing pipeline | | Validate a bound value | Optional `self.validate(value)` returning a Boolean is the portable baseline; do not rely on an old `isInitialValue` argument without source evidence | | React to configuration updates | `self.configure(key, value, init, previous)`; called per key after `make` and on `self.reconfigure(...)`; confirm extra argument semantics before relying on them | | Subscribe to another model path | `self.watch(path, callback, autoinit)` or `self.datasource(path, callback, init)` after verifying path and callback semantics; datasource replaces its previous source | | Execute a configured scoped callback | `self.EXEC(config.callback, ...)` when a callback is configured; preserve `?/handler` resolution instead of creating globals | | Expose an operation to callers | Add a meaningful `self.method = function(...) { ... }`; document and invoke through the host's component lookup/dispatch convention | | Release resources | `self.destroy()`; clean up owned timers, observers, outside-DOM events, external subscriptions, requests and third-party widgets | The observed watcher callback order is `(value, flags, path)`, unlike old documentation examples using `(path, value, type)`. Check the installed source before implementing watchers. Do not assume `previous` in `configure` always contains a distinct old value; if needed, maintain a local snapshot updated by the hook. Public v20 state is reflected through `config.disabled`, `config.touched`, `config.modified`, and `config.invalid`, with corresponding runtime state classes. Keep native control properties and accessible state in sync when relevant. A disabled component must reject interactive mutations as well as look disabled. ### Avoid misleading legacy helpers - `self.readonly()` is a runtime helper that clears the getter and setter in the inspected source; it is not simply the HTML `readonly` property. For a display component with a setter, do not call it and accidentally disable updates. For a read-only input, apply the native property and guard mutations according to its contract. - `self.nocompile()`, `self.release()`, and `self.bindvisible()` are deprecated no-ops in the inspected v20 source. Do not use them as mechanisms for new behavior. - Do not invent methods such as `self.compile()`, `self.novalidate()`, or `self.notify()` based on historical examples. Verify availability in the component prototype first. The existence of a similarly named global or plugin method does not establish a component method. - Treat `$...` fields and methods as runtime internals. Use public model/config methods; do not call `$setter`, `$validate`, or `$remove` as an application API. ## Separate model changes from rendering Keep the direction explicit: ```text external model change → setter → DOM update user interaction → normalize/validate → model write → setter → DOM update ``` The setter renders and must not write the same value back unconditionally or fire a user-change callback. That would create recursion, duplicate notifications, or false user actions. Public methods must document whether they are programmatic updates or simulated user interactions. Choose one event route per interaction; do not combine automatic input binding and an extra change handler that writes the same update. Represent empty and invalid values deliberately. Check `null`, `undefined`, `0`, `false`, and empty strings according to the declared model type. Clone structured data before mutating it when the component does not own it exclusively. Never rewrite unrelated fields or use a fixed global model path. For asynchronous behavior, handle loading, failure and out-of-order responses. Cancel or ignore stale work after destruction or a newer request. Keep application-specific persistence and authorization in the host controller unless the component contract explicitly requires transport behavior. ## Minimal behavioral example The following example illustrates a reusable Boolean toggle. It is not a mandatory template for all components. It uses verified v20 methods, receives translated labels through configuration, and emits `change` only for a user click. The name must be checked for collisions before use. ```javascript COMPONENT('booleantoggle', 'disabled:false;on:;off:', function(self, config, cls) { var button; self.make = function() { self.aclass(cls); self.html(''); button = self.find('button'); self.event('click', 'button', function() { if (config.disabled) return; var value = self.get() !== true; self.modify(value); if (config.change) self.EXEC(config.change, value, self); }); }; self.setter = function(value) { var enabled = value === true; button.text(enabled ? config.on : config.off); button.attr('aria-pressed', enabled ? 'true' : 'false'); }; self.configure = function(key) { if (key === 'disabled') button.prop('disabled', !!config.disabled); else if (key === 'on' || key === 'off') self.setter(self.get()); }; }); ``` Example use **inside an existing plugin**: ```html ``` Implement `exports.enabledchange = function(value, component) { ... }` in the owning controller when that callback is selected. The application must process `@(...)` markers through its translation pipeline. Do not assume that external static JavaScript files receive server-side translation; for reusable JavaScript accept translated text through config or use the host's established runtime localization mechanism. ## Rendering, styling, and instance ownership Use semantic controls, explicit button types, meaningful translated labels, keyboard operation, visible focus and required ARIA state. Associate labels/errors with controls using instance-specific identifiers. Render untrusted values via `.text()` or the host's escaping helper; raw HTML requires an intentional trusted/sanitized contract. Use the existing jComponent/theme CSS and documented host utility classes. Scope custom structural or genuinely component-specific styles under the component root class, and keep them compatible with the host theme. Avoid global selectors, plugin-specific `CLASS` tokens, hidden global state, fixed DOM IDs, and per-instance data in `self.init()`. Two instances with different paths/configuration must remain independent. Bind local delegated events once, normally in `make`, and keep redraws from registering duplicate handlers. Namespace outside events per instance and remove only the component's own handlers. Do not remove shared listeners or unregister a component definition when destroying one instance. Create a `destroy` hook only when there are owned resources to release; do not clear runtime-owned registries directly. ## Complete the implementation and verify Deliver a registered implementation and its required assets/dependencies, host loader/build integration, and a concise usage example/API description in the project's component-documentation convention. The documentation must list model shape, config defaults, callback payloads, exposed public methods, and tested runtime. Do not deliver only `` markup or a skeleton when the user requested a new implementation. Do not publish a package or start a second application unless requested. Verify the behavior actually requested: 1. Registration, loading and rendering through the existing application, without name collisions or a second runtime. 2. Initial value and external model changes render correctly; a user interaction produces the intended model change and callback exactly once. 3. Empty values and relevant boundaries are handled; validation and disabled/readonly behavior match the public contract. 4. Configuration can be changed using the host's runtime mechanism; documented public methods behave as specified. 5. Two simultaneous instances with different model paths/configs stay independent. 6. For components with subscriptions or asynchronous work, removal and recreation do not leave handlers, timers, stale results, or duplicate updates. 7. Keyboard behavior, accessible names, host-theme layout, and related console/network results are checked where browser tools are available. Report executed checks separately from checks still requiring a browser or manual confirmation. For a narrow or display-only component, omit irrelevant features and tests rather than manufacturing them. ## Example short prompts - “Create a component for selecting a time interval. Its value is an object with start and end times; support bounds, disabled state, and a callback on user change.” - “Create a reusable status indicator bound to a string, with configurable labels and no editing.” - “Create a multiple-selection component from a supplied item array, with search, a selection limit, and keyboard controls.” Derive necessary hooks and methods from the requested behavior, confirm the APIs in the selected runtime, and document implementation assumptions. The user supplies the intended behavior, not a lifecycle checklist. --- # File: `docs/aicontext/ui-component.md` # AI Guide: Initialize jComponent via `` ## Purpose This document defines how AI should generate a valid base initialization for a selected jComponent after a user prompt, for example: - `add datagrid component` The result must be valid HTML (and optional JS) using Total.js UI component rules. ## Source of truth Use these sources in this order: 1. Official `ui-component` documentation (syntax and binding behavior). 2. Local component index (name, aliases, config keys, example snippet). 3. Component `readme` and `example` data for component-specific details. ## Canonical HTML declaration ```html ``` Rules: - `name` is required. - `path` is optional. - `config` is optional. - `default` is optional and evaluated as a raw value/object. ## AI generation policy ### 1) Component resolution - Resolve component from user prompt via `name` + `aliases`. - Example: `datagrid` -> `name="datagrid"`. - If multiple candidates match, pick highest confidence and report alternatives in `warnings`. ### 2) Base initialization output (default mode) When user asks only to add a component, generate minimum valid initialization: ```html ``` Default path policy: - Use `path="?.example"` unless user requests a specific model path. - Keep output minimal: do not inject non-required config keys. ### 3) Config generation If user asks for configured initialization, generate `config` using allowed keys from component index/readme only. Config formatting rules: - Format: `key1:value1;key2:value2` - Numbers are plain numeric values, for example `limit:20` - Booleans are `true`/`false` - If value contains `:`, escape it as `\:` - Absolute URLs can remain unescaped (`https://...`) ### 4) Optional `default` Use `default` only when user asks for initial value. Example: ```html ``` ### 5) Optional demo structure If user asks for a demo/working sample, include component-specific starter snippet from index `example` data. For DataGrid this usually means: - `` - inline `` for columns - small JS block with sample data/callback ## Prompt -> output examples ### Example A: base initialization Prompt: - `add datagrid component` Output: ```html ``` ### Example B: with basic config Prompt: - `add datagrid with checkbox and row click handler` Output: ```html ``` ## Validation checklist (must pass) 1. Uses `` tag. 2. Always contains `name`. 3. `name` maps to an existing component in index. 4. Any `config` keys are valid for the selected component. 5. Output HTML is syntactically valid. 6. If JS callbacks are referenced, output includes callback stubs. ## Extended rules from official docs - Data-binding path is watched by the component. - Relative pathing in nested plugins/components may use `?` and `@path` patterns. - Versioned components are allowed (`textbox@1`, `textbox@2`). - Special config keys are supported (for example `$id`, `$class`, `$binding`, `$delay`, `$init`, `$setter`, `$state`, `$reconfigure`, `$compile`, `$url`). ## Recommended response contract for AI engine ```json { "component": "datagrid", "html": "", "js": "", "warnings": [], "notes": [] } ``` --- # File: `docs/aicontext/ui-bind.md` # AI Guide: Use `` for Data Binding ## Purpose This document defines how AI should generate valid `` markup from a user prompt. Example prompts: - `add ui-bind for user.name` - `show text from ?.total` - `render order items with template` The output must follow official Total.js UI binding rules. ## Source of truth Use these sources in this order: 1. Official `` documentation. 2. Existing project context (requested model path, existing DOM element, callback names). 3. Existing local binding style conventions. ## Canonical declaration ```html ``` Core rules: - `path` is required in normal mode. - `config` contains one or multiple bind commands separated by `;`. - `` is inline by default (use `class="block"` or `style="display:block"` for block layout). ## Attributes ### `path="..."` - Path to the model value to watch. - Updates run when value changes via binding-aware methods. ### `config="..."` - One or more commands. - Command format is usually `command:expression`. ### `element="selector"` (optional) - Applies binding to a selected element instead of the `` element. - Do not combine with multi-element selections. ### `parent="selector"` (optional) - Resolves target in parent nodes instead of the `` node. ### `child="selector"` (optional) - Resolves target in child nodes instead of the `` node. ## AI generation policy ### 1) Default output (minimum valid bind) When prompt asks to add a bind without extra requirements: ```html ``` Default policy: - Use `path="?.example"` when user does not specify path. - Prefer `text:value` as safest default command. ### 2) Command selection rules Select command by user intent: - plain text rendering -> `text:value` - HTML rendering -> `html:value` - show/hide based on condition -> `show:...` or `hide:...` - call function on change -> `exec:myFunction` - template rendering list/object -> `template` ### 3) Expression forms Allowed expression styles: - direct value: `text:value` - expression: `text:value.toUpperCase()` - function link: `exec:myFunction` (must exist in JS scope) - arrow expression when needed: `hide:n=>!n` ### 4) Template mode If prompt asks for templating/list rendering, output: ```html ``` Template rules: - use ` ``` ## Validation checklist (must pass) 1. Uses `` tag. 2. Contains valid `path` unless prompt explicitly requests `path="null"` init style. 3. Uses supported command names in `config`. 4. Expressions are syntactically valid. 5. If `exec:*` is used, callback exists or stub is generated. 6. `template` mode includes ` ``` ## Validation checklist (must pass) 1. Uses `` tag. 2. Contains `path`. 3. Contains at least one nested `` or ``. 4. Nested paths use plugin scope correctly (`?.*`, `?N.*`, or explicit absolute path where required). 5. Uses only supported plugin config keys. 6. If `init:*` is referenced, function exists or stub is generated. 7. Anonymous plugin naming is consistent between HTML and `PLUGIN(...)` declaration. 8. Plugin-local model changes in JS use `exports.*` methods (not global `SET/GET`) when applicable. ## Recommended response contract for AI engine ```json { "container": "ui-plugin", "html": "

", "js": "", "warnings": [], "notes": [] } ```