RJS-2648: Add ability for Realm instance to be used in RealmProvider

[gagik]

What, How & Why?

@realm/devdocs

What, How

1. The default RealmProvider (or any empty provider created from createRealmContext()) is the most generic provider which has mutually exclusive PropTypes that accepts either an existing realm or Realm configuration fields as props.

import { RealmProvider } from `@realm/react`;
...
return <>
  {/* Valid */}
  <RealmProvider realm={new Realm(...)}> ... </RealmProvider>
  {/* Valid */}
  <RealmProvider schema={[catSchema]} path="test.realm" realmRef={ref}> ... </RealmProvider>
  {/* Invalid, would raise a type exception */}
  <RealmProvider realm={new Realm()} schema={[catSchema]}> ... </RealmProvider>
</>

2. Provider created from using an existing Realm instance, i.e. createRealmContext(realm) is a simple wrapper with no props, just children. NOTE: This provider is not necessary, you can use the hooks without it as long as you import from the correct context!

const { RealmProvider, useRealm } = createRealmContext(realm);
...
<>
   {/* This provider is valid but not needed */}
  <RealmProvider> ... </RealmProvider>
  <AnotherComponent>
  {/*  When using createRealmContext(realm) with an existing Realm,
       you can use the hooks outside of the scope of the provider! */}
  </AnotherComponent>
</>

3. Provider created from a configuration, i.e. createRealmContext({schema: [...]) allows you to use all the Realm configuration settings as well as the existing special @realm/react props.

const { RealmProvider } = createRealmContext({schema: [catSchema]});
...
<RealmProvider closeOnUnmount={false} realmRef={ref} path="thing.realm" schema={...}> ... </RealmProvider>

Nesting

If two default providers are nested, the deepest provider will take precedence, i.e.

<RealmProvider realm={realmA}>
     <RealmProvider realm={realmB}>
            {/* Running useRealm() here will return realmB */}
      </RealmProvider>
</RealmProvider>

Same applies for configuration-based providers.

Why?

Unlocks new usecases and abilities for the RealmProvider, where one might want to use their own managed Realm in the context.

This closes #6283

☑️ ToDos

• 📝 Changelog entry
• 📝 Compatibility label is updated or copied from previous entry
• 📝 Update COMPATIBILITY.md
• 🚦 Tests
• 📦 Updated internal package version in consuming package.jsons (if updating internal packages)
• 📱 Check the React Native/other sample apps work if necessary
• 💥 Breaking label has been applied or is not necessary

[gagik]

Some things worth discussing.

[elle-j]

Nice to see this feature coming alive 🎉 Leaving my comments from a first pass. (Haven't gone through all of it yet.)

[kraenhansen]

I really like they way you're expressing the two mutually exclusive modes of the provider and also tying that back with the createRealmContext - Great stuff! 🎉 I have minor comments, but nothing blocking a merge.

[kraenhansen]

I think it would be good to have a few tests using @ts-expect-error comments to assert the mutual exclusivity of the different props.

[elle-j]

Awesome work and nicely documented! 🙂