@appinternalleads/ui 0.2.0

package/src/components/onboarding/dashboard-config/DashboardConfigView.tsx

@@ -0,0 +1,91 @@
+import { Box, Text } from '../../../core';
+import { Callout, ToggleCardGroup } from '../../../ds';
+import type { DensityName } from '../../../tokens';
+import { iconFor, resolveConfig, type OnboardingPreset, type OnboardingResult, type PatternStatus } from '../shared/contract';
+import type { OnboardingOperation } from '../shared/mock';
+import { OnboardingCard } from '../shared/OnboardingCard';
+import { usePatternStatus, useSceneReport } from '../shared/runtime';
+import { InvalidConfig } from '../shared/InvalidConfig';
+import { DASHBOARD_PRESETS, validateDashboardConfig, type DashboardConfigSettings } from './contract';
+import type { DashboardSeed } from './engine';
+import { useDashboardConfig, type DashboardOperations } from './runtime';
+import { guarded } from '../shared/guard';
+
+export type DashboardConfigProps = {
+  /** One of the five case studies. Omit for the default (case 1's data). */
+  preset?: OnboardingPreset;
+  /** Merged over the preset: `BASE_COPY ← BASE ← CASES[preset] ← config`. */
+  config?: Partial<DashboardConfigSettings>;
+  density?: DensityName;
+  /** Where the step starts: the host is loading it, has nothing for it, or failed to load it. */
+  status?: PatternStatus;
+  /** How the default (mock) save ends. Ignored when `operations` is given. */
+  result?: OnboardingResult;
+  operations?: DashboardOperations;
+  /** The host's reload, run by Retry and Refresh. Default: the placeholder 900ms. */
+  reload?: OnboardingOperation<void>;
+  /** Restore a session — a scene seed. Never part of the config. */
+  initial?: DashboardSeed;
+  onChange?: (selected: string[]) => void;
+  onSave?: (selected: string[]) => void;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+/**
+ * **Dashboard Config** — a hint line (live), a two-column grid of multi-select cards (C4, B4) with
+ * each tile keeping its category hue, and one save. Chip "2 selected" (M5) → "Saving…" → "Saved";
+ * primary gated below `min`; at `max` the unselected cards disable.
+ */
+function DashboardConfigView(props: DashboardConfigProps) {
+  const config = resolveConfig(DASHBOARD_PRESETS, props.preset, props.config);
+  const issues = validateDashboardConfig(config);
+  if (issues.length) return <InvalidConfig title={config.title} issues={issues} testID={props.testID} />;
+  return <Valid {...props} config={config} />;
+}
+
+function Valid({
+  config, density, status = 'ready', result, operations, reload, initial, onChange, onSave, onScene, testID,
+}: Omit<DashboardConfigProps, 'config'> & { config: DashboardConfigSettings }) {
+  const pattern = usePatternStatus(status, reload);
+  const rt = useDashboardConfig({ config, operations, result, initial, onChange, onSave });
+  const v = rt.view;
+  useSceneReport(pattern.status === 'ready' ? v.scene : pattern.status, onScene);
+  const locked = rt.state.save === 'saving' || rt.state.save === 'saved';
+
+  return (
+    <OnboardingCard
+      testID={testID}
+      header={config}
+      copy={config}
+      density={density}
+      status={pattern.status}
+      onRetry={pattern.retry}
+      onEmptyAction={pattern.retry}
+      chip={v.chip}
+      hint={v.footerHint}
+      secondary={config.secondaryLabel ? { label: config.secondaryLabel, onPress: () => onScene?.('skipped') } : undefined}
+      primary={{ label: v.primaryLabel, onPress: rt.save, disabled: !v.canSave, busy: rt.state.save === 'saving' }}>
+      <Box gap="s3">
+        <Box role="status" aria-live="polite"><Text variant="caption" color="textSecondary" style={{ fontSize: 12 }}>{v.gridHint}</Text></Box>
+        <ToggleCardGroup
+          label={config.title}
+          value={rt.state.selected}
+          onChange={next => {
+            const added = next.find(x => !rt.state.selected.includes(x));
+            const removed = rt.state.selected.find(x => !next.includes(x));
+            const id = added ?? removed;
+            if (id) rt.toggle(id);
+          }}
+          max={config.max}
+          disabled={locked}
+          options={config.widgets.map(w => ({ value: w.id, title: w.title, description: w.description, icon: iconFor(w.icon), type: w.type }))}
+        />
+        {rt.state.save === 'failed' ? <Callout alert title={config.saveErrorTitle}>{config.saveErrorBody}</Callout> : null}
+      </Box>
+    </OnboardingCard>
+  );
+}
+
+/** DashboardConfig, guarded: a wrong-kind config is refused by name and a render error is caught, never thrown to the page (`shared/guard`). */
+export const DashboardConfig = guarded(DashboardConfigView, DASHBOARD_PRESETS, 'DashboardConfig');

package/src/components/onboarding/dashboard-config/contract.ts

@@ -0,0 +1,49 @@
+import type { DataType } from '../../../tokens';
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import presetsJson from './presets.json';
+
+/**
+ * **Dashboard Config (handoff §3.6)** — choose which widgets appear on a dashboard. A two-column
+ * grid of multi-select cards between `min` and `max`; one save.
+ */
+
+export type DashboardWidget = { id: string; type: DataType; icon: string; title: string; description: string };
+
+export const DASHBOARD_SCENES = ['default', 'below', 'atMax', 'saving', 'saved', 'failed', 'loading', 'empty', 'error'] as const;
+export type DashboardScene = (typeof DASHBOARD_SCENES)[number];
+/** Scenes that are an operation in flight — see `sceneProps`. */
+export const DASHBOARD_IN_FLIGHT: readonly string[] = ['saving'];
+
+export type DashboardConfigSettings = HeaderConfig & LoadCopy & {
+  min: number;
+  max: number;
+  widgets: DashboardWidget[];
+  defaultSelected: string[];
+  /** The scene the case ships in. Demo boards only. */
+  ship?: DashboardScene;
+  primaryLabel: string;
+  savingLabel: string;
+  savedLabel: string;
+  savedHint: string;
+  saveErrorTitle: string;
+  saveErrorBody: string;
+  /** Optional ghost secondary ("Skip"). */
+  secondaryLabel?: string;
+};
+
+export const DASHBOARD_PRESETS = presetsJson as unknown as PresetsFile<DashboardConfigSettings>;
+
+export function validateDashboardConfig(c: DashboardConfigSettings): OnboardingIssue[] {
+  const issues: OnboardingIssue[] = [];
+  const ids = new Set<string>();
+  if (!Array.isArray(c.widgets)) return [{ path: 'widgets', message: 'widgets must be a list.' }];
+  c.widgets.forEach((w, i) => {
+    if (!w.id) issues.push({ path: `widgets[${i}].id`, message: 'Every widget needs an id.' });
+    if (ids.has(w.id)) issues.push({ path: `widgets[${i}].id`, message: `The id “${w.id}” is used twice.` });
+    ids.add(w.id);
+  });
+  if (!(c.min >= 0) || !(c.max >= 1) || c.min > c.max) issues.push({ path: 'min', message: 'min must be between 0 and max.' });
+  for (const id of c.defaultSelected ?? []) if (!ids.has(id)) issues.push({ path: 'defaultSelected', message: `“${id}” is not a widget.` });
+  if ((c.defaultSelected ?? []).length > c.max) issues.push({ path: 'defaultSelected', message: 'More widgets are selected than max allows.' });
+  return issues;
+}

package/src/components/onboarding/dashboard-config/engine.ts

@@ -0,0 +1,81 @@
+import type { StateChipTone } from '../../../ds';
+import type { SavePhase } from '../shared/contract';
+import type { DashboardConfigSettings, DashboardScene } from './contract';
+
+/**
+ * **The Dashboard Config engine** — pure. Selection, the save lifecycle and everything the view
+ * derives from them (chip, hint, gate), so every rule is testable without rendering.
+ */
+
+export type DashboardState = { selected: string[]; save: SavePhase };
+export type DashboardSeed = Partial<DashboardState>;
+
+export type DashboardAction =
+  | { type: 'toggle'; id: string }
+  | { type: 'save' }
+  | { type: 'saved' }
+  | { type: 'failed' }
+  | { type: 'reset'; state: DashboardState };
+
+export function initialDashboard(c: DashboardConfigSettings, seed: DashboardSeed = {}): DashboardState {
+  return { selected: (seed.selected ?? c.defaultSelected ?? []).slice(), save: seed.save ?? 'idle' };
+}
+
+/** The demo scenes as seeds — `ship` and the boards' state switcher. Pattern scenes are the shell's. */
+export function dashboardSeed(c: DashboardConfigSettings, scene: DashboardScene): DashboardSeed {
+  const ids = c.widgets.map(w => w.id);
+  const atLeastMin = (s: string[]) => (s.length < c.min ? ids.slice(0, c.min) : s);
+  switch (scene) {
+    case 'below': return { selected: ids.slice(0, Math.max(0, c.min - 1)) };
+    case 'atMax': return { selected: ids.slice(0, c.max) };
+    case 'saving': case 'saved': case 'failed': return { selected: atLeastMin(c.defaultSelected ?? []), save: scene };
+    default: return {};
+  }
+}
+
+export const isLocked = (s: DashboardState) => s.save === 'saving' || s.save === 'saved';
+
+export function reduceDashboard(c: DashboardConfigSettings, s: DashboardState, a: DashboardAction): DashboardState {
+  switch (a.type) {
+    case 'toggle': {
+      if (isLocked(s)) return s;
+      const on = s.selected.includes(a.id);
+      if (!on && s.selected.length >= c.max) return s;
+      return { selected: on ? s.selected.filter(x => x !== a.id) : [...s.selected, a.id], save: 'idle' };
+    }
+    case 'save': return s.selected.length < c.min || isLocked(s) ? s : { ...s, save: 'saving' };
+    case 'saved': return s.save === 'saving' ? { ...s, save: 'saved' } : s;
+    case 'failed': return s.save === 'saving' ? { ...s, save: 'failed' } : s;
+    case 'reset': return a.state;
+  }
+}
+
+export type DashboardView = {
+  scene: DashboardScene;
+  chip: { tone: StateChipTone; label: string };
+  gridHint: string;
+  footerHint: string;
+  primaryLabel: string;
+  canSave: boolean;
+  atMax: boolean;
+  below: boolean;
+};
+
+export function dashboardView(c: DashboardConfigSettings, s: DashboardState): DashboardView {
+  const n = s.selected.length;
+  const atMax = n >= c.max;
+  const below = n < c.min;
+  const range = c.min <= 1 ? `Pick up to ${c.max} widgets` : `Pick ${c.min} to ${c.max} widgets`;
+  return {
+    scene: s.save !== 'idle' ? s.save : below ? 'below' : atMax ? 'atMax' : 'default',
+    chip: s.save === 'saving' ? { tone: 'neutral', label: c.savingLabel }
+      : s.save === 'saved' ? { tone: 'success', label: c.savedLabel }
+      : { tone: 'neutral', label: `${n} selected` },
+    gridHint: atMax ? `Up to ${c.max} widgets. Deselect one to swap it.` : range,
+    footerHint: s.save === 'saved' ? c.savedHint : below ? `Pick at least ${c.min} to continue` : `${n} of ${c.max} widgets`,
+    primaryLabel: s.save === 'saving' ? c.savingLabel : s.save === 'saved' ? c.savedLabel : s.save === 'failed' ? c.retryLabel : c.primaryLabel,
+    canSave: !below && !isLocked(s),
+    atMax,
+    below,
+  };
+}

package/src/components/onboarding/dashboard-config/index.ts

@@ -0,0 +1,10 @@
+export {
+  DASHBOARD_PRESETS, DASHBOARD_SCENES, DASHBOARD_IN_FLIGHT, validateDashboardConfig,
+  type DashboardConfigSettings, type DashboardScene, type DashboardWidget,
+} from './contract';
+export {
+  dashboardSeed, initialDashboard, reduceDashboard, dashboardView,
+  type DashboardAction, type DashboardSeed, type DashboardState, type DashboardView,
+} from './engine';
+export { useDashboardConfig, type DashboardOperations, type DashboardSaveRequest } from './runtime';
+export { DashboardConfig, type DashboardConfigProps } from './DashboardConfigView';

package/src/components/onboarding/dashboard-config/presets.json

@@ -0,0 +1,307 @@
+{
+  "component": "dashboard-config",
+  "baseCopy": {
+    "loadErrorTitle": "Couldn’t load this step",
+    "loadErrorBody": "Nothing was lost. Retry to load it again.",
+    "retryLabel": "Retry",
+    "emptyCta": "Refresh"
+  },
+  "base": {
+    "type": "data",
+    "icon": "grid",
+    "title": "Set up your sales overview",
+    "subtitle": "Choose the widgets on your home dashboard.",
+    "min": 1,
+    "max": 4,
+    "widgets": [
+      {
+        "id": "pipeline",
+        "type": "data",
+        "icon": "chart",
+        "title": "Pipeline",
+        "description": "Open deals by stage"
+      },
+      {
+        "id": "winrate",
+        "type": "data",
+        "icon": "trend",
+        "title": "Win rate",
+        "description": "Closed won versus lost"
+      },
+      {
+        "id": "quota",
+        "type": "action",
+        "icon": "target",
+        "title": "Quota",
+        "description": "Progress against this quarter"
+      },
+      {
+        "id": "deals",
+        "type": "file",
+        "icon": "briefcase",
+        "title": "Top deals",
+        "description": "Five largest open deals"
+      },
+      {
+        "id": "activity",
+        "type": "schedule",
+        "icon": "pulse",
+        "title": "Activity",
+        "description": "Calls and meetings this week"
+      },
+      {
+        "id": "forecast",
+        "type": "agent",
+        "icon": "sparkle",
+        "title": "Forecast",
+        "description": "Projected close for the quarter"
+      }
+    ],
+    "defaultSelected": [
+      "pipeline",
+      "quota"
+    ],
+    "primaryLabel": "Save dashboard",
+    "savingLabel": "Saving…",
+    "savedLabel": "Saved",
+    "savedHint": "Saved · your dashboard is ready",
+    "saveErrorTitle": "Couldn’t save your dashboard",
+    "saveErrorBody": "Your picks are still here. Retry when you’re ready.",
+    "emptyTitle": "No widgets available",
+    "emptyBody": "Connect a data source to unlock widgets.",
+    "emptyCta": "Refresh"
+  },
+  "cases": {
+    "case1": {},
+    "case2": {
+      "icon": "server",
+      "title": "Service health dashboard",
+      "subtitle": "What the on-call engineer sees first.",
+      "min": 2,
+      "max": 6,
+      "defaultSelected": [
+        "uptime",
+        "errors",
+        "latency"
+      ],
+      "widgets": [
+        {
+          "id": "uptime",
+          "type": "data",
+          "icon": "pulse",
+          "title": "Uptime",
+          "description": "Availability over 30 days"
+        },
+        {
+          "id": "errors",
+          "type": "data",
+          "icon": "alert",
+          "title": "Error rate",
+          "description": "5xx responses per minute"
+        },
+        {
+          "id": "latency",
+          "type": "schedule",
+          "icon": "clock",
+          "title": "Latency",
+          "description": "p95 response time"
+        },
+        {
+          "id": "deploys",
+          "type": "action",
+          "icon": "rocket",
+          "title": "Deploys",
+          "description": "Releases in the last 24 hours"
+        },
+        {
+          "id": "incidents",
+          "type": "agent",
+          "icon": "bell",
+          "title": "Incidents",
+          "description": "Open and recently resolved"
+        },
+        {
+          "id": "queue",
+          "type": "file",
+          "icon": "layers",
+          "title": "Queue depth",
+          "description": "Jobs waiting per worker"
+        }
+      ]
+    },
+    "case3": {
+      "icon": "headset",
+      "title": "Support desk home",
+      "subtitle": "Pick what agents see on sign-in.",
+      "min": 1,
+      "max": 3,
+      "ship": "atMax",
+      "defaultSelected": [
+        "open",
+        "reply",
+        "csat"
+      ],
+      "widgets": [
+        {
+          "id": "open",
+          "type": "action",
+          "icon": "inbox",
+          "title": "Open tickets",
+          "description": "Waiting on an agent"
+        },
+        {
+          "id": "reply",
+          "type": "schedule",
+          "icon": "chat",
+          "title": "First reply",
+          "description": "Median time to first response"
+        },
+        {
+          "id": "csat",
+          "type": "agent",
+          "icon": "smile",
+          "title": "CSAT",
+          "description": "Satisfaction over 7 days"
+        },
+        {
+          "id": "backlog",
+          "type": "data",
+          "icon": "tasks",
+          "title": "Backlog",
+          "description": "Tickets older than 48 hours"
+        },
+        {
+          "id": "tags",
+          "type": "file",
+          "icon": "tag",
+          "title": "Tags",
+          "description": "Most common topics this week"
+        }
+      ]
+    },
+    "case4": {
+      "icon": "cash",
+      "title": "Finance snapshot",
+      "subtitle": "A board-ready view of cash and spend.",
+      "min": 3,
+      "max": 5,
+      "defaultSelected": [
+        "cash",
+        "burn",
+        "runway"
+      ],
+      "widgets": [
+        {
+          "id": "cash",
+          "type": "data",
+          "icon": "cash",
+          "title": "Cash",
+          "description": "Balance across accounts"
+        },
+        {
+          "id": "burn",
+          "type": "action",
+          "icon": "flame",
+          "title": "Burn",
+          "description": "Net monthly outflow"
+        },
+        {
+          "id": "runway",
+          "type": "schedule",
+          "icon": "hourglass",
+          "title": "Runway",
+          "description": "Months at current burn"
+        },
+        {
+          "id": "ar",
+          "type": "file",
+          "icon": "download",
+          "title": "Receivables",
+          "description": "Invoices awaiting payment"
+        },
+        {
+          "id": "ap",
+          "type": "file",
+          "icon": "upload",
+          "title": "Payables",
+          "description": "Bills due in 30 days"
+        },
+        {
+          "id": "spend",
+          "type": "agent",
+          "icon": "pie",
+          "title": "Spend by team",
+          "description": "This quarter versus plan"
+        }
+      ]
+    },
+    "case5": {
+      "type": "agent",
+      "icon": "sparkle",
+      "title": "Your assistant’s home",
+      "subtitle": "Choose what it shows when you open it.",
+      "min": 1,
+      "max": 4,
+      "defaultSelected": [
+        "today"
+      ],
+      "widgets": [
+        {
+          "id": "today",
+          "type": "schedule",
+          "icon": "calendar",
+          "title": "Today’s schedule",
+          "description": "Meetings and focus time"
+        },
+        {
+          "id": "drafts",
+          "type": "agent",
+          "icon": "pen",
+          "title": "Drafts",
+          "description": "Replies waiting for review"
+        },
+        {
+          "id": "files",
+          "type": "file",
+          "icon": "file",
+          "title": "Recent files",
+          "description": "Opened in the last week"
+        },
+        {
+          "id": "auto",
+          "type": "action",
+          "icon": "bolt",
+          "title": "Automations",
+          "description": "Runs and failures today"
+        }
+      ]
+    }
+  },
+  "meta": {
+    "case1": {
+      "eyebrow": "Case study 1 · Sales",
+      "title": "Sales overview",
+      "scenario": "A sales rep picks up to four widgets for their home dashboard."
+    },
+    "case2": {
+      "eyebrow": "Case study 2 · DevOps",
+      "title": "Service health",
+      "scenario": "An on-call engineer builds a health view. At least two widgets are needed, and all six fit."
+    },
+    "case3": {
+      "eyebrow": "Case study 3 · Support",
+      "title": "Support desk",
+      "scenario": "A support lead sets the agent home view. It ships at the maximum, so the unselected cards are disabled."
+    },
+    "case4": {
+      "eyebrow": "Case study 4 · Finance",
+      "title": "Finance snapshot",
+      "scenario": "A finance lead builds a board-ready snapshot. Three widgets are the minimum."
+    },
+    "case5": {
+      "eyebrow": "Case study 5 · AI agent",
+      "title": "Assistant home",
+      "scenario": "A user chooses what their assistant shows first. The four widgets span four hues."
+    }
+  }
+}

package/src/components/onboarding/dashboard-config/runtime.ts

@@ -0,0 +1,80 @@
+import { useCallback, useEffect, useMemo, useReducer, useRef } from 'react';
+import { useOperationRunner } from '../../../runtime/operations';
+import type { OnboardingResult } from '../shared/contract';
+import { ONBOARDING_TIMING, createMockOperation, type OnboardingOperation } from '../shared/mock';
+import { runOutcome } from '../shared/runtime';
+import type { DashboardConfigSettings } from './contract';
+import {
+  dashboardSeed, initialDashboard, reduceDashboard, dashboardView,
+  type DashboardAction, type DashboardSeed, type DashboardState,
+} from './engine';
+
+/** What the host is asked to do on Save. */
+export type DashboardSaveRequest = { selected: string[] };
+export type DashboardOperations = { save: OnboardingOperation<DashboardSaveRequest> };
+
+/**
+ * **The Dashboard Config runtime** — the reducer and its one boundary operation, save, through
+ * `src/runtime/operations`. Without `operations`, save runs the prototype's placeholder (1400ms)
+ * and `result` decides how it ends — the README's demo contract; a product passes `operations`.
+ */
+export function useDashboardConfig({
+  config, operations, result = 'success', initial, onChange, onSave,
+}: {
+  config: DashboardConfigSettings;
+  operations?: DashboardOperations;
+  result?: OnboardingResult;
+  initial?: DashboardSeed;
+  onChange?: (selected: string[]) => void;
+  onSave?: (selected: string[]) => void;
+}) {
+  const seed = () => initialDashboard(config, initial ?? (config.ship ? dashboardSeed(config, config.ship) : {}));
+  const [state, send] = useReducer((s: DashboardState, a: DashboardAction) => reduceDashboard(config, s, a), undefined, seed);
+  const stateRef = useRef(state);
+  stateRef.current = state;
+  const runner = useOperationRunner();
+  const save = useMemo(
+    () => operations?.save ?? createMockOperation<DashboardSaveRequest>({ latencyMs: ONBOARDING_TIMING.save, fail: () => result === 'error' }),
+    [operations, result],
+  );
+
+  /* A new config (a preset switch) or seed starts over; an equal one re-rendered does not. */
+  const key = JSON.stringify([config, initial ?? null]);
+  const seeded = useRef(key);
+  useEffect(() => {
+    if (seeded.current === key) return;
+    seeded.current = key;
+    runner.cancel('save');
+    send({ type: 'reset', state: seed() });
+  });
+
+  const run = useCallback(() => {
+    const s = stateRef.current;
+    runOutcome(runner, 'save', save, { selected: s.selected }, {
+      ok: () => { send({ type: 'saved' }); onSave?.(s.selected); },
+      fail: () => send({ type: 'failed' }),
+    });
+  }, [runner, save, onSave]);
+
+  /* A session restored mid-save (the "saving" scene) finishes the save it was in. */
+  useEffect(() => { if (stateRef.current.save === 'saving') run(); }, [key]);
+
+  const selectedKey = state.selected.join('|');
+  const reported = useRef(selectedKey);
+  useEffect(() => {
+    if (reported.current === selectedKey) return;
+    reported.current = selectedKey;
+    onChange?.(state.selected);
+  }, [selectedKey]);
+
+  return {
+    state,
+    view: dashboardView(config, state),
+    toggle: (id: string) => send({ type: 'toggle', id }),
+    save: () => {
+      if (!dashboardView(config, stateRef.current).canSave) return;
+      send({ type: 'save' });
+      run();
+    },
+  };
+}