@newlogic-digital/core 4.0.0-rc.1 → 4.0.0-rc.10

package/skills/newlogic-ui/references/templating-guide.md

@@ -0,0 +1,106 @@
+# Templating Guide
+
+## Layout
+
+- Use `src/templates/layouts/default.latte` unless the user explicitly asks for another layout.
+- Do NOT create a custom layout when the default layout already supports the change.
+
+## Data Sources
+
+- Global data lives in `src/data/main.json`.
+- In this repo, global layout sections are typically defined through `head` and `foot` arrays in `src/data/main.json`.
+- Page data lives in `src/pages/*.json` and inherits global data.
+- Section rendering is handled through `src/templates/utils/sections.latte`.
+- Components referenced from page JSON are passed as `$control`.
+- In this repo, `src/pages/*.json` is the composition layer for whole pages. Prefer assembling a page there instead of creating a wrapper `*Page.latte` component that just nests the entire page structure.
+- Preserve the existing `head` and `foot` layout structure unless the user explicitly asks to change the layout contract.
+- If a Figma page includes a site header or site footer, implement those designs in the existing `components/header/Header.latte` and `components/footer/Footer.latte` flow rather than moving them into `body`.
+
+**Global layout data example:**
+
+```json
+{
+  "head": [
+    { "src": "components/header/Header.latte" }
+  ],
+  "foot": [
+    { "src": "components/footer/Footer.latte" }
+  ]
+}
+```
+
+**Layout asset access example:**
+
+```latte
+<link n:foreach="$assets->css->all as $url" href="{$url|asset}" rel="stylesheet">
+<script src="{$assets->js->main|asset}" type="module"></script>
+```
+
+## JSON Rules
+
+- Do NOT store CSS class strings in JSON.
+- JSON should contain semantic values and content, NOT presentation classes.
+- If a template depends on an optional flag such as `active`, `dropdown`, or variant switches, define that flag explicitly in JSON.
+- Keep repeated global UI data in `src/data/main.json` rather than duplicating it across page JSON files.
+
+## Latte Rules
+
+- Prefer direct access to existing variables such as `$control` and global layout data.
+- Keep ad hoc `{var ...}` usage to a minimum.
+- Use `{default}` for optional fallback values when needed.
+- Do NOT combine `class` and `n:class` on the same element. Use one `n:class` expression that includes the base classes.
+
+**`n:class` pattern:**
+
+```latte
+<a n:class="'base classes ' . ($isActive ? 'active' : 'idle')">Link</a>
+```
+
+**`{default}` pattern:**
+
+```latte
+{default $disabled = false}
+```
+
+## Components
+
+- Put reusable page sections in `src/templates/components/`.
+- Keep component file names in PascalCase.
+- If a component is rendered from page JSON, assume `$control` is the primary input object unless the existing local pattern clearly does something else.
+- Match the current folder conventions such as `(sections)`, `(ui)`, `header/`, `footer/`, `dialog/`, or `cookieconsent/` before introducing a new grouping.
+- Do NOT create a monolithic page wrapper component when the page can be expressed as multiple body sections in JSON.
+- Prefer one component per visible section or repeated block, then compose those sections from `src/pages/*.json`.
+- If an existing component already matches the Figma element, reuse that component instead of creating a specific duplicate.
+- If a Figma element maps to an existing `(ui)` component such as `Pagination.latte`, `Button`, `Dialog`, `Toast`, or similar, extend that existing component if needed; do NOT create parallel specific versions like `ArticlesPagination.latte` unless the user explicitly asks for a separate component.
+
+**Page JSON to component flow:**
+
+```json
+{
+  "body": [
+    {
+      "src": "components/HeroSection.latte",
+      "heading": "Welcome",
+      "buttonText": "Get Started"
+    }
+  ]
+}
+```
+
+```latte
+{foreach $sections as $section}
+    {include ('../' . $section->src), control => $section}
+{/foreach}
+```
+
+```latte
+<section class="x-hero-section">
+    <h1 n:if="isset($control->heading)">{$control->heading}</h1>
+</section>
+```
+
+**Direct include pattern:**
+
+```latte
+{include 'components/Button.latte', text: 'Click me'}
+```

