OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

AI index

@lssm-tech/lib.personalization

Track field/feature/workflow usage, analyze drop-offs, and convert insights into OverlaySpecs or workflow tweaks.

Installation

bun add @lssm-tech/lib.personalization

Tracker

Buffer events per tenant/user and emit OpenTelemetry counters automatically.

import { createBehaviorTracker } from '@lssm-tech/lib.personalization';

const tracker = createBehaviorTracker({
  store,
  context: { tenantId: ctx.tenant.id, userId: ctx.identity.id },
});

tracker.trackFieldAccess({ operation: 'billing.createOrder', field: 'items' });
tracker.trackWorkflowStep({ workflow: 'invoice', step: 'review', status: 'entered' });

DataView Preferences

Use resolveDataViewPreferences when a collection DataView should honor a user's preferred list/grid/table mode, compact or comfortable density, data depth, and page size. The helper returns plain values that can be passed into the renderer without coupling the design-system package to personalization. Start from the

DataViews runtime guide

when you need the contract and renderer shape.

import { DataViewRenderer } from '@lssm-tech/lib.design-system';
import { resolveDataViewPreferences } from '@lssm-tech/lib.personalization/data-view-preferences';

const resolved = resolveDataViewPreferences({
  spec: AccountsDataView,
  preferences: profile.canonical,
  insights,
  record: savedAccountViewPreference,
});

return (
  <DataViewRenderer
    spec={AccountsDataView}
    items={accounts}
    defaultViewMode={resolved.viewMode}
    defaultDensity={resolved.density}
    defaultDataDepth={resolved.dataDepth}
    pagination={{
      page,
      pageSize: resolved.pageSize ?? 25,
      total,
    }}
  />
);

DataView Interaction Events

Track data_view_interaction events for view mode, density, data depth, search, filters, sorting, and pagination. The in-memory store summarizes those events, and the analyzer can derive a scoped preferred collection mode from valid interaction counts.

tracker.trackDataViewInteraction({
  dataViewKey: AccountsDataView.meta.key,
  dataViewVersion: AccountsDataView.meta.version,
  action: 'view_mode_changed',
  viewMode: 'grid',
});

tracker.trackDataViewInteraction({
  dataViewKey: AccountsDataView.meta.key,
  action: 'data_depth_changed',
  dataDepth: 'detailed',
});

tracker.trackDataViewInteraction({
  dataViewKey: AccountsDataView.meta.key,
  action: 'filter_changed',
  filterKey: 'status',
});

Analyzer

Summarize events and highlight unused UI, frequent fields, and workflow bottlenecks.

import { BehaviorAnalyzer } from '@lssm-tech/lib.personalization/analyzer';

const analyzer = new BehaviorAnalyzer(store);
const insights = await analyzer.analyze({ tenantId: 'acme', userId: 'ops-42' });
// {
//   unusedFields: ['internalNotes'],
//   workflowBottlenecks: [...],
//   dataViewPreferences: {
//     'crm.accounts': { preferredViewMode: 'grid' }
//   }
// }

Adapter

Convert insights into overlays or workflow extension hints.

import { insightsToOverlaySuggestion } from '@lssm-tech/lib.personalization/adapter';

const overlay = insightsToOverlaySuggestion(insights, {
  overlayId: 'acme-order-form',
  tenantId: 'acme',
  capability: 'billing.createOrder',
});

Agent Prompt

Use this when asking an agent to wire DataView preferences while preserving the personalization/design-system boundary.

Add DataView personalization for <screen>.

Acceptance criteria:
- Resolve viewMode, density, dataDepth, and pageSize with resolveDataViewPreferences.
- Apply resolved values to DataViewRenderer as default or controlled props.
- Track opened, view_mode_changed, density_changed, data_depth_changed, search_changed, filter_changed, sort_changed, and page_changed actions with trackDataViewInteraction.
- Persist only the dimensions allowed by view.collection.personalization.persist.
- Ignore behavior-derived modes that are not allowed by view.collection.viewModes.allowedModes.
- Do not import React or design-system code into @lssm-tech/lib.personalization helpers.

Back to Libraries

Next: Overlay Engine

OSS docsbuildStart with OSS. Adopt Studio when you want the operating layer.
Previous

DataViews runtime

Render list, grid, and table DataViews with shared collection defaults, toolbar controls, data depth, and personalization bridges.

Next

Translation runtime

Use ContractSpec TranslationSpec catalogs as the canonical i18n layer, then resolve, format, snapshot, and optionally project messages to i18next.

Why ContractSpec

Keep educational and comparison content reachable without letting it define the primary OSS learning path.

ManifestoContract-first APISpec-driven development