@cdmbase/wiki-browser 12.0.18-alpha.5

package/lib/templates/content/docs/organization/organization-resource-vs-resource.md

@@ -0,0 +1,112 @@
+---
+meta:
+    title: Organization Resources vs normal resources
+    description: Organization Resources vs normal resources
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Organization Resources vs normal resources...
+headers:
+    Cache-Control: no-cache
+---
+
+## Organization Resources vs normal resources
+
+To differentiate between organizational resources and normal resources based on the criteria that organizational resources are those that involve grouping people (e.g., teams, projects, channels), while normal resources do not inherently involve grouping or managing people (e.g., timesheet entries, documents), we can define clear guidelines and scenarios.
+
+### Criteria for Differentiating Resources
+
+1. **Organizational Resources:**
+    - Involve grouping or managing people.
+    - Examples include teams, projects, channels, departments, and committees.
+    - These resources typically have members and are used to structure and manage the organization.
+    - Direct Member Management: Projects allow for direct addition of members. This is useful when the resource needs to directly manage the contributions and roles of individual members.
+    - Flexibility in Roles: You can assign specific roles and permissions directly to members within the project.
+
+2. **Normal Resources:**
+    - Do not involve grouping or managing people.
+    - Examples include timesheet entries, documents, files, individual tasks, and logs.
+    - These resources are typically individual records or items not used to organize people within the organization.
+    - Team-Based Management: Properties manage access through teams. This ensures that permissions are handled at a higher level of abstraction, simplifying the management of access for resources that don't require granular control over individual members.
+    - Scalability and Simplification: By using teams, you reduce the complexity of managing permissions directly on a large number of individual resources. Instead, you manage permissions at the team level and assign teams to resources.
+
+### Scenarios Covered
+
+1. **Teams:**
+    - **Organizational Resource:** A team is a group of people working together on specific tasks or projects. It has members who are part of the organization.
+    - **Example:** Development team, Marketing team.
+
+2. **Projects:**
+    - **Organizational Resource:** A project involves a group of people working towards a common goal or deliverable. It has members assigned to it.
+    - **Example:** Project Alpha, Website Redesign Project.
+
+3. **Channels:**
+    - **Organizational Resource:** Channels are used for communication within a group of people, such as in a messaging or collaboration platform.
+    - **Example:** Slack channel for the Sales team, Microsoft Teams channel for the HR department.
+
+4. **Timesheet Entries:**
+    - **Normal Resource:** Timesheet entries are individual records of time worked by employees. They are not used to organize or manage people directly.
+    - **Example:** Time record for an employee for a specific date and time.
+
+5. **Documents and Files:**
+    - **Normal Resource:** Documents and files are individual items that do not involve grouping people.
+    - **Example:** Company policy document, financial report file.
+
+6. **Individual Tasks:**
+    - **Normal Resource:** Tasks assigned to individuals that do not involve managing a group of people.
+    - **Example:** Task to update a document, task to attend a meeting.
+
+### Implementation
+
+Based on the differentiation criteria, you can structure your methods and data storage accordingly.
+
+#### Data Storage
+
+##### Organization Collection
+
+```json
+{
+    "_id": "org_123",
+    "name": "Organization Name",
+    "resources": {
+        "projects": [
+            { "id": "project_1", "name": "Project 1" },
+            { "id": "project_2", "name": "Project 2" }
+        ],
+        "teams": [
+            { "id": "team_1", "name": "Team 1" },
+            { "id": "team_2", "name": "Team 2" }
+        ],
+        "channels": [
+            { "id": "channel_1", "name": "Channel 1" },
+            { "id": "channel_2", "name": "Channel 2" }
+        ]
+    }
+}
+```
+
+##### Timesheet Collection
+
+```json
+{
+    "_id": "timesheet_1",
+    "orgId": "org_123",
+    "userId": "user_456",
+    "timeEntries": [
+        { "startTime": "2023-07-01T08:00:00Z", "endTime": "2023-07-01T16:00:00Z", "task": "Development" },
+        { "startTime": "2023-07-02T08:00:00Z", "endTime": "2023-07-02T16:00:00Z", "task": "Meeting" }
+    ]
+}
+```
+
+### Explanation of Differentiation
+
+- **Organizational Resources:** These include entities that group people together, such as teams, projects, and channels. These resources are managed within the `resources` field of the organization document.
+- **Normal Resources:** These are individual records that do not inherently group people. Examples include timesheet entries, documents, and individual tasks. These resources are stored in their own collections and linked to the organization via a foreign key (e.g., `orgId`).
+
+### Benefits
+
+- **Scalability:** By separating organizational resources from normal resources, the system can handle large numbers of individual records without impacting the performance of organization-level operations.
+- **Clarity:** The clear separation of concerns ensures that resources are managed appropriately based on their type, improving maintainability and readability.
+- **Efficiency:** Operations related to adding, removing, and querying resources are more efficient because each resource type is stored and managed in the most appropriate way.
+
+This approach provides a structured and scalable way to differentiate and manage organizational resources and normal resources within your application.

