@cdmbase/wiki-browser 12.0.18-alpha.5

package/lib/templates/content/docs/adminide-modules/preferences/pageSettings/migratingFromUseSettings.md

@@ -0,0 +1,215 @@
+# PageSettings with Simplified Apollo Client Hooks
+
+This document explains the new simplified implementation of pageSettings using Apollo Client hooks.
+
+## Overview
+
+The new implementation replaces the complex service-based logic in `useSetting.tsx` with simple GraphQL hooks that leverage Apollo Client's caching mechanisms.
+
+## Key Components
+
+### 1. Updated GraphQL Fragment (`pageSettings.gql`)
+
+```graphql
+fragment PageSettings on PageResourceSetting {
+    settings
+    resourceUri
+    target
+    updateTimestamp
+    keys
+    # Client-side fields for filtering and computed values
+    configKeyValue(configKey: $configKey) @client
+    filteredSettings(configKey: $configKey) @client
+    modifiedAt @client
+}
+```
+
+### 2. Enhanced Type Policies (`pageSettingsTypePolicy.ts`)
+
+The type policy includes client-side field resolvers for advanced use cases:
+
+- **`configKeyValue`**: Extracts a specific nested value from settings using lodash `get()`
+- **`filteredSettings`**: Returns filtered settings based on configKey
+- **`modifiedAt`**: Tracks when settings were last modified for cache invalidation
+
+### 3. Two Simple Hooks (`usePageSettings.tsx`)
+
+#### `usePageSettings` - Full pageSettings data
+
+```typescript
+export const usePageSettings = (variables: IPageSettingsVariable) => {
+    return useGetPageSettingsQuery({ variables: { resourceUri }, skip });
+};
+```
+
+#### `usePageSettingsConfigKey` - Specific config key value
+
+```typescript
+export const usePageSettingsConfigKey = <T = any>(variables: IPageSettingsConfigKeyVariable) => {
+    // Returns the specific configKey value extracted with lodash get()
+};
+```
+
+## Benefits
+
+1. **Simple & Direct**: Just Apollo Client hooks, no complex logic
+2. **Better Caching**: Leverages Apollo Client's sophisticated caching mechanisms
+3. **Type Safety**: Full TypeScript support with proper typing
+4. **Flexible**: Two hooks for different use cases
+5. **Performance**: Client-side extraction with lodash `get()`
+
+## Migration Guide
+
+### Before (useSetting)
+
+```typescript
+import { useSetting } from './useSetting';
+
+// For specific config key
+const { data, loading, error } = useSetting({
+    configKey: 'theme.colorScheme',
+    target: ConfigurationTarget.ORGANIZATION,
+});
+
+// For all settings
+const { data, loading, error } = useSetting({
+    target: ConfigurationTarget.ORGANIZATION,
+});
+```
+
+### After (usePageSettings)
+
+```typescript
+import { usePageSettingsConfigKey, usePageSettings } from './usePageSettings';
+import { URI } from '@adminide-stack/core';
+
+// For specific config key
+const resourceUri = URI.parse('adminide://org/myorg#settings');
+const { data, loading, error } = usePageSettingsConfigKey({
+    resourceUri,
+    configKey: 'theme.colorScheme',
+});
+
+// For all settings
+const { data, loading, error } = usePageSettings({
+    resourceUri,
+});
+const settings = data?.pageSettings?.settings;
+```
+
+## API Comparison
+
+| Feature             | useSetting       | usePageSettings            |
+| ------------------- | ---------------- | -------------------------- |
+| ConfigKey filtering | ✅ Service-based | ✅ Client-side with lodash |
+| Resource URI        | ❌ Implicit      | ✅ Explicit                |
+| Caching             | ❌ Complex       | ✅ Apollo Client           |
+| Type safety         | ⚠️ Partial       | ✅ Full                    |
+| Performance         | ❌ Service calls | ✅ Client-side             |
+| Simplicity          | ❌ Complex       | ✅ Simple hooks            |
+
+## Usage Examples
+
+### Basic Config Key Access
+
+```typescript
+const { data, loading, error } = usePageSettingsConfigKey({
+    resourceUri: URI.parse('adminide://org/myorg#settings'),
+    configKey: 'editor.fontSize',
+});
+// data contains just the fontSize value
+```
+
+### Full Settings Access
+
+```typescript
+const { data, loading, error } = usePageSettings({
+    resourceUri: URI.parse('adminide://org/myorg#settings'),
+});
+const settings = data?.pageSettings?.settings;
+// settings contains the full settings object
+```
+
+### Multiple Config Keys
+
+```typescript
+const { data, loading, error } = usePageSettings({
+    resourceUri: URI.parse('adminide://org/myorg#settings'),
+});
+
+if (data?.pageSettings?.settings) {
+    const themeSettings = get(data.pageSettings.settings, 'theme');
+    const editorSettings = get(data.pageSettings.settings, 'editor');
+    const fontSize = get(data.pageSettings.settings, 'editor.fontSize');
+}
+```
+
+## Cache Invalidation
+
+The type policy automatically handles cache invalidation by:
+
+1. Comparing organization modification timestamps
+2. Checking resource update timestamps
+3. Triggering refetch when org settings are newer than resource settings
+
+## Examples
+
+See `usePageSettings.example.tsx` for comprehensive usage examples including:
+
+- Basic configKey usage
+- Full settings access
+- Resource URI construction
+- Migration patterns
+- Multiple value access
+
+## Technical Details
+
+### Hook Implementation
+
+Both hooks are simple wrappers around `useGetPageSettingsQuery`:
+
+```typescript
+// Base hook - returns full Apollo query result
+export const usePageSettings = (variables: IPageSettingsVariable) => {
+    return useGetPageSettingsQuery({
+        variables: { resourceUri },
+        skip,
+    });
+};
+
+// ConfigKey hook - extracts specific value with lodash get
+export const usePageSettingsConfigKey = <T = any>(variables: IPageSettingsConfigKeyVariable) => {
+    const { data, loading, error, ...rest } = useGetPageSettingsQuery({
+        variables: { resourceUri },
+        skip,
+    });
+
+    const configKeyValue = data?.pageSettings?.settings ? get(data.pageSettings.settings, configKey) : null;
+
+    return {
+        data: configKeyValue as T,
+        loading,
+        error,
+        settings: data?.pageSettings?.settings,
+        pageSettings: data?.pageSettings,
+        ...rest,
+    };
+};
+```
+
+### Resource URI Construction
+
+You need to construct the proper resource URI:
+
+```typescript
+// Organization settings
+const orgUri = URI.parse('adminide://org/myorg#settings');
+
+// Workspace settings
+const workspaceUri = URI.parse('adminide://org/myorg/workspace/myworkspace#settings');
+
+// Project settings
+const projectUri = URI.parse('adminide://org/myorg/workspace/myworkspace/project/myproject#settings');
+```
+
+This approach provides better performance, simpler code, and improved caching while being more explicit about resource URIs.

