@carlonicora/nextjs-jsonapi 1.108.0 → 1.110.0

package/src/features/help/components/HelpTOC.tsx

@@ -0,0 +1,49 @@
+"use client";
+import { useEffect, useState } from "react";
+import { useTranslations } from "next-intl";
+import type { HelpHeading } from "../types/help-article.types";
+
+export function HelpTOC({ headings }: { headings: readonly HelpHeading[] }) {
+  const t = useTranslations();
+  const [active, setActive] = useState<string | null>(null);
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const e of entries) {
+          if (e.isIntersecting) setActive(e.target.id);
+        }
+      },
+      { rootMargin: "0px 0px -70% 0px", threshold: 0 },
+    );
+    headings.forEach((h) => {
+      const el = document.getElementById(h.slug);
+      if (el) observer.observe(el);
+    });
+    return () => observer.disconnect();
+  }, [headings]);
+
+  if (headings.length === 0) return null;
+  return (
+    <nav aria-label={t("help.toc.title")} className="hidden lg:block">
+      <div className="text-muted-foreground mb-2 text-xs font-semibold tracking-wider uppercase">
+        {t("help.toc.title")}
+      </div>
+      <ul className="space-y-1 text-sm">
+        {headings.map((h) => (
+          <li key={h.slug} style={{ paddingLeft: `${(h.depth - 2) * 0.75}rem` }}>
+            <a
+              href={`#${h.slug}`}
+              className={
+                "block truncate hover:text-foreground " +
+                (active === h.slug ? "text-foreground font-medium" : "text-muted-foreground")
+              }
+            >
+              {h.text}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+}

package/src/features/help/components/__tests__/HelpAskAi.spec.tsx

@@ -0,0 +1,68 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { configureJsonApi } from "../../../../client/config";
+import { HelpProvider } from "../../contexts/HelpContext";
+import { HelpAskAi } from "../HelpAskAi";
+
+vi.mock("../../../user/contexts/CurrentUserContext", () => ({
+  useCurrentUserContext: () => ({ currentUser: (globalThis as any).__mockUser ?? null }),
+}));
+
+// HelpAssistantSheet is intentionally rendered ONLY when logged-in to keep the
+// disabled-state DOM minimal. We mock it to a marker so the test asserts presence.
+vi.mock("../HelpAssistantSheet", () => ({
+  HelpAssistantSheet: ({ open }: { open: boolean }) => (open ? <div data-testid="sheet" /> : null),
+}));
+
+function setupConfig() {
+  configureJsonApi({
+    apiUrl: "http://localhost",
+    helpContent: { brand: { label: "narr8" } },
+  });
+}
+
+describe("HelpAskAi", () => {
+  it("renders a disabled button + tooltip for anonymous users", () => {
+    (globalThis as any).__mockUser = null;
+    setupConfig();
+
+    render(
+      <HelpProvider>
+        <HelpAskAi />
+      </HelpProvider>,
+    );
+
+    const button = screen.getByRole("button");
+    expect(button).toHaveAttribute("disabled");
+    // vitest.setup.ts stubs next-intl's useTranslations to return the key as-is.
+    // The TooltipTrigger renders as a <span>, so the disabled <button> is the
+    // only <button> in the DOM (no nested-button hydration risk).
+    expect(screen.queryByTestId("sheet")).toBeNull();
+  });
+
+  it("clicking the disabled button does not open the sheet", () => {
+    (globalThis as any).__mockUser = null;
+    setupConfig();
+    render(
+      <HelpProvider>
+        <HelpAskAi />
+      </HelpProvider>,
+    );
+    fireEvent.click(screen.getByRole("button"));
+    expect(screen.queryByTestId("sheet")).toBeNull();
+  });
+
+  it("renders an enabled button for logged-in users; clicking opens the sheet", () => {
+    (globalThis as any).__mockUser = { id: "u-1" };
+    setupConfig();
+    render(
+      <HelpProvider>
+        <HelpAskAi />
+      </HelpProvider>,
+    );
+    const button = screen.getByRole("button");
+    expect(button).not.toHaveAttribute("disabled");
+    fireEvent.click(button);
+    expect(screen.getByTestId("sheet")).toBeInTheDocument();
+  });
+});

package/src/features/help/components/__tests__/HelpAssistantSheet.spec.tsx

@@ -0,0 +1,36 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { HelpAssistantSheet } from "../HelpAssistantSheet";
+
+const sendMessage = vi.fn().mockResolvedValue(undefined);
+
+vi.mock("../../../assistant/contexts/AssistantContext", () => ({
+  AssistantProvider: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  useAssistantContext: () => ({
+    assistant: undefined,
+    messages: [],
+    sending: false,
+    status: undefined,
+    failedMessageIds: new Set(),
+    sendMessage,
+    retrySend: vi.fn(),
+  }),
+}));
+
+describe("HelpAssistantSheet", () => {
+  beforeEach(() => sendMessage.mockClear());
+
+  it("submitting the composer calls sendMessage with howToMode: true", async () => {
+    render(<HelpAssistantSheet open={true} onOpenChange={() => {}} />);
+
+    // AssistantEmptyState renders the composer (a textarea + send button).
+    const textarea = screen.getByPlaceholderText("features.assistant.composer_placeholder");
+    fireEvent.change(textarea, { target: { value: "how do scenes work?" } });
+
+    // The empty-state composer's send button is found by its visible text.
+    const sendButton = screen.getByRole("button", { name: /save|send/i });
+    fireEvent.click(sendButton);
+
+    expect(sendMessage).toHaveBeenCalledWith("how do scenes work?", { howToMode: true });
+  });
+});

package/src/features/help/components/__tests__/HelpHint.spec.tsx

@@ -0,0 +1,50 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import { configureJsonApi } from "../../../../client/config";
+import { HelpProvider } from "../../contexts/HelpContext";
+import { HelpHint } from "../HelpHint";
+import { HowToService } from "../../../how-to/data/HowToService";
+
+vi.mock("../../../how-to/data/HowToService", () => ({
+  HowToService: { findPublished: vi.fn() },
+}));
+
+const article = {
+  id: "1",
+  slug: "x",
+  howToType: "how-to",
+  name: "X",
+  summary: "S",
+  contextualKeys: ["npc.editor"],
+  draft: false,
+} as any;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  vi.mocked(HowToService.findPublished).mockResolvedValue([article]);
+  configureJsonApi({
+    apiUrl: "http://localhost",
+    helpContent: { brand: { label: "narr8" } },
+  });
+});
+
+describe("HelpHint", () => {
+  it("renders null when no published article matches the contextKey", async () => {
+    const { container } = render(
+      <HelpProvider>
+        <HelpHint contextKey="nope.absent" />
+      </HelpProvider>,
+    );
+    await waitFor(() => expect(HowToService.findPublished).toHaveBeenCalled());
+    expect(container.querySelector("button")).toBeNull();
+  });
+
+  it("renders the trigger when at least one published article matches", async () => {
+    render(
+      <HelpProvider>
+        <HelpHint contextKey="npc.editor" />
+      </HelpProvider>,
+    );
+    expect(await screen.findByLabelText(/help on this|hint/i)).toBeTruthy();
+  });
+});

package/src/features/help/components/__tests__/HelpSearchResultRow.spec.tsx

@@ -0,0 +1,58 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import { Command, CommandList } from "../../../../shadcnui";
+import { configureJsonApi } from "../../../../client/config";
+import { HelpProvider } from "../../contexts/HelpContext";
+import { HelpSearchResultRow } from "../HelpSearchResultRow";
+import { HowToService } from "../../../how-to/data/HowToService";
+
+vi.mock("../../../how-to/data/HowToService", () => ({
+  HowToService: { findOne: vi.fn() },
+}));
+
+const article = {
+  id: "abc",
+  slug: "x",
+  howToType: "how-to",
+  name: "X title",
+  summary: "S",
+} as any;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  configureJsonApi({
+    apiUrl: "http://localhost",
+    helpContent: { brand: { label: "narr8" } },
+  });
+});
+
+describe("HelpSearchResultRow", () => {
+  it("renders the article title when the service returns the how-to", async () => {
+    vi.mocked(HowToService.findOne).mockResolvedValue(article);
+    render(
+      <HelpProvider>
+        <Command>
+          <CommandList>
+            <HelpSearchResultRow result={{ id: "abc", name: "ignored", entityType: "howtos" }} />
+          </CommandList>
+        </Command>
+      </HelpProvider>,
+    );
+    expect(await screen.findByText("X title")).toBeTruthy();
+  });
+
+  it("renders disabled removed-state row when the service has no how-to", async () => {
+    vi.mocked(HowToService.findOne).mockRejectedValue(new Error("not found"));
+    render(
+      <HelpProvider>
+        <Command>
+          <CommandList>
+            <HelpSearchResultRow result={{ id: "ghost", name: "ignored", entityType: "howtos" }} />
+          </CommandList>
+        </Command>
+      </HelpProvider>,
+    );
+    await waitFor(() => expect(HowToService.findOne).toHaveBeenCalledWith({ id: "ghost" }));
+    expect(screen.queryByText("X title")).toBeNull();
+  });
+});

