@saasbase-io/core-elements 1.5.0 → 1.7.0

package/dist/components/renderers/_updated/field/_email-field.d.ts

@@ -0,0 +1,236 @@
+import { LitElement } from '../../../../../node_modules/lit';
+import { EmailFieldContent, EmailFieldProps } from './field.types';
+/**
+ * A self-validating email field for auth widget forms.
+ * @element sb-email-field
+ *
+ * @part email-field (rtg-field)
+ * @part email-field-content (rtg-field-content): label + description wrapper
+ * @part email-field-label (rtg-field-label)
+ * @part email-field-mark (span): decorative marker with text or `"*"` in label
+ * @part email-field-description (rtg-field-description)
+ * @part email-field-input (rtg-input)
+ * @part email-field-error (rtg-field-error)
+ *
+ * @fires sb-email-field:validate
+ * { id, parentId, name, value, valid, type, message }
+ *  - id: inputId
+ *  - parentId: rootId
+ *  - type: "required" | "format" | "success"
+ */
+export declare class SbEmailField extends LitElement implements EmailFieldProps {
+    private static readonly _ROOT;
+    private static readonly _CONTENT;
+    private static readonly _LABEL;
+    private static readonly _MARK;
+    private static readonly _DESCRIPTION;
+    private static readonly _INPUT;
+    private static readonly _ERROR;
+    private static readonly _PATTERN;
+    /**
+     * The stable CSS part names exposed for external targeting.
+     */
+    static get parts(): {
+        root: string;
+        content: string;
+        label: string;
+        mark: string;
+        description: string;
+        input: string;
+        error: string;
+    };
+    /**
+     * The name of the custom event fired on validate.
+     */
+    static get validateEventName(): string;
+    /**
+     * A unique value used as a substring in the generated part/child IDs, when
+     * the `child-id` prop is not provided.
+     */
+    seed: string;
+    /**
+     * The `id` value given to the root child/part and used as the base of other
+     * child/part IDs.
+     */
+    childId?: string;
+    /**
+     * The `id` value given to the input child/part to override the auto-generated
+     * input ID, derived from the `rootId`.
+     */
+    fieldId?: string;
+    /**
+     * The `name` prop of the input part, used by the parent form.
+     */
+    name: string;
+    /**
+     * Whether the label and description are grouped together above the input, or
+     * split up with the input in-between them.
+     */
+    content: EmailFieldContent;
+    /**
+     * The text content of the field label.
+     */
+    label: string;
+    /**
+     * The text used as the input placeholder.
+     */
+    placeholder?: string;
+    /**
+     * The text content of the field description.
+     */
+    description?: string;
+    /**
+     * The text rendered in the field label as a custom mark.
+     */
+    mark?: string;
+    /**
+     * When provided with `required`, a caret mark is rendered in the field label.
+     */
+    caret?: boolean;
+    /**
+     * Whether the field is in a disabled state.
+     */
+    disabled?: boolean;
+    /**
+     * When provided, the parent form cannot be submitted without this field.
+     */
+    required?: boolean;
+    /**
+     * Error message shown when the field is required but empty upon submission.
+     */
+    requiredError: string;
+    /**
+     * Error message shown when the field is invalid upon submission.
+     */
+    formatError: string;
+    /**
+     * Indicates that the field is in an invalid state.
+     */
+    private _invalid;
+    /**
+     * The text rendered in field error when in an invalid state.
+     */
+    private _error;
+    /**
+     * The current value of the email input.
+     */
+    private _value;
+    /**
+     * Reference to the nearest `form` ancestor.
+     */
+    private _form;
+    /**
+     * Overrides default behavior to render into light DOM.
+     */
+    protected createRenderRoot(): this;
+    /**
+     * The `id` of the root element. Equal to `childId` when provided, otherwise
+     * derived from the component's part name and `seed`.
+     */
+    get rootId(): string;
+    /**
+     * The `id` of the field content element, derived from `rootId` with the
+     * content part name appended.
+     */
+    get contentId(): string;
+    /**
+     * The `id` of the field label element, derived from `rootId` with the label
+     * part name appended.
+     */
+    get labelId(): string;
+    /**
+     * The `id` of the field description element, derived from `rootId` with the
+     * description part name appended.
+     */
+    get descriptionId(): string;
+    /**
+     * The `id` of the mark element, derived from `rootId` with the mark part name
+     * appended.
+     */
+    get markId(): string;
+    /**
+     * The `id` of the input element, equal to `fieldId` when provided, otherwise
+     * derived from `rootId` with the input part name appended.
+     */
+    get inputId(): string;
+    /**
+     * The `id` of the field error element, derived from `rootId` with the error
+     * part name appended.
+     */
+    get errorId(): string;
+    /**
+     * Returns a the normalized value of `_value` by trimming whitespace and
+     * converting letters to lowercase.
+     */
+    private get _normalizedValue();
+    /**
+     * Adds the input, form submit, and form reset event listeners.
+     */
+    connectedCallback(): void;
+    /**
+     * Removes the input, form submit, and form reset event listeners.
+     */
+    disconnectedCallback(): void;
+    /**
+     * The public validate method that calls the private `_validate()` method for
+     * manual, external validation.
+     */
+    validate(): boolean;
+    /**
+     * Defines and dispatches the validate event.
+     */
+    private _dispatchValidate;
+    /**
+     * Handles the required condition validation, accepting empty non-required
+     * fields and non-empty required fields, otherwise dispatching and displaying
+     * the required error.
+     */
+    private _validateRequired;
+    /**
+     * Handles the format condition validation with `_PATTERN`, accepting empty
+     * non-required fields and non-empty fields that satisfy the pattern,
+     * otherwise dispatching and displaying the format error.
+     */
+    private _validateFormat;
+    /**
+     * Handles validation and dispatches the success event if the required and
+     * format conditions are met.
+     */
+    private _validate;
+    /**
+     * Handles the input event, updating the private `_value` prop.
+     */
+    private _handleInput;
+    /**
+     * Handles the form submit event, running the `_validate()` method and
+     * preventing the default submission behavior if invalid.
+     */
+    private _handleFormSubmit;
+    /**
+     * Handles the form reset event, resetting the input element's `value` as well
+     * as the email field's private props: `_value`, `_invalid`, and `_error`.
+     */
+    private _handleFormReset;
+    /**
+     * Conditionally returns the mark template for the field label. When `caret`
+     * and `required` are provided, the mark becomes an asterisk. When `mark` is
+     * provided, its value is rendered inside the element.
+     * If both a caret and custom text mark have their conditions met, the custom
+     * mark will be prioritised and rendered instead of the asterisk.
+     */
+    private _renderMark;
+    /**
+     * Returns the field label template with the label text and optional mark.
+     */
+    private _renderLabel;
+    /**
+     * Returns the field description template if `description` is defined.
+     */
+    private _renderDescription;
+    /**
+     * Returns the field error template with the `_error` message if the
+     * `_invalid` state is `true`.
+     */
+    private _renderError;
+    render(): import('../../../../../node_modules/lit-html').TemplateResult<1>;
+}

