mui-toolpad-extended-tuni 1.0.0 → 1.0.3

package/README.md

@@ -1,20 +1,407 @@
 <!-- @format -->
 
-# MUI Toolpad extended Library (TUNI)
+# MUI Toolpad Extended Library (TUNI)
 
-This project is an extended version of MUI Toolpad, originally developed by MUI. It includes modifications and additional features to enhance functionality.
+A React library extending MUI Toolpad functionality with additional features for educational applications. This library provides components and tools for building interactive educational interfaces.
 
-## Installation
+## Prerequisites
+
+This library requires the following peer dependencies:
 
-Install with:
+- React ≥18.0.0
+- React DOM ≥18.0.0
+- @mui/material ≥6.0.0
+- @mui/icons-material ≥6.0.0
+- @emotion/react ≥11.0.0
+- @emotion/styled ≥11.0.0
+
+## Installation
 
 ```bash
-npm install @jalez/mui-toolpad-extended-tuni'
+npm install @jalez/mui-toolpad-extended-tuni
 ```
 
-Use in your React project:
+## Basic Usage
 
-```typescript
+1. Wrap your application with `EduMLProvider`:
+
+```tsx
+import { BrowserRouter } from 'react-router-dom';
 import { EduMLProvider } from '@jalez/mui-toolpad-extended-tuni';
