### Install Konturio UI Packages

Source: https://context7.com/konturio/ui/llms.txt

Installs the necessary Konturio UI packages, including the core UI kit, default icons, default theme, and floating services, along with `clsx` and `react`.

```bash
npm install @konturio/ui-kit @konturio/default-icons @konturio/default-theme @konturio/floating clsx react
```

--------------------------------

### Modal Component Examples in React

Source: https://context7.com/konturio/ui/llms.txt

Illustrates the usage of the Modal component, showcasing basic modal implementation, handling backdrop clicks and ESC key presses for dismissal, and customizing the z-index. This example uses React and the @konturio/ui-kit library.

```tsx
import { Modal } from '@konturio/ui-kit';
import { useState } from 'react';

function ModalExamples() {
  const [isOpen, setIsOpen] = useState(false);
  const [confirmOpen, setConfirmOpen] = useState(false);

  const handleCancel = (reason: 'esc' | 'click_outside') => {
    console.log('Modal closed by:', reason);
    setIsOpen(false);
  };

  return (
    <div>
      {/* Basic modal */}
      <button onClick={() => setIsOpen(true)}>Open Modal</button>

      {isOpen && (
        <Modal onCancel={handleCancel}>
          <div style={{ padding: '24px', background: 'white', borderRadius: '8px' }}>
            <h2>Modal Title</h2>
            <p>Modal content goes here.</p>
            <button onClick={() => setIsOpen(false)}>Close</button>
          </div>
        </Modal>
      )}

      {/* Modal with custom z-index */}
      <button onClick={() => setConfirmOpen(true)}>Open Confirmation</button>

      {confirmOpen && (
        <Modal
          onCancel={() => setConfirmOpen(false)}
          zIndex="1000"
        >
          <div style={{ padding: '24px', background: 'white', borderRadius: '8px' }}>
            <h3>Confirm Action</h3>
            <p>Are you sure you want to proceed?</p>
            <div style={{ display: 'flex', gap: '8px' }}>
              <button onClick={() => setConfirmOpen(false)}>Cancel</button>
              <button onClick={() => {
                console.log('Confirmed!');
                setConfirmOpen(false);
              }}>Confirm</button>
            </div>
          </div>
        </Modal>
      )}
    </div>
  );
}

```

--------------------------------

### Release Packages with Lerna

Source: https://github.com/konturio/ui/blob/v5/README.md

This command initiates the release process for packages managed by Lerna. It handles version bumping, changelog generation, and publishing to a package registry. Ensure you are on the main branch and have pushed your changes before running this.

```sh
npm run release
```

--------------------------------

### Panel Component Examples in React

Source: https://context7.com/konturio/ui/llms.txt

Demonstrates various configurations of the Panel component, including basic collapsible panels, panels with header icons, custom controls, height constraints, and modal display modes. It utilizes React and the @konturio/ui-kit library.

```tsx
import { Panel, PanelIcon } from '@konturio/ui-kit';
import { useState } from 'react';
import { InfoIcon, CloseIcon } from '@konturio/default-icons';

function PanelExamples() {
  const [isOpen, setIsOpen] = useState(true);
  const [showModal, setShowModal] = useState(false);

  return (
    <div>
      {/* Basic collapsible panel */}
      <Panel
        header="Panel Title"
        isOpen={isOpen}
        onHeaderClick={() => setIsOpen(!isOpen)}
      >
        <p>Panel content goes here. This panel can be collapsed.</p>
      </Panel>

      {/* Panel with header icon */}
      <Panel
        header="Settings Panel"
        headerIcon={<InfoIcon />}
        isOpen={true}
      >
        <p>Panel with an icon in the header.</p>
      </Panel>

      {/* Panel with custom controls */}
      <Panel
        header="Custom Controls"
        isOpen={true}
        customControls={[
          {
            icon: <CloseIcon />,
            onClick: () => console.log('Close clicked'),
          }
        ]}
      >
        <p>Panel with custom header controls.</p>
      </Panel>

      {/* Panel with height constraints */}
      <Panel
        header="Scrollable Panel"
        isOpen={true}
        contentHeight="200px"
        minContentHeight="100px"
        maxContentHeight="400px"
        resize="vertical"
      >
        <p>Content with constrained height and vertical resize.</p>
        <p>More content...</p>
        <p>Even more content...</p>
      </Panel>

      {/* Panel displayed in modal */}
      <button onClick={() => setShowModal(true)}>Open Panel Modal</button>
      <Panel
        header="Modal Panel"
        isOpen={showModal}
        modal={{
          showInModal: true,
          onModalClick: () => setShowModal(false)
        }}
      >
        <p>This panel is displayed in a modal overlay.</p>
      </Panel>
    </div>
  );
}

```

--------------------------------

### Tooltip Component Examples (React)

Source: https://context7.com/konturio/ui/llms.txt

