@letar/forms 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+Все значимые изменения в библиотеке @lena/form-components документируются в этом файле.
+
+Формат основан на [Keep a Changelog](https://keepachangelog.com/ru/1.0.0/).
+
+## [0.54.1] - 2026-01-05
+
+### Fixed
+
+- `FieldNumber`: для опциональных полей не передаём min/max в NumberInput когда значение пустое — убрана красная рамка для пустых опциональных полей
+
+## [0.54.0] - 2026-01-03
+
+### Added
+
+- `form-from-schema.spec.tsx` — unit тесты для `FormFromSchema` (~15 тестов)
+- `form-with-api.spec.tsx` — unit тесты для `FormWithApi` (~12 тестов)
+- Покрытие тестами всех критичных компонентов схемогенерации
+
+### Changed
+
+- Deprecated type aliases централизованы в `form-fields/index.ts`
+- Удалены локальные deprecated экспорты из 7 selection компонентов
+- `field-select.tsx` использует `BaseOption<string | number>[]` вместо `SelectOption`
+
+### Improved
+
+- Общее покрытие тестами: +27 unit тестов
+- Обратная совместимость сохранена через централизованный реэкспорт deprecated типов
+
+## [0.53.0] - 2025-12-31
+
+### Added
+
+- Оптимизация производительности форм
+- Улучшенная мемоизация в form-fields
+
+## [0.51.0] - 2025-12-24
+
+### Added
+
+- `useAsyncSearch` — общий хук для async поиска с debounce (Combobox, Autocomplete)
+- `AsyncQueryFn`, `AsyncQueryResult` — типы для async запросов
+- Persistence TTL — опция `ttl` для времени жизни черновика
+- `ClearDraftButton` — компонент кнопки очистки черновика
+- `savedAt` — timestamp сохранения черновика в `FormPersistenceResult`
+
+### Changed
+
+- `FieldCombobox` и `FieldAutocomplete` используют `useAsyncSearch` вместо дублирования логики
+- `useFormPersistence` теперь сохраняет данные в новом формате с метаданными (version, savedAt)
+- Обратная совместимость со старым форматом сохранённых данных
+
+## [0.50.0] - 2025-12-24
+
+### Added
+
+- `SelectionFieldLabel` — общий компонент для label+tooltip в selection полях
+- `useGroupedOptions` — хук группировки опций (Combobox, Listbox, Select)
+- `getOptionLabel` — утилита для получения label опции
+- `zod-utils.ts` — централизованные функции `unwrapSchema`, `unwrapSchemaWithRequired`
+- `LinkPopover` — модальное окно для ввода URL вместо `window.prompt()`
+- Защита от циклических схем в `schema-traversal` (WeakSet + MAX_DEPTH=20)
+- `SWITCH_STYLES` константы в `field-schedule.tsx`
+
+### Changed
+
+- `extractConstraints` рефакторинг с generic handler pattern
+- `FormSteps` декомпозиция на хуки: `useStepState`, `useStepPersistence`, `useStepNavigation`
+- Selection поля используют общие компоненты вместо дублирования
+
+### Fixed
+
+- `field-rich-text`: добавлен try/catch для JSON.parse
+
+### Removed
+
+- ~500 строк дублирующегося кода
+
+## [0.49.0] и ранее
+
+История изменений до v0.50.0 не документировалась.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Letar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# @letar/forms
+
+Declarative form components for React with **40+ field types**, powered by [TanStack Form](https://tanstack.com/form) and [Chakra UI v3](https://chakra-ui.com).
+
+[![npm version](https://img.shields.io/npm/v/@letar/forms)](https://www.npmjs.com/package/@letar/forms)
+[![license](https://img.shields.io/npm/l/@letar/forms)](./LICENSE)
+
+## Quick Start
+
+```bash
+npm install @letar/forms @tanstack/react-form @chakra-ui/react zod
+```
+
+```tsx
+import { Form } from '@letar/forms'
+import { z } from 'zod/v4'
+
+const Schema = z.object({
+  title: z.string().min(2).meta({ ui: { title: 'Title', placeholder: 'Enter...' } }),
+  rating: z.number().min(0).max(10).meta({ ui: { title: 'Rating' } }),
+})
+
+function MyForm() {
+  return (
+    <Form schema={Schema} initialValue={{ title: '', rating: 5 }} onSubmit={save}>
+      <Form.Field.String name="title" />
+      <Form.Field.Number name="rating" />
+      <Form.Button.Submit>Save</Form.Button.Submit>
+    </Form>
+  )
+}
+```
+
+**Or fully auto-generated from schema:**
+
+```tsx
+<Form.FromSchema schema={Schema} initialValue={data} onSubmit={handleSubmit} submitLabel="Create" />
+```
+
+## Philosophy: Separate Layout from Logic
+
+| Aspect          | Where defined              | How used in JSX                 |
+| --------------- | -------------------------- | ------------------------------- |
+| **Validation**  | Zod schema                 | `schema={Schema}`               |
+| **UI metadata** | Zod `.meta({ ui: {...} })` | Auto-extracted from schema      |
+| **Structure**   | TypeScript types           | `initialValue={data}`           |
+| **Layout**      | JSX                        | `<HStack>`, `<VStack>`, `<Box>` |
+
+**Result:** JSX contains only layout and field names. All logic lives in the schema.
+
+## Features
+
+### 40+ Field Components
+
+```tsx
+// Text
+<Form.Field.String name="title" />
+<Form.Field.Textarea name="description" />
+<Form.Field.RichText name="content" />
+<Form.Field.Password name="password" />
+
+// Numbers
+<Form.Field.Number name="price" />
+<Form.Field.Slider name="rating" />
+<Form.Field.Currency name="amount" />
+
+// Selection
+<Form.Field.Select name="category" />
+<Form.Field.Combobox name="search" />
+<Form.Field.RadioGroup name="type" />
+<Form.Field.Checkbox name="agree" />
+
+// Date & Time
+<Form.Field.Date name="birthday" />
+<Form.Field.DateRange name="period" />
+<Form.Field.Time name="time" />
+
+// Specialized
+<Form.Field.Phone name="phone" />
+<Form.Field.FileUpload name="avatar" />
+<Form.Field.ColorPicker name="color" />
+<Form.Field.PinInput name="code" />
+```
+
+### Conditional Rendering
+
+```tsx
+<Form schema={Schema} initialValue={data} onSubmit={save}>
+  <Form.Field.Select name="type" />
+
+  <Form.When field="type" is="company">
+    <Form.Field.String name="companyName" />
+  </Form.When>
+
+  <Form.Button.Submit />
+</Form>
+```
+
+### Multi-Step Forms
+
+```tsx
+<Form schema={Schema} initialValue={data} onSubmit={save}>
+  <Form.Steps animated validateOnNext>
+    <Form.Steps.Step title="Personal Info">
+      <Form.Field.String name="name" />
+      <Form.Field.String name="email" />
+    </Form.Steps.Step>
+
+    <Form.Steps.Step title="Address">
+      <Form.Field.String name="city" />
+      <Form.Field.String name="street" />
+    </Form.Steps.Step>
+
+    <Form.Steps.Navigation />
+  </Form.Steps>
+</Form>
+```
+
+### Groups and Arrays
+
+```tsx
+// Nested object
+<Form.Group name="address">
+  <Form.Field.String name="city" />    {/* → address.city */}
+  <Form.Field.String name="street" />  {/* → address.street */}
+</Form.Group>
+
+// Array of items
+<Form.Group.List name="phones">
+  <Form.Field.Phone />
+  <Form.Group.List.Button.Add>Add Phone</Form.Group.List.Button.Add>
+</Form.Group.List>
+```
+
+### Auto Constraints from Zod
+
+```tsx
+const Schema = z.object({
+  title: z.string().min(2).max(100),  // → minLength={2} maxLength={100}
+  email: z.string().email(),          // → type="email"
+  rating: z.number().min(1).max(10),  // → min={1} max={10}
+})
+
+// DRY: validation and UI constraints in one place
+<Form.Field.String name="title" />  {/* maxLength={100} from schema */}
+```
+
+### Error Summary
+
+```tsx
+<Form schema={Schema} initialValue={data} onSubmit={save}>
+  <Form.Field.String name="name" />
+  <Form.Field.String name="email" />
+
+  <Form.Errors title="Please fix:" />
+  <Form.Button.Submit />
+</Form>
+```
+
+## Subpath Exports
+
+```tsx
+// Offline support (PWA)
+import { FormOfflineIndicator, useOfflineForm } from '@letar/forms/offline'
+
+// Internationalization
+import { FormI18nProvider, useFormI18n } from '@letar/forms/i18n'
+```
+
+## Peer Dependencies
+
+| Package                | Version   | Required |
+| ---------------------- | --------- | -------- |
+| `react`                | >= 18.0.0 | Yes      |
+| `@tanstack/react-form` | >= 1.0.0  | Yes      |
+| `@chakra-ui/react`     | >= 3.0.0  | Yes      |
+| `framer-motion`        | >= 10.0.0 | Yes      |
+| `zod`                  | >= 3.24.0 | Yes      |
+| `@dnd-kit/*`           | >= 6.0.0  | Optional |
+| `use-mask-input`       | >= 3.0.0  | Optional |
+
+## Documentation
+
+Full documentation and live examples: **[forms.letar.best](https://forms.letar.best)**
+
+## License
+
+[MIT](./LICENSE)