@lssm-tech/lib.ui-kit 4.1.6 → 8.0.3

package/README.md

@@ -1,16 +1,16 @@
-# @contractspec/lib.ui-kit
+# @lssm-tech/lib.ui-kit
 
-`@contractspec/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.
+`@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 @contractspec/lib.ui-kit`
+`bun add @lssm-tech/lib.ui-kit`
 
 or
 
-`npm install @contractspec/lib.ui-kit`
+`npm install @lssm-tech/lib.ui-kit`
 
 ## What belongs here
 
@@ -35,7 +35,7 @@ Use this package for Expo and React Native surfaces. Do not use it as the design
 
 Native contract-driven forms consume the shared `Field` semantics through the
 design-system renderer; web-only input-addon composition remains in
-`@contractspec/lib.ui-kit-web/ui/input-group` and the design-system platform
+`@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
@@ -59,29 +59,52 @@ current/new password autocomplete hints and a right-side visibility toggle.
 - `./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:
+
+- 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 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
-[`@contractspec/example.data-grid-showcase`](../../examples/data-grid-showcase/README.md).
+[`@lssm-tech/example.data-grid-showcase`](../../examples/data-grid-showcase/README.md).
 Its native-first lane renders the same account-grid controller through
-`@contractspec/lib.ui-kit/ui/data-table`:
+`@lssm-tech/lib.ui-kit/ui/data-table`:
 
 ```tsx
-import { DataTable } from '@contractspec/lib.ui-kit/ui/data-table';
-import { useContractTable } from '@contractspec/lib.presentation-runtime-react';
+import { DataTable } from '@lssm-tech/lib.ui-kit/ui/data-table';
+import { useContractTable } from '@lssm-tech/lib.presentation-runtime-react';
 
-import { SHOWCASE_ROWS } from '@contractspec/example.data-grid-showcase/ui/data-grid-showcase.data';
-import { useShowcaseColumns } from '@contractspec/example.data-grid-showcase/ui/data-grid-showcase.columns';
+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 '@contractspec/example.data-grid-showcase/ui/data-grid-showcase.parts';
+} from '@lssm-tech/example.data-grid-showcase/ui/data-grid-showcase.parts';
 
 export function NativeAccountGrid() {
   const columns = useShowcaseColumns();
@@ -133,7 +156,7 @@ This example explicitly demonstrates the same sorting, pagination, selection, co
 - `./ui/utils`
 - grouped subpaths under `./ui/marketing`, `./ui/usecases`, and `./ui/visualization`
 - icons under `./ui/icons/*`
-- shared semantic contracts are defined in `@contractspec/lib.ui-kit-core/interfaces`
+- shared semantic contracts are defined in `@lssm-tech/lib.ui-kit-core/interfaces`
 
 ## Public surface
 
@@ -159,7 +182,7 @@ Use `package.json` as the exhaustive source of truth for all exported subpaths.
 - 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 `@contractspec/lib.ui-kit-core`.
+- `./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
@@ -170,11 +193,40 @@ Use `package.json` as the exhaustive source of truth for all exported subpaths.
 
 ## Related packages
 
-- `@contractspec/lib.ui-kit-core`: tiny shared utility layer used by the UI packages.
-- `@contractspec/lib.ui-kit-web`: web-first component package for React and Next surfaces.
-- `@contractspec/lib.design-system`: higher-level design-system and composition layer built on top of the UI 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](./AGENTS.md#graph--timeline-primitives) 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.