@marlink-technologies/mrlnk v1.2.0

MRLNK

A modern, lightweight TypeScript UI framework for building responsive and accessible web applications. MRLNK is designed to work seamlessly with any JavaScript framework or vanilla JS, with special support for Webflow integration.

✨ Why MRLNK?

• 🎯 Zero Dependencies - Only core dependencies (GSAP, Floating UI) for essential features
• 🚀 Performance First - Lightweight (~12KB gzipped), tree-shakeable components with minimal DOM operations
• 🎨 Customizable - Extensive theming system using CSS custom properties
• ♿ Accessible - WCAG 2.1 compliant components with full keyboard navigation
• 📦 Framework Agnostic - Works with any framework or vanilla JavaScript
• 🔧 TypeScript Native - Full type safety and excellent IDE support
• 🌐 Webflow Ready - Special integration support for Webflow projects
• 🔄 Live Reload - Development server with hot reload support
• 📱 Responsive - Mobile-first design approach
• 🔒 Type Safe - Full TypeScript support with IntelliSense

🚀 Getting Started

Common Use Cases

1. Simple Component Usage

// Create and mount a button
const button = App.Component.Button.create({
  text: 'Click me',
  variant: 'primary',
});
document.body.appendChild(button);

// Create a color picker with preview
const picker = App.Component.ColorPicker.create({
  onChange: (color) => (document.body.style.backgroundColor = color),
});
document.body.appendChild(picker);

2. Form Validation

const form = document.createElement('form');

const input = App.Component.Input.create({
  label: 'Email',
  type: 'email',
  required: true,
  validation: {
    pattern: /^[^@]+@[^@]+\.[^@]+$/,
    message: 'Please enter a valid email',
  },
});

const submit = App.Component.Button.create({
  text: 'Submit',
  type: 'submit',
  onClick: (e) => {
    e.preventDefault();
    if (input.validate()) {
      console.log('Form valid!');
    }
  },
});

form.appendChild(input);
form.appendChild(submit);

3. Modal Dialog

const modal = App.Component.Modal.create({
  title: 'Confirmation',
  content: 'Are you sure you want to proceed?',
  buttons: [
    {
      text: 'Cancel',
      variant: 'secondary',
      onClick: () => modal.hide(),
    },
    {
      text: 'Confirm',
      variant: 'primary',
      onClick: () => {
        console.log('Confirmed!');
        modal.hide();
      },
    },
  ],
});

const openButton = App.Component.Button.create({
  text: 'Open Modal',
  onClick: () => modal.show(),
});

4. Data Display

const table = App.Component.Table.create({
  columns: [
    { field: 'name', header: 'Name' },
    { field: 'age', header: 'Age' },
  ],
  data: [
    { name: 'John', age: 30 },
    { name: 'Jane', age: 25 },
  ],
  sortable: true,
  pagination: {
    pageSize: 10,
  },
});

📦 Installation

Prerequisites

• Node.js (v16 or higher)
• npm (v7 or higher) or pnpm (recommended)
• TypeScript (v4.5 or higher)

# Using npm
npm install @marlink-technologies/mrlnk

# Using pnpm (recommended)
pnpm add @marlink-technologies/mrlnk

# Using yarn
yarn add @marlink-technologies/mrlnk

CDN Usage

<!-- Production version -->
<script src="https://cdn.jsdelivr.net/npm/@marlink-technologies/mrlnk@latest/dist/index.js"></script>
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@marlink-technologies/mrlnk@latest/dist/style.css"
/>

<!-- Development version -->
<script src="http://localhost:3000/index.js"></script>
<link rel="stylesheet" href="http://localhost:3000/style.css" />

🎯 Quick Start

Basic Usage

import { App } from '@marlink-technologies/mrlnk';

// Create a button
const button = App.Component.Button.create({
  text: 'Click me',
  variant: 'primary',
  onClick: () => console.log('Button clicked!'),
});

// Add it to the DOM
document.body.appendChild(button);

Framework Integration

React

import { useEffect, useRef } from 'react';
import { App } from '@marlink-technologies/mrlnk';

function Button({ onClick }) {
  const containerRef = useRef(null);

  useEffect(() => {
    if (!containerRef.current) return;

    const button = App.Component.Button.create({
      text: 'Click me',
      onClick,
    });

    containerRef.current.appendChild(button);
    return () => button.remove();
  }, [onClick]);

  return <div ref={containerRef} />;
}

Vue

<template>
  <div ref="container"></div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import { App } from '@marlink-technologies/mrlnk';

