@evenicanpm/portal-table-ui 1.5.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@evenicanpm/portal-table-ui",
-	"version": "1.5.0",
+	"version": "1.7.0",
 	"description": "",
 	"license": "ISC",
 	"author": "",
@@ -16,7 +16,8 @@
 	},
 	"types": "./dist/index.d.ts",
 	"files": [
-		"dist"
+		"dist",
+		"src"
 	],
 	"devDependencies": {
 		"@emotion/react": "^11.11.3",
@@ -40,11 +41,11 @@
 	},
 	"dependencies": {
 		"@arrows/multimethod": "^2.1.0",
-		"@evenicanpm/portal-types-schemas": "^1.5.0",
-		"@evenicanpm/ui": "^1.4.0",
+		"@evenicanpm/portal-types-schemas": "^1.7.0",
+		"@evenicanpm/ui": "^1.6.0",
 		"@mui/lab": "^7.0.1-beta.19",
 		"@tanstack/react-query": "^5.90.11",
 		"date-fns": "^4.1.0"
 	},
-	"gitHead": "5c5e3fe19b92a17cbaf897b4cee20ee59331603f"
+	"gitHead": "2e25d32705901a4ff2dd43aa420fde931568ad93"
 }

package/src/auth/auth-context.tsx

@@ -0,0 +1,92 @@
+import {
+	createContext,
+	type PropsWithChildren,
+	useContext,
+	useMemo,
+} from "react";
+
+// --- 1. Types --- //
+/**
+ * Powers the auth provider that portal is wrapped in
+ * Aggregates user and session related data that is needed
+ * within the portal
+ */
+interface AuthProviderProps {
+	/** The user details returned from auth framework eg. next-auth **/
+	session: Session;
+	/** how to handle logout **/
+	logout: () => void;
+}
+
+/**
+ * The context value
+ */
+interface AuthContext {
+	session: Session | null;
+	/** how to handle logout **/
+	logout: (() => void) | null;
+	isAuthenticated: boolean | null;
+}
+
+/*
+ * Session details returned from authentication
+ *
+ */
+interface Session {
+	email: string | null | undefined;
+	name: string | null | undefined;
+	token: string | null | undefined;
+}
+
+// --- 2. Context --- //
+const AuthContext = createContext<AuthContext>({
+	session: null,
+	logout: null,
+	isAuthenticated: null,
+});
+
+// --- 3. Hook --- //
+/**
+ * Used to access auth details and callback handlers within the portal auth context
+ */
+const useAuth = () => {
+	const context = useContext(AuthContext);
+	if (!context) {
+		// This error helps developers debug if they forget to wrap the component.
+		throw new Error("useAuth must be used within a PortalAuthProvider");
+	}
+	return context;
+};
+
+// --- Provider --- //
+/**
+ *
+ */
+const PortalAuthProvider = ({
+	session,
+	logout,
+	children,
+}: PropsWithChildren<AuthProviderProps>) => {
+	const isAuthenticated = !!session?.email;
+
+	const authValue = useMemo(
+		() => ({
+			isAuthenticated,
+			session,
+			logout,
+		}),
+		[isAuthenticated, session, logout],
+	);
+
+	return (
+		<AuthContext.Provider value={authValue}>{children}</AuthContext.Provider>
+	);
+};
+
+export {
+	PortalAuthProvider,
+	useAuth,
+	type AuthProviderProps,
+	AuthContext,
+	type Session,
+};

package/src/features/table/components/dashboard/table/bulk-action-button.tsx

