- Add confirmation dialog implementation and docs update

- Introduced `confirmAndDoAction` function in `lib.js` for displaying customizable confirmation dialogs.
- Updated minified JS in `lib.min.js` to include the new functionality.
- Added `docs/components.md` with usage examples for the existing `hipot:includer` component.
- Enhanced PHPDoc annotations in `phpdocs.php` for better type definitions.
- Updated `README.md` to link `components.md` and revised information about components.

Author: hipot

README.md

@@ -35,7 +35,7 @@ bitrix [main 23.600+](https://dev.1c-bitrix.ru/docs/versions.php?lang=ru&module=
 - универсальные обработчики событий <code>/lib/handlers_add.php</code> с подключением констант-рубильников из файла <code>/lib/constants.php</code>  
 - скрипт [xhprof.php](docs/xhprof.md) для быстрого профилирования "боевых" проектов
 - страница <code>pages/error.php</code> с перехватом фатальных php-ошибок и отправке их на почту разработчикам (размещается в DOCUMENT_ROOT проекта)
-- компоненты в папке <code>install/components</code> для копирования в <code>/local/components</code>
+- [компоненты](docs/components.md) в папке <code>install/components</code> для копирования в <code>/local/components</code>
   - <code>Hipot\Components\IblockList</code> - универсальный компонент для работы с элементами инфоблоков <code>hipot:iblock.list</code>. Этот же компонент умеет использовать и Abstract Iblock Elements Layer. В [теории двух компонент](https://github.com/bitrix-expert/bbc) - этот компонент можно использовать и для создания карточки (детальной страницы) элемента (товара, новости...)
   - <code>Hipot\Components\IblockSection</code> - компонент для работы со списком секций <code>hipot:iblock.section</code>
   - <code>Hipot\Components\HiBlockList</code> - список hightload блока <code>hipot:hiblock.list</code>

docs/components.md

@@ -0,0 +1,34 @@
+# TODO; описать все компоненты с примерами
+
+## hipot:includer
+Простой компонент для создания повторно используемых виджетов или блоков на сайте:
+
+```php
+<?
+\Hipot\Services\BitrixEngine::getAppD0()->IncludeComponent("hipot:includer", "widget.input_xls_file", [
+    'IS_REQUIRED' => 'Y'
+], $component, ['HIDE_ICONS' => 'Y']);
+?>
+```
+
+Либо целых страниц:
+```php
+<?
+require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
+
+/**
+ * @global $APPLICATION \CMain
+ * @global $USER \CUser
+ * @global $DB \CDatabase
+ * @global $USER_FIELD_MANAGER \CUserTypeManager
+ * @global $BX_MENU_CUSTOM \CMenuCustom
+ * @global $stackCacheManager \CStackCacheManager
+ */
+$APPLICATION->SetPageProperty('title', 'Voice Termination Solutions');
+$APPLICATION->SetTitle("Expand Your Reach with <br/> Reliable <span class=\"red-text\">Voice Termination Solutions</span>");
+?>
+
+<?$APPLICATION->IncludeComponent('hipot:includer', 'page.voice', [], null, ['HIDE_ICONS' => 'Y'])?>
+
+<?require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");?>
+```

install/js/hipot.framework/lib.js

@@ -28,6 +28,21 @@
 		});
 	};
 
+	/**
+	 * Плагин для сокрытия емейлов у ссылки
+	 * @memberOf JQuery
+	 */
+	$.fn.mailmea = function () {
+		let at = / AT /,
+			dot = / DOT /g;
+
+		return this.each(function () {
+			let text = $(this).data('mailme'),
+				addr = text.replace(at, '@').replace(dot, '.');
+			$(this).attr('href', 'mailto:' + addr);
+		});
+	};
+
 	/**
 	 * сериализует форму в объект JSON
 	 * @usage $('form').serializeJSON();
@@ -451,3 +466,49 @@ function requireJJs(libs, logik)
 	});
 	// console.info(libs);
 }
+
+/**
+ * Displays a confirmation dialog with specified text, an action to execute on confirmation, and customizable button text and color.
+ *
+ * @param {string} confirmTxt - The confirmation message to display in the dialog.
+ * @param {Function} action - The callback function to execute when the confirmation button is clicked.
+ * @param {string} btnOkTxt - The text to display on the confirmation button.
+ * @param {string} [btnOkColor] - The optional color for the confirmation button ex.: BX.UI.Button.Color.DANGER.
+ * @return {void}
+ */
+function confirmAndDoAction(confirmTxt, action, btnOkTxt, btnOkColor)
+{
+	if (typeof btnOkColor === 'undefined') {
+		btnOkColor = BX.UI.Button.Color.PRIMARY;
+	}
+
+	BX.UI.Dialogs.MessageBox.show({
+		message: confirmTxt,
+		title: "",
+		modal: true,
+		buttons: [
+			new BX.UI.Button(
+				{
+					color: btnOkColor,
+					text: btnOkTxt,
+					onclick: function(button, event) {
+						action();
+						button.context.close();
+					}
+				}
+			),
+			new BX.UI.CancelButton(
+				{
+					color: BX.UI.Button.Color.LINK,
+					onclick: function(button, event) {
+						button.context.close();
+					}
+				}
+			)
+		],
+	});
+	/*BX.UI.Dialogs.MessageBox.confirm(confirmTxt, '', (messageBox) => {
+		action();
+		messageBox.close();
+	}, btnOkTxt);*/
+}