includio-cms 0.1.3 → 0.5.0

package/dist/admin/client/entry/header/a11y-validator.js

@@ -0,0 +1,311 @@
+import { walkNodes } from '../../../components/tiptap/structured-content-utils.js';
+const GENERIC_LINK_TEXTS = new Set([
+    'kliknij tutaj',
+    'kliknij',
+    'tutaj',
+    'czytaj więcej',
+    'więcej',
+    'dowiedz się więcej',
+    'sprawdź',
+    'link',
+    'here',
+    'click here',
+    'click',
+    'read more',
+    'more',
+    'learn more',
+    'check',
+    'this'
+]);
+/** Count images (figure/image nodes) without alt text. */
+function checkImagesWithoutAlt(doc) {
+    let count = 0;
+    walkNodes(doc.content, (node) => {
+        if (node.type === 'figure' || node.type === 'image') {
+            const alt = node.attrs?.alt;
+            if (!alt || !alt.trim()) {
+                count++;
+            }
+        }
+    });
+    return count;
+}
+/** Check heading hierarchy — returns true if headings are properly ordered.
+ *  Rules:
+ *  - First heading should be H2 (H1 is the page title)
+ *  - Going deeper: can only increase by 1 (H2→H3 ok, H2→H4 not ok)
+ *  - Going up: can jump back freely (H3→H2 ok)
+ *  - But cannot go deeper than previous minimum at that nesting level
+ *    i.e. H3→H2→H4 is invalid (skips H3 after establishing it)
+ */
+function checkHeadingHierarchy(doc) {
+    const levels = [];
+    walkNodes(doc.content, (node) => {
+        if (node.type === 'heading' && node.attrs?.level) {
+            levels.push(node.attrs.level);
+        }
+    });
+    if (levels.length === 0)
+        return true;
+    // First heading should be H2 (H1 is reserved for page title)
+    if (levels[0] > 2)
+        return false;
+    for (let i = 1; i < levels.length; i++) {
+        // Going deeper: can only increase by 1 level
+        if (levels[i] > levels[i - 1] + 1) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Collect text content of a node (recursively). */
+function collectText(node) {
+    let text = node.text ?? '';
+    if (node.content) {
+        for (const child of node.content) {
+            text += collectText(child);
+        }
+    }
+    return text;
+}
+/** Count links with generic/non-descriptive anchor text. */
+function checkGenericLinkTexts(doc) {
+    let count = 0;
+    walkNodes(doc.content, (node) => {
+        if (!node.marks)
+            return;
+        const hasLink = node.marks.some((m) => m.type === 'link');
+        if (hasLink) {
+            const text = collectText(node).trim().toLowerCase();
+            if (text && GENERIC_LINK_TEXTS.has(text)) {
+                count++;
+            }
+        }
+    });
+    return count;
+}
+export function getHeadingIssuePositions(doc) {
+    const issues = [];
+    if (!doc.content)
+        return issues;
+    let pos = 1; // ProseMirror positions: doc starts at 0, first child at 1
+    let seenH2 = false;
+    for (const node of doc.content) {
+        if (node.type === 'heading' && node.attrs?.level) {
+            const level = node.attrs.level;
+            if (level === 2) {
+                seenH2 = true;
+            }
+            else if (level === 3 && !seenH2) {
+                issues.push({
+                    pos,
+                    message: 'Dodaj H2 przed tą podsekcją'
+                });
+            }
+            else if (level > 3 && !seenH2) {
+                issues.push({
+                    pos,
+                    message: 'Pierwszy nagłówek powinien być H2'
+                });
+            }
+        }
+        // Advance position: each block node = open tag + content size + close tag
+        pos += nodeSize(node);
+    }
+    return issues;
+}
+/** Calculate ProseMirror node size (used for position tracking). */
+function nodeSize(node) {
+    if (node.type === 'text') {
+        return (node.text ?? '').length;
+    }
+    // Block/inline nodes: open + content + close = 2 + content size
+    let size = 2;
+    if (node.content) {
+        for (const child of node.content) {
+            size += nodeSize(child);
+        }
+    }
+    return size;
+}
+/** Find position of first image without alt in TipTap JSON doc. */
+export function findFirstImageWithoutAlt(doc) {
+    if (!doc.content)
+        return null;
+    let pos = 1;
+    for (const node of doc.content) {
+        if (node.type === 'figure' || node.type === 'image') {
+            const alt = node.attrs?.alt;
+            if (!alt || !alt.trim())
+                return pos;
+        }
+        pos += nodeSize(node);
+    }
+    return null;
+}
+/** Find position of first heading hierarchy issue in TipTap JSON doc. */
+export function findFirstHeadingIssue(doc) {
+    const issues = getHeadingIssuePositions(doc);
+    return issues.length > 0 ? issues[0].pos : null;
+}
+/** Find position of first generic link in TipTap JSON doc. */
+export function findFirstGenericLink(doc) {
+    if (!doc.content)
+        return null;
+    let pos = 1;
+    function walk(nodes, basePos) {
+        let p = basePos;
+        for (const node of nodes) {
+            if (node.marks?.some((m) => m.type === 'link')) {
+                const text = (node.text ?? '').trim().toLowerCase();
+                if (text && GENERIC_LINK_TEXTS.has(text))
+                    return p;
+            }
+            if (node.content) {
+                const found = walk(node.content, p + 1);
+                if (found !== null)
+                    return found;
+            }
+            p += nodeSize(node);
+        }
+        return null;
+    }
+    return walk(doc.content, pos);
+}
+/** Try to extract a StructuredContentDoc from a value.
+ *  Handles both direct doc format and language-keyed format { en: doc, pl: doc }. */
+function tryExtractDoc(val) {
+    if (!val || typeof val !== 'object')
+        return [];
+    const obj = val;
+    // Direct doc: { type: 'doc', content: [...] }
+    if (obj.type === 'doc' && Array.isArray(obj.content)) {
+        return [obj];
+    }
+    // Language-keyed: { en: { type: 'doc', ... }, pl: { type: 'doc', ... } }
+    const docs = [];
+    for (const langVal of Object.values(obj)) {
+        if (langVal && typeof langVal === 'object') {
+            const langObj = langVal;
+            if (langObj.type === 'doc' && Array.isArray(langObj.content)) {
+                docs.push(langObj);
+            }
+        }
+    }
+    return docs;
+}
+/** Extract StructuredContentDoc values from entry data for content/richtext fields. */
+function extractDocs(data, fields) {
+    const result = [];
+    for (const field of fields) {
+        if (field.type !== 'content' && field.type !== 'richtext')
+            continue;
+        const val = data[field.slug];
+        const docs = tryExtractDoc(val);
+        for (const doc of docs) {
+            result.push({ doc, fieldSlug: field.slug });
+        }
+    }
+    return result;
+}
+export const a11yLangPl = {
+    imagesWithoutAlt: (n) => `${n} ${n === 1 ? 'obraz' : n < 5 ? 'obrazy' : 'obrazów'} bez opisu alternatywnego`,
+    headingsOk: 'Hierarchia nagłówków poprawna',
+    headingsSkipped: 'Nagłówki pomijają poziomy (np. H2 → H4)',
+    genericLinks: (n) => `${n} ${n === 1 ? 'link' : n < 5 ? 'linki' : 'linków'} z generycznym tekstem`,
+    allImagesHaveAlt: 'Wszystkie obrazy mają opis alternatywny',
+    noGenericLinks: 'Linki mają opisowe teksty'
+};
+export const a11yLangEn = {
+    imagesWithoutAlt: (n) => `${n} image${n === 1 ? '' : 's'} without alt text`,
+    headingsOk: 'Heading hierarchy is correct',
+    headingsSkipped: 'Headings skip levels (e.g. H2 → H4)',
+    genericLinks: (n) => `${n} link${n === 1 ? '' : 's'} with generic text`,
+    allImagesHaveAlt: 'All images have alt text',
+    noGenericLinks: 'Links have descriptive text'
+};
+/** Run a11y validation on entry data and return issues list. */
+export function validateA11y(data, fields, lang = a11yLangPl) {
+    const entries = extractDocs(data, fields);
+    const issues = [];
+    // Images without alt
+    let totalMissingAlt = 0;
+    let firstMissingAltPos = null;
+    let firstMissingAltField;
+    for (const { doc, fieldSlug } of entries) {
+        totalMissingAlt += checkImagesWithoutAlt(doc);
+        if (firstMissingAltPos === null) {
+            const pos = findFirstImageWithoutAlt(doc);
+            if (pos !== null) {
+                firstMissingAltPos = pos;
+                firstMissingAltField = fieldSlug;
+            }
+        }
+    }
+    if (totalMissingAlt > 0) {
+        issues.push({
+            type: 'warning',
+            message: lang.imagesWithoutAlt(totalMissingAlt),
+            fieldSlug: firstMissingAltField,
+            firstNodePos: firstMissingAltPos ?? undefined
+        });
+    }
+    else if (entries.length > 0) {
+        issues.push({ type: 'success', message: lang.allImagesHaveAlt });
+    }
+    // Heading hierarchy
+    if (entries.length > 0) {
+        let allHeadingsOk = true;
+        let firstHeadingIssuePos = null;
+        let firstHeadingIssueField;
+        for (const { doc, fieldSlug } of entries) {
+            if (!checkHeadingHierarchy(doc)) {
+                allHeadingsOk = false;
+                if (firstHeadingIssuePos === null) {
+                    const pos = findFirstHeadingIssue(doc);
+                    if (pos !== null) {
+                        firstHeadingIssuePos = pos;
+                        firstHeadingIssueField = fieldSlug;
+                    }
+                }
+            }
+        }
+        if (allHeadingsOk) {
+            issues.push({ type: 'success', message: lang.headingsOk });
+        }
+        else {
+            issues.push({
+                type: 'warning',
+                message: lang.headingsSkipped,
+                fieldSlug: firstHeadingIssueField,
+                firstNodePos: firstHeadingIssuePos ?? undefined
+            });
+        }
+    }
+    // Generic link text
+    let totalGenericLinks = 0;
+    let firstGenericLinkPos = null;
+    let firstGenericLinkField;
+    for (const { doc, fieldSlug } of entries) {
+        totalGenericLinks += checkGenericLinkTexts(doc);
+        if (firstGenericLinkPos === null) {
+            const pos = findFirstGenericLink(doc);
+            if (pos !== null) {
+                firstGenericLinkPos = pos;
+                firstGenericLinkField = fieldSlug;
+            }
+        }
+    }
+    if (totalGenericLinks > 0) {
+        issues.push({
+            type: 'warning',
+            message: lang.genericLinks(totalGenericLinks),
+            fieldSlug: firstGenericLinkField,
+            firstNodePos: firstGenericLinkPos ?? undefined
+        });
+    }
+    else if (entries.length > 0) {
+        issues.push({ type: 'success', message: lang.noGenericLinks });
+    }
+    return issues;
+}