package/src/features/help/components/__tests__/HelpSideNav.spec.tsx

@@ -0,0 +1,50 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { configureJsonApi } from "../../../../client/config";
+import { HelpProvider } from "../../contexts/HelpContext";
+import { HelpSideNav } from "../HelpSideNav";
+
+// HelpSideNav now sources its list from the public API via
+// HowToService.findPublished() (Plan 3b) instead of the help manifest, so the
+// test mocks the service rather than seeding the manifest.
+vi.mock("../../../how-to/data/HowToService", () => ({
+  HowToService: { findPublished: vi.fn() },
+}));
+import { HowToService } from "../../../how-to/data/HowToService";
+
+const published = [
+  { id: "a", name: "Alpha", summary: "s", tags: [], howToType: "how-to", slug: "a", order: 1, draft: false },
+  { id: "b", name: "Beta", summary: "s", tags: [], howToType: "how-to", slug: "b", order: 2, draft: false },
+];
+
+beforeEach(() => {
+  configureJsonApi({
+    apiUrl: "http://localhost",
+    helpContent: { brand: { label: "narr8" } },
+  });
+  (HowToService.findPublished as ReturnType<typeof vi.fn>).mockResolvedValue(published as any);
+});
+
+describe("HelpSideNav", () => {
+  it("lists every non-draft article", async () => {
+    render(
+      <HelpProvider>
+        <HelpSideNav />
+      </HelpProvider>,
+    );
+    expect(await screen.findByText("Alpha")).toBeTruthy();
+    expect(await screen.findByText("Beta")).toBeTruthy();
+  });
+
+  it("filters by query", async () => {
+    render(
+      <HelpProvider>
+        <HelpSideNav />
+      </HelpProvider>,
+    );
+    await screen.findByText("Alpha");
+    fireEvent.change(screen.getByPlaceholderText(/filter/i), { target: { value: "Bet" } });
+    expect(screen.queryByText("Alpha")).toBeNull();
+    expect(screen.getByText("Beta")).toBeTruthy();
+  });
+});

