@blokkli/editor 2.0.0-alpha.5 → 2.0.0-alpha.50

package/dist/runtime/editor/features/analyze/analyzers/axe.js

@@ -0,0 +1,78 @@
+import { defineAnalyzer } from "./defineAnalyzer.js";
+import { falsy } from "#blokkli/helpers";
+function mapAxeNode(node) {
+  return {
+    description: node.failureSummary,
+    impact: node.impact ?? void 0,
+    targets: node.target.map((v) => {
+      if (Array.isArray(v)) {
+        return null;
+      }
+      return v;
+    }).filter(falsy)
+  };
+}
+function mapAxeResult(result, status) {
+  return {
+    id: result.id,
+    title: result.description,
+    category: "accessibility",
+    description: result.help,
+    link: result.helpUrl,
+    status,
+    impact: result.impact ?? void 0,
+    nodes: result.nodes.map(mapAxeNode)
+  };
+}
+function mapAxeResults(results, status) {
+  return results.map((v) => mapAxeResult(v, status));
+}
+async function getLocale(langcode) {
+  if (langcode === "de") {
+    const de = await import("axe-core/locales/de.json");
+    return de.default;
+  } else if (langcode === "fr") {
+    const fr = await import("axe-core/locales/fr.json");
+    return fr.default;
+  } else if (langcode === "it") {
+    const it = await import("axe-core/locales/it.json");
+    return it.default;
+  }
+  return null;
+}
+export default defineAnalyzer((options) => {
+  const userExclude = options?.exclude ?? [];
+  const elementContext = {
+    exclude: [
+      "#nuxt-devtools-container",
+      ".bk",
+      ".bk-sidebar",
+      "#bk-animation-canvas-webgl",
+      ...userExclude
+    ]
+  };
+  let axe;
+  return {
+    id: "axe",
+    label: "Axe (Accessibility Check)",
+    requireRawPage: true,
+    init: async function(context) {
+      const axeModule = await import("axe-core");
+      axe = axeModule.default;
+      const locale = await getLocale(context.interfaceLangcode) ?? {};
+      axe.configure({
+        locale
+      });
+    },
+    run: function() {
+      return axe.run(elementContext, options?.runOptions ?? {}).then((result) => {
+        return [
+          ...mapAxeResults(result.incomplete, "incomplete"),
+          ...mapAxeResults(result.inapplicable, "inapplicable"),
+          ...mapAxeResults(result.passes, "pass"),
+          ...mapAxeResults(result.violations, "violation")
+        ];
+      });
+    }
+  };
+});

package/dist/runtime/editor/features/analyze/analyzers/defineAnalyzer.d.ts

@@ -0,0 +1,4 @@
+import type { Analyzer } from './types.js';
+type AnalyzerInit<O extends object> = (options?: O) => Analyzer;
+export declare function defineAnalyzer<O extends object, HasOptions = object extends O ? true : false>(init: AnalyzerInit<O>): HasOptions extends true ? (options?: O) => Analyzer : (options: O) => Analyzer;
+export {};

package/dist/runtime/editor/features/analyze/analyzers/defineAnalyzer.js

@@ -0,0 +1,5 @@
+export function defineAnalyzer(init) {
+  return function(options) {
+    return init(options);
+  };
+}

package/dist/runtime/editor/features/analyze/analyzers/headingStructure.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (options?: object | undefined) => import("./types.js").Analyzer;
+export default _default;

package/dist/runtime/editor/features/analyze/analyzers/headingStructure.js