package/lib/templates/content/docs/adminide-modules/preferences/permissions/Roles-Permissions.md

@@ -0,0 +1,72 @@
+---
+meta:
+    title: Roles & Permissions
+    description: Roles & Permissions
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Roles & Permissions...
+headers:
+    Cache-Control: no-cache
+---
+
+## Roles & Permissions
+
+Following Permissions scopes can be used. Each module can add permissions to the permission contributions.
+
+- Organization/Window Permissions
+- Resource Permissions
+
+### Pre defined roles
+
+Pre defined roles are added by default with selected Permissions values.
+
+**_ note _** It is hard coded in [here](https://github.com/cdebase/adminide-stack/blob/79cd0d746c9a116f1807b1d8a2a61ade8b611d48/packages-modules/account-api/server/src/roles/accounts-roles.ts#L44)
+
+In the UI, user will get the permissions based on his role in the organization.
+
+His organization role can be seen in the apollo cache as `OrganizationRole:/organizations:name=<org name>
+`.
+
+User updated permissions are stored in specific collection under `roles`.
+
+A role can be added at the resource level for the same user which overrides his organization role's permission.
+
+If the resource level permission is not set, it's value is inherited from the organization level.
+
+At the database side, the collection that is used will be usually `organizations` but if the user updates at resource level then it will be stored in that respective resource.
+
+Following query helps to get the organization level permission.
+
+```gql
+query GetRoleValue($key: String, $overrides: ConfigurationOverrides_Input) {
+  getPermissionValue(key: $key, overrides: $overrides) @client(always: true)
+}
+
+variables:
+{ "key": "accounts.inviteMember" }
+```
+
+Result
+
+```
+{
+  "data": {
+    "getPermissionValue": "Allow"
+  },
+  "loading": false,
+  "networkStatus": 7,
+  "stale": false
+}
+```
+
+If it needs resource level, we need to add `overrides` in the variables with the rsource uri.
+
+At the server side, the following query can be used to get the user's permissions based on his role.
+
+```gql
+query {
+  getViewerPermissions(input: { resource: "mongo-db-file:/teams?orgName%3Dstackflow-1%26name%3DNiceTeam2#settings", target: 5, roleName: "ADMIN"}) {
+  permissions
+    roleURL
+  }
+```

package/lib/templates/content/docs/adminide-modules/preferences/permissions/settingUserPermissions.md

@@ -0,0 +1,139 @@
+---
+meta:
+    title: Setting User Permissions
+    description: Setting User Permissions
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Setting User Permissions...
+headers:
+    Cache-Control: no-cache
+---
+
+## Setting User Permissions
+
+Cdmbase DevOps permissions are structured to provide a comprehensive and flexible security model that allows for precise control over who can access and perform various operations within the system. Here’s an overview of how permissions are structured in Cdmbase DevOps:
+
+### 1. **Security Namespaces and Tokens**
+
+Azure DevOps uses a concept called security namespaces to group permissions. Each namespace contains a set of permissions that apply to specific areas or resources within Cdmbase DevOps. Security tokens are used to reference specific objects within these namespaces.
+
+### 2. **Permission Levels**
+
+Permissions in Azure DevOps are organized at several levels:
+
+- **Organization Level**: Permissions that apply to the entire Cdmbase DevOps organization.
+- **Project Level**: Permissions specific to individual projects.
+- **Resource Level**: Permissions for specific resources within a project, such as repositories, pipelines, boards, etc.
+
+### 3. **Roles and Access Levels**
+
+Roles and access levels determine what permissions a user or group has within Cdmbase DevOps. These include:
+
+- **Access Levels**: Determine the features a user can access (e.g., Basic, Stakeholder, Visual Studio Subscriber).
+- **Security Groups**: Collections of users with a predefined set of permissions (e.g., Project Administrators, Contributors, Readers).
+
+### 4. **Permission Inheritance and Overrides**
+
+Permissions can be inherited from parent objects (e.g., from organization to project) but can also be explicitly set or overridden at more specific levels.
+
+### 5. **Deny, Allow, and Not Set**
+
+Permissions can be set to:
+
+- **Deny**: Explicitly denies the permission, overriding any allow permissions.
+- **Allow**: Explicitly allows the permission.
+- **Not Set**: Inherits permissions from the parent object.
+
+### Example Structure of Permissions in Cdmbase DevOps
+
+#### Organization Level Permissions
+
+These control access to the organization settings and features.
+
+- **Organization Owner**: Has full control over the entire organization.
+- **Billing Manager**: Can manage billing but not other administrative settings.
+
+#### Project Level Permissions
+
+These control access to project-specific settings and features.
+
+- **Project Administrator**: Can manage all aspects of a project.
+- **Contributor**: Can contribute to the project, such as adding code and managing builds.
+- **Reader**: Can view project information but cannot make changes.
+
+#### Resource Level Permissions
+
+These control access to specific resources within a project.
+
+- **Repositories**: Permissions like Read, Contribute, Branch, and Tag.
+- **Pipelines**: Permissions like View, Edit, and Queue builds.
+- **Boards**: Permissions like View, Edit, and Create work items.
+
+### Example: Setting Permissions for a User
+
+Here is an example of how permissions can be structured and set for a user in Cdmbase DevOps.
+
+#### Step 1: Assign Access Level
+
+Assign an access level to determine the features the user can access.
+
+```json
+{
+    "accessLevel": "Basic"
+}
+```
+
+#### Step 2: Add User to Security Groups
+
+Add the user to the relevant security groups.
+
+```json
+{
+    "securityGroups": ["Project Administrators", "Contributors"]
+}
+```
+
+#### Step 3: Set Resource-Level Permissions
+
+Explicitly set permissions for specific resources.
+
+```json
+{
+    "repository": {
+        "permissions": {
+            "Read": "Allow",
+            "Contribute": "Allow",
+            "Branch": "Deny",
+            "Tag": "Not Set"
+        }
+    },
+    "pipeline": {
+        "permissions": {
+            "View": "Allow",
+            "Edit": "Allow",
+            "Queue builds": "Deny"
+        }
+    },
+    "board": {
+        "permissions": {
+            "View": "Allow",
+            "Edit": "Deny",
+            "Create work items": "Allow"
+        }
+    }
+}
+```
+
+### Managing Permissions in Cdmbase DevOps
+
+Permissions in Cdmbase DevOps can be managed via the Cdmbase DevOps portal or through Cdmbase DevOps REST APIs for more automated and programmatic control.
+
+#### Using the Cdmbase DevOps Portal
+
+1. **Navigate to Organization Settings**: Manage organization-level permissions.
+2. **Navigate to Project Settings**: Manage project-level permissions.
+3. **Select Specific Resources**: Manage permissions for specific resources like repositories, pipelines, and boards.
+
+### Summary
+
+Cdmbase DevOps permissions are structured hierarchically, allowing for precise control over who can access and perform operations at various levels (organization, project, and resource). Roles, access levels, and security groups help manage permissions, while the inheritance and override mechanism ensures flexibility and control. Permissions can be managed through the Cdmbase DevOps portal or programmatically via REST APIs.

package/lib/templates/content/docs/adminide-modules/preferences/preference-dependency.md

@@ -0,0 +1,138 @@
+---
+meta:
+    title: Preference Dependency
+    description: Preference Dependency
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Preference Dependency...
+headers:
+    Cache-Control: no-cache
+---
+
+## How to call Preferences from Microservices
+
+Preferences are native to the Graphql Gateway server. Inorder to get preferences, you can call in same methodology used in the browser. Which is by using Apollo Client.
+
+1. First make sure all the preferences are mapped to the graphql schema so they can be called through graphql queries
+
+```
+type Preference_Timer_notifications {
+    approvalNotifications: Boolean
+    submitNotifications: Boolean
+    timeTrackingNotifications: Boolean
+    enableTimetrackerNotifications: Boolean
+}
+
+type Preference_Timer_Activity {
+    autoStop: Int
+    maxTimeInADay: Int
+    waitingTime: Int
+}
+
+type Preference_Timetracker {
+    activity: Preference_Timer_Activity
+    notifications: Preference_Timer_notifications
+}
+
+extend type Preferences {
+    timetracker: Preference_Timetracker
+}
+```
+
+2. Verify from the frontend graphql tools to make sure the `preferences` types have the preference you want to query
+
+![codegen](/assets/images/preferences_graphql_type.png)
+
+3. If you using Moleculer Plugin and within it one of the service has dependency on PreferencesService then use the Mixin to load apolloClient in the Moleculer Plugin. As the `PreferencesService` is depend on `Apollo Client`
+
+```
+import { ApolloClientMixin, getPreferenceSettingsInput } from '@adminide-stack/platform-server';
+
+export class TimesheetMoleculerService extends Service {
+    private timesheetService: ITimesheetService;
+
+    private container: Container;
+
+    constructor(broker: ServiceBroker, { container, ...settings }: { container: Container }) {
+        super(broker);
+        this.container = container;
+
+        const topic = MoleculerTopics.Timesheet;
+
+        this.parseServiceSchema({
+            name: topic,
+            mixins: [ApolloClientMixin],
+            settings: {
+                apolloClient: {
+                    serverUri: config.GRAPHQL_URL,
+                },
+            },
+            events: {
+                ....
+            }
+            this.container.bind(ClientTypes.ApolloClient).toConstantValue(this.apolloClient);
+```
+
+4. Now in the Service to make a call we need to create a fragment of the `preferences` fields you need.
+
+a)
+
+```
+export const TrackerNotificationsPreferencesFragmentDoc = gql`
+    fragment TrackerNotificationsPreferences on Preferences {
+  timetracker {
+    notifications {
+      approvalNotifications
+      enableTimetrackerNotifications
+      submitNotifications
+    }
+  }
+}
+    `;
+```
+
+b)
+
+Make sure the file is included in the codegen.yaml
+
+![codegen](/assets/images/codegen_file_update.png)
+
+c) Run `yarn generateGraphql` to generate types
+
+d) import the `fragment` and call the `preferencesService.viewerSettings`
+
+```
+import { ITrackerNotificationsPreferencesFragment } from '...timetracker-core';
+const timerNotification =  require('../graphql/fragments/timer-notifications.gql');
+
+    const settings = await this.preferencesService.viewerSettings<ITrackerNotificationsPreferencesFragment>(
+        {
+            target: ConfigurationTarget.ORGANIZATION,
+            settingsResource: resourceUri,
+        },
+        {
+            fragmentName: 'TimetrackerPreferences',
+            fragmentDoc: timerNotification.default,
+        },
+    );
+
+```
+
+e. Note, webpack or rollback generator should load the `.gql` file imported as raw text instead of compiled gql.
+
+```
+// in webpack.config.js
+
+    module: {
+        rules: [
+            ...
+            {
+                test: /\.(gql)$/,
+                exclude: /node_modules/,
+                use: 'raw-loader',
+            },
+            ....
+        ],
+    },
+
+```

