diff --git a/.cursor/rules/00-repo-quality-foundation.mdc b/.cursor/rules/00-repo-quality-foundation.mdc index 5bc1e2e..3cf9760 100644 --- a/.cursor/rules/00-repo-quality-foundation.mdc +++ b/.cursor/rules/00-repo-quality-foundation.mdc @@ -3,4 +3,4 @@ description: Always-on quality baseline for jooservices/react alwaysApply: true --- -Read `AGENTS.md` first. Prefer `.github/skills/` for workflows. Do not create version tags unless the user explicitly requests a release. Never commit `.npmrc` tokens. Keep `dist/` rebuilt when shipping package source that consumers resolve from git. +Read `AGENTS.md` first. Prefer `.github/skills/` for workflows. Do not create version tags unless the user explicitly requests a release. Never commit `.npmrc` tokens. Keep `dist/` rebuilt when shipping package source that consumers resolve from git. PageShell view-level CTAs belong only in `PageShellIdentity` → `actions` via `@jooservices/react-action-buttons` (see `components/content/AGENTS.md`). ConfigPanel Create / New / Publish / Export likewise belong in Identity (wire `ConfigPanelHandle.openCreate()`; see `components/config/AGENTS.md`) — never as built-in panel primary buttons. diff --git a/.github/skills/coverage-and-lint-guard/SKILL.md b/.github/skills/coverage-and-lint-guard/SKILL.md index 1e48524..79bd867 100644 --- a/.github/skills/coverage-and-lint-guard/SKILL.md +++ b/.github/skills/coverage-and-lint-guard/SKILL.md @@ -1,14 +1,17 @@ --- name: coverage-and-lint-guard -description: "Use when: running typecheck and tests as the quality gate for this monorepo." +description: "Use when: running lint, typecheck, and tests as the quality gate for this monorepo." --- # Coverage and lint guard ## Commands +- `npm run lint` — TypeScript strictness (alias of `typecheck`; no ESLint/Prettier stack) - `npm run typecheck` - `npm run test` - `npm run build` +- `npm run demo:typecheck` when package UI / public API changes (also `demo:build` when layout/CSS changes) -Fix failures; do not weaken tests to greenwash. No formatter/linter stack beyond TypeScript + Vitest is mandated yet. +Fix failures; do not weaken tests to greenwash. +CI (`.github/workflows/ci.yml`) runs the same gates on push/PR. diff --git a/.github/skills/documentation-sync/SKILL.md b/.github/skills/documentation-sync/SKILL.md index e95ef39..ca581e4 100644 --- a/.github/skills/documentation-sync/SKILL.md +++ b/.github/skills/documentation-sync/SKILL.md @@ -14,4 +14,8 @@ description: "Use when: keeping README, docs/, AGENTS, skills, and CHANGELOG ali ## DoD Tests · Docs · AI/Agents/Skills · Changelog · README (when applicable) · Demo (`apps/demo`) when package UI/docs change +When documenting or reviewing PageShell pages: confirm view-level CTAs use `@jooservices/react-action-buttons` in `PageShellIdentity` → `actions` only (see `components/content/AGENTS.md`). + +When documenting or reviewing `ConfigPanel`: confirm Create / New / Publish / Export are Identity-only and wired via `ConfigPanelHandle.openCreate()` — the panel must not render competing primary CTAs (see `components/config/AGENTS.md`). + Never invent commands not present in `package.json`. diff --git a/.github/skills/react-package-development/SKILL.md b/.github/skills/react-package-development/SKILL.md index 82985f3..c8b8c1d 100644 --- a/.github/skills/react-package-development/SKILL.md +++ b/.github/skills/react-package-development/SKILL.md @@ -16,3 +16,15 @@ description: "Use when: adding or changing React packages under components/*." 8. `npm run demo:typecheck` (and `npm run demo:build` when layout or shipped CSS changes) Peers (`react`, `react-dom`, `lucide-react`) stay external in `tsup` config. + +## PageShell + action buttons +- View-level CTAs on PageShell pages belong in `PageShellIdentity` → `actions` (Primary action) using `@jooservices/react-action-buttons`. +- **No exceptions** for primary / global view actions. +- Local controls (filters, rows, banner dismiss) may use action-buttons outside Identity — they must not replace Primary action. +- Follow `components/content/AGENTS.md` and `components/action-buttons/AGENTS.md`. + +## ConfigPanel + PageShell +- Create / New / Publish / Export / other **view-level** CTAs for config pages → Identity only; wire create via `ConfigPanelHandle.openCreate()`. +- `ConfigPanel` must **not** render its own New / Create primary (or empty-state Create) button. +- Per-row edit/delete, search, and toggles stay local inside the panel. +- Follow `components/config/AGENTS.md`. diff --git a/.github/skills/release-management/SKILL.md b/.github/skills/release-management/SKILL.md index cbf1ce0..3e01632 100644 --- a/.github/skills/release-management/SKILL.md +++ b/.github/skills/release-management/SKILL.md @@ -10,9 +10,8 @@ If the user did not ask to release, **do not tag**. ## Workflow (v1.0.0+) 1. `release/X.Y.Z` from `develop` -2. Bump all five package versions; update CHANGELOG + README pins -3. `npm run build` && `npm run test`; commit `dist/` -4. PR → `main`; tag `vX.Y.Z`; `gh release create` +2. Bump **all nine** `components/*/package.json` versions; update CHANGELOG + README pins +3. `npm run lint` && `npm run typecheck` && `npm run test` && `npm run build` && `npm run demo:typecheck`; commit `dist/` +4. PR → `main` (CI green); tag `vX.Y.Z`; `gh release create` See `docs/04-development/05-release-process.md`. - diff --git a/.github/skills/task-routing-and-intent-map/SKILL.md b/.github/skills/task-routing-and-intent-map/SKILL.md index 9db2e75..28afb26 100644 --- a/.github/skills/task-routing-and-intent-map/SKILL.md +++ b/.github/skills/task-routing-and-intent-map/SKILL.md @@ -9,6 +9,8 @@ description: "Use when: routing a request to the correct package and skill befor | Intent | Go to | |--------|-------| | Component / CSS / exports | `react-package-development` + package `AGENTS.md` | +| PageShell primary actions / action-buttons placement | `react-package-development` + `components/content/AGENTS.md` + `components/action-buttons/AGENTS.md` | +| ConfigPanel create / view CTAs | `react-package-development` + `components/config/AGENTS.md` + `components/content/AGENTS.md` | | Docs drift | `documentation-sync` | | Release / tag | `release-management` (only if user asked) | | Secrets / deps risk | `security-hardening` | diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..73440c8 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,53 @@ +name: CI + +on: + push: + branches: [main, develop, "release/**"] + pull_request: + +concurrency: + group: ci-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + quality: + name: Lint · typecheck · test · build · demo + runs-on: ubuntu-latest + timeout-minutes: 30 + + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: "20" + + - name: Install package dependencies + run: | + set -euo pipefail + for dir in components/*/; do + echo "::group::npm install ${dir}" + npm ci --prefix "$dir" + echo "::endgroup::" + done + + - name: Lint (TypeScript) + run: npm run lint + + - name: Typecheck + run: npm run typecheck + + - name: Test + run: npm run test + + - name: Build packages + run: npm run build + + - name: Install demo dependencies + run: npm ci --prefix apps/demo + + - name: Demo typecheck + run: npm run demo:typecheck + + - name: Demo production build + run: npm run demo:build diff --git a/AGENTS.md b/AGENTS.md index 84e77e5..705bedf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,11 +19,16 @@ This repository is the **JOOservices React Components** monorepo (`jooservices/r | `@jooservices/react-layout` | `components/layout` | `components/layout/AGENTS.md` | | `@jooservices/react-table` | `components/table` | `components/table/AGENTS.md` | | `@jooservices/react-content` | `components/content` | `components/content/AGENTS.md` | +| `@jooservices/react-action-buttons` | `components/action-buttons` | `components/action-buttons/AGENTS.md` | +| `@jooservices/react-card` | `components/card` | `components/card/AGENTS.md` | +| `@jooservices/react-modal` | `components/modal` | `components/modal/AGENTS.md` | +| `@jooservices/react-toast` | `components/toast` | `components/toast/AGENTS.md` | ## Required command map From repo root (package `node_modules` must already be installed as needed): +- `npm run lint` — TypeScript strictness (alias of `typecheck`; no ESLint stack) - `npm run build` - `npm run test` - `npm run typecheck` @@ -31,6 +36,7 @@ From repo root (package `node_modules` must already be installed as needed): Per package (from that package directory): +- `npm run lint` (alias of `typecheck` when present) - `npm run build` - `npm run test` - `npm run typecheck` @@ -39,10 +45,9 @@ Never invent alternative root scripts beyond this map. ## Distribution and release -- Consumers install via **git tag + path** after the first stable tag (planned `v1.0.0`). +- Consumers install via **git tag + path** (`v1.0.0` and later). - Built `dist/` must be committed so git installs work without a build step for consumers. - **Do not create `v*` tags** unless the user explicitly requests a release. -- Until `v1.0.0`, document install examples as future contract only. - Release flow: see `docs/04-development/05-release-process.md` and `.github/skills/release-management/SKILL.md`. ## Quality rules @@ -52,6 +57,8 @@ Never invent alternative root scripts beyond this map. - Tests: `vitest` via `npm run test`. - React 18+ and `lucide-react` are peer dependencies — do not bundle them. - Styles ship as `dist/styles.css` with `joo-*` CSS variables; keep that contract stable. +- **PageShell primary actions:** view-level CTAs must use `@jooservices/react-action-buttons` in `PageShellIdentity` `actions` only — no exceptions (see `components/content/AGENTS.md`). +- **ConfigPanel:** Create / New / Publish / Export (view-level) → Identity only via `ConfigPanelHandle.openCreate()`; panel must not ship its own primary Create button (see `components/config/AGENTS.md`). ## Agent-first guidance diff --git a/CHANGELOG.md b/CHANGELOG.md index 3bad981..e9c1341 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,11 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [1.0.0] - 2026-07-14 + +### Released + +- First stable git tag + path distribution for all nine `@jooservices/react-*` packages + +### Changed + +- `apps/demo` IA rebuild: Overview → **Dashboard** (cross-package showcase + placeholder metrics/chart); top nav lists all packages + Packages dropdown; generic search; Docs → `/docs` with topic dropdown; sidebar Dashboard + package guides; each package page opens with a How-to block +- `@jooservices/react-config`: removed built-in panel / empty-state Create buttons; Create / New / Publish / Export live in `PageShellIdentity` via `ConfigPanelHandle.openCreate()` (docs, AGENTS, skills updated) +- Docs / AGENTS / skills: PageShell **Primary action** must be `PageShellIdentity` → `actions` with `@jooservices/react-action-buttons` — no exceptions; other buttons stay local/isolated +- `apps/demo` shows a dismissible `AppShell.Banner` on load (search / account menu still rewrite the strip) +- `@jooservices/react-table` `headerActions` / `rowActions` are `ReactNode` slots (compose with `@jooservices/react-action-buttons`); custom `footer` coexists with selection / pagination +- `apps/demo` `/table` exercises the full DataTable surface with action-buttons for identity, header, toolbar, row actions, star/note annotation, and status activate/disable toggle; XFlickr-style annotation column before Name + ### Added -- Public monorepo `jooservices/react` with five packages under `components/` +- `@jooservices/react-toast` — imperative `toast` API + `` (Tailwind-style Simple / actions-below, variants, promise, title/action/secondaryAction, progress, pause-on-hover); demo `/toast` +- `@jooservices/react-modal` — compound `Modal` (Header / Body / Footer), portal overlay, Escape / backdrop close, `closeDisabled`, sizes `sm`–`xl`; demo `/modal` +- `@jooservices/react-card` — `BaseCard` (header icon/title/actions, content, footer) and `StatCard` (value/subtext, optional header icon + info tooltip); demo Dashboard + `/card` +- `apps/demo` `/docs` and `/docs/:slug` in-app documentation views (header Docs dropdown) +- `apps/demo` pages use `@jooservices/react-action-buttons` for PageShell identity actions (Dashboard, Layout, Content, Buttons, Table, Config, UI, Docs) +- `@jooservices/react-action-buttons` — Bootstrap-inspired button colors (JOO cyan-tuned): `primary`/`secondary`/`success`/`danger`/`warning`/`info`/`light`/`dark` + `outline`/`ghost`; `BUTTON_VARIANTS`; `ACTION_COLOR_GUIDE`; demo `/buttons` gallery + guides +- `@jooservices/react-layout` `AppShell.FooterBar` — shared HeaderBar chrome (optional brand); demo omits brand and uses distinct nav/action labels +- `@jooservices/react-content` `PageShellBanner` / `PageBanner` — page-scoped flash under app header (demo Content / Dashboard / Config) +- `@jooservices/react-content` breadcrumb items accept optional `icon?: ReactNode` (demo PageShell pages exercise icons) +- Public monorepo `jooservices/react` with packages under `components/` - Root build/test/typecheck scripts - Documentation hub, AGENTS policy, and AI skill pack -- Git+path distribution model (tagged installs begin at future `v1.0.0`) +- Git+path distribution model (stable installs from `v1.0.0`) - `apps/demo` Vite showcase (AppShell → PageShell → table/config/ui) with root `demo` / `demo:build` / `demo:typecheck` scripts - `@jooservices/react-layout` `AppShell.HeaderBar` — declarative brand / nav (+ dropdowns + icons) / search / actions + user menu (no theme toggle) diff --git a/README.md b/README.md index 7299106..760a267 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Shared React UI packages for the JOOservices ecosystem. -> **Status:** public development monorepo — **not yet tagged for production installs**. Stable git installs start at **`v1.0.0`** (not released yet). Prefer continuing local / tarball workflows until then. +> **Status:** first stable release **`v1.0.0`** — install from git tag + path (not the public npm registry). ## Packages @@ -13,12 +13,15 @@ Shared React UI packages for the JOOservices ecosystem. | `@jooservices/react-layout` | `components/layout` | App shell (top bar, sidebar, content) | | `@jooservices/react-table` | `components/table` | DataTable (TanStack Table + themed UI) | | `@jooservices/react-content` | `components/content` | Page layout shell (identity, toolbar, filters) | +| `@jooservices/react-action-buttons` | `components/action-buttons` | Action bars, menus, split buttons | +| `@jooservices/react-card` | `components/card` | BaseCard shell and StatCard metrics | +| `@jooservices/react-modal` | `components/modal` | Compound Modal (Header / Body / Footer) | +| `@jooservices/react-toast` | `components/toast` | Global toast stack (`toast` API + Toaster) | -## Install (after `v1.0.0`) +## Install ```bash -# example — pin to a future release tag -pnpm add github:jooservices/react#v1.0.0&path:components/table +pnpm add "github:jooservices/react#v1.0.0&path:components/table" ``` ```json @@ -44,7 +47,7 @@ See [docs/01-getting-started/01-installation.md](docs/01-getting-started/01-inst - [Documentation hub](docs/README.md) - [Architecture](docs/00-architecture/01-project-overview.md) - [Distribution model](docs/00-architecture/05-distribution-model.md) -- [Release process](docs/04-development/05-release-process.md) (for maintainers; future `v1.0.0+`) +- [Release process](docs/04-development/05-release-process.md) (for maintainers) - [Consumer migration guide](docs/05-maintenance/03-consumer-migration.md) (apps migrate themselves) ## AI Support @@ -55,7 +58,7 @@ See [docs/01-getting-started/01-installation.md](docs/01-getting-started/01-inst ## Live demo -XCrawlerII-style Vite SPA under [`apps/demo`](apps/demo) that consumes all five packages (styles + composition). +XCrawlerII-style Vite SPA under [`apps/demo`](apps/demo) that consumes all packages (styles + composition). ```bash npm run build # build packages first (dist/) @@ -68,9 +71,10 @@ See [docs/03-examples/04-demo-site.md](docs/03-examples/04-demo-site.md). ## Development ```bash -npm run build # build all packages (writes dist/) -npm run test +npm run lint # TypeScript strictness (alias of typecheck) npm run typecheck +npm run test +npm run build # build all packages (writes dist/) ``` Or per package: diff --git a/apps/demo/AGENTS.md b/apps/demo/AGENTS.md index a9ddcd4..8d82cf6 100644 --- a/apps/demo/AGENTS.md +++ b/apps/demo/AGENTS.md @@ -5,9 +5,18 @@ ## Rules - Light-only chrome — no theme toggle / dark mode switcher. -- Prefer package public APIs (`AppShell.HeaderBar`, `PageShell`, `DataTable`, …). +- Prefer package public APIs (`AppShell.HeaderBar`, `PageShell`, `DataTable`, `ActionBar` / `Button`, …). - When any `components/*` public API or user-visible styles change, update this demo in the same change and run `npm run demo:typecheck` (and `demo:build` when layout/styles change). +### Primary action placement (no exceptions) + +On every PageShell demo page, **view-level CTAs** must use `@jooservices/react-action-buttons` in **`PageShellIdentity` → `actions`** only. + +- Do not invent custom primary `