Merge pull request #63 from raid-guild/feat/widget-summaries

Feat/widget summaries

Author: dekanbro

.github/ISSUE_TEMPLATE/module-spec.yml

@@ -59,6 +59,32 @@ body:
     validations:
       required: true
 
+  - type: dropdown
+    id: summary_layout
+    attributes:
+      label: Summary layout
+      description: "How should the module summary render in cards?"
+      options:
+        - list
+        - excerpt
+        - compact
+        - widget
+        - none
+    validations:
+      required: true
+
+  - type: dropdown
+    id: summary_widget_mode
+    attributes:
+      label: Summary widget mode (if widget)
+      description: "If Summary layout is widget, choose data (portal-rendered) or embed (iframe)."
+      options:
+        - not-applicable
+        - data
+        - embed
+    validations:
+      required: true
+
   - type: dropdown
     id: storage
     attributes:

README.md

@@ -111,6 +111,8 @@ Behavior notes:
   - `compact`: small stats/data tile
   - `default`: standard stackable module card
   - `wide`: full-width module card
+- Summary cards can also render dynamic widgets via `summary.layout: "widget"` and
+  `summary.widget` (data-rendered or embedded iframe).
 
 ## Supabase
 - Migrations and seeds live in `supabase/`

docs/module-authoring.md

@@ -198,12 +198,80 @@ The summary endpoint should return:
 
 ### Summary presentation options
 Optional fields for summary layout:
-- `layout`: `list` (default), `excerpt`, or `compact`
+- `layout`: `list` (default), `excerpt`, `compact`, or `widget`
 - `maxItems`: limit the number of items shown
 - `truncate`: max character length for values or excerpts
 - `showTitle`: boolean to show/hide the summary title
 - `progressKey`: render a progress bar for the matching item label
 - `imageKey`: render a circular thumbnail for the matching item label (compact layout)
