bernova 0.0.2

package/src/lib/generateCss/helpers/rulename/formatRuleName.utils.js

@@ -0,0 +1,163 @@
+/**
+ * CSS Rule Name Formatter for Bernova CSS Framework
+ *
+ * Handles CSS class name generation, registration, and formatting.
+ * Manages component-variant relationships and maintains class name registry.
+ */
+
+const { formattedStatKey } = require('../utils');
+
+/**
+ * Registers component and variant information in the CSS class registry
+ * Manages hierarchical component structure with variants and base classes
+ *
+ * @param {Object} register - CSS class registry to update
+ * @param {string} component - Component name to register
+ * @param {string} variant - Optional variant name for the component
+ * @param {string} mainComponent - Main parent component name
+ * @param {boolean} hasStyles - Whether component has actual CSS styles
+ * @param {string} prefix - CSS class prefix for namespacing
+ */
+const setRegister = ({
+  register,
+  component,
+  variant,
+  mainComponent,
+  hasStyles,
+  prefix,
+}) => {
+  // Initialize main component in register if not exists
+  if (!(mainComponent in register)) {
+    register[mainComponent] = {};
+  }
+
+  // Register base component (only if it has styles)
+  if (!(component in register[mainComponent])) {
+    register[mainComponent][component] = !!hasStyles && `${prefix}${component}`;
+  }
+
+  // Handle variant registration
+  if (!!variant) {
+    const v = `$_${formattedStatKey(variant)}`;
+
+    // Initialize variant section
+    if (!(v in register[mainComponent])) {
+      register[mainComponent][v] = {};
+    }
+
+    // Register component with variant
+    if (!(component in register[mainComponent][v])) {
+      const regWithoutVariant = !!register[mainComponent][component];
+      register[mainComponent][v][component] = regWithoutVariant
+        ? `${prefix}${component} ${prefix}${component}--${variant}` // Base + variant classes
+        : `${prefix}${component}--${variant}`; // Variant only
+    }
+  }
+};
+
+const getRuleNameSlices = ({ parentRule, key, prefix }) => {
+  //? extract the component from the parentRule
+  const [mainComponent, rest] = parentRule.split('--');
+  //? format the key to lower case and remove any brackets
+  const variant = rest && rest.length && rest.replace(/\[.*?\]/g, '');
+  //? format the key to lower case
+  const lowerKey = !!key && key.length && key.toLocaleLowerCase();
+
+  return {
+    mainComponent,
+    variant,
+    lowerKey,
+  };
+};
+
+const setForeignRegister = ({ ruleName, foreignRegister, register }) => {
+  const { mainComponent, variant } = getRuleNameSlices({
+    parentRule: ruleName,
+  });
+  if (!(mainComponent in register)) {
+    register[mainComponent] = {};
+  }
+  if (!!variant) {
+    const v = `$_${formattedStatKey(variant)}`;
+    if (!(v in register[mainComponent])) {
+      register[mainComponent][v] = {};
+    }
+    register[mainComponent][v] = {
+      ...register[mainComponent][v],
+      ...foreignRegister,
+    };
+  } else {
+    register[mainComponent] = {
+      ...register[mainComponent],
+      ...foreignRegister,
+    };
+  }
+};
+
+const formatRuleName = ({
+  key = '',
+  parentRule,
+  theRule,
+  hasStyles,
+  prefix,
+  register = {},
+}) => {
+  let className = '';
+  // Use theRule directly if provided (for pseudo-classes, selectors, etc.)
+  if (theRule) {
+    className = theRule;
+
+    // Generate base className from key if no parent rule exists
+  } else if (!parentRule) {
+    const cleanKey = key.toLocaleLowerCase().replace(/\[.*?\]/g, '');
+    className = `${prefix}${cleanKey}`;
+
+    if (key.length) {
+      setRegister({
+        register,
+        component: cleanKey,
+        mainComponent: cleanKey,
+        hasStyles,
+        prefix,
+      });
+    }
+  } else {
+    // Handle component with parent rule (nested components, variants)
+    const { mainComponent, variant, lowerKey } = getRuleNameSlices({
+      parentRule,
+      key,
+    });
+    const componentRegistered = mainComponent.replace(prefix, '');
+    const keyTarget = key.startsWith('_');
+
+    if (keyTarget) {
+      className = !!variant
+        ? `${mainComponent}_${lowerKey}--${variant}`
+        : `${mainComponent}_${lowerKey}`;
+
+      setRegister({
+        register,
+        mainComponent: componentRegistered,
+        component: `${componentRegistered}_${lowerKey}`,
+        variant,
+        hasStyles,
+        prefix,
+      });
+    } else if (lowerKey) {
+      className = `${mainComponent}--${lowerKey}`;
+
+      setRegister({
+        register,
+        mainComponent: componentRegistered,
+        component: componentRegistered,
+        variant: lowerKey,
+        hasStyles,
+        prefix,
+      });
+    }
+  }
+
+  return className;
+};
+
+module.exports = { formatRuleName, setForeignRegister };

