@carlonicora/nextjs-jsonapi 5.3.0 → 5.5.0

package/src/features/blog/hooks/useBlogPostTableStructure.tsx

@@ -0,0 +1,126 @@
+"use client";
+
+import { ColumnDef } from "@tanstack/react-table";
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+import { Modules } from "../../../core";
+import { registerTableGenerator, TableContent, usePageUrlGenerator, UseTableStructureHook } from "../../../hooks";
+import { useI18nLocale } from "../../../i18n";
+import { Badge, Link } from "../../../shadcnui";
+import { BLOG_STATUS_BADGE } from "../components/admin/BlogTranslationStatus";
+import { useBlogCategoryNames } from "./useBlogCategoryNames";
+import { BlogPostFields, BlogPostInterface } from "../data";
+
+/**
+ * Admin posts table: title (original language, links to the post page),
+ * status, categories, published date and "languages ready" (completed
+ * translations / all translations). Mirrors hooks/useEmailAutomationTableStructure.tsx
+ * in features/email-automation.
+ */
+export const useBlogPostTableStructure: UseTableStructureHook<BlogPostInterface, BlogPostFields> = (params) => {
+  const t = useTranslations();
+  const locale = useI18nLocale();
+  const generateUrl = usePageUrlGenerator();
+  const categoryName = useBlogCategoryNames();
+
+  const tableData = useMemo(() => {
+    return params.data.map((post: BlogPostInterface) => {
+      const entry: TableContent<BlogPostInterface> = { jsonApiData: post };
+      params.fields.forEach((field) => {
+        entry[field] = (post as any)[field as keyof BlogPostInterface];
+      });
+      return entry;
+    });
+  }, [params.data, params.fields]);
+
+  const fieldColumnMap: Partial<Record<BlogPostFields, () => any>> = {
+    [BlogPostFields.title]: () => ({
+      id: BlogPostFields.title,
+      accessorKey: BlogPostFields.title,
+      header: t("blog.fields.title"),
+      cell: ({ row }: { row: TableContent<BlogPostInterface> }) => {
+        const post: BlogPostInterface = row.original.jsonApiData;
+        return (
+          <Link href={generateUrl({ page: Modules.BlogPost, id: post.id })}>
+            {post.original?.title ?? post.title ?? post.id}
+          </Link>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [BlogPostFields.status]: () => ({
+      id: BlogPostFields.status,
+      accessorKey: BlogPostFields.status,
+      header: t("blog.fields.status"),
+      cell: ({ row }: { row: TableContent<BlogPostInterface> }) => {
+        const post: BlogPostInterface = row.original.jsonApiData;
+        const label = {
+          draft: t("blog.status.draft"),
+          published: t("blog.status.published"),
+          unpublished: t("blog.status.unpublished"),
+        }[post.status];
+        return <Badge variant={BLOG_STATUS_BADGE[post.status] ?? "softGray"}>{label ?? post.status}</Badge>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [BlogPostFields.categories]: () => ({
+      id: BlogPostFields.categories,
+      accessorKey: BlogPostFields.categories,
+      header: t("blog.fields.categories"),
+      cell: ({ row }: { row: TableContent<BlogPostInterface> }) => {
+        const post: BlogPostInterface = row.original.jsonApiData;
+        const names = post.categories.map((category) => categoryName(category.id)).filter(Boolean);
+        if (names.length === 0) return <span className="text-muted-foreground text-xs">—</span>;
+        return <span className="text-xs">{names.join(", ")}</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [BlogPostFields.publishedAt]: () => ({
+      id: BlogPostFields.publishedAt,
+      accessorKey: BlogPostFields.publishedAt,
+      header: t("blog.fields.publishedAt"),
+      cell: ({ row }: { row: TableContent<BlogPostInterface> }) => {
+        const post: BlogPostInterface = row.original.jsonApiData;
+        if (!post.publishedAt) return <span className="text-muted-foreground text-xs">—</span>;
+        return (
+          <span className="text-xs tabular-nums">
+            {post.publishedAt.toLocaleDateString(locale, { dateStyle: "medium" })}
+          </span>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [BlogPostFields.languages]: () => ({
+      id: BlogPostFields.languages,
+      accessorKey: BlogPostFields.languages,
+      header: t("blog.fields.languages"),
+      cell: ({ row }: { row: TableContent<BlogPostInterface> }) => {
+        const post: BlogPostInterface = row.original.jsonApiData;
+        const total = post.translations.length;
+        if (total === 0) return <span className="text-muted-foreground text-xs">—</span>;
+        const ready = post.translations.filter((translation) => translation.aiStatus === "completed").length;
+        return (
+          <span className="block text-xs tabular-nums text-end">
+            {ready}/{total}
+          </span>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+  };
+
+  const columns = useMemo(() => {
+    return params.fields.map((field) => fieldColumnMap[field]?.()).filter((col) => col !== undefined) as ColumnDef<
+      TableContent<BlogPostInterface>
+    >[];
+  }, [params.fields, fieldColumnMap, t, generateUrl, locale, categoryName]);
+
+  return useMemo(() => ({ data: tableData, columns: columns }), [tableData, columns]);
+};
+
+registerTableGenerator("blog-posts", useBlogPostTableStructure);

package/src/features/blog/index.ts

@@ -0,0 +1,15 @@
+// Client-only public barrel for the blog feature.
+// Consumed via `@carlonicora/nextjs-jsonapi/blog`. Tsup adds a top-level
+// "use client" directive to the bundled output via clientEntries.
+//
+// Models, services and modules are server-safe and ship from
+// `@carlonicora/nextjs-jsonapi/core`. Server fetchers ship from
+// `@carlonicora/nextjs-jsonapi/blog/server`.
+
+export * from "./components/admin";
+export * from "./components/public";
+export * from "./contexts";
+// Imported for its registerTableGenerator side effect as well as its exports.
+export * from "./hooks";
+export * from "./types/blog.constants";
+export type { PublicBlogCategory, PublicBlogList, PublicBlogPost } from "./types/blog-public.types";

package/src/features/blog/server/fetchers.ts

@@ -0,0 +1,169 @@
+import { EndpointCreator, Modules } from "../../../core";
+import { ServerJsonApiGet } from "../../../server/JsonApiServer";
+import { BlogCategoryInterface } from "../data/BlogCategoryInterface";
+import { BlogPostInterface } from "../data/BlogPostInterface";
+import { BlogSettingsInterface } from "../data/BlogSettingsInterface";
+import { BLOG_ACTION, BLOG_LIST_LAYOUTS, BLOG_PUBLIC_PREFIX, BlogListLayout } from "../types/blog.constants";
+import { PublicBlogCategory, PublicBlogList, PublicBlogPost } from "../types/blog-public.types";
+import { toPublicBlogCategory, toPublicBlogPost } from "./toPublic";
+
+// Public, token-free reads for the marketing blog pages.
+//
+// `cache: "minutes"` is a cacheLife profile name: the GET goes through
+// cachedServerGet ("use cache"), so an admin change shows up within about a
+// minute. Nothing connects API or worker writes to the web cache, and
+// translations finish asynchronously in the worker, so there is no tag to expire.
+//
+// Each classKey is built INSIDE the function, never at module scope: reading
+// Modules.X while the module evaluates throws "Module X not registered" in build
+// workers that never ran the app's bootstrapper (see the app's publicHowTo.ts).
+
+const BLOG_PAGE_SIZE = 12;
+
+const publicPostsEndpoint = () => `${BLOG_PUBLIC_PREFIX}/${Modules.BlogPost.name}`;
+
+const asArray = <T>(data: unknown): T[] => (Array.isArray(data) ? data : data ? [data] : []) as T[];
+
+export async function fetchPublicBlogPosts(params: {
+  language: string;
+  categorySlug?: string;
+  search?: string;
+  /** 1-based list page; ignored with `all`. */
+  page?: number;
+  /** Every matching post, read in API-sized pages (a sitemap). `hasMore` is then false. */
+  all?: boolean;
+}): Promise<PublicBlogList> {
+  if (params.all) return { posts: await fetchEveryPublicBlogPost(params), hasMore: false };
+
+  // Matches the API cap (120 = 10 pages of 12); a larger ?page= is served as the last allowed one.
+  const page = Math.min(10, Math.max(1, Math.floor(params.page || 1)));
+  const size = BLOG_PAGE_SIZE * page;
+
+  const res = await ServerJsonApiGet({
+    classKey: { ...Modules.BlogPost, cache: "minutes" },
+    endpoint: publicPostsListEndpoint({ ...params, size }),
+    language: params.language,
+  });
+  if (!res.ok) return { posts: [], hasMore: false };
+
+  const posts = asArray<BlogPostInterface>(res.data).map(toPublicBlogPost);
+  const total = Number(res.meta?.total);
+  const hasMore = Number.isFinite(total) ? total > posts.length : false;
+
+  return { posts, hasMore };
+}
+
+function publicPostsListEndpoint(params: {
+  language: string;
+  categorySlug?: string;
+  search?: string;
+  size: number;
+  offset?: number;
+}): string {
+  const endpoint = new EndpointCreator({ endpoint: publicPostsEndpoint() });
+  endpoint.addAdditionalParam("language", params.language);
+  if (params.categorySlug) endpoint.addAdditionalParam("category", encodeURIComponent(params.categorySlug));
+  if (params.search) endpoint.addAdditionalParam("search", encodeURIComponent(params.search));
+  endpoint.addAdditionalParam("page[size]", String(params.size));
+  if (params.offset) endpoint.addAdditionalParam("page[offset]", String(params.offset));
+  return endpoint.generate();
+}
+
+// The API serves at most PUBLIC_MAX_PAGE_SIZE posts per request, so "all" walks
+// page[offset] until a short page comes back. MAX_ALL_PAGES only stops a runaway loop.
+const PUBLIC_MAX_PAGE_SIZE = 120;
+const MAX_ALL_PAGES = 100;
+
+async function fetchEveryPublicBlogPost(params: {
+  language: string;
+  categorySlug?: string;
+  search?: string;
+}): Promise<PublicBlogPost[]> {
+  const posts: PublicBlogPost[] = [];
+
+  // In sequence: a failing cached call throws, and parallel failing cached calls
+  // never close the response.
+  for (let index = 0; index < MAX_ALL_PAGES; index++) {
+    const res = await ServerJsonApiGet({
+      classKey: { ...Modules.BlogPost, cache: "minutes" },
+      endpoint: publicPostsListEndpoint({
+        ...params,
+        size: PUBLIC_MAX_PAGE_SIZE,
+        offset: index * PUBLIC_MAX_PAGE_SIZE,
+      }),
+      language: params.language,
+    });
+    if (!res.ok) break;
+
+    const batch = asArray<BlogPostInterface>(res.data);
+    posts.push(...batch.map(toPublicBlogPost));
+    if (batch.length < PUBLIC_MAX_PAGE_SIZE) break;
+  }
+
+  return posts;
+}
+
+export async function fetchPublicBlogPost(params: { language: string; slug: string }): Promise<PublicBlogPost | null> {
+  const endpoint = new EndpointCreator({ endpoint: publicPostsEndpoint(), id: encodeURIComponent(params.slug) });
+  endpoint.addAdditionalParam("language", params.language);
+
+  const res = await ServerJsonApiGet({
+    classKey: { ...Modules.BlogPost, cache: "minutes" },
+    endpoint: endpoint.generate(),
+    language: params.language,
+  });
+  if (!res.ok) return null;
+
+  const post = asArray<BlogPostInterface>(res.data)[0];
+  return post ? toPublicBlogPost(post) : null;
+}
+
+export async function fetchRelatedBlogPosts(params: { language: string; slug: string }): Promise<PublicBlogPost[]> {
+  const endpoint = new EndpointCreator({
+    endpoint: publicPostsEndpoint(),
+    id: encodeURIComponent(params.slug),
+    childEndpoint: BLOG_ACTION.related,
+  });
+  endpoint.addAdditionalParam("language", params.language);
+
+  const res = await ServerJsonApiGet({
+    classKey: { ...Modules.BlogPost, cache: "minutes" },
+    endpoint: endpoint.generate(),
+    language: params.language,
+  });
+  if (!res.ok) return [];
+
+  return asArray<BlogPostInterface>(res.data).map(toPublicBlogPost);
+}
+
+export async function fetchPublicBlogCategories(params: { language: string }): Promise<PublicBlogCategory[]> {
+  const endpoint = new EndpointCreator({ endpoint: `${BLOG_PUBLIC_PREFIX}/${Modules.BlogCategory.name}` });
+  endpoint.addAdditionalParam("language", params.language);
+
+  const res = await ServerJsonApiGet({
+    classKey: { ...Modules.BlogCategory, cache: "minutes" },
+    endpoint: endpoint.generate(),
+    language: params.language,
+  });
+  if (!res.ok) return [];
+
+  return asArray<BlogCategoryInterface>(res.data).map(toPublicBlogCategory);
+}
+
+export async function fetchBlogSettings(): Promise<{ listLayout: BlogListLayout }> {
+  const fallback: { listLayout: BlogListLayout } = { listLayout: "featured" };
+
+  // The settings are language-neutral; the language only fills the required
+  // request header, so one fixed value keeps a single cache entry.
+  const res = await ServerJsonApiGet({
+    classKey: { ...Modules.BlogSettings, cache: "minutes" },
+    endpoint: new EndpointCreator({ endpoint: `${BLOG_PUBLIC_PREFIX}/${Modules.BlogSettings.name}` }).generate(),
+    language: "en",
+  });
+  if (!res.ok) return fallback;
+
+  const settings = asArray<BlogSettingsInterface>(res.data)[0];
+  if (!settings || !BLOG_LIST_LAYOUTS.includes(settings.listLayout)) return fallback;
+
+  return { listLayout: settings.listLayout };
+}

package/src/features/blog/server/toPublic.spec.ts

@@ -0,0 +1,91 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { User } from "../../user/data/user";
+import { ModuleRegistry } from "../../../core/registry/ModuleRegistry";
+import { ModuleFactory, ModuleWithPermissions } from "../../../permissions/types";
+import {
+  BlogCategoryModule,
+  BlogCategoryTranslationModule,
+  BlogPostModule,
+  BlogPostTranslationModule,
+} from "../BlogModules";
+import { BlogCategory } from "../data/BlogCategory";
+import { BlogPost } from "../data/BlogPost";
+import { toPublicBlogCategory, toPublicBlogPost } from "./toPublic";
+
+const moduleFactory: ModuleFactory = (params) =>
+  ({
+    pageUrl: params.pageUrl,
+    name: params.name,
+    model: params.model,
+  }) as ModuleWithPermissions;
+
+beforeAll(() => {
+  ModuleRegistry.register("BlogPost", BlogPostModule(moduleFactory));
+  ModuleRegistry.register("BlogPostTranslation", BlogPostTranslationModule(moduleFactory));
+  ModuleRegistry.register("BlogCategory", BlogCategoryModule(moduleFactory));
+  ModuleRegistry.register("BlogCategoryTranslation", BlogCategoryTranslationModule(moduleFactory));
+  ModuleRegistry.register("User", { name: "users", model: User } as ModuleWithPermissions);
+});
+
+const blocks = [{ type: "paragraph", content: [{ type: "text", text: "Hello", styles: {} }] }];
+
+const makePost = () =>
+  new BlogPost().rehydrate({
+    jsonApi: {
+      id: "p",
+      type: "blog-posts",
+      attributes: {
+        status: "published",
+        originalLanguage: "en",
+        publishedAt: "2026-10-12T09:00:00.000Z",
+        language: "en",
+        title: "Prep situations",
+        slug: "prep-situations",
+        summary: "What to prepare.",
+        body: JSON.stringify(blocks),
+        readingMinutes: 4,
+        authorName: "Ada",
+        categoryIds: ["c1"],
+      },
+      meta: { createdAt: "2026-10-10T09:00:00.000Z", updatedAt: "2026-10-14T09:00:00.000Z" },
+    },
+    included: [],
+  } as any);
+
+describe("toPublicBlogPost", () => {
+  it("toPublicBlogPost maps a rehydrated post to plain serialisable data", () => {
+    expect(JSON.parse(JSON.stringify(toPublicBlogPost(makePost())))).toEqual(toPublicBlogPost(makePost()));
+    expect(toPublicBlogPost(makePost()).publishedAt).toBe("2026-10-12T09:00:00.000Z");
+  });
+
+  it("carries the resolved fields", () => {
+    const result = toPublicBlogPost(makePost());
+    expect(result).toMatchObject({
+      id: "p",
+      language: "en",
+      title: "Prep situations",
+      slug: "prep-situations",
+      summary: "What to prepare.",
+      readingMinutes: 4,
+      updatedAt: "2026-10-14T09:00:00.000Z",
+      authorName: "Ada",
+      categoryIds: ["c1"],
+    });
+    expect(result.body).toEqual(blocks);
+  });
+});
+
+describe("toPublicBlogCategory", () => {
+  it("maps the resolved name and slug", () => {
+    const category = new BlogCategory().rehydrate({
+      jsonApi: {
+        id: "c1",
+        type: "blog-categories",
+        attributes: { originalLanguage: "en", name: "Game prep", slug: "game-prep" },
+      },
+      included: [],
+    } as any);
+
+    expect(toPublicBlogCategory(category)).toEqual({ id: "c1", name: "Game prep", slug: "game-prep" });
+  });
+});

package/src/features/blog/server/toPublic.ts

@@ -0,0 +1,36 @@
+import { BlogCategoryInterface } from "../data/BlogCategoryInterface";
+import { BlogPostInterface } from "../data/BlogPostInterface";
+import { PublicBlogCategory, PublicBlogPost } from "../types/blog-public.types";
+
+// Serialisation boundary: a rehydrated model (class instance, Date getters)
+// becomes plain data a server page can pass to the public client components.
+
+export function toPublicBlogPost(post: BlogPostInterface): PublicBlogPost {
+  const publishedAt = post.publishedAt ?? post.createdAt;
+
+  return {
+    id: post.id,
+    language: post.language ?? post.originalLanguage,
+    title: post.title ?? "",
+    slug: post.slug ?? "",
+    summary: post.summary,
+    body: post.body,
+    coverImage: post.coverImage,
+    coverImageAlt: post.coverImageAlt,
+    readingMinutes: post.readingMinutes ?? 1,
+    publishedAt: publishedAt.toISOString(),
+    updatedAt: post.updatedAt.toISOString(),
+    authorName: post.authorName,
+    categoryIds: [...post.categoryIds],
+  };
+}
+
+export function toPublicBlogCategory(category: BlogCategoryInterface): PublicBlogCategory {
+  return {
+    id: category.id,
+    name: category.name ?? "",
+    slug: category.slug ?? "",
+    description: category.description,
+    image: category.image,
+  };
+}

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

@@ -0,0 +1,17 @@
+// Server-safe public barrel for the blog feature.
+// Consumed via `@carlonicora/nextjs-jsonapi/blog/server`. Must NOT receive a
+// "use client" directive: server pages import the cached public fetchers and
+// the plain view-model types from here without pulling the client bundle.
+// Client components live in `@carlonicora/nextjs-jsonapi/blog`.
+
+export {
+  fetchBlogSettings,
+  fetchPublicBlogCategories,
+  fetchPublicBlogPost,
+  fetchPublicBlogPosts,
+  fetchRelatedBlogPosts,
+} from "./server/fetchers";
+export { toPublicBlogCategory, toPublicBlogPost } from "./server/toPublic";
+export { BLOG_LIST_LAYOUTS } from "./types/blog.constants";
+export type { BlogListLayout } from "./types/blog.constants";
+export type { PublicBlogCategory, PublicBlogList, PublicBlogPost } from "./types/blog-public.types";

package/src/features/blog/types/blog-public.types.ts

@@ -0,0 +1,34 @@
+// Plain, serialisable view models handed from server pages to the public
+// components. No class instances and no Date objects: they cross the
+// server → client boundary as props.
+
+import type { PartialBlock } from "@blocknote/core";
+
+export type PublicBlogCategory = {
+  id: string;
+  name: string;
+  slug: string;
+  description?: string;
+  image?: string;
+};
+
+export type PublicBlogPost = {
+  id: string;
+  language: string;
+  title: string;
+  slug: string;
+  summary?: string;
+  body?: PartialBlock[];
+  coverImage?: string;
+  coverImageAlt?: string;
+  readingMinutes: number;
+  publishedAt: string;
+  updatedAt: string;
+  authorName?: string;
+  categoryIds: string[];
+};
+
+export type PublicBlogList = {
+  posts: PublicBlogPost[];
+  hasMore: boolean;
+};

package/src/features/blog/types/blog.constants.ts

@@ -0,0 +1,40 @@
+// Mirrors packages/nestjs-neo4jsonapi/src/foundations/blog/blog.constants.ts and
+// CoreModuleId.Blog. The two packages share no code, so the values are repeated.
+
+export const BLOG_LIST_LAYOUTS = ["featured", "column", "rail"] as const;
+export type BlogListLayout = (typeof BLOG_LIST_LAYOUTS)[number];
+
+export const BLOG_POST_STATUSES = ["draft", "published", "unpublished"] as const;
+export type BlogPostStatus = (typeof BLOG_POST_STATUSES)[number];
+
+export const BLOG_TRANSLATION_SOURCES = ["original", "ai", "manual"] as const;
+export type BlogTranslationSource = (typeof BLOG_TRANSLATION_SOURCES)[number];
+
+// Same values as the backend AiStatus enum.
+export type BlogAiStatus = "pending" | "in_progress" | "completed" | "failed";
+
+export const BLOG_SETTINGS_ID = "5f3c2a9e-8d41-4b7a-9c2e-1a6b0d4e7f13";
+
+export const BLOG_MODULE_ID = "c1d0e6a2-4b8f-4f3e-9a7d-2e5b8c6f1a90";
+
+/**
+ * Storage root for blog images (covers, category images, images pasted into a
+ * post body). Blog content belongs to the platform, not to a company, and the
+ * administrators who write it may belong to no company, so the keys are
+ * `blog/<folder>/<id>/<file>` instead of `companies/<companyId>/...`. An app's
+ * S3 key access policy must allow Administrators on this root.
+ */
+export const BLOG_UPLOAD_ROOT = "blog";
+export const BLOG_POST_UPLOAD_PREFIX = `${BLOG_UPLOAD_ROOT}/blog-posts`;
+export const BLOG_CATEGORY_UPLOAD_PREFIX = `${BLOG_UPLOAD_ROOT}/blog-categories`;
+
+/** Path prefix of the token-free public blog endpoints (`public/blog-posts`, ...). */
+export const BLOG_PUBLIC_PREFIX = "public";
+
+/** Action segments under a blog resource (`blog-posts/:id/publish`, ...). */
+export const BLOG_ACTION = {
+  publish: "publish",
+  unpublish: "unpublish",
+  retranslate: "retranslate",
+  related: "related",
+} as const;

package/src/features/email-automation/components/containers/EmailAutomationsListContainer.tsx

@@ -1,8 +1,10 @@
 "use client";
 
+import { useTranslations } from "next-intl";
 import { RoundPageContainer } from "../../../../components";
+import { SharedProvider } from "../../../../contexts/SharedContext";
 import { Modules } from "../../../../core";
-import { AdministrationProvider } from "../../../administration/contexts/AdministrationContext";
+import { BreadcrumbItemData } from "../../../../interfaces";
 import { EmailAutomationsList } from "../lists/EmailAutomationsList";
 
 /**
@@ -15,13 +17,20 @@ import { EmailAutomationsList } from "../lists/EmailAutomationsList";
  *
  * No `forceHeader`: ContentListTable draws its own header row with the title
  * and the create action, exactly as the company and user list pages do.
+ *
+ * Publishes its own breadcrumb, as CompanyProvider does for the companies list:
+ * the list root comes first and has no href because it is the current page.
  */
 export function EmailAutomationsListContainer() {
+  const t = useTranslations();
+
+  const breadcrumbs: BreadcrumbItemData[] = [{ name: t("emailAutomations.admin.title") }];
+
   return (
-    <AdministrationProvider>
+    <SharedProvider value={{ breadcrumbs, title: { type: t("emailAutomations.admin.title") } }}>
       <RoundPageContainer module={Modules.EmailAutomation} fullWidth>
         <EmailAutomationsList fullWidth />
       </RoundPageContainer>
-    </AdministrationProvider>
+    </SharedProvider>
   );
 }

package/src/features/rbac/contexts/RbacContext.tsx

@@ -4,8 +4,6 @@ import { DownloadIcon, Loader2Icon } from "lucide-react";
 import { useTranslations } from "next-intl";
 import { createContext, ReactNode, useCallback, useContext, useEffect, useMemo, useState } from "react";
 import { SharedProvider } from "../../../contexts";
-import { Modules } from "../../../core";
-import { usePageUrlGenerator } from "../../../hooks";
 import { BreadcrumbItemData } from "../../../interfaces";
 import { Button } from "../../../shadcnui";
 import { showError, showToast } from "../../../utils/toast";
@@ -70,7 +68,6 @@ export const RbacProvider = ({
   moduleNames,
   outputPath = DEFAULT_OUTPUT_PATH,
 }: RbacProviderProps) => {
-  const generateUrl = usePageUrlGenerator();
   const t = useTranslations();
 
   const [matrix, setMatrix] = useState<RbacMatrix | null>(null);
@@ -149,10 +146,10 @@ export const RbacProvider = ({
 
   const breadcrumb = (): BreadcrumbItemData[] => {
     const response: BreadcrumbItemData[] = [];
-    response.push({
-      name: t(`entities.rbac`, { count: 2 }),
-      href: generateUrl({ page: Modules.RbacMatrix }),
-    });
+    // Unlinked: the provider only serves the RBAC page, so the root is always
+    // the current page. The dev matrix module has no pageUrl either, so a link
+    // built from it pointed at "undefined".
+    response.push({ name: t(`entities.rbac`, { count: 2 }) });
     return response;
   };
 

package/src/features/rbac/contexts/__tests__/RbacContext.spec.tsx

@@ -0,0 +1,42 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useSharedContext } from "../../../../contexts/SharedContext";
+import { RbacService } from "../../data/RbacService";
+import { RbacProvider } from "../RbacContext";
+
+vi.mock("../../data/RbacService", () => ({
+  RbacService: {
+    fetchMatrix: vi.fn(async () => ({ matrix: {}, modulePaths: {} })),
+    saveMatrix: vi.fn(async () => undefined),
+  },
+}));
+
+// The provider refetches whenever `t` changes identity, and the global next-intl
+// mock in vitest.setup.ts builds a new `t` per call. A stable one keeps the fetch
+// to a single run. Labels still render as their own key.
+const { stableT } = vi.hoisted(() => ({ stableT: (key: string) => key }));
+vi.mock("next-intl", () => ({
+  useTranslations: () => stableT,
+  useLocale: () => "en",
+  useNow: () => new Date(),
+  useTimeZone: () => "UTC",
+  useFormatter: () => ({ dateTime: vi.fn(), number: vi.fn(), relativeTime: vi.fn() }),
+}));
+
+function BreadcrumbProbe() {
+  const { breadcrumbs } = useSharedContext();
+  return <span data-testid="breadcrumbs">{JSON.stringify(breadcrumbs)}</span>;
+}
+
+describe("RbacContext", () => {
+  it("publishes the page as an unlinked breadcrumb, since it is the current page", async () => {
+    render(
+      <RbacProvider>
+        <BreadcrumbProbe />
+      </RbacProvider>,
+    );
+
+    await waitFor(() => expect(RbacService.fetchMatrix).toHaveBeenCalled());
+    expect(screen.getByTestId("breadcrumbs")).toHaveTextContent(JSON.stringify([{ name: "entities.rbac" }]));
+  });
+});

package/src/features/s3/data/s3.service.ts

@@ -12,6 +12,23 @@ export class S3Service extends AbstractService {
     return this.callApi<S3Interface>({ type: Modules.S3, method: HttpMethod.GET, endpoint: endpoint.generate() });
   }
 
+  /**
+   * Presigns `key` and PUTs `file` to the presigned S3 URL. The PUT goes straight
+   * to object storage (not the JSON:API backend), so it cannot use callApi.
+   * Throws when the upload is rejected.
+   */
+  static async upload(params: { key: string; contentType: string; file: Blob; isPublic?: boolean }): Promise<void> {
+    const s3 = await this.getPreSignedUrl({
+      key: params.key,
+      contentType: params.contentType,
+      isPublic: params.isPublic,
+    });
+
+    const response = await fetch(s3.url, { method: "PUT", headers: s3.headers, body: params.file });
+
+    if (!response.ok) throw new Error(`S3 upload failed: ${response.status}`);
+  }
+
   static async getSignedUrl(params: { key: string; isPublic?: boolean }): Promise<S3Interface> {
     const endpoint = new EndpointCreator({ endpoint: Modules.S3, id: "sign" }).addAdditionalParam("key", params.key);