tessl/npm-uikit

UIkit is a lightweight and modular front-end framework for developing fast and powerful web interfaces.

—

Pending

Overview

Eval results

Files

JavaScript API

Name: tessl/npm-uikit
Author: tessl

UIkit's JavaScript API provides a comprehensive component system with lifecycle management, global utilities, and plugin architecture for creating dynamic web interfaces.

Capabilities

Global UIkit Object

The main UIkit object exposed globally and as a module export.

/**
 * Main UIkit object providing component management and utilities
 */
declare const UIkit: {
  /** Current UIkit version string */
  version: string;
  
  /** Global options object for framework-wide defaults */
  options: Record<string, any>;
  
  /** Utility functions collection */
  util: UtilityCollection;
  
  /** Global container element (default: document.body) */
  container: HTMLElement;
  
  /** Register or retrieve component definitions */
  component(name: string, definition?: ComponentDefinition): ComponentConstructor | void;
  
  /** Get component instance(s) from element */
  getComponent(element: HTMLElement, name?: string): ComponentInstance | Record<string, ComponentInstance>;
  
  /** Get all component instances from element */
  getComponents(element: HTMLElement): Record<string, ComponentInstance>;
  
  /** Update components within element */
  update(element?: HTMLElement, event?: Event): void;
  
  /** Install plugin */
  use(plugin: Plugin): typeof UIkit;
  
  /** Add mixin to component */
  mixin(mixin: Mixin, component?: string | ComponentConstructor): void;
  
  /** Create UIkit subclass */
  extend(options: ComponentOptions): ComponentConstructor;
};

Usage Examples:

// Check version
console.log(UIkit.version); // "3.23.12"

// Set global container
UIkit.container = document.getElementById('app');

// Update all components
UIkit.update();

// Update specific element
UIkit.update(document.getElementById('content'));

Component Management

/**
 * Register a new component or retrieve existing component definition
 * @param name - Component name
 * @param definition - Component definition object (optional)
 * @returns Component constructor if retrieving, undefined if registering
 */
component(name: string, definition?: ComponentDefinition): ComponentConstructor | void;

/**
 * Get component instance from element
 * @param element - Target HTML element
 * @param name - Component name (optional, returns all if omitted)
 * @returns Component instance or all instances object
 */
getComponent(element: HTMLElement, name?: string): ComponentInstance | Record<string, ComponentInstance>;

/**
 * Get all component instances from element
 * @param element - Target HTML element
 * @returns Object with component names as keys and instances as values
 */
getComponents(element: HTMLElement): Record<string, ComponentInstance>;

Usage Examples:

// Register custom component
UIkit.component('custom-component', {
  connected() {
    console.log('Component connected');
  }
});

// Get modal component from element
const modal = UIkit.getComponent(document.getElementById('my-modal'), 'modal');

// Get all components from element
const components = UIkit.getComponents(document.getElementById('container'));

Component Instances

Individual component instances with lifecycle and interaction methods.

interface ComponentInstance {
  /** Component's root element */
  $el: HTMLElement;
  
  /** Component configuration options */
  $options: Record<string, any>;
  
  /** Component's container element */
  $container: HTMLElement;
  
  /** Mount component to element */
  $mount(element: HTMLElement): void;
  
  /** Destroy component instance */
  $destroy(removeEl?: boolean): void;
  
  /** Create child component */
  $create(component: string, element: HTMLElement, options?: Record<string, any>): ComponentInstance;
  
  /** Emit component update event */
  $emit(event: Event): void;
  
  /** Update component */
  $update(element?: HTMLElement, event?: Event): void;
  
  /** Reset component state */
  $reset(): void;
  
  /** Get related component instance */
  $getComponent(name: string): ComponentInstance;
}

Usage Examples:

// Create modal instance
const modal = UIkit.modal('#my-modal', {
  keyboard: false,
  stack: true
});

// Mount to different element
modal.$mount(document.getElementById('new-target'));

// Destroy component
modal.$destroy(true); // true to remove element

// Reset component state
modal.$reset();

Plugin System

Install and manage UIkit plugins and extensions.

/**
 * Install plugin
 * @param plugin - Plugin function
 * @returns UIkit object for chaining
 */
use(plugin: Plugin): typeof UIkit;

interface Plugin {
  /** Installation flag to prevent double installation */
  installed?: boolean;
  /** Plugin installation function */
  (UIkit: typeof UIkit): void;
}

Usage Examples:

// Install icons plugin
import Icons from 'uikit/dist/js/uikit-icons';
UIkit.use(Icons);

// Create custom plugin
const customPlugin = function(UIkit) {
  UIkit.component('my-component', {
    // Component definition
  });
};

UIkit.use(customPlugin);

Mixin System

Add reusable functionality to components through mixins.

/**
 * Add mixin to component(s)
 * @param mixin - Mixin object with reusable functionality
 * @param component - Target component name or constructor (optional, applies globally if omitted)
 */
mixin(mixin: Mixin, component?: string | ComponentConstructor): void;

interface Mixin {
  /** Mixin properties and methods */
  [key: string]: any;
}

Usage Examples:

// Global mixin
UIkit.mixin({
  connected() {
    console.log('Component connected via mixin');
  }
});

// Component-specific mixin
UIkit.mixin({
  customMethod() {
    return 'Custom functionality';
  }
}, 'modal');

Extension System

Create UIkit subclasses with custom functionality.

/**
 * Create UIkit subclass
 * @param options - Extension options
 * @returns Extended UIkit constructor
 */
extend(options: ComponentOptions): ComponentConstructor;

