Overview

CLI toolkit

SDKs

Initialization

Auth

Anonymous account

Firestore

Collection

Document

Query

Create and update data

Firestore Security rules

Storage

Object: reference and metadata

List objects

Download an object

Upload an object

Upload task (advanced)

Setting the bucket CORS header

Cloud Functions

Define Callable functions

Invoke a Callable functions

HTTP endpoint (REST-API)

Functions on Auth events

on Firestore events - functions

Environment variables

Debug Functions locally

Deployment

Timestamp and dates

Cron

GenKit

.prompt Prompt file

Typescript Prompt file

# Overview

<div class="bookHeroImage" style="border: currentColor .5px solid;padding: 32px;border-radius: 8px;margin: 8px 0;">
<svg viewBox="0 0 749 205" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M707.39 161.434C700.156 161.434 693.615 159.749 687.768 156.379C682.021 153.01 677.512 148.352 674.241 142.406C670.971 136.361 669.336 129.623 669.336 122.19C669.336 115.055 670.872 108.514 673.944 102.568C677.115 96.5234 681.525 91.7666 687.174 88.2981C692.822 84.7306 699.264 82.9468 706.498 82.9468C713.931 82.9468 720.372 84.5819 725.823 87.8522C731.372 91.1225 735.584 95.6811 738.458 101.528C741.332 107.276 742.769 113.915 742.769 121.447C742.769 122.339 742.719 123.231 742.62 124.123C742.521 125.014 742.471 125.51 742.471 125.609H685.687C686.183 132.348 688.611 137.551 692.971 141.217C697.332 144.884 702.286 146.717 707.836 146.717C716.359 146.717 722.899 142.753 727.458 134.825L741.431 141.515C738.16 147.56 733.602 152.415 727.755 156.082C722.007 159.65 715.219 161.434 707.39 161.434ZM726.12 113.123C725.922 110.744 725.129 108.316 723.742 105.839C722.354 103.361 720.174 101.28 717.201 99.5955C714.327 97.8117 710.71 96.9198 706.35 96.9198C701.494 96.9198 697.282 98.4063 693.714 101.379C690.246 104.352 687.868 108.267 686.579 113.123H726.12Z" fill="#5E5E5E"/>
<path d="M633.449 161.434C625.025 161.434 618.039 159.501 612.489 155.636C607.039 151.672 603.174 146.717 600.895 140.771L615.462 134.528C617.147 138.591 619.575 141.663 622.746 143.744C626.016 145.825 629.584 146.866 633.449 146.866C637.512 146.866 640.832 146.123 643.408 144.636C645.985 143.051 647.273 141.019 647.273 138.542C647.273 136.163 646.233 134.231 644.151 132.744C642.07 131.159 638.651 129.771 633.895 128.582L623.786 126.204C618.237 124.915 613.431 122.537 609.368 119.069C605.404 115.501 603.422 110.893 603.422 105.244C603.422 98.4063 606.246 93.0054 611.895 89.0414C617.543 84.9783 624.48 82.9468 632.705 82.9468C639.543 82.9468 645.588 84.3837 650.841 87.2576C656.192 90.1315 660.057 94.2937 662.435 99.7441L648.016 105.839C646.629 102.767 644.498 100.487 641.624 99.0009C638.75 97.5144 635.629 96.7711 632.26 96.7711C628.989 96.7711 626.115 97.5144 623.638 99.0009C621.16 100.388 619.922 102.271 619.922 104.65C619.922 106.731 620.764 108.415 622.449 109.704C624.232 110.992 627.007 112.082 630.773 112.974L641.773 115.65C649.205 117.532 654.755 120.406 658.422 124.271C662.088 128.037 663.922 132.596 663.922 137.947C663.922 142.307 662.584 146.271 659.908 149.839C657.332 153.406 653.715 156.231 649.057 158.312C644.498 160.393 639.296 161.434 633.449 161.434Z" fill="#5E5E5E"/>
<path d="M555.223 161.434C549.971 161.434 545.214 160.393 540.953 158.312C536.791 156.132 533.471 153.159 530.993 149.393C528.615 145.528 527.426 141.168 527.426 136.312C527.426 128.582 530.3 122.487 536.047 118.028C541.894 113.568 549.277 111.339 558.196 111.339C566.025 111.339 572.714 112.677 578.264 115.352V112.231C578.264 107.771 576.48 104.105 572.912 101.231C569.444 98.2576 565.232 96.7711 560.277 96.7711C552.746 96.7711 546.701 99.8432 542.142 105.987L529.656 97.3657C533.124 92.7081 537.435 89.1405 542.588 86.663C547.84 84.1855 553.737 82.9468 560.277 82.9468C571.079 82.9468 579.403 85.672 585.25 91.1225C591.196 96.4738 594.169 104.055 594.169 113.866V159.055H578.264V149.988H577.372C574.994 153.357 571.971 156.132 568.304 158.312C564.638 160.393 560.277 161.434 555.223 161.434ZM557.899 147.906C561.566 147.906 564.935 147.015 568.007 145.231C571.178 143.348 573.656 140.92 575.439 137.947C577.322 134.875 578.264 131.605 578.264 128.136C573.012 125.262 567.412 123.825 561.466 123.825C556.016 123.825 551.755 125.014 548.683 127.393C545.611 129.771 544.075 132.794 544.075 136.46C544.075 139.83 545.412 142.605 548.088 144.785C550.863 146.866 554.133 147.906 557.899 147.906Z" fill="#5E5E5E"/>
<path d="M486.618 161.433C481.266 161.433 476.46 160.294 472.199 158.014C468.037 155.735 464.915 152.861 462.834 149.393H461.942V159.055H446.482V52.6221H462.834V84.5816L461.942 94.8384H462.834C464.915 91.469 468.037 88.6447 472.199 86.3654C476.46 84.0861 481.266 82.9465 486.618 82.9465C492.96 82.9465 498.807 84.6312 504.158 88.0006C509.609 91.3699 513.92 96.0772 517.091 102.122C520.361 108.068 521.996 114.757 521.996 122.19C521.996 129.622 520.361 136.312 517.091 142.257C513.92 148.203 509.609 152.911 504.158 156.379C498.807 159.749 492.96 161.433 486.618 161.433ZM483.793 146.42C487.658 146.42 491.226 145.429 494.496 143.447C497.865 141.465 500.541 138.64 502.523 134.974C504.604 131.208 505.645 126.947 505.645 122.19C505.645 117.433 504.604 113.221 502.523 109.555C500.541 105.789 497.865 102.915 494.496 100.933C491.226 98.951 487.658 97.9601 483.793 97.9601C479.928 97.9601 476.311 98.951 472.942 100.933C469.672 102.915 466.996 105.739 464.915 109.406C462.933 113.073 461.942 117.334 461.942 122.19C461.942 127.046 462.933 131.307 464.915 134.974C466.996 138.64 469.672 141.465 472.942 143.447C476.311 145.429 479.928 146.42 483.793 146.42Z" fill="#5E5E5E"/>
<path d="M401.365 161.434C394.13 161.434 387.59 159.749 381.743 156.379C375.995 153.01 371.486 148.352 368.216 142.406C364.946 136.361 363.311 129.623 363.311 122.19C363.311 115.055 364.847 108.514 367.919 102.568C371.09 96.5234 375.5 91.7666 381.148 88.2981C386.797 84.7306 393.239 82.9468 400.473 82.9468C407.905 82.9468 414.347 84.5819 419.797 87.8522C425.347 91.1225 429.559 95.6811 432.432 101.528C435.306 107.276 436.743 113.915 436.743 121.447C436.743 122.339 436.694 123.231 436.595 124.123C436.495 125.014 436.446 125.51 436.446 125.609H379.662C380.157 132.348 382.585 137.551 386.946 141.217C391.306 144.884 396.261 146.717 401.811 146.717C410.333 146.717 416.874 142.753 421.432 134.825L435.405 141.515C432.135 147.56 427.577 152.415 421.73 156.082C415.982 159.65 409.194 161.434 401.365 161.434ZM420.095 113.123C419.896 110.744 419.104 108.316 417.716 105.839C416.329 103.361 414.149 101.28 411.176 99.5955C408.302 97.8117 404.685 96.9198 400.324 96.9198C395.468 96.9198 391.257 98.4063 387.689 101.379C384.221 104.352 381.842 108.267 380.554 113.123H420.095Z" fill="#5E5E5E"/>
<path d="M317.93 85.3252H333.389V96.3252H334.281C335.867 92.5595 338.741 89.4378 342.903 86.9603C347.065 84.3838 351.326 83.0955 355.687 83.0955C359.254 83.0955 362.178 83.591 364.457 84.582V101.677C361.087 99.9919 357.322 99.1496 353.16 99.1496C347.808 99.1496 343.299 101.231 339.632 105.393C336.065 109.456 334.281 114.46 334.281 120.406V159.055H317.93V85.3252Z" fill="#5E5E5E"/>
<path d="M294.594 72.8384C291.522 72.8384 288.896 71.7979 286.715 69.7168C284.634 67.5366 283.594 64.9105 283.594 61.8384C283.594 58.7663 284.634 56.1897 286.715 54.1087C288.896 51.9285 291.522 50.8384 294.594 50.8384C297.666 50.8384 300.242 51.9285 302.324 54.1087C304.504 56.1897 305.594 58.7663 305.594 61.8384C305.594 64.9105 304.504 67.5366 302.324 69.7168C300.242 71.7979 297.666 72.8384 294.594 72.8384ZM286.418 85.325H302.769V159.055H286.418V85.325Z" fill="#5E5E5E"/>
<path d="M211.938 52.6221H276.6V68.5275H228.586V99.1492H271.843V114.906H228.586V159.055H211.938V52.6221Z" fill="#5E5E5E"/>
<path d="M51.2275 191.109C59.4031 194.399 68.2727 196.352 77.5857 196.677C90.1896 197.117 102.175 194.511 112.89 189.561C100.041 184.513 88.4043 177.131 78.4729 167.952C72.0352 178.26 62.5135 186.401 51.2275 191.109Z" fill="#FF9100"/>
<path d="M78.4711 167.955C55.8006 146.988 42.0477 116.641 43.21 83.3558C43.2478 82.2749 43.3048 81.1947 43.3715 80.1148C39.3113 79.0647 35.0725 78.4239 30.7103 78.2716C24.4663 78.0535 18.4195 78.8279 12.7108 80.4355C6.659 91.0365 3.00696 103.2 2.552 116.228C1.37785 149.852 21.7254 179.231 51.2257 191.112C62.5117 186.404 72.0331 178.272 78.4711 167.955Z" fill="#FFC400"/>
<path d="M78.472 167.954C83.7428 159.519 86.9386 149.63 87.3106 138.976C88.2893 110.95 69.4486 86.8412 43.3725 80.1137C43.3058 81.1936 43.2487 82.2738 43.211 83.3547C42.0486 116.64 55.8015 146.987 78.472 167.954Z" fill="#FF9100"/>
<path d="M84.3945 1.33524C69.5432 13.233 57.8158 28.9212 50.7205 46.9936C46.6583 57.3453 44.1056 68.4647 43.3603 80.1206C69.4365 86.8481 88.2772 110.957 87.2985 138.983C86.9264 149.637 83.7213 159.516 78.4599 167.961C88.391 177.149 100.028 184.522 112.877 189.57C138.667 177.649 156.965 151.996 158.025 121.654C158.711 101.995 151.158 84.4744 140.485 69.6852C129.214 54.0442 84.3945 1.33524 84.3945 1.33524Z" fill="#DD2C00"/>
</svg></div>

Firebase allows to create a backend managed by Google.

### overall benefits

-   good developer experience
-   it may scale with virtually no limit
-   extensive free-tier and affordable rates
-   good documentation and supported by AI models.
-   actively developed and maintained.



# CLI toolkit

### toolkit overview

The firebase CLI allows to:

-   run and debug an emulated backend locally, with no incurred cost: an authentication server, a database, and serverless functions.

-   start a shell session from the CLI to call and debug the emulated cloud functions.

-   scaffold a project or a directory with boilerplate code, notably the cloud functions directory.

-   deploy cloud functions, security rules, and possibly a website.

-   list and manage the firebase projects that live on the current account

### install the executable through npm

the npm package's name is different from the executable

```shell
firebase-tools 	# npm package
firebase 				# executable name
```

### CLI setup

```bash
firebase login
firebase login:list # indicates which account is logged in
```

### project initialization

```bash
firebase init
```

### main uses

```bash
firebase help
firebase help deploy # get help about a command

firebase help | grep firestore # filter lines
firebase help | grep functions

firebase projects:list

firebase functions:list
firebase functions:shell

firebase functions:secrets:set OPENAI_API_KEY
firebase functions:secrets:get OPENAI_API_KEY


firebase deploy
firebase deploy --only functions
firebase deploy --only functions:requestPlanet
```

### emulators

start emulators:

```bash
firebase emulators:start
firebase emulators:start --import=./emulatorData/ --export-on-exit
```

We specify which emulator to run in `firebase.json`. In absence of such file, no emulator may run. The port is optional: we may omit it and provide an empty object instead.

```json
{
    "emulators": {
        "firestore": { "port": 8080 },
        "auth": { "port": 9099 },
        "functions": { "port": 5001 },
        "storage": { "port": 9199 },
        "ui": { "enabled": true }
    },
    "storage": { "rules": "storage.rules" },
    "functions": [
        {
            "source": "functions",
            "codebase": "default",
            "ignore": [
                "node_modules",
                ".git",
                "firebase-debug.log",
                "firebase-debug.*.log",
                "*.local"
            ],
            "predeploy": ["npm --prefix \"$RESOURCE_DIR\" run build"]
        }
    ]
}
```



# SDKs

### Client SDK npm package

    firebase

client SDK for firestore, auth, callable functions and more.

### admin SDK npm package

    firebase-admin

It runs through Node.js.