package/src/features/help/contexts/HelpContext.spec.tsx

@@ -0,0 +1,26 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { ReactNode } from "react";
+import { configureJsonApi } from "../../../client/config";
+import { HelpProvider, useHelp } from "./HelpContext";
+
+describe("HelpProvider / useHelp", () => {
+  const cfg = {
+    brand: { logo: "/logo.png", label: "Test", appHref: "/" },
+  };
+
+  beforeEach(() => {
+    configureJsonApi({ apiUrl: "http://localhost", helpContent: cfg });
+  });
+
+  it("exposes the configured helpContent via useHelp()", () => {
+    const wrapper = ({ children }: { children: ReactNode }) => <HelpProvider>{children}</HelpProvider>;
+    const { result } = renderHook(() => useHelp(), { wrapper });
+    expect(result.current.brand?.label).toBe("Test");
+    expect(result.current.brand?.appHref).toBe("/");
+  });
+
+  it("throws when useHelp() is called outside HelpProvider", () => {
+    expect(() => renderHook(() => useHelp())).toThrow(/outside <HelpProvider>/);
+  });
+});

package/src/features/help/contexts/HelpContext.tsx

@@ -0,0 +1,24 @@
+"use client";
+import { createContext, useContext, ReactNode } from "react";
+import { _getStaticHelpContent } from "../../../core/registry/helpStore";
+import type { HelpContentConfig } from "../interfaces/help-content-config.interface";
+
+const HelpContext = createContext<HelpContentConfig | null>(null);
+
+export function HelpProvider({ children }: { children: ReactNode }) {
+  const cfg = _getStaticHelpContent<HelpContentConfig>();
+  if (!cfg) {
+    throw new Error(
+      "Help content not configured — call configureJsonApi({ helpContent: {...} }) before importing help components.",
+    );
+  }
+  return <HelpContext.Provider value={cfg}>{children}</HelpContext.Provider>;
+}
+
+export function useHelp(): HelpContentConfig {
+  const ctx = useContext(HelpContext);
+  if (!ctx) {
+    throw new Error("useHelp() called outside <HelpProvider>. Wrap your help route group with <HelpProvider>.");
+  }
+  return ctx;
+}

