@furystack/shades 11.0.35 → 12.0.0

package/src/css-generator.spec.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from 'vitest'
+import { camelToKebab, generateCSS, generateCSSRule, isSelectorKey, propertiesToCSSString } from './css-generator.js'
+import type { CSSProperties } from './models/css-object.js'
+
+describe('css-generator', () => {
+  describe('camelToKebab', () => {
+    it('should convert camelCase to kebab-case', () => {
+      expect(camelToKebab('backgroundColor')).toBe('background-color')
+      expect(camelToKebab('fontSize')).toBe('font-size')
+      expect(camelToKebab('borderTopLeftRadius')).toBe('border-top-left-radius')
+    })
+
+    it('should handle single word properties', () => {
+      expect(camelToKebab('color')).toBe('color')
+      expect(camelToKebab('margin')).toBe('margin')
+    })
+
+    it('should handle empty string', () => {
+      expect(camelToKebab('')).toBe('')
+    })
+  })
+
+  describe('isSelectorKey', () => {
+    it('should return true for selector keys starting with &', () => {
+      expect(isSelectorKey('&:hover')).toBe(true)
+      expect(isSelectorKey('&:active')).toBe(true)
+      expect(isSelectorKey('& .className')).toBe(true)
+      expect(isSelectorKey('& > div')).toBe(true)
+    })
+
+    it('should return false for regular CSS property keys', () => {
+      expect(isSelectorKey('color')).toBe(false)
+      expect(isSelectorKey('backgroundColor')).toBe(false)
+      expect(isSelectorKey('fontSize')).toBe(false)
+    })
+  })
+
+  describe('propertiesToCSSString', () => {
+    it('should convert CSS properties object to CSS string', () => {
+      const result = propertiesToCSSString({
+        color: 'red',
+        backgroundColor: 'blue',
+      })
+      expect(result).toBe('color: red; background-color: blue')
+    })
+
+    it('should skip undefined and null values', () => {
+      const result = propertiesToCSSString({
+        color: 'red',
+        backgroundColor: undefined,
+      })
+      expect(result).toBe('color: red')
+    })
+
+    it('should skip empty string values', () => {
+      const result = propertiesToCSSString({
+        color: 'red',
+        backgroundColor: '',
+      })
+      expect(result).toBe('color: red')
+    })
+
+    it('should return empty string for empty object', () => {
+      const result = propertiesToCSSString({})
+      expect(result).toBe('')
+    })
+
+    it('should ignore selector keys', () => {
+      // Type assertion needed to test mixed object with selectors
+      const mixedObject = {
+        color: 'red',
+        '&:hover': { color: 'blue' },
+      }
+      const result = propertiesToCSSString(mixedObject as unknown as CSSProperties)
+      expect(result).toBe('color: red')
+    })
+
+    it('should filter out non-string values', () => {
+      // Type assertion to test edge case with non-string values
+      const mixedObject = {
+        color: 'red',
+        opacity: 0.5, // number - should be filtered
+        display: 'flex',
+        hidden: true, // boolean - should be filtered
+      }
+      const result = propertiesToCSSString(mixedObject as unknown as CSSProperties)
+      expect(result).toBe('color: red; display: flex')
+    })
+  })
+
+  describe('generateCSSRule', () => {
+    it('should generate a complete CSS rule', () => {
+      const result = generateCSSRule('my-component', {
+        color: 'red',
+        padding: '10px',
+      })
+      expect(result).toBe('my-component { color: red; padding: 10px; }')
+    })
+
+    it('should return empty string for empty properties', () => {
+      const result = generateCSSRule('my-component', {})
+      expect(result).toBe('')
+    })
+  })
+
+  describe('generateCSS', () => {
+    it('should generate CSS for base properties only', () => {
+      const result = generateCSS('my-component', {
+        color: 'red',
+        padding: '10px',
+      })
+      expect(result).toBe('my-component { color: red; padding: 10px; }')
+    })
+
+    it('should generate CSS with pseudo-selectors', () => {
+      const result = generateCSS('my-component', {
+        color: 'red',
+        '&:hover': { color: 'blue' },
+      })
+      expect(result).toContain('my-component { color: red; }')
+      expect(result).toContain('my-component:hover { color: blue; }')
+    })
+
+    it('should generate CSS with nested class selectors', () => {
+      const result = generateCSS('my-component', {
+        padding: '10px',
+        '& .inner': { fontWeight: 'bold' },
+      })
+      expect(result).toContain('my-component { padding: 10px; }')
+      expect(result).toContain('my-component .inner { font-weight: bold; }')
+    })
+
+    it('should generate CSS with child selectors', () => {
+      const result = generateCSS('my-component', {
+        display: 'flex',
+        '& > div': { margin: '5px' },
+      })
+      expect(result).toContain('my-component { display: flex; }')
+      expect(result).toContain('my-component > div { margin: 5px; }')
+    })
+
+    it('should handle multiple pseudo-selectors', () => {
+      const result = generateCSS('my-button', {
+        backgroundColor: 'blue',
+        '&:hover': { backgroundColor: 'darkblue' },
+        '&:active': { backgroundColor: 'navy' },
+        '&:disabled': { opacity: '0.5' },
+      })
+      expect(result).toContain('my-button { background-color: blue; }')
+      expect(result).toContain('my-button:hover { background-color: darkblue; }')
+      expect(result).toContain('my-button:active { background-color: navy; }')
+      expect(result).toContain('my-button:disabled { opacity: 0.5; }')
+    })
+
+    it('should handle empty css object', () => {
+      const result = generateCSS('my-component', {})
+      expect(result).toBe('')
+    })
+
+    it('should handle css object with only selectors', () => {
+      const result = generateCSS('my-component', {
+        '&:hover': { color: 'blue' },
+      })
+      expect(result).toBe('my-component:hover { color: blue; }')
+    })
+
+    it('should skip selector keys with non-object values', () => {
+      // Type assertion to test edge case with invalid selector values
+      const cssObject = {
+        color: 'red',
+        '&:hover': 'invalid', // string instead of object - should be skipped
+        '&:active': null, // null - should be skipped
+        '&:focus': { backgroundColor: 'blue' }, // valid - should be included
+      }
+      const result = generateCSS('my-component', cssObject as unknown as Parameters<typeof generateCSS>[1])
+      expect(result).toContain('my-component { color: red; }')
+      expect(result).toContain('my-component:focus { background-color: blue; }')
+      expect(result).not.toContain('invalid')
+      expect(result).not.toContain(':hover')
+      expect(result).not.toContain(':active')
+    })
+  })
+})

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/initialize.ts

