sponsor-block-renderer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Himpfen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# sponsor-block-renderer
+
+Render lightweight sponsor sections for websites, newsletters, and content workflows.
+
+`sponsor-block-renderer` helps you define sponsor content once and render it into simple HTML blocks. It is designed for creators, publishers, and developers who want a minimal and repeatable way to output sponsor sections without hardcoding HTML in multiple places.
+
+## Why this project exists
+
+Sponsor content is often handled inconsistently.
+
+One page may use a hand-written HTML block. Another may embed a slightly different variation in a template. A newsletter workflow may use an entirely separate rendering path. Over time, this creates duplication, formatting drift, and more effort when sponsor content needs to be updated.
+
+This project provides a small rendering layer that standardizes sponsor blocks while staying easy to understand and integrate.
+
+## Mental model
+
+Think of the package as a small publishing utility:
+
+`Structured sponsor data -> HTML block -> site, newsletter, or app`
+
+It does not replace a CMS or ad platform.
+
+It standardizes one small but useful part of a publishing workflow.
+
+## What is included
+
+- Sponsor block builder.
+- HTML renderer for single sponsor blocks.
+- HTML renderer for multiple sponsor blocks.
+- Minimal validation for common fields.
+- Example usage for content workflows.
+- Basic tests.
+
+## Install
+
+```bash
+npm install sponsor-block-renderer
+```
+
+## Example
+
+```js
+import { renderSponsorBlock } from "sponsor-block-renderer";
+
+const html = renderSponsorBlock({
+  label: "Sponsor",
+  name: "Example Sponsor",
+  description: "A simple product for thoughtful publishers.",
+  url: "https://example.com",
+  ctaText: "Visit sponsor",
+  disclosure: "Sponsored placement"
+});
+
+console.log(html);
+```
+
+## Output shape
+
+A rendered sponsor block produces simple HTML with a predictable structure.
+
+```html
+<section class="sponsor-block">
+  <p class="sponsor-block__label">Sponsor</p>
+  <h2 class="sponsor-block__title">Example Sponsor</h2>
+  <p class="sponsor-block__description">A simple product for thoughtful publishers.</p>
+  <p class="sponsor-block__disclosure">Sponsored placement</p>
+  <p class="sponsor-block__cta"><a href="https://example.com" target="_blank" rel="sponsored noopener noreferrer">Visit sponsor</a></p>
+</section>
+```
+
+## API
+
+### `createSponsorBlock(input)`
+
+Normalizes sponsor input and validates required fields.
+
+### `renderSponsorBlock(input, options)`
+
+Renders a single sponsor block as HTML.
+
+### `renderSponsorBlocks(items, options)`
+
+Renders multiple sponsor blocks separated by blank lines.
+
+## Design Principles
+
+This project is intentionally minimal.
+
+It focuses on a clear rendering path rather than a full sponsorship management platform. The goal is to keep sponsor content structured, reusable, and easy to publish.
+
+The design emphasizes:
+
+- Simplicity over abstraction.
+- Reuse over duplication.
+- Predictable output over visual opinion.
+- Easy integration over framework lock-in.
+
+## Example Use Cases
+
+This utility is useful for:
+
+- websites with recurring sponsor sections.
+- newsletter generation workflows.
+- static site generators.
+- content systems that separate data from presentation.
+
+## Roadmap
+
+Future extensions may include:
+
+- plain text sponsor rendering.
+- JSON export helpers.
+- optional template presets.
+- disclosure helpers for different publishing workflows.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "sponsor-block-renderer",
+  "version": "0.1.0",
+  "description": "Render lightweight sponsor sections for websites, newsletters, and content workflows.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "sponsor",
+    "sponsorship",
+    "renderer",
+    "html",
+    "newsletter",
+    "publishing",
+    "utility"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brandonhimpfen/sponsor-block-renderer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/brandonhimpfen/sponsor-block-renderer/issues"
+  },
+  "homepage": "https://github.com/brandonhimpfen/sponsor-block-renderer#readme",
+  "author": "Brandon Himpfen",
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,105 @@
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function attrsToString(attrs = {}) {
+  return Object.entries(attrs)
+    .filter(([, value]) => value !== undefined && value !== null && value !== false)
+    .map(([key, value]) => {
+      if (value === true) return ` ${key}`;
+      return ` ${key}="${escapeHtml(value)}"`;
+    })
+    .join('');
+}
+
+function normalizeSponsor(input = {}) {
+  const sponsor = {
+    label: input.label ?? 'Sponsor',
+    name: input.name ?? null,
+    description: input.description ?? null,
+    url: input.url ?? null,
+    ctaText: input.ctaText ?? 'Learn more',
+    imageUrl: input.imageUrl ?? null,
+    imageAlt: input.imageAlt ?? input.name ?? 'Sponsor image',
+    disclosure: input.disclosure ?? null,
+    meta: input.meta ?? null
+  };
+
+  if (!sponsor.name) {
+    throw new Error('Sponsor name is required.');
+  }
+
+  if (sponsor.url && !/^https?:\/\//i.test(sponsor.url)) {
+    throw new Error('Sponsor url must start with http:// or https://');
+  }
+
+  return sponsor;
+}
+
+export function createSponsorBlock(input = {}) {
+  return normalizeSponsor(input);
+}
+
+export function renderSponsorBlock(input = {}, options = {}) {
+  const sponsor = normalizeSponsor(input);
+  const {
+    className = 'sponsor-block',
+    headingLevel = 2,
+    openInNewTab = true,
+    rel = 'sponsored noopener noreferrer',
+    wrapperTag = 'section'
+  } = options;
+
+  if (!Number.isInteger(headingLevel) || headingLevel < 1 || headingLevel > 6) {
+    throw new Error('headingLevel must be an integer between 1 and 6.');
+  }
+
+  const headingTag = `h${headingLevel}`;
+  const linkAttrs = sponsor.url
+    ? attrsToString({
+        href: sponsor.url,
+        target: openInNewTab ? '_blank' : undefined,
+        rel: sponsor.url ? rel : undefined
+      })
+    : '';
+
+  const imageHtml = sponsor.imageUrl
+    ? `<div class="${escapeHtml(className)}__media"><img src="${escapeHtml(sponsor.imageUrl)}" alt="${escapeHtml(sponsor.imageAlt)}"></div>`
+    : '';
+
+  const descriptionHtml = sponsor.description
+    ? `<p class="${escapeHtml(className)}__description">${escapeHtml(sponsor.description)}</p>`
+    : '';
+
+  const disclosureHtml = sponsor.disclosure
+    ? `<p class="${escapeHtml(className)}__disclosure">${escapeHtml(sponsor.disclosure)}</p>`
+    : '';
+
+  const ctaHtml = sponsor.url
+    ? `<p class="${escapeHtml(className)}__cta"><a${linkAttrs}>${escapeHtml(sponsor.ctaText)}</a></p>`
+    : '';
+
+  return [
+    `<${wrapperTag} class="${escapeHtml(className)}">`,
+    `  <p class="${escapeHtml(className)}__label">${escapeHtml(sponsor.label)}</p>`,
+    `  <${headingTag} class="${escapeHtml(className)}__title">${escapeHtml(sponsor.name)}</${headingTag}>`,
+    imageHtml ? `  ${imageHtml}` : '',
+    descriptionHtml ? `  ${descriptionHtml}` : '',
+    disclosureHtml ? `  ${disclosureHtml}` : '',
+    ctaHtml ? `  ${ctaHtml}` : '',
+    `</${wrapperTag}>`
+  ].filter(Boolean).join('\n');
+}
+
+export function renderSponsorBlocks(items = [], options = {}) {
+  if (!Array.isArray(items)) {
+    throw new Error('items must be an array.');
+  }
+
+  return items.map((item) => renderSponsorBlock(item, options)).join('\n\n');
+}