@amxts/menu-core 0.2.1 → 0.3.0

package/PAWN.md

@@ -22,8 +22,8 @@ A plugin compiled against it gets a tag warning for a bare number where `MenuPro
 - `mc_get_menu_property_string(idx, MP_SECTION)` gives the menu's section.
 - A condition filter applies wherever the condition is asked.
 - A restriction's `message` is shown beside an item it greys out when the item has no message of its own.
-- `IS_ALIVE`, `IS_DEAD`, `TEAM_<team>`, `IS_BOT`, `IS_ADMIN` and `FLAG_<letters>` are built-in conditions, answered while no plugin registers the name. A plugin that registers one of them answers instead.
-- `ADMIN` and `ACCESS_ADMIN` are not built in: they are names like any other, and a menu that uses them needs a plugin that registers them (`mc_register_condition`, `mc_register_restriction`). Otherwise the check says the name is not registered and suggests `IS_ADMIN`. Without a plugin, write `IS_ADMIN` (any admin) or `FLAG_<letters>` (`FLAG_dluy`: ban, rcon, admin or menu access).
+- `IS_ALIVE`, `IS_DEAD`, `TEAM_<team>`, `IS_BOT`, `IS_ADMIN`, `ADMIN`, `ACCESS_ADMIN` and `FLAG_<letters>` are built-in conditions, answered while no plugin registers the name. A plugin that registers one of them answers instead.
+- `ADMIN` and `ACCESS_ADMIN`, as conditions and as restrictions, hold for ban, rcon, admin or menu access (`FLAG_dluy`), as in the Pawn menu_core.
 - A restriction `NAME:text` takes the rest of the line, spaces and all, as its text; names before it are restrictions of their own.
 - Closing a menu because another opens over it tells the close callbacks its name.
 - A locked menu greys out the items of any menu, not only list rows.

package/PAWN.ru.md

@@ -22,8 +22,8 @@ Pawn-плагины пишут `#include <menu_core>`; в пакете лежи
 - `mc_get_menu_property_string(idx, MP_SECTION)` отдаёт секцию меню.
 - Фильтр условия применяется везде, где спрашивают условие.
 - `message` ограничения показывается рядом с посеревшим пунктом, если у пункта нет своего сообщения.
-- `IS_ALIVE`, `IS_DEAD`, `TEAM_<команда>`, `IS_BOT`, `IS_ADMIN` и `FLAG_<буквы>` — встроенные условия, на них отвечает Menu Core, пока имя не регистрирует ни один плагин. Плагин, который регистрирует такое имя, отвечает вместо него.
-- `ADMIN` и `ACCESS_ADMIN` не встроены: это такие же имена, как любые другие, и меню, где они есть, нужен плагин, который их регистрирует (`mc_register_condition`, `mc_register_restriction`). Иначе проверка скажет, что имя не зарегистрировано, и предложит `IS_ADMIN`. Без плагина пишите `IS_ADMIN` (любой админ) или `FLAG_<буквы>` (`FLAG_dluy` — доступ ban, rcon, admin или menu).
+- `IS_ALIVE`, `IS_DEAD`, `TEAM_<команда>`, `IS_BOT`, `IS_ADMIN`, `ADMIN`, `ACCESS_ADMIN` и `FLAG_<буквы>` — встроенные условия, на них отвечает Menu Core, пока имя не регистрирует ни один плагин. Плагин, который регистрирует такое имя, отвечает вместо него.
+- `ADMIN` и `ACCESS_ADMIN` — и как условия, и как ограничения — выполняются при доступе ban, rcon, admin или menu (`FLAG_dluy`), как в Pawn menu_core.
 - Ограничение `NAME:текст` забирает остаток строки вместе с пробелами как свой текст; имена перед ним — отдельные ограничения.
 - Когда меню закрывается, потому что поверх открылось другое, колбэки закрытия получают его имя.
 - Заблокированное меню делает серыми пункты любого меню, а не только строки списков.

package/README.md

