feat: add documentation

docs/astro.config.mjs

@@ -16,8 +16,25 @@ export default defineConfig({
       },
       sidebar: [
         {
-          label: 'Guides',
-          autogenerate: { directory: 'guides' },
+          label: 'Overview',
+          link: '',
+        },
+        {
+          label: 'Core',
+          items: [
+            'core/providers',
+            'core/scoped-di',
+            'core/modals',
+            'core/testing',
+            'core/configuration',
+          ],
+        },
+        {
+          label: 'Miscellaneous',
+          items: [
+            'miscellaneous/reactivity',
+            'miscellaneous/comparison-with-alternatives',
+          ],
         },
       ],
     }),

docs/src/content/docs/core/configuration.md

@@ -0,0 +1,19 @@
+---
+title: Configuration
+description: How to set up the application-wide configuration for Disco.
+---
+
+Disco aims to be minimally opinionated. To customize the default configuration, set the desired preferences using `DiscoConfig` before calling `runApp`. For example:
+
+```dart
+DiscoConfig.lazy = false;
+runApp(
+  // ...
+);
+```
+
+### All options
+
+| Option         | Default | Description |
+| -------------- | ------- | ----------- |
+| `lazy`         | true    | The values of the providers provided in a `ProviderScope` are created lazily. |

docs/src/content/docs/core/modals.md

@@ -0,0 +1,52 @@
+---
+title: Modals
+description: How to access providers inside modals.
+---
+
+A modal spawns a new widget tree, making injecting providers not possible out of the box.
+
+This library offers `ProviderScopePortal`, which gives access to all the providers that were created in the main widget tree.
+
+Note that you have to pass it the context of the main tree for it to work. Also, a `BuildContext` that is a descendant of `ProviderScopePortal` needs to be used. This is why in the following example we created a `Builder` and used its argument `innerContext` to inject the provider.
+
+```dart
+final numberProvider = Provider((context) => 1);
+
+Future<void> showNumberDialog({required BuildContext context}) {
+  return showDialog(
+    context: context,
+    builder: (dialogContext) {
+      return ProviderScopePortal(
+        mainContext: context,
+        child: Builder(
+          builder: (innerContext) {
+            final number =
+                numberProvider.of(innerContext);
+            return Text('$number');
+          },
+        ),
+      );
+    },
+  );
+}
+
+runApp(
+  MaterialApp(
+    home: Scaffold(
+      body: ProviderScope(
+        providers: [numberProvider],
+        child: Builder(
+          builder: (context) {
+            return ElevatedButton(
+              onPressed: () {
+                showNumberDialog(context: context);
+              },
+              child: const Text('show dialog'),
+            );
+          },
+        ),
+      ),
+    ),
+  ),
+);
+```

docs/src/content/docs/core/providers.md

@@ -0,0 +1,83 @@
+---
+title: Providers
+description: How to create Disco providers.
+---
+
+A provider is a tool that helps manage and inject dependencies in an application, making it easier to share data or services across different parts of the app.
+
+**NB:** When we use the term "provider", it can refer to either the `Provider` class of this library or the value it contains, depending on the context.
+
+## Providers
+
+Declare a new provider either as a global `final` variable or a `final` static field.
+
+**NB:** while providers can be declared globally, they **do not function globally**. They are just used as **identifiers** when registered in a scope.
+
+Example with a global `final` variable.
+
+```dart
+/// global scope
+final numberProvider = Provider((context) => 5);
+```
+
+If there is only a provider per class, you can also create a `final` static field. This comes down to personal preference.
+
+```dart
+class MyDatabase {
+  static final provider = Provider((context) => MyDatabase());
+}
+```
+
+### Injection of other providers with context
+
+Providers can leverage the context to inject other providers. The context will be relative to the scope in which they are provided.
+
+```dart
+final doubleNumberProvider = Provider((context) {
+  final number = numberProvider.of(context);
+  return number * 2;
+});
+```
+
+## Providers with argument
+
+Providers need to be provided before they can be injected in the widget tree. Sometimes, they need an initial argument so that they can be instantiated correctly. This is possible with `Provider.withArgument`.
+
+```dart
+final numberPlusArgProvider = Provider.withArgument((context, int arg) {
+  return 5 + arg;
+});
+```
+
+An example where this might make more sense would be an application with multi-account support, where the database is loaded per user, and the filepath of the database contains the user ID:
+
+```dart
+class MyDatabase {
+  static final provider = Provider.withArgument((context, String userId) => MyDatabase.fromId(id));
+}
+```
+
+This `MyDatabase.provider` has to be provided in a subtree (of the widget tree) belonging to the currently logged user.
+
+### Injection of other providers with context
+
+Providers can both take an argument and rely on context.
+
+```dart
+final doubleNumberPlusArgProvider = Provider.withArgument((context, int arg) {
+  final number = numberProvider.of(context);
+  return number * 2 + arg;
+});
+```
+
+## Dispose and lazy parameters
+
+When defining a provider, we need to pass the positional `create` argument, which is a function used to generate the value contained by the provider.
+
+There are also two optional named parameters that can be specified.
+
+| Parameter | Default | Description |
+| -------------- | ------- | ----------- |
+| `dispose`      | null    | The function to call when the scope containing the provider gets disposed. It is used to dispose correctly the value held by the provider. |
+| `lazy`         | `DiscoConfig.lazy`, which defaults to true | The values of the providers provided in a scope are created lazily.|
+