Illustrates the use of the Tooltip component from the '@konturio/floating' package. It covers simple, compound, and programmatically controlled tooltips with various placement and content options. Includes `SimpleTooltip`, `Tooltip`, `TooltipTrigger`, `TooltipContent`, `FloatingProvider`, and `TooltipService`.

```tsx
import {
  Tooltip,
  TooltipTrigger,
  TooltipContent,
  SimpleTooltip,
  FloatingProvider
} from '@konturio/floating';

function TooltipExamples() {
  return (
    <div>
      {/* Simple tooltip (all-in-one) */}
      <SimpleTooltip
        content="This is a simple tooltip"
        placement="top"
        size="default"
      >
        <button>Hover for tooltip</button>
      </SimpleTooltip>

      {/* Compound tooltip with more control */}
      <Tooltip placement="bottom">
        <TooltipTrigger asChild>
          <button>Hover me</button>
        </TooltipTrigger>
        <TooltipContent>
          <div>
            <strong>Rich Content</strong>
            <p>Tooltips can contain any React content.</p>
          </div>
        </TooltipContent>
      </Tooltip>

      {/* Tooltip with different placements */}
      <Tooltip placement="right-start">
        <TooltipTrigger asChild>
          <span style={{ cursor: 'help' }}>Info icon</span>
        </TooltipTrigger>
        <TooltipContent>
          Aligned to the right, starting at top
        </TooltipContent>
      </Tooltip>

      {/* Bigger tooltip variant */}
      <SimpleTooltip
        content="This tooltip has a larger size"
        placement="top"
        size="bigger"
      >
        <button>Large tooltip</button>
      </SimpleTooltip>
    </div>
  );
}

```

```tsx
// Tooltip Service for programmatic tooltips
import { TooltipService } from '@konturio/floating';

function TooltipServiceExample() {
  const tooltipService = new TooltipService();

  return (
    <FloatingProvider tooltipService={tooltipService}>
      <MapTooltipConsumer />
    </FloatingProvider>
  );
}

function MapTooltipConsumer() {
  const { useTooltip } = require('@konturio/floating');
  const tooltip = useTooltip({ placement: 'top' });

  const handleMouseMove = (e: React.MouseEvent) => {
    tooltip.show({ x: e.clientX, y: e.clientY }, 'Tooltip at cursor position');
  };

  const handleMouseLeave = () => {
    tooltip.close();
  };

  return (
    <div
      onMouseMove={handleMouseMove}
      onMouseLeave={handleMouseLeave}
      style={{ width: 400, height: 300, background: '#f0f0f0' }}
    >
      Move mouse here for position-based tooltip
    </div>
  );
}

```

--------------------------------

### Textarea Component Examples in React

Source: https://context7.com/konturio/ui/llms.txt

Demonstrates the usage of the Textarea component from '@konturio/ui-kit'. Supports resizable dimensions, animated placeholders, and error states. It takes value, onChange, renderLabel, placeholder, and error props for configuration.

```tsx
import { Textarea } from '@konturio/ui-kit';
import { useState } from 'react';

function TextareaExamples() {
  const [description, setDescription] = useState('');

  return (
    <div>
      {/* Basic textarea */}
      <Textarea
        value={description}
        onChange={(e) => setDescription(e.target.value)}
        renderLabel="Description"
        placeholder="Enter description..."
      />

      {/* Textarea with top placeholder */}
      <Textarea
        value={description}
        onChange={(e) => setDescription(e.target.value)}
        topPlaceholder="Description"
        placeholder="Enter your detailed description here..."
        showTopPlaceholder={true}
      />

      {/* Textarea with size constraints */}
      <Textarea
        value={description}
        onChange={(e) => setDescription(e.target.value)}
        minWidth="300px"
        maxWidth="600px"
        minHeight="100px"
        maxHeight="300px"
        renderLabel="Notes"
      />

      {/* Textarea with error */}
      <Textarea
        value={description}
        error="Description is required"
        message="Minimum 50 characters"
      />
    </div>
  );
}

```

--------------------------------

### Menu Component Examples (React)

Source: https://context7.com/konturio/ui/llms.txt

Demonstrates the usage of the Menu component for creating dropdown menus. Supports various item types like buttons, links, and dividers, along with keyboard navigation. It imports components from '@konturio/ui-kit'.

