npm package: @fluid-app/fluid-widget-tools
Description: 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.
Latest version: 0.0.22

# 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

```bash
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

```typescript
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

```typescript
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.

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

### transformWidgetCode

Applies widget transformations to a string of code.

```typescript
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).

```typescript
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