Usage Examples:

// Create custom UIkit subclass
const CustomUIkit = UIkit.extend({
  customOption: 'default-value',
  
  connected() {
    console.log('Custom UIkit connected');
  }
});

// Use custom subclass
const instance = new CustomUIkit({ el: '#element' });

Update System

Manage component updates and lifecycle.

/**
 * Update components within element tree
 * @param element - Root element to update (default: document.body)
 * @param event - Event that triggered update (optional)
 */
update(element?: HTMLElement, event?: Event): void;

Usage Examples:

// Update all components
UIkit.update();

// Update specific element tree
UIkit.update(document.getElementById('dynamic-content'));

// Update with event context
UIkit.update(element, new CustomEvent('data-changed'));

// Update on DOM changes
const observer = new MutationObserver(() => {
  UIkit.update();
});
observer.observe(document.body, { childList: true, subtree: true });

Utility Functions

Collection of utility functions available via UIkit.util.

interface UtilityCollection {
  // DOM utilities
  $(selector: string | HTMLElement): HTMLElement | null;
  $$(selector: string): HTMLElement[];
  addClass(element: HTMLElement, className: string): void;
  removeClass(element: HTMLElement, className: string): void;
  hasClass(element: HTMLElement, className: string): boolean;
  toggleClass(element: HTMLElement, className: string): void;
  
  // Attribute utilities
  attr(element: HTMLElement, name: string, value?: string): string | void;
  removeAttr(element: HTMLElement, name: string): void;
  data(element: HTMLElement, key: string): any;
  
  // Style utilities
  css(element: HTMLElement, property: string | Record<string, string>, value?: string): string | void;
  
  // Event utilities
  on(element: HTMLElement, events: string, handler: Function): void;
  off(element: HTMLElement, events: string, handler: Function): void;
  once(element: HTMLElement, events: string, handler: Function): void;
  trigger(element: HTMLElement, event: string, detail?: any): void;
  
  // Position utilities
  offset(element: HTMLElement): { top: number; left: number };
  position(element: HTMLElement): { top: number; left: number };
  
  // Animation utilities
  Animation: AnimationConstructor;
  Transition: TransitionConstructor;
  
  // Type checking
  isArray(obj: any): boolean;
  isFunction(obj: any): boolean;
  isObject(obj: any): boolean;
  isPlainObject(obj: any): boolean;
  isString(obj: any): boolean;
  isNumber(obj: any): boolean;
  isWindow(obj: any): boolean;
  isDocument(obj: any): boolean;
  
  // Language utilities
  each(obj: any, callback: Function): void;
  includes(array: any[], item: any): boolean;
  startsWith(str: string, search: string): boolean;
  endsWith(str: string, search: string): boolean;
  
  // Object utilities
  assign(target: any, ...sources: any[]): any;
  
  // String utilities
  hyphenate(str: string): string;
  camelize(str: string): string;
  ucfirst(str: string): string;
}

Usage Examples:

const { $, addClass, on, isArray } = UIkit.util;

// DOM selection
const element = $('#my-element');

// Class manipulation
addClass(element, 'uk-active');

// Event handling
on(element, 'click', () => {
  console.log('Clicked');
});

// Type checking
if (isArray(data)) {
  // Handle array
}

Component Definition Structure

interface ComponentDefinition {
  /** Mixins to apply to component */
  mixins?: Mixin[];
  
  /** Default component data */
  data?: Record<string, any>;
  
  /** Component properties configuration */
  props?: Record<string, PropDefinition>;
  
  /** Computed properties */
  computed?: Record<string, ComputedProperty>;
  
  /** Component methods */
  methods?: Record<string, Function>;
  
  /** Event definitions */
  events?: EventDefinition[];
  
  /** Lifecycle hooks */
  connected?(): void;
  disconnected?(): void;
  beforeConnect?(): void;
  beforeDisconnect?(): void;
  destroy?(): void;
  
  /** Update hooks */
  update?: {
    read?(): void;
    write?(): void;
    events?: string[];
  };
}

interface PropDefinition {
  /** Property type(s) */
  type?: string | string[];
  /** Default value */
  default?: any;
  /** Validation function */
  validator?(value: any): boolean;
}

interface ComputedProperty {
  /** Getter function */
  get?(): any;
  /** Setter function */
  set?(value: any): void;
  /** Dependencies for caching */
  depends?: string[];
}

interface EventDefinition {
  /** Event name(s) */
  name: string;
  /** Handler method name or function */
  handler: string | Function;
  /** Target element selector or function */
  el?: string | Function;
  /** Event delegation selector */
  delegate?: string;
  /** Filter function */
  filter?: Function;
  /** Self-only flag */
  self?: boolean;
}

Component Definition Example:

UIkit.component('example', {
  mixins: [UIkit.mixin.togglable],
  
  data: {
    active: false,
    duration: 300
  },
  
  props: {
    toggle: {
      type: String,
      default: '.uk-toggle'
    }
  },
  
  computed: {
    toggleElement() {
      return UIkit.util.$(this.toggle, this.$el);
    }
  },
  
  methods: {
    show() {
      this.active = true;
      this.$emit('show');
    },
    
    hide() {
      this.active = false;
      this.$emit('hide');
    }
  },
  
  events: [
    {
      name: 'click',
      el: 'toggleElement',
      handler: 'toggle'
    }
  ],
  
  connected() {
    console.log('Component connected');
  },
  
  update: {
    read() {
      // Read DOM properties
    },
    write() {
      // Write DOM changes
    },
    events: ['resize']
  }
});

Install with Tessl CLI