@codepress/blog 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# @codepress/blog
 
-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.
+Renders a CodePress blog. codepress.dev/blog runs on it, so a site that
+installs it renders posts exactly the same way.
+
+## Add a blog to a Next.js site
+
+```bash
+npx @codepress/blog init --site <your-content-site> --base-url https://your.site
+npm install
+```
+
+`init` detects the App or Pages Router and writes `/blog`, `/blog/[slug]`,
+`/blog/feed.xml` and `/blog/sitemap.xml`, plus `codepress-blog.ts` with the
+config. The pages render inside your root layout and import
+`@codepress/blog/blog.css`. It checks both the `app/` and `pages/` trees
+first and changes nothing if `/blog` is already served. `--force` overwrites the
+files `init` itself writes and keeps other `/blog` routes, but a `/blog` URL
+served from a different file (the other router, a route group,
+`pages/blog.tsx`) still stops it: move or delete that file first. Other options: `--base-path`, `--api-base`, `--revalidate`,
+`--router app|pages`. Pages regenerate every 60 seconds (ISR); if the CodePress
+API is down, the last good page keeps being served. Run `npx @codepress/blog --help`
+for the full list.
+
+The package is ESM and uses `html-react-parser`, whose dependencies are
+ESM-only. Run Next.js on Node 20.19+ or 22.12+ (these versions can `require()`
+ESM), or add `@codepress/blog` and `html-react-parser` to `transpilePackages`.
+
+## Entries
+
+- `@codepress/blog` (server-safe, no React)
+  - `registry`: the elements, attributes, URL schemes and `cp-*` components a
+    post may contain, and the post metadata schema.
+  - `sanitize`: `sanitizeHtml` and `sanitizeNodes`, an allowlist derived from
+    the registry.
+  - `schema`: `buildContentSchema()` and `schemaVersion`, the contract a site
+    serves at `<blog>/_schema.json`.
+  - `seo`, `feed`, `sitemap`: canonical URLs, JSON-LD, RSS and sitemap
+    builders. Each takes a `BlogSite` (`baseUrl`, `name`, `title`,
+    `description`, `defaultImage`), so the blog can live at any URL.
+  - `createHttpContentSource({ apiBase, site })`: reads published posts from
+    the CodePress read API.
+- `@codepress/blog/react`: `renderPostBody(html)` (always sanitizes) and the
+  component views, `COMPONENT_VIEWS`.
+- `@codepress/blog/blog.css`: styles for the component views, and the
+  optional `.cp-blog-prose` typography for the post body.
+- `@codepress/blog/next`: `createAppBlog(config)` for App Router pages and
+  metadata. `@codepress/blog/next/routes`: `createAppBlogRoutes(config)` for
+  the feed and sitemap route handlers. `@codepress/blog/next/pages`:
+  `createPagesBlog(config)` for the Pages Router.
+- `@codepress/blog/editor` (client-only): the in-place editor.
+  `BlogEditorMount` asks `GET {apiBase}/content-sites/{site}/me` and shows an
+  Edit button to callers who can edit; the Tiptap editor is a lazy chunk that
+  loads on Edit, so importing this entry downloads no ProseMirror code. Props:
+  `site`, `slug`, `apiBase`, `auth: { getToken() }` (the only token any draft
+  call sends), `header: { selector?, offset? }` (the toolbar pins below
+  `[data-blog-header]`, else the page's first `header`, else the top),
+  `column`, `onPublished`, `onLeave`, `slots.askPanel`, `slots.designLink` and
+  `actions.askCodePress`. `NewPostForm` starts a post (`new` is reserved).
+  Tiptap `3.24.0` is a peer dependency. The editor is styled with Tailwind
+  utilities: a Tailwind v4 host adds `@source` for this package's
+  `src/editor` in this workspace, or `dist/editor` when it installs the
+  package from npm.
+- `@codepress/blog/editor/client`: `createDraftClient({ apiBase, auth })`, the
+  draft API without the editor.
+
+## Example
+
+```tsx
+import {
+  createHttpContentSource,
+  postUrl,
+  type BlogSite,
+} from "@codepress/blog";
+import { renderPostBody } from "@codepress/blog/react";
+import "@codepress/blog/blog.css";
+
+const site: BlogSite = {
+  baseUrl: "https://acme.com/blog",
+  name: "Acme",
+  title: "Acme Blog",
+  description: "News from Acme.",
+  defaultImage: "https://acme.com/og.png",
+};
+const source = createHttpContentSource({
+  apiBase: "https://api.codepress.dev/v1",
+  site: "acme",
+});
+
+const post = await source.getPost("hello");
+// <link rel="canonical" href={postUrl(site, "hello")} />
+// <article className="cp-blog-prose">{renderPostBody(post.html)}</article>
+```
+
+## Styling
+
+Every colour, font and radius in `blog.css` is a CSS variable (`--cp-blog-*`,
+`--cp-callout-*`, `--cp-figure-*`). Override them on `:root` or on an element
+that wraps the post. The defaults are codepress.dev's.
+
+## Development
+
+```bash
+pnpm --filter @codepress/blog test
+pnpm --filter @codepress/blog typecheck
+pnpm --filter @codepress/blog lint   # also forbids apps/web (`@/`) imports
+pnpm --filter @codepress/blog build:package  # dist/, as published
+pnpm --filter @codepress/blog test:packaged  # init + next build on fixtures/
+node packages/blog/scripts/pack.mjs --dry-run  # what npm would publish
+```
+
+In the workspace the exports point at `src/`; `publishConfig.exports` holds the
+published `dist/` entries. A new entry in `exports` needs a `publishConfig.exports`
+counterpart, or `pack.mjs` fails. It also fails when a `publishConfig.exports`
+entry has no source export, lacks `types`, or points at a file missing from the
+tarball, and when a declaration file's relative import has no `.js` extension
+(`build.mjs` adds them, so NodeNext TypeScript consumers resolve the types).
+`test:packaged` imports every export from the tarball with Node and type-checks
+a NodeNext consumer against it.

package/dist/blog.css

@@ -0,0 +1,227 @@
+/*
+ * @codepress/blog styles.
+ *
+ * Every colour, font and radius is a CSS variable. Override any of them on
+ * `:root` or on an element that contains the post to match your site:
+ *
+ *   .blog-post { --cp-blog-font: "Inter", sans-serif; --cp-blog-link: #0a66c2; }
+ *
+ * `.cp-blog-prose` is optional typography for the post body. Sites that
+ * already style articles (for example with Tailwind's `prose`) can skip it;
+ * the component styles below stand on their own.
+ */
+
+:where(:root) {
+  --cp-blog-font: inherit;
+  --cp-blog-heading-font: inherit;
+  --cp-blog-mono-font:
+    ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  --cp-blog-text: #111110;
+  --cp-blog-body: #3f3d38;
+  --cp-blog-muted: #6b6760;
+  --cp-blog-link: #111110;
+  --cp-blog-border: #e6e3de;
+  --cp-blog-code-bg: #f4f2ee;
+  --cp-blog-font-size: 1rem;
+  --cp-blog-line-height: 1.75;
+
+  --cp-callout-radius: calc(0.625rem + 4px);
+  --cp-callout-font-size: 15px;
+  --cp-callout-text: var(--cp-blog-text);
+  --cp-callout-label: var(--cp-blog-muted);
+  --cp-callout-info-border: #c7d7f5;
+  --cp-callout-info-bg: #f3f7fe;
+  --cp-callout-warn-border: #f1d6a3;
+  --cp-callout-warn-bg: #fff9ec;
+  --cp-callout-tip-border: #bfe3cc;
+  --cp-callout-tip-bg: #f1faf4;
+
+  --cp-figure-radius: 0.625rem;
+  --cp-figure-caption: var(--cp-blog-muted);
+}
+
+/* Post body typography. */
+
+.cp-blog-prose {
+  color: var(--cp-blog-body);
+  font-family: var(--cp-blog-font);
+  font-size: var(--cp-blog-font-size);
+  line-height: var(--cp-blog-line-height);
+}
+
+.cp-blog-prose :where(p, ul, ol, blockquote, pre, table) {
+  margin: 1.25em 0;
+}
+
+.cp-blog-prose :where(h2, h3, h4) {
+  color: var(--cp-blog-text);
+  font-family: var(--cp-blog-heading-font);
+  font-weight: 600;
+  line-height: 1.3;
+  margin: 2em 0 0.75em;
+}
+
+.cp-blog-prose :where(h2) {
+  font-size: 1.5em;
+}
+
+.cp-blog-prose :where(h3) {
+  font-size: 1.25em;
+}
+
+.cp-blog-prose :where(h4) {
+  font-size: 1em;
+}
+
+.cp-blog-prose :where(a) {
+  color: var(--cp-blog-link);
+  font-weight: 500;
+  text-decoration: underline;
+}
+
+.cp-blog-prose :where(strong) {
+  color: var(--cp-blog-text);
+  font-weight: 600;
+}
+
+.cp-blog-prose :where(ul, ol) {
+  padding-left: 1.625em;
+}
+
+.cp-blog-prose :where(ul) {
+  list-style: disc;
+}
+
+.cp-blog-prose :where(ol) {
+  list-style: decimal;
+}
+
+.cp-blog-prose :where(li) {
+  margin: 0.5em 0;
+}
+
+.cp-blog-prose :where(code) {
+  color: var(--cp-blog-text);
+  font-family: var(--cp-blog-mono-font);
+  font-size: 0.875em;
+  font-weight: 600;
+}
+
+.cp-blog-prose :where(pre) {
+  background: var(--cp-blog-code-bg);
+  border-radius: 0.375rem;
+  overflow-x: auto;
+  padding: 0.875em 1.125em;
+}
+
+.cp-blog-prose :where(pre code) {
+  font-weight: inherit;
+}
+
+.cp-blog-prose :where(blockquote) {
+  border-left: 0.25em solid var(--cp-blog-border);
+  color: var(--cp-blog-text);
+  font-style: italic;
+  padding-left: 1em;
+}
+
+.cp-blog-prose :where(hr) {
+  border: 0;
+  border-top: 1px solid var(--cp-blog-border);
+  margin: 3em 0;
+}
+
+.cp-blog-prose :where(img) {
+  height: auto;
+  max-width: 100%;
+}
+
+.cp-blog-prose :where(table) {
+  border-collapse: collapse;
+  font-size: 0.875em;
+  width: 100%;
+}
+
+.cp-blog-prose :where(th, td) {
+  border-bottom: 1px solid var(--cp-blog-border);
+  padding: 0.5em;
+  text-align: left;
+}
+
+.cp-blog-prose :where(th) {
+  color: var(--cp-blog-text);
+  font-weight: 600;
+}
+
+.cp-blog-prose > :first-child {
+  margin-top: 0;
+}
+
+.cp-blog-prose > :last-child {
+  margin-bottom: 0;
+}
+
+/* <cp-callout> */
+
+.cp-callout {
+  border: 1px solid;
+  border-radius: var(--cp-callout-radius);
+  box-sizing: border-box;
+  color: var(--cp-callout-text);
+  font-size: var(--cp-callout-font-size);
+  line-height: 1.625;
+  margin: 1.5rem 0;
+  padding: 1rem 1.25rem;
+}
+
+.cp-callout > * {
+  margin: 0;
+}
+
+.cp-callout--info {
+  background: var(--cp-callout-info-bg);
+  border-color: var(--cp-callout-info-border);
+}
+
+.cp-callout--warn {
+  background: var(--cp-callout-warn-bg);
+  border-color: var(--cp-callout-warn-border);
+}
+
+.cp-callout--tip {
+  background: var(--cp-callout-tip-bg);
+  border-color: var(--cp-callout-tip-border);
+}
+
+.cp-callout .cp-callout__label {
+  color: var(--cp-callout-label);
+  font-size: 0.75rem;
+  font-weight: 600;
+  letter-spacing: 0.025em;
+  line-height: 1rem;
+  margin: 0 0 0.25rem;
+  text-transform: uppercase;
+}
+
+/* <cp-figure> */
+
+.cp-figure {
+  margin: 2rem 0;
+}
+
+.cp-figure .cp-figure__img {
+  border-radius: var(--cp-figure-radius);
+  display: block;
+  height: auto;
+  margin: 0;
+  max-width: 100%;
+  width: 100%;
+}
+
+.cp-figure .cp-figure__caption {
+  color: var(--cp-figure-caption);
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  margin: 0.5rem 0 0;
+  text-align: center;
+}