package/src/lib/generateCss/helpers/utils/extractValues.utils.js

@@ -0,0 +1,44 @@
+const { cssProps } = require('../../../../constants/cssProps.js');
+
+/**
+ * Extracts CSS values from an object and formats them as CSS properties.
+ * Accepts both real CSS properties and custom properties defined in cssProps.
+ *
+ * @param {Object} styles - The object containing CSS values.
+ * @returns {string} The formatted CSS properties.
+ */
+const extractValues = ({ styles, dynamicValues }) => {
+  return Object.entries(styles)
+    .filter(([key]) => cssProps[key])
+    .map(([key, value]) => {
+      //* replace the js key for css property
+      const cssProperty = cssProps[key];
+      //* handle dynamic values
+      //? Count how many times '$' appears in the value
+      //? the length is always 1 more than the count of '$', becase the first values is a empty string
+      const varsFinded = String(value).split('$').length - 1;
+      const validValue = (() => {
+        if (!!dynamicValues && varsFinded > 0) {
+          return String(value)
+            .split(' ')
+            .reduce((acc, curr, idx) => {
+              if (curr in dynamicValues) {
+                if (idx > 0) {
+                  acc += ' ';
+                }
+                acc += dynamicValues[curr];
+              }
+              return acc;
+            }, '');
+        }
+        return value;
+      })();
+
+      return cssProperty === cssProps.$content
+        ? `${cssProperty}: '${validValue}';`
+        : `${cssProperty}: ${validValue};`;
+    })
+    .join(' ');
+};
+
+module.exports = { extractValues };

package/src/lib/generateCss/helpers/utils/formattedStatKey.utils.js

@@ -0,0 +1,43 @@
+/**
+ * Statistical Key Formatter for Bernova Analytics
+ *
+ * Normalizes CSS class names and component keys for statistical tracking.
+ * Removes special prefixes and standardizes separators to underscores.
+ */
+
+/**
+ * Formats a statistical key by normalizing separators and removing prefixes
+ * Used for consistent analytics and tracking across the CSS generation process
+ *
+ * @param {string} key - The key to format and normalize
+ * @returns {string} Normalized key with standardized separators
+ * @example
+ * formattedStatKey('$_component--name') → 'component_name'
+ * formattedStatKey('my-class__name') → 'my_class_name'
+ */
+const formattedStatKey = (key) => {
+  let k = key;
+
+  // Remove library-specific prefix
+  if (k.includes('$_')) {
+    k = k.replace('$_', '');
+  }
+
+  // Normalize all separators to underscores
+  if (k.includes(' ', '_')) {
+    k = k.replace(' ', '_');
+  }
+  if (k.includes('__')) {
+    k = k.replace('__', '_');
+  }
+  if (k.includes('--')) {
+    k = k.replace('--', '_');
+  }
+  if (k.includes('-')) {
+    k = k.replace('-', '_');
+  }
+
+  return k;
+};
+
+module.exports = { formattedStatKey };

package/src/lib/generateCss/helpers/utils/index.js

@@ -0,0 +1,15 @@
+const { extractValues } = require('./extractValues.utils');
+const { processCssWithPostcss } = require('./processCss.utils');
+const { separateStyles } = require('./separateStyles.utils');
+const {
+  validatePreviouslyExists,
+} = require('./validatePreviouslyExists.utils');
+const { formattedStatKey } = require('./formattedStatKey.utils');
+
+module.exports = {
+  extractValues,
+  processCssWithPostcss,
+  separateStyles,
+  validatePreviouslyExists,
+  formattedStatKey,
+};

