@ryuzaki13/react-foundation-lib 1.4.0 → 1.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/README.md +20 -16
  2. package/package.json +1 -1
  3. package/src/array/README.mdx +1630 -0
  4. package/src/binary/README.mdx +1405 -0
  5. package/src/copy/README.mdx +992 -0
  6. package/src/crypto/README.mdx +1052 -0
  7. package/src/dom/README.mdx +2179 -0
  8. package/src/file/README.mdx +1957 -0
  9. package/src/formatters/README.mdx +469 -0
  10. package/src/formatters/boolean/README.mdx +494 -0
  11. package/src/formatters/date/README.mdx +732 -0
  12. package/src/formatters/number/README.mdx +542 -0
  13. package/src/formatters/pipeline/README.mdx +629 -0
  14. package/src/formatters/rowBased/README.mdx +486 -0
  15. package/src/formatters/strings/README.mdx +442 -0
  16. package/src/formatters/valueState/README.mdx +459 -0
  17. package/src/formulas/README.mdx +1283 -0
  18. package/src/binary/README.md +0 -110
  19. package/src/docs/browserAndReact.mdx +0 -150
  20. package/src/docs/filesAndExcel.mdx +0 -163
  21. package/src/docs/formatters-runtime.mdx +0 -455
  22. package/src/docs/formatters.mdx +0 -380
  23. package/src/docs/odataAndTables.mdx +0 -178
  24. package/src/docs/pureUtilities.mdx +0 -96
  25. package/src/docs/runtimeAndState.mdx +0 -155
  26. package/src/file/README.md +0 -289
  27. package/src/formatters/date/README.md +0 -520
  28. package/src/formatters/number/README.md +0 -123
  29. package/src/formatters/valueState/README.md +0 -275
  30. package/src/formulas/README.md +0 -42
package/README.md CHANGED
@@ -30,7 +30,7 @@ import type { RowRecord } from "@ryuzaki13/react-foundation-lib/types";
30
30
  | Entry point | Что может потребоваться в host-проекте |
31
31
  | ------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
32
32
  | `formatters`, `array`, `utils`, `validators` | Обычно не требуют дополнительных runtime-зависимостей. |
33
- | `hooks`, `dom`, `copy`, `media`, `pwa` | `react`, если используются React hooks. |
33
+ | `hooks`, `binary`, `dom`, `copy`, `media`, `pwa` | `react`: `binary` экспортирует `useBinaryFile`, остальные entrypoints требуют React при использовании hooks. |
34
34
  | `query-client`, `error-report` | `@tanstack/react-query`, `@tanstack/query-persist-client-core`, `@tanstack/query-broadcast-client-experimental`. |
35
35
  | `odata-service` | `zod`; отдельные helpers типизируются вокруг `@tanstack/react-query`. |
36
36
  | `odata`, `notifications` | `zustand`, для отдельных store-helpers также `immer`. |
@@ -80,6 +80,7 @@ npm run pack:dry-run
80
80
  | Числа, проценты, валютные числа, compact axis labels | [`formatters/number`](./src/formatters/number/index.ts), тесты: [`formatNumber.test.ts`](./src/formatters/number/formatNumber.test.ts), [`parseNumber.test.ts`](./src/formatters/number/parseNumber.test.ts) |
81
81
  | Строки, ФИО, телефон, leading zeros, SAP boolean | [`formatters`](./src/formatters/index.ts), тесты: [`common.test.ts`](./src/formatters/common.test.ts), [`boolean.test.ts`](./src/formatters/boolean/boolean.test.ts), [`strings.test.ts`](./src/formatters/strings/strings.test.ts) |
82
82
  | Runtime-форматирование ячеек таблицы | [`formatters/pipeline`](./src/formatters/pipeline/index.ts), тесты в [`formatters/pipeline`](./src/formatters/pipeline) |
83
+ | Группировка, дедупликация, порядок и нормализация массивов | [`array`](./src/array/index.ts), подробный README: [`array/README.mdx`](./src/array/README.mdx) |
83
84
  | OData metadata, filters, sorts, path, values | [`odata-service`](./src/odata-service/index.ts), тесты в [`odata-service`](./src/odata-service) |
