denwa-react-shared 1.0.88 → 1.0.90

package/package.json

@@ -1,13 +1,25 @@
 {
   "name": "denwa-react-shared",
   "private": false,
-  "version": "1.0.88",
+  "version": "1.0.90",
   "type": "module",
   "author": "Denwa",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Denwa799/react-shared.git"
+  },
+  "keywords": [
+    "react",
+    "shared",
+    "admin",
+    "tanstack-intent"
+  ],
   "main": "dist/denwa-react-shared.umd.js",
   "module": "dist/denwa-react-shared.es.js",
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "!skills/_artifacts"
   ],
   "types": "dist/index.d.ts",
   "exports": {
@@ -63,6 +75,7 @@
     "@types/react": "^19.1.6",
     "@types/react-dom": "^19.1.6",
     "@types/validator": "^13.15.1",
+    "@tanstack/intent": "latest",
     "@vitejs/plugin-react-swc": "^3.10.1",
     "autoprefixer": "^10.4.21",
     "eslint": "^9.28.0",

package/skills/admin-forms/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: admin-forms
+description: >
+  Implement entity editor forms using DrawerForm and specialized inputs. 
+  Covers form submission, language switching, and integration with 
+  AdminTable actions.
+type: framework
+library: denwa-react-shared
+framework: react
+library_version: "1.0.88"
+requires:
+  - session-auth
+---
+
+# Drawer Forms & Inputs
+
+Most entity management in the admin panel happens within `Drawer` panels using `BaseDrawerForm`. This component standardizes the appearance of save buttons and multi-language controls.
+
+## Setup
+
+```tsx
+import { BaseDrawerForm, AdminDrawerFormProps } from 'denwa-react-shared';
+
+const UserForm = ({ id, action, onClose, onRefetch }: AdminDrawerFormProps<'create' | 'update' | 'read'>) => {
+  const { control, handleSubmit } = useForm();
+  
+  const isReadOnly = action === 'read';
+
+  return (
+    <BaseDrawerForm
+      saveText="Сохранить"
+      submitButtonText={action === 'create' ? 'Создать' : 'Обновить'}
+      isVisibleSubmit={!isReadOnly}
+      onSubmitClick={handleSubmit(onSave)}
+    >
+      <Controller
+        name="name"
+        control={control}
+        render={({ field }) => <Input {...field} disabled={isReadOnly} />}
+      />
+      {/* ... form content */}
+    </BaseDrawerForm>
+  );
+};
+```
+
+## Core Patterns
+
+### Language Switching
+If the entity supports multiple languages, enable `isVisibleLanguage` and provide `languagesData`.
+
+```tsx
+<BaseDrawerForm
+  isVisibleLanguage
+  language={currentLang}
+  languagesData={[
+    { label: 'Русский', value: 'ru' },
+    { label: 'English', value: 'en' },
+  ]}
+  onChangeLang={(lang) => setLang(lang)}
+  // Optional: Bulk translation button
+  isVisibleLanguageButton
+  translateAllText="Перевести все"
+  onTranslateAllClick={handleTranslate}
+>
+  {/* ... fields */}
+</BaseDrawerForm>
+```
+
+### Integration with AdminTable
+The `AdminTable` orchestration passes `id`, `action`, `onClose`, and `onRefetch` to the `drawerContent` component.
+
+```tsx
+// In AdminTable:
+<AdminTable
+  drawerContent={UserForm}
+  readAction="read"
+  createAction="create"
+  updateAction="update"
+  // ...
+/>
+```
+
+## Common Mistakes
+
+### MEDIUM Using raw antd Form
+Wrong:
+```tsx
+import { Form } from 'antd';
+return <Form>{children}</Form>;
+```
+Correct:
+```tsx
+import { BaseDrawerForm } from 'denwa-react-shared';
+return <BaseDrawerForm>{children}</BaseDrawerForm>;
+```
+`BaseDrawerForm` wraps `antd` Form but adds standardized footer buttons and integrated logic for language switching and submission loading states.
+
+Source: maintainer interview
+
+### HIGH Mismanaging "read" action state
+Wrong:
+```tsx
+const UserForm = ({ action }) => {
+  return <BaseDrawerForm>{/* inputs are always enabled */}</BaseDrawerForm>;
+};
+```
+Correct:
+```tsx
+const UserForm = ({ action }) => {
+  const isReadOnly = action === 'read';
+  return (
+    <BaseDrawerForm isVisibleSubmit={!isReadOnly}>
+       <Input disabled={isReadOnly} />
+    </BaseDrawerForm>
+  );
+};
+```
+When `action` is 'read', the form should visually hide the submit button and disable all input fields.
+
+Source: src/shared/ui/admin-table/index.tsx

package/skills/admin-table/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: admin-table
+description: >
+  Implement complex data tables using AdminTable and useFetchTableData. 
+  Covers columns configuration, server-side filtering, sorting, 
+  and search state mapping.
+type: framework
+library: denwa-react-shared
+framework: react
+library_version: "1.0.88"
+requires:
+  - session-auth
+sources:
+  - "Denwa799/react-shared:src/shared/ui/admin-table/index.tsx"
+  - "Denwa799/react-shared:src/shared/lib/hooks/use-fetch-table-data.ts"
+---
+
+# Admin Table & Data Fetching
+
+The `AdminTable` component is the centerpiece for building resource lists. It works in conjunction with `useFetchTableData` to map UI states (search, sort, page) to API filters.
+
+## Setup
+
+```tsx
+import { AdminTable, useFetchTableData } from 'denwa-react-shared';
+import { ColumnsType } from 'antd/es/table';
+
+const UsersPage = () => {
+  // 1. Setup state setters (usually from nuqs or local state)
+  const [order, setOrder] = useState('createdAtDesc');
+  const [search, setSearch] = useState('');
+  
+  // 2. Use hook to get mapped filters/sort for API
+  const { filter, sort, onChangeOrder, ...searchHandlers } = useFetchTableData({
+    order,
+    search,
+    onSetOrder: setOrder,
+    onSetSearch: setSearch,
+    // ... other setters for pagination, radio, date search
+    sortFields: [{ key: 'createdAtDesc', field: 'createdAt', order: 'desc' }],
+    searchFields: ['name', 'email'],
+    // ... field configuration
+  });
+
+  // 3. Render table
+  return (
+    <AdminTable
+      tableData={data}
+      columns={columns}
+      order={order}
+      onChangeOrder={onChangeOrder}
+      searchProps={{
+        ...searchHandlers,
+        // ... text labels
+      }}
+      // ... actions and text props
+    />
+  );
+};
+```
+
+## Core Patterns
+
+### Configuring Search and Filters
+`searchProps` expects a `TableSearchProps` object. Ensure you provide the `datePickerComponent` and all required handlers from `useFetchTableData`.
+
+```tsx
+<AdminTable
+  searchProps={{
+    datePickerComponent: BaseDatePicker,
+    searchText: 'Поиск',
+    noDateText: 'Нет даты',
+    emptyText: 'Ничего не найдено',
+    searchSelect: currentSearchField,
+    radioOptions: [{ label: 'Все', value: 'all' }],
+    searchOptions: [{ label: 'Имя', value: 'name' }],
+    searchType: 'text',
+    onChangeSearch: handleFieldChange,
+    onChangeTextSearch: handleTextChange,
+  }}
+  // ...
+/>
+```
+
+### Server-Side Pagination
+The table expects `serverPagination` prop of type `IPaginate`.
+
+```tsx
+<AdminTable
+  serverPagination={{
+    total: totalItems,
+    page: currentPage,
+    limit: pageSize,
+  }}
+  onSetPaginate={(page, limit) => {
+    setPage(page);
+    setLimit(limit);
+  }}
+/>
+```
+
+## Common Mistakes
+
+### HIGH Hallucinating internal state management
+Wrong:
+```tsx
+// Trying to use useFetchTableData without passing external setters
+const tableInfo = useFetchTableData({
+  order: 'desc', // Static value
+  // Missing onSetOrder, onSetSearch, etc.
+});
+```
+Correct:
+```tsx
+const [order, setOrder] = useState('desc');
+const tableInfo = useFetchTableData({
+  order,
+  onSetOrder: setOrder,
+  // Must provide setters to allow the hook to update external state
+});
+```
+The hook acts as a logic mapper and relies on external state (like `nuqs` or `useState`) to persist changes.
+
+Source: maintainer interview
+
+### HIGH Passings wrong pagination format
+Wrong:
+```tsx
+// Using antd internal pagination object
+<AdminTable serverPagination={{ current: 1, pageSize: 10 }} />
+```
+Correct:
+```tsx
+<AdminTable serverPagination={{ page: 1, limit: 10, total: 100 }} />
+```
+`AdminTable` expects a custom `IPaginate` shape, not the standard Ant Design pagination object.
+
+Source: src/shared/ui/admin-table/types.ts
+
+### MEDIUM Using raw antd Table
+Wrong:
+```tsx
+import { Table } from 'antd';
+return <Table dataSource={data} columns={columns} />;
+```
+Correct:
+```tsx
+import { AdminTable } from 'denwa-react-shared';
+return <AdminTable tableData={data} columns={columns} ... />;
+```
+Using raw `Table` loses integrated search UI, standardized skeletons, and the "Drawer Form" orchestration.
+
+Source: maintainer interview

package/skills/material-map/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: material-map
+description: >
+  Integrate Yandex Maps for coordinate selection. Covers map initialization, 
+  setting markers, and coordinate synchronization.
+type: framework
+library: denwa-react-shared
+framework: react
+library_version: "1.0.88"
+requires:
+  - session-auth
+sources:
+  - "Denwa799/react-shared:src/shared/ui/material-map/index.tsx"
+---
+
+# Yandex Maps Integration
+
+`BaseMaterialMap` uses Yandex Maps to allow users to select geographic coordinates. It requires a Yandex Maps API key and provides a simple interface for single-point selection.
+
+## Setup
+
+```tsx
+import { BaseMaterialMap } from 'denwa-react-shared';
+
+const LocationPicker = () => {
+  return (
+    <BaseMaterialMap
+      apiKey="your-yandex-api-key"
+      value={{ lat: 55.751244, lng: 37.618423 }}
+      onChange={(coords) => setLocation(coords)}
+      height={400}
+      zoom={10}
+      noDataText="Координаты не выбраны"
+    />
+  );
+};
+```
+
+## Core Patterns
+
+### Manual Coordinate Entry
+The component displays the current coordinates in inputs. Users can either click on the map or type values manually. Always ensure `onChange` is provided to capture changes from both sources.
+
+### Custom Height and Styling
+The map container should be constrained by the `height` prop. It defaults to `100%` width of the parent container.
+
+## Common Mistakes
+
+### CRITICAL Missing API Key
+Wrong:
+```tsx
+<BaseMaterialMap value={coords} />
+```
+Correct:
+```tsx
+<BaseMaterialMap apiKey={import.meta.env.VITE_YAMAP_KEY} value={coords} />
+```
+The map uses `@iminside/react-yandex-maps` internally. If the `apiKey` is missing or invalid, the map will fail to load or will show a "Demo mode" watermark.
+
+Source: src/shared/ui/material-map/index.tsx
+
+### HIGH Forgetting default center for empty values
+If the `value` is undefined, the map might center on a default (often 0,0) or fail. Always provide a fallback `defaultCenter` or check for existence.
+
+Source: maintainer interview

package/skills/media-management/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: media-management
+description: >
+  Handle single/multiple image uploads and file attachments. 
+  Covers drag-and-drop sorting, temporary upload patterns, 
+  and media deletion.
+type: framework
+library: denwa-react-shared
+framework: react
+library_version: "1.0.88"
+requires:
+  - session-auth
+sources:
+  - "Denwa799/react-shared:src/shared/ui/image-upload/base-image-upload.tsx"
+  - "Denwa799/react-shared:src/shared/ui/file-upload/file-upload.tsx"
+---
+
+# Media & File Management
+
+The library provides `BaseImageUpload` for image galleries and `FileUpload` for general documents. Both rely on a two-step process: uploading to a temporary location first, then associating the path with the entity.
+
+## Setup
+
+### Image Upload with Sorting
+```tsx
+import { BaseImageUpload, TAdminImage } from 'denwa-react-shared';
+
+const Gallery = () => {
+  return (
+    <BaseImageUpload
+      isMultiple
+      label="Галерея"
+      images={images}
+      onUpdateTempImage={handleTempUpload}
+      onUpdateItems={handleReorder}
+      onUpdateDeleteItems={handleDelete}
+    />
+  );
+};
+```
+
+## Core Patterns
+
+### Two-Step Upload Process
+Components emit native File objects. You must upload these to a temporary storage API and return the resulting path to the component's state.
+
+```tsx
+const handleTempUpload = async (file: File) => {
+  const formData = new FormData();
+  formData.append('file', file);
+  
+  const response = await api.upload(formData); // Your API
+  return response.path; // e.g. "/temp/random-id.png"
+};
+```
+
+### File Attachments
+For non-image files, use `FileUpload`. It supports single or multiple files with size/extension limits.
+
+```tsx
+import { FileUpload } from 'denwa-react-shared';
+
+<FileUpload
+  label="Документ"
+  onUpload={handleFileUpload}
+  onRemove={handleFileRemove}
+  items={data.files}
+  isMultiple={false}
+/>
+```
+
+## Common Mistakes
+
+### CRITICAL Forgetting to handle reordering
+Wrong:
+```tsx
+// Only handling uploads
+<BaseImageUpload onUpdateTempImage={upload} /> 
+```
+Correct:
+```tsx
+<BaseImageUpload 
+  onUpdateTempImage={upload}
+  onUpdateItems={(newItems) => setImages(newItems)}
+/>
+```
+If `onUpdateItems` is missing, drag-and-drop reordering will visually work but won't persist to state.
+
+Source: src/shared/ui/image-upload/base-image-upload.tsx
+
+### HIGH Passing only URLs instead of Image objects
+Wrong:
+```tsx
+<BaseImageUpload images={["/image1.png"]} />
+```
+Correct:
+```tsx
+<BaseImageUpload images={[{ id: 1, path: "/image1.png" }]} />
+```
+`BaseImageUpload` expects an array of objects containing `id` and `path`, not raw strings.
+
+Source: src/shared/ui/image-upload/types.ts
+
+### MEDIUM Missing upload button due to limits
+If the `limit` prop is reached, the "Upload" button disappears. Ensure you communicate this UI behavior or provide a way to delete items.
+
+Source: src/shared/ui/image-upload/base-image-upload.tsx:55

package/skills/session-auth/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: session-auth
+description: >
+  Manage authentication sessions, parse server responses, and validate identity 
+  cookies using Zod schemas. Use for handling login flow results and 
+  session integrity checks.
+type: core
+library: denwa-react-shared
+library_version: "1.0.88"
+sources:
+  - "Denwa799/react-shared:src/shared/schemas/index.ts"
+---
+
+# Session & Auth Management
+
+This skill covers the standardization of server responses and session state validation using Zod schemas. All API interactions should be validated against these schemas to ensure data consistency.
+
+## Setup
+
+```typescript
+import { responseSchema, sessionCookieSchema } from 'denwa-react-shared';
+
+// Example: Validating an API response
+const handleApiResponse = (data: unknown) => {
+  const result = responseSchema.safeParse(data);
+  if (!result.success) {
+    console.error('API format mismatch:', result.error);
+    return;
+  }
+  return result.data;
+};
+```
+
+## Core Patterns
+
+### Parsing Session Cookies
+Use `sessionCookieSchema` to validate the structure of the authentication cookie before using it in the application.
+
+```typescript
+import { sessionCookieSchema } from 'denwa-react-shared';
+
+const validateSession = (cookieData: unknown) => {
+  const session = sessionCookieSchema.parse(cookieData);
+  return {
+    isLoggedIn: !!session.tokens.accessToken.token,
+    userRoles: session.roles,
+    isAdmin: session.roles.includes('admin'),
+  };
+};
+```
+
+### Handling Standard Error Envelopes
+The `responseSchema` includes a structured `error` field. Always check for both the top-level `error` object and `statusCode`.
+
+```typescript
+import { responseSchema } from 'denwa-react-shared';
+
+async function fetchData(url: string) {
+  const response = await fetch(url);
+  const data = await response.json();
+  
+  const parsed = responseSchema.parse(data);
+  if (parsed.error) {
+    throw new Error(parsed.error.message || 'Unknown error');
+  }
+  
+  return parsed.data;
+}
+```
+
+## Common Mistakes
+
+### MEDIUM Manually parsing cookies without schema
+Wrong:
+```typescript
+const id = JSON.parse(cookies.get('session')).id;
+```
+Correct:
+```typescript
+const session = sessionCookieSchema.parse(cookies.get('session'));
+const id = session.id;
+```
+Manually accessing properties bypasses validation and creates runtime risks if the session structure changes.
+
+Source: maintainer interview
+
+### HIGH Ignoring the data/response duality
+Wrong:
+```typescript
+// Expecting data to always be the result
+const users = response.data; 
+```
+Correct:
+```typescript
+// Checking both data and any legacy response fields
+const users = response.data ?? response.response;
+```
+The `responseSchema` allows for flexibility in return fields (`data` vs `response`). Agents should account for both.
+
+Source: src/shared/schemas/index.ts

package/skills/text-editor/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: text-editor
+description: >
+  Implement rich text editing using BaseTextEditor (Slate.js). 
+  Covers content synchronization (JSON and HTML) and toolbar configuration.
+type: framework
+library: denwa-react-shared
+framework: react
+library_version: "1.0.88"
+requires:
+  - session-auth
+sources:
+  - "Denwa799/react-shared:src/shared/ui/text-editor/text-editor.tsx"
+---
+
+# Slate Rich Text Editor
+
+`BaseTextEditor` provides a rich text editing experience based on Slate.js. It handles serialization to HTML and synchronization with external form state through debounced handlers.
+
+## Setup
+
+```tsx
+import { BaseTextEditor, BaseTextEditorRefMethods } from 'denwa-react-shared';
+
+const MyForm = () => {
+  const editorRef = useRef<BaseTextEditorRefMethods>(null);
+
+  return (
+    <BaseTextEditor
+      boldText="Жирный"
+      italicText="Курсив"
+      underlineText="Подчеркнутый"
+      // ... more labels
+      onSetContent={(jsonString, lang) => setFieldValue('content', jsonString)}
+      onSetHtml={(htmlString, lang) => setFieldValue('contentHtml', htmlString)}
+      onErrorMessage={(msg) => alert(msg)}
+    />
+  );
+};
+```
+
+## Core Patterns
+
+### Content Initialization
+To set the editor value (e.g. when loading an existing entity), use the `setValue` method on the ref. It expects the serialized JSON string found in the database.
+
+```tsx
+useEffect(() => {
+  if (data?.content) {
+    editorRef.current?.setValue(data.content);
+  }
+}, [data]);
+```
+
+### Syncing JSON and HTML
+The editor emits events for both the raw Slate JSON structure (for editing) and the rendered HTML (for display/SEO). Always provide both `onSetContent` and `onSetHtml`.
+
+```tsx
+<BaseTextEditor
+  onSetContent={(json) => updateJson(json)}
+  onSetHtml={(html) => updateHtml(html)}
+/>
+```
+
+## Common Mistakes
+
+### HIGH Passing raw HTML to setValue
+Wrong:
+```tsx
+editorRef.current?.setValue("<p>Hello world</p>");
+```
+Correct:
+```tsx
+editorRef.current?.setValue(JSON.stringify([{ type: 'paragraph', children: [{ text: 'Hello world' }] }]));
+```
+`setValue` expects a serialized JSON string representing the Slate document structure. Passing raw HTML will cause parsing errors or an empty editor.
+
+Source: src/shared/ui/text-editor/text-editor.tsx:113
+
+### MEDIUM Missing synchronization handlers
+Wrong:
+```tsx
+<BaseTextEditor onSetHtml={(html) => setHtml(html)} /> 
+// Missing onSetContent
+```
+Correct:
+```tsx
+<BaseTextEditor 
+  onSetContent={(json) => setJson(json)} 
+  onSetHtml={(html) => setHtml(html)} 
+/>
+```
+Failing to provide `onSetContent` prevents the application from saving the internal editor state, making future edits impossible even if the HTML is saved.
+
+Source: src/shared/ui/text-editor/text-editor.tsx:83
+
+### MEDIUM Ignoring the debounce
+The editor uses a 1-second debounce (`TIME.seconds.seconds1`) before firing sync events. Do not expect immediate state updates on every keystroke. 
+
+Source: src/shared/ui/text-editor/text-editor.tsx:86

package/skills/utility-hooks/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: utility-hooks
+description: >
+  Essential helper hooks for responsive design, provider composition, 
+  and application lifecycle management.
+type: framework
+library: denwa-react-shared
+framework: react
+library_version: "1.0.88"
+requires:
+  - session-auth
+---
+
+# Shared Utilities & Hooks
+
+Standardized helpers to reduce boilerplate in provider setup and responsive logic.
+
+## Setup
+
+```tsx
+import { ProviderComposer, useViewPort } from 'denwa-react-shared';
+
+const App = ({ children }) => {
+  return (
+    <ProviderComposer
+      providers={[
+        <AuthProvider key="auth" />,
+        <ConfigProvider key="config" />,
+        <ReactQueryProvider key="query" />,
+      ]}
+    >
+      {children}
+    </ProviderComposer>
+  );
+};
+```
+
+## Core Patterns
+
+### Responsive Logic with useViewPort
+Standardizes breakpoints across the admin panel.
+
+```tsx
+const { isMobile, isTablet, isLaptop } = useViewPort();
+
+return (
+  <div>
+    {isMobile ? <MobileNav /> : <DesktopNav />}
+  </div>
+);
+```
+
+### Local Storage Wrapper
+Safe wrappers for browser storage with type-safety.
+
+```tsx
+import { getStorageItem, setStorageItem } from 'denwa-react-shared';
+
+const theme = getStorageItem('admin_theme', 'light');
+setStorageItem('admin_theme', 'dark');
+```
+
+## Common Mistakes
+
+### MEDIUM Pyramid of doom in Providers
+Wrong:
+```tsx
+<Auth>
+  <Config>
+    <Query>
+      <Layout>{children}</Layout>
+    </Query>
+  </Config>
+</Auth>
+```
+Correct:
+```tsx
+<ProviderComposer providers={[<Auth/>, <Config/>, <Query/>]}>
+  <Layout>{children}</Layout>
+</ProviderComposer>
+```
+`ProviderComposer` simplifies deep nesting of React providers, making the root file more readable.
+
+Source: src/shared/lib/provider-composer/index.tsx
+
+### MEDIUM Hardcoding breakpoints
+Wrong:
+```tsx
+const isMobile = useMediaQuery('(max-width: 768px)');
+```
+Correct:
+```tsx
+const { isMobile } = useViewPort();
+```
+Internal library components (like `AdminTable`) use breakpoints from `useViewPort`. Custom components should use the same hook to ensure consistent responsive behavior.
+
+Source: src/shared/lib/hooks/use-view-port.ts