@qratilabs/qrati-connect 2.23.9 → 2.24.0

package/README.md

@@ -11,32 +11,46 @@
 
 ---
 
-# Qrati Connect — Embeddable Media & Engagement SDK 🚀
+# 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.
 
 ---
 
-## Why Qrati Connect? 💡
+## Why Qrati Connect?
 
-- **Plug & Play**: Use the Web Component anywhere, or import the React wrapper for rapid integration.
-- **Strict TypeScript**: Full typings for safer integration and better DX.
-- **Performance-first**: Small initial bundle, strategic lazy-loading for heavy features (HEIC conversion, upload tooling).
-- **Accessible & Themeable**: ARIA-friendly; visual theme is centrally configured via the Qrati Organization Settings page and applied to the component (exposed via CSS variables and className hooks).
+- **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 — What’s inside ✨
+## Highlights
 
-- Interactive media gallery with lightbox, blurhash placeholders and infinite scroll
-- Smart uploads: compression, chunked progress, HEIC → JPEG conversion (on-demand)
-- Reactions, curation workflow, and leaderboards for engagement
+- 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
 
-### Install
+### React (client component)
 
 ```bash
 pnpm add @qratilabs/qrati-connect
@@ -44,10 +58,9 @@ pnpm add @qratilabs/qrati-connect
 npm install @qratilabs/qrati-connect
 ```
 
-### React (Client Component)
-
 ```tsx
 'use client';
+
 import { QratiConnect } from '@qratilabs/qrati-connect';
 
 export default function Page() {
@@ -55,90 +68,107 @@ export default function Page() {
 }
 ```
 
-### Web Component (Framework Agnostic)
+### Web Component (framework-agnostic)
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@qratilabs/qrati-connect/element/web.es.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@qratilabs/qrati-connect@2/element/web.es.js"></script>
+
 <qrati-connect organization-id="your-org-id" router="hash"></qrati-connect>
 ```
 
-### Embed (Single Script — No Code)
-
-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.
 
 ---
 
 ## Props & Attributes
 
-| 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
+\* Required.
+
+Custom auth requires `uid` and `fname`; `lname` is optional.
 
 ---
 
 ## Events & Callbacks
 
-| Callback  | Payload | Description                           |
-| --------- | ------- | ------------------------------------- |
-| `onError` | `Error` | Fires when an error occurs in the SDK |
+| 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.