npm - @estuary-solutions/rn-core-ui - Versions diffs - 0.0.5 → 0.1.0 - Mend

@estuary-solutions/rn-core-ui 0.0.5 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1761) hide show

package/README.md CHANGED Viewed

@@ -1,743 +1,787 @@
-# Estuary RN Core UI
-[![NPM Version][npm-image]][npm-url]
-[![Build Status][build-image]][build-url]
-[![License][license-image]][license-url]
-`estuary-rn-core-ui` provides a collection of core, reusable, and easily customizable User Interface (UI) Components built for React Native applications. Our goal is to help you build beautiful and consistent user interfaces quickly.
-**Note:** If you are new to this project just follow this command:
-```sh
-# If you are currently in root package folder
-# Run yarn install for the first time
-yarn install
-# Run yarn build for apply you local changes -> build -> copy to example/RNCoreUISample/node_modules
-yarn build
-# From now if you are in example/RNCoreUISample. Just run yarn install
-# All your changes in package will be packed and copy to example/RNCoreUISample/node_modules
-yarn install
-```
-## Table of Contents
-- [Installation](#installation)
-- [Custom components](#custom-components)
-  - [Text](#text)
-  - [GalleryBottomSheet](#gallerybottomsheet)
-- [Custom hooks](#custom-hooks)
-  - [useGalleryAssets](#usegalleryassetsdefaultassettype-assettype)
-- [ScrollPercentage (Future)](#scrollpercentage)
-- [Color pallete](#colors)
-- [Font size template](#fontsize)
-- [Scaling Function](#scaling-function)
-  - [scale(size: number)](#scalesize-number)
-  - [scaleH(size: number)](#scalehsize-number)
-  - [moderateScale(size: number, factor?: number)](#moderatescalesize-number-factor-number)
-  - [moderateHeightScale(size: number, factor?: number)](#moderateheightscalesize-number-factor-number)
-  - [scaleFont(size: number)](#scalefontsize-number)
-  - [IPHONE_12_WIDTH](#iphone_12_width)
-  - [IPHONE_12_HEIGHT](#iphone_12_heigth)
-- [Resolution Function](#resolution-function)
-  - [getPaddingTop()](#getpaddingtop)
-  - [getPaddingBottom()](#getpaddingbottom)
-  - [isTablet](#istablet)
-  - [StylePlatform](#styleplatform)
-  - [statusBarHeight](#statusbarheight)
-- [Converter and format](#converter-and-format)
-  - [convertString(value: any)](#convertstring)
-  - [convertNumber(value: any)](#convertnumber)
-  - [convertSeconds(seconds: number)](#convertseconds)
-  - [formatHours(seconds: number)](#formathour)
-  - [fixedDistance(distance?: number, toFixed?: number)](#fixeddistance)
-  - [formatMoney(num: number, maximumFractionDigits: number, lang: string)](#formatmoney)
-- [Debounce](#debounce)
-- [Others](#others)
-  - [cleanTagHTML(str: string)](#cleantaghtml)
-  - [limitedString(str: string, maxLength: number)](#limitedstring)
-## Installation
-Please install required packages:
-- @react-native-camera-roll/camera-roll: ">=7.10.0" => For access devices media support [GalleryBottomSheet](#gallerybottomsheet) & [useGalleryAssets](#usegalleryassetsdefaultassettype-assettype). `Note`: This package should be upper then 7.10.0. Due to error in v7.7.0 and lowwer version this package won't work correct in [GalleryBottomSheet](#gallerybottomsheet) & [useGalleryAssets](#usegalleryassetsdefaultassettype-assettype)
-- react-native-device-info: ">=8.1.3", => Use for knowing device is table or not
-- react-native-gesture-handler: ">=2.9.0", => Support handling gesture for [GalleryBottomSheet](#gallerybottomsheet)
-- react-native-reanimated: ">=2.8.0", => For handling package animation
-- react-native-svg: ">=12.1.1", => For custom svg
-- react-native-vector-icons: ">=8.1.0", => Please config correct [installation guidline](https://www.npmjs.com/package/react-native-vector-icons#installation) for not handling icon error
-## Custom components
-### Text
-Text component for displaying text with custom styles and loading state. This component also have its own view and can easily be customized.
-#### Props
-| Prop            | Type                   | Default     | Description                                                             |
-| --------------- | ---------------------- | ----------- | ----------------------------------------------------------------------- |
-| **`style`**     | `StyleProp<TextStyle>` | _None_      | Style of the Text component, just like [Text Style Props](https://reactnative.dev/docs/text-style-props)                 |
-| **`color`**     | `ColorValue`           | `"black"`   | Color of the text                                                       |
-| **`bold`**      | `boolean`              | `false`     | Choose to bold the text                                                 |
-| **`children`**  | `React.ReactNode`      | _None_      | Provide the text string or another Text component                       |
-| **`load`**      | `boolean`              | `false`     | Waiting before show Text                                                |
-| **`styleView`** | `StyleProp<ViewStyle>` | _None_      | For custom a View outside Text component                                |
-### GalleryBottomSheet
-A bottom sheet component for displaying a gallery of images and videos. It allows users to select multiple assets and provides a filter for albums.
 <p align="center">
-  <img src="https://s4.gifyu.com/images/bLfMU.gif" width="200" style="display: inline-block; margin-right: 10px;" />
-  <img src="https://s4.gifyu.com/images/bLfzY.gif" width="200" style="display: inline-block; margin-right: 10px;" />
-  <img src="https://s4.gifyu.com/images/bLfMT.gif" width="200" style="display: inline-block;" />
+  <h1 align="center">@estuary-solutions/rn-core-ui</h1>
 </p>
-#### Permissions
-##### Android
-Add this permission to your AndroidManifest.xml:
-```xml
-<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32"/>
-<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="32"/>
-<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
-<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
-```
-##### iOS
-Add this perission to your Info.plist:
-```xml
-<key>NSPhotoLibraryUsageDescription</key>
-<string>App request permission for access your gallery</string>
-<key>NSPhotoLibraryAddUsageDescription</key>
-<string>App request permission for create assets in your gallery</string>
-```
-#### Props
-| Prop                     | Type                                                                | Default                                                   | Description                                                                                                                                                                                                                              |
-|--------------------------|---------------------------------------------------------------------|------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **`isOpen`**     | `boolean` | `false`      | Define to open gallery or not. |
-| **`openHeight`**         | `number`                                                            | `ScreenHeight / 2`                                         | Define the position to open gallery. **Note:** y coordinate of the top of the bottom sheet from the top of the screen                                                                             |
-| **`closeHeight`**        | `number`                                                            | `ScreenHeight`                                             | Define the position when closed gallery. **Note:** y coordinate of the top of the bottom sheet from the top of the screen                                                                         |
-| **`maxHeight`**          | `number`                                                            | `0`                                                        | Define the maximum y coordinate that gallery should snapped at after finger release. **Note:** y coordinate of the top of the bottom sheet from the top of the screen                             |
-| **`headerBarColor`**     | `ColorValue`                                                        | `"#FFFFFF"`                                                | Define the background color of the header bar. **Note:** Full control over the look at each position. Whether it's beautiful or ugly is up to you.                                                 |
-| **`barIconColor`**       | `ColorValue`                                                        | `"#000000"`                                                | Define the header bar icon color. **Note:** Full control over the look at each position. Whether it's beautiful or ugly is up to you.                                                             |
-| **`headerTitleStyle`**   | `Pick<TextStyle, "color" \| "fontFamily" \| "fontWeight">`         | `{ color: '#000000' }`                                     | Define styling for the header title. Only supports: `color`, `fontFamily`, `fontWeight`.                                                                                                          |
-| **`headerTitle`**        | `string`                                                            | `'Tất cả ảnh'`                                             | Define the header title. Will be overridden by folder name when one is selected. Will be truncated if too long.                                                                                   |
-| **`headerTitleIconColor`** | `ColorValue`                                                     | `"#000000"`                                                | Define the header title icon color.                                                                                                                                                                |
-| **`backgroundColor`**    | `ColorValue`                                                        | `"#FFFFFF"`                                                | Define the background color of the gallery bottom sheet.                                                                                                                                           |
-| **`emptyGalleryMsg`**    | `string`                                                            | `'Không có hình ảnh để hiển thị'`                          | Message shown when there are no media items available. Please provide meaningful content.                                                                                                         |
-| **`emptyGalleryMsgStyle`** | `Pick<TextStyle, "color" \| "fontFamily" \| "fontWeight">`      | `{ color: '#000000' }`                                     | Define styling for the empty message. Only supports: `color`, `fontFamily`, `fontWeight`. [See example](#headertitlestyle)                                                                                                        |
-| **`videoIconStyle`**     | `{ circleStyle?: CircleStyleProps; polygonStyle?: CircleStyleProps }` | [See example](#videoiconstyle)                                        | Define styling for the video icon shown for video items. Full control over circle and polygon styles.                                                                                             |
-| **`albumItemStyle`**     | `AlbumFilterStyleProps`                                             | `{ titleColor: '#000000', countColor: '#A0A0A0' }`         | Define style for album filter items. Full control over title and count colors. [See example](#albumitemstyle)                                                                                                                     |
-| **`assetType`**          | `'All'` \| `'Photos'` \| `'Videos'`                                 | `'All'`                                                    | Asset types to display. Can be dynamically changed with setState.                                                                                                                                |
-| **`maxSelectable`**      | `number`                                                            | `5`                                                        | Max number of items selectable. Min: `0`, Max: `10`. Large values may cause performance issues.                                                                                                       |
-| **`onSelectedAssetsChange`** | `(assets: PhotoIdentifier[]) => void`                         | `undefined`                                                | Define function for handling selected assets data. This function will be called when the user select an asset.                                                                                                                     |
-##### headerTitleStyle
-Only support: `color`, `fontFamily`, `fontWeight`.
-```jsx
-  import { GalleryBottomSheet, Text } from '@estuary-solutions/rn-core-ui';
-  <GalleryBottomSheet
-    isOpen={isOpen}
-    ...
-    headerTitleStyle={{
-      color: '#000000',
-      fontFamily: 'Arial',
-      fontWeight: 400,      // Correct ✅
-      fontSize: 20          // Wrong => Unsupport ❌
-    }}
-    ...
-  />
-```
-##### videoIconStyle
-Only support: `fill`, `stroke`, `strokeWidth`.
-For the `strokeWidth`, we accept value start from `scale(5)` to `scale(8)`
-```jsx
-  import { GalleryBottomSheet, Text } from '@estuary-solutions/rn-core-ui';
-  <GalleryBottomSheet
-    isOpen={isOpen}
-    ...
-    videoIconStyle={{
-      circleStyle: {
-        fill: 'rgba(0, 0, 0, 0.5)',
-        stroke: 'black',
-        strokeWidth: 7
-      },
-      polygonStyle: {
-        fill: 'rgba(0, 0, 0, 0.5)',
-        stroke: 'black',
-        strokeWidth: 7
-      },
-    }}
-    ...
-  />
-```
-##### albumItemStyle
-Only support: `titleColor`, `countColor`.
-```jsx
-  import { GalleryBottomSheet, Text } from '@estuary-solutions/rn-core-ui';
-  <GalleryBottomSheet
-    isOpen={isOpen}
-    ...
-    albumItemStyle={{
-      titleColor: '#000000',
-      countColor: '#A0A0A0'
-    }}
-    ...
-  />
-```
-## Custom hooks
-### useGalleryAssets(defaultAssetType?: AssetType)
-You can use this hook for accessing device's assets or requesting related permission.
+<p align="center">
+  A comprehensive React Native UI component library built for building beautiful, consistent mobile applications.
+</p>
-#### Permissions
+<p align="center">
+  <a href="https://www.npmjs.com/package/@estuary-solutions/rn-core-ui">
+    <img src="https://img.shields.io/npm/v/@estuary-solutions/rn-core-ui.svg" alt="npm version" />
+  </a>
+  <a href="https://www.npmjs.com/package/@estuary-solutions/rn-core-ui">
+    <img src="https://img.shields.io/npm/dm/@estuary-solutions/rn-core-ui.svg" alt="npm downloads" />
+  </a>
+  <a href="https://github.com/user/estuary-rn-core-ui/blob/main/LICENSE">
+    <img src="https://img.shields.io/npm/l/@estuary-solutions/rn-core-ui.svg" alt="license" />
+  </a>
+</p>
-##### Android
+---
-Add this permission to your AndroidManifest.xml:
-```xml
-<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32"/>
-<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="32"/>
-<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
-<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
-```
+## Features
-##### iOS
+- **15+ ready-to-use components** — Text, Button, Card, Badge, Avatar, TextField, Accordion, and more
+- **Theming** — `ThemeProvider` + design tokens: light/dark schemes, one hex per brand colour family, per-customer themes with `createTheme()`
+- **Typography roles** — `display` to `caption` through `<Text variant>`, with OS font scaling capped
+- **Icons** — about 180 curated Lucide icons behind `<Icon name>`, typed names, app icons via `registerIcons`
+- **TypeScript** — Full type definitions for every component and utility
+- **Customizable** — Extensible styling via standard React Native `StyleProp` patterns
+- **Lightweight** — Zero runtime dependencies beyond React Native peer deps
-Add this perission to your Info.plist:
-```xml
-<key>NSPhotoLibraryUsageDescription</key>
-<string>App request permission for access your gallery</string>
-<key>NSPhotoLibraryAddUsageDescription</key>
-<string>App request permission for create assets in your gallery</string>
-```
+---
-#### Props
-| Prop                     | Type                                                                | Default                                                   | Description                                                                                                                                                                                                                              |
-|--------------------------|---------------------------------------------------------------------|------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **`defaultAssetType`**     | `AssetType` | `'All'`      | Initiallize the default asset type. |
-| **`albums`**     | `Album[]` | `[]`      | Provide list of albums on current device. |
-| **`assets`**         | `Record<string, PhotoIdentifier[]>` | `{}` | Provide list of assets on current device grouped by album. |
-| **`fullAssets`**         | `PhotoIdentifier[]` | `[]` | Provide list of assets on current device. |
-| **`loading`**         | `boolean` | `false` | Provide loading assets state. |
-| **`error`**         | `string` | `null` | Provide string error if loading cause any error. |
-| **`totalAssets`**         | `number` | `0` | Provide the total assets that has been accessed. |
-| **`fullAssetsPagination`**         | `Pagination` | `undefined` | Provide the object related for pagination on `fullAssets`. |
-| **`loadFullAssets`**         | `Promise function` | `` | Provide function for fecth assets which not grouped by album. Return `true` if has next page. [See example](#usage) |
-| **`loadAssets`**         | `Promise function` | `` | Provide function for fecth assets which grouped by album. Return `true` if has next page. [See example](#usage) |
-| **`pagination`**         | `Pagination` | `undefined` | Provide the object related for pagination on `assets`. |
-| **`requestPermission`**         | `Promise function` | `` | Provide function for request permission. Return `true` if user provided permission. [See example](#usage) |
-| **`checkPermission`**         | `Promise function` | `` | Provide function returning if user has provided permission. [See example](#usage) |
-| **`hasPermission`**         | `boolean` | `false` | Provide a state that keep track user permisison. |
-| **`changeAssetType`**         | `function` | `` | Provide function changing with asset type that you want to fecth. Please notice that, you should provide video permision if want to access videos. Default type `'All'`. [See example](#usage) |
-#### Usage
-```jsx
-  import { View, Text } from 'react-native'
-  import React from 'react'
-  import { useGalleryAssets } from '@estuary-solutions/rn-core-ui';
-  const MyComponent = () => {
-    const [selectedAlbum, setSelectedAlbum] = React.useState<Album | null>(null);
-    const {
-        albums,
-        fullAssets,
-        fullAssetsPagination,
-        loadFullAssets,
-        totalAssets,
-        assets,
-        loadAssets,
-        pagination,
-        requestPermission,
-        hasPermission,
-        changeAssetType,
-    } = useGalleryAssets('All');
-    const getSelectedInfo = (item: any) => {
-      // Do your own selection logic
-    }
-    const toggleAsset = (item: any) => {
-      // Do your own selection logic
-    }
-    return (
-      <View>
-        {(albums.length === 0 || fullAssets.length === 0 || totalAssets == 0) ? (
-          <View>
-            <Text style={[
-              styles.noImage,
-              safeEmptyGalleryMsgStyle
-            ]}>No assets</Text>
-          </View>
-        ) : (
-        <FlatList
-          data={selectedAlbum == null ? fullAssets : assets[selectedAlbum.id]}
-          keyExtractor={(item) => item.node.image.uri}
-          renderItem={({ item }) => {
-            const info = getSelectedInfo(item);
-            return (
-              <TouchableOpacity
-                style={styles.image}
-                onPress={() => toggleAsset(item)}
-                activeOpacity={0.7}
-              >
-                <Image
-                  source={{ uri: item.node.image.uri }}
-                  style={styles.image}
-                />
-                  {
-                    item.node.type === "video/mp4" &&
-                    <PlayCircle size={videoIconSize} />
-                  }
-                  {info.isSelected && (
-                    <SelectItem value={info.index + 1} />
-                  )}
-              </TouchableOpacity>
-            )
-          }}
-          ...
-          onEndReached={() => {
-            //Load more assets
-            if (selectedAlbum == null) {
-              loadFullAssets(15, fullAssetsPagination?.endCursor, assetTypeState);
-            } else {
-              loadAssets(selectedAlbum, 15, pagination[selectedAlbum.id].endCursor, assetTypeState);
-            }
-          }}
-        />
-        )}
-      </View>
-    )
-  }
+## Installation
-  export default MyComponent
+```bash
+npm install @estuary-solutions/rn-core-ui react-native-svg react-native-linear-gradient
+# or
+yarn add @estuary-solutions/rn-core-ui react-native-svg react-native-linear-gradient
 ```
-## Colors
+Requires React Native 0.77+ (New Architecture) and React 18.3+.
-We provide a variety of palete `colors` and some shadows!
+### Peer Dependencies
-### Usage
+| Package                        | Version              | Needed for                                               |
+| ------------------------------ | -------------------- | -------------------------------------------------------- |
+| `react`                        | `>=18.3.0`           | everything                                               |
+| `react-native`                 | `>=0.77.0`           | everything                                               |
+| `react-native-svg`             | `>=15.0.0`           | `Icon` and the components that use it                    |
+| `react-native-linear-gradient` | `>=2.8.3`            | `ButtonGradient`                                         |
+| `react-native-reanimated`      | `>=3.16.0`, optional | `@estuary-solutions/rn-core-ui/draggable-flat-list` only |
+| `react-native-gesture-handler` | `>=2.20.0`, optional | `@estuary-solutions/rn-core-ui/draggable-flat-list` only |
-```jsx
-  import  { colors } from '@estuary-solutions/rn-core-ui/themes';
-  import { StyleSheet } from 'react-native';
+Metro honours the package `exports` map from React Native 0.79; on 0.77 and 0.78 the subpaths resolve through proxy directories shipped in the package, nothing to configure. Jest in your app must transform this package like other React Native libraries (see `CHANGELOG.md`).
-  const styles = StyleSheet.create({
-    container: {
-      flex: 1,
-      backgroundColor: colors.black,
-    },
-  });
-```
+---
-## Fontsize
+## Quick Start
-We provide variety of fontSize that aldready scaled by our [scaleFont](#scalefontsize-number) API
+```tsx
+import {
+  Button,
+  Text,
+  ThemeProvider,
+  createTheme,
+  useStyles,
+} from '@estuary-solutions/rn-core-ui';
-### Usage
+// One hex per family is enough; hover/pressed/subtle/on* are derived.
+const theme = createTheme({
+  name: 'acme',
+  light: { color: { brand: '#df1c29' } },
+});
-```jsx
-  import  { fontSize } from '@kietpt2003/react-native-core-ui/themes';
-  import { StyleSheet } from 'react-native';
+const useAppStyles = () =>
+  useStyles(t => ({
+    screen: { padding: t.space[4], backgroundColor: t.color.surface.default },
+  }));
-  const styles = StyleSheet.create({
-    text: {
-      fontSize: fontSize._16,
-    },
-  });
-```
+function Home() {
+  const styles = useAppStyles();
+  return (
+    <View style={styles.screen}>
+      <Text variant="h2">Welcome</Text>
+      <Button title="Get Started" onPress={() => {}} />
+    </View>
+  );
+}
-## Scaling Function
-```jsx
-  import { scale, verticalScale, moderateScale } from '@estuary-solutions/rn-core-ui/utils';
-  import  { colors, fontSize } from '@estuary-solutions/rn-core-ui/themes'
-  const Component = props =>
-    <View style={{
-      width: scale(30),
-      height: verticalScale(50),
-      padding: moderateScale(5)
-    }}>
-      <Text style={{
-        fontSize: fontSize._16,
-        color: colors.black
-      }}>Component</Text>
-    </View>;
+export default function App() {
+  return (
+    <ThemeProvider theme={theme} scheme="system">
+      <Home />
+    </ThemeProvider>
+  );
+}
 ```
-### scale(size: number)
-Will return a linear scaled result of the provided size, based on your device's screen width.
+---
-#### Usage
+## Components
-```jsx
-  import  { scale } from '@estuary-solutions/rn-core-ui/utils';
-  import { StyleSheet } from 'react-native';
-  const styles = StyleSheet.create({
-    container: {
-      padding: scale(5),
-    },
-  });
-```
-### scaleH(size: number)
-Will return a linear scaled result of the provided size, based on your device's screen height.
+### Text
-#### Usage
+Text component with built-in font weight helpers and responsive sizing.
-```jsx
-  import  { scaleH } from '@estuary-solutions/rn-core-ui/utils';
-  import { StyleSheet } from 'react-native';
+```tsx
+import { Text } from '@estuary-solutions/rn-core-ui';
-  const styles = StyleSheet.create({
-    container: {
-      position: 'absolute',
-      top: scaleH(5),
-    },
-  });
+<Text bold size={18} color="#333">Hello World</Text>
+<Text italic light>Subtitle text</Text>
+<Text semiBold>Semi-bold text</Text>
+```
+| Prop       | Type                                                                                                     | Default                    | Description                                                                        |
+| ---------- | -------------------------------------------------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------- |
+| `variant`  | `'display' \| 'h1' \| 'h2' \| 'h3' \| 'title' \| 'bodyLg' \| 'body' \| 'bodySm' \| 'label' \| 'caption'` | `'body'`                   | Typography role from the theme (size, line height, weight, letter spacing, family) |
+| `size`     | `number`                                                                                                 | `typography.body.fontSize` | Font size                                                                          |
+| `color`    | `string`                                                                                                 | `color.text.primary`       | Text color                                                                         |
+| `bold`     | `boolean`                                                                                                | `false`                    | Font weight 700                                                                    |
+| `semiBold` | `boolean`                                                                                                | `false`                    | Font weight 600                                                                    |
+| `medium`   | `boolean`                                                                                                | `false`                    | Font weight 500                                                                    |
+| `light`    | `boolean`                                                                                                | `false`                    | Font weight 300                                                                    |
+| `thin`     | `boolean`                                                                                                | `false`                    | Font weight 100                                                                    |
+| `italic`   | `boolean`                                                                                                | `false`                    | Italic style                                                                       |
+| `style`    | `StyleProp<TextStyle>`                                                                                   | —                          | Additional styles                                                                  |
+Extends all React Native `TextProps`.
+---
+### Button
+Versatile button with `filled` and `outline` variants, loading state, and icon support.
+```tsx
+import { Button } from '@estuary-solutions/rn-core-ui';
+<Button title="Submit" onPress={handleSubmit} />
+<Button title="Cancel" variant="outline" onPress={handleCancel} />
+<Button title="Loading..." isSubmit />
+<Button title="Disabled" disabled />
+```
+| Prop              | Type                    | Default               | Description                      |
+| ----------------- | ----------------------- | --------------------- | -------------------------------- |
+| `title`           | `string`                | —                     | Button label                     |
+| `variant`         | `'filled' \| 'outline'` | `'filled'`            | Button style variant             |
+| `disabled`        | `boolean`               | `false`               | Disable the button               |
+| `isSubmit`        | `boolean`               | `false`               | Show loading indicator           |
+| `startIcon`       | `React.ReactNode`       | —                     | Icon before title                |
+| `endIcon`         | `React.ReactNode`       | —                     | Icon after title                 |
+| `activeBgColor`   | `string`                | `color.brand.default` | Background color                 |
+| `inactiveBgColor` | `string`                | `color.text.disabled` | Disabled background color        |
+| `borderColor`     | `string`                | `color.brand.default` | Border color for outline variant |
+| `titleStyle`      | `StyleProp<TextStyle>`  | —                     | Title text style                 |
+| `style`           | `StyleProp<ViewStyle>`  | —                     | Container style                  |
+| `onPress`         | `(event) => void`       | —                     | Press handler                    |
+Extends all React Native `TouchableOpacityProps`.
+---
+### ButtonGradient
+Gradient background button powered by `react-native-linear-gradient`.
+```tsx
+import { ButtonGradient } from '@estuary-solutions/rn-core-ui';
+<ButtonGradient
+  title="Gradient Button"
+  colors={['#FF6B6B', '#EE5A24']}
+  onPress={handlePress}
+/>;
+```
+| Prop            | Type                    | Default                  | Description                                   |
+| --------------- | ----------------------- | ------------------------ | --------------------------------------------- |
+| `title`         | `string`                | **Required**             | Button label                                  |
+| `colors`        | `string[]`              | `['#8a3380', '#8a3380']` | Gradient colors                               |
+| `variant`       | `'filled' \| 'outline'` | `'filled'`               | Button style variant                          |
+| `disabled`      | `boolean`               | —                        | Disable the button                            |
+| `isSubmit`      | `boolean`               | —                        | Show a loading indicator instead of the title |
+| `colorsLoading` | `string`                | `'white'`                | Loading indicator color                       |
+| `titleStyle`    | `TextStyle`             | —                        | Title text style                              |
+| `borderColor`   | `string`                | `'#00B4F0'`              | Border color of the `outline` variant         |
+| `styleButton`   | `ViewStyle`             | —                        | Button container style                        |
+| `styleGradient` | `ViewStyle`             | —                        | Gradient container style                      |
+---
+### Card
+Material Design-inspired card system with composable sub-components.
+```tsx
+import {
+  Card,
+  CardHeader,
+  CardContent,
+  CardMedia,
+  CardActions,
+  CardActionArea,
+} from '@estuary-solutions/rn-core-ui';
+<Card variant="elevation" raised>
+  <CardHeader
+    title="Card Title"
+    subheader="Subtitle"
+    avatar={<Avatar alt="A" size={40} />}
+  />
+  <CardContent>
+    <Text>Card body content goes here.</Text>
+  </CardContent>
+  <CardActions>
+    <Button title="Action" onPress={() => {}} />
+  </CardActions>
+</Card>;
 ```
-### moderateScale(size: number, factor?: number)
-Sometimes you don't want to scale everything in a linear manner, that's where moderateScale comes in.
-The cool thing about it is that you can control the resize factor (default is 0.5).
-If normal scale will increase your size by +2X, moderateScale will only increase it by +X, for example:
-➡️ &nbsp;&nbsp;scale(10) = 20
-➡️ &nbsp;&nbsp;moderateScale(10) = 15
-➡️ &nbsp;&nbsp;moderateScale(10, 0.1) = 11
+#### Card
-#### Usage
+| Prop      | Type                        | Default       | Description             |
+| --------- | --------------------------- | ------------- | ----------------------- |
+| `variant` | `'elevation' \| 'outlined'` | `'elevation'` | Card style              |
+| `raised`  | `boolean`                   | `false`       | Increase elevation to 8 |
+| `style`   | `ViewStyle`                 | —             | Container style         |
-```jsx
-  import  { moderateScale } from '@estuary-solutions/rn-core-ui/utils';
-  import { StyleSheet } from 'react-native';
-  const styles = StyleSheet.create({
-    container: {
-      padding: moderateScale(5),
-    },
-  });
-```
+#### CardHeader
-### moderateHeightScale(size: number, factor?: number)
+| Prop                | Type              | Default | Description             |
+| ------------------- | ----------------- | ------- | ----------------------- |
+| `title`             | `React.ReactNode` | —       | Header title            |
+| `subheader`         | `React.ReactNode` | —       | Subtitle text           |
+| `avatar`            | `React.ReactNode` | —       | Left avatar/icon        |
+| `action`            | `React.ReactNode` | —       | Right action element    |
+| `disableTypography` | `boolean`         | `false` | Skip auto Text wrapping |
-Same as [moderateScale](#moderatescalesize-number-factor-number), but using scaleH instead of scale.
+#### CardContent
-#### Usage
+| Prop       | Type                   | Default | Description                        |
+| ---------- | ---------------------- | ------- | ---------------------------------- |
+| `children` | `React.ReactNode`      | —       | Content elements                   |
+| `isLast`   | `boolean`              | `true`  | Extra bottom padding for last item |
+| `style`    | `StyleProp<ViewStyle>` | —       | Container style                    |
-```jsx
-  import  { moderateHeightScale } from '@estuary-solutions/rn-core-ui/utils';
-  import { StyleSheet } from 'react-native';
+#### CardMedia
-  const styles = StyleSheet.create({
-    container: {
-      padding: moderateHeightScale(5),
-    },
-  });
-```
+| Prop          | Type                                              | Default      | Description                                                                               |
+| ------------- | ------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------- |
+| `component`   | `'image' \| 'background'`                         | `'image'`    | Render as Image or ImageBackground                                                        |
+| `source`      | `ImageSourcePropType`                             | **Required** | `{ uri }` or `require(...)`                                                               |
+| `resizeMode`  | `ImageResizeMode`                                 | `'cover'`    | Image resize mode                                                                         |
+| `style`       | `StyleProp<ImageStyle \| ViewStyle>`              | —            | Image or background style (width defaults to 100%)                                        |
+| `renderImage` | `(props: CardMediaImageRenderProps) => ReactNode` | RN `Image`   | Swap in another image component (image variant); receives `source`, `resizeMode`, `style` |
-### scaleFont(size: number)
+#### CardActions
-Will return a linear scaled result of the provided size, based on PixelRatio & scaleAvg.
-You can use [fontSize](#fontsize) from /theme instead of using scalefont().
+| Prop             | Type              | Default | Description                          |
+| ---------------- | ----------------- | ------- | ------------------------------------ |
+| `children`       | `React.ReactNode` | —       | Action buttons                       |
+| `disableSpacing` | `boolean`         | `false` | Remove auto spacing between children |
-#### Usage
+#### CardActionArea
-```jsx
-  import  { scaleFont } from '@estuary-solutions/rn-core-ui/utils';
-  import { StyleSheet } from 'react-native';
+| Prop       | Type              | Default | Description            |
+| ---------- | ----------------- | ------- | ---------------------- |
+| `children` | `React.ReactNode` | —       | Touchable content area |
+| `onPress`  | `() => void`      | —       | Press handler          |
+| `disabled` | `boolean`         | `false` | Disable interaction    |
-  const styles = StyleSheet.create({
-    text: {
-      fontSize: scaleFont(16), // fontSize._16
-    },
-  });
-```
+---
-### IPHONE_12_WIDTH
+### Paper
-Just a constants that specify iPhone 12 width.
-```js
-  import { IPHONE_12_WIDTH } from '@estuary-solutions/rn-core-ui/utils';
-  console.log(IPHONE_12_WIDTH); // 375
-```
+Surface component with elevation and outlined variants. Used internally by Card.
-### IPHONE_12_HEIGTH
+```tsx
+import { Paper } from '@estuary-solutions/rn-core-ui';
-Just a constants that specify iPhone 12 height.
-```js
-  import { IPHONE_12_HEIGTH } from '@estuary-solutions/rn-core-ui/utils';
-  console.log(IPHONE_12_HEIGTH); // 812
+<Paper elevation={2} style={{ padding: 16 }}>
+  <Text>Elevated surface</Text>
+</Paper>;
 ```
-## Resolution Function
+| Prop        | Type                        | Default       | Description                                                                                                   |
+| ----------- | --------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------- |
+| `elevation` | `0 \| 1 \| 2 \| 3`          | `1`           | Theme elevation level, rendered with `boxShadow` (`elevation.0..3`); raised levels use `color.surface.raised` |
+| `variant`   | `'elevation' \| 'outlined'` | `'elevation'` | Surface style                                                                                                 |
+| `square`    | `boolean`                   | `false`       | Remove border radius                                                                                          |
-### getPaddingTop
+---
-Get the top padding based on the device type
-- 26 OPPO
-- 28 NOKIA
+### Badge
-#### Usage
+Notification badge with standard and dot variants.
-```jsx
-  import { getPaddingTop } from '@estuary-solutions/rn-core-ui/utils';
-  const paddingTop = getPaddingTop();
-  console.log("paddingTop:", paddingTop);
-```
+```tsx
+import { Badge } from '@estuary-solutions/rn-core-ui';
+<Badge badgeContent={5}>
+  <Icon name="mail" />
+</Badge>
+<Badge badgeContent={100} max={99}>
+  <Icon name="notifications" />
+</Badge>
+<Badge variant="dot" color="#FF0000">
+  <Icon name="chat" />
+</Badge>
+```
+| Prop           | Type                          | Default                                    | Description                           |
+| -------------- | ----------------------------- | ------------------------------------------ | ------------------------------------- |
+| `children`     | `React.ReactNode`             | **Required**                               | Content to badge                      |
+| `badgeContent` | `number \| string`            | —                                          | Badge value                           |
+| `max`          | `number`                      | `99`                                       | Max before showing `99+`              |
+| `variant`      | `'standard' \| 'dot'`         | `'standard'`                               | Badge type                            |
+| `color`        | `string`                      | `color.brand.default`                      | Badge background color                |
+| `invisible`    | `boolean`                     | `false`                                    | Hide the badge                        |
+| `showZero`     | `boolean`                     | `false`                                    | Show badge when value is 0            |
+| `overlap`      | `'rectangular' \| 'circular'` | `'rectangular'`                            | Position adjustment for content shape |
+| `anchorOrigin` | `{ vertical, horizontal }`    | `{ vertical: 'top', horizontal: 'right' }` | Badge position                        |
-### getPaddingBottom
+---
-Get the bottom padding based on the device type
+### Avatar
-#### Usage
+User avatar with image, text fallback, and icon fallback.
+```tsx
+import { Avatar } from '@estuary-solutions/rn-core-ui';
-```jsx
-  import { getPaddingBottom } from '@estuary-solutions/rn-core-ui/utils';
-  const paddingBottom = getPaddingBottom();
-  console.log("paddingBottom:", paddingBottom);
+<Avatar source={{ uri: 'https://example.com/photo.jpg' }} size={48} />
+<Avatar alt="John Doe" size={40} backgroundColor="#6C63FF" />
+<Avatar variant="rounded" size={56}>
+  <CustomIcon />
+</Avatar>
 ```
-### isTablet
+| Prop              | Type                                     | Default                 | Description                                                                                                |
+| ----------------- | ---------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `source`          | `ImageSourcePropType`                    | —                       | `{ uri }` or `require(...)`                                                                                |
+| `size`            | `number`                                 | `40`                    | Avatar diameter                                                                                            |
+| `variant`         | `'circular' \| 'rounded' \| 'square'`    | `'circular'`            | Shape variant                                                                                              |
+| `alt`             | `string`                                 | —                       | Fallback text (first letter displayed)                                                                     |
+| `backgroundColor` | `string`                                 | `color.brand.default`   | Background when showing text/icon fallback                                                                 |
+| `iconColor`       | `string`                                 | `color.brand.onDefault` | Fallback icon color                                                                                        |
+| `isFirstAlt`      | `boolean`                                | `true`                  | Use first word's initial (`true`) or last word's (`false`)                                                 |
+| `renderImage`     | `(props: AvatarImageProps) => ReactNode` | RN `Image`              | Swap in another image component; receives `source`, `style`, `resizeMode`, `onError`, `accessibilityLabel` |
+| `imageStyle`      | `StyleProp<ImageStyle>`                  | —                       | Extra image style                                                                                          |
+| `textStyle`       | `StyleProp<TextStyle>`                   | —                       | Fallback letter style                                                                                      |
+| `style`           | `StyleProp<ViewStyle>`                   | —                       | Container style                                                                                            |
+**Fallback priority:** image → `children` → `alt` letter → person icon.
-Check if the device is a tablet
+---
-#### Usage
+### TextField
-```jsx
-  import { isTablet } from '@estuary-solutions/rn-core-ui/utils';
-  console.log("isTablet", isTablet); // true/false
-```
-### StylePlatform
-Use this function to get the styles based on the device type
+Feature-rich text input with floating label animation, error states, and helper text.
-@param {Object} styles - StyleProp
-@param {ViewStyle} styles.tablet - Styles for tablet
-@param {ViewStyle} styles.phone - Styles for phone
+```tsx
+import { TextField } from '@estuary-solutions/rn-core-ui';
-#### Props
+<TextField
+  label="Email"
+  value={email}
+  onChangeText={setEmail}
+  placeholder="you@example.com"
+/>
-| Prop                     | Type                                                                | Default                                                   | Description                                                                                                                                                                                                                              |
-|--------------------------|---------------------------------------------------------------------|------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **`styles`**     | `StyleProp<any>` | `undefined`      | Initiallize the styles for table and phone. Its contains 2 fields: `tablet` & `phone`. [See example](#usage-11) |
+<TextField
+  label="Password"
+  value={password}
+  onChangeText={setPassword}
+  error={passwordError ? 'Password must be at least 8 characters' : false}
+  secureTextEntry
+/>
-#### Usage
-```jsx
-  <View style={StylePlatform({
-    tablet: styles.containerTablet,
-    phone: styles.containerPhone
-  })}>
-    <Text style={StylePlatform({
-      tablet: styles.textTablet,
-      phone: styles.textPhone
-    })}>
-      Hello, Platform!
-    </Text>
-  </View>
+<TextField
+  label="Bio"
+  multiline
+  rows={4}
+  maxRows={8}
+  value={bio}
+  onChangeText={setBio}
+/>
 ```
-### statusBarHeight
-statusBarHeight of the device
-#### Usage
-```jsx
-  import { statusBarHeight } from '@estuary-solutions/rn-core-ui/utils';
-  console.log("statusBarHeight", statusBarHeight);
+| Prop                  | Type                     | Default                | Description                  |
+| --------------------- | ------------------------ | ---------------------- | ---------------------------- |
+| `label`               | `string`                 | —                      | Floating label text          |
+| `value`               | `string`                 | —                      | Controlled input value       |
+| `defaultValue`        | `string`                 | —                      | Uncontrolled default value   |
+| `onChangeText`        | `(text: string) => void` | —                      | Change handler               |
+| `error`               | `boolean \| string`      | —                      | Error state or error message |
+| `helperText`          | `string`                 | —                      | Helper text below input      |
+| `errorColor`          | `string`                 | `color.danger.default` | Error state color            |
+| `focusedColor`        | `string`                 | `color.border.focus`   | Focused state color          |
+| `multiline`           | `boolean`                | `false`                | Enable multiline input       |
+| `rows`                | `number`                 | `3`                    | Initial rows for multiline   |
+| `maxRows`             | `number`                 | —                      | Max rows for multiline       |
+| `editable`            | `boolean`                | `true`                 | Enable/disable editing       |
+| `renderStartIcon`     | `(params) => ReactNode`  | —                      | Custom start icon            |
+| `renderEndIcon`       | `(params) => ReactNode`  | —                      | Custom end icon              |
+| `applyTopLabel`       | `boolean`                | `true`                 | Float label to top on focus  |
+| `containerStyle`      | `StyleProp<ViewStyle>`   | —                      | Outer container style        |
+| `inputContainerStyle` | `StyleProp<ViewStyle>`   | —                      | Input area container style   |
+Icon render functions receive `{ focused, hasError, editable }` parameters.
+Extends all React Native `TextInputProps`.
+---
+### Flex
+Shorthand layout component for flexbox patterns.
+```tsx
+import { Flex } from '@estuary-solutions/rn-core-ui';
+<Flex justify="space-between" align="center" gap={12}>
+  <Text>Left</Text>
+  <Text>Right</Text>
+</Flex>
+<Flex vertical gap={8}>
+  <Text>Row 1</Text>
+  <Text>Row 2</Text>
+</Flex>
+```
+| Prop       | Type             | Default        | Description                  |
+| ---------- | ---------------- | -------------- | ---------------------------- |
+| `vertical` | `boolean`        | `false`        | Column direction when `true` |
+| `gap`      | `number`         | `0`            | Gap between children         |
+| `justify`  | `JustifyContent` | `'flex-start'` | `justifyContent` value       |
+| `align`    | `AlignItems`     | —              | `alignItems` value           |
+| `flex`     | `number`         | `0`            | Flex value                   |
+| `wrap`     | `boolean`        | `false`        | Enable flex wrap             |
+Extends all React Native `ViewProps`.
+---
+### Breadcrumb
+Navigation breadcrumb trail with customizable separator.
+```tsx
+import { Breadcrumb } from '@estuary-solutions/rn-core-ui';
+<Breadcrumb
+  items={[
+    { item: 'Home', onPress: () => navigate('Home') },
+    { item: 'Products', onPress: () => navigate('Products') },
+    { item: 'Detail' },
+  ]}
+  separator="/"
+/>;
+```
+| Prop        | Type                        | Default      | Description             |
+| ----------- | --------------------------- | ------------ | ----------------------- |
+| `items`     | `BreadcrumbItem[]`          | **Required** | Breadcrumb entries      |
+| `separator` | `string \| React.ReactNode` | `'›'`        | Separator between items |
+**BreadcrumbItem:**
+| Field      | Type                        | Description                                |
+| ---------- | --------------------------- | ------------------------------------------ |
+| `item`     | `string \| React.ReactNode` | Display content                            |
+| `onPress`  | `() => void`                | Press handler                              |
+| `disabled` | `boolean`                   | Disabled state (auto `true` for last item) |
+---
+### Icon
+Curated [Lucide](https://lucide.dev) icons (about 180, see `assets/icons/manifest.json`) rendered with `react-native-svg`. Names are typed, so a typo fails to compile.
+```tsx
+import { Icon, IconBell, createIcon, registerIcons } from '@estuary-solutions/rn-core-ui';
+<Icon name="bell" />
+<Icon name="circle-alert" size={16} color={theme.color.danger.default} accessibilityLabel="Error" />
+<IconBell size={24} />
+```
+| Prop                 | Type       | Default              | Description                                                                                           |
+| -------------------- | ---------- | -------------------- | ----------------------------------------------------------------------------------------------------- |
+| `name`               | `IconName` | **Required**         | Manifest name (`bell`, `chevron-left`, `circle-check`, ...) or an app icon added with `registerIcons` |
+| `size`               | `number`   | `size.icon.md` (20)  | Width and height in dp                                                                                |
+| `color`              | `string`   | `color.text.primary` | Stroke colour (`currentColor` in the SVG)                                                             |
+| `strokeWidth`        | `number`   | `2`                  | Lucide's default; use 1.5 for a lighter look                                                          |
+| `accessibilityLabel` | `string`   | —                    | When set the icon is announced as an image; otherwise it is decorative                                |
+| ...`SvgProps`        |            |                      | Everything else goes to the root `Svg` (`style`, `testID`, ...)                                       |
+Every icon is also exported as a component (`IconBell`, `IconChevronLeft`, `IconTable`, ...). App-specific glyphs stay in the app:
+```tsx
+const TierGold = createIcon(
+  'tier-gold',
+  ({ size, color, strokeWidth, ...props }) => (
+    <Svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke={color}
+      strokeWidth={strokeWidth}
+      {...props}>
+      <Path d="..." />
+    </Svg>
+  ),
+);
+registerIcons({ 'tier-gold': TierGold });
+declare module '@estuary-solutions/rn-core-ui' {
+  interface IconRegistry {
+    'tier-gold': true;
+  }
+}
 ```
-## Converter and format
-### convertString
+Lucide is ISC licensed (Feather-derived icons MIT); the notices ship in `THIRD_PARTY_LICENSES.md`.
-This function converts input into a string.
-* If the input is null or undefined, it returns an empty string.
-* If the input is an object, it returns a stringified version of the object.
-* Otherwise, it returns the string representation of the input.
+---
-#### Usage
+### Accordion
-```js
-  import { convertString } from '@estuary-solutions/rn-core-ui/utils';
-  const str = convertString(2003); // "2003"
-```
-### convertNumber
+Expandable/collapsible panels with animation support. Available as standalone, grouped, and tree variants.
-This function converts input into a number.
-* If the input is null or undefined, it returns 0.
-* If the input is not a number, it returns 0.
-* Otherwise, it returns the parsed float value of the input.
+#### Accordion (standalone)
-#### Usage
+```tsx
+import { Accordion } from '@estuary-solutions/rn-core-ui';
-```js
-  import { convertNumber } from '@estuary-solutions/rn-core-ui/utils';
-  const num = convertNumber("2003"); // 2003
+<Accordion header={<Text>Section Title</Text>} defaultExpanded>
+  <Text>Section content</Text>
+</Accordion>;
 ```
-### convertSeconds
-This function convert seconds to a string in the format "mm:ss".
+| Prop              | Type                          | Default      | Description               |
+| ----------------- | ----------------------------- | ------------ | ------------------------- |
+| `header`          | `React.ReactNode`             | **Required** | Header content            |
+| `children`        | `React.ReactNode`             | **Required** | Collapsible content       |
+| `expanded`        | `boolean`                     | —            | Controlled expanded state |
+| `defaultExpanded` | `boolean`                     | `false`      | Initial expanded state    |
+| `onChange`        | `(expanded: boolean) => void` | —            | Toggle callback           |
+| `disabled`        | `boolean`                     | —            | Disable toggle            |
-* If the input is less than 0, it returns "00:00".
-* If the input is greater than 3599, it returns "00:00".
+#### AccordionGroup + AccordionItem
-#### Usage
+Only one item open at a time (`single`) or multiple (`multiple`).
-```js
-  import { convertSeconds } from '@estuary-solutions/rn-core-ui/utils';
-  const time = convertSeconds(123); // "02:03"
-```
+```tsx
+import { AccordionGroup, AccordionItem } from '@estuary-solutions/rn-core-ui';
-### formatHour
-Function to format seconds into a string in the format "hh:mm:ss".
-* If the input is less than 0, it returns "00:00:00".
-* If the input is greater than 86399, it returns "00:00:00".
-#### Usage
-```js
-  import { formatHour } from '@estuary-solutions/rn-core-ui/utils';
-  const time = formatHour(3661); // "01:01:01"
+<AccordionGroup type="single" defaultOpenIds={['faq-1']}>
+  <AccordionItem id="faq-1" header={<Text>Question 1</Text>}>
+    <Text>Answer 1</Text>
+  </AccordionItem>
+  <AccordionItem id="faq-2" header={<Text>Question 2</Text>}>
+    <Text>Answer 2</Text>
+  </AccordionItem>
+</AccordionGroup>;
 ```
-### fixedDistance
+#### AccordionTree
-Function to format a distance value.
-- If the input is an integer, it returns the integer value.
-- If the input is a float, it returns the value formatted to a custom toFixed value decimal places.
-- If the input is null or undefined, it returns 0.
+Render nested tree structures from data.
-*Note:* The toFixed value should be between 1 and 5, otherwise it defaults to 2.
+```tsx
+import { AccordionTree } from '@estuary-solutions/rn-core-ui';
-#### Usage
+<AccordionTree
+  type="multiple"
+  data={[
+    {
+      id: 'root',
+      title: 'Root',
+      children: [
+        { id: 'child-1', title: 'Child 1' },
+        { id: 'child-2', title: 'Child 2', children: [...] },
+      ],
+    },
+  ]}
+  renderItem={({ item, level }) => (
+    <Text style={{ paddingLeft: level * 16 }}>{item.title}</Text>
+  )}
+/>
+```
+---
+### DraggableFlatList
+Drag-to-reorder list powered by `react-native-gesture-handler` and `react-native-reanimated`.
+```tsx
+import { DraggableFlatList } from '@estuary-solutions/rn-core-ui/draggable-flat-list';
+<DraggableFlatList
+  data={items}
+  keyExtractor={item => item.id}
+  renderItem={({ item, drag, isActive }) => (
+    <TouchableOpacity
+      onLongPress={drag}
+      style={{ opacity: isActive ? 0.5 : 1 }}>
+      <Text>{item.label}</Text>
+    </TouchableOpacity>
+  )}
+  onDragEnd={({ data }) => setItems(data)}
+/>;
+```
+| Prop             | Type                           | Default      | Description                                                   |
+| ---------------- | ------------------------------ | ------------ | ------------------------------------------------------------- |
+| `data`           | `T[]`                          | **Required** | List data                                                     |
+| `renderItem`     | `RenderItem<T>`                | **Required** | Item renderer (receives `{ item, drag, isActive, getIndex }`) |
+| `keyExtractor`   | `(item, index) => string`      | **Required** | Unique key extractor                                          |
+| `onDragEnd`      | `({ data, from, to }) => void` | —            | Called when drag finishes with reordered data                 |
+| `onDragBegin`    | `(index) => void`              | —            | Called when drag starts                                       |
+| `containerStyle` | `StyleProp<ViewStyle>`         | —            | Container style                                               |
+The subpath also exports `ScaleDecorator`, `ShadowDecorator`, `OpacityDecorator`, `NestableDraggableFlatList`, `NestableScrollContainer` and the `RenderItemParams` / `DragEndParams` types. It needs the optional peers `react-native-reanimated` and `react-native-gesture-handler`; apps that never import it do not.
+---
+### ImageView
+Full-screen image viewer: modal, swipe between images, double-tap zoom, swipe down to close. Lives on its own subpath.
+```tsx
+import { ImageView } from '@estuary-solutions/rn-core-ui/image-view';
+<ImageView
+  images={[{ uri: 'https://example.com/a.jpg' }, require('./b.png')]}
+  imageIndex={0}
+  visible={visible}
+  onRequestClose={() => setVisible(false)}
+/>;
+```
+| Prop                                  | Type                                    | Default              | Description                                    |
+| ------------------------------------- | --------------------------------------- | -------------------- | ---------------------------------------------- |
+| `images`                              | `ImageSource[]`                         | **Required**         | `ImageURISource` or `ImageRequireSource` items |
+| `imageIndex`                          | `number`                                | **Required**         | Index shown first                              |
+| `visible`                             | `boolean`                               | **Required**         | Show or hide the modal                         |
+| `onRequestClose`                      | `() => void`                            | **Required**         | Called when the viewer asks to close           |
+| `onImageIndexChange`                  | `(index: number) => void`               | —                    | Called after paging to another image           |
+| `onLongPress`                         | `(image: ImageSource) => void`          | —                    | Long-press handler                             |
+| `swipeToCloseEnabled`                 | `boolean`                               | `true`               | Swipe vertically to close                      |
+| `doubleTapToZoomEnabled`              | `boolean`                               | `true`               | Double tap to zoom                             |
+| `delayLongPress`                      | `number`                                | `800`                | Long-press delay in ms                         |
+| `animationType`                       | `ModalProps['animationType']`           | `'fade'`             | Modal animation                                |
+| `presentationStyle`                   | `ModalProps['presentationStyle']`       | —                    | Modal presentation style                       |
+| `backgroundColor`                     | `string`                                | `'#000000'`          | Backdrop color                                 |
+| `HeaderComponent` / `FooterComponent` | `ComponentType<{ imageIndex: number }>` | default close header | Custom header and footer                       |
+| `keyExtractor`                        | `(image, index) => string`              | uri or require id    | List key extractor                             |
+---
+## Theming
+Every component reads design tokens from the nearest `ThemeProvider`; without one it renders the neutral light theme (generic blue brand, slate neutrals).
+```tsx
+import {
+  ThemeProvider,
+  createTheme,
+  useTheme,
+  useStyles,
+} from '@estuary-solutions/rn-core-ui';
+export const hafele = createTheme({
+  name: 'hafele',
+  light: {
+    color: {
+      brand: '#df1c29', // one hex: hover, pressed, subtle, onDefault, onSubtle are derived
+      accent: '#df1c29',
+      danger: { default: '#b50617', subtle: '#fcd0cf' }, // explicit keys win, the rest is derived
+    },
+    radius: { md: 8 },
+    typography: { fontFamily: { sans: 'IBM Plex Sans' } }, // the app bundles the font
+  },
+  // dark omitted: the light overrides are re-applied onto the neutral dark scheme
+});
-```js
-  import { fixedDistance } from '@estuary-solutions/rn-core-ui/utils';
-  const distance = fixedDistance(123.456); // "123.46"
-  const distance2 = fixedDistance(123.4567, 3); // "123.457"
+<ThemeProvider theme={hafele} scheme="system">
+  {children}
+</ThemeProvider>;
 ```
-### formatMoney
-Function to format money values.
+| API                                           | Description                                                                                                                                                               |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createTheme({ name, light, dark? })`         | Pure; call at module scope. Returns `{ name, light, dark }` fully resolved. Colour families accept a hex or a partial object. `space` cannot be overridden (dev warning). |
+| `ThemeProvider`                               | Props `theme` (default `neutralTheme`) and `scheme`: `'light' \| 'dark' \| 'system'` (default, follows the OS).                                                           |
+| `useTheme()`                                  | The active scheme's tokens plus `name` and `scheme`. Stable identity per theme and scheme.                                                                                |
+| `useStyles(factory)`                          | `StyleSheet.create(factory(theme))`, cached per factory and theme value. Define the factory at module scope.                                                              |
+| `neutralTheme`, `neutralLight`, `neutralDark` | The shipped theme and its resolved schemes.                                                                                                                               |
-#### Props
+### Token vocabulary
-| Prop                     | Type                                                                | Default                                                   | Description                                                                                                                                                                                                                              |
-|--------------------------|---------------------------------------------------------------------|------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **`num`**     | `number` | `0`      | Define the value need to be format. |
-| **`maximumFractionDigits`**     | `number` | `0`      | Define the maximum fraction digits. [See example](#usage-18) |
-| **`lang`**     | `string` | `en-US`      | Define the language. This should be a BCP 47 language tag (e.g., 'en-US', 'vi-VN'). [View detail](#lang-prop) |
+| Group                                                          | Keys                                                                                                                                                                                                           |
+| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `color.brand`, `color.accent`                                  | `default`, `hover`, `pressed`, `subtle`, `onDefault`, `onSubtle`                                                                                                                                               |
+| `color.success`, `color.warning`, `color.danger`, `color.info` | `default`, `subtle`, `border`, `onDefault`, `onSubtle`                                                                                                                                                         |
+| `color.text`                                                   | `primary`, `secondary`, `tertiary`, `disabled`, `inverse`, `link`                                                                                                                                              |
+| `color.surface`                                                | `default`, `raised`, `sunken`, `overlay`, `inverse`                                                                                                                                                            |
+| `color.border`                                                 | `default`, `strong`, `focus`, `disabled`                                                                                                                                                                       |
+| `typography`                                                   | roles `display`, `h1`, `h2`, `h3`, `title`, `bodyLg`, `body`, `bodySm`, `label`, `caption` (`fontFamily`, `fontSize`, `lineHeight`, `fontWeight`, `letterSpacing`); `fontFamily.sans`; `maxFontSizeMultiplier` |
+| `space`                                                        | `0,1,2,3,4,5,6,8,10,12` = 0, 4, 8, 12, 16, 20, 24, 32, 40, 48 dp (fixed)                                                                                                                                       |
+| `radius`                                                       | `xs` 2, `sm` 4, `md` 8, `lg` 12, `xl` 16, `full`                                                                                                                                                               |
+| `elevation`                                                    | `0..3`, `boxShadow` strings (New Architecture)                                                                                                                                                                 |
+| `size`                                                         | `icon.sm/md/lg` 16/20/24, `control.sm/md/lg` 32/36/40, `touchTarget` 44                                                                                                                                        |
+| `breakpoint`                                                   | `sm` 480, `md` 768, `lg` 1024 (window width, use with `useWindowDimensions`)                                                                                                                                   |
-#### lang prop
+Tokens are authored as DTCG JSON in `tokens/` and generated into the package with `yarn tokens`; see `tokens/README.md` and ADR-0001. Extend the theme type for your own groups with module augmentation of `ThemeExtensions`.
-This is a string that contains a language code and an optional country code, separated by a hyphen.
+---
-*Structure:* `"[languageCode]-[countryCode]"`
-*Example:* `'en-IN'` => en: Language English, IN: Country India
-*Reference:*
-- [List of ISO 639 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes)
-- [List of ISO 3166-1 country codes](https://vi.wikipedia.org/wiki/ISO_3166-1)
+## Utilities
-#### Usage
+Non-UI helpers, exported from the root.
-```js
-  import { formatMoney } from '@estuary-solutions/rn-core-ui/utils';
-  const money = formatMoney(1234567.89); // "1,234,568"
-  const money2 = formatMoney(1234567.89, 2); // "1,234,567.89"
-  const money3 = formatMoney(1234567.89, 2, 'vi-VN'); // "1.234.567,89"
+```tsx
+import {
+  formatMoney,
+  debounce,
+  cleanTagHTML,
+  WEB,
+} from '@estuary-solutions/rn-core-ui';
 ```
-## Debounce
+| Export                                          | Description                              |
+| ----------------------------------------------- | ---------------------------------------- |
+| `IOS` / `ANDROID` / `WEB` / `MACOS` / `WINDOWS` | `boolean` platform flags                 |
+| `convertString(value)`                          | Safe conversion to string (null → `""`)  |
+| `convertNumber(value)`                          | Safe conversion to number (null → `0`)   |
+| `convertSeconds(seconds)`                       | Seconds → `"mm:ss"`                      |
+| `formatHour(seconds)`                           | Seconds → `"hh:mm:ss"`                   |
+| `fixedDistance(distance, toFixed?)`             | Format decimal distance                  |
+| `formatMoney(num, fractionDigits?, lang?)`      | Locale-aware money formatting            |
+| `cleanTagHTML(str)`                             | Strip HTML tags and `&nbsp;`             |
+| `limitedString(str, maxLength?)`                | Truncate to word limit (default 5 words) |
+| `debounce(fn, delay)`                           | Debounce with `.cancel()` and `.flush()` |
+| `sum(values)`                                   | Sum of numbers                           |
+| `filterAllowedTextStyle(style)`                 | Keep only text style keys                |
-- Creates a debounced function that delays invoking the provided function until after a specified delay in milliseconds has elapsed since the last time the debounced function was invoked.
-- The debounced function comes with `cancel` and `flush` methods to cancel the debounced invocation and to immediately invoke the function, respectively.
+Removed in 0.1.0: `scale`, `scaleH`, `scaleFont`, `moderateScale`, `width`, `height` (use theme tokens and `useWindowDimensions()`), `isTablet`, `statusBarHeight`, `getPaddingTop`, `getPaddingBottom`, `StylePlatform` (use `react-native-safe-area-context`).
-### Usage
+---
-```jsx
-  import { debounce } from '@estuary-solutions/rn-core-ui/utils';
-  const onChangeText = debounce(() => {
-    console.log('Function executed!');
-  }, 1000);
+## Import Paths
-  //Flush case
-  const debouncedLog = debounce(logMessage, 2000);
-  debouncedLog("Waiting 2s...");
-  setTimeout(() => {
-    debouncedLog.flush(); // Immediately execute the function
-  }, 1000);
+| Path                                                | Contents                                                                                             |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `@estuary-solutions/rn-core-ui`                     | All components and their prop types, `ThemeProvider`/`createTheme`/`useTheme`/`useStyles`, utilities |
+| `@estuary-solutions/rn-core-ui/draggable-flat-list` | `DraggableFlatList`, decorators, nestable variants (needs reanimated + gesture-handler)              |
+| `@estuary-solutions/rn-core-ui/image-view`          | `ImageView`                                                                                          |
-  //Cancel case
-  debouncedLog("Canceled");
-  setTimeout(() => {
-    debouncedLog.cancel(); // Don't execute the function
-  }, 1000);
-```
-## Others
+The former `/themes`, `/utils`, `/Cards/*`, `/Badges/*`, `/Accordion/*` and `/ImageView/*` subpaths were removed in 0.1.0; see `CHANGELOG.md` for the migration table.
-### cleanTagHTML
+---
-Provide a function to clean HTML tags and &nbsp; from a string.
+## Contributing
-#### Usage
+See `CONTRIBUTING.md` for the development workflow, `CHANGELOG.md` for release notes, `docs/design-system/release.md` for the npm + Figma kit release steps and `docs/adr/` for architecture decisions. Variant catalogues (`BUTTON_VARIANTS`, `TEXT_VARIANTS`, ...) are exported so app code and the Figma kit contract share one source.
-```js
-  import { cleanHTML } from '@estuary-solutions/rn-core-ui/utils';
-  const raw = `
-    <div>Hello&nbsp;&nbsp;&nbsp;World</div>
-    <p>This is&nbsp;a <strong>test</strong></p>
-  `;
-  console.log(cleanHTML(raw));
-  // Output:
-  // Hello
-  // World
-  // This is a test
-```
+---
-### limitedString
+## License
-Function to limit the number of words in a string.
-- `str` - The string to limit. *Default:* str = ''
-- `maxLength` - The maximum number of words allowed. *Default:* maxLength = 5
+MIT
-#### Usage
+---
-```js
-  import { limitedString } from '@estuary-solutions/rn-core-ui/utils';
-  const inputString  = "Lorem Ipsum is simply dummy text of the printing and typesetting industry";
-  console.log(limitedString(inputString)); // "Lorem Ipsum is simply dummy..."
-```
+<p align="center">
+  Powered by <a href="https://estuary-solutions.com">Estuary Solutions</a>
+</p>