@nuraly/runtime 0.1.0

package/components/ui/nuraly-ui/src/shared/themes/index.ts

@@ -0,0 +1,132 @@
+/**
+ * Theme CSS Variables Index
+ * 
+ * Import these CSS files to apply design system themes with light/dark variants:
+ * 
+ * @example
+ * ```html
+ * <!-- Apply Carbon Design System Light -->
+ * <div data-theme="carbon-light">
+ *   <nr-button type="primary">Carbon Light Button</nr-button>
+ * </div>
+ * 
+ * <!-- Apply Carbon Design System Dark -->
+ * <div data-theme="carbon-dark">
+ *   <nr-button type="primary">Carbon Dark Button</nr-button>
+ * </div>
+ * 
+ * <!-- Use default theme light -->
+ * <div data-theme="default-light">
+ *   <nr-button type="primary">Default Light Button</nr-button>
+ * </div>
+ * 
+ * <!-- Use default theme dark -->
+ * <div data-theme="default-dark">
+ *   <nr-button type="primary">Default Dark Button</nr-button>
+ * </div>
+ * ```
+ * 
+ * @example JavaScript/TypeScript
+ * ```ts
+ * // In your app entry point
+ * import './themes/carbon.css'; // for Carbon theme
+ * // OR
+ * import './themes/default.css'; // for default theme
+ * ```
+ */
+
+export const THEME_FILES = {
+  // Main theme files (import complete themes with all components)
+  default: './default.css',
+  carbon: './carbon.css',
+  editor: './editor.css',
+  
+  // Individual theme folders (for granular imports)
+  'default-folder': './default/index.css',
+  'carbon-folder': './carbon/index.css',
+  'editor-folder': './editor/index.css',
+  
+  // Component-specific theme files (for component-only imports)
+  'default-button': './default/button/index.css',
+  'carbon-button': './carbon/button/index.css',
+  'editor-button': './editor/button/index.css',
+  
+  // Core theme variables only (no component styles)
+  'default-core': './default/theme.css',
+  'carbon-core': './carbon/theme.css'
+} as const;
+
+export type ThemeName = keyof typeof THEME_FILES;
+
+export const THEME_VARIANTS = {
+  'default-light': 'Default Light',
+  'default-dark': 'Default Dark',
+  'carbon-light': 'Carbon Light',
+  'carbon-dark': 'Carbon Dark',
+  // Backward compatibility
+  'light': 'Default Light',
+  'dark': 'Default Dark'
+} as const;
+
+export type ThemeVariant = keyof typeof THEME_VARIANTS;
+
+/**
+ * Utility function to apply theme to an element
+ * @param element - The element to apply the theme to
+ * @param theme - The theme variant to apply
+ */
+export function applyTheme(element: HTMLElement, theme: ThemeVariant): void {
+  // Remove existing theme attributes
+  element.removeAttribute('data-theme');
+  
+  // Apply new theme
+  element.setAttribute('data-theme', theme);
+}
+
+/**
+ * Utility function to get current theme from an element or its parents
+ * @param element - The element to check for theme
+ * @returns The current theme variant or null if not found
+ */
+export function getCurrentTheme(element: HTMLElement): ThemeVariant | null {
+  let currentElement: HTMLElement | null = element;
+  
+  while (currentElement) {
+    const theme = currentElement.getAttribute('data-theme') as ThemeVariant;
+    if (theme && theme in THEME_VARIANTS) {
+      return theme;
+    }
+    currentElement = currentElement.parentElement;
+  }
+  
+  return null;
+}
+
+/**
+ * Utility function to toggle between light and dark variants of the same theme
+ * @param element - The element to toggle theme on
+ */
+export function toggleThemeVariant(element: HTMLElement): void {
+  const currentTheme = getCurrentTheme(element);
+  
+  if (!currentTheme) {
+    // Default to default-light if no theme is set
+    applyTheme(element, 'default-light');
+    return;
+  }
+  
+  // Toggle between light and dark variants
+  const toggleMap: Record<ThemeVariant, ThemeVariant> = {
+    'default-light': 'default-dark',
+    'default-dark': 'default-light',
+    'carbon-light': 'carbon-dark',
+    'carbon-dark': 'carbon-light',
+    'light': 'dark',
+    'dark': 'light'
+  };
+  
+  const newTheme = toggleMap[currentTheme];
+  if (newTheme) {
+    applyTheme(element, newTheme);
+  }
+}