+- `widget`: configuration for dynamic summary widgets when `layout` is `widget`
+
+### Summary widget primitive
+Use `layout: "widget"` when a summary card should render dynamic content.
+
+Supported widget modes:
+- `mode: "data"`: endpoint returns generic `widget.data`; portal renders a supported widget component.
+- `mode: "embed"`: portal renders an iframe from `widget.src` (use for third-party mini apps).
+
+Widget config shape:
+```json
+{
+  "summary": {
+    "source": "api",
+    "endpoint": "/api/modules/example/summary",
+    "layout": "widget",
+    "widget": {
+      "mode": "data",
+      "type": "chart",
+      "variant": "force-graph",
+      "height": 220
+    }
+  }
+}
+```
+
+Endpoint response shape (with fallback):
+```json
+{
+  "title": "Example Summary",
+  "items": [
+    { "label": "People", "value": "42" }
+  ],
+  "widget": {
+    "mode": "data",
+    "type": "chart",
+    "variant": "force-graph",
+    "data": {
+      "nodes": [{ "id": "skill:Solidity", "label": "Solidity", "group": "skill" }],
+      "links": []
+    }
+  }
+}
+```
+
+Notes:
+- Always include `items` as a fallback for clients/surfaces that cannot render the widget.
+- For third-party widgets, prefer `mode: "embed"` with explicit origins and auth constraints.
+
+Example: third-party embedded widget summary
+```json
+{
+  "allowedOrigins": ["https://widgets.example.com"],
+  "summaryBySurface": {
+    "home": {
+      "source": "api",
+      "title": "Module Snapshot",
+      "endpoint": "/api/modules/example/summary",
+      "layout": "widget",
+      "widget": {
+        "mode": "embed",
+        "src": "https://widgets.example.com/summary?module=example",
+        "height": 220
+      }
+    }
+  }
+}
+```
 
 Example with excerpt:
 ```json

modules/README.md

@@ -23,5 +23,14 @@ Control module card size in surface grids via `presentation.layout`:
 
 If omitted, the portal currently treats layout as `default`.
 
+## Dynamic Summary Widgets
+Summary cards can render richer dynamic content by using:
+- `summary.layout: "widget"`
+- `summary.widget.mode: "data"` (portal-rendered widget data), or
+- `summary.widget.mode: "embed"` (iframe widget URL).
+
+Include summary `items` as fallback content for clients/surfaces that cannot render the
+widget.
+
 ## Host-only Modules
 Add the `hosts` tag to hide a module from non-hosts. Roles are managed in `public.user_roles`.

modules/registry.json

@@ -404,7 +404,8 @@
       },
       "requiresAuth": true,
       "tags": [
-        "me-tools"
+        "me-tools",
+        "member-tools"
       ],
       "url": "/modules/dao-membership",
       "presentation": {
@@ -468,7 +469,6 @@
       },
       "requiresAuth": true,
       "tags": [
-        "start-here",
         "hosts",
         "host-tools"
       ],
@@ -559,17 +559,20 @@
       "presentation": {
         "mode": "page",
         "trigger": "button",
-        "layout": "default"
-      },
-      "access": {
-        "requiresAuth": true,
-        "entitlement": "cohort-access"
+        "layout": "wide"
       },
       "summaryBySurface": {
         "home": {
           "source": "api",
           "title": "Cohort Skills",
-          "endpoint": "/api/modules/skills-explorer/summary"
+          "endpoint": "/api/modules/skills-explorer/summary/widget",
+          "layout": "widget",
+          "widget": {
+            "mode": "data",
+            "type": "chart",
+            "variant": "force-graph",
+            "height": 220
+          }
         },
         "people": {
           "source": "api",
@@ -738,7 +741,7 @@
       },
       "requiresAuth": true,
       "tags": [
-        "start-here",
+        "people-tools",
         "me-tools",
         "profile-tools-public"
       ],
@@ -771,6 +774,7 @@
       },
       "requiresAuth": true,
       "tags": [
+        "start-here",
         "people-tools"
       ],
       "presentation": {
@@ -801,6 +805,7 @@
       },
       "requiresAuth": false,
       "tags": [
+        "start-here",
         "people-tools"
       ],
       "presentation": {
@@ -896,6 +901,59 @@
         "showTitle": true
       }
     },
+    {
+      "id": "dao-handbook",
+      "title": "DAO Handbook",
+      "description": "Open DAO docs, policies, and contributor guidance in one place.",
+      "lane": "cohort",
+      "type": "link",
+      "url": "https://rg-handbook-nextra.vercel.app/",
+      "status": "live",
+      "owner": {
+        "name": "@dekanbro",
+        "contact": "@dekanbro"
+      },
+      "requiresAuth": true,
+      "access": {
+        "requiresAuth": true,
+        "entitlement": "dao-member"
+      },
+      "tags": [
+        "member-tools"
+      ],
+      "presentation": {
+        "mode": "dialog",
+        "trigger": "button",
+        "dialog": {
+          "size": "lg"
+        },
+        "iframe": {
+          "height": 820
+        },
+        "layout": "default"
+      },
+      "summary": {
+        "source": "static",
+        "title": "DAO Handbook",
+        "items": [
+          {
+            "label": "Governance docs",
+            "value": "Browse rules, voting norms, and governance references."
+          },
+          {
+            "label": "Operations guides",
+            "value": "Find practical workflows for running DAO work."
+          },
+          {
+            "label": "Contributor context",
+            "value": "Review expectations and orientation material."
+          }
+        ],
+        "layout": "list",
+        "maxItems": 3,
+        "showTitle": true
+      }
+    },
     {
       "id": "module-requests",
       "title": "Module Requests",

src/app/api/modules/skills-explorer/summary/route.ts

@@ -1,6 +1,51 @@
+import { supabaseAdminClient } from "@/lib/supabase/admin";
 import { loadPeople } from "@/lib/people";
+import { supabaseServerClient } from "@/lib/supabase/server";
 
-export async function GET() {
+type ViewTier = "public" | "authenticated" | "dao-member";
+
+async function resolveTier(request: Request): Promise<ViewTier> {
+  const authHeader = request.headers.get("authorization");
+  if (!authHeader?.startsWith("Bearer ")) {
+    return "public";
+  }
+
+  const token = authHeader.replace("Bearer ", "");
+  let userId: string;
+  try {
+    const supabase = supabaseServerClient();
+    const { data: userData, error: userError } = await supabase.auth.getUser(token);
+    if (userError || !userData.user) {
+      return "public";
+    }
+    userId = userData.user.id;
+  } catch {
+    return "public";
+  }
+
+  try {
+    const admin = supabaseAdminClient();
+    const now = new Date().toISOString();
+    const { data, error } = await admin
+      .from("entitlements")
+      .select("entitlement")
+      .eq("user_id", userId)
+      .eq("status", "active")
+      .or(`expires_at.is.null,expires_at.gt.${now}`);
+
+    if (error || !data) {
+      return "authenticated";
+    }
+
+    const entitlements = new Set(data.map((row) => row.entitlement));
+    return entitlements.has("dao-member") ? "dao-member" : "authenticated";
+  } catch {
+    return "authenticated";
+  }
+}
+
+export async function GET(request: Request) {
+  const tier = await resolveTier(request);
   const people = await loadPeople();
   const allSkills = people.flatMap((person) => person.skills ?? []);
   const uniqueSkills = new Set(allSkills);
@@ -14,12 +59,20 @@ export async function GET() {
     .sort((a, b) => b[1] - a[1])
     .at(0);
 
+  const visibility =
+    tier === "dao-member"
+      ? "DAO detail"
+      : tier === "authenticated"
+        ? "Authenticated aggregate"
+        : "Public aggregate";
+
   return Response.json({
     title: "Cohort Skills",
     items: [
       { label: "People", value: String(people.length) },
       { label: "Unique skills", value: String(uniqueSkills.size) },
       { label: "Top skill", value: top ? `${top[0]}` : "TBD" },
+      { label: "View", value: visibility },
     ],
   });
 }