Ranui NPM | npm.io

ranui

UI Component library based on Web Component

Feature

High Cross-Framework Compatibility: Our solution seamlessly adapts to a wide array of leading front-end frameworks, including React, Vue, Preact, SolidJS, Svelte, and more. It also integrates smoothly with any project built on JavaScript and adhering to W3C standards. No matter your choice of technology stack, we guarantee consistent and reliable support.
Pure Native Experience: Our solution eliminates the need for dependencies on front-end frameworks like npm, React/Vue, or complex build tools such as webpack/vite. It truly embodies the essence of Web technology. You can get started effortlessly, just like manipulating native div tags, immediately experiencing the purity and intuitiveness of the technology. This design not only simplifies project structure but also reduces the cost of learning and usage, enabling every developer to appreciate the native charm of Web technology.
Ultimate Modular Design: Utilizing the principle of minimal modularization, we carefully dismantle large and complex systems or applications into extremely small, functionally independent, and easily reusable component units. This approach significantly enhances code maintainability, scalability, and reusability.
Fully Open-Source for Free Learning: Our project fully adheres to the MIT open-source license, granting unrestricted access to all source code. This means you are free to access, learn from, reference, and even modify our code, whether for personal development or commercial applications. We firmly believe that open-source is a vital pathway for technological advancement and innovation.
Interactive and Comprehensive Documentation: We provide detailed and highly interactive documentation, where all component examples are live and interactive. This allows you to directly experience the component functionality while reading, deepening your understanding and enabling quick hands-on learning. This design is aimed at providing you with the most intuitive and efficient learning experience possible.
Type-Checking Support: Our development environment is fully built on TypeScript, equipped with comprehensive declaration files and type definitions, ensuring smooth integration for both JavaScript and TypeScript projects. With powerful type-checking capabilities, we significantly enhance code readability, maintainability, and project robustness, bringing unprecedented convenience and peace of mind to development work.
Enhanced Durability and Stability: Our solution offers exceptional stability, eliminating concerns about disruptive updates encountered during version upgrades, such as React from version 15 to 16 (with fiber) or Vue from version 2 to 3 (with hooks). We ensure that your components won't be forced into unnecessary updates or redevelopments, thus avoiding potential project interruptions and additional workloads. This translates into a continuous and hassle-free project operation.

Install

Using npm:

npm install ranui --save

Document

See components and use examples

Example

https://github.com/chaxus/ran/blob/main/packages/ranui/index.html

Import

Support for on-demand import, which can reduce the size of loaded js

import 'ranui/button';

For global components like preview and message, you need to import global styles

import 'ranui/preview';
import 'ranui/style';

Support global import

ES module

import 'ranui';

UMD, IIFE, CJS

<script src="./ranui/dist/umd/index.umd.cjs"></script>

Usage

It is based on the Web Component, you can use it without focusing on the framework.

In most cases, you can use it just like a native div tag

Here are some examples:

html
js
jsx
vue
tsx

html

<script src="./ranui/dist/umd/index.umd.cjs"></script>

<body>
  <r-button>Button</r-button>
</body>

js

import 'ranui';

const Button = document.createElement('r-button');
Button.appendChild('this is button text');
document.body.appendChild(Button);

jsx

Since react has composite events, for more convenient use, ranui is encapsulated through react high-level components to form @ranui/react.

In react, it is recommended to use @ranui/react.

However, ranui can still be used in any js or ts framework.

import 'ranui';

const App = () => {
  return (
    <>
      <r-button>Button</r-button>
    </>
  );
};

vue

<template>
  <r-button></r-button>
</template>
<script>
import 'ranui';
</script>

tsx

Since react has composite events, for more convenient use, ranui is encapsulated through react high-level components, so there is @ranui/react.

In react, using @ranui/react is silky and fully integrated into the react ecosystem after being wrapped in higher-order functions.

However, ranui can still be used in any js or ts.

// react 18
import type { SyntheticEvent } from 'react';
import React, { useRef } from 'react';
import 'ranui';

const FilePreview = () => {
  const ref = useRef<HTMLDivElement | null>(null);
  const uploadFile = (e: SyntheticEvent<HTMLDivElement>) => {
    if (ref.current) {
      const uploadFile = document.createElement('input');
      uploadFile.setAttribute('type', 'file');
      uploadFile.click();
      uploadFile.onchange = (e) => {
        const { files = [] } = uploadFile;
        if (files && files?.length > 0 && ref.current) {
          ref.current.setAttribute('src', '');
          const file = files[0];
          const url = URL.createObjectURL(file);
          ref.current.setAttribute('src', url);
        }
      };
    }
  };
  return (
    <div>
      <r-preview ref={ref}></r-preview>
      <r-button type="primary" onClick={uploadFile}>
        choose file to preview
      </r-button>
    </div>
  );
};

jsx defines the types of all HTML-native components in TypeScript.

The web component type is not in the jsx definition.

You need to add it manually.

Otherwise you'll have type problems, but it actually works.

// typings.d.ts
interface RButton {
  type?: string;
  onClick?: React.MouseEventHandler<HTMLDivElement> | undefined;
}

interface RPreview {
  src?: string | Blob | ArrayBuffer;
  onClick?: React.MouseEventHandler<HTMLDivElement> | undefined;
  ref?: React.MutableRefObject<HTMLDivElement | null>;
}

declare namespace JSX {
  interface IntrinsicElements {
    'r-preview': React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement> & RPreview;
    'r-button': React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement> & RButton;
  }
}

ranui v0.1.10-alpha.1