denwa-react-shared 1.0.87 → 1.0.89

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