@sandboxsonny/ace-kit 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @sandboxsonny/ace-kit
 
+## 0.8.0
+
+### Minor Changes
+
+- 7b85a62: Add `AceSeo` for Astro: one component for a page's title, description, canonical address, robots and sharing tags, built on `astro-seo` (with `siteName` ending the title) and filled from the entry's SEO title and description. Every content type in the CMS now has those two required fields, so the Astro starter depends on `astro-seo`, uses `AceSeo` in its layout, and fills them in on its starter pages. `seoProperties` is exported for any other framework.
+
 ## 0.7.1
 
 ### Patch Changes

package/astro/AceSeo.astro

@@ -0,0 +1,12 @@
+---
+import { SEO } from "astro-seo";
+
+import { seoProperties } from "../dist/index.js";
+import type { AceSeoOptions } from "../dist/index.js";
+
+type Props = AceSeoOptions;
+
+const properties = seoProperties(Astro.props);
+---
+
+<SEO {...properties} />

package/dist/cli.js

@@ -9,8 +9,8 @@ if (major < 22 || major === 22 && minor < 12) {
   process.exit(1);
 }
 try {
-  const { createRealEnvironment } = await import("./environment-TGMGSRJ3.js");
-  const { runCli } = await import("./main-IAQ2IL3M.js");
+  const { createRealEnvironment } = await import("./environment-NGXBLWXM.js");
+  const { runCli } = await import("./main-JOA27GX6.js");
   const environment = await createRealEnvironment();
   process.exit(await runCli(process.argv.slice(2), environment));
 } catch (error) {

package/dist/{environment-TGMGSRJ3.js → environment-NGXBLWXM.js}

@@ -145,7 +145,7 @@ function createLastApiUrl(path) {
 }
 
 // src/cli/version.ts
-var aceKitVersion = true ? "0.7.1" : "development";
+var aceKitVersion = true ? "0.8.0" : "development";
 
 // src/cli/environment.ts
 var runCommand = (command, commandArguments, input) => new Promise((resolve, reject) => {

package/dist/index.d.ts

@@ -447,6 +447,54 @@ declare function refreshPageContent(): Promise<void>;
  */
 declare function listenForPreviewRefresh(adminOrigin: string, refresh?: () => Promise<void>): () => void;
 
+/** The two values every entry has, whatever its content type: what a search engine shows for it. */
+declare const seoTitleHandle = "seo-title";
+declare const seoDescriptionHandle = "seo-description";
+type AceSeoOptions = {
+    /** The entry the page shows. Its SEO title and description are used, falling back to its title and description. */
+    entry?: Pick<AceEntry, "title" | "description" | "values">;
+    /** Used when there is no entry, or the entry has no title of its own. */
+    title?: string;
+    /** Used when there is no entry, or the entry has no description of its own. */
+    description?: string;
+    /** The site's name: it ends the page's `<title>` ("About us | Acme") and is the shared link's `og:site_name`. */
+    siteName?: string;
+    /** The page's address, if it isn't the one requested. Left out, the requested address is used. */
+    canonical?: string;
+    /** A picture to show when the page is shared: a full web address. */
+    image?: string;
+    /** Tells search engines to leave the page out, as for a draft shown in preview. */
+    noindex?: boolean;
+};
+type Meta = {
+    property?: string;
+    name?: string;
+    content: string;
+};
+/** What `astro-seo`'s `<SEO>` takes (only the parts used here). */
+type AceSeoProperties = {
+    title?: string;
+    description?: string;
+    canonical?: string;
+    noindex: boolean;
+    twitter: {
+        card: "summary" | "summary_large_image";
+        title?: string;
+        description?: string;
+        image?: string;
+    };
+    extend: {
+        meta: Meta[];
+    };
+};
+/**
+ * Works out what a page's search and sharing tags say. An entry's SEO title and description win; if the editor left
+ * them out (an entry saved before they were required, say) its own title and description are used, then the
+ * options'. The site's name ends the `<title>` (not the sharing titles), unless the title already is the name.
+ * Open Graph is written as plain meta tags, so a page with no picture needs no placeholder.
+ */
+declare function seoProperties(options: AceSeoOptions): AceSeoProperties;
+
 /**
  * A text area field's text as HTML. With `multiline` (the default) blank lines start new paragraphs (`<p>`) and a
  * single new line is a line break; without it the text is one line, with no element around it. Every piece of text
@@ -488,4 +536,4 @@ type AceSection = {
   blocks: AceSectionBlock[];
 };
 
-export { type AceAddress, type AceClient, type AceClientOptions, type AceContentTypeHandle, type AceContentTypeSchema, type AceContentTypes, type AceDateFormat, type AceEntry, type AceFieldSchema, type AceImageAttributes, type AceImageData, type AceImageOptions, type AceLinkAttributes, type AceLinkData, type AceMenu, type AceMenuItem, type AceNavigationLink, type AcePage, AcePreviewExpiredError, type AceRichTextDocument, type AceRichTextMark, type AceRichTextNode, type AceSection, type AceSectionBlock, AceUnavailableError, type AceValuesOf, type BlockDefinition, type SectionDefinition, type SectionFieldDefinition, type SectionFieldType, type SectionOf, type SectionTypesPayload, type ValuesOfFields, addFramingPolicy, addressFromPath, checkSectionDefinition, createAceClient, defineSection, formatAceDate, framingPolicy, headingLevel, homeAddress, imageAttributes, isCurrentPage, isHomeAddress, isInternalPath, isRefreshRequest, linkAddress, linkAttributes, linksFromMenu, listStart, listenForPreviewRefresh, loadMenuLinks, loadPage, originOf, pageNotices, pathOfAddress, previewHeaders, previewParameter, previewTokenFrom, refreshMessageType, refreshPageContent, renderRichText, renderTextArea, richTextImageSizes, sectionTypesPayload, swapPageContent, visitablePath };
+export { type AceAddress, type AceClient, type AceClientOptions, type AceContentTypeHandle, type AceContentTypeSchema, type AceContentTypes, type AceDateFormat, type AceEntry, type AceFieldSchema, type AceImageAttributes, type AceImageData, type AceImageOptions, type AceLinkAttributes, type AceLinkData, type AceMenu, type AceMenuItem, type AceNavigationLink, type AcePage, AcePreviewExpiredError, type AceRichTextDocument, type AceRichTextMark, type AceRichTextNode, type AceSection, type AceSectionBlock, type AceSeoOptions, type AceSeoProperties, AceUnavailableError, type AceValuesOf, type BlockDefinition, type SectionDefinition, type SectionFieldDefinition, type SectionFieldType, type SectionOf, type SectionTypesPayload, type ValuesOfFields, addFramingPolicy, addressFromPath, checkSectionDefinition, createAceClient, defineSection, formatAceDate, framingPolicy, headingLevel, homeAddress, imageAttributes, isCurrentPage, isHomeAddress, isInternalPath, isRefreshRequest, linkAddress, linkAttributes, linksFromMenu, listStart, listenForPreviewRefresh, loadMenuLinks, loadPage, originOf, pageNotices, pathOfAddress, previewHeaders, previewParameter, previewTokenFrom, refreshMessageType, refreshPageContent, renderRichText, renderTextArea, richTextImageSizes, sectionTypesPayload, seoDescriptionHandle, seoProperties, seoTitleHandle, swapPageContent, visitablePath };

package/dist/index.js

@@ -133,4 +133,35 @@ function formatAceDate(date, format = {}) {
   }).format(moment);
 }
 
-export { checkSectionDefinition, defineSection, formatAceDate, sectionTypesPayload };
+// src/helpers/seo.ts
+var seoTitleHandle = "seo-title";
+var seoDescriptionHandle = "seo-description";
+var textValue = (value) => typeof value === "string" ? value.trim() : "";
+function seoProperties(options) {
+  const { entry } = options;
+  const title = textValue(entry?.values?.[seoTitleHandle]) || textValue(entry?.title) || textValue(options.title);
+  const description = textValue(entry?.values?.[seoDescriptionHandle]) || textValue(entry?.description) || textValue(options.description);
+  const meta = [{ property: "og:type", content: "website" }];
+  if (title) meta.push({ property: "og:title", content: title });
+  if (description) meta.push({ property: "og:description", content: description });
+  if (options.siteName) meta.push({ property: "og:site_name", content: options.siteName });
+  if (options.canonical) meta.push({ property: "og:url", content: options.canonical });
+  if (options.image) meta.push({ property: "og:image", content: options.image });
+  const siteName = options.siteName?.trim();
+  const pageTitle = title && siteName && title !== siteName ? `${title} | ${siteName}` : title;
+  return {
+    ...pageTitle && { title: pageTitle },
+    ...description && { description },
+    ...options.canonical && { canonical: options.canonical },
+    noindex: options.noindex === true,
+    twitter: {
+      card: options.image ? "summary_large_image" : "summary",
+      ...title && { title },
+      ...description && { description },
+      ...options.image && { image: options.image }
+    },
+    extend: { meta }
+  };
+}
+
+export { checkSectionDefinition, defineSection, formatAceDate, sectionTypesPayload, seoDescriptionHandle, seoProperties, seoTitleHandle };

package/dist/{main-IAQ2IL3M.js → main-JOA27GX6.js}

@@ -197,6 +197,8 @@ function starterEntries(framework, siteName) {
       title: "Home",
       description: `Welcome to ${siteName}.`,
       values: {
+        "seo-title": `${siteName} | Welcome`,
+        "seo-description": `Welcome to ${siteName}.`,
         headline: `Welcome to ${siteName}`,
         body: richText(
           "Edit this text in the CMS and reload the page to see it change.\n\nPages are rendered on each request, so there is nothing to rebuild."
@@ -254,6 +256,8 @@ function starterEntries(framework, siteName) {
       title: "About",
       description: `About ${siteName}.`,
       values: {
+        "seo-title": `About | ${siteName}`,
+        "seo-description": `About ${siteName}.`,
         headline: "About",
         body: richText(
           "Say who you are and what you do.\n\nThis text is an entry in the CMS: editing it there changes this page."
@@ -271,6 +275,8 @@ function starterEntries(framework, siteName) {
       title: "Contact",
       description: `How to reach ${siteName}.`,
       values: {
+        "seo-title": `Contact | ${siteName}`,
+        "seo-description": `How to reach ${siteName}.`,
         headline: "Contact",
         body: richText("Tell people how to get in touch."),
         // A link to another entry of the site: it needs About's ID, which exists by now.

package/docs/astro.md

@@ -92,6 +92,7 @@ import AcePreviewRefresh from "@sandboxsonny/ace-kit/astro/AcePreviewRefresh.ast
 - **AceLink** draws a link field as an `<a>` with the editor's words (or the address when there are none; put your own words in the slot to replace them). Nothing is drawn if the address can't be trusted, so check for a missing link yourself if you need a fallback. A date field is plain text: `formatAceDate(entry.values.published, { locale: "en-GB" })` gives "13 October 2026", and `<time datetime={entry.values.published}>` takes the raw value.
 - **AceRichText** draws a rich text field as HTML. It outputs bare elements (`h2`, `p`, `ul`, `a`...); style them from a wrapping element. Astro scopes styles, so reach them with `:global`, e.g. `.rich-text :global(h2) { ... }`.
 - **AceTextArea** draws a Textarea field (plain text): `multiline` (the default) makes paragraphs of blocks and a `<br>` of a new line; `multiline={false}` is one line of text with no element around it.
+- **AceSeo** goes in your layout's `<head>`: the page's `<title>`, description, canonical address, robots and Open Graph / Twitter tags, built on [astro-seo](https://github.com/jonasmerlin/astro-seo) (a site made by `ace-kit create` already depends on it; add `astro-seo` to a site you made by hand). Give it the entry and it uses the entry's SEO title and description (every content type has those two required fields), falling back to the entry's title and description, then to its own `title` and `description` props. Other props: `siteName` (ends the `<title>`, as "About us | Acme", and is the shared link's site name; leave it out if editors write the whole title), `canonical`, `image` (a full web address, for sharing) and `noindex` (set it for a draft shown in preview). On another framework, `seoProperties(options)` gives the same answer as plain data.
 - **AcePreviewRefresh** goes once in your layout. It does nothing unless the page was opened by the CMS's editor.
 - **AceNotice** is the message for a page that isn't an entry.
 

package/docs/getting-started.md

@@ -25,7 +25,7 @@ npm install @sandboxsonny/ace-kit
 | `@sandboxsonny/ace-kit`                                  | The framework-free core: the client, errors, `loadPage`, addressing, image attributes, menu helpers, rich text to HTML, preview helpers, all the types            |
 | `@sandboxsonny/ace-kit/astro/integration`                | The Astro integration: add it to `astro.config.mjs` and an Astro site is wired up                                                                                 |
 | `@sandboxsonny/ace-kit/astro`                            | What an Astro page calls: `getPage`, `getEntry`, `getEntries`, `getMenuLinks`, `getMenu`, `ace` (the client)                                                      |
-| `@sandboxsonny/ace-kit/astro/AceImage.astro` and friends | Astro components: `AceImage`, `AceRichText`, `AceMenu`, `AceNotice`, `AcePreviewRefresh`                                                                          |
+| `@sandboxsonny/ace-kit/astro/AceImage.astro` and friends | Astro components: `AceImage`, `AceRichText`, `AceSeo`, `AceMenu`, `AceNotice`, `AcePreviewRefresh`                                                                |
 | `@sandboxsonny/ace-kit/react`                            | `AceImage`, `AceRichText`, `usePreviewRefresh`                                                                                                                    |
 | `@sandboxsonny/ace-kit/react-router`                     | React Router 7, browser-safe: `AceRichText` (router links), `AceImage`, `AceNotice`, `createMeta`, `useAceMenu`, `useAcePreview`                                  |
 | `@sandboxsonny/ace-kit/react-router/server`              | React Router 7, server only: `createPageLoader`, `createRootLoader`, `handleRequest` (the server entry), `getEntry`, `getEntries`, `getMenuLinks`, `getAceClient` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxsonny/ace-kit",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Everything a website needs to use CMS Ace: a typed client, addressing, images, menus, rich text, live preview, and Astro and React adapters.",
   "keywords": [
     "cms",
@@ -105,7 +105,8 @@
     "react-router": ">=7",
     "react-dom": ">=18",
     "@react-router/node": ">=7",
-    "vite": ">=5"
+    "vite": ">=5",
+    "astro-seo": ">=1"
   },
   "peerDependenciesMeta": {
     "astro": {
@@ -125,6 +126,9 @@
     },
     "vite": {
       "optional": true
+    },
+    "astro-seo": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -139,6 +143,7 @@
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "astro": "^7.3.8",
+    "astro-seo": "^1.2.0",
     "eslint": "^10.12.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-astro": "^1.7.0",

package/templates/astro/package.json

@@ -21,8 +21,9 @@
   },
   "dependencies": {
     "@astrojs/node": "^11.1.7",
-    "@sandboxsonny/ace-kit": "^0.5.0",
-    "astro": "^7.3.8"
+    "@sandboxsonny/ace-kit": "file:../ace-kit/sandboxsonny-ace-kit-0.7.0.tgz",
+    "astro": "^7.3.8",
+    "astro-seo": "^1.2.0"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",

package/templates/astro/src/ace-kit.generated.d.ts

@@ -17,6 +17,10 @@ declare module "@sandboxsonny/ace-kit" {
       "button"?: AceLinkData;
       /** Content */
       "content"?: AceSection[];
+      /** SEO title */
+      "seo-title": string;
+      /** SEO description */
+      "seo-description": string;
     };
   }
 }

