@rindo/core 2.18.0 → 2.22.3

package/internal/rindo-public-compiler.d.ts

@@ -1,6 +1,6 @@
-import type { JsonDocs } from './rindo-public-docs';
-import type { PrerenderUrlResults } from '../internal';
 import type { ConfigFlags } from '../cli/config-flags';
+import type { PrerenderUrlResults } from '../internal';
+import type { JsonDocs } from './rindo-public-docs';
 export * from './rindo-public-docs';
 /**
  * https://rindojs.web.app/docs/config/
@@ -66,7 +66,7 @@ export interface RindoConfig {
      * The namespace config is a string representing a namespace for the app.
      * For apps that are not meant to be a library of reusable components,
      * the default of App is just fine. However, if the app is meant to be consumed
-     * as a third-party library, such as Navify, a unique namespace is required.
+     * as a third-party library, such as Family, a unique namespace is required.
      */
     namespace?: string;
     /**
@@ -153,7 +153,7 @@ export interface RindoConfig {
      */
     hydratedFlag?: HydratedFlag;
     /**
-     * Navify prefers to hide all components prior to hydration with a style tag appended
+     * Family prefers to hide all components prior to hydration with a style tag appended
      * to the head of the document containing some `visibility: hidden;` css rules.
      *
      * Disabling this will remove the style tag that sets `visibility: hidden;` on all
@@ -163,7 +163,7 @@ export interface RindoConfig {
      */
     invisiblePrehydration?: boolean;
     /**
-     * Sets the task queue used by rindo's runtime. The task queue schedules DOM read and writes
+     * Sets the task queue used by Rindo's runtime. The task queue schedules DOM read and writes
      * across the frames to efficiently render and reduce layout thrashing. By default,
      * `async` is used. It's recommended to also try each setting to decide which works
      * best for your use-case. In all cases, if your app has many CPU intensive tasks causing the
@@ -351,12 +351,12 @@ export interface Config extends RindoConfig {
  * conforming to a given interface. For best results, pair with a validation
  * function as shown in the example.
  */
-declare type Loose<T extends Object> = Record<string, any> & Partial<T>;
+type Loose<T extends Object> = Record<string, any> & Partial<T>;
 /**
  * A Loose version of the Config interface. This is intended to let us load a partial config
  * and have type information carry though as we construct an object which is a valid `Config`.
  */
-export declare type UnvalidatedConfig = Loose<Config>;
+export type UnvalidatedConfig = Loose<Config>;
 /**
  * Helper type to strip optional markers from keys in a type, while preserving other type information for the key.
  * This type takes a union of keys, K, in type T to allow for the type T to be gradually updated.
@@ -366,20 +366,20 @@ export declare type UnvalidatedConfig = Loose<Config>;
  * type ReqFieldFoo = RequireFields<Foo, 'bar'>; // { bar: number, baz?: string }
  * ```
  */
