@mhmo91/schmancy 0.10.36 → 0.10.37

package/skills/schmancy/steps.md

@@ -1,53 +1,87 @@
-# schmancy-steps-container / schmancy-step
+# schmancy-steps / schmancy-step
 
-> Vertical stepper with collapsible steps, completion state, and navigation.
+> Vertical stepper with orientation rail and optional collapsible content. Dual render mode decided per step by content presence.
 
 ## Usage
+
 ```html
-<schmancy-steps-container currentStep="1" @change=${(e) => handleStep(e.detail.value)}>
-  <schmancy-step position="1" title="Account" description="Create your account">
+<!-- Rail mode (no slotted content) — dot + connector + label -->
+<schmancy-steps
+  class="flex flex-col"
+  .value=${activeStep}
+  @change=${(e) => handleStep(e.detail.value)}
+>
+  <schmancy-step position="1" label="Organisation"></schmancy-step>
+  <schmancy-step position="2" label="Legal entity"></schmancy-step>
+  <schmancy-step position="3" label="Location"></schmancy-step>
+  <schmancy-step position="4" label="Done"></schmancy-step>
+</schmancy-steps>
+
+<!-- Content mode (slotted content) — collapsible card, active step expands -->
+<schmancy-steps .value=${activeStep} @change=${(e) => handleStep(e.detail.value)}>
+  <schmancy-step position="1" label="Account" description="Create your account">
     <schmancy-input label="Email" required></schmancy-input>
   </schmancy-step>
-  <schmancy-step position="2" title="Profile" description="Set up profile">
+  <schmancy-step position="2" label="Profile" description="Set up profile">
     <schmancy-input label="Name" required></schmancy-input>
   </schmancy-step>
-</schmancy-steps-container>
+</schmancy-steps>
 ```
 
-## Properties (schmancy-steps-container)
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| currentStep | number | `1` | Currently active step (1-based) |
-| gap | number | `4` | Gap between steps (Tailwind scale) |
+## Properties — schmancy-steps
 
-## Properties (schmancy-step)
 | Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| position | number | `1` | Step position (1-based) |
-| title | string | `''` | Step title |
-| description | string | `''` | Step description |
-| completed | boolean | `false` | Explicitly mark as complete |
-| lockBack | boolean | `false` | Prevent navigating to previous steps |
-
-## Events (schmancy-steps-container)
+|---|---|---|---|
+| `value` | `number` | `1` | Active step (1-based). Reflected attribute. |
+| `lockBack` | `boolean` | `false` | Block back-navigation for the whole stepper. |
+
+Layout (spacing, orientation, width) is set by Tailwind classes on the host element; the primitive owns no layout props.
+
+## Events — schmancy-steps
+
 | Event | Detail | Description |
-|-------|--------|-------------|
-| change | `{ value: number }` | When current step changes |
+|---|---|---|
+| `change` | `{ value: number }` | Active step changed (property set or step click). |
+
+```ts
+export type SchmancyStepsChangeEvent = CustomEvent<{ value: number }>
+```
+
+## Properties — schmancy-step
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `position` | `number` | `1` | This step's 1-based index. Unique within the container. |
+| `label` | `string` | `''` | Step label. |
+| `description` | `string` | `''` | Secondary line (content mode only). |
+| `completed` | `boolean` | `false` | Force complete status regardless of order. |
+
+## Dual render mode
+
+A `<schmancy-step>` detects its own content via `slotchange`:
+
+- **With slotted content** — renders an interactive card row (icon circle, check/dot, label + description, `bg-primary-container/20` active card). The active step expands with `flex: 1 1 auto`; inactive steps collapse.
+- **Without slotted content** — renders a minimal orientation rail row (dot + connector + label). Use this for a left-panel navigation rail.
+
+## Step status
+
+| Condition | Status |
+|---|---|
+| `position < value` or `completed` | `complete` |
+| `position === value` | `current` |
+| `position > value` | `upcoming` |
+
+Clicking a `complete` or `current` step sets `value` and emits `change`. `upcoming` steps are inert. Back-navigation is blocked when the container has `lockBack`.
 
 ## Examples
