sap-sac-custom-widget

# SAP Analytics Cloud Custom Widget Development

## Related Skills

- **sap-sac-scripting**: Use when custom widgets interact with SAC scripting, widgets, or story/application APIs
- **sap-sac-planning**: Use when widgets participate in planning workflows or planning table interactions
- **sapui5**: Use for Web Component/UI5 frontend implementation patterns and browser-side quality
- **sap-dependency-security**: Use when adding third-party charting or build dependencies to widget projects

## Table of Contents
- [Overview](#overview)
- [AI-Assisted Generation](#ai-assisted-generation)
- [Browser Design Runtime](#browser-design-runtime)
- [CSS and Styling Compliance](#css-and-styling-compliance)
- [Plugin Components](#plugin-components)
- [Quick Start](#quick-start)
- [Community Sample Widgets](#community-sample-widgets)
- [Key Concepts](#key-concepts)
- [Common Errors & Solutions](#common-errors--solutions)
- [Bundled Resources](#bundled-resources)

## Overview

This skill enables development of custom widgets for SAP Analytics Cloud (SAC). Custom widgets are Web Components that extend SAC stories and applications with custom visualizations, interactive elements, and specialized functionality.

## When to Use This Skill

**Use this skill when**:
- Building custom visualizations not available in standard SAC
- Generating prompt-driven widget ideas, branded widget packages, or composite-ready widget designs
- Integrating third-party charting libraries (ECharts, D3.js, Chart.js)
- Creating interactive input components for SAC applications
- Implementing specialized data displays or KPI widgets
- Extending Analytics Designer applications with custom functionality
- Troubleshooting custom widget loading or data binding issues

**Requirements**:
- SAC tenant with Optimized Story Experience or Analytics Designer
- JavaScript/Web Components knowledge
- External hosting (GitHub Pages, AWS S3, Azure) OR SAC-hosted resources (QRC Q2 2023+)

---

## AI-Assisted Generation

For prompt-driven widget creation, first suggest 2-3 data-aware widget options, then generate the selected complete package. Keep AI-generated code SAC-compatible, preserve data-binding order, and validate/repair before import. See **`references/ai-assisted-composite-generation.md`** for output contracts, RAG context patterns, brand styling, and composite caveats.

---

## Browser Design Runtime

Generated widget packages should include **`templates/design-runtime/`** as a no-build, file-first browser preview scaffold. Use it to mock custom-widget essentials outside SAP, adjust properties/design tokens/sample data/viewports, compare multiple widgets, and export an agent iteration payload. See **`references/browser-design-runtime.md`** for runtime boundaries and configuration/export contracts.

---

## CSS and Styling Compliance

Style custom widgets inside their Web Component/Shadow DOM boundary. Do not rely on SAC optimized story theme CSS, SAP shell selectors, or global story CSS to style widget internals. For generated packages, confirm the hosting mode before splitting CSS/HTML into separate files, because SAC ZIP upload packages support component JavaScript and PNG/JPG icons only. See **`references/css-and-styling-compliance.md`** for SAP Help-backed allowed/restricted styling rules.

---

## Plugin Components

This plugin provides specialized agents, commands, and validation hooks for comprehensive widget development support.

### Agents

| Agent | Color | Purpose | Trigger Examples |
|-------|-------|---------|------------------|
| **widget-architect** | Blue | Design widget structure, metadata, and integration patterns | "design custom widget", "plan widget architecture" |
| **widget-debugger** | Yellow | Troubleshoot loading, data binding, CORS, and runtime issues | "widget won't load", "CORS error", "data not binding" |
| **widget-api-assistant** | Green | Write JavaScript widget code, lifecycle functions, API integrations | "write widget code", "implement lifecycle functions" |

### Commands

| Command | Usage | Description |
|---------|-------|-------------|
| `/widget-validate` | `/widget-validate [file]` | Validate widget.json schema and widget.js structure |
| `/widget-generate` | `/widget-generate` | Interactively generate widget scaffold with JSON, JS, and browser design runtime |
| `/widget-lint` | `/widget-lint [file]` | Performance, security, and best practices analysis |

### Validation Hooks

Automatic quality checks triggered on Write/Edit operations:
- **widget.json**: Required fields, tag naming, property types, data binding config
- **widget.js**: Lifecycle functions, Shadow DOM, propertiesChanged dispatch
- **Performance**: Resize debouncing, chart disposal, XSS prevention
- **Context Reminders**: Template suggestions, command recommendations

### Templates

Ready-to-use scaffolds in `templates/` directory:
- `basic-widget.js` - Minimal Web Component with all lifecycle functions
- `data-bound-chart.js` - ECharts widget with data binding
- `styling-panel.js` - Runtime customization panel
- `design-runtime/` - Browser preview and design iteration runtime
- `widget.json-minimal` - Bare-minimum metadata
- `widget.json-complete` - Full-featured metadata with all options

---

## Quick Start

### Minimal Custom Widget Structure

A custom widget requires two files:

**1. widget.json** (Metadata)
```json
{
  "id": "com.company.mywidget",
  "version": "1.0.0",
  "name": "My Custom Widget",
  "description": "A simple custom widget",
  "vendor": "Company Name",
  "license": "MIT",
  "icon": "",
  "webcomponents": [
    {
      "kind": "main",
      "tag": "my-custom-widget",
      "url": "https://your-host.com/widget.js",
      "integrity": "",
      "ignoreIntegrity": true
    }
  ],
  "properties": {
    "title": {
      "type": "string",
      "default": "My Widget"
    }
  },
  "methods": {},
  "events": {}
}
```

**2. widget.js** (Web Component)
```javascript
(function() {
  const template = document.createEl