```tsx
import { Menu, MenuButton, MenuList, MenuItem, MenuLink } from '@konturio/ui-kit';
import { Button, Divider } from '@konturio/ui-kit';

function MenuExamples() {
  const handleAction = (action: string) => () => {
    console.log(`Action: ${action}`);
  };

  return (
    <div>
      {/* Basic menu */}
      <Menu>
        <MenuButton>
          Actions <span aria-hidden>▾</span>
        </MenuButton>
        <MenuList>
          <MenuItem onSelect={handleAction('download')}>Download</MenuItem>
          <MenuItem onSelect={handleAction('copy')}>Create a Copy</MenuItem>
          <MenuItem onSelect={handleAction('delete')}>Delete</MenuItem>
        </MenuList>
      </Menu>

      {/* Menu with Button component as trigger */}
      <Menu>
        <MenuButton as={Button} size="small">
          Options <span aria-hidden>▾</span>
        </MenuButton>
        <MenuList>
          <MenuItem onSelect={handleAction('edit')}>Edit</MenuItem>
          <MenuItem onSelect={handleAction('duplicate')}>Duplicate</MenuItem>
          <Divider style={{ margin: '4px 0' }} />
          <MenuItem onSelect={handleAction('archive')}>Archive</MenuItem>
          <MenuItem disabled onSelect={handleAction('delete')}> 
            Delete (disabled)
          </MenuItem>
        </MenuList>
      </Menu>

      {/* Menu with links */}
      <Menu>
        <MenuButton>
          Navigate <span aria-hidden>▾</span>
        </MenuButton>
        <MenuList>
          <MenuLink href="/dashboard">Dashboard</MenuLink>
          <MenuLink href="/settings">Settings</MenuLink>
          <MenuLink href="/help" target="_blank">Help (new tab)</MenuLink>
        </MenuList>
      </Menu>
    </div>
  );
}

```

--------------------------------

### Tabs Component Examples (React)

Source: https://context7.com/konturio/ui/llms.txt

Illustrates the functionality of the Tabs component for creating tabbed interfaces. It supports horizontal and vertical orientations, controlled and uncontrolled states, and keyboard navigation. The component is provided by the @konturio/ui-kit library.

```tsx
import { Tabs, TabList, Tab, TabPanels, TabPanel } from '@konturio/ui-kit';
import { useState } from 'react';

function TabsExamples() {
  const [activeTab, setActiveTab] = useState(0);

  return (
    <div>
      {/* Basic horizontal tabs */}
      <Tabs>
        <TabList>
          <Tab>Overview</Tab>
          <Tab>Settings</Tab>
          <Tab>Analytics</Tab>
        </TabList>

        <TabPanels>
          <TabPanel>
            <h3>Overview Content</h3>
            <p>Welcome to the dashboard overview.</p>
          </TabPanel>
          <TabPanel>
            <h3>Settings Content</h3>
            <p>Configure your preferences here.</p>
          </TabPanel>
          <TabPanel>
            <h3>Analytics Content</h3>
            <p>View your analytics data.</p>
          </TabPanel>
        </TabPanels>
      </Tabs>

      {/* Vertical tabs */}
      <Tabs orientation="vertical">
        <TabList>
          <Tab>Profile</Tab>
          <Tab>Security</Tab>
          <Tab>Notifications</Tab>
        </TabList>

        <TabPanels>
          <TabPanel>Profile settings</TabPanel>
          <TabPanel>Security options</TabPanel>
          <TabPanel>Notification preferences</TabPanel>
        </TabPanels>
      </Tabs>

      {/* Controlled tabs with onChange */}
      <Tabs index={activeTab} onChange={(index) => setActiveTab(index)}>
        <TabList>
          <Tab>Tab 1</Tab>
          <Tab disabled>Tab 2 (Disabled)</Tab>
          <Tab>Tab 3</Tab>
        </TabList>

        <TabPanels>
          <TabPanel>Content for Tab 1</TabPanel>
          <TabPanel>Content for Tab 2</TabPanel>
          <TabPanel>Content for Tab 3</TabPanel>
        </TabPanels>
      </Tabs>

      {/* Tabs with default index */}
      <Tabs defaultIndex={1}>
        <TabList>
          <Tab>First</Tab>
          <Tab>Second (default)</Tab>
          <Tab>Third</Tab>
        </TabList>

        <TabPanels>
          <TabPanel>First panel</TabPanel>
          <TabPanel>Second panel - shown by default</TabPanel>
          <TabPanel>Third panel</TabPanel>
        </TabPanels>
      </Tabs>
    </div>
  );
}

```

--------------------------------

### Input Component Examples (React)

Source: https://context7.com/konturio/ui/llms.txt

Illustrates the functionality of the Konturio UI Input component, including basic usage with labels and placeholders, animated top placeholders, password visibility toggles, error states, and applying custom CSS classes. It requires importing `Input` from `@konturio/ui-kit` and using React's `useState` and `useRef` hooks.

```tsx
import { Input } from '@konturio/ui-kit';
import { useState, useRef } from 'react';

function InputExamples() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const inputRef = useRef(null);

  return (
    <div>
      {/* Basic input with label */}
      <Input
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        renderLabel="Email Address"
        placeholder="Enter your email"
      />

      {/* Input with top placeholder animation */}
      <Input
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email"
        showTopPlaceholder={true}
      />

      {/* Password input with visibility toggle */}
      <Input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        renderLabel="Password"
        placeholder="Enter password"
      />

      {/* Input with error state */}
      <Input
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        error="Invalid email format"
        renderLabel="Email"
      />

      {/* Input with custom classes */}
      <Input
        ref={inputRef}
        isFocused={true}
        classes={{
          inputBox: 'custom-box',
          input: 'custom-input',
          error: 'custom-error'
        }}
      />
    </div>
  );
}

```

