@cancia/astro 0.6.0 → 0.8.0

package/dist/schema/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 export { z } from 'zod';
-export { P as PT_DECORATORS, a as PT_LIST_ITEMS, b as PT_STYLES, c as PortableTextValue, d as PtBlock, e as PtDecorator, f as PtLinkMarkDef, g as PtListItem, h as PtSpan, i as PtStyle, j as isSafeHref, p as portableTextSubsetSchema, k as ptBlockSchema } from '../portable-text-BikSqS9T.js';
+export { P as PT_DECORATORS, a as PT_LIST_ITEMS, b as PT_STYLES, c as PortableTextValue, d as PtBlock, e as PtDecorator, f as PtLinkMarkDef, g as PtListItem, h as PtSpan, i as PtStyle, j as isSafeHref, p as parseRichValue, k as portableTextSubsetSchema, l as ptBlockSchema, s as serializeRichValue } from '../portable-text-D74aIuHn.js';
 
 /**
  * Widget hint the modal form uses to pick an input element. The Zod type
@@ -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"). */
@@ -80,6 +82,21 @@ interface ListSchemaOptions<TFields extends Record<string, z.ZodTypeAny>> {
      * Defaults to the entry ID. The server validates slug uniqueness on save.
      */
     slugField?: keyof TFields & string;
+    /**
+     * Field name holding the entry's draft flag. When set, `canciaLoader`
+     * omits entries whose value is truthy from the content collection, so a
+     * draft never reaches the built site.
+     *
+     * The field MUST be a boolean with a default (`defineField.draft()` gives
+     * you exactly that) — an `undefined` draft flag reads as published, which
+     * is the safe direction for the pre-existing entries of a list that adds
+     * `draftField` later.
+     *
+     * Draft is deliberately per-list opt-in rather than an implicit field on
+     * every list: a list of office locations or nav links has no meaningful
+     * draft state, and a phantom "Draft" checkbox on every form is noise.
+     */
+    draftField?: keyof TFields & string;
     /** Field definitions. */
     fields: TFields;
 }
@@ -89,10 +106,24 @@ interface ListSchema<TFields extends Record<string, z.ZodTypeAny> = Record<strin
     titleField: string;
     bodyField: string | undefined;
     slugField: string | undefined;
+    draftField: string | undefined;
     fields: TFields;
     /** Zod object schema combining all fields, for one-shot validation. */
     validator: z.ZodObject<TFields>;
 }
