lib.ui-kit

@lssm-tech/lib.ui-kit

@lssm-tech/lib.ui-kit provides cross-platform UI components for native-first and Expo-based surfaces, with most real usage happening through ./ui/* subpaths rather than the root barrel.

Website: https://contractspec.io

Installation

bun add @lssm-tech/lib.ui-kit

or

npm install @lssm-tech/lib.ui-kit

What belongs here

This package owns the native-first component layer for ContractSpec UI work:

• React Native and Expo component wrappers.
• Shared UI building blocks such as forms, tables, overlays, navigation, loading states, marketing blocks, and visualization surfaces.
• Platform-aware helpers such as useColorScheme and list state helpers.

Use this package for Expo and React Native surfaces. Do not use it as the design-token layer or as the framework-agnostic link package.

API map

Forms and inputs

• ./ui/input
• ./ui/input-password
• ./ui/textarea
• ./ui/select
• ./ui/form
• ./ui/field

Native contract-driven forms consume the shared Field semantics through the design-system renderer; web-only input-addon composition remains in @lssm-tech/lib.ui-kit-web/ui/input-group and the design-system platform facade.

./ui/input-password provides the native masked password primitive with current/new password autocomplete hints and a right-side visibility toggle.

Overlays and menus

• ./ui/dialog
• ./ui/alert-dialog
• ./ui/popover
• ./ui/sheet
• ./ui/dropdown-menu
• ./ui/context-menu
• ./ui/portal
• ./ui/toast
• ./ui/toolbar

./ui/sheet is the native edge-anchored panel: Sheet, SheetTrigger, SheetClose, SheetContent, SheetHeader, SheetFooter, SheetTitle and SheetDescription match @lssm-tech/lib.ui-kit-web/ui/sheet, so Metro's ui-kit-web/ui/* remap lands on a working sheet. It is built on @rn-primitives/dialog (controlled or uncontrolled open, dialog semantics, Android back and the accessibility escape gesture close it). SheetContent slides in from side (right by default) and merges className after the side classes; a scrim press or the close button (closeLabel) dismisses it. React Native does not link SheetTitle to the dialog, so pass accessibilityLabel to SheetContent to name it for screen readers. Under a SafeAreaProvider (from react-native-safe-area-context), the screen edges the panel touches are padded by their non-zero insets, replacing className padding on those edges (style still wins), and the close button clears the status bar and notch. Mount <PortalHost /> from ./ui/portal once at the app root, or pass portalHost.

Navigation and display

• ./ui/link
• ./ui/sidebar
• ./ui/navigation-menu
• ./ui/page-header
• ./ui/stack
• ./ui/table
• ./ui/data-table
• ./ui/card
• ./ui/empty-state
• ./ui/slider

Stack and Box layout intent

./ui/stack exports the native Box, HStack, and VStack primitives. Treat direction as part of the component contract:

• Utiliser VStack for vertical sections, card content, forms, lists, and panels.
• Utiliser HStack for horizontal rows, toolbars, chips, inline metrics, and action groups.
• Utiliser 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 spacing, 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". spacing, width, and padding remain native-lane transition props behind legacy compatibility; the shared cross-platform stack subset is gap, align, justify, and wrap.

Data table example

The canonical data-table example lives in @lssm-tech/example.data-grid-showcase^†. Its native-first lane renders the same account-grid controller through @lssm-tech/lib.ui-kit/ui/data-table:

import { DataTable } from '@lssm-tech/lib.ui-kit/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 NativeAccountGrid() {
  const columns = useShowcaseColumns();

  const controller = useContractTable({
    data: SHOWCASE_ROWS,
    columns,
    selectionMode: 'single',
    initialState: {
      sorting: [{ id: 'arr', 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="Native primitive"
          primaryColumnId="account"
          toggleColumnId="notes"
          pinColumnId="owner"
          sortColumnIds={['arr', 'renewalDate']}
        />
      }
      loading={false}
      footer={\`Rows \${controller.rows.length}\`}
    />
  );
}

Cells receive overflow behavior from the table controller. Native renderers use single-line ellipsis for truncate and expand, multiline text for wrap, and preserve caller rendering for none.

This example explicitly demonstrates the same sorting, pagination, selection, column visibility, column resizing, left/right pinning, row expansion, loading, and empty-state contracts used by the browser lanes.

Hooks, utilities, and grouped surfaces

• ./ui/useColorScheme
• ./ui/useListState
• ./ui/utils
• grouped subpaths under ./ui/marketing, ./ui/usecases, and ./ui/visualization
• icons under ./ui/icons/*
• shared semantic contracts are defined in @lssm-tech/lib.ui-kit-core/interfaces

Public surface

The current root entry exists, but it is not the meaningful consumer surface for this package.

Consumers should import ./ui/* subpaths directly. The public surface is best understood in groups:

• atoms and controls
• forms
• overlays and menus
• navigation and layout
• data display
• loading and empty states
• marketing and use-case blocks
• organisms and visualization
• hooks, utilities, and icons

Utiliser package.json as the exhaustive source of truth for all exported subpaths.

Operational semantics and gotchas

• Consumers should import subpaths directly; the root package is not the useful primary API today.
• Many components wrap Expo, React Native, or RN-oriented primitives and dependencies.
• ./ui/link is router-coupled through expo-router.
• ./ui/useColorScheme is built on nativewind.
• ./ui/utils exposes a local cn() helper, but the deeper compatibility dependency is @lssm-tech/lib.ui-kit-core.
• This package is native-first even when some components can render cross-platform through React Native Web.

When not to use this package

• Do not use it for pure web-first Radix or Next.js surfaces.
• Do not use it for token or theming orchestration.
• Do not use it for framework-agnostic link behavior.

Related packages

• @lssm-tech/lib.ui-kit-core: tiny shared utility layer used by the UI packages.
• @lssm-tech/lib.ui-kit-web: web-first component package for React and Next 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

Graph & Timeline Primitives

@lssm-tech/lib.ui-kit ships native graph and timeline primitives backed by react-native-svg for Expo and React Native surfaces.

@lssm-tech/lib.ui-kit/ui/graph:

• GraphCanvas — native SVG graph renderer; same GraphCanvasProps interface as the web lane

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

• Timeline — native SVG timeline renderer
• TimelineGraph — native combined timeline + graph view

All three respect prefers-reduced-motion via the reducedMotion prop (parity with web lane).

Metro aliases (withPresentationMetroAliases) automatically map @lssm-tech/lib.ui-kit-web/ui/* subpaths to @lssm-tech/lib.ui-kit/ui/* for native surfaces. Product code can import from @lssm-tech/lib.design-system and let the alias system route to the correct primitive.

See AGENTS.md for layer placement and full import rules.

Native compiler compatibility

The workspace development compiler is pinned to Babel 7.29.7. The installed Expo 57 and React Native Worklets presets use Babel 7 transforms; resolving this package to Babel 8 prevents Metro from exporting native skeleton/worklet components. Qualify the presets and compiler together before upgrading this pin. iOS/Android export success is build evidence, not real-device accessibility or release acceptance.

Standalone declaration exports keep their existing public subpath names. The shared builder preserves their original declaration suffix and copies checked source declarations into dist, without overwriting emitted implementation types.