GH-181 Add placeholder docs automation (#181)

* Add dynamic placeholders documentation and API integration

* lint fix, add placeholder documentation.

* Add "Placeholders" to sidebar; improve type imports and button accessibility

* revert

* Update components/docs/eternalcore/placeholder/PlaceholderTable.tsx

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Update components/docs/eternalcore/placeholder/hooks/usePlaceholders.ts

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Refactor `usePlaceholders` hook: improve type imports, use `useCallback` for `filterPlaceholders`, and enhance error handling.

* Refine `PlaceholderSearchBar`: improve focus styles, add shadow enhancements, and ensure consistent dark mode styling.

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: vLuckyyy

components/docs/eternalcore/placeholder/DynamicNoPlaceholderMessage.tsx

@@ -0,0 +1,15 @@
+"use client";
+
+import { motion } from "framer-motion";
+
+export function DynamicNoPlaceholderMessage() {
+  return (
+    <motion.div
+      initial={{ opacity: 0 }}
+      animate={{ opacity: 1 }}
+      className="py-12 text-center text-gray-500 dark:text-gray-400"
+    >
+      No placeholders found.
+    </motion.div>
+  );
+}

components/docs/eternalcore/placeholder/DynamicPlaceholdersTable.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import { DynamicNoPlaceholderMessage } from "@/components/docs/eternalcore/placeholder/DynamicNoPlaceholderMessage";
+import { usePlaceholders } from "@/components/docs/eternalcore/placeholder/hooks/usePlaceholders";
+import { PlaceholderCategoryButtons } from "@/components/docs/eternalcore/placeholder/PlaceholderCategoryButtons";
+import { PlaceholderSearchBar } from "@/components/docs/eternalcore/placeholder/PlaceholderSearchBar";
+import { PlaceholderTable } from "@/components/docs/eternalcore/placeholder/PlaceholderTable";
+
+export default function DynamicPlaceholdersTable() {
+  const {
+    allPlaceholders,
+    viewablePlaceholders,
+    categories,
+    activeCategory,
+    searchQuery,
+    error,
+    loading,
+    handleSearchChange,
+    handleCategoryClick,
+  } = usePlaceholders();
+
+  if (error) {
+    return <div className="p-6 text-center text-red-500">Error: {error}</div>;
+  }
+
+  if (loading) {
+    return <div className="p-6 text-center text-gray-500 dark:text-gray-400">Loading...</div>;
+  }
+
+  return (
+    <div className="w-full">
+      <div className="mb-6 flex flex-col gap-4">
+        <PlaceholderSearchBar
+          searchQuery={searchQuery}
+          onSearchChange={handleSearchChange}
+          viewableCount={viewablePlaceholders.length}
+          totalCount={allPlaceholders.length}
+        />
+
+        <PlaceholderCategoryButtons
+          categories={categories}
+          activeCategory={activeCategory}
+          onCategoryClick={handleCategoryClick}
+        />
+      </div>
+
+      <PlaceholderTable placeholders={viewablePlaceholders} />
+
+      {!viewablePlaceholders.length && <DynamicNoPlaceholderMessage />}
+    </div>
+  );
+}

components/docs/eternalcore/placeholder/PlaceholderCategoryButtons.tsx

@@ -0,0 +1,38 @@
+"use client";
+
+import { Tag } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+interface PlaceholderCategoryButtonsProps {
+  categories: string[];
+  activeCategory: string;
+  onCategoryClick: (category: string) => void;
+}
+
+export function PlaceholderCategoryButtons({
+  categories,
+  activeCategory,
+  onCategoryClick,
+}: PlaceholderCategoryButtonsProps) {
+  return (
+    <div className="flex flex-wrap gap-2">
+      {categories.map((category) => (
+        <button
+          type="button"
+          key={category}
+          onClick={() => onCategoryClick(category)}
+          className={cn(
+            "cursor-pointer flex items-center gap-1.5 rounded-full px-3 py-1.5 text-xs font-medium transition-all",
+            category === activeCategory
+              ? "bg-blue-500 text-white shadow-md shadow-blue-500/30"
+              : "bg-gray-100 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-300 dark:hover:bg-gray-700"
+          )}
+        >
+          <Tag size={12} />
+          {category}
+        </button>
+      ))}
+    </div>
+  );
+}

components/docs/eternalcore/placeholder/PlaceholderSearchBar.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+import { Search } from "lucide-react";
+import { type ChangeEvent, useState } from "react";
+
+import { cn } from "@/lib/utils";
+
+interface PlaceholderSearchBarProps {
+  searchQuery: string;
+  onSearchChange: (event: ChangeEvent<HTMLInputElement>) => void;
+  viewableCount: number;
+  totalCount: number;
+}
+
+export function PlaceholderSearchBar({
+  searchQuery,
+  onSearchChange,
+  viewableCount,
+  totalCount,
+}: PlaceholderSearchBarProps) {
+  const [isInputFocused, setIsInputFocused] = useState(false);
+
+  return (
+    <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+      <div className="relative w-full sm:w-80">
+        <Search className="absolute left-3 top-1/2 -translate-y-1/2 text-gray-400" size={18} />
+        <input
+          value={searchQuery}
+          onChange={onSearchChange}
+          onFocus={() => setIsInputFocused(true)}
+          onBlur={() => setIsInputFocused(false)}
+          placeholder="Search placeholders..."
+          className={cn(
+            "w-full select-none rounded-lg border bg-white px-4 py-2.5 pl-10 pr-10 text-sm outline-hidden transition-all duration-200",
+            isInputFocused
+              ? "border-blue-500 shadow-lg shadow-blue-500/20 ring-2 ring-blue-500/50 dark:shadow-blue-500/10"
+              : "border-gray-300 shadow-xs dark:border-gray-700",
+            "placeholder:text-gray-400 dark:bg-gray-800 dark:text-white dark:placeholder:text-gray-500"
+          )}
+        />
+      </div>
+      <div className="text-sm text-gray-600 dark:text-gray-400">
+        Placeholders: <span className="font-semibold">{viewableCount}</span> / {totalCount}
+      </div>
+    </div>
+  );
+}

components/docs/eternalcore/placeholder/PlaceholderTable.tsx

@@ -0,0 +1,72 @@
+"use client";
+
+import { AnimatePresence, motion } from "framer-motion";
+
+import type { Placeholder } from "@/components/docs/eternalcore/placeholder/types";
+import { cn } from "@/lib/utils";
+
+interface PlaceholderTableProps {
+  placeholders: Placeholder[];
+}
+
+export function PlaceholderTable({ placeholders }: PlaceholderTableProps) {
+  return (
+    <div className="overflow-x-auto rounded-lg">
+      <table className="w-full text-left text-sm">
+        <thead className="bg-gray-100 text-gray-800 dark:bg-gray-800 dark:text-gray-100">
+          <tr>
+            {["Placeholder", "Description", "Example", "Type", "Category", "Player Context"].map(
+              (header) => (
+                <th key={header} className="px-4 py-3 font-semibold">
+                  {header}
+                </th>
+              )
+            )}
+          </tr>
+        </thead>
+        <tbody className="divide-y divide-gray-200 dark:divide-gray-700">
+          <AnimatePresence>
+            {placeholders.map((p, i) => (
+              <motion.tr
+                key={p.name}
+                initial={{ opacity: 0, y: 5 }}
+                animate={{ opacity: 1, y: 0 }}
+                exit={{ opacity: 0, y: -5 }}
+                transition={{ duration: 0.2, delay: i * 0.01 }}
+                className="hover:bg-gray-50 dark:hover:bg-gray-900/50"
+              >
+                <td className="px-4 py-2 font-mono text-blue-600 dark:text-blue-400">{p.name}</td>
+                <td className="px-4 py-2 text-gray-600 dark:text-gray-300">{p.description}</td>
+                <td className="px-4 py-2 font-mono text-green-600 dark:text-green-400">
+                  {p.example}
+                </td>
+                <td className="px-4 py-2">
+                  <span className="rounded bg-purple-100 px-2 py-0.5 text-xs font-medium text-purple-700 dark:bg-purple-900/30 dark:text-purple-300">
+                    {p.returnType}
+                  </span>
+                </td>
+                <td className="px-4 py-2">
+                  <span className="rounded bg-gray-100 px-2 py-0.5 text-xs font-medium text-gray-600 dark:bg-gray-700 dark:text-gray-300">
+                    {p.category}
+                  </span>
+                </td>
+                <td className="px-4 py-2 text-center">
+                  <span
+                    className={cn(
+                      "rounded px-2 py-0.5 text-xs font-medium",
+                      p.requiresPlayer
+                        ? "bg-orange-100 text-orange-700 dark:bg-orange-900/30 dark:text-orange-300"
+                        : "bg-gray-100 text-gray-600 dark:bg-gray-800 dark:text-gray-400"
+                    )}
+                  >
+                    {p.requiresPlayer ? "Required" : "Optional"}
+                  </span>
+                </td>
+              </motion.tr>
+            ))}
+          </AnimatePresence>
+        </tbody>
+      </table>
+    </div>
+  );
+}

components/docs/eternalcore/placeholder/hooks/index.ts

@@ -0,0 +1 @@
+export * from "./usePlaceholders";

components/docs/eternalcore/placeholder/hooks/usePlaceholders.ts

@@ -0,0 +1,122 @@
+"use client";
+
+import { create, insert, type Orama, search } from "@orama/orama";
+import type React from "react";
+import { useCallback, useEffect, useState } from "react";
+import type { Placeholder } from "@/components/docs/eternalcore/placeholder/types";
+
+const placeholderSchema = {
+  name: "string",
+  description: "string",
+  example: "string",
+  returnType: "string",
+  category: "string",
+  requiresPlayer: "boolean",
+} as const;
+
+type PlaceholderDB = Orama<typeof placeholderSchema>;
+
+export function usePlaceholders() {
+  const [allPlaceholders, setAllPlaceholders] = useState<Placeholder[]>([]);
+  const [viewablePlaceholders, setViewablePlaceholders] = useState<Placeholder[]>([]);
+  const [categories, setCategories] = useState<string[]>([]);
+  const [activeCategory, setActiveCategory] = useState("All");
+  const [searchQuery, setSearchQuery] = useState("");
+  const [db, setDb] = useState<PlaceholderDB | undefined>();
+  const [error, setError] = useState<string | undefined>();
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const initializeData = async () => {
+      try {
+        setLoading(true);
+
+        const response = await fetch(
+          "https://raw.githubusercontent.com/EternalCodeTeam/EternalCore/refs/heads/master/raw_eternalcore_placeholders.json"
+        );
+
+        if (!response.ok) {
+          setError(`Failed to fetch data: ${response.statusText}`);
+          return;
+        }
+
+        const data = (await response.json()) as Placeholder[];
+        const sortedData = [...data].sort((a, b) => a.name.localeCompare(b.name, "pl"));
+
+        setAllPlaceholders(sortedData);
+        setViewablePlaceholders(sortedData);
+
+        const uniqueCategories = Array.from(new Set(sortedData.map((p) => p.category))).sort();
+        setCategories(["All", ...uniqueCategories]);
+
+        const oramaDb = create({ schema: placeholderSchema });
+        await Promise.all(sortedData.map((p) => insert(oramaDb, p)));
+
+        setDb(oramaDb);
+      } catch (exception) {
+        setError(exception instanceof Error ? exception.message : "An unknown error occurred");
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    initializeData();
+  }, []);
+
+  const filterPlaceholders = useCallback(
+    async (query = searchQuery, category = activeCategory) => {
+      try {
+        let filteredList =
+          category === "All"
+            ? allPlaceholders
+            : allPlaceholders.filter((p) => p.category === category);
+
+        if (query.trim() && db) {
+          const searchResult = await search(db, {
+            term: query,
+            properties: ["name", "description", "example", "category"],
+            tolerance: 1,
+          });
+
+          const resultIds = new Set(searchResult.hits.map((hit) => hit.document.name));
+          filteredList = filteredList.filter((p) => resultIds.has(p.name));
+        }
+
+        setViewablePlaceholders(filteredList);
+      } catch (exception) {
+        setError(
+          exception instanceof Error ? exception.message : "An unknown search error occurred"
+        );
+      }
+    },
+    [allPlaceholders, db, searchQuery, activeCategory]
+  );
+
+  const handleSearchChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    setSearchQuery(event.target.value);
+  };
+
+  useEffect(() => {
+    const timeout = setTimeout(() => {
+      filterPlaceholders(searchQuery, activeCategory);
+    }, 300);
+
+    return () => clearTimeout(timeout);
+  }, [searchQuery, activeCategory, filterPlaceholders]);
+
+  const handleCategoryClick = (category: string) => {
+    setActiveCategory(category);
+  };
+
+  return {
+    allPlaceholders,
+    viewablePlaceholders,
+    categories,
+    activeCategory,
+    searchQuery,
+    error,
+    loading,
+    handleSearchChange,
+    handleCategoryClick,
+  };
+}

