lib.ui-kit-web
Web UI components with Radix primitives
@lssm-tech/lib.ui-kit-webbun add @lssm-tech/lib.ui-kit-webManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
@lssm-tech/lib.ui-kit-web provides web UI components for React and Next surfaces, with accessible building blocks, Radix-based primitives, layout helpers, and web-specific UX utilities exposed through ./ui/* subpaths.
Website: https://contractspec.io
Form hosts support @hookform/resolvers ^5.4.0, including the workspace-tested 5.9.1 release. The development dependency must remain within that peer range.
Installation
bun add @lssm-tech/lib.ui-kit-web
or
npm install @lssm-tech/lib.ui-kit-web
What belongs here
This package owns the web-first component layer:
- Radix-backed web UI components.
- Web-only accessibility helpers and route-announcement primitives.
- Map, marketing, list-page, and visualization building blocks.
- Web form, navigation, and layout primitives.
Use this package for browser and Next.js surfaces. Do not use it for native or Expo UI work.
Core workflows
Opt into the executable Storybook catalog
The package publishes a contract-driven, relocatable catalog at @lssm-tech/lib.ui-kit-web/storybook. It covers eight representative public families with Editorial light and Executive Ledger dark reference cases; it does not multiply primitives across the full design-pack matrix.
import { uiKitWebStorybookCatalog } from "@lssm-tech/lib.ui-kit-web/storybook";
export default {
// ...ContractSpec Storybook configuration
catalogs: [uiKitWebStorybookCatalog],
};Catalog V2 embeds scenarios and references the public ./storybook/bindings entry. The consuming host owns the Storybook integration and generates CSF; the library no longer ships executable generated stories or requires that peer. bun run storybook:generate and bun run storybook:check maintain the data manifest. Consumers that used storyGlobs directly must adopt the catalog through the integration and regenerate their host. Existing catalogs: [uiKitWebStorybookCatalog] configuration remains valid. The exported coverage manifest maps controls, forms, navigation, overlays, feedback, data display, accessibility, and graph/visualization to their scenarios and typed bindings.
Import a web component by subpath
import { Button } from "@lssm-tech/lib.ui-kit-web/ui/button";
import { Form } from "@lssm-tech/lib.ui-kit-web/ui/form";Wire accessibility helpers at the app root
import {
SRLiveRegionProvider,
useSRLiveRegion,
} from "@lssm-tech/lib.ui-kit-web/ui/live-region";
import { SkipLink } from "@lssm-tech/lib.ui-kit-web/ui/skip-link";
import { RouteAnnouncer } from "@lssm-tech/lib.ui-kit-web/ui/route-announcer";
import { FocusOnRouteChange } from "@lssm-tech/lib.ui-kit-web/ui/focus-on-route-change";
function AppShell({ title, children }: { title: string; children: React.ReactNode }) {
return (
<SRLiveRegionProvider>
<SkipLink targetId="main" />
<RouteAnnouncer title={title} />
<main id="main">
<FocusOnRouteChange />
{children}
</main>
</SRLiveRegionProvider>
);
}Render the canonical account grid
The canonical data-table example lives in @lssm-tech/example.data-grid-showcase. Its raw browser lane renders @lssm-tech/lib.ui-kit-web/ui/data-table directly:
import { DataTable } from '@lssm-tech/lib.ui-kit-web/ui/data-table';
import { useContractTable } from '@lssm-tech/lib.presentation-runtime-react';
import { SHOWCASE_ROWS } from '@lssm-tech/example.data-grid-showcase/ui/data-grid-showcase.data';
import { useShowcaseColumns } from '@lssm-tech/example.data-grid-showcase/ui/data-grid-showcase.columns';
import {
ExpandedRowContent,
ShowcaseToolbar,
} from '@lssm-tech/example.data-grid-showcase/ui/data-grid-showcase.parts';
export function WebAccountGrid() {
const columns = useShowcaseColumns();
const controller = useContractTable({
data: SHOWCASE_ROWS,
columns,
selectionMode: 'single',
initialState: {
sorting: [{ id: 'lastActivityAt', desc: true }],
pagination: { pageIndex: 0, pageSize: 4 },
columnVisibility: { notes: false },
columnPinning: { left: ['account'], right: [] },
},
renderExpandedContent: (row) => <ExpandedRowContent row={row} />,
getCanExpand: () => true,
});
return (
<DataTable
controller={controller}
toolbar={
<ShowcaseToolbar
controller={controller}
label="Web primitive"
primaryColumnId="account"
toggleColumnId="notes"
pinColumnId="owner"
sortColumnIds={['arr', 'renewalDate']}
/>
}
loading={false}
emptyState={<div>No rows available.</div>}
footer={\`Rows \${controller.totalItems}\`}
/>
);
}Cells receive overflow behavior from the table controller. Web renderers use a compact truncating wrapper for truncate and expand, multiline wrapping for wrap, and preserve caller rendering for none.
Use the web primitive when you want direct control over the render surface. For higher-level search, active chips, selection summary, and hidden-column recovery, keep this primitive lean and layer @lssm-tech/lib.design-system DataTableToolbar into the toolbar slot.
API map
Controls and forms
./ui/button./ui/button-group./ui/input./ui/input-password./ui/textarea./ui/select./ui/native-select./ui/field./ui/form
./ui/input-password composes the shared input group, masked input, and right-side visibility toggle while preserving current-password and new-password autocomplete hints for password managers.
./ui/combobox
./ui/combobox keeps the select-style button API compatible and also supports editable autocomplete usage with query control, listbox ARIA wiring, loading, empty, error, disabled-option, description, and multi-select chip states.
./ui/input-group./ui/input-otp./ui/spinner./ui/kbd
Overlays, menus, and navigation
./ui/dialog./ui/drawer./ui/dropdown-menu./ui/popover./ui/navigation-menu./ui/nav-layout./ui/link
Data display and layout
./ui/table./ui/data-table./ui/page-header./ui/section./ui/sidebar./ui/stack./ui/item./ui/chart./ui/direction
Stack and Box layout intent
./ui/stack exports the web Box, HStack, and VStack primitives. Treat direction as part of the component contract:
- Use
VStackfor vertical sections, card content, forms, lists, and panels. - Use
HStackfor horizontal rows, toolbars, chips, inline metrics, and action groups. - Use
Boxas a neutral wrapper, semantic surface, single-child container, or explicit true-grid/custom-positioning host. - Do not introduce new
Boxusage that depends on implicit flex direction, default gap, centered alignment, orclassName-only stack layout.
Box is neutral by default and no longer injects legacy row/gap/center layout. Legacy layout behavior is available only through the temporary legacyBoxLayout compatibility bridge while owned callsites migrate. New code must not use that bridge; replace Box className="flex flex-col gap-4" with VStack gap="md" or Box className="flex flex-row items-center" with HStack align="center". Changes to gap, align, justify, wrap, as, or Box defaults require release-capsule evidence and guard output.
Accessibility helpers
./ui/skip-link./ui/live-region./ui/route-announcer./ui/focus-on-route-change./ui/visually-hidden
Hooks and grouped surfaces
./ui/use-media-query./ui/use-mobile./ui/use-reduced-motion./ui/use-toast./ui/utils- grouped subpaths under
./ui/map,./ui/marketing,./ui/usecases,./ui/organisms/ListPage, and./ui/visualization - shared semantic contracts are defined in
@lssm-tech/lib.ui-kit-core/interfaces
Public surface
The package publishes a root entry, but the meaningful consumer surface is ./ui/*.
Consumers should import grouped subpaths directly. The public surface is best understood by category:
- controls and forms
- shadcn/Radix-style
FieldandInputGroupprimitives for accessible labels, descriptions, errors, legends, addons, and grouped controls - overlays and menus
- layout and navigation
- accessibility helpers
- data display
- grouped map, marketing, organisms, use-case, and visualization surfaces
- hooks and utilities
Use package.json as the exhaustive export map.
Operational semantics and gotchas
- Components rely on Radix and browser or Next assumptions.
./ui/linkis based onnext/link../ui/skip-link, live-region helpers, and route announcers are first-class web-only APIs in this package.- Component catalogs are hosted through
@lssm-tech/app.storybook; downstream verticals should adopt@lssm-tech/integration.storybookinstead of adding a package-local Storybook configuration here. - The package has optional map-related peer dependencies; map features should stay opt-in and not become implicit hard requirements.
- The root entry is not the meaningful consumer surface today.
When not to use this package
- Do not use it for native or Expo surfaces.
- Do not use it for token orchestration or platform abstraction.
- Do not use it for framework-agnostic linking.
Related packages
@lssm-tech/lib.ui-kit-core: shared low-level utilities used across UI packages.
The server-only ./rich-ref/ssr-boundary-resolver reads the shared @lssm-tech/lib.ui-kit-core/ssr/subject-scope port. AuthOS request handlers continue to use runWithSubject from @lssm-tech/lib.authos-runtime/ssr to install their resolved subject. Both entry points use one canonical async scope; the resolver keeps its existing arguments, subject identity and per-session hash. No identity-domain implementation is imported by the web primitives.
@lssm-tech/lib.ui-kit: native-first component package for Expo and React Native surfaces.@lssm-tech/lib.design-system: higher-level design-system and composition layer built on top of the UI packages.
Local commands
bun run lint:checkbun run typecheckbun run test
Graph & Timeline Primitives
@lssm-tech/lib.ui-kit-web ships SVG graph and timeline primitives for web and Next.js surfaces.
@lssm-tech/lib.ui-kit-web/ui/graph:
GraphCanvas— SVG-based graph renderer with layout + selection hooksGraphCanvasAdvanced— ReactFlow (@xyflow/react) adapter for large graphs
@lssm-tech/lib.ui-kit-web/ui/timeline:
Timeline— SVG timeline with brush, axis, and event sub-modulesTimelineGraph— combined timeline + graph view
All three respect prefers-reduced-motion via the reducedMotion prop.
Bundle-size note: GraphCanvasAdvanced pulls in @xyflow/react. Always import it via React.lazy(...) — never statically. GraphCanvas (SVG-only) is safe for static import.
// GraphCanvas — static import OK
import { GraphCanvas } from "@lssm-tech/lib.ui-kit-web/ui/graph";
// GraphCanvasAdvanced — always lazy-load
const GraphCanvasAdvanced = React.lazy(
() => import("@lssm-tech/lib.ui-kit-web/ui/graph").then(m => ({ default: m.GraphCanvasAdvanced }))
);See AGENTS.md for layer placement and full import rules.
./ui/sonner-toast exposes the theme-independent toast emitter. Use it for action feedback that does not render a themed toaster; ./ui/sonner keeps its existing Next-theme-aware Toaster surface and optional peer requirement.
Declaration-only JSX augmentations under ui/**/*.d.ts participate in source type checking but are excluded from generated runtime entries and public runtime exports. They do not provide an executable component or require a native peer.
The narrow ./themed-primitives/{context,stack,list,text} exports own the existing web themed wrappers. WebComponentThemeProvider accepts already resolved component variants from a composition owner; it performs no discovery, registration, permission decision, or theme selection. Bare ./ui/* primitives retain their behavior. Caller props override variant defaults. These React client exports preserve the web DOM and shared context identity used by DesignSystem and SurfaceRuntime.
Canonical builds retain the intentional published export map (exports.rewrite: false). New production roots must be declared in the existing build entries and manifest together; generation must not silently rename or drop supported aliases or platform conditions. Full artifact verification checks every advertised target, including native aliases. Test fixtures remain in source verification while excluded from production entry discovery.
Canonical contract suppliers
Web graph, rich-reference and Storybook consumers use complete canonical Core, Kernel, UiKitCore and DesignCatalog families. Their implementation bodies, defaults, layout behavior, fixtures and assertions are unchanged. The full original rich-reference denial-token parity fixture remains in this package and uses the canonical Core serialization entry. Source supplier wiring is separate from fresh owning-build, declaration, affected-test and platform qualification.
Relationships
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
49 declarations
@daypicker/react10.0.1
@lssm-tech/lib.presentation-runtime-coreworkspace:^
Read the package manual ↗@lssm-tech/lib.ui-kit-coreworkspace:^
Read the package manual ↗@radix-ui/react-accordion^1.2.20
@radix-ui/react-alert-dialog^1.1.23
@radix-ui/react-aspect-ratio^1.1.15
Declared capabilities
Web UI components with Radix primitives
Scripts
publish:pkgbun publish --tolerate-republish --ignore-scripts --verbosepublish:pkg:canarybun publish:pkg --tag canarybuildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typesdevcontractspec-bun-build devcleanrm -rf distlintbun run lint:fixlint:fixnode ../../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../../scripts/biome.cjs check --write .lint:checknode ../../../../scripts/biome.cjs check .testbun test --pass-with-no-testsstorybook:generatebun scripts/storybook.mjsstorybook:checkbun scripts/storybook.mjs --checkcheck:bundlenode scripts/check-bundle.mjsprebuildcontractspec-bun-build prebuildtypechecktsgo --noEmit