feat: Create random demo, personas in groups, BDD no webServer, docs

Author: devalbo

AGENTS.md

@@ -7,7 +7,7 @@ Context for AI assistants working on this repo.
 **tb-solid-pod** is a browser-based personal data pod inspired by the [Solid Project](https://solidproject.org/), built with [TinyBase](https://tinybase.org/) for reactive state and LocalStorage. It is **not** a real Solid server (no LDP, no WebID-TLS); it simulates Solid-style data (personas, contacts, groups, type indexes, file metadata) in a single-page app.
 
 - **Dual interface**: graphical UI (tabs, forms, lists) + CLI terminal.
-- **Data**: personas (WebID-style), contacts (including agents), groups (org/team/group), type indexes, virtual file system with metadata, settings/preferences.
+- **Data**: personas (WebID-style), contacts (including agents), groups (org/team/group) with membership of contacts and your personas, type indexes, virtual file system with metadata, settings/preferences.
 - **Stack**: React, TinyBase, Zod, Vite, TypeScript. Vocabularies: FOAF, vCard, Dublin Core, W3C Org, `@inrupt/vocab-*`.
 
 ## Repo layout
@@ -21,7 +21,7 @@ Context for AI assistants working on this repo.
 | `src/utils/` | settings, storeExport, typeIndex helpers, validation. |
 | `src/cli/` | CliTerminal, command registry, parse-args, types. |
 | `src/components/` | PersonaList/Form, ContactList/Form, GroupList/Form, MembershipManager, FileMetadataPanel. |
-| `docs/` | CODING_GUIDELINES.md, DESIGN.md, IMPLEMENTATION_PLAN.md, testing/. |
+| `docs/` | CODING_GUIDELINES.md, DESIGN.md, IMPLEMENTATION_PLAN.md, TEST_PLAN.md, testing/. |
 
 ## What’s done so far
 
@@ -70,7 +70,9 @@ When someone wants to use this in an app they’re working on, point them to the
 
 ## Useful docs
 
-- **README.md** – Overview, limitations, Use as a library (Zod + JSON Schema), Integration Guide (copy-paste vs install-from-GitHub), Getting Started (Node note, Live demo + 404 troubleshooting), CLI command list.  
+- **README.md** – Overview, limitations, Use as a library (Zod + JSON Schema), Integration Guide (copy-paste vs install-from-GitHub), Getting Started (Node note, Live demo + 404 troubleshooting), Testing (unit, BDD, Storybook link), CLI command list.  
 - **docs/CODING_GUIDELINES.md** – TypeScript (strict types, no sloppy types), short functions, simple React components, naming, file length.  
 - **docs/IMPLEMENTATION_PLAN.md** – Feature/phases.  
+- **docs/TEST_PLAN.md** – Test phases and verification.  
+- **docs/testing/** – Unit (unit-tests.md), BDD/E2E (bdd-tests.md), Storybook (storybook.md); BDD does not start the dev server (start it manually).  
 - **DESIGN.md** – Design notes.

README.md

@@ -25,7 +25,7 @@ This library provides a complete foundation for **user-owned social data** in we
 ### Groups & Organizations
 - Three group types: Organizations, Teams, and informal Groups
 - W3C Organization Ontology (org:) vocabulary
-- Membership management with contact linking
+- Membership management: add contacts and your own personas to groups
 - Group metadata: name, description, URL, logo
 
 ### File Storage with Metadata
@@ -47,7 +47,7 @@ This library provides a complete foundation for **user-owned social data** in we
 - Persona schema includes optional `solid:publicTypeIndex` and `solid:privateTypeIndex` links
 
 ### Dual Interface
-- **Graphical UI**: Tab-based navigation with forms and lists
+- **Graphical UI**: Tab-based navigation with forms and lists. Personas, Contacts, and Groups tabs each have a **Create random** button that opens the form with sample data for quick try-out.
 - **CLI Terminal**: Full command-line interface for power users
 
 ## Benefits for Social Applications
@@ -441,13 +441,14 @@ clear                         Clear terminal
 ## Testing
 
 - **Unit tests (Vitest):** `npm test` or `npm run test:run`; coverage: `npm run test:coverage`
+- **Storybook:** `npm run storybook` → http://localhost:6006 (component development). See [docs/testing/](docs/testing/README.md).
 - **BDD / E2E (Playwright):** Generate specs from Gherkin, then run Playwright:
   ```bash
   npx bddgen && npx playwright test
   ```
   Or use the scripts: `npm run test:e2e` or `npm run test:bdd` (same thing). With browser visible: `npm run test:e2e:headed`.
 
-  **Start the server manually (recommended if E2E hangs):** In one terminal start the app; in another run the tests. Playwright will reuse the existing server on port 5173 (`reuseExistingServer` when not in CI).
+  **Start the server first (required):** The BDD/E2E command does not start the dev server. In one terminal start the app; in another run the tests.
   1. **Terminal 1:** `npm run dev` — leave it running (app at http://localhost:5173).
   2. **Terminal 2:** `npx bddgen && npx playwright test` (or `npm run test:e2e`).
 

docs/TEST_PLAN.md

@@ -107,7 +107,7 @@
 - @playwright/test, playwright-bdd; `npx playwright install` (chromium)
 
 ### Configuration
-- `playwright.config.ts` — Playwright config with defineBddConfig, webServer (port 5173), baseURL
+- `playwright.config.ts` — Playwright config with defineBddConfig, baseURL; no webServer (start dev server manually)
 
 ### Feature Files and Steps
 - `tests/features/*.feature` — app, cli-contacts, cli-personas, cli-navigation, contacts, personas

docs/testing/bdd-tests.md

@@ -24,19 +24,19 @@ To inspect the latest run: open the HTML report, or look at `test-results/.last-
 
 ## Layout
 
-- **Config:** `playwright.config.ts` (defineBddConfig, baseURL, webServer)
+- **Config:** `playwright.config.ts` (defineBddConfig, baseURL; no webServer — start the app yourself)
 - **Features:** `tests/features/*.feature` (Gherkin)
 - **Steps:** `tests/features/steps/*.ts` (Given/When/Then)
 - **Generated specs:** `.features-gen/` (output of `npx bddgen`)
 
-## Running with the app already up
+## Starting the app (required)
 
-If E2E hangs when Playwright starts the dev server, run the app yourself and reuse it:
+The BDD/E2E command does **not** start the dev server. Start the app first, then run the tests:
 
 1. **Terminal 1:** `npm run dev` (leave running; app at http://localhost:5173).
 2. **Terminal 2:** `npx bddgen && npx playwright test`.
 
-Playwright will reuse the server on 5173 when not in CI. For a different port, set `E2E_BASE_URL` (e.g. `E2E_BASE_URL=http://localhost:3000 npx playwright test`).
+For a different port, set `E2E_BASE_URL` (e.g. `E2E_BASE_URL=http://localhost:3000 npx playwright test`).
 
 ## Manual BDD steps
 

playwright.config.ts

@@ -24,10 +24,5 @@ export default defineConfig({
   projects: [
     { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
   ],
-  webServer: {
-    command: 'npm run dev',
-    url: process.env.E2E_BASE_URL || 'http://localhost:5173',
-    reuseExistingServer: !process.env.CI,
-    timeout: 60_000,
-  },
+  // No webServer: start the dev server yourself (e.g. npm run dev) before running BDD/E2E tests.
 });

src/App.tsx

@@ -62,6 +62,73 @@ const getDefaultContent = (): [Record<string, Record<string, Record<string, unkn
   {}
 ];
 
+// ==========================================
+// RANDOM DEMO DATA (for "Add random" buttons)
+// ==========================================
+function pick<T>(arr: readonly T[]): T {
+  return arr[Math.floor(Math.random() * arr.length)];
+}
+
+function getRandomPersonaFormValues(): Record<string, string> {
+  const first = pick(['Alex', 'Sam', 'Jordan', 'Casey', 'Riley', 'Morgan', 'Quinn', 'Avery']);
+  const last = pick(['Smith', 'Chen', 'Williams', 'Brown', 'Lee', 'Jones', 'Garcia']);
+  const name = `${first} ${last}`;
+  const nick = pick([first.toLowerCase(), `${first}${last.slice(0, 1)}`.toLowerCase(), `${first}_${last}`.toLowerCase()]);
+  return {
+    name,
+    nickname: nick,
+    givenName: first,
+    familyName: last,
+    email: `${nick}@example.com`,
+    phone: `+1-555-${Math.floor(100 + Math.random() * 900)}-${Math.floor(1000 + Math.random() * 9000)}`,
+    bio: pick(['Developer and designer.', 'Works on the Solid ecosystem.', 'Building for the decentralized web.']),
+    homepage: `https://${nick}.example.com`,
+    image: '',
+    oidcIssuer: '',
+    inbox: '',
+    preferencesFile: '',
+    publicTypeIndex: '',
+    privateTypeIndex: '',
+  };
+}
+
+function getRandomContactFormValues(): Record<string, string | boolean> {
+  const first = pick(['Jamie', 'Taylor', 'Robin', 'Drew', 'Skyler', 'Parker']);
+  const last = pick(['Miller', 'Davis', 'Wilson', 'Martinez', 'Anderson']);
+  const name = `${first} ${last}`;
+  const nick = first.toLowerCase();
+  const isAgent = Math.random() > 0.7;
+  return {
+    name,
+    nickname: nick,
+    email: `${nick}@company.com`,
+    phone: `+1-555-${Math.floor(200 + Math.random() * 800)}-${Math.floor(1000 + Math.random() * 9000)}`,
+    url: `https://${nick}.company.com`,
+    photo: '',
+    notes: pick(['Met at conference.', 'Collaborator on project X.', '']),
+    organization: pick(['Acme Inc', 'Tech Corp', 'Solid Labs', '']),
+    role: pick(['Engineer', 'Designer', 'PM', '']),
+    webId: '',
+    isAgent,
+    agentCategory: isAgent ? pick(['DeveloperApplication', 'SocialNetworking', 'Utilities']) : '',
+  };
+}
+
+type GroupType = 'group' | 'organization' | 'team';
+function getRandomGroupFormValues(): Record<string, string> {
+  const adj = pick(['Core', 'Product', 'Platform', 'Research', 'Community']);
+  const noun = pick(['Team', 'Squad', 'Group', 'Org', 'Circle']);
+  const name = `${adj} ${noun}`;
+  const type: GroupType = pick(['group', 'organization', 'team']);
+  return {
+    name,
+    type,
+    description: pick([`The ${name} works on key initiatives.`, `Internal ${type}.`, '']),
+    url: `https://${name.toLowerCase().replace(/\s+/g, '-')}.company.com`,
+    logo: '',
+  };
+}
+
 // ==========================================
 // MIME & IMAGE HELPERS
 // ==========================================
@@ -450,12 +517,15 @@ export default function App() {
   const [selectedPersonaId, setSelectedPersonaId] = useState<string | undefined>();
   const [personaFormOpen, setPersonaFormOpen] = useState(false);
   const [editingPersonaId, setEditingPersonaId] = useState<string | undefined>();
+  const [personaFormInitial, setPersonaFormInitial] = useState<Record<string, string> | undefined>();
   const [selectedContactId, setSelectedContactId] = useState<string | undefined>();
   const [contactFormOpen, setContactFormOpen] = useState(false);
   const [editingContactId, setEditingContactId] = useState<string | undefined>();
+  const [contactFormInitial, setContactFormInitial] = useState<Record<string, string | boolean> | undefined>();
   const [selectedGroupId, setSelectedGroupId] = useState<string | undefined>();
   const [groupFormOpen, setGroupFormOpen] = useState(false);
   const [editingGroupId, setEditingGroupId] = useState<string | undefined>();
+  const [groupFormInitial, setGroupFormInitial] = useState<Record<string, string> | undefined>();
   const [managingMembersGroupId, setManagingMembersGroupId] = useState<string | undefined>();
 
   const row = useRow('resources', currentUrl, store ?? undefined) as ResourceRow | undefined;
@@ -734,6 +804,12 @@ export default function App() {
               }}
               onCreate={() => {
                 setEditingPersonaId(undefined);
+                setPersonaFormInitial(undefined);
+                setPersonaFormOpen(true);
+              }}
+              onCreateRandom={() => {
+                setEditingPersonaId(undefined);
+                setPersonaFormInitial(getRandomPersonaFormValues());
                 setPersonaFormOpen(true);
               }}
             />
@@ -742,13 +818,16 @@ export default function App() {
                 store={store}
                 baseUrl={BASE_URL}
                 personaId={editingPersonaId}
+                initialValues={personaFormInitial}
                 onSave={() => {
                   setPersonaFormOpen(false);
                   setEditingPersonaId(undefined);
+                  setPersonaFormInitial(undefined);
                 }}
                 onCancel={() => {
                   setPersonaFormOpen(false);
                   setEditingPersonaId(undefined);
+                  setPersonaFormInitial(undefined);
                 }}
               />
             )}
@@ -774,6 +853,12 @@ export default function App() {
               }}
               onCreate={() => {
                 setEditingContactId(undefined);
+                setContactFormInitial(undefined);
+                setContactFormOpen(true);
+              }}
+              onCreateRandom={() => {
+                setEditingContactId(undefined);
+                setContactFormInitial(getRandomContactFormValues());
                 setContactFormOpen(true);
               }}
             />
@@ -782,13 +867,16 @@ export default function App() {
                 store={store}
                 baseUrl={BASE_URL}
                 contactId={editingContactId}
+                initialValues={contactFormInitial}
                 onSave={() => {
                   setContactFormOpen(false);
                   setEditingContactId(undefined);
+                  setContactFormInitial(undefined);
                 }}
                 onCancel={() => {
                   setContactFormOpen(false);
                   setEditingContactId(undefined);
+                  setContactFormInitial(undefined);
                 }}
               />
             )}
@@ -817,6 +905,12 @@ export default function App() {
               }}
               onCreate={() => {
                 setEditingGroupId(undefined);
+                setGroupFormInitial(undefined);
+                setGroupFormOpen(true);
+              }}
+              onCreateRandom={() => {
+                setEditingGroupId(undefined);
+                setGroupFormInitial(getRandomGroupFormValues());
                 setGroupFormOpen(true);
               }}
             />
@@ -825,13 +919,16 @@ export default function App() {
                 store={store}
                 baseUrl={BASE_URL}
                 groupId={editingGroupId}
+                initialValues={groupFormInitial}
                 onSave={() => {
                   setGroupFormOpen(false);
                   setEditingGroupId(undefined);
+                  setGroupFormInitial(undefined);
                 }}
                 onCancel={() => {
                   setGroupFormOpen(false);
                   setEditingGroupId(undefined);
+                  setGroupFormInitial(undefined);
                 }}
               />
             )}

src/components/ContactForm.tsx

@@ -15,6 +15,8 @@ interface ContactFormProps {
   store: Store;
   baseUrl: string;
   contactId?: string; // If provided, we're editing; otherwise creating
+  /** Pre-fill form when creating (e.g. "Add random" demo). */
+  initialValues?: Partial<FormData>;
   onSave: () => void;
   onCancel: () => void;
 }