84
85
  | Справочные code/text пары OData collections | [`odata`](./src/odata/index.ts), тест: [`odata.test.ts`](./src/odata/odata.test.ts) |
85
86
  | TanStack Table helpers | [`table`](./src/table/index.ts), тесты в [`table`](./src/table) |
@@ -95,9 +96,11 @@ npm run pack:dry-run
95
96
 
96
97
  ## Форматирование и значения
97
98
 
99
+ Полный пользовательский путеводитель находится в [`formatters/README.mdx`](./src/formatters/README.mdx). Он объясняет общие правила, публичную границу единственного entrypoint `@ryuzaki13/react-foundation-lib/formatters` и ведёт к подробным документам каждой предметной области. Разделы ниже дают только краткую карту пакета и не заменяют API-документацию.
100
+
98
101
  ### `formatters/date`
99
102
 
100
- Файлы: [`formatters/date/index.ts`](./src/formatters/date/index.ts), подробный README: [`formatters/date/README.md`](./src/formatters/date/README.md).
103
+ Файлы: [`formatters/date/index.ts`](./src/formatters/date/index.ts), подробный README: [`formatters/date/README.mdx`](./src/formatters/date/README.mdx).
101
104
 
102
105
  Главная идея: модуль работает в плавающей календарной семантике. ISO/OData строки с timezone не пересчитываются в timezone клиента, а сохраняют видимые компоненты даты и времени.
103
106
 
@@ -125,7 +128,7 @@ npm run pack:dry-run
125
128
 
126
129
  ### `formatters/number`
127
130
 
128
- Файлы: [`formatters/number/index.ts`](./src/formatters/number/index.ts), README: [`formatters/number/README.md`](./src/formatters/number/README.md).
131
+ Файлы: [`formatters/number/index.ts`](./src/formatters/number/index.ts), README: [`formatters/number/README.mdx`](./src/formatters/number/README.mdx).
129
132
 
130
133
  Модуль форматирует числа через presets и кеширует `Intl.NumberFormat`. Это стандартный путь для таблиц, графиков и SAP-like строк.
131
134
 
@@ -136,7 +139,7 @@ npm run pack:dry-run
136
139
  | `formatNumber(value, presetOrName)` | Универсальный formatter по имени preset или объекту preset. |
137
140
  | `formatNumberAsInteger`, `formatNumberAsDecimal*`, `formatNumberAsCurrency`, `formatNumberAsPercent`, `formatNumberAsPrice`, `formatNumberAsTonnage` | Типовые UI-форматы. |
138
141
  | `formatNumberAs*OrEmpty` | То же, но semantic zero отображается пустой строкой. |
139
- | `formatCompactNumber`, `formatNumberAsChartAxis`, `formatNumberAsChartTooltip`, `formatNumberAsCurrencyChartAxis` | Compact-формат для осей и tooltip графиков. |
142
+ | Встроенные `compact-*` presets и собственный `NumberFormatPreset.compact` | Compact-формат с `тыс`, `млн`, `млрд`, `трлн`. |
140
143
  | `parseNumber`, `toFiniteNumber`, `toPositiveInteger`, `isPositiveValue`, `isZeroValue` | Чтение SAP-like чисел из `unknown`. |
141
144
  | `registerNumberPreset`, `getNumberPreset`, `getNumberPresetNames`, `resetNumberPresets`, `clearFormatCache` | Реестр presets и кеш formatter-ов. |
142
145
 
@@ -152,7 +155,7 @@ npm run pack:dry-run
152
155
 
153
156
  ### `formatters/strings`
154
157
 
155
- Файлы: [`formatters/strings/index.ts`](./src/formatters/strings/index.ts).
158
+ Файлы: [`formatters/strings/index.ts`](./src/formatters/strings/index.ts), подробный README: [`formatters/strings/README.mdx`](./src/formatters/strings/README.mdx).
156
159
 
157
160
  | API | Поведение |
158
161
  | ---------------------------------------------------- | --------------------------------------------------------------- |
@@ -182,7 +185,7 @@ npm run pack:dry-run
182
185
 
183
186
  ### `formatters/boolean`
184
187
 
