@wix/origami-lint 1.34.24 → 1.34.26

package/dist/rules/site-app/global-styles.js

@@ -1,6 +1,6 @@
 import { BREAKPOINT_AT_RULES, createCssFileReporter, describeAtRule, getCssChildren, getDashedId, getMixinId, getSegmentClass, getSelectorSegments, isCssIdentifier, isSafeCssIdentifier } from "../../rules-api/index.js";
 import { defineRule } from "./define-rule.js";
-const CHECKS = ['invalid_mixin_id', 'invalid_mixin_result', 'missing_parent_selector', 'bare_parent_selector', 'nested_style_rule', 'apply_at_result_root', 'nested_mixin', 'invalid_result_at_rule', 'invalid_parent_selector', 'conditional_global_style_link', 'invalid_linked_style_id', 'missing_linked_style', 'duplicate_global_style_link', 'link_with_values', 'missing_global_style_link'];
+const CHECKS = ['invalid_mixin_id', 'invalid_mixin_result', 'missing_parent_selector', 'bare_parent_selector', 'nested_style_rule', 'apply_at_result_root', 'nested_mixin', 'invalid_result_at_rule', 'invalid_parent_selector', 'conditional_global_style_link', 'invalid_linked_style_id', 'missing_linked_style', 'duplicate_global_style_link', 'link_with_values', 'missing_global_style_link', 'mixin_link_cycle'];
 export default defineRule({
     name: 'global-styles',
     checks: CHECKS,
@@ -22,9 +22,12 @@ function checkMixinsAndLinks(root, file, report) {
     const mixins = getCssChildren(root).filter((node) => node.type === 'atrule' && node.name === 'mixin');
     const rules = mixins.flatMap((mixin) => checkMixin(mixin, reportInFile));
     const declaredIds = new Set(mixins.flatMap((mixin) => getMixinId(mixin) ?? []));
-    const linkedParts = checkLinks(rules.filter((rule) => rule.apply), declaredIds, reportInFile);
+    const { linkedParts, validLinks } = checkLinks(rules.filter((rule) => rule.apply), declaredIds, reportInFile);
     for (const group of groupBySelector(rules))
         checkLinkOrValues(group, linkedParts, reportInFile);
+    // the build keeps the last `@mixin` of an id (mixins.js bodies.set): its links are the ones it follows
+    const lastMixinById = new Map(mixins.flatMap((mixin) => { const id = getMixinId(mixin); return id === null ? [] : [[id, mixin]]; }));
+    checkLinkCycles(validLinks.filter((link) => getEnclosingMixin(link.node) === lastMixinById.get(link.mixin)), reportInFile);
 }
 /** `@mixin --id { @result { … } }` (CONV-astParser.ts:287, :293), then its `@result`; returns its `&` rules that pass. */
 function checkMixin(mixin, reportInFile) {
@@ -107,6 +110,7 @@ function checkSelector(rule, reportInFile) {
 function checkLinks(links, declaredIds, reportInFile) {
     const linkedParts = new Set();
     const validLinkParts = new Set();
+    const validLinks = [];
     for (const link of links) {
         const child = link.apply.params.trim();
         const linkDescription = `\`@mixin --${link.mixin}\`'s link \`@apply ${child}\``;
@@ -135,8 +139,43 @@ function checkLinks(links, declaredIds, reportInFile) {
             continue;
         }
         validLinkParts.add(part);
+        validLinks.push(link);
     }
-    return linkedParts;
+    return { linkedParts, validLinks };
+}
+/** Reports each link that closes a cycle (OUR-007): a walk from each mixin in the file's order, depth first, visiting each mixin once; a link
+ * to a mixin still on the walk's path leads back to it. Every cycle holds such a link, so removing the reported ones breaks them all. */
+function checkLinkCycles(validLinks, reportInFile) {
+    const linksByMixin = new Map();
+    for (const link of validLinks)
+        linksByMixin.set(link.mixin, [...(linksByMixin.get(link.mixin) ?? []), link]);
+    const visited = new Set();
+    for (const start of linksByMixin.keys()) {
+        if (visited.has(start))
+            continue;
+        visited.add(start);
+        // the walk's path: each mixin on it, and how many of its links were followed
+        const path = [{ mixin: start, next: 0 }];
+        while (path.length > 0) {
+            const step = path.at(-1);
+            const link = linksByMixin.get(step.mixin)?.[step.next++];
+            if (!link) {
+                path.pop();
+                continue;
+            }
+            const child = getDashedId(link.apply.params);
+            const onPath = path.findIndex(({ mixin }) => mixin === child);
+            if (onPath !== -1)
+                reportCycle(link, child, [...path.slice(onPath).map(({ mixin }) => mixin), child], reportInFile);
+            else if (!visited.has(child)) {
+                visited.add(child);
+                path.push({ mixin: child, next: 0 });
+            }
+        }
+    }
+}
+function reportCycle(link, child, chain, reportInFile) {
+    reportInFile(link.apply, 'mixin_link_cycle', `\`@mixin --${link.mixin}\` links \`--${child}\`, which leads back to it: ${chain.map((id) => `--${id}`).join(' → ')}. A global style can't contain itself: remove this link, or link a style that doesn't lead back to \`--${child}\` (tracker OUR-007).`);
 }
 /** One selector of a mixin (across its breakpoints): a link alone, or values; values on an inner part where a link names it (CONV-styleParser.ts:803, :698). */
 function checkLinkOrValues(group, linkedParts, reportInFile) {
@@ -152,6 +191,13 @@ function checkLinkOrValues(group, linkedParts, reportInFile) {
     reportInFile(first.node, 'missing_global_style_link', `\`@mixin --${first.mixin}\` styles \`${part}\` but links no global style there: add \`& ${part} { @apply --<child> }\` and move the values to that child's @mixin (tracker CONV-styleParser.ts:698).`);
 }
 // ── reading a mixin ──
+/** The `@mixin` a rule of its `@result` sits in. */
+function getEnclosingMixin(rule) {
+    for (let node = rule.parent; node; node = node.parent)
+        if (node.type === 'atrule' && node.name === 'mixin')
+            return node;
+    return undefined;
+}
 /** The mixin's one `@result` with no params and a block, beside nothing; undefined otherwise. */
 function getResult(mixin) {
     if (mixin.nodes === undefined)

package/dist/rules/site-app/page-structure.js

@@ -14,15 +14,21 @@
 // - a <Remove> holds exactly one component element (CONV-parseJsx.ts:1028), and no <Remove> sits inside another: <Remove> wraps
 //   the component itself (CONV-parseJsx.ts:1237; converter 0.86 parseJsx.ts:1500, :1681);
 // - only elements go between a component's tags: no text, no {…}, no fragment (CONV-parseJsx.ts:1668);
-// - an <InternalContainer>'s backgroundLayer / pinnedLayer is an array of elements (CONV-parseJsx.ts:1630).
-// Wrappers are transparent for the tree, as they are for the import: a section wrapped in <Remove> is still the page's child.
+// - an <InternalContainer>'s backgroundLayer / pinnedLayer, and a <Page>'s backgroundLayer / viewportLayer, is an array of elements
+//   (CONV-parseJsx.ts:1630);
+// - a <PinnedToScreen> takes no props and holds one section, header or footer, in its <Page> slot: a child of the <Page>, or its
+//   header / footer. A pinned section is never in the viewportLayer, which holds the page's other pinned components.
+// Wrappers are transparent for the tree, as they are for the import: a section wrapped in <Remove> or <PinnedToScreen> is still the
+// page's child.
 // <Interaction> is no wrapper since converter 0.80 (interactions live in servicesConfigs/interactions.ts): allowed-imports
 // reports the tag, and it stays transparent here so the elements inside it aren't reported too. Context-provider wrappers join
 // once the page model lists the providers.
 import { FILE_START } from "../../page-model/index.js";
-import { LAYER_ATTRIBUTES, SECTIONS, WRAPPERS } from "../../rules-api/index.js";
+import { getName, GLOBAL_SECTIONS, LAYER_ATTRIBUTES, SECTIONS, WRAPPERS } from "../../rules-api/index.js";
 import { defineRule } from "./define-rule.js";
-const CHECKS = ['missing_root', 'invalid_global_root', 'missing_root_id', 'invalid_page_root', 'non_element_child', 'invalid_section_container', 'nested_page', 'landmark_inside_container', 'invalid_wrapper_children', 'nested_remove', 'invalid_element_array', 'invalid_landmark_section'];
+const CHECKS = ['missing_root', 'invalid_global_root', 'missing_root_id', 'invalid_page_root', 'non_element_child', 'invalid_section_container', 'nested_page', 'landmark_inside_container', 'invalid_wrapper_children', 'nested_remove', 'invalid_element_array', 'invalid_landmark_section', 'invalid_pinned_child', 'invalid_pinned_placement', 'pinned_wrapper_props', 'section_in_viewport_layer'];
+/** What <PinnedToScreen> may hold: a section, a header or footer, or a page's reference to a global one. */
+const PINNABLE = [...SECTIONS, ...GLOBAL_SECTIONS, 'headerLandmark', 'footerLandmark'];
 export default defineRule({
     name: 'page-structure',
     checks: CHECKS,
@@ -33,7 +39,10 @@ export default defineRule({
             if (!input.rulesApi.getComponent(input.node))
                 return;
             if (isWrapper(input.node, input.rulesApi)) {
-                if (input.rulesApi.getType(input.node) !== 'remove')
+                const type = input.rulesApi.getType(input.node);
+                if (type === 'pinnedToScreen')
+                    checkPinnedToScreen(input);
+                if (type !== 'remove')
                     return;
                 holdsOneElement(input);
                 checkNoRemoveInRemove(input);
@@ -45,6 +54,7 @@ export default defineRule({
             if (isSection(input.node, input.rulesApi))
                 hasOneInternalContainer(input.node, input);
             hasLayerArrays(input);
+            checkViewportLayerItems(input);
             isNotNestedPage(input);
             isOutsideInternalContainers(input);
             if (!isTop(input.node, input.rulesApi))
@@ -162,9 +172,10 @@ function hasOnlyElements({ node, rulesApi, report }) {
         report({ check: 'non_element_child', loc: child.type === 'JSXText' ? getTextLoc(child) : child.loc, message: `${describeElement(node, rulesApi)} has text or {…} as a child. Put the value in an attribute: only elements go between the tags (tracker CONV-parseJsx.ts:1668).` });
     }
 }
-/** Reports an <InternalContainer>'s backgroundLayer / pinnedLayer that isn't an array literal of elements (CONV-parseJsx.ts:1630). */
+/** Reports an <InternalContainer>'s or a <Page>'s layer that isn't an array literal of elements (CONV-parseJsx.ts:1630). */
 function hasLayerArrays({ node, rulesApi, report }) {
-    if (rulesApi.getType(node) !== 'innerElement')
+    const type = rulesApi.getType(node);
+    if (type !== 'innerElement' && type !== 'page')
         return;
     for (const attribute of node.openingElement.attributes) {
         if (attribute.type !== 'JSXAttribute' || attribute.name.type !== 'JSXIdentifier' || !LAYER_ATTRIBUTES.includes(attribute.name.name))
@@ -174,7 +185,62 @@ function hasLayerArrays({ node, rulesApi, report }) {
         report({ check: 'invalid_element_array', loc: attribute.loc, message: `${describeElement(node, rulesApi)}'s ${attribute.name.name} must be an array of elements: ${attribute.name.name}={[<… />]} (tracker CONV-parseJsx.ts:1630).` });
     }
 }
+/** A <PinnedToScreen>: no props, one element held, a pinnable one, in its <Page> slot. */
+function checkPinnedToScreen(input) {
+    const { node, rulesApi, report } = input;
+    if (node.openingElement.attributes.length > 0) {
+        report({ check: 'pinned_wrapper_props', loc: node.openingElement.name.loc, message: `<${rulesApi.getTagName(node)}> takes no props: the element it pins keeps its own id, className and layout.` });
+    }
+    holdsOneElement(input);
+    checkPinnedChild(input);
+    checkPinnedPlacement(input);
+}
+/** Reports a <PinnedToScreen> whose one element isn't a section, header or footer; the wrong number of elements is holdsOneElement's. */
+function checkPinnedChild({ node, rulesApi, report }) {
+    if (!holdsOne(node))
+        return;
+    const inside = rulesApi.getChildElements(node);
+    if (inside.length === 1 && isPinnable(inside[0], rulesApi))
+        return;
+    report({ check: 'invalid_pinned_child', loc: node.openingElement.name.loc, message: `<${rulesApi.getTagName(node)}> holds ${inside.map((child) => describeElement(child, rulesApi)).join(', ') || 'nothing'}. It pins a section, header or footer; put any other pinned component in the <Page>'s viewportLayer.` });
+}
+/** Reports a <PinnedToScreen> anywhere but in a <Page>'s children or its header / footer, or inside another <PinnedToScreen>. */
+function checkPinnedPlacement({ node, rulesApi, report }) {
+    const holder = getHolder(node, rulesApi);
+    const between = getAncestors(node).slice(0, holder ? getAncestors(node).indexOf(holder) : undefined);
+    const attribute = holder && getHolderAttribute(node, holder);
+    if (holder && rulesApi.getType(holder) === 'page' && (attribute === null || attribute === 'header' || attribute === 'footer')
+        && !between.some((wrapper) => rulesApi.getType(wrapper) === 'pinnedToScreen'))
+        return;
+    const where = holder ? `inside ${describeElement(holder, rulesApi)}${attribute ? `'s ${attribute}` : ''}` : 'at the top';
+    report({ check: 'invalid_pinned_placement', loc: node.openingElement.name.loc, message: `<${rulesApi.getTagName(node)}> is ${where}. It goes in its <Page> slot only, once: around a child of the <Page>, or in its header or footer.` });
+}
+/** Reports a section, header or footer in a <Page>'s viewportLayer: a pinned one stays in its slot, wrapped in <PinnedToScreen>. One already wrapped is checkPinnedPlacement's. */
+function checkViewportLayerItems({ node, rulesApi, report }) {
+    if (rulesApi.getType(node) !== 'page')
+        return;
+    for (const { element, attribute } of rulesApi.getAttributeElements(node)) {
+        if (getName(attribute) !== 'viewportLayer' || !isPinnable(element, rulesApi))
+            continue;
+        if (getAncestors(element).some((wrapper) => rulesApi.getType(wrapper) === 'pinnedToScreen'))
+            continue;
+        report({ check: 'section_in_viewport_layer', loc: getLoc(element, rulesApi), message: `${describeElement(element, rulesApi)} is in the viewportLayer of ${describeElement(node, rulesApi)}. A pinned section, header or footer stays in its <Page> slot, wrapped in <PinnedToScreen>.` });
+    }
+}
 // ── reading the tree ──
+/** A section, header or footer, which <PinnedToScreen> may hold. */
+const isPinnable = (element, rulesApi) => {
+    const type = rulesApi.getType(element);
+    return type !== null && PINNABLE.includes(type);
+};
+/** The attribute of the holder the element is passed in (`header`); null for one of its children. */
+function getHolderAttribute(element, holder) {
+    for (let node = element.parent; node && node !== holder; node = node.parent) {
+        if (node.type === 'JSXAttribute')
+            return getName(node);
+    }
+    return null;
+}
 /** 'header' / 'footer' for the section tags and for a page's reference to the global ones; null for anything else. */
 function headerOrFooter(type) {
     if (type === 'header' || type === 'globalHeader' || type === 'headerLandmark')

package/dist/shared/constants.js

@@ -2,8 +2,8 @@
 export const SECTIONS = ['section', 'header', 'footer'];
 /** A page's reference to a global component (`<HeaderSection_x sharedCompId="…" />`). */
 export const GLOBAL_SECTIONS = ['globalHeader', 'globalFooter', 'globalSection'];
-/** A tag that wraps one component and isn't one itself: `<Remove when={…}>`, `<Interaction interactKey="…">`. */
-export const WRAPPERS = ['remove', 'interaction'];
+/** A tag that wraps one component and isn't one itself: `<Remove when={…}>`, `<Interaction interactKey="…">`, `<PinnedToScreen>` (the import drops it). */
+export const WRAPPERS = ['remove', 'interaction', 'pinnedToScreen'];
 /** The name a structure file exports its tree under: `export const Structure = () => (…)`. */
 export const STRUCTURE = 'Structure';
 /** The props a global component's Structure may take: its instance identity, `({ id, className })` (#300). */
@@ -38,6 +38,7 @@ export const EVENT_ATTRIBUTE = /^on/i;
 /** A callback prop, which the runtime hands a function: `on` and a capital letter, `onClick` but not `onclick` (the runtime's withOrigami.tsx). */
 export const CALLBACK_PROP = /^on[A-Z]/;
 /** By import source; the wrappers also by the imported name, since their packages export other things (`Show`, `Interact`). */
-export const LAYER_ATTRIBUTES = ['backgroundLayer', 'pinnedLayer'];
+/** The attributes that hold an element's layers: drawn behind it, and pinned to it (a container's pinnedLayer, the Page's viewportLayer). */
+export const LAYER_ATTRIBUTES = ['backgroundLayer', 'pinnedLayer', 'viewportLayer'];
 /** The attribute that holds the elements of a component's inner parts: `elementProps={{ panel: { content: <X /> } }}`. */
 export const ELEMENT_PROPS = 'elementProps';

package/dist/shared/utils.js

@@ -4,6 +4,7 @@ const TYPE_BY_IMPORT_SOURCE = [
     [new RegExp(`^${SYSTEM_PACKAGE}/(?:layout/)?Page$`), 'page'],
     [new RegExp(`^${SYSTEM_PACKAGE}/layout/Header$`), 'headerLandmark'],
     [new RegExp(`^${SYSTEM_PACKAGE}/layout/Footer$`), 'footerLandmark'],
+    [new RegExp(`^${SYSTEM_PACKAGE}/layout/PinnedToScreen$`), 'pinnedToScreen'],
     [new RegExp(`^${SYSTEM_PACKAGE}/(?:layout/)?Section$`), 'section'],
     [new RegExp(`^${SYSTEM_PACKAGE}/(?:layout/)?HeaderSection$`), 'header'],
     [new RegExp(`^${SYSTEM_PACKAGE}/(?:layout/)?FooterSection$`), 'footer'],
@@ -37,7 +38,7 @@ export function getType(element, program) {
     return imported === undefined || found.imported === imported ? type : null;
 }
 /** The tags the import reads as the DM's own components ('document') or a global component's reference (identity.ts identityOfTag): no data attributes. */
-const NO_DATA_TYPES = ['page', 'section', 'header', 'footer', 'headerLandmark', 'footerLandmark', ...GLOBAL_SECTIONS];
+const NO_DATA_TYPES = ['page', 'section', 'header', 'footer', 'headerLandmark', 'footerLandmark', 'pinnedToScreen', ...GLOBAL_SECTIONS];
 /** Converter 0.81: are the tag's attributes saved as its component's data? Yes on a builder component (its import gives a componentType):
  * imported, not from `document` and not from a local file. No on the DM's own tags (`Page`, the sections) and a global component's reference. */
 export function hasDataAttributes(element, program) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/origami-lint",
-  "version": "1.34.24",
+  "version": "1.34.26",
   "description": "Offline lint for an exported Origami site: lints the pages that changed since the last passing run",
   "type": "module",
   "bin": {
@@ -52,5 +52,5 @@
       ]
     }
   },
-  "falconPackageHash": "1bb53e289c65cf4acdcbc54a85fcf823b282d0e1be7bac656dff5170"
+  "falconPackageHash": "789db12225da1bce9eb55f3b1d60b56d77f04f07778f4eb0a234e3ff"
 }