-declare type RequireFields<T, K extends keyof T> = T & {
+type RequireFields<T, K extends keyof T> = T & {
     [P in K]-?: T[P];
 };
 /**
  * Fields in {@link Config} to make required for {@link ValidatedConfig}
  */
-declare type StrictConfigFields = 'flags' | 'logger' | 'outputTargets' | 'rootDir' | 'sys' | 'testing';
+type StrictConfigFields = 'flags' | 'logger' | 'outputTargets' | 'rootDir' | 'sys' | 'testing';
 /**
  * A version of {@link Config} that makes certain fields required. This type represents a valid configuration entity.
  * When a configuration is received by the user, it is a bag of unverified data. In order to make stricter guarantees
  * about the data from a type-safety perspective, this type is intended to be used throughout the codebase once
  * validations have occurred at runtime.
  */
-export declare type ValidatedConfig = RequireFields<Config, StrictConfigFields>;
+export type ValidatedConfig = RequireFields<Config, StrictConfigFields>;
 export interface HydratedFlag {
     /**
      * Defaults to `hydrated`.
@@ -512,6 +512,10 @@ export interface RindoDevServerConfig {
 export interface DevServerConfig extends RindoDevServerConfig {
     browserUrl?: string;
     devServerDir?: string;
+    /**
+     * A list of glob patterns like `subdir/*.js`  to exclude from hot-module
+     * reloading updates.
+     */
     excludeHmr?: string[];
     historyApiFallback?: HistoryApiFallback;
     openBrowser?: boolean;
@@ -529,8 +533,8 @@ export interface DevServerEditor {
     supported?: boolean;
     priority?: number;
 }
-export declare type TaskCommand = 'build' | 'docs' | 'generate' | 'g' | 'help' | 'info' | 'prerender' | 'serve' | 'telemetry' | 'test' | 'version';
-export declare type PageReloadStrategy = 'hmr' | 'pageReload' | null;
+export type TaskCommand = 'build' | 'docs' | 'generate' | 'g' | 'help' | 'info' | 'prerender' | 'serve' | 'telemetry' | 'test' | 'version';
+export type PageReloadStrategy = 'hmr' | 'pageReload' | null;
 /**
  * The prerender config is used when prerendering a `www` output target.
  * Within `rindo.config.ts`, set the path to the prerendering
@@ -1052,7 +1056,23 @@ export interface CompilerSystem {
     statSync(p: string): CompilerFsStats;
     tmpDirSync(): string;
     watchDirectory?(p: string, callback: CompilerFileWatcherCallback, recursive?: boolean): CompilerFileWatcher;
-    watchFile?(p: string, callback: CompilerFileWatcherCallback): CompilerFileWatcher;
+    /**
+     * A `watchFile` implementation in order to hook into the rest of the {@link CompilerSystem} implementation that is
+     * used when running Rindo's compiler in "watch mode".
+     *
+     * It is analogous to TypeScript's `watchFile`  implementation.
+     *
+     * Note, this function may be called for full builds of Rindo projects by the TypeScript compiler. It should not
+     * assume that it will only be called in watch mode.
+     *
+     * This function should not perform any file watcher registration itself. Each `path` provided to it when called
+     * should already have been registered as a file to watch.
+     *
+     * @param path the path to the file that is being watched
+     * @param callback a callback to invoke when a file that is being watched has changed in some way
+     * @returns an object with a method for unhooking the file watcher from the system
+     */
+    watchFile?(path: string, callback: CompilerFileWatcherCallback): CompilerFileWatcher;
     /**
      * How many milliseconds to wait after a change before calling watch callbacks.
      */
@@ -1146,6 +1166,7 @@ export interface BuildOnEvents {
     on(eventName: CompilerEventBuildNoChange, cb: () => void): BuildOnEventRemove;
 }
 export interface BuildEmitEvents {
+    emit(eventName: CompilerEventName, path: string): void;
     emit(eventName: CompilerEventFileAdd, path: string): void;
     emit(eventName: CompilerEventFileDelete, path: string): void;
     emit(eventName: CompilerEventFileUpdate, path: string): void;
@@ -1220,7 +1241,7 @@ export interface HmrStyleUpdate {
     styleTag: string;
     styleText: string;
 }
-export declare type BuildOnEventRemove = () => boolean;
+export type BuildOnEventRemove = () => boolean;
 export interface BuildEvents extends BuildOnEvents, BuildEmitEvents {
     unsubscribeAll(): void;
 }
@@ -1228,19 +1249,28 @@ export interface CompilerBuildStart {
     buildId: number;
     timestamp: string;
 }
-export declare type CompilerFileWatcherCallback = (fileName: string, eventKind: CompilerFileWatcherEvent) => void;
-export declare type CompilerFileWatcherEvent = CompilerEventFileAdd | CompilerEventFileDelete | CompilerEventFileUpdate | CompilerEventDirAdd | CompilerEventDirDelete;
-export declare type CompilerEventName = CompilerEventFsChange | CompilerEventFileUpdate | CompilerEventFileAdd | CompilerEventFileDelete | CompilerEventDirAdd | CompilerEventDirDelete | CompilerEventBuildStart | CompilerEventBuildFinish | CompilerEventBuildNoChange | CompilerEventBuildLog;
-export declare type CompilerEventFsChange = 'fsChange';
-export declare type CompilerEventFileUpdate = 'fileUpdate';
-export declare type CompilerEventFileAdd = 'fileAdd';
-export declare type CompilerEventFileDelete = 'fileDelete';
-export declare type CompilerEventDirAdd = 'dirAdd';
-export declare type CompilerEventDirDelete = 'dirDelete';
-export declare type CompilerEventBuildStart = 'buildStart';
-export declare type CompilerEventBuildFinish = 'buildFinish';
-export declare type CompilerEventBuildLog = 'buildLog';
-export declare type CompilerEventBuildNoChange = 'buildNoChange';
+/**
+ * A type describing a function to call when an event is emitted by a file watcher
+ * @param fileName the path of the file tied to event
+ * @param eventKind a variant describing the type of event that was emitter (added, edited, etc.)
+ */
+export type CompilerFileWatcherCallback = (fileName: string, eventKind: CompilerFileWatcherEvent) => void;
+/**
+ * A type describing the different types of events that Rindo expects may happen when a file being watched is altered
+ * in some way
+ */
+export type CompilerFileWatcherEvent = CompilerEventFileAdd | CompilerEventFileDelete | CompilerEventFileUpdate | CompilerEventDirAdd | CompilerEventDirDelete;
+export type CompilerEventName = CompilerEventFsChange | CompilerEventFileUpdate | CompilerEventFileAdd | CompilerEventFileDelete | CompilerEventDirAdd | CompilerEventDirDelete | CompilerEventBuildStart | CompilerEventBuildFinish | CompilerEventBuildNoChange | CompilerEventBuildLog;
+export type CompilerEventFsChange = 'fsChange';
+export type CompilerEventFileUpdate = 'fileUpdate';
+export type CompilerEventFileAdd = 'fileAdd';
+export type CompilerEventFileDelete = 'fileDelete';
+export type CompilerEventDirAdd = 'dirAdd';
+export type CompilerEventDirDelete = 'dirDelete';
+export type CompilerEventBuildStart = 'buildStart';
+export type CompilerEventBuildFinish = 'buildFinish';
+export type CompilerEventBuildLog = 'buildLog';
+export type CompilerEventBuildNoChange = 'buildNoChange';
 export interface CompilerFileWatcher {
     close(): void | Promise<void>;
 }
@@ -1654,7 +1684,7 @@ export interface EmulateViewport {
  * in this array without good reason!
  */
 export declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
-export declare type LogLevel = typeof LOG_LEVELS[number];
+export type LogLevel = (typeof LOG_LEVELS)[number];
 /**
  * Common logger to be used by the compiler, dev-server and CLI. The CLI will use a
  * NodeJS based console logging and colors, and the web will use browser based
@@ -1850,6 +1880,12 @@ export interface OutputTargetBaseNext {
 export interface OutputTargetDistCustomElements extends OutputTargetBaseNext {
     type: 'dist-custom-elements';
     empty?: boolean;
+    /**
+     * Triggers the following behaviors when enabled:
+     * 1. All `@rindo/core/*` module references are treated as external during bundling.
+     * 2. File names are not hashed.
+     * 3. File minification will follow the behavior defined at the root of the Rindo config.
+     */
     externalRuntime?: boolean;
     copy?: CopyTask[];
     inlineDynamicImports?: boolean;
@@ -1884,7 +1920,7 @@ export interface OutputTargetBase {
      */
     type: string;
 }
-export declare type OutputTargetBuild = OutputTargetDistCollection | OutputTargetDistLazy;
+export type OutputTargetBuild = OutputTargetDistCollection | OutputTargetDistLazy;
 export interface OutputTargetAngular extends OutputTargetBase {
     type: 'angular';
     componentCorePackage: string;
@@ -1972,7 +2008,7 @@ export interface OutputTargetWww extends OutputTargetBase {
     serviceWorker?: ServiceWorkerConfig | null | false;
     appDir?: string;
 }
-export declare type OutputTarget = OutputTargetAngular | OutputTargetCopy | OutputTargetCustom | OutputTargetDist | OutputTargetDistCollection | OutputTargetDistCustomElements | OutputTargetDistCustomElementsBundle | OutputTargetDistLazy | OutputTargetDistGlobalStyles | OutputTargetDistLazyLoader | OutputTargetDocsJson | OutputTargetDocsCustom | OutputTargetDocsReadme | OutputTargetDocsVscode | OutputTargetWww | OutputTargetHydrate | OutputTargetStats | OutputTargetDistTypes;
+export type OutputTarget = OutputTargetAngular | OutputTargetCopy | OutputTargetCustom | OutputTargetDist | OutputTargetDistCollection | OutputTargetDistCustomElements | OutputTargetDistCustomElementsBundle | OutputTargetDistLazy | OutputTargetDistGlobalStyles | OutputTargetDistLazyLoader | OutputTargetDocsJson | OutputTargetDocsCustom | OutputTargetDocsReadme | OutputTargetDocsVscode | OutputTargetWww | OutputTargetHydrate | OutputTargetStats | OutputTargetDistTypes;
 export interface ServiceWorkerConfig {
     unregister?: boolean;
     swDest?: string;
@@ -2111,7 +2147,7 @@ export interface OptimizeCssInput {
  * Instead, this basically just serves as a label type to track
  * that arguments are being passed consistently.
  */
-export declare type AutoprefixerOptions = Object;
+export type AutoprefixerOptions = Object;
 /**
  * Output from CSS optimization functions, wrapping up optimized
  * CSS and any diagnostics produced during optimization.
@@ -2281,7 +2317,7 @@ export interface TranspileOptions {
      */
     sys?: CompilerSystem;
 }
-export declare type CompileTarget = 'latest' | 'esnext' | 'es2020' | 'es2019' | 'es2018' | 'es2017' | 'es2015' | 'es5' | string | undefined;
+export type CompileTarget = 'latest' | 'esnext' | 'es2020' | 'es2019' | 'es2018' | 'es2017' | 'es2015' | 'es5' | string | undefined;
 export interface TranspileResults {
     code: string;
     data?: any[];

package/internal/rindo-public-docs.d.ts

@@ -18,6 +18,10 @@ export interface JsonDocsComponent {
     readme: string;
     docs: string;
     docsTags: JsonDocsTag[];
+    /**
+     * The text from the class-level JSDoc for a Rindo component, if present.
+     */
+    overview?: string;
     usage: JsonDocsUsage;
     props: JsonDocsProp[];
     methods: JsonDocsMethod[];
@@ -42,6 +46,26 @@ export interface JsonDocsValue {
     value?: string;
     type: string;
 }
+/**
+ * A mapping of file names to their contents.
+ *
+ * This type is meant to be used when reading one or more usage markdown files associated with a component. For the
+ * given directory structure:
+ * ```
+ * src/components/my-component
+ * ├── my-component.tsx
+ * └── usage
+ *     ├── bar.md
+ *     └── foo.md
+ * ```
+ * an instance of this type would include the name of the markdown file, mapped to its contents:
+ * ```ts
+ * {
+ *   'bar': STRING_CONTENTS_OF_BAR.MD
+ *   'foo': STRING_CONTENTS_OF_FOO.MD
+ * }
+ * ```
+ */
 export interface JsonDocsUsage {
     [key: string]: string;
 }

package/internal/rindo-public-runtime.d.ts

@@ -133,7 +133,7 @@ export interface ListenOptions {
      */
     passive?: boolean;
 }
-export declare type ListenTargetOptions = 'body' | 'document' | 'window';
+export type ListenTargetOptions = 'body' | 'document' | 'window';
 export interface StateDecorator {
     (): PropertyDecorator;
 }
@@ -214,14 +214,16 @@ export declare const State: StateDecorator;
  * https://rindojs.web.app/docs/reactive-data#watch-decorator
  */
 export declare const Watch: WatchDecorator;
-export declare type ResolutionHandler = (elm: HTMLElement) => string | undefined | null;
-export declare type ErrorHandler = (err: any, element?: HTMLElement) => void;
+export type ResolutionHandler = (elm: HTMLElement) => string | undefined | null;
+export type ErrorHandler = (err: any, element?: HTMLElement) => void;
 /**
  * `setMode()` is used for libraries which provide multiple "modes" for styles.
  */
 export declare const setMode: (handler: ResolutionHandler) => void;
 /**
- * getMode
+ * `getMode()` is used for libraries which provide multiple "modes" for styles.
+ * @param ref a reference to the node to get styles for
+ * @returns the current mode or undefined, if not found
  */
 export declare function getMode<T = string | undefined>(ref: any): T;
 export declare function setPlatformHelpers(helpers: {
@@ -234,6 +236,9 @@ export declare function setPlatformHelpers(helpers: {
 /**
  * Get the base path to where the assets can be found. Use `setAssetPath(path)`
  * if the path needs to be customized.
+ * @param path the path to use in calculating the asset path. this value will be
+ * used in conjunction with the base asset path
+ * @returns the base path
  */
 export declare function getAssetPath(path: string): string;
 /**
@@ -246,22 +251,38 @@ export declare function getAssetPath(path: string): string;
  * `setAssetPath(document.currentScript.src)`, or using a bundler's replace plugin to
  * dynamically set the path at build time, such as `setAssetPath(process.env.ASSET_PATH)`.
  * But do note that this configuration depends on how your script is bundled, or lack of
- * bunding, and where your assets can be loaded from. Additionally custom bundling
+ * bundling, and where your assets can be loaded from. Additionally custom bundling
  * will have to ensure the static assets are copied to its build directory.
+ * @param path the asset path to set
+ * @returns the set path
  */
 export declare function setAssetPath(path: string): string;
 /**
- * getElement
+ * Used to specify a nonce value that corresponds with an application's
+ * [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP).
+ * When set, the nonce will be added to all dynamically created script and style tags at runtime.
+ * Alternatively, the nonce value can be set on a `meta` tag in the DOM head
+ * (<meta name="csp-nonce" content="{ nonce value here }" />) and will result in the same behavior.
+ * @param nonce The value to be used for the nonce attribute.
+ */
+export declare function setNonce(nonce: string): void;
+/**
+ * Retrieve a Rindo element for a given reference
+ * @param ref the ref to get the Rindo element for
+ * @returns a reference to the element
  */
 export declare function getElement(ref: any): HTMLRindoElement;
 /**
  * Schedules a new render of the given instance or element even if no state changed.
  *
- * Notice `forceUpdate()` is not syncronous and might perform the DOM render in the next frame.
+ * Notice `forceUpdate()` is not synchronous and might perform the DOM render in the next frame.
+ *
+ * @param ref the node/element to force the re-render of
  */
 export declare function forceUpdate(ref: any): void;
 /**
  * getRenderingRef
+ * @returns the rendering ref
  */
 export declare function getRenderingRef(): any;
 export interface HTMLRindoElement extends HTMLElement {
@@ -272,6 +293,8 @@ export interface HTMLRindoElement extends HTMLElement {
  * in the best moment to perform DOM mutation without causing layout thrashing.
  *
  * For further information: https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing
+ *
+ * @param task the DOM-write to schedule
  */
 export declare function writeTask(task: RafCallback): void;
 /**
@@ -279,6 +302,8 @@ export declare function writeTask(task: RafCallback): void;
  * in the best moment to perform DOM reads without causing layout thrashing.
  *
  * For further information: https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing
+ *
+ * @param task the DOM-read to schedule
  */
 export declare function readTask(task: RafCallback): void;
 /**
@@ -417,13 +442,57 @@ interface HostAttributes {
     ref?: (el: HTMLElement | null) => void;
     [prop: string]: any;
 }
+/**
+ * Utilities for working with functional Rindo components. An object
+ * conforming to this interface is passed by the Rindo runtime as the third
+ * argument to a functional component, allowing component authors to work with
+ * features like children.
+ *
+ * The children of a functional component will be passed as the second
+ * argument, so a functional component which uses these utils to transform its
+ * children might look like the following:
+ *
+ * ```ts
+ * export const AddClass: FunctionalComponent = (_, children, utils) => (
+ *  utils.map(children, child => ({
+ *    ...child,
+ *    vattrs: {
+ *      ...child.vattrs,
+ *      class: `${child.vattrs.class} add-class`
+ *    }
+ *  }))
+ * );
+ * ```
+ *
+ * For more see the Rindo documentation, here:
+ * https://rindojs.web.app/docs/functional-components
+ */
 export interface FunctionalUtilities {
+    /**
+     * Utility for reading the children of a functional component at runtime.
+     * Since the Rindo runtime uses a different interface for children it is
+     * not recommendeded to read the children directly, and is preferable to use
+     * this utility to, for instance, perform a side effect for each child.
+     */
     forEach: (children: VNode[], cb: (vnode: ChildNode, index: number, array: ChildNode[]) => void) => void;
+    /**
+     * Utility for transforming the children of a functional component. Given an
+     * array of children and a callback this will return a list of the results of
+     * passing each child to the supplied callback.
+     */
     map: (children: VNode[], cb: (vnode: ChildNode, index: number, array: ChildNode[]) => ChildNode) => VNode[];
 }
 export interface FunctionalComponent<T = {}> {
     (props: T, children: VNode[], utils: FunctionalUtilities): VNode | VNode[];
 }
+/**
+ * A Child VDOM node
+ *
+ * This has most of the same properties as {@link VNode} but friendlier names
+ * (i.e. `vtag` instead of `$tag$`, `vchildren` instead of `$children$`) in
+ * order to provide a friendlier public interface for users of the
+ * {@link FunctionalUtilities}).
+ */
 export interface ChildNode {
     vtag?: string | number | Function;
     vkey?: string | number;
@@ -470,6 +539,9 @@ export declare function h(sel: any, children: Array<VNode | undefined | null>):
 export declare function h(sel: any, data: VNodeData | null, text: string): VNode;
 export declare function h(sel: any, data: VNodeData | null, children: Array<VNode | undefined | null>): VNode;
 export declare function h(sel: any, data: VNodeData | null, children: VNode): VNode;
+/**
+ * A virtual DOM node
+ */
 export interface VNode {
     $flags$: number;
     $tag$: string | number | Function;