@glimstone/react

中文文档
4.5.4发布于 2026/11/16AGPL-3.0-onlyTypeScriptES Module近 30 天下载 3918

GlimStone's components for React

原始使用文档
文档目录4 节
  1. Using it
  2. What's here
  3. What is not here
  4. The Info tile

@glimstone/react

The components of GlimStone for React 19. @glimstone/core says what a control must look like and decides what it shows; these say what a control is, so an app uses them rather than rebuilding them.

That distinction is the reason this package exists. Two apps built from the prose alone arrived at the same design language in two different dialects: one calls the switch Toggle and keeps it in components/Toggle.tsx, the other calls it Switch and keeps it inside a Field.tsx next to six other controls; one has ConfirmDialog, the other has Confirm. Every one of those is a correct reading of the same document, and every rule would then have to be re-applied by hand in each dialect.

Using it

npm install @glimstone/core @glimstone/react
import "@glimstone/core/tokens.css";
import { applyCachedAppearance, applyStoredLabelModes } from "@glimstone/core";
import { Button, setGlyphResolver } from "@glimstone/react";
import { Select } from "@glimstone/react/Select";

applyCachedAppearance();
applyStoredLabelModes();
setGlyphResolver((key) => appGlyphs[key]);

Call the two apply functions at the app root before the first render, not from the settings page that edits them, or the app opens in the default look and snaps over. setStoragePrefix() before them keeps choices an app already stored under its own name. Under Tailwind v4 load @glimstone/core/tailwind-theme.css after the tokens; the components themselves use no Tailwind class.

Select, Combobox and Slider come from their own entries and need @zag-js/react with their machine packages (@zag-js/select and @zag-js/menu, @zag-js/combobox, @zag-js/slider). The rest of the package needs none of them.

What's here

ComponentWhat it is
ButtonEvery button, including the label engine's text/glyph/both modes and the chip form
ToggleThe switch. Never a checkbox
CardThe surface, and the one place a section heading is drawn
BadgeStatus pills and the filled section heading the card draws
SelectThe one dropdown, on Zag's select machine and on its menu machine for a list with submenus
ComboboxA field that filters a long list as somebody types
SliderA value on a range, with the value in words beside the label
DropdownListboxDeprecated, use Select
ConfirmDialog + useConfirmThe confirm surface for a destructive action, and the hook that gives it a portal, Escape, the Tab trap and focus back to the control that asked
ToastViewportTransient feedback; the queue is the core's toastEngine
InfoBubble, IconTipButtonThe "(i)" explanation and the hover name on an icon-only control
InfoTileThe Info tile with its Version, Help and About cards, each also on its own
ReadmeButtonThe button in the shape of the README's, with its segments
CryptoDonateDialog, CoffeeDialog, PaypalDialogThe three windows to give
SelectorThe one horizontal selector: tabs, filter bars, segmented pickers, one value or many, and with orientation="vertical" the column of tiles beside a settings area's pages
NumberFieldA number with its two steppers inside the field and the wheel while it has focus
SidebarRowOne row of the rail: glyph, words by the label mode, the current page and a count
EmptyStateWhat a list, table or panel shows when it holds nothing
SubCardA filled inset group inside a card, which replaces a fold-out
UnavailableNoticeWhat stands where a control would be, when the environment forbids the thing entirely
WindowBarA desktop app's own title bar on Windows and Linux
WindowThe general window: the title notch, a body for anything and a foot that adds Cancel or Close by itself; windows stack
ContextMenu, MenuBarA menu at a point and the row of menus in a head bar, with submenus, rows that tick a box, choices, key caps and counts. Opened with the pointer, the first row shows its ring only once a key is pressed
CheckboxThe drawn box for "Don't show again" and for choices applied together, slim for the box alone in a dense row. Every setting is a Toggle
Kbd, PillA key cap, and the quiet data pill of a list row
TextField, TextAreaA line of text and a few lines of text, borderless and filled, in the widths a row needs, with error for a value they cannot take
FieldErrorThe line under a field whose value it cannot take, for an app's own field
FieldRow, FieldRowGroupOne labelled row: the name at its start with an "(i)", the control at its end, named by the row, or a lone value as a pill, and rows that share one column for their names. useFieldName gives an app's own control the same name
GlyphFieldA field with a glyph inside it, such as a filter, and controls after it in the box
TableA short list of facts in columns
PasswordField, CopyFieldA secret with the reveal eye inside the field, and a value in monospace with a button that copies it
Fortress, FortressPairing, InstanceCard, FortressAppCard, FortressPermissionsThe fortress in an app's Instances tab: the app's own cards as children, the switch for the other apps, a card per app with a row per instance, the permissions with a switch each, and the windows to join with the phrase, remove an instance and show the phrase beside its QR code. FortressPairing is the card in the pairing settings that changes the phrase and leaves
SignInCard, SignInFieldThe sign-in page: the app's logo and name, the password, a code when the app asks for one, a passkey and the reset form in the same card. The app's own fields, buttons and steps go into fields, actions and step, and SignInField gives a field of the app's own the label above it
PathField, TreeA path with a button that asks the app for one, and a hierarchy loaded as it opens, for the picker behind that button
ListRow, RowMark, GlyphTileOne row of a list with a tile, badges and buttons that come in on hover, the round mark on a row picked for an action on many, and a small holder for a glyph
ListTableThe list of a list page: sorting by a click on a heading, a filter per column, a search that floats inside it, and rows picked as in a file manager
IconButtonA glyph in a square in every label mode, for a row that keeps its text, as a link with href, on or off with pressed, and absent to hold a missing button's place
Meter, ProgressBarA level such as a disk's, red from a threshold and quiet for a footer line, and work toward its end with a sheen while it runs. Only the bar moves
BusyRing, SkeletonRowThe ring that turns while the app works on something, and a row that holds a list row's place while the list loads. Both show only after 400 ms
Popover, SheetA small panel beside its trigger in the top layer, and a panel at the end edge for a row's details, a <dialog> shown modal with a window's foot
ColorPickerThe square, the hue bar, a preview with the name the colour proposes, the hex field and Apply, in the page or floating beside its swatch
useLabelMode, useTipBubble, usePortalHueThe small hooks the components need
glyphsThe marks the components draw themselves, and setGlyphResolver, the seam an app registers its own icon set through

