Overview

CLI tool

SDKs

Initialization

Auth Overview

Email account

Identity Provider

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 Cloud function (REST-API)

Functions on Auth events

Functions on Firestore events

Environment variables

Debug Functions locally

Cron jobs

Deployment

Timestamp and dates

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 scales with virtually no limit
-   extensive free-tier and affordable rates
-   extensive docs and well supported by AI models.
-   actively developed and maintained.



# CLI tool

The Firebase CLI tool is important for some workflows:

-   we may run an emulated backend locally to debug it with no incurred cost: authentication, database, and cloud functions.
-   it is the main way to scaffold the cloud functions directory with boilerplate code
-   it is the main way to deploy cloud functions, security rules, and websites if we host them on Firebase.
-   we may browse and manage the Firebase projects linked to the Firebase account.

### the executable

The executable is provided by the _firebase-tools_ npm package. It is invoked as _firebase_:

```bash
npm i firebase-tools
firebase
```

### one-time setup

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

### list projects and select one

```bash
firebase projects:list
firebase use imagetales
```

### project configuration and scaffolding

```bash
firebase init
```

### help

```bash
firebase help
firebase help deploy
firebase help | grep firestore
```

### cloud functions

```bash
firebase functions:list
firebase functions:shell

firebase functions:secrets:access ABC_API_KEY
firebase functions:secrets:set ABC_API_KEY
firebase functions:secrets:destroy ABC_API_KEY

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 emulators to run in `firebase.json`. In absence of such file, emulators will not 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": [
        /* ... */
    ]
}
```

### Google Cloud CLI tool

The tool unlocks some operations not available on the Firebase's one.

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



# SDKs

### client SDK

The client SDK helps to interact with Firebase from unprivileged clients, usually a browser. It may run on Node.js but with lesser capabilities.

    npm i firebase

### admin SDK

The admin SDK helps to interact with Firebase from privileged environments configured with a special, privileged account called a _service account_. The _service account_ belongs to the Firebase project and authenticates the environment.

The _service account_ allows to skip the user-centric authentication workflows and to bypass the client-centric security rules.

Firebase Cloud Functions run on an environment that Google pre-configures with the proper _service account_.

    npm i firebase-admin

The admin and client SDK APIs are similar in shape when applicable.

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

### firebase cloud functions

The firebase CLI scaffolder adds the _firebase-functions_ package as a dependency automatically when we add cloud functions to a project.

```
npm i firebase-functions
```



# Initialization

### config object: credentials

The config object provides the credentials that identify the Firebase project it is part of. The credentials are sent when interacting with Firebase services.

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

### the app object

we compute and store a reference to _app_ to provide it to services such as _auth_ or _firestore_.

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

### environments managed by Google: skip the config

On a server managed by Google, the admin SDK is automatically configured, so we initialize the app config-less:

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



# Auth Overview



### client SDK: user authentication

The client-SDK provides workflows to authenticate the user against Firebase's authentication servers.

### auth object

We store a reference to the _auth_ object for use in various functions auth-related functions or to access `currentUser` . It is initialized with a given `app` object.

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

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

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

### User instance properties

_uid_ uniquely identifies the user. Other properties are optional.

```tsx
uid
email
phoneNumber
displayName
isAnonymous
```

### listen to authentication state changes

We may listen to authentication events and update the app accordingly. Technically, we provide a callback to `onAuthStateChanged`, which is run by Firebase on auth event, and given a `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

We store the authentication status (logged-in or not) 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 add a second state variable to keep track of the loading state, such as `isLoading`. It starts as _true_ and switches to _false_ on the first authentication event.

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

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

### automatic login after registration

If the registration succeeds, the user is automatically logged-in. We may detect the change by listening to _auth.currentUser_. The user remains logged-in in a given browser until a manual logout.

### others

sign-out works for any auth provider:

```tsx
signOut(auth)
```

# Email account



### registration

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

### login

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

### password reset

We may ask Firebase to send a password-reset email. We may customize it in the Firebase console:

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

# Identity Provider



### Google Provider

We have to enable the Google provider in the Firebase console first.

```tsx
const provider = new GoogleAuthProvider()
/*  */
signInWithPopup(auth, provider).then(() => {
    /* we may reload the page */
    window.location.reload()
})
```

# 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
if (auth.currentUser?.isAnonymous)
// auth.currentUser?.providerData.length === 0
```

### convert to an email account

we build an email credential, then link it it to the account.

```tsx
// 1. build an email credential
const credential = EmailAuthProvider.credential(email, password)
// 2. link the credential to the existing account
linkWithCredential(auth.currentUser, credential)
```

# Firestore



### conceptual

Firestore is a noSQL database most similar to MongoDB. It's made of collections and documents.

A _collection_ is set of documents

A _document_ is set of fields. A document may contain 20k fields and 2 megabytes of data.

A _reference_ serves to identify a tentative collection or a tentative document. They are tentative because the reference on its own does not guarantee the existence of what it is referring to.

### references and release notes

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

### import paths and init

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

We init a _db_ object with the config, for use in firestore-related functions.

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

# Collection



## Collection Reference

### collection reference usage

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
```

### use reference for CRUD operations

We provide the document reference for CRUD operations:

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

-   read the document - `getDoc(ref)`

-   update an existing document (it errors if the document is not found) - `updateDoc(ref, data)`

-   delete the document - `deleteDoc(ref)`

### build a document reference

The document's path identifies it uniquely. We provide it either as a single string or build it from multiple strings.

Alternatively, we may provide the collectionRef and the document ID.

We may also let Firestore creates a reference for us. In that case, we only need 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, but it still includes metadata.

The data, if any, is accessible at _snapshot.data(options)_.

We may provide a config, though it's unneeded most of the time.

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
if (!data) { .. }
```

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

### 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



### The result of performing a query

Firestore answers to a query with a query snapshot, even when no match is found.

The query snapshot contains zero or more documents.

The documents, if any, come as a list of QueryDocumentSnapshot, similar to a list of DocumentSnapshot. All document that appear in the list do exist, aka they are not empty document references.

We check if the query snapshot is empty:

```tsx
if (querySnaptshot.empty) {
    // ...
}
```

We extract the list of documents

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

### a query to 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()
```

### build a 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 an object. We must create a new, distinct object. This is different from files that are writable and may change over time. We can technically have a similar outcome by creating a new object and storing it with 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
imagetales.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://imagetales.firebasestorage.app
```

the domain name and the URI do not have a matching HTTP endpoint. If we attempt to visit them, it errors. Instead, they serve as an identifier.

### 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://...")
```

### bucket information

```
gcloud storage buckets describe gs://imagetales.firebasestorage.app
```

# 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.

It hosts properties related to the object's location and 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` or `gcloud storage`.

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

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

gcloud storage buckets update gs://imagetales.firebasestorage.app --cors-file=cors.json

