Skip to content

docs: refonte README en page de légitimité (soin palier 0) #117

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
remigit55 merged 1 commit into from
Jun 15, 2026
Merged

docs: refonte README en page de légitimité (soin palier 0) #117

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
265 changes: 49 additions & 216 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,250 +1,83 @@
# Blueprint Modular

**Open-source React component library for business applications.**
> Un instrument ne se contente pas d'afficher une valeur — il porte un jugement.

Blueprint Modular is a production-grade UI framework built for data-intensive apps. 75+ components designed for dashboards, KPI tracking, production monitoring, and enterprise tooling — all accessible through a single `bpm.*` API.
![Blueprint Modular](public/Logo-BPM-nom.jpg)

```bash
npm install @blueprint-modular/core
```

---

## Why Blueprint Modular

Most UI libraries give you buttons and inputs. Blueprint Modular gives you the building blocks of business intelligence:

- **Metrics** — `bpm.metric`, `bpm.metricRow` with delta tracking and automatic color coding
- **Data tables** — `bpm.table` with search, pagination, sort, and custom cell renderers
- **Charts** — `bpm.plotlyChart` wrapping Plotly.js with zero configuration
- **Modals** — `bpm.modal` with a predictable conditional rendering pattern
- **Navigation** — `bpm.sidebar`, `bpm.tabs`, `bpm.breadcrumb`
- **Forms** — `bpm.input`, `bpm.selectbox`, `bpm.numberInput`, `bpm.toggle`, `bpm.datePicker`
- **Feedback** — `bpm.badge`, `bpm.spinner`, `bpm.emptyState`, `bpm.alert`
<!--
TODO(showcase) : aucune capture du showcase n'existe au dépôt à ce jour.
Quand une vraie capture de /components sera exportée (public/ ou docs/),
remplacer l'image ci-dessus (ou décommenter la ligne ci-dessous). Ne pas
inventer d'image.
TODO(manifeste) : la phrase de catégorie ci-dessus reflète la primitive
`interpret` (components/bpm/interpret.ts). Lui substituer la citation
verbatim du Manifeste (repo `memory`, MANIFESTE_Blueprint.md) dès qu'une
source publique est disponible.
-->
<!-- ![Showcase Blueprint Modular](docs/showcase.png) -->

All components share a single import, a consistent prop API, and a unified design language.
Blueprint Modular n'est pas un énième UI kit. C'est une bibliothèque
d'**instruments** : 104 composants métier appelables comme des fonctions,
dont une classe porte la primitive de jugement partagée
`interpret(value, context)` — écart au repère, tendance, anomalie, sévérité.
La sémantique est unique, pure, et vérifiée par le convergence gate.

---

## Quick start

```tsx
import { bpm } from '@blueprint-modular/core'
import '@blueprint-modular/core/dist/style.css'

export default function Dashboard() {
return bpm.container({
children: (
<>
{bpm.pageHeader({ title: 'Production Dashboard' })}
{bpm.metricRow({
children: (
<>
{bpm.metric({ label: 'TRS', value: '87.4%', delta: 2.1, deltaLabel: 'vs last week' })}
{bpm.metric({ label: 'Output', value: '12 480', delta: -340, deltaLabel: 'units' })}
{bpm.metric({ label: 'Downtime', value: '2h 14m' })}
</>
)
})}
</>
)
})
}
```
## Vivant

---
- **Vitrine** — <https://blueprint-modular.com>
- **App de démonstration** — <https://app.blueprint-modular.com>
- **Connecteur MCP** (lecture seule, sans auth) —
`https://mcp.blueprint-modular.com/api/mcp` ·
doc <https://blueprint-modular.com/mcp>

## Installation
## Installer

### npm
**React / TypeScript** (npm)

```bash
npm install @blueprint-modular/core
```

### Import

```tsx
// Always import as a namespace — never destructure
// Toujours en namespace — ne jamais destructurer.
import { bpm } from '@blueprint-modular/core'
import '@blueprint-modular/core/dist/style.css'
```

### Tailwind (required for bpm.tabs and bpm.badge)

```js
// tailwind.config.js
module.exports = {
content: [
'./app/**/*.{ts,tsx}',
'./components/**/*.{ts,tsx}',
'./node_modules/@blueprint-modular/core/dist/**/*.{js,mjs}',
],
safelist: [
{ pattern: /^bpm-tabs-/ },
{ pattern: /^bpm-badge-/ },
],
}
```

---

## Component reference