components/docs/eternalcore/placeholder/index.ts

@@ -0,0 +1,5 @@
+export * from "./DynamicNoPlaceholderMessage";
+export * from "./PlaceholderCategoryButtons";
+export * from "./PlaceholderSearchBar";
+export * from "./PlaceholderTable";
+export * from "./types";

components/docs/eternalcore/placeholder/types.ts

@@ -0,0 +1,8 @@
+export interface Placeholder {
+  name: string;
+  description: string;
+  example: string;
+  returnType: string;
+  category: string;
+  requiresPlayer: boolean;
+}

components/mdx/mdx-components.tsx

@@ -3,6 +3,7 @@ import type { ComponentProps, HTMLAttributes } from "react";
 import Image from "next/image";
 
 import DynamicCommandsTable from "@/components/docs/eternalcore/DynamicCommandsTable";
+import DynamicPlaceholdersTable from "@/components/docs/eternalcore/placeholder/DynamicPlaceholdersTable";
 import { CodeBlock } from "@/components/mdx/CodeBlock";
 import { CodeTab, CodeTabs } from "@/components/mdx/CodeTabs";
 import { Heading } from "@/components/mdx/Heading";
@@ -43,6 +44,7 @@ export const components: MDXComponents = {
   CodeTabs,
   CodeTab,
   DynamicCommandsTable,
+  DynamicPlaceholdersTable,
 
   code: (props: ComponentProps<"code">) => {
     const { children, ...rest } = props;