@webround/editor 0.0.0-stage → 0.3.0

package/dist/operations/ops/seo.js

@@ -0,0 +1,358 @@
+import fs from 'fs';
+import path from 'path';
+import { wrPageConfigPath } from '@webround/core/routing';
+import { WR_SEO_KEY, wrJsonLdProblems, wrSearchConsoleCode, wrSeoFiles, wrSnapshotTargets, wrSeoPageOf, wrSiteUrlOf } from '@webround/core/seo';
+import { wrLocalizeItems, wrSetLocalized } from '@webround/core/localized';
+import { defineOperation, flag, invalid, list, OperationError, text } from '../define.js';
+import { checkScopeFromCode } from '../../check/producer-code.js';
+import { SEO_FILE, langKeyOf, patchJsonFile, readJsonFile, readLangs, readRoutes, readSeoSite, scopeFilesOf } from './project.js';
+// What search engines and social networks read: a page's title, description, picture, noindex (under `_seo` in its JSON, translated like any
+// text) and the site's own data (`config/seo.json`). The tags are built by `@webround/core/seo` and the files (robots.txt, the sitemaps) by
+// `wrSeoFiles`: this file only reads and writes the data, for the editor, `wr`, an MCP client and the dev server's watcher alike.
+const PAGE_FIELDS = ['title', 'description'];
+const LANGUAGE_FREE_FIELDS = ['canonical'];
+/** `https://www.example.com` from whatever was typed: only the address, no path. Throws when it is not one. */
+function siteUrlFrom(value) {
+    let url;
+    try {
+        url = new URL(value.trim());
+    }
+    catch {
+        throw invalid('siteUrl must be a full address, e.g. https://www.example.com', 'invalid-site-url');
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        throw invalid('siteUrl must start with https:// (or http://)', 'invalid-site-url');
+    if (url.pathname !== '/' || url.search || url.hash)
+        throw invalid('siteUrl is the address of the site without a path', 'invalid-site-url');
+    return url.origin;
+}
+/** Every page's JSON, by page name: what `wrSeoFiles` needs to know who is noindex. */
+function readPages(ctx) {
+    return Object.fromEntries(Object.keys(readRoutes(ctx)).map(name => [name, readJsonFile(ctx, wrPageConfigPath(name)) ?? undefined]));
+}
+/**
+ * Writes robots.txt and the sitemaps into `public/` (only what changed). Nothing is written while the site does not know its public address.
+ * ONE function: the dev server's watcher calls it whenever pages, languages or SEO data change, `seo-sync` calls it on demand.
+ */
+export function writeSeoFiles(ctx) {
+    const files = wrSeoFiles({ routes: readRoutes(ctx), pages: readPages(ctx), langs: readLangs(ctx) ?? undefined, site: readSeoSite(ctx) });
+    if (!files)
+        return { written: [], reason: 'no-site-url' };
+    const written = [];
+    fs.mkdirSync(ctx.publicRoot, { recursive: true });
+    for (const [name, content] of Object.entries(files)) {
+        const file = path.join(ctx.publicRoot, name);
+        if (fs.existsSync(file) && fs.readFileSync(file, 'utf-8') === content)
+            continue;
+        fs.writeFileSync(file, content);
+        written.push(name);
+    }
+    return { written };
+}
+export const seoGet = defineOperation({
+    name: 'seo-get',
+    readOnly: true,
+    summary: 'What search engines and social networks read: the site\'s data (address, name, title template, favicon, picture, extra sitemaps) and, for a page, its title and description in every language, picture, noindex and canonical.',
+    params: [{ name: 'page', type: 'string', positional: true, help: 'a page; without it only the site\'s data' }],
+    run: (input, ctx) => {
+        const page = text(input, 'page');
+        const site = readSeoSite(ctx);
+        return {
+            site,
+            siteUrlKnown: wrSiteUrlOf(site) !== undefined,
+            langs: readLangs(ctx),
+            ...(page ? { page: { pageName: page, seo: wrSeoPageOf(readJsonFile(ctx, scopeFilesOf(ctx, page).json) ?? undefined) } } : {}),
+        };
+    },
+});
+const TITLE_SUGGESTED_MAX = 60;
+const DESCRIPTION_SUGGESTED_MAX = 155;
+/** `text` cut at a word, with an ellipsis, so that it fits in `max` characters. */
+function fitted(text, max) {
+    if (text.length <= max)
+        return text;
+    const cut = text.slice(0, max - 1);
+    return `${cut.slice(0, Math.max(cut.lastIndexOf(' '), max / 2))}…`.replace(/[\s,;:.-]+…$/, '…');
+}
+/**
+ * The text of the page that is written in a language, in document order: the elements read for that language (a rich text's headings and
+ * paragraphs included). In a language other than the default only what is TRANSLATED counts — an element whose text comes from the code, or
+ * a rich text with no translation, would be the default language's words under another name.
+ */
+function wordsIn(nodes, lang, translated = lang === 'default') {
+    return nodes.flatMap(node => {
+        if (node.hidden)
+            return [];
+        // An element that holds a translated field says whether it is; what is made of its text (a rich text's headings) follows it
+        const own = node.values?.content ? lang === 'default' || lang in node.values.content : translated;
+        return [...(node.text && own ? [{ tag: node.tag, text: node.text }] : []), ...wordsIn(node.children, lang, own)];
+    });
+}
+export const seoSuggest = defineOperation({
+    name: 'seo-suggest',
+    readOnly: true,
+    summary: 'A title and a description for a page, taken from what it says: its first heading and its first paragraph, in the language asked (nothing for a language the page is not translated in). Only a proposal: nothing is written.',
+    params: [
+        { name: 'page', type: 'string', positional: true, required: true, help: 'the page' },
+        { name: 'lang', type: 'string', help: 'the language: `default` (the default one) or a language code of the site' },
+    ],
+    run: (input, ctx) => {
+        const page = text(input, 'page', { required: true });
+        const lang = langKeyOf(ctx, text(input, 'lang'));
+        // The page's own code, not the shared header and footer: their text says what the site is, not what the page is
+        const words = wordsIn(checkScopeFromCode(ctx, scopeFilesOf(ctx, page), { lang }).nodes, lang);
+        const heading = words.find(w => w.tag === 'h1')?.text;
+        const paragraph = words.find(w => w.tag === 'p' && w.text.length >= 20)?.text;
+        return {
+            page, lang,
+            ...(heading ? { title: fitted(heading, TITLE_SUGGESTED_MAX) } : {}),
+            ...(paragraph ? { description: fitted(paragraph, DESCRIPTION_SUGGESTED_MAX) } : {}),
+        };
+    },
+});
+const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** A translated text with one language written (an empty text takes it away); undefined when nothing is left of it. */
+function writeText(current, lang, value) {
+    const map = { ...wrSetLocalized(current, lang, value.trim()) };
+    if (!value.trim())
+        delete map[lang];
+    return Object.keys(map).length === 0 ? undefined : map;
+}
+/**
+ * `writeText` for a value that is the same for every language until one is written for a language of its own (a name, a picture): while only the default language has it, it is
+ * the plain text it always was; once another language has one it is a map.
+ */
+function writeLocalized(current, lang, value) {
+    const map = writeText(current, lang, value);
+    if (!map)
+        return undefined;
+    const languages = Object.keys(map);
+    return languages.length === 1 && languages[0] === 'default' ? map.default : map;
+}
+/** What a caller gave as JSON-LD (a list, one object, or JSON text of either) as a list of objects; throws when it is not JSON-LD. */
+function jsonLdItems(input, key) {
+    let value = input[key];
+    if (typeof value === 'string') {
+        if (!value.trim())
+            return [];
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            throw invalid(`${key} is not valid JSON`, 'invalid-json-ld');
+        }
+    }
+    const items = Array.isArray(value) ? value : value === null || value === undefined ? [] : [value];
+    const problems = wrJsonLdProblems(items);
+    if (problems.length > 0)
+        throw invalid(`${problems.join('; ')}`, 'invalid-json-ld');
+    return items;
+}
+/** The JSON-LD of a page or the site with one language's list written: a list while it is the same for every language, a map once a language has its own. */
+function writeJsonLd(current, lang, items) {
+    const map = Array.isArray(current) ? { default: current } : isPlainObject(current) ? { ...current } : {};
+    if (items.length === 0)
+        delete map[lang];
+    else
+        map[lang] = items;
+    const languages = Object.keys(map);
+    if (languages.length === 0)
+        return undefined;
+    return languages.length === 1 && languages[0] === 'default' ? map.default : map;
+}
+export const seoSet = defineOperation({
+    name: 'seo-set',
+    summary: 'Sets what a page tells search engines and social networks. Title, description, pictures and the texts for social networks are written in one language (the default one unless `lang` says otherwise); an empty text takes the value away.',
+    params: [
+        { name: 'page', type: 'string', positional: true, required: true, help: 'the page' },
+        { name: 'lang', type: 'string', help: 'the language of the texts and pictures (title, description, image, ogTitle, ogDescription, ogImage, meta, jsonLd): `default` (the default one) or a language code of the site' },
+        { name: 'title', type: 'string', help: 'the title of the page (what the browser tab and search results show)' },
+        { name: 'description', type: 'string', help: 'a sentence or two for search results (about 150 characters)' },
+        { name: 'image', type: 'string', help: 'picture shown when the page is shared: a path in the site (/media/x.jpg) or a full address (written in `lang`: a language with none uses the default one\'s)' },
+        { name: 'noindex', type: 'boolean', help: 'keep the page out of search engines and out of the sitemap' },
+        { name: 'canonical', type: 'string', help: 'the page this one is a copy of (a path in the site or a full address)' },
+        { name: 'robots', type: 'string', help: 'the robots directives in full, e.g. "noindex, follow" or "max-snippet:-1"; they replace what noindex says' },
+        { name: 'ogTitle', type: 'string', help: 'the title social networks show, when it must not be the page\'s own (written in `lang`)' },
+        { name: 'ogDescription', type: 'string', help: 'the description social networks show, when it must not be the page\'s own (written in `lang`)' },
+        { name: 'ogImage', type: 'string', help: 'the picture social networks show, when it must not be the page\'s own (written in `lang`)' },
+        { name: 'ogType', type: 'string', help: 'the Open Graph type: website (the default), article, product…' },
+        { name: 'twitterCard', type: 'string', choices: ['summary', 'summary_large_image'], help: 'how the page looks when shared on X/Twitter' },
+        { name: 'twitterSite', type: 'string', help: 'the account of the site on X/Twitter (@acme), for this page' },
+        { name: 'twitterCreator', type: 'string', help: 'the account of the author on X/Twitter (@jane), for this page' },
+        { name: 'meta', type: 'array', help: 'any other <meta> the page needs: a list of { name | property, content }, the whole list; content is written in `lang`' },
+        { name: 'jsonLd', type: 'any', help: 'structured data (JSON-LD) of this page: a list of objects with a "@type" (or JSON text of one), written for `lang`; [] takes it away. It is added to the site\'s' },
+    ],
+    run: (input, ctx) => {
+        const page = text(input, 'page', { required: true });
+        const json = scopeFilesOf(ctx, page).json;
+        const current = wrSeoPageOf(readJsonFile(ctx, json) ?? undefined);
+        const next = { ...current };
+        const lang = langKeyOf(ctx, text(input, 'lang'));
+        const set = (key, value) => { if (value === undefined)
+            delete next[key];
+        else
+            next[key] = value; };
+        for (const field of PAGE_FIELDS) {
+            const value = text(input, field);
+            if (value !== undefined)
+                set(field, writeText(current[field], lang, value));
+        }
+        for (const field of LANGUAGE_FREE_FIELDS) {
+            const value = text(input, field);
+            if (value === undefined)
+                continue;
+            if (value.trim())
+                next[field] = value.trim();
+            else
+                delete next[field];
+        }
+        const image = text(input, 'image');
+        if (image !== undefined)
+            set('image', writeLocalized(current.image, lang, image));
+        const noindex = flag(input, 'noindex');
+        if (noindex !== undefined) {
+            if (noindex)
+                next.noindex = true;
+            else
+                delete next.noindex;
+        }
+        const robots = text(input, 'robots');
+        if (robots !== undefined)
+            set('robots', robots.trim() || undefined);
+        // What social networks show: an object that exists only while it has something in it
+        const og = { ...(current.og ?? {}) };
+        const ogSet = (key, value) => { if (value === undefined)
+            delete og[key];
+        else
+            og[key] = value; };
+        for (const [param, key] of [['ogTitle', 'title'], ['ogDescription', 'description']]) {
+            const value = text(input, param);
+            if (value !== undefined)
+                ogSet(key, writeText(og[key], lang, value));
+        }
+        const ogImage = text(input, 'ogImage');
+        if (ogImage !== undefined)
+            ogSet('image', writeLocalized(og.image, lang, ogImage));
+        const ogType = text(input, 'ogType');
+        if (ogType !== undefined)
+            ogSet('type', ogType.trim() || undefined);
+        if (['ogTitle', 'ogDescription', 'ogImage', 'ogType'].some(param => input[param] !== undefined))
+            set('og', Object.keys(og).length > 0 ? og : undefined);
+        const twitter = { ...(current.twitter ?? {}) };
+        for (const [param, key] of [['twitterCard', 'card'], ['twitterSite', 'site'], ['twitterCreator', 'creator']]) {
+            const value = text(input, param);
+            if (value === undefined)
+                continue;
+            if (key === 'card' && value.trim() && !['summary', 'summary_large_image'].includes(value.trim()))
+                throw invalid('twitterCard is summary or summary_large_image', 'invalid-value');
+            if (value.trim())
+                twitter[key] = value.trim();
+            else
+                delete twitter[key];
+        }
+        if (['twitterCard', 'twitterSite', 'twitterCreator'].some(param => input[param] !== undefined))
+            set('twitter', Object.keys(twitter).length > 0 ? twitter : undefined);
+        if (input.meta !== undefined) {
+            const given = input.meta;
+            if (!Array.isArray(given) || given.some(entry => !isPlainObject(entry) || (typeof entry.name !== 'string' && typeof entry.property !== 'string') || typeof entry.content !== 'string')) {
+                throw invalid('meta must be a list of { name or property, content }', 'invalid-value');
+            }
+            const entries = wrLocalizeItems(current.meta, given, ['content'], lang);
+            set('meta', entries.length > 0 ? entries : undefined);
+        }
+        if (input.jsonLd !== undefined)
+            set('jsonLd', writeJsonLd(current.jsonLd, lang, jsonLdItems(input, 'jsonLd')));
+        patchJsonFile(ctx, json, { [WR_SEO_KEY]: Object.keys(next).length > 0 ? next : null });
+        return { page, seo: next };
+    },
+});
+export const seoSiteSet = defineOperation({
+    name: 'seo-site-set',
+    summary: 'Sets what is the same for the whole site: its public address (needed for canonical links, hreflang and the sitemaps), name, how page titles are shown, the favicon, the default sharing picture, the Google Search Console verification code, and the sitemaps the site does not write itself. An empty text takes the value away.',
+    params: [
+        { name: 'siteUrl', type: 'string', help: 'the public address, no path: https://www.example.com' },
+        { name: 'siteName', type: 'string', help: 'the name of the site (written in `lang`)' },
+        { name: 'titleTemplate', type: 'string', help: 'how a title is shown, %s being the page\'s title: "%s | Acme" (written in `lang`)' },
+        { name: 'favicon', type: 'string', help: 'the icon of the site (browser tab, search results): a path in the site (/favicon.png) or a full address' },
+        { name: 'image', type: 'string', help: 'the sharing picture of pages that have none: a path in the site or a full address (written in `lang`)' },
+        { name: 'searchConsole', type: 'string', help: 'the code that proves the site is yours to Google Search Console: the code, or the whole <meta name="google-site-verification"…> tag as Google shows it (only the code is kept); it is written in every page\'s head' },
+        { name: 'extraSitemaps', type: 'array', help: 'sitemaps the index must point to besides the site\'s own, e.g. ["sitemap-products.xml"] (the shop writes it); a list, [] for none' },
+        { name: 'twitterSite', type: 'string', help: 'the account of the site on X/Twitter (@acme), for every page' },
+        { name: 'twitterCreator', type: 'string', help: 'the account of the author on X/Twitter (@jane), for every page' },
+        { name: 'lang', type: 'string', help: 'the language of `siteName`, `titleTemplate`, `image` and `jsonLd`: `default` (the default one) or a language code of the site' },
+        { name: 'jsonLd', type: 'any', help: 'structured data (JSON-LD) of every page — the organisation, the website: a list of objects with a "@type" (or JSON text of one), written for `lang`; [] takes it away' },
+    ],
+    run: (input, ctx) => {
+        const patch = {};
+        const siteUrl = text(input, 'siteUrl');
+        if (siteUrl !== undefined)
+            patch.siteUrl = siteUrl.trim() ? siteUrlFrom(siteUrl) : null;
+        const siteLang = langKeyOf(ctx, text(input, 'lang'));
+        const current = readSeoSite(ctx);
+        const favicon = text(input, 'favicon');
+        if (favicon !== undefined)
+            patch.favicon = favicon.trim() || null;
+        for (const field of ['siteName', 'image']) {
+            const value = text(input, field);
+            if (value !== undefined)
+                patch[field] = writeLocalized(current[field], siteLang, value) ?? null;
+        }
+        const template = text(input, 'titleTemplate');
+        if (template !== undefined) {
+            if (template.trim() && !template.includes('%s'))
+                throw invalid('titleTemplate must contain %s, where the page\'s title goes', 'invalid-title-template');
+            patch.titleTemplate = writeLocalized(current.titleTemplate, siteLang, template) ?? null;
+        }
+        const searchConsole = text(input, 'searchConsole');
+        if (searchConsole !== undefined) {
+            const code = searchConsole.trim() ? wrSearchConsoleCode(searchConsole) : null;
+            if (searchConsole.trim() && !code)
+                throw invalid('that is not a Search Console verification code: paste the code, or the <meta name="google-site-verification" …> tag Google gives', 'invalid-search-console');
+            patch.searchConsole = code;
+        }
+        const extra = list(input, 'extraSitemaps');
+        if (extra !== undefined) {
+            const names = extra.map(name => name.trim()).filter(Boolean);
+            if (names.some(name => /\s/.test(name)))
+                throw invalid('a sitemap is a file name or an address, without spaces', 'invalid-sitemap');
+            patch.extraSitemaps = names.length > 0 ? names : null;
+        }
+        if (input.twitterSite !== undefined || input.twitterCreator !== undefined) {
+            const twitter = { ...(readSeoSite(ctx).twitter ?? {}) };
+            for (const [param, key] of [['twitterSite', 'site'], ['twitterCreator', 'creator']]) {
+                const value = text(input, param);
+                if (value === undefined)
+                    continue;
+                if (value.trim())
+                    twitter[key] = value.trim();
+                else
+                    delete twitter[key];
+            }
+            patch.twitter = Object.keys(twitter).length > 0 ? twitter : null;
+        }
+        if (input.jsonLd !== undefined)
+            patch.jsonLd = writeJsonLd(readSeoSite(ctx).jsonLd, langKeyOf(ctx, text(input, 'lang')), jsonLdItems(input, 'jsonLd')) ?? null;
+        patchJsonFile(ctx, SEO_FILE, patch);
+        const site = readSeoSite(ctx);
+        return { site };
+    },
+});
+export const seoSync = defineOperation({
+    name: 'seo-sync',
+    summary: 'Writes robots.txt, sitemap-index.xml and sitemap-pages.xml in public/ from the pages, the languages and the SEO data. The dev server does it by itself whenever those change: this is for when it is not running. Needs the site\'s public address (seo-site-set).',
+    run: (_input, ctx) => {
+        const result = writeSeoFiles(ctx);
+        if (result.reason === 'no-site-url')
+            throw new OperationError(409, 'no-site-url', 'the site does not know its public address yet: set siteUrl with seo-site-set');
+        return result;
+    },
+});
+export const seoSnapshotTargets = defineOperation({
+    name: 'seo-snapshot-targets',
+    readOnly: true,
+    summary: 'The pages a build prerenders as HTML for search engines and bots (each page in each language, without those marked noindex), with the address of each and the file it is written to.',
+    params: [],
+    run: (_input, ctx) => ({ targets: wrSnapshotTargets({ routes: readRoutes(ctx), pages: readPages(ctx), langs: readLangs(ctx) ?? undefined }) }),
+});
+export const SEO_OPERATIONS = [seoGet, seoSuggest, seoSet, seoSiteSet, seoSync, seoSnapshotTargets];
+//# sourceMappingURL=seo.js.map

