@furystack/shades-common-components 11.0.0 → 12.0.0

package/src/services/list-service.spec.ts

@@ -0,0 +1,364 @@
+import { describe, expect, it } from 'vitest'
+import { ListService } from './list-service.js'
+
+type TestItem = { id: number; name: string }
+
+describe('ListService', () => {
+  const createTestService = (options?: ConstructorParameters<typeof ListService<TestItem>>[0]) => {
+    const service = new ListService<TestItem>(options)
+    const items: TestItem[] = [
+      { id: 1, name: 'First' },
+      { id: 2, name: 'Second' },
+      { id: 3, name: 'Third' },
+    ]
+    service.items.setValue(items)
+    return { service, items }
+  }
+
+  describe('selection helpers', () => {
+    it('should check if item is selected', () => {
+      const { service, items } = createTestService()
+      service.selection.setValue([items[0]])
+
+      expect(service.isSelected(items[0])).toBe(true)
+      expect(service.isSelected(items[1])).toBe(false)
+
+      service[Symbol.dispose]()
+    })
+
+    it('should add item to selection', () => {
+      const { service, items } = createTestService()
+      service.addToSelection(items[0])
+
+      expect(service.selection.getValue()).toContain(items[0])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should remove item from selection', () => {
+      const { service, items } = createTestService()
+      service.selection.setValue([items[0], items[1]])
+      service.removeFromSelection(items[0])
+
+      expect(service.selection.getValue()).not.toContain(items[0])
+      expect(service.selection.getValue()).toContain(items[1])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should toggle selection on', () => {
+      const { service, items } = createTestService()
+      service.toggleSelection(items[0])
+
+      expect(service.isSelected(items[0])).toBe(true)
+
+      service[Symbol.dispose]()
+    })
+
+    it('should toggle selection off', () => {
+      const { service, items } = createTestService()
+      service.selection.setValue([items[0]])
+      service.toggleSelection(items[0])
+
+      expect(service.isSelected(items[0])).toBe(false)
+
+      service[Symbol.dispose]()
+    })
+  })
+
+  describe('handleKeyDown', () => {
+    it('should not handle keyboard when not focused', () => {
+      const { service, items } = createTestService()
+      service.hasFocus.setValue(false)
+      service.focusedItem.setValue(items[0])
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: 'ArrowDown' }))
+
+      expect(service.focusedItem.getValue()).toBe(items[0])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should handle ArrowDown to move focus to next item', () => {
+      const { service, items } = createTestService()
+      service.hasFocus.setValue(true)
+      service.focusedItem.setValue(items[0])
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: 'ArrowDown' }))
+
+      expect(service.focusedItem.getValue()).toBe(items[1])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should not move past last item on ArrowDown', () => {
+      const { service, items } = createTestService()
+      service.hasFocus.setValue(true)
+      service.focusedItem.setValue(items[2])
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: 'ArrowDown' }))
+
+      expect(service.focusedItem.getValue()).toBe(items[2])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should handle ArrowUp to move focus to previous item', () => {
+      const { service, items } = createTestService()
+      service.hasFocus.setValue(true)
+      service.focusedItem.setValue(items[1])
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: 'ArrowUp' }))
+
+      expect(service.focusedItem.getValue()).toBe(items[0])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should not move past first item on ArrowUp', () => {
+      const { service, items } = createTestService()
+      service.hasFocus.setValue(true)
+      service.focusedItem.setValue(items[0])
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: 'ArrowUp' }))
+
+      expect(service.focusedItem.getValue()).toBe(items[0])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should handle Home to move focus to first item', () => {
+      const { service, items } = createTestService()
+      service.hasFocus.setValue(true)
+      service.focusedItem.setValue(items[2])
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: 'Home' }))
+
+      expect(service.focusedItem.getValue()).toBe(items[0])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should handle End to move focus to last item', () => {
+      const { service, items } = createTestService()
+      service.hasFocus.setValue(true)
+      service.focusedItem.setValue(items[0])
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: 'End' }))
+
+      expect(service.focusedItem.getValue()).toBe(items[2])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should handle Space to toggle selection of focused item', () => {
+      const { service, items } = createTestService()
+      service.hasFocus.setValue(true)
+      service.focusedItem.setValue(items[0])
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: ' ' }))
+      expect(service.selection.getValue()).toContain(items[0])
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: ' ' }))
+      expect(service.selection.getValue()).not.toContain(items[0])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should handle + to select all items', () => {
+      const { service, items } = createTestService()
+      service.hasFocus.setValue(true)
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: '+' }))
+
+      expect(service.selection.getValue().length).toBe(3)
+      expect(service.selection.getValue()).toEqual(items)
+
+      service[Symbol.dispose]()
+    })
+
+    it('should handle - to deselect all items', () => {
+      const { service, items } = createTestService()
+      service.hasFocus.setValue(true)
+      service.selection.setValue([...items])
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: '-' }))
+
+      expect(service.selection.getValue().length).toBe(0)
+
+      service[Symbol.dispose]()
+    })
+
+    it('should handle * to invert selection', () => {
+      const { service, items } = createTestService()
+      service.hasFocus.setValue(true)
+      service.selection.setValue([items[0]])
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: '*' }))
+
+      const selection = service.selection.getValue()
+      expect(selection).not.toContain(items[0])
+      expect(selection).toContain(items[1])
+      expect(selection).toContain(items[2])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should handle Insert to toggle selection and move to next item', () => {
+      const { service, items } = createTestService()
+      service.hasFocus.setValue(true)
+      service.focusedItem.setValue(items[0])
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: 'Insert' }))
+
+      expect(service.selection.getValue()).toContain(items[0])
+      expect(service.focusedItem.getValue()).toBe(items[1])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should handle Insert to deselect already selected item', () => {
+      const { service, items } = createTestService()
+      service.hasFocus.setValue(true)
+      service.focusedItem.setValue(items[0])
+      service.selection.setValue([items[0]])
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: 'Insert' }))
+
+      expect(service.selection.getValue()).not.toContain(items[0])
+      expect(service.focusedItem.getValue()).toBe(items[1])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should handle Tab to toggle focus', () => {
+      const { service } = createTestService()
+      service.hasFocus.setValue(true)
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: 'Tab' }))
+
+      expect(service.hasFocus.getValue()).toBe(false)
+
+      service[Symbol.dispose]()
+    })
+
+    it('should handle Escape to clear selection and search term', () => {
+      const { service, items } = createTestService()
+      service.hasFocus.setValue(true)
+      service.selection.setValue([items[0], items[1]])
+      service.searchTerm.setValue('test')
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: 'Escape' }))
+
+      expect(service.selection.getValue()).toEqual([])
+      expect(service.searchTerm.getValue()).toBe('')
+
+      service[Symbol.dispose]()
+    })
+
+    it('should handle type-ahead search when searchField is set', () => {
+      const { service, items } = createTestService({ searchField: 'name' })
+      service.hasFocus.setValue(true)
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: 'S' }))
+
+      expect(service.searchTerm.getValue()).toBe('S')
+      expect(service.focusedItem.getValue()).toBe(items[1])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should accumulate type-ahead search characters', () => {
+      const { service, items } = createTestService({ searchField: 'name' })
+      service.hasFocus.setValue(true)
+
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: 'T' }))
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: 'h' }))
+      service.handleKeyDown(new KeyboardEvent('keydown', { key: 'i' }))
+
+      expect(service.searchTerm.getValue()).toBe('Thi')
+      expect(service.focusedItem.getValue()).toBe(items[2])
+
+      service[Symbol.dispose]()
+    })
+  })
+
+  describe('handleItemClick', () => {
+    it('should set focused item on click', () => {
+      const { service, items } = createTestService()
+
+      service.handleItemClick(items[1], new MouseEvent('click'))
+
+      expect(service.focusedItem.getValue()).toBe(items[1])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should add to selection on Ctrl+Click', () => {
+      const { service, items } = createTestService()
+
+      service.handleItemClick(items[0], new MouseEvent('click', { ctrlKey: true }))
+
+      expect(service.selection.getValue()).toContain(items[0])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should remove from selection on Ctrl+Click when already selected', () => {
+      const { service, items } = createTestService()
+      service.selection.setValue([items[0]])
+
+      service.handleItemClick(items[0], new MouseEvent('click', { ctrlKey: true }))
+
+      expect(service.selection.getValue()).not.toContain(items[0])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should select range on Shift+Click', () => {
+      const { service, items } = createTestService()
+      service.focusedItem.setValue(items[0])
+
+      service.handleItemClick(items[2], new MouseEvent('click', { shiftKey: true }))
+
+      const selection = service.selection.getValue()
+      expect(selection).toContain(items[0])
+      expect(selection).toContain(items[1])
+      expect(selection).toContain(items[2])
+
+      service[Symbol.dispose]()
+    })
+
+    it('should select range backwards on Shift+Click', () => {
+      const { service, items } = createTestService()
+      service.focusedItem.setValue(items[2])
+
+      service.handleItemClick(items[0], new MouseEvent('click', { shiftKey: true }))
+
+      const selection = service.selection.getValue()
+      expect(selection).toContain(items[0])
+      expect(selection).toContain(items[1])
+      expect(selection).toContain(items[2])
+
+      service[Symbol.dispose]()
+    })
+  })
+
+  describe('handleItemDoubleClick', () => {
+    it('should not throw on double-click', () => {
+      const { service, items } = createTestService()
+
+      expect(() => service.handleItemDoubleClick(items[0])).not.toThrow()
+
+      service[Symbol.dispose]()
+    })
+  })
+
+  describe('dispose', () => {
+    it('should dispose all observables', () => {
+      const { service } = createTestService()
+
+      expect(() => service[Symbol.dispose]()).not.toThrow()
+    })
+  })
+})