@@ -0,0 +1,141 @@
+import { falsy } from "#blokkli/helpers";
+import { defineAnalyzer } from "./defineAnalyzer.js";
+export default defineAnalyzer(() => {
+  return {
+    id: "blokkli:heading-structure",
+    label: (_langcode, $t) => $t("analyzeHeadingStructureLabel", "Heading Structure"),
+    continuous: true,
+    run: async (context) => {
+      const $t = context.$t;
+      const results = [];
+      const allHeadings = [
+        ...context.providerRootElement.querySelectorAll(
+          "h1, h2, h3, h4, h5, h6"
+        )
+      ].map((heading) => {
+        if (heading instanceof HTMLElement) {
+          const level = parseInt(heading.tagName.substring(1));
+          return {
+            element: heading,
+            level,
+            text: heading.textContent?.trim() || ""
+          };
+        }
+      }).filter(falsy);
+      const h1Elements = allHeadings.filter((h) => h.level === 1);
+      if (h1Elements.length > 1) {
+        results.push({
+          id: "blokkli:heading-structure:multiple-h1",
+          title: $t("analyzeHeadingMultipleH1", "Multiple H1 headings"),
+          category: "seo",
+          description: $t(
+            "analyzeHeadingMultipleH1Description",
+            "The page contains multiple H1 headings. There should only be one H1 heading per page."
+          ),
+          status: "violation",
+          impact: "serious",
+          nodes: h1Elements.map((h) => ({
+            description: h.text,
+            targets: h.element
+          }))
+        });
+      } else if (h1Elements.length === 1) {
+        results.push({
+          id: "blokkli:heading-structure:single-h1",
+          title: $t("analyzeHeadingSingleH1", "Single H1 heading"),
+          category: "seo",
+          description: $t(
+            "analyzeHeadingSingleH1Description",
+            "The page has exactly one H1 heading."
+          ),
+          status: "pass",
+          nodes: h1Elements.map((h) => ({
+            description: h.text,
+            targets: h.element
+          }))
+        });
+      }
+      const orderIssues = [];
+      for (let i = 1; i < allHeadings.length; i++) {
+        const previous = allHeadings[i - 1];
+        const current = allHeadings[i];
+        if (!previous || !current) {
+          continue;
+        }
+        if (current.level > previous.level + 1) {
+          orderIssues.push({ current, previous });
+        }
+      }
+      if (orderIssues.length > 0) {
+        results.push({
+          id: "blokkli:heading-structure:skipped-levels",
+          title: $t("analyzeHeadingSkippedLevels", "Skipped heading levels"),
+          category: "seo",
+          description: $t(
+            "analyzeHeadingSkippedLevelsDescription",
+            "Headings skip a level. The heading hierarchy should not skip levels (e.g. do not jump from H2 to H4)."
+          ),
+          status: "violation",
+          impact: "moderate",
+          nodes: orderIssues.map(({ current, previous }) => ({
+            description: `${previous.element.tagName} \u2192 ${current.element.tagName}: "${current.text}"`,
+            impact: "moderate",
+            targets: current.element
+          }))
+        });
+      } else if (allHeadings.length > 1) {
+        results.push({
+          id: "blokkli:heading-structure:no-skipped-levels",
+          title: $t(
+            "analyzeHeadingNoSkippedLevels",
+            "No skipped heading levels"
+          ),
+          category: "seo",
+          description: $t(
+            "analyzeHeadingNoSkippedLevelsDescription",
+            "The heading hierarchy does not skip any levels."
+          ),
+          status: "pass",
+          nodes: allHeadings.map((h) => ({
+            description: `${h.element.tagName}: ${h.text}`,
+            targets: h.element
+          }))
+        });
+      }
+      const h2Elements = allHeadings.filter((h) => h.level === 2);
+      if (h2Elements.length === 0) {
+        results.push({
+          id: "blokkli:heading-structure:no-h2",
+          title: $t("analyzeHeadingNoH2", "Missing H2 headings"),
+          category: "seo",
+          description: $t(
+            "analyzeHeadingNoH2Description",
+            "The page contains no H2 headings. A clear heading structure is important for SEO and accessibility."
+          ),
+          status: "violation",
+          impact: "moderate",
+          nodes: {
+            description: $t("analyzeHeadingNoH2Found", "No H2 headings found"),
+            targets: context.providerRootElement
+          }
+        });
+      } else {
+        results.push({
+          id: "blokkli:heading-structure:has-h2",
+          title: $t("analyzeHeadingHasH2", "H2 headings present"),
+          category: "seo",
+          description: $t(
+            "analyzeHeadingHasH2Description",
+            "The page contains H2 headings for a clear content structure."
+          ),
+          status: "pass",
+          nodes: h2Elements.map((h) => ({
+            description: h.text,
+            targets: h.element
+          }))
+        });
+      }
+      return results;
+    }
+  };
+});

