stash

stash/config/plugins/community/CommunityScriptsUILibrary/README.md

@@ -0,0 +1,90 @@
+# CommunityScripts UI Plugin library
+
+This is a set of slimmed down functions from StashUserscriptLibrary, targeting CommunityScripts originally introduced in [#319](https://github.com/stashapp/CommunityScripts/pull/319)
+
+
+## functions
+All the following functions are exposed under `window.csLib` and `csLib`
+
+## callGQL
+```js
+/**
+   * This is a wrapped GraphQL (GQL) query caller
+   * @param {...Object} reqData
+   * @param {Object} reqData.query - GraphQL query
+   * @param {Object}= reqData.variables - GraphQL variables
+   * @returns {Object} - GQL response data with the `data` wrapper removed
+   * 
+   * @example
+   *   // fetch the count of organized scenes
+   *   const filter = { organized: true };
+   *   const query = `query findScenes($filter: SceneFilter) { findScenes(filter: $filter) { count } }`;
+   *   const variables = { filter };
+   *   const response = await callGQL({ query, variables });
+   *   // response = { findScenes: { count: 3 } }
+   */
+```
+
+## getConfiguration
+```js
+/**
+   * Get configuration of a plugin from the server via GraphQL
+   * @param {string} pluginId - The ID of the plugin as it is registered in the server
+   * @param {*}= fallback - Fallback value if the configuration is not found. Defaults to an empty object
+   * @returns {Object} - The configuration object of the plugin as it is stored in the server
+   * 
+   * @example
+   *    // set default config
+   *    const defaultConfig = { enabled: true, theme: 'light' };
+   *    // fetch config from the server
+   *    const config = await getConfiguration('CommunityScriptsUIPlugin', defaultConfig);
+   *    // config = { theme: 'dark' }
+   *    // merge fetched with default config
+   *    const pluginConfig = {
+   *      ...defaultConfig
+   *      ...config
+   *    };
+   *    // pluginConfig = { enabled: true, theme: 'dark' }
+   * }
+   */
+```
+
+## setConfiguration
+```js
+/**
+   * Set configuration of a plugin in the server via GraphQL
+   * @param {string} pluginId - The ID of the plugin as it is registered in the server
+   * @param {*} values - The configuration object with the values you want to save in the server
+   * @returns {Object} - The configuration object of the plugin as it is stored in the server after update
+   *
+   * @example
+   *    // fetch config from the server
+   *    const config = await getConfiguration('CommunityScriptsUIPlugin', defaultConfig);
+   *    // config = { theme: 'dark' }
+   *    // update the config based on user input
+   *    // config = { theme: 'light' }
+   *    // save config in the server
+   *    await setConfiguration('CommunityScriptsUIPlugin', config);
+   * }
+   */
+```
+
+## waitForElement
+```js
+  /**
+   * Waits for an element to be available in the DOM and runs the callback function once it is
+   * @param {string} selector - The CSS selector of the element to wait for
+   * @param {function} callback - The function to be called once the element is available (with the element as an argument)
+   * @returns 
+   * 
+   * @example
+   *   // wait for the element with the class 'my-element' to be available
+   *   // and change its color to red
+   *   function myCallback(el) {
+   *     el.style.color = 'red';
+   *    };
+   *    waitForElement('.my-element', myCallback);
+   */
+```
+
+## pathElementListener