-   [release notes](https://firebase.google.com/support/release-notes/admin/node/)
-   [admin SDK reference](https://firebase.google.com/docs/reference/admin/node/firebase-admin)



# Initialization

### config object

The config object allows the client to identify itself when talking to the Firebase services.

```tsx
const firebaseConfig = {
    apiKey: "....",
    authDomain: ".....firebaseapp.com",
    projectId: "....",
    storageBucket: ".....appspot.com",
    messagingSenderId: "....",
    appId: "....",
}
```

### the app object

we get and keep a reference to the app object to provide it to services such as _auth_ or _firestore_.

### embed the config in the app object

On the client, we provide the config to the _app_ object , through `initializeApp()`.

```tsx
const app = initializeApp(firebaseConfig)
```

### cloud functions: pre-configured

On a server managed by Google, the admin SDK is automatically configured, so that we don't need to give the config to the app.

```tsx
const app = initializeApp() // on google server
```



# Auth



### interact with authentication servers from the client

Google manages the authentication servers. As developers we focus on interacting with those servers from the client. We use the Auth client SDK.

### auth object

We get and keep a reference to the auth object as we use it in various methods and because it holds `currentUser`. We give it ``app` so that it receives the config.

```tsx
const auth = getAuth(app)
```

_currentUser_ starts as _null_. When the SDK has finished initializing, it switches to an object if a user has been logged-in automatically. Otherwise it stays _null_. It's also _null_ when the user logs out.

```tsx
auth.currentUser // User | null
```

### User type

_uid_ uniquely identifies the user. Other properties are optional.

```tsx
uid
email
phoneNumber
displayName
```

### request registration, and other requests related to Auth

attempt to register

```tsx
createUserWithEmailAndPassword(auth, email, password)
```

attempt to sign-in

```tsx
signInWithEmailAndPassword(auth, email, password)
```

sign-out

```tsx
signOut(auth)
```

ask for a password reset mail

```tsx
sendPasswordResetEmail(auth, email)
```

### patterns to manage failed attempts

await within _try...catch_

```tsx
async function signUp() {
    try {
        const userCredential = await createUserWithEmailAndPassword(auth, email, password)
        console.log("user ID:", userCredential.user.uid)
    } catch (error) {
        console.log(error)
    } finally {
        setIsLoading(false)
    }
}
```

trailing _then...catch_

```tsx
createUserWithEmailAndPassword(auth, email, password)
    .catch((error) => alert(error.message))
    .finally(() => setIsLoading(false))
```

### react to authentication state changes

We call `onAuthStateChanged` to register a callback. Each time firebase runs our callback, it provides us with the `user` object.

The state changes when:

-   the user registers (sign-up)

-   the user logs in (sign-in)
-   the user logs out (sign-out)

the login may occur in two ways:

-   the user fills the login form and submits it successfully
-   the user is recognized by the SDK and is logged in automatically

```tsx
onAuthStateChanged(auth, (user) => {
    const isAuthenticated = Boolean(user)
    // setIsAuthenticated(isAuthenticated)
    // setIsLoading(false)
    // const userID = user.uid
})
```

### React patterns

In React apps, we store the user authentication status in a state variable such as `isAuthenticated`.

We display the authenticated area when _isAuthenticated_ is true.

At page launch, the authentication state is not determined. We may keep track of it in a `isLoading` state variable. It would default to _true_ and switch to _false_ on the first authentication event.

```ts
// loading
isLoading // true
isAuthenticated // false

// loaded
isLoading // false
isAuthenticated // true or false
```

# Anonymous account



### register as anonymous

```tsx
signInAnonymously(auth)
```

### check if the account is anonymous

the account is anonymous if there is no provider data:

```tsx
const isAnonymous = auth.currentUser?.providerData.length === 0
```

### convert to an email account

we build an email credential and add it to the account.

```tsx
const credential = EmailAuthProvider.credential(email, password)
linkWithCredential(auth.currentUser, credential)
```

# Firestore



-   [client SDK reference](https://firebase.google.com/docs/reference/js/firestore)
-   [server SDK reference overview - firebase](https://firebase.google.com/docs/reference/admin/node/firebase-admin.firestore)
-   [server SDK reference - googleapis](https://googleapis.dev/nodejs/firestore/latest/CollectionReference.html)
-   [server SDK reference - cloud.google.com](https://cloud.google.com/nodejs/docs/reference/firestore/latest/firestore/collectionreference)

import paths

```tsx
"firebase/firestore" // client SDK
"firebase/firestore/lite" // client SDK

"firebase-admin/firestore" // server SDK
```

We create a _db_ object that embeds the config, and provide it to the firestore functions.

```tsx
const db = getFirestore(app)
```

## conceptual overview

### Collection

A set of documents

### Document

A set of fields. A document may contain 20k fields and 1 megabyte data.

### Reference to a document or to a collection

A reference serves to identify an item but does not guarantee the item existence (underlying
collection, or underlying document). That is, the item either exists or is a tentative item.

It is built with the item's path or ID.

# Collection



## Collection Reference

### uses

We provide the collection reference to:

-   fetch all documents - `getDocs(colRef)`

-   build a query targeting the collection - `query(colRef, filters..)`

-   build an empty document reference within the collection - `doc(colRef)`
-   add a document to the collection, by submitting data and delegating the id creation to the SDK - `addDoc(colRef, data)`. (it returns the reference)

We may also use it in combination with a document's ID to uniquely identify this document, such as in `getDoc(colRef, id)`

A documentRef already encapsulates the collection reference. As such, we don't need to provide both.

### build a collection reference

The path to the collection identifies it uniquely. If the collection lives at the top, aka is not a sub-collection, the path is the same as the collection name, such as `"users"`. Otherwise it's made of several components.

We indicate the collection's path, either as:

-   a single string, with no starting slash for the root collection

-   a sequence of string arguments with no slash.

```tsx
const collectionRef = collection(db, "users")
const collectionRef = collection(db, `users/${uid}/custom_list`)
const collectionRef = collection(db, "users", uid, "custom_list")
```

```tsx
// firebase-admin/firestore
const collectionRef = db.collection("users")
const collectionRef = db.collection(`users/${uid}/custom_list`)
```

### Typescript: indicate the document's type at the collection level.

The SDK cannot infer the document type for a given collection. As such, we provide it at the collection reference level.

We may have a client specific type, one that results from a client-side transformation, that we do with a converter. In that case, we provide the client-side type first. Otherwise, we provide the same type twice.

```tsx
const playersColRef = collectionRef as CollectionReference<Player, Player>
const playersColRef = collectionRef as CollectionReference<Player, FirestorePlayer>
const playersColRef = collectionRef.withConverter(myConverter)
```

## Firestore Converter

### declare transform between firestore shape and client shape.

We may want to have a shape on the client that is distinct from the one in the database. For example:

-   a property is a Timestamp in the database, but we want a Date on the
    client.
-   We want to add client only properties, such as helper properties.

In this case, we want Firebase to transform the document when

-   receiving it from Firestore (`fromFirestore()`)
-   sending it to Firestore (`toFirestore()`)

We define a converter, made of two functions.

_fromFirestore_ takes a query document snapshot.:

```tsx
fromFirestore(snapshot: QueryDocumentSnapshot<FirestoreWorkout>): Workout{
		// transform to client shape
		const firestoreWorkout = snapshot.data()
		const workout = { ...firestoreItem, date: firestoreItem.date.toDate()}
     return workout
    }
```

_toFirestore_ takes the local object.

```tsx
toFirestore(workout: Workout) {
		// prepare the object for firestore
        	return { ...workout, date: Timestamp.fromDate(workout.date)}
    }
```

and put them in a data converter of type _FirestoreDataConverter_, which dictates both types, provided as type parameters following the shape of: _FirestoreDataConverter\<AppModel, DbModel\>_

```tsx
const myConverter: FirestoreDataConverter<Workout, FirestoreWorkout> = {
    toFirestore() {},
    fromFirestore() {},
}
```

### attach the converter to the collectionRef

We attach the converter with `withConverter()`

```tsx
const collectionRef = collection(db, "users").withConverter(myConverter)
```

### cloud functions may not use a converter

the Admin SDK does not provide `withConverter()`

# Document



## Document reference

the document reference identifies a document within a collection, and embeds information about the parent collection.

_parent_ is the the collection reference, _id_ is the document's id. _path_ is the document's absolute path as a string.

```tsx
docRef.parent
docRef.id
docRed.path
```

### uses: CRUD

We provide the document reference for CRUD operations:

-   create or override (upsert) the document - `setDoc(ref, data)`

-   read the document - `getDoc(ref)`

-   update the document - `updateDoc(ref, data)`

-   delete the document - `deleteDoc(ref)`

### compute a document reference

The path identifies the document uniquely. We provide it either as a single string or multiple strings.

We may provide the collectionRef and the document ID.

We may let Firestore creates the reference for us.

In some cases, we may provide only the parent collection's reference.

-   compute a reference out of a path or ID.

```tsx
const docRef = doc(collectionRef, id)
const docRef = doc(collectionRef) // ID is generated by firestore

const docRef = doc(db, "users", id) // collectionRef-less alternative
const docRef = doc(db, "users", "Nk....WQ")

const docRef = doc(db, "users/Nk....WQ") // path as single argument
const docRef = doc(db, "users/" + id)

const docRef = collectionRef.doc("John") // admin sdk
const docRef = collectionRef.doc("NkJz11WQ")
```

### read single document

at ref, or at id

```tsx
getDoc(docRef)
db.collection("messages").doc(id).get()
```

## Document snapshot

The document snapshot is a wrapper that does not guarantee the document
existence.

When we request a document, we receive a snapshot, which may be empty in the sense of not containing data.

The snapshot still embeds metadata.

The data, if any, is accessible at _snapshot.data(options)_. We may provide a config, though it's unneeded most of the time.

If the snapshot is empty, _snapshot.data()_ returns _undefined_.

Besides, the term snapshot aims to stress that it's a static snapshot of the document rather than a live view over it.

We may subscribe to receive snapshots in realtime on document change.

### work with the snapshot and the underlying document.

check document existence

```tsx
docSnapshot.exists()
```

get the underlying document if it exists.

```tsx
docSnapshot.data() // undefined if document doesn't exist
// typescript infered type: DocumentData | undefined
```

guard against document inexistence (redundant but needed by typescript).

```tsx
if (!data) { .. }
```

we may typecast if collection didn't embed the type.

```tsx
doc as FirestorePlanet
```

### other props and methods

requested id, provided ref, resulting metadata.

```tsx
docSnapshot.id
docSnapshot.ref
docSnapshot.metadata
```

get a single property directly through the document snapshot.

```tsx
docSnapshot.get("phoneNumber")
```

# Query



## QuerySnapshot, QueryDocumentSnapshot

the query snapshot contains zero or more documents.

Firestore answers to a query with a query snapshot, regardless if there
are matches or not. The documents it contains, if any, are wrapped
individually as a QueryDocumentSnapshot, which is an API that extends
DocumentSnapshot and that is mostly the same. The difference in this
scenario is that they are always non-empty.

We check if the query snapshot is empty

```tsx
if (querySnaptshot.empty) {
    return []
}
```

The (non-empty) queryDocumentSnapshots, are available at _docs_ as an
array. A queryDocumentSnapshot guarantees it contains an actual
document, due to the context in which the docs array has been built,
with only non-empty snapshots. For simplicity, we may call it a
docSnapshot and we use the DocumentSnapshot API.

```tsx
querySnaptshot.docs

const cats = querySnaptshot.docs.map((docSnapshot) => docSnapshot.data())
```

## Query

## Read data

### read several documents

-   we provide a Query.
-   We receive a querySnapshot

```tsx
getDocs(query(..))
collection(..).where(..).orderBy(..).limit(..).get()
```

### note on getting all documents

A bare collection ref is accepted as a query, and we receive all
documents. It's rarerly used as it's often better to:

specify some order/sorting criteria

limit the number of documents

```tsx
getDocs(collectionRef)
collectionRef.get()
```

## Query

we query a specific part of the collection, aka the documents that match
a criteria or a set of criteria.

```tsx
const q = query(collectionRef, where(..), where(..), orderBy(..), limit(..))

const q = collection(..).where(..).orderBy(..).limit(..)
```

### where

filter documents based on a property whose value must follow a rule. It
filters out the document who do not have this property.

```tsx
where(propertyName, operator, value)
where("id", "==", user.id)
```

operator (provided as string)

```tsx
<
<=
>
>=
==
!=
array-contains // the property is an array and contains the specified value
array-contains-any // the property is an array and contains at least one of the specified values. contains A or B or C ..
in // the property is equal to at least one of the specified value. is equal to A or B or C

not-in // the property must be different from all the specified values. not A and not B and not C.
```

### orderBy

by default, ascending

sort the fetched document by a criteria

```tsx
orderBy(propertyName, orderDirection)
orderBy("postCount") // ascending
orderBy("postCount", "asc")
orderBy("postCount", "desc")
```

### limit

get at most n documents

```tsx
limit(n)
limit(5)
```

### startAt, startAfter

When doing pagingation, we either the store:

the count _n_ of document we already fetched

the snapshot _docSnapshot_ of the document we fetched last

```tsx
startAt(n)
startAt(docSnapshot)

startAfter(n) // does not include n
startAfter(docSnapshot) // does not include docSnapshot
```

### Run the query

We assume we will receive one or more documents, as such, we use the
_getDocs_ function

```tsx
getDocs(query)
query.get()
```

## Real time listener

we may target

a single document with its reference

several documents through a query

we provide a callback as for what to do with the query snapshot or the
document snapshot.

### query real time read

v9

```tsx
const unsub = onSnapshot(query, (qs) => {
    const documents = qs.docs.map((docSnapshot) => docSnapshot.data())
    setMessages(documents)
})
```

### document real time read

```tsx
const unsub = onSnapshot(docRef, (docSnapshot) => {
    console.log("Current data: ", docSnapshot.data())
})
```

# Create and update data



### document creation or override

we provide docRef

    setDoc(docRef, data)
    docRef.set(data)

reference-less document creation

    addDoc(collectionRef, data)
    db.collection("message").add(data)

ref creation utility

```tsx
doc(db, "users", userID, "HSK1", word.character)
doc(collectionRef, word.character)

collection(db, "players")
```

### document partial update

```tsx
updateDoc(docRef, data)
setDoc(docRef, data, { merge: true })

docRef.set(data, { merge: true })
docRef.update(data)
```

delete document document

```tsx
docRef.delete()
deleteDoc(docRef)
```

### mutate a single field

we use the update() function along with a directive on a specific field.

### increment field

```tsx
docRef.update({
    count: FieldValue.increment(),
})
```

### delete field

```tsx
tsxdocRef.update({
    fleet: FieldValue.delete(),
})
```

### sever timestamp for field

this creates a trusted timestamp object. this is not needed when doing
it from admin-sdk, because we may already trust a date created from the
admin environment. Besides, it use firebase specific Timestamp instead
of a multi platform iso date string.

```tsx
docRef.update({
    count: FieldValue.serverTimestamp(),
})
```

### Increment

```tsx
const partialUserDoc = {
    activityScore: increment(1),
}
```

# Firestore Security rules



ruleset

```tsx
rules_version = "2"
```

### firestore scope

```tsx
service cloud.firestore {
    	// ...
    }
```

### database scope

```tsx
match /databases/{database}/documents {
// ...
}
```

### collection's documents scope

set the rule for each document of a collection

```ts
match /collection/{document_id}{
    	// ...
}
match /posts/{post_id}{
    	// ...
}
```

### operations and condition

```tsx
allow operation, operation: if condition;
```

operations

```tsx
read
create
update
delete
```

### authentication and user ID

If the user is authenticated with Firebase Auth, the request comes with
its Firebase Auth user ID (_auth.uid_).

This user ID is the only piece of information we may reasonably trust.

```tsx
request.auth.uid
```

### filtering out unauthenticated users

An attacker may attempt to reach the database without authentication. If
authentication is required, the attempt fails, and does not trigger
billing.

```tsx
if request.auth.uid != null;
```

### document green-flagged for the user ID

a document may have a flag that greenlights the user ID. It may be:

the document's ID, which has been made equal to the matching user ID

```tsx
    match /users/{user_id} {
         allow read: if request.auth.uid == user_id;
    }
```

a document's field, such as _owner_ or _owner_id_, which has been made
equal to the matching user ID

```tsx
    match /diaries/{diary_id} {
         allow read: if request.auth.uid == resource.data.owner_id;
    }
```

### document green-flagged for a user's rank, status, or permission flag

Firebase Auth may not store a user's rank or set of permission flags.

Instead, we store the flags in a firestore document that matches the
auth ID, and make sure the user may not tamper them. We may store them
in the _users_ collection.

_users/xyz_

    {
    email
    uid
    rank: "Game Master"
    }

### fetch the permission, compare with requested document

fetch rank of requester

```tsx
get(/databases/$(database) / documents / users / $(request.auth.uid)).data.rank
```

enforce specific rank

```tsx
    match /characters/{character_id} {
         allow update: if get(/databases/$(database)/documents/users/$(request.auth.uid)).data.rank == "Game Master";
    }
```

complete rule

```tsx
    service cloud.firestore {
      match /databases/{database}/documents {
        // Match each document in the 'characters' collection
        match /characters/{characterId} {
          allow update: if get(/databases/$(database)/documents/users/$(request.auth.uid)).data.rank == "Game Master";
        }
      }
    }
```

enfore user's rank matching requested document rank

    match /overworld_characters/{overworld_character} {
         allow read: if get(/databases/$(database)/documents/characters/$(request.auth.uid)).data.zone == resource.data.zone;
    }

check requested document

    resource.data.uid
    resource.data.zone
    resource.data.required_rank

check payload, data validation

    request.resource.data.uid;
    request.resource.data.age > 0
      // A) user sends a post that mentions himself as uid
      allow create : if request.auth.uid == request.resource.data.uid;
    
      // B) user modifies a post that mentions himself as uid
      // A) he must send a post that still mentions him as uid
      allow update,delete: if
      request.auth.uid == resource.data.uid
      &&
      request.auth.uid == request.resource.data.uid;

check if the request user is an admin

    allow write:
    if get(/databases/$(database)/documents/users/$(request.auth.uid))
    .data.admin == true;

# Storage



```tsx
"firebase/storage"
"firebase-admin/storage"
```

### Google Cloud Storage

Firebase Storage is a wrapper around [Google Cloud Storage](https://cloud.google.com/storage/?hl=en), which is a *cloud storage* service similar to Amazon S3.

It is an *object storage* service because it stores *objects* in a *bucket*.

A firebase project is given a default bucket.

### objects in a bucket

we use the term object instead of file to emphasize some differences:

-   objects are immutable. We may not edit and save an object. We must create a new, distinct object. This is distinct from files that are writable and may change over time. We may overwrite an object with an object of the same name. In that case, we may describe it as a new generation.
-   objects live in a single, flat container, whereas files usually live in a vertical hierarchy of directories. The flat layout allows to split up objects on different machines, which makes it easier for provider to accommodate large storage needs.
-   the flat container is called a bucket. Within a bucket, we may emulate a hierarchy by adding subpaths to file names such as _public/_ in `public/abc.png`

### default's bucket's identifier and URI.

The bucket's name or identifier is a domain that uses the project's name, such as _projectname.firebasestorage.app_. It is unique because the project's name itself is (globally) unique.

```url
projectname.firebasestorage.app
imgtale.firebasestorage.app
projectname.appspot.com # old domain name
```

the extended name or identifier is a fully-fledged URI, and uses the `gs://` prefix.

```url
gs://imgtale.firebasestorage.app
```

We may not query the domain name or the URI as-is, as it only serves as an identifier: the bucket is not accessible in this way.

### specify a bucket

The client SDK picks the default bucket by default.

If we are to use a distinct bucket, we must provide its URI.

```tsx
const storage = getStorage(app, bucketURI)
const storage = getStorage(app, "gs://...")
```

# Object: reference and metadata



### object reference

the object reference does not guarantee the object's existence. We use the reference to upload data and to download the object.

The object reference exposes properties related to the object's location and exposes related references.

```tsx
// location (strings)
bucket
fullPath
name

// reference
parent
root
```

### build a reference

We build the reference by providing the object's name, which is its full path within the bucket. That is, it includes the file extension and the parents' path.

```tsx
ref(storage, objectName)
ref(storage, "tts/2F1ZqipqaG0Mg....KoFq4Izjv.mp3") // a file name
```

### object metadata

firebase gathers the object's metadata in a _[FullMetadata](https://firebase.google.com/docs/reference/js/storage.fullmetadata)_ object, which exposes properties such as the size, the contentType and the creation date.

```tsx
// location (strings)
bucket
fullPath
name

// size, type and time
size
contentType
timeCreated

// objects reference
ref
```

we may fetch the metadata of an existing object:

```ts
const metadata = await getMetadata(fileRef)
```

# List objects



We build a reference to a directory and call `list` or `listAll()`. We access the references in `result.items`

```tsx
directoryRef = ref(storage, "uploads/")

const result = await listAll(directoryRef)
const result = await list(directoryRef, { maxResults: 100 })

result.items // StorageReference[]
```

# Download an object



### general considerations

A download only works if the object exists.

The access control varies based on the download method.

A download to the user computer may involve several steps.

### download a blob (browser) and expose it as a local URL

Downloading a blob is invisible to the user and happens in the background. The browser expects the server to have a CORS header authorizing our domain as part of a whitelist, that we may set with `gsutil`. Otherwise, the browser refuses the operation.

If the browser allows it, it download the data and stores into memory, as a Blob object. 

```tsx
getBlob(fileRef).then((blob) => {
    // create the URL and trigger download imperatively
})
```

We may create a local URL that refers to the blob in memory and trigger a download from that local URL.

### get a download HTTP URL

Alternatively, we may directly request a download URL from Firebase. Such URL remains valid unless explicitely revoked. Access control is done at URL creation time. Once the URL is created, it may be consumed without access control checks.

```tsx
getDownloadURL(fileRef).then(url => ...)
```

The URL points to a Google domain. Such domain does not add CORS headers by default.

### HTTP URL: browser specifics

Due to cross-origin, the browser prevents the user from doing a direct download when clicking on a download anchor tag. Instead, the browser performs a navigation, ignore any `download` attribute.

When we make use of the URL in a media element's `src` attribute, there is no download on the user's filesystem, so the browser display the content immediately even though it's cross-origin.

Due to the absence of the CORS header by default, the browser does not allow fetching the data in the background. We may enable the CORS header if such background download is important.

# Upload an object



### upload some data

The upload operation is an upsert: it creates the object if it does not exist, or override the object if it already exists.

When we build the object's reference, we may make the name unique to prevent an unintended override.

The browser SDK upload method accepts different kind of binary data: a Blob or a File object.

We provide the reference and the data to `uploadBytes()`.

```tsx
uploadBytes(fileRef, file).then((snapshot) => {})
```

### upload's result

On success, we receive the object's metadata and reference, in a _UploadResult_ object.

```tsx
const result = await uploadBytes(fileRef, file)

result.metadata
result.ref
```

# Upload task (advanced)



### working with the upload task

we may track the upload progress. For each tick, we receive a snapshot.

```tsx
const uploadTask = uploadBytesResumable(ref, file)

uploadTask.on(
    "state_changed",
    function (snapshot) {
        let progress = (snapshot.bytesTransferred / snapshot.totalBytes) * 100
        console.log("Upload is " + progress + "% done")
        setProgress(progress)
        switch (snapshot.state) {
            case "paused":
                console.log("Upload is paused")
                break
            case "running":
                console.log("Upload is running")
                break
            default:
                break
        }
    },
    function (error) {},
    function () {
        getDownloadURL(uploadTask.snapshot.ref).then(function (downloadURL) {
            console.log("File available at", downloadURL)
        })
    }
)
```

# Setting the bucket CORS header



Some browser operations require the domain to be whitelisted by the CORS header. We setup firebase to whitelist our domain by providing a `cors.json` config file to `gsutil`.

```json
[
    {
        "origin": ["https://mytale.io", "http://localhost:5173"],
        "method": ["GET"],
        "maxAgeSeconds": 3600
    }
]
```

```bash
gsutil cors set cors.json gs://mytale.firebasestorage.app
```

# Cloud Functions



[reference](https://firebase.google.com/docs/functions/callable?gen=2nd)

## Overview

Cloud Functions is a way to run JS code through Node.js on a server managed by Google.

We assume the server is safe from tampering or leaks.

As such, we may perform server side validation and trigger database mutations. We may store and use API keys and secrets.

Some functions are triggered on HTTP requests. Some functions are triggered by events that happens in the Firebase ecosystem such as the registration of a new user in Firebase Auth.

### Two kinds of functions triggered by an HTTP request.

A `Firebase HTTP` function exposes a regular REST API endpoint. We must craft and send a valid
HTTP request on the client. Once the Cloud Function returns a response, we must parse it.

A `Firebase Callable` function is a pattern where the client SDK and the server SDK do more work as they create and manage the HTTP messages (requests and responses) including managing the authentication data. Such a function may easily deny the request if the user is unauthenticated.

### Create a function

We create functions through the `onCall` or `onRequest` helpers. They both live in the `https` sub-package.

```tsx
import { onRequest, onCall } from "firebase-functions/https"
```

```tsx
onCall(async (request) => {
    return "OK"
})
```

specify region in options object

```tsx
onCall({ region: CLOUD_FUNCTION_REGION }, async (request) => {
    return "OK"
})
```

### Activate functions

Firebase checks the `package.json`'s `main` field to find the file that exports the functions. Such file is usually called `index.js`

```json
{
    "main": "lib/index.js"
}
```

A function is not activated unless it is exported by such file as a named export. Such file usually reexports the function from where it is implemented.

```tsx
export { requestExamples } from "./requestExamples.js"
```

```tsx
export const requestExamples = ...
```

### Write functions in typescript, deploy JS

We must provide functions in JS. The convention is to store TS source code in `src/` and transpile it to JS in `lib/`.

We may ask the build to happen every time we change TS:

```tsx
npm run build:watch // runs tsc --watch
```

## Admin SDK

If the function is to use the firestore service.

```tsx
import { initializeApp } from "firebase-admin/app"
import { getFirestore } from "firebase-admin/firestore"

const app = initializeApp()
const db = getFirestore(app)
```

# Define Callable functions



The callable function checks authentication, triggers internal
functions, and send back the result when it's available, and/or send
back an error if the operation failed. It may stream the response.

## Overview and syntax

### synopsis

```tsx
onCall<T, U, V>(options, callback)
```

### provide a callback to onCall

`onCall`'s main argument is the callback function that we define ourself. We define it async so it returns a promise.

The callback receives a request object as its main argument, of type [CallableRequest](https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.https.callablerequest). Its main properties are _auth_ and _data_. The callback also receives a `response` object, which we may use to stream so chunks.

```tsx
onCall<ReqData, Promise<ResData>, StreamData>(async (request, response) => {
    request.auth
    request.data // ReqData
    response?.sendChunk("abc") // StreamData is string here
    response?.sendChunk("def") // StreamData is string here
    return { example: "" }
})
```

-   `request.auth` is of type `AuthData | undefined`. It is `undefined` when the request is unauthenticated. It has `uid` and `token.email` props.
-   `request.data`'s type is provided by the first type parameter in `onCall<T,U,V>()`, here `ReqData`

The callback returns an object, whose type is provided by the second parameter in `onCall<T,U,V>()`, here `ResData`

### type example

```tsx
interface ReqData {
    character: string
}
interface ResData {
    example: string
}
type StreamData = string
```

### provide settings

we may give onCall an options argument object, of type
`CallableOptions`, a subclass of [GlobalOptions](https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.globaloptions.md#globaloptions_interface), as the first argument. Options include `region`, `concurrency`, `minInstances` and `maxInstances`.

Concurrency sets how many processes a single instance may run in
parallel. By default, it may run multiple processes in parallel, even
when there is a single instance. We may limit the number of process to
one, so that there the server only runs a single process at time, aka
process a single request at a time.

```tsx
const options: CallableOptions = {
    concurrency: 1, // how many
    minInstances: 1,
    maxInstances: 1,
    region: "europe-west1",
}
```

## v1 (deprecated)

### define the function

```tsx
functions.https.onCall(async (data, context) => {
    const auth = context.auth
    const message = data.message
    return { message }
})
```

### the context object

The context object provides the authentication details, if any, such as
the email, and the request metadata such as the IP address, or the raw
HTTP request. It is of type [CallableContext](https://firebase.google.com/docs/reference/functions/firebase-functions.https.callablecontext)

### check authentication

```tsx
if (!context.auth) {
    throw functions.https.HttpsError("unauthenticated", "you must be authenticated")
}
```

## Cloud function patterns and misc

### halt and sends error to client

We provide a specific error code string which belongs to a [predefined list](https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.https.md#httpsfunctionserrorcode). If we omit any argument, it defaults to an _internal error_.

```tsx
throw new HttpsError("unauthenticated", "unauthenticated")
```

### lightweight endpoint: dispatch work

A callable function endpoint must delegate application logic to internal
functions, in order to remain a lightweight and readable function.

### run side effects, return data

the callable function performs side effects and/or returns some data.

### endpoint naming: requestX

using _request_ indicates the server may refuse to perform the action.
It separates the request from the action proper. The action proper may
be performed by an internal function.

we may call the endpoint request*Verb*, and the internal function v*erb*
or _performVerb_.

For example, _requestCreateFleetMission_ calls the _createFleetMission_
internal function.

# Invoke a Callable functions



We get a reference to the callable function, and call it like a regular
function.

### indicate the firebase project

since the client may work with different projects, we must provide the project's ID. We do so by providing the app object which already includes such ID.

### indicate the region

A function may be deployed across multiple regions, so the client must specify which regions it wants.

The region identifier we provide must match the one defined in the callable options.

The option defaults to `us-central1`. If the function lives in europe, we must specify the `europe-west1` location.

### initialize the _functions_ object

```tsx
const functions = getFunctions(app, "europe-west1")
```

### synthesize a caller function

We synthesize it through the `httpsCallable` function.

```tsx
const requestPokemon = httpsCallable<ReqData, ResData>(functions, "requestPokemon")
```

The caller function returns (the promise of) a _result_, of type
`HttpsCallableResult<ResData>`. It is a wrapper over the `data` property it
embeds. It is not similar in shape and content to a HTTP response.

### call and handle the result

we provide a payload, if applicable, of type `ReqData`

```tsx
const result = await requestPokemon({ number: 151 })
```

The response's data, if any, lives in result._data_. It has type of `ResData`

```tsx
result.data
```

Alternatively, call it and handle result with then

```tsx
requestPokemon({ number: 151 })
    .then((result) => {
        result.data
    })
    .catch((error) => {})
```

# HTTP endpoint (REST-API)



### overview

Deal with raw HTTP requests and responses, on the client and on the
server. This mimics the creation and use of a regular REST API.

The server API resembles the ExpressJS API.

We respond with JSON or HTML.

```tsx
export const sayHello = onRequest((req, res) => {
    res.send("Hello from Firebase!")
})
```

### options argument

```tsx
const options = {
region: ""
cors: true,
}
export const sayHello = onRequest(options, (req, res) => {});
```

### ExpressJS concepts and syntax

We may use middleware. Req and res objects have the shape of an expressJS req and res objects.

## Build a REST request

This is not specific to firebase. From a web client, we may use fetch().

We may provide a payload and specify the method as POST.

# Functions on Auth events



Functions that trigger on Auth events

## Blocking functions

### a cloud function runs before the user is created

The Authentication service waits for the function to complete successfully before adding the user. If the function throws, the error is thrown to the client and the user is not created, aka the registration fails.

```tsx
const options: BlockingOptions = {
    region: "europe-west1",
}

export const onRegisterBlocking = beforeUserCreated(options, async (event) => {
    const user = event.data // AuthUserRecord === UserRecord
    // user.uid
    // user.email
    if (user?.email?.includes("@hotmail.com")) {
        throw new HttpsError("invalid-argument", "don't use hotmail")
    }
    // create the user in the database first, then return
    await createDefaultDataForUser(user)
})
```

## Non blocking functions

As of writing, there is no v2 equivalents for `onCreate`.

```tsx
functions.auth
functions.auth.user()
```

Firebase Auth has its own list of users. By default, the database
doesn't have the list of users. It's best to store the users in the
database too.

### return a promise

it's important to return a promise so that the cloud function can return
immediately without waiting the actually promise to resolve or error.

### new user through Auth =\> create user in database

```tsx
import { auth } from "firebase-functions/v1"

export const onRegisterNonBlocking = auth.user().onCreate(async (user) => {
    return db
        .collection("users")
        .doc(user.uid)
        .set(
            {
                uid: user.uid,
                email: user.email,
            },
            { merge: true }
        )
        .then(() => {
            console.log("user created in Firestore: " + user.email)
            return true
        })
        .catch((error) => {
            console.error("Error creating user: ", error)
            return true
        })
})
```

### user deleted in auth =\> delete user in database

```tsx
exports.deleteUserOnFirestore = functions.auth.user().onDelete((user) => {
    return db
        .collection("users")
        .doc(user.uid)
        .delete()
        .then(() => {
            console.log("user deleted from Firestore: " + user.email)
            return true
        })
        .catch((error) => {
            console.error("Error deleting user: ", error)
            return true
        })
})
```

# on Firestore events - functions



```tsx
functions.firestore
functions.firestore.document()
```

Validate the data sent by a user to the database. Make sure they don't
send incorrect data. This helps to preserve data integrity.

```tsx
exports.myFunction = functions.firestore
    .document("my-collection/{docId}")
    .onWrite((change, context) => {
        /* ... */
    })
```

## on Storage events

```tsx
functions.storage
```

the user uploads a file to Firebase Storage

perform data validation and transform

### React to completed files uploads:

```tsx
exports.generateThumbnail = functions.storage.object().onFinalize(async (object) => {
    const fileBucket = object.bucket
    // The Storage bucket that contains the file.
    const filePath = object.name
    // File path in the bucket.
    const contentType = object.contentType
    // File content type.
    const metageneration = object.metageneration
    // Number of times metadata has been generated. New objects have a value of 1.
})
```

[Create a thumbnail for an uploaded image.](https://github.com/firebase/functions-samples/blob/313de92ff1612dd6b3c2ee9320d269aee9b8045d/quickstarts/thumbnails/functions/index.js#L58-L78)

# Environment variables



[https://firebase.google.com/docs/functions/config-env?gen=2nd#env-variables](https://firebase.google.com/docs/functions/config-env?gen=2nd#env-variables)

.env

    OPENAI_API_KEY=xxx

or

    firebase functions:secrets:set OPENAI_API_KEY

### Read from Env

read from inside the cloud function

    process.env

read from secret (callable)

```tsx
const options: CallableOptions = {
    region: "europe-west1",
    secrets: ["OPENAI_API_KEY"],
}

 onCall<RequestPayload, Promise<ResponsePayload>>(
    options,
    async (request) => {
        const openaiKey = process.env.OPENAI_API_KEY

```

```tsx
onRequest(
  { secrets: ["OPENAI_API_KEY"] },
  (req, res) => {
	process.env.
```

### debug secrets

```bash
gcloud secrets list --project <PROJECT_ID>
```

### deployment

the .env file is not versioned. At deployment, firebase sends the .env file to firebase servers.

## v1 (deprecated)

Tell firebase to save a token/key on our behalf so that we can access it
by reference in code, without writing the actual key in code and in git
as a result.

```bash
firebase functions:config:set sendgrid.key="...." sendgrid.template="TEMP"
```

### Read from Env

Firebase exposes the tokens/keys in an object we get through the
config() method.

```tsx
const API_KEY = functions.config().myKey
```

# Debug Functions locally



### run the emulator

the functions may be called by the client

```bash
npm run serve
firebase emulators:start --only functions
```

### call from the client

we opt-in for using the emulated cloud functions

```tsx
connectFunctionsEmulator(functions, "localhost", 5001)
```

### call from an interactive REPL shell

start the shell. it also starts the emulators. It allows to call the functions in an interactive REPL:

```bash
npm run shell
firebase functions:shell
```

Callable function: We provide a payload object with a mandatory `data` property.

```ts
requestArticles({ data: {} })
```

### make a direct HTTP request

The URL follows a specific pattern

```
http://localhost:5001/imgtale/europe-west1/request_articles
```

```bash
curl -s -H "Content-Type: application/json" \
  -d '{ "data": { } }' \
  http://localhost:5001/imgtale/europe-west1/request_articles
```

# Deployment



### deploy functions

```shell
firebase deploy --only functions
```

# Timestamp and dates

### list of interactions

-   client SDK ↔ cloud function

-   client SDK ↔ firestore database

-   admin SDK ↔ firestore database

### list of representation

Date object: clientSDK, adminSDK

Timestamp object: clientSDK, adminSDK, firestore

ISO string: clientSDK, adminSDK, firestore

### (client SDK, adminSDK) ↔ firestore database

The SDK (client or admit) transforms a Date field or a Timestamp field
into a timestampValue ISO date string, before sending it to Firestore.

JS object to send

```tsx
const docRef = await addDoc(collection(db, "users"), {
    first: "John",
    last: "Appleseed",
    born: 1899,
    currentDate: new Date(),
})
```

JSON payload: (double quotes stripped)

```tsx
const payload = {
    streamToken: "MA==",
    writes: [
        {
            update: {
                name: "projects/fir-9-demo-b106a/databases/(default)/documents/users/hreijX....bXuvinA0",
                fields: {
                    first: { stringValue: "John" },
                    last: { stringValue: "Appleseed" },
                    born: { integerValue: "1899" },
                    currentDate: { timestampValue: "2023-10-07T18:47:13.279000000Z" },
                },
            },
            currentDocument: { exists: false },
        },
    ],
}
```

Alternative with Timestamp object:

```tsx
import { Timestamp } from "firebase/firestore"
currentDate: Timestamp.now()
```

JSON payload

```tsx
currentDate: { "timestampValue": "2023-10-07T19:20:40.438000000Z" }
```

As we retrieve the property from Firestore: the Client/Admin SDK receive
it as a Timestamp JSON and instantiate it as a Timestamp object.

The received object date field is a Timestamp object regardless if we
sent a Date object.

Alternative with ISO string:

```tsx
currentDate: new Date().toISOString()
```

JSON payload

```tsx
currentDate: {
    stringValue: "2023-10-07T18:52:37.995Z"
}
```

### client SDK ↔ cloud function

Send a Date or an ISO string date to the cloud function through request
data: the cloud function receives an ISO string.

Send a Timestamp to the cloud function through request data: the cloud
function receives a record object with two properties: seconds and
nanoseconds.

```tsx
date: '2023-10-08T07:54:47.527Z',
isoStringDate: '2023-10-08T07:54:47.527Z'
receivedTimestamp: { seconds: 1696751687, nanoseconds: 527000000 },
```

As such, the cloud function must manually instantiate either a Date or a
Timestamp from the raw data it receives from the ISO string or from the
Timestamp object.

instanciate a Timestamp on cloud functions

```tsx
new Timestamp(receivedTimestamp.seconds, receivedTimestamp.nanoseconds)
```

instanciate a Date

```tsx
new Date(date)
new Date(isoStringDate)
new Date(receivedTimestamp.seconds * 1000)
```

### In the response

date

the server does not send Date fields to the client.

We must transform the date field to a number (getTime()) or as a string
(toJSON()) on the server before sending it back, and then parse back to
a Date manually on the client.

timestamp

the server sends a Timestamp field to the client, but it transforms it
to a two-properties record that contains \_seconds and \_nanoseconds.

We may transform the timestamp field to a number (toMillis()), send it,
then parse back to a Timestamp on the client.



# Cron

### schedule code execution

the _onSchedule_ function expects a time interval string, usually starting with _every_, along with a callback.

v2

```tsx
export const CRON_spawn_rares = onSchedule("every day 00:00", async () => {
  ...
})
```

v1

```tsx
export const computeAndStoreRankingsCRON = functions.pubsub
    .schedule("every 8 hours")
    .onRun(async function (context) {
        const rankings = await computeRankings()
        await db.doc("rankings/rankings").set(rankings)
        return null
    })
```



# GenKit



### overview

Genkit enables interacting with LLM providers through a single, unified interface. It allows us to compose prompts together within a flow. It also offers a UI to test and debug prompts and flows.

### packages

```bash
genkit
@genkit-ai/compat-oai
@genkit-ai/compat-oai/openai # import
dotenv #to embed tokens

#genkitx-openai #deprecated
```

https://github.com/firebase/genkit/tree/main/js/plugins/compat-oai

### quick setup

get an ai provider with `genkit()`

```tsx
import { genkit } from "genkit"
import openAI, { gpt4o } from "genkitx-openai"

const ai = genkit({
    plugins: [openAI({ apiKey: process.env.OPENAI_API_KEY })],
    model: gpt4o,
})
```

### quick request with an inline prompt

The inline prompt may be used for simple usecases or for prototyping.

trigger the request with `generate()` or `generateStream()`. It expects an arguments object, with a `prompt` property, and other optional properties

```tsx
const { text } = await ai.generate({
    prompt: `Pick a number between 222 and 333`,
})
return text
```

### stream the response

We call `generateStream()`. _stream_ is an async iterable, so we may iterate over it with `for await`.

```tsx
const { response, stream } = ai.generateStream({
    prompt: `Pick a number between 222 and 333`,
})

for await (const chunk of stream) {
    process.stdout.write(chunk.text) // debug in stdout
}
// we may still use the complete response
const completeText = (await response).text
```

# .prompt Prompt file



### overview

The prompt file, also called a `dotprompt` file, is a text file with a `.prompt` extension. It contains the prompt, along with some metadata. The metadata lives at the top, in the file's front matter.

### prompt

We may use a fixed prompt or a template prompt:

-   The fixed prompt is not customizable and is used as-is.
-   The template prompt is a piece of text that includes slots, which makes it customizable. The caller provides data to customize the prompt.

```yaml
Translate to english: { { character } }
```

### front matter

the front matter follows a YAML syntax, and provides metadata.

```yaml
---
name: requestExamples
model: openai/gpt-4o
config:
    temperature: 0.5
---
```

### front matter for a template prompt

If the prompt is to receive arguments, we define their name, type and default value in the front matter.

The arguments live in the `input` object. `schema` provides the types, while `default` provides the default values.

```yaml
___
...
input:
	schema:
		character: string
	default:
		character: 我
---

Translate to english: {{character}}
```

### reference the prompt file

We provide the prompt file path. `prompt()` returns an object of type _ExecutablePrompt_.

```tsx
const requestExamples = ai.prompt("requestExamples")
```

### run the prompt file

We may use the handle to trigger the request.

```tsx
// wait for completion
const { text } = await requestExamples({ character: "菠萝" })
// stream
const { stream } = requestExamples.stream({ character: "菠萝" })
```

# Typescript Prompt file



Using typescript to define the prompt allows to type the arguments and benefit from autocomplete for the model name.

We define a prompt with `definePrompt()`:

```tsx
import { ai } from "../utils/ai"
import { gpt41 } from "genkitx-openai"
import { z } from "zod"

export const requestExamples = ai.definePrompt({
    name: "requestExamples",
    model: gpt41.name,
    input: {
        schema: z.object({
            character: z.string(),
        }),
    },
    prompt: `Make 3 example sentences for the character {{character}}.
  Provide the english translation but not the pinyin. Do not comment`,
})
```

### call the prompt

call the prompt and wait for the full response

```tsx
const { text } = await requestExamples({ character: "菠萝" })
```

call the prompt and stream the response

```tsx
const { stream, response } = requestExamples.stream({ character: "菠萝" })

    for await (const chunk of stream) {
        ...
    }
```

Firebase

Repository

Selecting changes

Common workflows

Branches

Remote

Other

# Overview

<div class="bookHeroImage" style="border: currentColor .5px solid;padding: 32px;border-radius: 8px;margin: 8px 0;">
<svg xmlns="http://www.w3.org/2000/svg" width="292" height="92pt" viewBox="0 0 219 92">
    <defs>
        <clipPath id="a">
            <path d="M159 .79h25V69h-25Zm0 0"/>
        </clipPath>
        <clipPath id="b">
            <path d="M183 9h35.371v60H183Zm0 0"/>
        </clipPath>
        <clipPath id="c">
            <path d="M0 .79h92V92H0Zm0 0"/>
        </clipPath>
    </defs>
    <path style="stroke:none;fill-rule:nonzero;fill:#362701;fill-opacity:1" d="M130.871 31.836c-4.785 0-8.351 2.352-8.351 8.008 0 4.261 2.347 7.222 8.093 7.222 4.871 0 8.18-2.867 8.18-7.398 0-5.133-2.961-7.832-7.922-7.832Zm-9.57 39.95c-1.133 1.39-2.262 2.87-2.262 4.612 0 3.48 4.434 4.524 10.527 4.524 5.051 0 11.926-.352 11.926-5.043 0-2.793-3.308-2.965-7.488-3.227Zm25.761-39.688c1.563 2.004 3.22 4.789 3.22 8.793 0 9.656-7.571 15.316-18.536 15.316-2.789 0-5.312-.348-6.879-.785l-2.87 4.613 8.526.52c15.059.96 23.934 1.398 23.934 12.968 0 10.008-8.789 15.665-23.934 15.665-15.75 0-21.757-4.004-21.757-10.88 0-3.917 1.742-6 4.789-8.878-2.875-1.211-3.828-3.387-3.828-5.739 0-1.914.953-3.656 2.523-5.312 1.566-1.652 3.305-3.305 5.395-5.219-4.262-2.09-7.485-6.617-7.485-13.058 0-10.008 6.613-16.88 19.93-16.88 3.742 0 6.004.344 8.008.872h16.972v7.394l-8.007.61"/>
    <g clip-path="url(#a)">
        <path style="stroke:none;fill-rule:nonzero;fill:#362701;fill-opacity:1" d="M170.379 16.281c-4.961 0-7.832-2.87-7.832-7.836 0-4.957 2.871-7.656 7.832-7.656 5.05 0 7.922 2.7 7.922 7.656 0 4.965-2.871 7.836-7.922 7.836Zm-11.227 52.305V61.71l4.438-.606c1.219-.175 1.394-.437 1.394-1.746V33.773c0-.953-.261-1.566-1.132-1.824l-4.7-1.656.957-7.047h18.016V59.36c0 1.399.086 1.57 1.395 1.746l4.437.606v6.875h-24.805"/>
    </g>
    <g clip-path="url(#b)">
        <path style="stroke:none;fill-rule:nonzero;fill:#362701;fill-opacity:1" d="M218.371 65.21c-3.742 1.825-9.223 3.481-14.187 3.481-10.356 0-14.27-4.175-14.27-14.015V31.879c0-.524 0-.871-.7-.871h-6.093v-7.746c7.664-.871 10.707-4.703 11.664-14.188h8.27v12.36c0 .609 0 .87.695.87h12.27v8.704h-12.965v20.797c0 5.136 1.218 7.136 5.918 7.136 2.437 0 4.96-.609 7.047-1.39l2.351 7.66"/>
    </g>
    <g clip-path="url(#c)">
        <path style="stroke:none;fill-rule:nonzero;fill:#f03c2e;fill-opacity:1" d="M89.422 42.371 49.629 2.582a5.868 5.868 0 0 0-8.3 0l-8.263 8.262 10.48 10.484a6.965 6.965 0 0 1 7.173 1.668 6.98 6.98 0 0 1 1.656 7.215l10.102 10.105a6.963 6.963 0 0 1 7.214 1.657 6.976 6.976 0 0 1 0 9.875 6.98 6.98 0 0 1-9.879 0 6.987 6.987 0 0 1-1.519-7.594l-9.422-9.422v24.793a6.979 6.979 0 0 1 1.848 1.32 6.988 6.988 0 0 1 0 9.88c-2.73 2.726-7.153 2.726-9.875 0a6.98 6.98 0 0 1 0-9.88 6.893 6.893 0 0 1 2.285-1.523V34.398a6.893 6.893 0 0 1-2.285-1.523 6.988 6.988 0 0 1-1.508-7.637L29.004 14.902 1.719 42.187a5.868 5.868 0 0 0 0 8.301l39.793 39.793a5.868 5.868 0 0 0 8.3 0l39.61-39.605a5.873 5.873 0 0 0 0-8.305"/>
    </g>
</svg></div>

### traditional save patterns without git

Traditionally we may save a file in-place, or to a new file.

Saving in place is destructive: it does not preserve the old version.

Saving to a new file is not destructive, but leads to another challenge: managing multiple versions of a file, including managing the name and the location. Doing this manually is cumbersome and error-prone.

### saving a project's snapshot

Software projects are made of multiples files, that live in nested directories.

As such, if we want to save a project as to how it was at one point in time, we must save the whole file tree as a snapshot.

The simplest way to save a file tree is to archive it as-is, but it leads to heavy storage footprint, and it clutters the filesystem with duplicates. It requires naming each snapshot with a distinct name, and navigating between different snapshots manually.

### what we want from a versioning software

We want an approach that is more efficient in terms of storage and more convenient in that we don't name or navigate between snapshots manually. We also want the ability to store metadata related to a snapshot, such as a message that describes the changes made compared to the previous snapshot, the snapshot's date and unique ID.

The snapshots must not be stored as-is but instead be stored in a more granular way. The software ensure files are not duplicated: it manages, stores and retrieves files in way that does not require duplication.

The software ensures the snapshot may be reconstructed on-demand.

The software ensure we may conveniently browse and load old snapshots.

### lightweight snapshot: a declarative list of files

We store the snapshot as a declarative list of files (their names) that make up its content, like a shopping list. The software may reconstruct the snapshot based on the list.

In this pattern, the files may live anywhere, for example in a storage area. This allows files to be referred to by several snapshots, and to only be stored once.

When needed, the software fetches the files from the storage and place them (a copy) in a given directory, effectively reconstructing the snapshot.

### edit area

The local directory where we make changes is called the working directory or working tree.

We want the latest snapshot (or rather a copy of its content) to be, by default, present in the working tree so that we may easily edit it and submit a new snapshot for save.

### terminology

to commit means to intentionally save a snapshot. A commit as a name is the term that refers to a given snapshot. Technically it's an object that stores references and metadata.

staging area, also called the index, represents a tentative snapshot,
that is yet to be committed.



# Repository

### the .git directory serves as a repository

Strictly speaking, the git repository is the `.git` directory managed by git. It is hidden by default and lives at the roof of the project. It stores all the data and metadata. The working directory is reconstructed from it.

In a broader sense, we sometimes consider the project's root directory as the repository, the one that includes both the `.git` directory and the working directory.

### enable git versioning in a project

The git init command creates the .git repository and enables git commands.

```shell
git init
```

### .git directory content

files and directories

    COMMIT_EDITMSG
    FETCH_HEAD
    HEAD
    ORIG_HEAD
    config
    description
    index
    packed-refs
    
    hooks/
    info/
    logs/
    objects/
    refs/

### project specific configuration

the configuration file lives at .git/config

```shell
open .git/config
```



# Selecting changes

The ability to select changes and store them temporarily before commit has many benefits and requires the existence of a staging area.

### separation of concern

We keep the working directory and the staging area (index) separate to aknowledge their different role.

### the role of the working directory

The working directory is a playground where changes are not saved, good for exploration and iteration. Its content has no influence on what is saved when we perform a commit.

This allows to keep a file that we don't plan to commit yet or that we never intend to commit. Such file is called _untracked_ if it has never been part of a commit, and _modified_ if it was part of a commit but has changed since. (If the file is added to the staging area, we may not use those adjectives anymore)

### the role of the staging area (index)

The staging area is directly tied to what is saved when we perform a commit. Adding to the staging requires the explicit `git add` command.

This favors explicitness and intent, and flexibility, because we don't have to save everything at once. We may selectively pick files or lines. Such granularity allows to group related changes and separate unrelated ones.

### the index as a temporary storage area for temporary checkpoints

To further the distinction with the working directory, the index has its own storage: it may contain files that not present in the working directory, or a different version.

Such storage may save temporary work as a sort of checkpoint. This allows to iterate on further changes, with the ability to revert to the checkpoint if needed.



# Common workflows

### standard workflow

the standard workflow is as follows:

-   make some changes to one or more files in the working directory
-   select one or more changes, put them in the staging area
-   save the staging area as a commit.

### working directory to staged

this adds both _untracked_ files and _modified_ files to the index. They become _staged_ files.

```shell
git add .
```

We may exclude untracked files, that is, keep untracked files untracked.

```shell
git add -u
```

This is mostly when we do not control the .gitignore and we have local files that we do not want to delete because they serve a purpose, but also do not want to be tracked by git because they are personal or not accepted by the maintainer.

### commit to staged: cleanup the staging area

We may revert the staging area to the clean state of the previous commit. The working tree is unaffected.

We use the _restore_ command, with the _staged_ flag.

```shell
git restore --staged . # tested

git reset .
```

If we are before the first commit, we may remove content from the staging area:

    git rm --cached file
    git reset

### staged to working directory

We may restore the worktree from the index. This may restore a checkpoint or the last commit, depending on the content of the staging area.

The `restore` and `checkout` command implictly restore the worktree from the staged area. We may make it more explicit by setting flags.

```shell
git restore .
git restore --worktree . #same
git restore file
```

```shell
git checkout .
git checkout main.js
```

### commit to working directory

we may use the `restore` command and set the `--source` flag to HEAD.

```shell
git restore --worktree --source=HEAD .
git restore --source=HEAD .
```

old syntax

```shell
git checkout HEAD   -- . 				# the last commit
git checkout v1.2.3 -- .      # tag v1.2.3
git checkout stable -- file   # stable branch
git checkout origin/master -- file  # upstream master
git checkout HEAD^ -- file          # the version before the last commit
```

### committed to staged AND working directory

this reverts both the index and the working directory to the commit version.

It does not affect untracked files, which is a good seperation of concern, and allows to keep them outside of the git ecosystem.

```shell
git reset --hard

git restore --source=HEAD --staged --worktree .
```

### staged to commit

save the staging area as a new commit. It has no effect over the working directory.

```shell
git commit -m "..."
```

we may add modified files and commit them in one command. This has not effect over untracked files, which is different from the usual `git add .`

```shell
git commit -am "initial commit"
```

we may change the message of the last commit - also change the hash

```shell
git commit --amend -m "an updated commit message"
```

### revert the current branch to a previous commit

Restaurer la version de travail, la version staged et la version
sauvegardée depuis la sauvegarde précédente nommée explicitement ou
relativement par le nombre de commit depuis cette sauvegarde.

revenir au commit spécifié explicitement.

```shell
git reset --hard 2bje9dlhash
```

revenir au commit à une distance de N par rapport au dernier commit, ici
l'avant dernier commit.

```shell
git reset --hard HEAD^1
```

### remove untracked files

delete untracked files

```shell
git clean -fd
```

delete untracked files and files present but ignored by git

```shell
git clean -fdx
```

dry run

```shell
git clean -fdn
git clean -fdxn
```



# Branches

A branch points to a commit. The currently selected branch, if any, is the one that HEAD points to.

When we add a commit, the selected branch, and only this branch, is updated to point to the new commit.

As such, branches evolve independently.

We usually merge branches back to main. If main has evolved in a conflicting since then, we decide as to how to solve the conflict, that is, which version of the file prevails.

### list branches

```shell
git branch    # local branches
git branch -a # include remote branches
```

### create, rename, delete branch

creating a branch does not switch to it.

```shell
git branch dev
git branch -m master main
git branch -d dev
```

## Branch switching and stashing

switching to a branch means to have HEAD pointing to the branch, which points to a commit. The idea of switching to a commit is to get a clean working directory and index that match this commit, so we may start working from this snapshot.

This also means that any unsaved work in the working directory or in the index before switching may be lost. As such, we either commit all changes, or use the `stash` technique to locally save the state of the working directory and the staging area.

There is one exception: if we create a branch from the current one and switch into it, our working directory and staging area are not changed. Instead we keep our dirty working directory and staging area. This is because git realizes that both branches point to the same commit for now, and as such, the changes we made still make sense because they change this share commit, and we may use those changes to make the first commit on the distinct branch.

### switch to branch

```shell
git switch dev
git checkout dev
```

### stash and pop

save the working directory and staging area with stash:

```shell
git stash
git switch dev
```

restore the working directory and staging area, assuming we are back on the correct branch. the --index flag restores the staging area as well.

```shell
git stash pop --index
```

### switching to a branch that comes from a remote

if the remote branch such as _origin/dev_ does not have a matching local branch, the git switch command may create the _dev_ local branch and switch into it.

```shell
git switch dev
```

###



# Remote

We upload the .git repository on github. The repository hosted by github becomes the _de facto_ single source of truth. From the point of view of clients, it is a remote.

The remote is identified by its URL. But we give it an alias for convenience. We name this alias `origin`.

### setup an alias

We alias the remote URL as _origin_.

```shell
git remote add origin https://github.com/s3/a33.git
```

### list the aliases

there should be only one, origin

```shell
git remote show
```

### read a specific remote details

read the URL and other details

```shell
git remote show origin
```

### change an alias' URL

change the URL that _origin_ refers to

```shell
git remote set-url origin git@github.com:s3/a33.git
```

### delete a branch on remote

push is because it's an update to the remote repo.

```shell
git push origin --delete 2024
```

## fast forward.

Our local commit is an ancestor of the tentative remote commit. That is,
the remote repo added commits to our local one and reached a final
commit. This means our local commit didn't branch/fork away from the
remote commit, and as such, no merge is applicable or need. We add the
remote commits to our local commit.

If our working tree is "dirty", that is, has uncommited changes, we must
compare it to the tentative new working tree.

### clean and dirty files

Let's called the working tree files we changed "dirty" and the files we
didn't change "clean".

If the fast forward only affect "clean" files, those receive the
commits' changes and are changed to their latest version.

If the fast forward affects "dirty" files, we must decide if we keep our
local dirty files or if we instead pick the new commited version.

### conflit avec la version de travail

Si la version de travail d'Antoine comporte des modifications qui
risquent d'être perdues, car par exemple il a modifié chen.txt, git va
le prévenir et lui proposer soit de commit, soit de stash.

_\> error: Your local changes to the following files would be
overwritten by merge:_

_chen.txt_

_\> Please commit your changes or stash them before you merge._

_\> Aborting_

### utiliser stash pour gérer le conflit

stash notre version de travail, accepter le commit

```shell
git stash
git pull
```

la version de travail est mise dans la version du commit, celui de chen.

tenter de pop le stash

```shell
git stash pop
```

git détecte le conflit entre la version stashed et la version de
travail, celle de chen. Git décide alors d'exposer ce conflit
directement dans le fichier concerné.

```shell
Auto-merging chen.txt
CONFLICT (content): Merge conflict in chen.txt
On branch main
Your branch is up to date with 'origin/main'.

Unmerged paths:
  (use "git restore --staged <file>..." to unstage)
  (use "git add <file>..." to mark resolution)
	both modified:   chen.txt
______

<<<<<<< Updated upstream
4, signed chen
=======
4, signed antoine
>>>>>>> Stashed changes
```

Il suffit alors de modifier le fichier concerné, en décidant quelle
version garder. On fait ensuite git add pour confirmer la résolution.
Enfin, on purge le stash.

```shell
open chen.txt
..
git add chen.txt
..
git stash pop
```

## fetch

update the remote-tracking local branches, such as _origin/main_ and
_origin/dev_

They are listed at: _.git/refs/remotes/origin_

## merge

### merge one branch (ex:dev) to current (ex:main)

We first compare the two branches: the receiving branch (current), and
the giving branch.

If the receiving branch is a parent of the giving branch, that is, it
has not drifted away because it didn't do any commit on its own, then we
can simply fast forward the receiving branch to the state of the giving
branch, making them point to the same commit.

If the receiving branch has done at least one distinct commit, it means
there was an actual fork, and a merge commit is required, to integrate
the branch that has forked, and to preserve the fact that there was a
fork. The merge commit only occurs on the receiving branch.

For example, we merge dev into main. dev is unaffected. main has a merge
commit.

### merge the changes coming from remote

this is what happens when we do git pull (fetch + merge): the _fetch_
updates _origin/main_, then the merge applies a fast forward so that
main and origin/main point to the same commit.

```shell
git merge origin/main
```

### merge a branch into main

```shell
git merge <branch-name>
git merge dev
```

## clone: download and expand the .git directory

### download

a clone download the .git directory.

    https://github.com/mantinedev/mantine.git

we may clone a stripped-out version of the .git directory, one who
contains less files.

For example, we ask the files needed by the last commit, and not the
others. This is called a shallow clone.

We specify the depth, to target only the n-last commits.

```shell
git clone --depth 1 https://github.com/mantinedev/mantine.git
git clone --depth 1 [--branch master] https://github.com/mantinedev/mantine.git
```

### expand

the clone automatically expands the latest commit files into the working
directory.

## branches and remote

### push a new branch to a remote

we must specify

the remote repo we want to push to (here origin)

the branch to push

that this branch will now push by default on that remote

```shell
git push --set-upstream origin en
git push --set-upstream origin dev
```

### indicate the remote branch where to push

this does not indicate the local branch, so it probably push the
currently selected branch.

```shell
git push -u origin beta
```

### indicate match between current local branch and remote branch

```shell
git branch --set-upstream-to origin/my_branch
git branch -u origin/my_branch
```

### remove the branch from the remote

```shell
git push origin --delete beta
```

###



# Other

edit the files without editing the message

    git commit --amend --no-edit

### example

    git init
    git add .
    git commit -m "initial commit"
    git remote add origin https://github.com/s3/aw33.git
    git push -u origin master

### diff

    git diff

affiche le diff qui existe entre differents snapshot. snapshot can be
the working tree, the index, or a tree.

we may show information about a commit, including the diff, wit the git
show command. It shows information about the last commit by default.

    git show

### prune .git folder, prevent some safeguards

### clean : supprimer aussi les untracked files et folders

    git clean -df

supprime les untracked files et directories. En effet, git checkout . ne
permet pas de supprimer les fichiers et directories qui sont untracked,
ramene a leur ancienne version seulement les fichiers tracked.

### log commits, forks and merges

we log the commits of the current branch

    git log

we may display the forks and merge commits

    git log --graph --oneline

### head

Head is which commit the working tree is coming from.

We change the head by checking out a specific commit.

When we check-in a commit that is not tracked by any branch, we say the
head is detached, probably meaning detached from any branch.


Customize a component inline

CSS Module patterns

Global customization

Inner working

Mantine's Style props

Responsive inline props

Light mode, dark mode

Flex

Group

Stack

SimpleGrid

Container

Center

Divider

Space

Paper

Accordion

Appshell

Tabs

Table

Table from data object

TextInput

NumberInput

Button

ButtonGroup

ActionIcon

Native Select

SegmentedControl

Pagination

Modal

Title

Text

Bar Chart

Progress

Notifications

useForm

useLocalStorage

useDisclosure

Default theme

Gray Palette

Dark Palette

Global Style: Colors

Global style: Others

# Overview

<div class="bookHeroImage" style="border: currentColor .5px solid;padding: 32px;border-radius: 8px;margin: 8px 0;"><svg  xmlns="http://www.w3.org/2000/svg" viewBox="0 0 623 163" style="height:calc(2rem * var(--mantine-scale))" class="m_2075ec07"><g fill="none" fill-rule="evenodd"><path fill="#339af0" fill-rule="nonzero" d="M162.162 81.5c0-45.011-36.301-81.5-81.08-81.5C36.301 0 0 36.489 0 81.5 0 126.51 36.301 163 81.081 163s81.081-36.49 81.081-81.5z"></path><g fill="#fff"><path fill-rule="nonzero" d="M65.983 43.049a6.234 6.234 0 00-.336 6.884 6.14 6.14 0 001.618 1.786c9.444 7.036 14.866 17.794 14.866 29.52 0 11.726-5.422 22.484-14.866 29.52a6.142 6.142 0 00-1.616 1.786 6.211 6.211 0 00-.694 4.693c.197.79.546 1.533 1.028 2.186a6.154 6.154 0 008.634 1.284 50.112 50.112 0 007.947-7.39h17.493c3.406 0 6.174-2.772 6.174-6.194s-2.762-6.194-6.174-6.194h-9.655a49.166 49.166 0 004.071-19.69 49.166 49.166 0 00-4.07-19.692h9.66c3.406 0 6.173-2.771 6.173-6.194 0-3.422-2.762-6.193-6.173-6.193H82.574a50.11 50.11 0 00-7.952-7.397 6.149 6.149 0 00-4.578-1.153 6.189 6.189 0 00-4.055 2.438h-.006z"></path><path d="M56.236 79.391a9.342 9.342 0 01.632-3.608 9.261 9.261 0 011.967-3.077 9.143 9.143 0 012.994-2.063 9.06 9.06 0 017.103 0 9.144 9.144 0 012.995 2.063 9.261 9.261 0 011.967 3.077 9.34 9.34 0 01.63 3.608 9.299 9.299 0 01-2.755 6.395 9.094 9.094 0 01-6.388 2.63 9.094 9.094 0 01-6.39-2.63 9.299 9.299 0 01-2.755-6.395z"></path></g><path fill="currentColor" fill-rule="nonzero" d="M291.736 126.644c1.984 0 3.823-.434 5.518-1.302 1.695-.868 2.542-2.129 2.542-3.782v-77.5c0-2.976-.827-5.063-2.48-6.262-1.653-1.199-3.513-1.798-5.58-1.798-1.901 0-3.555.207-4.96.62-1.405.413-2.666 1.24-3.782 2.48s-2.418 3.059-3.906 5.456l-15.252 27.776-15.128-27.776c-1.323-2.397-2.583-4.216-3.782-5.456-1.199-1.24-2.48-2.067-3.844-2.48-1.364-.413-3.038-.62-5.022-.62-1.984 0-3.823.6-5.518 1.798-1.695 1.199-2.542 3.286-2.542 6.262v77.5c0 1.653.847 2.914 2.542 3.782 1.695.868 3.534 1.302 5.518 1.302 2.067 0 3.927-.434 5.58-1.302 1.653-.868 2.48-2.129 2.48-3.782V67.248l14.26 26.784c.744 1.24 1.591 2.087 2.542 2.542.95.455 1.88.682 2.79.682.992 0 1.984-.248 2.976-.744s1.86-1.323 2.604-2.48l14.384-25.792v53.32c0 1.653.847 2.914 2.542 3.782 1.695.868 3.534 1.302 5.518 1.302zm34.375 1.116c4.298 0 7.956-.992 10.974-2.976 3.017-1.984 5.642-4.257 7.874-6.82v3.596c0 1.405.682 2.604 2.046 3.596 1.364.992 3.08 1.488 5.146 1.488 2.232 0 4.092-.496 5.58-1.488 1.488-.992 2.232-2.19 2.232-3.596V91.18c0-4.216-.889-8.143-2.666-11.78-1.778-3.637-4.609-6.613-8.494-8.928-3.886-2.315-9.052-3.472-15.5-3.472-2.894 0-5.87.372-8.928 1.116-3.059.744-5.642 1.798-7.75 3.162-2.108 1.364-3.162 2.914-3.162 4.65 0 1.819.475 3.596 1.426 5.332.95 1.736 2.294 2.604 4.03 2.604 1.074 0 2.066-.33 2.976-.992.91-.661 2.211-1.302 3.906-1.922 1.694-.62 4.112-.93 7.254-.93 2.81 0 4.98.579 6.51 1.736 1.53 1.157 2.645 2.604 3.348 4.34a14.092 14.092 0 011.054 5.332v1.612h-5.084c-5.704 0-10.726.537-15.066 1.612-4.34 1.075-7.73 2.935-10.168 5.58-2.439 2.645-3.658 6.324-3.658 11.036 0 5.621 1.591 9.775 4.774 12.462 3.182 2.687 6.964 4.03 11.346 4.03zm6.448-11.904c-1.819 0-3.369-.537-4.65-1.612-1.282-1.075-1.922-2.77-1.922-5.084 0-2.315.764-4.03 2.294-5.146 1.53-1.116 3.534-1.84 6.014-2.17 2.48-.33 5.084-.496 7.812-.496h1.86v2.604c0 1.984-.6 3.885-1.798 5.704-1.199 1.819-2.666 3.307-4.402 4.464-1.736 1.157-3.472 1.736-5.208 1.736zm84.169 10.788c2.067 0 3.927-.434 5.58-1.302 1.653-.868 2.48-2.129 2.48-3.782V92.172c0-4.63-.971-8.845-2.914-12.648-1.943-3.803-4.526-6.84-7.75-9.114C410.9 68.137 407.345 67 403.46 67c-4.133 0-7.626.971-10.478 2.914-2.852 1.943-4.898 4.113-6.138 6.51v-3.72c0-1.488-.682-2.687-2.046-3.596-1.364-.91-3.038-1.364-5.022-1.364-2.315 0-4.216.455-5.704 1.364-1.488.91-2.232 2.108-2.232 3.596v48.856c0 1.24.744 2.397 2.232 3.472 1.488 1.075 3.39 1.612 5.704 1.612 2.232 0 4.133-.537 5.704-1.612 1.57-1.075 2.356-2.232 2.356-3.472V92.172c0-2.315.496-4.299 1.488-5.952.992-1.653 2.273-2.935 3.844-3.844 1.57-.91 3.183-1.364 4.836-1.364 1.984 0 3.803.558 5.456 1.674 1.653 1.116 2.955 2.5 3.906 4.154a10.52 10.52 0 011.426 5.332v29.388c0 1.653.868 2.914 2.604 3.782 1.736.868 3.513 1.302 5.332 1.302zm47.432 0c2.315 0 4.03-.703 5.146-2.108 1.116-1.405 1.674-2.976 1.674-4.712 0-1.653-.558-3.183-1.674-4.588-1.116-1.405-2.831-2.108-5.146-2.108h-4.836c-2.563 0-4.36-.496-5.394-1.488-1.033-.992-1.55-2.687-1.55-5.084V79.4h14.632c1.323 0 2.335-.6 3.038-1.798.703-1.199 1.054-2.542 1.054-4.03 0-1.488-.351-2.831-1.054-4.03-.703-1.199-1.715-1.798-3.038-1.798H452.38V46.416c0-1.488-.847-2.687-2.542-3.596-1.695-.91-3.534-1.364-5.518-1.364-1.819 0-3.596.455-5.332 1.364-1.736.91-2.604 2.108-2.604 3.596v60.14c0 6.944 1.963 12.028 5.89 15.252 3.927 3.224 9.61 4.836 17.05 4.836h4.836zM487.232 54.6c2.397 0 4.443-.806 6.138-2.418 1.695-1.612 2.542-3.41 2.542-5.394 0-2.15-.847-3.989-2.542-5.518-1.695-1.53-3.74-2.294-6.138-2.294-2.397 0-4.464.765-6.2 2.294-1.736 1.53-2.604 3.369-2.604 5.518 0 1.984.868 3.782 2.604 5.394 1.736 1.612 3.803 2.418 6.2 2.418zm0 72.044c2.232 0 4.133-.537 5.704-1.612 1.57-1.075 2.356-2.232 2.356-3.472V72.704c0-1.488-.785-2.687-2.356-3.596-1.57-.91-3.472-1.364-5.704-1.364-2.315 0-4.216.455-5.704 1.364-1.488.91-2.232 2.108-2.232 3.596v48.856c0 1.24.744 2.397 2.232 3.472 1.488 1.075 3.39 1.612 5.704 1.612zm65.247 0c2.066 0 3.926-.434 5.58-1.302 1.653-.868 2.48-2.129 2.48-3.782V92.172c0-4.63-.972-8.845-2.914-12.648-1.943-3.803-4.526-6.84-7.75-9.114-3.224-2.273-6.779-3.41-10.664-3.41-4.134 0-7.626.971-10.478 2.914-2.852 1.943-4.898 4.113-6.138 6.51v-3.72c0-1.488-.682-2.687-2.046-3.596-1.364-.91-3.038-1.364-5.022-1.364-2.315 0-4.216.455-5.704 1.364-1.488.91-2.232 2.108-2.232 3.596v48.856c0 1.24.744 2.397 2.232 3.472 1.488 1.075 3.39 1.612 5.704 1.612 2.232 0 4.133-.537 5.704-1.612 1.57-1.075 2.356-2.232 2.356-3.472V92.172c0-2.315.496-4.299 1.488-5.952.992-1.653 2.273-2.935 3.844-3.844 1.57-.91 3.182-1.364 4.836-1.364 1.984 0 3.802.558 5.456 1.674 1.653 1.116 2.955 2.5 3.906 4.154a10.52 10.52 0 011.426 5.332v29.388c0 1.653.868 2.914 2.604 3.782 1.736.868 3.513 1.302 5.332 1.302zm47.68 1.116c4.464 0 8.328-.558 11.594-1.674 3.265-1.116 5.786-2.48 7.564-4.092 1.777-1.612 2.666-3.12 2.666-4.526 0-.827-.248-1.798-.744-2.914a8.641 8.641 0 00-2.108-2.914c-.91-.827-1.984-1.24-3.224-1.24-1.158 0-2.398.372-3.72 1.116-1.323.744-2.894 1.53-4.712 2.356-1.819.827-4.092 1.24-6.82 1.24-4.299 0-7.792-1.095-10.478-3.286-2.687-2.19-4.03-5.063-4.03-8.618v-1.86h25.172c1.901 0 3.74-.186 5.518-.558 1.777-.372 3.244-1.323 4.402-2.852 1.157-1.53 1.736-4.071 1.736-7.626 0-4.63-1.199-8.68-3.596-12.152-2.398-3.472-5.518-6.2-9.362-8.184-3.844-1.984-8.08-2.976-12.71-2.976-5.043 0-9.61 1.137-13.702 3.41-4.092 2.273-7.358 5.29-9.796 9.052-2.439 3.761-3.658 7.874-3.658 12.338v10.54c0 5.043 1.281 9.486 3.844 13.33 2.562 3.844 6.096 6.82 10.602 8.928 4.505 2.108 9.692 3.162 15.562 3.162zm4.092-35.836h-18.104v-3.472c0-1.984.516-3.7 1.55-5.146 1.033-1.447 2.376-2.563 4.03-3.348 1.653-.785 3.43-1.178 5.332-1.178 1.984 0 3.802.413 5.456 1.24 1.653.827 2.976 1.984 3.968 3.472s1.488 3.183 1.488 5.084c0 1.323-.269 2.211-.806 2.666-.538.455-1.509.682-2.914.682z"></path></g></svg></div>

[Mantine](https://mantine.dev/) provides pre-styled React components.

### overall benefits

-   solid, unremarkable, neutral, functional style (UI)
-   easy-to-use and consistent API (DX)
-   rapid development of utilitarian and productivity apps

### default overall style

The default overall style is functional, neutral and minimalist.

### mantine style is opinionated and cohesive

Mantine provides a set of cohesive style defaults.

If we do override part of it, we should ensure our changes are compatible with the Mantine overall look.

### unstyled components

Mantine provides an unstyled version of its components, but such pattern requires to come up with a comprehensive style replacement.

### components and component variants

Mantine provides components, and for some of them, provides variants. For example,
it provides the Button component along with the _outline_ and _filled_ Button variants.

### component inner structure

a component is constructed through several, named, inner-components.
For example, the Slider is built upon a _mark_, a _track_ and a _bar_. Mantine allows us to target and style the inner-components.

### links

-   [components source code](https://github.com/mantinedev/mantine/tree/master/packages/%40mantine/core/src/components)



# Customize a component inline



### inline customization

We customize (the given instance of) a component inline, directly where the component is used, so that only this instance is affected, with no side-effect.

### styling a DOM element (not Mantine specific)

There are two ways to style a given DOM element:

-   provide style in the _style_ attribute
-   mark an element with an id, a class, or a custom attribute, and provide style for those in a .css file. Such option allows to provide state-specific style:

```css
.beautifulLink {
}
.beautifulLink:hover {
}
/* .. */
```

### Mantine's role

Mantine's role is to translate the style we provide into style that lives either in the _style_ attribute, or either into a .css file.

### Mantine's universal _style props_

Mantine's style props are a set of props that we may set on any Mantine component. Mantine translates such props into style that lives in the _style_ attribute. If the component is made of nested DOM elements, the styles lives in the top-level DOM element's _style_ attribute.

```tsx
<Box m={4}></Box>
// translates to
<div style="margin:4px;"></div>
```

### Mantine's component-unique props

Mantine exposes props that are unique to some components or to a single component. Such props may determine the component's structure by enabling inner-components. For example, the _TextInput_ exposes a _label_ prop that will, if provided, add a _label_ DOM element with the provided text:

```tsx
<TextInput label="Username"></TextInput>
// add a <label> element.
<label>Username</label>
```

### target an inner-component

We target an inner-component by its name, and provide a style object or one or more classes.

_styles_ allows to provide a style object:

```tsx
 <Button
	styles={{
        root: { backgroundColor: 'red', height: 16},
        label: { color: 'blue' },
      }}
```

_classNames_ allows to provide classes:

```tsx
<Button
    classNames={{
        root: "primarybutton-root",
        label: "primarybutton-label",
    }}
/>
```

reminder: the benefit of classes is the ability to provide state-specific style.

```css
.primarybutton-root {
}

.primarybutton-root:hover {
}
```

### class naming pattern

We are customizing a Mantine's component, effectively creating a variant. We build the class name with the variant name and the inner-component name.

```css
.pinkbutton-root {
}
.pinkbutton-label {
}
```

# CSS Module patterns



A CSS module is a CSS file where class names are processed so that they may not clash with other stylesheets classes.

A CSS module should not trigger global style changes such as targeting the :root element or any other html element.

Instead, the CSS module should only provide style through classes. We may retrieve such classes by importing the object that contains those classes, from a React component that intends to make use of one or more classes.

```tsx
import classes from "xxx.module.css";

<Button
classNames={{
        root: classes.xxx,
        label: classes.xxx,
    }}
  >
```

### one module to one Mantine's component pattern

In this pattern, the CSS Module provides style for a specific Mantine component such as `Button`: we effectively create a variant of it, such as a primary button. As such, we may name the CSS Module with the variant name: `PrimaryButton.module.css`

We name the classes directly with the inner-component name we want to target.

```css
/* PrimaryButton.module.css */
.root {
}

.root:hover {
}

.label {
}
```

```tsx
import PrimaryButtonClassNames from "PrimaryButton.module.css";
{/* provide properties */}
<Button
classNames={{
        root: PrimaryButtonClassNames.root,
        label: PrimaryButtonClassNames.label,
    }}
  >
```

### provide the classes object directly

When we follow this pattern, we may provide the classes object to `classNames`.

```tsx
<Button classNames={primaryButtonClassNames}>
```

# Global customization



Global customization, or theming, is when we set some style that will affect all instances of one or more Mantine component within a project.

### implement a global Mantine class

Mantine applies some classes on all instances of a given Component. We may implement such classes to affect all instances.

For example, `mantine-Button-root` is applied on instances' root component, while `mantine-Button-label` is applied on instances' label component.

```css
.mantine-Button-root {
    border-width: 0.5px; /* influences all Button instances */
}
```

The empty classes have the same priority as classes used by Mantine to provide its style. To give more priority to the classes we implement,
we must implement them in a stylesheet with higher priority. That is, we
import our stylesheet after Mantine's.

### set style primitives in the global theme

#todo

# Inner working



This is how Mantine implements and ships `<Button>`

[sourcecode (unbuilt)](https://github.com/mantinedev/mantine/tree/master/packages/%40mantine/core/src/components/Button)

### html elements structure

-   the innermost span contains only text
-   the intermediate _inner_ span contain icons and the innermost span
-   the root contains the _inner_ span, and may probably replace it on
    loading state.

```pug
button // root
	span // inner
		span // label
			text
		span
	span
button
```

layer terminology and empty classes

```pug
root // mantine-Button-root
	inner // mantine-Button-inner
		label // mantine-Button-label
			text
		label
	inner
root
```

mantine-implemented classes and empty classes

```tsx
<button class="m-77c9d27d mantine-Button-root .." type="button">
    {" "}
    // root
    <span class="m-80f1301b mantine-Button-inner">
        {" "}
        // inner
        <span class="m-811560b9 mantine-Button-label"> // label Save</span>
    </span>
</button>
```

### class analysis

All those classes appear on root, which here is the \<button\> element.

```tsx
m-87cf2631				// Mantine implementation class, (UnstyledButton)
m-77c9d27d				// Mantine implementation class, (Button)

mantine-UnstyledButton-root	// empty class
mantine-Button-root					// empty class

mantine-active
// Mantine implementation class
/*
mantine-active:active {
    transform: translateY(calc(.0625rem * var(--mantine-scale)));
}
*/
mantine-focus-auto	// allows :focus-visible
```

### mantine source style for Button's root:

Mantine's [implementation of _root_](https://github.com/mantinedev/mantine/blob/master/packages/%40mantine/core/src/components/Button/Button.module.css):

```css
.root {
    --button-height-xs: 30px;
    --button-height-sm: 36px;
    --button-height-md: 42px;
    --button-height-lg: 50px;
    --button-height-xl: 60px;

    --button-height-compact-xs: 22px;
    --button-height-compact-sm: 26px;
    --button-height-compact-md: 30px;
    --button-height-compact-lg: 34px;
    --button-height-compact-xl: 40px;

    --button-padding-x-xs: 14px;
    --button-padding-x-sm: 18px;
    --button-padding-x-md: 22px;
    --button-padding-x-lg: 26px;
    --button-padding-x-xl: 32px;

    --button-padding-x-compact-xs: 7px;
    --button-padding-x-compact-sm: 8px;
    --button-padding-x-compact-md: 10px;
    --button-padding-x-compact-lg: 12px;
    --button-padding-x-compact-xl: 14px;

    --button-height: var(--button-height-sm);
    --button-padding-x: var(--button-padding-x-sm);
    --button-color: var(--mantine-color-white);

    user-select: none;
    font-weight: 600;
    position: relative;
    line-height: 1;
    text-align: center;
    overflow: hidden;

    width: auto;
    cursor: pointer;
    display: inline-block;
    border-radius: var(--button-radius, var(--mantine-radius-default));
    font-size: var(--button-fz, var(--mantine-font-size-sm));
    background: var(--button-bg, var(--mantine-primary-color-filled));
    border: var(--button-bd, rem(1px) solid transparent);
    color: var(--button-color, var(--mantine-color-white));
    height: var(--button-height, var(--button-height-sm));
    padding-inline: var(--button-padding-x, var(--button-padding-x-sm));
    vertical-align: middle;

    &:where([data-block]) {
        display: block;
        width: 100%;
    }

    &:where([data-with-left-section]) {
        padding-inline-start: calc(var(--button-padding-x) / 1.5);
    }

    &:where([data-with-right-section]) {
        padding-inline-end: calc(var(--button-padding-x) / 1.5);
    }

    &:where(:disabled:not([data-loading]), [data-disabled]:not([data-loading])) {
        cursor: not-allowed;
        border: 1px solid transparent;
        transform: none;

        @mixin where-light {
            color: var(--mantine-color-gray-5);
            background: var(--mantine-color-gray-1);
        }

        @mixin where-dark {
            color: var(--mantine-color-dark-3);
            background: var(--mantine-color-dark-6);
        }
    }

    &::before {
        content: "";
        pointer-events: none;
        position: absolute;
        inset: -1px;
        border-radius: var(--button-radius, var(--mantine-radius-default));
        transform: translateY(-100%);
        opacity: 0;
        filter: blur(12px);
        transition: transform 150ms ease, opacity 100ms ease;

        @mixin where-light {
            background-color: rgba(255, 255, 255, 0.15);
        }

        @mixin where-dark {
            background-color: rgba(0, 0, 0, 0.15);
        }
    }

    &:where([data-loading]) {
        cursor: not-allowed;
        transform: none;

        &::before {
            transform: translateY(0);
            opacity: 1;
        }

        & .inner {
            opacity: 0;
            transform: translateY(100%);
        }
    }

    @mixin hover {
        &:where(:not([data-loading], :disabled, [data-disabled])) {
            background-color: var(--button-hover, var(--mantine-primary-color-filled-hover));
            color: var(--button-hover-color, var(--button-color));
        }
    }
}
```

### style shipped on npm

the style is mostly the same. It is probably processed by PostCSS. It does not use CSS nesting.

```css
.m_77c9d27d {
    /* zip, the code is the same */
    /* ... */
    /* ... */
    /* ... */
    /* ... */
    /* ... */

  .m_77c9d27d:where([data-block]) {
    display: block;
    width: 100%;
  }

  .m_77c9d27d:where([data-with-left-section]) {
    padding-inline-start: calc(var(--button-padding-x) / 1.5);
  }

  .m_77c9d27d:where([data-with-right-section]) {
    padding-inline-end: calc(var(--button-padding-x) / 1.5);
  }

  .m_77c9d27d:where(:disabled:not([data-loading]), [data-disabled]:not([data-loading])) {
    cursor: not-allowed;
    border: 1px solid transparent;
    transform: none;
  }

  :where([data-mantine-color-scheme='light']) .m_77c9d27d:where(:disabled:not([data-loading]), [data-disabled]:not([data-loading])) {
      color: var(--mantine-color-gray-5);
      background: var(--mantine-color-gray-1);
}

  :where([data-mantine-color-scheme='dark']) .m_77c9d27d:where(:disabled:not([data-loading]), [data-disabled]:not([data-loading])) {
      color: var(--mantine-color-dark-3);
      background: var(--mantine-color-dark-6);
}

  .m_77c9d27d::before {
    content: '';
    pointer-events: none;
    position: absolute;
    inset: -1px;
    border-radius: var(--button-radius, var(--mantine-radius-default));
    transform: translateY(-100%);
    opacity: 0;
    filter: blur(12px);
    transition:
      transform 150ms ease,
      opacity 100ms ease;
  }

  :where([data-mantine-color-scheme='light']) .m_77c9d27d::before {
      background-color: rgba(255, 255, 255, 0.15);
}

  :where([data-mantine-color-scheme='dark']) .m_77c9d27d::before {
      background-color: rgba(0, 0, 0, 0.15);
}

  .m_77c9d27d:where([data-loading]) {
    cursor: not-allowed;
    transform: none;
  }

  .m_77c9d27d:where([data-loading])::before {
      transform: translateY(0);
      opacity: 1;
    }

  .m_77c9d27d:where([data-loading]) .m_80f1301b {
      opacity: 0;
      transform: translateY(100%);
    }

  @media (hover: hover) {
    .m_77c9d27d:hover:where(:not([data-loading], :disabled, [data-disabled])) {
      background-color: var(--button-hover, var(--mantine-primary-color-filled-hover));
      color: var(--button-hover-color, var(--button-color));
    }
}

  @media (hover: none) {
    .m_77c9d27d:active:where(:not([data-loading], :disabled, [data-disabled])) {
      background-color: var(--button-hover, var(--mantine-primary-color-filled-hover));
      color: var(--button-hover-color, var(--button-color));
    }
}
```

It is then processed even more and merged to a gigantic 232kb stylesheet, shipped on npm too, the one we import from our app.

# Mantine's Style props



We may set such props on any Mantine component:

| Prop        | CSS Property              | Theme key                                     |
| ----------- | ------------------------- | --------------------------------------------- |
| **m**       | margin                    | theme.spacing                                 |
| **mt**      | marginTop                 | theme.spacing                                 |
| **mb**      | marginBottom              | theme.spacing                                 |
| **ml**      | marginLeft                | theme.spacing                                 |
| **mr**      | marginRight               | theme.spacing                                 |
| **mx**      | marginRight, marginLeft   | theme.spacing                                 |
| **my**      | marginTop, marginBottom   | theme.spacing                                 |
|             |                           |                                               |
| **p**       | padding                   | theme.spacing                                 |
| **pt**      | paddingTop                | theme.spacing                                 |
| **pb**      | paddingBottom             | theme.spacing                                 |
| **pl**      | paddingLeft               | theme.spacing                                 |
| **pr**      | paddingRight              | theme.spacing                                 |
| **px**      | paddingRight, paddingLeft | theme.spacing                                 |
| **py**      | paddingTop, paddingBottom | theme.spacing                                 |
|             |                           |                                               |
| **bg**      | background                | theme.colors                                  |
| **bgsz**    | backgroundSize            | –                                             |
| **bgp**     | backgroundPosition        | –                                             |
| **bgr**     | backgroundRepeat          | –                                             |
| **bga**     | backgroundAttachment      | –                                             |
|             |                           |                                               |
| **c**       | color                     | theme.colors gray.5 blue blue.7 blue.5 blue.0 |
| **opacity** | opacity                   | –                                             |
|             |                           |                                               |
| **ff**      | fontFamily                | –                                             |
| **fz**      | fontSize                  | theme.fontSizes                               |
| **fw**      | fontWeight                | –                                             |
| **lts**     | letterSpacing             | –                                             |
| **ta**      | textAlign                 | –                                             |
| **lh**      | lineHeight                | theme.lineHeights                             |
| **fs**      | fontStyle                 | –                                             |
| **tt**      | textTransform             | –                                             |
| **td**      | textDecoration            | –                                             |
|             |                           |                                               |
| **w**       | width                     | theme.spacing                                 |
| **miw**     | minWidth                  | theme.spacing                                 |
| **maw**     | maxWidth                  | theme.spacing                                 |
| **h**       | height                    | theme.spacing                                 |
| **mih**     | minHeight                 | theme.spacing                                 |
| **mah**     | maxHeight                 | theme.spacing                                 |
|             |                           |                                               |
| **bgsz**    | backgroundSize            | –                                             |
| **bgp**     | backgroundPosition        | –                                             |
| **bgr**     | backgroundRepeat          | –                                             |
| **bga**     | backgroundAttachment      | –                                             |
|             |                           |                                               |
| **pos**     | position                  | –                                             |
| **top**     | top                       | –                                             |
| **left**    | left                      | –                                             |
| **bottom**  | bottom                    | –                                             |
| **right**   | right                     | –                                             |
| **inset**   | inset                     | –                                             |
|             |                           |                                               |
| **display** | display                   | –                                             |
|             |                           |                                               |
| **flex**    | flex                      |                                               |

# Responsive inline props



### allow an attribute to pick a different value depending on screen size.

Instead of a single value, we provide an object with properties, most of
the time only two properties.

-   The base property provides the mobile value. All iPhones are under 450p
    in width. All non-plus size iPhones are under 400p
-   The xs or sm property provides the value for bigger devices, similar
    to a min-width media query, which applies to either 576p (36em) aka phablets and higher or 768px (48em) aka tablets and higher. iPad
    tablets start at 768px. When setting the breakpoint at sm size, we
    allow the iPads to benefit from the desktop style.

```tsx
<Flex
 direction=	{{ base: 'column',sm: 'row' }}
 gap=		{{ base: 'sm', 	sm: 'lg' }}
 justify=	{{ base: 'sm', 	sm: 'lg' }}
>
```

# Light mode, dark mode



Mantine defaults to light mode: `defaultColorScheme` defaults to `light`.

We may change it to `dark` or `auto`. `auto` is better because it follows the user's color scheme.

```tsx
<MantineProvider defaultColorScheme="auto"></MantineProvider>
```

# Flex



Thin abstraction over a flex div.

Mantine only sets _display: flex_ if nothing else is set.

props:

-   the `direction`, horizontal (_row_) by default. We may set it as vertical (_column_), and switch to horizontal on desktop.
-   the `gap`, defaults to 0, due to matching a regular flex.
-   `justify`, aka main axis alignment, default to _flex-start_, due to
    matching a regular flex.
-   `align`, aka cross-axis alignment, defaults to _stretch_, due to matching
    regular flex.

```tsx
<Flex
 direction=	{{ base: 'column',sm: 'row' }}
 gap=		{{ base: 'sm', 	sm: 'lg' }}
 justify=	{{ base: 'flex-start', 	sm: 'space-between' }}
>
```

# Group



Layout elements horizontally, add some space between them. This is a
high-level abstraction over an horizontal flex. The container spans the whole line.

-   `gap`: defaults to some spacing, as opposed to a regular flex. The default
    spacing is _md_, aka 16px.
-   `justify`: defaults to flex-start. (elements sit at the left)
-   `align`: defaults to _center_ (vertically center), instead of _stretch_
    for regular flex.
-   `grow`: make children same width. It calculates the
    tentative equal width by dividing the remaining space by the number of
    items. It uses this tentative width a max-width for each children.
    Then, it sets flex-grow: 1 on each of them. If there was no limit, the
    bigger items would still be be bigger than the other even after the
    growing process, because each child would receive an equal share of the
    remaining space. Defaults to false. Also activates mono-line.
-   `wrap`: pick between mono-line (_nowrap_) or multi-line flex (_wrap_) and set the _flex-wrap_ property with it. Mantine default to multi-line (_wrap_) whereas a flex-div defaults to _nowrap_.

The subtle differences with a regular flex may not be worth it. The main point could be the use of `grow` to make children of equal width.

# Stack



Layout elements vertically, add some space between elements.

A thin abstraction over a flex: it only adds a gap and makes the flex vertical (by setting _flex-direction_)

Being a _display:flex_, and regardless of the direction, it occupies the full width. Elements stretch to fill the stack horizontally.

-   `gap`: defaults to _16px_.
-   `justify`: defaults to browser's default: _flex-start_ (elements sit at
    the top),
-   `align`: defaults to browser's default: _stretch_ (elements fill the cross axis horizontally)

# SimpleGrid



A grid with fluid, equal-width tracks: tracks expand horizontally, while being constrained to the same width.

It's common to have a single track for mobile and more tracks for wider screens.

# Container



Act as a wrapper so that inner content, such as the main column of a website, displays nicely, both in desktop and mobile.

In desktop, it centers the content and limit its width. In mobile, it ensures minimum padding.

### limited width container

It claims a minimum padding, limits its own width and centers itself
through margins.

`size`: The max-width. Defaults to _md_ (aka 960px, 60rem). We may pick
720px instead by setting _sm_. If we are to provide an arbitrary numeric
value, we may use _maw_ directly for less indirection.

The default padding is 16px, aka _md_. We may set it with `px`.

### fluid container

We may opt for a fluid container: the container spreads to
occupy the whole width of its parent. It still brings some padding.
For that, we add `fluid` or set _size_ to 100%.

This is overkill because we may use a div with some padding instead.

# Center



A utility component that "CenterCenters" the child or children.

It translates to a div with _display:flex_ and:

-   _justify-content_: center
-   _align-items_: center

### vertical-centering and height

To activate vertical centering, we must set the
Center's height bigger than the inner content.

### horizontal-centering and width.

As a regular div, it occupies the whole parent's width. As a display:flex, it makes children adopt a `max-content` width.

# Divider



A line that acts as a separator/divider.

Similar to the \<hr\> element in usage, at least for the horizontal
version.

May be used as a horizontal line or a vertical line/divider.

Technically, Mantine uses an empty element whose border acts as the
visible line. The _size_ determines the line's size.

The line's default color is?

The line does not have any margin by default, we use _my_ or _mx_, or
set the spacing at the parent level.

-   `orientation`: set the line orientation, "horizontal" (default), or
    "vertical".
-   `size`: set the line thickness, _xs_ by default, aka 1px.
-   `variant`: set a line variant: solid (default), dashed or dotted

# Space



Add some space at a location in the layout. Abstraction over a div on
which we set some size. It defaults to size 0.

-   `h`, set the height, to set the vertical space, usually in a stack-like
    layout.
-   `w`, set the width, to set the horizontal space, usually in a horizontal
    flex-like layout.

# Paper



Encapsulate some UI to set it apart visually.

Paper sets a fill-color background.

In light mode, it sets a plain white \#FFF background. This matches the
light mode default background. As such, we either change the light mode
default background, or change the Paper background.

In dark mode, it sets a _dark.7_. Similarly, it matches the dark mode
default background. As such, we either change the dark mode default
background, or change the Paper background.

In addition to the background, we may set a pre-styled border and/or a
pre-styled shadow.

We usually add some padding, but nothing specific to Paper.

### props

-   `radius`, sets the background area radius. defaults to _sm_, aka 4px.
-   `shadow`, sets the size of a predefined shadow, if any. defaults to
    _none_.
-   `withBorder`, toggles a predefined border. defaults to _false_

# Accordion



### For each item, show a preview and allow disclosure of a detail panel.

The Accordion may contain one or several items, related or not. An item
shows up as a clickable preview (_Accordion.Control_) and embeds a
panel, hidden by default, that we toggle through clicking on the
preview.

In Mantine, the panel remains mounted regardless if it's toggled on or
off.

In Mantine, we set the chevron at the Accordion root, so it's shared
among all items

The panel may be a form. In that case, we may set the chevron as a plus
sign, to indicate we intend to add (submit) data to the server.

```tsx
Accordion variant="separated" chevron={<IconPlus/>}
	Accordion.Item value="item1"
		Accordion.Control
			Log Workout
		Accordion.Panel
			Content

	Accordion.Item value="item2"
		..
```

# Appshell



### overview

-   manages the banner (header)
-   manages the sidebar
-   embeds the main section

### Appshell.Header

The app's banner that stands ontop.

-   manages the burger button.
-   manages the logo.
-   manages the dark/light mode toggle

### header config

_header_ is a prop of AppShell

set the height:

```tsx
header={{ height: 70 }}
```

### Appshell.Navbar

manages the left-side navbar

-   the navbar is hidden by default on mobile. When it is open, it takes the full width.
-   we open and close it by toggling _collapsed_ (to false or true). We
    track the state in a variable such as _opened_ and give it to
    _collapsed_. The burger button, should toggle _opened_ to true.
-   in desktop, it's better to always show up the navbar. By default, the navbar always shows up: it ignores the _opened_ variable given in _collapsed_, because we scoped it to _mobile._ _breakpoint_ determines
    when it goes into desktop mode. _width_ determines its desktop width.
-   we can create a distinct state variable to track the open state in
    desktop, or the use same as the mobile and provide it in _collapsed_, to the _desktop_ key.

### navbar config

_navbar_ is a prop of AppShell

-   width
-   breakpoint: from what size onward should we display the navbar
    unconditionally, aka activate desktop mode. For example, _sm_, which
    includes desktop mode for tablets. (see meaning of _sm_ for breakpoint
    later)
-   collapsed, for mobile (can also work for desktop),

```tsx
navbar={{ width: 300, breakpoint: 'sm', collapsed: { mobile: !opened } }}
```

### Appshell.Section: implement top and bottom sections

```tsx
<AppShell.Navbar>
    <AppShell.Section grow> </AppShell.Section>
    <AppShell.Section> </AppShell.Section>
</AppShell.Navbar>
```

### Appshell.Main

The container for the main panel. It's appropriate to set the main
panel's background color here.

For light mode, the background is white.

We may pick a light gray such as _gray.1_, to allow white Papers to
standout.

For dark mode, the background is dark.7???

```tsx
<AppShell.Main bg={colorScheme === "dark" ? "dark.8" : "gray.1"}>{children}</AppShell.Main>
```

### Configure subcomponents at Appshell level

the configuration object is required for each subcomponent.

```tsx
<AppShell
      header={{ .. }}
      navbar={{ .. }}
      padding="md"
>..subcomponents..</AppShell>
```

### Subcomponents, as children

```tsx
AppShell.Header
AppShell.Navbar
AppShell.Main
```

### related components

```tsx
Burger
useDisclosure
```

# Table



### Abstract

A table is supposed to work with an array of items

    an array						<=> a table
    an item							<=> a row
    an item's property              <=> a cell

example data

```tsx
;[
    { position: 6, mass: 12.011, symbol: "C", name: "Carbon" },
    { position: 7, mass: 14.007, symbol: "N", name: "Nitrogen" },
    { position: 39, mass: 88.906, symbol: "Y", name: "Yttrium" },
    { position: 56, mass: 137.33, symbol: "Ba", name: "Barium" },
    { position: 58, mass: 140.12, symbol: "Ce", name: "Cerium" },
]
```

### Overall structure

```tsx
Table
	Table.Thead
		Table.Tr
			Table.Th
			Table.Th
			Table.Th
	Table.Tbody
		Table.Tr
			Table.Td
			Table.Td
			Table.Td
		Table.Tr
			Table.Td
			Table.Td
			Table.Td
		...
```

### the table head contains labels

Thead contains labels.. A _th_ defines the label for that column.

### the table body contains data, a row represents a record.

Tr represents a record. Each value is displayed in a distinct Td cell.

### Regular rows

Fill the cell out of a property

```tsx
<Table.Td>{record.name}</Table.Td>
```

Create a row out of an element, as the container of cells

```tsx
;(record) => (
    <Table.Tr>
        <Table.Td>{record.name}</Table.Td>
        <Table.Td>{record.level}</Table.Td>
        <Table.Td>{record.class}</Table.Td>
    </Table.Tr>
)
```

Create a row list out of an element list, store it in _rows_

```tsx
const rows = records.map((record) => (
    <Table.Tr>
        <Table.Td>{record.name}</Table.Td>
        <Table.Td>{record.level}</Table.Td>
        <Table.Td>{record.class}</Table.Td>
    </Table.Tr>
))
```

the Tbody is the container for the regulars rows. We provide the _rows_

```tsx
<Table.Tbody>{rows}</Table.Tbody>
```

### Header row

    a single label 	    <=> a cell
    all labels			<=> a row

The Thead is the container for the header row.

```tsx
<Table.Thead>
    <Table.Tr>
        <Table.Th>{label1}</Table.Th>
        <Table.Th>{label2}</Table.Th>
        <Table.Th>{label3}</Table.Th>
    </Table.Tr>
</Table.Thead>
```

# Table from data object



Provide complete table data as an object, containing some arrays:

-   Array of labels for the head
-   Array of elements for the body.
-   We cannot provide elements as objects as the properties ordering is
    unclear. We instead provides the elements as arrays of properties, so that each property has a clear order. For the table body, the cell
    content is the property value, and the property name is unused. As such, we represent an element as an array/list of values.

```tsx
const tableData: TableData = {
    caption: "Some elements from periodic table",
    head: ["Element position", "Atomic mass", "Symbol", "Element name"],
    body: [
        [6, 12.011, "C", "Carbon"],
        [7, 14.007, "N", "Nitrogen"],
        [39, 88.906, "Y", "Yttrium"],
        [56, 137.33, "Ba", "Barium"],
        [58, 140.12, "Ce", "Cerium"],
    ],
}
```

transforming an element as an object to an element as an array of values

    (player) => [player.name, player.level, player.class]

### data prop

The table component receives the data in the data attribute. In that
case, it creates all the markup (head, body, rows) automatically.

```tsx
<Table data={tableData} />
```

# TextInput



TextInput extends the Input component.

-   `label` sets the input's main label.
-   `descriptions` sets the secondary label (optional)
-   `placeholder` sets the placeholder text
-   `leftSection` and `rightSection` allow to insert an icon, visually inside the text input.
-   `withAsterisk`

A text input has almost always a label that explains what this input is about.

# NumberInput



Under the hood, It's a text input. This allows more flexibility, such as displaying formatting commas directly in the input.

The value we get is a number or, when it's not possible to infer a number, a string. For example, we get an empty string when the input is empty.

We may customize the input:

-   `allowDecimal`: allow or forbid decimal numbers. Defaults to allow.
-   `allowNegative`: allow or forbid negative numbers. Defaults to allow.
-   `min`, `max`: specify minimum and maximum values. The way it influences the input is determined by `clampBehavior`
-   `clampBehavior`: determine how the value should clamp within the limits. We may forbid input outside the limits (`strict`), clamp after input on `blur` (d), or never clamp (`none`)

As any text input we may have:

-   `label`
-   `description` (secondary label)
-   `placeholder`

```tsx
const [value, setValue] = useState<string | number>("")
return <NumberInput value={value} onChange={setValue} />
```

# Button



An abstraction over a \<button\>.

### props

-   `variant`, set the button overall appearance, such as _filled_, _outline_,
    _subtle_, _gradient_ or _default_. defaults to _filled_
-   `color`, set the button overall color. the coloring depends on the
    variant. defaults to the theme's _primaryColor_, aka Mantine's blue.
-   `leftSection`, `rightSection`, for example for an icon.
-   `size`, to specify two things. First, if it's a _compact_ button with less
    inner space. second, if we want a smaller or bigger font size.
-   `fullWidth`, to fill the parent's width
-   `disabled`, sets the appearance and behaviour to disabled. the disabled
    appearance is the same across all variants.
-   `loading`, sets the appearance to loading, aka loader overlaid on top, and
    the behaviour to disabled. We may customize the loader with loaderProps
    (see Loader component)
-   `gradient`, sets the gradient's colors and direction. It requires using
    the _gradient_ variant.

```tsx
<Button rightSection={<IconDownload size={14} />}>Download</Button>
```

### Button not submitting form by default

Mantine adds _type=button_ on the underlying \<button\>. It prevents the
button from triggering the form submit, when pressed inside a \<form\>.

The idea is for the developer to explicitely set _type=submit_ on the
Button if it is set to submit the form.

### providing an onClick handler

The handler specifies which action to perform on click. This action
usually does not depend on any information related to the click event.

Still, the handler receives the event as an argument. If we define the
handler somewhere else than inline, we must indicate its typing. The
argument it takes is of type Event.

More specifically, the event is of type
`React.MouseEvent<HTMLButtonElement >`.

The `HTMLButtonElement` type parameter indicates the type of the
_target_ of the event, which in this case is a \<button\> element.

The handler is not supposed to return anything.

Handler type signature

```tsx
onClick: React.MouseEvent<HTMLButtonElement> => void
```

shortcut type

```tsx
onClick: React.MouseEventHandler<HTMLButtonElement>
```

# ButtonGroup



We creates a button cluster/group, where the children buttons are
glued-up

We may use _ButtonGroup_ or _Button.Group_

```tsx
<ButtonGroup>
    <Button variant="default">First</Button>
    <Button variant="default">Second</Button>
    <Button variant="default">Third</Button>
</ButtonGroup>
```

we may set the orientation property to vertical if needed.

# ActionIcon



### icon button

ActionIcon serves the "icon as a button" pattern. UI-wise, the idea is
that the icon is expressive enough to be self-explanatory, with no need
for accompanying text, for example the "trash" icon refers to the
"delete" action.

Technically it is a container that is distinct from the icon, that must
be added as a child.

It gives its child icon the behaviour of a button, and it customizes its
appearance according to the selected variant.

-   `variant`: same variants as Button's variants. To get a naked icon effect,
    we select _subtle_ or _transparent_.
-   `size`: the container's size impacts the hover and active zone, and the
    icon scale.

### required child icon

As a wrapper, it impacts the concrete child icon.

We may still set _size_ directly on the child Icon.

```tsx
<ActionIcon variant='default'>
	<IconMail size={14} stroke={..?}/>
</ActionIcon>
```

# Native Select



An abstraction over an HTML _select_ element embedding some _option_
elements. Here, we do not nest actual _option_ elements. Instead, we
provide their data the in the _data_ attribute. For each option, we
provide the _label_ and the _value_.

If the _label_ is the same as the _value_ (not recommended), we may
provide a single string for each option, which act as both _label_ and
_value_.

-   `data`: an array of {label,value} elements.
-   `label`: The label that describes the select

```tsx
const options = [
    { label: "Death Knight", value: "death_knight" },
    { label: "Demon Hunter", value: "demon_hunter" },
]

const options = ["death_knight", "demon_hunter"]
```

```tsx
<NativeSelect label="Class" data={options} />
```

# SegmentedControl



_SegmentedControl_ allows to pick a value among a list of predefined options. In that it resembles a Select control or a Radio button. All options remain simultaneously on-screen , which is typical of a Radio button.

The picked option has a highlight overlay ontop. As the selected option changes, Mantine moves the overlay toward the selection with a smooth animation.

Each option comes with a `label`, which is the user-facing description, and a `value`, which is the unique identifier that represents it, and which we store in the client state. We make the `value` conform to a type union to prevent typos.

We store the options in `data`. We set the initial selection in `value`.

`onChange` is called on user selection and before browser paint. React prevents any change unless we mutate the state accordingly.

```tsx
type AIProvider = "GPT" | "IMAGEN"

const [provider, setProvider] = useState<AIProvider>("GPT")

<SegmentedControl
    radius="md"
    size="sm"
    value={provider}
    bg={"transparent"}
    onChange={(v) => setProvider(v as AIProvider)}
    data={[
        { label: openAILabel, value: "GPT" },
        { label: geminiLabel, value: "IMAGEN" },
    ]}
/>
```

# Pagination



we provide:

-   the `total` number of pages
-   the `value` of the cursor aka selected page number.
-   the `onChange` handler
-   (optional) `withControls`, to show previous and next arrows, defaults to
    true.
-   (optional) `withEdges`, to show first and last arrows, default to false.
-   (optional) `size`, to get bigger or smaller pagination control, defaults
    to _md_
-   (optional) `radius`, to get rounder or squarer controls, defaults to
    _md_

```tsx
const [activePage, setActivePage] = useState<number>(1)
```

```tsx
<Pagination total={10} value={activePage} onChange={setActivePage} />
```

# Modal



The modal is a container for some UI that is conditionally overlaid ontop of the application. It dims the background while opened. We may dismiss it by pressing escape, clicking outside or on the close button.

The modal works with an `opened` prop: it expects a boolean state variable, which effectively controls the display of the modal.

We may get such a boolean state variable with _useDisclosure_, so that we also get access to semantically correct `open` and `close` state mutation methods.

When the user acts to dismiss the modal, Mantine calls the handler we attached to the `onClose` prop: if the dismissal is approved, such handler should mutate the boolean state accordingly.

```tsx
import { useDisclosure } from '@mantine/hooks';
import { Modal, Button } from '@mantine/core';

function Demo() {
  const [opened, { open, close }] = useDisclosure(false);

  return (
    <>
      <Modal opened={opened} onClose={close}>
        {/* Modal content */}
      </Modal>

      <Button .. onClick={open}>
        Open modal
      </Button>
    </>
  );
}
```

The modal has a top section by default. It may have

-   a close button, which we may remove with `withCloseButton={false}`.
-   a `title`, which accepts any React node (not only text).

The inner content usually comes with controls: inputs and a submit button.

# Menu



A menu that gathers a set of controls, that we display conditionally. `Menu` manages the opened state automatically.

The user toggles the menu by clicking the control that lives in `Menu.Target`.

We add a set of `Menu.Item` which are `<button>` under the hood.

We may separate two different sections with `Menu.Divider`. We may give a section a label with `Menu.Label`.

### overall structure

```tsx
<Menu shadow="md">
    <Menu.Target>
        <Button>Toggle menu</Button>
    </Menu.Target>
    <Menu.Dropdown>/* */</Menu.Dropdown>
</Menu>
```

### menu proper

```tsx
<Menu.Dropdown>
    <Menu.Label>Application</Menu.Label>
    <Menu.Item leftSection={<IconSettings size={14} />}>Settings</Menu.Item>
    <Menu.Item leftSection={<IconMessageCircle size={14} />}>Messages</Menu.Item>
    <Menu.Divider />
    <Menu.Label>Danger zone</Menu.Label>
    <Menu.Item leftSection={<IconArrowsLeftRight size={14} />}>Transfer</Menu.Item>
    <Menu.Item leftSection={<IconTrash size={14} />}>Delete</Menu.Item>
</Menu.Dropdown>
```

# Title

Thin abstraction over a heading element. It uses a HTML heading under the hood, _h1_ by default.

It removes the user agent stylesheet's default margin by setting them to 0. It keeps the bold font weight.

The font size, font weight, and line height, come from _theme.headings_.

The default theme defines five font sizes:

-   h5 comes at 16px
-   h4 comes at 18px
-   h3 comes at 22px
-   h2 comes at 26px
-   h1 comes at 34px

We set the heading as follows:

-   `order`: pick the underlying html element, such as _1_ for _h1_. It defaults to h1. Affects the font-size by default.
-   `size`: override the font-size caused by _order_. we pick a size as a number or as a heading in the
    heading hierarchy such as _h5_.
-   `lineClamp`: set the maximum number _n_ of lines. If not set, the browser allow multiple lines for a heading element. If truncation happens, it shows an ellipsis thanks to _text-overflow: ellipsis_.

```tsx
<Title order={3} size={"h5"}>
    Daybreak
</Title>
```



# Text

A container for some text content.

It is a `<p>` element under the hood by default, but we may set it to be another element such as an anchor tag or a span with the `component` prop.

It removes default margins by setting the (vertical) margin to 0.

It comes with some style affecting the font size, the font family and the line height, which is 1.55 by default. We may set it to inherit all those styles instead by adding the `inherit` prop.

```tsx
<Text c="dimmed">Dimmed text</Text>
```



# Box

Utility component that translates to an HTML element, by default div, on
which we may apply style.



# Bar Chart



packages

```pug
@mantine/charts
recharts
```

stylesheet

```tsx
import "@mantine/charts/styles.css"
```

### bar-chart logic

for each index, display one or several bars. We assume one bar for each
index.

### data for a given index

The chart library expects an object for each index. The object contains
raw data. Among this data, we select which property acts as the label.
The remaining properties may act as magnitude.

```tsx
{month: "Jan", workouts: 17},
{month: "Feb", workouts: 18}
```

### indicate data's shape

We indicate:

-   the property that acts as the label, here month
-   for each property that we want to act as a magnitude, we indicate: the
    property's name (here workouts) the color for that bar, and the
    label for that bar.

In the following example, _workouts_ provides the magnitude for the
unique serie.

```tsx
<BarChart
    data={}
    h={300}
    dataKey="month" // key that provides label
    series={[
        // bar(s) configuration
        { name: "workouts", color: "blue.6", label: "Workouts" },
    ]}
/>
```

Each magnitude's property, as it spreads over all the indexes, makes a
distinct serie. For example, the ipadSales, the iponeSales, and the
macSales make each one a distinct serie.

# Progress

### simple progress bar

-   `value`: from 0 to 100
-   `size`: the vertical size, aka how thick it is. Defaults to `8px` through default _md_.
-   `radius`: defaults to `4px` through default _sm_. The default size and radius lead to a perfect semi circle border.
-   `color`: defaults to `blue`
-   `animated`: enable a striped pattern and animate the stripes.
-   `striped`: enable a striped pattern.
-   `transitionDuration`: set the duration of the animation that occurs when the value changes, in ms. Defaults to 100.

```tsx
<Progress value={50} />
```

### compound progress bar • segmented bar

We may have several segments.

-   The container is `Progress.Root`
-   Each segment is a `Progress.Section`
-   We may add a segment label with `Progress.Label`

We may make the label have a smart color with `autoContrast`.

```tsx
<Progress.Root>
    <Progress.Section value={20} color="indigo">
        <Progress.Label>Documents</Progress.Label>
    </Progress.Section>
    <Progress.Section value={50} color="orange">
        <Progress.Label>Photos</Progress.Label>
    </Progress.Section>
</Progress.Root>
```



# Notifications

### setup

```bash
npm install @mantine/notifications
```

```ts
import "@mantine/notifications/styles.css" // here
```

```tsx
<MantineProvider>
    <Notifications />
    {/* Your app here */}
</MantineProvider>
```

```tsx
import { notifications } from "@mantine/notifications"
```

### create notification

we create a notification. We may set:

-   an `id`, if we intend to update this notification later on
-   `loading` to display a spinner
-   `autoClose` to false, to keep the notification on-screen until dismissed. By default, the notification closes automatically. We may set the delay by providing a duration in milliseconds.
-   `position` to set it somewhere else than bottom-right.

`message` is required, while `title` is optional.

```tsx
notifications.show({
    id: task.id,
    color: "white",
    title: "Generating...",
    message: task.prompt,
    autoClose: false,
    loading: true,
    position: "top-right",
    radius: "xl",
    withCloseButton: false,
})
```

### update notification with id

If the update indicates completion, we may show a completion icon, provide a completion text and plan for an auto-close.

```tsx
notifications.update({
    id: task.id,
    color: "gray",
    title: "Image successfully created",
    message: task.prompt,
    icon: <IconCheck size={18} />,
    loading: false,
    autoClose: 2500,
    radius: "xl",
})
```



# useForm

Gather data from user and send it to a server. Send it as-is or after
some (client-side) validation and/or transformation.

In React, a form uses either controlled or uncontrolled inputs. Mantine
provides both options.

The Mantine's _useForm_ hook attempts to provide a convenient way to
specify initial data, and specify validation and/or transformation to
perform on submit.

### Overview

We work with a regular \<form\>, a set of inputs, and a submit button.

We provide initial data in an object (_initialValues_). The user may
edit data through the inputs.

On submit, Mantine collects the data and provide it to the validator
and/or transformer. Then, it provides the processed data to the
callback, in principle for it to send it to the server.

When an initial value has no matching input (invisible, uneditable
property), Mantine still collects it.

### main steps

-   we create a _configuration_ object
-   We compute a configured _form_ object, through
    _useForm_(_configuration_)
-   We generate the form-submit handler with _form.onSubmit(f)_, where f is
    our callback to handle the processed data. The form-submit handler takes
    an event as argument, and is assigned to the \<form\> _onSubmit_
    attribute, which is the react version of standard _onsubmit_.
-   We add attributes to the form inputs so that they interoperate. we
    spread _form.getInputProps(email)_ to add the relevant attributes on the
    input, depending if it is controlled or uncontrolled: _value_ if it is
    controlled, _initialValue_ and _ref_ if it is uncontrolled. They also
    get _onChange_ and _onBlur_.

init form

```tsx
const form = useForm({ // config
  	initialValues: {x: "", y: ""},
	validate: f
	transformValues: (collected) => processed
})
```

form callback

```tsx
function my_callback(data) {
    data.x
    data.y
}

const mantineEventHandler = form.onSubmit(my_callback)
```

wire up

```tsx
form onSubmit={e => mantineEventHandler(e)}
	TextInput label="x" {...form.getInputProps('x')}
	TextInput label="x" {...form.getInputProps('y')}
	TextInput label="x" {...form.getInputProps('z')} // z is not part of initial values, but may still be included if input is changed}
/form
```

### initial value or not.

Mantine collect properties from the initial values, even if there is no
matching input, and even if the value is null or undefined, and provide
them for processing.

If an input is connected to an initial value that does not exist, it is
effectively initialized to undefined, which will generate a React
warning. Mantine will collect the value of that input and associate with
the key provided in form.getInputProps??

### initial value for a TextInput

The initial value for a TextInput should no be null: it triggers a React
warning. It should also not be set to undefined. Instead, we should
initialize to empty string. We may do post-processing in the transformer
to change the empty string to null.

### utils

```tsx
// get current form values
form.values

// Set all or some form values
form.setValues(values)

// Set all form values using the previous state
form.setValues((prev) => ({ ...prev, ...values }))

// Set value of single field
form.setFieldValue("path", value)

// Set value of nested field
form.setFieldValue("user.firstName", "Jane")

// Resets form.values to initialValues,
// clears all validation errors,
// resets touched and dirty state
form.reset()

// Sets initial values, used when form is reset
form.setInitialValues({ values: "object" })
```



# useLocalStorage

`useLocalStorage` exposes an API similar to `useState`, but uses the local storage as a single source of truth. It requires a `key` that describes the local storage entry, and a `defaultValue` for when such entry is missing.

```tsx
const config = {
    key: "default-ai-provider",
    defaultValue: "GPT",
}
```

### synchronous version (opt-in)

When the component mounts, the hook attempts to read a persisted value from the local storage, and initializes the state with it. If the entry is missing, it creates one with `defaultValue`, and initialize the state with it.

```tsx
const config = {
    // ..
    // opt-in for the synchronous version
    getInitialValueInEffect: false,
}
```

### asynchronous version (default)

In the asynchronous version, the hook immediately initializes the state with the default value, to avoid delaying the first paint. The local storage lookup is implemented as an effect that runs later on, after the first paint. Only then it may push the persisted value to the state.

Having the first paint ignoring the persisted value is not always desirable, that's why we may opt-in for the synchronous version.

### exposed API

The hook exposes the state value and the dispatch method. It also exposes a method to remove the entry.

```tsx
const [provider, setProvider, removeEntry] = useLocalStorage<AIProvider>(config)
```

The hook listens for changes in state and updates the local storage accordingly.



# useDisclosure

A wrapper around `useState<boolean>`. It exposes a boolean state variable and provides helper methods which use terminology related to UI elements being opened or closed, such as `open()` and `close()`, in place of `setIsOpened(true/false)`.

```tsx
const [opened, { open, close, toggle }] = useDisclosure(false)
```



# Default theme



The default theme spreads over several categories. We may browse the [default theme](https://v7.mantine.dev/theming/default-theme/).

### spacing

used for:

-   `gap` in Group, Flex, Stack.
-   padding style props such a `p`.
-   margin style props such as `m`, notably for Divider
-   width and height props such as `w` and `h`, notably for Space.

```tsx
xs: 10px
sm: 12px
md: 16px
lg: 20px
xl: 32px
```

### radius

used for:

-   Paper
-   Dialog, Modal, ..
-   Button, Tooltip..

the default radius is `sm`, aka `4px`.

```tsx
"defaultRadius": "sm",
```

mantine provides a lit of sensible values

```tsx
xs: 2px
sm: 4px (d)
md: 8px
lg: 16px
xl: 32px
```

### breakpoints

determines from which point onward to activate desktop mode.

Some behaviour only makes sense in desktop, such as always-on navbar.

The `sm` breakpoint activates desktop mode from 768px onwards.

iPads have at least 768px width. As such, they will activate desktop
mode. iPad users enjoy the desktop UI because their bigger screen make
it reasonable.

```tsx
  "breakpoints": {
    "xs": "36em", // 576px
    "sm": "48em", // 768px
    "md": "62em",
    "lg": "75em",
    "xl": "88em"
  },
```

### font sizes: a set of 5 distinct values.

a set of font sizes, for body text or UI elements other than titles.

used for:

the _fz_ inline prop.

the middle ground _md_ is 16px.

```tsx
"fontSizes": {
    "xs": 12px
    "sm": 14px
    "md": 16px,
    "lg": 18px
    "xl": 20px
  },
```

# Gray Palette

### the gray palette

the gray palette is used in light mode. It has a blue tint (slate gray). It goes from white to very dark gray.

-   `gray.0` white: #F8F9FA
-   `gray.1` white: #F1F3F5
-   `gray.2` white gray: #E9ECEF
-   ...
-   `gray.6` gray: #868e96
-   `gray.7` dark gray: #495057
-   `gray.8` very dark gray: #343A40
-   `gray.9`: very dark gray: #212529

### use in light mode

-   The background is usually pure white. This is the case for the app background, for buttons and for inputs.

-   The background may go darker on hover. This is the case for buttons, and for the options of a select: `gray.1`

-   The text is black:
    -   pure black text:
        -   some headings
        -   body text
        -   input label
        -   button label
    -   gray 9 (readable black for body text)
    -   gray 8 (readable black)
    -   dark 7 (dimmed black)
    -   gray 6 (gray) for secondary text, and input description



# Dark Palette



### the dark palette

the dark palette is used in dark mode. It uses a neutral gray tint since Mantine 7.3. It goes from very light gray to black:

-   `dark.0`: very light gray close to white: #C9C9C9.
-   ..
-   `dark.9`: black: #141414

### use in dark mode

-   The app background is dark 7. We may go darker with dark 8.
-   Controls are lighter: dark 6, and even lighter on hover: dark 5.
    Sometimes, hover goes to a darker background: such as the hovered option in a select control: dark 8.

-   The slider's bar background is dark 4.

-   The text is light:
    -   pure white (bright white for some headings)
    -   dark 0 (readable white for body text)
    -   dark 1 (dimmed white)
    -   dark 2 (very dimmed, secondary text)
    -   For example, we may have a white title and a dark 0 paragraph
-   The button label is pure white, both for _filled_ and _default_ variants.
-   The input's label is dark 0, the input's description is dark 2.
-   The dimmed text is dark 2, such as secondary label, or secondary
    text in general.

### revert to blue tinted dark palette

```tsx
const theme = createTheme({
    colors: {
        dark: [
            "#C1C2C5",
            "#A6A7AB",
            "#909296",
            "#5c5f66",
            "#373A40",
            "#2C2E33",
            "#25262b",
            "#1A1B1E",
            "#141517",
            "#101113",
        ],
    },
})
```

# Global Style: Colors



### body background

-   lightmode: white \#FFF
-   darkmode: dark.7

### body text color

-   lightmode: black \#000
-   darkmode: dark.0

### dimmed text color

dark.2

dark mode

```css
--mantine-color-scheme: dark;
--mantine-primary-color-contrast: var(--mantine-color-white);
--mantine-color-bright: var(--mantine-color-white);
--mantine-color-text: var(--mantine-color-dark-0);
--mantine-color-body: var(--mantine-color-dark-7);
--mantine-color-error: var(--mantine-color-red-8);
--mantine-color-placeholder: var(--mantine-color-dark-3);
--mantine-color-anchor: var(--mantine-color-blue-4);
--mantine-color-default: var(--mantine-color-dark-6);
--mantine-color-default-hover: var(--mantine-color-dark-5);
--mantine-color-default-color: var(--mantine-color-white);
--mantine-color-default-border: var(--mantine-color-dark-4);
--mantine-color-dimmed: var(--mantine-color-dark-2);
--mantine-color-dark-text: var(--mantine-color-dark-4);
--mantine-color-dark-filled: var(--mantine-color-dark-8);
--mantine-color-dark-filled-hover: var(--mantine-color-dark-7);
--mantine-color-dark-light: rgba(36, 36, 36, 0.15);
--mantine-color-dark-light-hover: rgba(36, 36, 36, 0.2);
--mantine-color-dark-light-color: var(--mantine-color-dark-3);
--mantine-color-dark-outline: var(--mantine-color-dark-4);
--mantine-color-dark-outline-hover: rgba(36, 36, 36, 0.05);
--mantine-color-gray-text: var(--mantine-color-gray-4);
--mantine-color-gray-filled: var(--mantine-color-gray-8);
--mantine-color-gray-filled-hover: var(--mantine-color-gray-9);
--mantine-color-gray-light: rgba(134, 142, 150, 0.15);
--mantine-color-gray-light-hover: rgba(134, 142, 150, 0.2);
--mantine-color-gray-light-color: var(--mantine-color-gray-3);
--mantine-color-gray-outline: var(--mantine-color-gray-4);
--mantine-color-gray-outline-hover: rgba(206, 212, 218, 0.05);
--mantine-color-red-text: var(--mantine-color-red-4);
```

# Global style: Others



line-height defaults to 1.55

```css
--mantine-line-height: 1.55;
```

Mantine

Syntax

GitHub Flavored Markdown (GFM)

# Syntax

-   [markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
-   [github guide](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)

### headings

    # H1
    ## H2
    ### H3

### horizontal line

    ---

### inline code

    The call to `fetch()` was breaking the app.

The call to `fetch()` was breaking the app.

### block of code

    ```typescript
    <Box>Hello World!</Box>
    ```

```typescript
<Box>Hello World!</Box>
```

| language specifier |
| ------------------ |
| typescript         |
| javascript         |
| tsx                |
| jsx                |
| bash               |



# GitHub Flavored Markdown (GFM)

it adds features such as code blocks with three backticks. It's the
prevalent syntax, and is adopted by github and discord.


Markdown

React component

Props object

useState

useRef

useEffect

# Overview

<div class="bookHeroImage"  style="border: currentColor .5px solid;padding: 32px;border-radius: 8px;margin: 8px 0;"><svg style="margin:auto;" id="Layer_2"  height="110px" data-name="Layer 2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 202.72 53.91">
  <g id="Layer_1-2" data-name="Layer 1">
    <g>
      <circle cx="29.62" cy="26.66" r="5.64" fill="#087ea4"/>
      <g>
        <ellipse cx="29.62" cy="26.66" rx="28.21" ry="12.7" fill="none" stroke="#087ea4" stroke-width="2.82"/>
        <ellipse cx="29.62" cy="26.66" rx="12.7" ry="28.21" transform="translate(-9.36 18.38) rotate(-30)" fill="none" stroke="#087ea4" stroke-miterlimit="4" stroke-width="2.82"/>
        <ellipse cx="29.62" cy="26.66" rx="28.21" ry="12.7" transform="translate(-8.28 38.98) rotate(-60)" fill="none" stroke="#087ea4" stroke-miterlimit="4" stroke-width="2.82"/>
      </g>
    </g>
    <g>
      <rect x="67.76" y="5.91" width="134.96" height="48" fill="none"/>
      <path d="M72.42,40.95V7.35h14.38c4.21,0,7.36.95,9.46,2.84s3.14,4.45,3.14,7.67c0,2.43-.6,4.5-1.8,6.19-1.2,1.7-3.01,2.9-5.42,3.62,1.46,2.06,2.88,4.21,4.27,6.43,1.39,2.22,2.73,4.5,4.01,6.84h-5.88c-1.17-2.27-2.4-4.49-3.68-6.65-1.29-2.16-2.55-4.14-3.78-5.93h-9.65v12.58h-5.04ZM86.31,12.03h-8.86v11.76h8.86c2.72,0,4.72-.48,6-1.45,1.28-.97,1.92-2.44,1.92-4.43s-.64-3.46-1.92-4.43c-1.28-.97-3.28-1.45-6-1.45Z" fill="#353947"/>
      <path d="M115.4,41.53c-2.3,0-4.32-.53-6.06-1.58-1.74-1.06-3.09-2.53-4.06-4.42-.97-1.89-1.45-4.07-1.45-6.55s.48-4.67,1.45-6.56c.97-1.9,2.32-3.38,4.06-4.44,1.74-1.06,3.76-1.6,6.06-1.6h.53c2.1,0,3.94.52,5.53,1.55,1.59,1.03,2.84,2.52,3.73,4.46s1.34,4.28,1.34,7.02v1.46h-17.74c.29,1.97,1.03,3.52,2.22,4.64s2.75,1.69,4.67,1.69h.48c1.15,0,2.26-.24,3.31-.71,1.06-.47,1.94-1.11,2.66-1.91l2.95,3.12c-1.09,1.17-2.43,2.1-4.02,2.78-1.59.69-3.31,1.03-5.15,1.03h-.53ZM115.26,20.69c-1.71,0-3.14.56-4.28,1.69-1.14,1.13-1.87,2.67-2.17,4.62h12.91c-.14-1.78-.72-3.27-1.74-4.49-1.02-1.22-2.43-1.82-4.24-1.82h-.48Z" fill="#353947"/>
      <path d="M138.68,41.43c-2.53,0-4.49-.65-5.89-1.96-1.4-1.3-2.1-3.02-2.1-5.15s.79-3.88,2.36-5.3c1.58-1.42,4.09-2.14,7.55-2.14h6.53v-.07c0-4.03-1.86-6.05-5.57-6.05-1.55,0-2.86.28-3.92.84-1.06.56-1.92,1.34-2.58,2.35l-3.29-2.66c1.02-1.58,2.37-2.8,4.04-3.65,1.67-.85,3.57-1.27,5.7-1.27h.53c2.94,0,5.31.85,7.1,2.54,1.79,1.7,2.69,4.23,2.69,7.61v14.42h-4.61v-3.91c-.93,1.41-2.12,2.49-3.58,3.25s-3.11,1.14-4.97,1.14ZM139.74,37.16c1.86,0,3.4-.42,4.63-1.26,1.23-.84,2.15-1.98,2.76-3.42v-1.82h-6.34c-1.89,0-3.24.3-4.04.9-.81.6-1.21,1.41-1.21,2.44,0,2.11,1.4,3.17,4.2,3.17Z" fill="#353947"/>
      <path d="M168.94,41.53c-2.3,0-4.34-.5-6.12-1.51s-3.16-2.45-4.16-4.33c-1-1.88-1.5-4.12-1.5-6.71s.5-4.85,1.49-6.73c.99-1.88,2.37-3.33,4.14-4.34s3.82-1.52,6.16-1.52h.53c1.86,0,3.61.48,5.27,1.43,1.66.95,3,2.26,4.02,3.92l-3.72,2.59c-.69-1.09-1.51-1.94-2.47-2.56-.96-.62-2.05-.92-3.26-.92h-.48c-2.08,0-3.72.73-4.91,2.2-1.19,1.46-1.79,3.44-1.79,5.92s.6,4.43,1.79,5.9c1.19,1.47,2.83,2.21,4.91,2.21h.48c1.22,0,2.34-.27,3.36-.82,1.02-.54,1.9-1.27,2.64-2.18l3.46,2.93c-1.07,1.41-2.42,2.52-4.04,3.32-1.62.81-3.37,1.21-5.24,1.21h-.53Z" fill="#353947"/>
      <path d="M194.81,41.26c-2.85,0-5.02-.72-6.5-2.16-1.49-1.44-2.23-3.66-2.23-6.65v-11.33h-4.7v-4.18h4.7v-7.15h4.8v7.15h8.09v4.18h-8.09v10.68c0,1.89.39,3.2,1.18,3.94.78.74,1.94,1.1,3.48,1.1.74,0,1.4-.03,1.98-.1.58-.06,1.19-.14,1.81-.24v4.2c-.64.16-1.36.29-2.16.4s-1.58.16-2.35.16Z" fill="#353947"/>
    </g>
  </g>
</svg></div>

### benefits

-   divide the UI codebase into individual components.
-   combine HTML-like syntax and Javascript into a single file (JSX/TSX).
-   consume components provided by third-party libraries.
-   entrust React to manage the DOM and keep it in sync with the data and state.



# JSX

### overview

JSX is a variant of JS that allows HTML-like snippets:

```tsx
const HiText = <div>Hi</div>
```

We may interweave JS and HTML snippets recursively

```tsx
const HiText = <div>Hi {nickname}</div>
const HiText = <div>Hi {nickname ?? <Spinner />}</div>
```

### start an html-like snippet

HTML-like syntax starts at the first HTML element and ends on it's matching closing element.

```tsx
const HiText = <div>Hi</div>
```

### embed a JS snippet

Within the snippet, we may embed some JS with curly braces.

```tsx
const HiText = <div>Hi {nickname}</div>
const HiText = <div style={st}>Hi</div>
```

### transpile

A transpiler transforms the HTML-like snippets into JS function calls:

```tsx
const hi = <div>Hi</div>
const hi = _jsx("div", { children: "Hi" })
```

### tsx

TSX is the file format for typescript files that contain HTML-like snippets in the same fashion as JSX.



# React component

A React component describes a set of nested elements. Those elements are HTML elements, or React components that ultimately resolve to HTML elements.

```tsx
function Home() {
    return <div>Hi</div>
}
function App() {
    return <Home />
}
```

### consume a React element

```tsx
<App />
```



# Props object

A React component is being passed a single argument: an object containing various properties that we call _props_. By default, it is empty. Any data passed by the consumer as an attribute lives as a _prop_ in the props object.

```tsx
function Home(props) {} // props.x
function Home({ x }) {} // x
```

```tsx
<Home x={3} />
```

### the children prop

When the consumer nests some elements inside the component, React provides such elements to the component, as a single prop called `children`.

```tsx
<Container>
    <div>Hello</div>
    <div>World!</div>
</Container>
```

```tsx
function Container({ children }) {}
```

`children` is a `ReactNode`, even when it is a set of adjacent elements, aka an array of `ReactElement`.



# useState

We request React to create a state variable and give us a view on it as well as a dispatch method which allows to request state changes. It is up to React to account for such requests, update the state and trigger a new render.

### initial value

```tsx
useState<number>(0)
```

### Get the reference and a dispatch method

```tsx
const [count, setCount] = React.useState<number>(0)
```

### call the dispatch method

In the simplest form, the dispatch method expects a raw value.

Alternatively, it expects a callback, which may read the current state value and derive a value from it.

```tsx
setCount(1)
setCount((count) => count + 1)
```



# useRef

### container persisting across renders

-   the container persists until the component unmounts.
-   it holds mutable data.
-   data mutation does not trigger a re-render.
-   it is made of a unique property called `current`.

```tsx
const x = useRef(33)
x.current // 33
x.current += 1 // 34
```

### targeting a DOM element

a child component in the tree may declare itself as the target of the ref:

```tsx
<input ref={myInputRef} />
```

React mutates the reference as soon as the target element has mounted in the DOM. At that point, `current` targets the element, which is an _HTMLElement_. We may provide a more specific type such as _HTMLInputElement_

### Typescript example

```tsx
const myInput = useRef<HTMLInputElement>(null)
// ..
<input ref={myInput}/>
```

Even though `current` holds null before targeting the element, we may omit null from the type parameters.

We may now use the DOM APIs relevant to the specific HTML element.

```tsx
myInput.current.innerText
myInput.current.innerHTML
myInput.current.value
```



# useEffect

### effect

We register an effect with useEffect. The effect is a fancy name for a function that React runs at specific times.

### run effect after first paint...

React runs the effect after the component's first paint, so that it does not block or delay it.

We prioritize UI responsiveness. To avoid any slowdown, the effect we define and register in useEffect runs only after the initial UI has been painted on screen. If some data is missing, we may paint a blank screen, a spinner or a skeleton.

For example, fetch takes a long time to complete, so it cannot block the main UI.

### ...then conditionally

The dependency array signals a dependency that should trigger the effect again on any change to it.

### clean up

React runs the clean up function when the component unmounts.

### synopsis

```tsx
useEffect(effect, dependencies)
```

### effect function

the effect function may not use top level await, because it may not be an async function.

```tsx
function myEffect() {
    /* effect content */

    return /* clean up content */
}
```

### dependencies

```tsx
useEffect(effect, []) // once
useEffect(effect, [x]) // once, then when x changes
useEffect(effect) // on every render
```
