embed-dlsurf-blogs 1.0.2 → 1.0.4

package/README.md

@@ -1,53 +1,19 @@
 # `embed-dlsurf-blogs`
 
-Render dlsurf blog posts with a single React component.
+Embed DL Surf blog content into any React app — a full blog listing page **and** individual post viewer, all in two components.
 
-## Quick Start
-
-You do not need to fetch API data manually first.
-
-Pass either:
-
-- `blogUrl`, or
-- `user` + `linkSlug`
+---
 
-The component fetches from:
+## Components
 
-`https://docapi.dl.surf/api/doc/{user}/{linkSlug}`
+| Component      | Purpose                                                         |
+| -------------- | --------------------------------------------------------------- |
+| `UserHomePage` | Shows a creator's **featured hero** + **recent articles** grid. |
+| `BlogRenderer` | Renders a **single blog post** (Tiptap JSON → HTML).            |
 
-internally.
+They are designed to work together: `UserHomePage` links each article card to a post page (default `/blog/{linkSlug}`), and you host `BlogRenderer` on that route to display the full post. The link path is fully customisable via `basePath` or `getPostUrl`.
 
-## API Response Shape (for reference)
-
-The upstream doc API returns:
-
-```json
-{
-  "status": "success",
-  "message": "Document retrieved successfully",
-  "data": {
-    "id": 1345,
-    "title": "6 Years of dlsurf, 300000+ Users & Counting",
-    "content_json": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"text\":\"Happy New Year 2026 🥳\",\"type\":\"text\"}]},{\"type\":\"paragraph\",\"content\":[{\"text\":\"It has been an incredible journey of building dlsurf...\",\"type\":\"text\"}]}, ...]}",
-    "thumbnail_path": "media/default_thumbnail/thumbnail_b2.png",
-    "keywords": "[]",
-    "followers_only": false,
-    "visibility": "public",
-    "created_at": "2026-01-01T08:02:57.253021Z",
-    "link_slug": "happy-new-year-6-years-of-building-dlsurf-300000-users-and-counting",
-    "updated_at": "2026-01-01T10:16:04.803993Z",
-    "profile": {
-      "username": "arjun",
-      "display_name": "Arjun Ghimire",
-      "account_level": "6",
-      "profile_picture": "/media/profile_picture/efd953bb1b.jpeg"
-    },
-    "ads_step": 0,
-    "banner_ads": false,
-    "video_ads": false
-  }
-}
-```
+---
 
 ## Pre-requirements
 
@@ -73,84 +39,209 @@ or
 pnpm add embed-dlsurf-blogs @tiptap/core
 ```
 
-## Usage Patterns
+---
+
+## Quick Start
+
+### Theme color (`themeColor` prop)
+
+Both components accept a `themeColor` prop to control accent/highlight UI color.
+
+- Default: `#2d66f5`
+- Accepts any valid CSS color value (hex, rgb, hsl, named color, etc.)
+
+```tsx
+import { UserHomePage, BlogRenderer } from "embed-dlsurf-blogs";
+
+// Listing page accents (dots, hovers, CTA, themed shadows)
+<UserHomePage username="rishav" themeColor="#0ea5e9" />;
+
+// Single post accents (top progress bar, badge, themed shadows)
+<BlogRenderer user="rishav" linkSlug="my-post" themeColor="#0ea5e9" />;
+```
+
+If you omit `themeColor`, both components use `#2d66f5`.
+
+### 1. Add the blog listing page — `UserHomePage`
 
-### 1. Simplest: pass `blogUrl`
+Drop `<UserHomePage>` on the page where you want the blog listing to appear. Pass the DL Surf **username** of the creator whose posts you want to display.
 
 ```tsx
-import BlogRenderer from "embed-dlsurf-blogs";
+import { UserHomePage } from "embed-dlsurf-blogs";
 
-export default function Page() {
-  return (
-    <BlogRenderer blogUrl="https://docapi.dl.surf/api/doc/rishav/why-django-is-a-game-changer-in-modern-web-development" />
-  );
+export default function BlogIndex() {
+  return <UserHomePage username="rishav" />;
 }
 ```
 
