@cdmbase/wiki-browser 12.0.18-alpha.5

package/lib/templates/content/docs/remix/configuration/routes-json-graphql.md

@@ -0,0 +1,79 @@
+---
+meta:
+    title: GraphQL Integration in routes.json
+    description: GraphQL Integration in routes.json
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: GraphQL Integration in routes.json...
+headers:
+    Cache-Control: no-cache
+---
+
+# GraphQL Integration in routes.json
+
+This document explains how to integrate GraphQL queries with your routes using the `routes.json` file.
+
+## Defining GraphQL Queries
+
+GraphQL queries are defined in the `queries` field of a route in `routes.json`.
+
+### Syntax
+
+```json
+{
+    "/path": {
+        "queries": {
+            "QueryName": "{ variableName: params.paramName }"
+        }
+    }
+}
+```
+
+### Example
+
+```json
+{
+    "/teams": {
+        "queries": {
+            "TeamsDocument": "{orgName: params.orgName, pageSize: 10}"
+        }
+    }
+}
+```
+
+## Passing Parameters to Queries
+
+Parameters can be passed to queries using the `params` object. The `params` object contains route parameters and query string parameters.
+
+### Example
+
+```json
+{
+    "/o/:orgName/teams": {
+        "queries": {
+            "TeamsDocument": "{orgName: params.orgName, pageSize: params.pageSize || 10}"
+        }
+    }
+}
+```
+
+## Handling Query Results in Components
+
+Query results are automatically passed to your components as props.
+
+### Example
+
+```javascript
+const Teams = (props) => {
+    const { data } = props.loaderData.TeamsDocument;
+    // Use data here
+};
+```
+
+## Related Topics
+
+- For detailed parameter generation, see [Query Params Generator](query-params-generator.md)
+- For automated loader generation, see [Generated Data Loaders](generated-data-loaders.md)
+- For authentication integration, see [Authentication and Authorization](routes-json-auth.md)
+
+[Back to Index](routes-json-index.md) | [Previous: Loaders and Data Fetching](routes-json-loaders.md) | [Next: Query Params Generator](query-params-generator.md)

package/lib/templates/content/docs/remix/configuration/routes-json-index.md

