diff --git a/README.md b/README.md index 57900ee3..58e61278 100644 --- a/README.md +++ b/README.md @@ -8,72 +8,126 @@ Mapsight is a framework for building web applications with OpenLayers and React. ## Package overview -| Package | Description | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| ⛓️ [**`core`**](packages/core/README.md)
![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Fcore?style=flat) | **Mapsight Core (Redux Store)**
The core of Mapsight, providing the Redux store and the core architecture (controllers, base actions, redux devtools). | -| 🖥️ [**`ui`**](packages/ui/README.md)
![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Fui?style=flat) | **Default UI (React)**
The default UI and component library with maps, lists, filters, switchers, etc. Mapsight UI allows you to compose your own UI from the provided components or use a default UI with some configuration and customizations. | -| 🎨 [**`traffic-style`**](packages/traffic-style/README.md)
![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Ftraffic-style?style=flat) | **Default style package (icons and vector styles)**
The default style package with icons and vector styles, tailored for traffic applications, but also provides a set of general POI styles and icons, suitable for various use cases. | -| ✏️ [**`vector-style-compiler`**](packages/vector-style-compiler/README.md)
![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Fvector-style-compiler?style=flat) | **CSS → OL StyleFunction compiler**
The vector style compiler is a tool that converts a subset of CSS styles into a multi-layer cached efficient OpenLayers style function, letting you style based on zoom, feature properties, environment, and more. It also allows you to freely add more geometries based on the base features to build complex vector objects. | -| 📦 [**`vite-host-embed`**](packages/vite-host-embed/README.md) | **Host embed Vite plugin**
Lib-mode post-build finalize, HTML snippet markers (`snippetSources`), dev deploy-path aliases, snippet preview. | -| 📦 [**`vite-count-aggregator-embed`**](packages/vite-count-aggregator-embed/README.md) | **Count-aggregator CMS Vite plugin**
App-shell post-build finalize — assets-only deploy tree + paste-ready snippet for `@mapsight/count-aggregator-ui`. | -| 🌐 [**`lib-ol`**](packages/lib-ol/README.md)
![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Flib-ol?style=flat) | **OpenLayers utilities**
This package contains utilities for working with OpenLayers. | -| ⚛️ [**`lib-redux`**](packages/lib-redux/README.md)
![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Flib-redux?style=flat) | **Redux utilities**
This package contains utilities for working with Redux. | -| ⚙️ [**`lib-js`**](packages/lib-js/README.md)
![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Flib-js?style=flat) | **JavaScript utilities (Deprecated)**
This package contains utilities for working with JavaScript.
⚠️ **Warning:** Do not depend on this package. It is deprecated and will be removed in the future. | -| 📊 [**`count-aggregator-api`**](packages/count-aggregator-api/README.md)
![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Fcount-aggregator-api?style=flat) | **Count aggregator API client**
OpenAPI contract, Zod schemas, and typed HTTP client for Mapsight count-aggregator station metadata and aggregated count data. | -| 📈 [**`count-aggregator-ui`**](packages/count-aggregator-ui/README.md)
![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Fcount-aggregator-ui?style=flat) | **Count aggregator UI (React)**
Embeddable wizard, time-series charts, and export links. CMS app-shell embed via [`vite-count-aggregator-embed`](packages/vite-count-aggregator-embed/README.md). | + +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PackageDescription
⛓️ core
NPM Version | README		Mapsight Core (Redux Store)
The core of Mapsight, providing the Redux store and the core architecture (controllers, base actions, redux devtools).
🖥️ ui
NPM Version | README		Default UI (React)
The default UI and component library with maps, lists, filters, switchers, etc. Mapsight UI allows you to compose your own UI from the provided components or use a default UI with some configuration and customizations.
🎨 traffic-style
NPM Version | README		Default style package (icons and vector styles)
The default style package with icons and vector styles, tailored for traffic applications, but also provides a set of general POI styles and icons, suitable for various use cases.
✏️ vector-style-compiler
NPM Version | README		CSS → OL StyleFunction compiler
The vector style compiler is a tool that converts a subset of CSS styles into a multi-layer cached efficient OpenLayers style function, letting you style based on zoom, feature properties, environment, and more. It also allows you to freely add more geometries based on the base features to build complex vector objects.
📦 vite-host-embed
NPM Version | README		Host embed Vite plugin
Lib-mode post-build finalize, HTML snippet markers (snippetSources), dev deploy-path aliases, snippet preview.
📦 vite-count-aggregator-embed
NPM Version | README		Count-aggregator CMS Vite plugin
App-shell post-build finalize — assets-only deploy tree + paste-ready snippet for @mapsight/count-aggregator-ui.
🌐 lib-ol
NPM Version | README		OpenLayers utilities
This package contains utilities for working with OpenLayers.
⚛️ lib-redux
NPM Version | README		Redux utilities
This package contains utilities for working with Redux.
⚙️ lib-js
NPM Version | README		JavaScript utilities (Deprecated)
This package contains utilities for working with JavaScript.
⚠️ Warning: Do not depend on this package. It is deprecated and will be removed in the future.
📊 count-aggregator-api
NPM Version | README		Count aggregator API client
OpenAPI contract, Zod schemas, and typed HTTP client for Mapsight count-aggregator station metadata and aggregated count data.
📈 count-aggregator-ui
NPM Version | README		Count aggregator UI (React)
Embeddable wizard, time-series charts, and export links. CMS app-shell embed via vite-count-aggregator-embed.
## Applications -| Application | Description | -| :-------------------------------------------------------- | :-------------------------------------------------------------------------- | -| 🧑‍🎨 [**`vector-editor`**](apps/vector-editor) | Vector editor for creating and editing vector features exported as GeoJSON. | -| 💡 [**`showcase`**](apps/showcase) | Mapsight ecosystem showcase — UI demo, icon catalog, and runtime icons. | + +++ + + + + + + + + + + + + + + + + +
ApplicationDescription
🧑‍🎨 vector-editor
App		Vector editor for creating and editing vector features exported as GeoJSON.
💡 showcase
App		Mapsight ecosystem showcase — UI demo, icon catalog, and runtime icons.
## Starters Copy-out host integration templates under [`starters/`](starters/) — semver `@mapsight/*` pins only; not published as a monorepo unit. See [`starters/README.md`](starters/README.md). -| Starter | Status | Description | -| :-------------------------------------------------------------------- | :------- | :------------------------------------------------------- | -| [**`mapsight-host-starter`**](starters/mapsight-host-starter) | **Beta** | Host embed build (`browserEmbed` + paste-ready snippet). | -| **`mapsight-next-starter`** | **WIP** | Next.js App Router copy-out template. | -| [**`mapsight-vite-spa-starter`**](starters/mapsight-vite-spa-starter) | **WIP** | Minimal Vite + React Router SPA copy-out template. | + +++ + + + + + + + + + + + + + + + + + + + + + + + + +
StarterStatusDescription
mapsight-host-starter
README		BetaHost embed build (browserEmbed + paste-ready snippet).
mapsight-next-starter
README		WIPNext.js App Router copy-out template.
mapsight-vite-spa-starter
README		WIPMinimal Vite + React Router SPA copy-out template.
## Documentation -Start at **[`docs/README.md`](docs/README.md)** for role-based paths, architecture, integration guides, -and [getting started](docs/getting-started.md). The [private workspace](#private-workspace-paths) section applies only -to maintainers with a private checkout. - -| Topic | Document | -| ---------------------- | -------------------------------------------------------------------------------------- | -| Hub | [`docs/README.md`](docs/README.md) | -| Getting started | [`docs/getting-started.md`](docs/getting-started.md) | -| Host embed starter | [`starters/mapsight-host-starter`](starters/mapsight-host-starter) | -| Ecosystem & deployment | [`docs/architecture/ECOSYSTEM.md`](docs/architecture/ECOSYSTEM.md) | -| Principles & scope | [`docs/architecture/PRINCIPLES.md`](docs/architecture/PRINCIPLES.md) | -| Decisions | [`docs/architecture/decisions/README.md`](docs/architecture/decisions/README.md) | -| Current vs target | [`docs/architecture/CURRENT_VS_TARGET.md`](docs/architecture/CURRENT_VS_TARGET.md) | -| Redux runtime | [`packages/core/docs/REDUX_ARCHITECTURE.md`](packages/core/docs/REDUX_ARCHITECTURE.md) | -| Redux actions | [`packages/core/docs/ACTION_GUIDE.md`](packages/core/docs/ACTION_GUIDE.md) | -| Licensing | [`docs/LICENSING.md`](docs/LICENSING.md), [`docs/TRADEMARK.md`](docs/TRADEMARK.md) | -| Code of conduct | [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) | - -## Private workspace paths - -Mapsight is open source, but some development still happens outside this tree. The monorepo reserves workspace paths for -that (`private/apps/*`, `private/packages/*` in [`pnpm-workspace.yaml`](pnpm-workspace.yaml)) without publishing -anything under `private/` here. - -To prevent accidental leaks, this repository enforces checks locally and in CI: - -- Git hooks: [`.husky/pre-commit`](.husky/pre-commit), [`.husky/pre-push`](.husky/pre-push) -- Script: [`scripts/check-no-private-leak.mts`](scripts/check-no-private-leak.mts) — `pnpm run check:no-private-leak`, - `pnpm run typecheck:scripts` -- CI: `no-private-leak` job in [`.github/workflows/ci.yml`](.github/workflows/ci.yml) - -**Please do not open pull requests that remove or weaken these guards.** +See **[`docs/README.md`](docs/README.md)** — role-based paths, architecture, integration guides, and getting started. ## Development diff --git a/docs/development/STANDARDS.md b/docs/development/STANDARDS.md index b4a729b8..a46ca5eb 100644 --- a/docs/development/STANDARDS.md +++ b/docs/development/STANDARDS.md @@ -1,6 +1,6 @@ # Development standards -Conventions for contributing to the Mapsight monorepo. AI agents: see also [`AGENTS.md`](../../AGENTS.md). +Conventions for contributing to the Mapsight monorepo. --- @@ -104,13 +104,27 @@ Aligned with [Decision 005](../architecture/decisions/005-fetch-and-tanstack-que ## Private workspace +Mapsight is open source, but some development still happens outside this tree. The monorepo reserves workspace paths for +that (`private/apps/*`, `private/packages/*` in [`pnpm-workspace.yaml`](../../pnpm-workspace.yaml)) without publishing +anything under `private/` here. + On checkouts that include a private workspace: -- Never leak customer-specific deployment details into public paths -- `pnpm run check:no-private-leak` enforces on public branches -- Merge direction: integrate **open source into private**, not the reverse +- Never leak customer-specific deployment details into public paths (`apps/`, `packages/`, `docs/`, root config, CI, + hooks, etc.) +- `pnpm run check:no-private-leak` enforces on public branches; `pnpm-lock.yaml` must not list importers under + `private/` on public branches +- On **`private/*` branches**, these checks are skipped +- Merge direction: integrate **open source into private**, not the reverse — see [`private/README.md`](../../private/README.md) + when present + +To prevent accidental leaks, this repository enforces checks locally and in CI: + +- Git hooks: [`.husky/pre-commit`](../../.husky/pre-commit), [`.husky/pre-push`](../../.husky/pre-push) +- Script: [`scripts/check-no-private-leak.mts`](../../scripts/check-no-private-leak.mts) — `pnpm run check:no-private-leak` +- CI: `no-private-leak` job in [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml) -Details: [`AGENTS.md`](../../AGENTS.md). +**Please do not open pull requests that remove or weaken these guards.** ---