@tixyel/streamelements 7.6.8 → 7.8.0

package/dist/index.d.ts

@@ -2468,7 +2468,55 @@ declare class ElementHelper {
          */
         skipWhitespaceIndex?: boolean;
     }): string;
+    /**
+     * Retrieves CSS variables defined in the stylesheets of the document for a given selector, with optional filtering and helper variable exclusion.
+     * @param selector - The CSS selector to search for (default is ':root' to target global variables).
+     * @param filter - A function to filter the retrieved CSS variables. It receives each variable as a [key, value] pair, along with its index and the full array of variables. Should return true to include the variable in the results.
+     * @param options - Optional settings for retrieving CSS variables, including filterHelpers to exclude common helper variables (those ending with -min, -max, or -step).
+     * @returns - An array of [key, value] pairs representing the CSS variables that match the selector and filter criteria.
+     * @example
+     * ```javascript
+     * // Retrieve all CSS variables defined under :root
+     * const variables = getElementCSSVariables();
+     * console.log(variables);
+     * // Retrieve CSS variables defined under a specific selector, e.g., .my-class
+     * const classVariables = getElementCSSVariables('.my-class');
+     * console.log(classVariables);
+     * // Retrieve CSS variables with a custom filter, e.g., only variables that include 'color' in their name
+     * const colorVariables = getElementCSSVariables(':root', ([key]) => key.includes('color'));
+     * console.log(colorVariables);
+     */
+    getElementCSSVariables(selector?: string, filter?: ([k, v]: [string, string], i: number, array: [string, string][]) => boolean, options?: {
+        filterHelpers?: boolean;
+    }): [string, string][];
+    /**
+     * Applies CSS styles to an HTML or SVG element, supporting both standard and custom properties, as well as '!important' values.
+     * @param element - The target HTML or SVG element to which the styles will be applied.
+     * @param styles - An object containing CSS property-value pairs. Property names can be in camelCase or kebab-case, and values can include '!important'.
+     * @example
+     * ```javascript
+     * CSS(document.getElementById('myElement'), {
+     *   backgroundColor: 'red',
+     *   '--custom-var': '10px',
+     *   color: 'blue !important',
+     * });
+     * ```
+     */
+    CSS(element: HTMLElement | SVGElement, styles: Partial<Record<keyof CSSStyleProperties | `--${string}`, CSSValue>>): void;
+    /**
+     * Escapes special HTML characters in a string to prevent XSS attacks and ensure safe rendering in HTML contexts.
+     * @param value - The input string that may contain special HTML characters such as &, <, >, ", and '.
+     * @returns A new string with special HTML characters replaced by their corresponding HTML entities.
+     * @example
+     * ```javascript
+     * const unsafeString = '<script>alert("XSS")</script>';
+     * const safeString = escapeHtml(unsafeString);
+     * console.log(safeString); // Output: '&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;'
+     * ```
+     */
+    escapeHtml(value: string): string;
 }
