@sudajs/cli 0.13.1 → 0.13.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudajs/cli",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "type": "module",
   "bin": {
     "suda": "./bin/suda.js"
@@ -34,7 +34,7 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "zod": "^3.24.1",
-    "@sudajs/theme-engine": "5.1.1"
+    "@sudajs/theme-engine": "5.1.2"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.0",

package/templates/theme/AGENTS.md

@@ -71,6 +71,28 @@ one pass:
 8. Run `pnpm typecheck`, `pnpm lint`, `pnpm build`, and `pnpm validate` before
    handoff.
 
+Rendering fallback rule:
+
+- Defaults belong in `defaultProps`, starter page data, or CMS template data.
+  During render, read values directly from props. Do not add fallback display
+  values with `||`, `??`, or ternaries unless the fallback is truly required for
+  runtime safety.
+- This is wrong because render invents content that is not in props:
+
+```tsx
+<div>{props.title || "title"}</div>
+```
+
+- This is correct because render only displays the authored prop value:
+
+```tsx
+<div>{props.title}</div>
+```
+
+- Conditional rendering is fine when absence intentionally removes optional UI,
+  such as hiding an optional image, button, or eyebrow. Do not use conditional
+  rendering to substitute placeholder copy, labels, links, or menu items.
+
 Configure ordinary fields like this:
 
 ```ts
@@ -143,6 +165,145 @@ Field source of truth:
   `range`, `spacing`, `media`, `image`, `video`, and `posts`. These are valid
   in `fields` and are normalized by `@sudajs/theme-engine`.
 
+## Navigation and footer menus
+
+Navigation and footer menus must be typed arrays. Do not use the legacy menu
+field type, multiline text areas, or newline-delimited strings to model menus.
+Every link destination must use a `url` field type, never a plain `text` field.
+The `fields`, TypeScript props, and `defaultProps` data structures must match
+exactly.
+
+Navigation supports at most two levels:
+
+- `navItems[]`
+- `navItems[].submenu[]`
+
+Submenu items may contain only text and link fields. Do not add another nested
+submenu field inside `navItems[].submenu[]`; the field shape must make third
+levels impossible. An empty `submenu` array means the item is an ordinary
+top-level link.
+
+The simplest Navigation field shape is:
+
+```ts
+type NavSubItem = {
+  label: string;
+  href: string;
+};
+
+type NavItem = {
+  label: string;
+  href: string;
+  submenu: NavSubItem[];
+};
+
+const navItemsField = {
+  type: "array",
+  label: t("common.fields.navigationItems"),
+  getItemSummary: (item: NavItem) => item.label || "Navigation item",
+  defaultItemProps: {
+    label: "Home",
+    href: "/",
+    submenu: [],
+  },
+  arrayFields: {
+    label: {
+      type: "text",
+      label: t("common.fields.label"),
+    },
+    href: {
+      type: "url",
+      label: t("common.fields.link"),
+    },
+    submenu: {
+      type: "array",
+      label: t("common.fields.submenu"),
+      getItemSummary: (item: NavSubItem) => item.label || "Submenu item",
+      arrayFields: {
+        label: {
+          type: "text",
+          label: t("common.fields.label"),
+        },
+        href: {
+          type: "url",
+          label: t("common.fields.link"),
+        },
+      },
+    },
+  },
+};
+
+const defaultNavItems: NavItem[] = [
+  {
+    label: "Home",
+    href: "/",
+    submenu: [],
+  },
+  {
+    label: "Company",
+    href: "/company",
+    submenu: [
+      {
+        label: "About",
+        href: "/about",
+      },
+    ],
+  },
+];
+```
+
+Footer grouped menus use two array levels:
+
+- `columns[]`
+- `columns[].links[]`
+
+Use this prop shape and mirror it exactly in the field config and defaults:
+
+```ts
+type FooterColumn = {
+  title: string;
+  links: {
+    text: string;
+    url: string;
+  }[];
+};
+
+const footerColumnsField = {
+  type: "array",
+  label: t("common.fields.columns"),
+  getItemSummary: (item: FooterColumn) => item.title || "Footer column",
+  defaultItemProps: {
+    title: "Company",
+    links: [{ text: "About", url: "/about" }],
+  },
+  arrayFields: {
+    title: {
+      type: "text",
+      label: t("common.fields.title"),
+    },
+    links: {
+      type: "array",
+      label: t("common.fields.links"),
+      getItemSummary: (item: FooterColumn["links"][number]) => item.text || "Footer link",
+      defaultItemProps: {
+        text: "About",
+        url: "/about",
+      },
+      arrayFields: {
+        text: {
+          type: "text",
+          label: t("common.fields.label"),
+        },
+        url: {
+          type: "url",
+          label: t("common.fields.link"),
+        },
+      },
+    },
+  },
+};
+```
+
 Use these field patterns:
 
 ```ts
@@ -236,8 +397,6 @@ defaultProps: {
   download: "",
   icon: "sparkles",
   accentColor: "#2563eb",
-  font: "system",
-  links: [{ label: "Home", url: "/" }],
   spacing: "md",
   postList: { strategy: "featured", limit: 3 },
   badge: { label: "New", tone: "primary" },