dees-catalog/readme.plan.md

# Plan: dees-stepper — adopt dees-tile + optional overlay window layer

> First line (per CLAUDE.md): Please reread `/home/philkunz/.claude/CLAUDE.md` before continuing.

## Context

Today `dees-stepper` is an inline-only layout component: it hard-codes each step as a custom `.step` `<div>` with its own border / background / box-shadow / border-radius, and its `:host` is `position: absolute; width: 100%; height: 100%;` so it can only live inside a bounded parent container.

The user wants it to behave more like `dees-modal`:

1. Each step should be wrapped in a `<dees-tile>` — the unified "rounded on rounded" frame used by modals and panels — rather than a bespoke `.step` div.
2. A `DeesWindowLayer` should be added behind the stepper, the same way `DeesModal.createAndShow` does, so the stepper can appear as an overlay on top of the page.

User has confirmed (via AskUserQuestion in this session):
- **API**: keep the current inline usage working AND add a static `createAndShow()` like dees-modal.
- **Layout**: keep the current vertical stack + SweetScroll behavior inside the overlay (don't switch to single-tile swap).
- **Nav placement**: split header/footer — goBack + step counter go into the `dees-tile` header slot; the title stays in the content area; the tile footer is used for optional next/submit buttons supplied per-step.

No external consumers of `dees-stepper` were found inside this package (`grep dees-stepper|DeesStepper` only matches its own source, demo, index, changelog, readme). External consumers in dependent projects may exist — the refactor is kept backward-compatible for the inline path.

## Current state (reference)

**File:** `ts_web/elements/00group-layout/dees-stepper/dees-stepper.ts` (lines 20–299)

- `IStep` interface — `title`, `content: TemplateResult`, `validationFunc`, `onReturnToStepFunc`, internal flags (lines 20–27).
- `:host { position: absolute; width: 100%; height: 100%; }` (lines 59–63).
- `.stepperContainer` — absolute, 100% w/h, `overflow: hidden`, holds SweetScroll (lines 64–69).
- `.step` — max-width 500, min-height 300, `border-radius: 12px`, theme background, theme border, `box-shadow: 0 8px 32px rgba(0,0,0,0.4)`, `filter: opacity(0.55) saturate(0.85)`, transform transition (lines 71–97). **These frame styles overlap with what `dees-tile` already provides.**
- `.step.selected` — `filter: opacity(1) saturate(1)` (lines 89–93). **Scroll-through visual cue, keep.**
- `.step.hiddenStep` — `filter: opacity(0)` (line 95). **Keep.**
- `.step.entrance` — faster transition variant for first-render (lines 99–105). **Keep.**
- `.step .stepCounter` — `position: absolute; top: 12px; right: 12px;` pill (lines 111–121). **Move into header slot as a flex child.**
- `.step .goBack` — `position: absolute; top: 12px; left: 12px;` pill + icon + hover (lines 123–161). **Move into header slot as a flex child.**
- `.step .title` — centered, 24px, 64px top padding (lines 163–171). **Keep inside the tile's content slot; remove the 64px top padding since goBack/counter no longer overlap it.**
- `.step .content` — 32px padding (lines 173–175). **Keep.**
- `render()` (lines 179–204) — maps `steps` to `.step` divs.
- `setScrollStatus()` (lines 226–263) — SweetScroll container setup + step validation kick-off. **Keep mostly as-is; selectors still target `.step`/`.selected` so rename cautiously.**
- `firstUpdated` (lines 210–218), `updated` (lines 220–222), `goBack` (lines 265–282), `goNext` (lines 284–298) — untouched in behavior, only DOM selectors may need adjusting.

**Reference files (read, do not modify):**
- `ts_web/elements/00group-overlay/dees-modal/dees-modal.ts` — canonical `createAndShow` + `destroy` + window-layer coordination + z-index registry usage.
- `ts_web/elements/00group-layout/dees-tile/dees-tile.ts` — slot API: `slot="header"`, default slot, `slot="footer"`. Auto-hides footer when slotted nodes are empty. Uses `part="outer"`, `part="header"`, `part="content"`, `part="footer"` for external shadow-part styling.
- `ts_web/elements/00group-overlay/dees-windowlayer/dees-windowlayer.ts` — `createAndShow({ blur })`, `destroy()`, dispatches `clicked` event on backdrop click, uses `zIndexRegistry`.
- `ts_web/elements/00group-layout/dees-stepper/dees-stepper.demo.ts` — existing inline demo.

## Target state

### 1. IStep interface — add one optional field

```ts
export interface IStep {
  title: string;
  content: TemplateResult;
  footerContent?: TemplateResult;   // NEW: optional, rendered in dees-tile footer slot
  validationFunc?: (stepper: DeesStepper, htmlElement: HTMLElement, signal?: AbortSignal) => Promise<any>;
  onReturnToStepFunc?: (stepper: DeesStepper, htmlElement: HTMLElement) => Promise<any>;
  validationFuncCalled?: boolean;
  abortController?: AbortController;
}
```

Form-based steps don't need `footerContent` — their `dees-form-submit` stays inside the form in the content slot (as today). `footerContent` is for non-form steps that need an explicit primary action, or for any step that wants buttons in the conventional tile footer location.

### 2. New overlay-mode state + API on DeesStepper

```ts
@state() accessor overlay: boolean = false;
@state() accessor stepperZIndex: number = 1000;
private windowLayer?: DeesWindowLayer;

public static async createAndShow(optionsArg: {
  steps: IStep[];
}): Promise<DeesStepper> {
  const body = document.body;
  const stepper = new DeesStepper();
  stepper.steps = optionsArg.steps;
  stepper.overlay = true;
  stepper.windowLayer = await DeesWindowLayer.createAndShow({ blur: true });
  stepper.windowLayer.addEventListener('click', async () => {
    await stepper.destroy();
  });
  body.append(stepper.windowLayer);   // (already appended inside createAndShow, but mirror dees-modal's pattern; see note)
  body.append(stepper);
  stepper.stepperZIndex = zIndexRegistry.getNextZIndex();
  zIndexRegistry.register(stepper, stepper.stepperZIndex);
  return stepper;
}

public async destroy() {
  const domtools = await this.domtoolsPromise;
  const container = this.shadowRoot!.querySelector('.stepperContainer');
  container?.classList.add('predestroy');
  await domtools.convenience.smartdelay.delayFor(200);
  if (this.parentElement) this.parentElement.removeChild(this);
  if (this.windowLayer) await this.windowLayer.destroy();
  zIndexRegistry.unregister(this);
}
```

**Note on `body.append(windowLayer)`:** `DeesWindowLayer.createAndShow` already appends the window layer to `document.body` (line 27 of `dees-windowlayer.ts`). `dees-modal.ts:71` still calls `body.append(modal.windowLayer)` — that's either a no-op (already-attached nodes) or a re-parent to keep ordering. I will match dees-modal's exact sequence verbatim to avoid introducing subtle differences; if it's a bug in dees-modal it is out of scope for this task.

**Minimum new scope for createAndShow:** just `steps` for now. No `onComplete`, no `showCloseButton`, no width options. Future-proofing via additional options is an explicit follow-up — this plan keeps scope razor-sharp (per CLAUDE.md). The caller can already wire completion via the last step's `validationFunc` calling back into their own code.

### 3. Render template — wrap each step in `<dees-tile>`

```ts
public render() {
  return html`
    <div class="stepperContainer ${this.overlay ? 'overlay' : ''}" style="${this.overlay ? `z-index: ${this.stepperZIndex}` : ''}">
      ${this.steps.map((stepArg, i) => {
        const isSelected = stepArg === this.selectedStep;
        const isHidden = this.getIndexOfStep(stepArg) > this.getIndexOfStep(this.selectedStep);
        const isFirst = i === 0;
        const stepNumber = i + 1;
        return html`
          <dees-tile
            class="step ${isSelected ? 'selected' : ''} ${isHidden ? 'hiddenStep' : ''} ${isFirst ? 'entrance' : ''}"
          >
            <div slot="header" class="step-header">
              ${!isFirst
                ? html`<div class="goBack" @click=${this.goBack}>
                    <span>&larr;</span> go to previous step
                  </div>`
                : html`<div class="goBack-spacer"></div>`}
              <div class="stepCounter">Step ${stepNumber} of ${this.steps.length}</div>
            </div>
            <div class="step-body">
              <div class="title">${stepArg.title}</div>
              <div class="content">${stepArg.content}</div>
            </div>
            ${stepArg.footerContent
              ? html`<div slot="footer" class="step-footer">${stepArg.footerContent}</div>`
              : ''}
          </dees-tile>
        `;
      })}
    </div>
  `;
}
```

**Key detail:** on the first step, render a `.goBack-spacer` (empty div) in the header instead of nothing — so the `stepCounter` stays right-aligned via `justify-content: space-between`. Without a spacer, flex would left-align the counter on step 1.

### 4. CSS changes

**Remove from `.step`:**
- `border-radius: 12px;`
- `background: ${cssManager.bdTheme(...)};`
- `border: 1px solid ${cssManager.bdTheme(...)};`
- `color: ${cssManager.bdTheme(...)};`
- `box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);`
- `overflow: hidden;`

**Why:** `dees-tile` owns all of these now. The `.step` selector still exists (since `dees-tile` has `class="step ..."` on it), but it only controls the outer animation wrapper: `max-width`, `min-height`, `margin`, `filter`, `transform`, `transition`, `user-select`, `pointer-events`.

**Keep on `.step`:**
- `position: relative;`
- `pointer-events: none;` + `.step.selected { pointer-events: all; }`
- `max-width: 500px;` / `min-height: 300px;`
- `margin: auto; margin-bottom: 20px;`
- `filter: opacity(0.55) saturate(0.85);` + `.selected { filter: opacity(1) saturate(1); }`
- `.hiddenStep { filter: opacity(0); }`
- All the cubic-bezier transitions (transform/filter/box-shadow — but box-shadow is now a no-op since dees-tile provides the shadow; leave the transition spec in so we don't have to re-check browser parsing; or just drop `box-shadow` from the transition list — I'll drop it for cleanliness).
- `.step.entrance` + `.step.entrance.hiddenStep { transform: translateY(16px); }`
- `.step:last-child { margin-bottom: 100vh; }`

**Add for dees-tile shadow enhancement:** use `::part(outer)` to apply the modal-style elevated shadow only when in overlay mode (optional polish — inline mode stays flat):
```css
.stepperContainer.overlay dees-tile.step::part(outer) {
  box-shadow:
    0 0 0 1px ${cssManager.bdTheme('hsl(0 0% 0% / 0.03)', 'hsl(0 0% 100% / 0.03)')},
    0 8px 40px ${cssManager.bdTheme('hsl(0 0% 0% / 0.12)', 'hsl(0 0% 0% / 0.5)')},
    0 2px 8px ${cssManager.bdTheme('hsl(0 0% 0% / 0.06)', 'hsl(0 0% 0% / 0.25)')};
}
```
This exactly mirrors the dees-modal::part(outer) shadow stack (dees-modal.ts:157–161) so the overlay stepper reads as "same visual language as modal."

**Restyle `.step-header` (NEW — the `<div slot="header">`):**
```css
.step-header {
  height: 48px;
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 8px 12px;
  gap: 12px;
}
```

**Restyle `.step .stepCounter` → `.step-header .stepCounter` (move from absolute to flex child):**
- Drop `position: absolute; top: 12px; right: 12px;`
- Keep everything else (padding, font-size, border-radius, background, border).

**Restyle `.step .goBack` → `.step-header .goBack` (move from absolute to flex child):**
- Drop `position: absolute; top: 12px; left: 12px;`
- Keep everything else (padding, font-size, border-radius, background, border, hover/active states).

**Add `.goBack-spacer`:**
```css
.goBack-spacer { width: 1px; }   /* placeholder so flex space-between works on step 1 */
```

**Restyle `.step .title`:**
- Drop `padding-top: 64px;` — no longer overlaps anything since header is in its own slot.
- Keep `text-align: center; font-family: 'Geist Sans', sans-serif; font-size: 24px; font-weight: 600; letter-spacing: -0.01em; color: inherit;`
- Add `padding-top: 32px;` (or similar) so there's consistent breathing room above the title inside the tile content.

**Add `.step-footer` (new container for `stepArg.footerContent`):**
```css
.step-footer {
  display: flex;
  align-items: center;
  justify-content: flex-end;
  gap: 8px;
  padding: 12px 16px;
}
```

**Add overlay-mode positioning:**
```css
.stepperContainer {
  position: absolute;
  width: 100%;
  height: 100%;
  overflow: hidden;
}
.stepperContainer.overlay {
  position: fixed;
  top: 0;
  left: 0;
  width: 100vw;
  height: 100vh;
}
.stepperContainer.predestroy {
  opacity: 0;
  transition: opacity 0.2s ease-in;
}
```

**Adjust `:host` for dual-mode:**
```css
:host {
  position: absolute;      /* inline default */
  width: 100%;
  height: 100%;
  font-family: ${cssGeistFontFamily};
  color: var(--dees-color-text-primary);
}
:host([overlay]) {
  position: fixed;         /* overlay mode */
  top: 0;
  left: 0;
  width: 100vw;
  height: 100vh;
}
```

The `overlay` @state needs to reflect to an attribute for the `:host([overlay])` selector to work. Since `@state` doesn't reflect attributes, use `@property({ type: Boolean, reflect: true })` instead — change the decorator accordingly.

### 5. Imports to add in `dees-stepper.ts`

```ts
import { DeesWindowLayer } from '../../00group-overlay/dees-windowlayer/dees-windowlayer.js';
import { zIndexRegistry } from '../../00zindex.js';
import { cssGeistFontFamily } from '../../00fonts.js';
import '../../00group-layout/dees-tile/dees-tile.js';
```

`dees-tile` side-effect import registers the custom element. `cssGeistFontFamily` is only needed if I add it to `:host` (which I want, to match modal).

### 6. SweetScroll selector stability

`setScrollStatus()` selectors target `.step` and `.selected` (lines 228–229). These continue to match since I'm keeping those class names on the `<dees-tile>` elements. **No selector changes needed.**

One subtlety: `offsetTop` / `offsetHeight` on `<dees-tile>` should still work — the tile's `:host` is `display: flex; flex-direction: column;` which participates in layout. I'll verify visually in the demo.

### 7. Demo update

**File:** `ts_web/elements/00group-layout/dees-stepper/dees-stepper.demo.ts`

Current demo renders one inline stepper directly. I'll keep that and add an **overlay launcher button** above it:

```ts
export const stepperDemo = () => html`
  <div style="padding: 16px;">
    <dees-button @click=${async () => {
      const stepper = await DeesStepper.createAndShow({
        steps: [/* same steps as inline demo */],
      });
    }}>Open stepper as overlay</dees-button>
  </div>
  <dees-stepper .steps=${[/* ... existing inline demo steps ... */]}></dees-stepper>
`;
```

Extract the step definitions into a `const demoSteps = [...]` above the template so both the inline and overlay paths reuse them (DRY). Import `DeesStepper` at the top of the demo file.

## Files to modify

1. **`ts_web/elements/00group-layout/dees-stepper/dees-stepper.ts`** — main refactor (IStep, imports, render, styles, createAndShow, destroy, overlay state).
2. **`ts_web/elements/00group-layout/dees-stepper/dees-stepper.demo.ts`** — add overlay launcher button, extract shared `demoSteps` const, import `DeesStepper`.

**Files explicitly NOT modified:**
- `dees-tile.ts` — used as-is via its slot API.
- `dees-windowlayer.ts` — used as-is via `createAndShow` / `destroy` / `click` event.
- `dees-modal.ts` — reference only.
- `00zindex.ts` — reference only.

## Verification

1. **Build**: `pnpm run build` — must pass with no TS errors. Pure refactor, no new dependencies, no lib-check regressions expected.

2. **Inline demo (backward compat)**:
   - Start the demo server (port 8080 is already running) and navigate to the dees-stepper demo page.
   - Confirm the stepper renders inline exactly like before: first step centered, subsequent steps dimmed below, scroll-through animation on goNext / goBack.
   - Fill out the first form, submit → stepper scrolls to step 2. Click goBack → scrolls back.
   - Confirm the `dees-tile` frame is visible on each step (rounded, bordered, themed) and that the title + form are inside the tile's content area.
   - Confirm goBack button + step counter sit in the tile's header row, space-between, left/right respectively.

3. **Overlay demo (new path)**:
   - Click the "Open stepper as overlay" button.
   - Confirm a `dees-windowlayer` with blur appears behind the stepper.
   - Confirm the stepper fills the viewport (fixed, 100vw×100vh).
   - Confirm z-index stacking: stepper above window layer above page content.
   - Click the window layer (outside the tile) → stepper animates out, then destroys along with the window layer.
   - Re-open and step through forward & back — behavior identical to inline mode.

4. **Playwright visual check** (per CLAUDE.md: screenshots MUST go in `.playwright-mcp/`):
   - `.playwright-mcp/dees-stepper-inline.png` — inline mode, step 1 with form.
   - `.playwright-mcp/dees-stepper-overlay.png` — overlay mode, same step.
   - `.playwright-mcp/dees-stepper-overlay-step3.png` — overlay mode mid-flow, to verify scroll-stack visual.
   - Both light and dark themes if the demo has a theme toggle.

5. **Grep sanity**:
   - Confirm `dees-stepper` has no new unexpected match locations: `grep dees-stepper ts_web/` should still only match stepper's own files.
   - Confirm no `.step` class collisions elsewhere (unlikely — `.step` is a plain class name; all usages should be shadow-scoped to `dees-stepper`).

## Open assumptions & deferred scope

These are explicit defaults in this plan. If the user wants different behavior for any of them, they should flag it on review — each is a simple follow-up but not in scope right now (CLAUDE.md: stay focused, no "while we're at it"):

- **No close button on overlay stepper.** Clicking the window layer backdrop is the only way to dismiss. Matches how dees-modal with `showCloseButton: false` behaves. Can add a close button in a follow-up.
- **No `onComplete` callback in `createAndShow`.** The last step doesn't auto-destroy the overlay — the app controls it via the step's `validationFunc`. Can add a callback option in a follow-up.
- **No width/size options in `createAndShow`.** The step tile continues to use the stepper's existing `max-width: 500px`. Can parameterize in a follow-up.
- **Box-shadow in the `.step` transition list** is dropped from the transition for cleanliness — the box-shadow is now on `dees-tile::part(outer)` and doesn't change between selected/hiddenStep, so transitioning it was already a no-op.
- **`pnpm start` / dev server path**: I'll reuse the existing server on port 8080 that was already listening when this session began; if that server doesn't serve the stepper demo, I'll start wcctools manually.

## Risk

- **Low-medium.** The change is localized to one component and its demo. No API removal, only an additive `createAndShow` + an optional `footerContent` field. External consumers of the inline API continue to work if they only set `steps` + `selectedStep`.
- **Biggest risk:** SweetScroll's `offsetTop` / `offsetHeight` measurements on `<dees-tile>` may compute differently than on the former `<div class="step">` because `dees-tile` has an internal `display: flex; flex-direction: column;` host and a `.tile-outer { flex: 1; min-height: 0; }` inner frame. If the scroll math drifts, the mitigation is to keep the `.step` wrapper as an outer `<div>` that **contains** a `<dees-tile>`, rather than putting the class directly on `<dees-tile>`. That preserves the exact box model SweetScroll was measuring. I'll try the direct-class approach first (simpler) and fall back to the wrapper approach if the scroll target looks off in the demo.
- **Second risk:** The `:host([overlay])` attribute selector requires `overlay` to be a reflected `@property`, not `@state`. I've already accounted for this in the plan (decorator change).