@sevenfold/setto-client 0.33.1 → 0.34.0

package/dist/blog/contract.d.ts

@@ -0,0 +1,149 @@
+/**
+ * The blog post contract, version 1.
+ *
+ * A post is an MDX file in the site's repo, at
+ * `src/content/blog/<slug>.<locale>.mdx`. The file is the record, so its shape
+ * is a contract between everything that touches it: Pixel, which writes it;
+ * setto-server, which validates and commits it; the click-to-edit path, which
+ * patches one paragraph or one image in it; and this library, which renders
+ * it. A redesign of the blog may change how a component looks, never its name,
+ * its props or where posts live — old posts must keep rendering.
+ *
+ * MDX compiles to JavaScript, and these files are written by a model and
+ * patched by owners. So the contract is closed: frontmatter with known keys,
+ * CommonMark (plus GFM tables and strikethrough), and the four components
+ * below with quoted string props. No `import`, no `export`, no `{…}`. A post
+ * is data that happens to use JSX syntax, and is rendered from its syntax
+ * tree — it is never compiled and never run.
+ *
+ * Changing anything here is a contract change: bump `BLOG_CONTRACT_VERSION`
+ * and migrate the posts that exist, in the same release.
+ */
+export declare const BLOG_CONTRACT_VERSION = 1;
+/** Where published posts live, relative to the site repo root. */
+export declare const BLOG_DIR = "src/content/blog";
+/** The public route the blog is served under. */
+export declare const BLOG_ROUTE = "/blogg";
+/** Lowercase words joined by single hyphens: `ny-kaffemaskin-i-butikken`. */
+export declare const BLOG_SLUG_PATTERN: RegExp;
+export declare const BLOG_SLUG_MAX = 80;
+/** A site language code, as the locale files use them: `no`, `en`, `sv`. */
+export declare const BLOG_LOCALE_PATTERN: RegExp;
+/** Hard ceiling on a post file, so a runaway generation cannot be committed. */
+export declare const BLOG_MAX_SOURCE_LENGTH = 200000;
+export interface BlogFrontmatter {
+    /** The post's only top-level heading; the body starts at `##`. */
+    title: string;
+    /** The lead under the title, the meta description and the share text. */
+    description: string;
+    /** Publication date, `YYYY-MM-DD`. */
+    date: string;
+    /** Must match the file name. */
+    slug: string;
+    /** Must match the file name. */
+    locale: string;
+    /** Cover image (https), also the share image. Optional: the site's own is the fallback. */
+    cover?: string;
+    tags?: string[];
+}
+export declare const BLOG_FRONTMATTER_KEYS: readonly ["title", "description", "date", "slug", "locale", "cover", "tags"];
+export declare const BLOG_TITLE_MAX = 120;
+export declare const BLOG_DESCRIPTION_MAX = 300;
+export declare const BLOG_TAGS_MAX = 8;
+export declare const BLOG_TAG_MAX = 40;
+export type BlogPropKind = 'text' | 'image-url' | 'youtube-id' | 'enum';
+export interface BlogPropSpec {
+    kind: BlogPropKind;
+    required: boolean;
+    /** For `text`: the longest value accepted. */
+    max?: number;
+    /** For `enum`: the accepted values. */
+    values?: readonly string[];
+}
+/**
+ * What a component may contain:
+ * - `none`: self-closing, no children;
+ * - `images`: only `<Image>` elements (a gallery);
+ * - `markdown`: paragraphs and lists with inline formatting, no headings and
+ *   no components.
+ */
+export type BlogChildren = 'none' | 'images' | 'markdown';
+export interface BlogComponentSpec {
+    props: Readonly<Record<string, BlogPropSpec>>;
+    children: BlogChildren;
+}
+export declare const BLOG_GALLERY_MIN = 2;
+export declare const BLOG_GALLERY_MAX = 24;
+export declare const BLOG_COMPONENTS: {
+    readonly Image: {
+        readonly props: {
+            readonly src: {
+                readonly kind: "image-url";
+                readonly required: true;
+            };
+            readonly alt: {
+                readonly kind: "text";
+                readonly required: true;
+                readonly max: 300;
+            };
+            readonly caption: {
+                readonly kind: "text";
+                readonly required: false;
+                readonly max: 300;
+            };
+        };
+        readonly children: "none";
+    };
+    readonly Gallery: {
+        readonly props: {
+            readonly caption: {
+                readonly kind: "text";
+                readonly required: false;
+                readonly max: 300;
+            };
+        };
+        readonly children: "images";
+    };
+    readonly YouTube: {
+        readonly props: {
+            /** The 11-character video id, never a URL: no other embed can be smuggled in. */
+            readonly id: {
+                readonly kind: "youtube-id";
+                readonly required: true;
+            };
+            readonly title: {
+                readonly kind: "text";
+                readonly required: false;
+                readonly max: 200;
+            };
+        };
+        readonly children: "none";
+    };
+    readonly Callout: {
+        readonly props: {
+            readonly tone: {
+                readonly kind: "enum";
+                readonly required: false;
+                readonly values: readonly ["info", "tip", "warning"];
+            };
+        };
+        readonly children: "markdown";
+    };
+};
+export type BlogComponentName = keyof typeof BLOG_COMPONENTS;
+export declare const BLOG_COMPONENT_NAMES: BlogComponentName[];
+export declare function isBlogComponentName(name: string): name is BlogComponentName;
+export declare const YOUTUBE_ID_PATTERN: RegExp;
+/** Link targets a post may use. Anything else, `javascript:` included, is refused. */
+export declare const BLOG_LINK_SCHEMES: readonly ["https:", "http:", "mailto:", "tel:"];
+export declare function isValidBlogSlug(slug: string): boolean;
+export declare function isValidBlogLocale(locale: string): boolean;
+/** `src/content/blog/<slug>.<locale>.mdx`. Throws on a slug or locale the contract refuses. */
+export declare function blogPostPath(slug: string, locale: string): string;
+/** The slug and locale a post path names, or null if it is not a post path. */
+export declare function parseBlogPostPath(path: string): {
+    slug: string;
+    locale: string;
+} | null;
+/** The public URL path of a post. */
+export declare function blogPostRoute(slug: string): string;

