@ryuzaki13/react-foundation-ui 1.8.11 → 1.8.12

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

@@ -0,0 +1,64 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-FSp_AjJa.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-B5YBxaaS.js";function o(e){let t={code:`code`,h1:`h1`,h2:`h2`,li:`li`,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/Data/String Comparison`}),`
+`,(0,c.jsxs)(t.h1,{id:`сравнение-строк-через-ryuzaki13react-foundation-libstring-comparison`,children:[`Сравнение строк через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/string-comparison`})]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`compareStrings`}),` задаёт единый порядок строк для русскоязычных UI-списков, смешанной кириллицы/латиницы и числовых суффиксов.`]}),`
+`,(0,c.jsx)(t.h2,{id:`установка-и-импорт`,children:`Установка и импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { compareStrings } from "@ryuzaki13/react-foundation-lib/string-comparison";
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль использует стандартный `,(0,c.jsx)(t.code,{children:`Intl.Collator`}),` и не зависит от React.`]}),`
+`,(0,c.jsx)(t.h2,{id:`использование`,children:`Использование`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const names = ["item10", "item2", "item1"];
+const sorted = [...names].sort(compareStrings);
+
+console.log(sorted); // ["item1", "item2", "item10"].
+console.log(names); // Исходный массив не изменён из-за [...names].
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Важно: сам `,(0,c.jsx)(t.code,{children:`Array.prototype.sort`}),` мутирует массив. `,(0,c.jsx)(t.code,{children:`compareStrings`}),` только comparator.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`names.sort(compareStrings); // names изменится.
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`правила-сравнения`,children:`Правила сравнения`}),`
+`,(0,c.jsx)(t.p,{children:`Основной collator настроен так:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`new Intl.Collator("ru-RU", {
+	usage: "sort",
+	sensitivity: "base",
+	numeric: true
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Это означает:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`locale фиксирован как `,(0,c.jsx)(t.code,{children:`ru-RU`}),`, а не зависит от системного языка;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`числовые части сравниваются как числа: `,(0,c.jsx)(t.code,{children:`item2`}),` раньше `,(0,c.jsx)(t.code,{children:`item10`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`основной проход не различает регистр и часть диакритики;`}),`
+`,(0,c.jsx)(t.li,{children:`если collator считает разные строки равными, применяется строгий UTF-16 fallback;`}),`
+`,(0,c.jsxs)(t.li,{children:[`результат нормализуется до `,(0,c.jsx)(t.code,{children:`-1`}),`, `,(0,c.jsx)(t.code,{children:`0`}),` или `,(0,c.jsx)(t.code,{children:`1`}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`["a", "A"].sort(compareStrings); // ["A", "a"].
+`})}),`
+`,(0,c.jsx)(t.p,{children:`UTF-16 fallback нужен для детерминированного порядка, а не для лингвистической оценки регистра.`}),`
+`,(0,c.jsx)(t.h2,{id:`контракт-comparator`,children:`Контракт comparator`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function compareStrings(left: string, right: string): number;
+`})}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{style:{textAlign:`right`},children:`Результат`}),(0,c.jsx)(t.th,{children:`Значение`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{style:{textAlign:`right`},children:(0,c.jsx)(t.code,{children:`-1`})}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`left`}),` должен находиться раньше `,(0,c.jsx)(t.code,{children:`right`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{style:{textAlign:`right`},children:(0,c.jsx)(t.code,{children:`0`})}),(0,c.jsx)(t.td,{children:`строки полностью равны для итогового comparator`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{style:{textAlign:`right`},children:(0,c.jsx)(t.code,{children:`1`})}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`left`}),` должен находиться позже `,(0,c.jsx)(t.code,{children:`right`})]})]})]})]}),`
+`,(0,c.jsx)(t.p,{children:`Подходящие места:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`array.sort`}),` / `,(0,c.jsx)(t.code,{children:`toSorted`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`сортировка labels справочника;`}),`
+`,(0,c.jsx)(t.li,{children:`предсказуемый порядок смешанных технических и русских названий;`}),`
+`,(0,c.jsx)(t.li,{children:`tie-breaker после бизнес-сортировки.`}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`ограничения`,children:`Ограничения`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[`Аргументы должны быть strings; функция не приводит `,(0,c.jsx)(t.code,{children:`null`}),`/число.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Это UI-сортировка, а не database collation или backend `,(0,c.jsx)(t.code,{children:`$orderby`}),`.`]}),`
+`,(0,c.jsx)(t.li,{children:`Не используйте comparator для equality/identity: разные строки могут быть близки по основной collation.`}),`
+`,(0,c.jsx)(t.li,{children:`Порядок не является Unicode normalization; при необходимости нормализуйте вход на явной boundary.`}),`
+`,(0,c.jsx)(t.li,{children:`Для server-side таблицы сортировку полного набора должен выполнять backend, а не одна загруженная страница.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Runtime должен поддерживать `,(0,c.jsx)(t.code,{children:`Intl.Collator`}),` и locale data `,(0,c.jsx)(t.code,{children:`ru-RU`}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`пример-с-объектами`,children:`Пример с объектами`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type Option = { id: string; label: string };
+
+const sortedOptions = options.toSorted((left, right) => {
+	const byLabel = compareStrings(left.label, right.label);
+	return byLabel !== 0 ? byLabel : compareStrings(left.id, right.id);
+});
+`})})]})}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};

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