-You can also pass a non-API URL as long as the last two path segments are `{user}/{linkSlug}`.
+That's it — the component fetches the creator's featured + latest posts and renders them in a responsive card grid.
+
+#### Props
+
+| Prop         | Type                       | Default        | Description                                         |
+| ------------ | -------------------------- | -------------- | --------------------------------------------------- |
+| `username`   | `string`                   | **(required)** | DL Surf username (with or without a leading `@`).   |
+| `limit`      | `number`                   | `6`            | Maximum number of recent articles to show.          |
+| `basePath`   | `string`                   | `"/blog"`      | Base path prepended to every post slug.             |
+| `getPostUrl` | `(slug: string) => string` | —              | Custom URL builder. Takes priority over `basePath`. |
+| `themeColor` | `string`                   | `"#2d66f5"`    | Accent color used for interactive/highlight states. |
+
+#### What happens when a user clicks an article?
+
+Every card links to **`{basePath}/{linkSlug}`** (default: `/blog/why-django-is-a-game-changer`). You need to set up a page at that route in your app and render `<BlogRenderer>` there — see below.
+
+#### Customising the post URL
+
+By default all links point to `/blog/{slug}`. If your app uses a different route structure, pass `basePath` or `getPostUrl`:
+
+```tsx
+// Simple — change the base path
+<UserHomePage username="rishav" basePath="/articles" />
+// → links become /articles/my-post-slug
+
+// Full control — build any URL you want
+<UserHomePage
+  username="rishav"
+  getPostUrl={(slug) => `/rishav/posts/${slug}`}
+/>
+// → links become /rishav/posts/my-post-slug
+
+// Change the accent/theme color (default is #2d66f5)
+<UserHomePage username="rishav" themeColor="#0ea5e9" />
+```
+
+Just make sure the page at that URL renders `<BlogRenderer>` with the matching slug.
+
+---
 
-### 2. Pass `user` + `linkSlug`
+### 2. Add the single-post page — `BlogRenderer`
+
+Create a page that matches the `/blog/{linkSlug}` route and render `<BlogRenderer>`, passing the **username** and the **slug** from the URL.
+
+#### Next.js (App Router) example
 
 ```tsx
+// app/blog/[slug]/page.tsx
 import { BlogRenderer } from "embed-dlsurf-blogs";
 
-export default function Page() {
-  return (
-    <BlogRenderer
-      user="rishav"
-      linkSlug="why-django-is-a-game-changer-in-modern-web-development"
-    />
-  );
+export default function BlogPost({ params }: { params: { slug: string } }) {
+  return <BlogRenderer user="rishav" linkSlug={params.slug} />;
 }
 ```
 
-### 3. Advanced: override API base URL
+#### React Router example
 
 ```tsx
-import BlogRenderer from "embed-dlsurf-blogs";
-
-export default function Page() {
-  return (
-    <BlogRenderer
-      user="rishav"
-      linkSlug="why-django-is-a-game-changer-in-modern-web-development"
-      apiBaseUrl="https://docapi.dl.surf/api/doc"
-    />
-  );
+// src/pages/BlogPost.tsx
+import { useParams } from "react-router-dom";
+import { BlogRenderer } from "embed-dlsurf-blogs";
+
+export default function BlogPost() {
+  const { slug } = useParams<{ slug: string }>();
+  return <BlogRenderer user="rishav" linkSlug={slug!} />;
 }
 ```
 
-## Component Props
+> **Tip:** You can also pass a full `blogUrl` instead of `user` + `linkSlug` — as long as the last two path segments are `{user}/{linkSlug}`.
+
+#### Props
+
+| Prop         | Type       | Description                                                          |
+| ------------ | ---------- | -------------------------------------------------------------------- |
+| `post`       | `BlogPost` | Pre-fetched post object — skips the internal fetch.                  |
+| `user`       | `string`   | DL Surf username.                                                    |
+| `linkSlug`   | `string`   | URL-friendly slug that identifies the post.                          |
+| `blogUrl`    | `string`   | Full blog URL (user + slug are parsed from the path).                |
+| `themeColor` | `string`   | Accent color used for progress/highlight states (`#2d66f5` default). |
+
+Provide **one** of:
+
+- `post` (pre-fetched data), **or**
+- `user` + `linkSlug`, **or**
+- `blogUrl`
+
+---
+
+### Putting it all together
 
-```ts
-type BlogRendererProps = {
-  user?: string;
-  linkSlug?: string;
-  blogUrl?: string;
-  apiBaseUrl?: string;
-};
 ```
