@stacksjs/cms 0.75.134 → 0.75.136

package/dist/blog.d.ts

@@ -0,0 +1,124 @@
+/** The posts folder: `<cwd>/content/blog`. */
+export declare function blogContentDir(): string;
+/** Whether a string can name a post (letters, digits, `-`, `_`; no dots or slashes). */
+export declare function isPostSlug(slug: string): boolean;
+/**
+ * `key: value` lines between `---` fences, quotes optional. A value may
+ * contain colons; only the first one separates the key.
+ */
+export declare function parseFrontmatter(markdown: string): { data: Record<string, string>, body: string };
+/**
+ * Whether frontmatter describes a published post: a title and a date, and no
+ * `draft: true`. Files without both (a STRATEGY.md, notes) are not posts.
+ */
+export declare function isPublished(data: Record<string, string>): boolean;
+/** Whole minutes to read a markdown body at 230 words a minute, at least one. Code blocks are skipped. */
+export declare function readingMinutes(markdown: string): number;
+/**
+ * The authors a post's frontmatter names: `authors: chris, pawel` (brackets
+ * and quotes allowed), each with its `author.<username>.*` fallbacks, or the
+ * single-author keys.
+ */
+export declare function authorsOf(data: Record<string, string>): AuthorRef[];
+/** Featured first, then newest first. */
+export declare function sortPosts<T extends Pick<PostMeta, 'date' | 'featured'>>(posts: T[]): T[];
+/** Every published post, featured first and then newest first, without bodies. */
+export declare function loadPosts(options?: BlogDirOptions): PostMeta[];
+/** One published post with its body, or null for a draft, an unsafe slug or no such file. */
+export declare function loadPost(slug: unknown, options?: BlogDirOptions): Post | null;
+/**
+ * A post body as HTML: Bun's markdown parser, then `renderPostHtml`, which
+ * turns a lone image into a captioned figure, consecutive images into a grid
+ * and a bare video link into an embed. Pair it with `articleHead()` for the
+ * figure and grid styles.
+ */
+export declare function renderPostBody(markdown: string, options?: { publicDir?: string }): string;
+/** "October 11, 2026". A post date is a calendar day, so it is read as UTC. */
+export declare function formatPostDate(date: string, locale?: string): string;
+/** "CB" for "Chris Breuer", first and last word. */
+export declare function initialsOf(name: string): string;
+/** "A", "A and B", "A, B and C". */
+export declare function joinNames(names: string[]): string;
+/**
+ * Resolves bylines through the app's own profiles.
+ *
+ * Each author is looked up by username; a profile's name, initials, picture
+ * and link win, and the post's own frontmatter fills whatever it does not
+ * have. A `bio` in the frontmatter wins over the profile's, so a post can say
+ * what it means to about its writer. A lookup that throws, or answers null,
+ * leaves the frontmatter standing, without a link.
+ *
+ * Create it once at module scope so its cache outlives a render:
+ *
+ * ```ts
+ * export const resolveAuthors = createAuthorResolver({
+ *   lookup: async (username) => {
+ *     const res = await fetch(`${api}/api/u/${username}`)
+ *     const { profile } = res.ok ? await res.json() : {}
+ *     return profile ? { ...profile, url: `/${profile.username}` } : null
+ *   },
+ * })
+ * ```
+ */
+export declare function createAuthorResolver(options?: AuthorResolverOptions): AuthorResolver;
+/**
+ * The byline as a template draws it: each author with the words before their
+ * name (`''`, `', '` or `' and '`) and an inline style that paints their
+ * picture as a background. Lay that over their initials and a picture that
+ * fails to load leaves the initials showing rather than an empty circle.
+ */
+export declare function bylineOf(authors: PostAuthor[]): Array<PostAuthor & { joiner: string, avatarStyle: string }>;
+export declare interface PostMeta {
+  slug: string
+  title: string
+  date: string
+  description: string
+  author: string
+  authors: AuthorRef[]
+  image: string
+  imageAlt: string
+  featured: boolean
+  minutes: number
+  frontmatter: Record<string, string>
+}
+export declare interface Post extends PostMeta {
+  body: string
+}
+/** An author as a post's frontmatter names them. */
+export declare interface AuthorRef {
+  username: string
+  name: string
+  avatar: string
+  bio: string
+}
+/** What an app knows about an author, from its `AuthorLookup`. */
+export declare interface AuthorProfile {
+  name?: string
+  initials?: string
+  avatar?: string
+  bio?: string
+  url?: string
+}
+/** An author as a byline shows them. */
+export declare interface PostAuthor {
+  name: string
+  initials: string
+  avatar: string
+  bio: string
+  url: string
+}
+export declare interface BlogDirOptions {
+  dir?: string
+}
+export declare interface AuthorResolverOptions {
+  lookup?: AuthorLookup
+  ttlMs?: number
+  fallbackName?: string
+}
+export declare interface AuthorResolver {
+  (post: Pick<PostMeta, 'authors'>): Promise<PostAuthor[]>
+  one: (ref: AuthorRef) => Promise<PostAuthor>
+  clear: () => void
+}
+/** Finds an author by username: their profile, or null when there is none to show. */
+export type AuthorLookup = (username: string) => Promise<AuthorProfile | null | undefined> | AuthorProfile | null | undefined;

