@sandboxsonny/ace-kit 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @sandboxsonny/ace-kit
 
+## 0.10.0
+
+### Minor Changes
+
+- 4215f32: Show the site's favicon in `<AceSeo>`. The favicon is chosen in the site's settings in the CMS; `<AceSeo>` adds `<link rel="icon">` and `<link rel="apple-touch-icon">` for it when you don't pass a `favicon` yourself. If your layout already has its own icon link, remove it, or the browser may pick either. `getSite()` now also returns the favicon.
+
+## 0.9.0
+
+### Minor Changes
+
+- 6e6885f: Show the site's social image in `<AceSeo>`. The image is chosen in the site's settings in the CMS; `<AceSeo>` uses it for `og:image` and the Twitter card when you don't pass an `image` yourself. Also adds `getSite()` (Astro and React Router) for the site's name and social image.
+
 ## 0.8.0
 
 ### Minor Changes

package/astro/AceSeo.astro

@@ -3,10 +3,19 @@ import { SEO } from "astro-seo";
 
 import { seoProperties } from "../dist/index.js";
 import type { AceSeoOptions } from "../dist/index.js";
+import { getSite } from "../dist/astro.js";
 
 type Props = AceSeoOptions;
 
-const properties = seoProperties(Astro.props);
+// With no picture or icon of its own, a page shows the ones chosen in the site's settings. The tags are never worth
+// failing the page for, so a CMS that can't be reached just means none.
+const needsSite = Astro.props.image === undefined || Astro.props.favicon === undefined;
+const site = needsSite ? await getSite().catch(() => null) : null;
+const properties = seoProperties({
+  ...Astro.props,
+  image: Astro.props.image ?? site?.social_image?.src,
+  favicon: Astro.props.favicon ?? site?.favicon ?? undefined,
+});
 ---
 
 <SEO {...properties} />

package/dist/astro.d.ts

@@ -14,6 +14,45 @@ type AceContentTypeSchema = {
   fields: AceFieldSchema[];
 };
 
+/** An image as the CMS Ace public API returns it. Use `src` and `srcset` in an `<img>`. */
+type AceImageData = {
+  id: number;
+  /** The untouched original. */
+  url: string;
+  /** A web-sized copy, for browsers that ignore `srcset`. */
+  src: string;
+  /** Copies at several widths; empty when the image is too small to need them. */
+  srcset: string;
+  width: number | null;
+  height: number | null;
+  alt_text: string;
+  content_type: string;
+};
+
+/** The site's favicon as the CMS Ace public API returns it: the original, and square PNG copies. */
+type AceFavicon = {
+  id: number;
+  /** The untouched original. */
+  url: string;
+  /** A small square PNG (48 pixels), for the browser tab and search results. */
+  icon: string;
+  /** A square PNG (180 pixels), for a phone's home screen. */
+  apple_touch_icon: string;
+  content_type: string;
+};
+
+/** The site the request is for, as the CMS Ace public API returns it. */
+type AceSite = {
+  id: number;
+  name: string;
+  domain: string;
+  handle: string;
+  /** The picture the site's owners chose to show in search results and social posts; null if none. */
+  social_image: AceImageData | null;
+  /** The small picture the site's owners chose for browser tabs; null if none. */
+  favicon: AceFavicon | null;
+};
+
 /** One link of a menu as the public API returns it, with its address already worked out. */
 type AceMenuItem = {
   label: string;
@@ -90,6 +129,7 @@ declare const ace: {
         limit?: number;
     }): Promise<AceEntry<AceValuesOf<Handle>>[]>;
     getMenu(handle: string): Promise<AceMenu | null>;
+    getSite(): Promise<AceSite | null>;
     getContentTypes(): Promise<AceContentTypeSchema[]>;
 };
 /** One live entry of a content type by its handle, or `null`. See `createAceClient`. */
@@ -102,6 +142,8 @@ declare const getEntries: <Handle extends AceContentTypeHandle>(contentTypeHandl
 }) => Promise<AceEntry<AceValuesOf<Handle>>[]>;
 /** A navigation menu with every link worked out, or `null`. */
 declare const getMenu: (handle: string) => Promise<AceMenu | null>;
