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

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/dist/components/AssertionsEditor.d.ts

@@ -0,0 +1,12 @@
+import { SectionTone } from '../styles';
+import { AssertionObject } from '../types';
+import { RuleErrors } from '../validation';
+export interface AssertionsEditorProps {
+    assertions: AssertionObject;
+    onChange: (assertions: AssertionObject) => void;
+    keyword: string;
+    tone: SectionTone;
+    errors: RuleErrors;
+    errorPrefix: string;
+}
+export declare function AssertionsEditor({ assertions, onChange, keyword, tone, errors, errorPrefix, }: AssertionsEditorProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ConfigPreview.d.ts

@@ -0,0 +1,7 @@
+import { HostAdapters } from '../types';
+export interface ConfigPreviewProps {
+    yaml: string;
+    host?: HostAdapters;
+    fileName?: string;
+}
+export declare function ConfigPreview({ yaml, host, fileName }: ConfigPreviewProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ImportPanel.d.ts

@@ -0,0 +1,5 @@
+import { NamedRule } from '../types';
+export interface ImportPanelProps {
+    onImport: (rules: NamedRule[]) => void;
+}
+export declare function ImportPanel({ onImport }: ImportPanelProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Modal.d.ts

@@ -0,0 +1,10 @@
+import { ReactNode } from 'react';
+export interface ModalProps {
+    title: string;
+    subtitle?: string;
+    onClose: () => void;
+    children: ReactNode;
+    footer?: ReactNode;
+    width?: number;
+}
+export declare function Modal({ title, subtitle, onClose, children, footer, width }: ModalProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/OverviewRuler.d.ts

@@ -0,0 +1,13 @@
+export interface RulerMarker {
+    line: number;
+    from: number;
+    to: number;
+    kind: 'match' | 'error' | 'warn';
+    title?: string;
+}
+export interface OverviewRulerProps {
+    markers: RulerMarker[];
+    totalLines: number;
+    onMarkerClick: (marker: RulerMarker) => void;
+}
+export declare function OverviewRuler({ markers, totalLines, onMarkerClick }: OverviewRulerProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ProblemsPanel.d.ts

@@ -0,0 +1,9 @@
+import { ProblemInfo } from '../types';
+export interface ProblemsPanelProps {
+    problems: ProblemInfo[];
+    ruleErrors: string[];
+    specError?: string;
+    isRunning: boolean;
+    onSelect: (problem: ProblemInfo) => void;
+}
+export declare function ProblemsPanel({ problems, ruleErrors, specError, isRunning, onSelect, }: ProblemsPanelProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/RuleCard.d.ts

@@ -0,0 +1,17 @@
+import { RuleEntry } from '../state';
+export interface RuleCardProps {
+    entry: RuleEntry;
+    selected: boolean;
+    matchCount: number;
+    isDuplicateName: boolean;
+    isEvaluating: boolean;
+    onToggle: () => void;
+    onChange: (entry: RuleEntry) => void;
+    onRemove: () => void;
+}
+export declare function RuleCard({ entry, selected, matchCount, isDuplicateName, isEvaluating, onToggle, onChange, onRemove, }: RuleCardProps): import("react/jsx-runtime").JSX.Element;
+export declare const Badge: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components').FastOmit<import('styled-components').FastOmit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "$dim"> & {
+    $dim?: boolean;
+}, never> & Partial<Pick<import('styled-components').FastOmit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "$dim"> & {
+    $dim?: boolean;
+}, never>>> & string;

package/dist/components/RuleList.d.ts

@@ -0,0 +1,16 @@
+import { RuleEntry } from '../state';
+import { ConfigPreviewProps } from './ConfigPreview';
+import { ImportPanelProps } from './ImportPanel';
+export interface RuleListProps {
+    entries: RuleEntry[];
+    selectedId: string | null;
+    matchCountById: Record<string, number>;
+    onToggle: (id: string) => void;
+    onChangeEntry: (entry: RuleEntry) => void;
+    onRemove: (id: string) => void;
+    onAdd: () => void;
+    isEvaluating: boolean;
+    importProps: ImportPanelProps;
+    configPreviewProps: ConfigPreviewProps;
+}
+export declare function RuleList({ entries, selectedId, matchCountById, onToggle, onChangeEntry, onRemove, onAdd, isEvaluating, importProps, configPreviewProps, }: RuleListProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/RulesBuilder.d.ts

@@ -0,0 +1,11 @@
+import { ConfigurableRule, HostAdapters, NamedRule } from '../types';
+export interface RulesBuilderProps {
+    defaultSpec?: string;
+    defaultSpecFileName?: string;
+    initialRule?: ConfigurableRule;
+    initialRuleName?: string;
+    onRuleChange?: (yaml: string, rules: NamedRule[]) => void;
+    host?: HostAdapters;
+    height?: number;
+}
+export declare function RulesBuilder({ defaultSpec, defaultSpecFileName, initialRule, initialRuleName, onRuleChange, host, height, }: RulesBuilderProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/SpecPanel.d.ts

@@ -0,0 +1,48 @@
+import { HostAdapters } from '../types';
+import { RulerMarker } from './OverviewRuler';
+export interface FailRange {
+    from: number;
+    to: number;
+    messages: string[];
+    severity: 'error' | 'warn';
+}
+export interface SpecHighlights {
+    matchKeys: {
+        from: number;
+        to: number;
+    }[];
+    matchBlocks: {
+        from: number;
+        to: number;
+    }[];
+    matchProps: {
+        from: number;
+        to: number;
+    }[];
+    fails: FailRange[];
+}
+export declare const EMPTY_HIGHLIGHTS: SpecHighlights;
+export interface SpecPanelProps {
+    spec: string;
+    fileName: string;
+    highlights: SpecHighlights;
+    rulerMarkers: RulerMarker[];
+    matchTargets: {
+        from: number;
+        to: number;
+    }[];
+    totalLines: number;
+    jump?: {
+        from: number;
+        to: number;
+    };
+    matchCount: number;
+    showMatchStatus: boolean;
+    isEvaluating: boolean;
+    onSpecChange: (content: string, fileName?: string) => void;
+    onResetSpec: () => void;
+    uploadError?: string;
+    onUploadError: (message?: string) => void;
+    host?: HostAdapters;
+}
+export declare function SpecPanel({ spec, fileName, highlights, rulerMarkers, matchTargets, totalLines, jump, matchCount, showMatchStatus, isEvaluating, onSpecChange, onResetSpec, uploadError, onUploadError, host, }: SpecPanelProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/SubjectEditor.d.ts

@@ -0,0 +1,11 @@
+import { SubjectObject } from '../types';
+import { RuleErrors } from '../validation';
+export interface SubjectEditorProps {
+    subject: SubjectObject;
+    onChange: (subject: SubjectObject) => void;
+    lead: string;
+    ariaPrefix: string;
+    errors: RuleErrors;
+    errorPrefix: string;
+}
+export declare function SubjectEditor({ subject, onChange, lead, ariaPrefix, errors, errorPrefix, }: SubjectEditorProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/controls/ChipListInput.d.ts

@@ -0,0 +1,7 @@
+export interface ChipListInputProps {
+    values: string[];
+    onChange: (values: string[]) => void;
+    ariaLabel: string;
+    placeholder?: string;
+}
+export declare function ChipListInput({ values, onChange, ariaLabel, placeholder }: ChipListInputProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/controls/Combobox.d.ts

@@ -0,0 +1,9 @@
+export interface ComboboxProps {
+    value: string;
+    options: string[];
+    onChange: (value: string) => void;
+    ariaLabel: string;
+    placeholder?: string;
+    width?: number;
+}
+export declare function Combobox({ value, options, onChange, ariaLabel, placeholder, width, }: ComboboxProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/controls/Segmented.d.ts

@@ -0,0 +1,12 @@
+export interface SegmentedOption<T extends string> {
+    value: T;
+    label: string;
+    activeColor?: string;
+}
+export interface SegmentedProps<T extends string> {
+    value: T;
+    options: SegmentedOption<T>[];
+    onChange: (value: T) => void;
+    ariaLabel: string;
+}
+export declare function Segmented<T extends string>({ value, options, onChange, ariaLabel, }: SegmentedProps<T>): import("react/jsx-runtime").JSX.Element;

package/dist/components/controls/SeverityPill.d.ts

@@ -0,0 +1,5 @@
+import { Severity } from '../../types';
+export declare function SeverityPill({ value, onChange, }: {
+    value: Severity;
+    onChange: (value: Severity) => void;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/controls/primitives.d.ts

@@ -0,0 +1,31 @@
+import { CSSProperties, ReactNode } from 'react';
+import { SectionTone } from '../../styles';
+export declare const InlineSelect: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components').FastOmit<import('react').DetailedHTMLProps<import('react').SelectHTMLAttributes<HTMLSelectElement>, HTMLSelectElement>, never> & Partial<Pick<import('react').DetailedHTMLProps<import('react').SelectHTMLAttributes<HTMLSelectElement>, HTMLSelectElement>, never>>> & string;
+export declare const InlineInput: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components').FastOmit<import('react').DetailedHTMLProps<import('react').InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, never> & Partial<Pick<import('react').DetailedHTMLProps<import('react').InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, never>>> & string;
+export declare const MonoInput: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components').FastOmit<import('styled-components').FastOmit<import('styled-components').FastOmit<import('react').DetailedHTMLProps<import('react').InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, never> & Partial<Pick<import('react').DetailedHTMLProps<import('react').InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, never>>, "as" | "forwardedAs"> & {
+    as?: import('styled-components').WebTarget | undefined;
+    forwardedAs?: import('styled-components').WebTarget | undefined;
+}, never> & Partial<Pick<import('styled-components').FastOmit<import('styled-components').FastOmit<import('react').DetailedHTMLProps<import('react').InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, never> & Partial<Pick<import('react').DetailedHTMLProps<import('react').InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, never>>, "as" | "forwardedAs"> & {
+    as?: import('styled-components').WebTarget | undefined;
+    forwardedAs?: import('styled-components').WebTarget | undefined;
+}, never>>> & string;
+export declare const ToolbarButton: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components').FastOmit<import('react').DetailedHTMLProps<import('react').ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, never> & Partial<Pick<import('react').DetailedHTMLProps<import('react').ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, never>>> & string;
+export declare const TriggerButton: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components').FastOmit<import('react').DetailedHTMLProps<import('react').ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, never> & Partial<Pick<import('react').DetailedHTMLProps<import('react').ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, never>>> & string;
+export declare const SecondaryButton: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components').FastOmit<import('react').DetailedHTMLProps<import('react').ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, never> & Partial<Pick<import('react').DetailedHTMLProps<import('react').ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, never>>> & string;
+export declare const PrimaryButton: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components').FastOmit<import('react').DetailedHTMLProps<import('react').ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, never> & Partial<Pick<import('react').DetailedHTMLProps<import('react').ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, never>>> & string;
+export declare const Keyword: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components').FastOmit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, never> & Partial<Pick<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, never>>> & string;
+export declare function Section({ tone, label, hint, children, }: {
+    tone: SectionTone;
+    label: string;
+    hint: string;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare const SentenceRow: import('styled-components/dist/types').IStyledComponentBase<"web", import('styled-components').FastOmit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, never> & Partial<Pick<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, never>>> & string;
+export declare function Chevron({ open }: {
+    open: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function FieldSquiggle({ error, children, style, }: {
+    error?: string;
+    children: ReactNode;
+    style?: CSSProperties;
+}): import("react/jsx-runtime").JSX.Element;