Language-agnostic specification for PasteStack Surface Rendering Layer.
This specification defines the contracts for rendering HTML templates using PasteStack. Implementations:
- Scala/Twirl →
paste-surface-scala✓ - Python/Jinja →
paste-surface-python(planned) - Basic HTML → Use
paste-assetgraphdirectly (no surface needed)
┌─────────────────────────────────────────────────────────────────┐
│ Level 4: paste-surface-* │
│ Templated UI (Scala/Twirl, Python/Jinja) │
├─────────────────────────────────────────────────────────────────┤
│ Level 3: paste-surface-spec (this repo) │
│ Contract for how elements get templated │
├─────────────────────────────────────────────────────────────────┤
│ Level 2: paste-elements │
│ UI behaviors (JS + SCSS only, YUI-style modules) │
├─────────────────────────────────────────────────────────────────┤
│ Level 1: paste-assetgraph │
│ Asset pipeline (Rust binary, JAM URLs, manifest) │
└─────────────────────────────────────────────────────────────────┘
Inspired by Model-View-Presenter pattern:
Route -> Presenter -> ViewModelFactory -> ViewModel -> Template
↓
(or JSON)
Presenters are optional. Simple sites use ViewModels directly in templates.
- Page — PageMeta (SEO, meta tags)
- Components — Hero, Address
- Includes — CSS/JS asset injection with JAM
- Factories — PageMetaFactory, HeroFactory, IncludesFactory
- Presenters — PagePresenter, HomePagePresenter
- Web Base Layout — Base HTML structure
- Hero, Address
- Form Fields — Input, Button, Textarea, Hidden
- Configuration — SurfaceConfig, loading from resources
spec/
├── view_models/
│ ├── page.md # PageMeta
│ ├── components.md # Hero, Address
│ └── includes.md # CSSInclude, JSInclude (JAM)
├── view_model_factories/
│ └── factories.md # PageMetaFactory, HeroFactory, IncludesFactory
├── presenters/
│ └── presenters.md # PagePresenter (optional)
├── layouts/
│ └── webbase.md # Base HTML layout
├── components/
│ └── formfield/
│ └── form.md # Input, Button, Textarea, Hidden
└── config/
└── config.md # SurfaceConfig
paste-elements (JS + SCSS) paste-surface-* (Templates)
───────────────────────── ────────────────────────────
src/js/heroscroll.js → components/hero.html
src/js/stickynav.js → components/hero.html (data attrs)
src/js/autogrow.js → components/formfield/textarea.html
src/scss/heroscroll.scss → (bundled CSS)
Elements = JS behaviors + SCSS styles
Components = Template implementations that use elements
MIT