@furystack/shades 11.0.35 → 12.0.0

package/src/models/selection-state.ts

@@ -1,3 +1,7 @@
+/**
+ * Captures the current focus and selection range within a DOM subtree.
+ * Used internally by the reconciler to preserve user selection across re-renders.
+ */
 export interface SelectionState {
   focusedPath?: number[]
   selectionRange?: {

package/src/services/location-service.tsx

@@ -4,6 +4,10 @@ import {
   serializeToQueryString as defaultSerializeToQueryString,
 } from '@furystack/rest'
 import { ObservableValue } from '@furystack/utils'
+/**
+ * Singleton service that tracks browser location changes (pathname, search, hash)
+ * and exposes them as observable values for reactive routing and URL-driven state.
+ */
 @Injectable({ lifetime: 'singleton' })
 export class LocationService implements Disposable {
   constructor(
@@ -119,6 +123,13 @@ export class LocationService implements Disposable {
   }).bind(this)
 }
 
+/**
+ * Configures custom serialization for URL search state.
+ * Must be called **before** `LocationService` is first instantiated by the injector.
+ * @param injector The root injector
+ * @param serialize Function to serialize state to a query string
+ * @param deserialize Function to deserialize a query string to state
+ */
 export const useCustomSearchStateSerializer = (
   injector: Injector,
   serialize: typeof defaultSerializeToQueryString,

package/src/services/resource-manager.spec.ts

@@ -19,6 +19,122 @@ describe('ResourceManager', () => {
     })
   })
 
+  it('Should switch to a new observable when a different reference is passed for the same key', async () => {
+    await usingAsync(new ResourceManager(), async (rm) => {
+      const o1 = new ObservableValue(1)
+      const o2 = new ObservableValue(42)
+      const onChange = vi.fn()
+
+      const [value1] = rm.useObservable('test', o1, onChange)
+      expect(value1).toBe(1)
+      expect(o1.getObservers().length).toBe(1)
+
+      const [value2] = rm.useObservable('test', o2, onChange)
+      expect(value2).toBe(42)
+      expect(o1.getObservers().length).toBe(0)
+      expect(o2.getObservers().length).toBe(1)
+    })
+  })
+
+  it('Should subscribe with the new onChange callback when switching observables', async () => {
+    await usingAsync(new ResourceManager(), async (rm) => {
+      const o1 = new ObservableValue('a')
+      const o2 = new ObservableValue('x')
+      const onChange1 = vi.fn()
+      const onChange2 = vi.fn()
+
+      rm.useObservable('test', o1, onChange1)
+      rm.useObservable('test', o2, onChange2)
+
+      o2.setValue('y')
+      expect(onChange2).toHaveBeenCalledWith('y')
+      expect(onChange1).not.toHaveBeenCalled()
+    })
+  })
+
+  it('Should not re-subscribe when the same observable reference is passed', async () => {
+    await usingAsync(new ResourceManager(), async (rm) => {
+      const o = new ObservableValue(1)
+      const onChange = vi.fn()
+
+      rm.useObservable('test', o, onChange)
+      rm.useObservable('test', o, onChange)
+      rm.useObservable('test', o, onChange)
+
+      expect(o.getObservers().length).toBe(1)
+    })
+  })
+
+  it('Should return a setValue bound to the new observable after switching', async () => {
+    await usingAsync(new ResourceManager(), async (rm) => {
+      const o1 = new ObservableValue(1)
+      const o2 = new ObservableValue(10)
+      const onChange = vi.fn()
+
+      const [, setValue1] = rm.useObservable('test', o1, onChange)
+      setValue1(5)
+      expect(o1.getValue()).toBe(5)
+
+      const [, setValue2] = rm.useObservable('test', o2, onChange)
+      setValue2(99)
+      expect(o2.getValue()).toBe(99)
+      expect(o1.getValue()).toBe(5)
+    })
+  })
+
+  it('Should handle multiple sequential observable switches for the same key', async () => {
+    await usingAsync(new ResourceManager(), async (rm) => {
+      const o1 = new ObservableValue('a')
+      const o2 = new ObservableValue('b')
+      const o3 = new ObservableValue('c')
+      const onChange = vi.fn()
+
+      const [v1] = rm.useObservable('test', o1, onChange)
+      expect(v1).toBe('a')
+
+      const [v2] = rm.useObservable('test', o2, onChange)
+      expect(v2).toBe('b')
+      expect(o1.getObservers().length).toBe(0)
+
+      const [v3] = rm.useObservable('test', o3, onChange)
+      expect(v3).toBe('c')
+      expect(o2.getObservers().length).toBe(0)
+      expect(o3.getObservers().length).toBe(1)
+    })
+  })
+
+  it('Should not trigger callbacks on the old observable after switching', async () => {
+    await usingAsync(new ResourceManager(), async (rm) => {
+      const o1 = new ObservableValue(1)
+      const o2 = new ObservableValue(2)
+      const onChange = vi.fn()
+
+      rm.useObservable('test', o1, onChange)
+      rm.useObservable('test', o2, onChange)
+
+      onChange.mockClear()
+      o1.setValue(999)
+      expect(onChange).not.toHaveBeenCalled()
+
+      o2.setValue(100)
+      expect(onChange).toHaveBeenCalledWith(100)
+    })
+  })
+
+  it('Should clean up switched observers on dispose', async () => {
+    const o1 = new ObservableValue(1)
+    const o2 = new ObservableValue(2)
+    const onChange = vi.fn()
+
+    await usingAsync(new ResourceManager(), async (rm) => {
+      rm.useObservable('test', o1, onChange)
+      rm.useObservable('test', o2, onChange)
+      expect(o2.getObservers().length).toBe(1)
+    })
+
+    expect(o2.getObservers().length).toBe(0)
+  })
+
   it('Should return a disposable from cache', async () => {
     await usingAsync(new ResourceManager(), async (rm) => {
       const factory = vi.fn(() => ({

package/src/services/resource-manager.ts

@@ -8,6 +8,13 @@ import { ObservableValue, isAsyncDisposable, isDisposable } from '@furystack/uti
 export class ResourceManager implements AsyncDisposable {
   private readonly disposables = new Map<string, Disposable | AsyncDisposable>()
 
+  /**
+   * Returns an existing disposable resource by key, or creates and caches a new one.
+   * Resources are automatically disposed when the component is removed from the DOM.
+   * @param key Unique key for caching this resource
+   * @param factory Factory function called once to create the resource
+   * @returns The cached or newly created resource
+   */
   public useDisposable<T extends Disposable | AsyncDisposable>(key: string, factory: () => T): T {
     const existing = this.disposables.get(key)
     if (!existing) {
@@ -20,6 +27,15 @@ export class ResourceManager implements AsyncDisposable {
 
   public readonly observers = new Map<string, ValueObserver<any>>()
 
+  /**
+   * Subscribes to an observable value by key. If the observable changes between renders,
+   * the previous subscription is disposed and a new one is created.
+   * @param key Unique key for caching this subscription
+   * @param observable The observable to subscribe to
+   * @param onChange Callback invoked when the value changes
+   * @param options Additional observer options
+   * @returns Tuple of [currentValue, setValue]
+   */
   public useObservable = <T>(
     key: string,
     observable: ObservableValue<T>,
@@ -28,6 +44,12 @@ export class ResourceManager implements AsyncDisposable {
   ): [value: T, setValue: (newValue: T) => void] => {
     const alreadyUsed = this.observers.get(key) as ValueObserver<T> | undefined
     if (alreadyUsed) {
+      if (alreadyUsed.observable !== observable) {
+        alreadyUsed[Symbol.dispose]()
+        const observer = observable.subscribe(onChange, options)
+        this.observers.set(key, observer)
+        return [observable.getValue(), observable.setValue.bind(observable)]
+      }
       return [alreadyUsed.observable.getValue(), alreadyUsed.observable.setValue.bind(alreadyUsed.observable)]
     }
     const observer = observable.subscribe(onChange, options)
@@ -37,6 +59,14 @@ export class ResourceManager implements AsyncDisposable {
 
   public readonly stateObservers = new Map<string, ObservableValue<any>>()
 
+  /**
+   * Creates or retrieves a local state observable by key.
+   * State is persisted across re-renders and disposed with the component.
+   * @param key Unique key for caching this state
+   * @param initialValue Initial value used on first call
+   * @param callback Callback invoked when the state changes
+   * @returns Tuple of [currentValue, setValue]
+   */
   public useState = <T>(
     key: string,
     initialValue: T,

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

@@ -1,7 +1,7 @@
 import { Injector } from '@furystack/inject'
 import { usingAsync } from '@furystack/utils'
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { ScreenService } from './screen-service.js'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { ScreenService, ScreenSizes } from './screen-service.js'
 
 describe('ScreenService', () => {
   beforeEach(() => {
@@ -9,19 +9,121 @@ describe('ScreenService', () => {
   })
   afterEach(() => {
     document.body.innerHTML = ''
+    vi.restoreAllMocks()
   })
 
-  it('Shuld be constructed', async () => {
+  it('Should be constructed', async () => {
     await usingAsync(new Injector(), async (i) => {
       const s = i.getInstance(ScreenService)
       expect(s).toBeInstanceOf(ScreenService)
     })
   })
 
-  it('Shuld update state on events', async () => {
-    await usingAsync(new Injector(), async (i) => {
-      i.getInstance(ScreenService)
-      /** TODO */
+  describe('breakpoints', () => {
+    it('Should have correct breakpoint definitions', async () => {
+      await usingAsync(new Injector(), async (i) => {
+        const s = i.getInstance(ScreenService)
+
+        expect(s.breakpoints.xs.minSize).toBe(0)
+        expect(s.breakpoints.sm.minSize).toBe(600)
+        expect(s.breakpoints.md.minSize).toBe(960)
+        expect(s.breakpoints.lg.minSize).toBe(1280)
+        expect(s.breakpoints.xl.minSize).toBe(1920)
+      })
+    })
+  })
+
+  describe('screenSize.atLeast', () => {
+    it('Should have observable for each screen size', async () => {
+      await usingAsync(new Injector(), async (i) => {
+        const s = i.getInstance(ScreenService)
+
+        for (const size of ScreenSizes) {
+          expect(s.screenSize.atLeast[size]).toBeDefined()
+          expect(typeof s.screenSize.atLeast[size].getValue()).toBe('boolean')
+        }
+      })
+    })
+
+    it('Should return true for xs on any screen size', async () => {
+      await usingAsync(new Injector(), async (i) => {
+        const s = i.getInstance(ScreenService)
+        // xs has minSize 0, so it should always be true
+        expect(s.screenSize.atLeast.xs.getValue()).toBe(true)
+      })
+    })
+
+    it('Should update screenSize observables on window resize', async () => {
+      await usingAsync(new Injector(), async (i) => {
+        const s = i.getInstance(ScreenService)
+
+        // Mock window.innerWidth to simulate a large screen
+        vi.spyOn(window, 'innerWidth', 'get').mockReturnValue(1920)
+
+        // Trigger resize event
+        window.dispatchEvent(new Event('resize'))
+
+        // All breakpoints should be true for 1920px width
+        expect(s.screenSize.atLeast.xs.getValue()).toBe(true)
+        expect(s.screenSize.atLeast.sm.getValue()).toBe(true)
+        expect(s.screenSize.atLeast.md.getValue()).toBe(true)
+        expect(s.screenSize.atLeast.lg.getValue()).toBe(true)
+        expect(s.screenSize.atLeast.xl.getValue()).toBe(true)
+
+        // Mock a small screen
+        vi.spyOn(window, 'innerWidth', 'get').mockReturnValue(500)
+        window.dispatchEvent(new Event('resize'))
+
+        // Only xs should be true for 500px width
+        expect(s.screenSize.atLeast.xs.getValue()).toBe(true)
+        expect(s.screenSize.atLeast.sm.getValue()).toBe(false)
+        expect(s.screenSize.atLeast.md.getValue()).toBe(false)
+        expect(s.screenSize.atLeast.lg.getValue()).toBe(false)
+        expect(s.screenSize.atLeast.xl.getValue()).toBe(false)
+      })
+    })
+  })
+
+  describe('orientation', () => {
+    it('Should have an orientation observable', async () => {
+      await usingAsync(new Injector(), async (i) => {
+        const s = i.getInstance(ScreenService)
+        const orientation = s.orientation.getValue()
+        expect(['landscape', 'portrait']).toContain(orientation)
+      })
+    })
+
+    it('Should update orientation on resize', async () => {
+      // Mock matchMedia before creating the service
+      const matchMediaMock = vi.fn()
+      window.matchMedia = matchMediaMock
+
+      await usingAsync(new Injector(), async (i) => {
+        // Set initial orientation to landscape
+        matchMediaMock.mockReturnValue({ matches: true } as MediaQueryList)
+        const s = i.getInstance(ScreenService)
+
+        // Verify initial landscape
+        window.dispatchEvent(new Event('resize'))
+        expect(s.orientation.getValue()).toBe('landscape')
+
+        // Change to portrait
+        matchMediaMock.mockReturnValue({ matches: false } as MediaQueryList)
+        window.dispatchEvent(new Event('resize'))
+        expect(s.orientation.getValue()).toBe('portrait')
+      })
+    })
+  })
+
+  describe('disposal', () => {
+    it('Should remove resize event listener on dispose', async () => {
+      const removeEventListenerSpy = vi.spyOn(window, 'removeEventListener')
+
+      await usingAsync(new Injector(), async (i) => {
+        i.getInstance(ScreenService)
+      })
+
+      expect(removeEventListenerSpy).toHaveBeenCalledWith('resize', expect.any(Function))
     })
   })
 })

package/src/services/screen-service.ts

@@ -1,21 +1,74 @@
 import { Injectable } from '@furystack/inject'
 import { ObservableValue } from '@furystack/utils'
 
+/**
+ * Available screen size breakpoint identifiers, ordered from smallest to largest.
+ */
 export const ScreenSizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const
 
+/**
+ * A screen size breakpoint identifier.
+ */
 export type ScreenSize = (typeof ScreenSizes)[number]
 
+/**
+ * Breakpoint definition with name and size constraints.
+ */
 export type Breakpoint = { name: ScreenSize; minSize: number; maxSize?: number }
 
 /**
- * Service for handling screen size changes
+ * Service for detecting and subscribing to screen size and orientation changes.
+ *
+ * This service provides reactive observables for responsive design decisions.
+ * Use `screenSize.atLeast[size]` to check if the viewport is at least a certain size.
+ *
+ * **Breakpoint Thresholds:**
+ * - `xs`: 0px+ (all sizes)
+ * - `sm`: 600px+ (small tablets and up)
+ * - `md`: 960px+ (tablets and up)
+ * - `lg`: 1280px+ (desktops and up)
+ * - `xl`: 1920px+ (large desktops)
+ *
+ * @example
+ * ```typescript
+ * const screenService = injector.getInstance(ScreenService);
+ *
+ * // Check if screen is at least medium size
+ * if (screenService.screenSize.atLeast.md.getValue()) {
+ *   // Show desktop layout
+ * }
+ *
+ * // Subscribe to size changes for responsive behavior
+ * screenService.screenSize.atLeast.md.subscribe((isAtLeastMd) => {
+ *   if (isAtLeastMd) {
+ *     console.log('Desktop or tablet view');
+ *   } else {
+ *     console.log('Mobile view');
+ *   }
+ * });
+ *
+ * // Get current breakpoint by checking from largest to smallest
+ * const getCurrentBreakpoint = (): ScreenSize => {
+ *   if (screenService.screenSize.atLeast.xl.getValue()) return 'xl';
+ *   if (screenService.screenSize.atLeast.lg.getValue()) return 'lg';
+ *   if (screenService.screenSize.atLeast.md.getValue()) return 'md';
+ *   if (screenService.screenSize.atLeast.sm.getValue()) return 'sm';
+ *   return 'xs';
+ * };
+ *
+ * // Subscribe to orientation changes
+ * screenService.orientation.subscribe((orientation) => {
+ *   console.log(`Screen is now in ${orientation} mode`);
+ * });
+ * ```
  */
 @Injectable({ lifetime: 'singleton' })
 export class ScreenService implements Disposable {
   private getOrientation = () => (window.matchMedia?.('(orientation:landscape').matches ? 'landscape' : 'portrait')
 
   /**
-   * The definitions of the breakpoints
+   * The definitions of the breakpoint thresholds in pixels.
+   * Each breakpoint represents the minimum width for that size category.
    */
   public readonly breakpoints: { [K in ScreenSize]: { minSize: number } } = {
     xl: { minSize: 1920 },
@@ -25,12 +78,26 @@ export class ScreenService implements Disposable {
     xs: { minSize: 0 },
   }
 
+  /**
+   * Cleans up event listeners when the service is disposed.
+   */
   public [Symbol.dispose]() {
     window.removeEventListener('resize', this.onResizeListener)
   }
 
   /**
-   * Observers for the current screen size. Will refresh on resize
+   * Observable values for checking if the screen is at least a certain size.
+   *
+   * Each observable emits `true` when the viewport width is >= the breakpoint threshold,
+   * and `false` otherwise. Values update automatically on window resize.
+   *
+   * @example
+   * ```typescript
+   * // Hide sidebar on small screens
+   * screenService.screenSize.atLeast.md.subscribe((isAtLeastMd) => {
+   *   sidebarVisible.setValue(isAtLeastMd);
+   * });
+   * ```
    */
   public readonly screenSize: {
     atLeast: { [K in ScreenSize]: ObservableValue<boolean> }
@@ -49,7 +116,17 @@ export class ScreenService implements Disposable {
   }
 
   /**
-   * Observable value for tracking the screen orientation
+   * Observable value for tracking the screen orientation.
+   * Emits 'landscape' or 'portrait' based on the current viewport dimensions.
+   *
+   * @example
+   * ```typescript
+   * screenService.orientation.subscribe((orientation) => {
+   *   if (orientation === 'landscape') {
+   *     // Adjust layout for landscape mode
+   *   }
+   * });
+   * ```
    */
   public orientation = new ObservableValue<'landscape' | 'portrait'>(this.getOrientation())
 

package/src/shade-component.ts

@@ -1,17 +1,37 @@
 import type { ChildrenList, ShadeComponent } from './models/index.js'
 import { isShadeComponent } from './models/shade-component.js'
+import { SVG_NS, isSvgTag } from './svg.js'
+import { createVNode } from './vnode.js'
+
+// ---------------------------------------------------------------------------
+// Render-mode toggle
+// ---------------------------------------------------------------------------
+
+let renderMode = false
 
 /**
- * Appends a list of items to a HTML element
+ * When true, the JSX factory produces VNode descriptors instead of real DOM elements.
+ * Set to true by `_performUpdate` before calling `render()`, then back to false after.
+ */
+export const setRenderMode = (mode: boolean): void => {
+  renderMode = mode
+}
+
+// ---------------------------------------------------------------------------
+// Real-DOM helpers (used outside render mode)
+// ---------------------------------------------------------------------------
+
+/**
+ * Appends a list of items to an element
  * @param el the root element
  * @param children array of items to append
  */
-export const appendChild = (el: HTMLElement | DocumentFragment, children: ChildrenList) => {
+export const appendChild = (el: Element | DocumentFragment, children: ChildrenList) => {
   for (const child of children) {
     if (typeof child === 'string' || typeof child === 'number') {
       el.appendChild(document.createTextNode(child))
     } else {
-      if (child instanceof HTMLElement || child instanceof DocumentFragment) {
+      if (child instanceof Element || child instanceof DocumentFragment) {
         el.appendChild(child)
       } else if (child instanceof Array) {
         appendChild(el, child)
@@ -44,7 +64,7 @@ export const attachStyles = (el: HTMLElement, props: unknown) => {
 export const attachDataAttributes = <TProps extends object>(el: HTMLElement, props: TProps) => {
   if (props) {
     Object.entries(props)
-      .filter(([key]) => key.startsWith('data-'))
+      .filter(([key]) => key.startsWith('data-') || key.startsWith('aria-'))
       .forEach(([key, value]) => el.setAttribute(key, (value as string) || ''))
   }
 }
@@ -69,6 +89,32 @@ export const attachProps = <TProps extends object>(el: HTMLElement, props: TProp
   attachDataAttributes(el, props)
 }
 
+/**
+ * Attaches properties to an SVG element via setAttribute.
+ * SVG attributes are XML-based and must be set via setAttribute,
+ * not via property assignment like HTML elements.
+ * @param el The target SVG element
+ * @param props The props to attach
+ */
+export const attachSvgProps = <TProps extends object>(el: Element, props: TProps) => {
+  if (!props) {
+    return
+  }
+  for (const [key, value] of Object.entries(props)) {
+    if (key === 'style' && typeof value === 'object' && value !== null) {
+      for (const [sk, sv] of Object.entries(value as Record<string, string>)) {
+        ;((el as HTMLElement).style as unknown as Record<string, string>)[sk] = sv
+      }
+    } else if (key === 'className') {
+      el.setAttribute('class', String(value))
+    } else if (key.startsWith('on') && typeof value === 'function') {
+      ;(el as unknown as Record<string, unknown>)[key] = value
+    } else if (value !== null && value !== undefined && value !== false) {
+      el.setAttribute(key, String(value))
+    }
+  }
+}
+
 type CreateComponentArgs<TProps> = [
   elementType: string | ShadeComponent<TProps>,
   props: TProps,
@@ -83,9 +129,14 @@ export const createComponentInner = <TProps extends object>(
   ...[elementType, props, ...children]: CreateComponentArgs<TProps>
 ) => {
   if (typeof elementType === 'string') {
-    const el = document.createElement(elementType)
+    const isSvg = isSvgTag(elementType)
+    const el = isSvg ? document.createElementNS(SVG_NS, elementType) : document.createElement(elementType)
 
-    attachProps(el, props)
+    if (isSvg) {
+      attachSvgProps(el, props)
+    } else {
+      attachProps(el as HTMLElement, props)
+    }
 
     if (children) {
       appendChild(el, children)
@@ -108,6 +159,21 @@ export const createFragmentInner = (...[_props, ...children]: CreateFragmentArgs
 }
 
 export const createComponent = <TProps extends object>(...args: CreateComponentArgs<TProps> | CreateFragmentArgs) => {
+  // In render mode, produce VNode descriptors instead of real DOM elements
+  if (renderMode) {
+    const [type, props, ...children] = args
+    // When jsxFragmentFactory === jsxFactory (both "createComponent"), the compiler
+    // passes createComponent itself as the first arg for fragments: createComponent(createComponent, null, ...)
+    if (type === null || (type as unknown) === createComponent) {
+      return createVNode(null, null, ...children) as unknown as ReturnType<typeof createComponentInner>
+    }
+    return createVNode(
+      type as string | ((...a: unknown[]) => unknown),
+      props as Record<string, unknown> | null,
+      ...children,
+    ) as unknown as ReturnType<typeof createComponentInner>
+  }
+
   if (args[0] === null) {
     return createFragmentInner(...args)
   }