package/dist/blog/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@sevenfold/setto-client/blog` — the blog post contract.
+ *
+ * A separate entry so the MDX parser it needs never reaches a site's main
+ * bundle: setto-server and setto-agent validate with it, and the site's build
+ * step uses it to read posts.
+ */
+export * from './contract';
+export { validateBlogPost, parseBlogPost } from './validate';
+export type { BlogIssue, BlogPost, BlogValidationResult, BlogValidateOptions } from './validate';

package/dist/blog/validate.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Validates a blog post file against the contract in `contract.ts`.
+ *
+ * setto-server runs this before it commits a post, and before it stores a
+ * draft Pixel wrote; the site renders only what passes. Issues name the
+ * frontmatter key or the body line and say what to write instead, because the
+ * first reader of a failure is usually a model that has to fix its own output.
+ */
+import type { Root } from 'mdast';
+import { type BlogFrontmatter } from './contract';
+export interface BlogIssue {
+    /** `frontmatter`, `frontmatter.<key>`, `body` or `path`. */
+    path: string;
+    /** 1-based line in the file, when the issue has one. */
+    line?: number;
+    message: string;
+}
+export interface BlogPost {
+    frontmatter: BlogFrontmatter;
+    /** The body's syntax tree, frontmatter removed. What the renderer walks. */
+    body: Root;
+}
+export type BlogValidationResult = {
+    ok: true;
+    post: BlogPost;
+} | {
+    ok: false;
+    issues: BlogIssue[];
+};
+export interface BlogValidateOptions {
+    /** The repo path the file is (or will be) committed at; slug and locale must match it. */
+    path?: string;
+    /**
+     * Hosts images may come from (`blob.vercel-storage.com` also admits its
+     * subdomains). Omitted, any https URL is accepted — the server passes its
+     * media store so a post cannot hotlink.
+     */
+    imageHosts?: readonly string[];
+}
+export declare function validateBlogPost(source: string, options?: BlogValidateOptions): BlogValidationResult;
+/** Like `validateBlogPost`, but throws `Invalid blog post at <where>: <message>` on the first issue. */
+export declare function parseBlogPost(source: string, options?: BlogValidateOptions): BlogPost;