@ryuzaki13/react-foundation-ui 1.8.6 → 1.8.8

package/storybook-static/assets/README-CMoAGNQ5.js

@@ -0,0 +1,282 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-C5-IVaAZ.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-Dx5UE11l.js";function o(e){let t={a:`a`,code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,table:`table`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,...n(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(i,{title:`Foundation Lib/API/Formatters/Обзор`}),`
+`,(0,c.jsx)(t.h1,{id:`ryuzaki13react-foundation-libformatters`,children:(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/formatters`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`formatters`}),` — большой модуль подготовки значений для интерфейса и transport-контрактов. Он работает с датами, числами, строками, boolean/ABAP-флагами, ФИО, российскими телефонами, ведущими нулями и семантическими состояниями. Для таблиц модуль также предоставляет конфигурируемый formatter pipeline и row-based формулы.`]}),`
+`,(0,c.jsx)(t.p,{children:`Документация разделена по предметным областям, чтобы разработчику не приходилось читать один огромный файл. Этот README объясняет общие правила, помогает выбрать API и подробно описывает небольшие helpers верхнего уровня.`}),`
+`,(0,c.jsx)(t.h2,{id:`установка`,children:`Установка`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-bash`,children:`npm install @ryuzaki13/react-foundation-lib
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Пакет является ESM. Корневого импорта пакета нет. Все formatter functions и их типы импортируются из точечного entrypoint:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { formatDateAsDate, formatNumberAsDecimal2, normalizeText } from "@ryuzaki13/react-foundation-lib/formatters";
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Некоторые общие типы принадлежат `,(0,c.jsx)(t.code,{children:`/types`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import type { AbapBoolean, State } from "@ryuzaki13/react-foundation-lib/types";
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Вложенные каталоги исходников не являются package subpaths:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`// Неправильно: таких exports нет.
+// import { formatDate } from "@ryuzaki13/react-foundation-lib/formatters/date";
+// import { formatNumber } from "@ryuzaki13/react-foundation-lib/formatters/number";
+
+// Правильно.
+import { formatDate, formatNumber } from "@ryuzaki13/react-foundation-lib/formatters";
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`карта-документации`,children:`Карта документации`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Область`}),(0,c.jsx)(t.th,{children:`README`}),(0,c.jsx)(t.th,{children:`Что внутри`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Boolean и ABAP-флаги`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.a,{href:`./boolean/README.mdx`,children:`boolean/README.mdx`})}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`parseAbapBoolean`}),`, `,(0,c.jsx)(t.code,{children:`parseBoolean`}),`, `,(0,c.jsx)(t.code,{children:`toAbapBoolean`}),`, truthy/falsy`]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Даты и диапазоны`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.a,{href:`./date/README.mdx`,children:`date/README.mdx`})}),(0,c.jsx)(t.td,{children:`parsing, formatting, timezone, presets, calendar, education dates`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Числа`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.a,{href:`./number/README.mdx`,children:`number/README.mdx`})}),(0,c.jsx)(t.td,{children:`presets, parsing SAP-like строк, compact, zero semantics`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Строки`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.a,{href:`./strings/README.mdx`,children:`strings/README.mdx`})}),(0,c.jsx)(t.td,{children:`trim, spaces, leading zeros, truncate, русские plural forms`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Value state`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.a,{href:`./valueState/README.mdx`,children:`valueState/README.mdx`})}),(0,c.jsx)(t.td,{children:`fixed/threshold resolvers, registry, CSS presentation`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Row-based формулы`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.a,{href:`./rowBased/README.mdx`,children:`rowBased/README.mdx`})}),(0,c.jsx)(t.td,{children:`formula context, registry, dependencies и purity`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Formatter pipeline`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.a,{href:`./pipeline/README.mdx`,children:`pipeline/README.mdx`})}),(0,c.jsx)(t.td,{children:`plan/graph, validation, compilation, runtime ячеек`})]})]})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Все эти области остаются частью одного публичного `,(0,c.jsx)(t.code,{children:`/formatters`}),` entrypoint. Деление относится к документации и организации исходников, а не к способу импорта.`]}),`
+`,(0,c.jsx)(t.h2,{id:`быстрый-выбор-функции`,children:`Быстрый выбор функции`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Нужно`}),(0,c.jsx)(t.th,{children:`Использовать`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Показать дату`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`formatDateAsDate`}),`, `,(0,c.jsx)(t.code,{children:`formatDate`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Прочитать календарную дату`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`parseDate`}),`, `,(0,c.jsx)(t.code,{children:`parseDateValue`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Прочитать абсолютный timestamp с timezone`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`parseDateTZ`}),`, `,(0,c.jsx)(t.code,{children:`parseDateValueTZ`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Показать число`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`formatNumberAs*`}),`, `,(0,c.jsx)(t.code,{children:`formatNumber`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsxs)(t.td,{children:[`Прочитать строку `,(0,c.jsx)(t.code,{children:`"1 234,5"`}),` как число`]}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`toFiniteNumber`}),` или `,(0,c.jsx)(t.code,{children:`parseNumber`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Нормализовать необязательный текст`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`normalizeText`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Схлопнуть пробелы в пользовательском тексте`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`normalizeTextSpaces`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsxs)(t.td,{children:[`Выбрать `,(0,c.jsx)(t.code,{children:`файл/файла/файлов`})]}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`selectRussianPluralForm`}),`, `,(0,c.jsx)(t.code,{children:`formatRussianPlural`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsxs)(t.td,{children:[`Прочитать ABAP `,(0,c.jsx)(t.code,{children:`X`})]}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`parseAbapBoolean`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Сформировать ABAP boolean`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`toAbapBoolean`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Нормализовать ФИО`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`formatFullName`}),`, `,(0,c.jsx)(t.code,{children:`formatShortName`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Показать российский телефон`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`formatPhone`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Получить условно очищенный телефон`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`clearPhone`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Дополнить числовую строку нулями`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`normalizeLeadingZeros`}),` или `,(0,c.jsx)(t.code,{children:`normalizeLeadingZerosStrict`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Вычислить visual state`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`createFixedResolver`}),`, `,(0,c.jsx)(t.code,{children:`createThresholdResolver`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Форматировать ячейку по сериализуемой схеме`}),(0,c.jsx)(t.td,{children:`formatter pipeline`})]})]})]}),`
+`,(0,c.jsx)(t.h2,{id:`общие-правила`,children:`Общие правила`}),`
+`,(0,c.jsx)(t.h3,{id:`formatter-обычно-не-является-validator-ом`,children:`Formatter обычно не является validator-ом`}),`
+`,(0,c.jsx)(t.p,{children:`Функция может иметь fallback для невалидного значения, но это не делает данные валидными:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatNumber("abc", "decimal"); // "0"
+formatDateAsDate("abc"); // ""
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Если нужно сообщить пользователю об ошибке, сначала валидируйте или парсите вход, а затем форматируйте успешный результат.`}),`
+`,(0,c.jsxs)(t.h3,{id:`unknown-требует-понимания-coercion`,children:[(0,c.jsx)(t.code,{children:`unknown`}),` требует понимания coercion`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Некоторые функции принимают `,(0,c.jsx)(t.code,{children:`unknown`}),`, чтобы безопасно работать с внешними данными, но внутри используют разные правила:`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`formatNumber`}),` применяет `,(0,c.jsx)(t.code,{children:`Number(value)`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`toFiniteNumber`}),` принимает только number или строку и понимает SAP-like separators;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`parseBoolean`}),` использует whitelist для строк и truthy/falsy для остальных значений;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`fixed value state сравнивает `,(0,c.jsx)(t.code,{children:`String(value)`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`normalizeText`}),` принимает только настоящий string.`]}),`
+`]}),`
+`,(0,c.jsx)(t.p,{children:`Не переносите ожидания от одной функции на другую.`}),`
+`,(0,c.jsx)(t.h3,{id:`нормализуйте-на-явной-границе`,children:`Нормализуйте на явной границе`}),`
+`,(0,c.jsx)(t.p,{children:`Функции меняют значения: обрезают пробелы, меняют регистр, удаляют нули или форматируют числа. Для формы обычно разумно хранить пользовательский draft буквально, а нормализацию выполнять при сохранении/восстановлении или другом явно выбранном переходе.`}),`
+`,(0,c.jsx)(t.h3,{id:`глобальные-реестры-настраиваются-один-раз`,children:`Глобальные реестры настраиваются один раз`}),`
+`,(0,c.jsx)(t.p,{children:`Date/number presets, value-state resolvers и row-based formulas хранятся на уровне загруженного модуля. Регистрируйте их в bootstrap-коде до построения formatter pipeline:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`export function configureApplicationFormatters(): void {
+	registerNumberPreset({ name: "quantity-4", decimals: 4 });
+	registerDatePreset({ name: "document-date", pattern: "dd.MM.yyyy" });
+
+	configureRowBasedFormatterRegistry(createRowBasedFormatterRegistry(rowBasedDefinitions));
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Функции `,(0,c.jsx)(t.code,{children:`reset*`}),` предназначены в основном для тестов. Они могут инвалидировать runtime, который уже хранит ссылки или ids.`]}),`
+`,(0,c.jsx)(t.h3,{id:`компилируйте-горячий-runtime-заранее`,children:`Компилируйте горячий runtime заранее`}),`
+`,(0,c.jsx)(t.p,{children:`Presets и formatter pipeline рассчитаны на множество ячеек. Не регистрируйте правила и не компилируйте pipeline в цикле рендера. Подготовьте стабильные объекты один раз, затем вызывайте готовый formatter/executor.`}),`
+`,(0,c.jsx)(t.h2,{id:`фио`,children:`ФИО`}),`
+`,(0,c.jsx)(t.h3,{id:`formatfullnamefullname`,children:(0,c.jsx)(t.code,{children:`formatFullName(fullName)`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function formatFullName(fullName: string): string;
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Функция пытается привести ФИО к виду `,(0,c.jsx)(t.code,{children:`Фамилия Имя Отчество`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatFullName("  иВАНОВ   иВАН   иВАНОВИЧ  ");
+// "Иванов Иван Иванович"
+
+formatFullName("петров"); // "Петров"
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Обработка:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`falsy string возвращает `,(0,c.jsx)(t.code,{children:`""`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`внешние пробелы удаляются;`}),`
+`,(0,c.jsx)(t.li,{children:`последовательности whitespace схлопываются;`}),`
+`,(0,c.jsx)(t.li,{children:`строка приводится к нижнему регистру;`}),`
+`,(0,c.jsx)(t.li,{children:`у каждой из первых трёх частей первая code unit переводится в верхний регистр.`}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Функция предполагает порядок `,(0,c.jsx)(t.code,{children:`фамилия имя отчество`}),` и учитывает максимум три space-separated части. Всё после третьей части игнорируется.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatFullName("Иванов Иван Иванович младший");
+// "Иванов Иван Иванович"
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Она не знает сложные правила имён, дефисы, частицы, locale и правильный регистр вроде `,(0,c.jsx)(t.code,{children:`МакДональд`}),`. `,(0,c.jsx)(t.code,{children:`toLowerCase`}),` + первая заглавная может испортить нестандартное написание. Используйте только для данных с ожидаемой простой русской структурой.`]}),`
+`,(0,c.jsx)(t.p,{children:`Инициалы обрабатываются минимально, без восстановления полного имени:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatFullName("Иванов И.И."); // "Иванов И И."
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Поэтому функция не является parser-ом формата `,(0,c.jsx)(t.code,{children:`Фамилия И.О.`}),` в полноценное ФИО.`]}),`
+`,(0,c.jsx)(t.h3,{id:`formatshortnamefullname`,children:(0,c.jsx)(t.code,{children:`formatShortName(fullName)`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function formatShortName(fullName: string): string;
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Создаёт вид `,(0,c.jsx)(t.code,{children:`Фамилия И.О.`}),` из первых трёх частей:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatShortName("иванов иван иванович"); // "Иванов И.И."
+formatShortName("петров петр"); // "Петров П."
+formatShortName("сидоров"); // "Сидоров"
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Требуется корректный порядок частей. Готовая строка с двумя инициалами в одном token не разбирается полноценно:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatShortName("Иванов И.И."); // "Иванов И."
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Пустой token после необычной пунктуации может привести к неожиданному результату; передавайте обычную строку ФИО, а не произвольный текст.`}),`
+`,(0,c.jsx)(t.h3,{id:`когда-не-использовать-helpers-фио`,children:`Когда не использовать helpers ФИО`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`для международных имён с другим порядком;`}),`
+`,(0,c.jsx)(t.li,{children:`для юридически значимого написания;`}),`
+`,(0,c.jsx)(t.li,{children:`для восстановления ФИО из инициалов;`}),`
+`,(0,c.jsx)(t.li,{children:`когда четвёртая и последующие части значимы;`}),`
+`,(0,c.jsx)(t.li,{children:`когда регистр должен сохраняться буквально.`}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Для структурированных данных предпочтительнее хранить `,(0,c.jsx)(t.code,{children:`surname`}),`, `,(0,c.jsx)(t.code,{children:`name`}),`, `,(0,c.jsx)(t.code,{children:`patronymic`}),` отдельно и собирать нужное представление явно.`]}),`
+`,(0,c.jsx)(t.h2,{id:`российский-телефон`,children:`Российский телефон`}),`
+`,(0,c.jsx)(t.h3,{id:`clearphonenumber`,children:(0,c.jsx)(t.code,{children:`clearPhone(number)`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function clearPhone(number: string): string;
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Функция:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsx)(t.li,{children:`удаляет все нецифровые символы;`}),`
+`,(0,c.jsx)(t.li,{children:`оставляет первые 11 цифр;`}),`
+`,(0,c.jsxs)(t.li,{children:[`удаляет первый символ, если это `,(0,c.jsx)(t.code,{children:`7`}),` или `,(0,c.jsx)(t.code,{children:`8`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`добавляет префикс `,(0,c.jsx)(t.code,{children:`+7`}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`clearPhone("8 (912) 345-67-89"); // "+79123456789"
+clearPhone("+7 912 345-67-89 доб. 42"); // "+79123456789"
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Название `,(0,c.jsx)(t.code,{children:`clearPhone`}),` не означает строгую очистку до валидного E.164. Функция всегда добавляет `,(0,c.jsx)(t.code,{children:`+7`}),` и не проверяет количество цифр:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`clearPhone(""); // "+7"
+clearPhone("123"); // "+7123"
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Если передать 11 цифр, которые начинаются не с `,(0,c.jsx)(t.code,{children:`7`}),` и не с `,(0,c.jsx)(t.code,{children:`8`}),`, все 11 останутся после добавленного `,(0,c.jsx)(t.code,{children:`+7`}),`, то есть результат не будет валидным российским номером.`]}),`
+`,(0,c.jsx)(t.h3,{id:`formatphonenumber`,children:(0,c.jsx)(t.code,{children:`formatPhone(number)`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Форматирует только результат, который строго совпал с `,(0,c.jsx)(t.code,{children:`+7`}),` и десятью цифрами:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatPhone("8 (912) 345-67-89");
+// "+7 (912) 345-67-89"
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Если после `,(0,c.jsx)(t.code,{children:`clearPhone`}),` не получился полный шаблон, возвращается исходная строка `,(0,c.jsx)(t.code,{children:`number`}),`, а не частично очищённое значение:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`formatPhone("123"); // "123"
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Это display helper, а не validator. Для формы телефона отдельно проверяйте контракт номера и храните явное transport-представление.`}),`
+`,(0,c.jsx)(t.h2,{id:`ведущие-нули`,children:`Ведущие нули`}),`
+`,(0,c.jsx)(t.p,{children:`В модуле есть две функции с различной семантикой.`}),`
+`,(0,c.jsx)(t.h3,{id:`normalizeleadingzerosvalue-fixed`,children:(0,c.jsx)(t.code,{children:`normalizeLeadingZeros(value, fixed?)`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function normalizeLeadingZeros(value: unknown, fixed?: number): unknown;
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Сначала функция приводит значение к числу через `,(0,c.jsx)(t.code,{children:`Number(value)`}),`. Если результат не finite, исходное значение возвращается без изменений. Затем число снова превращается в строку, поэтому исходное форматирование теряется.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`При положительном `,(0,c.jsx)(t.code,{children:`fixed`}),` целая часть дополняется слева:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`normalizeLeadingZeros("42", 5); // "00042"
+normalizeLeadingZeros(-12.3, 4); // "-0012.3"
+normalizeLeadingZeros("00042", 5); // "00042"
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`При отсутствии положительного `,(0,c.jsx)(t.code,{children:`fixed`}),` возвращается `,(0,c.jsx)(t.code,{children:`String(Number(value))`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`normalizeLeadingZeros("00042"); // "42"
+normalizeLeadingZeros("00042", 0); // "42"
+normalizeLeadingZeros("00042", -1); // "42"
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Это важное отличие от комментария «ничего не делает»: для parseable входа функция всё равно нормализует его через number/string.`}),`
+`,(0,c.jsx)(t.p,{children:`JavaScript coercion также означает:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`normalizeLeadingZeros(null); // "0"
+normalizeLeadingZeros(""); // "0"
+normalizeLeadingZeros(false); // "0"
+normalizeLeadingZeros(true); // "1"
+normalizeLeadingZeros(undefined); // undefined
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Используйте положительное целое `,(0,c.jsx)(t.code,{children:`fixed`}),`. Дробное, бесконечное или экстремально большое значение не является поддержанным пользовательским контрактом.`]}),`
+`,(0,c.jsx)(t.h3,{id:`normalizeleadingzerosstrictvalue-fixed`,children:(0,c.jsx)(t.code,{children:`normalizeLeadingZerosStrict(value, fixed?)`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function normalizeLeadingZerosStrict<T>(value: T, fixed?: number): T;
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Эта версия предназначена для строк с SAP-like grouping/decimal separators и старается сохранить тип входа.`}),`
+`,(0,c.jsxs)(t.p,{children:[`Если `,(0,c.jsx)(t.code,{children:`fixed`}),` отсутствует, равен `,(0,c.jsx)(t.code,{children:`0`}),`, `,(0,c.jsx)(t.code,{children:`NaN`}),` или бесконечности, возвращается строго исходное значение:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const input = " 001 234,50 ";
+normalizeLeadingZerosStrict(input); // та же строка с пробелами
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Для строк:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`проверяется наличие хотя бы одной цифры;`}),`
+`,(0,c.jsxs)(t.li,{children:[`число должно успешно читаться через `,(0,c.jsx)(t.code,{children:`toFiniteNumber`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`внешние пробелы удаляются;`}),`
+`,(0,c.jsx)(t.li,{children:`grouping spaces из целой части удаляются;`}),`
+`,(0,c.jsxs)(t.li,{children:[`первый `,(0,c.jsx)(t.code,{children:`.`}),` или `,(0,c.jsx)(t.code,{children:`,`}),` и дробная часть сохраняются;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`fixed < 0`}),` удаляет ведущие нули;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`fixed > 0`}),` дополняет целую часть до длины.`]}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`normalizeLeadingZerosStrict(" 00012,50 ", -1); // "12,50"
+normalizeLeadingZerosStrict("12,50", 5); // "00012,50"
+normalizeLeadingZerosStrict("1 234,50", 6); // "001234,50"
+normalizeLeadingZerosStrict("not-a-number", 5); // исходная строка
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Для number функция возвращает number. Поэтому видимые ведущие нули исчезают при обратном преобразовании:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`normalizeLeadingZerosStrict(12, 5); // 12, не "00012"
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Остальные типы (`,(0,c.jsx)(t.code,{children:`null`}),`, object, boolean и т. п.) возвращаются без изменений.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Внутри `,(0,c.jsx)(t.code,{children:`fixed`}),` приводится к 32-bit integer через bitwise operation. Передавайте небольшое целое число; дробные и очень большие значения могут быть преобразованы неожиданно.`]}),`
+`,(0,c.jsx)(t.h3,{id:`как-выбрать`,children:`Как выбрать`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Ситуация`}),(0,c.jsx)(t.th,{children:`Выбор`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsxs)(t.td,{children:[`Простое значение, допустим `,(0,c.jsx)(t.code,{children:`Number(value)`})]}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`normalizeLeadingZeros`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsxs)(t.td,{children:[`Нужно сохранить строковый `,(0,c.jsx)(t.code,{children:`,`}),` и fraction`]}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`normalizeLeadingZerosStrict`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Есть grouping spaces`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`normalizeLeadingZerosStrict`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Number должен остаться number`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`normalizeLeadingZerosStrict`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Нужен гарантированный display с нулями для number`}),(0,c.jsxs)(t.td,{children:[`сначала явно `,(0,c.jsx)(t.code,{children:`String`}),`, затем strict или обычная функция`]})]})]})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Не применяйте ведущие нули к бизнес-идентификаторам без уверенности: `,(0,c.jsx)(t.code,{children:`00123`}),` может быть отдельным значимым кодом, а не числом.`]}),`
+`,(0,c.jsx)(t.h2,{id:`boolean`,children:`Boolean`}),`
+`,(0,c.jsx)(t.p,{children:`Три функции имеют намеренно разные контракты:`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`API`}),(0,c.jsx)(t.th,{children:`Краткое правило`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`parseAbapBoolean`})}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`true`}),` только для точного `,(0,c.jsx)(t.code,{children:`"X"`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`parseBoolean`})}),(0,c.jsxs)(t.td,{children:[`строки `,(0,c.jsx)(t.code,{children:`true`}),`, `,(0,c.jsx)(t.code,{children:`x`}),`, `,(0,c.jsx)(t.code,{children:`1`}),` без учёта регистра; прочие values через truthy/falsy`]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`toAbapBoolean`})}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`"X"`}),` или `,(0,c.jsx)(t.code,{children:`" "`}),`; среди строк только точное `,(0,c.jsx)(t.code,{children:`"0"`}),` считается false`]})]})]})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Последнее правило особенно неочевидно: `,(0,c.jsx)(t.code,{children:`toAbapBoolean("")`}),` и `,(0,c.jsx)(t.code,{children:`toAbapBoolean("false")`}),` возвращают `,(0,c.jsx)(t.code,{children:`"X"`}),`. Полная таблица и безопасные recipes приведены в `,(0,c.jsx)(t.a,{href:`./boolean/README.mdx`,children:`boolean/README.mdx`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`строки`,children:`Строки`}),`
+`,(0,c.jsx)(t.p,{children:`Строковое семейство включает:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`normalizeText*`}),` и `,(0,c.jsx)(t.code,{children:`toSafeString`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`normalizeTextSpaces`}),` и `,(0,c.jsx)(t.code,{children:`stripInnerSpaces`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`stripLeadingZeros`}),` и `,(0,c.jsx)(t.code,{children:`startsWithIgnoringZeros`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`truncateText`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`русские plural forms.`}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Точные различия пустой строки, fallback, whitespace и Unicode описаны в `,(0,c.jsx)(t.a,{href:`./strings/README.mdx`,children:`strings/README.mdx`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`даты`,children:`Даты`}),`
+`,(0,c.jsxs)(t.p,{children:[`Date API различает floating calendar и instant timezone parsing, поддерживает ABAP/OData, Intl/pattern presets, ranges, periods и учебный календарь. Начните с `,(0,c.jsx)(t.a,{href:`./date/README.mdx`,children:`date/README.mdx`}),`, особенно с раздела о timezone.`]}),`
+`,(0,c.jsx)(t.h2,{id:`числа`,children:`Числа`}),`
+`,(0,c.jsxs)(t.p,{children:[`Числовой API различает `,(0,c.jsx)(t.code,{children:`formatNumber`}),` с обычным `,(0,c.jsx)(t.code,{children:`Number(value)`}),` и SAP-like parser `,(0,c.jsx)(t.code,{children:`toFiniteNumber`}),`. Presets, compact formatting, `,(0,c.jsx)(t.code,{children:`OrEmpty`}),` и registry lifecycle подробно разобраны в `,(0,c.jsx)(t.a,{href:`./number/README.mdx`,children:`number/README.mdx`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`value-state`,children:`Value state`}),`
+`,(0,c.jsxs)(t.p,{children:[`Fixed resolver сопоставляет точные строковые keys, threshold resolver делит число на сегменты. Registry ids, boundary semantics и presentation helpers описаны в `,(0,c.jsx)(t.a,{href:`./valueState/README.mdx`,children:`valueState/README.mdx`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`formatter-pipeline`,children:`Formatter pipeline`}),`
+`,(0,c.jsxs)(t.p,{children:[`Pipeline последовательно применяет `,(0,c.jsx)(t.code,{children:`rowBasedOverride`}),`, leading zeros, value state и typed formatting. Он поддерживает сериализуемые plan/graph configs, validation, dependency collection и construction-stage compilation.`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.a,{href:`./pipeline/README.mdx`,children:`pipeline/README.mdx`}),` — основной runtime и config API;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.a,{href:`./rowBased/README.mdx`,children:`rowBased/README.mdx`}),` — host-defined formulas и их registry.`]}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`пример-единой-конфигурации-приложения`,children:`Пример единой конфигурации приложения`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	configureRowBasedFormatterRegistry,
+	createRowBasedFormatterRegistry,
+	registerDatePreset,
+	registerNumberPreset,
+	type RowBasedFormatterDefinition
+} from "@ryuzaki13/react-foundation-lib/formatters";
+
+const rowBasedDefinitions: RowBasedFormatterDefinition[] = [
+	{
+		id: "completion-percent",
+		name: "Процент выполнения",
+		description: "actual / planned * 100; dependencies: planned, actual",
+		fn: (ctx) => {
+			const planned = ctx.num(0);
+			return planned === 0 ? undefined : (ctx.num(1) / planned) * 100;
+		}
+	}
+];
+
+export function configureApplicationFormatters(): void {
+	registerDatePreset({
+		name: "document-date",
+		pattern: "dd.MM.yyyy",
+		invalidFallback: "—"
+	});
+
+	registerNumberPreset({
+		name: "quantity-4",
+		decimals: 4
+	});
+
+	configureRowBasedFormatterRegistry(createRowBasedFormatterRegistry(rowBasedDefinitions));
+}
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Вызовите bootstrap-функцию до чтения пользовательских formatter configs и компиляции runtime fields.`}),`
+`,(0,c.jsx)(t.h2,{id:`тестирование-formatter-кода`,children:`Тестирование formatter-кода`}),`
+`,(0,c.jsx)(t.p,{children:`Проверяйте не только «обычный» пример:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`null`}),`, `,(0,c.jsx)(t.code,{children:`undefined`}),`, `,(0,c.jsx)(t.code,{children:`""`}),`, whitespace;`]}),`
+`,(0,c.jsx)(t.li,{children:`неправильный тип;`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`NaN`}),`, `,(0,c.jsx)(t.code,{children:`Infinity`}),`, отрицательный ноль;`]}),`
+`,(0,c.jsx)(t.li,{children:`границы threshold и date ranges;`}),`
+`,(0,c.jsx)(t.li,{children:`timezone среды для date parsing;`}),`
+`,(0,c.jsx)(t.li,{children:`NBSP/NNBSP в числах и строках;`}),`
+`,(0,c.jsx)(t.li,{children:`неизвестный preset/formula id;`}),`
+`,(0,c.jsx)(t.li,{children:`reset глобального реестра между тестами;`}),`
+`,(0,c.jsxs)(t.li,{children:[`точный тип результата (`,(0,c.jsx)(t.code,{children:`number`}),`, `,(0,c.jsx)(t.code,{children:`string`}),`, `,(0,c.jsx)(t.code,{children:`undefined`}),`).`]}),`
+`]}),`
+`,(0,c.jsx)(t.p,{children:`Formatter output часто содержит locale-specific неразрывный пробел. В тесте лучше сравнивать точный ожидаемый Unicode-контракт либо явно нормализовать только тогда, когда это разрешено задачей.`}),`
+`,(0,c.jsx)(t.h2,{id:`частые-архитектурные-ошибки`,children:`Частые архитектурные ошибки`}),`
+`,(0,c.jsx)(t.h3,{id:`deep-import-из-исходников`,children:`Deep import из исходников`}),`
+`,(0,c.jsxs)(t.p,{children:[`В consumer разрешён только опубликованный `,(0,c.jsx)(t.code,{children:`/formatters`}),`. Внутренние пути могут исчезнуть и не входят в npm `,(0,c.jsx)(t.code,{children:`exports`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`своя-копия-formatter-а-в-приложении`,children:`Своя копия formatter-а в приложении`}),`
+`,(0,c.jsxs)(t.p,{children:[`Если правило является общим техническим и уже покрыто модулем, используйте существующий API. Если действительно не хватает общего контракта, расширяйте foundation package и его публичный `,(0,c.jsx)(t.code,{children:`index.ts`}),`, а не копируйте helper локально.`]}),`
+`,(0,c.jsx)(t.h3,{id:`смешивание-display-и-transport`,children:`Смешивание display и transport`}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`formatPhone`}),` создаёт человекочитаемый телефон, `,(0,c.jsx)(t.code,{children:`formatDateAsDateLong`}),` — локализованную дату, `,(0,c.jsx)(t.code,{children:`formatNumberAsDecimal2`}),` — UI-число. Не отправляйте display strings в API без явного transport-контракта.`]}),`
+`,(0,c.jsx)(t.h3,{id:`невидимое-подавление-ошибок`,children:`Невидимое подавление ошибок`}),`
+`,(0,c.jsxs)(t.p,{children:[`Некоторые formatters возвращают `,(0,c.jsx)(t.code,{children:`""`}),` или `,(0,c.jsx)(t.code,{children:`"0"`}),` для ошибки. Если источник ненадёжен, используйте parser/validator до formatter-а и решайте fallback явно.`]}),`
+`,(0,c.jsx)(t.h3,{id:`глобальная-настройка-во-время-рендера`,children:`Глобальная настройка во время рендера`}),`
+`,(0,c.jsx)(t.p,{children:`Preset и formula registries — application configuration, а не component state.`}),`
+`,(0,c.jsx)(t.h2,{id:`публичная-граница`,children:`Публичная граница`}),`
+`,(0,c.jsxs)(t.p,{children:[`Фактическим источником истины является `,(0,c.jsx)(t.a,{href:`./index.ts`,children:(0,c.jsx)(t.code,{children:`index.ts`})}),`. Документируются только exports, достижимые через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/formatters`}),`.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Например, внутренний файл `,(0,c.jsx)(t.code,{children:`formatTagAsHashtag.ts`}),` сейчас не экспортирован из публичного index и поэтому не является поддерживаемым API. Наличие файла в repository не разрешает consumer делать private import.`]}),`
+`,(0,c.jsx)(t.h2,{id:`следующий-шаг`,children:`Следующий шаг`}),`
+`,(0,c.jsxs)(t.p,{children:[`Если нужна одна простая функция, выберите строку в таблице быстрого выбора. Если настраивается таблица или сохраняемый пользовательский config, начните с `,(0,c.jsx)(t.a,{href:`./pipeline/README.mdx`,children:`formatter pipeline`}),` и затем откройте документы зависимых областей.`]})]})}function s(e={}){let{wrapper:t}={...n(),...e.components};return t?(0,c.jsx)(t,{...e,children:(0,c.jsx)(o,{...e})}):o(e)}var c;function l(){return(l=e((()=>{c=t(),r(),a()})))()}l();export{s as default};