@design.estate/dees-catalog 9.5.0 → 9.6.0

package/dist_ts_web/elements/00group-layout/dees-stepper/styles.d.ts

@@ -0,0 +1 @@
+export declare const stepperStyles: import("@design.estate/dees-element").CSSResult;

package/dist_ts_web/elements/00group-layout/dees-stepper/styles.js

@@ -0,0 +1,41 @@
+import { css } from '@design.estate/dees-element';
+export const stepperStyles = css `
+  :host { display: block; position: relative; width: 100%; height: 100%; min-height: 440px; min-width: 0; font-family: var(--dees-font-family); color: var(--dees-color-text-primary); }
+  :host([overlay]) { position: static; width: 0; height: 0; min-height: 0; }
+  .stepperContainer { position: absolute; inset: 0; width: 100%; height: 100%; overflow: hidden; overflow-anchor: none; box-sizing: border-box; container: stepper-surface / inline-size; }
+  .stepperContainer.overlay { position: fixed; width: 100%; height: 100dvh; max-width: none; max-height: none; border: 0; padding: 0; margin: 0; color: inherit; background: transparent; }
+  .stepperContainer::backdrop { background: var(--dees-color-scrim); }
+  dees-tile.step { position: relative; width: min(var(--dees-stepper-width, 520px), calc(100% - 40px)); max-height: calc(100% - 48px); min-height: min(280px, calc(100% - 48px)); margin: 0 auto 20px; pointer-events: none; opacity: .25; transition: opacity 240ms var(--dees-ease-standard); }
+  dees-tile.step::part(outer) { border-color: var(--dees-color-border-subtle); }
+  dees-tile.step.selected { pointer-events: auto; opacity: 1; }
+  dees-tile.step.selected::part(outer) { border-color: var(--dees-color-border-default); box-shadow: var(--dees-shadow-md); }
+  dees-tile.step.hiddenStep { opacity: 0; }
+  dees-tile.step:last-child { margin-bottom: 100dvh; }
+  .step-header { display: flex; align-items: center; gap: 16px; padding: 16px 24px; min-height: 48px; box-sizing: border-box; }
+  .step-rail { display: flex; flex: 1; gap: 5px; list-style: none; margin: 0; padding: 0; min-width: 0; }
+  .step-marker { flex: 1; height: 4px; border-radius: 2px; background: var(--dees-color-fill-secondary); }
+  .step-marker.complete { background: var(--dees-color-text-secondary); }
+  .step-marker.current { background: var(--dees-color-accent-primary); }
+  .step-counter { flex: none; font-size: 12px; font-weight: 500; font-variant-numeric: tabular-nums; color: var(--dees-color-text-secondary); }
+  .step-body { padding: 24px; }
+  .heading-row { display: flex; align-items: flex-start; gap: 16px; }
+  .title { margin: 0; font-size: 20px; line-height: 1.3; font-weight: 600; letter-spacing: -.025em; overflow-wrap: anywhere; outline: none; }
+  .description { margin: 8px 0 0; font-size: 13px; line-height: 1.55; color: var(--dees-color-text-secondary); }
+  .content { margin-top: 24px; font-size: 13px; line-height: 1.55; overflow-wrap: anywhere; }
+  .content:empty { display: none; }
+  .progressStep { margin: 20px -8px 0; }
+  .step-error { display: flex; align-items: flex-start; gap: 8px; padding: 12px; margin-top: 16px; border-radius: var(--dees-radius-md); background: var(--dees-color-badge-error-bg); color: var(--dees-color-text-error); font-size: 12px; line-height: 1.5; overflow-wrap: anywhere; }
+  .step-error dees-icon { flex: none; margin-top: 1px; }
+  .step-footer { padding: 12px 24px; }
+  .step-hint { flex: 0 0 120px; padding-top: 4px; margin-left: auto; color: var(--dees-color-text-secondary); font-size: 11px; line-height: 1.4; text-align: right; transition: opacity 160ms var(--dees-ease-standard), visibility 160ms; }
+  .step-hint[aria-hidden='true'] { opacity: 0; visibility: hidden; pointer-events: none; }
+  .bottomButtons { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+  .back-action { margin-right: auto; }
+  .footer-spacer { margin-right: auto; }
+  .empty { display: grid; place-content: center; height: 100%; text-align: center; color: var(--dees-color-text-secondary); font-size: 13px; }
+  .predestroy .step.selected { animation: stepper-exit 160ms var(--dees-ease-standard) forwards; }
+  @keyframes stepper-exit { to { opacity: 0; transform: translateY(10px); } }
+  @media (prefers-reduced-motion: reduce) { dees-tile.step, .step-hint { transition: none; } .predestroy .step.selected { animation: none; } }
+  @container stepper-surface (max-width: 540px) { dees-tile.step { width: calc(100% - 24px); max-height: calc(100% - 24px); } .step-header { padding: 12px 20px; } .step-body { padding: 20px; } .step-footer { padding: 12px 20px; } .step-hint { flex-basis: 84px; } }
+`;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3R5bGVzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vdHNfd2ViL2VsZW1lbnRzLzAwZ3JvdXAtbGF5b3V0L2RlZXMtc3RlcHBlci9zdHlsZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLEdBQUcsRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBRWxELE1BQU0sQ0FBQyxNQUFNLGFBQWEsR0FBRyxHQUFHLENBQUE7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0NBc0MvQixDQUFDIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design.estate/dees-catalog",
-  "version": "9.5.0",
+  "version": "9.6.0",
   "private": false,
   "description": "A comprehensive library that provides dynamic web components for building sophisticated and modern web applications using JavaScript and TypeScript.",
   "main": "dist_ts_web/index.js",

