@modular-component/with-components 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @modular-component/with-components
 
+## 0.3.0
+
+### Minor Changes
+
+- 1784a2b: Add a clean way to extend the ModularComponent API with new dedicated stage functions
+
+### Patch Changes
+
+- Updated dependencies [1784a2b]
+  - @modular-component/core@0.3.0
+
 ## 0.2.3
 
 ### Patch Changes

package/README.md

@@ -1,14 +1,16 @@
 # @modular-component/with-components
 
-Provides a `with(components)` stage that fills the `components` argument with
+Provides a `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
 mocking the stage to replace their implementations.
 
 ## Usage
 
+**Stage function imports**
+
 ```tsx
-import { ModularComponent } from '@modular-component/core'
+import { ModularComponent, render } from '@modular-component/core'
 import { components } from '@modular-component/with-components'
 
 import { SomeComponent } from 'some-component'
@@ -18,52 +20,72 @@ const MyComponent = ModularComponent()
   .with(render(({ props, components }) => <components.SomeComponent />))
 ```
 
+**Stage registration**
+
+```tsx
+import { ModularComponent } from '@modular-component/core'
+import '@modular-component/core/register'
+import '@modular-component/with-components/register'
+
+import { SomeComponent } from 'some-component'
+
+const MyComponent = ModularComponent()
+  .withComponents({ SomeComponent })
+  .withRender(({ props, components }) => <components.SomeComponent />)
+```
+
 ## Replacing sub-components
 
 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,
+It allows creating a clone of the component with a different sub-components implementation,
 either for tests or for content.
 For instance, one could imagine a `Layout` base component taking advantage of this functionality:
 
 ```tsx
 const PageLayout = ModularComponent()
-  .with(components({
+  .withComponents({
     Title: React.Fragment,
     Subtitle: React.Fragment,
     Content: React.Fragment,
-    Footer: React.Fragment
-  }))
-  .with(render(({ components }) => (
+    Footer: React.Fragment,
+  })
+  .withRender(({ components }) => {
     // Build a layout using <components.Title />, <components.Subtitle />...
-  )))
+  })
 
-const PageOne = PageLayout.with(components({
+const PageOne = PageLayout.withComponents({
   Title: () => <>First page</>,
   Subtitle: () => <>I have a subtitle but no footer</>,
   Content: () => <>First page content</>,
-  Footer: React.Fragment
-}))
+  Footer: React.Fragment,
+})
 
-const PageTwo = PageLayout.with(components({
+const PageTwo = PageLayout.withComponents({
   Title: () => <>Second page</>,
   Subtitle: React.Fragment,
   Content: () => <>Second page content</>,
-  Footer: () => <>I have a footer but no subtitle</>
-}))
+  Footer: () => <>I have a footer but no subtitle</>,
+})
 ```
 
-## Implementation
+## Stage registration
 
-`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.
+You can either automatically register the stage on `withComponents` by importing `@modular-component/with-components/register`,
+or handle the registration manually thanks to the `components` function and `WithComponents` type exports.
 
-```tsx
-import { ComponentType } from 'react'
-import { ModularStage } from '@modular-component/core'
+For instance, here is how you could register it on `withSubComponents` instead:
+
+```ts
+import { ModularComponent, ModularContext } from '@modular-component/core'
+import { components, WithComponents } from '@modular-component/with-components'
+
+// Register the stage on the factory
+ModularComponent.register({ subComponents: components })
 