package/src/lib/generateCss/helpers/utils/processCss.utils.js

@@ -0,0 +1,93 @@
+const postcss = require('postcss');
+const autoprefixer = require('autoprefixer');
+const cssnano = require('cssnano');
+const postcssPresetEnv = require('postcss-preset-env');
+// const combineMediaQuery = require('postcss-combine-media-query'); // <- this plugin is not used in the provided code
+const fontMagician = require('postcss-font-magician');
+const path = require('path');
+
+/**
+ * Processes CSS with PostCSS using the configuration in postcss.config.js.
+ *
+ * @param {string} css - The CSS to process.
+ * @param {boolean} [minified=false] - Whether to minify the CSS.
+ * @param {string} [prefix=''] - The prefix to add to :root and all classes.
+ * @param {Object} fonts - The fonts configuration.
+ * @returns {Promise<string>} The processed CSS.
+ */
+const processCssWithPostcss = async (
+  css,
+  minified = false,
+  prefix = '',
+  fonts = {}
+) => {
+  const plugins = [
+    postcssPresetEnv({
+      stage: 0,
+      autoprefixer: { grid: true },
+      features: {
+        'custom-properties': false, // <- Disable CSS variable resolution
+      },
+    }),
+    autoprefixer({
+      overrideBrowserslist: [
+        '> 1%',
+        'last 2 versions',
+        'Firefox ESR',
+        'not dead',
+      ],
+    }),
+    // combineMediaQuery,
+    fontMagician({
+      variants: fonts?.google?.reduce((acc, font) => {
+        acc[font.name] = font.weights.reduce((weights, weight) => {
+          weights[weight] = [];
+          return weights;
+        }, {});
+        return acc;
+      }, {}),
+      foundries: ['google', 'local'],
+      custom: fonts?.local?.reduce((acc, font) => {
+        acc[font.name] = {
+          variants: Object.keys(font.files).reduce((variants, weight) => {
+            variants[weight] = {
+              normal: {
+                url: {
+                  ttf: path.join('fonts', path.basename(font.files[weight])),
+                },
+              },
+            };
+            return variants;
+          }, {}),
+        };
+        return acc;
+      }, {}),
+    }),
+  ];
+
+  if (minified) {
+    plugins.push(
+      cssnano({
+        preset: 'default',
+      })
+    );
+  }
+
+  if (prefix) {
+    css = css.replace(/:root/g, `[data-theme='${prefix}']`);
+    css = css.replace(/\.([a-zA-Z_][\w-]*)/g, (match, p1) => {
+      if (css.includes(`@font-face`) || css.includes(`@import`)) {
+        return match;
+      }
+      return `[data-theme='${prefix}'] .${p1}`;
+    });
+  }
+
+  const result = await postcss(plugins).process(css, {
+    from: undefined,
+  });
+
+  return result.css;
+};
+
+module.exports = { processCssWithPostcss };

package/src/lib/generateCss/helpers/utils/separateStyles.utils.js

@@ -0,0 +1,43 @@
+/**
+ * Style Separation Utility for Bernova CSS Framework
+ *
+ * Separates CSS object properties into different categories:
+ * - Standard CSS properties (styles)
+ * - Library-specific properties (lib) - starting with $
+ * - Other properties (nested objects, pseudo-classes, etc.)
+ */
+
+const { cssProps } = require('../../../../constants/index.js');
+
+/**
+ * Separates a CSS object into different property categories
+ *
+ * @param {Object} css - CSS object to categorize
+ * @returns {Object} Separated properties: { styles, lib, other }
+ * @example
+ * separateStyles({
+ *   color: 'red',           // → styles
+ *   $dynamic: 'value',      // → lib
+ *   hover: { color: 'blue' } // → other
+ * })
+ */
+const separateStyles = (css) => {
+  const styles = {}; // Standard CSS properties
+  const other = {}; // Nested objects (pseudo-classes, selectors, etc.)
+  const lib = {}; // Library-specific properties (starting with $)
+
+  // Categorize each property based on its type and prefix
+  Object.entries(css).forEach(([key, value]) => {
+    if (key in cssProps) {
+      styles[key] = value; // Standard CSS properties
+    } else if (key.startsWith('$') && !!value) {
+      lib[key] = value; // Library-specific properties
+    } else {
+      other[key] = value; // Everything else (nested objects)
+    }
+  });
+
+  return { styles, lib, other };
+};
+
+module.exports = { separateStyles };