package/src/services/list-service.ts

@@ -0,0 +1,169 @@
+import { ObservableValue } from '@furystack/utils'
+
+export type ListServiceOptions<T> = {
+  /**
+   * An optional field that can be used for type-ahead search
+   */
+  searchField?: keyof T
+}
+
+/**
+ * Service for managing list state including focus, selection, and keyboard navigation
+ */
+export class ListService<T> implements Disposable {
+  public [Symbol.dispose]() {
+    this.items[Symbol.dispose]()
+    this.selection[Symbol.dispose]()
+    this.searchTerm[Symbol.dispose]()
+    this.hasFocus[Symbol.dispose]()
+    this.focusedItem[Symbol.dispose]()
+  }
+
+  public isSelected = (item: T) => this.selection.getValue().includes(item)
+
+  public addToSelection = (item: T) => {
+    this.selection.setValue([...this.selection.getValue(), item])
+  }
+
+  public removeFromSelection = (item: T) => {
+    this.selection.setValue(this.selection.getValue().filter((e) => e !== item))
+  }
+
+  public toggleSelection = (item: T) => {
+    if (this.isSelected(item)) {
+      this.removeFromSelection(item)
+    } else {
+      this.addToSelection(item)
+    }
+  }
+
+  public items = new ObservableValue<T[]>([])
+
+  public focusedItem = new ObservableValue<T | undefined>(undefined)
+
+  public selection = new ObservableValue<T[]>([])
+
+  public searchTerm = new ObservableValue('')
+
+  public hasFocus = new ObservableValue(false)
+
+  public handleKeyDown(ev: KeyboardEvent) {
+    const items = this.items.getValue()
+    const hasFocus = this.hasFocus.getValue()
+    const selectedItems = this.selection.getValue()
+    const focusedItem = this.focusedItem.getValue()
+    const searchTerm = this.searchTerm.getValue()
+
+    if (hasFocus) {
+      switch (ev.key) {
+        case ' ':
+          ev.preventDefault()
+          if (focusedItem) {
+            this.selection.setValue(
+              selectedItems.includes(focusedItem)
+                ? selectedItems.filter((e) => e !== focusedItem)
+                : [...selectedItems, focusedItem],
+            )
+          }
+          break
+        case '*':
+          ev.preventDefault()
+          this.selection.setValue(items.filter((e) => !selectedItems.includes(e)))
+          break
+        case '+':
+          ev.preventDefault()
+          this.selection.setValue(items)
+          break
+        case '-':
+          ev.preventDefault()
+          this.selection.setValue([])
+          break
+        case 'Insert':
+          ev.preventDefault()
+          if (focusedItem) {
+            if (this.selection.getValue().includes(focusedItem)) {
+              this.selection.setValue([...this.selection.getValue().filter((e) => e !== focusedItem)])
+            } else {
+              this.selection.setValue([...this.selection.getValue(), focusedItem])
+            }
+            this.focusedItem.setValue(items[items.findIndex((e) => e === this.focusedItem.getValue()) + 1])
+          }
+          break
+        case 'ArrowUp':
+          ev.preventDefault()
+          this.focusedItem.setValue(items[Math.max(0, items.findIndex((e) => e === focusedItem) - 1)])
+          break
+        case 'ArrowDown':
+          ev.preventDefault()
+          this.focusedItem.setValue(items[Math.min(items.length - 1, items.findIndex((e) => e === focusedItem) + 1)])
+          break
+        case 'Home': {
+          ev.preventDefault()
+          this.focusedItem.setValue(items[0])
+          break
+        }
+        case 'End': {
+          ev.preventDefault()
+          this.focusedItem.setValue(items[items.length - 1])
+          break
+        }
+        case 'Tab': {
+          this.hasFocus.setValue(!hasFocus)
+          break
+        }
+        case 'Escape': {
+          ev.preventDefault()
+          this.searchTerm.setValue('')
+          this.selection.setValue([])
+          break
+        }
+        default:
+          if (this.options.searchField && ev.key.length === 1) {
+            const newSearchExpression = searchTerm + ev.key
+            const newFocusedItem = items.find(
+              (e) =>
+                this.options.searchField &&
+                (e[this.options.searchField] as string)?.toString().startsWith(newSearchExpression),
+            )
+            this.focusedItem.setValue(newFocusedItem)
+            this.searchTerm.setValue(newSearchExpression)
+          }
+      }
+    }
+  }
+
+  public handleItemClick(item: T, ev: MouseEvent) {
+    const currentSelectionValue = this.selection.getValue()
+    const lastFocused = this.focusedItem.getValue()
+    if (ev.ctrlKey) {
+      if (currentSelectionValue.includes(item)) {
+        this.selection.setValue(currentSelectionValue.filter((s) => s !== item))
+      } else {
+        this.selection.setValue([...currentSelectionValue, item])
+      }
+    }
+    if (ev.shiftKey) {
+      const items = this.items.getValue()
+      const lastFocusedIndex = items.findIndex((e) => e === lastFocused)
+      const itemIndex = items.findIndex((e) => e === item)
+      const start = Math.min(lastFocusedIndex, itemIndex)
+      const end = Math.max(lastFocusedIndex, itemIndex)
+      const rangeItems = items.slice(start, end + 1)
+      const newSelection = [...currentSelectionValue]
+      for (const rangeItem of rangeItems) {
+        if (!newSelection.includes(rangeItem)) {
+          newSelection.push(rangeItem)
+        }
+      }
+      this.selection.setValue(newSelection)
+    }
+    this.focusedItem.setValue(item)
+  }
+
+  /**
+   * Hook for double-click behavior. No-op in base class; overridden by TreeService for expand/collapse.
+   */
+  public handleItemDoubleClick(_item: T) {}
+
+  constructor(private options: ListServiceOptions<T> = {}) {}
+}