package/dist/components/renderers/_updated/field/_phone-field.d.ts

@@ -0,0 +1,235 @@
+import { LitElement } from '../../../../../node_modules/lit';
+import { PhoneFieldContent, PhoneFieldProps } from './field.types';
+/**
+ * A self-validating phone field for auth widget forms.
+ * @element sb-phone-field
+ *
+ * @part phone-field (rtg-field)
+ * @part phone-field-content (rtg-field-content): label + description wrapper
+ * @part phone-field-label (rtg-field-label)
+ * @part phone-field-mark (span): decorative marker with text or `"*"` in label
+ * @part phone-field-description (rtg-field-description)
+ * @part phone-field-input (rtg-input)
+ * @part phone-field-error (rtg-field-error)
+ *
+ * @fires sb-phone-field:validate
+ * { id, parentId, name, value, valid, type, message }
+ *  - id: inputId
+ *  - parentId: rootId
+ *  - type: "required" | "format" | "success"
+ */
+export declare class SbPhoneField extends LitElement implements PhoneFieldProps {
+    private static readonly _ROOT;
+    private static readonly _CONTENT;
+    private static readonly _LABEL;
+    private static readonly _MARK;
+    private static readonly _DESCRIPTION;
+    private static readonly _INPUT;
+    private static readonly _ERROR;
+    private static readonly _PATTERN;
+    /**
+     * The stable CSS part names exposed for external targeting.
+     */
+    static get parts(): {
+        root: string;
+        content: string;
+        label: string;
+        mark: string;
+        description: string;
+        input: string;
+        error: string;
+    };
+    /**
+     * The name of the custom event fired on validate.
+     */
+    static get validateEventName(): string;
+    /**
+     * A unique value used as a substring in the generated part/child IDs, when
+     * the `child-id` prop is not provided.
+     */
+    seed: string;
+    /**
+     * The `id` value given to the root child/part and used as the base of other
+     * child/part IDs.
+     */
+    childId?: string;
+    /**
+     * The `id` value given to the input child/part to override the auto-generated
+     * input ID, derived from the `rootId`.
+     */
+    fieldId?: string;
+    /**
+     * The `name` prop of the input part, used by the parent form.
+     */
+    name: string;
+    /**
+     * Whether the label and description are grouped together above the input, or
+     * split up with the input in-between them.
+     */
+    content: PhoneFieldContent;
+    /**
+     * The text content of the field label.
+     */
+    label: string;
+    /**
+     * The text used as the input placeholder.
+     */
+    placeholder?: string;
+    /**
+     * The text content of the field description.
+     */
+    description?: string;
+    /**
+     * The text rendered in the field label as a custom mark.
+     */
+    mark?: string;
+    /**
+     * When provided with `required`, a caret mark is rendered in the field label.
+     */
+    caret?: boolean;
+    /**
+     * Whether the field is in a disabled state.
+     */
+    disabled?: boolean;
+    /**
+     * When provided, the parent form cannot be submitted without this field.
+     */
+    required?: boolean;
+    /**
+     * Error message shown when the field is required but empty upon submission.
+     */
+    requiredError: string;
+    /**
+     * Error message shown when the field is invalid upon submission.
+     */
+    formatError: string;
+    /**
+     * Indicates that the field is in an invalid state.
+     */
+    private _invalid;
+    /**
+     * The text rendered in field error when in an invalid state.
+     */
+    private _error;
+    /**
+     * The current value of the phone input.
+     */
+    private _value;
+    /**
+     * Reference to the nearest `form` ancestor.
+     */
+    private _form;
+    /**
+     * Overrides default behavior to render into light DOM.
+     */
+    protected createRenderRoot(): this;
+    /**
+     * The `id` of the root element. Equal to `childId` when provided, otherwise
+     * derived from the component's part name and `seed`.
+     */
+    get rootId(): string;
+    /**
+     * The `id` of the field content element, derived from `rootId` with the
+     * content part name appended.
+     */
+    get contentId(): string;
+    /**
+     * The `id` of the field label element, derived from `rootId` with the label
+     * part name appended.
+     */
+    get labelId(): string;
+    /**
+     * The `id` of the field description element, derived from `rootId` with the
+     * description part name appended.
+     */
+    get descriptionId(): string;
+    /**
+     * The `id` of the mark element, derived from `rootId` with the mark part name
+     * appended.
+     */
+    get markId(): string;
+    /**
+     * The `id` of the input element, equal to `fieldId` when provided, otherwise
+     * derived from `rootId` with the input part name appended.
+     */
+    get inputId(): string;
+    /**
+     * The `id` of the field error element, derived from `rootId` with the error
+     * part name appended.
+     */
+    get errorId(): string;
+    /**
+     * Returns the normalized value of `_value` by stripping all whitespace.
+     */
+    private get _normalizedValue();
+    /**
+     * Adds the input, form submit, and form reset event listeners.
+     */
+    connectedCallback(): void;
+    /**
+     * Removes the input, form submit, and form reset event listeners.
+     */
+    disconnectedCallback(): void;
+    /**
+     * The public validate method that calls the private `_validate()` method for
+     * manual, external validation.
+     */
+    validate(): boolean;
+    /**
+     * Defines and dispatches the validate event.
+     */
+    private _dispatchValidate;
+    /**
+     * Handles the required condition validation, accepting empty non-required
+     * fields and non-empty required fields, otherwise dispatching and displaying
+     * the required error.
+     */
+    private _validateRequired;
+    /**
+     * Handles the format condition validation with `_PATTERN`, accepting empty
+     * non-required fields and non-empty fields that satisfy the pattern,
+     * otherwise dispatching and displaying the format error.
+     */
+    private _validateFormat;
+    /**
+     * Handles validation and dispatches the success event if the required and
+     * format conditions are met.
+     */
+    private _validate;
+    /**
+     * Handles the input event, updating the private `_value` prop.
+     */
+    private _handleInput;
+    /**
+     * Handles the form submit event, running the `_validate()` method and
+     * preventing the default submission behavior if invalid.
+     */
+    private _handleFormSubmit;
+    /**
+     * Handles the form reset event, resetting the input element's `value` as well
+     * as the phone field's private props: `_value`, `_invalid`, and `_error`.
+     */
+    private _handleFormReset;
+    /**
+     * Conditionally returns the mark template for the field label. When `caret`
+     * and `required` are provided, the mark becomes an asterisk. When `mark` is
+     * provided, its value is rendered inside the element.
+     * If both a caret and custom text mark have their conditions met, the custom
+     * mark will be prioritised and rendered instead of the asterisk.
+     */
+    private _renderMark;
+    /**
+     * Returns the field label template with the label text and optional mark.
+     */
+    private _renderLabel;
+    /**
+     * Returns the field description template if `description` is defined.
+     */
+    private _renderDescription;
+    /**
+     * Returns the field error template with the `_error` message if the
+     * `_invalid` state is `true`.
+     */
+    private _renderError;
+    render(): import('../../../../../node_modules/lit-html').TemplateResult<1>;
+}

