@appinternalleads/ui 0.2.0

package/src/components/onboarding/mark-read/presets.json

@@ -0,0 +1,266 @@
+{
+  "component": "mark-read",
+  "baseCopy": {
+    "loadErrorTitle": "Couldn’t load this step",
+    "loadErrorBody": "Nothing was lost. Retry to load it again.",
+    "retryLabel": "Retry",
+    "emptyCta": "Refresh"
+  },
+  "base": {
+    "type": "action",
+    "icon": "bell",
+    "title": "Notifications",
+    "subtitle": "Northwind workspace",
+    "items": [
+      {
+        "type": "agent",
+        "icon": "chat",
+        "title": "Sam mentioned you in Launch plan",
+        "subtitle": "“@you can you check the dates?”",
+        "time": "2m",
+        "unread": true
+      },
+      {
+        "type": "file",
+        "icon": "doc",
+        "title": "Jo commented on Roadmap",
+        "subtitle": "Looks good to me",
+        "time": "18m",
+        "unread": true
+      },
+      {
+        "type": "action",
+        "icon": "tasks",
+        "title": "You were assigned “Fix billing bug”",
+        "subtitle": "Due tomorrow",
+        "time": "1h",
+        "unread": true
+      },
+      {
+        "type": "data",
+        "icon": "server",
+        "title": "Weekly backup finished",
+        "subtitle": "All 4 projects backed up",
+        "time": "3h",
+        "unread": false
+      },
+      {
+        "type": "schedule",
+        "icon": "calendar",
+        "title": "Stand-up moved to 10:30",
+        "subtitle": "Updated by Priya",
+        "time": "Yesterday",
+        "unread": false
+      }
+    ],
+    "emptyTitle": "All caught up",
+    "emptyBody": "You’ve read every notification.",
+    "emptyCta": "View earlier"
+  },
+  "cases": {
+    "case1": {},
+    "case2": {
+      "type": "data",
+      "icon": "cart",
+      "title": "Order updates",
+      "subtitle": "Harbor Goods",
+      "items": [
+        {
+          "type": "data",
+          "icon": "cart",
+          "title": "Order #1048 placed",
+          "subtitle": "$64.00 · 2 items",
+          "time": "1m",
+          "unread": true
+        },
+        {
+          "type": "data",
+          "icon": "cart",
+          "title": "Order #1047 placed",
+          "subtitle": "$120.00 · 3 items",
+          "time": "6m",
+          "unread": true
+        },
+        {
+          "type": "schedule",
+          "icon": "truck",
+          "title": "Order #1045 shipped",
+          "subtitle": "Arrives Thursday",
+          "time": "20m",
+          "unread": true
+        },
+        {
+          "type": "data",
+          "icon": "cash",
+          "title": "Order #1044 paid",
+          "subtitle": "$128.50",
+          "time": "42m",
+          "unread": true
+        },
+        {
+          "type": "action",
+          "icon": "refresh",
+          "title": "Return requested · #1039",
+          "subtitle": "Wrong size",
+          "time": "1h",
+          "unread": true
+        },
+        {
+          "type": "data",
+          "icon": "cart",
+          "title": "Order #1043 placed",
+          "subtitle": "$42.00",
+          "time": "2h",
+          "unread": true
+        },
+        {
+          "type": "schedule",
+          "icon": "truck",
+          "title": "Order #1042 delivered",
+          "subtitle": "Signed by Ana",
+          "time": "3h",
+          "unread": true
+        },
+        {
+          "type": "agent",
+          "icon": "star",
+          "title": "New review on Linen shirt",
+          "subtitle": "5 stars",
+          "time": "5h",
+          "unread": true
+        }
+      ]
+    },
+    "case3": {
+      "type": "schedule",
+      "icon": "book",
+      "title": "Classroom",
+      "subtitle": "Year 9 · Biology",
+      "items": [
+        {
+          "type": "file",
+          "icon": "doc",
+          "title": "New assignment: Cell structure",
+          "subtitle": "Due Friday",
+          "time": "10m",
+          "unread": true
+        },
+        {
+          "type": "agent",
+          "icon": "chat",
+          "title": "Ms Rahman replied to your question",
+          "subtitle": "“Yes, diagrams count”",
+          "time": "1h",
+          "unread": false
+        },
+        {
+          "type": "schedule",
+          "icon": "calendar",
+          "title": "Quiz moved to Monday",
+          "subtitle": "Room 12",
+          "time": "Yesterday",
+          "unread": false
+        },
+        {
+          "type": "data",
+          "icon": "chart",
+          "title": "Grades posted: Lab report",
+          "subtitle": "18 / 20",
+          "time": "Mon",
+          "unread": false
+        }
+      ]
+    },
+    "case4": {
+      "type": "schedule",
+      "icon": "building",
+      "title": "Clinic inbox",
+      "subtitle": "Riverside Clinic",
+      "items": [],
+      "emptyCta": "View last week"
+    },
+    "case5": {
+      "type": "agent",
+      "icon": "sparkle",
+      "title": "Needs approval",
+      "subtitle": "Your assistant is waiting on you",
+      "items": [
+        {
+          "type": "agent",
+          "icon": "cash",
+          "title": "Send $120 to Harbor Legal?",
+          "subtitle": "Invoice #88 · due today",
+          "time": "3m",
+          "unread": true
+        },
+        {
+          "type": "agent",
+          "icon": "mail",
+          "title": "Send reply to Ana Ruiz?",
+          "subtitle": "Re: Contract changes",
+          "time": "12m",
+          "unread": true
+        },
+        {
+          "type": "agent",
+          "icon": "calendar",
+          "title": "Accept meeting with Ken Ito?",
+          "subtitle": "Thu 11:00–11:30",
+          "time": "1h",
+          "unread": false
+        },
+        {
+          "type": "agent",
+          "icon": "users",
+          "title": "Share Roadmap with Jo?",
+          "subtitle": "Edit access",
+          "time": "2h",
+          "unread": false
+        },
+        {
+          "type": "agent",
+          "icon": "box",
+          "title": "Order office supplies?",
+          "subtitle": "$48.20 · Staples",
+          "time": "Yesterday",
+          "unread": false
+        },
+        {
+          "type": "agent",
+          "icon": "globe",
+          "title": "Renew northwind.com?",
+          "subtitle": "$12 · 1 year",
+          "time": "Mon",
+          "unread": false
+        }
+      ]
+    }
+  },
+  "meta": {
+    "case1": {
+      "eyebrow": "Case study 1 · SaaS",
+      "title": "Workspace",
+      "scenario": "Five workspace notifications, three of them unread."
+    },
+    "case2": {
+      "eyebrow": "Case study 2 · E-commerce",
+      "title": "Orders",
+      "scenario": "A merchant has eight order updates, all unread."
+    },
+    "case3": {
+      "eyebrow": "Case study 3 · Education",
+      "title": "Classroom",
+      "scenario": "A student has one new assignment."
+    },
+    "case4": {
+      "eyebrow": "Case study 4 · Healthcare ops",
+      "title": "Clinic",
+      "scenario": "Nothing new, so the inbox shows \"All caught up\" with one action."
+    },
+    "case5": {
+      "eyebrow": "Case study 5 · AI agent",
+      "title": "Agent inbox",
+      "scenario": "Six requests from the assistant are waiting for approval. Two are unread."
+    }
+  }
+}

