@risalabs_frontend_org/oasis-ui-kit 0.1.0 → 0.3.0

package/README.md

@@ -1,25 +1,521 @@
-# RISA Oasis React UI Components Library
+# RISA Oasis UI Kit
 
-## Running locally
+A comprehensive React UI component library built with TypeScript and SCSS, featuring 25+ production-ready components for building modern web applications.
 
-In the project directory, run:
+## Installation
 
-### `npm install risa-oasis-ui_v2`
+```bash
+npm install @risalabs_frontend_org/oasis-ui-kit
+```
 
-## DO NOT INCREASE BUILD NO. in package.json
+## ⚠️ Important Notes
 
-## DO NOT PUBLISH MANUALLY
+- **DO NOT** increase build number in `package.json`
+- **DO NOT** publish manually - the CI/CD pipeline handles publishing
 
-Once all the dependencies are installed, run
+---
 
-### `npm run storybook`
+## Development
 
-App will run in the development mode.
-Open [http://localhost:6006](http://localhost:6006) to view it in the browser.
+### Prerequisites
 
-The page will reload if you make edits.\
-You will also see any lint errors in the console.
+- Node.js (v18 or higher recommended)
+- npm
 
-### `npm run test`
+### Getting Started
 
-Launches the test runner in the terminal and executes a number of unit tests. Tests are written in [Jest](https://jestjs.io/).
+```bash
+# Install dependencies
+npm install
+
+# Start Storybook development server
+npm run storybook
+```
+
+Open [http://localhost:6006](http://localhost:6006) to view the component library in your browser.
+
+### Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run storybook` | Start Storybook dev server on port 6006 |
+| `npm run build-storybook` | Build static Storybook site |
+| `npm run build` | Build the library for production |
+| `npm run test` | Run unit tests with Jest |
+| `npm run chromatic` | Run visual regression tests with Chromatic |
+
+---
+
+## Components
+
+### Form Controls
+
+#### `Button`
+A versatile button component with multiple variants and sizes.
+
+```tsx
+import { Button } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<Button
+  buttonType="primary" // "primary" | "secondary" | "tertiary" | "danger"
+  size="medium"        // "small" | "medium" | "large"
+  disabled={false}
+  onClick={() => {}}
+>
+  Click Me
+</Button>
+```
+
+#### `ButtonWithDropdown`
+A split button with dropdown menu functionality.
+
+```tsx
+import { ButtonWithDropdown } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<ButtonWithDropdown
+  buttonType="primary"
+  size="medium"
+  disabled={false}
+  menuData={[
+    { label: 'Option 1', onClick: (item) => console.log(item) },
+    { label: 'Option 2', onClick: (item) => console.log(item), color: '#ff0000' }
+  ]}
+  alwaysOpenDropdown={false} // If false, content and chevron act independently
+  onButtonClick={() => {}}   // Called when content area is clicked (split mode)
+>
+  Actions
+</ButtonWithDropdown>
+```
+
+#### `TextInput`
+A flexible text input with label, validation, formatting, and password visibility toggle.
+
+```tsx
+import { TextInput } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<TextInput
+  id="username"
+  label="Username"
+  placeholder="Enter username"
+  required={true}
+  type="text"              // "text" | "number"
+  textHidden={false}       // Enable password mode
+  error="Invalid username"
+  onChange={(data) => console.log(data)}
+  onBlur={(data) => console.log(data)}
+  formatInput={(value) => value.toUpperCase()} // Custom formatting
+/>
+```
+
+#### `Select`
+A custom dropdown select component with search and validation.
+
+```tsx
+import { Select } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<Select
+  id="country"
+  label="Country"
+  placeholder="Select a country"
+  options={[
+    { value: 'us', label: 'United States' },
+    { value: 'uk', label: 'United Kingdom' }
+  ]}
+  required={true}
+  onOptionChange={(data) => console.log(data)}
+/>
+```
+
+#### `CheckBox`
+A styled checkbox component.
+
+```tsx
+import { CheckBox } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<CheckBox
+  id="terms"
+  label="I agree to the terms"
+  defaultValue={false}
+  isDisabled={false}
+  onCheckBoxValueChange={(data) => console.log(data)}
+/>
+```
+
+#### `Toggle` & `ToggleSwitch`
+Toggle switch components for boolean settings.
+
+```tsx
+import { Toggle, ToggleSwitch } from '@risalabs_frontend_org/oasis-ui-kit';
+
+// Toggle with label
+<Toggle
+  id="notifications"
+  label="Enable Notifications"
+  defaultValue={true}
+  onChange={(data) => console.log(data)}
+/>
+
+// Standalone toggle switch
+<ToggleSwitch
+  id="darkMode"
+  defaultChecked={false}
+  onChangeEmit={(data) => console.log(data)}
+/>
+```
+
+### Date & Time Components
+
+#### `DateInput`
+A date input with custom format support using moment.js.
+
+```tsx
+import { DateInput } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<DateInput
+  id="birthdate"
+  label="Date of Birth"
+  placeholder="Select date"
+  format="DD/MM/YYYY"    // Custom display format
+  required={true}
+  onChange={(data) => console.log(data)}
+  onBlur={(data) => console.log(data)}
+/>
+```
+
+#### `DatePicker`
+A calendar-based date picker component.
+
+```tsx
+import { DatePicker } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<DatePicker
+  initialDate={new Date()}
+  onDateChange={(date) => console.log(date)}
+/>
+```
+
+#### `DateRangeCalendar`
+A calendar for selecting date ranges with month/year selectors.
+
+```tsx
+import { DateRangeCalendar } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<DateRangeCalendar
+  initialStartDate={new Date()}
+  initialEndDate={new Date()}
+  onDateRangeChange={(startDate, endDate) => console.log(startDate, endDate)}
+  resetSelection={false}
+/>
+```
+
+#### `TimeDue`
+Component for displaying time-related information.
+
+```tsx
+import { TimeDue } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<TimeDue {...props} />
+```
+
+### File Handling
+
+#### `FileUpload`
+A file upload component with preview and delete functionality.
+
+```tsx
+import { FileUpload } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<FileUpload
+  id="documents"
+  deleteUploadedFile={() => {}}
+/>
+```
+
+#### `AttachmentCard`
+Display uploaded files with upload progress indicator.
+
+```tsx
+import { AttachmentCard } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<AttachmentCard
+  title="document.pdf"
+  isUploading={true}
+  uploadProgress={65}
+  onDelete={() => {}}
+/>
+```
+
+#### `UploadedFileBanner`
+Banner display for uploaded files.
+
+```tsx
+import { UploadedFileBanner } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<UploadedFileBanner {...props} />
+```
+
+### Navigation
+
+#### `SideNavigation`
+A vertical side navigation with tab-style content switching.
+
+```tsx
+import { SideNavigation } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<SideNavigation
+  sideTabContent={[
+    { id: 'profile', label: 'Profile', sideNavContent: ProfileComponent },
+    { id: 'settings', label: 'Settings', sideNavContent: SettingsComponent }
+  ]}
+/>
+```
+
+#### `TabContainer` & `SingleTab`
+Horizontal tab navigation components.
+
+```tsx
+import { TabContainer, SingleTab } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<TabContainer {...props} />
+```
+
+#### `Pagination`
+A pagination control with prev/next buttons.
+
+```tsx
+import { Pagination } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<Pagination
+  currentPage={1}
+  totalPages={10}
+  onPrevious={() => {}}
+  onNext={() => {}}
+  disabled={false}
+/>
+```
+
+#### `Stepper`
+A vertical stepper for multi-step processes.
+
+```tsx
+import { Stepper } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<Stepper
+  id={0}
+  currentActiveIndex={1}
+  label="Step 1: Personal Info"
+  stepperText="1"
+  showDashedLine={true}
+/>
+```
+
+### Feedback & Overlays
+
+#### `Modal`
+A customizable modal dialog with header, body, and footer.
+
+```tsx
+import { Modal, openModal, closeModal } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<Modal
+  dialogId="myModal"
+  title="Confirm Action"
+  saveButtonText="Confirm"
+  cancelText="Cancel"
+  onSave={() => {}}
+  onCancel={() => {}}
+  onClose={() => {}}
+  showSingleButton={false}
+  hideFooter={false}
+  disableSave={false}
+>
+  <p>Are you sure you want to continue?</p>
+</Modal>
+
+// Control modal visibility
+openModal('myModal');
+closeModal('myModal');
+```
+
+#### `Toast`
+Notification toast for success/error messages.
+
+```tsx
+import { Toast, controlToastState } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<Toast
+  id="successToast"
+  type="success"  // "success" | "error"
+  header="Success!"
+  message="Your changes have been saved."
+/>
+
+// Show toast
+controlToastState('successToast', true);
+```
+
+#### `InfoIconWithTooltip`
+An info icon with popover tooltip.
+
+```tsx
+import { InfoIconWithTooltip } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<InfoIconWithTooltip
+  content={<p>This is helpful information</p>}
+  directionToDisplay="bottom" // "left" | "right" | "top" | "bottom"
+  maxWidth={20}  // in rem
+  maxHeight={10} // in rem
+/>
+```
+
+### Layout & Display
+
+#### `HeaderCard`
+A card component for headers/titles.
+
+```tsx
+import { HeaderCard } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<HeaderCard {...props} />
+```
+
+#### `Footer`
+A footer component.
+
+```tsx
+import { Footer } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<Footer {...props} />
+```
+
+#### `NotificationCard`
+A card for displaying notifications.
+
+```tsx
+import { NotificationCard } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<NotificationCard {...props} />
+```
+
+#### `StatusText`
+Display status text with styling.
+
+```tsx
+import { StatusText } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<StatusText {...props} />
+```
+
+#### `ProfileButton`
+A user profile button with avatar and dropdown indicator.
+
+```tsx
+import { ProfileButton } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<ProfileButton
+  name="John Doe"
+  initials="JD"
+  imageUrl="/avatar.jpg"        // Optional: use image instead of initials
+  avatarBackgroundColor="#007028"
+  onClick={() => {}}
+/>
+```
+
+### Loaders
+
+#### `SpinningLoader`
+A simple spinning loading indicator.
+
+```tsx
+import { SpinningLoader } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<SpinningLoader />
+```
+
+#### `ProgressLoaderWithText`
+A loader with text description.
+
+```tsx
+import { ProgressLoaderWithText } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<ProgressLoaderWithText {...props} />
+```
+
+### Search
+
+#### `SearchComponent`
+A search input with button.
+
+```tsx
+import { SearchComponent } from '@risalabs_frontend_org/oasis-ui-kit';
+
+<SearchComponent
+  placeholder="Search..."
+  onSearch={(query) => console.log(query)}
+/>
+```
+
+---
+
+## Types & Utilities
+
+The library exports a comprehensive color palette and types:
+
+```tsx
+import { Colors, productWidgetColors, WidgetType } from '@risalabs_frontend_org/oasis-ui-kit';
+
+// Color palette includes:
+// - Primary Green (primaryGreen1-11)
+// - Primary Gray (primaryGray1-16)
+// - Secondary Purple, Yellow, Orange
+// - Tertiary Red, Magenta, Cyan, Lime, Blue
+// - Grayscale Black
+```
+
+---
+
+## Tech Stack
+
+- **React** 18.x
+- **TypeScript** 5.x
+- **SCSS** for styling
+- **Storybook** 7.x for component documentation
+- **Jest** + React Testing Library for testing
+- **Webpack** for bundling
+- **Moment.js** & **date-fns** for date handling
+- **Ant Design Icons** for icons
+- **React Feather** for additional icons
+
+---
+
+## Project Structure
+
+```
+oasis-ui/
+├── src/
+│   ├── components/       # All UI components
+│   ├── shared/           # Shared styles, types, and utilities
+│   ├── stories/          # Additional Storybook stories
+│   └── SVG/              # SVG icon components
+├── stories/              # Main Storybook stories
+├── public/
+│   └── icons/            # Static SVG icons
+├── index.ts              # Main entry point (exports)
+└── index.d.ts            # TypeScript declarations
+```
+
+---
+
+## Contributing
+
+1. Create a feature branch from `main`
+2. Make your changes
+3. Add/update Storybook stories for your components
+4. Add/update unit tests
+5. Submit a pull request
+
+---
+
+## License
+
+Proprietary - RISA Labs