@idealyst/components 1.2.98 → 1.2.99

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/components",
-  "version": "1.2.98",
+  "version": "1.2.99",
   "description": "Shared component library for React and React Native",
   "documentation": "https://github.com/IdealystIO/idealyst-framework/tree/main/packages/components#readme",
   "readme": "README.md",
@@ -56,7 +56,7 @@
     "publish:npm": "npm publish"
   },
   "peerDependencies": {
-    "@idealyst/theme": "^1.2.98",
+    "@idealyst/theme": "^1.2.99",
     "@mdi/js": ">=7.0.0",
     "@mdi/react": ">=1.0.0",
     "@react-native-vector-icons/common": ">=12.0.0",
@@ -107,8 +107,8 @@
   },
   "devDependencies": {
     "@idealyst/blur": "^1.2.40",
-    "@idealyst/theme": "^1.2.98",
-    "@idealyst/tooling": "^1.2.98",
+    "@idealyst/theme": "^1.2.99",
+    "@idealyst/tooling": "^1.2.99",
     "@mdi/react": "^1.6.1",
     "@types/react": "^19.1.0",
     "react": "^19.1.0",

package/src/Grid/Grid.native.tsx

@@ -0,0 +1,102 @@
+import React, { forwardRef, useMemo, Children } from 'react';
+import { View } from 'react-native';
+import { useResponsiveStyle, isResponsiveValue, Responsive } from '@idealyst/theme';
+import { UnistylesRuntime } from 'react-native-unistyles';
+import { GridProps } from './types';
+import { gridStyles } from './Grid.styles';
+import type { IdealystElement } from '../utils/refTypes';
+
+/**
+ * Resolve a responsive number value to a concrete number for the current breakpoint.
+ */
+function useResolvedColumns(columns: Responsive<number>): number {
+    const resolved = useResponsiveStyle(
+        isResponsiveValue(columns)
+            ? { zIndex: columns as any }
+            : {}
+    );
+
+    if (isResponsiveValue(columns)) {
+        return (resolved.zIndex as number) ?? 1;
+    }
+
+    return columns;
+}
+
+/**
+ * Get the gap value in pixels from the theme for a given size key.
+ */
+function getGapPixels(size: string): number {
+    const theme = UnistylesRuntime.getTheme();
+    const sizes = (theme as any).sizes?.view;
+    return sizes?.[size]?.spacing ?? 16;
+}
+
+/**
+ * Grid component for React Native.
+ *
+ * Uses flexbox wrapping with calculated percentage widths to simulate
+ * a grid layout. Each child is wrapped in a cell view that handles sizing.
+ */
+const Grid = forwardRef<IdealystElement, GridProps>(({
+    children,
+    columns = 1,
+    gap = 'md',
+    padding,
+    paddingVertical,
+    paddingHorizontal,
+    margin,
+    marginVertical,
+    marginHorizontal,
+    style,
+    testID,
+    id,
+    onLayout,
+}, ref) => {
+    const resolvedColumns = useResolvedColumns(columns);
+    const gapPx = getGapPixels(gap);
+
+    gridStyles.useVariants({
+        gap,
+        padding,
+        paddingVertical,
+        paddingHorizontal,
+        margin,
+        marginVertical,
+        marginHorizontal,
+    });
+
+    // Calculate cell width accounting for gaps between columns.
+    // Total gap space = gapPx * (columns - 1), divided equally among all columns.
+    const cellStyle = useMemo(() => {
+        const totalGapSpace = gapPx * (resolvedColumns - 1);
+        return {
+            flexBasis: `${((1 / resolvedColumns) * 100).toFixed(4)}%` as any,
+            maxWidth: `${((1 / resolvedColumns) * 100).toFixed(4)}%` as any,
+            // Subtract proportional gap from each cell using negative margin + padding trick
+            // is fragile, so we use the gap property on the container which RN supports.
+        };
+    }, [resolvedColumns, gapPx]);
+
+    const items = Children.toArray(children);
+
+    return (
+        <View
+            ref={ref as any}
+            style={[gridStyles.grid as any, style]}
+            testID={testID}
+            nativeID={id}
+            onLayout={onLayout}
+        >
+            {items.map((child, index) => (
+                <View key={(child as any).key ?? index} style={cellStyle}>
+                    {child}
+                </View>
+            ))}
+        </View>
+    );
+});
+
+Grid.displayName = 'Grid';
+
+export default Grid;

package/src/Grid/Grid.styles.tsx

@@ -0,0 +1,56 @@
+import { StyleSheet } from 'react-native-unistyles';
+import { defineStyle, ThemeStyleWrapper } from '@idealyst/theme';
+import type { Theme as BaseTheme } from '@idealyst/theme';
+import { ViewStyleSize } from '../utils/viewStyleProps';
+
+// Required: Unistyles must see StyleSheet usage in original source
+void StyleSheet;
+
+type Theme = ThemeStyleWrapper<BaseTheme>;
+
+export type GridVariants = {
+    gap: ViewStyleSize;
+    padding: ViewStyleSize;
+    paddingVertical: ViewStyleSize;
+    paddingHorizontal: ViewStyleSize;
+    margin: ViewStyleSize;
+    marginVertical: ViewStyleSize;
+    marginHorizontal: ViewStyleSize;
+};
+
+export const gridStyles = defineStyle('Grid', (theme: Theme) => ({
+    grid: {
+        // Theme marker for Unistyles reactivity
+        borderColor: theme.colors.border.primary,
+        borderWidth: 0,
+        flexDirection: 'row' as const,
+        flexWrap: 'wrap' as const,
+        variants: {
+            gap: {
+                gap: theme.sizes.$view.spacing,
+            },
+            padding: {
+                padding: theme.sizes.$view.padding,
+            },
+            paddingVertical: {
+                paddingVertical: theme.sizes.$view.padding,
+            },
+            paddingHorizontal: {
+                paddingHorizontal: theme.sizes.$view.padding,
+            },
+            margin: {
+                margin: theme.sizes.$view.padding,
+            },
+            marginVertical: {
+                marginVertical: theme.sizes.$view.padding,
+            },
+            marginHorizontal: {
+                marginHorizontal: theme.sizes.$view.padding,
+            },
+        },
+        _web: {
+            display: 'grid',
+            boxSizing: 'border-box',
+        },
+    },
+}));

package/src/Grid/Grid.web.tsx

@@ -0,0 +1,88 @@
+import React, { forwardRef, useMemo } from 'react';
+import { getWebProps } from 'react-native-unistyles/web';
+import { useBreakpoint, Breakpoint } from '@idealyst/theme';
+import { GridProps, ResponsiveColumns } from './types';
+import { gridStyles } from './Grid.styles';
+import useMergeRefs from '../hooks/useMergeRefs';
+import { useWebLayout } from '../hooks/useWebLayout';
+import type { IdealystElement } from '../utils/refTypes';
+import { flattenStyle } from '../utils/flattenStyle';
+
+const BREAKPOINT_ORDER: Breakpoint[] = ['xl', 'lg', 'md', 'sm', 'xs'];
+
+function resolveColumns(columns: ResponsiveColumns, breakpoint: Breakpoint | undefined): number {
+    if (typeof columns === 'number') return columns;
+
+    const bpIndex = breakpoint ? BREAKPOINT_ORDER.indexOf(breakpoint) : BREAKPOINT_ORDER.length - 1;
+    for (let i = bpIndex; i < BREAKPOINT_ORDER.length; i++) {
+        const bp = BREAKPOINT_ORDER[i];
+        if (columns[bp] !== undefined) {
+            return columns[bp]!;
+        }
+    }
+
+    return 1;
+}
+
+/**
+ * Grid component for Web.
+ *
+ * Uses CSS Grid for efficient, native grid layout with responsive column counts.
+ */
+const Grid = forwardRef<IdealystElement, GridProps>(({
+    children,
+    columns = 1,
+    gap: gapProp = 'md',
+    padding,
+    paddingVertical,
+    paddingHorizontal,
+    margin,
+    marginVertical,
+    marginHorizontal,
+    style,
+    testID,
+    id,
+    onLayout,
+}, ref) => {
+    const layoutRef = useWebLayout<HTMLDivElement>(onLayout);
+    const breakpoint = useBreakpoint();
+
+    const resolvedColumns = useMemo(
+        () => resolveColumns(columns, breakpoint),
+        [columns, breakpoint]
+    );
+
+    gridStyles.useVariants({
+        gap: gapProp,
+        padding,
+        paddingVertical,
+        paddingHorizontal,
+        margin,
+        marginVertical,
+        marginHorizontal,
+    });
+
+    const webProps = getWebProps([gridStyles.grid, flattenStyle(style)]);
+    const mergedRef = useMergeRefs(ref, webProps.ref, layoutRef);
+
+    const gridTemplateColumns = `repeat(${resolvedColumns}, 1fr)`;
+
+    return (
+        <div
+            {...webProps}
+            ref={mergedRef as any}
+            id={id}
+            data-testid={testID}
+            style={{
+                ...webProps.style,
+                gridTemplateColumns,
+            }}
+        >
+            {children}
+        </div>
+    );
+});
+
+Grid.displayName = 'Grid';
+
+export default Grid;

package/src/Grid/index.native.ts

@@ -0,0 +1,2 @@
+export { default } from './Grid.native';
+export * from './types';

package/src/Grid/index.ts

@@ -0,0 +1,5 @@
+import GridComponent from './Grid.web';
+
+export default GridComponent;
+export { GridComponent as Grid };
+export * from './types';

package/src/Grid/index.web.ts

@@ -0,0 +1,5 @@
+import GridComponent from './Grid.web';
+
+export default GridComponent;
+export { GridComponent as Grid };
+export * from './types';

package/src/Grid/types.ts

@@ -0,0 +1,73 @@
+import { Size } from '@idealyst/theme';
+import type { Breakpoint } from '@idealyst/theme';
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { ContainerStyleProps } from '../utils/viewStyleProps';
+import type { LayoutChangeEvent } from '../hooks/useWebLayout';
+
+export type { LayoutChangeEvent };
+
+/**
+ * Responsive column count - either a fixed number or a breakpoint map.
+ *
+ * @example
+ * ```tsx
+ * // Fixed columns
+ * <Grid columns={3} />
+ *
+ * // Responsive columns
+ * <Grid columns={{ xs: 1, sm: 2, lg: 4 }} />
+ * ```
+ */
+export type ResponsiveColumns = number | Partial<Record<Breakpoint, number>>;
+
+/**
+ * Gap size between grid items. Uses theme spacing values.
+ */
+export type GridGap = Size;
+
+/**
+ * Cross-platform grid layout component.
+ *
+ * Arranges children into columns with consistent gap spacing.
+ * Supports responsive column counts that adapt to screen size.
+ *
+ * - **Web**: Uses CSS Grid for optimal layout performance.
+ * - **Native**: Uses percentage-based widths with flexbox wrapping.
+ *
+ * @example
+ * ```tsx
+ * <Grid columns={{ xs: 1, sm: 2, lg: 4 }} gap="md">
+ *   <Card>Item 1</Card>
+ *   <Card>Item 2</Card>
+ *   <Card>Item 3</Card>
+ *   <Card>Item 4</Card>
+ * </Grid>
+ * ```
+ */
+export interface GridProps extends ContainerStyleProps {
+  /** Grid content - each direct child becomes a grid item */
+  children?: ReactNode;
+
+  /**
+   * Number of columns. Can be a fixed number or responsive breakpoint map.
+   * @default 1
+   */
+  columns?: ResponsiveColumns;
+
+  /**
+   * Gap between grid items (both rows and columns).
+   * Uses theme spacing values (theme.sizes.view[size].spacing).
+   * @default 'md'
+   */
+  gap?: GridGap;
+
+  /** Additional styles applied to the grid container */
+  style?: StyleProp<ViewStyle>;
+
+  /** Test ID for testing */
+  testID?: string;
+
+  /** Called when the grid's layout changes */
+  onLayout?: (event: LayoutChangeEvent) => void;
+}

package/src/Progress/Progress.native.tsx

@@ -41,10 +41,8 @@ const Progress = forwardRef<IdealystElement, ProgressProps>(({
     rounded,
   });
 
-  // Compute dynamic styles with intent
-  const dynamicProps = { intent };
-  const linearBarStyle = (progressStyles.linearBar as any)(dynamicProps);
-  const indeterminateBarStyle = (progressStyles.indeterminateBar as any)(dynamicProps);
+  const linearBarStyle = (progressStyles.linearBar as any);
+  const indeterminateBarStyle = (progressStyles.indeterminateBar as any);
 
   // Animation values
   const animatedValue = useSharedValue(0);
@@ -163,8 +161,8 @@ const Progress = forwardRef<IdealystElement, ProgressProps>(({
   });
 
   // Get dynamic styles for extended styles
-  const containerStyle = (progressStyles.container as any)({});
-  const linearTrackStyle = (progressStyles.linearTrack as any)({});
+  const containerStyle = (progressStyles.container as any);
+  const linearTrackStyle = (progressStyles.linearTrack as any);
 
   return (
     <View ref={ref as any} nativeID={id} style={[containerStyle, style]} testID={testID} accessibilityRole="progressbar">

package/src/examples/GridExamples.tsx

@@ -0,0 +1,108 @@
+import { Screen, View, Text, Card, Grid } from '../index';
+
+export const GridExamples = () => {
+  return (
+    <Screen background="primary" padding="lg">
+      <View gap="xl">
+        <Text typography="h4" align="center">
+          Grid Examples
+        </Text>
+
+        {/* Fixed Columns */}
+        <View gap="md">
+          <Text typography="subtitle1">Fixed Columns</Text>
+          <Grid columns={3} gap="md">
+            {Array.from({ length: 6 }, (_, i) => (
+              <Card key={i} type="outlined" padding="md">
+                <Text weight="medium">Item {i + 1}</Text>
+              </Card>
+            ))}
+          </Grid>
+        </View>
+
+        {/* Responsive Columns */}
+        <View gap="md">
+          <Text typography="subtitle1">Responsive Columns</Text>
+          <Text typography="caption" color="secondary">
+            1 col on mobile, 2 on tablet, 4 on desktop
+          </Text>
+          <Grid columns={{ xs: 1, sm: 2, lg: 4 }} gap="md">
+            {Array.from({ length: 8 }, (_, i) => (
+              <Card key={i} type="elevated" padding="md">
+                <Text weight="medium">Card {i + 1}</Text>
+                <Text typography="caption" color="secondary">Responsive</Text>
+              </Card>
+            ))}
+          </Grid>
+        </View>
+
+        {/* Gap Variants */}
+        <View gap="md">
+          <Text typography="subtitle1">Gap Variants</Text>
+
+          <Text typography="caption" color="secondary">gap="xs"</Text>
+          <Grid columns={4} gap="xs">
+            {Array.from({ length: 4 }, (_, i) => (
+              <Card key={i} type="outlined" padding="sm">
+                <Text typography="caption">XS</Text>
+              </Card>
+            ))}
+          </Grid>
+
+          <Text typography="caption" color="secondary">gap="md"</Text>
+          <Grid columns={4} gap="md">
+            {Array.from({ length: 4 }, (_, i) => (
+              <Card key={i} type="outlined" padding="sm">
+                <Text typography="caption">MD</Text>
+              </Card>
+            ))}
+          </Grid>
+
+          <Text typography="caption" color="secondary">gap="xl"</Text>
+          <Grid columns={4} gap="xl">
+            {Array.from({ length: 4 }, (_, i) => (
+              <Card key={i} type="outlined" padding="sm">
+                <Text typography="caption">XL</Text>
+              </Card>
+            ))}
+          </Grid>
+        </View>
+
+        {/* Dashboard Layout */}
+        <View gap="md">
+          <Text typography="subtitle1">Dashboard Layout</Text>
+          <Grid columns={{ xs: 1, md: 2, lg: 4 }} gap="md">
+            <Card type="elevated" padding="md">
+              <Text typography="caption" color="secondary">Revenue</Text>
+              <Text typography="h3" weight="bold">$12,345</Text>
+            </Card>
+            <Card type="elevated" padding="md">
+              <Text typography="caption" color="secondary">Users</Text>
+              <Text typography="h3" weight="bold">1,234</Text>
+            </Card>
+            <Card type="elevated" padding="md">
+              <Text typography="caption" color="secondary">Orders</Text>
+              <Text typography="h3" weight="bold">567</Text>
+            </Card>
+            <Card type="elevated" padding="md">
+              <Text typography="caption" color="secondary">Growth</Text>
+              <Text typography="h3" weight="bold">+12%</Text>
+            </Card>
+          </Grid>
+        </View>
+
+        {/* Grid with Padding */}
+        <View gap="md">
+          <Text typography="subtitle1">Grid with Padding</Text>
+          <Grid columns={2} gap="sm" padding="lg">
+            {Array.from({ length: 4 }, (_, i) => (
+              <Card key={i} type="outlined" padding="md">
+                <Text>Padded Item {i + 1}</Text>
+              </Card>
+            ))}
+          </Grid>
+        </View>
+      </View>
+    </Screen>
+  );
+};

package/src/examples/index.ts

@@ -32,4 +32,5 @@ export { AlertExamples } from './AlertExamples';
 export { SkeletonExamples } from './SkeletonExamples';
 export { ChipExamples } from './ChipExamples';
 export { BreadcrumbExamples } from './BreadcrumbExamples';
+export { GridExamples } from './GridExamples';
 export { ThemeExtensionExamples } from './ThemeExtensionExamples';

package/src/index.native.ts

@@ -89,6 +89,9 @@ export * from './Table/types';
 export { default as Menu } from './Menu';
 export * from './Menu/types';
 
+export { default as Grid } from './Grid';
+export * from './Grid/types';
+
 export { default as Image } from './Image';
 export * from './Image/types';
 
@@ -144,6 +147,7 @@ export type { AccordionProps, AccordionItem } from './Accordion/types';
 export type { ListProps, ListItemProps, ListSectionProps } from './List/types';
 export type { TableProps, TableColumn } from './Table/types';
 export type { MenuProps, MenuItem } from './Menu/types';
+export type { GridProps, ResponsiveColumns, GridGap } from './Grid/types';
 export type { ImageProps } from './Image/types';
 export type { VideoProps, VideoSource } from './Video/types';
 export type { AlertProps } from './Alert/types';

package/src/index.ts

@@ -100,6 +100,9 @@ export * from './Table/types';
 export { default as Menu } from './Menu';
 export * from './Menu/types';
 
+export { default as Grid } from './Grid';
+export * from './Grid/types';
+
 export { default as Image } from './Image';
 export * from './Image/types';
 
@@ -154,6 +157,7 @@ export type { AccordionProps, AccordionItem } from './Accordion/types';
 export type { ListProps, ListItemProps, ListSectionProps } from './List/types';
 export type { TableProps, TableColumn } from './Table/types';
 export type { MenuProps, MenuItem } from './Menu/types';
+export type { GridProps, ResponsiveColumns, GridGap } from './Grid/types';
 export type { ImageProps } from './Image/types';
 export type { VideoProps, VideoSource } from './Video/types';
 export type { AlertProps } from './Alert/types';