@karibsen/eponyme 0.7.0 → 0.8.0

package/dist/runtime/types/eponyme.d.ts

@@ -1,4 +1,4 @@
-import type { ArrayFieldDefinition, ArrayItemValue, BooleanFieldDefinition, CheckboxGroupFieldDefinition, EmailFieldDefinition, FieldDefinition, NumberFieldDefinition, PhoneFieldDefinition, RadioFieldDefinition, SectionFieldDefinition, SectionValue, SelectFieldDefinition, SlugFieldDefinition, StringFieldDefinition, TabFieldDefinition, TabsValue, TextareaFieldDefinition, UrlFieldDefinition, UrlValue } from './field.js';
+import type { ArrayFieldDefinition, ArrayItemValue, BooleanFieldDefinition, CheckboxGroupFieldDefinition, EmailFieldDefinition, FieldDefinition, NumberFieldDefinition, PhoneFieldDefinition, RadioFieldDefinition, SectionFieldDefinition, SectionValue, SelectFieldDefinition, SlugFieldDefinition, StringFieldDefinition, TabFieldDefinition, TagsFieldDefinition, TagsValueOf, TabsValue, TextareaFieldDefinition, UrlFieldDefinition, UrlValue } from './field.js';
 export type EponymeSchema = Record<string, FieldDefinition>;
 export interface EponymeCollectionDefinitionBase {
     __eponymeCollection: true;
@@ -65,7 +65,7 @@ export type FieldValue<T extends FieldDefinition> = T extends {
     type: 'number';
 } ? number : T extends {
     type: 'boolean';
-} ? boolean : T extends UrlFieldDefinition ? UrlValue : T extends ArrayFieldDefinition<infer Item> ? Array<ArrayItemValue<Item>> : T extends CheckboxGroupFieldDefinition<infer Value> ? Value[] : T extends SectionFieldDefinition<infer Section> ? SectionValue<Section> : T extends TabFieldDefinition<infer Tabs> ? TabsValue<Tabs> : string;
+} ? boolean : T extends UrlFieldDefinition ? UrlValue : T extends ArrayFieldDefinition<infer Item> ? Array<ArrayItemValue<Item>> : T extends CheckboxGroupFieldDefinition<infer Value> ? Value[] : T extends TagsFieldDefinition<infer Options> ? Array<TagsValueOf<Options>> : T extends SectionFieldDefinition<infer Section> ? SectionValue<Section> : T extends TabFieldDefinition<infer Tabs> ? TabsValue<Tabs> : string;
 export type EponymeData<T extends EponymeSchema> = {
     [K in keyof T]: T[K] extends FieldDefinition ? FieldValue<T[K]> : never;
 };
@@ -74,6 +74,57 @@ export type EponymeCollectionName<T extends EponymeConfig> = {
     [K in keyof T & string]: T[K] extends EponymeCollectionDefinitionBase ? K : T[K] extends EponymeFormDefinitionBase ? never : T[K] extends EponymeSchema ? never : T[K] extends EponymeConfig ? `${K}/${EponymeCollectionName<T[K]>}` : never;
 }[keyof T & string];
 export type EponymeCollectionDataByName<T extends EponymeConfig, Name extends EponymeCollectionName<T>> = EponymeCollectionAtPath<T, Name> extends EponymeCollectionDefinition<infer Schema> ? EponymeData<Schema> : never;
+/**
+ * Field types a `where` can filter on, mirroring the write path's `INDEXABLE_TYPES`.
+ *
+ * The two lists are separate because one runs on values and the other on types, but they
+ * describe the same rule: a filterable field is one whose stored form compares correctly as
+ * text. That is why `date` is here — validation pins it to `YYYY-MM-DD` — and `number` is
+ * not, since `'10'` sorts before `'9'`.
+ */
+type FilterableFieldType = 'tags' | 'checkboxGroup' | 'select' | 'radio' | 'boolean' | 'date';
+/** A multi-valued field is filtered by one of its items, not by the whole list. */
+type FilterOperand<T extends FieldDefinition> = FieldValue<T> extends readonly (infer Item)[] ? Item : FieldValue<T>;
+/**
+ * Bounds, offered only where alphabetical order is the value's natural order — which is
+ * `field.date()`, pinned by validation to `YYYY-MM-DD`. On a tag or a select, comparing
+ * with `gte` would sort labels, which answers no question anyone asks.
+ */
+export interface EponymeFilterBounds {
+    gte?: string;
+    lte?: string;
+    gt?: string;
+    lt?: string;
+}
+type FilterOperators<T extends FieldDefinition> = {
+    /** Any of these, the same as passing the list directly. */
+    in?: readonly FilterOperand<T>[];
+    /** None of these. Combines with the positive operators to narrow then subtract. */
+    not?: FilterOperand<T> | readonly FilterOperand<T>[];
+    /**
+     * Substring of the stored value, case-insensitive.
+     *
+     * The only operator that cannot use the index's ordering — a leading wildcard scans it.
+     * That still reads a narrow table instead of every entry's content, but it does not
+     * scale the way the others do.
+     */
+    contains?: string;
+} & (T extends {
+    type: 'date';
+} ? EponymeFilterBounds : unknown);
+/** The values of one key are ORed; the keys of a `where` are ANDed. */
+export type EponymeFieldFilter<T extends FieldDefinition> = FilterOperand<T> | readonly FilterOperand<T>[] | FilterOperators<T>;
+/**
+ * The filter a schema accepts, keyed by field name. Nested fields are left out: a field
+ * inside a section, a tab or an array has no single key to name it by, which is the same
+ * reason `orderBy` cannot reach one.
+ */
+export type EponymeFilterInput<T extends EponymeSchema> = {
+    [K in keyof T as T[K] extends {
+        type: FilterableFieldType;
+    } ? K : never]?: T[K] extends FieldDefinition ? EponymeFieldFilter<T[K]> : never;
+};
+export type EponymeCollectionFilter<T extends EponymeConfig, Name extends EponymeCollectionName<T>> = EponymeCollectionAtPath<T, Name> extends EponymeCollectionDefinition<infer Schema> ? EponymeFilterInput<Schema> : never;
 export type EponymeName<T extends EponymeConfig> = {
     [K in keyof T & string]: T[K] extends EponymeCollectionDefinitionBase ? never : T[K] extends EponymeFormDefinitionBase ? never : T[K] extends EponymeSchema ? K : T[K] extends EponymeConfig ? `${K}/${EponymeName<T[K]>}` : never;
 }[keyof T & string];

package/dist/runtime/types/field.d.ts

@@ -1,5 +1,5 @@
 import type { CountryCode } from 'libphonenumber-js/min';
-export type EponymeFieldType = 'string' | 'slug' | 'email' | 'phone' | 'url' | 'textarea' | 'richText' | 'number' | 'boolean' | 'image' | 'select' | 'radio' | 'checkboxGroup' | 'date' | 'color' | 'array' | 'section' | 'tabs';
+export type EponymeFieldType = 'string' | 'slug' | 'email' | 'phone' | 'url' | 'textarea' | 'richText' | 'number' | 'boolean' | 'image' | 'select' | 'radio' | 'checkboxGroup' | 'tags' | 'date' | 'color' | 'array' | 'section' | 'tabs';
 export type FieldVisibilityCondition = {
     field: string;
     equals: unknown;
@@ -176,6 +176,39 @@ export interface CheckboxGroupFieldDefinition<T extends string = string> {
     type: 'checkboxGroup';
     options: CheckboxGroupFieldOptions<T>;
 }
+export interface TagsFieldOptions<T extends string = string> extends DefaultFieldOptions<T[]> {
+    /** Offered while typing. With `allowCustom` off, they are also the only accepted values. */
+    suggestions?: readonly T[];
+    /**
+     * Whether a tag outside `suggestions` may be entered.
+     *
+     * @default false
+     */
+    allowCustom?: boolean;
+    minItems?: number;
+    maxItems?: number;
+    placeholder?: string;
+}
+/**
+ * Values a tags field may hold, read from the options as they were written: the suggestions
+ * themselves while the list is closed, any string once `allowCustom` opens it. A tag list is
+ * therefore never a mix of types.
+ *
+ * Read from the object rather than from a type parameter on purpose. A parameter carrying
+ * `allowCustom` is re-inferred as `boolean` when the config is checked against `EponymeConfig`,
+ * and a conditional on `boolean` distributes over `true | false`, collapsing the union of
+ * suggestions to plain `string`. The shape of the object survives that check — which is also
+ * how `field.select()` and `field.checkboxGroup()` keep their literals.
+ */
+export type TagsValueOf<O> = O extends {
+    allowCustom: true;
+} ? string : O extends {
+    suggestions: readonly (infer S extends string)[];
+} ? S : string;
+export interface TagsFieldDefinition<O extends TagsFieldOptions = TagsFieldOptions> {
+    type: 'tags';
+    options: O;
+}
 export interface TodayDateDefault {
     readonly __eponymeDefault: 'today';
 }
@@ -200,7 +233,7 @@ export interface ColorFieldDefinition {
     type: 'color';
     options: ColorFieldOptions;
 }
-export type ArrayItemFieldDefinition = StringFieldDefinition | SlugFieldDefinition | EmailFieldDefinition | PhoneFieldDefinition | UrlFieldDefinition | TextareaFieldDefinition | RichTextFieldDefinition | NumberFieldDefinition | BooleanFieldDefinition | ImageFieldDefinition | SelectFieldDefinition | RadioFieldDefinition | CheckboxGroupFieldDefinition | DateFieldDefinition | ColorFieldDefinition;
+export type ArrayItemFieldDefinition = StringFieldDefinition | SlugFieldDefinition | EmailFieldDefinition | PhoneFieldDefinition | UrlFieldDefinition | TextareaFieldDefinition | RichTextFieldDefinition | NumberFieldDefinition | BooleanFieldDefinition | ImageFieldDefinition | SelectFieldDefinition | RadioFieldDefinition | CheckboxGroupFieldDefinition | TagsFieldDefinition | DateFieldDefinition | ColorFieldDefinition;
 export type ArrayItemSchema = Record<string, ArrayItemFieldDefinition>;
 export type ArrayItemDefinition = ArrayItemFieldDefinition | ArrayItemSchema;
 export type ArrayItemValue<T extends ArrayItemDefinition> = T extends NumberFieldDefinition ? number : T extends BooleanFieldDefinition ? boolean : T extends UrlFieldDefinition ? UrlValue : T extends CheckboxGroupFieldDefinition<infer Value> ? Value[] : T extends ArrayItemFieldDefinition ? string : T extends ArrayItemSchema ? {

package/dist/runtime/utils/eponyme-entry-index.d.ts

@@ -0,0 +1,39 @@
+import type { EponymeSchema } from '../types/eponyme.js';
+export interface EponymeIndexRow {
+    entryName: string;
+    version: 'draft' | 'published';
+    key: string;
+    value: string;
+}
+/** Rejecting a query on an unknown key beats silently returning the whole collection. */
+export declare function eponymeIndexKeys(schema: EponymeSchema): string[];
+export declare function isEponymeIndexKey(schema: EponymeSchema, key: string): boolean;
+/**
+ * Deliberately not `schemaFingerprint`, which covers names and types only. That one is the
+ * import compatibility contract — widening it would start refusing imports over harmless
+ * edits. Here the opposite bias applies: `field.select()` losing an option, or
+ * `field.tags({ allowCustom })` being turned off, makes `reconcile` drop stored values, and
+ * `defaultValue` decides what an entry missing the field gets indexed with. All of that has
+ * to invalidate the index, and none of it changes a name or a type.
+ *
+ * `validate` and `visibleWhen` are functions, kept as their mere presence: a body cannot be
+ * hashed honestly, since a minifier would change it without changing behaviour. Editing a
+ * custom validator so that it rejects previously stored values therefore needs a manual
+ * `reindexEponymeEntries()`.
+ */
+export declare function describeEponymeIndexSchema(schema: EponymeSchema): string;
+/**
+ * Only top-level fields are covered, which is the same reach as `orderBy`: a field nested
+ * in a section, a tab or an array is not addressable by a single key, so neither sorting
+ * nor filtering can name one.
+ *
+ * Draft and published are indexed separately. The dashboard lists drafts and a public page
+ * lists published entries, and the two disagree on purpose — one index for both would make
+ * an unpublished tag leak into a public listing.
+ */
+export declare function buildEponymeIndexRows(entryName: string, schema: EponymeSchema, versions: {
+    draft: Record<string, unknown>;
+    published: Record<string, unknown>;
+}): EponymeIndexRow[];
+/** The form both the write path and a query reduce a value to, so they always agree. */
+export declare function foldEponymeIndexValue(value: string): string;

package/dist/runtime/utils/eponyme-entry-index.js

@@ -0,0 +1,51 @@
+const INDEXABLE_TYPES = /* @__PURE__ */ new Set(["tags", "checkboxGroup", "select", "radio", "boolean", "date"]);
+const INDEX_ALGORITHM = 1;
+const COSMETIC_OPTION_KEYS = /* @__PURE__ */ new Set(["label", "description", "placeholder"]);
+export function eponymeIndexKeys(schema) {
+  return Object.keys(schema).filter((name) => isIndexable(schema[name]));
+}
+export function isEponymeIndexKey(schema, key) {
+  return isIndexable(schema[key]);
+}
+function isIndexable(definition) {
+  return Boolean(definition && INDEXABLE_TYPES.has(definition.type));
+}
+export function describeEponymeIndexSchema(schema) {
+  const fields = Object.keys(schema).filter((name) => isIndexable(schema[name])).sort().map((name) => `${name}:${schema[name].type}:${stableDescribe(schema[name].options)}`);
+  return `v${INDEX_ALGORITHM}|${fields.join(",")}`;
+}
+function stableDescribe(value) {
+  if (typeof value === "function") return "fn";
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "undefined";
+  if (Array.isArray(value)) return `[${value.map(stableDescribe).join(",")}]`;
+  const entries = Object.keys(value).filter((key) => !COSMETIC_OPTION_KEYS.has(key)).sort().map((key) => `${key}:${stableDescribe(value[key])}`);
+  return `{${entries.join(",")}}`;
+}
+export function buildEponymeIndexRows(entryName, schema, versions) {
+  const rows = /* @__PURE__ */ new Map();
+  for (const version of ["draft", "published"]) {
+    const data = versions[version];
+    for (const [key, definition] of Object.entries(schema)) {
+      if (!isIndexable(definition)) continue;
+      for (const value of indexValues(data[key])) {
+        rows.set(`${version}\0${key}\0${value}`, { entryName, version, key, value });
+      }
+    }
+  }
+  return [...rows.values()];
+}
+function indexValues(value) {
+  if (value === void 0 || value === null || value === "") return [];
+  if (typeof value === "boolean") return [String(value)];
+  if (typeof value === "string") return [fold(value)];
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => typeof item === "string" && item.trim() ? [fold(item)] : []);
+  }
+  return [];
+}
+export function foldEponymeIndexValue(value) {
+  return fold(value);
+}
+function fold(value) {
+  return value.trim().toLocaleLowerCase();
+}

