@hortiview/default-components 1.0.0 → 1.0.1

package/README.md

@@ -1,50 +1,189 @@
-# React + TypeScript + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:
-
-- Configure the top-level `parserOptions` property like this:
-
-```js
-export default tseslint.config({
-  languageOptions: {
-    // other options...
-    parserOptions: {
-      project: ['./tsconfig.node.json', './tsconfig.app.json'],
-      tsconfigRootDir: import.meta.dirname,
-    },
-  },
-})
-```
-
-- Replace `tseslint.configs.recommended` to `tseslint.configs.recommendedTypeChecked` or `tseslint.configs.strictTypeChecked`
-- Optionally add `...tseslint.configs.stylisticTypeChecked`
-- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and update the config:
-
-```js
-// eslint.config.js
-import react from 'eslint-plugin-react'
-
-export default tseslint.config({
-  // Set the react version
-  settings: { react: { version: '18.3' } },
-  plugins: {
-    // Add the react plugin
-    react,
-  },
-  rules: {
-    // other rules...
-    // Enable its recommended rules
-    ...react.configs.recommended.rules,
-    ...react.configs['jsx-runtime'].rules,
-  },
-})
-```
+# Hortiview Default Components
+
+This is a component library that provides default components that possess default translations for the basic languages used in the HortiView Platform.
+
+Supported languages are currently: English, spanish and turkish.
+
+## Install
+
+`npm i @hortiview/default-components`
+
+`yarn add @hortiview/default-components`
+
+## Important Note
+
+To ensure that this library´s components always have access to the current platform language, it is mandatory to pass the language from the base props or from the i18n instance the components are wrapped in.
+
+To do so please call the useChangeDefaultComponentsLanguage-hook in a place where you can access the current language. The current language has to be provided to the hook as a parameter.
+The hook only has to be called once inside of a module.
+
+When using the current language from the base props this might look like shown in the following example:
+
+```tsx
+import { useChangeDefaultComponentsLanguage } from '@hortiview/default-components';
+import { useBasePropsStore } from './stores/BaseStore';
+
+export const ModuleBase = () => {
+  const currentLanguage = useBasePropsStore(state => state.currentLanguage);
+
+  /**
+   * needed to handle translations of the default components
+   */
+  useChangeDefaultComponentsLanguage(currentLanguage);
+
+  return <AnyComponent />;
+};
+```
+
+When using i18next this might look like shown in the following example:
+
+```tsx
+import { useChangeDefaultComponentsLanguage } from '@hortiview/default-components';
+import { AVAILABLE_LANGUAGE_CODES } from '@hortiview/shared-components';
+import { useTranslation } from 'react-i18next';
+
+export const ModuleBase = () => {
+  const { i18n } = useTranslation();
+  /**
+   * needed to handle translations of the default components
+   */
+  useChangeDefaultComponentsLanguage(i18n.language as AVAILABLE_LANGUAGE_CODES);
+
+  return <AnyComponent />;
+};
+```
+
+## Remarks
+
+This library provides form components using [react-hook-form](https://react-hook-form.com/get-started). When you want to use these components please install `react-hook-form` before using them.
+
+## Available Components
+
+1. [DefaultFormNumber](#defaultformnumber)
+1. [DefaultLoadingSpinner](#defaultloadingspinner)
+1. [HealthCheckComponents](#healthcheckcomponents)
+   1. [DataBaseHealthCheck](#databasehealthcheck)
+   1. [DefaultHealthCheck](#defaulthealthcheck)
+   1. [IotServiceHealthCheck](#iotservicehealthcheck)
+   1. [PlatformHealthCheck](#platformhealthcheck)
+1. [ImpatienceLoadingSpinner](#impatienceloadingspinner)
+
+## Available Components
+
+### DefaultFormNumber
+
+Number input field that formats the users input depending on the input language. The component automatically sets the language specific thousand separators and only allows the language specific decimal separator.
+
+```tsx
+import { DefaultFormNumber } from '@hortiview/default-components';
+import { FormProvider, SubmitHandler, useForm } from 'react-hook-form';
+
+const formMethods = useForm<{ birthday: string }>({
+  mode: 'onSubmit',
+});
+
+const { handleSubmit } = formMethods;
+
+<FormProvider {...formMethods}>
+  <form onSubmit={handleSubmit(onSubmit)}>
+    <DefaultFormNumber<{ price: number }>
+      propertyName='price'
+      label='module.price'
+      decimalScale={5}
+      fixedDecimalScale={true}
+      allowNegative={false}
+      allowLeadingZeros={false}
+      prefix=' €'
+    />
+  </form>
+</FormProvider>;
+```
+
+### DefaultLoadingSpinner
+
+Renders a loading spinner. The loading spinner can be customized in size and color. It can also be centered.
+
+```tsx
+import { DefaultLoadingSpinner } from '@hortiview/default-components';
+
+const [isLoading, setIsLoading] = useState(false);
+
+/** add logic that changes state of isLoading */
+
+if (isLoading) return <DefaultLoadingSpinner />;
+return <DefaultComponent />;
+```
+
+### HealthCheckComponents
+
+A screen that shows a health check failed message. It can be used if the check for database health, iot health or HV platform health fails. Please use the default components provided here to ensure a consistent user experience for the HV platform.
+
+If a custom text and type should be displayed please use the shared component `<HealthCheckFailed />` and provide a custom `title` and `subtitle`.
+
+#### DataBaseHealthCheck
+
+```tsx
+import { DataBaseHealthCheck } from '@hortiview/default-components';
+
+const [isHealthy, setIsHealthy] = useState(false);
+
+/** add logic that changes state of isHealthy */
+
+if (!isHealthy) return <DataBaseHealthCheck />;
+return <DefaultComponent />;
+```
+
+#### DataBaseHealthCheck
+
+```tsx
+import { DataBaseHealthCheck } from '@hortiview/default-components';
+
+const [isHealthy, setIsHealthy] = useState(false);
+
+/** add logic that changes state of isHealthy */
+
+if (!isHealthy) return <DataBaseHealthCheck />;
+return <DefaultComponent />;
+```
+
+#### IotServiceHealthCheck
+
+```tsx
+import { IotServiceHealthCheck } from '@hortiview/default-components';
+
+const [isHealthy, setIsHealthy] = useState(false);
+
+/** add logic that changes state of isHealthy */
+
+if (!isHealthy) return <IotServiceHealthCheck />;
+return <DefaultComponent />;
+```
+
+#### PlatformHealthCheck
+
+```tsx
+import { PlatformHealthCheck } from '@hortiview/default-components';
+
+const [isHealthy, setIsHealthy] = useState(false);
+
+/** add logic that changes state of isHealthy */
+
+if (!isHealthy) return <PlatformHealthCheck />;
+return <DefaultComponent />;
+```
+
+### ImpatienceLoadingSpinner
+
+This Loading spinner will automatically change to a specific text, after a certain waiting time, the time is adjustable.
+The default waiting time are 10 seconds.
+
+```tsx
+import { ImpatienceLoadingSpinner } from '@hortiview/default-components';
+
+const [isLoading, setIsLoading] = useState(false);
+
+/** add logic that changes state of isLoading */
+
+if (isLoading) return <ImpatienceLoadingSpinner />;
+return <DefaultComponent />;
+```