@fluid-app/fluid-cli-theme-dev 0.1.516 → 0.1.518

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -93,9 +93,39 @@ hosts and rejects cross-origin requests.
93
93
 
94
94
  Successful watched uploads refresh the page list before reloading. Failed uploads
95
95
  retain the last known routes, and a removed page returns an explicit error.
96
- `--live-reload off` disables automatic reload. System screens report unsupported
97
- until the separate sample-runtime integration ships. The navigation command
98
- integration is a separate follow-up; use `/_members` for this version.
96
+ `--live-reload off` disables automatic reload.
97
+
98
+ ### Choose a member preview page
99
+
100
+ Run `fluid theme navigate` while the dev server is running, or start it with
101
+ `fluid theme dev --navigate`, to use the same route picker. Member pages are
102
+ grouped by site and include drafts. Storefront choices remain available.
103
+
104
+ Use `--host` and `--port` for a custom local address. `theme navigate --theme <id>`
105
+ must match the running server’s theme. The picker reads routes after acknowledged
106
+ syncs and rechecks a member page before opening it. System screens appear only
107
+ when the running preview runtime advertises support; unavailable screens are
108
+ listed in the terminal. Cancelling the picker leaves the dev server running.
109
+
110
+ ### System-screen sample previews
111
+
112
+ Member navigation also lists **profile, messaging, contacts, my-site, orders, and subscriptions** when
113
+ both the Rails catalogue and the packaged CLI runtime support them. The CLI
114
+ ships its own sample-only account-screen bundle; no CDN update or member login
115
+ is needed. A missing bundle produces an explicit unavailable response instead
116
+ of loading a live screen.
117
+
118
+ Screen links use production paths under `/_members`, for example
119
+ `/_members/profile/orders?members_site_id=42`. Detail navigation, refresh and
120
+ browser back preserve the selected site and audience. Theme layouts, attribute
121
+ settings and `--fluid-account-*` CSS overrides apply to these screens.
122
+
123
+ Data is synthetic. Writes and sign-out are rejected; payment entry is disabled.
124
+ These previews do not verify private member data or real member permissions.
125
+ Screens outside the packaged catalogue, currently `media` and `playlists`,
126
+ return 501. From source, run
127
+ `pnpm --filter @fluid-app/fluid-cli-theme-dev build` before starting the CLI;
128
+ this also builds and copies the shared sample runtime into the CLI package.
99
129
 
100
130
  ### `fluid theme push`
101
131
 
@@ -275,6 +305,155 @@ Do not add `.fluid-assets.json` to `.fluidignore`; it is already excluded from
275
305
  theme uploads and file watching. Commit it with the theme source so every
276
306
  developer receives the same remote asset references.
277
307
 
