@lumiastream/lumia-types 3.6.3 → 3.6.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -394,7 +394,7 @@ A field object can now contain these properties:
|
|
|
394
394
|
|
|
395
395
|
| Property | Required | Purpose | Example |
|
|
396
396
|
| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
|
|
397
|
-
| **`type`** | ✅ | UI control to render. Must be one of the `
|
|
397
|
+
| **`type`** | ✅ | UI control to render. Must be one of the `ConfigsFieldType` enum values (`input`, `textarea`, `number`, `checkbox`, `dropdown`, `multiselect`, `colorpicker`, `fontpicker`, `slider`, `imageupload`, `soundupload`, `videoupload`, `actionbutton`). | `"type": "dropdown"` |
|
|
398
398
|
| **`label`** | ✅ | Human-readable name shown in the sidebar. | `"label": "Favorite Color:"` |
|
|
399
399
|
| **`value`** | ❌ | Default value that appears the first time the user opens the overlay (also pre populates `Overlay.data`). Omit it to leave the field blank/unchecked on first load. | `"value": 18` |
|
|
400
400
|
| **`options`** | ☑️\* | Key value map of selectable choices. Required **only** for `dropdown`, `multiselect` and `slider`; ignored for other types. For `slider`, `options` supports `step`, `min`, `max`, `prefix`, `suffix`. | `"options": { "step": 5, "min": 0, "max": 100 }` |
|
|
@@ -402,13 +402,27 @@ A field object can now contain these properties:
|
|
|
402
402
|
| **`visibleIf`** | ❌ | **Conditional render rule**. Field is shown **only if** `Overlay.data[visibleIf.key]` strictly equals one of the values in `visibleIf.equals`. | `"visibleIf": { "key": "targetKey", "equals": ["yes", "maybe"] }` |
|
|
403
403
|
| **`hidden`** | ❌ | **Hard-hide rule.** When set to `true`, the field is **never displayed** in the Configs sidebar, preventing end users from altering it. The value still flows into `Overlay.data`, so the overlay can rely on it internally.<br>Useful for locking event subscriptions or other advanced settings. | `"hidden": true` |
|
|
404
404
|
|
|
405
|
-
Additional properties for text
|
|
405
|
+
Additional properties for text fields (`type: "input"` and `type: "textarea"`):
|
|
406
406
|
|
|
407
407
|
| Property | Required | Purpose | Example |
|
|
408
408
|
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- |
|
|
409
|
-
| **`placeholder`** | ❌ | Placeholder text inside the
|
|
410
|
-
| **`enableVariables`** | ❌ | When `true`, renders a variable-enabled
|
|
409
|
+
| **`placeholder`** | ❌ | Placeholder text inside the field. | `"placeholder": "Enter title..."` |
|
|
410
|
+
| **`enableVariables`** | ❌ | When `true`, renders a variable-enabled field that lets users insert variables (e.g., `{{username}}`) from a picker. | `"enableVariables": true` |
|
|
411
411
|
| **`allowedVariables`** | ❌ | When present with `enableVariables: true`, limits the top of the picker to this list. System/function variables are still available below. | `"allowedVariables": ["username", "message"]` |
|
|
412
|
+
| **`rows`** | ❌ | **`textarea` only.** Visible row count. Defaults to `4`. | `"rows": 6` |
|
|
413
|
+
|
|
414
|
+
Additional properties for media upload fields (`type: "imageupload"`, `"soundupload"`, `"videoupload"`):
|
|
415
|
+
|
|
416
|
+
| Property | Required | Purpose | Example |
|
|
417
|
+
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
|
|
418
|
+
| **`value`** | ❌ | Default asset URL. The field's `Overlay.data` value is always the uploaded asset's URL string. | `"value": "https://.../logo.png"` |
|
|
419
|
+
| **`accept`** | ❌ | Optional comma-separated MIME accept hint for the upload picker. | `"accept": "image/png,image/jpeg"` |
|
|
420
|
+
|
|
421
|
+
Additional properties for the action button (`type: "actionbutton"`):
|
|
422
|
+
|
|
423
|
+
| Property | Required | Purpose | Example |
|
|
424
|
+
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
|
|
425
|
+
| **`buttonLabel`** | ❌ | Button-text override. Defaults to the field `label`. The action button has **no persisted value** — clicking it fires the `configAction` event. | `"buttonLabel": "Reset game"` |
|
|
412
426
|
|
|
413
427
|
### Variable-enabled Input Fields
|
|
414
428
|
|
|
@@ -454,16 +468,21 @@ Before looking at the individual properties (type, label, value, options), remem
|
|
|
454
468
|
|
|
455
469
|
### Supported Field Types
|
|
456
470
|
|
|
457
|
-
| type | UI Control
|
|
458
|
-
| --------------- |
|
|
459
|
-
| `"input"` | Single-line text box
|
|
460
|
-
| `"
|
|
461
|
-
| `"
|
|
462
|
-
| `"
|
|
463
|
-
| `"
|
|
464
|
-
| `"
|
|
465
|
-
| `"
|
|
466
|
-
| `"
|
|
471
|
+
| type | UI Control | `Overlay.data` value |
|
|
472
|
+
| --------------- | --------------------------- | --------------------------------------------- |
|
|
473
|
+
| `"input"` | Single-line text box | `string` |
|
|
474
|
+
| `"textarea"` | Multi-line text area | `string` |
|
|
475
|
+
| `"number"` | Numeric input spinner | `number` |
|
|
476
|
+
| `"checkbox"` | Checkbox selection | `boolean` |
|
|
477
|
+
| `"dropdown"` | Select menu | `string` (selected option key) |
|
|
478
|
+
| `"multiselect"` | Multi-select box | `string[]` (selected option keys) |
|
|
479
|
+
| `"colorpicker"` | Color picker widget | `string` (hex/rgba) |
|
|
480
|
+
| `"fontpicker"` | Font picker (Google) | `string` (font family name) |
|
|
481
|
+
| `"slider"` | Number slider | `number` |
|
|
482
|
+
| `"imageupload"` | Image upload picker | `string` (uploaded asset URL) |
|
|
483
|
+
| `"soundupload"` | Audio upload picker | `string` (uploaded asset URL) |
|
|
484
|
+
| `"videoupload"` | Video upload picker | `string` (uploaded asset URL) |
|
|
485
|
+
| `"actionbutton"`| Clickable action button | _none_ — fires the `configAction` event |
|
|
467
486
|
|
|
468
487
|
### Font Picker
|
|
469
488
|
|
|
@@ -502,6 +521,95 @@ The key in the json an ddata must match the variable name used in the css
|
|
|
502
521
|
|
|
503
522
|
> Note we're using variable replacement within the css.
|
|
504
523
|
|
|
524
|
+
### Textarea
|
|
525
|
+
|
|
526
|
+
The `textarea` type renders a multi-line text box for long-form content. It supports the same `placeholder`, `enableVariables`, and `allowedVariables` props as `input`, plus a `rows` prop to control the visible height (defaults to `4`).
|
|
527
|
+
|
|
528
|
+
Configs Tab
|
|
529
|
+
|
|
530
|
+
```json
|
|
531
|
+
{
|
|
532
|
+
"welcomeMessage": {
|
|
533
|
+
"type": "textarea",
|
|
534
|
+
"label": "Welcome Message",
|
|
535
|
+
"rows": 6,
|
|
536
|
+
"placeholder": "Enter the message shown when the overlay loads",
|
|
537
|
+
"enableVariables": true,
|
|
538
|
+
"allowedVariables": ["username"]
|
|
539
|
+
}
|
|
540
|
+
}
|
|
541
|
+
```
|
|
542
|
+
|
|
543
|
+
The value flows into `Overlay.data.welcomeMessage` as a plain string and can be used with `{{welcomeMessage}}` replacement just like any other field.
|
|
544
|
+
|
|
545
|
+
### Media Upload Fields (Image / Sound / Video)
|
|
546
|
+
|
|
547
|
+
The `imageupload`, `soundupload`, and `videoupload` types render an asset picker tied to Lumia's media browser. Once a user picks (or uploads) an asset, the field's value is the **uploaded asset's URL string**. Each type scopes the picker to the matching media kind: images, audio, and video respectively.
|
|
548
|
+
|
|
549
|
+
Configs Tab
|
|
550
|
+
|
|
551
|
+
```json
|
|
552
|
+
{
|
|
553
|
+
"logo": {
|
|
554
|
+
"type": "imageupload",
|
|
555
|
+
"label": "Logo Image"
|
|
556
|
+
},
|
|
557
|
+
"chime": {
|
|
558
|
+
"type": "soundupload",
|
|
559
|
+
"label": "Alert Sound",
|
|
560
|
+
"accept": "audio/mpeg,audio/ogg"
|
|
561
|
+
},
|
|
562
|
+
"intro": {
|
|
563
|
+
"type": "videoupload",
|
|
564
|
+
"label": "Intro Clip"
|
|
565
|
+
}
|
|
566
|
+
}
|
|
567
|
+
```
|
|
568
|
+
|
|
569
|
+
Because the value is just a URL, you can use it directly in your HTML, CSS, or JS:
|
|
570
|
+
|
|
571
|
+
```html
|
|
572
|
+
<img src="{{logo}}" alt="logo" />
|
|
573
|
+
```
|
|
574
|
+
|
|
575
|
+
```js
|
|
576
|
+
const chime = new Audio(Overlay.data.chime);
|
|
577
|
+
chime.play();
|
|
578
|
+
```
|
|
579
|
+
|
|
580
|
+
> The optional `accept` property is a comma-separated MIME hint (e.g. `image/png,image/jpeg`). The picker is already scoped by media type, so `accept` is an extra narrowing hint and can be omitted.
|
|
581
|
+
|
|
582
|
+
### Action Button
|
|
583
|
+
|
|
584
|
+
The `actionbutton` type renders a clickable button in the Configs sidebar. Unlike every other field, it has **no persisted value** — it is a trigger, not a setting. Clicking it dispatches a `configAction` event that your overlay JS can subscribe to. Use `buttonLabel` to override the button text (it defaults to `label`).
|
|
585
|
+
|
|
586
|
+
Configs Tab
|
|
587
|
+
|
|
588
|
+
```json
|
|
589
|
+
{
|
|
590
|
+
"resetGame": {
|
|
591
|
+
"type": "actionbutton",
|
|
592
|
+
"label": "Reset",
|
|
593
|
+
"buttonLabel": "Reset game"
|
|
594
|
+
}
|
|
595
|
+
}
|
|
596
|
+
```
|
|
597
|
+
|
|
598
|
+
JS Tab
|
|
599
|
+
|
|
600
|
+
```js
|
|
601
|
+
// Fired when the user clicks an actionbutton field in the Configs sidebar.
|
|
602
|
+
// `key` is the field's JSON key; `value` is the field's optional `value`.
|
|
603
|
+
Overlay.on("configAction", ({ key, value }) => {
|
|
604
|
+
if (key === "resetGame") {
|
|
605
|
+
toast("Game reset!");
|
|
606
|
+
// run your reset logic here
|
|
607
|
+
}
|
|
608
|
+
});
|
|
609
|
+
```
|
|
610
|
+
|
|
611
|
+
> `configAction` is a Configs-driven event, not a platform event — it does not need to be declared in the Data tab's `events` array and is unaffected by the OverlayListener subscriptions.
|
|
612
|
+
|
|
505
613
|
### Field Display Order
|
|
506
614
|
|
|
507
615
|
By default, config fields are displayed in alphabetical order by their key names. You can override this behavior using the `order` property:
|
|
@@ -628,6 +736,24 @@ In this example, the fields would appear in this order:
|
|
|
628
736
|
"prefix": "",
|
|
629
737
|
"suffix": "px"
|
|
630
738
|
}
|
|
739
|
+
},
|
|
740
|
+
"bio": {
|
|
741
|
+
"order": 11,
|
|
742
|
+
"type": "textarea",
|
|
743
|
+
"label": "Bio:",
|
|
744
|
+
"rows": 4,
|
|
745
|
+
"placeholder": "Tell us about yourself"
|
|
746
|
+
},
|
|
747
|
+
"logo": {
|
|
748
|
+
"order": 12,
|
|
749
|
+
"type": "imageupload",
|
|
750
|
+
"label": "Logo:"
|
|
751
|
+
},
|
|
752
|
+
"reset": {
|
|
753
|
+
"order": 13,
|
|
754
|
+
"type": "actionbutton",
|
|
755
|
+
"label": "Reset",
|
|
756
|
+
"buttonLabel": "Reset overlay"
|
|
631
757
|
}
|
|
632
758
|
}
|
|
633
759
|
```
|
|
@@ -718,6 +844,10 @@ Custom overlay modules carry an optional `content.flavor` field that tells the r
|
|
|
718
844
|
|
|
719
845
|
If you're inspecting an imported overlay's JSON and see `"flavor": "streamelements"`, that's why it can call `SE_API.store.set(...)`, `jQuery`, etc. — none of those are part of the native Lumia overlay API, but the shim makes them available for that specific layer.
|
|
720
846
|
|
|
847
|
+
StreamElements imports also stamp a `content.sourceProvider` field (`'twitch'`, `'youtube'`, or `'kick'`, defaulting to `'twitch'`). The SE compatibility shim reads it to pick the correct listener-name mapping when forwarding Lumia events into the iframe as `onEventReceived` payloads. Hand-authored overlays don't set it.
|
|
848
|
+
|
|
849
|
+
When the import wizard translates an SE widget's fields into Lumia config fields, it maps SE control types onto the native Lumia field types — `googleFont` → `fontpicker`, `image` / `image-input` → `imageupload`, `sound-input` → `soundupload`, `video-input` → `videoupload`, `button` → `actionbutton`, and SE `hidden` fields onto a plain `input` carrying `hidden: true`. The emitted `type` is always a native `ConfigsFieldType`, so an imported overlay's Configs tab behaves identically to one you author by hand.
|
|
850
|
+
|
|
721
851
|
## Code ID
|
|
722
852
|
|
|
723
853
|
The codeId is primarily meant to be used when talking to Lumia Stream. It is used to store storage data, it is used when calling send overlay content that will only send to overlays with that specific code id. It can be retrieved within the overlay using `Overlay.on('overlaycontent', (data) => {...})`
|