@carlonicora/nextjs-jsonapi 1.68.0 → 1.70.0

package/dist/server/index.d.ts

@@ -1,13 +1,12 @@
 import { A as ApiData } from '../ApiData-DPKNfY-9.js';
-import { M as ModuleWithPermissions, A as Action } from '../notification.interface-ItBxq2au.js';
+import { M as ModuleWithPermissions, A as Action } from '../notification.interface-DYDZENx2.js';
 import { A as ApiRequestDataTypeInterface } from '../ApiRequestDataTypeInterface-CYEcRUrh.js';
 import { A as ApiResponseInterface } from '../ApiResponseInterface-CAIAeP5d.js';
-export { A as ServerAuthService, C as ServerCompanyService, a as ServerContentService, F as ServerFeatureService, N as ServerNotificationService, P as ServerPushService, R as ServerRoleService, S as ServerS3Service, U as ServerUserService } from '../s3.service-N1g0piXD.js';
+export { A as ServerAuthService, C as ServerCompanyService, a as ServerContentService, F as ServerFeatureService, N as ServerNotificationService, P as ServerPushService, R as ServerRoleService, S as ServerS3Service, U as ServerUserService } from '../s3.service-DK2KKXbR.js';
 import 'lucide-react';
 import '../ApiDataInterface-DPP8s46n.js';
 import '../feature.interface-CIWxo8NP.js';