package/dist/components/renderers/_updated/field/field.stories/email-field.stories.d.ts

@@ -0,0 +1,14 @@
+import { Meta, StoryObj } from '@storybook/web-components-vite';
+declare const meta: Meta;
+export default meta;
+type Story = StoryObj;
+export declare const Basic: Story;
+export declare const Label: Story;
+export declare const Placeholder: Story;
+export declare const Description: Story;
+export declare const Content: Story;
+export declare const Disabled: Story;
+export declare const Caret: Story;
+export declare const Mark: Story;
+export declare const Validate: Story;
+export declare const Form: Story;

package/dist/components/renderers/_updated/field/field.stories/phone-field.stories.d.ts

@@ -0,0 +1,14 @@
+import { Meta, StoryObj } from '@storybook/web-components-vite';
+declare const meta: Meta;
+export default meta;
+type Story = StoryObj;
+export declare const Basic: Story;
+export declare const Label: Story;
+export declare const Placeholder: Story;
+export declare const Description: Story;
+export declare const Content: Story;
+export declare const Disabled: Story;
+export declare const Caret: Story;
+export declare const Mark: Story;
+export declare const Validate: Story;
+export declare const Form: Story;

package/dist/components/renderers/_updated/field/field.types.d.ts

@@ -0,0 +1,28 @@
+type BaseFieldContent = "split" | "group";
+type BaseFieldProps = {
+    seed: string;
+    childId?: string;
+    fieldId?: string;
+    name: string;
+    content: BaseFieldContent;
+    label: string;
+    placeholder?: string;
+    description?: string;
+    mark?: string;
+    caret?: boolean;
+    disabled?: boolean;
+    required?: boolean;
+    requiredError: string;
+    formatError: string;
+};
+export type EmailFieldValidateType = "success" | "required" | "format";
+export type EmailFieldContent = BaseFieldContent;
+export type EmailFieldProps = Omit<BaseFieldProps, "content"> & {
+    content: EmailFieldContent;
+};
+export type PhoneFieldValidateType = "success" | "required" | "format";
+export type PhoneFieldContent = BaseFieldContent;
+export type PhoneFieldProps = Omit<BaseFieldProps, "content"> & {
+    content: PhoneFieldContent;
+};
+export {};

package/dist/components/renderers/_updated/field/index.d.ts

@@ -0,0 +1,9 @@
+import { SbEmailField } from './_email-field';
+import { SbPhoneField } from './_phone-field';
+export { SbEmailField, SbPhoneField };
+declare global {
+    interface HTMLElementTagNameMap {
+        "sb-email-field": SbEmailField;
+        "sb-phone-field": SbPhoneField;
+    }
+}

package/dist/components/renderers/_updated/index.d.ts

@@ -1,3 +1,4 @@
+export * from './field';
 export * from './form';
 export * from './passkey-button';
 export * from './provider';