@hanzogui/shell

中文文档
8.4.4发布于 2026/10/31TypeScriptESM + CJS零依赖近 30 天下载 9403

Unified Hanzo shell — Frame (the workspace a signed-in app wears: rail, workspace switcher, account menu), HanzoHeader (the one public bar: Hanzo mega-menu, ⌘K search, the canonical CTA pill, IAM identity), OrgHeader (the signed-in bar), UserOrgDropdown (

原始使用文档
文档目录13 节
  1. Usage
  2. Public header — rich Products mega-menu (7.5.0+)
  3. A nav entry that holds links (8.1.14+)
  4. The one header, and what each surface passes
  5. Identity — one action, one provider
  6. The visitor chat
  7. Org switching, and reaching past your own orgs
  8. Chrome is dark, everywhere
  9. The workspace frame (8.3.19+)
  10. One app list
  11. Exports
  12. Language
  13. Peer dependencies

@hanzogui/shell

The navigation shell for Hanzo-stack apps — one public header, one signed-in header, one cross-app switcher.

Canonical, single source of truth for the shared chrome (HanzoHeader, OrgHeader, HanzoAppLauncher, UserOrgDropdown, OrgCommandPalette, HanzoMark, BeamAvatar, UserAvatar) across billing, console, chat and platform.

Auth comes from @hanzo/iam/react (the canonical IAM client) — never a second session scheme here.

Usage

import { IamProvider, useIam, useOrganizations } from '@hanzo/iam/react'
import { OrgHeader } from '@hanzogui/shell'

export function App() {
  return (
    <IamProvider
      config={{
        serverUrl: 'https://iam.hanzo.ai',
        clientId: 'my-app',
        redirectUri: `${window.location.origin}/auth/callback`,
      }}
    >
      <Shell />
    </IamProvider>
  )
}

function Shell() {
  const { user, logout } = useIam()
  const { organizations, currentOrg, switchOrg } = useOrganizations()
  return (
    <OrgHeader
      currentApp="MyApp"
      currentAppId="myapp"
      user={user ?? undefined}
      organizations={organizations}
      currentOrgId={currentOrg?.id}
      onOrgSwitch={switchOrg}
      onSignOut={logout}
    />
  )
}

Public header — rich Products mega-menu (7.5.0+)

HanzoHeader is the ONE public/marketing header. By default it renders a flat localNav + the universal "Meet Hanzo" menu. Pass productsTaxonomy to opt into the RICH ten-category cloud Products mega-menu (the flagship hanzo.ai UX) — a "Products ⌄" trigger appears next to "Meet Hanzo" and opens <ProductsMegaMenu>. Omit it and the header behaves exactly as before (fully backward compatible).

import { HanzoHeader, HANZO_PRODUCT_CATEGORIES } from '@hanzogui/shell'

// Shared default taxonomy:
<HanzoHeader surface="ai" productsTaxonomy={HANZO_PRODUCT_CATEGORIES} />

// A surface that owns the taxonomy locally passes its own (mapped to
// ProductCategory[]) so its /products/<slug> pages + routes never drift, and
// supplies its own wordmark + identity control via the slots:
<HanzoHeader
  surface="ai"
  productsTaxonomy={myCategories}     // ProductCategory[]
  currentCategoryId="ai"              // highlight the current category header
  currentHref="/models"              // highlight the current leaf
  brandSlot={<MyAnimatedWordmark />}  // replaces the default mark + name
  identitySlot={<MyAccountMenu />}    // far-right identity control
/>

ProductsMegaMenu is also exported standalone (controlled open/onClose/ anchor, keyboard-accessible). HANZO_PRODUCT_CATEGORIES (+ productCategorySlug) is the shared default taxonomy; ProductCategory is the taxonomy type.

A nav entry that holds links (8.1.14+)

A localNav entry (HanzoNav) with items opens them instead of navigating — a card under the label on the desktop, the sheet's own disclosure on a phone. It keeps its href, so the label is a real link before hydration and without JavaScript, and the ⌘K palette indexes what it holds rather than the entry.

localNav: [
  { id: 'solutions', label: 'Solutions', href: '/solutions' },
  {
    id: 'resources',
    label: 'Resources',
    href: '/learn',
    items: [
      { id: 'learn', label: 'Learn', href: '/learn', hint: 'Guides and documentation' },
      { id: 'blog', label: 'Blog', href: '/blog', hint: 'News and deep dives' },
    ],
  },
]

The one header, and what each surface passes

HanzoHeader is the ONE public bar. It renders the chrome; a surface passes only its own data. The brand trigger says Hanzo and opens the same mega-menu everywhere — Flagship products · Platform · Install · Resources, projected from HANZO_PRODUCTS in hanzo-registry.ts. That menu is identical on every surface by construction; nothing about it is per-surface.

<HanzoHeader
  surface="ai" // id · hostname · or a HanzoSurface object
  productsTaxonomy={HANZO_PRODUCT_CATEGORIES} // opt into the rich Products menu
  tryMenu // primary action opens the menu
  auth={{ user, onSignIn, onSignOut }} // the identity cluster
  commands={myPages} // what ⌘K should also find
/>
Surfacesurfacesecondary nav (its data)primary pill
hanzo.ai"ai"Models · Agents · Solutions · Developers · Pricing · EnterpriseTry Hanzo
hanzo.app"app"Features · Templates · Pricing · Business+ New project
docs.hanzo.ai"docs"API · CLI · MCP · SDKsGet API key
console.hanzo.ai"console"Docs · API · Statusnone (signed in)

A surface that owns its nav passes a HanzoSurface object instead of an id. The LABEL of the primary action is the surface's; its STYLE never varies — one white pill, radius 999, rgb(250,250,250), 34 tall, 13px/600, from cta(true).

Identity — one action, one provider

Hanzo IAM is the only identity provider, and this package never runs a session. Pass the mapped user and your @hanzo/iam client's calls; the cluster renders one sign-in action when signed out and the account menu when signed in. There is no password field, no provider buttons and no email fallback here on purpose — every method lives on the IAM login page, which is the only place that knows which are enabled.

const { user, startLogin, logout } = useIam()
<HanzoHeader surface="docs" auth={{ user, onSignIn: startLogin, onSignOut: logout }} />

The visitor chat

One chat, two docks. corner mounts the small launcher in the bottom-right; without it the same chat is a right-side drawer. Model defaults to enso-free.

<AskHanzo corner authToken={bearer} />          // signed in — meters to the user
<AskHanzo corner auth={{ onSignIn }} />         // signed out — invites sign-in
<AskHanzo corner onSubmit={myTransport} />      // the host owns the transport

There is no signed-out credential, by design. A publishable key (pk-) is read-only and refuses completions; a secret key (sk-) is spendable, so putting one in shared chrome would ship a spendable secret to every page that mounts it. Anonymous inference needs a SERVER holding the key — never the browser.

So with no authToken and no onSubmit, the card does not render a composer that would be refused: it shows one sign-in action against the same provider as the header. Give it auth (the HanzoAuth shape the header takes) and that action runs the host's IAM login; omit it and the action links to the site's own /login.

Org switching, and reaching past your own orgs

UserOrgDropdown is the ONE switcher (OrgHeader mounts it). Your own orgs render immediately and switching them is unchanged. Supply findOrgs and it gains a search field: the server filters, sorts and pages; the client only asks.

<OrgHeader
  organizations={mine} // instant, no round trip
  onOrgSwitch={switchOrg}
  findOrgs={({ q, cursor }) => api.orgs({ q, cursor })}
  onMasquerade={startMasquerade} // only reachable for reach rows
  masquerade={actingAs} // renders the persistent sign
  onMasqueradeStop={stopMasquerade}
/>

A page the server marks reach: true lists orgs beyond the caller's memberships — the SuperAdmin reach. The client never computes a privilege: no reach page, no section, no way to ask for one. Switching your own org calls onOrgSwitch; acting as someone else's calls onMasquerade, because they are different acts. While one runs, <Masquerade> names the org in the bar with a one-click exit, and it rides with the switcher — you get it by mounting.

ORG_DOMAINS maps each org to its branded domains — Hanzo / Lux / Zoo / Pars baked in — and the signed-in chrome reads it for the account and billing links.

Chrome is dark, everywhere

The bar, its menus, the launcher and the palette are one material: 60px of glass (rgba(9,9,11,0.72) over blur(20px) saturate(1.8), no hairline) with dark menus hanging off it — on every surface, in every host theme. A menu attached to the chrome wears PANEL and stays dark under a light theme; a menu inside the page body is content and follows the theme. No ground here reads --background or any other inverting token, which is what keeps that true. Get it by MOUNTING the component; if you must build a chrome-attached menu we do not ship, spread PANEL rather than matching a colour by hand.

The workspace frame (8.3.19+)

Frame is the shell a signed-in Hanzo app wears — hanzo.ai and the Hanzo App mount the same one, the way claude.ai wears one frame around chat and code.

import { Frame, Account, Scope, useScope, Beside, useFrame } from '@hanzogui/shell'

<Frame
  sections={[{ id: 'chat', label: 'Chat', icon: MessageSquare, href: '/chat' }, …]}
  active="chat"
  navigate={(href) => router.push(href)}
  back={router.back}
  forward={router.forward}
  workspace={<OrgProjectSwitcher … />}          // top of the sidebar: the ONE switcher
  scope={<Scope projects={…} project={…} onProject={…} environments={…} />} // the bar
  find={{ label: 'hanzo', open: () => setFinding(true) }}                   // ⌘K too
  list={<WhatTheSectionHolds />}
  account={<Account name={…} email={…} onProfile={…} onNotifications={…}
                    onAppearance={…} onSecurity={…} onSignOut={logout} />}
  settings={() => showSettings()}
  side={{ open, close, toggles }}
>
  {room}
</Frame>
  • Rail: the sections as marks — the sidebar SHUT on a laptop (an explicit, per-device toggle; nothing opens under a passing pointer) and the tab bar along the bottom of a phone, four sections and More.
  • Strip, opt-in: pass strip (an org's mark) and the rail stands beside the OPEN sidebar with that mark at its head, the way hanzo.team draws it. Off by default: without it there is no far-left strip.
  • Sidebar: the workspace switcher at the top, the sections, what the section holds (list), the host's rows (foot), the account at the foot. Resizable by its edge, and a sheet on a phone. Inside it, useFrame().pick puts the sheet away once a row is chosen.
  • Account: Profile, Notifications, Appearance, Security, Sign out, in that order, and no balance — credits are the workspace's, under Billing. A row the host gives nowhere to go is not drawn.
  • Scope: project and environment, one resource scope in the bar. useScope(org) keeps the last project per workspace and restores it on a switch, or falls back visibly to All projects; no environment is drawn that the platform did not name. Its keys (hanzo:scope:*) are per workspace, not per person: the host clears them when the person changes, as hanzo.ai and the Hanzo App do for every hanzo* key.
  • Sections point at a path of the app (/…) or an https:// address on another host, which is drawn as a link. Anything else is not drawn.
  • Beside: a room puts content in the column beside it; the frame owns the column, the room owns what is in it.
  • Notifications: the reader's own (/v1/team/inbox), read through the host's call — the package holds no credential.

The frame follows the host's theme (FRAME in theme.ts reads gui's and @hanzo/design's ladder), unlike the chrome, which is dark everywhere.

One app list

HANZO_APPS is the only app registry. HanzoAppLauncher renders it; OrgHeader mounts that launcher; OrgCommandPalette derives its cross-app commands from it. Pass apps to any of the three to override.

Exports

  • HanzoHeader — the ONE public header
  • HanzoIdentity, HanzoAuth — the identity cluster (IAM, one action)
  • AskHanzo — the visitor chat (corner for the bottom-right launcher)
  • Masquerade — the sign that a masquerade is running, and its exit
  • OrgHeader, OrgHeaderProps, OrgSearch — THE signed-in bar: launcher, breadcrumb, centre search, org switcher + user menu, headerLeft for the surface's own leading controls
  • HanzoAppLauncher — the cross-app switcher
  • UserOrgDropdown, UserOrgDropdownProps — the ONE org switcher
  • OrgQuery, OrgPage — what the switcher asks the server, and its answer
  • OrgCommandPalette, OrgCommandItem — ⌘K palette
  • HanzoMark, HanzoWordmark — brand mark (brandMenu opts into the right-click brand menu)
  • Frame, Beside, useFrame, Section, Side, Find — the workspace frame
  • Account — the account card and menu at the foot of the sidebar
  • Scope, useScope — project and environment in the bar
  • Notifications, Notice — the reader's notifications page
  • BeamAvatar, UserAvatar — avatars
  • HANZO_APPS, ORG_DOMAINS — the app registry and the per-org domain map
  • HanzoApp, HanzoUser, HanzoOrg, OrgDomains — types

Language

Every word the shell draws goes through @hanzo/i18n: mount its I18nProvider once and the menus, the palette, the frame and the account controls read in the reader's language. Without a provider they read in English. What a host passes in — a palette command, a section, a person's or an org's name — is drawn as given.

Peer dependencies

  • react, react-dom
  • @hanzo/i18n (>= 0.4.0) — one provider context, the host's

版本与发布记录

@hanzogui/shell 共发布 100 个版本,首次发布于 2026/06/09;过去 12 个月发布了 100 个版本。

版本发布日期距今
8.4.4latest2026/10/3117 天前
8.4.32026/10/3018 天前
8.4.22026/10/2325 天前
8.4.12026/10/2325 天前
8.4.02026/10/2325 天前
8.3.212026/10/051 个月前

其他发布通道:stable → 8.0.1。

关于 @hanzogui/shell 的常见问题

@hanzogui/shell 是什么?

Unified Hanzo shell — Frame (the workspace a signed-in app wears: rail, workspace switcher, account menu), HanzoHeader (the one public bar: Hanzo mega-menu, ⌘K search, the canonical CTA pill, IAM identity), OrgHeader (the signed-in bar), UserOrgDropdown (

如何安装 @hanzogui/shell?

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

@hanzogui/shell 支持 TypeScript 吗?

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

@hanzogui/shell 支持 ESM 还是 CommonJS?

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

@hanzogui/shell 可以商用吗?

@hanzogui/shell 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@hanzogui/shell 的下载量有多少?

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

@hanzogui/shell 还在维护吗?

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