@@ -0,0 +1,77 @@
+import { Badge, Button, CircularProgress, IconButton } from "@mui/material";
+import { useMutation } from "@tanstack/react-query";
+import type { Row } from "src/features/table/types/queries";
+import type { UIBulkAction } from "src/features/table/types/schemas";
+
+interface BulkActionButtonProps {
+	action: UIBulkAction;
+	resourceName: string;
+	selectedIds: (string | number)[];
+	clearSelection: () => void;
+	selectedRows: Row[];
+}
+export function BulkActionButton({
+	action,
+	resourceName,
+	selectedIds,
+	clearSelection,
+	selectedRows,
+}: BulkActionButtonProps) {
+	const mutationOptions = action.mutation({
+		resourceName,
+		selectedIds,
+	});
+
+	const allowed = !action.isAllowed || action.isAllowed(selectedRows);
+	const { mutate, isPending } = useMutation(mutationOptions);
+
+	const handleClick = () => {
+		mutate(undefined, {
+			onSuccess: () => {
+				clearSelection();
+			},
+		});
+	};
+
+	const Icon = action.icon;
+
+	if (Icon) {
+		return (
+			<IconButton
+				size="small"
+				onClick={handleClick}
+				disabled={isPending || selectedIds.length === 0 || !allowed}
+				sx={{
+					border: 1,
+					borderRadius: 1,
+					paddingInline: 2,
+					minHeight: "fit-content",
+				}}
+			>
+				{isPending ? (
+					<CircularProgress size={26} />
+				) : (
+					<Badge badgeContent={selectedIds.length} color="primary">
+						<Icon />
+					</Badge>
+				)}
+			</IconButton>
+		);
+	}
+
+	return (
+		<Button
+			variant="contained"
+			onClick={handleClick}
+			size="large"
+			sx={{ textWrap: "nowrap", minHeight: "fit-content" }}
+			disabled={isPending || selectedIds.length === 0 || !allowed}
+		>
+			{isPending ? (
+				<CircularProgress size={22} />
+			) : (
+				`${action.label} (${selectedIds.length})`
+			)}
+		</Button>
+	);
+}

package/src/features/table/components/dashboard/table/data-mask-map.ts

@@ -0,0 +1,26 @@
+"use client";
+import { format } from "date-fns";
+import type * as Table from "../../../types/";
+
+export const dataMaskMap: Table.Handlers.DataMaskMap = {
+	// DATE TIME HAS SPECIFIC MASK HANDLING
+	datetime: (value: string | number, _dataMask: string) => {
+		return format(new Date(value), "MM/dd/yyyy");
+	},
+	date: (value: string | number, _dataMask: string) => {
+		return format(new Date(value), "MM/dd/yyyy");
+	},
+	numeric: (value: string | number, dataMask: string) => {
+		// IS CURRENCY?
+		if (dataMask.includes("$")) {
+			// Very generic stub... project fill out.
+			return new Intl.NumberFormat("en-US", {
+				style: "currency",
+				currency: "USD",
+			}).format(Number(value));
+		}
+		// IS ...X?
+		// IS ...Y?
+		return String(value);
+	},
+};

package/src/features/table/components/dashboard/table/details/details.tsx

