@lssm-tech/lib.ui-kit-web 3.13.4 → 9.0.2

package/README.md

@@ -1,16 +1,19 @@
-# @contractspec/lib.ui-kit-web
+# @lssm-tech/lib.ui-kit-web
 
-`@contractspec/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.
+`@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 @contractspec/lib.ui-kit-web`
+`bun add @lssm-tech/lib.ui-kit-web`
 
 or
 
-`npm install @contractspec/lib.ui-kit-web`
+`npm install @lssm-tech/lib.ui-kit-web`
 
 ## What belongs here
 
@@ -25,11 +28,38 @@ Use this package for browser and Next.js surfaces. Do not use it for native or E
 
 ## 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.
+
+```ts
+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
 
 ```ts
-import { Button } from "@contractspec/lib.ui-kit-web/ui/button";
-import { Form } from "@contractspec/lib.ui-kit-web/ui/form";
+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
@@ -38,10 +68,10 @@ import { Form } from "@contractspec/lib.ui-kit-web/ui/form";
 import {
   SRLiveRegionProvider,
   useSRLiveRegion,
-} from "@contractspec/lib.ui-kit-web/ui/live-region";
-import { SkipLink } from "@contractspec/lib.ui-kit-web/ui/skip-link";
-import { RouteAnnouncer } from "@contractspec/lib.ui-kit-web/ui/route-announcer";
-import { FocusOnRouteChange } from "@contractspec/lib.ui-kit-web/ui/focus-on-route-change";
+} 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 (
@@ -60,20 +90,20 @@ function AppShell({ title, children }: { title: string; children: React.ReactNod
 ### Render the canonical account grid
 
 The canonical data-table example lives in
-[`@contractspec/example.data-grid-showcase`](../../examples/data-grid-showcase/README.md).
-Its raw browser lane renders `@contractspec/lib.ui-kit-web/ui/data-table`
+[`@lssm-tech/example.data-grid-showcase`](../../examples/data-grid-showcase/README.md).
+Its raw browser lane renders `@lssm-tech/lib.ui-kit-web/ui/data-table`
 directly:
 
 ```tsx
-import { DataTable } from '@contractspec/lib.ui-kit-web/ui/data-table';
-import { useContractTable } from '@contractspec/lib.presentation-runtime-react';
+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 '@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 WebAccountGrid() {
   const columns = useShowcaseColumns();
@@ -120,7 +150,7 @@ compact truncating wrapper for `truncate` and `expand`, multiline wrapping for
 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
-`@contractspec/lib.design-system` `DataTableToolbar` into the `toolbar` slot.
+`@lssm-tech/lib.design-system` `DataTableToolbar` into the `toolbar` slot.
 
 ## API map
 
@@ -166,10 +196,32 @@ empty, error, disabled-option, description, and multi-select chip states.
 - `./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`
@@ -186,7 +238,7 @@ empty, error, disabled-option, description, and multi-select chip states.
 - `./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 `@contractspec/lib.ui-kit-core/interfaces`
+- shared semantic contracts are defined in `@lssm-tech/lib.ui-kit-core/interfaces`
 
 ## Public surface
 
@@ -210,7 +262,9 @@ Use `package.json` as the exhaustive export map.
 - 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.
-- Storybook scripts exist here, unlike the other UI packages in this rewrite set.
+- 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.
 
@@ -222,12 +276,47 @@ Use `package.json` as the exhaustive export map.
 
 ## Related packages
 
-- `@contractspec/lib.ui-kit-core`: shared low-level utilities used across UI packages.
-- `@contractspec/lib.ui-kit`: native-first component package for Expo and React Native 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`: shared low-level utilities used across UI packages.
+- `@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.
+
+```ts
+// 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](./AGENTS.md#graph--timeline-primitives) 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.