mosaic-headless 1.26.1 → 1.28.0

package/references/dynamic-content.md

@@ -111,3 +111,57 @@ attachment(2)  find_image(2)  find_link(2)  find_video(2)       media
 `sum`, `avg`, `concat` and `fallback` are variadic. `date()`'s timestamp argument is a
 true GMT Unix timestamp — pair it with `post/publish_timestamp_gmt`, not
 `publish_timestamp`, unless you want the local-time value re-interpreted as UTC.
+
+## A loop in place of a component's children
+
+Three component families take a loop INSTEAD of hand-authored children, which is
+the thing a page builder needs a plugin per component to do:
+
+```
+slider-slides > slider-loop-slides  > slider-slide      one slide per row
+tabs-menu     > tabs-loop-tabs      > tabs-tab
+tabs-content  > tabs-loop-tab-panes > tabs-tab-pane
+list          > list-loop-items     > list-item
+accordion     > accordion-loop-items> accordion-item
+```
+
+Each loop container carries the same three keys an ordinary `loop` does —
+`loopType`, `loopNamespace` and a `<loopType>Options` group — and the template
+inside reads its row with `@VAR('<namespace>/…')`. You author ONE slide, one tab,
+one row; the count comes from the content. The assertion that matters is therefore
+a COUNT: a template that failed to loop renders exactly once and looks correct.
+
+**`canBeParentFor` disagrees with the factory's own default data on these.**
+`SliderLoopSlidesElementTypeFactory::canBeParentFor()` returns true for
+`SliderSlidesElementTypeFactory` — the track, not the slide — while its
+`getDefaultData()` seeds itself with a `slider-slide`. `accordion-loop-items` says
+`accordion` the same way. The structure the editor actually builds is the second
+one. `build_page.py` resolves it by treating a loop container as standing in for
+its parent's children: what `slider-loop-slides` accepts is what `slider-slides`
+accepts.
+
+## `loop-pagination`, and the key you must not use
+
+```
+loop > loop-pagination > loop-pagination-button-previous
+                       > loop-pagination-numbers > loop-pagination-number
+                       > loop-pagination-button-next
+```
+
+`loop-pagination-number` is a TEMPLATE repeated per page, the same rule as a
+slider bullet — author one. `loop-pagination-numbers` takes `pagesBefore` /
+`pagesAfter` / `pagesStart` / `pagesEnd` to decide how much of a long range to
+show.
+
+**Do not set `paginationKey` to `p`.** It is one of WordPress's own reserved query
+vars, meaning "post ID": `?p=2` answers **HTTP 301** to post 2, so the visitor
+leaves the page entirely and the loop renders nothing. Measured. Any other key
+works — `?notes=2` on the demo pages the archive and changes all three rows.
+
+## `@substr` counts BYTES
+
+`@substr(@VAR('post/title'), 0, 14)` on a Han title cuts the fifth character in
+half and the output ends in U+FFFD. Lengths have to be a multiple of the encoding
+width — 18 for six three-byte characters — or the truncation has to be left to CSS.
+A count-based check cannot see this; `verify_components.py` looks for the
+replacement character directly.

package/references/failure-modes.md

@@ -372,3 +372,30 @@ Two things come out of it:
 The general form: a check that confirms a resource EXISTS is not a check that the
 control WORKS, and anything living in a shared layout needs verifying on every
 page that includes it, not on the page it was designed for.
+
+## Three ways a form comes back empty, none of them an error
+
+A form page built in one pass rendered two fieldsets, one stray label and **zero
+controls**. The commit succeeded, the response carried no exception, and the HTML
+was valid. Every field had been dropped on the way in, for three different reasons:
+
+- **`label` and the inputs need a `field` above them.** They declare
+  `canBeNestedChildFor` and walk the parent chain looking for one; committed under
+  a plain div they are refused and discarded. `placement-rules.csv` now carries a
+  `nested_under` column naming exactly what each type is looking for — 54 types
+  have one, and the names rarely share a prefix (`radio-input` wants `choice`,
+  `label` wants `field`, `loop-pagination` wants `loop`).
+- **`fieldset` does not take fields.** It renders `fieldset-legend` +
+  `fieldset-content`, and direct children are dropped. Neither type was in
+  `node-types.csv` at all, because they are declared by an
+  `*ElementMResourceFactory.php` and every extractor here walked
+  `*ElementTypeFactory.php` only. Two types were missing from the catalog; the
+  walk now covers both and the count went 126 → 128.
+- **`select-option` is a leaf and its label is the `text` PROPERTY.** Give it a
+  `wysiwyg-text` child and the option renders with an empty label: a dropdown that
+  opens onto five blank lines, which looks like a styling problem and is not.
+
+The through-line is the one this file keeps recording: Mosaic accepts a write it
+cannot use and says nothing. The defence is to read the delivered page back and
+count what arrived — `verify_components.py` now asserts the control count, the option
+labels and that an empty required form is actually refused.

