@vitus-labs/elements 0.77.0 → 0.80.0

package/lib/index.d.ts

@@ -5,7 +5,7 @@ import { FC } from 'react';
 import type { ForwardedRef } from 'react';
 import type { ForwardRefExoticComponent } from 'react';
 import { HTMLTags } from '@vitus-labs/core';
-import type { HTMLTagsText } from '@vitus-labs/core';
+import type { HTMLTextTags } from '@vitus-labs/core';
 import { MutableRefObject } from 'react';
 import type { PropsWithChildren } from 'react';
 import { Provider } from '@vitus-labs/unistyle';
@@ -63,32 +63,421 @@ declare const Element_2: VLElement;
 export { Element_2 as Element }
 
 export declare type ElementProps = Partial<{
+    /**
+     * Valid HTML Tag
+     */
     tag: HTMLTags;
+    /**
+     * React `ref`, the prop is alternative to `ref` prop without need to wrap component to `forwardRef`
+     */
     innerRef: InnerRef;
+    /**
+     * Valid React `children`
+     */
     children: Content;
+    /**
+     * Alternative prop to React `children`
+     * It is recommended to pass only one of `children`, `content` or `label` props
+     *
+     * The prioritization of rendering is following: `children` → `content` → `label`
+     */
     content: Content;
+    /**
+     * Alternative prop to React `children`
+     * It is recommended to pass only one of `children`, `content` or `label` props
+     *
+     * The prioritization of rendering is following: `children` → `content` → `label`
+     */
     label: Content;
+    /**
+     * Valid React `children` to be rendered inside _beforeContent_ wrapper
+     *
+     * In a case, where at least one of `beforeContent` or `afterContent` is defined,
+     * **Element** component will render additional inner wrapper helpers to
+     * attach `beforeContent` **before** any of `children`, `context` or `label`
+     * props.
+     *
+     * Together with prop `direction` can be the **Element** component aligned
+     * vertically or horizontally.
+     *
+     * To attach any react node _after_, use `afterContent`
+     */
     beforeContent: Content;
+    /**
+     * Valid React `children` to be rendered inside _afterContent_ wrapper
+     *
+     * In a case, where at least one of `beforeContent` or `afterContent` is defined,
+     * **Element** component will render additional inner wrapper helpers to
+     * attach `afterContent` **after** any of `children`, `context` or `label`
+     * props.
+     *
+     * Together with prop `direction` can be the **Element** component aligned
+     * vertically or horizontally.
+     *
+     * To attach any react node _before_, use `beforeContent`
+     */
     afterContent: Content;
+    /**
+     * A boolean type to define wheather **Element** should behave
+     * as an inline or block element (`flex` vs. `inline-flex`)
+     */
     block: ResponsiveBooltype;
+    /**
+     * A boolean type to define wheather inner wrappers should be equal
+     * (have the same width or height)
+     */
     equalCols: ResponsiveBooltype;
+    /**
+     * Defines a `gap` spacing between inner wrappers between `beforeContent` and `children`
+     * and `children` and `afterContent`
+     */
     gap: Responsive;
+    /**
+     * Defines a `gap` spacing between inner wrappers between `beforeContent`,
+     * `children` and `afterContent`
+     */
     direction: Direction;
+    /**
+     * Defines flow of `children` elements within it's inner wrapper.
+     *
+     * Can be one of the following **flex** values `inline` | `rows` | `reverseInline` | `reverseRows`
+     */
     contentDirection: Direction;
+    /**
+     * Defines flow of `beforeContent` elements within it's inner wrapper.
+     *
+     * Can be one of the following **flex** values `inline` | `rows` | `reverseInline` | `reverseRows`
+     */
     beforeContentDirection: Direction;
+    /**
+     * Defines flow of `afterContent` elements within it's inner wrapper.
+     *
+     * Can be one of the following **flex** values `inline` | `rows` | `reverseInline` | `reverseRows`
+     */
     afterContentDirection: Direction;
+    /**
+     * Define alignment of `beforeContent`, `content`, and `afterContent`
+     * with respect to root element **horizontally**.
+     *
+     * Can be one of the following **flex** values `left` | `center` | `right` | `spaceBetween` |
+     * `spaceAround` | `block`
+     */
     alignX: AlignX;
+    /**
+     * Defines how `content` children (`children`, `content` or `label` props)
+     * are aligned within it's inner wrapper **horizontally**.
+     *
+     * Can be one of the following **flex** values `left` | `center` | `right` | `spaceBetween` |
+     * `spaceAround` | `block`
+     */
     contentAlignX: AlignX;
+    /**
+     * Defines how `beforeContent` children are aligned within it's inner wrapper **horizontally**.
+     *
+     * Can be one of the following **flex** values `left` | `center` | `right` | `spaceBetween` |
+     * `spaceAround` | `block`
+     */
     beforeContentAlignX: AlignX;
+    /**
+     * Defines how `afterContent` children are aligned within it's inner wrapper **horizontally**.
+     *
+     * Can be one of the following **flex** values `left` | `center` | `right` | `spaceBetween` |
+     * `spaceAround` | `block`
+     */
     afterContentAlignX: AlignX;
+    /**
+     * Define alignment of `beforeContent`, `content`, and `afterContent`
+     * with respect to root element **vertically**.
+     *
+     * Can be one of the following **flex** values `top` | `center` | `bottom` | `spaceBetween` |
+     * `spaceAround` | `block`
+     */
     alignY: AlignY;
+    /**
+     * Defines how `content` children (`children`, `content` or `label` props)
+     * are aligned within it's inner wrapper **vertically**.
+     *
+     * Can be one of the following **flex** values `top` | `center` | `bottom` | `spaceBetween` |
+     * `spaceAround` | `block`
+     */
     contentAlignY: AlignY;
+    /**
+     * Defines how `beforeContent` children are aligned within it's inner wrapper **vertically**.
+     *
+     * Can be one of the following **flex** values `top` | `center` | `bottom` | `spaceBetween` |
+     * `spaceAround` | `block`
+     */
     beforeContentAlignY: AlignY;
+    /**
+     * Defines how `afterContent` children are aligned within it's inner wrapper **vertically**.
+     *
+     * Can be one of the following **flex** values `top` | `center` | `bottom` | `spaceBetween` |
+     * `spaceAround` | `block`
+     */
     afterContentAlignY: AlignY;
-    dangerouslySetInnerHTML: any;
+    /**
+     * React `dangerouslySetInnerHTML` prop. For more details follow the link:
+     *
+     * https://reactjs.org/docs/dom-elements.html#dangerouslysetinnerhtml
+     */
+    dangerouslySetInnerHTML: {
+        __html: string;
+    };
+    /**
+     * An additional prop for extending styling of the **root** wrapper element
+     *
+     * #### [A] Template literals
+     *
+     * (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+     *
+     * ```jsx
+     * export default () => (
+     *  <Element
+     *    label="This is an element"
+     *    css={`
+     *      text-color: red;
+     *    `}
+     *  />
+     * )
+     * ```
+     *
+     * #### [B] String
+     *
+     * (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+     *
+     * ```jsx
+     * export default () => (
+     *  <Element
+     *    label="This is an element"
+     *    css="text-color: red;"
+     *  />
+     * )
+     * ```
+     *
+     * #### [C] Css Function
+     *
+     * (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+     *
+     * ```jsx
+     * import { css } from 'styled-components'
+     *
+     * export default () => (
+     *  <Element
+     *    label="This is an element"
+     *    css={css`
+     *      text-color: red;
+     *    `}
+     *  />
+     * )
+     * ```
+     *
+     * #### [D] Css Callback
+     *
+     * (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+     *
+     * ```jsx
+     * export default () => (
+     *  <Element
+     *    label="This is an element"
+     *    css={css => css`
+     *      text-color: red;
+     *    `}
+     *  />
+     * )
+     * ```
+     */
     css: ExtendCss;
+    /**
+     * An additional prop for extending styling of the **content** wrapper element
+     *
+     * #### [A] Template literals
+     *
+     * (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+     *
+     * ```jsx
+     * export default () => (
+     *  <Element
+     *    label="This is an element"
+     *    css={`
+     *      text-color: red;
+     *    `}
+     *  />
+     * )
+     * ```
+     *
+     * #### [B] String
+     *
+     * (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+     *
+     * ```jsx
+     * export default () => (
+     *  <Element
+     *    label="This is an element"
+     *    css="text-color: red;"
+     *  />
+     * )
+     * ```
+     *
+     * #### [C] Css Function
+     *
+     * (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+     *
+     * ```jsx
+     * import { css } from 'styled-components'
+     *
+     * export default () => (
+     *  <Element
+     *    label="This is an element"
+     *    css={css`
+     *      text-color: red;
+     *    `}
+     *  />
+     * )
+     * ```
+     *
+     * #### [D] Css Callback
+     *
+     * (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+     *
+     * ```jsx
+     * export default () => (
+     *  <Element
+     *    label="This is an element"
+     *    css={css => css`
+     *      text-color: red;
+     *    `}
+     *  />
+     * )
+     * ```
+     */
     contentCss: ExtendCss;
+    /**
+     * An additional prop for extending styling of the **beforeContent** wrapper element
+     *
+     * #### [A] Template literals
+     *
+     * (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+     *
+     * ```jsx
+     * export default () => (
+     *  <Element
+     *    label="This is an element"
+     *    css={`
+     *      text-color: red;
+     *    `}
+     *  />
+     * )
+     * ```
+     *
+     * #### [B] String
+     *
+     * (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+     *
+     * ```jsx
+     * export default () => (
+     *  <Element
+     *    label="This is an element"
+     *    css="text-color: red;"
+     *  />
+     * )
+     * ```
+     *
+     * #### [C] Css Function
+     *
+     * (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+     *
+     * ```jsx
+     * import { css } from 'styled-components'
+     *
+     * export default () => (
+     *  <Element
+     *    label="This is an element"
+     *    css={css`
+     *      text-color: red;
+     *    `}
+     *  />
+     * )
+     * ```
+     *
+     * #### [D] Css Callback
+     *
+     * (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+     *
+     * ```jsx
+     * export default () => (
+     *  <Element
+     *    label="This is an element"
+     *    css={css => css`
+     *      text-color: red;
+     *    `}
+     *  />
+     * )
+     * ```
+     */
     beforeContentCss: ExtendCss;
+    /**
+     * An additional prop for extending styling of the **afterContent** wrapper element
+     *
+     * #### [A] Template literals
+     *
+     * (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+     *
+     * ```jsx
+     * export default () => (
+     *  <Element
+     *    label="This is an element"
+     *    css={`
+     *      text-color: red;
+     *    `}
+     *  />
+     * )
+     * ```
+     *
+     * #### [B] String
+     *
+     * (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+     *
+     * ```jsx
+     * export default () => (
+     *  <Element
+     *    label="This is an element"
+     *    css="text-color: red;"
+     *  />
+     * )
+     * ```
+     *
+     * #### [C] Css Function
+     *
+     * (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+     *
+     * ```jsx
+     * import { css } from 'styled-components'
+     *
+     * export default () => (
+     *  <Element
+     *    label="This is an element"
+     *    css={css`
+     *      text-color: red;
+     *    `}
+     *  />
+     * )
+     * ```
+     *
+     * #### [D] Css Callback
+     *
+     * (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)
+     *
+     * ```jsx
+     * export default () => (
+     *  <Element
+     *    label="This is an element"
+     *    css={css => css`
+     *      text-color: red;
+     *    `}
+     *  />
+     * )
+     * ```
+     */
     afterContentCss: ExtendCss;
 }>;
 
