@profullstack/footer 0.2.6 → 0.3.1

package/README.md

@@ -72,11 +72,25 @@ npx @profullstack/footer html --site https://example.com/ --link Docs=/docs
 | `ring` | `{ slug: 'profullstack', name: 'Profullstack', host: 'https://rssamplifier.com' }` | |
 | `css` | `true` | `false` drops the `<style>`; style `.pfs-footer*` yourself |
 | `houseLinks` | `true` | `false` hides links the template adds for every site |
+| `subscribe` | `true` | `false` hides the newsletter form |
+| `badges` | `[]` | `{ href, src, alt, width?, height? }[]`: badges only this site shows, after the house badges |
 | `nonce` | | CSP nonce for the inline `<style>`; or `css: false` and style `.pfs-footer*` yourself |
 
 Theme it with `--pfs-footer-muted`, `--pfs-footer-gap` and `--pfs-footer-size` on
 `.pfs-footer`; colors otherwise inherit from the page.
 
+## Newsletter form
+
+Every footer carries a small email field and a Subscribe button: a plain HTML form (no script)
+that posts to `https://pit.world/subscribe` with the site's hostname. pit.world runs the double
+opt-in (confirmation email, nothing kept until the click), answers with a "check your inbox" page
+that links back to the site, and records which property each subscriber came from
+(`https://pit.world/admin/subscribers`). The endpoint is fixed in render.js, never in the template.
+
+**CSP:** a site that sets `form-action` must allow it: `form-action 'self' https://pit.world`.
+Turn it off with `subscribe: false` (`--no-subscribe`). Installs before 0.3.0 cannot render the
+form; their footer shows a plain "Newsletter" link to the same page instead, from the @latest template.
+
 ## CLI
 
 ```sh

package/bin/profullstack-footer.js

@@ -20,6 +20,7 @@ const HELP = `usage: profullstack-footer <html|json|descriptor|template|check> [
   --slug <slug>       ring member slug (descriptor; default host with dashes)
   --offline           use the bundled template, do not fetch @latest
   --no-css            leave the <style> out
+  --no-subscribe      leave the newsletter form out
 `;
 
 const { values, positionals } = parseArgs({
@@ -33,6 +34,7 @@ const { values, positionals } = parseArgs({
     slug: { type: 'string' },
     offline: { type: 'boolean' },
     'no-css': { type: 'boolean' },
+    'no-subscribe': { type: 'boolean' },
     help: { type: 'boolean', short: 'h' },
   },
 });
@@ -62,6 +64,7 @@ const opts = () => ({
   since: values.since ? Number(values.since) : undefined,
   tagline: values.tagline,
   css: !values['no-css'],
+  subscribe: !values['no-subscribe'],
 });
 
 switch (cmd) {

package/index.d.ts

@@ -1,4 +1,12 @@
 export interface FooterLink { label: string; href: string; rel?: string }
+export interface FooterBadge {
+  href: string;
+  /** Image URL (http(s) or root-relative). */
+  src: string;
+  alt: string;
+  width?: number;
+  height?: number;
+}
 export interface RingOptions { slug?: string; name?: string; host?: string }
 export interface FooterOptions {
   /** The site's homepage; hops are measured from it. */
@@ -20,6 +28,10 @@ export interface FooterOptions {
   houseLinks?: boolean;
   /** CSP nonce for the inline <style> (style-src 'nonce-...'). */
   nonce?: string;
+  /** false hides the newsletter form (it posts to SUBSCRIBE_URL; CSP form-action must allow https://pit.world). */
+  subscribe?: boolean;
+  /** Badges only this site shows, after the house badges (e.g. a game's Foundplay badge). */
+  badges?: FooterBadge[];
 }
 export interface FooterTemplate {
   version: string;
@@ -46,6 +58,9 @@ export interface DescriptorOptions {
 
 export declare const RENDERER: number;
 export declare const TEMPLATE_URL: string;
+export declare const SUBSCRIBE_URL: string;
+export declare function subscribeForm(site: string): string;
+export declare function siteBadges(badges?: FooterBadge[]): string;
 export declare const DEFAULT_RING: Required<RingOptions>;
 export declare const DEFAULT_OWNER: { name: string; url: string };
 export declare const bundledTemplate: FooterTemplate;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/footer",
-  "version": "0.2.6",
+  "version": "0.3.1",
   "type": "module",
   "description": "One footer for every Profullstack site: links, copyright and the << Profullstack >> webring nav with Random. Sites render the @latest template from the CDN at runtime, so a release updates every site without a redeploy.",
   "keywords": ["footer", "webring", "openwebring", "copyright", "react", "nextjs", "hono", "ssr"],

package/src/embed.js

@@ -32,6 +32,7 @@ export async function mount(root = document) {
       since: d.since ? Number(d.since) : undefined,
       links: parse(d.links),
       owner: parse(d.owner),
+      badges: parse(d.badges),
     });
     const tpl = document.createElement('template');
     tpl.innerHTML = html;

package/src/index.js

@@ -18,6 +18,9 @@ export {
   renderFooter,
   ringLinks,
   sanitizeTemplate,
+  siteBadges,
+  SUBSCRIBE_URL,
+  subscribeForm,
 } from './render.js';
 export { bundled as bundledTemplate };
 

package/src/render.js

@@ -10,6 +10,11 @@ export const DEFAULT_RING = {
 
 export const DEFAULT_OWNER = { name: 'Profullstack, Inc.', url: 'https://profullstack.com/' };
 
+// The one newsletter endpoint for every Profullstack property (double opt-in, keeps the site's host).
+// Fixed here, never taken from the template: a CDN template cannot carry a <form> (sanitizeTemplate
+// strips them), so it can only say WHERE the form goes ({{{subscribe}}}), not where it posts.
+export const SUBSCRIBE_URL = 'https://pit.world/subscribe';
+
 const ESC = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
 
 /** @param {unknown} value */
@@ -48,6 +53,47 @@ export function ringLinks(site, ring = {}) {
   };
 }
 
+/**
+ * The low-profile newsletter form: plain HTML, works with no script, posts the site's hostname so the
+ * signup records which property it came from. The endpoint answers with a "check your inbox" page and
+ * a link back here.
+ * @param {string} site
+ */
+export function subscribeForm(site) {
+  const host = new URL(canonicalSite(site)).hostname;
+  return (
+    `<form class="pfs-footer__sub" action="${SUBSCRIBE_URL}" method="post">` +
+    `<input type="hidden" name="site" value="${escapeHtml(host)}">` +
+    '<input class="pfs-footer__hp" name="website" type="text" tabindex="-1" autocomplete="off" aria-hidden="true">' +
+    '<input type="email" name="email" required maxlength="254" autocomplete="email" placeholder="Email for our newsletter" aria-label="Email address for the Profullstack newsletter">' +
+    '<button type="submit">Subscribe</button>' +
+    '</form>'
+  );
+}
+
+const SAFE_URL = /^\s*(https?:\/\/|\/(?!\/))/i;
+
+/**
+ * Badges only this site shows, after the house badges: an image link each. Only http(s) or
+ * root-relative URLs; anything else is dropped.
+ * @param {FooterBadge[] | undefined} badges
+ */
+export function siteBadges(badges) {
+  return (badges ?? [])
+    .filter((b) => b && b.href && b.src && SAFE_URL.test(b.href) && SAFE_URL.test(b.src))
+    .map((b) => {
+      const size = ['width', 'height']
+        .filter((k) => Number.isFinite(Number(b[k])) && Number(b[k]) > 0)
+        .map((k) => ` ${k}="${Math.round(Number(b[k]))}"`)
+        .join('');
+      return (
+        `<a class="pfs-footer__badge pfs-footer__badge--site" href="${escapeHtml(b.href)}">` +
+        `<img src="${escapeHtml(b.src)}" alt="${escapeHtml(b.alt ?? '')}"${size} loading="lazy"></a>`
+      );
+    })
+    .join('');
+}
+
 /** @param {number} since @param {number} year */
 export function years(since, year) {
   return since && since < year ? `${since}–${year}` : String(year);
@@ -98,6 +144,7 @@ export function fill(tpl, vars) {
 
 /**
  * @typedef {{ label: string, href: string, rel?: string }} FooterLink
+ * @typedef {{ href: string, src: string, alt: string, width?: number, height?: number }} FooterBadge
  * @typedef {{
  *   site: string,
  *   name?: string,
@@ -110,6 +157,8 @@ export function fill(tpl, vars) {
  *   css?: boolean,
  *   houseLinks?: boolean,
  *   nonce?: string,
+ *   subscribe?: boolean,
+ *   badges?: FooterBadge[],
  * }} FooterOptions
  * @typedef {{ version: string, renderer: number, css: string, link: string, footer: string, houseLinks?: FooterLink[] }} FooterTemplate
  */
@@ -143,6 +192,8 @@ export function renderFooter(template, opts) {
     site: canonicalSite(opts.site),
     name: opts.name ?? '',
     nonce: opts.nonce ?? '',
+    subscribe: opts.subscribe === false ? '' : subscribeForm(opts.site),
+    badges: siteBadges(opts.badges),
   });
 }
 

package/src/template.js

@@ -9,7 +9,7 @@
 // render.js does not fill; older installs then keep their bundled template.
 
 export default {
-  version: '0.2.6',
+  version: '0.3.1',
   renderer: 1,
   css: [
     '.pfs-footer{--pfs-footer-muted:color-mix(in srgb,currentColor 62%,transparent);--pfs-footer-gap:.5rem 1.25rem;--pfs-footer-size:.875rem;',
@@ -22,6 +22,16 @@ export default {
     '.pfs-footer__badges{display:flex;flex-wrap:wrap;justify-content:center;align-items:center;gap:.6rem}',
     '.pfs-footer a.pfs-footer__badge{display:inline-block;line-height:0}',
     '.pfs-footer__badge img{display:block;width:200px;height:44px;max-width:100%}',
+    '.pfs-footer__badge--site img{width:auto;height:auto}',
+    '.pfs-footer__news{display:flex;justify-content:center}',
+    '.pfs-footer__sub{display:flex;align-items:center;gap:.35rem;margin:0;flex-wrap:wrap;justify-content:center}',
+    '.pfs-footer__sub input[type=email]{font:inherit;font-size:.8125rem;color:inherit;background:transparent;width:13.5rem;max-width:62vw;padding:.2rem .5rem;border:1px solid color-mix(in srgb,currentColor 25%,transparent);border-radius:.35rem}',
+    '.pfs-footer__sub input[type=email]::placeholder{color:var(--pfs-footer-muted);opacity:1}',
+    '.pfs-footer__sub input[type=email]:focus-visible{outline:2px solid color-mix(in srgb,currentColor 45%,transparent);outline-offset:1px}',
+    '.pfs-footer__sub button{font:inherit;font-size:.8125rem;color:var(--pfs-footer-muted);background:transparent;padding:.2rem .6rem;border:1px solid color-mix(in srgb,currentColor 25%,transparent);border-radius:.35rem;cursor:pointer}',
+    '.pfs-footer__sub button:hover,.pfs-footer__sub button:focus-visible{color:inherit}',
+    '.pfs-footer__hp{position:absolute!important;left:-9999px!important;width:1px;height:1px;opacity:0}',
+    '.pfs-footer__sub+.pfs-footer__sublink{display:none}',
     '.pfs-footer__copy{margin:0;color:var(--pfs-footer-muted)}',
     '.pfs-footer__copy a{color:inherit}',
   ].join(''),
@@ -36,9 +46,14 @@ export default {
     '<a href="{{ring}}">{{ring_name}}</a>',
     '<a href="{{next}}" rel="next" title="Next site">&gt;&gt;</a>',
     '</nav>',
+    // The newsletter form comes from render.js ({{{subscribe}}}). Installs older than 0.3.0 cannot render
+    // it and show the plain link instead; when the form is there, CSS hides the link.
+    '<div class="pfs-footer__news">{{{subscribe}}}<a class="pfs-footer__sublink" href="https://pit.world/subscribe?site={{site}}">Newsletter</a></div>',
     '<div class="pfs-footer__badges">',
     '<a class="pfs-footer__badge" href="https://built.indie.pit.world/for?site={{site}}"><img src="https://built.indie.pit.world/for.svg?site={{site}}" alt="Listed on built.indie" width="200" height="44" loading="lazy"></a>',
     '<a class="pfs-footer__badge pfs-footer__badge--pwamart" href="https://pwamart.com/for?site={{site}}"><img src="https://pwamart.com/for.svg?site={{site}}" alt="Get it on pwamart" width="200" height="44" loading="lazy"></a>',
+    // Per-site badges (the `badges` option, e.g. a game's Foundplay badge), built and escaped by render.js.
+    '{{{badges}}}',
     '</div>',
     '<p class="pfs-footer__copy">&copy; {{years}} <a href="{{owner_url}}">{{owner_name}}</a>{{#tagline}} &middot; {{tagline}}{{/tagline}}</p>',
     '</div>',

package/template.json

@@ -1,8 +1,8 @@
 {
-  "version": "0.2.6",
+  "version": "0.3.1",
   "renderer": 1,
-  "css": ".pfs-footer{--pfs-footer-muted:color-mix(in srgb,currentColor 62%,transparent);--pfs-footer-gap:.5rem 1.25rem;--pfs-footer-size:.875rem;border-top:1px solid color-mix(in srgb,currentColor 14%,transparent);font-size:var(--pfs-footer-size);line-height:1.5;color:inherit}.pfs-footer__inner{max-width:72rem;margin:0 auto;padding:1.5rem 1rem;display:flex;flex-direction:column;align-items:center;gap:.75rem;text-align:center}.pfs-footer a{color:var(--pfs-footer-muted);text-decoration:none}.pfs-footer a:hover,.pfs-footer a:focus-visible{color:inherit;text-decoration:underline}.pfs-footer__links{display:flex;flex-wrap:wrap;justify-content:center;gap:var(--pfs-footer-gap)}.pfs-footer__ring{display:flex;flex-wrap:wrap;justify-content:center;align-items:center;gap:.6rem}.pfs-footer__badges{display:flex;flex-wrap:wrap;justify-content:center;align-items:center;gap:.6rem}.pfs-footer a.pfs-footer__badge{display:inline-block;line-height:0}.pfs-footer__badge img{display:block;width:200px;height:44px;max-width:100%}.pfs-footer__copy{margin:0;color:var(--pfs-footer-muted)}.pfs-footer__copy a{color:inherit}",
+  "css": ".pfs-footer{--pfs-footer-muted:color-mix(in srgb,currentColor 62%,transparent);--pfs-footer-gap:.5rem 1.25rem;--pfs-footer-size:.875rem;border-top:1px solid color-mix(in srgb,currentColor 14%,transparent);font-size:var(--pfs-footer-size);line-height:1.5;color:inherit}.pfs-footer__inner{max-width:72rem;margin:0 auto;padding:1.5rem 1rem;display:flex;flex-direction:column;align-items:center;gap:.75rem;text-align:center}.pfs-footer a{color:var(--pfs-footer-muted);text-decoration:none}.pfs-footer a:hover,.pfs-footer a:focus-visible{color:inherit;text-decoration:underline}.pfs-footer__links{display:flex;flex-wrap:wrap;justify-content:center;gap:var(--pfs-footer-gap)}.pfs-footer__ring{display:flex;flex-wrap:wrap;justify-content:center;align-items:center;gap:.6rem}.pfs-footer__badges{display:flex;flex-wrap:wrap;justify-content:center;align-items:center;gap:.6rem}.pfs-footer a.pfs-footer__badge{display:inline-block;line-height:0}.pfs-footer__badge img{display:block;width:200px;height:44px;max-width:100%}.pfs-footer__badge--site img{width:auto;height:auto}.pfs-footer__news{display:flex;justify-content:center}.pfs-footer__sub{display:flex;align-items:center;gap:.35rem;margin:0;flex-wrap:wrap;justify-content:center}.pfs-footer__sub input[type=email]{font:inherit;font-size:.8125rem;color:inherit;background:transparent;width:13.5rem;max-width:62vw;padding:.2rem .5rem;border:1px solid color-mix(in srgb,currentColor 25%,transparent);border-radius:.35rem}.pfs-footer__sub input[type=email]::placeholder{color:var(--pfs-footer-muted);opacity:1}.pfs-footer__sub input[type=email]:focus-visible{outline:2px solid color-mix(in srgb,currentColor 45%,transparent);outline-offset:1px}.pfs-footer__sub button{font:inherit;font-size:.8125rem;color:var(--pfs-footer-muted);background:transparent;padding:.2rem .6rem;border:1px solid color-mix(in srgb,currentColor 25%,transparent);border-radius:.35rem;cursor:pointer}.pfs-footer__sub button:hover,.pfs-footer__sub button:focus-visible{color:inherit}.pfs-footer__hp{position:absolute!important;left:-9999px!important;width:1px;height:1px;opacity:0}.pfs-footer__sub+.pfs-footer__sublink{display:none}.pfs-footer__copy{margin:0;color:var(--pfs-footer-muted)}.pfs-footer__copy a{color:inherit}",
   "link": "<a href=\"{{href}}\"{{#rel}} rel=\"{{rel}}\"{{/rel}}>{{label}}</a>",
-  "footer": "<footer class=\"pfs-footer\" data-pfs-footer=\"{{version}}\">{{#css}}<style{{#nonce}} nonce=\"{{nonce}}\"{{/nonce}}>{{{css}}}</style>{{/css}}<div class=\"pfs-footer__inner\">{{#links}}<nav class=\"pfs-footer__links\" aria-label=\"Footer\">{{{links}}}</nav>{{/links}}<nav class=\"webring pfs-footer__ring\" aria-label=\"{{ring_name}} webring\"><a href=\"{{previous}}\" rel=\"prev\" title=\"Previous site\">&lt;&lt;</a><a href=\"{{ring}}\">{{ring_name}}</a><a href=\"{{next}}\" rel=\"next\" title=\"Next site\">&gt;&gt;</a></nav><div class=\"pfs-footer__badges\"><a class=\"pfs-footer__badge\" href=\"https://built.indie.pit.world/for?site={{site}}\"><img src=\"https://built.indie.pit.world/for.svg?site={{site}}\" alt=\"Listed on built.indie\" width=\"200\" height=\"44\" loading=\"lazy\"></a><a class=\"pfs-footer__badge pfs-footer__badge--pwamart\" href=\"https://pwamart.com/for?site={{site}}\"><img src=\"https://pwamart.com/for.svg?site={{site}}\" alt=\"Get it on pwamart\" width=\"200\" height=\"44\" loading=\"lazy\"></a></div><p class=\"pfs-footer__copy\">&copy; {{years}} <a href=\"{{owner_url}}\">{{owner_name}}</a>{{#tagline}} &middot; {{tagline}}{{/tagline}}</p></div></footer>",
+  "footer": "<footer class=\"pfs-footer\" data-pfs-footer=\"{{version}}\">{{#css}}<style{{#nonce}} nonce=\"{{nonce}}\"{{/nonce}}>{{{css}}}</style>{{/css}}<div class=\"pfs-footer__inner\">{{#links}}<nav class=\"pfs-footer__links\" aria-label=\"Footer\">{{{links}}}</nav>{{/links}}<nav class=\"webring pfs-footer__ring\" aria-label=\"{{ring_name}} webring\"><a href=\"{{previous}}\" rel=\"prev\" title=\"Previous site\">&lt;&lt;</a><a href=\"{{ring}}\">{{ring_name}}</a><a href=\"{{next}}\" rel=\"next\" title=\"Next site\">&gt;&gt;</a></nav><div class=\"pfs-footer__news\">{{{subscribe}}}<a class=\"pfs-footer__sublink\" href=\"https://pit.world/subscribe?site={{site}}\">Newsletter</a></div><div class=\"pfs-footer__badges\"><a class=\"pfs-footer__badge\" href=\"https://built.indie.pit.world/for?site={{site}}\"><img src=\"https://built.indie.pit.world/for.svg?site={{site}}\" alt=\"Listed on built.indie\" width=\"200\" height=\"44\" loading=\"lazy\"></a><a class=\"pfs-footer__badge pfs-footer__badge--pwamart\" href=\"https://pwamart.com/for?site={{site}}\"><img src=\"https://pwamart.com/for.svg?site={{site}}\" alt=\"Get it on pwamart\" width=\"200\" height=\"44\" loading=\"lazy\"></a>{{{badges}}}</div><p class=\"pfs-footer__copy\">&copy; {{years}} <a href=\"{{owner_url}}\">{{owner_name}}</a>{{#tagline}} &middot; {{tagline}}{{/tagline}}</p></div></footer>",
   "houseLinks": []
 }