Interactivity API: update TS/JSDocs after migrating to the new store() API

packages/interactivity/src/hooks.tsx

@@ -1,44 +1,93 @@
-// @ts-nocheck
-
 /**
  * External dependencies
  */
 import { h, options, createContext, cloneElement } from 'preact';
 import { useRef, useCallback, useContext } from 'preact/hooks';
 import { deepSignal } from 'deepsignal';
+import type { VNode, Context, RefObject } from 'preact';
+
 /**
  * Internal dependencies
  */
 import { stores } from './store';
+interface DirectiveEntry {
+	value: string | Object;
+	namespace: string;
+	suffix: string;
+}
 
-/** @typedef {import('preact').VNode} VNode */
-/** @typedef {typeof context} Context */
-/** @typedef {ReturnType<typeof getEvaluate>} Evaluate */
+type DirectiveEntries = Record< string, DirectiveEntry[] >;
 
-/**
- * @typedef {Object} DirectiveCallbackParams Callback parameters.
- * @property {Object}   directives Object map with the defined directives of the element being evaluated.
- * @property {Object}   props      Props present in the current element.
- * @property {VNode}    element    Virtual node representing the original element.
- * @property {Context}  context    The inherited context.
- * @property {Evaluate} evaluate   Function that resolves a given path to a value either in the store or the context.
- */
+interface DirectiveArgs {
+	/**
+	 * Object map with the defined directives of the element being evaluated.
+	 */
+	directives: DirectiveEntries;
+	/**
+	 * Props present in the current element.
+	 */
+	props: Object;
+	/**
+	 * Virtual node representing the element.
+	 */
+	element: VNode;
+	/**
+	 * The inherited context.
+	 */
+	context: Context< any >;
+	/**
+	 * Function that resolves a given path to a value either in the store or the
+	 * context.
+	 */
+	evaluate: Evaluate;
+}
 
-/**
- * @callback DirectiveCallback Callback that runs the directive logic.
- * @param {DirectiveCallbackParams} params Callback parameters.
- */
+interface DirectiveCallback {
+	( args: DirectiveArgs ): VNode | void;
+}
 
-/**
- * @typedef DirectiveOptions Options object.
- * @property {number} [priority=10] Value that specifies the priority to
- *                                  evaluate directives of this type. Lower
- *                                  numbers correspond with earlier execution.
- *                                  Default is `10`.
- */
+interface DirectiveOptions {
+	/**
+	 * Value that specifies the priority to evaluate directives of this type.
+	 * Lower numbers correspond with earlier execution.
+	 *
+	 * @default 10
+	 */
+	priority?: number;
+}
+
+interface Scope {
+	evaluate: Evaluate;
+	context: Context< any >;
+	ref: RefObject< HTMLElement >;
+	state: any;
+	props: any;
+}
+
+interface Evaluate {
+	( entry: DirectiveEntry, ...args: any[] ): any;
+}
+
+interface GetEvaluate {
+	( args: { scope: Scope } ): Evaluate;
+}
+
+type PriorityLevel = string[];
+
+interface GetPriorityLevels {
+	( directives: DirectiveEntries ): PriorityLevel[];
+}
+
+interface DirectivesProps {
+	directives: DirectiveEntries;
+	priorityLevels: PriorityLevel[];
+	element: VNode;
+	originalProps: any;
+	previousScope?: Scope;
+}
 
 // Main context.
-const context = createContext( {} );
+const context = createContext< any >( {} );
 
 // Wrap the element props to prevent modifications.
 const immutableMap = new WeakMap();
