@cdmbase/wiki-browser 12.0.18-alpha.5

package/lib/templates/content/docs/remix/configuration/query-params-generator.md

@@ -0,0 +1,216 @@
+---
+meta:
+    title: Query Params Generator
+    description: Query Params Generator
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Query Params Generator...
+headers:
+    Cache-Control: no-cache
+---
+
+# Query Parameters and External Values in GraphQL Loaders
+
+## Simple Parameter Handling (Using params)
+
+When your query only needs values from `params`, use direct parameter definition in `routes.json`:
+
+```json
+{
+    "queries": {
+        "GetFilteredProjects": "{filter: {id: params.id, orgName: params.orgName}}",
+        "GetTeamMembers": "{teamId: params.teamId, pageSize: 10}"
+    }
+}
+```
+
+## Query Parameter Generator
+
+Use Query Parameter Generator when you need to incorporate values from external sources, imports, or complex computations.
+
+### When to Use Query Parameter Generator
+
+1. **External Configuration Values**
+
+```typescript
+import { dimensions } from './dimension.js';
+import { DEFAULT_PAGE_SIZE } from './constants';
+import { calculateDateRange } from './utils';
+
+export const queryParamsGenerator = (params) => ({
+    teamSearch: {
+        filters: {
+            teamId: params.teamId,
+            dimensions: dimensions, // From import
+            pageSize: DEFAULT_PAGE_SIZE, // From constants
+            dateRange: calculateDateRange(params.period), // From utility function
+        },
+    },
+});
+```
+
+2. **Environment-Specific Values**
+
+```typescript
+import { environmentConfig } from './config';
+
+export const queryParamsGenerator = (params) => ({
+    search: {
+        orgId: params.orgId,
+        region: environmentConfig.defaultRegion,
+        features: environmentConfig.enabledFeatures,
+    },
+});
+```
+
+3. **Computed or Transformed Values**
+
+```typescript
+import { getRolePermissions } from './permissions';
+import { getDefaultFilters } from './filters';
+
+export const queryParamsGenerator = (params) => {
+    const rolePermissions = getRolePermissions(params.role);
+    const defaultFilters = getDefaultFilters();
+
+    return {
+        userQuery: {
+            id: params.userId,
+            permissions: rolePermissions,
+            filters: {
+                ...defaultFilters,
+                ...params.filters,
+            },
+        },
+    };
+};
+```
+
+### Example Implementation
+
+```typescript
+// dimensions.ts
+export const dimensions = {
+    layout: 'horizontal',
+    maxItems: 50,
+    sortOrder: 'asc',
+};
+
+// searchConfig.ts
+export const searchDefaults = {
+    pageSize: 20,
+    sortField: 'createdAt',
+    includeArchived: false,
+};
+
+// queryParamGenerator.ts
+import { dimensions } from './dimensions';
+import { searchDefaults } from './searchConfig';
+import { formatDateRange } from './utils';
+
+export const queryParamsGenerator = (params) => ({
+    searchParams: {
+        basic: {
+            query: params.searchTerm,
+            pageSize: searchDefaults.pageSize,
+        },
+        advanced: {
+            dimensions: dimensions,
+            dateRange: formatDateRange(params.startDate, params.endDate),
+            sorting: {
+                field: searchDefaults.sortField,
+                order: dimensions.sortOrder,
+            },
+        },
+    },
+});
+
+// Component Usage
+const SearchComponent = () => {
+    const params = {
+        searchTerm: 'example',
+        startDate: '2024-01-01',
+        endDate: '2024-12-31',
+    };
+
+    const SearchQuery = useCustomQuery({
+        variables: queryParamsGenerator(params).searchParams,
+        fetchPolicy: 'cache-only',
+    });
+
+    return (
+        <Suspense fallback={<Spinner />}>
+            <Await resolve={SearchQuery}>{(data) => <SearchResults data={data} />}</Await>
+        </Suspense>
+    );
+};
+```
+
+### routes.json Integration
+
+When using query parameter generators, you reference them in `routes.json`:
+
+```json
+{
+    "queries": {
+        "SearchDocument": "queryParamsGenerator(params).searchParams"
+    }
+}
+```
+
+### Generated Loader
+
+```typescript
+export const defaultServerLoader = async ({ context, params, _dataContext = {} }) => {
+    const { apolloClient: client } = context;
+
+    // System automatically handles the query parameter generation
+    const searchResults = client.query({
+        query: SearchDocument,
+        variables: queryParamsGenerator(params).searchParams,
+        fetchPolicy: __SERVER__ ? 'network-only' : 'cache-first',
+    });
+
+    return {
+        data: {
+            searchResults,
+        },
+    };
+};
+```
+
+## Comparison: Direct Params vs Query Parameter Generator
+
+### Direct Params (Simple Cases)
+
+```json
+{
+    "queries": {
+        "GetTeamMembers": "{teamId: params.teamId, pageSize: 10}"
+    }
+}
+```
+
+✓ Good for: Simple parameter passing from URL/route parameters
+
+### Query Parameter Generator (Complex Cases)
+
+```typescript
+export const queryParamsGenerator = (params) => ({
+    teamMembers: {
+        teamId: params.teamId,
+        pageSize: environmentConfig.pageSize,
+        permissions: getRolePermissions(params.role),
+        filters: getTeamFilters(environmentConfig.region),
+    },
+});
+```
+
+✓ Good for:
+
+- Including imported values
+- Environment-specific configuration
+- Computed or transformed values
+- Complex parameter structures with external dependencies
+
+[Back to Index](routes-json-index.md) | [Previous: Generated Data Loaders](generated-data-loaders.md) | [Next: Resource Loaders](generated-resource-loaders.md)