package/skills/newlogic-ui/references/theme-guide.md

@@ -0,0 +1,23 @@
+# Theme Guide
+
+## Theme Files
+
+- Main website theme tokens live in `src/styles/theme/main.css`.
+- Keep website theme defaults in `@theme`.
+- Extend the existing token system before inventing component-local hardcoded values.
+
+## Local Rules
+
+- ALWAYS prefer semantic tokens over raw values in templates and components.
+- If the design introduces a new shared color, spacing, or layout default, add or adjust the token in `src/styles/theme/main.css`.
+- Reuse existing tokens such as `primary`, `main`, `body`, and status colors before creating new ones.
+- Keep theme changes centralized instead of scattering hardcoded values across multiple component files.
+
+**Common token usage:**
+
+```html
+<div class="bg-primary text-primary-foreground">Primary Button</div>
+<div class="bg-main text-main-foreground">Dark Section</div>
+<div class="max-w-(--container-width)">Constrained content</div>
+<div class="x-button accent-main">Primary text</div>
+```

package/src/createEslintStylisticConfig.js

@@ -0,0 +1,16 @@
+import stylistic from '@stylistic/eslint-plugin'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const outputPath = path.resolve(scriptDir, '..', 'eslint-stylistic.json')
+
+fs.writeFileSync(outputPath, JSON.stringify({
+  rules: {
+    ...stylistic.configs.recommended.rules,
+  },
+  jsPlugins: [
+    '@stylistic/eslint-plugin',
+  ],
+}, null, 2))

package/src/linkAgentSkills.js

@@ -0,0 +1,83 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { styleText } from 'node:util'
+import { fileURLToPath } from 'node:url'
+import { getPackageInfo } from 'vituum/utils/common.js'
+
+const IS_WIN32 = process.platform === 'win32'
+const { name } = getPackageInfo(new URL('../package.json', import.meta.url).href)
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const packageRoot = path.resolve(scriptDir, '..')
+const sourceSkillsDir = path.join(packageRoot, 'skills')
+const projectRoot = process.env.INIT_CWD ? path.resolve(process.env.INIT_CWD) : null
+
+function isSameSymlinkTarget(targetPath, expectedSourcePath) {
+  const currentTarget = fs.readlinkSync(targetPath)
+  const resolvedTarget = path.resolve(path.dirname(targetPath), currentTarget)
+
+  return resolvedTarget === expectedSourcePath
+}
+
+function getExistingTargetStat(targetPath) {
+  try {
+    return fs.lstatSync(targetPath)
+  }
+  catch (error) {
+    if (error?.code === 'ENOENT') {
+      return null
+    }
+
+    throw error
+  }
+}
+
+function createSkillSymlink(sourcePath, targetPath) {
+  const symlinkTarget = IS_WIN32
+    ? sourcePath
+    : path.relative(path.dirname(targetPath), sourcePath)
+  const symlinkType = IS_WIN32 ? 'junction' : 'dir'
+
+  fs.symlinkSync(symlinkTarget, targetPath, symlinkType)
+}
+
+if (!projectRoot || projectRoot === packageRoot || !fs.existsSync(sourceSkillsDir)) {
+  process.exit(0)
+}
+
+const targetSkillsDir = path.join(projectRoot, '.agents', 'skills')
+const skillEntries = fs.readdirSync(sourceSkillsDir, { withFileTypes: true })
+  .filter(entry => entry.isDirectory())
+
+if (skillEntries.length === 0) {
+  process.exit(0)
+}
+
+fs.mkdirSync(targetSkillsDir, { recursive: true })
+
+let linkedCount = 0
+
+for (const entry of skillEntries) {
+  const sourcePath = path.join(sourceSkillsDir, entry.name)
+  const targetPath = path.join(targetSkillsDir, entry.name)
+  const targetStat = getExistingTargetStat(targetPath)
+
+  if (targetStat) {
+    if (!targetStat.isSymbolicLink()) {
+      console.warn(`${styleText(['cyan', 'bold'], name)} ${styleText('yellow', `Skipping skill "${entry.name}" because "${targetPath}" already exists and is not a symlink.`)}`)
+      continue
+    }
+
+    if (isSameSymlinkTarget(targetPath, sourcePath)) {
+      continue
+    }
+
+    fs.unlinkSync(targetPath)
+  }
+
+  createSkillSymlink(sourcePath, targetPath)
+  linkedCount += 1
+}
+
+if (linkedCount > 0) {
+  console.info(`${styleText(['cyan', 'bold'], name)} ${styleText('green', `Linked ${linkedCount} skill${linkedCount === 1 ? '' : 's'} into "${targetSkillsDir}".`)}`)
+}

