@lssm-tech/lib.ui-kit-core 3.8.9 → 6.0.1

package/README.md

@@ -1,16 +1,16 @@
-# @contractspec/lib.ui-kit-core
+# @lssm-tech/lib.ui-kit-core
 
-`@contractspec/lib.ui-kit-core` is the shared foundation for the UI packages. It provides the low-level `cn()` utility plus the canonical shared interface layer used by `ui-kit` and `ui-kit-web`.
+`@lssm-tech/lib.ui-kit-core` is the shared foundation for the UI packages. It provides the low-level `cn()` utility plus the canonical shared interface layer used by `ui-kit` and `ui-kit-web`.
 
 Website: https://contractspec.io
 
 ## Installation
 
-`bun add @contractspec/lib.ui-kit-core`
+`bun add @lssm-tech/lib.ui-kit-core`
 
 or
 
-`npm install @contractspec/lib.ui-kit-core`
+`npm install @lssm-tech/lib.ui-kit-core`
 
 ## What belongs here
 
@@ -25,16 +25,47 @@ This package is intentionally small:
 - root export: `.`  
 - shared interfaces subpath: `./interfaces`
 - utility subpath: `./utils`
+- command theme class contract: `./command-theme`
 - core function: `cn(...inputs)`
 
 ## Operational semantics and gotchas
 
 - This package is intentionally tiny.
 - `./interfaces` is the shared compatibility layer for semantically matching `ui-kit` and `ui-kit-web` exports.
+- `./command-theme` is a narrow shared class contract for command palette/search-trigger color states. It exists only to keep native, web, and design-system command surfaces aligned on semantic theme tokens; it is not a general design-token bucket.
 - `cn()` composes `clsx` with `tailwind-merge`.
 - Changes here ripple into all UI packages even though the file count is small.
 - This package should stay boring and predictable.
 
+## Compatibility guard
+
+`ui-kit-core` also owns the registry used to compare the native and web UI kit lanes. Run the repo-level guard before adding or changing shared `./ui/*` surfaces:
+
+```bash
+bun run ui-kit:compat
+```
+
+The guard compares `packages/libs/ui-kit` and `packages/libs/ui-kit-web` exported `./ui/*` subpaths, exported symbols, and shared prop-shape contracts. Existing drift is recorded in `scripts/ui-kit-compatibility-baseline.json`; new drift should be fixed or deliberately accepted by refreshing that baseline in the same reviewed change. Shared component contracts should be declared here first under `./interfaces`, then consumed from both UI kit packages.
+
+## Layout contract split
+
+`./interfaces` separates neutral wrapper semantics from directional stack
+semantics so the web and native lanes can migrate `Box` safely:
+
+- `SharedBoxProps` is the shared semantic wrapper contract. It intentionally
+  carries only `className` today; consumers should not depend on `Box` for flex
+  direction, default gap, or default alignment.
+- `SharedFlexStackProps` owns the cross-platform stack subset:
+  `gap`, `align`, `justify`, and `wrap`.
+- `HStack` and `VStack` should consume `SharedFlexStackProps`; new shared UI
+  should pick one of them whenever direction matters.
+- `SharedStackProps` remains exported for compatibility while the staged Box
+  neutral-default migration is underway.
+
+Changing `gap`, `align`, `justify`, `wrap`, `as`, or the Box/stack split is a
+public compatibility decision. Update package docs, release capsules, and guard
+evidence in the same reviewed change.
+
 ## When not to use this package
 
 - Do not use it for components.
@@ -43,11 +74,23 @@ This package is intentionally small:
 
 ## Related packages
 
-- `@contractspec/lib.ui-kit`
-- `@contractspec/lib.ui-kit-web`
-- `@contractspec/lib.ui-link`
+- `@lssm-tech/lib.ui-kit`
+- `@lssm-tech/lib.ui-kit-web`
+- `@lssm-tech/lib.ui-link`
 
 ## Local commands
 
 - `bun run lint:check`
 - `bun run typecheck`
+
+## Graph & Timeline Primitives
+
+`@lssm-tech/lib.ui-kit-core` now exports platform-agnostic graph and timeline hooks and interfaces — pure TypeScript, no React or react-native imports.
+
+**Hooks**: `useGraphFilter`, `useGraphLayout`, `useGraphSelection`, `useAdaptiveGraphRenderer`, `useTimelineRange`, `useTimelineZoom`
+
+**Interfaces**: `GraphNode`, `GraphEdge`, `GraphSelection`, `GraphCanvasProps`, `TimelineEvent`, `TimelineRange`, `TimelineProps`, `TimelineGraphProps`, `GraphLayoutKind`
+
+`useAdaptiveGraphRenderer` returns `"svg"` or `"reactflow"` based on a bounded node/edge threshold (default 300 nodes / 500 edges), enabling lazy-loading of `GraphCanvasAdvanced` in the web lane.
+
+See [AGENTS.md](./AGENTS.md#graph--timeline-primitives) for full details.