@@ -1,10 +1,22 @@
 import type { Injector } from '@furystack/inject'
 
+/**
+ * Options for bootstrapping a Shades application.
+ */
 export interface InitializeOptions {
+  /** The DOM element that will host the application */
   rootElement: HTMLElement
+  /** The root JSX element to render */
   jsxElement: JSX.Element
+  /** The root injector instance for dependency injection */
   injector: Injector
 }
+
+/**
+ * Bootstraps a Shades application by attaching the root JSX element to a DOM node
+ * and wiring up the dependency injection context.
+ * @param options The initialization options
+ */
 export const initializeShadeRoot = (options: InitializeOptions) => {
   options.jsxElement.injector = options.injector
   options.rootElement.appendChild(options.jsxElement)

package/src/jsx.ts

@@ -1,6 +1,48 @@
 import type { Injector } from '@furystack/inject'
 import type { ChildrenList, PartialElement } from './models/index.js'
 import type { ResourceManager } from './services/resource-manager.js'
+import type {
+  SvgAnimateAttributes,
+  SvgAnimateMotionAttributes,
+  SvgAnimateTransformAttributes,
+  SvgCircleAttributes,
+  SvgClipPathAttributes,
+  SvgCoreAttributes,
+  SvgDefsAttributes,
+  SvgDescAttributes,
+  SvgEllipseAttributes,
+  SvgFeBlendAttributes,
+  SvgFeColorMatrixAttributes,
+  SvgFeCompositeAttributes,
+  SvgFeFloodAttributes,
+  SvgFeGaussianBlurAttributes,
+  SvgFeMergeAttributes,
+  SvgFeMergeNodeAttributes,
+  SvgFeOffsetAttributes,
+  SvgFilterAttributes,
+  SvgForeignObjectAttributes,
+  SvgGAttributes,
+  SvgImageAttributes,
+  SvgLinearGradientAttributes,
+  SvgLineAttributes,
+  SvgMarkerAttributes,
+  SvgMaskAttributes,
+  SvgPathAttributes,
+  SvgPatternAttributes,
+  SvgPolygonAttributes,
+  SvgPolylineAttributes,
+  SvgRadialGradientAttributes,
+  SvgRectAttributes,
+  SvgSetAttributes,
+  SvgStopAttributes,
+  SvgSvgAttributes,
+  SvgSymbolAttributes,
+  SvgTextAttributes,
+  SvgTextPathAttributes,
+  SvgTitleAttributes,
+  SvgTspanAttributes,
+  SvgUseAttributes,
+} from './svg-types.js'
 
 declare global {
   // eslint-disable-next-line @typescript-eslint/no-namespace
@@ -10,7 +52,6 @@ declare global {
       props: TProps
       updateComponent: () => void
       shadeChildren?: ChildrenList
-      callConstructed: () => void
       resourceManager: ResourceManager
       getRenderCount(): number
     }
@@ -423,7 +464,7 @@ declare global {
        * The <svg> tag defines a container for SVG graphics.
        * SVG has several methods for drawing paths, boxes, circles, text, and graphic images.
        */
-      svg: PartialElement<SVGElement>
+      svg: SvgSvgAttributes
       /**
        * The <table> tag defines an HTML table.
        * An HTML table consists of the <table> element and one or more <tr>, <th>, and <td> elements.
@@ -519,6 +560,92 @@ declare global {
        * Tip: When a word is too long, or you are afraid that the browser will break your lines at the wrong place, you can use the <wbr> element to add word break opportunities.
        */
       wbr: PartialElement<HTMLElement>
+
+      // -------------------------------------------------------------------
+      // SVG Elements
+      // -------------------------------------------------------------------
+
+      /** The `<g>` element groups SVG elements together. */
+      g: SvgGAttributes
+      /** The `<defs>` element stores graphical objects for later reuse. */
+      defs: SvgDefsAttributes
+      /** The `<symbol>` element defines a reusable graphical template. */
+      symbol: SvgSymbolAttributes
+      /** The `<use>` element references another element for rendering. */
+      use: SvgUseAttributes
+      /** The `<path>` element defines a shape via SVG path commands. */
+      path: SvgPathAttributes
+      /** The `<rect>` element draws a rectangle. */
+      rect: SvgRectAttributes
+      /** The `<circle>` element draws a circle. */
+      circle: SvgCircleAttributes
+      /** The `<ellipse>` element draws an ellipse. */
+      ellipse: SvgEllipseAttributes
+      /** The `<line>` element draws a straight line between two points. */
+      line: SvgLineAttributes
+      /** The `<polyline>` element draws connected straight line segments. */
+      polyline: SvgPolylineAttributes
+      /** The `<polygon>` element draws a closed shape of connected line segments. */
+      polygon: SvgPolygonAttributes
+      /** The `<text>` element renders text in SVG. */
+      text: SvgTextAttributes
+      /** The `<tspan>` element defines a subtext within a `<text>` element. */
+      tspan: SvgTspanAttributes
+      /** The `<textPath>` element renders text along a path. */
+      textPath: SvgTextPathAttributes
+      /** The `<clipPath>` element defines a clipping region. */
+      clipPath: SvgClipPathAttributes
+      /** The `<mask>` element defines an alpha mask for compositing. */
+      mask: SvgMaskAttributes
+      /** The `<linearGradient>` element defines a linear color gradient. */
+      linearGradient: SvgLinearGradientAttributes
+      /** The `<radialGradient>` element defines a radial color gradient. */
+      radialGradient: SvgRadialGradientAttributes
+      /** The `<stop>` element defines a color stop in a gradient. */
+      stop: SvgStopAttributes
+      /** The `<pattern>` element defines a repeating graphic pattern. */
+      pattern: SvgPatternAttributes
+      /** The `<marker>` element defines a graphic for drawing on edges of shapes. */
+      marker: SvgMarkerAttributes
+      /** The `<filter>` element defines a set of filter operations. */
+      filter: SvgFilterAttributes
+      /** The `<feGaussianBlur>` filter primitive blurs the input image. */
+      feGaussianBlur: SvgFeGaussianBlurAttributes
+      /** The `<feBlend>` filter primitive composites two inputs. */
+      feBlend: SvgFeBlendAttributes
+      /** The `<feColorMatrix>` filter primitive applies a matrix color transform. */
+      feColorMatrix: SvgFeColorMatrixAttributes
+      /** The `<feOffset>` filter primitive offsets the input image. */
+      feOffset: SvgFeOffsetAttributes
+      /** The `<feFlood>` filter primitive fills with a solid color. */
+      feFlood: SvgFeFloodAttributes
+      /** The `<feMerge>` filter primitive composites multiple inputs. */
+      feMerge: SvgFeMergeAttributes
+      /** The `<feMergeNode>` element defines an input for `<feMerge>`. */
+      feMergeNode: SvgFeMergeNodeAttributes
+      /** The `<feComposite>` filter primitive combines images using Porter-Duff operations. */
+      feComposite: SvgFeCompositeAttributes
+      /** The `<image>` element (SVG) embeds a raster image. */
+      image: SvgImageAttributes
+      /** The `<foreignObject>` element embeds external XML (e.g. HTML) in SVG. */
+      foreignObject: SvgForeignObjectAttributes
+      /** The `<animate>` element animates an attribute over time. */
+      animate: SvgAnimateAttributes
+      /** The `<animateMotion>` element animates an element along a path. */
+      animateMotion: SvgAnimateMotionAttributes
+      /** The `<animateTransform>` element animates a transformation attribute. */
+      animateTransform: SvgAnimateTransformAttributes
+      /** The `<set>` element sets an attribute to a value for a duration. */
+      set: SvgSetAttributes
+      /** The `<title>` element (SVG) provides an accessible title. */
+      title: SvgTitleAttributes
+      /** The `<desc>` element provides an accessible description. */
+      desc: SvgDescAttributes
+      /**
+       * Catch-all for SVG filter primitives and other SVG elements
+       * not explicitly listed above.
+       */
+      [key: `fe${string}`]: SvgCoreAttributes
     }
   }
 }

