@evenicanpm/portal-table-ui 1.5.0 → 1.6.0

package/src/features/table/logic/resolvers.ts

@@ -0,0 +1,68 @@
+import { method, multi } from "@arrows/multimethod";
+import type { Column } from "@evenicanpm/portal-types-schemas";
+import type * as Types from "../types";
+import type { FilterRequest } from "./types";
+
+/** MULTIMETHOD FOR FILTERS
+ * Allows multiple implementations
+ * based on multiple column properties.
+ * Priotizes column name, but also can
+ * use data type
+ * @internal
+ */
+export const resolveFilterUI = multi(
+	(req: FilterRequest, handlers: Types.Handlers.FilterRenderMap) => {
+		if (handlers?.[req.filterName]) return "BY_NAME";
+		if (handlers?.[req.filterType]) return "BY_TYPE";
+		return "NONE";
+	},
+	method(
+		"BY_NAME",
+		(req: FilterRequest, handlers: Types.Handlers.FilterRenderMap) =>
+			handlers[req.filterName],
+	),
+	method(
+		"BY_TYPE",
+		(req: FilterRequest, handlers: Types.Handlers.FilterRenderMap) =>
+			handlers[req.filterType],
+	),
+	method("NONE", () => () => null),
+);
+
+/**
+ * Dispatch identifies which properties are
+ * in handler, then provides corresponding method
+ * @internal
+ */
+export const resolveDataMask = multi(
+	(col: Column, handlers: Types.Handlers.DataMaskMap) => {
+		if (!col?.DataMask) return "SKIP";
+		if (handlers?.[col?.DataType]) return "BY_TYPE";
+		if (handlers?.[col?.Data]) return "BY_NAME";
+		return "SKIP";
+	},
+	method(
+		"BY_TYPE",
+		(col: Column, handlers: Types.Handlers.DataMaskMap) =>
+			handlers?.[col?.DataType],
+	),
+	method(
+		"BY_NAME",
+		(col: Column, handlers: Types.Handlers.DataMaskMap) =>
+			handlers?.[col?.Data],
+	),
+	method("SKIP", () => (value: string | number) => value),
+);
+
+/**
+ * Simpler, doesn't need multimethod cause only dispatches on column name
+ * @internal
+ */
+export const resolveCellUI = (
+	col: Column,
+	handlers: Types.Handlers.CellRenderMap,
+) => {
+	if (Object.hasOwn(handlers, col.Data)) return handlers?.[col?.Data];
+
+	return (value: string | number) => value;
+};

package/src/features/table/logic/transformers.ts

@@ -0,0 +1,56 @@
+import type { Column } from "@evenicanpm/portal-types-schemas";
+
+/**
+ * These are pure static functions that include business rules
+ * and data manipulation to get the data into the correct
+ * form for rendering.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Gets filters and returns an array of the
+ * active filters and corresponding options
+ * in FilterRequest
+ */
+export const getActiveFilters = (columns: Column[] | undefined) => {
+	return columns
+		?.filter((c) => c?.IsFilterable)
+		?.flatMap((c) =>
+			c?.Filters?.map((f) => ({
+				filterName: c.Data,
+				filterOptions: f.FilterOptions,
+				filterType: f.FilterType ?? c.DataType,
+			})),
+		);
+};
+
+/**
+ * Filters and sorts visible cols
+ */
+export const getVisibleColumns = (columns: Column[] | undefined) =>
+	columns
+		?.filter(
+			(column): column is Column & { ColumnOrder: number } =>
+				typeof column.ColumnOrder === "number",
+		)
+		.sort((a, b) => a.ColumnOrder - b.ColumnOrder);
+
+/**
+ *
+ */
+export const getVisibleDetails = (columns: Column[] | undefined) =>
+	columns
+		?.filter((col) => col.DisplayOrder)
+		?.sort((a, b) => {
+			if (a?.DisplayOrder && b?.DisplayOrder) {
+				return a?.DisplayOrder - b?.DisplayOrder;
+			}
+			return -1;
+		});
+
+/**
+ * Filters and sorts visible cols
+ */
+export const getSearchableColumns = (columns: Column[] | undefined) =>
+	columns?.filter((column) => column?.IsSearchable);