gcloud storage buckets describe gs://imagetales.firebasestorage.app --format="default(cors_config)" # describe the bucket cors config
```

# 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 being 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 happen 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, parse it manually on the server, and parse back the response on the client.

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. They may conveniently deny the request if the user is unauthenticated.

### Create a function

We build functions with the `onCall` or `onRequest` helpers and export them. The helpers live in the `https` sub-package.

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

onCall function example:

```tsx
export const requestExamples = onCall(async (request, response) => {
    /* ... */
})
```

### Activate functions

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

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

A function is not activated unless exported by such file as a named export. It is usually a barrel file, that exports function from where they are implemented.

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

### Write functions in typescript, deploy JS

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

We may make the transpile continuous by watching the typescript files. This helps the emulator to update the cloud functions on the go since it watches the JS functions.

```bash
tsc --watch
```

### admin SDK

functions may interact with firebase services such as databases and storage with a privileged role by using the admin SDK.

```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 may verify the request comes from an authenticated user, perform work
and send back a result or an error. It may stream the response.

## Overview and syntax

### synopsis

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

### provide a callback

We define a callback and provide it to onCall. We define it async so it returns a promise. The connection is kept open until the promise settles.

The callback receives the _request_ object 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 that we may use to stream content.

```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`
-   request's `acceptsStreaming` property indicates if we may stream the response.

The callback usually 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 options

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",
}
```

## Cloud functions patterns

### halt and send an error immediately

We throw an _HttpsError_ instance with specific error code string which follows a [predefined list](https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.https.md#httpsfunctionserrorcode). If we don't provide a specific error, it defaults to an _internal error_.

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

### lightweight file: dispatch work

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

### 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.

## 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")
}
```

# 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 Cloud function (REST-API)



### overview

Deal with HTTP requests and responses on the client and on the
server in a fashion that resembles setting up REST endpoints with an Express.js like API.

We respond with JSON, HTML, or any other format.

```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
        })
})
```

# Functions on Firestore events



```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



### firebase secrets pattern

we provide secrets through the CLI tool. We may then request some cloud functions to expose the secrets as Node.js process environment variables.

```bash
firebase functions:secrets:set ABC_API_KEY
```

### .env file pattern

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

we may set the env variables in a .env file

    ABC_API_KEY=xxx

the .env should not be versioned. At function deployment, the firebase CLI tool sends the .env file to firebase servers.

### read from env

read env within cloud functions

    process.env

callable function: indicate the environment variables dependencies, that firebase should expose on the _process.env_

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

onCall<ReqData, Promise<ResData>>(options, async (request) => {
    const abcKey = process.env.ABC_API_KEY
})
```

onRequest

```tsx
const options = { secrets: ["ABC_API_KEY"] }

onRequest(options, (req, res) => {
    process.env.ABC_API_KEY
})
```

### debug secrets

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

## 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

We may run the functions on their own or all emulators.

```bash
npm run serve
firebase emulators:start --only functions
firebase emulators:start --import=./saved --export-on-exit
```

### connect the client to the emulator

we opt-in to use the emulated cloud functions:

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

### connect a shell to the emulator

The command starts the emulator and connects a CLI REPL shell session to it so that we may trigger the functions from the CLI:

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

call a Callable function from the CLI: we add the request's payload to the mandatory `data` property.

```ts
requestArticles({ data: { name: "Lena" } })
```

### make direct HTTP requests to the emulated functions

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
```

# Cron jobs



### schedule code execution

the _onSchedule_ function expects:

-   a time-interval string, that may start with _every_, such as `every day 00:00`
-   a callback function

v2

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

v1

```tsx
export const computeAndStoreRankingsCRON = functions.pubsub
    .schedule("every 8 hours")
    .onRun(async function (context) {
        // ..
    })
```

# Deployment



### deploy functions

```bash
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.



# 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

Git repository

Editing and staging

Common commands

Branches

Remote

Stashing unsaved work

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

The traditional save pattern is to store 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 safe, but leads to another challenge: managing multiple versions, their names, the storage and the retrieval, which is cumbersome and error-prone.

### software source code specifics

Software source code usually consists of a tree of files that, together, make a whole unit. Compiling the software usually requires to have the whole tree available as-is on the filesystem.

As such, an actionable snapshot is one that comes as a whole.

The naive way to store snapshots is to store the whole file tree for any given file change. This method has a heavy and inefficient storage footprint, due to spreading identical files across snapshots.

### what we want from a versioning software

We want an approach that is more efficient in terms of storage: the snapshots should not be stored as-is, but instead be reconstructed on-demand, with files being fetched from a central storage. The software should keep track of the files that a given snapshot relies on.

We want to conveniently browse and load old snapshots or snapshots from alternative development branches.

We also want snapshots to come with metadata: their date, their unique ID, and the description of changes they bring (commit message).

### lightweight snapshot: a declarative list of files

We have the snapshot as a declarative list of files it is comprised of, like a shopping list.

In this pattern, the files may live anywhere. This allows files to be referred to by any snapshot, and to be stored only once.

The software may reconstruct the snapshot based on the list: the software fetches the files from the storage and build a snapshot mirror.

### edit area

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

Most of the time, it should start as a mirror of the latest snapshot, allowing to work on changes and submit a new snapshot for commit.

Sometimes, it will instead mirror an old snapshot, so that we may run the snapshot as it was, or if we want to branch out from that snapshot onwards.

### other terminology

to commit means to intentionally save a snapshot. By extension, we may refer to a snapshot itself as a commit. In git internals, a commit is the file that stores all the file dependencies and the metadata related to a given snapshot.

The staging area or the staging snapshot, also called the index, is a tentative snapshot. See more in _Selecting changes_.



# Git repository

### the .git directory serves as the git repository

In Git terminology, the git repository is the `.git` directory managed by git. It is a hidden directory that lives at the root of the project. It stores all versioning data.

Because the directory stores all the project's data, we sometimes conflate it with the project directory itself, the one that lives locally and that contains both the working tree and the git repository proper.

