@redocly/config-rules-builder 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,3 @@
+Copyright 2022 (C) Redocly Inc, all rights reserved.
+
+See license agreement here: https://redocly.com/subscription-agreement/

package/README.md

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# @redocly/config-rules-builder
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Visual, two-panel builder for [Redocly configurable rules](https://redocly.com/docs/cli/rules/configurable-rules)
+(`rule/*` entries in `redocly.yaml`). Build a rule with sentence-style form controls on the left
+and instantly see which nodes of a real OpenAPI document it matches, and which of them fail the
+assertions, on the right.
+
+```
+┌──────────────────────────────┬───────────────────────────────┐
+│ Rule cards (collapsible)     │ OpenAPI document editor       │
+│ subject / where / assertions │ matched nodes highlighted,    │
+│ message / suggest / severity │ failures underlined + tooltip │
+│ import rules · redocly.yaml  ├───────────────────────────────┤
+│ export · add rule            │ Problems (click to jump)      │
+└──────────────────────────────┴───────────────────────────────┘
+```
+
+## Features
+
+- **Real lint engine.** Rules are evaluated by `@redocly/openapi-core` in the browser, so results
+  match `redocly lint` exactly.
+- **Live matching.** Nodes matched by the selected rule are highlighted in the document. When the
+  rule targets a property (`subject.property`), only that property is highlighted. The
+  `N nodes matched` badge is a button: each click scrolls to the next match.
+- **Inline problems.** Failing assertions get a squiggly underline with a hover tooltip, a gutter
+  marker, and an entry in the Problems list that jumps to the location.
+- **Import and export.** Paste an existing `redocly.yaml`, or copy and download the generated one.
+- **Bring your own document.** Upload any OpenAPI file (YAML or JSON, up to 2 MB) or edit the
+  sample in place.
+
+## Install
+
+```bash
+npm install @redocly/config-rules-builder
+```
+
+Peer dependencies: `react` ≥18, `react-dom` ≥18, `styled-components` ≥6.
+
+The package ships **ESM only**. `styled-components` v6 has no `exports` map, so a CJS build would
+resolve its broken CJS entry in Node. Any modern bundler (Vite, webpack 5, esbuild) and Node ESM
+consumers work; `require()` is not supported.
+
+## Usage
+
+```tsx
+import { RulesBuilder } from '@redocly/config-rules-builder';
+
+export function ConfigRulesBuilderPage() {
+  return <RulesBuilder />;
+}
+```
+
+The component is self-contained: it ships with a sample OpenAPI document, a demo rule, and
+copy/download buttons for the generated `redocly.yaml` snippet. Pass `onRuleChange` to receive the
+snippet in the host app; see [Props](#props).
+
+### Server-side rendering
+
+CodeMirror and the lint engine are browser-only. When the host framework renders on the server
+(for example a Realm or Next.js page), mount the component after hydration:
+
+```tsx
+import { useEffect, useState } from 'react';
+import { RulesBuilder } from '@redocly/config-rules-builder';
+
+export default function RulesBuilderPage() {
+  const [isClientSide, setIsClientSide] = useState(false);
+  useEffect(() => setIsClientSide(true), []);
+
+  return isClientSide ? <RulesBuilder /> : <div style={{ minHeight: 640 }} />;
+}
+```
+
+The lint engine imports Node's `path` module. Bundlers that target the browser need it aliased to
+`path-browserify` (Realm's client build already does this).
+
+### Props
+
+All props are optional.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `defaultSpec` | `string` | Redocly Museum API | OpenAPI document shown initially |
+| `defaultSpecFileName` | `string` | `museum-api.yaml` | File name shown above the editor |
+| `initialRule` | `ConfigurableRule` | `Operation.summary` defined + `maxLength: 20` | Rule loaded into the first card |
+| `initialRuleName` | `string` | `operation-summary` | Name of the first rule (`rule/<name>`) |
+| `onRuleChange` | `(yaml: string, rules: NamedRule[]) => void` | | Called with the generated `redocly.yaml` snippet and the normalized rules on every change |
+| `host` | `HostAdapters` | browser APIs | Environment integrations, see [Host adapters](#host-adapters) |
+| `height` | `number` | `640` | Height of the two-panel area in px. Below 1024px the panels stack and auto-size |
+
+### Theming
+
+Styling is fully scoped via `styled-components`: no global styles and no CSS framework, so the
+component can be dropped into pages with their own global CSS. Colors and fonts default to
+`@redocly/theme` CSS variables (`--color-primary-base`, `--font-family-base`, and so on) with
+hard-coded fallbacks, so the component looks right inside Redocly products and standalone alike.
+To restyle it, define those CSS variables on an ancestor element.
+
+### Host adapters
+
+`host` swaps browser defaults for environment-specific integrations, for example inside a VS Code
+webview:
+
+| Adapter | Default | Used by |
+| --- | --- | --- |
+| `copyToClipboard(text)` | `navigator.clipboard.writeText` | Copy button in the `redocly.yaml` preview |
+| `downloadFile(fileName, content)` | Blob download | Download button in the `redocly.yaml` preview |
+| `pickSpecFile()` | `<input type="file">` | Upload button above the OpenAPI editor |
+
+### Other exports
+
+Besides the component, the package exports its building blocks:
+
+- `evaluateRules(specText, rules, fileName?)` runs the lint engine and returns matched nodes and
+  problems.
+- `serializeRules(rules)` and `parseImportedRules(yaml)` convert between `NamedRule[]` and a
+  `redocly.yaml` snippet.
+- `DEFAULT_SPEC` is the bundled Museum API sample.
+- All public types: `RulesBuilderProps`, `ConfigurableRule`, `NamedRule`, `HostAdapters`,
+  `EvaluationResult`, `MatchedNode`, `ProblemInfo`, and the rule-shape types.
+
+## Development
+
+This package lives in the Redocly monorepo. From `packages/config-rules-builder`:
+
+```bash
+pnpm run dev       # demo app at http://localhost:5199
+pnpm run test      # unit tests (Vitest)
+pnpm run build     # library build to dist/ (ESM bundle + .d.ts)
+pnpm run ts:check  # type-check
+```
+
+CI runs `lint`, `ts:check`, `build`, and `vitest:test` through Nx, so
+`pnpm nx run @redocly/config-rules-builder:lint` mirrors what the pipeline does.
+
+## Release
+
+Versioning and npm releases use [Changesets](https://github.com/changesets/changesets). Run
+everything from the monorepo root.
+
+1. Add a changeset with `pnpm run changeset:common` and include `@redocly/config-rules-builder`.
+2. Merge the PR with the changeset into `main`.
+3. Release automation opens a version PR; merging it publishes the package to npm.

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@redocly/config-rules-builder",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Visual builder for Redocly configurable rules (rule/*) with live matching against an OpenAPI document",
+  "keywords": [
+    "redocly",
+    "openapi",
+    "lint",
+    "configurable-rules",
+    "react",
+    "editor"
+  ],
+  "author": "team@redocly.com",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "./dist/config-rules-builder.js",
+  "module": "./dist/config-rules-builder.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/config-rules-builder.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@codemirror/commands": "^6.9.0",
+    "@codemirror/lang-yaml": "^6.1.2",
+    "@codemirror/language": "^6.11.3",
+    "@codemirror/state": "^6.5.2",
+    "@codemirror/view": "^6.25.1",
+    "@redocly/openapi-core": "2.62.1",
+    "js-yaml": "4.3.2",
+    "yaml-ast-parser": "0.0.43"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "styled-components": ">=6"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "4.0.9",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "6.0.1",
+    "path-browserify": "^1.0.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "styled-components": "^6.4.2",
+    "typescript": "6.0.3",
+    "vite": "8.3.3",
+    "vite-plugin-dts": "4.5.4",
+    "vitest": "4.1.11"
+  },
+  "scripts": {
+    "clean": "rm -rf dist dist-demo",
+    "build": "pnpm run clean && vite build",
+    "dev": "vite --config vite.demo.config.ts",
+    "build:demo": "vite build --config vite.demo.config.ts",
+    "preview": "vite preview --config vite.demo.config.ts",
+    "test": "vitest run",
+    "ts:check": "tsc --noEmit"
+  }
 }