@@ -0,0 +1,75 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-FSp_AjJa.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-B5YBxaaS.js";function o(e){let t={code:`code`,h1:`h1`,h2:`h2`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,ul:`ul`,...n(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(i,{title:`Foundation Lib/Forms/Form Errors`}),`
+`,(0,c.jsxs)(t.h1,{id:`чтение-первой-ошибки-формы-через-ryuzaki13react-foundation-libform`,children:[`Чтение первой ошибки формы через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/form`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль содержит одну функцию `,(0,c.jsx)(t.code,{children:`readFirstFormError`}),`. Она получает неоднородный массив ошибок и возвращает первое найденное текстовое сообщение.`]}),`
+`,(0,c.jsx)(t.h2,{id:`установка-и-импорт`,children:`Установка и импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import { readFirstFormError } from "@ryuzaki13/react-foundation-lib/form";
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Модуль ESM, не зависит от React и не привязан к конкретной form library.`}),`
+`,(0,c.jsx)(t.h2,{id:`поддерживаемые-формы-ошибки`,children:`Поддерживаемые формы ошибки`}),`
+`,(0,c.jsx)(t.p,{children:`Функция понимает:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsx)(t.li,{children:`Строку.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Объект с непустым строковым полем `,(0,c.jsx)(t.code,{children:`message`}),`.`]}),`
+`,(0,c.jsx)(t.li,{children:`Вложенный массив таких значений.`}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`readFirstFormError([undefined, { message: "Поле обязательно" }]);
+// "Поле обязательно".
+
+readFirstFormError([[null, "Неверный формат"], "Другая ошибка"]);
+// "Неверный формат".
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Обычный `,(0,c.jsx)(t.code,{children:`Error`}),` также подходит, потому что имеет строковое поле `,(0,c.jsx)(t.code,{children:`message`}),`:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`readFirstFormError([new Error("Ошибка проверки")]);
+// "Ошибка проверки".
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`алгоритм`,children:`Алгоритм`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`errors отсутствует ──► undefined
+        │
+        ▼
+обход слева направо
+        │
+        ├─ string ─────────► вернуть строку
+        ├─ array ──────────► рекурсивно найти первую строку
+        ├─ { message } ────► вернуть непустой string message
+        └─ другое ─────────► пропустить
+`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const message = readFirstFormError(errors);
+
+if (message) {
+	showFieldError(message);
+}
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`точные-правила`,children:`Точные правила`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`undefined`}),` вместо массива возвращает `,(0,c.jsx)(t.code,{children:`undefined`}),`.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`Пустой массив возвращает `,(0,c.jsx)(t.code,{children:`undefined`}),`.`]}),`
+`,(0,c.jsx)(t.li,{children:`Поиск идёт в исходном порядке.`}),`
+`,(0,c.jsx)(t.li,{children:`Пустая строка не является результатом и поиск продолжается.`}),`
+`,(0,c.jsx)(t.li,{children:`Строка из пробелов считается непустой и возвращается буквально.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Числа, boolean, functions, `,(0,c.jsx)(t.code,{children:`null`}),` и объекты без string `,(0,c.jsx)(t.code,{children:`message`}),` пропускаются.`]}),`
+`,(0,c.jsx)(t.li,{children:`Массивы обходятся рекурсивно без ограничения глубины.`}),`
+`,(0,c.jsx)(t.li,{children:`Входные массивы и objects не изменяются.`}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`пример-в-react`,children:`Пример в React`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`type FieldErrorProps = {
+	errors?: readonly unknown[];
+};
+
+export function FieldError({ errors }: FieldErrorProps) {
+	const message = readFirstFormError(errors);
+
+	return message ? <p role="alert">{message}</p> : null;
+}
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Для нескольких ошибок, summary списка, локализации и сопоставления ошибки конкретному field нужен отдельный form-layer host-приложения.`}),`
+`,(0,c.jsx)(t.h2,{id:`ограничения-и-ошибки`,children:`Ограничения и ошибки`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`Функция не выполняет trim или перевод сообщений.`}),`
+`,(0,c.jsx)(t.li,{children:`Она не проверяет schema form-library.`}),`
+`,(0,c.jsx)(t.li,{children:`Возвращается только первое сообщение; остальные теряются для этого вызова.`}),`
+`,(0,c.jsx)(t.li,{children:`Циклический массив приведёт к бесконечной рекурсии/ошибке call stack.`}),`
+`,(0,c.jsx)(t.li,{children:`Не передавайте backend payload напрямую без runtime-проверки и безопасного отображения.`}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`api`,children:`API`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`function readFirstFormError(errors: readonly unknown[] | undefined): string | undefined;
+`})})]})}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};