@@ -126,13 +515,41 @@ export declare type InnerRef = ForwardedRef<any>;
 declare type isEmpty = null | undefined;
 
 export declare type IteratorProps = Partial<{
+    /**
+     * Valid React `children`
+     */
     children: ReactNode;
+    /**
+     * Array of data passed to `component` prop
+     */
     data: Array<SimpleValue | ObjectValue | MaybeNull>;
+    /**
+     * A React component to be rendred within list
+     */
     component: ElementType;
+    /**
+     * Defines name of the prop to be passed to the iteration component
+     * when **data** prop is type of `string[]`, `number[]` or combination
+     * of both. Otherwise ignored.
+     */
     valueName: string;
+    /**
+     * A React component to be rendred within list. `wrapComponent`
+     * wraps `component`. Therefore it can be used to enhance the behavior
+     * of the list component
+     */
     wrapComponent: ElementType;
+    /**
+     * Extension of **item** `component` props to be passed
+     */
     itemProps: PropsCallback;
+    /**
+     * Extension of **item** `wrapComponent` props to be passed
+     */
     wrapProps?: PropsCallback;
+    /**
+     * Extension of **item** `wrapComponent` props to be passed
+     */
     itemKey?: keyof ObjectValue | ((item: SimpleValue | Omit<ObjectValue, 'component'>, index: number) => SimpleValue);
 }>;
 