package/dist/runtime/editor/features/analyze/analyzers/helpers/Context.d.ts

@@ -0,0 +1,38 @@
+import type { FieldListItemTyped } from '#blokkli-build/generated-types';
+import type { StateProvider } from '#blokkli/editor/providers/state';
+import type { ReadabilityProvider } from '#blokkli/editor/providers/readability';
+import type { TextProvider } from '#blokkli/editor/providers/texts';
+import type { MutatedField } from '#blokkli/editor/types/state';
+import type { AnalyzeCategory, AnalyzeNode, AnalyzeResult, AnalyzeStatus } from '../types.js';
+import { type TextElement } from './collectTextElements.js';
+export declare class AnalyzerContext {
+    readonly langcode: string;
+    readonly interfaceLangcode: string;
+    readonly providerRootElement: HTMLElement;
+    private state;
+    readonly $t: TextProvider;
+    readonly signal: AbortSignal | undefined;
+    readonly mutatedFields: Readonly<MutatedField[]>;
+    /**
+     * The readability provider.
+     */
+    readonly readability: ReadabilityProvider;
+    /**
+     * The collected text elements.
+     */
+    private textElements;
+    constructor(langcode: string, interfaceLangcode: string, providerRootElement: HTMLElement, state: StateProvider, $t: TextProvider, signal: AbortSignal | undefined, readability: ReadabilityProvider);
+    /**
+     * Get the field list item for a block UUID.
+     */
+    getFieldListItem(uuid: string): FieldListItemTyped | undefined;
+    /**
+     * Returns an array of all text elements inside the provider root element.
+     *
+     * A 'text element' is defined as the lowest block element that contains text.
+     * For example, a structure like `<p><span>Foobar</span> <strong>Test</strong></p>`
+     * would return as a single text element containing "Foobar Test".
+     */
+    getTextElements(): Readonly<TextElement[]>;
+    defineResult(id: string, title: string, category: AnalyzeCategory, description: string, status: AnalyzeStatus, nodes?: AnalyzeNode | AnalyzeNode[]): AnalyzeResult;
+}

package/dist/runtime/editor/features/analyze/analyzers/helpers/Context.js

@@ -0,0 +1,51 @@
+import { collectTextElements } from "./collectTextElements.js";
+export class AnalyzerContext {
+  constructor(langcode, interfaceLangcode, providerRootElement, state, $t, signal, readability) {
+    this.langcode = langcode;
+    this.interfaceLangcode = interfaceLangcode;
+    this.providerRootElement = providerRootElement;
+    this.state = state;
+    this.$t = $t;
+    this.signal = signal;
+    this.readability = readability;
+    this.mutatedFields = JSON.parse(JSON.stringify(state.mutatedFields.value));
+  }
+  mutatedFields;
+  /**
+   * The readability provider.
+   */
+  readability;
+  /**
+   * The collected text elements.
+   */
+  textElements = null;
+  /**
+   * Get the field list item for a block UUID.
+   */
+  getFieldListItem(uuid) {
+    return this.state.getFieldListItem(uuid);
+  }
+  /**
+   * Returns an array of all text elements inside the provider root element.
+   *
+   * A 'text element' is defined as the lowest block element that contains text.
+   * For example, a structure like `<p><span>Foobar</span> <strong>Test</strong></p>`
+   * would return as a single text element containing "Foobar Test".
+   */
+  getTextElements() {
+    if (!this.textElements) {
+      this.textElements = collectTextElements(this.providerRootElement);
+    }
+    return this.textElements;
+  }
+  defineResult(id, title, category, description, status, nodes = []) {
+    return {
+      id,
+      title,
+      category,
+      description,
+      status,
+      nodes
+    };
+  }
+}

package/dist/runtime/editor/features/analyze/analyzers/helpers/collectTextElements.d.ts

@@ -0,0 +1,5 @@
+export interface TextElement {
+    text: string;
+    element: HTMLElement;
+}
+export declare function collectTextElements(rootElement: HTMLElement): TextElement[];

package/dist/runtime/editor/features/analyze/analyzers/helpers/collectTextElements.js

