@react-hive/honey-layout 1.3.0-beta → 2.3.1

package/dist/components/index.d.ts

@@ -1,4 +1,5 @@
 export * from './HoneyBox';
+export * from './HoneyFlexBox';
 export * from './HoneyGrid';
 export * from './HoneyGridColumn';
 export * from './HoneyList';

package/dist/constants.d.ts

@@ -1,3 +1,3 @@
 import { HoneyCSSColorProperty, HoneyCSSDimensionProperty } from './types';
-export declare const CSS_DIMENSION_PROPERTIES: HoneyCSSDimensionProperty[];
-export declare const CSS_COLOR_PROPERTIES: HoneyCSSColorProperty[];
+export declare const CSS_DIMENSION_PROPERTIES: readonly HoneyCSSDimensionProperty[];
+export declare const CSS_COLOR_PROPERTIES: readonly HoneyCSSColorProperty[];

package/dist/helpers.d.ts

@@ -1,63 +1,76 @@
 import { HTMLAttributes } from 'react';
-import { HoneyBreakpointName, HoneyCSSArrayValue, HoneyCSSDimensionShortHandValue, HoneyCSSDimensionUnit, HoneyCSSMultiValue, HoneyCSSMediaRule, HoneySpacings, HoneyThemedProps, HoneyColorKey, HoneyFontName, HoneyCSSColor, HoneyDimensionName, Nullable, HoneyCSSProperties, HoneyBreakpoints, HoneyScreenState } from './types';
+import { ExecutionContext, StyleFunction, css } from 'styled-components';
+import { Nullable, HoneyBreakpointName, HoneyCSSArrayValue, HoneyCSSDimensionShortHandValue, HoneyCSSDimensionUnit, HoneyCSSMultiValue, HoneyCSSMediaRule, HoneySpacings, HoneyColorKey, HoneyFontName, HoneyCSSColor, HoneyDimensionName, HoneyPrefixedCSSProperties, HoneyBreakpoints, HoneyScreenState, HoneyCSSDimensionValue } from './types';
 /**
  * Conditional type to determine the return type of the `resolveSpacing` function.
  *
- * @template MultiValue - Type of the spacing value, can be a single value or an array of values.
+ * @template MultiValue - Type of the spacing value can be a single value or an array of values.
  * @template Unit - CSS length unit, which can be null or a specific unit type.
- * @template T - Type of the numeric value.
  */
-type ResolveSpacingResult<MultiValue extends HoneyCSSMultiValue<T>, Unit extends Nullable<HoneyCSSDimensionUnit>, T extends number> = Unit extends null ? MultiValue extends HoneyCSSArrayValue<T> ? HoneyCSSArrayValue<T> : T : MultiValue extends HoneyCSSArrayValue<T> ? HoneyCSSDimensionShortHandValue<MultiValue, NonNullable<Unit>> : `${T}${Unit}`;
+export type ResolveSpacingResult<MultiValue extends HoneyCSSMultiValue<number>, Unit extends Nullable<HoneyCSSDimensionUnit>> = Unit extends null ? MultiValue extends HoneyCSSArrayValue<number> ? HoneyCSSArrayValue<number> : number : MultiValue extends HoneyCSSArrayValue<number> ? HoneyCSSDimensionShortHandValue<MultiValue, NonNullable<Unit>> : `${number}${Unit}`;
 /**
- * Resolves the spacing value based on the provided `value`, `unit`, and `type`.
- *
- * @template MultiValue - Type of the spacing value, can be a single value or an array of values.
- * @template Unit - CSS length unit, which can be null or a specific unit type.
- * @template T - Type of the numeric value.
- *
- * @param value - The spacing factor to be applied, which can be a single number or an array of 2, 3, or 4 numbers.
- * @param unit - The CSS unit to be used for the calculated value, e.g., 'px', 'em'. Set `null` to apply no unit. Default: 'px'.
- * @param type - The type of spacing to be used from the theme, e.g., 'base', 'small', 'large'. Default: 'base'.
- *
- * @returns The resolved spacing value, either as a single number or a string of space-separated numbers, optionally with the specified unit.
+ * Resolves a spacing value or multiple spacing values based on the provided input, CSS unit, and spacing type.
+ * This function calculates the appropriate spacing values from a theme and formats them with the specified CSS unit.
+ *
+ * @template MultiValue - Represents the spacing value(s), which could be a single number or an array of numbers (e.g., [1, 2, 3, 4]).
+ * @template Unit - The CSS unit used for the resolved spacing value, e.g., 'px', 'em'. Defaults to 'px'.
+ *
+ * @param {MultiValue} value - The spacing factor(s) to be applied. It can be:
+ * - A single number representing a multiplier for the base spacing value.
+ * - An array of numbers representing multiple multipliers for base spacing values (e.g., for margins or padding).
+ * @param {Unit} [unit='px'] - The CSS unit to use for the calculated value. If `null` or `undefined`, no unit is applied.
+ * Defaults to 'px'.
+ * @param {keyof HoneySpacings} [type='base'] - The type of spacing to use from the theme. Determines which base spacing
+ * value to use for calculations (e.g., 'base', 'small', 'large'). Defaults to 'base'.
+ *
+ * @returns {(context: ExecutionContext) => ResolveSpacingResult<MultiValue, Unit>} - A function that takes `ExecutionContext`
+ * (containing the theme object) and returns the resolved spacing value(s). The result is either:
+ * - A single calculated value (e.g., '16px') if the input is a single number.
+ * - A string of space-separated values (e.g., '8px 16px 24px 32px') if the input is an array of numbers.
  */
