import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/functional/ru/Element Utils'/>

# Утилиты для работы с DOM элементами

Набор функций для создания, поиска и манипуляции DOM элементами.

## `createElement`

Создает новый HTML элемент с указанным тегом и опционально добавляет его в родительский элемент.

**Параметры:**
- `parentElement?: HTMLElement` — родительский элемент для вставки (опционально)
- `tagName: string` — тег создаваемого элемента (по умолчанию `'div'`)
- `options?: Partial<T> | Record<keyof T, T[keyof T]> | ((element: T) => void)` — объект атрибутов или функция настройки (опционально)
- `referenceElement?: HTMLElement` — элемент, перед которым вставить новый (опционально)

```javascript
import { createElement } from '@dxtmisha/functional'

const div = createElement() // <div>
const button = createElement(parent, 'button') // <button> в parent
const input = createElement(parent, 'input', { type: 'text' }) // <input type="text">
```

## `domQuerySelector`

Безопасно ищет первый элемент, соответствующий CSS селектору.

**Параметры:**
- `selectors: string` — CSS селектор для поиска

```javascript
import { domQuerySelector } from '@dxtmisha/functional'

const header = domQuerySelector('#header') // HTMLElement | undefined
const button = domQuerySelector('.submit-btn') // HTMLElement | undefined
const input = domQuerySelector('input[type="email"]') // HTMLInputElement | undefined
```

## `domQuerySelectorAll`

Безопасно ищет все элементы, соответствующие CSS селектору.

**Параметры:**
- `selectors: string` — CSS селектор для поиска

```javascript
import { domQuerySelectorAll } from '@dxtmisha/functional'

const buttons = domQuerySelectorAll('button') // NodeList | undefined
const items = domQuerySelectorAll('.menu-item') // NodeList | undefined
const links = domQuerySelectorAll('a[href]') // NodeList | undefined
```

## `getAttributes`

Получает все атрибуты HTML элемента в виде объекта ключ-значение.

**Параметры:**
- `element?: ElementOrString<E>` — селектор или элемент для получения атрибутов

```javascript
import { getAttributes } from '@dxtmisha/functional'

const attrs = getAttributes('#my-element') // { id: 'my-element', class: 'btn' }
const buttonAttrs = getAttributes(button) // { type: 'submit', disabled: '' }
```

## `getElement`

Универсальная функция для получения DOM элемента. Принимает CSS селектор, элемент или window.

**Параметры:**
- `element?: ElementOrString<E>` — селектор, элемент или window

```javascript
import { getElement } from '@dxtmisha/functional'

const header = getElement('#header') // HTMLElement | undefined
const sameEl = getElement(existingEl) // возвращает existingEl
const bodyEl = getElement(window) // возвращает document.body
```

## `getElementId`

Получает ID элемента или создает уникальный ID, если элемент не имеет атрибута `id`.

**Параметры:**
- `element?: ElementOrString<E>` — элемент для получения ID
- `selector?: string` — дополнительный селектор для добавления к ID

```javascript
import { getElementId } from '@dxtmisha/functional'

const id1 = getElementId(elementWithId) // 'existing'
const id2 = getElementId(elementNoId) // 'id-123456' (сгенерированный)
const id3 = getElementId('#header', ' .title') // '#header .title'
```

## `getElementItem`

Получает значение свойства элемента по ключу с возможностью указания значения по умолчанию.

**Параметры:**
- `element: ElementOrString<T>` — элемент для проверки
- `index: K | string` — ключ свойства для получения
- `defaultValue?: D` — значение по умолчанию

```javascript
import { getElementItem } from '@dxtmisha/functional'

const value = getElementItem(input, 'value') // значение input
const type = getElementItem(input, 'type', 'text') // тип или 'text' по умолчанию
const width = getElementItem(element, 'offsetWidth')
```

## `getElementOrWindow`

Возвращает window объект как есть или получает DOM элемент.

**Параметры:**
- `element?: ElementOrString<E>` — селектор, элемент или window

```javascript
import { getElementOrWindow } from '@dxtmisha/functional'

const windowObj = getElementOrWindow(window) // window
const element = getElementOrWindow('#container') // HTMLElement
```

## `goScroll`

Плавно прокручивает страницу или элемент к указанной позиции.

**Параметры:**
- `element?: ElementOrString<E>` — элемент для прокрутки (по умолчанию window)
- `top?: number` — позиция по вертикали
- `left?: number` — позиция по горизонтали

```javascript
import { goScroll } from '@dxtmisha/functional'

goScroll(window, 0) // прокрутка наверх
goScroll('#container', 100, 50) // прокрутка элемента
```

## `initScrollbarOffset`

Инициализирует данные для управления скроллом, устанавливая CSS-переменную с шириной полосы прокрутки.

```javascript
import { initScrollbarOffset } from '@dxtmisha/functional'

// Инициализация при загрузке приложения
await initScrollbarOffset() // устанавливает --sys-scrollbar-offset в CSS
```

## `setElementItem`

Устанавливает значение свойства элемента по ключу.

**Параметры:**
- `element: ElementOrString<T>` — элемент для изменения
- `index: K | string` — ключ свойства для установки
- `value: any` — новое значение

```javascript
import { setElementItem } from '@dxtmisha/functional'

setElementItem(input, 'value', 'новое значение')
setElementItem('#my-element', 'textContent', 'Hello World')
setElementItem(button, 'disabled', true)
```