+/** The site: its name and the social image its owners chose (`social_image`, or `null`). */
+declare const getSite: () => Promise<AceSite | null>;
 /**
  * A menu's links, ready to draw: `[{ label, to, children? }]`. If the site has no such menu, or the CMS can't be
  * reached, you get `fallback` instead, so a missing menu never takes a page down.
@@ -136,4 +178,4 @@ declare function getPage<Values = Record<string, unknown>>(astro: {
     };
 }): Promise<AcePage<Values>>;
 
-export { ace, applyPage, getEntries, getEntry, getMenu, getMenuLinks, getPage };
+export { ace, applyPage, getEntries, getEntry, getMenu, getMenuLinks, getPage, getSite };

package/dist/astro.js

@@ -1,4 +1,4 @@
-import { createAceClient, loadMenuLinks, loadPage } from './chunk-XYOW63V6.js';
+import { createAceClient, loadMenuLinks, loadPage } from './chunk-EKZRLWNO.js';
 import './chunk-M5WR5TCR.js';
 import './chunk-YLO6IAXF.js';
 import { ACE_SITE_DOMAIN, ACE_API_URL } from 'astro:env/server';
@@ -7,6 +7,7 @@ var ace = createAceClient({ apiUrl: ACE_API_URL, siteDomain: ACE_SITE_DOMAIN });
 var getEntry = ace.getEntry;
 var getEntries = ace.getEntries;
 var getMenu = ace.getMenu;
+var getSite = ace.getSite;
 function getMenuLinks(handle, options = {}) {
   return loadMenuLinks(ace, handle, options.fallback ?? []);
 }
@@ -21,4 +22,4 @@ async function getPage(astro) {
   return page;
 }
 
-export { ace, applyPage, getEntries, getEntry, getMenu, getMenuLinks, getPage };
+export { ace, applyPage, getEntries, getEntry, getMenu, getMenuLinks, getPage, getSite };

package/dist/{chunk-XYOW63V6.js → chunk-EKZRLWNO.js}

@@ -89,6 +89,10 @@ function createAceClient({
     getMenu(handle) {
       return get(`/public/menus/${encodeURIComponent(handle)}`);
     },
+    /** The site itself: its name, and the social image its owners chose (null if none). */
+    getSite() {
+      return get("/public/site");
+    },
     /** What the site's content types and fields are, which is what type generation reads. */
     async getContentTypes() {
       return await get("/public/content-types") ?? [];

package/dist/cli.js

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

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

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

package/dist/index.d.ts

@@ -84,6 +84,45 @@ type AceNavigationLink = {
   children?: AceNavigationLink[];
 };
 
+/** An image as the CMS Ace public API returns it. Use `src` and `srcset` in an `<img>`. */
+type AceImageData = {
+  id: number;
+  /** The untouched original. */
+  url: string;
+  /** A web-sized copy, for browsers that ignore `srcset`. */
+  src: string;
+  /** Copies at several widths; empty when the image is too small to need them. */
+  srcset: string;
+  width: number | null;
+  height: number | null;
+  alt_text: string;
+  content_type: string;
+};
+
+/** The site's favicon as the CMS Ace public API returns it: the original, and square PNG copies. */
+type AceFavicon = {
+  id: number;
+  /** The untouched original. */
+  url: string;
+  /** A small square PNG (48 pixels), for the browser tab and search results. */
+  icon: string;
+  /** A square PNG (180 pixels), for a phone's home screen. */
+  apple_touch_icon: string;
+  content_type: string;
+};
+
+/** The site the request is for, as the CMS Ace public API returns it. */
+type AceSite = {
+  id: number;
+  name: string;
+  domain: string;
+  handle: string;
+  /** The picture the site's owners chose to show in search results and social posts; null if none. */
+  social_image: AceImageData | null;
+  /** The small picture the site's owners chose for browser tabs; null if none. */
+  favicon: AceFavicon | null;
+};
+
 /**
  * A client for the CMS Ace public API. It runs on the server only, so the visitor's browser never talks to the
  * API. The API finds the site from X-Ace-Site-Domain, which this client sets to the site's domain. X-Forwarded-Host
@@ -104,6 +143,8 @@ declare function createAceClient({ apiUrl, siteDomain, cacheSeconds, fetchImplem
     }): Promise<AceEntry<AceValuesOf<Handle>>[]>;
     /** One of the site's navigation menus by its handle, with every link worked out; null if the site has none. */
     getMenu(handle: string): Promise<AceMenu | null>;
+    /** The site itself: its name, and the social image its owners chose (null if none). */
+    getSite(): Promise<AceSite | null>;
     /** What the site's content types and fields are, which is what type generation reads. */
     getContentTypes(): Promise<AceContentTypeSchema[]>;
 };
@@ -142,21 +183,6 @@ declare const isHomeAddress: (address: AceAddress) => boolean;
  */
 declare function visitablePath(path: string): string;
 
