docs: migrate to nextra@4

apps/docs/env.d.ts

@@ -0,0 +1,4 @@
+declare module "!!raw-loader!*" {
+  const src: string;
+  export default src;
+}

apps/docs/next-env.d.ts

@@ -2,4 +2,4 @@
 /// <reference types="next/image-types/global" />
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/pages/api-reference/config/typescript for more information.
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

apps/docs/next.config.mjs

@@ -2,8 +2,6 @@ import nextra from "nextra";
 import rehypeMdxCodeProps from "rehype-mdx-code-props";
 
 const withNextra = nextra({
-  theme: "nextra-theme-docs",
-  themeConfig: "./theme.config.tsx",
   defaultShowCopyCode: true,
   search: {
     codeblocks: false,
@@ -43,6 +41,21 @@ export default withNextra({
       ],
     });
 
+    // Inject "use client"; to UI Kit packages' entry (index.ts) file
+    config.module.rules.push({
+      test: /packages\/.*\/src\/index\.ts$/,
+      use: [
+        {
+          loader: "string-replace-loader",
+          options: {
+            search: "^",
+            replace: '"use client";\n',
+            flags: "g",
+          },
+        },
+      ],
+    });
+
     // Add raw file loader
     config.module.rules.push({
       test: /\.(tsx|ts|mdx)$/,

apps/docs/package.json

@@ -5,6 +5,7 @@
   "scripts": {
     "dev": "next dev",
     "build": "next build",
+    "postbuild": "pagefind --site dist --output-path dist/_pagefind",
     "start": "npx serve dist"
   },
   "dependencies": {
@@ -14,9 +15,9 @@
     "@hitachivantara/uikit-react-viz": "*",
     "@phosphor-icons/react": "^2.1.7",
     "clsx": "^2.1.1",
-    "next": "^15.1.7",
-    "nextra": "^3.3.1",
-    "nextra-theme-docs": "^3.3.1",
+    "next": "^15.3.2",
+    "nextra": "^4.2.17",
+    "nextra-theme-docs": "^4.2.17",
     "prism-react-renderer": "^2.4.0",
     "react": "^18.3.1",
     "react-docgen-typescript": "^2.2.2",
@@ -30,6 +31,7 @@
     "@types/node": "^20.11.6",
     "@types/react": "^18.2.43",
     "@unocss/postcss": "^66.0.0",
+    "pagefind": "^1.3.0",
     "raw-loader": "^4.0.2",
     "rehype-mdx-code-props": "^3.0.1",
     "string-replace-loader": "^3.1.0",

apps/docs/src/app/[[...mdxPath]]/page.tsx

@@ -0,0 +1,25 @@
+import { generateStaticParamsFor, importPage } from "nextra/pages";
+
+import { useMDXComponents as getMDXComponents } from "../../mdx-components";
+
+export const generateStaticParams = generateStaticParamsFor("mdxPath");
+
+export async function generateMetadata(props: any) {
+  const params = await props.params;
+  const { metadata } = await importPage(params.mdxPath);
+  return metadata;
+}
+
+const Wrapper = getMDXComponents().wrapper;
+
+export default async function Page(props: any) {
+  const params = await props.params;
+  const result = await importPage(params.mdxPath);
+  const { default: MDXContent, toc, metadata } = result;
+
+  return (
+    <Wrapper toc={toc} metadata={metadata}>
+      <MDXContent {...props} params={params} />
+    </Wrapper>
+  );
+}

apps/docs/src/app/globals.css

@@ -0,0 +1,67 @@
+@unocss all;
+
+.dark {
+  @apply bg-[#151c26];
+}
+
+html,
+body {
+  height: auto;
+}
+
+pre {
+  @apply my-4;
+}
+
+article main,
+article main.x\:w-full {
+  font-size: 1rem;
+}
+
+header {
+  & a:last-of-type svg {
+    @apply size-20px;
+  }
+  & button svg {
+    @apply size-16px;
+  }
+}
+
+.nextra-toc {
+  @apply w-224px;
+
+  & a {
+    @apply font-normal;
+  }
+
+  & p {
+    @apply shadow-none;
+  }
+}
+
+.nextra-sidebar-footer,
+.nextra-toc-footer {
+  display: none;
+}
+
+.nextra-breadcrumb {
+  @apply mb-sm;
+}
+
+.nextra-code {
+  @apply !my-0;
+}
+
+.nextra-code .nextra-focus {
+  @apply bg-slate-50;
+}
+
+.nextra-scrollbar {
+  & [aria-current="true"] {
+    @apply text-text;
+  }
+
+  & [aria-current="false"] {
+    @apply text-textSubtle;
+  }
+}

apps/docs/src/app/layout.tsx

@@ -0,0 +1,79 @@
+import "nextra-theme-docs/style.css";
+import "./globals.css";
+
+import { type NextraMetadata } from "nextra";
+import { Layout, Navbar, ThemeSwitch } from "nextra-theme-docs";
+import { Head, Search } from "nextra/components";
+import { getPageMap } from "nextra/page-map";
+
+import { UIKitLogo } from "../assets/logos";
+import { Footer } from "../components/Footer";
+import { Main } from "../components/Main";
+import { ThemeSwitcher } from "../components/ThemeSwitcher";
+
+const title = "UI Kit";
+const description = "UI Kit documentation site";
+
+export const metadata = {
+  metadataBase: new URL("https://github.com/lumada-design/hv-uikit-react"),
+  title: { default: "UI Kit", template: "%s - UI Kit" },
+  description,
+  icons: "https://lumada-design.github.io/assets/uikit-icon.svg",
+  creator: "UI Kit Team",
+  applicationName: title,
+  appleWebApp: { title },
+  openGraph: {
+    url: "@site",
+    siteName: title,
+    title,
+    description,
+    type: "website",
+  },
+  twitter: {
+    site: "@site",
+    creator: "@creator",
+    card: "summary",
+  },
+} satisfies NextraMetadata;
+
+const navbar = (
+  <Navbar
+    logo={<UIKitLogo />}
+    projectLink="https://github.com/lumada-design/hv-uikit-react"
+  >
+    <ThemeSwitch lite />
+    <ThemeSwitcher />
+  </Navbar>
+);
+
+export default async function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en" dir="ltr" suppressHydrationWarning>
+      <Head faviconGlyph="✦" color={{ hue: 210 }}>
+        <link
+          href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600;&family=Open+Sans:wght@400;600&display=swap"
+          rel="stylesheet"
+        />
+      </Head>
+      <body>
+        <Layout
+          navbar={navbar}
+          feedback={{ content: null }}
+          toc={{ title: "Table of Contents" }}
+          search={<Search placeholder="Search..." />}
+          footer={<Footer />}
+          editLink={null}
+          docsRepositoryBase="https://github.com/lumada-design/hv-uikit-react/tree/master/apps/docs"
+          sidebar={{ defaultMenuCollapseLevel: 1, toggleButton: false }}
+          pageMap={await getPageMap()}
+        >
+          <Main>{children}</Main>
+        </Layout>
+      </body>
+    </html>
+  );
+}

apps/docs/src/assets/logos.tsx

@@ -0,0 +1,31 @@
+export const UIKitLogo = () => (
+  <svg width="100" viewBox="0 0 439 160" fill="light-dark(#333, #fff)">
+    <title>UI Kit Logo</title>
+    <path d="M0 12C0 5.37258 5.37258 0 12 0H165C171.627 0 177 5.37258 177 12V148C177 154.627 171.627 160 165 160H12C5.37258 160 0 154.627 0 148V12Z" />
+    <path
+      d="M82.2727 39.7273H105.966V95.6364C105.966 102.284 104.375 108.037 101.193 112.895C98.0398 117.724 93.6364 121.46 87.983 124.102C82.3295 126.716 75.767 128.023 68.2955 128.023C60.767 128.023 54.1761 126.716 48.5227 124.102C42.8693 121.46 38.4659 117.724 35.3125 112.895C32.1875 108.037 30.625 102.284 30.625 95.6364V39.7273H54.3182V93.5909C54.3182 96.2898 54.9148 98.7045 56.108 100.835C57.3011 102.937 58.9489 104.585 61.0511 105.778C63.1818 106.972 65.5966 107.568 68.2955 107.568C71.0227 107.568 73.4375 106.972 75.5398 105.778C77.642 104.585 79.2898 102.937 80.483 100.835C81.6761 98.7045 82.2727 96.2898 82.2727 93.5909V39.7273ZM140.92 39.7273V127H117.227V39.7273H140.92Z"
+      fill="light-dark(#fff, #333)"
+    />
+    <path d="M214.608 127V39.7273H230.418V79.8267H231.483L265.531 39.7273H284.835L251.085 78.8892L285.134 127H266.128L240.091 89.5852L230.418 101.006V127H214.608ZM311.629 39.7273V127H295.819V39.7273H311.629ZM324.913 52.9801V39.7273H394.544V52.9801H367.57V127H351.888V52.9801H324.913Z" />
+  </svg>
+);
+
+export const GitHubLogo = () => (
+  <svg
+    width="1em"
+    height="1em"
+    viewBox="0 0 16 16"
+    fill="light-dark(#000, #fff)"
+  >
+    <title>GitHub Logo</title>
+    <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" />
+  </svg>
+);
+
+export const NpmLogo = () => (
+  <svg width="1em" height="1em" viewBox="0 0 256 256">
+    <title>NPM Logo</title>
+    <path d="M0 256V0h256v256z" fill="#C12127" />
+    <path d="M48 48h160v160h-32V80h-48v128H48z" fill="#FFF" />
+  </svg>
+);

apps/docs/src/components/Examples.tsx

@@ -1,17 +1,16 @@
+import canvas from "!!raw-loader!../content/examples/canvas.mdx";
+import charts from "!!raw-loader!../content/examples/charts.mdx";
+import dnd from "!!raw-loader!../content/examples/dnd.mdx";
+import inputs from "!!raw-loader!../content/examples/inputs.mdx";
+import kpis from "!!raw-loader!../content/examples/kpis.mdx";
+import tables from "!!raw-loader!../content/examples/tables.mdx";
 import { clsx } from "clsx";
 import Link from "next/link";
 import {
   HvIconContainer,
   HvTypography,
 } from "@hitachivantara/uikit-react-core";
 
-import canvas from "../pages/examples/canvas.mdx?raw";
-import charts from "../pages/examples/charts.mdx?raw";
-import dnd from "../pages/examples/dnd.mdx?raw";
-import inputs from "../pages/examples/inputs.mdx?raw";
-import kpis from "../pages/examples/kpis.mdx?raw";
-import tables from "../pages/examples/tables.mdx?raw";
-
 /**
  * Extracts the number of CodeBlock components in the given file content.
  */

apps/docs/src/components/Footer.tsx

@@ -1,6 +1,6 @@
 import Link from "next/link";
 
-import { UIKitLogo } from "./logo/uikit";
+import { UIKitLogo } from "../assets/logos";
 
 const footerLinks = [
   {
@@ -48,7 +48,7 @@ export const Footer = () => {
   const year = new Date().getFullYear();
 
   return (
-    <footer className="py-lg border-t border-bgPage">
+    <footer className="py-lg border-t border-border">
       <div className="max-w-1400px mx-auto px-md">
         <div className="flex flex-col md:flex-row md:justify-between space-y-md md:space-y-0">
           {/* Logo Section with More Space */}

apps/docs/src/components/Header.tsx

@@ -1,43 +1,27 @@
-import { useRouter } from "next/router";
-import { HvContainer, HvTab, HvTabs } from "@hitachivantara/uikit-react-core";
+import { Suspense } from "react";
 
-import { Classes } from "./usage/Classes";
+import { ComponentDataParams, getComponentData } from "../utils/component";
+import { PlaygroundProps } from "./code/Playground";
 import { Description } from "./usage/Description";
-import { Props } from "./usage/Props";
+import { Tabs } from "./usage/Tabs";
 
-type TabId = "usage" | "props" | "classes";
+interface HeaderProps extends PlaygroundProps {
+  params: ComponentDataParams;
+}
 
 /**
  * The `Header` component manages a tab-based layout
  * and dynamically displays specific sections based on the selected tab.
  */
-export const Header = () => {
-  const { query, push } = useRouter();
-
-  const tab = (query.tab as TabId) || "usage";
+export async function Header({ params, ...playgroundProps }: HeaderProps) {
+  const meta = await getComponentData(params);
 
   return (
-    <div
-      // Hide sibling elements except for the last child when tab !== 0.
-      className={tab === "usage" ? "" : "[&~*:not(:last-child)]:hidden"}
-    >
-      <Description />
-      <div className="pt-md">
-        <HvTabs
-          variant="fullWidth"
-          value={tab}
-          onChange={(_, value) => push({ query: { ...query, tab: value } })}
-          className="mt-sm mb-md w-360px"
-        >
-          <HvTab value="usage" label="Usage" />
-          <HvTab value="props" label="Props" />
-          <HvTab value="classes" label="Classes" />
-        </HvTabs>
-        <HvContainer disableGutters className="mb-lg">
-          {tab === "props" && <Props />}
-          {tab === "classes" && <Classes />}
-        </HvContainer>
-      </div>
+    <div className="[&:not(:has([data-tab=usage]))_~_*]:hidden">
+      <Description meta={meta} />
+      <Suspense fallback={null}>
+        <Tabs meta={meta} playgroundProps={{ ...playgroundProps, meta }} />
+      </Suspense>
     </div>
   );
-};
+}

apps/docs/src/components/Main.tsx

@@ -1,3 +1,6 @@
+"use client";
+
+// TODO: 👆 remove this, make HvProvider SSR-friendly
 import createCache from "@emotion/cache";
 import { useTheme } from "nextra-theme-docs";
 import { HvProvider, pentahoPlus } from "@hitachivantara/uikit-react-core";

apps/docs/src/components/home/ThemeSwitcher.tsx → apps/docs/src/components/ThemeSwitcher.tsx

@@ -1,7 +1,9 @@
+"use client";
+
 import { usePathname } from "next/navigation";
 import { HvSelect } from "@hitachivantara/uikit-react-core";
 
-import { useDocsTheme } from "../../hooks/useDocsTheme";
+import { useDocsTheme } from "../hooks/useDocsTheme";
 
 const themes = [
   { value: "pentahoPlus", label: "Pentaho+" },