@modular-component/with-fragment 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @modular-component/with-fragment
 
+## 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

@@ -8,60 +8,114 @@ specifying a field key to use and returning a single React node.
 
 ## Usage
 
+**Stage function imports**
+
 ```tsx
 import { ModularComponent, render } from '@modular-component/core'
-import { fragment } from '@modular-component/with-fragment'
+import { fragment, fragments } from '@modular-component/with-fragment'
+
+// Through multiple calls
+const MultipleCalls = ModularComponent<{ loading: boolean }>()
+  .with(fragment('loading', <div>Loading...</div>))
+  .with(fragment('loaded', <div>Loaded</div>))
+  .with(
+    render(({ props, loading, loaded }) => (
+      <div>Current status: {props.loading ? loading : loaded}</div>
+    )),
+  )
+
+// Through a single call
+const SingleCall = ModularComponent<{ loading: boolean }>()
+  .with(
+    fragments({
+      loading: <div>Loading...</div>,
+      loaded: <div>Loaded</div>,
+    }),
+  )
+  .with(
+    render(({ props, fragments }) => (
+      <div>
+        Current status: {props.loading ? fragments.loading : fragments.loaded}
+      </div>
+    )),
+  )
+```
+
+**Stage registration**
+
+```tsx
+import { ModularComponent } from '@modular-component/core'
+import '@modular-component/core/register'
+import '@modular-component/with-fragment/register'
 
 // Through multiple calls
 const MultipleCalls = ModularComponent<{ loading: boolean }>()
-  .with(fragment('loading', () => <div>Loading...</div>))
-  .with(fragment('loaded', () => <div>Loaded</div>))
-  .with(render(({ props, loading, loaded }) => (
+  .withFragment('loading', <div>Loading...</div>)
+  .withFragment('loaded', <div>Loaded</div>)
+  .withRender(({ props, loading, loaded }) => (
     <div>Current status: {props.loading ? loading : loaded}</div>
-  )))
+  ))
 
 // Through a single call
 const SingleCall = ModularComponent<{ loading: boolean }>()
-  .with(fragment(() => ({
+  .withFragments({
     loading: <div>Loading...</div>,
     loaded: <div>Loaded</div>,
-  }))
-  .with(render(({ props, fragments }) => (
-    <div>Current status: {props.loading ? fragments.loading : fragments.loaded}</div>
-  ))))
+  })
+  .withRender(({ props, fragments }) => (
+    <div>
+      Current status: {props.loading ? fragments.loading : fragments.loaded}
+    </div>
+  ))
 ```
 
-## Implementation
+## Reacting to previous stages
+
+The fragment argument can either be a JSX fragment, or a function
+receiving the previous stages arguments and returning a JSX fragment:
 
-`with(fragment)` receives a function taking the current arguments map as parameter and returns either a map of React node
-or a single React node, to set as stage function, and optionally a key to be used as the field.
+```tsx
+const UserCard = ModularComponent<{
+  firstName: string
+  lastName: string
+  email: string
+}>()
+  .withFragment('name', ({ props }) => (
+    <p>
+      {props.firstName} {props.lastName}
+    </p>
+  ))
+  .withFragment('email', ({ props }) => <p>{props.email}</p>)
+  .withRender(({ name, email }) => (
+    <article>
+      {name}
+      {email}
+    </article>
+  ))
+```
+
+## Stage registration
+
+You can either automatically register the stages on `withFragment` and `withFragments` by importing `@modular-component/with-fragment/register`,
+or handle the registration manually thanks to the `fragment` and `fragments` functions, and `WithFragment` and `WithFragments` type exports.
 
 ```ts
-import { ReactNode } from 'react'
-import { ModularStage } from '@modular-component/core'
-
-export function fragment<
-  Args extends {},
-  Fragments extends Record<string, ReactNode>,
->(
-  useFragment: (args: Args) => Fragments,
-): ModularStage<'fragments', (args: Args) => Fragments>
-export function fragment<
-  Args extends {},
-  Fragment extends ReactNode,
-  Key extends string,
->(
-  key: Key,
-  useFragment: (args: Args) => Fragment,
-): ModularStage<Key, (args: Args) => Fragment>
-
-export function fragment<Key extends string, Stage extends () => unknown>(
-  key: Key | Stage,
-  useFragment?: Stage,
-): ModularStage<Key, Stage> {
-  return {
-    field: (typeof key === 'string' ? key : 'fragments') as Key,
-    useStage: (typeof key === 'string' ? useFragment : key) as Stage,
+import { ModularComponent, ModularContext } from '@modular-component/core'
+import {
+  fragment,
+  fragments,
+  WithFragment,
+  WithFragments,
+} from '@modular-component/with-fragment'
+
+// Register the stages on the factory
+ModularComponent.register({ fragment, fragments })
+
+// Extend the type definition
+declare module '@modular-component/stages' {
+  export interface ModularComponentStages<Context extends ModularContext> {
+    withFragment: WithFragment<Context>
+    withFragments: WithFragment<Context>
   }
 }
 ```

