Update documentation on Text (Shopify#2023)

docs/docs/text/paragraph.md

@@ -8,7 +8,6 @@ slug: /text/paragraph
 React Native Skia offers an API to perform text layouts.
 Behind the scene, this API is the Skia Paragraph API.
 
-
 ## Hello World
 
 In the example below, we create a simple paragraph based on custom fonts.
@@ -79,6 +78,34 @@ const textStyle = {
 };
 ```
 
+## Fonts
+
+By default, the paragraph API will use the system fonts.
+You can also use custom fonts with this API was well. 
+
+The `useFonts` hooks allows you to load custom fonts to be used for your Skia drawing.
+The font files should be organized by family names.
+For example:
+
+```tsx twoslash
+import {useFonts} from "@shopify/react-native-skia";
+
+const fontMgr = useFonts({
+  Roboto: [
+    require("./Roboto-Medium.ttf"),
+    require("./Roboto-Regular.ttf"),
+    require("./Roboto-Bold.ttf"),
+  ],
+  Helvetica: [require("./Helvetica.ttf")],
+});
+if (!fontMgr) {
+  // Returns null until all fonts are loaded
+}
+// Now the fonts are available
+```
+
+You can also list the available system fonts via `listFontFamilies()` function.
+
 ## Styling Paragraphs
 
 These properties define the overall layout and behavior of a paragraph.
@@ -96,7 +123,7 @@ These properties define the overall layout and behavior of a paragraph.
 | `textHeightBehavior`    | Controls the behavior of text ascent and descent in the first and last lines.         |
 | `textStyle`             | Default text style for the paragraph (can be overridden by individual text styles).   |
 
-### Text Style Properties
+## Text Style Properties
 
 These properties are used to style specific segments of text within a paragraph.
 

docs/docs/text/text.md

@@ -11,7 +11,7 @@ Please note that the y origin of the Text is the bottom of the text, not the top
 | Name        | Type       |  Description                                                    |
 |:------------|:-----------|:----------------------------------------------------------------|
 | text        | `string`   | Text to draw                                                    |
-| font        | `SkFont`   | Font to use (optional, see [font management](/docs/text/fonts)) |
+| font        | `SkFont`   | Font to use (optional)                                          |
 | x           | `number`   | Left position of the text (default is 0)                        |
 | y           | `number`   | Bottom position the text (default is 0, the )                   |
 
@@ -40,21 +40,130 @@ export const HelloWorld = () => {
 
 <img src={require("/static/img/text/hello-world.png").default} width="256" height="256" />
 
-### Emojis
+## Fonts
+
+Once the fonts are loaded, we provide a `matchFont` function that given a font style will return a font object that you can use directly.
 
 ```tsx twoslash
-import {Canvas, Text, useFont, Fill} from "@shopify/react-native-skia";
+import {useFonts, Text, matchFont} from "@shopify/react-native-skia";
+
+const Demo = () => {
+  const fontMgr = useFonts({
+    Roboto: [
+      require("./Roboto-Medium.ttf"),
+      require("./Roboto-Regular.ttf"),
+      require("./Roboto-Bold.ttf"),
+    ]
+  });
+  if (!fontMgr) {
+    return null;
+  }
+  const fontStyle = {
+    fontFamily: "Roboto",
+    fontWeight: "bold",
+    fontSize: 16
+  } as const;
+  const font = matchFont(fontStyle, fontMgr);
+  return (
+    <Text text="Hello World" y={32} x={32} font={font} />
+  );
+};
+```
+
+## System Fonts
+
+System fonts are available via `Skia.FontMgr.System()`.
+You can list system fonts via  `listFontFamilies` function returns the list of available system font families.
+By default the function will list system fonts but you can pass an optional `fontMgr` object as parameter.
+
+```jsx twoslash
+import {listFontFamilies} from "@shopify/react-native-skia";
+
+console.log(listFontFamilies());
+```
+
+Output example on Android:
+```
+["sans-serif", "arial", "helvetica", "tahoma", "verdana", ...]
+```
+
+or on iOS:
+```
+["Academy Engraved LET", "Al Nile", "American Typewriter", "Apple Color Emoji", ...]
+```
+
+By default matchFont, will match fonts from the system font manager:
+
+```jsx twoslash
+import {Platform} from "react-native";
+import {Canvas, Text, matchFont, Fill, Skia} from "@shopify/react-native-skia";
+
+const fontFamily = Platform.select({ ios: "Helvetica", default: "serif" });
+const fontStyle = {
+  fontFamily,
+  fontSize: 14,
+  fontStyle: "italic",
+  fontWeight: "bold",
+};
+const font = matchFont(fontStyle);
 
 export const HelloWorld = () => {
-  const fontSize = 32;
-  const font = useFont(require("./NotoColorEmoji.ttf"), fontSize);
   return (
     <Canvas style={{ flex: 1 }}>
       <Fill color="white" />
-      <Text text="🙋🌎" font={font} y={fontSize} x={0} />
+      <Text
+        x={0}
+        y={fontStyle.fontSize}
+        text="Hello World"
+        font={font}
+      />
     </Canvas>
   );
 };
 ```
 
-<img src={require("/static/img/text/text-emoji.png").default} width="256" height="256" />
+The `fontStyle` object can have the following list of optional attributes:
+
+- `fontFamily`: The name of the font family.
+- `fontSize`: The size of the font.
+- `fontStyle`: The slant of the font. Can be `normal`, `italic`, or `oblique`.
+- `fontWeight`: The weight of the font. Can be `normal`, `bold`, or any of `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`.
+
+By default, `matchFont` uses the system font manager to match the font style. However, if you want to use your custom font manager, you can pass it as the second parameter to the `matchFont` function:
+
+```jsx twoslash
+import {matchFont, useFonts} from "@shopify/react-native-skia";
+
+const fontMgr = useFonts({
+  Roboto: [
+    require("../../Tests/assets/Roboto-Medium.ttf"),
+    require("../../Tests/assets/Roboto-Bold.ttf"),
+  ]
+});
+
+const font = matchFont(fontStyle, fontMgr);
+```
+
+## Low-level API
+
+The basic usage of the system font manager is as follows.
+These are the APIs used behind the scene by the `matchFont` function.
+
+```tsx twoslash
+import {Platform} from "react-native";
+import {Skia, FontStyle} from "@shopify/react-native-skia";
+
+const familyName = Platform.select({ ios: "Helvetica", default: "serif" });
+const fontSize = 32;
+// Get the system font manager
+const fontMgr = Skia.FontMgr.System();
+// The custom font manager is available via Skia.TypefaceFontProvider.Make()
+const customFontMgr = Skia.TypefaceFontProvider.Make();
+// typeface needs to be loaded via Skia.Data and instanciated via
+// Skia.Typeface.MakeFreeTypeFaceFromData()
+// customFontMgr.registerTypeface(customTypeFace, "Roboto");
+
+// Matching a font
+const typeface =  fontMgr.matchFamilyStyle(familyName, FontStyle.Bold);
+const font = Skia.Font(typeface, fontSize);
+```

docs/sidebars.js

@@ -68,7 +68,6 @@ const sidebars = {
       type: "category",
       label: "Text",
       items: [
-        "text/fonts",
         "text/paragraph",
         "text/text",
         "text/glyphs",