From 37a538a54e372349421b7e8824acfe064d5663f4 Mon Sep 17 00:00:00 2001 From: Rashmitha Chamikara Date: Thu, 5 Mar 2026 10:04:29 +0530 Subject: [PATCH 001/161] Initial commit --- portal/frontend/.ai/oxygen-ui/AGENTS.md | 81 + portal/frontend/.ai/oxygen-ui/components.md | 1431 +++++++ portal/frontend/.ai/oxygen-ui/migration.md | 281 ++ portal/frontend/.ai/oxygen-ui/patterns.md | 1197 ++++++ portal/frontend/.ai/oxygen-ui/theming.md | 334 ++ portal/frontend/.gitignore | 24 + portal/frontend/AGENTS.md | 81 + portal/frontend/README.md | 73 + portal/frontend/eslint.config.js | 23 + portal/frontend/index.html | 13 + portal/frontend/package-lock.json | 4271 +++++++++++++++++++ portal/frontend/package.json | 32 + portal/frontend/public/vite.svg | 1 + portal/frontend/src/App.css | 42 + portal/frontend/src/App.tsx | 81 + portal/frontend/src/assets/react.svg | 1 + portal/frontend/src/index.css | 68 + portal/frontend/src/main.tsx | 13 + portal/frontend/tsconfig.app.json | 28 + portal/frontend/tsconfig.json | 7 + portal/frontend/tsconfig.node.json | 26 + portal/frontend/vite.config.ts | 7 + 22 files changed, 8115 insertions(+) create mode 100644 portal/frontend/.ai/oxygen-ui/AGENTS.md create mode 100644 portal/frontend/.ai/oxygen-ui/components.md create mode 100644 portal/frontend/.ai/oxygen-ui/migration.md create mode 100644 portal/frontend/.ai/oxygen-ui/patterns.md create mode 100644 portal/frontend/.ai/oxygen-ui/theming.md create mode 100644 portal/frontend/.gitignore create mode 100644 portal/frontend/AGENTS.md create mode 100644 portal/frontend/README.md create mode 100644 portal/frontend/eslint.config.js create mode 100644 portal/frontend/index.html create mode 100644 portal/frontend/package-lock.json create mode 100644 portal/frontend/package.json create mode 100644 portal/frontend/public/vite.svg create mode 100644 portal/frontend/src/App.css create mode 100644 portal/frontend/src/App.tsx create mode 100644 portal/frontend/src/assets/react.svg create mode 100644 portal/frontend/src/index.css create mode 100644 portal/frontend/src/main.tsx create mode 100644 portal/frontend/tsconfig.app.json create mode 100644 portal/frontend/tsconfig.json create mode 100644 portal/frontend/tsconfig.node.json create mode 100644 portal/frontend/vite.config.ts diff --git a/portal/frontend/.ai/oxygen-ui/AGENTS.md b/portal/frontend/.ai/oxygen-ui/AGENTS.md new file mode 100644 index 00000000..e76ab7ff --- /dev/null +++ b/portal/frontend/.ai/oxygen-ui/AGENTS.md @@ -0,0 +1,81 @@ +# Oxygen UI - AI Development Guide + +> WSO2's React component library built on Material-UI v7 + +## Quick Start + +```tsx +import { OxygenUIThemeProvider, OxygenTheme, Button } from '@wso2/oxygen-ui'; + +function App() { + return ( + + + + ); +} +``` + +## Critical Rules + +1. **Import from `@wso2/oxygen-ui`** - Never import directly from `@mui/material` +2. **Always wrap with `OxygenUIThemeProvider`** - Required at app root +3. **Icons from `@wso2/oxygen-ui-icons-react`** - Separate package for icons +4. **MUI X uses namespaces** - `DataGrid.DataGrid`, `DatePickers.DatePicker`, `TreeView.TreeView` +5. **Use theme tokens** - Use `sx` prop with theme values, not hardcoded colors/spacing + +## Import Patterns + +```tsx +// Components - import from @wso2/oxygen-ui +import { Button, TextField, Box, Typography, ListingTable } from '@wso2/oxygen-ui'; + +// Icons - import from @wso2/oxygen-ui-icons-react +import { HomeIcon, SettingsIcon, UserIcon } from '@wso2/oxygen-ui-icons-react'; + +// MUI X - use as namespaces +import { DataGrid, DatePickers, TreeView } from '@wso2/oxygen-ui'; + + +``` + +## Theme Tokens (Always Use) + +```tsx +// CORRECT - Use theme tokens + + +// WRONG - Never hardcode + +``` + +## Available Themes + +- `OxygenTheme` - Default theme (recommended) +- `AcrylicOrangeTheme` - Orange accent variant +- `AcrylicPurpleTheme` - Purple accent variant +- `ChoreoTheme` - Choreo product theme (indigo-violet gradient) +- `ClassicTheme` - Traditional styling +- `HighContrastTheme` - Accessibility-focused +- `PaleBaseTheme` - Minimal color palette +- `PaleGrayTheme` - Soft gray tones +- `PaleIndigoTheme` - Soft indigo tones + +## Custom Oxygen Components + +- **Layout**: `AppShell`, `Layout`, `Header`, `Sidebar`, `Footer`, `PageContent` +- **Data Display**: `ListingTable`, `PageTitle`, `CodeBlock`, `StatCard` +- **Forms**: `Form.CardButton`, `Form.Section`, `Form.Stack`, `Form.Wizard` +- **Inputs**: `SearchBar`, `SearchBarWithAdvancedFilter`, `ComplexSelect` +- **Feedback**: `NotificationPanel`, `NotificationBanner` +- **Theming**: `OxygenUIThemeProvider`, `ThemeSwitcher`, `ColorSchemeToggle`, `ColorSchemeImage` +- **User**: `UserMenu` +- **Animations**: `ParticleBackground` + +## Detailed Documentation + +For comprehensive API reference and examples, see: +- [Component API Reference](./components.md) +- [UI Patterns & Examples](./patterns.md) +- [Theme Customization](./theming.md) +- [Migration Guide](./migration.md) diff --git a/portal/frontend/.ai/oxygen-ui/components.md b/portal/frontend/.ai/oxygen-ui/components.md new file mode 100644 index 00000000..fe912c6f --- /dev/null +++ b/portal/frontend/.ai/oxygen-ui/components.md @@ -0,0 +1,1431 @@ +# Oxygen UI Component Reference + +Complete API reference for custom Oxygen UI components. For MUI components, refer to [Material-UI documentation](https://mui.com/material-ui/). + +## Table of Contents + +- [OxygenUIThemeProvider](#oxygenuitthemeprovider) +- [ListingTable](#listingtable) +- [AppShell](#appshell) +- [Layout](#layout) +- [Header](#header) +- [Sidebar](#sidebar) +- [Footer](#footer) +- [UserMenu](#usermenu) +- [Form](#form) +- [NotificationPanel](#notificationpanel) +- [NotificationBanner](#notificationbanner) +- [ParticleBackground](#particlebackground) +- [Other Components](#other-components) +- [MUI X Namespaces](#mui-x-namespaces) +- [Hooks](#hooks) +- [Utilities](#utilities) + +--- + +## OxygenUIThemeProvider + +Theme provider that wraps your application. Required at the root level. + +```tsx +import { OxygenUIThemeProvider, OxygenTheme } from '@wso2/oxygen-ui'; +``` + +### Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `children` | `ReactNode` | required | App content | +| `theme` | `Theme` | `OxygenTheme` | Single theme (disables switching) | +| `themes` | `ThemeOption[]` | - | Array of themes (enables switching) | +| `initialTheme` | `string` | First theme key | Initial theme key | + +### ThemeOption Type + +```tsx +interface ThemeOption { + key: string; // Unique identifier + label: string; // Display name + theme: Theme; // MUI Theme object +} +``` + +### Basic Usage + +```tsx +// Single theme (no switching) + + + +``` + +### Theme Switching + +```tsx +import { + OxygenUIThemeProvider, + OxygenTheme, + AcrylicOrangeTheme, + AcrylicPurpleTheme, +} from '@wso2/oxygen-ui'; + +const themes = [ + { key: 'default', label: 'Default', theme: OxygenTheme }, + { key: 'orange', label: 'Orange', theme: AcrylicOrangeTheme }, + { key: 'purple', label: 'Purple', theme: AcrylicPurpleTheme }, +]; + + + + +``` + +--- + +## ListingTable + +Advanced data table with compound component pattern. Supports search, sort, pagination, selection, and bulk actions. + +```tsx +import { ListingTable } from '@wso2/oxygen-ui'; +``` + +### Sub-components + +| Component | Description | +|-----------|-------------| +| `ListingTable.Provider` | Context provider for state management | +| `ListingTable.Container` | Paper wrapper with styling | +| `ListingTable.Toolbar` | Search, filters, and actions bar | +| `ListingTable.Head` | Table header wrapper | +| `ListingTable.Body` | Table body wrapper | +| `ListingTable.Footer` | Table footer (pagination) | +| `ListingTable.Row` | Table row | +| `ListingTable.Cell` | Table cell | +| `ListingTable.SortLabel` | Sortable column header | +| `ListingTable.DensityControl` | Density toggle button | +| `ListingTable.EmptyState` | Empty state display | +| `ListingTable.RowActions` | Row action buttons | +| `ListingTable.CellIcon` | Icon in cell | + +### ListingTable Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `variant` | `'table' \| 'card'` | `'table'` | Display style | +| `density` | `'compact' \| 'standard' \| 'comfortable'` | `'standard'` | Row padding | +| `striped` | `boolean` | `false` | Alternating row colors | +| `bordered` | `boolean` | `false` | Cell borders | + +### Provider Props (Context State) + +```tsx +interface ListingTableProviderProps { + // Search + searchValue?: string; + onSearchChange?: (value: string) => void; + + // Sort + sortField?: string; + sortDirection?: 'asc' | 'desc'; + onSortChange?: (field: string, direction: 'asc' | 'desc') => void; + + // Pagination + page?: number; // 0-indexed + rowsPerPage?: number; + totalCount?: number; + onPageChange?: (page: number) => void; + onRowsPerPageChange?: (rowsPerPage: number) => void; + + // Selection + selected?: readonly string[]; + onSelectionChange?: (selected: readonly string[]) => void; + onSelectAll?: () => void; + onClearSelection?: () => void; + isSelected?: (id: string) => boolean; + + // Filters + filters?: Record; + onFilterChange?: (key: string, value: unknown) => void; + onClearFilters?: () => void; + + // Bulk Actions + onBulkDelete?: (ids: readonly string[]) => void; + onBulkAction?: (actionId: string, ids: readonly string[]) => void; + + // UI State + density?: 'compact' | 'standard' | 'comfortable'; + onDensityChange?: (density: ListingTableDensity) => void; + loading?: boolean; +} +``` + +### Toolbar Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `showSearch` | `boolean` | `false` | Show built-in search | +| `searchSlot` | `ReactNode` | - | Custom search component | +| `searchPlaceholder` | `string` | `'Search...'` | Search placeholder | +| `actions` | `ReactNode` | - | Right-side actions | +| `children` | `ReactNode` | - | Center content | + +### Basic Table + +```tsx + + + + + Name + Status + Actions + + + + {data.map((row) => ( + + {row.name} + {row.status} + + edit(row.id) }, + { id: 'delete', label: 'Delete', onClick: () => delete(row.id) }, + ]} + /> + + + ))} + + + +``` + +### Full-Featured Table with Context + +```tsx +const [search, setSearch] = useState(''); +const [sortField, setSortField] = useState('name'); +const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>('asc'); +const [page, setPage] = useState(0); +const [rowsPerPage, setRowsPerPage] = useState(10); + + { + setSortField(field); + setSortDirection(dir); + }} + page={page} + rowsPerPage={rowsPerPage} + totalCount={data.length} + onPageChange={setPage} + onRowsPerPageChange={setRowsPerPage} +> + + } + /> + + + + + Name + + + Status + + + + + {paginatedData.map((row) => ( + + {row.name} + {row.status} + + ))} + + + + + +``` + +--- + +## AppShell + +Application layout wrapper using compound component pattern. + +```tsx +import { AppShell } from '@wso2/oxygen-ui'; +``` + +### Sub-components + +| Component | Description | +|-----------|-------------| +| `AppShell.Navbar` | Top navigation area (header) | +| `AppShell.Sidebar` | Left sidebar area | +| `AppShell.Main` | Main content area | +| `AppShell.Footer` | Bottom footer area | +| `AppShell.NotificationPanel` | Overlay notification panel | + +### Usage + +```tsx + + +
...
+ + + + ... + + + + {/* React Router outlet */} + + + +