fluid-widget-tools

A utility package for working with Fluid web widget implementations in codebases. This package generates regular expressions to find widget instances and update their attributes programmatically.

Features

• Generate regular expressions to find specific widget instances in your code
• Create replacement patterns with specified attributes
• Transform code strings by replacing widget instances with updated configurations
• Type-safe: Uses TypeScript and imports prop types directly from web-widgets

Installation

npm install @fluid-app/fluid-widget-tools
# or with yarn
yarn add @fluid-app/fluid-widget-tools
# or with pnpm
pnpm add @fluid-app/fluid-widget-tools

Usage

Generating Widget RegEx Patterns

import { generateWidgetRegex } from "@fluid-app/fluid-widget-tools";

// Generate a regex pattern for finding and replacing fluid-cart-widget instances
const pattern = generateWidgetRegex("fluid-cart-widget", {
  position: "bottom-right",
  fluidShopDisplayName: "Tangerine.fun",
  hideWidget: true,
});

console.log(pattern.find); // RegExp to find <fluid-cart-widget> instances
console.log(pattern.replace); // String replacement with specified attributes

Transforming Code

import { transformWidgetCode } from "@fluid-app/fluid-widget-tools";

const originalCode = `
<div>
  <fluid-cart-widget position="top-right"></fluid-cart-widget>
</div>
`;

// Transform the code with new widget attributes
const transformedCode = transformWidgetCode(originalCode, "fluid-cart-widget", {
  position: "bottom-right",
  fluidShopDisplayName: "Tangerine.fun",
  hideWidget: true,
});

// Result:
// <div>
//   <fluid-cart-widget position="bottom-right" fluid-shop-display-name="Tangerine.fun" hide-widget></fluid-cart-widget>
// </div>

API Reference

generateWidgetRegex

Generates a regular expression for finding widget instances and a string pattern for replacing them.

function generateWidgetRegex<T extends keyof WebWidgetComponents>(
  widgetName: T,
  attributes: Partial<WebWidgetPropsType<T>>,
): WidgetRegexResult;

transformWidgetCode

Applies widget transformations to a string of code.

function transformWidgetCode<T extends keyof WebWidgetComponents>(
  code: string,
  widgetName: T,
  attributes: Partial<WebWidgetPropsType<T>>,
): string;

validateWidgetAttributes

Validates attribute values against widget prop types (primarily for TypeScript validation).

function validateWidgetAttributes<T extends keyof WebWidgetComponents>(
  widgetName: T,
  attributes: Partial<WebWidgetPropsType<T>>,
): boolean;

Available Widgets

The available widgets depend on the types defined in @fluid-app/web-widgets-types. This typically includes widgets like:

• fluid-cart-widget
• fluid-banner-widget
• fluid-lead-capture-widget

And any other widgets defined in the types package.

License

MIT