package/dist/index.d.ts

@@ -1,5 +1,15 @@
-import { ReactNode } from 'react';
-import { ModularStage } from '@modular-component/core';
-export declare function fragment<Args extends {}, Fragments extends Record<string, ReactNode>>(useFragment: (args: Args) => Fragments): ModularStage<'fragments', (args: Args) => Fragments>;
-export declare function fragment<Args extends {}, Fragment extends ReactNode, Key extends string>(key: Key, useFragment: (args: Args) => Fragment): ModularStage<Key, (args: Args) => Fragment>;
+import { FunctionComponent } from 'react';
+import { ModularContext, GetConstraintFor, GetValueGetterFor, StageParams, StageReturn } from '@modular-component/core/extend';
+export declare function fragment<Context extends ModularContext, Field extends string>(field: Field, fragment: GetValueGetterFor<Context, Field, ReturnType<FunctionComponent>>): (_?: Context | undefined) => {
+    field: Field;
+    provide: (args: import("@modular-component/core/extend").GetArgsFor<Context, Field>) => import("react").ReactElement<any, any> | null;
+};
+export type WithFragment<Context extends ModularContext> = <Field extends string>(...args: StageParams<typeof fragment<Context, Field>>) => StageReturn<typeof fragment<Context, Field>>;
+type Constraint<Context extends ModularContext> = GetConstraintFor<Context, 'fragments', Record<string, ReturnType<FunctionComponent>>>;
+export declare function fragments<Context extends ModularContext, Type extends Constraint<Context>>(fragments: GetValueGetterFor<Context, 'fragments', Type>): (_?: Context | undefined) => {
+    field: "fragments";
+    provide: (args: import("@modular-component/core/extend").GetArgsFor<Context, "fragments">) => Type;
+};
+export type WithFragments<Context extends ModularContext> = <Type extends Constraint<Context>>(...args: StageParams<typeof fragments<Context, Type>>) => StageReturn<typeof fragments<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,SAAS,EAAE,MAAM,OAAO,CAAA;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAEtD,wBAAgB,QAAQ,CACtB,IAAI,SAAS,EAAE,EACf,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAE3C,WAAW,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,GACrC,YAAY,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAA;AACvD,wBAAgB,QAAQ,CACtB,IAAI,SAAS,EAAE,EACf,QAAQ,SAAS,SAAS,EAC1B,GAAG,SAAS,MAAM,EAElB,GAAG,EAAE,GAAG,EACR,WAAW,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,QAAQ,GACpC,YAAY,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAA;AACzC,OAAO,EAGL,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,WAAW,EACZ,MAAM,gCAAgC,CAAA;AAEvC,wBAAgB,QAAQ,CAAC,OAAO,SAAS,cAAc,EAAE,KAAK,SAAS,MAAM,EAC3E,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,iBAAiB,CAAC,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,iBAAiB,CAAC,CAAC;;;EAG3E;AAED,MAAM,MAAM,YAAY,CAAC,OAAO,SAAS,cAAc,IAAI,CACzD,KAAK,SAAS,MAAM,EAEpB,GAAG,IAAI,EAAE,WAAW,CAAC,OAAO,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,KAClD,WAAW,CAAC,OAAO,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAA;AAEjD,KAAK,UAAU,CAAC,OAAO,SAAS,cAAc,IAAI,gBAAgB,CAChE,OAAO,EACP,WAAW,EACX,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAC9C,CAAA;AAED,wBAAgB,SAAS,CACvB,OAAO,SAAS,cAAc,EAC9B,IAAI,SAAS,UAAU,CAAC,OAAO,CAAC,EAChC,SAAS,EAAE,iBAAiB,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC;;;EAEzD;AAED,MAAM,MAAM,aAAa,CAAC,OAAO,SAAS,cAAc,IAAI,CAC1D,IAAI,SAAS,UAAU,CAAC,OAAO,CAAC,EAEhC,GAAG,IAAI,EAAE,WAAW,CAAC,OAAO,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,KAClD,WAAW,CAAC,OAAO,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAA"}

