@wwog/react

A practical React component library providing declarative flow control and common UI utility components to make your React code more concise and readable.

中文文档

Installation

# Using npm
npm install @wwog/react

# Using yarn
yarn add @wwog/react

# Using pnpm
pnpm add @wwog/react

Features

• ESModule only: Modern module system support
• Full TypeScript support: Written in TypeScript with complete type definitions
• Zero dependencies: Only React and React DOM as peer dependencies
• Declarative flow control: JSX-style conditional rendering and flow control components
• Utility components: Simple and practical common UI utility components
• Lightweight and efficient Excellent performance and compact size

Components & Usage

Flow Control Components

<If>

A declarative conditional rendering component, similar to if-else statements but used in JSX.

import { If } from "@wwog/react";

function Example({ count }) {
  return (
    <If condition={count > 10}>
      <If.Then>
        <p>Count is greater than 10</p>
      </If.Then>
      <If.ElseIf condition={count > 5}>
        <p>Count is greater than 5</p>
      </If.ElseIf>
      <If.Else>
        <p>Count is 5 or less</p>
      </If.Else>
    </If>
  );
}

<Switch>, <Case>, <Default>

A declarative and type-safe alternative to JavaScript's switch statement.

import { Switch } from "@wwog/react";

function Example({ status }) {
  return (
    <Switch value={status}>
      <Switch.Case value="loading">
        <Loading />
      </Switch.Case>
      <Switch.Case value="success">
        <Success />
      </Switch.Case>
      <Switch.Case value="error">
        <Error />
      </Switch.Case>
      <Switch.Default>
        <p>Unknown status</p>
      </Switch.Default>
    </Switch>
  );
}

<When> (v1.1.5+)

A concise conditional rendering component supporting multiple logic combinations. More succinct than , suitable for simple conditions.

import { When } from "@wwog/react";

function Example() {
  const isAdmin = useIsAdmin();
  const isLoading = useIsLoading();
  const hasErrors = useHasErrors();

  return (
    <>
      {/* Render when all conditions are true */}
      <When all={[isAdmin, !isLoading]}>
        <AdminPanel />
      </When>

      {/* Render when any condition is true */}
      <When any={[isLoading, hasErrors]} fallback={<ReadyContent />}>
        <LoadingOrErrorMessage />
      </When>

      {/* Render when all conditions are false */}
      <When none={[isAdmin, isLoading]}>
        <RegularUserContent />
      </When>
    </>
  );
}

<True> / <False> (v1.1.6+)

Helper components for simple boolean conditional rendering.

import { True, False } from "@wwog/react";

function Example({ isActive }) {
  return (
    <>
      <True condition={isActive}>
        <p>Active</p>
      </True>
      <False condition={isActive}>
        <p>Inactive</p>
      </False>
    </>
  );
}

• <True condition={...}>: Renders children when condition is true.
• <False condition={...}>: Renders children when condition is false.

<Toggle>

A declarative toggle component that switches values among predefined options and passes them to child components via specified props, supporting custom toggle logic.

import { Toggle } from "@wwog/react";

<Toggle
  options={["light", "dark"]}
  render={(value, toggle) => {
    /* xxx */
  }}
/>;

• options: Array of values to toggle between.
• index: Initial Options index.
• next: Custom toggle logic function.
• render: Render Function.

Utility Components

<ArrayRender>

Efficiently render array data, supports filtering, sorting, and custom rendering. Optimized for performance with minimal loops.

import { ArrayRender } from "@wwog/react";

function UserList({ users }) {
  return (
    <ArrayRender
      items={users}
      filter={(user) => user.active}
      sort={(a, b) => a.name.localeCompare(b.name)}
      renderItem={(user, index) => (
        <div key={user.id}>
          {index + 1}. {user.name}
        </div>
      )}
      renderEmpty={() => <div>No users found</div>}
    />
  );
}

• items: Array of data to render
• renderItem: Function to render each item, receives (item, index) as parameters
• filter: Optional filter function to filter items
• sort: Optional sort function for array sorting, uses standard comparison function (a, b) => number
• renderEmpty: Optional function to render content when array is empty