package/components/ui/nuraly-ui/src/shared/utils.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Throttles a function call to limit execution frequency
+ * Useful for performance optimization of frequently called functions
+ * 
+ * @param func - Function to throttle  
+ * @param limit - Milliseconds to limit between calls
+ * @returns Throttled function that will execute at most once per limit period
+ * 
+ * @example
+ * ```typescript
+ * const throttledScroll = throttle((event) => {
+ *   console.log('Scroll event:', event);
+ * }, 16); // 60fps limit
+ * 
+ * window.addEventListener('scroll', throttledScroll);
+ * ```
+ */
+export function throttle<T extends (...args: any[]) => any>(
+  func: T, 
+  limit: number
+): (...args: Parameters<T>) => void {
+  let inThrottle: boolean;
+  return function(this: any, ...args: Parameters<T>) {
+    if (!inThrottle) {
+      func.apply(this, args);
+      inThrottle = true;
+      setTimeout(() => inThrottle = false, limit);
+    }
+  };
+}
+
+/**
+ * Debounces a function call to delay execution until after a period of inactivity
+ * Useful for search inputs, resize handlers, etc.
+ * 
+ * @param func - Function to debounce
+ * @param delay - Milliseconds to wait after last call
+ * @returns Debounced function that will execute after delay period of inactivity
+ * 
+ * @example
+ * ```typescript
+ * const debouncedSearch = debounce((query: string) => {
+ *   console.log('Searching for:', query);
+ * }, 300); // Wait 300ms after user stops typing
+ * 
+ * input.addEventListener('input', (e) => debouncedSearch(e.target.value));
+ * ```
+ */
+export function debounce<T extends (...args: any[]) => any>(
+  func: T, 
+  delay: number
+): (...args: Parameters<T>) => void {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  return function(this: any, ...args: Parameters<T>) {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => func.apply(this, args), delay);
+  };
+}
+
+/**
+ * RAF (RequestAnimationFrame) throttle for smooth animations
+ * Ensures function is called at most once per animation frame
+ * 
+ * @param func - Function to throttle to animation frames
+ * @returns Function that will execute at most once per animation frame
+ * 
+ * @example
+ * ```typescript
+ * const rafThrottledUpdate = rafThrottle(() => {
+ *   // Expensive DOM updates
+ *   updateUI();
+ * });
+ * 
+ * element.addEventListener('mousemove', rafThrottledUpdate);
+ * ```
+ */
+export function rafThrottle<T extends (...args: any[]) => any>(
+  func: T
+): (...args: Parameters<T>) => void {
+  let rafId: number | undefined;
+  return function(this: any, ...args: Parameters<T>) {
+    if (rafId) return;
+    rafId = requestAnimationFrame(() => {
+      func.apply(this, args);
+      rafId = undefined;
+    });
+  };
+}

package/components/ui/nuraly-ui/src/shared/validation.types.ts

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Validation event detail structure that validation controllers emit
+ */
+export interface ValidationEventDetail {
+  /** Whether the field is currently valid */
+  isValid: boolean;
+  /** Current validation message */
+  validationMessage: string;
+  /** Current validation state */
+  validationState: string;
+  /** Array of error messages */
+  errors: string[];
+  /** Array of warning messages */
+  warnings: string[];
+  /** Complete validation result object */
+  validationResult: any; // Generic to allow different validation result types
+}
+
+/**
+ * Validation status information returned by getValidationStatus()
+ */
+export interface ValidationStatus {
+  /** Whether the field is currently valid */
+  isValid: boolean;
+  /** Whether validation is currently in progress */
+  isValidating?: boolean;
+  /** Array of error messages */
+  errors: string[];
+  /** Array of warning messages */
+  warnings: string[];
+}
+
+/**
+ * Generic validation rule interface
+ */
+export interface ValidationRule {
+  /** Validation function */
+  validator: (value: any) => boolean | Promise<boolean>;
+  /** Error/warning message */
+  message: string;
+  /** Validation level */
+  level?: 'error' | 'warning';
+  /** Whether this rule blocks form submission */
+  blocking?: boolean;
+}
+
+/**
+ * Interface for components that support validation through events and API
+ * This is the shared pattern used by input, textarea, and other form field components
+ */
+export interface ValidatableComponent {
+  /** Field name for form submission */
+  name?: string;
+  /** Field value */
+  value: any;
+  /** Required field indicator */
+  required?: boolean;
+  /** Disabled state */
+  disabled?: boolean;
+  /** Readonly state */
+  readonly?: boolean;
+  /** Current validation message */
+  validationMessage?: string;
+
+  // Validation API Methods
+  /** Add a validation rule */
+  addRule?(rule: ValidationRule): void;
+  /** Remove validation rules matching predicate */
+  removeRule?(predicate: (rule: ValidationRule) => boolean): void;
+  /** Clear all validation rules */
+  clearRules?(): void;
+  /** Get current validation status */
+  getValidationStatus(): ValidationStatus;
+  /** Trigger validation manually */
+  validate(): Promise<boolean> | boolean;
+  /** Clear validation state */
+  clearValidation?(): void;
+
+  // Event-based Integration
+  /** Dispatches 'nr-validation' events with ValidationEventDetail */
+  addEventListener(type: 'nr-validation', listener: (event: CustomEvent<ValidationEventDetail>) => void): void;
+  /** Removes 'nr-validation' event listeners */
+  removeEventListener(type: 'nr-validation', listener: (event: CustomEvent<ValidationEventDetail>) => void): void;
+}
+
+/**
+ * Form field information for form integration
+ */
+export interface FormFieldInfo {
+  element: HTMLElement & ValidatableComponent;
+  name: string;
+  value: any;
+  isValid: boolean;
+  validationMessage: string;
+  required: boolean;
+  touched: boolean;
+  dirty: boolean;
+}
+
+/**
+ * Constants for validation events
+ */
+export const VALIDATION_EVENTS = {
+  VALIDATION: 'nr-validation',
+  FIELD_FOCUS: 'nr-focus',
+  FIELD_BLUR: 'nr-blur',
+  FIELD_CHANGE: 'nr-change',
+  FIELD_INPUT: 'nr-input',
+  FIELD_CLEAR: 'nr-clear'
+} as const;
+
+export type ValidationEventType = typeof VALIDATION_EVENTS[keyof typeof VALIDATION_EVENTS];

