kwant-ui 3.47.1-dev.6 → 3.48.0

package/README.md

@@ -1,73 +1,181 @@
-# Kwant UI Components
+# Kwant-UI
 
-Welcome to Kwant UI Components! This repository contains a collection of reusable user interface components that can be used to build modern and responsive web applications. These components are designed to provide a consistent and intuitive user experience across different platforms and devices.
+`kwant-ui` is the official frontend component library for Kwant-App. It provides a set of reusable, accessible, and themeable React components to build beautiful and consistent user interfaces.
 
-## Table of Contents
+## 📋 Table of Contents
 
-- [Installation](#installation)
-- [Development environment](#Development)
-- [Usage](#usage)
-- [Storybook](#storybook)
+- [About The Project](#about-the-project 'null')
+- [Installation](#installation 'null')
+- [Usage](#usage 'null')
+- [Storybook: Visualizing Components](#storybook-visualizing-components 'null')
+- [Available Scripts for Development](#available-scripts-for-development 'null')
 
-## Installation
+- [Publishing to NPM](#publishing-to-npm)
+- [Folder Structure](#folder-structure 'null')
+- [Contributing](#contributing 'null')
 
-To install Kwant UI Components, you can use NPM or YARN package manager.
+## 🚀 About The Project
 
-```bash
-# npm
- npm install kwant-ui
+This library contains all the foundational UI elements required for the Kwant ecosystem. Each component is built with TypeScript for type safety and styled to fit our design system. The components are bundled using Rollup.js for optimized performance.
 
-# yarn
- yarn add kwant-ui
-```
+**Built With:**
 
-## Development
+- [**React**](https://reactjs.org/ 'null')**:** A JavaScript library for building user interfaces.
 
-#### Clone the repository to your local machine:
+- [**Styled Components**](https://styled-components.com/ 'null')**:** For component level styling.
 
-```bash
- git clone git@gitlab.com:kwant.ai/frontend/ui-components.git
-```
+- [**TypeScript**](https://www.typescriptlang.org/ 'null')**:** For robust, type-safe components.
+- [**Storybook**](https://storybook.js.org/ 'null')**:** For developing and showcasing components in isolation.
+- [**Rollup.js**](https://rollupjs.org/ 'null')**:** For bundling the library into a distributable format.
+- [**ESLint**](https://eslint.org/ 'null')**:** For maintaining code quality.
 
-#### Navigate to the project directory:
+## 📥 Installation
 
-```bash
-cd ui-components
-```
+To use kwant-ui in your project, you need to install the library along with its peer dependencies.
 
-#### Install the required dependencies:
+Install with npm:
 
-```bash
- npm install
+```
+npm install kwant-ui react react-dom styled-components react-viewport-list
 ```
 
-If you encounter a `Could not resolve dependency` error when configuring the packages above, you can either downgrade Rollup to v3.0.0, downgrade the version of the plugins that have the dependency issue to the version suggested in the terminal, or try running the command with the `--force` option.`
+**Note:** `react-dom, styled-components, react-viewport-list` are a peer dependency and must be installed alongside `kwant-ui`.
 
-## Usage
+## 💡 Usage
 
-You can now import the components into your project and start using them. Here's an example of how to use a button component:
+To use `kwant-ui`, you must wrap your application with the `ThemeProvider` from `styled-components` and provide it with a theme from our library. This is a required step for the components to render correctly.
 
-example
+### 1. Set up the ThemeProvider
 
-```jsx
+In your main application entry point (`main.tsx` or `index.tsx`), set up the provider as follows:
+
+```
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { createBrowserRouter, RouterProvider } from 'react-router-dom';
+import { ROUTES } from './routes';
+import { ThemeProvider } from 'styled-components';
+import './assets/styles/index.scss';
+import { colors } from 'kwant-ui';
+
+const router = createBrowserRouter(ROUTES);
+
+ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
+  <React.StrictMode>
+    <ThemeProvider theme={colors}>
+      <RouterProvider router={router} />
+    </ThemeProvider>
+  </React.StrictMode>
+);
+
+```
+
+### 2. Use Components in Your App
+
+Once the `ThemeProvider` is set up, you can import and use any component from the library throughout your application.
+
+```
 import React from 'react';
-import { Button } from 'kwant-ui';
+import { Button, Text } from 'kwant-ui';
 
-function App() {
+function MyComponent() {
   return (
-    <div>
-      <Button variant='primary'>Click me</Button>
-    </div>
+    <>
+      <Text category="subtitle2" weight="semiBold">Welcome</Text>
+      <Button onClick={() => alert('Button Clicked!')} label="Click Me"/>
+    </>
   );
 }
 
-export default App;
+export default MyComponent;
+
+```
+
+## 📖 Storybook: Visualizing Components
+
+We use Storybook for interactive development and documentation. It allows you to browse the component library, view the different states of each component, and interact with them in a live environment.
+
+#### Live Playground
+
+_Explore the live Storybook playground at:_ [_https://ui.kwant.ai/_](https://ui.kwant.ai/ 'null')
+
+#### Local Development
+
+To run Storybook locally, clone this repository and run:
+
+```
+npm run storybook
+```
+
+This will start the Storybook development server on [http://localhost:6006](https://www.google.com/search?q=http://localhost:6006 'null').
+
+## 📜 Available Scripts for Development
+
+These scripts are for the development and maintenance of this library.
+
+### `npm run storybook` or `npm run dev`
+
+Starts the Storybook development server. This is the primary command for developing and testing components in isolation.
+
+### `npm run build`
+
+```
+rm -rf ./dist && rollup -c --bundleConfigAsCjs
 ```
 
-## Storybook
+Builds the library for production. It first cleans the `dist` directory and then uses Rollup to bundle the components into an optimized format suitable for publishing to NPM.
+
+### `npm run prebuild`
+
+This script runs automatically before the `build` script.
+
+- `npm run generate-icon-types`: Executes a utility script to automatically generate TypeScript type definitions for the icons used in the library.
+
+### `npm run build-storybook`
+
+Builds a static version of the Storybook documentation site, which can be deployed and hosted online.
+
+### `npm run lint`
 
-You can explore and interact with the Kwant UI Components using our Storybook. The Storybook showcases all the available components with their various configurations and states.
+```
+eslint "**/*.ts*"
+```
+
+Lints all TypeScript files (`.ts` and `.tsx`) in the project to enforce code quality and style consistency.
+
+## 📦 Publishing to NPM
+
+For instructions on how to publish a new version of `kwant-ui` to the NPM repository, please refer to our internal documentation on Confluence.
+
+[**Publishing Guide: Publishing a version of ui-components(npm package)**](https://ontargetapp.atlassian.net/wiki/x/AwDcfg 'null')
+
+## 📂 Folder Structure
+
+The library is organized as follows:
+
+```
+kwant-ui/
+├── .storybook/         # Storybook configuration files
+├── components/         # The source code for all React components
+├── GlobalStyles/       # Global CSS styles and resets
+├── HOC/                # Higher-Order Components
+├── hooks/              # Custom React hooks
+├── stories/            # Storybook stories for each component
+├── themes/             # Design tokens (colors, spacing, typography)
+├── types/              # Global TypeScript type definitions
+├── utils/              # Utility scripts, like the icon type generator
+├── .eslintrc.cjs       # ESLint configuration
+├── .prettierrc         # Prettier configuration
+├── package.json        # Project dependencies and scripts
+├── rollup.config.js    # Rollup configuration for building the library
+└── tsconfig.json       # TypeScript configuration
+
+```
 
-You can access the Storybook here: [Kwant UI Components Storybook](https://ui.kwant.ai/)
+## 🤝 Contributing
 
-Feel free to experiment with the components and see how they can be customized and integrated into your projects.
+1.  Fork the Project
+2.  Create your Feature Branch (`git checkout -b PR-JIRA-TICKET-ID`)
+3.  Commit your Changes (`git commit -m 'Add NewComponent'`)
+4.  Push to the Branch (`git push origin PR-JIRA-TICKET-ID`)
+5.  Open a Pull Request

package/dist/components/Dropdown/DropdownTypes.d.ts

@@ -1,4 +1,4 @@
-/// <reference types="react" />
+import { RefObject } from 'react';
 import { AvatarDeclarations } from '../Avatar/Avatar.types';
 import { IBaseDropdown } from '../BaseDropdown/BaseDropdownTypes';
 export declare namespace IDropdown {
@@ -10,6 +10,7 @@ export declare namespace IDropdown {
     };
     type Props = Omit<IBaseDropdown.Props, 'height' | 'children'> & {
         maxHeight?: number;
+        isDynamicOptionPosition?: boolean;
         onChange?: React.Dispatch<React.SetStateAction<boolean>>;
         onDropdownVisibilityChange?: () => void;
         data?: Option[];
@@ -32,3 +33,19 @@ export declare namespace IDropdown {
         withInput?: boolean;
     };
 }
+export interface DropdownOffsets {
+    offsetTop?: string;
+    offsetBottom?: string;
+    maxHeight: number;
+}
+export interface UseDropdownPositioningProps {
+    isDynamicOptionPosition?: boolean;
+    targetRef?: RefObject<HTMLElement>;
+    opened: boolean;
+    maxHeight?: number;
+    offsetTop?: string;
+    offsetBottom?: string;
+    searchable?: boolean;
+    dataLength?: number;
+    itemHeight?: number;
+}

package/dist/components/Dropdown/hooks/useDropdownPositioning.d.ts

@@ -0,0 +1,7 @@
+import { DropdownOffsets, UseDropdownPositioningProps } from '../DropdownTypes';
+export declare const useDropdownPositioning: ({ isDynamicOptionPosition, targetRef, opened, maxHeight, offsetTop, offsetBottom, searchable, dataLength, itemHeight, }: UseDropdownPositioningProps) => {
+    currentOffsets: DropdownOffsets;
+    isOpeningUpward: boolean;
+    calculateDropdownPosition: () => void;
+    renderDropDown: boolean;
+};

package/dist/components/DropdownSelect/DropdownSelect.types.d.ts

@@ -3,7 +3,7 @@ import { IDropdown } from '../Dropdown/DropdownTypes';
 export declare namespace IDropdownSelect {
     type Option = IDropdown.Option;
     type Props = IDropdown.Props & {
-        children: React.ReactNode;
+        children?: React.ReactNode;
         toggleOnTargetClick?: boolean;
         withInput?: boolean;
         disabled?: boolean;

package/dist/components/Select/Select.types.d.ts

@@ -17,6 +17,7 @@ export declare namespace ISelect {
         onClear?: () => void;
         onSelect?: (option: ISelect.Option, index?: number) => void;
         disabled?: boolean;
+        isDynamicOptionPosition?: boolean;
     }
     interface Option extends IDropdownSelect.Option {
     }

package/dist/components/TimePicker/TimePicker.d.ts

@@ -0,0 +1,2 @@
+import { TimePickerProps } from './types';
+export declare function TimePicker({ label, disabled, tooltipContent, tooltipPosition, format, onChange, onBlur, value, required, id, period, onlyHours, }: TimePickerProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/TimePicker/index.d.ts

@@ -0,0 +1,2 @@
+import { TimePicker } from './TimePicker';
+export { TimePicker };

package/dist/components/TimePicker/timepicker.styled.d.ts

@@ -0,0 +1,13 @@
+export declare const TimeContainer: import("styled-components").StyledComponent<"div", any, {}, never>;
+export declare const TimeInput: import("styled-components").StyledComponent<"input", any, {
+    format?: string;
+    onlyHours?: boolean;
+}, never>;
+export declare const TimeInputWrapper: import("styled-components").StyledComponent<"div", any, {
+    onlyHours?: boolean;
+}, never>;
+export declare const ColonSeparator: import("styled-components").StyledComponent<"span", any, {}, never>;
+export declare const DisabledMinutes: import("styled-components").StyledComponent<"span", any, {}, never>;
+export declare const DropdownContainer: import("styled-components").StyledComponent<"div", any, {}, never>;
+export declare const DropdownButton: import("styled-components").StyledComponent<"button", any, {}, never>;
+export declare const PeriodText: import("styled-components").StyledComponent<"span", any, {}, never>;

package/dist/components/TimePicker/types.d.ts

@@ -0,0 +1,22 @@
+/// <reference types="react" />
+import { TooltipComponent } from '../Tooltip/types';
+type Period = 'AM' | 'PM';
+type Format = '12' | '24';
+export interface TimePickerProps {
+    onChange?: (value: {
+        time: string;
+        period?: Period;
+    }) => void;
+    onBlur?: (e: React.FocusEvent<HTMLInputElement>) => void;
+    disabled?: boolean;
+    required?: boolean;
+    label?: string;
+    id?: string;
+    value?: string;
+    tooltipContent?: string;
+    tooltipPosition?: TooltipComponent.Position;
+    format?: Format;
+    period?: Period;
+    onlyHours?: boolean;
+}
+export {};

package/dist/index.d.ts

@@ -61,6 +61,7 @@ export * from './components/Charts/HorizontalStackedBarChart';
 export * from './components/Charts/GaugeChart';
 export * from './components/Charts/ProgressChart';
 export * from './components/Charts/LineChart';
+export * from './components/TimePicker';
 export { CALENDAR_CONSTANTS, getDateObjectForCalendarConstants, } from './components/Calendar/CalendarUtils';
 export * from './components/TrendPercentage';
 export * from './components/Charts/WorkerTimeChart';