### 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
```



# Editing and staging

### separation of concern: working directory and staging area

We keep the working directory and the staging area (index) separate to acknowledge 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 ability to select changes and store them temporarily before commit has many benefits and requires the existence of a staging area.

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 commands

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 line of commits and the last commit on a line

A list of commits can be seen as a line in the sense of a continuous list of snapshots that follow each other. Technically, each commit keeps a reference to its parent (the former commit), so that we may reconstruct a whole line from a given commit.

We may conceptualize a branch as a line of a commits that lead to a tip commit.

There are as many distinct theoretical branches as there are commits, and we may have several actual branches pointing to the same commit.

All it takes to create a branch is to pick a name and decide what commit it points to. This commit becomes the current tip of the branch.

Branches are independent from each others: they allow to work in isolation. When we add a commit, the active branch is updated to point to the new commit, while others are untouched.

### branches that live on the same line: fast-forward compatible

We may say that two branches live on the same line when the longer branch is the continuation of the shorter branch. The tip of the longer branch is a descendant of the tip of the short branch.

To fast forward a branch is to bring it closer to, or at the same point than a longer branch that lives on the same line. Technically, we make it point to a more recent commit on the line.

while the git command we use is called _merge_, there is no graph merge during a fast-forward.

### branches that have forked: eligible for a merge commit

One branch has forked from the other one. The last commit they have in common is the common ancestor. The merge commit is one that aims to merge the paths coming from two parents. As such, it is a special commit that points to two parents instead of one.

Git compares files across the two parents and, when they are different, checks if one of them is _stalled_, aka has not changed since the last common ancestor. In that case, it favors the one that has received work, as it assumes the merge intends to make use of such work.

If both paths have worked on the ancestor version to change it, the merge cannot pick one version on its own. It asks the developer to resolve the difference between the two parents.

### add the merge commit to the receiving branch

Once the merge commit has been created, the merge process doesn't merge the two branches into one, neither does it make both branches point to it.

Instead, the merge commit is only added to the _receiving_ branch. The receiving branch is now "aware" of the two paths that led to the merge commit.

The other branch stays as-is. It is eligible for fast forward toward the receiving branch.

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

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.

## commands

### list branches

```shell
## list branches
git branch
## includes remote-tracking branches
git branch -a
```

### create, rename, delete branch commands

creating a branch does not switch to it.

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

### branch switching

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.

```bash
git switch dev
```

### 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.



# Remote

### instances and the canonical repository.

A remote repository is an instance of the repository that lives at another location.

There is no built-in hierarchy between instances. When there is a conflict, it's up to users to resolve it.

We use a pattern that sets one instance as the source-of-truth, with some flexibility when it needs to be corrected. We name it the _canonical repository_.

In practice, we put the canonical repository on a server known by all team members. Each member pushes changes to it and pulls changes from it.

For example, a member sets up a repository and publishes it to a host such as Github. The hosted repository becomes the _canonical repository_. Then, members clone the repository. _Cloning_ downloads the repository and pre-configures it to be linked with the _canonical repository_.

### remote-tracking branch

the remote-tracking branch mirrors a branch that lives on a remote repository, usually the canonical repository. As a faithful mirror, it is read-only, and only changes through a network call that signals changes.

we may poll the remote repository with `git fetch`. If updates are found, Git downloads the related commits and add them to the remote-tracking branches. We may inspect them like any other branch: we may log the commits and check the differences.

```bash
git log origin/main
git diff main origin/main
```

We may then merge the remote-tracking branch into the local-only one:

```bash
git merge origin/main
```

_git pull_ is a shortcut for _git fetch_ and _git merge_.

### remote

As a Git technical term, a _remote_ is a configured reference to a remote repository. We setup a remote to be able to push and pull from it.

We add a remote through its URL, and give it an alias name for convenience. By convention, we use _origin_ for the main repository remote.

```shell
git remote add origin https://github.com/user333/helloworld.git
```

We may list remotes and show information for a given one. It's usually only _origin_.

```shell
git remote show
git remote show origin

## remote origin
##   Fetch URL: https://github.com/user33/abc.git
##   Push  URL: https://github.com/user33/abc.git
##   HEAD branch: main
##   Remote branch:
##     main tracked
##   Local branch configured for 'git pull':
##     main merges with remote main
##   Local ref configured for 'git push':
##     main pushes to main (up to date)
```

### mutate a remote's URL

example: change the URL that _origin_ refers to

```shell
git remote set-url origin git@github.com:user33/abc.git
```

### 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 branch that does not exist yet on the remote repository

Given that the remote repository doesn't have our local branch, we also don't have a remote-tracking branch that is supposed to track this branch on the remote. As such, we cannot set up an upstream just yet, because doing so requires binding a local-only branch to a remote-tracking branch.

Instead, we must first push the branch to the remote repository. If it is successful, we get the remote-tracking branch, and Git may now bind the branch to the remote-tracking branch, configuring it as the upstream.

We do it with one command: the `push` command, where we specify which _remote_ we are pushing to, which branch we are pushing, and that we want Git to make the upstream binding if the push was a success

```shell
git push -u origin 2024
```

### delete a branch on the remote repository

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

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

### indicate match between current branch and remote-tracking branch

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



# Stashing unsaved work

### dirty working tree

The working tree is dirty when it has _modified files_. They may represent unsaved work. _Untracked files_ live outside of Git, but may also represent unsaved work.

the _modified files_ that we added to the index became _staged files_. They also represent unsaved work.

There are a few scenario where Git has to clear up both the working tree and the index, to replace them with the content from another commit. This may occur when switching to a branch that points to another commit, or when merging some remote branch into our current one. (this does not occur when creating a branch because it keeps pointing to the current commit, keeping the current changes relevant)

The straightforward solution is to save the pending work into a new commit to make the working directory and index clean, and then perform the operation mentioned above.

### stashing and popping

In the case where we _don't want_ to create a commit, but we want to preserve the work that lives in the working tree and the index, we may ask Git to `stash -u` the changes. Under the hood, Git creates a hidden commit for the working tree and one for the index.

Later, we may reverse the operation, bringing back the unsaved work to the working tree and the index, with `pop --index`.

```shell
git stash
git stash -u # include the untracked files
```

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 # if it worked without conflict

git stash pop --index
git stash drop # if conflict happened and has been sovled

git stash apply --index # apply never drops the stash
git stash drop
```

### conflict resolution on pop

When popping the unsaved files back to the working tree, there may be a conflict. The conflict resolution is the same as the one for merge conflicts. If it cannot solve the conflict itself, it will expose the incompatible changes in the files with visible marks to let the developer pick one. Similar for merge conflicts, the developer edits the file and signals it as resolved by performing a `git add` on the file.

As Git is conservative, it does not clear the stash if a conflict was detected. After we have resolved the conflict, we may have to clear the stash manually.

advanced: If we attempt to pop back a file from the index into an index that has a distinct version that also received work, it will fail completely, since the manual resolution is not possible for files that are in the index.

###



# 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
    git diff --staged

The default diff is the one between the working tree and the staging area.

Once changed are staged, we may check the diff between the staging area and the last commit instead.

### information about latest commit

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.


Plist files

Application bundle

Application's data and preferences

Launch processes automatically

# Plist files

A `.plist` file (Property List) commonly stores a set of user-preferences or some metadata about an app. It is a list of key-values.

The data's format is either binary or XML.

We may view or edit data with Xcode or `plutil`. We may use a text editor for XML ones.

```bash
plutil -p Info.plist
plutil -p "/Applications/Discord.app/Contents/Info.plist"
```

we may use `file` to detect if it's binary or XML:

```bash
file Info.plist
## Info.plist: XML 1.0 document text, ASCII text
```



# Application bundle

A pattern where we bundle the executable along with supporting files in a directory that looks like the application itself, at least in the Finder, as it has an `.app` suffix and as it comes with special behaviour and appearance:

