@cundi/refine-xaf 1.0.0

package/README.md

@@ -0,0 +1,267 @@
+# @cundi/refine-xaf
+
+This is an SDK integrating XAF backend with Refine frontend, including core logic for Authentication (Auth Provider), Data Access (Data Provider), and a complete UI component library.
+
+## Features
+
+- **Auth Provider**: Handles login, logout, Token management, and permission checks.
+- **Data Provider**: Data access layer designed specifically for XAF OData.
+- **UI Components**:
+    - `Header`: Application header including user menu and theme toggle (Dark/Light Mode).
+    - `LoginPage`: Standard login page.
+    - `SmartList`, `RelatedList`: Highly encapsulated generic list and detail components.
+    - `TiptapEditor`: Rich text editor with support for Images, Tables, Tasks, Math (LaTeX), YouTube, Emoji, Highlight, and Text Color.
+    - `ApplicationUser`: Complete user management (List, Create, Edit, Role Assignment).
+    - `PermissionPolicyRole`: Complete role and permission management.
+
+## How to use in a new project
+
+### 1. Initialize Project
+
+It is recommended to use the official tool to create a standard Refine + Vite + Ant Design project:
+
+```bash
+npm create refine-app@latest my-project
+# Recommended options:
+# Backend: Custom JSON REST (will be replaced later)
+# UI Framework: Ant Design
+# Authentication: None (will use SDK later)
+```
+
+### 2. Install SDK
+
+Install this SDK in your project directory:
+
+```bash
+# If in the same level as packages folder (monorepo structure)
+npm install ../packages/refine-xaf
+
+# Or use the published package name
+# npm install @cundi/refine-xaf
+```
+
+### 3. Setup Environment Variables (.env)
+
+Create a `.env` file in the project root directory and specify the backend API location.
+
+> **Note**: SDK's `httpClient` (used for Auth) defaults to reading `VITE_API_URL`. OData endpoints usually need the `/odata` suffix.
+
+```env
+VITE_API_URL=https://localhost:7087/api
+```
+
+### 4. Setup App.tsx
+
+Modify `src/App.tsx` to import components and logic from the SDK:
+
+```tsx
+import React from "react";
+import { BrowserRouter, Routes, Route, Outlet } from "react-router-dom";
+import { App as AntdApp, ConfigProvider, theme } from "antd";
+import { Refine, Authenticated } from "@refinedev/core";
+import { ThemedLayout, ErrorComponent, RefineThemes, useNotificationProvider } from "@refinedev/antd";
+import routerProvider, { NavigateToResource, CatchAllNavigate, UnsavedChangesNotifier, DocumentTitleHandler } from "@refinedev/react-router";
+import "@refinedev/antd/dist/reset.css";
+
+// 1. Import SDK
+import {
+    authProvider,
+    dataProvider,
+    Header,
+    LoginPage,
+    ApplicationUserList,
+    ApplicationUserCreate,
+    ApplicationUserEdit,
+    RoleList,
+    RoleCreate,
+    RoleEdit,
+    ColorModeContextProvider,
+    useColorMode
+} from "@cundi/refine-xaf";
+
+// 2. Setup API URL (Raw URL for Auth, /odata for Data)
+const API_URL = import.meta.env.VITE_API_URL;
+
+const InnerApp: React.FC = () => {
+    const { mode } = useColorMode();
+
+    return (
+        <BrowserRouter>
+            <ConfigProvider
+                theme={{
+                    ...RefineThemes.Blue,
+                    algorithm: mode === "dark" ? theme.darkAlgorithm : theme.defaultAlgorithm,
+                }}
+            >
+                <AntdApp>
+                    <Refine
+                        authProvider={authProvider}
+                        // 3. Setup Data Provider (Note the /odata suffix)
+                        dataProvider={dataProvider(API_URL + "/odata")}
+                        routerProvider={routerProvider}
+                        notificationProvider={useNotificationProvider}
+                        resources={[
+                            {
+                                name: "dashboard",
+                                list: "/",
+                                meta: { label: "Dashboard" }
+                            },
+                            {
+                                name: "ApplicationUser",
+                                list: "/ApplicationUsers",
+                                create: "/ApplicationUsers/create",
+                                edit: "/ApplicationUsers/edit/:id",
+                                meta: { label: "Users" }
+                            },
+                            {
+                                name: "PermissionPolicyRole",
+                                list: "/PermissionPolicyRoles",
+                                create: "/PermissionPolicyRoles/create",
+                                edit: "/PermissionPolicyRoles/edit/:id",
+                                meta: { label: "Roles" }
+                            }
+                        ]}
+                    >
+                        <Routes>
+                            <Route
+                                element={
+                                    <Authenticated key="authenticated-routes" fallback={<CatchAllNavigate to="/login" />}>
+                                        <ThemedLayout Header={Header}>
+                                            <Outlet />
+                                        </ThemedLayout>
+                                    </Authenticated>
+                                }
+                            >
+                                <Route index element={<div>Welcome to Dashboard</div>} />
+                                
+                                {/* 4. Setup pages provided by SDK */}
+                                <Route path="/ApplicationUsers">
+                                    <Route index element={<ApplicationUserList />} />
+                                    <Route path="create" element={<ApplicationUserCreate />} />
+                                    <Route path="edit/:id" element={<ApplicationUserEdit />} />
+                                </Route>
+
+                                <Route path="/PermissionPolicyRoles">
+                                    <Route index element={<RoleList />} />
+                                    <Route path="create" element={<RoleCreate />} />
+                                    <Route path="edit/:id" element={<RoleEdit />} />
+                                </Route>
+                            </Route>
+
+                            <Route
+                                element={
+                                    <Authenticated key="auth-pages" fallback={<Outlet />}>
+                                        <NavigateToResource resource="dashboard" />
+                                    </Authenticated>
+                                }
+                            >
+                                <Route path="/login" element={<LoginPage />} />
+                            </Route>
+                        </Routes>
+                        <UnsavedChangesNotifier />
+                        <DocumentTitleHandler />
+                    </Refine>
+                </AntdApp>
+            </ConfigProvider>
+        </BrowserRouter>
+    );
+};
+
+const App: React.FC = () => {
+    return (
+        <ColorModeContextProvider>
+            <InnerApp />
+        </ColorModeContextProvider>
+    );
+};
+
+export default App;
+```
+
+## Building Custom CRUD Pages
+
+To create CRUD pages for your own XAF business objects (e.g., `DemoObject`), follow these patterns (reference `cundiweb/src/pages/demo-objects` for complete examples).
+
+### List Page
+
+Use the `SmartList` component to quickly build a feature-rich list view with search capabilities.
+
+```tsx
+import { SmartList } from "@cundi/refine-xaf";
+import { Table, Checkbox, Space } from "antd";
+import { EditButton, ShowButton, DeleteButton, DateField } from "@refinedev/antd";
+
+export const DemoObjectList = () => {
+    return (
+        // searchFields prop enables the search bar for specified columns
+        <SmartList searchFields={["Name", "StringValue"]}>
+            <Table.Column dataIndex="Name" title="Name" sorter defaultVisible />
+            <Table.Column dataIndex="StringValue" title="String Value" sorter />
+            <Table.Column 
+                dataIndex="BoolValue" 
+                title="Boolean" 
+                render={(value) => <Checkbox checked={value} disabled />} 
+            />
+            {/* Standard Ant Design Table.Column configuration */}
+            <Table.Column
+                title="Actions"
+                dataIndex="actions"
+                render={(_, record) => (
+                    <Space>
+                        <EditButton hideText size="small" recordItemId={record.Oid} />
+                        <ShowButton hideText size="small" recordItemId={record.Oid} />
+                        <DeleteButton hideText size="small" recordItemId={record.Oid} />
+                    </Space>
+                )}
+            />
+        </SmartList>
+    );
+};
+```
+
+### Create/Edit Page
+
+Use standard Refine hooks (`useForm`) combined with Ant Design Form components. For file uploads (like Images), use the `Base64Upload` component provided by the SDK.
+
+```tsx
+import { Create, useForm } from "@refinedev/antd"; // or Edit
+import { Base64Upload } from "@cundi/refine-xaf";
+import { Form, Input, Switch } from "antd";
+
+export const DemoObjectCreate = () => {
+    const { formProps, saveButtonProps } = useForm();
+
+    return (
+        <Create saveButtonProps={saveButtonProps}>
+            <Form {...formProps} layout="vertical">
+                <Form.Item
+                    label="Name"
+                    name={["Name"]}
+                    rules={[{ required: true }]}
+                >
+                    <Input />
+                </Form.Item>
+                
+                {/* Image upload example */}
+                <Form.Item label="Image" name={["ImageValue"]}>
+                    <Base64Upload />
+                </Form.Item>
+
+                <Form.Item 
+                    label="Active" 
+                    name={["Active"]} 
+                    valuePropName="checked"
+                >
+                    <Switch />
+                </Form.Item>
+            </Form>
+        </Create>
+    );
+};
+```
+
+## Development and Publishing
+
+1. **Install Dependencies**: `npm install`
+2. **Build SDK**: `npm run build`
+3. **Development Mode**: `npm run dev`

