@newlogic-digital/core 4.0.0-next.9 → 4.0.0-rc.10

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

@@ -0,0 +1,75 @@
+# Styling Guide
+
+## General
+
+- ALWAYS prefer Tailwind utilities before writing custom CSS.
+- Use custom CSS for defaults, complex states, or component-specific behavior that should NOT live in templates.
+- Follow nearby files before introducing a new styling pattern.
+- Prefer responsive utilities such as `sm:`, `md:`, and `lg:` in templates. Use `@custom-media` only when writing custom CSS.
+
+**Custom breakpoint example:**
+
+```css
+.my-component {
+    padding: 1rem;
+
+    @media (--media-lg) {
+        padding: 2rem;
+    }
+}
+```
+
+## UI Components
+
+- Winduum-based UI components live in `src/styles/components/(ui)/`.
+- UI component defaults belong in their CSS files, NOT in template utility piles.
+- Define base sizing, padding, radius, font defaults, and default colors in CSS for UI components.
+- In templates, only small layout utilities are allowed on UI components, such as width, flex, gap, order, or spacing adjustments.
+- Do NOT redefine a UI component's base look directly in templates.
+- Do NOT restyle existing `x-*` UI components from a large level CSS file when the change is really a button, badge, control, field, pagination, or other UI-component concern.
+- If a Figma page introduces a new shared UI look, extend the relevant file in `src/styles/components/(ui)/` instead of creating specific overrides from a parent component for that component.
+
+## Non-UI Components
+
+- Regular non-UI components SHOULD be styled entirely with Tailwind utilities in the template by default.
+- For non-UI components, prefer Tailwind even when the template gets longer. A longer utility-based template is still preferred over creating component CSS too early.
+- Create component CSS for non-UI components ONLY when there is styling logic that genuinely should not live in the template, such as complex selectors, state relationships, pseudo-element composition, browser-specific behavior, or similarly non-trivial logic that cannot be expressed cleanly with Tailwind utilities alone.
+- Do NOT create component CSS just to group utilities, shorten markup, or move ordinary layout/spacing/typography rules out of the template.
+- Treat non-UI component CSS as a true last resort. It should be used only in genuinely exceptional cases, not as a convenience or organizational preference.
+- If a non-UI component reaches that exceptional threshold and needs CSS, follow the `data-part` pattern for internal styling instead of inventing extra internal class names.
+- Avoid large level CSS files that absorb layout, typography, and UI and other component styling at the same time. If a page file starts becoming the source of truth for `x-*` components, move that logic back into `(ui)` CSS and keep the page mostly utility-driven.
+
+## Tokens And Units
+
+- ALWAYS use theme tokens such as `text-primary`, `bg-main`, or `text-body-foreground` before raw color values.
+- If the design needs a new default token, update `src/styles/theme/main.css`.
+- Do NOT use `px` units, except `1px` or `2px` borders when needed.
+
+## Component Parts
+
+- This section applies primarily to non-UI components when CSS is truly unavoidable.
+- Use `data-part` for stylable internal parts.
+- Do NOT create extra part class names such as `x-card-header` or `x-hero-content` when `data-part` is sufficient.
+- For non-UI components, `data-part` is the required internal styling pattern whenever an exceptional CSS case is justified.
+
+**Preferred part pattern:**
+
+```html
+<div class="x-my-component">
+    <div data-part="header">...</div>
+    <div data-part="content">...</div>
+</div>
+```
+
+```css
+.x-my-component {
+    [data-part="header"] {
+        /* complex styles */
+    }
+}
+```
+
+## Winduum Extensions
+
+- Inspect the imported Winduum files in the component CSS to see which custom properties are available.
+- Extend Winduum components through their existing imports and local CSS layers instead of re-implementing them from scratch.

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,20 +1,21 @@
 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
-    juice?: import('@vituum/vite-plugin-juice').PluginUserConfig
-    send?: import('@vituum/vite-plugin-send').PluginUserConfig
-    tailwindcss?: import('@vituum/vite-plugin-tailwindcss').PluginUserConfig
-    latte?: import('@vituum/vite-plugin-latte').PluginUserConfig
-    twig?: import('@vituum/vite-plugin-twig').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
 }