@design.estate/dees-catalog 3.97.1 → 3.98.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design.estate/dees-catalog",
-  "version": "3.97.1",
+  "version": "3.98.1",
   "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",
@@ -35,11 +35,11 @@
   "devDependencies": {
     "@design.estate/dees-wcctools": "^3.9.2",
     "@git.zone/tsbuild": "^4.4.2",
-    "@git.zone/tsbundle": "^2.11.0",
+    "@git.zone/tsbundle": "^2.11.3",
     "@git.zone/tstest": "^3.6.6",
     "@git.zone/tswatch": "^3.3.5",
     "@push.rocks/projectinfo": "^5.1.0",
-    "@types/node": "^26.1.0"
+    "@types/node": "^26.1.1"
   },
   "files": [
     "ts/**/*",

package/readme.hints.md

@@ -1114,3 +1114,38 @@ Some components appear in multiple groups via `demoGroups = ['Primary', 'Seconda
 - Tool cards resolve their kind through `DeesHarnessToolRegistry.default` (open set + `kind` override), so consumers register custom tools without forking components; `server__tool` names auto-classify as MCP with annotation badges.
 - The syntax palette moved to the shared `ts_web/elements/00syntax.ts` (`syntaxPaletteStyles` + `syntaxScopeStyles`); codebox and harness markdown consume it — don't re-declare `--syntax-*`/hljs scope colors per component.
 - `dees-dataview-codebox` diff mode: set `codeBefore` (against `codeToDisplay`) or a pre-computed `unifiedDiff` patch; `diffView` = `'inline' | 'split'`. Engine lives dependency-free in `codebox.diff.ts` (LCS + intraline segments + context folding + `toUnifiedDiff`). Tool cards use it for file-write bodies via the `diffBlock` render helper.
+
+## dees-simple-login multi-method rework (2026-07)
+
+- **The catalog owns no WebAuthn protocol.** A passkey ceremony needs server-issued options and server-side verification, so `@simplewebauthn/browser` is deliberately *not* a dependency. Two mutually exclusive plug-in modes: no handler set → the component dispatches `passkey-login` / `passkey-register` / `provider-login` and stops; handler set (`passkeyLoginHandler` etc.) → the component awaits it, owns the busy state, turns a rejection into that method's error, and does **not** dispatch the request event. Suppressing the event in handler mode is what makes a double-started ceremony impossible — two concurrent `navigator.credentials.get()` calls reject each other.
+- **`login` is the one exception**: it is a notification, not a request, and always fires with dees-form's detail verbatim (`{ data: { username, password } }`) because cloudly, dcrouter and gitops depend on it.
+- **Configuration decides availability, `methodOrder` only reorders.** `passkey` (false), `providers` ([]), `password` (true) decide *whether* a method renders; `methodOrder` decides the sequence and appends anything it omits, so an incomplete order can never silently hide a configured method. Default therefore resolves to `['password']`, so the zero-configuration card is the same username/password form with the same API surface. It is **not** pixel-identical to the pre-rework component: three deliberate visual changes ship with it — the submit button is now card-width (the pre-existing `dees-tile dees-form-submit { width: 100% }` never worked because the host is `inline-block`), `.subheader` moved from `--dees-color-text-muted` (0.30 alpha, ~2:1) to `--dees-color-text-secondary`, and `.loginContainer` gained `box-sizing`, `padding` and `overflow-y: auto` so a tall multi-method card scrolls instead of clipping.
+- **Shadow-DOM reach-in is a real contract.** All three consumers do `shadowRoot.querySelector('dees-form')` then `form.setStatus()` / `form.reset()`, and cloudly's `switchToLoginContent()` hand-reverses the inline styles `switchToSlottedContent()` sets. So: `.loginContainer` / `.login` / `.slotContainer` must keep their names and inline-style choreography, the password `dees-form` must stay the first and only form in shadow order, and the `formData` listener is bound declaratively (`@formData`) because the form is now conditionally rendered and a one-shot `firstUpdated` hook-up would silently stop firing.
+- **Do not bind `.text` on the credentials `dees-form-submit`.** `dees-form.setStatus(state, text)` writes that property imperatively, and `dees-form.reset()` ends with `setStatus('normal', 'Submit')`. A Lit property binding would clobber a consumer's status text on the next render, so the label is slotted instead — which also means `labels.passwordSubmit` is read at first render only.
+- The credentials form is wrapped in `dees-tile` **only when password is the sole method**. Once the column holds other methods the column is the card, and a nested tile would inset the fields 24px against full-width buttons and read as a stray box.
+- Additive primitive gaps closed on the way: `dees-button.fullWidth` (`full-width` attribute — the host being `inline-block` meant `width: 100%` never stretched the `inline-flex` face; the opt-in path also adds `min-width: 0` + label ellipsis), the same forwarded on `dees-form-submit`, `dees-input-text.autocomplete` (needed for `username webauthn` conditional mediation), and `--dees-spinner-color` on `dees-spinner` (it hard-coded `--dees-color-text-primary`, painting a near-black arc on an accent button face in bright theme).
+- **Never mark a pending `dees-button` disabled** — `.button.disabled { opacity: 0.5 }` washes out the spinner. Guard re-entry in the handler instead; only *sibling* buttons get `disabled`.
+- Known pre-existing gaps this rework did **not** change: `--dees-color-text-secondary` is 3.44:1 in bright theme (sub-AA for 13px copy); `--dees-color-accent-primary` with white text is 3.65–4.02:1; `dees-tile`'s 16px heading padding vs the 24px content padding this component sets leaves an 8px misalignment; `dees-spinner`'s success/error faces still hard-code `--dees-color-text-primary`.
+
+## dees-button keyboard operability (2026-07)
+
+`dees-button` renders its face as a `<div class="button">`, so it had no keyboard affordance at all — nothing built on it (including every action in `dees-simple-login`) was reachable by Tab. Fixed in the primitive rather than per consumer.
+
+- The face carries `role="button"`, `tabindex` (`0`, or `-1` when `disabled`), `aria-disabled`, and `aria-busy` while `status === 'pending'`. A pending button stays focusable on purpose — pulling focus mid-ceremony strands the user.
+- **Enter activates on keydown, Space on keyup**, matching native buttons. Space keydown is swallowed so the page cannot scroll under a focused button. Verified with real CDP key events: Space activates without moving a scrollable ancestor's `scrollTop`.
+- **Keyboard activation goes through a real `click()` on the face, not a direct `clicked` dispatch.** `dees-workspace-diff-editor` (5 call sites) and `profilepicture.modal` (2) bind plain `@click` on `dees-button` rather than `@clicked`; only a real click drives both. `pointer-events: none` does not block a programmatic `click()`, so inertness is enforced in `activateFromKeyboard()` — refusing `disabled` *and* any non-`normal` status, because the status faces already set `pointer-events: none` for the mouse.
+- `DeesButton.focus()` / `.blur()` forward to the face; without that, `host.focus()` is a silent no-op.
+- **`dees-form-submit.focus()` is NOT a focus method — it submits.** `dees-form.addBehaviours()` calls `getSubmitButton()?.focus()` to implement "Enter in the last field submits the form". An earlier attempt to make it forward focus properly broke that; it must stay as-is. Keyboard focus reaches the submit through the inner `dees-button` face instead. Pinned by a test.
+- The `:focus-visible` ring uses the **opaque** `--dees-color-accent-primary`, not `--dees-color-focus-ring`. That shared token is a 0.45/0.55 alpha and composites to 1.85:1 (bright) / 2.31:1 (dark) against the surface behind the button — under the 3:1 WCAG 2.2 SC 1.4.11 wants, and a navy hairline on a dark canvas. Raising the alpha on the token itself would fix every other control too and is the wider change.
+### Focus containment across the login/app crossfade
+
+Both halves of `dees-simple-login` live in the DOM permanently, stacked and cross-faded with `opacity` + `pointer-events`. That was sufficient only while nothing inside them could hold focus. Once `dees-button` faces became focusable, `pointer-events: none` stopped containing anything — it does not remove a tab stop, and keyboard activation deliberately bypasses it — so the hidden half became reachable in both directions: Tab out of the password form into the invisible app shell, or Tab back into the invisible login card after signing in and start a passkey ceremony there.
+
+`inert` is the only thing that removes a hidden-but-rendered subtree from focus and the accessibility tree. It is derived from each container's effective `pointer-events` via a `MutationObserver` on the inline styles, **not** from an internal flag, because consumers reverse the transition by hand: cloudly's `switchToLoginContent()` writes `.login` / `.loginContainer` / `.slotContainer` inline styles directly and knows nothing about `inert`. Keying off a flag it cannot reset would leave its login card permanently inert after a session expiry. Observe only `attributeFilter: ['style']` — `inert` reflects to its own attribute and would otherwise re-trigger the observer.
+
+### Open follow-ups from this change (separate decisions, deliberately not done here)
+
+- **`--dees-color-focus-ring` is still sub-3:1 for every control other than `dees-button`.** Inputs, dropdowns and the rest still use the shared token at 0.45/0.55 alpha, which composites to 1.85:1 (bright) / 2.31:1 (dark). `dees-button` was fixed locally by switching its ring to the opaque accent, so the catalog is now *inconsistent*: one control has a compliant focus indicator and the others do not. Raising the token's alpha is the wider fix and needs its own review across every control that reads it.
+- **`dees-button-exit` is unaudited and very likely has the same keyboard defect.** It renders a decorative X glyph (`.maincontainer` + two line divs) with no click handler, no `role` and no `tabindex`; consumers wire clicks on the host. It is not a `dees-button` consumer, so the keyboard fix does not reach it.
+
+- Consumer audit: 16 non-demo components use `dees-button`. None wrap it in a `role="menu"/"listbox"/"option"/"tab"` container, none attach keyboard handlers to the button or an ancestor of it (`dees-harness-composer` and `dees-harness-question-card` bind keydown on their own `textarea`/`input`), `dees-modal` has no focus trap, `dees-button-group` only slots, and no component binds both `@click` and `@clicked` on the same button — so no double activation and no nested-role reporting change.

package/readme.md

@@ -90,10 +90,15 @@ button.text = 'Click me';
   shape="pill"        // Options: squircle (default rounded rect), pill (capsule for standalone actions)
   status="pending"    // Options: normal, pending, success, error
   disabled={false}    // Optional: disables the button
+  full-width          // Optional: stretches the button face to the host width
   @click=${handleClick}
 >Click me</dees-button>
 ```
 
+The button is keyboard operable: its face carries `role="button"` and `tabindex`, Enter and
+Space activate it (dispatching a real `click`, so both `@click` and `@clicked` fire), a
+disabled button leaves the tab order, and keyboard focus draws a `:focus-visible` ring.
+
 #### `DeesBadge`
 Display status indicators or counts with customizable styles.
 
@@ -157,12 +162,22 @@ Loading indicator with customizable appearance.
 
 ```typescript
 <dees-spinner
-  size="medium"         // Options: small, medium, large
-  type="primary"        // Options: primary, secondary, light, dark
-  overlay              // Optional: adds a full-screen overlay
+  .size=${20}                    // Optional: diameter in pixels (default 20)
+  .status=${'normal'}            // Optional: 'normal' | 'pending' | 'success' | 'error'
+  .bnw=${true}                   // Optional: black-and-white treatment
 ></dees-spinner>
 ```
 
+The arc colour follows the `--dees-spinner-color` custom property, falling back to
+`--dees-color-text-primary`. Set it on an ancestor when the spinner sits on a coloured
+surface — an accent button face, for example — so the arc matches that surface's foreground:
+
+```css
+dees-button {
+  --dees-spinner-color: var(--dees-color-on-accent);
+}
+```
+
 #### `DeesToast`
 Notification toast messages with various styles, positions, and auto-dismiss functionality.
 
@@ -325,6 +340,7 @@ Text input field with validation, info tooltips, description text, and context m
   value="initial@value.com"  // Initial value
   required             // Makes the field required
   disabled            // Disables the input
+  .autocomplete=${'username'}   // Autofill hint; unset renders no autocomplete attribute
   .infoText=${'Hover icon tooltip text'}    // Shows ⓘ icon on label with hover tooltip
   .description=${'Permanent help text below the input'}  // Small text below the input
   .validationFunction=${(value) => {        // Auto-validates on every keystroke
@@ -711,9 +727,14 @@ Submit button component specifically designed for `DeesForm`.
 <dees-form-submit
   disabled            // Optional: disable submit button
   status="normal"     // Options: normal, pending, success, error
+  full-width          // Optional: stretches the button face to the host width
 >Submit Form</dees-form-submit>
 ```
 
+Note that `DeesFormSubmit.focus()` submits rather than focuses — `DeesForm` calls it to
+implement "Enter in the last field submits". Keyboard focus reaches the submit through the
+inner `DeesButton` face.
+
 ---
 
 ### App Shell (Layout) Components
@@ -1848,21 +1869,69 @@ Simple application dashboard component for quick prototyping.
 ```
 
 #### `DeesSimpleLogin`
-Simple login form component with validation and customization.
+
+Login surface for an application shell. Offers up to three authentication methods in one
+card — passkeys, identity providers ("sign in with …") and a username/password form — and
+renders the authenticated app through its default slot.
+
+A method is offered only when it is **configured**, so the zero-configuration default is the
+password form alone:
+
+```typescript
+<dees-simple-login name="My Application" @login=${handleLogin}>
+  <!-- authenticated content -->
+</dees-simple-login>
+```
+
+`login` fires with `detail.data.{username,password}`; call `switchToSlottedContent()` once
+credentials check out.
+
+Turn on more methods and they render in the canonical order passkey → provider → password:
 
 ```typescript
 <dees-simple-login
-  .appName=${'My Application'}
-  .logo=${'./assets/logo.png'}
-  .backgroundImage=${'./assets/background.jpg'}
-  .fields=${['username', 'password']}
-  showForgotPassword
-  showRememberMe
+  name="login.idp.global"
+  .passkey=${true}
+  .providers=${[
+    { id: 'idp-global', label: 'idp.global', icon: 'lucide:shieldCheck' },
+    { id: 'workspace', label: 'Workspace SSO', icon: 'lucide:building2' },
+  ]}
+  .passkeyLoginHandler=${async (context) => runWebAuthnCeremony(context)}
+  .providerLoginHandler=${async (context) => redirectTo(context.providerId)}
   @login=${handleLogin}
-  @forgot-password=${handleForgotPassword}
 ></dees-simple-login>
 ```
 
+**Configuration** — `passkey` (default `false`), `providers` (default `[]`), `password`
+(default `true`), `passkeyIntents` (`['authenticate']`, add `'register'` to offer
+enrollment), `methodOrder`, `labels`, `passkeyAvailable` (override capability detection),
+`passkeyAutofill` (WebAuthn conditional mediation — inert unless `passkeyLoginHandler` is set,
+the password method renders a username field, and the browser reports conditional mediation).
+
+**Who owns the WebAuthn ceremony** — not this component. A ceremony needs server-issued
+options and server-side verification, so the catalog carries no WebAuthn dependency. Plug
+one in either way, never both for the same interaction:
+
+- **Event mode** (no handler set) — the component dispatches `passkey-login`,
+  `passkey-register` or `provider-login` and stops. Report progress back with `setBusy()` /
+  `reportError()`.
+- **Handler mode** (`passkeyLoginHandler`, `passkeyRegisterHandler`, `providerLoginHandler`,
+  `passwordLoginHandler`) — the component awaits the handler, owns that method's busy state
+  and turns a rejection into that method's error message. The request event is not
+  dispatched, so a ceremony can never start twice.
+
+`login` is a notification rather than a request and always fires, even in handler mode.
+
+Busy and error state is independent per method, per passkey intent and per provider, so a
+failed passkey attempt never blanks the password form. `reportError(target, message)`,
+`setBusy(target, busy)`, `isBusy(target)` and `getError(target)` each take either a
+`TDeesLoginMethod` or an `IDeesLoginTarget` (`{ method, intent?, providerId? }`).
+`clearError(target?)` takes an optional target and clears every error when called without
+one; `reset()` takes no arguments and clears all busy and error state plus the password form.
+
+Provider icons are always consumer-supplied Lucide names — the catalog ships no third-party
+brand assets.
+
 ---
 
 ### Shopping Components

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/dees-catalog',
-  version: '3.97.1',
+  version: '3.98.1',
   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-button/dees-button/dees-button.ts

@@ -78,6 +78,15 @@ export class DeesButton extends DeesElement {
   })
   accessor insideForm: boolean = false;
 
+  /**
+   * stretches the inner button face to the host width.
+   * The host is `inline-block`, so `width: 100%` on the host alone leaves the
+   * `inline-flex` face shrink-wrapped. Opt in for stacked, full-bleed actions
+   * (login cards, sheets, empty states).
+   */
+  @property({ type: Boolean, reflect: true, attribute: 'full-width' })
+  accessor fullWidth: boolean = false;
+
   @property({ type: String, reflect: true })
   accessor icon!: string;
 
@@ -124,6 +133,26 @@ export class DeesButton extends DeesElement {
         display: none;
       }
 
+      :host([full-width]) {
+        display: block;
+        width: 100%;
+      }
+
+      /* A full-width button is sized by its container, so its label has to yield rather
+         than spill out of the face when the container is narrower than the text. */
+      :host([full-width]) .button {
+        width: 100%;
+        min-width: 0;
+        overflow: hidden;
+      }
+
+      :host([full-width]) .textbox {
+        min-width: 0;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+      }
+
       /* Form spacing styles */
       :host([inside-form]) {
         margin-bottom: var(--dees-spacing-lg);
@@ -363,10 +392,30 @@ export class DeesButton extends DeesElement {
         display: none;
       }
 
-      /* Focus state */
+      /* Focus state.
+         The base .button rule sets outline:none for the pointer path; the ring is restored
+         here for :focus-visible only, so a mouse press never leaves a ring behind while
+         keyboard focus is always visible. This rule is the focus affordance keyboard users
+         actually see — do not remove it alongside the base outline:none. */
       .button:focus-visible {
-        outline: 2px solid var(--dees-color-focus-ring);
+        /* Deliberately NOT --dees-color-focus-ring: that token is a 0.45/0.55 alpha, which
+           composites to 1.85:1 (bright) and 2.31:1 (dark) against the surface behind the
+           button — under the 3:1 that WCAG 2.2 SC 1.4.11 requires of a focus indicator, and
+           effectively invisible as a navy hairline on a dark canvas. The opaque accent
+           measures 4.02:1 bright / 5.76:1 dark. Raising the alpha on the shared token would
+           fix every other control too and is the wider change. */
+        outline: 2px solid var(--dees-color-accent-primary);
         outline-offset: 2px;
+        /* The indicator has to appear at once. The base .button rule carries
+           transition:all, which animates outline-color up from its initial currentColor —
+           measured as ~50ms of a near-white ring on a bright accent face, i.e. briefly
+           invisible right when the user needs it. Only the focused state opts out. */
+        transition: none;
+      }
+
+      /* A disabled face is removed from the tab order, so it should never show a ring. */
+      .button.disabled:focus-visible {
+        outline: none;
       }
 
       /* Loading spinner */
@@ -488,7 +537,14 @@ export class DeesButton extends DeesElement {
         class="button ${this.isHidden ? 'hidden' : ''} ${actualType} size-${actualSize} shape-${this.shape} ${this.status} ${this.disabled
           ? 'disabled'
           : ''}"
+        role="button"
+        tabindex=${this.disabled ? -1 : 0}
+        aria-disabled=${this.disabled ? 'true' : 'false'}
+        aria-busy=${this.status === 'pending' ? 'true' : 'false'}
+        .ariaLabel=${showText ? null : this.text || null}
         @click="${this.dispatchClick}"
+        @keydown=${this.handleKeydown}
+        @keyup=${this.handleKeyup}
       >
         ${this.status === 'normal' ? html``: html`
           <dees-spinner
@@ -519,6 +575,76 @@ export class DeesButton extends DeesElement {
     );
   }
 
+  /** the inner face — the element that actually carries focus */
+  private get faceElement(): HTMLElement | null {
+    return (this.shadowRoot?.querySelector('.button') as HTMLElement | null) || null;
+  }
+
+  /**
+   * States in which the button must not react to input. `disabled` is obvious; the status
+   * faces matter too, because `.button.pending / .success / .error` already set
+   * `pointer-events: none` and keyboard activation has to refuse the same interactions a
+   * mouse cannot make.
+   */
+  private get isInert(): boolean {
+    return this.disabled || this.status !== 'normal';
+  }
+
+  /**
+   * Focus lives on the inner face inside the shadow root, so `host.focus()` has to forward
+   * or it is a silent no-op. Note that `dees-form-submit.focus()` is deliberately *not*
+   * wired to this — that method submits the form, and dees-form depends on it.
+   */
+  public focus(optionsArg?: FocusOptions): void {
+    const face = this.faceElement;
+    if (face) {
+      face.focus(optionsArg);
+      return;
+    }
+    super.focus(optionsArg);
+  }
+
+  public blur(): void {
+    this.faceElement?.blur();
+    super.blur();
+  }
+
+  private handleKeydown = (eventArg: KeyboardEvent): void => {
+    if (eventArg.key === ' ' || eventArg.key === 'Spacebar') {
+      // Native buttons activate Space on keyup. Swallow the keydown so the page cannot
+      // scroll underneath the focused button.
+      eventArg.preventDefault();
+      return;
+    }
+    if (eventArg.key === 'Enter') {
+      eventArg.preventDefault();
+      this.activateFromKeyboard();
+    }
+  };
+
+  private handleKeyup = (eventArg: KeyboardEvent): void => {
+    if (eventArg.key === ' ' || eventArg.key === 'Spacebar') {
+      eventArg.preventDefault();
+      this.activateFromKeyboard();
+    }
+  };
+
+  /**
+   * Keyboard activation goes through a real click rather than dispatching `clicked`
+   * directly, exactly as a native button does. Several catalog components bind `@click` on
+   * dees-button instead of `@clicked` (dees-workspace-diff-editor, the profile picture
+   * modal), and both listener styles have to keep working from the keyboard.
+   *
+   * `pointer-events: none` does not block a programmatic `click()`, so inertness is
+   * enforced here rather than left to CSS.
+   */
+  private activateFromKeyboard(): void {
+    if (this.isInert) {
+      return;
+    }
+    this.faceElement?.click();
+  }
+
   public async firstUpdated() {
     // Extract light DOM content (icon + text) and set as properties
     this.extractLightDom();