@vitus-labs/elements 2.0.0-alpha.9 → 2.0.0-beta.1

package/README.md

@@ -16,12 +16,12 @@ Five composable components for building buttons, cards, lists, dropdowns, toolti
 - **Portal** — React Portal wrapper for DOM appending
 - **Util** — non-rendering utility for injecting className and style
 - **Responsive everything** — single value, array, or breakpoint object on every layout prop
-- **Selection state** — `withActiveState` HOC for single/multi item selection on List
+- **Equal before/after** — `equalBeforeAfter` prop on Element to equalize slot dimensions
 
 ## Installation
 
 ```bash
-npm install @vitus-labs/elements @vitus-labs/core @vitus-labs/unistyle styled-components
+npm install @vitus-labs/elements @vitus-labs/core @vitus-labs/unistyle
 ```
 
 ## Components
@@ -161,33 +161,6 @@ import { List, Element } from '@vitus-labs/elements'
 
 `index`, `first`, `last`, `odd`, `even`, `position` (1-based)
 
-### withActiveState
-
-HOC that adds selection state management to List.
-
-```tsx
-import { List, withActiveState } from '@vitus-labs/elements'
-
-const SelectableList = withActiveState(List)
-
-<SelectableList
-  type="single"
-  component={ListItem}
-  data={items}
-  activeItems="item-1"
-/>
-
-<SelectableList
-  type="multi"
-  component={ListItem}
-  data={items}
-  activeItems={['item-1', 'item-3']}
-  activeItemRequired
-/>
-```
-
-Each item receives: `active`, `handleItemActive`, `setItemActive`, `unsetItemActive`, `toggleItemActive`.
-
 ### Overlay
 
 Portal-based overlay with intelligent positioning and event management.