package/dist/operations/ops/style.d.ts

@@ -0,0 +1,76 @@
+import { type WrStateId, type WrStyleDescription, type WrStyleOptions } from '@webround/core/style';
+import { type OperationContext, type OperationInput } from '../define.js';
+/**
+ * The colors the project's theme names, and how they look: the `--color-*` of its `@theme` (in theme.css, or in index.css for an older site: what makes `text-accent` a class), and
+ * the color each one comes to (`--color-accent: var(--wr-color-accent)` → the value of `--wr-color-accent` in theme.css, the light theme's).
+ * The starter site's names when the stylesheet says none.
+ */
+export declare function themeColorsOf(ctx: OperationContext): {
+    tokens: string[];
+    swatches: Record<string, string>;
+};
+export declare function element(ctx: OperationContext, input: OperationInput): {
+    found: {
+        node: import("../../vite-plugins/jsx-tree.js").JsxNode;
+        full: import("../../vite-plugins/jsx-tree.js").FullJsxNode;
+        kind: import("@webround/core/kinds").WrElementKind;
+    };
+    id: string;
+    scope: import("./project.js").ScopeFiles;
+};
+/** The element's classes when they are a plain text (or there are none); an expression (`cn(…)`, a template) is the code's, and is not rewritten. */
+export declare function classesOf(found: ReturnType<typeof element>['found']): {
+    className: string;
+} | {
+    className: null;
+    reason: string;
+};
+export declare const optionsOf: (ctx: OperationContext) => WrStyleOptions;
+/** What a className says for each state (hover, focus, pressed) that it says something for: the states of the properties that can have one. */
+export declare function statesOf(className: string, options: WrStyleOptions): Partial<Record<WrStateId, WrStyleDescription[]>>;
+export declare const styleCatalog: import("../define.js").Operation;
+export declare const styleGet: import("../define.js").Operation;
+/** The shared styles an element's classes use. */
+export declare function setsOf(ctx: OperationContext, className: string): {
+    name: string;
+    class: string;
+}[];
+export declare const styleSet: import("../define.js").Operation;
+/**
+ * The step every change of classes takes: find who is styled (an element, or a shared style by `set`), refuse classes that are code, ask `next` for the text, write it if it changed, say what it is now.
+ * What a change IS (a value, a copy between screens) is the table's; this is only reading and writing the file.
+ */
+export declare function changeClasses(ctx: OperationContext, input: OperationInput, next: (className: string, options: WrStyleOptions) => string): {
+    set: string;
+    changed: boolean;
+    previous: string;
+    className: string;
+    styles: WrStyleDescription[];
+    unmanaged: string[];
+    states: Partial<Record<"hover" | "focus" | "active", WrStyleDescription[]>>;
+    usedBy: number;
+    id?: undefined;
+    sets?: undefined;
+} | {
+    id: string;
+    changed: boolean;
+    previous: string;
+    className: string;
+    styles: WrStyleDescription[];
+    unmanaged: string[];
+    states: Partial<Record<"hover" | "focus" | "active", WrStyleDescription[]>>;
+    sets: {
+        name: string;
+        class: string;
+    }[];
+    set?: undefined;
+    usedBy?: undefined;
+};
+export declare const styleCopy: import("../define.js").Operation;
+/**
+ * Puts an element's classes back exactly as they were: what the editor's undo and redo need, because what a change replaced (padding replaces padding-x,
+ * a custom width…) cannot be said as another change. Only for the editor's page: an agent has style-set, which says what it means.
+ */
+export declare const styleRestore: import("../define.js").Operation;
+export declare const STYLE_OPERATIONS: import("../define.js").Operation[];
+//# sourceMappingURL=style.d.ts.map