asljs-ui-text-input 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,76 @@
-# Temporary Holding Version
+# text-input
 
-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-text-input` provides `asljs-text-input`, a labelled text field or
+textarea with validation. `value` sets or resets the field; the user's draft,
+its validity and dirty state are reported through `input` and `change` events.
+
+## Scope
+
+- Single-line input or auto-extending textarea.
+- Validation through a `validator` function returning an error message.
+- Layout and control markup from templates: a local slot template, the
+  `textInput` theme section, or the Bootstrap part,
+  `createBootstrapTextInputTheme()`.
+
+## Installation
+
+```bash
+npm install asljs-ui-text-input
+```
+
+NPM package: [asljs-ui-text-input][NPM]
+
+## Usage
+
+Import the package once to register the element:
+
+```ts
+import 'asljs-ui-text-input';
+
+const input =
+  document.createElement('asljs-text-input') as HTMLElement & {
+    label: string | null;
+    validator: ((value: string) => string | null) | null;
+  };
+
+input.label = 'Name';
+input.validator =
+  value => value.trim() === ''
+    ? 'Name is required.'
+    : null;
+
+input.addEventListener(
+  'change',
+  event => console.log((event as CustomEvent<{ value: string }>).detail.value));
+
+document.body.appendChild(input);
+```
+
+## Further reading
+
+- [Text Input][DOC] - properties, events and template overrides.
+- [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 templates use.
+
+## License
+
+MIT License. See [LICENSE][LIC] for details.
+
+[#1]: https://github.com/AlexandriteSoftware/asljs
+[DOC]: <docs/Text Input.md>
+[ISS]: https://github.com/AlexandriteSoftware/asljs/issues
+[LIC]: LICENSE.md
+[NPM]: https://www.npmjs.com/package/asljs-ui-text-input
+[THM]: ../core/docs/Theming.md
+[UI]: ../core/README.md

package/dist/bootstrap-text-input.tpl.d.ts

@@ -0,0 +1,6 @@
+import { type BindDataModelOptions } from "asljs-data-binding";
+import type { TextInputTemplateModel as TemplateModel } from "./text-input.js";
+/** The markup inside the template's <template> element. */
+export declare const html = "\n  <div class=\"mb-3\"\n       data-bind-class-asljs-text-input-empty=\"isEmpty\"\n       data-bind-class-asljs-text-input-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-text-input.tpl.js

@@ -0,0 +1,28 @@
+// Generated by data-bind-compile from bootstrap-text-input.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-text-input-empty=\"isEmpty\"\n       data-bind-class-asljs-text-input-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-text-input.tpl.html:3:8 data-bind-class-asljs-text-input-empty
+    void model.hasError; // bootstrap-text-input.tpl.html:4:8 data-bind-class-asljs-text-input-invalid
+    void model.label; // bootstrap-text-input.tpl.html:6:12 data-bind-text
+    void model.hideLabel; // bootstrap-text-input.tpl.html:7:12 data-bind-prop-hidden
+    void model.inputId; // bootstrap-text-input.tpl.html:8:12 data-bind-for
+    void model.errorMessage; // bootstrap-text-input.tpl.html:11:10 data-bind-text
+    void model.hideError; // bootstrap-text-input.tpl.html:12:10 data-bind-prop-hidden
+    void model.errorId; // bootstrap-text-input.tpl.html:13:10 data-bind-prop-id
+    void model.description; // bootstrap-text-input.tpl.html:15:10 data-bind-text
+    void model.hideDescription; // bootstrap-text-input.tpl.html:16:10 data-bind-prop-hidden
+    void model.descriptionId; // bootstrap-text-input.tpl.html:17:10 data-bind-prop-id
+}
+void check;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { TextInput, TextInputModelDefinition, type TextInputChangeDetail, type TextInputEnterKeyBehavior, type TextInputStatus, type TextInputValidator } from './text-input.js';
+export { createBootstrapTextInputTheme, type TextInputThemeDefinition } from './theme.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { TextInput, TextInputModelDefinition } from './text-input.js';
+export { createBootstrapTextInputTheme } from './theme.js';

package/dist/text-input.d.ts

@@ -0,0 +1,61 @@
+import { type Converted } from 'asljs-observable';
+import { ComponentModelDefinition, ComponentsTheme } from 'asljs-ui';
+import { LitElement } from 'lit';
+export type TextInputEnterKeyBehavior = 'finish' | 'newline';
+export type TextInputValidator = (value: string) => string | null;
+export interface TextInputChangeDetail {
+    value: string;
+    isEmpty: boolean;
+    isValid: boolean;
+    errorMessage: string | null;
+    dirty: boolean;
+}
+export type TextInputStatus = Converted<{
+    draftValue: string;
+    isEmpty: boolean;
+    isValid: boolean;
+    errorMessage: string | null;
+    dirty: boolean;
+}>;
+export type TextInputTemplateModel = Converted<{
+    label: string;
+    description: string;
+    errorMessage: string;
+    hideLabel: boolean;
+    hideDescription: boolean;
+    hideError: boolean;
+    hasError: boolean;
+    isEmpty: boolean;
+    multiline: boolean;
+    inputId: string;
+    descriptionId: string;
+    errorId: string;
+}>;
+export declare const TextInputModelDefinition: ComponentModelDefinition;
+export declare class TextInput extends LitElement {
+    #private;
+    readonly status: TextInputStatus;
+    accessor label: string | null;
+    accessor description: string | null;
+    accessor validator: TextInputValidator | null;
+    accessor theme: ComponentsTheme | null;
+    accessor value: string | null;
+    accessor placeholder: string | null;
+    accessor inputType: string;
+    accessor controlClassName: string;
+    accessor multiline: boolean;
+    accessor autoExtend: boolean;
+    accessor autoExtendMaxRows: number | null;
+    accessor enterKeyBehavior: TextInputEnterKeyBehavior;
+    accessor disabled: boolean;
+    accessor rows: number;
+    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/text-input.js

@@ -0,0 +1,676 @@
+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 './text-input.tpl.js';
+export const TextInputModelDefinition = { name: 'TextInputModelDefinition',
+    title: 'Text Input',
+    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: 'inputType',
+            title: 'Input type',
+            type: 'string' },
+        { name: 'controlClassName',
+            title: 'Control class name',
+            type: 'string' },
+        { name: 'multiline',
+            title: 'Multiline',
+            type: 'boolean' },
+        { name: 'autoExtend',
+            title: 'Auto extend',
+            type: 'boolean' },
+        { name: 'autoExtendMaxRows',
+            title: 'Auto extend max rows',
+            type: 'number',
+            description: 'Maximum rows when auto extend is enabled.' },
+        { name: 'enterKeyBehavior',
+            title: 'Enter key behavior',
+            type: 'string' },
+        { name: 'disabled',
+            title: 'Disabled',
+            type: 'boolean' },
+        { name: 'rows',
+            title: 'Rows',
+            type: 'number' },
+        { name: 'status',
+            title: 'Status',
+            type: 'object',
+            description: 'Observable draft status object.',
+            editable: false },
+        { name: 'draftValue',
+            title: 'Draft value',
+            type: 'string',
+            description: 'Current in-progress text.',
+            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-text-input', TextInputModelDefinition);
+let TextInput = class TextInput extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.#templateElement = null;
+        this.#inputTemplateElement = null;
+        this.#textareaTemplateElement = null;
+        this.#templateDispose = null;
+        this.#controlTemplateDispose = null;
+        this.#themeProvider = null;
+        this.#control = null;
+        this.#controlBaseClassName = '';
+        this.#controlInvalidClassName = null;
+        this.#controlInputListener = null;
+        this.#controlBlurListener = null;
+        this.#controlKeydownListener = null;
+        this.#skipNextBlur = false;
+        this.#idBase = `asljs-text-input-${nextTextInputId++}`;
+        this.#model = observable({ label: '',
+            description: '',
+            errorMessage: '',
+            hideLabel: true,
+            hideDescription: true,
+            hideError: true,
+            hasError: false,
+            isEmpty: true,
+            multiline: false,
+            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.#inputType_accessor_storage = 'text';
+        this.#controlClassName_accessor_storage = '';
+        this.#multiline_accessor_storage = false;
+        this.#autoExtend_accessor_storage = false;
+        this.#autoExtendMaxRows_accessor_storage = null;
+        this.#enterKeyBehavior_accessor_storage = 'finish';
+        this.#disabled_accessor_storage = false;
+        this.#rows_accessor_storage = 3;
+        this.#handleThemeChanged = () => {
+            this.#renderTemplate();
+        };
+    }
+    #templateElement;
+    #inputTemplateElement;
+    #textareaTemplateElement;
+    #templateDispose;
+    #controlTemplateDispose;
+    #themeProvider;
+    #control;
+    #controlBaseClassName;
+    #controlInvalidClassName;
+    #controlInputListener;
+    #controlBlurListener;
+    #controlKeydownListener;
+    #skipNextBlur;
+    #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; }
+    #inputType_accessor_storage;
+    get inputType() { return this.#inputType_accessor_storage; }
+    set inputType(value) { this.#inputType_accessor_storage = value; }
+    #controlClassName_accessor_storage;
+    get controlClassName() { return this.#controlClassName_accessor_storage; }
+    set controlClassName(value) { this.#controlClassName_accessor_storage = value; }
+    #multiline_accessor_storage;
+    get multiline() { return this.#multiline_accessor_storage; }
+    set multiline(value) { this.#multiline_accessor_storage = value; }
+    #autoExtend_accessor_storage;
+    get autoExtend() { return this.#autoExtend_accessor_storage; }
+    set autoExtend(value) { this.#autoExtend_accessor_storage = value; }
+    #autoExtendMaxRows_accessor_storage;
+    get autoExtendMaxRows() { return this.#autoExtendMaxRows_accessor_storage; }
+    set autoExtendMaxRows(value) { this.#autoExtendMaxRows_accessor_storage = value; }
+    #enterKeyBehavior_accessor_storage;
+    get enterKeyBehavior() { return this.#enterKeyBehavior_accessor_storage; }
+    set enterKeyBehavior(value) { this.#enterKeyBehavior_accessor_storage = value; }
+    #disabled_accessor_storage;
+    get disabled() { return this.#disabled_accessor_storage; }
+    set disabled(value) { this.#disabled_accessor_storage = value; }
+    #rows_accessor_storage;
+    get rows() { return this.#rows_accessor_storage; }
+    set rows(value) { this.#rows_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('multiline')
+            || changedProperties.has('theme')) {
+            this.#renderTemplate();
+            return;
+        }
+        if (changedProperties.has('placeholder')
+            || changedProperties.has('inputType')
+            || changedProperties.has('controlClassName')
+            || changedProperties.has('disabled')
+            || changedProperties.has('rows')
+            || changedProperties.has('autoExtend')
+            || changedProperties.has('autoExtendMaxRows')
+            || changedProperties.has('enterKeyBehavior')) {
+            this.#syncControlState();
+        }
+        this.#syncModelState();
+    }
+    #captureTemplates() {
+        this.#templateElement = null;
+        this.#inputTemplateElement = null;
+        this.#textareaTemplateElement = null;
+        this.#templateElement =
+            cloneNamedTemplate(this, 'template');
+        this.#inputTemplateElement =
+            cloneNamedTemplate(this, 'input');
+        this.#textareaTemplateElement =
+            cloneNamedTemplate(this, 'textarea');
+    }
+    #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() {
+        const nextValue = normalizeText(this.value);
+        this.status.draftValue = nextValue;
+        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.#model.multiline = this.multiline;
+        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)
+            ?? createDefaultTextInputTemplate();
+    }
+    #getLocalTemplate(slotName) {
+        switch (slotName) {
+            case 'template':
+                return this.#templateElement;
+            case 'input':
+                return this.#inputTemplateElement;
+            case 'textarea':
+                return this.#textareaTemplateElement;
+        }
+    }
+    #getThemeTemplate(slotName) {
+        const theme = this.theme
+            ?? this.#themeProvider?.theme
+            ?? getDefaultTheme();
+        return resolveThemeTemplate(slotName === 'template'
+            ? theme.textInput?.template
+            : slotName === 'input'
+                ? theme.textInput?.input
+                : theme.textInput?.textarea, this);
+    }
+    #mountControl() {
+        const controlHost = this.querySelector('[data-role="control-host"]');
+        if (controlHost === null) {
+            return;
+        }
+        const mountedControl = this.#createMountedControl(controlHost);
+        const control = mountedControl.control;
+        this.#controlTemplateDispose =
+            bindDataModel(mountedControl.fragment, this.#model);
+        controlHost.replaceChildren(mountedControl.fragment);
+        this.#control = control;
+        this.#controlBaseClassName =
+            mountedControl.className;
+        this.#controlInvalidClassName =
+            mountedControl.invalidClassName;
+        const inputListener = () => {
+            this.status.draftValue = control.value;
+            this.#syncModelState();
+            this.#dispatchValueEvent('input');
+        };
+        const blurListener = () => {
+            if (this.#skipNextBlur) {
+                this.#skipNextBlur = false;
+                return;
+            }
+            this.#dispatchValueEvent('change');
+        };
+        const keydownListener = (event) => {
+            const keyboardEvent = event;
+            if (keyboardEvent.key !== 'Enter') {
+                return;
+            }
+            if (this.multiline
+                && !keyboardEvent.ctrlKey
+                && !keyboardEvent.metaKey
+                && this.enterKeyBehavior
+                    === 'newline') {
+                return;
+            }
+            keyboardEvent.preventDefault();
+            this.#skipNextBlur = true;
+            this.#dispatchValueEvent('change');
+            control.blur();
+        };
+        control.addEventListener('input', inputListener);
+        control.addEventListener('blur', blurListener);
+        control.addEventListener('keydown', keydownListener);
+        this.#controlInputListener =
+            () => {
+                control.removeEventListener('input', inputListener);
+            };
+        this.#controlBlurListener =
+            () => {
+                control.removeEventListener('blur', blurListener);
+            };
+        this.#controlKeydownListener =
+            () => {
+                control.removeEventListener('keydown', keydownListener);
+            };
+        this.#syncControlState();
+    }
+    #syncControlState() {
+        const control = this.#control;
+        if (control === null) {
+            return;
+        }
+        if (control.value
+            !== this.status.draftValue) {
+            control.value =
+                this.status.draftValue;
+        }
+        control.id = this.#model.inputId;
+        control.placeholder =
+            normalizeOptionalText(this.placeholder) ?? '';
+        control.disabled = this.disabled;
+        control.className =
+            joinClassNames(this.#controlBaseClassName, this.controlClassName);
+        const invalidClassName = this.#controlInvalidClassName;
+        if (control instanceof HTMLInputElement) {
+            control.type = this.inputType;
+        }
+        if (invalidClassName !== null
+            && !this.status.isValid) {
+            control.classList.add(invalidClassName);
+        }
+        control.toggleAttribute('aria-invalid', !this.status.isValid);
+        control.setAttribute('aria-describedby', resolveAriaDescribedBy(this.#model));
+        if (this.multiline
+            && control instanceof HTMLTextAreaElement) {
+            control.rows =
+                Math.max(1, this.rows);
+            this.#syncAutoExtend(control);
+            return;
+        }
+        control.style.height = '';
+        control.style.overflowY = '';
+    }
+    #createMountedControl(controlHost) {
+        const slotName = this.multiline
+            ? 'textarea'
+            : 'input';
+        const template = this.#resolveTemplate(slotName);
+        if (template === null) {
+            return createFallbackMountedControl(this.multiline, controlHost);
+        }
+        const fragment = template.content.cloneNode(true);
+        const control = this.multiline
+            ? fragment.querySelector('textarea')
+            : fragment.querySelector('input');
+        if (control === null) {
+            return createFallbackMountedControl(this.multiline, controlHost);
+        }
+        return { fragment,
+            control,
+            className: resolveInitialControlClassName(control, controlHost),
+            invalidClassName: resolveInitialControlInvalidClassName(control, controlHost) };
+    }
+    #syncAutoExtend(control) {
+        if (!this.autoExtend) {
+            control.style.height = '';
+            control.style.overflowY = '';
+            return;
+        }
+        control.style.height = 'auto';
+        const maxHeight = resolveMaxHeight(control, this.autoExtendMaxRows);
+        const nextHeight = maxHeight === null
+            ? control.scrollHeight
+            : Math.min(control.scrollHeight, maxHeight);
+        control.style.height = `${nextHeight}px`;
+        control.style.overflowY =
+            maxHeight !== null && control.scrollHeight > maxHeight
+                ? 'auto'
+                : 'hidden';
+    }
+    #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.#controlInputListener?.();
+        this.#controlBlurListener?.();
+        this.#controlKeydownListener?.();
+        this.#controlInputListener = null;
+        this.#controlBlurListener = null;
+        this.#controlKeydownListener = null;
+        this.#control = null;
+        this.#controlBaseClassName = '';
+        this.#controlInvalidClassName = null;
+        this.#controlTemplateDispose?.();
+        this.#controlTemplateDispose = null;
+    }
+};
+__decorate([
+    property({ attribute: false })
+], TextInput.prototype, "label", null);
+__decorate([
+    property({ attribute: false })
+], TextInput.prototype, "description", null);
+__decorate([
+    property({ attribute: false })
+], TextInput.prototype, "validator", null);
+__decorate([
+    property({ attribute: false })
+], TextInput.prototype, "theme", null);
+__decorate([
+    property({ attribute: false })
+], TextInput.prototype, "value", null);
+__decorate([
+    property({ attribute: false })
+], TextInput.prototype, "placeholder", null);
+__decorate([
+    property({ attribute: false })
+], TextInput.prototype, "inputType", null);
+__decorate([
+    property({ attribute: false })
+], TextInput.prototype, "controlClassName", null);
+__decorate([
+    property({ attribute: false })
+], TextInput.prototype, "multiline", null);
+__decorate([
+    property({ attribute: false })
+], TextInput.prototype, "autoExtend", null);
+__decorate([
+    property({ attribute: false })
+], TextInput.prototype, "autoExtendMaxRows", null);
+__decorate([
+    property({ attribute: false })
+], TextInput.prototype, "enterKeyBehavior", null);
+__decorate([
+    property({ attribute: false })
+], TextInput.prototype, "disabled", null);
+__decorate([
+    property({ attribute: false })
+], TextInput.prototype, "rows", null);
+TextInput = __decorate([
+    customElement('asljs-text-input')
+], TextInput);
+export { TextInput };
+let nextTextInputId = 1;
+function normalizeText(value) {
+    return value ?? '';
+}
+function normalizeOptionalText(value) {
+    if (value === null
+        || value === undefined
+        || value === '') {
+        return null;
+    }
+    return value;
+}
+function resolveAriaDescribedBy(model) {
+    const ids = [];
+    if (!model.hideDescription) {
+        ids.push(model.descriptionId);
+    }
+    if (!model.hideError) {
+        ids.push(model.errorId);
+    }
+    return ids.join(' ');
+}
+function resolveMaxHeight(control, maxRows) {
+    if (maxRows === null
+        || maxRows <= 0) {
+        return null;
+    }
+    const computed = getComputedStyle(control);
+    const lineHeight = parseFloat(computed.lineHeight);
+    if (!Number.isFinite(lineHeight)
+        || lineHeight <= 0) {
+        return null;
+    }
+    const borderTop = parseFloat(computed.borderTopWidth) || 0;
+    const borderBottom = parseFloat(computed.borderBottomWidth) || 0;
+    const paddingTop = parseFloat(computed.paddingTop) || 0;
+    const paddingBottom = parseFloat(computed.paddingBottom) || 0;
+    return lineHeight * maxRows
+        + paddingTop
+        + paddingBottom
+        + borderTop
+        + borderBottom;
+}
+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 createDefaultTextInputTemplate() {
+    return createTemplate();
+}
+function createSingleLineInput() {
+    const input = document.createElement('input');
+    input.type = 'text';
+    return input;
+}
+function createDefaultInputTemplate() {
+    const template = document.createElement('template');
+    template.innerHTML =
+        '<input type="text">';
+    return template;
+}
+function createDefaultTextareaTemplate() {
+    const template = document.createElement('template');
+    template.innerHTML =
+        '<textarea></textarea>';
+    return template;
+}
+function createFallbackMountedControl(multiline, controlHost) {
+    const fragment = document.createDocumentFragment();
+    const template = multiline
+        ? createDefaultTextareaTemplate()
+        : createDefaultInputTemplate();
+    const templateFragment = template.content.cloneNode(true);
+    const control = multiline
+        ? templateFragment.querySelector('textarea')
+        : templateFragment.querySelector('input');
+    if (control === null) {
+        const fallbackControl = multiline
+            ? document.createElement('textarea')
+            : createSingleLineInput();
+        fragment.append(fallbackControl);
+        return { fragment,
+            control: fallbackControl,
+            className: resolveInitialControlClassName(fallbackControl, controlHost),
+            invalidClassName: resolveInitialControlInvalidClassName(fallbackControl, controlHost) };
+    }
+    fragment.append(templateFragment);
+    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/text-input.tpl.d.ts

@@ -0,0 +1,6 @@
+import { type BindDataModelOptions } from "asljs-data-binding";
+import type { TextInputTemplateModel as TemplateModel } from "./text-input.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/text-input.tpl.js

@@ -0,0 +1,26 @@
+// Generated by data-bind-compile from text-input.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; // text-input.tpl.html:4:12 data-bind-text
+    void model.hideLabel; // text-input.tpl.html:5:12 data-bind-prop-hidden
+    void model.inputId; // text-input.tpl.html:6:12 data-bind-for
+    void model.description; // text-input.tpl.html:9:10 data-bind-text
+    void model.hideDescription; // text-input.tpl.html:10:10 data-bind-prop-hidden
+    void model.descriptionId; // text-input.tpl.html:11:10 data-bind-prop-id
+    void model.errorMessage; // text-input.tpl.html:13:10 data-bind-text
+    void model.hideError; // text-input.tpl.html:14:10 data-bind-prop-hidden
+    void model.errorId; // text-input.tpl.html:15:10 data-bind-prop-id
+}
+void check;

package/dist/theme.d.ts

@@ -0,0 +1,13 @@
+import { type ComponentsTheme, type ThemeTemplateValue } from 'asljs-ui';
+export interface TextInputThemeDefinition {
+    template?: ThemeTemplateValue;
+    input?: ThemeTemplateValue;
+    textarea?: ThemeTemplateValue;
+}
+declare module 'asljs-ui' {
+    interface ComponentsTheme {
+        textInput?: TextInputThemeDefinition;
+    }
+}
+/** The Bootstrap text input section. */
+export declare function createBootstrapTextInputTheme(): ComponentsTheme;

package/dist/theme.js

@@ -0,0 +1,14 @@
+import { html as textInputTemplate } from './bootstrap-text-input.tpl.js';
+/** The Bootstrap text input section. */
+export function createBootstrapTextInputTheme() {
+    return { textInput: { template: textInputTemplate,
+            input: `
+            <input type="text"
+                   class="form-control"
+                   data-control-invalid-class="is-invalid">
+          `,
+            textarea: `
+            <textarea class="form-control"
+                      data-control-invalid-class="is-invalid"></textarea>
+          ` } };
+}

package/docs/Text Input.md

@@ -0,0 +1,112 @@
+# Text Input
+
+`asljs-text-input` is a labelled text field or textarea with validation.
+
+## Properties
+
+- `value` — the external set/reset value
+- `label`
+- `description`
+- `placeholder`
+- `validator` — returns an error message or `null`
+- `multiline` — renders a textarea instead of an input
+- `enterKeyBehavior` — `finish` or `newline`
+- `autoExtend` and `autoExtendMaxRows` — textarea growth
+- `theme`
+- local `template[data-slot="template"]`, `template[data-slot="input"]` and
+  `template[data-slot="textarea"]`
+
+`value` is a set/reset input, not the live draft. User edits are kept in
+`draftValue`, reflected in the observable `status` object, and emitted through
+`input` and `change` events whose detail reports the draft value, validity and
+dirty state. Listen for those events and decide whether to persist or reset.
+
+## Usage
+
+```ts
+import 'asljs-ui-text-input';
+
+const textInput =
+  document.createElement('asljs-text-input') as HTMLElement & {
+    label: string | null;
+    description: string | null;
+    value: string | null;
+    placeholder: string | null;
+    validator: ((value: string) => string | null) | null;
+    multiline: boolean;
+    enterKeyBehavior: 'finish' | 'newline';
+    autoExtend: boolean;
+    autoExtendMaxRows: number | null;
+  };
+
+textInput.label = 'Summary';
+textInput.description = 'Ctrl+Enter always finishes editing.';
+textInput.placeholder = 'Write a short summary';
+textInput.multiline = true;
+textInput.enterKeyBehavior = 'newline';
+textInput.autoExtend = true;
+textInput.autoExtendMaxRows = 8;
+textInput.validator =
+  value => value.trim() === ''
+    ? 'Summary is required.'
+    : null;
+textInput.value = 'Initial text';
+
+textInput.addEventListener(
+  'change',
+  event => {
+    const detail =
+      (event as CustomEvent<{
+        value: string;
+        isValid: boolean;
+      }>).detail;
+
+    console.log(detail.value, detail.isValid);
+  });
+```
+
+## Template overrides
+
+Provide a local `template[data-slot="template"]` when the layout must differ
+from the Bootstrap-oriented default. The template can use any supported
+`asljs-data-binding` attributes, but it must include
+`[data-role="control-host"]` so the component can mount the actual `input` or
+`textarea`.
+
+```html
+<asljs-text-input>
+  <template data-slot="template">
+    <div class="editor-field">
+      <div data-role="control-host"></div>
+      <small data-bind-text="description"
+             data-bind-prop-hidden="hideDescription"></small>
+      <div class="error"
+           data-bind-text="errorMessage"
+           data-bind-prop-hidden="hideError"></div>
+    </div>
+  </template>
+</asljs-text-input>
+```
+
+Provide `template[data-slot="input"]` or `template[data-slot="textarea"]` when
+the native control markup itself must come from the local component or theme.
+The slot must include the matching native control element, but wrapper markup
+around it is allowed. Control templates can also use `asljs-data-binding`
+attributes, for example to place validation feedback next to the real control.
+
+```html
+<asljs-text-input>
+  <template data-slot="input">
+    <div class="field-shell">
+      <input class="field-control"
+             data-control-invalid-class="field-control-invalid">
+    </div>
+  </template>
+</asljs-text-input>
+```
+
+Themes can supply the same templates, in the `textInput` section;
+`createBootstrapTextInputTheme()` supplies Bootstrap form markup. See
+[Theming][THM].
+
+[THM]: ../../core/docs/Theming.md

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "asljs-ui-text-input",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "A text field or textarea 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",
+    "input",
+    "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"
+  }
+}