--------------------------------

### Button Component Examples (React)

Source: https://context7.com/konturio/ui/llms.txt

Demonstrates the usage of the Konturio UI Button component, showcasing various variants, sizes, icon placements, active states, and disabled states. It requires importing `Button` from `@konturio/ui-kit` and optionally icons from `@konturio/default-icons`.

```tsx
import { Button } from '@konturio/ui-kit';
import { EyeBallIcon } from '@konturio/default-icons';

function ButtonExamples() {
  const handleClick = () => console.log('Button clicked');

  return (
    <div>
      {/* Basic button */}
      <Button onClick={handleClick}>Click Me</Button>

      {/* Button with icon before text */}
      <Button
        variant="primary"
        size="medium"
        iconBefore={<EyeBallIcon />}
        onClick={handleClick}
      >
        View Details
      </Button>

      {/* Icon-only button */}
      <Button
        variant="invert-outline"
        size="small"
        iconBefore={<EyeBallIcon />}
        onClick={handleClick}
      />

      {/* Active state button */}
      <Button
        variant="invert"
        size="large"
        active={true}
        iconAfter={<EyeBallIcon />}
      >
        Active Button
      </Button>

      {/* Disabled button */}
      <Button disabled>Disabled</Button>
    </div>
  );
}

```

--------------------------------

### Select Component Examples in React

Source: https://context7.com/konturio/ui/llms.txt

Illustrates the functionality of the Select component from '@konturio/ui-kit'. It supports single and multiple selections (chips, aggregate), custom item rendering, and keyboard navigation. Key props include items, value, onChange, label, multiselect, and error.

```tsx
import { Select } from '@konturio/ui-kit';
import { useState } from 'react';
import type { SelectableItem } from '@konturio/ui-kit';

const items: SelectableItem[] = [
  { title: 'Option One', value: 1 },
  { title: 'Option Two', value: 2 },
  { title: 'Option Three', value: 3, hasDivider: true },
  { title: 'Disabled Option', value: 4, disabled: true },
  { title: 'Option Five', value: 5 },
];

function SelectExamples() {
  const [selected, setSelected] = useState<SelectableItem | null>(null);
  const [multiSelected, setMultiSelected] = useState<SelectableItem[]>([]);

  return (
    <div>
      {/* Basic single select */}
      <Select
        items={items}
        value={selected?.value}
        onChange={(e) => setSelected(e.selectedItem || null)}
        label="Choose Option"
      >
        Select an option...
      </Select>

      {/* Select with default value */}
      <Select
        items={items}
        defaultValue={2}
        label="Pre-selected"
        onSelect={(item) => console.log('Selected:', item)}
      />

      {/* Multiselect with chips */}
      <Select
        items={items}
        multiselect="chips"
        label="Select Multiple"
        onSelect={(items) => setMultiSelected(items as SelectableItem[])}
      >
        Choose items...
      </Select>

      {/* Multiselect with aggregate display */}
      <Select
        items={items}
        multiselect="aggregate"
        label="Multiple Selection"
        showEntryIcon={true}
      >
        Select items
      </Select>

      {/* Inline select variant */}
      <Select
        items={items}
        type="inline"
        label="Inline Select"
        withResetButton={false}
      />

      {/* Select with error state */}
      <Select
        items={items}
        error="Selection required"
        disabled={false}
        label="Required Field"
      />
    </div>
  );
}

```

--------------------------------

### Manual Publish Command for Lerna

Source: https://github.com/konturio/ui/blob/v5/README.md

This command can be used as a workaround if the automated release pipeline fails. It manually publishes packages, which might be necessary in certain CI/CD troubleshooting scenarios. Use with caution and ensure proper versioning.

```sh
npm run publish
```

--------------------------------

### Add Dependency to All Packages with Lerna

Source: https://github.com/konturio/ui/blob/v5/README.md

This command adds a specified package as a dependency to all packages within the Lerna monorepo. It's a convenient way to ensure a common dependency is available across the entire project.

```sh
lerna add @konturio/module3
```

--------------------------------

### Add Dependency to Specific Package with Lerna

Source: https://github.com/konturio/ui/blob/v5/README.md

This command adds a specified package as a dependency to a particular package within the Lerna monorepo. The `--scope` flag targets the installation to a single package, useful for managing inter-package dependencies.

```sh
lerna add @konturio/module3 --scope=@konturio/module2
```

--------------------------------

### Toggler Component Examples (React)

Source: https://context7.com/konturio/ui/llms.txt

Demonstrates the usage of the Toggler component for managing boolean states. It supports basic toggling, bidirectional labels, disabled states, and custom class names for labels. This component is part of the @konturio/ui-kit library.

