@handsontable/react-wrapper 0.0.0-next-7cc7ef7-20241028

package/commonjs/src/helpers.d.ts

@@ -0,0 +1,105 @@
+import React, { ComponentType, CSSProperties, DependencyList, EffectCallback, ReactNode, ReactPortal } from 'react';
+import { HotTableProps } from './types';
+/**
+ * Warning message for the `autoRowSize`/`autoColumnSize` compatibility check.
+ */
+export declare const AUTOSIZE_WARNING: string;
+/**
+ * Warning message for the `hot-renderer` obsolete renderer passing method.
+ */
+export declare const OBSOLETE_HOTRENDERER_WARNING: string;
+/**
+ * Warning message for the `hot-editor` obsolete editor passing method.
+ */
+export declare const OBSOLETE_HOTEDITOR_WARNING: string;
+/**
+ * Warning message for the unexpected children of HotTable component.
+ */
+export declare const UNEXPECTED_HOTTABLE_CHILDREN_WARNING: string;
+/**
+ * Warning message for the unexpected children of HotColumn component.
+ */
+export declare const UNEXPECTED_HOTCOLUMN_CHILDREN_WARNING: string;
+/**
+ * Message for the warning thrown if the Handsontable instance has been destroyed.
+ */
+export declare const HOT_DESTROYED_WARNING: string;
+/**
+ * Default classname given to the wrapper container.
+ */
+export declare const DEFAULT_CLASSNAME = "hot-wrapper-editor-container";
+/**
+ * Logs warn to the console if the `console` object is exposed.
+ *
+ * @param {...*} args Values which will be logged.
+ */
+export declare function warn(...args: any[]): void;
+/**
+ * Detect if `hot-renderer` or `hot-editor` is defined, and if so, throw an incompatibility warning.
+ *
+ * @returns {boolean} 'true' if the warning was issued
+ */
+export declare function displayObsoleteRenderersEditorsWarning(children: ReactNode): boolean;
+/**
+ * Detect if children of specified type are defined, and if so, throw an incompatibility warning.
+ *
+ * @param {ReactNode} children Component children nodes
+ * @param {ComponentType} Component Component type to check
+ * @returns {boolean} 'true' if the warning was issued
+ */
+export declare function displayChildrenOfTypeWarning(children: ReactNode, Component: ComponentType): boolean;
+/**
+ * Detect if children is defined, and if so, throw an incompatibility warning.
+ *
+ * @param {ReactNode} children Component children nodes
+ * @returns {boolean} 'true' if the warning was issued
+ */
+export declare function displayAnyChildrenWarning(children: ReactNode): boolean;
+/**
+ * Create an editor portal.
+ *
+ * @param {Document} doc Document to be used.
+ * @param {ComponentType} Editor Editor component or render function.
+ * @returns {ReactPortal} The portal for the editor.
+ */
+export declare function createEditorPortal(doc: Document | null, Editor: HotTableProps['editor'] | undefined): ReactPortal | null;
+/**
+ * Render a cell component to an external DOM node.
+ *
+ * @param {React.ReactElement} rElement React element to be used as a base for the component.
+ * @param {Document} [ownerDocument] The owner document to set the portal up into.
+ * @param {String} portalKey The key to be used for the portal.
+ * @param {HTMLElement} [cachedContainer] The cached container to be used for the portal.
+ * @returns {{portal: ReactPortal, portalContainer: HTMLElement}} An object containing the portal and its container.
+ */
+export declare function createPortal(rElement: React.ReactElement, ownerDocument: Document | null | undefined, portalKey: string, cachedContainer?: HTMLElement): {
+    portal: ReactPortal;
+    portalContainer: HTMLElement;
+};
+/**
+ * Get an object containing the `id`, `className` and `style` keys, representing the corresponding props passed to the
+ * component.
+ *
+ * @param {HotTableProps} props Object containing the React element props.
+ * @param {Boolean} randomizeId If set to `true`, the function will randomize the `id` property when no `id` was present in the `prop` object.
+ * @returns An object containing the `id`, `className` and `style` keys, representing the corresponding props passed to the
+ * component.
+ */
+export declare function getContainerAttributesProps(props: HotTableProps, randomizeId?: boolean): {
+    id?: string;
+    className: string;
+    style: CSSProperties;
+};
+/**
+ * Checks if the environment that the code runs in is a browser.
+ *
+ * @returns {boolean}
+ */
+export declare function isCSR(): boolean;
+/**
+ * A variant of useEffect hook that does not trigger on initial mount, only updates
+ *
+ * @param effect Effect function
+ * @param deps Effect dependencies
+ */
+export declare function useUpdateEffect(effect: EffectCallback, deps?: DependencyList): void;

