@blockle/blocks-react-slot 1.1.3 → 1.2.0

package/README.md

@@ -1,44 +1,190 @@
 # @blockle/blocks-react-slot
 
-A simple slot component for React.
-
-> Note: The Slot component must be used as a direct child of the Template component.
+A React utility for creating flexible, composable components using the asChild pattern. This package enables components to merge their props with child elements, allowing for powerful composition patterns.
 
 ## Installation
 
 ```bash
-npm install @blockle/blocks-slot
+npm install @blockle/blocks-react-slot
 ```
 
+## Features
+
+- **asChild Pattern**: Merge component props with child elements
+- **Slot Composition**: Use slots as placeholders for dynamic content
+- **Type-Safe**: Full TypeScript support with proper type inference
+- **Prop Merging**: Automatically merges className, style, and other props
+- **Ref Forwarding**: Supports React refs
+
 ## Usage
 
+### Basic Example
+
 ```tsx
-import { createSlottable } from '@blockle/blocks-slot';
+import { createSlottable } from '@blockle/blocks-react-slot';
 
-const [Template, Slot] = createSlottable('button'); // Provide default html tag
+// Create Template and Slot components with a default element
+const [Template, Slot] = createSlottable('div');
 
-export const Button = ({asChild}) => {
+const MyComponent = ({ children, asChild, ...props }) => {
   return (
-    // Template setup
-    <Template className="btn" onClick={() => console.log('clicked')}>
-      [ICON]
-      <Slot>{asChild}</Slot>
+    <Template asChild={asChild} {...props}>
+      <Slot>{children}</Slot>
     </Template>
   );
-};
+}
+
+// Renders as: <div class="container">Content</div>
+<MyComponent className="container">Content</MyComponent>
+
+// Renders as: <a href="#" class="container">Link</a>
+<MyComponent className="container" asChild>
+  <a href="#">Link</a>
+</MyComponent>
 ```
 
+### Creating a Button Component
+
 ```tsx
-import { Button } from './Button';
+import { createSlottable } from '@blockle/blocks-react-slot';
+
+const [Template, Slot] = createSlottable('button');
+
+const Button = ({ children, asChild, variant = 'primary', ...props }) => {
+  const className = `btn btn-${variant}`;
 
-export const App = () => {
   return (
-    <>
-      <Button>Button</Button> {/* -> <button class="btn">[ICON] Tag button</button> */}
-      <Button asChild>
-        <a href="/">Anchor</a>
-      </Button> {/* -> <a class="btn">[ICON] Tag a</a> */}
-    </>
+    <Template asChild={asChild} className={className} {...props}>
+      <Slot>{children}</Slot>
+    </Template>
   );
-};
+}
+
+// Renders as a button element
+<Button onClick={handleClick}>Click me</Button>
+
+// Renders as a link that looks like a button
+<Button asChild>
+  <a href="/home">Go Home</a>
+</Button>
+```
+
+### Advanced Composition with Multiple Children
+
+```tsx
+const [Template, Slot] = createSlottable('div');
+
+const Card = ({ children, asChild, ...props }) => {
+  return (
+    <Template asChild={asChild} className="card" {...props}>
+      <span className="card-decoration">★</span>
+      <Slot>{children}</Slot>
+      <span className="card-decoration">★</span>
+    </Template>
+  );
+}
+
+// The Slot is replaced with the child, decorations are preserved
+<Card asChild>
+  <article>
+    <h2>Title</h2>
+    <p>Content</p>
+  </article>
+</Card>
+// Renders: <article class="card"><span>★</span><h2>Title</h2><p>Content</p><span>★</span></article>
+```
+
+### Using noSlot for Simple Prop Merging
+
+```tsx
+const [Template] = createSlottable('div');
+
+const Container = ({ children, asChild, ...props }) => {
+  return (
+    <Template asChild={asChild} noSlot className="container" {...props}>
+      {children}
+    </Template>
+  );
+}
+
+// Direct prop merging without Slot component
+<Container asChild className="wrapper">
+  <section className="content">Hello</section>
+</Container>
+// Renders: <section class="container wrapper content">Hello</section>
+```
+
+## API
+
+### `createSlottable(defaultElement)`
+
+Creates a Template component and Slot component pair.
+
+**Parameters:**
+
+- `defaultElement`: A valid HTML element tag name (e.g., `'div'`, `'button'`, `'span'`)
+
+**Returns:**
+
+- `[Template, Slot]`: A tuple containing the Template component and Slot component
+
+### Template Component Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `asChild` | `boolean` | When true, merges props with child element instead of rendering default element |
+| `noSlot` | `boolean` | When true with `asChild`, directly merges props without requiring a Slot component |
+| `children` | `React.ReactNode` | Content to render |
+| `ref` | `React.Ref<Element>` | React ref |
+| ...props | varies | Any props valid for the default element type |
+
+### Slot Component
+
+A marker component that indicates where child content should be inserted when using `asChild`.
+
+```tsx
+<Slot>{children}</Slot>
 ```
