{"id":20719283,"url":"https://github.com/userscripters/userscripts-configurer","last_synced_at":"2025-04-14T06:23:18.341Z","repository":{"id":36987690,"uuid":"488173506","full_name":"userscripters/userscripts-configurer","owner":"userscripters","description":"One configurer to setup them all","archived":false,"fork":false,"pushed_at":"2025-04-12T23:14:55.000Z","size":1861,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-13T00:20:18.543Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/userscripters.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-03T11:00:47.000Z","updated_at":"2025-04-12T23:14:58.000Z","dependencies_parsed_at":"2023-02-15T19:30:30.691Z","dependency_job_id":"63e5b441-28a8-401b-9434-1e4ff03fe58b","html_url":"https://github.com/userscripters/userscripts-configurer","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":"userscripters/template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/userscripters%2Fuserscripts-configurer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/userscripters%2Fuserscripts-configurer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/userscripters%2Fuserscripts-configurer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/userscripters%2Fuserscripts-configurer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/userscripters","download_url":"https://codeload.github.com/userscripters/userscripts-configurer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248831181,"owners_count":21168413,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-17T03:16:41.264Z","updated_at":"2025-04-14T06:23:18.291Z","avatar_url":"https://github.com/userscripters.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# About\n\n| Author       | Oleg Valter\u003cbr\u003e[oleg.a.valter@gmail.com](mailto:oleg.a.valter@gmail.com) |\n| :----------- | :----------------------- |\n| Name | @userscripters/userscripts-configurer |\n| Description | One script to configure them all |\n| License | [GPL-3.0-or-later](https://spdx.org/licenses/GPL-3.0-or-later) |\n| Version | 2.1.1 |\n\nUserScripts Configurer is a shared configuration controller for UserScripters' userscripts.\n\n### How to use\n\nConfigurer is exposed as a global accessible via `UserScripters.Userscripts.Configurer`.\nTo ensure the Configurer is done loading, including scripts are encouraged to listen to a `userscript-configurer-load` event on `unsafeWindow` before hooking:\n\n```lang-ts\nunsafeWindow.addEventListener(\"userscript-configurer-load\", () =\u003e {\n    // it is safe to hook into the configurer now\n});\n```\n\nTo hook to the Configurer, call its `register` method with the name of the userscript as its single parameter:\n\n```lang-ts\nconst configurer = UserScripters.Userscripts.Configurer;\nconst script = configurer.register(\"Auto Review Comments\");\n```\n\nThe method will return an instance of `Userscript` to which options (if any) can be added by calling its `option` method with 2 parameters. The 1\u003csup\u003est\u003c/sup\u003e is the option's name, the 2\u003csup\u003end\u003c/sup\u003e is its configuration. The configurer currently supports 4 types of options (`type` field):\n\n- text input\n- checkboxes\n- toggle switch\n- select\n\nIf you want to ensure a `Userscript` or an `Option` is registered only once, both classes have a `has` method that accepts a `name` and returns a `boolean`:\n\n```lang-ts\n// ensure the script hasn't been registered\nif(!configurer.has(\"my-script\")) {\n    configurer.register(\"my-script\");\n}\n\n// ensure the option hasn't been registered\nif(!script.has(\"my-option\") {\n    script.option(\"my-option\", { type: \"text\" });\n}\n```\n\nOption config interface (as well as the interface of the Configurer itself) is described by our [Global Types](https://github.com/userscripters/global-types) type definitions package.\n\n```lang-ts\n// text input option\nscript.option(\n    \"welcome-text\",\n    {\n        def: \"Welcome to Stack Overflow\",\n        title: \"Greeting text\",\n        type: \"text\",\n    }\n);\n\n// checkbox option\nscript.option(\"prefer-diff-view\", {\n    items: [{\n        label: \"Use diff view\",\n        value: true\n    }],\n    type: \"checkbox\",\n});\n\n//toggle option\nscript.option(\"prefer-diff-view\", {\n    direction: \"left\", // aligns levers to the left of the title\n    selected: true,\n    title: \"Prefer diff view\",\n    type: \"toggle\",\n});\n\n// select option\nscript.option(\"style\", {\n    items: [\n        { label: \"Simple\", value: \"simple\" },\n        { label: \"Full\", value: \"full\", selected: true }\n    ],\n    title: \"Reference style\",\n    type: \"select\",\n});\n```\n\n---\n\nAs of version 2.0.0, options can have disabled state conditions ensuring a given option can be dynamically disabled based on the values of other options.\nTo add conditions, pass a `disabledWhen` dictionary to the option config. The dictionary is keyed on option *names* with values corresponding to one of the options' values.\nWhen the value of the option specified in the dictionary matches the one in storage, the option the dictionary belongs to will be disabled and vice versa otherwise.\nAn example option configuration looks like this:\n\n```\n// an option that will be disabled if 'prefer-diff-view' is false\nscript.option(\"dependent\", {\n    disabledWhen: {\n        [\"prefer-diff-view\"]: false,\n    },\n    title: \"Dependent option\",\n    type: \"toggle\",\n});\n```\n\nOptions can be added in bulk as a record of name-config pairs via the `options` method. An optional second parameter can provide shared config options:\n\n```lang-ts\nscript.options({\n    welcome: {\n        def: \"Welcome to Stack Overflow\",\n        title: \"Greeting text\",\n    },\n}, {\n    type: \"text\",\n});\n```\n\nOn value change, the Configurer dispatches a custom *bubbling* event on the registered script's `container` with the following `detail`:\n\n```lang-ts\ninterface ChangeEventDetail {\n    name: string,\n    script: string,\n    oldValue: string | boolean | string[],\n    value: string | boolean | string[],\n}\n```\n\nThe custom event can be listened to via the `userscript-configurer-change` event name:\n\n```lang-ts\nwindow.addEventListener(\"userscript-configurer-change\", ({ detail }) =\u003e {\n    // do something with the change data\n});\n```\n\n---\n\nAs of version 2.1.0, end users can configure where the button toggling the options modal will be rendered in the UI:\n\n![configuration option for choosing the controller button position](https://i.stack.imgur.com/hSwSM.png)\n\nBy default, the button is still displayed in the sidebar slightly above the expandable modal. There are 2 other options users can choose instead:\n\n1. As an icon button in the top navigation bar\n\n    ![top navigation bar icon button position](https://i.stack.imgur.com/OD9Mt.png)\n\n2. As a link button in the footer under the \"Data\" link in the \"Stack Exchange Network\" column\n\n    ![footer button position](https://i.stack.imgur.com/NrRfq.png)\n\n---\n\nThe Configurer uses a [userscript manager-agnostic storage](https://github.com/userscripters/storage) that also works with `localStorage` if manager storages are inaccessible.\n\n\n# Support\n\nBug reports for the project should be [submitted here](https://github.com/userscripters/userscripts-configurer/issues).\n\u003cbr\u003eBefore adding a new one, please check if it hasn't been raised before.\n  ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuserscripters%2Fuserscripts-configurer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuserscripters%2Fuserscripts-configurer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuserscripters%2Fuserscripts-configurer/lists"}