@widgetic/design-system 0.5.15 → 0.5.17

package/dist/rtl/audit/physicalPlacement.js

@@ -0,0 +1,444 @@
+/**
+ * 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]:...`).
+ */
+/** The note that lets a physical placement through; it goes on the line itself or on the line above, with the reason. */
+export const ALLOWED_PLACEMENT_NOTE = 'rtl-ok';
+const LOGICAL_MARGIN_AND_PADDING = { ml: 'ms', mr: 'me', pl: 'ps', pr: 'pe' };
+const LOGICAL_CORNER = { l: 's', r: 'e', tl: 'ss', tr: 'se', bl: 'es', br: 'ee' };
+const CLASS_RULES = [
+    {
+        pattern: /^(?:scroll-)?(?:ml|mr|pl|pr)-/,
+        instead: (utility) => utility.replace(/^(scroll-)?(ml|mr|pl|pr)-/, (_whole, scroll, side) => `${scroll ?? ''}${LOGICAL_MARGIN_AND_PADDING[side]}-`)
+    },
+    { pattern: /^(?:left|right)-/, instead: (utility) => utility.replace(/^left-/, 'start-').replace(/^right-/, 'end-') },
+    { pattern: /^text-(?:left|right)$/, instead: (utility) => (utility === 'text-left' ? 'text-start' : 'text-end') },
+    {
+        pattern: /^rounded-(?:tl|tr|bl|br|l|r)(?:-|$)/,
+        instead: (utility) => utility.replace(/^rounded-(tl|tr|bl|br|l|r)/, (_whole, side) => `rounded-${LOGICAL_CORNER[side]}`)
+    },
+    { pattern: /^border-(?:l|r)(?:-|$)/, instead: (utility) => utility.replace(/^border-l/, 'border-s').replace(/^border-r/, 'border-e') },
+    { pattern: /^(?:float|clear)-(?:left|right)$/, instead: (utility) => utility.replace('-left', '-start').replace('-right', '-end') }
+];
+/** Moving by a distance to one side only means something in a left-to-right screen. */
+const SHIFT_PATTERN = /^translate-x-/;
+/** Centring is the same in both directions: the pair `left-1/2` and `-translate-x-1/2`, or the same with `50%`. */
+const CENTRING_PATTERN = /^(?:(?:left|right)-(?:1\/2|\[50%\])|translate-x-(?:1\/2|\[-?50%\])|slide-(?:in-from|out-to)-(?:left|right)-1\/2)$/;
+/** An animation that comes from a side is physical; it belongs under the side a pop-up opens on. */
+const SIDE_ANIMATION_PATTERN = /^slide-(?:in-from|out-to)-(?:left|right)(?:-|$)/;
+/** The variant that follows the side a pop-up opens on: what is written under it is meant to be physical. */
+const POPUP_SIDE_VARIANT_PATTERN = /^data-\[side=(?:left|right)\]$/;
+/**
+ * The words a stylesheet or a style attribute uses for a side, and what to write instead. A property is the whole word:
+ * `margin-left` is one, `grid-margin-left` (the name of a class) and `--card-padding-right` (a custom property) are not.
+ */
+const NOT_PART_OF_A_LONGER_NAME = '(?<![\\w$-])';
+const STYLE_RULES = [
+    { pattern: new RegExp(`${NOT_PART_OF_A_LONGER_NAME}(?:margin|padding)-(?:left|right)\\b`, 'g'), instead: (text) => text.replace('-left', '-inline-start').replace('-right', '-inline-end') },
+    { pattern: new RegExp(`${NOT_PART_OF_A_LONGER_NAME}border-(?:left|right)(?:-(?:width|color|style))?\\b`, 'g'), instead: (text) => text.replace('-left', '-inline-start').replace('-right', '-inline-end') },
+    {
+        pattern: new RegExp(`${NOT_PART_OF_A_LONGER_NAME}border-(?:top|bottom)-(?:left|right)-radius\\b`, 'g'),
+        instead: (text) => text.replace(/-(top|bottom)-(left|right)-/, (_whole, block, side) => `-${block === 'top' ? 'start' : 'end'}-${side === 'left' ? 'start' : 'end'}-`)
+    },
+    { pattern: new RegExp(`${NOT_PART_OF_A_LONGER_NAME}(?:margin|padding)(?:Left|Right)\\b`, 'g'), instead: (text) => text.replace('Left', 'InlineStart').replace('Right', 'InlineEnd') },
+    { pattern: new RegExp(`${NOT_PART_OF_A_LONGER_NAME}text-align\\s*:\\s*(?:left|right)\\b`, 'g'), instead: (text) => text.replace(/(left|right)$/, (side) => (side === 'left' ? 'start' : 'end')) },
+    { pattern: new RegExp(`${NOT_PART_OF_A_LONGER_NAME}(?:float|clear)\\s*:\\s*(?:left|right)\\b`, 'g'), instead: (text) => text.replace(/(left|right)$/, (side) => (side === 'left' ? 'inline-start' : 'inline-end')) }
+];
+/**
+ * The place a box is put at from a physical edge. These are found only where the words are a style: in a stylesheet, in a
+ * `<style>` block, in a style attribute (`style="left: 8px"`, `style:right={x}`, also when it runs over several lines), in an
+ * assignment to `style.left` and in a string of a script that is a list of declarations with a length
+ * (`` `top: ${top}px; right: ${right}px;` ``).
+ */
+const OFFSET_DECLARATION = new RegExp(`${NOT_PART_OF_A_LONGER_NAME}(left|right)\\s*:\\s*`, 'g');
+const OFFSET_DIRECTIVE = new RegExp(`${NOT_PART_OF_A_LONGER_NAME}style:(left|right)\\b`, 'g');
+const OFFSET_ASSIGNMENT = new RegExp(`${NOT_PART_OF_A_LONGER_NAME}style\\.(left|right)\\s*=(?!=)`, 'g');
+const STYLE_ATTRIBUTE = /(?<![\w$-])style=["'{`]/;
+/**
+ * The side a pop-up opens on, named by a place on the screen (`side="left"`, `side={'right'}`). It does not turn around by
+ * itself: a pop-up that opens beside a control at the end of the line must open on the left in a right to left screen.
+ */
+const POPUP_SIDE_ATTRIBUTE = new RegExp(`${NOT_PART_OF_A_LONGER_NAME}side=(?:"(left|right)"|'(left|right)'|\\{\\s*["'\`](left|right)["'\`]\\s*\\})`, 'g');
+/**
+ * A shorthand that names the sides by their place (`padding: 0 8px 0 4px` is top, right, bottom, left) puts one length at the
+ * left and another at the right, and the left stays the left on a right to left screen. It is found where the words are a
+ * style, like the offsets above.
+ */
+const POSITIONAL_SHORTHAND = new RegExp(`${NOT_PART_OF_A_LONGER_NAME}(margin|padding|inset|scroll-margin|scroll-padding|border-width|border-color|border-style|border-radius)\\s*:\\s*`, 'g');
+/** What a `left` or a `right` may be set to without moving anything to one side: the browser decides, or it is the middle. */
+const SAME_IN_BOTH_DIRECTIONS = /^(?:auto|50%|inherit|initial|unset|revert)\s*(?:!important)?$/;
+const ZERO_OFFSET = /^0(?:px|rem|em|%)?\s*(?:!important)?$/;
+/** The part of the advice that is the same for every offset: a number measured from the left edge may be meant. */
+const OFFSET_ADVICE = 'a distance from the start of the line is written `inset-inline-start` / `inset-inline-end`; one that was measured from the left edge of the screen, or that an element does not follow, stays with the note `rtl-ok` and the reason';
+/**
+ * A comment of the kinds that may be written anywhere in the source.
+ *
+ * - A block comment starts where a comment can start: at the beginning of a line, after a space or after a mark of the code
+ *   (`;`, `,`, a bracket, `:`, `>`). A `/` and `*` that follow a letter or a star are part of a word, a path or a mime type
+ *   (`accept="image/*"`, the glob `src/**` and `/*.ts`) and are not the start of anything.
+ * - A line comment (two slashes) runs to the end of the line, and starts after a space or a mark of the code, so that the
+ *   two slashes of an address (`https://`, `src="//cdn"`) are left alone.
+ */
+const BLOCK_COMMENT = /(?<=^|[\s;,{}()[\]:>])\/\*[\s\S]*?\*\//g;
+const LINE_COMMENT = /(^|[\s;,{}()])\/\/[^\n]*/gm;
+/** A comment that only a template can hold: in a script `<!--` is text (`'<!--'`, `/<!--/`) and must not hide what follows it. */
+const TEMPLATE_COMMENT = /<!--[\s\S]*?-->/g;
+/** A block of a Svelte or HTML file that is not template: its tags, and what it holds up to the closing tag. */
+const SCRIPT_OR_STYLE_BLOCK = /<(script|style)\b[^>]*>[\s\S]*?<\/\1\s*>/gi;
+const blankText = (text) => text.replace(/[^\n]/g, ' ');
+const blankBlockComments = (text) => text.replace(BLOCK_COMMENT, blankText);
+const blankLineComments = (text) => text.replace(LINE_COMMENT, (whole, before) => `${before}${blankText(whole.slice(before.length))}`);
+/**
+ * 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 function blankComments(source, language = 'markup') {
+    if (language === 'stylesheet')
+        return blankBlockComments(source);
+    if (language === 'script')
+        return blankLineComments(blankBlockComments(source));
+    const blankTemplate = (text) => blankLineComments(blankBlockComments(text.replace(TEMPLATE_COMMENT, blankText)));
+    let result = '';
+    let position = 0;
+    for (const block of source.matchAll(SCRIPT_OR_STYLE_BLOCK)) {
+        const start = block.index ?? 0;
+        const openingTag = block[0].match(/^<(?:script|style)\b[^>]*>/i)?.[0] ?? '';
+        const closingTag = block[0].match(/<\/(?:script|style)\s*>$/i)?.[0] ?? '';
+        const inside = block[0].slice(openingTag.length, block[0].length - closingTag.length);
+        const blankedInside = block[1].toLowerCase() === 'style' ? blankBlockComments(inside) : blankLineComments(blankBlockComments(inside));
+        result += blankTemplate(source.slice(position, start)) + openingTag + blankedInside + closingTag;
+        position = start + block[0].length;
+    }
+    return result + blankTemplate(source.slice(position));
+}
+/**
+ * Splits a word of the source into variants and utility. A colon splits only outside `[...]` and `(...)`, and a word
+ * ends where a class cannot continue (`=`, `{`, `}`, `<`, `>`, `,`, `;`) so that `class:pr-10={open}` reads as `pr-10`.
+ */
+function readClassWord(rawWord) {
+    const word = rawWord.startsWith('class:') ? rawWord.slice('class:'.length) : rawWord;
+    const pieces = [];
+    let depth = 0;
+    let current = '';
+    for (const character of word) {
+        if (character === '[' || character === '(')
+            depth += 1;
+        else if (character === ']' || character === ')')
+            depth = Math.max(0, depth - 1);
+        if (depth === 0 && character === ':') {
+            pieces.push(current);
+            current = '';
+            continue;
+        }
+        if (depth === 0 && '={}<>,;'.includes(character))
+            break;
+        current += character;
+    }
+    pieces.push(current);
+    const lastPiece = pieces[pieces.length - 1];
+    const leading = lastPiece.match(/^[!-]*/)?.[0] ?? '';
+    const afterLeading = lastPiece.slice(leading.length);
+    const trailing = afterLeading.match(/!+$/)?.[0] ?? '';
+    const utility = afterLeading.slice(0, afterLeading.length - trailing.length);
+    if (!utility)
+        return null;
+    return { variants: pieces.slice(0, -1), leading, trailing, utility, written: pieces.join(':') };
+}
+/** Whether a line carries the note that lets a physical placement through, on itself or on the line above. */
+function isAllowedByNote(rawLines, lineIndex) {
+    return rawLines[lineIndex].includes(ALLOWED_PLACEMENT_NOTE) || (lineIndex > 0 && rawLines[lineIndex - 1].includes(ALLOWED_PLACEMENT_NOTE));
+}
+/** Every physical placement in `source`, in the order the source has them; each with its line and what to write instead. */
+export function findPhysicalPlacement(source, { language = 'markup' } = {}) {
+    const rawLines = source.split('\n');
+    const codeLines = blankComments(source, language).split('\n');
+    const found = [];
+    const lineIsInStylesheet = linesInStylesheet(codeLines, language);
+    const lineIsInStyleAttribute = linesInStyleAttribute(codeLines.join('\n'));
+    const offsets = [];
+    codeLines.forEach((codeLine, lineIndex) => {
+        if (isAllowedByNote(rawLines, lineIndex))
+            return;
+        const line = lineIndex + 1;
+        const classWords = codeLine
+            .split(/[\s"'`]+/)
+            .map(readClassWord)
+            .filter((word) => word !== null);
+        // A shift to one side is let through when the same line has its mirror, written with the `rtl:` variant.
+        const lineHasMirroredClass = classWords.some((word) => word.variants.includes('rtl'));
+        for (const { variants, leading, trailing, utility, written } of classWords) {
+            if (variants.includes('rtl') || variants.includes('ltr'))
+                continue;
+            if (variants.some((variant) => POPUP_SIDE_VARIANT_PATTERN.test(variant)))
+                continue;
+            if (CENTRING_PATTERN.test(utility))
+                continue;
+            if (SHIFT_PATTERN.test(utility)) {
+                if (!lineHasMirroredClass)
+                    found.push({ line, text: written, kind: 'class', suggestion: `\`${written}\` moves to one physical side: pair it with an \`rtl:\` class that moves the other way` });
+                continue;
+            }
+            if (SIDE_ANIMATION_PATTERN.test(utility)) {
+                found.push({ line, text: written, kind: 'class', suggestion: `\`${written}\` comes from one physical side: write it under \`data-[side=...]:\` so that it follows the side the pop-up opens on` });
+                continue;
+            }
+            const rule = CLASS_RULES.find((candidate) => candidate.pattern.test(utility));
+            if (rule) {
+                const replacement = [...variants, `${leading}${rule.instead(utility)}${trailing}`].join(':');
+                found.push({ line, text: written, kind: 'class', suggestion: `write \`${replacement}\` instead of \`${written}\`` });
+            }
+        }
+        for (const rule of STYLE_RULES) {
+            for (const match of codeLine.matchAll(rule.pattern)) {
+                found.push({ line, text: match[0], kind: 'style', suggestion: `write \`${rule.instead(match[0])}\` instead of \`${match[0]}\`` });
+            }
+        }
+        for (const match of codeLine.matchAll(POPUP_SIDE_ATTRIBUTE)) {
+            const side = match[1] ?? match[2] ?? match[3];
+            found.push({
+                line,
+                text: `side="${side}"`,
+                kind: 'attribute',
+                suggestion: `\`side="${side}"\` opens the pop-up on the ${side} of the screen: write \`side={${side === 'left' ? 'sideAtStart' : 'sideAtEnd'}($textDirection)}\` for the side at the ${side === 'left' ? 'start' : 'end'} of the line, or say why it must stay with the note \`rtl-ok\``
+            });
+        }
+        for (const match of codeLine.matchAll(OFFSET_ASSIGNMENT)) {
+            found.push({ line, text: `style.${match[1]}`, kind: 'style', suggestion: `\`style.${match[1]}\` puts the box at the ${match[1]} edge: ${OFFSET_ADVICE}` });
+        }
+        for (const match of codeLine.matchAll(OFFSET_DIRECTIVE)) {
+            found.push({ line, text: `style:${match[1]}`, kind: 'style', suggestion: `\`style:${match[1]}\` puts the box at the ${match[1]} edge: ${OFFSET_ADVICE}` });
+        }
+        const lineIsStyle = lineIsInStylesheet[lineIndex] || lineIsInStyleAttribute[lineIndex] || STYLE_ATTRIBUTE.test(codeLine);
+        for (const match of codeLine.matchAll(OFFSET_DECLARATION)) {
+            const side = match[1];
+            const value = readDeclarationValue(codeLine.slice((match.index ?? 0) + match[0].length));
+            if (!lineIsStyle && !isDeclarationInStyleString(codeLine, match.index ?? 0, value))
+                continue;
+            if (SAME_IN_BOTH_DIRECTIONS.test(value))
+                continue;
+            offsets.push({ line, side, written: `${side}: ${value}`.trim(), zero: ZERO_OFFSET.test(value) });
+        }
+        for (const match of codeLine.matchAll(POSITIONAL_SHORTHAND)) {
+            const property = match[1];
+            const value = readDeclarationValue(codeLine.slice((match.index ?? 0) + match[0].length));
+            if (!lineIsStyle && !isDeclarationInStyleString(codeLine, match.index ?? 0, value))
+                continue;
+            const advice = adviseOnPositionalShorthand(property, value);
+            if (advice)
+                found.push({ line, text: `${property}: ${value}`.trim(), kind: 'style', suggestion: advice });
+        }
+    });
+    // A box stretched from both edges (`left: 0` and `right: 0` in the same rule or the same attribute) is the same in both directions.
+    for (const offset of offsets) {
+        const hasZeroMirror = offset.zero && offsets.some((other) => other.zero && other.side !== offset.side && Math.abs(other.line - offset.line) <= STRETCH_REACH_IN_LINES);
+        if (hasZeroMirror)
+            continue;
+        found.push({ line: offset.line, text: offset.written, kind: 'style', suggestion: `\`${offset.side}\` puts the box at the ${offset.side} edge: ${OFFSET_ADVICE}` });
+    }
+    return found.sort((first, second) => first.line - second.line);
+}
+/** A length: a number or a `{...}` / `${...}` of a template, followed by a unit that measures a distance. */
+const LENGTH_VALUE = /(?:-?\d*\.?\d+|\$?\{[^}]*\})\s*(?:px|rem|em|%|vw|vh|ch)(?![\w-])/;
+/** What a string holds before a declaration when it is a list of declarations: nothing, or complete ones. */
+const DECLARATIONS_BEFORE = /^(?:\s*[\w-]+\s*:\s*[^;]*;)*\s*$/;
+/**
+ * Whether the `left:` or `right:` at `index` is written inside a string of a script that is a list of declarations (a style
+ * built as text and handed to an element), as opposed to an object (`{ left: 3 }`), a label or a sentence. The string must
+ * hold only complete declarations before it, and the value must be a length.
+ */
+function isDeclarationInStyleString(codeLine, index, value) {
+    if (!LENGTH_VALUE.test(value))
+        return false;
+    let openQuote = null;
+    let openAt = -1;
+    for (let position = 0; position < index; position += 1) {
+        const character = codeLine[position];
+        if (openQuote === null) {
+            if (character === '"' || character === "'" || character === '`') {
+                openQuote = character;
+                openAt = position;
+            }
+        }
+        else if (character === '\\') {
+            position += 1;
+        }
+        else if (character === openQuote) {
+            openQuote = null;
+        }
+    }
+    if (openQuote === null)
+        return false;
+    return DECLARATIONS_BEFORE.test(codeLine.slice(openAt + 1, index));
+}
+/** How many lines apart `left: 0` and `right: 0` may be and still be one rule. */
+const STRETCH_REACH_IN_LINES = 3;
+/**
+ * The value of a declaration, from the text that follows its colon: up to the `;`, the end of the rule (a `}` that closes
+ * nothing opened in the value) or the quote that ends a style attribute. A `{...}` of a template (`{mouseX + 20}px`) is part
+ * of the value.
+ */
+function readDeclarationValue(rest) {
+    let depth = 0;
+    let value = '';
+    for (const character of rest) {
+        if (character === '{')
+            depth += 1;
+        else if (character === '}') {
+            if (depth === 0)
+                break;
+            depth -= 1;
+        }
+        else if (depth === 0 && (character === ';' || character === '"' || character === "'" || character === '`'))
+            break;
+        value += character;
+    }
+    return value.trim();
+}
+/** The words of a shorthand value, split where there is a space outside a `(...)` or a `{...}`; `!important` is not one of them. */
+function splitShorthandValue(value) {
+    const words = [];
+    let depth = 0;
+    let current = '';
+    for (const character of value.replace(/!important\s*$/i, '').trim()) {
+        if (character === '(' || character === '{')
+            depth += 1;
+        else if (character === ')' || character === '}')
+            depth = Math.max(0, depth - 1);
+        if (depth === 0 && /\s/.test(character)) {
+            if (current)
+                words.push(current);
+            current = '';
+            continue;
+        }
+        current += character;
+    }
+    if (current)
+        words.push(current);
+    return words;
+}
+/** The property that sets the sides at the start and the end of the line, for each shorthand that names the four sides. */
+const LOGICAL_INLINE_SHORTHAND = {
+    margin: 'margin-inline',
+    padding: 'padding-inline',
+    inset: 'inset-inline',
+    'scroll-margin': 'scroll-margin-inline',
+    'scroll-padding': 'scroll-padding-inline',
+    'border-width': 'border-inline-width',
+    'border-color': 'border-inline-color',
+    'border-style': 'border-inline-style'
+};
+/** Two lengths are the same when they are written the same, a zero with or without its unit counting as one. */
+function sameLength(first, second) {
+    const plain = (length) => (/^0(?:px|rem|em|%)?$/.test(length) ? '0' : length);
+    return plain(first) === plain(second);
+}
+/**
+ * What to write instead of a shorthand that puts a different length at the left than at the right, or nothing when the two
+ * sides are the same. A box has four sides (`top right bottom left`, with the missing ones copied) and four corners
+ * (`top-left top-right bottom-right bottom-left`); only the pairs that sit across the line from each other matter.
+ */
+function adviseOnPositionalShorthand(property, value) {
+    if (property === 'border-radius') {
+        // A slash separates the horizontal radii from the vertical ones; each half is read as a list of corners.
+        const halves = value.split('/').map((half) => splitShorthandValue(half));
+        const differs = halves.some((corners) => {
+            if (corners.length === 2)
+                return !sameLength(corners[0], corners[1]);
+            if (corners.length === 3)
+                return !sameLength(corners[0], corners[1]) || !sameLength(corners[1], corners[2]);
+            if (corners.length === 4)
+                return !sameLength(corners[0], corners[1]) || !sameLength(corners[3], corners[2]);
+            return false;
+        });
+        return differs
+            ? `\`border-radius: ${value}\` rounds the left corners differently from the right ones: write \`border-start-start-radius\`, \`border-start-end-radius\`, \`border-end-end-radius\` and \`border-end-start-radius\` for the corners at the start and the end of the line`
+            : null;
+    }
+    const sides = splitShorthandValue(value);
+    if (sides.length !== 4 || sameLength(sides[1], sides[3]))
+        return null;
+    const logical = LOGICAL_INLINE_SHORTHAND[property] ?? `${property}-inline`;
+    return `\`${property}: ${value}\` names the sides by their place: the second length is the right and the fourth the left, so on a right to left screen they are on the wrong sides: write \`${logical}: ${sides[3]} ${sides[1]}\` (start, then end) and the top and bottom lengths on their own`;
+}
+/**
+ * For each line, whether it is inside the value of a style attribute that began on the line before it or on this one
+ * (`style="` ... `"`, or `style={` ... `}`, over several lines). The end of the value is the quote that closes it outside
+ * any `{...}` of an expression, so a quote of an expression (`{open ? 'a' : 'b'}`) does not end it.
+ */
+function linesInStyleAttribute(source) {
+    const lineCount = source.split('\n').length;
+    const inside = new Array(lineCount).fill(false);
+    const lineOfIndex = (index) => source.slice(0, index).split('\n').length - 1;
+    for (const opening of source.matchAll(new RegExp(STYLE_ATTRIBUTE.source, 'g'))) {
+        const valueStart = (opening.index ?? 0) + opening[0].length - 1;
+        const opener = source[valueStart];
+        const closer = opener === '{' ? '}' : opener;
+        let depth = 0;
+        let end = -1;
+        for (let position = valueStart + 1; position < source.length; position += 1) {
+            const character = source[position];
+            if (character === '{')
+                depth += 1;
+            else if (character === '}' && depth > 0)
+                depth -= 1;
+            else if (character === closer && depth === 0) {
+                end = position;
+                break;
+            }
+        }
+        if (end === -1)
+            continue;
+        for (let line = lineOfIndex(valueStart); line <= lineOfIndex(end); line += 1)
+            inside[line] = true;
+    }
+    return inside;
+}
+/** For each line, whether it is a line of a stylesheet: in a `.css` file every line is, in a markup file those of a `<style>` block. */
+function linesInStylesheet(codeLines, language) {
+    if (language === 'stylesheet')
+        return codeLines.map(() => true);
+    if (language === 'script')
+        return codeLines.map(() => false);
+    let insideBlock = false;
+    return codeLines.map((codeLine) => {
+        if (/<style\b/.test(codeLine))
+            insideBlock = true;
+        const insideThisLine = insideBlock;
+        if (/<\/style\s*>/.test(codeLine))
+            insideBlock = false;
+        return insideThisLine;
+    });
+}
+/** A placement as one line of a report: where it is, what it is and what to do. */
+export function describePhysicalPlacement(file, placement) {
+    return `${file}:${placement.line} ${placement.text} - ${placement.suggestion}`;
+}

package/dist/shad-editor/index.d.ts

@@ -1 +1 @@
-export { ShadEditor, type TipTapEditor, type TipTapEditorLevel } from '../components/shad-editor';
+export { ShadEditor, SHAD_EDITOR_MESSAGES, checkShadEditorMessages, type ShadEditorMessageKey, type TipTapEditor, type TipTapEditorLevel } from '../components/shad-editor';

package/dist/shad-editor/index.js

@@ -1 +1 @@
-export { ShadEditor } from '../components/shad-editor';
+export { ShadEditor, SHAD_EDITOR_MESSAGES, checkShadEditorMessages } from '../components/shad-editor';

package/dist/styles/global.css

@@ -291,7 +291,7 @@ go 3 levels up in development mode, 2 levels up in production mode*/
     width: 100%;
     position: absolute;
     top: 0;
-    left: 0;
+    inset-inline-start: 0;
     pointer-events: none;
   }
 
@@ -634,14 +634,14 @@ go 3 levels up in development mode, 2 levels up in production mode*/
   .modal-close {
     @apply fixed z-50;
     top: 16px;
-    right: 16px;
+    inset-inline-end: 16px;
     width: 40px;
     height: 40px;
   }
 
   /* Modal Button Container */
   .modal-actions {
-    @apply flex justify-end gap-4 absolute bottom-6 right-6;
+    @apply flex justify-end gap-4 absolute bottom-6 end-6;
   }
 
   /* Modal Button Styles */
@@ -790,7 +790,7 @@ go 3 levels up in development mode, 2 levels up in production mode*/
   }
 
   .dropdown-menu-item {
-    @apply !flex !items-center !gap-2 !w-full !text-left !h6 !text-[hsl(var(--grey7))] !whitespace-nowrap;
+    @apply !flex !items-center !gap-2 !w-full !text-start !h6 !text-[hsl(var(--grey7))] !whitespace-nowrap;
     padding: 8px 16px;
   }
 

