@xh/hoist 57.0.0 → 57.0.2

package/build/types/utils/react/Hooks.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Hook to run a function once after component has been mounted.
+ */
+export declare function useOnMount(fn: () => void): void;
+/**
+ * Hook to run a function once after component has been unmounted.
+ */
+export declare function useOnUnmount(fn: () => void): void;
+/**
+ * Hook to run a function when a DOM element is resized.
+ *
+ * @see observeResize() for more details.
+ *
+ * @param fn - receives a DOMRect containing the dimensions of the DOM element.
+ * @param opts - extra options, currently supporting a `debounce` specified in ms.
+ * @returns callback ref to be placed on target component
+ */
+export declare function useOnResize(fn: (rect: DOMRect) => any, opts?: {
+    debounce?: number;
+}): (node: any) => void;
+/**
+ * Hook to run a function when a DOM element becomes visible / invisible.
+ *
+ * @see observeVisibleChange() for more details.
+ *
+ * @param fn - receives a boolean signifying if visible.
+ * @returns callback ref to be placed on target component
+ */
+export declare function useOnVisibleChange(fn: (visible: boolean) => any): (node: any) => void;
+/**
+ * Hook to run a function when a DOM element scrolls.
+ *
+ * @param fn - receives the scroll event.
+ * @returns callback ref to be placed on target component
+ */
+export declare function useOnScroll(fn: (ev: Event) => any): (node: any) => void;
+/**
+ * Hook to return a cached version of a value - similar useCallback() and useMemo().
+ * Useful for providing stable object references across renders.
+ *
+ * @param value - value (typically an object) to be cached and potentially returned to this and
+ *      subsequent calls.
+ * @param equalsFn - A function taking the previously cached value and the currently presented
+ *      value. If evaluates to true, the cached value will be returned rather than the presented
+ *      value. If null, any cached value will always be returned.
+ */
+export declare function useCached<T>(value: T, equalsFn: (prev: T, curr: T) => boolean): T;

package/build/types/utils/react/LayoutPropUtils.d.ts

@@ -0,0 +1,42 @@
+import { HoistProps, LayoutProps, PlainObject } from '@xh/hoist/core';
+/**
+ * These utils support accepting the CSS styles enumerated below as top-level props of a Component,
+ * and are typically accessed via the `@LayoutSupport` mixin (for class-based components) or the
+ * `useLayoutProps()` Hook (for function components).
+ *
+ * Any supported properties will be extracted from the overall props bundle and returned from
+ * `getLayoutProps()`. The contrasting `getNonLayoutProps()` will output all other props _not_
+ * included in this list, useful when e.g. relaying unrelated props to a child component without
+ * also sending down unwanted/unexpected layout-related keys.
+ *
+ * The following properties are supported:
+ *     margin, marginTop, marginRight, marginBottom, marginLeft,
+ *     padding, paddingTop, paddingRight, paddingBottom, paddingLeft,
+ *     height, minHeight, maxHeight, width, minWidth, maxWidth,
+ *     flex, flexBasis, flexDirection, flexGrow, flexShrink, flexWrap,
+ *     alignItems, alignSelf, alignContent, justifyContent,
+ *     overflow, overflowX, overflowY, textOverflow,
+ *     top, left, position, display
+ *
+ * NOTE - this system relies on Components respecting and responding to these properties.
+ * Component authors must ensure they do, typically by spreading the extracted props onto a
+ * child component that also implements LayoutSupport. `Box` is typically the Hoist layout Component
+ * that is ultimately rendered and will actually implement this system by outputting a div with
+ * appropriate styles set.
+ */
+/**
+ * Return all layout related props found in props.
+ *
+ * This method implements some minor translations, to allow a more user friendly specification than
+ * that afforded by the underlying flexbox styles. In particular, it accepts flex and sizing props
+ * as raw numbers rather than strings.
+ */
+export declare function getLayoutProps(props: PlainObject): LayoutProps;
+/**
+ * Return all non-layout related props found in props.
+ */
+export declare function getNonLayoutProps<T extends HoistProps>(props: T): T;
+/**
+ * Split a set of props into layout and non-layout props.
+ */
+export declare function splitLayoutProps<T extends HoistProps>(props: T): [LayoutProps, T];

package/build/types/utils/react/ObservableRef.d.ts

@@ -0,0 +1,13 @@
+import { RefCallback, RefObject } from 'react';
+/**
+ * Create an observable ref.
+ *
+ * The object returned by this function supports the
+ * API returned by React.createRef(), but the `current`
+ * property is a MobX observable value.
+ *
+ * This object *also* supports the legacy callback Ref API
+ *
+ * https://reactjs.org/docs/refs-and-the-dom.html
+ */
+export declare function createObservableRef<T>(): RefObject<T> & RefCallback<T>;

