# Layout Splitter

Customize your layout effortlessly by adjusting block sizes to your preference with Tailwind CSS Layout Splitters.

[![npm](https://img.shields.io/badge/npm-v4.2.0-blue)](https://www.npmjs.com/package/@preline/layout-splitter) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Demo](https://img.shields.io/badge/demo-online-brightgreen)](https://preline.co/plugins/layout-splitter.html)

## Contents

- [Overview](#overview)
- [Installation](#installation)
- [Basic usage](#basic-usage)
- [Configuration Options](#configuration-options)
- [JavaScript API](#javascript-api)
- [Events](#events)
- [Common Patterns](#common-patterns)
- [License](#license)

## Overview

The Layout Splitter component provides resizable layout panels with drag handles. It allows users to adjust the size of layout sections horizontally or vertically, creating flexible and customizable interfaces.

**Key Features:**
- Horizontal and vertical resizing
- Drag handles for intuitive resizing
- Minimum size constraints
- Pre-limit size detection
- Responsive breakpoint support
- Programmatic control via JavaScript API
- Event system for drag tracking

## Installation

To get started, install Layout Splitter plugin via npm, else you can skip this step if you are already using Preline UI as a package.

```bash
npm i @preline/layout-splitter
```

### CSS

Use [`@source`](https://tailwindcss.com/docs/functions-and-directives#source-directive) to register the plugin's JavaScript path for Tailwind CSS scanning, then [`@import`](https://tailwindcss.com/docs/functions-and-directives#import-directive) the plugin's CSS files into your Tailwind CSS file.

```css
@import "tailwindcss";

/* @preline/layout-splitter */
@source "../node_modules/@preline/layout-splitter/*.js";
@import "./node_modules/@preline/layout-splitter/variants.css";
@import "./node_modules/@preline/layout-splitter/theme.css";
```

### JavaScript

Include the JavaScript that powers the interactive elements near the end of your `</body>` tag:

```html
<script src="./node_modules/@preline/layout-splitter/index.js"></script>
```

### Manual Initialization

Use the `non-auto` entry if you need manual initialization. In this mode, automatic initialization on page load is not included, so the component should be initialized explicitly.

```html
<script type="module">
  import HSLayoutSplitter from "@preline/layout-splitter/non-auto.mjs";

  new HSLayoutSplitter(document.querySelector("#layout-splitter"));
</script>
```

### Via Bundler

When using a bundler (Vite, webpack, etc.), import the plugin directly as an ES module.

`@preline/layout-splitter` is the auto-init entry: it scans the DOM and initializes matching elements automatically.

```js
import "@preline/layout-splitter";
```

`@preline/layout-splitter/non-auto` is the manual entry: use it when you want explicit control over when initialization happens, either via `autoInit()` or by creating a specific instance yourself.

```js
import HSLayoutSplitter from "@preline/layout-splitter/non-auto";

HSLayoutSplitter.autoInit();

// Or initialize a specific element manually
const el = document.querySelector("#layout-splitter");
if (el) new HSLayoutSplitter(el);
```

### TypeScript

This package ships with TypeScript type definitions. No additional `@types/` package is needed.

## Basic usage

The following example demonstrates the minimal HTML structure required for a layout splitter component. This is a base template without custom styling - you can apply your own CSS classes and styles as needed. The layout allows resizing blocks by dragging the splitter handle.

```html
<div data-hs-layout-splitter='{
  "horizontalSplitterTemplate": "<div><span class=\"absolute top-1/2 start-1/2 -translate-x-2/4 -translate-y-2/4 block w-[11px] h-5 bg-gray-400\"></span></div>",
  "horizontalSplitterClasses": "relative flex border-s border-gray-200"
}'>
  <div class="flex h-50" data-hs-layout-splitter-horizontal-group>
    <div class="h-full" data-hs-layout-splitter-item="48.2">Horizontal Block 1</div>
    <div class="h-full" data-hs-layout-splitter-item="30.0">Horizontal Block 2</div>
  </div>
</div>
```

**Structure Requirements:**
- `data-hs-layout-splitter`: Required on the container element, contains configuration options as JSON
- `data-hs-layout-splitter-horizontal-group`: Required for horizontal splitting
- `data-hs-layout-splitter-vertical-group`: Required for vertical splitting
- `data-hs-layout-splitter-item`: Required on resizable blocks, accepts float number or object for initial size

**Initial State:**
- Blocks are sized according to `data-hs-layout-splitter-item` values
- Splitter handles are visible and draggable

## Configuration Options

### Data Options

Data options are specified in the `data-hs-layout-splitter` attribute and on splitter items.

| Option | Target Element | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `data-hs-layout-splitter` | Container | - | - | Activate a Layout Splitter by specifying on an element. Should be added to the container. |
| `:horizontalSplitterTemplate` | Inside `data-hs-layout-splitter` | string (HTML markup) | - | Defines the horizontal splitter template. HTML markup for the drag handle. |
| `:horizontalSplitterClasses` | Inside `data-hs-layout-splitter` | string | - | Defines the horizontal splitter CSS classes. CSS classes must be separated by a space. |
| `:verticalSplitterTemplate` | Inside `data-hs-layout-splitter` | string (HTML markup) | - | Defines the vertical splitter template. HTML markup for the drag handle. |
| `:verticalSplitterClasses` | Inside `data-hs-layout-splitter` | string | - | Defines the vertical splitter CSS classes. CSS classes must be separated by a space. |
| `data-hs-layout-splitter-horizontal-group` | Container element | - | - | Defines a group of elements with horizontal resizable blocks. |
| `data-hs-layout-splitter-vertical-group` | Container element | - | - | Defines a group of elements with vertical resizable blocks. |
| `data-hs-layout-splitter-item` | Resizable block | float \| object | - | Defines a block that can be resized depending on what group it is in. Also accepts a float number as a value to specify the initial width or height of the element. Can be an object with `dynamicSize`, `minSize`, `preLimitSize` properties. |
| `:dynamicSize` | Inside `data-hs-layout-splitter-item` | float | - | Defines the initialized block size. |
| `:minSize` | Inside `data-hs-layout-splitter-item` | float | - | Defines the size at which further narrowing of the block will be prevented. |
| `:preLimitSize` | Inside `data-hs-layout-splitter-item` | float | - | Determines the size at which the `onPrevPreLimit` event will be called. For example, on this event you can add specific classes to the block to the right or left of the divider. |

**Example:**
```html
<div data-hs-layout-splitter-item='{
  "dynamicSize": 30.0,
  "minSize": 10.0,
  "preLimitSize": 20.0
}'>
  Resizable Block
</div>
```

## JavaScript API

The `HSLayoutSplitter` object is available in the global `window` object after the plugin is loaded.

### Instance Methods

These methods are called on a layout splitter instance.

| Method | Parameters | Return Type | Description |
| --- | --- | --- | --- |
| `getSplitterItemSingleParam(item, name)` | `item`: `HTMLElement` (splitter item element)<br>`name`: `string` (parameter name) | `any` | Retrieves the value of a specific parameter (name) from the data attribute of a splitter item (item). The parameter is extracted from the parsed JSON object stored in the `data-hs-layout-splitter-item` attribute. |
| `getData(el)` | `el`: `HTMLElement` (splitter item element) | `object` | Retrieves detailed information about a splitter item, including its current size, minimum size, and pre-limit size, both in pixels and flex values. Returns a structured object. |
| `setSplitterItemSize(el, size)` | `el`: `HTMLElement` (splitter item element)<br>`size`: `number` (percentage) | `void` | Updates the size of a specified splitter item (`el`) to the given value (size). The new size is converted into a flex value and applied to the element. The method also updates the corresponding data attribute (`data-hs-layout-splitter-item`). |
| `updateFlexValues(data)` | `data`: `Array<{ id: string, breakpoints: Record<number, number> }>` | `void` | Updates the flex values of splitter items based on the provided configuration. Each configuration object specifies an element's ID and its size values for different screen widths (breakpoints). The method dynamically adjusts the flex values of the specified elements to match the current screen width. |
| `destroy()` | None | `void` | Cleans up and removes all event listeners, styles, and data attributes associated with the layout splitter. This method restores the affected elements to their original state and releases resources. |

### Static Methods

These methods are called directly on the `HSLayoutSplitter` class.

| Method | Parameters | Return Type | Description |
| --- | --- | --- | --- |
| `HSLayoutSplitter.getInstance(target, isInstance)` | `target`: `HTMLElement \| string` (CSS selector)<br>`isInstance`: `boolean` (optional) | `HTMLElement \| { id: string \| number, element: HSLayoutSplitter } \| null` | Returns the layout splitter instance or element associated with the target. If `isInstance` is `true`, returns collection item object `{ id, element }` where `element` is the `HSLayoutSplitter` instance. If `isInstance` is `false` or omitted, returns the DOM element (`HTMLElement`). Returns `null` if layout splitter instance is not found. |
| `HSLayoutSplitter.autoInit()` | None | `void` | Reinitializes all Layout Splitters on the page. Useful after dynamically adding layout splitters to DOM. |

### Usage Examples

**Example 1: Getting splitter item data**
```javascript
// Get the layout splitter instance
const instance = HSLayoutSplitter.getInstance('#hs-layout-splitter', true);

if (instance) {
  const { element } = instance;
  const item = document.querySelector('#hs-splitter-item');
  // Get item data
  const data = element.getData(item);

  console.log('Item data:', data);
}
```

**Example 2: Setting splitter item size**
```javascript
const instance = HSLayoutSplitter.getInstance('#hs-layout-splitter', true);

if (instance) {
  const { element } = instance;
  const item = document.querySelector('#hs-splitter-item');

  // Set item size to 50%
  element.setSplitterItemSize(item, 50);
}
```

**Example 3: Responsive breakpoints**
```javascript
const instance = HSLayoutSplitter.getInstance('#hs-layout-splitter', true);

if (instance) {
  const { element } = instance;
  // Update flex values based on window size
  const updateLayoutSplitter = (splitter) => {
    splitter.updateFlexValues([
      {
        id: "hs-section-first",
        breakpoints: {
          "0": 0,
          "1280": 15.0
        }
      },
      {
        id: "hs-section-second",
        breakpoints: {
          "0": 0,
          "1024": 25.4,
          "1280": 21.0
        }
      },
      {
        id: "hs-section-third",
        breakpoints: {
          "0": 100,
          "1024": 74.6,
          "1280": 64.0
        }
      }
    ]);
  };

  window.addEventListener('resize', () => {
    if (instance) updateLayoutSplitter(instance.element);
  });
}
```

**Example 4: Destroying layout splitter instance**
```javascript
const instance = HSLayoutSplitter.getInstance('#hs-layout-splitter', true);

if (instance) {
  const { element } = instance;
  const removeBtn = document.querySelector('#hs-remove-btn');

  removeBtn.addEventListener('click', () => {
    // Clean up before removing from DOM
    element.destroy();
    // Now safe to remove the element
    document.querySelector('#hs-layout-splitter').remove();
  });
}
```

## Events

Layout splitter instances emit events that can be listened to for drag tracking and custom behavior.

| Event Name | When Fired | Callback Parameter | Description |
| --- | --- | --- | --- |
| `on:drag` | When the splitter is dragged | `{ prev: HTMLElement, next: HTMLElement, previousSize: number, previousFlexSize: number, nextSize: number, nextFlexSize: number }` | Fires when the splitter is being dragged. Returns an object with previous and next elements and their sizes. |
| `on:onPrevLimit` | When the previous section size limit is reached | `HTMLElement` (previous element) | Fires when the previous section reaches its minimum size limit. |
| `on:onPrevPreLimit` | When the previous section size is less than `preLimitSize` | `HTMLElement` (previous element) | Fires when the previous section size is less than the `preLimitSize` parameter value. |
| `on:onNextLimit` | When the next section size limit is reached | `HTMLElement` (next element) | Fires when the next section reaches its minimum size limit. |
| `on:onNextPreLimit` | When the next section size is less than `preLimitSize` | `HTMLElement` (next element) | Fires when the next section size is less than the `preLimitSize` parameter value. |

### Event Usage Example

```javascript
// Get layout splitter instance
const instance = HSLayoutSplitter.getInstance('#hs-layout-splitter', true);

if (instance) {
  const { element } = instance;

  // Listen to limit events
  element.on('onPrevLimit', (prev) => {
    prev.classList.add('hs-prev-limit-reached');
  });

  element.on('onPrevPreLimit', (prev) => {
    prev.classList.add('hs-prev-pre-limit-reached');
  });

  // Listen to drag event
  element.on('drag', ({ prev, previousFlexSize }) => {
    if (previousFlexSize > 10) {
      prev.classList.remove('hs-prev-limit-reached');
    }

    if (previousFlexSize > 20) {
      prev.classList.remove('hs-prev-pre-limit-reached');
    }
  });
}
```

## Common Patterns

### Pattern 1: Horizontal Splitter

Create horizontal resizable panels.

```html
<div data-hs-layout-splitter>
  <div data-hs-layout-splitter-horizontal-group>
    <div data-hs-layout-splitter-item="50">Left Panel</div>
    <div data-hs-layout-splitter-item="50">Right Panel</div>
  </div>
</div>
```

### Pattern 2: With Minimum Size

Set minimum size constraints.

```html
<div data-hs-layout-splitter-item='{
  "dynamicSize": 30.0,
  "minSize": 10.0
}'>
  Resizable Panel
</div>
```

## License

Copyright (c) 2024 Htmlstream.

Licensed under the [MIT License](https://opensource.org/licenses/MIT).
