asljs-ui-select 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,79 @@
-# Temporary Holding Version
+# select
 
-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-select` provides `asljs-select`, a labelled drop-down with validation.
+`items` lists the options, `value` sets or resets the selection, and the user's
+choice is reported through `input` and `change` events.
+
+## Scope
+
+- Explicit `{ value, label, disabled? }` items and an optional placeholder.
+- Validation through a `validator` function returning an error message.
+- Layout and control markup from templates: a local slot template, the `select`
+  theme section, or the Bootstrap part, `createBootstrapSelectTheme()`.
+
+## Installation
+
+```bash
+npm install asljs-ui-select
+```
+
+NPM package: [asljs-ui-select][NPM]
+
+## Usage
+
+Import the package once to register the element:
+
+```ts
+import 'asljs-ui-select';
+
+const select =
+  document.createElement('asljs-select') as HTMLElement & {
+    label: string | null;
+    items: Array<{ value: string; label: string }>;
+    value: string | null;
+  };
+
+select.label = 'Size';
+select.items =
+  [ { value: 's', label: 'Small' },
+    { value: 'm', label: 'Medium' } ];
+select.value = 'm';
+
+select.addEventListener(
+  'change',
+  event => console.log((event as CustomEvent<{ value: string }>).detail.value));
+
+document.body.appendChild(select);
+```
+
+## Further reading
+
+- [Select][DOC] - properties, events and templates.
+- [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.
+- [text-input][TXT] - the text field with the same set/reset contract.
+- [select-lookup][SLK] - a drop-down that searches as the user types.
+
+## License
+
+MIT License. See [LICENSE][LIC] for details.
+
+[#1]: https://github.com/AlexandriteSoftware/asljs
+[DOC]: docs/Select.md
+[ISS]: https://github.com/AlexandriteSoftware/asljs/issues
+[LIC]: LICENSE.md
+[NPM]: https://www.npmjs.com/package/asljs-ui-select
+[SLK]: ../select-lookup/README.md
+[THM]: ../core/docs/Theming.md
+[TXT]: ../text-input/README.md
+[UI]: ../core/README.md

package/dist/bootstrap-select.tpl.d.ts

@@ -0,0 +1,6 @@
+import { type BindDataModelOptions } from "asljs-data-binding";
+import type { SelectTemplateModel as TemplateModel } from "./select.js";
+/** The markup inside the template's <template> element. */
+export declare const html = "\n  <div class=\"mb-3\"\n       data-bind-class-asljs-select-empty=\"isEmpty\"\n       data-bind-class-asljs-select-invalid=\"hasError\">\n    <label class=\"form-label\"\n           data-bind-text=\"label\"\n           data-bind-prop-hidden=\"hideLabel\"\n           data-bind-for=\"inputId\"></label>\n    <div data-role=\"control-host\"></div>\n    <div class=\"invalid-feedback\"\n         data-bind-text=\"errorMessage\"\n         data-bind-prop-hidden=\"hideError\"\n         data-bind-prop-id=\"errorId\"></div>\n    <div class=\"form-text\"\n         data-bind-text=\"description\"\n         data-bind-prop-hidden=\"hideDescription\"\n         data-bind-prop-id=\"descriptionId\"></div>\n  </div>\n";
+export declare function createTemplate(doc?: Document): HTMLTemplateElement;
+export declare function bindTemplate(root: ParentNode, model: TemplateModel, options?: BindDataModelOptions): () => boolean;

package/dist/bootstrap-select.tpl.js

@@ -0,0 +1,28 @@
+// Generated by data-bind-compile from bootstrap-select.tpl.html. Do not edit.
+import { bindDataModel } from "asljs-data-binding";
+/** The markup inside the template's <template> element. */
+export const html = "\n  <div class=\"mb-3\"\n       data-bind-class-asljs-select-empty=\"isEmpty\"\n       data-bind-class-asljs-select-invalid=\"hasError\">\n    <label class=\"form-label\"\n           data-bind-text=\"label\"\n           data-bind-prop-hidden=\"hideLabel\"\n           data-bind-for=\"inputId\"></label>\n    <div data-role=\"control-host\"></div>\n    <div class=\"invalid-feedback\"\n         data-bind-text=\"errorMessage\"\n         data-bind-prop-hidden=\"hideError\"\n         data-bind-prop-id=\"errorId\"></div>\n    <div class=\"form-text\"\n         data-bind-text=\"description\"\n         data-bind-prop-hidden=\"hideDescription\"\n         data-bind-prop-id=\"descriptionId\"></div>\n  </div>\n";
+export function createTemplate(doc = document) {
+    const template = doc.createElement('template');
+    template.innerHTML = html;
+    return template;
+}
+export function bindTemplate(root, model, options) {
+    return bindDataModel(root, model, options);
+}
+// Never called: each statement checks one binding against the model and
+// element types, and names the template line it comes from.
+function check(model) {
+    void model.isEmpty; // bootstrap-select.tpl.html:3:8 data-bind-class-asljs-select-empty
+    void model.hasError; // bootstrap-select.tpl.html:4:8 data-bind-class-asljs-select-invalid
+    void model.label; // bootstrap-select.tpl.html:6:12 data-bind-text
+    void model.hideLabel; // bootstrap-select.tpl.html:7:12 data-bind-prop-hidden
+    void model.inputId; // bootstrap-select.tpl.html:8:12 data-bind-for
+    void model.errorMessage; // bootstrap-select.tpl.html:11:10 data-bind-text
+    void model.hideError; // bootstrap-select.tpl.html:12:10 data-bind-prop-hidden
+    void model.errorId; // bootstrap-select.tpl.html:13:10 data-bind-prop-id
+    void model.description; // bootstrap-select.tpl.html:15:10 data-bind-text
+    void model.hideDescription; // bootstrap-select.tpl.html:16:10 data-bind-prop-hidden
+    void model.descriptionId; // bootstrap-select.tpl.html:17:10 data-bind-prop-id
+}
+void check;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Select, SelectModelDefinition, type SelectChangeDetail, type SelectItem, type SelectStatus, type SelectValidator } from './select.js';
+export { createBootstrapSelectTheme, type SelectThemeDefinition } from './theme.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Select, SelectModelDefinition } from './select.js';
+export { createBootstrapSelectTheme } from './theme.js';

package/dist/select.d.ts

@@ -0,0 +1,59 @@
+import { type Converted } from 'asljs-observable';
+import { ComponentModelDefinition, ComponentsTheme } from 'asljs-ui';
+import { LitElement } from 'lit';
+export interface SelectItem {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+export type SelectValidator = (value: string) => string | null;
+export interface SelectChangeDetail {
+    value: string;
+    isEmpty: boolean;
+    isValid: boolean;
+    errorMessage: string | null;
+    dirty: boolean;
+}
+export type SelectStatus = Converted<{
+    draftValue: string;
+    isEmpty: boolean;
+    isValid: boolean;
+    errorMessage: string | null;
+    dirty: boolean;
+}>;
+export type SelectTemplateModel = Converted<{
+    label: string;
+    description: string;
+    errorMessage: string;
+    hideLabel: boolean;
+    hideDescription: boolean;
+    hideError: boolean;
+    hasError: boolean;
+    isEmpty: boolean;
+    inputId: string;
+    descriptionId: string;
+    errorId: string;
+}>;
+export declare const SelectModelDefinition: ComponentModelDefinition;
+export declare class Select extends LitElement {
+    #private;
+    readonly status: SelectStatus;
+    accessor label: string | null;
+    accessor description: string | null;
+    accessor validator: SelectValidator | null;
+    accessor theme: ComponentsTheme | null;
+    accessor value: string | null;
+    accessor placeholder: string | null;
+    accessor items: SelectItem[];
+    accessor disabled: boolean;
+    accessor controlClassName: string;
+    get draftValue(): string;
+    get isEmpty(): boolean;
+    get isValid(): boolean;
+    get errorMessage(): string | null;
+    createRenderRoot(): this;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    render(): ReturnType<LitElement['render']>;
+    updated(changedProperties: Map<PropertyKey, unknown>): void;
+}

package/dist/select.js

@@ -0,0 +1,508 @@
+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 { observable } from 'asljs-observable';
+import { defineComponentModel, findThemeProvider, getDefaultTheme, resolveThemeTemplate, THEME_CHANGED_EVENT_NAME } from 'asljs-ui';
+import { html, LitElement } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+import { createTemplate } from './select.tpl.js';
+export const SelectModelDefinition = { name: 'SelectModelDefinition',
+    title: 'Select',
+    properties: [{ name: 'label',
+            title: 'Label',
+            type: 'string' },
+        { name: 'description',
+            title: 'Description',
+            type: 'string' },
+        { name: 'validator',
+            title: 'Validator',
+            type: 'function',
+            description: 'Validation function that returns an error message or null.' },
+        { name: 'theme',
+            title: 'Theme',
+            type: 'object',
+            description: 'Per-instance components theme override.' },
+        { name: 'value',
+            title: 'Value',
+            type: 'string' },
+        { name: 'placeholder',
+            title: 'Placeholder',
+            type: 'string' },
+        { name: 'items',
+            title: 'Items',
+            type: 'array' },
+        { name: 'disabled',
+            title: 'Disabled',
+            type: 'boolean' },
+        { name: 'controlClassName',
+            title: 'Control class name',
+            type: 'string' },
+        { name: 'status',
+            title: 'Status',
+            type: 'object',
+            description: 'Observable draft status object.',
+            editable: false },
+        { name: 'draftValue',
+            title: 'Draft value',
+            type: 'string',
+            description: 'Current in-progress selection.',
+            editable: false },
+        { name: 'isEmpty',
+            title: 'Is empty',
+            type: 'boolean',
+            editable: false },
+        { name: 'isValid',
+            title: 'Is valid',
+            type: 'boolean',
+            editable: false },
+        { name: 'errorMessage',
+            title: 'Error message',
+            type: 'string',
+            description: 'Current validation message or null.',
+            editable: false }] };
+defineComponentModel('asljs-select', SelectModelDefinition);
+let Select = class Select extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.#templateElement = null;
+        this.#selectTemplateElement = null;
+        this.#templateDispose = null;
+        this.#controlTemplateDispose = null;
+        this.#themeProvider = null;
+        this.#control = null;
+        this.#controlBaseClassName = '';
+        this.#controlInvalidClassName = null;
+        this.#controlChangeListener = null;
+        this.#idBase = `asljs-select-${nextSelectId++}`;
+        this.#model = observable({ label: '',
+            description: '',
+            errorMessage: '',
+            hideLabel: true,
+            hideDescription: true,
+            hideError: true,
+            hasError: false,
+            isEmpty: true,
+            inputId: `${this.#idBase}-control`,
+            descriptionId: `${this.#idBase}-description`,
+            errorId: `${this.#idBase}-error` });
+        this.status = observable({ draftValue: '',
+            isEmpty: true,
+            isValid: true,
+            errorMessage: null,
+            dirty: false });
+        this.#label_accessor_storage = null;
+        this.#description_accessor_storage = null;
+        this.#validator_accessor_storage = null;
+        this.#theme_accessor_storage = null;
+        this.#value_accessor_storage = '';
+        this.#placeholder_accessor_storage = null;
+        this.#items_accessor_storage = [];
+        this.#disabled_accessor_storage = false;
+        this.#controlClassName_accessor_storage = '';
+        this.#handleThemeChanged = () => {
+            this.#renderTemplate();
+        };
+    }
+    #templateElement;
+    #selectTemplateElement;
+    #templateDispose;
+    #controlTemplateDispose;
+    #themeProvider;
+    #control;
+    #controlBaseClassName;
+    #controlInvalidClassName;
+    #controlChangeListener;
+    #idBase;
+    #model;
+    #label_accessor_storage;
+    get label() { return this.#label_accessor_storage; }
+    set label(value) { this.#label_accessor_storage = value; }
+    #description_accessor_storage;
+    get description() { return this.#description_accessor_storage; }
+    set description(value) { this.#description_accessor_storage = value; }
+    #validator_accessor_storage;
+    get validator() { return this.#validator_accessor_storage; }
+    set validator(value) { this.#validator_accessor_storage = value; }
+    #theme_accessor_storage;
+    get theme() { return this.#theme_accessor_storage; }
+    set theme(value) { this.#theme_accessor_storage = value; }
+    #value_accessor_storage;
+    get value() { return this.#value_accessor_storage; }
+    set value(value) { this.#value_accessor_storage = value; }
+    #placeholder_accessor_storage;
+    get placeholder() { return this.#placeholder_accessor_storage; }
+    set placeholder(value) { this.#placeholder_accessor_storage = value; }
+    #items_accessor_storage;
+    get items() { return this.#items_accessor_storage; }
+    set items(value) { this.#items_accessor_storage = value; }
+    #disabled_accessor_storage;
+    get disabled() { return this.#disabled_accessor_storage; }
+    set disabled(value) { this.#disabled_accessor_storage = value; }
+    #controlClassName_accessor_storage;
+    get controlClassName() { return this.#controlClassName_accessor_storage; }
+    set controlClassName(value) { this.#controlClassName_accessor_storage = value; }
+    get draftValue() {
+        return this.status.draftValue;
+    }
+    get isEmpty() {
+        return this.status.isEmpty;
+    }
+    get isValid() {
+        return this.status.isValid;
+    }
+    get errorMessage() {
+        return this.status.errorMessage;
+    }
+    createRenderRoot() {
+        return this;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.#captureTemplates();
+        this.#syncThemeProvider();
+        this.#applyExternalValue();
+    }
+    disconnectedCallback() {
+        this.#disposeControlBindings();
+        this.#templateDispose?.();
+        this.#templateDispose = null;
+        this.#controlTemplateDispose?.();
+        this.#controlTemplateDispose = null;
+        this.#disposeThemeProvider();
+        super.disconnectedCallback();
+    }
+    render() {
+        return html `
+      <div data-role="template-host"></div>
+    `;
+    }
+    updated(changedProperties) {
+        if (changedProperties.has('theme')) {
+            this.#syncThemeProvider();
+        }
+        if (changedProperties.has('value')) {
+            this.#applyExternalValue();
+        }
+        if (changedProperties.has('label')
+            || changedProperties.has('description')
+            || changedProperties.has('theme')) {
+            this.#renderTemplate();
+            return;
+        }
+        if (changedProperties.has('placeholder')
+            || changedProperties.has('disabled')
+            || changedProperties.has('items')
+            || changedProperties.has('controlClassName')) {
+            this.#syncControlState();
+        }
+        this.#syncModelState();
+    }
+    #captureTemplates() {
+        this.#templateElement =
+            cloneNamedTemplate(this, 'template');
+        this.#selectTemplateElement =
+            cloneNamedTemplate(this, 'select');
+    }
+    #syncThemeProvider() {
+        this.#disposeThemeProvider();
+        this.#themeProvider =
+            findThemeProvider(this);
+        if (this.#themeProvider === null) {
+            return;
+        }
+        this.#themeProvider.addEventListener(THEME_CHANGED_EVENT_NAME, this.#handleThemeChanged);
+    }
+    #disposeThemeProvider() {
+        this.#themeProvider?.removeEventListener(THEME_CHANGED_EVENT_NAME, this.#handleThemeChanged);
+        this.#themeProvider = null;
+    }
+    #handleThemeChanged;
+    #applyExternalValue() {
+        this.status.draftValue =
+            normalizeText(this.value);
+        this.#syncModelState();
+        this.#syncControlState();
+    }
+    #syncModelState() {
+        const label = normalizeOptionalText(this.label);
+        const description = normalizeOptionalText(this.description);
+        let errorMessage = null;
+        const validator = this.validator;
+        if (validator !== null) {
+            errorMessage =
+                validator(this.status.draftValue);
+        }
+        const isEmpty = this.status.draftValue === '';
+        const dirty = this.status.draftValue !== normalizeText(this.value);
+        this.status.isEmpty = isEmpty;
+        this.status.errorMessage = errorMessage;
+        this.status.isValid = errorMessage === null;
+        this.status.dirty = dirty;
+        this.#model.label = label ?? '';
+        this.#model.description = description ?? '';
+        this.#model.errorMessage = errorMessage ?? '';
+        this.#model.hideLabel = label === null;
+        this.#model.hideDescription = description === null;
+        this.#model.hideError = errorMessage === null;
+        this.#model.hasError = errorMessage !== null;
+        this.#model.isEmpty = isEmpty;
+        this.#syncControlState();
+    }
+    #renderTemplate() {
+        const templateHost = this.querySelector('[data-role="template-host"]');
+        if (templateHost === null) {
+            return;
+        }
+        this.#templateDispose?.();
+        this.#templateDispose = null;
+        this.#controlTemplateDispose?.();
+        this.#controlTemplateDispose = null;
+        this.#disposeControlBindings();
+        const template = this.#resolveTemplate('template');
+        if (template === null) {
+            templateHost.replaceChildren();
+            return;
+        }
+        const fragment = template.content.cloneNode(true);
+        this.#templateDispose =
+            bindDataModel(fragment, this.#model);
+        templateHost.replaceChildren(fragment);
+        this.#mountControl();
+        this.#syncModelState();
+    }
+    #resolveTemplate(slotName) {
+        return this.#getLocalTemplate(slotName)
+            ?? this.#getThemeTemplate(slotName)
+            ?? createDefaultSelectTemplate(slotName);
+    }
+    #getLocalTemplate(slotName) {
+        return slotName === 'template'
+            ? this.#templateElement
+            : this.#selectTemplateElement;
+    }
+    #getThemeTemplate(slotName) {
+        const theme = this.theme
+            ?? this.#themeProvider?.theme
+            ?? getDefaultTheme();
+        return resolveThemeTemplate(slotName === 'template'
+            ? theme.select?.template
+            : theme.select?.select, this);
+    }
+    #mountControl() {
+        const controlHost = this.querySelector('[data-role="control-host"]');
+        if (controlHost === null) {
+            return;
+        }
+        const mountedControl = this.#createMountedControl(controlHost);
+        this.#controlTemplateDispose =
+            bindDataModel(mountedControl.fragment, this.#model);
+        controlHost.replaceChildren(mountedControl.fragment);
+        this.#control =
+            mountedControl.control;
+        this.#controlBaseClassName =
+            mountedControl.className;
+        this.#controlInvalidClassName =
+            mountedControl.invalidClassName;
+        const changeListener = () => {
+            if (this.#control === null) {
+                return;
+            }
+            this.status.draftValue = this.#control.value;
+            this.#syncModelState();
+            this.#dispatchValueEvent('input');
+            this.#dispatchValueEvent('change');
+        };
+        this.#control.addEventListener('change', changeListener);
+        this.#controlChangeListener =
+            () => {
+                this.#control?.removeEventListener('change', changeListener);
+            };
+        this.#syncControlState();
+    }
+    #syncControlState() {
+        const control = this.#control;
+        if (control === null) {
+            return;
+        }
+        control.replaceChildren();
+        const placeholder = normalizeOptionalText(this.placeholder);
+        if (placeholder !== null) {
+            const option = document.createElement('option');
+            option.value = '';
+            option.textContent = placeholder;
+            control.appendChild(option);
+        }
+        for (const item of normalizeItems(this.items)) {
+            const option = document.createElement('option');
+            option.value = item.value;
+            option.textContent = item.label;
+            option.disabled = item.disabled ?? false;
+            control.appendChild(option);
+        }
+        const candidateValues = Array.from(control.options).map(option => option.value);
+        const nextValue = candidateValues.includes(this.status.draftValue)
+            ? this.status.draftValue
+            : placeholder !== null
+                ? ''
+                : candidateValues[0] ?? '';
+        if (this.status.draftValue
+            !== nextValue) {
+            this.status.draftValue = nextValue;
+            this.#syncModelState();
+        }
+        control.value = nextValue;
+        control.id = this.#model.inputId;
+        control.disabled = this.disabled;
+        control.className =
+            joinClassNames(this.#controlBaseClassName, this.controlClassName);
+        if (this.#controlInvalidClassName
+            !== null
+            && !this.status.isValid) {
+            control.classList.add(this.#controlInvalidClassName);
+        }
+        control.toggleAttribute('aria-invalid', !this.status.isValid);
+        control.setAttribute('aria-describedby', resolveAriaDescribedBy(this.#model));
+    }
+    #createMountedControl(controlHost) {
+        const template = this.#resolveTemplate('select');
+        if (template === null) {
+            return createFallbackMountedControl(controlHost);
+        }
+        const fragment = template.content.cloneNode(true);
+        const control = fragment.querySelector('select');
+        if (control === null) {
+            return createFallbackMountedControl(controlHost);
+        }
+        return { fragment,
+            control,
+            className: resolveInitialControlClassName(control, controlHost),
+            invalidClassName: resolveInitialControlInvalidClassName(control, controlHost) };
+    }
+    #dispatchValueEvent(name) {
+        const detail = { value: this.status.draftValue,
+            isEmpty: this.status.isEmpty,
+            isValid: this.status.isValid,
+            errorMessage: this.status.errorMessage,
+            dirty: this.status.dirty };
+        this.dispatchEvent(new CustomEvent(name, { detail,
+            bubbles: true,
+            composed: true }));
+    }
+    #disposeControlBindings() {
+        this.#controlChangeListener?.();
+        this.#controlChangeListener = null;
+        this.#control = null;
+        this.#controlBaseClassName = '';
+        this.#controlInvalidClassName = null;
+        this.#controlTemplateDispose?.();
+        this.#controlTemplateDispose = null;
+    }
+};
+__decorate([
+    property({ attribute: false })
+], Select.prototype, "label", null);
+__decorate([
+    property({ attribute: false })
+], Select.prototype, "description", null);
+__decorate([
+    property({ attribute: false })
+], Select.prototype, "validator", null);
+__decorate([
+    property({ attribute: false })
+], Select.prototype, "theme", null);
+__decorate([
+    property({ attribute: false })
+], Select.prototype, "value", null);
+__decorate([
+    property({ attribute: false })
+], Select.prototype, "placeholder", null);
+__decorate([
+    property({ attribute: false })
+], Select.prototype, "items", null);
+__decorate([
+    property({ attribute: false })
+], Select.prototype, "disabled", null);
+__decorate([
+    property({ attribute: false })
+], Select.prototype, "controlClassName", null);
+Select = __decorate([
+    customElement('asljs-select')
+], Select);
+export { Select };
+let nextSelectId = 1;
+function normalizeText(value) {
+    return value ?? '';
+}
+function normalizeOptionalText(value) {
+    if (value === null
+        || value === undefined
+        || value === '') {
+        return null;
+    }
+    return value;
+}
+function normalizeItems(items) {
+    return items
+        .map(item => ({ value: item.value,
+        label: item.label,
+        disabled: item.disabled ?? false }))
+        .filter(item => item.label.trim() !== '');
+}
+function resolveAriaDescribedBy(model) {
+    const ids = [];
+    if (!model.hideDescription) {
+        ids.push(model.descriptionId);
+    }
+    if (!model.hideError) {
+        ids.push(model.errorId);
+    }
+    return ids.join(' ');
+}
+function cloneNamedTemplate(host, slotName) {
+    const element = host.querySelector(`template[data-slot="${slotName}"]`);
+    if (element === null) {
+        return null;
+    }
+    const templateElement = element;
+    const clonedTemplate = document.createElement('template');
+    clonedTemplate.content.append(templateElement.content.cloneNode(true));
+    return clonedTemplate;
+}
+function resolveInitialControlClassName(control, controlHost) {
+    return control.className
+        || controlHost.getAttribute('data-control-class')
+        || '';
+}
+function resolveInitialControlInvalidClassName(control, controlHost) {
+    return control.getAttribute('data-control-invalid-class')
+        ?? controlHost.getAttribute('data-control-invalid-class')
+        ?? null;
+}
+function createDefaultSelectTemplate(slotName) {
+    if (slotName === 'template') {
+        return createTemplate();
+    }
+    const template = document.createElement('template');
+    template.innerHTML = '<select></select>';
+    return template;
+}
+function createFallbackMountedControl(controlHost) {
+    const fragment = document.createDocumentFragment();
+    const control = document.createElement('select');
+    fragment.append(control);
+    return { fragment,
+        control,
+        className: resolveInitialControlClassName(control, controlHost),
+        invalidClassName: resolveInitialControlInvalidClassName(control, controlHost) };
+}
+function joinClassNames(...classNames) {
+    return classNames
+        .flatMap(className => className.split(/\s+/))
+        .map(className => className.trim())
+        .filter(className => className !== '')
+        .join(' ');
+}

package/dist/select.tpl.d.ts

@@ -0,0 +1,6 @@
+import { type BindDataModelOptions } from "asljs-data-binding";
+import type { SelectTemplateModel as TemplateModel } from "./select.js";
+/** The markup inside the template's <template> element. */
+export declare const html = "\n  <div>\n    <label\n           data-bind-text=\"label\"\n           data-bind-prop-hidden=\"hideLabel\"\n           data-bind-for=\"inputId\"></label>\n    <div data-role=\"control-host\"></div>\n    <div\n         data-bind-text=\"description\"\n         data-bind-prop-hidden=\"hideDescription\"\n         data-bind-prop-id=\"descriptionId\"></div>\n    <div\n         data-bind-text=\"errorMessage\"\n         data-bind-prop-hidden=\"hideError\"\n         data-bind-prop-id=\"errorId\"></div>\n  </div>\n";
+export declare function createTemplate(doc?: Document): HTMLTemplateElement;
+export declare function bindTemplate(root: ParentNode, model: TemplateModel, options?: BindDataModelOptions): () => boolean;

package/dist/select.tpl.js

@@ -0,0 +1,26 @@
+// Generated by data-bind-compile from select.tpl.html. Do not edit.
+import { bindDataModel } from "asljs-data-binding";
+/** The markup inside the template's <template> element. */
+export const html = "\n  <div>\n    <label\n           data-bind-text=\"label\"\n           data-bind-prop-hidden=\"hideLabel\"\n           data-bind-for=\"inputId\"></label>\n    <div data-role=\"control-host\"></div>\n    <div\n         data-bind-text=\"description\"\n         data-bind-prop-hidden=\"hideDescription\"\n         data-bind-prop-id=\"descriptionId\"></div>\n    <div\n         data-bind-text=\"errorMessage\"\n         data-bind-prop-hidden=\"hideError\"\n         data-bind-prop-id=\"errorId\"></div>\n  </div>\n";
+export function createTemplate(doc = document) {
+    const template = doc.createElement('template');
+    template.innerHTML = html;
+    return template;
+}
+export function bindTemplate(root, model, options) {
+    return bindDataModel(root, model, options);
+}
+// Never called: each statement checks one binding against the model and
+// element types, and names the template line it comes from.
+function check(model) {
+    void model.label; // select.tpl.html:4:12 data-bind-text
+    void model.hideLabel; // select.tpl.html:5:12 data-bind-prop-hidden
+    void model.inputId; // select.tpl.html:6:12 data-bind-for
+    void model.description; // select.tpl.html:9:10 data-bind-text
+    void model.hideDescription; // select.tpl.html:10:10 data-bind-prop-hidden
+    void model.descriptionId; // select.tpl.html:11:10 data-bind-prop-id
+    void model.errorMessage; // select.tpl.html:13:10 data-bind-text
+    void model.hideError; // select.tpl.html:14:10 data-bind-prop-hidden
+    void model.errorId; // select.tpl.html:15:10 data-bind-prop-id
+}
+void check;

package/dist/theme.d.ts

@@ -0,0 +1,12 @@
+import { type ComponentsTheme, type ThemeTemplateValue } from 'asljs-ui';
+export interface SelectThemeDefinition {
+    template?: ThemeTemplateValue;
+    select?: ThemeTemplateValue;
+}
+declare module 'asljs-ui' {
+    interface ComponentsTheme {
+        select?: SelectThemeDefinition;
+    }
+}
+/** The Bootstrap select section. */
+export declare function createBootstrapSelectTheme(): ComponentsTheme;

package/dist/theme.js

@@ -0,0 +1,9 @@
+import { html as selectTemplate } from './bootstrap-select.tpl.js';
+/** The Bootstrap select section. */
+export function createBootstrapSelectTheme() {
+    return { select: { template: selectTemplate,
+            select: `
+            <select class="form-select"
+                    data-control-invalid-class="is-invalid"></select>
+          ` } };
+}

package/docs/Select.md

@@ -0,0 +1,68 @@
+# Select
+
+`asljs-select` is a labelled drop-down with validation.
+
+## Properties
+
+- `items` — explicit `{ value, label, disabled? }` entries
+- `value` — the external set/reset selection
+- `label`
+- `description`
+- `placeholder` — when set, an empty prompt option is shown first
+- `validator` — returns an error message or `null`
+- `disabled`
+- `controlClassName` — a class for the inner native `select`, for host CSS
+- `theme`
+- local `template[data-slot="template"]` and `template[data-slot="select"]`
+
+As with [text input][TXT], `value` is a set/reset input. The user's selection is
+kept in `draftValue`, reflected in the observable `status` object, and emitted
+through `input` and `change` events. Their detail is:
+
+```ts
+{
+  value: string;
+  isEmpty: boolean;
+  isValid: boolean;
+  errorMessage: string | null;
+  dirty: boolean;
+}
+```
+
+## Usage
+
+```ts
+import 'asljs-ui-select';
+
+const select =
+  document.createElement('asljs-select') as HTMLElement & {
+    label: string | null;
+    items: Array<{ value: string; label: string; disabled?: boolean }>;
+    value: string | null;
+    placeholder: string | null;
+  };
+
+select.label = 'Size';
+select.placeholder = 'Choose a size';
+select.items =
+  [ { value: 's', label: 'Small' },
+    { value: 'm', label: 'Medium' },
+    { value: 'l', label: 'Large', disabled: true } ];
+select.value = 'm';
+
+select.addEventListener(
+  'change',
+  event => {
+    const detail =
+      (event as CustomEvent<{ value: string; isValid: boolean }>).detail;
+
+    console.log(detail.value, detail.isValid);
+  });
+```
+
+Layout and control markup can be overridden with local slot templates or the
+`select` section of a theme, as for text input; `createBootstrapSelectTheme()`
+supplies Bootstrap form markup. See [Theming][THM].
+
+[THM]: ../../core/docs/Theming.md
+[TXT]: <../../text-input/docs/Text Input.md>

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "asljs-ui-select",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "A drop-down web component with validation.",
+  "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",
+    "codegen": "data-bind-compile"
+  },
+  "keywords": [
+    "web-components",
+    "lit",
+    "ui",
+    "select",
+    "form"
+  ],
+  "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-observable": "^0.5.5",
+    "asljs-ui": "^0.1.1",
+    "lit": "^3.3.1"
+  },
+  "devDependencies": {
+    "asljs-testing": "^0.1.1",
+    "asljs-toolkit": "^0.1.0"
+  }
+}