@furystack/shades 15.0.0 → 15.0.2

package/src/shade.ts

@@ -19,18 +19,18 @@ export type ShadeOptions<TProps, TElementBase extends HTMLElement> = {
    */
   customElementName: string
 
-  /**
-   * Render hook, this method will be executed on each and every render.
-   */
   render: (options: RenderOptions<TProps, TElementBase>) => JSX.Element | string | null
 
   /**
-   * Name of the HTML Element's base class. Needs to be defined if the elementBase is set. E.g.: 'div', 'button', 'input'
+   * Tag name of the base built-in element when extending one (e.g. `'a'`,
+   * `'button'`, `'input'`). Required when {@link ShadeOptions.elementBase}
+   * is set; passed to `customElements.define` as `{ extends }`.
    */
   elementBaseName?: string
 
   /**
-   * Base class for the custom element. Defaults to HTMLElement. E.g. HTMLButtonElement
+   * Constructor of the built-in element to extend (e.g. `HTMLButtonElement`).
+   * Defaults to `HTMLElement`. Pair with {@link ShadeOptions.elementBaseName}.
    */
   elementBase?: Constructable<TElementBase>
 
@@ -61,9 +61,14 @@ export type ShadeOptions<TProps, TElementBase extends HTMLElement> = {
 }
 
 /**
- * Factory method for creating Shade components
- * @param o The options object for component creation
- * @returns the JSX element
+ * Defines and registers a Shade component as a custom element. Returns a
+ * JSX-callable factory `(props, children?) => JSX.Element`. Throws when a
+ * component with the same {@link ShadeOptions.customElementName} has
+ * already been registered — registration is global and process-wide.
+ *
+ * The returned factory is the entry point for downstream code. The custom
+ * element class itself is installed via `customElements.define` and never
+ * directly exposed.
  */
 export const Shade = <TProps, TElementBase extends HTMLElement = HTMLElement>(
   o: ShadeOptions<TProps, TElementBase>,
@@ -84,9 +89,6 @@ export const Shade = <TProps, TElementBase extends HTMLElement = HTMLElement>(
       class extends (ElementBase as Constructable<HTMLElement>) implements JSX.Element {
         private _renderCount = 0
 
-        /**
-         * @returns the current render count
-         */
         public getRenderCount() {
           return this._renderCount
         }
@@ -128,28 +130,15 @@ export const Shade = <TProps, TElementBase extends HTMLElement = HTMLElement>(
           await this.resourceManager[Symbol.asyncDispose]()
         }
 
-        /**
-         * Will be triggered when updating the external props object
-         */
         public props!: TProps & { children?: JSX.Element[] } & PartialElement<TElementBase>
 
-        /**
-         * Will be updated when on children change
-         */
         public shadeChildren?: ChildrenList
 
-        /**
-         * @param options Options for rendering the component
-         * @returns the JSX element
-         */
         public render = (options: RenderOptions<TProps, TElementBase>) => {
           this._renderCount++
           return o.render(options)
         }
 
-        /**
-         * @returns values for the current render options
-         */
         private getRenderOptions = (): RenderOptions<TProps, TElementBase> => {
           const renderOptions: RenderOptions<TProps, TElementBase> = {
             props: this.props,
@@ -163,8 +152,8 @@ export const Shade = <TProps, TElementBase extends HTMLElement = HTMLElement>(
               const existingRef = this._refs.get(key) as RefObject<T> | undefined
               if (existingRef) return existingRef
               const refObject = { current: null } as { current: T | null }
-              this._refs.set(key, refObject as unknown as RefObject<Element>)
-              return refObject as RefObject<T>
+              this._refs.set(key, refObject)
+              return refObject
             },
             useObservable: (key, observable, options) => {
               const onChange = options?.onChange || (() => this.updateComponent())
@@ -308,7 +297,7 @@ export const Shade = <TProps, TElementBase extends HTMLElement = HTMLElement>(
                 this.removeAttribute(key)
               }
               if (this._prevHostProps.style) {
-                for (const sk of Object.keys(this._prevHostProps.style as Record<string, string>)) {
+                for (const sk of Object.keys(this._prevHostProps.style)) {
                   if (sk.startsWith('--')) {
                     this.style.removeProperty(sk)
                   } else {
@@ -464,11 +453,9 @@ export const Shade = <TProps, TElementBase extends HTMLElement = HTMLElement>(
 }
 
 /**
- * Flushes any pending microtask-based component updates.
- * Useful in tests to wait for batched renders to complete before asserting DOM state.
- *
- * Child component updates during reconciliation are performed synchronously, so a single
- * `await flushUpdates()` is sufficient to settle the entire component tree after a state change.
- * @returns a promise that resolves after the current microtask queue has been processed
+ * Awaits the next microtask tick — long enough for `updateComponent`'s
+ * batching microtask to drain. A single `await flushUpdates()` settles the
+ * entire component tree because child reconciliation is synchronous within
+ * the parent's render. Use in tests before asserting on DOM state.
  */
 export const flushUpdates = (): Promise<void> => new Promise<void>((resolve) => queueMicrotask(resolve))

package/src/style-manager.ts

@@ -1,19 +1,16 @@
 import { generateCSS } from './css-generator.js'
 import type { CSSObject } from './models/css-object.js'
+import type { Shade } from './shade.js'
 
 /**
- * Singleton that manages component CSS injection.
- * Creates and maintains a shared `<style>` element in the document head,
- * and tracks registered component styles to avoid duplicates.
+ * Owns a shared `<style data-shades-styles>` element in `document.head`
+ * and dedupes component-style registration. Internal — consumers use
+ * the {@link StyleManager} singleton.
  */
 class StyleManagerClass {
   private styleElement: HTMLStyleElement | null = null
   private registeredComponents = new Set<string>()
 
-  /**
-   * Gets or creates the shared style element
-   * @returns The style element for CSS injection
-   */
   private getStyleElement(): HTMLStyleElement {
     if (!this.styleElement) {
       this.styleElement = document.createElement('style')
@@ -66,26 +63,16 @@ class StyleManagerClass {
     return false
   }
 
-  /**
-   * Checks if a component's styles have already been registered
-   * @param customElementName - The component identifier to check
-   * @returns True if styles are already registered
-   */
   public isRegistered(customElementName: string): boolean {
     return this.registeredComponents.has(customElementName)
   }
 
-  /**
-   * Gets all registered component names (for debugging/testing)
-   * @returns Set of registered component names
-   */
+  /** Snapshot of registered component names. Intended for diagnostics + tests. */
   public getRegisteredComponents(): ReadonlySet<string> {
     return this.registeredComponents
   }
 
-  /**
-   * Clears all registered styles (useful for testing)
-   */
+  /** Removes the shared style element and clears the registration set. Test-only. */
   public clear(): void {
     this.registeredComponents.clear()
     if (this.styleElement) {
@@ -97,8 +84,8 @@ class StyleManagerClass {
 }
 
 /**
- * Singleton instance for managing component CSS styles.
- * Use this to register component-level styles that support
- * pseudo-selectors and nested selectors.
+ * Process-wide CSS injection registry for Shade components. The {@link Shade}
+ * factory calls `registerComponentStyles` automatically; direct use is rare
+ * (e.g. injecting a third-party stylesheet keyed off a component name).
  */
 export const StyleManager = new StyleManagerClass()

package/src/styled-shade.ts

@@ -1,17 +1,14 @@
 import type { ChildrenList } from './models/children-list.js'
 
-/**
- * Props constraint for styled components - must have an optional style property
- */
 type StyledProps = {
   style?: Partial<CSSStyleDeclaration>
 }
 
 /**
- * Creates a shortcut for a specific custom Shade element with additional styles
- * @param element The element instance
- * @param styles The additional styles to add
- * @returns The updated element
+ * Wraps a Shade factory with a baked-in `style` overlay. Baked-in `styles`
+ * win over caller-supplied `style` props (the wrapper merges last). Use to
+ * specialise an existing Shade (e.g. theme variants) without registering
+ * a new custom element.
  */
 export const styledShade = <TProps extends StyledProps>(
   element: (props: TProps, children?: ChildrenList) => JSX.Element,
@@ -25,7 +22,7 @@ export const styledShade = <TProps extends StyledProps>(
           ...props.style,
           ...styles,
         },
-      } as TProps,
+      },
       childrenList,
     )
   }

package/src/view-transition.ts

@@ -8,16 +8,13 @@ export type ViewTransitionConfig = {
 }
 
 /**
- * Wraps a DOM update in `document.startViewTransition()` when the View Transition API
- * is available and `config` is truthy. Falls back to calling `update()` directly otherwise.
+ * Runs `update` inside `document.startViewTransition()` when the API is
+ * available and `config` is truthy; otherwise calls `update` synchronously.
  *
- * Returns the `updateCallbackDone` promise when a transition is started, allowing callers
- * that need to wait for the DOM update (e.g. to run lifecycle hooks) to `await` the result.
- * Returns `undefined` when no transition is used (the update runs synchronously).
- *
- * @param config - The view transition configuration (boolean or object with types)
- * @param update - The synchronous DOM update callback
- * @returns A promise that resolves after the update callback completes inside the transition, or `undefined`
+ * The returned promise (when a transition starts) resolves once the update
+ * callback completes inside the transition — callers that need to chain
+ * lifecycle work after the DOM swap can `await` it. Returns `undefined`
+ * when no transition is used.
  */
 export const maybeViewTransition = (
   config: boolean | ViewTransitionConfig | undefined,
@@ -33,19 +30,10 @@ export const maybeViewTransition = (
 }
 
 /**
- * Keeps a "displayed" copy of `value` that is updated through a view transition
- * whenever the value changes and `shouldTransition` returns true.
- *
- * When the transition is skipped (config is falsy or `shouldTransition` returns false),
- * the displayed value is updated synchronously without an animation.
- *
- * @param useState - The component's `useState` hook
- * @param key - Unique state key for caching the displayed value
- * @param value - The latest source value (e.g. from `useObservable` or derived from props)
- * @param config - View transition configuration forwarded to `maybeViewTransition`
- * @param shouldTransition - Predicate that decides whether a value change warrants a transition.
- *   Defaults to `() => true` (always transition).
- * @returns The currently displayed value
+ * Decouples a component's "displayed" value from its source. When `value`
+ * changes and `shouldTransition(prev, next)` returns true, the swap is
+ * routed through {@link maybeViewTransition}; otherwise the displayed
+ * value updates synchronously. `shouldTransition` defaults to always-true.
  */
 export const transitionedValue = <T>(
   useState: <S>(key: string, initialValue: S) => [S, (v: S) => void],

package/src/vnode.spec.ts

@@ -545,7 +545,7 @@ describe('vnode', () => {
         ;(fakeShadeEl as unknown as Record<string, unknown>).props = { count: 1 }
         ;(fakeShadeEl as unknown as Record<string, unknown>).shadeChildren = undefined
 
-        const factory = vi.fn(() => fakeShadeEl as unknown as JSX.Element)
+        const factory = vi.fn(() => fakeShadeEl)
 
         const old: VChild[] = [{ _brand: 'vnode', type: factory, props: { count: 1 }, children: [], _el: fakeShadeEl }]
         parent.appendChild(fakeShadeEl)
@@ -566,7 +566,7 @@ describe('vnode', () => {
         ;(fakeShadeEl as unknown as Record<string, unknown>).props = { elevation: 2 }
         ;(fakeShadeEl as unknown as Record<string, unknown>).shadeChildren = undefined
 
-        const factory = vi.fn(() => fakeShadeEl as unknown as JSX.Element)
+        const factory = vi.fn(() => fakeShadeEl)
 
         const old: VChild[] = [
           { _brand: 'vnode', type: factory, props: { elevation: 2 }, children: [], _el: fakeShadeEl },
@@ -591,7 +591,7 @@ describe('vnode', () => {
         ;(fakeShadeEl as unknown as Record<string, unknown>).props = props
         ;(fakeShadeEl as unknown as Record<string, unknown>).shadeChildren = undefined
 
-        const factory = vi.fn(() => fakeShadeEl as unknown as JSX.Element)
+        const factory = vi.fn(() => fakeShadeEl)
 
         const old: VChild[] = [{ _brand: 'vnode', type: factory, props: { count: 1 }, children: [], _el: fakeShadeEl }]
         parent.appendChild(fakeShadeEl)

package/src/vnode.ts

@@ -197,9 +197,9 @@ export const toVChildArray = (renderResult: unknown): VChild[] => {
   // Real DOM element (from async code that ran outside renderMode)
   if (renderResult instanceof DocumentFragment) {
     return Array.from(renderResult.childNodes).map((node) => ({
-      _brand: VNODE_BRAND as typeof VNODE_BRAND,
+      _brand: VNODE_BRAND,
       type: EXISTING_NODE,
-      props: {} as Record<string, unknown>,
+      props: {},
       children: [] as VChild[],
       _el: node,
     }))