@carlonicora/nextjs-jsonapi 2.3.0 → 2.4.0

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";

package/src/features/billing/stripe-product/components/containers/ProductsAdminContainer.tsx

@@ -5,6 +5,7 @@ import { useEffect, useState } from "react";
 import { getRoleId } from "../../../../../roles";
 import { Button } from "../../../../../shadcnui";
 import { useCurrentUserContext } from "../../../../user/contexts";
+import { useOptionalBillingContext } from "../../../contexts/BillingContext";
 import { StripeProductInterface } from "../../data/stripe-product.interface";
 import { StripeProductService } from "../../data/stripe-product.service";
 import { ProductEditor } from "../forms/ProductEditor";
@@ -12,6 +13,10 @@ import { ProductsList } from "../lists/ProductsList";
 
 export function ProductsAdminContainer() {
   const { hasRole } = useCurrentUserContext();
+  // Optional on purpose: the create action lives in BillingProvider's title
+  // functions when this container is a page, but the container is still mounted
+  // bare elsewhere, where it keeps its own inline create button.
+  const billing = useOptionalBillingContext();
   const [products, setProducts] = useState<StripeProductInterface[]>([]);
   const [loading, setLoading] = useState<boolean>(true);
   const [showCreateProduct, setShowCreateProduct] = useState<boolean>(false);
@@ -37,9 +42,10 @@ export function ProductsAdminContainer() {
     }
   };
 