@@ -0,0 +1,185 @@
+"use client";
+import { method, multi } from "@arrows/multimethod";
+import type { Column } from "@evenicanpm/portal-types-schemas";
+import { FlexBox, H6, Subtitle } from "@evenicanpm/ui";
+import ArrowBackIcon from "@mui/icons-material/ArrowBack";
+import { Box, Button } from "@mui/material";
+import Grid from "@mui/material/Grid2";
+import { resolvers, transformers } from "../../../../logic";
+import type * as Types from "../../../../types";
+import type { StatusColorMap, StatusTextMap } from "../../../../types/schemas";
+import { StatusPill } from "../status-pill";
+import { DetailsRowLabel } from "./label";
+import { DetailsDownloads, DetailsPrimitive, DetailsTable } from "./rows";
+import { detailsTemplateRegistry } from "./templates/template-registry";
+
+interface DetailsProps {
+	/** What do we do when use clicks back button? */
+	handleBack: () => void;
+	/** What is the id field name */
+	id: string | number;
+	/** The actual pojo of data from the API */
+	documentData: Types.Queries.Row | unknown;
+	/* the label of the document type ie 'INVOICES' */
+	documentTypeLabel: string;
+	/** Special instructions for how to render certain properties */
+	detailsRenderMap?: Types.Handlers.DetailsRenderMap;
+	/** Data mask map */
+	dataMaskMap: Types.Handlers.DataMaskMap;
+	/** Table columns **/
+	columns: Column[];
+	/** */
+	statusColorMap: StatusColorMap;
+	/** */
+	statusTextMap: StatusTextMap;
+	template?: string;
+	loading?: boolean;
+}
+
+/**
+ * The Details Page
+ */
+const Details = ({
+	id,
+	documentTypeLabel,
+	documentData,
+	handleBack,
+	columns,
+	dataMaskMap,
+	statusColorMap,
+	statusTextMap,
+	template,
+	loading = false,
+}: DetailsProps) => {
+	// Resolve the template component once — undefined when the key is absent or
+	// not found in the registry, which gracefully falls back to the generic view.
+	const TemplateComponent = template
+		? detailsTemplateRegistry[template]
+		: undefined;
+
+	const visibleDetails = transformers.getVisibleDetails(columns);
+
+	// Pre-compute primitive items only when the generic grid is needed
+	const primitiveItems = TemplateComponent
+		? undefined
+		: visibleDetails?.map((col) => ({
+				key: col.Data,
+				value: (documentData as Types.Queries.Row)?.[col.Data],
+				maskFn: resolvers.resolveDataMask(col, dataMaskMap),
+				mask: col.DataMask,
+				col,
+			}));
+
+	return (
+		<Box>
+			<Box height={48} sx={{ borderBottom: 1, borderColor: "divider" }}>
+				<FlexBox
+					alignItems="center"
+					justifyContent="space-between"
+					mb={2}
+					height="100%"
+				>
+					<Button onClick={handleBack} startIcon={<ArrowBackIcon />}>
+						{documentTypeLabel}
+					</Button>
+					<H6 color="grey.800">
+						{documentTypeLabel}-{id}
+					</H6>
+					<Subtitle>DETAILS</Subtitle>
+				</FlexBox>
+			</Box>
+
+			<Box mt={2}>
+				{TemplateComponent ? (
+					<TemplateComponent
+						data={documentData}
+						statusColorMap={statusColorMap}
+						statusTextMap={statusTextMap}
+						loading={loading}
+					/>
+				) : (
+					<Grid container spacing={2}>
+						{primitiveItems?.map((col) => {
+							const maskedValue = col.maskFn(col.value, col.mask);
+							const Component = getRowComponent(maskedValue, col.key);
+							const sx = getRowLayout(maskedValue, col.key);
+							return (
+								<Grid key={col.key} {...sx}>
+									<DetailsRowLabel label={col.col.Label} />
+									<Component
+										value={maskedValue}
+										label={col.key}
+										column={col.col}
+										dataMaskMap={dataMaskMap}
+										statusColorMap={statusColorMap}
+										statusTextMap={statusTextMap}
+										status={col.value}
+									/>
+								</Grid>
+							);
+						})}
+					</Grid>
+				)}
+			</Box>
+		</Box>
+	);
+};
+
+/**
+ * Default renders.
+ *
+ * -- What do we render? --
+ *
+ */
+const detailsRenders = {
+	DOCUMENTS: DetailsDownloads,
+	PRIMITIVE: DetailsPrimitive,
+	OBJECT: DetailsTable,
+	STATUS: StatusPill,
+};
+
+/**
+ * Multi-method to resolve the renders.
+ *
+ * -- How do we know what to render? --
+ *
+ */
+const detailTypeDispatch = (detail: Types.Queries.Row, col: string) => {
+	if (col === "Documents") return "DOCUMENTS";
+	if (col === "Status") return "STATUS";
+	if (typeof detail === "string" || typeof detail === "number")
+		return "PRIMITIVE";
+	if (Array.isArray(detail)) return "OBJECT";
+};
+
+/**
+ * Multi-method to resolve the renders.
+ *
+ * -- what do we render? --
+ *
+ */
+const getRowComponent = multi(
+	detailTypeDispatch,
+	method("PRIMITIVE", () => detailsRenders.PRIMITIVE),
+	method("DOCUMENTS", () => detailsRenders.DOCUMENTS),
+	method("OBJECT", () => detailsRenders.OBJECT),
+	method("STATUS", () => detailsRenders.STATUS),
+);
+
+/**
+ * Multi-method to resolve layout styles
+ *
+ * -- what do we render? --
+ */
+const getRowLayout = multi(
+	detailTypeDispatch,
+	method("PRIMITIVE", () => ({ size: 6, display: "flex" })),
+	method("STATUS", () => ({ size: 6, display: "flex" })),
+	method("DOCUMENTS", () => ({ size: 12 })),
+	method("OBJECT", () => ({ size: 12 })),
+);
+
+// Note: another way to dispatch table is
+// if the column has a children property
+
+export { Details };

package/src/features/table/components/dashboard/table/details/label.tsx

@@ -0,0 +1,26 @@
+"use client";
+
+import { Typography } from "@mui/material";
+
+interface Props {
+	label: string;
+}
+
+const DetailsRowLabel = (props: Props) => {
+	const { label } = props;
+	return (
+		<Typography
+			variant="subtitle2"
+			color="text.secondary"
+			sx={{
+				minWidth: 150,
+				fontWeight: 600,
+				alignSelf: "flex-start",
+			}}
+		>
+			{label}:
+		</Typography>
+	);
+};
+
+export { DetailsRowLabel };

