@adobe-commerce/elsie 1.2.0 → 1.2.1-alpha56

package/config/vite.mjs

@@ -29,6 +29,15 @@ const elsieConfig = await import(
   path.resolve(process.cwd(), './.elsie.js')
 ).then((m) => m.default);
 
+const packageJSON = await import(
+  path.resolve(process.cwd(), './package.json'),
+  {
+    assert: {
+      type: 'json',
+    },
+  }
+).then((m) => m.default);
+
 // Paths
 const paths = {
   api: elsieConfig.api?.root
@@ -116,7 +125,6 @@ export default {
         entryFileNames: '[name].js',
         assetFileNames: '[name].[ext]',
         chunkFileNames: 'chunks/[name].js',
-
         manualChunks: (id) => {
           if (id.includes(paths.fragments)) {
             // Fragments file does not accept chunking
@@ -176,7 +184,7 @@ export default {
     modulePreload: false,
     commonjsOptions: { transformMixedEsModules: true },
     minify: !!isProd,
-    sourcemap: !isProd,
+    sourcemap: true,
   },
 
   optimizeDeps: {},
@@ -274,12 +282,12 @@ export default {
 
         // Normalize elsie imports to point to the correct paths
         content = content.replace(
-          /'(.*@adobe\/elsie\/src\/)/g,
+          /'(.*@adobe-commerce\/elsie\/src\/)/g,
           "'@dropins/tools/types/elsie/src/"
         );
 
         content = content.replace(
-          /'(@adobe\/elsie\/icons)'/g,
+          /'(@adobe-commerce\/elsie\/icons)'/g,
           "'@dropins/tools/types/elsie/src/icons'"
         );
 
@@ -287,6 +295,39 @@ export default {
       },
     }),
 
+    {
+      name: 'rewrite-sourcemap-sources',
+      generateBundle(options, bundle) {
+        for (const fileName in bundle) {
+          const chunk = bundle[fileName];
+          
+          // Process both .map files and JS/TS files with sourcemaps
+          if ((chunk.type === 'asset' && fileName.endsWith('.map')) || 
+              (chunk.type === 'chunk' && chunk.map)) {
+            try {
+              // Get the sourcemap object - either from the asset source or the chunk's map
+              const map = chunk.type === 'asset' ? JSON.parse(chunk.source) : chunk.map;
+              
+              if (map.sources) {
+                map.sources = map.sources.map((input) => {
+                  return input.replace(/(?:\.\.?\/)+src\//, `/${packageJSON.name}/src/`);
+                });
+                
+                // Update the sourcemap in the appropriate place
+                if (chunk.type === 'asset') {
+                  chunk.source = JSON.stringify(map);
+                } else {
+                  chunk.map = map;
+                }
+              }
+            } catch (e) {
+              console.error('Error transforming sourcemap:', e);
+            }
+          }
+        }
+      }
+    },
+
     process.env.ANALYZE
       ? visualizer({
           title: `${elsieConfig.name} Dropin Bundle Analysis`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe-commerce/elsie",
-  "version": "1.2.0",
+  "version": "1.2.1-alpha56",
   "license": "SEE LICENSE IN LICENSE.md",
   "description": "Domain Package SDK",
   "engines": {

package/src/components/CartItem/CartItem.tsx

@@ -432,9 +432,7 @@ export const CartItem: FunctionComponent<CartItemProps> = ({
 
         {/* Footer */}
         {footer && (
-          <div className={classes(['dropin-cart-item__footer'])}>
-            <VComponent node={footer} />
-          </div>
+            <VComponent node={footer} className={classes(['dropin-cart-item__footer'])} />
         )}
       </div>
 

package/src/components/ImageSwatch/ImageSwatch.css

@@ -33,6 +33,12 @@
   overflow: hidden;
 }
 
+.dropin-image-swatch__span span {
+  display: inline-block;
+  width: 100%;
+  height: 100%;
+}
+
 .dropin-image-swatch__span img,
 .dropin-image-swatch__content {
   width: inherit;

package/src/components/ProductItemCard/ProductItemCard.css

@@ -0,0 +1,87 @@
+/********************************************************************
+ *  Copyright 2025 Adobe
+ *  All Rights Reserved.
+ *
+ * NOTICE:  Adobe permits you to use, modify, and distribute this 
+ * file in accordance with the terms of the Adobe license agreement 
+ * accompanying it. 
+ *******************************************************************/
+
+/* https://cssguidelin.es/#bem-like-naming */
+
+.dropin-product-item-card {
+  display: grid;
+  position: relative;
+  grid-auto-flow: row;
+  background: var(--color-neutral-50);
+  border: 1px solid var(--color-neutral-400);
+  color: var(--color-neutral-800);
+  font: var(--type-body-1-default-font);
+  letter-spacing: var(--type-body-1-default-letter-spacing);
+  margin: var(--spacing-small);
+  width: 300px;
+}
+
+.dropin-product-item-card__image-container {
+  overflow: hidden;
+  width: 100%;
+  height: auto;
+}
+
+.dropin-product-item-card__image img {
+  width: 100%;
+  max-height: 375px;
+}
+
+.dropin-product-item-card__content {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  padding: var(--spacing-small);
+  gap: var(--spacing-xxsmall);
+  align-items: center;
+  color: var(--color-neutral-800);
+}
+
+.dropin-product-item-card__title,
+.dropin-product-item-card__sku,
+.dropin-product-item-card__price,
+.dropin-product-item-card__swatches,
+.dropin-product-item-card__action {
+  grid-column: 1/3;
+}
+
+.dropin-product-item-card__title {
+  font: var(--type-body-1-strong-font);
+  letter-spacing: var(--type-body-1-strong-letter-spacing);
+}
+
+.dropin-product-item-card__sku {
+  font: var(--type-body-1-default-font);
+  letter-spacing: var(--type-body-1-default-letter-spacing);
+}
+
+.dropin-product-item-card__price {
+  font: var(--type-body-1-default-font);
+  letter-spacing: var(--type-body-1-default-letter-spacing);
+}
+
+.dropin-product-item-card__swatches {
+  margin-top: var(--spacing-xsmall);
+}
+
+.dropin-product-item-card__action {
+  margin-top: var(--spacing-xsmall);
+  width: 100%;
+}
+
+/* Medium (portrait tablets and large phones, 768px and up) */
+/* @media only screen and (min-width: 768px) { } */
+
+/* Large (landscape tablets, 1024px and up) */
+/* @media only screen and (min-width: 1024px) { } */
+
+/* XLarge (laptops/desktops, 1366px and up) */
+/* @media only screen and (min-width: 1366px) { } */
+
+/* XXlarge (large laptops and desktops, 1920px and up) */
+/* @media only screen and (min-width: 1920px) { } */

package/src/components/ProductItemCard/ProductItemCard.stories.tsx

@@ -0,0 +1,371 @@
+/********************************************************************
+ * ADOBE CONFIDENTIAL
+ * __________________
+ *
+ *  Copyright 2025 Adobe
+ *  All Rights Reserved.
+ *
+ * NOTICE:  All information contained herein is, and remains
+ * the property of Adobe and its suppliers, if any. The intellectual
+ * and technical concepts contained herein are proprietary to Adobe
+ * and its suppliers and are protected by all applicable intellectual
+ * property laws, including trade secret and copyright laws.
+ * Dissemination of this information or reproduction of this material
+ * is strictly forbidden unless prior written permission is obtained
+ * from Adobe.
+ *******************************************************************/
+
+// https://storybook.js.org/docs/7.0/preact/writing-stories/introduction
+import type { Meta, StoryObj } from '@storybook/preact';
+import {
+  Button,
+  Icon,
+  Image,
+  Price,
+  ProductItemCard as component,
+  ProductItemCardProps,
+  ColorSwatch,
+} from '@adobe-commerce/elsie/components';
+import { Cart } from '@adobe-commerce/elsie/icons';
+/**
+ * Use ProductItemCard to display product recommendations with image, title, price, SKU, and action button.
+ */
+const meta: Meta<ProductItemCardProps> = {
+  title: 'Components/ProductItemCard',
+  component,
+
+  argTypes: {
+    image: {
+      control: {
+        type: 'select',
+        labels: {
+          DefaultImage: 'Default Image',
+          Empty: 'No Image',
+        },
+      },
+      description: 'Product image node.',
+      options: ['DefaultImage', 'Empty'],
+      mapping: {
+        DefaultImage: (
+          <Image
+            src="https://picsum.photos/300/375"
+            width="300"
+            height="375"
+            alt="Product Image"
+            loading="lazy"
+          />
+        ),
+        Empty: null,
+      },
+      table: { defaultValue: { summary: 'null' } },
+    },
+    titleNode: {
+      control: {
+        type: 'select',
+        labels: {
+          DefaultTitle: 'Default Title',
+          LongTitle: 'Long Title',
+          Empty: 'No Title',
+        },
+      },
+      description: 'Product title node.',
+      options: ['DefaultTitle', 'LongTitle', 'Empty'],
+      mapping: {
+        DefaultTitle: <div>Hollister Backyard Sweatshirt</div>,
+        LongTitle: (
+          <div>
+            Hollister Backyard Sweatshirt with Extra Long Product Name That
+            Might Wrap
+          </div>
+        ),
+        Empty: null,
+      },
+    },
+    price: {
+      control: {
+        type: 'select',
+        labels: {
+          DefaultPrice: 'Default Price',
+          SalePrice: 'Sale Price',
+          Empty: 'No Price',
+        },
+      },
+      description: 'Product price node.',
+      options: ['DefaultPrice', 'SalePrice', 'Empty'],
+      mapping: {
+        DefaultPrice: (
+          <>
+            <Price amount={49.99} />
+          </>
+        ),
+        SalePrice: (
+          <>
+            <Price amount={69.99} variant="strikethrough" />
+            <Price amount={49.99} sale />
+          </>
+        ),
+        Empty: null,
+      },
+    },
+    sku: {
+      control: {
+        type: 'select',
+        labels: {
+          DefaultSku: 'Default SKU',
+          Empty: 'No SKU',
+        },
+      },
+      description: 'Product SKU node.',
+      options: ['DefaultSku', 'Empty'],
+      mapping: {
+        DefaultSku: <div>SKU: 123456789</div>,
+        Empty: null,
+      },
+    },
+    swatches: {
+      control: {
+        type: 'select',
+        labels: {
+          DefaultSwatches: 'Default Swatches',
+          SelectedSwatches: 'Selected Swatches',
+          OutOfStockSwatches: 'Out of Stock Swatches',
+          Empty: 'No Swatches',
+        },
+      },
+      description: 'Product swatches node.',
+      options: [
+        'DefaultSwatches',
+        'SelectedSwatches',
+        'OutOfStockSwatches',
+        'Empty',
+      ],
+      mapping: {
+        DefaultSwatches: (
+          <div style={{ display: 'flex', gap: '8px' }}>
+            <ColorSwatch
+              color="red"
+              label="Red"
+              groupAriaLabel="Color options"
+              value="red"
+            />
+            <ColorSwatch
+              color="blue"
+              label="Blue"
+              groupAriaLabel="Color options"
+              value="blue"
+            />
+            <ColorSwatch
+              color="green"
+              label="Green"
+              groupAriaLabel="Color options"
+              value="green"
+            />
+          </div>
+        ),
+        SelectedSwatches: (
+          <div style={{ display: 'flex', gap: '8px' }}>
+            <ColorSwatch
+              color="red"
+              label="Red"
+              groupAriaLabel="Color options"
+              value="red"
+              selected
+            />
+            <ColorSwatch
+              color="blue"
+              label="Blue"
+              groupAriaLabel="Color options"
+              value="blue"
+            />
+            <ColorSwatch
+              color="green"
+              label="Green"
+              groupAriaLabel="Color options"
+              value="green"
+            />
+          </div>
+        ),
+        OutOfStockSwatches: (
+          <div style={{ display: 'flex', gap: '8px' }}>
+            <ColorSwatch
+              color="red"
+              label="Red"
+              groupAriaLabel="Color options"
+              value="red"
+              outOfStock
+            />
+            <ColorSwatch
+              color="blue"
+              label="Blue"
+              groupAriaLabel="Color options"
+              value="blue"
+            />
+            <ColorSwatch
+              color="green"
+              label="Green"
+              groupAriaLabel="Color options"
+              value="green"
+            />
+          </div>
+        ),
+        Empty: null,
+      },
+      table: { defaultValue: { summary: 'null' } },
+    },
+    actionButton: {
+      control: {
+        type: 'select',
+        labels: {
+          DefaultButton: 'Default Button',
+          CustomButton: 'Custom Button',
+          Empty: 'No Button',
+        },
+      },
+      description: 'Action button node.',
+      options: ['DefaultButton', 'CustomButton', 'Empty'],
+      mapping: {
+        DefaultButton: <Button>Select Options</Button>,
+        CustomButton: (
+          <Button icon={<Icon source={Cart} size="24" />} variant="primary">
+            Add to Cart
+          </Button>
+        ),
+        Empty: null,
+      },
+      table: { defaultValue: { summary: 'null' } },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<ProductItemCardProps>;
+
+/**
+ * Default ProductItemCard with all elements
+ */
+export const Default: Story = {
+  args: {
+    initialized: true,
+    image: 'DefaultImage' as any,
+    titleNode: 'DefaultTitle' as any,
+    price: 'DefaultPrice' as any,
+    sku: 'DefaultSku' as any,
+    swatches: 'DefaultSwatches' as any,
+    actionButton: 'DefaultButton' as any,
+  },
+};
+
+/**
+ * ProductItemCard with long title
+ */
+export const LongTitle: Story = {
+  args: {
+    initialized: true,
+    image: 'DefaultImage' as any,
+    titleNode: 'LongTitle' as any,
+    price: 'DefaultPrice' as any,
+    sku: 'DefaultSku' as any,
+    swatches: 'DefaultSwatches' as any,
+    actionButton: 'DefaultButton' as any,
+  },
+};
+
+/**
+ * ProductItemCard with sale price
+ */
+export const SalePrice: Story = {
+  args: {
+    initialized: true,
+    image: 'DefaultImage' as any,
+    titleNode: 'DefaultTitle' as any,
+    price: 'SalePrice' as any,
+    sku: 'DefaultSku' as any,
+    swatches: 'DefaultSwatches' as any,
+    actionButton: 'DefaultButton' as any,
+  },
+};
+
+/**
+ * ProductItemCard without action button
+ */
+export const NoButton: Story = {
+  args: {
+    initialized: true,
+    image: 'DefaultImage' as any,
+    titleNode: 'DefaultTitle' as any,
+    price: 'DefaultPrice' as any,
+    sku: 'DefaultSku' as any,
+    swatches: 'DefaultSwatches' as any,
+    actionButton: 'Empty' as any,
+  },
+};
+
+/**
+ * ProductItemCard without image
+ */
+export const NoImage: Story = {
+  args: {
+    initialized: true,
+    image: 'Empty' as any,
+    titleNode: 'DefaultTitle' as any,
+    price: 'DefaultPrice' as any,
+    sku: 'DefaultSku' as any,
+    swatches: 'DefaultSwatches' as any,
+    actionButton: 'DefaultButton' as any,
+  },
+};
+
+/**
+ * ProductItemCard with minimal content
+ */
+export const Minimal: Story = {
+  args: {
+    initialized: true,
+    image: 'DefaultImage' as any,
+    titleNode: 'DefaultTitle' as any,
+    price: 'Empty' as any,
+    sku: 'Empty' as any,
+    swatches: 'Empty' as any,
+    actionButton: 'Empty' as any,
+  },
+};
+
+/**
+ * ProductItemCard with selected swatch
+ */
+export const SelectedSwatch: Story = {
+  args: {
+    initialized: true,
+    image: 'DefaultImage' as any,
+    titleNode: 'DefaultTitle' as any,
+    price: 'DefaultPrice' as any,
+    sku: 'DefaultSku' as any,
+    swatches: 'SelectedSwatches' as any,
+    actionButton: 'DefaultButton' as any,
+  },
+};
+
+/**
+ * ProductItemCard with out of stock swatch
+ */
+export const OutOfStockSwatch: Story = {
+  args: {
+    initialized: true,
+    image: 'DefaultImage' as any,
+    titleNode: 'DefaultTitle' as any,
+    price: 'DefaultPrice' as any,
+    sku: 'DefaultSku' as any,
+    swatches: 'OutOfStockSwatches' as any,
+    actionButton: 'DefaultButton' as any,
+  },
+};
+
+/**
+ * ProductItemCard in skeleton loading state
+ */
+export const Skeleton: Story = {
+  args: {
+    initialized: false,
+  },
+};

package/src/components/ProductItemCard/ProductItemCard.tsx

@@ -0,0 +1,94 @@
+/********************************************************************
+ *  Copyright 2025 Adobe
+ *  All Rights Reserved.
+ *
+ * NOTICE:  Adobe permits you to use, modify, and distribute this
+ * file in accordance with the terms of the Adobe license agreement
+ * accompanying it.
+ *******************************************************************/
+
+import { FunctionComponent, VNode } from 'preact';
+import { HTMLAttributes } from 'preact/compat';
+import { VComponent, classes } from '@adobe-commerce/elsie/lib';
+import { ProductItemCardSkeleton } from '@adobe-commerce/elsie/components/ProductItemCard/ProductItemCardSkeleton';
+import '@adobe-commerce/elsie/components/ProductItemCard/ProductItemCard.css';
+
+export interface ProductItemCardProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'loading'> {
+  image?: VNode;
+  titleNode?: VNode;
+  price?: VNode;
+  sku?: VNode;
+  actionButton?: VNode;
+  swatches?: VNode;
+  initialized?: boolean;
+}
+
+export const ProductItemCard: FunctionComponent<ProductItemCardProps> = ({
+  className,
+  image,
+  titleNode,
+  price,
+  sku,
+  actionButton,
+  swatches,
+  initialized = false,
+  ...props
+}) => {
+  if (!initialized) {
+    return <ProductItemCardSkeleton />;
+  }
+  return (
+    <div
+      {...props}
+      className={classes(['dropin-product-item-card', className])}
+    >
+      <div className="dropin-product-item-card__image-container">
+        {image && (
+          <VComponent
+            node={image}
+            className={classes(['dropin-product-item-card__image'])}
+          />
+        )}
+      </div>
+      <div className="dropin-product-item-card__content">
+        {titleNode && (
+          <VComponent
+            node={titleNode}
+            className={classes(['dropin-product-item-card__title'])}
+          />
+        )}
+        {sku && (
+          <VComponent
+            node={sku}
+            className={classes(['dropin-product-item-card__sku'])}
+          />
+        )}
+        {price && (
+          <div className="dropin-product-item-card__price">
+            <VComponent
+              node={price}
+              className={classes(['dropin-product-item-card__price'])}
+            />
+          </div>
+        )}
+        {swatches && (
+          <div className="dropin-product-item-card__swatches">
+            <VComponent
+              node={swatches}
+              className={classes(['dropin-product-item-card__swatches'])}
+            />
+          </div>
+        )}
+        {actionButton && (
+          <div className="dropin-product-item-card__action">
+            <VComponent
+              node={actionButton}
+              className={classes(['dropin-product-item-card__action'])}
+            />
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};

package/src/components/ProductItemCard/ProductItemCardSkeleton.css

@@ -0,0 +1,40 @@
+/********************************************************************
+ *  Copyright 2025 Adobe
+ *  All Rights Reserved.
+ *
+ * NOTICE:  Adobe permits you to use, modify, and distribute this 
+ * file in accordance with the terms of the Adobe license agreement 
+ * accompanying it. 
+ *******************************************************************/
+
+/* https://cssguidelin.es/#bem-like-naming */
+
+.dropin-product-item-card__skeleton {
+  gap: var(--spacing-small);
+}
+
+.dropin-product-item-card__skeleton__image {
+  height: 375px;
+}
+
+.dropin-product-item-card__skeleton__content {
+  grid-column: 1/-1;
+}
+
+/* .dropin-product-item-card__skeleton__image {
+  width: 100%;
+  height: auto;
+}
+*/
+
+/* Medium (portrait tablets and large phones, 768px and up) */
+/* @media only screen and (min-width: 768px) { } */
+
+/* Large (landscape tablets, 1024px and up) */
+/* @media only screen and (min-width: 1024px) { } */
+
+/* XLarge (laptops/desktops, 1366px and up) */
+/* @media only screen and (min-width: 1366px) { } */
+
+/* XXlarge (large laptops and desktops, 1920px and up) */
+/* @media only screen and (min-width: 1920px) { } */

package/src/components/ProductItemCard/ProductItemCardSkeleton.tsx

@@ -0,0 +1,42 @@
+/********************************************************************
+ *  Copyright 2025 Adobe
+ *  All Rights Reserved.
+ *
+ * NOTICE:  Adobe permits you to use, modify, and distribute this
+ * file in accordance with the terms of the Adobe license agreement
+ * accompanying it.
+ *******************************************************************/
+
+import { FunctionComponent } from 'preact';
+import { Skeleton, SkeletonRow } from '@adobe-commerce/elsie/components';
+import '@adobe-commerce/elsie/components/ProductItemCard/ProductItemCardSkeleton.css';
+
+export const ProductItemCardSkeleton: FunctionComponent = () => {
+  return (
+    <div className="dropin-product-item-card dropin-product-item-card-skeleton">
+      <Skeleton className="dropin-product-item-card__skeleton dropin-product-item-card__image-container">
+        <SkeletonRow
+          fullWidth={true}
+          className="dropin-product-item-card__skeleton__image"
+        />
+        <div className="dropin-product-item-card__content dropin-product-item-card__skeleton__content">
+          <SkeletonRow
+            fullWidth={true}
+            size="large"
+            className="dropin-product-item-card__skeleton__item"
+          />
+          <SkeletonRow
+            fullWidth={true}
+            size="xsmall"
+            className="dropin-product-item-card__skeleton__item"
+          />
+          <SkeletonRow
+            fullWidth={true}
+            size="small"
+            className="dropin-product-item-card__skeleton__item"
+          />
+        </div>{' '}
+      </Skeleton>
+    </div>
+  );
+};

package/src/components/ProductItemCard/index.ts

@@ -0,0 +1,11 @@
+/********************************************************************
+ *  Copyright 2025 Adobe
+ *  All Rights Reserved.
+ *
+ * NOTICE:  Adobe permits you to use, modify, and distribute this 
+ * file in accordance with the terms of the Adobe license agreement 
+ * accompanying it. 
+ *******************************************************************/
+  
+export * from '@adobe-commerce/elsie/components/ProductItemCard/ProductItemCard';
+export { ProductItemCard as default } from '@adobe-commerce/elsie/components/ProductItemCard/ProductItemCard';

package/src/components/index.ts

@@ -47,3 +47,4 @@ export * from '@adobe-commerce/elsie/components/Header';
 export * from '@adobe-commerce/elsie/components/Tag';
 export * from '@adobe-commerce/elsie/components/ContentGrid';
 export * from '@adobe-commerce/elsie/components/Pagination';
+export * from '@adobe-commerce/elsie/components/ProductItemCard';

package/src/docs/Utilities/VComponent.mdx

@@ -0,0 +1,92 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+
+<Meta title="Utilities/VComponent" />
+<Unstyled>
+
+# VComponent: A VNode wrapper for dynamic rendering
+
+In modern Preact-based architectures, composability and flexibility are essential for building reusable UI components. `VComponent` is a utility provided by the SDK that enables rendering of virtual nodes (`VNode`) passed as props—empowering consumers to inject arbitrary content while maintaining a clean separation of concerns.
+
+## Why use VComponent?
+
+By default, Preact allows children to be passed as virtual nodes, enabling dynamic rendering:
+
+```tsx
+<MyComponent>
+  <h1>Hello</h1>
+</MyComponent>
+```
+However, flexibility increases when we extend this pattern to named props like `header`, `footer`, or `image`. Instead of hardcoding internal markup, we delegate the responsibility of rendering to the consumer.
+
+## Traditional approach (tightly coupled)
+
+The standard approach to rendering a component is to pass values as props directly to the component.
+
+**Implementation:**
+
+```tsx
+const Card = ({ imageProps }) => {
+  return <img {...imageProps} />;
+};
+```
+
+**Usage:**
+```tsx
+<Card imageProps={{ src: 'logo.png', alt: 'Logo' }} />
+```
+
+This implementation tightly couples the component to a specific HTML element (`<img>`), which limits its flexibility and reuse.
+
+## Composable approach with VComponent
+
+The composable approach with `VComponent` allows consumers to pass arbitrary DOM nodes through props.
+
+**Implementation:**
+
+```tsx
+import { VComponent } from '@adobe-commerce/elsie/lib';
+
+interface Props {
+  image: VNode;
+}
+
+const Card = ({ image }: Props) => {
+  return <VComponent node={image} className="dropin-header-image" />;
+};
+```
+
+**Usage:**
+
+```tsx
+<Card image={<img src="logo.png" alt="Logo" />} />
+// or with a custom slot/component
+<Card image={<Slot name="brand-image" />} />
+```
+
+This decouples the component from a specific element. Instead, it renders whatever VNode is passed in. Consumers now have full control over what gets displayed.
+
+## How it works
+
+`VComponent` is a thin wrapper around a virtual node (`VNode`). It renders the node it receives as-is, while optionally applying extra props like `className`.
+
+This makes it ideal for rendering content passed through slots or injected from a higher-order component.
+
+```tsx
+<VComponent node={header} className="my-header" />
+```
+
+## When to use it
+
+Use `VComponent` when:
+
+- You want to allow injected custom DOM nodes (icons, slots, rich content)
+- You're designing reusable components meant to be extended or implemented by different consumers (Containers, Slots, etc.)
+
+## Benefits
+
+- Promotes reusability and composability
+- Supports custom rendering logic with no assumptions
+- Reduces internal complexity by offloading rendering decisions
+- Ideal for BYO-UI and dynamic layout strategies
+
+</Unstyled>

package/src/docs/Utilities/links.mdx

@@ -0,0 +1,58 @@
+import { Meta, Unstyled } from '@storybook/blocks';
+
+<Meta title="Utilities/Links" />
+<Unstyled>
+
+# Adding Links using the route pattern
+
+Whenever possible, avoid placing `onClick` handlers directly on anchor elements (`<a>`) in drop-in components, such as product or category pages, as this results in accessibility issues and broken browser behavior. Problems include:
+
+- Right-click > Open in New Tab results in blank pages.
+- Middle-click (open in background tab) won't work as expected.
+- Keyboard navigation and screen readers may not trigger the link correctly.
+
+Instead, follow the route pattern to provide composable and accessible navigation.
+
+## How it works
+
+Components accept a `routeX` function as a prop. The function receives a data model (a product, for example) and returns a URL. Internally, it's used like this:
+
+```tsx
+<a href={routeProduct?.(product) ?? '#'}>...</a>
+```
+
+This lets developers customize routing logic per storefront while preserving link semantics.
+
+## Example — Component-Side
+
+In your component (a PLP item, for example):
+
+The `routeProduct` prop must be optional and default to a # or an non-functional element like a `div` if not provided.
+
+```tsx
+type Props = {
+  routeProduct?: (product: ProductModel) => string;
+};
+
+function ProductCard({ product, routeProduct }: Props) {
+  return (
+    <a href={routeProduct?.(product) ?? '#'}>
+      <div>{product.name}</div>
+    </a>
+  );
+}
+```
+
+## Example — Storefront-Side
+
+In the storefront integration (`commerce-cart.js` or `commerce-plp.js`, for example):
+
+```js
+import { rootLink } from '@adobe/commerce-url-utils';
+
+provider.render(ProductList, {
+  routeProduct: (product) => rootLink(`/products/${product.url.urlKey}/${product.topLevelSku}`),
+});
+```
+
+</Unstyled>