@feedlog-ai/react 0.0.44 → 0.0.46

package/BUILD_FEEDLOG_CLIENT.md

@@ -0,0 +1,50 @@
+# Build with the top-level client (`@feedlog-ai/react`)
+
+Use **`FeedlogIssuesClient`** when you want props + events and the component performs fetching internally.
+
+## When to use
+
+- Standard client-rendered apps, or a client boundary in Next.js / RSC setups
+- You do not need the initial HTML to already contain the issues array (for full SSR of issues data, see [BUILD_FEEDLOG_COMPOSABLE.md](./BUILD_FEEDLOG_COMPOSABLE.md))
+
+## Install
+
+```bash
+npm install @feedlog-ai/react @feedlog-ai/core
+```
+
+(`@feedlog-ai/core` is often pulled in as a dependency; install explicitly if your tooling requires it.)
+
+## Minimal example
+
+```tsx
+'use client';
+
+import { FeedlogIssuesClient } from '@feedlog-ai/react';
+
+export function Changelog() {
+  return (
+    <FeedlogIssuesClient
+      apiKey="your-api-key"
+      type="bug"
+      limit={10}
+      theme="light"
+      maxWidth="42rem"
+      onFeedlogUpvote={event => {
+        console.log('Issue upvoted:', event.detail);
+      }}
+      onFeedlogError={event => {
+        console.error('Error:', event.detail);
+      }}
+    />
+  );
+}
+```
+
+In the **Next.js App Router**, any file that imports `@feedlog-ai/react` for interactive components should be a **Client Component** (`'use client'`), as described in [README](./README.md#nextjs-app-router-or-pages-router).
+
+## See also
+
+- [README](./README.md) — SSR (`withFeedlogSSR`, `feedlogSSR`), TanStack Start, limitations
+- [Build Your Own Feedlog hub](../../docs/BUILD_YOUR_OWN_FEEDLOG.md)
+- [Customize Feedlog styling](../../docs/CUSTOMIZE_FEEDLOG_STYLING.md)

package/BUILD_FEEDLOG_COMPOSABLE.md

@@ -0,0 +1,85 @@
+# Composable changelog (`@feedlog-ai/react` + `@feedlog-ai/core`)
+
+Use **`FeedlogSDK.fetchIssues`** where your app resolves the API key (server, loader, or client), then render **`FeedlogIssues`** with an **`issues`** prop. You handle **`onFeedlogUpvote`** with **`sdk.toggleUpvote`**.
+
+## When to use
+
+- **Full SSR** of the issues list (props resolved at request time, no empty flash from client-only fetch inside the widget)
+- **Dynamic props** that Stencil’s static SSR analysis cannot serialize (see [README](./README.md#ssr-limitations))
+
+## When not to use imports
+
+Do **not** import `FeedlogIssues` from `@feedlog-ai/react/ssr-components` or `@feedlog-ai/react/next` for the issues list. Use the main package: `@feedlog-ai/react`.
+
+## Install
+
+```bash
+npm install @feedlog-ai/react @feedlog-ai/core
+```
+
+## Server-rendered page (Next.js App Router)
+
+```tsx
+// app/changelog/page.tsx
+import { FeedlogIssues } from '@feedlog-ai/react';
+import { FeedlogSDK } from '@feedlog-ai/core';
+
+export default async function ChangelogPage() {
+  const sdk = new FeedlogSDK({ apiKey: process.env.FEEDLOG_API_KEY! });
+  const { issues } = await sdk.fetchIssues({ limit: 10 });
+  return <FeedlogIssues issues={issues} theme="light" maxWidth="42rem" />;
+}
+```
+
+## Client upvote handling
+
+Upvotes need a browser and your SDK instance (or an API route). Typical pattern: a **client component** wraps `FeedlogIssues`, keeps `issues` in state initialized from server props, and on `onFeedlogUpvote` calls `toggleUpvote` then updates state or re-fetches.
+
+```tsx
+'use client';
+
+import { useState, useMemo } from 'react';
+import { FeedlogIssues } from '@feedlog-ai/react';
+import { FeedlogSDK, type FeedlogIssue } from '@feedlog-ai/core';
+
+export function ChangelogInteractive({ initialIssues }: { initialIssues: FeedlogIssue[] }) {
+  const [issues, setIssues] = useState(initialIssues);
+  const sdk = useMemo(
+    () => new FeedlogSDK({ apiKey: process.env.NEXT_PUBLIC_FEEDLOG_API_KEY! }),
+    []
+  );
+
+  return (
+    <FeedlogIssues
+      issues={issues}
+      theme="light"
+      onFeedlogUpvote={async event => {
+        const { issueId } = event.detail;
+        await sdk.toggleUpvote(issueId);
+        const { issues: next } = await sdk.fetchIssues({ limit: 10 });
+        setIssues(next);
+      }}
+    />
+  );
+}
+```
+
+Adjust API key handling for your framework (env, server actions, etc.).
+
+## Finer composition
+
+You can also use:
+
+- **`FeedlogIssuesList`** — list without outer chrome (see package exports)
+- **`FeedlogIssueComponent`** — single card; pass `issue={...}`
+
+## Other frameworks
+
+- **Pages Router / `getServerSideProps`:** Fetch in the data hook, pass `issues` into `FeedlogIssues` on the page.
+- **Remix / Vite loaders:** Fetch in the loader, pass `issues` as props.
+
+## See also
+
+- [@feedlog-ai/core README](../core/README.md)
+- [README](./README.md) — SSR plugins and troubleshooting
+- [Build Your Own Feedlog hub](../../docs/BUILD_YOUR_OWN_FEEDLOG.md)

package/README.md

@@ -158,9 +158,11 @@ The compiler-based SSR (used by Vite, Remix, and Next.js with `feedlogSSR` / `wi
 
 This is a [documented limitation](https://stenciljs.com/docs/server-side-rendering) of Stencil's compiler approach ("Static props only").
 
-### Build Your Own Feedlog (Full SSR)
+### Build your own changelog
 
-For full SSR of the issues list (no flash of empty content), build a custom wrapper that fetches on the server and passes data to `FeedlogIssues`. See [Build Your Own Feedlog](../../docs/BUILD_YOUR_OWN_FEEDLOG.md) for copy-paste instructions for AI assistants and code generators.
+- [Build Your Own Feedlog (hub)](../../docs/BUILD_YOUR_OWN_FEEDLOG.md) — three tiers (client, composable, core-only) and AI copy-paste blocks
+- [Top-level client](./BUILD_FEEDLOG_CLIENT.md) — `FeedlogIssuesClient`
+- [Composable + your data](./BUILD_FEEDLOG_COMPOSABLE.md) — `FeedlogSDK` + `FeedlogIssues` (full SSR, loaders)
 
 ### Event Handling
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feedlog-ai/react",
-  "version": "0.0.44",
+  "version": "0.0.46",
   "description": "React bindings for Feedlog Toolkit Web Components",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -33,7 +33,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "BUILD_FEEDLOG_CLIENT.md",
+    "BUILD_FEEDLOG_COMPOSABLE.md"
   ],
   "sideEffects": false,
   "scripts": {
@@ -55,7 +57,7 @@
     }
   },
   "dependencies": {
-    "@feedlog-ai/webcomponents": "^0.0.44"
+    "@feedlog-ai/webcomponents": "^0.0.46"
   },
   "devDependencies": {
     "@jest/test-sequencer": "^29.7.0",