@fluid-app/fluid-cli-theme-dev 0.1.63 → 0.1.64

package/dist/skills/themes-review/references/setting-types.md

@@ -9,112 +9,171 @@
 - Visual & media
 - Layout
 - Organization
-- Resource — single
-- Resource — list (multiple)
+- Resource — resolved by Fluid
+- Resource — unresolved pickers
 - Common type mistakes — find and fix
 
 
-These are the canonical setting types. **Any `type:` value not in this list is rejected by the validator** (`fluid theme lint --json`).
+These are the canonical setting types. **Any `type:` value not in this list is rejected by the validator** (`fluid theme lint --json`). "Saves" is what Liquid receives in `section.settings.<id>` / `block.settings.<id>`.
+
+Section and block settings render the same control for each type, with one exception: blocks do not accept `image` (the block panel shows the word "Unknown"). Use `image_picker`. Section and block controls ignore `unit` and `placeholder`.
 
 ### Input
 
-| `type`          | Stores      | Notes                                                     |
-| --------------- | ----------- | --------------------------------------------------------- |
-| `text`          | string      | Single-line.                                              |
-| `plaintext`     | string      | Single-line, no formatting allowed.                       |
-| `textarea`      | string      | Multi-line, no formatting.                                |
-| `richtext`      | HTML string | WYSIWYG. **Render with `{{ value }}` — do not `escape`.** |
-| `rich_text`     | HTML string | Alias for `richtext`. Prefer `richtext`.                  |
-| `html`          | HTML string | Raw HTML editor. Same render rule as `richtext`.          |
-| `html_textarea` | HTML string | Multi-line raw HTML. Same render rule.                    |
-| `url`           | string      | Validated URL input.                                      |
+| `type`                              | Saves         | Notes                                                                                                                                                 |
+| ----------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plaintext`                         | string        | Single-line input, no formatting. **The only plain-text type in section/block schemas** — use it for anything that lands in an attribute, CSS value, URL, or script. |
+| `text`                              | HTML fragment | Compact rich-text editor: bold, italic, underline, strikethrough, links, alignment, text styles, and a variable picker. Render raw; do not `escape`.   |
+| `textarea`, `richtext`, `rich_text` | HTML fragment | Full rich-text editor: everything in `text` plus lists, code blocks, images, indentation. Render raw inside a block element (`<div>`, not `<p>`).    |
+| `html`, `html_textarea`             | HTML string   | Raw HTML textarea. Render raw.                                                                                                                        |
+| `url`                               | string        | URL field with a picker for store destinations (pages, products, collections, …).                                                                     |
+
+The variable picker inserts Liquid such as `{{ company.name }}` into the saved HTML; Fluid renders Liquid in saved setting values before the template reads them.
+
+> **Global settings differ.** In `config/settings_schema.json` the Theme panel renders `text` as a **plain input** and `textarea` as a compact rich-text editor, and it has no `plaintext`. So a global `settings.<id>` of type `text` is a plain string — escape it like any other plain string. Only section and block `text` settings save HTML.
 
 ### Number & selection
 
-| `type`     | Required extras                       | Notes                                                           |
-| ---------- | ------------------------------------- | --------------------------------------------------------------- |
-| `range`    | `min`, `max`, `step`                  | Slider. Optional `unit`.                                        |
-| `number`   | —                                     | Free numeric input (no slider). Prefer `range` when bounded.    |
-| `select`   | `options` array of `{ value, label }` | Dropdown.                                                       |
-| `radio`    | `options` array of `{ value, label }` | Radio group.                                                    |
-| `checkbox` | —                                     | Boolean. **Always set `default:`** so the value is never `nil`. |
+| `type`     | Saves                               | Notes                                                                                                      |
+| ---------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `range`    | number                              | Slider. `min`/`max`/`step` fall back to `0`/`100`/`1` when missing — always set them.                      |
+| `number`   | number, or `""` when cleared        | Free numeric field. Optional `min`/`max`/`step` clamp entries. Give it a Liquid fallback (`\| default: 0`). |
+| `select`   | the option `value`, **as a string** | `options`: array of `{ "label", "value" }`, or an option-group ID string.                                  |
+| `radio`    | the option `value`, **as a string** | Segmented buttons. Same `options` shape as `select`.                                                       |
+| `checkbox` | `true` / `false`                    | **Always set `default:`.**                                                                                 |
 
 ### Visual & media
 
-Render `image` / `image_picker` / `video_picker` / `media_picker` values with the `media_tag` filter, not a hand-rolled `<img>`/`<video>` — see [Media rendering](media-tag.md).
-
-| `type`             | Notes                                                             |
-| ------------------ | ----------------------------------------------------------------- |
-| `color`            | Single color picker.                                              |
-| `color_background` | Same as `color`, semantic name for fills.                         |
-| `font`             | Font family.                                                      |
-| `font_picker`      | Font family with Google Fonts + system fonts.                     |
-| `image`            | Single image.                                                     |
-| `image_picker`     | Single image. Prefer `image_picker` in new code (clearer intent). |
-| `video_picker`     | Single video.                                                     |
-| `media_picker`     | Image **or** video — use when both are acceptable.                |
-| `text_alignment`   | left / center / right control.                                    |
+Render `image` / `image_picker` / `video_picker` values with the `media_tag` filter, not a hand-rolled `<img>`/`<video>` — see [Media rendering](media-tag.md). A `media_picker` needs a branch: when `fluid_media_id` is positive the value is a Fluid media item, which must render as `<fluid-media-widget>` to keep its embed behavior (popover, inline shopping, CTAs); only a plain file (`fluid_media_id` `0` or absent) goes through `media_tag`. Compare with `> 0` — Liquid treats `0` as true.
+
+| `type`                  | Saves                                                       | Notes                                                                                                                                         |
+| ----------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `color`                 | color string (`#e7f0ff`)                                    | Section/block colors are plain strings. A global `settings.<color>` from `config/settings_schema.json` is a color value with `.rgb`, `.hue`, … |
+| `color_background`      | color string or `linear-gradient(...)`                      | **Not the same as `color`** — supports gradients. Apply with `background:`, never `background-color:`.                                         |
+| `font_picker`, `font`   | the option `value` (CSS font family)                        | Offers the fonts in `options` (array or option group); without options, only system fonts.                                                    |
+| `image_picker`, `image` | image URL string                                            | `image` works in sections only. Prefer `image_picker`.                                                                                        |
+| `video_picker`          | video URL string                                            |                                                                                                                                               |
+| `media_picker`          | object `{ url, fluid_media_id, embed_type, embed_settings }` | Image **or** video plus embed options. Read `.url`. A positive `fluid_media_id` is a Fluid media item (render `<fluid-media-widget>`).      |
+| `text_alignment`        | `left`, `center`, or `right`                                | Defaults to `left`. No `justify`.                                                                                                             |
+
+All three pickers get an editor-managed companion setting `<id>_alt` holding the alt text. Do not declare it; read it: `media_tag: alt: section.settings.<id>_alt`.
+
+Pass the merchant's saved embed options through to the widget, or the embed ignores them. `embed_settings` can be missing, so each attribute is conditional:
+
+| `embed_settings` key | Widget attribute |
+| --- | --- |
+| `autoOpen` | `auto-open="true"` |
+| `width`, `height` (pixel numbers) | `width="<n>px"`, `height="<n>px"` — only when `responsive` is `false`; a responsive embed fills its container |
+| `hideCta` | `cta-options-manual-override='{"type":"cart","enabled":false}'` (hides the CTA panel) |
+| `responsive` | No widget attribute. The widget is responsive unless it has an explicit `width`/`height`, so a fixed-size embed is expressed by emitting the dimensions above — `responsive="false"` would be ignored |
+| `fairShareVisible` | No widget attribute |
+
+```liquid
+{%- assign media = section.settings.banner_media -%}
+{%- if media != blank and media.url != blank -%}
+  {%- if media.fluid_media_id > 0 -%}
+    {%- assign embed = media.embed_settings -%}
+    <fluid-media-widget
+      media-id="{{ media.fluid_media_id }}"
+      embed-type="{{ media.embed_type | default: 'default' }}"
+      {% if embed.autoOpen %}auto-open="true"{% endif %}
+      {% if embed.responsive == false and embed.width != blank %}width="{{ embed.width }}px"{% endif %}
+      {% if embed.responsive == false and embed.height != blank %}height="{{ embed.height }}px"{% endif %}
+      {% if embed.hideCta %}cta-options-manual-override='{"type":"cart","enabled":false}'{% endif %}
+    ></fluid-media-widget>
+  {%- else -%}
+    {{ media | media_tag: alt: section.settings.banner_media_alt }}
+  {%- endif -%}
+{%- endif -%}
+```
 
 ### Layout
 
