@furystack/shades 14.0.0 → 15.0.1

package/src/shade-component.ts

@@ -22,9 +22,9 @@ export const setRenderMode = (mode: boolean): void => {
 // ---------------------------------------------------------------------------
 
 /**
- * Appends a list of items to an element
- * @param el the root element
- * @param children array of items to append
+ * Appends `children` to `el`. Strings/numbers are wrapped in text nodes;
+ * nested arrays are flattened recursively. Used outside render mode (real
+ * DOM); inside render mode the JSX factory builds VNodes instead.
  */
 export const appendChild = (el: Element | DocumentFragment, children: ChildrenList) => {
   for (const child of children) {
@@ -46,10 +46,7 @@ export const hasStyle = (props: unknown): props is { style: Partial<CSSStyleDecl
   )
 }
 
-/**
- * @param el The Target HTML Element
- * @param props The Properties to fetch The Styles Object
- */
+/** Copies `props.style` (when present) onto `el.style`. No-op for non-styled props. */
 export const attachStyles = (el: HTMLElement, props: unknown) => {
   if (hasStyle(props))
     for (const key in props.style) {
@@ -70,9 +67,9 @@ export const attachDataAttributes = <TProps extends object>(el: HTMLElement, pro
 }
 
 /**
- * Attaches properties to an HTML element
- * @param el The Target HTML Element
- * @param props The Props to attach
+ * Assigns `props` onto `el` as element properties (not attributes). `style`
+ * is forwarded to {@link attachStyles}; `data-*` / `aria-*` are forwarded to
+ * {@link attachDataAttributes}.
  */
 export const attachProps = <TProps extends object>(el: HTMLElement, props: TProps) => {
   if (!props) {
@@ -90,11 +87,9 @@ export const attachProps = <TProps extends object>(el: HTMLElement, props: TProp
 }
 
 /**
- * Attaches properties to an SVG element via setAttribute.
- * SVG attributes are XML-based and must be set via setAttribute,
- * not via property assignment like HTML elements.
- * @param el The target SVG element
- * @param props The props to attach
+ * SVG counterpart of {@link attachProps}. SVG attributes are XML-based and
+ * must be set via `setAttribute` rather than property assignment. Event
+ * handlers (`on*`) and `style` are still set as properties.
  */
 export const attachSvgProps = <TProps extends object>(el: Element, props: TProps) => {
   if (!props) {
@@ -122,8 +117,10 @@ type CreateComponentArgs<TProps> = [
 ]
 
 /**
- * Factory method that creates a component. This should be configured as a default JSX Factory in tsconfig.
- * @returns the created JSX element
+ * JSX factory backing both intrinsic elements (`<div>`, `<svg>`, …) and
+ * Shade components (`<MyShade>`). Configured as `jsxFactory` in tsconfig.
+ * Outside render mode this returns real DOM nodes; the render-mode wrapper
+ * {@link createComponent} swaps in VNode descriptors.
  */
 export const createComponentInner = <TProps extends object>(
   ...[elementType, props, ...children]: CreateComponentArgs<TProps>

package/src/shade.ts

@@ -1,5 +1,5 @@
-import type { Constructable } from '@furystack/inject'
-import { hasInjectorReference, Injector } from '@furystack/inject'
+import type { Constructable } from '@furystack/core'
+import { Injector } from '@furystack/inject'
 import { ObservableValue } from '@furystack/utils'
 import type { ChildrenList, CSSObject, PartialElement, RenderOptions } from './models/index.js'
 import type { RefObject } from './models/render-options.js'
@@ -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,19 +152,19 @@ 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, obesrvable, options) => {
+            useObservable: (key, observable, options) => {
               const onChange = options?.onChange || (() => this.updateComponent())
-              return this.resourceManager.useObservable(key, obesrvable, onChange, options)
+              return this.resourceManager.useObservable(key, observable, onChange, options)
             },
             useState: (key, initialValue) =>
               this.resourceManager.useState(key, initialValue, this.updateComponent.bind(this)),
             useSearchState: (key, initialValue) =>
               this.resourceManager.useObservable(
                 `useSearchState-${key}`,
-                this.injector.getInstance(LocationService).useSearchParam(key, initialValue),
+                this.injector.get(LocationService).useSearchParam(key, initialValue),
                 () => 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 {
@@ -416,8 +405,8 @@ export const Shade = <TProps, TElementBase extends HTMLElement = HTMLElement>(
             return this._injector
           }
 
-          const fromProps = hasInjectorReference(this.props) && this.props.injector
-          if (fromProps && fromProps instanceof Injector) {
+          const fromProps = (this.props as { injector?: unknown } | undefined)?.injector
+          if (fromProps instanceof Injector) {
             return fromProps
           }
 
@@ -426,7 +415,10 @@ export const Shade = <TProps, TElementBase extends HTMLElement = HTMLElement>(
             this._injector = fromParent
             return fromParent
           }
-          // Injector not set explicitly and not found on parents!
+          // Fallback for isolated components (tests and non-DI use cases) that
+          // never reach for any services. Components that do resolve tokens
+          // will fail loudly at resolution time, since this throwaway injector
+          // has no bindings.
           return new Injector()
         }
 
@@ -461,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,
     }))