@htmlbricks/hb-input-radio 0.71.35 → 0.71.37

package/README.md

@@ -1,23 +1,189 @@
-# hb-input-radio
+# `hb-input-radio`
 
-## Description
+**Category:** inputs · **Tags:** inputs
 
-Radio group built from **`schemaentry.params`** as **`InputRadioParams`**: optional **`options`** array of **`InputRadioOption`** (`value`, optional `label`). The shared native `name` is derived from the field `id`. Parses JSON `schemaentry` for initial `value` and supports required validation with Bulma `help is-danger` when `show_validation` is `yes` and invalid. Dispatches **`setVal`** with the selected string `value`, `valid`, and `id` whenever the choice changes.
+`hb-input-radio` is a Bulma-styled **radio group** web component. It reads its configuration from a single **`schemaentry`** payload (JSON in HTML, or an object when set from JavaScript), builds one native `<input type="radio">` per option under a shared **`name`** equal to the field **`id`**, and reports the current choice with a **`setVal`** custom event.
 
-## Styling (Bulma)
+The group’s accessible name comes from **`label`**, then **`id`**, then the fallback `"Options"` (`aria-label` on the `radiogroup`).
 
-Shadow bundle: `form/shared`, `form/input-textarea`, `form/checkbox-radio`, `form/tools`. Markup uses Bulma `radios` / `radio` and host outline when invalid.
+---
 
-## `schemaentry.params` (`InputRadioParams`)
+## When the component renders
+
+- If **`schemaentry`** is missing, not parseable as JSON, or not an object, **nothing** is rendered.
+- If **`params.options`** is missing or empty, the **field shell** still renders but **no radios** appear until you supply at least one option.
+
+---
+
+## Custom element
+
+| Name | Tag |
+| --- | --- |
+| `hb-input-radio` | `<hb-input-radio …></hb-input-radio>` |
+
+---
+
+## Attributes (snake_case)
+
+Web component attributes are **strings**. For booleans exposed as attributes, use **`yes`** or **`no`** (see `show_validation`).
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `schemaentry` | Yes* | Serialized field definition (JSON string from HTML). Must include a stable **`id`** and, for choices, **`params.options`**. Can be set to `undefined` / omitted in typed wrappers; the host then renders nothing. |
+| `show_validation` | No | `"yes"` or `"no"` (default **`no`**). When **`yes`**, a required group with no selection shows **`validationTip`** in a Bulma danger help line (if `validationTip` is set). |
+| `id` | No | Optional id on the host element. |
+| `style` | No | Optional inline styles on the host element. |
+
+\*Required for a usable field in markup; the TypeScript `Component` type allows `undefined` for programmatic cases.
+
+### Passing `schemaentry` from HTML
+
+Use a **single-quoted** attribute value so the JSON can use double quotes:
+
+```html
+<hb-input-radio
+  schemaentry='{"id":"plan","required":true,"label":"Plan","validationTip":"Select a plan.","params":{"options":[{"label":"Starter","value":"starter"},{"label":"Pro","value":"pro"}]}}'
+  show_validation="yes"
+></hb-input-radio>
+```
+
+From JavaScript you may assign **`element.schemaentry`** as either a **JSON string** or a **plain object**; the internal parser accepts both without mutating the prop.
+
+---
+
+## `schemaentry` shape
+
+The host expects a **`FormSchemaEntry`** compatible object (see `types/webcomponent.type.d.ts` and shared `FormSchemaEntryShared` from `hb-form`). Fields that matter for this component:
+
+| Field | Description |
+|-------|-------------|
+| `id` | **Required.** Becomes the native `name` for all radios in the group and is echoed on events as `detail.id`. |
+| `label` | Optional visible context; used for `aria-label` on the radiogroup. |
+| `required` | If true, **`valid`** is false until an option is selected. |
+| `value` | Optional initial selection; coerced with `String(...)` when the schema sync runs. |
+| `validationTip` | Message shown when **`show_validation="yes"`**, the field is invalid, and this string is set. |
+| `disabled` | If true, all radios are disabled. |
+| `readonly` | If true, all radios are disabled (same effect as `disabled` in the template). |
+| `placeholder` | Allowed by the shared schema type; **not** rendered as a separate control by this component. |
+| `params` | **`InputRadioParams`** — see below. |
+
+### `params` (`InputRadioParams`)
 
 | Key | Type | Description |
-| --- | --- | --- |
-| `options` | `InputRadioOption[]` | Each entry: **`value`**, optional **`label`** (falls back to `value` in the UI). |
+|-----|------|-------------|
+| `options` | `InputRadioOption[]` | List of choices. Each item needs a **`value`** (string). **`label`** is optional; the UI falls back to **`value`**. |
 
-## Typings
+---
 
-**`types/webcomponent.type.d.ts`** — `InputRadioParams`, `InputRadioOption`, `FormSchemaEntry`, `Component`, `Events`.
+## Validation behavior
+
+- **Required (`required: true`)**: `valid` is **false** until the user selects an option (`value` is a non-empty choice).
+- **Optional (`required: false` or omitted)**: `valid` is **true** even when nothing is selected (`value` may be `undefined`).
+- **Inline message**: Shown only when **`show_validation`** is **`yes`**, **`validationTip`** is set, and the current state is invalid.
+
+---
 
 ## Events
 