package/readme.md

@@ -2173,13 +2173,43 @@ const layer = await DeesWindowLayer.createAndShow({
 ### Navigation Components
 
 #### `DeesStepper`
-Multi-step navigation component for guided user flows, including optional auto-advancing progress steps that can render `dees-progressbar` status output between form steps.
+Guided form and background-work flows with a compact progress strip, shared action
+buttons, and a vertical transition between steps. Use it inline or open the same
+steps as a modal with `DeesStepper.createAndShow({ steps, cancelable: true })`.
+
+- `IStep` accepts `title`, optional `description`, `content`, `menuOptions`,
+  `allowBack`, `validationFunc`, `onReturnToStepFunc`, and `progressStep`.
+- The last menu action is primary. A nested `dees-form` gates that action on its
+  required fields and dispatches collected `formData` before the action runs.
+  The required-fields hint fades beside the heading without changing its layout.
+- Async actions prevent duplicate activation and display failures in the current
+  step. Progress failures expose **Try again**; `retryStep()` reruns validation.
+  Keep external work abortable using the callback's `AbortSignal`.
+- Progress steps use `dees-progressbar` and advance after successful validation
+  unless `progressStep.autoAdvance` is `false`. Use `updateProgressStep()`,
+  `appendProgressStepLine()`, and `resetProgressStep()` to report work.
+- `goNext()` and `goBack()` preserve mounted form contents. Back honors
+  `allowBack: false`. Inactive steps are inert. Transitions respect reduced motion
+  and adjust to changing content and container sizes without snapping.
+- Overlay mode uses native dialog focus containment and restoration. Cancel,
+  Escape, and backdrop clicks share a confirmation flow; `cancelable: false`
+  disables those dismissal paths. `destroy()` closes the flow; `stepper-close`
+  fires when it disconnects. Disconnecting also aborts work and releases observers.
+- Inline steppers fill a bounded area (440px minimum height by default). Set a
+  height appropriate to the composition; `--dees-stepper-width` controls the card's
+  maximum width (520px by default).
+
+The catalog demo combines setup fields, preferences, a review, background work,
+and completion. **Retry example** fails the first background attempt and preserves
+the choices for recovery. It also shows optional and required-completion overlays.
 
 ```typescript
 <dees-stepper
+  style="height: 540px"
   .steps=${[
     {
       title: 'Account Setup',
+      description: 'Choose the owner of your workspace.',
       content: html`<dees-form>...</dees-form>`,
       menuOptions: [{ name: 'Continue', action: async (stepper) => stepper?.goNext() }]
     },

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-catalog',
-  version: '9.5.0',
+  version: '9.6.0',
   description: 'A comprehensive library that provides dynamic web components for building sophisticated and modern web applications using JavaScript and TypeScript.'
 }

package/ts_web/elements/00group-layout/dees-stepper/dees-stepper.demo.ts

@@ -1,212 +1,154 @@
-import { html } from '@design.estate/dees-element';
+import { DeesElement, customElement, property, state, html, css, cssManager } from '@design.estate/dees-element';
 import { DeesStepper, type IStep } from './dees-stepper.js';
+import { themeDefaultStyles } from '../../00theme.js';
+import { demoPage } from '../../../demos/templates.js';
+import '../../00group-form/dees-form/dees-form.js';
+import '../../00group-input/dees-input-text/dees-input-text.js';
+import '../../00group-input/dees-input-multitoggle/dees-input-multitoggle.js';
+import '../../00group-input/dees-input-toggle/dees-input-toggle.js';
 
-const waitForProgressTick = async (timeoutArg: number, signal?: AbortSignal): Promise<boolean> => {
-  return new Promise((resolve) => {
-    let completed = false;
+const waitForProgressTick = (duration: number, signal?: AbortSignal): Promise<boolean> => new Promise(resolve => {
+  if (signal?.aborted) { resolve(false); return; }
+  const abort = () => { clearTimeout(timer); resolve(false); };
+  const timer = setTimeout(() => { signal?.removeEventListener('abort', abort); resolve(true); }, duration);
+  signal?.addEventListener('abort', abort, { once: true });
+});
 
-    const finish = (result: boolean) => {
-      if (completed) {
-        return;
-      }
+const contentStyles = html`<style>
+  .setup-summary { margin: 0; display: grid; grid-template-columns: auto minmax(0, 1fr); gap: 12px 24px; font-size: 13px; }
+  .setup-summary dt { color: var(--dees-color-text-secondary); }
+  .setup-summary dd { margin: 0; text-align: right; overflow-wrap: anywhere; font-weight: 500; }
+  .setup-note { color: var(--dees-color-text-secondary); font-size: 12px; line-height: 1.6; margin: 20px 0 0; }
+  .setup-success { display: flex; align-items: center; gap: 10px; margin: 0 0 20px; color: var(--dees-color-text-success); }
+</style>`;
 
-      completed = true;
-      if (signal) {
-        signal.removeEventListener('abort', handleAbort);
-      }
-      resolve(result);
-    };
-
-    const handleAbort = () => {
-      window.clearTimeout(timeoutId);
-      finish(false);
-    };
-
-    const timeoutId = window.setTimeout(() => {
-      finish(true);
-    }, timeoutArg);
-
-    if (signal) {
-      signal.addEventListener('abort', handleAbort, { once: true });
-    }
-  });
-};
-
-const createContinueMenuOptions = (labelArg = 'Continue') => [
-  {
-    name: labelArg,
-    action: async (stepper?: DeesStepper) => stepper?.goNext(),
-  },
-];
-
-const createDemoSteps = (): IStep[] => [
-  {
-    title: 'Account Setup',
-    content: html`
-      <dees-form>
-        <dees-input-text key="email" label="Work Email" required></dees-input-text>
-        <dees-input-text key="password" label="Create Password" type="password" required></dees-input-text>
-      </dees-form>
-    `,
-    menuOptions: createContinueMenuOptions(),
-  },
-  {
-    title: 'Profile Details',
-    content: html`
-      <dees-form>
-        <dees-input-text key="firstName" label="First Name" required></dees-input-text>
-        <dees-input-text key="lastName" label="Last Name" required></dees-input-text>
-      </dees-form>
-    `,
-    menuOptions: createContinueMenuOptions(),
-  },
-  {
-    title: 'Contact Information',
-    content: html`
-      <dees-form>
-        <dees-input-phone key="phone" label="Mobile Number" required></dees-input-phone>
-        <dees-input-text key="company" label="Company"></dees-input-text>
-      </dees-form>
-    `,
-    menuOptions: createContinueMenuOptions(),
-  },
-  {
-    title: 'Provision Workspace',
-    content: html`
-      <dees-panel>
-        <p>
-          We are creating your starter workspace, applying your onboarding choices,
-          and preparing a live preview. This step moves forward automatically when
-          the environment is ready.
-        </p>
-      </dees-panel>
-    `,
-    progressStep: {
-      label: 'Workspace setup',
-      percentage: 8,
-      indeterminate: true,
-      statusRows: 4,
-      statusText: 'Allocating a clean workspace...',
-      terminalLines: ['Allocating a clean workspace'],
+const createDemoSteps = (failFirst: boolean, finish: (name: string) => void): IStep[] => {
+  const draft = { name: '', email: '', purpose: 'Product', updates: true };
+  let attempts = 0;
+  const summary = () => html`${contentStyles}<dl class="setup-summary">
+    <dt>Workspace</dt><dd>${draft.name}</dd><dt>Owner</dt><dd>${draft.email}</dd>
+    <dt>Built for</dt><dd>${draft.purpose}</dd><dt>Weekly digest</dt><dd>${draft.updates ? 'On' : 'Off'}</dd>
+  </dl>`;
+  const collect = (event: CustomEvent<{ data: Partial<typeof draft> }>) => {
+    Object.assign(draft, event.detail.data);
+    steps[2].content = summary();
+    steps[4].content = html`${contentStyles}<p class="setup-success"><dees-icon icon="lucide:CircleCheck" iconSize="20"></dees-icon>Everything is in place.</p>${summary()}`;
+  };
+  const next = [{ name: 'Continue', action: async (stepper?: DeesStepper) => stepper?.goNext() }];
+  const steps: IStep[] = [
+    {
+      title: 'Create a workspace.',
+      description: 'Give your workspace a name and choose who will own it.',
+      content: html`<dees-form @formData=${collect}>
+        <dees-input-text key="name" label="Workspace name" placeholder="Studio Notes" required></dees-input-text>
+        <dees-input-text key="email" label="Work email" placeholder="alex@example.com" type="email" required></dees-input-text>
+      </dees-form>`,
+      menuOptions: next,
     },
-    validationFunc: async (stepper, _htmlElement, signal) => {
-      const progressFrames = [
-        { line: 'Allocating a clean workspace', percentage: 8, delay: 500 },
-        { line: 'Syncing account preferences', percentage: 24, delay: 650 },
-        { line: 'Installing selected integrations', percentage: 47, delay: 700 },
-        { line: 'Generating starter project files', percentage: 71, delay: 650 },
-        { line: 'Booting the live preview environment', percentage: 92, delay: 700 },
-      ];
-
-      stepper.resetProgressStep();
-
-      for (const [index, progressFrame] of progressFrames.entries()) {
-        if (signal?.aborted) {
-          return;
+    {
+      title: 'Make it yours.',
+      description: 'Start with a focus. You can change these choices later.',
+      content: html`<dees-form @formData=${collect}>
+        <dees-input-multitoggle key="purpose" label="What are you working on?" .options=${['Product', 'Operations', 'Research']}></dees-input-multitoggle>
+        <dees-input-toggle key="updates" label="Weekly workspace digest" .value=${true}></dees-input-toggle>
+      </dees-form>`,
+      menuOptions: next,
+    },
+    {
+      title: 'Ready to create?',
+      description: 'Take a moment to check your choices.',
+      content: summary(),
+      menuOptions: [{ name: 'Create workspace', action: async (stepper) => stepper?.goNext() }],
+    },
+    {
+      title: 'Bringing it together.',
+      description: 'Your workspace is taking shape. This usually takes a few seconds.',
+      content: html`${contentStyles}<p class="setup-note">You can go back to adjust your choices, or cancel while setup is running.</p>`,
+      progressStep: { label: 'Creating workspace', percentage: 0, statusRows: 3 },
+      validationFunc: async (stepper, _element, signal) => {
+        attempts++;
+        const messages = ['Creating your space', 'Applying preferences', 'Preparing starter files', 'Workspace ready'];
+        for (const [index, message] of messages.entries()) {
+          if (!await waitForProgressTick(650, signal)) return;
+          if (failFirst && attempts === 1 && index === 2) throw new Error('Starter files could not be copied. Your choices are saved. Try again.');
+          stepper.appendProgressStepLine(message);
+          stepper.updateProgressStep({ percentage: (index + 1) * 25, statusText: message, indeterminate: false });
         }
+        await waitForProgressTick(450, signal);
+      },
+    },
+    {
+      title: 'Your workspace is ready.',
+      description: 'A fresh start, with all the details you chose.',
+      allowBack: false,
+      content: summary(),
+      menuOptions: [{ name: 'Done', action: async stepper => { finish(draft.name); await stepper?.destroy(); } }],
+    },
+  ];
+  return steps;
+};
 
-        if (index === 0) {
-          stepper.updateProgressStep({
-            percentage: progressFrame.percentage,
-            indeterminate: true,
-            statusText: `${progressFrame.line}...`,
-            terminalLines: [progressFrame.line],
-          });
-        } else {
-          stepper.appendProgressStepLine(progressFrame.line);
-          stepper.updateProgressStep({
-            percentage: progressFrame.percentage,
-            indeterminate: true,
-            statusText: `${progressFrame.line}...`,
-          });
-        }
+@customElement('dees-demo-stepper')
+class DeesDemoStepper extends DeesElement {
+  @property() accessor scenario = 'Standard setup';
+  @state() private accessor closed = false;
+  @state() private accessor result = '';
+  private steps = createDemoSteps(false, name => { this.result = `${name} is ready.`; });
+  private overlayStepper?: DeesStepper;
 
-        const completed = await waitForProgressTick(progressFrame.delay, signal);
-        if (!completed) {
-          return;
-        }
-      }
+  public static styles = [themeDefaultStyles, cssManager.defaultStyles, css`
+    :host { display: block; min-width: 0; }
+    .toolbar { display: flex; align-items: center; justify-content: space-between; gap: 12px; flex-wrap: wrap; margin-bottom: 20px; }
+    .actions { display: flex; gap: 8px; flex-wrap: wrap; }
+    .stage { position: relative; height: 540px; border: 1px solid var(--dees-color-border-subtle); border-radius: 18px; background: var(--dees-color-bg-secondary); overflow: hidden; }
+    .finished { display: grid; place-content: center; justify-items: center; gap: 16px; height: 100%; padding: 24px; box-sizing: border-box; text-align: center; }
+    .finished h2 { margin: 0; font-size: 20px; letter-spacing: -.025em; font-weight: 600; }
+    .finished p, .caption { font-size: 12px; line-height: 1.6; color: var(--dees-color-text-secondary); }
+    .caption { margin: 16px 0 0; }
+    summary.caption { cursor: pointer; font-size: 13px; font-weight: 500; }
+    .finished dees-icon { color: var(--dees-color-text-success); }
+    @media (max-width: 540px) { .stage { height: 560px; } }
+  `];
 
-      stepper.appendProgressStepLine('Workspace ready');
-      stepper.updateProgressStep({
-        percentage: 100,
-        indeterminate: false,
-        statusText: 'Workspace ready.',
-      });
+  private reset() {
+    this.result = '';
+    this.closed = false;
+    this.steps = createDemoSteps(this.scenario === 'Retry example', name => { this.result = `${name} is ready.`; });
+    this.requestUpdate();
+  }
 
-      await waitForProgressTick(350, signal);
-    },
-  },
-  {
-    title: 'Team Size',
-    content: html`
-      <dees-form>
-        <dees-input-dropdown
-          key="teamSize"
-          label="How big is your team?"
-          .options=${[
-            { label: '1-5', value: '1-5' },
-            { label: '6-20', value: '6-20' },
-            { label: '21-50', value: '21-50' },
-            { label: '51+', value: '51+' },
-          ]}
-          required
-        ></dees-input-dropdown>
-      </dees-form>
-    `,
-    menuOptions: createContinueMenuOptions(),
-  },
-  {
-    title: 'Goals',
-    content: html`
-      <dees-form>
-        <dees-input-multitoggle
-          key="goal"
-          label="Main objective"
-          .options=${[
-            { label: 'Onboarding', key: 'onboarding' },
-            { label: 'Analytics', key: 'analytics' },
-            { label: 'Automation', key: 'automation' },
-          ]}
-        ></dees-input-multitoggle>
-      </dees-form>
-    `,
-    menuOptions: createContinueMenuOptions(),
-  },
-  {
-    title: 'Review & Launch',
-    content: html`
-      <dees-panel>
-        <p>
-          Your workspace is ready. Review the collected details and launch when
-          you are ready to start.
-        </p>
-      </dees-panel>
-    `,
-    menuOptions: [
-      {
-        name: 'Launch',
-        action: async (stepper?: DeesStepper) => {
-          if (stepper?.overlay) {
-            await stepper.destroy();
-          }
-        },
-      },
-    ],
-  },
-];
+  private async openOverlay(cancelable = true) {
+    if (this.overlayStepper?.isConnected) return;
+    this.overlayStepper = await DeesStepper.createAndShow({
+      cancelable,
+      steps: createDemoSteps(this.scenario === 'Retry example', name => { this.result = `${name} is ready.`; }),
+    });
+  }
 
-export const stepperDemo = () => html`
-  <div style="position: absolute; inset: 0;">
-    <div
-      style="position: absolute; top: 16px; left: 50%; transform: translateX(-50%); z-index: 10;"
-    >
-      <dees-button
-        @click=${async () => {
-          await DeesStepper.createAndShow({ steps: createDemoSteps() });
-        }}
-      >Open stepper as overlay</dees-button>
+  public render() {
+    return html`<div class="toolbar">
+      <dees-input-multitoggle size="sm" label="Demo scenario" labelPosition="none"
+        .options=${['Standard setup', 'Retry example']} .selectedOption=${this.scenario}
+        @change=${(event: CustomEvent<{ value: string }>) => { this.scenario = event.detail.value; this.reset(); }}></dees-input-multitoggle>
+      <div class="actions"><dees-button type="secondary" text="Open overlay" @clicked=${() => this.openOverlay()}></dees-button>
+        <dees-button type="ghost" text="Reset" @clicked=${this.reset}></dees-button></div>
     </div>
-    <dees-stepper .steps=${createDemoSteps()}></dees-stepper>
-  </div>
-`;
+    <div class="stage">${this.closed ? html`<div class="finished">
+      <dees-icon icon=${this.result ? 'lucide:CircleCheck' : 'lucide:Layers'} iconSize="32"></dees-icon>
+      <h2>${this.result || 'Setup cancelled.'}</h2><p>This example uses local sample data.</p>
+      <dees-button type="secondary" text="Start again" @clicked=${this.reset}></dees-button>
+    </div>` : html`<dees-stepper .steps=${this.steps} @stepper-close=${() => { this.closed = true; }}></dees-stepper>`}</div>
+    <p class="caption">${this.scenario === 'Retry example' ? 'The first setup attempt pauses with an error. Try again to continue with your saved choices.' : 'Move forward, go back, and review your choices. Changes stay in this demo.'}</p>
+    <details><summary class="caption">Completion required</summary>
+      <p class="caption">For a flow that must finish, such as a required update, cancellation can be disabled.</p>
+      <dees-button type="secondary" text="Open required setup" @clicked=${() => this.openOverlay(false)}></dees-button>
+    </details>`;
+  }
+
+  public async disconnectedCallback() {
+    if (this.overlayStepper?.isConnected) await this.overlayStepper.destroy();
+    await super.disconnectedCallback();
+  }
+}
+
+export const stepperDemo = () => demoPage('Stepper', 'A clear path from the first detail to the finished result.', html`<dees-demo-stepper></dees-demo-stepper>`);