+/**
+ * True when `entry.data` is a draft under `schema.draftField`.
+ *
+ * The single source of truth for "is this entry a draft" — the loader, the
+ * toolbar preview rows and any user-side filter all call THIS, so a draft is
+ * decided identically everywhere. Vite-free and dependency-free by design.
+ *
+ * Reads as published (`false`) when the list declares no draftField, when the
+ * field is absent, or when it is `undefined` — every ambiguous case resolves
+ * to "published", matching the field's own default and keeping entries that
+ * predate the draftField visible.
+ */
+declare function isDraft(schema: Pick<ListSchema, "draftField">, data: Record<string, unknown>): boolean;
 declare function defineList<TFields extends Record<string, z.ZodTypeAny>>(opts: ListSchemaOptions<TFields>): ListSchema<TFields>;
 /**
  * One field as seen by the modal form. Plain JSON, no Zod refs.
@@ -152,6 +183,15 @@ declare const defineField: {
     email: (o?: PlainFieldOptions) => z.ZodString;
     datetime: (o?: PlainFieldOptions) => z.ZodString;
     checkbox: (o?: PlainFieldOptions) => z.ZodBoolean;
+    /**
+     * The draft flag for a list's `draftField`. A checkbox that DEFAULTS to
+     * false, which is what makes it safe to add to an existing list: every
+     * stored entry that predates the field validates and reads as published
+     * rather than vanishing from the built site.
+     *
+     * Label defaults to "Draft" so the affordance reads the same on every list.
+     */
+    draft: (o?: PlainFieldOptions) => z.ZodDefault<z.ZodBoolean>;
     number: (o?: PlainFieldOptions & {
         min?: number;
         max?: number;
@@ -194,6 +234,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,
@@ -240,6 +304,11 @@ interface ListDescription {
     titleField: string;
     bodyField?: string;
     slugField?: string;
+    /**
+     * Field holding the draft flag, when the list opts in. The toolbar uses it
+     * to badge unpublished rows; the loader uses it to omit them from the build.
+     */
+    draftField?: string;
     fields: FieldDescription[];
 }
 /**
@@ -257,7 +326,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, isDraft, isExternalHref, parseLinkValue, serializeLinkValue, slugify };

package/dist/schema/index.js

@@ -2,17 +2,23 @@ import {
   defineField,
   defineList,
   describeList,
+  isDraft,
+  isExternalHref,
+  parseLinkValue,
+  serializeLinkValue,
   slugify,
   z
-} from "../chunk-MCHQV6Y7.js";
+} from "../chunk-WVHTCFE6.js";
 import {
   PT_DECORATORS,
   PT_LIST_ITEMS,
   PT_STYLES,
   isSafeHref,
+  parseRichValue,
   portableTextSubsetSchema,
-  ptBlockSchema
-} from "../chunk-BOIQNZAO.js";
+  ptBlockSchema,
+  serializeRichValue
+} from "../chunk-KHCFVVYV.js";
 export {
   PT_DECORATORS,
   PT_LIST_ITEMS,
@@ -20,9 +26,15 @@ export {
   defineField,
   defineList,
   describeList,
+  isDraft,
+  isExternalHref,
   isSafeHref,
+  parseLinkValue,
+  parseRichValue,
   portableTextSubsetSchema,
   ptBlockSchema,
+  serializeLinkValue,
+  serializeRichValue,
   slugify,
   z
 };

package/dist/schema/loader.d.ts

@@ -0,0 +1,23 @@
+import { ListSchema, SchemasModule } from './index.js';
+import 'zod';
+import '../portable-text-D74aIuHn.js';
+
+/**
+ * Resolve the absolute path to the user's schemas.ts. Returns null if no
+ * file exists at the expected location.
+ */
+declare function resolveSchemasPath(projectRoot: string, overridePath?: string): string | null;
+/**
+ * Load (and cache) the user's schemas module. Returns an empty map if no
+ * schemas.ts exists — the inline editor still works for KV edits without
+ * any lists defined.
+ */
+declare function loadSchemas(projectRoot: string, overridePath?: string): Promise<SchemasModule>;
+/**
+ * Get a single list schema, or null if it doesn't exist.
+ */
+declare function loadListSchema(projectRoot: string, listName: string, overridePath?: string): Promise<ListSchema | null>;
+/** For tests — drop the in-memory cache. */
+declare function clearSchemaCache(): void;
+
+export { clearSchemaCache, loadListSchema, loadSchemas, resolveSchemasPath };

package/dist/schema/loader.js

@@ -0,0 +1,12 @@
+import {
+  clearSchemaCache,
+  loadListSchema,
+  loadSchemas,
+  resolveSchemasPath
+} from "../chunk-VL6FO446.js";
+export {
+  clearSchemaCache,
+  loadListSchema,
+  loadSchemas,
+  resolveSchemasPath
+};

package/dist/transform/text-helper.d.ts

@@ -0,0 +1,47 @@
+import { ContentMap } from '../content.js';
+
+/** Test/dev hook — a content change must not be served from a stale cache. */
+declare function clearTextCache(): void;
+interface TextHelperConfig {
+    site: string;
+    lang: string;
+    /** Reads the whole content map. Injected so this module imports no adapter. */
+    read: () => Promise<ContentMap>;
+}
+declare function configureTextHelper(next: TextHelperConfig): void;
+/**
+ * Load the content map. Awaited once per page, in frontmatter.
+ *
+ * NEVER throws or rejects. A content read must not break a build — the same rule
+ * createContentReader holds — so every failure resolves to an empty map, and
+ * every call site then falls back to the text authored in the page. A site whose
+ * database is unreachable renders exactly as its source says.
+ */
+declare function __canciaContent(): Promise<ContentMap>;
+/**
+ * Resolve one annotated element's text.
+ *
+ * `??` is load-bearing, not style: a stored "" means DELIBERATELY EMPTY (the
+ * client removed this text on purpose) and must NOT fall through to the authored
+ * fallback, or deleted content reappears on every build.
+ */
+declare function __canciaText(cms: ContentMap, key: string, fallback: string): string;
+interface LinkValue {
+    label: string;
+    href: string;
+}
+/**
+ * Resolve a link field — label AND href from one stored value.
+ *
+ * A link stores `{label, href}` as JSON so a new label can never be saved
+ * against a stale href. Both halves have an authored fallback (the text, and the
+ * `href=` already in the markup), which is why a link needs no t() call either.
+ *
+ * An unsafe href is DROPPED on read, falling back to the authored one — the same
+ * rule parseLinkValue holds, and for the same reason: validation guards the
+ * write path, but a value can reach a renderer from an older row or a
+ * hand-edited DB, so the read is where the guarantee has to hold.
+ */
+declare function __canciaLink(cms: ContentMap, key: string, labelFallback: string, hrefFallback: string): LinkValue;
+
+export { type LinkValue, type TextHelperConfig, __canciaContent, __canciaLink, __canciaText, clearTextCache, configureTextHelper };

package/dist/transform/text-helper.js

@@ -0,0 +1,64 @@
+// src/transform/text-helper.ts
+var contentPromise = null;
+function clearTextCache() {
+  contentPromise = null;
+}
+var config = null;
+function configureTextHelper(next) {
+  config = next;
+  contentPromise = null;
+}
+async function __canciaContent() {
+  if (!config) return {};
+  try {
+    if (!contentPromise) contentPromise = config.read();
+    return await contentPromise;
+  } catch {
+    contentPromise = null;
+    return {};
+  }
+}
+function lang() {
+  return config?.lang ?? "en";
+}
+function __canciaText(cms, key, fallback) {
+  return cms[`${key}.${lang()}`] ?? fallback;
+}
+function isSafeHref(href) {
+  const trimmed = href.trim();
+  if (trimmed === "") return true;
+  if (/^(https?:|mailto:|tel:)/i.test(trimmed)) return true;
+  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(trimmed);
+  if (scheme) {
+    const firstSep = trimmed.search(/[/?#]/);
+    if (firstSep === -1 || scheme[1].length < firstSep) return false;
+  }
+  return true;
+}
+function __canciaLink(cms, key, labelFallback, hrefFallback) {
+  const fallback = { label: labelFallback, href: hrefFallback };
+  const raw = cms[`${key}.${lang()}`];
+  if (raw === void 0) return fallback;
+  if (raw === "") return { label: "", href: "" };
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("{")) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      const href = String(parsed.href ?? "");
+      return {
+        label: String(parsed.label ?? "") || labelFallback,
+        href: href && isSafeHref(href) ? href : hrefFallback
+      };
+    } catch {
+      return fallback;
+    }
+  }
+  return { label: raw, href: hrefFallback };
+}
+export {
+  __canciaContent,
+  __canciaLink,
+  __canciaText,
+  clearTextCache,
+  configureTextHelper
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cancia/astro",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Astro integration for Cancia CMS — inline editing with zero separate server",
   "license": "MIT",
   "repository": {
@@ -20,6 +20,10 @@
       "types": "./dist/schema/index.d.ts",
       "import": "./dist/schema/index.js"
     },
+    "./schema-loader": {
+      "types": "./dist/schema/loader.d.ts",
+      "import": "./dist/schema/loader.js"
+    },
     "./loader": {
       "types": "./dist/loader/index.d.ts",
       "import": "./dist/loader/index.js"
@@ -40,7 +44,8 @@
       "types": "./dist/richtext/index.d.ts",
       "import": "./dist/richtext/index.js"
     },
-    "./richtext/CanciaRichText.astro": "./dist/richtext/CanciaRichText.astro"
+    "./richtext/CanciaRichText.astro": "./dist/richtext/CanciaRichText.astro",
+    "./richtext/CanciaRichRegion.astro": "./dist/richtext/CanciaRichRegion.astro"
   },
   "files": [
     "dist"
@@ -68,7 +73,8 @@
   },
   "dependencies": {
     "astro-portabletext": "^0.13.0",
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "@astrojs/compiler": "^2.10.0"
   },
   "scripts": {
     "build": "tsup",