@sandboxsonny/ace-kit 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @sandboxsonny/ace-kit
 
+## 0.2.0
+
+### Minor Changes
+
+- 801266d: Support for the CMS's new Date and Link field types.
+  
+  - `ace-kit generate` types a Date field as `string` (a day written `YYYY-MM-DD`) and a Link field as the new `AceLinkData` (`{ href, label? }`). Before, both were `unknown`.
+  - `AceLink` draws a link field: `AceLink.astro` for Astro, `AceLink` from `@sandboxsonny/ace-kit/react`, and a version from `@sandboxsonny/ace-kit/react-router` that uses the router's `Link` for pages of the site. It shows the editor's words, or yours as children, and draws nothing for an address that can't be trusted.
+  - `linkAttributes(link)` is what those components use, for sites that draw links their own way.
+  - `formatAceDate(date, format?)` turns a Date field's day into words in any language, and never shifts the day with the server's time zone.
+  
+  Needs a CMS Ace API with the Date and Link field types (the API's migration 00018). Against an older API nothing changes.
+
 ## 0.1.2
 
 ### Patch Changes

package/astro/AceLink.astro

@@ -0,0 +1,20 @@
+---
+import { linkAttributes } from "../dist/index.js";
+import type { AceLinkData } from "../dist/index.js";
+
+type Props = {
+  /** A link field's value: `entry.values.button`. */
+  link: AceLinkData;
+  class?: string;
+};
+
+const { link, class: className } = Astro.props;
+const attributes = linkAttributes(link);
+const hasContent = Astro.slots.has("default");
+---
+
+{attributes && (
+  <a href={attributes.href} class={className}>
+    {hasContent ? <slot /> : (attributes.label ?? attributes.href)}
+  </a>
+)}

package/dist/astro.d.ts

@@ -2,7 +2,7 @@
 type AceFieldSchema = {
   handle: string;
   label: string;
-  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image` or `richtext`. */
+  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image`, `richtext`, `date` or `link`. */
   component_key: string;
   config: { required?: boolean; options?: string[] } | null;
 };

package/dist/{chunk-KEV3YAWN.js → chunk-2MXND4HG.js}

@@ -1,4 +1,4 @@
-import { imageAttributes, textAreaSingleLine, textAreaParagraphs, textAreaLines, richTextImageSizes, listStart, headingLevel, linkAddress } from './chunk-URLKW2YS.js';
+import { imageAttributes, linkAttributes, textAreaSingleLine, textAreaParagraphs, textAreaLines, richTextImageSizes, listStart, headingLevel, linkAddress } from './chunk-FVR55GIU.js';
 import { listenForPreviewRefresh } from './chunk-YN7LJWGI.js';
 import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
 import { Fragment as Fragment$1, useEffect } from 'react';
@@ -7,7 +7,13 @@ function AceImage({ image, sizes, lazy, ...rest }) {
   const attributes = imageAttributes(image, { sizes, lazy });
   return /* @__PURE__ */ jsx("img", { ...rest, ...attributes });
 }
-var PlainLink = ({ href, children }) => /* @__PURE__ */ jsx("a", { href, children });
+var PlainLink = ({ href, children, className }) => /* @__PURE__ */ jsx("a", { href, className, children });
+function AceLink({ link, children, className, as: Link = PlainLink }) {
+  const attributes = linkAttributes(link);
+  if (!attributes) return null;
+  return /* @__PURE__ */ jsx(Link, { href: attributes.href, className, children: children ?? attributes.label ?? attributes.href });
+}
+var PlainLink2 = ({ href, children }) => /* @__PURE__ */ jsx("a", { href, children });
 function renderText(node, Link) {
   return (node.marks ?? []).reduce((inner, mark) => {
     if (mark.type === "bold") return /* @__PURE__ */ jsx("strong", { children: inner });
@@ -46,7 +52,7 @@ function Node({ node, Link }) {
       return null;
   }
 }
-function AceRichText({ document, link = PlainLink }) {
+function AceRichText({ document, link = PlainLink2 }) {
   return /* @__PURE__ */ jsx(Fragment, { children: renderNodes(document.content, link) });
 }
 function AceTextArea({ value, multiline = true }) {
@@ -63,4 +69,4 @@ function usePreviewRefresh(adminOrigin, refresh) {
   }, [adminOrigin, refresh]);
 }
 
-export { AceImage, AceRichText, AceTextArea, usePreviewRefresh };
+export { AceImage, AceLink, AceRichText, AceTextArea, usePreviewRefresh };

package/dist/{chunk-URLKW2YS.js → chunk-FVR55GIU.js}

@@ -26,6 +26,10 @@ function linkAddress(address) {
 function isInternalPath(address) {
   return address.startsWith("/") && !address.startsWith("//");
 }
+function linkAttributes(link) {
+  const href = linkAddress(link.href);
+  return href ? { href, label: link.label ? link.label : null } : null;
+}
 
 // src/helpers/text-area.ts
 var escapes = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
@@ -104,4 +108,4 @@ function renderRichText(document) {
   return (document.content ?? []).map(renderNode).join("");
 }
 
-export { headingLevel, imageAttributes, isInternalPath, linkAddress, listStart, renderRichText, renderTextArea, richTextImageSizes, textAreaLines, textAreaParagraphs, textAreaSingleLine };
+export { headingLevel, imageAttributes, isInternalPath, linkAddress, linkAttributes, listStart, renderRichText, renderTextArea, richTextImageSizes, textAreaLines, textAreaParagraphs, textAreaSingleLine };

package/dist/cli.js

@@ -119,6 +119,10 @@ function typeOfField(field) {
       return { type: "AceImageData", uses: "AceImageData" };
     case "richtext":
       return { type: "AceRichTextDocument", uses: "AceRichTextDocument" };
+    case "date":
+      return { type: "string" };
+    case "link":
+      return { type: "AceLinkData", uses: "AceLinkData" };
     default:
       return { type: "unknown" };
   }

package/dist/index.d.ts

@@ -13,7 +13,7 @@ type AceClientOptions = {
 type AceFieldSchema = {
   handle: string;
   label: string;
-  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image` or `richtext`. */
+  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image`, `richtext`, `date` or `link`. */
   component_key: string;
   config: { required?: boolean; options?: string[] } | null;
 };
@@ -178,6 +178,25 @@ type AceImageAttributes = {
 /** What to put on an `<img>`: a web-sized `src`, `srcset` when there are copies, and the size so the page doesn't jump. */
 declare function imageAttributes(image: AceImageData, { sizes, lazy }: AceImageOptions): AceImageAttributes;
 
+type AceDateFormat = Intl.DateTimeFormatOptions & {
+    /** A language such as "en-GB". The default is the one the server or browser runs in. */
+    locale?: string;
+};
+/**
+ * A date field's day (a text such as "2026-10-13") as words, or null if it isn't a real day. A date field holds a
+ * day with no time of day, so this never shifts it with a time zone: 13 October is 13 October everywhere.
+ */
+declare function formatAceDate(date: string, format?: AceDateFormat): string | null;
+
+/**
+ * What a link field holds in an entry's values, as visitors get it: where it goes, already worked out (a link to a
+ * page of the site is its address, such as "/pages/about"), and the words it is shown with, if the editor gave any.
+ */
+type AceLinkData = {
+  href: string;
+  label?: string;
+};
+
 /**
  * Where a link in rich text goes, or null if it can't be trusted. The CMS only allows paths, web addresses,
  * mailto: and tel:; this checks again so the page stays safe even if something else ever gets into the text.
@@ -185,6 +204,16 @@ declare function imageAttributes(image: AceImageData, { sizes, lazy }: AceImageO
 declare function linkAddress(address: string): string | null;
 /** Whether a link stays on this site: a path such as "/pages/about", not "//elsewhere", "https://..." or "mailto:...". */
 declare function isInternalPath(address: string): boolean;
+/** What to draw for a link field: where it goes and its words (null when the editor gave none). */
+type AceLinkAttributes = {
+    href: string;
+    label: string | null;
+};
+/**
+ * What a link field's value is drawn with, or null if its address can't be trusted. The CMS only allows paths, web
+ * addresses, mailto: and tel:; this checks again so the page stays safe even if something else ever gets into the data.
+ */
+declare function linkAttributes(link: AceLinkData): AceLinkAttributes | null;
 
 /** A CMS menu as links ready to draw. An entry link to the home entry goes to "/" so it isn't a redirect. */
 declare function linksFromMenu(menu: AceMenu): AceNavigationLink[];
@@ -308,4 +337,4 @@ declare const listStart: (node: AceRichTextNode) => number | undefined;
  */
 declare function renderRichText(document: AceRichTextDocument): string;
 
-export { type AceAddress, type AceClient, type AceClientOptions, type AceContentTypeHandle, type AceContentTypeSchema, type AceContentTypes, type AceEntry, type AceFieldSchema, type AceImageAttributes, type AceImageData, type AceImageOptions, type AceMenu, type AceMenuItem, type AceNavigationLink, type AcePage, AcePreviewExpiredError, type AceRichTextDocument, type AceRichTextMark, type AceRichTextNode, AceUnavailableError, type AceValuesOf, addFramingPolicy, addressFromPath, createAceClient, framingPolicy, headingLevel, homeAddress, imageAttributes, isCurrentPage, isHomeAddress, isInternalPath, isRefreshRequest, linkAddress, linksFromMenu, listStart, listenForPreviewRefresh, loadMenuLinks, loadPage, originOf, pageNotices, pathOfAddress, previewHeaders, previewParameter, previewTokenFrom, refreshMessageType, refreshPageContent, renderRichText, renderTextArea, richTextImageSizes, 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, AceUnavailableError, type AceValuesOf, addFramingPolicy, addressFromPath, createAceClient, 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, swapPageContent, visitablePath };

package/dist/index.js

@@ -1,6 +1,24 @@
 export { pageNotices } from './chunk-XPZY5R5A.js';
-export { headingLevel, imageAttributes, isInternalPath, linkAddress, listStart, renderRichText, renderTextArea, richTextImageSizes } from './chunk-URLKW2YS.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 { addressFromPath, homeAddress, isHomeAddress, pathOfAddress, visitablePath } from './chunk-M5WR5TCR.js';
 export { addFramingPolicy, framingPolicy, isRefreshRequest, originOf, previewHeaders, previewParameter, previewTokenFrom, refreshMessageType, swapPageContent } from './chunk-YLO6IAXF.js';
+
+// src/helpers/dates.ts
+var defaultFormat = { dateStyle: "long" };
+function formatAceDate(date, format = {}) {
+  const parts = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+  if (!parts) return null;
+  const [year, month, day] = [Number(parts[1]), Number(parts[2]), Number(parts[3])];
+  const moment = new Date(Date.UTC(year, month - 1, day));
+  if (moment.getUTCFullYear() !== year || moment.getUTCMonth() !== month - 1 || moment.getUTCDate() !== day)
+    return null;
+  const { locale, ...options } = format;
+  return new Intl.DateTimeFormat(locale, {
+    ...Object.keys(options).length > 0 ? options : defaultFormat,
+    timeZone: "UTC"
+  }).format(moment);
+}
+
+export { formatAceDate };

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

@@ -75,7 +75,7 @@ type AceClientOptions = {
 type AceFieldSchema = {
   handle: string;
   label: string;
-  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image` or `richtext`. */
+  /** `text`, `textarea`, `select`, `number`, `checkbox`, `image`, `richtext`, `date` or `link`. */
   component_key: string;
   config: { required?: boolean; options?: string[] } | null;
 };

package/dist/react-router.d.ts

@@ -29,6 +29,25 @@ type AceImageProps = AceImageOptions & {
 /** An image from the CMS as an `<img>` with a web-sized `src`, `srcset`, its size and its alt text. */
 declare function AceImage({ image, sizes, lazy, ...rest }: AceImageProps): react.JSX.Element;
 
+/**
+ * What a link field holds in an entry's values, as visitors get it: where it goes, already worked out (a link to a
+ * page of the site is its address, such as "/pages/about"), and the words it is shown with, if the editor gave any.
+ */
+type AceLinkData = {
+  href: string;
+  label?: string;
+};
+
+/**
+ * A link field, drawn with React Router's `Link` for a page of this site. Everything else is as `AceLink` from
+ * `@sandboxsonny/ace-kit/react`: its words by default, nothing drawn for an address that can't be trusted.
+ */
+declare function AceLink({ link, children, className, }: {
+    link: AceLinkData;
+    children?: React.ReactNode;
+    className?: string;
+}): react.JSX.Element;
+
 type AceTextAreaProps = {
     /** The text area field's value. Missing or blank draws nothing. */
     value: string | undefined;
@@ -152,4 +171,4 @@ type AceRootData = {
   };
 };
 
-export { AceImage, AceNotice, AceRichText, type AceRootData, AceTextArea, createMeta, meta, useAceMenu, useAcePreview };
+export { AceImage, AceLink, AceNotice, AceRichText, type AceRootData, AceTextArea, createMeta, meta, useAceMenu, useAcePreview };

package/dist/react-router.js

@@ -1,14 +1,22 @@
 import { pageNotices } from './chunk-XPZY5R5A.js';
-import { AceRichText, usePreviewRefresh } from './chunk-KEV3YAWN.js';
-export { AceImage, AceTextArea } from './chunk-KEV3YAWN.js';
-import { isInternalPath } from './chunk-URLKW2YS.js';
+import { AceLink, AceRichText, usePreviewRefresh } from './chunk-2MXND4HG.js';
+export { AceImage, AceTextArea } from './chunk-2MXND4HG.js';
+import { isInternalPath } from './chunk-FVR55GIU.js';
 import './chunk-YN7LJWGI.js';
 import './chunk-M5WR5TCR.js';
 import './chunk-YLO6IAXF.js';
 import { Link, useRevalidator, useRouteLoaderData } from 'react-router';
-import { jsxs, jsx } from 'react/jsx-runtime';
+import { jsx, jsxs } from 'react/jsx-runtime';
 import { useCallback } from 'react';
 
+var RouterLink = ({ href, children, className }) => isInternalPath(href) ? /* @__PURE__ */ jsx(Link, { to: href, className, children }) : /* @__PURE__ */ jsx("a", { href, className, children });
+function AceLink2({
+  link,
+  children,
+  className
+}) {
+  return /* @__PURE__ */ jsx(AceLink, { link, className, as: RouterLink, children });
+}
 function AceNotice({ page, className }) {
   const { heading, message } = pageNotices[page.kind];
   return /* @__PURE__ */ jsxs("div", { className, children: [
@@ -17,9 +25,9 @@ function AceNotice({ page, className }) {
     page.kind === "preview-expired" ? null : /* @__PURE__ */ jsx(Link, { to: "/", children: "Back to the home page" })
   ] });
 }
-var RouterLink = ({ href, children }) => isInternalPath(href) ? /* @__PURE__ */ jsx(Link, { to: href, children }) : /* @__PURE__ */ jsx("a", { href, children });
+var RouterLink2 = ({ href, children }) => isInternalPath(href) ? /* @__PURE__ */ jsx(Link, { to: href, children }) : /* @__PURE__ */ jsx("a", { href, children });
 function AceRichText2({ document }) {
-  return /* @__PURE__ */ jsx(AceRichText, { document, link: RouterLink });
+  return /* @__PURE__ */ jsx(AceRichText, { document, link: RouterLink2 });
 }
 
 // src/react-router/meta.ts
@@ -52,4 +60,4 @@ function useAcePreview() {
   usePreviewRefresh(useAceRootData()?.previewAdminOrigin, refresh);
 }
 
-export { AceNotice, AceRichText2 as AceRichText, createMeta, meta, useAceMenu, useAcePreview };
+export { AceLink2 as AceLink, AceNotice, AceRichText2 as AceRichText, createMeta, meta, useAceMenu, useAcePreview };

package/dist/react.d.ts

@@ -29,6 +29,15 @@ type AceImageProps = AceImageOptions & {
 /** An image from the CMS as an `<img>` with a web-sized `src`, `srcset`, its size and its alt text. */
 declare function AceImage({ image, sizes, lazy, ...rest }: AceImageProps): react.JSX.Element;
 
+/**
+ * What a link field holds in an entry's values, as visitors get it: where it goes, already worked out (a link to a
+ * page of the site is its address, such as "/pages/about"), and the words it is shown with, if the editor gave any.
+ */
+type AceLinkData = {
+  href: string;
+  label?: string;
+};
+
 /** A mark on a piece of text. A link's address is already worked out: an entry link comes as its path. */
 type AceRichTextMark = { type: "bold" } | { type: "italic" } | { type: "link"; attrs: { href: string } };
 
@@ -51,6 +60,7 @@ type AceRichTextDocument = { type: "doc"; content?: AceRichTextNode[] };
 type AceRichTextLink = ComponentType<{
     href: string;
     children: ReactNode;
+    className?: string;
 }>;
 type AceRichTextProps = {
     document: AceRichTextDocument;
@@ -63,6 +73,18 @@ type AceRichTextProps = {
  */
 declare function AceRichText({ document, link }: AceRichTextProps): react.JSX.Element;
 
+type AceLinkProps = {
+    /** A link field's value: `entry.values.button`. */
+    link: AceLinkData;
+    /** What to show instead of the editor's words, which are the default (or the address when there are none). */
+    children?: ReactNode;
+    className?: string;
+    /** Draws the link; the default is a plain `<a>`. Give one that uses your router's link to keep navigation client-side. */
+    as?: AceRichTextLink;
+};
+/** A link field, drawn as a link. Nothing is drawn if the address can't be trusted. */
+declare function AceLink({ link, children, className, as: Link }: AceLinkProps): react.JSX.Element | null;
+
 type AceTextAreaProps = {
     /** The text area field's value. Missing or blank draws nothing. */
     value: string | undefined;
@@ -85,4 +107,4 @@ declare function AceTextArea({ value, multiline }: AceTextAreaProps): react.JSX.
  */
 declare function usePreviewRefresh(adminOrigin: string | null | undefined, refresh?: () => Promise<void>): void;
 
-export { AceImage, AceRichText, type AceRichTextLink, AceTextArea, usePreviewRefresh };
+export { AceImage, AceLink, AceRichText, type AceRichTextLink, AceTextArea, usePreviewRefresh };

package/dist/react.js

@@ -1,5 +1,5 @@
-export { AceImage, AceRichText, AceTextArea, usePreviewRefresh } from './chunk-KEV3YAWN.js';
-import './chunk-URLKW2YS.js';
+export { AceImage, AceLink, AceRichText, AceTextArea, usePreviewRefresh } from './chunk-2MXND4HG.js';
+import './chunk-FVR55GIU.js';
 import './chunk-YN7LJWGI.js';
 import './chunk-M5WR5TCR.js';
 import './chunk-YLO6IAXF.js';

package/docs/api-reference.md

@@ -29,6 +29,13 @@ Everything below is exported from `@sandboxsonny/ace-kit` unless a path is given
 | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
 | `imageAttributes(image, { sizes, lazy? })` | The attributes for an `<img>`: `src`, `srcSet`, `sizes`, `width`, `height`, `alt`, `loading`, `decoding`, `fetchPriority`. |
 
+## Links and dates
+
+|                                |                                                                                                                                                                                                                                                                                   |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `linkAttributes(link)`         | What to draw for a link field: `{ href, label }` (`label` is `null` when the editor gave no words), or `null` if the address can't be trusted.                                                                                                                                    |
+| `formatAceDate(date, format?)` | A date field's day (`"2026-10-13"`) as words, in the language asked for (`{ locale: "en-GB" }`), or `null` if it isn't a real day. Takes the options of `Intl.DateTimeFormat`; the default is `dateStyle: "long"`. A day has no time of day, so it never shifts with a time zone. |
+
 ## Menus
 
 |                                            |                                                                            |
@@ -60,7 +67,7 @@ Everything below is exported from `@sandboxsonny/ace-kit` unless a path is given
 
 ## Types
 
-`AceEntry<Values>`, `AceImageData`, `AceMenu`, `AceMenuItem`, `AceNavigationLink`, `AceRichTextDocument`, `AceRichTextNode`, `AceRichTextMark`, `AceContentTypeSchema`, `AceFieldSchema`, `AceAddress`, `AcePage`, `AceClient`, `AceClientOptions`, `AceImageAttributes`, `AceImageOptions`, and the ones generation fills in: `AceContentTypes`, `AceContentTypeHandle`, `AceValuesOf`.
+`AceEntry<Values>`, `AceImageData`, `AceLinkData`, `AceLinkAttributes`, `AceDateFormat`, `AceMenu`, `AceMenuItem`, `AceNavigationLink`, `AceRichTextDocument`, `AceRichTextNode`, `AceRichTextMark`, `AceContentTypeSchema`, `AceFieldSchema`, `AceAddress`, `AcePage`, `AceClient`, `AceClientOptions`, `AceImageAttributes`, `AceImageOptions`, and the ones generation fills in: `AceContentTypes`, `AceContentTypeHandle`, `AceValuesOf`.
 
 ## Astro
 
@@ -76,7 +83,7 @@ Everything below is exported from `@sandboxsonny/ace-kit` unless a path is given
 | `applyPage(response, page)`                                                               | Puts a page's status and headers on a response.                                                                                                           |
 | `ace`                                                                                     | The client these use.                                                                                                                                     |
 
-Components, by file: `AceImage.astro`, `AceRichText.astro`, `AceTextArea.astro`, `AceMenu.astro`, `AceNotice.astro`, `AcePreviewRefresh.astro`.
+Components, by file: `AceImage.astro`, `AceLink.astro`, `AceRichText.astro`, `AceTextArea.astro`, `AceMenu.astro`, `AceNotice.astro`, `AcePreviewRefresh.astro`.
 
 ## React Router 7
 
@@ -84,11 +91,11 @@ Components, by file: `AceImage.astro`, `AceRichText.astro`, `AceTextArea.astro`,
 
 `@sandboxsonny/ace-kit/react-router` (browser-safe):
 
-|                                                       |                                                                      |
-| ----------------------------------------------------- | -------------------------------------------------------------------- |
-| `AceRichText`, `AceTextArea`, `AceImage`, `AceNotice` | Components; rich text links are router links.                        |
-| `createMeta({ siteName? })`, `meta`                   | The route's `meta`.                                                  |
-| `useAceMenu()`, `useAcePreview()`                     | Read the header menu; keep a preview fresh. Need `createRootLoader`. |
+|                                                                  |                                                                                   |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `AceRichText`, `AceTextArea`, `AceImage`, `AceLink`, `AceNotice` | Components; rich text links and `AceLink` are router links for pages of the site. |
+| `createMeta({ siteName? })`, `meta`                              | The route's `meta`.                                                               |
+| `useAceMenu()`, `useAcePreview()`                                | Read the header menu; keep a preview fresh. Need `createRootLoader`.              |
 
 `@sandboxsonny/ace-kit/react-router/server` (server only):
 
@@ -102,4 +109,4 @@ Components, by file: `AceImage.astro`, `AceRichText.astro`, `AceTextArea.astro`,
 
 ## React (`@sandboxsonny/ace-kit/react`)
 
-`AceImage`, `AceRichText` (with `link`), `usePreviewRefresh(adminOrigin, refresh?)`.
+`AceImage`, `AceLink` (with `as`), `AceRichText` (with `link`), `usePreviewRefresh(adminOrigin, refresh?)`.

package/docs/astro.md

@@ -69,6 +69,7 @@ Import them by file:
 ```astro
 ---
 import AceImage from "@sandboxsonny/ace-kit/astro/AceImage.astro";
+import AceLink from "@sandboxsonny/ace-kit/astro/AceLink.astro";
 import AceRichText from "@sandboxsonny/ace-kit/astro/AceRichText.astro";
 import AceTextArea from "@sandboxsonny/ace-kit/astro/AceTextArea.astro";
 import AceMenu from "@sandboxsonny/ace-kit/astro/AceMenu.astro";
@@ -78,11 +79,13 @@ import AcePreviewRefresh from "@sandboxsonny/ace-kit/astro/AcePreviewRefresh.ast
 <AceMenu handle="main-menu" />
 <AceImage image={entry.values.hero} sizes="(min-width: 64rem) 64rem, 100vw" lazy={false} />
 <AceRichText document={entry.values.body} />
+<AceLink link={entry.values.button} class="button" />
 <AcePreviewRefresh />
 ```
 
 - **AceMenu** draws a whole menu as a `<nav>` with nested lists, marking the current page with `aria-current="page"`. Props: `handle`, `fallback`, `label` (what a screen reader calls it) and `class`. It is deliberately unstyled (`.ace-menu`, `.ace-menu__list`, `.ace-menu__sublist` are the hooks); to control the markup, use `getMenuLinks` and draw it yourself.
 - **AceImage** writes an `<img>` with `src`, `srcset`, `sizes`, `width`, `height`, `alt`, `loading` and `decoding`. Set `sizes` to how wide the image is shown, and `lazy={false}` for the image at the top of the page.
+- **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.
 - **AcePreviewRefresh** goes once in your layout. It does nothing unless the page was opened by the CMS's editor.

package/docs/react-router.md

@@ -93,6 +93,7 @@ export default function App() {
 From `@sandboxsonny/ace-kit/react-router` (these are safe in the browser):
 
 - **AceRichText** draws a rich text field. Links to pages of this site are router `Link`s, so navigating doesn't reload the page. It renders bare elements; style them from a wrapper.
+- **AceLink** draws a link field. A link to a page of this site is a router `Link`; any other is a plain `<a>`. It shows the editor's words (or the address), or your children instead, and draws nothing for an address that can't be trusted. Dates are text: format them with `formatAceDate` from `@sandboxsonny/ace-kit`.
 - **AceTextArea** draws a Textarea field (plain text): `multiline` (the default) makes paragraphs and line breaks, `multiline={false}` is one line of text.
 - **AceImage** is an `<img>` with `src`, `srcset`, `sizes`, size and alt text. Set `sizes` to how wide it is shown, and `lazy={false}` for the image at the top of the page.
 - **AceNotice** is the heading and message for a page that isn't an entry. Give it a `className`.

package/docs/react.md

@@ -3,7 +3,7 @@
 Needs `react` 18 or newer. The components work with any React framework (React Router, Next.js, Remix, plain Vite). **On React Router 7, use the [React Router adapter](./react-router.md) instead of wiring this up yourself.** Fetch with the [client](./getting-started.md#the-client) on the server (a loader, a server component, `getServerSideProps`), then draw.
 
 ```tsx
-import { AceImage, AceRichText } from "@sandboxsonny/ace-kit/react";
+import { AceImage, AceLink, AceRichText } from "@sandboxsonny/ace-kit/react";
 ```
 
 ## AceImage
@@ -14,6 +14,18 @@ import { AceImage, AceRichText } from "@sandboxsonny/ace-kit/react";
 
 An `<img>` with `src`, `srcset`, `sizes`, `width`, `height` and `alt`. Any other `<img>` prop (`className`, `style`, `onLoad`...) is passed through. `lazy` defaults to `true`; turn it off for the image at the top of the page.
 
+## AceLink
+
+```tsx
+{
+  entry.values.button ? <AceLink link={entry.values.button} className="button" /> : null;
+}
+```
+
+A link field as an `<a>` with the editor's words, or the address when there are none; children replace the words. Nothing is drawn if the address can't be trusted. Give it your router's link with `as` so navigation stays in the browser (`as={({ href, children, className }) => <Link to={href} className={className}>{children}</Link>}`).
+
+A date field is text: `formatAceDate(entry.values.published, { locale: "en-GB" })` gives "13 October 2026" whatever the server's time zone, and `<time dateTime={entry.values.published}>` takes the raw value.
+
 ## AceRichText
 
 ```tsx

package/docs/typed-content.md

@@ -35,15 +35,17 @@ about?.values.headline; // string
 cms.getEntry("pagez", "about"); // type error: no such content type
 ```
 
-| Field                            | Type                                                |
-| -------------------------------- | --------------------------------------------------- |
-| Text, Textarea                   | `string`                                            |
-| Number                           | `number`                                            |
-| Checkbox                         | `boolean`                                           |
-| Select                           | a union of its options, e.g. `"formal" \| "casual"` |
-| Image                            | `AceImageData`                                      |
-| Rich text                        | `AceRichTextDocument`                               |
-| a kind this version doesn't know | `unknown`                                           |
+| Field                            | Type                                                       |
+| -------------------------------- | ---------------------------------------------------------- |
+| Text, Textarea                   | `string`                                                   |
+| Number                           | `number`                                                   |
+| Checkbox                         | `boolean`                                                  |
+| Select                           | a union of its options, e.g. `"formal" \| "casual"`        |
+| Image                            | `AceImageData`                                             |
+| Rich text                        | `AceRichTextDocument`                                      |
+| Date                             | `string`, a day written `YYYY-MM-DD` (see `formatAceDate`) |
+| Link                             | `AceLinkData`: `{ href, label? }`                          |
+| a kind this version doesn't know | `unknown`                                                  |
 
 A field is optional unless it is marked required in the CMS. Before you generate, handles are plain `string` and values are `Record<string, unknown>`, so nothing breaks.
 

package/package.json

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