```tsx
import { Toggler } from '@konturio/ui-kit';
import { useState } from 'react';

function TogglerExamples() {
  const [darkMode, setDarkMode] = useState(false);
  const [notifications, setNotifications] = useState(true);

  return (
    <div>
      {/* Basic toggle */}
      <Toggler
        id="dark-mode"
        label="Dark Mode"
        on={darkMode}
        onChange={(e) => setDarkMode(e.target.checked)}
      />

      {/* Toggle with off-value label (bidirectional) */}
      <Toggler
        id="view-mode"
        label="Grid"
        offValueLabel="List"
        on={false}
        onChange={(e) => console.log('View mode:', e.target.checked ? 'Grid' : 'List')}
      />

      {/* Disabled toggle */}
      <Toggler
        id="premium"
        label="Premium Features"
        on={true}
        disabled
      />

      {/* Toggle with custom label classes */}
      <Toggler
        id="notifications"
        label="Enable Notifications"
        on={notifications}
        onChange={(e) => setNotifications(e.target.checked)}
        classes={{
          label: 'custom-label',
          activeLabel: 'active-label-highlight'
        }}
      />
    </div>
  );
}

```

--------------------------------

### GitHub Actions CI/CD Workflow for PNPM Monorepo

Source: https://github.com/konturio/ui/blob/v5/docs/adr/0002-build-system-workflow-implementation.md

This YAML workflow defines the CI/CD pipeline for a PNPM monorepo. It includes a 'build' job that checks out code, sets up PNPM and Node.js, installs dependencies, builds the project, and runs tests. The 'release' job, triggered only on the main branch and not on 'ci skip' commits, depends on the 'build' job and uses Changesets to manage package releases and publishing.

```yaml
name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v2
        with:
          version: 7
      - uses: actions/setup-node@v3
        with:
          node-version: 16
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm run build
      - run: pnpm run test

  release:
    if: github.ref == 'refs/heads/main' && !contains(github.event.head_commit.message, 'ci skip')
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v2
        with:
          version: 7
      - uses: actions/setup-node@v3
        with:
          node-version: 16
          cache: 'pnpm'
          registry-url: 'https://registry.npmjs.org'
      - run: pnpm install --frozen-lockfile
      - name: Create Release Pull Request or Publish
        id: changesets
        uses: changesets/action@v1
        with:
          publish: pnpm run publish
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
```

--------------------------------

### Pull Request: Branch Naming Convention

Source: https://github.com/konturio/ui/blob/v5/AGENTS.md

Branch names should align with the branch name recorded in Fibery, if provided. For example, a branch name might look like `21648-switch-page-after-login-to-map`. This ensures consistency between development tasks and version control.

```git
git checkout -b 21648-switch-page-after-login-to-map
```

--------------------------------

### Context System Implementation Comparison

Source: https://github.com/konturio/ui/blob/v5/docs/investigations/tooltips-popups-audit.md

Illustrates the difference in context system implementation between the legacy ui-kit Dropdown and the modern floating TooltipService. The legacy system uses `createContext` for isolated implementations, while the modern system employs a standalone manager class.

```typescript
// ui-kit/Dropdown/context.ts
createContext(); // Isolated implementation
```

```typescript
// floating/TooltipService.ts
class TooltipService {
  /* Standalone manager */
}
```

--------------------------------

### Python Code Commenting

Source: https://github.com/konturio/ui/blob/v5/AGENTS.md

This illustrates the practice of writing comments for each logical block of Python code to enhance readability and maintainability.

```python
def my_function(param1, param2):
    # This is a comment for the first logical block
    result1 = param1 + param2

    # This is a comment for the second logical block
    result2 = result1 * 2
    return result2
```

--------------------------------

### Makefile Tab Usage

Source: https://github.com/konturio/ui/blob/v5/AGENTS.md

This highlights the requirement for Makefiles to use tabs for indentation, a common convention that needs to be adhered to for correct execution.

```makefile
target:
	@echo "This command uses a tab for indentation."
```

--------------------------------

### Testing: Makefile Smoke Test

Source: https://github.com/konturio/ui/blob/v5/AGENTS.md

The `make --trace all` command can be used to smoke-test a Makefile. This command displays the dependency chain as it is executed, helping to identify any issues or unexpected behavior in the build process.

```bash
make --trace all
```

--------------------------------

### CI: GitHub Actions Configuration

Source: https://github.com/konturio/ui/blob/v5/AGENTS.md

The project utilizes GitHub Actions for its Continuous Integration (CI) processes. It's important to keep the GitHub Actions configuration up-to-date to ensure that the CI pipeline functions correctly and efficiently.

```yaml
name: CI Pipeline

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python 3.10
        uses: actions/setup-python@v3
        with:
          python-version: "3.10"
      - name: Install dependencies
        run: | 
          python -m pip install --upgrade pip
          pip install -r requirements.txt
      - name: Run tests
        run: pytest
```

