HoistProps.ts

/*
 * This file belongs to Hoist, an application development toolkit
 * developed by Extremely Heavy Industries (www.xh.io | info@xh.io)
 *
 * Copyright © 2026 Extremely Heavy Industries Inc.
 */
import {HoistModel} from '@xh/hoist/core';
import {Property} from 'csstype';
import {CSSProperties, HTMLAttributes, LegacyRef, ReactNode, Ref} from 'react';

/**
 * Props interface for Hoist Components.
 *
 * This interface brings in additional properties that are added to the props
 * collection by HoistComponent.
 */
export interface HoistProps<M extends HoistModel = HoistModel> {
    /**
     * Associated HoistModel for this Component.  Depending on the component, may be specified as
     * an instance of a HoistModel, or a configuration object to create one, or left undefined.
     * HoistComponent will resolve (i.e. lookup in context or create if needed) a concrete Model
     * instance and provide it to the Render method of the component.
     */
    model?: M;

    /**
     * Used for specifying the *configuration* of a model to be created by Hoist for this component
     * when first mounted.  Should be used only on a component that specifies the 'uses()' directive
     * with the `createFromConfig` set as true. See the `uses()` directive for more information.
     */
    modelConfig?: M extends null ? never : M['config'];

    /**
     * Used for gaining a reference to the model of a HoistComponent.
     */
    modelRef?: M extends null ? never : Ref<M>;

    /**
     * ClassName for the component.  Includes the classname as provided in props, enhanced with
     * any base class name provided by the component definition itself.
     */
    className?: string;

    /** React children. */
    children?: ReactNode;

    /** React Ref for this component. */
    ref?: LegacyRef<any>;
}

/**
 * A version of Hoist props that allows dynamic keys/properties.   This is the interface that
 * Hoist uses for components that do not explicitly specify the type of props they expect.
 *
 * This behavior is useful for file or package-local components that do not require an explicit
 * props API.
 */

export interface DefaultHoistProps<M extends HoistModel = HoistModel> extends HoistProps<M> {
    [x: string]: any;
}

/**
 * Props for components that support standard layout attributes (margin, padding, dimensions,
 * flex, alignment, overflow). Extends {@link LayoutProps} with test support and standard
 * HTML div attributes.
 *
 * Higher-level components accept these props and pass them through to a {@link Box} or
 * {@link Frame} at the bottom of their render tree, where they are resolved to CSS styles.
 *
 * @see Box
 * @see Frame
 * @see LayoutProps
 */
export interface BoxProps
    extends
        LayoutProps,
        TestSupportProps,
        Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'contextMenu'> {}

/**
 * Props for Components that accept standard HTML `style` attributes.
 */
export interface StyleProps {
    style?: CSSProperties;
}

/**
 * Props to support reliable selection of components for automated testing.
 */
export interface TestSupportProps {
    /**
     * Unique identifier for this component for the purposes of locating and interacting with
     * its primary/outer DOM element using automated testing tools. Hoist components that support
     * this interface will add a "data-testid" attribute to an appropriate DOM element - typically
     * (but not always) the outermost tag in their rendered markup. Some components may generate
     * and apply additional child testIds to support testing of nested elements.
     */
    testId?: string;
}

export interface LayoutProps {
    margin?: string | number | boolean;
    marginTop?: string | number | boolean;
    marginRight?: string | number | boolean;
    marginBottom?: string | number | boolean;
    marginLeft?: string | number | boolean;

    padding?: string | number | boolean;
    paddingTop?: string | number | boolean;
    paddingRight?: string | number | boolean;
    paddingBottom?: string | number | boolean;
    paddingLeft?: string | number | boolean;

    height?: string | number;
    minHeight?: string | number;
    maxHeight?: string | number;
    width?: string | number;
    minWidth?: string | number;
    maxWidth?: string | number;

    flex?: string | number;
    flexBasis?: string | number;
    flexDirection?: Property.FlexDirection;
    flexFlow?: Property.FlexFlow;
    flexGrow?: string | number;
    flexShrink?: string | number;
    flexWrap?: Property.FlexWrap;
    gap?: string | number | boolean;

    alignItems?: string;
    alignSelf?: string;
    alignContent?: string;
    justifyContent?: string;

    overflow?: string;
    overflowX?: Property.OverflowX;
    overflowY?: Property.OverflowY;
    textOverflow?: string;

    top?: string | number;
    left?: string | number;
    position?: Property.Position;
    display?: string;
}

/** LayoutProps after resolution by `getLayoutProps()`, with boolean values resolved. */
export type ResolvedLayoutProps = {
    [K in keyof LayoutProps]: Exclude<LayoutProps[K], boolean>;
};