docs/src/content/docs/core/scoped-di.md

@@ -0,0 +1,106 @@
+---
+title: Scoped DI
+description: How to use Disco providers and understanding scoping.
+---
+
+Providers have to be provided before they can be injected.
+
+Let us consider two providers of the previous page for this section.
+
+```dart
+final numberProvider = Provider((context) => 5);
+
+final doubleNumberPlusArgProvider = Provider.withArgument((context, int arg) {
+  final number = numberProvider.of(context);
+  return number * 2 + arg;
+});
+```
+
+### How to scope
+
+Scoping means that the provider must be specified within a `ProviderScope` before it can be injected.
+
+In case the provider does not take an argument, we scope it the following way:
+
+```dart
+ProviderScope(
+  providers: [numberProvider]
+  child: // ...
+)
+```
+
+In case the provider takes an argument, we need to specify it when providing it.
+
+```dart
+ProviderScope(
+  providers: [doubleNumberPlusArgProvider(10)]
+  child: // ...
+)
+```
+
+### How to inject
+
+Injecting is the act of retrieving a dependency. It is done with the methods `of(context)` and `maybeOf(context)`, the latter one being safer because it returns null instead of throwing if the provider is not found in any scopes. If you are unsure about which one to use, for simplicity you should probably stick to `of(context)` (and maybe set up an error monitoring solution to automatically detect invalid injections).
+
+We inject the two providers above by using the `numberProvider.of(context)` and `doubleNumberPlusArgProvider.of(context)`.
+
+### Full example
+
+Try and guess what the displayed text will be before reading the solution.
+
+```dart
+runApp(
+  MaterialApp(
+    home: Scaffold(
+      body: ProviderScope(
+        providers: [numberProvider],
+        child: ProviderScope(
+          providers: [doubleNumberPlusArgProvider(10)],
+          child: Builder(
+            builder: (context) {
+              final number = numberProvider.of(context);
+              final doubleNumberPlusArg = doubleNumberPlusArgProvider.of(context);
+              return Text('$number $doubleNumberPlusArg');
+            },
+          ),
+        ),
+      ),
+    ),
+  ),
+);
+```
+
+The solution is "5 20".
+
+## Scoping correctly
+
+Some providers might have a dependency on other providers or as an argument. It is important that the following considerations are made.
+
+### Context
+
+Note that the scope containing `doubleNumberPlusArgProvider` needs to be a descendant of the one containing `numberProvider`. This is because `doubleNumberPlusArgProvider` uses the context to find the value of `numberProvider`. The following will thus **not** work:
+
+```dart
+// bad example
+ProviderScope(
+  providers: [
+    numberProvider,
+    doubleNumberPlusArgProvider(10),
+  ],
+  child: // ...
+)
+```
+
+Placing the `ProviderScope` containing `doubleNumberPlusArgProvider` above the one containing `numberProvider` would also not work. It needs to be like in the full example above.
+
+### Argument
+
+Let's recall the example from the previous page.
+
+```dart
+class MyDatabase {
+  static final provider = Provider((context, String userId) => MyDatabase.fromId(id));
+}
+```
+
+The `MyDatabase.provider` should be provided in a subtree (of the widget tree) belonging to the currently logged user. If you provide it too high up in the widget tree (above the currently logged user logic) it will not be possible to change database, because the `ProviderScope` where `MyDatabase.provider` is provided is never disposed. In practice, this particular error is unlikely due to the `userId` being first available in the currently logged user logic. However, this kind of scenario needs to be considered.

docs/src/content/docs/core/testing.md

@@ -0,0 +1,70 @@
+---
+title: Testing
+description: How to use overrides for testing.
+---
+
+Testing is done with overrides. You will need to place a `ProviderScopeOverride` (preferably as the root widget) and then specify the `overrides`, which is a list containing the providers followed by `.overrideWithValue(T value)`.
+
+Note that you can **only** use one `ProviderScopeOverride` per test.
+
+The text displayed in the following example will be "100".
+
+```dart
+testWidgets(
+    '''ProviderScopeOverride should override providers''',
+    (tester) async {
+  final numberProvider = Provider<int>((context) => 0);
+  await tester.pumpWidget(
+    ProviderScopeOverride(
+      overrides: [
+        numberProvider.overrideWithValue(100),
+      ],
+      child: MaterialApp(
+        home: ProviderScope(
+          providers: [
+            numberProvider,
+          ],
+          child: Builder(
+            builder: (context) {
+              final number = numberProvider.of(context);
+              return Text(number.toString());
+            },
+          ),
+        ),
+      ),
+    ),
+  );
+  expect(find.text('100'), findsOneWidget);
+});
+```
+
+Testing is possible also with providers that take an argument, and it is done same exact way. The text displayed in the following example will be "16".
+
+```dart
+testWidgets(
+    '''ProviderScopeOverride should override argument providers''',
+    (tester) async {
+  final numberProvider = Provider.withArgument((context, int arg) => arg * 2);
+  await tester.pumpWidget(
+    ProviderScopeOverride(
+      overrides: [
+        numberProvider.overrideWithValue(8),
+      ],
+      child: MaterialApp(
+        home: ProviderScope(
+          providers: [
+            numberProvider(1),
+          ],
+          child: Builder(
+            builder: (context) {
+              final number = numberProvider.of(context);
+              return Text(number.toString());
+            },
+          ),
+        ),
+      ),
+    ),
+  );
+  expect(find.text('16'), findsOneWidget);
+});
+```