-export function components<Components extends Record<string, ComponentType>>(
-  components: Components,
-): ModularStage<'components', () => Components> {
-  return { field: 'components', useStage: () => components }
+// Extend the type definition
+declare module '@modular-component/stages' {
+  export interface ModularComponentStages<Context extends ModularContext> {
+    withSubComponents: WithComponents<Context>
+  }
 }
 ```

package/dist/index.d.ts

@@ -1,4 +1,10 @@
 import { ComponentType } from 'react';
-import { ModularStage } from '@modular-component/core';
-export declare function components<Components extends Record<string, ComponentType>>(components: Components): ModularStage<'components', () => Components>;
+import { ModularContext, GetConstraintFor, GetValueGetterFor, StageParams, StageReturn } from '@modular-component/core/extend';
+type Constraint<Context extends ModularContext> = GetConstraintFor<Context, 'components', Record<string, ComponentType<any>>>;
+export declare function components<Context extends ModularContext, Type extends Constraint<Context>>(components: GetValueGetterFor<Context, 'components', Type>): (_?: Context | undefined) => {
+    field: "components";
+    provide: (args: import("@modular-component/core/extend").GetArgsFor<Context, "components">) => Type;
+};
+export type WithComponents<Context extends ModularContext> = <Type extends Constraint<Context>>(...args: StageParams<typeof components<Context, Type>>) => StageReturn<typeof components<Context, Type>>;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAEtD,wBAAgB,UAAU,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,EACzE,UAAU,EAAE,UAAU,GACrB,YAAY,CAAC,YAAY,EAAE,MAAM,UAAU,CAAC,CAE9C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AACrC,OAAO,EAGL,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,WAAW,EACZ,MAAM,gCAAgC,CAAA;AAEvC,KAAK,UAAU,CAAC,OAAO,SAAS,cAAc,IAAI,gBAAgB,CAChE,OAAO,EACP,YAAY,EACZ,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CACnC,CAAA;AAED,wBAAgB,UAAU,CACxB,OAAO,SAAS,cAAc,EAC9B,IAAI,SAAS,UAAU,CAAC,OAAO,CAAC,EAChC,UAAU,EAAE,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,CAAC;;;EAE3D;AAED,MAAM,MAAM,cAAc,CAAC,OAAO,SAAS,cAAc,IAAI,CAC3D,IAAI,SAAS,UAAU,CAAC,OAAO,CAAC,EAEhC,GAAG,IAAI,EAAE,WAAW,CAAC,OAAO,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,KACnD,WAAW,CAAC,OAAO,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAA"}

package/dist/index.js

@@ -1,4 +1,5 @@
+import { addTo, wrap, } from '@modular-component/core/extend';
 export function components(components) {
-    return { field: 'components', useStage: () => components };
+    return addTo().on('components').provide(wrap(components));
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,UAAU,CACxB,UAAsB;IAEtB,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,UAAU,EAAE,CAAA;AAC5D,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,EACL,IAAI,GAML,MAAM,gCAAgC,CAAA;AAQvC,MAAM,UAAU,UAAU,CAGxB,UAA0D;IAC1D,OAAO,KAAK,EAAW,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAA;AACpE,CAAC"}

package/package.json

@@ -9,7 +9,7 @@
     "Sub-components",
     "Injection"
   ],
-  "version": "0.2.3",
+  "version": "0.3.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -18,23 +18,24 @@
   "files": [
     "src",
     "dist",
+    "register.js",
+    "register.d.ts",
     "CHANGELOG.md"
   ],
   "scripts": {
     "build": "yarn build:core && yarn build:self",
     "build:core": "yarn workspace @modular-component/core build",
-    "build:self": "tsc -p tsconfig.build.json",
+    "build:self": "tsc -p tsconfig.build.json && tsc --noEmit register",
     "license": "cp ../../LICENSE ./LICENSE"
   },
-  "dependencies": {
-    "@modular-component/core": "0.2.3"
-  },
   "peerDependencies": {
+    "@modular-component/core": "0.3.0",
     "react": ">=17 <19"
   },
   "devDependencies": {
+    "@modular-component/core": "*",
     "@types/react": "^18.0.17",
-    "typescript": "^5.2.2"
+    "typescript": "^5.9.3"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts"

package/register.d.ts

@@ -0,0 +1,8 @@
+import { ModularContext } from '@modular-component/core'
+import { WithComponents } from '@modular-component/with-components'
+
+declare module '@modular-component/stages' {
+  export interface ModularComponentStages<Context extends ModularContext> {
+    withComponents: WithComponents<Context>
+  }
+}

package/register.js

@@ -0,0 +1,4 @@
+import { ModularComponent } from '@modular-component/core'
+import { components } from '@modular-component/with-components'
+
+ModularComponent.register({ components })

package/src/index.ts

@@ -1,8 +1,29 @@
 import { ComponentType } from 'react'
-import { ModularStage } from '@modular-component/core'
+import {
+  addTo,
+  wrap,
+  ModularContext,
+  GetConstraintFor,
+  GetValueGetterFor,
+  StageParams,
+  StageReturn,
+} from '@modular-component/core/extend'
 
-export function components<Components extends Record<string, ComponentType>>(
-  components: Components,
-): ModularStage<'components', () => Components> {
-  return { field: 'components', useStage: () => components }
+type Constraint<Context extends ModularContext> = GetConstraintFor<
+  Context,
+  'components',
+  Record<string, ComponentType<any>>
+>
+
+export function components<
+  Context extends ModularContext,
+  Type extends Constraint<Context>,
+>(components: GetValueGetterFor<Context, 'components', Type>) {
+  return addTo<Context>().on('components').provide(wrap(components))
 }
+
+export type WithComponents<Context extends ModularContext> = <
+  Type extends Constraint<Context>,
+>(
+  ...args: StageParams<typeof components<Context, Type>>
+) => StageReturn<typeof components<Context, Type>>