package/storybook-static/assets/{README-CTIBG4zH.js → README-CIGfHKKE.js}

@@ -1,4 +1,4 @@
-import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-Sr0umHM6.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-DndFRxxW.js";function o(e){let t={a:`a`,code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,h4:`h4`,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/Array`}),`
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-FSp_AjJa.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-B5YBxaaS.js";function o(e){let t={a:`a`,code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,h4:`h4`,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/Array`}),`
 `,(0,c.jsxs)(t.h1,{id:`работа-с-массивами-через-ryuzaki13react-foundation-libarray`,children:[`Работа с массивами через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/array`})]}),`
 `,(0,c.jsxs)(t.p,{children:[`Модуль `,(0,c.jsx)(t.code,{children:`array`}),` содержит небольшие типизированные функции для типовых операций с массивами:`]}),`
 `,(0,c.jsxs)(t.ul,{children:[`

package/storybook-static/assets/{README-BHw6MVjD.js → README-CM-7E-Jf.js}

@@ -1,4 +1,4 @@
-import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-Sr0umHM6.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-DndFRxxW.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/Row-Based`}),`
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-FSp_AjJa.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-B5YBxaaS.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/Row-Based`}),`
 `,(0,c.jsx)(t.h1,{id:`row-based-форматтеры`,children:`Row-based форматтеры`}),`
 `,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`rowBased`}),` — небольшой runtime-слой для формул, которые вычисляют отображаемое значение одной ячейки на основании других полей той же строки.`]}),`
 `,(0,c.jsxs)(t.p,{children:[`Он используется шагом `,(0,c.jsx)(t.code,{children:`rowBasedOverride`}),` в `,(0,c.jsx)(t.a,{href:`../pipeline/README.mdx`,children:`formatter pipeline`}),`. Сам модуль не содержит бизнес-формул: host-приложение создаёт их, собирает в реестр и один раз передаёт реестр библиотеке.`]}),`