package/components/ui/nuraly-ui/tools/bump-versions.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function findPackageJsonFiles(dir, results = []) {
+  const files = fs.readdirSync(dir);
+  
+  for (const file of files) {
+    const fullPath = path.join(dir, file);
+    const stat = fs.statSync(fullPath);
+    
+    if (stat.isDirectory() && !file.startsWith('.') && file !== 'node_modules') {
+      findPackageJsonFiles(fullPath, results);
+    } else if (file === 'package.json') {
+      results.push(fullPath);
+    }
+  }
+  
+  return results;
+}
+
+function bumpVersion(version) {
+  const parts = version.split('.');
+  if (parts.length !== 3) {
+    throw new Error(`Invalid version format: ${version}`);
+  }
+  
+  // Increment patch version
+  parts[2] = (parseInt(parts[2]) + 1).toString();
+  return parts.join('.');
+}
+
+function updatePackageJson(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const packageData = JSON.parse(content);
+    
+    if (packageData.version) {
+      const oldVersion = packageData.version;
+      const newVersion = bumpVersion(oldVersion);
+      packageData.version = newVersion;
+      
+      fs.writeFileSync(filePath, JSON.stringify(packageData, null, 2) + '\n');
+      console.log(`Updated ${filePath}: ${oldVersion} -> ${newVersion}`);
+      return true;
+    } else {
+      console.log(`Skipped ${filePath}: No version field found`);
+      return false;
+    }
+  } catch (error) {
+    console.error(`Error updating ${filePath}:`, error.message);
+    return false;
+  }
+}
+
+function main() {
+  // Go up one directory from tools to reach the project root
+  const rootDir = path.join(__dirname, '..');
+  console.log(`Searching for package.json files in: ${rootDir}`);
+  
+  const packageFiles = findPackageJsonFiles(rootDir);
+  console.log(`Found ${packageFiles.length} package.json files\n`);
+  
+  let updatedCount = 0;
+  
+  for (const filePath of packageFiles) {
+    if (updatePackageJson(filePath)) {
+      updatedCount++;
+    }
+  }
+  
+  console.log(`\nSummary: Updated ${updatedCount} of ${packageFiles.length} package.json files`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}

package/components/ui/nuraly-ui/web-dev-server.config.js

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+import {legacyPlugin} from '@web/dev-server-legacy';
+
+const mode = process.env.MODE || 'dev';
+if (!['dev', 'prod'].includes(mode)) {
+  throw new Error(`MODE must be "dev" or "prod", was "${mode}"`);
+}
+
+export default {
+  nodeResolve: {exportConditions: mode === 'dev' ? ['development'] : []},
+  preserveSymlinks: true,
+  plugins: [
+    legacyPlugin({
+      polyfills: {
+        // Manually imported in index.html file
+        webcomponents: false,
+      },
+    }),
+  ],
+};

package/components/ui/nuraly-ui/web-test-runner.config.js

@@ -0,0 +1,124 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+import {legacyPlugin} from '@web/dev-server-legacy';
+import {playwrightLauncher} from '@web/test-runner-playwright';
+
+const mode = process.env.MODE || 'dev';
+if (!['dev', 'prod'].includes(mode)) {
+  throw new Error(`MODE must be "dev" or "prod", was "${mode}"`);
+}
+
+// Uncomment for testing on Sauce Labs
+// Must run `npm i --save-dev @web/test-runner-saucelabs` and set
+// SAUCE_USERNAME and SAUCE_USERNAME environment variables
+// ===========
+// import {createSauceLabsLauncher} from '@web/test-runner-saucelabs';
+// const sauceLabsLauncher = createSauceLabsLauncher(
+//   {
+//     user: process.env.SAUCE_USERNAME,
+//     key: process.env.SAUCE_USERNAME,
+//   },
+//   {
+//     'sauce:options': {
+//       name: 'unit tests',
+//       build: `${process.env.GITHUB_REF ?? 'local'} build ${
+//         process.env.GITHUB_RUN_NUMBER ?? ''
+//       }`,
+//     },
+//   }
+// );
+
+// Uncomment for testing on BrowserStack
+// Must run `npm i --save-dev @web/test-runner-browserstack` and set
+// BROWSER_STACK_USERNAME and BROWSER_STACK_ACCESS_KEY environment variables
+// ===========
+// import {browserstackLauncher as createBrowserstackLauncher} from '@web/test-runner-browserstack';
+// const browserstackLauncher = (config) => createBrowserstackLauncher({
+//   capabilities: {
+//     'browserstack.user': process.env.BROWSER_STACK_USERNAME,
+//     'browserstack.key': process.env.BROWSER_STACK_ACCESS_KEY,
+//     project: 'my-element',
+//     name: 'unit tests',
+//     build: `${process.env.GITHUB_REF ?? 'local'} build ${
+//       process.env.GITHUB_RUN_NUMBER ?? ''
+//     }`,
+//     ...config,
+//   }
+// });
+
+const browsers = {
+  // Local browser testing via playwright
+  // ===========
+  chromium: playwrightLauncher({product: 'chromium'}),
+  firefox: playwrightLauncher({product: 'firefox'}),
+  webkit: playwrightLauncher({product: 'webkit'}),
+
+  // Uncomment example launchers for running on Sauce Labs
+  // ===========
+  // chromium: sauceLabsLauncher({browserName: 'chrome', browserVersion: 'latest', platformName: 'Windows 10'}),
+  // firefox: sauceLabsLauncher({browserName: 'firefox', browserVersion: 'latest', platformName: 'Windows 10'}),
+  // edge: sauceLabsLauncher({browserName: 'MicrosoftEdge', browserVersion: 'latest', platformName: 'Windows 10'}),
+  // ie11: sauceLabsLauncher({browserName: 'internet explorer', browserVersion: '11.0', platformName: 'Windows 10'}),
+  // safari: sauceLabsLauncher({browserName: 'safari', browserVersion: 'latest', platformName: 'macOS 10.15'}),
+
+  // Uncomment example launchers for running on Sauce Labs
+  // ===========
+  // chromium: browserstackLauncher({browserName: 'Chrome', os: 'Windows', os_version: '10'}),
+  // firefox: browserstackLauncher({browserName: 'Firefox', os: 'Windows', os_version: '10'}),
+  // edge: browserstackLauncher({browserName: 'MicrosoftEdge', os: 'Windows', os_version: '10'}),
+  // ie11: browserstackLauncher({browserName: 'IE', browser_version: '11.0', os: 'Windows', os_version: '10'}),
+  // safari: browserstackLauncher({browserName: 'Safari', browser_version: '14.0', os: 'OS X', os_version: 'Big Sur'}),
+};
+
+// Prepend BROWSERS=x,y to `npm run test` to run a subset of browsers
+// e.g. `BROWSERS=chromium,firefox npm run test`
+const noBrowser = (b) => {
+  throw new Error(`No browser configured named '${b}'; using defaults`);
+};
+let commandLineBrowsers;
+try {
+  commandLineBrowsers = process.env.BROWSERS?.split(',').map(
+    (b) => browsers[b] ?? noBrowser(b)
+  );
+} catch (e) {
+  console.warn(e);
+}
+
+// https://modern-web.dev/docs/test-runner/cli-and-configuration/
+export default {
+  rootDir: '.',
+  files: ['./dist/**/*_test.js'],
+  nodeResolve: {exportConditions: mode === 'dev' ? ['development'] : []},
+  preserveSymlinks: true,
+  browsers: commandLineBrowsers ?? Object.values(browsers),
+  testFramework: {
+    // https://mochajs.org/api/mocha
+    config: {
+      ui: 'tdd',
+      timeout: '60000',
+    },
+  },
+  plugins: [
+    // Detect browsers without modules (e.g. IE11) and transform to SystemJS
+    // (https://modern-web.dev/docs/dev-server/plugins/legacy/).
+    legacyPlugin({
+      polyfills: {
+        webcomponents: true,
+        // Inject lit's polyfill-support module into test files, which is required
+        // for interfacing with the webcomponents polyfills
+        custom: [
+          {
+            name: 'lit-polyfill-support',
+            path: 'node_modules/lit/polyfill-support.js',
+            test: "!('attachShadow' in Element.prototype) || !('getRootNode' in Element.prototype) || window.ShadyDOM && window.ShadyDOM.force",
+            module: false,
+          },
+        ],
+      },
+    }),
+  ],
+};