ropav 0.1.9 → 0.2.0

package/docs/code-architecture.md

@@ -0,0 +1,147 @@
+# Code architecture
+
+This guide defines the source structure expected from contributors. The goal is a predictable
+codebase where UI files describe rendering, behavior is testable through small interfaces, and
+shared logic has one obvious home.
+
+## Package seams
+
+This repository publishes `ropav`, a zero-VDOM UI component library for Vue Vapor. Paths such as
+`src/utils/` below are relative to this package's root.
+
+The library integrates `@floating-ui/dom` and `focus-trap` through package dependencies, and it
+exposes public composables, component subpath exports, design tokens, and styles through its
+`package.json` exports. Production source stays zero-VDOM: component rendering, style injection,
+and accessible behavior are built with Vue Vapor, never through VDOM interfaces.
+
+## Module seams
+
+A module should hide a meaningful amount of behavior behind a small interface. Extract code around
+a responsibility, not merely to reduce a line count. A useful extraction makes callers simpler and
+lets tests exercise the same interface that production code uses.
+
+Use this dependency direction:
+
+```text
+Vue components and component-local modules
+    -> internal composables
+    -> public composables
+    -> utilities
+```
+
+A higher layer may also import a lower layer directly. Lower layers must not import higher layers:
+
+- `src/utils/` does not import components or composables.
+- `src/composables/` does not import components or internal modules.
+- `src/internal/` does not import components.
+- Components may compose other components when the dependency remains acyclic.
+
+## Where code belongs
+
+| Location                                  | Responsibility                                                        |
+| ----------------------------------------- | --------------------------------------------------------------------- |
+| `src/components/<name>/*.vue`             | Template, bindings, slots, and lightweight view-derived state         |
+| `src/components/<name>/useX.ts`           | Component-specific reactive state, lifecycle, and event orchestration |
+| `src/components/<name>/<concern>Model.ts` | Pure behavior that encodes only that component's contract             |
+| `src/internal/composables/`               | Shared reactive behavior that is not part of the package interface    |
+| `src/composables/`                        | Reusable public composables exported by the package                   |
+| `src/utils/`                              | Reusable runtime helpers without component state or lifecycle         |
+| `src/utils/dom/`                          | Reusable helpers that operate on browser and DOM primitives           |
+| `tests/`, `tooling/`, `scripts/`          | Test, build, and repository automation helpers                        |
+
+Do not add catch-all `utils`, `helpers`, or `core` modules beside a component. Keep a pure helper
+local when it expresses one component's contract, and give it a semantic name such as
+`sliderModel`. Move it to `src/utils/` once more than one feature needs the behavior.
+
+## Component shape
+
+Production SFCs use `<script setup lang="ts" vapor>` and remain zero-VDOM. Do not use `h`, `VNode`,
+`defineComponent`, `createVNode`, or related VDOM block helpers in production source.
+
+Keep SFC blocks in this order:
+
+1. `<template>`
+2. `<script setup lang="ts" vapor>`
+3. `<style>`
+
+Within the script block, use this order:
+
+1. Imports
+2. `defineOptions`, props defaults, emits, and slots
+3. Composable state and template refs
+4. View-derived computed attributes
+5. Small event adapters and `defineExpose`
+
+A short computed value used only to bind the template can stay in the SFC. Move state transitions,
+timers, document listeners, multi-step event handling, and reusable calculations behind a
+composable or pure model interface.
+
+## Function design
+
+Oxlint enforces a conservative baseline of cyclomatic complexity 20, nesting depth 4, at most 5
+parameters, and at most 250 non-blank, non-comment lines per function. These are upper bounds, not
+targets.
+
+- Give each function one reason to change.
+- Prefer guard clauses over deeply nested branches.
+- Use an options object when several parameters describe one concept.
+- Split orchestration into named steps, while keeping the external interface small.
+- Accept dependencies or callbacks at the module seam instead of constructing hard-to-test global
+  dependencies inside the implementation.
+- Return observable results where practical; isolate side effects in lifecycle or event adapters.
+
+Do not create shallow pass-through functions solely to satisfy a metric. A refactor should improve
+the caller, the module interface, or the test surface.
+
+## Imports and package interfaces
+
+- Import utilities directly from their module, for example `@/utils/number`; do not add a utils
+  barrel.
+- Component `index.ts` files define package-facing exports. Internal code should not import from the
+  root package barrel.
+- Keep imports acyclic. If two modules need each other, move the shared behavior to the lowest
+  layer that owns the concept.
+- Use `import type` for type-only dependencies.
+
+## Testing
+
+Test through the interface of the extracted module:
+
+- Pure models and utilities use deterministic unit tests.
+- Composables test returned state and commands, using the smallest host needed for lifecycle
+  behavior.
+- Component tests cover DOM integration, events, accessibility, and public rendering contracts.
+- Storybook tests cover visual and interaction scenarios that depend on real browser layout.
+
+Tests should assert observable behavior rather than private implementation details. Refactoring a
+module internally should not require rewriting its behavioral tests.
+
+### Storybook organization
+
+Keep component stories beside their component at
+`src/components/<name>/<name>.stories.ts`. Use human-readable Storybook titles with this hierarchy:
+
+```text
+Foundations/<name>
+Components/<category>/<name>
+Utilities/<name>
+Contracts/<name>
+```
+
+Component categories are `Actions`, `Data Display`, `Feedback`, `Forms`, `Layout`, `Navigation`,
+and `Overlays`. Foundations document design tokens, utilities demonstrate lower-level package
+capabilities, and contracts exercise cross-component or browser integration behavior.
+
+## Contributor checklist
+
+Before opening a pull request:
+
+- The SFC primarily adapts props, slots, and composable results to the template.
+- New reusable helpers live in `src/utils/`; feature-only pure logic has a semantic local name.
+- Dependency direction remains downward and acyclic.
+- Functions stay below the enforced complexity, depth, length, and parameter limits.
+- New behavior is tested at the module interface.
+- The package defines a `verify` script for package-owned type, test, build, and bundle behavior.
+- Lint, formatting, architecture, and zero-VDOM bundle contracts run from the root verification
+  interface.
+- `pnpm verify` passes from the repository root.

