asljs-ui-list 0.0.0-stage → 0.1.1

package/LICENSE.md

@@ -0,0 +1,51 @@
+# Permissive No-Derivatives License 1.0
+
+Copyright (c) 2026 Alexandrite Software Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software (the "Software") to:
+
+1. Use the Software for any purpose, including commercial purposes.
+2. Copy and redistribute the Software, including as part of another application,
+   library, or package.
+3. Modify the Software for private or internal use.
+
+Subject to the following conditions:
+
+## 1. No Distribution of Modified Versions
+
+Modified versions of the Software, or substantial portions thereof, must not be
+distributed without prior written permission from the copyright holder.
+
+Routine build transformations, including minification, transpilation, and
+bundling, are permitted for distribution, provided they do not intentionally
+alter the Software's functionality.
+
+## 2. Licence and Copyright Preservation
+
+All distributed copies of the Software must retain this copyright notice and
+licence.
+
+The Software itself, including copies incorporated into other applications,
+libraries, or packages, remains subject to this licence.
+
+The Software must not be sublicensed or redistributed under a different licence.
+
+## 3. Use in Other Software
+
+Applications and libraries that merely use, import, link to, or bundle the
+Software are not considered modified versions of the Software and may be
+distributed under any licence.
+
+Such use, incorporation, or bundling does not grant permission to relicense the
+Software or distribute modified versions of it.
+
+### 4. No Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# list
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Part of [Alexandrite Software Library][#1] - a set of high-quality, performant
+> JavaScript libraries and tools for everyday use.
+
+## Overview
+
+`asljs-ui-list` provides `asljs-list`, which renders a collection from
+templates. Each row is bound with `asljs-data-binding` to its own context: the
+item, its position, and the shared `context` of row actions.
+
+## Scope
+
+- Items as a plain array or an eventful-like collection the list re-renders from
+  when it changes.
+- Row, empty-state and container templates, local or from the `list` theme
+  section; `createBootstrapListTheme()` supplies a Bootstrap list group.
+- Render callbacks and inline call expressions are outside the model: rows come
+  from templates and handlers are binding paths.
+
+## Installation
+
+```bash
+npm install asljs-ui-list
+```
+
+NPM package: [asljs-ui-list][NPM]
+
+## Usage
+
+Import the package once to register the element:
+
+```ts
+import 'asljs-ui-list';
+
+const list =
+  document.createElement('asljs-list');
+
+list.context = {
+  select(this: { item: { title: string } }) {
+    console.log('selected', this.item.title);
+  }
+};
+
+list.innerHTML = `
+  <template data-slot="item">
+    <a data-bind-text="item.title"
+       data-bind-on-click="context.select"></a>
+  </template>
+`;
+
+list.items =
+  [ { title: 'First' },
+    { title: 'Second' } ];
+
+document.body.appendChild(list);
+```
+
+## Further reading
+
+- [List][DOC] - templates, the row binding context and row actions.
+- [Theming][THM] - templates, themes and how they combine.
+
+Questions and bugs: [asljs/issues][ISS].
+
+## Related packages
+
+- [ui][UI] - the shared theme and the other UI packages.
+- `asljs-data-binding` for the bindings the row templates use.
+- `asljs-eventful` for the collections the list follows.
+
+## License
+
+MIT License. See [LICENSE][LIC] for details.
+
+[#1]: https://github.com/AlexandriteSoftware/asljs
+[DOC]: docs/List.md
+[ISS]: https://github.com/AlexandriteSoftware/asljs/issues
+[LIC]: LICENSE.md
+[NPM]: https://www.npmjs.com/package/asljs-ui-list
+[THM]: ../core/docs/Theming.md
+[UI]: ../core/README.md

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { List, ListModelDefinition, type ListItem, type ListItemsSource, type ListRowContext } from './list.js';
+export { createBootstrapListTheme, type ListThemeDefinition } from './theme.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { List, ListModelDefinition } from './list.js';
+export { createBootstrapListTheme } from './theme.js';

package/dist/list.d.ts

@@ -0,0 +1,26 @@
+import { ComponentModelDefinition, ComponentsTheme } from 'asljs-ui';
+import { LitElement } from 'lit';
+export type ListRowContext = {
+    item: ListItem;
+    index: number;
+    context: unknown;
+    first: boolean;
+    last: boolean;
+    odd: boolean;
+    even: boolean;
+    count: number;
+};
+export type ListItem = Record<string, unknown>;
+export type ListItemsSource = ListItem[];
+export declare const ListModelDefinition: ComponentModelDefinition;
+export declare class List extends LitElement {
+    #private;
+    accessor items: ListItemsSource;
+    accessor context: unknown;
+    accessor theme: ComponentsTheme | null;
+    createRenderRoot(): this;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    render(): ReturnType<LitElement['render']>;
+    updated(changedProperties: Map<PropertyKey, unknown>): void;
+}

package/dist/list.js

@@ -0,0 +1,313 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { bindDataModel } from 'asljs-data-binding';
+import { asEventfulLike } from 'asljs-eventful';
+import { defineComponentModel, findThemeProvider, getDefaultTheme, resolveThemeTemplate, THEME_CHANGED_EVENT_NAME } from 'asljs-ui';
+import { html, LitElement, nothing } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+export const ListModelDefinition = { name: 'ListModelDefinition',
+    title: 'List',
+    properties: [{ name: 'items',
+            title: 'Items',
+            type: 'array',
+            description: 'Rows rendered by the list.' },
+        { name: 'context',
+            title: 'Context',
+            type: 'object',
+            description: 'Shared row binding context.' },
+        { name: 'theme',
+            title: 'Theme',
+            type: 'object',
+            description: 'Per-instance components theme override.' }] };
+defineComponentModel('asljs-list', ListModelDefinition);
+let List = class List extends LitElement {
+    #containerTemplate = null;
+    #emptyTemplate = null;
+    #itemTemplate = null;
+    #itemBindingDisposers = [];
+    #itemsObserverDispose = null;
+    #themeProvider = null;
+    #warnedMissingItemTemplate = false;
+    #warnedInvalidContainer = false;
+    #handleThemeChanged = () => {
+        this.requestUpdate();
+    };
+    #items_accessor_storage = [];
+    get items() { return this.#items_accessor_storage; }
+    set items(value) { this.#items_accessor_storage = value; }
+    #context_accessor_storage = undefined;
+    get context() { return this.#context_accessor_storage; }
+    set context(value) { this.#context_accessor_storage = value; }
+    #theme_accessor_storage = null;
+    get theme() { return this.#theme_accessor_storage; }
+    set theme(value) { this.#theme_accessor_storage = value; }
+    createRenderRoot() {
+        return this;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.#captureTemplates();
+        this.#syncItemsObserver();
+        this.#syncThemeProvider();
+    }
+    disconnectedCallback() {
+        this.#disposeItemsObserver();
+        this.#disposeItemBindings();
+        this.#disposeThemeProvider();
+        super.disconnectedCallback();
+    }
+    render() {
+        const emptyTemplate = this.#resolveTemplate('empty');
+        const itemTemplate = this.#resolveTemplate('item');
+        const containerTemplate = this.#resolveTemplate('container');
+        if (this.items.length === 0) {
+            if (emptyTemplate) {
+                return html `
+          <div data-role="empty-template-host"></div>
+        `;
+            }
+            return nothing;
+        }
+        if (!itemTemplate) {
+            return nothing;
+        }
+        if (containerTemplate) {
+            return html `
+        <div data-role="container-template-host"></div>
+      `;
+        }
+        return html `
+      <div data-role="default-container-host">
+      </div>
+    `;
+    }
+    updated(changedProperties) {
+        if (changedProperties.has('items')) {
+            this.#syncItemsObserver();
+        }
+        if (changedProperties.has('theme')) {
+            this.#syncThemeProvider();
+        }
+        this.#renderTemplateContent();
+    }
+    #captureTemplates() {
+        this.#containerTemplate = null;
+        this.#emptyTemplate = null;
+        this.#itemTemplate = null;
+        this.#warnedMissingItemTemplate = false;
+        this.#warnedInvalidContainer = false;
+        const templateElements = this.querySelectorAll('template[data-slot]');
+        for (const item of templateElements) {
+            const templateElement = item;
+            const slotName = templateElement.getAttribute('data-slot');
+            const clonedTemplate = document.createElement('template');
+            clonedTemplate.content.append(templateElement.content.cloneNode(true));
+            if (slotName === 'empty') {
+                this.#emptyTemplate = clonedTemplate;
+            }
+            if (slotName === 'item') {
+                this.#itemTemplate = clonedTemplate;
+            }
+            if (slotName === 'container') {
+                this.#containerTemplate = clonedTemplate;
+            }
+        }
+    }
+    #renderTemplateContent() {
+        this.#renderEmptyTemplate();
+        this.#renderItemTemplates();
+    }
+    #renderEmptyTemplate() {
+        const emptyTemplate = this.#resolveTemplate('empty');
+        if (!emptyTemplate
+            || this.items.length > 0) {
+            return;
+        }
+        const host = this.querySelector('[data-role="empty-template-host"]');
+        if (!host) {
+            return;
+        }
+        host.replaceChildren(emptyTemplate.content.cloneNode(true));
+    }
+    #renderItemTemplates() {
+        this.#disposeItemBindings();
+        const itemTemplate = this.#resolveTemplate('item');
+        if (!itemTemplate
+            || this.items.length === 0) {
+            if (!itemTemplate
+                && this.items.length > 0) {
+                this.#warnMissingItemTemplate();
+            }
+            return;
+        }
+        const itemsHost = this.#resolveItemsHost();
+        if (!itemsHost) {
+            return;
+        }
+        const rowNodes = [];
+        const count = this.items.length;
+        for (let index = 0; index < this.items.length; index++) {
+            const item = this.items[index];
+            const rowContext = { item,
+                index,
+                context: this.#createRowScopeContext(item, index),
+                first: index === 0,
+                last: index === count - 1,
+                odd: index % 2 === 1,
+                even: index % 2 === 0,
+                count };
+            const fragment = itemTemplate.content.cloneNode(true);
+            this.#bindFragmentModel(fragment, rowContext);
+            rowNodes.push(...[...fragment.childNodes]);
+        }
+        itemsHost.replaceChildren(...rowNodes);
+    }
+    #resolveItemsHost() {
+        const containerTemplate = this.#resolveTemplate('container');
+        if (containerTemplate) {
+            const containerHost = this.querySelector('[data-role="container-template-host"]');
+            if (!containerHost) {
+                return null;
+            }
+            const fragment = containerTemplate.content.cloneNode(true);
+            const templatedItemsHost = fragment.querySelector('[data-role="items"]');
+            containerHost.replaceChildren(fragment);
+            if (!templatedItemsHost) {
+                this.#warnInvalidContainer();
+                return null;
+            }
+            return templatedItemsHost;
+        }
+        const defaultContainerHost = this.querySelector('[data-role="default-container-host"]');
+        return defaultContainerHost;
+    }
+    #resolveTemplate(slotName) {
+        return this.#getLocalTemplate(slotName)
+            ?? this.#getThemeTemplate(slotName);
+    }
+    #getLocalTemplate(slotName) {
+        if (slotName === 'container') {
+            return this.#containerTemplate;
+        }
+        if (slotName === 'empty') {
+            return this.#emptyTemplate;
+        }
+        return this.#itemTemplate;
+    }
+    #getThemeTemplate(slotName) {
+        const activeTheme = this.theme
+            ?? this.#themeProvider?.theme
+            ?? getDefaultTheme();
+        return resolveThemeTemplate(activeTheme.list?.[slotName], this);
+    }
+    #bindFragmentModel(fragment, model) {
+        const dispose = bindDataModel(fragment, model);
+        this.#itemBindingDisposers.push(dispose);
+    }
+    #createRowScopeContext(item, index) {
+        if (this.context === null
+            || this.context === undefined
+            || typeof this.context
+                !== 'object') {
+            return this.context;
+        }
+        const baseContext = this.context;
+        const rowContext = Object.create(baseContext);
+        rowContext.item = item;
+        rowContext.index = index;
+        for (const key of Object.keys(baseContext)) {
+            const value = baseContext[key];
+            if (typeof value
+                === 'function') {
+                rowContext[key] =
+                    value.bind(rowContext);
+            }
+        }
+        return rowContext;
+    }
+    #disposeItemBindings() {
+        for (const dispose of this.#itemBindingDisposers) {
+            dispose();
+        }
+        this.#itemBindingDisposers = [];
+    }
+    #syncItemsObserver() {
+        this.#disposeItemsObserver();
+        const eventSource = toEventfulLike(this.items);
+        if (!eventSource) {
+            return;
+        }
+        const unsubscribers = [];
+        const onCollectionChanged = () => {
+            this.requestUpdate();
+        };
+        // An observable collection reports every change as one `change` event,
+        // carrying the list of what changed; the list re-reads it all anyway.
+        const unsubscribe = eventSource.on('change', onCollectionChanged);
+        unsubscribers.push(() => {
+            unsubscribe();
+        });
+        this.#itemsObserverDispose =
+            () => {
+                for (const unsubscribe of unsubscribers) {
+                    unsubscribe();
+                }
+            };
+    }
+    #disposeItemsObserver() {
+        if (this.#itemsObserverDispose) {
+            this.#itemsObserverDispose();
+            this.#itemsObserverDispose = null;
+        }
+    }
+    #syncThemeProvider() {
+        const nextProvider = this.theme
+            ? null
+            : findThemeProvider(this);
+        if (this.#themeProvider === nextProvider) {
+            return;
+        }
+        this.#disposeThemeProvider();
+        this.#themeProvider = nextProvider;
+        this.#themeProvider?.addEventListener(THEME_CHANGED_EVENT_NAME, this.#handleThemeChanged);
+    }
+    #disposeThemeProvider() {
+        this.#themeProvider?.removeEventListener(THEME_CHANGED_EVENT_NAME, this.#handleThemeChanged);
+        this.#themeProvider = null;
+    }
+    #warnMissingItemTemplate() {
+        if (this.#warnedMissingItemTemplate) {
+            return;
+        }
+        this.#warnedMissingItemTemplate = true;
+        console.warn('asljs-list: missing required template[data-slot="item"] for non-empty items.');
+    }
+    #warnInvalidContainer() {
+        if (this.#warnedInvalidContainer) {
+            return;
+        }
+        this.#warnedInvalidContainer = true;
+        console.warn('asljs-list: container template must include [data-role="items"].');
+    }
+};
+__decorate([
+    property({ attribute: false })
+], List.prototype, "items", null);
+__decorate([
+    property({ attribute: false })
+], List.prototype, "context", null);
+__decorate([
+    property({ attribute: false })
+], List.prototype, "theme", null);
+List = __decorate([
+    customElement('asljs-list')
+], List);
+export { List };
+function toEventfulLike(value) {
+    return asEventfulLike(value)
+        ?? null;
+}