package/lib/templates/content/docs/remix/configuration/routes-extra-icons.md

@@ -0,0 +1,103 @@
+---
+meta:
+    title: Icon System Documentation
+    description: Icon System Documentation
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Icon System Documentation...
+headers:
+    Cache-Control: no-cache
+---
+
+# Icon System Documentation
+
+This document explains the icon system used in our application, including configuration, implementation, and usage.
+
+## Icon Configuration in routes.json
+
+### Menu Icons
+
+In the `routes.json` file, you can specify an icon for each route that will appear in the menu. This is done using the `icon` property:
+
+```json
+{
+    "//listings": {
+        "path": "//listings",
+        "key": "SELECT_ORGANIZATION",
+        "icon": "FaHotel",
+        "name": "My Listings"
+        // ... other properties
+    }
+}
+```
+
+By default, any icon specified in the `icon` property of a route in `routes.json` will be automatically added to `selectiveIcons` This means it will be available for use in the application without any additional configuration.
+
+### Additional Icons for Components
+
+If a component requires more icons than just the menu icon, you can use the `extraIcons` property in the route configuration. This allows you to specify additional icons that should be loaded for a particular route:
+
+```json
+{
+    "//landing": {
+        "path": "//landing",
+        "key": "landing",
+        "extraIcons": [
+            "rifi.RifiAllCategories",
+            "rifi.RifiAppartments",
+            "rifi.RifiArtStudio"
+            // ... other icons
+        ]
+        // ... other properties
+    }
+}
+```
+
+## Icon Repository Configuration
+
+The icon repository configuration is defined in a `config.json` file . This configuration specifies where different sets of icons can be found. Here's an example of how the `iconsRepository` should be defined:
+
+```json
+{
+    "iconsRepository": {
+        "accounts": "@pubngo-stack/icons/lib/accounts/accountIcons/{iconName}.js",
+        "rifi": "@pubngo-stack/icons/lib/rifi/{iconName}.js",
+        "custom": "./path/to/custom/icons/{iconName}.js"
+    }
+}
+```
+
+In this configuration:
+
+- The keys (e.g., "rifi", "accounts", "custom") represent the repository prefixes.
+- The values are the paths where the icons can be found, with `{iconName}` as a placeholder for the specific icon name.
+
+The `{iconName}` placeholder in the paths will be replaced with the actual name of the icon from extraIcons when it's being loaded.
+
+This configuration allows the selective icons system to know where to find different sets of icons, enabling it to dynamically import the correct icon based on the name provided in the `icon` or `extraIcons` properties in the routes configuration.
+
+## Usage
+
+To use the selective icon system in your application:
+
+1. Import the default function from `selectiveIcons.js`.
+2. Call the function with the desired icon name.
+3. Handle the returned Promise to render the icon component.
+
+Example:
+
+```javascript
+import getIcon from '@app/selectiveIcons.js';
+
+function IconComponent({ name }) {
+    const [Icon, setIcon] = useState(null);
+
+    useEffect(() => {
+        getIcon(nameOfIcon).then((module) => setIcon(module.default));
+    }, [name]);
+
+    return Icon ? <Icon /> : null;
+}
+```
+
+[Back to Index](routes-json-index.md) | [Previous: Configuration Management](configurations.md) | [Next: Best Practices](routes-json-best-practices.md)

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

