@cancia/astro 0.6.0 → 0.7.0

package/dist/{chunk-MCHQV6Y7.js → chunk-UMCBQXB6.js}

@@ -1,4 +1,5 @@
 import {
+  isSafeHref,
   portableTextSubsetSchema
 } from "./chunk-BOIQNZAO.js";
 
@@ -56,6 +57,30 @@ var defineField = {
    *   related: f.array(f.reference({ list: "posts" }), { label: "Related" }),
    */
   reference: (o) => z.string().meta({ widget: "reference", ...o }),
+  /**
+   * A link: label + href as ONE unit.
+   *
+   * A button/CTA is two values that must stay together — saving a new label
+   * against a stale href produces a broken call-to-action, so they are stored
+   * as a single object rather than two flat keys that could drift.
+   *
+   *   cta: f.link({ label: "Primary CTA" }),
+   *
+   * `href` is NOT z.url(): a relative href ("/start", "#programmes") and a
+   * mailto:/tel: are all legitimate and z.url() rejects the relative forms.
+   * It IS constrained by `isSafeHref` — the SAME guard richtext link marks
+   * use — so a stored value can never carry a javascript:/data: XSS payload.
+   * Without this, the link widget would be a hole around a protection
+   * richtext already enforces.
+   *
+   * Whether to open in a new tab is derived from the href at render time
+   * (see `isExternalHref`) instead of being stored — one less thing that can
+   * fall out of sync with the URL it describes.
+   */
+  link: (o) => z.object({
+    label: z.string(),
+    href: z.string().refine(isSafeHref, "unsafe or unsupported URL scheme")
+  }).meta({ widget: "link", ...o }),
   /**
    * A constrained rich-text body. Stored as a Portable-Text SUBSET array (D4):
    * block styles normal/h2/h3/blockquote, bullet/number lists, strong/em marks,
@@ -145,11 +170,43 @@ function describeList(name, schema) {
     fields
   };
 }
+function parseLinkValue(raw) {
+  const safe = (href) => isSafeHref(href) ? href : "";
+  if (raw && typeof raw === "object") {
+    const o = raw;
+    return { label: String(o.label ?? ""), href: safe(String(o.href ?? "")) };
+  }
+  if (typeof raw !== "string" || raw === "") return { label: "", href: "" };
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("{")) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (parsed && typeof parsed === "object") {
+        return {
+          label: String(parsed.label ?? ""),
+          href: safe(String(parsed.href ?? ""))
+        };
+      }
+    } catch {
+    }
+  }
+  return { label: raw, href: "" };
+}
+function serializeLinkValue(value) {
+  return JSON.stringify({ label: value.label ?? "", href: value.href ?? "" });
+}
+function isExternalHref(href) {
+  if (!href) return false;
+  return /^https?:\/\//i.test(href);
+}
 
 export {
   z,
   defineList,
   defineField,
   slugify,
-  describeList
+  describeList,
+  parseLinkValue,
+  serializeLinkValue,
+  isExternalHref
 };

package/dist/{chunk-IIGDU5SV.js → chunk-VFMOVGMC.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-NG5GJME5.js";
 import {
   describeList
-} from "./chunk-MCHQV6Y7.js";
+} from "./chunk-UMCBQXB6.js";
 
 // src/routes/schemas.ts
 function json(body, status = 200) {

package/dist/content.d.ts

@@ -2,6 +2,13 @@
 type ContentMap = Record<string, string>;
 /** A translator: `(key, fallback) => cms[`${key}.${lang}`] ?? fallback`. */
 type Translate = (key: string, fallback: string) => string;
+/** The value behind a `link` field: a label and where it points. */
+interface LinkValue {
+    label: string;
+    href: string;
+}
+/** Resolve a link field, falling back to the values authored in the page. */
+type TranslateLink = (key: string, fallback: LinkValue) => LinkValue;
 interface ContentReaderOptions {
     /** Site id (the `?site=` query param and the storage `site` column). */
     site: string;
@@ -44,9 +51,16 @@ interface ContentReader {
     getCMS(): Promise<ContentMap>;
     /** Build a translator over a content map for the reader's `lang`. */
     makeT(cms: ContentMap): Translate;
-    /** Sugar: `const { t, cms } = await reader.get()` in a page's frontmatter. */
+    /**
+     * Build a link resolver over a content map. A link field stores
+     * `{label, href}` as JSON; this parses it and falls back to the values
+     * authored in the page. Never throws; drops an unsafe href.
+     */
+    makeTLink(cms: ContentMap): TranslateLink;
+    /** Sugar: `const { t, tLink, cms } = await reader.get()` in frontmatter. */
     get(): Promise<{
         t: Translate;
+        tLink: TranslateLink;
         cms: ContentMap;
     }>;
 }
@@ -57,4 +71,4 @@ interface ContentReader {
  */
 declare function createContentReader(opts: ContentReaderOptions): ContentReader;
 
-export { type ContentMap, type ContentReader, type ContentReaderOptions, type Translate, createContentReader };
+export { type ContentMap, type ContentReader, type ContentReaderOptions, type LinkValue, type Translate, type TranslateLink, createContentReader };

package/dist/content.js

@@ -8,6 +8,35 @@ import "./chunk-L2VKQJPY.js";
 import "./chunk-7IA5B5CF.js";
 
 // src/content.ts
+function isSafeHref(href) {
+  const trimmed = href.trim();
+  if (trimmed === "") return false;
+  if (/^(https?:|mailto:|tel:)/i.test(trimmed)) return true;
+  const schemeMatch = /^([a-z][a-z0-9+.-]*):/i.exec(trimmed);
+  if (schemeMatch) {
+    const firstSep = trimmed.search(/[/?#]/);
+    if (firstSep === -1 || schemeMatch[1].length < firstSep) return false;
+  }
+  return true;
+}
+function parseLink(raw, fallback) {
+  if (!raw) return fallback;
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("{")) {
+    try {
+      const p = JSON.parse(trimmed);
+      if (p && typeof p === "object") {
+        const href = String(p.href ?? "");
+        return {
+          label: String(p.label ?? "") || fallback.label,
+          href: href && isSafeHref(href) ? href : fallback.href
+        };
+      }
+    } catch {
+    }
+  }
+  return { label: raw, href: fallback.href };
+}
 function createContentReader(opts) {
   const site = opts.site;
   const lang = opts.lang ?? "en";
@@ -41,11 +70,14 @@ function createContentReader(opts) {
   function makeT(cms) {
     return (key, fallback) => cms[`${key}.${lang}`] ?? fallback;
   }
+  function makeTLink(cms) {
+    return (key, fallback) => parseLink(cms[`${key}.${lang}`], fallback);
+  }
   async function get() {
     const cms = await getCMS();
-    return { t: makeT(cms), cms };
+    return { t: makeT(cms), tLink: makeTLink(cms), cms };
   }
-  return { getCMS, makeT, get };
+  return { getCMS, makeT, makeTLink, get };
 }
 export {
   createContentReader

package/dist/endpoints/schemas.js

@@ -1,8 +1,8 @@
 import {
   makeSchemasRoute
-} from "../chunk-IIGDU5SV.js";
+} from "../chunk-VFMOVGMC.js";
 import "../chunk-NG5GJME5.js";
-import "../chunk-MCHQV6Y7.js";
+import "../chunk-UMCBQXB6.js";
 import "../chunk-BOIQNZAO.js";
 
 // src/endpoints/schemas.ts

package/dist/index.js

@@ -6,7 +6,7 @@ import {
 } from "./chunk-22DJVJBR.js";
 import {
   makeSchemasRoute
-} from "./chunk-IIGDU5SV.js";
+} from "./chunk-VFMOVGMC.js";
 import "./chunk-NG5GJME5.js";
 import {
   makeLocalUploadHandler,
@@ -20,7 +20,7 @@ import {
   defineList,
   describeList,
   z
-} from "./chunk-MCHQV6Y7.js";
+} from "./chunk-UMCBQXB6.js";
 import {
   canciaLoader
 } from "./chunk-UR5WC3RA.js";

package/dist/schema/index.d.ts

@@ -16,7 +16,7 @@ export { P as PT_DECORATORS, a as PT_LIST_ITEMS, b as PT_STYLES, c as PortableTe
  *   z.boolean()          → "checkbox"
  *   z.enum([...])        → "select"
  */
-type FieldWidget = "text" | "textarea" | "url" | "email" | "datetime" | "number" | "checkbox" | "select" | "image" | "slug" | "array" | "object" | "reference" | "richtext";
+type FieldWidget = "text" | "textarea" | "url" | "email" | "datetime" | "number" | "checkbox" | "select" | "image" | "slug" | "array" | "object" | "reference" | "richtext" | "link";
 /**
  * Fields common to every widget's metadata. All optional.
  */
@@ -61,6 +61,8 @@ type FieldMeta = (FieldMetaBase & {
     list: string;
 }) | (FieldMetaBase & {
     widget: "richtext";
+}) | (FieldMetaBase & {
+    widget: "link";
 });
 interface ListSchemaOptions<TFields extends Record<string, z.ZodTypeAny>> {
     /** Display label for the list (e.g. "Blog Posts"). */
@@ -194,6 +196,30 @@ declare const defineField: {
     reference: (o: FieldMetaBase & {
         list: string;
     }) => z.ZodString;
+    /**
+     * A link: label + href as ONE unit.
+     *
+     * A button/CTA is two values that must stay together — saving a new label
+     * against a stale href produces a broken call-to-action, so they are stored
+     * as a single object rather than two flat keys that could drift.
+     *
+     *   cta: f.link({ label: "Primary CTA" }),
+     *
+     * `href` is NOT z.url(): a relative href ("/start", "#programmes") and a
+     * mailto:/tel: are all legitimate and z.url() rejects the relative forms.
+     * It IS constrained by `isSafeHref` — the SAME guard richtext link marks
+     * use — so a stored value can never carry a javascript:/data: XSS payload.
+     * Without this, the link widget would be a hole around a protection
+     * richtext already enforces.
+     *
+     * Whether to open in a new tab is derived from the href at render time
+     * (see `isExternalHref`) instead of being stored — one less thing that can
+     * fall out of sync with the URL it describes.
+     */
+    link: (o?: FieldMetaBase) => z.ZodObject<{
+        label: z.ZodString;
+        href: z.ZodString;
+    }, z.core.$strip>;
     /**
      * A constrained rich-text body. Stored as a Portable-Text SUBSET array (D4):
      * block styles normal/h2/h3/blockquote, bullet/number lists, strong/em marks,
@@ -257,7 +283,38 @@ interface ListDescription {
  */
 declare function slugify(input: string): string;
 declare function describeList(name: string, schema: ListSchema): ListDescription;
+/** The value behind a `link` widget: a label and where it points. */
+interface LinkValue {
+    label: string;
+    href: string;
+}
+/**
+ * Parse a stored link value. NEVER throws.
+ *
+ * The KV surface stores every value as a string, so a link round-trips as
+ * JSON. Three cases must all degrade gracefully rather than break a render:
+ *
+ *   - proper JSON object  → used as-is (missing halves coerced to "")
+ *   - a bare string       → treated as the LABEL with an empty href. This is
+ *                           the migration path for a field that used to be
+ *                           `text`, and for a fallback authored in markup.
+ *   - empty / malformed   → `{ label: "", href: "" }`
+ *
+ * A content read must never throw (same rule as createContentReader).
+ */
+declare function parseLinkValue(raw: unknown): LinkValue;
+/** Serialize a link value for storage. The inverse of `parseLinkValue`. */
+declare function serializeLinkValue(value: LinkValue): string;
+/**
+ * Should this href open in a new tab? Derived, never stored.
+ *
+ * External = has a scheme+host that isn't the current origin. Relative hrefs
+ * ("/start", "#programmes") and mailto:/tel: are NOT external — mailto/tel
+ * hand off to another app, and forcing target=_blank on them leaves a blank
+ * tab behind.
+ */
+declare function isExternalHref(href: string): boolean;
 /** Map of list name → schema. What users export from src/cms/schemas.ts. */
 type SchemasModule = Record<string, ListSchema>;
 
-export { type FieldDescription, type FieldMeta, type FieldMetaBase, type FieldWidget, type ListDescription, type ListSchema, type ListSchemaOptions, type SchemasModule, defineField, defineList, describeList, slugify };
+export { type FieldDescription, type FieldMeta, type FieldMetaBase, type FieldWidget, type LinkValue, type ListDescription, type ListSchema, type ListSchemaOptions, type SchemasModule, defineField, defineList, describeList, isExternalHref, parseLinkValue, serializeLinkValue, slugify };

package/dist/schema/index.js

@@ -2,9 +2,12 @@ import {
   defineField,
   defineList,
   describeList,
+  isExternalHref,
+  parseLinkValue,
+  serializeLinkValue,
   slugify,
   z
-} from "../chunk-MCHQV6Y7.js";
+} from "../chunk-UMCBQXB6.js";
 import {
   PT_DECORATORS,
   PT_LIST_ITEMS,
@@ -20,9 +23,12 @@ export {
   defineField,
   defineList,
   describeList,
+  isExternalHref,
   isSafeHref,
+  parseLinkValue,
   portableTextSubsetSchema,
   ptBlockSchema,
+  serializeLinkValue,
   slugify,
   z
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cancia/astro",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Astro integration for Cancia CMS — inline editing with zero separate server",
   "license": "MIT",
   "repository": {