@scripso-homepad/ui 0.3.6 → 0.3.7

package/README.md

@@ -1,35 +1,63 @@
 # @scripso-homepad/ui
 
-Cross-platform UI component library for Homepad. Components use React Native primitives and work in both **React Web** (via [react-native-web](https://necolas.github.io/react-native-web/)) and **React Native** (Expo).
+Cross-platform UI component library for Homepad. Built with React Native primitives — works in **Expo / React Native** and **React web** (via [react-native-web](https://necolas.github.io/react-native-web/)).
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| `Button` | Primary actions with variants, sizes, and optional icon badge |
+| `Input` | Text field with label, left/right icons, error, and hint |
+| `PhoneInput` | Country code selector + phone number field |
+| `CountryCodeSelector` | Standalone country dial-code dropdown |
+| `Label` | Form field label |
 
 ## Installation
 
+### React Native (Expo)
+
 ```bash
-npm install @scripso-homepad/ui react react-native
+npm install @scripso-homepad/ui react-native-svg
 ```
 
-### React Web
+Expo resolves the package from TypeScript source automatically (`react-native` export). Icons use `react-native-svg` on native.
 
-Also install `react-native-web`:
+### React web
 
 ```bash
-npm install react-native-web
+npm install @scripso-homepad/ui react-native-web
 ```
 
-Alias `react-native` → `react-native-web` in your bundler.
+Configure your bundler to alias `react-native` → `react-native-web` and resolve `.web.tsx` icon files.
 
-#### Vite (React)
+#### Vite
 
 ```ts
 // vite.config.ts
+import path from "node:path";
+import { existsSync } from "node:fs";
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
 
+function resolveUiPackageEntry() {
+  const workspaceEntry = path.resolve(__dirname, "../homepad-ui/src/index.ts");
+  if (existsSync(workspaceEntry)) return workspaceEntry;
+  return path.resolve(__dirname, "node_modules/@scripso-homepad/ui/src/index.ts");
+}
+
 export default defineConfig({
-  plugins: [react()],
+  plugins: [
+    react({
+      include: [
+        /\.[tj]sx?$/,
+        /node_modules\/(@scripso-homepad\/ui|react-native|react-native-web)/,
+      ],
+    }),
+  ],
   resolve: {
     alias: {
       "react-native": "react-native-web",
+      "@scripso-homepad/ui": resolveUiPackageEntry(),
     },
     extensions: [
       ".web.tsx",
@@ -44,6 +72,19 @@ export default defineConfig({
   },
   optimizeDeps: {
     include: ["react-native-web", "@scripso-homepad/ui"],
+    exclude: ["react-native-svg"],
+    esbuildOptions: {
+      resolveExtensions: [
+        ".web.js",
+        ".web.jsx",
+        ".web.ts",
+        ".web.tsx",
+        ".js",
+        ".jsx",
+        ".ts",
+        ".tsx",
+      ],
+    },
   },
 });
 ```
@@ -59,31 +100,64 @@ module.exports = {
       ...config.resolve.alias,
       "react-native$": "react-native-web",
     };
+    config.resolve.extensions = [
+      ".web.tsx",
+      ".web.ts",
+      ".web.jsx",
+      ".web.js",
+      ...config.resolve.extensions,
+    ];
     return config;
   },
 };
 ```
 
-### React Native (Expo)
-
-Install from npm — no extra config needed:
-
-```bash
-npm install @scripso-homepad/ui
-```
-
 ## Usage
 
 ```tsx
-import { Button } from "@scripso-homepad/ui";
-
-export function Example() {
+import {
+  Button,
+  Input,
+  PhoneInput,
+  CountryCodeSelector,
+  colors,
+} from "@scripso-homepad/ui";
+import { KeyIcon } from "@scripso-homepad/ui/src/icons/KeyIcon";
+import { EyeIcon } from "@scripso-homepad/ui/src/icons/EyeIcon";
+
+export function SignUpForm() {
   return (
-    <Button
-      title="Press me"
-      onPress={() => console.log("pressed")}
-      disabled={false}
-    />
+    <>
+      <Button
+        title="Continue"
+        variant="primary"
+        size="lg"
+        showIcon
+        onPress={() => {}}
+        className="w-full"
+      />
+
+      <Input
+        label="Password"
+        placeholder="placeholder"
+        leftIcon={<KeyIcon />}
+        rightIcon={<EyeIcon />}
+        hint="Use at least 8 characters"
+        secureTextEntry
+      />
+
+      <PhoneInput
+        label="Phone"
+        placeholder="placeholder"
+        hint="Include your area code"
+        onCountryCodeChange={(code) => console.log(code)}
+      />
+
+      <CountryCodeSelector
+        value="AM"
+        onValueChange={(code) => console.log(code)}
+      />
+    </>
   );
 }
 ```
@@ -92,93 +166,173 @@ export function Example() {
 
 ### `Button`
 
-| Prop            | Type                                              | Required | Default     | Description                                              |
-| --------------- | ------------------------------------------------- | -------- | ----------- | -------------------------------------------------------- |
-| `title`         | `string`                                          | Yes      | —           | Button label text                                        |
-| `onPress`       | `() => void`                                      | Yes      | —           | Press handler                                            |
-| `disabled`      | `boolean`                                         | No       | `false`     | Disables interaction                                     |
-| `variant`       | `"primary" \| "secondary" \| "outline" \| "ghost"` | No       | `"primary"` | Visual style preset                                      |
-| `size`          | `"small" \| "medium" \| "large"`                  | No       | `"medium"`  | Size preset                                              |
-| `style`         | `StyleProp<ViewStyle>`                            | No       | —           | Extra container styles (web + native)                    |
-| `textStyle`     | `StyleProp<TextStyle>`                            | No       | —           | Extra label styles (web + native)                        |
-| `className`     | `string`                                          | No       | —           | CSS/Tailwind classes for container (web / NativeWind)    |
-| `textClassName` | `string`                                          | No       | —           | CSS/Tailwind classes for label (web / NativeWind)        |
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | — | Button label (use `children` for custom content) |
+| `onPress` | `(event) => void` | — | Press handler |
+| `variant` | `"white" \| "primary" \| "green" \| "gray"` | `"primary"` | Visual style |
+| `size` | `"lg" \| "sm"` | `"lg"` | Size preset |
+| `showIcon` | `boolean` | `false` | Show icon badge |
+| `icon` | `ReactNode` | — | Custom icon (defaults to arrow icon when `showIcon` is true) |
+| `disabled` | `boolean` | `false` | Disable interaction |
+| `style` | `StyleProp<ViewStyle>` | — | Container styles |
+| `textStyle` | `StyleProp<TextStyle>` | — | Label styles |
+| `className` | `string` | — | CSS classes on container (web) |
+| `textClassName` | `string` | — | CSS classes on label (web) |
+
+```tsx
+<Button title="Save" variant="green" size="sm" showIcon onPress={handleSave} />
+<Button title="Custom" showIcon icon={<MyIcon />} onPress={handleSave} />
+```
+
+### `Input`
+
+Extends React Native `TextInput` props.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | — | Label above the field |
+| `leftIcon` | `ReactNode` | — | Icon on the left (20px, color follows state) |
+| `rightIcon` | `ReactNode` | — | Icon on the right |
+| `error` | `string` | — | Error message (shown instead of hint) |
+| `hint` | `string` | — | Helper text below the field |
+| `className` | `string` | — | Wrapper CSS classes (web) |
+| `labelClassName` | `string` | — | Label CSS classes (web) |
+| `inputClassName` | `string` | — | Input CSS classes (web) |
+| `errorClassName` | `string` | — | Error message CSS classes (web) |
+| `hintClassName` | `string` | — | Hint message CSS classes (web) |
+| `containerStyle` | `StyleProp<ViewStyle>` | — | Wrapper styles |
+| `style` | `StyleProp<TextStyle>` | — | Input text styles |
+
+Field height is **52px**. Icons receive `size` and `color` automatically when they accept those props.
+
+### `PhoneInput`
+
+Same props as `Input`, plus:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `countryCode` | `string` | Selected country code (e.g. `"AM"`) |
+| `onCountryCodeChange` | `(code: string) => void` | Country selection handler |
 
-#### Variants and sizes
+Error and hint messages render under the phone number field (not under the country selector).
+
+### `CountryCodeSelector`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | `"AM"` | Selected country code |
+| `onValueChange` | `(code: string) => void` | — | Selection handler |
+| `options` | `Country[]` | built-in list | Country list override |
+| `disabled` | `boolean` | `false` | Disable interaction |
+| `style` | `StyleProp<ViewStyle>` | — | Wrapper styles |
+| `className` | `string` | — | CSS classes (web) |
+
+Also exports `countries`, `defaultCountry`, and `findCountry` for country data.
+
+### `Label`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | — | Label text |
+| `required` | `boolean` | `false` | Show required indicator |
+| `disabled` | `boolean` | `false` | Muted disabled color |
+| `className` | `string` | — | CSS classes (web) |
+
+## Design tokens
 
 ```tsx
-<Button title="Save" onPress={handleSave} variant="primary" size="medium" />
-<Button title="Cancel" onPress={handleCancel} variant="outline" size="small" />
-<Button title="Delete" onPress={handleDelete} variant="secondary" size="large" />
-<Button title="More" onPress={handleMore} variant="ghost" />
+import {
+  colors,
+  brand,
+  stormGray,
+  navy,
+  rubyRed,
+  emeraldGreen,
+  spacing,
+  radii,
+  fonts,
+  buttonTypography,
+  labelTypography,
+} from "@scripso-homepad/ui";
 ```
 
-Preview all combinations in Storybook: `npm run storybook` → **AllVariants**, **AllSizes**, **VariantMatrix**.
+### Brand colors
+
+| Name | Token | Hex |
+|------|-------|-----|
+| Slate Blue | `brand.slateBlue` | `#182E3C` |
+| Storm Gray | `brand.stormGray` | `#455765` |
+| Navy | `brand.navy` | `#08275D` |
+| Ruby Red | `brand.rubyRed` | `#AE0011` |
+| Emerald Green | `brand.emeraldGreen` | `#279D54` |
 
-#### Custom styles (React Native `style`)
+### Color scales
+
+Each palette has steps `0`, `0.5`, `1`, `1.5`, `2` … `8`, `8.5`, exposed as flat tokens:
 
 ```tsx
-<Button
-  title="Save"
-  onPress={handleSave}
-  style={{ backgroundColor: "#dc2626", borderRadius: 999 }}
-  textStyle={{ fontSize: 14, textTransform: "uppercase" }}
-/>
+colors.stormGray0    // #FBFCFC
+colors.stormGray50   // #ECEEF0  (Figma 0.5)
+colors.stormGray500  // #455765  (brand)
+colors.stormGray850  // #151A1E  (Figma 8.5)
+
+colors.navy500       // brand navy
+colors.rubyRed500    // brand ruby red
+colors.emeraldGreen500
 ```
 
-#### Tailwind classes (React web)
+Or use the scale objects: `stormGray["0.5"]`, `navy["5"]`, `rubyRed["5"]`, `emeraldGreen["5"]`.
+
+## Styling on web
 
-`className` is applied to the same `TouchableOpacity` / `Text` DOM nodes as the default styles — layout and padding stay consistent with native:
+`className` props apply Tailwind / CSS classes to the underlying DOM node on web only. On native they are no-ops.
 
 ```tsx
 <Button
-  title="Save"
-  onPress={handleSave}
-  className="!bg-violet-600 shadow-lg"
-  textClassName="text-sm font-bold uppercase"
+  title="Submit"
+  onPress={handleSubmit}
+  className="w-full max-w-md"
 />
-```
 
-Use `!` (important) on Tailwind utilities when overriding default colors, e.g. `!bg-red-500`, because react-native-web applies inline styles from `StyleSheet`.
+<Input
+  label="Email"
+  className="w-full"
+  inputClassName="text-base"
+/>
+```
 
-Ensure Tailwind scans the package if needed:
+When overriding default colors with Tailwind, use `!` (important) because react-native-web applies inline styles:
 
-```js
-content: ["./src/**/*.{js,ts,jsx,tsx}", "./node_modules/@scripso-homepad/ui/**/*.{js,ts,jsx,tsx}"],
+```tsx
+<Button title="Delete" className="!bg-red-600" onPress={handleDelete} />
 ```
 
 ## Development
 
 ```bash
 npm install
-npm run build
 npm run typecheck
 npm run lint
+npm run build
+npm run storybook        # http://localhost:6006
+npm run build-storybook
 ```
 
-### Storybook
-
-Preview components in the browser with hot reload:
+Clear Storybook cache if needed:
 
 ```bash
-npm run storybook
+rm -rf node_modules/.cache/storybook node_modules/.vite
 ```
 
-Opens at [http://localhost:6006](http://localhost:6006). Components render via `react-native-web`.
-
-Build a static Storybook site:
+## Architecture
 
-```bash
-npm run build-storybook
-```
+- **Shared implementation** — one component per platform, React Native primitives throughout
+- **Web icons** — `.web.tsx` files use plain SVG (no `react-native-svg` on web)
+- **Native icons** — `react-native-svg` (peer dependency)
+- **Source resolution** — bundlers import from `src/index.ts` for correct `.web.tsx` resolution
+- **Metro / Expo** — `"react-native"` package export points to TypeScript source
 
 ## Publishing
 
-Push to `main` — CI auto-bumps the patch version and publishes to npm. See [PUBLISHING.md](./PUBLISHING.md).
-
-## Architecture
-
-- **Single shared implementation** — no `.web.tsx` / `.native.tsx` split
-- **React Native primitives** — `TouchableOpacity`, `Text`, `StyleSheet`
-- **Web via react-native-web** — consumers alias `react-native` at build time
-- **Metro source resolution** — `"react-native"` export points to TypeScript source for native bundlers
+See [PUBLISHING.md](./PUBLISHING.md).