@ecohouse/ui 0.1.0 → 0.1.2

package/README.md

@@ -1,58 +1,261 @@
-# eco-cottage-ui (`@ecohouse/ui`)
+# @ecohouse/ui
 
-Presentation-only universal UI package for EcoHouse customer web and mobile.
+Cross-platform UI component library for EcoHouse. Built with React Native primitives — works in **Expo / React Native** and **React web** (via [react-native-web](https://necolas.github.io/react-native-web/)).
 
-## Purpose
+## Components
 
-Reusable design tokens and cross-platform components built with **React Native primitives** + **React Native Web**, documented in Storybook.
+| Component | Description                                                                 |
+| --------- | --------------------------------------------------------------------------- |
+| `Button`  | Pill CTA — `primary` / `secondary`, sizes `lg` / `sm`, optional arrow badge |
+| `Input`   | Text field with label, hint, left/right icons, error & disabled states      |
+| `Icon`    | Dynamic icon by name from the registry (`<Icon name="user" />`)             |
 
-## Package rules (MUST)
+Named icon exports (`UserIcon`, `HomeIcon`, …) are also available. Full icon list: [`docs/icons.md`](./docs/icons.md).
 
-This package is **presentation-only**:
+## Installation
 
-- No backend API clients
-- No application secrets
-- No provider SDKs
-- No EcoHouse booking / domain business logic
+### React Native (Expo)
 
-Application routes, API calls, and booking logic stay in `eco-cottage-web` and `eco-cottage-mobile`. Consumers install published npm versions only (exact pin in `package-lock.json`).
+```bash
+npm install @ecohouse/ui react-native-svg
+```
+
+Expo resolves the package from TypeScript source (`react-native` export). Icons use `react-native-svg` on native.
+
+### React web
+
+```bash
+npm install @ecohouse/ui react-native react-native-web react-native-svg
+```
+
+Configure your bundler to alias `react-native` → `react-native-web` and prefer `.web.tsx` icon files.
+
+#### Vite
+
+```ts
+// vite.config.ts
+import path from "node:path";
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [
+    react({
+      include: [/\.[tj]sx?$/, /node_modules\/(@ecohouse\/ui|react-native|react-native-web)/],
+    }),
+  ],
+  resolve: {
+    dedupe: ["react", "react-dom", "react-native", "react-native-web"],
+    alias: {
+      "react-native": "react-native-web",
+      react: path.resolve(__dirname, "node_modules/react"),
+      "react-dom": path.resolve(__dirname, "node_modules/react-dom"),
+      "react/jsx-runtime": path.resolve(__dirname, "node_modules/react/jsx-runtime"),
+      "react/jsx-dev-runtime": path.resolve(__dirname, "node_modules/react/jsx-dev-runtime"),
+    },
+    extensions: [".web.tsx", ".web.ts", ".web.jsx", ".web.js", ".tsx", ".ts", ".jsx", ".js"],
+  },
+  optimizeDeps: {
+    include: ["react", "react-dom", "react/jsx-runtime", "react-native-web"],
+    exclude: ["react-native-svg", "@ecohouse/ui"],
+    esbuildOptions: {
+      resolveExtensions: [
+        ".web.js",
+        ".web.jsx",
+        ".web.ts",
+        ".web.tsx",
+        ".js",
+        ".jsx",
+        ".ts",
+        ".tsx",
+      ],
+    },
+  },
+});
+```
+
+#### Next.js
+
+```js
+// next.config.js / next.config.ts
+module.exports = {
+  transpilePackages: ["@ecohouse/ui", "react-native-web", "react-native-svg"],
+  webpack: (config) => {
+    config.resolve.alias = {
+      ...config.resolve.alias,
+      "react-native$": "react-native-web",
+    };
+    config.resolve.extensions = [
+      ".web.js",
+      ".web.jsx",
+      ".web.ts",
+      ".web.tsx",
+      ...config.resolve.extensions,
+    ];
+    return config;
+  },
+};
+```
+
+Optional web typography helpers (import fonts first):
+
+```ts
+import "@ecohouse/ui/web/fonts.css";
+import "@ecohouse/ui/web/typography.css";
+```
+
+## Usage
+
+```tsx
+import { Button, Input, Icon, UserIcon, ShowIcon, colors } from "@ecohouse/ui";
+
+export function Example() {
+  return (
+    <>
+      <Button title="Continue" variant="primary" size="lg" showIcon onPress={() => {}} />
+
+      <Input
+        label="Password"
+        placeholder="••••••••"
+        hint="Use at least 8 characters"
+        secureTextEntry
+        leftIcon={<UserIcon size={20} />}
+        rightIcon={<ShowIcon size={20} />}
+        onRightIconPress={() => {}}
+        onChangeText={() => {}}
+      />
+
+      <Icon name="home" size={20} color={colors.white} />
+    </>
+  );
+}
+```
+
+Same API on web and mobile.
+
+## API
+
+### `Button`
+
+Pill CTA — sizes `lg` (44px) / `sm` (32px). Secondary fill uses `colors.grey500`.
 
-## Stack (Architecture v1.4 §§4.4, 5)
+| Prop       | Type                       | Default     | Description       |
+| ---------- | -------------------------- | ----------- | ----------------- |
+| `title`    | `string`                   | —           | Label text        |
+| `onPress`  | `(event) => void`          | required    | Press handler     |
+| `variant`  | `"primary" \| "secondary"` | `"primary"` | Fill style        |
+| `size`     | `"lg" \| "sm"`             | `"lg"`      | Height / padding  |
+| `showIcon` | `boolean`                  | `false`     | Right arrow badge |
+| `icon`     | `ReactNode`                | —           | Custom badge icon |
+| `disabled` | `boolean`                  | `false`     | 60% opacity       |
 
-| Area          | Technology                                |
-| ------------- | ----------------------------------------- |
-| Package       | TypeScript, tsup                          |
-| UI            | React Native primitives, React Native Web |
-| Docs          | Storybook                                 |
-| Lint / format | ESLint, Prettier                          |
-| Tests         | Vitest                                    |
-| Commits       | Conventional Commits (commitlint + husky) |
+```tsx
+<Button title="Continue" variant="primary" size="lg" showIcon onPress={() => {}} />
+<Button title="Cancel" variant="secondary" size="sm" onPress={() => {}} />
+```
+
+### `Input`
+
+Extends React Native `TextInput` props. Default size `lg` (44px pill, radius 60).
+
+| Prop                     | Type                                                         | Default            | Description                |
+| ------------------------ | ------------------------------------------------------------ | ------------------ | -------------------------- |
+| `label` / `showLabel`    | `string` / `boolean`                                         | `"Label"` / `true` | Top label                  |
+| `hint` / `showHint`      | `string` / `boolean`                                         | `"Hint"` / `true`  | Bottom helper              |
+| `placeholder`            | `string`                                                     | `"placeholder"`    | Field placeholder          |
+| `size`                   | `"lg" \| "sm"`                                               | `"lg"`             | Field height               |
+| `state`                  | `"default" \| "filled" \| "active" \| "error" \| "disabled"` | derived            | Override auto state        |
+| `disabled` / `error`     | `boolean`                                                    | `false`            | Disabled / error chrome    |
+| `showLeftIcon`           | `boolean`                                                    | `false`            | Defaults to `UserIcon`     |
+| `showRightIcon`          | `boolean`                                                    | `false`            | Defaults to `ShowIcon`     |
+| `leftIcon` / `rightIcon` | `ReactNode`                                                  | —                  | Custom icons               |
+| `onRightIconPress`       | `() => void`                                                 | —                  | Makes right icon pressable |
+
+| State      | Behavior                                                             |
+| ---------- | -------------------------------------------------------------------- |
+| `default`  | Grey field (`grey700`), white label, grey hint                       |
+| `filled`   | Same chrome when value is present                                    |
+| `active`   | On focus — border `primaryMuted`, left icon `primary`                |
+| `error`    | Border `redMuted`; label, text, placeholder, hint, left icon = `red` |
+| `disabled` | Not editable, muted icons/text                                       |
+
+### `Icon`
+
+| Prop    | Type       | Default          | Description         |
+| ------- | ---------- | ---------------- | ------------------- |
+| `name`  | `IconName` | —                | Registry key        |
+| `size`  | `number`   | `20` or `24`     | Matches SVG viewBox |
+| `color` | `string`   | `colors.primary` | Stroke / fill       |
+
+```tsx
+import { Icon, iconNames, iconGroups } from "@ecohouse/ui";
+
+<Icon name="user" size={20} color="#fff" />;
+```
+
+More: [`docs/icons.md`](./docs/icons.md), [`docs/components.md`](./docs/components.md).
+
+## Design tokens
+
+```tsx
+import { colors, grey, fonts, buttonTypography, inputTypography } from "@ecohouse/ui";
+```
 
-## Current exports
+| Token               | Value           | Use                        |
+| ------------------- | --------------- | -------------------------- |
+| `primary`           | `#B46436`       | Brand / active left icon   |
+| `primaryMuted`      | `#B464360F`     | Input active border        |
+| `red`               | `#A63E3E`       | Error text / icons         |
+| `redMuted`          | `#A63E3E0F`     | Input error border         |
+| `black` / `white`   | `#000` / `#fff` | Surfaces / labels          |
+| `grey0` … `grey950` | Grey scale      | e.g. `grey700` = `#171717` |
 
-| Export             | Description                                               |
-| ------------------ | --------------------------------------------------------- |
-| `Button`           | Primary actions with variants, sizes, optional icon badge |
-| Design tokens      | `colors`, typography, spacing, radii, shadows             |
-| `ArrowUpRightIcon` | Default button badge icon                                 |
+```tsx
+colors.primary;
+colors.grey700;
+grey["5"]; // same as colors.grey500
+```
+
+Full token reference: [`docs/tokens.md`](./docs/tokens.md).
 
-## Scripts
+## Development
 
 ```bash
-npm ci
-npm run lint
-npm run format:check
+npm install
 npm run typecheck
-npm test
+npm run lint
+npm run test
 npm run build
-npm run storybook
+npm run storybook        # http://localhost:6006
 npm run build-storybook
 ```
 
-## Branch model
+Clear Storybook cache if needed:
+
+```bash
+rm -rf node_modules/.cache/storybook node_modules/.vite
+```
+
+## Architecture
+
+- **Shared implementation** — React Native primitives throughout (one API for web + mobile)
+- **Web icons** — `.web.tsx` uses plain SVG (no `react-native-svg` on web)
+- **Native icons** — `react-native-svg` (peer dependency)
+- **Source resolution** — package `react-native` / `import` exports point at `src/index.ts` for correct `.web.tsx` resolution
+- **Presentation only** — no API clients, secrets, or booking domain logic
+
+## Publishing
+
+Push to `main` after CI `verify` passes. The **Release** job publishes `@ecohouse/ui` to npm (bumps patch if the current version already exists). Requires the `NPM_TOKEN` repository secret.
 
-`feature/*` (or ticket branches such as `E0-1-ui/bootstrap-repo`) → `development` → `staging` → `main`
+Consumers:
+
+```bash
+npm install @ecohouse/ui@^0.1.0
+```
 
-## Out of scope for E0-1
+## Package rules
 
-npm publishing / semantic-release / consumer update PRs (E0-3-ui), full component set, consumer app integration.
+- No backend API clients, secrets, provider SDKs, or domain business logic
+- App routes and booking logic stay in `eco-cottage-web` / `eco-cottage-mobile`
+- Prefer published npm versions in consumers