@fireng/layout/README.md

Angular directives for responsive layout and visual adjustments using Fireng breakpoints.

# `@fireng/layout`

## Introduction

`@fireng/layout` is a powerful Angular library that helps you build responsive layouts easily. It’s built on top of `@fireng/core` and gives you special Angular directives that wrap common CSS layout styles like `display`, `flex`, `gap`, and more.

You can use these as:

- **Atomic directives** – for single CSS properties
- **Compositional directives** – for combining multiple layout properties together (like Flexbox settings)

It uses Angular Signals to update layouts automatically when the screen size changes. Whether you're making simple containers or complex responsive UIs, `@fireng/layout` helps you write less CSS and keep your templates clean.

## Features

- **Declarative Layouts**: Set layout styles directly in your HTML using clear directive inputs.
- **Signal-Powered Reactivity**: Breakpoint changes update layouts instantly using Angular Signals.
- **Mobile-First Friendly**: Works perfectly with `@fireng/core`’s mobile-first breakpoints.
- **Type-Safe API**: Get auto-complete and error checks with fully typed directive inputs.
- **Modular Design**: Each directive focuses on one thing, which you can mix and match.
- **Less CSS Code**: Control layout from templates, no need for extra utility classes or stylesheets.

## Installation

Run this in your Angular project:

```bash
npm install @fireng/layout
```

Make sure `@fireng/core` is also installed, since it’s a required dependency.

## Quick Example: Responsive Inline Styles

Here’s a basic example showing how to style an element responsively using `fireStyle`.

```typescript
import { Component } from "@angular/core";
import { FirengStyleDirective } from "@fireng/layout"; // Import the specific directive

@Component({
  selector: "app-style-demo",
  standalone: true,
  imports: [FirengStyleDirective], // Add it to your imports
  template: ``
    <h3>Responsive Inline Styles with fireStyle</h3>
    <p>Resize your browser to see font size and alignment changes:</p>
    <span
      [fireStyle]="{
        color: 'white',
        backgroundColor: '#007bff',
        fontSize: { xs: '16px', sm: '24px' },
        padding: '10px 20px',
        borderRadius: '5px',
        textAlign: { xs: 'center', md: 'left' }
      }"
      style="display: block; width: fit-content; margin: 10px auto;"
    >
      Responsive Text
    </span>
  ``,
})
export class FirengStyleDemoComponent {}
```

## Usage

To use any directive from `@fireng/layout`, simply import it into your standalone component, module, or directive. Directives are applied directly to your HTML elements using their selectors. Responsive inputs accept either a single static value or a `FirengResponsiveMap` object from `@fireng/core` for breakpoint-specific adjustments.

### Flexbox Layouts with `FirengBoxDirective`

The `FirengBoxDirective` is a fundamental building block for creating responsive Flexbox layouts.

```ts
import { Component } from "@angular/core";
import { FirengBoxDirective } from "@fireng/layout"; // Import the compositional directive

@Component({
  selector: "app-flexbox-demo",
  standalone: true,
  imports: [FirengBoxDirective], // Add it to your imports
  template: ``
    <h3>Static Flexbox Layout</h3>
    <div fireBox display="flex" flexDirection="column" justifyContent="center" alignItems="center" gap="1rem">
      <span>Item A</span>
      <span>Item B</span>
      <span>Item C</span>
    </div>

    <h3>Responsive Flexbox Layout</h3>
    <p>Watch this container change direction and spacing on resize:</p>
    <div
      fireBox
      display="flex"
      [flexDirection]="{ xs: 'column', md: 'row' }"
      [justifyContent]="{
        xs: 'flex-start',
        md: 'space-between',
        lg: 'space-around'
      }"
      gap="2rem"
      [style]="{border: '1px dashed #007bff', padding: '10px', minHeight: '150px',}"
    >
      <span>Small Screen</span>
      <span>Medium Screen</span>
      <span>Large Screen</span>
    </div>
  ``
})
export class FlexboxDemoComponent {}
```

> **Note**: Input names follow **camelCase** (e.g. `alignItems`, `flexDirection`, etc.)

### Standalone Atomic Directive Usage

You can also use atomic directives independently for fine-grained control over individual CSS properties.

```typescript
import { Component } from '@angular/core';
import { FirengDisplayDirective, FirengGapDirective } from '@fireng/layout'; // Import atomic directives

@Component({
selector: 'app-atomic-demo',
standalone: true,
imports: [FirengDisplayDirective, FirengGapDirective], // Add them to your imports
template: ``
<h3>Standalone Atomic Directive Usage</h3>
<h3>Standalone Atomic Directive Usage</h3>
<p>This box hides on extra-small screens and shows a gap on medium screens:</p>
<div
  [fireDisplay]="{ xs: 'none', sm: 'flex' }"
  [fireGap]="{ sm: '0', md: '40px' }"
>
  <span>Element 1</span>
  <span>Element 2</span>
  <span>Element 3</span>
</div>

<p style="margin-top: 20px">
  Text below will be hidden on extra-small screens using ``fireDisplay`` on this
  span:
</p>
<span
  [fireDisplay]="{ xs: 'none', sm: 'inline' }"
  style="border: 1px dashed orange; padding: 5px"
>
  This span is only visible from small screens up.
</span>

``,
})
export class AtomicDirectiveDemoComponent {}
```

---


## Directives

### Compositional Directive

#### `FirengBoxDirective` (`[fireBox]`)

The `FirengBoxDirective` is a fundamental building block for creating responsive Flexbox layouts in Angular. It transforms any element into a Flexbox container, providing intuitive inputs to control its core layout and spacing.

- `style` → sets inline styles
- `display` → sets `display`
- `flexDirection` → sets `flex-direction`
- `flexWrap` → sets `flex-wrap`
- `justifyContent` → sets `justify-content`
- `alignItems` → sets `align-items`
- `alignContent` → sets `align-content`
- `gap` → sets `gap`

You can pass:

- A single value (like `"row"`)
- Or a responsive map (like `{ xs: 'column', md: 'row' }`)

These inputs are reactive and will update automatically when the screen size changes.
For a complete list of all accepted values, types, and detailed examples for each input, please refer to the comprehensive JSDoc comments of the corresponding atomic directive.

---


### Atomic Directives

Use these to control individual CSS properties:

- **`[fireStyle]`** – Responsive binding for inline styles like `color`, `fontSize`, etc., supporting both static and per-breakpoint values.
- **`[fireDisplay]`** – Sets the `display` value (e.g., `flex`, `grid`, `none`)
- **`[fireFlexDirection]`** – Sets `flex-direction`
- **`[fireFlexWrap]`** – Sets `flex-wrap`
- **`[fireJustifyContent]`** – Sets `justify-content`
- **`[fireAlignItems]`** – Sets `align-items`
- **`[fireAlignContent]`** – Sets `align-content`
- **`[fireGap]`** – Sets the `gap`

All of these work with responsive values and Angular Signals.
For comprehensive details on accepted values, types, and usage examples for each atomic directive, consult their respective JSDoc comments in the source code.

---


## 📦 Coming Soon

More compositional directives will be added soon:

- **`[fireGrid]`** – Grid layouts with responsive columns and rows
- **`[fireSpacing]`** – Easy responsive padding and margin
- **`[fireText]`** – Responsive control of font size, weight, color, and alignment

---


## Contributing

We welcome contributions! A full guide will be published soon.

---


## License

Licensed under the [MIT License](https://github.com/BhanukaDev/fireng/blob/main/LICENSE.md).