@beechcms/core 0.4.0-preview.1

package/src/richtext-render.ts

@@ -0,0 +1,87 @@
+import { generateHTML } from '@tiptap/html'
+import type { JSONContent } from '@tiptap/core'
+import Highlight from '@tiptap/extension-highlight'
+import Image from '@tiptap/extension-image'
+import Link from '@tiptap/extension-link'
+import Subscript from '@tiptap/extension-subscript'
+import Superscript from '@tiptap/extension-superscript'
+import { Table, TableCell, TableHeader, TableRow } from '@tiptap/extension-table'
+import TextAlign from '@tiptap/extension-text-align'
+import { Mathematics } from '@tiptap/extension-mathematics'
+import StarterKit from '@tiptap/starter-kit'
+
+import { isRichtextEnvelopeV1 } from './richtext.js'
+
+/**
+ * Allinea l'output HTML allo schema TipTap usato dall'editor dashboard.
+ * Mantieni sincronizzato con `apps/dashboard/src/features/richtext-editor/extensions/build-editor-extensions.ts`.
+ */
+function createRichTextHtmlExtensions() {
+  return [
+    StarterKit.configure({
+      link: false,
+      codeBlock: {
+        HTMLAttributes: {
+          class: 'richtext-code-block',
+        },
+      },
+    }),
+    Link.configure({
+      openOnClick: false,
+      autolink: true,
+      defaultProtocol: 'https',
+    }),
+    Mathematics.configure({
+      katexOptions: {
+        throwOnError: false,
+      },
+    }),
+    Highlight,
+    Superscript,
+    Subscript,
+    Image.configure({
+      allowBase64: false,
+    }),
+    TextAlign.configure({
+      types: ['heading', 'paragraph'],
+    }),
+    Table.configure({
+      resizable: false,
+    }),
+    TableRow,
+    TableHeader,
+    TableCell,
+  ]
+}
+
+/**
+ * Accetta JSON TipTap (`{ type: 'doc', ... }`), envelope v1, o stringa HTML legacy.
+ */
+export function normalizeRichtextForRender(value: unknown): JSONContent | string | null {
+  if (value == null || value === '') return null
+  if (typeof value === 'string') return value
+  if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    const o = value as Record<string, unknown>
+    if (isRichtextEnvelopeV1(value)) {
+      return o.doc as JSONContent
+    }
+    if (o.type === 'doc') {
+      return value as JSONContent
+    }
+  }
+  return null
+}
+
+/**
+ * Render deterministico JSON → HTML (per display, anteprime, API pubblica).
+ * Per stringhe HTML legacy restituisce la stringa sanificata come pass-through (nessun parse TipTap).
+ */
+export function renderRichText(value: unknown): string {
+  const normalized = normalizeRichtextForRender(value)
+  if (normalized == null) return ''
+  if (typeof normalized === 'string') {
+    return normalized
+  }
+  const extensions = createRichTextHtmlExtensions()
+  return generateHTML(normalized, extensions)
+}

package/src/richtext.ts

@@ -0,0 +1,16 @@
+/**
+ * Convenzione storage richtext TipTap nel Content Engine.
+ * @see docs/Sprints/tiptap-elevation.md
+ */
+export const RICHTEXT_SCHEMA_VERSION = 1 as const
+
+export type RichtextEnvelopeV1 = {
+  schemaVersion: typeof RICHTEXT_SCHEMA_VERSION
+  doc: Record<string, unknown>
+}
+
+export function isRichtextEnvelopeV1(value: unknown): value is RichtextEnvelopeV1 {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const o = value as Record<string, unknown>
+  return o.schemaVersion === RICHTEXT_SCHEMA_VERSION && typeof o.doc === 'object' && o.doc !== null
+}

package/src/seeds.ts