package/dist/utils/fillMessage.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Puts values into a message: `{max}` becomes the value called `max`. A name that has no value stays as it was
+ * written, so a message with a typo shows the typo rather than "undefined".
+ *
+ * Used by the components whose words a page can replace (see `messages` of RenameDialog and NewItemDialog), so a
+ * translated sentence can put a number or a name wherever its grammar needs it.
+ */
+export declare function fillMessage(template: string, values: Record<string, string | number>): string;

package/dist/utils/fillMessage.js

@@ -0,0 +1,10 @@
+/**
+ * Puts values into a message: `{max}` becomes the value called `max`. A name that has no value stays as it was
+ * written, so a message with a typo shows the typo rather than "undefined".
+ *
+ * Used by the components whose words a page can replace (see `messages` of RenameDialog and NewItemDialog), so a
+ * translated sentence can put a number or a name wherever its grammar needs it.
+ */
+export function fillMessage(template, values) {
+    return template.replace(/\{(\w+)\}/g, (placeholder, name) => Object.prototype.hasOwnProperty.call(values, name) ? String(values[name]) : placeholder);
+}

package/dist/utils/itemName.d.ts

@@ -0,0 +1,17 @@
+/**
+ * What a name given to a new item (a folder, a project...) may be made of.
+ *
+ * Letters, numbers and combining marks of ANY script, and white space. A German "ü", a Japanese or Arabic name, a
+ * Cyrillic "Фото 2024" are fine; punctuation and symbols are not. Combining marks are part of the rule because many
+ * scripts write one letter with a base character and a mark ("é" can be "e" followed by a combining accent, and
+ * Hindi and Thai vowels are marks). The two invisible joiners (U+200C zero width non-joiner, U+200D zero width
+ * joiner) are allowed too: Persian, Hindi and several other scripts need them to spell a word correctly.
+ */
+/** What is wrong with a name. `null` means nothing. */
+export type ItemNameProblem = 'required' | 'invalidCharacters';
+/** True when the name has a letter or a number and only allowed characters (white space around it is ignored). */
+export declare function isValidItemName(name: string): boolean;
+/** What is wrong with a name, or `null` when it is fine. */
+export declare function findItemNameProblem(name: string): ItemNameProblem | null;
+/** The text without the characters a name may not have. Used while the visitor types or pastes. */
+export declare function keepAllowedNameCharacters(text: string): string;