-| `type`             | Notes                           |
-| ------------------ | ------------------------------- |
-| `media_fit`        | cover / contain / fill control. |
-| `corner_radius`    | Border-radius preset.           |
-| `padding`          | Padding scale picker.           |
-| `border`           | Border preset.                  |
-| `gradient_overlay` | Gradient editor for overlays.   |
+| `type`             | Saves                                                                                             | Notes                                                                                             |
+| ------------------ | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `media_fit`        | `width`, `height`, or `fit`                                                                       | Dropdown labelled Width / Height / Fit to Media. **Not** cover/contain/fill.                      |
+| `corner_radius`    | `{ "tl", "tr", "br", "bl", "linked" }`                                                            | Each corner is a pixel number or a `var(--…)` preset reference (from the `corner_radius` group).   |
+| `padding`          | `{ "top", "bottom", "left", "right", "verticalLinked", "horizontalLinked" }`                      | Each side is a pixel number or a `var(--…)` preset reference (from the `padding` group).           |
+| `border`           | `{ "width": "2px", "color": "#d0d5dd" }`                                                          | Width includes its unit. Color can be a `color_schema` preset reference.                          |
+| `gradient_overlay` | `{ "enabled", "mode", "gradientType", "angle", "colors": [{ "color", "opacity", "position" }] }` | `mode`: `solid`/`gradient`; `gradientType`: `linear`/`radial`; opacity and position `0`–`100`.    |
 