package/src/features/table/components/dashboard/table/details/rows/downloads.tsx

@@ -0,0 +1,25 @@
+import FileDownloadOutlinedIcon from "@mui/icons-material/FileDownloadOutlined";
+import { Button, Stack } from "@mui/material";
+
+interface Props {
+	value: string[];
+}
+
+const DetailsDownloads = ({ value }: Props) => (
+	<Stack spacing={1} sx={{ mt: 1 }}>
+		{value?.map((doc: string) => (
+			<Button
+				key={doc}
+				variant="outlined"
+				size="small"
+				startIcon={<FileDownloadOutlinedIcon />}
+				onClick={() => window.open(doc, "_blank")}
+				sx={{ justifyContent: "flex-start" }}
+			>
+				Download Document
+			</Button>
+		))}
+	</Stack>
+);
+
+export { DetailsDownloads };

package/src/features/table/components/dashboard/table/details/rows/primitive.tsx

@@ -0,0 +1,25 @@
+"use client";
+
+import { Box } from "@mui/material";
+
+interface Props {
+	value: string | number;
+}
+
+const DetailsPrimitive = (props: Props) => {
+	const { value } = props;
+	return (
+		<Box
+			sx={{
+				mb: 2,
+				display: "flex",
+				alignItems: "flex-start",
+				gap: 2,
+			}}
+		>
+			<Box sx={{ flex: 1 }}>{value}</Box>
+		</Box>
+	);
+};
+
+export { DetailsPrimitive };

package/src/features/table/components/dashboard/table/details/rows/table.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import type { Column } from "@evenicanpm/portal-types-schemas";
+import {
+	Table,
+	TableBody,
+	TableCell,
+	TableContainer,
+	TableHead,
+	TableRow,
+} from "@mui/material";
+import { resolvers } from "../../../../../logic";
+import type { DataMaskMap } from "../../../../../types/handlers";
+
+interface Props {
+	column: Column;
+	value: Record<string, string>[];
+	dataMaskMap: DataMaskMap;
+}
+
+/**
+ * Simple table that takes an array of records,
+ * builds array of columns from first index and then loops
+ * builds table values from rest of the indexes.
+ * @param props
+ * @returns
+ */
+const DetailsTable = (props: Props) => {
+	const { value: rows, dataMaskMap, column } = props;
+
+	// call resolvers ahead of time on each column once
+	// then they are pre-resolved and ready to be used
+	// in render body.
+	const preparedCols = column?.Children?.map((col) => ({
+		key: col?.Data,
+		maskFn: resolvers.resolveDataMask(col, dataMaskMap),
+		mask: col?.DataMask,
+	}));
+
+	return (
+		<TableContainer sx={{ my: 2 }}>
+			<Table size="small" sx={{ mt: 1, p: 0 }}>
+				<TableHead>
+					<TableRow>
+						{Object.keys(rows[0])?.map((key) => (
+							<TableCell key={key} sx={{ fontWeight: 600 }}>
+								{key}
+							</TableCell>
+						))}
+					</TableRow>
+				</TableHead>
+				<TableBody>
+					{rows.map((row) => {
+						return (
+							<TableRow key={row?.key + row?.value}>
+								{preparedCols?.map((col) => (
+									<TableCell
+										key={col?.key + row?.key + row?.value}
+										align={"left"}
+									>
+										{col.maskFn(row?.[col?.key], col.mask)}
+									</TableCell>
+								))}
+							</TableRow>
+						);
+					})}
+				</TableBody>
+			</Table>
+		</TableContainer>
+	);
+};
+
+export { DetailsTable };

package/{dist/features/table/components/dashboard/table/details/styles.d.ts → src/features/table/components/dashboard/table/details/styles.ts}

@@ -1,10 +1,18 @@
 import type { StyledComponent } from "@emotion/styled";
-import { type BoxProps } from "@mui/material";
+import { Box, type BoxProps } from "@mui/material";
+import { styled } from "@mui/material/styles";
+
 /**
  * Explicit type annotation is required here to prevent TS2742.
  * Without it, TypeScript tries to infer complex internal types from nested
  * node_modules (@mui/system), which leads to non-portable type definitions
  * in monorepo or library builds.
  */
-declare const DetailsRowBox: StyledComponent<BoxProps>;
+const DetailsRowBox: StyledComponent<BoxProps> = styled(Box)({
+	mb: 2,
+	display: "flex",
+	alignItems: "flex-start",
+	gap: 2,
+});
+
 export { DetailsRowBox };