@k34a/blog 0.0.7 → 0.0.8

package/README.md

@@ -1,236 +1,413 @@
-# @k34a/forms
+# @k34a/blog
 
-**Dynamic Form Builder & Handler for Next.js and Supabase**  
-Easily create, render, and manage dynamic forms directly from your admin panel.  
-Supports form validation, user-friendly UI (powered by Mantine), and built-in submission handling.
+**A complete Articles/Blog Engine for Next.js + Supabase**
+Easily fetch, search, filter, render, and display articles inside your application.
+Includes backend utilities, frontend UI components, filtering, pagination, and SEO-ready article rendering out of the box.
 
-## Features
+---
 
-- **Dynamic form rendering** using JSON schema  
-- **Automatic form validation** with [Zod](https://github.com/colinhacks/zod)  
-- **Form schema management** from your Supabase database  
-- **Built-in notification hooks** for success, error, and validation feedback  
-- **Easy API integration** for form submission  
-- **Custom callback support** (e.g., Telegram notifications)
+## ✨ Features
 
-## Installation
+-   **Article fetching & server-side rendering** using Supabase
+-   **Search, filter & sort** via built-in query schema
+-   **Article listing UI components** (cards, filters, pagination)
+-   **Full article viewer** with banner, tags, metadata & Supabase-hosted images
+-   **Reusable ArticleService** for all backend functionalities
+
+---
+
+## 📦 Installation
 
 ```bash
-npm install @k34a/forms
+npm install @k34a/blog
 ```
 
 ### Required peer dependencies
 
-Make sure you already have these installed in your project:
-
 ```bash
-npm install @mantine/core @mantine/dates @mantine/dropzone @mantine/notifications @supabase/supabase-js @tabler/icons-react react zod
+npm install @mantine/core @tabler/icons-react react @supabase/supabase-js zod
 ```
 
-**Required versions:**
-
-| Package | Version |
-|----------|----------|
-| `@mantine/core` | ≥ 8.0.0 |
-| `@mantine/dates` | ≥ 8.0.0 |
-| `@mantine/dropzone` | ≥ 8.0.0 |
-| `@mantine/notifications` | ≥ 8.0.0 |
+| Package                 | Version  |
+| ----------------------- | -------- |
+| `@mantine/core`         | ≥ 8.0.0  |
 | `@supabase/supabase-js` | ≥ 2.52.0 |
-| `@tabler/icons-react` | ≥ 3.0.0 |
-| `react` | ≥ 19.1.0 |
-| `zod` | ≥ 4.0.0 |
-
+| `@tabler/icons-react`   | ≥ 3.0.0  |
+| `react`                 | ≥ 19.1.0 |
+| `zod`                   | >= 4.0.0 |
 
-## ⚙️ API Setup
+---
 
-You might need to create an **API route** in your application to handle form submissions.
+# ⚙️ Setup (Backend)
 
-Example using Next.js **Route Handlers (`app/api/fill-me/[formType]/route.ts`)**:
+Create an instance of `ArticleService` anywhere in your backend/server code.
+A common location is: `lib/articles.ts`.
 
 ```ts
-import { adminPanelLink, ORG_ID } from "@/config/config";
-import { supabaseAdmin } from "@/lib/db/supabase";
-import { sendTelegramMessage } from "@/lib/telegram";
-import { FormFillingService } from "@k34a/forms";
-import { headers } from "next/headers";
-import { NextRequest, NextResponse } from "next/server";
-
-function isPlainObject(input: unknown): input is Record<string, any> {
-  return typeof input === "object" && input !== null && !Array.isArray(input);
-}
+import { supabaseAdmin } from '@/lib/db/supabase';
+import { ArticleService } from '@k34a/blog';
+
+export const articleService = new ArticleService(supabaseAdmin);
+```
+
+> This gives you access to all backend operations including listing, filtering, fetching by slug, resolving descriptions, etc.
+
+---
+
+# 📰 Creating an Article Card Component
 
-async function getSourceDetails() {
-  const hdrs = await headers();
-  const userAgent = hdrs.get("user-agent") ?? null;
-  const xff = hdrs.get("x-forwarded-for");
-  const realIp = hdrs.get("x-real-ip");
-  const sourceIp = xff?.split(",")[0].trim() ?? realIp ?? null;
-  return { sourceIp, userAgent };
+Use the built-in types & image resolver:
+
+```tsx
+'use client';
+
+import React from 'react';
+import {
+    Card,
+    Text,
+    Badge,
+    Group,
+    Button,
+    Stack,
+    Title,
+    Divider,
+} from '@mantine/core';
+import { IconBrandWhatsapp, IconClock, IconTag } from '@tabler/icons-react';
+import Image from '@/components/image';
+import Link from 'next/link';
+import { ngoDetails } from '@/config/config';
+import {
+    type ArticleDetailsForListing,
+    resolveImageForArticle,
+} from '@k34a/blog';
+
+interface Props {
+    article: ArticleDetailsForListing & { tags?: string[] };
 }
 
-export async function POST(
-  request: NextRequest,
-  { params }: { params: Promise<{ formType: string }> },
-) {
-  const { formType } = await params;
-
-  let body: unknown;
-  try {
-    body = await request.json();
-  } catch {
-    return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
-  }
-
-  if (!isPlainObject(body)) {
-    return NextResponse.json(
-      { error: "Invalid request format. Expected a key-value object." },
-      { status: 400 }
+export default function ArticleCard({ article }: Props) {
+    const {
+        id,
+        title,
+        description,
+        slug,
+        banner_image,
+        created_at,
+        tags = [],
+    } = article;
+
+    const articleLink = `/articles/${slug}`;
+    const shareUrl = `${ngoDetails.contact.website}/articles/${slug}`;
+    const shareText = encodeURIComponent(
+        `Check out this article "${title}": ${shareUrl}`
     );
-  }
-
-  try {
-    const service = new FormFillingService(
-      adminPanelLink,
-      ORG_ID,
-      supabaseAdmin,
-      async (msg) => {
-        try {
-          await sendTelegramMessage(msg);
-        } catch (error) {
-          console.log(error);
-        }
-      },
+    const whatsappLink = `https://wa.me/?text=${shareText}`;
+
+    const formattedDate = new Date(created_at).toLocaleDateString('en-IN', {
+        day: 'numeric',
+        month: 'short',
+        year: 'numeric',
+    });
+
+    return (
+        <Card shadow="sm" radius="md" p={0} withBorder maw={350}>
+            {banner_image && (
+                <Card.Section style={{ position: 'relative' }}>
+                    <Link href={articleLink}>
+                        <Image
+                            src={resolveImageForArticle(
+                                process.env.NEXT_PUBLIC_SUPABASE_HOSTNAME!,
+                                id,
+                                banner_image
+                            )}
+                            alt={`${title} banner`}
+                            width={400}
+                            height={220}
+                            style={{
+                                objectFit: 'cover',
+                                width: '100%',
+                                height: 220,
+                            }}
+                        />
+                    </Link>
+                </Card.Section>
+            )}
+
+            <Stack gap="xs" p="md">
+                <Link href={articleLink}>
+                    <Title size="lg" order={3} style={{ lineHeight: 1.2 }}>
+                        {title}
+                    </Title>
+                </Link>
+
+                <Group gap="xs" c="dimmed" mb={4}>
+                    <IconClock size={14} />
+                    <Text size="sm">{formattedDate}</Text>
+                </Group>
+
+                <Text size="sm" lineClamp={3}>
+                    {description}
+                </Text>
+
+                {tags.length > 0 && (
+                    <Group gap={6} mt={6}>
+                        {tags.slice(0, 3).map((tag, idx) => (
+                            <Badge
+                                key={idx}
+                                color="gray"
+                                variant="light"
+                                leftSection={<IconTag size={12} />}
+                            >
+                                {tag}
+                            </Badge>
+                        ))}
+                    </Group>
+                )}
+
+                <Divider my="sm" />
+
+                <Group grow>
+                    <Button
+                        component="a"
+                        href={whatsappLink}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        variant="outline"
+                        color="green"
+                        leftSection={<IconBrandWhatsapp size={16} />}
+                        fullWidth
+                        size="md"
+                    >
+                        Share
+                    </Button>
+
+                    <Button
+                        component={Link}
+                        href={articleLink}
+                        variant="filled"
+                        fullWidth
+                        size="md"
+                    >
+                        Read More
+                    </Button>
+                </Group>
+            </Stack>
+        </Card>
     );
-
-    const userDetails = await getSourceDetails();
-    const result = await service.fillForm(
-      formType,
-      body,
-      userDetails.sourceIp ?? "",
-      userDetails.userAgent ?? "",
-    );
-
-    return NextResponse.json(result);
-  } catch (err: any) {
-    return NextResponse.json({ error: err.message || "Internal Server Error" }, { status: 500 });
-  }
 }
 ```
 
+---
+
+# 🔍 Creating a Search + Filter + Sort Bar
+
+```tsx
+'use client';
+
+import {
+    FilterSearchSortArticles,
+    type FilterSearchSortArticlesProps,
+} from '@k34a/blog';
+import { usePathname, useRouter } from 'next/navigation';
+
+type Props = Omit<FilterSearchSortArticlesProps, 'navigate'>;
 