package/lib/templates/content/docs/adminide-modules/preferences/route-based-configuration.md

@@ -0,0 +1,41 @@
+---
+meta:
+    title: Route Based Configuration
+    description: Route Based Configuration
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Route Based Configuration...
+headers:
+    Cache-Control: no-cache
+---
+
+## Route based configuration
+
+Based on the URL route, we pull the `orgName` which is useful to pull the configuration resources to build `configurationService`.
+
+ConfigurationService methods such as `getValue` will give the merge of all the above settings in that order.
+
+Default Configuration will be overwritten by User Configuration and User Configuration will be overwritten by Organization Configuration and follows the order for Resource Configuration.
+
+`Resource Configuration` are related to specific `url` path within that organization that may have it's own configuration.
+
+Here is a small example:
+Organization can have multiple Teams. Each Team can have it's own Configuration. In this case, a resource configuration is created for each Team and when requesting the configuration value we need to provide the team resource URI path like:
+
+```
+getValue('organization.team.visibility', { resource: 'mongo-db-file:///team/<teamId>/settings })
+
+--check its interface
+    getValue<T>(section: string, overrides: IConfigurationOverrides): T;
+
+```
+
+The `overrides` parameter will take the resource and overrides the resulted organizationConfiguration with the `resourceConfiguration` value and gives the final `value`.
+
+`orgName` is stateless and will be placed in the url for tracking the page and its configuration to be loaded.
+
+Based on the following sample url, the route path that is used to generate is `/o/:orgName/teams/dashboard` and params value is `orgName` is `testorg`. Based on this `orgName`, we reload the configuration with `oraganizationContextService.initialize(<orgName>)` which eventually will load configurationService based on that specific organization.
+
+```
+https://idefront-adminide-v1.cdebase.io/teams/testorg/dashboard
+```

