@furystack/shades 12.4.0 → 13.0.0

package/src/services/location-service.tsx

@@ -39,10 +39,11 @@ export class LocationService implements Disposable {
   public [Symbol.dispose]() {
     window.removeEventListener('popstate', this.popStateListener)
     window.removeEventListener('hashchange', this.hashChangeListener)
-    this.onLocationPathChanged[Symbol.dispose]()
     this.onLocationSearchChanged[Symbol.dispose]()
     this.onDeserializedLocationSearchChanged[Symbol.dispose]()
     this.locationDeserializerObserver[Symbol.dispose]()
+    this.onLocationPathChanged[Symbol.dispose]()
+    this.onLocationHashChanged[Symbol.dispose]()
 
     window.history.pushState = this.originalPushState
     window.history.replaceState = this.originalReplaceState
@@ -69,6 +70,10 @@ export class LocationService implements Disposable {
     this.onDeserializedLocationSearchChanged.setValue(this.deserializeQueryString(search))
   })
 
+  /**
+   * Synchronizes the observable state with the current browser location.
+   * Called internally after navigation events and history state changes.
+   */
   public updateState = (() => {
     this.onLocationPathChanged.setValue(location.pathname)
     this.onLocationHashChanged.setValue(location.hash.replace('#', ''))
@@ -80,10 +85,25 @@ export class LocationService implements Disposable {
    * The LocationService interceptor ensures routing state is updated correctly.
    */
   public navigate(path: string): void {
+    // eslint-disable-next-line furystack/prefer-location-service -- This IS the LocationService.navigate() implementation.
     history.pushState(null, '', path)
     this.updateState()
   }
 
+  /**
+   * Replace the current history entry with a new path. Use this instead of
+   * raw history.replaceState for SPA redirects (e.g. the intermediate URL
+   * should not appear in the browser's back/forward stack).
+   */
+  public replace(path: string): void {
+    // eslint-disable-next-line furystack/prefer-location-service -- This IS the LocationService.replace() implementation.
+    history.replaceState(null, '', path)
+    this.updateState()
+  }
+
+  /**
+   * Internal cache of per-key search parameter observables created by {@link useSearchParam}.
+   */
   public readonly searchParamObservables = new Map<string, ObservableValue<any>>()
 
   /**
@@ -110,6 +130,7 @@ export class LocationService implements Disposable {
         if (currentQueryStringObject[key] !== value) {
           const params = this.serializeToQueryString({ ...currentQueryStringObject, [key]: value })
           const newUrl = `${location.pathname}?${params}`
+          // eslint-disable-next-line furystack/prefer-location-service -- Internal LocationService plumbing for search param sync.
           history.pushState({}, '', newUrl)
         }
       })

package/src/services/screen-service.ts

@@ -83,6 +83,10 @@ export class ScreenService implements Disposable {
    */
   public [Symbol.dispose]() {
     window.removeEventListener('resize', this.onResizeListener)
+    this.orientation[Symbol.dispose]()
+    Object.values(this.screenSize.atLeast).forEach((observable) => {
+      observable[Symbol.dispose]()
+    })
   }
 
   /**

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

@@ -18,7 +18,7 @@ describe('useHostProps integration tests', () => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
       const ExampleComponent = Shade<{ variant: string }>({
-        shadowDomName: 'host-props-data-attr-test',
+        customElementName: 'host-props-data-attr-test',
         render: ({ props, useHostProps }) => {
           useHostProps({
             'data-variant': props.variant,
@@ -45,7 +45,7 @@ describe('useHostProps integration tests', () => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
       const ExampleComponent = Shade({
-        shadowDomName: 'host-props-aria-test',
+        customElementName: 'host-props-aria-test',
         render: ({ useHostProps }) => {
           useHostProps({
             role: 'progressbar',
@@ -77,7 +77,7 @@ describe('useHostProps integration tests', () => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
       const ExampleComponent = Shade({
-        shadowDomName: 'host-props-css-vars-test',
+        customElementName: 'host-props-css-vars-test',
         render: ({ useHostProps }) => {
           useHostProps({
             style: {
@@ -107,7 +107,7 @@ describe('useHostProps integration tests', () => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
       const ExampleComponent = Shade({
-        shadowDomName: 'host-props-inline-style-test',
+        customElementName: 'host-props-inline-style-test',
         render: ({ useHostProps }) => {
           useHostProps({
             style: {
@@ -137,7 +137,7 @@ describe('useHostProps integration tests', () => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
       const ExampleComponent = Shade({
-        shadowDomName: 'host-props-merge-test',
+        customElementName: 'host-props-merge-test',
         render: ({ useHostProps }) => {
           useHostProps({
             'data-first': 'one',
@@ -172,7 +172,7 @@ describe('useHostProps integration tests', () => {
       const showExtra = new ObservableValue(true)
 
       const ExampleComponent = Shade({
-        shadowDomName: 'host-props-remove-attr-test',
+        customElementName: 'host-props-remove-attr-test',
         render: ({ useHostProps, useObservable }) => {
           const [show] = useObservable('showExtra', showExtra)
           useHostProps({
@@ -208,7 +208,7 @@ describe('useHostProps integration tests', () => {
       const showColor = new ObservableValue(true)
 
       const ExampleComponent = Shade({
-        shadowDomName: 'host-props-remove-css-var-test',
+        customElementName: 'host-props-remove-css-var-test',
         render: ({ useHostProps, useObservable }) => {
           const [show] = useObservable('showColor', showColor)
           useHostProps({
@@ -246,7 +246,7 @@ describe('useHostProps integration tests', () => {
       let clicked = false
 
       const ExampleComponent = Shade({
-        shadowDomName: 'host-props-event-test',
+        customElementName: 'host-props-event-test',
         render: ({ useHostProps }) => {
           useHostProps({
             onclick: () => {
@@ -286,7 +286,7 @@ describe('useRef integration tests', () => {
       let capturedRef: { readonly current: HTMLDivElement | null } | undefined
 
       const ExampleComponent = Shade({
-        shadowDomName: 'use-ref-basic-test',
+        customElementName: 'use-ref-basic-test',
         render: ({ useRef }) => {
           const divRef = useRef<HTMLDivElement>('myDiv')
           capturedRef = divRef
@@ -320,7 +320,7 @@ describe('useRef integration tests', () => {
       const capturedRefs: Array<{ readonly current: Element | null }> = []
 
       const ExampleComponent = Shade({
-        shadowDomName: 'use-ref-stable-test',
+        customElementName: 'use-ref-stable-test',
         render: ({ useRef, useObservable }) => {
           const [count] = useObservable('counter', counter)
           const divRef = useRef('myDiv')
@@ -355,7 +355,7 @@ describe('useRef integration tests', () => {
       let capturedInputRef: { readonly current: HTMLInputElement | null } | undefined
 
       const ExampleComponent = Shade({
-        shadowDomName: 'use-ref-nested-test',
+        customElementName: 'use-ref-nested-test',
         render: ({ useRef }) => {
           const inputRef = useRef<HTMLInputElement>('input')
           capturedInputRef = inputRef
@@ -391,7 +391,7 @@ describe('useRef integration tests', () => {
       let capturedRef: { readonly current: HTMLSpanElement | null } | undefined
 
       const ExampleComponent = Shade({
-        shadowDomName: 'use-ref-unmount-test',
+        customElementName: 'use-ref-unmount-test',
         render: ({ useRef, useObservable }) => {
           const [show] = useObservable('showChild', showChild)
           const spanRef = useRef<HTMLSpanElement>('span')
@@ -423,7 +423,7 @@ describe('useRef integration tests', () => {
       const counter = new ObservableValue(0)
 
       const ExampleComponent = Shade({
-        shadowDomName: 'use-ref-onchange-test',
+        customElementName: 'use-ref-onchange-test',
         render: ({ useRef, useObservable }) => {
           const spanRef = useRef<HTMLSpanElement>('counterSpan')
           useObservable('counter', counter, {

package/src/shade-resources.integration.spec.tsx

@@ -35,7 +35,7 @@ describe('Shade Resources integration tests', () => {
             </div>
           )
         },
-        shadowDomName: 'shades-example-resource',
+        customElementName: 'shades-example-resource',
       })
 
       expect(obs1.getObservers().length).toBe(0)
@@ -99,7 +99,7 @@ describe('Shade Resources integration tests', () => {
           renderCounter()
           return <div id="val">{value}</div>
         },
-        shadowDomName: 'shades-example-custom-onchange',
+        customElementName: 'shades-example-custom-onchange',
       })
 
       initializeShadeRoot({
@@ -162,11 +162,12 @@ describe('Shade Resources integration tests', () => {
           renderCounter()
           return (
             <div ref={valRef} id="manual-val">
+              {/* eslint-disable-next-line furystack/no-direct-get-value-in-render -- Test: verifying manual DOM update pattern with onChange callback */}
               {obs.getValue()}
             </div>
           )
         },
-        shadowDomName: 'shades-example-manual-dom-update',
+        customElementName: 'shades-example-manual-dom-update',
       })
 
       initializeShadeRoot({
@@ -227,7 +228,7 @@ describe('Shade Resources integration tests', () => {
             </div>
           )
         },
-        shadowDomName: 'shades-example-batching',
+        customElementName: 'shades-example-batching',
       })
 
       initializeShadeRoot({
@@ -272,7 +273,7 @@ describe('Shade Resources integration tests', () => {
           renderCounter()
           return <div>content</div>
         },
-        shadowDomName: 'shades-example-update-batching',
+        customElementName: 'shades-example-update-batching',
       })
 
       initializeShadeRoot({

package/src/shade.spec.tsx

@@ -13,18 +13,18 @@ describe('Shade edge cases', () => {
     document.body.innerHTML = ''
   })
 
-  describe('duplicate shadowDomName error', () => {
-    it('should throw an error when registering a duplicate shadowDomName', () => {
+  describe('duplicate customElementName error', () => {
+    it('should throw an error when registering a duplicate customElementName', () => {
       // First registration should succeed
       Shade({
-        shadowDomName: 'shade-duplicate-test',
+        customElementName: 'shade-duplicate-test',
         render: () => <div>First</div>,
       })
 
       // Second registration with the same name should throw
       expect(() => {
         Shade({
-          shadowDomName: 'shade-duplicate-test',
+          customElementName: 'shade-duplicate-test',
           render: () => <div>Second</div>,
         })
       }).toThrow("A custom shade with name 'shade-duplicate-test' has already been registered!")
@@ -34,13 +34,13 @@ describe('Shade edge cases', () => {
       const uniqueName = `shade-duplicate-name-in-error-${Date.now()}`
 
       Shade({
-        shadowDomName: uniqueName,
+        customElementName: uniqueName,
         render: () => <div>First</div>,
       })
 
       try {
         Shade({
-          shadowDomName: uniqueName,
+          customElementName: uniqueName,
           render: () => <div>Second</div>,
         })
         // Should not reach here
@@ -61,7 +61,7 @@ describe('Shade edge cases', () => {
           let childCapturedInjector: Injector | undefined
 
           const ChildComponent = Shade<{ injector?: Injector }>({
-            shadowDomName: 'shade-injector-child-props-test',
+            customElementName: 'shade-injector-child-props-test',
             render: ({ injector }) => {
               childCapturedInjector = injector
               return <div>Child</div>
@@ -69,7 +69,7 @@ describe('Shade edge cases', () => {
           })
 
           const ParentComponent = Shade({
-            shadowDomName: 'shade-injector-parent-props-test',
+            customElementName: 'shade-injector-parent-props-test',
             render: ({ injector, children }) => {
               parentCapturedInjector = injector
               return <div>{children}</div>
@@ -105,7 +105,7 @@ describe('Shade edge cases', () => {
         const renderCounter = vi.fn()
 
         const ExampleComponent = Shade({
-          shadowDomName: 'shade-no-render-after-disconnect',
+          customElementName: 'shade-no-render-after-disconnect',
           render: () => {
             renderCounter()
             return <div>content</div>
@@ -140,7 +140,7 @@ describe('Shade edge cases', () => {
         const renderCounter = vi.fn()
 
         const ExampleComponent = Shade({
-          shadowDomName: 'shade-no-sync-render-after-disconnect',
+          customElementName: 'shade-no-sync-render-after-disconnect',
           render: () => {
             renderCounter()
             return <div>content</div>
@@ -174,7 +174,7 @@ describe('Shade edge cases', () => {
         const obs = new ObservableValue(0)
 
         const ExampleComponent = Shade({
-          shadowDomName: 'shade-no-render-during-disposal',
+          customElementName: 'shade-no-render-during-disposal',
           render: ({ useObservable, useDisposable }) => {
             useObservable('obs', obs)
             useDisposable('cleanup', () => ({
@@ -183,6 +183,7 @@ describe('Shade edge cases', () => {
               },
             }))
             renderCounter()
+            // eslint-disable-next-line furystack/no-direct-get-value-in-render -- Test: verifying no re-render during disposal; already subscribed via useObservable above
             return <div>{obs.getValue()}</div>
           },
         })
@@ -226,7 +227,7 @@ describe('Shade edge cases', () => {
         const stateKey = 'broadcast-test-key'
 
         const ExampleComponent = Shade({
-          shadowDomName: 'shade-broadcast-channel-test',
+          customElementName: 'shade-broadcast-channel-test',
           render: ({ useStoredState }) => {
             const [value] = useStoredState(stateKey, 'initial', store)
             return <div id="value">{value}</div>
@@ -270,7 +271,7 @@ describe('Shade edge cases', () => {
         const stateKey = 'broadcast-filter-test-key'
 
         const ExampleComponent = Shade({
-          shadowDomName: 'shade-broadcast-channel-filter-test',
+          customElementName: 'shade-broadcast-channel-filter-test',
           render: ({ useStoredState }) => {
             const [value] = useStoredState(stateKey, 'initial', store)
             return <div id="value">{value}</div>
@@ -315,7 +316,7 @@ describe('Shade edge cases', () => {
         const stateKey = 'broadcast-cleanup-test-key'
 
         const ExampleComponent = Shade({
-          shadowDomName: 'shade-broadcast-channel-cleanup-test',
+          customElementName: 'shade-broadcast-channel-cleanup-test',
           render: ({ useStoredState }) => {
             const [value] = useStoredState(stateKey, 'initial', store)
             return <div id="value">{value}</div>

package/src/shade.ts

@@ -17,7 +17,7 @@ export type ShadeOptions<TProps, TElementBase extends HTMLElement> = {
    *
    * @example 'my-button', 'shade-dialog', 'app-header'
    */
-  shadowDomName: string
+  customElementName: string
 
   /**
    * Render hook, this method will be executed on each and every render.
@@ -68,8 +68,7 @@ export type ShadeOptions<TProps, TElementBase extends HTMLElement> = {
 export const Shade = <TProps, TElementBase extends HTMLElement = HTMLElement>(
   o: ShadeOptions<TProps, TElementBase>,
 ) => {
-  // Register custom element
-  const customElementName = o.shadowDomName
+  const { customElementName } = o
 
   const existing = customElements.get(customElementName)
   if (!existing) {
@@ -438,7 +437,7 @@ export const Shade = <TProps, TElementBase extends HTMLElement = HTMLElement>(
       o.elementBaseName ? { extends: o.elementBaseName } : undefined,
     )
   } else {
-    throw Error(`A custom shade with name '${o.shadowDomName}' has already been registered!`)
+    throw Error(`A custom shade with name '${o.customElementName}' has already been registered!`)
   }
 
   return (props: TProps & PartialElement<TElementBase>, children?: ChildrenList) => {

package/src/shades.integration.spec.tsx

@@ -18,7 +18,7 @@ describe('Shades integration tests', () => {
     await usingAsync(new Injector(), async (injector) => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
-      const ExampleComponent = Shade({ render: () => <div>Hello</div>, shadowDomName: 'shades-example' })
+      const ExampleComponent = Shade({ render: () => <div>Hello</div>, customElementName: 'shades-example' })
 
       initializeShadeRoot({
         injector,
@@ -34,7 +34,7 @@ describe('Shades integration tests', () => {
     await usingAsync(new Injector(), async (injector) => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
-      const ExampleComponent = Shade({ render: () => 'Hello', shadowDomName: 'shades-string-render-result' })
+      const ExampleComponent = Shade({ render: () => 'Hello', customElementName: 'shades-string-render-result' })
 
       initializeShadeRoot({
         injector,
@@ -52,7 +52,7 @@ describe('Shades integration tests', () => {
     await usingAsync(new Injector(), async (injector) => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
-      const ExampleComponent = Shade({ render: () => null, shadowDomName: 'shades-null-render-result' })
+      const ExampleComponent = Shade({ render: () => null, customElementName: 'shades-null-render-result' })
 
       initializeShadeRoot({
         injector,
@@ -77,7 +77,7 @@ describe('Shades integration tests', () => {
             <p>2</p>
           </>
         ),
-        shadowDomName: 'shades-fragment-render-result',
+        customElementName: 'shades-fragment-render-result',
       })
 
       initializeShadeRoot({
@@ -105,7 +105,7 @@ describe('Shades integration tests', () => {
             </>
           </p>
         ),
-        shadowDomName: 'shades-fragment-render-result-nested',
+        customElementName: 'shades-fragment-render-result-nested',
       })
 
       initializeShadeRoot({
@@ -125,7 +125,7 @@ describe('Shades integration tests', () => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
       const CustomComponent = Shade({
-        shadowDomName: 'shades-fragment-test-custom-component',
+        customElementName: 'shades-fragment-test-custom-component',
         render: () => <p>Hello</p>,
       })
 
@@ -136,7 +136,7 @@ describe('Shades integration tests', () => {
             <CustomComponent />
           </>
         ),
-        shadowDomName: 'shades-fragment-render-result-2',
+        customElementName: 'shades-fragment-render-result-2',
       })
 
       initializeShadeRoot({
@@ -157,12 +157,12 @@ describe('Shades integration tests', () => {
 
       const ExampleComponent = Shade({
         render: ({ children }) => <div>{children}</div>,
-        shadowDomName: 'shades-example-2',
+        customElementName: 'shades-example-2',
       })
 
       const ExampleSubs = Shade<{ no: number }>({
         render: ({ props }) => <div>{props.no}</div>,
-        shadowDomName: 'shades-example-sub',
+        customElementName: 'shades-example-sub',
       })
 
       initializeShadeRoot({
@@ -190,7 +190,7 @@ describe('Shades integration tests', () => {
       const setup = vi.fn()
 
       const ExampleComponent = Shade({
-        shadowDomName: 'example-component-1',
+        customElementName: 'example-component-1',
         render: ({ useDisposable }) => {
           useDisposable('test', () => {
             setup()
@@ -219,7 +219,7 @@ describe('Shades integration tests', () => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
       const ExampleComponent = Shade({
-        shadowDomName: 'example-component-3',
+        customElementName: 'example-component-3',
         render: ({ useState }) => {
           const [count, setCount] = useState('count', 0)
           return (
@@ -290,7 +290,7 @@ describe('Shades integration tests', () => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
       const ExampleComponent = Shade({
-        shadowDomName: 'example-component-3-stored-state',
+        customElementName: 'example-component-3-stored-state',
         render: ({ useStoredState }) => {
           const [count, setCount] = useStoredState('count', 0, store)
           return (
@@ -348,7 +348,7 @@ describe('Shades integration tests', () => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
       const ExampleComponent = Shade({
-        shadowDomName: 'example-component-3-search-state',
+        customElementName: 'example-component-3-search-state',
         render: ({ useSearchState }) => {
           const [count, setCount] = useSearchState('count', 0)
           return (
@@ -403,7 +403,7 @@ describe('Shades integration tests', () => {
     await usingAsync(new Injector(), async (injector) => {
       const rootElement = document.getElementById('root') as HTMLDivElement
       const Parent = Shade({
-        shadowDomName: 'shade-remount-parent',
+        customElementName: 'shade-remount-parent',
         render: ({ children, useState }) => {
           const [areChildrenVisible, setAreChildrenVisible] = useState('areChildrenVisible', true)
           return (
@@ -423,7 +423,7 @@ describe('Shades integration tests', () => {
       })
 
       const Child = Shade({
-        shadowDomName: 'example-remount-child',
+        customElementName: 'example-remount-child',
         render: ({ useState }) => {
           const [count, setCount] = useState('count', 0)
 
@@ -493,14 +493,14 @@ describe('Shades integration tests', () => {
       const rootElement = document.getElementById('root') as HTMLDivElement
 
       const ChildComponent = Shade<{ isDisabled: boolean }>({
-        shadowDomName: 'shade-prop-child',
+        customElementName: 'shade-prop-child',
         render: ({ props }) => {
           return <input type="checkbox" disabled={props.isDisabled} data-testid="inner-input" />
         },
       })
 
       const ParentComponent = Shade({
-        shadowDomName: 'shade-prop-parent',
+        customElementName: 'shade-prop-parent',
         render: ({ useState }) => {
           const [isDisabled, setIsDisabled] = useState('isDisabled', false)
           return (

package/src/style-manager.spec.ts

@@ -181,7 +181,7 @@ describe('StyleManager', () => {
   describe('Shade integration', () => {
     it('should register CSS styles when Shade component is created with css property', () => {
       Shade({
-        shadowDomName: 'shade-css-test-component',
+        customElementName: 'shade-css-test-component',
         css: {
           color: 'red',
           padding: '10px',
@@ -200,7 +200,7 @@ describe('StyleManager', () => {
 
     it('should register CSS with attribute selector for customized built-in elements', () => {
       Shade({
-        shadowDomName: 'shade-css-test-button',
+        customElementName: 'shade-css-test-button',
         elementBase: HTMLButtonElement,
         elementBaseName: 'button',
         css: {
@@ -219,7 +219,7 @@ describe('StyleManager', () => {
 
     it('should not register styles when Shade component has no css property', () => {
       Shade({
-        shadowDomName: 'shade-no-css-component',
+        customElementName: 'shade-no-css-component',
         render: () => null,
       })
 

package/src/style-manager.ts

@@ -27,7 +27,7 @@ class StyleManagerClass {
    * Registers CSS styles for a component.
    * Styles are only injected once per component (based on the custom element name).
    *
-   * @param shadowDomName - The custom element tag name (used as CSS selector)
+   * @param customElementName - The custom element tag name (used as CSS selector)
    * @param cssObject - The CSSObject containing styles and nested selectors
    * @param elementBaseName - Optional base element name for customized built-in elements (e.g., 'a', 'button').
    *                          When provided, generates selector like `a[is="component-name"]` instead of `component-name`
@@ -49,17 +49,17 @@ class StyleManagerClass {
    * // Generates: a[is="my-link"] { color: blue; }
    * ```
    */
-  public registerComponentStyles(shadowDomName: string, cssObject: CSSObject, elementBaseName?: string): boolean {
-    if (this.registeredComponents.has(shadowDomName)) {
+  public registerComponentStyles(customElementName: string, cssObject: CSSObject, elementBaseName?: string): boolean {
+    if (this.registeredComponents.has(customElementName)) {
       return false
     }
 
-    const selector = elementBaseName ? `${elementBaseName}[is="${shadowDomName}"]` : shadowDomName
+    const selector = elementBaseName ? `${elementBaseName}[is="${customElementName}"]` : customElementName
     const css = generateCSS(selector, cssObject)
     if (css) {
       const styleElement = this.getStyleElement()
-      styleElement.textContent += `\n/* ${shadowDomName} */\n${css}\n`
-      this.registeredComponents.add(shadowDomName)
+      styleElement.textContent += `\n/* ${customElementName} */\n${css}\n`
+      this.registeredComponents.add(customElementName)
       return true
     }
 
@@ -68,11 +68,11 @@ class StyleManagerClass {
 
   /**
    * Checks if a component's styles have already been registered
-   * @param shadowDomName - The component identifier to check
+   * @param customElementName - The component identifier to check
    * @returns True if styles are already registered
    */
-  public isRegistered(shadowDomName: string): boolean {
-    return this.registeredComponents.has(shadowDomName)
+  public isRegistered(customElementName: string): boolean {
+    return this.registeredComponents.has(customElementName)
   }
 
   /**