package/src/services/palette-css-vars.ts

@@ -0,0 +1,46 @@
+import { cssVariableTheme } from './css-variable-theme.js'
+import type { ColorVariants, Palette } from './theme-provider-service.js'
+
+/**
+ * A Record mapping every Palette key to main + mainContrast CSS variable references.
+ * Shared by components that accept a `color?: keyof Palette` prop (Badge, Pagination, etc.).
+ */
+export const paletteMainColors: Record<keyof Palette, Pick<ColorVariants, 'main' | 'mainContrast'>> = {
+  primary: {
+    main: cssVariableTheme.palette.primary.main,
+    mainContrast: cssVariableTheme.palette.primary.mainContrast,
+  },
+  secondary: {
+    main: cssVariableTheme.palette.secondary.main,
+    mainContrast: cssVariableTheme.palette.secondary.mainContrast,
+  },
+  error: {
+    main: cssVariableTheme.palette.error.main,
+    mainContrast: cssVariableTheme.palette.error.mainContrast,
+  },
+  warning: {
+    main: cssVariableTheme.palette.warning.main,
+    mainContrast: cssVariableTheme.palette.warning.mainContrast,
+  },
+  success: {
+    main: cssVariableTheme.palette.success.main,
+    mainContrast: cssVariableTheme.palette.success.mainContrast,
+  },
+  info: {
+    main: cssVariableTheme.palette.info.main,
+    mainContrast: cssVariableTheme.palette.info.mainContrast,
+  },
+}
+
+/**
+ * A Record mapping every Palette key to the full set of CSS variable references.
+ * Shared by components that need light/dark variants (Chip, etc.).
+ */
+export const paletteFullColors: Record<keyof Palette, ColorVariants> = {
+  primary: { ...cssVariableTheme.palette.primary },
+  secondary: { ...cssVariableTheme.palette.secondary },
+  error: { ...cssVariableTheme.palette.error },
+  warning: { ...cssVariableTheme.palette.warning },
+  success: { ...cssVariableTheme.palette.success },
+  info: { ...cssVariableTheme.palette.info },
+}