package/lib/templates/content/docs/remix/configuration/component-structure-best-practices.md

@@ -0,0 +1,152 @@
+---
+meta:
+    title: Component Structure Best Practices
+    description: Component Structure Best Practices
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Component Structure Best Practices...
+headers:
+    Cache-Control: no-cache
+---
+
+# Component Structure Best Practices
+
+This guide outlines best practices for structuring components in your application, focusing on the proper placement of network requests and separation of concerns.
+
+## Don't: Place Network Requests in Subcomponents
+
+Avoid placing GraphQL queries or other network requests directly in subcomponents. This practice can lead to performance issues and makes it harder to manage data flow.
+
+### Example of What Not to Do
+
+```javascript
+// SubComponent.js
+import { gql, useQuery } from '@apollo/client';
+
+const GET_USERS = gql`
+    query GetUsers {
+        users {
+            id
+            name
+            email
+        }
+    }
+`;
+
+function SubComponent() {
+    const { data, loading, error } = useQuery(GET_USERS);
+
+    if (loading) return <p>Loading...</p>;
+    if (error) return <p>Error: {error.message}</p>;
+
+    return (
+        <div>
+            <h1>Users</h1>
+            <ul>
+                {data.users.map((user) => (
+                    <li key={user.id}>
+                        {user.name} ({user.email})
+                    </li>
+                ))}
+            </ul>
+        </div>
+    );
+}
+
+export default SubComponent;
+```
+
+## Do: Centralize Data Fetching in Main Components
+
+Instead, centralize data fetching in the main routed components and pass data down to subcomponents as props.
+
+### Step-by-Step Refactor
+
+1. **Define the GraphQL Query in the Main Page**
+
+```javascript
+// mainPage.js
+import { gql } from '@apollo/client';
+
+const GET_USERS = gql`
+    query GetUsers {
+        users {
+            id
+            name
+            email
+        }
+    }
+`;
+```
+
+2. **Set Up the Loader Function**
+
+```javascript
+// mainPage.js
+import { json, LoaderFunction } from '@remix-run/node';
+import { useLoaderData } from '@remix-run/react';
+import { initializeApollo } from '~/utils/apolloClient';
+import SubComponent from './SubComponent';
+
+export let loader: LoaderFunction = async () => {
+    const client = initializeApollo();
+    try {
+        const { data } = await client.query({ query: GET_USERS });
+        return json(data);
+    } catch (error) {
+        console.error('Error fetching users:', error);
+        throw new Response('Error fetching users', { status: 500 });
+    }
+};
+```
+
+3. **Create the SubComponent as a Pure Component**
+
+```javascript
+// SubComponent.js
+function SubComponent({ users }) {
+    return (
+        <div>
+            <h1>Users</h1>
+            <ul>
+                {users.map((user) => (
+                    <li key={user.id}>
+                        {user.name} ({user.email})
+                    </li>
+                ))}
+            </ul>
+        </div>
+    );
+}
+
+export default SubComponent;
+```
+
+4. **Use the SubComponent in the Main Page**
+
+```javascript
+// mainPage.js
+import { useLoaderData } from '@remix-run/react';
+import SubComponent from './SubComponent';
+
+export default function MainPage() {
+    const { users } = useLoaderData();
+
+    return (
+        <div>
+            <SubComponent users={users} />
+        </div>
+    );
+}
+```
+
+## Benefits of This Approach
+
+1. **Improved Performance**: Data fetching is handled during server-side rendering.
+2. **Better Separation of Concerns**: Subcomponents are pure and focused on presentation.
+3. **Easier Testing**: Pure components are simpler to unit test.
+4. **Enhanced Reusability**: Subcomponents can be used in different contexts with different data.
+
+By following these best practices, you can create more maintainable, performant, and scalable components in your application.
+
+[Back to Index](routes-json-index.md) | [Previous: CSS Import and Stylesheets](css-import-and-stylesheets.md) | [Next: Configuration Management](configurations.md)

