ranui

Development scheme based on Web Components

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.

Situation

git：https://github.com/chaxus/ran/tree/main/packages/ranui
npm：https://www.npmjs.com/package/ranui

Usage

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

Here are some examples

html
js
jsx
vue
tsx

1.`html`

html

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

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

2.`js`

import 'ranui';

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

3.`jsx`

Because react synthetic events, in order to more convenient to use, by react higher-order components encapsulation ranui, Output the @ranui/react

In react, use the @ranui/react will be more smooth, by higher-order functions after package, and react ecosystem.

ranui, however, still can be in any js or ts in use.

jsx

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

4.`vue`

vue

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

5.`tsx`

Because react synthetic events, in order to more convenient to use, by react higher-order components encapsulation ranui, Output the @ranui/react

In react, use the @ranui/react will be more smooth, by higher-order functions after package, and react ecosystem.

ranui, however, still can be in any js or ts in use.

tsx

// 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 type 'web component' is not in the jsx definition. You need to add it manually. Otherwise there is a type problem, 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;
  }
}

Import

Support for on-demand import

import 'ranui/button';

For some globally displayed components, such as preview and message, additional styles need to be loaded

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

It can also be imported globally, which is more convenient, so that there is no need to consider anything, so that it is done.

ES module

import 'ranui';

UMD, IIFE, CJS

html

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

Overview

Button

Primary button

Warning button

Text button

Default button

Icon

Skeleton

Input

message

Information prompt

Warning prompt

Error prompt

Success tip

toast tip

Tab

tab1

tab2

tab3

Radar

Progress

Player

Select

Mike

Tom

Lucy

Event

react

@ranui/react By react higher-order functions encapsulated ranui and become, Event events follow react Event specification. It is slightly different from the W3C standard.

Modern 'web' standards

In the W3C standard, you can use the on attribute to define event handlers on HTML elements. But this is the old event handler approach.

Modern web development recommends the addEventListener method.

html

<r-button id="button">Button</r-button>

<script>
  const button = document.getElementById('button');
  button.addEventListener('click', function (event) {
    alert('New click event!');
  });
</script>

However, if you do need to use the 'on' attribute, here is an example:

html

<r-input onchange="change(this.value)"></r-input>

<script>
  function change(e) {
    console.log('e--->', e);
  }
</script>

Note that using the 'on' attribute to define event handlers has some limitations and disadvantages.

For example, you can't use event capture or event delegation, and each event type requires a separate attribute.

This is why the addEventListener method is recommended for modern web development.

You can also use the 'property' method:

html

<r-input id="input"></r-input>

<script>
  const input = document.getElementById("input")
  input.onchange = (e) {
    console.log('e--->', e)
  }
</script>

style

`::part`

html

<r-input id="input"></r-input>

<style>
  /* #input refers to the current custom element
input in ::part(input) refers to the class  of the Shadow DOM element inside the current custom element*/
  #input::part(input) {
    width: 100px;
  }
</style>

For specific pseudo-class names(::part), please refer to the specific introduction.

Pass in by attribute

A sheet attribute is added to all components, passing in a CSSStyleSheet string. It will be inserted directly into the Shadow DOM.

`CSS3` variable `var`

By setting the CSS3 variable for a component, you can customize the specified styles within the component, such as:

html

<r-progress percent="0.7" type="drag"></r-progress>
<r-progress
  percent="0.70"
  type="drag"
  style="--ran-progress-wrap:linear-gradient(to right, #ff0000, #ffff00, #00ff00, #00ffff, #0000ff, #ff00ff, #ff0000);"
></r-progress>

For specific CSS3 variable names, refer to the introduction and description of each component.

Compatibility

Do not support IE, others have better support

ranui

Feature

Situation

Usage

1.`html`

2.`js`

3.`jsx`

4.`vue`

5.`tsx`

Import

Overview

Event

style

`::part`

Pass in by attribute

`CSS3` variable `var`

Compatibility

Contributors

Other

Protocols and standards

ranui ​

Feature ​

Situation ​

Usage ​

1.html ​

2.js ​

3.jsx ​

4.vue ​

5.tsx ​

Import ​

Overview ​

Event ​

style ​

::part ​

Pass in by attribute ​

CSS3 variable var ​

Compatibility ​

Contributors ​

Other ​

Protocols and standards ​

ranui

Feature

Situation

Usage

1.`html`

2.`js`

3.`jsx`

4.`vue`

5.`tsx`

Import

Overview

Event

style

`::part`

Pass in by attribute

`CSS3` variable `var`

Compatibility

Contributors

Other

Protocols and standards