# `hb-input-text`

Single-line text input (`<input type="text">`) styled with Bulma inside the shadow root. The field is configured entirely through the **`schemaentry`** payload (JSON object or JSON string). The component reports value and validity with **`setVal`** and emits **`clickEnter`** when the user presses Enter.

## When to use it

Use **`hb-input-text`** for plain text capture in forms or standalone pages where you want Bulma field styling, optional length and regex checks (for **required** fields), and typed custom events instead of wiring `input` yourself.

## Attributes (web component)

HTML attributes and reflected properties are **strings**. Boolean-like flags use **`yes`** / **`no`** where noted.

| Attribute | Values | Description |
| --- | --- | --- |
| `schemaentry` | JSON string | Serialized **`FormSchemaEntry`** for this field (see below). Required for UI; invalid or missing JSON yields no rendered field. May be set as a property with an object in JavaScript frameworks that support non-string props. |
| `show_validation` | `yes` / `no` (default `no`) | When `yes`, applies Bulma **`is-success`** / **`is-danger`** on the input for **required** fields and shows **`validationTip`** in **`::part(invalid-feedback)`** while invalid. |
| `id` | string | Optional host id (separate from the field id inside `schemaentry`). |
| `style` | string | Optional inline style on the host element. |

Pass **`schemaentry`** as a **JSON string** from HTML, for example:

```html
<hb-input-text schemaentry='{"id":"username","label":"Username","placeholder":"Your name","required":true}'></hb-input-text>
```

Adjust attribute quoting for your templating system. In JavaScript you can assign **`schemaentry`** as an object if your integration passes object props to the custom element.

## `schemaentry` shape

Authoritative TypeScript types live in **`types/webcomponent.type.d.ts`** (`InputTextParams`, `FormSchemaEntry`, `Component`, `Events`). The JSON object extends the shared form row shape with a typed optional **`params`** object.

| Property | Type / notes | Description |
| --- | --- | --- |
| `id` | string | **Required.** Becomes the native `<input>` **`id`** and is included in event payloads. |
| `type` | string | Optional discriminator for **`hb-form`** rows; may be omitted when this element is used alone. |
| `label` | string | Optional. Present on the shared schema for form tooling; **this web component does not render a label**—place headings or `<label for="…">` in the light DOM if needed. |
| `value` | string | Optional initial / controlled value (coerced with **`String(...)`** when synced from schema). |
| `placeholder` | string | Optional placeholder text. |
| `readonly` | boolean | Optional; maps to the input **`readonly`** attribute. |
| `disabled` | boolean | Optional; disables the control. |
| `required` | boolean | When truthy, validation runs (see below) and visual validation classes apply if **`show_validation`** is **`yes`**. |
| `validationRegex` | string | Optional **string** form of a JavaScript regex (passed to **`new RegExp(...)`**). Evaluated only for **required** fields when the value is non-empty. |
| `validationTip` | string | Message shown in **`::part(invalid-feedback)`** when invalid and **`show_validation`** is **`yes`**. |
| `dependencies` | array | Optional; carried on the shared schema type for form systems—**not used** by this component’s template. |
| `params` | object | Optional **`InputTextParams`** (see next section). |

### `params` (`InputTextParams`)

| Key | Type | Description |
| --- | --- | --- |
| `min` | number | Inclusive **minimum string length**. Used only when **`required`** is truthy. If omitted, length is not enforced from below (implementation treats missing **`min`** as no minimum other than “non-empty” when required). |
| `max` | number | Inclusive **maximum string length**. Used only when **`required`** is truthy. If omitted, an internal upper bound is used so very long strings still pass unless you set **`max`** explicitly. |

## Validation behavior