package/src/lib/generateCss/helpers/utils/validatePreviouslyExists.utils.js

@@ -0,0 +1,61 @@
+/**
+ * CSS File Validation Utility for Bernova
+ *
+ * Validates and handles existing CSS files during compilation.
+ * Supports partial compilation by preserving existing sections
+ * when generating foundation-only or component-only builds.
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const { compilerTypeValid } = require('../../../../constants');
+const {
+  extractDocFragment,
+} = require('../../../extractDocFragment/extractDocFragment.utils');
+
+/**
+ * Validates if CSS files exist and handles partial compilation preservation
+ *
+ * @param {Object} params - Validation parameters
+ * @param {string} params.stylesDir - Directory where CSS files are stored
+ * @param {string} params.compilerType - Type of compilation (full, foundationOnly, componentOnly)
+ * @param {string} params.name - Base name for CSS files
+ * @returns {Object} Directory paths and existing CSS data
+ */
+const validatePreviouslyExists = async ({ stylesDir, compilerType, name }) => {
+  const dirs = {
+    cssDir: path.resolve(stylesDir, `${name}.css`),
+    cssMinifiedDir: path.resolve(stylesDir, `${name}.min.css`),
+    oldData: '',
+  };
+  try {
+    await fs.access(stylesDir);
+    try {
+      await fs.access(dirs.cssDir);
+      if (!compilerType || compilerType === compilerTypeValid.full) {
+        return dirs;
+      }
+      const oldCss = await fs.readFile(dirs.cssDir, 'utf8');
+      const section = (() => {
+        switch (compilerType) {
+          case compilerTypeValid.foundationOnly:
+            return 'Components';
+          case compilerTypeValid.componentOnly:
+            return 'Foundations';
+          default:
+            return '';
+        }
+      })();
+      dirs.oldData = extractDocFragment({ section, doc: oldCss });
+    } catch {
+      return dirs;
+    }
+  } catch {
+    await fs.mkdir(stylesDir, { recursive: true });
+    return dirs;
+  }
+
+  return dirs;
+};
+
+module.exports = { validatePreviouslyExists };

package/src/lib/generateCssDoc/generateCssDoc.util.js

@@ -0,0 +1,47 @@
+/**
+ * CSS Documentation Generator for Bernova
+ *
+ * Combines foundation and component CSS into a single document with proper
+ * sectioning and comments. Handles different compilation modes and preserves
+ * existing data when doing partial compilation.
+ */
+
+const { compilerTypeValid } = require('../../constants');
+
+/**
+ * Generates final CSS document by combining foundations and components
+ * Adds section comments and handles partial compilation modes
+ *
+ * @param {Object} params - Generation parameters
+ * @param {string} params.compilerType - Type of compilation being performed
+ * @param {string} params.stylesCss - Generated component/theme CSS
+ * @param {string} params.foundationsCss - Generated foundation CSS (variables, reset)
+ * @param {string} params.oldData - Existing CSS data to preserve (optional)
+ * @returns {string} Complete CSS document with sections and comments
+ */
+const generateCssDoc = ({
+  compilerType,
+  stylesCss,
+  foundationsCss,
+  oldData = '',
+}) => {
+  // Determine what sections to include based on compilation type
+  const createFoundations = compilerType !== compilerTypeValid.componentOnly;
+  const createComponents = compilerType !== compilerTypeValid.foundationOnly;
+
+  // Generate foundations section (CSS variables, reset, base styles)
+  const foundations = createFoundations
+    ? `/* === BERNOVA FOUNDATIONS === */\n${foundationsCss}\n/* === END FOUNDATIONS === */\n\n`
+    : oldData;
+
+  // Generate components section (component styles, utilities, media queries)
+  const components = createComponents
+    ? `/* === BERNOVA COMPONENTS === */\n${stylesCss}\n/* === END COMPONENTS === */\n`
+    : oldData;
+
+  // Combine sections into final CSS document
+  const cssDocument = `${foundations}${components}`;
+  return cssDocument;
+};
+
+module.exports = { generateCssDoc };