@qratilabs/qrati-connect 2.23.0-beta.10 → 2.23.0-beta.12

package/README.md

@@ -4,15 +4,46 @@ Qrati Connect is a React component library designed to seamlessly integrate Qrat
 
 # Features
 
-- **Interactive Media Gallery :** Integrate Qrati's powerful interactive media gallery into your own site without a hassle.
-- **Media Upload :** Users can directly upload content from your host site.
-- **Reaction :** Engage your users with a completely customizable set of emojis.
-- **Curation :** Want to host a photo contest? Our curation feature can be a one stop solution for that.
-- **Leaderboard :** Gamify your contest with a precise and fun leaderboard.
+# Qrati Connect — Embeddable Media & Engagement SDK
 
-**Qrati Connect** is a compact, production-grade SDK for embedding photo galleries, uploads, curation, and engagement into any website. Built with strict TypeScript, Preact compatibility, and careful bundling to deliver a fast, accessible, and themeable integration.
+**Qrati Connect** is a compact, production-grade SDK for embedding photo galleries, media uploads, curation, and engagement into any website. It is built with [Preact](https://preactjs.com/), strict TypeScript, and Shadow-DOM style isolation, then distributed as a Web Component, React wrapper, and zero-code embed script.
 
-Install `qrati-connect` using npm, yarn, pnpm or bun:
+---
+
+## Why Qrati Connect?
+
+- **Framework-agnostic** — works in React, Vue, Angular, WordPress, or plain HTML.
+- **Style isolation** — Shadow DOM keeps SDK styles separate from the host page.
+- **Small initial payload** — Preact core plus strategic lazy-loading for heavy features (upload, HEIC conversion, maps).
+- **Themeable** — organization colors, fonts, radius, and shadows are fetched from the Qrati API and applied via CSS custom properties.
+- **TypeScript-first** — full typings for the public API.
+
+---
+
+## Highlights
+
+- Interactive media gallery with lightbox, blurhash placeholders, infinite scroll, and facial search.
+- Smart uploads: compression, chunked progress, video trimming, and HEIC → JPEG conversion on demand.
+- Reactions, curation workflow, leaderboards, and points-based engagement.
+- Public events page with folder navigation and optional map view (Google Maps, Mapbox, OpenStreetMap).
+
+---
+
+## Distribution Formats
+
+| Format | Output | Best for |
+|--------|--------|----------|
+| **React wrapper** | `dist/react/index.mjs` / `index.cjs` | React / Next.js apps |
+| **Web Component** | `dist/element/web.es.js` | Any framework or vanilla JS |
+| **Embed loader** | `dist/embed/embed.js` | Zero-code `<script>` integration |
+
+The React wrapper and embed loader dynamically load the element build at runtime, so the same `web.es.js` bundle is always used.
+
+---
+
+## Quick Install & Integration
+
+### React (client component)
 
 ```bash
 npm install @qratilabs/qrati-connect
@@ -24,11 +55,10 @@ pnpm add @qratilabs/qrati-connect
 bun install @qratilabs/qrati-connect
 ```
 
-Sample react page -
+```tsx
+'use client';
 
-```javascript
-import QratiConnect from '@qratilabs/qrati-connect/react';
-import '@qratilabs/qrati-connect/react/styles.css';
+import { QratiConnect } from '@qratilabs/qrati-connect';
 
 const Page = () => {
     return (
@@ -41,68 +71,42 @@ const Page = () => {
 export default Page;
 ```
 
-**Note**: Add 'use client' directive if you are using any React frameworks which supports Server Side Rendering (SSR) like Next.js.
-
-# Available props
-
-- **router :** Custom router configuration for internal navigation ('memory or 'hash').
-- **organizationId :** Unique identifier for your organization inside Qrati.
-- **fontClassName :** Classes to control custom font for the component.
-- **textClassName :** Classes to apply any additional styling to texts inside the component.
-- **emptyStateImage :** Link or path to image which will be shown for any empty state in the component.
-- **curateLabel :** Label to show in place of 'Curate' in header for contest type events.
-- **leaderboardLabel :** Label to show in place of 'Leaders' in header for contest type events.
-- **uid :** User id for your application user (applicable for custom auth only).
-- **fname :** First name for your application user (applicable for custom auth only).
-- **lname :** Last name for your application user (applicable for custom auth only).
-- **loginUrl :** The page url inside your web app where we should redirect when authentication is required for user intended action (applicable for custom auth only).
-
-# Qrati Connect Element (Web Component)
-
-Qrati Connect is also available as a Web Component (Custom Element) that you can use directly in your HTML without React. This is useful for non-React applications or when you want to embed Qrati Connect in static HTML pages.
-
-## Installation via CDN (jsDelivr)
-
-Add the following script and stylesheet tags to your HTML:
+### Web Component (framework-agnostic)
 
 ```html
-<!-- Import the Web Component -->
-<script type="module" src="https://cdn.jsdelivr.net/npm/@qratilabs/qrati-connect/element/web.es.js"></script>
-<!-- Import the styles -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@qratilabs/qrati-connect/element/styles.css" />
-```
+<script type="module" src="https://cdn.jsdelivr.net/npm/@qratilabs/qrati-connect@2/element/web.es.js"></script>
 
-### Embed (Single Script — No Code)
+<qrati-connect organization-id="your-org-id" router="hash"></qrati-connect>
+```
 
-The simplest integration: one `async` tag, config in `data-*` attributes. Mounts
-where the tag sits, or into the element matched by `data-target`.
+### Embed script (zero-code)
 
 ```html
 <script async
-        src="https://cdn.jsdelivr.net/npm/@qratilabs/qrati-connect/embed/embed.js"
+        src="https://cdn.jsdelivr.net/npm/@qratilabs/qrati-connect@2/embed/embed.js"
         data-organization-id="your-org-id"
         data-router="hash"></script>
 ```
 
-Supported `data-*` attributes: `data-organization-id` (required), `data-router`,
-`data-uid`, `data-fname`, `data-lname`, `data-theme`, and `data-target` (CSS
-selector for the mount container).
+The embed script inserts a `<qrati-connect>` element next to the script tag (or into the element matched by `data-target`) and lazy-loads the element build.
 
 ---
 
 Once imported, you can use the custom element tag `<qrati-connect>` in your HTML:
 
-| Prop / Attribute    | Type                     | Default    | Description                            |
-| ------------------- | ------------------------ | ---------- | -------------------------------------- |
-| `organizationId` \* | `string`                 | —          | Your Qrati organization ID (required)  |
-| `router`            | `'memory' \| 'hash'`     | `'memory'` | Routing strategy for navigation        |
-| `uid`               | `string`                 | —          | Pre-authenticated user ID              |
-| `fname`             | `string`                 | —          | Pre-authenticated user first name      |
-| `lname`             | `string`                 | —          | Pre-authenticated user last name       |
-| `theme`             | `'light' \| 'dark'`      | `'light'`  | Color scheme                           |
-| `onError`           | `(error: Error) => void` | —          | Error callback for handling SDK errors |
+| Prop / Attribute | Type | Default | Description |
+|------------------|------|---------|-------------|
+| `organizationId` * | `string` | — | Qrati organization ID |
+| `router` | `'memory' \| 'hash'` | `'memory'` | Routing strategy |
+| `uid` | `string` | — | Pre-authenticated user ID |
+| `fname` | `string` | — | Pre-authenticated first name |
+| `lname` | `string` | — | Pre-authenticated last name |
+| `theme` | `'light' \| 'dark'` | `'light'` | Color scheme |
+| `onError` | `(error: Error) => void` | — | SDK error callback |
+
+\* Required.
 
-Note: When using the Web Component version, props are passed as HTML attributes with kebab-case naming (e.g., `organization-id` instead of `organizationId`).
+Custom auth requires `uid` and `fname`; `lname` is optional.
 
 3. Tailwindv3 -> Tailwindv4
 
@@ -112,45 +116,66 @@ text-secondary -> text-muted-foreground
 bg-brand, text-brand -> bg-primary, text-primary
 qc-text-lg, qc-bg-red-500 -> qc:text-lg, qc:bg-red-500
 
-4. IconifyReact -> Iconify Tailwindv4
+| Callback / Event | Payload | Description |
+|------------------|---------|-------------|
+| `onError` | `Error` | Called when an SDK error is caught |
+| `qrati-error` (custom event) | `{ error: Error }` | Dispatched on `window` and the custom element |
+
+React wrapper users should use the `onError` prop. Vanilla Web Component users can listen for `qrati-error`.
 
 ---
 
 ## Performance & Bundling
 
-We optimize for small initial loads and lazy-load heavy features:
+Sizes are approximate and depend on the build output:
 
-- Initial: ~139 KB gzipped (core UI + essentials)
-- Upload feature: +~73 KB gzipped (lazy)
-- HEIC conversion (heic2any): large dependency loaded only on-demand (~345 KB gzipped)
+- React wrapper: ~1–2 KB gzipped (loads element build at runtime).
+- Initial element bundle: ~139 KB gzipped.
+- Upload feature: loaded on demand.
+- HEIC conversion (`heic2any`): loaded only when a `.heic` file is selected.
+- Maps and heavy UI libraries are split into lazy chunks.
 
 ---
 
 ## Development
 
-Common commands for contributors:
+This repository uses **pnpm** and **Node.js 24.x**.
 
 ```bash
-pnpm build          # Build all distribution targets (element → umd → react → embed)
-pnpm test:unit      # Run Vitest unit tests in watch mode
-pnpm test:unit:run  # Run Vitest unit tests once
-pnpm test:production # Build and run Playwright production regression tests
-pnpm type-check     # TypeScript type checking (no emit)
+pnpm install        # install dependencies
+pnpm storybook      # start Storybook on http://localhost:6006
+pnpm type-check     # TypeScript check (no emit)
 pnpm lint           # ESLint
+pnpm format         # Prettier
+pnpm build          # build all distribution targets
+pnpm test:unit      # Vitest unit tests (watch)
+pnpm test:unit:run  # Vitest unit tests (once)
+pnpm test:all       # unit tests + Playwright production regression
 ```
 
-## Support
+See [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) for the full setup guide and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for design details.
 
-- Report bugs or request features via GitHub Issues: https://github.com/qrati-labs/qrati-connect-ts/issues
-- See `docs/` for architecture, component, and hook references
-- For commercial support: support@qrati.com
+---
+
+## Documentation
+
+- [`docs/INDEX.md`](docs/INDEX.md) — documentation map
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — architecture, build system, routing, styling, i18n
+- [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) — environment setup, workflow, testing, Storybook
+- [`docs/API.md`](docs/API.md) — backend API communication
+- [`docs/REFERENCE.md`](docs/REFERENCE.md) — components, hooks, pages, utilities, router API
+- [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) — release process and CDN
+- [`docs/FAQ.md`](docs/FAQ.md) — common questions
 
 ---
 
-## License
+## Support
 
-Proprietary © Qrati Labs — https://qrati.com. All rights reserved.
+- GitHub Issues: https://github.com/qrati-labs/qrati-connect-ts/issues
+- Email: support@qrati.com
 
 ---
 
-Visit `docs/` for full API and integration patterns.
+## License
+
+Proprietary © Qrati Labs — https://qrati.com. All rights reserved.