package/src/models/children-list.ts

@@ -1 +1,7 @@
-export type ChildrenList = Array<string | HTMLElement | JSX.Element | string[] | HTMLElement[] | JSX.Element[]>
+/**
+ * The type for children passed to Shade components and intrinsic JSX elements.
+ * Supports strings, HTML/SVG elements, JSX elements, and nested arrays of these.
+ */
+export type ChildrenList = Array<
+  string | HTMLElement | SVGElement | JSX.Element | string[] | HTMLElement[] | SVGElement[] | JSX.Element[]
+>

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/models/partial-element.ts

@@ -1,5 +1,16 @@
-export type PartialElement<T> = T extends { style?: CSSStyleDeclaration }
+import type { RefObject } from './render-options.js'
+
+/**
+ * Makes all properties of an HTML element type optional, with `style` narrowed
+ * to `Partial<CSSStyleDeclaration>` and a `ref` prop for capturing DOM references.
+ * Used as the props type for intrinsic JSX elements and component host element overrides.
+ * @typeParam T - The base HTML element type
+ */
+export type PartialElement<T> = (T extends { style?: CSSStyleDeclaration }
   ? Omit<Partial<T>, 'style'> & {
       style?: Partial<CSSStyleDeclaration>
     }
-  : Partial<T>
+  : Partial<T>) & {
+  /** Ref object to capture a reference to the underlying DOM element. */
+  ref?: RefObject<Element>
+}

