@sapphirelabs/blog-cms-next 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sapphire Labs
+
+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

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# @sapphirelabs/blog-cms-next
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Sapphire Blog CMS](https://github.com/sapphire-labs-dev/sapphire-blog-cms) for Next.js (App Router):
+a CMS panel at `/admin`, helpers to load your Markdown posts, and a component that renders them safely.
+
+```bash
+npm install @sapphirelabs/blog-cms-next
+```
+
+```ts
+// app/admin/route.ts
+import { createAdminRoute } from '@sapphirelabs/blog-cms-next/admin';
+
+export const { GET } = createAdminRoute({
+  scriptUrl: 'https://unpkg.com/@sapphirelabs/blog-cms@0.1.0/dist/sapphire-cms.js',
+});
+export const dynamic = 'force-static';
+```
+
+```tsx
+// app/blog/[slug]/page.tsx
+import { notFound } from 'next/navigation';
+import { getPost, getSlugs, SapphireContent } from '@sapphirelabs/blog-cms-next';
+
+export async function generateStaticParams() {
+  return (await getSlugs('content/blog')).map((slug) => ({ slug }));
+}
+
+export default async function Post({ params }: { params: Promise<{ slug: string }> }) {
+  const post = await getPost('content/blog', (await params).slug);
+  if (!post) notFound();
+
+  return <SapphireContent source={post.body} />;
+}
+```
+
+```tsx
+// app/layout.tsx
+import '@sapphirelabs/blog-cms-next/prose.css';
+```
+
+- `getPosts(folder)`: every post, newest first; `draft: true` posts are hidden in production.
+- `getPost(folder, slug)`: one post, or `null`.
+- `<SapphireContent source>`: renders Markdown plus the HTML the editor writes (color, underline,
+  alignment, tables, YouTube) and strips anything that could run code. `allowUnsafeHtml` turns that off.
+
+Full setup and the `config.yml` reference:
+[getting started](https://github.com/sapphire-labs-dev/sapphire-blog-cms/blob/main/docs/getting-started.md).
+
+## License
+
+MIT

package/dist/SapphireContent.d.ts

@@ -0,0 +1,18 @@
+export interface SapphireContentProps {
+    /** The post text (the `body` from `getPost`). */
+    source: string;
+    /** Class of the wrapping element. Default: `sapphire-prose`, the theme in `@sapphirelabs/blog-cms-next/prose.css`. */
+    className?: string;
+    as?: 'article' | 'div' | 'section';
+    /**
+     * Skips HTML sanitizing. Only turn this on if every editor is fully trusted and your posts need
+     * HTML beyond what the editor produces (scripts, forms, custom embeds).
+     */
+    allowUnsafeHtml?: boolean;
+}
+/**
+ * Renders text saved by Sapphire Blog CMS. Besides Markdown, it accepts the HTML the editor writes
+ * for color, underline, highlight, alignment, tables and YouTube videos. Anything else that could run
+ * code (scripts, event handlers, other iframes) is removed, unless `allowUnsafeHtml` is set.
+ */
+export declare function SapphireContent({ source, className, as: Tag, allowUnsafeHtml }: SapphireContentProps): import("react").JSX.Element;

package/dist/SapphireContent.js

@@ -0,0 +1,64 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import Markdown from 'react-markdown';
+import rehypeRaw from 'rehype-raw';
+import rehypeSanitize, { defaultSchema } from 'rehype-sanitize';
+import remarkGfm from 'remark-gfm';
+/** The HTML the editor writes, on top of the standard safe Markdown subset. */
+const schema = {
+    ...defaultSchema,
+    tagNames: [...(defaultSchema.tagNames ?? []), 'u', 'mark', 'iframe', 'figure', 'figcaption'],
+    attributes: {
+        ...defaultSchema.attributes,
+        '*': [...(defaultSchema.attributes?.['*'] ?? []), 'style', 'className'],
+        mark: ['dataColor'],
+        div: ['dataYoutubeVideo'],
+        iframe: ['src', 'width', 'height', 'title', 'allowFullScreen', 'allow', 'loading'],
+    },
+};
+const ALLOWED_STYLES = new Set(['color', 'background-color', 'text-align']);
+const YOUTUBE_EMBED = /^https:\/\/(www\.)?(youtube\.com|youtube-nocookie\.com)\/embed\//;
+/** Keeps only the style properties the editor uses (no url(), no layout tricks). */
+function cleanStyle(style) {
+    return style
+        .split(';')
+        .map((part) => part.split(':').map((s) => s.trim()))
+        .filter(([prop, value]) => prop && value && ALLOWED_STYLES.has(prop.toLowerCase()) && /^[#\w\s(),.%-]+$/.test(value) && !/url|expression/i.test(value))
+        .map(([prop, value]) => `${prop.toLowerCase()}: ${value}`)
+        .join('; ');
+}
+/** Drops iframes that are not YouTube embeds and trims inline styles. */
+function rehypeSapphireEmbeds() {
+    const walk = (node) => {
+        if (!node.children) {
+            return;
+        }
+        node.children = node.children.filter((child) => {
+            if (child.type !== 'element') {
+                return true;
+            }
+            if (child.tagName === 'iframe' && !YOUTUBE_EMBED.test(String(child.properties?.src ?? ''))) {
+                return false;
+            }
+            if (typeof child.properties?.style === 'string') {
+                const style = cleanStyle(child.properties.style);
+                if (style) {
+                    child.properties.style = style;
+                }
+                else {
+                    delete child.properties.style;
+                }
+            }
+            walk(child);
+            return true;
+        });
+    };
+    return (tree) => walk(tree);
+}
+/**
+ * Renders text saved by Sapphire Blog CMS. Besides Markdown, it accepts the HTML the editor writes
+ * for color, underline, highlight, alignment, tables and YouTube videos. Anything else that could run
+ * code (scripts, event handlers, other iframes) is removed, unless `allowUnsafeHtml` is set.
+ */
+export function SapphireContent({ source, className = 'sapphire-prose', as: Tag = 'article', allowUnsafeHtml = false }) {
+    return (_jsx(Tag, { className: className, children: _jsx(Markdown, { remarkPlugins: [remarkGfm], rehypePlugins: allowUnsafeHtml ? [rehypeRaw] : [rehypeRaw, [rehypeSanitize, schema], rehypeSapphireEmbeds], children: source }) }));
+}

package/dist/admin.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CMS panel page for the App Router. In `app/admin/route.ts`:
+ *
+ *   import { createAdminRoute } from '@sapphirelabs/blog-cms-next/admin';
+ *   export const { GET } = createAdminRoute();
+ *   export const dynamic = 'force-static';
+ *
+ * Without `config`, the panel reads `public/admin/config.yml`.
+ */
+export declare const DEFAULT_SCRIPT_URL = "https://unpkg.com/@sapphirelabs/blog-cms/dist/sapphire-cms.js";
+export interface AdminOptions {
+    /** URL of `sapphire-cms.js`. Default: the latest version on unpkg. */
+    scriptUrl?: string;
+    /** Configuration instead of `config.yml`, in the same format. */
+    config?: Record<string, unknown>;
+    /** Browser tab title. */
+    title?: string;
+}
+export declare function adminHtml({ scriptUrl, config, title }?: AdminOptions): string;
+export declare function createAdminRoute(options?: AdminOptions): {
+    GET: () => Response;
+};

package/dist/admin.js

@@ -0,0 +1,39 @@
+/**
+ * CMS panel page for the App Router. In `app/admin/route.ts`:
+ *
+ *   import { createAdminRoute } from '@sapphirelabs/blog-cms-next/admin';
+ *   export const { GET } = createAdminRoute();
+ *   export const dynamic = 'force-static';
+ *
+ * Without `config`, the panel reads `public/admin/config.yml`.
+ */
+export const DEFAULT_SCRIPT_URL = 'https://unpkg.com/@sapphirelabs/blog-cms/dist/sapphire-cms.js';
+const escapeHtml = (value) => value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+export function adminHtml({ scriptUrl = DEFAULT_SCRIPT_URL, config, title } = {}) {
+    const pageTitle = title ?? (typeof config?.site_title === 'string' ? config.site_title : 'Content Manager');
+    const inline = config
+        ? `<script>window.SAPPHIRE_CMS_CONFIG = ${JSON.stringify(config).replace(/</g, '\\u003c')};</script>`
+        : '';
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex, nofollow" />
+    <title>${escapeHtml(pageTitle)}</title>
+    <style>body { margin: 0; }</style>
+    ${inline}
+    <script src="${escapeHtml(scriptUrl)}"></script>
+  </head>
+  <body></body>
+</html>
+`;
+}
+export function createAdminRoute(options = {}) {
+    const html = adminHtml(options);
+    return {
+        GET: () => new Response(html, {
+            headers: { 'Content-Type': 'text/html; charset=utf-8', 'X-Robots-Tag': 'noindex' },
+        }),
+    };
+}

package/dist/content.d.ts

@@ -0,0 +1,29 @@
+/** A collection file: the front matter fields in `data` and the text in `body`. */
+export interface Post<T = Record<string, unknown>> {
+    slug: string;
+    data: T;
+    body: string;
+}
+export interface ReadOptions {
+    /**
+     * Include posts with `draft: true`. Default: only outside production, so drafts show up in
+     * `next dev` and never on the published site.
+     */
+    drafts?: boolean;
+    /** File extensions to read. Default: md and markdown. */
+    extensions?: string[];
+}
+/** Splits the front matter (YAML between `---`) from the text. */
+export declare function parseMarkdown<T = Record<string, unknown>>(text: string): {
+    data: T;
+    body: string;
+};
+/**
+ * Reads every post in a folder, newest first (by the `pubDate`, `date` or `publishDate` field).
+ * The folder is relative to the project root, e.g. `content/blog`.
+ */
+export declare function getPosts<T = Record<string, unknown>>(folder: string, options?: ReadOptions): Promise<Post<T>[]>;
+/** Post slugs (the file name without extension). Handy for `generateStaticParams`. */
+export declare function getSlugs(folder: string, options?: ReadOptions): Promise<string[]>;
+/** Reads one post by slug. Returns `null` if it does not exist (or is a draft in production). */
+export declare function getPost<T = Record<string, unknown>>(folder: string, slug: string, options?: ReadOptions): Promise<Post<T> | null>;

package/dist/content.js

@@ -0,0 +1,68 @@
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import YAML from 'yaml';
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+const DATE_FIELDS = ['pubDate', 'date', 'publishDate', 'published_at'];
+const SAFE_SLUG = /^[\w][\w.-]*$/;
+/** Splits the front matter (YAML between `---`) from the text. */
+export function parseMarkdown(text) {
+    const match = text.match(FRONTMATTER);
+    if (!match) {
+        return { data: {}, body: text };
+    }
+    return {
+        data: (YAML.parse(match[1]) ?? {}),
+        body: text.slice(match[0].length).replace(/^\r?\n/, ''),
+    };
+}
+const showDrafts = (options) => options.drafts ?? process.env.NODE_ENV !== 'production';
+const extensionsOf = (options) => options.extensions ?? ['md', 'markdown'];
+const resolve = (folder) => path.resolve(process.cwd(), folder);
+const isDraft = (data) => data?.draft === true;
+function dateOf(data) {
+    for (const field of DATE_FIELDS) {
+        const value = data?.[field];
+        const time = value instanceof Date ? value.getTime() : typeof value === 'string' ? Date.parse(value) : NaN;
+        if (!Number.isNaN(time)) {
+            return time;
+        }
+    }
+    return 0;
+}
+/**
+ * Reads every post in a folder, newest first (by the `pubDate`, `date` or `publishDate` field).
+ * The folder is relative to the project root, e.g. `content/blog`.
+ */
+export async function getPosts(folder, options = {}) {
+    const extensions = extensionsOf(options);
+    const names = (await readdir(resolve(folder))).filter((name) => extensions.includes(path.extname(name).slice(1)));
+    const posts = await Promise.all(names.map(async (name) => {
+        const { data, body } = parseMarkdown(await readFile(path.join(resolve(folder), name), 'utf8'));
+        return { slug: name.slice(0, -path.extname(name).length), data, body };
+    }));
+    return posts
+        .filter((post) => showDrafts(options) || !isDraft(post.data))
+        .sort((a, b) => dateOf(b.data) - dateOf(a.data) || a.slug.localeCompare(b.slug));
+}
+/** Post slugs (the file name without extension). Handy for `generateStaticParams`. */
+export async function getSlugs(folder, options = {}) {
+    return (await getPosts(folder, options)).map((post) => post.slug);
+}
+/** Reads one post by slug. Returns `null` if it does not exist (or is a draft in production). */
+export async function getPost(folder, slug, options = {}) {
+    if (!SAFE_SLUG.test(slug)) {
+        return null;
+    }
+    for (const extension of extensionsOf(options)) {
+        let text;
+        try {
+            text = await readFile(path.join(resolve(folder), `${slug}.${extension}`), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const { data, body } = parseMarkdown(text);
+        return !showDrafts(options) && isDraft(data) ? null : { slug, data, body };
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { getPost, getPosts, getSlugs, parseMarkdown, type Post, type ReadOptions } from './content.js';
+export { SapphireContent, type SapphireContentProps } from './SapphireContent.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { getPost, getPosts, getSlugs, parseMarkdown } from './content.js';
+export { SapphireContent } from './SapphireContent.js';

package/dist/prose.css

@@ -0,0 +1,250 @@
+/*
+ * Sapphire Blog CMS — reading theme for posts.
+ *
+ * Usage: wrap the post text in <article class="sapphire-prose">…</article>.
+ * Works even with Tailwind's reset (preflight), which strips headings, lists and tables.
+ * Everything is inside :where(), so any site rule wins without needing !important.
+ *
+ * To match your site, override the variables:
+ *   .sapphire-prose { --sp-accent: #b5651d; --sp-font: Georgia, serif; }
+ * Colors derive from the text color (currentColor), so dark mode works on its own.
+ */
+
+:where(.sapphire-prose) {
+  --sp-font: inherit;
+  --sp-heading-font: inherit;
+  --sp-mono-font: ui-monospace, 'Cascadia Code', 'SFMono-Regular', Menlo, Consolas, monospace;
+  --sp-size: 1.0625rem;
+  --sp-leading: 1.75;
+  --sp-measure: 70ch;
+  --sp-accent: #1f4fe0;
+  --sp-muted: color-mix(in srgb, currentColor 68%, transparent);
+  --sp-border: color-mix(in srgb, currentColor 16%, transparent);
+  --sp-soft: color-mix(in srgb, currentColor 6%, transparent);
+  --sp-radius: 8px;
+
+  max-width: var(--sp-measure);
+  font-family: var(--sp-font);
+  font-size: var(--sp-size);
+  line-height: var(--sp-leading);
+  overflow-wrap: break-word;
+}
+
+:where(.sapphire-prose) > :first-child {
+  margin-top: 0;
+}
+
+:where(.sapphire-prose) > :last-child {
+  margin-bottom: 0;
+}
+
+:where(.sapphire-prose) :where(p, ul, ol, blockquote, pre, table, figure) {
+  margin: 1.1em 0;
+}
+
+/* Headings */
+
+:where(.sapphire-prose) :where(h1, h2, h3, h4, h5, h6) {
+  margin: 1.8em 0 0.6em;
+  font-family: var(--sp-heading-font);
+  font-weight: 700;
+  line-height: 1.25;
+  letter-spacing: -0.01em;
+  text-wrap: balance;
+}
+
+:where(.sapphire-prose) h1 {
+  font-size: 2.1em;
+}
+
+:where(.sapphire-prose) h2 {
+  font-size: 1.55em;
+}
+
+:where(.sapphire-prose) h3 {
+  font-size: 1.25em;
+}
+
+:where(.sapphire-prose) :where(h4, h5, h6) {
+  font-size: 1.05em;
+}
+
+:where(.sapphire-prose) :where(h1, h2, h3, h4, h5, h6) + * {
+  margin-top: 0;
+}
+
+/* Text */
+
+:where(.sapphire-prose) a {
+  color: var(--sp-accent);
+  text-decoration: underline;
+  text-decoration-thickness: 1px;
+  text-underline-offset: 3px;
+}
+
+:where(.sapphire-prose) a:hover {
+  text-decoration-thickness: 2px;
+}
+
+:where(.sapphire-prose) :where(strong, b) {
+  font-weight: 700;
+}
+
+:where(.sapphire-prose) :where(em, i) {
+  font-style: italic;
+}
+
+:where(.sapphire-prose) u {
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+
+:where(.sapphire-prose) :where(s, del) {
+  text-decoration: line-through;
+}
+
+/* Highlight: the color comes from the editor (style="background-color: …"). */
+:where(.sapphire-prose) mark {
+  padding: 0.05em 0.2em;
+  border-radius: 3px;
+  background-color: #fef08a;
+  color: inherit;
+  box-decoration-break: clone;
+  -webkit-box-decoration-break: clone;
+}
+
+/* Lists */
+
+:where(.sapphire-prose) ul {
+  padding-left: 1.5em;
+  list-style: disc;
+}
+
+:where(.sapphire-prose) ol {
+  padding-left: 1.6em;
+  list-style: decimal;
+}
+
+:where(.sapphire-prose) :where(ul ul) {
+  list-style: circle;
+}
+
+:where(.sapphire-prose) li {
+  margin: 0.35em 0;
+  padding-left: 0.25em;
+}
+
+:where(.sapphire-prose) li > :where(p) {
+  margin: 0.35em 0;
+}
+
+:where(.sapphire-prose) li > :where(ul, ol) {
+  margin: 0.35em 0;
+}
+
+:where(.sapphire-prose) li::marker {
+  color: var(--sp-muted);
+}
+
+/* Quote */
+
+:where(.sapphire-prose) blockquote {
+  padding: 0.2em 0 0.2em 1.1em;
+  border-left: 3px solid var(--sp-accent);
+  color: var(--sp-muted);
+  font-style: italic;
+}
+
+/* Images and videos */
+
+:where(.sapphire-prose) img {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  margin: 1.6em auto;
+  border-radius: var(--sp-radius);
+}
+
+:where(.sapphire-prose) figure img {
+  margin-bottom: 0.5em;
+}
+
+:where(.sapphire-prose) figcaption {
+  color: var(--sp-muted);
+  font-size: 0.875em;
+  text-align: center;
+}
+
+:where(.sapphire-prose) :where(iframe, video) {
+  display: block;
+  width: 100%;
+  max-width: 100%;
+  height: auto;
+  aspect-ratio: 16 / 9;
+  margin: 1.6em auto;
+  border: 0;
+  border-radius: var(--sp-radius);
+}
+
+/* Code */
+
+:where(.sapphire-prose) code {
+  padding: 0.15em 0.35em;
+  border-radius: 5px;
+  background: var(--sp-soft);
+  font-family: var(--sp-mono-font);
+  font-size: 0.875em;
+}
+
+:where(.sapphire-prose) pre {
+  padding: 1em 1.2em;
+  overflow-x: auto;
+  border: 1px solid var(--sp-border);
+  border-radius: var(--sp-radius);
+  background: var(--sp-soft);
+  font-size: 0.875em;
+  line-height: 1.6;
+}
+
+:where(.sapphire-prose) pre code {
+  padding: 0;
+  background: none;
+  font-size: inherit;
+}
+
+/* Divider */
+
+:where(.sapphire-prose) hr {
+  height: 0;
+  margin: 2.5em 0;
+  border: 0;
+  border-top: 1px solid var(--sp-border);
+}
+
+/* Tables: scroll horizontally on phones instead of overflowing the page. */
+
+:where(.sapphire-prose) table {
+  display: block;
+  width: max-content;
+  max-width: 100%;
+  overflow-x: auto;
+  border-collapse: collapse;
+  font-size: 0.95em;
+}
+
+:where(.sapphire-prose) :where(th, td) {
+  padding: 0.55em 0.9em;
+  border: 1px solid var(--sp-border);
+  text-align: left;
+  vertical-align: top;
+}
+
+:where(.sapphire-prose) th {
+  background: var(--sp-soft);
+  font-weight: 600;
+}
+
+/* Editor protected block (HTML it does not edit): shown as written. */
+:where(.sapphire-prose) :where(div, section, aside) {
+  max-width: 100%;
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@sapphirelabs/blog-cms-next",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Sapphire Blog CMS for Next.js: CMS panel at /admin, post loading helpers and a component that renders the text.",
+  "license": "MIT",
+  "author": "Sapphire Labs (https://github.com/sapphire-labs-dev)",
+  "homepage": "https://github.com/sapphire-labs-dev/sapphire-blog-cms#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sapphire-labs-dev/sapphire-blog-cms.git",
+    "directory": "packages/next"
+  },
+  "bugs": "https://github.com/sapphire-labs-dev/sapphire-blog-cms/issues",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./admin": "./dist/admin.js",
+    "./prose.css": "./dist/prose.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "nextjs",
+    "cms",
+    "markdown"
+  ],
+  "peerDependencies": {
+    "next": ">=14",
+    "react": ">=18"
+  },
+  "dependencies": {
+    "react-markdown": "^10.1.0",
+    "rehype-raw": "^7.0.0",
+    "rehype-sanitize": "^6.0.0",
+    "remark-gfm": "^4.0.1",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "@types/react": "^19.3.0",
+    "next": "^16.4.6",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p . && node -e \"require('node:fs').copyFileSync('../app/public/prose.css', 'dist/prose.css')\"",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p ."
+  }
 }