@materializecms/core 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Novità di Materialize
+
+Ogni versione, dalla più recente. Le novità in arrivo si scrivono sotto «Prossima versione»: `npm run bump` le assegna alla nuova versione.
+
+## Prossima versione
+
+## 0.1.0 — 2026-10-31
+
+La prima versione pubblica.
+
+- **Editor visuale**: pagine disegnate su una tela, con sezioni, colonne, testi, immagini, video, icone e forme; componenti riutilizzabili con varianti; righelli, guide, allineamenti e misure; modalità Contenuti per chi modifica solo i testi.
+- **Animazioni ed effetti**: animazioni allo scorrimento e con linee temporali, stati al passaggio del mouse, sfondi WebGL e oggetti 3D.
+- **Contenuti**: raccolte come Progetti, Diario e Team, con pagine modello; azioni rapide e selezione multipla negli elenchi e nei Media.
+- **Siti in più lingue**: traduzioni collegate tra loro, anche con l’AI, e un selettore di lingua per il sito.
+- **SEO**: titoli e descrizioni, sitemap, controlli sulla pagina e reindirizzamenti automatici quando cambia un indirizzo.
+- **Moduli di contatto** con invio delle email dal tuo server di posta.
+- **Assistente AI e server MCP**: testi, traduzioni e modifiche alle pagine chiedendole a parole.
+- **Importazione da WordPress**: pagine, articoli e immagini.
+- **Statistiche e cookie**: Google Analytics, Tag Manager, Meta Pixel, Plausible, Matomo e codice personalizzato, con il banner per il consenso.
+- **Installazione su VPS con un comando**: Node.js, HTTPS con Caddy, servizio che riparte da solo, firewall e link per finire nel browser.
+- **Immagine Docker** con `compose.yaml` pronto per l'HTTPS: il sito sta in un volume, quindi gli aggiornamenti dal pannello restano anche ricreando il container.
+- **Installazione nel browser**: controllo del server, nome e lingua del sito, account amministratore, passo per passo.
+- **Aggiornamenti con un clic** da Impostazioni → Aggiornamenti, con backup prima e ritorno automatico alla versione precedente se la nuova non parte; le correzioni possono installarsi da sole.
+- **Sicurezza**: verifica in due passaggi, pausa dopo i tentativi di accesso falliti, registro delle attività, backup giornalieri del database e dei media.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristiano Casazza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# @materializecms/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Il modello dei contenuti di Materialize: raccolte, campi, validazione, libreria di sezioni, SEO.
+
+Qui si definisce lo schema del sito in `materialize.config.ts`, con `defineConfig`, `defineCollection` e i campi `f.*`. Contiene anche i tipi condivisi, la libreria di sezioni del costruttore di pagine, la SEO e le animazioni.
+
+```ts
+import { defineCollection, defineConfig, f } from '@materializecms/core'
+```
+
+## Materialize
+
+CMS open source con editor visuale: le pagine si disegnano sulla tela, il sito è fatto di file statici veloci. Per un nuovo sito (serve Node 24):
+
+```bash
+npm create materialize@latest
+```
+
+Documentazione e codice: https://github.com/materializecms/materialize · Licenza MIT.

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@materializecms/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Il modello dei contenuti di Materialize: raccolte, campi, validazione, libreria di sezioni, SEO.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/materializecms/materialize.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/materializecms/materialize#readme",
+  "bugs": "https://github.com/materializecms/materialize/issues",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./slug": {
+      "types": "./src/slug.d.ts",
+      "default": "./src/slug.js"
+    },
+    "./style": {
+      "types": "./src/style.d.ts",
+      "default": "./src/style.js"
+    },
+    "./page": {
+      "types": "./src/page.d.ts",
+      "default": "./src/page.js"
+    },
+    "./library": {
+      "types": "./src/library.d.ts",
+      "default": "./src/library.js"
+    },
+    "./motion": {
+      "types": "./src/motion.d.ts",
+      "default": "./src/motion.js"
+    },
+    "./scene": {
+      "types": "./src/scene.d.ts",
+      "default": "./src/scene.js"
+    },
+    "./icons": {
+      "types": "./src/icons.d.ts",
+      "default": "./src/icons.js"
+    },
+    "./seo": {
+      "types": "./src/seo.d.ts",
+      "default": "./src/seo.js"
+    },
+    "./i18n": {
+      "types": "./src/i18n.d.ts",
+      "default": "./src/i18n.js"
+    },
+    "./tracking": {
+      "types": "./src/tracking.d.ts",
+      "default": "./src/tracking.js"
+    },
+    "./updates": {
+      "types": "./src/updates.d.ts",
+      "default": "./src/updates.js"
+    }
+  },
+  "dependencies": {
+    "lucide": "1.64.0",
+    "three": "0.186.1",
+    "zod": "4.6.7"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/fields.d.ts

@@ -0,0 +1,204 @@
+import { z } from 'zod';
+import type { PageNode } from './page.ts';
+import { type BlockStyle } from './style.ts';
+export type FieldKind = 'text' | 'richText' | 'number' | 'boolean' | 'date' | 'select' | 'slug' | 'media' | 'link' | 'relation' | 'blocks' | 'page' | 'group' | 'array' | 'seo' | 'color' | 'json';
+/**
+ * A field definition. `V` is the stored value type and `R` whether the field is required;
+ * both exist only at the type level so documents can be typed straight from the schema.
+ */
+export interface Field<V = unknown, R extends boolean = boolean> {
+    readonly kind: FieldKind;
+    readonly required: R;
+    readonly label?: string;
+    readonly description?: string;
+    readonly localized: boolean;
+    readonly options: Readonly<Record<string, unknown>>;
+    /** Validator for a present value; optionality is applied by the collection. */
+    readonly schema: () => z.ZodType;
+    readonly children?: Fields;
+    readonly item?: Field;
+    readonly blocks?: readonly Block[];
+    readonly __value?: V;
+}
+export type Fields = Record<string, Field>;
+export interface Block<N extends string = string, F extends Fields = Fields> {
+    readonly name: N;
+    readonly label: string;
+    readonly description?: string;
+    readonly fields: F;
+}
+interface Common<R extends boolean> {
+    label?: string;
+    description?: string;
+    required?: R;
+    /** Store a separate value per locale. Defaults to true for text-like fields in localized collections. */
+    localized?: boolean;
+}
+type Req<O> = O extends {
+    required: true;
+} ? true : false;
+export interface Media {
+    src: string;
+    alt: string;
+    width?: number;
+    height?: number;
+    /** Focal point in percent, kept visible whatever the crop. */
+    focal?: {
+        x: number;
+        y: number;
+    };
+}
+export interface Link {
+    href: string;
+    label?: string;
+    newTab?: boolean;
+}
+export interface Seo {
+    title?: string;
+    description?: string;
+    image?: Media;
+    noindex?: boolean;
+    /** Search engines index the page but do not follow its links. */
+    nofollow?: boolean;
+    /** Title and description when shared (Facebook, LinkedIn, WhatsApp, X), if different. */
+    socialTitle?: string;
+    socialDescription?: string;
+    /** The address search engines should consider the original, when this page repeats another. */
+    canonical?: string;
+    /** Structured data: what kind of page this is (see SCHEMA_TYPES in seo.ts). */
+    schema?: 'article' | 'project' | 'service' | 'event' | 'faq';
+    faq?: {
+        q: string;
+        a: string;
+    }[];
+    event?: {
+        start?: string;
+        end?: string;
+        place?: string;
+        address?: string;
+        online?: boolean;
+        price?: string;
+    };
+}
+/** Inline text with formatting marks. */
+export interface RichTextRun {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    href?: string;
+}
+export interface RichTextBlock {
+    type: 'paragraph' | 'heading' | 'quote' | 'listItem' | 'image';
+    level?: 2 | 3 | 4;
+    children: RichTextRun[];
+    /** An image between paragraphs (type "image"); its children are empty. */
+    image?: Media;
+}
+export type RichText = RichTextBlock[];
+interface TextOptions<R extends boolean> extends Common<R> {
+    min?: number;
+    max?: number;
+    multiline?: boolean;
+    placeholder?: string;
+}
+declare function text<const O extends TextOptions<boolean>>(o?: O): Field<string, Req<O>>;
+declare function richText<const O extends Common<boolean>>(o?: O): Field<RichText, Req<O>>;
+interface NumberOptions<R extends boolean> extends Common<R> {
+    min?: number;
+    max?: number;
+    integer?: boolean;
+}
+declare function number<const O extends NumberOptions<boolean>>(o?: O): Field<number, Req<O>>;
+declare function boolean<const O extends Common<boolean>>(o?: O): Field<boolean, Req<O>>;
+declare function date<const O extends Common<boolean>>(o?: O): Field<string, Req<O>>;
+type SelectOption = string | {
+    value: string;
+    label: string;
+};
+type OptionValue<T> = T extends {
+    value: infer V extends string;
+} ? V : T extends string ? T : never;
+interface SelectOptions<R extends boolean, T extends readonly SelectOption[]> extends Common<R> {
+    options: T;
+}
+declare function select<const T extends readonly SelectOption[], const O extends SelectOptions<boolean, T>>(o: O & {
+    options: T;
+}): Field<OptionValue<T[number]>, Req<O>>;
+interface SlugOptions<R extends boolean> extends Common<R> {
+    /** Field to generate the slug from when it is left empty. */
+    from?: string;
+}
+declare function slug<const O extends SlugOptions<boolean>>(o?: O): Field<string, Req<O>>;
+interface MediaOptions<R extends boolean> extends Common<R> {
+    accept?: string;
+    focalPoint?: boolean;
+}
+declare function media<const O extends MediaOptions<boolean>>(o?: O): Field<Media, Req<O>>;
+declare function link<const O extends Common<boolean>>(o?: O): Field<Link, Req<O>>;
+interface RelationOptions<R extends boolean, M extends boolean> extends Common<R> {
+    to: string;
+    many?: M;
+}
+declare function relation<const O extends RelationOptions<boolean, boolean>>(o: O): Field<O extends {
+    many: true;
+} ? string[] : string, Req<O>>;
+export type BlockValue<B extends Block> = B extends Block<infer N, infer F> ? {
+    _type: N;
+    _key: string;
+    _label?: string;
+    _style?: BlockStyle;
+} & InferFields<F> : never;
+interface BlocksOptions<R extends boolean> extends Common<R> {
+    min?: number;
+    max?: number;
+}
+declare function blocks<const B extends readonly Block[], const O extends BlocksOptions<boolean>>(defs: B, o?: O): Field<BlockValue<B[number]>[], Req<O>>;
+declare function group<const F extends Fields, const O extends Common<boolean>>(fields: F, o?: O): Field<InferFields<F>, Req<O>>;
+interface ArrayOptions<R extends boolean> extends Common<R> {
+    min?: number;
+    max?: number;
+}
+declare function array<const I extends Field, const O extends ArrayOptions<boolean>>(item: I, o?: O): Field<NonNullable<I['__value']>[], Req<O>>;
+declare function seo<const O extends Common<boolean>>(o?: O): Field<Seo, Req<O>>;
+declare function color<const O extends Common<boolean>>(o?: O): Field<string, Req<O>>;
+/**
+ * A page composed on the canvas: sections of frames, text, images and buttons, with their design.
+ * Render it with `renderPage` from `@materializecms/core/page`, or the Astro `<Page>` component.
+ */
+declare function page<const O extends Common<boolean>>(o?: O): Field<PageNode[], Req<O>>;
+declare function json<const O extends Common<boolean>>(o?: O): Field<unknown, Req<O>>;
+/** Field builders: `f.text({ required: true })`, `f.blocks([hero, gallery])`, … */
+export declare const f: {
+    text: typeof text;
+    richText: typeof richText;
+    number: typeof number;
+    boolean: typeof boolean;
+    date: typeof date;
+    select: typeof select;
+    slug: typeof slug;
+    media: typeof media;
+    link: typeof link;
+    relation: typeof relation;
+    blocks: typeof blocks;
+    page: typeof page;
+    group: typeof group;
+    array: typeof array;
+    seo: typeof seo;
+    color: typeof color;
+    json: typeof json;
+};
+type ValueOf<F> = F extends Field<infer V, boolean> ? V : never;
+type RequiredKeys<F extends Fields> = {
+    [K in keyof F]: F[K] extends Field<unknown, true> ? K : never;
+}[keyof F];
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** The document data type described by a set of fields. */
+export type InferFields<F extends Fields> = Prettify<{
+    [K in RequiredKeys<F>]: ValueOf<F[K]>;
+} & {
+    [K in Exclude<keyof F, RequiredKeys<F>>]?: ValueOf<F[K]>;
+}>;
+export declare function objectShape(fields: Fields): Record<string, z.ZodType>;
+export {};

package/src/fields.js

@@ -0,0 +1,213 @@
+import { z } from 'zod';
+import { SLUG_PATTERN } from './slug.js';
+import { ANCHOR_PATTERN, BLOCK_STYLE } from './style.js';
+const blockStyleSchema = z.object({
+    background: z.enum(BLOCK_STYLE.background).optional(),
+    spacing: z.enum(BLOCK_STYLE.spacing).optional(),
+    animation: z.enum(BLOCK_STYLE.animation).optional(),
+    anchor: z.string().max(60).regex(ANCHOR_PATTERN, 'Usa lettere minuscole, numeri e trattini').optional(),
+});
+// Returns Field<never, never>, which is assignable to the precise Field<V, R> each builder declares.
+function field(kind, common, options, schema, extra = {}) {
+    return {
+        kind,
+        required: (common?.required ?? false),
+        label: common?.label,
+        description: common?.description,
+        localized: common?.localized ?? ['text', 'richText', 'slug', 'seo', 'link'].includes(kind),
+        options,
+        schema,
+        ...extra,
+    };
+}
+// ---------- shared validators ----------
+const mediaSchema = z.object({
+    src: z.string().min(1),
+    alt: z.string(),
+    width: z.number().int().positive().optional(),
+    height: z.number().int().positive().optional(),
+    focal: z.object({ x: z.number().min(0).max(100), y: z.number().min(0).max(100) }).optional(),
+});
+const linkSchema = z.object({
+    href: z.string().min(1),
+    label: z.string().optional(),
+    newTab: z.boolean().optional(),
+});
+const runSchema = z.object({
+    text: z.string(),
+    bold: z.boolean().optional(),
+    italic: z.boolean().optional(),
+    href: z.string().optional(),
+});
+const richTextSchema = z.array(z
+    .object({
+    type: z.enum(['paragraph', 'heading', 'quote', 'listItem', 'image']),
+    level: z.union([z.literal(2), z.literal(3), z.literal(4)]).optional(),
+    children: z.array(runSchema),
+    image: mediaSchema.optional(),
+})
+    .refine((b) => b.type !== 'image' || !!b.image, { message: 'Scegli l’immagine', path: ['image'] }));
+function text(o) {
+    const { min, max, multiline, placeholder } = o ?? {};
+    return field('text', o, { min, max, multiline, placeholder }, () => {
+        let s = z.string().trim();
+        if (o?.required)
+            s = s.min(Math.max(1, min ?? 1));
+        else if (min)
+            s = s.min(min);
+        if (max)
+            s = s.max(max);
+        return s;
+    });
+}
+function richText(o) {
+    return field('richText', o, {}, () => (o?.required ? richTextSchema.min(1) : richTextSchema));
+}
+function number(o) {
+    const { min, max, integer } = o ?? {};
+    return field('number', o, { min, max, integer }, () => {
+        let s = z.number();
+        if (integer)
+            s = s.int();
+        if (min !== undefined)
+            s = s.min(min);
+        if (max !== undefined)
+            s = s.max(max);
+        return s;
+    });
+}
+function boolean(o) {
+    return field('boolean', o, {}, () => z.boolean());
+}
+function date(o) {
+    return field('date', o, {}, () => z.union([z.iso.date(), z.iso.datetime({ offset: true })]));
+}
+function select(o) {
+    const values = o.options.map((x) => (typeof x === 'string' ? x : x.value));
+    if (!values.length)
+        throw new Error('f.select() needs at least one option');
+    return field('select', o, { options: o.options }, () => z.enum(values));
+}
+function slug(o) {
+    return field('slug', o, { from: o?.from }, () => z.string().max(96).regex(SLUG_PATTERN, 'Usa lettere minuscole, numeri e trattini singoli'));
+}
+function media(o) {
+    return field('media', o, { accept: o?.accept ?? 'image/*', focalPoint: o?.focalPoint ?? true }, () => mediaSchema);
+}
+function link(o) {
+    return field('link', o, {}, () => linkSchema);
+}
+function relation(o) {
+    return field('relation', o, { to: o.to, many: o.many ?? false }, () => o.many ? z.array(z.string().min(1)) : z.string().min(1));
+}
+function blocks(defs, o) {
+    if (!defs.length)
+        throw new Error('f.blocks() needs at least one block');
+    return field('blocks', o, { min: o?.min, max: o?.max }, () => {
+        const variants = defs.map((b) => z.object({
+            _type: z.literal(b.name),
+            _key: z.string().min(1),
+            // A name chosen in the editor's layers, for people only: the site ignores it.
+            _label: z.string().max(80).optional(),
+            _style: blockStyleSchema.optional(),
+            ...objectShape(b.fields),
+        }));
+        const item = variants.length === 1
+            ? variants[0]
+            : z.discriminatedUnion('_type', variants);
+        let s = z.array(item);
+        if (o?.min !== undefined)
+            s = s.min(o.min);
+        if (o?.max !== undefined)
+            s = s.max(o.max);
+        return s;
+    }, { blocks: defs });
+}
+function group(fields, o) {
+    return field('group', o, {}, () => z.object(objectShape(fields)), { children: fields });
+}
+function array(item, o) {
+    return field('array', o, { min: o?.min, max: o?.max }, () => {
+        let s = z.array(item.schema());
+        if (o?.min !== undefined)
+            s = s.min(o.min);
+        if (o?.max !== undefined)
+            s = s.max(o.max);
+        return s;
+    }, { item });
+}
+function seo(o) {
+    return field('seo', o, {}, () => z.object({
+        title: z.string().max(70).optional(),
+        description: z.string().max(170).optional(),
+        image: mediaSchema.optional(),
+        noindex: z.boolean().optional(),
+        nofollow: z.boolean().optional(),
+        socialTitle: z.string().max(90).optional(),
+        socialDescription: z.string().max(200).optional(),
+        canonical: z.string().max(500).optional(),
+        schema: z.enum(['article', 'project', 'service', 'event', 'faq']).optional(),
+        faq: z
+            .array(z.object({ q: z.string().max(300), a: z.string().max(3000) }))
+            .max(50)
+            .optional(),
+        event: z
+            .object({
+            start: z.string().optional(),
+            end: z.string().optional(),
+            place: z.string().optional(),
+            address: z.string().optional(),
+            online: z.boolean().optional(),
+            price: z.string().optional(),
+        })
+            .optional(),
+    }));
+}
+function color(o) {
+    return field('color', o, {}, () => z.string().regex(/^#[0-9a-fA-F]{6}$/, 'Usa un colore nel formato #rrggbb'));
+}
+const pageNodeSchema = z.lazy(() => z
+    .object({
+    id: z.string().min(1),
+    type: z.enum(['frame', 'text', 'image', 'button', 'video', 'embed', 'scene', 'icon', 'input']),
+    name: z.string().max(120).optional(),
+    children: z.array(pageNodeSchema).optional(),
+})
+    .loose());
+/**
+ * A page composed on the canvas: sections of frames, text, images and buttons, with their design.
+ * Render it with `renderPage` from `@materializecms/core/page`, or the Astro `<Page>` component.
+ */
+function page(o) {
+    return field('page', { localized: true, ...o }, {}, () => z.array(pageNodeSchema).max(200));
+}
+function json(o) {
+    return field('json', o, {}, () => z.json());
+}
+/** Field builders: `f.text({ required: true })`, `f.blocks([hero, gallery])`, … */
+export const f = {
+    text,
+    richText,
+    number,
+    boolean,
+    date,
+    select,
+    slug,
+    media,
+    link,
+    relation,
+    blocks,
+    page,
+    group,
+    array,
+    seo,
+    color,
+    json,
+};
+export function objectShape(fields) {
+    const shape = {};
+    for (const [name, def] of Object.entries(fields)) {
+        shape[name] = def.required ? def.schema() : def.schema().optional();
+    }
+    return shape;
+}

package/src/i18n.d.ts

@@ -0,0 +1,36 @@
+import type { Fields } from './fields.ts';
+import { type PageNode } from './page.ts';
+import type { Locales } from './schema.ts';
+/** The site's languages: the ones saved in the panel when valid, else the config's. */
+export declare function withLocales<T extends {
+    locales: Locales;
+}>(config: T, saved: unknown): T;
+export declare const isLocaleCode: (code: string) => boolean;
+/** Node properties a translation changes: the words, the links, the pictures. */
+export declare const TRANSLATED_KEYS: readonly string[];
+/**
+ * The original's structure and design with a translation's words: what a translated header or
+ * footer shows, and how a translated page catches up with a changed original. Elements the
+ * translation does not have keep the original's words.
+ */
+export declare function mergeTranslation(original: PageNode[], translation: PageNode[]): PageNode[];
+/** Ids of the elements in `original` the translation does not have yet. */
+export declare function untranslatedIds(original: PageNode[], translation: PageNode[]): string[];
+/** One text of a document, as sent to the translator, and where its translation goes. */
+export interface TextSlot {
+    text: string;
+    set: (value: string) => void;
+}
+/** The texts of a canvas page: words, formatted sentences, alternative texts, field options. */
+export declare function nodeSlots(nodes: PageNode[]): TextSlot[];
+/**
+ * Every text of a document that a translation changes, read from its fields: texts, rich text,
+ * link labels, alternative texts, SEO, canvas pages, blocks, groups and lists. `data` is changed
+ * in place by the slots, so pass a copy.
+ */
+export declare function documentSlots(fields: Fields, data: Record<string, unknown>): TextSlot[];
+/**
+ * Internal links pointing at pages of the main language, sent to the same pages in this
+ * language where they are translated: "/contatti#form" becomes "/en/contact#form".
+ */
+export declare function localizeLinks(nodes: PageNode[], urls: Record<string, string>): PageNode[];