> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deskofy.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Title Bar Component

The `DeskofyTitleBar` component provides a fully customizable, draggable title bar designed for **Electron-based Deskofy applications**. It allows developers to replace the default OS title bar with a **custom React-driven UI**, giving full control over layout, styling, and interactivity.

# Overview

`DeskofyTitleBar` is a React component that renders a flexible container at the top of the application window. It supports **custom alignment**, **dynamic visibility**, and **drag regions** that integrate with Electron’s window controls (e.g., drag, maximize, unmaximize). It does **not rely on any external CSS files**, all styles are inline and customizable via props.

## Key Features

* **Draggable region** support using `WebkitAppRegion` for Electron windows.
* **Fully customizable layout** via `contentAlignment`, padding, height, and inline styles.
* **Composable components array**, render any React elements (buttons, titles, icons, menus, etc.) inside the title bar.
* **Visibility control** for both the entire title bar and individual components.
* **Double-click maximize/unmaximize** behavior, mimicking native window behavior.

## Usage Example

```typescript theme={null}
import { DeskofyTitleBar, ContentAlignment } from '@deskofy/react';

import { MyWindowControls } from './MyWindowControls';
import { AppLogo } from './AppLogo';

export const MyAppTitleBar = () => (
  <DeskofyTitleBar
    height={36}
    inlinePadding={10}
    blockPadding={4}
    contentAlignment={ContentAlignment.SPACE_BETWEEN}
    components={[
      {
        id: 'left',
        component: <AppLogo />,
        isDragable: false,
      },
      {
        id: 'right',
        component: <MyWindowControls />,
        isDragable: false,
      },
    ]}
  />
);
```

# Titlebar Component

## Props

| Prop               | Type                | Default         | Description                                                          |
| :----------------- | :------------------ | :-------------- | :------------------------------------------------------------------- |
| `id`               | `string`            | —               | Optional ID for the title bar.                                       |
| `components`       | `TComponent[]`      | `[]`            | Array of components (React elements) to render inside the title bar. |
| `contentAlignment` | `TContentAlignment` | `SPACE_BETWEEN` | Determines how components are aligned within the container.          |
| `height`           | `number`            | `32`            | Height of the title bar in pixels.                                   |
| `inlinePadding`    | `number`            | `8`             | Horizontal padding (left and right).                                 |
| `blockPadding`     | `number`            | `0`             | Vertical padding (top and bottom).                                   |
| `className`        | `string`            | `''`            | Optional custom class name.                                          |
| `style`            | `CSSProperties`     | `{}`            | Inline style overrides for the container.                            |
| `isDragable`       | `boolean`           | `true`          | Enables dragging of the entire title bar area.                       |
| `isVisible`        | `boolean`           | `true`          | Controls visibility of the entire title bar.                         |

## Component Types

Each component object inside the `components` array defines what to render and how it behaves.

| Field        | Type            | Default       | Description                                        |                                                         |
| :----------- | :-------------- | :------------ | :------------------------------------------------- | ------------------------------------------------------- |
| `id`         | \`string        | number\`      | —                                                  | Optional unique identifier.                             |
| `component`  | \`ReactNode     | JSX.Element\` | —                                                  | The React element to render (e.g., icon, button, text). |
| `className`  | `string`        | —             | Optional class name for the wrapper div.           |                                                         |
| `style`      | `CSSProperties` | `{}`          | Inline style for the wrapper div.                  |                                                         |
| `isDragable` | `boolean`       | `true`        | Whether this component region should be draggable. |                                                         |
| `isVisible`  | `boolean`       | `true`        | Controls visibility of this specific component.    |                                                         |

## Content Alignment Options

The `contentAlignment` prop controls horizontal positioning of child components.

| Alignment       | CSS Equivalent  | Description                                              |
| :-------------- | :-------------- | :------------------------------------------------------- |
| `LEFT`          | `flex-start`    | Align items to the left.                                 |
| `RIGHT`         | `flex-end`      | Align items to the right.                                |
| `CENTER`        | `center`        | Center all items horizontally.                           |
| `SPACE_BETWEEN` | `space-between` | Evenly distribute items, first at start and last at end. |
| `SPACE_AROUND`  | `space-around`  | Even spacing around all items.                           |
| `SPACE_EVENLY`  | `space-evenly`  | Equal spacing between and around all items.              |

# Notes

* The title bar is rendered as a **fixed element** positioned at the top of the viewport.
* The container has a default background color of **red** — intended for debugging. You should override it using the `style` prop.
* For best results, combine with Electron’s frameless window mode.

# Developer Notes

## Design Philosophy

* The component is **style-agnostic**, no CSS or theme dependency.
* Built for **Electron environments only**, where frameless windows require custom drag and control logic.
* Uses **flexbox layout** for predictable alignment and composability.

## Drag Region Behavior

* Setting `WebkitAppRegion: drag` makes an area draggable by Deskofy.
* **MacOS and Windows handle drag regions slightly differently**:
  * On **macOS**, buttons near the top-left may interfere with draggable areas; ensure custom buttons are within `no-drag` zones.
  * On **Windows**, draggable areas may overlap invisible hitboxes if padding or overlapping elements are misaligned.

<Note>
  Always mark interactive elements (buttons, menus) as `isDragable: false`.
</Note>

## Window Events

* Double-clicking toggles maximize/unmaximize via `window.deskofyWindow`.
* Developers can disable this behavior by removing or replacing the event listener.

## Performance & Rendering

* The component uses **inline styles** to avoid runtime stylesheet loading.
* Recommended for small, lightweight render trees (\<10 child components).
* Since it’s fixed-positioned, it won’t reflow with other layout changes.

## Accessibility

* The component itself doesn’t handle focus, keyboard navigation, or ARIA roles yet.
* If accessibility is a priority, wrap internal components (like buttons or menus) with proper roles and keyboard handlers.