Publish

- jazz-example-pets@0.0.19
 - jazz-example-todo@0.0.43
 - jazz-example-twit@0.0.6
 - cojson@0.4.6
 - cojson-simple-sync@0.4.6
 - cojson-storage-indexeddb@0.4.6
 - cojson-storage-sqlite@0.4.6
 - jazz-autosub@0.4.6
 - jazz-browser@0.4.6
 - jazz-browser-auth-local@0.4.6
 - jazz-browser-media-images@0.4.7
 - jazz-react@0.4.6
 - jazz-react-auth-local@0.4.6

.github/workflows/build-and-deploy.yaml

@@ -7,8 +7,11 @@ on:
     branches: [ "main" ]
 
 jobs:
-  build-and-deploy:
+  build:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        example: ["todo", "pets", "twit"]
 
     steps:
     - uses: actions/checkout@v3
@@ -17,40 +20,50 @@ jobs:
 
     - uses: actions/setup-node@v3
       with:
-        node-version: 18
+        node-version: 16
         cache: 'yarn'
         cache-dependency-path: yarn.lock
-    - name: Nuke Workspace
-      run: |
-        rm package.json yarn.lock;
-    - name: Yarn Build
-      run: |
-        yarn install --frozen-lockfile;
-        yarn build;
-      working-directory: ./examples/todo
 
-    - uses: satackey/action-docker-layer-caching@v0.0.11
-      continue-on-error: true
-      with:
-        key: docker-layer-caching-${{ github.workflow }}-{hash}
-        restore-keys: |
-          docker-layer-caching-${{ github.workflow }}-
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v2
 
     - name: Login to GitHub Container Registry
-      uses: docker/login-action@v1
+      uses: docker/login-action@v2
       with:
         registry: ghcr.io
         username: gardencmp
         password: ${{ secrets.GITHUB_TOKEN }}
 
-    - name: Docker Build & Push
+    - name: Nuke Workspace
       run: |
-        export DOCKER_TAG=ghcr.io/gardencmp/jazz-example-todo:${{github.head_ref || github.ref_name}}-${{github.sha}}-$(date +%s) ;
-        docker build . --file Dockerfile --tag $DOCKER_TAG;
-        docker push $DOCKER_TAG;
-        echo "DOCKER_TAG=$DOCKER_TAG" >> $GITHUB_ENV
-      working-directory: ./examples/todo
+        rm package.json yarn.lock;
 
+    - name: Yarn Build
+      run: |
+        yarn install --frozen-lockfile;
+        yarn build;
+      working-directory: ./examples/${{ matrix.example }}
+
+    - name: Docker Build & Push
+      uses: docker/build-push-action@v4
+      with:
+        context: ./examples/${{ matrix.example }}
+        push: true
+        tags: ghcr.io/gardencmp/${{github.event.repository.name}}-example-${{ matrix.example }}:${{github.head_ref || github.ref_name}}-${{github.sha}}-${{github.run_number}}-${{github.run_attempt}}
+        cache-from: type=gha
+        cache-to: type=gha,mode=max
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    strategy:
+      matrix:
+        example: ["todo", "pets", "twit"]
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        submodules: true
     - uses: gacts/install-nomad@v1
     - name: Tailscale
       uses: tailscale/github-action@v1
@@ -69,9 +82,9 @@ jobs:
 
         export DOCKER_USER=gardencmp;
         export DOCKER_PASSWORD=${{ secrets.DOCKER_PULL_PAT }};
-        export DOCKER_TAG=${{ env.DOCKER_TAG }};
+        export DOCKER_TAG=ghcr.io/gardencmp/${{github.event.repository.name}}-example-${{ matrix.example }}:${{github.head_ref || github.ref_name}}-${{github.sha}}-${{github.run_number}}-${{github.run_attempt}};
 
         envsubst '${DOCKER_USER} ${DOCKER_PASSWORD} ${DOCKER_TAG} ${BRANCH_SUFFIX} ${BRANCH_SUBDOMAIN}' < job-template.nomad > job-instance.nomad;
         cat job-instance.nomad;
         NOMAD_ADDR='http://control1v2-london:4646' nomad job run job-instance.nomad;
-      working-directory: ./examples/todo
+      working-directory: ./examples/${{ matrix.example }}

.gitignore

@@ -1,3 +1,4 @@
 node_modules
 yarn-error.log
-lerna-debug.log
+lerna-debug.log
+docsTmp

README.md

@@ -1,488 +1,116 @@
 # Jazz - instant sync
 