package/dist/index.d.mts

@@ -0,0 +1,140 @@
+import { AuthProvider, DataProvider, BaseRecord, IResourceComponentsProps } from '@refinedev/core';
+import React, { PropsWithChildren } from 'react';
+import * as _tanstack_react_query from '@tanstack/react-query';
+
+declare const authProvider: AuthProvider;
+
+declare const dataProvider: (apiUrl: string) => DataProvider;
+
+interface IApplicationUser {
+    Oid: string;
+    UserName: string;
+    DisplayName: string;
+    Email: string;
+    Photo?: string;
+    IsActive: boolean;
+    AccessFailedCount: number;
+    LockoutEnd?: string;
+    Roles?: IPermissionPolicyRole[];
+}
+declare enum SecurityPermissionPolicy {
+    DenyAllByDefault = "DenyAllByDefault",
+    ReadOnlyAllByDefault = "ReadOnlyAllByDefault",
+    AllowAllByDefault = "AllowAllByDefault"
+}
+declare enum SecurityPermissionState {
+    Allow = "Allow",
+    Deny = "Deny"
+}
+interface IPermissionPolicyTypePermissionObject {
+    Oid?: string;
+    TargetType: string;
+    ReadState?: SecurityPermissionState;
+    WriteState?: SecurityPermissionState;
+    CreateState?: SecurityPermissionState;
+    DeleteState?: SecurityPermissionState;
+    NavigateState?: SecurityPermissionState;
+}
+interface IPermissionPolicyRole {
+    Oid: string;
+    Name: string;
+    IsAdministrative: boolean;
+    PermissionPolicy: SecurityPermissionPolicy;
+    TypePermissions?: IPermissionPolicyTypePermissionObject[];
+}
+
+declare const TOKEN_KEY = "refine-auth";
+declare class HttpError extends Error {
+    statusCode: number;
+    message: string;
+    body: any;
+    constructor(statusCode: number, message: string, body: any);
+}
+interface RequestOptions extends RequestInit {
+    skipAuth?: boolean;
+}
+declare const getBaseUrl: () => any;
+declare const httpClient: (endpoint: string, options?: RequestOptions) => Promise<Response | null>;
+declare const parseJwt: (token: string) => any;
+
+declare const authService: {
+    login: ({ username, password }: any) => Promise<string>;
+    getUserByUsername: (username: string) => Promise<IApplicationUser | null>;
+    getUserById: (userId: string) => Promise<IApplicationUser | null>;
+    resetPassword: (userId: string, newPassword: string) => Promise<boolean>;
+};
+
+declare const Header: React.FC;
+
+interface SmartListProps {
+    children?: React.ReactNode;
+    resource?: string;
+    searchFields?: string[];
+}
+declare const SmartList: <T extends BaseRecord = BaseRecord>({ children, resource, searchFields, }: SmartListProps) => React.JSX.Element;
+
+interface RelatedListProps<TItem extends BaseRecord> {
+    resource: string;
+    /** Field name in the detail object that links to master (e.g. "Master") */
+    masterField: string;
+    /** ID of the master record */
+    masterId?: string;
+    /** Data source for the table */
+    dataSource?: TItem[];
+    /** Callback when data changes (save/delete) to refresh parent */
+    onMutationSuccess?: () => void;
+    /** Function component to render form fields. Receives 'mode' prop. */
+    FormFields: any;
+    /** Title for the modal, defaults to "Manage Detail" */
+    modalTitle?: string;
+    /** Extra props for the Table */
+    children?: React.ReactNode;
+}
+declare const RelatedList: <TItem extends BaseRecord>({ resource, masterField, masterId, dataSource, onMutationSuccess, FormFields, modalTitle, children, }: RelatedListProps<TItem>) => React.JSX.Element;
+
+interface Base64UploadProps {
+    value?: string;
+    onChange?: (value: string) => void;
+}
+declare const Base64Upload: React.FC<Base64UploadProps>;
+
+interface TiptapEditorProps {
+    value?: string;
+    onChange?: (value: string) => void;
+    disabled?: boolean;
+}
+declare const TiptapEditor: React.FC<TiptapEditorProps>;
+
+declare const LoginPage: React.FC;
+
+declare const ApplicationUserList: React.FC<IResourceComponentsProps>;
+
+declare const ApplicationUserCreate: React.FC<IResourceComponentsProps>;
+
+declare const ApplicationUserEdit: React.FC<IResourceComponentsProps>;
+
+declare const RoleList: React.FC<IResourceComponentsProps>;
+
+declare const RoleCreate: React.FC<IResourceComponentsProps>;
+
+declare const RoleEdit: React.FC<IResourceComponentsProps>;
+
+type ColorModeContextType = {
+    mode: "light" | "dark";
+    setMode: (mode: "light" | "dark") => void;
+};
+declare const ColorModeContext: React.Context<ColorModeContextType>;
+declare const ColorModeContextProvider: React.FC<PropsWithChildren>;
+declare const useColorMode: () => ColorModeContextType;
+
+interface IModelType {
+    Name: string;
+    Caption: string;
+    IsCreatable: boolean;
+    IsDeprecated: boolean;
+    Value?: string;
+    Label?: string;
+}
+declare const useModelTypes: () => _tanstack_react_query.UseQueryResult<IModelType[], Error>;
+
+export { ApplicationUserCreate, ApplicationUserEdit, ApplicationUserList, Base64Upload, ColorModeContext, ColorModeContextProvider, Header, HttpError, type IApplicationUser, type IModelType, type IPermissionPolicyRole, type IPermissionPolicyTypePermissionObject, LoginPage, RelatedList, type RequestOptions, RoleCreate, RoleEdit, RoleList, SecurityPermissionPolicy, SecurityPermissionState, SmartList, TOKEN_KEY, TiptapEditor, type TiptapEditorProps, authProvider, authService, dataProvider, getBaseUrl, httpClient, parseJwt, useColorMode, useModelTypes };

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+import { AuthProvider, DataProvider, BaseRecord, IResourceComponentsProps } from '@refinedev/core';
+import React, { PropsWithChildren } from 'react';
+import * as _tanstack_react_query from '@tanstack/react-query';
+
+declare const authProvider: AuthProvider;
+
+declare const dataProvider: (apiUrl: string) => DataProvider;
+
+interface IApplicationUser {
+    Oid: string;
+    UserName: string;
+    DisplayName: string;
+    Email: string;
+    Photo?: string;
+    IsActive: boolean;
+    AccessFailedCount: number;
+    LockoutEnd?: string;
+    Roles?: IPermissionPolicyRole[];
+}
+declare enum SecurityPermissionPolicy {
+    DenyAllByDefault = "DenyAllByDefault",
+    ReadOnlyAllByDefault = "ReadOnlyAllByDefault",
+    AllowAllByDefault = "AllowAllByDefault"
+}
+declare enum SecurityPermissionState {
+    Allow = "Allow",
+    Deny = "Deny"
+}
+interface IPermissionPolicyTypePermissionObject {
+    Oid?: string;
+    TargetType: string;
+    ReadState?: SecurityPermissionState;
+    WriteState?: SecurityPermissionState;
+    CreateState?: SecurityPermissionState;
+    DeleteState?: SecurityPermissionState;
+    NavigateState?: SecurityPermissionState;
+}
+interface IPermissionPolicyRole {
+    Oid: string;
+    Name: string;
+    IsAdministrative: boolean;
+    PermissionPolicy: SecurityPermissionPolicy;
+    TypePermissions?: IPermissionPolicyTypePermissionObject[];
+}
+
+declare const TOKEN_KEY = "refine-auth";
+declare class HttpError extends Error {
+    statusCode: number;
+    message: string;
+    body: any;
+    constructor(statusCode: number, message: string, body: any);
+}
+interface RequestOptions extends RequestInit {
+    skipAuth?: boolean;
+}
+declare const getBaseUrl: () => any;
+declare const httpClient: (endpoint: string, options?: RequestOptions) => Promise<Response | null>;
+declare const parseJwt: (token: string) => any;
+
+declare const authService: {
+    login: ({ username, password }: any) => Promise<string>;
+    getUserByUsername: (username: string) => Promise<IApplicationUser | null>;
+    getUserById: (userId: string) => Promise<IApplicationUser | null>;
+    resetPassword: (userId: string, newPassword: string) => Promise<boolean>;
+};
+
+declare const Header: React.FC;
+
+interface SmartListProps {
+    children?: React.ReactNode;
+    resource?: string;
+    searchFields?: string[];
+}
+declare const SmartList: <T extends BaseRecord = BaseRecord>({ children, resource, searchFields, }: SmartListProps) => React.JSX.Element;
+
+interface RelatedListProps<TItem extends BaseRecord> {
+    resource: string;
+    /** Field name in the detail object that links to master (e.g. "Master") */
+    masterField: string;
+    /** ID of the master record */
+    masterId?: string;
+    /** Data source for the table */
+    dataSource?: TItem[];
+    /** Callback when data changes (save/delete) to refresh parent */
+    onMutationSuccess?: () => void;
+    /** Function component to render form fields. Receives 'mode' prop. */
+    FormFields: any;
+    /** Title for the modal, defaults to "Manage Detail" */
+    modalTitle?: string;
+    /** Extra props for the Table */
+    children?: React.ReactNode;
+}
+declare const RelatedList: <TItem extends BaseRecord>({ resource, masterField, masterId, dataSource, onMutationSuccess, FormFields, modalTitle, children, }: RelatedListProps<TItem>) => React.JSX.Element;
+
+interface Base64UploadProps {
+    value?: string;
+    onChange?: (value: string) => void;
+}
+declare const Base64Upload: React.FC<Base64UploadProps>;
+
+interface TiptapEditorProps {
+    value?: string;
+    onChange?: (value: string) => void;
+    disabled?: boolean;
+}
+declare const TiptapEditor: React.FC<TiptapEditorProps>;
+
+declare const LoginPage: React.FC;
+
+declare const ApplicationUserList: React.FC<IResourceComponentsProps>;
+
+declare const ApplicationUserCreate: React.FC<IResourceComponentsProps>;
+
+declare const ApplicationUserEdit: React.FC<IResourceComponentsProps>;
+
+declare const RoleList: React.FC<IResourceComponentsProps>;
+
+declare const RoleCreate: React.FC<IResourceComponentsProps>;
+
+declare const RoleEdit: React.FC<IResourceComponentsProps>;
+
+type ColorModeContextType = {
+    mode: "light" | "dark";
+    setMode: (mode: "light" | "dark") => void;
+};
+declare const ColorModeContext: React.Context<ColorModeContextType>;
+declare const ColorModeContextProvider: React.FC<PropsWithChildren>;
+declare const useColorMode: () => ColorModeContextType;
+
+interface IModelType {
+    Name: string;
+    Caption: string;
+    IsCreatable: boolean;
+    IsDeprecated: boolean;
+    Value?: string;
+    Label?: string;
+}
+declare const useModelTypes: () => _tanstack_react_query.UseQueryResult<IModelType[], Error>;
+
+export { ApplicationUserCreate, ApplicationUserEdit, ApplicationUserList, Base64Upload, ColorModeContext, ColorModeContextProvider, Header, HttpError, type IApplicationUser, type IModelType, type IPermissionPolicyRole, type IPermissionPolicyTypePermissionObject, LoginPage, RelatedList, type RequestOptions, RoleCreate, RoleEdit, RoleList, SecurityPermissionPolicy, SecurityPermissionState, SmartList, TOKEN_KEY, TiptapEditor, type TiptapEditorProps, authProvider, authService, dataProvider, getBaseUrl, httpClient, parseJwt, useColorMode, useModelTypes };