-   The double-click runs the program instead of opening the directory
-   Finder shows the application's icon instead of a directory icon.

The content is semi-standardized. It includes

-   the icons
-   the internationalization strings
-   metadata about the app
-   frameworks and libraries, separated from the executable.

```bash
ls -1p "/Applications/Google Chrome.app/Contents/"

Frameworks/
Library/
Resources/
_CodeSignature/
MacOS/

Info.plist
PkgInfo
```

Such content should be treated as read-only, as tampering it triggers a signature change and security measures that prevent the executable from running.

The application's dynamic's data and preferences are stored outside the bundle.



# Application's data and preferences

The `Library` directory, located in the user's directory, helps to store data and preferences on behalf of applications.

While it has many directories, the one that applications should use are as follows:

```
~/Library/Application\ Support/
~/Library/Caches
~/Library/Preferences
```

### preferences

The `Preferences` directory stores lightweight user-preferences files related to a given program. They represent persisted user-specific settings. For example, _com.apple.dock.plist_ stores the _Dock_ settings.

```bash
ls ~/Library/Preferences/

com.microsoft.VSCode.plist
com.blizzard.diablo3.plist
com.apple.dock.plist

plutil -p ~/Library/Preferences/com.apple.dock.plist
```

### application support

`Application Support` is the general purpose storage area where each application may persist arbitrary data, such as databases, downloaded content, or extensions.

### caches

`Caches` stores cached data on behalf of applications. Those are usually artifacts produced by network fetches, which caches the networks responses to keep them available across runs.



# Launch processes automatically

### register a process for automatic launch

Applications (or simple processes) may request the OS to automatically launch them at boot-up or at user-login.

Boot-up items start before login, for critical services that should run as soon as possible and regardless of the user.

Login items start on user login, and may launch applications automatically.

### traditional registration process

We craft a `plist` file that identifies a process and provides some settings such as the launch arguments. We then place it in a hardcoded directory.

We place it in `/Library/LaunchDaemons` if it has to start on boot-up. We place it in either `/Library/LaunchAgents` or `~/Library/LaunchAgents` if it has to start on user login.

macOS manages a distinct database to keep track of which item has been disabled from the OS login-items settings.

```bash
open /Library/LaunchDaemons
open /Library/LaunchAgents
open ~/Library/LaunchAgents

sfltool dumpbtm

launchctl print-disabled user/$(id -u)
```

### modern registration process

applications are now encouraged to store the `plist` files inside their bundles and register them through a macOS API. This ends the pattern of having `plist` files outside of their bundles.

```
MyApp.app/
 └── Contents/
      ├── Info.plist
      ├── MacOS/
      │    └── MyApp  (The main executable)
      └── Library/
           └── LaunchAgents/
                └── com.myapp.helper.plist
```


macOS

Customize an instance

Universal style props

Global customization

CSS Module pattern

Mantine's internal styling

Light mode, dark mode

Default theme

Gray Palette

Dark Palette

Global Style: Colors

Global style: Others

Flex

Group

Stack

SimpleGrid

Container

Center

Divider

Space

Paper

Accordion

Appshell

Tabs

Table data

Table with explicit structure

Table from data prop

TextInput

NumberInput

FileInput

Native Select

SegmentedControl

Button

Button.Group

ActionIcon

Pagination

Modal

Title

Text

Bar Chart

Progress

RingProgress

Avatar

Notifications

useForm

useLocalStorage

useDisclosure

useMantineColorTheme

# 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 UI components.

### benefits

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

### mantine style is opinionated and cohesive

Mantine brings a set of cohesive style defaults.

If we aim to override some style, we should make it compatible with the Mantine overall look.

Some components, such as layout components and Mantine hooks, don't have a visible style, so we may use them in any design or project.

### mantine's packages

Mantine provides distinct packages. The main ones are Mantine _core_ and Mantine _hooks_.

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

### terminology: components and component variants

Mantine provides components, and for some of them, _variants_. For example,
it provides the _Button_ component, for which it provides the _outline_ and _filled_ variants.

### terminology: component's inner-elements

A component is constructed through several, named, _inner-elements_.
For example, _Slider_ is built upon a _mark_, a _track_ and a _bar_. We may style the inner-elements distinctively.

### customization patterns

We have three main patterns:

-   (Local) customization of an instance: the scope of the change is local and limited.
-   (Global) override of a Mantine component: it affects all sites that use this components.
-   (Global) customization of style primitives, also called theming, which affects several components.



# Customize an instance



### overview

We want to customize a single instance of a component.

We do that by adding inline style, classes, or provide props.

### inner workings

Technically, this pattern resolves to:

-   style that lives in the element's _style_ attribute
-   markers set on the element, such as a class, an id, an attribute or a custom attribute, along with some CSS targeting those markers.
-   inner DOM elements being added.

### the limits of setting style or className attributes directly

We may provide quick inline style in the _style_ attribute or classes to the _className_ attribute, but there is no granularity into which inner-element we target. The style we provide usually applies to the root inner-element.

While this is possible, it's not a pattern recommended by Mantine, because it doesn't let Mantine act as an intermediary.

### mantine patterns

Mantine offers patterns that are more powerful, and for them, allow to target inner-elements.

### props that we may set on any Mantine component instance.

Mantine's `style props` are a set of props that we may set on any Mantine component, and which aim to set a single style aspect. The style targets the top-level element.

```tsx
<Box m={4}></Box>
```

### props that are specific to one or more components

Some props are unique to some components. They may determine the style, but also determine the component's inner structure, such as toggling inner-elements. For example, the TextInput's _label_ prop adds a _label_ element in addition to the _input_ element.

```tsx
<TextInput label="Username"></TextInput>
// adds:
<label>Username</label>
```

### target an inner-element

We target an inner-element by specifying its Mantine-defined name, and provide a style object (_styles_ pattern) or one or more classes (_classNames_ pattern).

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

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

### class naming pattern

The classes we provide in _styles_ are to customize an instance of a given Mantine component. But we may wrap the instance into a new component, effectively creating a variant of the given Mantine component.

Given that, we may use the variant's name in all classes related to it, as a prefix, such as _pinkbutton_-\* if we are making a Button variant. if we are to target an inner component, we use its name as a suffix.

```txt
.pinkbutton-root
.pinkbutton-label
```

# Universal style props



We may set such props on any Mantine component. They target a single style aspect.

| 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                                 |
|             |                           |                                               |
| **pos**     | position                  | –                                             |
| **top**     | top                       | –                                             |
| **left**    | left                      | –                                             |
| **bottom**  | bottom                    | –                                             |
| **right**   | right                     | –                                             |
| **inset**   | inset                     | –                                             |
|             |                           |                                               |
| **display** | display                   | –                                             |
|             |                           |                                               |
| **flex**    | flex                      |                                               |
|             |                           |                                               |
| bd          | border                    |                                               |
| bdrs        | borderRadius              |                                               |