@@ -0,0 +1,194 @@
+/**
+ * Seed Registry: configurazione degli schemi di contenuto.
+ * In v0.4.0 ogni Seed genera una tabella `content_{slug}` con colonne reali.
+ * `branch.alias` è il nome della colonna SQL.
+ */
+import type { Seed } from './types.js'
+
+/** Articolo: contenuto editoriale con richtext, immagine e SEO */
+export const ARTICOLO_SEED: Seed = {
+  slug: 'articoli',
+  label: 'Articolo',
+  labelPlural: 'Articoli',
+  displayNameAlias: 'title',
+  allowPublicRead: true,
+  allowDrafts: true,
+  branches: [
+    { alias: 'title', label: 'Titolo', type: 'text' },
+    { alias: 'publishedAt', label: 'Data pubblicazione', type: 'date' },
+    { alias: 'coverImage', label: 'Immagine copertina', type: 'file' },
+    { alias: 'tags', label: 'Tag', type: 'json', options: ['cms', 'tutorial', 'release', 'annuncio', 'guida', 'news', 'aggiornamento'] },
+    { alias: 'body', label: 'Corpo articolo', type: 'richtext' },
+    { alias: 'metaTitle', label: 'Meta titolo (SEO)', type: 'text' },
+    { alias: 'metaDescription', label: 'Meta descrizione (SEO)', type: 'text' },
+  ],
+}
+
+/** Prodotto: scheda prodotto e-commerce con richtext, galleria e SEO */
+export const PRODOTTO_SEED: Seed = {
+  slug: 'prodotti',
+  label: 'Prodotto',
+  labelPlural: 'Prodotti',
+  displayNameAlias: 'name',
+  allowPublicRead: true,
+  branches: [
+    { alias: 'name', label: 'Nome', type: 'text' },
+    { alias: 'price', label: 'Prezzo (€)', type: 'number' },
+    { alias: 'stock', label: 'Quantità disponibile', type: 'number' },
+    { alias: 'active', label: 'In vendita', type: 'boolean' },
+    { alias: 'coverImage', label: 'Immagine principale', type: 'file' },
+    { alias: 'images', label: 'Galleria immagini', type: 'file', multiple: true, format: 'asset-list' },
+    { alias: 'description', label: 'Descrizione', type: 'richtext' },
+    { alias: 'metaTitle', label: 'Meta titolo (SEO)', type: 'text' },
+    { alias: 'metaDescription', label: 'Meta descrizione (SEO)', type: 'text' },
+  ],
+}
+
+/** Membro del team: profilo con foto e link social */
+export const TEAM_SEED: Seed = {
+  slug: 'team',
+  label: 'Membro',
+  labelPlural: 'Team',
+  displayNameAlias: 'name',
+  allowPublicRead: true,
+  branches: [
+    { alias: 'name', label: 'Nome', type: 'text' },
+    { alias: 'role', label: 'Ruolo', type: 'text' },
+    { alias: 'bio', label: 'Bio breve', type: 'text' },
+    { alias: 'photo', label: 'Foto', type: 'file' },
+    { alias: 'linkedIn', label: 'URL LinkedIn', type: 'text' },
+    { alias: 'active', label: 'Visibile', type: 'boolean' },
+    { alias: 'metaTitle', label: 'Meta titolo (SEO)', type: 'text' },
+    { alias: 'metaDescription', label: 'Meta descrizione (SEO)', type: 'text' },
+  ],
+}
+
+/** Testimonianza: recensione cliente con valutazione e foto */
+export const TESTIMONIANZA_SEED: Seed = {
+  slug: 'testimonianze',
+  label: 'Testimonianza',
+  labelPlural: 'Testimonianze',
+  displayNameAlias: 'author',
+  allowPublicRead: true,
+  branches: [
+    { alias: 'author', label: 'Autore', type: 'text' },
+    { alias: 'company', label: 'Azienda', type: 'text' },
+    { alias: 'quote', label: 'Citazione', type: 'text' },
+    { alias: 'rating', label: 'Valutazione (1-5)', type: 'number' },
+    { alias: 'date', label: 'Data', type: 'date' },
+    { alias: 'photo', label: 'Foto autore', type: 'file' },
+    { alias: 'active', label: 'Pubblica', type: 'boolean' },
+    { alias: 'metaTitle', label: 'Meta titolo (SEO)', type: 'text' },
+    { alias: 'metaDescription', label: 'Meta descrizione (SEO)', type: 'text' },
+  ],
+}
+
+/** Pagina: pagina statica con richtext, immagine hero e SEO */
+export const PAGINA_SEED: Seed = {
+  slug: 'pagine',
+  label: 'Pagina',
+  labelPlural: 'Pagine',
+  displayNameAlias: 'title',
+  allowPublicRead: true,
+  allowDrafts: true,
+  branches: [
+    { alias: 'title', label: 'Titolo', type: 'text' },
+    { alias: 'coverImage', label: 'Immagine hero', type: 'file' },
+    { alias: 'body', label: 'Contenuto', type: 'richtext' },
+    { alias: 'metaTitle', label: 'Meta titolo (SEO)', type: 'text' },
+    { alias: 'metaDescription', label: 'Meta descrizione (SEO)', type: 'text' },
+  ],
+}
+
+/**
+ * Cliente: dimostra tutte le assi di Branch.policies.
+ *
+ * email        → visibility:masked, search:false, public:false
+ * passwordHash → privacy:hash, visibility:hidden, search/filter/sort/public: false
+ * phone        → visibility:masked, filter:false, public:false
+ * internalNote → visibility:hidden, search:false, public:false
+ * registeredAt → public:false (data interna, non esposta)
+ */
+export const CLIENTE_SEED: Seed = {
+  slug: 'clienti',
+  label: 'Cliente',
+  labelPlural: 'Clienti',
+  displayNameAlias: 'name',
+  allowPublicRead: true,
+  branches: [
+    { alias: 'name', label: 'Nome', type: 'text' },
+    {
+      alias: 'email',
+      label: 'Email',
+      type: 'text',
+      policies: { visibility: 'masked', search: false, public: false },
+    },
+    {
+      alias: 'passwordHash',
+      label: 'Password (hash)',
+      type: 'text',
+      policies: { privacy: 'hash', visibility: 'hidden', search: false, filter: false, sort: false, public: false },
+    },
+    {
+      alias: 'tier',
+      label: 'Piano',
+      type: 'text',
+      options: ['free', 'starter', 'pro', 'enterprise'],
+    },
+    {
+      alias: 'phone',
+      label: 'Telefono',
+      type: 'text',
+      policies: { visibility: 'masked', filter: false, public: false },
+    },
+    {
+      alias: 'internalNote',
+      label: 'Note interne',
+      type: 'text',
+      policies: { visibility: 'hidden', search: false, public: false },
+    },
+    {
+      alias: 'registeredAt',
+      label: 'Data iscrizione',
+      type: 'date',
+      policies: { public: false },
+    },
+    { alias: 'active', label: 'Attivo', type: 'boolean' },
+  ],
+}
+
+/**
+ * TODO: Rimuovere al termine dei test del testsite
+ * Messaggio di contatto: per form contatti esterni
+ */
+export const MESSAGGI_SEED: Seed = {
+  slug: 'messaggi',
+  label: 'Messaggio',
+  labelPlural: 'Messaggi',
+  displayNameAlias: 'name',
+  allowPublicPost: true,
+  allowPublicEdit: true,
+  branches: [
+    { alias: 'name', label: 'Nome mittente', type: 'text', requiredOnCreate: true },
+    { alias: 'email', label: 'Email mittente', type: 'text', requiredOnCreate: true },
+    { alias: 'subject', label: 'Oggetto', type: 'text', requiredOnCreate: true },
+    { alias: 'message', label: 'Messaggio', type: 'richtext', requiredOnCreate: true },
+    { alias: 'read', label: 'Letto', type: 'boolean' },
+  ],
+}
+
+/** Registro: slug -> Seed */
+export const SEED_REGISTRY: Record<string, Seed> = {
+  articoli: ARTICOLO_SEED,
+  prodotti: PRODOTTO_SEED,
+  team: TEAM_SEED,
+  testimonianze: TESTIMONIANZA_SEED,
+  pagine: PAGINA_SEED,
+  clienti: CLIENTE_SEED,
+  messaggi: MESSAGGI_SEED,
+}
+
+/** Ritorna il Seed per lo slug dato, o null se non esiste. */
+export function getSeed(slug: string): Seed | null {
+  return SEED_REGISTRY[slug] ?? null
+}