- **`required`** is falsy: **`valid`** is always **`true`**. **`validationRegex`**, **`params.min`**, and **`params.max`** are **not** applied. **`setVal`** still fires as the user types with **`valid: true`** (once `schemaentry` is parsed and **`id`** is present).
- **`required`** is truthy:
  - Empty value ⇒ **`valid: false`**.
  - Non-empty value ⇒ if **`validationRegex`** is set, the whole value must match the regex.
  - Length: value length must be **≥ `params.min`** when **`min`** is set (including **`0`**), and **≤ `params.max`** when **`max`** is set.
- Success / danger Bulma classes and the danger help line only appear when **`show_validation="yes"`** **and** the field is **required**.

## Events

Listen with **`addEventListener`** or framework equivalents.

| Event | `detail` | When |
| --- | --- | --- |
| **`setVal`** | `{ value: string; valid: boolean; id: string }` | Whenever **`value`** or **`valid`** changes (deduplicated when unchanged). Requires a parsed **`schemaentry`** with **`id`**. |
| **`clickEnter`** | `{ value: string; valid: boolean; id?: string }` | User presses **Enter** in the input; default is prevented. **`id`** matches **`schemaentry.id`** when present. |

Authoring types for both events are in **`types/webcomponent.type.d.ts`** (`Events`).

## Styling

The shadow root bundles Bulma **form** modules (see **`styles/bulma.scss`**). Theme the control from a parent document by setting **`--bulma-*`** custom properties on **`hb-input-text`** (or inherited from **`body`** / **`:root`** depending on your setup).

### CSS custom properties

| Variable | Role |
| --- | --- |
| `--bulma-text` | Label-like copy, input text, and help text color. |
| `--bulma-border` | Neutral input border before success / danger modifiers. |
| `--bulma-danger` | Invalid (**`is-danger`**) border and feedback emphasis. |
| `--bulma-success` | Valid (**`is-success`**) accents when validation feedback is shown. |
| `--bulma-scheme-main` | Input surface / scheme-driven background where Bulma maps scheme to controls. |

### CSS parts

| Part | Role |
| --- | --- |
| **`invalid-feedback`** | The **`p.help.is-danger`** node that shows **`validationTip`** when **`show_validation`** is **`yes`** and the field is invalid. |

### Slots

None. Layout and copy come only from **`schemaentry`**.

## TypeScript

For authoring and wrappers, import or mirror the types in **`types/webcomponent.type.d.ts`**. After a full web component build, generated **`types/html-elements.d.ts`** and **`types/svelte-elements.d.ts`** under the package describe the custom element and DOM typings.

## Examples

**Minimal optional field** (always valid; no success/danger styling unless you treat it as required elsewhere):

```html
<hb-input-text schemaentry='{"id":"nickname","placeholder":"Optional nickname"}'></hb-input-text>
```

**Required field with validation message and Bulma states:**

```html
<hb-input-text
  show_validation="yes"
  schemaentry='{"id":"code","required":true,"placeholder":"2–6 chars","validationTip":"Enter between 2 and 6 characters.","params":{"min":2,"max":6}}'
></hb-input-text>
```

**Disabled with initial value:**

```html
<hb-input-text
  schemaentry='{"id":"email_display","label":"Email","value":"user@example.com","disabled":true,"placeholder":"Locked"}'
></hb-input-text>
```

```js
const el = document.querySelector("hb-input-text");
el.addEventListener("setVal", (e) => {
  console.log(e.detail.id, e.detail.value, e.detail.valid);
});
el.addEventListener("clickEnter", (e) => {
  if (e.detail.valid) submit(e.detail);
});
```

## Related files

| File | Purpose |
| --- | --- |
| `component.wc.svelte` | Implementation, events, and Bulma markup. |
| `types/webcomponent.type.d.ts` | **`Component`**, **`Events`**, **`FormSchemaEntry`**, **`InputTextParams`**. |
| `extra/docs.ts` | Storybook metadata, **`styleSetup`**, and example payloads. |
| `styles/bulma.scss` / `styles/webcomponent.scss` | Bulma forwarding and component-specific shadow styles. |