-### Organization
+These are objects. **Never interpolate one directly into CSS** (`padding: {{ section.settings.padding }}` prints a hash). Read each key, and append `px` only to plain numbers:
+
+```liquid
+{%- assign pt = section.settings.padding.top -%}
+padding-top: {% if pt contains 'var' %}{{ pt }}{% else %}{{ pt | default: 0 }}px{% endif %};
+```
 
-| `type`   | Notes                                                 |
-| -------- | ----------------------------------------------------- |
-| `header` | Settings-panel divider. No `id`. Requires `content:`. |
+### Organization
 
-### Resource — single
+| `type`   | Notes                                                                                                         |
+| -------- | ------------------------------------------------------------------------------------------------------------- |
+| `header` | Starts a collapsible group in the settings panel. No `id`. Title from `content` (or `label`). Saves nothing. |
 
-These pick **one** resource. Settings hold the resource object/ID.
+`visible_if` (on any setting or header) hides the control in the editor only — the saved value still reaches Liquid. Syntax: `{{ section.settings.x == 'grid' }}`, with `==`, `!=`, `<`, `>`, `<=`, `>=`, `contains`, `and`/`or`, `not`, parentheses. Block settings can also read `block.settings.*`. The theme panel ignores it.
 
-`product`, `collection`, `category`, `blog`, `post`, `enrollment`, `enrollment_pack`, `variant`, `forms`, `media`, `link_list`
+### Resource — resolved by Fluid
 