package/lib/templates/content/docs/adminide-modules/preferences/schema-configuration.md

@@ -0,0 +1,71 @@
+---
+meta:
+    title: Schema Configuration
+    description: Schema Configuration
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Schema Configuration...
+headers:
+    Cache-Control: no-cache
+---
+
+# Conditional Field Rendering - Schema Documentation
+
+This documentation explains how to extend a schema to conditionally render a new field based on a specific condition. This example focuses on a generic schema and uses a placeholder `$newFieldCondition` for the condition.
+
+## Introduction
+
+You may need to conditionally display or hide a field in your data schema based on certain criteria. This document outlines the steps to add a new field to a generic schema and specify conditions for when it should be rendered.
+
+## Updating the Schema
+
+### Step 1: Update the Schema Object
+
+Modify the schema object to include the new field (`newField`) at the appropriate location within the existing structure.
+
+```javascript
+export const genericSchema = {
+    def: {},
+    schema: {
+        type: 'object',
+        properties: {
+            existingField1: { type: 'string' },
+            existingField2: { type: 'number' },
+            // ... (other existing fields)
+            newField: { type: 'string' }, // New field
+        },
+        if: {
+            properties: {
+                $newFieldCondition: { const: true }, // Placeholder for the condition
+            },
+        },
+        then: {
+            properties: {
+                $conditionalField: { type: 'string' }, // Define the new field in 'then' when the condition is met
+            },
+        },
+    },
+};
+```
+
+### Step 2: Define the Condition
+
+Define the condition within the `if` section. Replace the `$newFieldCondition` placeholder with the actual property and condition that should trigger the visibility of `newField`. For example:
+
+```javascript
+if: {
+   properties: {
+       someProperty: { const: "" }, // Example condition: newField shown when someProperty is greater than 10
+   },
+}
+```
+
+The `then` section specifies what properties to add when the condition is met.
+
+## How the UI Looks
+
+In the user interface, the appearance of the `newField` element depends on whether the specified condition is met. Here's how the UI behaves:
+
+- **Condition Met**: When the condition, as defined in the schema (e.g., `someProperty` > 10), is satisfied, the `newField` will be rendered and displayed within the user interface. Users can interact with this field as they would with any other field.
+
+- **Condition Not Met**: If the condition is not met, the `newField` will not be displayed in the UI. It will be hidden, and users will not see or interact with it. This behavior ensures that the UI remains user-friendly and responsive to the defined conditions.

package/lib/templates/content/docs/adminide-modules/preferences/supported.md

@@ -0,0 +1,24 @@
+---
+meta:
+    title: Supported
+    description: Supported
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Supported...
+headers:
+    Cache-Control: no-cache
+---
+
+## Supported
+
+Multiple overrides identifier using `[a][b]`
+
+```
+"workbench.colorCustomizations": {
+		"[GitHub Sharp][GitHub Sharp Dark]": {
+                       "editorPane.background": "#d6d0d01a",
+			"sideBarSectionHeader.border": "#D3D3D3",
+                 }
+}
+
+```