-export declare const resolveSpacing: <MultiValue extends HoneyCSSMultiValue<T>, Unit extends Nullable<HoneyCSSDimensionUnit> = "px", T extends number = number>(value: MultiValue, unit?: Unit, type?: keyof HoneySpacings) => ({ theme }: HoneyThemedProps) => ResolveSpacingResult<MultiValue, Unit, T>;
+export declare const resolveSpacing: <MultiValue extends HoneyCSSMultiValue<number>, Unit extends Nullable<HoneyCSSDimensionUnit> = "px">(value: MultiValue, unit?: Unit, type?: keyof HoneySpacings) => ((context: ExecutionContext) => ResolveSpacingResult<MultiValue, Unit>);
 /**
  * Resolves a color value based on the provided color key and optional alpha value.
  *
  * @param colorKey - The key representing the color to be resolved. This key is a string in the format 'colorType.colorName'.
- * @param alpha - Optional. The alpha transparency value between 0 (fully transparent) and 1 (fully opaque).
+ * @param alpha - Optional. The alpha transparency value between 0 (fully transparent) and 1 (fully opaque). Default to `undefined`.
  *
  * @returns The resolved color value from the theme, either in HEX format or in 8-character HEX with alpha format.
  *
  * @throws Will throw an error if the provided alpha value is not within the valid range (0 to 1).
  * @throws Will throw an error if the color format is invalid.
  */
-export declare const resolveColor: (colorKey: HoneyColorKey, alpha?: number) => ({ theme }: HoneyThemedProps) => HoneyCSSColor;
+export declare const resolveColor: (colorKey: HoneyColorKey, alpha?: number) => ({ theme }: ExecutionContext) => HoneyCSSColor;
 /**
  * Resolves the font styles based on the provided font name from the theme.
  *
- * @param fontName - The name of the font to be resolved from the theme.
+ * @param {HoneyFontName} fontName - The name of the font to be resolved from the theme.
  *
- * @returns A function that takes the theme and returns the CSS for the specified font.
+ * @returns A style function that takes a theme object and returns the CSS styles for the specified font.
  */
-export declare const resolveFont: (fontName: HoneyFontName) => ({ theme }: HoneyThemedProps) => import('styled-components').FlattenSimpleInterpolation;
+export declare const resolveFont: (fontName: HoneyFontName) => ({ theme }: ExecutionContext) => import('styled-components').RuleSet<object>;
 /**
  * Resolves a specific dimension value from the theme configuration.
  *
- * @param dimensionName - The name of the dimension to resolve.
+ * @param {HoneyDimensionName} dimensionName - The name of the dimension to resolve.
  *
- * @returns A function that takes the theme and returns the resolved dimension value from the theme.
+ * @returns A style function that takes the theme and returns the resolved dimension value from the theme.
  */