-### Explanation of Methods & Callbacks
+export const FilterSearchSort = (props: Props) => {
+    const router = useRouter();
+    const pathname = usePathname();
 
-| Function / Callback | Description |
-|---------------------|-------------|
-| **`isPlainObject()`** | Ensures the incoming JSON body is a plain object (key-value pairs) and not an array or invalid input. |
-| **`getSourceDetails()`** | Extracts the client’s IP address and `User-Agent` from headers for logging or analytics. |
-| **`FormFillingService`** | Core service from `@k34a/forms` that handles form validation, storage, and notifications. |
-| **`fillForm(formType, body, ip, userAgent)`** | Saves and validates the submitted form data. It links the form type to the schema defined in your admin panel. |
-| **Telegram Callback (`async (msg) => { ... }`)** | Optional async callback triggered after a successful form submission. You can send notifications to Telegram, Slack, etc. |
+    function navigate(query: string) {
+        router.push(`${pathname}?${query}`);
+    }
 
+    return <FilterSearchSortArticles {...props} navigate={navigate} />;
+};
+```
 
-## Creating a Dynamic Form Component
+---
 
-The simplest way to render a form dynamically is by using the `FormBuilder` component.
+# 📄 Pagination Control
 
 ```tsx
-"use client";
+'use client';
 