package/src/components/onboarding/onboarding-step/OnboardingStepView.tsx

@@ -0,0 +1,158 @@
+import { Box, MotionView, Text, useTween } from '../../../core';
+import { blockRadii, useDs, type DensityName } from '../../../tokens';
+import { iconFor, resolveConfig, type OnboardingPreset, type OnboardingResult, type PatternStatus } from '../shared/contract';
+import { ONBOARDING_TIMING, type OnboardingOperation } from '../shared/mock';
+import { InvalidConfig } from '../shared/InvalidConfig';
+import { OnboardingCard } from '../shared/OnboardingCard';
+import { HueTile, Slot, StatusMark } from '../shared/parts';
+import { runOutcome, useDefaultOperation, usePatternStatus, useSceneReport, useSeededReducer } from '../shared/runtime';
+import { useOperationRunner } from '../../../runtime/operations';
+import { STEP_PRESETS, validateOnboardingStep, type OnboardingStepSettings, type SetupStep } from './contract';
+import { initialOnboardingStep, reduceOnboardingStep, stepSeed, stepView, type DotState, type OnboardingStepSeed } from './engine';
+import { guarded } from '../shared/guard';
+
+export type OnboardingStepOperations = {
+  /** Do the current step ("Invite", "Connect"). The prototype's placeholder is 900ms. */
+  advance: OnboardingOperation<{ index: number; title: string }>;
+};
+
+export type OnboardingStepProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<OnboardingStepSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  /** The prototype's step never fails; an `operations.advance` that refuses leaves the step current. */
+  result?: OnboardingResult;
+  operations?: OnboardingStepOperations;
+  reload?: OnboardingOperation<void>;
+  initial?: OnboardingStepSeed;
+  onStep?: (step: SetupStep, how: 'done' | 'skipped') => void;
+  onFinish?: (skipped: number[]) => void;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+/**
+ * **Onboarding Step** — Q3 dots (a named list: done ink, current ink and stretched, upcoming line,
+ * skipped a hollow ring), the current step as a card that cross-fades to the next (M4) — a 48px hue
+ * tile, "Step n of N", the title and what it does — then "Up next". Footer: Skip (if skippable) and
+ * the step's own verb; the last step finishes to "You're all set".
+ */
+function OnboardingStepView(props: OnboardingStepProps) {
+  const config = resolveConfig(STEP_PRESETS, props.preset, props.config);
+  const issues = validateOnboardingStep(config);
+  if (issues.length) return <InvalidConfig title={config.title} issues={issues} testID={props.testID} />;
+  return <Valid {...props} config={config} />;
+}
+
+function Valid({
+  config, density, status, result, operations, reload, initial, onStep, onFinish, onScene, testID,
+}: Omit<OnboardingStepProps, 'config'> & { config: OnboardingStepSettings }) {
+  const { colors, density: d } = useDs();
+  const runner = useOperationRunner();
+  const key = JSON.stringify([config, initial ?? null]);
+  const [state, send, ref] = useSeededReducer(
+    reduceOnboardingStep,
+    () => initialOnboardingStep(config, initial ?? (config.ship ? stepSeed(config, config.ship) : {})),
+    key,
+    () => runner.cancel('advance'),
+  );
+  const pattern = usePatternStatus(status ?? 'ready', reload);
+  const v = stepView(config, state);
+  useSceneReport(pattern.status === 'ready' ? (state.phase === 'working' ? 'working' : v.scene) : pattern.status, onScene);
+  const advance = useDefaultOperation(operations?.advance, ONBOARDING_TIMING.finish, () => result === 'error');
+  const n = config.steps.length;
+  const move = (skip: boolean) => {
+    const s = ref.current;
+    const step = config.steps[s.current]!;
+    const next = reduceOnboardingStep(s, { type: 'advance', skip, count: n });
+    send({ type: 'advance', skip, count: n });
+    onStep?.(step, skip ? 'skipped' : 'done');
+    if (next.finished) onFinish?.(next.skipped);
+  };
+  const doIt = () => {
+    const s = ref.current;
+    if (s.finished || s.phase === 'working') return;
+    send({ type: 'work' });
+    runOutcome(runner, 'advance', advance, { index: s.current, title: config.steps[s.current]!.title }, { ok: () => move(false), fail: () => send({ type: 'rest' }) });
+  };
+  const working = state.phase === 'working';
+  const step = config.steps[state.current]!;
+
+  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={v.canSkip ? { label: 'Skip', disabled: working, onPress: () => { if (!ref.current.finished && ref.current.phase !== 'working') move(true); } } : undefined}
+      primary={{ label: v.primaryLabel, disabled: state.finished, busy: working, onPress: doIt }}>
+      <Box gap="s3">
+        <Box role="list" aria-label="Setup progress" row align="center" gap="s2" style={{ gap: 6 }}>
+          {config.steps.map((s, i) => <StepDot key={i} state={v.dots[i]!} label={`Step ${i + 1}: ${s.title}, ${v.dots[i]}`} />)}
+        </Box>
+        {v.skipNote ? <Text variant="caption" color="textSecondary" style={{ fontSize: 12 }}>{v.skipNote}</Text> : null}
+        <Slot slotKey={state.finished ? 'done' : `step-${state.current}`} align="flex-start">
+          <Box
+            row
+            align={state.finished ? 'center' : 'flex-start'}
+            gap="s3"
+            style={{ flex: 1, gap: 14, borderWidth: 1, borderColor: colors.hairlineStrong, borderRadius: blockRadii.mid, paddingHorizontal: d.padX, paddingVertical: d.padY }}>
+            {state.finished ? (
+              <>
+                <StatusMark tone="mint" size={48} />
+                <Box flex={1} gap="s1" style={{ minWidth: 0 }}>
+                  <Text variant="label" color="textPrimary" style={{ fontSize: 16, fontWeight: '600', letterSpacing: -0.24 }}>{config.doneTitle}</Text>
+                  <Text variant="caption" color="textSecondary" style={{ fontSize: 13 }}>{v.doneBody}</Text>
+                </Box>
+              </>
+            ) : (
+              <>
+                <HueTile icon={iconFor(step.icon)} type={step.type} size={48} />
+                <Box flex={1} gap="s1" style={{ minWidth: 0 }}>
+                  <Text variant="caption" color="textSecondary" numeric style={{ fontSize: 12 }}>{`Step ${state.current + 1} of ${n}`}</Text>
+                  <Text variant="label" color="textPrimary" style={{ fontSize: 16, fontWeight: '600', letterSpacing: -0.24 }}>{step.title}</Text>
+                  <Text variant="caption" color="textSecondary" style={{ fontSize: 13 }}>{step.description}</Text>
+                </Box>
+              </>
+            )}
+          </Box>
+        </Slot>
+        {v.next ? (
+          <Box row align="center" gap="s2" style={{ paddingVertical: 10, paddingHorizontal: 12, borderRadius: blockRadii.inset, backgroundColor: colors.surfaceSunken }}>
+            <HueTile icon={iconFor(v.next.icon)} tone="muted" size={24} />
+            <Text variant="caption" color="textSecondary" style={{ fontSize: 12, flexShrink: 1 }}>
+              {'Up next · '}
+              <Text variant="caption" color="textSecondary" style={{ fontSize: 12, fontWeight: '600' }}>{v.next.title}</Text>
+            </Text>
+          </Box>
+        ) : null}
+      </Box>
+    </OnboardingCard>
+  );
+}
+
+/** One Q3 dot. The current one stretches to 2.5× (M7) — drawn as its width, so the row reflows. */
+function StepDot({ state, label }: { state: DotState; label: string }) {
+  const { colors } = useDs();
+  const w = useTween(state === 'current' ? 20 : 8);
+  return (
+    <MotionView
+      role="listitem"
+      aria-label={label}
+      style={{
+        height: 8, width: w, borderRadius: 4,
+        backgroundColor: state === 'skipped' ? 'transparent' : state === 'upcoming' ? colors.hairlineStrong : colors.textPrimary,
+        ...(state === 'skipped' ? { borderWidth: 1.5, borderColor: colors.textSecondary } : null),
+      }}
+    />
+  );
+}
+
+/** OnboardingStep, guarded: a wrong-kind config is refused by name and a render error is caught, never thrown to the page (`shared/guard`). */
+export const OnboardingStep = guarded(OnboardingStepView, STEP_PRESETS, 'OnboardingStep');