package/stylelint-config.json

@@ -0,0 +1,16 @@
+{
+  "extends": [
+    "@stylistic/stylelint-config",
+    "stylelint-config-standard"
+  ],
+  "rules": {
+    "at-rule-no-unknown": [true, {"ignoreAtRules": ["layer", "tailwind", "theme", "utility", "variant", "custom-variant", "source"]}],
+    "length-zero-no-unit": [true, {"ignore": ["custom-properties"]}],
+    "number-max-precision": [4, { "ignoreProperties": "letter-spacing" }],
+    "property-no-unknown": [true, { "ignoreProperties": ["/^mso-/"]} ],
+    "import-notation": "string",
+    "media-feature-range-notation": null,
+    "nesting-selector-no-missing-scoping-root": null,
+    "no-invalid-position-declaration": null
+  }
+}

package/types/index.d.ts

@@ -1,23 +1,21 @@
-import {HeroiconsOptions} from "@newlogic-digital/vite-plugin-heroicons";
-
 interface Input {
-    assets?: string[]
-    pages?: string[]
-    emails?: string[]
+  assets?: string[]
+  pages?: string[]
+  emails?: string[]
 }
 
 export interface PluginUserConfig {
-    mode?: 'development' | 'production' | 'emails' | string
-    format?: string[]
-    input?: Input
-    cert?: string
-    codeSplitting?: import('rolldown').OutputOptions['codeSplitting']
-    vituum?: import('vituum').UserConfig,
-    css?: import('vite').CSSOptions
-    cssInline?: import('@vituum/vite-plugin-css-inline').PluginUserConfig
-    send?: import('@vituum/vite-plugin-send').PluginUserConfig
-    tailwindcss?: import('@tailwindcss/vite').PluginOptions
-    latte?: import('@vituum/vite-plugin-latte').PluginUserConfig
-    twig?: import('@vituum/vite-plugin-twig').PluginUserConfig
-    heroicons?: import('@newlogic-digital/vite-plugin-heroicons').HeroiconsOptions
-}
+  mode?: 'development' | 'production' | 'emails' | string
+  format?: string[]
+  input?: Input
+  cert?: string
+  codeSplitting?: import('rolldown').OutputOptions['codeSplitting']
+  vituum?: import('vituum').UserConfig
+  css?: import('vite').CSSOptions
+  cssInline?: import('@vituum/vite-plugin-css-inline').PluginUserConfig
+  send?: import('@vituum/vite-plugin-send').PluginUserConfig
+  tailwindcss?: import('@tailwindcss/vite').PluginOptions
+  latte?: import('@vituum/vite-plugin-latte').PluginUserConfig
+  twig?: import('@vituum/vite-plugin-twig').PluginUserConfig
+  heroicons?: import('@newlogic-digital/vite-plugin-heroicons').HeroiconsOptions
+}