hb-input-email

Category: inputs · Tags: inputs · Package: @htmlbricks/hb-input-email

Overview

hb-input-email is a Bulma-styled email field built as a custom element with a shadow root. It binds to a single schemaentry object (serialized as JSON when used from HTML), runs lightweight email-shape checks and optional validationRegex / length params, and emits setVal whenever the value or validity changes. Pressing Enter in the input emits clickEnter.

The markup is the native control only (Bulma input inside control). There is no built-in <label> element; add a label in the host page if you need one.

Validation rules

Behavior depends on required in schemaentry:

• Required (required: true)
  The value is invalid until all of the following hold:

  • Non-empty string.
  • Contains @ and ., with reasonable placement: no leading/trailing @ or . on the local or domain side, no .@ or @., no spaces.
  • If validationRegex is present and parses as a valid RegExp, the whole value must match it.
  • If params.min / params.max are set, the string length must be ≥ min and ≤ max (inclusive), evaluated after the checks above.

  If any step fails, the field is invalid.

• Optional (required: false or omitted)
  The component treats the field as always valid (valid: true in events). Optional fields do not receive Bulma is-success / is-danger classes, even when show_validation="yes".

Invalid validationRegex strings are ignored (no extra regex constraint).

Visual feedback (show_validation)

Set show_validation to yes or no (string booleans for HTML attributes).

When show_validation="yes" and the field is required and invalid, the input gets Bulma’s is-danger class. When valid under the same conditions, it gets is-success.

If validationTip is set and validation is shown and the field is invalid, a p.help.is-danger line is rendered. You can style it via the invalid-feedback CSS part (see below).

Styling

The component forwards shared Bulma form styles into the shadow root. Theme it with Bulma’s --bulma-* custom properties on body, :root, or any ancestor so they inherit onto :host. See the Bulma CSS variables documentation.

Variables documented for this package are listed in extra/docs.ts under styleSetup.vars (for example --bulma-text, --bulma-border, --bulma-danger, --bulma-success, --bulma-scheme-main).

Custom element

| Name | Tag | | --- | --- | | hb-input-email | <hb-input-email …></hb-input-email> |

Attributes (snake_case; string values from HTML)

Web component attributes are always strings. Pass schemaentry as a JSON string. Use yes / no for boolean-like flags.

| Attribute | Required | Description | |---------------------|----------|-------------| | schemaentry | Yes | JSON object describing the field (see next section). | | show_validation | No | yes or no. Default in the implementation is no. | | id | No | Optional id on the host element. | | style | No | Optional inline styles on the host element. |

If schemaentry cannot be parsed (invalid JSON string), nothing is rendered.

schemaentry JSON

Typical keys (aligned with shared form schema types; see types/webcomponent.type.d.ts):

| Key | Role | |---------------------|------| | id | Field identifier. Should be set: the setVal effect only runs when id is present, so consumers usually rely on this id in event payloads. | | label | Optional; useful for metadata or parent forms. Not rendered as a DOM label by this component. | | value | Optional initial value (coerced with String(...) when applied from the schema). | | placeholder | Optional placeholder text. | | required | true / false — drives validation and Bulma state classes as described above. | | readonly | Optional; passed to the input. | | disabled | Optional; disables the input when truthy. | | validationRegex | Optional string compiled with new RegExp(...). | | validationTip | Message shown in the danger help line when validation UI is active and the field is invalid. | | params | Optional InputEmailParams object (see below). |

params (InputEmailParams)

| Key | Type | Description | |--------|--------|-------------| | min | number | Minimum string length (inclusive), after basic email checks. | | max | number | Maximum string length (inclusive). |

Events

Listen with addEventListener or framework bindings on the custom element.

| Event | detail | |------------------|----------| | setVal | { value: string; valid: boolean; id: string } — emitted when the value or validity changes, only if schemaentry.id is defined. | | clickEnter | { value: string; valid: boolean; id?: string } — emitted when the user presses Enter in the input (default prevented). |

CSS ::part names

| Part | Description | |------------------------|-------------| | invalid-feedback | The p.help.is-danger element when show_validation="yes", validationTip is set, and the field is invalid. |

TypeScript

Authoring types for props and events live in types/webcomponent.type.d.ts:

• InputEmailParams
• FormSchemaEntry
• Component
• Events

Examples

Minimal required email (HTML)

<hb-input-email
  schemaentry="{&quot;id&quot;:&quot;email&quot;,&quot;required&quot;:true,&quot;placeholder&quot;:&quot;[email protected]&quot;}"
></hb-input-email>

Show validation styling and tip

<hb-input-email
  schemaentry="{&quot;id&quot;:&quot;work_email&quot;,&quot;required&quot;:true,&quot;placeholder&quot;:&quot;[email protected]&quot;,&quot;validationTip&quot;:&quot;Enter a valid work email address.&quot;}"
  show_validation="yes"
></hb-input-email>

Optional secondary email

<hb-input-email
  schemaentry="{&quot;id&quot;:&quot;backup_email&quot;,&quot;required&quot;:false,&quot;placeholder&quot;:&quot;[email protected]&quot;}"
></hb-input-email>

Length bounds (params)

<hb-input-email
  schemaentry="{&quot;id&quot;:&quot;corp_email&quot;,&quot;required&quot;:true,&quot;params&quot;:{&quot;min&quot;:6,&quot;max&quot;:254},&quot;validationTip&quot;:&quot;Adjust length to fit your policy.&quot;}"
  show_validation="yes"
></hb-input-email>

validationRegex and JSON escaping

validationRegex is a string passed to new RegExp(...). When you embed it in a schemaentry JSON attribute, follow normal JSON escaping (for example a literal dot in the pattern is often written as \\. inside the JSON string value). Building schemaentry with JSON.stringify({...}) in JavaScript avoids manual escaping mistakes.

Listening for changes (vanilla JS)

const el = document.querySelector("hb-input-email");

el.addEventListener("setVal", (e) => {
  const { value, valid, id } = e.detail;
  console.log(id, value, valid);
});

el.addEventListener("clickEnter", (e) => {
  const { value, valid, id } = e.detail;
  // handle submit-on-enter
});