@port60/template-kit 0.21.0 → 1.0.0

package/src/vendor/contract/v2/imagery.json

@@ -0,0 +1,32 @@
+{
+  "description": "Platform imagery envelopes, ADVICE, never enforcement. Entity images (events, courses, articles) render on SEVERAL surfaces at once (cards, carousel slides, detail banners), including platform-owned components, so their guidance is platform-level: the envelope every surface can live with. Template-composed slots (the home hero) are different, their ideal is the TEMPLATE's own design call, declared per-template in manifest.imagery and surfaced beside the upload. Editors measure the actual upload against the relevant guidance and advise; the charity always decides.",
+  "entityImages": {
+    "eventPromo": {
+      "idealAspect": "3:2",
+      "aspectRange": [
+        "4:3",
+        "16:9"
+      ],
+      "minWidth": 1600,
+      "note": "One photo, several surfaces: the events card, the home carousel slide, and the event page banner, each crops differently, so keep the subject centred and avoid text baked into the image."
+    },
+    "courseImage": {
+      "idealAspect": "3:2",
+      "aspectRange": [
+        "4:3",
+        "16:9"
+      ],
+      "minWidth": 1600,
+      "note": "Renders as the course card and the course page opener, subject centred, no baked-in text."
+    },
+    "articleCover": {
+      "idealAspect": "16:9",
+      "aspectRange": [
+        "3:2",
+        "2:1"
+      ],
+      "minWidth": 1600,
+      "note": "The article card thumbnail and the article page cover, wide editorial shots sit best."
+    }
+  }
+}

package/src/vendor/contract/v2/islands.json

