{"id":18057396,"url":"https://github.com/syropian/lssm","last_synced_at":"2025-04-11T04:41:17.007Z","repository":{"id":61921701,"uuid":"552529125","full_name":"syropian/lssm","owner":"syropian","description":"Opinionated list selection state manager.","archived":false,"fork":false,"pushed_at":"2024-03-04T14:05:22.000Z","size":338,"stargazers_count":22,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-25T02:43:54.648Z","etag":null,"topics":["finder","list-selection","macos","multiselect"],"latest_commit_sha":null,"homepage":"https://lssm-js.netlify.app/","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/syropian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-10-16T19:47:58.000Z","updated_at":"2024-06-13T10:17:45.000Z","dependencies_parsed_at":"2023-01-20T16:45:29.312Z","dependency_job_id":null,"html_url":"https://github.com/syropian/lssm","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syropian%2Flssm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syropian%2Flssm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syropian%2Flssm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syropian%2Flssm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/syropian","download_url":"https://codeload.github.com/syropian/lssm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247595375,"owners_count":20963940,"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":["finder","list-selection","macos","multiselect"],"created_at":"2024-10-31T02:07:35.786Z","updated_at":"2025-04-11T04:41:16.985Z","avatar_url":"https://github.com/syropian.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# lssm [![Tests](https://github.com/syropian/lssm/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/syropian/lssm/actions/workflows/test.yml)\n\n\u003e Opinionated list selection state manager.\n\n`lssm` is small library that provides a simple command-driven API for managing the selection state of a list of items. It allows you to easily build a selectable list UI that supports complex multi-select rules modelled after the macOS Finder. It was written in vanilla TypeScript, and can be freely used alongside your favourite JavaScript framework, or no framework at all!\n\n[Check out the demo](https://lssm-js.netlify.app/)\n\n## Can I customize the style of my lists?\n\n`lssm` works purely with data and has no opinions on your UI layer. You can use a list manager to return the currently selected items, compare them against the orignal list of items, and render your UI accordingly.\n\n## Install\n\n```\nnpm install lssm --save\n```\n\n**or** include it in a `\u003cscript\u003e` tag, hosted by [unpkg](https://unpkg.com).\n\n```js\n\u003cscript src=\"https://unpkg.com/lssm/dist/lssm.iife.js\" /\u003e\n```\n\n## Usage\n\nTo begin, you'll need to create a list manager, and pass it your list of selectable items.\n\n```ts\nimport { ListSelectionStateManager as Lssm } from 'lssm'\n\nconst items = [\n  'Apple',\n  'Banana',\n  'Dragonfruit',\n  'Strawberry',\n  // etc...\n]\n\nconst listManager = new Lssm(items)\n```\n\n### Commands\n\nOnce you have a manager instance, you can use it to manage the selection state of your list using a few basic commands.\n\n\u003e **Note**\n\u003e Some commands accept a modifier config. This config is an object that specifies whether shift, ctrl, or command is being pressed while the command is being executed. This data can easily be extrapolated from the event object of various event handlers such as click and keydown. If you don't pass a modifier config, the command will be run as if no modifier keys are being pressed.\n\n#### `select(item: T, config: ModifierConfig): this`\n\nSelects a specific item in the list. If the ctrl/cmd modifier is passed, the item will be toggled. If the shift modifier is passed, a range of items will be selected using a predetermined set of rules.\n\n**Example**\n\n```ts\ndocument.querySelectorAll('.list-item').forEach(item =\u003e {\n  item.addEventListener('click', event =\u003e {\n    const { ctrlKey, metaKey, shiftKey } = event\n    listManager.select(item.dataset.listItem, {\n      ctrlKey,\n      metaKey,\n      shiftKey,\n    })\n  })\n})\n```\n\n#### `next(config: ModifierConfig): this`\n\nSelects the next item in the list. If the shift modifier is passed, the next adjacent item will be toggled using a predetermined set of rules.\n\n#### `previous(config: ModifierConfig): this`\n\nSelects the previous item in the list. If the shift modifier is passed, the previous adjacent item will be toggled using a predetermined set of rules.\n\n**Example**\n\n```ts\ndocument.addEventListener('keydown', e =\u003e {\n  if (e.key !== 'ArrowUp' \u0026\u0026 e.key !== 'ArrowDown') return\n\n  e.preventDefault()\n\n  const config = {\n    shiftKey: e.shiftKey,\n  }\n\n  if (e.key === 'ArrowDown') {\n    listManager.next(config)\n  } else {\n    listManager.previous(config)\n  }\n\n  console.log(listManager.get())\n})\n```\n\n#### `get(): T[]`\n\nReturns the currently selected items in the list.\n\n**Example**\n\n```ts\nconst items = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\nconst listManager = new Lssm(items)\n\n// Note how commands can be chained together\nlistManager.select(1).select(4, { shiftKey: true }).select(8, { metaKey: true })\n\nconsole.log(listManager.get()) // [1, 2, 3, 4, 8]\n```\n\n#### `getIndices(): number[]`\n\nSimilar to `get()` but returns the indices of the selected items instead of the items themselves.\n\n**Example**\n\n```ts\nconst items = [\n  { id: 1, name: 'Item 1' },\n  { id: 2, name: 'Item 2' },\n  { id: 3, name: 'Item 3' },\n  { id: 4, name: 'Item 4' },\n  { id: 5, name: 'Item 5' },\n]\n\nconst listManager = new Lssm(items)\nlistManager.select(1).select(3, { shiftKey: true }).select(5, { metaKey: true })\n\nconsole.log(listManager.getIndices()) // [0, 1, 2, 5]\n```\n\n#### `set(items: T[]): this`\n\nAllows you to manually set the selected items in the list.\n\n**Example**\n\n```ts\nconst items = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\nconst listManager = new Lssm(items)\n\nlistManager.set([1, 5, 6, 7])\n\nconsole.log(listManager.get()) // [1, 5, 6, 7]\n```\n\n#### `selectAll(): this`\n\nSelects all items in the list.\n\n#### `clear(): this`\n\nDeselcts all items in the list.\n\n### Working with objects\n\nIf you are using objects as your list items, you will need to pass a comparator function to the list manager. This is because `lssm` uses strict equality checks to compare items in the list, and objects are not strictly equal to each other even if they have the same properties.\n\nTo solve this issue, you may pass a comparator function to the list manager. This function will be used to compare items in the list, and should return `true` if the items are equal, and `false` if they are not.\n\n**Example**\n\n```ts\nconst items = [\n  { id: 1, name: 'Item 1' },\n  { id: 2, name: 'Item 2' },\n  { id: 3, name: 'Item 3' },\n  { id: 4, name: 'Item 4' },\n  { id: 5, name: 'Item 5' },\n]\n\nconst itemComparator = (a, b) =\u003e a.id === b.id\nconst listManager = new Lssm(items, itemComparator)\n```\n\n## Development\n\n```bash\n# To run the tests\npnpm test\n# or\npnpm run test:watch\n\n# To run the example\npnpm run dev\n\n# To publish the dist files\npnpm run build\n```\n\n## License\n\nMIT © [Collin Henderson](https://github.com/syropian)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyropian%2Flssm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyropian%2Flssm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyropian%2Flssm/lists"}