{"id":22131954,"url":"https://github.com/seaofvoices/menu-handler","last_synced_at":"2026-02-10T20:32:28.839Z","repository":{"id":231734141,"uuid":"782568609","full_name":"seaofvoices/menu-handler","owner":"seaofvoices","description":"A crosswalk client module to handle UI menus using tagged instances","archived":false,"fork":false,"pushed_at":"2025-01-23T18:49:45.000Z","size":35,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-23T14:33:22.086Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seaofvoices.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null},"funding":{"github":["jeparlefrancais"],"ko_fi":"seaofvoices"}},"created_at":"2024-04-05T15:02:51.000Z","updated_at":"2025-01-23T18:49:01.000Z","dependencies_parsed_at":"2025-01-23T16:31:43.738Z","dependency_job_id":"2b0944ca-cbc4-4254-b84a-bac523b28f53","html_url":"https://github.com/seaofvoices/menu-handler","commit_stats":null,"previous_names":["seaofvoices/menu-handler"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/seaofvoices/menu-handler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seaofvoices%2Fmenu-handler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seaofvoices%2Fmenu-handler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seaofvoices%2Fmenu-handler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seaofvoices%2Fmenu-handler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seaofvoices","download_url":"https://codeload.github.com/seaofvoices/menu-handler/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seaofvoices%2Fmenu-handler/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29314705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-10T17:48:59.043Z","status":"ssl_error","status_checked_at":"2026-02-10T17:45:37.240Z","response_time":65,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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-12-01T18:38:36.966Z","updated_at":"2026-02-10T20:32:28.813Z","avatar_url":"https://github.com/seaofvoices.png","language":"Lua","funding_links":["https://github.com/sponsors/jeparlefrancais","https://ko-fi.com/seaofvoices"],"categories":["Roblox"],"sub_categories":[],"readme":"[![checks](https://github.com/seaofvoices/menu-handler/actions/workflows/test.yml/badge.svg)](https://github.com/seaofvoices/menu-handler/actions/workflows/test.yml)\n![version](https://img.shields.io/github/package-json/v/seaofvoices/menu-handler)\n[![GitHub top language](https://img.shields.io/github/languages/top/seaofvoices/menu-handler)](https://github.com/luau-lang/luau)\n![license](https://img.shields.io/npm/l/@crosswalk-game/menu-handler)\n![npm](https://img.shields.io/npm/dt/@crosswalk-game/menu-handler)\n\n# MenuHandler\n\nA [crosswalk](https://github.com/seaofvoices/crosswalk) client module to handle UI menus using tagged instances (built with the [tag-effect library](https://github.com/seaofvoices/tag-effect)).\n\n## Installation\n\nAdd `@crosswalk-game/menu-handler` in your dependencies:\n\n```bash\nyarn add @crosswalk-game/menu-handler\n```\n\nOr if you are using `npm`:\n\n```bash\nnpm install @crosswalk-game/menu-handler\n```\n\n## Content\n\n- [open](#openmenuid-string)\n- [push](#pushmenuid-string)\n- [back](#back)\n- [close](#closemenuid-string)\n- [toggle](#togglemenuid-string)\n- [whileOpened](#whileopenedmenuid-string-effect----teardown----)\n\n- [Tag effects](#tag-effects)\n  - [MenuInstance of MenuExtension](#menuinstance-or-menuextension)\n  - [Menu Navigation](#menu-navigation)\n\n### `open(menuId: string)`\n\n- **Description**: Opens the menu with the specified ID. Closes any menu that are not explicitly marked as compatible with the ID.\n\n- **Parameters**:\n  - `menuId`: The unique identifier of the menu to open.\n\n### `push(menuId: string)`\n\n- **Description**: Similar to the `open` function: it opens the menu with the specified ID and closes any menu that are not explicitly marked as compatible with the ID.\n\nAdditionally, it saves the current menu state into the history stack before opening the new one. Calling [`back`](#back) will return to that state.\n\n- **Parameters**:\n  - `menuId`: The unique identifier of the menu to open.\n\n### `back()`\n\n- **Description**: Go back to the previous menu state from the history stack. State is added in the history stack when calling [`push`](#pushmenuid-string).\n\n### `close(menuId: string)`\n\n- **Description**: Closes the menu with the specified ID.\n\n- **Parameters**:\n  - `menuId`: The unique identifier of the menu to close.\n\n### `toggle(menuId: string)`\n\n- **Description**: Toggles the state (open/close) of the menu with the specified ID.\n\n- **Parameters**:\n  - `menuId`: The unique identifier of the menu to toggle.\n\n### `whileOpened(menuId: string, effect: () -\u003e Teardown): () -\u003e ()`\n\n- **Description**: Executes the specified effect while the menu with the specified ID is open. The effect will automatically be cleaned up when the menu is closed.\n\n- **Parameters**:\n\n  - `menuId`: The unique identifier of the menu to target.\n  - `effect`: The effect to execute while the menu is open. This function return any kind of [teardown object](https://github.com/seaofvoices/luau-teardown) (for example: `nil`, a cleanup function or event connections) that will automatically get cleaned up when the menu is closed.\n\n- **Returns**: A function to remove the effect.\n\n## Tag Effects\n\nThis module defines a series of [tag-effects](https://github.com/seaofvoices/tag-effect) to define menus (that can be opened or closed) or buttons to open, close or toggle those menus.\n\n### `MenuInstance` or `MenuExtension`\n\n_Allowed instance class: [`GuiObject`](https://robloxapi.github.io/ref/class/GuiObject.html), [`LayerCollector`](https://robloxapi.github.io/ref/class/LayerCollector.html), [`ProximityPrompt`](https://robloxapi.github.io/ref/class/ProximityPrompt.html), [`BoolValue`](https://robloxapi.github.io/ref/class/BoolValue.html)_\n\nThose two tag-effects are used to define a new menu with the given `id`. The difference between a `MenuInstance` and a `MenuExtension` is how they influence other menus:\n\n- when a `MenuInstance` is opened, __all other `MenuInstance` will be closed__ (except other `MenuInstance` objects explicitly marked as compatible with the opened menu `id`)\n- when a `MenuExtension` is opened, it does not change other `MenuInstance` or `MenuExtension` objects\n\nBoth tag-effects have the same base configuration:\n\n__Configuration:__\n- `id` (string): identifier for the menu\n\n_Optional:_\n- `defaultState` (boolean): define if the menu is visible (or not) by default\n\nOptionally, the `MenuInstance` tag effect can also be configured to mark other menus as compatible with itself, by adding string attributes set to other compatible menu `id`. For example, one could add an attribute `compatibleWithStore = \"Store\"`, where `Store` would be another `MenuInstance` `id`.\n\n### Menu Navigation\n\nThere are various tags to navigate through menus: `OpenMenu`, `PushMenu`, `BackMenu`, `CloseMenu` and `ToggleMenu`.\n\nThese tag-effects can be used bind a signal to open, close or toggle a menu. They can be applied to any kind of instances:\n\n- [`GuiButton`](https://robloxapi.github.io/ref/class/GuiButton.html): which will trigger on the `Activated` event\n- [`ClickDetector`](https://robloxapi.github.io/ref/class/ClickDetector.html): which will trigger on the `MouseClick` event\n- [`ProximityPrompt`](https://robloxapi.github.io/ref/class/ProximityPrompt.html): which will trigger on the `Triggered` event\n- Any other instance, if the `eventName` attribute is set to an appropriate event name\n\n__Configuration:__\n- `id` (string): identifier of the menu that needs to be opened/pushed/closed/toggled. (**excepted** for `BackMenu`, this field is required)\n\n_Optional:_\n- `eventName` (string): specify which signal to use to bind the behavior\n\n## License\n\nThis project is available under the MIT license. See [LICENSE.txt](LICENSE.txt) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseaofvoices%2Fmenu-handler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseaofvoices%2Fmenu-handler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseaofvoices%2Fmenu-handler/lists"}