@carlonicora/nextjs-jsonapi 2.2.3 → 2.4.0

package/dist/server/index.mjs

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

package/package.json

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

package/src/billing/index.ts

@@ -1,5 +1,6 @@
 // Billing components - separate entry point to avoid loading Stripe.js globally
 export * from "../features/billing/components";
+export * from "../features/billing/contexts";
 export * from "../features/billing/stripe-customer/components";
 export * from "../features/billing/stripe-invoice/components";
 export * from "../features/billing/stripe-price/components";

package/src/components/editors/BlockNoteEditor.tsx

@@ -93,6 +93,11 @@ export type BlockNoteEditorProps = {
   // height and scrolls internally. Without it the editor grows to fit its
   // content and pushes the surrounding form to scroll instead.
   stretch?: boolean;
+  // Gates AI on top of `aiConfig` (credit availability, etc.). Defaults to
+  // true so existing callers that only pass `aiConfig` are unaffected. When
+  // false, no AI extension is created, the AI toolbar button and AI slash
+  // items are hidden, and the editor falls back to the plain slash menu.
+  aiEnabled?: boolean;
 };
 
 function isBlockEmpty(block: any): boolean {
@@ -408,6 +413,7 @@ export default function BlockNoteEditor({
   onWarmMentions,
   aiConfig,
   stretch,
+  aiEnabled = true,
 }: BlockNoteEditorProps): React.JSX.Element {
   const t = useTranslations();
   const locale = useI18nLocale();
@@ -483,7 +489,7 @@ export default function BlockNoteEditor({
 
   const companyId = company?.id;
   const aiExtension = useMemo(() => {
-    if (!aiConfig) return undefined;
+    if (!aiConfig || !aiEnabled) return undefined;
     const base = getPublicApiUrl();
     const url = new URL(aiConfig.endpoint, base.endsWith("/") ? base : base + "/").toString();
     return AIExtension({
@@ -524,7 +530,7 @@ export default function BlockNoteEditor({
         },
       }),
     });
-  }, [aiConfig, companyId, locale]);
+  }, [aiConfig, aiEnabled, companyId, locale]);
 
   const uploadImage = useCallback(
     async (file: File): Promise<string> => {
@@ -834,7 +840,7 @@ export default function BlockNoteEditor({
         onChange={handleChange}
         editable={onChange !== undefined}
         formattingToolbar={false}
-        slashMenu={!aiConfig}
+        slashMenu={!aiConfig || !aiEnabled}
         // Follow the app theme: hardcoding "light" leaves dark (light-theme)
         // text on the dark card, which is nearly unreadable in dark mode.
         theme={resolvedTheme === "dark" ? "dark" : "light"}
@@ -854,7 +860,7 @@ export default function BlockNoteEditor({
           size === "sm" && "small",
         )}
       >
-        <BlockNoteEditorFormattingToolbar showAI={!!aiConfig} />
+        <BlockNoteEditorFormattingToolbar showAI={!!aiConfig && aiEnabled} />
         {enableMentions && mentionSearchFn && (
           <BlockNoteEditorMentionSuggestionMenu
             editor={editor}
@@ -867,7 +873,7 @@ export default function BlockNoteEditor({
         {enableMentions && mentionResolveFn && (
           <BlockNoteEditorMentionHoverCard containerRef={editorRef} mentionResolveFn={mentionResolveFn} />
         )}
-        {aiConfig && (
+        {aiConfig && aiEnabled && (
           <SuggestionMenuController
             triggerCharacter="/"
             getItems={async (query: string) =>
@@ -875,7 +881,7 @@ export default function BlockNoteEditor({
             }
           />
         )}
-        {aiConfig && <AIMenuController aiMenu={() => <NarrAIMenu />} />}
+        {aiConfig && aiEnabled && <AIMenuController aiMenu={() => <NarrAIMenu />} />}
       </BlockNoteView>
     </div>
   );

package/src/components/index.ts

@@ -20,6 +20,7 @@ export { parseFiscalData } from "../utils/fiscal-utils";
 
 // Feature components
 export * from "../features/auth/components";
+export * from "../features/administration";
 // Billing components moved to separate entry point: @carlonicora/nextjs-jsonapi/billing
 export * from "../features/company/components";
 export * from "../features/content/components";

package/src/contexts/index.ts

@@ -1,3 +1,4 @@
+export * from "../features/administration/contexts";
 export * from "../features/company/contexts/CompanyContext";
 export * from "../features/notification/contexts/NotificationContext";
 export * from "../features/onboarding/contexts";

package/src/features/administration/components/AdminIndexContainer.tsx

@@ -0,0 +1,150 @@
+"use client";
+
+import { Building2Icon, CoinsIcon, CreditCardIcon, ShieldCheckIcon, UsersIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { getStripePublishableKey } from "../../../client/config";
+import { MicroLabel, RoundPageContainer } from "../../../components";
+import { Link } from "../../../shadcnui";
+import { AdministrationProvider } from "../contexts/AdministrationContext";
+import type { AdminGroup, AdminSection } from "../data/admin-section.types";
+
+/**
+ * The sections every NJA project has. Hrefs are constants rather than props:
+ * the path convention IS the contract that makes this component reusable, and
+ * it already exists in the package (see TOKEN_USAGE_ADMIN_PAGE_URL in
+ * features/tokenusage/contexts/TokenUsageAdminContext.tsx).
+ */
+const PLATFORM_SECTIONS: AdminSection[] = [
+  {
+    key: "companies",
+    icon: Building2Icon,
+    labelKey: "entities.companies",
+    labelValues: { count: 2 },
+    descriptionKey: "administration.companies.description",
+    href: "/administration/companies",
+  },
+  {
+    key: "users",
+    icon: UsersIcon,
+    labelKey: "entities.users",
+    labelValues: { count: 2 },
+    descriptionKey: "administration.users.description",
+    href: "/administration/users",
+  },
+  {
+    key: "token-usage",
+    icon: CoinsIcon,
+    labelKey: "token_usage.admin.title",
+    descriptionKey: "administration.token_usage.description",
+    href: "/administration/token-usage",
+  },
+  {
+    key: "rbac",
+    icon: ShieldCheckIcon,
+    labelKey: "entities.rbac",
+    labelValues: { count: 2 },
+    descriptionKey: "administration.rbac.description",
+    href: "/administration/rbac",
+  },
+];
+
+/**
+ * The only conditional entry. getStripePublishableKey comes from /client rather
+ * than isStripeConfigured() from /billing on purpose: /billing exists to keep
+ * Stripe.js out of the global bundle, and isStripeConfigured lives in
+ * StripeProvider.tsx, which imports @stripe/stripe-js at module scope. The two
+ * are the same check — isStripeConfigured is a one-line wrapper over this call.
+ */
+const BILLING_SECTION: AdminSection = {
+  key: "billing",
+  icon: CreditCardIcon,
+  labelKey: "billing.admin.products.title",
+  descriptionKey: "administration.billing.description",
+  href: "/administration/billing",
+};
+
+/** Keys of the built-in platform sections, for `hiddenSections`. */
+export type PlatformSectionKey = "companies" | "users" | "token-usage" | "rbac" | "billing";
+
+type AdminIndexProps = {
+  /** Project-specific groups, appended after the built-in platform group. */
+  additionalGroups?: AdminGroup[];
+  /**
+   * Built-in sections to leave out. Every NJA project gets the same platform
+   * group by default, but a project whose backend does not wire a foundation
+   * must be able to drop its entry rather than advertise a route that throws —
+   * narr8, for instance, never calls `RbacModule.register()`, so it has no RBAC
+   * controllers at all.
+   */
+  hiddenSections?: PlatformSectionKey[];
+};
+
+/**
+ * The grid itself, with no page shell — this is what the specs render, because
+ * RoundPageContainer pulls in the app Header and its four header contexts.
+ */
+export function AdminIndexGrid({ additionalGroups = [], hiddenSections = [] }: AdminIndexProps) {
+  const t = useTranslations();
+
+  const available = getStripePublishableKey() ? [...PLATFORM_SECTIONS, BILLING_SECTION] : PLATFORM_SECTIONS;
+
+  const platformGroup: AdminGroup = {
+    key: "platform",
+    labelKey: "administration.group.platform",
+    sections: available.filter((section) => !hiddenSections.includes(section.key as PlatformSectionKey)),
+  };
+
+  const groups = [platformGroup, ...additionalGroups].filter((group) => group.sections.length > 0);
+
+  return (
+    <div className="mx-auto flex w-full max-w-5xl flex-1 flex-col gap-8 py-8">
+      {/* No page title here: AdministrationProvider feeds "Administration" to
+          RoundPageContainerTitle, which owns the page's name. Repeating it as a
+          role-1 title would triple up with that strip and the breadcrumb. */}
+      <p className="text-muted-foreground text-sm">{t("administration.subtitle")}</p>
+
+      {groups.map((group) => (
+        <div key={group.key}>
+          <MicroLabel as="h3" className="mb-2 px-3">
+            {t(group.labelKey, group.labelValues)}
+          </MicroLabel>
+          <div className="grid grid-cols-1 gap-1 md:grid-cols-2 lg:grid-cols-3">
+            {group.sections.map((section) => (
+              <Link
+                key={section.key}
+                href={section.href}
+                className="text-foreground font-normal"
+                data-testid={`admin-index-${section.key}`}
+              >
+                <div className="hover:bg-muted/50 flex cursor-pointer items-center gap-3 rounded-md px-3 py-2">
+                  <section.icon className="text-muted-foreground h-4 w-4 shrink-0" />
+                  <div className="flex flex-col">
+                    <span className="text-sm font-medium">{t(section.labelKey, section.labelValues)}</span>
+                    <span className="text-muted-foreground text-xs">
+                      {t(section.descriptionKey, section.descriptionValues)}
+                    </span>
+                  </div>
+                </div>
+              </Link>
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Drop-in administration landing page. Mount it bare — it brings its own shell
+ * and its own page chrome (AdministrationProvider), so it does not inherit the
+ * title and breadcrumb of whatever page rendered before it.
+ */
+export function AdminIndexContainer({ additionalGroups, hiddenSections }: AdminIndexProps) {
+  return (
+    <AdministrationProvider>
+      <RoundPageContainer>
+        <AdminIndexGrid additionalGroups={additionalGroups} hiddenSections={hiddenSections} />
+      </RoundPageContainer>
+    </AdministrationProvider>
+  );
+}

package/src/features/administration/components/__tests__/AdminIndexContainer.spec.tsx

@@ -0,0 +1,96 @@
+import { render, screen } from "@testing-library/react";
+import { BookOpenIcon } from "lucide-react";
+import { beforeEach, describe, expect, it } from "vitest";
+import { configureJsonApi } from "../../../../client/config";
+import { configureI18n } from "../../../../i18n";
+import { AdminIndexGrid } from "../AdminIndexContainer";
+import type { AdminGroup } from "../../data/admin-section.types";
+
+// next-intl is globally mocked in vitest.setup.ts with `t = (key) => key`, so
+// every label below renders as its own key. That is what the assertions match.
+const configure = (stripePublishableKey?: string) => {
+  configureJsonApi({ apiUrl: "http://api.test", stripePublishableKey });
+  configureI18n({
+    useRouter: () => ({
+      push: () => {},
+      replace: () => {},
+      back: () => {},
+      forward: () => {},
+      refresh: () => {},
+      prefetch: () => {},
+    }),
+    useTranslations: () => (key: string) => key,
+    usePathname: () => "/administration",
+    Link: ({ href, children, ...props }: any) => (
+      <a href={href} {...props}>
+        {children}
+      </a>
+    ),
+  });
+};
+
+const extraGroup: AdminGroup = {
+  key: "documentation",
+  labelKey: "administration.group.documentation",
+  sections: [
+    {
+      key: "howtos",
+      icon: BookOpenIcon,
+      labelKey: "entities.howtos",
+      labelValues: { count: 2 },
+      descriptionKey: "administration.howtos.description",
+      href: "/administration/howtos",
+    },
+  ],
+};
+
+describe("AdminIndexGrid", () => {
+  beforeEach(() => configure());
+
+  it("renders the four unconditional platform entries with their hrefs", () => {
+    render(<AdminIndexGrid />);
+
+    expect(screen.getByTestId("admin-index-companies")).toHaveAttribute("href", "/administration/companies");
+    expect(screen.getByTestId("admin-index-users")).toHaveAttribute("href", "/administration/users");
+    expect(screen.getByTestId("admin-index-token-usage")).toHaveAttribute("href", "/administration/token-usage");
+    expect(screen.getByTestId("admin-index-rbac")).toHaveAttribute("href", "/administration/rbac");
+  });
+
+  it("omits the billing entry when no Stripe publishable key is configured", () => {
+    render(<AdminIndexGrid />);
+
+    expect(screen.queryByTestId("admin-index-billing")).not.toBeInTheDocument();
+  });
+
+  it("includes the billing entry when a Stripe publishable key is configured", () => {
+    configure("pk_test_123");
+    render(<AdminIndexGrid />);
+
+    expect(screen.getByTestId("admin-index-billing")).toHaveAttribute("href", "/administration/billing");
+  });
+
+  it("appends additionalGroups after the platform group, in order", () => {
+    render(<AdminIndexGrid additionalGroups={[extraGroup]} />);
+
+    const headings = screen.getAllByRole("heading", { level: 3 }).map((h) => h.textContent);
+    expect(headings).toEqual(["administration.group.platform", "administration.group.documentation"]);
+    expect(screen.getByTestId("admin-index-howtos")).toHaveAttribute("href", "/administration/howtos");
+  });
+
+  it("skips a group that has no sections", () => {
+    render(
+      <AdminIndexGrid additionalGroups={[{ key: "empty", labelKey: "administration.group.empty", sections: [] }]} />,
+    );
+
+    expect(screen.queryByText("administration.group.empty")).not.toBeInTheDocument();
+  });
+
+  it("renders the subtitle but not a page title of its own", () => {
+    render(<AdminIndexGrid />);
+
+    expect(screen.getByText("administration.subtitle")).toBeInTheDocument();
+    // The page's name comes from AdministrationProvider via
+    // RoundPageContainerTitle, so the grid must not repeat it.
+    expect(screen.queryByText("administration.title")).not.toBeInTheDocument();
+  });
+});

package/src/features/administration/components/index.ts

@@ -0,0 +1 @@
+export { AdminIndexContainer, AdminIndexGrid } from "./AdminIndexContainer";

package/src/features/administration/contexts/AdministrationContext.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { createContext, ReactNode, useContext } from "react";
+import { SharedProvider } from "../../../contexts/SharedContext";
+import { BreadcrumbItemData } from "../../../interfaces";
+
+interface AdministrationContextType {}
+
+const AdministrationContext = createContext<AdministrationContextType | undefined>(undefined);
+
+type AdministrationProviderProps = {
+  children: ReactNode;
+};
+
+/**
+ * Supplies the page chrome for every administration surface.
+ *
+ * `RoundPageContainerTitle` and the header breadcrumb both read
+ * `useSharedContext()`, and that context is provided far up the tree by the
+ * layout — so an administration page that provides nothing of its own silently
+ * inherits whatever the *previously rendered* page put there (a company name, a
+ * "Notifications" title). Wrapping in this provider replaces that value, which
+ * is why every administration container mounts inside it.
+ *
+ * Mirrors CommonProvider (contexts/CommonContext.tsx), which does the same job
+ * for the ordinary application shell.
+ */
+export const AdministrationProvider = ({ children }: AdministrationProviderProps) => {
+  const t = useTranslations();
+
+  const breadcrumbs: BreadcrumbItemData[] = [];
+
+  return (
+    <SharedProvider value={{ breadcrumbs, title: { type: t(`administration.title`) } }}>
+      <AdministrationContext.Provider value={{}}>{children}</AdministrationContext.Provider>
+    </SharedProvider>
+  );
+};
+
+export const useAdministrationContext = (): AdministrationContextType => {
+  const context = useContext(AdministrationContext);
+  if (context === undefined) {
+    throw new Error("useAdministrationContext must be used within an AdministrationProvider");
+  }
+  return context;
+};

package/src/features/administration/contexts/index.ts

@@ -0,0 +1 @@
+export * from "./AdministrationContext";

package/src/features/administration/data/admin-section.types.ts

@@ -0,0 +1,30 @@
+import { LucideIcon } from "lucide-react";
+
+/**
+ * One row of the administration index: an icon, a translated label and
+ * description, and the route it opens.
+ *
+ * Labels and descriptions are i18n *keys*, never resolved strings, so
+ * AdminIndexGrid stays the single place that calls useTranslations().
+ * `labelValues` / `descriptionValues` carry ICU arguments — `{ count: 2 }` for
+ * the `entities.*` plural keys, or `{ type: "..." }` for an app reusing its own
+ * parameterised heading key.
+ */
+export type AdminSection = {
+  /** Stable React key, and the `admin-index-<key>` test id on the rendered link. */
+  key: string;
+  icon: LucideIcon;
+  labelKey: string;
+  labelValues?: Record<string, string | number>;
+  descriptionKey: string;
+  descriptionValues?: Record<string, string | number>;
+  href: string;
+};
+
+/** A titled block of sections. The built-in "platform" group always renders first. */
+export type AdminGroup = {
+  key: string;
+  labelKey: string;
+  labelValues?: Record<string, string | number>;
+  sections: AdminSection[];
+};

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

@@ -0,0 +1,26 @@
+/**
+ * The fixed namespace of i18n keys the administration index reads via
+ * useTranslations. Consuming apps must define each entry in their
+ * messages/<locale>.json — this list is the contract between the package and
+ * the app, and the names are frozen: an app that wants different wording
+ * changes its own translation, never the key.
+ *
+ * Section LABELS are deliberately absent: they reuse keys every NJA app already
+ * defines — `entities.companies`, `entities.users`, `entities.rbac` (all with
+ * `{ count: 2 }`), `token_usage.admin.title`, and
+ * `billing.admin.products.title` — so section names stay in each app's own
+ * vocabulary.
+ *
+ * Mirrors the contract shipped by the token-usage feature
+ * (features/tokenusage/i18n-keys.ts).
+ */
+export const ADMINISTRATION_I18N_KEYS = [
+  "administration.title",
+  "administration.subtitle",
+  "administration.group.platform",
+  "administration.companies.description",
+  "administration.users.description",
+  "administration.token_usage.description",
+  "administration.rbac.description",
+  "administration.billing.description",
+] as const;

package/src/features/administration/index.ts

@@ -0,0 +1,3 @@
+export * from "./components";
+export * from "./data/admin-section.types";
+export { ADMINISTRATION_I18N_KEYS } from "./i18n-keys";

package/src/features/assistant/components/containers/AssistantPageContainer.tsx

@@ -31,6 +31,12 @@ interface Props {
   /** Rendered inside the sidebar's details panel above the thread list. */
   detailsTitle: string;
   detailsIcon: React.ReactNode;
+  /**
+   * Disables the composer for a reason external to this component (e.g. the
+   * consuming app's credit gate) — ORed with the in-flight `ctx.sending`
+   * disable, never replacing it.
+   */
+  disabled?: boolean;
 }
 
 /**
@@ -47,6 +53,7 @@ export function AssistantPageContainer({
   suggestionMenuComponent,
   detailsTitle,
   detailsIcon,
+  disabled,
 }: Props) {
   const t = useTranslations();
   const ctx = useAssistantContext();
@@ -111,7 +118,7 @@ export function AssistantPageContainer({
         )}
         <AssistantBlockNoteComposer
           onSend={(content, opts) => ctx.sendMessage(content, { contentBlocks: opts.contentBlocks })}
-          disabled={ctx.sending}
+          disabled={ctx.sending || disabled}
           mentionSearchFn={mentionSearchFn}
           mentionSearchParams={mentionSearchParams}
           mentionResolveFn={mentionResolveFn}

package/src/features/billing/contexts/BillingContext.tsx

@@ -0,0 +1,95 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { createContext, ReactNode, useCallback, useContext, useState } from "react";
+import { SharedProvider } from "../../../contexts/SharedContext";
+import { BreadcrumbItemData } from "../../../interfaces";
+import { getRoleId } from "../../../roles";
+import { Button } from "../../../shadcnui";
+import { useCurrentUserContext } from "../../user/contexts";
+import { ProductEditor } from "../stripe-product/components/forms/ProductEditor";
+
+interface BillingContextType {
+  /**
+   * Bumped every time the provider's own actions change the product catalogue.
+   * ProductsAdminContainer reloads on it — the create action lives up here in
+   * the page title bar, so it cannot call the container's loader directly.
+   */
+  refreshToken: number;
+  refresh: () => void;
+}
+
+const BillingContext = createContext<BillingContextType | undefined>(undefined);
+
+type BillingProviderProps = {
+  children: ReactNode;
+};
+
+/**
+ * Page chrome for the administrative billing surface (Stripe products, prices
+ * and their credit allowances).
+ *
+ * Billing gets its own provider rather than borrowing AdministrationProvider so
+ * the page carries its own name — and, like CompanyProvider with CompanyEditor,
+ * it owns the page's ACTIONS: the create-product control is published through
+ * `title.functions`, which RoundPageContainerTitle renders in the header bar.
+ * That is where every other page in this codebase puts its primary action.
+ */
+export const BillingProvider = ({ children }: BillingProviderProps) => {
+  const t = useTranslations();
+  const { hasRole } = useCurrentUserContext();
+  const [showCreateProduct, setShowCreateProduct] = useState<boolean>(false);
+  const [refreshToken, setRefreshToken] = useState<number>(0);
+
+  const refresh = useCallback(() => setRefreshToken((value) => value + 1), []);
+
+  // No href: this crumb IS the current page. Linking it would also point at the
+  // StripeProduct module's `pageUrl` (/stripe-products), which no consuming app
+  // routes — the page lives under the administration tree.
+  const breadcrumbs: BreadcrumbItemData[] = [{ name: t(`billing.admin.products.title`) }];
+
+  const title = () => {
+    const response: any = { type: t(`billing.admin.products.title`) };
+
+    if (hasRole(getRoleId().Administrator)) {
+      response.functions = [
+        <Button key="productEditorTrigger" onClick={() => setShowCreateProduct(true)}>
+          {t(`billing.admin.products.create`)}
+        </Button>,
+        showCreateProduct ? (
+          <ProductEditor
+            key="productEditor"
+            open={showCreateProduct}
+            onOpenChange={setShowCreateProduct}
+            onSuccess={() => {
+              setShowCreateProduct(false);
+              refresh();
+            }}
+          />
+        ) : null,
+      ];
+    }
+
+    return response;
+  };
+
+  return (
+    <SharedProvider value={{ breadcrumbs, title: title() }}>
+      <BillingContext.Provider value={{ refreshToken, refresh }}>{children}</BillingContext.Provider>
+    </SharedProvider>
+  );
+};
+
+export const useBillingContext = (): BillingContextType => {
+  const context = useContext(BillingContext);
+  if (context === undefined) {
+    throw new Error("useBillingContext must be used within a BillingProvider");
+  }
+  return context;
+};
+
+/**
+ * Non-throwing variant. ProductsAdminContainer predates this provider and is
+ * still mounted bare by other consumers, so it must keep working without one.
+ */
+export const useOptionalBillingContext = (): BillingContextType | undefined => useContext(BillingContext);

package/src/features/billing/contexts/index.ts

@@ -0,0 +1 @@
+export * from "./BillingContext";

package/src/features/billing/index.ts

@@ -1,3 +1,4 @@
 export * from "./components";
+export * from "./contexts";
 export * from "./data";
 export * from "./modules";