@saasbase-io/core-elements 1.18.0 → 1.20.0

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

@@ -1,57 +1,284 @@
 import { LitElement } from '../../../../../node_modules/lit';
-export type NameFieldValidateType = "success" | "required" | "format";
-export declare class SbNameField extends LitElement {
+import { NameFieldContent, NameFieldProps } from './field.types';
+/**
+ * A self-validating name field for auth widget forms.
+ * @element sb-name-field
+ *
+ * @part name-field (rtg-field)
+ * @part name-field-content (rtg-field-content): label + description wrapper
+ * @part name-field-label (rtg-field-label)
+ * @part name-field-mark (span): decorative marker with text or `"*"` in label
+ * @part name-field-description (rtg-field-description)
+ * @part name-field-input (rtg-input)
+ * @part name-field-error (rtg-field-error)
+ *
+ * @fires sb-name-field:validate
+ * { id, parentId, name, value, valid, type, message }
+ *  - id: inputId
+ *  - parentId: rootId
+ *  - type: "required" | "format" | "success" | "minlength" | "maxlength"
+ */
+export declare class SbNameField extends LitElement implements NameFieldProps {
     private static readonly _ROOT;
-    private static readonly _FIRST;
-    private static readonly _LAST;
+    private static readonly _CONTENT;
+    private static readonly _LABEL;
+    private static readonly _MARK;
+    private static readonly _DESCRIPTION;
+    private static readonly _INPUT;
+    private static readonly _ERROR;
+    static readonly TAG: string;
+    private static readonly _PATTERN;
+    /**
+     * The stable CSS part names exposed for external targeting.
+     */
     static get parts(): {
         root: string;
-        firstField: string;
-        lastField: string;
-        input: string;
+        content: string;
         label: string;
-        error: string;
         mark: string;
         description: string;
+        input: string;
+        error: string;
     };
+    /**
+     * The name of the custom event fired on validate.
+     */
     static get validateEventName(): string;
-    firstLabel: string;
-    lastLabel: 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;
-    required?: boolean;
+    /**
+     * Whether the label and description are grouped together above the input, or
+     * split up with the input in-between them.
+     */
+    content: NameFieldContent;
+    /**
+     * 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;
-    firstName: string;
-    lastName: string;
-    firstPlaceholder: string;
-    lastPlaceholder: string;
+    /**
+     * When provided, the parent form cannot be submitted without this field.
+     */
+    required?: boolean;
+    /**
+     * The minimum number of characters required for a valid name.
+     */
+    minlength?: number;
+    /**
+     * The maximum number of characters accepted for a valid name.
+     */
+    maxlength?: number;
+    /**
+     * The regex pattern for a valid name, used in place of `_PATTERN`.
+     */
+    pattern?: string;
+    /**
+     * Error message shown when the field is required but empty upon submission.
+     */
     requiredError: string;
+    /**
+     * Custom error message shown when the name is shorter than minlength.
+     */
+    minlengthError?: string;
+    /**
+     * Custom error message shown when the name is longer than maxlength.
+     */
+    maxlengthError?: string;
+    /**
+     * Error message shown when the field is invalid upon submission.
+     */
     formatError: string;
-    mark?: string;
-    caret?: boolean;
-    private _first;
-    private _firstInvalid;
-    private _firstError;
-    private _last;
-    private _lastInvalid;
-    private _lastError;
+    /**
+     * 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 name 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;
-    private _renderMark;
+    /**
+     * 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 trimming leading/trailing
+     * whitespace and collapsing consecutive interior spaces into one.
+     */
+    private get _normalizedValue();
+    /**
+     * Returns sanitized `minlength` and `maxlength` values, filtering out
+     * non-positive numbers and discarding `maxlength` if it is less than
+     * `minlength` to prevent conflicting length constraints.
+     */
+    private get _lengths();
+    /**
+     * Returns the resolved regex pattern, using a `RegExp` built from the
+     * `pattern` prop when provided, otherwise falling back to `_PATTERN`.
+     */
+    private get _pattern();
+    /**
+     * 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;
-    private _validateName;
+    /**
+     * 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 minlength condition validation, determining if a valid
+     * `minlength` prop was provided, dispatching and displaying the minlength
+     * error if the value is shorter than accepted.
+     */
+    private _validateMinlength;
+    /**
+     * Handles the maxlength condition validation, determining if a valid
+     * `maxlength` prop was provided, dispatching and displaying the maxlength
+     * error if the value is longer than accepted.
+     */
+    private _validateMaxlength;
+    /**
+     * Handles the format condition validation, testing against `_pattern`, and
+     * dispatching and displaying the format error for an invalid value.
+     */
+    private _validateFormat;
+    /**
+     * Resets the `_invalid` and `_error` private props and dispatches the
+     * validate event, indicating a successfully validated and valid name.
+     */
+    private _doValidateSuccess;
+    /**
+     * Handles validation and dispatches the success event if the required,
+     * length, and format conditions are met.
+     */
     private _validate;
-    validate(): boolean;
+    /**
+     * Handles the input event, updating the private `_value` prop.
+     */
     private _handleInput;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    private _renderFirstField;
-    private _renderLastField;
+    /**
+     * 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 name 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>;
 }
-declare global {
-    interface HTMLElementTagNameMap {
-        "sb-name-field": SbNameField;
-    }
-}

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

@@ -1,12 +1,15 @@
 import { Meta, StoryObj } from '@storybook/web-components-vite';
-import { SbNameField } from '../_name-field';
 declare const meta: Meta;
 export default meta;
-type Story = StoryObj<SbNameField>;
+type Story = StoryObj;
 export declare const Basic: Story;
-export declare const Required: Story;
-export declare const FormatValidation: Story;
-export declare const MarkAndCaret: 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 Form: Story;
+export declare const Caret: Story;
+export declare const Mark: Story;
 export declare const Validate: Story;
+export declare const Form: Story;
+export declare const FormGroup: Story;

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

@@ -40,6 +40,12 @@ export type UsernameFieldProps = Omit<BaseFieldPropsWithLength, "content"> & {
     content: UsernameFieldContent;
     pattern?: string;
 };
+export type NameFieldValidateType = BaseFieldValidateTypeWithLength;
+export type NameFieldContent = BaseFieldContent;
+export type NameFieldProps = Omit<BaseFieldPropsWithLength, "content"> & {
+    content: NameFieldContent;
+    pattern?: string;
+};
 export type PasswordFieldValidateType = BaseFieldValidateTypeWithLength;
 export type PasswordFieldVariant = "toggle" | "simple";
 export type PasswordFieldContent = BaseFieldContent;
@@ -77,33 +83,4 @@ export type IdentifierFieldProps = Omit<BaseFieldProps, "label" | "content" | "f
     content: IdentifierFieldContent;
     autocomplete?: IdentifierFieldAutocomplete;
 };
-export type NameFieldValidateType = BaseFieldValidateType;
-export type NameFieldContent = BaseFieldContent;
-export type NameFieldProps = {
-    seed: string;
-    childId?: string;
-    fieldId?: string;
-    /**
-     * Base form field name (e.g. "name", "full_name")
-     */
-    name: string;
-    content: NameFieldContent;
-    /**
-     * Label for first name input (e.g. "First name")
-     */
-    firstLabel: string;
-    /**
-     * Label for last name input (e.g. "Last name")
-     */
-    lastLabel: string;
-    firstPlaceholder?: string;
-    lastPlaceholder?: string;
-    description?: string;
-    mark?: string;
-    caret?: boolean;
-    disabled?: boolean;
-    required?: boolean;
-    requiredError: string;
-    formatError: string;
-};
 export {};

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

@@ -5,7 +5,7 @@ import { SbNameField } from './_name-field';
 import { SbPasswordField } from './_password-field';
 import { SbPhoneField } from './_phone-field';
 import { SbUsernameField } from './_username-field';
-export { SbConfirmField, SbEmailField, SbIdentifierField, SbPasswordField, SbPhoneField, SbUsernameField, SbNameField, };
+export { SbConfirmField, SbEmailField, SbIdentifierField, SbNameField, SbPasswordField, SbPhoneField, SbUsernameField, };
 declare global {
     interface HTMLElementTagNameMap {
         "sb-email-field": SbEmailField;

package/dist/components/renderers/_updated/passkey-button/_passkey-button.d.ts

@@ -1,7 +1,7 @@
 import { LitElement } from '../../../../../node_modules/lit';
 import { PasskeyButtonProps, PasskeyButtonSize, PasskeyButtonSpinnerAlign, PasskeyButtonVariant } from './passkey-button.types';
 /**
- * A button for passkey authentication.
+ * A button for passkey authentication in auth widgets.
  * @element sb-passkey-button
  *
  * @part passkey-button (rtg-button)
@@ -12,6 +12,8 @@ import { PasskeyButtonProps, PasskeyButtonSize, PasskeyButtonSpinnerAlign, Passk
 export declare class SbPasskeyButton extends LitElement implements PasskeyButtonProps {
     private static readonly _ROOT;
     private static readonly _SPINNER;
+    static readonly TAG: string;
+    static readonly CLICK_EVENT: string;
     /**
      * The stable CSS part names exposed for external targeting.
      */
@@ -20,17 +22,11 @@ export declare class SbPasskeyButton extends LitElement implements PasskeyButton
         spinner: string;
     };
     /**
-     * The name of the custom event fired on click.
-     */
-    static get clickEventName(): string;
-    /**
-     * A unique value used as a substring in the generated part/child IDs, when
-     * the `child-id` prop is not provided.
+     * A unique substring for fallback part IDs generated.
      */
     seed: string;
     /**
-     * The `id` value given to the root child/part and used as the base of other
-     * child/part IDs.
+     * The `id` of the root part and the base of sub-part IDs.
      */
     childId?: string;
     /**
@@ -58,7 +54,7 @@ export declare class SbPasskeyButton extends LitElement implements PasskeyButton
      */
     loading?: boolean;
     /**
-     * The event identifier/name as defined in auth service.
+     * The event name as defined in the loginflow auth service.
      */
     event?: string;
     /**
@@ -75,8 +71,7 @@ export declare class SbPasskeyButton extends LitElement implements PasskeyButton
      */
     get rootId(): string;
     /**
-     * The `id` of the spinner element, derived from `rootId` with the spinner
-     * part name appended.
+     * The `id` of the spinner element, derived from `rootId` and the part name.
      */
     get spinnerId(): string;
     /**
@@ -91,14 +86,6 @@ export declare class SbPasskeyButton extends LitElement implements PasskeyButton
      * Removes the click event listener.
      */
     disconnectedCallback(): void;
-    /**
-     * Defines and dispatches the click event.
-     */
-    private _dispatchClick;
-    /**
-     * Emits the provided `event` to the auth service to process.
-     */
-    private _emitClickEvent;
     /**
      * Handles the click event, preventing execution when disabled/loading, firing
      * the click event, and emitting to auth service.