@deloraprotocol/widget 1.0.0

package/README.md

@@ -0,0 +1,175 @@
+# @deloraprotocol/widget
+
+A React widget component library for crypto trading UI, migrated from delora-exchange (Angular). Includes Trade widget, token selection, network selection, and slippage panel. **Consumers do not need Tailwind** — the library ships compiled CSS.
+
+**Note:** Wallet connection is not implemented. The widget shows placeholder UI for swap actions.
+
+## Installation
+
+```bash
+npm install @deloraprotocol/widget react react-dom
+```
+
+## Import styles
+
+You must import the library CSS once in your app (e.g. in your root entry file):
+
+```ts
+import "@deloraprotocol/widget/styles.css";
+```
+
+## Usage
+
+### Trade Widget
+
+```tsx
+import { TradeWidget } from "@deloraprotocol/widget";
+
+<TradeWidget
+  theme="dark"
+  config={{
+    dataBaseUrl: "https://your-app.com",  // or "" for same-origin
+    apiBase: "https://api.delora.build",
+  }}
+/>
+```
+
+`dataBaseUrl` must point to a server that hosts:
+- `/data/networks.json`
+- `/data/tokens.json`
+- `/data/tokens_search.json`
+
+Use `""` for same-origin (e.g. when data is in your app's public folder).
+
+### Simple Widget (MyWidget)
+
+```tsx
+import { MyWidget } from "@deloraprotocol/widget";
+
+<MyWidget theme="light" />
+<MyWidget theme="dark" />
+<MyWidget vars={{ accent: "#22c55e", radius: "24px" }} />
+<MyWidget className="max-w-md" style={{ marginLeft: "2rem" }} />
+```
+
+## API
+
+### Exports
+
+- `MyWidget` — the widget component
+- `MyWidgetTheme` — `"light" | "dark"`
+- `MyWidgetVars` — typed object for token overrides
+- `MyWidgetProps` — component props
+
+### `MyWidgetProps`
+
+| Prop     | Type              | Description                                      |
+|----------|-------------------|--------------------------------------------------|
+| `theme`  | `"light" \| "dark"` | Built-in theme (default: `"light"`)              |
+| `vars`   | `Partial<MyWidgetVars>` | Override theme tokens via CSS variables      |
+| `className` | `string`       | Applied to root (for host layout/styling)        |
+| `style`  | `React.CSSProperties` | Applied last for advanced overrides         |
+
+Extends `React.HTMLAttributes<HTMLDivElement>` for other div props.
+
+## Why no Tailwind required in host
+
+The library uses Tailwind only at **build time** to author styles. The output is plain compiled CSS shipped in `dist/styles.css`. Your host app imports this CSS file and does not need Tailwind, PostCSS, or any build-time Tailwind configuration.
+
+## Style isolation
+
+The library provides style isolation **without Shadow DOM**:
+
+1. **Our styles don't affect the host**: We disable Tailwind preflight and do not emit global element selectors (e.g. no `button {}` or `h1 {}`). All styling is class-based and scoped within the widget markup.
+
+2. **Host styles have limited impact on us**: We add a minimal scoped reset under `[data-delora-widget-root]`:
+   - `box-sizing: border-box` on root and descendants
+   - Explicit `font-family`, `font-size`, `color`, `line-height` on the root
+
+3. **Limitations**: Host global styles (e.g. `* { box-sizing: content-box; }` or `button { font-size: 30px; }`) can still affect the widget in extreme cases. We mitigate by setting explicit values on the widget root and avoiding reliance on inherited defaults.
+
+## Build
+
+```bash
+npm run build
+```
+
+Outputs:
+- `dist/index.js` (ESM)
+- `dist/index.d.ts`
+- `dist/styles.css`
+
+## Publishing to npm
+
+### Prerequisites
+
+- [npm account](https://www.npmjs.com/signup)
+- For scoped packages like `@deloraprotocol/widget`: create the org at [npmjs.com/org/create](https://www.npmjs.com/org/create) (or change the scope in `package.json` to your username)
+
+### First-time publish
+
+1. **Build the package:**
+   ```bash
+   npm run build
+   ```
+
+2. **Log in to npm:**
+   ```bash
+   npm login
+   ```
+   Enter your username, password, and email. If 2FA is enabled, enter the one-time code.
+
+3. **Publish (scoped packages require `--access public`):**
+   ```bash
+   npm publish --access public
+   ```
+
+### Publishing updates
+
+1. Bump the version:
+   ```bash
+   npm version patch   # 1.0.0 → 1.0.1 (bug fixes)
+   npm version minor   # 1.0.0 → 1.1.0 (new features)
+   npm version major   # 1.0.0 → 2.0.0 (breaking changes)
+   ```
+
+2. Build and publish:
+   ```bash
+   npm run build
+   npm publish --access public
+   ```
+
+### Org members
+
+- Add members under **Organization → Members** on npmjs.com
+- Any member with publish rights can publish and update the package
+- Only one person needs to create the org; others can be invited
+
+## Running the widget locally
+
+### One-time setup
+
+```bash
+npm install
+npm run build
+cd playground && npm install
+```
+
+### Development
+
+```bash
+npm run playground:dev
+```
+
+This runs the library watcher and the playground dev server together. The playground uses the built output from `dist/`.
+
+**When errors occur or the UI shows stale/broken code:** run `npm run build` separately to rebuild the library, then restart or refresh the playground. The playground does not auto-rebuild the library.
+
+### Alternative: build then run
+
+```bash
+npm run build
+cd playground && npm run dev
+```
+
+Build the library first, then run only the playground dev server.

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { HTMLAttributes } from 'react';
+
+declare interface INativeCurrency {
+    name: string;
+    symbol: string;
+    decimals: number;
+}
+
+export declare function MyWidget(props: MyWidgetProps): JSX.Element;
+
+export declare interface MyWidgetProps extends HTMLAttributes<HTMLDivElement> {
+    theme?: MyWidgetTheme;
+    vars?: Partial<MyWidgetVars>;
+}
+
+export declare type MyWidgetTheme = "light" | "dark";
+
+export declare interface MyWidgetVars {
+    bg: string;
+    fg: string;
+    accent: string;
+    border: string;
+    muted: string;
+    surface?: string;
+    surfaceAlt?: string;
+    surfaceHover?: string;
+    textSubtle?: string;
+    accentHover?: string;
+    success?: string;
+    danger?: string;
+    overlay?: string;
+    shadow?: string;
+    radius: string;
+    fontFamily: string;
+    fontSize: string;
+    lineHeight?: string;
+    letterSpacing?: string;
+}
+
+export declare interface Network {
+    id: number;
+    name: string;
+    rpcUrls: string[];
+    logoURI?: string;
+    idHex?: string;
+    chainType: string;
+    explorerUrl?: string;
+    key: string;
+    nativeCurrency: INativeCurrency;
+}
+
+export declare interface Token {
+    symbol: string;
+    imageUrl: string;
+    contractAddress: string;
+    chainId: number;
+    decimals: number;
+    priceUSD?: string;
+    name?: string;
+}
+
+export declare function TradeWidget(props: TradeWidgetProps): JSX.Element;
+
+export declare interface TradeWidgetConfig {
+    dataBaseUrl: string;
+    apiBase?: string;
+    /** Base URL for resolving relative image paths (e.g. /img/...). Defaults to dataBaseUrl or origin. */
+    assetBaseUrl?: string;
+    /** Whether a wallet is connected. When false, the main button shows "Connect Wallet" (Angular: isWalletConnected). */
+    isWalletConnected?: boolean;
+    /** Called when user clicks "Connect Wallet". The host should open its connect-wallet UI. */
+    onConnectWallet?: () => void;
+}
+
+export declare interface TradeWidgetProps extends MyWidgetProps {
+    config: TradeWidgetConfig;
+}
+
+export { }