@hanzo/data

中文文档
1.4.8发布于 2026/11/17MITTypeScriptESM + CJS近 30 天下载 1.3万

Hanzo Data — cross-platform, metadata-driven data-app components (typed fields, record table, kanban board, record detail, saved views) on @hanzo/gui. The universal object/field/record/view layer that powers any Base-backed CRM, CMS, or commerce app on we

原始使用文档
文档目录6 节
  1. Install
  2. The flagship: RecordsView
  3. Field types
  4. Extend
  5. Pure logic (host-usable, tested)
  6. Surface

@hanzo/data

Cross-platform, metadata-driven data-app components for any Hanzo Base-backed app — CRM, CMS, commerce, or a one-off internal tool. One model (typed fields → records → views) renders everywhere, on web, native (iOS), and desktop, because it's built on @hanzo/gui and drawn with @hanzo/ui's record kit — table ⇆ board, filter, sort, group, inline edit, saved views.

An object is a set of typed fields. A record is values for those fields. Every view — table, board, detail — renders from that one model, dispatched through a registry, so adding a field type is one registration, never a switch edit. A business app (CRM/CMS/ERP) is just a curated set of views over these components.

Install

bun add @hanzo/data @hanzo/ui @hanzo/gui

@hanzo/ui, @hanzo/gui and react are peers. Mount it under <Hanzo> (the @hanzo/ui root) and the cells, cards and editors follow the theme. Wrap a record surface in <Density value="compact"> for the record density: 32px rows and controls, an 8px gutter, 13px text; without it the table keeps 44px rows and the editors the kit's 36px.

The flagship: RecordsView

One shell turns any collection into a record surface — a toolbar (view switch, search, filter builder, sort builder, board group-by) over a DataTable or a BoardView, driven by a single ViewConfig. Presentational + data-injected: the host supplies raw records and the persistence callbacks; the view owns interaction state.

import { RecordsView, type FieldDefinition } from '@hanzo/data'

<RecordsView
  fields={fields}
  records={records}                              // raw rows; the view applies search + filter + sort
  onOpen={openDetail}                            // expand a record
  onEditCommit={(rec, field, value) => save(rec, field, value)}  // inline cell / board edit
  onCreate={createRecord}
  savedViews={{ views, activeId, onSelect, onSave, onDelete, deletable }}  // optional named views; deletable(id) keeps built-ins
/>
  • DataTable — click-to-sort headers, drag-resize + drag-reorder columns, row selection with a header select-all, inline cell editing (the field's own editor), pagination, hover-reveal open, honest empty/loading.
  • BoardView — kanban grouped by a select/status/boolean/relation field; drag a card to another lane and the record patch is emitted (optimistic, reverts on failure).
  • RecordDetail — a titled panel of fields, optionally inline-editable, with a related slot. RecordForm — the create/edit form.

A view's rules combine by match: and (every rule, the default) or or (any one); the word between two rules switches it. Numbers, money and dates also filter between two values, either end left open, and a range that ends on a day takes that day whole.

A server's page. For a collection too large to hold, the host runs the view as its query and passes the one page it got back with remote: the records are shown as given, never re-filtered, and the pager reads the total.

<RecordsView
  fields={fields}
  records={page.items}                                       // already searched, filtered, sorted
  view={view}
  onViewChange={setView}                                     // the host re-queries on every change
  remote={{ page: page.page, total: page.total, onPage: setPageNumber }}
/>

Field types

text · longText · number · percent · currency · boolean · select · multiSelect · date · dateTime · email · url · links · phone · rating · relation · json · uuid · fullName · address · files · richText · position · actor

Each type has a read Display and (where editable) an Input, resolved by the registry, both from @hanzo/ui's record kit: a select is a Tag in its option's colour (thirty data hues, TagColor) and its editor a searchable menu with a "No …" row; several values are one line of tags or pills with a +N; emails, links and phones are pills with their mailto / https / tel target; a relation is a record chip with an Avatar; a currency is an amount with a currency picker at its start; a phone a number with a calling-code picker; a date the kit's calendar under a typed day; a rating a row of stars. Enter commits an edit, Escape cancels it.

Extend

Register a renderer for any type — built-in or custom — and it works in every view:

import { registerField } from '@hanzo/data'

registerField('rating', { Display: MyStars, Input: MyStarPicker })

Pure logic (host-usable, tested)

The sort / filter / search / group / view helpers are pure and exported (also on subpaths @hanzo/data/{table,board,view}/logic so a Node host can import them with no gui runtime):

import { applyView, sortRecords, filterRecords, boardColumns } from '@hanzo/data'

Surface

  • Model — FieldDefinition, FieldType, FieldMetadata, SelectOption, TagColor, CurrencyValue, LinkValue, AddressValue, FullNameValue, ActorValue
  • Lists — regions(), currencies() (from Intl, in the reader's language), CALLING (E.164 calling codes)
  • Views — RecordsView, DataTable, BoardView, RecordDetail, RecordForm, RecordCard, RecordsToolbar
  • Primitives — Menu, MenuItem, CheckBox, Toggle, Calendar
  • Routers / Registry — FieldDisplay, FieldInput, isEditable, registerField, getFieldRenderers
  • Logic — applyView, sortRecords, filterRecords, searchRecords, paginate, boardColumns, movePatch, operatorsForType, emptyView, describeView, …
  • Theme — TAG_TONES, tagTone (the data palette's tag pairs as custom properties); tokens (the old fixed dark palette, kept for callers)

MIT · Hanzo AI — see LICENSE.md. HIP-0137 (hanzoai/hips).

版本与发布记录

@hanzo/data 共发布 19 个版本,首次发布于 2024/07/24;过去 12 个月发布了 17 个版本。

版本发布日期距今
1.4.8latest2026/11/17今天
1.4.72026/11/17今天
1.4.62026/11/134 天前
1.4.52026/11/0215 天前
1.4.42026/11/0215 天前
1.4.32026/11/0215 天前

关于 @hanzo/data 的常见问题

@hanzo/data 是什么?

Hanzo Data — cross-platform, metadata-driven data-app components (typed fields, record table, kanban board, record detail, saved views) on @hanzo/gui. The universal object/field/record/view layer that powers any Base-backed CRM, CMS, or commerce app on we

如何安装 @hanzo/data?

在项目目录运行 npm install @hanzo/data,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=19.2.8)、@hanzo/ui(>=8.28.0)、@hanzo/gui(>=8.3.5)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@hanzo/data 支持 TypeScript 吗?

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

@hanzo/data 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@hanzo/data 可以商用吗?

@hanzo/data 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@hanzo/data 的下载量有多少?

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

@hanzo/data 还在维护吗?

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