-> **Naming oddity:** `products`, `collections`, `categories`, `posts`, `enrollments` also exist in the _single_ bucket of the canonical list. Read this as **legacy aliases**. Always pair "I want multiple resources" with the `_list` types below — that is the unambiguous, list-shaped contract.
+Fluid turns these into Liquid objects before the template reads them. An unset or unresolvable value is an **empty object** (`[]` for `product_list`), and Liquid treats an empty object as true — guard with `!= blank`, never a bare `{% if %}`.
 
-### Resource — list (multiple)
+| `type`            | Picker                | Liquid receives                                                   |
+| ----------------- | --------------------- | ----------------------------------------------------------------- |
+| `product`         | one product           | product                                                           |
+| `variant`         | one variant           | variant                                                           |
+| `collection`      | one collection        | collection                                                        |
+| `category`        | one category          | category                                                          |
+| `enrollment_pack` | one enrollment pack   | enrollment pack                                                   |
+| `link_list`       | one menu              | `{ title, handle, menu_items: [{ title, url, sub_menu_items }] }` |
+| `product_list`    | several products      | array of products                                                 |
+| `media`           | **no editor control** | medium (set through presets only)                                 |
 
-These pick **many** resources, stored as arrays. Always require `limit:`.
+### Resource — unresolved pickers
 
-`product_list`, `products_list`, `collection_list`, `collections_list`, `category_list`, `categories_list`, `posts_list`, `enrollment_list`, `enrollments_list`, `blog_list`, `blogs_list`, `post_list`, `enrollment_packs_list`
+These open a picker but **Liquid receives the saved ID, or an array of IDs** — no object, so `.title` / `.url` render empty.
 
-**Canonical names to prefer in new code:**
+| `type`                                                                        | Picker                   | Liquid receives              |
+| ----------------------------------------------------------------------------- | ------------------------ | ---------------------------- |
+| `post`, `blog`                                                                | one post                 | post ID                      |
+| `enrollment`                                                                  | one enrollment pack      | enrollment pack ID           |
+| `forms`                                                                       | one form                 | form ID                      |
+| `products`, `products_list`                                                   | several products         | array of product IDs         |
+| `collections`, `collections_list`, `collection_list`                          | several collections      | array of collection IDs      |
+| `categories`, `categories_list`, `category_list`                              | several categories       | array of category IDs        |
+| `posts`, `posts_list`, `post_list`, `blog_list`, `blogs_list`                 | several posts            | array of post IDs            |
+| `enrollments`, `enrollments_list`, `enrollment_list`, `enrollment_packs_list` | several enrollment packs | array of enrollment pack IDs |
 
-| Resource                | Use                     |
-| ----------------------- | ----------------------- |
-| Products (many)         | `product_list`          |
-| Collections (many)      | `collection_list`       |
-| Categories (many)       | `category_list`         |
-| Posts (many)            | `posts_list`            |
-| Enrollments (many)      | `enrollment_list`       |
-| Enrollment packs (many) | `enrollment_packs_list` |
-| Blogs (many)            | `blog_list`             |
+> **The plural types are multi-select, not aliases of the singular ones.** `products` saves an array of unresolved IDs; `product` saves one resolved product. For several resolved products use `product_list` — it is the **only** list type Fluid resolves.
 
-The `*s_list` variants (`products_list`, `collections_list`, etc.) exist but are duplicative — flag them as a `nit` and suggest the canonical `*_list` form.
+`limit:` caps any multi-select picker.
 
 ### Common type mistakes — find and fix
 
