diff --git a/.claude/skills/react-doctor/SKILL.md b/.claude/skills/react-doctor/SKILL.md new file mode 100644 index 0000000..332a47f --- /dev/null +++ b/.claude/skills/react-doctor/SKILL.md @@ -0,0 +1,51 @@ +--- +name: react-doctor +description: Use when finishing a feature, fixing a bug, before committing React code, or when the user types `/doctor`, asks to scan, triage, or clean up React diagnostics. Covers lint, accessibility, bundle size, architecture. Includes a regression check and a full local-triage workflow that fetches the canonical playbook. +version: "1.2.0" +--- + +# React Doctor + +Scans React codebases for security, performance, correctness, and architecture issues. Outputs a 0–100 health score. + +## After making React code changes: + +Run `npx react-doctor@latest --verbose --scope changed` and check the score did not regress. + +If the score dropped, fix the regressions before committing. + +## For general cleanup or code improvement: + +Run `npx react-doctor@latest --verbose` (the default `--scope full`) to scan the full codebase. Fix issues by severity — errors first, then warnings. + +## /doctor — full local triage workflow + +When the user types `/doctor`, says "run react doctor", or asks for a full triage / cleanup pass (not just a regression check), fetch the canonical local-triage playbook and follow every step in it: + +```bash +curl --fail --silent --show-error \ + --header 'Cache-Control: no-cache' \ + https://www.react.doctor/prompts/react-doctor-agent.md +``` + +The playbook is the single source of truth — a scan → filter → triage → fix → validate loop that edits the working tree directly (never commits, never opens PRs). Updating the prompt at its source updates every agent on its next fetch — no skill reinstall needed. + +Pair it with the matching per-rule prompts at `https://www.react.doctor/prompts/rules//.md` (fetched on demand inside the playbook) so each fix uses the canonical, reviewer-tested recipe. + +## Configuring or explaining rules + +When the user wants to understand a rule, disagrees with one, or wants to disable / tune which rules run (not fix code), read [references/explain.md](references/explain.md) and follow it. Start with `npx react-doctor@latest rules explain `, then apply the narrowest control via `npx react-doctor@latest rules disable|set|category|ignore-tag …`, which edits your `doctor.config.*` (or `package.json#reactDoctor`). + +## Command + +```bash +npx react-doctor@latest --verbose --scope changed +``` + +| Flag | Purpose | +| ----------------- | ---------------------------------------------------------------- | +| `.` | Scan current directory | +| `--verbose` | Show affected files and line numbers per rule | +| `--scope changed` | Only report issues introduced vs the base branch (default: full) | +| `--scope lines` | Only report issues on the changed lines | +| `--score` | Output only the numeric score | diff --git a/.claude/skills/react-doctor/references/explain.md b/.claude/skills/react-doctor/references/explain.md new file mode 100644 index 0000000..8e4defe --- /dev/null +++ b/.claude/skills/react-doctor/references/explain.md @@ -0,0 +1,72 @@ +# Explaining and configuring rules + +Explain React Doctor rules and edit `doctor.config.*` safely. Use this when a user +wants to understand a rule or change which rules run — not for fixing diagnostics +(that is the main `react-doctor` skill / `/doctor`). + +Triggers: "why did this rule fire", "I disagree with this rule", "turn this rule off", +"stop flagging X", "too noisy", "disable design rules". + +## Workflow + +1. Identify the rule key from the diagnostic (e.g. `react-doctor/no-array-index-as-key`). +2. Explain it before changing anything: + +```bash +npx react-doctor@latest rules explain react-doctor/no-array-index-as-key +``` + +3. Pick the narrowest control that matches the user's intent (see decision guide). +4. Apply it with a `rules` subcommand (edits your `doctor.config.*` or `package.json#reactDoctor` in place, preserving other fields and formatting). +5. Validate the change did what they wanted: + +```bash +npx react-doctor@latest --verbose --diff +``` + +## Commands + +```bash +npx react-doctor@latest rules list # every rule + its effective severity +npx react-doctor@latest rules list --configured # only what your config changed +npx react-doctor@latest rules list --category Performance # filter by category +npx react-doctor@latest rules explain # why it matters + how to configure +npx react-doctor@latest rules disable # rule never runs +npx react-doctor@latest rules enable # turn back on at its recommended severity +npx react-doctor@latest rules set warn # off | warn | error +npx react-doctor@latest rules category "React Native" off # whole category +npx react-doctor@latest rules ignore-tag design # skip a rule family (design, test-noise, …) +npx react-doctor@latest rules unignore-tag design +``` + +Rule references accept the full key (`react-doctor/no-danger`), the bare id (`no-danger`), or a legacy key (`react/no-danger`). + +## Decision guide + +Match the control to the intent — prefer the narrowest one: + +- **User disagrees with one rule / it's a false positive for them** → `rules disable ` (sets `rules. = "off"`; the rule stops running everywhere). This is the default for "I don't want this rule". +- **Rule is fine but wrong severity** → `rules set warn` or `rules set error`. +- **A disabled-by-default rule they want on** → `rules enable `. +- **A whole area is unwanted** (e.g. all React Native rules) → `rules category "" off`. +- **A behavioral family is noisy** (`design`, `test-noise`, `migration-hint`) → `rules ignore-tag `. +- **Keep it locally but hide from PR comment / score / CI gate only** → do NOT disable. Edit `surfaces` in your config (`surfaces.prComment.excludeRules`, `surfaces.score.excludeTags`, `surfaces.ciFailure.excludeCategories`). The rule still shows in local `cli` output. + +How the layers combine: `ignore.tags` disables every rule carrying that tag **before** linting, so a tagged rule stays off even if `rules`/`categories` set it to `warn`/`error` (a rule-level override cannot re-enable a tag-ignored rule). For rules that aren't tag-disabled, `rules` overrides `categories` overrides the rule's default. `surfaces` is visibility-only and never changes whether a rule runs. + +## Config shape + +Config lives in `doctor.config.ts` (or `.js`/`.mjs`/`.cjs`/`.json`/`.jsonc`), or the `reactDoctor` key in `package.json`. The `rules` commands edit whichever exists — TS/JS edits preserve formatting (via magicast) — and create `doctor.config.json` when none does, stamping `$schema`: + +```ts +// doctor.config.ts +export default { + rules: { "react-doctor/no-array-index-as-key": "off" }, + categories: { "React Native": "warn" }, + ignore: { tags: ["design"] }, +}; +``` + +## Educating the user + +When explaining a rule, lead with the "Why it matters" guidance from `rules explain` and, when they want depth, the per-rule recipe at `https://www.react.doctor/prompts/rules//.md`. Only after they understand it should you offer to disable it — many "bad" rules are catching real issues. diff --git a/.github/workflows/react-doctor.yml b/.github/workflows/react-doctor.yml new file mode 100644 index 0000000..a8727fa --- /dev/null +++ b/.github/workflows/react-doctor.yml @@ -0,0 +1,53 @@ +# React Doctor — finds security, performance, correctness, accessibility, +# bundle-size, and architecture issues in React codebases. +# +# Docs: https://www.react.doctor/ci +# Source: https://github.com/millionco/react-doctor + +name: React Doctor + +on: + # Scans the PR's changed files and posts a sticky summary comment listing only the new issues introduced relative to the merge base of the target branch. + pull_request: + types: [opened, synchronize, reopened, ready_for_review] + # Scans `main` on every push to track the health-score trend and catch regressions that slipped past PR review. + push: + branches: ["main"] + +permissions: + contents: read + pull-requests: write + issues: write + statuses: write + +# Cancels any in-flight scan for the same PR (or branch, on push) the moment a new commit arrives, so reviewers only ever see the latest run. +concurrency: + group: react-doctor-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + react-doctor: + runs-on: ubuntu-latest + steps: + # fetch-depth: 0 gives React Doctor the full git history it needs to find the merge base with the target branch. Without it a shallow checkout has no merge base, so PR runs can't compare against the base and fall back to reporting every issue in the changed files (pre-existing ones included) instead of only the ones the PR introduced. + - uses: actions/checkout@v5 + with: + fetch-depth: 0 + + - uses: millionco/react-doctor@v2 + # Advisory by default: React Doctor reports findings on every PR — a + # sticky summary comment, inline review comments, and a commit status + # with the health score — but never fails the check, so it won't red-X + # a teammate's PR on day one. When your team trusts the signal, graduate + # the gate: uncomment the block below and set blocking to "error" (fail + # on new error-severity findings) or "warning" (fail on any finding). + # Full reference: https://www.react.doctor/ci + # with: + # blocking: error # Gate level: "none" (advisory, the default) | "warning" | "error" + # scope: full # On PRs, scan the whole project instead of just changed files + # comment: false # Disable the sticky PR summary comment + # review-comments: false # Disable inline review comments on changed lines + # commit-status: false # Disable the commit status (score + counts, links to the run) + # version: "0.4.0" # Pin to a specific react-doctor version instead of "latest" + # directory: apps/web # Scan a sub-directory (default: ".") + # project: "web,admin" # In a monorepo, scan specific workspace project(s) diff --git a/package.json b/package.json index ff046e2..5c3114b 100644 --- a/package.json +++ b/package.json @@ -17,7 +17,8 @@ "build-storybook": "turbo run build --filter=@elide/tokens --filter=@elide/ui && bun run --filter=@elide/storybook build-storybook", "chromatic": "bun run --filter @elide/storybook chromatic", "changeset": "changeset", - "release": "changeset publish" + "release": "changeset publish", + "doctor": "npx react-doctor@latest" }, "devDependencies": { "@changesets/cli": "^2.31.0", diff --git a/packages/ui/src/components/ai-actions.tsx b/packages/ui/src/components/ai-actions.tsx index 5c37e1d..bc7b110 100644 --- a/packages/ui/src/components/ai-actions.tsx +++ b/packages/ui/src/components/ai-actions.tsx @@ -1,7 +1,7 @@ import * as React from "react"; import { Check, Copy, ExternalLink, Sparkles } from "lucide-react"; import { cn } from "../lib/utils"; -import { useMessages } from "../i18n/provider"; +import { useMessages } from "../i18n/context"; /** * AiActions — the "Use with AI" panel in the docs right rail: copy the page as diff --git a/packages/ui/src/components/app-nav.tsx b/packages/ui/src/components/app-nav.tsx index 3518302..2ca67fe 100644 --- a/packages/ui/src/components/app-nav.tsx +++ b/packages/ui/src/components/app-nav.tsx @@ -3,7 +3,7 @@ import { ChevronDown, Globe, History, Search, Sparkles, Sun } from "lucide-react import { cn } from "../lib/utils"; import { Button } from "./button"; import { ElideLogo } from "./elide-logo"; -import { useMessages } from "../i18n/provider"; +import { useMessages } from "../i18n/context"; /** * AppNav — the 56px top nav bar present on every docs page: brand + "DOCS" @@ -120,12 +120,23 @@ export function AppNav({ - - diff --git a/packages/ui/src/components/badge-variants.ts b/packages/ui/src/components/badge-variants.ts new file mode 100644 index 0000000..5c89417 --- /dev/null +++ b/packages/ui/src/components/badge-variants.ts @@ -0,0 +1,25 @@ +import { cva } from "class-variance-authority"; + +/** + * Badge class variants. Kept out of badge.tsx so that file exports only + * components and Fast Refresh can preserve state on edit. + */ +export const badgeVariants = cva( + "inline-flex items-center gap-1.5 rounded-full font-semibold leading-none", + { + variants: { + variant: { + neutral: "border border-border text-muted-foreground", + primary: "text-[var(--primary-emphasis)] [background:var(--primary-soft)]", + supported: "text-[var(--eld-success-strong)] [background:color-mix(in_oklab,var(--eld-success-strong)_14%,transparent)]", + partial: "text-[var(--eld-warning-strong)] [background:color-mix(in_oklab,var(--eld-warning-strong)_14%,transparent)]", + missing: "text-muted-foreground [background:var(--muted)]", + }, + size: { + sm: "px-2 py-0.5 text-[10px]", + md: "px-2.5 py-1 text-xs", + }, + }, + defaultVariants: { variant: "neutral", size: "md" }, + }, +); diff --git a/packages/ui/src/components/badge.tsx b/packages/ui/src/components/badge.tsx index 09919f9..18a77b0 100644 --- a/packages/ui/src/components/badge.tsx +++ b/packages/ui/src/components/badge.tsx @@ -1,31 +1,12 @@ import * as React from "react"; -import { cva, type VariantProps } from "class-variance-authority"; +import { type VariantProps } from "class-variance-authority"; import { cn } from "../lib/utils"; +import { badgeVariants } from "./badge-variants"; /** * Badge — leaf primitive. Includes the API-reference status tones * (supported / partial / missing) used across the docs reference pages. */ -const badgeVariants = cva( - "inline-flex items-center gap-1.5 rounded-full font-semibold leading-none", - { - variants: { - variant: { - neutral: "border border-border text-muted-foreground", - primary: "text-[var(--primary-emphasis)] [background:var(--primary-soft)]", - supported: "text-[var(--eld-success-strong)] [background:color-mix(in_oklab,var(--eld-success-strong)_14%,transparent)]", - partial: "text-[var(--eld-warning-strong)] [background:color-mix(in_oklab,var(--eld-warning-strong)_14%,transparent)]", - missing: "text-muted-foreground [background:var(--muted)]", - }, - size: { - sm: "px-2 py-0.5 text-[10px]", - md: "px-2.5 py-1 text-xs", - }, - }, - defaultVariants: { variant: "neutral", size: "md" }, - }, -); - export interface BadgeProps extends React.HTMLAttributes, VariantProps { @@ -41,5 +22,3 @@ export function Badge({ className, variant, size, dot, children, ...props }: Bad ); } - -export { badgeVariants }; diff --git a/packages/ui/src/components/breadcrumbs.tsx b/packages/ui/src/components/breadcrumbs.tsx index 7208a1c..dcf0ce8 100644 --- a/packages/ui/src/components/breadcrumbs.tsx +++ b/packages/ui/src/components/breadcrumbs.tsx @@ -23,7 +23,7 @@ export function Breadcrumbs({ segments, className, ...props }: BreadcrumbsProps) {segments.map((segment, i) => { const isLast = i === segments.length - 1; return ( -
  • +
  • {isLast ? ( {segment.label} diff --git a/packages/ui/src/components/button-variants.ts b/packages/ui/src/components/button-variants.ts new file mode 100644 index 0000000..ee21b3e --- /dev/null +++ b/packages/ui/src/components/button-variants.ts @@ -0,0 +1,31 @@ +import { cva } from "class-variance-authority"; + +/** + * Button class variants. Kept out of button.tsx so that file exports only + * components and Fast Refresh can preserve state on edit. + * + * `gradient` is the Elide brand CTA (the "Install" button). `changelog` is the + * violet-outlined affordance used in the docs nav. + */ +export const buttonVariants = cva( + "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-lg font-medium transition-colors outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0", + { + variants: { + variant: { + primary: "bg-primary text-primary-foreground hover:bg-primary/90", + gradient: "text-white [background:var(--eld-gradient-brand)] hover:opacity-95", + outline: "border border-border bg-transparent text-foreground hover:bg-[var(--hover)]", + ghost: "bg-transparent text-muted-foreground hover:bg-[var(--hover)] hover:text-foreground", + changelog: + "border text-foreground [border-color:var(--eld-accent-violet)] [background:color-mix(in_oklab,var(--eld-accent-violet)_10%,transparent)] [box-shadow:0_0_0_1px_color-mix(in_oklab,var(--eld-accent-violet)_22%,transparent),0_0_16px_-4px_color-mix(in_oklab,var(--eld-accent-violet)_55%,transparent)] hover:[background:color-mix(in_oklab,var(--eld-accent-violet)_16%,transparent)]", + }, + size: { + sm: "h-8 px-3 text-xs", + md: "h-9 px-4 text-sm", + icon: "h-9 w-9 p-0", + "icon-sm": "h-8 w-8 p-0", + }, + }, + defaultVariants: { variant: "primary", size: "md" }, + }, +); diff --git a/packages/ui/src/components/button.tsx b/packages/ui/src/components/button.tsx index fb6170f..2172c5d 100644 --- a/packages/ui/src/components/button.tsx +++ b/packages/ui/src/components/button.tsx @@ -1,41 +1,17 @@ import * as React from "react"; -import { cva, type VariantProps } from "class-variance-authority"; +import { type VariantProps } from "class-variance-authority"; import { cn } from "../lib/utils"; +import { buttonVariants } from "./button-variants"; /** * Button — leaf primitive. * * Styled entirely from @elide/tokens (bg-primary, text-primary-foreground, …). - * `gradient` is the Elide brand CTA (the "Install" button). `changelog` is the - * violet-outlined affordance used in the docs nav. * * The `render` prop mirrors Base UI's composition model (replaces Radix * `asChild`): pass an element and the button's props/classes merge onto it — * e.g. ``. */ -const buttonVariants = cva( - "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-lg font-medium transition-colors outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0", - { - variants: { - variant: { - primary: "bg-primary text-primary-foreground hover:bg-primary/90", - gradient: "text-white [background:var(--eld-gradient-brand)] hover:opacity-95", - outline: "border border-border bg-transparent text-foreground hover:bg-[var(--hover)]", - ghost: "bg-transparent text-muted-foreground hover:bg-[var(--hover)] hover:text-foreground", - changelog: - "border text-foreground [border-color:var(--eld-accent-violet)] [background:color-mix(in_oklab,var(--eld-accent-violet)_10%,transparent)] [box-shadow:0_0_0_1px_color-mix(in_oklab,var(--eld-accent-violet)_22%,transparent),0_0_16px_-4px_color-mix(in_oklab,var(--eld-accent-violet)_55%,transparent)] hover:[background:color-mix(in_oklab,var(--eld-accent-violet)_16%,transparent)]", - }, - size: { - sm: "h-8 px-3 text-xs", - md: "h-9 px-4 text-sm", - icon: "h-9 w-9 p-0", - "icon-sm": "h-8 w-8 p-0", - }, - }, - defaultVariants: { variant: "primary", size: "md" }, - }, -); - export interface ButtonProps extends React.ButtonHTMLAttributes, VariantProps { @@ -65,5 +41,3 @@ export const Button = React.forwardRef( }, ); Button.displayName = "Button"; - -export { buttonVariants }; diff --git a/packages/ui/src/components/code-block.tsx b/packages/ui/src/components/code-block.tsx index 7decbca..9894603 100644 --- a/packages/ui/src/components/code-block.tsx +++ b/packages/ui/src/components/code-block.tsx @@ -1,8 +1,8 @@ import * as React from "react"; import { Check, Copy } from "lucide-react"; import { Highlight, type PrismTheme } from "prism-react-renderer"; -import { cn } from "../lib/utils"; -import { useMessages } from "../i18n/provider"; +import { cn, keyed } from "../lib/utils"; +import { useMessages } from "../i18n/context"; /** * CopyButton — copies `value` to the clipboard, flips to a check for 1.5s. @@ -102,13 +102,16 @@ function Highlighted({ code, lang }: { code: string; lang?: string }) { {({ tokens, getLineProps, getTokenProps }) => ( <> - {tokens.map((line, i) => ( - - {line.map((token, j) => ( - - ))} - - ))} + {/* Lines carry no ids, so key by content (disambiguated for repeats). */} + {keyed(tokens, (line) => line.map((token) => token.content).join("")).map( + ({ item: line, key }) => ( + + {line.map((token, j) => ( + + ))} + + ), + )} )} diff --git a/packages/ui/src/components/elide-logo.tsx b/packages/ui/src/components/elide-logo.tsx index 3c4dbd7..16bff0f 100644 --- a/packages/ui/src/components/elide-logo.tsx +++ b/packages/ui/src/components/elide-logo.tsx @@ -14,25 +14,25 @@ export function ElideMark({ className, ...props }: React.SVGProps const gid = React.useId(); return ( - + ); diff --git a/packages/ui/src/components/mobile-nav.tsx b/packages/ui/src/components/mobile-nav.tsx index 3a0518c..5b28fc2 100644 --- a/packages/ui/src/components/mobile-nav.tsx +++ b/packages/ui/src/components/mobile-nav.tsx @@ -3,7 +3,7 @@ import { History, Menu, Search, Sparkle } from "lucide-react"; import { cn } from "../lib/utils"; import { Button } from "./button"; import { Sheet, SheetTrigger, SheetContent } from "./sheet"; -import { useMessages } from "../i18n/provider"; +import { useMessages } from "../i18n/context"; /** * MobileNav — the docs shell at phone width (mockup 3b): a condensed top app @@ -172,7 +172,9 @@ export function MobileNav({