package/src/features/table/logic/types.ts

@@ -0,0 +1,8 @@
+/**
+ * FILTER REQUEST to RESOLVER
+ */
+export interface FilterRequest {
+	filterName: string;
+	filterOptions: string[];
+	filterType: string;
+}

package/src/features/table/types/handlers.ts

@@ -0,0 +1,71 @@
+import type { FilterOption } from "@evenicanpm/portal-types-schemas";
+
+/**
+ *
+ * @group View Handlers
+ */
+export type DataMaskMap = Record<string, MaskingFunction>;
+export type MaskingFunction = (
+	value: string | number,
+	dataMask: string,
+) => string;
+
+/**
+ * Uses column names as keys and maps out
+ * value with specific JSX for specific column names.
+ *
+ *
+ * e.g. Status -> MUIChip
+ *
+ * @group View Handlers
+ */
+export interface CellRenderMap {
+	[ColumnName: string]: (
+		value: string | number | string[],
+	) => React.ReactElement;
+}
+
+export interface FilterProps {
+	filterName: string;
+	filterOptions: FilterOption[];
+	value: Record<string, string>;
+	setValue: React.Dispatch<React.SetStateAction<Record<string, string>>>;
+	resetPagination: () => void;
+}
+
+/**
+ *
+ * Provides render methods for particular filter
+ * types. Filter types currently come from DataTypes.
+ *
+ * Note: Naive solution is to trust that project injects filter
+ * render methods for all columns with filters.We can then have a fallback for
+ * general data types.
+ *
+ * @group View Handlers
+ */
+export interface FilterRenderMap {
+	[ColumnName: string]: (props: FilterProps) => React.ReactElement;
+}
+
+/**
+ *
+ * @group View Handlers
+ */
+export interface EmptyStateProps {
+	label: string;
+}
+
+export type NoResultsComponent = (props: EmptyStateProps) => React.ReactElement;
+
+export interface DetailsRenderMap {
+	[columnName: string]: (props: {
+		[columnName: string]:
+			| string
+			| number
+			| object
+			| string[]
+			| number[]
+			| object[];
+	}) => React.ReactNode;
+}

package/src/features/table/types/index.ts

