@blinkk/selective-edit/dist/selective/field.d.ts

Selective structured text editor.

import { Validation } from './validation';
import { GlobalConfig, SelectiveEditor } from './editor';
import { RuleConfig, Rules } from './validationRules';
import { Template } from './template';
import { TemplateResult } from 'lit-html';
import { Base } from '../mixins';
import { DeepObject } from '../utility/deepObject';
import { Types } from './types';
export interface FieldConfig {
    /**
     * Extra css classes to apply to the field in the editor.
     */
    classes?: Array<string>;
    /**
     * default value to use for the field.
     */
    default?: any;
    /**
     * Help string to display to assist user in understanding the
     * expectations of the field.
     *
     * In complex fields, this can be broken up into zones like
     * validation rules.
     */
    help?: string | Record<string, string>;
    /**
     * Key to reference the field in the data.
     */
    key: string;
    /**
     * Label for the field in the editor.
     */
    label?: string;
    /**
     * Type of field. Used to create the correct field in the
     * editor UI.
     */
    type: string;
    /**
     * Validation rules that should be applied to the field.
     *
     * In complex fields, this can be broken up into zone like
     * help text.
     */
    validation?: Array<RuleConfig> | Record<string, Array<RuleConfig>>;
}
/**
 * Protected values for the field config.
 *
 * These are reserved for internal usage and should not be overwritten
 * by individual field configurations.
 *
 * When adding new protected configs, they cannot be required as that would
 * break the interface for the base `FieldConfig`.
 */