package/src/components/onboarding/onboarding-step/contract.ts

@@ -0,0 +1,38 @@
+import type { DataType } from '../../../tokens';
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import presetsJson from './presets.json';
+
+/** **Onboarding Step (batch 3 §3.9)** — an in-product nudge for the current setup step. */
+
+export type SetupStep = { type: DataType; icon: string; title: string; description: string; ctaLabel: string };
+
+export const STEP_SCENES = ['default', 'current', 'completed', 'skipped', 'final', 'done', 'loading', 'empty', 'error'] as const;
+export type StepScene = (typeof STEP_SCENES)[number];
+/** Scenes that are an operation in flight — none: "Working…" is one click from any step. */
+export const STEP_IN_FLIGHT: readonly string[] = [];
+
+export type OnboardingStepSettings = HeaderConfig & LoadCopy & {
+  steps: SetupStep[];
+  /** 0-based. */
+  current: number;
+  skippable: boolean;
+  /** Steps skipped earlier (0-based). */
+  skippedIdx: number[];
+  /** The primary when a step has no `ctaLabel`. */
+  primaryLabel: string;
+  doneTitle: string;
+  doneBody: string;
+  doneHint: string;
+  /** Demo-only: the scene this case ships in (B2-9). */
+  ship?: StepScene;
+};
+
+export const STEP_PRESETS = presetsJson as unknown as PresetsFile<OnboardingStepSettings>;
+
+export function validateOnboardingStep(c: OnboardingStepSettings): OnboardingIssue[] {
+  if (!Array.isArray(c.steps) || !c.steps.length) return [{ path: 'steps', message: 'steps must list at least one step.' }];
+  const issues: OnboardingIssue[] = [];
+  if (!(Number.isInteger(c.current) && c.current >= 0 && c.current < c.steps.length)) issues.push({ path: 'current', message: `current is a step index from 0 to ${c.steps.length - 1}.` });
+  (c.skippedIdx ?? []).forEach((k, i) => { if (!(Number.isInteger(k) && k >= 0 && k < c.steps.length)) issues.push({ path: `skippedIdx[${i}]`, message: 'Not a step index.' }); });
+  return issues;
+}

