improve plugin exports (#135)

Author: JannikStreek

docs/client-packages-react.md

@@ -10,7 +10,9 @@ Ensure the GitHub package registry is configured (see [Registry Setup](./client-
 pnpm add @edufeed-org/oer-finder-plugin-react
 ```
 
-This package depends on `@edufeed-org/oer-finder-plugin` internally — you do not need to install the base plugin separately.
+The base plugin (`@edufeed-org/oer-finder-plugin`) is installed automatically as a dependency — you do not need to install it separately. All necessary imports (components, types, and adapter registration) are available directly from this React package.
+
+> **Important:** Do not install `@edufeed-org/oer-finder-plugin` as a direct dependency alongside the React package. Doing so can result in two separate copies on disk, each with its own adapter registry. Adapters registered via one copy would be invisible to components from the other, causing searches to silently return zero results. Always import from `@edufeed-org/oer-finder-plugin-react` instead.
 
 ## Operating Modes
 
@@ -48,15 +50,14 @@ You **must register adapters** before the component renders. Call the registrati
 
 ```typescript
 // Register all built-in adapters
-import { registerAllBuiltInAdapters } from '@edufeed-org/oer-finder-plugin/adapters';
+import { registerAllBuiltInAdapters } from '@edufeed-org/oer-finder-plugin-react/adapters';
 registerAllBuiltInAdapters();
 ```
 
-Or register only the adapters you need to reduce bundle size:
+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';
+import { registerOpenverseAdapter, registerArasaacAdapter } from '@edufeed-org/oer-finder-plugin-react/adapters';
 registerOpenverseAdapter();
 registerArasaacAdapter();
 ```
@@ -93,9 +94,11 @@ import {
 
 // Configure available sources (checked: true sets the pre-selected sources)
 const SOURCES: SourceConfig[] = [
-  { id: 'nostr', label: 'Nostr', checked: true },
+  { 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' },
 ];
 
 function OerFinder() {
@@ -183,8 +186,7 @@ The component code is identical to the [server-proxy example above](#server-prox
 **1. Register adapters once at your app entry point (e.g., `main.tsx`):**
 
 ```tsx
-import { registerOpenverseAdapter } from '@edufeed-org/oer-finder-plugin/adapter/openverse';
-import { registerArasaacAdapter } from '@edufeed-org/oer-finder-plugin/adapter/arasaac';
+import { registerOpenverseAdapter, registerArasaacAdapter } from '@edufeed-org/oer-finder-plugin-react/adapters';
 registerOpenverseAdapter();
 registerArasaacAdapter();
 ```
@@ -289,6 +291,31 @@ 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 — all functions are available from a single import path:
+
+```typescript
+// All adapters
+import { registerAllBuiltInAdapters } from '@edufeed-org/oer-finder-plugin-react/adapters';
+registerAllBuiltInAdapters();
+
+// Or selectively
+import { registerOpenverseAdapter, registerWikimediaAdapter } from '@edufeed-org/oer-finder-plugin-react/adapters';
+registerOpenverseAdapter();
+registerWikimediaAdapter();
+```
+
 ## Key Types
 
 All types are importable from `@edufeed-org/oer-finder-plugin-react`:
@@ -309,13 +336,26 @@ import {
 
   // 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
+
+  // Adapter types
+  type AdapterFactory,         // Factory function type for custom adapters
+
+  // 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
 
-  // API client types (re-exported from oer-finder-api-client)
-  type OerMetadata,
-  type OerListResponse,
+  // Adapter registry API
+  registerAdapter,             // Register a custom adapter factory
+  getAdapterFactory,           // Retrieve a registered adapter factory by ID
 } from '@edufeed-org/oer-finder-plugin-react';
 ```
 

docs/creating-a-new-adapter.md

@@ -187,10 +187,14 @@ export function register<Name>Adapter(): void {
 }
 ```
 
-**f)** Import and call the new function in `packages/oer-finder-plugin/src/built-in-registrations.ts`:
+**f)** Import, export, and call the new function in `packages/oer-finder-plugin/src/built-in-registrations.ts`:
 ```typescript
 import { register<Name>Adapter } from './adapter/<name>.js';
-// ... inside registerAllBuiltInAdapters():
+
+// Add to the named exports block (this is how the React package picks it up automatically):
+export { register<Name>Adapter };
+
+// Add inside registerAllBuiltInAdapters():
 register<Name>Adapter();
 ```
 
@@ -209,32 +213,36 @@ register<Name>Adapter();
 
 **i)** Add to source configs in `packages/oer-finder-plugin-example/src/main.ts`.
 
+**j)** Add to source configs in `packages/oer-finder-plugin-react-example/src/App.tsx`.
+
+> **Note:** The React package (`oer-finder-plugin-react`) automatically re-exports all adapter registration functions from the base plugin via `export * from '@edufeed-org/oer-finder-plugin/adapters'`. No changes to the React package are needed — new adapters are picked up automatically once added to the base plugin's `built-in-registrations.ts`.
+
 #### Docker
 
-**j)** Add a COPY line in the `Dockerfile` (in the `production` stage):
+**k)** Add a COPY line in the `Dockerfile` (in the `production` stage):
 ```dockerfile
 COPY --chown=node:node packages/oer-adapter-<name> $APP_PATH/packages/oer-adapter-<name>/
 ```
 
 #### CI/CD Workflows (all three required)
 
-**k)** `.github/workflows/ci.yml` — `oer-adapters` job: add a test step:
+**l)** `.github/workflows/ci.yml` — `oer-adapters` job: add a test step:
 ```yaml
 - name: Test adapter <name>
   run: pnpm --filter @edufeed-org/oer-adapter-<name> run test
 ```
 