Performance Note: When no sorting is needed, filtering is done during the map loop for optimal performance. When sorting is provided, filtering is applied first, then sorting, to minimize operations.

#### `<Clamp>` (v1.2.14+)

> Removed in v1.3.0. The compatibility problem is too big, the desktop web page works well, h5 has a problem.

A component for displaying text with a fixed number of lines, ellipsis, and optional extra content.

```tsx
import { Clamp } from "@wwog/react";

function Example() {
  return (
    <Clamp
      text="This is a long text that will be truncated with ellipsis..."
      maxLine={2}
      extraContent={<button>See more</button>}
    />
  );
}

• text: The text content to be displayed.
• maxLine: Maximum number of lines, defaults to 1.
• extraContent: Extra content to display at the end of the text, such as a "See more" button.
• extraHeight: Height of the extra content, defaults to 20.
• wrapperStyle: Style for the wrapper container.

<Pipe> (v1.1.7+)

A declarative data pipeline component for multi-step data transformation and chaining.

Declarative data processing, replacing nested function calls. Improves code readability and logic clarity. Suitable for data cleaning, formatting, etc.

import { Pipe } from "@wwog/react";

function Example({ users }) {
  return (
    <Pipe
      data={users}
      transform={[
        (data) => data.filter((user) => user.active),
        (data) => data.map((user) => user.name),
      ]}
      render={(names) => <div>{names.join(", ")}</div>}
      fallback={<div>No Data</div>}
    />
  );
}

• data: Initial data.
• transform: Array of transformation functions, applied in order.
• render: Render the final result.
• fallback: Content to render if result is null/undefined.

<Scope> (v1.1.7+)

Provides a local scope for children, declaratively defines temporary variables, and simplifies complex rendering logic.

Avoids defining temporary state or calculations outside the component. Declaratively defines local variables for better self-containment. Suitable for forms, computation-heavy rendering, etc.

import { Scope } from "@wwog/react";

function Example() {
  return (
    <Scope let={{ count: 1, text: "Hello" }}>
      {({ count, text }) => (
        <div>
          {text} {count}
        </div>
      )}
    </Scope>
  );
}

// Function-style let is supported
<Scope
  let={(props) => ({ total: props.items.length })}
  props={{ items: [1, 2] }}
  fallback={<div>Empty</div>}
>
  {({ total }) => <div>Total: {total}</div>}
</Scope>;

• let: Object or function defining scope variables.
• props: Props passed to the let function.
• children: Render function for scope variables.
• fallback: Fallback content when empty.

<DateRender> (v1.2.3+)

A declarative component for formatting and rendering dates, simple to use with support for custom formatting.

import { DateRender } from "@wwog/react";

function Example() {
  return (
    <>
      {/* Using default formatting */}
      <DateRender source="2025-05-06">
        {(formatted) => <div>Date: {formatted}</div>}
      </DateRender>

      {/* Using custom formatting */}
      <DateRender
        source={new Date()}
        format={(date) => date.toLocaleDateString("en-US")}
      >
        {(formatted) => <div>Date: {formatted}</div>}
      </DateRender>
    </>
  );
}

• source: The input date to render (Date object, ISO string, or timestamp).
• format: Optional function to format the date, defaults to toLocaleString().
• children: Function to render the formatted date, receives the formatted date as an argument.

<Observer> (v1.3.1+)

A declarative Intersection Observer component for lazy loading, infinite scrolling, and viewport-based interactions.

import { Observer } from "@wwog/react";

function LazyImage({ src, alt }) {
  const [isVisible, setIsVisible] = useState(false);

  return (
    <Observer
      onIntersect={(entry) => {
        if (entry.isIntersecting) {
          setIsVisible(true);
        }
      }}
      threshold={0.1}
      triggerOnce
    >
      <div className="image-container">
        {isVisible ? (
          <img src={src} alt={alt} />
        ) : (
          <div className="placeholder">Loading...</div>
        )}
      </div>
    </Observer>
  );
}

// Infinite scrolling example
function InfiniteList({ items, onLoadMore }) {
  return (
    <div>
      {items.map((item) => (
        <div key={item.id}>{item.content}</div>
      ))}
      <Observer
        onIntersect={(entry) => {
          if (entry.isIntersecting) {
            onLoadMore();
          }
        }}
        rootMargin="100px"
      >
        <div>Loading more...</div>
      </Observer>
    </div>
  );
}

• onIntersect: Callback function triggered when intersection changes, receives IntersectionObserverEntry as parameter.
• threshold: Intersection threshold, can be a number (0-1) or array of numbers, defaults to 0.
• root: Root element for intersection observation, defaults to viewport.
• rootMargin: Root margin for expanding/shrinking the root's bounding box, defaults to "0px".
• triggerOnce: Whether to trigger only once, defaults to false.
• disabled: Whether to disable observation, defaults to false.
• children: Child elements to observe.
• className: CSS class name for the wrapper element.
• style: Inline styles for the wrapper element.

<SizeBox>

Create a fixed-size container for layout adjustment and spacing control.

v1.1.8: Fixed SizeBox not working in 'flex' layouts, add classname props

import { SizeBox } from "@wwog/react";

function Layout() {
  return (
    <div>
      <Header />
      {/* Vertical spacing */}
      <SizeBox height={20} />
      <Content />
      {/* Fixed-size container */}
      <SizeBox width={200} height={150}>
        <SideContent />
      </SizeBox>
    </div>
  );
}

<Styles> (v1.2.7+)

Categorically write styles and basic string styles, with built-in functionality similar to clsx for combining type description object values, supporting duplicate class name removal and nesting.

import { Styles } from "@wwog/react";
import clazz from "./index.module.css";

function Example() {
  return (
    <Styles
      className={{
        base: "p-2 bg-white",
        hover: "hover:bg-gray-100",
        active: "active:bg-gray-200",
        focus: "focus:ring-2",
        other: "button",
      }}
    >
      <Styles className={clazz.button}>
        <button>Click me</button>
      </Styles>
    </Styles>
  );
}

You can also use a container wrapper element:

<Styles
  className={{
    base: ["p-2"],
    hover: { "hover:bg-blue-500": true },
  }}
  asWrapper="span"
>
  Content
</Styles>

• className [string | StylesDescriptor]: Category object for class names, all values in the object will be merged
• asWrapper [boolean | HTMLElementType]: Whether to generate a wrapper containing all classNames, default is false, pass tag name like 'div' or 'span'
• children : Only works with a single child element; if there are multiple child elements, please pass asWrapper to write types and avoid ambiguity

hooks

useControlled

• Applied to states that can be controlled or uncontrolled components

useScreen (v1.3.5+)

Return the current breakpoint name

• Supports passing in custom breakpoints, defaults to the same breakpoint definitions as TailwindCSS

This hook is implemented based on listening. If useScreen needs to be used multiple times without changing the passed parameters, it is recommended to wrap Context

Development notes: Internally implemented via mediaQuery, it does not listen to a specific breakpoint but is optimized to listen only to the previous and next breakpoints of the current breakpoint for better performance.

utils

Internal functions used by some components, which can also be used if needed

ruleChecker (v1.3.9+)

A type-safe data validation utility that provides comprehensive validation rules for different data types with full TypeScript support.

import { ruleChecker } from "@wwog/react";

// Define your data and validation rules
const userData = {
  username: 'john',
  email: '[email protected]',
  age: 25,
  hobbies: ['reading', 'coding']
};

const validationRules = {
  username: { required: true, min: 3, max: 20 },
  email: { required: true, email: true },
  age: { required: true, min: 18, max: 120 },
  hobbies: { min: 1, max: 5, unique: true }
};

// Validate the data
const result = ruleChecker(userData, validationRules);

if (result.valid) {
  console.log('Data is valid:', result.data);
} else {
  console.log('Validation errors:', result.errors);
  console.log('Field-specific errors:', result.fieldErrors);
}

Features:

• Type-safe: Full TypeScript support with automatic type inference
• Multiple data types: Support for strings, numbers, booleans, and arrays
• Comprehensive rules: Built-in validation for length, range, format, uniqueness, etc.
• Custom validators: Support for custom validation functions
• Dependency validation: Validate fields based on other field values
• Array element validation: Validate individual elements within arrays
• Multiple rule support: Apply multiple validation rules to a single field
• Detailed error reporting: Get both general errors and field-specific errors

Available Rules:

• Common rules: required, message, validator, dependsOn
• String rules: min, max, len, regex, email, url, phone
• Number rules: min, max
• Array rules: min, max, len, unique, elementRule
• Boolean rules: Basic validation with custom validators

Complex Example:

const registrationData = {
  username: 'user123',
  email: '[email protected]',
  password: 'SecurePass123',
  confirmPassword: 'SecurePass123',
  age: 25,
  tags: ['developer', 'typescript'],
  terms: true
};

const rules = {
  username: { required: true, min: 3, max: 20, regex: /^[a-zA-Z0-9_]+$/ },
  email: { required: true, email: true },
  password: [
    { required: true, min: 8 },
    { regex: /[A-Z]/, message: 'Password must contain uppercase letter' },
    { regex: /[0-9]/, message: 'Password must contain number' }
  ],
  confirmPassword: {
    required: true,
    validator: (value, data) => value === data.password || 'Passwords do not match'
  },
  age: { required: true, min: 18, max: 120 },
  tags: {
    min: 1,
    max: 10,
    unique: true,
    elementRule: { min: 2, max: 20 } // Each tag must be 2-20 characters
  },
  terms: {
    required: true,
    validator: (value) => value === true || 'You must accept the terms'
  }
};

const result = ruleChecker(registrationData, rules);

createExternalState (v1.2.9+, useGetter added in v1.2.13)

v1.2.21: Refactor the API to move sideeffects into options and enhance support for the transform interface v1.2.13: add useGetter

A lightweight external state management utility that allows you to create and manage state outside the React component tree while maintaining perfect integration with components.

createStorageState (v1.3.2+)

Extends from createExternalState and uses storage to persist state, supports localStorage and sessionStorage

import { createExternalState } from "@wwog/react";

// Create a global theme state
const themeState = createExternalState("light", {
  sideEffect: (newTheme, oldTheme) => {
    console.log(`Theme changed from ${oldTheme} to ${newTheme}`);
  },
});

// Get or modify state from anywhere
console.log(themeState.get()); // 'light'
themeState.set("dark");

// Use the state in components
function ThemeConsumer() {
  const [theme, setTheme] = themeState.use();

  return (
    <div className={theme}>
      Current theme: {theme}
      <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
        Toggle theme
      </button>
    </div>
  );
}

// For read-only access (v1.2.13+)
function ReadOnlyThemeConsumer() {
  const theme = themeState.useGetter();

  return <div>Current theme is: {theme}</div>;
}

• createExternalState<T>(initialState, options?): Creates a state accessible outside components

  • initialState: Initial state value
  • options.sideEffect: Optional side effect function, called on state updates
  • Returns an object with methods:
    • get(): Get the current state value
    • set(newState): Update the state value
    • use(): React Hook, returns [state, setState] for using this state in components
    • useGetter(): React Hook that only returns the state value, useful when you only need to read the state
  • options.transform: - get - set Use cases:

• Global state management (themes, user settings, etc.)

• Cross-component communication

• Reactive state in services or utility classes

• Sharing state with non-React code

formatDate

A relatively standard date formatting function

childrenLoop

Interruptible child node traversal, enabling some branch processes to have ultimate performance

Counter

Incrementally class

safePromiseTry (v1.2.10+)

Support Promise.try Use Promise.try, otherwise use internal implementation

cx (v1.2.5+)

An efficient CSS class name merging utility function, similar to clsx or classnames, but automatically removes duplicate class names.

import { cx } from "@wwog/react";

function Example({ isActive, isDisabled }) {
  return (
    <div
      className={cx("base-class", ["array-class-1", "array-class-2"], {
        "active-class": isActive,
        "disabled-class": isDisabled,
      })}
    >
      Content
    </div>
  );
}

Supports various parameter types:

• String: "class1 class2"
• String array: ["class1", "class2"]
• Object: { "class1": true, "class2": false }
• Any combination of the above types

License