aquasis-fe-components

Shared React UI library for AQUASIS apps (WiseApps Portal, Flowise, Meterwise, Infrawise…): the portal components (profile chip, profile modal, language switcher, theme toggle, helpdesk and release notes) and, since 5.x, a full component set with the AGS design — shadcn/ui-style components (Radix primitives + Tailwind CSS v4) with the same features and prop names as Ant Design 6, without depending on it.

Current version: 6.2.0 — upgrading from 5.x or 4.x? See MIGRATION.md. · Upgrading from 3.x or 4.x? Read MIGRATION.md.

Documentation

| For | Read | |---|---| | App developers (integrating the library) | docs/INTEGRATION.md | | Library developers (changing it) | CONTRIBUTING.md | | Design decisions | docs/ARCHITECTURE.md | | Publishing a version | docs/RELEASING.md | | Upgrading between majors | MIGRATION.md | | 5.x components and their antd 6 parity | docs/v5/PARITY.md | | AGS design system (tokens, rules, component guidelines) | design-system/README.md · developer guide docs/DESIGN-SYSTEM.md | | AI assistants (Claude Code / Cursor) | CLAUDE.md, AGENTS.md, .cursor/rules | | What changed | changelog.md |

Highlights

• Standalone — every component works with zero setup: no Redux, Router, QueryClient or i18n provider needed.
• Version-tolerant — only react / react-dom are shared with your app (>=19.2). Nothing is bundled; the library owns its own ConfigProvider theme, React Query client and i18next instance, so your versions never clash with it.
• AGS design, Tailwind CSS v4 — components are styled with Tailwind utilities and the AGS tokens from aquasis-fe-components/theme.css (light and dark); icons are Font Awesome 6 solid via <Icon>. No antd, no Sass. The design system (token source, generator with a WCAG contrast gate, guidelines) is versioned in design-system/.
• No prop drilling — configure your app's data once with AquasisProvider (or configureAquasis outside React).

Install

pnpm add aquasis-fe-components

Requirements: react / react-dom ≥ 19.2 (peer) and Tailwind CSS v4 in the app, with the library theme and a @source for its dist (details: docs/INTEGRATION.md §8):

/* src/index.css */
@import "tailwindcss";
@import "aquasis-fe-components/theme.css";           /* AGS tokens, @theme, utilities, animations */
@source "../node_modules/aquasis-fe-components/dist"; /* let Tailwind generate the library's classes */

The (scoped) library stylesheet is imported automatically by the JS entry. You can also import it explicitly:

import "aquasis-fe-components/style.css";

Quick start

Zero config (Global Auth SSO cookies provide the session):

import { ProfileChip, ThemeModeToggle } from "aquasis-fe-components";

<ThemeModeToggle />
<ProfileChip gauApiUrl="https://…/ga/api" onLogout={() => navigate("/login")} />

Configure once per app:

import { AquasisProvider, Helpdesk, LanguageSwitcher, ProfileChip, ThemeModeToggle } from "aquasis-fe-components";

<AquasisProvider
  gauApiUrl={import.meta.env.VITE_GLOBAL_AUTH_URL}
  appId={APP_ID}
  appName="Flowise"
  helpdesk={{ submitTicket: (ticket) => api.post("/support/tickets", ticket) }}
>
  <Helpdesk />
  <LanguageSwitcher onChange={(code) => appI18n.changeLanguage(code)} />
  <ThemeModeToggle />
  <ProfileChip onLogout={logout} />
</AquasisProvider>

Sharing data between your app and the library

| Direction | How | |---|---| | App → library (React) | <AquasisProvider …settings> — nearest provider wins; nested providers override only what they set | | App → library (outside React) | configureAquasis({ … }) / resetAquasisConfig() (reactive) | | Library → app | Callbacks: onChange, onLogout, onSaved, onThemeChange, onLanguageChange; subscribeAquasisTheme() |

Every setting resolves as prop → AquasisProvider → configureAquasis → Global Auth cookies/localStorage.

AquasisSettings: gauApiUrl, appId, tenantId, appName, accessToken (string or getter), userId, authCookieEnvironment, theme, language, onThemeChange, onLanguageChange, queryClient, helpdesk, appUrls.

Theme and language are controlled when your app passes them (you receive the callbacks and decide), and uncontrolled otherwise (library store, persisted per appName). Programmatic API: setAquasisTheme, getAquasisTheme, setAquasisLanguage, getAquasisLanguage.

Components

Portal components

