@jahia/agentic 0.4.0 → 0.5.0

package/dist/copilot/.agents/skills/jahia-cnd-author/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: jahia-cnd-author
+description: Use when you need to write a Jahia CND content type definition and its TypeScript props interface. Receives a component spec and produces definition.cnd + types.ts + .properties labels with correct Jahia-specific syntax. Self-validates output before returning.
+context: fork
+argument-hint: "[business need]"
+---
+
+You are a Jahia content modeling specialist. You receive a business need, e.g. "I want to model a blog post". If used in interactive mode, you may ask for clarifications. Your job is to write correct `definition.cnd`, `types.ts`, and `.properties` files for Jahia components.
+
+## Content Modeling 101
+
+Jahia stores content in a tree structure. Each content node can define props (attached to the node itself) and child nodes (attached to the node as children). To reduce duplication, all nodes extend exactly one node type (usually `jnt:content`) and as many mixins as needed. Mixins are reusable sets of props and child nodes. Jahia ships with many native mixins, and you can define your own.
+
+The content model is pushed to Jahia as CND files. The content is displayed with JS and therefore requires a TypeScript interface for each node type. For each component, you need to provide a `definition.cnd` and a `types.ts` file.
+
+Unless told otherwise, the practice is to create one component per file, colocated with the type definition: `src/components/<name>/definition.cnd` and `./types.ts`.
+
+Project-wide mixins are declared in `settings/definitions.cnd`. Read this file first to see which mixins are already defined. Unless told otherwise, in an existing project, read all existing `.cnd` files to infer practices. When doing so, share a concise summary of your findings with the user and ask for confirmation before proceeding.
+
+## Step 1: establish the component requirements
+
+Understanding the needs correctly is mandatory to provide a good editing experience. The component may be contributed directly in pages, with the visual editor named Page Builder, or from content folders (content collections).
+
+If invoked as a sub-agent with a structured spec, skip to Step 2.
+
+In interactive mode, ask the user to confirm using this template:
+
+```
+Component: [PascalCase name]
+Description: [what it represents and how editors use it]
+Fields:
+  - name: type / i18n? / mandatory?
+Views: [default, card, fullPage, small — list all needed]
+Used where: [page area / content folder / child of <Parent>]
+Has repeatable children: [no / yes: describe them]
+```
+
+For decisions that aren't obvious — semantic vs. generic type, weakreference vs. child nodes, whether to extract a mixin — load [references/cnd-modeling-decisions.md].
+
+## Step 2: survey the project
+
+Before writing anything, understand the project context:
+
+```bash
+grep -h "^<" settings/definitions.cnd | head -1                             # namespace prefix
+grep "nsmix:pageComponent" settings/definitions.cnd                         # two-tier mixin?
+grep -rh "^\[" settings/definitions.cnd src/components/ 2>/dev/null | sort  # existing types
+```
+
+Note the namespace prefix. Check whether `nsmix:pageComponent` is declared — this means components dropped in page areas must extend `nsmix:pageComponent` rather than just `nsmix:component`. Share a concise summary of your findings and, in interactive sessions, ask for confirmation before writing.
+
+## Step 3: write `definition.cnd`
+
+Load reference files as needed for the syntax you require:
+
+- **File structure, namespace declarations, property anatomy** → [references/cnd-syntax.md]
+- **Which Jahia native mixins to extend** (`mix:title`, `jmix:mainResource`, etc.) → [references/cnd-jahia-mixins.md]
+- **String properties, choicelists, link pickers, richtext** → [references/cnd-string-selectors.md]
+- **Numeric, boolean, and date properties** → [references/cnd-numbers-dates.md]
+- **Child nodes, CTAs, orderable containers** → [references/cnd-child-nodes.md]
+- **Custom area types** (only relevant for page template types) → [references/cnd-area-types.md]
+
+Write component-level definitions to `src/components/<Category>/<Name>/definition.cnd`. Module-level mixins belong in `settings/definitions.cnd`.
+
+## Step 4: write `types.ts`
+
+Every CND property needs a corresponding TypeScript entry. Load [references/types-ts-mapping.md] for the full mapping rules, including the discriminated union pattern required for `j:linkType` properties.
+
+Write to `src/components/<Category>/<Name>/types.ts`.
+
+## Step 5: write `.properties` labels
+
+Editors see these labels in the content editor — every type name and every field needs an entry. Load [references/cnd-authoring-experience.md] for the naming conventions and icon patterns.
+
+Write to:
+- `settings/resources/<module>_en.properties`
+- `settings/resources/<module>_fr.properties` (use the English label as a placeholder if no translation is available)
+
+## Step 6: validate and report
+
+Before returning, verify:
+
+- [ ] Namespace prefix matches `settings/definitions.cnd`
+- [ ] All component types extend `nsmix:component` (or `nsmix:pageComponent` if page-area only)
+- [ ] No `- title (string) i18n mandatory` — use `mix:title` instead
+- [ ] No `imageAlt (string)` — the image node's `jcr:title` serves as alt text
+- [ ] Links use `choicelist[linkTypeInitializer]`, not a plain string
+- [ ] No declared `j:linknode` or `j:url` — Jahia injects these automatically
+- [ ] Every `autocreated` property has a `= 'value'` default
+- [ ] `jmix:hiddenType` used for structural types (never `jmix:studioOnly`)
+- [ ] Every CND property has a matching entry in `types.ts`
+- [ ] `.properties` labels written for every type and field
+
+Return **PASS** or **FAIL** with a list of specific issues.