const container = ref(null);
let button = null;

onMounted(() => {
  if (!container.value) return;

  button = App.Component.Button.create({
    text: 'Click me',
    onClick: () => emit('click'),
  });

  container.value.appendChild(button);
});

onUnmounted(() => button?.remove());
</script>

Webflow Integration

1. Add the MRLNK script and styles to your Webflow project settings:

<script
  defer
  src="https://cdn.jsdelivr.net/npm/@marlink-technologies/mrlnk@latest/dist/index.js"
></script>
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@marlink-technologies/mrlnk@latest/dist/style.css"
/>

2. Create a custom code block in Webflow:

<div id="mrlnk-component"></div>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    const component = App.Component.Button.create({
      text: 'Webflow Button',
      variant: 'primary',
    });
    document.getElementById('mrlnk-component').appendChild(component);
  });
</script>

📚 Documentation

• Framework Overview - Architecture & core concepts
• Development Guide - Development workflow & best practices
• Components Map - Available components & usage
• Theming Guide - Customization & styling
• Playground - Interactive examples
• Architecture - Technical diagrams & flows

🛠️ Development

Setting Up Development Environment

1. Clone the repository:

git clone https://github.com/Marlink-Technologies/mrlnk.git
cd mrlnk

2. Install dependencies:

pnpm install

3. Start development server:

pnpm dev

Available Commands

# Start development server (http://localhost:3000)
pnpm dev

# Build for production (outputs to /dist)
pnpm build

# Run tests in headless mode
pnpm test

# Run tests in browser
pnpm test:headed

# Format code with Prettier
pnpm format

# Run ESLint checks
pnpm lint

# Fix ESLint issues
pnpm lint:fix

# Check TypeScript types
pnpm check

# Create a new release
pnpm release

# Update dependencies interactively
pnpm update

Development Tips

1. Live Reloading: The development server includes live reloading by default
2. Path Aliases: Use $utils/* for importing from the utils directory
3. Type Checking: Run pnpm check before committing changes
4. Testing: Write tests for new components in the /tests directory

🌐 Browser Support

🔧 Tech Stack

• TypeScript - Type-safe component development
• GSAP - Smooth animations and transitions
• Floating UI - Positioning for tooltips and popovers
• ESBuild - Fast bundling and compilation
• Playwright - End-to-end testing
• Changesets - Version management and changelogs

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (pnpm test)
5. Create a changeset (pnpm changeset)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

See our Contributing Guide for more details.

🐛 Troubleshooting

Common Issues

1. Components not rendering

   • Check if MRLNK is properly imported
   • Verify the CDN links are accessible
   • Check browser console for errors

2. Styling issues

   • Ensure the CSS file is properly loaded
   • Check if custom properties are correctly defined
   • Verify CSS specificity

3. TypeScript errors

   • Make sure @types are installed
   • Check TypeScript version compatibility
   • Verify tsconfig.json settings

Getting Help

• Common Issues
• Stack Overflow
• GitHub Issues
• Discord Community

📄 License

MRLNK is licensed under the ISC License - see the LICENSE file for details.

🙏 Credits

Created and maintained by Marlink Technologies.

🔗 Quick Links

• NPM Package
• GitHub Repository
• Documentation
• Changelog
• Website
• Component Playground
• Examples

🎨 Theming

Custom Properties

:root {
  /* Colors */
  --mlk-color-primary: #007bff;
  --mlk-color-secondary: #6c757d;
  --mlk-color-success: #28a745;
  --mlk-color-danger: #dc3545;

  /* Typography */
  --mlk-font-family: system-ui, -apple-system, sans-serif;
  --mlk-font-size-base: 16px;
  --mlk-line-height: 1.5;

  /* Spacing */
  --mlk-spacing-unit: 8px;
  --mlk-border-radius: 4px;

  /* Transitions */
  --mlk-transition-duration: 200ms;
  --mlk-transition-timing: ease-in-out;
}

Dark Mode

[data-theme='dark'] {
  --mlk-color-primary: #0d6efd;
  --mlk-color-secondary: #495057;
  --mlk-background: #212529;
  --mlk-text: #f8f9fa;
}

📊 Performance

🔐 Security

• All dependencies are regularly updated
• No eval() or innerHTML usage
• XSS protection built-in
• CSP compatible
• Regular security audits

🗺️ Roadmap

• Server Components Support
• Web Components Export
• SSR Support
• Animation System
• Form Builder
• Data Grid
• Chart Components
• Mobile Components

💖 Sponsors