-// ...existing code...
+
+function App() {
+  return (
+    <BrowserRouter>
+      <EduMLProvider>{/* Your application content */}</EduMLProvider>
+    </BrowserRouter>
+  );
+}
 ```
+
+2. Use the included stores and components:
+
+```tsx
+import {
+  useUserStore,
+  useCourseStore,
+  useNavigationStore,
+} from '@jalez/mui-toolpad-extended-tuni';
+
+function MyComponent() {
+  const { user } = useUserStore();
+  const { currentCourse } = useCourseStore();
+
+  return (
+    <div>
+      <h1>Welcome, {user?.name}!</h1>
+      <p>Current course: {currentCourse?.title}</p>
+    </div>
+  );
+}
+```
+
+## Core Components
+
+### EduMLProvider
+
+The main provider component that sets up the application context:
+
+```tsx
+import { BrowserRouter } from 'react-router-dom';
+import { EduMLProvider } from '@jalez/mui-toolpad-extended-tuni';
+
+function App() {
+  return (
+    <BrowserRouter>
+      <EduMLProvider>
+        <YourComponents />
+      </EduMLProvider>
+    </BrowserRouter>
+  );
+}
+```
+
+### LoadingScreen
+
+A customizable loading indicator with animations:
+
+```tsx
+import { LoadingScreen } from '@jalez/mui-toolpad-extended-tuni';
+
+function MyComponent() {
+  return isLoading ? <LoadingScreen /> : <YourContent />;
+}
+```
+
+### Notifications
+
+Built-in notification system using notistack:
+
+```tsx
+import { useNotificationStore } from '@jalez/mui-toolpad-extended-tuni';
+
+function MyComponent() {
+  const { addNotificationData } = useNotificationStore();
+
+  const showNotification = () => {
+    addNotificationData({
+      type: 'success',
+      message: 'Operation completed successfully',
+      singular: true, // Optional: show only once
+    });
+  };
+}
+```
+
+### EduMLDialog
+
+A responsive dialog component:
+
+```tsx
+import { EduMLDialog } from '@jalez/mui-toolpad-extended-tuni';
+
+function MyComponent() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <EduMLDialog open={open} onClose={() => setOpen(false)}>
+      <DialogContent>Your content here</DialogContent>
+    </EduMLDialog>
+  );
+}
+```
+
+### Course Management Components
+
+#### CourseSelector
+
+A component for listing and selecting courses:
+
+```tsx
+import { CourseSelector } from '@jalez/mui-toolpad-extended-tuni';
+
+function MyComponent() {
+  return <CourseSelector />;
+}
+```
+
+#### CourseTools
+
+Manages course-specific tools and LTI configuration:
+
+```tsx
+import { CourseTools } from '@jalez/mui-toolpad-extended-tuni';
+
+function MyComponent() {
+  return <CourseTools />;
+}
+```
+
+#### LTI Login Configuration
+
+For teachers to set up course authentication:
+
+```tsx
+import { LtiLoginUrlForm } from '@jalez/mui-toolpad-extended-tuni';
+
+function MyComponent() {
+  return <LtiLoginUrlForm />;
+}
+```
+
+### Error Handling Components
+
+#### ErrorBoundary
+
+Catches and handles React component errors:
+
+```tsx
+import { ErrorBoundary } from '@jalez/mui-toolpad-extended-tuni';
+
+function App() {
+  return (
+    <ErrorBoundary>
+      <YourComponents />
+    </ErrorBoundary>
+  );
+}
+```
+
+#### NullStateWarning
+
+Detects and displays warnings for null states:
+
+```tsx
+import { NullStateWarning } from '@jalez/mui-toolpad-extended-tuni';
+
+function MyComponent() {
+  const states = [{ user: currentUser }, { course: currentCourse }];
+
+  return (
+    <NullStateWarning states={states}>
+      <YourContent />
+    </NullStateWarning>
+  );
+}
+```
+
+## Development Tools
+
+When running in development mode (localhost), the library provides additional tools:
+
+- User Switcher: Easily switch between different user roles (student/teacher/guest)
+- Development Toolbar: Additional debugging and testing features
+
+## Features
+
+- User authentication and management
+- Course handling and navigation
+- Notification system
+- Custom dialog management
+- Role-based navigation filtering
+- LTI integration support
+- Customizable theme
+
+## Available Stores
+
+### useUserStore
+
+```tsx
+const {
+  user, // Current user data
+  getUser, // Fetch user data
+  changeRole, // Switch user role
+  logout, // Logout current user
+} = useUserStore();
+```
+
+### useCourseStore
+
+```tsx
+const {
+  currentCourse, // Current active course
+  courses, // List of available courses
+  getCourses, // Fetch all courses
+  getCourseByUrl, // Get course by URL
+} = useCourseStore();
+```
+
+### useNavigationStore
+
+```tsx
+const {
+  navigation, // Current navigation structure
+  updateSection, // Update navigation section
+  setNavigation, // Set entire navigation
+} = useNavigationStore();
+```
+
+### useNotificationStore
+
+```tsx
+const {
+  addNotificationData, // Add new notification
+  removeNotificationData, // Remove notification
+} = useNotificationStore();
+```
+
+## Utility Functions
+
+### String Manipulation
+
+```tsx
+import {
+  slugify,
+  camelCaseToUnderscore,
+  underscoreToCamelCase,
+} from '@jalez/mui-toolpad-extended-tuni';
+
+// Convert strings to URL-friendly format
+const slug = slugify('My Course Title'); // 'my-course-title'
+
+// Convert between case styles
+const underscore = camelCaseToUnderscore('myVariable'); // 'my_variable'
+const camelCase = underscoreToCamelCase('my_variable'); // 'myVariable'
+```
+
+### Object Key Conversion
+
+```tsx
+import {
+  convertObjectKeysToCamelCase,
+  convertObjectKeysToUnderscore,
+} from '@jalez/mui-toolpad-extended-tuni';
+
+// Convert API responses
+const camelCaseData = convertObjectKeysToCamelCase(apiResponse);
+const underscoreData = convertObjectKeysToUnderscore(requestData);
+```
+
+## Network Configuration
+
+The library includes pre-configured Axios instance for API communications:
+
+```tsx
+import { axiosInstance } from '@jalez/mui-toolpad-extended-tuni';
+
+// Handles CSRF tokens and base URL automatically
+const response = await axiosInstance.get('/api/endpoint');
+```
+
+## Course Types and Interfaces
+
+```tsx
+interface Course {
+  id: string;
+  title: string;
+  description: string;
+  createdAt: string;
+  ltiLoginUrl: string;
+  updatedAt: string;
+}
+
+// Course creation payload
+interface CourseRaw {
+  title: string;
+  description: string;
+}
+```
+
+## Theme Customization
+
+The library includes a customizable Material-UI theme:
+
+```tsx
+import { EduMLTheme } from '@jalez/mui-toolpad-extended-tuni';
+
+// Theme includes predefined:
+// - Color schemes (light/dark)
+// - Typography scales
+// - Component style overrides
+// - Transition effects
+// - Z-index hierarchy
+```
+
+## Current Limitations
+
+1. **Authentication:**
+
+   - LTI login URL must be configured per course
+   - Only supports single active session
+   - Development mode uses mock authentication
+
+2. **Course Management:**
+
+   - Limited to predefined course structure
+   - No bulk operations support
+   - Course tools must follow specific navigation structure
+
+3. **State Management:**
+
+   - No persistence between page reloads
+   - Limited offline support
+   - State updates are synchronous
+
+4. **Network:**
+
+   - Base URL is fixed to '/'
+   - CSRF token handling is mandatory
+   - No request caching implementation
+
+5. **Browser Support:**
+   - Requires modern browser features
+   - Limited mobile responsiveness
+   - No IE11 support
+
+## Types and Interfaces
+
+### Common Types
+
+```typescript
+type fetchState = 'idle' | 'loading' | 'error' | 'success';
+
+interface NavigationStoreItem {
+  kind: 'header' | 'page';
+  title: string;
+  segment?: string;
+  children?: NavigationStoreItem[];
+}
+```
+
+## License
+
+MIT License - See LICENSE file for details.
+
+## Contributing
+
+When contributing, please note:
+
+- All components must implement error boundaries
+- State management should use Zustand stores
+- Network requests must use the provided axios instance
+- Theme modifications should extend EduMLTheme
+- Components should handle null states appropriately
+
+## Support
+
+For issues and feature requests, please use the GitHub issue tracker.

package/dist/EduMLToolpad/EduMLProvider.d.ts

@@ -0,0 +1,20 @@
+/** @format */
+import { ReactNode } from 'react';
+export interface EduMLProviderProps {
+    children?: ReactNode;
+}
+/**
+ * EduMLProvider must be wrapped in a Router component from react-router-dom
+ * Example:
+ * ```tsx
+ * import { BrowserRouter } from 'react-router-dom';
+ *
+ * <BrowserRouter>
+ *   <EduMLProvider>
+ *     {children}
+ *   </EduMLProvider>
+ * </BrowserRouter>
+ * ```
+ */
+declare const EduMLProvider: ({ children }: EduMLProviderProps) => import("react/jsx-runtime").JSX.Element;
+export default EduMLProvider;

package/dist/EduMLToolpad/components/Courses/CourseItem.d.ts

@@ -0,0 +1,9 @@
+/** @format */
+import { Course } from '../../store/useCourseStore';
+type CourseItemProps = {
+    course: Course;
+    isSelected: boolean;
+    onSelect: (course: Course) => void;
+};
+declare const CourseItem: ({ course, isSelected, onSelect }: CourseItemProps) => import("react/jsx-runtime").JSX.Element;
+export default CourseItem;

package/dist/EduMLToolpad/components/Courses/CourseList.d.ts

@@ -0,0 +1,9 @@
+/** @format */
+import { Course } from '../../store/useCourseStore';
+type CourseListProps = {
+    courses: Course[];
+    selectedCourse?: Course | null;
+    onSelectCourse: (course: Course) => void;
+};
+declare const CourseList: ({ courses, selectedCourse, onSelectCourse, }: CourseListProps) => import("react/jsx-runtime").JSX.Element;
+export default CourseList;

package/dist/EduMLToolpad/components/Courses/CourseSelector.d.ts

@@ -0,0 +1,3 @@
+/** @format */
+declare const CourseSelector: () => import("react/jsx-runtime").JSX.Element;
+export default CourseSelector;

package/dist/EduMLToolpad/components/Courses/CourseTools.d.ts

@@ -0,0 +1,3 @@
+/** @format */
+declare const CourseTools: () => import("react/jsx-runtime").JSX.Element;
+export default CourseTools;

package/dist/EduMLToolpad/components/Courses/LtiLoginUrlForm.d.ts

@@ -0,0 +1,3 @@
+/** @format */
+declare const LtiLoginUrlForm: () => import("react/jsx-runtime").JSX.Element;
+export default LtiLoginUrlForm;

package/dist/EduMLToolpad/components/Courses/NoCoursesMessage.d.ts

@@ -0,0 +1,3 @@
+/** @format */
+declare const NoCoursesMessage: () => import("react/jsx-runtime").JSX.Element;
+export default NoCoursesMessage;

package/dist/EduMLToolpad/components/DevelopmentTools.d.ts

@@ -0,0 +1,3 @@
+/** @format */
+declare const DevelopmentTools: React.FC;
+export default DevelopmentTools;

package/dist/EduMLToolpad/components/Dialogs/DialogOpener.d.ts

@@ -0,0 +1,10 @@
+/** @format */
+import { dialogType } from '../../store/useDialogStore';
+type DialogOpenerProps = {
+    title: string;
+    dialogId: dialogType;
+    callOnOpen?: (event: React.MouseEvent<HTMLButtonElement | HTMLElement>) => void;
+    showTitle?: boolean;
+};
+declare const DialogOpener: ({ title, dialogId, callOnOpen, showTitle, }: DialogOpenerProps) => import("react/jsx-runtime").JSX.Element;
+export default DialogOpener;

package/dist/EduMLToolpad/components/Dialogs/FormDialog.d.ts

@@ -0,0 +1,10 @@
+/** @format */
+interface FormDialogProps {
+    onSubmit: (event: React.FormEvent<HTMLFormElement>) => void;
+    title: string;
+    children: React.ReactNode;
+    submitText?: string;
+    disableSubmit?: boolean;
+}
+declare const FormDialog: React.FC<FormDialogProps>;
+export default FormDialog;

package/dist/EduMLToolpad/components/EduMLDialog.d.ts

@@ -0,0 +1,9 @@
+/** @format */
+import { ReactNode } from 'react';
+type EduMLDialogProps = {
+    children: ReactNode;
+    open: boolean;
+    onClose: () => void;
+};
+declare const EduMLDialog: ({ children, open, onClose, ...dialogProps }: EduMLDialogProps) => import("react/jsx-runtime").JSX.Element;
+export default EduMLDialog;

package/dist/EduMLToolpad/components/Home.d.ts

@@ -0,0 +1,3 @@
+/** @format */
+declare const Home: () => import("react/jsx-runtime").JSX.Element;
+export default Home;

package/dist/EduMLToolpad/components/IconWithBadge.d.ts

@@ -0,0 +1,10 @@
+/** @format */
+import { SxProps, Theme } from '@mui/material/styles';
+type IconWithBadgeProps = {
+    Icon: React.FC;
+    size: number;
+    title: string;
+    sx?: SxProps<Theme>;
+};
+declare const IconWithBadge: ({ Icon, size, title, sx }: IconWithBadgeProps) => import("react/jsx-runtime").JSX.Element;
+export default IconWithBadge;

package/dist/EduMLToolpad/components/LoadingScreen.d.ts

@@ -0,0 +1,2 @@
+declare const LoadingScreen: () => import("react/jsx-runtime").JSX.Element;
+export default LoadingScreen;

package/dist/EduMLToolpad/components/Logo.d.ts

@@ -0,0 +1,2 @@
+/** @format */
+export declare const Logo: () => import("react/jsx-runtime").JSX.Element;

package/dist/EduMLToolpad/components/Notifications.d.ts

@@ -0,0 +1,3 @@
+/** @format */
+declare const Notifications: () => import("react/jsx-runtime").JSX.Element;
+export default Notifications;

package/dist/EduMLToolpad/components/PageToolBar.d.ts

@@ -0,0 +1,3 @@
+/** @format */
+declare const PageToolbar: () => import("react/jsx-runtime").JSX.Element;
+export default PageToolbar;

package/dist/EduMLToolpad/components/ToolSelector.d.ts

@@ -0,0 +1,17 @@
+import { NavigationPageStoreItem } from '../store/useNavigationStore';
+export type ToolSelectorItem = {
+    path: string;
+    icon: JSX.Element;
+    label: string;
+    description: string;
+    forRoles?: string[];
+};
+type ToolSelectorProps = {
+    show: boolean;
+    title: string;
+    navigationItems?: ToolSelectorItem[];
+    navItems?: NavigationPageStoreItem[];
+    roleCheck?: boolean;
+};
+declare const ToolSelector: ({ show, title, navigationItems, navItems, roleCheck }: ToolSelectorProps) => import("react/jsx-runtime").JSX.Element;
+export default ToolSelector;

package/dist/EduMLToolpad/components/UserSwitcher.d.ts

@@ -0,0 +1,3 @@
+/** @format */
+declare const UserSwitcher: React.FC;
+export default UserSwitcher;

package/dist/EduMLToolpad/components/sidebar/Footer.d.ts

@@ -0,0 +1,3 @@
+import { SidebarFooterProps } from "@toolpad/core";
+declare function SidebarFooter({ mini }: SidebarFooterProps): import("react/jsx-runtime").JSX.Element;
+export default SidebarFooter;

package/dist/EduMLToolpad/components/toolbar/Account.d.ts

@@ -0,0 +1 @@
+export declare const ToolbarAccount: () => import("react/jsx-runtime").JSX.Element;

package/dist/EduMLToolpad/components/toolbar/Actions.d.ts

@@ -0,0 +1 @@
+export declare function CustomActions(): import("react/jsx-runtime").JSX.Element;

package/dist/EduMLToolpad/components/tools/addActions.d.ts

@@ -0,0 +1,5 @@
+import { NavigationStoreItem } from "../../store/useNavigationStore";
+/**
+ * Adds actions to navigation items based on their actionHandlers
+ */
+export declare const addActions: (navItems: NavigationStoreItem[], role: string) => NavigationStoreItem[];

package/dist/EduMLToolpad/components/tools/addIcons.d.ts

@@ -0,0 +1,2 @@
+import { NavigationStoreItem } from "../../store/useNavigationStore";
+export declare const addIcons: (navItems: NavigationStoreItem[]) => NavigationStoreItem[];

package/dist/EduMLToolpad/components/tools/iconsByType.d.ts

@@ -0,0 +1,6 @@
+/** @format */
+type iconByType = {
+    [key: string]: React.ReactNode;
+};
+export declare const iconByType: iconByType;
+export {};

package/dist/EduMLToolpad/components/tools/utils/ActionFCWrapper.d.ts

@@ -0,0 +1,5 @@
+declare const ActionFCWrapper: <T extends Record<string, unknown>>({ ActionHandler, props }: {
+    ActionHandler: import("react").FC<T>;
+    props: T;
+}) => import("react/jsx-runtime").JSX.Element;
+export default ActionFCWrapper;

package/dist/EduMLToolpad/components/tools/utils/IconFCWrapper.d.ts

@@ -0,0 +1,6 @@
+/** @format */
+import { SvgIconComponent } from '@mui/icons-material';
+declare const IconWrapper: ({ IconFC }: {
+    IconFC: SvgIconComponent;
+}) => import("react/jsx-runtime").JSX.Element | null;
+export default IconWrapper;

package/dist/EduMLToolpad/constants.d.ts

@@ -0,0 +1,2 @@
+/** @format */
+export declare const baseUrl = "/";

package/dist/EduMLToolpad/hooks/useCustomRouter.d.ts

@@ -0,0 +1,6 @@
+declare function useCustomRouter(): {
+    pathname: any;
+    searchParams: URLSearchParams;
+    navigate: any;
+};
+export default useCustomRouter;

package/dist/EduMLToolpad/interfaces.d.ts

@@ -0,0 +1 @@
+export type fetchState = "idle" | "loading" | "error" | "success";

package/dist/EduMLToolpad/layout/breadcrumbs/SizableContentHeader.d.ts

@@ -0,0 +1,7 @@
+/** @format */
+/**
+ * ContentHeader component
+ *
+ * @returns
+ */
+export declare const SizableContentHeader: () => import("react/jsx-runtime").JSX.Element;

package/dist/EduMLToolpad/network/axiosConfig.d.ts

@@ -0,0 +1,3 @@
+export declare const csrftoken: string | null;
+declare const axiosInstance: any;
+export default axiosInstance;