package/src/slug-utils.ts

@@ -0,0 +1,33 @@
+/**
+ * Utility per la gestione degli slug.
+ * Condivisa tra Dashboard e API pubbliche.
+ */
+
+/**
+ * Converte una stringa in uno slug URL-safe.
+ * Limita la lunghezza a 15 caratteri come richiesto.
+ */
+export function slugify(value: string): string {
+  return value
+    .normalize('NFKD')               // Normalizza caratteri accentati
+    .replace(/[^\w\s-]/g, '')        // Rimuove tutto ciò che non è alfanumerico (accetta underscore temporaneamente)
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_-]+/g, '-')        // Sostituisce spazi, underscore e trattini multipli con singolo trattino
+    .replace(/^-+|-+$/g, '')         // Rimuove trattini all'inizio o alla fine
+    .slice(0, 15)                    // Limita a 15 caratteri
+}
+
+/**
+ * Genera uno slug da un input (es. titolo o nome) o un fallback UUID.
+ */
+export function generateEntrySlug(input: { slug?: string; title?: unknown; name?: unknown }): string {
+  const candidate =
+    (typeof input.slug === 'string' && input.slug) ||
+    (typeof input.title === 'string' && input.title) ||
+    (typeof input.name === 'string' && input.name) ||
+    Math.random().toString(36).slice(2, 10) // Fallback compatto se crypto non disponibile (o slice 8)
+
+  const normalized = slugify(candidate)
+  return normalized || Math.random().toString(36).slice(2, 10)
+}

package/src/types.ts