package/lib/templates/content/docs/remix/configuration/configurations.md

@@ -0,0 +1,218 @@
+---
+meta:
+    title: Configurations
+    description: Configurations
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Configurations...
+headers:
+    Cache-Control: no-cache
+---
+
+### Retrieving Configurations and Permissions in the Loader Data
+
+To retrieve configurations and permissions in the loader data, you need to:
+
+1. **Define Configurations in Routes**: Specify the configurations you need in the `configurations` field of the route definition. You can either fetch all configurations (`['*']`) or list specific configuration keys.
+2. **Use `resourceParams`**: This allows dynamic resolution of parameters for specific resources using placeholders like `$params` to construct the query or path used to fetch the configuration and permissions.
+3. **Fetch Data in Loader**: The loader fetches the configuration and permissions based on the defined `resourceParams` and configurations.
+
+Here’s how you can set up **routes**, **resourceParams**, and **configuration** to get configurations in the loader data.
+
+### Example 1: Generic Configuration (`configurations: ['*']`)
+
+This will retrieve all available configurations generically for the route.
+
+#### Route Definition:
+
+```ts
+export const project_route = [
+    {
+        name: 'menu.projects',
+        path: PROJECTS_ROUTES.projectView,
+        key: 'project-view',
+        priority: 7,
+        position: IMenuPosition.Middle,
+        icon: {
+            name: 'AiOutlineProject',
+            style: { fontSize: 'large' },
+        },
+        component: () => import('./components/index'),
+        authority: [IPreDefineAccountPermissions.viewSelfProjects, IPreDefineAccountPermissions.viewOthersProjects],
+        extraPermissions: [
+            IPreDefineAccountPermissions.manageSelfProjects,
+            IPreDefineAccountPermissions.editSelfProjects,
+            IPreDefineAccountPermissions.createSelfProjects,
+        ],
+        extraParams: ({ params }) => ({
+            resourceParams: {
+                path: IConfigCollectionName.Organizations, // Default to Organizations, could change to Projects based on logic
+                fragment: IConfigFragmentName.Settings,
+                query: {
+                    name: '$params.orgName',
+                },
+                configKey: '', // Optional. Add the initial hierarchy of the settings, or leave empty.
+            },
+        }),
+        configurations: ['*'], // Fetch all configurations
+    },
+];
+```
+
+#### Component Usage:
+
+Within the component, the configurations and permissions retrieved via the loader can be accessed using `useLoaderData`:
+
+```ts
+export default () => {
+    const loaderData = useLoaderData<{
+        permissions: IPermissions;
+        configurations: IPreferences;
+        dataContext: any;
+    }>();
+
+    const { permissions, configurations, dataContext } = loaderData;
+    const { preferencesInput } = dataContext; // Use this to get the settings URI for updates
+
+    const [updateConfigurationMutation] = useUpdateConfigurationMutation();
+
+    const overrides: IConfigurationOverridesInput = {
+        resource: preferencesInput.editableSettingsInput, // Override based on resource
+    };
+
+    // Function to update specific configuration
+    const updateConfiguration = ({
+        key,
+        value,
+    }: {
+        key: IConfigurationsFlattenedKeys;
+        value: string | number | boolean;
+    }) => {
+        return updateConfigurationMutation({
+            variables: {
+                key,
+                input: preferencesInput,
+                value,
+                target: ConfigurationTarget.ORGANIZATION_RESOURCE, // Use based on URI or resource context
+                overrides,
+            },
+        });
+    };
+
+    // Further component logic...
+};
+```
+
+### When to Use `resourceParams`:
+
+For organization-related pages, you generally **do not need to specify `resourceParams`** explicitly because the system will automatically resolve the organization's settings using the `:orgName` from the route. For example, the following default behavior will occur:
+
+```ts
+resourceParams = { path: 'organizations', query: { name: params.orgName }, fragment: 'settings' };
+```
+
+However, for **resource-specific pages** such as `o/:orgName/projects/:projectId`, you must provide `resourceParams` to get the specific configurations and permissions related to that resource (in this case, `projectId`):
+
+```ts
+resourceParams = {
+    path: IConfigCollectionName.Projects,
+    query: {
+        name: '$params.projectId', // Retrieves configurations for the specific project
+    },
+    fragment: IConfigFragmentName.Settings,
+};
+```
+
+### Example 2: Fetching Specific Configuration Keys
+
+When you want to optimize the loader by fetching only specific configurations, you can define the required configuration keys in the route.
+
+#### Route Definition:
+
+```ts
+export const project_route = [
+    {
+        name: 'menu.projects',
+        path: PROJECTS_ROUTES.projectView,
+        key: 'project-view',
+        priority: 7,
+        position: IMenuPosition.Middle,
+        icon: {
+            name: 'AiOutlineProject',
+            style: { fontSize: 'large' },
+        },
+        component: () => import('./components/index'),
+        authority: [IPreDefineAccountPermissions.viewSelfProjects, IPreDefineAccountPermissions.viewOthersProjects],
+        extraPermissions: [
+            IPreDefineAccountPermissions.manageSelfProjects,
+            IPreDefineAccountPermissions.editSelfProjects,
+            IPreDefineAccountPermissions.createSelfProjects,
+        ],
+        extraParams: ({ params }) => ({
+            resourceParams: {
+                path: IConfigCollectionName.Projects,
+                fragment: IConfigFragmentName.Settings,
+                query: {
+                    name: '$params.projectId', // Use the project ID for specific project configuration
+                },
+            },
+        }),
+        configurations: ['organization.projectDefaults', 'organization.projectSettings'], // Fetch specific configurations
+    },
+];
+```
+
+This fetches only the `projectDefaults` and `projectSettings` configurations for the project.
+
+### Example 3: No Configurations Specified
+
+If `configurations` is not specified in the route definition, no configuration data will be included in the loader. This is useful for pages where configurations are not required.
+
+#### Route Definition (No Configurations):
+
+```ts
+export const project_route = [
+    {
+        name: 'menu.projects',
+        path: PROJECTS_ROUTES.projectView,
+        key: 'project-view',
+        priority: 7,
+        position: IMenuPosition.Middle,
+        icon: {
+            name: 'AiOutlineProject',
+            style: { fontSize: 'large' },
+        },
+        component: () => import('./components/index'),
+        authority: [IPreDefineAccountPermissions.viewSelfProjects, IPreDefineAccountPermissions.viewOthersProjects],
+        extraPermissions: [
+            IPreDefineAccountPermissions.manageSelfProjects,
+            IPreDefineAccountPermissions.editSelfProjects,
+            IPreDefineAccountPermissions.createSelfProjects,
+        ],
+        extraParams: ({ params }) => ({
+            resourceParams: {
+                path: IConfigCollectionName.Projects,
+                fragment: IConfigFragmentName.Settings,
+                query: {
+                    name: '$params.projectId',
+                },
+            },
+        }),
+        // No configurations specified, so the loader won't fetch any
+    },
+];
+```
+
+In this case, no configurations will be fetched or included in the loader data.
+
+### Conclusion:
+
+- **Generic Configurations (`['*']`)**: Fetch all available configurations if you need them.
+- **Specific Configurations**: Use specific configuration keys to optimize performance.
+- **No Configurations**: If no configurations are needed, simply omit the `configurations` field from the route definition.
+
+In addition to using the above approach for configuring routes, try avoiding the use of `useSettings` or its wrapped loaders and hooks. Instead, use the route-based configuration outlined earlier to manage the retrieval of configurations and permissions. This method provides a more flexible and efficient way to handle dynamic data in the loader, ensuring that you have full control over the configurations fetched for each route or resource.
+
+This route-based approach allows for a more streamlined and maintainable way of handling settings, reducing dependencies on custom hooks or loaders like useSettings, and centralizing your configuration management within your routes.
+
+[Back to Index](routes-json-index.md) | [Previous: Component Structure](component-structure-best-practices.md) | [Next: Icon System](routes-extra-icons.md)