@@ -0,0 +1,86 @@
+---
+meta:
+    title: Advanced Configurations in routes.json
+    description: Advanced Configurations in routes.json
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Advanced Configurations in routes.json...
+headers:
+    Cache-Control: no-cache
+---
+
+# Advanced Configurations in routes.json
+
+This document covers advanced configurations and usage patterns for `routes.json`.
+
+## Custom Wrappers
+
+You can specify custom wrappers for your routes to add additional functionality or behavior.
+
+```json
+{
+    "/custom-route": {
+        "wrapperPath": "@your-package/custom-wrapper"
+    }
+}
+```
+
+## Resource URIs
+
+For routes that are associated with specific resources, you can specify a `resourceUri`:
+
+```json
+{
+    "/api/resource/:id": {
+        "resourceUri": "/api/resource/{id}"
+    }
+}
+```
+
+## Dynamic Routes
+
+For dynamic routes, use parameters in your path definition:
+
+```json
+{
+    "/user/:userId": {
+        "componentPath": "@your-package/UserProfile"
+    }
+}
+```
+
+## Nested Routes
+
+You can define nested routes to create a hierarchical structure:
+
+```json
+{
+    "/parent": {
+        "componentPath": "@your-package/ParentComponent",
+        "children": {
+            "/child": {
+                "componentPath": "@your-package/ChildComponent"
+            }
+        }
+    }
+}
+```
+
+## Route-Specific Configurations
+
+You can add custom configurations for specific routes:
+
+```json
+{
+    "/custom-config": {
+        "customConfig": {
+            "key1": "value1",
+            "key2": "value2"
+        }
+    }
+}
+```
+
+These advanced configurations allow for more flexible and powerful routing setups in your application.
+
+[Back to Index](routes-json-index.md) | [Previous: Middleware System](routes-json-middleware.md) | [Next: Generated Data Loaders](generated-data-loaders.md)

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

@@ -0,0 +1,113 @@
+---
+meta:
+    title: Authentication and Authorization in routes.json
+    description: Authentication and Authorization in routes.json
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Authentication and Authorization in routes.json...
+headers:
+    Cache-Control: no-cache
+---
+
+# Authentication and Authorization in routes.json
+
+This document explains how to configure authentication and authorization for routes using the `routes.json` file.
+
+## Authentication
+
+Authentication is configured using the `auth` field in the route definition.
+
+### Syntax
+
+```json
+{
+  "/path": {
+    "auth": true | false | "optional"
+  }
+}
+```
+
+### Options
+
+- `true`: The route requires authentication. Users must be logged in to access this route.
+- `false`: The route does not require authentication. It's publicly accessible.
+- `"optional"`: Authentication is optional for this route. Both authenticated and unauthenticated users can access it.
+
+### Example
+
+```json
+{
+    "/login": {
+        "auth": false
+    },
+    "/dashboard": {
+        "auth": true
+    },
+    "/public-content": {
+        "auth": "optional"
+    }
+}
+```
+
+## Authorization
+
+Authorization is configured using the `authority` and `extraPermissions` fields.
+
+### Authority
+
+The `authority` field specifies the permissions required to access the route.
+
+#### Syntax
+
+```json
+{
+    "/path": {
+        "authority": ["permission1", "permission2"]
+    }
+}
+```
+
+#### Example
+
+```json
+{
+    "/o/:orgName/settings": {
+        "authority": ["organization.settings.view"]
+    }
+}
+```
+
+### Extra Permissions
+
+The `extraPermissions` field specifies additional permissions that might be required for certain actions within the route.
+
+#### Syntax
+
+```json
+{
+    "/path": {
+        "extraPermissions": ["permission1", "permission2"]
+    }
+}
+```
+
+#### Example
+
+```json
+{
+    "/o/:orgName/settings": {
+        "authority": ["organization.settings.view"],
+        "extraPermissions": ["organization.settings.edit"]
+    }
+}
+```
+
+## Automatic Wrapping
+
+Based on the authentication and authorization configurations in `routes.json`, the application automatically applies the necessary wrappers to the components:
+
+1. If `auth` is set to `true`, an authentication wrapper is applied to ensure the user is logged in.
+2. If `authority` is specified, a permission wrapper is added to check the user's permissions.
+3. If `extraPermissions` are defined, additional permission checks may be implemented within the component.
+
+[Back to Index](routes-json-index.md) | [Previous: Field Descriptions](routes-json-fields.md) | [Next: Data Loading](routes-json-loaders.md)

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

