@grapp/stacks

Stacks is a set of components designed for building layouts in React Native, powered by React Native Unistyles. It provides tools to manage layouts effortlessly across web, mobile, and desktop platforms.

Key features include:

• Compatibility: Works across web, mobile, and desktop via Unistyles.
• Design Flexibility: Enables designer-centric layout creation, allowing you to eliminate manual margins and distribute content evenly.
• Debug Mode: Includes a built-in debug mode to quickly investigate and identify visual UI issues.
• Design Grid: Provides a design grid component to help align and organize content.
• Responsive Props: Supports responsive prop formats, allowing you to customize spacing, column counts, or alignments based on screen size.

The Tiles component is used to display a grid of elements with equal spacing. It is built on top of the Box component and allows for responsive control over columns and spacing.

Key features include:

• columns: Control the number of columns per screen size.
• space: Adjust the general spacing between tiles.
• fill: When set to true, it fills empty slots in the last row if the number of items is less than the defined columns count.

import { Tiles } from '@grapp/stacks'; // Note: Import path assumed based on package name

// Basic usage example
<Tiles columns={3} space={10}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Tiles>

Stacks uses Unistyles as a core dependency to handle styling. By leveraging Unistyles, Stacks provides the following capabilities:

• Responsive Design: Support for media queries and defined breakpoints to adapt layouts to different screen sizes.
• Variants: Easy creation of different component versions based on specific conditions.
• Cross-Platform Compatibility: Full compatibility with React Native Web, allowing for single-codebase development for both mobile and web.
• High Performance: Optimized for speed, which is critical for mobile application responsiveness.

The Inline component is used to arrange children side-by-side horizontally. It automatically wraps children to the next line if they exceed the available width, maintaining equal spacing between them. It is built on top of the Box component.

import { Inline } from '@grapp/stacks'; // Assuming standard export pattern

<Inline>
  <Item />
  <Item />
  <Item />
</Inline>

The Bleed component creates a container with negative margins, allowing its content to visually extend beyond the boundaries of its parent container. This is useful for breaking out of a layout without refactoring the parent component tree.

It is the functional opposite of the Inset component; while Inset adds padding to keep content within boundaries, Bleed uses negative margins to push content outward.

Stack is a layout component designed to position child elements with consistent spacing. By default, it arranges children vertically.

Key capabilities include:

• Vertical Spacing: Automatically applies equal spacing between children using the space prop.
• Horizontal Layout: Switch from vertical to horizontal arrangement using the horizontal prop.
• Alignment: Control how children are aligned (left, right, center, etc.) using the align prop.
• Dividers: Insert a custom element (like a line or separator) between every child using the divider prop.

// Example of a vertical stack with spacing and a divider
<Stack space={16} divider={<DividerLine />}>
  <ChildA />
  <ChildB />
  <ChildC />
</Stack>

// Example of a horizontal stack with alignment
<Stack horizontal align="center" space={10}>
  <ChildA />
  <ChildB />
</Stack>

The Box component is a fundamental layout element that renders a single React Native View. It is used to create containers and manage spacing, alignment, and sizing. It extends all standard React Native View props and adds specialized layout props like padding, margin, gap, and alignX/alignY to simplify layout creation.

import { Box } from '@grapp/stacks';

// Basic usage as a container
<Box padding={2} margin={4}>
  {/* children */}
</Box>

The Rows component organizes its children into rows with consistent vertical spacing. It is a foundational component often used for building layouts like a Screen component.

Key layout capabilities include:

• Vertical Alignment: Use alignY to align rows vertically if they have varying heights.
• Horizontal Alignment: Use alignX to align rows horizontally when their total width is less than the parent container.
• Flex Control: You can set a defaultFlex on the Rows component to apply a flex value to all rows, or place a Row directly inside Rows and set its individual flex property.

// Example of setting default flex for all rows
<Rows defaultFlex="1">
  <Row>Row 1</Row>
  <Row>Row 2</Row>
</Rows>

Columns is a layout component used to organize content horizontally with consistent spacing.

Key behaviors:

• Width Control: By default, all columns have equal width. You can assign fractional flex values (up to 1/5) for precise control, or use the value content to make a column only as wide as its content.
• Vertical Alignment: Use alignY to align columns with varying content heights.
• Horizontal Alignment: Use alignX to align columns when their total width is less than the parent container.
• Reversing Order: Use the reverse prop to flip the display order of columns.
• Responsive Stacking: Use collapseBelow to stack columns vertically when the viewport width is smaller than a specified breakpoint.

// Example usage patterns
<Columns alignY="center" alignX="space-between" reverse />
<Columns collapseBelow="sm" />