### responsiveness: provide alternative values.

Instead of a single value, we provide an object with alternative values. Most of
the time, we only provide two values.

-   the _base_ value provides the mobile-centric, default value. Its exact scope depends on which other breakpoints we define.
-   The _xs_ value activates at 576p. It excludes most smartphones. For reference, iPhones are under 450p width, with standard-size iPhones under 400p. If we want to exclude phablets as well, we use _sm_ instead.
-   The _sm_ value activates at 768p (48em), which excludes phablets, and includes tablets and wider screens. For reference, iPads start at 768px.

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

# Global customization



Global customization, also called theming, aims to override style at the style-primitives level (affecting several components), or at the component level, affecting all instances.

### customize style primitives

#todo

### implement Mantine-provided, component-scoped empty classes

Mantine sticks a series of empty classes on each of its built-in components. We may implement them to customize a given aspect of a given component.

(Implementing such class affects all instances)

For example, Mantine sticks `mantine-Button-root` and `mantine-Button-label` on inner-elements of the _Button_ component.

```css
.mantine-Button-root {
    border-width: 0.5px;
}
```

### empty classes specificity

Those classes have the same specificity than Mantine's implemented internal classes. One technique to make them win is to import our stylesheet after Mantine's one.

# CSS Module pattern



### css module pattern overview

A processor parses a given stylesheet to scan the classes and expose them to JS. It generates a globally unique name for each of them. It packs the developer-defined classes and globally unique classes in a dictionary object:

```tsx
export const classes = {
    supercool: "supercool_5cEkq2n0x1",
    supernice: "supernice_1kmox6oL39",
    superGreat: "superGreat_1kmox6oL39",
    "super-awesome": "super-awesome_1kmox6oL39",
} // conceptual // class dictionary
```

We import the dictionary.

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

<Button
classNames={{
        root: classes.xxx, 	// resolves to the processed class
        label: classes.xxx,	// resolves to the processed class
    }}
  >
```

### pattern: a module targets a Mantine component custom variant

In this pattern, the module's purpose is to define the style of a Mantine component custom variant for which we create a name. For example, we may create a _PrimaryButton_ variant of `Button`. We name the CSS Module with the variant name: `PrimaryButton.module.css`

We name the classes according to the inner-element they target, such as _root_ or _label_.

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

.root:hover {
}

.label {
}
```

We may then use the classes to inline-customize a Mantine's component instance, or to create a fully-fledged React component variant.

```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 the inner-element-as-a-classname naming pattern, we may give the CSS-module object directly to `classNames`, since _classNames_ expects an object with inner-element named properties.

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

# Mantine's internal styling



### case study: Mantine's implementation of Button

The [Button source code](https://github.com/mantinedev/mantine/tree/master/packages/%40mantine/core/src/components/Button) includes the typescript file (`Button.tsx`) and the stylesheet (`Button.module.css`).

### HTML element structure

There are several, nested elements:

-   the _root_ button is the top level container.
-   the _inner_ span is an intermediate container for the _label_ and the _sections_
-   a _section_ is a container for an icon.
-   the _label_ span contains the button's text.
-   the _loader_ span is an intermediate container for a loader.

```tsx
/* root */
<button>
    {/* 1.0 loader container*/}
    <span />
    {/* 2.0 inner */}
    <span>
        {/* 2.1 section  */}
        <span>
            <svg /> {/* 2.1.0 icon */}
        </span>
        {/* 2.2 label  */}
        <span>{/* 2.2.0 text */}</span>
    </span>
</button>
```

Both the mantine-implemented internal classes and empty classes are present, on each inner-element:

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

some inner-elements have some data-attributes, which may be shared across inner-elements of distinct components, such as the _mantine-active_ and _mantine-focus-auto_ attributes.

For example, `mantine-active` allows to receive style that activates when the element is active. The attribute is always there, and the stylesheet discriminates to the :active state.

```css
mantine-active:active {
    transform: translateY(calc(0.0625rem));
}
```

### Button's stylesheet

The [stylesheet](https://github.com/mantinedev/mantine/blob/master/packages/%40mantine/core/src/components/Button/Button.module.css) is a CSS module and follows the pattern where classes are named after inner-elements of the Button component. We reproduce the _root_ class.

```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));
        }
    }
}
```

For reference, we also reproduce the typescript file. It imports the CSS module.

```tsx
import {
    Box,
    BoxProps,
    createVarsResolver,
    getFontSize,
    getRadius,
    getSize,
    MantineColor,
    MantineGradient,
    MantineRadius,
    MantineSize,
    polymorphicFactory,
    PolymorphicFactory,
    rem,
    StylesApiProps,
    useProps,
    useStyles,
} from "../../core"
import { Loader, LoaderProps } from "../Loader"
import { MantineTransition, Transition } from "../Transition"
import { UnstyledButton } from "../UnstyledButton"
import { ButtonGroup } from "./ButtonGroup/ButtonGroup"
import { ButtonGroupSection } from "./ButtonGroupSection/ButtonGroupSection"
import classes from "./Button.module.css"

export type ButtonStylesNames = "root" | "inner" | "loader" | "section" | "label"
export type ButtonVariant =
    | "filled"
    | "light"
    | "outline"
    | "transparent"
    | "white"
    | "subtle"
    | "default"
    | "gradient"

export type ButtonCssVariables = {
    root:
        | "--button-justify"
        | "--button-height"
        | "--button-padding-x"
        | "--button-fz"
        | "--button-radius"
        | "--button-bg"
        | "--button-hover"
        | "--button-hover-color"
        | "--button-color"
        | "--button-bd"
}

export interface ButtonProps extends BoxProps, StylesApiProps<ButtonFactory> {
    "data-disabled"?: boolean

    /** Controls button `height`, `font-size` and horizontal `padding` @default `'sm'` */
    size?: MantineSize | `compact-${MantineSize}` | (string & {})

    /** Key of `theme.colors` or any valid CSS color @default `theme.primaryColor` */
    color?: MantineColor

    /** Sets `justify-content` of `inner` element, can be used to change distribution of sections and label @default `'center'` */
    justify?: React.CSSProperties["justifyContent"]

    /** Content displayed on the left side of the button label */
    leftSection?: React.ReactNode

    /** Content displayed on the right side of the button label */
    rightSection?: React.ReactNode

    /** If set, the button takes 100% width of its parent container @default `false` */
    fullWidth?: boolean

    /** Key of `theme.radius` or any valid CSS value to set `border-radius` @default `theme.defaultRadius` */
    radius?: MantineRadius

    /** Gradient configuration used when `variant="gradient"` @default `theme.defaultGradient` */
    gradient?: MantineGradient

    /** Sets `disabled` attribute, applies disabled styles */
    disabled?: boolean

    /** Button content */
    children?: React.ReactNode

    /** If set, the `Loader` component is displayed over the button */
    loading?: boolean