@@ -0,0 +1,70 @@
+/**
+ * # Table System: Module Registry
+ *
+ * This registry defines the structural blueprints for the Table system modules.
+ * Architecture driven by an array of Resource types which are equipped with
+ * configuration and render handlers responsible for rendering a table.
+ *
+ * ---
+ *
+ * ### 1. Queries (queries.ts)
+ * API Contracts. The raw shapes of server responses. These act as the transport
+ * layer for data before it is mapped into the system's primary models.
+ *
+ * ### 2. Schemas (schemas.ts)
+ * System Models. The primary blueprints—such as Column, Filter, and Resource—often
+ * derived from API definitions. These are the vocabulary used to drive the module.
+ *
+ * ### 3. State (state.ts)
+ * View Configuration. The dynamic parameters tracking how resources are
+ * filtered, sorted, and paginated in the current view.
+ *
+ * ### 4. Handlers (handlers.ts)
+ * Logic Registries. Objects indexed by column or resource type that map
+ * logic (like filtering and data masking) to specific parts of the system.
+ *
+ * ---
+ *
+ * @remarks
+ * ## File descriptions
+ * ```
+ * ├── components                        // UI
+ * │   └── dashboard                     // displays multiple tables with tabs
+ * │       ├── index.tsx
+ * │       ├── table                     // individual table component
+ * │       │   ├── details
+ * │       │   │   ├── details.tsx       // the details page
+ * │       │   │   ├── index.ts
+ * │       │   │   ├── label.tsx         // labels used on details page
+ * │       │   │   ├── rows              // individual rows for different details
+ * │       │   │   │   ├── downloads.tsx // download button for "documents" field
+ * │       │   │   │   ├── index.ts
+ * │       │   │   │   ├── primitive.tsx // simple text or number details field
+ * │       │   │   │   └── table.tsx     // for complex object data (displays in table)
+ * │       │   │   └── styles.ts
+ * │       │   ├── status-pill.tsx       // status pill used across table and details
+ * │       │   ├── table-input.tsx       // table search bar
+ * │       │   └── table.tsx             // actual table component
+ * │       └── table-dashboard.tsx       // actual dashboard component
+ * ├── index.ts
+ * ├── logic                             // handles data transformations
+ * │   ├── index.ts
+ * │   ├── resolvers.ts                  // multi methods that just handle resolving the maps
+ * │   ├── transformers.ts               // pure functions just for simple data transformations
+ * │   └── types.ts                      // types specifically for the transformations
+ * ├── queries                           // handles data fetching with react-query
+ * │   └── useTableQueries.tsx
+ * └── types                             // global types for feature
+ * ├── handlers.ts                   // types for handler maps (masks, renders, filters)
+ * ├── index.ts
+ * ├── queries.ts                    // types for data coming over the wire
+ * ├── schemas.ts                    // core system types (Resource)
+ * └── state.ts                      // types for transient state data (filter state)
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export * as Handlers from "./handlers";
+export * as Queries from "./queries";
+export * as Schemas from "./schemas";

package/src/features/table/types/queries.ts

@@ -0,0 +1,34 @@
+import type { ViewConfig } from "@evenicanpm/portal-types-schemas";
+
+/**
+ *
+ * These are data types returned from API Backend
+ *
+ */
+
+/**
+ *
+ * A single row in the data table response object.
+ *
+ */
+export type Row = Record<
+	string,
+	string | number | string[] | Record<string, string>[] | unknown
+>;
+
+/**
+ *
+ * The response type defined in TDD for row data.
+ *
+ */
+export interface TableRows {
+	items: number;
+	data: Row[];
+}
+
+/**
+ *
+ * Response type of data from table config
+ *
+ */
+export type TableConfig = ViewConfig;

package/src/features/table/types/schemas.ts