@@ -0,0 +1,55 @@
+---
+meta:
+    title: Best Practices and Tips for routes.json
+    description: Best Practices and Tips for routes.json
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Best Practices and Tips for routes.json...
+headers:
+    Cache-Control: no-cache
+---
+
+# Best Practices and Tips for routes.json
+
+This document outlines best practices and tips for working with `routes.json` in your application.
+
+## Organizing routes.json
+
+1. **Group related routes**: Keep related routes together for better readability.
+2. **Use meaningful keys**: Choose descriptive keys that reflect the purpose of each route.
+3. **Maintain a consistent structure**: Follow a consistent pattern when defining routes.
+
+## Naming Conventions
+
+1. **Use kebab-case for paths**: e.g., `/user-profile` instead of `/userProfile`.
+2. **Use camelCase for keys**: e.g., `"userProfile"` instead of `"user-profile"`.
+3. **Be consistent with authority strings**: Use a consistent naming pattern for permissions.
+
+## Security Considerations
+
+1. **Always set the `auth` field**: Explicitly define authentication requirements for each route.
+2. **Use granular permissions**: Prefer specific permissions over broad ones.
+3. **Regularly audit your routes**: Review and update permissions as your application evolves.
+
+## Performance Optimization
+
+1. **Minimize the use of wildcards**: Be specific with route paths when possible.
+2. **Use exact matching**: Set `"exact": true` for routes that don't have children.
+3. **Optimize loader usage**: Only use loaders when necessary to avoid unnecessary data fetching.
+
+## Maintainability
+
+1. **Keep routes.json DRY**: Use variables or functions to generate repeated configurations.
+2. **Document complex configurations**: Add comments for non-obvious setups.
+3. **Version control**: Keep track of changes to `routes.json` in your version control system.
+
+## Troubleshooting Common Issues
+
+1. **Check for typos**: Many issues stem from simple typing errors.
+2. **Verify file paths**: Ensure all referenced component paths are correct.
+3. **Test authentication flows**: Regularly test different auth scenarios.
+4. **Monitor for circular dependencies**: Avoid circular references in your route structure.
+
+By following these best practices, you can create a more maintainable, secure, and efficient routing configuration for your application.
+
+[Back to Index](routes-json-index.md) | [Previous: Icon System](routes-extra-icons.md) | [Next: Routes Overview](routes-json-overview.md)

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

@@ -0,0 +1,79 @@
+---
+meta:
+    title: routes.json Field Descriptions
+    description: routes.json Field Descriptions
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: routes.json Field Descriptions...
+headers:
+    Cache-Control: no-cache
+---
+
+# routes.json Field Descriptions
+
+This document provides detailed descriptions of the fields used in the `routes.json` file.
+
+## Common Fields
+
+- **`path`**: (String) The URL path for the route.
+  Example: `"/login"` or `"/o/:orgName/dashboard"`
+
+- **`componentPath`**: (String) The path to the component to be rendered for this route.
+  Example: `"@adminide-stack/user-auth0-browser-ant/lib/pages/Login/Login.js"`
+
+- **`key`**: (String) A unique identifier for the route.
+  Example: `"login"` or `"organizations.dashboard"`
+
+- **`name`**: (String) A human-readable name for the route, often used in menus or breadcrumbs.
+  Example: `"Login Page"` or `"Organization Dashboard"`
+
+- **`exact`**: (Boolean) If true, the path must be an exact match.
+  Example: `true`
+
+## Authentication and Authorization Fields
+
+- **`auth`**: (Boolean or String) Represents the authentication requirement for the route.
+  Possible values: `true`, `false`, or `"optional"`
+
+- **`authority`**: (Array of Strings) Authority strings required to access the route.
+  Example: `["organization.settings.view"]`
+
+- **`extraPermissions`**: (Array of Strings) Additional permissions required for certain actions on the route.
+  Example: `["organization.settings.edit"]`
+
+## Component and Data Loading Fields
+
+- **`hasComponent`**: (Boolean) Indicates if the component exists for the route.
+  Example: `true`
+
+- **`hasLoader`**: (Boolean) If true, the route has a server-side loader.
+  Example: `true`
+
+- **`hasClientLoader`**: (Boolean) If true, the route has a client-side loader.
+  Example: `true`
+
+- **`hasAction`**: (Boolean) If true, the route has an action for form submissions or mutations.
+  Example: `true`
+
+- **`hasServerCode`**: (Boolean) Indicates if the route has server-specific code.
+  Example: `true`
+
+## GraphQL and Data Fetching Fields
+
+- **`queries`**: (Object) GraphQL queries that need to be run as part of the loader. Each query can have associated parameters.
+  Example:
+    ```json
+    "queries": {
+      "GetAllCountriesDocument": "{}"
+    }
+    ```
+
+## Additional Configuration Fields
+
+- **`configurations`**: (Object) Additional configuration options for the route.
+  (This field was not explicitly defined in the provided documentation, but it's mentioned as a possibility)
+
+- **`resourceUri`**: (String) URI for specific resources associated with the route.
+  (This field was not explicitly defined in the provided documentation, but it's mentioned as a possibility)
+
+[Back to Index](routes-json-index.md) | [Previous: Routes Overview](routes-json-overview.md) | [Next: Authentication](routes-json-auth.md)