package/storybook-static/assets/{README-C0BwTe5N.js → README-CNHemCS2.js}

@@ -1,4 +1,4 @@
-import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-Sr0umHM6.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-DndFRxxW.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/Number`}),`
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-FSp_AjJa.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-B5YBxaaS.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/Number`}),`
 `,(0,c.jsx)(t.h1,{id:`числовые-форматтеры`,children:`Числовые форматтеры`}),`
 `,(0,c.jsx)(t.p,{children:`Модуль форматирует числа для интерфейса, читает распространённые SAP-подобные числовые строки и управляет реестром именованных presets.`}),`
 `,(0,c.jsx)(t.p,{children:`Все API доступны через один публичный entrypoint:`}),`

package/storybook-static/assets/{README-DzTc6XmY.js → README-CWfPiPIB.js}

@@ -1,4 +1,4 @@
-import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-Sr0umHM6.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-DndFRxxW.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/Strings`}),`
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-FSp_AjJa.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-B5YBxaaS.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/Strings`}),`
 `,(0,c.jsx)(t.h1,{id:`строковые-форматтеры`,children:`Строковые форматтеры`}),`
 `,(0,c.jsx)(t.p,{children:`Модуль содержит небольшие предсказуемые функции для подготовки пользовательского текста: обрезки пробелов, безопасного преобразования в строку, удаления ведущих нулей, сокращения длинного текста и выбора русской формы слова.`}),`
 `,(0,c.jsx)(t.p,{children:`Все функции экспортируются через один публичный entrypoint:`}),`

package/storybook-static/assets/{README-Dx3cpFMr.js → README-CeK4kfFO.js}

@@ -1,4 +1,4 @@
-import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-Sr0umHM6.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-DndFRxxW.js";function o(e){let t={a:`a`,code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,li:`li`,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/Date`}),`
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-FSp_AjJa.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-B5YBxaaS.js";function o(e){let t={a:`a`,code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,li:`li`,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/Date`}),`
 `,(0,c.jsx)(t.h1,{id:`даты-время-и-календарные-диапазоны`,children:`Даты, время и календарные диапазоны`}),`
 `,(0,c.jsx)(t.p,{children:`Модуль решает четыре связанные задачи:`}),`
 `,(0,c.jsxs)(t.ul,{children:[`

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

