lib.ui-kit-web

@lssm-tech/lib.ui-kit-web

@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 VStack for vertical sections, card content, forms, lists, and panels.
• Use HStack for horizontal rows, toolbars, chips, inline metrics, and action groups.
• Use Box as a neutral wrapper, semantic surface, single-child container, or explicit true-grid/custom-positioning host.
• Do not introduce new Box usage that depends on implicit flex direction, default gap, centered alignment, or className-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 Field and InputGroup primitives 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/link is based on next/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.storybook instead 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:check
• bun run typecheck
• bun 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 hooks
• GraphCanvasAdvanced — ReactFlow (@xyflow/react) adapter for large graphs

@lssm-tech/lib.ui-kit-web/ui/timeline:

• Timeline — SVG timeline with brush, axis, and event sub-modules
• TimelineGraph — 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.