@wix/origami-lint 0.0.0-stage → 1.34.2

package/dist/rules/css-layout-properties.js

@@ -0,0 +1,398 @@
+import { CONTENT_TARGET, createCssFileReporter, getName, LAYER_ATTRIBUTES, OVERFLOW_TARGET } from "../rules-api/index.js";
+import { defineRule } from "./define-rule.js";
+// ── the tables (propSpecs.ts) ──
+const keywords = (...values) => ({ values, allowed: values.join(', ') });
+const ANY = { allowed: 'any value' };
+const SIZE = { reads: isSize, allowed: 'a size: a number with px, %, fr, spx, vh, vw, em or rem, calc(…), auto, fit-content, max-content, min-content or unset' };
+const NUMBER = { reads: (value) => Number.isFinite(Number(value)), allowed: 'a number' };
+const TRACKS = { reads: isTracks, allowed: 'grid tracks: sizes, minmax(…) and repeat(…)' };
+const TEMPLATE_TRACKS = { reads: (value) => value === 'none' || isTracks(value), allowed: 'grid tracks: sizes, minmax(…) and repeat(…), or none' };
+const GRID_LINE = { reads: (value) => /^-?\d+\s*\/\s*-?\d+$/.test(value), allowed: '`<start> / <end>`, two whole numbers' };
+const ALIGNMENT = keywords('space-between', 'space-around', 'space-evenly', 'start', 'center', 'end');
+/** align-self and justify-self: the converter copies the value as written, and the page schema's ItemsAlignment takes only these (live import). */
+const SELF_ALIGNMENT = keywords('start', 'end', 'center', 'stretch', 'content');
+/** The element's own properties (COMPONENT_LAYOUT_PROPS). */
+const ELEMENT_PROPS = {
+    width: SIZE,
+    height: SIZE,
+    'aspect-ratio': { reads: isAspectRatio, allowed: 'a ratio: `<width> / <height>`, or one number' },
+    'min-width': SIZE,
+    'min-height': SIZE,
+    'max-width': SIZE,
+    'max-height': SIZE,
+    rotate: { reads: (value) => /^-?\d+(?:\.\d+)?deg$/.test(value), allowed: '`<n>deg`' },
+    visibility: keywords('hidden', 'visible'),
+    direction: keywords('ltr', 'rtl'),
+    'container-type': keywords('inline-size'),
+};
+/** How the element sits in its parent (GRID_ITEM_PROPS, STACK_ITEM_PROPS, grid-row / grid-column). */
+const ITEM_PROPS = {
+    'grid-row': GRID_LINE,
+    'grid-column': GRID_LINE,
+    position: ANY,
+    top: SIZE,
+    bottom: SIZE,
+    left: SIZE,
+    right: SIZE,
+    'z-index': { reads: (value) => value === 'auto' || /^calc\(\s*infinity\s*\)$/.test(value), allowed: 'calc(infinity), auto' },
+    'align-self': SELF_ALIGNMENT,
+    'justify-self': SELF_ALIGNMENT,
+    'scroll-snap-align': keywords('start', 'center', 'end', 'none'),
+    order: NUMBER,
+    'flex-basis': SIZE,
+    'flex-grow': NUMBER,
+    'flex-shrink': NUMBER,
+    'margin-top': SIZE,
+    'margin-bottom': SIZE,
+    'margin-left': SIZE,
+    'margin-right': SIZE,
+};
+const grid = (spec, target = CONTENT_TARGET) => ({ spec, grid: true, stack: false, target });
+const stack = (spec, target = CONTENT_TARGET) => ({ spec, grid: false, stack: true, target });
+const both = (spec, target = CONTENT_TARGET) => ({ spec, grid: true, stack: true, target });
+/** The container's properties (GRID_CONTAINER_PROPS, STACK_CONTAINER_PROPS), in a rule or in their `@origami-target` block. */
+const CONTAINER_PROPS = {
+    display: both(keywords('grid', 'flex')),
+    'grid-template-columns': grid(TEMPLATE_TRACKS),
+    'grid-template-rows': grid(TEMPLATE_TRACKS),
+    'grid-auto-flow': grid(keywords('row', 'column', 'dense', 'row dense', 'column dense')),
+    'grid-auto-rows': grid(TRACKS),
+    'grid-auto-columns': grid(TRACKS),
+    'flex-direction': stack(keywords('row', 'row-reverse', 'column', 'column-reverse')),
+    'flex-wrap': stack(keywords('nowrap')),
+    'justify-content': stack(ALIGNMENT),
+    'align-items': stack(ANY),
+    'align-content': stack(ALIGNMENT),
+    'row-gap': both(SIZE),
+    'column-gap': both(SIZE),
+    'padding-top': both(SIZE),
+    'padding-bottom': both(SIZE),
+    'padding-left': both(SIZE),
+    'padding-right': both(SIZE),
+    'scroll-behavior': both(keywords('auto', 'smooth'), OVERFLOW_TARGET),
+    'scrollbar-width': both(keywords('none', 'auto'), OVERFLOW_TARGET),
+    'overflow-x': both(keywords('auto', 'scroll', 'hidden', 'visible', 'clip'), OVERFLOW_TARGET),
+    'overflow-y': both(keywords('auto', 'scroll', 'hidden', 'visible', 'clip'), OVERFLOW_TARGET),
+    'scroll-snap-type': both({ reads: (value) => value === 'none' || /^(?:(?:x|y)\s+)?(?:mandatory|proximity)$|^(?:x|y)$/.test(value), allowed: 'x, y, mandatory, proximity, `<x|y> <mandatory|proximity>`, none' }, OVERFLOW_TARGET),
+    '--content-max-width': both(SIZE),
+    '--content-max-width-align': both(keywords('center', 'left', 'right')),
+    '--spx-stopper-min': both(SIZE, 'root'),
+    '--spx-stopper-max': both(SIZE, 'root'),
+};
+/** The reference its `--spx()` sizes scale by (spxTransformer.ts SPX_PROPS); checked together, :417. */
+const SPX_PROPS = ['--spx-ref-width', '--spx-resolver-type'];
+const SPX_RESOLVER_TYPES = ['scale', 'fixed'];
+/** A property allowed at the top of a rule with `@origami-target` blocks (isRootLayoutProperty): the element's own, item and spx properties, and the root-target container property. */
+const isRootProperty = (prop) => prop in ELEMENT_PROPS || prop in ITEM_PROPS || SPX_PROPS.includes(prop) || CONTAINER_PROPS[prop]?.target === 'root';
+const isLayoutProperty = (prop) => isRootProperty(prop) || prop in CONTAINER_PROPS;
+const ROW = (line) => `(tracker CONV-layoutParser.ts:${line})`;
+export default defineRule({
+    name: 'css-layout-properties',
+    editors: ['studio2'],
+    callbacks: {
+        Program: checkLayoutFile,
+        JSXElement: checkItemParents,
+    },
+});
+/** The page's layout.css: each rule block, then each element at each breakpoint. */
+function checkLayoutFile({ rulesApi, report }) {
+    const root = rulesApi.page.css.files.layout;
+    if (!root)
+        return;
+    const reportAt = createCssFileReporter('layout.css', report);
+    const blocks = readRuleBlocks(root);
+    for (const block of blocks)
+        checkBlock(block, reportAt);
+    const scopes = mergeScopes(blocks);
+    const defaultTypes = new Map();
+    for (const scope of scopes) {
+        const inherited = scope.media === null ? undefined : defaultTypes.get(scope.element);
+        const type = checkScope(scope, inherited, reportAt);
+        if (scope.media === null && type)
+            defaultTypes.set(scope.element, type);
+    }
+}
+/** Each property once per block (:498); a rule without targets holds layout properties (:505); with targets, root properties at the top (:512) and each container property in its target (:524). */
+function checkBlock(block, reportAt) {
+    checkPropertiesOnce(block.declarations, `${block.element}'s rule`, reportAt);
+    for (const [target, declarations] of block.targets)
+        checkPropertiesOnce(declarations, `${block.element}'s \`@origami-target ${target}\` block`, reportAt);
+    if (block.targets.size === 0)
+        return checkLayoutPropertiesOnly(block, reportAt);
+    checkRootPropertiesAtTop(block, reportAt);
+    for (const [target, declarations] of block.targets)
+        checkTargetProperties(block.element, target, declarations, reportAt);
+}
+function checkPropertiesOnce(declarations, where, reportAt) {
+    const seen = new Set();
+    for (const decl of declarations) {
+        if (seen.has(decl.prop))
+            reportAt(decl, `\`${decl.prop}\` is declared twice in ${where}: keep one ${ROW(498)}.`);
+        seen.add(decl.prop);
+    }
+}
+function checkLayoutPropertiesOnly({ element, declarations }, reportAt) {
+    for (const decl of declarations) {
+        if (!isLayoutProperty(decl.prop))
+            reportAt(decl, `${describeNonLayoutProperty(decl.prop, element)} ${ROW(505)}.`);
+    }
+}
+/** A property the layout tables don't have: in capitals, the import doesn't know it (it reads names as written), else it is paint for style.css. */
+function describeNonLayoutProperty(prop, element) {
+    const lowercase = prop.toLowerCase();
+    if (!prop.startsWith('--') && lowercase !== prop && isLayoutProperty(lowercase))
+        return `\`${prop}\` on ${element}: the import reads a property name as written, so write it in lowercase, \`${lowercase}\``;
+    return `\`${prop}\` on ${element} is not a layout property: move it to ${element}'s rule in style.css`;
+}
+function checkRootPropertiesAtTop({ element, declarations }, reportAt) {
+    for (const decl of declarations) {
+        if (isRootProperty(decl.prop))
+            continue;
+        const container = CONTAINER_PROPS[decl.prop];
+        if (container)
+            reportAt(decl, `${element}'s \`${decl.prop}\` goes inside \`@origami-target ${container.target} { … }\`, not at the top of its rule ${ROW(512)}.`);
+        else
+            reportAt(decl, `${describeNonLayoutProperty(decl.prop, element)} ${ROW(512)}.`);
+    }
+}
+/** Each declaration of a target block is a container property of that target; the content block also takes `position: relative` (targetContract.ts). */
+function checkTargetProperties(element, target, declarations, reportAt) {
+    for (const decl of declarations) {
+        if (target === CONTENT_TARGET && decl.prop === 'position' && decl.value.trim() === 'relative')
+            continue;
+        const container = CONTAINER_PROPS[decl.prop];
+        if (container?.target === target)
+            continue;
+        if (container) {
+            const place = container.target === 'root' ? `at the top of ${element}'s rule` : `in \`@origami-target ${container.target}\``;
+            reportAt(decl, `${element}'s \`${decl.prop}\` goes ${place}, not in ${target} ${ROW(524)}.`);
+        }
+        else {
+            const fix = isLayoutProperty(decl.prop) ? `move it to the top of ${element}'s rule` : `move it to ${element}'s rule in style.css`;
+            reportAt(decl, `\`${decl.prop}\` in ${element}'s \`@origami-target ${target}\` block is not a container property: ${fix} ${ROW(524)}.`);
+        }
+    }
+}
+/** An element at one breakpoint: its spx reference (:417), its container type (:218), each value (:430, :437, :440, :447), a display for its targets (:451), grid-row with grid-column (:264). Returns the container type, for the breakpoints that inherit it. */
+function checkScope(scope, inherited, reportAt) {
+    const { element, values } = scope;
+    checkSpxReference(scope, reportAt);
+    const ownType = checkContainerType(scope, reportAt);
+    const type = ownType ?? inherited;
+    for (const [prop, decl] of values) {
+        const value = decl.value.trim();
+        if (value === '') {
+            reportAt(decl, `${element}'s \`${prop}\` has no value: write a value or remove the declaration ${ROW(430)}.`);
+            continue;
+        }
+        if (SPX_PROPS.includes(prop))
+            continue;
+        const container = CONTAINER_PROPS[prop];
+        if (container && type && !container[type]) {
+            const [own, other] = type === 'grid' ? ['grid', 'flex'] : ['flex', 'grid'];
+            reportAt(decl, `${element} is a ${own} container (\`display: ${own}\`), and \`${prop}\` is a ${other} property: remove it, or use \`display: ${other}\` ${ROW(447)}.`);
+            continue;
+        }
+        if (prop === 'flex-wrap' && ownType === 'stack')
+            continue; // :218 reported it; an inherited flex reads it as a value (:437)
+        const spec = ELEMENT_PROPS[prop] ?? ITEM_PROPS[prop] ?? container?.spec;
+        if (spec && !isReadable(spec, value))
+            reportAt(decl, `${element}'s \`${prop}: ${value}\` is not a layout value. Allowed: ${spec.allowed} ${ROW(437)}.`);
+    }
+    if (scope.rulesWithTargets.length && !type) {
+        reportAt(scope.rulesWithTargets[0], `${element} has \`@origami-target\` blocks but no display: add \`display: grid\` or \`display: flex\` in its \`@origami-target ${CONTENT_TARGET}\` block ${ROW(451)}.`);
+    }
+    const gridRow = values.get('grid-row');
+    if (gridRow && !values.has('grid-column')) {
+        reportAt(gridRow, `${element} has \`grid-row\` but no \`grid-column\`: add \`grid-column: <start> / <end>\` (in the same @media, if the grid-row is in one) ${ROW(264)}.`);
+    }
+    return type;
+}
+/** `--spx-ref-width` is a plain number and `--spx-resolver-type` is scale or fixed; a missing one takes its default (spxTransformer.ts). */
+function checkSpxReference({ element, values }, reportAt) {
+    const [refWidth, resolverType] = SPX_PROPS.map((prop) => values.get(prop));
+    const first = refWidth ?? resolverType;
+    if (!first)
+        return;
+    const refWidthValue = refWidth?.value.trim();
+    const resolverTypeValue = resolverType?.value.trim();
+    if (refWidthValue === '' || resolverTypeValue === '')
+        return; // :430 reports the empty one
+    if ((refWidthValue === undefined || Number.isFinite(Number(refWidthValue))) && (resolverTypeValue === undefined || SPX_RESOLVER_TYPES.includes(resolverTypeValue)))
+        return;
+    reportAt(first, `${element}'s spx context is invalid: \`--spx-ref-width\` takes a plain number (1280, no px) and \`--spx-resolver-type\` takes scale or fixed ${ROW(417)}.`);
+}
+/** The container type the scope's own display gives (resolveContainerType): grid, or flex with no flex-wrap other than nowrap (:218). */
+function checkContainerType({ element, values }, reportAt) {
+    const display = values.get('display')?.value.trim();
+    if (display === 'grid')
+        return 'grid';
+    if (display !== 'flex')
+        return undefined;
+    const wrap = values.get('flex-wrap');
+    const wrapValue = wrap?.value.trim();
+    if (wrap && wrapValue !== '' && wrapValue !== 'nowrap') {
+        reportAt(wrap, `${element} has \`flex-wrap: ${wrapValue}\`, which isn't supported: remove it (or write \`nowrap\`), or use \`display: grid\` for items that wrap ${ROW(218)}.`);
+    }
+    return 'stack';
+}
+// ── the elements: an item needs a container parent (:359) ──
+/** Each item of this element (its children, the elements in its attributes) against this element's container type. */
+function checkItemParents(input) {
+    const parent = input.rulesApi.getComponent(input.node);
+    if (!parent)
+        return;
+    if (!parent.classNames.length)
+        return; // fromBundle.ts gives a class-less parent no children's layout
+    for (const child of getItems(input))
+        checkContainerParent(child, parent, input);
+}
+/** The elements this one is the parent of, as the import reads structure.jsx: its child elements and the elements in its attributes, through wrappers; not its layers (they get their item layout from the layer). */
+function getItems({ node, rulesApi }) {
+    const held = rulesApi.getAttributeElements(node).filter(({ attribute }) => !LAYER_ATTRIBUTES.includes(getName(attribute))).map(({ element }) => element);
+    return [...rulesApi.getChildElements(node), ...held].flatMap((element) => rulesApi.getComponent(element) ?? []);
+}
+/** Reports each breakpoint at which the child sets item properties in layout.css while its parent has no `display: grid` or `flex` there or by default; not for a `position: fixed` child (its last position at that breakpoint). */
+function checkContainerParent(child, parent, { report }) {
+    const byMedia = new Map();
+    for (const prop of Object.keys(ITEM_PROPS)) {
+        for (const decl of (child.css.layout[prop] ?? []).filter(isOnElement))
+            byMedia.set(decl.media, [...(byMedia.get(decl.media) ?? []), { prop, decl }]);
+    }
+    for (const [media, declarations] of byMedia) {
+        if (declarations.filter(({ prop }) => prop === 'position').at(-1)?.decl.value.trim() === 'fixed')
+            continue; // the last position wins, as the import merges the scope
+        if (isContainerAt(parent, media))
+            continue;
+        const childName = nameOf(child);
+        const parentName = nameOf(parent);
+        const props = [...new Set(declarations.map(({ prop }) => prop))].join(', ');
+        const line = Math.min(...declarations.map(({ decl }) => decl.line));
+        report({ loc: child.loc, message: `layout.css:${line}: ${childName} sets item properties (${props}), but its parent ${parentName} has no container layout${media ? ` at @media ${media}` : ''}: give ${parentName} \`display: grid\` or \`display: flex\`, or remove ${childName}'s item properties ${ROW(359)}.` });
+    }
+}
+/** The parent's container type at this breakpoint, as the import derives it: its last `display` there (on itself or in its content-wrapper block) when it is grid or flex, else the default's. */
+function isContainerAt(parent, media) {
+    const displays = (parent.css.layout.display ?? []).filter((decl) => decl.selector === '&' || decl.selector === `& @origami-target ${CONTENT_TARGET}`);
+    const isContainer = (at) => ['grid', 'flex'].includes(displays.filter((decl) => decl.media === at).at(-1)?.value.trim() ?? '');
+    return isContainer(media) || (media !== null && isContainer(null));
+}
+/** On the element itself, not in a target block or on an inner part; at any breakpoint. */
+const isOnElement = (decl) => decl.selector === '&';
+/** How the import names the element: its class (the selector's), or its key when it has no class (and so no layout CSS). */
+const nameOf = (component) => component.classNames[0] ?? component.key;
+// ── reading the file ──
+/** A layout rule's selector: one element's class. Any other selector is the selectors subject's. */
+const CLASS_SELECTOR = /^\.(\S+)$/;
+/** The rule blocks of the file in order: at the top level, in each `@media`, and in each `@scope`'s `@media`. The preamble layer is skipped. */
+function readRuleBlocks(root) {
+    const blocks = [];
+    const readRules = (container, media) => {
+        for (const node of container.nodes ?? []) {
+            if (node.type === 'rule') {
+                const element = CLASS_SELECTOR.exec(node.selector.trim())?.[1];
+                if (element)
+                    blocks.push(readRuleBlock(element, media, node));
+            }
+            else if (node.type === 'atrule' && media === null) {
+                if (node.name === 'media')
+                    readRules(node, node.params.trim());
+                else if (node.name === 'scope')
+                    readRules(node, null);
+            }
+        }
+    };
+    readRules(root, null);
+    return blocks;
+}
+function readRuleBlock(element, media, rule) {
+    const block = { element, media, rule, declarations: [], targets: new Map() };
+    for (const node of rule.nodes) {
+        if (node.type === 'decl')
+            block.declarations.push(node);
+        else if (node.type === 'atrule' && node.name === 'origami-target' && node.nodes) {
+            const target = node.params.trim();
+            block.targets.set(target, [...(block.targets.get(target) ?? []), ...node.nodes.filter((child) => child.type === 'decl')]);
+        }
+    }
+    return block;
+}
+/** The blocks merged per element and breakpoint, the default scopes first (a breakpoint inherits the default's container type); a target's declarations join the rule's. */
+function mergeScopes(blocks) {
+    const scopes = new Map();
+    for (const block of blocks) {
+        const key = `${block.media ?? ''}\n${block.element}`;
+        const scope = scopes.get(key) ?? { element: block.element, media: block.media, values: new Map(), rulesWithTargets: [] };
+        scopes.set(key, scope);
+        for (const decl of [...block.declarations, ...[...block.targets.values()].flat()])
+            scope.values.set(decl.prop, decl);
+        if (block.targets.size)
+            scope.rulesWithTargets.push(block.rule);
+    }
+    return [...scopes.values()].sort((a, b) => Number(a.media !== null) - Number(b.media !== null));
+}
+// ── reading values (valueDeserializers.ts) ──
+/** A value reads as the import reads it: a site layout variable's token, `var(--name, <fallback>)`, by its fallback (layoutVariables.ts literalOf); `--spx(12)` as `12spx`. */
+function isReadable(spec, value) {
+    const literal = LAYOUT_VARIABLE_TOKEN.exec(value)?.[1] ?? value;
+    if (spec.values)
+        return spec.values.includes(literal);
+    return spec.reads ? spec.reads(restoreSpx(literal)) : true;
+}
+/** `var(--name, <fallback>)`: a field connected to one of the site's layout variables, written with the field's own value as the fallback. */
+const LAYOUT_VARIABLE_TOKEN = /^var\(--[A-Za-z_-][\w-]*,\s*(.+)\)$/;
+/** The import reads `--spx(12)` as `12spx` before it reads a value (spxTransformer.ts restoreSpxValue). */
+const restoreSpx = (value) => value.replace(/--spx\((-?\d+(?:\.\d+)?)\)/g, '$1spx');
+const SIZE_KEYWORDS = ['auto', 'fit-content', 'max-content', 'min-content', 'unset'];
+const UNIT_SIZE = /^-?\d+(?:\.\d+)?(?:px|%|fr|spx|vh|vw|em|rem)$/;
+function isSize(value) {
+    return SIZE_KEYWORDS.includes(value) || UNIT_SIZE.test(value) || /^calc\(.+\)$/.test(value);
+}
+/** `<width> / <height>` → height / width; one number → 1 / n; a ratio that is finite and above zero. */
+function isAspectRatio(value) {
+    const match = /^(\d*\.?\d+)\s*\/\s*(\d*\.?\d+)$/.exec(value);
+    const ratio = match ? Number(match[2]) / Number(match[1]) : 1 / Number(value);
+    return Number.isFinite(ratio) && ratio > 0;
+}
+/** A track list: tracks separated by spaces outside parentheses, each a size, `minmax(<size>, <size>)` or `repeat(<n | auto-fill | auto-fit>, <tracks>)`. */
+function isTracks(value) {
+    const tracks = splitOutsideParens(value, ' ');
+    return tracks.length > 0 && tracks.every(isTrack);
+}
+function isTrack(track) {
+    if (track.startsWith('repeat(') && track.endsWith(')')) {
+        const [count, tracks] = splitOutsideParens(track.slice('repeat('.length, -1), ',', 2);
+        if (tracks === undefined)
+            return false;
+        const n = Number(count);
+        const countOk = Number.isFinite(n) ? Number.isInteger(n) && n > 0 : ['auto-fill', 'auto-fit'].includes(count);
+        return countOk && isTracks(tracks);
+    }
+    if (track.startsWith('minmax(') && track.endsWith(')')) {
+        const [min, max] = splitOutsideParens(track.slice('minmax('.length, -1), ',', 2);
+        return max !== undefined && isSize(min) && isSize(max);
+    }
+    return isSize(track);
+}
+/** Splits on a separator at parenthesis depth 0, trimming each part and dropping empty ones; `limit` 2 splits once (the import's splitFunctionArgs). */
+function splitOutsideParens(value, separator, limit = Infinity) {
+    const parts = [];
+    let current = '';
+    let depth = 0;
+    for (const char of value) {
+        if (char === '(')
+            depth++;
+        else if (char === ')')
+            depth--;
+        if (char === separator && depth === 0 && parts.length < limit - 1) {
+            if (current.trim() || separator === ',')
+                parts.push(current.trim());
+            current = '';
+        }
+        else
+            current += char;
+    }
+    if (current.trim() || separator === ',')
+        parts.push(current.trim());
+    return parts;
+}