@@ -0,0 +1,50 @@
+import type { TableViewParams } from "@evenicanpm/portal-types-schemas";
+import type {
+	CellRenderMap,
+	DataMaskMap,
+	DetailsRenderMap,
+	FilterRenderMap,
+	NoResultsComponent,
+} from "./handlers";
+import type { TableRows } from "./queries";
+
+/**
+ * These are primary domain models and the source of truth for table system.
+ */
+
+/**
+ * Status maps
+ */
+export type StatusTextMap = Record<number | string, string>;
+
+export type StatusColor = "success" | "primary" | "warning" | "error";
+
+export type StatusColorMap = Record<number | string, StatusColor>;
+
+/**
+ * Resource Definition
+ */
+export interface Resource {
+	name: string;
+	label: string;
+	idField: string;
+
+	// Data Handlers
+	rowsQueryFn: (displaySettings: TableViewParams) => {
+		queryKey: readonly unknown[];
+		queryFn: () => Promise<TableRows>;
+	};
+
+	// UI Renderers & Mappings
+	cellRenderMap?: CellRenderMap;
+	dataMaskMap?: DataMaskMap;
+	filterRenderMap?: FilterRenderMap;
+	noResultsComponent?: NoResultsComponent;
+
+	// Optional Details view
+	detailsRenderMap?: DetailsRenderMap;
+
+	// State Visuals
+	statusTextMap: StatusTextMap;
+	statusColorMap: StatusColorMap;
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+/**
+ * Main entry point for the **e4Portal** library.
+ * All public functions are exported from here.
+ *
+ * The primary export of this package is the `Portal` React compound-component.
+ * The `Portal` component is the top-level that contains the auth, rbac and any other
+ * functionality that is not related to specific features. Specific features (e.g. `Table`)
+ * are modularized and exported as compond components attached to the main `Portal` component.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ *
+ * import { Portal } from "@evenicanpm/portal";
+ *
+ * return (
+ * 	<Portal>
+ * 		<Portal.Table resources={resources}/>
+ * 	</Portal>
+ * );
+ *```
+ * To explore package hierarchy, navigate to the `Portal` link in the components group below.
+ * `TableProps` will be the main interface used to setup the `Table` feature for Copperstate implementation.
+ *
+ * ## Table Feature Usage
+ * ```tsx
+ * const PortalView = () => {
+ *	const { data: session, status } = useSession(); // authentication + token
+ *	const { data: userData, isPending } = getUser.useData(); // D365 User Info
+ *	const { mutateAsync } = useSessionLogout();
+ *
+ *
+ *	const invoicesResource = {
+ *		name: "invoices",
+ *		label: "Invoices",
+ *		detailsFields: ["Code", "AccountName", "Total", "Status"],
+ *		rowsQueryFn: getInvoices,
+ *		configQueryFn: getInvoicesTable,
+ *		idField: "Code",
+ *		dataMaskHandlers,
+ *		columnRenderHandlers: fieldRenderMap,
+ *		filterRenderHandlers: filterRenderHandlers,
+ *	};
+ *
+ *	const resources = [
+ *		invoicesResource,
+ *		// DEFINE MORE RESOURCES HERE
+ *	];
+ *
+ *	return (
+ *		<Container>
+ *			<Portal session={authObject} logout={handleLogout}>
+ *				<Portal.Table resources={resources} />
+ *			</Portal>
+ *		</Container>
+ *  )
+ *};
+ * ```
+ * @module e4 Portal
+ */
+
+export type { Session } from "./auth/auth-context";
+export { Portal, type PortalProps } from "./portal";
+
+export { Table } from "./features/table";

package/src/portal.tsx

@@ -0,0 +1,68 @@
+import { FlexBox } from "@evenicanpm/ui";
+import type { PropsWithChildren } from "react";
+import {
+	type AuthProviderProps,
+	PortalAuthProvider,
+} from "./auth/auth-context";
+import { TableDashboard } from "./features/table/components/dashboard/table-dashboard";
+
+/**
+ * Main Entry point properties into portal package
+ *
+ *
+ */
+interface PortalProps extends AuthProviderProps {
+	// Add Portal Specific Properties Here
+	// ie. roles
+}
+
+/**
+ * The main **e4Portal** entry point.
+ * * This is a React Functional Component that provides the core context
+ * and layout for the application. It is required to wrap all components
+ * that use the library's hooks or sub-components.
+ *
+ *
+ * @param props - The properties passed to the Portal component.
+ * @returns A React Element rendering the main application structure.
+ */
+const Portal = ({
+	session,
+	logout,
+	children,
+}: PropsWithChildren<PortalProps>) => {
+	// Not Logged In
+	if (!session?.email) {
+		return (
+			<FlexBox mt={5} width="100%" justifyContent="center">
+				Please login to view the portal.
+			</FlexBox>
+		);
+	}
+
+	// Logged In yes
+	return (
+		<PortalAuthProvider session={session} logout={logout}>
+			{children}
+		</PortalAuthProvider>
+	);
+};
+
+/**
+ *
+ * # Feature: Table
+ * This is the table feature component.
+ * @params props
+ *
+ */
+Portal.Table = TableDashboard;
+
+/**
+ *
+ * # Feature: Settings
+ * This is the table feature component.
+ * @params props
+ *
+ */
+
+export { Portal, type PortalProps };