@getaster/elements 0.0.0-stage → 0.1.0-preview.1

package/dist/field/bound-field.d.ts

@@ -0,0 +1,55 @@
+import type { EditModel, Field as FieldMeta, FieldState, Value } from "@getaster/data";
+import { AsterElement, type View } from "../base/element.ts";
+/** What a control needs to render itself inside a bound field. */
+export interface ControlContext {
+    readonly id: string;
+    readonly name: string;
+    readonly meta: FieldMeta | undefined;
+    readonly value: Value | undefined;
+    readonly state: FieldState;
+    /** `aria-describedby` for the control: the error, then the read-only reason. */
+    readonly describedBy: string | undefined;
+    readonly invalid: boolean;
+    readonly label: string;
+}
+/**
+ * A control bound to one field of an edit model, with what every field
+ * shows: its label and required marker, pending styling and a revert, the
+ * read-only reason, and the error under it.
+ *
+ * The field's state (from metadata and page rules) decides: a hidden field
+ * renders nothing and a read-only one shows its reason. Most fields are
+ * required, so the label marks the optional ones; the control carries
+ * `aria-required` either way.
+ * Pending is the model's: the value differs from the baseline, or it's forced.
+ * A value the server hides on this record shows as a read-only box saying
+ * "Hidden", whatever the control, with the reason as its description.
+ */
+export declare abstract class BoundField extends AsterElement {
+    #private;
+    get model(): EditModel | undefined;
+    set model(v: EditModel | undefined);
+    get field(): string;
+    set field(v: string);
+    /** The label; defaults to the field's title from metadata. */
+    get label(): string;
+    set label(v: string);
+    /** Show the label above the control. Otherwise it's the accessible name only. */
+    get labelled(): boolean;
+    set labelled(v: boolean);
+    /**
+     * Reasons shown once for several fields, by the id of the element that
+     * shows them; such a reason isn't repeated here, only referenced.
+     */
+    get sharedReasons(): ReadonlyMap<string, string>;
+    set sharedReasons(v: ReadonlyMap<string, string>);
+    protected abstract control(c: ControlContext): View;
+    /** Control-specific validation supplements the model's errors. */
+    protected validation(_meta: FieldMeta | undefined, _value: Value | undefined): string | undefined;
+    /** The frame and anything beside it; a subclass can wrap the control. */
+    protected row(c: ControlContext): View;
+    /** A value as words, for the revert's label; a picker names the record. */
+    protected describe(meta: FieldMeta | undefined, value: Value | undefined): string;
+    protected write(value: Value): void;
+    protected render(): View;
+}

package/dist/field/bound-field.js