-**l)** `.github/workflows/ci.yml` — `oer-finder-plugin` job: add a build step inside "Build dependencies":
+**m)** `.github/workflows/ci.yml` — `oer-finder-plugin` job: add a build step inside "Build dependencies":
 ```yaml
 pnpm --filter @edufeed-org/oer-adapter-<name> run build
 ```
 
-**m)** `.github/workflows/release.yml` — `publish-npm-packages` job: add a build step inside "Build dependencies":
+**n)** `.github/workflows/release.yml` — `publish-npm-packages` job: add a build step inside "Build dependencies":
 ```yaml
 pnpm --filter @edufeed-org/oer-adapter-<name> run build
 ```
 
-> **Warning:** Forgetting the release workflow step (m) will cause the release build to fail with `[commonjs--resolver] Failed to resolve entry for package`. The plugin bundles all adapters — if yours isn't built before the plugin build runs, Vite cannot resolve it.
+> **Warning:** Forgetting the release workflow step (n) will cause the release build to fail with `[commonjs--resolver] Failed to resolve entry for package`. The plugin bundles all adapters — if yours isn't built before the plugin build runs, Vite cannot resolve it.
 
 ### 6. Export Your Public API
 
@@ -304,6 +312,7 @@ readonly capabilities: AdapterCapabilities = {
 - [ ] Entry point in `packages/oer-finder-plugin/vite.config.ts`
 - [ ] Sub-path export in `packages/oer-finder-plugin/package.json`
 - [ ] Source config in `packages/oer-finder-plugin-example/src/main.ts`
+- [ ] Source config in `packages/oer-finder-plugin-react-example/src/App.tsx`
 - [ ] COPY line in `Dockerfile`
 - [ ] Test step in `.github/workflows/ci.yml` (`oer-adapters` job)
 - [ ] Build step in `.github/workflows/ci.yml` (`oer-finder-plugin` job)

packages/oer-finder-plugin-react-example/package.json

@@ -18,7 +18,6 @@
     "format": "echo 'Format not configured yet'"
   },
   "dependencies": {
-    "@edufeed-org/oer-finder-plugin": "workspace:*",
     "@edufeed-org/oer-finder-plugin-react": "workspace:*",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"

packages/oer-finder-plugin-react-example/src/App.tsx

@@ -30,13 +30,15 @@ const SERVER_SOURCES: SourceConfig[] = [
   { id: 'openverse', label: 'Openverse' },
   { id: 'arasaac', label: 'ARASAAC' },
   { id: 'rpi-virtuell', label: 'RPI-Virtuell' },
+  { id: 'wikimedia', label: 'Wikimedia Commons' },
 ];
 
 const DIRECT_SOURCES: SourceConfig[] = [
   { id: 'openverse', label: 'Openverse', checked: true },
   { id: 'arasaac', label: 'ARASAAC', checked: true },
   { id: 'nostr-amb-relay', label: 'Nostr AMB Relay', baseUrl: 'wss://amb-relay.edufeed.org' },
   { id: 'rpi-virtuell', label: 'RPI-Virtuell' },
+  { id: 'wikimedia', label: 'Wikimedia Commons' },
 ];
 
 interface SearchDemoProps {

packages/oer-finder-plugin-react/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edufeed-org/oer-finder-plugin-react",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "React components for OER Finder Plugin",
   "author": "B310 Digital GmbH",
   "license": "MIT",

packages/oer-finder-plugin-react/src/adapters.ts

@@ -1 +1 @@
-export { registerAllBuiltInAdapters } from '@edufeed-org/oer-finder-plugin/adapters';
+export * from '@edufeed-org/oer-finder-plugin/adapters';

packages/oer-finder-plugin-react/src/index.ts

@@ -74,7 +74,7 @@ export {
  *   }}
  * >
  *   <OerList oers={oers} loading={loading} onCardClick={(e) => handleCardClick(e.detail.oer)} />
- *   <OerLoadMore metadata={metadata} loading={loading} shownCount={oers.length} />
+ *   <OerLoadMore metadata={metadata} loading={loading} />
  * </OerSearch>
  * ```
  */
@@ -150,7 +150,6 @@ export const OerCard = createComponent({
  * ```tsx
  * <OerLoadMore
  *   metadata={metadata}
- *   shownCount={oers.length}
  *   loading={isLoading}
  *   language="en"
  * />

packages/oer-finder-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edufeed-org/oer-finder-plugin",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Web Components plugin for OER Proxy",
   "author": "B310 Digital GmbH",
   "license": "MIT",

packages/oer-finder-plugin/src/built-in-registrations.ts

@@ -4,6 +4,14 @@ import { registerNostrAmbRelayAdapter } from './adapter/nostr-amb-relay.js';
 import { registerRpiVirtuellAdapter } from './adapter/rpi-virtuell.js';
 import { registerWikimediaAdapter } from './adapter/wikimedia.js';
 
+export {
+  registerOpenverseAdapter,
+  registerArasaacAdapter,
+  registerNostrAmbRelayAdapter,
+  registerRpiVirtuellAdapter,
+  registerWikimediaAdapter,
+};
+
 /**
  * Register all built-in adapter factories.
  * Convenience helper for consumers who want all adapters.