@carlonicora/nextjs-jsonapi 1.108.0 → 1.110.0

package/src/features/assistant/data/AssistantService.ts

@@ -1,6 +1,7 @@
 import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
-import { AssistantInput, AssistantInterface } from "./AssistantInterface";
+import { AssistantMessage } from "../../assistant-message/data/AssistantMessage";
 import { AssistantMessageInterface } from "../../assistant-message/data/AssistantMessageInterface";
+import { AssistantInput, AssistantInterface } from "./AssistantInterface";
 
 export class AssistantService extends AbstractService {
   static async findOne(params: { id: string }): Promise<AssistantInterface> {
@@ -33,8 +34,18 @@ export class AssistantService extends AbstractService {
   /**
    * Sends a new user message to an existing assistant thread. The agent turn
    * runs synchronously; the response is a two-element list: [user, assistant].
+   *
+   * Uses the dedicated AssistantMessage.createAppendMessageJsonApi method to
+   * build the JSON:API envelope; this is the architecture-compliant pairing
+   * with `overridesJsonApiCreation: true`.
    */
-  static async appendMessage(params: { assistantId: string; content: string }): Promise<AssistantMessageInterface[]> {
+  static async appendMessage(params: {
+    assistantId: string;
+    content: string;
+    howToMode?: boolean;
+    limitToHowToId?: string;
+  }): Promise<AssistantMessageInterface[]> {
+    const message = new AssistantMessage();
     return this.callApi<AssistantMessageInterface[]>({
       type: Modules.AssistantMessage,
       method: HttpMethod.POST,
@@ -43,12 +54,11 @@ export class AssistantService extends AbstractService {
         id: params.assistantId,
         childEndpoint: Modules.AssistantMessage,
       }).generate(),
-      input: {
-        data: {
-          type: Modules.AssistantMessage.name,
-          attributes: { content: params.content },
-        },
-      },
+      input: message.createAppendMessageJsonApi({
+        content: params.content,
+        howToMode: params.howToMode,
+        limitToHowToId: params.limitToHowToId,
+      }),
       overridesJsonApiCreation: true,
     });
   }

package/src/features/assistant-message/components/parts/MessageSourcesContainer.tsx

@@ -20,6 +20,10 @@ class SourcesFetcher extends ClientAbstractService {
   }): Promise<ApiDataInterface[]> {
     const endpoint = new EndpointCreator({ endpoint: params.module });
     endpoint.addAdditionalParam(params.idsParam, params.ids.join(","));
+    // The list endpoint paginates and does not honour the `<x>Ids` filter, so a cited
+    // entity beyond the default first page never comes back and its citation falls back
+    // to "<Type> <id>". Request the full set and resolve client-side by id.
+    endpoint.addAdditionalParam("fetchAll", "true");
     if (params.module.inclusions?.lists?.fields) endpoint.limitToFields(params.module.inclusions.lists.fields);
     if (params.module.inclusions?.lists?.types) endpoint.limitToType(params.module.inclusions.lists.types);
     return this.callApi<ApiDataInterface[]>({

package/src/features/assistant-message/components/parts/MessageSourcesPanel.tsx

@@ -55,12 +55,14 @@ export function MessageSourcesPanel({ message, isLatestAssistant, onSelectFollow
   const suggestionsCount = isLatestAssistant ? message.suggestedQuestions.length : 0;
 
   const contentsCount = useMemo(() => {
-    if (sources) return sources.size;
-    // Fallback: derive from unique nodeId on chunks when sources haven't been
-    // supplied yet (e.g., during the initial fetch).
+    // Count unique nodeIds across citations. Mirrors what ContentsTab actually
+    // renders (one row per cited source), instead of `sources.size` which can
+    // include entities the fetch returned but no citation references.
     const ids = new Set<string>();
     for (const c of message.citations) {
-      if (c.nodeId) ids.add(c.nodeId);
+      if (!c.nodeId) continue;
+      if (sources && !sources.has(c.nodeId)) continue;
+      ids.add(c.nodeId);
     }
     return ids.size;
   }, [message.citations, sources]);

package/src/features/assistant-message/components/parts/tabs/ContentsTab.tsx

@@ -64,7 +64,11 @@ export function ContentsTab({ citations, sources }: Props) {
           } catch {
             return null;
           }
-          const href = generate({ page: module, id: source.id });
+          // Help HowTos are public articles, not admin records: route to
+          // /help/<mode>/<slug> instead of the module's /administration/howtos page.
+          const howToType = (source as any).howToType as string | undefined;
+          const slug = (source as any).slug as string | undefined;
+          const href = howToType && slug ? `/help/${howToType}/${slug}` : generate({ page: module, id: source.id });
           const name = (source as any).name ?? source.identifier;
           return (
             <TableRow key={`${source.type}/${source.id}`}>

package/src/features/assistant-message/components/parts/tabs/ReferencesTab.tsx

@@ -33,7 +33,9 @@ export function ReferencesTab({ references }: Props) {
           } catch {
             return null;
           }
-          const href = generate({ page: module, id: ref.id });
+          const howToType = (ref as any).howToType as string | undefined;
+          const slug = (ref as any).slug as string | undefined;
+          const href = howToType && slug ? `/help/${howToType}/${slug}` : generate({ page: module, id: ref.id });
           return (
             <TableRow key={`${ref.type}/${ref.id}`}>
               <TableCell>

package/src/features/assistant-message/data/AssistantMessage.ts

@@ -1,3 +1,4 @@
+import { v4 as uuidv4 } from "uuid";
 import { AbstractApiData, ApiDataInterface, JsonApiHydratedDataInterface, Modules } from "../../../core";
 import { AssistantMessageInput, AssistantMessageInterface, AssistantMessageRole } from "./AssistantMessageInterface";
 import { resolveReferenceableModules } from "../../assistant/utils/resolveReferenceableModules";
@@ -12,6 +13,7 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
   private _outputTokens?: number;
   private _references?: ApiDataInterface[];
   private _citations?: (ChunkInterface & ChunkRelationshipMeta)[];
+  private _isOptimistic = false;
 
   get role(): AssistantMessageRole {
     return this._role ?? "assistant";
@@ -45,6 +47,10 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
     return this._citations ?? [];
   }
 
+  get isOptimistic(): boolean {
+    return this._isOptimistic;
+  }
+
   rehydrate(data: JsonApiHydratedDataInterface): this {
     super.rehydrate(data);
     const attrs = data.jsonApi.attributes ?? {};
@@ -93,10 +99,29 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
     };
   }
 
+  /**
+   * JSON:API envelope for POST /assistants/:id/assistant-messages.
+   * Different from `createJsonApi` (which expects a full message with role/position/assistant ref);
+   * the append-to-thread endpoint derives those server-side, so we only send `content` and
+   * the optional retrieval-mode flags.
+   */
+  createAppendMessageJsonApi(params: { content: string; howToMode?: boolean; limitToHowToId?: string }) {
+    return {
+      data: {
+        type: Modules.AssistantMessage.name,
+        attributes: {
+          content: params.content,
+          ...(params.howToMode !== undefined ? { howToMode: params.howToMode } : {}),
+          ...(params.limitToHowToId !== undefined ? { limitToHowToId: params.limitToHowToId } : {}),
+        },
+      },
+    };
+  }
+
   static buildOptimistic(params: { content: string; position: number; assistantId?: string }): AssistantMessage {
     const msg = new AssistantMessage();
     const jsonApi: Record<string, unknown> = {
-      id: `tmp-${crypto.randomUUID()}`,
+      id: uuidv4(),
       type: Modules.AssistantMessage.name,
       attributes: {
         role: "user",
@@ -110,6 +135,7 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
       };
     }
     msg.rehydrate({ jsonApi: jsonApi as any, included: [] });
+    msg._isOptimistic = true;
     return msg;
   }
 }

package/src/features/assistant-message/data/AssistantMessageInterface.ts

@@ -20,4 +20,5 @@ export interface AssistantMessageInterface extends ApiDataInterface {
   get outputTokens(): number | undefined;
   get references(): ApiDataInterface[];
   get citations(): (ChunkInterface & ChunkRelationshipMeta)[];
+  get isOptimistic(): boolean;
 }

package/src/features/assistant-message/data/__tests__/AssistantMessage.spec.ts

@@ -136,14 +136,17 @@ describe("AssistantMessage.rehydrate", () => {
 });
 
 describe("AssistantMessage.buildOptimistic", () => {
-  it("creates a user message with a tmp-prefixed id and the given content + position", () => {
+  const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+  it("creates a user message with a plain UUID id and the given content + position", () => {
     const msg = AssistantMessage.buildOptimistic({
       content: "hello",
       assistantId: "a-1",
       position: 3,
     });
 
-    expect(msg.id.startsWith("tmp-")).toBe(true);
+    expect(msg.id).toMatch(UUID_RE);
+    expect(msg.isOptimistic).toBe(true);
     expect(msg.role).toBe("user");
     expect(msg.content).toBe("hello");
     expect(msg.position).toBe(3);
@@ -152,7 +155,8 @@ describe("AssistantMessage.buildOptimistic", () => {
   it("allows an omitted assistantId (first-message case)", () => {
     const msg = AssistantMessage.buildOptimistic({ content: "first", position: 1 });
 
-    expect(msg.id.startsWith("tmp-")).toBe(true);
+    expect(msg.id).toMatch(UUID_RE);
+    expect(msg.isOptimistic).toBe(true);
     expect(msg.role).toBe("user");
     expect(msg.content).toBe("first");
     expect(msg.position).toBe(1);

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

@@ -0,0 +1,62 @@
+"use client";
+
+import { ReactNode } from "react";
+import Link from "next/link";
+import { useFormatter, useTranslations } from "next-intl";
+import { usePageUrlGenerator } from "../../../client";
+
+type Sibling = { howToType: string; slug: string; title: string };
+
+export function HelpArticleBody(props: {
+  howToType: string;
+  title: string;
+  summary?: string;
+  updatedAt?: string;
+  prev?: Sibling | null;
+  next?: Sibling | null;
+  children: ReactNode;
+}) {
+  const t = useTranslations();
+  const format = useFormatter();
+  const generateUrl = usePageUrlGenerator();
+  const { howToType, title, summary, updatedAt, prev, next, children } = props;
+
+  return (
+    <article className="prose dark:prose-invert max-w-none">
+      <nav className="text-muted-foreground mb-2 text-xs">
+        <Link href={generateUrl({ page: "/help" })}>Help</Link>
+        {" · "}
+        <Link href={generateUrl({ page: `/help/${howToType}` })}>{t(`help.modes.${howToType}`)}</Link>
+      </nav>
+      <h1>{title}</h1>
+      {summary ? <p className="text-muted-foreground !mt-0 text-base">{summary}</p> : null}
+      {children}
+      <hr className="my-6" />
+      {updatedAt ? (
+        <div className="text-muted-foreground text-xs">
+          <span>
+            {t("help.article.lastUpdated", {
+              date: format.dateTime(new Date(updatedAt), { dateStyle: "short" }),
+            })}
+          </span>
+        </div>
+      ) : null}
+      <div className="mt-4 flex justify-between text-sm">
+        {prev ? (
+          <Link href={generateUrl({ page: `/help/${prev.howToType}/${prev.slug}` })} className="hover:underline">
+            ← {t("help.article.previous")}: {prev.title}
+          </Link>
+        ) : (
+          <span />
+        )}
+        {next ? (
+          <Link href={generateUrl({ page: `/help/${next.howToType}/${next.slug}` })} className="hover:underline">
+            {t("help.article.next")}: {next.title} →
+          </Link>
+        ) : (
+          <span />
+        )}
+      </div>
+    </article>
+  );
+}

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

@@ -0,0 +1,36 @@
+"use client";
+import { useState } from "react";
+import { SparklesIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useCurrentUserContext } from "../../user/contexts/CurrentUserContext";
+import { Button, Tooltip, TooltipTrigger, TooltipContent } from "../../../shadcnui";
+import { HelpAssistantSheet } from "./HelpAssistantSheet";
+
+export function HelpAskAi() {
+  const t = useTranslations();
+  const { currentUser } = useCurrentUserContext();
+  const [open, setOpen] = useState(false);
+  const disabled = !currentUser;
+
+  if (disabled) {
+    return (
+      <Tooltip>
+        <TooltipTrigger render={<Button variant="outline" size="sm" disabled />}>
+          <SparklesIcon className="h-4 w-4" />
+          {t("help.askAi.button")}
+        </TooltipTrigger>
+        <TooltipContent>{t("help.askAi.loginTooltip")}</TooltipContent>
+      </Tooltip>
+    );
+  }
+
+  return (
+    <>
+      <Button variant="outline" size="sm" onClick={() => setOpen(true)}>
+        <SparklesIcon className="h-4 w-4" />
+        {t("help.askAi.button")}
+      </Button>
+      <HelpAssistantSheet open={open} onOpenChange={setOpen} />
+    </>
+  );
+}

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

@@ -0,0 +1,53 @@
+"use client";
+import { useTranslations } from "next-intl";
+import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetDescription } from "../../../shadcnui";
+import { AssistantProvider, useAssistantContext } from "../../assistant/contexts/AssistantContext";
+import { AssistantThread } from "../../assistant/components/parts/AssistantThread";
+import { AssistantComposer } from "../../assistant/components/parts/AssistantComposer";
+import { AssistantEmptyState } from "../../assistant/components/parts/AssistantEmptyState";
+
+export function HelpAssistantSheet({ open, onOpenChange }: { open: boolean; onOpenChange: (o: boolean) => void }) {
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent
+        side="right"
+        className="flex w-full flex-col data-[side=right]:sm:max-w-2xl data-[side=right]:lg:max-w-3xl"
+      >
+        <AssistantProvider manageUrl={false}>
+          <HelpAssistantSheetBody />
+        </AssistantProvider>
+      </SheetContent>
+    </Sheet>
+  );
+}
+
+function HelpAssistantSheetBody() {
+  const t = useTranslations();
+  const ctx = useAssistantContext();
+  const showThread = !!ctx.assistant || ctx.sending || ctx.messages.length > 0;
+  const send = (content: string) => ctx.sendMessage(content, { howToMode: true });
+
+  return (
+    <>
+      <SheetHeader>
+        <SheetTitle>{t("help.askAi.sheet.title")}</SheetTitle>
+        <SheetDescription>{t("help.askAi.sheet.subtitle")}</SheetDescription>
+      </SheetHeader>
+      {!showThread ? (
+        <AssistantEmptyState onSend={send} />
+      ) : (
+        <>
+          <AssistantThread
+            messages={ctx.messages}
+            sending={ctx.sending}
+            status={ctx.status}
+            onSelectFollowUp={send}
+            failedMessageIds={ctx.failedMessageIds}
+            onRetry={ctx.retrySend}
+          />
+          <AssistantComposer onSend={send} disabled={ctx.sending} />
+        </>
+      )}
+    </>
+  );
+}

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

@@ -0,0 +1,40 @@
+"use client";
+import Link from "next/link";
+import Image from "next/image";
+import { useTranslations } from "next-intl";
+import { useCurrentUserContext } from "../../user/contexts/CurrentUserContext";
+import { Button } from "../../../shadcnui";
+import { useHelp } from "../contexts/HelpContext";
+import { HelpAskAi } from "./HelpAskAi";
+
+export function HelpHeader() {
+  const t = useTranslations();
+  const { currentUser } = useCurrentUserContext();
+  const { brand } = useHelp();
+  const logo = brand?.logo;
+  const label = brand?.label ?? "Help";
+  const appHref = brand?.appHref ?? "/";
+
+  return (
+    <header className="border-border bg-background flex items-center justify-between border-b px-4 py-3">
+      <Link href="/help" className="flex items-center gap-2">
+        {logo ? <Image src={logo} alt={label} width={28} height={28} /> : null}
+        <span className="text-base font-semibold">
+          {label} · {t("help.footerLink")}
+        </span>
+      </Link>
+      <div className="flex items-center gap-2">
+        <HelpAskAi />
+        {currentUser ? (
+          <Button render={<Link href={appHref} />} nativeButton={false} variant="outline" size="sm">
+            {t("help.header.openApp")}
+          </Button>
+        ) : (
+          <Button render={<Link href="/login" />} nativeButton={false} variant="outline" size="sm">
+            {t("help.header.login")}
+          </Button>
+        )}
+      </div>
+    </header>
+  );
+}

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

@@ -0,0 +1,86 @@
+"use client";
+import { useEffect, useMemo, useState } from "react";
+import { useTranslations } from "next-intl";
+import Link from "next/link";
+import { HelpCircleIcon } from "lucide-react";
+import {
+  Button,
+  Sheet,
+  SheetContent,
+  SheetTrigger,
+  SheetHeader,
+  SheetTitle,
+  SheetDescription,
+} from "../../../shadcnui";
+import { usePageUrlGenerator } from "../../../client";
+import { HowToService } from "../../how-to/data/HowToService";
+import type { HowToInterface } from "../../how-to/data/HowToInterface";
+
+export function HelpHint({ contextKey }: { contextKey: string }) {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+  const [open, setOpen] = useState(false);
+  const [picked, setPicked] = useState<HowToInterface | null>(null);
+
+  const [articles, setArticles] = useState<HowToInterface[]>([]);
+  useEffect(() => {
+    let active = true;
+    HowToService.findPublished()
+      .then((list) => active && setArticles(list))
+      .catch(() => active && setArticles([]));
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  const matches = useMemo(
+    () => articles.filter((a) => a.contextualKeys.includes(contextKey) && !a.draft),
+    [articles, contextKey],
+  );
+
+  if (matches.length === 0) return null;
+  const active = picked ?? (matches.length === 1 ? matches[0] : null);
+
+  return (
+    <Sheet
+      open={open}
+      onOpenChange={(o) => {
+        setOpen(o);
+        if (!o) setPicked(null);
+      }}
+    >
+      <SheetTrigger render={<Button variant="ghost" size="icon-sm" aria-label={t("help.hint.trigger")} />}>
+        <HelpCircleIcon className="h-4 w-4" />
+      </SheetTrigger>
+      <SheetContent side="right" className="w-full max-w-md sm:max-w-lg">
+        <SheetHeader>
+          <SheetTitle>{active ? active.name : t("help.hint.pickArticle")}</SheetTitle>
+          <SheetDescription>{active?.summary ?? ""}</SheetDescription>
+        </SheetHeader>
+        {active ? (
+          <div className="mt-4 space-y-3">
+            <p className="text-muted-foreground text-sm">{active.summary}</p>
+            <Link href={generateUrl({ page: `/help/${active.howToType}/${active.slug}` })} className="text-sm">
+              {t("help.hint.viewArticle")}
+            </Link>
+          </div>
+        ) : (
+          <ul className="mt-4 space-y-1">
+            {matches.map((a) => (
+              <li key={a.id}>
+                <button
+                  type="button"
+                  onClick={() => setPicked(a)}
+                  className="hover:bg-muted block w-full rounded px-2 py-1 text-left text-sm"
+                >
+                  <div className="font-medium">{a.name}</div>
+                  <div className="text-muted-foreground text-xs">{a.summary}</div>
+                </button>
+              </li>
+            ))}
+          </ul>
+        )}
+      </SheetContent>
+    </Sheet>
+  );
+}

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

@@ -0,0 +1,61 @@
+"use client";
+import Link from "next/link";
+import { useTranslations } from "next-intl";
+import { useEffect, useState } from "react";
+import { LifeBuoyIcon, ArrowUpRightIcon } from "lucide-react";
+import { CommandItem } from "../../../shadcnui";
+import { usePageUrlGenerator } from "../../../client";
+import { HowToService } from "../../how-to/data/HowToService";
+import type { HowToInterface } from "../../how-to/data/HowToInterface";
+
+export interface HelpSearchResultRowProps {
+  result: { id: string; name: string; entityType: string };
+  onSelect?: () => void;
+}
+
+export function HelpSearchResultRow({ result, onSelect }: HelpSearchResultRowProps) {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+  const [article, setArticle] = useState<HowToInterface | null>(null);
+  useEffect(() => {
+    let active = true;
+    HowToService.findOne({ id: result.id })
+      .then((a) => active && setArticle(a))
+      .catch(() => active && setArticle(null));
+    return () => {
+      active = false;
+    };
+  }, [result.id]);
+
+  if (!article) {
+    return (
+      <CommandItem
+        value={result.id}
+        disabled
+        className="text-muted-foreground cursor-not-allowed px-3 py-1.5 text-sm italic"
+      >
+        {t("help.search.removed")}
+      </CommandItem>
+    );
+  }
+
+  return (
+    <CommandItem value={result.id} onSelect={onSelect} className="cursor-pointer p-0">
+      <Link
+        href={generateUrl({ page: `/help/${article.howToType}/${article.slug}` })}
+        className="hover:bg-muted flex w-full items-center gap-3 rounded px-3 py-2"
+      >
+        <div className="bg-muted text-muted-foreground flex h-10 w-10 shrink-0 items-center justify-center rounded-full">
+          <LifeBuoyIcon className="h-5 w-5" />
+        </div>
+        <div className="flex min-w-0 flex-1 flex-col">
+          <span className="text-foreground truncate text-sm font-semibold">{article.name}</span>
+          <span className="text-muted-foreground truncate text-xs">
+            {t(`help.modes.${article.howToType}`)} · {article.summary}
+          </span>
+        </div>
+        <ArrowUpRightIcon className="text-muted-foreground h-5 w-5 shrink-0" />
+      </Link>
+    </CommandItem>
+  );
+}

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

@@ -0,0 +1,119 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import { useTranslations } from "next-intl";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { HELP_MODES } from "../types/help-article.types";
+import { usePageUrlGenerator } from "../../../client";
+import { useHelpFilter } from "../hooks/useHelpFilter";
+import { HowToService } from "../../how-to/data/HowToService";
+import type { HowToInterface } from "../../how-to/data/HowToInterface";
+
+export function HelpSideNav() {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+  const pathname = usePathname();
+  const [articles, setArticles] = useState<HowToInterface[]>([]);
+
+  useEffect(() => {
+    let active = true;
+    HowToService.findPublished()
+      .then((list) => active && setArticles(list))
+      .catch(() => active && setArticles([]));
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  // useHelpFilter indexes by title/summary/tags — map HowTo getters into the shape it expects.
+  const indexable = useMemo(
+    () =>
+      articles.map((a) => ({
+        id: a.id,
+        title: a.name,
+        summary: a.summary ?? "",
+        tags: a.tags,
+        mode: a.howToType ?? "",
+        slug: a.slug ?? "",
+      })),
+    [articles],
+  );
+  const { query, setQuery, filtered } = useHelpFilter(indexable as any);
+  const filtering = query.trim().length > 0;
+
+  const groups = useMemo(
+    () =>
+      HELP_MODES.map((mode) => ({
+        mode,
+        articles: articles
+          .filter((a) => a.howToType === mode && !a.draft)
+          .sort((x, y) => (x.order ?? 0) - (y.order ?? 0)),
+      })),
+    [articles],
+  );
+
+  const isActive = (mode: string, slug: string) => pathname.endsWith(`/help/${mode}/${slug}`);
+
+  return (
+    <nav aria-label="Help navigation" className="flex h-full flex-col gap-3 overflow-y-auto p-4">
+      <input
+        type="search"
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        placeholder={t("help.sideNav.filterPlaceholder")}
+        className="border-input bg-background w-full rounded-md border px-3 py-2 text-sm"
+      />
+      {filtering ? (
+        (filtered as any[]).length === 0 ? (
+          <p className="text-muted-foreground text-sm">{t("help.sideNav.noMatches")}</p>
+        ) : (
+          <ul className="space-y-1">
+            {(filtered as any[]).map((a) => (
+              <li key={a.id}>
+                <Link
+                  href={generateUrl({ page: `/help/${a.mode}/${a.slug}` })}
+                  className={
+                    "hover:bg-muted block rounded px-2 py-1 text-sm " +
+                    (isActive(a.mode, a.slug) ? "bg-muted font-medium" : "")
+                  }
+                >
+                  {a.title}
+                </Link>
+              </li>
+            ))}
+          </ul>
+        )
+      ) : (
+        groups.map((group) => {
+          if (group.articles.length === 0) return null;
+          return (
+            <div key={group.mode}>
+              <Link
+                href={generateUrl({ page: `/help/${group.mode}` })}
+                className="text-muted-foreground hover:text-foreground mb-1 block text-xs font-semibold tracking-wider uppercase"
+              >
+                {t(`help.modes.${group.mode}`)}
+              </Link>
+              <ul className="space-y-0.5">
+                {group.articles.map((a) => (
+                  <li key={a.id}>
+                    <Link
+                      href={generateUrl({ page: `/help/${a.howToType}/${a.slug}` })}
+                      className={
+                        "hover:bg-muted block rounded px-2 py-1 text-sm " +
+                        (isActive(a.howToType ?? "", a.slug ?? "") ? "bg-muted font-medium" : "")
+                      }
+                    >
+                      {a.name}
+                    </Link>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          );
+        })
+      )}
+    </nav>
+  );
+}