@digi-frontend/dgate-api-documentation 1.4.97 → 2.0.1-test.0

package/README.md

@@ -0,0 +1,333 @@
+# DGate API Documentation View
+
+A modern, type-safe React component library for rendering and managing API documentation interfaces.
+Built with Zustand for state management and designed for scalability and developer experience.
+
+## Features
+
+- **🎯 Type-Safe State Management**: Built with Zustand and TypeScript for reliable state handling
+- **🏗️ Modular Architecture**: Separation of concerns between view and editor states
+- **⚡ Performance Optimized**: Selective subscriptions to minimize unnecessary re-renders
+- **🛠️ Developer Experience**: Comprehensive TypeScript support with excellent IDE integration
+- **🎨 Theme Support**: Built-in light/dark theme switching capabilities
+- **📝 Content Editing**: Integrated editor state management for content modification workflows
+
+## Quick Start
+
+### Installation
+
+```bash
+pnpm install
+```
+
+### Development
+
+```bash
+pnpm run build
+```
+
+### Usage Example
+
+```typescript
+import { useStore } from './store'
+
+function MyComponent() {
+  // State access
+  const theme = useStore((state) => state.view.theme)
+  const isEditing = useStore((state) => state.editor.isEditing)
+
+  // Actions
+  const setTheme = useStore((state) => state.setTheme)
+  const startEdit = useStore((state) => state.startEdit)
+
+  return (
+    <div className={`theme-${theme}`}>
+      <button onClick={() => setTheme('dark')}>Switch Theme</button>
+      <button onClick={() => startEdit('content')}>Edit Content</button>
+    </div>
+  )
+}
+```
+
+## Architecture
+
+### Store Organization
+
+The application state is organized into two primary domains:
+
+- **View State**: UI preferences, display data, and user interface state
+- **Editor State**: Content editing, form management, and modification tracking
+
+### Key Components
+
+- **`src/store/`**: Centralized state management with Zustand
+- **`src/store/README.md`**: Complete usage guide with examples
+- **`src/types/`**: TypeScript definitions and interfaces
+
+## State Management Patterns
+
+### Direct State Access
+
+```typescript
+const count = useStore((state) => state.view.count)
+```
+
+### Action Dispatching
+
+```typescript
+const increment = useStore((state) => state.increment)
+increment()
+```
+
+### Computed Values
+
+```typescript
+const totalItems = useStore((state) => state.getItemCount())
+```
+
+## Development Guidelines
+
+### Adding New Features
+
+1. Define interfaces in the store types
+2. Add initial state values
+3. Implement actions with proper typing
+4. Create computed getters as needed
+5. See `src/store/README.md` for detailed examples
+
+### Best Practices
+
+- Use TypeScript strictly for all implementations
+- Leverage Immer for immutable state updates
+- Organize actions by domain (view vs editor)
+- Implement computed values for derived state
+- Use selective subscriptions for performance
+
+## Technical Stack
+
+- **Zustand**: Lightweight state management
+- **TypeScript**: Type safety and developer experience
+- **Immer**: Immutable state updates
+- **React**: UI component framework
+- **DevTools**: Debugging and state inspection
+
+## Local Development Setup
+
+### Linking this package locally with pnpm
+
+This guide explains how to link **`@digi-frontend/dgate-api-documentation`** with a separate React
+app for live development.
+
+---
+
+#### Folder layout
+
+Place the app and this library **side-by-side** (for example, on Desktop):
+
+```
+Desktop/
+  dgate-api-documentation/       ← this repo (the library)
+  your-react-app/                 ← the consuming app
+```
+
+---
+
+#### 1) In the app: install peer dependencies
+
+The app must provide the library's required peers:
+
+```bash
+cd .\your-next-app
+pnpm add react react-dom antd @ant-design/cssinjs
+```
+
+> In the **library**, keep `react`, `react-dom`, `antd`, and `@ant-design/cssinjs` in
+> **peerDependencies** (and optionally in `devDependencies` for local lib testing).  
+> Do **not** put them in `dependencies` in the lib.
+
+---
+
+#### 2) In the app: link the library by relative path
+
+Remove any previous install and add the link:
+
+```bash
+pnpm remove @digi-frontend/dgate-api-documentation
+pnpm add @digi-frontend/dgate-api-documentation@link:../dgate-api-documentation
+```
+
+If the path has spaces, quote it:
+
+```bash
+pnpm add @digi-frontend/dgate-api-documentation@link:"../dgate-api-documentation"
+```
+
+---
+
+#### 3) In the app: Next.js config (webpack-only)
+
+Use webpack in dev and let Next transpile the linked package.
+
+**`next.config.ts` (in the app):**
+
+```ts
+import type { NextConfig } from 'next'
+
+const config: NextConfig = {
+  // Transpile the linked library if it ships TS/ESM source
+  transpilePackages: ['@digi-frontend/dgate-api-documentation'],
+
+  webpack(config) {
+    // Follow pnpm symlinks so HMR works across repos
+    config.resolve.symlinks = true
+    return config
+  },
+
+  eslint: { ignoreDuringBuilds: true },
+}
+
+export default config
+```
+
+**Start dev (webpack):**
+
+```bash
+pnpm dev
+```
+
+> Don't pass `--turbo`/`--turbopack`. Turbopack does not follow out-of-tree links.
+
+---
+
+#### 4) In the library: start development mode
+
+To enable live updates, run the development server in the **library** package:
+
+```bash
+cd ../dgate-api-documentation
+pnpm dev
+```
+
+This will start the library in watch mode, allowing changes to be reflected immediately in the
+consuming app.
+
+---
+
+#### 5) Verify the link
+
+From the **app** folder:
+
+```bash
+# Show that the dependency is linked
+pnpm list @digi-frontend/dgate-api-documentation
+```
+
+```bash
+# Show the symlink target path on disk
+(Get-Item ./node_modules/@digi-frontend/dgate-api-documentation).Target
+```
+
+Optionally resolve the entry file:
+
+```bash
+# CJS resolution (works if the package exposes a CJS entry)
+node -p "require.resolve('@digi-frontend/dgate-api-documentation')"
+```
+
+If your package is ESM-only:
+
+```bash
+node --input-type=module -p "import.meta.resolve('@digi-frontend/dgate-api-documentation')"
+```
+
+> If `require.resolve('@pkg/package.json')` fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`,  
+> that's normal unless you explicitly export `./package.json` in the lib's `exports`.
+
+---
+
+#### 6) Troubleshooting
+
+**Fast Refresh performs full reload**  
+A module from the lib is likely imported both inside and _outside_ the React render tree.  
+Split React components/hooks and non-React utilities into separate modules/entries (e.g.,
+`@pkg/react` vs `@pkg/core`).
+
+**"Invalid hook call" (duplicate React)**
+
+- Ensure the lib keeps `react` and `react-dom` in **peerDependencies** (not `dependencies`).
+- The app must install compatible versions.
+- If needed, hard-dedupe to the app's React in `next.config.ts`:
+
+```ts
+webpack(config) {
+  config.resolve.alias = {
+    ...(config.resolve.alias ?? {}),
+    react: require('path').resolve(__dirname, 'node_modules/react'),
+    'react-dom': require('path').resolve(__dirname, 'node_modules/react-dom'),
+  }
+  return config
+}
+```
+
+**File watching on Windows is flaky**  
+Enable polling temporarily:
+
+```bash
+$env:WATCHPACK_POLLING="true"; pnpm dev
+```
+
+**Avoid `pnpm link --global`**  
+Global links resolve peers relative to the lib folder and can cause missing/duplicate React/AntD in
+the app.
+
+---
+
+#### 7) Unlink / switch back to registry
+
+From the **app** folder:
+
+```bash
+pnpm remove @digi-frontend/dgate-api-documentation
+pnpm add @digi-frontend/dgate-api-documentation    # install from registry again
+```
+
+---
+
+#### 8) Alternatives (if you don't want a live symlink)
+
+**Local tarball**
+
+```bash
+# in the lib
+pnpm pack  # creates a .tgz
+# in the app
+pnpm add ../dgate-api-documentation/@digi-frontend/dgate-api-documentation-x.y.z.tgz
+```
+
+**`file:` protocol (no live updates)**
+
+```json
+{
+  "dependencies": {
+    "@digi-frontend/dgate-api-documentation": "file:../dgate-api-documentation"
+  }
+}
+```
+
+```bash
+pnpm install
+```
+
+---
+
+### Summary
+
+- Link with:
+
+```bash
+pnpm add @digi-frontend/dgate-api-documentation@link:../dgate-api-documentation
+```
+
+- Run **webpack dev** (`pnpm dev`, no Turbopack).
+- Keep peers in the **app**, not as `dependencies` in the lib.
+- Verify with `pnpm list` and `Get-Item … .Target`.