package/src/features/help/hooks/useHelp.ts

@@ -0,0 +1 @@
+export { useHelp } from "../contexts/HelpContext";

package/src/features/help/hooks/useHelpFilter.ts

@@ -0,0 +1,27 @@
+"use client";
+import { useMemo, useState } from "react";
+import Fuse from "fuse.js";
+import type { HelpArticle } from "../types/help-article.types";
+
+export function useHelpFilter(articles: readonly HelpArticle[]) {
+  const [query, setQuery] = useState("");
+  const fuse = useMemo(
+    () =>
+      new Fuse([...articles], {
+        keys: [
+          { name: "title", weight: 0.5 },
+          { name: "summary", weight: 0.3 },
+          { name: "tags", weight: 0.1 },
+          { name: "headings.text", weight: 0.1 },
+        ],
+        threshold: 0.4,
+        ignoreLocation: true,
+      }),
+    [articles],
+  );
+  const filtered = useMemo(() => {
+    if (!query.trim()) return [...articles];
+    return fuse.search(query).map((r) => r.item);
+  }, [query, articles, fuse]);
+  return { query, setQuery, filtered };
+}

package/src/features/help/i18n-keys.ts

@@ -0,0 +1,34 @@
+/**
+ * The fixed namespace of i18n keys this feature reads via useTranslations/getTranslations.
+ * Consuming apps must define each entry in their messages/<locale>.json.
+ */
+export const HELP_I18N_KEYS = [
+  "help.modes.tutorial",
+  "help.modes.how-to",
+  "help.modes.reference",
+  "help.modes.explanation",
+  "help.sideNav.filterPlaceholder",
+  "help.sideNav.noMatches",
+  "help.toc.title",
+  "help.article.lastUpdated",
+  "help.article.previous",
+  "help.article.next",
+  "help.article.related",
+  "help.askAi.button",
+  "help.askAi.loginTooltip",
+  "help.askAi.sheet.title",
+  "help.askAi.sheet.subtitle",
+  "help.header.search",
+  "help.header.login",
+  "help.header.openApp",
+  "help.hint.trigger",
+  "help.hint.viewArticle",
+  "help.hint.pickArticle",
+  "help.landing.heading",
+  "help.landing.subheading",
+  "help.landing.featuredTutorials",
+  "help.landing.browseByMode",
+  "help.modeIndex.empty",
+  "help.search.removed",
+  "help.footerLink",
+] as const;

package/src/features/help/index.ts

@@ -0,0 +1,24 @@
+// Client-only public barrel for the help feature.
+// Consumed via `@carlonicora/nextjs-jsonapi/help`. Tsup adds a top-level
+// "use client" directive to the bundled output via clientEntries.
+//
+// Pair this with `@carlonicora/nextjs-jsonapi/help/server` for the server-safe
+// HELP_MODES constant + article types (imported by server-component pages).
+// Consumers compose page shells themselves: import the client primitives below
+// (HelpProvider, HelpHeader, HelpSideNav, HelpArticleBody, HelpTOC, etc.) and
+// assemble pages in app routes.
+
+export { HelpProvider, useHelp } from "./contexts/HelpContext";
+export { HelpHeader } from "./components/HelpHeader";
+export { HelpSideNav } from "./components/HelpSideNav";
+export { HelpArticleBody } from "./components/HelpArticleBody";
+export { HelpTOC } from "./components/HelpTOC";
+export { HelpHint } from "./components/HelpHint";
+export { HelpAskAi } from "./components/HelpAskAi";
+export { HelpSearchResultRow } from "./components/HelpSearchResultRow";
+export { useHelpFilter } from "./hooks/useHelpFilter";
+export { articleUrl, modeUrl } from "./utils/articleUrl";
+export { HELP_I18N_KEYS } from "./i18n-keys";
+export type { HelpContentConfig, HelpBrandConfig } from "./interfaces/help-content-config.interface";
+export { HELP_MODES } from "./types/help-article.types";
+export type { HelpArticle, HelpHeading, HelpMode, HelpRedirect } from "./types/help-article.types";

