@stacksjs/defaults 0.75.27 → 0.75.28

package/ai/skills/stacks-dashboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-dashboard
-description: Use when building or customizing the Stacks admin dashboard, including dashboard pages, model management views, analytics widgets, commerce dashboards, content management, settings panels, deployment monitoring, job/queue management, or the 406 built-in dashboard components. Covers the dashboard system at storage/framework/defaults/.
+description: Use when building or customizing the Stacks admin dashboard, including dashboard pages, model management views, analytics widgets, commerce dashboards, content management, settings panels, deployment monitoring, job/queue management, or the 407 built-in dashboard components. Covers the dashboard system at storage/framework/defaults/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -8,7 +8,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Dashboard
 
-The Stacks admin dashboard provides a full-featured admin panel with 100+ route views, 406 components, and a multi-section layout.
+The Stacks admin dashboard provides a full-featured admin panel with 100+ route views, 407 components, and a multi-section layout.
 
 ## Key Paths
 - Dashboard components: `storage/framework/defaults/resources/components/Dashboard/`

package/ai/skills/stacks-mail/SKILL.md

@@ -106,6 +106,42 @@ export default {
 }
 ```
 
+## The base design: email components
+
+STX templates build on a bundled component library (`defaults/resources/components/Email`),
+which every bundled template uses and which gives an app a finished look with a few props:
+
+```html
+<EmailLayout
+  title="Your license key"
+  preheader="Shown after the subject in the inbox"
+  brand="Uplink" brandUrl="https://uplink.example" accent="#f59e0b"
+  footer="You are getting this because you bought Uplink."
+>
+  <EmailText size="heading">You have Uplink Monthly.</EmailText>
+  <EmailText>Here is your license key.</EmailText>
+  <EmailCode>UPLK-7RKR-Z2BJ-V6QV-4PUH</EmailCode>
+  <EmailButton href="https://uplink.example/activate" bg="#f59e0b" color="#18181b">Activate</EmailButton>
+  <EmailDivider />
+  <EmailText size="sm">Small print.</EmailText>
+</EmailLayout>
+```
+
+- `<EmailLayout>`: a muted page with one bordered card (a border, not a shadow: Gmail strips
+  shadows), an optional brand header and footer, a hidden `preheader`, and `@media` rules for
+  dark mode and phones on the class hooks the other components carry. Clients that ignore
+  `@media` keep the inline light design.
+- `<EmailText size="heading|lg|md|sm">`, `<EmailButton>`, `<EmailDivider>`, `<EmailSection>`,
+  `<EmailImage>`, `<EmailLink>`.
+- `<EmailCode>`: a key or one-time code, large and monospace, selectable in one tap, wrapping at
+  hyphens on a phone.
+
+A colour passed as a prop is the template's own choice: that element gets no dark-mode hook.
+
+Two stx traps when writing a component or template: never put the literal text of a style
+tag inside a `<script server>` comment (the parser takes it for one), and write head CSS as a
+raw string (`{!! css !!}`) rather than a style element, which stx lifts out as component CSS.
+
 ## Template Locations
 - STX templates: `.stx` files processed by STX engine
 - HTML templates: `.html` files with `{{ }}` variable interpolation

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.27",
+  "version": "0.75.28",
   "description": "A modern Stacks development environment.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.27",
+  "version": "0.75.28",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.27",
-    "@stacksjs/mobile": "^0.75.27",
+    "@stacksjs/mobile": "^0.75.28",
     "@stacksjs/sanitizer": "^0.2.113",
     "ts-qr-codes": "^0.1.8"
   }

package/resources/components/Email/EmailButton.stx

@@ -23,8 +23,8 @@ const padY = props.padY || '14px'
 </script>
 <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin:24px 0;border-collapse:separate;">
   <tr>
-    <td align="center" style="border-radius:6px;background-color:{{ bg }};mso-padding-alt:0;">
-      <a href="{{ href }}" style="display:inline-block;padding:{{ padY }} {{ padX }};color:{{ color }};text-decoration:none;border-radius:6px;font-weight:600;font-size:16px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif;text-align:center;mso-padding-alt:{{ padY }} {{ padX }};">
+    <td align="center" style="border-radius:8px;background-color:{{ bg }};mso-padding-alt:0;">
+      <a href="{{ href }}" style="display:inline-block;padding:{{ padY }} {{ padX }};color:{{ color }};text-decoration:none;border-radius:8px;font-weight:600;font-size:16px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif;text-align:center;mso-padding-alt:{{ padY }} {{ padX }};">
         <slot />
       </a>
     </td>

package/resources/components/Email/EmailCode.stx

@@ -0,0 +1,28 @@
+<script server>
+// A code the reader copies: a license key, a one-time passcode, a recovery
+// code. Large monospace on a tinted block, spaced so O and 0, l and 1 are
+// told apart, and selectable as one unit where the client allows it
+// (`user-select: all`), so a tap or double-click takes the whole code. On a
+// narrow screen it wraps at a hyphen rather than mid-group, and only breaks
+// inside a group when a code has no hyphens to wrap at.
+//
+//   <EmailCode>UPLK-7RKR-Z2BJ-V6QV-4PUH</EmailCode>
+//   <EmailCode size="32px" align="center">482 913</EmailCode>
+interface EmailCodeProps {
+  size?: string
+  align?: 'left' | 'center' | 'right'
+  spacing?: string
+}
+
+const props = defineProps<EmailCodeProps>()
+const size = props.size || '22px'
+const align = props.align || 'center'
+const spacing = props.spacing || '24px'
+</script>
+<table role="presentation" cellpadding="0" cellspacing="0" border="0" style="width:100%;border-collapse:separate;margin:0 0 {{ spacing }} 0;">
+  <tr>
+    <td class="email-code" align="{{ align }}" style="padding:18px 20px;background-color:#f4f4f5;border:1px solid #e4e4e7;border-radius:10px;color:#18181b;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,'Liberation Mono',monospace;font-size:{{ size }};font-weight:600;letter-spacing:0.08em;line-height:1.4;text-align:{{ align }};-webkit-user-select:all;user-select:all;overflow-wrap:anywhere;">
+      <slot />
+    </td>
+  </tr>
+</table>

package/resources/components/Email/EmailDivider.stx

@@ -10,11 +10,11 @@ interface EmailDividerProps {
 }
 
 const props = defineProps<EmailDividerProps>()
-const color = props.color || '#e5e7eb'
+const color = props.color || '#e4e4e7'
 const spacing = props.spacing || '24px'
 </script>
 <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="width:100%;border-collapse:collapse;margin:{{ spacing }} 0;">
   <tr>
-    <td style="height:1px;font-size:1px;line-height:1px;background-color:{{ color }};">&nbsp;</td>
+    <td class="email-divider" style="height:1px;font-size:1px;line-height:1px;background-color:{{ color }};">&nbsp;</td>
   </tr>
 </table>

package/resources/components/Email/EmailLayout.stx

@@ -3,10 +3,25 @@
 //
 // Wraps content in the table-based body that Outlook + Gmail (Android)
 // require, plus the standard meta block (charset / viewport /
-// X-UA-Compatible / colour-scheme). Two-tone bodyBg / contentBg
-// mirrors the bundled templates: muted page colour outside, white
-// card inside. Named slots: head / header / footer. See README for
-// usage examples.
+// X-UA-Compatible / colour-scheme). Named slots: head / header / footer.
+//
+// The base design, which every bundled template inherits:
+//   - a muted page with one white card, a hairline border and a 12px radius.
+//     A border rather than a shadow: Gmail strips box-shadow, so a shadow-only
+//     card lost its edge in the most-used client.
+//   - `preheader`: the line an inbox shows after the subject. Without it the
+//     inbox shows whatever text comes first - usually the brand name again.
+//   - `brand` / `accent` / `brandUrl`: a small brand header (an accent dot and
+//     the name) when the template does not fill the `header` slot itself.
+//   - `footer`: a muted, centred line under the card when the template does
+//     not fill the `footer` slot.
+//   - dark mode and a tighter phone layout, as `@media` rules on the class
+//     hooks below. The CSS inliner leaves `@media` rules in the head
+//     (stacksjs/stacks#1902), so clients that honour them (Apple Mail, iOS,
+//     Outlook for Mac) get them and the rest keep the inline light design.
+//   - those rules are written out raw from here, not as a style element in
+//     the template: stx treats a component's own style element as component
+//     CSS and lifts it out of the head, which lost them.
 //
 // Notes on `defineProps()`: stx fills missing props with an empty
 // string (not `undefined`), so destructure defaults silently no-op
@@ -17,6 +32,11 @@ interface EmailLayoutProps {
   width?: number | string
   bodyBg?: string
   contentBg?: string
+  preheader?: string
+  brand?: string
+  brandUrl?: string
+  accent?: string
+  footer?: string
 }
 
 const props = defineProps<EmailLayoutProps>()
@@ -24,6 +44,32 @@ const title = props.title || ''
 const width = props.width || 600
 const bodyBg = props.bodyBg || '#f4f4f5'
 const contentBg = props.contentBg || '#ffffff'
+const preheader = props.preheader || ''
+const brand = props.brand || ''
+const brandUrl = props.brandUrl || ''
+const accent = props.accent || '#3451b2'
+const footer = props.footer || ''
+const fontStack = '-apple-system,BlinkMacSystemFont,\'Segoe UI\',Roboto,\'Helvetica Neue\',Arial,sans-serif'
+
+const responsiveCss = [
+  '<style>',
+  '@media only screen and (max-width: 620px) {',
+  '  .email-outer { padding: 16px 8px !important; }',
+  '  .email-pad { padding: 28px 24px !important; }',
+  '  .email-brand { padding: 24px 24px 0 !important; }',
+  '  .email-code { font-size: 18px !important; letter-spacing: 0.04em !important; }',
+  '}',
+  '@media (prefers-color-scheme: dark) {',
+  '  .email-body, .email-outer { background-color: #0c0c0e !important; }',
+  '  .email-card { background-color: #141417 !important; border-color: #27272a !important; }',
+  '  .email-heading, .email-brand-name { color: #f4f4f5 !important; }',
+  '  .email-text { color: #d4d4d8 !important; }',
+  '  .email-muted { color: #a1a1aa !important; }',
+  '  .email-code { background-color: #1c1c20 !important; border-color: #27272a !important; color: #f4f4f5 !important; }',
+  '  .email-divider { background-color: #27272a !important; }',
+  '}',
+  '</style>',
+].join('\n')
 </script>
 
 <!DOCTYPE html>
@@ -35,19 +81,42 @@ const contentBg = props.contentBg || '#ffffff'
   <meta name="color-scheme" content="light dark">
   <meta name="supported-color-schemes" content="light dark">
   <title>{{ title }}</title>
+  {!! responsiveCss !!}
   <slot name="head" />
 </head>
-<body style="margin:0;padding:0;background-color:{{ bodyBg }};font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif;line-height:1.6;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%;">
+<body class="email-body" style="margin:0;padding:0;background-color:{{ bodyBg }};font-family:{{ fontStack }};line-height:1.6;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%;">
+  @if(preheader)
+    <div style="display:none;max-height:0;max-width:0;overflow:hidden;opacity:0;mso-hide:all;font-size:1px;line-height:1px;color:{{ bodyBg }};">{{ preheader }}&#8199;&#847;&#8199;&#847;&#8199;&#847;&#8199;&#847;&#8199;&#847;&#8199;&#847;&#8199;&#847;&#8199;&#847;</div>
+  @endif
   <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="width:100%;border-collapse:collapse;background-color:{{ bodyBg }};">
     <tr>
-      <td align="center" style="padding:40px 20px;">
-        <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="max-width:{{ width }}px;width:100%;background-color:{{ contentBg }};border-radius:8px;overflow:hidden;box-shadow:0 1px 3px rgba(0,0,0,0.1);">
+      <td class="email-outer" align="center" style="padding:40px 20px;background-color:{{ bodyBg }};">
+        <table class="email-card" role="presentation" cellpadding="0" cellspacing="0" border="0" style="max-width:{{ width }}px;width:100%;background-color:{{ contentBg }};border:1px solid #e4e4e7;border-radius:12px;overflow:hidden;border-collapse:separate;">
+          @if(brand)
+            <tr>
+              <td class="email-brand" style="padding:32px 40px 0;">
+                <span style="display:inline-block;width:10px;height:10px;border-radius:5px;background-color:{{ accent }};vertical-align:middle;margin-right:10px;"></span>
+                @if(brandUrl)
+                  <a class="email-brand-name" href="{{ brandUrl }}" style="color:#18181b;text-decoration:none;font-size:15px;font-weight:600;letter-spacing:-0.01em;vertical-align:middle;font-family:{{ fontStack }};">{{ brand }}</a>
+                @else
+                  <span class="email-brand-name" style="color:#18181b;font-size:15px;font-weight:600;letter-spacing:-0.01em;vertical-align:middle;font-family:{{ fontStack }};">{{ brand }}</span>
+                @endif
+              </td>
+            </tr>
+          @endif
           <slot name="header" />
-          <tr><td style="padding:40px;">
+          <tr><td class="email-pad" style="padding:32px 40px 40px;">
             <slot />
           </td></tr>
           <slot name="footer" />
         </table>
+        @if(footer)
+          <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="max-width:{{ width }}px;width:100%;border-collapse:collapse;">
+            <tr>
+              <td class="email-muted" style="padding:20px 24px 0;text-align:center;color:#71717a;font-size:12px;line-height:1.6;font-family:{{ fontStack }};">{{ footer }}</td>
+            </tr>
+          </table>
+        @endif
       </td>
     </tr>
   </table>

package/resources/components/Email/EmailText.stx

@@ -14,17 +14,20 @@ interface EmailTextProps {
 const props = defineProps<EmailTextProps>()
 const align = props.align || 'left'
 const size = props.size || 'md'
-const color = props.color || (size === 'heading' ? '#111827' : '#4b5563')
+const color = props.color || (size === 'heading' ? '#18181b' : size === 'sm' ? '#71717a' : '#3f3f46')
+// Hooks for the dark-mode rules in <EmailLayout>. A colour passed as a prop is
+// the template's own choice, so it gets no hook and dark mode leaves it alone.
+const role = props.color ? '' : size === 'heading' ? 'email-heading' : size === 'sm' ? 'email-muted' : 'email-text'
 const spacing = props.spacing || '16px'
 
 const sizeStyles: Record<string, string> = {
   sm: 'font-size:14px;line-height:1.5;',
   md: 'font-size:16px;line-height:1.6;',
   lg: 'font-size:18px;line-height:1.6;',
-  heading: 'font-size:20px;line-height:1.4;font-weight:600;',
+  heading: 'font-size:22px;line-height:1.3;font-weight:600;letter-spacing:-0.01em;',
 }
 const sizeStyle = sizeStyles[size] || sizeStyles.md
 </script>
-<p style="margin:0 0 {{ spacing }} 0;text-align:{{ align }};color:{{ color }};{{ sizeStyle }}">
+<p class="{{ role }}" style="margin:0 0 {{ spacing }} 0;text-align:{{ align }};color:{{ color }};{{ sizeStyle }}">
   <slot />
 </p>