@@ -0,0 +1,98 @@
+const blockElements = /* @__PURE__ */ new Set([
+  "ADDRESS",
+  "ARTICLE",
+  "ASIDE",
+  "BLOCKQUOTE",
+  "CANVAS",
+  "DD",
+  "DIV",
+  "DL",
+  "DT",
+  "FIELDSET",
+  "FIGCAPTION",
+  "FIGURE",
+  "FOOTER",
+  "FORM",
+  "H1",
+  "H2",
+  "H3",
+  "H4",
+  "H5",
+  "H6",
+  "HEADER",
+  "HR",
+  "LI",
+  "MAIN",
+  "NAV",
+  "OL",
+  "P",
+  "PRE",
+  "SECTION",
+  "TABLE",
+  "TD",
+  "TH",
+  "UL",
+  "DETAILS",
+  "SUMMARY",
+  "DIALOG"
+]);
+const isBlockElement = (element) => {
+  if (blockElements.has(element.tagName.toUpperCase())) {
+    return true;
+  }
+  if (element.tagName.toUpperCase() === "A" && element instanceof HTMLElement) {
+    const display = window.getComputedStyle(element).display;
+    return display === "block" || display === "flex" || display === "grid";
+  }
+  return false;
+};
+const containsBlockElements = (element) => {
+  for (const child of element.children) {
+    if (isBlockElement(child)) {
+      return true;
+    }
+    if (child instanceof HTMLElement && containsBlockElements(child)) {
+      return true;
+    }
+  }
+  return false;
+};
+const getCleanText = (element) => {
+  return element.textContent?.trim() || "";
+};
+const traverse = (element, results) => {
+  if (element.tagName === "SCRIPT" || element.tagName === "STYLE") {
+    return;
+  }
+  if (element.classList.contains("bk-skip-analyze")) {
+    return;
+  }
+  if (isBlockElement(element)) {
+    if (!containsBlockElements(element)) {
+      const text = getCleanText(element);
+      if (text) {
+        results.push({
+          text,
+          element
+        });
+      }
+    } else {
+      for (const child of element.children) {
+        if (child instanceof HTMLElement) {
+          traverse(child, results);
+        }
+      }
+    }
+  } else {
+    for (const child of element.children) {
+      if (child instanceof HTMLElement) {
+        traverse(child, results);
+      }
+    }
+  }
+};
+export function collectTextElements(rootElement) {
+  const results = [];
+  traverse(rootElement, results);
+  return results;
+}

package/dist/runtime/editor/features/analyze/analyzers/helpers/normalizeArray.d.ts

@@ -0,0 +1,3 @@
+type NormalizeToArray<T> = undefined | null | T | T[] | Promise<T | T[] | undefined | null>;
+export declare function normalizeToArray<T>(input: NormalizeToArray<T>): Promise<T[]>;
+export {};

package/dist/runtime/editor/features/analyze/analyzers/helpers/normalizeArray.js

@@ -0,0 +1,13 @@
+export async function normalizeToArray(input) {
+  if (input === null || input === void 0) {
+    return [];
+  }
+  if (input instanceof Promise) {
+    const resolved = await input;
+    if (resolved === null || resolved === void 0) {
+      return [];
+    }
+    return Array.isArray(resolved) ? resolved : [resolved];
+  }
+  return Array.isArray(input) ? input : [input];
+}

package/dist/runtime/editor/features/analyze/analyzers/index.d.ts

@@ -0,0 +1,6 @@
+import { defineAnalyzer } from './defineAnalyzer.js';
+import readabilityAnalyzer from './readability.js';
+import headingStructureAnalyzer from './headingStructure.js';
+import altTextAnalyzer from './altText.js';
+import axeAnalyzer from './axe.js';
+export { defineAnalyzer, readabilityAnalyzer, headingStructureAnalyzer, altTextAnalyzer, axeAnalyzer, };

package/dist/runtime/editor/features/analyze/analyzers/index.js

@@ -0,0 +1,12 @@
+import { defineAnalyzer } from "./defineAnalyzer.js";
+import readabilityAnalyzer from "./readability.js";
+import headingStructureAnalyzer from "./headingStructure.js";
+import altTextAnalyzer from "./altText.js";
+import axeAnalyzer from "./axe.js";
+export {
+  defineAnalyzer,
+  readabilityAnalyzer,
+  headingStructureAnalyzer,
+  altTextAnalyzer,
+  axeAnalyzer
+};