package/dist/index.js

@@ -1,7 +1,8 @@
-export function fragment(key, useFragment) {
-    return {
-        field: (typeof key === 'string' ? key : 'fragments'),
-        useStage: (typeof key === 'string' ? useFragment : key),
-    };
+import { addTo, wrap, } from '@modular-component/core/extend';
+export function fragment(field, fragment) {
+    return addTo().on(field).provide(wrap(fragment));
+}
+export function fragments(fragments) {
+    return addTo().on('fragments').provide(wrap(fragments));
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkBA,MAAM,UAAU,QAAQ,CACtB,GAAgB,EAChB,WAAmB;IAEnB,OAAO;QACL,KAAK,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAQ;QAC3D,QAAQ,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAU;KACjE,CAAA;AACH,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,EACL,IAAI,GAML,MAAM,gCAAgC,CAAA;AAEvC,MAAM,UAAU,QAAQ,CACtB,KAAY,EACZ,QAA0E;IAE1E,OAAO,KAAK,EAAW,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAA;AAC3D,CAAC;AAcD,MAAM,UAAU,SAAS,CAGvB,SAAwD;IACxD,OAAO,KAAK,EAAW,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAA;AAClE,CAAC"}

package/package.json

@@ -8,7 +8,7 @@
     "Default",
     "Conditional"
   ],
-  "version": "0.2.3",
+  "version": "0.3.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -17,6 +17,8 @@
   "files": [
     "src",
     "dist",
+    "register.js",
+    "register.d.ts",
     "CHANGELOG.md"
   ],
   "scripts": {
@@ -25,15 +27,14 @@
     "build:self": "tsc -p tsconfig.build.json",
     "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,9 @@
+import { ModularContext } from '@modular-component/core'
+import { WithFragment, WithFragments } from '@modular-component/with-fragment'
+
+declare module '@modular-component/stages' {
+  export interface ModularComponentStages<Context extends ModularContext> {
+    withFragment: WithFragment<Context>
+    withFragments: WithFragments<Context>
+  }
+}

package/register.js

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

package/src/index.ts

@@ -1,27 +1,42 @@
-import { ReactNode } from 'react'
-import { ModularStage } from '@modular-component/core'
+import { FunctionComponent } from 'react'
+import {
+  addTo,
+  wrap,
+  ModularContext,
+  GetConstraintFor,
+  GetValueGetterFor,
+  StageParams,
+  StageReturn,
+} from '@modular-component/core/extend'
 
-export function fragment<
-  Args extends {},
-  Fragments extends Record<string, ReactNode>,
->(
-  useFragment: (args: Args) => Fragments,
-): ModularStage<'fragments', (args: Args) => Fragments>
-export function fragment<
-  Args extends {},
-  Fragment extends ReactNode,
-  Key extends string,
+export function fragment<Context extends ModularContext, Field extends string>(
+  field: Field,
+  fragment: GetValueGetterFor<Context, Field, ReturnType<FunctionComponent>>,
+) {
+  return addTo<Context>().on(field).provide(wrap(fragment))
+}
+
+export type WithFragment<Context extends ModularContext> = <
+  Field extends string,
 >(
-  key: Key,
-  useFragment: (args: Args) => Fragment,
-): ModularStage<Key, (args: Args) => Fragment>
+  ...args: StageParams<typeof fragment<Context, Field>>
+) => StageReturn<typeof fragment<Context, Field>>
 
-export function fragment<Key extends string, Stage extends () => unknown>(
-  key: Key | Stage,
-  useFragment?: Stage,
-): ModularStage<Key, Stage> {
-  return {
-    field: (typeof key === 'string' ? key : 'fragments') as Key,
-    useStage: (typeof key === 'string' ? useFragment : key) as Stage,
-  }
+type Constraint<Context extends ModularContext> = GetConstraintFor<
+  Context,
+  'fragments',
+  Record<string, ReturnType<FunctionComponent>>
+>
+
+export function fragments<
+  Context extends ModularContext,
+  Type extends Constraint<Context>,
+>(fragments: GetValueGetterFor<Context, 'fragments', Type>) {
+  return addTo<Context>().on('fragments').provide(wrap(fragments))
 }
+
+export type WithFragments<Context extends ModularContext> = <
+  Type extends Constraint<Context>,
+>(
+  ...args: StageParams<typeof fragments<Context, Type>>
+) => StageReturn<typeof fragments<Context, Type>>