@@ -142,12 +559,25 @@ export declare const List: VLElement<ListProps>;
 
 export declare type ListProps = MergeTypes<[
 IteratorProps,
-    {
+ListProps_2
+]>;
+
+declare type ListProps_2 = {
+    /**
+     * A boolean value. When set to `false`, component returns `React.Fragment`
+     * When set to `true`, component returns as the **root** element `Element`
+     * component.
+     */
     rootElement?: boolean;
+    /**
+     * Label prop frol `Element` component is being ignored.
+     */
     label: never;
+    /**
+     * Content prop frol `Element` component is being ignored.
+     */
     content: never;
-}
-]>;
+};
 
 declare type MaybeNull = undefined | null;
 
@@ -163,10 +593,33 @@ export declare type ObjectValue = Partial<{
 export declare const Overlay: VLComponent<OverlayProps>;
 
 export declare type OverlayProps = {
+    /**
+     * Children to be rendered within **Overlay** component when Overlay is active.
+     */
     children: Content | TriggerRenderer;
+    /**
+     * React component to be used as a trigger (e.g. `Button` for opening
+     * dropdowns). Component must acept accept `ref` or any other prop name
+     * defined in `triggerRefName` prop.
+     */
     trigger: Content | ContentRenderer;
+    /**
+     * Defines a HTML DOM where children to be appended. Component uses JavaScript
+     * [`Node.appendChild`](https://developer.mozilla.org/en-US/docs/Web/API/Node/appendChild)
+     *
+     * For more information follow [Portal](https://vitus-labs.com/docs/ui-system/elements/portal)
+     * component.
+     */
     DOMLocation?: HTMLElement;
+    /**
+     * Defines a prop name to be used for passing `ref` for **trigger**. By default,
+     * the value is `ref`.
+     */
     triggerRefName?: string;
+    /**
+     * Defines a prop name to be used for passing `ref` for **content** (passed `children`).
+     * By default, the value is `ref`.
+     */
     contentRefName?: string;
 } & UseOverlayProps;
 
@@ -177,8 +630,18 @@ export declare const OverlayProvider: FC<Context & {
 export declare const Portal: VLComponent<PortalProps>;
 
 export declare type PortalProps = {
+    /**
+     * Defines a HTML DOM where children to be appended. Component uses JavaScript
+     * [`Node.appendChild`](https://developer.mozilla.org/en-US/docs/Web/API/Node/appendChild)
+     */
     DOMLocation?: HTMLElement;
+    /**
+     * Children to be rendered within **Portal** component.
+     */
     children: ReactNode;
+    /**
+     * Valid HTML Tag
+     */
     tag?: string;
 };
 
@@ -218,11 +681,26 @@ declare const Text_2: VLForwardedComponent<TextProps> & {
 export { Text_2 as Text }
 
 export declare type TextProps = Partial<{
-    paragraph: boolean;
+    /**
+     * Label can be used instead of children for inline syntax. But **children** prop takes a precedence
+     */
     label: ReactNode;
+    /**
+     * Children to be rendered within **Text** component.
+     */
     children: ReactNode;
-    tag: HTMLTagsText;
-    extendCss: ExtendCss;
+    /**
+     * Defines whether should behave as a block text element. Automatically adds **p** HTML tag
+     */
+    paragraph: boolean;
+    /**
+     * Defines what kind of HTML tag should be rendered
+     */
+    tag: HTMLTextTags;
+    /**
+     * If an additional styling needs to be added, it can be do so via injecting styles using this property.
+     */
+    css: ExtendCss;
 }>;
 
 declare type TObj = Record<string, unknown>;
@@ -255,38 +733,104 @@ export declare const useOverlay: ({ isOpen, openOn, closeOn, type, position, ali
 };
 
 export declare type UseOverlayProps = Partial<{
+    /**
+     * Defines default state whather **Overlay** component should be active.
+     * Default value is `false`.
+     */
     isOpen: boolean;
+    /**
+     * Defines `event` when **Overlay** is supposed to be open.
+     *
+     * When `manual` is set, callbacks needs to be applied to make it working.
+     */
     openOn: 'click' | 'hover' | 'manual';
+    /**
+     * Defines `event` when **Overlay** is supposed to be closed.
+     */
     closeOn: 'click' | 'clickOnTrigger' | 'clickOutsideContent' | 'hover' | 'manual';
+    /**
+     * Defines what type of **Overlay** will be created. Type `modal`
+     * has different positioning calculations than others.
+     */
     type: 'dropdown' | 'tooltip' | 'popover' | 'modal';
+    /**
+     * Defines how `content` is treated regarding CSS positioning.
+     */
     position: 'absolute' | 'fixed' | 'relative' | 'static';
+    /**
+     * Defines from which side is `content` aligned to `trigger` (top, left, bottom, right).
+     * For more specific alignment configuration can be used `alignX` and/or `alignY` prop.
+     */
     align: Align;
+    /**
+     * Defines how `content` is aligned to `trigger` on axis X
+     */
     alignX: AlignX_2;
+    /**
+     * Defines how `content` is aligned to `trigger` on axis Y
+     */
     alignY: AlignY_2;
+    /**
+     * Defines `margin` from trigger on axis X.
+     */
     offsetX: number;
+    /**
+     * Defines `margin` from trigger on axis Y.
+     */
     offsetY: number;
+    /**
+     * Performance helper. Value defined in miliseconds for `throttling`
+     * recalculations
+     */
     throttleDelay: number;
+    /**
+     * A valid HTML element. Prop can be used for ability to handle properly
+     * scrolling inside custom scrollable HTML element.
+     */
     parentContainer: HTMLElement | null;
+    /**
+     * Defines wheather active **Overlay** is supposed to be closed on pressing
+     * `ESC` key.
+     */
     closeOnEsc: boolean;
+    /**
+     * When set to `true`, **Overlay** is automatically closed and is blocked for
+     * being opened.
+     */
     disabled: boolean;
+    /**
+     * A callback hook to be called when **Overlay** is being opened. Does not
+     * accept any arguments.
+     */
     onOpen: () => void;
+    /**
+     * A callback hook to be called when **Overlay** is being closed. Does not
+     * accept any arguments.
+     */
     onClose: () => void;
 }>;
 
 export declare const Util: VLComponent<UtilProps>;
 
 export declare type UtilProps = {
+    /**
+     * Children to be rendered within **Util** component.
+     */
     children: ReactNode;
+    /**
+     * Class name(s) to be added to children component.
+     */
     className?: string | string[];
+    /**
+     * Style property to extend children component inline styles
+     */
     style?: Record<string, unknown>;
 };
 
 declare type VLComponent<P = Record<string, unknown>> = FC<P> & VLStatic;
 
 declare type VLElement<P extends Record<string, unknown> = {}> = {
-    <T extends HTMLTags>(props: {
-        tag?: T;
-    } & ElementProps & P & {
+    <T extends Record<string, unknown> = {}>(props: ElementProps & P & T & {
         ref?: ForwardedRef<any>;
     }): ReactElement | null;
 } & VLStatic;