package/dist/runtime/editor/features/analyze/analyzers/readability.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (options?: object | undefined) => import("./types.js").Analyzer;
+export default _default;

package/dist/runtime/editor/features/analyze/analyzers/readability.js

@@ -0,0 +1,135 @@
+import { defineAnalyzer } from "./defineAnalyzer.js";
+import { collectTextElements } from "./helpers/collectTextElements.js";
+function summarizeImpact(nodes) {
+  const order = ["minor", "moderate", "serious", "critical"];
+  let maxIdx = -1;
+  for (const n of nodes) {
+    if (!n.impact) continue;
+    const i = order.indexOf(n.impact);
+    if (i > maxIdx) maxIdx = i;
+  }
+  return maxIdx >= 0 ? order[maxIdx] : void 0;
+}
+function format(n, d = 1) {
+  return typeof n === "number" && Number.isFinite(n) ? n.toFixed(d) : "\u2014";
+}
+function buildDescription(score, scoreLabel, lang, band, $t) {
+  const parts = [];
+  if (band === "hard") {
+    parts.push(
+      $t("analyzerReadabiliyHardToRead", `Hard to read (@lang).`).replace(
+        "@lang",
+        lang.toUpperCase()
+      )
+    );
+  } else {
+    parts.push(
+      $t(
+        "analyzerReadabiliyCouldBeSimpler",
+        `Could be simpler (@lang).`
+      ).replace("@lang", lang.toUpperCase())
+    );
+  }
+  parts.push(`${scoreLabel} ${format(score)}`);
+  parts.push(
+    $t(
+      "analyzerReadabiliyShorterSentences",
+      `Consider shorter sentences and simpler wording.`
+    )
+  );
+  return parts.join(" \xB7 ");
+}
+async function analyzeViaProvider(readabilityProvider, langcode, $t) {
+  const result = await readabilityProvider.analyzeAllFields();
+  const analyzer = readabilityProvider.analyzer.value;
+  const hardNodes = [];
+  const okNodes = [];
+  for (const [key, fieldResult] of Object.entries(result)) {
+    const separatorIndex = key.indexOf("/");
+    const uuid = key.slice(0, separatorIndex);
+    const fieldName = key.slice(separatorIndex + 1);
+    const fieldElement = readabilityProvider.getFieldElement(uuid, fieldName);
+    const fieldTextElements = fieldElement ? collectTextElements(fieldElement) : [];
+    for (let i = 0; i < fieldResult.chunks.length; i++) {
+      const chunk = fieldResult.chunks[i];
+      if (chunk.band === "easy" || chunk.band === null || chunk.score === null)
+        continue;
+      const targets = [];
+      const textElement = fieldTextElements[i];
+      if (textElement) {
+        targets.push(textElement.element);
+      }
+      const node = {
+        description: buildDescription(
+          chunk.score,
+          analyzer.scoreLabel,
+          langcode,
+          chunk.band,
+          $t
+        ),
+        impact: analyzer.impactForScore(chunk.score),
+        score: chunk.score,
+        targets
+      };
+      if (chunk.band === "hard") {
+        hardNodes.push(node);
+      } else {
+        okNodes.push(node);
+      }
+    }
+  }
+  const results = [];
+  results.push({
+    id: "low-readability",
+    title: $t("analyzerReadabiliyTitle", "Text readability issues"),
+    category: "text",
+    description: $t(
+      "analyzerReadabiliyDescription",
+      "Avoid texts that are hard to read."
+    ),
+    link: "https://en.wikipedia.org/wiki/Readability",
+    status: hardNodes.length ? "violation" : "pass",
+    nodes: hardNodes,
+    impact: summarizeImpact(hardNodes)
+  });
+  if (okNodes.length) {
+    results.push({
+      id: "ok-readability",
+      title: $t("analyzerReadabiliyOkTitle", "Text could be simpler"),
+      category: "text",
+      description: $t(
+        "analyzerReadabiliyOkDescription",
+        "Text that could be easier to read."
+      ),
+      link: "https://en.wikipedia.org/wiki/Readability",
+      status: "incomplete",
+      nodes: okNodes,
+      impact: summarizeImpact(okNodes)
+    });
+  }
+  return results;
+}
+export default defineAnalyzer(() => {
+  return {
+    id: "readability",
+    type: "readability",
+    label: (langcode) => {
+      if (langcode === "de") {
+        return "Lesbarkeit";
+      }
+      return "Readability";
+    },
+    description: "Analyzes text readability using language-specific algorithms. Flags hard-to-read text blocks.",
+    continuous: true,
+    async init(context) {
+      await context.readability.ensureInitialized();
+    },
+    run(context) {
+      return analyzeViaProvider(
+        context.readability,
+        context.langcode,
+        context.$t
+      );
+    }
+  };
+});