package/templates/astro/src/layouts/BaseLayout.astro

@@ -1,17 +1,22 @@
 ---
 import AcePreviewRefresh from "@sandboxsonny/ace-kit/astro/AcePreviewRefresh.astro";
+import AceSeo from "@sandboxsonny/ace-kit/astro/AceSeo.astro";
+import type { AceEntry } from "@sandboxsonny/ace-kit";
 import SiteFooter from "~/components/SiteFooter.astro";
 import SiteHeader from "~/components/SiteHeader.astro";
 import "~/styles/global.css";
 
 type Props = {
+  /** The entry the page shows: its SEO title and description fill the page's search and sharing tags. */
+  entry?: AceEntry;
+  /** Used when there is no entry (a notice page), and when an entry has no title of its own. */
   title: string;
   description?: string;
   /** True when the page is showing a draft inside the CMS's preview frame. */
   preview?: boolean;
 };
 
-const { title, description = "A simple example site for testing CMS Ace.", preview = false } = Astro.props;
+const { entry, title, description = "A simple example site for testing CMS Ace.", preview = false } = Astro.props;
 ---
 
 <!doctype html>
@@ -19,11 +24,17 @@ const { title, description = "A simple example site for testing CMS Ace.", previ
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <meta name="description" content={description} />
     <meta name="generator" content={Astro.generator} />
-    {preview && <meta name="robots" content="noindex" />}
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-    <title>{title}</title>
+    {/* Title, description, canonical address, robots and sharing tags. A draft shown in preview is kept out of search. */}
+    <AceSeo
+      entry={entry}
+      {title}
+      {description}
+      siteName="Example Site"
+
+      noindex={preview}
+    />
   </head>
   <body>
     <SiteHeader />

package/templates/astro/src/pages/[...slug].astro

@@ -15,11 +15,7 @@ const isPreview = Boolean(page.headers["Cache-Control"]);
 ---
 
 {page.kind === "entry" ? (
-  <BaseLayout
-    title={`${page.entry.title} | Example Site`}
-    description={page.entry.description || undefined}
-    preview={isPreview}
-  >
+  <BaseLayout entry={page.entry} title={page.entry.title} preview={isPreview}>
     <PageContent entry={page.entry} />
   </BaseLayout>
 ) : (