+
 ```html
-<!-- With locked steps -->
-<schmancy-steps-container currentStep="2">
-  <schmancy-step position="1" title="Step 1" completed lockBack>
-    <!-- Already completed, cannot go back -->
-  </schmancy-step>
-  <schmancy-step position="2" title="Step 2">
+<!-- Lock back-navigation after the first step -->
+<schmancy-steps .value=${step} lockBack @change=${onStep}>
+  <schmancy-step position="1" label="Review" completed></schmancy-step>
+  <schmancy-step position="2" label="Confirm">
     <p>Current step content</p>
   </schmancy-step>
-  <schmancy-step position="3" title="Step 3">
-    <!-- Not yet reachable -->
-  </schmancy-step>
-</schmancy-steps-container>
+  <schmancy-step position="3" label="Done"></schmancy-step>
+</schmancy-steps>
 ```
-
-Only the active step renders its slotted content. Completed steps show a checkmark. Active step expands with `flex: 1`.

package/src/directives/reveal.ts

@@ -4,6 +4,9 @@
  * Uses Blackbird spring physics for natural, organic motion.
  * Element stays in DOM to prevent layout shift.
  *
+ * When fully revealed, no directive-imposed max-height or overflow:hidden
+ * is left on the element — it lays out at its natural full height.
+ *
  * Usage:
  * ```ts
  * // Basic - uses 'smooth' preset
@@ -12,7 +15,7 @@
  * // With preset - 'snappy' for quick interactions
  * html`<div ${reveal(this.isVisible, { preset: 'snappy' })}>Content</div>`
  *
- * // With custom max height
+ * // Opt-in scroll cap (explicit maxHeight — keeps overflow:auto, does NOT clip)
  * html`<div ${reveal(this.items.length > 1, { maxHeight: '200px' })}>Content</div>`
  *
  * // Bouncy for playful UI
@@ -28,131 +31,202 @@
  * @see packages/schmancy/src/utils/animation.ts for Blackbird system
  */
 
-import { noChange } from 'lit'
-import { AsyncDirective, directive } from 'lit/async-directive.js'
-import type { ElementPart, PartInfo } from 'lit/directive.js'
-import { PartType } from 'lit/directive.js'
+import { noChange } from 'lit';
+import { AsyncDirective, directive } from 'lit/async-directive.js';
+import { type ElementPart, type PartInfo, PartType } from 'lit/directive.js';
+import { fromEvent, Subject } from 'rxjs';
+import { filter, take, takeUntil } from 'rxjs/operators';
 import {
-	SPRING_SMOOTH,
-	SPRING_SNAPPY,
-	SPRING_BOUNCY,
-	SPRING_GENTLE,
-	getEasing,
-	type AnimationPreset,
-} from '../utils/animation'
-import { reducedMotion$ } from './reduced-motion'
+  type AnimationPreset,
+  getEasing,
+  SPRING_BOUNCY,
+  SPRING_GENTLE,
+  SPRING_SMOOTH,
+  SPRING_SNAPPY,
+} from '../utils/animation';
+import { reducedMotion$ } from './reduced-motion';
 
-export type RevealPreset = 'smooth' | 'snappy' | 'bouncy' | 'gentle'
+export type RevealPreset = 'smooth' | 'snappy' | 'bouncy' | 'gentle';
 
 export interface RevealOptions {
-	/** Animation preset (default: 'smooth') */
-	preset?: RevealPreset
-	/** Max height when revealed (default: '10rem') */
-	maxHeight?: string
-	/** Custom duration override in ms (uses preset duration if not specified) */
-	duration?: number
-	/** Custom easing override (uses preset easing if not specified) */
-	easing?: string
+  /** Animation preset (default: 'smooth') */
+  preset?: RevealPreset;
+  /**
+   * Explicit scroll cap (opt-in). When set the element is constrained to
+   * this height with overflow:auto — content scrolls rather than clips.
+   * When omitted (the default) the element is fully unconstrained after
+   * opening: no max-height, no overflow:hidden left on it.
+   */
+  maxHeight?: string;
+  /** Custom duration override in ms (uses preset duration if not specified) */
+  duration?: number;
+  /** Custom easing override (uses preset easing if not specified) */
+  easing?: string;
 }
 
 const PRESETS: Record<RevealPreset, AnimationPreset> = {
-	smooth: SPRING_SMOOTH,
-	snappy: SPRING_SNAPPY,
-	bouncy: SPRING_BOUNCY,
-	gentle: SPRING_GENTLE,
-}
+  smooth: SPRING_SMOOTH,
+  snappy: SPRING_SNAPPY,
+  bouncy: SPRING_BOUNCY,
+  gentle: SPRING_GENTLE,
+};
 
 class RevealDirective extends AsyncDirective {
-	private initialized = false
-	private element: HTMLElement | null = null
-
-	constructor(partInfo: PartInfo) {
-		super(partInfo)
-		if (partInfo.type !== PartType.ELEMENT) {
-			throw new Error('reveal() can only be used on elements')
-		}
-	}
-
-	render(_show?: boolean, _options?: RevealOptions) {
-		return noChange
-	}
-
-	override update(part: ElementPart, [show = false, options = {}]: [boolean | undefined, RevealOptions?]) {
-		const element = part.element as HTMLElement
-		this.element = element
-
-		const { preset = 'smooth', maxHeight = '10rem', duration, easing } = options
-
-		// Get the preset configuration
-		const presetConfig = PRESETS[preset]
-
-		// Determine actual duration and easing
-		const actualDuration = duration ?? presetConfig.duration
-		const actualEasing = easing ?? getEasing(presetConfig)
-
-		const reducedMotion = reducedMotion$.value
-
-		// Set up transitions on first run or when preset changes
-		if (!this.initialized) {
-			this.setupElement(element, actualDuration, actualEasing, reducedMotion)
-			this.initialized = true
-		}
-
-		// Apply show/hide styles with spring physics
-		if (show) {
-			element.style.maxHeight = maxHeight
-			element.style.opacity = '1'
-			element.style.transform = 'translateY(0) scale(1)'
-			element.style.pointerEvents = ''
-			element.style.paddingTop = ''
-			element.style.paddingBottom = ''
-			element.style.marginTop = ''
-			element.style.marginBottom = ''
-			element.removeAttribute('aria-hidden')
-			element.removeAttribute('inert')
-		} else {
-			element.style.maxHeight = '0'
-			element.style.opacity = '0'
-			element.style.transform = 'translateY(-8px) scale(0.98)'
-			element.style.pointerEvents = 'none'
-			element.style.paddingTop = '0'
-			element.style.paddingBottom = '0'
-			element.style.marginTop = '0'
-			element.style.marginBottom = '0'
-			element.setAttribute('aria-hidden', 'true')
-			element.setAttribute('inert', '')
-		}
-
-		return noChange
-	}
-
-	private setupElement(element: HTMLElement, duration: number, easing: string, reducedMotion: boolean): void {
-		element.style.overflow = 'hidden'
-
-		if (reducedMotion) {
-			// Instant transitions for reduced motion
-			element.style.transition = 'none'
-		} else {
-			// Spring physics transitions — include padding/margin so hidden elements take zero space
-			element.style.transition = [
-				`max-height ${duration}ms ${easing}`,
-				`opacity ${duration}ms ${easing}`,
-				`transform ${duration}ms ${easing}`,
-				`padding ${duration}ms ${easing}`,
-				`margin ${duration}ms ${easing}`,
-			].join(', ')
-		}
-	}
-
-	override disconnected(): void {
-		if (this.element) {
-			this.element.style.willChange = ''
-		}
-	}
-
-	override reconnected(): void {
-		// State preserved in inline styles — no action needed
-	}
+  private initialized = false;
+  /** Fires on disconnect to tear down the transitionend subscription. */
+  private teardown$ = new Subject<void>();
+  /** True if this is the very first update call — used to detect always-true initial mount. */
+  private firstUpdate = true;
+
+  constructor(partInfo: PartInfo) {
+    super(partInfo);
+    if (partInfo.type !== PartType.ELEMENT) {
+      throw new Error('reveal() can only be used on elements');
+    }
+  }
+
+  render(_show?: boolean, _options?: RevealOptions) {
+    return noChange;
+  }
+
+  override update(
+    part: ElementPart,
+    [show = false, options = {}]: [boolean | undefined, RevealOptions?],
+  ) {
+    const element = part.element as HTMLElement;
+
+    const { preset = 'smooth', maxHeight, duration, easing } = options;
+    const explicitCap = maxHeight !== undefined;
+
+    const presetConfig = PRESETS[preset];
+    const actualDuration = duration ?? presetConfig.duration;
+    const actualEasing = easing ?? getEasing(presetConfig);
+    const reducedMotion = reducedMotion$.value;
+
+    const isFirstUpdate = this.firstUpdate;
+    this.firstUpdate = false;
+
+    if (!this.initialized) {
+      this.initialized = true;
+
+      if (reducedMotion) {
+        element.style.transition = 'none';
+      } else {
+        element.style.transition = [
+          `max-height ${actualDuration}ms ${actualEasing}`,
+          `opacity ${actualDuration}ms ${actualEasing}`,
+          `transform ${actualDuration}ms ${actualEasing}`,
+          `padding ${actualDuration}ms ${actualEasing}`,
+          `margin ${actualDuration}ms ${actualEasing}`,
+        ].join(', ');
+      }
+    }
+
+    if (show) {
+      if (isFirstUpdate) {
+        // Always-true initial mount: do not impose max-height animation.
+        // Apply opacity/transform entrance only (visible immediately for
+        // reduced-motion; fades in via the transition for normal motion).
+        if (explicitCap) {
+          element.style.maxHeight = maxHeight;
+          element.style.overflow = 'auto';
+        } else {
+          element.style.maxHeight = '';
+          element.style.overflow = '';
+        }
+        element.style.opacity = '1';
+        element.style.transform = 'translateY(0) scale(1)';
+      } else {
+        // Toggle case: false→true. Animate from 0 to natural height,
+        // then release the clamp so content is fully unconstrained.
+        if (reducedMotion) {
+          if (explicitCap) {
+            element.style.maxHeight = maxHeight;
+            element.style.overflow = 'auto';
+          } else {
+            element.style.maxHeight = '';
+            element.style.overflow = '';
+          }
+          element.style.opacity = '1';
+          element.style.transform = 'translateY(0) scale(1)';
+        } else {
+          // Force a concrete start value so CSS can animate from it.
+          element.style.overflow = 'hidden';
+          element.style.maxHeight = '0';
+          void element.offsetHeight; // force reflow
+
+          const targetHeight = explicitCap ? maxHeight : `${element.scrollHeight}px`;
+          element.style.maxHeight = targetHeight;
+          element.style.opacity = '1';
+          element.style.transform = 'translateY(0) scale(1)';
+
+          if (!explicitCap) {
+            // Once the open animation settles, release the clamp entirely.
+            fromEvent<TransitionEvent>(element, 'transitionend')
+              .pipe(
+                filter((e) => e.propertyName === 'max-height' && e.target === element),
+                take(1),
+                takeUntil(this.teardown$),
+              )
+              .subscribe(() => {
+                element.style.maxHeight = '';
+                element.style.overflow = '';
+              });
+          } else {
+            fromEvent<TransitionEvent>(element, 'transitionend')
+              .pipe(
+                filter((e) => e.propertyName === 'max-height' && e.target === element),
+                take(1),
+                takeUntil(this.teardown$),
+              )
+              .subscribe(() => {
+                element.style.overflow = 'auto';
+              });
+          }
+        }
+      }
+
+      element.style.pointerEvents = '';
+      element.style.paddingTop = '';
+      element.style.paddingBottom = '';
+      element.style.marginTop = '';
+      element.style.marginBottom = '';
+      element.removeAttribute('aria-hidden');
+      element.removeAttribute('inert');
+    } else {
+      // Collapse: animate to height 0. Re-measure from natural height if
+      // the clamp was previously released (max-height is '' or 'none').
+      if (element.style.maxHeight === '' || element.style.maxHeight === 'none') {
+        element.style.overflow = 'hidden';
+        element.style.maxHeight = `${element.scrollHeight}px`;
+        void element.offsetHeight; // force reflow so CSS sees the start value
+      } else {
+        element.style.overflow = 'hidden';
+      }
+
+      element.style.maxHeight = '0';
+      element.style.opacity = '0';
+      element.style.transform = 'translateY(-8px) scale(0.98)';
+      element.style.pointerEvents = 'none';
+      element.style.paddingTop = '0';
+      element.style.paddingBottom = '0';
+      element.style.marginTop = '0';
+      element.style.marginBottom = '0';
+      element.setAttribute('aria-hidden', 'true');
+      element.setAttribute('inert', '');
+    }
+
+    return noChange;
+  }
+
+  override disconnected(): void {
+    this.teardown$.next();
+  }
+
+  override reconnected(): void {
+    // Re-subscribe is handled on the next update() call via the new subscription
+    // created in the show branch. Nothing to wire up here explicitly.
+  }
 }
 
-export const reveal = directive(RevealDirective)
+export const reveal = directive(RevealDirective);

package/src/steps/index.ts

@@ -1,3 +1,3 @@
 export * from './schmancy-step';
-export * from './schmancy-steps-container';
+export * from './schmancy-steps';
 export * from './steps.context';