package/dist/runtime/editor/features/analyze/analyzers/types.d.ts

@@ -0,0 +1,78 @@
+import type { AnalyzerContext } from './helpers/Context.js';
+import type { TextProvider } from '#blokkli/editor/providers/texts';
+export type AnalyzeStatus = 'pass' | 'incomplete' | 'inapplicable' | 'violation';
+export type AnalyzeImpact = 'minor' | 'moderate' | 'serious' | 'critical';
+export type AnalyzeCategory = 'accessibility' | 'seo' | 'text' | 'content';
+export type AnalyzeNodeTarget = string | HTMLElement | {
+    uuid: string;
+};
+export type AnalyzeNodeTargetMapped = {
+    target: AnalyzeNodeTarget;
+    globalIndex: number;
+};
+export type AnalyzeNode = {
+    description?: string;
+    impact?: AnalyzeImpact;
+    /**
+     * Optional numeric score for this node (e.g. readability index).
+     */
+    score?: number;
+    /**
+     * An array of either:
+     * - string: a valid selector
+     * - HTMLElement: the DOM node
+     *  - object: An object containing the UUID of a block
+     */
+    targets: AnalyzeNodeTarget | AnalyzeNodeTarget[];
+};
+export type AnalyzeNodeMapped = Omit<AnalyzeNode, 'targets'> & {
+    targets: AnalyzeNodeTargetMapped[];
+};
+export type AnalyzeResult = {
+    id: string;
+    title: string;
+    category: AnalyzeCategory;
+    description: string;
+    link?: string;
+    status: AnalyzeStatus;
+    nodes: AnalyzeNode | AnalyzeNode[];
+    impact?: AnalyzeImpact;
+    /**
+     * If true, the total summary score will be calculated for each target element.
+     */
+    scoreTargets?: boolean;
+};
+export type AnalyzeResultMapped = Omit<AnalyzeResult, 'nodes'> & {
+    plugin: string;
+    nodes: AnalyzeNodeMapped[];
+};
+export type AnalyzerType = 'generic' | 'readability';
+export type Analyzer = {
+    id: string;
+    /**
+     * The type of analyzer. Defaults to 'generic'.
+     *
+     * - 'readability': Text readability analysis (LIX, Flesch, etc.)
+     * - 'generic': Any other type of analysis (accessibility, SEO, custom checks)
+     */
+    type?: AnalyzerType;
+    label?: string | ((langcode: string, $t: TextProvider) => string);
+    description?: string | ((langcode: string, $t: TextProvider) => string);
+    /**
+     * If true, the raw page (without editor UI) is required for this analyzer.
+     */
+    requireRawPage?: boolean;
+    /**
+     * If true, the analyzer is called automatically. This assumes it runs without
+     * blocking the main thread.
+     */
+    continuous?: boolean;
+    init?: (context: AnalyzerContext) => void | Promise<void>;
+    run: (context: AnalyzerContext) => undefined | null | AnalyzeResult | AnalyzeResult[] | Promise<undefined | null | AnalyzeResult | AnalyzeResult[]>;
+    /**
+     * Optional method to analyze raw text without DOM context.
+     * Enables agent feedback loops (test a rewrite before applying).
+     * Analyzers that only work with DOM (e.g. axe-core) don't implement this.
+     */
+    analyzeText?: (text: string, langcode: string) => AnalyzeNode[] | Promise<AnalyzeNode[]>;
+};