@@ -0,0 +1,178 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-FSp_AjJa.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-B5YBxaaS.js";function o(e){let t={code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,li:`li`,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 API/Orchestration/Async Tasks`}),`
+`,(0,c.jsxs)(t.h1,{id:`асинхронные-задачи-через-ryuzaki13react-foundation-apiasync`,children:[`Асинхронные задачи через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-api/async`})]}),`
+`,(0,c.jsx)(t.p,{children:`Модуль запускает независимые Promise-задачи, сохраняет связь результата с исходным элементом и формирует удобную сводку для UI/логов.`}),`
+`,(0,c.jsx)(t.h2,{id:`какой-runner-выбрать`,children:`Какой runner выбрать`}),`
+`,(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:`Задач немного, можно начать все одновременно, любая ошибка должна завершить batch исключением`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`runAsyncTasks`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Нужно ограничить число одновременных запросов, показать progress или поддержать abort`}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`runConcurrentTasks`})})]})]})]}),`
+`,(0,c.jsx)(t.p,{children:`Обе функции выполняют задачи параллельно. Они не создают web workers и не ускоряют CPU-bound JavaScript: Promise-concurrency полезна прежде всего для I/O — HTTP, чтения storage и других async операций.`}),`
+`,(0,c.jsx)(t.h2,{id:`импорт`,children:`Импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	AsyncTasksError,
+	ConcurrencyPartialError,
+	runAsyncTasks,
+	runConcurrentTasks
+} from "@ryuzaki13/react-foundation-api/async";
+
+import type {
+	AsyncTask,
+	RunAsyncTasksResult,
+	RunConcurrentTasksOptions,
+	RunConcurrentTasksResult
+} from "@ryuzaki13/react-foundation-api/async";
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Модуль не требует React или TanStack Query.`}),`
+`,(0,c.jsxs)(t.h2,{id:`база-async-promise-и-await`,children:[`База: `,(0,c.jsx)(t.code,{children:`async`}),`, `,(0,c.jsx)(t.code,{children:`Promise`}),` и `,(0,c.jsx)(t.code,{children:`await`})]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`async`}),`-функция всегда возвращает `,(0,c.jsx)(t.code,{children:`Promise`}),`. `,(0,c.jsx)(t.code,{children:`await`}),` приостанавливает только текущую async-функцию, а не весь browser thread:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`async function loadName() {
+	const response = await fetch("/api/me");
+	return response.text();
+}
+
+const namePromise = loadName(); // Promise<string>.
+const name = await namePromise; // string.
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Ошибку Promise обрабатывают через `,(0,c.jsx)(t.code,{children:`try/catch`}),` вокруг `,(0,c.jsx)(t.code,{children:`await`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`runasynctasks`,children:(0,c.jsx)(t.code,{children:`runAsyncTasks`})}),`
+`,(0,c.jsx)(t.h3,{id:`быстрый-старт`,children:`Быстрый старт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const result = await runAsyncTasks([
+	{ name: "profile", run: () => fetchProfile() },
+	{ name: "settings", run: () => fetchSettings() }
+]);
+
+console.log(result.summary);
+// { total: 2, succeeded: 2, failed: 0 }
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Все `,(0,c.jsx)(t.code,{children:`run`}),` запускаются сразу через `,(0,c.jsx)(t.code,{children:`Promise.all`}),`. Важное отличие от обычного `,(0,c.jsx)(t.code,{children:`Promise.all`}),`: ошибка одной задачи перехватывается внутри runner-а, поэтому остальные задачи успевают завершиться. После завершения всего batch функция либо возвращает полный результат, либо бросает `,(0,c.jsx)(t.code,{children:`AsyncTasksError`}),` с тем же полным результатом.`]}),`
+`,(0,c.jsx)(t.h3,{id:`обработка-частичного-успеха`,children:`Обработка частичного успеха`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`try {
+	const result = await runAsyncTasks(tasks, {
+		errorMessage: "Не все стартовые данные загрузились"
+	});
+	useData(result.successes);
+} catch (error) {
+	if (error instanceof AsyncTasksError) {
+		usePartialData(error.result.successes);
+		showErrors(error.result.errors);
+		return;
+	}
+
+	throw error;
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`AsyncTasksError.result`}),` содержит:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type RunAsyncTasksResult<TResult> = {
+	settled: readonly AsyncTaskSettled<TResult>[];
+	successes: readonly AsyncTaskSuccess<TResult>[];
+	errors: readonly AsyncTaskFailure[];
+	summary: {
+		total: number;
+		succeeded: number;
+		failed: number;
+	};
+};
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Элементы `,(0,c.jsx)(t.code,{children:`settled`}),`, `,(0,c.jsx)(t.code,{children:`successes`}),` и `,(0,c.jsx)(t.code,{children:`errors`}),` сохраняют порядок исходного массива. Каждый элемент содержит `,(0,c.jsx)(t.code,{children:`index`}),` и `,(0,c.jsx)(t.code,{children:`name`}),`.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`if (item.status === "fulfilled") {
+	console.log(item.data);
+} else {
+	console.error(item.error);
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`TypeScript сужает union по `,(0,c.jsx)(t.code,{children:`status`}),`.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Пустой список возвращает успешный пустой результат. `,(0,c.jsx)(t.code,{children:`runAsyncTasks`}),` не имеет встроенного concurrency limit и AbortSignal.`]}),`
+`,(0,c.jsx)(t.h2,{id:`runconcurrenttasks`,children:(0,c.jsx)(t.code,{children:`runConcurrentTasks`})}),`
+`,(0,c.jsx)(t.h3,{id:`ограничение-одновременных-запросов`,children:`Ограничение одновременных запросов`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const result = await runConcurrentTasks(
+	userIds,
+	async (userId, { signal }) => {
+		const response = await fetch(\`/api/users/\${userId}\`, { signal });
+		if (!response.ok) throw new Error(\`HTTP \${response.status}\`);
+		return response.json();
+	},
+	{ concurrency: 4 }
+);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Не более четырёх задач будут находиться в работе одновременно. Значение по умолчанию — `,(0,c.jsx)(t.code,{children:`4`}),`. Если элементов меньше, workers создаются только по числу элементов.`]}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`concurrency`}),` обязан быть целым числом не меньше `,(0,c.jsx)(t.code,{children:`1`}),`:`]}),`
+`,(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.jsx)(t.code,{children:`4`})}),(0,c.jsx)(t.td,{children:`Работает`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`1`})}),(0,c.jsx)(t.td,{children:`Последовательное выполнение`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`0`}),`, `,(0,c.jsx)(t.code,{children:`-1`})]}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`RangeError`})})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`1.5`}),`, `,(0,c.jsx)(t.code,{children:`NaN`})]}),(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`TypeError`})})]})]})]}),`
+`,(0,c.jsx)(t.h3,{id:`ошибки-отдельных-элементов`,children:`Ошибки отдельных элементов`}),`
+`,(0,c.jsxs)(t.p,{children:[`Runner не бросает ошибки отдельных задач. Он помещает их в `,(0,c.jsx)(t.code,{children:`result.errors`}),` и продолжает обработку:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const result = await runConcurrentTasks(inputs, task);
+
+if (result.errors.length > 0) {
+	for (const failure of result.errors) {
+		console.error(failure.index, failure.input, failure.error);
+	}
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Исключение самой функции возможно при невалидном `,(0,c.jsx)(t.code,{children:`concurrency`}),` или если callback `,(0,c.jsx)(t.code,{children:`onProgress`}),`/`,(0,c.jsx)(t.code,{children:`onItemSuccess`}),`/`,(0,c.jsx)(t.code,{children:`onItemError`}),` сам бросил ошибку. Callbacks должны быть безопасными и быстрыми.`]}),`
+`,(0,c.jsx)(t.h3,{id:`progress`,children:`Progress`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`await runConcurrentTasks(files, uploadFile, {
+	concurrency: 3,
+	onProgress(progress) {
+		setProgress(progress.percentage);
+	},
+	onItemSuccess(item) {
+		console.log("Загружен", item.input.name);
+	},
+	onItemError(item) {
+		console.error("Ошибка", item.input.name, item.error);
+	}
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`onProgress`}),` вызывается после каждой завершённой задачи. В первом вызове процент уже больше нуля; отдельного начального события `,(0,c.jsx)(t.code,{children:`0%`}),` нет.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type ConcurrentTaskProgress<TInput, TResult> = {
+	total: number;
+	completed: number;
+	succeeded: number;
+	failed: number;
+	running: number;
+	pending: number;
+	percentage: number;
+	aborted: boolean;
+	lastSettled?: ConcurrentTaskSettled<TInput, TResult>;
+};
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`percentage`}),` округляется через `,(0,c.jsx)(t.code,{children:`Math.round`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`abort`,children:`Abort`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const controller = new AbortController();
+
+const promise = runConcurrentTasks(urls, async (url, { signal }) => {
+	const response = await fetch(url, { signal });
+	return response.text();
+}, {
+	concurrency: 2,
+	signal: controller.signal
+});
+
+controller.abort();
+const result = await promise;
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`После abort новые задачи не стартуют. Уже начатая операция прервётся только если сама использует переданный `,(0,c.jsx)(t.code,{children:`signal`}),`. Runner ждёт завершения начатых tasks и возвращает:`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`aborted: true`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`обработанные элементы в `,(0,c.jsx)(t.code,{children:`settled`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`не начатые элементы в `,(0,c.jsx)(t.code,{children:`unprocessed`}),`.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Abort не является ошибкой runner-а и сам по себе не приводит к `,(0,c.jsx)(t.code,{children:`throw`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`порядок-результата`,children:`Порядок результата`}),`
+`,(0,c.jsxs)(t.p,{children:[`Tasks могут завершаться в любом порядке, callbacks идут в порядке фактического завершения. Итоговые `,(0,c.jsx)(t.code,{children:`settled`}),`, `,(0,c.jsx)(t.code,{children:`successes`}),`, `,(0,c.jsx)(t.code,{children:`errors`}),` и `,(0,c.jsx)(t.code,{children:`unprocessed`}),` собираются по исходным индексам, поэтому результат детерминирован относительно input.`]}),`
+`,(0,c.jsx)(t.h2,{id:`concurrencypartialerror`,children:(0,c.jsx)(t.code,{children:`ConcurrencyPartialError`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`runConcurrentTasks`}),` сам не создаёт этот error. Класс нужен, если слой приложения хочет преобразовать частичный результат в исключение:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const result = await runConcurrentTasks(inputs, task);
+
+if (result.errors.length > 0 || result.aborted) {
+	throw new ConcurrencyPartialError("Batch выполнен частично", result);
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Не путайте его с `,(0,c.jsx)(t.code,{children:`AsyncTasksError`}),`: первый создаёт consumer по своей policy, второй автоматически бросает `,(0,c.jsx)(t.code,{children:`runAsyncTasks`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`практические-рекомендации`,children:`Практические рекомендации`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`Не ставьте слишком большой concurrency: browser, proxy и backend имеют свои лимиты.`}),`
+`,(0,c.jsx)(t.li,{children:`Для write-операций продумайте идемпотентность: retry может повторить уже выполненное действие.`}),`
+`,(0,c.jsx)(t.li,{children:`Не меняйте input objects внутри task, если те же значения использует UI.`}),`
+`,(0,c.jsxs)(t.li,{children:[`Обрабатывайте `,(0,c.jsx)(t.code,{children:`unknown`}),` error через безопасный normalizer.`]}),`
+`,(0,c.jsx)(t.li,{children:`Не используйте runner вместо TanStack Query cache для одного и того же resource.`}),`
+`,(0,c.jsx)(t.li,{children:`Если задача зависит от результата предыдущей, это не независимый batch: выполните зависимые шаги последовательно.`}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`полный-api`,children:`Полный API`}),`
+`,(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:`Exports`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`All-at-once`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`runAsyncTasks`}),`, `,(0,c.jsx)(t.code,{children:`AsyncTasksError`}),`, `,(0,c.jsx)(t.code,{children:`AsyncTask`}),`, `,(0,c.jsx)(t.code,{children:`AsyncTaskSuccess`}),`, `,(0,c.jsx)(t.code,{children:`AsyncTaskFailure`}),`, `,(0,c.jsx)(t.code,{children:`AsyncTaskSettled`}),`, `,(0,c.jsx)(t.code,{children:`RunAsyncTasksResult`}),`, `,(0,c.jsx)(t.code,{children:`RunAsyncTasksOptions`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:`Bounded concurrency`}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`runConcurrentTasks`}),`, `,(0,c.jsx)(t.code,{children:`ConcurrencyPartialError`}),`, `,(0,c.jsx)(t.code,{children:`ConcurrentTaskContext`}),`, `,(0,c.jsx)(t.code,{children:`ConcurrentTaskFn`}),`, `,(0,c.jsx)(t.code,{children:`ConcurrentTaskSuccess`}),`, `,(0,c.jsx)(t.code,{children:`ConcurrentTaskError`}),`, `,(0,c.jsx)(t.code,{children:`ConcurrentTaskSettled`}),`, `,(0,c.jsx)(t.code,{children:`ConcurrentTaskUnprocessed`}),`, `,(0,c.jsx)(t.code,{children:`ConcurrentTaskProgress`}),`, `,(0,c.jsx)(t.code,{children:`RunConcurrentTasksOptions`}),`, `,(0,c.jsx)(t.code,{children:`RunConcurrentTasksResult`})]})]})]})]})]})}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};