{"id":14962728,"url":"https://github.com/oskarhane/actus","last_synced_at":"2025-10-25T00:30:41.768Z","repository":{"id":45081743,"uuid":"348113672","full_name":"oskarhane/actus","owner":"oskarhane","description":"A monorepo for a self learning command palette driven by a final state machine implemented in XState.","archived":false,"fork":false,"pushed_at":"2022-01-10T12:50:30.000Z","size":2346,"stargazers_count":51,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-30T00:32:49.086Z","etag":null,"topics":["command-palette","finite-state-machine","self-learning","svelte","xstate"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/oskarhane.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-15T20:30:14.000Z","updated_at":"2023-10-20T10:46:23.000Z","dependencies_parsed_at":"2022-09-04T18:21:53.417Z","dependency_job_id":null,"html_url":"https://github.com/oskarhane/actus","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oskarhane%2Factus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oskarhane%2Factus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oskarhane%2Factus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oskarhane%2Factus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oskarhane","download_url":"https://codeload.github.com/oskarhane/actus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238046850,"owners_count":19407625,"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":["command-palette","finite-state-machine","self-learning","svelte","xstate"],"created_at":"2024-09-24T13:30:25.714Z","updated_at":"2025-10-25T00:30:41.241Z","avatar_url":"https://github.com/oskarhane.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @actus\n\n![bar](packages/svelte/images/bar.png)\nThis repo holds a command palette with robust interactions and predictable behavior backed by a finite state machine.\nA command palette (or command bar) is a user interface that receives user input and presents the user with a list of matching commands and executes the command the user chooses.\n\nYou see this kind of UI in many application nowadays. `Ctrl/cmd + k` in Slack and Discord, `Ctrl/cmd + p` in VS Code, `cmd + Space` in MacOS etc.\n\n\u003e I wanted to have as much as possible handled in a UI framework / library agnostic way, so gluing it to a React or Svelte component should be trivial.\n\n## Self learning\n\nIt's self learning in the sense that it ranks items higher the more you pick them for a certain input. To follow trends and have new commands\nhave achance to get to the top fairly quick, it doesn't keep the execution history forever but normalizes it from time to time. See [packages/core/src/exec-graph.ts](packages/core/src/exec-graph.ts) for the implementation of this.\n\n## Demo\n\nHere's a demo of the Svelte implementation of the core: [https://ti99l.csb.app](https://ti99l.csb.app)\n\n## States and transitions\n\n**Open / Close**\n\nThe command palette behaves as most palettes do. It's able to become visible by using a hot-key, and closed with the escape key.\n\n**Command matching and ranking**\n\nWhile open and on user input, it waits for relevant commands and rank the matching ones in a natural order (the ranking algo can be overridden) with the best match on top.\n\n**Command list selection**\n\nWith the matching command results listed, the top one is selected automatically (called auto selection). If the user would continue typing, the top one should always stay selected until the user selects one manually (with arrow keys or hover with the mouse).\n\nIf the user selects one manually (called id selection), and then continues typing, as long as the selected command is in the list it should stay selected, no matter if its position changes. When the selected result isn't available in the result list anymore (due to not matching anymore), the top result should be selected again (by position, not by id).\n\nThe user is able to step over the selection boundaries (pressing arrow down on the last result should roll over to select the top result and vice versa).\n\n**Dynamic list of commands**\n\nCommands might be added and removed at any time, and the palette should be able to handle that when opened. If a new command becomes available and it matches the current user input, it should be shown in the correct position in the result listing and should not interfere with any user selection.\n\n**Execution**\n\nThe user can execute a command in two ways: Click on it or press Enter.\nWhen a command is executed, the palette should close and the user input should be emptied.\n\n**Remember non executed input**\n\nIf the user types something in the command palette input but closes it without executing, the palette should remember it and populate the input once the user opens it again.\n\n## The Finite State Machine\n\nHave a look at [packages/core/src/selection-machine.ts](packages/core/src/selection-machine.ts) to see the machine and its services / actions / guards implementations.\n\nHere's a visualization of the machine:\n![vis](packages/core/images/vis.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foskarhane%2Factus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foskarhane%2Factus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foskarhane%2Factus/lists"}