@@ -123,7 +123,7 @@ const vote = menus.create("LIST_MAPS", { title: "Next map" });
 vote.setListSource(() => maps.map((map, index) => menus.listRow(index, map)));
 vote.addItem({
 	title: ({ row }) => maps[row],
-	onSelect: ({ player, row }) => print(0, `${player.name} votes for ${maps[row]}`),
+	onSelect: ({ player, row }) => player.print(`You vote for ${maps[row]}`),
 });
 ```
 
@@ -138,6 +138,9 @@ In code a requirement is a function. Names — `IS_ALIVE`, `FLAG_d`, a restricti
 
 Keys: **1–7** choose, **8** is the next page, **9** the previous page or back to the menu this one was opened from, **0** closes.
 
+> [!WARNING]
+> **Showing the menu a player is on:** from a command or a timer, `show()` opens it anew, at its first page. From one of its own items it stays on its page — and after an item's action the menu is drawn again by itself. `setPage(player, page)` is the page the next `show()` draws.
+
 Text colours are written as tags, the same letters as in chat: `!y` yellow, `!r` red, `!d` grey, `!w` white, `!R` aligns right. Chat's own `!g`, `!b` and `!t` are dropped from a menu.
 
 ### API
@@ -161,9 +164,9 @@ Its fields — `title`, `time`, `hideBack`, `hideExit`, `locked`, `sharedTimer`
 | Function | What it does |
 | --- | --- |
 | `create(name, options?)` | A menu in code, or the existing one with that name. A name starting with `LIST_` makes a list menu. Options: `title` (text or a function), `time`, `hideBack`, `hideExit`, `locked`, `activeWhen`. |
-| `find(name)` · `register(name)` | A menu by its name; `register` reads it from the file ahead of time. |
+| `find(name)` · `register(...names)` | A menu by its name; `register` reads them from the file ahead of time: `register("MAIN_MENU", "ADMIN_MENU")`. |
 | `show(player, name, options?)` · `close(player)` · `activeMenu(player)` · `lock(player)` | The player's menu, whichever it is. |
-| `addCondition(name, test)` · `addAction(name, handler)` · `addPlaceholder(name, value)` · `addRestriction(name, test, message?)` | What menu files and Pawn plugins name, answered by functions — `%name%` in their text is a placeholder. An action, a placeholder and a restriction get the menu's context and the `name` they are asked by; a condition, `(player, viewer, name)`, is asked of the row's player in a list menu. A restriction's `message` is said beside an item it greys out, unless the item or the requirement has its own. `menu.addPlaceholder(name, value)` gives one to a single menu. |
+| `addCondition(name, test)` · `addAction(name, handler)` · `addPlaceholder(name, value)` · `addRestriction(name, test, message?)` · `addActions({ NAME: handler })` · `addPlaceholders({ name: value })` | What menu files and Pawn plugins name, answered by functions — `%name%` in their text is a placeholder; `addActions` and `addPlaceholders` take several at once. An action or a placeholder is a function of the player, `(player) => ...`, or of the menu's context. An action, a placeholder and a restriction get the menu's context and the `name` they are asked by; a condition, `(player, viewer, name)`, is asked of the row's player in a list menu. A restriction's `message` is said beside an item it greys out, unless the item or the requirement has its own. `menu.addPlaceholder(name, value)` gives one to a single menu. |
 | `setListSource(name, rows)` · `refresh("A B")` · `conditionChanged(name)` · `addEventListener(type, listener)` | The same for menus by name, and every menu's events. |
 
 ## Menus in a file
@@ -280,7 +283,7 @@ VIEW = {
 
 | YAML, JSON | INI | What it is |
 | --- | --- | --- |
-| `chatPrefix` | `[MAIN]` `PREFIX` | The chat prefix of Menu Core's messages. |
+| `chatPrefix` | `[MAIN]` `PREFIX` | The chat prefix of Menu Core's messages. The Pawn menu_core's `[Основное]` is read as `[MAIN]`. |
 | `labels`: `exit`, `back`, `next`, `number`, `disabled`, `page`, `time` | `[MAIN]` `KEY = { ... }` | The words of the buttons, the page and the countdown. |
 | `menus`: `{ NAME: menu }` | `[NAME]` | The menus; a name starting with `LIST_` is a list menu. |
 | `title` | `TITLE` | The title; a menu has one. |
@@ -317,6 +320,7 @@ A `visible`, `when`, `enabled`, `activeOn`, `action` or `onTimeout` is a name, s
   | `TEAM_CT` · `TEAM_TERRORIST` · `TEAM_SPECTATOR` · `TEAM_UNASSIGNED` | is in that team |
   | `IS_BOT` | is a bot |
   | `IS_ADMIN` | has any access but a plain user's `z` — AMX Mod X's `is_user_admin` |
+  | `ADMIN` · `ACCESS_ADMIN` | has ban, rcon, admin or menu access — `FLAG_dluy`, as the Pawn menu_core answered them |
   | `FLAG_<letters>` | has any of those `users.ini` letters: `FLAG_ab` |
 
   In a list menu, a condition of the view or a filter is asked of the row's player, and a restriction gets the row as its target. The names are case-insensitive.
@@ -332,7 +336,6 @@ A `visible`, `when`, `enabled`, `activeOn`, `action` or `onTimeout` is a name, s
 > - **An item's name in YAML or JSON is not split on `|`:** its faces are written with `variants`.
 > - **Colours** are tags in a menu file too: `!y`, `!r`, `!d`, `!w`, `!R`. Pawn's codes (`\y`, `\r`) are warned of, with the tag to write, and left out. Text from Pawn — a Pawn plugin's items and titles, a lang dictionary — keeps its codes, and Menu Core reads them as the tags.
 > - **`%time%` and `%target%` are lower case:** `%TIME%` and `%s` are left as written.
-> - **`ADMIN` and `ACCESS_ADMIN` are not built in:** a plugin registers them, or the file writes `IS_ADMIN` (any admin) or `FLAG_<letters>` (`FLAG_d`).
 
 ### INI's columns
 

package/README.ru.md

@@ -123,7 +123,7 @@ const vote = menus.create("LIST_MAPS", { title: "Следующая карта"
 vote.setListSource(() => maps.map((map, index) => menus.listRow(index, map)));
 vote.addItem({
 	title: ({ row }) => maps[row],
-	onSelect: ({ player, row }) => print(0, `${player.name} голосует за ${maps[row]}`),
+	onSelect: ({ player, row }) => player.print(`Ты голосуешь за ${maps[row]}`),
 });
 ```
 
