@hua-labs/hua

v1.2.1

Published

2 months ago

HUA - Ship UX faster: UI + motion + i18n, pre-wired. A framework for React product teams.

Downloads

0High
0Medium
0Low

devindown

hua-labs hua react framework ui-components motion animation i18n internationalization typescript nextjs ssr zustand

@hua-labs/hua

Batteries-included framework for React product teams. Unifies UI components, animation hooks, internationalization, state management, and utilities into a single dependency with automatic provider setup for Next.js.

Features

Pre-wired — UI, motion, i18n, state configured and ready to use
Framework layer — Next.js-optimized with defineConfig and automatic providers
Re-exports 300+ symbols — UI (100+ components), motion-core (40+ hooks), i18n, state
Accessibility — WCAG 2.1 compliant utilities (focus management, skip-to-content)
Loading UX — Built-in delayed loading, suspense wrappers
Error handling — ErrorBoundary built into HuaPage
White-labeling — SSR-compatible CSS variable injection via branding config
GEO support — Generative Engine Optimization for AI search engines
License system — Runtime feature gating with initLicense / requireLicense
Plugin system — Register and retrieve runtime plugins via pluginRegistry

Installation

pnpm add @hua-labs/hua

Peer dependencies: next >=13.0.0, react >=19.0.0, react-dom >=19.0.0, server-only ^0.0.1

Quick Start

// hua.config.ts
import { defineConfig } from "@hua-labs/hua/framework/config";

export default defineConfig({
  preset: "product",
  i18n: {
    defaultLanguage: "ko",
    supportedLanguages: ["ko", "en"],
    namespaces: ["common"],
    translationLoader: "api",
    translationApiPath: "/api/translations",
  },
});

// app/layout.tsx
import { HuaProvider } from "@hua-labs/hua/framework";

export default function RootLayout({ children }) {
  return (
    <html lang="ko">
      <body>
        <HuaProvider>{children}</HuaProvider>
      </body>
    </html>
  );
}

API