| Export | Description | |---|---| | AppSwitcher | WiseApps application selector for the header: current app, the apps the user can access, link to the Portal | | ProfileChip (alias ProfileChipComponent) | Header profile chip: avatar, name, role, logout, overflow menu, profile modal | | UserModal | Profile edit modal | | LanguageSwitcher | Language dropdown (GA API list or built-in list) | | ThemeModeToggle | Light/dark switch | | Helpdesk | Support trigger + ticket form (submitTicket or freshdesk config) | | WhatsNews | Release notes modal (slides, numbered changes, image viewer) | | AquasisProvider | Optional app-level settings |

The portal components are built on the 5.x components below and work standalone (theme, language and message/notification come from the library's own ConfigProvider).

5.x components (AGS design, antd 6 API)

Exported from the package root with antd 6 names and props (import { Button, Table, Form } from "aquasis-fe-components"). Status and the few differences per component: docs/v5/PARITY.md.

| Category | Components | |---|---| | General | Button, FloatButton (+ BackTop), Icon, Typography (Title, Text, Paragraph, Link) | | Layout | Divider, Flex, Row / Col (useBreakpoint), Layout (off-canvas Sider below lg + SiderToggle), Space, Splitter, Masonry | | Navigation | Anchor, Breadcrumb, Dropdown, Menu, Pagination, Steps, Tabs | | Data entry | AutoComplete, Cascader, Checkbox, ColorPicker, DatePicker, Form, Input (TextArea, Password, Search, OTP), InputNumber, Mentions, Radio, Rate, Select, Slider, Switch, TimePicker, Transfer, TreeSelect, Upload | | Data display | Avatar, Badge, Calendar, Card, Carousel, Collapse, Descriptions, Empty, Image, List, Popover, QRCode, Segmented, Statistic, Table, Tag, Timeline, Tooltip, Tour, Tree | | Feedback | Alert, Drawer, message, Modal, notification, Popconfirm, Progress, Result, Skeleton, Spin, Watermark | | Other | Affix, App, ConfigProvider, ThemeScope, cn |

Also exported: WISE_APPS (WiseApps catalogue), useGetProfileUser, useAquasisConfig, useThemeMode, useBreakpoint / useMediaQuery / useIsMobile (responsive hooks), configureAuthCookies, getAuthCookieName, HttpError, Themes, i18n (library instance), BREAKPOINTS, the stacking scale Z_INDEX (--z-* CSS variables, antdZIndexTokens for the antd theme, useZIndex / ZIndexContext — modals above popovers and map widgets, see INTEGRATION.md) and all public types.

Full, interactive docs: pnpm storybook.

Development

pnpm install
pnpm storybook       # component docs on :6006 (+ "Design System/…" foundations)
pnpm test            # unit tests
pnpm tokens          # regenerate the AGS tokens from design-system/scripts/token-source.mjs
pnpm verify          # tokens:check + typecheck + lint + tests (coverage ≥ 80%) + build — required before every PR

src/ui/styles/tokens.css and theme.css are generated (pnpm tokens) — never edit them by hand; see docs/DESIGN-SYSTEM.md.

Workflow, recipes and rules (tests ≥ 80% coverage, stories for every component, standalone architecture, translations through the Excel): CONTRIBUTING.md.

Translations (Excel ⇄ JSON)

Same workflow as FlowiseFrontendViteV2. The Excel (Key + one column per language: EN ES PT BR RO JP, keys like translation.PROFILE.LOGOUT) is the source of truth.

pnpm locales:from-xlsx   # or ConvertLocales2json.bat — Excel → src/i18n/locales/*.json (files fully replaced)
pnpm locales:to-xlsx     # or ConvertLocales2xlsx.bat — JSON → componentslibrary_translations.xlsx

• Folder: LOCALES_XLSX_DIR in .env.local (default \locales on the current drive, e.g. E:\locales).
• File: the newest componentslibrary_translations*.xlsx there (or LOCALES_XLSX_FILE).
• Keys present in the old JSON but not in the Excel are removed and listed as a warning.
• Empty cells = not translated. There is no fallback language: a missing translation renders its own key (e.g. PROFILE.LOGOUT), so what is missing from the Excel is visible in the UI.

Publish

Only via GitHub Actions with npm Trusted Publishing (no tokens): merge the version bump, then create a GitHub Release tagged v<version> (pre-release → beta). Full procedure: docs/RELEASING.md.

Changelog

See changelog.md.

License

ISC · AQUASISPT/FrontendComponents