@furystack/shades-common-components 11.0.0 → 12.0.1

package/src/services/theme-provider-service.ts

@@ -87,8 +87,237 @@ export interface Background {
 }
 
 /**
- * Complete theme definition containing all color tokens for the application.
+ * Interactive state colors for hover, selection, focus and overlay backgrounds.
+ */
+export type ActionColors = {
+  /** Background color on hover for interactive elements */
+  hoverBackground: Color
+  /** Background color for selected/checked elements */
+  selectedBackground: Color
+  /** Background color for actively pressed elements */
+  activeBackground: Color
+  /** Box-shadow value for focus ring indicators */
+  focusRing: string
+  /** Opacity value for disabled elements (e.g. '0.6') */
+  disabledOpacity: string
+  /** Overlay background color for backdrops (drawers, modals) */
+  backdrop: Color
+  /** Subtle border color for structural dividers, input borders, and dropdown outlines */
+  subtleBorder: Color
+}
+
+/**
+ * Border radius scale for consistent rounded corners.
+ */
+export type BorderRadiusScale = {
+  /** 2px - grid cells, small elements */
+  xs: string
+  /** 4px - badges, compact items */
+  sm: string
+  /** 8px - buttons, paper, inputs, cards */
+  md: string
+  /** 12px - suggest, command palette */
+  lg: string
+  /** 50% - circular elements (avatar, FAB, loader) */
+  full: string
+}
+
+/**
+ * Shape tokens for geometric properties.
+ */
+export type Shape = {
+  /** Border radius scale */
+  borderRadius: BorderRadiusScale
+}
+
+/**
+ * Elevation shadow presets from subtle to prominent.
+ */
+export type Shadows = {
+  /** No shadow */
+  none: string
+  /** Subtle shadow (paper elevation 1, notifications) */
+  sm: string
+  /** Medium shadow (paper elevation 2, context-menu, dropdowns) */
+  md: string
+  /** Large shadow (paper elevation 3, modals, overlays) */
+  lg: string
+  /** Extra large shadow (floating elements like FAB, avatar hover) */
+  xl: string
+}
+
+/**
+ * Font size scale for consistent text sizing.
+ */
+export type FontSizeScale = {
+  /** 11px - labels, helper text */
+  xs: string
+  /** 13px - small body, secondary text */
+  sm: string
+  /** 14px - body text, buttons */
+  md: string
+  /** 16px - large body, icons */
+  lg: string
+  /** 24px - page headings */
+  xl: string
+}
+
+/**
+ * Font weight scale.
+ */
+export type FontWeightScale = {
+  /** 400 - normal weight */
+  normal: string
+  /** 500 - medium weight */
+  medium: string
+  /** 600 - semibold weight */
+  semibold: string
+  /** 700 - bold weight */
+  bold: string
+}
+
+/**
+ * Line height scale.
+ */
+export type LineHeightScale = {
+  /** 1.3 - headings, compact text */
+  tight: string
+  /** 1.5 - standard body text */
+  normal: string
+  /** 1.75 - relaxed spacing */
+  relaxed: string
+}
+
+/**
+ * Letter spacing scale for consistent character spacing.
+ */
+export type LetterSpacingScale = {
+  /** -0.5px - tight spacing for large display text */
+  tight: string
+  /** -0.25px - slightly tight spacing for headings */
+  dense: string
+  /** 0px - default spacing */
+  normal: string
+  /** 0.15px - slightly wider for body text */
+  wide: string
+  /** 0.5px - wider for buttons and labels */
+  wider: string
+  /** 1.5px - widest for overline/caption text */
+  widest: string
+}
+
+/**
+ * Typography tokens for text styling.
+ */
+export type ThemeTypography = {
+  /** Base font family stack */
+  fontFamily: string
+  /** Font size scale */
+  fontSize: FontSizeScale
+  /** Font weight scale */
+  fontWeight: FontWeightScale
+  /** Line height scale */
+  lineHeight: LineHeightScale
+  /** Letter spacing scale */
+  letterSpacing?: LetterSpacingScale
+}
+
+/**
+ * Transition duration presets.
+ */
+export type TransitionDurations = {
+  /** 150ms - micro-interactions (hover, active states) */
+  fast: string
+  /** 200ms - default transitions */
+  normal: string
+  /** 300ms - layout changes, drawers */
+  slow: string
+}
+
+/**
+ * Transition easing presets.
+ */
+export type TransitionEasings = {
+  /** Standard Material easing - cubic-bezier(0.4, 0, 0.2, 1) */
+  default: string
+  /** Decelerate easing - cubic-bezier(0.23, 1.0, 0.32, 1.0) */
+  easeOut: string
+  /** Symmetric easing - ease-in-out */
+  easeInOut: string
+}
+
+/**
+ * Transition timing tokens for animations and state changes.
+ */
+export type Transitions = {
+  /** Duration presets */
+  duration: TransitionDurations
+  /** Easing function presets */
+  easing: TransitionEasings
+}
+
+/**
+ * Spacing scale for consistent padding, margins and gaps.
+ */
+export type Spacing = {
+  /** 4px */
+  xs: string
+  /** 8px */
+  sm: string
+  /** 16px */
+  md: string
+  /** 24px */
+  lg: string
+  /** 32px */
+  xl: string
+}
+
+/**
+ * Z-index layer scale for consistent stacking context.
+ */
+export type ZIndex = {
+  /** 1000 - drawers and sidebar panels */
+  drawer: string
+  /** 1100 - app bars and sticky headers */
+  appBar: string
+  /** 1200 - modals and dialogs */
+  modal: string
+  /** 1300 - tooltips and popovers */
+  tooltip: string
+  /** 1400 - dropdowns and context menus */
+  dropdown: string
+}
+
+/**
+ * Visual effect tokens for blur and backdrop effects.
+ */
+export type Effects = {
+  /** 4px - subtle blur for glassy surfaces */
+  blurSm: string
+  /** 8px - medium blur for overlays */
+  blurMd: string
+  /** 15px - strong blur for app bar / prominent overlays */
+  blurLg: string
+  /** 20px - heavy blur for command palette / suggestion lists */
+  blurXl: string
+}
+
+/**
+ * Complete theme definition containing all design tokens for the application.
  * Themes can be switched at runtime to support light/dark modes or custom branding.
+ *
+ * **Future extension — Component size variants:**
+ * When introducing size variants for form controls (e.g. sm/md/lg Button, Input),
+ * add a `componentDefaults` section to this interface:
+ *
+ * ```typescript
+ * type ComponentSize = 'sm' | 'md' | 'lg'
+ * type SizeTokens = { height: string; padding: string; fontSize: string; borderRadius: string; iconSize: string }
+ * componentDefaults: { size: Record<ComponentSize, SizeTokens> }
+ * ```
+ *
+ * The existing `typography.fontSize` and `shape.borderRadius` scales provide
+ * the building blocks that size tokens should reference.
  */
 export interface Theme {
   /** Unique identifier for the theme */
@@ -103,6 +332,22 @@ export interface Theme {
   background: Background
   /** Color for dividers and borders */
   divider: Color
+  /** Interactive state colors */
+  action: ActionColors
+  /** Shape tokens (border radius) */
+  shape: Shape
+  /** Elevation shadow presets */
+  shadows: Shadows
+  /** Typography scale (font sizes, weights, line heights, letter spacing) */
+  typography: ThemeTypography
+  /** Transition timing tokens */
+  transitions: Transitions
+  /** Spacing scale */
+  spacing: Spacing
+  /** Z-index stacking layers */
+  zIndex?: ZIndex
+  /** Visual effect tokens (blur, backdrop) */
+  effects?: Effects
 }
 
 export class RgbColor {

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

@@ -0,0 +1,412 @@
+import { using } from '@furystack/utils'
+import { describe, expect, it } from 'vitest'
+import { TreeService } from './tree-service.js'
+
+type TestNode = { id: number; name: string; children?: TestNode[] }
+
+const getChildren = (node: TestNode): TestNode[] => node.children ?? []
+
+describe('TreeService', () => {
+  const createTreeData = (): TestNode[] => [
+    {
+      id: 1,
+      name: 'Root 1',
+      children: [
+        {
+          id: 11,
+          name: 'Child 1-1',
+          children: [
+            { id: 111, name: 'Leaf 1-1-1' },
+            { id: 112, name: 'Leaf 1-1-2' },
+          ],
+        },
+        { id: 12, name: 'Child 1-2' },
+      ],
+    },
+    { id: 2, name: 'Root 2' },
+    {
+      id: 3,
+      name: 'Root 3',
+      children: [{ id: 31, name: 'Child 3-1' }],
+    },
+  ]
+
+  const createTestService = () => {
+    const rootItems = createTreeData()
+    const service = new TreeService<TestNode>({
+      getChildren,
+    })
+    service.rootItems.setValue(rootItems)
+    service.updateFlattenedNodes()
+    return { service, rootItems }
+  }
+
+  describe('flattenedNodes', () => {
+    it('should flatten only root items when none are expanded', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        const flattened = service.flattenedNodes.getValue()
+        expect(flattened.length).toBe(3)
+        expect(flattened[0].item).toBe(rootItems[0])
+        expect(flattened[0].level).toBe(0)
+        expect(flattened[0].hasChildren).toBe(true)
+        expect(flattened[0].isExpanded).toBe(false)
+        expect(flattened[1].item).toBe(rootItems[1])
+        expect(flattened[1].hasChildren).toBe(false)
+        expect(flattened[2].item).toBe(rootItems[2])
+      })
+    })
+
+    it('should flatten children when a node is expanded', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.expand(rootItems[0])
+
+        const flattened = service.flattenedNodes.getValue()
+        expect(flattened.length).toBe(5)
+        expect(flattened[0].item).toBe(rootItems[0])
+        expect(flattened[0].isExpanded).toBe(true)
+        expect(flattened[1].item).toBe(rootItems[0].children![0])
+        expect(flattened[1].level).toBe(1)
+        expect(flattened[2].item).toBe(rootItems[0].children![1])
+        expect(flattened[2].level).toBe(1)
+        expect(flattened[3].item).toBe(rootItems[1])
+        expect(flattened[4].item).toBe(rootItems[2])
+      })
+    })
+
+    it('should flatten deeply nested children', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.expand(rootItems[0])
+        service.expand(rootItems[0].children![0])
+
+        const flattened = service.flattenedNodes.getValue()
+        expect(flattened.length).toBe(7)
+        expect(flattened[2].item.id).toBe(111)
+        expect(flattened[2].level).toBe(2)
+        expect(flattened[3].item.id).toBe(112)
+        expect(flattened[3].level).toBe(2)
+      })
+    })
+
+    it('should sync items with flattened nodes', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.expand(rootItems[0])
+
+        const items = service.items.getValue()
+        const flattened = service.flattenedNodes.getValue()
+
+        expect(items.length).toBe(flattened.length)
+        for (let i = 0; i < items.length; i++) {
+          expect(items[i]).toBe(flattened[i].item)
+        }
+      })
+    })
+  })
+
+  describe('expand/collapse', () => {
+    it('should expand a node', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.expand(rootItems[0])
+
+        expect(service.isExpanded(rootItems[0])).toBe(true)
+      })
+    })
+
+    it('should collapse a node', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.expand(rootItems[0])
+        service.collapse(rootItems[0])
+
+        expect(service.isExpanded(rootItems[0])).toBe(false)
+      })
+    })
+
+    it('should toggle expand on a collapsed node with children', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.toggleExpanded(rootItems[0])
+
+        expect(service.isExpanded(rootItems[0])).toBe(true)
+      })
+    })
+
+    it('should toggle collapse on an expanded node', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.expand(rootItems[0])
+        service.toggleExpanded(rootItems[0])
+
+        expect(service.isExpanded(rootItems[0])).toBe(false)
+      })
+    })
+
+    it('should not expand a leaf node', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.toggleExpanded(rootItems[1])
+
+        expect(service.isExpanded(rootItems[1])).toBe(false)
+      })
+    })
+
+    it('should hide children when collapsing a node', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.expand(rootItems[0])
+        expect(service.flattenedNodes.getValue().length).toBe(5)
+
+        service.collapse(rootItems[0])
+        expect(service.flattenedNodes.getValue().length).toBe(3)
+      })
+    })
+  })
+
+  describe('getParent', () => {
+    it('should return undefined for root items', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        expect(service.getParent(rootItems[0])).toBeUndefined()
+        expect(service.getParent(rootItems[1])).toBeUndefined()
+      })
+    })
+
+    it('should return the parent of a child node', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        const parent = service.getParent(rootItems[0].children![0])
+        expect(parent).toBe(rootItems[0])
+      })
+    })
+
+    it('should return the parent of a deeply nested node', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        const parent = service.getParent(rootItems[0].children![0].children![0])
+        expect(parent).toBe(rootItems[0].children![0])
+      })
+    })
+  })
+
+  describe('getNodeInfo', () => {
+    it('should return node info for a visible item', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        const info = service.getNodeInfo(rootItems[0])
+        expect(info).toBeDefined()
+        expect(info?.level).toBe(0)
+        expect(info?.hasChildren).toBe(true)
+        expect(info?.isExpanded).toBe(false)
+      })
+    })
+
+    it('should return undefined for a hidden item', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        const info = service.getNodeInfo(rootItems[0].children![0])
+        expect(info).toBeUndefined()
+      })
+    })
+  })
+
+  describe('handleKeyDown - tree navigation', () => {
+    it('should expand a collapsed node on ArrowRight', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.hasFocus.setValue(true)
+        service.focusedItem.setValue(rootItems[0])
+
+        service.handleKeyDown(new KeyboardEvent('keydown', { key: 'ArrowRight' }))
+
+        expect(service.isExpanded(rootItems[0])).toBe(true)
+      })
+    })
+
+    it('should move focus to first child on ArrowRight when already expanded', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.hasFocus.setValue(true)
+        service.expand(rootItems[0])
+        service.focusedItem.setValue(rootItems[0])
+
+        service.handleKeyDown(new KeyboardEvent('keydown', { key: 'ArrowRight' }))
+
+        expect(service.focusedItem.getValue()).toBe(rootItems[0].children![0])
+      })
+    })
+
+    it('should do nothing on ArrowRight on a leaf node', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.hasFocus.setValue(true)
+        service.focusedItem.setValue(rootItems[1])
+
+        service.handleKeyDown(new KeyboardEvent('keydown', { key: 'ArrowRight' }))
+
+        expect(service.focusedItem.getValue()).toBe(rootItems[1])
+      })
+    })
+
+    it('should collapse an expanded node on ArrowLeft', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.hasFocus.setValue(true)
+        service.expand(rootItems[0])
+        service.focusedItem.setValue(rootItems[0])
+
+        service.handleKeyDown(new KeyboardEvent('keydown', { key: 'ArrowLeft' }))
+
+        expect(service.isExpanded(rootItems[0])).toBe(false)
+      })
+    })
+
+    it('should move focus to parent on ArrowLeft when node is collapsed', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.hasFocus.setValue(true)
+        service.expand(rootItems[0])
+        service.focusedItem.setValue(rootItems[0].children![0])
+
+        service.handleKeyDown(new KeyboardEvent('keydown', { key: 'ArrowLeft' }))
+
+        expect(service.focusedItem.getValue()).toBe(rootItems[0])
+      })
+    })
+
+    it('should do nothing on ArrowLeft on a root node that is collapsed', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.hasFocus.setValue(true)
+        service.focusedItem.setValue(rootItems[1])
+
+        service.handleKeyDown(new KeyboardEvent('keydown', { key: 'ArrowLeft' }))
+
+        expect(service.focusedItem.getValue()).toBe(rootItems[1])
+      })
+    })
+
+    it('should not handle keys when not focused', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.hasFocus.setValue(false)
+        service.focusedItem.setValue(rootItems[0])
+
+        service.handleKeyDown(new KeyboardEvent('keydown', { key: 'ArrowRight' }))
+
+        expect(service.isExpanded(rootItems[0])).toBe(false)
+      })
+    })
+  })
+
+  describe('inherited ListService keyboard navigation', () => {
+    it('should handle ArrowDown to move focus to next visible item', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.hasFocus.setValue(true)
+        service.focusedItem.setValue(rootItems[0])
+
+        service.handleKeyDown(new KeyboardEvent('keydown', { key: 'ArrowDown' }))
+
+        expect(service.focusedItem.getValue()).toBe(rootItems[1])
+      })
+    })
+
+    it('should handle ArrowUp to move focus to previous visible item', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.hasFocus.setValue(true)
+        service.focusedItem.setValue(rootItems[1])
+
+        service.handleKeyDown(new KeyboardEvent('keydown', { key: 'ArrowUp' }))
+
+        expect(service.focusedItem.getValue()).toBe(rootItems[0])
+      })
+    })
+
+    it('should handle Home to move focus to first item', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.hasFocus.setValue(true)
+        service.focusedItem.setValue(rootItems[2])
+
+        service.handleKeyDown(new KeyboardEvent('keydown', { key: 'Home' }))
+
+        expect(service.focusedItem.getValue()).toBe(rootItems[0])
+      })
+    })
+
+    it('should handle End to move focus to last item', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.hasFocus.setValue(true)
+        service.focusedItem.setValue(rootItems[0])
+
+        service.handleKeyDown(new KeyboardEvent('keydown', { key: 'End' }))
+
+        expect(service.focusedItem.getValue()).toBe(rootItems[2])
+      })
+    })
+
+    it('should handle Space to toggle selection of focused item', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.hasFocus.setValue(true)
+        service.focusedItem.setValue(rootItems[0])
+
+        service.handleKeyDown(new KeyboardEvent('keydown', { key: ' ' }))
+        expect(service.selection.getValue()).toContain(rootItems[0])
+
+        service.handleKeyDown(new KeyboardEvent('keydown', { key: ' ' }))
+        expect(service.selection.getValue()).not.toContain(rootItems[0])
+      })
+    })
+
+    it('should handle Escape to clear selection and search term', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.hasFocus.setValue(true)
+        service.selection.setValue([rootItems[0]])
+        service.searchTerm.setValue('test')
+
+        service.handleKeyDown(new KeyboardEvent('keydown', { key: 'Escape' }))
+
+        expect(service.selection.getValue()).toEqual([])
+        expect(service.searchTerm.getValue()).toBe('')
+      })
+    })
+  })
+
+  describe('handleItemDoubleClick', () => {
+    it('should toggle expansion on double-click of a node with children', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.handleItemDoubleClick(rootItems[0])
+        expect(service.isExpanded(rootItems[0])).toBe(true)
+
+        service.handleItemDoubleClick(rootItems[0])
+        expect(service.isExpanded(rootItems[0])).toBe(false)
+      })
+    })
+
+    it('should not expand on double-click of a leaf node', () => {
+      const { service, rootItems } = createTestService()
+      using(service, () => {
+        service.handleItemDoubleClick(rootItems[1])
+
+        expect(service.isExpanded(rootItems[1])).toBe(false)
+      })
+    })
+  })
+
+  describe('dispose', () => {
+    it('should dispose all observables', () => {
+      const { service } = createTestService()
+
+      expect(() => service[Symbol.dispose]()).not.toThrow()
+    })
+  })
+})