@henryx/onedot-ui

@henryx/onedot-ui

Vue 3 components and design tokens for the Onedot team.

Documentation

The npm package includes the Markdown user manual. After installation, open node_modules/@henryx/onedot-ui/用户使用手册/README.md for offline reading or give the manual directory to a coding agent. Start with the capability list, then read the relevant component guides.

See the team's deployed Storybook for the complete capability catalog and interactive component examples.

Local documentation starts at the structure index. The unified application navigation is available through the standard OdAppShell data mode and the standalone OdNavigation tree. Product scope, acceptance requirements, and the implementation record are documented in the requirements and implementation tasks.

OdDrawer is exported for right-side detail and editing workflows. It provides async close guards, close reasons, busy locking, focus/lifecycle controls and instance-level overlay registration. See the OdDrawer guide, the capability list, and its implementation tasks.

Install

pnpm add @henryx/onedot-ui

Usage

import { createApp } from 'vue'
import { OnedotUI } from '@henryx/onedot-ui'
import '@henryx/onedot-ui/style.css'
import App from './App.vue'

createApp(App).use(OnedotUI).mount('#app')

OnedotUI also initializes the pinned PrimeVue 4.5.5 and Aura configuration used inside Od components.

Components use the od- CSS namespace. Theme variables can be overridden on :root or on a containing element without changing component markup. The default --od-font-family uses bundled JetBrains Mono 300/400/500/600/700 for Onedot UI and PrimeVue components, with system Chinese font fallbacks. The managed Aura preset aligns common form controls to the Onedot 13/14/16px size scale.

OdButton uses nativeType (or native-type in templates) for the native button type. Passing the HTML type attribute does not change it and emits a development warning. See the OdButton guide.

Tables

OdTable provides local tables and remote queries. The example below uses the existing local mode:

<script setup lang="ts">
import { OdTable, type OdTableColumn } from '@henryx/onedot-ui'

const columns: OdTableColumn[] = [
  { field: 'name', title: 'Name', dataType: 'text', searchable: true, sortable: true },
]
const rows = [{ id: 1, name: 'Ada' }]
</script>

<template>
  <OdTable :columns="columns" :rows="rows" row-key="id" table-label="Users" />
</template>

For local or remote data, pass :pagination="{ enabled: false }" to show all filtered and sorted rows without rendering the pagination bar. Remote requests carry unpaged: true; use this only when the result size is bounded because all rows are loaded and rendered at once.

Remote tables default to frontend columns and one POST query endpoint returning paginated data plus meta.fields for query capabilities and enum options. Use query-url or load-data, with the same columns and row-key props. When the server determines columns, use schema-url + query-url or load-schema + load-data; omit frontend columns and row-key. Both column modes are supported starting in 0.4.0 (0.3.0 uses frontend columns). Both modes share query metadata. enum and multi-enum cells render stable-color tags by default; hovering or focusing a tag exposes a value filter action. Multi-enum overflow and default zebra stripes are described in the display guide. Field slots such as #cell-name match existing columns by field and let the page render links or dialog buttons. multi-enum columns support array intersection filtering; a template ref can use setQuery() for shortcuts or restore URL state with the exported encodeOdTableQuery/decodeOdTableQuery helpers. See the OdTable guide, read-only setup, editing guide, query contract, and backend integration for complete examples, and the capability list for implementation status.

Set exportCsv to expose a CSV action. The callback receives a pagination-free query and visible-column snapshot; local mode also receives every filtered/sorted row before pagination, while remote mode deliberately omits current-page rows so the business endpoint fetches the complete result. See the CSV callback guide.

An explicit editing mode with draft rows, editor slots, and batch create/update/delete contracts is available behind edit-mode="edit". The full query-guard, Storybook, and E01-E49 acceptance matrix remains in progress; see the editing implementation tasks.

Code viewers

OdCode renders read-only highlighted code at 14px with bundled JetBrains Mono and a One Dark syntax palette. Its height follows the rendered lines unless maxHeight is set. OdCodeDiff renders a single-column target-line diff from business-provided context/add/remove lines. Both support optional language selection, line numbers, copying, horizontal scrolling, and wrapping. OdCode also accepts original-file ranges and activeRangeId; call the exposed locateRange() method when the surrounding issue list explicitly requests navigation. See the OdCode guide for the public input contract.

Carousel

Use PrimeVue Carousel directly for image, announcement, or business-card rotation. The verified Onedot recipe adds explicit pause/continue intent, stacked hover/focus/visibility reasons, reduced-motion handling, narrow-screen single-item layout, and lifecycle cleanup without introducing an OdCarousel wrapper. See the Carousel guide.

Lineage

OdGraph renders expandable lists for version trees, call chains, and impact analysis from one complete nodes + edges + rootIds input. It supports branches, references, cycles, controlled expansion and selection, node/edge search across collapsed content, and automatic colorGroup colors. Set view="graph" for a Vue Flow canvas with budgeted local exploration, upstream/downstream expansion, hidden-target search locating, viewport history, temporary node positions, and optional graph-node, graph-edge-label, and graph-toolbar slots. linked instances can share controlled selection, query, and active search results. Collapsed branches are created lazily and long visible lists use dynamic-height virtualization for inputs up to the expected 10,000-node range. Both views show the complete input node count; budget-sized graphs and lists also expose a conditional “expand all nodes” action, while small Graph layouts cap automatic fit zoom at 1.25. See the OdGraph guide and the ImpactAnalysis story.