Full reference at [`blueprint-modular.com/llms.txt`](https://blueprint-modular.com/llms.txt) — machine-readable format designed for LLM-assisted development.

### Layout

| Component | Description |
|-----------|-------------|
| `bpm.container` | Root page wrapper |
| `bpm.pageHeader` | Page title + subtitle + actions |
| `bpm.card` | Content card with optional title |
| `bpm.section` | Labeled section within a page |
| `bpm.sidebar` | Collapsible navigation sidebar |
| `bpm.tabs` | Tab navigation with content panels |

### Data display

| Component | Description |
|-----------|-------------|
| `bpm.metric` | Single KPI with label, value, delta |
| `bpm.metricRow` | Responsive row of metrics |
| `bpm.table` | Searchable, sortable, paginated table |
| `bpm.plotlyChart` | Plotly.js chart wrapper |
| `bpm.timeline` | Chronological event list |
| `bpm.badge` | Status indicator |

### Forms

| Component | Description |
|-----------|-------------|
| `bpm.input` | Text input |
| `bpm.numberInput` | Numeric input with min/max |
| `bpm.selectbox` | Dropdown selector |
| `bpm.toggle` | Boolean switch |
| `bpm.datePicker` | Date selector |
| `bpm.button` | Action button (primary / secondary / outline) |

### Feedback

| Component | Description |
|-----------|-------------|
| `bpm.modal` | Dialog overlay |
| `bpm.spinner` | Loading indicator |
| `bpm.emptyState` | Empty list placeholder |
| `bpm.alert` | Inline alert message |

---
**Python** (PyPI)

## Critical rules

```tsx
// ✅ Correct
import { bpm } from '@blueprint-modular/core'

// ❌ Never destructure
import { bpm.modal } from '@blueprint-modular/core'

// ✅ Modal — always conditional, always inside return()
{isOpen && bpm.modal({ isOpen: true, onClose, title: 'Edit', children: <></> })}

// ❌ Never after return() or outside JSX
const modal = bpm.modal({ ... }) // wrong

// ✅ Charts — always bpm.plotlyChart
{bpm.plotlyChart({ data: traces, layout: {}, height: 300 })}

// ❌ Never bpm.lineChart / bpm.barChart / bpm.areaChart
```bash
pip install blueprint-modular
bpm run app.py
```

---

## LLM-friendly

Blueprint Modular is designed to be used with AI code generation tools.

- **`llms.txt`** — canonical machine-readable reference at [`blueprint-modular.com/llms.txt`](https://blueprint-modular.com/llms.txt)
- **[Blueprint Maker](https://blueprint-maker.com)** — AI app builder that generates full Next.js apps using `bpm.*` components from a plain-language prompt

---

## Validated at scale
Intégration complète (CSS, Tailwind, SSR, API des composants) :
[`packages/core/USAGE.md`](packages/core/USAGE.md). Référence machine pour
agents : [`public/llms.txt`](public/llms.txt).

Blueprint Modular is used in production at [NXTFOOD](https://nxtfood.fr) (food processing, ~120 employees) for operational dashboards, production monitoring, and internal tooling.

---

## Stack

| | |
|--|--|
| Language | TypeScript |
| Framework | React 18 |
| Styling | CSS Modules + Tailwind CSS |
| Charts | Plotly.js |
| Package | `@blueprint-modular/core` on npm |
| Version | 0.1.52 |

---

## Related projects

| Project | Description |
|---------|-------------|
| [Blueprint Maker](https://blueprint-maker.com) | AI app builder — prompt → Next.js app using bpm.* |
| Blueprint Monitor | AI teleprompter for video calls |
| Blueprint Market | Vertical app gallery with Stripe |

---

## Convergence gate

A single command validates the entire component surface — types, build, doc sync, smoke render, and prop-surface snapshot:
## Preuve — convergence gate

```bash
npm run gate
```

| Check | What it verifies |
|-------|-----------------|
| `tsc --noEmit` | TypeScript types in `packages/core/src/` compile without errors |
| `vite build` | Library bundles (`dist/index.mjs`, `dist/index.js`, `dist/style.css`) build cleanly |
| Doc sync | `public/llms.txt` and `lib/generated/bpm-components.json` match what the generators would produce today |
| Smoke render | Every `bpm.*` export mounts with minimal props without throwing |
| Prop-surface snapshot | The prop names for every component match the committed snapshot — any removal/rename = FAIL (θ-additive guarantee) |

**When to run it:** before any PR, after adding/modifying a component, after regenerating docs.

**When a check is red:**
- `tsc` / `vite build` failures → fix the type error or build config.
- Doc sync failure → run `python scripts/generate-llms-txt.py && python scripts/generate-bpm-components-json.py` then re-commit.
- Smoke render failure → the component throws with minimal props; update `packages/core/gate/fixtures.ts` with the correct minimal props, or fix the component bug.
- Prop snapshot failure → a prop was removed/renamed. If intentional, run `npx vitest run gate/ --update-snapshots` from `packages/core` and commit the updated snapshot.

---

## MCP connector (read-only)
Une commande valide toute la surface : types (`tsc`), build (`vite`),
synchro doc, smoke render de chaque `bpm.*`, et snapshot des props
(toute suppression/renommage = échec — garantie θ-additive).

A public, read-only **MCP server** exposes the component catalogue to Claude,
ChatGPT (developer mode) and any MCP host over **Streamable HTTP** — same
deployment, same source of truth as the site. Built to pass a directory review:
`readOnlyHint` tools, cursor pagination, structured/actionable errors, clean
output (catalogue data only), per-IP rate limiting.
## Écosystème

- **Endpoint** : `POST /api/mcp` (no auth — the catalogue is public)
- **Tools** : `list_components`, `search_components`, `get_component`, `suggest_composition`
- **Pages** : docs `/mcp` · privacy `/privacy` · health `GET /api/health`
- **Source of truth** : generated from `bpm-components.json` + `llms.txt`
via `npm run generate:mcp-registry` (never hand-authored)
[**Blueprint Maker**](https://blueprint-maker.com) — du prompt à l'app
Next.js, en composants `bpm.*`. Modular est le substrat ; Maker le fabrique.

Add it in Claude via **Settings → Connectors → Add custom connector**, URL
`https://blueprint-modular.com/api/mcp`. Full details — tools, params, local
testing, MCP Inspector — in [`docs/MCP_CONNECTOR.md`](docs/MCP_CONNECTOR.md).
Directory submission copy: [`SUBMISSION.md`](SUBMISSION.md).
## Aller plus loin

---
- Positionnement — <https://blueprint-modular.com/presentation>
- Catalogue MCP — [`docs/MCP_CONNECTOR.md`](docs/MCP_CONNECTOR.md)
- Référence machine — <https://blueprint-modular.com/llms.txt>

## License
## Licence

MIT
`@blueprint-modular/core` : Apache-2.0 · `blueprint-modular` (PyPI) : MIT
</content>
</invoke>
Loading