-/** An image as the CMS Ace public API returns it. Use `src` and `srcset` in an `<img>`. */
-type AceImageData = {
-  id: number;
-  /** The untouched original. */
-  url: string;
-  /** A web-sized copy, for browsers that ignore `srcset`. */
-  src: string;
-  /** Copies at several widths; empty when the image is too small to need them. */
-  srcset: string;
-  width: number | null;
-  height: number | null;
-  alt_text: string;
-  content_type: string;
-};
-
 type AceImageOptions = {
     /** How wide the image is shown, e.g. "(min-width: 64rem) 64rem, 100vw". The browser uses it to pick a copy from srcset. */
     sizes: string;
@@ -461,8 +487,16 @@ type AceSeoOptions = {
     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. */
+    /**
+     * A picture to show when the page is shared: a full web address. In the Astro `<AceSeo>`, leaving it out uses the
+     * social image chosen in the site's settings in the CMS (if any).
+     */
     image?: string;
+    /**
+     * The site's favicon. In the Astro `<AceSeo>`, leaving it out uses the favicon chosen in the site's settings in the
+     * CMS (if any); it then adds `<link rel="icon">` and `<link rel="apple-touch-icon">`.
+     */
+    favicon?: Pick<AceFavicon, "icon" | "apple_touch_icon">;
     /** Tells search engines to leave the page out, as for a draft shown in preview. */
     noindex?: boolean;
 };
@@ -471,6 +505,11 @@ type Meta = {
     name?: string;
     content: string;
 };
+type Link = {
+    rel: string;
+    href: string;
+    sizes?: string;
+};
 /** What `astro-seo`'s `<SEO>` takes (only the parts used here). */
 type AceSeoProperties = {
     title?: string;
@@ -485,6 +524,7 @@ type AceSeoProperties = {
     };
     extend: {
         meta: Meta[];
+        link?: Link[];
     };
 };
 /**
@@ -536,4 +576,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, 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 };
+export { type AceAddress, type AceClient, type AceClientOptions, type AceContentTypeHandle, type AceContentTypeSchema, type AceContentTypes, type AceDateFormat, type AceEntry, type AceFavicon, 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, type AceSite, 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

@@ -1,7 +1,7 @@
 export { pageNotices } from './chunk-XPZY5R5A.js';
 export { headingLevel, imageAttributes, isInternalPath, linkAddress, linkAttributes, listStart, renderRichText, renderTextArea, richTextImageSizes } from './chunk-FVR55GIU.js';
 export { listenForPreviewRefresh, refreshPageContent } from './chunk-YN7LJWGI.js';
-export { AcePreviewExpiredError, AceUnavailableError, createAceClient, isCurrentPage, linksFromMenu, loadMenuLinks, loadPage } from './chunk-XYOW63V6.js';
+export { AcePreviewExpiredError, AceUnavailableError, createAceClient, isCurrentPage, linksFromMenu, loadMenuLinks, loadPage } from './chunk-EKZRLWNO.js';
 export { addressFromPath, homeAddress, isHomeAddress, pathOfAddress, visitablePath } from './chunk-M5WR5TCR.js';
 export { addFramingPolicy, framingPolicy, isRefreshRequest, originOf, previewHeaders, previewParameter, previewTokenFrom, refreshMessageType, swapPageContent } from './chunk-YLO6IAXF.js';
 
@@ -160,7 +160,15 @@ function seoProperties(options) {
       ...description && { description },
       ...options.image && { image: options.image }
     },
-    extend: { meta }
+    extend: {
+      meta,
+      ...options.favicon && {
+        link: [
+          { rel: "icon", href: options.favicon.icon, sizes: "48x48" },
+          { rel: "apple-touch-icon", href: options.favicon.apple_touch_icon }
+        ]
+      }
+    }
   };
 }
 

package/dist/{main-JOA27GX6.js → main-6O2IIVHO.js}

@@ -1367,6 +1367,10 @@ function createAceClient({
     getMenu(handle) {
       return get(`/public/menus/${encodeURIComponent(handle)}`);
     },
+    /** The site itself: its name, and the social image its owners chose (null if none). */
+    getSite() {
+      return get("/public/site");
+    },
     /** What the site's content types and fields are, which is what type generation reads. */
     async getContentTypes() {
       return await get("/public/content-types") ?? [];

package/dist/react-router-server.d.ts

@@ -35,6 +35,45 @@ type AceValuesOf<Handle extends string> = Handle extends keyof AceContentTypes
   ? AceContentTypes[Handle]
   : Record<string, unknown>;
 
+/** An image as the CMS Ace public API returns it. Use `src` and `srcset` in an `<img>`. */
+type AceImageData = {
+  id: number;
+  /** The untouched original. */
+  url: string;
+  /** A web-sized copy, for browsers that ignore `srcset`. */
+  src: string;
+  /** Copies at several widths; empty when the image is too small to need them. */
+  srcset: string;
+  width: number | null;
+  height: number | null;
+  alt_text: string;
+  content_type: string;
+};
+
+/** The site's favicon as the CMS Ace public API returns it: the original, and square PNG copies. */
+type AceFavicon = {
+  id: number;
+  /** The untouched original. */
+  url: string;
+  /** A small square PNG (48 pixels), for the browser tab and search results. */
+  icon: string;
+  /** A square PNG (180 pixels), for a phone's home screen. */
+  apple_touch_icon: string;
+  content_type: string;
+};
+
+/** The site the request is for, as the CMS Ace public API returns it. */
+type AceSite = {
+  id: number;
+  name: string;
+  domain: string;
+  handle: string;
+  /** The picture the site's owners chose to show in search results and social posts; null if none. */
+  social_image: AceImageData | null;
+  /** The small picture the site's owners chose for browser tabs; null if none. */
+  favicon: AceFavicon | null;
+};
+
 /** One link of a menu as the public API returns it, with its address already worked out. */
 type AceMenuItem = {
   label: string;
@@ -107,6 +146,8 @@ declare function createAceClient({ apiUrl, siteDomain, cacheSeconds, fetchImplem
     }): Promise<AceEntry<AceValuesOf<Handle>>[]>;
     /** One of the site's navigation menus by its handle, with every link worked out; null if the site has none. */
     getMenu(handle: string): Promise<AceMenu | null>;
+    /** The site itself: its name, and the social image its owners chose (null if none). */
+    getSite(): Promise<AceSite | null>;
     /** What the site's content types and fields are, which is what type generation reads. */
     getContentTypes(): Promise<AceContentTypeSchema[]>;
 };
@@ -134,6 +175,8 @@ declare const getEntry: AceClient["getEntry"];
 declare const getEntries: AceClient["getEntries"];
 /** A navigation menu with every link worked out, or `null`. */
 declare const getMenu: (handle: string) => Promise<AceMenu | null>;
+/** The site: its name and the social image its owners chose (`social_image`, or `null`). */
+declare const getSite: () => Promise<AceSite | null>;
 /**
  * A menu's links, ready to draw. If the site has no such menu, or the CMS can't be reached, you get `fallback`
  * instead, so a missing menu never takes a page down.
@@ -223,4 +266,4 @@ declare const streamTimeout = 5000;
  */
 declare function handleRequest(request: Request, responseStatusCode: number, responseHeaders: Headers, routerContext: EntryContext, _loadContext: AppLoadContext): Promise<Response>;
 
-export { createPageLoader, createRootLoader, getAceClient, getEntries, getEntry, getMenu, getMenuLinks, handleRequest, headers, loader, streamTimeout };
+export { createPageLoader, createRootLoader, getAceClient, getEntries, getEntry, getMenu, getMenuLinks, getSite, handleRequest, headers, loader, streamTimeout };

package/dist/react-router-server.js

@@ -1,4 +1,4 @@
-import { createAceClient, loadMenuLinks, loadPage } from './chunk-XYOW63V6.js';
+import { createAceClient, loadMenuLinks, loadPage } from './chunk-EKZRLWNO.js';
 import './chunk-M5WR5TCR.js';
 import { hostedAdminOrigin, hostedApiUrl } from './chunk-N5DIMG3X.js';
 import { previewTokenFrom, addFramingPolicy } from './chunk-YLO6IAXF.js';
@@ -32,6 +32,7 @@ function getAceClient() {
 var getEntry = ((...parameters) => getAceClient().getEntry(...parameters));
 var getEntries = ((...parameters) => getAceClient().getEntries(...parameters));
 var getMenu = (handle) => getAceClient().getMenu(handle);
+var getSite = () => getAceClient().getSite();
 var getMenuLinks = (handle, options = {}) => loadMenuLinks(getAceClient(), handle, options.fallback ?? []);
 function createPageLoader() {
   return async function loader2({ request }) {
@@ -87,4 +88,4 @@ function handleRequest(request, responseStatusCode, responseHeaders, routerConte
   });
 }
 
-export { createPageLoader, createRootLoader, getAceClient, getEntries, getEntry, getMenu, getMenuLinks, handleRequest, headers, loader, streamTimeout };
+export { createPageLoader, createRootLoader, getAceClient, getEntries, getEntry, getMenu, getMenuLinks, getSite, handleRequest, headers, loader, streamTimeout };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandboxsonny/ace-kit",
-  "version": "0.8.0",
+  "version": "0.10.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",