@polymorphism-tech/morph-spec 9.7.0 → 10.0.0

package/framework/standards/frontend/scroll-driven/scroll-components.md

@@ -5,7 +5,7 @@
 > **Keywords:** pinned gallery, horizontal scroll, modal, lightbox, parallax, count-up, reveal, scroll progress, accordion
 > **Load When:** ui-designer active, or building a scroll-driven marketing page
 
-**Verified against:** GSAP 3.13 (ScrollTrigger, matchMedia, context) + React 18 + Lenis 1.x, shipped to production. Last-verified: 2026-08-21.
+**Verified against:** GSAP 3.13 (ScrollTrigger, matchMedia, context) + React 18 + Lenis 1.x, shipped to production. Last-verified: 2026-10-27.
 
 ---
 
@@ -114,6 +114,19 @@ useEffect(() => {
 
 **Render overlays outside any pinned section.** A pin applies a `transform` to its container, which becomes the containing block for `position: fixed` and breaks the overlay. Put the modal in a fragment as a sibling of the section.
 
+The markup: the backdrop closes on click, the panel stops propagation so a click inside does not close it, and the dialog carries its role.
+
+```jsx
+{active !== null && (
+  <div className={`lmodal${shown ? ' in' : ''}`} onClick={close} role="dialog" aria-modal="true">
+    <div className="lmodal__panel" data-lenis-prevent onClick={(e) => e.stopPropagation()}>
+      <button className="lmodal__close" onClick={close} aria-label="Close">×</button>
+      {/* content */}
+    </div>
+  </div>
+)}
+```
+
 **Mark the scrollable panel `data-lenis-prevent`.** Stopping the smooth scroller is not enough: while stopped it calls `preventDefault()` on any `touchmove` that reaches it, so a panel with `overflow-y: auto` scrolls with the wheel and is frozen under a finger. Whatever sits at the bottom of the panel, usually the CTA, becomes unreachable on a phone. See `frontend/scroll-driven/smooth-scroll.md`, Section 3.
 
 ```jsx
@@ -199,6 +212,8 @@ Format for the locale at write time (the decimal comma above is pt-BR). Never an
 
 ## Section 7: Persistent Elements
 
+These live at the app root, outside every section, and repeat on almost every marketing page.
+
 **Slim translucent nav** that gains a background once scrolled:
 
 ```jsx
@@ -208,6 +223,19 @@ useEffect(() => {
   window.addEventListener('scroll', onScroll, { passive: true })
   return () => window.removeEventListener('scroll', onScroll)
 }, [])
+return (
+  <nav className={`nav${solid ? ' nav--solid' : ''}`}>
+    <a className="nav__logo" href="#top"><span>{BRAND}</span></a>
+    <div className="nav__links">{/* anchors */}</div>
+    <a className="btn btn-accent" href="#contact">{CTA}</a>
+  </nav>
+)
+```
+
+```css
+.nav { position: fixed; top: 0; inset-inline: 0; z-index: 100; display: flex; align-items: center;
+  justify-content: space-between; padding: 16px clamp(16px,5vw,48px); transition: background .3s, backdrop-filter .3s; }
+.nav--solid { background: rgba(14,11,12,.7); backdrop-filter: blur(10px); border-bottom: 1px solid var(--hair); }
 ```
 
 **Scroll progress bar** that prefers the smooth scroller when present:
@@ -225,20 +253,64 @@ useEffect(() => {
 }, [])
 ```
 
+```jsx
+return <div className="scroll-progress" ref={ref} />
+```
+
+```css
+.scroll-progress { position: fixed; top: 0; left: 0; z-index: 101; height: 3px; width: 100%;
+  transform: scaleX(0); transform-origin: 0 50%; background: linear-gradient(90deg, var(--accent), var(--accent-soft)); }
+```
+
 Transform-based progress (`scaleX` with `transform-origin: 0 50%`) stays on the compositor. Animating `width` does not.
 
+**Floating chat button.** A fixed exit channel to the business's messaging app, always within reach. It is also the fallback when the lead form fails. For WhatsApp, a `wa.me` deep link with a prefilled message:
+
+```jsx
+<a className="chat-float" href={`https://wa.me/${PHONE}?text=${encodeURIComponent(MESSAGE)}`}
+   target="_blank" rel="noopener noreferrer" aria-label="Chat on WhatsApp">
+  <svg viewBox="0 0 24 24" width="26" height="26" aria-hidden="true">{/* icon path */}</svg>
+</a>
+```
+
+```css
+.chat-float { position: fixed; right: 20px; bottom: 20px; z-index: 90; width: 56px; height: 56px;
+  display: grid; place-items: center; border-radius: 50%; background: #25d366; color: #fff;
+  box-shadow: 0 8px 24px rgba(0,0,0,.35); transition: transform .25s; }
+.chat-float:hover { transform: translateY(-3px) scale(1.05); }
+```
+
+Keep its z-index below the nav and overlays, and check that it does not cover a CTA on mobile.
+
 ---
 
 ## Section 8: Accordion
 
-Use native `<details>`. It provides toggle, keyboard support and accessibility for free.
+Use native `<details>`. It provides toggle, keyboard support and accessibility for free. On a landing page the FAQ sits right before the form, to clear objections.
+
+```jsx
+const FAQ = [{ q: '...', a: '...' }]
+return (
+  <section className="section faq" id="faq">
+    <h2>{TITLE}</h2>
+    {FAQ.map((f) => (
+      <details className="faq__item" key={f.q}>
+        <summary>{f.q}<span className="faq__icon" aria-hidden="true">+</span></summary>
+        <p>{f.a}</p>
+      </details>
+    ))}
+  </section>
+)
+```
 
 ```css
+.faq__item { border-bottom: 1px solid var(--hair); padding: 18px 0; }
 .faq__item summary { cursor: pointer; list-style: none; display: flex;
-  justify-content: space-between; align-items: center; }
+  justify-content: space-between; align-items: center; font-family: var(--serif); font-size: 1.15rem; }
 .faq__item summary::-webkit-details-marker { display: none; }
-.faq__item .faq__icon { transition: transform .3s; }
+.faq__item .faq__icon { transition: transform .3s; color: var(--accent); }
 .faq__item[open] .faq__icon { transform: rotate(45deg); }
+.faq__item p { margin: 14px 0 0; color: var(--fg-dim); max-width: 70ch; }
 ```
 
 Native `<details>` cannot animate its own height. If height animation is required, drive the inner content with GSAP rather than replacing the element with a custom widget.

package/framework/templates/.idea/morph-templates.xml

@@ -0,0 +1,92 @@
+<templateSet group="MORPH Templates">
+  <template name="morph-pascal" value="{{pascalCase $FEATURE_NAME$}}" description="Convert to PascalCase (UserAuth)" toReformat="false" toShortenFQNames="true">
+    <variable name="FEATURE_NAME" expression="" defaultValue="&quot;FEATURE_NAME&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-camel" value="{{camelCase $FEATURE_NAME$}}" description="Convert to camelCase (userAuth)" toReformat="false" toShortenFQNames="true">
+    <variable name="FEATURE_NAME" expression="" defaultValue="&quot;FEATURE_NAME&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-snake" value="{{snakeCase $FEATURE_NAME$}}" description="Convert to snake_case (user_auth)" toReformat="false" toShortenFQNames="true">
+    <variable name="FEATURE_NAME" expression="" defaultValue="&quot;FEATURE_NAME&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-title" value="{{titleCase $FEATURE_NAME$}}" description="Convert to Title Case (User Auth)" toReformat="false" toShortenFQNames="true">
+    <variable name="FEATURE_NAME" expression="" defaultValue="&quot;FEATURE_NAME&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-kebab" value="{{kebabCase $FEATURE_NAME$}}" description="Convert to kebab-case (user-auth)" toReformat="false" toShortenFQNames="true">
+    <variable name="FEATURE_NAME" expression="" defaultValue="&quot;FEATURE_NAME&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-if" value="{{#if $CONDITION$}}&#10;  $END$&#10;{{/if}}" description="Handlebars if block" toReformat="false" toShortenFQNames="true">
+    <variable name="CONDITION" expression="" defaultValue="&quot;condition&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-if-else" value="{{#if $CONDITION$}}&#10;  $TRUE_BRANCH$&#10;{{else}}&#10;  $FALSE_BRANCH$&#10;{{/if}}" description="Handlebars if-else block" toReformat="false" toShortenFQNames="true">
+    <variable name="CONDITION" expression="" defaultValue="&quot;condition&quot;" alwaysStopAt="true" />
+    <variable name="TRUE_BRANCH" expression="" defaultValue="&quot;&quot;" alwaysStopAt="true" />
+    <variable name="FALSE_BRANCH" expression="" defaultValue="&quot;&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-each" value="{{#each $ITEMS$}}&#10;  {{this.$PROPERTY$}}&#10;{{/each}}" description="Handlebars each loop" toReformat="false" toShortenFQNames="true">
+    <variable name="ITEMS" expression="" defaultValue="&quot;items&quot;" alwaysStopAt="true" />
+    <variable name="PROPERTY" expression="" defaultValue="&quot;name&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-service" value="namespace {{NAMESPACE}}.Application.Features.{{pascalCase FEATURE_NAME}}.Services;&#10;&#10;public class {{pascalCase FEATURE_NAME}}Service(&#10;    I{{pascalCase FEATURE_NAME}}Repository repository,&#10;    ILogger&lt;{{pascalCase FEATURE_NAME}}Service&gt; logger) : I{{pascalCase FEATURE_NAME}}Service&#10;{&#10;    public async Task&lt;{{pascalCase FEATURE_NAME}}Dto?&gt; GetByIdAsync(int id, CancellationToken cancellationToken = default)&#10;    {&#10;        $END$&#10;    }&#10;}" description="MORPH .NET Service class template" toReformat="false" toShortenFQNames="true">
+    <context>
+      <option name="C_SHARP" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-repository" value="public class {{pascalCase FEATURE_NAME}}Repository(AppDbContext context) : I{{pascalCase FEATURE_NAME}}Repository&#10;{&#10;    private readonly DbSet&lt;{{pascalCase FEATURE_NAME}}&gt; _dbSet = context.Set&lt;{{pascalCase FEATURE_NAME}}&gt;();&#10;&#10;    public async Task&lt;{{pascalCase FEATURE_NAME}}?&gt; GetByIdAsync(int id, CancellationToken cancellationToken = default)&#10;    {&#10;        $END$&#10;    }&#10;}" description="MORPH .NET Repository class template" toReformat="false" toShortenFQNames="true">
+    <context>
+      <option name="C_SHARP" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-component" value="@page &quot;/{{kebabCase FEATURE_NAME}}&quot;&#10;@inject I{{pascalCase FEATURE_NAME}}Service {{pascalCase FEATURE_NAME}}Service&#10;@inject ILogger&lt;{{pascalCase FEATURE_NAME}}Page&gt; Logger&#10;&#10;&lt;PageTitle&gt;{{pascalCase FEATURE_NAME}}&lt;/PageTitle&gt;&#10;&#10;&lt;div class=&quot;container-fluid&quot;&gt;&#10;    $END$&#10;&lt;/div&gt;&#10;&#10;@code {&#10;&#10;}" description="MORPH Blazor component template" toReformat="false" toShortenFQNames="true">
+    <context>
+      <option name="HTML" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-migration" value="public partial class Add{{pascalCase FEATURE_NAME}} : Migration&#10;{&#10;    protected override void Up(MigrationBuilder migrationBuilder)&#10;    {&#10;        migrationBuilder.CreateTable(&#10;            name: &quot;{{pascalCase FEATURE_NAME}}s&quot;,&#10;            columns: table =&gt; new&#10;            {&#10;                Id = table.Column&lt;int&gt;(type: &quot;int&quot;, nullable: false)&#10;                    .Annotation(&quot;SqlServer:Identity&quot;, &quot;1, 1&quot;),&#10;                $END$&#10;            },&#10;            constraints: table =&gt;&#10;            {&#10;                table.PrimaryKey(&quot;PK_{{pascalCase FEATURE_NAME}}s&quot;, x =&gt; x.Id);&#10;            });&#10;    }&#10;&#10;    protected override void Down(MigrationBuilder migrationBuilder)&#10;    {&#10;        migrationBuilder.DropTable(name: &quot;{{pascalCase FEATURE_NAME}}s&quot;);&#10;    }&#10;}" description="MORPH EF Core migration template" toReformat="false" toShortenFQNames="true">
+    <context>
+      <option name="C_SHARP" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-ts-contract" value="export interface {{pascalCase FEATURE_NAME}} {&#10;  id: number;&#10;  $FIELD1$&#10;}&#10;&#10;export interface Create{{pascalCase FEATURE_NAME}}Request {&#10;  $FIELD2$&#10;}&#10;&#10;export interface Update{{pascalCase FEATURE_NAME}}Request {&#10;  $END$&#10;}" description="MORPH TypeScript contract template" toReformat="false" toShortenFQNames="true">
+    <variable name="FIELD1" expression="" defaultValue="&quot;&quot;" alwaysStopAt="true" />
+    <variable name="FIELD2" expression="" defaultValue="&quot;&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="TypeScript" value="true" />
+    </context>
+  </template>
+</templateSet>

package/framework/templates/.vscode/morph-templates.code-snippets

@@ -0,0 +1,186 @@
+{
+  "MORPH Template - PascalCase": {
+    "prefix": "morph-pascal",
+    "body": ["{{pascalCase ${1:FEATURE_NAME}}}"],
+    "description": "Convert to PascalCase (UserAuth)"
+  },
+  "MORPH Template - camelCase": {
+    "prefix": "morph-camel",
+    "body": ["{{camelCase ${1:FEATURE_NAME}}}"],
+    "description": "Convert to camelCase (userAuth)"
+  },
+  "MORPH Template - snake_case": {
+    "prefix": "morph-snake",
+    "body": ["{{snakeCase ${1:FEATURE_NAME}}}"],
+    "description": "Convert to snake_case (user_auth)"
+  },
+  "MORPH Template - Title Case": {
+    "prefix": "morph-title",
+    "body": ["{{titleCase ${1:FEATURE_NAME}}}"],
+    "description": "Convert to Title Case (User Auth)"
+  },
+  "MORPH Template - kebab-case": {
+    "prefix": "morph-kebab",
+    "body": ["{{kebabCase ${1:FEATURE_NAME}}}"],
+    "description": "Convert to kebab-case (user-auth)"
+  },
+  "MORPH Template - UPPER_SNAKE_CASE": {
+    "prefix": "morph-upper-snake",
+    "body": ["{{upperSnakeCase ${1:FEATURE_NAME}}}"],
+    "description": "Convert to UPPER_SNAKE_CASE (USER_AUTH)"
+  },
+  "MORPH Template - Conditional If": {
+    "prefix": "morph-if",
+    "body": [
+      "{{#if ${1:condition}}}",
+      "  $2",
+      "{{/if}}"
+    ],
+    "description": "Handlebars if block"
+  },
+  "MORPH Template - Conditional If-Else": {
+    "prefix": "morph-if-else",
+    "body": [
+      "{{#if ${1:condition}}}",
+      "  $2",
+      "{{else}}",
+      "  $3",
+      "{{/if}}"
+    ],
+    "description": "Handlebars if-else block"
+  },
+  "MORPH Template - Each Loop": {
+    "prefix": "morph-each",
+    "body": [
+      "{{#each ${1:items}}}",
+      "  {{this.$2}}",
+      "{{/each}}"
+    ],
+    "description": "Handlebars each loop"
+  },
+  "MORPH Template - Unless": {
+    "prefix": "morph-unless",
+    "body": [
+      "{{#unless ${1:condition}}}",
+      "  $2",
+      "{{/unless}}"
+    ],
+    "description": "Handlebars unless block"
+  },
+  "MORPH Template - .NET Service Class": {
+    "prefix": "morph-service",
+    "body": [
+      "namespace {{NAMESPACE}}.Application.Features.{{pascalCase FEATURE_NAME}}.Services;",
+      "",
+      "public class {{pascalCase FEATURE_NAME}}Service(",
+      "    I{{pascalCase FEATURE_NAME}}Repository repository,",
+      "    ILogger<{{pascalCase FEATURE_NAME}}Service> logger) : I{{pascalCase FEATURE_NAME}}Service",
+      "{",
+      "    public async Task<{{pascalCase FEATURE_NAME}}Dto?> GetByIdAsync(int id, CancellationToken cancellationToken = default)",
+      "    {",
+      "        $1",
+      "    }",
+      "}"
+    ],
+    "description": "MORPH .NET Service class template"
+  },
+  "MORPH Template - .NET Repository Class": {
+    "prefix": "morph-repository",
+    "body": [
+      "public class {{pascalCase FEATURE_NAME}}Repository(AppDbContext context) : I{{pascalCase FEATURE_NAME}}Repository",
+      "{",
+      "    private readonly DbSet<{{pascalCase FEATURE_NAME}}> _dbSet = context.Set<{{pascalCase FEATURE_NAME}}>();",
+      "",
+      "    public async Task<{{pascalCase FEATURE_NAME}}?> GetByIdAsync(int id, CancellationToken cancellationToken = default)",
+      "    {",
+      "        $1",
+      "    }",
+      "}"
+    ],
+    "description": "MORPH .NET Repository class template"
+  },
+  "MORPH Template - Blazor Component": {
+    "prefix": "morph-component",
+    "body": [
+      "@page \"/{{kebabCase FEATURE_NAME}}\"",
+      "@inject I{{pascalCase FEATURE_NAME}}Service {{pascalCase FEATURE_NAME}}Service",
+      "@inject ILogger<{{pascalCase FEATURE_NAME}}Page> Logger",
+      "",
+      "<PageTitle>{{pascalCase FEATURE_NAME}}</PageTitle>",
+      "",
+      "<div class=\"container-fluid\">",
+      "    $1",
+      "</div>",
+      "",
+      "@code {",
+      "    $2",
+      "}"
+    ],
+    "description": "MORPH Blazor component template"
+  },
+  "MORPH Template - EF Core Migration": {
+    "prefix": "morph-migration",
+    "body": [
+      "public partial class Add{{pascalCase FEATURE_NAME}} : Migration",
+      "{",
+      "    protected override void Up(MigrationBuilder migrationBuilder)",
+      "    {",
+      "        migrationBuilder.CreateTable(",
+      "            name: \"{{pascalCase FEATURE_NAME}}s\",",
+      "            columns: table => new",
+      "            {",
+      "                Id = table.Column<int>(type: \"int\", nullable: false)",
+      "                    .Annotation(\"SqlServer:Identity\", \"1, 1\"),",
+      "                $1",
+      "            },",
+      "            constraints: table =>",
+      "            {",
+      "                table.PrimaryKey(\"PK_{{pascalCase FEATURE_NAME}}s\", x => x.Id);",
+      "            });",
+      "    }",
+      "",
+      "    protected override void Down(MigrationBuilder migrationBuilder)",
+      "    {",
+      "        migrationBuilder.DropTable(name: \"{{pascalCase FEATURE_NAME}}s\");",
+      "    }",
+      "}"
+    ],
+    "description": "MORPH EF Core migration template"
+  },
+  "MORPH Template - Hangfire Job": {
+    "prefix": "morph-job",
+    "body": [
+      "public class {{pascalCase FEATURE_NAME}}ProcessorJob(",
+      "    I{{pascalCase FEATURE_NAME}}Service service,",
+      "    ILogger<{{pascalCase FEATURE_NAME}}ProcessorJob> logger) : I{{pascalCase FEATURE_NAME}}ProcessorJob",
+      "{",
+      "    [AutomaticRetry(Attempts = 3, DelaysInSeconds = new[] { 60, 300, 900 })]",
+      "    [Queue(\"default\")]",
+      "    [JobDisplayName(\"{{pascalCase FEATURE_NAME}} Processing - ID: {0}\")]",
+      "    public async Task ExecuteAsync(int id, CancellationToken cancellationToken)",
+      "    {",
+      "        $1",
+      "    }",
+      "}"
+    ],
+    "description": "MORPH Hangfire job template"
+  },
+  "MORPH Template - TypeScript Contract": {
+    "prefix": "morph-ts-contract",
+    "body": [
+      "export interface {{pascalCase FEATURE_NAME}} {",
+      "  id: number;",
+      "  $1",
+      "}",
+      "",
+      "export interface Create{{pascalCase FEATURE_NAME}}Request {",
+      "  $2",
+      "}",
+      "",
+      "export interface Update{{pascalCase FEATURE_NAME}}Request {",
+      "  $3",
+      "}"
+    ],
+    "description": "MORPH TypeScript contract template"
+  }
+}