@@ -0,0 +1,139 @@
+import { DEFAULT_STATE } from "@getaster/data";
+import { html, nothing } from "lit-html";
+import { AsterElement, uid } from "../base/element.js";
+import { formatValue } from "./values.js";
+/**
+ * A control bound to one field of an edit model, with what every field
+ * shows: its label and required marker, pending styling and a revert, the
+ * read-only reason, and the error under it.
+ *
+ * The field's state (from metadata and page rules) decides: a hidden field
+ * renders nothing and a read-only one shows its reason. Most fields are
+ * required, so the label marks the optional ones; the control carries
+ * `aria-required` either way.
+ * Pending is the model's: the value differs from the baseline, or it's forced.
+ * A value the server hides on this record shows as a read-only box saying
+ * "Hidden", whatever the control, with the reason as its description.
+ */
+export class BoundField extends AsterElement {
+    #model = this.prop(undefined);
+    #field = this.prop("");
+    #label = this.prop("");
+    #labelled = this.prop(false);
+    #shared = this.prop(new Map());
+    #uid = uid("aster-field");
+    get model() {
+        return this.#model.value;
+    }
+    set model(v) {
+        this.#model.value = v;
+    }
+    get field() {
+        return this.#field.value;
+    }
+    set field(v) {
+        this.#field.value = v;
+    }
+    /** The label; defaults to the field's title from metadata. */
+    get label() {
+        return this.#label.value;
+    }
+    set label(v) {
+        this.#label.value = v;
+    }
+    /** Show the label above the control. Otherwise it's the accessible name only. */
+    get labelled() {
+        return this.#labelled.value;
+    }
+    set labelled(v) {
+        this.#labelled.value = v;
+    }
+    /**
+     * Reasons shown once for several fields, by the id of the element that
+     * shows them; such a reason isn't repeated here, only referenced.
+     */
+    get sharedReasons() {
+        return this.#shared.value;
+    }
+    set sharedReasons(v) {
+        this.#shared.value = v;
+    }
+    /** Control-specific validation supplements the model's errors. */
+    validation(_meta, _value) { return undefined; }
+    /** The frame and anything beside it; a subclass can wrap the control. */
+    row(c) {
+        return this.control(c);
+    }
+    /** A value as words, for the revert's label; a picker names the record. */
+    describe(meta, value) {
+        return formatValue(meta, value);
+    }
+    #hiddenValue(c) {
+        return html `<label class="aster-field aster-field-hidden" data-ring-owner>
+      <input id=${c.id} type="text" readonly .value=${""} placeholder="Hidden"
+        aria-label=${this.#labelled.value ? nothing : c.label}
+        aria-describedby=${c.describedBy ?? nothing}>
+    </label>`;
+    }
+    write(value) {
+        this.#model.peek()?.set(this.#field.peek(), value);
+    }
+    render() {
+        const model = this.#model.value;
+        const name = this.#field.value;
+        const meta = model?.type.field(name);
+        const state = model && meta ? model.state(name).value : DEFAULT_STATE;
+        this.hidden = !state.visible;
+        if (!state.visible)
+            return nothing;
+        const hidden = model?.hidden.value.has(name) ?? false;
+        const error = model?.errors.value[name]?.[0] ?? this.validation(meta, model?.values.value[name]);
+        const pending = model && meta ? model.pending(name).value : false;
+        const reason = state.readOnly ? state.reasons.readOnly : undefined;
+        const sharedId = reason === undefined ? undefined : this.#shared.value.get(reason);
+        const errorId = `${this.#uid}-error`;
+        const reasonId = sharedId ?? `${this.#uid}-reason`;
+        const pendingId = `${this.#uid}-pending`;
+        const suggestedId = `${this.#uid}-suggested`;
+        const suggested = !hidden && !state.readOnly && (model?.derived(name).value ?? false);
+        // A new record's fields aren't "changed"; a new list row says it's new in its first cell. A replay says what its change did.
+        const replay = model?.replaying ?? false;
+        const changed = pending && (replay || !model?.isNew.value);
+        const label = this.#label.value || meta?.title || name;
+        const c = {
+            id: this.#uid,
+            name,
+            meta,
+            value: model?.values.value[name],
+            state,
+            describedBy: [error ? errorId : "", reason ? reasonId : "", changed ? pendingId : "", suggested ? suggestedId : ""].filter(Boolean).join(" ") || undefined,
+            invalid: error !== undefined,
+            label,
+        };
+        this.toggleAttribute("data-pending", pending);
+        this.toggleAttribute("data-readonly", state.readOnly);
+        this.toggleAttribute("data-value-hidden", hidden);
+        this.toggleAttribute("data-suggested", suggested);
+        const was = this.describe(meta, model?.baseline.value[name]) || "empty";
+        // Pending is drawn as a dot and an edge; this says it in words.
+        const added = replay && (model?.baseline.value[name] ?? null) === null && model?.values.value[name] !== undefined && Object.keys(model.baseline.value).length === 0;
+        const pendingText = !replay ? `Changed, not saved yet; was ${was}` : added ? "Added in this change" : `Changed in this change; was ${was}`;
+        const revert = pending && !state.readOnly && !model?.isNew.value
+            ? html `<button type="button" class="aster-revert" title=${`Was ${was}`}
+            aria-label=${`Revert ${label} to ${was}`}
+            @click=${() => model?.revert(name)}>Revert</button>`
+            : nothing;
+        return html `${this.#labelled.value
+            ? html `<div class="aster-field-head">
+            <label class="aster-field-label" id=${`${this.#uid}-label`} for=${this.#uid}>${label}</label>
+            ${meta && !state.required && !state.readOnly ? html `<span class="aster-optional">Optional</span>` : nothing}
+            ${revert}
+          </div>`
+            : nothing}
+      ${hidden ? this.#hiddenValue(c) : this.row(c)}
+      ${suggested ? html `<p class="aster-hint" id=${suggestedId}>Suggested value</p>` : nothing}
+      ${changed ? html `<span class="aster-sr-only" id=${pendingId}>${pendingText}</span>` : nothing}
+      ${reason && !sharedId ? html `<p class="aster-hint" id=${reasonId}>${reason}</p>` : nothing}
+      ${error ? html `<p class="aster-error" id=${errorId} role="alert">${error}</p>` : nothing}`;
+    }
+}