    /** Props added to the `Loader` component (only visible when `loading` prop is set) */
    loaderProps?: LoaderProps

    /** If set, adjusts text color based on background color for `filled` variant */
    autoContrast?: boolean
}

export type ButtonFactory = PolymorphicFactory<{
    props: ButtonProps
    defaultRef: HTMLButtonElement
    defaultComponent: "button"
    stylesNames: ButtonStylesNames
    vars: ButtonCssVariables
    variant: ButtonVariant
    staticComponents: {
        Group: typeof ButtonGroup
        GroupSection: typeof ButtonGroupSection
    }
}>

const loaderTransition: MantineTransition = {
    in: { opacity: 1, transform: `translate(-50%, calc(-50% + ${rem(1)}))` },
    out: { opacity: 0, transform: "translate(-50%, -200%)" },
    common: { transformOrigin: "center" },
    transitionProperty: "transform, opacity",
}

const varsResolver = createVarsResolver<ButtonFactory>(
    (theme, { radius, color, gradient, variant, size, justify, autoContrast }) => {
        const colors = theme.variantColorResolver({
            color: color || theme.primaryColor,
            theme,
            gradient,
            variant: variant || "filled",
            autoContrast,
        })

        return {
            root: {
                "--button-justify": justify,
                "--button-height": getSize(size, "button-height"),
                "--button-padding-x": getSize(size, "button-padding-x"),
                "--button-fz": size?.includes("compact")
                    ? getFontSize(size.replace("compact-", ""))
                    : getFontSize(size),
                "--button-radius": radius === undefined ? undefined : getRadius(radius),
                "--button-bg": color || variant ? colors.background : undefined,
                "--button-hover": color || variant ? colors.hover : undefined,
                "--button-color": colors.color,
                "--button-bd": color || variant ? colors.border : undefined,
                "--button-hover-color": color || variant ? colors.hoverColor : undefined,
            },
        }
    }
)

export const Button = polymorphicFactory<ButtonFactory>((_props, ref) => {
    const props = useProps("Button", null, _props)
    const {
        style,
        vars,
        className,
        color,
        disabled,
        children,
        leftSection,
        rightSection,
        fullWidth,
        variant,
        radius,
        loading,
        loaderProps,
        gradient,
        classNames,
        styles,
        unstyled,
        "data-disabled": dataDisabled,
        autoContrast,
        mod,
        attributes,
        ...others
    } = props

    const getStyles = useStyles<ButtonFactory>({
        name: "Button",
        props,
        classes,
        className,
        style,
        classNames,
        styles,
        unstyled,
        attributes,
        vars,
        varsResolver,
    })

    const hasLeftSection = !!leftSection
    const hasRightSection = !!rightSection

    return (
        <UnstyledButton
            ref={ref}
            {...getStyles("root", { active: !disabled && !loading && !dataDisabled })}
            unstyled={unstyled}
            variant={variant}
            disabled={disabled || loading}
            mod={[
                {
                    disabled: disabled || dataDisabled,
                    loading,
                    block: fullWidth,
                    "with-left-section": hasLeftSection,
                    "with-right-section": hasRightSection,
                },
                mod,
            ]}
            {...others}
        >
            {typeof loading === "boolean" && (
                <Transition mounted={loading} transition={loaderTransition} duration={150}>
                    {(transitionStyles) => (
                        <Box
                            component="span"
                            {...getStyles("loader", { style: transitionStyles })}
                            aria-hidden
                        >
                            <Loader
                                color="var(--button-color)"
                                size="calc(var(--button-height) / 1.8)"
                                {...loaderProps}
                            />
                        </Box>
                    )}
                </Transition>
            )}

            <span {...getStyles("inner")}>
                {leftSection && (
                    <Box component="span" {...getStyles("section")} mod={{ position: "left" }}>
                        {leftSection}
                    </Box>
                )}

                <Box component="span" mod={{ loading }} {...getStyles("label")}>
                    {children}
                </Box>

                {rightSection && (
                    <Box component="span" {...getStyles("section")} mod={{ position: "right" }}>
                        {rightSection}
                    </Box>
                )}
            </span>
        </UnstyledButton>
    )
})

Button.classes = classes
Button.displayName = "@mantine/core/Button"
Button.Group = ButtonGroup
Button.GroupSection = ButtonGroupSection
```

### style shipped on npm

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

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

# 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>
```

# Default theme



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

### spacing

space between elements and inside elements.

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

used for or usable by:

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

### radius

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

used for:

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

we may set the default with _defaultRadius_:

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

### breakpoints

a set of alternative thresholds that we may target to activate style conditionally.

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

The `sm` breakpoint targets tablets and wider devices.

we specify one or more thresholds in the styles-props alternative-values pattern.

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

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

Those sizes do not affect headings. We may use them in:

-   the _fz_ style prop, on any component.

### line heights

```ts
  "lineHeights": {
    xs: 1.4,
    sm: 1.45,
    md: 1.55,
    lg: 1.6,
    xl: 1.65
  },
```

### headings

family, weight and wrap behavior:

```tsx
"headings": {
    "fontFamily": "-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji",
    "fontWeight": "700",
    "textWrap": "wrap",
  },
```

size and line height:

```ts
  "sizes": {
      "h1": {
        "fontSize": "calc(2.125rem * var(--mantine-scale))",
        "lineHeight": "1.3"
      },
      "h2": {
        "fontSize": "calc(1.625rem * var(--mantine-scale))",
        "lineHeight": "1.35"
      },
      "h3": {
        "fontSize": "calc(1.375rem * var(--mantine-scale))",
        "lineHeight": "1.4"
      },
      "h4": {
        "fontSize": "calc(1.125rem * var(--mantine-scale))",
        "lineHeight": "1.45"
      },
      "h5": {
        "fontSize": "calc(1rem * var(--mantine-scale))",
        "lineHeight": "1.5"
      },
      "h6": {
        "fontSize": "calc(0.875rem * var(--mantine-scale))",
        "lineHeight": "1.5"
      }
    }
```

# Gray Palette



### description and use

It is a slate gray: it has a blue tint.

Mantine's `light-mode` theme makes use of this palette: it offers several whites for backgrounds, and a few dark grays for text. It does not include pure white, instead, it starts at #F8F9FA.

The following consideration usually apply for light-mode:

-   The background may be pure white. It may be the app/site global background of the controls background.

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

-   The text is black-ish or gray-ish depending on importance and role:
    -   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

### values