@@ -0,0 +1,112 @@
+---
+meta:
+    title: routes.json and Related Concepts Documentation
+    description: routes.json and Related Concepts Documentation
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: routes.json and Related Concepts Documentation...
+headers:
+    Cache-Control: no-cache
+---
+
+# routes.json and Related Concepts Documentation
+
+Welcome to the comprehensive documentation for `routes.json` and related concepts in our application architecture. This documentation covers various aspects of routing, data loading, styling, and best practices for building robust and efficient applications.
+
+## Table of Contents
+
+1. [Routes Overview](routes-json-overview.md)
+    - Purpose of routes.json
+    - Basic structure
+    - Key benefits
+
+2. [Field Descriptions](routes-json-fields.md)
+    - Common fields
+    - Authentication and authorization fields
+    - Component and data loading fields
+    - GraphQL and data fetching fields
+    - Additional configuration fields
+
+3. [Authentication and Authorization](routes-json-auth.md)
+    - Configuring authentication
+    - Setting up authorization
+    - Using authority and extraPermissions
+    - Automatic wrapper application
+
+4. [Loaders and Data Fetching](routes-json-loaders.md)
+    - Server-side loaders
+    - Client-side loaders
+    - Actions for form submissions
+    - Data loading patterns
+
+5. [Middleware System](routes-json-middleware.md)
+    - Middleware configuration
+    - Data flow through middlewares
+    - Error handling in middlewares
+
+6. [Advanced Configurations](routes-json-advanced.md)
+    - Custom wrappers
+    - Resource URIs
+    - Dynamic routes
+    - Route groups
+
+7. [Generated Data Loaders](generated-data-loaders.md)
+    - Automatic loader generation
+    - GraphQL query integration
+    - Cache strategies
+
+8. [Query Parameters Generator](query-params-generator.md)
+    - Simple vs complex parameters
+    - External value integration
+    - Parameter generation patterns
+
+9. [Resource Loaders](generated-resource-loaders.md)
+    - Resource route patterns
+    - Data resolution
+    - Error handling
+
+10. [CSS Import and Stylesheets](css-import-and-stylesheets.md)
+    - CSS module integration
+    - Style loading patterns
+    - Build configuration
+
+11. [Component Structure](component-structure-best-practices.md)
+    - Network request placement
+    - Data fetching patterns
+    - Component composition
+
+12. [Configuration Management](configurations.md)
+    - Configuration retrieval
+    - Settings management
+    - Preferences handling
+
+13. [Icon System](routes-extra-icons.md)
+    - Icon configuration
+    - Selective loading
+    - Custom icons
+
+14. [Best Practices](routes-json-best-practices.md)
+    - Organization patterns
+    - Security considerations
+    - Performance optimization
+
+## Quick Start
+
+1. Begin with [Routes Overview](routes-json-overview.md) to understand the basic concepts
+2. Learn about [Field Descriptions](routes-json-fields.md) for route configuration
+3. Set up [Authentication](routes-json-auth.md) for your routes
+4. Implement [Data Loading](routes-json-loaders.md) for your components
+
+## Version Compatibility
+
+- Remix: 2.0.0+
+- React: 18.0.0+
+- Node.js: 16.0.0+
+
+## Additional Resources
+
+- [Remix Documentation](https://remix.run/docs)
+- [React Documentation](https://react.dev)
+- [GraphQL Documentation](https://graphql.org/learn)
+
+Happy coding!

package/lib/templates/content/docs/remix/configuration/routes-json-loaders.md

@@ -0,0 +1,165 @@
+---
+meta:
+    title: Loaders and Data Fetching in routes.json
+    description: Loaders and Data Fetching in routes.json
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Loaders and Data Fetching in routes.json...
+headers:
+    Cache-Control: no-cache
+---
+
+# Loaders and Data Fetching in `routes.json`
+
+This document explains how to configure and use loaders, actions, and handle server-side and client-side code separation in your routes using the `routes.json` file.
+
+## Server-Side Loaders
+
+Server-side loaders are used to fetch data on the server before rendering a component. They are configured using the `hasLoader` field in `routes.json`. By default, server-side code must be located in files ending with `.server.js` for security and performance reasons.
+
+### Syntax
+
+```json
+{
+    "/path": {
+        "hasLoader": true,
+        "componentPath": "@adminide-stack/user-auth0/lib/components/callback.server.js"
+    }
+}
+```
+
+### Implementation
+
+When `hasLoader` is set to `true`, you need to implement a loader function in your route file:
+
+```javascript
+export const loader = async ({ params, context }) => {
+    // Fetch data here
+    return { data };
+};
+```
+
+### Handling Component with server code by using `hasServerCode`
+
+Remix recommends separating server-side logic into `.server.js` files for security and performance reasons. When the `hasServerCode` flag is set to `true`, it means that server-side code like loaders, actions, and headers will be located in a `.server.js` file, while client-side logic remains in the main component file.
+
+To ensure that `routes` understands there is a `.server.js` file in addition to `componentPath`, make sure to set `hasServerCode` to `true`.
+
+#### Example Configuration When `hasServerCode` is `true`
+
+```json
+{
+    "/login": {
+        "hasLoader": true,
+        "hasServerCode": true,
+        "componentPath": "@adminide-stack/user-auth0-browser-ant/lib/components/Login/index.js"
+    }
+}
+```
+
+#### Generated Wrapper When `hasServerCode` is `true`
+
+```javascript
+import OriginalComponent from '@adminide-stack/user-auth0-browser-ant/lib/components/Login/index.js';
+import { loader as loaderFunc } from '@adminide-stack/user-auth0-browser-ant/lib/components/Login/index.server.js';
+```
+
+#### Example Configuration When `hasServerCode` is `false`
+
+```json
+{
+    "/login": {
+        "hasLoader": true,
+        "hasServerCode": false,
+        "componentPath": "@adminide-stack/user-auth0-browser-ant/lib/components/Login/index.js"
+    }
+}
+```
+
+#### Generated Wrapper When `hasServerCode` is `false`
+
+```javascript
+import OriginalComponent, {
+    loader as loaderFunc,
+} from '@adminide-stack/user-auth0-browser-ant/lib/components/Login/index.js';
+```
+
+By separating the server-side code into `.server.js` files, we ensure that sensitive server-side logic is not included in the client bundle, as recommended by [Remix](https://remix.run/docs/en/main/discussion/server-vs-client).
+
+## Client-Side Loaders
+
+Client-side loaders are used to fetch data on the client after the initial render. They are configured using the `hasClientLoader` field in `routes.json`.
+
+### Syntax
+
+```json
+{
+    "/path": {
+        "hasClientLoader": true
+    }
+}
+```
+
+### Implementation
+
+When `hasClientLoader` is set to `true`, you need to implement a client loader function:
+
+```javascript
+export const clientLoader = async ({ params }) => {
+    // Fetch data here
+    return { data };
+};
+```
+
+## Actions for Form Submissions and Mutations
+
+Actions are used for handling form submissions and mutations. They are configured using the `hasAction` field in `routes.json`.
+
+### Syntax
+
+```json
+{
+    "/path": {
+        "hasAction": true
+    }
+}
+```
+
+### Implementation
+
+When `hasAction` is set to `true`, you need to implement an action function:
+
+```javascript
+export const action = async ({ request }) => {
+    // Handle form submission or mutation here
+    return { result };
+};
+```
+
+## Integrating Loaders with Authentication and Authorization
+
+Loaders can be integrated with authentication and authorization by checking the user's permissions before fetching data:
+
+```javascript
+export const loader = async ({ params, context }) => {
+    const { user } = context;
+    if (!user) {
+        throw new Error('Unauthorized');
+    }
+    if (!user.hasPermission('required.permission')) {
+        throw new Error('Forbidden');
+    }
+    // Fetch data here
+    return { data };
+};
+```
+
+## Why Separating Server-Side Code Matters
+
+Separating server-side code into `.server.js` files provides the following benefits:
+
+1. **Security**: Sensitive logic is not included in the client bundle.
+2. **Performance**: Smaller client bundles and faster loading times.
+3. **Clarity**: Clear distinction between client and server code, improving maintainability.
+
+[Back to Index](routes-json-index.md) | [Previous: Authentication](routes-json-auth.md) | [Next: Middleware System](routes-json-middleware.md)

package/lib/templates/content/docs/remix/configuration/routes-json-middleware.md

@@ -0,0 +1,196 @@
+---
+meta:
+    title: Middleware Configuration in routes.json
+    description: Middleware Configuration in routes.json
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Middleware Configuration in routes.json...
+headers:
+    Cache-Control: no-cache
+---
+
+# Middleware Configuration in routes.json
+
+## Overview
+
+Middlewares in `routes.json` allow you to inject data processing logic before your component renders. They can modify the context, prepare data, and interact with loaders.
+
+## Configuration
+
+### Basic Structure
+
+```json
+{
+    "/path": {
+        "exact": true,
+        "key": "unique-key",
+        "name": "Route Name",
+        "middlewares": ["@your-package/path/to/middleware.js"],
+        "componentPath": "@your-package/path/to/component.js",
+        "hasLoader": true,
+        "hasComponent": true,
+        "loaderReturnInfo": {
+            "returnType": "defer",
+            "hasOptions": false,
+            "keys": ["dataKey"]
+        }
+    }
+}
+```
+
+### Fields Explanation
+
+- **`middlewares`**: Array of paths to middleware files
+- **`hasLoader`**: Boolean indicating if the component has a loader
+- **`loaderReturnInfo`**: Configuration for loader return behavior
+    - `returnType`: Type of loader return ("defer" for async data)
+    - `hasOptions`: Boolean for additional options
+    - `keys`: Array of data keys that the loader will return
+
+## Middleware Implementation
+
+Middlewares should export a function with the following signature:
+
+```typescript
+export const middleware = async (
+    { context, request, params }, // Route information
+    dataLoader, // Data loader instance
+    next, // Next middleware function
+) => {
+    // Middleware logic
+    await next(); // Proceed to next middleware
+};
+```
+
+### Example Middleware
+
+```javascript
+export const middleware = async ({ context, request, params }, dataLoader, next) => {
+    const { apolloClient, logger } = context;
+
+    try {
+        // Async data fetching
+        const query1 = new Promise((resolve) => {
+            setTimeout(() => {
+                resolve({ data: 'Some api data' });
+            }, 1000);
+        });
+
+        logger.info('Data loaded and cached');
+
+        // Initialize componentData if needed
+        dataLoader.componentData = dataLoader.componentData || {};
+
+        // Assign async function to componentData
+        dataLoader.componentData.apiData = async () => await query1;
+
+        await next(); // Continue to next middleware
+    } catch (error) {
+        logger.error(error, 'Failed to load data:');
+        throw error;
+    }
+};
+```
+
+## Component Implementation
+
+Components can access middleware data through the loader and Remix's `useLoaderData` hook:
+
+```typescript
+import React from 'react';
+import { Await, useLoaderData } from '@remix-run/react';
+import { Spinner } from '@your-ui-library';
+import { defer } from '@remix-run/node';
+
+// Loader accessing middleware data
+export const loader = async ({ context, _dataContext }) => {
+    const apiData = _dataContext?.componentData?.apiData();
+    return defer({
+        apiData,
+    });
+};
+
+// Component using loader data
+export default (props) => {
+    const loaderData = useLoaderData();
+
+    return (
+        <React.Suspense fallback={<Spinner />}>
+            <Await resolve={Promise.all([loaderData.apiData])}>
+                {([{ data }]) => <YourComponent {...props} apiData={data} />}
+            </Await>
+        </React.Suspense>
+    );
+};
+```
+
+## Data Flow
+
+1. Middleware executes before the component loader
+2. Middleware adds data to the `dataLoader.componentData` object
+3. Loader accesses this data through `_dataContext.componentData`
+4. Component receives data through `useLoaderData` and `Await`
+
+## Best Practices
+
+1. **Error Handling**: Always include proper error handling in middlewares
+2. **Type Safety**: Use TypeScript interfaces for middleware parameters
+3. **Initialization**: Check if `componentData` exists before using
+4. **Async Operations**: Use `defer` for async data loading
+5. **Loading States**: Provide appropriate loading indicators
+
+## Example with Multiple Middlewares
+
+```json
+{
+    "/complex-route": {
+        "middlewares": ["@package/auth-middleware.js", "@package/data-middleware.js", "@package/logging-middleware.js"],
+        "hasLoader": true,
+        "loaderReturnInfo": {
+            "returnType": "defer",
+            "keys": ["authData", "apiData", "logData"]
+        }
+    }
+}
+```
+
+Middlewares execute in order, each having access to data set by previous middlewares:
+
+```typescript
+// First middleware
+export const authMiddleware = async ({ context }, dataLoader, next) => {
+    dataLoader.componentData = dataLoader.componentData || {};
+    dataLoader.componentData.authData = async () => ({ user: 'authenticated' });
+    await next();
+};
+
+// Second middleware
+export const dataMiddleware = async ({ context }, dataLoader, next) => {
+    dataLoader.componentData.apiData = async () => ({ data: 'fetched' });
+    await next();
+};
+
+// Component loader
+export const loader = async ({ _dataContext }) => {
+    const [authData, apiData] = await Promise.all([
+        _dataContext.componentData.authData(),
+        _dataContext.componentData.apiData(),
+    ]);
+
+    return defer({
+        authData,
+        apiData,
+    });
+};
+```
+
+## Troubleshooting
+
+Common issues and solutions:
+
+1. **Middleware Not Executing**: Verify path in `routes.json` is correct
+2. **Data Not Available**: Check `componentData` initialization
+3. **Type Errors**: Ensure proper TypeScript types for data
+4. **Loading Issues**: Verify `defer` usage and Suspense boundaries
+
+[Back to Index](routes-json-index.md) | [Previous: Loaders and Data Fetching](routes-json-loaders.md) | [Next: Advanced Configurations](routes-json-advanced.md)

package/lib/templates/content/docs/remix/configuration/routes-json-overview.md

@@ -0,0 +1,53 @@
+---
+meta:
+    title: routes.json Overview
+    description: routes.json Overview
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: routes.json Overview...
+headers:
+    Cache-Control: no-cache
+---
+
+# routes.json Overview
+
+The `routes.json` file is a crucial configuration file in our application that defines the structure and behavior of routes and their associated components. This file provides metadata for each route, including path, authority, loaders, and component paths.
+
+## Purpose
+
+The main purposes of `routes.json` are:
+
+1. Define the application's route structure
+2. Specify component paths for each route
+3. Configure authentication and authorization requirements
+4. Set up data loading mechanisms (server-side and client-side)
+5. Define GraphQL queries associated with routes
+6. Specify additional permissions and configurations
+
+## Basic Structure
+
+Each entry in `routes.json` represents a route and is structured as follows:
+
+```json
+{
+    "/path": {
+        "key": "unique.key",
+        "name": "Human Readable Name",
+        "path": "/path",
+        "componentPath": "path/to/component.js",
+        "auth": true,
+        "authority": ["required.permission"],
+        "hasLoader": true
+        // ... other configurations
+    }
+}
+```
+
+## Key Benefits
+
+1. **Centralized Configuration**: All route-related information is in one place.
+2. **Automatic Wrapping**: The application can automatically apply necessary wrappers based on the configuration.
+3. **Separation of Concerns**: Clearly separates routing logic from component implementation.
+4. **Easy Maintenance**: Simplifies the process of adding, modifying, or removing routes.
+
+[Back to Index](routes-json-index.md) | [Previous: Best Practices](routes-json-best-practices.md) | [Next: Field Descriptions](routes-json-fields.md)

package/lib/templates/content/docs/remix/data-loaders.md

@@ -0,0 +1,43 @@
+---
+meta:
+    title: Data Loaders
+    description: Data Loaders
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Data Loaders...
+headers:
+    Cache-Control: no-cache
+---
+
+# Data Loaders
+
+## What are Data Loaders
+
+[Data loaders](https://remix.run/docs/en/main/route/loader) are a powerful feature in Remix, that streamline data
+fetching by separating the concerns of UI and data handling. They allow developers to fetch data on the server side
+before rendering a component, ensuring that the UI is not tied to the data fetching logic. This abstraction simplifies
+code maintenance, improves performance by reducing client-side data fetching, and enhances SEO by preloading data. By
+defining data loaders at the route level, Remix ensures that each route manages its own data dependencies, leading to a
+more modular and scalable application structure.
+
+## What are Client Loaders
+
+[Client loaders](https://remix.run/docs/en/main/route/client-loader) in Remix are functions that fetch data on the
+client side, typically used when data needs to be refreshed or updated without a full page reload. Unlike server
+loaders, which fetch data on the server before rendering the page, client loaders run in the browser after the initial
+render.
+
+Here's a comparison table highlighting the differences between client loaders and server loaders in Remix:
+
+| Feature                | Server Loaders                                         | Client Loaders                                                       |
+| ---------------------- | ------------------------------------------------------ | -------------------------------------------------------------------- |
+| **Execution Context**  | Run on the server before rendering the page            | Run in the browser after the initial render                          |
+| **Initial Load Time**  | Improves initial load time by pre-fetching data        | Data fetched after initial load, may slightly delay updates          |
+| **SEO Benefits**       | Enhances SEO by providing pre-rendered content         | Limited SEO benefits as data is fetched client-side                  |
+| **Use Cases**          | Initial data fetching, SEO optimization, pre-rendering | Real-time updates, user-triggered data fetches, periodic re-fetching |
+| **Performance Impact** | Reduces client-side load, faster initial render        | Dynamic updates without full page reload, improves user experience   |
+| **Complexity**         | Simpler for initial load scenarios                     | More complex handling for dynamic, real-time data updates            |
+
+This table should help clarify when to use each type of loader based on your application's needs.
+
+## Auto generated loaders