package/dist/field/check.d.ts

@@ -0,0 +1,11 @@
+import { type View } from "../base/element.ts";
+import { BoundField, type ControlContext } from "./bound-field.ts";
+/**
+ * A Boolean field as a checkbox. A null shows as mixed until set. Read-only
+ * keeps it focusable, so its reason can be reached: it's `aria-readonly`
+ * and a click doesn't change it.
+ */
+export declare class Check extends BoundField {
+    focus(options?: FocusOptions): void;
+    protected control(c: ControlContext): View;
+}

package/dist/field/check.js

@@ -0,0 +1,26 @@
+import { html, nothing } from "lit-html";
+import { define } from "../base/element.js";
+import { BoundField } from "./bound-field.js";
+/**
+ * A Boolean field as a checkbox. A null shows as mixed until set. Read-only
+ * keeps it focusable, so its reason can be reached: it's `aria-readonly`
+ * and a click doesn't change it.
+ */
+export class Check extends BoundField {
+    focus(options) {
+        this.querySelector("input")?.focus(options);
+    }
+    control(c) {
+        return html `<label class="aster-check">
+      <input id=${c.id} type="checkbox" .checked=${c.value === true} .indeterminate=${c.value === null || c.value === undefined}
+        aria-label=${this.labelled ? nothing : c.label}
+        aria-readonly=${c.state.readOnly ? "true" : nothing}
+        aria-required=${c.state.required ? "true" : nothing}
+        @click=${(e) => c.state.readOnly && e.preventDefault()}
+        aria-invalid=${c.invalid ? "true" : nothing}
+        aria-describedby=${c.describedBy ?? nothing}
+        @change=${(e) => this.write(e.target.checked)}>
+    </label>`;
+    }
+}
+define("aster-check", Check);

package/dist/field/composite-field.d.ts

@@ -0,0 +1,35 @@
+import type { EditModel } from "@getaster/data";
+import { AsterElement, type View } from "../base/element.ts";
+export interface CompositeFieldContext<T = unknown> {
+    readonly value: T;
+    readonly disabled: boolean;
+    readonly readOnly: boolean;
+    readonly commit: (value: T) => void;
+}
+/** Related editors retain their own model fields, or edit an explicit application value. */
+export declare class CompositeField<T = unknown> extends AsterElement {
+    #private;
+    get model(): EditModel | undefined;
+    set model(v: EditModel | undefined);
+    get fields(): readonly string[];
+    set fields(v: readonly string[]);
+    get label(): string;
+    set label(v: string);
+    get help(): string;
+    set help(v: string);
+    get error(): string;
+    set error(v: string);
+    get disabled(): boolean;
+    set disabled(v: boolean);
+    get readOnly(): boolean;
+    set readOnly(v: boolean);
+    get content(): View;
+    set content(v: View);
+    get value(): T | undefined;
+    set value(v: T | undefined);
+    get renderValue(): ((context: CompositeFieldContext<T | undefined>) => View) | undefined;
+    set renderValue(v: ((context: CompositeFieldContext<T | undefined>) => View) | undefined);
+    focus(options?: FocusOptions): void;
+    revert(): void;
+    protected render(): View;
+}

package/dist/field/composite-field.js

