Merge pull request #38 from RonasIT/PRD-1608-js-doc-ui-and-utils

PRD-1608 - JSDoc - Ui and Utils

Author: ipakhomov

src/lib/src/ui/safe-area-view/component.tsx

@@ -3,13 +3,36 @@ import { ReactElement, useMemo } from 'react';
 import { StyleSheet, View, ViewProps } from 'react-native';
 import { Edge, useSafeAreaInsets } from 'react-native-safe-area-context';
 
+/**
+ * Props for {@link AppSafeAreaView}.
+ *
+ * @property children Elements rendered inside the padded container.
+ * @property edges An array indicating which edges of the screen to respect. Possible values are 'top', 'right', 'bottom', 'left'. Defaults to all edges.
+ * @property style Custom styles to apply to the view. Note that padding values will be adjusted to respect safe area insets.
+ * @property ...rest  All other {@link https://reactnative.dev/docs/view#props | ViewProps} are forwarded.
+ */
 export interface AppSafeAreaViewProps extends ViewProps {
   edges?: Array<Edge>;
 }
 
 const defaultEdges: Array<Edge> = ['top', 'right', 'bottom', 'left'];
 
-export function AppSafeAreaView({ children, edges = defaultEdges, style = {}, ...props }: AppSafeAreaViewProps): ReactElement {
+/**
+ * A component for granular control of safe area edges on each screen.
+ * The difference from `SafeAreaView` in [react-native-safe-area-context](https://www.npmjs.com/package/react-native-safe-area-context) is that the container adds padding to the elements inside it,
+ * rather than to the entire screen, making it more flexible for use.
+ *
+ * > Requires the `react-native-safe-area-context`.
+ *
+ * @param props Component props. See {@link AppSafeAreaViewProps} for a detailed list.
+ * @returns ReactElement
+ */
+export function AppSafeAreaView({
+  children,
+  edges = defaultEdges,
+  style = {},
+  ...props
+}: AppSafeAreaViewProps): ReactElement {
   const insets = useSafeAreaInsets();
 
   const containerStyle = useMemo(() => {
@@ -21,9 +44,13 @@ export function AppSafeAreaView({ children, edges = defaultEdges, style = {}, ..
 
         return [...acc, { [paddingName]: Number(paddings[paddingName] ?? 0) + insets[edge] }];
       },
-      [style]
+      [style],
     );
   }, [style, insets, edges]);
 
-  return <View style={containerStyle} {...props}>{children}</View>;
+  return (
+    <View style={containerStyle} {...props}>
+      {children}
+    </View>
+  );
 }

src/lib/src/utils/i18n/i18n.ts

@@ -1,3 +1,9 @@
 import { I18n } from 'i18n-js';
 
+/**
+ * Global {@link I18n} instance.
+ *
+ * Import this singleton anywhere you need direct access to `i18n.t()`
+ * or other i18n‑js APIs.
+ */
 export const i18n = new I18n();

src/lib/src/utils/i18n/set-language.ts

@@ -1,9 +1,22 @@
 import * as Localization from 'expo-localization';
 import { i18n } from './i18n';
 
+/**
+ * Register translation tables **once** and receive a helper to change the active language.
+ *
+ * > Requires `i18n-js` and `expo-localization`.
+ *
+ * @typeParam T Map of language codes (`en`, `fr`, `ru`, …) to their translation dictionaries.
+ *
+ * @param translations Object containing translation tables keyed by language code.
+ * @param defaultLanguage Language that will be used when the requested language is missing.
+ *
+ * @returns Function that sets `i18n.locale`.
+ *          When called **without** arguments, the device locale from `expo-localization` is used.
+ */
 export function setLanguage<T extends (typeof i18n)['translations']>(
   translations: T,
-  defaultLanguage: keyof typeof translations
+  defaultLanguage: keyof typeof translations,
 ): (language?: keyof typeof translations) => void {
   i18n.translations = translations;
 

src/lib/src/utils/i18n/use-translation.ts

@@ -1,6 +1,14 @@
 import { TranslateOptions } from 'i18n-js';
 import { i18n } from './i18n';
 
+/**
+ * Returns a function bound to a **base namespace** so you can translate keys without repetition.
+ *
+ * > Requires `i18n-js`.
+ *
+ * @param basePath Translation namespace, e.g. `'ACCOUNT.WELCOME'`.
+ * @returns Translator function `(key, options?) => string`.
+ */
 export function useTranslation(basePath: string) {
   return (key: string, options?: TranslateOptions): string => {
     return i18n.t(`${basePath}.${key}`, options);