What is not here

The icon set. An icon's meaning belongs to the app: only it knows that its own action is called "backup now". GlimStone ships the assortment as a specification (glyphs.md in the core) and one function, setGlyphResolver, that a button asks by meaning. Register it once at boot and every button can be shown in glyph mode; skip it and buttons fall back to the glyph they are handed, then to text alone.

Translation. Every string is a prop. The components carry the order and the behaviour, the app carries its own language.

Data. No component fetches anything. The Version card takes its versions as props and its update check as a function rather than reading a health endpoint, so the same component serves an app with a different one.

The Info tile

InfoTile takes one prop object per card and a hueIndex for the first of them; the others take the next positions. It returns the cards without a wrapper, so they stack in the page's own rhythm.

  • Version: rows lists the app first, then GlimStone and every component the app ships, each with a name, an optional sub line, the version read from the build and the repoUrl whose release page the number opens. A row without repoUrl, or a build that is not a published release, shows the number as plain text. The GlimStone row sets latest, so its number opens the newest release at GLIMSTONE_RELEASE_URL. updateCheck.run checks them all and resolves to how many have a newer release; the button turns ok with upToDate, warn with updatesFound(n), or danger with checkFailed and a shake when it rejects. The app puts the reason for a failure in its toast. One button stands before the check: whatsNew, the app's own "New · n" button, which opens its window with the release notes and the changes as tabs, or, in an app that marks no changes, "Release notes" from onReleaseNotes with text.releaseNotes, which opens the notes alone. The card never draws both.
  • Help: the report sentence, GitHub, Discord with IconDiscord as discordGlyph when the sentence names Discord and discordUrl and text.discordButton are set, Email with MAIL_SVG when the sentence names a mail route and mailAddress is set, the manual when manualUrl and text.manual are set, with MANUAL_SVG as manualGlyph and "Open" as text.manualSub, and the bug report when onBugReport and text.bugReport are set, with IconDiagnostics as bugGlyph and "Download" as text.bugReportSub.
  • About: the maker's sentence, then the sentence about the money with the give row under it.

The glyphs on the update check come from the app's resolver under the keys about.checkUpdates, about.upToDate, about.updatesFound and about.checkFailed, and the one on "Release notes" under about.releaseNotes.

版本与发布记录

@glimstone/react 共发布 22 个版本,首次发布于 2026/11/04;过去 12 个月发布了 22 个版本。

版本发布日期距今
4.5.4latest2026/11/16今天
4.5.32026/11/16今天
4.5.22026/11/161 天前
4.5.12026/11/151 天前
4.5.02026/11/151 天前
4.4.12026/11/142 天前

关于 @glimstone/react 的常见问题

@glimstone/react 是什么?

GlimStone's components for React

如何安装 @glimstone/react?

在项目目录运行 npm install @glimstone/react,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(^19.0.0)、react-dom(^19.0.0)、@zag-js/menu(^1.48.0)、@zag-js/tour(^1.48.0)、@zag-js/react(^1.48.0)、@zag-js/steps(^1.48.0)、@zag-js/timer(^1.48.0)、@zag-js/avatar(^1.48.0)、@zag-js/select(^1.48.0)、@zag-js/slider(^1.48.0)、@zag-js/marquee(^1.48.0)、@zag-js/carousel(^1.48.0)、@zag-js/combobox(^1.48.0)、@zag-js/splitter(^1.48.0)、@zag-js/accordion(^1.48.0)、@zag-js/pin-input(^1.48.0)、@zag-js/hover-card(^1.48.0)、@zag-js/pagination(^1.48.0)、@zag-js/tags-input(^1.48.0)、@zag-js/collapsible(^1.48.0)、@zag-js/date-picker(^1.48.0)、@zag-js/file-upload(^1.48.0)、@zag-js/scroll-area(^1.48.0)、@zag-js/angle-slider(^1.48.0)、@zag-js/rating-group(^1.48.0)、@zag-js/signature-pad(^1.48.0)、@zag-js/floating-panel(^1.48.0)、@internationalized/date(^3.12.4)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@glimstone/react 支持 TypeScript 吗?

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

@glimstone/react 支持 ESM 还是 CommonJS?

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

@glimstone/react 可以商用吗?

@glimstone/react 使用 AGPL-3.0-only 许可。最严格的 Copyleft:除分发外,通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括,不构成法律意见,请以许可原文为准。

@glimstone/react 的下载量有多少?

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

@glimstone/react 还在维护吗?

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