package/src/models/render-options.ts

@@ -3,12 +3,81 @@ import type { ObservableValue, ValueObserverOptions } from '@furystack/utils'
 import type { ChildrenList } from './children-list.js'
 import type { PartialElement } from './partial-element.js'
 
+/**
+ * A reference object returned by `useRef`.
+ * `current` is set to the DOM element when it is mounted, and `null` when unmounted.
+ * The `readonly` modifier ensures covariance so that `RefObject<HTMLInputElement>`
+ * is assignable to `RefObject<Element>`.
+ */
+export type RefObject<T extends Element = HTMLElement> = {
+  readonly current: T | null
+}
+
+/**
+ * Options provided to a Shade component's `render` function.
+ * Contains the current props, injector, children, and hooks for managing state, side effects, and host element attributes.
+ * @typeParam TProps - The component's props type
+ * @typeParam TElementBase - The base HTML element type (defaults to HTMLElement)
+ */
 export type RenderOptions<TProps, TElementBase extends HTMLElement = HTMLElement> = {
   readonly props: TProps & PartialElement<TElementBase>
   renderCount: number
   injector: Injector
   children?: ChildrenList
-  element: JSX.Element<TProps>
+  /**
+   * Declaratively sets attributes and styles on the host custom element.
+   * Can be called multiple times per render; each call merges into the previous values.
+   *
+   * CSS custom properties (e.g. `--my-color`) are applied via `setProperty`.
+   * The `style` property accepts both standard camelCase properties and CSS custom properties.
+   *
+   * **Best practice:** Use `useHostProps` for data attributes, ARIA attributes, CSS variables,
+   * and event handlers on the host element instead of imperative DOM manipulation.
+   *
+   * @param hostProps An object of attribute key-value pairs, optionally including a `style` record
+   *
+   * **Note:** Object and function values are assigned as properties on the host element
+   * (not as attributes). This means you can set event handlers (e.g. `onclick`) and
+   * even class properties like `injector` via `useHostProps`.
+   *
+   * @example
+   * ```typescript
+   * useHostProps({
+   *   'data-variant': props.variant,
+   *   role: 'progressbar',
+   *   'aria-valuenow': String(value),
+   *   style: {
+   *     '--btn-color-main': colors.main,
+   *     display: 'flex',
+   *   },
+   * })
+   * ```
+   */
+  useHostProps: (hostProps: Record<string, unknown> & { style?: Record<string, string> }) => void
+
+  /**
+   * Creates a mutable ref object that can be attached to intrinsic JSX elements via the `ref` prop.
+   * The ref's `current` property will be set to the DOM element after mount and `null` on unmount.
+   *
+   * Refs are cached by key, so calling `useRef` with the same key returns the same object across renders.
+   *
+   * **Best practice:** Prefer declarative JSX and `useHostProps` when possible.
+   * Use refs sparingly for imperative needs like focus management or measuring elements.
+   *
+   * @param key A unique key for caching the ref object
+   * @returns A ref object with a `current` property
+   *
+   * @example
+   * ```typescript
+   * const inputRef = useRef<HTMLInputElement>('input')
+   * // In JSX:
+   * <input ref={inputRef} />
+   * // Later:
+   * inputRef.current?.focus()
+   * ```
+   */
+  useRef: <T extends Element = HTMLElement>(key: string) => RefObject<T>
+
   /**
    * Creates and disposes a resource after the component has been detached from the DOM
    * @param key The key for caching the disposable resource
@@ -18,11 +87,29 @@ export type RenderOptions<TProps, TElementBase extends HTMLElement = HTMLElement
   useDisposable: <T extends Disposable | AsyncDisposable>(key: string, factory: () => T) => T
 
   /**
-   * Creates a state object from an existing observable value
+   * Creates a state object from an existing observable value.
+   *
+   * **Important:** By default, this will trigger a full component re-render when the observable value changes.
+   * To prevent re-renders (e.g., for manual DOM updates or animations), provide a custom `onChange` callback.
+   *
    * @param key The key for caching the observable value
    * @param observable The observable value to observe
-   * @param options Optional options for the observer including onChange callback
+   * @param options Optional options for the observer
+   * @param options.onChange Custom callback when value changes. If not provided, the component will re-render on each change.
    * @returns tuple with the current value and a setter function
+   *
+   * @example
+   * // Default behavior: re-renders component on change
+   * const [count] = useObservable('count', countObservable)
+   *
+   * @example
+   * // Custom onChange: no re-render, update host element via useHostProps
+   * useHostProps({ 'data-active': count > 0 ? '' : undefined })
+   * const [count] = useObservable('count', countObservable, {
+   *   onChange: () => {
+   *     // Triggers a re-render so useHostProps above picks up the new value
+   *   }
+   * })
    */
   useObservable: <T>(
     key: string,