package/commonjs/src/hotColumn.d.ts

@@ -0,0 +1,5 @@
+import React, { FC } from 'react';
+import { HotColumnProps } from './types';
+declare const isHotColumn: (childNode: any) => childNode is React.ReactElement<any, string | ((props: any, deprecatedLegacyContext?: any) => React.ReactElement<any, any> | null) | (new (props: any, deprecatedLegacyContext?: any) => React.Component<any, any, any>)>;
+declare const HotColumn: FC<HotColumnProps>;
+export { HotColumn, isHotColumn };

package/commonjs/src/hotColumnContext.d.ts

@@ -0,0 +1,16 @@
+import { FC, PropsWithChildren } from 'react';
+export interface HotColumnContextImpl {
+    /**
+     * Column index within a HotTable.
+     */
+    readonly columnIndex: number;
+    /**
+     * Get the `Document` object corresponding to the main component element.
+     *
+     * @returns The `Document` object used by the component.
+     */
+    readonly getOwnerDocument: () => Document | null;
+}
+declare const HotColumnContextProvider: FC<PropsWithChildren<HotColumnContextImpl>>;
+declare const useHotColumnContext: () => HotColumnContextImpl;
+export { useHotColumnContext, HotColumnContextProvider };

package/commonjs/src/hotEditor.d.ts

@@ -0,0 +1,33 @@
+import { DependencyList, FC, MutableRefObject, ReactNode, Ref, RefObject } from 'react';
+import Handsontable from 'handsontable/base';
+import { HotEditorHooks, UseHotEditorImpl } from './types';
+/**
+ * Create a class to be passed to the Handsontable's settings.
+ *
+ * @param {RefObject<HotEditorHooks>} hooksRef Reference to component-based editor overridden hooks object.
+ * @param {RefObject} instanceRef Reference to Handsontable-native custom editor class instance.
+ * @returns {Function} A class to be passed to the Handsontable editor settings.
+ */
+export declare function makeEditorClass(hooksRef: MutableRefObject<HotEditorHooks | null>, instanceRef: MutableRefObject<Handsontable.editors.BaseEditor | null>): typeof Handsontable.editors.BaseEditor;
+interface EditorContextProviderProps {
+    hooksRef: Ref<HotEditorHooks>;
+    hotCustomEditorInstanceRef: RefObject<Handsontable.editors.BaseEditor>;
+    children: ReactNode;
+}
+/**
+ * Provider of the context that exposes Handsontable-native editor instance and passes hooks object
+ * for custom editor components.
+ *
+ * @param {Ref} hooksRef Reference for component-based editor overridden hooks object.
+ * @param {RefObject} hotCustomEditorInstanceRef  Reference to Handsontable-native editor instance.
+ */
+export declare const EditorContextProvider: FC<EditorContextProviderProps>;
+/**
+ * Hook that allows encapsulating custom behaviours of component-based editor by customizing passed ref with overridden hooks object.
+ *
+ * @param {HotEditorHooks} overriddenHooks Overrides specific for the custom editor.
+ * @param {DependencyList} deps Overridden hooks object React dependency list.
+ * @returns {UseHotEditorImpl} Editor API methods
+ */
+export declare function useHotEditor<T>(overriddenHooks?: HotEditorHooks, deps?: DependencyList): UseHotEditorImpl<T>;
+export {};

package/commonjs/src/hotTable.d.ts