-   `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

# Dark Palette



### the dark palette

It is a neutral gray palette. It was a slate-gray palette (blue-tint) before Mantine 7.3.

Mantine's `dark-mode` theme makes use of this palette. It offers several darks for backgrounds, grays for controls, and whites for text.

### use in dark mode

-   The app background is dark 7. We may go darker with dark 8.
-   Controls have lighter backgrounds: dark 6, and even lighter on hover: dark 5.
    Sometimes, hover goes to a darker background instead: such as the hovered option in a select control: dark 8.
-   The text is light. It uses one of those colors:
    -   pure white (bright white for some headings)
    -   dark 0 (readable white for body text)
    -   dark 1 (slightly dimmed)
    -   dark 2 (dimmed, secondary text, matches `c=dimmed`)
-   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.

### values

-   `dark.0`: very light gray close to white: #C9C9C9.
-   ..
-   `dark.9`: black: #141414

### 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



#todo

```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;
```

# 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 adds a gap and makes the flex vertical (by setting _flex-direction_).

The stack itself occupies the full width because it is a _display:flex_. Elements stretch to fill the stack by default (_align_ prop).

-   `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 equal-width tracks, and which expands horizontally (fluid).

We set the number of tracks with `cols`. It defaults to a single track. Wide screens accommodate multiple tracks, but mobile devices may stick with a single one. As such, it's common to set `cols` with at least two values:

```tsx
<SimpleGrid cols={{ base: 1, sm: 2, lg: 5 }}>// items</SimpleGrid>
```

Mantine adds space between tracks by default (_16px_). We may set it with `spacing` and `verticalSpacing`.

# Container



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

### limited-width container version

The first version, the default one, comes with a max-width that limits the width in desktop, while bringing minimum padding for mobiles so that the content does not touch the screen edges.

it centers the content with margin: auto.

The max-width is defined by `size`. It defaults to _md_ (aka 960px, or 60rem). We may pick
720px (_sm_). If we are to provide an arbitrary numeric value, we may as well use `maw` directly which is semantically more accurate.

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

### fluid container version

We may opt for a fluid container, which expands horizontally, with the `fluid` prop. It only comes with some padding, at 16px.

The fluid version is a bit of an overkill: We may as well use a _Box_ with some horizontal padding instead.

# Center



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

It translates to a div with:

-   _display: flex_
-   _justify-content_: center
-   _align-items_: center

### vertical-centering and height

Vertical centering will only come into play if _Center_'s height is 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 and sections divider, similar in essence to the \<hr\> element.

It may be used as an horizontal line or a vertical line.

Technically, Mantine uses an element with no content, but 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 spacing at a location in the layout. It uses an element with no content but with some non-zero size. It defaults to size 0. As such, we must set either the height or the width.

-   `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 add a pre-styled border and a
pre-styled shadow.

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

### props

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

# Accordion



The Accordion is a container for one or more items that are expandable. Expanding an item will show additional content related to that item.

### 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, which we toggle through clicking.

In Mantine, the detail panel mounts immediately, regardless if it's toggled or not.

In Mantine, we set the chevron style at the Accordion's 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



Appshell is a mega layout component that aims to manage:

-   The _header_ that appears on-top, also called the banner.
-   The _main_ section, that appears below the header
-   The potential left-side _navbar_ and right-side _aside_.

### header: Appshell.Header

The header manages:

-   the burger button
-   the logo
-   the dark mode / light mode toggle (potentially)
-   the user button (potentially)
-   a set of links (potentially)

### configure the header

We build a header config and provide it to AppShell as a _header_ prop. We commonly set the _height_.

```tsx
<AppShell /* ... */ header={{ height: 60 }} />
```

### navbar: Appshell.Navbar

The _navbar_ stands on the left side. It is transient on mobile devices. On desktop it is commonly always-on, but Mantine supports having a conditional collapse as well, following a distinct logic and state variable.

We build a navbar config and provide it to AppShell as a _navbar_ prop. _collapsed_ aims to control the display of the navbar, while _breakpoint_ sets the breakpoint from which we go from _mobile_ to _desktop_ logic.

```tsx
<AppShell /* ... */ navbar={{}} />
```

-   `collapsed` receives up to two boolean state variables: one for _mobile_ and one for _desktop_. Most of the time, we only set _mobile_.
-   `breakpoint` controls when the collapse logic switches from mobile to desktop, aka when to use the mobile opened state versus the desktop opened state.
-   The burger button is responsible for toggling the state on and off. We hide the mobile burger button with `hiddenFrom`. If desktop supports collapse too, we use a distinct burger button (see below).

```tsx
const [mobileOpened, { toggle: toggleMobile }] = useDisclosure()

return (
    <AppShell
        navbar={{
            collapsed: { mobile: !opened },
            breakpoint: "sm",
        }}
    >
        <AppShell.Header>
            <Burger opened={opened} onClick={toggle} hiddenFrom="sm" />
        </AppShell.Header>
    </AppShell>
)
```

### navbar: allow collapse on desktop

We may allow the collapse behavior on Desktop as well: we create an additional, distinct boolean state variable, and provide it to the _desktop_ property of `collapsed`. We also add a dedicated desktop burger button, which commonly keeps the same appearance regardless of the collapse state (we don't show a close icon because there is no overlay). This burger button condition its display to desktop with _visibleFrom_.

```tsx
const [mobileOpened, { toggle: toggleMobile }] = useDisclosure(false)
const [desktopOpened, { toggle: toggleDesktop }] = useDisclosure(true)

return (
    <AppShell
        navbar={{
            collapsed: { mobile: !mobileOpened, desktop: !desktopOpened },
            breakpoint: "sm",
        }}
    >
        <AppShell.Header>
            {/* mobile */}
            <Burger opened={mobileOpened} onClick={toggleMobile} hiddenFrom="sm" />
            {/* desktop */}
            <Burger opened={false} onClick={toggleDesktop} visibleFrom="sm" />
        </AppShell.Header>
    </AppShell>
)
```

### navbar: other configuration

```tsx
navbar={{ width: 300, /* ... */ }}
```

-   `width` controls the width in desktop mode (it is always full-screen in mobile). We provide an immediate value or an object with two or more values.

### navbar: implement top and bottom sections

We may split the navbar into _AppShell.Sections_, and one of them may grow.

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

### Appshell.Main

The container for the main panel.

We may set the panel background color. The default light theme sets a _white_ background while the dark theme sets a _dark.7_ background.

Override example: we may pick a light gray background such as _gray.1_, so that inner containers may stand out as white. Similarly, we may change the background to _dark.8_ so that inner elements may standout as _dark.7_.

```tsx
const backgroundColor = colorScheme === "dark" ? "dark.8" : "gray.1"
```

### synopsis

the configuration objects are required if we use the matching element, except for _main_ which may not be configured with this pattern.

```tsx
<AppShell header={{}} navbar={{}} aside={{}} footer={{}}>
    <AppShell.Header />
    <AppShell.Navbar />
    <AppShell.Aside />
    <AppShell.Main />
    <AppShell.Footer />
