@digi-frontend/dgate-api-documentation 2.0.1-test.9 → 2.0.2

package/README.md

@@ -1,333 +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`.
+# 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`.