package/dist/copilot/.agents/skills/jahia-cnd-author/references/cnd-area-types.md

@@ -0,0 +1,55 @@
+# CND Area Types — Quick Reference
+
+## Two-tier mixin system
+
+Define in `settings/definitions.cnd`:
+
+```cnd
+[nsmix:component]     > jmix:droppableContent, jmix:accessControllableContent mixin
+[nsmix:pageComponent] > nsmix:component mixin
+```
+
+| Component placement | Extend |
+|---|---|
+| Dropped in page areas (top-level) | `nsmix:pageComponent` |
+| Child of another component | `nsmix:component` |
+
+A component extending only `nsmix:component` cannot be dropped in areas that restrict to `nsmix:pageComponent`.
+
+## Custom area type
+
+Restricts what editors can drop into a given area:
+
+```cnd
+[nsnt:pageArea] > jnt:content, jmix:list, jmix:studioOnly orderable
+ + * (nsmix:pageComponent)
+```
+
+Use in a page template view:
+
+```tsx
+<Area name="main" nodeType="nsnt:pageArea" />
+```
+
+`jmix:studioOnly` on the area type prevents it from appearing in the content picker. Use `jmix:hiddenType` for regular component types that should be hidden.
+
+## Escape hatch component
+
+One component that accepts any droppable content, for advanced editors:
+
+```cnd
+[nsnt:contentStack] > jnt:content, nsmix:pageComponent
+ + * (jmix:droppableContent)
+```
+
+Editors add this to a page area, then drop any content type inside it.
+
+## Page templates vs sectioning components
+
+| Page templates | Sectioning components |
+|---|---|
+| Fixed vertical sections per template | Editor builds sections freely |
+| Simpler for less experienced editors | More flexible, preferred for evolving integrations |
+| Use when mockups define clear distinct layouts | Use for a single free-form template |
+
+Reuse area names across templates (e.g. always `main` and `sidebar`) so content is not lost when editors switch templates.

package/dist/copilot/.agents/skills/jahia-cnd-author/references/cnd-authoring-experience.md

