@aceshooting/lyra-ui 2.0.0 → 2.2.0

package/dist/components/tool-param-form/tool-param-form.class.d.ts

@@ -0,0 +1,216 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+import '../select/select.class.js';
+import '../combobox/option.class.js';
+import '../checkbox/checkbox.class.js';
+/** The four leaf property types this flat-schema renderer understands. */
+export type ToolParamFormPropertyType = 'string' | 'number' | 'integer' | 'boolean';
+export type ToolParamFormPrimitive = string | number | boolean;
+/**
+ * One `schema.properties` entry. Deliberately shallow — see the class doc for
+ * the full scope limitation this type encodes.
+ */
+export interface ToolParamFormProperty {
+    type: ToolParamFormPropertyType;
+    /** A closed set of string choices, rendered as a `<lyra-select>`. Only meaningful when `type` is `'string'`. */
+    enum?: string[];
+    /** Helper text rendered under the field. */
+    description?: string;
+    /** Display label. Falls back to the property key itself when omitted. */
+    title?: string;
+    /** Pre-filled value used whenever `value` doesn't already have this key. */
+    default?: unknown;
+    /** Exact primitive value required when the property is present. */
+    const?: ToolParamFormPrimitive;
+}
+/**
+ * The (intentionally flat) JSON Schema subset this component can render:
+ * a plain object whose every property is a string, number/integer, boolean,
+ * or string enum. See the class doc for what's out of scope.
+ */
+export interface ToolParamFormSchema {
+    type: 'object';
+    properties: Record<string, ToolParamFormProperty>;
+    required?: string[];
+}
+/**
+ * `<lyra-tool-param-form>` — renders one form control per top-level property
+ * of a JSON Schema object, for ad hoc tool invocation or approval-editing UIs
+ * (e.g. "the agent wants to call `create_event(title, attendees, allDay)` —
+ * let the user tweak the arguments before running it").
+ *
+ * **Scope limitation (intentional, not accidental):** this renderer only
+ * understands a *flat* object schema — every `properties` entry must be
+ * `'string'`, `'number'`, `'integer'`, `'boolean'`, or a string `enum`;
+ * primitive `const` is also enforced. Nested objects, arrays,
+ * `oneOf`/`anyOf`/`allOf`, `$ref`, constraints such as `minLength`/`minimum`,
+ * and schema-valued `additionalProperties` are not read. A full
+ * JSON-Schema-to-form renderer is
+ * out of scope for this component; a property whose `type` isn't one of the
+ * four above renders a visible "Unsupported field type" note and marks the
+ * form invalid instead of silently dropping it or throwing.
+ *
+ * Fields render in `Object.keys(schema.properties)` order (insertion order,
+ * which is reliable for a plain object's string keys). A field's label is
+ * `title ?? ` the property key; `description` renders as helper text below
+ * the control; a key listed in `required` gets a visible `*`. The outer
+ * component owns validation because JSON Schema `required` means property
+ * presence, unlike HTML controls' nonempty/must-check semantics.
+ *
+ * This component owns no Submit/Cancel/Approve chrome — a consumer composes
+ * it inside their own dialog (e.g. a tool-approval dialog) and reads
+ * `.value`/`.errors`/`checkValidity()` (or calls `reportValidity()` right
+ * before acting, which also reveals any inline errors that user interaction
+ * hasn't surfaced yet).
+ *
+ * `value` is exactly what the consumer last set it to — a field with no
+ * entry in `value` but a schema `default` displays (and is *emitted*, via
+ * `lyra-input`) as that default, but the `value` *property* itself is left
+ * alone until the user actually edits that field. This mirrors an
+ * uncontrolled `<input placeholder>` not writing to `.value`, and means the
+ * very first `lyra-input` a consumer receives already carries every default
+ * resolved, so round-tripping `e.detail.value` back into `.value` converges
+ * after one edit. JSON Schema defines `default` as an annotation; this form
+ * renderer deliberately materializes it before validation and submission,
+ * so a valid default can satisfy `required` here.
+ *
+ * Optional native `<form>` participation is implemented via `ElementInternals`
+ * attached directly (this component's value is a whole object, not a plain
+ * string, so the `FormAssociated` string-value mixin doesn't fit — same
+ * shape as `<lyra-combobox>`'s array-valued case). This is a nice-to-have
+ * layered on top of the primary integration contract (`value` +
+ * `lyra-input`/`lyra-validity-change`), not a requirement: a consumer that
+ * never puts this inside a `<form>` loses nothing.
+ *
+ * @customElement lyra-tool-param-form
+ * @event lyra-input - A field's value changed. `detail: { value }` — the
+ * full current value object (every property, defaults resolved), not just
+ * the field that changed.
+ * @event lyra-validity-change - Overall validity or field errors changed.
+ * `detail: { valid: boolean; errors: Record<string, string> }`.
+ * @csspart base - The outer wrapper around all fields.
+ * @csspart field - One property's wrapper (label + control + description + error).
+ * @csspart label - A field's label.
+ * @csspart description - A field's helper text, from `schema.description`.
+ * @csspart error - A field-level or form-level validation message.
+ */
+export interface LyraToolParamFormEventMap {
+    'lyra-validity-change': CustomEvent<{
+        valid: boolean;
+        errors: Record<string, string>;
+    }>;
+    'lyra-input': CustomEvent<{
+        value: Record<string, unknown>;
+    }>;
+}
+export declare class LyraToolParamForm extends LyraElement<LyraToolParamFormEventMap> {
+    static formAssociated: boolean;
+    static styles: import("lit").CSSResultGroup[];
+    static properties: {
+        name: {
+            reflect: boolean;
+            noAccessor: boolean;
+        };
+        schema: {
+            attribute: boolean;
+            noAccessor: boolean;
+        };
+        value: {
+            attribute: boolean;
+            noAccessor: boolean;
+        };
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+            noAccessor: boolean;
+        };
+    };
+    private _errors;
+    private _formError;
+    private showFormError;
+    private touchedFields;
+    private internals;
+    private validityController;
+    private baseId;
+    private _fieldsetDisabled;
+    private _name;
+    private _schema;
+    private _value;
+    private _effectiveValue;
+    private _validityFlags;
+    private _disabled;
+    private lastValidityKey;
+    constructor();
+    get form(): HTMLFormElement | null;
+    get labels(): NodeList;
+    get validity(): ValidityState;
+    get validationMessage(): string;
+    get willValidate(): boolean;
+    private firstInvalidField;
+    connectedCallback(): void;
+    /** `value`, with any property missing from it filled in from `schema`'s own `default` — see the class doc. */
+    get effectiveValue(): Record<string, unknown>;
+    private get schemaProperties();
+    private get requiredKeys();
+    private resolveEffectiveValue;
+    get schema(): ToolParamFormSchema;
+    set schema(next: ToolParamFormSchema);
+    get value(): Record<string, unknown>;
+    set value(next: Record<string, unknown>);
+    /** Submission key for the optional native `<form>` participation, reflected synchronously. */
+    get name(): string;
+    set name(next: string);
+    get disabled(): boolean;
+    set disabled(next: boolean);
+    /** Whether the form is disabled explicitly or by an ancestor fieldset. */
+    get effectiveDisabled(): boolean;
+    /**
+     * The current per-field validation errors (`{ [propertyKey]: message }`) —
+     * required presence, primitive type, integer, enum, const, or unsupported
+     * type — mirrors the last `lyra-validity-change` event's `errors`.
+     * Independent of which fields have been visited; a consumer wanting the
+     * visited-only, screen-reader-announced subset should read the rendered
+     * `[part="error"]` elements instead.
+     */
+    get errors(): Record<string, string>;
+    /** A schema-wide or JSON-serialization error that cannot be assigned to one field. */
+    get formError(): string;
+    /**
+     * Computes the supported flat JSON Schema subset against the exact value
+     * that will be submitted. Defaults are already materialized in `effective`.
+     */
+    private computeValidation;
+    /** Resynchronizes validity without revealing inline errors. */
+    checkValidity(): boolean;
+    /**
+     * Reveals every current field/root error (as if each field had been
+     * visited) and returns overall validity — the hook a
+     * consumer's own Submit/Approve button should call right before acting,
+     * mirroring a native `<form>`'s `reportValidity()`.
+     */
+    reportValidity(): boolean;
+    formResetCallback(): void;
+    formStateRestoreCallback(state: string | File | FormData | null, _mode?: 'restore' | 'autocomplete'): void;
+    formDisabledCallback(disabled: boolean): void;
+    private schemaShapeError;
+    private serializeEffectiveValue;
+    /** Pushes the already-computed snapshot into `ElementInternals`. */
+    private syncInternals;
+    private syncFormState;
+    protected updated(changed: PropertyValues): void;
+    private setFieldValue;
+    private markTouched;
+    private onTextInput;
+    private onNumberInput;
+    private onSelectChange;
+    private onCheckboxChange;
+    private renderControl;
+    private renderField;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-tool-param-form': LyraToolParamForm;
+    }
+}
+//# sourceMappingURL=tool-param-form.class.d.ts.map

package/dist/components/tool-param-form/tool-param-form.class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-param-form.class.d.ts","sourceRoot":"","sources":["../../../src/components/tool-param-form/tool-param-form.class.ts"],"names":[],"mappings":"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"}