entangle-ui 0.2.0 → 0.4.0

package/dist/types/components/layout/Flex/Flex.d.ts

@@ -0,0 +1,215 @@
+import React from 'react';
+import { BaseComponent } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+
+/**
+ * Flex direction options
+ */
+type FlexDirection = 'row' | 'row-reverse' | 'column' | 'column-reverse';
+/**
+ * Flex wrap options
+ */
+type FlexWrap = 'nowrap' | 'wrap' | 'wrap-reverse';
+/**
+ * Justify content options
+ */
+type FlexJustify = 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly';
+/**
+ * Align items options
+ */
+type FlexAlign = 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline';
+/**
+ * Align content options (for wrapped flex containers)
+ */
+type FlexAlignContent = 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'space-between' | 'space-around';
+/**
+ * Spacing multiplier (0-8) based on theme spacing unit
+ */
+type FlexSpacing = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+interface FlexBaseProps extends BaseComponent<HTMLDivElement> {
+    /**
+     * Flex content - any React elements
+     */
+    children?: React.ReactNode;
+    /**
+     * Flex direction - controls main axis orientation
+     * - `row`: Left to right (default)
+     * - `row-reverse`: Right to left
+     * - `column`: Top to bottom
+     * - `column-reverse`: Bottom to top
+     * @default "row"
+     */
+    direction?: FlexDirection | undefined;
+    /**
+     * Responsive flex direction
+     * Allows different directions at different breakpoints
+     */
+    sm?: FlexDirection | undefined;
+    md?: FlexDirection | undefined;
+    lg?: FlexDirection | undefined;
+    xl?: FlexDirection | undefined;
+    /**
+     * Flex wrap behavior
+     * - `nowrap`: Items stay on one line (default)
+     * - `wrap`: Items wrap to new lines as needed
+     * - `wrap-reverse`: Items wrap in reverse order
+     * @default "nowrap"
+     */
+    wrap?: FlexWrap | undefined;
+    /**
+     * Justify content - distributes space along main axis
+     * - `flex-start`: Items packed to start (default)
+     * - `flex-end`: Items packed to end
+     * - `center`: Items centered
+     * - `space-between`: Even space between items
+     * - `space-around`: Even space around items
+     * - `space-evenly`: Equal space between and around items
+     * @default "flex-start"
+     */
+    justify?: FlexJustify | undefined;
+    /**
+     * Align items - aligns items along cross axis
+     * - `stretch`: Items stretch to fill container (default)
+     * - `flex-start`: Items align to start of cross axis
+     * - `flex-end`: Items align to end of cross axis
+     * - `center`: Items centered on cross axis
+     * - `baseline`: Items align to text baseline
+     * @default "stretch"
+     */
+    align?: FlexAlign | undefined;
+    /**
+     * Align content - aligns wrapped lines
+     * Only applies when wrap is enabled and there are multiple lines
+     * - `stretch`: Lines stretch to fill container (default)
+     * - `flex-start`: Lines packed to start
+     * - `flex-end`: Lines packed to end
+     * - `center`: Lines centered
+     * - `space-between`: Even space between lines
+     * - `space-around`: Even space around lines
+     * @default "stretch"
+     */
+    alignContent?: FlexAlignContent | undefined;
+    /**
+     * Gap between flex items (multiplier of base spacing unit)
+     * - `0`: No gap (0px)
+     * - `1`: 1x base unit (4px)
+     * - `2`: 2x base unit (8px)
+     * - `3`: 3x base unit (12px)
+     * - `4`: 4x base unit (16px)
+     * @default 0
+     */
+    gap?: FlexSpacing | undefined;
+    /**
+     * Custom gap override (CSS value)
+     * Overrides gap prop if provided
+     * @example "16px", "1rem", "2rem 1rem"
+     */
+    customGap?: string | number | undefined;
+    /**
+     * Flex grow - how much item should grow
+     * @default 0
+     */
+    grow?: number | undefined;
+    /**
+     * Flex shrink - how much item should shrink
+     * @default 1
+     */
+    shrink?: number | undefined;
+    /**
+     * Flex basis - initial size before free space is distributed
+     * @example "auto", "100px", "50%", "0"
+     * @default "auto"
+     */
+    basis?: string | number | undefined;
+    /**
+     * Whether this flex container should fill available width
+     * @default false
+     */
+    fullWidth?: boolean;
+    /**
+     * Whether this flex container should fill available height
+     * @default false
+     */
+    fullHeight?: boolean;
+    /**
+     * Minimum height for the flex container
+     * @example "100vh", "300px", "50%"
+     */
+    minHeight?: string | number | undefined;
+    /**
+     * Maximum width for the flex container
+     * @example "1200px", "100%", "50vw"
+     */
+    maxWidth?: string | number | undefined;
+}
+/**
+ * Props for the Flex component with prettified type for better IntelliSense
+ */
+type FlexProps = Prettify<FlexBaseProps>;
+/**
+ * A comprehensive flexbox component providing full control over flex properties.
+ *
+ * More powerful than Stack for complex layouts requiring precise flexbox control.
+ * Supports all flexbox properties, responsive direction changes, and flexible sizing.
+ * Perfect for complex layouts, navigation bars, form layouts, and sophisticated arrangements.
+ *
+ * @example
+ * ```tsx
+ * // Basic horizontal flex
+ * <Flex justify="space-between" align="center">
+ *   <div>Left content</div>
+ *   <div>Right content</div>
+ * </Flex>
+ *
+ * // Vertical stack with gap
+ * <Flex direction="column" gap={3}>
+ *   <Card>Item 1</Card>
+ *   <Card>Item 2</Card>
+ *   <Card>Item 3</Card>
+ * </Flex>
+ *
+ * // Responsive navigation
+ * <Flex
+ *   direction="column"
+ *   md="row"
+ *   justify="space-between"
+ *   align="center"
+ *   gap={2}
+ * >
+ *   <Logo />
+ *   <Navigation />
+ *   <UserMenu />
+ * </Flex>
+ *
+ * // Flexible form layout
+ * <Flex direction="column" gap={2} maxWidth="400px">
+ *   <Input label="Email" />
+ *   <Input label="Password" />
+ *   <Flex justify="space-between" gap={2}>
+ *     <Button fullWidth variant="ghost">Cancel</Button>
+ *     <Button fullWidth variant="filled">Login</Button>
+ *   </Flex>
+ * </Flex>
+ *
+ * // Card grid with wrapping
+ * <Flex wrap="wrap" gap={3} justify="center">
+ *   <Card basis="300px">Card 1</Card>
+ *   <Card basis="300px">Card 2</Card>
+ *   <Card basis="300px">Card 3</Card>
+ * </Flex>
+ *
+ * // Complex layout with nesting
+ * <Flex direction="column" fullHeight>
+ *   <Header />
+ *   <Flex grow={1}>
+ *     <Sidebar basis="200px" />
+ *     <MainContent grow={1} />
+ *   </Flex>
+ *   <Footer />
+ * </Flex>
+ * ```
+ */
+declare const Flex: React.FC<FlexProps>;
+
+export { Flex };
+export type { FlexAlign, FlexAlignContent, FlexBaseProps, FlexDirection, FlexJustify, FlexProps, FlexSpacing, FlexWrap };