package/src/components/onboarding/onboarding-step/engine.ts

@@ -0,0 +1,55 @@
+import type { OnboardingStepSettings, StepScene } from './contract';
+
+/** **The Onboarding Step engine** — pure: the current step, what was skipped, and finishing. */
+
+export type StepPhase = 'idle' | 'working';
+export type OnboardingStepState = { current: number; skipped: number[]; phase: StepPhase; finished: boolean };
+export type OnboardingStepSeed = Partial<OnboardingStepState>;
+export type OnboardingStepAction = { type: 'work' } | { type: 'advance'; skip: boolean; count: number } | { type: 'rest' };
+export type DotState = 'done' | 'current' | 'upcoming' | 'skipped';
+
+export function initialOnboardingStep(c: OnboardingStepSettings, seed: OnboardingStepSeed = {}): OnboardingStepState {
+  return { current: seed.current ?? c.current, skipped: seed.skipped ?? [...(c.skippedIdx ?? [])], phase: seed.phase ?? 'idle', finished: seed.finished ?? false };
+}
+
+export function stepSeed(c: OnboardingStepSettings, scene: StepScene): OnboardingStepSeed {
+  const last = c.steps.length - 1;
+  if (scene === 'completed') return { current: Math.min(last, c.current + 1) };
+  if (scene === 'skipped') return { skipped: [...(c.skippedIdx ?? []), c.current], current: Math.min(last, c.current + 1) };
+  if (scene === 'final') return { current: last };
+  if (scene === 'done') return { current: last, finished: true };
+  return {};
+}
+
+export function reduceOnboardingStep(s: OnboardingStepState, a: OnboardingStepAction): OnboardingStepState {
+  switch (a.type) {
+    case 'work': return s.finished || s.phase === 'working' ? s : { ...s, phase: 'working' };
+    case 'rest': return { ...s, phase: 'idle' };
+    case 'advance': {
+      if (s.finished) return s;
+      const skipped = a.skip && !s.skipped.includes(s.current) ? [...s.skipped, s.current] : s.skipped;
+      if (s.current >= a.count - 1) return { ...s, skipped, phase: 'idle', finished: true };
+      return { ...s, skipped, phase: 'idle', current: s.current + 1 };
+    }
+  }
+}
+
+export function stepView(c: OnboardingStepSettings, s: OnboardingStepState) {
+  const n = c.steps.length;
+  const fin = s.finished;
+  const dots: DotState[] = c.steps.map((_, i) => (s.skipped.includes(i) ? 'skipped' : i === s.current && !fin ? 'current' : i < s.current || fin ? 'done' : 'upcoming'));
+  const skippedNums = [...s.skipped].sort((a, b) => a - b).map(i => i + 1);
+  const next = !fin && s.current < n - 1 ? c.steps[s.current + 1]! : null;
+  const left = n - s.current - 1;
+  return {
+    dots,
+    next,
+    skipNote: skippedNums.length && !fin ? `Skipped step ${skippedNums.join(' and ')} · you can come back to it` : '',
+    doneBody: skippedNums.length ? `You skipped step ${skippedNums.join(' and ')}. You can finish it from Settings.` : c.doneBody,
+    chip: fin ? { tone: 'success' as const, label: 'Set up', dot: true } : { tone: 'neutral' as const, label: `Step ${s.current + 1} of ${n}`, dot: false },
+    footerHint: fin ? c.doneHint : s.current === n - 1 ? 'Last step' : `${left} ${left === 1 ? 'step' : 'steps'} after this`,
+    primaryLabel: s.phase === 'working' ? 'Working…' : fin ? 'Done' : c.steps[s.current]!.ctaLabel || c.primaryLabel,
+    canSkip: c.skippable && !fin,
+    scene: (fin ? 'done' : s.current === n - 1 ? 'final' : 'current') as StepScene,
+  };
+}

package/src/components/onboarding/onboarding-step/index.ts

@@ -0,0 +1,9 @@
+export {
+  STEP_IN_FLIGHT, STEP_PRESETS, STEP_SCENES, validateOnboardingStep,
+  type OnboardingStepSettings, type SetupStep, type StepScene,
+} from './contract';
+export {
+  initialOnboardingStep, reduceOnboardingStep, stepSeed, stepView,
+  type DotState, type OnboardingStepAction, type OnboardingStepSeed, type OnboardingStepState, type StepPhase,
+} from './engine';
+export { OnboardingStep, type OnboardingStepOperations, type OnboardingStepProps } from './OnboardingStepView';