-- **`setVal`** — `{ value: string | undefined; valid: boolean; id: string }`
+| Event | `detail` | When |
+|-------|----------|------|
+| `setVal` | `{ value: string \| undefined; valid: boolean; id: string }` | Whenever **`value`**, **`valid`**, or **`id`** changes in a way that affects the payload. Duplicate payloads are suppressed. |
+
+Listen in plain JavaScript:
+
+```js
+const el = document.querySelector("hb-input-radio");
+el.addEventListener("setVal", (e) => {
+  const { value, valid, id } = e.detail;
+  console.log(id, value, valid);
+});
+```
+
+---
+
+## Styling
+
+- Bulma **form** patterns: `field`, `control`, `radios`, `radio`, and `help is-danger` for invalid feedback.
+- Theme the host with Bulma **CSS variables** on `:host` — see [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/). Public tokens used by this bundle are listed in **`extra/docs.ts`** (`styleSetup.vars`).
+
+### CSS custom properties (high level)
+
+| Variable | Role |
+|----------|------|
+| `--bulma-text` | Labels and legend-related text. |
+| `--bulma-border` | Radio outline; group border when invalid. |
+| `--bulma-link` | Checked accent where the browser supports tinting. |
+| `--bulma-danger` | Invalid outline and danger help. |
+| `--bulma-scheme-main` | Background inside the shadow root. |
+
+### `::part` selectors
+
+| Part | Targets |
+|------|---------|
+| `input` | Each native `<input type="radio">` (same part name repeated per option). |
+| `invalid-feedback` | The `p.help.is-danger` node when validation messaging is visible. |
+
+---
+
+## TypeScript
+
+Authoring types for this package live in **`types/webcomponent.type.d.ts`**:
+
+- **`InputRadioOption`**, **`InputRadioParams`**
+- **`FormSchemaEntry`** (radio-specific entry)
+- **`Component`** (host props)
+- **`Events`** (`setVal` detail)
+
+After a full web component build, generated element maps may also include this tag under **`types/html-elements.d.ts`** / **`types/svelte-elements.d.ts`**.
+
+---
+
+## Examples
+
+### Required group with validation
+
+```html
+<hb-input-radio
+  schemaentry='{"id":"tier","required":true,"label":"Tier","validationTip":"Choose a tier.","params":{"options":[{"label":"Free","value":"free"},{"label":"Paid","value":"paid"}]}}'
+  show_validation="yes"
+></hb-input-radio>
+```
+
+### Preselected value
+
+```html
+<hb-input-radio
+  schemaentry='{"id":"region","required":true,"label":"Region","value":"eu","params":{"options":[{"label":"US","value":"us"},{"label":"EU","value":"eu"}]}}'
+></hb-input-radio>
+```
+
+### Disabled group
+
+```html
+<hb-input-radio
+  schemaentry='{"id":"locked","label":"Plan","value":"pro","disabled":true,"params":{"options":[{"label":"Starter","value":"starter"},{"label":"Pro","value":"pro"}]}}'
+></hb-input-radio>
+```
+
+### Updating options from JavaScript
+
+```js
+const radio = document.querySelector("hb-input-radio");
+radio.schemaentry = JSON.stringify({
+  id: "gift",
+  required: false,
+  label: "Gift wrap",
+  params: {
+    options: [
+      { label: "No", value: "no" },
+      { label: "Yes", value: "yes" },
+    ],
+  },
+});
+```
+
+---
+
+## Related metadata
+
+Storybook knobs, CSS variables, `::part` names, and packaged examples are defined in **`extra/docs.ts`** (`componentSetup`, `styleSetup`, `examples`).

package/manifest.json

@@ -176,15 +176,46 @@
     }
   },
   "styleSetup": {
-    "vars": [],
+    "vars": [
+      {
+        "name": "--bulma-text",
+        "valueType": "color",
+        "defaultValue": "",
+        "description": "Radio labels and legend text color."
+      },
+      {
+        "name": "--bulma-border",
+        "valueType": "color",
+        "defaultValue": "",
+        "description": "Radio outline and group border when invalid."
+      },
+      {
+        "name": "--bulma-link",
+        "valueType": "color",
+        "defaultValue": "",
+        "description": "Checked radio accent (native control tint where supported)."
+      },
+      {
+        "name": "--bulma-danger",
+        "valueType": "color",
+        "defaultValue": "",
+        "description": "Invalid group outline and `help is-danger`."
+      },
+      {
+        "name": "--bulma-scheme-main",
+        "valueType": "color",
+        "defaultValue": "",
+        "description": "Background for the radios block inside the shadow root."
+      }
+    ],
     "parts": [
       {
         "name": "input",
-        "description": ""
+        "description": "Each native `<input type=\"radio\">` in the group (same part name repeated per option)."
       },
       {
         "name": "invalid-feedback",
-        "description": ""
+        "description": "The `p.help.is-danger` message when `show_validation` is `yes` and a required choice is missing."
       }
     ]
   },
@@ -344,5 +375,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-input-radio",
-  "version": "0.71.35"
+  "version": "0.71.37"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-input-radio",
-  "version": "0.71.35",
+  "version": "0.71.37",
   "contributors": [],
   "description": "Radio group from `schemaentry.params` as `InputRadioParams`: optional `options` array of `InputRadioOption` (`value`, optional `label`); the native `name` matches the field `id`. Initial `value` is stringified from `schemaentry`. Required + `show_validation` use Bulma `radios` / `radio` and `help is-danger`. Dispatches `setVal` `{ value, valid, id }` when the selection changes. Theme `--bulma-*` on `:host`. Typings: `InputRadioParams`, `InputRadioOption`, `FormSchemaEntry`, `Component`, `Events`.",
   "licenses": [