Dialogs

OdDialog is the default modal for business forms and details. It standardizes responsive sizes, an opaque panel and mask, close behavior, busy locking, and focus restoration when a trigger disappears after list updates. See the OdDialog guide and the form story.

List feedback: pagination, inline messages, empty states

OdPaginator is the controlled paginator shared by OdTable and standalone lists: 1-based page/pageSize/total props, first/last page plus ellipsis window, page-size select, and one change snapshot per user action as the single load trigger. OdInlineMessage standardizes in-page info/success/warning/error feedback with retry busy states, close, and tone-based role/aria-live semantics on PrimeVue Message. OdEmptyState standardizes no-data and filtered-empty layouts with icon, title, description, and action slots. See the OdPaginator guide, the OdInlineMessage guide, and the OdEmptyState guide.

Page structure: forms, headers, toolbars, activity, app shell

Seven structure components cover the stable page scaffolding around business data:

• OdFormField wraps one field's label, required mark, help and error text with a slot context that wires PrimeVue InputText/Textarea/Select/DatePicker (4.5.5 recipes in the guide). It owns no values and adds no validation engine.
• OdDescriptionList renders detail-page key/value facts as semantic dl/dt/dd grids (1–4 columns, compact density, unified empty values).
• OdActivityList renders activity/audit timelines from a prepared array on PrimeVue Timeline, with tone-colored markers and an empty slot that composes OdEmptyState.
• OdFilterToolbar lays out filters, summary and actions over PrimeVue Toolbar and stacks them below 680px; it never owns filter state.
• OdPageHeader composes eyebrow, title, subtitle, back entry, status and actions; the title is always a plain-text heading.
• OdSegmentedControl is the standard v-model single-select mode switch on PrimeVue SelectButton (allowEmpty, per-option disabled, fluid).
• OdAppShell is the router-free micro-app shell with a standard vertical menu data mode (breadcrumbs, recent visits, all-menus overview and search), while retaining the legacy top/side slot mode, skip link, named landmarks, and non-modal mobile navigation disclosure. Set a stable navigationPreferenceKey per application and account to persist and isolate recent visits. For embedded portals and paginated pages, see the height and scrolling guide. Adapter completion timing and stale navigation handling are described in the navigation integration guide.

OdEsFilter renders the legacy ES aggregation filter sidebar on PrimeVue Accordion/InputText/AutoComplete: the page owns a mutable esFilterVo, the component writes selection/text/extend leaves in place and emits one argument-less refresh per user submit (aggregation refills replace the VO from the page). See the OdEsFilter guide.

See the guides for OdFormField, OdDescriptionList, OdActivityList, OdFilterToolbar, OdPageHeader, OdSegmentedControl, OdAppShell, and OdNavigation.

Development

corepack enable
corepack pnpm install
corepack pnpm dev

Storybook is served at http://localhost:6006. For browsing without development compilation or file watching, run corepack pnpm build:storybook then corepack pnpm preview:storybook. See the Storybook guide for preview and icon search usage.

Open Capabilities for the complete catalog, existing Od stories and PrimeVue 4.5.5 (MIT) previews with Aura. The catalog is generated from the user manual; PrimeVue is included as a pinned runtime dependency but is not re-exported from the public Onedot UI entry point. Basic form inputs use PrimeVue directly; this package does not export OdForm or OdInput. PrimeVue 4.5.5 and Aura theme 1.2.5 are installed and versioned by this package for the Onedot organization.

Before publishing, run the complete release check:

corepack pnpm test:e2e:chrome
corepack pnpm test:navigation:chrome
corepack pnpm test:visual
corepack pnpm release:check

test:navigation:chrome uses installed Google Chrome to check navigation interactions and visual snapshots; its baselines are separate from Chromium. See the all-menus guide and Storybook verification instructions.

release:check runs type checking, unit tests, package and Storybook builds, Chromium E2E, visual tests, and npm package/publish dry-runs. It does not publish to npm. The actual publish still requires npm authentication and an explicit npm.cmd publish --access public command from this directory.

For the repository's requirement sources and maintainer documentation, read the 整体结构索引.md. For end-to-end consumer integration, including Vue 3 and Spring Boot 3 remote table examples, read 用户使用手册/OdTable.md. For read-only code and single-column target-line diffs, read 用户使用手册/OdCode.md. For version trees and impact analysis, read 用户使用手册/OdGraph.md. For business dialogs, read 用户使用手册/OdDialog.md. For shared pagination, inline messages, and empty states, read 用户使用手册/OdPaginator.md, 用户使用手册/OdInlineMessage.md, and 用户使用手册/OdEmptyState.md. For direct PrimeVue carousel integration, read 用户使用手册/Carousel.md. For page structure components, read the seven guides linked in the Page structure section. The Storybook Components/OdIcon/AllIcons story provides a searchable view of the complete locally bundled Tabler Icons SVG catalog. The package has no runtime dependency on @tabler/icons or @tabler/icons-vue.

Icons

See the icon usage guide for recommended single-icon imports.

The full Tabler Vue catalog and raw SVG assets are shipped inside this package, so moving the component library to another application does not require a second icon dependency or a network request.

The working package version is 1.2.2; released changes are documented in 用户使用手册/release-notes.md. Maintainers should run corepack pnpm release:check before publishing subsequent versions.

License

MIT. Font licenses and attribution are documented in THIRD_PARTY_NOTICES.md.