package/src/features/help/interfaces/help-content-config.interface.ts

@@ -0,0 +1,12 @@
+export interface HelpBrandConfig {
+  /** URL of the brand logo image (served by the consuming app). */
+  logo?: string;
+  /** Brand label shown in the help header. */
+  label?: string;
+  /** Where the "Open app" button navigates for logged-in users. Defaults to "/". */
+  appHref?: string;
+}
+
+export interface HelpContentConfig {
+  brand?: HelpBrandConfig;
+}

package/src/features/help/server-entry.ts

@@ -0,0 +1,11 @@
+// Server-safe public barrel for the help feature.
+// Consumed via `@carlonicora/nextjs-jsonapi/help/server`. Must NOT receive a
+// "use client" directive — server components (e.g. the /help index + mode pages)
+// import HELP_MODES/HelpMode from here without pulling the client bundle.
+//
+// Now that help articles are served from the API (HowTo) rather than the MDX
+// manifest, this barrel exposes only the shared mode constant + article types.
+// Client primitives live in `@carlonicora/nextjs-jsonapi/help`.
+
+export { HELP_MODES } from "./types/help-article.types";
+export type { HelpArticle, HelpHeading, HelpMode, HelpRedirect } from "./types/help-article.types";

package/src/features/help/types/help-article.types.ts

@@ -0,0 +1,35 @@
+/**
+ * Help-article types for the frontend help feature. Self-contained — the
+ * published frontend library stays decoupled from `@carlonicora/nestjs-neo4jsonapi`.
+ */
+
+export const HELP_MODES = ["tutorial", "how-to", "reference", "explanation"] as const;
+export type HelpMode = (typeof HELP_MODES)[number];
+
+export interface HelpHeading {
+  depth: 2 | 3;
+  slug: string;
+  text: string;
+}
+
+export interface HelpArticle {
+  id: string;
+  slug: string;
+  mode: HelpMode;
+  title: string;
+  summary: string;
+  order: number;
+  tags: readonly string[];
+  contextualKeys: readonly string[];
+  aiIndexed: boolean;
+  draft: boolean;
+  path: string;
+  headings: readonly HelpHeading[];
+  relatedSlugs: readonly string[];
+  lastUpdated: string;
+}
+
+export interface HelpRedirect {
+  from: string;
+  to: string;
+}

package/src/features/help/utils/articleUrl.ts

@@ -0,0 +1,13 @@
+import type { HelpMode } from "../types/help-article.types";
+import type { usePageUrlGenerator } from "../../../client";
+
+export function articleUrl(
+  generateUrl: ReturnType<typeof usePageUrlGenerator>,
+  article: { mode: HelpMode; slug: string },
+): string {
+  return generateUrl({ page: `/help/${article.mode}/${article.slug}` });
+}
+
+export function modeUrl(generateUrl: ReturnType<typeof usePageUrlGenerator>, mode: HelpMode): string {
+  return generateUrl({ page: `/help/${mode}` });
+}

package/src/features/how-to/HowToModule.ts

@@ -12,7 +12,20 @@ export const HowToModule = (factory: ModuleFactory) =>
     icon: LifeBuoyIcon,
     inclusions: {
       lists: {
-        fields: [createJsonApiInclusion("howtos", [`name`, `description`, `pages`])],
+        fields: [
+          createJsonApiInclusion("howtos", [
+            "name",
+            "description",
+            "pages",
+            "howToType",
+            "slug",
+            "order",
+            "summary",
+            "tags",
+            "contextualKeys",
+            "draft",
+          ]),
+        ],
       },
     },
   });