package/references/placement.md

@@ -115,3 +115,41 @@ Reach for the measured table when you are deciding what to build with, and this
 when you are deciding what may go inside what. `tools/check_placement_predicts.py`
 re-scores the numbers above after any re-sweep, so the claim stays honest if the
 plugin changes.
+
+## `nested_under`: what a type is looking for above it
+
+`rule` is the `canBeParentFor()` answer — "will the editor let me drop this here".
+Many types also implement `canBeNestedChildFor()`, which walks the parent chain at
+runtime looking for ONE ancestor class, and until now this table only recorded
+that such a rule existed. The `nested_under` column now names it. 54 of 128 types
+have one, and the names usually share no prefix with the type, so there is no way
+to infer it:
+
+| type | needs above it |
+|---|---|
+| `radio-input`, `checkbox-input`, `choice-label` | `choice` |
+| `choice`, | `choice-field` |
+| `label`, `fileupload-input` | `field` |
+| `choice-field`, `fieldset`, `field`, `hidden-input` | `choice-field` \| `field` \| `form` |
+| `loop-item` | `loop-items` |
+| `loop-pagination` | `loop` |
+| `list-item` | `list` \| `list-loop-items` \| `wp-menu` |
+| `accordion-item` | `accordion` \| `accordion-loop-items` |
+
+A node committed without its required ancestor is **accepted and discarded**. The
+commit returns no exception, the page renders, and the element is simply not
+there — which is how a form came back with two fieldsets and no fields.
+`build_page.py` reads this column and now carries the ancestor chain down the walk,
+so a correct placement is allowed and an incorrect one is refused before the write
+rather than silently lost after it.
+
+Two other things the table was short of, both fixed the same way — by reading the
+source the column was derived from rather than the one it was convenient to read:
+
+- **`takes_children`**, from the factory's `getDefaultData($data, $children)`
+  signature. `dropdown-wrapper` answers `none` to `canBeParentFor` and holds the
+  menu's links regardless.
+- **two missing types.** `fieldset-legend` and `fieldset-content` are declared by
+  an `*ElementMResourceFactory.php`; every extractor walked
+  `*ElementTypeFactory.php` only, so they were absent from the catalog and a
+  fieldset appeared to have no inner structure.

package/scripts/check-release.mjs

@@ -101,9 +101,11 @@ const counts = {
   "data/dialog-verification.csv": 19,
   "data/slider-verification.csv": 30,
   "data/token-verification.csv": 15,
-  "data/mobile-audit.csv": 58,
-  "data/component-wall-verification.csv": 11,
-  "data/navigation-verification.csv": 33,
+  "data/mobile-audit.csv": 63,
+  "data/component-wall-verification.csv": 13,
+  "data/form-surface-verification.csv": 8,
+  "data/content-loop-verification.csv": 10,
+  "data/navigation-verification.csv": 39,
   "data/page-modal-verification.csv": 19,
   "data/interaction-rules-verification.csv": 17,
   "data/dialog-form-verification.csv": 49,

package/sites/_moksa.py

@@ -304,6 +304,10 @@ CONVERTED_COUNT = _count("conversion-batch.csv",
 
 # label, href, one line of what it demonstrates
 CAPABILITIES = [
+    ("內容驅動", "/content/",
+     "輪播、分頁、存檔——都由文章資料複製"),
+    ("表單", "/forms/",
+     "下拉、單選、複選、上傳、必填規則與錯誤訊息"),
     ("元件牆", "/components/",
      "分頁、手風琴、表單、地圖——都能直接操作"),
     ("彈窗與觸發", "/dialogs/",
@@ -3228,6 +3232,14 @@ if __name__ == "__main__":
     # helpers it reads are pure functions - two copies produce identical dicts.
     import _dialogs
     import _sliders
+    import _content
+    SITE["pages"].append({"slug": "content", "post_id": 283,
+                          "title": "內容驅動",
+                          "tree": apply_type(_content.TREE, DISPLAY, CJK, "600")})
+    import _forms
+    SITE["pages"].append({"slug": "forms", "post_id": 282,
+                          "title": "表單",
+                          "tree": apply_type(_forms.TREE, DISPLAY, CJK, "600")})
     import _components
     SITE["pages"].append({"slug": "components", "post_id": 281,
                           "title": "元件",