+Your app  (using default basePath="/blog")
+├── /blog          → <UserHomePage username="rishav" />
+│                     ↳ each card links to /blog/{linkSlug}
+│
+└── /blog/:slug    → <BlogRenderer user="rishav" linkSlug={slug} />
+                      ↳ renders the full post
+```
+
+Or with a custom base path:
 
-Notes:
+```
+Your app  (basePath="/articles")
+├── /articles      → <UserHomePage username="rishav" basePath="/articles" />
+│                     ↳ each card links to /articles/{linkSlug}
+│
+└── /articles/:slug → <BlogRenderer user="rishav" linkSlug={slug} />
+```
 
-- Use `blogUrl` or `user` + `linkSlug`.
-- If required fetch fields are missing, the component shows an inline error message.
+---
+
+## API Response Shape (for reference)
+
+The upstream doc API returns:
+
+```json
+{
+  "status": "success",
+  "message": "Document retrieved successfully",
+  "data": {
+    "id": 1345,
+    "title": "6 Years of dlsurf, 300000+ Users & Counting",
+    "content_json": "{\"type\":\"doc\",\"content\":[...]}",
+    "thumbnail_path": "media/default_thumbnail/thumbnail_b2.png",
+    "keywords": "[]",
+    "followers_only": false,
+    "visibility": "public",
+    "created_at": "2026-01-01T08:02:57.253021Z",
+    "link_slug": "happy-new-year-6-years-of-building-dlsurf-300000-users-and-counting",
+    "updated_at": "2026-01-01T10:16:04.803993Z",
+    "profile": {
+      "username": "arjun",
+      "display_name": "Arjun Ghimire",
+      "account_level": "6",
+      "profile_picture": "/media/profile_picture/efd953bb1b.jpeg"
+    },
+    "ads_step": 0,
+    "banner_ads": false,
+    "video_ads": false
+  }
+}
+```
 
 ## Exported API
 
-- Default export: `BlogRenderer`
-- Named export: `BlogRenderer`
-- Utility: `renderText`
+| Export         | Type                   |
+| -------------- | ---------------------- |
+| `BlogRenderer` | Named + default export |
+| `UserHomePage` | Named export           |
 
 ## Internal Behavior
 
-The component:
+Both components:
+
+- Fetch post data internally (no manual API calls needed).
+- Use scoped CSS class names to avoid style collisions.
+- Render Tiptap JSON via an SSR-safe HTML renderer.
+
+`BlogRenderer` additionally:
 
-- Fetches post data internally when needed.
-- Parses `content_json` via SSR-safe renderer.
 - Strips outer `prose` wrappers.
-- Generates a Table of Contents from `h2`/`h3`.
-- Injects scoped styles at build time.
+- Generates a collapsible Table of Contents from `h2`/`h3` headings.
+- Shows a reading-progress bar and social-share buttons.
+
+`UserHomePage` additionally:
+
+- Responds to its own container width (CSS container queries) — works in sidebars, panels, or full-width layouts.
+- Auto-rotates through featured posts every 4 seconds.
 
 ## License
 

package/dist/index.d.mts

@@ -1,18 +1,27 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 export { JSONContent } from '@tiptap/core';
 
+/** Props accepted by the <BlogRenderer> component. */
 interface BlogRendererProps {
+    /** Pre-fetched post object – if provided the component skips its own fetch. */
     post?: BlogPost;
+    /** DL Surf username (with or without leading "@"). */
     user?: string;
+    /** URL-friendly slug that identifies the post. */
     linkSlug?: string;
+    /** Full blog URL from which user + slug can be parsed. */
     blogUrl?: string;
+    /** Main accent color used for progress + highlighted UI states. */
+    themeColor?: string;
 }
+/** Author profile embedded in a BlogPost. */
 interface BlogPostProfile {
     username: string;
     display_name: string;
     account_level: string;
     profile_picture: string;
 }
+/** Full blog-post payload as returned by the DL Surf API. */
 interface BlogPost {
     id: number;
     title: string;
@@ -29,8 +38,42 @@ interface BlogPost {
     banner_ads: boolean;
     video_ads: boolean;
 }
-declare function BlogRenderer({ post, user, linkSlug, blogUrl, }: BlogRendererProps): react_jsx_runtime.JSX.Element;
+/**
+ * Renders a single DL Surf blog post with:
+ *  - A top reading-progress bar
+ *  - Post header (title, date, reading time)
+ *  - Thumbnail hero image
+ *  - Collapsible table of contents (auto-generated from h2/h3)
+ *  - Rendered Tiptap HTML body
+ *  - Social share buttons
+ *
+ * The post can be supplied directly via `post`, resolved from
+ * `user` + `linkSlug`, or parsed from a full `blogUrl`.
+ */
+declare function BlogRenderer({ post, user, linkSlug, blogUrl, themeColor, }: BlogRendererProps): react_jsx_runtime.JSX.Element;
 
-declare function renderText(): string;
+/** Props accepted by the <UserHomePage> component. */
+interface BlogListClientProps {
+    /** DL Surf username (with or without leading "@"). */
+    username: string;
+    /** Max number of latest posts to display (default 6). */
+    limit?: number;
+    /** Base path prepended to every post slug (default "/blog"). */
+    basePath?: string;
+    /**
+     * Custom URL builder — receives the post slug and returns the full href.
+     * When provided this takes priority over `basePath`.
+     *
+     * @example getPostUrl={(slug) => `/articles/${slug}`}
+     */
+    getPostUrl?: (slug: string) => string;
+    /** Main accent color used for interactive/highlighted UI states. */
+    themeColor?: string;
+}
+/**
+ * Renders a creator's blog home page with an auto-rotating featured
+ * hero section and a grid of recent article cards.
+ */
+declare function UserHomePage({ username, limit, basePath, getPostUrl, themeColor, }: BlogListClientProps): react_jsx_runtime.JSX.Element;
 
-export { BlogRenderer, BlogRenderer as default, renderText };
+export { BlogRenderer, UserHomePage };

package/dist/index.d.ts

@@ -1,18 +1,27 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 export { JSONContent } from '@tiptap/core';
 
+/** Props accepted by the <BlogRenderer> component. */
 interface BlogRendererProps {
+    /** Pre-fetched post object – if provided the component skips its own fetch. */
     post?: BlogPost;
+    /** DL Surf username (with or without leading "@"). */
     user?: string;
+    /** URL-friendly slug that identifies the post. */
     linkSlug?: string;
+    /** Full blog URL from which user + slug can be parsed. */
     blogUrl?: string;
+    /** Main accent color used for progress + highlighted UI states. */
+    themeColor?: string;
 }
+/** Author profile embedded in a BlogPost. */
 interface BlogPostProfile {
     username: string;
     display_name: string;
     account_level: string;
     profile_picture: string;
 }
+/** Full blog-post payload as returned by the DL Surf API. */
 interface BlogPost {
     id: number;
     title: string;
@@ -29,8 +38,42 @@ interface BlogPost {
     banner_ads: boolean;
     video_ads: boolean;
 }
-declare function BlogRenderer({ post, user, linkSlug, blogUrl, }: BlogRendererProps): react_jsx_runtime.JSX.Element;
+/**
+ * Renders a single DL Surf blog post with:
+ *  - A top reading-progress bar
+ *  - Post header (title, date, reading time)
+ *  - Thumbnail hero image
+ *  - Collapsible table of contents (auto-generated from h2/h3)
+ *  - Rendered Tiptap HTML body
+ *  - Social share buttons
+ *
+ * The post can be supplied directly via `post`, resolved from
+ * `user` + `linkSlug`, or parsed from a full `blogUrl`.
+ */
+declare function BlogRenderer({ post, user, linkSlug, blogUrl, themeColor, }: BlogRendererProps): react_jsx_runtime.JSX.Element;
 
-declare function renderText(): string;
+/** Props accepted by the <UserHomePage> component. */
+interface BlogListClientProps {
+    /** DL Surf username (with or without leading "@"). */
+    username: string;
+    /** Max number of latest posts to display (default 6). */
+    limit?: number;
+    /** Base path prepended to every post slug (default "/blog"). */
+    basePath?: string;
+    /**
+     * Custom URL builder — receives the post slug and returns the full href.
+     * When provided this takes priority over `basePath`.
+     *
+     * @example getPostUrl={(slug) => `/articles/${slug}`}
+     */
+    getPostUrl?: (slug: string) => string;
+    /** Main accent color used for interactive/highlighted UI states. */
+    themeColor?: string;
+}
+/**
+ * Renders a creator's blog home page with an auto-rotating featured
+ * hero section and a grid of recent article cards.
+ */
+declare function UserHomePage({ username, limit, basePath, getPostUrl, themeColor, }: BlogListClientProps): react_jsx_runtime.JSX.Element;
 
-export { BlogRenderer, BlogRenderer as default, renderText };
+export { BlogRenderer, UserHomePage };