@frame-kit/ui-ng-patterns 0.1.19 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frame-kit/ui-ng-patterns",
-  "version": "0.1.19",
+  "version": "0.2.0",
   "description": "Opinionated, dashboard-ready Angular component patterns composed from @frame-kit/ui-ng.",
   "license": "MIT",
   "repository": {
@@ -17,7 +17,7 @@
     "@angular/forms": "^21.2.0",
     "@angular/platform-browser": "^21.2.0",
     "@angular/router": "^21.2.0",
-    "@frame-kit/ui-ng": "0.1.19",
+    "@frame-kit/ui-ng": "0.2.0",
     "rxjs": "^7.0.0"
   },
   "sideEffects": false,

package/types/frame-kit-ui-ng-patterns-dashboard.d.ts

@@ -618,8 +618,8 @@ interface OnboardingSubstep {
  * - a **group** step — carries `substeps`, and is considered complete once every
  *   substep is `done` (the top-level `done` flag is ignored for group steps).
  *
- * All state (`done`) is owned by the consumer; the widget is a controlled view
- * of the `steps` model and emits events when the user acts.
+ * All state (`done`, `pending`) is owned by the consumer; the widget is a
+ * controlled view of the `steps` model and emits events when the user acts.
  */
 interface OnboardingStep {
     /** Stable identifier, unique within the guide. */
@@ -628,10 +628,23 @@ interface OnboardingStep {
     label: string;
     /** Whether a leaf step is complete. Ignored when `substeps` is set. */
     done: boolean;
+    /**
+     * The step is in flight — not complete, but expected to complete without
+     * further user action (e.g. an invite that auto-completes when accepted).
+     * Purely visual: a pending step still counts as incomplete for progress.
+     */
+    pending?: boolean;
+    /** Optional supporting copy shown while the step is `pending`. */
+    pendingNote?: string;
     /** Optional supporting copy shown when the step is expanded. */
     description?: string;
     /** Optional call-to-action label (defaults to a generic "Start"). */
     actionLabel?: string;
+    /**
+     * Optional secondary text-action label (e.g. "Show help"). When set, the
+     * expanded body renders it and clicks emit `stepSecondaryAction`.
+     */
+    secondaryActionLabel?: string;
     /** When set, the step renders a sub-checklist and auto-completes when all are done. */
     substeps?: OnboardingSubstep[];
 }
@@ -648,19 +661,41 @@ interface Point {
 /**
  * A floating, draggable onboarding-progress widget. It presents a checklist of
  * steps with a progress bar, collapses to a compact pill with a progress ring,
- * and can be dragged anywhere on screen (CDK drag). It renders over the app in
- * a fixed layer — drop it once near the app root.
+ * and can be dragged around (CDK drag). It renders over the app in a fixed
+ * layer — drop it once near the app root.
+ *
+ * **Presentational, not clever.** It renders exactly what it is given and
+ * reports what the user did — it derives no step state of its own. Which step
+ * is open (`openStepId`), which are done or pending (`steps`), whether it is
+ * collapsed (`collapsed`): all inputs. When a step should advance, when a
+ * context switch should re-focus the guide, when a choice has gone stale —
+ * all consumer decisions, because the consumer knows *what changed*, while
+ * the widget only ever sees a new array.
  *
  * **Controlled model, no domain data.** The `steps` model is a required,
  * reactive input: the widget is a pure view of it and emits events when the
- * user acts (`stepAction`, `stepMarkDone`, `substepToggle`, `goLive`). The
- * consumer owns the step state — so if it is keyed by, say, the active account
- * or environment, swapping the input re-renders the widget instantly. The
- * widget never persists step state.
+ * user acts (`stepAction`, `stepMarkDone`, `stepSecondaryAction`,
+ * `substepToggle`, `footerAction`). The consumer owns the step state — so if
+ * it is keyed by, say, the active account or environment, swapping the input
+ * re-renders the widget instantly. The widget never persists step state.
+ *
+ * **Collapsed and openStepId are two-way models.** Bind `[(collapsed)]` /
+ * `[(openStepId)]` to drive the card ↔ pill swap and the expanded row from
+ * outside; the widget writes them only in response to a direct user action.
  *
- * **Presentation state is internal + persisted.** Collapsed and drag position
- * live in the widget and persist to `localStorage` under `storageKey` — these
- * are UI preferences, not part of the model.
+ * **Container-aware.** `boundary` (a selector or element) confines both
+ * dragging and the widget's resting position to a region of the app — e.g. a
+ * dashboard's content area, so the widget can never cover navigation or a
+ * footer. The default resting spot is the boundary's bottom-right corner, and
+ * the widget re-clamps itself whenever its own footprint changes (pill ↔ card
+ * swap, a step expanding) or the viewport resizes — a corner-parked pill that
+ * expands into a large card pulls itself fully back into view. Until the user
+ * actually drags it, it stays anchored to the bottom-right corner.
+ *
+ * **Presentation state is internal + optionally persisted.** Collapsed and
+ * drag position persist to `localStorage` under `storageKey`; pass
+ * `storageKey = null` for session-only behavior (e.g. when a consumer-side
+ * store owns presentation policy).
  *
  * **Opinionated but themeable.** It ships a house look out of the box; all
  * colour flows through `--fk-onboarding-guide-*` tokens, so overriding those
@@ -670,9 +705,12 @@ interface Point {
  * <fk-onboarding-guide
  *   [steps]="steps()"
  *   title="Setup guide"
+ *   boundary=".app-content"
+ *   [storageKey]="null"
+ *   [(collapsed)]="collapsed"
  *   (stepAction)="onStart($event)"
  *   (substepToggle)="onToggle($event)"
- *   (goLive)="onGoLive()"
+ *   (footerAction)="onGoLive()"
  *   (dismiss)="onDismiss()"
  * />
  * ```
@@ -685,16 +723,30 @@ declare class OnboardingGuideComponent {
     readonly steps: _angular_core.InputSignal<OnboardingStep[]>;
     /** Widget title. */
     readonly title: _angular_core.InputSignal<string>;
-    /** `localStorage` key for the collapsed + drag-position preferences. */
-    readonly storageKey: _angular_core.InputSignal<string>;
-    /** Initial collapsed state, used only when nothing is persisted yet. */
-    readonly startCollapsed: _angular_core.InputSignal<boolean>;
+    /**
+     * `localStorage` key for the collapsed + drag-position preferences.
+     * `null` disables persistence entirely — presentation state then lives and
+     * dies with the component instance (or with whatever the consumer binds).
+     */
+    readonly storageKey: _angular_core.InputSignal<string | null>;
+    /**
+     * Region the widget is confined to: a CSS selector or an element. Both
+     * dragging and the widget's resting position are clamped inside it. `null`
+     * (the default) confines to the viewport.
+     */
+    readonly boundary: _angular_core.InputSignal<string | HTMLElement | null>;
+    /** Breathing room kept between the widget and the boundary's edges. */
+    readonly boundaryMargin: _angular_core.InputSignal<number>;
+    /** Shows the rename (edit) affordance next to the title. */
+    readonly renamable: _angular_core.InputSignal<boolean>;
+    /** Shows the secondary "mark this step done" action on leaf steps. */
+    readonly showMarkDone: _angular_core.InputSignal<boolean>;
     /** Default CTA label when a step doesn't supply its own `actionLabel`. */
     readonly startLabel: _angular_core.InputSignal<string>;
     /** Secondary "mark this step done" action label. */
     readonly markDoneLabel: _angular_core.InputSignal<string>;
-    /** Footer / final go-live action label. */
-    readonly goLiveLabel: _angular_core.InputSignal<string>;
+    /** Footer action label (e.g. "Go live"). `null` hides the footer action. */
+    readonly footerActionLabel: _angular_core.InputSignal<string | null>;
     /** Footer noun for the "{done} of {total} {stepsWord} {doneWord}" summary. */
     readonly stepsWord: _angular_core.InputSignal<string>;
     /** Footer verb for the summary. */
@@ -715,34 +767,55 @@ declare class OnboardingGuideComponent {
     readonly dismissIcon: _angular_core.InputSignal<string>;
     readonly expandIcon: _angular_core.InputSignal<string>;
     readonly actionIcon: _angular_core.InputSignal<string>;
+    /**
+     * Whether the widget is collapsed to the pill. Two-way bindable so a
+     * consumer-side policy (auto-open on context switches, banner-triggered
+     * opens) can drive the card ↔ pill swap; unbound, the widget manages it.
+     */
+    readonly collapsed: _angular_core.ModelSignal<boolean>;
     /** A step's primary CTA was clicked. Emits the step id. */
     readonly stepAction: _angular_core.OutputEmitterRef<string>;
     /** A step's "mark done" was clicked. Emits the step id. */
     readonly stepMarkDone: _angular_core.OutputEmitterRef<string>;
+    /** A step's secondary text-action was clicked. Emits the step id. */
+    readonly stepSecondaryAction: _angular_core.OutputEmitterRef<string>;
     /** A substep checkbox was toggled. */
     readonly substepToggle: _angular_core.OutputEmitterRef<OnboardingSubstepToggle>;
-    /** The final go-live action was invoked (footer or the go-live step CTA). */
-    readonly goLive: _angular_core.OutputEmitterRef<void>;
+    /** The footer action was invoked. */
+    readonly footerAction: _angular_core.OutputEmitterRef<void>;
     /** The rename (edit) affordance was clicked; the consumer owns renaming. */
     readonly renameClick: _angular_core.OutputEmitterRef<void>;
     /** The dismiss control was clicked; the consumer decides whether to hide it. */
     readonly dismiss: _angular_core.OutputEmitterRef<void>;
-    /** Fires when the collapsed state changes. */
-    readonly collapsedChange: _angular_core.OutputEmitterRef<boolean>;
     readonly className: _angular_core.InputSignal<string>;
     readonly id: _angular_core.InputSignal<string | null>;
-    protected readonly collapsed: _angular_core.WritableSignal<boolean>;
     protected readonly dragPosition: _angular_core.WritableSignal<Point>;
     /** True immediately after a real drag, so the drag-handle's click (e.g. the
      *  pill's expand) is suppressed rather than firing at the drop point. */
     private justDragged;
     /**
-     * The expanded step. A `linkedSignal` over `steps` so that whenever the model
-     * changes (e.g. the consumer swaps in another account/environment's steps) it
-     * resets to the first incomplete step; user toggles override until the next
-     * model change.
+     * True once the user has deliberately placed the widget (a real drag now,
+     * or a persisted position from a previous session). Until then the widget
+     * re-anchors to the boundary's bottom-right corner on every viewport or
+     * footprint change instead of merely clamping its current spot.
+     */
+    private userMoved;
+    private footprintObserver;
+    /** Guards the one-time preference restore in `hydrateOnce`. */
+    private hydrated;
+    /** True between CDK's drag start and drop — `reposition` stands down. */
+    private dragging;
+    /** The boundary element currently under observation (if any). */
+    private observedBoundary;
+    /**
+     * The expanded step, or `null` for none. Fully controlled: the widget
+     * writes it only when the user toggles a row, and never infers a value
+     * of its own — which step should be open, when to advance to the next
+     * one, and whether a context switch should re-focus the guide are all
+     * decisions the consumer owns (it knows what changed; the widget only
+     * sees a new array).
      */
-    protected readonly openStepId: _angular_core.WritableSignal<string | null>;
+    readonly openStepId: _angular_core.ModelSignal<string | null>;
     protected readonly total: _angular_core.Signal<number>;
     protected readonly doneCount: _angular_core.Signal<number>;
     protected readonly percent: _angular_core.Signal<number>;
@@ -756,27 +829,67 @@ declare class OnboardingGuideComponent {
     get hostId(): string | null;
     constructor();
     isComplete(step: OnboardingStep): boolean;
+    isPending(step: OnboardingStep): boolean;
     protected isActive(step: OnboardingStep): boolean;
     protected actionLabelFor(step: OnboardingStep): string;
     protected toggleStep(stepId: string): void;
     protected onAction(step: OnboardingStep): void;
     protected onMarkDone(step: OnboardingStep): void;
+    protected onSecondaryAction(step: OnboardingStep): void;
     protected onSubstep(step: OnboardingStep, substep: OnboardingSubstep): void;
     protected onCollapse(): void;
     protected onExpand(): void;
     protected onRename(): void;
     protected onDismiss(): void;
-    protected onGoLive(): void;
+    protected onFooterAction(): void;
     private setCollapsed;
     private onDragEnded;
+    /**
+     * Keep the resting position valid as the world changes around it. Two
+     * signals feed the same repositioning: the viewport resizing, and the
+     * widget's own footprint changing (pill ↔ card swap, a step expanding) —
+     * the latter is what stops a corner-parked pill from reopening as a card
+     * that's mostly off-screen.
+     */
+    private watchGeometry;
+    /**
+     * The boundary region can resize without a viewport resize — a side
+     * panel opening, chrome banners toggling — so the confining element is
+     * observed alongside the widget's own footprint. Re-synced whenever the
+     * `boundary` input changes.
+     */
+    private syncBoundaryObservation;
+    private resolveBoundaryElement;
+    private readonly onViewportResize;
+    private reposition;
+    /** The confining region: the `boundary` element's rect, or the viewport. */
+    private boundaryRect;
+    /**
+     * Constrain one axis to `[start + margin, end - size - margin]`.
+     *
+     * When the region can't fit the widget plus both margins that range is
+     * inverted, so the margin is dropped and the widget is fitted to the
+     * region's own edges instead — keeping it inside the boundary rather
+     * than letting the inset push it out. A widget genuinely larger than
+     * its region still overflows (the card has a fixed width and something
+     * has to give); it pins to the start edge.
+     */
+    private clampAxis;
     private clamp;
-    private hydrate;
     private defaultBottomRight;
+    /**
+     * One-time restore of the persisted preferences, run from the first
+     * execution of the boundary effect — inputs are set by then, storage
+     * reads are synchronous, and it lands during initial change detection
+     * so the restored state is what the first paint shows. The caller's
+     * `reposition()` clamps the raw restored position right afterwards.
+     */
+    private hydrateOnce;
     private read;
     private persist;
     private storage;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<OnboardingGuideComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<OnboardingGuideComponent, "fk-onboarding-guide", never, { "steps": { "alias": "steps"; "required": true; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; "storageKey": { "alias": "storageKey"; "required": false; "isSignal": true; }; "startCollapsed": { "alias": "startCollapsed"; "required": false; "isSignal": true; }; "startLabel": { "alias": "startLabel"; "required": false; "isSignal": true; }; "markDoneLabel": { "alias": "markDoneLabel"; "required": false; "isSignal": true; }; "goLiveLabel": { "alias": "goLiveLabel"; "required": false; "isSignal": true; }; "stepsWord": { "alias": "stepsWord"; "required": false; "isSignal": true; }; "doneWord": { "alias": "doneWord"; "required": false; "isSignal": true; }; "stepsLeftWord": { "alias": "stepsLeftWord"; "required": false; "isSignal": true; }; "allDoneLabel": { "alias": "allDoneLabel"; "required": false; "isSignal": true; }; "renameLabel": { "alias": "renameLabel"; "required": false; "isSignal": true; }; "collapseLabel": { "alias": "collapseLabel"; "required": false; "isSignal": true; }; "dismissLabel": { "alias": "dismissLabel"; "required": false; "isSignal": true; }; "expandLabel": { "alias": "expandLabel"; "required": false; "isSignal": true; }; "checkIcon": { "alias": "checkIcon"; "required": false; "isSignal": true; }; "caretIcon": { "alias": "caretIcon"; "required": false; "isSignal": true; }; "editIcon": { "alias": "editIcon"; "required": false; "isSignal": true; }; "collapseIcon": { "alias": "collapseIcon"; "required": false; "isSignal": true; }; "dismissIcon": { "alias": "dismissIcon"; "required": false; "isSignal": true; }; "expandIcon": { "alias": "expandIcon"; "required": false; "isSignal": true; }; "actionIcon": { "alias": "actionIcon"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; }, { "stepAction": "stepAction"; "stepMarkDone": "stepMarkDone"; "substepToggle": "substepToggle"; "goLive": "goLive"; "renameClick": "renameClick"; "dismiss": "dismiss"; "collapsedChange": "collapsedChange"; }, never, never, true, [{ directive: typeof i1.CdkDrag; inputs: {}; outputs: {}; }]>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<OnboardingGuideComponent, "fk-onboarding-guide", never, { "steps": { "alias": "steps"; "required": true; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; "storageKey": { "alias": "storageKey"; "required": false; "isSignal": true; }; "boundary": { "alias": "boundary"; "required": false; "isSignal": true; }; "boundaryMargin": { "alias": "boundaryMargin"; "required": false; "isSignal": true; }; "renamable": { "alias": "renamable"; "required": false; "isSignal": true; }; "showMarkDone": { "alias": "showMarkDone"; "required": false; "isSignal": true; }; "startLabel": { "alias": "startLabel"; "required": false; "isSignal": true; }; "markDoneLabel": { "alias": "markDoneLabel"; "required": false; "isSignal": true; }; "footerActionLabel": { "alias": "footerActionLabel"; "required": false; "isSignal": true; }; "stepsWord": { "alias": "stepsWord"; "required": false; "isSignal": true; }; "doneWord": { "alias": "doneWord"; "required": false; "isSignal": true; }; "stepsLeftWord": { "alias": "stepsLeftWord"; "required": false; "isSignal": true; }; "allDoneLabel": { "alias": "allDoneLabel"; "required": false; "isSignal": true; }; "renameLabel": { "alias": "renameLabel"; "required": false; "isSignal": true; }; "collapseLabel": { "alias": "collapseLabel"; "required": false; "isSignal": true; }; "dismissLabel": { "alias": "dismissLabel"; "required": false; "isSignal": true; }; "expandLabel": { "alias": "expandLabel"; "required": false; "isSignal": true; }; "checkIcon": { "alias": "checkIcon"; "required": false; "isSignal": true; }; "caretIcon": { "alias": "caretIcon"; "required": false; "isSignal": true; }; "editIcon": { "alias": "editIcon"; "required": false; "isSignal": true; }; "collapseIcon": { "alias": "collapseIcon"; "required": false; "isSignal": true; }; "dismissIcon": { "alias": "dismissIcon"; "required": false; "isSignal": true; }; "expandIcon": { "alias": "expandIcon"; "required": false; "isSignal": true; }; "actionIcon": { "alias": "actionIcon"; "required": false; "isSignal": true; }; "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; "openStepId": { "alias": "openStepId"; "required": false; "isSignal": true; }; }, { "collapsed": "collapsedChange"; "stepAction": "stepAction"; "stepMarkDone": "stepMarkDone"; "stepSecondaryAction": "stepSecondaryAction"; "substepToggle": "substepToggle"; "footerAction": "footerAction"; "renameClick": "renameClick"; "dismiss": "dismiss"; "openStepId": "openStepIdChange"; }, never, never, true, [{ directive: typeof i1.CdkDrag; inputs: {}; outputs: {}; }]>;
 }
 
 /**