-export declare const resolveDimension: (dimensionName: HoneyDimensionName) => ({ theme }: HoneyThemedProps) => `${number}px` | `${number}cm` | `${number}mm` | `${number}in` | `${number}pt` | `${number}pc` | `${number}em` | `${number}rem` | `${number}%` | `${number}vh` | `${number}vw` | `${number}vmin` | `${number}vmax`;
+export declare const resolveDimension: (dimensionName: HoneyDimensionName) => ({ theme }: ExecutionContext) => HoneyCSSDimensionValue;
 /**
- * Generates CSS styles based on the provided breakpoint and props.
- * Filters the props to include only those with breakpoints matching the specified breakpoint.
- * For each matching prop, it converts the property name to dash-case and retrieves the corresponding value.
+ * Generates CSS styles based on the provided breakpoint and properties.
+ * Filters the properties to include only those that match the specified breakpoint.
+ * Converts the property names from camelCase to dash-case and retrieves their values.
  *
- * @param {HoneyBreakpointName} breakpoint - The name of the breakpoint.
+ * @template Props - The type representing HTML attributes and Honey-prefixed CSS properties.
+ *
+ * @param {HoneyBreakpointName} breakpoint - The name of the breakpoint to filter properties by.
+ *
+ * @returns {(context: ExecutionContext & Props) => ReturnType<typeof css>} -
+ *   A function that takes an execution context and properties, and returns a CSS block
+ *   with styles generated for the specified breakpoint.
  */
-export declare const generateStyles: <Props extends HTMLAttributes<HTMLElement>>(breakpoint: HoneyBreakpointName) => ({ theme, ...props }: HoneyThemedProps<Props>) => import('styled-components').FlattenInterpolation<import('styled-components').ThemeProps<import('styled-components').DefaultTheme>>;
+export declare const createStyles: <Props extends HTMLAttributes<HTMLElement> & HoneyPrefixedCSSProperties>(breakpoint: HoneyBreakpointName) => ((context: ExecutionContext & Props) => ReturnType<typeof css>);
 /**
  * Utility function that returns functions for generating media queries for the specified breakpoint.
  * The down function creates a media query for screen sizes smaller than the breakpoint,
@@ -66,16 +79,25 @@ export declare const generateStyles: <Props extends HTMLAttributes<HTMLElement>>
  * @param {HoneyBreakpointName} breakpoint - The name of the breakpoint.
  * @param {HoneyCSSMediaRule} [ruleOptions={}] - Additional options for the media rule.
  *
- * @returns Functions for generating media queries.
+ * @returns Styled functions for generating media queries.
  */
 export declare const bpMedia: (breakpoint: HoneyBreakpointName, ruleOptions?: Omit<HoneyCSSMediaRule, "width" | "minWidth" | "maxWidth">) => {
-    down: ({ theme }: HoneyThemedProps) => string;
-    up: ({ theme }: HoneyThemedProps) => string;
+    down: StyleFunction<object>;
+    up: StyleFunction<object>;
 };
 /**
- * Generates media query styles based on the provided breakpoint and props.
+ * Applies CSS styles wrapped in a media query for the specified breakpoint based on the provided properties.
+ * If no styles are found for the specified breakpoint or if the breakpoint configuration is missing,
+ * it returns `null`. Otherwise, it generates media query styles using the `createStyles` function.
+ *
+ * @template Props - The type representing HTML attributes and Honey-prefixed CSS properties.
+ *
+ * @param {HoneyBreakpointName} breakpoint - The name of the breakpoint to apply media query styles for.
+ *
+ * @returns {(context: ExecutionContext & Props) => Nullable<ReturnType<typeof css>>} - A function that takes context and properties
+ *   and returns a CSS block wrapped in a media query if styles exist for the specified breakpoint; otherwise, returns `null`.
  */
-export declare const generateMediaStyles: <Props extends HoneyCSSProperties>(breakpoint: HoneyBreakpointName) => ({ theme, ...props }: HoneyThemedProps<Props>) => import('styled-components').FlattenInterpolation<import('styled-components').ThemedStyledProps<HTMLAttributes<HTMLElement>, import('styled-components').DefaultTheme>> | null;
+export declare const applyBreakpointStyles: <Props extends HTMLAttributes<HTMLElement> & HoneyPrefixedCSSProperties>(breakpoint: HoneyBreakpointName) => ((context: ExecutionContext & Props) => Nullable<ReturnType<typeof css>>);
 /**
  * Resolves the current screen state based on the window's dimensions and the breakpoints provided in the theme.
  *
@@ -96,4 +118,3 @@ export declare const generateMediaStyles: <Props extends HoneyCSSProperties>(bre
  *  - `isXl`: Whether the screen width is less than the 'xl' breakpoint.
  */
 export declare const resolveScreenState: (breakpoints: Partial<HoneyBreakpoints> | undefined) => HoneyScreenState;
-export {};

package/dist/hooks/use-honey-drag.d.ts