@@ -0,0 +1,29 @@
+import { ForwardRefExoticComponent, RefAttributes } from 'react';
+import { HotTableProps, HotTableRef } from './types';
+interface Version {
+    version?: string;
+}
+declare type HotTable = ForwardRefExoticComponent<HotTableProps & RefAttributes<HotTableRef>> & Version;
+/**
+ * A Handsontable-ReactJS wrapper.
+ *
+ * To implement, use the `HotTable` tag with properties corresponding to Handsontable options.
+ * For example:
+ *
+ * ```js
+ * <HotTable id="hot" data={dataObject} contextMenu={true} colHeaders={true} width={600} height={300} stretchH="all" />
+ *
+ * // is analogous to
+ * let hot = new Handsontable(document.getElementById('hot'), {
+ *    data: dataObject,
+ *    contextMenu: true,
+ *    colHeaders: true,
+ *    width: 600
+ *    height: 300
+ * });
+ *
+ * ```
+ */
+declare const HotTable: HotTable;
+export default HotTable;
+export { HotTable };

package/commonjs/src/hotTableContext.d.ts

@@ -0,0 +1,55 @@
+import Handsontable from 'handsontable/base';
+import { ComponentType, FC, PropsWithChildren } from 'react';
+import { ScopeIdentifier, HotRendererProps } from './types';
+import { RenderersPortalManagerRef } from './renderersPortalManager';
+export interface HotTableContextImpl {
+    /**
+     * Map with column indexes (or a string = 'global') as keys, and booleans as values. Each key represents a component-based editor
+     * declared for the used column index, or a global one, if the key is the `global` string.
+     */
+    readonly componentRendererColumns: Map<ScopeIdentifier, boolean>;
+    /**
+     * Array of object containing the column settings.
+     */
+    readonly columnsSettings: Handsontable.ColumnSettings[];
+    /**
+     * Sets the column settings based on information received from HotColumn.
+     *
+     * @param {HotTableProps} columnSettings Column settings object.
+     * @param {Number} columnIndex Column index.
+     */
+    readonly emitColumnSettings: (columnSettings: Handsontable.ColumnSettings, columnIndex: number) => void;
+    /**
+     * Return a renderer wrapper function for the provided renderer component.
+     *
+     * @param {ComponentType<HotRendererProps>} Renderer React renderer component.
+     * @returns {Handsontable.renderers.BaseRenderer} The Handsontable rendering function.
+     */
+    readonly getRendererWrapper: (Renderer: ComponentType<HotRendererProps>) => typeof Handsontable.renderers.BaseRenderer;
+    /**
+     * Clears portals cache.
+     */
+    readonly clearPortalCache: () => void;
+    /**
+     * Clears rendered cells cache.
+     */
+    readonly clearRenderedCellCache: () => void;
+    /**
+     * Set the renderers portal manager dispatch function.
+     *
+     * @param {RenderersPortalManagerRef} pm The PortalManager dispatch function.
+     */
+    readonly setRenderersPortalManagerRef: (pm: RenderersPortalManagerRef) => void;
+    /**
+     * Puts cell portals into portal manager and purges portals cache.
+     */
+    readonly pushCellPortalsIntoPortalManager: () => void;
+}
+declare const HotTableContextProvider: FC<PropsWithChildren>;
+/**
+ * Exposes the table context object to components
+ *
+ * @returns HotTableContext
+ */
+declare function useHotTableContext(): HotTableContextImpl;
+export { HotTableContextProvider, useHotTableContext };

package/commonjs/src/hotTableInner.d.ts

@@ -0,0 +1,5 @@
+import React from 'react';
+import { HotTableProps, HotTableRef } from './types';
+declare const HotTableInner: React.ForwardRefExoticComponent<HotTableProps & React.RefAttributes<HotTableRef>>;
+export default HotTableInner;
+export { HotTableInner };

package/commonjs/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './hotColumn';
+export * from './hotTable';
+export { useHotEditor } from './hotEditor';
+export * from './types';
+export { default } from './hotTable';

package/commonjs/src/renderersPortalManager.d.ts

