@react-ui-org/react-ui 0.63.1 → 0.64.0

package/.claude/agents/code-reviewer.md

@@ -0,0 +1,122 @@
+---
+name: code-reviewer
+description: Thorough review of a change against this repo's rules — intent/requirements, correctness, design, security (incl. dependency audit), and test coverage. Reviews flexibly by scope: uncommitted work, the whole branch against its base (default master), a specific commit, or a named branch — always as one combined diff. Use after implementing a change, or to review a branch before merge. Complements the generic /code-review skill, which does not know these project rules.
+tools: Read, Grep, Glob, Bash
+---
+
+# Code Reviewer
+
+Review a change as one coherent diff and report findings only — do not edit
+files. Read enough of the surrounding code to judge it, read the cited rule and
+doc files before ruling, and cite `file:line` for every finding.
+
+## Scope — what to review
+
+Orient first: `git status --short` and `git rev-parse --abbrev-ref HEAD`. Then
+pick the scope and state which you chose. Always review the **net result as a
+single diff, never commit-by-commit** — later commits (fixups, reverts) may
+correct earlier ones, and only the final state matters.
+
+* **Explicitly requested** — honour what the invocation asks for: a base branch
+  (`git diff <branch>...HEAD`), a single commit (`git show <sha>`), or a commit
+  range (`git diff <from>..<to>`).
+* **Uncommitted work present** (`git status --short` non-empty) → review the
+  working tree against `HEAD` (`git diff HEAD`) plus any untracked files (list
+  with `git status`, then read them).
+* **Clean tree** → review the whole branch against its base (default `master`):
+  `git diff master...HEAD` (three dots = only what this branch introduced).
+
+Work top-down: first establish what the change is supposed to do, then judge
+whether it does so correctly, cleanly, safely, and with tests. The repo-specific
+rules in section 6 are the easiest to miss — do not skip them.
+
+## 1. Intent & requirements
+
+* Establish the intent from the task / PR description and any linked issue (a
+  GitHub issue number appears in parentheses in the commit/PR name, e.g.
+  `(#261)`). Check the diff against it.
+* Is all the planned functionality present, or is something stubbed, `TODO`, or
+  silently dropped?
+* Flag scope creep — unrelated changes riding along
+  ([code.md](../rules/code.md)).
+
+## 2. Correctness & robustness
+
+* **Error handling.** Failures are handled at the right level, not swallowed;
+  promises are awaited; rejections are handled.
+* **Edge cases.** Empty / `null` / `undefined`, zero / one / many, boundary
+  values, async ordering, and failure paths are handled. Component edge cases:
+  missing `children`, controlled vs uncontrolled, ref forwarding.
+* **Resource hygiene.** `useEffect` subscriptions / listeners / timers are
+  cleaned up; no retained references or unbounded state growth.
+
+## 3. Design & maintainability
+
+* Clean separation of concerns; the change integrates with the existing patterns
+  rather than introducing a parallel style — `React.forwardRef` +
+  `withGlobalProps`, context-aware variants via `useContext`, `classNames()` for
+  CSS Module classes, `transferProps()` for HTML attribute pass-through, CSS
+  Modules for styles ([frontend.md](../rules/frontend.md),
+  [styling.md](../rules/styling.md)).
+* Props follow the [API Guidelines](../../src/docs/contribute/api.md) and nesting
+  follows [Composition](../../src/docs/contribute/composition.md).
+* DRY without premature abstraction; sound, reasonably performant code — no heavy
+  work in render, no needless re-renders.
+
+## 4. Security
+
+* Validate / sanitise external data; no unsafe HTML
+  (`dangerouslySetInnerHTML`) with untrusted content; no secrets committed.
+* **Dependencies.** If `package.json` / `package-lock.json` changed: new
+  dependencies need explicit approval
+  ([safety-guards.md](../rules/safety-guards.md)); run `npm audit` (in the
+  devcontainer) and report advisories; sanity-check the lockfile diff for
+  unexpected or transitive version bumps.
+
+## 5. Tests
+
+* New or changed code is covered — co-located Jest tests in `__tests__/` and/or
+  Playwright component tests (`.spec.tsx` + `.story.tsx`); obsolete tests for
+  removed code are deleted. Never leave a component or helper untested
+  ([testing.md](../rules/testing.md)).
+* A bug-fix test must fail before the fix and pass after.
+* Tests assert behaviour, not implementation details.
+
+## 6. This repo's rules
+
+Easy-to-miss invariants beyond the generic checks above:
+
+* **Lint gate** ([CLAUDE.md](../../CLAUDE.md#commands)): `npm run lint` =
+  eslint + markdownlint + stylelint. It is not auto-run — remind the author to
+  run `npm run lint`, `npm run test:jest`, and `npm run test:playwright-ct:all`.
+* **Component layout** ([frontend.md](../rules/frontend.md)): every component
+  folder has the `.jsx` + `index.js` barrel + `*.module.scss` + `_settings`/
+  `_theme`/`_tools` SCSS partials + `README.md` + `__tests__/`. PropTypes, not
+  TypeScript, in source.
+* **CSS Modules class naming** ([styling.md](../rules/styling.md)): `root`,
+  `isRootXxx`, `hasRootXxx`, `isRootInXxx`, `isRootLayoutXxx`.
+* **Docs** ([docs.md](../rules/docs.md)): component docs live in the component's
+  `README.md`; new doc pages are wired into `mkdocs.yml`.
+* **Git hygiene** ([git.md](../rules/git.md)): no push or remote change without
+  approval; commit/PR subjects imperative English with backticked symbols and a
+  trailing `(#issue)` when one exists; **no `Co-Authored-By`**. PR names land in
+  the changelog.
+
+## Output format
+
+Group findings by severity. For each:
+`severity | file:line | rule/doc cited | what is wrong | concrete fix`.
+
+```text
+## Blocking
+- [requirements] src/components/Foo/Foo.jsx:42 — acceptance criterion not implemented.
+- [tests] src/helpers/bar/bar.js:10 (testing.md) — new helper `bar` has no test.
+
+## Non-blocking / nits
+- [design] src/components/Foo/Foo.jsx:7 (frontend.md) — ref not forwarded to root element.
+
+## Reminders
+- Run `npm run lint`, `npm run test:jest`, and `npm run test:playwright-ct:all` before committing.
+```
+
+End with a one-line verdict: APPROVE / APPROVE WITH NITS / REQUEST CHANGES.

package/.claude/rules/code.md

@@ -0,0 +1,22 @@
+# Code
+
+* Modify files only within defined scope, do not make changes that affect
+  unrelated parts of the codebase, e.g. do not change unrelated comments,
+  imports, code or documentation.
+* Keep changes minimal and focused.
+* Follow the project formatting and style sources:
+  [.editorconfig](../../.editorconfig) (general),
+  [.markdownlint.jsonc](../../.markdownlint.jsonc) (Markdown),
+  [.eslintrc](../../.eslintrc) / [.eslintrc-ts](../../.eslintrc-ts)
+  (JavaScript/TypeScript), [stylelint.config.js](../../stylelint.config.js)
+  (SCSS).
+* Only fix linting/formatting issues in files you created or modified for the
+  current task. Do not fix pre-existing issues outside that scope.
+* Keep comments simple and use terminology and language matching repository
+  standards.
+* Revert unrelated changes. If they are worth keeping, ask the user whether to
+  track them separately — either as a GitHub issue (propose a title and
+  description first, and confirm before creating it) or, for small changes, on a
+  separate branch without an issue.
+* Do not use one character long variable names or shortened names unless it is a
+  common abbreviation.

package/.claude/rules/docs.md

@@ -0,0 +1,35 @@
+---
+paths:
+  - "src/docs/**"
+  - "src/components/**/README.md"
+  - "src/helpers/**/README.md"
+  - "README.md"
+---
+
+# Documentation
+
+## Commands
+
+* Run `npm run markdownlint` after changes (add `-- --fix` to autofix).
+* Run `mkdocs build` and `mkdocs serve` to build and serve the documentation
+* To verify a rendered component or the docs previews in a real browser
+  (navigate, click, screenshot, inspect the running docs site), drive host
+  Chrome through the `chrome-host` MCP. See
+  [AI Integration](../../src/docs/contribute/ai-integration.md).
+
+See [Commands](../../CLAUDE.md#commands).
+
+## Conventions
+
+* Documentation is built with [Material for MkDocs][mkdocs-material] and
+  [Docoff][docoff] (live, runnable component previews). Component docs live in
+  each component's `README.md`; guides and foundations live under `src/docs/`.
+* New pages must be wired into the navigation in [mkdocs.yml](../../mkdocs.yml).
+* Use relative links between docs.
+
+## Reference
+
+* [General Guidelines › Documenting](../../src/docs/contribute/general-guidelines.md#documenting)
+
+[mkdocs-material]: https://squidfunk.github.io/mkdocs-material/
+[docoff]: https://github.com/react-ui-org/docoff

package/.claude/rules/frontend.md

@@ -0,0 +1,72 @@
+---
+paths:
+  - "src/**/*.js"
+  - "src/**/*.jsx"
+---
+
+# Frontend (React component library)
+
+## Commands
+
+* If dependencies change, run `npm ci`.
+* Run `npm run eslint` after changes (add `-- --fix` to autofix).
+* To verify a rendered component or the docs previews in a real browser
+  (navigate, click, screenshot, inspect the running docs site), drive host
+  Chrome through the `chrome-host` MCP. See
+  [AI Integration](../../src/docs/contribute/ai-integration.md).
+
+## Stack
+
+React UI is a themeable React component library, distributed as a UMD bundle
+(with separate CSS) and as ESM (consumers run their own SASS pipeline).
+Components are plain JavaScript / JSX (Babel, no TypeScript in the source) for
+React 18, validated with `prop-types`. TypeScript appears only in tests and type
+checks.
+
+## Component structure
+
+Each component lives in `src/components/<ComponentName>/` and follows this
+layout:
+
+```text
+Button/
+  Button.jsx              # Component implementation (React.forwardRef + withGlobalProps)
+  Button.module.scss      # CSS Modules styles
+  index.js                # Re-exports default (withGlobalProps-wrapped) as named export
+  _settings.scss          # Component-level SCSS variables
+  _theme.scss             # CSS custom properties (design tokens)
+  _tools.scss             # SCSS mixins
+  README.md               # Docoff/MkDocs documentation with live previews
+  helpers/                # Component-specific helper functions
+  __tests__/
+    Button.spec.tsx       # Playwright visual + functional tests
+    Button.story.tsx      # Story components used as test fixtures
+    _propTests/           # Reusable prop test generators (arrays of test cases)
+```
+
+## Implementation pattern
+
+Components are `.jsx` files (not `.tsx`) using PropTypes. They:
+
+1. Use `React.forwardRef` to forward refs to the root HTML element.
+2. Are wrapped with `withGlobalProps(Component, 'ComponentName')` for global prop
+   injection; the wrapped version is the default export.
+3. Use `useContext` to detect layout/group contexts (`FormLayoutContext`,
+   `ButtonGroupContext`, `InputGroupContext`) and apply CSS class variants
+   accordingly.
+4. Use the `classNames()` helper to conditionally combine CSS Module class names.
+5. Use `transferProps()` to pass through non-React HTML attributes to the root
+   element.
+
+Honour the [API Guidelines](../../src/docs/contribute/api.md) and
+[Composition](../../src/docs/contribute/composition.md) when shaping props and
+nesting.
+
+## Styling
+
+Component styles use SCSS with CSS Modules — see the [styling rule](styling.md).
+
+## Tests
+
+Components are covered by Jest unit tests and table-driven Playwright component
+tests — see the [testing rule](testing.md).

package/.claude/rules/git.md

@@ -0,0 +1,13 @@
+# Git
+
+## Skills
+
+Use `/commit` to commit changes.
+
+## Conventions
+
+Full rules are in [General Guidelines › Git Workflow](../../src/docs/contribute/general-guidelines.md#git-workflow).
+
+## Reference
+
+* [General Guidelines › Git Workflow](../../src/docs/contribute/general-guidelines.md#git-workflow)

package/.claude/rules/safety-guards.md

@@ -0,0 +1,9 @@
+# Safety guards
+
+* Never modify files listed in [.gitignore](../../.gitignore) unless approved
+  in a skill
+* Never modify any files outside the project root
+* Never run shell commands that can alter system state or access sensitive data
+  when run on the host system
+* Never modify the git remote (e.g. `git push`) without explicit human approval
+* Never introduce new dependencies without explicit human approval

package/.claude/rules/styling.md

@@ -0,0 +1,32 @@
+---
+paths:
+  - "src/**/*.scss"
+  - "src/**/*.css"
+---
+
+# Styling
+
+## Commands
+
+Run `npm run stylelint` after changes (add `-- --fix` to autofix).
+
+## Styling
+
+Styles use SCSS with CSS Modules (`.module.scss`) with camelCase class names. A
+component's styles live next to it as `Foo.module.scss` and are imported as a
+module.
+
+Class naming convention:
+
+* `root` for the root element.
+* Modifiers follow `isRootXxx` (state), `hasRootXxx` (has feature),
+  `isRootInXxx` (context), `isRootLayoutXxx` (layout variant).
+
+`src/styles/` contains the global theming system: settings (variables), tools
+(mixins), and a large set of CSS custom properties for theming. Component SCSS
+files `@use` their own `_settings`, `_theme`, `_tools` partials plus the shared
+styles from `src/styles/`. Theme tokens are exposed as CSS custom properties.
+
+## Reference
+
+* [CSS Guidelines](../../src/docs/contribute/css.md)

package/.claude/rules/testing.md

@@ -0,0 +1,59 @@
+---
+paths:
+  - "**/*.spec.tsx"
+  - "**/*.story.tsx"
+  - "**/__tests__/**"
+  - "tests/**"
+---
+
+# Testing
+
+## Commands
+
+* Run all Jest unit tests with `npm run test:jest` (TS + JS). For a single file:
+  `npm run test:jest:ts -- <file>` or `npm run test:jest:js -- <file>`.
+* Run all Playwright component tests with `npm run test:playwright-ct:all`; for
+  one component, `npm run test:playwright-ct:all -- -- src/components/Button`.
+* Update Playwright snapshots with `npm run test:playwright-ct:all-with-update`.
+* Serve the report with `npm run test:playwright-ct:show-report`.
+
+## Testing
+
+Create/update tests for added or changed components and helpers, and remove
+obsolete tests when functionality is removed. Never leave a component or helper
+without tests. When fixing a bug, add a test that fails before the fix and
+passes after it.
+
+### Organization
+
+Jest unit/component tests are co-located in a component's `__tests__/` folder.
+
+### Playwright component tests
+
+`.spec.tsx` specs use a table-driven pattern:
+
+* Import arrays of test cases from `_propTests/` directories and from shared
+  `tests/playwright/propTests/`.
+* Each test case is `{ name, props, onBeforeTest?, onBeforeSnapshot? }`; custom
+  field tests add `customFieldLayoutProps`, `customFieldProps`, etc.
+* `mixPropTests([...arrays])` generates the cartesian product of multiple prop
+  arrays.
+* `propTests` from `tests/playwright/` provides standard reusable test sets
+  (e.g. `layoutPropTest`, `sizePropTest`, `disabledPropTest`).
+* Snapshot images are stored alongside the spec file in
+  `<ComponentName>.spec.tsx-snapshots/`.
+
+**Story components** (`.story.tsx`) wrap the real component in a minimal fixture
+(sometimes inside a context provider) and are imported only by `.spec.tsx`
+files. Naming convention: `<ComponentName>ForTest`, `<ComponentName>ForRefTest`,
+`<ComponentName>ForFormLayoutTests` — the FormLayout story component is always
+last.
+
+**Test describe structure:** `test.describe('ComponentName')` →
+`test.describe('base')` (if present) → `visual` / `non-visual` /
+`functionality`; the `formLayout` describe is always the last block at the same
+level as `base`.
+
+## Reference
+
+* [Testing Guidelines](../../src/docs/contribute/testing-guidelines.md)

package/.claude/settings.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git rev-parse:*)",
+      "Bash(git show:*)",
+      "Bash(git status:*)",
+      "Bash(npm audit)",
+      "Bash(npm audit signatures)",
+      "Bash(npm ci)",
+      "Bash(npm run build:*)",
+      "Bash(npm run lint)",
+      "Bash(npm run eslint:*)",
+      "Bash(npm run stylelint:*)",
+      "Bash(npm run markdownlint:*)",
+      "Bash(npm start)",
+      "Bash(npm run start:*)",
+      "Bash(npm test)",
+      "Bash(npm run test:jest:*)",
+      "Bash(npm run test:playwright-ct:*)"
+    ]
+  },
+  "enabledMcpjsonServers": [
+    "chrome-host"
+  ],
+  "enabledPlugins": {
+    "github@claude-plugins-official": true,
+    "context7@claude-plugins-official": true
+  }
+}

package/.claude/skills/commit/SKILL.md

@@ -0,0 +1,54 @@
+---
+description: Draft a commit message and commit staged changes, following the project git conventions
+allowed-tools: Bash(git status), Bash(git diff:*), Bash(git log:*), Bash(git blame:*), Bash(git merge-base:*), Bash(git rev-parse:*), Bash(git add:*), Bash(git commit:*)
+---
+
+# Commit
+
+Draft a commit message and commit the staged changes, following the project's
+git conventions.
+
+## When to use
+
+* You invoke this to commit staged work. User-only — never auto-invoked.
+
+## Context
+
+Status:
+
+!`git status`
+
+Staged diff:
+
+!`git diff --staged`
+
+Branch:
+
+!`git rev-parse --abbrev-ref HEAD`
+
+Branch commits since `master`:
+
+!`git log master..HEAD --oneline 2>/dev/null | head -20`
+
+## Steps
+
+Each commit must be atomic and never leave the app broken.
+
+If nothing is staged, stop and tell the user.
+
+Before committing, check the following (see [Commands](../../../CLAUDE.md#commands)):
+
+* `npm run build` passes
+* `mkdocs build` passes
+* `npm run lint` passes
+* `npm run test:jest` passes
+* `npm run test:playwright-ct:all` passes
+
+Write a commit message for the staged changes following the project's git
+conventions ([General Guidelines › Git Workflow](../../../src/docs/contribute/general-guidelines.md#git-workflow)):
+
+Do not append `Co-Authored-By`.
+
+## Reference
+
+* [General Guidelines › Git Workflow](../../../src/docs/contribute/general-guidelines.md#git-workflow)

package/.devcontainer/devcontainer.json

@@ -0,0 +1,23 @@
+{
+  "name": "React UI (${localWorkspaceFolderBasename})",
+  "initializeCommand": "bash ./setup.sh",
+  "dockerComposeFile": [
+    "../docker-compose.yml"
+  ],
+  "service": "devcontainer",
+  "shutdownAction": "stopCompose",
+  "workspaceFolder": "/workspace",
+  "forwardPorts": [
+    "docs:8000"
+  ],
+  "portsAttributes": {
+    "docs:8000": {
+      "label": "Docs server",
+      "protocol": "http",
+      "onAutoForward": "openBrowser"
+    }
+  },
+  "otherPortsAttributes": {
+    "onAutoForward": "ignore"
+  }
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "chrome-host": {
+      "command": "sh",
+      "args": ["scripts/mcps/chrome-host/mcp-entry.sh"]
+    }
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository
+
+## Environment
+
+This project is developed inside a Docker container called `devcontainer`.
+The commands below assume you are running inside the `devcontainer`.
+
+From the host, run them inside it with
+`docker compose exec -T devcontainer <command>` (start it first with
+`docker compose up -d`). The other service containers (`node`, `playwright`,
+`docs`) are implementation details — do not call them directly.
+
+If file `/.dockerenv` is present, you are in a Docker container.
+
+For details, see the
+[Contributing Guide](src/docs/contribute/general-guidelines.md#development-environment).
+
+## Commands
+
+Run these inside the `devcontainer` (from the host, prefix with
+`docker compose exec -T devcontainer`). For details, see the
+[Contributing Guide](src/docs/contribute/general-guidelines.md).
+
+| Task                              | Command                                                             |
+|-----------------------------------|---------------------------------------------------------------------|
+| Install JS                        | `npm ci`                                                            |
+| Build library                     | `npm run build`                                                     |
+| Run static checks                 | `npm run lint`                                                      |
+| Run unit tests                    | `npm run test:jest`                                                 |
+| Run a single unit test file       | `npm run test:jest:ts -- <file>` / `npm run test:jest:js -- <file>` |
+| Run component tests               | `npm run test:playwright-ct:all`                                    |
+| Component tests for one component | `npm run test:playwright-ct:all -- -- src/components/Button`        |
+| Update component snapshots        | `npm run test:playwright-ct:all-with-update`                        |
+| Start build watcher               | `npm start`                                                         |
+| Build documentation               | `mkdocs build`                                                      |
+| Serve documentation               | `mkdocs serve`                                                      |
+
+Notes:
+
+* Commands like `npm`, `playwright` run in specific Docker containers.
+  Normally, when you run those commands, they are executed within dedicated
+  containers. If you need to communicate directly with specific Docker container,
+  use `sudo docker compose ...`. It can be useful when stopping server that is
+  running within `node` container even though it is started from `devcontainer`.
+* See the `scripts` section in `package.json` for the full list of commands.
+
+## Topics (Claude Rules)
+
+Project rules live in [.claude/rules/](.claude/rules/). There are two kinds.
+
+**Always-on** (no frontmatter) — apply to every change:
+
+* [code.md](.claude/rules/code.md) — scope discipline, minimal changes.
+* [git.md](.claude/rules/git.md) — branches, commits, PRs.
+* [safety-guards.md](.claude/rules/safety-guards.md) — hard guard rails.
+
+**Path-scoped** — each carries a `paths:` glob declaring the files it governs;
+consult it when touching those files:
+
+* [frontend.md](.claude/rules/frontend.md) — `src/**/*.js`, `src/**/*.jsx`:
+  stack, component structure, implementation pattern.
+* [styling.md](.claude/rules/styling.md) — `src/**/*.scss`, `src/**/*.css`:
+  CSS Modules, class naming, theming.
+* [testing.md](.claude/rules/testing.md) — `*.spec.tsx`, `*.story.tsx`,
+  `__tests__/**`, `tests/**`: Jest and table-driven Playwright tests.
+* [docs.md](.claude/rules/docs.md) — `src/docs/**`, component `README.md`.
+
+## Agents (Claude Agents)
+
+Specialized agents live in [.claude/agents/](.claude/agents/).
+
+* `code-reviewer` — review a change against this repo's rules (uncommitted work,
+  or a whole branch vs its base).
+
+## AI Integration
+
+MCP-capable assistants in the `devcontainer` can drive host Chrome to verify the
+docs site and rendered components. See
+[AI Integration](src/docs/contribute/ai-integration.md) and
+[scripts/mcps/chrome-host/README.md](scripts/mcps/chrome-host/README.md).