+  // Reloads on mount and whenever the provider's create action succeeds.
   useEffect(() => {
     loadProducts();
-  }, []);
+  }, [billing?.refreshToken]);
 
   if (loading) {
     return (
@@ -50,37 +56,43 @@ export function ProductsAdminContainer() {
   }
 
   return (
-    <div className="flex w-full flex-col gap-y-6">
-      {/* Header */}
-      <div className="flex items-center justify-between">
-        <div className="flex items-center gap-x-3">
-          <Package className="h-8 w-8" />
-          <h1 className="text-primary text-3xl font-semibold">Product & Price Management</h1>
+    <div className="flex w-full flex-col">
+      {/* No header here. The page name and the create action belong to
+          BillingProvider, which publishes them through `title.functions` for
+          RoundPageContainerTitle to render — the same way CompanyProvider
+          publishes CompanyEditor. A header drawn inside the content would
+          duplicate the title bar and strand the button above the list. */}
+      {/* Fallback for consumers mounting this container without BillingProvider:
+          they have no title bar to host the action, so it stays inline. */}
+      {!billing && (
+        <div className="flex w-full items-center justify-end px-4 pt-4">
+          <Button onClick={() => setShowCreateProduct(true)}>Create Product</Button>
         </div>
-        <Button onClick={() => setShowCreateProduct(true)}>Create Product</Button>
-      </div>
+      )}
 
-      {/* Empty State */}
-      {products.length === 0 && (
-        <div className="bg-muted/50 flex flex-col items-center justify-center gap-y-4 rounded-lg border-2 border-dashed p-12">
-          <Package className="text-muted-foreground h-16 w-16" />
-          <div className="text-center">
-            <h3 className="mb-2 text-sm font-medium">No products yet</h3>
-            <p className="text-muted-foreground mb-4">
-              Create your first product to start offering subscriptions to your customers.
-            </p>
-            <Button onClick={() => setShowCreateProduct(true)}>Create Your First Product</Button>
+      <div className="flex w-full flex-col gap-y-6 px-4 pb-4">
+        {/* Empty State */}
+        {products.length === 0 && (
+          <div className="bg-muted/50 flex flex-col items-center justify-center gap-y-4 rounded-lg border-2 border-dashed p-12">
+            <Package className="text-muted-foreground h-16 w-16" />
+            <div className="text-center">
+              <h3 className="mb-2 text-sm font-medium">No products yet</h3>
+              <p className="text-muted-foreground mb-4">
+                Create your first product to start offering subscriptions to your customers.
+              </p>
+              <Button onClick={() => setShowCreateProduct(true)}>Create Your First Product</Button>
+            </div>
           </div>
-        </div>
-      )}
+        )}
 
-      {/* Products List */}
-      {products.length > 0 && <ProductsList products={products} onProductsChange={loadProducts} />}
+        {/* Products List */}
+        {products.length > 0 && <ProductsList products={products} onProductsChange={loadProducts} />}
 
-      {/* Create Product Modal */}
-      {showCreateProduct && (
-        <ProductEditor open={showCreateProduct} onOpenChange={setShowCreateProduct} onSuccess={loadProducts} />
-      )}
+        {/* Create Product Modal */}
+        {showCreateProduct && (
+          <ProductEditor open={showCreateProduct} onOpenChange={setShowCreateProduct} onSuccess={loadProducts} />
+        )}
+      </div>
     </div>
   );
 }

package/src/features/billing/stripe-product/components/containers/ProductsAdminPageContainer.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+import { RoundPageContainer } from "../../../../../components";
+import { Modules } from "../../../../../core";
+import { BillingProvider } from "../../../contexts/BillingContext";
+import { ProductsAdminContainer } from "./ProductsAdminContainer";
+
+/**
+ * Page shell around the Stripe product/price administration surface.
+ *
+ * Client component by necessity: `module={Modules.StripeProduct}` is a registry
+ * entry with an icon component and methods, which a Server Component cannot pass
+ * across the boundary.
+ */
+export function ProductsAdminPageContainer() {
+  return (
+    <BillingProvider>
+      {/* forceHeader, unlike the sibling list pages: those get their header row
+          (title + actions) from ContentListTable, and this page has no table.
+          The strip is what renders BillingProvider's title and its create-product
+          action — the same arrangement TokenUsageAdminContainer uses. */}
+      <RoundPageContainer module={Modules.StripeProduct} fullWidth forceHeader>
+        <ProductsAdminContainer />
+      </RoundPageContainer>
+    </BillingProvider>
+  );
+}

package/src/features/billing/stripe-product/components/containers/index.ts

@@ -1 +1,2 @@
 export * from "./ProductsAdminContainer";
+export * from "./ProductsAdminPageContainer";

package/src/features/company/components/containers/CompaniesListContainer.tsx

@@ -0,0 +1,25 @@
+"use client";
+
+import { RoundPageContainer } from "../../../../components";
+import { Modules } from "../../../../core";
+import { CompanyProvider } from "../../contexts/CompanyContext";
+import { CompaniesList } from "../lists/CompaniesList";
+
+/**
+ * Page container for the administrative company list.
+ *
+ * This has to be a client component: `module={Modules.Company}` is a registry
+ * entry carrying an icon component and methods, and a Server Component cannot
+ * pass it across the boundary ("Only plain objects can be passed to Client
+ * Components"). Routes mount this container instead — the same shape as every
+ * other list page.
+ */
+export function CompaniesListContainer() {
+  return (
+    <CompanyProvider>
+      <RoundPageContainer module={Modules.Company} fullWidth>
+        <CompaniesList fullWidth />
+      </RoundPageContainer>
+    </CompanyProvider>
+  );
+}

package/src/features/company/components/containers/index.ts

@@ -1,2 +1,3 @@
 export * from "./AdminCompanyContainer";
+export * from "./CompaniesListContainer";
 export * from "./CompanyContainer";

package/src/features/company/components/lists/CompaniesList.tsx

@@ -9,7 +9,17 @@ import { CompanyFields, CompanyInterface } from "../../data";
 import { CompanyService } from "../../data/company.service";
 import { CompanyEditor } from "../forms/CompanyEditor";
 
-export function CompaniesList() {
+type CompaniesListProps = {
+  /**
+   * Pass this whenever the list is the page's own content inside a
+   * `RoundPageContainer fullWidth`. Without it ContentListTable wraps itself in
+   * `rounded-md border`, drawing a second bordered card inside the page's
+   * rounded shell — two borders fighting each other at every corner.
+   */
+  fullWidth?: boolean;
+};
+
+export function CompaniesList({ fullWidth }: CompaniesListProps = {}) {
   const t = useTranslations();
 
   const data: DataListRetriever<CompanyInterface> = useDataListRetriever({
@@ -26,6 +36,7 @@ export function CompaniesList() {
       fields={[CompanyFields.name]}
       tableGeneratorType={Modules.Company}
       functions={functions}
+      fullWidth={fullWidth}
       title={t(`entities.companies`, { count: 2 })}
     />
   );

package/src/features/company/contexts/CompanyContext.tsx

@@ -43,10 +43,22 @@ export const CompanyProvider = ({ children, dehydratedCompany, configurationEdit
   const breadcrumb = () => {
     const response: BreadcrumbItemData[] = [];
 
+    // The list root always comes first, exactly as UserProvider does it —
+    // without it the company list rendered a breadcrumb of just "Home", while
+    // every sibling administration page showed its own name.
+    //
+    // Linked ONLY when it is not the current page: the Company module's
+    // `pageUrl` is /companies, which the administration tree does not route, so
+    // a link from the list itself would land on a 404.
+    response.push({
+      name: t(`entities.companies`, { count: 2 }),
+      ...(company ? { href: generateUrl({ page: Modules.Company }) } : {}),
+    });
+
     if (company)
       response.push({
         name: company.name,
-        href: generateUrl({ page: Modules.Company }),
+        href: generateUrl({ page: Modules.Company, id: company.id }),
       });
 
     return response;

package/src/features/user/components/containers/PlatformUsersContainer.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import { RoundPageContainer } from "../../../../components";
+import { Modules } from "../../../../core";
+import { UserProvider } from "../../contexts/UserContext";
+import { PlatformUsersList } from "../lists/PlatformUsersList";
+
+/**
+ * Page container for the platform-wide (cross-company) user list.
+ *
+ * Client component by necessity: `module={Modules.User}` is a registry entry
+ * with an icon component and methods, which a Server Component cannot pass
+ * across the boundary.
+ */
+export function PlatformUsersContainer() {
+  return (
+    <UserProvider>
+      <RoundPageContainer module={Modules.User} fullWidth>
+        <PlatformUsersList fullWidth />
+      </RoundPageContainer>
+    </UserProvider>
+  );
+}

package/src/features/user/components/containers/index.ts

@@ -1,4 +1,5 @@
 export * from "./AllUsersListContainer";
+export * from "./PlatformUsersContainer";
 export * from "./UserContainer";
 export * from "./UserIndexContainer";
 export * from "./UsersListContainer";

package/src/features/user/components/lists/PlatformUsersList.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { ContentListTable } from "../../../../components";
+import { Modules } from "../../../../core";
+import { DataListRetriever, useDataListRetriever } from "../../../../hooks";
+import { UserFields, UserInterface } from "../../data";
+import { UserService } from "../../data/user.service";
+
+type PlatformUsersListProps = {
+  includeDeleted?: boolean;
+  fullWidth?: boolean;
+};
+
+/**
+ * Every user on the platform, across all companies.
+ *
+ * Deliberately NOT company-scoped: `CompanyUsersList` and `AdminUsersList` both
+ * build `/companies/{id}/users` and need a company in context, so they render
+ * nothing for a system administrator — who has no Company. This one calls
+ * `UserService.findMany`, which hits `GET /users`; that controller widens the
+ * result set itself when the caller holds Administrator or CompanyAdministrator
+ * (see the backend user controller's `isAdmin` flag), so the same component is
+ * safe for both.
+ */
+export function PlatformUsersList({ includeDeleted, fullWidth }: PlatformUsersListProps) {
+  const t = useTranslations();
+
+  const data: DataListRetriever<UserInterface> = useDataListRetriever({
+    retriever: (params) => UserService.findMany(params),
+    retrieverParams: { includeDeleted: includeDeleted },
+    module: Modules.User,
+  }) as DataListRetriever<UserInterface>;
+
+  return (
+    <ContentListTable
+      data={data}
+      fields={[UserFields.name, UserFields.email, UserFields.company]}
+      tableGeneratorType={Modules.User}
+      fullWidth={fullWidth}
+      allowSearch
+      title={t(`entities.users`, { count: 2 })}
+    />
+  );
+}

package/src/features/user/components/lists/index.ts

@@ -1,5 +1,6 @@
 export * from "./AdminUsersList";
 export * from "./CompanyUsersList";
+export * from "./PlatformUsersList";
 export * from "./ContributorsList";
 export * from "./RelevantUsersList";
 export * from "./RoleUsersList";

package/src/features/user/data/user.fields.ts

@@ -2,6 +2,7 @@ export enum UserFields {
   userId = "userId",
   name = "name",
   email = "email",
+  company = "company",
   relevance = "relevance",
   createdAt = "createdAt",
   updatedAt = "updatedAt",

package/src/features/user/hooks/useUserTableStructure.tsx

@@ -68,6 +68,23 @@ export const useUserTableStructure: UseTableStructureHook<UserInterface, UserFie
       enableSorting: false,
       enableHiding: false,
     }),
+    // Only meaningful on a platform-wide list (PlatformUsersList), where users
+    // from every company sit in one table; a company-scoped list would repeat
+    // the same value on every row.
+    [UserFields.company]: () => ({
+      id: "company",
+      accessorKey: "company",
+      header: t(`entities.companies`, { count: 1 }),
+      cell: ({ row }: { row: Row<TableContent<UserInterface>> }) => {
+        const company = (row.original.jsonApiData as UserInterface).company;
+
+        if (!company) return <span className="text-muted-foreground text-xs">—</span>;
+
+        return <Link href={generateUrl({ page: Modules.Company, id: company.id })}>{company.name}</Link>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
     [UserFields.relevance]: () => ({
       id: "relevance",
       accessorKey: "relevance",