@mhmo91/schmancy 0.10.19 → 0.10.21

package/skills/schmancy/overlay.md

@@ -26,6 +26,19 @@ private handlePick = (ev: MouseEvent) => {
 
 Centered is the fallback (no anchor given). Sheet is the responsive adaptation (narrow viewport / touch / oversized content). You never pick layout — the system does.
 
+## Content forms
+
+`show()` accepts four content forms:
+
+| Form | When to use |
+|---|---|
+| `show(MyComponent)` | Component class — most common |
+| `show(html\`...\`)` | Inline template (eager — values frozen at call site) |
+| `show(() => html\`...\`)` | **Preferred for templates** — factory called at mount time; closed-over variables are read lazily, no snapshot staleness |
+| `show(lazy(() => import('./x')))` | Async / code-split component |
+
+Always prefer `() => html\`...\`` over `html\`...\`` when the template closes over any variable — the factory form evaluates those variables at mount time rather than baking them in at the call site.
+
 ## API
 
 | Export | Signature | Purpose |

package/skills/schmancy/page.md

@@ -1,42 +1,84 @@
 # schmancy-page
 
-> Native mobile-like page container. Fills remaining viewport height, prevents rubber-banding, pull-to-refresh, and double-tap zoom.
+> Viewport-locked layout primitive. Provides a definite-height frame so any composition inside it has a parent to resolve against.
+
+## Contract
+
+Two rules and one slot.
+
+1. **Outermost lock.** A `<schmancy-page>` with no `<schmancy-page>` ancestor anchors itself to the visual viewport (`position: fixed; inset: 0`) and tracks `visualViewport.height` for iOS soft-keyboard correctness. It does not rely on `html`/`body` height — the cascade above it is irrelevant.
+2. **Single-child stretch.** The slotted child fills the page box (`height: 100%; width: 100%; min-height: 0; min-width: 0`). More than one direct child produces a visible layout collision — fail-loud, not silent.
+
+Composition shape is plain CSS grid / flex inside the slotted child. The primitive does not prescribe header / footer / sidebar conventions; consumers arrange regions in standard CSS. The contract is the locked frame.
 
 ## Usage
+
+### App root
 ```html
-<schmancy-page rows="auto_1fr_auto">
-  <header>App bar</header>
-  <main>Scrollable content</main>
-  <footer>Bottom nav</footer>
+<schmancy-page>
+  <schmancy-area name="root" .default=${landing}>
+    <schmancy-route when="landing-view" .component=${landing}></schmancy-route>
+    <schmancy-route when="app-home"     .component=${appHome}></schmancy-route>
+  </schmancy-area>
 </schmancy-page>
 ```
 
-## Properties
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `rows` | string | `'auto_1fr_auto'` | Grid template rows — underscores become spaces (e.g. `'1fr_2fr_auto'`) |
-| `show-scrollbar` | boolean | `false` | Display scrollbar on scrollable area |
-| `no-select` | boolean | `false` | Disable text selection |
-
-## Behavior
-- Listens to `visualViewport` resize/scroll + `orientationchange` + keyboard focus events to recompute height.
-- Accounts for theme bottom offset (iOS safe area, home indicator).
-- Auto-assigns semantic elements (`header`, `main`, `footer`) to slots.
-- Inner scroll area uses `schmancy-scroll` for momentum-preserving scroll.
-
-## When to Use
-- Root of a mobile view or panel that should feel like a native page.
-- Any container where viewport-aware height + scroll containment matters.
-
-## Example — 3-row app shell
+### Sidebar + sticky header + body
 ```html
-<schmancy-page rows="auto_1fr_auto">
-  <schmancy-surface type="solid" rounded="none">
-    <schmancy-typography type="title">My App</schmancy-typography>
-  </schmancy-surface>
+<schmancy-page>
+  <div class="grid grid-cols-[auto_1fr]">
+    <app-rail></app-rail>
+    <schmancy-page>
+      <div class="grid grid-rows-[auto_1fr]">
+        <app-top-bar></app-top-bar>
+        <schmancy-area name="app">...</schmancy-area>
+      </div>
+    </schmancy-page>
+  </div>
+</schmancy-page>
+```
+
+The inner `<schmancy-page>` detects the outer ancestor, skips the viewport lock, and fills its grid cell via `height: 100%; width: 100%`.
 
-  <div class="p-4">…scrollable content…</div>
+### Tabs page
+```html
+<div class="grid grid-rows-[auto_1fr]">
+  <schmancy-tabs></schmancy-tabs>
+  <schmancy-area name="settings">...</schmancy-area>
+</div>
+```
 
-  <schmancy-navigation-bar></schmancy-navigation-bar>
+No `<schmancy-page>` here — this view is the routed body of a higher `<schmancy-page>`. The grid resolves against the area's `1fr` cell, which the area inherits from the page.
+
+### Admin shell (four regions)
+```html
+<schmancy-page>
+  <div class="grid grid-rows-[auto_1fr]">
+    <admin-top-bar></admin-top-bar>
+    <div class="grid grid-cols-[240px_1fr_320px]">
+      <admin-sidebar></admin-sidebar>
+      <schmancy-area name="admin"></schmancy-area>
+      <admin-inspector></admin-inspector>
+    </div>
+  </div>
 </schmancy-page>
 ```
+
+## Properties
+
+`<schmancy-page>` has no public properties. Composition is expressed by what you nest inside its single slot.
+
+The `outermost` attribute is set automatically on the page that owns the viewport lock. Consumers neither set nor read it.
+
+## Edge cases
+
+- **Print** — outermost page falls back to `position: static` so pagination works.
+- **iOS soft keyboard** — outermost page reads `visualViewport.height` and applies it as inline `height`, so the locked box shrinks when the keyboard opens.
+- **Long-form leaf (marketing, legal)** — opt out at the leaf, not at the page. The routed component declares its own `:host { height: auto; overflow: auto; min-height: 100% }`. The outer page stays locked; the leaf scrolls inside its `<schmancy-area>`.
+- **Master-detail with two scroll regions** — render two `<schmancy-area>` slots inside a grid; each owns its scroll.
+
+## Rules
+
+- A `<schmancy-page>` has exactly one direct child. If you need multiple regions, wrap them in a grid / flex container.
+- Do not put `class="h-full"`, `class="w-full"`, or `:host { height: 100% }` anywhere in your tree. The page and the area carry sizing; consumer code never does.
+- Scroll lives in `<schmancy-area>`, not in `<schmancy-page>`. Pages provide the locked frame; areas provide the scrolling region for their mounted component.

package/src/CLAUDE.md

@@ -18,6 +18,26 @@ by the Claude Code plugin. Drift here means drift everywhere.
 
 ## Source-author rules (not in the consumer docs)
 
+### Host sizing — `inline-flex` + `flex-1` pattern
+
+Every component whose `:host` carries visual affordances (box-shadow, transform) must follow the same pattern native `<button>` uses:
+
+```css
+/* ✓ correct */
+:host { display: inline-flex; }          /* host is a flex container */
+:host([width="full"]) { display: flex; width: 100%; }
+```
+
+```typescript
+/* inner interactive element */
+'flex-1 ...' : true,   /* ✓ resolves against the flex container's available space */
+'w-full ...' : true,   /* ✗ resolves against the containing block content-box — wrong when host is blockified by a parent flex layout */
+```
+
+**Why `flex-1` not `w-full`:** when a flex/grid parent stretches the `<schmancy-button>` host, `width: 100%` on the inner `<button>` resolves against the host's *containing-block content-box*, which remains content-sized for `inline-flex` hosts. The outer (flex-stretched) size and the inner (content-sized) size split — the inner element is narrower than the host, so `:host(:hover)` box-shadow fires across the full stretched area while the visible button fill is narrower. `flex-1` uses `flex-basis: 0` + grow, which resolves against the flex container's *available space* — always the stretched width — with no circular-percentage issue. This matches native `<button>` behavior: content-sized inline, stretches in flex containers.
+
+**Applies to:** `schmancy-button`, `schmancy-icon-button`, and any future component with host-level visual affordances.
+
 ### Component skeleton
 
 Every concrete component: