@lupinum/ginko-content 0.1.0

package/dist/types/config.d.ts

@@ -0,0 +1,281 @@
+import { z, type ZodType } from 'zod';
+/**
+ * Locale settings for a collection that ships translated variants.
+ */
+export interface ContentCollectionI18nConfig {
+    /**
+     * Locale treated as the canonical variant when no locale is specified.
+     */
+    defaultLocale: string;
+    /**
+     * Every locale code that can produce a concrete variant for the collection.
+     */
+    locales: string[];
+}
+export type ContentCollectionSource = string | string[];
+/**
+ * Public route mount for route-backed collections.
+ *
+ * A single string applies to every locale. A locale map lets translated apps
+ * express roots such as `{ en: '/docs', de: '/dokumentation' }`.
+ */
+export type ContentCollectionRouteConfig = string | Record<string, string>;
+export type ContentCmsFieldType = 'text' | 'textarea' | 'richtext' | 'slug' | 'email' | 'url' | 'number' | 'range' | 'select' | 'multiselect' | 'radio' | 'checkbox' | 'toggle' | 'date' | 'datetime' | 'time' | 'json' | 'object' | 'array' | 'blocks' | 'relation' | 'relations' | 'image' | 'images' | 'file' | 'icon' | 'code' | 'color' | 'divider' | 'section';
+export interface ContentCmsRelationConfig {
+    collectionId: string;
+    multiple?: boolean;
+}
+export interface ContentCmsFieldConfig {
+    type?: ContentCmsFieldType;
+    label?: string | Record<string, string> | null;
+    description?: string | null;
+    required?: boolean;
+    localized?: boolean;
+    hidden?: boolean;
+    searchable?: boolean;
+    sortable?: boolean;
+    order?: number;
+    width?: 'full' | 'half';
+    defaultValue?: unknown;
+    validation?: Record<string, unknown> | null;
+    condition?: Record<string, unknown> | null;
+    options?: string[] | null;
+    relation?: ContentCmsRelationConfig | null;
+    fields?: Record<string, ContentCmsFieldConfig> | ContentCmsFieldConfig[] | null;
+    min?: number | null;
+    max?: number | null;
+    step?: number | null;
+    slugFrom?: string | null;
+    language?: string | null;
+}
+export interface ContentCmsCollectionConfig {
+    label?: string | Record<string, string>;
+    type?: 'flat' | 'tree';
+    icon?: string;
+    route?: {
+        mode?: 'route' | 'none';
+        pathPrefix?: string;
+        slugMode?: 'shared' | 'localized' | 'stable' | 'localizedStable';
+        rootSlug?: string | null;
+        singleton?: boolean;
+    };
+    fields?: Record<string, ContentCmsFieldConfig>;
+    settings?: unknown;
+}
+/**
+ * Object source shape accepted for Nuxt Content v3 migration.
+ */
+export interface ContentCollectionSourceObject {
+    /**
+     * Source glob or globs included in the collection.
+     */
+    include: ContentCollectionSource;
+    /**
+     * Source glob or globs excluded from the collection.
+     */
+    exclude?: ContentCollectionSource;
+}
+/**
+ * Declarative collection definition used by `content.config.ts`.
+ */
+export interface ContentCollectionConfig<TSchema extends ZodType | undefined = ZodType | undefined> {
+    /**
+     * Source glob or source descriptor understood by the filesystem ingestion
+     * layer. CMS-backed projects do not need a runtime source; filesystem
+     * imports/seeding should be modeled by provider-owned import tooling.
+     */
+    source?: ContentCollectionSource;
+    /**
+     * Source glob or globs excluded from this collection.
+     */
+    exclude?: ContentCollectionSource;
+    /**
+     * Optional Zod schema applied to every parsed entry in the collection.
+     */
+    schema?: TSchema;
+    /**
+     * When `true`, reject documents with frontmatter fields not declared in `schema`.
+     */
+    strict?: boolean;
+    /**
+     * Per-collection locale settings. Use `true` to inherit the module-level i18n config.
+     */
+    i18n?: true | ContentCollectionI18nConfig;
+    /**
+     * Public route mount for this collection. Used to resolve `by.route`
+     * selectors and to emit requested-locale URLs for fallback content.
+     */
+    route?: ContentCollectionRouteConfig;
+    /**
+     * Opt-in to fully translated path segments per locale (ADR-0008). When `true`,
+     * the content graph pairs locale variants by numeric prefix on filenames so
+     * each locale can carry its own slug text, e.g. `1.guide/` ↔ `1.documentation/`.
+     *
+     * @default false
+     */
+    translatedSlugs?: boolean;
+    /**
+     * Include this collection in content-owned sitemap output and prerender route
+     * discovery. Route-backed collections are included by default; data-only or
+     * app-internal collections should opt out with `false`.
+     *
+     * @default true
+     */
+    sitemap?: boolean;
+    /**
+     * Optional CMS editor metadata for providers such as `@lupinum/ginko-cms`.
+     *
+     * The content collection remains the source of truth; this metadata only
+     * fills editor-specific gaps that cannot be inferred safely from route,
+     * source, i18n, and schema information.
+     */
+    cms?: ContentCmsCollectionConfig;
+}
+export type ContentCollectionKind = 'page' | 'data';
+export type BuiltinContentProviderName = 'filesystem' | 'cms' | 'ginko-cms' | 'ginko';
+export type ContentProviderName = BuiltinContentProviderName | (string & {});
+export type DefineCollectionOptions<TSchema extends ZodType | undefined = ZodType | undefined> = Omit<ContentCollectionConfig<TSchema>, 'source' | 'exclude'>;
+export interface DefineCollectionObject<TSchema extends ZodType | undefined = ZodType | undefined> extends DefineCollectionOptions<TSchema> {
+    /**
+     * Nuxt Content v3-compatible collection kind. Ginko does not keep separate
+     * page/data collection runtimes; `data` collections default to `sitemap: false`.
+     */
+    type: ContentCollectionKind;
+    /**
+     * Source glob, globs, or v3-compatible `{ include, exclude }` object.
+     * Required for filesystem-backed collections; optional for CMS-backed
+     * collections.
+     */
+    source?: ContentCollectionSource | ContentCollectionSourceObject;
+}
+/**
+ * Root object returned from `defineContentConfig`.
+ */
+export interface ContentConfig<TCollections extends Record<string, ContentCollectionConfig> = Record<string, ContentCollectionConfig>> {
+    /**
+     * Content backing implementation. `filesystem` is the default. `cms`,
+     * `ginko-cms`, and `ginko` resolve to the official Ginko CMS provider when
+     * `@lupinum/ginko-cms` is installed.
+     */
+    provider?: ContentProviderName;
+    /**
+     * External provider modules keyed by provider name. Built-in providers do not
+     * need to be registered here.
+     */
+    providers?: Record<string, string>;
+    /**
+     * Named content collections keyed by the identifier used at query time.
+     */
+    collections?: TCollections;
+}
+/**
+ * Infer the runtime data shape for a collection from its Zod schema.
+ */
+export type CollectionSchema<TCollection> = TCollection extends {
+    schema?: infer TSchema;
+} ? TSchema extends ZodType ? z.infer<TSchema> : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Zod string schema tagged as a Nuxt Content reference field.
+ */
+export interface ContentReferenceSchema extends z.ZodString {
+    /**
+     * Serialized descriptor in the form `__nuxt_content_ref__:<collection>`.
+     */
+    description: string;
+}
+/**
+ * Typed handle returned by `defineCollection`. Carries the collection's name
+ * and i18n discriminator at the type level so the unified query API
+ * (`one`, `many`, `useContentOne`, ...) can require `locale` only when the
+ * collection is internationalized.
+ *
+ * The handle extends `ContentCollectionConfig` so it can be stored directly
+ * in `defineContentConfig({ collections: ... })`.
+ */
+export interface ContentCollectionHandle<Name extends string = string, TSchema extends ZodType | undefined = ZodType | undefined, TI18n extends boolean = boolean> extends ContentCollectionConfig<TSchema> {
+    /**
+     * Stable identifier used at query time, e.g. `'docs'` or `'blog'`.
+     */
+    readonly name: Name;
+    /**
+     * Phantom flag — `true` when the collection ships translated variants.
+     * Used by the type system to make `locale` required on i18n queries.
+     *
+     * @internal
+     */
+    readonly __i18n: TI18n;
+    /**
+     * Phantom marker — Zod schema bound at definition time. Used to infer the
+     * returned document shape at query time.
+     *
+     * @internal
+     */
+    readonly __schema: TSchema;
+}
+type IsI18nConfig<TConfig> = TConfig extends {
+    i18n: true | ContentCollectionI18nConfig;
+} ? TConfig['i18n'] extends false ? false : true : false;
+/**
+ * Define a content collection in `content.config.ts`.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ * import { defineCollection } from '@lupinum/ginko-content/config'
+ *
+ * export const docs = defineCollection('docs', {
+ *   type: 'page',
+ *   source: 'docs/**\/*.md',
+ *   i18n: { locales: ['en', 'fr', 'de'], defaultLocale: 'en' },
+ *   schema: z.object({
+ *     title: z.string(),
+ *     published: z.boolean().default(true)
+ *   })
+ * })
+ * ```
+ */
+type SchemaOf<TConfig> = TConfig extends {
+    schema?: infer S;
+} ? S extends ZodType ? S : undefined : undefined;
+export declare function defineCollection<const Name extends string, const TConfig extends DefineCollectionObject<ZodType | undefined>>(name: Name, config: TConfig): ContentCollectionHandle<Name, SchemaOf<TConfig>, IsI18nConfig<TConfig>>;
+/**
+ * Wrap the root content configuration with full type inference.
+ *
+ * @example
+ * ```ts
+ * import { defineCollection, defineContentConfig } from '@lupinum/ginko-content/config'
+ *
+ * export default defineContentConfig({
+ *   collections: {
+ *     docs: defineCollection({
+ *       type: 'page',
+ *       source: 'docs/*.md'
+ *     })
+ *   }
+ * })
+ * ```
+ */
+export declare function defineContentConfig<TCollections extends Record<string, ContentCollectionConfig>>(config: ContentConfig<TCollections>): ContentConfig<TCollections>;
+/**
+ * Declare a schema field that stores a reference to another content entry.
+ *
+ * Use the optional `collection` argument when the field must target a single
+ * collection. Omit it to allow references across collections.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ * import { defineCollection, reference } from '@lupinum/ginko-content/config'
+ *
+ * export default defineCollection({
+ *   type: 'page',
+ *   source: 'blog/*.md',
+ *   schema: z.object({
+ *     author: reference('authors'),
+ *     related: z.array(reference('blog')).default([])
+ *   })
+ * })
+ * ```
+ */
+export declare function reference(collection?: string): ContentReferenceSchema;
+export {};

package/dist/types/config.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { CONTENT_REFERENCE_PREFIX } from "./reference.js";
+export function defineCollection(name, config) {
+  const { type, source, sitemap, ...rest } = config;
+  const normalized = normalizeCollectionSource(source);
+  return {
+    name,
+    ...normalized,
+    sitemap: sitemap ?? (type === "data" ? false : void 0),
+    ...rest
+  };
+}
+function normalizeCollectionSource(source) {
+  if (source === void 0) return {};
+  if (typeof source === "object" && !Array.isArray(source)) {
+    return {
+      source: source.include,
+      ...source.exclude ? { exclude: source.exclude } : {}
+    };
+  }
+  return { source };
+}
+export function defineContentConfig(config) {
+  return config;
+}
+export function reference(collection) {
+  return z.string().describe(`${CONTENT_REFERENCE_PREFIX}${collection || ""}`);
+}

package/dist/types/content

@@ -0,0 +1 @@
+export * from './content.js'

package/dist/types/content.d.ts

@@ -0,0 +1,311 @@
+import type { StorageValue } from 'unstorage';
+type LayoutKey = string;
+export interface ContentSeoImage {
+    src: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+}
+export interface ContentSeoMeta {
+    title?: string;
+    description?: string;
+    image?: string | ContentSeoImage;
+}
+/**
+ * Internal metadata attached to every parsed content record.
+ */
+export interface ParsedContentInternalMeta {
+    /**
+     * Stable unique id for the parsed source record.
+     */
+    _id: string;
+    /**
+     * Backing source name when multiple content sources are configured.
+     */
+    _source?: string;
+    /**
+     * Canonical content path. This is source-agnostic, so the same route can be
+     * backed by local files, remote storage, or generated data.
+     */
+    _path?: string;
+    /**
+     * Human-readable title resolved from frontmatter or generated metadata.
+     */
+    title?: string;
+    /**
+     * Human-readable summary used in listings, search, and SEO helpers.
+     */
+    description?: string;
+    /**
+     * Conventional SEO frontmatter shared by pages and app templates.
+     */
+    seo?: ContentSeoMeta;
+    /**
+     * Stable authored alias for internal content links.
+     */
+    ref?: string;
+    /**
+     * Marks the document as a draft.
+     */
+    _draft?: boolean;
+    /**
+     * Marks the document as a partial that should not become a page by default.
+     */
+    _partial?: boolean;
+    /**
+     * Locale code for the concrete variant.
+     */
+    _locale?: string;
+    /**
+     * Locale-agnostic content identity used to resolve variants.
+     */
+    _canonicalKey?: string;
+    /**
+     * Requested route path before locale fallback.
+     */
+    _requestedPath?: string;
+    /**
+     * Requested public route before locale fallback.
+     */
+    _requestedRoute?: string;
+    /**
+     * Requested authored reference before locale fallback.
+     */
+    _requestedRef?: string;
+    /**
+     * Requested locale before locale fallback.
+     */
+    _requestedLocale?: string;
+    /**
+     * Resolved locale after locale fallback.
+     */
+    _resolvedLocale?: string;
+    /**
+     * Whether the returned content was resolved through fallback.
+     */
+    _fallback?: boolean;
+    /**
+     * Locales that have a concrete variant for this document.
+     */
+    _availableLocales?: string[];
+    /**
+     * Map of available locale code to its locale-specific path.
+     */
+    _variantPaths?: Record<string, string>;
+    /**
+     * Resolved markdown `$ref` links for the current runtime locale.
+     */
+    _resolvedRefs?: Record<string, string>;
+    /**
+     * Collection name, when matched by a configured collection glob.
+     */
+    _collection?: string;
+    /**
+     * Marks folder-scoped navigation metadata documents.
+     */
+    _navigation?: boolean;
+    /**
+     * Parsed document kind.
+     */
+    _type?: 'markdown' | 'yaml' | 'json' | 'csv';
+    /**
+     * Source file path relative to the content root.
+     */
+    _file?: string;
+    /**
+     * Source file extension.
+     */
+    _extension?: 'md' | 'yaml' | 'yml' | 'json' | 'json5' | 'csv';
+}
+/**
+ * One entry in a generated table of contents.
+ */
+export interface TocLink {
+    id: string;
+    text: string;
+    depth: number;
+    children?: TocLink[];
+}
+/**
+ * Parsed table of contents generated from markdown headings.
+ */
+export interface Toc {
+    title: string;
+    depth: number;
+    searchDepth: number;
+    links: TocLink[];
+}
+/**
+ * Options object passed to a markdown plugin.
+ */
+export type MarkdownPluginOptions = Record<string, unknown>;
+/**
+ * User-authored plugin declaration in module options.
+ */
+export type MarkdownPluginDescriptor = string | [string, MarkdownPluginOptions];
+/**
+ * Normalized plugin declaration after resolution.
+ */
+export type ResolvedMarkdownPlugin = {
+    name: string;
+    options: MarkdownPluginOptions;
+};
+/**
+ * Object-shaped markdown AST node.
+ */
+export interface MarkdownNode {
+    type: string;
+    tag?: string;
+    value?: string;
+    props?: Record<string, unknown>;
+    content?: unknown;
+    children?: MarkdownNode[];
+    attributes?: Record<string, unknown>;
+    fmAttributes?: Record<string, unknown>;
+}
+/**
+ * Root node for the object-based markdown AST.
+ */
+export interface MarkdownRoot {
+    type: 'root';
+    children: MarkdownNode[];
+    props?: Record<string, any>;
+    toc?: Toc;
+}
+/**
+ * Resolved markdown runtime options.
+ */
+export interface MarkdownOptions {
+    plugins: ResolvedMarkdownPlugin[];
+    tags: Record<string, string>;
+    anchorLinks: {
+        depth: number;
+        exclude: number[];
+    };
+    image?: 'auto' | 'img' | 'nuxt-image';
+}
+/**
+ * Flexible parsed content shape that allows user-defined frontmatter fields.
+ */
+export interface ParsedContentMeta extends ParsedContentInternalMeta {
+    /**
+     * Preferred layout key for page rendering.
+     */
+    layout?: LayoutKey;
+    [key: string]: unknown;
+}
+/**
+ * Strict parsed content shape with no open-ended index signature.
+ */
+export interface StrictParsedContentMeta extends ParsedContentInternalMeta {
+    /**
+     * Preferred layout key for page rendering.
+     */
+    layout?: LayoutKey;
+}
+/**
+ * Parsed content document including the rendered body payload.
+ */
+export interface ParsedContent extends ParsedContentMeta {
+    /**
+     * Optional excerpt payload.
+     */
+    excerpt?: MarkdownRoot;
+    /**
+     * Parsed body payload. `null` means the source had no renderable body.
+     */
+    body: MarkdownRoot | null;
+}
+/**
+ * Strict parsed content document including the rendered body payload.
+ */
+export interface StrictParsedContent extends StrictParsedContentMeta {
+    /**
+     * Optional excerpt payload.
+     */
+    excerpt?: MarkdownRoot;
+    /**
+     * Parsed body payload. `null` means the source had no renderable body.
+     */
+    body: MarkdownRoot | null;
+}
+/**
+ * Specialized parsed content shape for markdown sources.
+ */
+export interface MarkdownParsedContent extends ParsedContent {
+    _type: 'markdown';
+    /**
+     * Whether the markdown source rendered no meaningful body content.
+     */
+    _empty: boolean;
+    /**
+     * Description resolved from frontmatter or excerpt generation.
+     */
+    description: string;
+    /**
+     * Object AST excerpt generated from the markdown body.
+     */
+    excerpt?: MarkdownRoot;
+    /**
+     * Parsed Markdown body with included table of contents.
+     */
+    body: MarkdownRoot & {
+        toc?: Toc;
+    };
+}
+/**
+ * Transformer hook used during ingestion.
+ */
+export interface ContentTransformer {
+    /**
+     * Stable transformer name used in logs and generated manifests.
+     */
+    name: string;
+    /**
+     * File extensions handled by the transformer.
+     */
+    extensions: string[];
+    /**
+     * Optional parse hook that turns raw source content into a parsed document.
+     */
+    parse?(id: string, content: StorageValue, options: unknown): Promise<ParsedContent> | ParsedContent;
+    /**
+     * Optional post-parse hook that mutates or enriches a parsed document.
+     */
+    transform?(content: ParsedContent, options: unknown): Promise<ParsedContent> | ParsedContent;
+}
+/**
+ * Ingestion options passed to the transform pipeline.
+ */
+export interface TransformContentOptions {
+    transformers?: ContentTransformer[];
+    [key: string]: unknown;
+}
+/**
+ * Navigation node returned by content navigation helpers.
+ */
+export interface NavItem {
+    title: string;
+    /**
+     * Nuxt Content compatible route path used by Nuxt UI content components.
+     */
+    path: string;
+    /**
+     * Canonical content route without locale prefix.
+     */
+    _path: string;
+    stem?: string;
+    page?: false;
+    _id?: string;
+    _canonicalKey?: string;
+    _locale?: string;
+    _fallback?: boolean;
+    _draft?: boolean;
+    children?: NavItem[];
+    [key: string]: unknown;
+}
+/**
+ * Public alias for navigation items returned by query helpers.
+ */
+export type ContentNavigationItem = NavItem;
+export {};

package/dist/types/content.js

@@ -0,0 +1 @@
+export {};

package/dist/types/fields

@@ -0,0 +1 @@
+export * from './fields.js'