@@ -0,0 +1,88 @@
+import { batch } from "@preact/signals-core";
+import { html, nothing } from "lit-html";
+import { AsterElement, define, uid } from "../base/element.js";
+/** Related editors retain their own model fields, or edit an explicit application value. */
+export class CompositeField extends AsterElement {
+    #model = this.prop(undefined);
+    #fields = this.prop([]);
+    #label = this.prop("");
+    #help = this.prop("");
+    #error = this.prop("");
+    #disabled = this.prop(false);
+    #readOnly = this.prop(false);
+    #content = this.prop(nothing);
+    #value = this.prop(undefined);
+    #renderer = this.prop(undefined);
+    #id = uid("aster-composite-field");
+    get model() { return this.#model.value; }
+    set model(v) { this.#validate(this.#fields.peek(), v); this.#model.value = v; }
+    get fields() { return this.#fields.value; }
+    set fields(v) { this.#validate(v, this.#model.peek()); this.#fields.value = [...v]; }
+    get label() { return this.#label.value; }
+    set label(v) { this.#label.value = v; }
+    get help() { return this.#help.value; }
+    set help(v) { this.#help.value = v; }
+    get error() { return this.#error.value; }
+    set error(v) { this.#error.value = v; }
+    get disabled() { return this.#disabled.value; }
+    set disabled(v) { this.#disabled.value = v; }
+    get readOnly() { return this.#readOnly.value; }
+    set readOnly(v) { this.#readOnly.value = v; }
+    get content() { return this.#content.value; }
+    set content(v) { this.#content.value = v; }
+    get value() { return this.#value.value; }
+    set value(v) { this.#value.value = v; }
+    get renderValue() { return this.#renderer.value; }
+    set renderValue(v) { this.#renderer.value = v; }
+    focus(options) {
+        if (this.#disabled.peek())
+            return;
+        (this.querySelector("[aria-invalid=true]:not([disabled])") ?? this.querySelector("input:not([readonly]):not([disabled]),textarea:not([readonly]):not([disabled]),select:not([disabled]),button:not([disabled])"))?.focus(options);
+    }
+    revert() {
+        const model = this.#model.peek();
+        if (!model || this.#disabled.peek() || this.#readOnly.peek())
+            return;
+        batch(() => {
+            for (const name of this.#fields.peek()) {
+                const state = model.state(name).peek();
+                if (state.visible && !state.readOnly && !model.hidden.peek().has(name)) {
+                    model.revert(name);
+                    model.forcePending(name, false);
+                }
+            }
+        });
+    }
+    #validate(fields, model) {
+        if (new Set(fields).size !== fields.length || fields.some(f => !f || model && !model.type.field(f)))
+            throw new TypeError("CompositeField fields must be unique model field names");
+    }
+    render() {
+        const model = this.#model.value;
+        const fields = this.#fields.value;
+        const states = fields.map(f => model?.state(f).value);
+        this.hidden = !!model && fields.length > 0 && states.every(s => !s?.visible);
+        if (this.hidden)
+            return nothing;
+        const pending = fields.some(f => model?.pending(f).value);
+        this.toggleAttribute("data-group-pending", pending);
+        const disabled = this.#disabled.value;
+        const readOnly = this.#readOnly.value;
+        const error = this.#error.value;
+        const renderer = this.#renderer.value;
+        const descriptions = [this.#help.value ? `${this.#id}-help` : "", error ? `${this.#id}-error` : ""].filter(Boolean).join(" ");
+        return html `<fieldset class="aster-composite-field" ?disabled=${disabled || readOnly && !renderer} aria-describedby=${descriptions || nothing}>
+      <legend>${this.#label.value}</legend>
+      ${this.#help.value ? html `<p class="aster-hint" id=${`${this.#id}-help`}>${this.#help.value}</p>` : nothing}
+      <div class="aster-composite-content">${renderer ? renderer({ value: this.#value.value, disabled, readOnly, commit: value => {
+                if (this.#disabled.peek() || this.#readOnly.peek())
+                    return;
+                this.#value.value = value;
+                this.emit("value-change", { value });
+            } }) : this.#content.value}</div>
+      ${pending && !disabled && !readOnly ? html `<button type="button" class="aster-revert" aria-label=${`Revert ${this.#label.value}`} @click=${() => this.revert()}>Revert group</button>` : nothing}
+      ${error ? html `<p class="aster-error" role="alert" id=${`${this.#id}-error`}>${error}</p>` : nothing}
+    </fieldset>`;
+    }
+}
+define("aster-composite-field", CompositeField);

package/dist/field/field.d.ts

@@ -0,0 +1,29 @@
+import { type View } from "../base/element.ts";
+import { BoundField, type ControlContext } from "./bound-field.ts";
+/**
+ * A text field. Bound to an edit model's field, it shows that field's value
+ * and writes every keystroke back, parsed by the field's type (numbers,
+ * decimals, dates); text that doesn't parse stays as typed, and validation
+ * says what's wrong. Without a model it shows `value`, and `readOnly`
+ * selects everything on focus.
+ *
+ * The frame owns the focus ring. `trailing` renders beside the frame (an
+ * Invite button), so the error still spans under both.
+ */
+export declare class Field extends BoundField {
+    #private;
+    get value(): string;
+    set value(v: string);
+    get placeholder(): string;
+    set placeholder(v: string);
+    get readOnly(): boolean;
+    set readOnly(v: boolean);
+    /** The `inputmode` to offer, when the field's type doesn't say (a number kept as text). */
+    get keyboard(): string;
+    set keyboard(v: string);
+    get trailing(): View;
+    set trailing(v: View);
+    focus(options?: FocusOptions): void;
+    protected row(c: ControlContext): View;
+    protected control(c: ControlContext): View;
+}

package/dist/field/field.js

@@ -0,0 +1,75 @@
+import { html, nothing } from "lit-html";
+import { inputView } from "./input.js";
+import { define } from "../base/element.js";
+import { BoundField } from "./bound-field.js";
+import { formatValue, inputKind, parseInput } from "./values.js";
+/**
+ * A text field. Bound to an edit model's field, it shows that field's value
+ * and writes every keystroke back, parsed by the field's type (numbers,
+ * decimals, dates); text that doesn't parse stays as typed, and validation
+ * says what's wrong. Without a model it shows `value`, and `readOnly`
+ * selects everything on focus.
+ *
+ * The frame owns the focus ring. `trailing` renders beside the frame (an
+ * Invite button), so the error still spans under both.
+ */
+export class Field extends BoundField {
+    #value = this.prop("");
+    #placeholder = this.prop("");
+    #readonly = this.prop(false);
+    #trailing = this.prop(nothing);
+    #keyboard = this.prop("");
+    get value() {
+        return this.#value.value;
+    }
+    set value(v) {
+        this.#value.value = v;
+    }
+    get placeholder() {
+        return this.#placeholder.value;
+    }
+    set placeholder(v) {
+        this.#placeholder.value = v;
+    }
+    get readOnly() {
+        return this.#readonly.value;
+    }
+    set readOnly(v) {
+        this.#readonly.value = v;
+    }
+    /** The `inputmode` to offer, when the field's type doesn't say (a number kept as text). */
+    get keyboard() {
+        return this.#keyboard.value;
+    }
+    set keyboard(v) {
+        this.#keyboard.value = v;
+    }
+    get trailing() {
+        return this.#trailing.value;
+    }
+    set trailing(v) {
+        this.#trailing.value = v;
+    }
+    focus(options) {
+        this.querySelector("input, textarea")?.focus(options);
+    }
+    row(c) {
+        return html `<div class="aster-field-row">${this.control(c)}${this.#trailing.value}</div>`;
+    }
+    control(c) {
+        const bound = this.model !== undefined;
+        // While typing, a Decimal shows exactly what was typed, not padded to its scale.
+        const text = bound ? (typeof c.value === "string" && c.meta?.type === "Edm.Decimal" ? c.value : formatValue(c.meta, c.value)) : this.#value.value;
+        const readOnly = this.#readonly.value || c.state.readOnly;
+        const kind = inputKind(c.meta);
+        return inputView({ id: c.id, value: text, type: kind.type, keyboard: this.#keyboard.value || kind.inputmode || "",
+            ...(this.labelled ? {} : { label: c.label }), placeholder: this.#placeholder.value, readOnly, required: c.state.required,
+            invalid: c.invalid, ...(c.describedBy ? { describedBy: c.describedBy } : {}), ...(isProse(c.meta) ? { rows: 2 } : {}),
+            input: (text) => this.write(parseInput(c.meta, text)) });
+    }
+}
+/** Long text (over 500 characters allowed) edits in a textarea that grows with it. */
+function isProse(field) {
+    return field?.type === "Edm.String" && !field.allowedValues && (field.maxLength ?? 0) > 500;
+}
+define("aster-field", Field);

package/dist/field/input.d.ts

@@ -0,0 +1,15 @@
+/** Scalar input chrome shared by record fields and standalone query drafts. */
+export declare function inputView(p: {
+    readonly value: string;
+    readonly input: (text: string) => void;
+    readonly id?: string;
+    readonly label?: string;
+    readonly type?: string;
+    readonly keyboard?: string;
+    readonly placeholder?: string;
+    readonly readOnly?: boolean;
+    readonly required?: boolean;
+    readonly invalid?: boolean;
+    readonly describedBy?: string;
+    readonly rows?: number;
+}): import("lit-html").TemplateResult<1>;

package/dist/field/input.js

@@ -0,0 +1,18 @@
+import { html, nothing } from "lit-html";
+import { live } from "lit-html/directives/live.js";
+/** Scalar input chrome shared by record fields and standalone query drafts. */
+export function inputView(p) {
+    return html `<label class=${p.rows ? "aster-field aster-field-prose" : "aster-field"} data-ring-owner>
+    ${p.rows ? html `<textarea id=${p.id ?? nothing} rows=${p.rows} .value=${live(p.value)}
+      aria-label=${p.label ?? nothing} placeholder=${p.placeholder || nothing} ?readonly=${p.readOnly}
+      aria-required=${p.required ? "true" : nothing} aria-invalid=${p.invalid ? "true" : nothing}
+      aria-describedby=${p.describedBy ?? nothing}
+      @input=${(e) => p.input(e.target.value)}></textarea>`
+        : html `<input id=${p.id ?? nothing} type=${p.type ?? "text"} inputmode=${p.keyboard || nothing} .value=${live(p.value)}
+        aria-label=${p.label ?? nothing} placeholder=${p.placeholder || nothing} ?readonly=${p.readOnly}
+        aria-required=${p.required ? "true" : nothing} aria-invalid=${p.invalid ? "true" : nothing}
+        aria-describedby=${p.describedBy ?? nothing} autocomplete="off" spellcheck="false"
+        @focus=${(e) => p.readOnly && e.target.select()}
+        @input=${(e) => p.input(e.target.value)}>`}
+  </label>`;
+}

package/dist/field/number-field.d.ts

@@ -0,0 +1,33 @@
+import type { Field as FieldMeta, Value } from "@getaster/data";
+import { type View } from "../base/element.ts";
+import { BoundField, type ControlContext } from "./bound-field.ts";
+export type NumericValue = string | number | null;
+export type NumericType = "decimal" | "integer" | "float";
+export declare class NumberField extends BoundField {
+    #private;
+    get value(): NumericValue;
+    set value(v: NumericValue);
+    get numericType(): NumericType;
+    set numericType(v: NumericType);
+    get min(): string | number | undefined;
+    set min(v: string | number | undefined);
+    get max(): string | number | undefined;
+    set max(v: string | number | undefined);
+    get step(): string | number | undefined;
+    set step(v: string | number | undefined);
+    get stepButtons(): boolean;
+    set stepButtons(v: boolean);
+    get prefixText(): string;
+    set prefixText(v: string);
+    get suffixText(): string;
+    set suffixText(v: string);
+    get placeholder(): string;
+    set placeholder(v: string);
+    get readOnly(): boolean;
+    set readOnly(v: boolean);
+    get format(): ((value: NumericValue) => string) | undefined;
+    set format(v: ((value: NumericValue) => string) | undefined);
+    focus(options?: FocusOptions): void;
+    protected validation(meta: FieldMeta | undefined, boundValue: Value | undefined): string | undefined;
+    protected control(c: ControlContext): View;
+}