| Export | ------------------------ | Button | Card | usePresetMotion | defineConfig | HuaProvider | HuaPage | BrandedButton | BrandedCard | WelcomePage | UnifiedProviders | ErrorBoundary | useMotion | BrandingProvider | useBranding | useBrandingColor | useFocusManagement | useFocusTrap | SkipToContent | LiveRegion | useLiveRegion | useDelayedLoading | useLoadingState | SuspenseWrapper | withSuspense | useData | fetchData | initLicense | getLicense | checkLicense | hasLicense | requireLicense | pluginRegistry | registerPlugin | getPlugin | getAllPlugins | generateGEOMetadata | renderJSONLD | generatePageMetadata | generateCSSVariables | generateTailwindConfig | createI18nMiddleware | Type | Description | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------- | | component | BrandedButton re-exported as Button — auto-applies branding primary/secondary/accent CSS variables when branding is configured. Falls back to @hua-labs/ui Button when no branding. | | component | BrandedCard re-exported as Card — auto-applies branding CSS variables when branding is configured. Falls back to @hua-labs/ui Card when no branding. | | hook | Convenience hook that resolves per-role motion config from the active preset and combines it with reducedMotion / enableAnimations global flags. Returns { config: ComponentMotionConfig | undefined, shouldAnimate: boolean }. | | function | Define hua configuration with presets (product, landing, docs). Available presets: 'product' | 'landing' | 'docs'. Import from '@hua-labs/hua/framework/config'. | | component | Root layout provider — injects Tailwind v4 CSS theme variables at runtime, auto-wires BrandingProvider, ToastProvider, IconProvider, MotionConfigProvider, and i18n. Import from '@hua-labs/hua/framework'. | | component | Page wrapper with automatic motion (vibe prop: 'clean' | 'fancy' | 'minimal'), ErrorBoundary, and i18nKey namespace hint. Import from '@hua-labs/hua/framework'. | | component | Lower-level branded button (same as Button export). Use the Button export from '@hua-labs/hua' or import BrandedButton from '@hua-labs/hua/framework' directly. | | component | Lower-level branded card (same as Card export). Use the Card export from '@hua-labs/hua' or import BrandedCard from '@hua-labs/hua/framework' directly. | | component | Default welcome page for new hua projects. Renders project name, framework feature cards, and quick links with fade/slide animations. Accepts projectName, showFeatures, showQuickLinks props. | | component | Lower-level provider composition component used internally by HuaProvider. Accepts optional config override. Prefer HuaProvider unless you need fine-grained provider control. | | component | React error boundary with optional custom fallback. Built into HuaPage; can also be used standalone. Import from '@hua-labs/hua/framework'. | | hook | Framework-level motion hook — wraps motion-core's useUnifiedMotion. Accepts { type: EntranceType, duration, autoStart } and returns { ref, style, start, stop }. Import from '@hua-labs/hua/framework'. | | component | Context provider that makes branding config (colors, logo, fonts) available to BrandedButton and BrandedCard. Automatically included by HuaProvider when branding is set in defineConfig. | | hook | Access branding config from context. Returns null when no branding is configured. | | hook | Retrieve a specific branding color by key (e.g. 'primary', 'secondary', 'accent'). Returns undefined when no branding is configured. | | hook | A11y hook for programmatic focus management — move focus to a target ref. Import from '@hua-labs/hua/framework'. | | hook | A11y hook that traps keyboard focus within a container (dialogs, drawers). Import from '@hua-labs/hua/framework'. | | component | Accessible skip-to-content link rendered at the top of the page for keyboard navigation. Import from '@hua-labs/hua/framework'. | | component | ARIA live region component for announcing dynamic content changes to screen readers. Import from '@hua-labs/hua/framework'. | | hook | Hook to imperatively announce messages to screen readers via an ARIA live region. Import from '@hua-labs/hua/framework'. | | hook | Prevents loading flicker by delaying the visible loading state by a configurable threshold (default 200ms). Import from '@hua-labs/hua/framework'. | | hook | Manages async loading state with error capture. Import from '@hua-labs/hua/framework'. | | component | Thin Suspense wrapper that accepts a skeleton fallback. Import from '@hua-labs/hua/framework'. | | function | HOC that wraps a component in SuspenseWrapper. Import from '@hua-labs/hua/framework'. | | hook | Client-side data fetching hook with loading/error state. Import from '@hua-labs/hua/framework'. | | function | Async data fetching utility for use outside React components (e.g. RSC, actions). Import from '@hua-labs/hua/framework'. | | function | Initialize the hua license at app startup. Import from '@hua-labs/hua/framework'. | | function | Return the currently active LicenseInfo. Import from '@hua-labs/hua/framework'. | | function | Check whether a specific LicenseFeature is available. Returns LicenseCheckResult. Import from '@hua-labs/hua/framework'. | | function | Boolean guard — true when the specified LicenseFeature is licensed. Import from '@hua-labs/hua/framework'. | | function | Throw if the specified LicenseFeature is not licensed (use at component/route level). Import from '@hua-labs/hua/framework'. | | constant | Central plugin registry instance. Use registerPlugin / getPlugin / getAllPlugins helpers instead of accessing directly. Import from '@hua-labs/hua/framework'. | | function | Register a HuaPlugin at runtime. Import from '@hua-labs/hua/framework'. | | function | Retrieve a registered plugin by name. Import from '@hua-labs/hua/framework'. | | function | Return all registered HuaPlugin instances. Import from '@hua-labs/hua/framework'. | | function | Generate Next.js Metadata object optimized for AI/LLM search engines (Generative Engine Optimization). Server-safe. Import from '@hua-labs/hua/framework'. | | function | Render a JSON-LD script tag for structured data. Server-safe. Import from '@hua-labs/hua/framework'. | | function | Convenience wrapper around Next.js generateMetadata for standard SEO fields. Server-safe. Import from '@hua-labs/hua/framework'. | | function | Generate a CSS string of branding color variables for server-side injection (e.g. inline ). Import from '@hua-labs/hua/framework'. | | function | Generate a Tailwind CSS config object from branding colors. Import from '@hua-labs/hua/framework'. | | function | Create a Next.js middleware handler for i18n locale detection and routing. Import from '@hua-labs/hua/framework'. |

Documentation

Full Documentation

Architecture

@hua-labs/hua is a meta-framework that re-exports from sub-packages and adds a framework layer on top.

