update packages guides (#137)

Author: JannikStreek

README.md

@@ -3,7 +3,7 @@
 <p align="center">
   <img src="./docs/images/oer-finder-plugin-logo.png" width=250 />
 </p>
-An Open Educational Resources (OER) discovery system built on Nostr and built on [AMB](https://dini-ag-kim.github.io/amb/draft/), providing:
+An Open Educational Resources (OER) discovery system built on Nostr and built on [AMB](https://dini-ag-kim.github.io/amb/latest/), providing:
 
 1. **Proxy Service**: Forwards search queries to configurable source adapters and returns unified OER results via a public API. Supports searching an AMB Nostr relay, Openverse, ARASAAC, RPI-Virtuell, and more through an **extendable adapter system** - add your own adapters to integrate any external API.
 2. **Source Adapters**: Pluggable adapters for OER sources (e.g., AMB relay, ARASAAC, Openverse) that integrate seamlessly with search results. The adapter plugin system makes it easy to add new sources.

docs/client-packages-angular.md

@@ -1,6 +1,6 @@
 # Using OER Finder Plugin in Angular
 
-This guide covers Angular-specific integration. For component properties and events, see [Client Packages](./client-packages.md).
+This guide covers Angular-specific integration. For component properties, events, available adapters, key types, and operating modes, see [Client Packages](./client-packages.md).
 
 ## Installation
 
@@ -14,7 +14,23 @@ For additional installation details (pnpm overrides, etc.), see [Client Packages
 
 ## Angular Configuration
 
-Angular requires `CUSTOM_ELEMENTS_SCHEMA` to recognize web component tags:
+Angular requires `CUSTOM_ELEMENTS_SCHEMA` to recognize web component tags.
+
+**Standalone component (Angular 14+, recommended):**
+
+```typescript
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+
+@Component({
+  selector: 'app-oer-finder',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  templateUrl: './oer-finder.component.html',
+})
+export class OerFinderComponent { /* ... */ }
+```
+
+**NgModule-based component:**
 
 ```typescript
 import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
@@ -26,9 +42,9 @@ import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
 export class OerFinderModule {}
 ```
 
-## Basic Usage
+## Basic Usage (Server-Proxy Mode)
 
-The recommended pattern is to slot `<oer-list>` and `<oer-load-more>` inside `<oer-search>`.
+The recommended pattern is to slot `<oer-list>` and `<oer-load-more>` inside `<oer-search>`. Use `@ViewChild` with `ElementRef` to access the underlying web component elements. For the full list of component properties and events, see [Component Properties](./client-packages.md#component-properties).
 
 ### Component
 
@@ -51,11 +67,13 @@ export class OerFinderComponent implements AfterViewInit {
   @ViewChild('listElement') listElement!: ElementRef;
   @ViewChild('loadMoreElement') loadMoreElement!: ElementRef;
 
-  // Configure available sources
+  // Configure available sources (checked: true sets the pre-selected sources)
   sources: SourceConfig[] = [
-    { id: 'nostr-amb-relay', label: 'AMB Relay' },
+    { id: 'nostr-amb-relay', label: 'Nostr AMB Relay', checked: true },
     { id: 'openverse', label: 'Openverse' },
     { id: 'arasaac', label: 'ARASAAC' },
+    { id: 'rpi-virtuell', label: 'RPI-Virtuell' },
+    { id: 'wikimedia', label: 'Wikimedia Commons' },
   ];
 
   ngAfterViewInit(): void {
@@ -67,6 +85,13 @@ export class OerFinderComponent implements AfterViewInit {
   // Note: load-more events bubble up and are automatically
   // caught by oer-search to fetch the next page of results.
 
+  onSearchLoading(): void {
+    const listEl = this.listElement.nativeElement;
+    const loadMoreEl = this.loadMoreElement.nativeElement;
+    listEl.loading = true;
+    loadMoreEl.loading = true;
+  }
+
   onSearchResults(event: Event): void {
     const { data, meta } = (event as OerSearchResultEvent).detail;
     const listEl = this.listElement.nativeElement;
@@ -100,59 +125,83 @@ export class OerFinderComponent implements AfterViewInit {
 
   onCardClick(event: Event): void {
     const { oer } = (event as OerCardClickEvent).detail;
-    // Handle card click
+    const url = oer.amb?.id;
+    if (url) {
+      window.open(String(url), '_blank', 'noopener,noreferrer');
+    }
   }
 }
 ```
 
 ### Template
 
+Angular uses `(event-name)="handler($event)"` syntax for web component events:
+
 ```html
 <oer-search
   #searchElement
   api-url="https://your-api-url.com"
-  language="de"
+  language="en"
   page-size="20"
+  (search-loading)="onSearchLoading()"
   (search-results)="onSearchResults($event)"
   (search-error)="onSearchError($event)"
   (search-cleared)="onSearchCleared()"
 >
   <oer-list
     #listElement
-    language="de"
+    language="en"
     (card-click)="onCardClick($event)"
   ></oer-list>
   <oer-load-more
     #loadMoreElement
-    language="de"
+    language="en"
   ></oer-load-more>
 </oer-search>
 ```
 
-## Configuring Sources
+## Direct Client Mode Example
 
-Sources are configured using the `SourceConfig` type and must be set as a JS property (not an HTML attribute).
-Set the `sources` property in `ngAfterViewInit` as shown in the example above.
+The component code is identical to the [server-proxy example above](#basic-usage-server-proxy-mode) with two differences: adapters must be registered at startup, and the `api-url` attribute is omitted. For adapter details, see [Available Adapters](./client-packages.md#available-adapters).
+
+**1. Register adapters once at your app entry point (e.g., `main.ts`):**
 
 ```typescript
-import type { SourceConfig } from '@edufeed-org/oer-finder-plugin';
+import { registerAllBuiltInAdapters } from '@edufeed-org/oer-finder-plugin/adapters';
+registerAllBuiltInAdapters();
+```
 
-// Server-proxy mode sources (with api-url set)
-// Use checked: true to set the pre-selected sources
-const serverSources: SourceConfig[] = [
-  { id: 'nostr-amb-relay', label: 'AMB Relay', checked: true },
-  { id: 'openverse', label: 'Openverse' },
-  { id: 'arasaac', label: 'ARASAAC' },
-];
+**2. Provide `baseUrl` in the source config where required:**
 
-// Direct client mode sources (without api-url)
-const directSources: SourceConfig[] = [
-  { id: 'openverse', label: 'Openverse' },
-  { id: 'arasaac', label: 'ARASAAC', checked: true },
+```typescript
+sources: SourceConfig[] = [
+  { id: 'openverse', label: 'Openverse', checked: true },
+  { id: 'arasaac', label: 'ARASAAC' },
+  { id: 'wikimedia', label: 'Wikimedia Commons' },
   { id: 'nostr-amb-relay', label: 'Nostr AMB Relay', baseUrl: 'wss://amb-relay.edufeed.org' },
+  { id: 'rpi-virtuell', label: 'RPI-Virtuell' },
 ];
 ```
 
+**3. Remove `api-url` from the template:**
+
+```html
+<oer-search
+  #searchElement
+  language="en"
+  page-size="20"
+  (search-loading)="onSearchLoading()"
+  (search-results)="onSearchResults($event)"
+  (search-error)="onSearchError($event)"
+  (search-cleared)="onSearchCleared()"
+>
+  <oer-list #listElement language="en" (card-click)="onCardClick($event)"></oer-list>
+  <oer-load-more #loadMoreElement language="en"></oer-load-more>
+</oer-search>
+```
+
+All event handlers and component logic remain the same.
+
 ## Example
 
 See the [TeamMapper integration PR](https://github.com/b310-digital/teammapper/pull/1081) for a real-world Angular example.

docs/client-packages-react.md

@@ -14,63 +14,10 @@ The base plugin is a peer dependency of the React package. Both packages must be
 
 ## Operating Modes
 
-The plugin supports two operating modes, determined by whether the `apiUrl` prop is provided:
+The plugin supports **server-proxy mode** (with `apiUrl` prop) and **direct client mode** (without `apiUrl`). For full details on each mode, adapter registration, and available adapters, see [Client Packages — Routing Modes](./client-packages.md#routing-modes) and [Available Adapters](./client-packages.md#available-adapters).
 
-### Server-Proxy Mode (with `apiUrl`)
-
-When `apiUrl` is set, all search requests are routed through your backend proxy. The server handles adapter logic, so **no adapter code is bundled into your client application**.
-
-**Use this mode when:**
-- You have a deployed OER Proxy backend
-- You want to keep client bundle size small
-- You need server-side features like image proxying, rate limiting, or signed URLs
-
-```tsx
-<OerSearch
-  apiUrl="https://your-api-url.com"
-  sources={SOURCES}
-  // ...event handlers
->
-```
-
-No adapter registration is needed — just provide the `apiUrl` and configure your sources.
-
-### Direct Client Mode (without `apiUrl`)
-
-When `apiUrl` is **omitted**, adapters run directly in the browser. No backend server is required.
-
-**Use this mode when:**
-- You want a serverless setup with no backend dependency
-- You are prototyping or building a static site
-- You want full client-side control over adapter behavior
-
-You **must register adapters** before the component renders. Call the registration function once at your app's entry point. Import adapter registration functions directly from `@edufeed-org/oer-finder-plugin`:
-
-```typescript
-// Register all built-in adapters
-import { registerAllBuiltInAdapters } from '@edufeed-org/oer-finder-plugin/adapters';
-registerAllBuiltInAdapters();
-```
-
-Or register only the adapters you need:
-
-```typescript
-import { registerOpenverseAdapter } from '@edufeed-org/oer-finder-plugin/adapter/openverse';
-import { registerArasaacAdapter } from '@edufeed-org/oer-finder-plugin/adapter/arasaac';
-registerOpenverseAdapter();
-registerArasaacAdapter();
-```
-
-Then render `OerSearch` without `apiUrl`:
-
-```tsx
-<OerSearch
-  sources={SOURCES}
-  // ...event handlers (no apiUrl prop)
->
-```
-
-Only registered adapters will be available — unregistered source IDs in the `sources` config are silently skipped.
+- **Server-proxy mode**: Set `apiUrl` — no adapter registration needed, no adapter code in your bundle.
+- **Direct client mode**: Omit `apiUrl` — register adapters at your app's entry point before the component renders. Import adapter registration functions from `@edufeed-org/oer-finder-plugin`.
 
 ## Basic Usage
 
@@ -291,75 +238,35 @@ If you render `OerLoadMore` outside of `OerSearch`, the event will not bubble to
 |------|-------------------|-------------|
 | `onLoadMore` | `(event: CustomEvent<void>) => void` | Fired when the "Load more" button is clicked. When slotted inside `OerSearch`, this event bubbles up automatically to trigger the next page fetch — no manual handler needed. |
 
-## Available Adapters
-
-The following built-in adapters are available for direct client mode:
-
-| Adapter ID | Source | Notes |
-|------------|--------|-------|
-| `openverse` | Openverse (Flickr, Wikimedia, etc.) | Images, license filter |
-| `arasaac` | ARASAAC pictograms API | Images only |
-| `nostr-amb-relay` | Nostr AMB relay (WebSocket) | Requires `baseUrl` with WebSocket URL(s) in `SourceConfig` |
-| `rpi-virtuell` | RPI-Virtuell Materialpool (GraphQL) | German educational resources |
-| `wikimedia` | Wikimedia Commons API | Images |
-
-Register all at once or selectively — import adapter registration functions from `@edufeed-org/oer-finder-plugin`:
-
-```typescript
-// All adapters
-import { registerAllBuiltInAdapters } from '@edufeed-org/oer-finder-plugin/adapters';
-registerAllBuiltInAdapters();
-
-// Or selectively (better for tree-shaking)
-import { registerOpenverseAdapter } from '@edufeed-org/oer-finder-plugin/adapter/openverse';
-import { registerWikimediaAdapter } from '@edufeed-org/oer-finder-plugin/adapter/wikimedia';
-registerOpenverseAdapter();
-registerWikimediaAdapter();
-```
-
 ## Key Types
 
-React components and UI-related types are importable from `@edufeed-org/oer-finder-plugin-react`:
+The React package (`@edufeed-org/oer-finder-plugin-react`) re-exports all shared types from the base plugin, so you can import everything from a single package. For the full list of shared types, see [Key Types](./client-packages.md#key-types).
 
 ```typescript
 import {
-  // Components
+  // React wrapper components
   OerSearch,
   OerList,
   OerCard,
   OerLoadMore,
 
-  // Event types
-  type OerSearchResultEvent,   // CustomEvent<{ data: OerItem[], meta: LoadMoreMeta }>
-  type OerSearchResultDetail,  // { data: OerItem[], meta: LoadMoreMeta }
-  type OerCardClickEvent,      // CustomEvent<{ oer: OerItem }>
-  type OerCardClickDetail,     // { oer: OerItem }
-
-  // Data types
-  type OerItem,                // Normalized AMB metadata for a single resource
-  type OerMetadata,            // Metadata structure on OerItem
-  type OerListResponse,        // Full list response shape from the API
-  type LoadMoreMeta,           // { total: number, shown: number, hasMore: boolean }
-  type SourceConfig,           // { id: string, label: string, baseUrl?: string, checked?: boolean }
-  type SupportedLanguage,      // 'en' | 'de'
-  type SearchParams,           // Search parameter structure
-  type SourceOption,           // Source option type for UI display
-
-  // Underlying web component types (for advanced use)
-  type OerSearchElement,       // <oer-search> element class
-  type OerListElement,         // <oer-list> element class
-  type OerCardElement,         // <oer-card> element class
-  type LoadMoreElement,        // <oer-load-more> element class
+  // All shared types are re-exported (OerItem, SourceConfig, event types, etc.)
+  type OerSearchResultEvent,
+  type OerCardClickEvent,
+  type OerItem,
+  type LoadMoreMeta,
+  type SourceConfig,
+  // ... see Client Packages — Key Types for the complete list
 } from '@edufeed-org/oer-finder-plugin-react';
 ```
 
-Adapter registry API and adapter types are imported from `@edufeed-org/oer-finder-plugin`:
+Adapter registry API and adapter registration functions are imported from `@edufeed-org/oer-finder-plugin`:
 
 ```typescript
 import {
-  registerAdapter,             // Register a custom adapter factory
-  getAdapterFactory,           // Retrieve a registered adapter factory by ID
-  type AdapterFactory,         // Factory function type for custom adapters
+  registerAdapter,
+  getAdapterFactory,
+  type AdapterFactory,
 } from '@edufeed-org/oer-finder-plugin';
 ```