Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(docs): add useFragment_experimental documentation #10099

Merged
merged 1 commit into from
Sep 14, 2022

Conversation

alessbell
Copy link
Member

@alessbell alessbell commented Sep 12, 2022

Closes #10056. Adds useFragment_experimental documentation.

CleanShot 2022-09-13 at 11 05 24@2x

This PR:

To do:

Checklist:

  • If this PR is a new feature, please reference an issue where a consensus about the design was reached (not necessary for small changes)
  • Make sure all of the significant new logic is covered by tests

@alessbell alessbell linked an issue Sep 12, 2022 that may be closed by this pull request
5 tasks
@alessbell alessbell mentioned this pull request Sep 12, 2022
5 tasks
Copy link
Contributor

@StephenBarlow StephenBarlow left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved on the docs side with suggestions!

docs/shared/useFragment-options.mdx Outdated Show resolved Hide resolved
docs/shared/useFragment-options.mdx Outdated Show resolved Hide resolved
docs/shared/useFragment-options.mdx Outdated Show resolved Hide resolved
docs/source/api/react/hooks-experimental.mdx Show resolved Hide resolved
docs/source/api/react/hooks-experimental.mdx Outdated Show resolved Hide resolved
docs/source/api/react/hooks-experimental.mdx Outdated Show resolved Hide resolved
docs/source/api/react/hooks-experimental.mdx Outdated Show resolved Hide resolved
docs/source/api/react/hooks-experimental.mdx Outdated Show resolved Hide resolved
@jpvajda
Copy link
Contributor

jpvajda commented Sep 13, 2022

@StephenBarlow thanks for all the great bits of feedback. 🙏 I like this a lot, but I'm curious if we could add a clear use case or example as I find it nice when we say things like:

Let's say you want to do X with Y... Well here is how you can with this new thing we are releasing...

@alessbell

@StephenBarlow
Copy link
Contributor

@jpvajda That addition might make the most sense as a separate section (marked "experimental") in this doc: https://www.apollographql.com/docs/react/caching/cache-interaction

The hook is always for reading and reacting to changes in cached data, correct?

@alessbell
Copy link
Member Author

Thanks for the review, @StephenBarlow! I like the idea of adding a section to the cache-interaction page - I should be able to wrap this up tomorrow 😄

@alessbell alessbell force-pushed the issue-10056-useFragment-documentation branch 2 times, most recently from f7dd0b3 to c26fb36 Compare September 13, 2022 14:54
Copy link
Member

@benjamn benjamn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Details 😈

docs/source/api/react/hooks-experimental.mdx Outdated Show resolved Hide resolved

<td>

**Required.** The cached object (or object reference) for the fragment being retrieved.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**Required.** The cached object (or object reference) for the fragment being retrieved.
**Required.** An object containing a `__typename` and primary key fields (such as `id`) identifying the entity object from which the fragment will be retrieved, or a `{ __ref: "..." }` reference, or a `string` ID (uncommon)

Need to be a little more specific than "the cached object"

Copy link
Member Author

@alessbell alessbell Sep 13, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, +1 for the details and updated the PR 👍 I took this from the InMemoryCache docs section on the identify method's signature and would be happy to update it there too.


<td>

An object or string containing an error message or path to cached items with corresponding error messages.
Copy link
Member

@benjamn benjamn Sep 13, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
An object or string containing an error message or path to cached items with corresponding error messages.
A tree of all `MissingFieldError` messages reported during fragment reading, where the branches of the tree indicate the paths of the errors within the query result

I should mention I'm especially open to feedback on this part of the (experimental) API. The MissingTree can be a lot more compact than a list of error objects, but some details require explanation, like how arrays are represented as objects in the MissingTree (because they tend to be sparse).

Copy link
Member Author

@alessbell alessbell Sep 13, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense, made that update - I'm curious about the best way to solicit feedback here but that's a more general question about the way we gather input on features in beta/preview.

docs/shared/useFragment-result.mdx Outdated Show resolved Hide resolved
@alessbell alessbell force-pushed the issue-10056-useFragment-documentation branch from c26fb36 to ee2ff81 Compare September 13, 2022 16:19
@alessbell alessbell merged commit d0da9d3 into main Sep 14, 2022
@alessbell alessbell deleted the issue-10056-useFragment-documentation branch September 14, 2022 15:31
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Feb 15, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

useFragment documentation
4 participants