+type CSSValue = string | number | null | undefined;
 
 declare class ObjectHelper {
     /**
@@ -3061,7 +3109,7 @@ declare class UtilsHelper {
         userId: string;
         name: string;
         broadcasterId?: string;
-    }, session: StreamElements.Session.Data, checkWithAPI?: boolean): Promise<3 | 1 | 2>;
+    }, session: StreamElements.Session.Data, checkWithAPI?: boolean): Promise<1 | 2 | 3>;
     /**
      * Identifies a user based on the received event and session data, returning their ID, name, role, badges, and top status.
      * @param receivedEvent - The event received from the provider (Twitch or YouTube) containing user information.
@@ -3400,6 +3448,105 @@ declare class AnimateHelper {
     sequence(animations: AnimResult[], delayFrames?: number | number[]): AnimResult;
 }
 
+declare class SEHelper {
+    /**
+     * Assign StreamElements custom field schemas from a given data object, with optional prefixing and grouping
+     * @param data - Object containing StreamElements custom field schemas to assign
+     * @param prefix - Optional string to prefix each field key with
+     * @param assign - Optional object to assign the resulting field schemas to (defaults to a new object)
+     * @param group - Optional string to group the fields under (will use existing group if not provided)
+     * @returns - Object containing the assigned StreamElements custom field schemas
+     * @example
+     * ```javascript
+     * const data = {
+     *   'field1': { type: 'text', label: 'Field 1', value: 'Value 1' },
+     *   'field2': { type: 'colorpicker', label: 'Field 2', value: '#ff0000' },
+     *   'field3': { type: 'number', label: 'Field 3', value: 10, min: 0, max: 100, step: 1 },
+     * }
+     *
+     * const fields = assignFields(data, 'prefix-', {}, 'Group 1');
+     *
+     * console.log(fields);
+     * // Output:
+     * // {
+     * //   'prefix-field1': { type: 'text', label: 'Field 1', value: 'Value 1', group: 'Group 1' },
+     * //   'prefix-field2': { type: 'colorpicker', label: 'Field 2', value: '#ff0000', group: 'Group 1' },
+     * //   'prefix-field3': { type: 'number', label: 'Field 3', value: 10, min: 0, max: 100, step: 1, group: 'Group 1' },
+     * // }
+     * ```
+     */
+    assignFields(data: Record<string, StreamElements.CustomField.Schema>, prefix?: string, assign?: Record<string, StreamElements.CustomField.Schema>, group?: string): Record<string, StreamElements.CustomField.Schema> | undefined;
+    /**
+     * Check for errors in StreamElements custom fields and throw an error if any are found
+     * @param fields - Object containing StreamElements custom field schemas to check for errors
+     * @throws Will throw an error if any custom field has a label that includes 'undefined', if a non-hidden/button field has an undefined value, or if a hidden/button field has an undefined label
+     * @example
+     * ```javascript
+     * const fields = {
+     *   'field1': { type: 'text', label: 'Field 1', value: 'Value 1' },
+     *   'field2': { type: 'colorpicker', label: 'Field 2', value: '#ff0000' },
+     *  'field3': { type: 'hidden', label: 'Hidden Field' },
+     *  'field4': { type: 'button', label: 'Button Field' },
+     *  'field5': { type: 'text', label: 'Undefined Value Field' },
+     * }
+     *
+     * checkFieldErrors(fields);
+     *
+     * // Output:
+     * //  Error: StreamElements custom fields have errors: field5 (Undefined Value Field)
+     * ```
+     */
+    checkFieldErrors(fields: Record<string, StreamElements.CustomField.Schema>): void;
+    /**
+     * Transform CSS variables into StreamElements custom fields
+     * @param data - Array of CSS variable entries (name and value)
+     * @param method - Whether to determine field type based on variable name or value
+     * @param replace - Function to modify the field label based on the variable name
+     * @param subgroup - Function to determine subgrouping of fields based on variable name and value
+     * @returns - Object containing StreamElements custom field schemas
+     * @example
+     * ```javascript
+     * const cssVariables = [
+     *   ['--primary-gradient-color', '#ff0000'],
+     *   ['--secondary-gradient-color', '#00ff00'],
+     * ];
+     * const fields = transformCSSIntoFields(
+     *   cssVariables,
+     *   'name',
+     *   (x) => x.replace('gradient', '').trim(),
+     *   (key, value) => {
+     *     if (key.includes('gradient')) return 'Gradients';
+     *     return null;
+     *   }
+     * );
+     *
+     * console.log(fields);
+     *
+     * /* Output:
+     *   {
+     *     '/Gradients': {
+     *       type: 'hidden',
+     *       label: 'Gradients',
+     *     },
+     *     '--primary-gradient-color': {
+     *       type: 'colorpicker',
+     *       label: 'Primary color',
+     *       value: '#ff0000',
+     *     },
+     *     '--secondary-gradient-color': {
+     *       type: 'colorpicker',
+     *       label: 'Secondary color',
+     *       value: '#00ff00',
+     *     },
+     *   }
+     * ```
+     */
+    transformCSSIntoFields(data: [string, string][], method?: 'name' | 'value', replace?: (name: string) => string, subgroup?: (key: string, value: string) => string | null): Record<string, StreamElements.CustomField.Schema>;
+    splitFieldLabel(keyPrefix: string, text: string, maxLabelLength?: number): {
+        [k: string]: StreamElements.CustomField.Schema;
+    };
+}
+
 declare namespace Helper {
     const animate: AnimateHelper;
     const number: NumberHelper;
@@ -3413,6 +3560,7 @@ declare namespace Helper {
     const random: RandomHelper;
     const fn: FunctionHelper;
     const utils: UtilsHelper;
+    const streamelements: SEHelper;
 }
 
 declare class Emulator {