WIP docs

docs/.gitignore

@@ -4,17 +4,5 @@ node_modules/
 # logs
 npm-debug.log*
 
-# environment variables
-.env
-.env.production
-
-# macOS-specific files
-.DS_Store
-
-# Rocket ignore files
-*-mdjs-generated.js
-*-converted-html.js
-*-converted-md.js
-*-converted-md-source.js
-_site
-_site-dev
+.vitepress/cache
+public/backend/

docs/.vitepress/config.mts

@@ -1,28 +1,76 @@
-import { defineConfig } from 'vitepress'
+import { defineConfig } from "vitepress";
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
+  vue: {
+    template: {
+      compilerOptions: {
+        // treat all tags with a dash as custom elements
+        isCustomElement: (tag) => tag.includes("-"),
+      },
+    },
+  },
+  base: "/profiles",
   title: "@holochain-open-dev/profiles",
   description: "Profiles module for holochain apps",
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
-    nav: [
-      { text: 'Home', link: '/' },
-      { text: 'Examples', link: '/markdown-examples' }
-    ],
+    // nav: [{ text: "Home", link: "/" }],
 
     sidebar: [
       {
-        text: 'Examples',
+        text: "Guides",
+        items: [
+          {
+            text: "Setup",
+            link: "/setup.md",
+          },
+        ],
+      },
+      {
+        text: "API Reference",
         items: [
-          { text: 'Markdown Examples', link: '/markdown-examples' },
-          { text: 'Runtime API Examples', link: '/api-examples' }
-        ]
-      }
+          {
+            text: "Integrity Zome",
+            link: "/backend/doc/hc_zome_profiles_integrity/index.html",
+            target: "_blank",
+          },
+          {
+            text: "Coordinator Zome",
+            link: "/backend/doc/hc_zome_profiles_coordinator/index.html",
+            target: "_blank",
+          },
+          {
+            text: "Frontend",
+            items: [
+              {
+                text: "ProfilesStore",
+                link: "/profiles-store.md",
+              },
+              {
+                text: "Elements",
+                items: [
+                  {
+                    text: "profiles-context",
+                    link: "/profiles-context.md",
+                  },
+                  {
+                    text: "profile-prompt",
+                    link: "/profile-prompt.md",
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
     ],
 
     socialLinks: [
-      { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
-    ]
-  }
-})
+      {
+        icon: "github",
+        link: "https://github.com/holochain-open-dev/profiles",
+      },
+    ],
+  },
+});

docs/2.1-backend-setup.md

@@ -0,0 +1,36 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="Backend/Setting up the zomes" />
+
+# Setting up the zomes
+
+> It's much much easier to set up the backend by using the [holochain-open-dev template](https://github.com/holochain-open-dev/templates). Only follow this guide if you can't use the template.
+
+> This guide assumes you are inside a nix-shell environment with `hc scaffold` available.
+
+1. Scaffold a new zome pair named `profiles` with:
+
+```bash
+hc scaffold zome profiles
+```
+
+Select the "Integrity/coordinator zome pair" option, and accept the path that the scaffolding tool offers to scaffold the zomes.
+
+2. Add the `hc_zome_profiles_coordinator` and `hc_zome_profiles_integrity` zomes as dependencies with:
+
+```bash
+cargo add -p profiles hc_zome_profiles_coordinator
+cargo add -p profiles_integrity hc_zome_profiles_integrity
+```
+
+3. Go into the newly scaffolded integrity zome's `lib.rs` (its path may be similar to `dnas/lobby/zomes/integrity/profiles/src/lib.rs`) and **replace its contents with**:
+
+```rust
+extern crate hc_zome_profiles_integrity;
+```
+
+4. Go into the newly scaffolded coordinator zome's `lib.rs` (its path may be similar to `dnas/lobby/zomes/coordinator/profiles/src/lib.rs`) and **replace its contents with**:
+
+```rust
+extern crate hc_zome_profiles_coordinator;
+```

docs/2.2-integrity.mdx