@@ -138,6 +138,9 @@ vote.addItem({
 
 Клавиши: **1–7** выбирают, **8** — следующая страница, **9** — предыдущая страница или назад, в меню, из которого открыли это, **0** закрывает.
 
+> [!WARNING]
+> **Показ меню, в котором игрок уже находится:** из команды или таймера `show()` открывает его заново, с первой страницы. Из его собственного пункта меню остаётся на своей странице — а после действия пункта меню и так рисуется снова. `setPage(player, page)` — страница, которую нарисует следующий `show()`.
+
 Цвета в тексте пишутся метками, теми же буквами, что в чате: `!y` жёлтый, `!r` красный, `!d` серый, `!w` белый, `!R` — выравнивание вправо. Метки только для чата — `!g`, `!b` и `!t` — из меню убираются.
 
 ### API
@@ -161,9 +164,9 @@ vote.addItem({
 | Функция | Что делает |
 | --- | --- |
 | `create(name, options?)` | Меню в коде или уже существующее с таким именем. Имя с `LIST_` делает меню-список. Опции: `title` (текст или функция), `time`, `hideBack`, `hideExit`, `locked`, `activeWhen`. |
-| `find(name)` · `register(name)` | Меню по имени; `register` заранее читает его из файла. |
+| `find(name)` · `register(...names)` | Меню по имени; `register` заранее читает их из файла: `register("MAIN_MENU", "ADMIN_MENU")`. |
 | `show(player, name, options?)` · `close(player)` · `activeMenu(player)` · `lock(player)` | Меню игрока, какое бы оно ни было. |
-| `addCondition(name, test)` · `addAction(name, handler)` · `addPlaceholder(name, value)` · `addRestriction(name, test, message?)` | То, что называют файлы меню и Pawn-плагины, — ответы функциями; `%name%` в их тексте — плейсхолдер. Действие, плейсхолдер и ограничение получают контекст меню и имя `name`, по которому их спросили; условие, `(player, viewer, name)`, в меню-списке спрашивается об игроке строки. `message` ограничения пишется рядом с пунктом, который оно гасит, если у пункта или требования нет своего. `menu.addPlaceholder(name, value)` задаёт его одному меню. |
+| `addCondition(name, test)` · `addAction(name, handler)` · `addPlaceholder(name, value)` · `addRestriction(name, test, message?)` · `addActions({ NAME: handler })` · `addPlaceholders({ name: value })` | То, что называют файлы меню и Pawn-плагины, — ответы функциями; `%name%` в их тексте — плейсхолдер; `addActions` и `addPlaceholders` принимают несколько сразу. Действие или плейсхолдер — функция игрока, `(player) => ...`, или контекста меню. Действие, плейсхолдер и ограничение получают контекст меню и имя `name`, по которому их спросили; условие, `(player, viewer, name)`, в меню-списке спрашивается об игроке строки. `message` ограничения пишется рядом с пунктом, который оно гасит, если у пункта или требования нет своего. `menu.addPlaceholder(name, value)` задаёт его одному меню. |
 | `setListSource(name, rows)` · `refresh("A B")` · `conditionChanged(name)` · `addEventListener(type, listener)` | То же для меню по имени и события всех меню. |
 
 ## Меню в файле
@@ -280,7 +283,7 @@ VIEW = {
 
 | YAML, JSON | INI | Что это |
 | --- | --- | --- |
-| `chatPrefix` | `[MAIN]` `PREFIX` | Префикс сообщений Menu Core в чате. |
+| `chatPrefix` | `[MAIN]` `PREFIX` | Префикс сообщений Menu Core в чате. `[Основное]` из Pawn-модуля menu_core читается как `[MAIN]`. |
 | `labels`: `exit`, `back`, `next`, `number`, `disabled`, `page`, `time` | `[MAIN]` `KEY = { ... }` | Слова кнопок, страницы и отсчёта. |
 | `menus`: `{ NAME: меню }` | `[NAME]` | Меню; имя на `LIST_` — меню-список. |
 | `title` | `TITLE` | Заголовок; он у меню обязателен. |
@@ -317,6 +320,7 @@ VIEW = {
   | `TEAM_CT` · `TEAM_TERRORIST` · `TEAM_SPECTATOR` · `TEAM_UNASSIGNED` | в этой команде |
   | `IS_BOT` | бот |
   | `IS_ADMIN` | имеет любой доступ, кроме `z` простого игрока, — `is_user_admin` AMX Mod X |
+  | `ADMIN` · `ACCESS_ADMIN` | имеет доступ ban, rcon, admin или menu — `FLAG_dluy`, как отвечал Pawn menu_core |
   | `FLAG_<буквы>` | имеет любую из этих букв `users.ini`: `FLAG_ab` |
 
   В меню-списке условие вида или фильтра спрашивается у игрока строки, а ограничение получает строку как цель. Регистр в именах не важен.
@@ -332,7 +336,6 @@ VIEW = {
 > - **Имя пункта в YAML или JSON не делится по `|`:** его варианты пишутся через `variants`.
 > - **Цвета** и в файле меню пишутся метками: `!y`, `!r`, `!d`, `!w`, `!R`. На коды Pawn (`\y`, `\r`) будет предупреждение с меткой, которую писать, и они выбрасываются. Текст из Pawn — пункты и заголовки Pawn-плагина, словарь lang — сохраняет свои коды, и Menu Core читает их как метки.
 > - **`%time%` и `%target%` пишутся строчными:** `%TIME%` и `%s` остаются как написаны.
-> - **`ADMIN` и `ACCESS_ADMIN` не встроены:** их регистрирует плагин, или файл пишет `IS_ADMIN` (любой админ) или `FLAG_<буквы>` (`FLAG_d`).
 
 ### Столбцы INI
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@amxts/menu-core",
 	"type": "module",
-	"version": "0.2.1",
+	"version": "0.3.0",
 	"description": "Menus for amxts plugins, from ini files or code: conditions, placeholders, lists - and the mc_* natives for Pawn plugins.",
 	"author": {
 		"name": "kukson777",
@@ -49,8 +49,8 @@
 		"lint:fix": "oxfmt && oxlint --fix --silent || oxlint --fix --silent || oxlint --fix"
 	},
 	"peerDependencies": {
-		"@amxts/config-core": "^0.1.2",
-		"@amxts/core": "^0.2.2"
+		"@amxts/config-core": "^0.2.0",
+		"@amxts/core": "^0.3.0"
 	},
 	"devDependencies": {
 		"@e18e/eslint-plugin": "^0.8.1",