@@ -0,0 +1,6 @@
+import React, { Dispatch, ReactPortal } from 'react';
+export declare type RenderersPortalManagerRef = Dispatch<ReactPortal[]>;
+/**
+ * Component used to manage the renderer component portals.
+ */
+export declare const RenderersPortalManager: React.ForwardRefExoticComponent<React.RefAttributes<React.Dispatch<React.ReactPortal[]>>>;

package/commonjs/src/settingsMapper.d.ts

@@ -0,0 +1,18 @@
+import Handsontable from 'handsontable/base';
+import { HotTableProps } from './types';
+export declare class SettingsMapper {
+    /**
+     * Parse component settings into Handsontable-compatible settings.
+     *
+     * @param {Object} properties Object containing properties from the HotTable object.
+     * @param {Object} additionalSettings Additional settings.
+     * @param {boolean} additionalSettings.isInit Flag determining whether the settings are being set during initialization.
+     * @param {string[]} additionalSettings.initOnlySettingKeys Array of keys that can be set only during initialization.
+     * @returns {Object} Handsontable-compatible settings object.
+     */
+    static getSettings(properties: HotTableProps, { prevProps, isInit, initOnlySettingKeys }?: {
+        prevProps?: HotTableProps;
+        isInit?: boolean;
+        initOnlySettingKeys?: Array<keyof Handsontable.GridSettings>;
+    }): Handsontable.GridSettings;
+}

package/commonjs/src/types.d.ts

@@ -0,0 +1,78 @@
+import Handsontable from 'handsontable/base';
+import { ComponentType, CSSProperties, Dispatch, DispatchWithoutAction, ReactNode } from 'react';
+/**
+ * Type of the identifier under which the cached components are stored.
+ */
+export declare type ScopeIdentifier = 'global' | number;
+/**
+ * Interface for the props of the component-based renderers.
+ */
+export interface HotRendererProps {
+    instance: Handsontable.Core;
+    TD: HTMLTableCellElement;
+    row: number;
+    col: number;
+    prop: string | number;
+    value: any;
+    cellProperties: Handsontable.CellProperties;
+}
+/**
+ * Interface for component-based editor overridden hooks object.
+ */
+export interface HotEditorHooks {
+    onOpen?: () => void;
+    onClose?: () => void;
+    onPrepare?: (row: number, column: number, prop: string | number, TD: HTMLTableCellElement, originalValue: any, cellProperties: Handsontable.CellProperties) => void;
+    onFocus?: () => void;
+}
+/**
+ * Interface for custom component-based editor API exposed by useHotEditor
+ */
+export interface UseHotEditorImpl<T> {
+    value?: T;
+    setValue: Dispatch<T>;
+    isOpen: boolean;
+    finishEditing: DispatchWithoutAction;
+    row?: number;
+    col?: number;
+}
+/**
+ * Helper type to expose GridSettings/ColumnSettings props with native renderers/editors separately
+ *  from component-based render prop.
+ */
+declare type ReplaceRenderersEditors<T extends Pick<Handsontable.GridSettings, 'renderer' | 'editor'>> = Omit<T, 'renderer' | 'editor'> & {
+    hotRenderer?: T['renderer'];
+    renderer?: ComponentType<HotRendererProps>;
+    hotEditor?: T['editor'];
+    editor?: ComponentType;
+};
+/**
+ * Interface for the `prop` of the HotTable component - extending the default Handsontable settings with additional,
+ * component-related properties.
+ */
+export interface HotTableProps extends ReplaceRenderersEditors<Handsontable.GridSettings> {
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+/**
+ * Properties related to the HotColumn architecture.
+ */
+export interface HotColumnProps extends ReplaceRenderersEditors<Handsontable.ColumnSettings> {
+    children?: ReactNode;
+}
+/**
+ * Type of interface exposed to parent components by HotTable instance via React ref
+ */
+export interface HotTableRef {
+    /**
+     * Reference to the main Handsontable DOM element.
+     */
+    hotElementRef: HTMLElement;
+    /**
+     * Reference to the Handsontable instance.
+     */
+    hotInstance: Handsontable | null;
+}
+export {};