@modular-component/with-components 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @modular-component/with-components
 
+## 0.2.1
+
+### Patch Changes
+
+- 09b9673: Update readmes
+- Updated dependencies [09b9673]
+  - @modular-component/core@0.2.1
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -1,48 +1,71 @@
-# `@modular-component/with-components`
+# @modular-component/with-components
 
-Provides a `withComponents` stage that fills the `components` argument with
+Provides a `with(components)` stage that fills the `components` argument with
 a map of React components. Useful when running tests in an environment that
 does not allow module mocking: sub-components can be stubbed in tests by
-calling the stage again to replace their implementations.
+mocking the stage to replace their implementations.
 
-## Installation and usage
-
-```bash
-yarn add @modular-component/core @modular-component/with-components
-```
+## Usage
 
 ```tsx
-// Usage in apps
-import { modularFactory } from '@modular-component/core'
-import { WithComponents } from '@modular-component/with-components'
-
-const ModularComponent = modularFactory.extend(WithComponents).build()
-
-const MyModularComponent = ModularComponent()
-  .withComponents({
-    SubComponent: () => <h2>Subtitle</h2>,
-  })
-  .withRender(({ components }) => (
-    <>
-      <h1>Main Title</h1>
-      <components.SubComponent />
-    </>
-  ))
+import { ModularComponent } from '@modular-component/core'
+import { components } from '@modular-component/with-components'
+
+import { SomeComponent } from 'some-component'
+
+const MyComponent = ModularComponent()
+  .with(components({ SomeComponent }))
+  .with(render(({ props, components }) => (
+    <components.SomeComponent />
+  )))
 ```
 
-```tsx
-// Usage in tests
+## Replacing sub-components
 
-const SubComponentMock = someMock()
-const TestMyModularComponent = MyModularComponent.withComponents({
-  SubComponent: SubComponentMock,
-})
+Replacing sub-components can be done either by updating or mocking the stage.
+It allows creating a clone of the component with a different sub-component implementation,
+either for tests or for content.
+For instance, one could imagine a `Layout` base component taking advantage of this functionality:
 
-render(<TestMyModularComponent />)
+```tsx
+const PageLayout = ModularComponent()
+  .with(components({
+    Title: React.Fragment,
+    Subtitle: React.Fragment,
+    Content: React.Fragment,
+    Footer: React.Fragment
+  }))
+  .with(render(({ components }) => (
+    // Build a layout using <components.Title />, <components.Subtitle />...
+  )))
 
-expect(someMock).toHaveBeenCalledOnce()
+const PageOne = PageLayout.with(components({
+  Title: () => <>First page</>,
+  Subtitle: () => <>I have a subtitle but no footer</>,
+  Content: () => <>First page content</>,
+  Footer: React.Fragment
+}))
+
+const PageTwo = PageLayout.with(components({
+  Title: () => <>Second page</>,
+  Subtitle: React.Fragment,
+  Content: () => <>Second page content</>,
+  Footer: () => <>I have a footer but no subtitle</>
+}))
 ```
 
-## Learn more
+## Implementation
+
+`with(components)` is a simple stage adding the provided record as a `components` argument. It has a restriction
+on accepted values, to only accept a record of React components.
 
-Read the [`ModularComponent` ReadMe](https://github.com/jvdsande/modular-component/blob/master/README.md) for more information about the `ModularComponent` system.
+```tsx
+import { ComponentType } from 'react'
+import { ModularStage } from '@modular-component/core'
+
+export function components<Components extends Record<string, ComponentType>>(
+  components: Components,
+): ModularStage<'components', () => Components> {
+  return { field: 'components', useStage: () => components }
+}
+```

package/package.json

@@ -9,7 +9,7 @@
     "Sub-components",
     "Injection"
   ],
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -27,7 +27,7 @@
     "license": "cp ../../LICENSE ./LICENSE"
   },
   "dependencies": {
-    "@modular-component/core": "0.2.0"
+    "@modular-component/core": "0.2.1"
   },
   "peerDependencies": {
     "react": ">=17 <19"