@@ -0,0 +1,92 @@
+# CND Authoring Experience Reference
+
+## .properties labels and icons
+
+Required files for every content type:
+- `settings/resources/<module>_en.properties`
+- `settings/resources/<module>_fr.properties`
+
+```ini
+# Node type label
+ns_heroSection.label=Hero Section
+
+# Field labels
+ns_heroSection.subtitle.label=Subtitle
+ns_heroSection.backgroundImage.label=Background Image
+
+# Field tooltip
+ns_heroSection.subtitle.ui.tooltip=Optional subtitle text displayed below the heading.
+
+# Choicelist item labels (for resourceBundle choicelist)
+ns_heroSection.variant.primary=Primary
+ns_heroSection.variant.secondary=Secondary
+```
+
+Icon file: `settings/content-types-icons/<ns>_<typeName>.png`
+Free icons: https://www.flaticon.com/
+
+**Rules:**
+- Every node type must have a `.label` entry.
+- Every field must have a `.label` entry.
+- Choicelist options using `resourceBundle` must have a label per value.
+- Replace special characters (e.g. `:`) with `_` in the `.properties` key.
+
+---
+
+## Editor hints in views
+
+Use `renderContext.isEditMode()` to show a flat, non-interactive layout and hints in edit mode.
+
+```tsx
+({ slides }: Props, { renderContext }) => {
+  const isEdit = renderContext.isEditMode();
+  return isEdit ? (
+    <div>
+      <RenderChildren />
+      <p className={classes.hint}>Carousel — add or reorder slides here</p>
+    </div>
+  ) : (
+    <div className={classes.carousel}><RenderChildren /></div>
+  );
+};
+```
+
+Show inline validation hints:
+
+```tsx
+{renderContext.isEditMode() && value % 2 !== 0 && (
+  <p className="editor-hint">Value should be even for best visual result.</p>
+)}
+```
+
+---
+
+## import.xml recommendations
+
+Provide `import.xml` in every template set to pre-populate new sites:
+
+- A homepage with `j:isHomePage="true"` — required for sitemap and nav generation.
+- Offline folder structure with `jmix:systemNameReadonly` + `jmix:nolive`:
+  - "Offline pages/Models"
+  - "Offline pages/Drafts"
+  - "Offline pages/Archive"
+- Content folders matching your types (e.g. "Blog/Authors", "Blog/Posts").
+- Content restrictions on folders:
+  ```xml
+  jcr:mixinTypes="jmix:contributeMode" j:contributeTypes="ns:blogPost"
+  ```
+
+> `import.xml` only applies at site creation — changes do NOT update existing sites.
+
+---
+
+## jmix:visibleInContentTree
+
+Enables Page Builder visual editing inside content folders (not just list view).
+
+```cnd
+[ns:authorCollection] > jnt:content, jmix:visibleInContentTree
+ + * (ns:author)
+```
+
+Use when editors benefit from visual layout while editing content folder items.

package/dist/copilot/.agents/skills/jahia-cnd-author/references/cnd-child-nodes.md

@@ -0,0 +1,74 @@
+# CND Child Nodes
+
+## Syntax
+
+```cnd
++ childName (ns:type)            // named child — exactly one
++ childName (ns:type) multiple   // named child — list
++ * (ns:type)                    // any-name child of a specific type
++ * (jmix:droppableContent)      // open container — any droppable component
+```
+
+## When to use child nodes vs `weakreference multiple`
+
+| Use child nodes when… | Use `weakreference multiple` when… |
+|---|---|
+| Each item has multiple properties (label + link) | Each item is just a reference (a page, an image) |
+| Items have no life outside the parent | Items are managed elsewhere and reused |
+| You always create them together | Editors need to pick from existing content |
+
+## Repeatable CTA pattern
+
+**NEVER put `ctaText + ctaLink/ctaUrl` on the parent type as flat properties.**
+Model CTAs as child nodes — editors can then add multiple CTAs.
+
+```cnd
+// ✅ Correct — supports multiple CTAs
+[ns:heroSection] > jnt:content, nsmix:component, mix:title
+ - subtitle (string, richtext) i18n
+ - backgroundImage (weakreference, picker[type='image']) < jmix:image
+ + * (ns:heroCallToAction)
+
+[ns:heroCallToAction] > jnt:content, nsmix:component
+ - label (string) i18n mandatory
+ - j:linkType (string, choicelist[linkTypeInitializer]) mandatory
+
+// ❌ Wrong — forces exactly one CTA, editors can't add more
+[ns:heroSection] > jnt:content, nsmix:component
+ - ctaText (string) i18n
+ - ctaLink (string) i18n       // also wrong type for links
+```
+
+## Ordering
+
+Add `orderable` to the parent type when editors need to reorder children:
+
+```cnd
+[ns:featureList] > jnt:content, nsmix:component orderable
+ + * (ns:featureItem)
+```
+
+## Hidden structural nodes
+
+Child nodes that editors should never add manually (structural containers, auto-created nodes):
+
+```cnd
+[ns:heroSection] > jnt:content, nsmix:component, mix:title
+ + ctaContainer (ns:ctaContainer) autocreated
+
+[ns:ctaContainer] > jnt:content, jmix:hiddenType orderable
+ + * (ns:callToAction)
+```
+
+`jmix:hiddenType` hides a type from the Page Builder component picker.
+**Never use `jmix:studioOnly`** — it causes silent rendering issues.
+
+## Open container (accept any droppable)
+
+```cnd
+[ns:gridRow] > jnt:content, nsmix:component
+ - columns (long) = '3' autocreated mandatory < '1', '2', '3', '4'
+ + * (jmix:droppableContent)
+```
+
+`+ * (jmix:droppableContent)` accepts any component the editor can drop.