@@ -65,12 +114,28 @@ const deepImmutable = < T extends Object = {} >( target: T ): T => {
 
 // Store stacks for the current scope and the default namespaces and export APIs
 // to interact with them.
-const scopeStack: any[] = [];
+const scopeStack: Scope[] = [];
 const namespaceStack: string[] = [];
 
+/**
+ * Retrieves the context inherited by the element evaluating a function from the
+ * store. The returned value depends on the element and the namespace where the
+ * function calling `getContext()` exists.
+ *
+ * @param namespace Store namespace. By default, the namespace where the calling
+ *                  function exists is used.
+ * @return The context content.
+ */
 export const getContext = < T extends object >( namespace?: string ): T =>
 	getScope()?.context[ namespace || namespaceStack.slice( -1 )[ 0 ] ];
 
+/**
+ * Retrieves a representation of the element where a function from the store
+ * is being evalutated. Such representation is read-only, and contains a
+ * reference to the DOM element, its props and a local reactive state.
+ *
+ * @return Element representation.
+ */
 export const getElement = () => {
 	if ( ! getScope() ) {
 		throw Error(
@@ -87,7 +152,7 @@ export const getElement = () => {
 
 export const getScope = () => scopeStack.slice( -1 )[ 0 ];
 
-export const setScope = ( scope ) => {
+export const setScope = ( scope: Scope ) => {
 	scopeStack.push( scope );
 };
 export const resetScope = () => {
@@ -102,8 +167,8 @@ export const resetNamespace = () => {
 };
 
 // WordPress Directives.
-const directiveCallbacks = {};
-const directivePriorities = {};
+const directiveCallbacks: Record< string, DirectiveCallback > = {};
+const directivePriorities: Record< string, number > = {};
 
 /**
  * Register a new directive type in the Interactivity API runtime.
@@ -112,34 +177,37 @@ const directivePriorities = {};
  * ```js
  * directive(
  *   'alert', // Name without the `data-wp-` prefix.
- *   ( { directives: { alert }, element, evaluate }) => {
- *     element.props.onclick = () => {
- *       alert( evaluate( alert.default ) );
- *     }
+ *   ( { directives: { alert }, element, evaluate } ) => {
+ *     const defaultEntry = alert.find( entry => entry.suffix === 'default' );
+ *     element.props.onclick = () => { alert( evaluate( defaultEntry ) ); }
  *   }
  * )
  * ```
  *
  * The previous code registers a custom directive type for displaying an alert
  * message whenever an element using it is clicked. The message text is obtained
- * from the store using `evaluate`.
+ * from the store under the inherited namespace, using `evaluate`.
  *
  * When the HTML is processed by the Interactivity API, any element containing
  * the `data-wp-alert` directive will have the `onclick` event handler, e.g.,
  *
  * ```html
- * <button data-wp-alert="state.messages.alert">Click me!</button>
+ * <div data-wp-interactive='{ "namespace": "messages" }'>
+ *   <button data-wp-alert="state.alert">Click me!</button>
+ * </div>
  * ```
- * Note that, in the previous example, you access `alert.default` in order to
- * retrieve the `state.messages.alert` value passed to the directive. You can
- * also define custom names by appending `--` to the directive attribute,
- * followed by a suffix, like in the following HTML snippet:
+ * Note that, in the previous example, the directive callback gets the path
+ * value (`state.alert`) from the directive entry with suffix `default`. A
+ * custom suffix can also be specified by appending `--` to the directive
+ * attribute, followed by the suffix, like in the following HTML snippet:
  *
  * ```html
- * <button
- *   data-wp-color--text="state.theme.text"
- *   data-wp-color--background="state.theme.background"
- * >Click me!</button>
+ * <div data-wp-interactive='{ "namespace": "myblock" }'>
+ *   <button
+ *     data-wp-color--text="state.text"
+ *     data-wp-color--background="state.background"
+ *   >Click me!</button>
+ * </div>
  * ```
  *
  * This could be an hypothetical implementation of the custom directive used in
@@ -149,28 +217,36 @@ const directivePriorities = {};
  * ```js
  * directive(
  *   'color', // Name without prefix and suffix.
- *   ( { directives: { color }, ref, evaluate }) => {
- *     if ( color.text ) {
- * 	     ref.style.setProperty(
- *         'color',
- *         evaluate( color.text )
- *       );
- *     }
- *     if ( color.background ) {
- *       ref.style.setProperty(
- *         'background-color',
- *         evaluate( color.background )
- *       );
- *     }
+ *   ( { directives: { color }, ref, evaluate } ) =>
+ *     colors.forEach( ( color ) => {
+ *       if ( color.suffix = 'text' ) {
+ *         ref.style.setProperty(
+ *           'color',
+ *           evaluate( color.text )
+ *         );
+ *       }
+ *       if ( color.suffix = 'background' ) {
+ *         ref.style.setProperty(
+ *           'background-color',
+ *           evaluate( color.background )
+ *         );
+ *       }
+ *     } );
  *   }
  * )
  * ```
  *
- * @param {string}            name     Directive name, without the `data-wp-` prefix.
- * @param {DirectiveCallback} callback Function that runs the directive logic.
- * @param {DirectiveOptions=} options  Options object.
+ * @param name             Directive name, without the `data-wp-` prefix.
+ * @param callback         Function that runs the directive logic.
+ * @param options          Options object.
+ * @param options.priority Option to control the directive execution order. The
+ *                         lesser, the highest priority. Default is `10`.
  */
-export const directive = ( name, callback, { priority = 10 } = {} ) => {
+export const directive = (
+	name: string,
+	callback: DirectiveCallback,
+	{ priority = 10 }: DirectiveOptions = {}
+) => {
 	directiveCallbacks[ name ] = callback;
 	directivePriorities[ name ] = priority;
 };
@@ -186,10 +262,13 @@ const resolve = ( path, namespace ) => {
 };
 
 // Generate the evaluate function.
-const getEvaluate =
-	( { scope } = {} ) =>
+const getEvaluate: GetEvaluate =
+	( { scope } ) =>
 	( entry, ...args ) => {
 		let { value: path, namespace } = entry;
+		if ( typeof path !== 'string' ) {
+			throw new Error( 'The `value` prop should be a string path' );
+		}
 		// If path starts with !, remove it and save a flag.
 		const hasNegationOperator =
 			path[ 0 ] === '!' && !! ( path = path.slice( 1 ) );
@@ -202,8 +281,10 @@ const getEvaluate =
 
 // Separate directives by priority. The resulting array contains objects
 // of directives grouped by same priority, and sorted in ascending order.
-const getPriorityLevels = ( directives ) => {
-	const byPriority = Object.keys( directives ).reduce( ( obj, name ) => {
+const getPriorityLevels: GetPriorityLevels = ( directives ) => {
+	const byPriority = Object.keys( directives ).reduce<
+		Record< number, string[] >
+	>( ( obj, name ) => {
 		if ( directiveCallbacks[ name ] ) {
 			const priority = directivePriorities[ name ];
 			( obj[ priority ] = obj[ priority ] || [] ).push( name );
@@ -212,7 +293,7 @@ const getPriorityLevels = ( directives ) => {
 	}, {} );
 
 	return Object.entries( byPriority )
-		.sort( ( [ p1 ], [ p2 ] ) => p1 - p2 )
+		.sort( ( [ p1 ], [ p2 ] ) => parseInt( p1 ) - parseInt( p2 ) )
 		.map( ( [ , arr ] ) => arr );
 };
 
@@ -222,17 +303,17 @@ const Directives = ( {
 	priorityLevels: [ currentPriorityLevel, ...nextPriorityLevels ],
 	element,
 	originalProps,
-	previousScope = {},
-} ) => {
+	previousScope,
+}: DirectivesProps ) => {
 	// Initialize the scope of this element. These scopes are different per each
 	// level because each level has a different context, but they share the same
 	// element ref, state and props.
-	const scope = useRef( {} ).current;
+	const scope = useRef< Scope >( {} as Scope ).current;
 	scope.evaluate = useCallback( getEvaluate( { scope } ), [] );
 	scope.context = useContext( context );
 	/* eslint-disable react-hooks/rules-of-hooks */
-	scope.ref = previousScope.ref || useRef( null );
-	scope.state = previousScope.state || useRef( deepSignal( {} ) ).current;
+	scope.ref = previousScope?.ref || useRef( null );
+	scope.state = previousScope?.state || useRef( deepSignal( {} ) ).current;
 	/* eslint-enable react-hooks/rules-of-hooks */
 
 	// Create a fresh copy of the vnode element and add the props to the scope.
@@ -276,7 +357,7 @@ const Directives = ( {
 
 // Preact Options Hook called each time a vnode is created.
 const old = options.vnode;
-options.vnode = ( vnode ) => {
+options.vnode = ( vnode: VNode< any > ) => {
 	if ( vnode.props.__directives ) {
 		const props = vnode.props;
 		const directives = props.__directives;
@@ -292,7 +373,7 @@ options.vnode = ( vnode ) => {
 				priorityLevels,
 				originalProps: props,
 				type: vnode.type,
-				element: h( vnode.type, props ),
+				element: h( vnode.type as any, props ),
 				top: true,
 			};
 			vnode.type = Directives;