@sudajs/cli 0.7.2 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudajs/cli",
-  "version": "0.7.2",
+  "version": "0.8.1",
   "type": "module",
   "bin": {
     "suda": "./bin/suda.js"
@@ -32,7 +32,7 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "zod": "^3.24.1",
-    "@sudajs/theme-engine": "2.0.3"
+    "@sudajs/theme-engine": "2.2.0"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.0",
@@ -47,9 +47,9 @@
     "typescript": "^5.7.2",
     "vite": "^7.3.3",
     "vitest": "^3.2.4",
-    "@suda/build-config": "0.0.0",
     "@suda/eslint-config": "0.0.0",
-    "@suda/tsconfig": "0.0.0"
+    "@suda/tsconfig": "0.0.0",
+    "@suda/build-config": "0.0.0"
   },
   "scripts": {
     "build": "tsup",

package/templates/theme/AGENTS.md

@@ -31,3 +31,99 @@ suda theme check
 ## AI metadata
 
 Every component and layout component should declare useful `ai.instructions`. Missing component-level instructions fail `suda theme check` and block publish.
+
+Use `visibleIf: ({ props }, { fields }) => boolean` for synchronous field visibility that depends on sibling props or resolved fields. Keep it pure and fast; use Puck `resolveFields` directly for heavier dynamic field changes. AI and MCP schemas expose `visibleIf` fields as dynamic visibility so agents know the editor surface can change with props.
+
+## Field authoring rules
+
+- Prefer Suda field helpers over generic text fields: use `url` for links and routes, `image` for images, `video` for videos, `media` for mixed media, `color` for colors, `icon` for icon names, `font` for font selections, `range` for bounded numbers, `spacing` for spacing tokens, and `menu` for navigation items.
+- Use `select` or `radio` when authors must choose from a fixed set of values. Keep option values stable and serializable.
+- Use `array` for repeatable items and `object` for grouped settings. Keep nested field names aligned with the prop shape and `defaultProps`.
+- For card grids, feature lists, pricing tables, logo walls, gallery grids, and any multi-column component, expose a `columns` prop with a `range` or `select` field and a sensible default.
+- Use `textarea` for multi-sentence copy and `text` only for short labels, headings, slugs, or plain strings that are not URLs/media/color/icon/font values.
+- Keep `fields`, `defaultProps`, and `render` in sync: every editor field should have a sensible default and render should tolerate omitted optional values.
+- Put editor-only controls in props when they change rendering, for example `showLogo`; pair dependent controls with `visibleIf` rather than hiding logic only in JSX.
+- Keep persisted props JSON-serializable. Do not store functions, React nodes, class instances, database ids for media, or environment-specific absolute filesystem paths.
+- Add optional field-level `ai.instructions`, `ai.required`, or `ai.exclude` when a prop needs generation guidance beyond its label and type.
+
+## Block slot authoring rules
+
+Prefer `blockSlots` when a section owns nested content that benefits from independent editor selection and configuration, such as hero actions, pricing cards, feature rows, stats, or timeline items. This is usually more editor-friendly than modeling those items as plain `array` / `object` fields because each local block can be selected and configured on its own in the visual editor. Keep ordinary section props in `fields`; `fields` is optional and does not need to list every prop.
+
+- Type the slot prop as Puck `Slot` and declare `blockSlots` with the same prop key. Non-slot props should stay in `fields` or nested `array` / `object` fields.
+- Define local block kinds under `blockSlots.<slotName>.blocks`. Local blocks support normal Suda fields, `label`, `defaultProps`, `render`, `metadata`, `inline`, `permissions`, and optional `ai`.
+- Do not add nested `blockSlots` or `cms` to local blocks. Block slots are one level deep in the theme authoring API.
+- Do not put the slot prop in the host component's `defaultProps`; use `defaultBlocks` on the slot instead.
+- Do not hand-write `id` in local block `defaultProps`, `defaultBlocks[].props`, or starter page nested block props. The editor/runtime owns block ids.
+
+Example:
+
+```tsx
+import type { Slot } from "@puckeditor/core";
+import type { SudaComponentConfig } from "@sudajs/theme-engine";
+
+type HeroProps = {
+  title?: string;
+  actions?: Slot;
+};
+
+export const Hero: SudaComponentConfig<HeroProps> = {
+  label: "Hero",
+  ai: {
+    instructions: "Primary page introduction with editable call-to-action blocks.",
+  },
+  fields: {
+    title: { type: "text", label: "Title" },
+  },
+  blockSlots: {
+    actions: {
+      label: "Actions",
+      blocks: {
+        button: {
+          label: "Button",
+          fields: {
+            label: { type: "text", label: "Label" },
+            href: { type: "url", label: "Link" },
+          },
+          defaultProps: {
+            label: "Get started",
+            href: "/contact",
+          },
+          render: ({ label, href }) => <a href={href}>{label}</a>,
+        },
+      },
+      defaultBlocks: [{ kind: "button" }],
+    },
+  },
+  defaultProps: {
+    title: "Build with SudaCloud",
+  },
+  render: ({ title, actions: Actions }) => (
+    <section>
+      <h1>{title}</h1>
+      <Actions />
+    </section>
+  ),
+};
+```
+
+Starter page data should use the public host component type and a standard slot array on the slot prop. Use local block `kind` values as nested `type` values.
+
+```ts
+{
+  type: "Hero",
+  props: {
+    id: "Hero-1",
+    title: "Welcome",
+    actions: [
+      {
+        type: "button",
+        props: {
+          label: "Contact us",
+          href: "/contact",
+        },
+      },
+    ],
+  },
+}
+```

package/templates/theme/README.md

@@ -23,6 +23,10 @@ pnpm validate
 
 Theme-local assets live in `src/assets/`. The starter hero exposes a Logo field that defaults to `src/assets/suda-logo.svg`, so you can replace it with your own brand image or choose a different image in the editor.
 
+Fields can use `visibleIf: ({ props }, { fields }) => boolean` for synchronous dynamic visibility. The starter hero shows this by hiding the Logo picker when `showLogo` is false. Suda converts `visibleIf` to Puck `resolveFields` during normalization, and the generated AI/MCP section schema marks those fields as dynamically visible.
+
+When adding fields, prefer purpose-built Suda field types over generic text inputs: use `url` for links, `image` / `video` / `media` for media, `color` for colors, `icon` for icon names, `range` for bounded numbers, `spacing` for spacing tokens, `menu` for navigation, `select` / `radio` for fixed choices, and `array` / `object` for structured values. Multi-column sections such as card grids should expose a `columns` prop.
+
 ## Publish
 
 ```bash

package/templates/theme/src/sections.tsx

@@ -6,6 +6,7 @@ import { themeAsset } from "./theme-asset.js";
 type FeatureItem = { title?: string; description?: string };
 type PuckExtras = { puck?: { metadata?: ThemeRenderMetadata } };
 type HeroProps = {
+  showLogo?: boolean;
   logo?: string;
   eyebrow?: string;
   title?: string;
@@ -16,6 +17,7 @@ type HeroProps = {
 type FeatureGridProps = {
   title?: string;
   description?: string;
+  columns?: number;
   features?: FeatureItem[];
 };
 type TestimonialProps = {
@@ -40,14 +42,27 @@ export const Hero: SudaComponentConfig<HeroProps> = {
       "Use at most once per page. Do not use for ordinary section headings or article content.",
   },
   fields: {
-    logo: { type: "image", label: "Logo" },
+    showLogo: {
+      type: "radio",
+      label: "Show logo",
+      options: [
+        { label: "Show", value: true },
+        { label: "Hide", value: false },
+      ],
+    },
+    logo: {
+      type: "image",
+      label: "Logo",
+      visibleIf: ({ props }) => props.showLogo !== false,
+    },
     eyebrow: { type: "text", label: "Eyebrow" },
     title: { type: "text", label: "Title" },
     description: { type: "textarea", label: "Description" },
     primaryLabel: { type: "text", label: "Primary button label" },
-    primaryHref: { type: "text", label: "Primary button link" },
+    primaryHref: { type: "url", label: "Primary button link" },
   },
   defaultProps: {
+    showLogo: true,
     logo: themeAsset("assets/suda-logo.svg"),
     eyebrow: "New theme",
     title: "Build with SudaCloud",
@@ -55,11 +70,20 @@ export const Hero: SudaComponentConfig<HeroProps> = {
     primaryLabel: "Get started",
     primaryHref: "#contact",
   },
-  render: ({ logo, eyebrow, title, description, primaryLabel, primaryHref, puck }) => {
+  render: ({
+    showLogo = true,
+    logo,
+    eyebrow,
+    title,
+    description,
+    primaryLabel,
+    primaryHref,
+    puck,
+  }) => {
     const logoSrc = resolveAsset(puck?.metadata, logo);
     return (
       <section className="__SUDA_THEME_KEY__-section __SUDA_THEME_KEY__-hero">
-        {logoSrc ? (
+        {showLogo && logoSrc ? (
           <img className="__SUDA_THEME_KEY__-hero-logo" src={logoSrc} alt="" />
         ) : null}
         <p className="__SUDA_THEME_KEY__-eyebrow">{eyebrow}</p>
@@ -84,6 +108,7 @@ export const FeatureGrid: SudaComponentConfig<FeatureGridProps> = {
   fields: {
     title: { type: "text", label: "Title" },
     description: { type: "textarea", label: "Description" },
+    columns: { type: "range", label: "Columns", min: 2, max: 4, step: 1 },
     features: {
       type: "array",
       label: "Features",
@@ -96,17 +121,21 @@ export const FeatureGrid: SudaComponentConfig<FeatureGridProps> = {
   defaultProps: {
     title: "Everything you need to launch",
     description: "Use this section to explain the core value of the project.",
+    columns: 3,
     features: [
       { title: "Fast setup", description: "Start from a clean theme contract." },
       { title: "Visual editing", description: "Expose content fields through Puck." },
       { title: "Publish ready", description: "Build and publish with the Suda CLI." },
     ],
   },
-  render: ({ title, description, features = [] }) => (
+  render: ({ title, description, columns = 3, features = [] }) => (
     <section className="__SUDA_THEME_KEY__-section">
       <h2>{title}</h2>
       <p>{description}</p>
-      <div className="__SUDA_THEME_KEY__-grid">
+      <div
+        className="__SUDA_THEME_KEY__-grid"
+        style={{ "--__SUDA_THEME_KEY__-columns": columns }}
+      >
         {features.map((feature: FeatureItem, index: number) => (
           <article className="__SUDA_THEME_KEY__-card" key={index}>
             <h3>{feature.title}</h3>
@@ -158,7 +187,7 @@ export const CallToAction: SudaComponentConfig<CallToActionProps> = {
     title: { type: "text", label: "Title" },
     description: { type: "textarea", label: "Description" },
     buttonLabel: { type: "text", label: "Button label" },
-    buttonHref: { type: "text", label: "Button link" },
+    buttonHref: { type: "url", label: "Button link" },
   },
   defaultProps: {
     title: "Ready to build your next page?",

package/templates/theme/src/styles.css

@@ -80,7 +80,7 @@
 }
 .__SUDA_THEME_KEY__-grid {
   display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  grid-template-columns: repeat(var(--__SUDA_THEME_KEY__-columns, 3), minmax(0, 1fr));
   gap: 16px;
   margin-top: 28px;
 }
@@ -106,3 +106,8 @@
   background: #ffffff;
   color: #111827;
 }
+@media (max-width: 760px) {
+  .__SUDA_THEME_KEY__-grid {
+    grid-template-columns: 1fr;
+  }
+}