Merge pull request #936 from NullVoxPopuli/better-composition

Revamp docs, provide better composition utilities

.changeset/flat-forks-boil.md

@@ -0,0 +1,124 @@
+---
+"ember-resources": minor
+---
+
+The `use` import from `ember-resources` now supports an alternate style of usage.
+This is partly to provide consistency across the different kinds of resources (and resource builders), whether or not arguments are provided.
+
+The motivation from this change comes from trying to better align with Starbeam's composition capabilities, and "define something once, use it anywhere" approach to that composition.
+
+For example, before, only this was possible:
+
+```js
+import { resource, use } from "ember-resources";
+
+const StuckClock = resource(() => 2);
+
+class MyClass {
+  @use data = StuckClock;
+}
+
+new MyClass().data === 2;
+```
+
+That looks a little awkward, because it looks like `data` is set to a constant.
+In `TypeScript`, this still worked out, and the type of `data` would be a `number`,
+but it still didn't look intuitive.
+
+_Now, we can do this_:
+
+```js
+import { resource, use } from "ember-resources";
+
+const StuckClock = resource(() => 2);
+
+class MyClass {
+  data = use(this, StuckClock);
+}
+
+new MyClass().data.current === 2;
+```
+
+The key difference here is that `data` is now a `Reactive<number>`, which, like a `cell`, has a `.current` property.
+This is a _readonly_ value -- however `current` can still return a mutable data structure.
+
+This style of `use` ends up extending nicely to Resources that take arguments:
+
+```js
+import { tracked } from "@glimmer/tracking";
+import { resource, use, resourceFactory } from "ember-resources";
+
+const Clock = resourceFactory((locale) => resource(/* ... */));
+
+class MyClass {
+  @tracked locale = "en-US";
+
+  data = use(
+    this,
+    Clock(() => this.locale)
+  );
+}
+```
+
+> **Note** <br>
+> The old way of using `@use` as a decorator is still supported, and has no plans of being deprecated.
+
+<details><summary>Another approach</summary>
+
+I can't recommend this approach for general usage, but it is supported under SemVer (for exploration and feedback).
+
+```ts
+import { resource, use } from "ember-resources";
+
+const StuckClock = resource(() => 2);
+
+class MyClass {
+  @use(StuckClock) declare data: number;
+}
+
+new MyClass().data === 2;
+```
+
+This should feel familiar as it looks like what we're familiar with when it comes to declaring `@tracked` properties as well as `@service`s.
+
+However, this has the same problems as `@service` -- in TypeScript, it requires you to use `declare` and specify a type, which may or may not match the actual type of `StuckClock`.
+
+Additionally, whenever we want to pass arguments to the resource, like this:
+
+```ts
+import { tracked } from '@glimmer/tracking';
+import { resource, use } from 'ember-resources';
+
+const Clock = resourceFactory((locale) => resource( /* ... */);
+
+class MyClass {
+  @tracked locale = 'en-US';
+
+  @use(Clock(() => this.locale) declare data: number;
+}
+```
+
+The arrow function passed to `Clock` would not have the correct this.
+This is confusing, because in every other situation where we use classes,
+the arrow function has the same context as the instance of the class.
+But due to how decorators are configured / transpiled, the `this` is actually the surrounding context around `MyClass`, because decorators are _statically applied_.
+
+```ts
+class MyClass {
+  @tracked locale = 'en-US';
+
+  @use(Clock( static context here, not instance ) declare data: number;
+}
+```
+
+So... that's why I want to recommend `property = use(this, Foo)` by default.
+
+```ts
+class MyClass {
+  @tracked locale = 'en-US';
+
+  data = use(this, (Clock( instance access ));
+}
+```
+
+</details>

.gitattributes

@@ -0,0 +1,2 @@
+*.gjs linguist-language=js linguist-detectable
+*.gts linguist-language=ts linguist-detectable

.github/workflows/ci.yml

@@ -48,7 +48,7 @@ jobs:
   typecheck:
     name: '${{ matrix.typescript-scenario }}'
     runs-on: ubuntu-latest
-    timeout-minutes: 2
+    timeout-minutes: 5
     needs: [build]
     continue-on-error: true
     strategy:

README.md

@@ -42,9 +42,11 @@ Which comes from [this branch][self-dist] from [this automation][self-dist-ci]
 ## Documentation
 
 
-- [API Documentation](https://ember-resources.pages.dev/modules)
+- [Resource Authoring](https://github.com/NullVoxPopuli/ember-resources/blob/main/docs/docs/resources.md)
 - [Interactive Tutorial](https://tutorial.glimdown.com/2-reactivity/5-resources)
-- [Resource Authoring](https://github.com/NullVoxPopuli/ember-resources/blob/main/DOCS.md)
+    - [util: RemoteData](https://tutorial.glimdown.com/11-requesting-data/1-using-remote-data)
+    - [util: keepLatest](https://tutorial.glimdown.com/12-loading-patterns/1-keeping-latest)
+- [API Reference](https://ember-resources.pages.dev/modules)
 
 
 ## Contributing
@@ -73,3 +75,4 @@ This library wouldn't be possible without the work of:
 
 So much appreciate for the work both you have put in to Resources <3
 
+

docs/custom.css

@@ -13,13 +13,24 @@
 /*   display: none; */
 /* } */
 
+.site-menu {
+  display: flex;
+  flex-direction: column-reverse;
+  align-self: start;
+  gap: 2rem;
+}
+
+.tsd-small-nested-navigation {
+  display: flex;
+  flex-direction: column-reverse;
+}
+
 #tsd-sidebar-links::before {
-  content: 'Utils';
+  content: "Utils / Examples";
   font-weight: bold;
   margin-bottom: 0.4rem;
   display: block;
   margin-top: 0.5rem;
-  margin-left: -0.25rem;
 }
 
 #tsd-sidebar-links a::after,
@@ -38,3 +49,13 @@
     filter: invert(1);
   }
 }
+
+.callout {
+  border: 1px solid;
+  padding: 0.5rem 1rem;
+}
+
+/* the "On This Page" menu */
+.page-menu .tsd-index-accordion.tsd-page-navigation {
+  display: none;
+}