@wix/origami-lint 1.34.24 → 1.34.25

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.25",
   "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": "e4031adeef0d38fd736d432532a85f648531c1c89cff31aa089a0fad"
 }