CKSource Samples Framework

Common errors

• Error: `grunt` command not found.

  cause Grunt CLI (Command Line Interface) is not installed globally or locally within the project's node_modules.
  fix Install Grunt CLI globally (`npm install -g grunt-cli`) or locally as a dev dependency (`npm install --save-dev grunt-cli`) and ensure it's in your PATH.

• NameError: @cksource-color-primary is undefined in ...

  cause A LESS variable from the framework, such as `@cksource-color-primary`, is being used, but the LESS file defining it (e.g., `variables.less`) has not been correctly imported or its path is incorrect in the Grunt LESS configuration.
  fix Ensure all necessary LESS files from `cksource-samples-framework/less` are `@import`ed in your source `.less` files and that the `paths` option in your `Gruntfile.js` correctly points to the framework's `less` directory.

• Fatal error: Unable to find Gruntfile.js

  cause The `grunt` command was executed in a directory that does not contain a `Gruntfile.js` file, or the file is named incorrectly.
  fix Create a `Gruntfile.js` in the root of your project directory, ensuring it defines the necessary tasks as demonstrated in the quickstart example.

Warnings

• deprecated This framework relies on older build tooling (Grunt) and a less commonly used CSS pre-processor (LESS). Modern frontend projects typically use bundlers like Webpack or Vite with Sass or PostCSS, which may require significant refactoring to integrate this framework's assets and build process.
  Fix: Consider manually extracting and adapting necessary LESS styles into your modern build pipeline, or replace them with actively maintained alternatives.
• gotcha The package has not been updated for approximately six years (since 2020), indicating it is effectively abandoned. This means no new features, bug fixes, or security patches will be released. Using this package in new projects is discouraged due to potential compatibility issues with newer environments or dependencies.
  Fix: Evaluate if the specific LESS styles or patterns are critical. If so, consider forking the repository for custom maintenance or porting the relevant styles to an actively supported framework.
• gotcha The framework's primary utility is providing LESS stylesheets and Grunt build configurations. It does not export JavaScript modules or components for direct `import` or `require` in application code, which can be a common misconception for AI agents and developers.
  Fix: Focus on integrating its LESS files into your CSS pre-processing workflow via `@import` statements in your `.less` files, and adapt its Grunt tasks if you are using Grunt.

Install

• npm install cksource-samples-framework npm
• yarn add cksource-samples-framework yarn
• pnpm add cksource-samples-framework pnpm

Imports

• CKSourceStyles
  wrong:

  import { CKSourceStyles } from 'cksource-samples-framework';

  correct:

  // This package provides LESS files (e.g., @import '~cksource-samples-framework/less/base.less';) and Grunt build tasks, not JavaScript modules.

  This package does not export JavaScript symbols or components for direct import into application code. It is a styling and build framework.
• SamplesFramework
  wrong:

  const SamplesFramework = require('cksource-samples-framework');

  correct:

  // The framework's functionality is accessed through its LESS files and by running its Grunt tasks defined in a Gruntfile.js.

  Attempting to `require()` this package in CommonJS will likely return an empty object or a non-functional reference, as its primary content is not a Node.js module API.
• FrameworkConfiguration
  wrong:

  import type { FrameworkConfiguration } from 'cksource-samples-framework';

  correct:

  // Configuration for the framework's build process is typically defined within a project's `Gruntfile.js` and `package.json` scripts.

  TypeScript type imports are not available as this package does not provide a public TypeScript API or declaration files for runtime use.

Quickstart

Demonstrates how to configure a Gruntfile.js to compile LESS files, importing styles and variables from `cksource-samples-framework`.

/* Gruntfile.js - Example for integrating cksource-samples-framework */
const path = require('path');

module.exports = function(grunt) {
  // Ensure a 'src' directory with a 'style.less' for compilation exists
  grunt.file.mkdir('src');
  grunt.file.write('src/style.less', `
    // Import core framework styles. Adjust path if necessary.
    @import (reference) "~cksource-samples-framework/less/base.less";
    @import (reference) "~cksource-samples-framework/less/variables.less";

    body {
      font-family: @cksource-font-family; // Using a variable from the framework
      background-color: @cksource-color-background;
      color: @cksource-color-text;
    }

    h1 {
      color: @cksource-color-primary;
    }
  `);

  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    less: {
      development: {
        options: {
          // Point to the framework's LESS files in node_modules
          paths: [path.join(__dirname, 'node_modules', 'cksource-samples-framework', 'less')],
          strictMath: true,
          syncImport: true
        },
        files: {
          'dist/style.css': 'src/style.less'
        }
      }
    },
    clean: {
      dist: ['dist']
    }
  });

  // Load the Grunt plugins required for the build
  grunt.loadNpmTasks('grunt-contrib-less');
  grunt.loadNpmTasks('grunt-contrib-clean');

  // Register tasks to build the CSS
  grunt.registerTask('build', ['clean:dist', 'less:development']);
  grunt.registerTask('default', ['build']);

  console.log("\nTo run this example, ensure you have a package.json with the following devDependencies and run 'npm install' then 'grunt':");
  console.log(`
    {
      "name": "my-cksource-less-project",
      "version": "1.0.0",
      "devDependencies": {
        "cksource-samples-framework": "^1.0.1",
        "grunt": "^1.0.0",
        "grunt-cli": "^1.0.0",
        "grunt-contrib-less": "^2.0.0",
        "less": "^4.0.0"
      }
    }
  `);
  console.log("After running 'grunt', compiled CSS will be in 'dist/style.css'.");
};