lib.personalized-presentation

@lssm-tech/lib.personalized-presentation

Schema bridge, React provider and hook that resolve lib.personalization preferences and authored role overrides into lib.cockpit-kit variant literals.

Status

Phase 3 — wired dimensions: density, expansion. usePersonalizedVariants resolves them per component through the schema bridge and role overrides.

Installation

This package is an internal workspace package. Add it as a peer or direct dependency from within the monorepo:

"@lssm-tech/lib.personalized-presentation": "workspace:*"

Peer dependencies

• @lssm-tech/lib.cockpit-kit — provides Density and Expansion variant types
• @lssm-tech/lib.personalization — provides PreferenceDimensions
• react — for the provider and hook

Usage

Provider

import {
  PersonalizedSurfaceProvider,
  type PersonalizedRoleVariants,
} from "@lssm-tech/lib.personalized-presentation";

const roleVariants: PersonalizedRoleVariants = {
  operator: { components: { NavRail: { expansion: "collapsed" } } },
  executive: {
    surface: { expansion: "collapsed" },
    components: { MetricPanel: { density: "comfortable" } },
  },
};

function App() {
  return (
    <PersonalizedSurfaceProvider
      role={viewerRole}
      prefs={userPrefs}
      roleVariants={roleVariants}
    >
      <MyCockpitSurface />
    </PersonalizedSurfaceProvider>
  );
}

roleVariants is optional. Each role entry may override variants for the whole surface (surface) and per component key (components).

Hook

import { usePersonalizedVariants } from "@lssm-tech/lib.personalized-presentation";
import { NavRail, type NavRailProps } from "@lssm-tech/lib.cockpit-kit-web/ui/NavRail";

function PersonalizedNavRail(props: NavRailProps) {
  const variants = usePersonalizedVariants("NavRail"); // { density, expansion }
  return <NavRail {...props} {...variants} />;
}

Resolution order, lowest precedence first:

1. prefs through the schema bridge (density from prefs.density, expansion from prefs.dataDepth).
2. roleVariants[role].surface.
3. roleVariants[role].components[componentKey].

Override values outside the cockpit-kit literal unions are ignored, so untyped role configuration falls back to the preference mapping. Outside a provider the hook returns the cockpit-kit defaults (comfortable, expanded). The optional type argument narrows the result and accepts only wired variants: usePersonalizedVariants<{ density: Density }>("Row") returns { density }.

Use resolvePersonalizedVariants({ role, prefs, componentKey, roleVariants }) from ./variant-resolution for the same resolution outside React.

Schema bridge (direct mapper access)

import {
  density,
  expansion,
  mapPreferencesToVariants,
} from "@lssm-tech/lib.personalized-presentation/schema-bridge";

const cockpitDensity = density("compact");   // → "compact"
const cockpitExpansion = expansion("detailed"); // → "expanded"
const variants = mapPreferencesToVariants(userPrefs); // → { density, expansion }

Dependency direction

personalized-presentation → cockpit-kit
personalized-presentation → personalization

cockpit-kit and personalization must NOT depend on this package.

Wired dimensions

All other dimensions (verbosity, trigger, panelMode, enrichedKinds, perKindOptOut) are stub-protected and will throw at runtime if called.