@haatlabs-core/ui

中文文档
0.18.5发布于 2026/11/14Apache-2.0TypeScriptES Module近 30 天下载 4676

React components for an app's dashboard, styled by the app.

原始使用文档
文档目录3 节
  1. Install
  2. The dashboard look
  3. @haatlabs-core/ui/client

@haatlabs-core/ui

React components the apps share. Fonts, theme and colours stay with each app: the components carry class names, and each app's stylesheet styles them.

import { Drawer, EmptyState, FullScreen, Loading, SearchBox } from '@haatlabs-core/ui';
ComponentWhat it isClass names it uses
EmptyStateWhat a list shows when it has nothing: a title and what to do next.empty
LoadingPlaceholder rows (rows) or a spinner, labelled for assistive technology.skeleton, .skeleton-row, .skeleton-box, .skeleton-line, .short, .loading, .spinner
DrawerA card's detail beside its list, with a link to its full page; Escape closes it.drawer, .drawer-bar, .drawer-body, .row, .spread
FullScreenA picture over the whole screen; Escape or a click outside closes it.full-screen, .full-screen-close
SearchBoxCalls onSearch with the trimmed phrase once typing pauses for 300 ms.search-box

react, react-dom and react-router-dom are peers: the app's own copies are used.

Install

pnpm add @haatlabs-core/ui

It leaves these packages to your app, so the app holds one copy: react, react-dom, react-router-dom, @tanstack/react-query, zod.

The dashboard look

One look for every Haatlabs dashboard: a sidebar app shell, light and dark themes, an accent per product.

import '@fontsource-variable/plus-jakarta-sans/index.css';
import '@fontsource/jetbrains-mono/500.css';
import { AppShell, ThemeStyles } from '@haatlabs-core/ui';

<ThemeStyles accent="indigo" />          // indigo, coral, teal, green, or { solid, textLight, … }
<AppShell
  brand={<Logo />}
  nav={[{ items: [{ label: 'Home', to: '/home' }] }, { label: 'Billing', items: [...] }]}
  account={{ name, detail: email, onSignOut, signingOut }}
  statusChip={<StatusChip to="/credits">₹480.00</StatusChip>}
>
  <Routes>…</Routes>
</AppShell>
  • Theme: follows the computer's setting until someone picks dark or light in the sidebar's switch; the choice is kept in the browser (haatlabs:theme). Serve THEME_BOOT_SCRIPT as public/theme-boot.js and load it in <head> (<script src="/theme-boot.js"></script>): the pages' CSP forbids inline scripts, and without it a dark page flashes light.
  • Tokens: --hl-* CSS variables (--hl-surface, --hl-text, --hl-accent, …), every accent tested for 4.5:1 contrast in both themes.
  • Pieces: PageHeader, Card, Callout, Checklist, StatusChip, ShellSearch.
  • The shell leaves <main> to the pages; its content area is #main, the skip link's target.
  • Adopting it in an app: drop LoginPage's accent/glow props (the theme's accent and link colour apply), and point the app's own colour variables at the theme (--surface: var(--hl-surface, #fff)), so its pages follow the dark theme.

@haatlabs-core/ui/client

What an app's pages use to talk to its API, and the sign-in pages:

  • createTransport({ baseUrl, credentials, fetch, envelope }): call, adminCall, send, queryOf. Writes carry the CSRF header (x-csrf-token); administrators' writes carry x-admin-csrf. A failure is an ApiError with the API's code and status.
  • cookieCredentials(appName): the dashboard's session cookie and its CSRF cookie <appName>_csrf. Inside Shopify admin, pass { kind: 'bearer', getToken }.
  • createQueryClient(): reads and writes that fail on the network or with a 5xx are tried again, twice at most; a 401 asks for me again.
  • LoginPage({ client, aside }) and EmailSignInPanel({ client }): signing in with a code, and giving a store installed from Shopify an email to sign in with.

@tanstack/react-query and zod are peers.

版本与发布记录

@haatlabs-core/ui 共发布 26 个版本,首次发布于 2026/11/07;过去 12 个月发布了 26 个版本。

版本发布日期距今
0.18.5latest2026/11/144 天前
0.18.42026/11/134 天前
0.18.32026/11/134 天前
0.18.22026/11/134 天前
0.18.12026/11/134 天前
0.18.02026/11/134 天前

关于 @haatlabs-core/ui 的常见问题

@haatlabs-core/ui 是什么?

React components for an app's dashboard, styled by the app.

如何安装 @haatlabs-core/ui?

在项目目录运行 npm install @haatlabs-core/ui,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:zod(^4.6.5)、react(^19.3.0)、react-dom(^19.3.0)、react-router-dom(^7.18.4)、@tanstack/react-query(^5.104.1)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@haatlabs-core/ui 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@haatlabs-core/ui 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@haatlabs-core/ui 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=24。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@haatlabs-core/ui 可以商用吗?

@haatlabs-core/ui 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@haatlabs-core/ui 的下载量有多少?

根据 npm 官方下载统计,@haatlabs-core/ui 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,676 次,日均约 156 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@haatlabs-core/ui 还在维护吗?

最新版本 0.18.5 发布于 2026/11/14(4 天前);至今共发布 26 个版本,其中过去 12 个月发布了 26 个;首次发布于 2026/11/07。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。