@widgetic/design-system 0.5.15 → 0.5.16

package/dist/i18n/translator.js

@@ -0,0 +1,337 @@
+/**
+ * The words of a package, as a function. One translator serves every Widgetic package that has words of its own (the File
+ * Browser, the editor, the canvas, the chat, the widget creator): each brings its English catalog and gets the same rules.
+ *
+ * A message is a template in a flat catalog: `'upload.progress': '{done} of {total} uploaded'`. A page can replace any
+ * of them (the `messages` option); a key it leaves out keeps the English text, so a partly translated catalog never
+ * shows a hole.
+ *
+ * A template is plain text with two kinds of `{...}`:
+ *
+ *   {name}                                         the value called `name`; a number is written the way the locale
+ *                                                  writes numbers (1,234 or 1.234)
+ *   {count, plural, =0 {none} one {# file} other {# files}}
+ *                                                  one branch, chosen by the locale's plural rules (`Intl.PluralRules`),
+ *                                                  so a language with more than two forms (Polish, Arabic) can say so.
+ *                                                  `=0` matches exactly 0; `other` is required; `#` is the number
+ *
+ * `\{`, `\}`, `\#` and `\\` write the character itself. An apostrophe is just an apostrophe: `Delete '{name}'?` works.
+ *
+ * In a language written right to left a text value (a file name, a person's name) is put between Unicode isolate marks
+ * (U+2068 and U+2069), so that the sentence around it cannot turn it around: `حذف '2024-report.pdf'؟` keeps the name
+ * whole, with its quotes and its leading digits where they belong. The marks cannot be seen. A number is never marked.
+ *
+ * Nothing here knows about Svelte or the DOM: the same code runs in a unit test.
+ */
+import { resolveTextDirection } from "./direction.js";
+/** One line a developer can read in the console about a {@link MessageProblem}. */
+export function describeMessageProblem(problem) {
+    switch (problem.kind) {
+        case 'unknown-message':
+            return problem.suggestion
+                ? `There is no message called "${problem.key}". Did you mean "${problem.suggestion}"? It is ignored.`
+                : `There is no message called "${problem.key}". It is ignored.`;
+        case 'not-text':
+            return `The message "${problem.key}" must be a string. The English text is used.`;
+        case 'broken-message':
+            return `The message "${problem.key}" cannot be used (${problem.reason}). The English text is used.`;
+        case 'unknown-value':
+            return `The message "${problem.key}" asks for {${problem.name}}, which this message is never given. It would show as written.`;
+        case 'unknown-locale':
+            return `"${problem.locale}" is not a language tag (like "de" or "pt-BR"). Numbers and dates use English.`;
+    }
+}
+class TemplateSyntaxError extends Error {
+}
+/** The names of the values a template uses, for checking a replacement against the English one. */
+function valueNamesOf(parts, names = new Set()) {
+    for (const part of parts) {
+        if (part.kind === 'value')
+            names.add(part.name);
+        if (part.kind === 'plural') {
+            names.add(part.name);
+            for (const branch of part.branches.values())
+                valueNamesOf(branch, names);
+        }
+    }
+    return names;
+}
+const NAME_START = /[A-Za-z_]/;
+const NAME_CHARACTER = /[A-Za-z0-9_]/;
+/** Starts a stretch of text that reads in the direction of its own first letter, and cannot be turned around by what is around it. */
+const FIRST_STRONG_ISOLATE = '\u2068';
+/** Ends the stretch that {@link FIRST_STRONG_ISOLATE} started. */
+const POP_DIRECTIONAL_ISOLATE = '\u2069';
+/** Reads a template. Throws a {@link TemplateSyntaxError} that says what is wrong, for the console. */
+function parseTemplate(source) {
+    let position = 0;
+    function skipSpaces() {
+        while (position < source.length && /\s/.test(source[position]))
+            position += 1;
+    }
+    function readName() {
+        skipSpaces();
+        const begin = position;
+        if (position >= source.length || !NAME_START.test(source[position])) {
+            throw new TemplateSyntaxError(`a value name was expected at character ${position + 1}`);
+        }
+        while (position < source.length && NAME_CHARACTER.test(source[position]))
+            position += 1;
+        const name = source.slice(begin, position);
+        skipSpaces();
+        return name;
+    }
+    /** Reads parts until the end of the text, or (inside a branch) until the `}` that ends it, which it does not consume. */
+    function readParts(insideBranch) {
+        const parts = [];
+        let text = '';
+        const flushText = () => {
+            if (text !== '')
+                parts.push({ kind: 'text', text });
+            text = '';
+        };
+        while (position < source.length) {
+            const character = source[position];
+            if (character === '\\') {
+                const escaped = source[position + 1];
+                if (escaped === undefined)
+                    throw new TemplateSyntaxError('a backslash at the end');
+                text += escaped;
+                position += 2;
+            }
+            else if (character === '{') {
+                flushText();
+                position += 1;
+                parts.push(readArgument());
+            }
+            else if (character === '}') {
+                if (insideBranch)
+                    break;
+                throw new TemplateSyntaxError(`a } at character ${position + 1} closes nothing (write \\} for the character)`);
+            }
+            else if (character === '#' && insideBranch) {
+                flushText();
+                parts.push({ kind: 'number' });
+                position += 1;
+            }
+            else {
+                text += character;
+                position += 1;
+            }
+        }
+        flushText();
+        return parts;
+    }
+    /** After the `{`: `name}` or `name, plural, selector {…} … }`. */
+    function readArgument() {
+        const name = readName();
+        if (source[position] === '}') {
+            position += 1;
+            return { kind: 'value', name };
+        }
+        if (source[position] !== ',') {
+            throw new TemplateSyntaxError(`a } or a comma was expected after {${name} at character ${position + 1}`);
+        }
+        position += 1;
+        skipSpaces();
+        const typeBegin = position;
+        while (position < source.length && /[a-z]/.test(source[position]))
+            position += 1;
+        const type = source.slice(typeBegin, position);
+        if (type !== 'plural') {
+            throw new TemplateSyntaxError(`{${name}, ${type || '…'}} is not supported: only plural is`);
+        }
+        skipSpaces();
+        if (source[position] !== ',')
+            throw new TemplateSyntaxError(`a comma was expected after {${name}, plural`);
+        position += 1;
+        const branches = new Map();
+        for (;;) {
+            skipSpaces();
+            if (position >= source.length)
+                throw new TemplateSyntaxError(`{${name}, plural, … is never closed`);
+            if (source[position] === '}') {
+                position += 1;
+                break;
+            }
+            const selectorBegin = position;
+            while (position < source.length && !/[\s{}]/.test(source[position]))
+                position += 1;
+            const selector = source.slice(selectorBegin, position);
+            if (selector === '' || !/^(=\d+|zero|one|two|few|many|other)$/.test(selector)) {
+                throw new TemplateSyntaxError(`"${selector}" is not a plural form (use =0, zero, one, two, few, many or other)`);
+            }
+            skipSpaces();
+            if (source[position] !== '{')
+                throw new TemplateSyntaxError(`a { was expected after "${selector}"`);
+            position += 1;
+            if (branches.has(selector))
+                throw new TemplateSyntaxError(`"${selector}" is given twice`);
+            const branch = readParts(true);
+            if (source[position] !== '}')
+                throw new TemplateSyntaxError(`the text of "${selector}" is never closed with }`);
+            position += 1;
+            branches.set(selector, branch);
+        }
+        if (!branches.has('other'))
+            throw new TemplateSyntaxError(`{${name}, plural, …} needs an "other" form`);
+        return { kind: 'plural', name, branches };
+    }
+    return readParts(false);
+}
+/** The catalog key nearest to `key` by spelling, when it is near enough to be a typo. */
+function nearestKey(key, keys) {
+    let best;
+    // A key that is up to three edits away is taken for a typo.
+    let bestDistance = 4;
+    for (const candidate of keys) {
+        if (Math.abs(candidate.length - key.length) >= bestDistance)
+            continue;
+        let previous = Array.from({ length: candidate.length + 1 }, (_, index) => index);
+        for (let row = 1; row <= key.length; row += 1) {
+            const current = [row];
+            for (let column = 1; column <= candidate.length; column += 1) {
+                current[column] = Math.min(previous[column] + 1, current[column - 1] + 1, previous[column - 1] + (key[row - 1] === candidate[column - 1] ? 0 : 1));
+            }
+            previous = current;
+        }
+        const distance = previous[candidate.length];
+        if (distance < bestDistance) {
+            best = candidate;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}
+/**
+ * Makes the function that turns keys into text. It never throws for what the page supplied: an unusable message is
+ * reported through `onProblem` (once) and the English one is used in its place.
+ */
+export function createTranslator(options) {
+    const { catalog, onProblem } = options;
+    const reported = new Set();
+    const report = (problem) => {
+        const signature = JSON.stringify(problem);
+        if (reported.has(signature))
+            return;
+        reported.add(signature);
+        onProblem?.(problem);
+    };
+    // The locale: a tag this browser has number and plural rules for, or English. A tag that Intl accepts but has no data
+    // for would silently use the visitor's own language, which would mix two languages on one screen.
+    let locale = 'en';
+    if (options.locale !== undefined && options.locale !== null && options.locale !== '') {
+        try {
+            const canonical = Intl.getCanonicalLocales(options.locale)[0];
+            if (canonical !== undefined &&
+                Intl.NumberFormat.supportedLocalesOf([canonical]).length > 0 &&
+                Intl.PluralRules.supportedLocalesOf([canonical]).length > 0) {
+                locale = canonical;
+            }
+            else {
+                report({ kind: 'unknown-locale', locale: String(options.locale) });
+            }
+        }
+        catch {
+            report({ kind: 'unknown-locale', locale: String(options.locale) });
+        }
+    }
+    const numberFormat = new Intl.NumberFormat(locale);
+    const pluralRules = new Intl.PluralRules(locale);
+    const isolateValues = options.isolateValues ?? resolveTextDirection(locale) === 'rtl';
+    const catalogKeys = Object.keys(catalog);
+    const englishParts = new Map();
+    const englishPartsOf = (key) => {
+        let parts = englishParts.get(key);
+        if (parts === undefined && Object.prototype.hasOwnProperty.call(catalog, key)) {
+            // The built-in messages are ours; a syntax error in one is a bug the tests catch, so it is allowed to throw.
+            parts = parseTemplate(catalog[key]);
+            englishParts.set(key, parts);
+        }
+        return parts;
+    };
+    // The page's messages, checked once, here: a typo in a key, a value that is not text, a template that does not parse,
+    // or one that asks for a value the English message is never given.
+    const replacements = new Map();
+    const supplied = options.messages;
+    if (supplied !== undefined && supplied !== null && typeof supplied === 'object') {
+        for (const key of Object.keys(supplied)) {
+            if (!Object.prototype.hasOwnProperty.call(catalog, key)) {
+                report({ kind: 'unknown-message', key, suggestion: nearestKey(key, catalogKeys) });
+                continue;
+            }
+            const text = supplied[key];
+            if (typeof text !== 'string') {
+                report({ kind: 'not-text', key });
+                continue;
+            }
+            try {
+                const parts = parseTemplate(text);
+                const allowedNames = valueNamesOf(englishPartsOf(key) ?? []);
+                for (const name of valueNamesOf(parts)) {
+                    if (!allowedNames.has(name))
+                        report({ kind: 'unknown-value', key, name });
+                }
+                replacements.set(key, parts);
+            }
+            catch (error) {
+                if (!(error instanceof TemplateSyntaxError))
+                    throw error;
+                report({ kind: 'broken-message', key, reason: error.message });
+            }
+        }
+    }
+    function write(parts, values, pluralNumber) {
+        let output = '';
+        for (const part of parts) {
+            if (part.kind === 'text') {
+                output += part.text;
+            }
+            else if (part.kind === 'number') {
+                output += pluralNumber === null ? '#' : numberFormat.format(pluralNumber);
+            }
+            else if (part.kind === 'value') {
+                const value = values[part.name];
+                if (value === undefined) {
+                    output += `{${part.name}}`;
+                }
+                else if (typeof value === 'number') {
+                    output += numberFormat.format(value);
+                }
+                else {
+                    const text = String(value);
+                    output += isolateValues && text !== '' ? `${FIRST_STRONG_ISOLATE}${text}${POP_DIRECTIONAL_ISOLATE}` : text;
+                }
+            }
+            else {
+                const raw = values[part.name];
+                const count = typeof raw === 'number' ? raw : Number(raw);
+                const form = Number.isFinite(count) ? (part.branches.get(`=${count}`) ?? part.branches.get(pluralRules.select(count))) : undefined;
+                output += write(form ?? part.branches.get('other'), values, Number.isFinite(count) ? count : null);
+            }
+        }
+        return output;
+    }
+    const t = (key, values = {}) => {
+        const parts = replacements.get(key) ?? englishPartsOf(key);
+        if (parts === undefined) {
+            report({ kind: 'unknown-message', key, suggestion: nearestKey(key, catalogKeys) });
+            return key;
+        }
+        return write(parts, values, null);
+    };
+    return { t, locale };
+}
+/**
+ * The names of the values a message asks for: each `{name}` in it, and the number a plural looks at, sorted. For a test
+ * or a tool that checks the code gives a message everything it needs. Throws when the template does not parse.
+ */
+export function valueNamesOfTemplate(template) {
+    return [...valueNamesOf(parseTemplate(template))].sort();
+}
+/** Checks `messages` against a catalog without making a translator: what a test, or a build step, can call. */
+export function findMessageProblems(catalog, messages) {
+    const problems = [];
+    createTranslator({ catalog, messages, onProblem: (problem) => problems.push(problem) });
+    return problems;
+}

package/dist/rtl/audit/auditPhysicalPlacement.d.ts

@@ -0,0 +1,36 @@
+import { type PhysicalPlacement } from './physicalPlacement.ts';
+export interface PhysicalPlacementOptions {
+    /** The folder to read, with everything under it. */
+    folder: string;
+    /**
+     * Parts of the tree that stay as they are, each with the reason. `path` is a piece of a path relative to `folder`
+     * (for example `components/widget-system/`); every file whose path contains it is left out.
+     */
+    skipped?: Array<{
+        path: string;
+        reason: string;
+    }>;
+    /** The file endings to read; the default is templates, scripts and stylesheets. */
+    extensions?: string[];
+}
+export interface PhysicalPlacementReport {
+    /** How many files were read, so a test can tell that it looked at something. */
+    filesRead: number;
+    /** Every physical placement that is not let through by a note, with the file it is in (relative to the folder). */
+    found: Array<{
+        file: string;
+        placement: PhysicalPlacement;
+    }>;
+    /** The same as one line each, ready to show when an expectation fails. */
+    lines: string[];
+    /** Entries of `skipped` that no file matched: the part they named is gone, so they should go too. */
+    unusedSkips: string[];
+}
+/**
+ * Reads every source file under a folder and reports the physical placement in it. A package runs it in its own tests:
+ *
+ *   const report = auditPhysicalPlacement({ folder: SOURCE_FOLDER, skipped: [{ path: 'lib/legacy/', reason: '...' }] });
+ *   expect(report.lines).toEqual([]);
+ *   expect(report.unusedSkips).toEqual([]);
+ */
+export declare function auditPhysicalPlacement({ folder, skipped, extensions }: PhysicalPlacementOptions): PhysicalPlacementReport;

package/dist/rtl/audit/auditPhysicalPlacement.js

@@ -0,0 +1,58 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { describePhysicalPlacement, findPhysicalPlacement } from "./physicalPlacement.js";
+const DEFAULT_EXTENSIONS = ['.svelte', '.ts', '.js', '.css'];
+const NEVER_READ_FOLDERS = new Set(['node_modules', 'dist', '.svelte-kit', '.git']);
+/** The kind of source a file is, by its ending: a stylesheet reads every line as a style, a script only a style written in a string. */
+function languageOfFile(file) {
+    if (file.endsWith('.css'))
+        return 'stylesheet';
+    if (/\.[cm]?[jt]s$/.test(file))
+        return 'script';
+    return 'markup';
+}
+/** Every file under `folder` that ends with one of `extensions`, as paths relative to `folder` with forward slashes. */
+function listFiles(folder, extensions, relativeFolder = '') {
+    const files = [];
+    for (const entry of fs.readdirSync(path.join(folder, relativeFolder), { withFileTypes: true })) {
+        const relative = relativeFolder ? `${relativeFolder}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            if (!NEVER_READ_FOLDERS.has(entry.name))
+                files.push(...listFiles(folder, extensions, relative));
+            continue;
+        }
+        const isDeclaration = entry.name.endsWith('.d.ts');
+        const isTest = /\.(?:test|spec)\.[cm]?[jt]s$/.test(entry.name);
+        if (!isDeclaration && !isTest && extensions.some((extension) => entry.name.endsWith(extension)))
+            files.push(relative);
+    }
+    return files.sort();
+}
+/**
+ * Reads every source file under a folder and reports the physical placement in it. A package runs it in its own tests:
+ *
+ *   const report = auditPhysicalPlacement({ folder: SOURCE_FOLDER, skipped: [{ path: 'lib/legacy/', reason: '...' }] });
+ *   expect(report.lines).toEqual([]);
+ *   expect(report.unusedSkips).toEqual([]);
+ */
+export function auditPhysicalPlacement({ folder, skipped = [], extensions = DEFAULT_EXTENSIONS }) {
+    const usedSkips = new Set();
+    const found = [];
+    let filesRead = 0;
+    for (const file of listFiles(folder, extensions)) {
+        const skip = skipped.find((candidate) => file.includes(candidate.path));
+        if (skip) {
+            usedSkips.add(skip.path);
+            continue;
+        }
+        filesRead += 1;
+        for (const placement of findPhysicalPlacement(fs.readFileSync(path.join(folder, file), 'utf8'), { language: languageOfFile(file) }))
+            found.push({ file, placement });
+    }
+    return {
+        filesRead,
+        found,
+        lines: found.map(({ file, placement }) => describePhysicalPlacement(file, placement)),
+        unusedSkips: skipped.map((skip) => skip.path).filter((skipPath) => !usedSkips.has(skipPath))
+    };
+}

package/dist/rtl/audit/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Test tooling for the direction of a Widgetic package: an audit a package runs in its own tests, so that a screen
+ * converted to start and end is not put back to left and right by a later change.
+ *
+ *   import { auditPhysicalPlacement } from '@widgetic/design-system/rtl/audit';
+ *
+ *   const report = auditPhysicalPlacement({ folder: SOURCE_FOLDER });
+ *   expect(report.lines).toEqual([]);
+ *
+ * A physical side that is on purpose stays when its line carries the note `rtl-ok` with the reason. It reads source text
+ * only, so it runs in Node (a test, a build step) and a page never loads it. Nothing here changes what a visitor sees.
+ */
+export { auditPhysicalPlacement, type PhysicalPlacementOptions, type PhysicalPlacementReport } from './auditPhysicalPlacement.ts';
+export { ALLOWED_PLACEMENT_NOTE, blankComments, describePhysicalPlacement, findPhysicalPlacement, type FindPlacementOptions, type PhysicalPlacement, type PlacementKind, type SourceLanguage } from './physicalPlacement.ts';

package/dist/rtl/audit/index.js

@@ -0,0 +1,14 @@
+/**
+ * Test tooling for the direction of a Widgetic package: an audit a package runs in its own tests, so that a screen
+ * converted to start and end is not put back to left and right by a later change.
+ *
+ *   import { auditPhysicalPlacement } from '@widgetic/design-system/rtl/audit';
+ *
+ *   const report = auditPhysicalPlacement({ folder: SOURCE_FOLDER });
+ *   expect(report.lines).toEqual([]);
+ *
+ * A physical side that is on purpose stays when its line carries the note `rtl-ok` with the reason. It reads source text
+ * only, so it runs in Node (a test, a build step) and a page never loads it. Nothing here changes what a visitor sees.
+ */
+export { auditPhysicalPlacement } from "./auditPhysicalPlacement.js";
+export { ALLOWED_PLACEMENT_NOTE, blankComments, describePhysicalPlacement, findPhysicalPlacement } from "./physicalPlacement.js";

package/dist/rtl/audit/physicalPlacement.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Finds the places where a screen is put in place with a physical side ("left", "right") instead of a logical one
+ * ("start", "end"), because a physical side does not follow the direction of the text: on a right-to-left screen a
+ * `ml-2` still opens a gap at the left, where the logical `ms-2` opens it at the right.
+ *
+ * It reads source text only (a class in a template, a style in a `<style>` block or a style attribute), so it runs in a
+ * test and a page never loads it. Nothing here changes what a visitor sees.
+ *
+ * A box put in place from the left or the right edge (`left: 8px`, `style:right={x}`, `element.style.left = ...`) is found
+ * in a stylesheet, in a `<style>` block, in a style attribute and in an assignment to `style.left` or `style.right`; the
+ * code around it (`rect.left`, `{ left: 3 }` in a script) is not a style and is left alone. A box that is stretched from
+ * both edges (`left: 0; right: 0`), centred (`left: 50%`) or given back to the browser (`left: auto`) is the same in both
+ * directions and is never reported.
+ *
+ * A shorthand that names the four sides by their place (`padding: 0 8px 0 4px`, `inset: 0 2rem 0 0`, `border-radius: 4px 0 0 4px`)
+ * is found when the length at the left differs from the one at the right (`padding: 4px 8px` and `border-radius: 4px` are the
+ * same on both sides and are left alone).
+ *
+ * Placement that is physical on purpose stays, when the line says why:
+ *
+ *   <!-- rtl-ok: the timeline is a left-to-right island -->
+ *   <div class="left-0 right-0">
+ *
+ * The note `rtl-ok` on the line itself or on the line above lets that line through. A few patterns are never reported
+ * because they cannot be wrong: centring (`left-1/2` with `-translate-x-1/2`), a class that already names its direction
+ * (`rtl:ml-2`, `ltr:ml-2`), and a class that follows the side a pop-up opens on (`data-[side=left]:...`).
+ */
+export type PlacementKind = 'class' | 'style' | 'attribute';
+export interface PhysicalPlacement {
+    /** The line of the source the placement is on, counted from 1. */
+    line: number;
+    /** What was found: a class such as `ml-2`, a style such as `margin-left`, or an attribute such as `side="left"`. */
+    text: string;
+    kind: PlacementKind;
+    /** What to write instead, as a short sentence a developer can act on. */
+    suggestion: string;
+}
+/** The note that lets a physical placement through; it goes on the line itself or on the line above, with the reason. */
+export declare const ALLOWED_PLACEMENT_NOTE = "rtl-ok";
+/**
+ * What kind of source is read. `markup` is a Svelte or HTML file (a `<style>` block is a stylesheet), `stylesheet` is a
+ * `.css` file (every line is a style), `script` is a `.ts` or `.js` file (only a style attribute written in a string, and
+ * an assignment to `style.left`, are styles).
+ */
+export type SourceLanguage = 'markup' | 'stylesheet' | 'script';
+export interface FindPlacementOptions {
+    /** The kind of source; `markup` when left out. */
+    language?: SourceLanguage;
+}
+/**
+ * The source with every comment blanked out (a space for each letter, new lines kept), so the lines still count the same
+ * and the words in a comment are never taken for a class.
+ *
+ * What counts as a comment depends on where it is written, because the same characters are text somewhere else: in a
+ * template an HTML comment, a block comment and a line comment are comments; in a `<script>` block a block comment and a
+ * line comment are, and `<!--` is not (a regular expression or a string may hold it, and it must not hide the lines up to
+ * the next `-->`); in a `<style>` block and in a stylesheet only a block comment is. A script file has block and line
+ * comments.
+ */
+export declare function blankComments(source: string, language?: SourceLanguage): string;
+/** Every physical placement in `source`, in the order the source has them; each with its line and what to write instead. */
+export declare function findPhysicalPlacement(source: string, { language }?: FindPlacementOptions): PhysicalPlacement[];
+/** A placement as one line of a report: where it is, what it is and what to do. */
+export declare function describePhysicalPlacement(file: string, placement: PhysicalPlacement): string;