-import { FormBuilder, FormSchema } from "@k34a/forms";
-import z from "zod";
-import { notifications } from "@mantine/notifications";
-import { ORG_ID } from "@/config/config";
+import { Pagination, Group } from '@mantine/core';
+import { useRouter, usePathname, useSearchParams } from 'next/navigation';
 
-interface FormProps {
-  schema: z.infer<typeof FormSchema>;
-  formType: string;
+interface PaginationControlsProps {
+    total: number;
+    currentPage: number;
+    pageSize: number;
 }
 
-export const FillMe = (props: FormProps) => {
-  return (
-    <FormBuilder
-      mode="fill"
-      schema={props.schema}
-      formType={props.formType}
-      orgId={ORG_ID}
-      submissionAPIEndPoint={`/api/fill-me/${props.formType}`}
-      onSuccess={() =>
-        notifications.show({
-          title: "All Set!",
-          message:
-            "Your details were submitted successfully. Thank you for completing the form!",
-          color: "green",
-        })
-      }
-      onValidationError={() =>
-        notifications.show({
-          title: "Please Review Your Form",
-          message:
-            "Some information seems to be missing or incorrect. Check the highlighted fields and try again.",
-          color: "orange",
-        })
-      }
-      onError={() =>
-        notifications.show({
-          title: "Submission Failed",
-          message:
-            "Something went wrong while sending your details. Please try again later.",
-          color: "red",
-        })
-      }
-    />
-  );
-};
+export default function PaginationControls({
+    total,
+    currentPage,
+    pageSize,
+}: PaginationControlsProps) {
+    const router = useRouter();
+    const pathname = usePathname();
+    const searchParams = useSearchParams();
+
+    const totalPages = Math.ceil(total / pageSize);
+
+    if (totalPages <= 1) return null;
+
+    const handlePageChange = (page: number) => {
+        const params = new URLSearchParams(searchParams.toString());
+        params.set('page', String(page - 1));
+        router.push(`${pathname}?${params.toString()}`);
+    };
+
+    return (
+        <Group justify="center" mt="xl">
+            <Pagination
+                total={totalPages}
+                value={currentPage + 1}
+                onChange={handlePageChange}
+            />
+        </Group>
+    );
+}
 ```
 
-> 💡 **Tip:** Make sure to set your organization ID (`ORG_ID`) from your admin panel at [k34a.vercel.app](https://k34a.vercel.app).
+---
 
+# 📝 Rendering a Single Article Page
 
-## Fetching the Form Schema from Supabase
+```tsx
+import { articleService } from '@/lib/db/articles';
+import { Article } from '@k34a/blog';
+import { Metadata } from 'next';
+import { notFound } from 'next/navigation';
 
-You can dynamically fetch a form schema from your Supabase database before rendering the form:
+type PageProps = {
+    params: Promise<{ slug: string }>;
+};
+
+export async function generateMetadata({
+    params,
+}: PageProps): Promise<Metadata> {
+    const campaign = await articleService.getBySlug((await params).slug);
+
+    if (!campaign) {
+        return {
+            title: 'Not Found',
+            description: "The article you're looking for does not exist.",
+        };
+    }
+
+    return {
+        title: campaign.title,
+        description: campaign.description,
+    };
+}
+
+export default async function ArticlePage({ params }: PageProps) {
+    const { slug } = await params;
+
+    const article = await articleService.getBySlug(slug);
+    if (!article) return notFound();
+
+    const description = (await articleService.getDescription(article.id)) ?? '';
+
+    return (
+        <Article
+            config={{
+                supabaseHost: process.env.NEXT_PUBLIC_SUPABASE_HOSTNAME!,
+                listingPage: '/articles',
+            }}
+            description={description}
+            tags={article.tags}
+            title={article.title}
+            banner_image={article.banner_image ?? undefined}
+            id={article.id}
+        />
+    );
+}
+```
+
+---
+
+# 📚 Rendering an Article Listing Page
 
 ```tsx
-import { FormFillingService } from "@k34a/forms";
-import { supabaseAdmin } from "@/lib/db/supabase";
-import { notFound } from "next/navigation";
-import { adminPanelLink, ORG_ID } from "@/config/config";
-import Partners from "@/components/partners/partners";
-
-export default async function PartnersPage() {
-  let schema;
-  const formType = "csr_partnership_inquiry";
-
-  try {
-    schema = await new FormFillingService(
-      adminPanelLink,
-      ORG_ID,
-      supabaseAdmin,
-    ).getFormSchema(formType);
-  } catch (err) {
-    console.error(err);
-    notFound();
-  }
-
-  return (
-    <main>
-      <Partners schema={schema} formType={formType} />
-    </main>
-  );
+import ArticlesCard from '@/components/articles-listing/card';
+import { articleQuerySchema } from '@k34a/blog';
+import { parseQueryWithPerFieldDefaults } from '@/lib/utils/query-params';
+import { Container, SimpleGrid, Stack, Text } from '@mantine/core';
+import { IconSearchOff } from '@tabler/icons-react';
+import { articleService } from '@/lib/db/articles';
+import PaginationControls from '@/components/content-management/pagination-controls';
+import { FilterSearchSort } from '@/components/articles-listing/filter-search-sort';
+
+interface Props {
+    searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
+}
+
+export default async function Page(props: Props) {
+    const searchParams = await props.searchParams;
+    const params = parseQueryWithPerFieldDefaults(
+        articleQuerySchema,
+        searchParams
+    );
+
+    const data = await articleService.list(params);
+    const tags = await articleService.getTagNames();
+
+    return (
+        <Container size="lg" py="xl">
+            <FilterSearchSort {...params} availableTags={tags} />
+
+            {data.items.length === 0 ? (
+                <Stack align="center" py="xl" gap="sm">
+                    <IconSearchOff size={48} stroke={1.5} color="gray" />
+                    <Text fw={500} size="lg">
+                        No articles found
+                    </Text>
+                    <Text size="sm" c="dimmed" ta="center" mx="auto" maw={300}>
+                        We couldn&apos;t find any articles matching your
+                        filters.
+                    </Text>
+                </Stack>
+            ) : (
+                <SimpleGrid cols={{ base: 1, sm: 2, md: 3 }} spacing="lg">
+                    {data.items.map((article) => (
+                        <ArticlesCard key={article.id} article={article} />
+                    ))}
+                </SimpleGrid>
+            )}
+
+            <Text size="sm" c="dimmed" mt="md">
+                Showing {data.items.length} of {data.total} articles
+            </Text>
+
+            <PaginationControls
+                total={data.total}
+                currentPage={params.page}
+                pageSize={10}
+            />
+        </Container>
+    );
 }
 ```
 
+---
+
+# 📘 Summary
 
-## Summary
+| Step                   | Description                                      |
+| ---------------------- | ------------------------------------------------ |
+| Install the package    | `npm install @k34a/blog`                         |
+| Create ArticleService  | Backend methods for fetching & listing articles  |
+| Build an Article Card  | Use `resolveImageForArticle` for Supabase images |
+| Add Search/Filter/Sort | Use `<FilterSearchSortArticles />`               |
+| Add Pagination         | Connect query params to your router              |
+| Render Articles        | With `<Article />` viewer                        |
+| Render Listings        | Using built-in schema & utilities                |
 
-| Step | Description |
-|------|--------------|
-| Install the package | `npm install @k34a/forms` |
-| Create API handler | Accepts and validates form submissions |
-| Use `FormBuilder` | To render and handle forms in your UI |
-| Fetch form schemas | From your Supabase database using `FormFillingService` |
-| Customize callbacks | (Success, ValidationError, Error) for better UX |
+---
 
-## License
+# 📝 License
 
 MIT © 2025 — Built with ❤️ by [K34A](https://k34a.vercel.app)

package/dist/cfg.d.ts

@@ -0,0 +1 @@
+export declare const PAGE_SIZE = 12;

package/dist/cfg.js

@@ -0,0 +1,5 @@
+"use client";
+const e = 12;
+export {
+  e as PAGE_SIZE
+};

package/dist/services/articles.js

@@ -1,7 +1,7 @@
-import { articleSortByVsQuery as _ } from "./search-params.js";
+import { articleSortByVsQuery as p } from "./search-params.js";
 import "zod";
-const p = 12;
-class q {
+import { PAGE_SIZE as _ } from "../cfg.js";
+class D {
   db;
   constructor(r) {
     this.db = r;
@@ -52,13 +52,13 @@ class q {
    * Paginated list of articles with filters and sorting.
    */
   async list(r) {
-    const { page: t, search: a, sortBy: c, tags: s } = r, o = _[c] ?? _.latest;
+    const { page: t, search: a, sortBy: c, tags: s } = r, o = p[c] ?? p.latest;
     let e = this.db.from("articles").select("*", { count: "exact" }).eq("status", "Published");
     if (a && (e = e.ilike("title", `%${a}%`)), s && s.length > 0) {
-      const { data: m, error: f } = await this.db.from("tags").select("id").in("name", s);
-      if (f || !m?.length)
+      const { data: d, error: f } = await this.db.from("tags").select("id").in("name", s);
+      if (f || !d?.length)
         return console.error("Error fetching tag IDs:", f?.message), { items: [], total: 0 };
-      const w = m.map((g) => g.id), { data: u, error: h } = await this.db.from("tag_articles").select("article_id").in("tag_id", w);
+      const w = d.map((g) => g.id), { data: u, error: h } = await this.db.from("tag_articles").select("article_id").in("tag_id", w);
       if (h || !u?.length)
         return console.error(
           "Error fetching articles by tags:",
@@ -72,10 +72,10 @@ class q {
       e = e.in("id", b);
     }
     e = e.order(o.column, { ascending: o.ascending });
-    const i = t * p, n = i + p - 1;
+    const i = t * _, n = i + _ - 1;
     e = e.range(i, n);
-    const { data: l, error: d, count: E } = await e;
-    return d ? (console.error("Error fetching articles:", d), { items: [], total: 0 }) : {
+    const { data: l, error: m, count: E } = await e;
+    return m ? (console.error("Error fetching articles:", m), { items: [], total: 0 }) : {
       items: l || [],
       total: E || 0
     };
@@ -91,5 +91,5 @@ class q {
   }
 }
 export {
-  q as ArticleService
+  D as ArticleService
 };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@k34a/blog",
   "description": "Create and share articles with your audience.",
   "private": false,
-  "version": "0.0.7",
+  "version": "0.0.8",
   "type": "module",
   "exports": {
     ".": {