@hua-labs/hua
├── /framework        ← HuaProvider, defineConfig, HuaPage (hua-unique)
│   ├── HuaProvider   ← root provider (theme CSS + all sub-providers)
│   ├── HuaPage       ← page wrapper (vibe, ErrorBoundary, motion)
│   ├── defineConfig  ← framework configuration
│   ├── BrandedButton / BrandedCard / WelcomePage
│   ├── a11y          ← useFocusManagement, useFocusTrap, SkipToContent, LiveRegion
│   ├── loading       ← useDelayedLoading, SuspenseWrapper, withSuspense
│   ├── branding      ← BrandingProvider, useBranding, generateCSSVariables
│   ├── license       ← initLicense, requireLicense, hasLicense
│   ├── plugins       ← registerPlugin, getPlugin
│   ├── seo/geo       ← generateGEOMetadata, renderJSONLD, generatePageMetadata
│   └── middleware    ← createI18nMiddleware
├── /ui               ← re-export @hua-labs/ui (100+ components)
├── /motion           ← re-export @hua-labs/motion-core (40+ hooks)
├── /i18n             ← re-export @hua-labs/i18n-core
├── /state            ← re-export @hua-labs/state
├── /formatters       ← re-export @hua-labs/i18n-formatters
├── /hooks            ← re-export @hua-labs/hooks
├── /utils            ← re-export @hua-labs/utils
├── /loaders          ← re-export @hua-labs/i18n-loaders
└── /dot              ← re-export @hua-labs/dot

The main entry (@hua-labs/hua) exports everything flat for convenience. Use subpath imports for tree-shaking.

Important overrides in the main entry:

Button → BrandedButton (not @hua-labs/ui's Button). Use UIButton for the raw version.
Card → BrandedCard (not @hua-labs/ui's Card). Use UICard for the raw version.
usePresetMotion is re-exported from /framework, not from motion-core.

Re-export Categories

| Category | Source Package | Key Exports | | -------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | UI Core | @hua-labs/ui | Button (UIButton), Card (UICard), Input, Modal, Badge, Toast, Icon, Avatar, Progress, Skeleton, Alert, Tooltip, ThemeProvider, ScrollArea, Slot, merge, cn | | UI Form | @hua-labs/ui/form | Form, FormField, Checkbox, Radio, Select, DatePicker, Upload, Autocomplete, ColorPicker, Slider, Textarea | | UI Navigation | @hua-labs/ui/navigation | Navigation, Breadcrumb, Pagination, PageTransition | | UI Overlay | @hua-labs/ui/overlay | Popover, Dropdown, Drawer, BottomSheet, ConfirmModal | | UI Data | @hua-labs/ui/data | Table, CodeBlock | | UI Interactive | @hua-labs/ui/interactive | Accordion, Tabs, Menu, ContextMenu, Command | | UI Advanced | @hua-labs/ui/advanced | EmotionAnalysis, ChatMessage, ScrollProgress, LanguageToggle, FeatureCard, HeroSection, SectionHeader, StatsPanel, BarChart | | Motion Core | @hua-labs/motion-core | useFadeIn, useSlideUp, useScrollReveal, useGesture, useStagger, useTypewriter, MOTION_PRESETS, Motion | | i18n | @hua-labs/i18n-core | useTranslation, useI18n, I18nProvider, Translator, ssrTranslate | | i18n Zustand | @hua-labs/i18n-core-zustand | createZustandI18n, useZustandI18n | | State | @hua-labs/state | createHuaStore, createI18nStore, isStoreRehydrated |

Configuration Presets

| Preset | Use Case | Includes | | --------- | ------------------------- | ------------------------------------- | | product | Full-featured product app | UI + i18n + state + motion + branding | | landing | Marketing/landing pages | UI + motion + GEO | | docs | Documentation sites | UI + i18n + code blocks |

// Minimal config — preset handles defaults
export default defineConfig({ preset: "product" });

Advanced Motion Hooks

The following hooks are re-exported from @hua-labs/motion-core and available from the main @hua-labs/hua entry.

| Hook | Purpose | | ------------------- | ------------------------------------------- | | useButtonEffect | Button press / ripple motion effect | | useScrollToggle | Show/hide elements based on scroll position | | useCardList | Staggered card list entrance animation | | useLoadingSpinner | Programmatic loading spinner control | | useNavigation | Navigation transition orchestration | | useSkeleton | Skeleton loading state management |

Related Packages

License

MIT — HUA Labs

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@hua-labs/hua

Features

Installation

Quick Start

API

Documentation

Architecture

Re-export Categories

Configuration Presets

Advanced Motion Hooks

Related Packages

License