package/dist/types/components/layout/Grid/Grid.d.ts

@@ -0,0 +1,113 @@
+import React from 'react';
+import { BaseComponent } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+
+/**
+ * Grid size variants from 1-12 columns or auto-sizing
+ */
+type GridSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 'auto';
+/**
+ * Spacing multiplier (0-8) based on theme spacing unit
+ * 0 = no spacing, 1 = 1x base unit, 2 = 2x base unit, etc.
+ */
+type GridSpacing = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+interface GridBaseProps extends Omit<BaseComponent<HTMLDivElement>, 'children'> {
+    /**
+     * Grid content - other Grid components or any React elements
+     */
+    children: React.ReactNode;
+    /**
+     * Whether this Grid acts as a container (enables CSS Grid)
+     * When true, this Grid becomes a container for child Grid items
+     * @default false
+     */
+    container?: boolean;
+    /**
+     * Grid item size (1-12 columns)
+     * Only used when this Grid is a child of a container Grid
+     * @example 6 // Takes 6 out of 12 columns (50% width)
+     */
+    size?: GridSize | undefined;
+    /**
+     * Responsive grid sizes
+     * Allows different column spans at different breakpoints
+     * @example xs={12} sm={6} md={4} // Full width on mobile, half on tablet, third on desktop
+     */
+    xs?: GridSize | undefined;
+    sm?: GridSize | undefined;
+    md?: GridSize | undefined;
+    lg?: GridSize | undefined;
+    xl?: GridSize | undefined;
+    /**
+     * Spacing between grid items (multiplier of base spacing unit)
+     * Only applies when container=true
+     * - `0`: No spacing (0px)
+     * - `1`: 1x base unit (4px)
+     * - `2`: 2x base unit (8px)
+     * - `3`: 3x base unit (12px)
+     * - `4`: 4x base unit (16px)
+     * @default 2
+     */
+    spacing?: GridSpacing | undefined;
+    /**
+     * Total number of columns in the grid
+     * Only applies when container=true
+     * @default 12
+     */
+    columns?: number | undefined;
+    /**
+     * Custom gap override (CSS value)
+     * Overrides spacing prop if provided
+     * @example "16px", "1rem", "2"
+     */
+    gap?: string | number | undefined;
+}
+/**
+ * Props for the Grid component with prettified type for better IntelliSense
+ */
+type GridProps = Prettify<GridBaseProps>;
+/**
+ * A flexible 12-column grid system component for creating responsive layouts.
+ *
+ * Supports both container and item modes. Container grids create the grid layout,
+ * while item grids define how much space each child should occupy.
+ * Built on CSS Grid for modern, flexible layouts.
+ *
+ * @example
+ * ```tsx
+ * // Basic two-column layout
+ * <Grid container spacing="md">
+ *   <Grid size={6}>Left content</Grid>
+ *   <Grid size={6}>Right content</Grid>
+ * </Grid>
+ *
+ * // Responsive three-column layout
+ * <Grid container spacing="lg">
+ *   <Grid xs={12} sm={6} md={4}>Card 1</Grid>
+ *   <Grid xs={12} sm={6} md={4}>Card 2</Grid>
+ *   <Grid xs={12} sm={12} md={4}>Card 3</Grid>
+ * </Grid>
+ *
+ * // Nested grids
+ * <Grid container spacing="md">
+ *   <Grid size={8}>
+ *     <Grid container spacing="sm">
+ *       <Grid size={6}>Nested left</Grid>
+ *       <Grid size={6}>Nested right</Grid>
+ *     </Grid>
+ *   </Grid>
+ *   <Grid size={4}>Sidebar</Grid>
+ * </Grid>
+ *
+ * // Custom gap
+ * <Grid container gap="2rem">
+ *   <Grid size={4}>Item 1</Grid>
+ *   <Grid size={4}>Item 2</Grid>
+ *   <Grid size={4}>Item 3</Grid>
+ * </Grid>
+ * ```
+ */
+declare const Grid: React.FC<GridProps>;
+
+export { Grid };
+export type { GridBaseProps, GridProps, GridSize, GridSpacing };