@furystack/shades 11.0.35 → 11.1.0

package/src/css-generator.ts

@@ -0,0 +1,117 @@
+import type { CSSObject, CSSProperties } from './models/css-object.js'
+
+/**
+ * Converts a camelCase string to kebab-case
+ * @param str - The camelCase string to convert
+ * @returns The kebab-case string
+ * @example
+ * camelToKebab('backgroundColor') // 'background-color'
+ * camelToKebab('fontSize') // 'font-size'
+ */
+export const camelToKebab = (str: string): string => {
+  return str.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`)
+}
+
+/**
+ * Checks if a key is a selector key (starts with '&')
+ * @param key - The key to check
+ * @returns True if the key is a selector key
+ */
+export const isSelectorKey = (key: string): boolean => {
+  return key.startsWith('&')
+}
+
+/**
+ * Converts CSS properties to a CSS declaration string
+ * @param properties - The CSS properties object
+ * @returns A CSS declaration string (e.g., "color: red; padding: 10px;")
+ */
+export const propertiesToCSSString = (properties: CSSProperties): string => {
+  const declarations: string[] = []
+
+  for (const key in properties) {
+    if (Object.prototype.hasOwnProperty.call(properties, key) && !isSelectorKey(key)) {
+      const value = properties[key as keyof CSSProperties]
+      if (value !== undefined && value !== null && value !== '' && typeof value === 'string') {
+        declarations.push(`${camelToKebab(key)}: ${value}`)
+      }
+    }
+  }
+
+  return declarations.join('; ')
+}
+
+/**
+ * Generates a CSS rule string from a selector and properties
+ * @param selector - The CSS selector
+ * @param properties - The CSS properties object
+ * @returns A complete CSS rule string (e.g., "selector { color: red; }")
+ */
+export const generateCSSRule = (selector: string, properties: CSSProperties): string => {
+  const cssString = propertiesToCSSString(properties)
+  if (!cssString) {
+    return ''
+  }
+  return `${selector} { ${cssString}; }`
+}
+
+/**
+ * Generates complete CSS from a CSSObject for a given component selector
+ * @param selector - The base selector (typically the shadowDomName)
+ * @param cssObject - The CSSObject containing styles and nested selectors
+ * @returns A complete CSS string with all rules
+ *
+ * @example
+ * ```typescript
+ * generateCSS('my-component', {
+ *   color: 'red',
+ *   '&:hover': { color: 'blue' },
+ *   '& .inner': { fontWeight: 'bold' }
+ * })
+ * // Returns:
+ * // "my-component { color: red; }
+ * //  my-component:hover { color: blue; }
+ * //  my-component .inner { font-weight: bold; }"
+ * ```
+ */
+export const generateCSS = (selector: string, cssObject: CSSObject): string => {
+  const rules: string[] = []
+
+  // Extract base properties (non-selector keys)
+  const baseProperties: CSSProperties = {}
+  const selectorRules: Array<{ selectorKey: string; properties: CSSProperties }> = []
+
+  for (const key in cssObject) {
+    if (Object.prototype.hasOwnProperty.call(cssObject, key)) {
+      if (isSelectorKey(key)) {
+        const properties = cssObject[key as keyof CSSObject]
+        if (properties && typeof properties === 'object') {
+          selectorRules.push({ selectorKey: key, properties: properties as CSSProperties })
+        }
+      } else {
+        const value = cssObject[key as keyof CSSObject]
+        if (typeof value !== 'object') {
+          ;(baseProperties as Record<string, unknown>)[key] = value
+        }
+      }
+    }
+  }
+
+  // Generate base rule
+  const baseRule = generateCSSRule(selector, baseProperties)
+  if (baseRule) {
+    rules.push(baseRule)
+  }
+
+  // Generate selector rules
+  for (const { selectorKey, properties } of selectorRules) {
+    // Replace '&' with the base selector
+    const fullSelector = selectorKey.replace(/&/g, selector)
+    const rule = generateCSSRule(fullSelector, properties)
+    if (rule) {
+      rules.push(rule)
+    }
+  }
+
+  return rules.join('\n')
+}

package/src/index.ts

@@ -1,10 +1,12 @@
 export * from './compile-route.js'
 export * from './components/index.js'
+export * from './css-generator.js'
 export * from './initialize.js'
 export * from './models/index.js'
 export * from './services/index.js'
 export * from './shade-component.js'
 export * from './shade.js'
+export * from './style-manager.js'
 export * from './styled-element.js'
 export * from './styled-shade.js'
 import './jsx.js'

package/src/models/css-object.ts

@@ -0,0 +1,34 @@
+/**
+ * Base CSS properties - subset of CSSStyleDeclaration
+ */
+export type CSSProperties = Partial<CSSStyleDeclaration>
+
+/**
+ * Selector key pattern for pseudo-classes and nested selectors
+ * Examples: '&:hover', '&:active', '& .className', '& > div'
+ */
+export type SelectorKey = `&${string}`
+
+/**
+ * CSS object supporting nested selectors for component-level styling.
+ *
+ * Use this type for the `css` property in Shade components to define
+ * styles that are injected as a stylesheet during component registration.
+ *
+ * @example
+ * ```typescript
+ * const styles: CSSObject = {
+ *   padding: '16px',
+ *   backgroundColor: 'white',
+ *   '&:hover': {
+ *     backgroundColor: '#f0f0f0'
+ *   },
+ *   '& .title': {
+ *     fontWeight: 'bold'
+ *   }
+ * }
+ * ```
+ */
+export type CSSObject = CSSProperties & {
+  [K in SelectorKey]?: CSSProperties
+}

package/src/models/index.ts

@@ -1,4 +1,5 @@
 export * from './children-list.js'
+export * from './css-object.js'
 export * from './partial-element.js'
 export * from './render-options.js'
 export * from './selection-state.js'

package/src/shade.spec.tsx

@@ -0,0 +1,238 @@
+import { Injector } from '@furystack/inject'
+import { sleepAsync, usingAsync } from '@furystack/utils'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { initializeShadeRoot } from './initialize.js'
+import { createComponent } from './shade-component.js'
+import { Shade } from './shade.js'
+
+describe('Shade edge cases', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '<div id="root"></div>'
+  })
+  afterEach(() => {
+    document.body.innerHTML = ''
+  })
+
+  describe('duplicate shadowDomName error', () => {
+    it('should throw an error when registering a duplicate shadowDomName', () => {
+      // First registration should succeed
+      Shade({
+        shadowDomName: 'shade-duplicate-test',
+        render: () => <div>First</div>,
+      })
+
+      // Second registration with the same name should throw
+      expect(() => {
+        Shade({
+          shadowDomName: 'shade-duplicate-test',
+          render: () => <div>Second</div>,
+        })
+      }).toThrow("A custom shade with shadow DOM name 'shade-duplicate-test' has already been registered!")
+    })
+
+    it('should include the duplicate name in the error message', () => {
+      const uniqueName = `shade-duplicate-name-in-error-${Date.now()}`
+
+      Shade({
+        shadowDomName: uniqueName,
+        render: () => <div>First</div>,
+      })
+
+      try {
+        Shade({
+          shadowDomName: uniqueName,
+          render: () => <div>Second</div>,
+        })
+        // Should not reach here
+        expect.fail('Expected an error to be thrown')
+      } catch (e) {
+        expect((e as Error).message).toContain(uniqueName)
+      }
+    })
+  })
+
+  describe('injector from props', () => {
+    it('should use props injector for child component instead of inheriting from parent', async () => {
+      await usingAsync(new Injector(), async (rootInjector) => {
+        const propsInjector = new Injector()
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        let parentCapturedInjector: Injector | undefined
+        let childCapturedInjector: Injector | undefined
+
+        const ChildComponent = Shade<{ injector?: Injector }>({
+          shadowDomName: 'shade-injector-child-props-test',
+          render: ({ injector }) => {
+            childCapturedInjector = injector
+            return <div>Child</div>
+          },
+        })
+
+        const ParentComponent = Shade({
+          shadowDomName: 'shade-injector-parent-props-test',
+          render: ({ injector, children }) => {
+            parentCapturedInjector = injector
+            return <div>{children}</div>
+          },
+        })
+
+        initializeShadeRoot({
+          injector: rootInjector,
+          rootElement,
+          jsxElement: (
+            <ParentComponent>
+              <ChildComponent injector={propsInjector} />
+            </ParentComponent>
+          ),
+        })
+
+        await sleepAsync(10)
+
+        // Parent should use root injector (inherited from parent)
+        expect(parentCapturedInjector).toBe(rootInjector)
+        // Child should use the props injector, not the parent's
+        expect(childCapturedInjector).toBe(propsInjector)
+        expect(childCapturedInjector).not.toBe(rootInjector)
+      })
+    })
+  })
+
+  describe('BroadcastChannel cross-tab communication', () => {
+    it('should update stored state when receiving BroadcastChannel message with matching key', async () => {
+      const mockedStorage = new Map<string, string>()
+
+      const store: typeof localStorage = {
+        getItem: (key) => mockedStorage.get(key) || null,
+        setItem: (key, value) => mockedStorage.set(key, value),
+        length: 0,
+        clear: () => mockedStorage.clear(),
+        key: (index) => Array.from(mockedStorage.keys())[index] || null,
+        removeItem: (key) => mockedStorage.delete(key),
+      }
+
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const stateKey = 'broadcast-test-key'
+
+        const ExampleComponent = Shade({
+          shadowDomName: 'shade-broadcast-channel-test',
+          render: ({ useStoredState }) => {
+            const [value] = useStoredState(stateKey, 'initial', store)
+            return <div id="value">{value}</div>
+          },
+        })
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <ExampleComponent />,
+        })
+
+        await sleepAsync(50)
+        expect(document.getElementById('value')?.textContent).toBe('initial')
+
+        // Simulate cross-tab message via BroadcastChannel
+        const channel = new BroadcastChannel('useStoredState-broadcast-channel')
+        channel.postMessage({ key: stateKey, value: 'updated-from-other-tab' })
+
+        await sleepAsync(50)
+        expect(document.getElementById('value')?.textContent).toBe('updated-from-other-tab')
+
+        channel.close()
+      })
+    })
+
+    it('should ignore BroadcastChannel messages with different key', async () => {
+      const mockedStorage = new Map<string, string>()
+
+      const store: typeof localStorage = {
+        getItem: (key) => mockedStorage.get(key) || null,
+        setItem: (key, value) => mockedStorage.set(key, value),
+        length: 0,
+        clear: () => mockedStorage.clear(),
+        key: (index) => Array.from(mockedStorage.keys())[index] || null,
+        removeItem: (key) => mockedStorage.delete(key),
+      }
+
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const stateKey = 'broadcast-filter-test-key'
+
+        const ExampleComponent = Shade({
+          shadowDomName: 'shade-broadcast-channel-filter-test',
+          render: ({ useStoredState }) => {
+            const [value] = useStoredState(stateKey, 'initial', store)
+            return <div id="value">{value}</div>
+          },
+        })
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <ExampleComponent />,
+        })
+
+        await sleepAsync(50)
+        expect(document.getElementById('value')?.textContent).toBe('initial')
+
+        // Simulate cross-tab message with different key
+        const channel = new BroadcastChannel('useStoredState-broadcast-channel')
+        channel.postMessage({ key: 'different-key', value: 'should-be-ignored' })
+
+        await sleepAsync(50)
+        // Value should remain unchanged
+        expect(document.getElementById('value')?.textContent).toBe('initial')
+
+        channel.close()
+      })
+    })
+
+    it('should cleanup BroadcastChannel on component disposal', async () => {
+      const mockedStorage = new Map<string, string>()
+
+      const store: typeof localStorage = {
+        getItem: (key) => mockedStorage.get(key) || null,
+        setItem: (key, value) => mockedStorage.set(key, value),
+        length: 0,
+        clear: () => mockedStorage.clear(),
+        key: (index) => Array.from(mockedStorage.keys())[index] || null,
+        removeItem: (key) => mockedStorage.delete(key),
+      }
+
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const stateKey = 'broadcast-cleanup-test-key'
+
+        const ExampleComponent = Shade({
+          shadowDomName: 'shade-broadcast-channel-cleanup-test',
+          render: ({ useStoredState }) => {
+            const [value] = useStoredState(stateKey, 'initial', store)
+            return <div id="value">{value}</div>
+          },
+        })
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <ExampleComponent />,
+        })
+
+        await sleepAsync(50)
+        expect(document.getElementById('value')?.textContent).toBe('initial')
+
+        // Remove the component from DOM
+        document.body.innerHTML = ''
+        await sleepAsync(50)
+
+        // Create a new channel to send a message (simulating another tab)
+        const channel = new BroadcastChannel('useStoredState-broadcast-channel')
+        // This should not cause any errors since the component's channel should be closed
+        channel.postMessage({ key: stateKey, value: 'should-not-crash' })
+        await sleepAsync(50)
+
+        channel.close()
+        // Test passes if no errors occur
+      })
+    })
+  })
+})

package/src/shade.ts

@@ -1,10 +1,11 @@
 import type { Constructable } from '@furystack/inject'
 import { hasInjectorReference, Injector } from '@furystack/inject'
 import { ObservableValue } from '@furystack/utils'
-import type { ChildrenList, PartialElement, RenderOptions } from './models/index.js'
+import type { ChildrenList, CSSObject, PartialElement, RenderOptions } from './models/index.js'
 import { LocationService } from './services/location-service.js'
 import { ResourceManager } from './services/resource-manager.js'
 import { attachProps, attachStyles } from './shade-component.js'
+import { StyleManager } from './style-manager.js'
 
 export type ShadeOptions<TProps, TElementBase extends HTMLElement> = {
   /**
@@ -45,9 +46,26 @@ export type ShadeOptions<TProps, TElementBase extends HTMLElement> = {
   elementBase?: Constructable<TElementBase>
 
   /**
-   * A default style that will be applied to the element. Can be overridden by external styles.
+   * A default style that will be applied to the element as inline styles.
+   * Can be overridden by external styles on instances.
    */
   style?: Partial<CSSStyleDeclaration>
+
+  /**
+   * CSS styles injected as a stylesheet during component registration.
+   * Supports pseudo-selectors (&:hover, &:active) and nested selectors (& .class).
+   * Use this for component-level styling that doesn't need per-instance overrides.
+   *
+   * @example
+   * ```typescript
+   * css: {
+   *   padding: '16px',
+   *   '&:hover': { backgroundColor: '#f0f0f0' },
+   *   '& .title': { fontWeight: 'bold' }
+   * }
+   * ```
+   */
+  css?: CSSObject
 }
 
 /**
@@ -63,6 +81,11 @@ export const Shade = <TProps, TElementBase extends HTMLElement = HTMLElement>(
 
   const existing = customElements.get(customElementName)
   if (!existing) {
+    // Register CSS styles if provided
+    if (o.css) {
+      StyleManager.registerComponentStyles(customElementName, o.css, o.elementBaseName)
+    }
+
     const ElementBase = o.elementBase || HTMLElement
 
     customElements.define(
@@ -285,6 +308,10 @@ export const Shade = <TProps, TElementBase extends HTMLElement = HTMLElement>(
     el.props = props || ({} as TProps & PartialElement<TElementBase>)
     el.shadeChildren = children
 
+    if (o.elementBaseName) {
+      el.setAttribute('is', customElementName)
+    }
+
     attachStyles(el, { style: o.style })
     attachProps(el, props)