# hb-input-area

**Category:** inputs · **Tags:** inputs · **Package:** `@htmlbricks/hb-input-area`

## Summary

Bulma **textarea** in the shadow root, driven by **`schemaentry`** (same shape as **`hb-form`** rows). Emits **`setVal`** and **`clickEnter`** (Enter without Shift).

Typings: `InputAreaParams`, `FormSchemaEntry`, `Component`, `Events` in `types/webcomponent.type.d.ts`.

## Behavior

- **Rendering:** If `schemaentry` is missing, invalid JSON, or otherwise unparsable, the component renders nothing until a valid object is provided.
- **Value sync:** When the fingerprint of `schemaentry` changes, the textarea value is reset from `schemaentry.value` when that property is present; otherwise the value becomes an empty string.
- **Live updates:** The component dispatches **`setVal`** whenever `value`, `valid`, or the field `id` changes (and redundant identical payloads are skipped). The field must have an **`id`** for `setVal` to be emitted.
- **Enter key:** **Enter** without **Shift** prevents the default newline and dispatches **`clickEnter`**. **Shift+Enter** keeps default behavior so users can insert line breaks.
- **Optional `label`:** The shared schema type allows `label`, but this web component’s markup does not render a separate label element; use your host page or a wrapping layout for captions if you need a visible title.

## Validation rules

Validation affects the `valid` flag in events and, when **`show_validation="yes"`** and the field is **`required`**, the `is-success` / `is-danger` classes on the textarea and the optional **`invalid-feedback`** part.

| Mode | `valid` |
| --- | --- |
| No parsed field | `false` |
| **`required: true`** and empty value | `false` |
| **`required: true`** with non-empty value | `true` only if `validationRegex` matches (when set), length ≥ `params.min` (when set), and length ≤ `params.max` (when set) |
| **`required`** not set or **`required: false`** | Always `true` (regex and `min` / `max` are not applied in this branch) |

`params.min` and `params.max` are **inclusive** character counts on the current string value.

## Styling

The shadow tree loads Bulma 1.x form modules (including textarea-related pieces) via `styles/bulma.scss`. Theme the control with **`--bulma-*`** custom properties on **`:host`** (see [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/)).

### CSS custom properties

| Variable | Role |
| --- | --- |
| `--bulma-primary` | Focus ring and valid-state accents |
| `--bulma-danger` | Invalid border and danger help text |
| `--bulma-border` | Default textarea border |
| `--bulma-text` | Text color inside the control |
| `--bulma-radius` | Corner radius |

### CSS parts

| Part | Target |
| --- | --- |
| `input` | The `<textarea>` element |
| `invalid-feedback` | The `help is-danger` line shown when validation feedback is enabled and the value is invalid |

### Slots

This component does not declare any slots.

## Custom element

```text
hb-input-area
```

## Attributes (snake_case)

Web component attributes are **strings**. Booleans use **`yes`** / **`no`**. Complex objects must be **JSON strings** (escape quotes correctly in HTML).

| Attribute | Required | Description |
| --- | --- | --- |
| `schemaentry` | Yes | JSON string (HTML) or object (JS); see below. |
| `show_validation` | No | `"yes"` or `"no"` (default **`no`**). When `"yes"` and the field is required, invalid state shows danger styling and `validationTip` under the textarea when invalid. |
| `id` | No | Optional host id string (component props typing). |
| `style` | No | Optional inline style string (component props typing). |

### `schemaentry` JSON shape

The payload follows **`FormSchemaEntryShared`** (from `hb-form` typings) with `params` narrowed to **`InputAreaParams`** for this control.

**Commonly used keys**

| Key | Description |
| --- | --- |
| `id` | **Required.** Field identifier; also used in event payloads. |
| `type` | Optional discriminator for form rows; may be omitted when the tag already implies a textarea. |
| `label` | Optional; not rendered by this component’s template. |
| `value` | Optional initial content (coerced with `String(...)`). |
| `placeholder` | Optional placeholder text. |
| `readonly` | Optional boolean in JSON. |
| `disabled` | Optional boolean in JSON. |
| `required` | Optional boolean in JSON. |
| `validationRegex` | Optional string; compiled with `new RegExp(...)`. |
| `validationTip` | Optional message shown in the danger help line when invalid and `show_validation` is enabled. |
| `dependencies` | Optional; carried in the shared schema type for form use cases. |
| `params` | Optional **`InputAreaParams`**: `min` / `max` inclusive length bounds (numbers in JSON). |

## Events

Listen with `addEventListener` or framework equivalents on the host element.

| Event | `detail` |
| --- | --- |
| `setVal` | `{ value: string; valid: boolean; id: string }` |
| `clickEnter` | `{ value: string; valid: boolean; id?: string }` |

## Usage examples

### Minimal host markup

```html
<hb-input-area
  schemaentry="{&quot;id&quot;:&quot;notes&quot;,&quot;label&quot;:&quot;Notes&quot;,&quot;placeholder&quot;:&quot;Type here…&quot;}"
  show_validation="no"
></hb-input-area>
```

### Required field with visible validation

```html
<hb-input-area
  schemaentry="{&quot;id&quot;:&quot;notes&quot;,&quot;required&quot;:true,&quot;placeholder&quot;:&quot;Notes (required)&quot;,&quot;validationTip&quot;:&quot;Please enter at least a few characters.&quot;}"
  show_validation="yes"
></hb-input-area>
```

### Length bounds (required field)

```html
<hb-input-area
  schemaentry="{&quot;id&quot;:&quot;bio&quot;,&quot;required&quot;:true,&quot;params&quot;:{&quot;min&quot;:10,&quot;max&quot;:500},&quot;validationTip&quot;:&quot;10–500 characters.&quot;}"
  show_validation="yes"
></hb-input-area>
```

### Listening from JavaScript

```js
const el = document.querySelector("hb-input-area");

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

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

## TypeScript

`types/webcomponent.type.d.ts` — `schemaentry` is typed as `string | FormSchemaEntry | undefined` for HTML vs JS consumers.

## Integration with `hb-form`

`schemaentry` matches the shared form row shape so the same JSON you would use in a form schema (for an area / textarea row) can be passed into this standalone control. Coordinate `id` with your surrounding form state and use `setVal` to keep parent models in sync.