@@ -0,0 +1,263 @@
+{
+  "description": "The platform's functional islands, the app-block table. A template PLACES an island with {% island 'name' %}; the platform renders, hydrates, upgrades and patches it. The stylingApi lists the STABLE class names a template may target with CSS; anything not listed is internal and may change without notice.",
+  "islands": [
+    {
+      "name": "donation_widget",
+      "label": "Donation widget",
+      "status": "available",
+      "description": "The full donation flow for the tenant's quick-give cause: suggested amounts, custom amount, donor details, Gift Aid opt-in, payment. All payment/compliance behaviour is platform-owned.",
+      "params": [],
+      "stylingApi": [
+        ".action-card",
+        ".donate-card",
+        ".donate-head",
+        ".donate-sub",
+        ".freq-tabs",
+        ".freq-tab",
+        ".amount-grid",
+        ".amount-option",
+        ".amount-list",
+        ".amount-row",
+        ".giftaid-box",
+        ".donate-submit",
+        ".donate-note",
+        ".donate-success"
+      ]
+    },
+    {
+      "name": "member_menu",
+      "label": "Port60 ID sign-in / account menu",
+      "status": "available",
+      "description": "The branded Port60 ID entry point: the sign-in button (popup flow) for guests, the account pill (Members area / Sign out) for signed-in members. Renders NOTHING when the tenant doesn't allow member sign-ups. The identity brand and popup behaviour are platform-owned and identical across every template, place it in your header's nav; never rebuild it.",
+      "params": [],
+      "stylingApi": [
+        ".nav-p60-signin",
+        ".nav-account",
+        ".nav-account-toggle",
+        ".nav-account-menu",
+        ".p60-mark",
+        ".nav-p60-signin-label",
+        ".nav-account-name",
+        ".nav-account-caret",
+        ".nav-account-icon"
+      ]
+    },
+    {
+      "name": "course_enrol",
+      "label": "Course enrolment widget",
+      "status": "available",
+      "description": "The member-gated course enrolment journey (schedule options, household picker, payment, seat holds) for the course the page addresses. Only meaningful on the course page template (pages/course.liquid), place it where your layout wants the purchase column (left rail, right rail, or below the content); position in your source is position on the page. Everything inside is platform-owned; it renders a standard sold-out note when no places remain (branch on course.soldOut if you want your own tag elsewhere).",
+      "params": [],
+      "stylingApi": [
+        ".course-enrol",
+        ".course-variant-list",
+        ".course-subject-list",
+        ".course-summary",
+        ".course-pay-panel",
+        ".course-soldout-note"
+      ]
+    },
+    {
+      "name": "next_prayer",
+      "label": "Next worship time",
+      "status": "available",
+      "description": "A live countdown to worship.next for the tenant's schedule. Renders nothing when no next time is available. The platform owns the clock; the template owns presentation through the stable classes.",
+      "params": [],
+      "stylingApi": [
+        ".next-prayer",
+        ".next-prayer-label",
+        ".next-prayer-name",
+        ".next-prayer-time",
+        ".next-prayer-countdown"
+      ]
+    },
+    {
+      "name": "article_engagement",
+      "label": "Article engagement",
+      "status": "available",
+      "description": "The platform-owned article views, likes and sharing bar for the article page being rendered.",
+      "params": [],
+      "stylingApi": [
+        ".article-engage",
+        ".article-views",
+        ".article-share-group",
+        ".article-share-btn",
+        ".article-share-word",
+        ".article-share-copied"
+      ]
+    },
+    {
+      "name": "article_comments",
+      "label": "Article comments",
+      "status": "available",
+      "description": "The identity-aware article conversation for the article page being rendered. Renders the closed state when comments are disabled.",
+      "params": [],
+      "stylingApi": [
+        ".article-comments",
+        ".article-comment-list",
+        ".article-comment",
+        ".article-comment-head",
+        ".article-comment-form",
+        ".article-comments-gate",
+        ".article-comments-note"
+      ]
+    },
+    {
+      "name": "hero_carousel",
+      "label": "Hero image carousel",
+      "status": "available",
+      "description": "Rotation for the home hero's photographs (homeHero.images, 2+): auto-advance every ~6s, pauses on hover/focus, honours prefers-reduced-motion (no auto-advance), swipe on touch, dot navigation. The platform owns the motion; the TEMPLATE owns the look, including the tonal treatment: every slide ships an empty .hero-slide-scrim layer over its image, and the template colours it from its OWN palette variables (a colour wash, a blend, a gradient) so any uploaded photo sits inside the template's tones. Renders nothing with fewer than 2 images, single-image and no-image states are the template's own renderer, not this island's.",
+      "params": [],
+      "stylingApi": [
+        ".hero-carousel",
+        ".hero-slides",
+        ".hero-slide",
+        ".hero-slide--active",
+        ".hero-slide-img",
+        ".hero-slide-scrim",
+        ".hero-dots",
+        ".hero-dot",
+        ".hero-dot--active"
+      ]
+    },
+    {
+      "name": "newsletter_signup",
+      "label": "Newsletter sign-up",
+      "status": "available",
+      "description": "Explicit email opt-in over the platform's versioned consent and one-click unsubscribe rail. Templates own placement and presentation; wording, evidence and abuse checks remain platform-owned.",
+      "params": [],
+      "stylingApi": [
+        ".newsletter-signup",
+        ".newsletter-label",
+        ".newsletter-fields",
+        ".newsletter-email",
+        ".newsletter-submit",
+        ".newsletter-consent",
+        ".newsletter-message"
+      ]
+    },
+    {
+      "name": "language_switch",
+      "label": "Language switch",
+      "status": "available",
+      "description": "Switches between the platform's supported public languages while preserving the current route. The host supplies locale and text direction to Liquid and the document element.",
+      "params": [],
+      "stylingApi": [
+        ".language-switch",
+        ".language-switch-label",
+        ".language-switch-select"
+      ]
+    },
+    {
+      "name": "search",
+      "label": "Site search",
+      "status": "available",
+      "description": "The site's search box: a typeahead over the platform's search index (articles, events, services, campaigns, appeals, volunteering and public documents; published and live rows only, never member, payment, private media or admin data). Suggestions are the things themselves, grouped by kind, each a direct link, with a matched-text line when the hit was in the body; Enter or the last row goes to the platform's /search results page. An accessible combobox: the active suggestion carries is-active. Where the box sits is the template's decision.",
+      "params": [],
+      "stylingApi": [
+        ".site-search",
+        ".site-search-form",
+        ".site-search-label",
+        ".site-search-fields",
+        ".site-search-input",
+        ".site-search-submit",
+        ".site-search-results",
+        ".site-search-result",
+        ".site-search-kind",
+        ".site-search-link",
+        ".site-search-summary",
+        ".site-search-empty",
+        ".site-search-title",
+        ".site-search-context",
+        ".site-search-more",
+        ".site-search-corrected"
+      ]
+    },
+    {
+      "name": "form",
+      "label": "Public form",
+      "status": "available",
+      "description": "Renders the tenant's first published platform form and records its submission with explicit privacy acceptance. Templates cannot handle or redirect submissions themselves.",
+      "params": [],
+      "stylingApi": [
+        ".public-form",
+        ".public-form-head",
+        ".public-form-field",
+        ".public-form-check",
+        ".public-form-privacy",
+        ".public-form-submit",
+        ".public-form-message"
+      ]
+    },
+    {
+      "name": "map",
+      "label": "Impact map",
+      "status": "available",
+      "description": "The selected map instance, including its own points and resolved public parent content. The platform owns interaction, eligibility and tiles; the template owns placement and documented styling.",
+      "params": [],
+      "stylingApi": [
+        ".impact-map",
+        ".impact-map-head",
+        ".impact-map-intro",
+        ".impact-map-canvas",
+        ".impact-map-pin",
+        ".impact-map-pin--active",
+        ".impact-map-card",
+        ".impact-map-card-kind",
+        ".impact-map-card-title",
+        ".impact-map-card-summary",
+        ".impact-map-card-cta",
+        ".impact-map-empty"
+      ]
+    },
+    {
+      "name": "volunteer_signup",
+      "label": "Volunteer sign-up",
+      "status": "preview",
+      "description": "The volunteer sign-up flow: what to help with (general, then the events and campaigns that need people), when (only when the opportunity runs in shifts), a few details, then confirmation by a charity-branded email that also signs the volunteer in. Shares the donation widget's card vocabulary so a themed donate card themes this too; the vol-* classes cover what is specific to asking for help.",
+      "params": [],
+      "stylingApi": [
+        ".donate-card",
+        ".action-card",
+        ".vol-body",
+        ".volunteer-card",
+        ".vol-card",
+        ".vol-chosen",
+        ".vol-search",
+        ".vol-list",
+        ".vol-group",
+        ".vol-group-label",
+        ".vol-option",
+        ".vol-option-main",
+        ".vol-option-summary",
+        ".vol-option-meta",
+        ".vol-needed",
+        ".vol-shift-count",
+        ".vol-form",
+        ".vol-availability",
+        ".vol-chips",
+        ".vol-chip",
+        ".vol-confirm",
+        ".vol-optional",
+        ".vol-why",
+        ".vol-extra",
+        ".vol-summary",
+        ".vol-signed-in",
+        ".vol-summary-needed",
+        ".vol-field-error"
+      ]
+    },
+    {
+      "name": "primary_action_widget",
+      "label": "Primary action widget",
+      "status": "available",
+      "description": "The platform-owned action widget selected by site.actions.widget: donate, volunteer or none. Templates place this island and style its documented classes; they never reverse the organisation's action choice.",
+      "params": [],
+      "stylingApi": [
+        ".action-card",
+        ".donate-card",
+        ".volunteer-card"
+      ]
+    }
+  ]
+}