--------------------------------

### Applying Default Theme in React

Source: https://context7.com/konturio/ui/llms.txt

Shows how to integrate the default theme CSS from '@konturio/default-theme' into a React application. This enables consistent styling across UI components by utilizing CSS custom properties.

```tsx
// Import theme CSS at application root
import '@konturio/default-theme/src/style.module.css';

// Theme CSS variables available:
// --base-strong-down, --base-weak-up, --faint-strong, etc.
// --control-bg-weak, --control-bg-strong
// --danger-strong, --warning-strong, --success-strong

function ThemedApp() {
  return (
    <div className="konturio-theme">
      {/* All @konturio/ui-kit components will use theme variables */}
      <Button>Themed Button</Button>
      <Input placeholder="Themed input" />
    </div>
  );
}
```

--------------------------------

### Manual vs. Floating UI Positioning Logic

Source: https://github.com/konturio/ui/blob/v5/docs/investigations/tooltips-popups-audit.md

Compares the manual boundary checking logic in the legacy Tooltip component with the modern Floating UI approach using `useFloating` hook and middleware. The legacy system requires explicit calculations, while the modern system leverages a library for automated placement and offset adjustments.

```typescript
// Legacy (ui-kit/Tooltip)
function calculatePlacement(target: DOMRect, tooltip: DOMRect) {
  // Manual boundary checks
}
```

```typescript
// Modern (floating/Tooltip)
const { x, y, refs } = useFloating({
  middleware: [autoPlacement(), offset(4)],
});
```

--------------------------------

### Autocomplete Component Usage with React

Source: https://context7.com/konturio/ui/llms.txt

Demonstrates the usage of the Autocomplete component for type-ahead filtering and selection. Supports custom filter functions and various display options. Requires React and '@konturio/ui-kit'.

```tsx
import { Autocomplete } from '@konturio/ui-kit';
import { useState } from 'react';
import type { AutocompleteItemType } from '@konturio/ui-kit';

const countries: AutocompleteItemType[] = [
  { title: 'United States', value: 'us' },
  { title: 'United Kingdom', value: 'uk' },
  { title: 'Germany', value: 'de' },
  { title: 'France', value: 'fr' },
  { title: 'Japan', value: 'jp' },
];

function AutocompleteExamples() {
  const [selected, setSelected] = useState<AutocompleteItemType | null>(null);

  // Custom filter function
  const fuzzyFilter = (inputValue: string, items: AutocompleteItemType[]) => {
    const lowerInput = inputValue.toLowerCase();
    return items.filter(item =>
      item.title.toLowerCase().startsWith(lowerInput) ||
      item.value.toString().toLowerCase().includes(lowerInput)
    );
  };

  return (
    <div>
      {/* Basic autocomplete */}
      <Autocomplete
        items={countries}
        label="Country"
        placeholder="Type to search..."
        onSelect={(item) => setSelected(item as AutocompleteItemType)}
      />

      {/* Autocomplete with custom filter */}
      <Autocomplete
        items={countries}
        filterFunction={fuzzyFilter}
        label="Search Country"
        showSelectedIcon={true}
        showEntryIcon={true}
      />

      {/* Controlled autocomplete */}
      <Autocomplete
        items={countries}
        value={selected?.value}
        defaultValue="us"
        onChange={(changes) => {
          console.log('Change:', changes);
          setSelected(changes.selectedItem || null);
        }}
        label="Select Country"
      />

      {/* Inline variant with error */}
      <Autocomplete
        items={countries}
        type="inline"
        error="Please select a country"
        withResetButton={true}
      />
    </div>
  );
}

```

--------------------------------

### Makefile: Target Comment Format

Source: https://github.com/konturio/ui/blob/v5/AGENTS.md

Makefile targets should be formatted with self-documenting comments on the same line. The format is `target: dependencies | order_only_deps ## Description`. This makes the Makefile easier to understand and maintain by providing inline explanations for each target.

```makefile
# Example Makefile targets

build: src/* ## Compile source files

clean: ## Remove build artifacts
	rm -rf build/

run: build ## Run the application
	./build/app
```

--------------------------------

### Using Default Icons in React

Source: https://context7.com/konturio/ui/llms.txt

Demonstrates how to import and use SVG icon components from the '@konturio/default-icons' package in a React application. Supports basic usage, custom styling, size variants, and integration within other elements like buttons.