-| You see                                                   | What you do                                                                                               |
-| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `type: "text_area"`                                       | **`blocker`.** Use `textarea` (one word).                                                                 |
-| `type: "checkBox"` / `"image_pick"`                       | **`blocker`.** Mistyped — replace with the exact value from the lists above.                              |
-| `type: "product_list"` without `"limit":`                 | **`should`** — the field saves but has no defined cap. Always set `limit:`.                               |
-| `type: "range"` without `min`/`max`/`step`                | **`blocker`.** Slider UI breaks.                                                                          |
-| `type: "select"` or `"radio"` without `options:`          | **`blocker`.** Empty dropdown / radio group.                                                              |
-| `type: "checkbox"` without `default:`                     | **`should`.** Truthiness is ambiguous on first render. Set `default: false` (or `true`).                  |
-| `type: "richtext"` rendered as `{{ value                  | escape }}`                                                                                                | **`blocker`.** Double-escapes HTML — users see `&lt;p&gt;`. Render raw: `{{ value }}`. |
-| Setting missing `id` / duplicate `id`                     | **`blocker`.** The validator will reject.                                                                 |
-| Block missing `type` or `name`                            | **`blocker`.** Validator rejects. (`name` may be omitted only for `@app`, `@theme`, or named-block refs.) |
-| `"settings": { ... }` inside a block (object, not array)  | **`blocker`.** Validator rejects — must be an array.                                                      |
-| `{% section 'foo' %}` with no `sections/foo/index.liquid` | **`blocker`.** Validator rejects.                                                                         |
-| 2+ singular `product` settings playing the same role      | **`should`.** Collapse to one `product_list`. See [next section](#selector-heuristic--singular--list).    |
-| `products_list` instead of `product_list`                 | **`nit`.** Both valid; prefer `product_list`.                                                             |
+| You see | Severity | What you do |
+| --- | --- | --- |
+| `type: "text_area"`, `"checkBox"`, `"image_pick"` | **`blocker`** | Lint rejects it. Use the exact value from the tables above. |
+| Setting with no `id` | **`blocker`** | Lint does **not** catch a missing `id` (only empty or duplicate ones), but the editor cannot save the value. Add one. |
+| Duplicate `id` | **`blocker`** | Lint rejects it. |
+| Section/block `text` / `textarea` / `richtext` rendered with `\| escape` | **`blocker`** | Merchants see `&lt;strong&gt;`. Render raw: `{{ value }}`. |
+| Section/block `text` / `textarea` value inside an HTML attribute, CSS, URL, or `<script>` | **`blocker`** | It is HTML. Change the setting to `plaintext`. |
+| Global `settings.<id>` of type `text` rendered without `\| escape` | **`blocker`** | The Theme panel's `text` is a plain input, so its value is a plain string. Escape it (there is no `plaintext` in the Theme panel). |
+| `media_picker` rendered only through `media_tag` | **`blocker`** | A Fluid media item (`fluid_media_id > 0`) loses its embed. Branch to `<fluid-media-widget>` (see Visual & media). |
+| `<fluid-media-widget>` for a `media_picker` that ignores `embed_settings` | **`should`** | The merchant's auto-open, size, and hide-CTA choices are dropped. Map them to widget attributes (see Visual & media). |
+| `textarea` / `richtext` output wrapped in `<p>` | **`should`** | Lists and paragraphs inside `<p>` are invalid HTML. Use `<div>`. |
+| Resolved resource guarded with `{% if section.settings.product %}` | **`blocker`** | Always true (empty object). Use `!= blank`. |
+| `collection_list` / `category_list` / `posts_list` / … iterated as objects (`item.title`) | **`blocker`** | These hold IDs. Model each item as a block with a singular resolved setting, or look the IDs up. |
+| `padding` / `corner_radius` / `border` / `gradient_overlay` interpolated whole into CSS | **`blocker`** | Prints a hash. Read the keys (see Layout). |
+| `color_background` applied with `background-color:` | **`should`** | Gradients are dropped. Use `background:`. |
+| `image` setting in a block schema | **`blocker`** | Renders "Unknown" in the block panel. Use `image_picker`. |
+| `unit` on a section/block setting, or `placeholder` on any section/block setting | **`nit`** | Ignored by the editor. Use `info` for helper text. |
+| `type: "product_list"` without `limit:` | **`should`** | Set `limit:`. |
+| `type: "range"` without `min`/`max`/`step` | **`should`** | Falls back to 0–100 in steps of 1. Set real bounds. |
+| `type: "select"` or `"radio"` without `options:` | **`blocker`** | Empty control. |
+| `type: "checkbox"` without `default:` | **`should`** | Set `default: false` (or `true`). |
+| `disabled_on` in a section schema | **`should`** | Accepted but not applied. Use `enabled_on`. |
+| Block missing `type` or `name` | **`blocker`** | Lint rejects it. (`name` may be omitted only for `@app`, `@theme`, or named-block refs.) |
+| `"settings": { ... }` inside a block (object, not array) | **`blocker`** | Lint rejects it — must be an array. |
+| `{% section 'foo' %}` with no `sections/foo/index.liquid` | **`blocker`** | Lint rejects it. |
+| 2+ singular `product` settings playing the same role | **`should`** | Collapse to one `product_list`. See [the selector heuristic](../SKILL.md#selector-heuristic--singular--list). |
+| `products_list` instead of `product_list` | **`blocker`** | Not an alias: `products_list` saves unresolved IDs. Use `product_list`. |
 
 ---

package/dist/skills/themes-settings-schema/SKILL.md

@@ -44,14 +44,27 @@ The outer array is **grouped, not flat**. Each object with a `name` becomes one
 | Group `name` | Behaviour |
 | --- | --- |
 | `typography` | **The only group rendered as text-preset cards.** Any other name renders a flat list, however the settings are shaped. |
+| `color_schema`, `padding`, `corner_radius` | Flat list in the panel, but their settings are the presets that section and block color, padding, radius, border, and overlay controls offer. The names must match exactly. |
 | `custom_font_sizes`, `custom_colors` | Hidden from the panel. Builder-managed — presets a merchant creates from the rich-text toolbar land here. Do not hand-author them. |
-| `theme_info` | Metadata only, no `settings` array. |
+| `theme_info` | Not read by Fluid (a Shopify convention). The panel drops it because it has no settings. |
 | anything else | Flat list of controls, in schema order. |
 
 Two things the panel silently drops, which surprise most authors:
 
 - **A setting without a string `id`, `type` *and* `label` is discarded.** That includes every `{"type": "header", "content": "…"}` — headers render in section schemas but **not** in the Themes panel. Do not rely on them to separate groups of settings; use a real group instead.
-- **A group whose settings all get discarded is dropped entirely.**
+- **A group whose settings all get discarded is dropped entirely.** So is any entry without a `name` — a flat array of settings renders an empty panel.
+
+The panel renders fewer types than a section schema. Anything else shows a red **Unsupported setting type** message:
+
+| Category | Types the theme panel renders |
+| --- | --- |
+| Text | `text` (plain input), `textarea` (rich text), `url` |
+| Numbers and choices | `range`, `number`, `select`, `radio`, `checkbox` |
+| Color | `color`, `color_background` (solid colors only here) |
+| Typography | `font_picker`, `font_weight` |
+| Media | `image`, `image_picker`, `video_picker`, `media_picker` |
+
+Notably absent: `plaintext`, `font`, `html`, layout types (`padding`, `corner_radius`, …), and every resource picker. `visible_if` is ignored in the panel.
 
 ## Step 2 — Fonts and weights
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-theme-dev",
-  "version": "0.1.63",
+  "version": "0.1.64",
   "description": "Fluid CLI plugin for theme developer workflows — dev server, push, pull, init",
   "files": [
     "dist",
@@ -21,7 +21,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@fluid-app/fluid-cli": "0.1.34",
+    "@fluid-app/fluid-cli": "0.1.35",
     "chalk": "^5.6.2",
     "chokidar": "^4.0.0",
     "commander": "^12.0.0",

package/dist/dist-cli-preview/chunks/OrdersScreen-d4fJE_dm.js

@@ -1,9 +0,0 @@
-import { j as r } from "./account-screen-runtime-DxhJm6Qd.js";
-import { O as e } from "./OrdersScreen-CVEl9FnN.js";
-import { M as o } from "./MemberManagementProviders-DMwkh3JW.js";
-function t() {
-  return /* @__PURE__ */ r.jsx(o, { children: /* @__PURE__ */ r.jsx(e, {}) });
-}
-export {
-  t as OrdersScreen
-};