</AppShell>
```

# Table data



### abstract

A table works with an array of items, where each item is a row, and each property or member is a cell.

An item may come as an object or as an array.

### pattern: the item is an object

```ts
const items = [
    { 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" },
]
```

### pattern: the item is an array

```ts
const items = [
    [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"],
]
```

We may come with this data by transforming an array of objects to an array of arrays:

```ts
const items = players.map((p) => [p.name, p.level, p.class])
```

### headers

An array usually comes with headers. We may provide them in an array.

```ts
const headers = ["Element position", "Atomic mass", "Symbol", "Element name"]
```

# Table with explicit structure



### structure preview

```tsx
<Table>
    <Table.Thead>
        {/* head */}
        <Table.Tr>
            <Table.Th>{col1Label}</Table.Th>
            <Table.Th>{col2Label}</Table.Th>
            <Table.Th>{col3Label}</Table.Th>
        </Table.Tr>
    </Table.Thead>

    {/* body */}
    <Table.Tbody>
        <Table.Tr>
            <Table.Td>{item1.name}</Table.Td>
            <Table.Td>{item1.level}</Table.Td>
            <Table.Td>{item1.class}</Table.Td>
        </Table.Tr>
        {/* ... more rows */}
    </Table.Tbody>
</Table>
```

### build rows from an array of objects

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

### build rows from an array of arrays

```tsx
const rows = items.map((item) => (
    <Table.Tr>
        <Table.Td>{item[0]}</Table.Td>
        <Table.Td>{item[1]}</Table.Td>
        <Table.Td>{item[2]}</Table.Td>
    </Table.Tr>
))
```

### headers and body

_Thead_ is the container for the headers.

```tsx
<Table.Thead>
    <Table.Tr>
        <Table.Th>{col1Label}</Table.Th>
        <Table.Th>{col2Label}</Table.Th>
        <Table.Th>{col3Label}</Table.Th>
    </Table.Tr>
</Table.Thead>
```

_Tbody_ is the container for rows.

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

# Table from data prop



We provide the complete data as a single object for a single prop:

-   The `caption` property defines the table's title
-   The `head` property is the array of headers.
-   The `body` array is the list of items. Each item is an array with bare values

```tsx
const tableData: TableData = {
    caption: "Some elements from periodic table",
    head: ["Element position", "Atomic mass", "Symbol", "Element name"], // headers
    body: [
        // items
        [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"],
    ],
}
```

### data prop

We provide such object to the `data` prop. Mantine then creates the markup automatically.

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

# TextInput



TextInput is an abstraction over an `<input type=text/>` element. It inherits some props from the abstract `<Input>` component.

-   We set the main label with `label`. A main label is often necessary to explain the purpose of such input.
-   We set the optional secondary label with `description`
-   `placeholder` sets the placeholder text
-   `leftSection` and `rightSection` allow to insert an icon, visually inside the text input.
-   The `required` prop adds the `required` attribute to the element. In that case, Mantine automatically adds an asterisk. But we may remove it with `withAsterisk`.

# 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} />
```

# FileInput



FileInput comes with props specific to the goal of selecting files:

-   We may allow multi-file selection with `multiple`. It defaults to false.
-   We may specify a file type in `accept`, such as `image/png`
-   We may show a clear button on the right by adding `clearable`
-   We work with the selected file by providing a handler to `onChange`. The handler receives a File object (or a File array) whenever the user picks some files or clears the selection.

We may limit the input's width to truncate long file names. We may add a file icon in the leftSection. The unstyled variant is similar to the `transparent` variant: there is no border or background. We may set it size to _xs_.

Finally, FileInput comes with the traditional input props such as label and placeholder.

```tsx
<FileInput
    size="xs"
    maw={150}
    onChange={onChange}
    placeholder="Reference Image"
    leftSection={<IconPhoto size={18} stroke={1.5} />}
    clearable
    variant="unstyled"
/>
```

# Native Select



An abstraction over a HTML <_select_> element that embeds some <_option_>
elements. We build an array describing data for each option, and provide it to the _data_ attribute. The data for an option is a record with a _label_ and a _value_.

If the _label_ is the same as the _value_ (not recommended), we may
provide a string instead of a record, which acts 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: "deathKnight" },
    { label: "Demon Hunter", value: "demonHunter" },
]

const options = ["deathKnight", "demonHunter"]
```

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

# 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" },
    ]}
/>
```

# 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.

### 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>
```

# Button.Group



We create a button cluster that glues up the buttons horizontally (default), or vertically.

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

# 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>
```

# 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 on top of the application. It dims the background while opened. We may dismiss it with escape, the close button (if it's displayed), or with a click outside.

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

reminder: We may get such a boolean state variable with _useDisclosure_, which also gives semantically correct `open` and `close` state-mutation functions.

When the user attempts to dismiss the modal, Mantine calls the `onClose` handler: We have to provide one. This handler has the responsibility to toggle the opened state back to false if it approves the dismiss. It will usually call the `close` function.

```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

A neutral wrapper, similar in essence to _div_ or _span_, which may affect its children through Mantine style props:

```tsx
<Box fz={12}>/* */</Box>
```



# 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

Progress is a replacement for the native `<progress>` element. It displays a linear bar. It uses a regular _div_ under the hood.

We may opt for a striped bar, or even an animated striped bar.

### 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>
```



# RingProgress

RingProgress displays a circular, segmented bar.

In the simplest form, we may use it as a circular progress bar, with a single bar showing the progress over the background track.

We may also use it as a segmented, Donut Chart, where one section represents a quantity and has a dedicated bar.

```tsx
<RingProgress
    sections={[{ value: 35, color: progressColor, tooltip: "35%" }]}
    rootColor={trackColor}
    size={30}
    thickness={4}
    roundCaps
/>
```

The Donut chart version has multiple sections:

```tsx
 sections={[
        { value: 40, color: 'cyan' },
        { value: 15, color: 'orange' },
        { value: 15, color: 'grape' },
      ]}
```



# Avatar

The Avatar component may work with the user profile's image or may generate an avatar based on its name's initials. In absence of valid image or name, it falls back to a generic user icon automatically.

The border is round by default, as it sets the _border-radius_ to 1000px.

The avatar size is 36px by default.

Mantine ensures the avatar remains square, cropping the image if needed, and that it covers the whole area, thanks to _object-fit: cover_.

### provide an image

```tsx
<Avatar src={imageURL} alt="John's portrait" />
```

### provide a name

```tsx
<Avatar name={name} />
```

### request a generic icon intentionally

if we omit _src_ and _name_, we always get a generic icon.

```tsx
<Avatar />
```



# 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.

Mantine's _useForm_ provides a convenient way to
specify the form's initial data and the validation and/or transformation to
perform on submit.

### Overview

We work with a regular \<form\>, which embeds 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)
```

# useMantineColorTheme



We want to read the current `colorScheme`, or set it to a value: _dark_ or _light_.

Mantine saves the selected `colorScheme` in localStorage.

Before the App appears on-screen, Mantine checks the localStorage for any saved `colorScheme`, so that the first paint is done with the correct `colorScheme`.

```tsx
const { colorScheme, setColorScheme } = useMantineColorScheme()
// also: toggleColorScheme and clearColorScheme
```

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.