185
- Файлы: [`formatters/boolean/index.ts`](./src/formatters/boolean/index.ts), тест: [`boolean.test.ts`](./src/formatters/boolean/boolean.test.ts).
188
+ Файлы: [`formatters/boolean/index.ts`](./src/formatters/boolean/index.ts), подробный README: [`formatters/boolean/README.mdx`](./src/formatters/boolean/README.mdx), тест: [`boolean.test.ts`](./src/formatters/boolean/boolean.test.ts).
186
189
 
187
190
  | API | Поведение |
188
191
  | ------------------ | ------------------------------------------------------------- |
@@ -192,7 +195,7 @@ npm run pack:dry-run
192
195
 
193
196
  ### `formatters/valueState`
194
197
 
195
- Файлы: [`formatters/valueState/index.ts`](./src/formatters/valueState/index.ts), README: [`formatters/valueState/README.md`](./src/formatters/valueState/README.md).
198
+ Файлы: [`formatters/valueState/index.ts`](./src/formatters/valueState/index.ts), README: [`formatters/valueState/README.mdx`](./src/formatters/valueState/README.mdx).
196
199
 
197
200
  Модуль вычисляет визуальный `State` (`none`, `information`, `success`, `warning`, `error`) по значению.
198
201
 
@@ -210,7 +213,7 @@ npm run pack:dry-run
210
213
 
211
214
  ### `formatters/pipeline`
212
215
 
213
- Файлы: [`formatters/pipeline/index.ts`](./src/formatters/pipeline/index.ts).
216
+ Файлы: [`formatters/pipeline/index.ts`](./src/formatters/pipeline/index.ts), подробный README: [`formatters/pipeline/README.mdx`](./src/formatters/pipeline/README.mdx).
214
217
 
215
218
  Pipeline — runtime форматирования ячейки. Он принимает сериализуемый `FormattersPipelineConfig` версии `1`, валидирует `plan` или строит линейный plan из `graph`, компилирует executor и возвращает display-result.
216
219
 
@@ -249,7 +252,7 @@ Pipeline — runtime форматирования ячейки. Он прини
249
252
 
250
253
  ### `formatters/rowBased`
251
254
 
252
- Файлы: [`formatters/rowBased/index.ts`](./src/formatters/rowBased/index.ts), тест: [`rowBased.test.ts`](./src/formatters/rowBased/rowBased.test.ts).
255
+ Файлы: [`formatters/rowBased/index.ts`](./src/formatters/rowBased/index.ts), подробный README: [`formatters/rowBased/README.mdx`](./src/formatters/rowBased/README.mdx), тест: [`rowBased.test.ts`](./src/formatters/rowBased/rowBased.test.ts).
253
256
 
254
257
  Это маленький реестр формул для row-based override внутри pipeline.
255
258
 
@@ -264,7 +267,7 @@ Pipeline — runtime форматирования ячейки. Он прини
264
267
 
265
268
  ### `formulas`
266
269
 
267
- Файлы: [`formulas/index.ts`](./src/formulas/index.ts), README: [`formulas/README.md`](./src/formulas/README.md).
270
+ Файлы: [`formulas/index.ts`](./src/formulas/index.ts), подробный README: [`formulas/README.mdx`](./src/formulas/README.mdx).
268
271
 
269
272
  Инфраструктура реестра клиентских формул таблицы для calculated/clientOnly measure-колонок. Definitions принадлежат host-приложению и не входят в foundation-пакет.
270
273
 
@@ -455,7 +458,7 @@ Pipeline — runtime форматирования ячейки. Он прини
455
458
 
456
459
  ### `file` и `binary`
457
460
 
458
- Файлы: [`file/index.ts`](./src/file/index.ts), README: [`file/README.md`](./src/file/README.md); [`binary/index.ts`](./src/binary/index.ts), README: [`binary/README.md`](./src/binary/README.md).
461
+ Файлы: [`file/index.ts`](./src/file/index.ts), подробный README: [`file/README.mdx`](./src/file/README.mdx); [`binary/index.ts`](./src/binary/index.ts), README: [`binary/README.mdx`](./src/binary/README.mdx).
459
462
 
460
463
  `file`:
461
464
 
@@ -491,7 +494,7 @@ Pipeline — runtime форматирования ячейки. Он прини
491
494
 
