# react-cmp-selector

A powerful and extensible utility for selecting and manipulating React components based on attributes. Ideal for dynamic layouts, slotted rendering, and component injection patterns.

---

## Table of Contents

- [react-cmp-selector](#react-cmp-selector)
  - [Table of Contents](#table-of-contents)
  - [Installation](#installation)
  - [Motivation](#motivation)
  - [Table of Proposals](#table-of-proposals)
  - [Usage](#usage)
    - [1. Basic Slot Matching](#1-basic-slot-matching)
    - [2. Matching Multiple Components](#2-matching-multiple-components)
    - [3. Combining Event Handlers](#3-combining-event-handlers)
    - [4. Declarative API with `<Slot>`](#4-declarative-api-with-slot)
    - [5. Fallback Slot Content](#5-fallback-slot-content)
    - [6. Slot Markers](#6-slot-markers)
    - [7. Slot Validation](#7-slot-validation)
  - [Use Cases](#use-cases)
  - [API Reference](#api-reference)
    - [`getCmpByAttr<P>()`](#getcmpbyattrp)
    - [`ComponentFinderProps`](#componentfinderprops)
    - [`Slot`](#slot)
    - [`SlotUtils`](#slotutils)
  - [Caveats](#caveats)
  - [License](#license)

---

## Installation

```bash
npm install react-cmp-selector
```

or using yarn:

```bash
yarn add react-cmp-selector
```

---

## Motivation

React does not support named slots or dynamic selection of children out of the box. This utility solves that by providing:

- A **hook** to search through children by attribute
- A **component-based API** (`<Slot>`) for declarative slot usage
- Tools to **inject props**, **merge handlers**, and **validate layout contracts**

---

## Table of Proposals

| Feature                       | Prop / Option              | Type                              | Description                                                   |
| ----------------------------- | -------------------------- | --------------------------------- | ------------------------------------------------------------- |
| **Attribute Matching**        | `attribute`                | `string`                          | Attribute name to search for (default: `'data-slot'`)         |
| **Value Matching**            | `value` / `name`           | `string`                          | The value to match against the selected attribute             |
| **Prop Merging**              | `props`                    | `Partial<P>`                      | Injected props to merge into the matched component(s)         |
| **Function Merging Strategy** | `functionPropMerge`        | `'combine' \| 'override'`         | Defines how function props like `onClick` should be merged    |
| **Debug Mode**                | `debug`                    | `boolean`                         | Enables logging of matching and merging behavior              |
| **Match All**                 | `findAll`                  | `boolean`                         | If true, returns all matching components instead of the first |
| **Hook Interface**            | `getCmpByAttr()`           | —                                 | Programmatic interface to extract and modify children         |
| **Declarative API**           | `<Slot>`                   | —                                 | React component alternative to the hook                       |
| **Slot Markers**              | `SlotUtils.createMarker()` | —                                 | Creates a named slot wrapper component                        |
| **Slot Validation**           | `SlotUtils.validate()`     | —                                 | Dev-only validation for required slot presence                |
| **Fallback Rendering**        | `fallback`                 | `ReactNode`                       | Rendered if no matching slot is found                         |
| **onFound Callback**          | `onFound`                  | `(element: ReactElement) => void` | Runs when a match is found (e.g. for side effects)            |

---

## Usage

### 1. Basic Slot Matching

**Children**

```tsx
export function ChildComponents() {
  return (
    <>
      <div data-slot="header">Header</div>
      <div data-slot="body">Body</div>
      <div data-slot="footer">Footer</div>
    </>
  );
}
```

**Parent**

```tsx
const header = getCmpByAttr({
  children: <ChildComponents />,
  value: "header",
  props: { className: "highlighted" },
});
```

**Output**

```html
<div data-slot="header" class="highlighted">Header</div>
```

**How It Works**

- `getCmpByAttr()` searches children for `data-slot="header"`.
- The match is cloned with the `className` prop added.

---

### 2. Matching Multiple Components

**Children**

```tsx
function Buttons() {
  return (
    <>
      <button data-role="action-button">Save</button>
      <button data-role="action-button">Cancel</button>
    </>
  );
}
```

**Parent**

```tsx
const buttons = getCmpByAttr({
  children: <Buttons />,
  attribute: "data-role",
  value: "action-button",
  findAll: true,
  props: { "data-tracked": true },
});
```

**Output**

```html
<button data-role="action-button" data-tracked="true">Save</button>
<button data-role="action-button" data-tracked="true">Cancel</button>
```

---

### 3. Combining Event Handlers

**Children**

```tsx
function CTA() {
  return (
    <button data-slot="cta" onClick={() => console.log("child")}>
      Click Me
    </button>
  );
}
```

**Parent**

```tsx
const cta = getCmpByAttr({
  children: <CTA />,
  value: "cta",
  props: {
    onClick: () => console.log("parent"),
  },
  functionPropMerge: "combine",
});
```

**Behavior**

Console logs:

```
child
parent
```

---

### 4. Declarative API with `<Slot>`

```tsx
export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <div>
      <Slot name="header">{children}</Slot>
      <main>
        <Slot name="content">{children}</Slot>
      </main>
    </div>
  );
}
```

```tsx
function PageContent() {
  return (
    <>
      <div data-slot="header">Welcome</div>
      <div data-slot="content">Hello, world!</div>
    </>
  );
}

<Layout>
  <PageContent />
</Layout>;
```

**Output**

```html
<div>
  <div data-slot="header">Welcome</div>
  <main>
    <div data-slot="content">Hello, world!</div>
  </main>
</div>
```

---

### 5. Fallback Slot Content

```tsx
<Slot name="hero" fallback={<div>Default Hero</div>}>
  {children}
</Slot>
```

If no `data-slot="hero"` is found, it renders:

```html
<div>Default Hero</div>
```

---

### 6. Slot Markers

**Marker Declaration**

```tsx
const HeroSlot = SlotUtils.createMarker("hero");

function Page() {
  return (
    <HeroSlot>
      <div className="hero-banner">Custom Hero</div>
    </HeroSlot>
  );
}
```

**Parent**

```tsx
<Slot name="hero" fallback={<div>Default Hero</div>}>
  <Page />
</Slot>
```

---

### 7. Slot Validation

```tsx
SlotUtils.validate(children, ["header", "footer"]);
```

- Dev-only.
- Warns if `data-slot="header"` or `footer` is missing in children.

---

## Use Cases

- **Composable Layouts**: Dynamically slot content into shared layouts.
- **Design Systems**: Enable flexible API layers with predictable slot names.
- **Multi-brand / White-label UIs**: Inject branding-specific content without hardcoding.
- **Next.js Layouts**: Use context + slots to bridge `app/layout.tsx` and pages.
- **Dynamic Prop Injection**: Apply analytics, A/B testing, or class injection to specific slots.

---

## API Reference

### `getCmpByAttr<P>()`

```ts
function getCmpByAttr<P>(
  options: ComponentFinderProps<P>
): ReactNode | ReactNode[] | null;
```

### `ComponentFinderProps`

```ts
interface ComponentFinderProps<P = unknown> {
  children: ReactNode;
  attribute?: string;
  value?: string;
  props?: Partial<P>;
  debug?: boolean;
  findAll?: boolean;
  onFound?: (component: ReactElement) => void;
  functionPropMerge?: "combine" | "override";
}
```

### `Slot`

```tsx
<Slot
  name="footer"
  props={{ className: "sticky" }}
  fallback={<DefaultFooter />}
>
  {children}
</Slot>
```

### `SlotUtils`

```ts
SlotUtils.createMarker(name: string, attribute?: string): Component
SlotUtils.validate(children: ReactNode, requiredSlots: string[], attribute?: string): void
```

---

## Caveats

- **Next.js layouts** require a shared context if crossing page boundaries.
- `getCmpByAttr` only works on elements rendered within the same render cycle.
- This is **not a DOM query tool** – it’s entirely based on **React element trees**.

---

## License

MIT License