diff --git a/PLUGINS.md b/PLUGINS.md index 0fd37c7..1eb7cd1 100644 --- a/PLUGINS.md +++ b/PLUGINS.md @@ -102,6 +102,7 @@ React component development — coding standards, testing, and structure | Skill | Description | |-------|-------------| | `pf-component-structure` | Audit PatternFly React component nesting, wrapper hierarchies, and layout structure. | +| `pf-design-comments` | Integrate @patternfly/design-comments into React apps for on-page design feedback, pinned comment threads, GitHub Issues sync, and Jira linking. | | `pf-import-checker` | Audit and fix invalid PatternFly import paths across packages. | | `pf-project-scaffolder` | Scaffolds PatternFly React projects with PF6-safe dependencies, imports, and starter layout. | | `pf-unit-test-generator` | Generate a unit test file for a React component using Testing Library. | diff --git a/plugins/react/README.md b/plugins/react/README.md index 413feed..f3aead5 100644 --- a/plugins/react/README.md +++ b/plugins/react/README.md @@ -13,12 +13,40 @@ React component development — coding standards, testing, and structure. - **PF Project Scaffolder** (`/react:pf-project-scaffolder`) — Scaffolds PatternFly React projects with PF6-safe dependencies, imports, and starter layout. - **PF Unit Test Generator** (`/react:pf-unit-test-generator`) — Generate a unit test file for a React component using Testing Library. +**PF Unit Test Generator** (`/react:pf-unit-test-generator`) — Generates a complete unit test file for a given React component. Works for both consumer applications and component library contributions, following Testing Library best practices. +**PF Component Structure** (`/react:pf-component-structure`) — Audit PatternFly React component nesting, wrapper hierarchies, and layout structure. + +**PF Import Checker** (`/react:pf-import-checker`) — Audit and fix invalid PatternFly import paths across packages. + +**PF Project Scaffolder** (`/react:pf-project-scaffolder`) — Scaffolds PatternFly React projects with PF6-safe dependencies, imports, and starter layout. + +**PF Design Comments** (`/react:pf-design-comments`) — Integrates `@patternfly/design-comments` for on-page design feedback with optional GitHub and Jira sync. ### Agents - **PF Coding Standards** (`pf-coding-standards`) — PatternFly React coding standards — import patterns, component composition, token usage, and style conventions. - **PF Component Structure Audit** (`pf-component-structure-audit`) — PatternFly React structural composition rules — required hierarchies, wrapper components, and props-vs-children patterns. - **PF Unit Test Standards** (`pf-unit-test-standards`) — PatternFly React unit testing standards — RTL patterns, mock boundaries, coverage expectations, and assertion style. +## File Structure +```text +react/ +├── .claude-plugin/ +│ └── plugin.json +├── .cursor-plugin/ +│ └── plugin.json +├── agents/ +│ ├── component-structure-audit.md +│ ├── pf-coding-standards.md +│ └── pf-unit-test-standards.md +├── skills/ +│ ├── pf-component-structure/ +│ ├── pf-import-checker/ +│ ├── pf-project-scaffolder/ +│ ├── pf-design-comments/ +│ ├── pf-prototype-mode/ +│ └── pf-unit-test-generator/ +└── README.md +``` ## Sources - [PatternFly.org](https://www.patternfly.org/) diff --git a/plugins/react/skills/pf-design-comments/SKILL.md b/plugins/react/skills/pf-design-comments/SKILL.md new file mode 100644 index 0000000..2b92372 --- /dev/null +++ b/plugins/react/skills/pf-design-comments/SKILL.md @@ -0,0 +1,138 @@ +--- +name: pf-design-comments +description: Integrate @patternfly/design-comments into React apps for on-page design feedback, pinned comment threads, GitHub Issues sync, and Jira linking. Use when adding design comments, review overlays, or removing the commenting system from a PatternFly React project. +--- + +# PF Design Comments + +Add the [@patternfly/design-comments](https://github.com/patternfly/design-comments) floating comment overlay to the user's React app. The package pins feedback to UI elements, detects React components, and optionally syncs with GitHub Issues and Jira. + +## When to use + +- User asks to add design comments, a comment overlay, or in-app design review +- User wants GitHub Issues or Jira linked to specific pages or components +- User wants to remove or uninstall design comments + +## Prerequisites + +Confirm before installing: + +- React 18+ and Node.js 18+ +- Webpack-based dev setup with `webpack.dev.js` (required for OAuth/Jira/summarize proxy middleware) +- `src/app/` layout similar to [PatternFly React Seed](https://github.com/patternfly/patternfly-react-seed) +- Peer deps present or installable: `@patternfly/react-core`, `@patternfly/react-icons`, `react-router-dom` v7 + +If the project uses Vite, Create React App, or a different folder layout, warn the user that `npx design-comments init` may fail or need manual integration. Offer to scaffold with `pf-project-scaffolder` first when starting from scratch. + +## Install workflow + +### Step 1: Inspect the project + +1. Read `package.json` for React, PatternFly, and router versions. +2. Confirm `src/app/index.tsx`, `src/app/routes.tsx`, and `src/app/AppLayout/AppLayout.tsx` exist (or note gaps). +3. Confirm `webpack.dev.js` exists at the project root or under a config folder the dev script uses. + +### Step 2: Install the package + +Use the scoped npm package name: + +```bash +npm install @patternfly/design-comments +``` + +Use `yarn add @patternfly/design-comments` if the project uses Yarn. + +### Step 3: Run the integration CLI + +```bash +npx design-comments init +``` + +The CLI is interactive. It will: + +- Wrap the app with `CommentProvider` and `GitHubAuthProvider` in `src/app/index.tsx` +- Add a Comments route in `src/app/routes.tsx` +- Add `CommentPanel` and `CommentOverlay` in `src/app/AppLayout/AppLayout.tsx` +- Patch `webpack.dev.js` with proxy middleware for GitHub OAuth, Jira, and optional AI summaries +- Create `src/app/Comments/Comments.tsx` and env templates + +Let the user answer prompts for GitHub OAuth and Jira. Both are optional — the overlay works without them. + +### Step 4: Configure environment files + +After `init`, guide the user through env setup: + +**`.env`** (client-safe values, may be committed) + +- GitHub OAuth client ID +- Jira base URL + +**`.env.server`** (secrets — should stay in `.gitignore`) + +- GitHub OAuth client secret +- Jira API tokens +- Optional AI summary keys: `MAAS_API_KEY`, `MAAS_ENDPOINT_URL`, `MAAS_MODEL` (default `gpt-4o-mini`) + +See `GITHUB_OAUTH_ENV_TEMPLATE.md` in the package for OAuth setup details. + +For production builds, set `SUMMARIZE_API_URL` when building so the client calls a hosted summarization endpoint. Do not put private API keys in client-bundled `.env` values. + +### Step 5: Verify + +1. Run the project's dev command (usually `npm run start:dev`). +2. Confirm the floating comment widget appears. +3. Test hover preview, pin creation, and the Comments sidebar. + +Report what changed: + +- Package added to `package.json` +- Files modified by `init` (index, routes, AppLayout, webpack) +- New Comments page and env files created + +## Uninstall workflow + +**Always run remove before uninstalling.** The package modifies project files. + +```bash +npx design-comments remove +npm uninstall @patternfly/design-comments +``` + +Then restart the dev server. + +If the user already uninstalled without running `remove` and the app is broken: + +```bash +npm install @patternfly/design-comments +npx design-comments remove +npm uninstall @patternfly/design-comments +``` + +The remove script reverses integration in `src/app/index.tsx` and `src/app/AppLayout/AppLayout.tsx`. Webpack middleware changes may need manual cleanup. `.env` and `.env.server` are kept intentionally. + +## Usage reference (for the user) + +After integration: + +1. Hover a component to preview with a dashed border and label +2. Click to pin a comment — React component name, type, tree path, and props are captured +3. Use the widget to toggle visibility, resize the panel, reply in threads, and sync with GitHub/Jira when configured + +Optional AI summaries (Summarize all threads / this page / this thread) need the local webpack proxy or a production `SUMMARIZE_API_URL` backend. + +## Manual integration fallback + +If `init` cannot run, read the package README and `scripts/README.md` from `node_modules/@patternfly/design-comments/` and apply the same changes by hand: + +- Providers in the app entry +- Comments route +- `CommentPanel` + `CommentOverlay` in the main layout +- Webpack dev middleware for integrations + +Import components from `@patternfly/design-comments` (package main: `src/commenting-system/index.ts`). + +## Notes + +- Run `init` only once per project unless the user asks to re-run after a failed partial install (the script is idempotent) +- Use git so the user can review integration diffs before committing +- For issues with the package itself, point to https://github.com/patternfly/design-comments/issues