```tsx
import {
  SearchIcon,
  CloseIcon,
  EyeBallIcon,
  EyeBallCrossedIcon,
  InfoIcon,
  TrashBinIcon,
  // Figma-exported icons with size variants
  ChevronDown16,
  ChevronDown24,
  Close16,
  Close24,
  Eye16,
  EyeOff16,
  Calendar16,
  Calendar24,
} from '@konturio/default-icons';

function IconExamples() {
  return (
    <div>
      {/* Basic icon usage */}
      <SearchIcon />
      <CloseIcon />
      <InfoIcon />

      {/* Icons with custom styling */}
      <EyeBallIcon style={{ width: 24, height: 24, color: 'blue' }} />
      <TrashBinIcon className="danger-icon" />

      {/* Size-variant icons (16px and 24px) */}
      <div>
        <ChevronDown16 /> {/* 16x16 */}
        <ChevronDown24 /> {/* 24x24 */}
      </div>

      {/* Icons in buttons */}
      <button>
        <Eye16 /> Show
      </button>
      <button>
        <EyeOff16 /> Hide
      </button>

      {/* Calendar icons */}
      <Calendar16 />
      <Calendar24 />
    </div>
  );
}
```

--------------------------------

### SQL: Idempotent Migration Format

Source: https://github.com/konturio/ui/blob/v5/AGENTS.md

SQL files, particularly migrations, should be idempotent. This means they can be run multiple times without causing unintended side effects. Typically, this involves using `DROP TABLE IF EXISTS` statements before creating tables and adding comments to clarify query logic.

```sql
-- Create users table if it does not exist
DROP TABLE IF EXISTS users;
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

--------------------------------

### Listing Tooltip Consumers with Sourcegraph

Source: https://github.com/konturio/ui/blob/v5/docs/investigations/tooltips-popups-audit.md

Employs the `sg` (Sourcegraph CLI) tool to search for all occurrences of 'Tooltip' within the codebase and outputs the results in JSON format. The output is then piped to `jq` to extract the file paths of the matches.

```powershell
# List all Tooltip consumers
sg -p 'Tooltip' --json | jq '.matches[].file'
```

--------------------------------

### Export Icons from Figma using Personal Access Token

Source: https://github.com/konturio/ui/blob/v5/packages/default-icons/README.md

This section outlines the process of exporting icons from Figma using a Personal Access Token. It details how to generate the token in Figma settings and then use it either directly in the command line or by saving it in a `.env.local` file for subsequent exports. This method automates the process of bringing Figma icons into the project.

```bash
export FIGMA_TOKEN=<personalAccessToken>
```

```bash
set FIGMA_TOKEN=<personalAccessToken>
```

```bash
npm run figma:export
```

```bash
FIGMA_TOKEN=<personalAccessToken>
```

```bash
npm run figma:export-env
```

--------------------------------

### Map Integration for Tooltips

Source: https://github.com/konturio/ui/blob/v5/docs/investigations/tooltips-popups-audit.md

Demonstrates how the MapTooltip component integrates with a map library to display tooltips based on screen coordinates and track geographical positions. This snippet shows the event handling for map clicks and the subsequent actions to show the tooltip and track the point's location.

```typescript
// MapTooltip.fixture.tsx
map.on('click', (e) => {
  tooltip.show(e.point); // Screen coordinates
  tracker.trackPointPosition(e.lngLat); // Geo coordinates
});
```

--------------------------------

### Testing: Offline Pipeline Execution

Source: https://github.com/konturio/ui/blob/v5/AGENTS.md

To run the CI pipeline in an offline testing mode, set the `TEST_MODE` environment variable to `1` and execute the `make -B -j all` command. This allows for testing without external network dependencies and helps verify build and test configurations.

```bash
TEST_MODE=1 PYTHONPATH=. make -B -j all
```

--------------------------------

### Python: Docstring Generation

Source: https://github.com/konturio/ui/blob/v5/AGENTS.md

Python code should include docstrings to facilitate the generation of call graphs and documentation. Docstrings explain the purpose of modules, classes, functions, and methods, making the codebase more understandable and maintainable.

```python
def calculate_area(length, width):
    """Calculates the area of a rectangle.

    Args:
        length (float): The length of the rectangle.
        width (float): The width of the rectangle.

    Returns:
        float: The calculated area of the rectangle.
    """
    return length * width
```

--------------------------------

### Checkbox Component Usage with React

Source: https://context7.com/konturio/ui/llms.txt

Illustrates the use of the Checkbox component for boolean selections. Supports controlled and uncontrolled states, labels, and custom styling. Requires React and '@konturio/ui-kit'.

```tsx
import { Checkbox } from '@konturio/ui-kit';
import { useState } from 'react';

function CheckboxExamples() {
  const [isChecked, setIsChecked] = useState(false);
  const [preferences, setPreferences] = useState({
    notifications: true,
    newsletter: false,
  });

  return (
    <div>
      {/* Basic checkbox */}
      <Checkbox
        id="terms"
        label="I agree to the terms and conditions"
        checked={isChecked}
        onChange={(checked) => setIsChecked(checked)}
      />

      {/* Inline checkbox (block=false) */}
      <Checkbox
        id="remember"
        label="Remember me"
        block={false}
        checked={preferences.notifications}
        onChange={(checked) =>
          setPreferences(prev => ({ ...prev, notifications: checked }))
        }
      />

      {/* Disabled checkbox */}
      <Checkbox
        id="disabled"
        label="Disabled option"
        disabled
        checked={true}
      />

      {/* Checkbox with custom classes */}
      <Checkbox
        id="custom"
        label="Custom styled checkbox"
        classes={{
          input: 'custom-input-class',
          icon: 'custom-icon-class',
          disabled: 'custom-disabled-class'
        }}
      />
    </div>
  );
}