package/build/types/utils/react/ReactUtils.d.ts

@@ -0,0 +1,19 @@
+import { Content } from '@xh/hoist/core';
+import { ReactElement } from 'react';
+/**
+ * Return the display name for either a class-based or functional Component.
+ */
+export declare function getReactElementName(obj: any): string;
+/**
+ * Create a React element from either a HoistComponent or a function returning an element.
+ *
+ * Used by the TabContainer, DashContainer, DockView, and Navigator APIs to process the 'content'
+ * configs provided to them for their tabs and views.
+ *
+ * @param content - ReactElement, HoistComponent or function returning a ReactElement.
+ *      If a function, it may be an ElemFactory or any function that returns a ReactElement. In
+ *      either case, the function will be called with no arguments.
+ * @param addProps -- optional additional props to apply to the element.  These will override
+ *      any existing props placed on the element, and should be used with care.
+ */
+export declare function elementFromContent(content: Content, addProps?: object): ReactElement;

package/build/types/utils/react/index.d.ts

@@ -0,0 +1,5 @@
+export * from './ClassName';
+export * from './ReactUtils';
+export * from './LayoutPropUtils';
+export * from './ObservableRef';
+export * from './Hooks';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "57.0.0",
+  "version": "57.0.2",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",
@@ -87,7 +87,7 @@
     "@ag-grid-community/client-side-row-model": "30.x",
     "@ag-grid-community/core": "30.x",
     "@ag-grid-community/react": "30.x",
-    "@xh/hoist-dev-utils": "^6.3.0",
+    "@xh/hoist-dev-utils": "^6.2.0",
     "eslint-config-prettier": "8.x",
     "eslint-plugin-tsdoc": "^0.2.17",
     "husky": "^8.0.3",

package/static/preflight.js

@@ -21,18 +21,20 @@ window._xhLoadTimestamp = Date.now();
     }
 })(window);
 
-// Catch errors that occur before our in-app exception handling takes over.
-window.onerror = function(errorMsg, url, line, col, error) {
-    document.body.innerHTML = (
-        '<div style="margin: 60px auto; font-family: sans-serif; width: 450px; max-width: 80%; text-align: center; padding: 20px; border: 1px solid #ccc;">' +
-        '<strong>This application can not be loaded in your current browser</strong><br/><br/>' +
+// Use flag below to catch and stop on errors that occur before in-app exception handling active.
+if (window.location.search.toLowerCase().indexOf('catchpreflighterror=true') != -1) {
+    window.onerror = function (errorMsg, url, line, col, error) {
+        document.body.innerHTML = (
+            '<div style="margin: 60px auto; font-family: sans-serif; width: 450px; max-width: 80%; text-align: center; padding: 20px; border: 1px solid #ccc;">' +
+            '<strong>This application can not be loaded in your current browser</strong><br/><br/>' +
             '<div style="text-align: left">' +
-                    errorMsg + '<br/>' +
-                    '<div style="padding-left: 3em; overflow-wrap: anywhere;">' +
-                        'at ' + url + ':' + line + ':' + col +
-                    '</div>' + '<br/><br/>' +
-                    window.navigator.userAgent +
+            errorMsg + '<br/>' +
+            '<div style="padding-left: 3em; overflow-wrap: anywhere;">' +
+            'at ' + url + ':' + line + ':' + col +
+            '</div>' + '<br/><br/>' +
+            window.navigator.userAgent +
             '</div>' +
-        '</div>'
-    );
-};
+            '</div>'
+        );
+    };
+}

package/tsconfig.json

@@ -1,20 +1,27 @@
 {
   "compilerOptions": {
-    "experimentalDecorators": true,
+    "composite": true,
+    "emitDeclarationOnly": true,
+    "declarationDir": "./build/types",
+
     "target": "ES2022",
     "module": "ES2022",
+    "lib": ["dom", "es2022"],
+
+    "jsx": "react",
     "moduleResolution": "Node",
     "skipLibCheck": true,
+
     "allowSyntheticDefaultImports": true,
+    "experimentalDecorators": true,
+    "noImplicitOverride": true,
     "resolveJsonModule": true,
-    "noEmit": true,
-    "jsx": "react",
     "useDefineForClassFields": true,
-    "noImplicitOverride": true,
+
     "paths": {
       "@xh/hoist/*": ["./*"]
-    },
-    "lib": ["dom", "es2022"]
+    }
   },
-  "exclude": ["node_modules"]
+  "include": ["./**/*", "package.json"],
+  "exclude": ["node_modules", "build"]
 }