package/lib/templates/content/docs/remix/configuration/css-import-and-stylesheets.md

@@ -0,0 +1,142 @@
+---
+meta:
+    title: CSS Import and Stylesheet Links
+    description: CSS Import and Stylesheet Links
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: CSS Import and Stylesheet Links...
+headers:
+    Cache-Control: no-cache
+---
+
+# CSS Import and Stylesheet Links
+
+This guide demonstrates how to import CSS files from a package and return them as stylesheet links in a TypeScript project.
+
+## Installation
+
+To use CSS imports, follow these steps:
+
+1. Install the necessary packages:
+
+    ```bash
+    npm install <your-css-package>
+    # or
+    yarn add <your-css-package>
+    ```
+
+## Importing CSS Files
+
+### Method 1: Direct Import
+
+Append `?url` at the end of the CSS import:
+
+```javascript
+import '<your-css-package>/any.css';
+```
+
+### Method 2: Named Import with URL
+
+Use a named import with `?url`:
+
+```javascript
+import mainStyles from '<your-css-package>/main.css?url';
+```
+
+Note: Add `@ts-ignore` above the import to avoid TypeScript errors:
+
+```javascript
+//@ts-ignore
+import mainStyles from '<your-css-package>/main.css?url';
+```
+
+## Defining Stylesheet Links
+
+Create a function to return stylesheet links:
+
+```javascript
+//@ts-ignore
+import mainStyles from '<your-css-package>/main.css?url';
+//@ts-ignore
+import customStyles from '../styles/landing.css?url';
+
+export const links = () => {
+    return [
+        {
+            rel: 'stylesheet',
+            href: customStyles as unknown as string,
+        },
+        {
+            rel: 'stylesheet',
+            href: mainStyles as unknown as string,
+        },
+    ];
+};
+```
+
+## Usage in Components
+
+### Route Component (app.tsx)
+
+```tsx
+import { LinksFunction } from 'remix';
+import buttonStyles from '../styles/button.css?url';
+
+export const links: LinksFunction = () => {
+    return [{ rel: 'stylesheet', href: buttonStyles }];
+};
+
+import Button from '../components/Button';
+
+const ComponentWithLoader = (props) => {
+    return (
+        <React.Suspense fallback={<Spinner />}>
+            <Await resolve={OwnerPropertiesLoader} errorElement={<Alert>Error loading TypeLists!</Alert>}>
+                <div>
+                    <h1>Welcome to my Remix app!</h1>
+                    <Button />
+                </div>
+            </Await>
+        </React.Suspense>
+    );
+};
+```
+
+### Subcomponent (Button.tsx)
+
+```tsx
+export default function Button() {
+    return <button className="custom-button">Click me</button>;
+}
+```
+
+## Troubleshooting
+
+### Error: No route matches URL "/styles/landing.css"
+
+Ensure the `styles` folder is copied to the `lib` folder. Check `rollup.config.base.mjs` for the correct copy plugin configuration:
+
+```js
+const additionalPlugins = [copy({ patterns: ['**/cdm-locales/**/*', '**/styles/**/*'], rootDir: './src' })];
+```
+
+### Build error: Could not resolve "../styles/landing.css?url"
+
+Add the `ignoreCssUrlPlugin` to `rollup.config.base.mjs` after the `typescript` plugin:
+
+```js
+// Add this import at the top of the file
+import { ignoreCssUrlPlugin } from '@common-stack/rollup-vite-utils/lib/rollup/pluginIgnore.js';
+
+// In the plugins array
+plugins: [
+    // ... other plugins
+    typescript(),
+    ignoreCssUrlPlugin(),
+    // ... other plugins
+];
+```
+
+By following these guidelines, you can effectively manage CSS imports and stylesheets in your TypeScript project.
+
+[Back to Index](routes-json-index.md) | [Previous: Resource Loaders](generated-resource-loaders.md) | [Next: Component Structure](component-structure-best-practices.md)