```

--------------------------------

### SQL JSONB Operator Usage

Source: https://github.com/konturio/ui/blob/v5/AGENTS.md

This snippet demonstrates the preferred method for querying jsonb data in SQL, utilizing indexed operators for better performance. It contrasts this with a less efficient alternative.

```sql
SELECT * FROM your_table WHERE tags @> '{"key": "value"}';
-- Instead of:
-- SELECT * FROM your_table WHERE tags ->> 'key' = 'value';
```

--------------------------------

### Radio Component Usage with React

Source: https://context7.com/konturio/ui/llms.txt

Shows how to use the Radio component for single selection within a group. It follows the API of the Checkbox component and supports labels and disabled states. Requires React and '@konturio/ui-kit'.

```tsx
import { Radio } from '@konturio/ui-kit';
import { useState } from 'react';

function RadioExamples() {
  const [selectedPlan, setSelectedPlan] = useState('basic');

  const handlePlanChange = (plan: string) => (checked: boolean) => {
    if (checked) setSelectedPlan(plan);
  };

  return (
    <div>
      {/* Radio group for plan selection */}
      <Radio
        id="plan-basic"
        name="plan"
        label="Basic Plan - $9/month"
        checked={selectedPlan === 'basic'}
        onChange={handlePlanChange('basic')}
      />

      <Radio
        id="plan-pro"
        name="plan"
        label="Pro Plan - $19/month"
        checked={selectedPlan === 'pro'}
        onChange={handlePlanChange('pro')}
      />

      <Radio
        id="plan-enterprise"
        name="plan"
        label="Enterprise Plan - Contact us"
        checked={selectedPlan === 'enterprise'}
        onChange={handlePlanChange('enterprise')}
      />

      {/* Disabled radio */}
      <Radio
        id="plan-legacy"
        name="plan"
        label="Legacy Plan (not available)"
        disabled
      />

      {/* Inline radio (block=false) */}
      <div style={{ display: 'flex', gap: '16px' }}>
        <Radio id="yes" name="confirm" label="Yes" block={false} />
        <Radio id="no" name="confirm" label="No" block={false} />
      </div>
    </div>
  );
}

```

--------------------------------

### Finding Broken Imports with ripgrep

Source: https://github.com/konturio/ui/blob/v5/docs/investigations/tooltips-popups-audit.md

Uses the `rg` (ripgrep) command-line tool to search for specific text patterns across files. This command is used to find broken imports related to '@konturio/floating'.

```powershell
# Find broken imports
rg '@konturio/floating' packages/
```

--------------------------------

### Makefile: Intermediate Target Dependency

Source: https://github.com/konturio/ui/blob/v5/AGENTS.md

When a Makefile target requires an intermediate result from another target, it should be split into two separate targets. The first target produces the intermediate result, and the second target depends on this intermediate result. This promotes modularity and clarity in build processes.

```makefile
target_with_intermediate:
	@echo "Running target with intermediate"

intermediate_target:
	@echo "Running intermediate target"

all: intermediate_target target_with_intermediate
	t@echo "All targets completed."
```

--------------------------------

### Manually Add New Icon as React Component

Source: https://github.com/konturio/ui/blob/v5/packages/default-icons/README.md

This snippet demonstrates how to manually add a new SVG icon as a React component in the Konturio UI module. It involves creating a new TSX file, pasting the SVG content, and structuring it as a functional component that accepts SVG props. The component is then memoized for performance optimization.

```typescript jsx
import React, { FC } from 'react';

const CloseIcon: FC = (props: React.SVGProps<SVGSVGElement>) => (
  <svg width="14" height="14" viewBox="0 0 14 14" {...props}>
    <path
      d="M13.9844 1.42188L8.40625 7L13.9844 12.5781L12.5781 13.9844L7 8.40625L1.42188 13.9844L0.015625 12.5781L5.59375 7L0.015625 1.42188L1.42188 0.015625L7 5.59375L12.5781 0.015625L13.9844 1.42188Z"
      fill="currentColor"
    />
  </svg>
);

export default React.memo(CloseIcon);
```

--------------------------------

### Pull Request: Conventional Commits Format

Source: https://github.com/konturio/ui/blob/v5/AGENTS.md

Pull requests and commits should follow the Conventional Commits specification. The format is `type(scope): TICKETNUMBER title ...`. The ticket number can be omitted if not provided. This convention helps in automating changelog generation and standardizing commit messages.

```git
feat(auth): AUTH-123 Implement user login endpoint

Adds a new POST endpoint to /api/v1/login for user authentication.
Includes validation for username and password.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.