package/docs/public-styles-api.md

@@ -121,13 +121,15 @@ Active menu and listbox descendants use `data-highlighted`. Actual DOM keyboard
 
 ## Public CSS variables
 
-The exact entries in [`styles-manifest.json`](../src/styles/styles-manifest.json) are the public contract. A design token enters that manifest only when it opts in with `$extensions.ropav.public: true`. Emitting a CSS variable is a separate runtime concern: neither emission nor a name prefix makes a variable public. Undocumented variables, underscore-prefixed variables, DOM structure and internal component selectors are not part of the public contract and may change.
+The exact entries in the packaged [`tokens/manifest.json`](../tokens/manifest.json) (also exported as `ropav/styles-manifest`) are the public contract. A design token enters that manifest only when it opts in with `$extensions.umberkit.public: true`. Emitting a CSS variable is a separate runtime concern: neither emission nor a name prefix makes a variable public. Undocumented variables, underscore-prefixed variables, DOM structure and internal component selectors are not part of the public contract and may change.
 
-The manifest contains design tokens plus a deliberately small component-geometry allowlist. Slider and RangeSlider share the `--rp-slider-*` namespace. Size presets provide fallbacks, while a consumer value wins for the individual dimension. See the generated [token table](./public-tokens.md).
+Tokens are built with [umberkit](https://www.npmjs.com/package/umberkit): 12-step OKLCH palettes generated from one seed per hue (Radix step semantics — 1-2 backgrounds, 3-5 component backgrounds, 6-8 borders, 9-10 solids, 11-12 text), plus hand-authored semantic roles (`--rp-color-<hue>-filled`, `-light`, `-outline`, …) and scheme semantics (`--rp-color-body`, `-text`, `-default`, …). The generated `tokens.md` and `showcase.html` shipped in `src/styles/generated/` document every token and render the ramps with a contrast grid.
 
-The schema-v2 manifest does not pin a Git commit. `tokens:check` resolves compatibility from release tags, so the baseline advances with releases instead of remaining hard-coded.
+A deliberately small component-geometry namespace (`--rp-switch-*`, `--rp-slider-*`, `--rp-radio-*`) stays outside the token tree: those variables are consumer override hooks with size-preset fallbacks, so they are intentionally undefined by default. Slider and RangeSlider share the `--rp-slider-*` namespace; size presets provide fallbacks, while a consumer value wins for the individual dimension.
 
-Palette shades and their normal and active `*-contrast` companions are required override groups because `autoContrast` consumes state-specific companions selected at build time. The [color override contract](./public-tokens.md#color-override-contract) documents the state pairings and preset-role requirements.
+## Color scheme
+
+Every color token is emitted as `light-dark()`. Set `data-scheme="dark"` (or `"light"`) on `<html>` to switch schemes; without the attribute the operating-system preference applies. Because `light-dark()` values resolve against the color scheme of the element they are declared on (`:root`), the attribute must be set on the document element — subtree scheme switching is not supported.
 
 ## Cascade layers and migration
 
@@ -144,6 +146,6 @@ Place global resets in `reset` and application overrides in `app`. Import order
 - Typed parts, state attributes, manifest entries, geometry variables and cascade layers form the current Public Styles API.
 - Renaming or removing a documented part, state attribute or variable changes the public contract.
 - Adding a public part, state attribute or variable extends the public contract.
-- `tokens:check` compares the current manifest with the latest reachable `ropav@*` release tag that contains one. Until the first package-specific release exists, it falls back to legacy `v*` tags and their pre-monorepo manifest path. Released variables cannot be removed, renamed or changed semantically; adding a variable requires incrementing the manifest's `contractVersion`.
-- Release tags must be available in the Git checkout that runs the check. `PUBLIC_STYLES_BASELINE_REF` can explicitly select another Git ref that contains a manifest.
+- `tokens:check` runs `umberkit check`: lint, generated-palette and manifest drift, and the contract ratchet against the latest reachable `v*` release tag. Removing, renaming, retyping or un-publishing a released public token fails until `contract.version` rises in `umberkit.config.ts`.
+- Release tags must be available in the Git checkout that runs the check (`fetch-depth: 0` in CI). `umberkit check --against <ref>` can explicitly select another baseline.
 - Internal DOM, selectors and undocumented variables are outside the public contract.

package/docs/releasing.md

@@ -0,0 +1,39 @@
+# Releasing
+
+This repository publishes `ropav` with [`bumpp`](https://www.npmjs.com/package/bumpp). Release notes
+are generated from Conventional Commits, and the package is published from GitHub Actions with npm
+Trusted Publishing.
+
+## Release
+
+With a clean working tree, run:
+
+```bash
+pnpm release
+```
+
+`bumpp` bumps the package to the next version (patch/minor/major prompt), runs `pnpm run changelog`
+to regenerate the changelog from commits since the last `v*` tag, then commits
+`chore(release): vX.Y.Z`, tags `vX.Y.Z`, and pushes the commit and tag.
+
+Every push to `main` runs the full quality suite. When the pushed commit is a release commit
+(message starts with `chore(release): v`), the release job rebuilds the package, checks the built
+bundles, and publishes it to npm. Change the release commit message in the `release` script and the
+release workflow will need the matching prefix.
+
+## Changelog
+
+`pnpm run changelog` regenerates `CHANGELOG.md` from commits since the latest `v*` tag. The release
+flow runs this automatically. The changelog is a tracked file, so the working tree must be clean
+before `pnpm release`.
+
+## Trusted Publisher configuration
+
+The npm package is configured as a Trusted Publisher:
+
+- GitHub owner: `daopk`
+- Repository: `ropav`
+- Workflow filename: `publish.yml`
+
+The workflow uses GitHub-hosted runners, Node 24, and `id-token: write`. Do not add a long-lived npm
+publish token to the workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ropav",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -10,7 +10,8 @@
     "dist",
     "docs",
     "src/styles/**/*.scss",
-    "src/styles/styles-manifest.json"
+    "src/styles/generated",
+    "tokens/manifest.json"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -225,8 +226,8 @@
       "import": "./dist/unplugin-icons.js"
     },
     "./base.css": "./dist/base.css",
-    "./styles-manifest": "./src/styles/styles-manifest.json",
-    "./styles-manifest.json": "./src/styles/styles-manifest.json",
+    "./styles-manifest": "./tokens/manifest.json",
+    "./styles-manifest.json": "./tokens/manifest.json",
     "./scss/*.scss": "./src/styles/*.scss"
   },
   "peerDependencies": {
@@ -255,15 +256,22 @@
     "@types/node": "^26.1.1",
     "@vitejs/plugin-vue": "^6.0.8",
     "@vitest/browser-playwright": "^4.1.10",
+    "@vue/compiler-sfc": "3.6.0-rc.2",
     "@vue/compiler-vapor": "3.6.0-rc.2",
     "@vue/tsconfig": "^0.9.1",
+    "bumpp": "^12.1.1",
+    "conventional-changelog": "^7.1.0",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
     "jsdom": "^29.1.1",
+    "oxfmt": "^0.60.0",
+    "oxlint": "^1.75.0",
     "playwright": "^1.61.1",
     "sass-embedded": "^1.100.0",
     "storybook": "^10.5.3",
     "storybook-addon-pseudo-states": "^10.5.3",
     "style-dictionary": "5.5.0",
     "typescript": "~6.0.3",
+    "umberkit": "0.0.1",
     "unplugin-icons": "^23.0.1",
     "vite": "^8.1.5",
     "vite-plugin-dts": "^5.0.3",
@@ -273,30 +281,43 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/daopk/ropav",
-    "directory": "packages/ropav"
+    "url": "https://github.com/daopk/ropav"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=24.7.0",
+      "onFail": "error"
+    }
   },
   "scripts": {
     "dev": "pnpm run storybook",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint . --fix",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "changelog": "node scripts/changelog.mjs",
+    "release": "test -z \"$(git status --porcelain)\" && bumpp --commit \"chore(release): v{version}\" --tag \"v{version}\" --execute \"pnpm run changelog\"",
+    "test:workspace": "node --test tests/*.test.mjs",
     "publication:sync": "node scripts/sync-package-publication.mjs --write",
     "publication:check": "node scripts/sync-package-publication.mjs --check",
     "publication:verify": "node scripts/verify-package-publication.mjs",
-    "tokens:build": "style-dictionary build --config scripts/tokens.config.mjs --silent",
-    "tokens:check": "node scripts/check-tokens.mjs",
+    "tokens:build": "umberkit generate && umberkit build",
+    "tokens:check": "umberkit check",
     "typecheck": "vue-tsc -b tsconfig.app.json tsconfig.node.json tsconfig.test.json",
     "typecheck:storybook": "vue-tsc -p tsconfig.storybook.json --noEmit",
-    "test": "vitest run --project=unit --project=tooling",
+    "test": "pnpm run tokens:emit && vitest run --project=unit --project=tooling",
     "test:consumer-types:built": "tsc -p tests/fixtures/consumer-types/tsconfig.bundler.json && tsc -p tests/fixtures/consumer-types/tsconfig.nodenext.json",
     "test:bundle:built": "node scripts/check-package-bundle.mjs",
     "test:consumer-fixture:built": "node tests/fixtures/consumer-app/check.mjs && vue-tsc -p tests/fixtures/consumer-app/tsconfig.json --noEmit && vite build --config tests/fixtures/consumer-app/vite.config.ts && node tests/fixtures/consumer-app/assertions.mjs",
     "test:package": "pnpm run build && pnpm run publication:verify && pnpm run test:bundle:built && pnpm run test:consumer-types:built && pnpm run test:consumer-fixture:built",
-    "test:watch": "vitest --project=unit --project=tooling",
-    "test:typecheck": "vitest run --project=unit --project=tooling --typecheck",
-    "test:storybook": "vitest run --project=storybook-light --project=storybook-dark",
-    "build": "pnpm run publication:check && pnpm run tokens:check && pnpm run typecheck && vite build",
-    "verify": "pnpm run typecheck:storybook && pnpm run test && pnpm run test:storybook && pnpm run test:package",
+    "test:watch": "pnpm run tokens:emit && vitest --project=unit --project=tooling",
+    "test:storybook": "pnpm run tokens:emit && vitest run --project=storybook-light --project=storybook-dark",
+    "build": "pnpm run publication:check && pnpm run tokens:check && pnpm run tokens:emit && pnpm run typecheck && vite build",
+    "verify": "pnpm run lint && pnpm run format:check && pnpm run test:workspace && pnpm run typecheck:storybook && pnpm run test && pnpm run test:storybook && pnpm run test:package",
     "preview": "vite preview",
-    "storybook": "pnpm run tokens:check && storybook dev -p 6006 --no-open",
-    "build-storybook": "pnpm run tokens:check && pnpm run typecheck:storybook && storybook build"
+    "storybook": "pnpm run tokens:emit && storybook dev -p 6006 --no-open",
+    "build-storybook": "pnpm run tokens:emit && pnpm run typecheck:storybook && storybook build",
+    "tokens:emit": "umberkit build"
   }
 }

package/src/styles/_mixins.scss

@@ -1,8 +1,4 @@
-@use 'variables' as *;
-
-$rp-component-colors:
-    'dark', 'gray', 'red', 'pink', 'grape', 'violet', 'indigo', 'blue', 'cyan', 'teal', 'green',
-    'lime', 'yellow', 'orange';
+@use 'generated/tokens.scss' as *;
 
 @mixin flex-center {
     display: inline-flex;
@@ -96,7 +92,7 @@ $rp-component-colors:
 }
 
 @mixin menu-surface(
-    $z-index: $z-index-dropdown,
+    $z-index: $rp-z-index-dropdown,
     $surface: var(--rp-color-default),
     $radius: var(--rp-radius-lg)
 ) {