@@ -53,16 +55,19 @@ const ContactForm: React.FC<ContactFormProps> = ({
   store,
   baseUrl,
   contactId,
+  initialValues,
   onSave,
   onCancel,
 }) => {
   const isEditing = !!contactId;
   const [form, setForm] = useState<FormData>(emptyForm);
   const [error, setError] = useState<string | null>(null);
+  const appliedInitialRef = React.useRef(false);
 
   // Load existing contact data when editing
   useEffect(() => {
     if (contactId) {
+      appliedInitialRef.current = false;
       const record = store.getRow(TABLE_NAME, contactId) as Record<string, unknown>;
       if (record) {
         const email = record[VCARD.hasEmail] as string | undefined;
@@ -90,6 +95,15 @@ const ContactForm: React.FC<ContactFormProps> = ({
     }
   }, [contactId, store]);
 
+  // Pre-fill form when creating with initialValues (e.g. "Add random" demo)
+  useEffect(() => {
+    if (!contactId && initialValues && !appliedInitialRef.current) {
+      setForm((prev) => ({ ...emptyForm, ...prev, ...initialValues }));
+      appliedInitialRef.current = true;
+    }
+    if (contactId) appliedInitialRef.current = false;
+  }, [contactId, initialValues]);
+
   const handleChange = (field: keyof FormData) => (
     e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>
   ) => {

src/components/ContactList.tsx

@@ -11,6 +11,8 @@ interface ContactListProps {
   onEdit: (id: string) => void;
   onDelete: (id: string) => void;
   onCreate: () => void;
+  /** Open create form with random demo values pre-filled. */
+  onCreateRandom?: () => void;
   selectedId?: string;
 }
 
@@ -28,6 +30,7 @@ const ContactList: React.FC<ContactListProps> = ({
   onEdit,
   onDelete,
   onCreate,
+  onCreateRandom,
   selectedId,
 }) => {
   const contacts = useTable(TABLE_NAME, store) as Record<string, Record<string, unknown>>;
@@ -66,9 +69,16 @@ const ContactList: React.FC<ContactListProps> = ({
     <div style={styles.container}>
       <div style={styles.header}>
         <h3 style={styles.title}>Contacts</h3>
-        <button style={styles.createBtn} onClick={onCreate}>
-          + Add Contact
-        </button>
+        <div style={styles.headerActions}>
+          {onCreateRandom && (
+            <button style={styles.randomBtn} onClick={onCreateRandom} title="Open form with random demo values">
+              Create random
+            </button>
+          )}
+          <button style={styles.createBtn} onClick={onCreate}>
+            + Add Contact
+          </button>
+        </div>
       </div>
 
       <div style={styles.toolbar}>
@@ -197,6 +207,21 @@ const styles: Record<string, CSSProperties> = {
     background: '#fafafa',
     borderBottom: '1px solid #eee',
   },
+  headerActions: {
+    display: 'flex',
+    gap: 8,
+    alignItems: 'center',
+  },
+  randomBtn: {
+    padding: '8px 14px',
+    background: '#fff',
+    color: '#555',
+    border: '1px solid #ccc',
+    borderRadius: 6,
+    cursor: 'pointer',
+    fontWeight: 500,
+    fontSize: 13,
+  },
   title: {
     margin: 0,
     fontSize: 16,