package/src/vendor/contract/v2/layout.json

@@ -0,0 +1,28 @@
+{
+  "description": "How platform pages are placed inside a template. Every platform page (donate, services, events, campaigns, the members area) renders through a fixed set of LAYOUT INTENTS, the content SEAM. A template STYLES these intents to place content its way; it must never build a parallel content container, or platform pages drift from the template's own sections. Enforced at publish by the conformance validator.",
+  "widthToken": "--container",
+  "intents": [
+    {
+      "class": "container",
+      "kind": "contained",
+      "note": "The contained content column, text, forms, cards. Style it (and override --container) to set your content width and gutter. Use it in your own layout and sections too, so everything shares one column."
+    },
+    {
+      "class": "full",
+      "kind": "full-bleed",
+      "note": "Edge-to-edge regardless of the container it sits in, a hero image, a colour band. Restyle it freely; the default breaks out to the viewport width."
+    }
+  ],
+  "rules": [
+    {
+      "id": "no-parallel-container",
+      "kind": "css-width-off-token",
+      "token": "--container",
+      "allow": [
+        "container",
+        "full"
+      ],
+      "message": "builds its own content container from var(--container). Platform pages render inside .container, so a parallel container drifts from your sections, style .container instead (override --container for width and add your gutter there), and use .full for edge-to-edge."
+    }
+  ]
+}