package/dist/runtime/utils/get-field-default-value.js

@@ -17,6 +17,8 @@ export function getFieldDefaultValue(definition) {
       return [];
     case "checkboxGroup":
       return [];
+    case "tags":
+      return [];
     case "section":
       return Object.fromEntries(
         Object.entries(definition.options.fields).map(([name, field]) => [name, getFieldDefaultValue(field)])

package/dist/runtime/utils/normalize-eponyme-values.d.ts

@@ -0,0 +1,13 @@
+import type { EponymeSchema } from '../types/index.js';
+/**
+ * Rewrites every value that has a canonical form — a phone in E.164, a tag list deduplicated —
+ * wherever it sits in the schema.
+ *
+ * Applied on the server before a write, which is what makes a stored format a guarantee rather
+ * than a convention: the API accepts any JSON, so a client normalising on its own could always
+ * be bypassed. A value that cannot be understood is left as sent, for validation to reject.
+ *
+ * One walk for every field type that needs one. A second walker would mean a second place to
+ * forget a container when a field type is added.
+ */
+export declare function normalizeEponymeValues(schema: EponymeSchema, data: Record<string, unknown>): Record<string, unknown>;

package/dist/runtime/utils/{normalize-eponyme-phones.js → normalize-eponyme-values.js}

@@ -1,6 +1,7 @@
 import { isArrayItemFieldDefinition } from "./get-field-default-value.js";
 import { toEponymePhoneValue } from "./normalize-phone.js";
-export function normalizeEponymePhones(schema, data) {
+import { normalizeEponymeTags } from "./normalize-tags.js";
+export function normalizeEponymeValues(schema, data) {
   const result = { ...data };
   for (const [name, definition] of Object.entries(schema)) {
     if (!(name in result)) continue;
@@ -10,6 +11,7 @@ export function normalizeEponymePhones(schema, data) {
 }
 function normalizeField(definition, value) {
   if (definition.type === "phone") return toEponymePhoneValue(value, definition.options);
+  if (definition.type === "tags") return Array.isArray(value) ? normalizeEponymeTags(value, definition.options) : value;
   if (definition.type === "section")
     return normalizeNested(definition.options.fields, value);
   if (definition.type === "tabs") {
@@ -31,7 +33,7 @@ function normalizeArrayItem(of, item) {
 }
 function normalizeNested(schema, value) {
   if (!isRecord(value)) return value;
-  return normalizeEponymePhones(schema, value);
+  return normalizeEponymeValues(schema, value);
 }
 function isRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);

package/dist/runtime/utils/normalize-tags.d.ts

@@ -0,0 +1,10 @@
+import type { TagsFieldOptions } from '../types/field.js';
+/**
+ * The canonical form of a tag list, shared by the validation the server enforces, the editor
+ * field, and the write path that stores the value.
+ *
+ * A tag list is a taxonomy, so `Nuxt` and ` nuxt ` are the same tag and must not both exist.
+ * The first spelling wins, and a suggestion counts as a first spelling: typing `nuxt` next to a
+ * declared `Nuxt` yields `Nuxt`, which keeps a listing from splitting in two.
+ */
+export declare function normalizeEponymeTags(value: unknown, options?: TagsFieldOptions): string[];

package/dist/runtime/utils/normalize-tags.js

@@ -0,0 +1,17 @@
+export function normalizeEponymeTags(value, options = {}) {
+  if (!Array.isArray(value)) return [];
+  const suggestions = new Map((options.suggestions ?? []).map((tag) => [fold(tag), tag]));
+  const seen = /* @__PURE__ */ new Map();
+  for (const item of value) {
+    if (typeof item !== "string") continue;
+    const tag = item.trim();
+    if (!tag) continue;
+    const key = fold(tag);
+    if (seen.has(key)) continue;
+    seen.set(key, suggestions.get(key) ?? tag);
+  }
+  return [...seen.values()];
+}
+function fold(tag) {
+  return tag.trim().toLocaleLowerCase();
+}

package/dist/runtime/utils/validate-eponyme-data.js

@@ -1,6 +1,7 @@
 import { isArrayItemFieldDefinition } from "./get-field-default-value.js";
 import { isFieldVisible } from "./is-field-visible.js";
 import { normalizeEponymePhone } from "./normalize-phone.js";
+import { normalizeEponymeTags } from "./normalize-tags.js";
 const urlPattern = /^https?:\/\//i;
 const datePattern = /^\d{4}-\d{2}-\d{2}$/;
 const colorPattern = /^#(?:[\da-f]{3}|[\da-f]{6}|[\da-f]{8})$/i;
@@ -71,6 +72,21 @@ function validateFieldRules(name, definition, value, errors, mode, _context) {
     }
     return;
   }
+  if (definition.type === "tags") {
+    if (!Array.isArray(value)) {
+      addError(errors, name, "Must be an array.");
+      return;
+    }
+    const tags = normalizeEponymeTags(value, definition.options);
+    if (mode === "publish" && options.required && tags.length === 0) addError(errors, name, "This field is required.");
+    if (mode === "publish" && definition.options.minItems !== void 0 && tags.length < definition.options.minItems) addError(errors, name, `Must contain at least ${definition.options.minItems} items.`);
+    if (definition.options.maxItems !== void 0 && tags.length > definition.options.maxItems) addError(errors, name, `Must contain at most ${definition.options.maxItems} items.`);
+    if (value.some((item) => typeof item !== "string" || !item.trim())) addError(errors, name, "Must contain only non-empty tags.");
+    const suggestions = definition.options.suggestions;
+    if (!definition.options.allowCustom && suggestions?.length && tags.some((tag) => !suggestions.includes(tag)))
+      addError(errors, name, "Must contain only available options.");
+    return;
+  }
   if (definition.type === "checkboxGroup") {
     if (!Array.isArray(value)) {
       addError(errors, name, "Must be an array.");

package/dist/runtime/utils/variables.d.ts

@@ -1,4 +1,8 @@
 import type { EponymeVariableDefinition, EponymeVariables } from '../types/variables.js';
+export declare function findEponymeVariableRanges(text: string): Array<{
+    from: number;
+    to: number;
+}>;
 /** Always available, whatever the host application configures. */
 export declare function builtinEponymeVariables(now?: Date): Record<string, EponymeVariableDefinition>;
 /** Host variables win, so an application can override a built-in for its own wording. */

package/dist/runtime/utils/variables.js

@@ -1,4 +1,11 @@
-const VARIABLE_PATTERN = /\{\{\s*([A-Z_]\w*)\s*\}\}/gi;
+const VARIABLE_PATTERN_SOURCE = String.raw`\{\{\s*([A-Z_]\w*)\s*\}\}`;
+const VARIABLE_PATTERN = new RegExp(VARIABLE_PATTERN_SOURCE, "gi");
+export function findEponymeVariableRanges(text) {
+  return [...text.matchAll(new RegExp(VARIABLE_PATTERN_SOURCE, "gi"))].map((match) => ({
+    from: match.index,
+    to: match.index + match[0].length
+  }));
+}
 export function builtinEponymeVariables(now = /* @__PURE__ */ new Date()) {
   return {
     currentYear: { label: "Current year", description: "The year at the time the page is served.", value: () => now.getFullYear() },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karibsen/eponyme",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A lightweight, type-safe content manager for Nuxt.",
   "license": "MIT",
   "type": "module",
@@ -60,13 +60,14 @@
   },
   "dependencies": {
     "@iconify-json/mingcute": "^1.2.7",
-    "@karibsen/ui": "latest",
+    "@karibsen/ui": "^1.0.1",
     "@nuxt/icon": "^2.3.1",
     "@nuxt/kit": "^4.4.8",
     "@tailwindcss/vite": "^4.1.12",
     "@tanstack/vue-table": "^8.21.3",
     "@tiptap/extension-image": "^3.29.2",
     "@tiptap/extension-placeholder": "^3.28.0",
+    "@tiptap/pm": "^3.28.0",
     "@tiptap/starter-kit": "^3.28.0",
     "@tiptap/vue-3": "^3.28.0",
     "@vueuse/core": "^14.3.0",

package/dist/runtime/utils/normalize-eponyme-phones.d.ts

@@ -1,9 +0,0 @@
-import type { EponymeSchema } from '../types/index.js';
-/**
- * Rewrites every phone value in a payload to E.164, wherever it sits in the schema.
- *
- * Applied on the server before a write, which is what makes the stored format a guarantee
- * rather than a convention: the API accepts any JSON, so a client normalising on its own could
- * always be bypassed. Values that cannot be parsed are left as typed for validation to reject.
- */
-export declare function normalizeEponymePhones(schema: EponymeSchema, data: Record<string, unknown>): Record<string, unknown>;