updated docs

.github/workflows/build-and-cache.yaml

@@ -9,7 +9,7 @@ jobs:
   build-and-cache-zomes:
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest]
+        os: [ubuntu-latest, macos-latest, macos-13]
 
     runs-on: ${{ matrix.os }}
     steps:

docs/.vitepress/config.mts

@@ -2,9 +2,7 @@ import fs from 'fs';
 import { withMermaid } from 'vitepress-plugin-mermaid';
 
 // https://vitepress.dev/reference/site-config
-// Uncomment this to enable mermaid inside your site when this is solved: https://github.com/mermaid-js/mermaid/issues/4320
-// export default withMermaid({
-export default {
+export default withMermaid({
 	vue: {
 		template: {
 			compilerOptions: {
@@ -13,6 +11,11 @@ export default {
 			},
 		},
 	},
+	vite: {
+		optimizeDeps: {
+			include: ['mermaid', 'dayjs', '@braintree/sanitize-url'],
+		},
+	},
 	base: '/roles',
 	title: '@darksoil-studio/roles',
 	description: 'Roles zome for holochain apps',
@@ -21,10 +24,19 @@ export default {
 		// https://vitepress.dev/reference/default-theme-config
 
 		sidebar: [
+
+			{
+				text: 'Overview',
+				link: '/overview.md',
+			},
 			{
 				text: 'Setup',
 				link: '/setup.md',
 			},
+			{
+				text: 'hc progenitor',
+				link: '/hc_progenitor.md',
+			},
 			{
 				text: 'API Reference',
 				items: [
@@ -95,4 +107,4 @@ export default {
         `,
 		],
 	],
-};
+});

docs/elements/all-roles.md

@@ -27,6 +27,11 @@ Here is an interactive demo of the element:
 <element-demo>
 </element-demo>
 
+```mermaid
+graph TD;
+  A-->B
+```
+
 <script setup>
 import { onMounted } from "vue";
 import { ProfilesClient, ProfilesStore } from '@holochain-open-dev/profiles';
@@ -63,7 +68,14 @@ onMounted(async () => {
 
   const record = await mock.create_role_claim(roleClaim);
 
-  const store = new RolesStore(client);
+  const store = new RolesStore(client, {
+    roles_config: [{
+      role: 'editor',
+      singular_name: 'editor',
+      plural_name: 'editor',
+      description: 'editor',
+    }]
+  });
 
   render(html`
     <profiles-context .store=${profilesStore}>

docs/hc_progenitor.md

@@ -0,0 +1,7 @@
+# hc progenitor
+
+## Why
+The hc progenitor exists in order for developers to able to instansiate apps with an initial admin inscribed in the happ DNA.
+
+## Using hc progenitor
+hc progenitor is using tauri...

docs/index.md

@@ -10,6 +10,9 @@ hero:
     - theme: brand
       text: Setup
       link: /setup.md
+    - theme: alt
+      text: Overview
+      link: /overview.md
     - theme: alt
       text: Integrity Zome API
       link: "/backend/doc/roles_integrity/index.html"
@@ -27,3 +30,10 @@ features:
     details: Following the holochain-open-dev guidelines
     link: https://holochain-open-dev.github.io
 ---
+
+
+## Module summary
+
+This module gives your apps the power of **role management**.
+
+It uses a *progenitor* as initial admin and allows consuming applications to create arbitrary roles and bind the possibility of preforming actions to those roles. 

docs/overview.md

@@ -0,0 +1,55 @@
+# @darksoil-studio/roles
+
+## Modularity
+This module follows the [holochain-open-dev](https://github.com/holochain-open-dev/) pattern of developing holochain modules. Read [its documentation](https://holochain-open-dev.github.io) to understand more about its motivation and the big picture.
+
+To integrate this module into your application:
+
+- If you are starting a new project from scratch, it is very recommended to follow the [Template Setup](?path=/docs/template-setup--docs).
+- If not, you can visit [Setting up the Backend](?path=/docs/backend-setting-up-the-zomes--docs) and [Setting up the Frontend](?path=/docs/frontend-setting-up-the-frontend--docs).
+
+
+## Module design
+Creating roles in fully peer-to-peer systems can be tricky. There is no node in the network that by default is able to administer the system. In order to introduce rolebased management on Holochain, someone needs to be written into the app as it is generated as the agent that has special rights, this will then be part of the rules of the app that everyone plays by (the DNA).
+
+The pattern we are using in this module is the progenitor pattern. This means that the agent that instansiates the DNA writes themselves into the DNA as the original admin. Once an original admin is created, this administrator is able to generate further roles including additional administrators. Administrators are also able to remove all of the roles from Agents (including the Admin role of the progenitor). Below you will find graphical representations of how the module works.
+
+**This pattern creates the requirement of a layer outside the app (like a lobby) where a user is able to create the instanciation of the app so that the public key (AgentPubKey) associated with the original user is encoded into the DNA as it is being created. Read more about this in the implementation considerations section below.**
+
+
+### Original administrator (progenitor)
+In order to create an initial admin for the app, we are using the progenitor pattern. This means, the creator of the app (of the DNA actually) is the one who is the original admin. More admins can be added like adding any other roles by the progenitor.
+
+
+
+```mermaid
+graph TD;
+  Agent --has--> AgentPubKey
+  Agent --creates--> hApp_DNA
+  AgentPubKey --included when creating--> hApp_DNA
+  Agent --joins -->hApp_DNA
+  Agent --claims--> ADMIN_ROLE
+  hApp_DNA --validates--> ADMIN_ROLE
+
+```
+
+### Role assignment
+In the diagram below Alice is the progenitor and is therefore granted ADMIN_ROLE when entering the DNA. 
+
+```mermaid
+graph TD;
+    Alice -- claims on init --> ADMIN_ROLE
+    Alice -- creates for Caroline --> admin_role_assignment
+    Caroline -- uses assignment to claim --> ADMIN_ROLE
+    Caroline -- (now admin) creates for David --> editor_role_assignment
+    David -- uses assignment to claim --> EDITOR_ROLE
+
+```
+
+## Design considerations
+The possibility of actually using the capacities that an app developer is connecting to a role is validated by checking if the Agent has commited a claim to a role in their own source chain. The validation for creating such a claim for yourself is based on finding an assignment from an admin that allows one to create the claim. 
+
+It is implemented in this way in order to be sure that when someone is evaluating if an action is allowed (through a role) from an Agent, that enabling role claim must be found earlier in the source chain of that Agent to become deterministic.
+
+## Implementation considerations
+It is very important to understand that if you want to use this module, the instansiators AgentPubKey needs to be inserted into the [DNA properties](https://docs.rs/holochain_types/0.5.0-dev.0/holochain_types/prelude/struct.DnaModifiers.html#structfield.properties). This means that you need to have a running conductor that has access to an AgentPubKey that can be insterted into the app. 

docs/package.json

@@ -7,7 +7,8 @@
     "start": "pnpm dev",
     "dev": "pnpm setup:docs && vitepress dev",
     "build": "pnpm setup:docs && vitepress build",
-    "setup:docs": "pnpm -F @darksoil-studio/roles analyze && cp ../ui/custom-elements.json elements && pnpm setup:cargo",
+    "setup:docs": "pnpm setup:custom-elements && pnpm setup:cargo",
+    "setup:custom-elements": "pnpm -F @darksoil-studio/roles analyze && mkdir -p public/elements && cp ../ui/custom-elements.json ./public/elements/custom-elements.json",
     "setup:cargo": "cargo doc --release --no-deps --target-dir public/backend",
     "preview": "vitepress preview"
   },
@@ -21,7 +22,8 @@
     "api-viewer-element": "^1.0.0-pre.10",
     "lit": "^3.0.0",
     "vitepress": "^1.0.1",
-    "vitepress-plugin-mermaid": "^2.0.16"
+    "vitepress-plugin-mermaid": "^2.0.16",
+    "mermaid": "^11.0.0"
   },
   "dependencies": {
     "dayjs": "^1.11.11"