308
+ ## Member sites
309
+
310
+ A theme's member sites, their pages and their menus are described by
311
+ `members_sites.json` at the theme root. Each page's content is an ordinary
312
+ template at `members_page/<name>/index.liquid`.
313
+
314
+ ### `members_sites.json`
315
+
316
+ The file is a version 2 JSON object:
317
+
318
+ ```json
319
+ {
320
+ "version": 2,
321
+ "sites": [
322
+ {
323
+ "key": "site-main",
324
+ "name": "Members",
325
+ "active": true,
326
+ "default": true,
327
+ "position": 0,
328
+ "layout_name": null,
329
+ "rule": { "country_codes": [], "member_type_slugs": [] },
330
+ "menu_key": "menu-main",
331
+ "pages": [
332
+ {
333
+ "key": "page-home",
334
+ "title": "Home",
335
+ "slug": "/",
336
+ "published": true,
337
+ "template_path": "members_page/home/index.liquid"
338
+ }
339
+ ]
340
+ }
341
+ ],
342
+ "menus": [
343
+ {
344
+ "key": "menu-main",
345
+ "handle": "members-main",
346
+ "title": "Members",
347
+ "active": true,
348
+ "country_codes": [],
349
+ "items": []
350
+ }
351
+ ],
352
+ "menu_references": []
353
+ }
354
+ ```
355
+
356
+ - `sites`, `menus` and `menu_references` are required arrays. An optional
357
+ `templates` array carries metadata for member templates. Each `key` is
358
+ unique within its kind and is how entries refer to each other.
359
+ - `sites[].pages[].template_path` is `null` or a
360
+ `members_page/<name>/index.liquid` path. A `slug` is `/` (the site's home
361
+ page) or lowercase words joined by hyphens.
362
+ - Slugs the account host already serves are refused: the system screens
363
+ `profile`, `orders`, `subscriptions`, `messaging`, `contacts`, `my-site`,
364
+ `media` and `playlists`, plus `auth`, `api` and `accounts`.
365
+ - `sites[].layout_name` picks the layout that frames the site's pages. Blank,
366
+ `member` and `theme` use `layouts/member.liquid` if the theme has it, then
367
+ `layouts/theme.liquid`. Any other name must exist as `layouts/<name>.liquid`
368
+ when the file is pushed. `none` renders pages with no layout.
369
+ - Every menu must be used by a site's `menu_key` or by a `menu_references`
370
+ entry. A `menu_references` entry points at a `link_list` setting in a
371
+ template (`path`, `location` of `json` or `schema`, a JSON `pointer`, and
372
+ `menu_key`).
373
+
374
+ A legacy array-format `members_sites.json` is still uploaded as an ordinary
375
+ file, without the bundling described below.
376
+
377
+ ### Member pages
378
+
379
+ A member page template has one `{% section %}` tag per placement, then a
380
+ `{% schema %}` block listing every placement's settings and the render order:
381
+
382
+ ```liquid
383
+ {% section 'hero_section', id: 'a1' %}
384
+ {% section 'fluid://native/widgets/orders', id: 'b2' %}
385
+
386
+ {% schema %}
387
+ {
388
+ "sections": {
389
+ "a1": { "type": "hero_section", "settings": {} },
390
+ "b2": { "type": "fluid://native/widgets/orders", "settings": {} }
391
+ },
392
+ "order": ["a1", "b2"]
393
+ }
394
+ {% endschema %}
395
+ ```
396
+
397
+ This is the shape the visual builder reads and writes. Do not give a page a
398
+ section-style schema (`name`, `settings`, `blocks`).
399
+
400
+ ### Native widgets
401
+
402
+ `{% section 'fluid://native/widgets/<key>', id: '…' %}` places a Fluid-owned
403
+ widget. It has no local file; `fluid theme lint` accepts known keys and warns
404
+ about unknown ones. Placing a new native widget needs the company to have
405
+ member sites enabled.
406
+
407
+ To customize a widget, create the theme's own copy with
408
+ `POST /api/v202604/themes/<id>/native-widget-copies` and
409
+ `{"native_widget_key": "<key>"}`. The copy replaces the widget at every
410
+ placement in that theme, and a later pull brings it down as
411
+ `sections/fluid_native_<key>/index.liquid`. Don't create that file by hand: a
412
+ hand-written `sections/fluid_native_<key>` is a plain section and does not
413
+ replace the widget.
414
+
415
+ ### How push, pull and staging handle member sites
416
+
417
+ - **Push bundles the manifest with its files.** When `members_sites.json` or
418
+ any file it references changes, `push` (and `dev`'s watcher) uploads the
419
+ manifest together with those files in one atomic request: page templates,
420
+ `templates` and `menu_references` paths, each site's layout, and the
421
+ `variables.json` and changed `styles.css` next to a referenced
422
+ `index.liquid`. Fluid applies all of it or none of it. Every referenced file
423
+ must be a local, non-ignored text file. If an upload earlier in the push
424
+ fails, the manifest is skipped.
425
+ - **Fluid may rewrite what it accepts**, for example to allocate menu handles.
426
+ The CLI records the server's version as synced, so the next pull may change
427
+ those files.
428
+ - **Deleting.** `members_sites.json` is never deleted from the server. Push
429
+ and `dev` refuse to delete it locally; to remove every member site, push
430
+ `{"version": 2, "sites": [], "menus": [], "menu_references": []}` instead.
431
+ A file the manifest still references can't be deleted either; remove the
432
+ reference first.
433
+ - **Pull keeps member files the server omits.** If the server's file list has
434
+ no `members_sites.json` (or it is in `.fluidignore`), pull keeps the local
435
+ manifest and every file it references. When that manifest has sites, pull also keeps
436
+ local `sections/`, `blocks/`, `components/`, `snippets/`, `navbar/` and
437
+ `footer/` files. Kept files are not recorded as synced. Pull stops without
438
+ changing anything if the previous manifest is over 2 MB, isn't JSON with
439
+ `"version": 2`, or isn't shaped well enough to list the files it
440
+ references: `sites`, `menus`, `menu_references` and each site's `pages`
441
+ must be arrays; site, page, `templates` and `menu_references` entries must
442
+ be objects; layout names and page template paths must be strings or
443
+ `null`; every template and menu
444
+ reference needs a `path`; and every referenced path must be a theme file
445
+ path. It doesn't check that those files exist. Everything else in the
446
+ manifest is validated when it is next pushed.
447
+ - **Retired template types are dropped.** `account_page`, `members_dashboard`
448
+ and `members_login` are no longer theme files. Their folders are never
449
+ uploaded. On push, references to them are removed from `templates` and
450
+ `menu_references` (with any menu left unused) and the local manifest is
451
+ rewritten to match.
452
+ - **`fluid theme staging publish` skips `members_sites.json`** and lists it
453
+ as skipped. Member configuration is not published to staging branches yet.
454
+ Retired template folders aren't theme files, so staging publish never sees
455
+ them: they are neither uploaded nor listed.
456
+
278
457
  ## Development
279
458
 
280
459
  For contributors working in this monorepo:
@@ -284,37 +463,6 @@ pnpm --filter @fluid-app/fluid-cli-theme-dev build
284
463
  node packages/cli/core/dist/bin/fluid.mjs theme --help
285
464
  ```
286
465
 
287
- ### Choose a member preview page
288
-
289
- Run `fluid theme navigate` while the dev server is running, or start it with
290
- `fluid theme dev --navigate`, to use the same route picker. Member pages are
291
- grouped by site and include drafts. Storefront choices remain available.
292
-
293
- Use `--host` and `--port` for a custom local address. `theme navigate --theme <id>`
294
- must match the running server’s theme. The picker reads routes after acknowledged
295
- syncs and rechecks a member page before opening it. System screens appear only
296
- when the running preview runtime advertises support; unavailable screens are
297
- listed in the terminal. Cancelling the picker leaves the dev server running.
298
-
299
- ### System-screen sample previews
300
-
301
- Member navigation also lists **profile, messaging, contacts, my-site, orders, and subscriptions** when
302
- both the Rails catalogue and the packaged CLI runtime support them. The CLI
303
- ships its own sample-only account-screen bundle; no CDN update or member login
304
- is needed. A missing bundle produces an explicit unavailable response instead
305
- of loading a live screen.
306
-
307
- Screen links use production paths under `/_members`, for example
308
- `/_members/profile/orders?members_site_id=42`. Detail navigation, refresh and
309
- browser back preserve the selected site and audience. Theme layouts, attribute
310
- settings and `--fluid-account-*` CSS overrides apply to these screens.
311
-
312
- Data is synthetic. Writes and sign-out are rejected; payment entry is disabled.
313
- These previews do not verify private member data or real member permissions.
314
- Screens outside the packaged catalogue remain unavailable. From source, run
315
- `pnpm --filter @fluid-app/fluid-cli-theme-dev build` before starting the CLI;
316
- this also builds and copies the shared sample runtime into the CLI package.
317
-
318
466
  ### Using member preview in Mist
319
467
 
320
468
  Start the theme's local preview in Mist, open the **Pages** sidebar, then choose
@@ -10,7 +10,8 @@ description: |
10
10
  pausing once in a while to ask the user whether to continue, skip, or stop. Covers: the
11
11
  schema validator, every valid setting `type`, singular vs plural selector misuse (e.g.
12
12
  multiple `product` settings → one `product_list`), the blocks-first content model, Liquid
13
- correctness, performance, security, accessibility, and file-size/DRY thresholds. Never
13
+ correctness, performance, security, accessibility, file-size/DRY thresholds, and member
14
+ sites (`members_sites.json`, `members_page` templates, native widget references). Never
14
15
  push to the live theme API without explicit approval.
15
16
  ---
16
17
 
@@ -69,6 +70,8 @@ my-theme/
69
70
  ├── navbar/default/index.liquid
70
71
  ├── footer/default/index.liquid
71
72
  ├── medium/default/index.liquid
73
+ ├── members_page/{name}/index.liquid ← member site pages, named by members_sites.json
74
+ ├── members_sites.json ← member sites, pages, and menus (version 2)
72
75
  ├── layouts/
73
76
  │ └── theme.liquid ← flat layout files, no wrapping dir
74
77
  ├── locales/
@@ -132,6 +135,8 @@ Every artifact has a fixed depth and shape. **No deeper nesting is allowed under
132
135
  **Page-type folder names recognized** (from the base-theme + reference theme):
133
136
  `home_page`, `product`, `cart_page`, `collection`, `collection_page`, `category`, `category_page`, `enrollment_pack`, `join_page`, `page`, `post`, `post_page`, `library`, `medium`, `navbar`, `footer`, `shop_page`, plus any others the engine adds. Each one holds **one or more variant directories** (`default/`, `revised/`, `holiday/`, etc.), each containing an `index.liquid`.
134
137
 
138
+ **Member pages** live at `members_page/{name}/index.liquid` and are routed by `members_sites.json`, not by page type. They use a different schema shape from sections and page templates, and they can place native widgets (`{% section 'fluid://native/widgets/<key>', id: '…' %}`). `account_page/`, `members_dashboard/` and `members_login/` are retired types the CLI never uploads. See [Member pages and native widgets](references/member-pages.md).
139
+
135
140
  **Blocks come in two shapes — prefer standalone.** Fluid themes are **blocks-first** (see [Blocks vs. sections](references/blocks-vs-sections.md)), and standalone blocks are the default shape.
136
141
 
137
142
  1. **Standalone (theme) blocks** — their own template at `blocks/{name}/index.liquid`, reusable across sections. A section opts in by declaring `@theme` (accept any theme block) or a named-block reference (a `{ "type": "<name>" }` entry with no `name`/`settings`) in its schema's `"blocks"` array; the engine resolves that to the matching `blocks/<name>/index.liquid` template. **This is the preferred shape for almost everything** — reusable, testable on its own, and it keeps the section to a few whole-section settings while each element's settings live on its block.
@@ -320,6 +325,7 @@ For each entry in `"blocks": [...]`:
320
325
  ### Section references
321
326
 
322
327
  - Every `{% section 'name' %}` in a Liquid template must have a matching section file on disk. Missing sections produce errors.
328
+ - `fluid://extensions/...` and `fluid://native/widgets/<key>` references have no local file and are not flagged. An unknown native widget key is a warning, not an error.
323
329
 
324
330
  ### Liquid block tags
325
331
 
@@ -353,6 +359,7 @@ touches them. Read the matching file when you hit its topic:
353
359
  - **[Security & accessibility](references/security-accessibility.md)** — escaping user content, alt text, semantic clickables.
354
360
  - **[Dead code](references/dead-code.md)** — unused sections/components/assets, unhandled block types.
355
361
  - **[CSS / JS hygiene](references/css-js-hygiene.md)** — co-located stylesheet deprecation, inline `<style>`/`<script>` thresholds, `defer`.
362
+ - **[Member pages and native widgets](references/member-pages.md)** — `members_sites.json`, the `members_page` placement schema, `fluid://native/widgets/<key>` references and theme copies, reserved slugs, layouts, retired template types. Read whenever a member site file is in scope.
356
363
  - **[Worked examples](references/examples.md)** — full section reviews, end to end.
357
364
 
358
365
  Every reference links directly from here (one level deep). "The validator" always means
@@ -619,6 +626,13 @@ When reviewing any theme file, run through this in order. Anything unchecked is
619
626
  - [ ] No co-located `styles.css` / `style.css` next to a template, section, or component (deprecated — all CSS lives in `assets/`)
620
627
  - [ ] Section/component directory names are `snake_case` and globally unique
621
628
 
629
+ **Member sites** (when the theme has `members_sites.json`; details in [Member pages](references/member-pages.md))
630
+
631
+ - [ ] Member pages use the placement schema (`sections` + `order`), not a section schema
632
+ - [ ] Native widgets are placed as `fluid://native/widgets/<key>`; no hand-written `sections/fluid_native_*`
633
+ - [ ] Every `template_path` and named layout exists locally; no page slug collides with a system screen
634
+ - [ ] No `account_page/`, `members_dashboard/` or `members_login/` folders
635
+
622
636
  **Layout**
623
637
 
624
638
  - [ ] Every file in `layouts/` emits `{{ content_for_header }}` inside `<head>`
@@ -0,0 +1,70 @@
1
+ # Member pages and native widgets
2
+
3
+ Read this when a review touches `members_sites.json`, a `members_page/` template, a
4
+ `layouts/` file a member site uses, or a `fluid://native/widgets/...` reference.
5
+
6
+ ## The files
7
+
8
+ - `members_sites.json` at the theme root describes member sites, their pages and their
9
+ menus. It is a version 2 object with `sites`, `menus` and `menu_references` arrays
10
+ (plus an optional `templates` array).
11
+ - Each page's content is `members_page/<name>/index.liquid`, named by
12
+ `sites[].pages[].template_path` (or `null` for a page with no template).
13
+ - `sites[].layout_name` frames the site's pages. Blank, `member` and `theme` use
14
+ `layouts/member.liquid` if it exists, then `layouts/theme.liquid`. Any other name must
15
+ exist as `layouts/<name>.liquid`. `none` means no layout.
16
+
17
+ ## Member page shape
18
+
19
+ One `{% section %}` tag per placement, then a `{% schema %}` with `sections` (id →
20
+ `{ "type", "settings" }`) and `order` (every id, in render order):
21
+
22
+ ```liquid
23
+ {% section 'hero_section', id: 'a1' %}
24
+ {% section 'fluid://native/widgets/orders', id: 'b2' %}
25
+
26
+ {% schema %}
27
+ {
28
+ "sections": {
29
+ "a1": { "type": "hero_section", "settings": {} },
30
+ "b2": { "type": "fluid://native/widgets/orders", "settings": {} }
31
+ },
32
+ "order": ["a1", "b2"]
33
+ }
34
+ {% endschema %}
35
+ ```
36
+
37
+ This is the shape the visual builder reads and writes. A member page is not a section.
38
+
39
+ ## Native widgets
40
+
41
+ `{% section 'fluid://native/widgets/<key>', id: '…' %}` places a Fluid-owned widget. It
42
+ has no local file, so it is not a missing section. `fluid theme lint` accepts known keys
43
+ and warns (does not error) on an unknown key, which may be newer than the CLI.
44
+
45
+ A theme customizes a widget through its own copy, created with
46
+ `POST /api/v202604/themes/<id>/native-widget-copies` and
47
+ `{"native_widget_key": "<key>"}`. The copy replaces the widget at every placement in the
48
+ theme and comes down on the next pull as `sections/fluid_native_<key>/index.liquid`.
49
+
50
+ ## Findings to surface
51
+
52
+ | You see | Severity | Fix |
53
+ | --- | --- | --- |
54
+ | A member page with a section-style schema (`name`, `settings`, `blocks`) or no `{% schema %}` | `should` | Rewrite to the placement shape above. Without it the builder can't edit the page. |
55
+ | A new `sections/fluid_native_<key>/index.liquid` written by hand | `blocker` | It is a plain section and does not replace the widget. Delete it and create the copy through the API. |
56
+ | Native widget reference with an unknown key (lint warning) | `should` | Check the key against the widget catalog; a typo renders nothing. |
57
+ | `template_path` outside `members_page/<name>/index.liquid` | `blocker` | Fluid refuses the manifest. Move the page template. |
58
+ | Page `slug` of `profile`, `orders`, `subscriptions`, `messaging`, `contacts`, `my-site`, `media`, `playlists`, `auth`, `api` or `accounts` | `blocker` | Those routes belong to the account host. Link to the system screen (`MembersScreen` menu target) or rename the page. |
59
+ | `layout_name` naming a layout the theme doesn't have | `blocker` | Add `layouts/<name>.liquid`, or use blank / `member` / `theme` / `none`. |
60
+ | A menu in `menus` that no site `menu_key` or `menu_references` entry uses | `blocker` | Fluid refuses unreferenced menus. Reference it or remove it. |
61
+ | `members_sites.json` deleted, or a file it references deleted | `blocker` | Push refuses both. To remove all member sites, keep the file with empty `sites`, `menus` and `menu_references`. |
62
+ | `account_page/`, `members_dashboard/` or `members_login/` folders, or references to them | `should` | Retired types. The CLI never uploads them and drops their references on push. Delete them; member home is a `members_page` on slug `/`. |
63
+
64
+ ## Checks
65
+
66
+ - [ ] Every `template_path` in `members_sites.json` exists locally as a text file
67
+ - [ ] Every member page uses the placement shape (`sections` + `order`)
68
+ - [ ] Native widgets are referenced by `fluid://native/widgets/<key>`, never by a hand-written `fluid_native_*` section
69
+ - [ ] No page slug collides with a system screen or reserved route
70
+ - [ ] Each site's layout resolves, and every layout it uses emits `content_for_header` and `content_for_layout`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fluid-app/fluid-cli-theme-dev",
3
- "version": "0.1.516",
3
+ "version": "0.1.518",
4
4
  "description": "Fluid CLI plugin for theme developer workflows — dev server, push, pull, init, crawl, compare",
5
5
  "files": [
6
6
  "dist",
@@ -21,7 +21,7 @@
21
21
  "access": "public"
22
22
  },
23
23
  "dependencies": {
24
- "@fluid-app/fluid-cli": "0.1.261",
24
+ "@fluid-app/fluid-cli": "0.1.263",
25
25
  "chalk": "^5.6.2",
26
26
  "chokidar": "^4.0.0",
27
27
  "commander": "^12.0.0",