-import '../auth.interface-BX_1qZZJ.js';
-import '../content.interface-D-xdYxjt.js';
+import '../auth.interface-BTco8PWs.js';
 
 type CacheProfile = "seconds" | "minutes" | "hours" | "days" | "weeks" | "max" | "default";
 /**

package/dist/server/index.js

@@ -15,7 +15,7 @@ var _chunk3ZPK4QOBjs = require('../chunk-3ZPK4QOB.js');
 
 
 
-var _chunk37KYO2UDjs = require('../chunk-37KYO2UD.js');
+var _chunk56VU7A4Ijs = require('../chunk-56VU7A4I.js');
 require('../chunk-LXKSUWAV.js');
 require('../chunk-IBS6NI7D.js');
 
@@ -86,7 +86,7 @@ var ServerSession = class {
     if (!rawModules) return false;
     const modules = JSON.parse(_pako2.default.ungzip(Buffer.from(rawModules, "base64"), { to: "string" }));
     const selectedModule = modules.find((module) => module.id === params.module.moduleId);
-    return _chunk37KYO2UDjs.checkPermissionsFromServer.call(void 0, {
+    return _chunk56VU7A4Ijs.checkPermissionsFromServer.call(void 0, {
       module: params.module,
       action: params.action,
       data: params.data,
@@ -296,5 +296,5 @@ _chunk7QVYU63Ejs.__name.call(void 0, ServerJsonApiDelete, "ServerJsonApiDelete")
 
 
 
-exports.ServerAuthService = _chunk37KYO2UDjs.AuthService; exports.ServerCompanyService = _chunk37KYO2UDjs.CompanyService; exports.ServerContentService = _chunk37KYO2UDjs.ContentService; exports.ServerFeatureService = _chunk37KYO2UDjs.FeatureService; exports.ServerJsonApiDelete = ServerJsonApiDelete; exports.ServerJsonApiGet = ServerJsonApiGet; exports.ServerJsonApiPatch = ServerJsonApiPatch; exports.ServerJsonApiPost = ServerJsonApiPost; exports.ServerJsonApiPut = ServerJsonApiPut; exports.ServerNotificationService = _chunk37KYO2UDjs.NotificationService; exports.ServerPushService = _chunk37KYO2UDjs.PushService; exports.ServerRoleService = _chunk37KYO2UDjs.RoleService; exports.ServerS3Service = _chunk37KYO2UDjs.S3Service; exports.ServerSession = ServerSession; exports.ServerUserService = _chunk37KYO2UDjs.UserService; exports.configureServerJsonApi = configureServerJsonApi; exports.getServerApiUrl = getServerApiUrl; exports.getServerAppUrl = getServerAppUrl; exports.getServerToken = _chunkYUO55Q5Ajs.getServerToken; exports.getServerTrackablePages = getServerTrackablePages; exports.invalidateCacheTag = invalidateCacheTag; exports.invalidateCacheTags = invalidateCacheTags; exports.serverRequest = _chunk3ZPK4QOBjs.serverRequest;
+exports.ServerAuthService = _chunk56VU7A4Ijs.AuthService; exports.ServerCompanyService = _chunk56VU7A4Ijs.CompanyService; exports.ServerContentService = _chunk56VU7A4Ijs.ContentService; exports.ServerFeatureService = _chunk56VU7A4Ijs.FeatureService; exports.ServerJsonApiDelete = ServerJsonApiDelete; exports.ServerJsonApiGet = ServerJsonApiGet; exports.ServerJsonApiPatch = ServerJsonApiPatch; exports.ServerJsonApiPost = ServerJsonApiPost; exports.ServerJsonApiPut = ServerJsonApiPut; exports.ServerNotificationService = _chunk56VU7A4Ijs.NotificationService; exports.ServerPushService = _chunk56VU7A4Ijs.PushService; exports.ServerRoleService = _chunk56VU7A4Ijs.RoleService; exports.ServerS3Service = _chunk56VU7A4Ijs.S3Service; exports.ServerSession = ServerSession; exports.ServerUserService = _chunk56VU7A4Ijs.UserService; exports.configureServerJsonApi = configureServerJsonApi; exports.getServerApiUrl = getServerApiUrl; exports.getServerAppUrl = getServerAppUrl; exports.getServerToken = _chunkYUO55Q5Ajs.getServerToken; exports.getServerTrackablePages = getServerTrackablePages; exports.invalidateCacheTag = invalidateCacheTag; exports.invalidateCacheTags = invalidateCacheTags; exports.serverRequest = _chunk3ZPK4QOBjs.serverRequest;
 //# sourceMappingURL=index.js.map

package/dist/server/index.mjs

@@ -15,7 +15,7 @@ import {
   S3Service,
   UserService,
   checkPermissionsFromServer
-} from "../chunk-IOMDNRX5.mjs";
+} from "../chunk-GZNHBAZF.mjs";
 import "../chunk-AUXK7QSA.mjs";
 import "../chunk-C7C7VY4F.mjs";
 import {

package/dist/{useRbacState-CUj0hp8t.d.ts → useRbacState-BYaSdA78.d.ts}

@@ -1,5 +1,5 @@
 import { F as FeatureInterface } from './feature.interface-CIWxo8NP.js';
-import { R as RoleInterface } from './notification.interface-ItBxq2au.js';
+import { R as RoleInterface } from './notification.interface-DYDZENx2.js';
 import { P as PermissionMappingInterface, M as ModulePathsInterface, A as ActionType, a as PermissionValue, b as PermissionsMap } from './ModulePathsInterface-wVS5Raa4.js';
 
 type PageInfo = {

package/dist/{useRbacState-Btk1gkQg.d.mts → useRbacState-CQEJ_ysV.d.mts}

@@ -1,5 +1,5 @@
 import { F as FeatureInterface } from './feature.interface-BxFFOPNq.mjs';
-import { R as RoleInterface } from './notification.interface-C6UcmJqu.mjs';
+import { R as RoleInterface } from './notification.interface-DrHu_1MM.mjs';
 import { P as PermissionMappingInterface, M as ModulePathsInterface, A as ActionType, a as PermissionValue, b as PermissionsMap } from './ModulePathsInterface-49EWvbWy.mjs';
 
 type PageInfo = {

package/dist/{useSocket-BSUN9s3p.d.ts → useSocket-Cjt_qvkI.d.ts}

@@ -1,4 +1,4 @@
-import { N as NotificationInterface } from './notification.interface-ItBxq2au.js';
+import { N as NotificationInterface } from './notification.interface-DYDZENx2.js';
 
 interface UseSocketOptions {
     token: string;

package/dist/{useSocket-DKI92Fbg.d.mts → useSocket-VAGetcT3.d.mts}

@@ -1,4 +1,4 @@
-import { N as NotificationInterface } from './notification.interface-C6UcmJqu.mjs';
+import { N as NotificationInterface } from './notification.interface-DrHu_1MM.mjs';
 
 interface UseSocketOptions {
     token: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "1.68.0",
+  "version": "1.70.0",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",

package/src/components/editors/BlockNoteEditor.tsx

@@ -27,6 +27,8 @@ export type BlockNoteEditorProps = {
   diffContent?: PartialBlock[];
   placeholder?: string;
   bordered?: boolean;
+  inlineContentSpecs?: Record<string, any>;
+  renderOverlays?: (editor: any) => React.ReactNode;
 };
 
 const createDiffActionsInlineContentSpec = (
@@ -88,6 +90,8 @@ export default function BlockNoteEditor({
   diffContent,
   placeholder,
   bordered,
+  inlineContentSpecs,
+  renderOverlays,
 }: BlockNoteEditorProps): React.JSX.Element {
   const t = useTranslations();
   const { company } = useCurrentUserContext<UserInterface>();
@@ -141,9 +145,10 @@ export default function BlockNoteEditor({
         inlineContentSpecs: {
           ...defaultInlineContentSpecs,
           diffActions: DiffActionsInlineContent,
+          ...inlineContentSpecs,
         },
       } as any),
-    [DiffActionsInlineContent],
+    [DiffActionsInlineContent, inlineContentSpecs],
   );
 
   const uploadImage = useCallback(
@@ -422,6 +427,7 @@ export default function BlockNoteEditor({
         className={cn(`BlockNoteView flex-1 ${onChange ? "p-4" : ""}`, size === "sm" && "small")}
       >
         <BlockNoteEditorFormattingToolbar />
+        {renderOverlays?.(editor)}
       </BlockNoteView>
     </div>
   );

package/src/components/forms/FormBlockNote.tsx

@@ -14,6 +14,8 @@ export function FormBlockNote({
   description,
   testId,
   onEmptyChange,
+  inlineContentSpecs,
+  renderOverlays,
 }: {
   form: any;
   id: string;
@@ -24,6 +26,8 @@ export function FormBlockNote({
   description?: string;
   testId?: string;
   onEmptyChange?: (isEmpty: boolean) => void;
+  inlineContentSpecs?: Record<string, any>;
+  renderOverlays?: (editor: any) => React.ReactNode;
 }) {
   return (
     <div className="flex w-full flex-col">
@@ -46,6 +50,8 @@ export function FormBlockNote({
             }}
             placeholder={placeholder}
             bordered
+            inlineContentSpecs={inlineContentSpecs}
+            renderOverlays={renderOverlays}
           />
         )}
       </FormFieldWrapper>

package/src/components/forms/FormSelect.tsx

@@ -16,6 +16,7 @@ export function FormSelect({
   useRows,
   testId,
   allowEmpty,
+  isRequired,
 }: {
   form: any;
   id: string;
@@ -27,6 +28,7 @@ export function FormSelect({
   useRows?: boolean;
   testId?: string;
   allowEmpty?: boolean;
+  isRequired?: boolean;
 }) {
   return (
     <div className="flex w-full flex-col">
@@ -34,6 +36,7 @@ export function FormSelect({
         form={form}
         name={id}
         label={name}
+        isRequired={isRequired}
         orientation={useRows ? "horizontal" : "vertical"}
         testId={testId}
       >

package/src/components/index.ts

@@ -19,6 +19,7 @@ export * from "../features/auth/components";
 // Billing components moved to separate entry point: @carlonicora/nextjs-jsonapi/billing
 export * from "../features/company/components";
 export * from "../features/content/components";
+export * from "../features/how-to/components";
 export * from "../features/feature/components";
 export * from "../features/notification/components";
 export * from "../features/onboarding/components";

package/src/contexts/index.ts

@@ -3,6 +3,7 @@ export * from "../features/notification/contexts/NotificationContext";
 export * from "../features/onboarding/contexts";
 export * from "../features/role/contexts/RoleContext";
 export * from "../features/user/contexts";
+export * from "../features/how-to/contexts/HowToContext";
 export * from "./CommonContext";
 export * from "./HeaderChildrenContext";
 export * from "./SharedContext";

package/src/core/index.ts

@@ -59,6 +59,8 @@ export * from "../features/company/company.module";
 export * from "../features/company/data";
 export * from "../features/content/content.module";
 export * from "../features/content/data";
+export * from "../features/how-to/HowToModule";
+export * from "../features/how-to/data";
 export * from "../features/feature/data";
 export * from "../features/feature/feature.module";
 export * from "../features/module";

package/src/core/registry/ModuleRegistry.ts

@@ -15,6 +15,7 @@ export interface FoundationModuleDefinitions {
   Feature: ModuleWithPermissions;
   Module: ModuleWithPermissions;
   Content: ModuleWithPermissions;
+  HowTo: ModuleWithPermissions;
   // Billing modules - READ: all users, UPDATE: CompanyAdministrator, ADMIN: Administrator
   Billing: ModuleWithPermissions;
   StripeCustomer: ModuleWithPermissions;
@@ -122,6 +123,24 @@ class ModuleRegistryClass {
     throw new Error(`Module not found: ${moduleName}`);
   }
 
+  getAllPageUrls(): { id: string; text: string }[] {
+    if (this._modules.size === 0) {
+      tryBootstrap();
+    }
+
+    const seen = new Set<string>();
+    const result: { id: string; text: string }[] = [];
+    for (const [key, module] of this._modules.entries()) {
+      const m = module as ModuleWithPermissions;
+      if (m.pageUrl && !seen.has(m.pageUrl)) {
+        seen.add(m.pageUrl);
+        result.push({ id: m.pageUrl, text: key });
+        result.push({ id: `${m.pageUrl}/:id`, text: `${key} (detail)` });
+      }
+    }
+    return result.sort((a, b) => a.text.localeCompare(b.text));
+  }
+
   findByModelName(modelName: string): ModuleWithPermissions {
     // Direct lookup by registry key (e.g., "Article", "Document")
     let module = this._modules.get(modelName);

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

@@ -0,0 +1,18 @@
+import { LifeBuoyIcon } from "lucide-react";
+import { createJsonApiInclusion } from "../../core";
+import { ModuleFactory } from "../../permissions";
+import { HowTo } from "./data/HowTo";
+
+export const HowToModule = (factory: ModuleFactory) =>
+  factory({
+    moduleId: "6f975207-0df3-4c0d-b541-ed5dc04487b2",
+    pageUrl: "/administration/howtos",
+    name: "howtos",
+    model: HowTo,
+    icon: LifeBuoyIcon,
+    inclusions: {
+      lists: {
+        fields: [createJsonApiInclusion("howtos", [`name`, `description`, `pages`])],
+      },
+    },
+  });

package/src/features/how-to/components/containers/HowToCommand.tsx

@@ -0,0 +1,230 @@
+"use client";
+
+import { ArrowRight, LifeBuoyIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+  SidebarMenuButton,
+} from "../../../../shadcnui";
+import { Modules } from "../../../../core";
+import { DataListRetriever, useDataListRetriever, useDebounce } from "../../../../hooks";
+import { HowTo } from "../../data/HowTo";
+import { HowToInterface } from "../../data/HowToInterface";
+import { HowToService } from "../../data/HowToService";
+import HowToCommandViewer from "./HowToCommandViewer";
+
+function matchPage(pathname: string, pattern: string): boolean {
+  if (pattern.includes(":")) {
+    const pathSegments = pathname.split("/").filter(Boolean);
+    const patternSegments = pattern.split("/").filter(Boolean);
+    if (pathSegments.length !== patternSegments.length) return false;
+    return patternSegments.every((seg, i) => (seg.startsWith(":") ? true : seg === pathSegments[i]));
+  }
+  return pathname.toLowerCase().includes(pattern.toLowerCase());
+}
+
+type HowToCommandProps = {
+  /** Current pathname for page relevance matching */
+  pathname: string;
+  /** Optional extra command groups to render when not searching */
+  extraGroups?: ReactNode;
+  /** Called when user starts a chat from the viewer */
+  onStartChat?: () => void;
+};
+
+export default function HowToCommand({ pathname, extraGroups, onStartChat }: HowToCommandProps) {
+  const t = useTranslations();
+
+  const [dialogOpen, setDialogOpen] = useState<boolean>(false);
+  const [selectedHowTo, setSelectedHowTo] = useState<HowToInterface | null>(null);
+
+  const searchTermRef = useRef<string>("");
+  const [searchTerm, setSearchTerm] = useState<string>("");
+
+  const data: DataListRetriever<HowToInterface> = useDataListRetriever({
+    retriever: (params) => {
+      return HowToService.findMany(params);
+    },
+    retrieverParams: {},
+    module: Modules.HowTo,
+  });
+
+  // Split HowTos into relevant (matching current page) and others
+  const { relevantHowTos, otherHowTos } = useMemo(() => {
+    if (!data.data) return { relevantHowTos: [], otherHowTos: [] };
+
+    const relevant: HowToInterface[] = [];
+    const other: HowToInterface[] = [];
+
+    (data.data as HowToInterface[]).forEach((howTo) => {
+      const pages = HowTo.parsePagesFromString(howTo.pages);
+      const isRelevant = pages.some((page) => page && matchPage(pathname, page));
+      if (isRelevant) {
+        relevant.push(howTo);
+      } else {
+        other.push(howTo);
+      }
+    });
+
+    return { relevantHowTos: relevant, otherHowTos: other };
+  }, [data.data, pathname]);
+
+  const search = useCallback(
+    async (searchedTerm: string) => {
+      if (searchedTerm === searchTermRef.current) return;
+      searchTermRef.current = searchedTerm;
+      await data.search(searchedTerm);
+    },
+    [searchTermRef, data],
+  );
+
+  const updateSearchTerm = useDebounce(search, 500);
+
+  useEffect(() => {
+    updateSearchTerm(searchTerm);
+  }, [updateSearchTerm, searchTerm]);
+
+  // Reset search when dialog closes
+  useEffect(() => {
+    if (!dialogOpen) {
+      setSearchTerm("");
+      searchTermRef.current = "";
+    }
+  }, [dialogOpen]);
+
+  // Keyboard shortcut: Cmd+K or Ctrl+K to toggle dialog
+  useEffect(() => {
+    const down = (e: KeyboardEvent) => {
+      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        setDialogOpen((open) => !open);
+      }
+    };
+
+    document.addEventListener("keydown", down);
+    return () => document.removeEventListener("keydown", down);
+  }, []);
+
+  const handleStartChat = () => {
+    setDialogOpen(false);
+    setSelectedHowTo(null);
+    if (onStartChat) onStartChat();
+  };
+
+  return (
+    <>
+      <SidebarMenuButton
+        tooltip={t(`howto.command.trigger`)}
+        onClick={() => setDialogOpen(true)}
+        className="text-muted-foreground"
+      >
+        <LifeBuoyIcon />
+        <span>{t(`howto.command.trigger`)}</span>
+      </SidebarMenuButton>
+
+      {/* Search HowTos Dialog */}
+      <Dialog
+        open={dialogOpen}
+        onOpenChange={(open) => {
+          setDialogOpen(open);
+          if (!open) setSelectedHowTo(null);
+        }}
+        modal={true}
+      >
+        <DialogContent
+          className={`flex flex-col gap-0 overflow-hidden p-0 ${selectedHowTo ? "h-[80vh] max-w-3xl" : "max-w-lg"}`}
+        >
+          <DialogHeader className="sr-only">
+            <DialogTitle>{selectedHowTo ? selectedHowTo.name : t("howto.command.title")}</DialogTitle>
+            <DialogDescription> </DialogDescription>
+          </DialogHeader>
+
+          {selectedHowTo ? (
+            <HowToCommandViewer
+              howTo={selectedHowTo}
+              onBack={() => setSelectedHowTo(null)}
+              onStartChat={handleStartChat}
+            />
+          ) : (
+            <Command
+              shouldFilter={false}
+              className="[&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group]]:px-2 [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5"
+            >
+              <CommandInput
+                onKeyDown={(e) => {
+                  if (e.key === "Escape") {
+                    setSearchTerm("");
+                    searchTermRef.current = "";
+                  }
+                }}
+                onValueChange={setSearchTerm}
+                value={searchTerm}
+                placeholder={t(`howto.search.placeholder`)}
+              />
+              <CommandList className="max-h-[60vh] overflow-y-auto">
+                <CommandEmpty>{t(`howto.command.empty`)}</CommandEmpty>
+
+                {/* App-specific extra groups (support, tours, etc.) */}
+                {!searchTerm && extraGroups}
+
+                {/* Relevant to this page */}
+                {relevantHowTos.length > 0 && (
+                  <CommandGroup heading={t(`howto.command.relevant`)}>
+                    {relevantHowTos.map((howTo: HowToInterface) => (
+                      <CommandItem key={howTo.id} onSelect={() => setSelectedHowTo(howTo)} className="cursor-pointer">
+                        <ArrowRight className="h-4 w-4" />
+                        <span>{howTo.name}</span>
+                      </CommandItem>
+                    ))}
+                  </CommandGroup>
+                )}
+
+                {/* All HowTos / Search Results */}
+                {otherHowTos.length > 0 && (
+                  <CommandGroup heading={searchTerm ? undefined : t(`howto.command.all`)}>
+                    {otherHowTos.map((howTo: HowToInterface) => (
+                      <CommandItem key={howTo.id} onSelect={() => setSelectedHowTo(howTo)} className="cursor-pointer">
+                        <ArrowRight className="h-4 w-4" />
+                        <span>{howTo.name}</span>
+                      </CommandItem>
+                    ))}
+                  </CommandGroup>
+                )}
+              </CommandList>
+
+              {/* Keyboard hints footer */}
+              <div className="text-muted-foreground flex items-center justify-center gap-4 border-t px-3 py-2 text-xs">
+                <span className="flex items-center gap-1">
+                  <kbd className="bg-muted rounded border px-1.5 py-0.5 font-mono text-[10px]">&#9166;</kbd>
+                  {t(`howto.command.keyboard.select`)}
+                </span>
+                <span className="flex items-center gap-1">
+                  <kbd className="bg-muted rounded border px-1.5 py-0.5 font-mono text-[10px]">&#8593;&#8595;</kbd>
+                  {t(`howto.command.keyboard.navigate`)}
+                </span>
+                <span className="flex items-center gap-1">
+                  <kbd className="bg-muted rounded border px-1.5 py-0.5 font-mono text-[10px]">
+                    {t(`howto.keyboard.esc`)}
+                  </kbd>
+                  {t(`howto.command.keyboard.close`)}
+                </span>
+              </div>
+            </Command>
+          )}
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}