@@ -9,17 +9,27 @@ import { Nullable } from '../types';
 export type HoneyDragOnStartHandler<Element extends HTMLElement> = (draggableElement: Element) => void | boolean;
 /**
  * Context provided to the move handler, containing information about the drag's movement.
- *
- * Note:
- * - `deltaX` and `deltaY` represent the movement since the last frame.
- * - `distanceX` and `distanceY` represent the total movement from the starting position.
- * - `euclideanDistance` is the straight-line distance from the start position to the current position.
  */
 type HoneyDragMoveContext = {
+    /**
+     * The horizontal distance has moved since the last frame.
+     */
     deltaX: number;
+    /**
+     * The vertical distance has moved since the last frame.
+     */
     deltaY: number;
+    /**
+     * The total horizontal distance from the starting position to the current position.
+     */
     distanceX: number;
+    /**
+     * The total vertical distance from the starting position to the current position.
+     */
     distanceY: number;
+    /**
+     * The straight-line distance from the starting position to the current position.
+     */
     euclideanDistance: number;
 };
 /**
@@ -30,15 +40,23 @@ type HoneyDragMoveContext = {
 export type HoneyDragOnMoveHandler<Element extends HTMLElement> = (draggableElement: Element) => (context: HoneyDragMoveContext) => void | false;
 /**
  * Context provided to the end handler, containing information about the drag's end state.
- *
- * Note:
- * - `deltaX` and `deltaY` represent the total movement from the start position to the end position.
- * - `movingSpeedX` and `movingSpeedY` represent the speed of movement in the X and Y directions, respectively.
  */
 type HoneyDragEndContext = {
+    /**
+     * The total horizontal movement from the starting position to the ending position.
+     */
     deltaX: number;
+    /**
+     * The total vertical movement from the starting position to the ending position.
+     */
     deltaY: number;
+    /**
+     * The speed of movement in the horizontal direction (X axis).
+     */
     movingSpeedX: number;
+    /**
+     * The speed of movement in the vertical direction (Y axis).
+     */
     movingSpeedY: number;
 };
 /**
@@ -47,25 +65,46 @@ type HoneyDragEndContext = {
  */
 export type HoneyDragOnEndHandler<Element extends HTMLElement> = (context: HoneyDragEndContext, draggableElement: Element) => void;
 /**
- * The set of handlers that can be passed to the hook.
- *
- * Note:
- * - `onStartDrag` is optional and handles the start of the drag.
- * - `onMoveDrag` is required and handles the drag movement.
- * - `onEndDrag` is optional and handles the end of the drag.
+ * Object containing the handlers for various stages of the drag operation.
+ * These handlers can be customized to manage the behavior of the drag process.
  */
 export type HoneyDragHandlers<Element extends HTMLElement> = {
+    /**
+     * Optional handler triggered when the drag operation starts.
+     * This can be used to capture the initial state or perform setup actions.
+     */
     onStartDrag?: HoneyDragOnStartHandler<Element>;
+    /**
+     * Required handler triggered continuously during the drag operation.
+     * This handles updating the drag state and typically tracks the element's movement.
+     */
     onMoveDrag: HoneyDragOnMoveHandler<Element>;
+    /**
+     * Optional handler triggered when the drag operation ends.
+     * This can be used for cleanup or finalizing the state after the drag ends.
+     */
     onEndDrag?: HoneyDragOnEndHandler<Element>;
 };
+/**
+ * Options passed to the `useHoneyDrag` hook.
+ */
+export type HoneyDragOptions = {
+    /**
+     * Determines whether the drag functionality is enabled or not.
+     *
+     * @default true
+     */
+    isEnabled?: boolean;
+};
 /**
  * A hook that provides touch and mouse-based dragging functionality for an element.
- * It tracks touch and mouse events, calculates dragging speed and distances during the drag,
- * and exposes `onStartDrag`, `onMoveDrag`, and `onEndDrag` callbacks to handle various stages of dragging.
+ * It tracks the movement of the element during the drag process and exposes handlers for each stage of the drag operation.
+ *
+ * @template Element - The type of the HTML element that is being dragged.
  *
- * @param {MutableRefObject<Element>} draggableElementRef - A `ref` to the element that should be made draggable.
- * @param {HoneyDragHandlers<Element>} handlers - An object containing the callback functions for different dragging stages.
+ * @param {MutableRefObject<Nullable<Element>>} draggableElementRef - A reference to the element that can be dragged.
+ * @param {HoneyDragHandlers<Element>} handlers - The drag event handlers for different stages of the drag operation (start, move, end).
+ * @param {HoneyDragOptions} options - Configuration options.
  */
