@inspirer-dev/hero-widget-selector/README.md

A custom field plugin for Strapi v5 that provides a widget selector with size filtering capabilities. Perfect for selecting hero widgets from a filtered collection based on size (S, M, L, XL).

# Hero Widget Selector Plugin

A Strapi v5 plugin that provides a custom field for selecting widgets from a filtered collection.

## Features

- Custom field type: `widget-selector`
- Filters widgets by size (S, M, L, XL)
- Default filter set to "S" size
- Admin API endpoint for fetching filtered widgets
- Configurable size filter in field options
- **Smart Layout Detection**: Automatically detects fallback vs default layouts
- **Fallback Layout Support**: Shows only widget selector for fallback layouts
- **Conditional Layout Support**: Shows widget, condition, and layout selectors for default layouts

## Installation

### Option 1: NPM Package (Recommended for Production)

> **Note**: This is a private package. You need proper authentication to install it.

#### NPM Authentication Setup

1. **Login to NPM** (if you have access to @inspirer-dev organization):

   ```bash
   npm login --scope=@inspirer-dev
   ```

2. **Or create/update .npmrc file** in your project root:

   ```bash
   # .npmrc
   @inspirer-dev:registry=https://registry.npmjs.org/
   //registry.npmjs.org/:_authToken=${NPM_TOKEN}
   ```

3. **For CI/CD environments**, set the NPM_TOKEN environment variable:
   ```bash
   export NPM_TOKEN=your_npm_auth_token
   ```

#### Install the Package

```bash
# Install from npm
npm install @inspirer-dev/hero-widget-selector

# Or with yarn
yarn add @inspirer-dev/hero-widget-selector
```

### Option 2: Local Development

For local development, you can use the plugin directly from the source:

1. Clone the plugin into your Strapi project's `src/plugins/` directory
2. Install dependencies:
   ```bash
   cd src/plugins/hero-widget-selector
   yarn install
   ```
3. Build the plugin:
   ```bash
   yarn build
   ```

## Usage

1. Install the plugin using one of the methods above
2. In your content type builder, add a new field
3. Select "Custom" field type
4. Choose "Widget Selector" from the list
5. Configure the widget size filter in the field options (defaults to "S")
6. The field will display a dropdown with widgets filtered by the selected size

### Layout Type Detection

The plugin automatically detects the layout type based on the field name:

#### Fallback Layouts

- **Field names containing**: `fallbackLayout` or `fallbackLayouts`
- **UI shown**: Only the widget selector
- **Purpose**: Simple widget selection without conditions
- **Data source**: `hero-section.fallbackLayout` field

#### Default Layouts

- **Field names containing**: `defaultLayouts` (or any other name)
- **UI shown**: Widget selector + Condition selector + Conditional layout selector
- **Purpose**: Advanced widget selection with conditional layout support
- **Data source**: `hero-section.defaultLayouts` field

### Example Schema Usage

```json
{
  "attributes": {
    "defaultLayouts": {
      "type": "dynamiczone",
      "components": ["hero-layouts.xl-l-l", "hero-layouts.xl-s-s-s-s"]
    },
    "fallbackLayout": {
      "type": "dynamiczone",
      "components": ["hero-layouts.xl-l-l", "hero-layouts.xl-s-s-s-s"]
    }
  }
}
```

## API Endpoints

- `GET /api/hero-widget-selector/widgets/admin?size=S` - Fetch widgets filtered by size
- `GET /api/hero-widget-selector/hero-layouts/admin` - Fetch default hero layouts
- `GET /api/hero-widget-selector/hero-layouts/admin?fallbackOnly=true` - Fetch fallback hero layouts only
- `GET /api/hero-widget-selector/hero-layouts/admin?search=term` - Search layouts by name
- `GET /api/hero-widget-selector/hero-layouts/admin?omitLayoutId=123` - Exclude specific layout by ID

## Field Configuration

The custom field accepts the following options:

- `size`: Filter widgets by size (S, M, L, XL) - defaults to "S"

## Development

### Local Development Workflow

1. **For Local Development**: Use the plugin directly in `src/plugins/hero-widget-selector`
2. **For Production**: Use the npm package `@inspirer-dev/hero-widget-selector`

### Building the Plugin

```bash
# Build the plugin
npm run build

# Watch for changes during development
npm run watch

# Verify the plugin structure
npm run verify
```

### Publishing Updates

```bash
# Increment version
npm version patch  # or minor/major

# Build and publish
npm run build
npm publish
```

### Linking for Development

If you want to test the npm package locally:

```bash
# In the plugin directory
npm link

# In your Strapi project
npm link @inspirer-dev/hero-widget-selector
```

### Docker Development

The plugin works seamlessly with Docker:

- **Local Development**: Plugin builds from source in `src/plugins/`
- **Production**: Plugin is installed as npm dependency, no build step needed

## Configuration

Add the plugin to your Strapi config if needed:

```javascript
// config/plugins.js
module.exports = {
  'hero-widget-selector': {
    enabled: true,
  },
};
```