492
495
  ### `dom`
493
496
 
494
- Файлы: [`dom/index.ts`](./src/dom/index.ts), тест: [`dom.test.tsx`](./src/dom/dom.test.tsx).
497
+ Файлы: [`dom/index.ts`](./src/dom/index.ts), подробный README: [`dom/README.mdx`](./src/dom/README.mdx), тест: [`dom.test.tsx`](./src/dom/dom.test.tsx).
495
498
 
496
499
  | API | Поведение |
497
500
  | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
@@ -524,14 +527,14 @@ Pipeline — runtime форматирования ячейки. Он прини
524
527
 
525
528
  ### `copy`
526
529
 
527
- Файлы: [`copy/index.ts`](./src/copy/index.ts).
530
+ Файлы: [`copy/index.ts`](./src/copy/index.ts), подробный README: [`copy/README.mdx`](./src/copy/README.mdx).
528
531
 
529
532
  | API | Поведение |
530
533
  | -------------------------------- | --------------------------------------------------------------------------------------- |
531
534
  | `useCopyText` | Clipboard API в secure context, fallback через `execCommand`; пустой текст не копирует. |
532
535
  | `useElementText` | Trimmed `textContent` ref. |
533
536
  | `useCopyElementText` | Копирует текст из ref. |
534
- | `useCopyFeedback` | `isCopied` на 2 секунды. |
537
+ | `useCopyFeedback` | `isCopied` на 2 секунды; повторные вызовы создают независимые timers. |
535
538
  | `useCopyElementTextWithFeedback` | Копирование элемента + feedback. |
536
539
 
537
540
  ### `media`
@@ -634,13 +637,14 @@ Service worker runtime helpers живут в [`pwa/serviceWorker.ts`](./src/pwa/
634
637
 
635
638
  ### `array`
636
639
 
637
- Файлы: [`array/index.ts`](./src/array/index.ts), тесты: [`array.test.ts`](./src/array/array.test.ts), [`reorder.test.ts`](./src/array/reorder.test.ts).
640
+ Файлы: [`array/index.ts`](./src/array/index.ts), подробный README: [`array/README.mdx`](./src/array/README.mdx), тесты: [`array.test.ts`](./src/array/array.test.ts), [`reorder.test.ts`](./src/array/reorder.test.ts).
638
641
 
639
642
  | API | Поведение |
640
643
  | --------------------------------------------------- | -------------------------------------------------------------------------- |
641
644
  | `arrayGroupBy`, `arrayGroupByToArray` | Группировка по ключу, порядок элементов внутри группы сохраняется. |
642
645
  | `arrayToMap` | Map-object по первому встреченному значению ключа. |
643
646
  | `arrayUniqueBy` | Дедупликация по ключу без перестановки первого значения. |
647
+ | `arrayDeduplicate` | Дедупликация значений через семантику `Set` с сохранением первого вхождения. |
644
648
  | `filterAndDeduplicateIds` | Оставляет только allowed ids, убирает пустые и дубли. |
645
649
  | `appendMissingIds` | Добавляет отсутствующие ids в конец базового списка. |
646
650
  | `pickExistingMapValues` | Значения `Map` в порядке keys, отсутствующие ключи пропускаются. |
@@ -688,7 +692,7 @@ Service worker runtime helpers живут в [`pwa/serviceWorker.ts`](./src/pwa/
688
692
 
689
693
  ### `crypto` и `session-storage`
690
694
 
691
- Файлы: [`crypto/index.ts`](./src/crypto/index.ts), [`session-storage/index.ts`](./src/session-storage/index.ts).
695
+ Файлы: [`crypto/index.ts`](./src/crypto/index.ts), подробный README: [`crypto/README.mdx`](./src/crypto/README.mdx); [`session-storage/index.ts`](./src/session-storage/index.ts).
692
696
 
693
697
  | API | Поведение |
694
698
  | -------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ryuzaki13/react-foundation-lib",
3
- "version": "1.4.0",
3
+ "version": "1.4.1",
4
4
  "description": "Reusable React and TypeScript foundation utilities, hooks, and primitives.",
5
5
  "license": "MIT",
6
6
  "author": "Ryuzaki13",