@@ -298,6 +271,10 @@ Every layout prop (direction, alignX, alignY, gap, block, equalCols) supports th
 <Element direction={{ xs: 'rows', md: 'inline', lg: 'inline' }} />
 ```
 
+## React Native
+
+Elements includes a native entry point (`index.native.ts`) that excludes Portal and Overlay (which depend on `react-dom`). Element, Text, List, and Util work on React Native when initialized with `@vitus-labs/connector-native`.
+
 ## Peer Dependencies
 
 | Package | Version |
@@ -306,7 +283,7 @@ Every layout prop (direction, alignX, alignY, gap, block, equalCols) supports th
 | react-dom | >= 19 |
 | @vitus-labs/core | * |
 | @vitus-labs/unistyle | * |
-| styled-components | >= 6 |
+| react-native | >= 0.76 (optional) |
 
 ## License
 

package/lib/index.d.ts

@@ -1,8 +1,7 @@
 import { Provider } from "@vitus-labs/unistyle";
 import { BreakpointKeys, HTMLTags, HTMLTextTags, config, render } from "@vitus-labs/core";
-import * as react from "react";
-import { ComponentType, FC, ForwardRefExoticComponent, ForwardedRef, PropsWithoutRef, ReactNode, Ref, RefAttributes } from "react";
-import * as react_jsx_runtime0 from "react/jsx-runtime";
+import * as _$react from "react";
+import { ComponentType, FC, ForwardRefExoticComponent, ForwardedRef, ReactElement, ReactNode } from "react";
 
 //#region src/types.d.ts
 type ExtractNullableKeys<T> = { [P in keyof T as T[P] extends null | undefined ? never : P]: T[P] };
@@ -10,7 +9,6 @@ type Id<T> = T extends infer U ? { [K in keyof U]: U[K] } : never;
 type SpreadTwo<L, R> = Id<Pick<L, Exclude<keyof L, keyof R>> & R>;
 type Spread<A extends readonly [...any]> = A extends [infer L, ...infer R] ? SpreadTwo<L, Spread<R>> : unknown;
 type MergeTypes<A extends readonly [...any]> = ExtractNullableKeys<Spread<A>>;
-type SimpleHoc<P extends Record<string, unknown> = {}> = (WrappedComponent: ComponentType<P>) => ComponentType<P>;
 type InnerRef = ForwardedRef<any>;
 type CssCallback = (css: typeof config.css) => ReturnType<typeof css>;
 type Css = CssCallback | ReturnType<typeof config.css> | string;
@@ -26,8 +24,9 @@ type Direction = ContentDirection | ContentDirection[] | Partial<Record<Breakpoi
 type ResponsiveBoolType = ContentBoolean | ContentBoolean[] | Partial<Record<BreakpointKeys, ContentBoolean>>;
 type Responsive = ContentSimpleValue | ContentSimpleValue[] | Partial<Record<BreakpointKeys, number | string>>;
 type ExtendCss = Css | Css[] | Partial<Record<BreakpointKeys, Css>>;
-type VLForwardedComponent<P extends Record<string, unknown> = {}> = ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<any>> & VLStatic;
-type VLComponent<P extends Record<string, any> = {}> = FC<P> & VLStatic;
+type VLComponent<P extends Record<string, any> = {}> = ((props: P & {
+  ref?: any;
+}) => ReactElement | null) & VLStatic;
 interface VLStatic {
   /**
    * React displayName
@@ -109,6 +108,14 @@ type Props = Partial<{
    * (have the same width or height)
    */
   equalCols: ResponsiveBoolType;
+  /**
+   * When true, measures the `beforeContent` and `afterContent` slot wrappers
+   * after render and sets both to the larger dimension so they match.
+   * Uses width for inline direction and height for rows direction.
+   * Useful for centering the main content when before/after slots have
+   * different intrinsic sizes.
+   */
+  equalBeforeAfter: boolean;
   /**
    * Defines a `gap` spacing between inner wrappers between `beforeContent` and `children`
    * and `children` and `afterContent`
@@ -270,220 +277,28 @@ type Props = Partial<{
    */
   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;
-   *    `}
-   *  />
-   * )
-   * ```
+   * An additional prop for extending styling of the **content** wrapper element.
+   * Accepts the same formats as `css` — template literal, string, css function, or callback.
    */
   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;
-   *    `}
-   *  />
-   * )
-   * ```
+   * An additional prop for extending styling of the **beforeContent** wrapper element.
+   * Accepts the same formats as `css` — template literal, string, css function, or callback.
    */
   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;
-   *    `}
-   *  />
-   * )
-   * ```
+   * An additional prop for extending styling of the **afterContent** wrapper element.
+   * Accepts the same formats as `css` — template literal, string, css function, or callback.
    */
   afterContentCss: ExtendCss;
 }>;
-type VLElement<P extends Record<string, unknown> = {}> = ForwardRefExoticComponent<PropsWithoutRef<Props & P> & RefAttributes<any>> & VLStatic;
+type VLElement<P extends Record<string, unknown> = {}> = ((props: Props & P & {
+  ref?: any;
+}) => ReactElement | null) & VLStatic;
 //#endregion
 //#region src/Element/component.d.ts
 declare const Component: VLElement;
 //#endregion
-//#region src/Element/withEqualSizeBeforeAfter.d.ts
-type Props$8 = Props & Partial<{
-  equalBeforeAfter: boolean;
-  ref: Ref<HTMLElement>;
-}>;
-declare const withEqualBeforeAfter: (WrappedComponent: any) => {
-  ({
-    equalBeforeAfter,
-    direction,
-    afterContent,
-    beforeContent,
-    ref,
-    ...rest
-  }: Props$8): react_jsx_runtime0.JSX.Element;
-  displayName: string;
-};
-//#endregion
 //#region src/helpers/Iterator/types.d.ts
 type MaybeNull = undefined | null;
 type TObj = Record<string, unknown>;
@@ -563,16 +378,6 @@ type ListProps = {
 type Props$2 = MergeTypes<[Props$1, ListProps]>;
 declare const Component$1: VLElement<Props$2>;
 //#endregion
-//#region src/List/withActiveState.d.ts
-type Key = string | number;
-interface Props$7 {
-  type?: 'single' | 'multi';
-  activeItemRequired?: boolean;
-  activeItems?: Key | (string | number)[];
-  itemProps?: Record<string, unknown> | ((props: Record<string, unknown>) => Record<string, unknown>);
-}
-declare const component: SimpleHoc<Props$7>;
-//#endregion
 //#region src/Overlay/context.d.ts
 interface Context {
   blocked: boolean;
@@ -583,10 +388,13 @@ declare const Component$3: FC<Context & {
   children: ReactNode;
 }>;
 //#endregion
-//#region src/Overlay/useOverlay.d.ts
+//#region src/Overlay/positionMath.d.ts
 type Align$1 = 'bottom' | 'top' | 'left' | 'right';
 type AlignX$2 = 'left' | 'center' | 'right';
 type AlignY$2 = 'bottom' | 'top' | 'center';
+type OverlayType = 'dropdown' | 'tooltip' | 'popover' | 'modal' | 'custom';
+//#endregion
+//#region src/Overlay/useOverlay.d.ts
 type UseOverlayProps = Partial<{
   /**
    * Defines default state whether **Overlay** component should be active.
@@ -610,7 +418,7 @@ type UseOverlayProps = Partial<{
    * has different positioning calculations than others.
    * @defaultValue `dropdown`
    */
-  type: 'dropdown' | 'tooltip' | 'popover' | 'modal' | 'custom';
+  type: OverlayType;
   /**
    * Defines how `content` is treated regarding CSS positioning.
    * @defaultValue `fixed`
@@ -659,6 +467,12 @@ type UseOverlayProps = Partial<{
    * @defaultValue `true`
    */
   closeOnEsc: boolean;
+  /**
+   * Delay in milliseconds before hiding content on hover leave. Bridges the
+   * gap between trigger and content elements to prevent flicker.
+   * @defaultValue `100`
+   */
+  hoverDelay: number;
   /**
    * When set to `true`, **Overlay** is automatically closed and is blocked for
    * being opened.
@@ -689,12 +503,13 @@ declare const useOverlay: ({
   throttleDelay,
   parentContainer,
   closeOnEsc,
+  hoverDelay,
   disabled,
   onOpen,
   onClose
 }?: Partial<UseOverlayProps>) => {
-  triggerRef: react.RefObject<HTMLElement | null>;
-  contentRef: (node: HTMLElement) => void;
+  triggerRef: _$react.RefObject<HTMLElement | null>;
+  contentRef: (node: HTMLElement | null) => void;
   active: boolean;
   align: Align$1;
   alignX: "left" | "right" | "center";
@@ -704,8 +519,8 @@ declare const useOverlay: ({
   blocked: boolean;
   setBlocked: () => void;
   setUnblocked: () => void;
-  Provider: react.FC<Context & {
-    children: react.ReactNode;
+  Provider: _$react.FC<Context & {
+    children: _$react.ReactNode;
   }>;
 };
 //#endregion
@@ -799,7 +614,7 @@ type Props$5 = Partial<{
    */
   css: ExtendCss;
 }>;
-declare const Component$5: VLForwardedComponent<Props$5> & {
+declare const Component$5: VLComponent<Props$5> & {
   isText?: true;
 };
 //#endregion
@@ -820,5 +635,5 @@ interface Props$6 {
 }
 declare const Component$6: VLComponent<Props$6>;
 //#endregion
-export { type AlignX, type AlignY, type Content, type ContentBoolean, type Direction, Component as Element, type Props as ElementProps, type ElementType, type ExtendCss, type ExtendedProps, type InnerRef, type Props$1 as IteratorProps, Component$1 as List, type Props$2 as ListProps, type ObjectValue, Component$2 as Overlay, type Props$3 as OverlayProps, Component$3 as OverlayProvider, Component$4 as Portal, type Props$4 as PortalProps, type PropsCallback, Provider, type Responsive, type ResponsiveBoolType, Component$5 as Text, type Props$5 as TextProps, type UseOverlayProps, Component$6 as Util, type Props$6 as UtilProps, type VLStatic, useOverlay, component as withActiveState, withEqualBeforeAfter as withEqualSizeBeforeAfter };
+export { type AlignX, type AlignY, type Content, type ContentBoolean, type Direction, Component as Element, type Props as ElementProps, type ElementType, type ExtendCss, type ExtendedProps, type InnerRef, type Props$1 as IteratorProps, Component$1 as List, type Props$2 as ListProps, type ObjectValue, Component$2 as Overlay, type Props$3 as OverlayProps, Component$3 as OverlayProvider, Component$4 as Portal, type Props$4 as PortalProps, type PropsCallback, Provider, type Responsive, type ResponsiveBoolType, Component$5 as Text, type Props$5 as TextProps, type UseOverlayProps, Component$6 as Util, type Props$6 as UtilProps, type VLStatic, useOverlay };
 //# sourceMappingURL=index2.d.ts.map