package/src/features/how-to/components/containers/HowToCommandViewer.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import { ArrowLeft, BookOpen, MessageSquare } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+
+import { BlockNoteEditorContainer } from "../../../../components";
+import { Button } from "../../../../shadcnui";
+import { HowToInterface } from "../../data/HowToInterface";
+import { calculateReadingTime, extractHeadings } from "../../utils/blocknote";
+
+type HowToCommandViewerProps = {
+  howTo: HowToInterface;
+  onBack: () => void;
+  onStartChat?: () => void;
+};
+
+export default function HowToCommandViewer({ howTo, onBack, onStartChat }: HowToCommandViewerProps) {
+  const t = useTranslations();
+
+  const readingTime = useMemo(() => calculateReadingTime(howTo.description), [howTo.description]);
+  const headings = useMemo(() => extractHeadings(howTo.description), [howTo.description]);
+
+  return (
+    <div className="flex h-full flex-col">
+      {/* Header with back button, title, and reading time */}
+      <div className="flex items-center gap-3 border-b px-4 py-3">
+        <Button variant="ghost" size="sm" onClick={onBack} className="h-8 px-2">
+          <ArrowLeft className="h-4 w-4" />
+          <span className="ml-1">{t("howto.command.back")}</span>
+        </Button>
+        <h2 className="flex-1 truncate text-lg font-semibold">{howTo.name}</h2>
+        <div className="text-muted-foreground flex items-center gap-1.5 text-sm">
+          <BookOpen className="h-4 w-4" />
+          <span>{t("howto.reading_time.label", { minutes: readingTime })}</span>
+        </div>
+      </div>
+
+      {/* Two-column body */}
+      <div className="flex min-h-0 flex-1">
+        {/* Left sidebar - table of contents */}
+        {headings.length > 0 && (
+          <div className="w-50 shrink-0 overflow-y-auto border-r p-4">
+            <nav className="space-y-1">
+              {headings.map((heading) => (
+                <a
+                  key={heading.id}
+                  href={`#${heading.id}`}
+                  className="text-muted-foreground hover:text-foreground block truncate text-sm"
+                  style={{ paddingLeft: `${(heading.level - 1) * 0.75}rem` }}
+                >
+                  {heading.text}
+                </a>
+              ))}
+            </nav>
+          </div>
+        )}
+
+        {/* Right content - scrollable */}
+        <div id="howto-viewer-content" className="min-w-0 flex-1 overflow-y-auto p-4">
+          <BlockNoteEditorContainer id={howTo.id} type="howto" initialContent={howTo.description} />
+        </div>
+      </div>
+
+      {/* Full-width footer */}
+      {onStartChat && (
+        <div className="flex items-center justify-end gap-2 border-t px-4 py-3">
+          <Button onClick={onStartChat} variant="default" size="sm">
+            <MessageSquare className="mr-2 h-4 w-4" />
+            {t("howto.command.chat_button")}
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/features/how-to/components/containers/HowToContainer.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+import { RoundPageContainer } from "../../../../components";
+import { Modules } from "../../../../core";
+import { useHowToContext } from "../../contexts/HowToContext";
+import { HowToInterface } from "../../data/HowToInterface";
+import HowToContent from "../details/HowToContent";
+import HowToDetails from "../details/HowToDetails";
+
+type HowToContainerProps = {
+  howTo: HowToInterface;
+};
+
+function HowToContainerInternal({ howTo }: HowToContainerProps) {
+  return (
+    <RoundPageContainer module={Modules.HowTo} details={<HowToDetails />}>
+      <HowToContent />
+    </RoundPageContainer>
+  );
+}
+
+export default function HowToContainer() {
+  const { howTo } = useHowToContext();
+  if (!howTo) return null;
+
+  return <HowToContainerInternal howTo={howTo} />;
+}

package/src/features/how-to/components/containers/HowToListContainer.tsx

@@ -0,0 +1,17 @@
+"use client";
+
+import { RoundPageContainer } from "../../../../components";
+import { Modules } from "../../../../core";
+import HowToList from "../lists/HowToList";
+
+function HowToListContainerInternal() {
+  return (
+    <RoundPageContainer module={Modules.HowTo} fullWidth>
+      <HowToList fullWidth />
+    </RoundPageContainer>
+  );
+}
+
+export default function HowToListContainer() {
+  return <HowToListContainerInternal />;
+}

package/src/features/how-to/components/details/HowToContent.tsx

@@ -0,0 +1,16 @@
+"use client";
+
+import { BlockNoteEditorContainer } from "../../../../components";
+import { Card } from "../../../../shadcnui";
+import { useHowToContext } from "../../contexts/HowToContext";
+
+export default function HowToContent() {
+  const { howTo } = useHowToContext();
+  if (!howTo) return null;
+
+  return (
+    <Card className="flex w-full flex-col p-4">
+      <BlockNoteEditorContainer id={howTo.id} type="howto" initialContent={howTo.description} />
+    </Card>
+  );
+}