package/dist/utils/itemName.js

@@ -0,0 +1,41 @@
+/**
+ * What a name given to a new item (a folder, a project...) may be made of.
+ *
+ * Letters, numbers and combining marks of ANY script, and white space. A German "ü", a Japanese or Arabic name, a
+ * Cyrillic "Фото 2024" are fine; punctuation and symbols are not. Combining marks are part of the rule because many
+ * scripts write one letter with a base character and a mark ("é" can be "e" followed by a combining accent, and
+ * Hindi and Thai vowels are marks). The two invisible joiners (U+200C zero width non-joiner, U+200D zero width
+ * joiner) are allowed too: Persian, Hindi and several other scripts need them to spell a word correctly.
+ */
+const ALLOWED_NAME_PATTERN = /^[\p{L}\p{N}\p{M}\s\u200C\u200D]+$/u;
+const NOT_ALLOWED_CHARACTERS_PATTERN = /[^\p{L}\p{N}\p{M}\s\u200C\u200D]/gu;
+// A name that is only marks, joiners and white space looks empty
+const LETTER_OR_NUMBER_PATTERN = /[\p{L}\p{N}]/u;
+/** True when the name has a letter or a number and only allowed characters (white space around it is ignored). */
+export function isValidItemName(name) {
+    if (!name || typeof name !== 'string')
+        return false;
+    const trimmed = name.trim();
+    if (trimmed.length === 0)
+        return false;
+    return ALLOWED_NAME_PATTERN.test(trimmed) && LETTER_OR_NUMBER_PATTERN.test(trimmed);
+}
+/** What is wrong with a name, or `null` when it is fine. */
+export function findItemNameProblem(name) {
+    if (!name || typeof name !== 'string')
+        return 'required';
+    const trimmed = name.trim();
+    if (trimmed.length === 0)
+        return 'required';
+    // A character the dialog does not accept is the clearer thing to tell the visitor about
+    if (!ALLOWED_NAME_PATTERN.test(trimmed))
+        return 'invalidCharacters';
+    // Only marks and joiners: the name looks empty
+    if (!LETTER_OR_NUMBER_PATTERN.test(trimmed))
+        return 'required';
+    return null;
+}
+/** The text without the characters a name may not have. Used while the visitor types or pastes. */
+export function keepAllowedNameCharacters(text) {
+    return text.replace(NOT_ALLOWED_CHARACTERS_PATTERN, '');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@widgetic/design-system",
-	"version": "0.5.15",
+	"version": "0.5.17",
 	"type": "module",
 	"svelte": "./dist/index.js",
 	"module": "./dist/index.js",
@@ -39,6 +39,7 @@
 		"check:watch": "NODE_OPTIONS='--max-old-space-size=8192' svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
 		"check:strict": "tsc --noEmit && npm run check",
 		"check:deps": "check-runtime-deps",
+		"test": "node --test \"tests/**/*.test.ts\"",
 		"test:deps": "check-runtime-deps-fixtures",
 		"pnpm-link": "zsh -c 'mkdir -p ~/.pnpm-global/bin && export PATH=\"$PATH:$HOME/.pnpm-global/bin\" && pnpm install -g pnpm && pnpm config set global-bin-dir ~/.pnpm-global/bin && echo \"export PATH=\\\"$PATH:$HOME/.pnpm-global/bin\\\"\" >> ~/.zshrc && source ~/.zshrc && pnpm link --global'",
 		"link-packs": "zsh -c 'mkdir -p ~/.pnpm-global/bin && export PATH=\"$PATH:$HOME/.pnpm-global/bin\" && pnpm install -g pnpm && pnpm config set global-bin-dir ~/.pnpm-global/bin && echo \"export PATH=\\\"$PATH:$HOME/.pnpm-global/bin\\\"\" >> ~/.zshrc && source ~/.zshrc && pnpm link --global @widgetic/api-sdk @widgetic/design-system'",
@@ -85,6 +86,19 @@
 			"svelte": "./dist/icons/*.js",
 			"default": "./dist/icons/*.js"
 		},
+		"./i18n": {
+			"types": "./dist/i18n/index.d.ts",
+			"svelte": "./dist/i18n/index.js",
+			"default": "./dist/i18n/index.js"
+		},
+		"./i18n/audit": {
+			"types": "./dist/i18n/audit/index.d.ts",
+			"default": "./dist/i18n/audit/index.js"
+		},
+		"./rtl/audit": {
+			"types": "./dist/rtl/audit/index.d.ts",
+			"default": "./dist/rtl/audit/index.js"
+		},
 		"./stores": {
 			"types": "./dist/stores/index.d.ts",
 			"svelte": "./dist/stores/index.js",
@@ -295,6 +309,9 @@
 			"optional": true
 		}
 	},
+	"overrides": {
+		"shell-quote": "^1.12.0"
+	},
 	"volta": {
 		"node": "22.14.0",
 		"npm": "11.1.0"