@furystack/shades 15.0.0 → 15.0.1

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