@tomo-inc/tomo-ui 0.0.11 → 0.0.13

package/README.md

@@ -0,0 +1,217 @@
+# @tomo-inc/tomo-ui
+
+Tomo UI is a React-based design system built on top of **HeroUI** and **Tailwind CSS v4**.  
+It provides:
+
+- A **component layer** (`Button`, `Card`, `Modal`, etc.) with Tomo defaults
+- A **provider layer** (`TomoUIProvider`) and a **theme hook** (`useTheme`)
+- A **Tailwind v4 plugin** that wires HeroUI and Tomo design tokens together
+
+It is designed so that **applications only depend on `@tomo-inc/tomo-ui`**, without touching the underlying UI framework directly.
+
+---
+
+## 1. Installation
+
+> This package is currently intended for use inside the Tomo monorepo and selected internal projects.
+
+Install from your workspace (example uses `pnpm`):
+
+```bash
+pnpm add @tomo-inc/tomo-ui
+```
+
+Peer dependencies (usually already present in the host app):
+
+- `react` `>=18`
+- `react-dom` `>=18`
+- `tailwindcss` `^4` (for apps that want to use the Tailwind plugin)
+
+---
+
+## 2. Usage
+
+### 2.1 Basic React usage
+
+Wrap your app with `TomoUIProvider` and import components from the root package:
+
+```tsx
+import {
+  TomoUIProvider,
+  Button,
+  Card,
+  CardBody,
+  CardFooter,
+  CardHeader,
+} from "@tomo-inc/tomo-ui";
+
+export function App() {
+  return (
+    <TomoUIProvider>
+      <div className="app-root">
+        <Card>
+          <CardHeader>
+            <h1>Tomo UI Starter</h1>
+          </CardHeader>
+          <CardBody>
+            <p>Now you can start building with @tomo-inc/tomo-ui components.</p>
+          </CardBody>
+          <CardFooter>
+            <Button color="primary">Get Started</Button>
+          </CardFooter>
+        </Card>
+      </div>
+    </TomoUIProvider>
+  );
+}
+```
+
+### 2.2 Tailwind CSS v4 integration
+
+Tomo UI ships a Tailwind v4 plugin that wraps HeroUI and Tomo design tokens.  
+In your main CSS entry (for example `src/index.css`):
+
+```css
+@import "tailwindcss";
+
+@plugin "@tomo-inc/tomo-ui/tailwind/plugin";
+
+@source "./**/*.{js,ts,jsx,tsx,mdx}";
+@source "../node_modules/@tomo-inc/tomo-ui/dist/**/*.{js,mjs}";
+```
+
+Notes:
+
+- `@plugin` references the **Tomo UI plugin only**; your app does not need to reference HeroUI directly.
+- `@source` must include:
+  - Your application source (so Tailwind can see your class usage)
+  - Tomo UI’s `dist` (so Tailwind can generate classes used by Tomo components)
+
+Tailwind v4 is configured via PostCSS only. A minimal `postcss.config.(js|mjs|cjs)` looks like:
+
+```js
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+```
+
+### 2.3 Dynamic theme configuration
+
+Tomo UI allows you to provide a theme configuration at runtime.  
+The type is aligned with HeroUI’s theme configuration surface.
+
+```tsx
+import {
+  TomoUIProvider,
+  useTheme,
+  type ThemeConfig,
+} from "@tomo-inc/tomo-ui";
+
+const themeConfig: ThemeConfig = {
+  themes: {
+    light: {
+      colors: {
+        primary: "#FCD436",
+      },
+    },
+    dark: {
+      colors: {
+        primary: "#FCD436",
+      },
+    },
+  },
+  defaultTheme: "light",
+};
+
+export function Root() {
+  return (
+    <TomoUIProvider themeConfig={themeConfig}>
+      <ThemedApp />
+    </TomoUIProvider>
+  );
+}
+
+function ThemedApp() {
+  const { theme, setTheme } = useTheme();
+
+  return (
+    <div>
+      <p>Current theme: {theme}</p>
+      <button onClick={() => setTheme("light")}>Light</button>
+      <button onClick={() => setTheme("dark")}>Dark</button>
+    </div>
+  );
+}
+```
+
+Under the hood, the provider:
+
+- Runs the Tomo UI Tailwind plugin at build time to generate base tokens
+- Uses `themeConfigToCSS` at runtime to convert your `ThemeConfig` into CSS variables
+- Scopes the variables to the provider’s DOM subtree, enabling per-subtree theming
+
+---
+
+## 3. Architecture Overview
+
+High-level architecture of `@tomo-inc/tomo-ui`:
+
+- **React components**
+  - Most components are **thin wrappers** around HeroUI components.
+  - Props and types are re-exported from the root package so consumers only import from `@tomo-inc/tomo-ui`.
+  - Domain-specific primitives (e.g. formatted numbers, QR code, MFA/passcode inputs) live under `src/components`.
+
+- **Provider and theming**
+  - `TomoUIProvider` wraps `HeroUIProvider` and a custom `ThemeContextProvider`.
+  - `ThemeConfig` (a typed wrapper around HeroUI’s theme config) is converted to CSS variables via `themeConfigToCSS`.
+  - Theme variables are scoped to a unique DOM node, allowing:
+    - Multiple independent theme instances on the same page
+    - Runtime theme switching (light/dark or brand-based)
+
+- **Tailwind v4 integration**
+  - `src/tailwind/plugin.ts` defines `baseConfig` and exports `heroui(baseConfig)` as the Tailwind plugin.
+  - The compiled plugin is exposed as `@tomo-inc/tomo-ui/tailwind/plugin`.
+  - During build, HeroUI’s theme dist is copied into `dist/theme` so that Tailwind can scan it through Tomo UI’s own package paths.
+  - Applications only interact with:
+    - `@plugin "@tomo-inc/tomo-ui/tailwind/plugin";`
+    - `@source "../node_modules/@tomo-inc/tomo-ui/dist/**/*.{js,mjs}";`
+
+- **Dynamic theme vs. build-time theme**
+  - **Build-time**: Tailwind + HeroUI produce the base class names and token structure.
+  - **Runtime**: `ThemeConfig` controls the concrete colors and layout tokens via CSS variables.
+  - This separation allows you to change branding and theme behavior without changing the Tailwind build configuration.
+
+---
+
+## 4. License, Copyright, and Usage
+
+> **Important:** This package is primarily intended for internal use within Tomo, Inc. and for selected partners.  
+> It is not a general-purpose public UI library unless explicitly documented and licensed as such.
+
+- **Ownership**
+  - `@tomo-inc/tomo-ui` is owned and maintained by **Tomo, Inc.**.
+  - All source code, compiled artifacts, and design assets are copyrighted.
+
+- **Usage scope**
+  - Intended for:
+    - Applications and packages inside the Tomo monorepo
+    - Official Tomo products and demos
+    - Partner integrations explicitly authorized by Tomo, Inc.
+  - Not intended for:
+    - Unlicensed redistribution
+    - White-label resale as a standalone UI library
+
+- **License**
+  - Unless otherwise stated in the repository root (e.g. in a `LICENSE` file), usage is governed by Tomo’s internal agreements and partner contracts.
+  - If you are unsure whether you are allowed to use this package, please contact the Tomo team or your technical point of contact.
+
+---
+
+If you are extending `@tomo-inc/tomo-ui` or integrating it into a new application, please:
+
+- Prefer importing from the root package (`@tomo-inc/tomo-ui`) instead of deep imports.
+- Avoid depending on HeroUI directly; treat it as an internal implementation detail.
+- Keep Tailwind integration minimal and aligned with the usage examples above, so that future UI framework changes can remain transparent to applications.
+