5d9730ae04
- Remove ScrubInput aliases, app wrappers, test hooks, and translated legacy references - Share a Tailwind NumberField demo between Storybook and VitePress - Generate component API tables from Vue metadata and type-check examples with Twoslash - Upgrade the docs stack to VitePress 2
97 lines
4.1 KiB
Markdown
97 lines
4.1 KiB
Markdown
# Contribuire
|
|
|
|
## Struttura del progetto
|
|
|
|
```
|
|
packages/
|
|
core/ @open-pencil/core — motore (zero dipendenze DOM)
|
|
src/ Grafo scena, renderer, layout, codec, kiwi, tipi
|
|
cli/ @open-pencil/cli — CLI headless per operazioni .fig
|
|
src/commands/ info, tree, find, export, eval, analyze
|
|
mcp/ @open-pencil/mcp — server MCP per strumenti IA
|
|
src/ Trasporti stdio + HTTP (Hono), 87 strumenti
|
|
src/
|
|
components/ Vue SFCs (canvas, pannelli, barra strumenti, selettore colore)
|
|
properties/ Sezioni pannello proprietà (Aspetto, Riempimento, Contorno, ecc.)
|
|
composables/ Input canvas, scorciatoie tastiera, hook di rendering
|
|
stores/ Stato editor (reattività Vue)
|
|
engine/ Shim di ri-esportazione da @open-pencil/core
|
|
kiwi/ Shim di ri-esportazione da @open-pencil/core
|
|
types.ts Tipi condivisi (ri-esportati da core)
|
|
constants.ts Colori UI, default, soglie
|
|
desktop/ Tauri v2 (Rust + config)
|
|
tests/
|
|
e2e/ Regressione visiva Playwright
|
|
engine/ Test unitari (bun:test)
|
|
docs/ Sito documentazione VitePress
|
|
specs/ Specifiche di capacità (fonte di verità)
|
|
changes/ Cambiamenti attivi e archiviati
|
|
```
|
|
|
|
## Configurazione sviluppo
|
|
|
|
```sh
|
|
bun install
|
|
bun run dev # Editor su localhost:1420
|
|
bun run docs:dev # Docs su localhost:5173
|
|
```
|
|
|
|
## Stile di codice
|
|
|
|
### Strumenti
|
|
|
|
| Strumento | Comando | Scopo |
|
|
|-----------|---------|-------|
|
|
| oxlint | `bun run lint` | Linting (basato su Rust, veloce) |
|
|
| oxfmt | `bun run format` | Formattazione codice |
|
|
| tsgo | `bun run typecheck` | Verifica tipi (checker TypeScript basato su Go) |
|
|
|
|
Eseguire tutte le verifiche:
|
|
|
|
```sh
|
|
bun run check
|
|
```
|
|
|
|
### Convenzioni
|
|
|
|
- **Nomi file** — kebab-case (`scene-graph.ts`, `use-canvas-input.ts`)
|
|
- **Componenti** — PascalCase Vue SFCs (`EditorCanvas.vue`, `NumberField.vue`)
|
|
- **Costanti** — SCREAMING_SNAKE_CASE
|
|
- **Funzioni/variabili** — camelCase
|
|
- **Tipi/interfacce** — PascalCase
|
|
|
|
### Convenzioni per agenti IA
|
|
|
|
Sviluppatori e agenti IA dovrebbero leggere `AGENTS.md` nella root del repo ([vedi su GitHub](https://github.com/open-pencil/open-pencil/blob/master/AGENTS.md)). Copre rendering, grafo scena, componenti e istanze, layout, UI, formato file, convenzioni Tauri e problemi noti.
|
|
|
|
## Apportare modifiche
|
|
|
|
3. Implementare il cambiamento
|
|
4. Eseguire `bun run check` e `bun run test`
|
|
5. Inviare una pull request
|
|
|
|
## File chiave
|
|
|
|
Il codice sorgente del motore core si trova in `packages/core/src/`. Il codice specifico dell'app per editor, documenti, IA, collaborazione, shell, demo e automazione vive in `src/app/*`; l'SDK Vue contiene il codice canvas e composable riutilizzabile in `packages/vue/src/`.
|
|
|
|
| File | Scopo |
|
|
|------|-------|
|
|
| `packages/core/src/scene-graph/` | Grafo scena: nodi, variabili, istanze, hit testing |
|
|
| `packages/core/src/canvas/renderer.ts` | Pipeline di rendering CanvasKit |
|
|
| `packages/core/src/layout.ts` | Adattatore layout Yoga |
|
|
| `packages/core/src/scene-graph/undo.ts` | Gestore annulla/ripristina |
|
|
| `packages/core/src/clipboard.ts` | Appunti compatibili con Figma |
|
|
| `packages/core/src/vector/` | Modello rete vettoriale |
|
|
| `packages/core/src/io/formats/raster/render.ts` | Export immagine offscreen (PNG/JPG/WEBP) |
|
|
| `packages/core/src/kiwi/binary/codec.ts` | Encoder/decoder binario Kiwi |
|
|
| `packages/core/src/kiwi/fig-import.ts` | Logica import file .fig |
|
|
| `packages/cli/src/index.ts` | Punto di ingresso CLI |
|
|
| `packages/core/src/tools/` | Definizioni strumenti unificate (IA, MCP, CLI) |
|
|
| `packages/core/src/figma-api/` | Implementazione Figma Plugin API |
|
|
| `packages/mcp/src/server.ts` | Factory del server MCP |
|
|
| `packages/cli/src/commands/` | Comandi CLI (info, tree, find, export, eval, analyze) |
|
|
| `src/app/editor/session/create.ts` | Editor session assembly |
|
|
| `packages/vue/src/canvas/CanvasRoot.vue` | Composable rendering canvas |
|
|
| `packages/vue/src/canvas/useCanvasInput.ts` | Gestione input mouse/touch |
|
|
| `src/app/shell/keyboard/use.ts` | Gestione scorciatoie tastiera |
|