Skip to content

Commit c633451

Browse files
update function naming, removing all instances of builder and changing to extender.
1 parent 076c08c commit c633451

7 files changed

+146
-153
lines changed

README.md

+58-58
Original file line numberDiff line numberDiff line change
@@ -19,20 +19,20 @@ $ npm install react-extend-components
1919
```
2020
## Basic Usage
2121

22-
First define a `ComponentBuilderGroup` that you will import in all of your component files.
22+
First define a `ComponentExtenderGroup` that you will import in all of your component files.
2323

2424
```tsx
25-
// in ComponentBuilders.ts
26-
import { createComponentBuilderGroup } from 'react-extend-components';
25+
// in ComponentExtenders.ts
26+
import { createComponentExtenderGroup } from 'react-extend-components';
2727

28-
export const ComponentBuilders = createComponentBuilderGroup();
28+
export const ComponentExtenders = createComponentExtenderGroup();
2929
```
3030
Now you can start writing your components.
3131

3232
```tsx
33-
import { ComponentBuilders } from './ComponentBuilders';
33+
import { ComponentExtenders } from './ComponentExtenders';
3434

35-
export const SubmitButton = ComponentBuilders.button(Button => {
35+
export const SubmitButton = ComponentExtenders.button(Button => {
3636
return <Button
3737
className="SubmitButton"
3838
style={{
@@ -165,18 +165,18 @@ The purpose of this package is to take care of all of this automatically, and al
165165
Here's how you would rewrite the above component using this package.
166166

167167
```tsx
168-
// in ComponentBuilders.ts
168+
// in ComponentExtenders.ts
169169

170-
import { createComponentBuilderGroup } from 'react-extend-components';
170+
import { createComponentExtenderGroup } from 'react-extend-components';
171171

172-
export const ComponentBuilders = createComponentBuilderGroup();
172+
export const ComponentExtenders = createComponentExtenderGroup();
173173

174174
// in Form.tsx
175175

176-
import { ComponentBuilders } from './ComponentBuilders';
176+
import { ComponentExtenders } from './ComponentExtenders';
177177
import { useRef } from 'react';
178178

179-
export const SubmitButton = ComponentBuilders.button(Button => {
179+
export const SubmitButton = ComponentExtenders.button(Button => {
180180
const buttonRef = useRef<HTMLButtonElement>(null);
181181
return <Button
182182
ref={buttonRef}
@@ -228,10 +228,10 @@ Also, the library automatically gives the users of the component access to the a
228228
You might be wondering how you would add custom props to your component. Here's how you would do this.
229229

230230
```tsx
231-
import { ComponentBuilders } from './ComponentBuilders';
231+
import { ComponentExtenders } from './ComponentExtenders';
232232
import { ComponentType } from 'react';
233233

234-
export const SubmitButton = ComponentBuilders.button<{
234+
export const SubmitButton = ComponentExtenders.button<{
235235
buttonTitle: string;
236236
Icon?: ComponentType<{className?: string}>
237237
}>((Button, props) => {
@@ -268,9 +268,9 @@ Note that if any of your custom prop names clash with the base element's prop na
268268
By default, the `children` prop is excluded from the type information of the resulting component. This is because, usually, components would want to add their own children to the underlying element or have specific control over how values provided to `children` are dealt with.
269269

270270
```tsx
271-
import { ComponentBuilders } from './ComponentBuilders';
271+
import { ComponentExtenders } from './ComponentExtenders';
272272

273-
const HeaderView = ComponentBuilders.header(Header => {
273+
const HeaderView = ComponentExtenders.header(Header => {
274274
return <Header>
275275
<h1>My Awesome Header</h1>
276276
</Header>
@@ -281,9 +281,9 @@ const HeaderView = ComponentBuilders.header(Header => {
281281
If you want to give users the ability to add a `children` prop, add it to your custom props type information.
282282

283283
```tsx
284-
import { ComponentBuilders } from './ComponentBuilders';
284+
import { ComponentExtenders } from './ComponentExtenders';
285285

286-
const HeaderView = ComponentBuilders.header<{
286+
const HeaderView = ComponentExtenders.header<{
287287
children?: string
288288
}>((Header, props) => {
289289
const { children } = props.pluck('children');
@@ -302,9 +302,9 @@ For whatever reason, you might want to have access to all the props that were pa
302302
To do this, use the `props.peek` function.
303303

304304
```tsx
305-
import { ComponentBuilders } from './ComponentBuilders';
305+
import { ComponentExtenders } from './ComponentExtenders';
306306

307-
const Link = ComponentBuilders.a((A, props) => {
307+
const Link = ComponentExtenders.a((A, props) => {
308308
const { href } = props.peek(); // The underlying anchor element will still receive all the passed props (including href), but you can still 'peek' at the value.
309309
return <A className="app-link">
310310
My AwesomeLink
@@ -319,9 +319,9 @@ When working with function components, React prevents you from treating a ref li
319319
You can pluck a ref as you would expect.
320320

321321
```tsx
322-
import { ComponentBuilders } from './ComponentBuilders';
322+
import { ComponentExtenders } from './ComponentExtenders';
323323

324-
const ListItemView = ComponentBuilders.div((Div, props) => {
324+
const ListItemView = ComponentExtenders.div((Div, props) => {
325325

326326
const { ref } = props.pluck('ref') // now the ref won't be passed to the underlying element
327327
return <Div className="list-item-view">
@@ -333,10 +333,10 @@ const ListItemView = ComponentBuilders.div((Div, props) => {
333333
Here's how you would implement a custom ref.
334334

335335
```tsx
336-
import { ComponentBuilders } from './ComponentBuilders';
336+
import { ComponentExtenders } from './ComponentExtenders';
337337
import { useImperativeHandle } from 'react';
338338

339-
const DialogBox = ComponentBuilders.div<
339+
const DialogBox = ComponentExtenders.div<
340340
{}, // add custom prop types here
341341
{ // add the type of the ref as the second generic parameter
342342
setOpened: (isOpen: boolean) => void;
@@ -358,22 +358,22 @@ const DialogBox = ComponentBuilders.div<
358358

359359
## Custom Components
360360

361-
By default, the `createComponentBuilderGroup` factory function gives you access to all the html elements listed in React's JSX.IntrinsicElements interface.
361+
By default, the `createComponentExtenderGroup` factory function gives you access to all the html elements listed in React's JSX.IntrinsicElements interface.
362362

363363
You're able to use them with this convenient syntax.
364364

365365
```tsx
366-
// in ComponentBuilders.ts
366+
// in ComponentExtenders.ts
367367

368-
import { createComponentBuilderGroup } from 'react-extend-components';
368+
import { createComponentExtenderGroup } from 'react-extend-components';
369369

370-
export const ComponentBuilders = createComponentBuilderGroup();
370+
export const ComponentExtenders = createComponentExtenderGroup();
371371

372372
// in MyComponent.tsx
373373

374-
import { ComponentBuilders } from './ComponentBuilders';
374+
import { ComponentExtenders } from './ComponentExtenders';
375375

376-
export const MyComponent = ComponentBuilders.div( // or section, or form, or button, or any other html tag
376+
export const MyComponent = ComponentExtenders.div( // or section, or form, or button, or any other html tag
377377
Div => {
378378
return <Div>{/* ... */}</Div>
379379
}
@@ -383,33 +383,33 @@ export const MyComponent = ComponentBuilders.div( // or section, or form, or but
383383
But you also have the ability to do the same with custom components that you've made yourself. The library makes this completely type-safe as well.
384384

385385
```tsx
386-
import { ComponentBuilders } from './ComponentBuilders';
386+
import { ComponentExtenders } from './ComponentExtenders';
387387
import { MainAppButton } from './MainAppButton';
388388

389-
export const MyComponent = ComponentBuilders(MainAppButton)(Button => {
389+
export const MyComponent = ComponentExtenders(MainAppButton)(Button => {
390390
return <Button>{/* ... */}</Button>
391391
})
392392
```
393393

394394
Please note, however, that the types for all the props of the root element (`MainAppButton` in this case), are marked as optional by default. If you would like to require those props, add them to your [custom props](#customizing-props) generic parameter.
395395

396-
You can also define custom components in an `additionalComponents` object when creating your component builder so that you can access them on the builder using the same dot syntax that you would use for html elements.
396+
You can also define custom components in an `additionalComponents` object when creating your component extender so that you can access them on the extender using the same dot syntax that you would use for html elements.
397397

398398
```tsx
399-
// in ComponentBuilders.ts
399+
// in ComponentExtenders.ts
400400

401401
import { MainAppButton } from './MainAppButton';
402-
import { createComponentBuilderGroup } from 'react-extend-components';
402+
import { createComponentExtenderGroup } from 'react-extend-components';
403403

404-
export const ComponentBuilders = createComponentBuilderGroup({
404+
export const ComponentExtenders = createComponentExtenderGroup({
405405
MainAppButton
406406
});
407407

408408
// in MyComponent.tsx
409409

410-
import { ComponentBuilders } from './ComponentBuilders';
410+
import { ComponentExtenders } from './ComponentExtenders';
411411

412-
export const MyComponent = ComponentBuilders.MainAppButton(
412+
export const MyComponent = ComponentExtenders.MainAppButton(
413413
Button => {
414414
return <Button />
415415
}
@@ -423,9 +423,9 @@ When you pass the same prop to the resulting component as well as to the underly
423423
- **The `style` prop:** The style properties passed to the outermost component will override the properties passed to the inner element.
424424

425425
```tsx
426-
import { ComponentBuilders } from './ComponentBuilders';
426+
import { ComponentExtenders } from './ComponentExtenders';
427427

428-
export const MyButton = ComponentBuilders.button(Button => {
428+
export const MyButton = ComponentExtenders.button(Button => {
429429
return <Button style={{
430430
backgroundColor: 'purple',
431431
color: 'white',
@@ -444,9 +444,9 @@ export const MyButton = ComponentBuilders.button(Button => {
444444
```
445445
- **The `className` prop:** The className string passed to the outermost component is appended to the className string passed to the inner element.
446446
```tsx
447-
import { ComponentBuilders } from './ComponentBuilders';
447+
import { ComponentExtenders } from './ComponentExtenders';
448448

449-
export const MyButton = ComponentBuilders.button(Button => {
449+
export const MyButton = ComponentExtenders.button(Button => {
450450
return <Button className="My-Button">My Button</Button>
451451
});
452452

@@ -460,9 +460,9 @@ export const MyButton = ComponentBuilders.button(Button => {
460460
- **Functions:** Functions are merged together by passing a new function to the prop that first calls the inner component function prop, then the outer one. The return value of the outer prop is the one that the function will return (if the outer prop is set).
461461
462462
```tsx
463-
import { ComponentBuilders } from './ComponentBuilders';
463+
import { ComponentExtenders } from './ComponentExtenders';
464464

465-
export const MyButton = ComponentBuilders.button(Button => {
465+
export const MyButton = ComponentExtenders.button(Button => {
466466
return <Button
467467
onClick={() => {
468468
// This function will be called first
@@ -483,9 +483,9 @@ export const MyButton = ComponentBuilders.button(Button => {
483483
Please note that in a situation where either the inner prop or outer prop is a function and the other one is a non-function (with the exception of null and undefined), the outer prop will always replace the inner one.
484484
485485
```tsx
486-
import { ComponentBuilders } from './ComponentBuilders';
486+
import { ComponentExtenders } from './ComponentExtenders';
487487

488-
export const MyButton = ComponentBuilders.button(Button => {
488+
export const MyButton = ComponentExtenders.button(Button => {
489489
return <Button
490490
onClick={() => {
491491
// this function will never be called because the corresponding outer prop is a string and it will override this value
@@ -503,9 +503,9 @@ export const MyButton = ComponentBuilders.button(Button => {
503503
- **The `children` prop:** The inner children prop will always override the outer prop if the inner prop is anything other than undefined.
504504
505505
```tsx
506-
import { ComponentBuilders } from './ComponentBuilders';
506+
import { ComponentExtenders } from './ComponentExtenders';
507507

508-
export const MyButton = ComponentBuilders.button<{
508+
export const MyButton = ComponentExtenders.button<{
509509
children?: string
510510
}>(Button => {
511511
return <Button>
@@ -523,9 +523,9 @@ export const MyButton = ComponentBuilders.button<{
523523
If you would like to allow users to customize the children of the component, pluck the `children` prop.
524524
525525
```tsx
526-
import { ComponentBuilders } from './ComponentBuilders';
526+
import { ComponentExtenders } from './ComponentExtenders';
527527

528-
export const MyButton = ComponentBuilders.button<{
528+
export const MyButton = ComponentExtenders.button<{
529529
children?: string
530530
}>((Button, props) => {
531531
const { children } = props.pluck('children');
@@ -543,9 +543,9 @@ export const MyButton = ComponentBuilders.button<{
543543
544544
- **Any Other Prop:** For any other prop, the outer props will override the inner props.
545545
```tsx
546-
import { ComponentBuilders } from './ComponentBuilders';
546+
import { ComponentExtenders } from './ComponentExtenders';
547547

548-
export const MyButton = ComponentBuilders.button(Button => {
548+
export const MyButton = ComponentExtenders.button(Button => {
549549
return <Button
550550
title="My Button" // this value will be ignored
551551
>My Button</Button>
@@ -566,9 +566,9 @@ You are given the option to implement a custom merge function if the provided me
566566
Here's how you would implement it.
567567
568568
```tsx
569-
import { createComponentBuilderGroup } from 'react-extend-components';
569+
import { createComponentExtenderGroup } from 'react-extend-components';
570570

571-
export const ComponentBuilders = createComponentBuilderGroup({
571+
export const ComponentExtenders = createComponentExtenderGroup({
572572
propsMergeFn: ({
573573
innerProps,
574574
outerProps,
@@ -592,9 +592,9 @@ Note that you will only receive props in the `outerProps` object that were not '
592592
You are provided with the `defaultMergeFn` in the merge function, which you may find useful if you'd just like to merge a specific prop but have the library handle the rest.
593593
594594
```tsx
595-
import { createComponentBuilderGroup } from 'react-extend-components';
595+
import { createComponentExtenderGroup } from 'react-extend-components';
596596

597-
export const ComponentBuilders = createComponentBuilderGroup({
597+
export const ComponentExtenders = createComponentExtenderGroup({
598598
propsMergeFn: ({
599599
innerProps,
600600
outerProps,
@@ -613,9 +613,9 @@ export const ComponentBuilders = createComponentBuilderGroup({
613613
You can also specify a customized merge function at the individual component level.
614614
615615
```tsx
616-
import { ComponentBuilders } from './ComponentBuilders';
616+
import { ComponentExtenders } from './ComponentExtenders';
617617

618-
const MyComponent = ComponentBuilders.div(Div => {
618+
const MyComponent = ComponentExtenders.div(Div => {
619619
return <Div></Div>
620620
}, ({
621621
innerProps,
@@ -627,4 +627,4 @@ const MyComponent = ComponentBuilders.div(Div => {
627627
return
628628
});
629629
```
630-
This will, of course, override the merge function at the Component Builder level.
630+
This will, of course, override the merge function at the Component Extender level.

src/createComponentBuilderGroup.ts

-45
This file was deleted.

0 commit comments

Comments
 (0)