export interface FieldProtectedConfig {
    /**
     * Set by the editor when the field was guessed by the auto
     * fields utility.
     */
    isGuessed?: boolean;
    /**
     * Set by the editor to allow for full reference to the
     * current field structure.
     */
    parentKey?: string;
}
export declare type InternalFieldConfig = FieldConfig & FieldProtectedConfig;
export interface FieldComponent {
    /**
     * Template for rendering the field.
     */
    template: Template;
    /**
     * Key to use to retrieve and save the value in the data.
     */
    key: string;
    /**
     * Track when an input has lost focus.
     *
     * This allows for the UI to only show an error message after the user has
     * attempted to change the value.
     */
    hasLostFocus(zoneKey?: string): boolean;
    /**
     * Is the field clean?
     *
     * The field is considered clean if there are no changes from the original.
     *
     * This is used by the editor to determine if there are changes pending.
     */
    isClean: boolean;
    /**
     * Is the data provided to the field in the correct format?
     *
     * If a field recieves data that is not in the format expected the field
     * will show a message instead of the normal inputs.
     */
    isDataFormatValid: boolean;
    /**
     * Is the field simple?
     *
     * Complex fields usually have multiple inputs. This is used to determine how
     * the field is shown in non-trivial view. For example, lists will not show a
     * 'simple' view of list items if it uses a complex field.
     */
    isSimple: boolean;
    /**
     * Has the field passed all relative validation rules.
     */
    isValid: boolean;
    /**
     * Internal lock for fields that can get messed up. For example list fields.
     */
    lock(): void;
    /**
     * Mark the zone as having lost focus.
     *
     * This allows for the UI to only show an error message after the user has
     * attempted to change the value.
     */
    lostFocus(zoneKey?: string): void;
    render(): void;
    updateOriginal(editor: SelectiveEditor, data: DeepObject): void;
    /**
     * Internal unlock for fields that can get messed up. For example list fields.
     */
    unlock(): void;
    /**
     * Unique id value for the field. Usually a shortened form of the UUID.
     */
    uid: string;
    /**
     * UUID value for the field.
     */
    uuid: string;
    /**
     * Current value of the field.
     */
    value: any;
}
export declare type FieldConstructor = (types: Types, config: InternalFieldConfig) => FieldComponent;
export interface ZoneInfo {
    key: string;
    hasLostFocus?: boolean;
}
declare const Field_base: {
    new (...args: any[]): {
        _uuid?: string | undefined;
        readonly uuid: string;
        readonly uid: string;
    };
} & {
    new (...args: any[]): {
        _data?: DeepObject | undefined;
        data: DeepObject | undefined;
    };
} & typeof Base;
export declare class Field extends Field_base implements FieldComponent {
    config: InternalFieldConfig;
    globalConfig: GlobalConfig;
    protected currentValue?: any;
    protected isLocked: boolean;
    protected isDeepLinked: boolean;
    readonly fieldType: string;
    protected originalValue?: any;
    types: Types;
    usingAutoFields: boolean;
    validation?: Validation;
    zones?: Record<string, ZoneInfo>;
    protected _rules?: Rules;
    constructor(types: Types, config: InternalFieldConfig, globalConfig: GlobalConfig, fieldType?: string);
    /**
     * Generates a list of classes to apply to the field element.
     */
    classesForField(): Record<string, boolean>;
    /**
     * Generates a list of classes to apply to the input element.
     */
    classesForInput(zoneKey?: string): Record<string, boolean>;
    /**
     * Generates a list of classes to apply to the label element.
     */
    classesForLabel(zoneKey?: string): Record<string, boolean>;
    /**
     * The format of the original value may need to be cleaned up to be used
     * by the editor in a consistent format.
     *
     * @param value Original value from the source.
     */
    cleanOriginalValue(value: any): any;
    /**
     * Store the validation to keep from having to repeat the validation.
     *
     * Validation is reset every time the updateOriginal is called (every render).
     *
     * @param editor Selective editor being rendered.
     */
    protected ensureValidation(editor?: SelectiveEditor): void;
    get fullKey(): string;
    /**
     * Handle when the input changes value.
     *
     * @param evt Input event from changing value.
     */
    handleInput(evt: Event): void;
    /**
     * Handle when the input loses focus.
     */
    handleBlur(): void;
    /**
     * Determines if the field has lost focus before for a zone.
     *
     * This is used for UI to determine when to display validation
     * messsages for a better UX when they have not interacted with
     * the field.
     */
    hasLostFocus(zoneKey?: string): boolean;
    get isClean(): boolean;
    /**
     * Check if the data format is invalid for what the field expects to edit.
     */
    get isDataFormatValid(): boolean;
    get isSimple(): boolean;
    get isValid(): boolean;
    get key(): string;
    /**
     * Certain cases require the field to be locked while updating to prevent
     * bad data mixing. This allows for manually locking the fields.
     */
    lock(): void;
    /**
     * Mark that the field has lost focus for a zone.
     *
     * This is used for UI to determine when to display validation
     * messsages for a better UX when they have not interacted with
     * the field.
     */
    lostFocus(zoneKey?: string): void;
    /**
     * Signal for the editor to re-render.
     */
    render(): void;
    get rules(): Rules;
    /**
     * Template for determining how to render the field.
     *
     * The default field template has several levels of templates
     * to make it easier for individual fields to override parts of
     * template without needing to replicate a lot of internal template
     * features.
     *
     * Base field template structure:
     *
     * ```
     * template
     * └── templateWrapper
     *     └── templateStructure
     *         ├── templateHeaderStructure
     *         │   ├── templateHeader
     *         │   └── templateLabel
     *         ├── templateInputStructure
     *         │   └── templateInput
     *         └── templateFooterStructure
     *             └── templateFooter
     * ```
     *
     * @param editor Selective editor used to render the template.
     * @param data Data provided to render the template.
     */
    template(editor: SelectiveEditor, data: DeepObject): TemplateResult;
    /**
     * Template for showing the invalid data format messaging.
     *
     * @param editor Selective editor used to render the template.
     * @param data Data provided to render the template.
     */
    templateDataFormatInvalid(editor: SelectiveEditor, data: DeepObject): TemplateResult;
    /**
     * Template for rendering the errors.
     *
     * @param editor Selective editor used to render the template.
     * @param data Data provided to render the template.
     * @param zoneKey Zone to provide the error messages for.
     */
    templateErrors(editor: SelectiveEditor, data: DeepObject, zoneKey?: string): TemplateResult;
    /**
     * Template for rendering the field footer.
     *
     * @param editor Selective editor used to render the template.
     * @param data Data provided to render the template.
     */
    templateFooter(editor: SelectiveEditor, data: DeepObject): TemplateResult;
    /**
     * Template for rendering the field footer structure.
     *
     * @param editor Selective editor used to render the template.
     * @param data Data provided to render the template.
     */
    templateFooterStructure(editor: SelectiveEditor, data: DeepObject): TemplateResult;
    /**
     * Template for rendering the field header.
     *
     * @param editor Selective editor used to render the template.
     * @param data Data provided to render the template.
     */
    templateHeader(editor: SelectiveEditor, data: DeepObject): TemplateResult;
    /**
     * Template for rendering the field header structure.
     *
     * @param editor Selective editor used to render the template.
     * @param data Data provided to render the template.
     */
    templateHeaderStructure(editor: SelectiveEditor, data: DeepObject): TemplateResult;
    /**
     * Template for rendering the field help.
     *
     * @param editor Selective editor used to render the template.
     * @param data Data provided to render the template.
     * @param zoneKey Zone to provide the error messages for.
     */
    templateHelp(editor: SelectiveEditor, data: DeepObject, zoneKey?: string): TemplateResult;
    /**
     * Template for rendering the icon for deep linking.
     *
     * @param editor Selective editor used to render the template.
     * @param data Data provided to render the template.
     */
    templateIconDeepLink(editor: SelectiveEditor, data: DeepObject): TemplateResult;
    /**
     * Template for rendering the icon for validation.
     *
     * @param editor Selective editor used to render the template.
     * @param data Data provided to render the template.
     */
    templateIconValidation(editor: SelectiveEditor, data: DeepObject): TemplateResult;
    /**
     * Template for rendering the field input.
     *
     * The help text is part of the input template so complex inputs can
     * use zones for the help text.
     *
     * @param editor Selective editor used to render the template.
     * @param data Data provided to render the template.
     */
    templateInput(editor: SelectiveEditor, data: DeepObject): TemplateResult;
    /**
     * Template for rendering the field input structure.
     *
     * @param editor Selective editor used to render the template.
     * @param data Data provided to render the template.
     */
    templateInputStructure(editor: SelectiveEditor, data: DeepObject): TemplateResult;
    /**
     * Template for rendering the field label.
     *
     * @param editor Selective editor used to render the template.
     * @param data Data provided to render the template.
     */
    templateLabel(editor: SelectiveEditor, data: DeepObject): TemplateResult;
    /**
     * Template for rendering the field structure.
     *
     * Used for controlling the order that parts of the field are rendered.
     *
     * @param editor Selective editor used to render the template.
     * @param data Data provided to render the template.
     */
    templateStructure(editor: SelectiveEditor, data: DeepObject): TemplateResult;
    /**
     * Template for rendering the field wrapper.
     *
     * @param editor Selective editor used to render the template.
     * @param data Data provided to render the template.
     */
    templateWrapper(editor: SelectiveEditor, data: DeepObject): TemplateResult;
    /**
     * Certain cases require the field to be locked while updating to prevent bad
     * data mixing. This allows for manually unlocking the fields.
     */
    unlock(): void;
    /**
     * Use the data passed to render to update the original value.
     * Also update the clean value when applicable.
     *
     * @param editor Selective editor used to render the template.
     * @param data Data provided to render the template.
     */
    updateOriginal(editor: SelectiveEditor, data: DeepObject): void;
    get value(): any;
}
export {};