package/dist/blog.js

@@ -0,0 +1,3 @@
+import{existsSync,readdirSync,readFileSync}from"node:fs";import{join}from"node:path";import process from"node:process";import{renderPostHtml}from"./article";export function blogContentDir(){return join(process.cwd(),"content/blog")}const SLUG=/^[A-Za-z0-9][\w-]{0,199}$/,USERNAME=/^[a-z0-9][a-z0-9_-]{0,99}$/;export function isPostSlug(slug){return SLUG.test(slug)}export function parseFrontmatter(markdown){const match=markdown.replace(/\r\n/g,`
+`).match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);if(!match)return{data:{},body:markdown};const data={};for(const line of(match[1]??"").split(`
+`)){const colon=line.indexOf(":");if(colon===-1)continue;const key=line.slice(0,colon).trim();let value=line.slice(colon+1).trim();if(value.startsWith('"')&&value.endsWith('"')||value.startsWith("'")&&value.endsWith("'"))value=value.slice(1,-1);if(key)data[key]=value}return{data,body:match[2]??""}}export function isPublished(data){return!!data.title&&!!data.date&&data.draft!=="true"}export function readingMinutes(markdown){const words=markdown.replace(/```[\s\S]*?```/g," ").replace(/!?\[([^\]]*)\]\([^)]*\)/g,"$1").split(/\s+/).filter((word)=>/[\p{L}\p{N}]/u.test(word)).length;return Math.max(1,Math.round(words/230))}export function authorsOf(data){const usernames=(data.authors??"").replace(/^\[|\]$/g,"").split(",").map((name)=>name.trim().replace(/^["']|["']$/g,"").toLowerCase()).filter((name)=>USERNAME.test(name));if(usernames.length>0)return[...new Set(usernames)].map((username)=>({username,name:data[`author.${username}.name`]??"",avatar:data[`author.${username}.avatar`]??"",bio:data[`author.${username}.bio`]??""}));const username=(data.authorUsername??"").toLowerCase();if(!data.author&&!username)return[];return[{username:USERNAME.test(username)?username:"",name:data.author??"",avatar:data.authorAvatar??"",bio:data.authorBio??""}]}function toPost(slug,markdown){const{data,body}=parseFrontmatter(markdown);if(!isPublished(data))return null;return{slug,title:data.title,date:data.date,description:data.description??"",author:data.author??"",authors:authorsOf(data),image:data.image??"",imageAlt:data.imageAlt??"",featured:data.featured==="true",minutes:readingMinutes(body),frontmatter:data,body}}export function sortPosts(posts){return[...posts].sort((a,b)=>{if(a.featured!==b.featured)return a.featured?-1:1;return b.date.localeCompare(a.date)})}export function loadPosts(options={}){const dir=options.dir??blogContentDir();if(!existsSync(dir))return[];const posts=[];for(const file of readdirSync(dir)){const slug=file.replace(/\.md$/,"");if(!file.endsWith(".md")||!SLUG.test(slug))continue;const post=toPost(slug,readFileSync(join(dir,file),"utf8"));if(post){const{body,...meta}=post;posts.push(meta)}}return sortPosts(posts)}export function loadPost(slug,options={}){const name=String(slug??"");if(!SLUG.test(name))return null;const file=join(options.dir??blogContentDir(),`${name}.md`);if(!existsSync(file))return null;return toPost(name,readFileSync(file,"utf8"))}export function renderPostBody(markdown,options={}){return renderPostHtml(Bun.markdown.html(markdown),{publicDir:options.publicDir??join(process.cwd(),"public")})}export function formatPostDate(date,locale="en-US"){const parsed=new Date(`${date}T00:00:00Z`);if(Number.isNaN(parsed.getTime()))return date;return parsed.toLocaleDateString(locale,{month:"long",day:"numeric",year:"numeric",timeZone:"UTC"})}export function initialsOf(name){const parts=name.trim().split(/\s+/).filter(Boolean);return((parts[0]?.[0]??"")+(parts.length>1?parts.at(-1)[0]:"")).toUpperCase()}export function joinNames(names){if(names.length<=1)return names[0]??"";return`${names.slice(0,-1).join(", ")} and ${names.at(-1)}`}export function createAuthorResolver(options={}){const ttl=options.ttlMs??600000,cache=new Map;async function profileOf(username){if(!options.lookup||!username||!USERNAME.test(username))return null;const cached=cache.get(username);if(cached&&Date.now()-cached.at<ttl)return cached.profile;let profile=null;try{profile=await options.lookup(username)??null}catch{profile=null}if(ttl>0)cache.set(username,{at:Date.now(),profile});return profile}const one=async(ref)=>{const profile=await profileOf(ref.username),name=String(profile?.name||ref.name||ref.username||options.fallbackName||process.env.APP_NAME||"Blog");return{name,initials:String(profile?.initials||initialsOf(name)),avatar:String(profile?.avatar||ref.avatar||""),bio:String(ref.bio||profile?.bio||""),url:String(profile?.url||"")}},resolve=async(post)=>{const refs=post.authors.length>0?post.authors:[{username:"",name:"",avatar:"",bio:""}];return Promise.all(refs.map(one))};resolve.one=one;resolve.clear=()=>cache.clear();return resolve}export function bylineOf(authors){return authors.map((author,index)=>({...author,joiner:index===0?"":index===authors.length-1?" and ":", ",avatarStyle:author.avatar?`background-image:url(${JSON.stringify(author.avatar)})`:""}))}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/cms",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.134",
+  "version": "0.75.136",
   "description": "Stacks cms utilities.",
   "author": "Chris Breuer",
   "contributors": [
@@ -58,14 +58,14 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/database": "0.75.134",
-    "@stacksjs/error-handling": "0.75.134",
-    "@stacksjs/orm": "0.75.134",
-    "@stacksjs/path": "0.75.134",
-    "@stacksjs/sites": "0.75.134",
-    "@stacksjs/slug": "0.75.134",
-    "@stacksjs/stx": "^0.2.440",
-    "@stacksjs/validation": "0.75.134",
+    "@stacksjs/database": "0.75.136",
+    "@stacksjs/error-handling": "0.75.136",
+    "@stacksjs/orm": "0.75.136",
+    "@stacksjs/path": "0.75.136",
+    "@stacksjs/sites": "0.75.136",
+    "@stacksjs/slug": "0.75.136",
+    "@stacksjs/stx": "^0.2.445",
+    "@stacksjs/validation": "0.75.136",
     "ts-medium-editor": "^0.2.0",
     "ts-slug": "^0.1.2",
     "ts-spreadsheets": "^0.2.5"