@@ -0,0 +1,121 @@
+export type BranchType = 'text' | 'number' | 'boolean' | 'json' | 'date' | 'richtext' | 'file'
+
+/** Branch: definizione di una proprietà. alias = nome colonna SQL. */
+export interface Branch {
+  /** Alias human-readable, usato nel payload API e come nome colonna SQL nella tabella dedicata */
+  alias: string
+  /** Etichetta per la UI */
+  label: string
+  /** Tipo del valore */
+  type: BranchType
+  /**
+   * Variante semantica opzionale del campo per UI/validazione.
+   * `asset-list` su `file` multiplo abilita la gestione galleria.
+   */
+  format?: 'plain' | 'markdown' | 'html' | 'date' | 'datetime' | 'asset-list'
+  /**
+   * Cardinalità opzionale per campi media:
+   * - false/undefined: singolo asset (string URL)
+   * - true: lista asset (string[] URL)
+   */
+  multiple?: boolean
+  /**
+   * Vocabolario predefinito per campi tag/select/multiselect.
+   * Lista statica definita nel Seed (non salvata nel DB).
+   */
+  options?: string[]
+  /** Campo obbligatorio in creazione — genera NOT NULL in generateCreateTable */
+  requiredOnCreate?: boolean
+  /** Campo obbligatorio in update */
+  requiredOnUpdate?: boolean
+  /**
+   * Policy di accesso e trattamento del campo.
+   * Tutti i valori sono opzionali — `resolvePolicies(branch)` fornisce i default.
+   */
+  policies?: {
+    /** Come il valore viene memorizzato. Default: 'plain' */
+    privacy?: 'plain' | 'hash' | 'encrypt'
+    /** Come il valore viene restituito nelle risposte API. Default: 'full' */
+    visibility?: 'full' | 'masked' | 'hidden'
+    /** Il campo è incluso nelle query di ricerca full-text. Default: true */
+    search?: boolean
+    /** Il campo è disponibile come colonna di filtro nella dashboard. Default: true */
+    filter?: boolean
+    /** Il campo è disponibile come colonna di ordinamento nella dashboard. Default: true */
+    sort?: boolean
+    /** Il campo è incluso nelle risposte della Public API. Default: true */
+    public?: boolean
+  }
+}
+
+/** Seed: definizione dello schema di un tipo di contenuto */
+export interface Seed {
+  /** Slug identificativo — anche nome tabella: `content_{slug}` */
+  slug: string
+  /** Etichetta singolare per la UI */
+  label: string
+  /** Etichetta plurale per la UI. Se assente si usa `label`. */
+  labelPlural?: string
+  /** Abilita lettura dalla Public API (`GET /api/v1/public/:seed`). Default: false */
+  allowPublicRead?: boolean
+  /** Abilita creazione dalla Public API (`POST /api/v1/public/:seed/add`). Default: false */
+  allowPublicPost?: boolean
+  /** Abilita modifica dalla Public API (`PUT /api/v1/public/:seed/edit/:id`). Default: false */
+  allowPublicEdit?: boolean
+  /**
+   * Abilita la feature "bozza in attesa" per questo seed.
+   * Quando true, genera tabella `content_{slug}_drafts` e abilita gli endpoint `/draft`.
+   * Default: false
+   */
+  allowDrafts?: boolean
+  /**
+   * Alias del branch usato come nome leggibile dell'entry (es. "title", "name", "author").
+   * Obbligatorio — le UI lo usano per display senza euristica.
+   */
+  displayNameAlias: string
+  /** Lista dei campi (Branch) */
+  branches: Branch[]
+}
+
+// ---- Query types (usati da buildSelectQuery nel Botanical Engine) ----
+
+export type FilterOperator =
+  | 'eq'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'contains'
+  | 'is_empty'
+  | 'is_not_empty'
+
+export type FilterType = 'text' | 'number' | 'date' | 'boolean' | 'tags' | 'select' | 'system'
+
+export interface FilterCondition {
+  op: FilterOperator
+  value: string | number | boolean | null
+}
+
+export interface FilterGroup {
+  /** Nome colonna: system column (id/slug/status/created_at/updated_at) o branch alias */
+  column: string
+  type: FilterType
+  conditions: FilterCondition[]
+}
+
+export interface SelectOptions {
+  filters?: FilterGroup[]
+  orderBy?: { column: string; dir: 'ASC' | 'DESC' }
+  pagination?: { limit: number; offset: number }
+  /** Filtra per status. null = nessun filtro status. */
+  status?: string | null
+  /** Full-text search — usa FTS5 se il seed ha branch richtext indicizzabili */
+  search?: string
+  /** Proiezione colonne. Vuoto = SELECT * */
+  fields?: string[]
+}
+
+export interface ParameterizedQuery {
+  sql: string
+  bindings: (string | number | boolean | null)[]
+}