-Homepage: [jazz.tools](https://jazz.tools) — [Discord](https://discord.gg/utDMjHYg42)
+<sub>Homepage: [jazz.tools](https://jazz.tools) &mdash; Docs: [DOCS.md](./DOCS.md) &mdash; Community & support: [Discord](https://discord.gg/utDMjHYg42) &mdash; Updates: [Twitter](https://twitter.com/jazz_tools) & [Email](https://gcmp.io/news)</sub>
 
-Jazz is an open-source toolkit for *secure telepathic data.*
+ **Jazz is an open-source toolkit for building apps with *secure sync.***
 
-- Ship faster & simplify your frontend and backend
-- Get cross-device sync, real-time collaboration & offline support for free
+Quickly build and ship apps with:
 
-[Jazz Global Mesh](https://jazz.tools/mesh) is serverless sync & storage for Jazz apps. (currently free!)
+- **Cross-device sync**
+- **Collaborative features** (incl. real-time multiplayer)
+- **Instantly reacting UIs**
+- Local-first storage & offline support
+- File upload and real-time media streaming
 
+# What is *secure sync*?
 
+**Sync** means that, *instead of making API requests*, you:
 
-## What is Secure Telepathic Data?
+- **Read and write data as if it was local** &mdash; from anywhere in your app.
+- **Always have data synced to wherever it's needed, instantly:** to other devices of the same user, to other users, to your backend, to your local machine for debugging, etc.
 
-**Telepathic** means:
+**Secure** means that, *instead of relying on your API or DB for access control*, you:
 
-- **Read and write data as if it was local,** from anywhere in your app.
-- **Always have that data synced, instantly.** Across devices of the same user &mdash; or to other users (coming soon: to your backend, workers, etc.)
+- **Set fine-grained, role-based permissions in `Group`s** that are **synced along with your data**.
+- **Permissions *verifiably enforced* everywhere,** using encryption & signatures under the hood.
+- **Change roles dynamically** for evolving teams, expiring invite links and more.
 
-**Secure** means:
+# What's special about Jazz?
 
-- **Fine-grained, role-based permissions are *baked into* your data.**
-- **Permissions are enforced everywhere, locally.** (using cryptography instead of through an API)
-- Roles can be changed dynamically, supporting changing teams, invite links and more.
+Compared to other libraries and frameworks for local-first, sync-based or real-time apps, these are some of the things that make Jazz unique:
 
-## How to build an app with Jazz?
+- **Jazz is a *batteries-included,* vertically integrated toolkit,** offering everything you need to build an app, including auth, permissions, data model, sync, conflict resolution, blob storage, file uploads, real-time media streaming and more.
+- **Jazz has a *small API surface* of only a few abstractions to learn,** which combine in powerful ways to implement a broad set of features.
+- **Jazz *granularly* loads and caches *only the data that is needed*,** combining *local-first* instant UI reactivity and offline support with the on-demand data efficiency of conventional APIs
+- **Jazz supports end-to-end encryption, but doesn't require it,** allowing you to either manage your user's secret keys for them (based on existing auth flows) or letting your users
+- **Jazz is based on CoJSON, a soon-to-be *open standard,*** which means that there will be a whole ecosystem of compatible libraries and frameworks in a variety of environments &mdash; and it will be easy to achieve (secure) interop between Jazz/CoJSON-based apps and services.
 
-### Building a new app, completely with Jazz
+# Jazz Global Mesh
 
-It's still a bit early, but these are the rough steps:
+Jazz is open source and you can run your own sync & storage server, but to really provide you with everything you need, we're also running
+**[Jazz Global Mesh](https://jazz.tools/mesh)**, a globally distributed mesh of servers optimized for:
 
-1. Define your data model with [CoJSON Values](#cojson).
-2. Implement permission logic using [CoJSON Groups](#group).
-3. Hook up a user interface with [jazz-react](#jazz-react).
+ - **Ultra-low-latency sync** (with geo-aware edge caching and optimal routing)
+ - **Low-cost, reliable storage**
 
-The best example is currently the [Todo List app](#example-app-todo-list).
 
-### Gradually adding Jazz to an existing app
+**Jazz Global Mesh is free for small volumes of data** and it's the **default syncing peer,** so you can  **start building multi-user Jazz apps with persistent data in minutes,** using only frontend code!
 
-Coming soon: Jazz will support gradual adoption by integrating with your existing UI, auth and database.
+# Getting started
 
-## Example App: Todo List
+## Example App Walkthrough
 
-The best example of Jazz is currently the Todo List app.
+**For now the best tutorial is the walkthrough of the [Todo List Example App](#todo-list).**
 
-- Live version: https://example-todo.jazz.tools
-- Source code: [`./examples/todo`](./examples/todo). See the README there for a walk-through and running instructions.
+## General Scenarios
 
-# API Reference
+### Building a new, entirely sync-based React app
 
-Note: Since it's early days, this is the only source of documentation so far.
+1. Define your data model with [cojson Collaborative Values (CoValues)](./DOCS.md#covalue).
+2. Implement permission logic using [cojson Groups](./DOCS.md#group).
+3. Build a user interface with [jazz-react](./DOCS.md#jazz-react) and [auto-sub](./DOCS.md#useautosubid).
 
-If you want to build something with Jazz, [join the Jazz Discord](https://discord.gg/utDMjHYg42) for encouragement and help!
+### Gradually adding sync to an existing React app
 
-## Overview: Main Packages
+Gradually migrate app features to use sync:
 
-**`cojson`**
+1. Define data model for small aspect of your app with [cojson Collaborative Values (CoValues)](./DOCS.md#covalue).
+    - Schema adapters/importers for Prisma/Drizzle/PostgreSQL introspection coming soon.
+2. Map existing permission logic with [cojson Groups](./DOCS.md#group) & integrate existing auth.
+    - Auth integrations coming soon.
+3. Replace some of the React state and API requests in your UI with [jazz-react](./DOCS.md#jazz-react) and [auto-sub](./DOCS.md#useautosubid).
 
-A library implementing abstractions and protocols for "Collaborative JSON". This will soon be standardized and forms the basis of secure telepathic data.
+# Example Apps
 
-**`jazz-react`**
+## Todo List
 
-Provides you with everything you need to build react apps around CoJSON, including reactive hooks for telepathic data, local IndexedDB persistence, support for different auth providers and helpers for simple invite links for CoJSON groups.
+**A simple collaborative todo list app.**
 
-### Supporting packages
-<small>
+Live version: https://example-todo.jazz.tools
 
-**`cojson-simple-sync`**
+Source code & walkthrough: [`./examples/todo`](./examples/todo)
 
-A generic CoJSON sync server you can run locally if you don't want to use Jazz Global Mesh (the default sync backend, at `wss://sync.jazz.tools`)
+Demonstrates:
+  - Defining a data model with `CoMap`s and `CoList`s
+  - Creating data and setting permissions with `Group`s
+  - Fetching, rendering & editing data from nested `CoValue`s with reactive synced queries
 
-**`jazz-browser`**
 
-framework-agnostic primitives that allow you to use CoJSON in the browser. Used to implement `jazz-react`, will be used to implement bindings for other frameworks in the future.
+## Rate-My-Pet
 
-**`jazz-react-auth-local`** (and `jazz-browser-auth-local`): A simple auth provider that stores cryptographic keys on user devices using WebAuthentication/Passkeys. Lets you build Jazz apps completely without a backend, with end-to-end encryption by default.
+**A simple social polling app.**
 
-**`jazz-storage-indexeddb`**
+Live version: https://example-pets.jazz.tools
 
-Provides local, offline-capable persistence. Included and enabled in `jazz-react` by default.
-</small>
+Source code (walkthrough coming soon): [`./examples/pets`](./examples/pets)
 
-## `CoJSON`
+Demonstrates:
+  - Implementing per-account data streams (reactions) with `CoStream`s
+  - Implementing image upload and progressive image streaming using helpers from `jazz-react-media-images` (on top of CoJSON's `BinaryCoStreams` & `ImageDefinition` convention)
 
-CoJSON is the core implementation of secure telepathic data. It provides abstractions for Collaborative JSON values ("`CoValues`"), groups for permission management and a protocol for syncing between nodes. Our goal is to standardise CoJSON soon and port it to other languages and platforms.
 
----
+# Documentation & API Reference
 
-### `LocalNode`
+For now, docs are hosted in a single well-structured markdown file: [`./DOCS.md`](./DOCS.md).
 
-A `LocalNode` represents a local view of a set of loaded `CoValue`s, from the perspective of a particular account (or primitive cryptographic agent).
+- [Package Overview](./DOCS.md#overview)
+- [`jazz-react` API](./DOCS.md#jazz-react)
+- [`cojson` API](./DOCS.md#cojson)
+- [`jazz-browser-media-images` API](./DOCS.md#jazz-browser-media-images)
 
-A `LocalNode` can have peers that it syncs to, for example some form of local persistence, or a sync server, such as `sync.jazz.tools` (Jazz Global Mesh).
 
-You typically get hold of a `LocalNode` using `jazz-react`'s `useJazz()`:
+In the future we'll build a dedicated docs page on the Jazz homepage.
 
-```typescript
-const { localNode } = useJazz();
-```
+----
 
-#### `LocalNode.load(id)`
-```typescript
-load<T extends ContentType>(id: CoID<T>): Promise<T>
-```
-
-Loads a CoValue's content, syncing from peers as necessary and resolving the returned promise once a first version has been loaded. See `ContentType.subscribe()` and `useTelepathicData` for listening to subsequent updates to the CoValue.
-
-#### `LocalNode.loadProfile(id)`
-```typescript
-loadProfile(accountID: AccountID): Promise<Profile>
-```
-
-Loads a profile associated with an account. `Profile` is at least a `CoMap<{string: name}>`, but might contain other, app-specific properties.
-
-#### `LocalNode.acceptInvite(valueOrGroup, inviteSecret)`
-```typescript
-acceptInvite<T extends ContentType>(
-    valueOrGroup: CoID<T>,
-    inviteSecret: InviteSecret
-): Promise<void>
-```
-
-Accepts an invite for a group, or infers the group if given the `CoID` of a value owned by that group. Resolves upon successful joining of that group, at which point you should be able to `LocalNode.load` the value.
-
-Invites can be created with `Group.createInvite(role)`.
-
-#### `LocalNode.createGroup()`
-```typescript
-createGroup(): Group
-```
-
-Creates a new group (with the current account as the group's first admin).
-
----
-
-### `Group`
-
-A CoJSON group manages permissions of its members. A `Group` object exposes those capabilities and allows you to create new CoValues owned by that group.
-
-(Internally, a `Group` is also just a `CoMap`, mapping member accounts to roles and containing some state management for making cryptographic keys available to current members)
-
-#### `Group.id`
-
-Returns the `CoID` of the `Group`.
-
-#### `Group.roleOf(accountID)`
-
-```typescript
-roleOf(accountID: AccountID): "reader" | "writer" | "admin" | undefined
-```
-
-Returns the current role of a given account.
-
-#### `Group.myRole()`
-
-```typescript
-myRole(accountID: AccountID): "reader" | "writer" | "admin" | undefined
-```
-
-Returns the role of the current account in the group.
-
-#### `Group.addMember(accountID, role)`
-
-```typescript
-addMember(
-  accountID: AccountID,
-  role:  "reader" | "writer" | "admin"
-)
-```
-
-Directly grants a new member a role in the group. The current account must be an admin to be able to do so. Throws otherwise.
-
-#### `Group.createInvite(role)`
-
-```typescript
-createInvite(role: "reader" | "writer" | "admin"): InviteSecret
-```
-
-Creates an invite for new members to indirectly join the group, allowing them to grant themselves the specified role with the InviteSecret (a string starting with "inviteSecret_") - use `LocalNode.acceptInvite()` for this purpose.
-
-#### `Group.removeMember(accountID)`
-
-```typescript
-removeMember(accountID: AccountID)
-```
-
-Strips the specified member of all roles (preventing future writes) and rotates the read encryption key for that group (preventing reads of new content, including in covalues owned by this group)
-
-#### `Group.createMap(meta?)`
-```typescript
-createMap<M extends CoMap<{ [key: string]: JsonValue }, JsonObject | null>>(
-  meta?: M["meta"]
-): M
-```
-
-Creates a new `CoMap` within this group, with the specified specialized `CoMap` type `M` and optional static metadata.
-
-#### `Group.createList(meta?)`
-```typescript
-createList<L extends CoList<JsonValue, JsonObject | null>>(
-  meta?: L["meta"]
-): L
-```
-
-Creates a new `CoList` within this group, with the specified specialized `CoList` type `L` and optional static metadata.
-
-#### `Group.createStream(meta?)` (coming soon)
-#### `Group.createStatic(meta)` (coming soon)
-
----
-### `CoValue` ContentType: `CoMap`
-
-```typescript
-class CoMap<
-    M extends { [key: string]: JsonValue; },
-    Meta extends JsonObject | null = null,
->
-```
-
-#### `CoMap.id`
-
-```typescript
-id: CoID<CoMap<M, Meta>>
-```
-
-Returns the CoMap's (precisely typed) `CoID`
-
-#### `CoMap.meta`
-
-```typescript
-meta: Meta
-```
-
-Returns the CoMap's (precisely typed) static metadata
-
-#### `CoMap.keys()`
-
-```typescript
-keys(): (keyof M & string)[]
-```
-
-#### `CoMap.get(key)`
-
-```typescript
-get<K extends keyof M>(key: K): M[K] | undefined
-```
-
-Returns the current value for the given key.
-
-#### `CoMap.whoEdited(key)`
-
-```typescript
-whoEdited<K extends keyof M>(key: K): AccountID | undefined
-```
-
-Returns the accountID of the last account to modify the value for the given key.
-
-#### `CoMap.toJSON()`
-
-```typescript
-toJSON(): JsonObject
-```
-
-Returns a JSON representation of the state of the CoMap.
-
-#### `CoMap.subscribe(listener)`
-
-```typescript
-subscribe(
-  listener: (coMap: CoMap<M, Meta>) => void
-): () => void
-```
-Lets you subscribe to future updates to this CoMap (whether made locally or by other users). Takes a listener function that will be called with the current state for each update. Returns an unsubscribe function.
-
-Used internally by `useTelepathicData()` for reactive updates on changes to a `CoMap`.
-
-#### `CoMap.edit(editable => {...})`
-
-```typescript
-edit(changer: (editable: WriteableCoMap<M, Meta>) => void): CoMap<M, Meta>
-```
-
-Lets you apply edits to a `CoMap`, inside the changer callback, which receives a `WriteableCoMap`. A `WritableCoMap` has all the same methods as a `CoMap`, but all edits made to it with `set` or `delete` are reflected in it immediately - so it behaves mutably, whereas a `CoMap` is always immutable (you need to use `subscribe` to receive new versions of it).
-
-```typescript
-export class WriteableCoMap<
-    M extends { [key: string]: JsonValue; },
-    Meta extends JsonObject | null = null,
-> extends CoMap<M, Meta>
-```
-
-#### `WritableCoMap.set(key, value)`
-
-```typescript
-set<K extends keyof M>(
-  key: K,
-  value: M[K],
-  privacy: "private" | "trusting" = "private"
-): void
-```
-
-Sets a new value for the given key.
-
-If `privacy` is `"private"` **(default)**, both `key` and `value` are encrypted in the transaction, only readable by other members of the group this `CoMap` belongs to. Not even sync servers can see the content in plaintext.
-
-If `privacy` is `"trusting"`, both `key` and `value` are stored in plaintext in the transaction, visible to everyone who gets a hold of it, including sync servers.
-
-#### `WritableCoMap.delete(key)`
-
-```typescript
-delete<K extends keyof M>(
-  key: K,
-  privacy: "private" | "trusting" = "private"
-): void
-```
-
-Deletes the value for the given key (setting it to undefined).
-
-If `privacy` is `"private"` **(default)**, `key` is encrypted in the transaction, only readable by other members of the group this `CoMap` belongs to. Not even sync servers can see the content in plaintext.
-
-If `privacy` is `"trusting"`, `key` is stored in plaintext in the transaction, visible to everyone who gets a hold of it, including sync servers.
-
----
-### `CoValue` ContentType: `CoList`
-
-```typescript
-class CoList<
-    T extends JsonValue,
-    Meta extends JsonObject | null = null
->
-```
-
-#### `CoList.id`
-
-```typescript
-id: CoID<CoList<T, Meta>>
-```
-
-Returns the CoList's (precisely typed) `CoID`
-
-#### `CoList.meta`
-
-```typescript
-meta: Meta
-```
-
-Returns the CoList's (precisely typed) static metadata
-
-### `CoList.asArray()`
-
-```typescript
-asArray(): T[]
-```
-
-Returns the current items in the CoList as an array.
-
-### `CoList.toJSON()`
-
-```typescript
-toJSON(): T[]
-```
-
-Returns the current items in the CoList as an array. (alias of asArray)
-
-#### `CoList.whoInserted(idx)`
-
-```typescript
-whoInserted(idx: number): AccountID | undefined
-```
-
-Returns the accountID of the account that inserted value at the given index.
-
-#### `CoList.subscribe(listener)`
-
-```typescript
-subscribe(
-  listener: (coMap: CoList<T, Meta>) => void
-): () => void
-```
-Lets you subscribe to future updates to this CoList (whether made locally or by other users). Takes a listener function that will be called with the current state for each update. Returns an unsubscribe function.
-
-Used internally by `useTelepathicData()` for reactive updates on changes to a `CoList`.
-
-#### `CoList.edit(editable => {...})`
-
-```typescript
-edit(changer: (editable: WriteableCoList<T, Meta>) => void): CoList<T, Meta>
-```
-
-Lets you apply edits to a `CoList`, inside the changer callback, which receives a `WriteableCoList`. A `WritableCoList` has all the same methods as a `CoList`, but all edits made to it with `append`, `push`, `prepend` or `delete` are reflected in it immediately - so it behaves mutably, whereas a `CoList` is always immutable (you need to use `subscribe` to receive new versions of it).
-
-```typescript
-export class WriteableCoList<
-    T extends JsonValue,
-    Meta extends JsonObject | null = null,
-> extends CoList<T, Meta>
-```
-
-#### `WritableCoList.append(after, value)`
-
-```typescript
-append(
-  after: number,
-  value: T,
-  privacy: "private" | "trusting" = "private"
-): void
-```
-
-Appends a new item after index `after`.
-
-If `privacy` is `"private"` **(default)**, both `value` is encrypted in the transaction, only readable by other members of the group this `CoList` belongs to. Not even sync servers can see the content in plaintext.
-
-If `privacy` is `"trusting"`, both `value` is stored in plaintext in the transaction, visible to everyone who gets a hold of it, including sync servers.
-
-#### `WritableCoList.prepend(after, value)`
-
-```typescript
-prepend(
-  before: number,
-  value: T,
-  privacy: "private" | "trusting" = "private"
-): void
-```
-
-Prepends a new item before index `before`.
-
-If `privacy` is `"private"` **(default)**, both `value` is encrypted in the transaction, only readable by other members of the group this `CoList` belongs to. Not even sync servers can see the content in plaintext.
-
-If `privacy` is `"trusting"`, both `value` is stored in plaintext in the transaction, visible to everyone who gets a hold of it, including sync servers.
-
-#### `WritableCoList.push(value)`
-
-```typescript
-push(
-  value: T,
-  privacy: "private" | "trusting" = "private"
-): void
-```
-
-Pushes a new item to the end of the list.
-
-If `privacy` is `"private"` **(default)**, both `value` is encrypted in the transaction, only readable by other members of the group this `CoList` belongs to. Not even sync servers can see the content in plaintext.
-
-If `privacy` is `"trusting"`, both `value` is stored in plaintext in the transaction, visible to everyone who gets a hold of it, including sync servers.
-
-#### `WritableCoList.delete(at)`
-
-```typescript
-delete(
-    at: number,
-    privacy: "private" | "trusting" = "private"
-): void
-```
-
-Deletes the item at index `at` from the list.
-
-If `privacy` is `"private"` **(default)**, the fact of this deletion is encrypted in the transaction, only readable by other members of the group this `CoList` belongs to. Not even sync servers can see the content in plaintext.
-
-If `privacy` is `"trusting"`, the fact of this deletion is stored in plaintext in the transaction, visible to everyone who gets a hold of it, including sync servers.
-
----
-### `CoValue` ContentType: `CoStream` (not yet implemented)
-
----
-### `CoValue` ContentType: `Static` (not yet implemented)
----
-
-## `jazz-react`
----
-### `<WithJazz>`
-
-Not yet documented, see [`examples/todo`](./examples/todo/) for now
-
----
-### `useJazz()`
-
-Not yet documented, see [`examples/todo`](./examples/todo/) for now
-
----
-### `useTelepathicData(coID)`
-
-Not yet documented, see [`examples/todo`](./examples/todo/) for now
-
----
-### `useProfile(accountID)`
-
-Not yet documented, see [`examples/todo`](./examples/todo/) for now
+Copyright 2023 &mdash; Garden Computing, Inc.

examples/pets/.eslintrc.cjs

@@ -0,0 +1,18 @@
+module.exports = {
+  root: true,
+  env: { browser: true, es2020: true },
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:react-hooks/recommended',
+  ],
+  ignorePatterns: ['dist', '.eslintrc.cjs'],
+  parser: '@typescript-eslint/parser',
+  plugins: ['react-refresh'],
+  rules: {
+    'react-refresh/only-export-components': [
+      'warn',
+      { allowConstantExport: true },
+    ],
+  },
+}

examples/pets/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

examples/pets/Dockerfile

@@ -0,0 +1,4 @@
+FROM caddy:2.7.3-alpine
+LABEL org.opencontainers.image.source="https://github.com/gardencmp/jazz"
+
+COPY ./dist /usr/share/caddy/

examples/pets/README.md

@@ -0,0 +1,51 @@
+# Jazz Rate-My-Pet List Example
+
+Live version: https://example-pets.jazz.tools
+
+## Installing & running the example locally
+
+Start by checking out just the example app to a folder:
+
+```bash
+npx degit gardencmp/jazz/examples/pets jazz-example-pets
+cd jazz-example-pets
+```
+
+(This ensures that you have the example app without git history or our multi-package monorepo)
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Start the dev server:
+
+```bash
+npm run dev
+```
+
+## Structure
+
+TODO
+
+## Walkthrough
+
+### Main parts
+
+TODO
+
+### Helpers
+
+TODO
+
+## Questions / problems / feedback
+
+If you have feedback, let us know on [Discord](https://discord.gg/utDMjHYg42) or open an issue or PR to fix something that seems wrong.
+
+
+## Configuration: sync server
+
+By default, the example app uses [Jazz Global Mesh](https://jazz.tools/mesh) (`wss://sync.jazz.tools`) - so cross-device use, invites and collaboration should just work.
+
+You can also run a local sync server by running `npx cojson-simple-sync` and adding the query param `?sync=ws://localhost:4200` to the URL of the example app (for example: `http://localhost:5173/?sync=ws://localhost:4200`), or by setting the `sync` parameter of the `<WithJazz>` provider component in [./src/0_main.tsx](./src/0_main.tsx).

examples/pets/components.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "default",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.js",
+    "css": "src/index.css",
+    "baseColor": "stone",
+    "cssVariables": true
+  },
+  "aliases": {
+    "components": "@/basicComponents",
+    "utils": "@/basicComponents/lib/utils"
+  }
+}

examples/pets/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/png" href="/jazz-logo.png" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Jazz Rate My Pet Example</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/2_main.tsx"></script>
+  </body>
+</html>

examples/pets/job-template.nomad

@@ -0,0 +1,56 @@
+job "example-pets$BRANCH_SUFFIX" {
+  region     = "global"
+  datacenters = ["*"]
+
+  group "static" {
+    count = 8
+
+    network {
+      port "http" {
+        to = 80
+      }
+    }
+
+    constraint {
+      attribute = "${node.class}"
+      operator  = "="
+      value     = "mesh"
+    }
+
+    spread {
+      attribute = "${node.datacenter}"
+      weight    = 100
+    }
+
+    constraint {
+      distinct_hosts = true
+    }
+
+    task "server" {
+      driver = "docker"
+
+      config {
+        image = "$DOCKER_TAG"
+        ports = ["http"]
+
+        auth = {
+          username = "$DOCKER_USER"
+          password = "$DOCKER_PASSWORD"
+        }
+      }
+
+      service {
+        tags = ["public"]
+        name = "example-pets$BRANCH_SUFFIX"
+        port = "http"
+        provider = "consul"
+      }
+
+      resources {
+        cpu    = 50 # MHz
+        memory = 50 # MB
+      }
+    }
+  }
+}
+# deploy bump 4

examples/pets/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "jazz-example-pets",
+  "private": true,
+  "version": "0.0.19",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@radix-ui/react-checkbox": "^1.0.4",
+    "@radix-ui/react-slot": "^1.0.2",
+    "@radix-ui/react-toast": "^1.1.4",
+    "@types/qrcode": "^1.5.1",
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.0.0",
+    "jazz-browser-media-images": "^0.4.7",
+    "jazz-react": "^0.4.6",
+    "jazz-react-auth-local": "^0.4.6",
+    "lucide-react": "^0.274.0",
+    "qrcode": "^1.5.3",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-router": "^6.16.0",
+    "react-router-dom": "^6.16.0",
+    "tailwind-merge": "^1.14.0",
+    "tailwindcss-animate": "^1.0.7",
+    "uniqolor": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.15",
+    "@types/react-dom": "^18.2.7",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "@vitejs/plugin-react-swc": "^3.3.2",
+    "autoprefixer": "^10.4.14",
+    "eslint": "^8.45.0",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-react-refresh": "^0.4.3",
+    "postcss": "^8.4.27",
+    "tailwindcss": "^3.3.3",
+    "typescript": "^5.0.2",
+    "vite": "^4.4.5"
+  }
+}

examples/pets/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

examples/pets/src/1_types.ts

@@ -0,0 +1,52 @@
+import {
+    AccountMigration,
+    CoList,
+    CoMap,
+    CoStream,
+    Media,
+    Profile,
+} from "cojson";
+
+/** Walkthrough: Defining the data model with CoJSON
+ *
+ *  Here, we define our main data model of TODO
+ *
+ *  TODO
+ **/
+
+export type PetPost = CoMap<{
+    name: string;
+    image: Media.ImageDefinition["id"];
+    reactions: PetReactions["id"];
+}>;
+
+export const REACTION_TYPES = [
+    "aww",
+    "love",
+    "haha",
+    "wow",
+    "tiny",
+    "chonkers",
+] as const;
+
+export type ReactionType = (typeof REACTION_TYPES)[number];
+
+export type PetReactions = CoStream<ReactionType>;
+
+export type ListOfPosts = CoList<PetPost["id"]>;
+
+export type PetAccountRoot = CoMap<{
+    posts: ListOfPosts["id"];
+}>;
+
+export const migration: AccountMigration<Profile, PetAccountRoot> = (account) => {
+    if (!account.get("root")) {
+        const root = account.createMap<PetAccountRoot>({
+            posts: account.createList<ListOfPosts>().id,
+        });
+        account.set("root", root.id);
+        console.log("Created root", root.id);
+    }
+};
+
+/** Walkthrough: Continue with ./2_App.tsx */

examples/pets/src/2_main.tsx

@@ -0,0 +1,115 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { Link, RouterProvider, createHashRouter } from "react-router-dom";
+import "./index.css";
+
+import { WithJazz, useJazz, useAcceptInvite } from "jazz-react";
+import { LocalAuth } from "jazz-react-auth-local";
+
+import {
+    Button,
+    ThemeProvider,
+    TitleAndLogo,
+} from "./basicComponents/index.ts";
+import { PrettyAuthUI } from "./components/Auth.tsx";
+import { NewPetPostForm } from "./3_NewPetPostForm.tsx";
+import { RatePetPostUI } from "./4_RatePetPostUI.tsx";
+import { PetAccountRoot, migration } from "./1_types.ts";
+import { AccountMigration, Profile } from "cojson";
+
+/** Walkthrough: The top-level provider `<WithJazz/>`
+ *
+ *  This shows how to use the top-level provider `<WithJazz/>`,
+ *  which provides the rest of the app with a `LocalNode` (used through `useJazz` later),
+ *  based on `LocalAuth` that uses PassKeys (aka WebAuthn) to store a user's account secret
+ *  - no backend needed. */
+
+const appName = "Jazz Rate My Pet Example";
+
+const auth = LocalAuth({
+    appName,
+    Component: PrettyAuthUI,
+});
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+    <React.StrictMode>
+        <ThemeProvider>
+            <TitleAndLogo name={appName} />
+            <div className="flex flex-col h-full items-center justify-start gap-10 pt-10 pb-10 px-5">
+                <WithJazz auth={auth} migration={migration as AccountMigration}>
+                    <App />
+                </WithJazz>
+            </div>
+        </ThemeProvider>
+    </React.StrictMode>
+);
+
+/** Walkthrough: Creating pet posts & routing in `<App/>`
+ *
+ *  <App> is the main app component, handling client-side routing based
+ *  on the CoValue ID (CoID) of our PetPost, stored in the URL hash
+ *  - which can also contain invite links.
+ */
+
+export default function App() {
+    const { logOut } = useJazz();
+
+    const router = createHashRouter([
+        {
+            path: "/",
+            element: <PostOverview />,
+        },
+        {
+            path: "/new",
+            element: <NewPetPostForm />,
+        },
+        {
+            path: "/pet/:petPostId",
+            element: <RatePetPostUI />,
+        },
+        {
+            path: "/invite/*",
+            element: <p>Accepting invite...</p>,
+        },
+    ]);
+
+    useAcceptInvite((petPostID) => router.navigate("/pet/" + petPostID));
+
+    return (
+        <>
+            <RouterProvider router={router} />
+
+            <Button
+                onClick={() => router.navigate("/").then(logOut)}
+                variant="outline"
+            >
+                Log Out
+            </Button>
+        </>
+    );
+}
+
+export function PostOverview() {
+    const { me } = useJazz<Profile, PetAccountRoot>();
+
+    const myPosts = me.root?.posts;
+
+    return (
+        <>
+            {myPosts?.length ? (
+                <>
+                    <h1>My posts</h1>
+                    {myPosts.map(
+                        (post) =>
+                            post && (
+                                <Link key={post.id} to={"/pet/" + post.id}>
+                                    {post.name}
+                                </Link>
+                            )
+                    )}
+                </>
+            ) : undefined}
+            <Link to="/new">New post</Link>
+        </>
+    );
+}

examples/pets/src/3_NewPetPostForm.tsx

@@ -0,0 +1,107 @@
+import { ChangeEvent, useCallback, useState } from "react";
+import { useNavigate } from "react-router";
+
+import { CoID, CoMap, Media, Profile } from "cojson";
+import { useAutoSub, useJazz } from "jazz-react";
+import { BrowserImage, createImage } from "jazz-browser-media-images";
+
+import { PetAccountRoot, PetPost, PetReactions } from "./1_types";
+
+import { Input, Button } from "./basicComponents";
+
+/** Walkthrough: TODO
+ */
+
+type PartialPetPost = CoMap<{
+    name: string;
+    image?: Media.ImageDefinition["id"];
+    reactions: PetReactions["id"];
+}>;
+
+export function NewPetPostForm() {
+    const { me } = useJazz<Profile, PetAccountRoot>();
+    const navigate = useNavigate();
+
+    const [newPostId, setNewPostId] = useState<
+        CoID<PartialPetPost> | undefined
+    >(undefined);
+
+    const newPetPost = useAutoSub(newPostId);
+
+    const onChangeName = useCallback(
+        (name: string) => {
+            if (newPetPost) {
+                newPetPost.set({ name });
+            } else {
+                const petPostGroup = me.createGroup();
+                const petPost = petPostGroup.createMap<PartialPetPost>({
+                    name,
+                    reactions: petPostGroup.createStream<PetReactions>().id,
+                });
+
+                setNewPostId(petPost.id);
+            }
+        },
+        [me, newPetPost]
+    );
+
+    const onImageSelected = useCallback(
+        async (event: ChangeEvent<HTMLInputElement>) => {
+            if (!newPetPost || !event.target.files) return;
+
+            const image = await createImage(
+                event.target.files[0],
+                newPetPost.meta.group
+            );
+
+            newPetPost.set({ image: image.id });
+        },
+        [newPetPost]
+    );
+
+    const onSubmit = useCallback(() => {
+        if (!newPetPost) return;
+        const myPosts = me.root?.posts;
+
+        if (!myPosts) {
+            throw new Error("No posts list found");
+        }
+
+        myPosts.append(newPetPost.id as PetPost["id"]);
+
+        navigate("/pet/" + newPetPost.id);
+    }, [me.root?.posts, newPetPost, navigate]);
+
+    return (
+        <div className="flex flex-col gap-10">
+            <p>Share your pet with friends!</p>
+            <Input
+                type="text"
+                placeholder="Pet Name"
+                className="text-3xl py-6"
+                onChange={(event) => onChangeName(event.target.value)}
+                value={newPetPost?.name || ""}
+            />
+
+            {newPetPost?.image ? (
+                <img
+                    className="w-80 max-w-full rounded"
+                    src={
+                        newPetPost?.image.as(BrowserImage)
+                            ?.highestResSrcOrPlaceholder
+                    }
+                />
+            ) : (
+                <Input
+                    type="file"
+                    disabled={!newPetPost?.name}
+                    onChange={onImageSelected}
+                />
+            )}
+
+            {newPetPost?.name && newPetPost?.image && (
+                <Button onClick={onSubmit}>Submit Post</Button>
+            )}
+        </div>
+    );
+}

examples/pets/src/4_RatePetPostUI.tsx

@@ -0,0 +1,126 @@
+import { useParams } from "react-router";
+import { CoID } from "cojson";
+
+import { PetPost, ReactionType, REACTION_TYPES, PetReactions } from "./1_types";
+
+import { ShareButton } from "./components/ShareButton";
+import { Button, Skeleton } from "./basicComponents";
+import { BrowserImage } from "jazz-browser-media-images";
+import uniqolor from "uniqolor";
+import { Resolved, useAutoSub } from "jazz-react";
+
+/** Walkthrough: TODO
+ */
+
+const reactionEmojiMap: { [reaction in ReactionType]: string } = {
+    aww: "😍",
+    love: "❤️",
+    haha: "😂",
+    wow: "😮",
+    tiny: "🐥",
+    chonkers: "🐘",
+};
+
+export function RatePetPostUI() {
+    const petPostID = useParams<{ petPostId: CoID<PetPost> }>().petPostId;
+
+    const petPost = useAutoSub(petPostID);
+
+    return (
+        <div className="flex flex-col gap-8">
+            <div className="flex justify-between">
+                <h1 className="text-3xl font-bold">{petPost?.name}</h1>
+                <ShareButton petPost={petPost} />
+            </div>
+
+            {petPost?.image && (
+                <img
+                    className="w-80 max-w-full rounded"
+                    src={
+                        petPost.image.as(BrowserImage)
+                            ?.highestResSrcOrPlaceholder
+                    }
+                />
+            )}
+
+            <div className="flex justify-between max-w-xs flex-wrap">
+                {REACTION_TYPES.map((reactionType) => (
+                    <Button
+                        key={reactionType}
+                        variant={
+                            petPost?.reactions?.me?.last === reactionType
+                                ? "default"
+                                : "outline"
+                        }
+                        onClick={() => {
+                            petPost?.reactions?.push(reactionType);
+                        }}
+                        title={`React with ${reactionType}`}
+                        className="text-2xl px-2"
+                    >
+                        {reactionEmojiMap[reactionType]}
+                    </Button>
+                ))}
+            </div>
+
+            {petPost?.meta.group.myRole() === "admin" && petPost.reactions && (
+                <ReactionOverview petReactions={petPost.reactions} />
+            )}
+        </div>
+    );
+}
+
+function ReactionOverview({
+    petReactions,
+}: {
+    petReactions: Resolved<PetReactions>;
+}) {
+    return (
+        <div>
+            <h2>Reactions</h2>
+            <div className="flex flex-col gap-1">
+                {REACTION_TYPES.map((reactionType) => {
+                    const reactionsOfThisType = petReactions.perAccount
+                        .map(([, reaction]) => reaction)
+                        .filter(({ last }) => last === reactionType);
+
+                    if (reactionsOfThisType.length === 0) return null;
+
+                    return (
+                        <div
+                            className="flex gap-2 items-center"
+                            key={reactionType}
+                        >
+                            {reactionEmojiMap[reactionType]}{" "}
+                            {reactionsOfThisType.map((reaction, idx) =>
+                                reaction.by?.profile?.name ? (
+                                    <span
+                                        className="rounded-full py-0.5 px-2 text-xs"
+                                        style={uniqueColoring(reaction.by.id)}
+                                        key={reaction.by.id}
+                                    >
+                                        {reaction.by.profile.name}
+                                    </span>
+                                ) : (
+                                    <Skeleton
+                                        className="mt-1 w-[50px] h-[1em] rounded-full"
+                                        key={idx}
+                                    />
+                                )
+                            )}
+                        </div>
+                    );
+                })}
+            </div>
+        </div>
+    );
+}
+
+function uniqueColoring(seed: string) {
+    const darkMode = window.matchMedia("(prefers-color-scheme: dark)").matches;
+
+    return {
+        color: uniqolor(seed, { lightness: darkMode ? 80 : 20 }).color,
+        background: uniqolor(seed, { lightness: darkMode ? 20 : 80 }).color,
+    };
+}

examples/pets/src/basicComponents/TitleAndLogo.tsx

@@ -0,0 +1,12 @@
+import { Toaster } from ".";
+
+export function TitleAndLogo({ name }: { name: string }) {
+    return (
+        <>
+            <div className="flex items-center gap-2 justify-center mt-5">
+                <img src="jazz-logo.png" className="h-5" /> {name}
+            </div>
+            <Toaster />
+        </>
+    );
+}

examples/pets/src/basicComponents/index.ts

@@ -0,0 +1,7 @@
+export { Button } from "./ui/button";
+export { Input } from "./ui/input";
+export { Toaster } from "./ui/toaster";
+export { useToast } from "./ui/use-toast";
+export { Skeleton } from "./ui/skeleton";
+export { TitleAndLogo } from "./TitleAndLogo";
+export { ThemeProvider } from "./themeProvider";

examples/pets/src/basicComponents/ui/button.tsx

@@ -2,7 +2,7 @@ import * as React from "react"
 import { Slot } from "@radix-ui/react-slot"
 import { cva, type VariantProps } from "class-variance-authority"
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/basicComponents/lib/utils"
 
 const buttonVariants = cva(
   "inline-flex items-center justify-center rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",

examples/pets/src/basicComponents/ui/input.tsx

@@ -1,6 +1,6 @@
 import * as React from "react"
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/basicComponents/lib/utils"
 
 export interface InputProps
   extends React.InputHTMLAttributes<HTMLInputElement> {}

examples/pets/src/basicComponents/ui/skeleton.tsx

@@ -1,4 +1,4 @@
-import { cn } from "@/lib/utils"
+import { cn } from "@/basicComponents/lib/utils"
 
 function Skeleton({
   className,

examples/pets/src/basicComponents/ui/toast.tsx

@@ -3,7 +3,7 @@ import * as ToastPrimitives from "@radix-ui/react-toast"
 import { cva, type VariantProps } from "class-variance-authority"
 import { X } from "lucide-react"
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/basicComponents/lib/utils"
 
 const ToastProvider = ToastPrimitives.Provider
 

examples/pets/src/basicComponents/ui/toaster.tsx

@@ -5,8 +5,8 @@ import {
   ToastProvider,
   ToastTitle,
   ToastViewport,
-} from "@/components/ui/toast"
-import { useToast } from "@/components/ui/use-toast"
+} from "@/basicComponents/ui/toast"
+import { useToast } from "@/basicComponents/ui/use-toast"
 
 export function Toaster() {
   const { toasts } = useToast()

examples/pets/src/basicComponents/ui/use-toast.ts

@@ -4,7 +4,7 @@ import * as React from "react"
 import type {
   ToastActionElement,
   ToastProps,
-} from "@/components/ui/toast"
+} from "@/basicComponents/ui/toast"
 
 const TOAST_LIMIT = 1
 const TOAST_REMOVE_DELAY = 1000000

examples/pets/src/components/Auth.tsx

@@ -1,9 +1,10 @@
-import { LocalAuthComponent } from "jazz-react-auth-local";
 import { useState } from "react";
-import { Input } from "./ui/input";
-import { Button } from "./ui/button";
 
-export const PrettyAuthComponent: LocalAuthComponent = ({
+import { LocalAuthComponent } from "jazz-react-auth-local";
+
+import { Input, Button } from "../basicComponents";
+
+export const PrettyAuthUI: LocalAuthComponent = ({
     loading,
     logIn,
     signUp,

examples/pets/src/components/ShareButton.tsx

@@ -0,0 +1,46 @@
+import { useState } from "react";
+
+import { PetPost } from "../1_types";
+
+import { Resolved, createInviteLink } from "jazz-react";
+import QRCode from "qrcode";
+
+import { useToast, Button } from "../basicComponents";
+
+export function ShareButton({ petPost }: { petPost?: Resolved<PetPost> }) {
+    const [existingInviteLink, setExistingInviteLink] = useState<string>();
+    const { toast } = useToast();
+
+    return (
+        petPost?.meta.group.myRole() === "admin" && (
+            <Button
+                size="sm"
+                className="py-0"
+                disabled={!petPost}
+                variant="outline"
+                onClick={async () => {
+                    let inviteLink = existingInviteLink;
+                    if (petPost && !inviteLink) {
+                        inviteLink = createInviteLink(petPost, "writer");
+                        setExistingInviteLink(inviteLink);
+                    }
+                    if (inviteLink) {
+                        const qr = await QRCode.toDataURL(inviteLink, {
+                            errorCorrectionLevel: "L",
+                        });
+                        navigator.clipboard.writeText(inviteLink).then(() =>
+                            toast({
+                                title: "Copied invite link to clipboard!",
+                                description: (
+                                    <img src={qr} className="w-20 h-20" />
+                                ),
+                            })
+                        );
+                    }
+                }}
+            >
+                Share
+            </Button>
+        )
+    );
+}

examples/pets/src/index.css

@@ -0,0 +1,76 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+ 
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 20 14.3% 4.1%;
+
+    --card: 0 0% 100%;
+    --card-foreground: 20 14.3% 4.1%;
+ 
+    --popover: 0 0% 100%;
+    --popover-foreground: 20 14.3% 4.1%;
+ 
+    --primary: 24 9.8% 10%;
+    --primary-foreground: 60 9.1% 97.8%;
+ 
+    --secondary: 60 4.8% 95.9%;
+    --secondary-foreground: 24 9.8% 10%;
+ 
+    --muted: 60 4.8% 95.9%;
+    --muted-foreground: 25 5.3% 44.7%;
+ 
+    --accent: 60 4.8% 95.9%;
+    --accent-foreground: 24 9.8% 10%;
+ 
+    --destructive: 0 84.2% 60.2%;
+    --destructive-foreground: 60 9.1% 97.8%;
+
+    --border: 20 5.9% 90%;
+    --input: 20 5.9% 90%;
+    --ring: 20 14.3% 4.1%;
+ 
+    --radius: 0.5rem;
+  }
+ 
+  .dark {
+    --background: 20 14.3% 4.1%;
+    --foreground: 60 9.1% 97.8%;
+ 
+    --card: 20 14.3% 4.1%;
+    --card-foreground: 60 9.1% 97.8%;
+ 
+    --popover: 20 14.3% 4.1%;
+    --popover-foreground: 60 9.1% 97.8%;
+ 
+    --primary: 60 9.1% 97.8%;
+    --primary-foreground: 24 9.8% 10%;
+ 
+    --secondary: 12 6.5% 15.1%;
+    --secondary-foreground: 60 9.1% 97.8%;
+ 
+    --muted: 12 6.5% 15.1%;
+    --muted-foreground: 24 5.4% 63.9%;
+ 
+    --accent: 12 6.5% 15.1%;
+    --accent-foreground: 60 9.1% 97.8%;
+ 
+    --destructive: 0 62.8% 30.6%;
+    --destructive-foreground: 60 9.1% 97.8%;
+ 
+    --border: 12 6.5% 15.1%;
+    --input: 12 6.5% 15.1%;
+    --ring: 24 5.7% 82.9%;
+  }
+}
+ 
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}

examples/pets/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

examples/pets/tailwind.config.js

@@ -0,0 +1,76 @@
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  darkMode: ["class"],
+  content: [
+    './pages/**/*.{ts,tsx}',
+    './components/**/*.{ts,tsx}',
+    './app/**/*.{ts,tsx}',
+    './src/**/*.{ts,tsx}',
+	],
+  theme: {
+    container: {
+      center: true,
+      padding: "2rem",
+      screens: {
+        "2xl": "1400px",
+      },
+    },
+    extend: {
+      colors: {
+        border: "hsl(var(--border))",
+        input: "hsl(var(--input))",
+        ring: "hsl(var(--ring))",
+        background: "hsl(var(--background))",
+        foreground: "hsl(var(--foreground))",
+        primary: {
+          DEFAULT: "hsl(var(--primary))",
+          foreground: "hsl(var(--primary-foreground))",
+        },
+        secondary: {
+          DEFAULT: "hsl(var(--secondary))",
+          foreground: "hsl(var(--secondary-foreground))",
+        },
+        destructive: {
+          DEFAULT: "hsl(var(--destructive))",
+          foreground: "hsl(var(--destructive-foreground))",
+        },
+        muted: {
+          DEFAULT: "hsl(var(--muted))",
+          foreground: "hsl(var(--muted-foreground))",
+        },
+        accent: {
+          DEFAULT: "hsl(var(--accent))",
+          foreground: "hsl(var(--accent-foreground))",
+        },
+        popover: {
+          DEFAULT: "hsl(var(--popover))",
+          foreground: "hsl(var(--popover-foreground))",
+        },
+        card: {
+          DEFAULT: "hsl(var(--card))",
+          foreground: "hsl(var(--card-foreground))",
+        },
+      },
+      borderRadius: {
+        lg: "var(--radius)",
+        md: "calc(var(--radius) - 2px)",
+        sm: "calc(var(--radius) - 4px)",
+      },
+      keyframes: {
+        "accordion-down": {
+          from: { height: 0 },
+          to: { height: "var(--radix-accordion-content-height)" },
+        },
+        "accordion-up": {
+          from: { height: "var(--radix-accordion-content-height)" },
+          to: { height: 0 },
+        },
+      },
+      animation: {
+        "accordion-down": "accordion-down 0.2s ease-out",
+        "accordion-up": "accordion-up 0.2s ease-out",
+      },
+    },
+  },
+  plugins: [require("tailwindcss-animate")],
+}

examples/pets/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}

examples/pets/tsconfig.node.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["vite.config.ts"]
+}

examples/pets/vite.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react-swc'
+import path from "path";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+  build: {
+    minify: false
+  }
+})

examples/todo/README.md

@@ -2,355 +2,63 @@
 
 Live version: https://example-todo.jazz.tools
 
-More comprehensive guide coming soon, but these are the most important bits, with explanations:
+## Installing & running the example locally
 
-From `./src/main.tsx`
-
-```typescript
-// ...
-
-import { WithJazz } from "jazz-react";
-import { LocalAuth } from "jazz-react-auth-local";
-
-// ...
-
-ReactDOM.createRoot(document.getElementById("root")!).render(
-    <React.StrictMode>
-        <ThemeProvider>
-            <div className="flex items-center gap-2 justify-center mt-5">
-                <img src="jazz-logo.png" className="h-5" /> Jazz Todo List
-                Example
-            </div>
-            <WithJazz
-                auth={LocalAuth({
-                    appName: "Jazz Todo List Example",
-                    Component: PrettyAuthComponent,
-                })}
-            >
-                <App />
-            </WithJazz>
-        </ThemeProvider>
-    </React.StrictMode>
-);
+Start by checking out just the example app to a folder:
 
+```bash
+npx degit gardencmp/jazz/examples/todo jazz-example-todo
+cd jazz-example-todo
 ```
 
-This shows how to use the top-level component `<WithJazz/>`, which provides the rest of the app with a `LocalNode` (used through `useJazz` later), based on `LocalAuth` that uses Passkeys to store a user's account secret - no backend needed.
+(This ensures that you have the example app without git history or our multi-package monorepo)
 
-Let's move on to the main app code.
+Install dependencies:
 
----
-
-From `./src/App.tsx`
-
-```typescript
-// ...
-
-import { CoMap, CoID, AccountID } from "cojson";
-import {
-   consumeInviteLinkFromWindowLocation,
-   useJazz,
-   useProfile,
-   useTelepathicState,
-   createInviteLink
-} from "jazz-react";
-
-// ...
-
-type Task = CoMap<{ done: boolean; text: string }>;
-
-type ListOfTasks = CoList<CoID<Task>>;
-
-type TodoList = CoMap<{
-    title: string;
-    tasks: CoID<ListOfTasks>;
-}>;
-
-// ...
+```bash
+npm install
 ```
 
-First, we define our main data model of tasks and todo lists, using CoJSON's collaborative map and list types, `CoMap` & `CoList`.
+Start the dev server:
 
----
-
-```typescript
-// ...
-
-export default function App() {
-    const [listId, setListId] = useState<CoID<TodoList>>();
-
-    const { localNode, logOut } = useJazz();
-
-    useEffect(() => {
-        const listener = async () => {
-            const acceptedInvitation =
-                await consumeInviteLinkFromWindowLocation(localNode);
-
-            if (acceptedInvitation) {
-                setListId(acceptedInvitation.valueID as CoID<TodoList>);
-                window.location.hash = acceptedInvitation.valueID;
-                return;
-            }
-
-            setListId(window.location.hash.slice(1) as CoID<TodoList>);
-        };
-        window.addEventListener("hashchange", listener);
-        listener();
-
-        return () => {
-            window.removeEventListener("hashchange", listener);
-        };
-    }, [localNode]);
-
-    const createList = useCallback(
-        (title: string) => {
-            if (!title) return;
-            const listGroup = localNode.createGroup();
-            const list = listGroup.createMap<TodoList>();
-            const tasks = listGroup.createList<ListOfTasks>();
-
-            list.edit((list) => {
-                list.set("title", title);
-                list.set("tasks", tasks.id);
-            });
-
-            window.location.hash = list.id;
-        },
-        [localNode]
-    );
-
-    return (
-        <div className="flex flex-col h-full items-center justify-start gap-10 pt-10 pb-10 px-5">
-            {listId ? (
-                <TodoListComponent listId={listId} />
-            ) : (
-                <SubmittableInput
-                    onSubmit={createList}
-                    label="Create New List"
-                    placeholder="New list title"
-                />
-            )}
-            <Button
-                onClick={() => {
-                    window.location.hash = "";
-                    logOut();
-                }}
-                variant="outline"
-            >
-                Log Out
-            </Button>
-        </div>
-    );
-}
+```bash
+npm run dev
 ```
 
-`<App>` is the main app component, handling client-side routing based on the CoValue ID (`CoID`) of our `TodoList`, stored in the URL hash - which can also contain invite links, which we intercept and use with `consumeInviteLinkFromWindowLocation`.
+## Structure
 
-`createList` is the first time we see CoJSON in action: using our `localNode` (which we got from `useJazz`), we first create a group for a new todo list (which allows us to set permissions later). Then, within that group, we create a new `CoMap<TodoListContent>` with `listGroup.createMap()`.
+- [`src/basicComponents`](./src/basicComponents): simple components to build the UI, unrelated to Jazz (uses [shadcn/ui](https://ui.shadcn.com))
+- [`src/components`](./src/components/): helper components that do contain Jazz-specific logic, but aren't very relevant to understand the basics of Jazz and CoJSON
+- [`src/1_types.ts`](./src/1_types.ts),
+[`src/2_main.tsx`](./src/2_main.tsx),
+[`src/3_NewProjectForm.tsx`](./src/3_NewProjectForm.tsx),
+[`src/4_ProjectTodoTable.tsx`](./src/4_ProjectTodoTable.tsx): the main files for this example, see the walkthrough below
 
-We immediately start editing the created `list`. Within the edit callback, we can use the `set` function, to collaboratively set the key `title` to the initial title provided to `createList`.
+## Walkthrough
 
-If we have a current `listId` set, we render `<TodoListComponent>` with it, which we'll see next.
+### Main parts
 
-If we have no `listId` set, the user can use the displayed creation input to create (and open) their first list.
+1. Defining the data model with CoJSON: [`src/1_types.ts`](./src/1_types.ts)
 
----
+2. The top-level provider `<WithJazz/>` and routing: [`src/2_main.tsx`](./src/2_main.tsx)
 
-```typescript
-export function TodoListComponent({ listId }: { listId: CoID<TodoList> }) {
-    const list = useTelepathicState(listId);
-    const tasks = useTelepathicState(list?.get("tasks"));
+3. Creating a new todo project: [`src/3_NewProjectForm.tsx`](./src/3_NewProjectForm.tsx)
 
-    const createTask = (text: string) => {
-        if (!tasks || !text) return;
-        const task = tasks.group.createMap<Task>();
+4. Reactively rendering a todo project as a table, adding and editing tasks: [`src/4_ProjectTodoTable.tsx`](./src/4_ProjectTodoTable.tsx)
 
-        task.edit((task) => {
-            task.set("text", text);
-            task.set("done", false);
-        });
+### Helpers
 
-        tasks.edit((tasks) => {
-            tasks.push(task.id);
-        });
-    };
-
-    return (
-        <div className="max-w-full w-4xl">
-            <div className="flex justify-between items-center gap-4 mb-4">
-                <h1>
-                    {list?.get("title") ? (
-                        <>
-                            {list.get("title")}{" "}
-                            <span className="text-sm">({list.id})</span>
-                        </>
-                    ) : (
-                        <Skeleton className="mt-1 w-[200px] h-[1em] rounded-full" />
-                    )}
-                </h1>
-                {list && <InviteButton list={list} />}
-            </div>
-            <Table>
-                <TableHeader>
-                    <TableRow>
-                        <TableHead className="w-[40px]">Done</TableHead>
-                        <TableHead>Task</TableHead>
-                    </TableRow>
-                </TableHeader>
-                <TableBody>
-                    {tasks &&
-                        tasks
-                            .asArray()
-                            .map((taskId) => (
-                                <TaskRow key={taskId} taskId={taskId} />
-                            ))}
-                    <TableRow key="new">
-                        <TableCell>
-                            <Checkbox className="mt-1" disabled />
-                        </TableCell>
-                        <TableCell>
-                            <SubmittableInput
-                                onSubmit={(taskText) => createTask(taskText)}
-                                label="Add"
-                                placeholder="New task"
-                                disabled={!list}
-                            />
-                        </TableCell>
-                    </TableRow>
-                </TableBody>
-            </Table>
-        </div>
-    );
-}
-```
-
-Here in `<TodoListComponent>`, we use `useTelepathicData()` for the first time, in this case to load the CoValue for our `TodoList` as well as the `ListOfTasks` referenced in it. `useTelepathicData()` reactively subscribes to updates to a CoValue's content - whether we create edits locally, load persisted data, or receive sync updates from other devices or participants!
-
-`createTask` is similar to `createList` we saw earlier, creating a new CoMap for a new task, and then adding it as an item to our `TodoList`'s `ListOfTasks`.
-
-As you can see, we iterate over the items of our `ListOfTasks` and render a `<TaskRow>` for each.
-
-Below all tasks, we render a simple input for adding a task.
-
----
-
-```typescript
-function TaskRow({ taskId }: { taskId: CoID<Task> }) {
-    const task = useTelepathicState(taskId);
-
-    return (
-        <TableRow>
-            <TableCell>
-                <Checkbox
-                    className="mt-1"
-                    checked={task?.get("done")}
-                    onCheckedChange={(checked) => {
-                        task?.edit((task) => {
-                            task.set("done", !!checked);
-                        });
-                    }}
-                />
-            </TableCell>
-            <TableCell>
-                <div className="flex flex-row justify-between items-center gap-2">
-                    <span className={task?.get("done") ? "line-through" : ""}>
-                        {task?.get("text") || (
-                            <Skeleton className="mt-1 w-[200px] h-[1em] rounded-full" />
-                        )}
-                    </span>
-                    <NameBadge accountID={task?.whoEdited("text")} />
-                </div>
-            </TableCell>
-        </TableRow>
-    );
-}
-```
-
-`<TaskRow>` uses `useTelepathicState()` as well, to granularly load and subscribe to changes for that particular task (the only thing we let the user change is the "done" status).
-
-We also use a `<NameBadge>` helper component to render the name of the author of the task, which we get by using the collaboration feature `whoEdited(key)` on our `Task` CoMap, which returns the accountID of the last account that changed a given key in the CoMap.
-
----
-
-```typescript
-function NameBadge({ accountID }: { accountID?: AccountID }) {
-    const profile = useProfile(accountID);
-
-    const theme = window.matchMedia("(prefers-color-scheme: dark)").matches
-        ? "dark"
-        : "light";
-
-    const brightColor = uniqolor(accountID || "", { lightness: 80 }).color;
-    const darkColor = uniqolor(accountID || "", { lightness: 20 }).color;
-
-    return (
-        profile?.get("name") ? (
-            <span
-                className="rounded-full py-0.5 px-2 text-xs"
-                style={{
-                    color: theme == "light" ? darkColor : brightColor,
-                    background: theme == "light" ? brightColor : darkColor,
-                }}
-            >
-                {profile.get("name")}
-            </span>
-        ) : (
-            <Skeleton className="mt-1 w-[50px] h-[1em] rounded-full" />
-        )
-    );
-}
-```
-
-`<NameBadge>` uses `useProfile(accountID)`, which is a shorthand for loading an account's profile (which is always a `CoMap<{name: string}>`, but might have app-specific additional properties).
-
-In our case, we just display the profile name (which, by the way, is set by the `LocalAuth` provider when we first create an account).
-
----
-
-```typescript
-function InviteButton({ list }: { list: TodoList }) {
-    const [existingInviteLink, setExistingInviteLink] = useState<string>();
-    const { toast } = useToast();
-
-    return (
-        list.group.myRole() === "admin" && (
-            <Button
-                size="sm"
-                className="py-0"
-                disabled={!list}
-                variant="outline"
-                onClick={async () => {
-                    let inviteLink = existingInviteLink;
-                    if (list && !inviteLink) {
-                        inviteLink = createInviteLink(list, "writer");
-                        setExistingInviteLink(inviteLink);
-                    }
-                    if (inviteLink) {
-                        const qr = await QRCode.toDataURL(inviteLink, {
-                            errorCorrectionLevel: "L",
-                        });
-                        navigator.clipboard.writeText(inviteLink).then(() =>
-                            toast({
-                                title: "Copied invite link to clipboard!",
-                                description: (
-                                    <img src={qr} className="w-20 h-20" />
-                                ),
-                            })
-                        );
-                    }
-                }}
-            >
-                Invite
-            </Button>
-        )
-    );
-}
-```
-
-Last, we have a look at the `<InviteButton>` component, which we use inside `<TodoListComponent>`. It only becomes visible when the current user is an admin in the `TodoList`'s group. You can see how we can create an invite link using `createInviteLink(coValue, role)` that allows anyone who has it to join the group as a specified role (here, as a writer).
-
----
+- (not yet explained) Creating invite links/QR codes with `<InviteButton/>`: [`src/components/InviteButton.tsx`](./src/components/InviteButton.tsx)
 
 This is the whole Todo List app!
 
-If you have feedback, let us know on [Discord](https://discord.gg/utDMjHYg42) or open an issue or PR to fix something that seems wrong.
+## Questions / problems / feedback
+
+If you have feedback, let us know on [Discord](https://discord.gg/utDMjHYg42) or open an issue or PR to fix something that seems wrong.
+
+
+## Configuration: sync server
+
+By default, the example app uses [Jazz Global Mesh](https://jazz.tools/mesh) (`wss://sync.jazz.tools`) - so cross-device use, invites and collaboration should just work.
+
+You can also run a local sync server by running `npx cojson-simple-sync` and adding the query param `?sync=ws://localhost:4200` to the URL of the example app (for example: `http://localhost:5173/?sync=ws://localhost:4200`), or by setting the `sync` parameter of the `<WithJazz>` provider component in [./src/2_main.tsx](./src/2_main.tsx).

examples/todo/components.json

@@ -10,7 +10,7 @@
     "cssVariables": true
   },
   "aliases": {
-    "components": "@/components",
-    "utils": "@/lib/utils"
+    "components": "@/basicComponents",
+    "utils": "@/basicComponents/lib/utils"
   }
 }

examples/todo/index.html

@@ -8,6 +8,6 @@
   </head>
   <body>
     <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
+    <script type="module" src="/src/2_main.tsx"></script>
   </body>
 </html>

examples/todo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jazz-example-todo",
   "private": true,
-  "version": "0.0.22",
+  "version": "0.0.43",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -16,14 +16,16 @@
     "@types/qrcode": "^1.5.1",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.0.0",
-    "jazz-react": "^0.1.8",
-    "jazz-react-auth-local": "^0.1.8",
-    "lucide-react": "^0.265.0",
+    "jazz-react": "^0.4.6",
+    "jazz-react-auth-local": "^0.4.6",
+    "lucide-react": "^0.274.0",
     "qrcode": "^1.5.3",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
+    "react-router": "^6.16.0",
+    "react-router-dom": "^6.16.0",
     "tailwind-merge": "^1.14.0",
-    "tailwindcss-animate": "^1.0.6",
+    "tailwindcss-animate": "^1.0.7",
     "uniqolor": "^1.1.0"
   },
   "devDependencies": {

examples/todo/src/1_types.ts

@@ -0,0 +1,42 @@
+import { CoMap, CoList, AccountMigration, Profile } from "cojson";
+
+/** Walkthrough: Defining the data model with CoJSON
+ *
+ *  Here, we define our main data model of tasks, lists of tasks and projects
+ *  using CoJSON's collaborative map and list types, CoMap & CoList.
+ *
+ *  CoMap values and CoLists items can contain:
+ *  - arbitrary immutable JSON
+ *  - references to other CoValues by their CoID
+ **/
+
+/** An individual task which collaborators can tick or rename */
+export type Task = CoMap<{ done: boolean; text: string; }>;
+
+export type ListOfTasks = CoList<Task["id"]>;
+
+/** Our top level object: a project with a title, referencing a list of tasks */
+export type TodoProject = CoMap<{
+    title: string;
+    /** A collaborative, ordered list of tasks */
+    tasks: ListOfTasks["id"];
+}>;
+
+export type ListOfProjects = CoList<TodoProject["id"]>;
+
+export type TodoAccountRoot = CoMap<{
+    projects: ListOfProjects["id"];
+}>;
+
+export const migration: AccountMigration<Profile, TodoAccountRoot> = (account) => {
+    if (!account.get("root")) {
+        account.set(
+            "root",
+            account.createMap<TodoAccountRoot>({
+                projects: account.createList<ListOfProjects>().id,
+            }).id
+        );
+    }
+}
+
+/** Walkthrough: Continue with ./2_main.tsx */

examples/todo/src/2_main.tsx

@@ -0,0 +1,121 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import {
+    RouterProvider,
+    createHashRouter,
+    useNavigate,
+} from "react-router-dom";
+import "./index.css";
+
+import { WithJazz, useJazz, useAcceptInvite } from "jazz-react";
+import { LocalAuth } from "jazz-react-auth-local";
+
+import {
+    Button,
+    ThemeProvider,
+    TitleAndLogo,
+} from "./basicComponents/index.ts";
+import { PrettyAuthUI } from "./components/Auth.tsx";
+import { NewProjectForm } from "./3_NewProjectForm.tsx";
+import { ProjectTodoTable } from "./4_ProjectTodoTable.tsx";
+import { TodoAccountRoot, migration } from "./1_types.ts";
+import { AccountMigration, Profile } from "cojson";
+
+/**
+ * Walkthrough: The top-level provider `<WithJazz/>`
+ *
+ * This shows how to use the top-level provider `<WithJazz/>`,
+ * which provides the rest of the app with a `LocalNode` (used through `useJazz` later),
+ * based on `LocalAuth` that uses Passkeys (aka WebAuthn) to store a user's account secret
+ * - no backend needed.
+ */
+
+const appName = "Jazz Todo List Example";
+
+const auth = LocalAuth({
+    appName,
+    Component: PrettyAuthUI,
+});
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+    <React.StrictMode>
+        <ThemeProvider>
+            <TitleAndLogo name={appName} />
+            <div className="flex flex-col h-full items-center justify-start gap-10 pt-10 pb-10 px-5">
+                <WithJazz auth={auth} migration={migration as AccountMigration}>
+                    <App />
+                </WithJazz>
+            </div>
+        </ThemeProvider>
+    </React.StrictMode>
+);
+
+/**
+ * Routing in `<App/>`
+ *
+ * <App> is the main app component, handling client-side routing based
+ * on the CoValue ID (CoID) of our TodoProject, stored in the URL hash
+ * - which can also contain invite links.
+ */
+
+function App() {
+    // logOut logs out the AuthProvider passed to `<WithJazz/>` above.
+    const { logOut } = useJazz();
+
+    const router = createHashRouter([
+        {
+            path: "/",
+            element: <HomeScreen />,
+        },
+        {
+            path: "/project/:projectId",
+            element: <ProjectTodoTable />,
+        },
+        {
+            path: "/invite/*",
+            element: <p>Accepting invite...</p>,
+        },
+    ]);
+
+    // `useAcceptInvite()` is a hook that accepts an invite link from the URL hash,
+    // and on success calls our callback where we navigate to the project that we were just invited to.
+    useAcceptInvite((projectID) => router.navigate("/project/" + projectID));
+
+    return (
+        <>
+            <RouterProvider router={router} />
+
+            <Button
+                onClick={() => router.navigate("/").then(logOut)}
+                variant="outline"
+            >
+                Log Out
+            </Button>
+        </>
+    );
+}
+
+export function HomeScreen() {
+    const { me } = useJazz<Profile, TodoAccountRoot>();
+    const navigate = useNavigate();
+
+    return (
+        <>
+            {me.root?.projects?.length ? <h1>My Projects</h1> : null}
+            {me.root?.projects?.map((project) => {
+                return (
+                    <Button
+                        key={project?.id}
+                        onClick={() => navigate("/project/" + project?.id)}
+                        variant="ghost"
+                    >
+                        {project?.title}
+                    </Button>
+                );
+            })}
+            <NewProjectForm />
+        </>
+    );
+}
+
+/** Walkthrough: Continue with ./3_NewProjectForm.tsx */

examples/todo/src/3_NewProjectForm.tsx

@@ -0,0 +1,49 @@
+import { useCallback } from "react";
+
+import { useJazz } from "jazz-react";
+
+import { ListOfTasks, TodoAccountRoot, TodoProject } from "./1_types";
+
+import { SubmittableInput } from "./basicComponents";
+
+import { useNavigate } from "react-router";
+import { Profile } from "cojson";
+
+export function NewProjectForm() {
+    // `me` represents the current user account, which will determine
+    // access rights to CoValues. We get it from the top-level provider `<WithJazz/>`.
+    const { me } = useJazz<Profile, TodoAccountRoot>();
+    const navigate = useNavigate();
+
+    const createProject = useCallback(
+        (title: string) => {
+            if (!title) return;
+
+            // To create a new todo project, we first create a `Group`,
+            // which is a scope for defining access rights (reader/writer/admin)
+            // of its members, which will apply to all CoValues owned by that group.
+            const projectGroup = me.createGroup();
+
+            // Then we create an empty todo project within that group
+            const project = projectGroup.createMap<TodoProject>({
+                title,
+                tasks: projectGroup.createList<ListOfTasks>().id,
+            });
+
+            me.root?.projects?.append(project.id);
+
+            navigate("/project/" + project.id);
+        },
+        [me, navigate]
+    );
+
+    return (
+        <SubmittableInput
+            onSubmit={createProject}
+            label="Create New Project"
+            placeholder="New project title"
+        />
+    );
+}
+
+/** Walkthrough: continue with ./4_ProjectTodoTable.tsx */

examples/todo/src/4_ProjectTodoTable.tsx

@@ -0,0 +1,177 @@
+import { useCallback } from "react";
+
+import { CoID } from "cojson";
+
+import { TodoProject, Task } from "./1_types";
+
+import {
+    Checkbox,
+    SubmittableInput,
+    Skeleton,
+    Table,
+    TableBody,
+    TableCell,
+    TableHead,
+    TableHeader,
+    TableRow,
+} from "./basicComponents";
+
+import { InviteButton } from "./components/InviteButton";
+import uniqolor from "uniqolor";
+import { useParams } from "react-router";
+import { Resolved, useAutoSub } from "jazz-react";
+
+/** Walkthrough: Reactively rendering a todo project as a table,
+ *               adding and editing tasks
+ *
+ *  Here in `<TodoTable/>`, we use `useAutoSub()` for the first time,
+ *  in this case to load the CoValue for our `TodoProject` as well as
+ *  the `ListOfTasks` referenced in it.
+ */
+
+export function ProjectTodoTable() {
+    const projectId = useParams<{ projectId: CoID<TodoProject> }>().projectId;
+
+    // `useAutoSub()` reactively subscribes to updates to a CoValue's
+    // content - whether we create edits locally, load persisted data, or receive
+    // sync updates from other devices or participants!
+    // It also recursively resolves and subsribes to all referenced CoValues.
+    const project = useAutoSub(projectId);
+
+    // `createTask` is similar to `createProject` we saw earlier, creating a new CoMap
+    // for a new task (in the same group as the project), and then
+    // adding that as an item to the project's list of tasks.
+    const createTask = useCallback(
+        (text: string) => {
+            if (!project?.tasks || !text) return;
+            const task = project.meta.group.createMap<Task>({
+                done: false,
+                text,
+            });
+
+            // project.tasks is immutable, but `append` will create an edit
+            // that will cause useAutoSub to rerender this component
+            // - here and on other devices!
+            project.tasks.append(task.id);
+        },
+        [project?.tasks, project?.meta.group]
+    );
+
+    return (
+        <div className="max-w-full w-4xl">
+            <div className="flex justify-between items-center gap-4 mb-4">
+                <h1>
+                    {
+                        // This is how we can access properties from the project query,
+                        // accounting for the fact that note everything might be loaded yet
+                        project?.title ? (
+                            <>
+                                {project.title}{" "}
+                                <span className="text-sm">({project.id})</span>
+                            </>
+                        ) : (
+                            <Skeleton className="mt-1 w-[200px] h-[1em] rounded-full" />
+                        )
+                    }
+                </h1>
+                <InviteButton value={project} />
+            </div>
+            <Table>
+                <TableHeader>
+                    <TableRow>
+                        <TableHead className="w-[40px]">Done</TableHead>
+                        <TableHead>Task</TableHead>
+                    </TableRow>
+                </TableHeader>
+                <TableBody>
+                    {project?.tasks?.map(
+                        (task) => task && <TaskRow key={task.id} task={task} />
+                    )}
+                    <NewTaskInputRow
+                        createTask={createTask}
+                        disabled={!project}
+                    />
+                </TableBody>
+            </Table>
+        </div>
+    );
+}
+
+export function TaskRow({ task }: { task: Resolved<Task> | undefined }) {
+    return (
+        <TableRow>
+            <TableCell>
+                <Checkbox
+                    className="mt-1"
+                    checked={task?.done}
+                    onCheckedChange={(checked) => {
+                        // Tick or untick the task
+                        // Task is also immutable, but this will update all queries
+                        // that include this task as a reference
+                        task?.set({ done: !!checked });
+                    }}
+                />
+            </TableCell>
+            <TableCell>
+                <div className="flex flex-row justify-between items-center gap-2">
+                    {task?.text ? (
+                        <span className={task?.done ? "line-through" : ""}>
+                            {task.text}
+                        </span>
+                    ) : (
+                        <Skeleton className="mt-1 w-[200px] h-[1em] rounded-full" />
+                    )}
+                    {
+                        // Here we see for the first time how we can access edit history
+                        // for a CoValue, and use it to display who created the task.
+                        task?.meta.edits.text?.by?.profile?.name ? (
+                            <span
+                                className="rounded-full py-0.5 px-2 text-xs"
+                                style={uniqueColoring(task.meta.edits.text.by.id)}
+                            >
+                                {task.meta.edits.text.by.profile.name}
+                            </span>
+                        ) : (
+                            <Skeleton className="mt-1 w-[50px] h-[1em] rounded-full" />
+                        )
+                    }
+                </div>
+            </TableCell>
+        </TableRow>
+    );
+}
+
+/** Walkthrough: This is the end of the walkthrough so far! */
+
+function NewTaskInputRow({
+    createTask,
+    disabled,
+}: {
+    createTask: (text: string) => void;
+    disabled: boolean;
+}) {
+    return (
+        <TableRow>
+            <TableCell>
+                <Checkbox className="mt-1" disabled />
+            </TableCell>
+            <TableCell>
+                <SubmittableInput
+                    onSubmit={(taskText) => createTask(taskText)}
+                    label="Add"
+                    placeholder="New task"
+                    disabled={disabled}
+                />
+            </TableCell>
+        </TableRow>
+    );
+}
+
+function uniqueColoring(seed: string) {
+    const darkMode = window.matchMedia("(prefers-color-scheme: dark)").matches;
+
+    return {
+        color: uniqolor(seed, { lightness: darkMode ? 80 : 20 }).color,
+        background: uniqolor(seed, { lightness: darkMode ? 20 : 80 }).color,
+    };
+}

examples/todo/src/App.tsx

@@ -1,259 +0,0 @@
-import { useCallback, useEffect, useState } from "react";
-
-import { CoMap, CoID, AccountID } from "cojson";
-import {
-    consumeInviteLinkFromWindowLocation,
-    useJazz,
-    useProfile,
-    useTelepathicState,
-    createInviteLink,
-} from "jazz-react";
-
-import { SubmittableInput } from "./components/SubmittableInput";
-import { useToast } from "./components/ui/use-toast";
-import { Skeleton } from "./components/ui/skeleton";
-import {
-    Table,
-    TableBody,
-    TableCell,
-    TableHead,
-    TableHeader,
-    TableRow,
-} from "@/components/ui/table";
-import { Checkbox } from "@/components/ui/checkbox";
-import { Button } from "@/components/ui/button";
-import uniqolor from "uniqolor";
-import QRCode from "qrcode";
-import { CoList } from "cojson/dist/contentTypes/coList";
-
-type Task = CoMap<{ done: boolean; text: string }>;
-
-type ListOfTasks = CoList<CoID<Task>>;
-
-type TodoList = CoMap<{
-    title: string;
-    tasks: CoID<ListOfTasks>;
-}>;
-
-export default function App() {
-    const [listId, setListId] = useState<CoID<TodoList>>();
-
-    const { localNode, logOut } = useJazz();
-
-    useEffect(() => {
-        const listener = async () => {
-            const acceptedInvitation =
-                await consumeInviteLinkFromWindowLocation<TodoList>(localNode);
-
-            if (acceptedInvitation) {
-                setListId(acceptedInvitation.valueID);
-                window.location.hash = acceptedInvitation.valueID;
-                return;
-            }
-
-            setListId(window.location.hash.slice(1) as CoID<TodoList>);
-        };
-        window.addEventListener("hashchange", listener);
-        listener();
-
-        return () => {
-            window.removeEventListener("hashchange", listener);
-        };
-    }, [localNode]);
-
-    const createList = useCallback(
-        (title: string) => {
-            if (!title) return;
-            const listGroup = localNode.createGroup();
-            const list = listGroup.createMap<TodoList>();
-            const tasks = listGroup.createList<ListOfTasks>();
-
-            list.edit((list) => {
-                list.set("title", title);
-                list.set("tasks", tasks.id);
-            });
-
-            window.location.hash = list.id;
-        },
-        [localNode]
-    );
-
-    return (
-        <div className="flex flex-col h-full items-center justify-start gap-10 pt-10 pb-10 px-5">
-            {listId ? (
-                <TodoListComponent listId={listId} />
-            ) : (
-                <SubmittableInput
-                    onSubmit={createList}
-                    label="Create New List"
-                    placeholder="New list title"
-                />
-            )}
-            <Button
-                onClick={() => {
-                    window.location.hash = "";
-                    logOut();
-                }}
-                variant="outline"
-            >
-                Log Out
-            </Button>
-        </div>
-    );
-}
-
-export function TodoListComponent({ listId }: { listId: CoID<TodoList> }) {
-    const list = useTelepathicState(listId);
-    const tasks = useTelepathicState(list?.get("tasks"));
-
-    const createTask = (text: string) => {
-        if (!tasks || !text) return;
-        const task = tasks.group.createMap<Task>();
-
-        task.edit((task) => {
-            task.set("text", text);
-            task.set("done", false);
-        });
-
-        tasks.edit((tasks) => {
-            tasks.push(task.id);
-        });
-    };
-
-    return (
-        <div className="max-w-full w-4xl">
-            <div className="flex justify-between items-center gap-4 mb-4">
-                <h1>
-                    {list?.get("title") ? (
-                        <>
-                            {list.get("title")}{" "}
-                            <span className="text-sm">({list.id})</span>
-                        </>
-                    ) : (
-                        <Skeleton className="mt-1 w-[200px] h-[1em] rounded-full" />
-                    )}
-                </h1>
-                {list && <InviteButton list={list} />}
-            </div>
-            <Table>
-                <TableHeader>
-                    <TableRow>
-                        <TableHead className="w-[40px]">Done</TableHead>
-                        <TableHead>Task</TableHead>
-                    </TableRow>
-                </TableHeader>
-                <TableBody>
-                    {tasks?.map((taskId) => (
-                        <TaskRow key={taskId} taskId={taskId} />
-                    ))}
-                    <TableRow key="new">
-                        <TableCell>
-                            <Checkbox className="mt-1" disabled />
-                        </TableCell>
-                        <TableCell>
-                            <SubmittableInput
-                                onSubmit={(taskText) => createTask(taskText)}
-                                label="Add"
-                                placeholder="New task"
-                                disabled={!list}
-                            />
-                        </TableCell>
-                    </TableRow>
-                </TableBody>
-            </Table>
-        </div>
-    );
-}
-
-function TaskRow({ taskId }: { taskId: CoID<Task> }) {
-    const task = useTelepathicState(taskId);
-
-    return (
-        <TableRow>
-            <TableCell>
-                <Checkbox
-                    className="mt-1"
-                    checked={task?.get("done")}
-                    onCheckedChange={(checked) => {
-                        task?.edit((task) => {
-                            task.set("done", !!checked);
-                        });
-                    }}
-                />
-            </TableCell>
-            <TableCell>
-                <div className="flex flex-row justify-between items-center gap-2">
-                    <span className={task?.get("done") ? "line-through" : ""}>
-                        {task?.get("text") || (
-                            <Skeleton className="mt-1 w-[200px] h-[1em] rounded-full" />
-                        )}
-                    </span>
-                    <NameBadge accountID={task?.whoEdited("text")} />
-                </div>
-            </TableCell>
-        </TableRow>
-    );
-}
-
-function NameBadge({ accountID }: { accountID?: AccountID }) {
-    const profile = useProfile(accountID);
-
-    const theme = window.matchMedia("(prefers-color-scheme: dark)").matches
-        ? "dark"
-        : "light";
-
-    const brightColor = uniqolor(accountID || "", { lightness: 80 }).color;
-    const darkColor = uniqolor(accountID || "", { lightness: 20 }).color;
-
-    return profile?.get("name") ? (
-        <span
-            className="rounded-full py-0.5 px-2 text-xs"
-            style={{
-                color: theme == "light" ? darkColor : brightColor,
-                background: theme == "light" ? brightColor : darkColor,
-            }}
-        >
-            {profile.get("name")}
-        </span>
-    ) : (
-        <Skeleton className="mt-1 w-[50px] h-[1em] rounded-full" />
-    );
-}
-
-function InviteButton({ list }: { list: TodoList }) {
-    const [existingInviteLink, setExistingInviteLink] = useState<string>();
-    const { toast } = useToast();
-
-    return (
-        list.group.myRole() === "admin" && (
-            <Button
-                size="sm"
-                className="py-0"
-                disabled={!list}
-                variant="outline"
-                onClick={async () => {
-                    let inviteLink = existingInviteLink;
-                    if (list && !inviteLink) {
-                        inviteLink = createInviteLink(list, "writer");
-                        setExistingInviteLink(inviteLink);
-                    }
-                    if (inviteLink) {
-                        const qr = await QRCode.toDataURL(inviteLink, {
-                            errorCorrectionLevel: "L",
-                        });
-                        navigator.clipboard.writeText(inviteLink).then(() =>
-                            toast({
-                                title: "Copied invite link to clipboard!",
-                                description: (
-                                    <img src={qr} className="w-20 h-20" />
-                                ),
-                            })
-                        );
-                    }
-                }}
-            >
-                Invite
-            </Button>
-        )
-    );
-}

examples/todo/src/basicComponents/SubmittableInput.tsx

@@ -1,5 +1,5 @@
-import { Input } from "@/components/ui/input";
-import { Button } from "@/components/ui/button";
+import { Input } from "@/basicComponents/ui/input";
+import { Button } from "@/basicComponents/ui/button";
 
 export function SubmittableInput({
     onSubmit,

examples/todo/src/basicComponents/TitleAndLogo.tsx

@@ -0,0 +1,10 @@
+import { Toaster } from ".";
+
+export function TitleAndLogo({name}: {name: string}) {
+    return <>
+        <div className="flex items-center gap-2 justify-center mt-5">
+                <img src="jazz-logo.png" className="h-5" /> {name}
+            </div>
+            <Toaster />
+    </>
+}

examples/todo/src/basicComponents/index.ts

@@ -0,0 +1,17 @@
+export { Button } from "./ui/button";
+export { Checkbox } from "./ui/checkbox";
+export { Input } from "./ui/input";
+export { Skeleton } from "./ui/skeleton";
+export { Toaster } from "./ui/toaster";
+export { useToast } from "./ui/use-toast";
+export { SubmittableInput } from "./SubmittableInput";
+export { TitleAndLogo } from "./TitleAndLogo";
+export { ThemeProvider } from "./themeProvider";
+export {
+    Table,
+    TableBody,
+    TableCell,
+    TableHead,
+    TableHeader,
+    TableRow,
+} from "./ui/table";

examples/todo/src/basicComponents/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx"
+import { twMerge } from "tailwind-merge"
+ 
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

examples/todo/src/basicComponents/themeProvider.tsx

@@ -0,0 +1,72 @@
+import { createContext, useContext, useEffect, useState } from "react";
+
+type ThemeProviderProps = {
+    children: React.ReactNode;
+    defaultTheme?: string;
+    storageKey?: string;
+};
+
+type ThemeProviderState = {
+    theme: string;
+    setTheme: (theme: string) => void;
+};
+
+const initialState = {
+    theme: "system",
+    setTheme: () => null,
+};
+
+const ThemeProviderContext = createContext<ThemeProviderState>(initialState);
+
+export function ThemeProvider({
+    children,
+    defaultTheme = "system",
+    storageKey = "vite-ui-theme",
+    ...props
+}: ThemeProviderProps) {
+    const [theme, setTheme] = useState(
+        () => localStorage.getItem(storageKey) || defaultTheme
+    );
+
+    useEffect(() => {
+        const root = window.document.documentElement;
+
+        root.classList.remove("light", "dark");
+
+        if (theme === "system") {
+            const systemTheme = window.matchMedia(
+                "(prefers-color-scheme: dark)"
+            ).matches
+                ? "dark"
+                : "light";
+
+            root.classList.add(systemTheme);
+            return;
+        }
+
+        root.classList.add(theme);
+    }, [theme]);
+
+    const value = {
+        theme,
+        setTheme: (theme: string) => {
+            localStorage.setItem(storageKey, theme);
+            setTheme(theme);
+        },
+    };
+
+    return (
+        <ThemeProviderContext.Provider {...props} value={value}>
+            {children}
+        </ThemeProviderContext.Provider>
+    );
+}
+
+export const useTheme = () => {
+    const context = useContext(ThemeProviderContext);
+
+    if (context === undefined)
+        throw new Error("useTheme must be used within a ThemeProvider");
+
+    return context;
+};

examples/todo/src/basicComponents/ui/button.tsx

@@ -0,0 +1,56 @@
+import * as React from "react"
+import { Slot } from "@radix-ui/react-slot"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/basicComponents/lib/utils"
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        outline:
+          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+        lg: "h-11 rounded-md px-8",
+        icon: "h-10 w-10",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button"
+    return (
+      <Comp
+        className={cn(buttonVariants({ variant, size, className }))}
+        ref={ref}
+        {...props}
+      />
+    )
+  }
+)
+Button.displayName = "Button"
+
+export { Button, buttonVariants }

examples/todo/src/basicComponents/ui/checkbox.tsx

@@ -2,7 +2,7 @@ import * as React from "react"
 import * as CheckboxPrimitive from "@radix-ui/react-checkbox"
 import { Check } from "lucide-react"
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/basicComponents/lib/utils"
 
 const Checkbox = React.forwardRef<
   React.ElementRef<typeof CheckboxPrimitive.Root>,

examples/todo/src/basicComponents/ui/input.tsx

@@ -0,0 +1,25 @@
+import * as React from "react"
+
+import { cn } from "@/basicComponents/lib/utils"
+
+export interface InputProps
+  extends React.InputHTMLAttributes<HTMLInputElement> {}
+
+const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  ({ className, type, ...props }, ref) => {
+    return (
+      <input
+        type={type}
+        className={cn(
+          "flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+          className
+        )}
+        ref={ref}
+        {...props}
+      />
+    )
+  }
+)
+Input.displayName = "Input"
+
+export { Input }

examples/todo/src/basicComponents/ui/skeleton.tsx

@@ -0,0 +1,15 @@
+import { cn } from "@/basicComponents/lib/utils"
+
+function Skeleton({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn("animate-pulse rounded-md bg-muted", className)}
+      {...props}
+    />
+  )
+}
+
+export { Skeleton }

examples/todo/src/basicComponents/ui/table.tsx

@@ -1,6 +1,6 @@
 import * as React from "react"
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/basicComponents/lib/utils"
 
 const Table = React.forwardRef<
   HTMLTableElement,

examples/todo/src/basicComponents/ui/toast.tsx

@@ -0,0 +1,127 @@
+import * as React from "react"
+import * as ToastPrimitives from "@radix-ui/react-toast"
+import { cva, type VariantProps } from "class-variance-authority"
+import { X } from "lucide-react"
+
+import { cn } from "@/basicComponents/lib/utils"
+
+const ToastProvider = ToastPrimitives.Provider
+
+const ToastViewport = React.forwardRef<
+  React.ElementRef<typeof ToastPrimitives.Viewport>,
+  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Viewport>
+>(({ className, ...props }, ref) => (
+  <ToastPrimitives.Viewport
+    ref={ref}
+    className={cn(
+      "fixed top-0 z-[100] flex max-h-screen w-full flex-col-reverse p-4 sm:bottom-0 sm:right-0 sm:top-auto sm:flex-col md:max-w-[420px]",
+      className
+    )}
+    {...props}
+  />
+))
+ToastViewport.displayName = ToastPrimitives.Viewport.displayName
+
+const toastVariants = cva(
+  "group pointer-events-auto relative flex w-full items-center justify-between space-x-4 overflow-hidden rounded-md border p-6 pr-8 shadow-lg transition-all data-[swipe=cancel]:translate-x-0 data-[swipe=end]:translate-x-[var(--radix-toast-swipe-end-x)] data-[swipe=move]:translate-x-[var(--radix-toast-swipe-move-x)] data-[swipe=move]:transition-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[swipe=end]:animate-out data-[state=closed]:fade-out-80 data-[state=closed]:slide-out-to-right-full data-[state=open]:slide-in-from-top-full data-[state=open]:sm:slide-in-from-bottom-full",
+  {
+    variants: {
+      variant: {
+        default: "border bg-background text-foreground",
+        destructive:
+          "destructive group border-destructive bg-destructive text-destructive-foreground",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+const Toast = React.forwardRef<
+  React.ElementRef<typeof ToastPrimitives.Root>,
+  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Root> &
+    VariantProps<typeof toastVariants>
+>(({ className, variant, ...props }, ref) => {
+  return (
+    <ToastPrimitives.Root
+      ref={ref}
+      className={cn(toastVariants({ variant }), className)}
+      {...props}
+    />
+  )
+})
+Toast.displayName = ToastPrimitives.Root.displayName
+
+const ToastAction = React.forwardRef<
+  React.ElementRef<typeof ToastPrimitives.Action>,
+  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Action>
+>(({ className, ...props }, ref) => (
+  <ToastPrimitives.Action
+    ref={ref}
+    className={cn(
+      "inline-flex h-8 shrink-0 items-center justify-center rounded-md border bg-transparent px-3 text-sm font-medium ring-offset-background transition-colors hover:bg-secondary focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 group-[.destructive]:border-muted/40 group-[.destructive]:hover:border-destructive/30 group-[.destructive]:hover:bg-destructive group-[.destructive]:hover:text-destructive-foreground group-[.destructive]:focus:ring-destructive",
+      className
+    )}
+    {...props}
+  />
+))
+ToastAction.displayName = ToastPrimitives.Action.displayName
+
+const ToastClose = React.forwardRef<
+  React.ElementRef<typeof ToastPrimitives.Close>,
+  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Close>
+>(({ className, ...props }, ref) => (
+  <ToastPrimitives.Close
+    ref={ref}
+    className={cn(
+      "absolute right-2 top-2 rounded-md p-1 text-foreground/50 opacity-0 transition-opacity hover:text-foreground focus:opacity-100 focus:outline-none focus:ring-2 group-hover:opacity-100 group-[.destructive]:text-red-300 group-[.destructive]:hover:text-red-50 group-[.destructive]:focus:ring-red-400 group-[.destructive]:focus:ring-offset-red-600",
+      className
+    )}
+    toast-close=""
+    {...props}
+  >
+    <X className="h-4 w-4" />
+  </ToastPrimitives.Close>
+))
+ToastClose.displayName = ToastPrimitives.Close.displayName
+
+const ToastTitle = React.forwardRef<
+  React.ElementRef<typeof ToastPrimitives.Title>,
+  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Title>
+>(({ className, ...props }, ref) => (
+  <ToastPrimitives.Title
+    ref={ref}
+    className={cn("text-sm font-semibold", className)}
+    {...props}
+  />
+))
+ToastTitle.displayName = ToastPrimitives.Title.displayName
+
+const ToastDescription = React.forwardRef<
+  React.ElementRef<typeof ToastPrimitives.Description>,
+  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Description>
+>(({ className, ...props }, ref) => (
+  <ToastPrimitives.Description
+    ref={ref}
+    className={cn("text-sm opacity-90", className)}
+    {...props}
+  />
+))
+ToastDescription.displayName = ToastPrimitives.Description.displayName
+
+type ToastProps = React.ComponentPropsWithoutRef<typeof Toast>
+
+type ToastActionElement = React.ReactElement<typeof ToastAction>
+
+export {
+  type ToastProps,
+  type ToastActionElement,
+  ToastProvider,
+  ToastViewport,
+  Toast,
+  ToastTitle,
+  ToastDescription,
+  ToastClose,
+  ToastAction,
+}

examples/todo/src/basicComponents/ui/toaster.tsx

@@ -0,0 +1,33 @@
+import {
+  Toast,
+  ToastClose,
+  ToastDescription,
+  ToastProvider,
+  ToastTitle,
+  ToastViewport,
+} from "@/basicComponents/ui/toast"
+import { useToast } from "@/basicComponents/ui/use-toast"
+
+export function Toaster() {
+  const { toasts } = useToast()
+
+  return (
+    <ToastProvider>
+      {toasts.map(function ({ id, title, description, action, ...props }) {
+        return (
+          <Toast key={id} {...props}>
+            <div className="grid gap-1">
+              {title && <ToastTitle>{title}</ToastTitle>}
+              {description && (
+                <ToastDescription>{description}</ToastDescription>
+              )}
+            </div>
+            {action}
+            <ToastClose />
+          </Toast>
+        )
+      })}
+      <ToastViewport />
+    </ToastProvider>
+  )
+}

examples/todo/src/basicComponents/ui/use-toast.ts

@@ -0,0 +1,192 @@
+// Inspired by react-hot-toast library
+import * as React from "react"
+
+import type {
+  ToastActionElement,
+  ToastProps,
+} from "@/basicComponents/ui/toast"
+
+const TOAST_LIMIT = 1
+const TOAST_REMOVE_DELAY = 1000000
+
+type ToasterToast = ToastProps & {
+  id: string
+  title?: React.ReactNode
+  description?: React.ReactNode
+  action?: ToastActionElement
+}
+
+const actionTypes = {
+  ADD_TOAST: "ADD_TOAST",
+  UPDATE_TOAST: "UPDATE_TOAST",
+  DISMISS_TOAST: "DISMISS_TOAST",
+  REMOVE_TOAST: "REMOVE_TOAST",
+} as const
+
+let count = 0
+
+function genId() {
+  count = (count + 1) % Number.MAX_VALUE
+  return count.toString()
+}
+
+type ActionType = typeof actionTypes
+
+type Action =
+  | {
+      type: ActionType["ADD_TOAST"]
+      toast: ToasterToast
+    }
+  | {
+      type: ActionType["UPDATE_TOAST"]
+      toast: Partial<ToasterToast>
+    }
+  | {
+      type: ActionType["DISMISS_TOAST"]
+      toastId?: ToasterToast["id"]
+    }
+  | {
+      type: ActionType["REMOVE_TOAST"]
+      toastId?: ToasterToast["id"]
+    }
+
+interface State {
+  toasts: ToasterToast[]
+}
+
+const toastTimeouts = new Map<string, ReturnType<typeof setTimeout>>()
+
+const addToRemoveQueue = (toastId: string) => {
+  if (toastTimeouts.has(toastId)) {
+    return
+  }
+
+  const timeout = setTimeout(() => {
+    toastTimeouts.delete(toastId)
+    dispatch({
+      type: "REMOVE_TOAST",
+      toastId: toastId,
+    })
+  }, TOAST_REMOVE_DELAY)
+
+  toastTimeouts.set(toastId, timeout)
+}
+
+export const reducer = (state: State, action: Action): State => {
+  switch (action.type) {
+    case "ADD_TOAST":
+      return {
+        ...state,
+        toasts: [action.toast, ...state.toasts].slice(0, TOAST_LIMIT),
+      }
+
+    case "UPDATE_TOAST":
+      return {
+        ...state,
+        toasts: state.toasts.map((t) =>
+          t.id === action.toast.id ? { ...t, ...action.toast } : t
+        ),
+      }
+
+    case "DISMISS_TOAST": {
+      const { toastId } = action
+
+      // ! Side effects ! - This could be extracted into a dismissToast() action,
+      // but I'll keep it here for simplicity
+      if (toastId) {
+        addToRemoveQueue(toastId)
+      } else {
+        state.toasts.forEach((toast) => {
+          addToRemoveQueue(toast.id)
+        })
+      }
+
+      return {
+        ...state,
+        toasts: state.toasts.map((t) =>
+          t.id === toastId || toastId === undefined
+            ? {
+                ...t,
+                open: false,
+              }
+            : t
+        ),
+      }
+    }
+    case "REMOVE_TOAST":
+      if (action.toastId === undefined) {
+        return {
+          ...state,
+          toasts: [],
+        }
+      }
+      return {
+        ...state,
+        toasts: state.toasts.filter((t) => t.id !== action.toastId),
+      }
+  }
+}
+
+const listeners: Array<(state: State) => void> = []
+
+let memoryState: State = { toasts: [] }
+
+function dispatch(action: Action) {
+  memoryState = reducer(memoryState, action)
+  listeners.forEach((listener) => {
+    listener(memoryState)
+  })
+}
+
+type Toast = Omit<ToasterToast, "id">
+
+function toast({ ...props }: Toast) {
+  const id = genId()
+
+  const update = (props: ToasterToast) =>
+    dispatch({
+      type: "UPDATE_TOAST",
+      toast: { ...props, id },
+    })
+  const dismiss = () => dispatch({ type: "DISMISS_TOAST", toastId: id })
+
+  dispatch({
+    type: "ADD_TOAST",
+    toast: {
+      ...props,
+      id,
+      open: true,
+      onOpenChange: (open) => {
+        if (!open) dismiss()
+      },
+    },
+  })
+
+  return {
+    id: id,
+    dismiss,
+    update,
+  }
+}
+
+function useToast() {
+  const [state, setState] = React.useState<State>(memoryState)
+
+  React.useEffect(() => {
+    listeners.push(setState)
+    return () => {
+      const index = listeners.indexOf(setState)
+      if (index > -1) {
+        listeners.splice(index, 1)
+      }
+    }
+  }, [state])
+
+  return {
+    ...state,
+    toast,
+    dismiss: (toastId?: string) => dispatch({ type: "DISMISS_TOAST", toastId }),
+  }
+}
+
+export { useToast, toast }

examples/todo/src/components/Auth.tsx

@@ -0,0 +1,48 @@
+import { useState } from "react";
+
+import { LocalAuthComponent } from "jazz-react-auth-local";
+
+import { Input, Button } from "../basicComponents";
+
+export const PrettyAuthUI: LocalAuthComponent = ({
+    loading,
+    logIn,
+    signUp,
+}) => {
+    const [username, setUsername] = useState<string>("");
+
+    return (
+        <div className="w-full h-full flex items-center justify-center p-5">
+            {loading ? (
+                <div>Loading...</div>
+            ) : (
+                <div className="w-72 flex flex-col gap-4">
+                    <form
+                        className="w-72 flex flex-col gap-2"
+                        onSubmit={(e) => {
+                            e.preventDefault();
+                            signUp(username);
+                        }}
+                    >
+                        <Input
+                            placeholder="Display name"
+                            value={username}
+                            onChange={(e) => setUsername(e.target.value)}
+                            autoComplete="webauthn"
+                            className="text-base"
+                        />
+                        <Button asChild>
+                            <Input
+                                type="submit"
+                                value="Sign Up as new account"
+                            />
+                        </Button>
+                    </form>
+                    <Button onClick={logIn}>
+                        Log In with existing account
+                    </Button>
+                </div>
+            )}
+        </div>
+    );
+};

examples/todo/src/components/InviteButton.tsx

@@ -0,0 +1,45 @@
+import { useState } from "react";
+
+import QRCode from "qrcode";
+
+import { useToast, Button } from "../basicComponents";
+import { CoValue } from "cojson";
+import { Resolved, createInviteLink } from "jazz-react";
+
+export function InviteButton<T extends CoValue>({ value }: { value?: Resolved<T> }) {
+    const [existingInviteLink, setExistingInviteLink] = useState<string>();
+    const { toast } = useToast();
+
+    return (
+        value?.meta.group?.myRole() === "admin" && (
+            <Button
+                size="sm"
+                className="py-0"
+                disabled={!value.meta.group || !value.id}
+                variant="outline"
+                onClick={async () => {
+                    let inviteLink = existingInviteLink;
+                    if (value.meta.group && value.id && !inviteLink) {
+                        inviteLink = createInviteLink(value, "writer");
+                        setExistingInviteLink(inviteLink);
+                    }
+                    if (inviteLink) {
+                        const qr = await QRCode.toDataURL(inviteLink, {
+                            errorCorrectionLevel: "L",
+                        });
+                        navigator.clipboard.writeText(inviteLink).then(() =>
+                            toast({
+                                title: "Copied invite link to clipboard!",
+                                description: (
+                                    <img src={qr} className="w-20 h-20" />
+                                ),
+                            })
+                        );
+                    }
+                }}
+            >
+                Invite
+            </Button>
+        )
+    );
+}

examples/todo/src/index.css

@@ -1,12 +1,7 @@
 @tailwind base;
 @tailwind components;
 @tailwind utilities;
-
-:root, body, #root {
-  width: 100%;
-  height: 100%;
-}
-
+ 
 @layer base {
   :root {
     --background: 0 0% 100%;
@@ -14,63 +9,63 @@
 
     --card: 0 0% 100%;
     --card-foreground: 20 14.3% 4.1%;
-
+ 
     --popover: 0 0% 100%;
     --popover-foreground: 20 14.3% 4.1%;
-
+ 
     --primary: 24 9.8% 10%;
     --primary-foreground: 60 9.1% 97.8%;
-
+ 
     --secondary: 60 4.8% 95.9%;
     --secondary-foreground: 24 9.8% 10%;
-
+ 
     --muted: 60 4.8% 95.9%;
     --muted-foreground: 25 5.3% 44.7%;
-
+ 
     --accent: 60 4.8% 95.9%;
     --accent-foreground: 24 9.8% 10%;
-
+ 
     --destructive: 0 84.2% 60.2%;
     --destructive-foreground: 60 9.1% 97.8%;
 
     --border: 20 5.9% 90%;
     --input: 20 5.9% 90%;
     --ring: 20 14.3% 4.1%;
-
+ 
     --radius: 0.5rem;
   }
-
+ 
   .dark {
     --background: 20 14.3% 4.1%;
     --foreground: 60 9.1% 97.8%;
-
+ 
     --card: 20 14.3% 4.1%;
     --card-foreground: 60 9.1% 97.8%;
-
+ 
     --popover: 20 14.3% 4.1%;
     --popover-foreground: 60 9.1% 97.8%;
-
+ 
     --primary: 60 9.1% 97.8%;
     --primary-foreground: 24 9.8% 10%;
-
+ 
     --secondary: 12 6.5% 15.1%;
     --secondary-foreground: 60 9.1% 97.8%;
-
+ 
     --muted: 12 6.5% 15.1%;
     --muted-foreground: 24 5.4% 63.9%;
-
+ 
     --accent: 12 6.5% 15.1%;
     --accent-foreground: 60 9.1% 97.8%;
-
+ 
     --destructive: 0 62.8% 30.6%;
     --destructive-foreground: 60 9.1% 97.8%;
-
+ 
     --border: 12 6.5% 15.1%;
     --input: 12 6.5% 15.1%;
     --ring: 24 5.7% 82.9%;
   }
 }
-
+ 
 @layer base {
   * {
     @apply border-border;

examples/todo/src/main.tsx

@@ -1,35 +0,0 @@
-import React from "react";
-import ReactDOM from "react-dom/client";
-
-import { WithJazz } from "jazz-react";
-import { LocalAuth } from "jazz-react-auth-local";
-
-import { PrettyAuthComponent } from "./components/prettyAuth.tsx";
-import { ThemeProvider } from "./components/themeProvider.tsx";
-import { Toaster } from "./components/ui/toaster.tsx";
-import App from "./App.tsx";
-import "./index.css";
-
-ReactDOM.createRoot(document.getElementById("root")!).render(
-    <React.StrictMode>
-        <ThemeProvider>
-            <div className="flex items-center gap-2 justify-center mt-5">
-                <img src="jazz-logo.png" className="h-5" /> Jazz Todo List
-                Example
-            </div>
-            <WithJazz
-                auth={LocalAuth({
-                    appName: "Jazz Todo List Example",
-                    Component: PrettyAuthComponent,
-                })}
-                syncAddress={
-                    new URLSearchParams(window.location.search).get("sync") ||
-                    undefined
-                }
-            >
-                <App />
-                <Toaster />
-            </WithJazz>
-        </ThemeProvider>
-    </React.StrictMode>
-);

examples/twit/.eslintrc.cjs

@@ -0,0 +1,18 @@
+module.exports = {
+  root: true,
+  env: { browser: true, es2020: true },
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:react-hooks/recommended',
+  ],
+  ignorePatterns: ['dist', '.eslintrc.cjs'],
+  parser: '@typescript-eslint/parser',
+  plugins: ['react-refresh'],
+  rules: {
+    'react-refresh/only-export-components': [
+      'warn',
+      { allowConstantExport: true },
+    ],
+  },
+}

examples/twit/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

examples/twit/.prettierrc

@@ -0,0 +1,11 @@
+{
+  "printWidth": 120,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "none",
+  "bracketSpacing": true,
+  "jsxBracketSameLine": false,
+  "arrowParens": "avoid"
+}

examples/twit/Dockerfile

@@ -0,0 +1,4 @@
+FROM caddy:2.7.3-alpine
+LABEL org.opencontainers.image.source="https://github.com/gardencmp/jazz"
+
+COPY ./dist /usr/share/caddy/

examples/twit/README.md

@@ -0,0 +1,64 @@
+# Jazz Todo List Example
+
+Live version: https://example-todo.jazz.tools
+
+## Installing & running the example locally
+
+Start by checking out just the example app to a folder:
+
+```bash
+npx degit gardencmp/jazz/examples/todo jazz-example-todo
+cd jazz-example-todo
+```
+
+(This ensures that you have the example app without git history or our multi-package monorepo)
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Start the dev server:
+
+```bash
+npm run dev
+```
+
+## Structure
+
+- [`src/basicComponents`](./src/basicComponents): simple components to build the UI, unrelated to Jazz (uses [shadcn/ui](https://ui.shadcn.com))
+- [`src/components`](./src/components/): helper components that do contain Jazz-specific logic, but aren't very relevant to understand the basics of Jazz and CoJSON
+- [`src/1_types.ts`](./src/1_types.ts),
+[`src/2_main.tsx`](./src/2_main.tsx),
+[`src/3_NewProjectForm.tsx`](./src/3_NewProjectForm.tsx),
+[`src/4_ProjectTodoTable.tsx`](./src/4_ProjectTodoTable.tsx): the main files for this example, see the walkthrough below
+
+## Walkthrough
+
+### Main parts
+
+1. Defining the data model with CoJSON: [`src/1_types.ts`](./src/1_types.ts)
+
+2. The top-level provider `<WithJazz/>` and routing: [`src/2_main.tsx`](./src/2_main.tsx)
+
+3. Creating a new todo project: [`src/3_NewProjectForm.tsx`](./src/3_NewProjectForm.tsx)
+
+4. Reactively rendering a todo project as a table, adding and editing tasks: [`src/4_ProjectTodoTable.tsx`](./src/4_ProjectTodoTable.tsx)
+
+### Helpers
+
+- (not yet explained) Creating invite links/QR codes with `<InviteButton/>`: [`src/components/InviteButton.tsx`](./src/components/InviteButton.tsx)
+
+This is the whole Todo List app!
+
+## Questions / problems / feedback
+
+If you have feedback, let us know on [Discord](https://discord.gg/utDMjHYg42) or open an issue or PR to fix something that seems wrong.
+
+
+## Configuration: sync server
+
+By default, the example app uses [Jazz Global Mesh](https://jazz.tools/mesh) (`wss://sync.jazz.tools`) - so cross-device use, invites and collaboration should just work.
+
+You can also run a local sync server by running `npx cojson-simple-sync` and adding the query param `?sync=ws://localhost:4200` to the URL of the example app (for example: `http://localhost:5173/?sync=ws://localhost:4200`), or by setting the `sync` parameter of the `<WithJazz>` provider component in [./src/2_main.tsx](./src/2_main.tsx).

examples/twit/components.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "default",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.js",
+    "css": "src/index.css",
+    "baseColor": "stone",
+    "cssVariables": true
+  },
+  "aliases": {
+    "components": "@/basicComponents",
+    "utils": "@/basicComponents/lib/utils"
+  }
+}

examples/twit/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/png" href="/jazz-logo.png" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Twit</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/2_main.tsx"></script>
+  </body>
+</html>

examples/twit/job-template.nomad

@@ -0,0 +1,56 @@
+job "twit$BRANCH_SUFFIX" {
+  region     = "global"
+  datacenters = ["*"]
+
+  group "static" {
+    count = 8
+
+    network {
+      port "http" {
+        to = 80
+      }
+    }
+
+    constraint {
+      attribute = "${node.class}"
+      operator  = "="
+      value     = "mesh"
+    }
+
+    spread {
+      attribute = "${node.datacenter}"
+      weight    = 100
+    }
+
+    constraint {
+      distinct_hosts = true
+    }
+
+    task "server" {
+      driver = "docker"
+
+      config {
+        image = "$DOCKER_TAG"
+        ports = ["http"]
+
+        auth = {
+          username = "$DOCKER_USER"
+          password = "$DOCKER_PASSWORD"
+        }
+      }
+
+      service {
+        tags = ["public"]
+        name = "twit$BRANCH_SUFFIX"
+        port = "http"
+        provider = "consul"
+      }
+
+      resources {
+        cpu    = 50 # MHz
+        memory = 50 # MB
+      }
+    }
+  }
+}
+# deploy bump 4

examples/twit/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "jazz-example-twit",
+  "private": true,
+  "version": "0.0.6",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@radix-ui/react-checkbox": "^1.0.4",
+    "@radix-ui/react-popover": "^1.0.7",
+    "@radix-ui/react-slot": "^1.0.2",
+    "@radix-ui/react-toast": "^1.1.4",
+    "@types/qrcode": "^1.5.1",
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.0.0",
+    "javascript-time-ago": "^2.5.9",
+    "jazz-browser-media-images": "^0.4.7",
+    "jazz-react": "^0.4.6",
+    "jazz-react-auth-local": "^0.4.6",
+    "lucide-react": "^0.274.0",
+    "qrcode": "^1.5.3",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-router": "^6.16.0",
+    "react-router-dom": "^6.16.0",
+    "react-time-ago": "^7.2.1",
+    "tailwind-merge": "^1.14.0",
+    "tailwindcss-animate": "^1.0.7",
+    "uniqolor": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.15",
+    "@types/react-dom": "^18.2.7",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "@vitejs/plugin-react-swc": "^3.3.2",
+    "autoprefixer": "^10.4.14",
+    "eslint": "^8.45.0",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-react-refresh": "^0.4.3",
+    "postcss": "^8.4.27",
+    "tailwindcss": "^3.3.3",
+    "typescript": "^5.0.2",
+    "vite": "^4.4.5"
+  }
+}

examples/twit/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

examples/twit/src/1_dataModel.ts

@@ -0,0 +1,64 @@
+import { CoMap, CoList, Media, CoStream, Group, AccountMigration, EVERYONE, Profile } from 'cojson';
+
+export type Twit = CoMap<{
+  text?: string;
+  images?: ListOfImages['id'];
+  likes: LikeStream['id'];
+  replies: ReplyStream['id'];
+  isReplyTo?: Twit['id'];
+}>;
+
+export type ListOfImages = CoList<Media.ImageDefinition['id']>;
+export type LikeStream = CoStream<'❤️' | null>;
+export type ReplyStream = CoStream<Twit['id']>;
+
+export type ListOfTwits = CoList<Twit['id']>;
+export type ListOfProfiles = CoList<TwitProfile['id']>;
+export type StreamOfFollowers = CoStream<TwitProfile['id'] | null>;
+
+export type TwitProfile = Profile<
+  {
+    name: string;
+    bio: string;
+    avatar?: Media.ImageDefinition['id'];
+    twits: ListOfTwits['id'];
+    following: ListOfProfiles['id'];
+    followers: StreamOfFollowers['id'];
+    twitStyle?: { fontFamily: string; color: string };
+  }
+>;
+
+export type TwitAccountRoot = CoMap<{
+  peopleWhoCanSeeMyTwits: Group['id'];
+  peopleWhoCanSeeMyFollows: Group['id'];
+  peopleWhoCanFollowMe: Group['id'];
+  peopleWhoCanInteractWithMe: Group['id'];
+}>;
+
+export const migration: AccountMigration<TwitProfile, TwitAccountRoot> = (account, profile) => {
+  if (!account.get('root')) {
+    const peopleWhoCanSeeMyTwits = account.createGroup();
+    const peopleWhoCanSeeMyFollows = account.createGroup();
+    const peopleWhoCanFollowMe = account.createGroup();
+    const peopleWhoCanInteractWithMe = account.createGroup();
+
+    peopleWhoCanFollowMe?.addMember(EVERYONE, 'writer');
+    peopleWhoCanSeeMyTwits?.addMember(EVERYONE, 'reader');
+    peopleWhoCanSeeMyFollows?.addMember(EVERYONE, 'reader');
+    peopleWhoCanInteractWithMe?.addMember(EVERYONE, 'writer');
+
+    const root = account.createMap<TwitAccountRoot>({
+      peopleWhoCanSeeMyTwits: peopleWhoCanSeeMyTwits.id,
+      peopleWhoCanSeeMyFollows: peopleWhoCanSeeMyFollows.id,
+      peopleWhoCanFollowMe: peopleWhoCanFollowMe.id,
+      peopleWhoCanInteractWithMe: peopleWhoCanInteractWithMe.id
+    });
+
+    account.set('root', root.id);
+
+    profile.set('twits', peopleWhoCanSeeMyTwits.createList<ListOfTwits>().id, 'trusting');
+    profile.set('following', peopleWhoCanSeeMyFollows.createList<ListOfProfiles>().id, 'trusting');
+    profile.set('followers', peopleWhoCanFollowMe.createStream<StreamOfFollowers>().id, 'trusting');
+    console.log('MIGRATION SUCCESSFUL!');
+  }
+};

examples/twit/src/2_main.tsx

@@ -0,0 +1,71 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { RouterProvider, createHashRouter } from 'react-router-dom';
+import './index.css';
+
+import { AccountMigration } from 'cojson';
+import { WithJazz, useJazz } from 'jazz-react';
+import { LocalAuth } from 'jazz-react-auth-local';
+
+import { Button, ThemeProvider, TitleAndLogo } from './basicComponents/index.tsx';
+import { PrettyAuthUI } from './components/Auth.tsx';
+
+import { migration } from './1_dataModel.ts';
+import { ChronoFeed } from './3_ChronoFeed.tsx';
+import { ProfilePage } from './5_ProfilePage.tsx';
+
+const appName = 'Jazz Twit Example';
+
+const auth = LocalAuth({
+  appName,
+  Component: PrettyAuthUI
+});
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <ThemeProvider>
+      <TitleAndLogo name={appName} />
+      <div className="flex flex-col h-full items-stretch justify-start gap-10 pt-10 pb-10 px-5 w-full max-w-xl mx-auto">
+        <WithJazz auth={auth} migration={migration as AccountMigration}>
+          <App />
+        </WithJazz>
+      </div>
+    </ThemeProvider>
+  </React.StrictMode>
+);
+
+function App() {
+  const { me, logOut } = useJazz();
+
+  const router = createHashRouter([
+    {
+      path: '/',
+      element: <ChronoFeed />
+    },
+    {
+      path: '/:profileId',
+      element: <ProfilePage />
+    },
+    {
+      path: '/me',
+      loader: () => router.navigate('/' + me.profile?.id)
+    }
+  ]);
+
+  return (
+    <>
+      <div className="flex gap-2">
+        <Button onClick={() => router.navigate('/')} variant="link" className="-ml-3">
+          Home
+        </Button>
+        <Button onClick={() => router.navigate('/me')} variant="link" className="ml-auto">
+          My Profile
+        </Button>
+        <Button onClick={() => router.navigate('/').then(logOut)} variant="outline">
+          Log Out
+        </Button>
+      </div>
+      <RouterProvider router={router} />
+    </>
+  );
+}

examples/twit/src/3_ChronoFeed.tsx

@@ -0,0 +1,35 @@
+import { useMemo } from 'react';
+import { useJazz } from 'jazz-react';
+import { TwitAccountRoot, TwitProfile } from './1_dataModel.ts';
+import { CreateTwitForm } from './6_CreateTwitForm.tsx';
+import { TwitComponent } from './4_TwitComponent.tsx';
+import { MainH1 } from './basicComponents/index.tsx';
+
+export function ChronoFeed() {
+  const { me } = useJazz<TwitProfile, TwitAccountRoot>();
+
+  const myTwits = me.profile?.twits;
+
+  const twitsFromFollows = useMemo(
+    () => me.profile?.following?.flatMap(follow => follow?.twits || []) || [],
+    [me.profile?.following]
+  );
+
+  const allTwitsSorted = useMemo(
+    () =>
+      [...(myTwits || []), ...twitsFromFollows]
+        .flatMap(tw => (tw ? (tw.isReplyTo ? [] : tw) : []))
+        .sort((a, b) => (b.meta.edits.text?.at?.getTime() || 0) - (a.meta.edits.text?.at?.getTime() || 0)),
+    [myTwits, twitsFromFollows]
+  );
+
+  return (
+    <div className="flex flex-col items-stretch">
+      <CreateTwitForm className="mb-10" />
+      <MainH1>From people you follow</MainH1>
+      {allTwitsSorted?.map(twit => (
+        <TwitComponent twit={twit} key={twit.id} />
+      ))}
+    </div>
+  );
+}

examples/twit/src/4_TwitComponent.tsx

@@ -0,0 +1,101 @@
+import React from 'react';
+import { Link } from 'react-router-dom';
+import {
+  ButtonWithCount,
+  ProfilePicImg,
+  ReactionsContainer,
+  RepliesContainer,
+  SubtleRelativeTimeAgo,
+  TwitContainer,
+  TwitWithRepliesContainer,
+  TwitImg,
+  TwitImgGallery,
+  TwitHeader,
+  TwitBody,
+  TwitText,
+} from './basicComponents/index.tsx';
+import { Twit, TwitProfile } from './1_dataModel.ts';
+import { BrowserImage } from 'jazz-browser-media-images';
+import { HeartIcon, MessagesSquareIcon } from 'lucide-react';
+import { CreateTwitForm } from './6_CreateTwitForm.tsx';
+import { Resolved } from 'jazz-react';
+
+export function TwitComponent({
+  twit,
+  alreadyInReplies: alreadyInReplies
+}: {
+  twit?: Resolved<Twit>;
+  alreadyInReplies?: boolean;
+}) {
+  const [showReplyForm, setShowReplyForm] = React.useState(false);
+
+  const posterProfile = twit?.meta.edits.text?.by?.profile as Resolved<TwitProfile> | undefined;
+  const isTopLevel = !twit?.isReplyTo || alreadyInReplies;
+
+  return (
+    <TwitWithRepliesContainer isTopLevel={isTopLevel}>
+      <TwitContainer>
+        <ProfilePicImg
+          src={posterProfile?.avatar?.as(BrowserImage)?.highestResSrcOrPlaceholder}
+          linkTo={'/' + posterProfile?.id}
+          initial={posterProfile?.name[0]}
+          size={twit?.isReplyTo && "sm"}
+        />
+
+        <TwitBody>
+          <TwitHeader>
+            <Link to={'/' + posterProfile?.id} className="font-bold hover:underline">
+              {posterProfile?.name}
+            </Link>
+            <SubtleRelativeTimeAgo dateTime={twit?.meta.edits.text?.at} />
+          </TwitHeader>
+
+          <TwitText style={posterProfile?.twitStyle}>
+            {/* This is where the tweet text goes */}
+            {twit?.text}
+          </TwitText>
+
+          {twit?.images && (
+            <TwitImgGallery>
+              {twit.images.map(image => (
+                <TwitImg src={image?.as(BrowserImage)?.highestResSrcOrPlaceholder} key={image?.id} />
+              ))}
+            </TwitImgGallery>
+          )}
+
+          <ReactionsContainer>
+            <ButtonWithCount
+              active={twit?.likes?.me?.last === '❤️'}
+              onClick={() => twit?.likes?.push(twit?.likes?.me?.last ? null : '❤️')}
+              count={twit?.likes?.perAccount.filter(([, liked]) => liked.last === '❤️').length || 0}
+              icon={<HeartIcon size="18" />}
+              activeIcon={<HeartIcon color="red" size="18" fill="red" />}
+            />
+            <ButtonWithCount
+              onClick={() => setShowReplyForm(s => !s)}
+              count={twit?.replies?.perAccount.flatMap(([, byAccount]) => byAccount.all).length || 0}
+              icon={<MessagesSquareIcon size="18" />}
+            />
+          </ReactionsContainer>
+        </TwitBody>
+      </TwitContainer>
+
+      <RepliesContainer>
+        {showReplyForm && (
+          <CreateTwitForm
+            inReplyTo={twit}
+            onSubmit={() => setShowReplyForm(false)}
+            className={'mt-5 ' + (isTopLevel ? 'ml-14' : 'ml-12')}
+          />
+        )}
+
+        {twit?.replies?.perAccount
+          .flatMap(([, byAccount]) => byAccount.all)
+          .sort((a, b) => b.at.getTime() - a.at.getTime())
+          .map(replyEntry => (
+            <TwitComponent twit={replyEntry.value} key={replyEntry.value?.id} alreadyInReplies={!!twit?.isReplyTo} />
+          ))}
+      </RepliesContainer>
+    </TwitWithRepliesContainer>
+  );
+}

examples/twit/src/5_ProfilePage.tsx

@@ -0,0 +1,127 @@
+import { useEffect, useMemo, useState } from 'react';
+import { useParams } from 'react-router-dom';
+import { useJazz, useAutoSub } from 'jazz-react';
+import QRCode from 'qrcode';
+import {
+  BioInput,
+  ChooseProfilePicInput,
+  FollowerStatsContainer,
+  Popover,
+  ProfileName,
+  ProfilePicImg,
+  ProfileTitleContainer,
+  SmallInlineButton
+} from './basicComponents/index.tsx';
+import { TwitAccountRoot, TwitProfile } from './1_dataModel.ts';
+import { CoID } from 'cojson';
+import { BrowserImage, createImage } from 'jazz-browser-media-images';
+import { FollowButton, FollowerList, FollowingList } from './7_FollowStuff.tsx';
+import { CreateTwitForm } from './6_CreateTwitForm.tsx';
+import { TwitComponent } from './4_TwitComponent.tsx';
+import { PopoverContent, PopoverTrigger } from '@radix-ui/react-popover';
+
+export function ProfilePage() {
+  const { profileId } = useParams<{ profileId: CoID<TwitProfile> }>();
+  const { me } = useJazz<TwitProfile, TwitAccountRoot>();
+
+  const profile = useAutoSub(profileId);
+  const isMe = profile?.id == me.profile?.id;
+
+  const profileTwitsAndRepliedToTwits = useMemo(() => {
+    return profile?.twits?.map((twit, _, allTwits) =>
+      twit?.isReplyTo
+        ? allTwits.some(
+            tw =>
+              tw?.id === twit?.isReplyTo?.id ||
+              tw?.id === twit?.isReplyTo?.isReplyTo?.id ||
+              tw?.id === twit?.isReplyTo?.isReplyTo?.isReplyTo?.id
+          )
+          ? null
+          : twit?.isReplyTo
+        : twit
+    );
+  }, [profile?.twits]);
+
+  const [qr, setQr] = useState<string>('');
+  useEffect(() => {
+    QRCode.toDataURL(
+      window.location.protocol + '//' + window.location.host + window.location.pathname + '#/' + profile?.id,
+      {
+        errorCorrectionLevel: 'L'
+      }
+    ).then(setQr);
+  }, [profile?.id]);
+
+  return (
+    <div>
+      <div className="py-2 mb-5 flex gap-4">
+        <div className="flex flex-col items-stretch">
+          <ProfilePicImg
+            src={profile?.avatar?.as(BrowserImage)?.highestResSrcOrPlaceholder}
+            initial={profile?.name[0]}
+            size="xxl"
+          />
+          {isMe && (
+            <ChooseProfilePicInput
+              onChange={(file: File) =>
+                me.root?.peopleWhoCanSeeMyTwits &&
+                createImage(file, me.root.peopleWhoCanSeeMyTwits, 256).then(image => {
+                  me.profile?.set({ avatar: image.id }, 'trusting');
+                })
+              }
+            />
+          )}
+        </div>
+        <div className="grow">
+          <ProfileTitleContainer>
+            <ProfileName>{profile?.name}</ProfileName>
+            {!isMe && <FollowButton profile={profile} />}
+          </ProfileTitleContainer>
+
+          <div>
+            {isMe ? (
+              <BioInput
+                value={profile?.bio}
+                onChange={newBio => {
+                  profile?.set({ bio: newBio }, 'trusting');
+                  // prettier-ignore
+                  if (newBio.startsWith('{')) { profile?.set('twitStyle', JSON.parse(newBio), 'trusting'); } else { profile?.set('twitStyle', undefined, 'trusting'); }
+                }}
+              />
+            ) : (
+              profile?.bio || '(No bio)'
+            )}
+          </div>
+
+          <FollowerStatsContainer>
+            <Popover>
+              <PopoverTrigger>
+                <SmallInlineButton>
+                  {profile?.followers?.perAccount?.filter(([, status]) => status.last).length} Followers
+                </SmallInlineButton>
+              </PopoverTrigger>
+              <PopoverContent>
+                <FollowerList profile={profile} />
+              </PopoverContent>
+            </Popover>
+            <span className="hidden md:block">&mdash;</span> <br className="md:hidden" />
+            <Popover>
+              <PopoverTrigger>
+                <SmallInlineButton>{new Set(profile?.following || []).size} Following</SmallInlineButton>
+              </PopoverTrigger>
+              <PopoverContent>
+                <FollowingList profile={profile} />
+              </PopoverContent>
+            </Popover>
+          </FollowerStatsContainer>
+        </div>
+
+        {isMe && <img src={qr} className="rounded w-28 h-28 -mr-3 dark:invert max-sm:w-16 max-sm:h-16" />}
+      </div>
+
+      {isMe && <CreateTwitForm className="mb-4" />}
+
+      {profileTwitsAndRepliedToTwits?.map(twit => twit && <TwitComponent twit={twit} key={twit?.id} />)}
+    </div>
+  );
+}

examples/twit/src/6_CreateTwitForm.tsx

@@ -0,0 +1,73 @@
+import React, { useCallback, useEffect } from 'react';
+import { Resolved, useJazz } from 'jazz-react';
+import { AddTwitPicsInput, TwitImg, TwitTextInput } from './basicComponents/index.tsx';
+import { LikeStream, ListOfImages, ReplyStream, Twit, TwitAccountRoot, TwitProfile } from './1_dataModel.ts';
+import { createImage } from 'jazz-browser-media-images';
+
+export function CreateTwitForm(
+  props: {
+    inReplyTo?: Resolved<Twit>;
+    onSubmit?: () => void;
+    className?: string;
+  } = {}
+) {
+  const { me } = useJazz<TwitProfile, TwitAccountRoot>();
+
+  const [pics, setPics] = React.useState<File[]>([]);
+
+  const onSubmit = useCallback(
+    (twitText: string) => {
+      const audience = me.root?.peopleWhoCanSeeMyTwits;
+      const interactors = me.root?.peopleWhoCanInteractWithMe;
+      if (!audience || !interactors) return;
+
+      const twit = audience.createMap<Twit>({
+        text: twitText,
+        likes: interactors.createStream<LikeStream>().id,
+        replies: interactors.createStream<ReplyStream>().id
+      });
+
+      me.profile?.twits?.prepend(twit?.id as Twit['id']);
+
+      if (props.inReplyTo) {
+        props.inReplyTo.replies?.push(twit.id);
+        twit.set({ isReplyTo: props.inReplyTo.id });
+      }
+
+      Promise.all(pics.map(pic => createImage(pic, twit.group, 1024))).then(createdPics => {
+        twit.set({ images: audience.createList<ListOfImages>(createdPics.map(pic => pic.id)).id });
+      });
+
+      setPics([]);
+      props.onSubmit?.();
+    },
+    [me.profile?.twits, me.root?.peopleWhoCanSeeMyTwits, me.root?.peopleWhoCanInteractWithMe, props, pics]
+  );
+
+  const [picPreviews, setPicPreviews] = React.useState<string[]>([]);
+  useEffect(() => {
+    const previews = pics.map(pic => URL.createObjectURL(pic));
+    setPicPreviews(previews);
+    return () => previews.forEach(preview => URL.revokeObjectURL(preview));
+  }, [pics]);
+
+  return (
+    <div className={props.className}>
+      <TwitTextInput onSubmit={onSubmit} submitButtonLabel={props.inReplyTo ? 'Reply!' : 'Twit!'} />
+
+      {picPreviews.length ? (
+        <div className="flex gap-2 mt-2">
+          {picPreviews.map(preview => (
+            <TwitImg src={preview} />
+          ))}
+        </div>
+      ) : (
+        <AddTwitPicsInput
+          onChange={(newPics: File[]) => {
+            setPics(newPics);
+          }}
+        />
+      )}
+    </div>
+  );
+}

examples/twit/src/7_FollowStuff.tsx

@@ -0,0 +1,80 @@
+import { useCallback } from 'react';
+import { Resolved, useJazz } from 'jazz-react';
+import { Button, ProfilePicImg } from './basicComponents/index.tsx';
+import { TwitAccountRoot, TwitProfile } from './1_dataModel.ts';
+import { Link } from 'react-router-dom';
+import { BrowserImage } from 'jazz-browser-media-images';
+
+export function FollowButton({ profile }: { profile?: Resolved<TwitProfile> }) {
+  const { me } = useJazz<TwitProfile, TwitAccountRoot>();
+
+  const alreadyFollowing = profile?.followers?.perAccount?.some(([acc, status]) => acc === me.id && !!status.last);
+  const theyFollowMe = profile?.following?.some(f => f?.id === me.profile?.id);
+
+  const followOrUnfollow = useCallback(() => {
+    if (!profile?.followers || !me.profile?.following) return;
+    if (alreadyFollowing) {
+      me.profile.following.delete(me.profile.following.findIndex(f => f?.id === profile.id));
+      profile.followers.push(null);
+    } else {
+      me.profile.following.append(profile.id);
+      profile.followers.push(me.profile.id);
+    }
+  }, [alreadyFollowing, me.profile, profile]);
+
+  return profile?.id === me.profile?.id ? (
+    <div className="ml-auto text-neutral-500">That's you!</div>
+  ) : (
+    <Button onClick={followOrUnfollow} className="ml-auto" variant={alreadyFollowing ? 'ghost' : 'default'}>
+      {alreadyFollowing ? 'Unfollow' : theyFollowMe ? 'Follow Back' : 'Follow'}
+    </Button>
+  );
+}
+
+export function FollowerList({ profile }: { profile?: Resolved<TwitProfile> }) {
+  return (
+    <div className="flex flex-col gap-4 p-4 bg-background rounded-lg border shadow-lg w-96 max-w-full m-2">
+      {profile?.followers?.perAccount.map(([, followEntry]) => {
+        const followerProfile = followEntry.last;
+        // not following anymore?
+        if (!followerProfile) return null;
+
+        return (
+          <div key={followerProfile.id} className="flex items-center">
+            <ProfilePicImg
+              src={followerProfile?.avatar?.as(BrowserImage)?.highestResSrcOrPlaceholder}
+              linkTo={'/' + followerProfile?.id}
+              initial={followerProfile?.name[0]}
+            />
+            <Link to={'/' + followerProfile?.id} className="font-bold hover:underline">
+              {followerProfile?.name}
+            </Link>
+            <FollowButton profile={followerProfile} />
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+export function FollowingList({ profile }: { profile?: Resolved<TwitProfile> }) {
+  return (
+    <div className="flex flex-col gap-4 p-4 bg-background rounded-lg border shadow-lg w-96 max-w-full m-2">
+      {[...new Set(profile?.following || [])].map(followingProfile => {
+        return (
+          <div key={followingProfile?.id} className="flex items-center">
+            <ProfilePicImg
+              src={followingProfile?.avatar?.as(BrowserImage)?.highestResSrcOrPlaceholder}
+              linkTo={'/' + followingProfile?.id}
+              initial={followingProfile?.name[0]}
+            />
+            <Link to={'/' + followingProfile?.id} className="font-bold hover:underline">
+              {followingProfile?.name}
+            </Link>
+            <FollowButton profile={followingProfile} />
+          </div>
+        );
+      })}
+    </div>
+  );
+}

examples/twit/src/basicComponents/SubmittableInput.tsx

@@ -0,0 +1,39 @@
+import { Input } from "@/basicComponents/ui/input";
+import { Button } from "@/basicComponents/ui/button";
+
+export function SubmittableInput({
+    onSubmit,
+    label,
+    placeholder,
+    disabled,
+}: {
+    onSubmit: (text: string) => void;
+    label: string;
+    placeholder: string;
+    disabled?: boolean;
+}) {
+    return (
+        <form
+            className="flex flex-row items-center gap-3"
+            onSubmit={(e) => {
+                e.preventDefault();
+                const textEl = e.currentTarget.elements.namedItem(
+                    "text"
+                ) as HTMLInputElement;
+                onSubmit(textEl.value);
+                textEl.value = "";
+            }}
+        >
+            <Input
+                className="-ml-3 -my-2 flex-grow flex-3 text-base"
+                name="text"
+                placeholder={placeholder}
+                autoComplete="off"
+                disabled={disabled}
+            />
+            <Button asChild type="submit" className="flex-shrink flex-1 cursor-pointer">
+                <Input type="submit" value={label} disabled={disabled} />
+            </Button>
+        </form>
+    );
+}

examples/twit/src/basicComponents/TitleAndLogo.tsx

@@ -0,0 +1,10 @@
+import { Toaster } from ".";
+
+export function TitleAndLogo({name}: {name: string}) {
+    return <>
+        <div className="flex items-center gap-2 justify-center mt-5">
+                <img src="jazz-logo.png" className="h-5" /> {name}
+            </div>
+            <Toaster />
+    </>
+}

examples/twit/src/basicComponents/index.tsx

@@ -0,0 +1,228 @@
+import ReactTimeAgo from 'react-time-ago';
+import { Button, ButtonProps } from './ui/button';
+export { Button } from './ui/button';
+export { Checkbox } from './ui/checkbox';
+import { Input } from './ui/input';
+import { Link } from 'react-router-dom';
+export { Input } from './ui/input';
+export { Skeleton } from './ui/skeleton';
+export { Toaster } from './ui/toaster';
+export { useToast } from './ui/use-toast';
+export { SubmittableInput } from './SubmittableInput';
+export { TitleAndLogo } from './TitleAndLogo';
+export { ThemeProvider } from './themeProvider';
+export { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from './ui/table';
+export { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from './ui/card';
+export { Popover, PopoverContent, PopoverTrigger } from './ui/popover';
+
+import TimeAgo from 'javascript-time-ago';
+import en from 'javascript-time-ago/locale/en.json';
+TimeAgo.addDefaultLocale(en);
+
+export function BioInput(props: { value?: string; onChange: (value: string) => void }) {
+  return (
+    <Input
+      type="text"
+      value={props.value}
+      autoComplete="off"
+      onChange={e => {
+        props.onChange(e.target.value);
+      }}
+      placeholder="Add a bio..."
+      className="w-full p-2 border rounded max-md:text-base"
+    />
+  );
+}
+
+export function ProfileTitleContainer(props: { children: React.ReactNode }) {
+  return <div className="flex items-baseline">{props.children}</div>;
+}
+
+export function ProfileName(props: { children: React.ReactNode }) {
+  return <h1 className="text-2xl">{props.children}</h1>;
+}
+
+export function FollowerStatsContainer(props: { children: React.ReactNode }) {
+  return <div className="flex gap-2 mt-2 text-neutral-500">{props.children}</div>;
+}
+
+export function ChooseProfilePicInput(props: { onChange: (file: File) => void }) {
+  return (
+    <Button asChild className="mt-2" size="sm" variant="secondary">
+      <label className="cursor-pointer text-xs">
+        Choose Pic
+        <Input
+          type="file"
+          accept="image/*"
+          onChange={e => {
+            e.target.files?.[0] && props.onChange(e.target.files[0]);
+            e.target.value = '';
+          }}
+          className="hidden"
+        />
+      </label>
+    </Button>
+  );
+}
+
+export function ProfilePicImg(props: { src?: string; size?: 'sm' | 'xxl'; linkTo?: string; initial?: string }) {
+  return (
+    <Link to={props.linkTo || ''}>
+      {props.src ? (
+        <img
+          src={props.src}
+          className={
+            'bg-neutral-200 rounded-full mr-2 object-cover shrink-0' +
+            (props.size === 'sm' ? ' w-8 h-8' : props.size === 'xxl' ? ' w-20 h-20' : ' w-10 h-10')
+          }
+        />
+      ) : (
+        <div
+          className={
+            'bg-neutral-200 rounded-full mr-2 object-cover shrink-0 flex items-center justify-center text-neutral-700 ' +
+            (props.size === 'sm'
+              ? ' w-8 h-8 text-[1.5rem]'
+              : props.size === 'xxl'
+              ? ' w-20 h-20 text-[3.75rem]'
+              : ' w-10 h-10 text-[1.875rem]')
+          }
+        >
+          <div className="-mt-[8%]">{props.initial}</div>
+        </div>
+      )}
+    </Link>
+  );
+}
+
+export function SubtleRelativeTimeAgo(props: { dateTime?: Date }) {
+  return (
+    <div className="ml-auto text-neutral-300 text-xs whitespace-nowrap">
+      <ReactTimeAgo date={props.dateTime || 0} />
+    </div>
+  );
+}
+
+export function TwitImg(props: { src?: string }) {
+  return <img src={props.src} className="h-40 rounded object-cover" />;
+}
+
+export function ReactionsContainer(props: { children: React.ReactNode }) {
+  return <div className="flex gap-4 mt-2">{props.children}</div>;
+}
+
+export function RepliesContainer(props: { children: React.ReactNode }) {
+  return <div className="flex flex-col items-stretch gap-2 mt-2">{props.children}</div>;
+}
+
+export function ButtonWithCount(props: {
+  count: number;
+  onClick: () => void;
+  active?: boolean;
+  icon: React.ReactNode;
+  activeIcon?: React.ReactNode;
+}) {
+  return (
+    <div className="flex items-center">
+      <Button
+        className="w-10 h-7 p-1 mr-1"
+        variant={props.active ? 'secondary' : 'outline'}
+        onClick={props.onClick}
+        size="icon"
+      >
+        {props.active ? props.activeIcon : props.icon}
+      </Button>{' '}
+      <span className="tabular-nums">{props.count}</span>
+    </div>
+  );
+}
+
+export function TwitTextInput(props: { onSubmit: (text: string) => void; submitButtonLabel: string }) {
+  return (
+    <form
+      onSubmit={event => {
+        event.preventDefault();
+
+        const form = event.target as HTMLFormElement;
+        const text = form.twitText.value;
+        text && props.onSubmit(text);
+        form.twitText.value = '';
+      }}
+      className="flex gap-2 items-end"
+    >
+      <Input
+        type="text"
+        name="twitText"
+        placeholder="What's happenin'"
+        autoComplete="off"
+        className="p-2 border rounded grow max-md:text-base"
+      />
+      <Button asChild>
+        <input type="submit" value={props.submitButtonLabel} />
+      </Button>
+    </form>
+  );
+}
+
+export function AddTwitPicsInput(props: { onChange: (files: File[]) => void }) {
+  return (
+    <Button asChild className="mt-2" size="sm" variant="secondary">
+      <label className="cursor-pointer text-xs">
+        Add Pics
+        <Input
+          type="file"
+          onChange={e => {
+            props.onChange(Array.from(e.target.files || []));
+          }}
+          className="hidden"
+          accept="image/*"
+          multiple
+        />
+      </label>
+    </Button>
+  );
+}
+
+export function TwitWithRepliesContainer(props: { children: React.ReactNode; isTopLevel?: boolean }) {
+  return (
+    <div className={'py-2 flex flex-col items-stretch' + (props.isTopLevel ? ' border-t' : ' ml-14')}>
+      {props.children}
+    </div>
+  );
+}
+
+export function TwitContainer(props: { children: React.ReactNode }) {
+  return <div className="flex gap-2">{props.children}</div>;
+}
+
+export function TwitBody(props: { children: React.ReactNode }) {
+  return <div className="grow flex flex-col items-stretch">{props.children}</div>;
+}
+
+export function TwitHeader(props: { children: React.ReactNode }) {
+  return <div className="flex items-baseline">{props.children}</div>;
+}
+
+export function TwitImgGallery(props: { children: React.ReactNode }) {
+  return <div className="flex gap-2 mt-2 max-w-full overflow-auto">{props.children}</div>;
+}
+
+export function TwitText(props: { children: React.ReactNode; style?: React.CSSProperties }) {
+  return <div style={props.style}>{props.children}</div>;
+}
+
+export function QuoteContainer(props: { children: React.ReactNode }) {
+  return <div className="border rounded">{props.children}</div>;
+}
+
+export function MainH1(props: { children: React.ReactNode }) {
+  return <h1 className="text-2xl mb-4">{props.children}</h1>;
+}
+
+export function SmallInlineButton(props: { children: React.ReactNode } & ButtonProps) {
+  const {children, ...rest} = props
+  return (
+    <Button variant={'ghost'} className="h-6 px-1 -mx-1" {...rest}>
+      {children}
+    </Button>
+  );
+}

examples/twit/src/basicComponents/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx"
+import { twMerge } from "tailwind-merge"
+ 
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

examples/twit/src/basicComponents/themeProvider.tsx

@@ -0,0 +1,72 @@
+import { createContext, useContext, useEffect, useState } from "react";
+
+type ThemeProviderProps = {
+    children: React.ReactNode;
+    defaultTheme?: string;
+    storageKey?: string;
+};
+
+type ThemeProviderState = {
+    theme: string;
+    setTheme: (theme: string) => void;
+};
+
+const initialState = {
+    theme: "system",
+    setTheme: () => null,
+};
+
+const ThemeProviderContext = createContext<ThemeProviderState>(initialState);
+
+export function ThemeProvider({
+    children,
+    defaultTheme = "system",
+    storageKey = "vite-ui-theme",
+    ...props
+}: ThemeProviderProps) {
+    const [theme, setTheme] = useState(
+        () => localStorage.getItem(storageKey) || defaultTheme
+    );
+
+    useEffect(() => {
+        const root = window.document.documentElement;
+
+        root.classList.remove("light", "dark");
+
+        if (theme === "system") {
+            const systemTheme = window.matchMedia(
+                "(prefers-color-scheme: dark)"
+            ).matches
+                ? "dark"
+                : "light";
+
+            root.classList.add(systemTheme);
+            return;
+        }
+
+        root.classList.add(theme);
+    }, [theme]);
+
+    const value = {
+        theme,
+        setTheme: (theme: string) => {
+            localStorage.setItem(storageKey, theme);
+            setTheme(theme);
+        },
+    };
+
+    return (
+        <ThemeProviderContext.Provider {...props} value={value}>
+            {children}
+        </ThemeProviderContext.Provider>
+    );
+}
+
+export const useTheme = () => {
+    const context = useContext(ThemeProviderContext);
+
+    if (context === undefined)
+        throw new Error("useTheme must be used within a ThemeProvider");
+
+    return context;
+};

examples/twit/src/basicComponents/ui/button.tsx

@@ -0,0 +1,56 @@
+import * as React from "react"
+import { Slot } from "@radix-ui/react-slot"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/basicComponents/lib/utils"
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        outline:
+          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+        lg: "h-11 rounded-md px-8",
+        icon: "h-10 w-10",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button"
+    return (
+      <Comp
+        className={cn(buttonVariants({ variant, size, className }))}
+        ref={ref}
+        {...props}
+      />
+    )
+  }
+)
+Button.displayName = "Button"
+
+export { Button, buttonVariants }

examples/twit/src/basicComponents/ui/card.tsx

@@ -0,0 +1,79 @@
+import * as React from "react"
+
+import { cn } from "@/basicComponents/lib/utils"
+
+const Card = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn(
+      "rounded-lg border bg-card text-card-foreground shadow-sm",
+      className
+    )}
+    {...props}
+  />
+))
+Card.displayName = "Card"
+
+const CardHeader = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("flex flex-col space-y-1.5 p-6", className)}
+    {...props}
+  />
+))
+CardHeader.displayName = "CardHeader"
+
+const CardTitle = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLHeadingElement>
+>(({ className, ...props }, ref) => (
+  <h3
+    ref={ref}
+    className={cn(
+      "text-2xl font-semibold leading-none tracking-tight",
+      className
+    )}
+    {...props}
+  />
+))
+CardTitle.displayName = "CardTitle"
+
+const CardDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <p
+    ref={ref}
+    className={cn("text-sm text-muted-foreground", className)}
+    {...props}
+  />
+))
+CardDescription.displayName = "CardDescription"
+
+const CardContent = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div ref={ref} className={cn("p-6 pt-0", className)} {...props} />
+))
+CardContent.displayName = "CardContent"
+
+const CardFooter = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("flex items-center p-6 pt-0", className)}
+    {...props}
+  />
+))
+CardFooter.displayName = "CardFooter"
+
+export { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent }

examples/twit/src/basicComponents/ui/checkbox.tsx

@@ -0,0 +1,28 @@
+import * as React from "react"
+import * as CheckboxPrimitive from "@radix-ui/react-checkbox"
+import { Check } from "lucide-react"
+
+import { cn } from "@/basicComponents/lib/utils"
+
+const Checkbox = React.forwardRef<
+  React.ElementRef<typeof CheckboxPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>
+>(({ className, ...props }, ref) => (
+  <CheckboxPrimitive.Root
+    ref={ref}
+    className={cn(
+      "peer h-4 w-4 shrink-0 rounded-sm border border-primary ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground",
+      className
+    )}
+    {...props}
+  >
+    <CheckboxPrimitive.Indicator
+      className={cn("flex items-center justify-center text-current")}
+    >
+      <Check className="h-4 w-4" />
+    </CheckboxPrimitive.Indicator>
+  </CheckboxPrimitive.Root>
+))
+Checkbox.displayName = CheckboxPrimitive.Root.displayName
+
+export { Checkbox }

examples/twit/src/basicComponents/ui/input.tsx

@@ -0,0 +1,25 @@
+import * as React from "react"
+
+import { cn } from "@/basicComponents/lib/utils"
+
+export interface InputProps
+  extends React.InputHTMLAttributes<HTMLInputElement> {}
+
+const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  ({ className, type, ...props }, ref) => {
+    return (
+      <input
+        type={type}
+        className={cn(
+          "flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+          className
+        )}
+        ref={ref}
+        {...props}
+      />
+    )
+  }
+)
+Input.displayName = "Input"
+
+export { Input }

examples/twit/src/basicComponents/ui/popover.tsx

@@ -0,0 +1,29 @@
+import * as React from "react"
+import * as PopoverPrimitive from "@radix-ui/react-popover"
+
+import { cn } from "@/basicComponents/lib/utils"
+
+const Popover = PopoverPrimitive.Root
+
+const PopoverTrigger = PopoverPrimitive.Trigger
+
+const PopoverContent = React.forwardRef<
+  React.ElementRef<typeof PopoverPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>
+>(({ className, align = "center", sideOffset = 4, ...props }, ref) => (
+  <PopoverPrimitive.Portal>
+    <PopoverPrimitive.Content
+      ref={ref}
+      align={align}
+      sideOffset={sideOffset}
+      className={cn(
+        "z-50 w-72 rounded-md border bg-popover p-4 text-popover-foreground shadow-md outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+        className
+      )}
+      {...props}
+    />
+  </PopoverPrimitive.Portal>
+))
+PopoverContent.displayName = PopoverPrimitive.Content.displayName
+
+export { Popover, PopoverTrigger, PopoverContent }

examples/twit/src/basicComponents/ui/skeleton.tsx

@@ -0,0 +1,15 @@
+import { cn } from "@/basicComponents/lib/utils"
+
+function Skeleton({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn("animate-pulse rounded-md bg-muted", className)}
+      {...props}
+    />
+  )
+}
+
+export { Skeleton }

examples/twit/src/basicComponents/ui/table.tsx

@@ -0,0 +1,114 @@
+import * as React from "react"
+
+import { cn } from "@/basicComponents/lib/utils"
+
+const Table = React.forwardRef<
+  HTMLTableElement,
+  React.HTMLAttributes<HTMLTableElement>
+>(({ className, ...props }, ref) => (
+  <div className="w-full overflow-auto">
+    <table
+      ref={ref}
+      className={cn("w-full caption-bottom text-sm", className)}
+      {...props}
+    />
+  </div>
+))
+Table.displayName = "Table"
+
+const TableHeader = React.forwardRef<
+  HTMLTableSectionElement,
+  React.HTMLAttributes<HTMLTableSectionElement>
+>(({ className, ...props }, ref) => (
+  <thead ref={ref} className={cn("[&_tr]:border-b", className)} {...props} />
+))
+TableHeader.displayName = "TableHeader"
+
+const TableBody = React.forwardRef<
+  HTMLTableSectionElement,
+  React.HTMLAttributes<HTMLTableSectionElement>
+>(({ className, ...props }, ref) => (
+  <tbody
+    ref={ref}
+    className={cn("[&_tr:last-child]:border-0", className)}
+    {...props}
+  />
+))
+TableBody.displayName = "TableBody"
+
+const TableFooter = React.forwardRef<
+  HTMLTableSectionElement,
+  React.HTMLAttributes<HTMLTableSectionElement>
+>(({ className, ...props }, ref) => (
+  <tfoot
+    ref={ref}
+    className={cn("bg-primary font-medium text-primary-foreground", className)}
+    {...props}
+  />
+))
+TableFooter.displayName = "TableFooter"
+
+const TableRow = React.forwardRef<
+  HTMLTableRowElement,
+  React.HTMLAttributes<HTMLTableRowElement>
+>(({ className, ...props }, ref) => (
+  <tr
+    ref={ref}
+    className={cn(
+      "border-b transition-colors hover:bg-muted/50 data-[state=selected]:bg-muted",
+      className
+    )}
+    {...props}
+  />
+))
+TableRow.displayName = "TableRow"
+
+const TableHead = React.forwardRef<
+  HTMLTableCellElement,
+  React.ThHTMLAttributes<HTMLTableCellElement>
+>(({ className, ...props }, ref) => (
+  <th
+    ref={ref}
+    className={cn(
+      "h-12 px-4 text-left align-middle font-medium text-muted-foreground [&:has([role=checkbox])]:pr-0",
+      className
+    )}
+    {...props}
+  />
+))
+TableHead.displayName = "TableHead"
+
+const TableCell = React.forwardRef<
+  HTMLTableCellElement,
+  React.TdHTMLAttributes<HTMLTableCellElement>
+>(({ className, ...props }, ref) => (
+  <td
+    ref={ref}
+    className={cn("p-4 align-middle [&:has([role=checkbox])]:pr-0", className)}
+    {...props}
+  />
+))
+TableCell.displayName = "TableCell"
+
+const TableCaption = React.forwardRef<
+  HTMLTableCaptionElement,
+  React.HTMLAttributes<HTMLTableCaptionElement>
+>(({ className, ...props }, ref) => (
+  <caption
+    ref={ref}
+    className={cn("mt-4 text-sm text-muted-foreground", className)}
+    {...props}
+  />
+))
+TableCaption.displayName = "TableCaption"
+
+export {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableHead,
+  TableRow,
+  TableCell,
+  TableCaption,
+}

examples/twit/src/basicComponents/ui/toast.tsx

@@ -0,0 +1,127 @@
+import * as React from "react"
+import * as ToastPrimitives from "@radix-ui/react-toast"
+import { cva, type VariantProps } from "class-variance-authority"
+import { X } from "lucide-react"
+
+import { cn } from "@/basicComponents/lib/utils"
+
+const ToastProvider = ToastPrimitives.Provider
+
+const ToastViewport = React.forwardRef<
+  React.ElementRef<typeof ToastPrimitives.Viewport>,
+  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Viewport>
+>(({ className, ...props }, ref) => (
+  <ToastPrimitives.Viewport
+    ref={ref}
+    className={cn(
+      "fixed top-0 z-[100] flex max-h-screen w-full flex-col-reverse p-4 sm:bottom-0 sm:right-0 sm:top-auto sm:flex-col md:max-w-[420px]",
+      className
+    )}
+    {...props}
+  />
+))
+ToastViewport.displayName = ToastPrimitives.Viewport.displayName
+
+const toastVariants = cva(
+  "group pointer-events-auto relative flex w-full items-center justify-between space-x-4 overflow-hidden rounded-md border p-6 pr-8 shadow-lg transition-all data-[swipe=cancel]:translate-x-0 data-[swipe=end]:translate-x-[var(--radix-toast-swipe-end-x)] data-[swipe=move]:translate-x-[var(--radix-toast-swipe-move-x)] data-[swipe=move]:transition-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[swipe=end]:animate-out data-[state=closed]:fade-out-80 data-[state=closed]:slide-out-to-right-full data-[state=open]:slide-in-from-top-full data-[state=open]:sm:slide-in-from-bottom-full",
+  {
+    variants: {
+      variant: {
+        default: "border bg-background text-foreground",
+        destructive:
+          "destructive group border-destructive bg-destructive text-destructive-foreground",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+const Toast = React.forwardRef<
+  React.ElementRef<typeof ToastPrimitives.Root>,
+  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Root> &
+    VariantProps<typeof toastVariants>
+>(({ className, variant, ...props }, ref) => {
+  return (
+    <ToastPrimitives.Root
+      ref={ref}
+      className={cn(toastVariants({ variant }), className)}
+      {...props}
+    />
+  )
+})
+Toast.displayName = ToastPrimitives.Root.displayName
+
+const ToastAction = React.forwardRef<
+  React.ElementRef<typeof ToastPrimitives.Action>,
+  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Action>
+>(({ className, ...props }, ref) => (
+  <ToastPrimitives.Action
+    ref={ref}
+    className={cn(
+      "inline-flex h-8 shrink-0 items-center justify-center rounded-md border bg-transparent px-3 text-sm font-medium ring-offset-background transition-colors hover:bg-secondary focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 group-[.destructive]:border-muted/40 group-[.destructive]:hover:border-destructive/30 group-[.destructive]:hover:bg-destructive group-[.destructive]:hover:text-destructive-foreground group-[.destructive]:focus:ring-destructive",
+      className
+    )}
+    {...props}
+  />
+))
+ToastAction.displayName = ToastPrimitives.Action.displayName
+
+const ToastClose = React.forwardRef<
+  React.ElementRef<typeof ToastPrimitives.Close>,
+  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Close>
+>(({ className, ...props }, ref) => (
+  <ToastPrimitives.Close
+    ref={ref}
+    className={cn(
+      "absolute right-2 top-2 rounded-md p-1 text-foreground/50 opacity-0 transition-opacity hover:text-foreground focus:opacity-100 focus:outline-none focus:ring-2 group-hover:opacity-100 group-[.destructive]:text-red-300 group-[.destructive]:hover:text-red-50 group-[.destructive]:focus:ring-red-400 group-[.destructive]:focus:ring-offset-red-600",
+      className
+    )}
+    toast-close=""
+    {...props}
+  >
+    <X className="h-4 w-4" />
+  </ToastPrimitives.Close>
+))
+ToastClose.displayName = ToastPrimitives.Close.displayName
+
+const ToastTitle = React.forwardRef<
+  React.ElementRef<typeof ToastPrimitives.Title>,
+  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Title>
+>(({ className, ...props }, ref) => (
+  <ToastPrimitives.Title
+    ref={ref}
+    className={cn("text-sm font-semibold", className)}
+    {...props}
+  />
+))
+ToastTitle.displayName = ToastPrimitives.Title.displayName
+
+const ToastDescription = React.forwardRef<
+  React.ElementRef<typeof ToastPrimitives.Description>,
+  React.ComponentPropsWithoutRef<typeof ToastPrimitives.Description>
+>(({ className, ...props }, ref) => (
+  <ToastPrimitives.Description
+    ref={ref}
+    className={cn("text-sm opacity-90", className)}
+    {...props}
+  />
+))
+ToastDescription.displayName = ToastPrimitives.Description.displayName
+
+type ToastProps = React.ComponentPropsWithoutRef<typeof Toast>
+
+type ToastActionElement = React.ReactElement<typeof ToastAction>
+
+export {
+  type ToastProps,
+  type ToastActionElement,
+  ToastProvider,
+  ToastViewport,
+  Toast,
+  ToastTitle,
+  ToastDescription,
+  ToastClose,
+  ToastAction,
+}

examples/twit/src/basicComponents/ui/toaster.tsx

@@ -0,0 +1,33 @@
+import {
+  Toast,
+  ToastClose,
+  ToastDescription,
+  ToastProvider,
+  ToastTitle,
+  ToastViewport,
+} from "@/basicComponents/ui/toast"
+import { useToast } from "@/basicComponents/ui/use-toast"
+
+export function Toaster() {
+  const { toasts } = useToast()
+
+  return (
+    <ToastProvider>
+      {toasts.map(function ({ id, title, description, action, ...props }) {
+        return (
+          <Toast key={id} {...props}>
+            <div className="grid gap-1">
+              {title && <ToastTitle>{title}</ToastTitle>}
+              {description && (
+                <ToastDescription>{description}</ToastDescription>
+              )}
+            </div>
+            {action}
+            <ToastClose />
+          </Toast>
+        )
+      })}
+      <ToastViewport />
+    </ToastProvider>
+  )
+}

examples/twit/src/basicComponents/ui/use-toast.ts

@@ -0,0 +1,192 @@
+// Inspired by react-hot-toast library
+import * as React from "react"
+
+import type {
+  ToastActionElement,
+  ToastProps,
+} from "@/basicComponents/ui/toast"
+
+const TOAST_LIMIT = 1
+const TOAST_REMOVE_DELAY = 1000000
+
+type ToasterToast = ToastProps & {
+  id: string
+  title?: React.ReactNode
+  description?: React.ReactNode
+  action?: ToastActionElement
+}
+
+const actionTypes = {
+  ADD_TOAST: "ADD_TOAST",
+  UPDATE_TOAST: "UPDATE_TOAST",
+  DISMISS_TOAST: "DISMISS_TOAST",
+  REMOVE_TOAST: "REMOVE_TOAST",
+} as const
+
+let count = 0
+
+function genId() {
+  count = (count + 1) % Number.MAX_VALUE
+  return count.toString()
+}
+
+type ActionType = typeof actionTypes
+
+type Action =
+  | {
+      type: ActionType["ADD_TOAST"]
+      toast: ToasterToast
+    }
+  | {
+      type: ActionType["UPDATE_TOAST"]
+      toast: Partial<ToasterToast>
+    }
+  | {
+      type: ActionType["DISMISS_TOAST"]
+      toastId?: ToasterToast["id"]
+    }
+  | {
+      type: ActionType["REMOVE_TOAST"]
+      toastId?: ToasterToast["id"]
+    }
+
+interface State {
+  toasts: ToasterToast[]
+}
+
+const toastTimeouts = new Map<string, ReturnType<typeof setTimeout>>()
+
+const addToRemoveQueue = (toastId: string) => {
+  if (toastTimeouts.has(toastId)) {
+    return
+  }
+
+  const timeout = setTimeout(() => {
+    toastTimeouts.delete(toastId)
+    dispatch({
+      type: "REMOVE_TOAST",
+      toastId: toastId,
+    })
+  }, TOAST_REMOVE_DELAY)
+
+  toastTimeouts.set(toastId, timeout)
+}
+
+export const reducer = (state: State, action: Action): State => {
+  switch (action.type) {
+    case "ADD_TOAST":
+      return {
+        ...state,
+        toasts: [action.toast, ...state.toasts].slice(0, TOAST_LIMIT),
+      }
+
+    case "UPDATE_TOAST":
+      return {
+        ...state,
+        toasts: state.toasts.map((t) =>
+          t.id === action.toast.id ? { ...t, ...action.toast } : t
+        ),
+      }
+
+    case "DISMISS_TOAST": {
+      const { toastId } = action
+
+      // ! Side effects ! - This could be extracted into a dismissToast() action,
+      // but I'll keep it here for simplicity
+      if (toastId) {
+        addToRemoveQueue(toastId)
+      } else {
+        state.toasts.forEach((toast) => {
+          addToRemoveQueue(toast.id)
+        })
+      }
+
+      return {
+        ...state,
+        toasts: state.toasts.map((t) =>
+          t.id === toastId || toastId === undefined
+            ? {
+                ...t,
+                open: false,
+              }
+            : t
+        ),
+      }
+    }
+    case "REMOVE_TOAST":
+      if (action.toastId === undefined) {
+        return {
+          ...state,
+          toasts: [],
+        }
+      }
+      return {
+        ...state,
+        toasts: state.toasts.filter((t) => t.id !== action.toastId),
+      }
+  }
+}
+
+const listeners: Array<(state: State) => void> = []
+
+let memoryState: State = { toasts: [] }
+
+function dispatch(action: Action) {
+  memoryState = reducer(memoryState, action)
+  listeners.forEach((listener) => {
+    listener(memoryState)
+  })
+}
+
+type Toast = Omit<ToasterToast, "id">
+
+function toast({ ...props }: Toast) {
+  const id = genId()
+
+  const update = (props: ToasterToast) =>
+    dispatch({
+      type: "UPDATE_TOAST",
+      toast: { ...props, id },
+    })
+  const dismiss = () => dispatch({ type: "DISMISS_TOAST", toastId: id })
+
+  dispatch({
+    type: "ADD_TOAST",
+    toast: {
+      ...props,
+      id,
+      open: true,
+      onOpenChange: (open) => {
+        if (!open) dismiss()
+      },
+    },
+  })
+
+  return {
+    id: id,
+    dismiss,
+    update,
+  }
+}
+
+function useToast() {
+  const [state, setState] = React.useState<State>(memoryState)
+
+  React.useEffect(() => {
+    listeners.push(setState)
+    return () => {
+      const index = listeners.indexOf(setState)
+      if (index > -1) {
+        listeners.splice(index, 1)
+      }
+    }
+  }, [state])
+
+  return {
+    ...state,
+    toast,
+    dismiss: (toastId?: string) => dispatch({ type: "DISMISS_TOAST", toastId }),
+  }
+}
+
+export { useToast, toast }

examples/twit/src/components/Auth.tsx

@@ -0,0 +1,48 @@
+import { useState } from "react";
+
+import { LocalAuthComponent } from "jazz-react-auth-local";
+
+import { Input, Button } from "../basicComponents";
+
+export const PrettyAuthUI: LocalAuthComponent = ({
+    loading,
+    logIn,
+    signUp,
+}) => {
+    const [username, setUsername] = useState<string>("");
+
+    return (
+        <div className="w-full h-full flex items-center justify-center p-5">
+            {loading ? (
+                <div>Loading...</div>
+            ) : (
+                <div className="w-72 flex flex-col gap-4">
+                    <form
+                        className="w-72 flex flex-col gap-2"
+                        onSubmit={(e) => {
+                            e.preventDefault();
+                            signUp(username);
+                        }}
+                    >
+                        <Input
+                            placeholder="Display name"
+                            value={username}
+                            onChange={(e) => setUsername(e.target.value)}
+                            autoComplete="webauthn"
+                            className="text-base"
+                        />
+                        <Button asChild>
+                            <Input
+                                type="submit"
+                                value="Sign Up as new account"
+                            />
+                        </Button>
+                    </form>
+                    <Button onClick={logIn}>
+                        Log In with existing account
+                    </Button>
+                </div>
+            )}
+        </div>
+    );
+};

examples/twit/src/index.css

@@ -0,0 +1,76 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+ 
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 20 14.3% 4.1%;
+
+    --card: 0 0% 100%;
+    --card-foreground: 20 14.3% 4.1%;
+ 
+    --popover: 0 0% 100%;
+    --popover-foreground: 20 14.3% 4.1%;
+ 
+    --primary: 24 9.8% 10%;
+    --primary-foreground: 60 9.1% 97.8%;
+ 
+    --secondary: 60 4.8% 95.9%;
+    --secondary-foreground: 24 9.8% 10%;
+ 
+    --muted: 60 4.8% 95.9%;
+    --muted-foreground: 25 5.3% 44.7%;
+ 
+    --accent: 60 4.8% 95.9%;
+    --accent-foreground: 24 9.8% 10%;
+ 
+    --destructive: 0 84.2% 60.2%;
+    --destructive-foreground: 60 9.1% 97.8%;
+
+    --border: 20 5.9% 90%;
+    --input: 20 5.9% 90%;
+    --ring: 20 14.3% 4.1%;
+ 
+    --radius: 0.5rem;
+  }
+ 
+  .dark {
+    --background: 20 14.3% 4.1%;
+    --foreground: 60 9.1% 97.8%;
+ 
+    --card: 20 14.3% 4.1%;
+    --card-foreground: 60 9.1% 97.8%;
+ 
+    --popover: 20 14.3% 4.1%;
+    --popover-foreground: 60 9.1% 97.8%;
+ 
+    --primary: 60 9.1% 97.8%;
+    --primary-foreground: 24 9.8% 10%;
+ 
+    --secondary: 12 6.5% 15.1%;
+    --secondary-foreground: 60 9.1% 97.8%;
+ 
+    --muted: 12 6.5% 15.1%;
+    --muted-foreground: 24 5.4% 63.9%;
+ 
+    --accent: 12 6.5% 15.1%;
+    --accent-foreground: 60 9.1% 97.8%;
+ 
+    --destructive: 0 62.8% 30.6%;
+    --destructive-foreground: 60 9.1% 97.8%;
+ 
+    --border: 12 6.5% 15.1%;
+    --input: 12 6.5% 15.1%;
+    --ring: 24 5.7% 82.9%;
+  }
+}
+ 
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}

examples/twit/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

examples/twit/tailwind.config.js

@@ -0,0 +1,76 @@
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  darkMode: ["class"],
+  content: [
+    './pages/**/*.{ts,tsx}',
+    './components/**/*.{ts,tsx}',
+    './app/**/*.{ts,tsx}',
+    './src/**/*.{ts,tsx}',
+	],
+  theme: {
+    container: {
+      center: true,
+      padding: "2rem",
+      screens: {
+        "2xl": "1400px",
+      },
+    },
+    extend: {
+      colors: {
+        border: "hsl(var(--border))",
+        input: "hsl(var(--input))",
+        ring: "hsl(var(--ring))",
+        background: "hsl(var(--background))",
+        foreground: "hsl(var(--foreground))",
+        primary: {
+          DEFAULT: "hsl(var(--primary))",
+          foreground: "hsl(var(--primary-foreground))",
+        },
+        secondary: {
+          DEFAULT: "hsl(var(--secondary))",
+          foreground: "hsl(var(--secondary-foreground))",
+        },
+        destructive: {
+          DEFAULT: "hsl(var(--destructive))",
+          foreground: "hsl(var(--destructive-foreground))",
+        },
+        muted: {
+          DEFAULT: "hsl(var(--muted))",
+          foreground: "hsl(var(--muted-foreground))",
+        },
+        accent: {
+          DEFAULT: "hsl(var(--accent))",
+          foreground: "hsl(var(--accent-foreground))",
+        },
+        popover: {
+          DEFAULT: "hsl(var(--popover))",
+          foreground: "hsl(var(--popover-foreground))",
+        },
+        card: {
+          DEFAULT: "hsl(var(--card))",
+          foreground: "hsl(var(--card-foreground))",
+        },
+      },
+      borderRadius: {
+        lg: "var(--radius)",
+        md: "calc(var(--radius) - 2px)",
+        sm: "calc(var(--radius) - 4px)",
+      },
+      keyframes: {
+        "accordion-down": {
+          from: { height: 0 },
+          to: { height: "var(--radix-accordion-content-height)" },
+        },
+        "accordion-up": {
+          from: { height: "var(--radix-accordion-content-height)" },
+          to: { height: 0 },
+        },
+      },
+      animation: {
+        "accordion-down": "accordion-down 0.2s ease-out",
+        "accordion-up": "accordion-up 0.2s ease-out",
+      },
+    },
+  },
+  plugins: [require("tailwindcss-animate")],
+}

examples/twit/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}