@furystack/shades 11.1.0 → 12.0.0

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)
   }

package/src/shade-host-props-ref.integration.spec.tsx

@@ -0,0 +1,460 @@
+import { Injector } from '@furystack/inject'
+import { ObservableValue, usingAsync } from '@furystack/utils'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { initializeShadeRoot } from './initialize.js'
+import { createComponent } from './shade-component.js'
+import { flushUpdates, Shade } from './shade.js'
+
+describe('useHostProps integration tests', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '<div id="root"></div>'
+  })
+  afterEach(() => {
+    document.body.innerHTML = ''
+  })
+
+  it('should set data attributes on the host element', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      const ExampleComponent = Shade<{ variant: string }>({
+        shadowDomName: 'host-props-data-attr-test',
+        render: ({ props, useHostProps }) => {
+          useHostProps({
+            'data-variant': props.variant,
+          })
+          return <div>content</div>
+        },
+      })
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent variant="primary" />,
+      })
+      await flushUpdates()
+
+      const el = document.querySelector('host-props-data-attr-test') as HTMLElement
+      expect(el).toBeTruthy()
+      expect(el.getAttribute('data-variant')).toBe('primary')
+    })
+  })
+
+  it('should set aria attributes on the host element', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      const ExampleComponent = Shade({
+        shadowDomName: 'host-props-aria-test',
+        render: ({ useHostProps }) => {
+          useHostProps({
+            role: 'progressbar',
+            'aria-valuenow': '50',
+            'aria-valuemin': '0',
+            'aria-valuemax': '100',
+          })
+          return <div>progress</div>
+        },
+      })
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
+
+      const el = document.querySelector('host-props-aria-test') as HTMLElement
+      expect(el.getAttribute('role')).toBe('progressbar')
+      expect(el.getAttribute('aria-valuenow')).toBe('50')
+      expect(el.getAttribute('aria-valuemin')).toBe('0')
+      expect(el.getAttribute('aria-valuemax')).toBe('100')
+    })
+  })
+
+  it('should apply CSS custom properties via style', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      const ExampleComponent = Shade({
+        shadowDomName: 'host-props-css-vars-test',
+        render: ({ useHostProps }) => {
+          useHostProps({
+            style: {
+              '--my-color': 'red',
+              '--my-size': '16px',
+            },
+          })
+          return <div>styled</div>
+        },
+      })
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
+
+      const el = document.querySelector('host-props-css-vars-test') as HTMLElement
+      expect(el.style.getPropertyValue('--my-color')).toBe('red')
+      expect(el.style.getPropertyValue('--my-size')).toBe('16px')
+    })
+  })
+
+  it('should apply standard inline styles', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      const ExampleComponent = Shade({
+        shadowDomName: 'host-props-inline-style-test',
+        render: ({ useHostProps }) => {
+          useHostProps({
+            style: {
+              display: 'flex',
+              gap: '8px',
+            },
+          })
+          return <div>styled</div>
+        },
+      })
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
+
+      const el = document.querySelector('host-props-inline-style-test') as HTMLElement
+      expect(el.style.display).toBe('flex')
+      expect(el.style.gap).toBe('8px')
+    })
+  })
+
+  it('should merge multiple useHostProps calls', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      const ExampleComponent = Shade({
+        shadowDomName: 'host-props-merge-test',
+        render: ({ useHostProps }) => {
+          useHostProps({
+            'data-first': 'one',
+            style: { '--color-a': 'red' },
+          })
+          useHostProps({
+            'data-second': 'two',
+            style: { '--color-b': 'blue' },
+          })
+          return <div>merged</div>
+        },
+      })
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
+
+      const el = document.querySelector('host-props-merge-test') as HTMLElement
+      expect(el.getAttribute('data-first')).toBe('one')
+      expect(el.getAttribute('data-second')).toBe('two')
+      expect(el.style.getPropertyValue('--color-a')).toBe('red')
+      expect(el.style.getPropertyValue('--color-b')).toBe('blue')
+    })
+  })
+
+  it('should remove attributes when they are no longer set on re-render', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+      const showExtra = new ObservableValue(true)
+
+      const ExampleComponent = Shade({
+        shadowDomName: 'host-props-remove-attr-test',
+        render: ({ useHostProps, useObservable }) => {
+          const [show] = useObservable('showExtra', showExtra)
+          useHostProps({
+            'data-always': 'yes',
+            ...(show ? { 'data-extra': 'present' } : {}),
+          })
+          return <div>content</div>
+        },
+      })
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
+
+      const el = document.querySelector('host-props-remove-attr-test') as HTMLElement
+      expect(el.getAttribute('data-always')).toBe('yes')
+      expect(el.getAttribute('data-extra')).toBe('present')
+
+      showExtra.setValue(false)
+      await flushUpdates()
+
+      expect(el.getAttribute('data-always')).toBe('yes')
+      expect(el.getAttribute('data-extra')).toBeNull()
+    })
+  })
+
+  it('should remove CSS custom properties when they are no longer set', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+      const showColor = new ObservableValue(true)
+
+      const ExampleComponent = Shade({
+        shadowDomName: 'host-props-remove-css-var-test',
+        render: ({ useHostProps, useObservable }) => {
+          const [show] = useObservable('showColor', showColor)
+          useHostProps({
+            style: {
+              display: 'block',
+              ...(show ? { '--my-color': 'red' } : {}),
+            },
+          })
+          return <div>content</div>
+        },
+      })
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
+
+      const el = document.querySelector('host-props-remove-css-var-test') as HTMLElement
+      expect(el.style.getPropertyValue('--my-color')).toBe('red')
+      expect(el.style.display).toBe('block')
+
+      showColor.setValue(false)
+      await flushUpdates()
+
+      expect(el.style.getPropertyValue('--my-color')).toBe('')
+      expect(el.style.display).toBe('block')
+    })
+  })
+
+  it('should set event handlers on the host element', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+      let clicked = false
+
+      const ExampleComponent = Shade({
+        shadowDomName: 'host-props-event-test',
+        render: ({ useHostProps }) => {
+          useHostProps({
+            onclick: () => {
+              clicked = true
+            },
+          })
+          return <div>clickable</div>
+        },
+      })
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
+
+      const el = document.querySelector('host-props-event-test') as HTMLElement
+      el.click()
+      expect(clicked).toBe(true)
+    })
+  })
+})
+
+describe('useRef integration tests', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '<div id="root"></div>'
+  })
+  afterEach(() => {
+    document.body.innerHTML = ''
+  })
+
+  it('should set ref.current to the mounted element', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      let capturedRef: { readonly current: HTMLDivElement | null } | undefined
+
+      const ExampleComponent = Shade({
+        shadowDomName: 'use-ref-basic-test',
+        render: ({ useRef }) => {
+          const divRef = useRef<HTMLDivElement>('myDiv')
+          capturedRef = divRef
+          return (
+            <div ref={divRef} id="target">
+              hello
+            </div>
+          )
+        },
+      })
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
+
+      expect(capturedRef).toBeTruthy()
+      expect(capturedRef!.current).toBeTruthy()
+      expect(capturedRef!.current).toBe(document.getElementById('target'))
+      expect(capturedRef!.current?.textContent).toBe('hello')
+    })
+  })
+
+  it('should return the same ref object across re-renders', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+      const counter = new ObservableValue(0)
+
+      const capturedRefs: Array<{ readonly current: Element | null }> = []
+
+      const ExampleComponent = Shade({
+        shadowDomName: 'use-ref-stable-test',
+        render: ({ useRef, useObservable }) => {
+          const [count] = useObservable('counter', counter)
+          const divRef = useRef('myDiv')
+          capturedRefs.push(divRef)
+          return <div ref={divRef}>{count}</div>
+        },
+      })
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
+
+      counter.setValue(1)
+      await flushUpdates()
+
+      counter.setValue(2)
+      await flushUpdates()
+
+      expect(capturedRefs.length).toBe(3)
+      expect(capturedRefs[0]).toBe(capturedRefs[1])
+      expect(capturedRefs[1]).toBe(capturedRefs[2])
+    })
+  })
+
+  it('should set ref.current on nested child elements', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      let capturedInputRef: { readonly current: HTMLInputElement | null } | undefined
+
+      const ExampleComponent = Shade({
+        shadowDomName: 'use-ref-nested-test',
+        render: ({ useRef }) => {
+          const inputRef = useRef<HTMLInputElement>('input')
+          capturedInputRef = inputRef
+          return (
+            <div>
+              <label>
+                <input ref={inputRef} type="text" id="my-input" />
+              </label>
+            </div>
+          )
+        },
+      })
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
+
+      expect(capturedInputRef).toBeTruthy()
+      expect(capturedInputRef!.current).toBeTruthy()
+      expect(capturedInputRef!.current).toBe(document.getElementById('my-input'))
+      expect(capturedInputRef!.current?.type).toBe('text')
+    })
+  })
+
+  it('should clear ref.current when element is unmounted', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+      const showChild = new ObservableValue(true)
+
+      let capturedRef: { readonly current: HTMLSpanElement | null } | undefined
+
+      const ExampleComponent = Shade({
+        shadowDomName: 'use-ref-unmount-test',
+        render: ({ useRef, useObservable }) => {
+          const [show] = useObservable('showChild', showChild)
+          const spanRef = useRef<HTMLSpanElement>('span')
+          capturedRef = spanRef
+          return <div>{show ? <span ref={spanRef}>visible</span> : null}</div>
+        },
+      })
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
+
+      expect(capturedRef!.current).toBeTruthy()
+      expect(capturedRef!.current?.textContent).toBe('visible')
+
+      showChild.setValue(false)
+      await flushUpdates()
+
+      expect(capturedRef!.current).toBeNull()
+    })
+  })
+
+  it('should work with useRef in onChange callbacks', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+      const counter = new ObservableValue(0)
+
+      const ExampleComponent = Shade({
+        shadowDomName: 'use-ref-onchange-test',
+        render: ({ useRef, useObservable }) => {
+          const spanRef = useRef<HTMLSpanElement>('counterSpan')
+          useObservable('counter', counter, {
+            onChange: (value) => {
+              if (spanRef.current) {
+                spanRef.current.textContent = String(value)
+              }
+            },
+          })
+          return (
+            <span ref={spanRef} id="counter-span">
+              0
+            </span>
+          )
+        },
+      })
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
+
+      const span = document.getElementById('counter-span')
+      expect(span?.textContent).toBe('0')
+
+      counter.setValue(42)
+      await flushUpdates()
+
+      expect(span?.textContent).toBe('42')
+    })
+  })
+})