Skip to content

docs: refresh root README tables and trim doc index #127

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pjeweb merged 2 commits into from
Jun 26, 2026
Merged

docs: refresh root README tables and trim doc index #127

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
030ddba
docs: refresh root README tables and trim doc index
pjeweb Jun 26, 2026
5aa5ca3
docs: drop AGENTS.md references from STANDARDS
pjeweb Jun 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
162 changes: 108 additions & 54 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,72 +8,126 @@ Mapsight is a framework for building web applications with OpenLayers and React.

## Package overview

| Package | Description |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <nobr>⛓️ [**`core`**](packages/core/README.md)</nobr><br>![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Fcore?style=flat) | **Mapsight Core (Redux Store)**<br>The core of Mapsight, providing the Redux store and the core architecture (controllers, base actions, redux devtools). |
| <nobr>🖥️ [**`ui`**](packages/ui/README.md)</nobr><br>![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Fui?style=flat) | **Default UI (React)**<br>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. |
| <nobr>🎨 [**`traffic-style`**](packages/traffic-style/README.md)</nobr><br>![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Ftraffic-style?style=flat) | **Default style package (icons and vector styles)**<br>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. |
| <nobr>✏️ [**`vector-style-compiler`**](packages/vector-style-compiler/README.md)</nobr><br>![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Fvector-style-compiler?style=flat) | **CSS → OL StyleFunction compiler**<br>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. |
| <nobr>📦 [**`vite-host-embed`**](packages/vite-host-embed/README.md)</nobr> | **Host embed Vite plugin**<br>Lib-mode post-build finalize, HTML snippet markers (`snippetSources`), dev deploy-path aliases, snippet preview. |
| <nobr>📦 [**`vite-count-aggregator-embed`**](packages/vite-count-aggregator-embed/README.md)</nobr> | **Count-aggregator CMS Vite plugin**<br>App-shell post-build finalize — assets-only deploy tree + paste-ready snippet for `@mapsight/count-aggregator-ui`. |
| <nobr>🌐 [**`lib-ol`**](packages/lib-ol/README.md)</nobr><br>![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Flib-ol?style=flat) | **OpenLayers utilities**<br>This package contains utilities for working with OpenLayers. |
| <nobr>⚛️ [**`lib-redux`**](packages/lib-redux/README.md)</nobr><br>![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Flib-redux?style=flat) | **Redux utilities**<br>This package contains utilities for working with Redux. |
| <nobr>⚙️ [**`lib-js`**](packages/lib-js/README.md)</nobr><br>![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Flib-js?style=flat) | **JavaScript utilities (Deprecated)**<br>This package contains utilities for working with JavaScript.<br>⚠️ **Warning:** Do not depend on this package. It is deprecated and will be removed in the future. |
| <nobr>📊 [**`count-aggregator-api`**](packages/count-aggregator-api/README.md)</nobr><br>![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Fcount-aggregator-api?style=flat) | **Count aggregator API client**<br>OpenAPI contract, Zod schemas, and typed HTTP client for Mapsight count-aggregator station metadata and aggregated count data. |
| <nobr>📈 [**`count-aggregator-ui`**](packages/count-aggregator-ui/README.md)</nobr><br>![NPM Version](https://img.shields.io/npm/v/%40mapsight%2Fcount-aggregator-ui?style=flat) | **Count aggregator UI (React)**<br>Embeddable wizard, time-series charts, and export links. CMS app-shell embed via [`vite-count-aggregator-embed`](packages/vite-count-aggregator-embed/README.md). |
<table>
<colgroup>
<col width="290">
</colgroup>
<thead>
<tr>
<th align="left">Package</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><nobr>⛓️ <strong><code>core</code></strong></nobr><br><nobr><a href="https://www.npmjs.com/package/@mapsight/core"><img alt="NPM Version" src="https://img.shields.io/npm/v/%40mapsight%2Fcore?style=flat"></a> | <a href="packages/core/README.md">README</a></nobr></td>
<td><strong>Mapsight Core (Redux Store)</strong><br>The core of Mapsight, providing the Redux store and the core architecture (controllers, base actions, redux devtools).</td>
</tr>
<tr>
<td><nobr>🖥️ <strong><code>ui</code></strong></nobr><br><nobr><a href="https://www.npmjs.com/package/@mapsight/ui"><img alt="NPM Version" src="https://img.shields.io/npm/v/%40mapsight%2Fui?style=flat"></a> | <a href="packages/ui/README.md">README</a></nobr></td>
<td><strong>Default UI (React)</strong><br>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.</td>
</tr>
<tr>
<td><nobr>🎨 <strong><code>traffic-style</code></strong></nobr><br><nobr><a href="https://www.npmjs.com/package/@mapsight/traffic-style"><img alt="NPM Version" src="https://img.shields.io/npm/v/%40mapsight%2Ftraffic-style?style=flat"></a> | <a href="packages/traffic-style/README.md">README</a></nobr></td>
<td><strong>Default style package (icons and vector styles)</strong><br>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.</td>
</tr>
<tr>
<td><nobr>✏️ <strong><code>vector-style-compiler</code></strong></nobr><br><nobr><a href="https://www.npmjs.com/package/@mapsight/vector-style-compiler"><img alt="NPM Version" src="https://img.shields.io/npm/v/%40mapsight%2Fvector-style-compiler?style=flat"></a> | <a href="packages/vector-style-compiler/README.md">README</a></nobr></td>
<td><strong>CSS → OL StyleFunction compiler</strong><br>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.</td>
</tr>
<tr>
<td><nobr>📦 <strong><code>vite-host-embed</code></strong></nobr><br><nobr><a href="https://www.npmjs.com/package/@mapsight/vite-host-embed"><img alt="NPM Version" src="https://img.shields.io/npm/v/%40mapsight%2Fvite-host-embed?style=flat"></a> | <a href="packages/vite-host-embed/README.md">README</a></nobr></td>
<td><strong>Host embed Vite plugin</strong><br>Lib-mode post-build finalize, HTML snippet markers (<code>snippetSources</code>), dev deploy-path aliases, snippet preview.</td>
</tr>
<tr>
<td><nobr>📦 <strong><code>vite-count-aggregator-embed</code></strong></nobr><br><nobr><a href="https://www.npmjs.com/package/@mapsight/vite-count-aggregator-embed"><img alt="NPM Version" src="https://img.shields.io/npm/v/%40mapsight%2Fvite-count-aggregator-embed?style=flat"></a> | <a href="packages/vite-count-aggregator-embed/README.md">README</a></nobr></td>
<td><strong>Count-aggregator CMS Vite plugin</strong><br>App-shell post-build finalize — assets-only deploy tree + paste-ready snippet for <code>@mapsight/count-aggregator-ui</code>.</td>
</tr>
<tr>
<td><nobr>🌐 <strong><code>lib-ol</code></strong></nobr><br><nobr><a href="https://www.npmjs.com/package/@mapsight/lib-ol"><img alt="NPM Version" src="https://img.shields.io/npm/v/%40mapsight%2Flib-ol?style=flat"></a> | <a href="packages/lib-ol/README.md">README</a></nobr></td>
<td><strong>OpenLayers utilities</strong><br>This package contains utilities for working with OpenLayers.</td>
</tr>
<tr>
<td><nobr>⚛️ <strong><code>lib-redux</code></strong></nobr><br><nobr><a href="https://www.npmjs.com/package/@mapsight/lib-redux"><img alt="NPM Version" src="https://img.shields.io/npm/v/%40mapsight%2Flib-redux?style=flat"></a> | <a href="packages/lib-redux/README.md">README</a></nobr></td>
<td><strong>Redux utilities</strong><br>This package contains utilities for working with Redux.</td>
</tr>
<tr>
<td><nobr>⚙️ <strong><code>lib-js</code></strong></nobr><br><nobr><a href="https://www.npmjs.com/package/@mapsight/lib-js"><img alt="NPM Version" src="https://img.shields.io/npm/v/%40mapsight%2Flib-js?style=flat"></a> | <a href="packages/lib-js/README.md">README</a></nobr></td>
<td><strong>JavaScript utilities (Deprecated)</strong><br>This package contains utilities for working with JavaScript.<br>⚠️ <strong>Warning:</strong> Do not depend on this package. It is deprecated and will be removed in the future.</td>
</tr>
<tr>
<td><nobr>📊 <strong><code>count-aggregator-api</code></strong></nobr><br><nobr><a href="https://www.npmjs.com/package/@mapsight/count-aggregator-api"><img alt="NPM Version" src="https://img.shields.io/npm/v/%40mapsight%2Fcount-aggregator-api?style=flat"></a> | <a href="packages/count-aggregator-api/README.md">README</a></nobr></td>
<td><strong>Count aggregator API client</strong><br>OpenAPI contract, Zod schemas, and typed HTTP client for Mapsight count-aggregator station metadata and aggregated count data.</td>
</tr>
<tr>
<td><nobr>📈 <strong><code>count-aggregator-ui</code></strong></nobr><br><nobr><a href="https://www.npmjs.com/package/@mapsight/count-aggregator-ui"><img alt="NPM Version" src="https://img.shields.io/npm/v/%40mapsight%2Fcount-aggregator-ui?style=flat"></a> | <a href="packages/count-aggregator-ui/README.md">README</a></nobr></td>
<td><strong>Count aggregator UI (React)</strong><br>Embeddable wizard, time-series charts, and export links. CMS app-shell embed via <a href="packages/vite-count-aggregator-embed/README.md"><code>vite-count-aggregator-embed</code></a>.</td>
</tr>
</tbody>
</table>

## Applications

| Application | Description |
| :-------------------------------------------------------- | :-------------------------------------------------------------------------- |
| <nobr>🧑‍🎨 [**`vector-editor`**](apps/vector-editor)</nobr> | Vector editor for creating and editing vector features exported as GeoJSON. |
| <nobr>💡 [**`showcase`**](apps/showcase)</nobr> | Mapsight ecosystem showcase — UI demo, icon catalog, and runtime icons. |
<table>
<colgroup>
<col width="290">
</colgroup>
<thead>
<tr>
<th align="left">Application</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><nobr>🧑‍🎨 <strong><code>vector-editor</code></strong></nobr><br><nobr><a href="apps/vector-editor">App</a></nobr></td>
<td>Vector editor for creating and editing vector features exported as GeoJSON.</td>
</tr>
<tr>
<td><nobr>💡 <strong><code>showcase</code></strong></nobr><br><nobr><a href="apps/showcase">App</a></nobr></td>
<td>Mapsight ecosystem showcase — UI demo, icon catalog, and runtime icons.</td>
</tr>
</tbody>
</table>

## 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. |
<table>
<colgroup>
<col width="290">
</colgroup>
<thead>
<tr>
<th align="left">Starter</th>
<th align="left">Status</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><nobr><strong><code>mapsight-host-starter</code></strong></nobr><br><nobr><a href="starters/mapsight-host-starter/README.md">README</a></nobr></td>
<td><strong>Beta</strong></td>
<td>Host embed build (<code>browserEmbed</code> + paste-ready snippet).</td>
</tr>
<tr>
<td><nobr><strong><code>mapsight-next-starter</code></strong></nobr><br><nobr><a href="starters/mapsight-next-starter/README.md">README</a></nobr></td>
<td><strong>WIP</strong></td>
<td>Next.js App Router copy-out template.</td>
</tr>
<tr>
<td><nobr><strong><code>mapsight-vite-spa-starter</code></strong></nobr><br><nobr><a href="starters/mapsight-vite-spa-starter/README.md">README</a></nobr></td>
<td><strong>WIP</strong></td>
<td>Minimal Vite + React Router SPA copy-out template.</td>
</tr>
</tbody>
</table>

## 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

Expand Down
Loading
Loading