package/dist/theme.d.ts

@@ -0,0 +1,13 @@
+import { type ComponentsTheme, type ThemeTemplateValue } from 'asljs-ui';
+export interface ListThemeDefinition {
+    container?: ThemeTemplateValue;
+    empty?: ThemeTemplateValue;
+    item?: ThemeTemplateValue;
+}
+declare module 'asljs-ui' {
+    interface ComponentsTheme {
+        list?: ListThemeDefinition;
+    }
+}
+/** The Bootstrap list section. */
+export declare function createBootstrapListTheme(): ComponentsTheme;

package/dist/theme.js

@@ -0,0 +1,4 @@
+/** The Bootstrap list section. */
+export function createBootstrapListTheme() {
+    return { list: { container: '<div class="list-group" data-role="items"></div>' } };
+}

package/docs/List.md

@@ -0,0 +1,106 @@
+# List
+
+`asljs-list` renders a collection from templates, binding each row to its own
+context.
+
+## Properties
+
+- `items` — a plain array, or an eventful-like collection the list re-renders
+  from when it changes
+- `context` — shared row actions and state
+- `theme`
+- local slot templates
+
+## Templates
+
+- `template[data-slot="item"]` — required; renders each row
+- `template[data-slot="empty"]` — optional; the empty state
+- `template[data-slot="container"]` — optional; must contain a
+  `[data-role="items"]` insertion point
+
+If `items` is non-empty and no item template is provided, the component warns
+and renders nothing. Themes can supply fallback templates; local templates
+always win. The theme section is `list`; `createBootstrapListTheme()` supplies
+Bootstrap list-group markup. See [Theming][THM].
+
+## Row binding context
+
+Each row is bound with `asljs-data-binding` to a row context with these fields:
+
+- `item`: the current row record
+- `index`: the zero-based row index
+- `first`: `true` for the first row
+- `last`: `true` for the last row
+- `odd`: `true` for odd row positions
+- `even`: `true` for even row positions
+- `count`: the total item count
+- `context`: the shared base context, adapted to the current row
+
+## Row actions
+
+- Reference shared actions through the row context, for example
+  `data-bind-on-click="context.select"`.
+- Row-specific values arrive through the derived row-local `this`, which
+  includes row fields such as `item` and `index`.
+- Arguments are not written in attributes: `select(item.id)` is not a binding.
+
+```ts
+import 'asljs-ui-list';
+
+const list =
+  document.createElement('asljs-list');
+
+list.context = {
+  select(this: { item: { id: string; title: string } }, event: Event) {
+    event.preventDefault();
+    console.log('selected', this.item.id, this.item.title);
+  }
+};
+
+list.innerHTML = `
+  <template data-slot="container">
+    <section class="rows" data-role="items"></section>
+  </template>
+
+  <template data-slot="empty">
+    <div>No items</div>
+  </template>
+
+  <template data-slot="item">
+    <div>
+      <a data-bind-href="item.url"
+         data-bind-text="item.title"
+         data-bind-on-click="context.select"></a>
+      <small data-bind-text="index"></small>
+    </div>
+  </template>
+`;
+
+list.items =
+  [ { title: 'First', url: '/first' },
+    { title: 'Second', url: '/second' } ];
+```
+
+## Authoring rules
+
+Rendering is template-driven. That shapes how a list is written:
+
+- Rows come from templates, not from React-style render callbacks or prop-driven
+  row renderers.
+- Bindings are `asljs-data-binding` paths, not template expressions with inline
+  function calls, and event handlers follow its path-based rules.
+- Only the documented slots are used, and a container template must keep its
+  `[data-role="items"]` insertion point.
+- Keep row templates declarative, and use `context` methods for shared row
+  actions rather than custom attribute protocols.
+- Do not mutate slot templates at runtime. Update `list.items`, or the source
+  collection, instead of rewriting row DOM.
+
+## Exports
+
+- `List` and `ListModelDefinition`
+- `ListItem`, `ListItemsSource` and `ListRowContext` types
+- `createBootstrapListTheme()` and the `ListThemeDefinition` type; the shared
+  theming exports of `asljs-ui` are listed in [Theming][THM]
+
+[THM]: ../../core/docs/Theming.md

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "asljs-ui-list",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "A web component that renders a collection from templates.",
+  "type": "module",
+  "asljs": {
+    "type": "lib"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE.md",
+    "docs/**"
+  ],
+  "scripts": {
+    "flint": "toolkit flint",
+    "clean": "toolkit clean",
+    "build": "npm run codegen --if-present && tsc -p tsconfig.build.json",
+    "build:dist": "npm run codegen --if-present && tsc -p tsconfig.dist.json",
+    "typecheck": "npm run codegen --if-present && tsc -p tsconfig.build.json --noEmit",
+    "guard:clean-git": "toolkit ensure-clean-working-directory",
+    "prepack": "npm run clean && npm run build:dist && npm run build && npm run test && npm run guard:clean-git",
+    "postpublish": "toolkit tag-release-revision",
+    "test": "node --test --enable-source-maps \"build/**/*.test.js\"",
+    "test:watch": "node --watch --test \"build/**/*.test.js\"",
+    "coverage": "npm run build && node --test --experimental-test-coverage --enable-source-maps --test-coverage-exclude=\"**/*.test.js\" \"build/**/*.test.js\"",
+    "release:patch": "toolkit release-patch",
+    "all": "npm run clean && npm run build:dist && npm run flint && npm run typecheck && npm run build && npm run test"
+  },
+  "keywords": [
+    "web-components",
+    "lit",
+    "ui",
+    "list"
+  ],
+  "author": "\"Alex Netkachov\" <alex.netkachov@gmail.com>",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "homepage": "https://github.com/AlexandriteSoftware/asljs#readme",
+  "bugs": {
+    "url": "https://github.com/AlexandriteSoftware/asljs/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlexandriteSoftware/asljs.git"
+  },
+  "dependencies": {
+    "asljs-data-binding": "^0.2.5",
+    "asljs-eventful": "^0.4.11",
+    "asljs-ui": "^0.1.1",
+    "lit": "^3.3.1"
+  },
+  "devDependencies": {
+    "asljs-observable": "^0.5.5",
+    "asljs-testing": "^0.1.1",
+    "asljs-toolkit": "^0.1.0"
+  }
+}