-export declare const useHoneyDrag: <Element extends HTMLElement>(draggableElementRef: MutableRefObject<Nullable<Element>>, { onMoveDrag, onStartDrag, onEndDrag }: HoneyDragHandlers<Element>) => void;
+export declare const useHoneyDrag: <Element extends HTMLElement>(draggableElementRef: MutableRefObject<Nullable<Element>>, { onMoveDrag, onStartDrag, onEndDrag }: HoneyDragHandlers<Element>, { isEnabled }?: HoneyDragOptions) => void;
 export {};

package/dist/hooks/use-honey-infinite-scroll.d.ts

@@ -1,7 +1,6 @@
-import { MutableRefObject } from 'react';
 import { Nullable } from '../types';
 export type UseHoneyInfiniteScrollOnFetchMoreItems = () => void;
-export declare const useHoneyInfiniteScroll: <ScrollableContainerElement extends HTMLElement, TargetElement extends HTMLElement>(containerRef: MutableRefObject<Nullable<ScrollableContainerElement>> | undefined, onFetchMoreItems: UseHoneyInfiniteScrollOnFetchMoreItems) => {
+export declare const useHoneyInfiniteScroll: <ScrollableContainerElement extends HTMLElement, TargetElement extends HTMLElement>(containerElement: Nullable<ScrollableContainerElement>, onFetchMoreItems: UseHoneyInfiniteScrollOnFetchMoreItems) => {
     scrollableContainerRef: (scrollableContainer: Nullable<ScrollableContainerElement>) => void;
     targetRef: (target: Nullable<TargetElement>) => void;
 };

package/dist/hooks/use-honey-media-query.d.ts

@@ -1,14 +1,21 @@
 import { HoneyScreenState } from '../types';
-type UseHoneyMediaQueryOptions = {
+export type UseHoneyMediaQueryOptions = {
     /**
      * The delay in milliseconds before the resize event is processed.
      *
      * @default 0
      */
     delay?: number;
+    /**
+     * Manually override screen state properties like isXs, isPortrait, etc.
+     *
+     * @remarks
+     * These values are only set once on initialization and will not dynamically update the state.
+     */
+    overrideScreenState?: Partial<HoneyScreenState>;
 };
 /**
- * A custom hook that tracks the current screen state based on the theme's media breakpoints.
+ * The hook that tracks the current screen state based on the theme's media breakpoints.
  * It updates the state on window resize and orientation change.
  *
  * @param options - Optional configuration object.
@@ -16,5 +23,4 @@ type UseHoneyMediaQueryOptions = {
  * @returns The current screen state, indicating the orientation (portrait or landscape)
  *          and the active breakpoint (xs, sm, md, lg, xl).
  */
-export declare const useHoneyMediaQuery: ({ delay }?: UseHoneyMediaQueryOptions) => HoneyScreenState;
-export {};
+export declare const useHoneyMediaQuery: ({ delay, overrideScreenState, }?: UseHoneyMediaQueryOptions) => HoneyScreenState;

package/dist/hooks/use-honey-synthetic-scrollable-container.d.ts

@@ -16,8 +16,6 @@ type SyntheticScrollableContainerOptions<Element extends HTMLElement> = Pick<Hon
  *
  * @param {MutableRefObject<Nullable<Element>>} scrollableContainerRef - A ref to the scrollable container element to be assigned to the target element.
  * @param {SyntheticScrollableContainerOptions<Element>} options - Options for configuring the synthetic scrollable container.
- *
- * @returns {MutableRefObject<Nullable<Element>>} - A ref to the scrollable container element that should be assigned to the target element.
  */
-export declare const useHoneySyntheticScrollableContainer: <Element extends HTMLElement>(scrollableContainerRef: MutableRefObject<Nullable<Element>>, { availableWindowPercentage, onStartDrag, onEndDrag, }?: SyntheticScrollableContainerOptions<Element>) => MutableRefObject<Nullable<Element>>;
+export declare const useHoneySyntheticScrollableContainer: <Element extends HTMLElement>(scrollableContainerRef: MutableRefObject<Nullable<Element>>, { availableWindowPercentage, onStartDrag, onEndDrag, }?: SyntheticScrollableContainerOptions<Element>) => void;
 export {};