@@ -0,0 +1,11 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="Backend/Integrity" />
+
+# hc_zome_profiles_integrity
+
+Use this crate directly if you want include and maybe extend this zome in your DNA.
+
+Notice that just by importing this crate, all its zome functions will be automatically defined in the consuming crate. This could create collisions in function names or entry definitions.
+
+[Read the documentation for the types available from this zome](https://docs.rs/hc_zome_profiles_integrity).

docs/2.3-coordinator.mdx

@@ -0,0 +1,11 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="Backend/Coordinator" />
+
+# hc_zome_profiles_coordinator
+
+Use this crate directly if you want include and maybe extend this zome in your DNA.
+
+Notice that just by importing this crate, all its zome functions will be automatically defined in the consuming crate. This could create collisions in function names or entry definitions.
+
+[Read the documentation for all the functions available from this zome.](https://docs.rs/hc_zome_profiles_coordinator)

docs/3.1-frontend-setup.mdx

@@ -0,0 +1,125 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="Frontend/Setting up the frontend" />
+
+# Seting Up the Frontend
+
+> It's much much easier to set up the frontend by using the [holochain-open-dev template](https://github.com/holochain-open-dev/templates). Only follow this guide if you can't use the template.
+
+> This guide assumes you are building a web application written in JS or TS, using NPM as the package manager.
+
+> [Go here](https://holochain-open-dev.github.io/reusable-modules/frontend/frameworks/) to look at examples of integration of this module in different frontend frameworks (Vue, Svelte, etc.).
+
+1. Install this module and its necessary dependencies with:
+
+```bash
+npm install @holochain-open-dev/profiles
+```
+
+Careful! If you are using NPM workspaces (which is the case for the apps generated with the holochain scaffolding tool (`hc scaffold`), you need to specify which workspace you want to install those dependencies to, and run the command from the root folder of the repository. In the case of the apps generated with the scaffolding tool:
+
+```bash
+npm install @holochain-open-dev/profiles -w ui
+```
+
+2. Connect to Holochain with the `AppAgentClient`, and create the `ProfilesStore` with it:
+
+```js
+import { ProfilesStore, ProfilesClient } from "@holochain-open-dev/profiles";
+import { AppWebsocket, AppAgentWebsocket } from "@holochain/client";
+
+async function setupProfilesStore() {
+  const client = await AppAgentWebsocket.connect('', '')
+
+// TODO: change "MY_CELL_ROLE" for the roleId that you can find in your "happ.yaml"
+  const profilesStore = new ProfilesStore(new ProfilesClient(client, '<MY_CELL_ROLE>'), {
+    avatarMode: "avatar-optional",
+  });
+  return profilesStore;
+}
+```
+
+3. Import the `<profiles-context>` element and add it to your html **wrapping the whole section of your page in which you are going to be placing** the other elements from `@holochain-open-dev/profiles`:
+
+```js
+// This can be placed in the index.js, at the top level of your web-app.
+import "@holochain-open-dev/profiles/dist/elements/profiles-context.js";
+```
+
+And then add the `<profiles-context>` element in your html:
+
+```html
+<profiles-context>
+  <!-- Replace <create-profile> with the contents of your application -->
+  <create-profile></create-profile>
+</profiles-context>
+```
+
+4. Attach the `profilesStore` to the `<profiles-context>` element:
+
+- Go to [this page](https://holochain-open-dev.github.io/reusable-modules/frontend/frameworks/), select the framework you are using, and follow its example.
+
+You need to set the `store` property of it to your already instantiated `ProfilesStore` object:
+
+- If you **are using some JS framework**:
+
+```html
+<!-- React -->
+<profiles-context store={profilesStore}><!-- ... --></profiles-context>
+
+<!-- Angular -->
+<profiles-context [store]="profilesStore"><!-- ... --></profiles-context>
+
+<!-- Vue -->
+<profiles-context :store="profilesStore"><!-- ... --></profiles-context>
+
+<!-- Svelte -->
+<profiles-context store={profilesStore}><!-- ... --></profiles-context>
+
+<!-- Lit -->
+<profiles-context .store=${profilesStore}><!-- ... --></profiles-context>
+```
+
+OR
+
+- If you **are not using any framework**:
+
+```js
+const contextElement = document.querySelector("profiles-context");
+contextElement.store = store;
+```
+
+> You can read more about the context pattern [here](https://holochain-open-dev.github.io/reusable-modules/frontend/using/#context).
+
+5. [Choose which elements you need](?path=/docs/frontend-elements) and import them like this:
+
+```js
+import "@holochain-open-dev/profiles/dist/elements/profiles-context.js";
+```
+
+And then they are ready be used inside the `<profiles-context>` just like any other HTML tag.
+
+This will define all the elements from this module in the global `CustomElementsRegistry`. You can read more about Custom Elements [here](https://developers.google.com/web/fundamentals/web-components/customelements).
+
+6. Add your preferred shoelace theme in your `<head>` tag:
+
+```html
+  <head>
+    <link rel="stylesheet" href="path/to/shoelace/dist/themes/light.css" />
+  </head>
+```
+
+or in JS:
+
+```js
+import '@shoelace-style/shoelace/dist/themes/light.css';
+```
+
+You can read more about how to initialize the shoelace theme [here](https://shoelace.style/getting-started/themes?id=activating-themes).
+
+That's it! You can spend some time now to take a look at [which elements are available for you to reuse](?path=/docs/frontend-elements-create-profile--docs).
+
+# Demo
+
+You can see a full working example of the UI working in [here](https://github.com/holochain-open-dev/profiles/blob/main/ui/demo/index.html).
+

docs/3.2-profiles-store.mdx

@@ -0,0 +1,58 @@
+import { Meta } from '@storybook/addon-docs';
+import { ArgsTable } from '@storybook/addon-docs/blocks';
+import {ProfilesStore} from '@holochain-open-dev/profiles'
+
+<Meta title="Frontend/ProfilesStore" 
+  parameters={{ previewTabs: { canvas: { hidden: true } } }}
+/>
+
+# ProfilesStore
+
+The `ProfilesStore` is a typescript class that contains `svelte` stores, to which you can subscribe to get reactive updates in your elements.
+
+```js
+import { ProfilesStore, ProfilesClient } from "@holochain-open-dev/profiles";
+
+const config = {
+  avatarMode: "identicon",
+
+  // Custom app level profile fields
+  additionalFields: [
+    {
+      name: "location",
+      label: "Location",
+      required: true, 
+    },
+    {
+      name: "bio",
+      label: "Bio",
+      required: false,
+    }
+  ], 
+};
+const store = new ProfilesStore(new ProfilesClient(appAgentClient, 'my-role-name'), config);
+```
+
+> Learn how to setup the `AppAgentClient` object [here](https://www.npmjs.com/package/@holochain/client).
+
+The config for the `ProfilesStore` has these options:
+
+```ts
+export interface ProfilesConfig {
+  avatarMode: "identicon" | "avatar-required" | "avatar-optional"; // default: 'avatar-optional'
+  additionalFields: FieldConfig[]; // default: []
+  minNicknameLength: number; // default: 3
+}
+```
+
+The `FieldConfig` has these options:
+
+```ts
+export interface FieldConfig {
+  name: string,
+  label: string,
+  required: boolean,
+}
+```
+
+Learn more about the stores and how to integrate them in different frameworks [here](https://holochain-open-dev.github.io/reusable-modules/frontend/using/#stores).