@reformer/core 11.0.0-beta.5 → 11.0.0-beta.7

package/dist/loader-Dv_Hl7JC.js

@@ -0,0 +1,216 @@
+class $ extends Error {
+  name = "MessageSyntaxError";
+}
+const v = (t) => `⟦${t}⟧`, b = /* @__PURE__ */ new Map(), y = /* @__PURE__ */ new Map();
+function g(t) {
+  let e = 0;
+  const s = (r) => {
+    throw new $(`${r} (позиция ${e}) в сообщении: ${t}`);
+  }, o = (r, i) => r === "{" || r === "}" || i && r === "#", n = () => {
+    for (; e < t.length && /\s/.test(t[e]); ) e++;
+  }, f = () => {
+    const r = e;
+    for (; e < t.length && !/[\s,{}#]/.test(t[e]); ) e++;
+    return e === r && s("ожидалось имя"), t.slice(r, e);
+  }, l = (r) => {
+    if (e++, t[e] === "'")
+      return e++, "'";
+    if (!o(t[e], r)) return "'";
+    let i = "";
+    for (; e < t.length; )
+      if (t[e] !== "'") i += t[e++];
+      else if (t[e + 1] === "'")
+        i += "'", e += 2;
+      else
+        return e++, i;
+    return i;
+  }, h = (r, i) => {
+    const u = [];
+    let m = "";
+    const p = () => {
+      m !== "" && (u.push({ kind: "text", value: m }), m = "");
+    };
+    for (; e < t.length; ) {
+      const d = t[e];
+      if (d === "}") {
+        r || s("непарная «}» — литерал пишется как '}'");
+        break;
+      }
+      d === "'" ? m += l(i !== null) : d === "#" && i !== null ? (e++, p(), u.push({ kind: "number", name: i })) : d === "{" ? (p(), u.push(a(i))) : (m += d, e++);
+    }
+    return p(), u;
+  }, c = (r, i, u) => {
+    const m = /* @__PURE__ */ new Map();
+    for (n(); e < t.length && t[e] !== "}"; ) {
+      const p = f();
+      n(), t[e] !== "{" && s(`ожидалась «{» после ветки «${p}»`), e++, m.set(p, h(!0, u)), t[e] !== "}" && s(`ветка «${p}» не закрыта`), e++, n();
+    }
+    return t[e] !== "}" && s(`«${r}, ${i}» не закрыт «}»`), e++, m.has("other") || s(`в «${r}, ${i}» нет обязательной ветки other`), m;
+  }, a = (r) => {
+    e++, n();
+    const i = f();
+    if (n(), t[e] === "}")
+      return e++, { kind: "arg", name: i };
+    t[e] !== "," && s(`ожидались «,» или «}» после аргумента «${i}»`), e++, n();
+    const u = f();
+    return u !== "plural" && u !== "select" && s(`неизвестный тип «${u}» у «${i}» — поддерживаются plural и select`), n(), t[e] !== "," && s(`ожидалась «,» после «${u}»`), e++, {
+      kind: u,
+      name: i,
+      branches: c(i, u, u === "plural" ? i : r)
+    };
+  };
+  return h(!1, null);
+}
+function M(t, e, s, o = {}) {
+  const n = o.onMissingArgument ?? v, f = (h) => {
+    const c = e[h];
+    return typeof c == "number" && Number.isFinite(c) ? c : null;
+  }, l = (h) => {
+    let c = "";
+    for (const a of h)
+      if (a.kind === "text") c += a.value;
+      else if (a.kind === "arg")
+        c += e[a.name] === void 0 ? n(a.name) : String(e[a.name]);
+      else if (a.kind === "number") {
+        const r = f(a.name);
+        c += r === null ? n(a.name) : j(s).format(r);
+      } else if (a.kind === "plural") {
+        const r = f(a.name);
+        c += r === null ? n(a.name) : l(
+          a.branches.get(`=${r}`) ?? a.branches.get(x(s).select(r)) ?? a.branches.get("other")
+        );
+      } else {
+        const r = e[a.name];
+        c += r === void 0 ? n(a.name) : l(a.branches.get(String(r)) ?? a.branches.get("other"));
+      }
+    return c;
+  };
+  return l(t);
+}
+function x(t) {
+  let e = b.get(t);
+  return e === void 0 && b.set(t, e = new Intl.PluralRules(t)), e;
+}
+function j(t) {
+  let e = y.get(t);
+  return e === void 0 && y.set(t, e = new Intl.NumberFormat(t)), e;
+}
+function E(t, e = {}) {
+  const s = /* @__PURE__ */ new Map();
+  return (o, n = {}) => {
+    let f = s.get(o);
+    return f === void 0 && s.set(o, f = g(o)), M(f, n, t, e);
+  };
+}
+const P = Object.freeze({
+  code: "en",
+  messages: Object.freeze({})
+});
+function O(t, e) {
+  const { messages: s, ...o } = e;
+  return {
+    ...t,
+    ...o,
+    messages: s === void 0 ? t.messages : { ...t.messages, ...s }
+  };
+}
+function k(t, e) {
+  return Object.prototype.hasOwnProperty.call(t, e);
+}
+function w(t, e = /* @__PURE__ */ new Set()) {
+  for (const s of t)
+    if (s.kind !== "text" && (e.add(s.name), s.kind === "plural" || s.kind === "select"))
+      for (const o of s.branches.values()) w(o, e);
+  return e;
+}
+function F(t, e) {
+  const s = [], o = /* @__PURE__ */ new Map();
+  for (const [n, f] of Object.entries(t))
+    try {
+      o.set(n, g(f));
+    } catch (l) {
+      s.push({
+        key: n,
+        kind: "syntax",
+        message: l instanceof Error ? l.message : String(l)
+      });
+    }
+  if (e === void 0) return s;
+  for (const n of Object.keys(t))
+    k(e, n) || s.push({ key: n, kind: "extra", message: "ключа нет в образце" });
+  for (const [n, f] of Object.entries(e)) {
+    if (!k(t, n)) {
+      s.push({ key: n, kind: "missing", message: "ключ есть в образце, но не переведён" });
+      continue;
+    }
+    const l = o.get(n);
+    if (l === void 0) continue;
+    const h = [...w(g(f))].sort().join(", "), c = [...w(l)].sort().join(", ");
+    h !== c && s.push({
+      key: n,
+      kind: "arguments",
+      message: `образец ждёт {${h}}, словарь — {${c}}`
+    });
+  }
+  return s;
+}
+function S(t) {
+  const e = t.messages;
+  return e !== null && typeof e == "object";
+}
+function L(t) {
+  if (t != null) {
+    if (typeof t != "object" || Array.isArray(t))
+      throw new TypeError("источник локали вернул не объект");
+    return S(t) ? t : { messages: t };
+  }
+}
+function A(t) {
+  const e = /* @__PURE__ */ new Map(), s = /* @__PURE__ */ new Map(), o = (n) => {
+    const f = e.get(n);
+    if (f !== void 0) return Promise.resolve(f);
+    const l = s.get(n);
+    if (l !== void 0) return l;
+    const h = Promise.all(t.map(async (c) => L(await c(n)))).then((c) => {
+      let a = { code: n, messages: {} };
+      for (const r of c)
+        r !== void 0 && (a = O(a, r));
+      return a = { ...a, code: n }, e.set(n, a), a;
+    }).finally(() => {
+      s.delete(n);
+    });
+    return s.set(n, h), h;
+  };
+  return Object.assign(o, {
+    peek: (n) => e.get(n),
+    preload: o
+  });
+}
+function N(t, e) {
+  return async (s) => {
+    const o = t(s), n = await fetch(o, e);
+    if (!n.ok)
+      throw new Error(`локаль «${s}»: ${o} ответил ${n.status}`);
+    return await n.json();
+  };
+}
+function C(t) {
+  return (e) => {
+    const s = e.split("-")[0].toLowerCase(), n = (Object.prototype.hasOwnProperty.call(t, e) ? t[e] : void 0) ?? (Object.prototype.hasOwnProperty.call(t, s) ? t[s] : void 0);
+    return n === void 0 ? null : n();
+  };
+}
+export {
+  P as D,
+  $ as M,
+  A as a,
+  C as b,
+  E as c,
+  N as d,
+  O as e,
+  M as f,
+  k as h,
+  w as m,
+  g as p,
+  F as v
+};

package/dist/locale/en.d.ts

@@ -0,0 +1,2 @@
+import { FormLocale } from '../i18n/locale';
+export declare const en: FormLocale;

package/dist/locale/en.js

@@ -0,0 +1,5 @@
+import { m as e } from "../en-CjAqn7h0.js";
+const o = { code: "en", weekStartsOn: 0, messages: e };
+export {
+  o as en
+};

package/dist/locale/en.json

@@ -0,0 +1,42 @@
+{
+  "code": "en",
+  "weekStartsOn": 0,
+  "messages": {
+    "format.fileSize.b": "{value} B",
+    "format.fileSize.kb": "{value} KB",
+    "format.fileSize.mb": "{value} MB",
+    "format.fileSize.gb": "{value} GB",
+    "format.fileSize.tb": "{value} TB",
+    "validation.required": "This field is required",
+    "validation.pattern": "Invalid format",
+    "validation.email": "Enter a valid email address",
+    "validation.url": "Enter a valid URL",
+    "validation.url_protocol": "The URL must use one of these protocols: {allowedProtocols}",
+    "validation.phone": "Enter a valid phone number",
+    "validation.min": "Must be at least {min}",
+    "validation.max": "Must be at most {max}",
+    "validation.minLength": "Enter at least {minLength, plural, one{# character} other{# characters}}",
+    "validation.maxLength": "Enter no more than {maxLength, plural, one{# character} other{# characters}}",
+    "validation.isNumber": "Enter a number",
+    "validation.integer": "Enter a whole number",
+    "validation.multipleOf": "Must be a multiple of {multipleOf}",
+    "validation.nonNegative": "Must not be negative",
+    "validation.nonZero": "Must not be zero",
+    "validation.date_invalid": "Enter a valid date",
+    "validation.date_min": "The date must not be earlier than {minDate}",
+    "validation.date_max": "The date must not be later than {maxDate}",
+    "validation.date_past": "The date must not be in the past",
+    "validation.date_future": "The date must not be in the future",
+    "validation.date_min_age": "Age must be at least {minAge}",
+    "validation.date_max_age": "Age must be at most {maxAge}",
+    "validation.fileType": "File {fileName} has a type that is not allowed. Allowed: {accept}",
+    "validation.maxFileSize": "File {fileName} is larger than {maxFileSize}",
+    "validation.minFileSize": "File {fileName} is smaller than {minFileSize}",
+    "validation.maxFiles": "No more than {maxFiles, plural, one{# file} other{# files}}",
+    "validation.minFiles": "At least {minFiles, plural, one{# file} other{# files}}",
+    "validation.maxTotalFileSize": "The total size of the files exceeds {maxTotalFileSize}",
+    "validation.fileExists": "File {fileName} has already been added",
+    "validation.uploadAborted": "Upload cancelled",
+    "validation.uploadFailed": "Failed to upload {fileName}"
+  }
+}

package/dist/locale/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Подпуть `@reformer/core/locale` — загрузчик встроенных локалей ядра (тексты ошибок валидации,
+ * единицы размера файла). Приложению с ui-kit он не нужен: `loadKitLocale` из
+ * `@reformer/ui-kit/locale` уже включает словари ядра и cdk.
+ *
+ * @module locale
+ */
+/** Языки, которые ядро поставляет само. */
+export declare const CORE_LOCALES: readonly string[];
+/**
+ * Источник локалей ядра для `createLocaleLoader`: чанк нужного языка по запросу.
+ *
+ * @example
+ * ```ts
+ * const loadLocale = createLocaleLoader([loadCoreLocale, fetchMessages((code) => `/locales/${code}.json`)]);
+ * ```
+ */
+export declare const loadCoreLocale: import('../i18n').LocaleSource;

package/dist/locale/ru.d.ts

@@ -0,0 +1,2 @@
+import { FormLocale } from '../i18n/locale';
+export declare const ru: FormLocale;

package/dist/locale/ru.js

@@ -0,0 +1,41 @@
+const a = {
+  "format.fileSize.b": "{value} Б",
+  "format.fileSize.kb": "{value} КБ",
+  "format.fileSize.mb": "{value} МБ",
+  "format.fileSize.gb": "{value} ГБ",
+  "format.fileSize.tb": "{value} ТБ",
+  "validation.required": "Обязательное поле",
+  "validation.pattern": "Неверный формат",
+  "validation.email": "Введите корректный email",
+  "validation.url": "Введите корректный адрес (URL)",
+  "validation.url_protocol": "Адрес должен начинаться с одного из протоколов: {allowedProtocols}",
+  "validation.phone": "Введите корректный номер телефона",
+  "validation.min": "Не меньше {min}",
+  "validation.max": "Не больше {max}",
+  "validation.minLength": "Не меньше {minLength, plural, one{# символа} few{# символов} many{# символов} other{# символа}}",
+  "validation.maxLength": "Не больше {maxLength, plural, one{# символа} few{# символов} many{# символов} other{# символа}}",
+  "validation.isNumber": "Введите число",
+  "validation.integer": "Введите целое число",
+  "validation.multipleOf": "Число должно быть кратно {multipleOf}",
+  "validation.nonNegative": "Число не может быть отрицательным",
+  "validation.nonZero": "Число не может быть нулём",
+  "validation.date_invalid": "Введите корректную дату",
+  "validation.date_min": "Дата не раньше {minDate}",
+  "validation.date_max": "Дата не позже {maxDate}",
+  "validation.date_past": "Дата не может быть в прошлом",
+  "validation.date_future": "Дата не может быть в будущем",
+  "validation.date_min_age": "Возраст не меньше {minAge, plural, one{# года} few{# лет} many{# лет} other{# года}}",
+  "validation.date_max_age": "Возраст не больше {maxAge, plural, one{# года} few{# лет} many{# лет} other{# года}}",
+  "validation.fileType": "Недопустимый тип файла {fileName}. Разрешено: {accept}",
+  "validation.maxFileSize": "Файл {fileName} больше {maxFileSize}",
+  "validation.minFileSize": "Файл {fileName} меньше {minFileSize}",
+  "validation.maxFiles": "Не больше {maxFiles, plural, one{# файла} few{# файлов} many{# файлов} other{# файла}}",
+  "validation.minFiles": "Не меньше {minFiles, plural, one{# файла} few{# файлов} many{# файлов} other{# файла}}",
+  "validation.maxTotalFileSize": "Суммарный размер файлов больше {maxTotalFileSize}",
+  "validation.fileExists": "Файл {fileName} уже добавлен",
+  "validation.uploadAborted": "Загрузка прервана",
+  "validation.uploadFailed": "Не удалось загрузить файл {fileName}"
+}, i = a, e = { code: "ru", weekStartsOn: 1, messages: i };
+export {
+  e as ru
+};

package/dist/locale/ru.json

@@ -0,0 +1,42 @@
+{
+  "code": "ru",
+  "weekStartsOn": 1,
+  "messages": {
+    "format.fileSize.b": "{value} Б",
+    "format.fileSize.kb": "{value} КБ",
+    "format.fileSize.mb": "{value} МБ",
+    "format.fileSize.gb": "{value} ГБ",
+    "format.fileSize.tb": "{value} ТБ",
+    "validation.required": "Обязательное поле",
+    "validation.pattern": "Неверный формат",
+    "validation.email": "Введите корректный email",
+    "validation.url": "Введите корректный адрес (URL)",
+    "validation.url_protocol": "Адрес должен начинаться с одного из протоколов: {allowedProtocols}",
+    "validation.phone": "Введите корректный номер телефона",
+    "validation.min": "Не меньше {min}",
+    "validation.max": "Не больше {max}",
+    "validation.minLength": "Не меньше {minLength, plural, one{# символа} few{# символов} many{# символов} other{# символа}}",
+    "validation.maxLength": "Не больше {maxLength, plural, one{# символа} few{# символов} many{# символов} other{# символа}}",
+    "validation.isNumber": "Введите число",
+    "validation.integer": "Введите целое число",
+    "validation.multipleOf": "Число должно быть кратно {multipleOf}",
+    "validation.nonNegative": "Число не может быть отрицательным",
+    "validation.nonZero": "Число не может быть нулём",
+    "validation.date_invalid": "Введите корректную дату",
+    "validation.date_min": "Дата не раньше {minDate}",
+    "validation.date_max": "Дата не позже {maxDate}",
+    "validation.date_past": "Дата не может быть в прошлом",
+    "validation.date_future": "Дата не может быть в будущем",
+    "validation.date_min_age": "Возраст не меньше {minAge, plural, one{# года} few{# лет} many{# лет} other{# года}}",
+    "validation.date_max_age": "Возраст не больше {maxAge, plural, one{# года} few{# лет} many{# лет} other{# года}}",
+    "validation.fileType": "Недопустимый тип файла {fileName}. Разрешено: {accept}",
+    "validation.maxFileSize": "Файл {fileName} больше {maxFileSize}",
+    "validation.minFileSize": "Файл {fileName} меньше {minFileSize}",
+    "validation.maxFiles": "Не больше {maxFiles, plural, one{# файла} few{# файлов} many{# файлов} other{# файла}}",
+    "validation.minFiles": "Не меньше {minFiles, plural, one{# файла} few{# файлов} many{# файлов} other{# файла}}",
+    "validation.maxTotalFileSize": "Суммарный размер файлов больше {maxTotalFileSize}",
+    "validation.fileExists": "Файл {fileName} уже добавлен",
+    "validation.uploadAborted": "Загрузка прервана",
+    "validation.uploadFailed": "Не удалось загрузить файл {fileName}"
+  }
+}

package/dist/locale.d.ts

@@ -0,0 +1,2 @@
+export * from './locale/index'
+export {}

package/dist/locale.js

@@ -0,0 +1,9 @@
+import { b as e } from "./loader-Dv_Hl7JC.js";
+const n = ["en", "ru"], t = e({
+  en: () => import("./locale/en.js").then((o) => o.en),
+  ru: () => import("./locale/ru.js").then((o) => o.ru)
+});
+export {
+  n as CORE_LOCALES,
+  t as loadCoreLocale
+};

package/dist/model/create-model.d.ts

@@ -3,13 +3,27 @@ import { FormModel, PathAwareSignal } from './types';
  * Обойти ВСЕ листовые сигналы модели (включая элементы массивов), вызвав `visit` на каждом.
  *
  * Внутри реактивного `effect` служит подпиской «любое поле изменилось»: `visit(sig => void sig.value)`
- * подписывает на значения листьев, а обход массивов через `items.value` — на их состав. Так строятся
- * триггеры `change`/`blur` стратегий валидации (см. `createFormValidation`), тем же паттерном, что
- * `revalidateWhen`, но без ручного перечисления зависимостей.
+ * подписывает на значения листьев, а обход массивов через `items.value` — на их состав. Тот же
+ * паттерн, что `revalidateWhen`, но без ручного перечисления зависимостей.
+ *
+ * Сами массивы обход не посещает — только их элементы. Поле, привязанное к массиву целиком
+ * (мультивыбор), живёт на сигнале массива; чтобы увидеть и его, берите {@link eachValueSignal}.
  *
  * @group Model
  */
 export declare function eachLeafSignal<T>(model: FormModel<T>, visit: (signal: PathAwareSignal<unknown>) => void): void;
+/**
+ * Обойти ВСЕ ручки значений модели: листья (включая элементы массивов) И сами массивы.
+ *
+ * Отличие от {@link eachLeafSignal} — узлы-массивы: массив бывает одним значением поля
+ * (`{ value: model.$.tags, component }`), и нода такого поля привязана к сигналу массива, а не
+ * к сигналам элементов. Обходчику, которому нужна именно НОДА поля (стратегия `blur` подписывается
+ * на её `touched`), одних листьев мало — он не увидел бы мультивыбор. Так строятся триггеры
+ * `change`/`blur` стратегий валидации (см. `createFormValidation`).
+ *
+ * @group Model
+ */
+export declare function eachValueSignal<T>(model: FormModel<T>, visit: (signal: PathAwareSignal<unknown>) => void): void;
 /**
  * Создать реактивную модель данных формы (слой M1).
  *

package/dist/model/index.d.ts

@@ -13,7 +13,7 @@
  * Состав (реэкспорты — из тех же файлов, что использует зонтик `.`, поэтому `.` и `/model` — один
  * module-инстанс: общий `derived`-WeakMap, единая идентичность `Signal`):
  * - **модель** — `createModel` + типы `FormModel`/`ModelArray`/… + `PathAwareSignal`;
- * - **обход листьев** — `eachLeafSignal` (подписка «любое поле изменилось»);
+ * - **обход значений** — `eachLeafSignal` (листья) и `eachValueSignal` (листья и массивы целиком);
  * - **value-операции** (реактивные правила) — `computeFrom`/`copyFrom`/`watchField`/`transformValue`/
  *   `resetWhen`/`syncFields`/`revalidateWhen`;
  * - **producer-owned флаг** — `markDerived`/`isDerived`/`unmarkDerived`;
@@ -22,9 +22,9 @@
  * @group Model
  * @module model
  */
-export { createModel, eachLeafSignal } from './create-model';
+export { createModel, eachLeafSignal, eachValueSignal } from './create-model';
 export type { FormModel, ModelArray, ModelArraySignals, ModelGroupSignals, ModelObject, ModelValue, ModelSignals, ModelApi, PathAwareSignal, } from './types';
-export { isModelContainerSignal } from './model-signals-proxy';
+export { isModelContainerSignal, isValueSignal } from './model-signals-proxy';
 export { computeFrom, copyFrom, watchField, transformValue, resetWhen, syncFields, revalidateWhen, } from './behaviors-value';
 export type { BehaviorCleanup } from './behaviors-value';
 export { markDerived, isDerived, unmarkDerived } from './derived-registry';

package/dist/model/model-signals-proxy.d.ts

@@ -1,9 +1,14 @@
+import { Signal } from '@preact/signals-core';
 import { PathAwareSignal } from './types';
 import { ModelNode, GroupNode } from './model-nodes';
 /**
  * Узел дерева `$`: лист → сам {@link PathAwareSignal}, группа/массив → контейнерный узел —
  * {@link ReadonlySignal} агрегированного значения ПЛЮС доступ к детям по имени/индексу.
  *
+ * Узел массива вдобавок принимает запись `.value` — замену массива целиком (см. шапку модуля).
+ * Любая другая запись в контейнер — ошибка: свойство, молча осевшее на прокси, выглядело бы как
+ * удачная запись, а модель осталась бы прежней.
+ *
  * Порядок разрешения ключа: служебные `__path`/`__kind` → ребёнок → свойство сигнала. Дети идут
  * раньше свойств сигнала — тот же приоритет, что у {@link makeFormModel} (поле формы затеняет метод
  * API). Поэтому имена `value`/`peek`/`subscribe`/`valueOf`/`toString`/`toJSON`/`brand` де-факто
@@ -29,4 +34,24 @@ export declare function signalsProxy(node: ModelNode): any;
  * ```
  */
 export declare function isModelContainerSignal(value: unknown): boolean;
+/** Узел-массив дерева `model.$` — ручка значения массива целиком. */
+export declare function isModelArraySignal(value: unknown): boolean;
+/**
+ * «Ручка значения», к которой можно привязать поле: лист (`instanceof Signal`) либо узел-массив
+ * дерева `model.$` (значение — массив целиком, `.value` читается и пишется).
+ *
+ * Группа сюда не входит: она читается целиком, но не пишется и полем не бывает. Этой проверкой
+ * `createForm` и рендереры отличают узел-поле схемы (`{ value, component }`) от контейнера —
+ * вместо голого `value instanceof Signal`, который узел-массив не проходит.
+ *
+ * @group Model
+ * @example
+ * ```typescript
+ * const model = createModel({ name: '', tags: [] as string[], address: { city: '' } });
+ * isValueSignal(model.$.name);    // true — лист
+ * isValueSignal(model.$.tags);    // true — массив как значение
+ * isValueSignal(model.$.address); // false — группа
+ * ```
+ */
+export declare function isValueSignal(value: unknown): value is Signal<unknown>;
 export declare function resolveSignalAt(root: GroupNode, path: string): PathAwareSignal<unknown> | undefined;

package/dist/model/types.d.ts

@@ -108,12 +108,23 @@ type ContainerSignal<T, TKeys extends PropertyKey> = Omit<ReadonlySignal<T>, TKe
 export type ModelGroupSignals<T> = ModelSignals<T> & ContainerSignal<T, keyof T>;
 /**
  * Узел-массив дерева `model.$`: индексируемый доступ к под-сигналам элементов, реактивная `length`
- * и {@link ReadonlySignal} значения массива целиком (реагирует и на правку элемента, и на изменение
- * состава — push/removeAt/move).
+ * и сигнал значения массива целиком (реагирует и на правку элемента, и на изменение состава —
+ * push/removeAt/move).
+ *
+ * В отличие от группы, узел ЗАПИСЫВАЕМ: `model.$.tags.value = ['a']` заменяет массив целиком. Это
+ * делает его {@link PathAwareSignal} — к нему привязывают поле (`{ value: model.$.tags, component }`),
+ * правило (`validate(model.$.tags, …)`) и поведение, как к листу. Так массив служит ОДНИМ значением
+ * поля: мультивыбор, теги, список файлов.
+ *
+ * `V` — объявленный тип поля, включая `null`/`undefined`: поле `string[] | null` с начальным `null`
+ * в рантайме — лист с тем же `.value`/`peek`/`subscribe`, поэтому общая часть честна для обоих
+ * случаев. `length` и индексы есть только у настоящего узла-массива (начальное значение — массив).
  *
  * @group Model
  */
-export type ModelArraySignals<U, V> = ContainerSignal<V, 'length'> & {
+export type ModelArraySignals<U, V> = Signal<V> & {
+    /** Путь массива в модели (dot-нотация). */
+    readonly __path: string;
     readonly length: number;
     readonly [index: number]: ModelSignalNode<U>;
 };
@@ -124,7 +135,7 @@ export type ModelArraySignals<U, V> = ContainerSignal<V, 'length'> & {
  * `PathAwareSignal<string>`, а не `ModelGroupSignals<never>`.
  * @internal
  */
-type ModelSignalNode<V> = NonNullable<V> extends ReadonlyArray<infer U> ? ModelArraySignals<U, NonNullable<V>> : NonNullable<V> extends Opaque ? PathAwareSignal<V> : NonNullable<V> extends object ? ModelGroupSignals<NonNullable<V>> : PathAwareSignal<V>;
+type ModelSignalNode<V> = NonNullable<V> extends ReadonlyArray<infer U> ? ModelArraySignals<U, V> : NonNullable<V> extends Opaque ? PathAwareSignal<V> : NonNullable<V> extends object ? ModelGroupSignals<NonNullable<V>> : PathAwareSignal<V>;
 /**
  * API уровня модели (доступно на корне, под-моделях вложенных объектов-групп и элементов массива).
  *
@@ -158,7 +169,10 @@ export interface ModelApi<T> {
     reset(): void;
     /** Зафиксировать текущие значения как новый initial-снимок («точка отсчёта»). */
     captureInitial(): void;
-    /** Резолв строкового пути в сигнал (для error-routing/мостов). */
+    /**
+     * Резолв строкового пути в сигнал (для error-routing/мостов): лист либо массив целиком
+     * (ручка значения массива — см. {@link ModelArraySignals}). Для пути группы — `undefined`.
+     */
     signalAt(path: string): PathAwareSignal<unknown> | undefined;
 }
 /**