+
+## Behavior
+
+### Without asChild
+
+Renders as the default element with provided props:
+
+```tsx
+<Template className="foo">Content</Template>
+// Renders: <div class="foo">Content</div>
+```
+
+### With asChild and Slot
+
+Merges Template props with the child element inside Slot:
+
+```tsx
+<Template asChild className="parent">
+  <Slot>
+    <a href="#" className="child">Link</a>
+  </Slot>
+</Template>
+// Renders: <a href="#" class="parent child">Link</a>
+```
+
+### With asChild and noSlot
+
+Directly merges props with the single child element:
+
+```tsx
+<Template asChild noSlot className="parent">
+  <a href="#" className="child">Link</a>
+</Template>
+// Renders: <a href="#" class="parent child">Link</a>
+```
+
+## Use Cases
+
+- **Polymorphic Components**: Create components that can render as different elements
+- **Design Systems**: Build flexible UI components that work with various HTML elements
+- **Accessibility**: Allow semantic HTML while maintaining component styling and behavior
+- **Link Components**: Create button-styled links without nesting interactive elements
+- **Headless UI**: Separate component logic from rendering

package/dist/Slot/Slot.d.ts

@@ -1,6 +1,10 @@
 type SlotProps = {
-    children: React.ReactNode;
+    children?: React.ReactNode;
 };
+/**
+ * Indicates a placeholder for slottable content.
+ * The `children` prop is optional; when omitted, `Slot` renders nothing (`null`).
+ */
 export declare const Slot: React.FC<SlotProps>;
 export {};
 //# sourceMappingURL=Slot.d.ts.map

package/dist/Slot/Slot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Slot.d.ts","sourceRoot":"","sources":["../../src/Slot/Slot.tsx"],"names":[],"mappings":"AACA,KAAK,SAAS,GAAG;IACf,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,CAAC;AAEF,eAAO,MAAM,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,SAAS,CAEpC,CAAC"}
+{"version":3,"file":"Slot.d.ts","sourceRoot":"","sources":["../../src/Slot/Slot.tsx"],"names":[],"mappings":"AAAA,KAAK,SAAS,GAAG;IACf,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,SAAS,CAEpC,CAAC"}

package/dist/createSlottable.d.ts

@@ -5,6 +5,7 @@ type TemplateProps = {
     asChild?: boolean;
     children?: React.ReactNode;
     ref?: React.Ref<Element>;
+    noSlot?: boolean;
 };
 /**
  * Create a Template component that can render as a child of another component with asChild prop.

package/dist/createSlottable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createSlottable.d.ts","sourceRoot":"","sources":["../src/createSlottable.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAc,MAAM,sBAAsB,CAAC;AACzE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC,KAAK,aAAa,GAAG;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,qBAAqB,EACnE,cAAc,EAAE,CAAC,GAChB;IACD,QAAQ,EAAE,KAAK,CAAC,EAAE,CAChB,aAAa,GAAG,gBAAgB,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAC3D;IACD,IAAI,EAAE,OAAO,IAAI;CAClB,CAmFA"}
+{"version":3,"file":"createSlottable.d.ts","sourceRoot":"","sources":["../src/createSlottable.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAc,MAAM,sBAAsB,CAAC;AACzE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC,KAAK,aAAa,GAAG;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,qBAAqB,EACnE,cAAc,EAAE,CAAC,GAChB;IACD,QAAQ,EAAE,KAAK,CAAC,EAAE,CAChB,aAAa,GAAG,gBAAgB,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAC3D;IACD,IAAI,EAAE,OAAO,IAAI;CAClB,CA2GA"}

package/dist/createSlottable.js

@@ -7,14 +7,26 @@ function createSlottable(defaultElement) {
   const Template = ({
     asChild,
     children,
-    ref,
+    noSlot,
     ...rootProps
   }) => {
     if (!asChild) {
-      const tagProps = { ref, ...rootProps };
-      return /* @__PURE__ */ jsx(Tag, { ...tagProps, children });
+      return /* @__PURE__ */ jsx(Tag, { ...rootProps, children });
     }
     const childrenArray = Children.toArray(children);
+    if (noSlot) {
+      if (childrenArray.length !== 1) {
+        return null;
+      }
+      const child = childrenArray[0];
+      if (!isValidElement(child)) {
+        return null;
+      }
+      return cloneElement(
+        child,
+        mergeProps(rootProps, child.props)
+      );
+    }
     const slotIndex = childrenArray.findIndex((child) => {
       if (!isValidElement(child)) {
         return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockle/blocks-react-slot",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Slot",
   "type": "module",
   "exports": {
@@ -32,7 +32,7 @@
   "homepage": "https://github.com/Blockle/blocks#readme",
   "peerDependencies": {
     "@blockle/blocks-core": ">=1.2.x",
-    "react": "^19.2.3"
+    "react": ">=19.1.0"
   },
   "publishConfig": {
     "access": "public",