@stacksjs/defaults 0.75.136 → 0.75.138

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 413 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 414 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, 413 components, and a multi-section layout.
+The Stacks admin dashboard provides a full-featured admin panel with 100+ route views, 414 components, and a multi-section layout.
 
 ## Key Paths
 - Dashboard components: `storage/framework/defaults/resources/components/Dashboard/`

package/ai/skills/stacks-native/CATALOG.md

@@ -63,7 +63,7 @@ Browser runtime bindings are documented separately in `stacks-auto-imports`.
 | `@stacksjs/mobile` | [`stacks-mobile`](../stacks-mobile/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/index.ts) | 12 |
 | `@stacksjs/model-meta` | [`stacks-models`](../stacks-models/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/model-meta/src/index.ts) | 1 |
 | `@stacksjs/newsletter` | [`stacks-newsletter`](../stacks-newsletter/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/newsletter/src/index.ts) | 7 |
-| `@stacksjs/notifications` | [`stacks-notifications`](../stacks-notifications/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/index.ts) | 11 |
+| `@stacksjs/notifications` | [`stacks-notifications`](../stacks-notifications/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/index.ts) | 12 |
 | `@stacksjs/objects` | [`stacks-objects`](../stacks-objects/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/objects/src/index.ts) | 4 |
 | `@stacksjs/orm` | [`stacks-orm`](../stacks-orm/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/index.ts) | 60 |
 | `@stacksjs/pagination` | [`stacks-pagination`](../stacks-pagination/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/pagination/src/index.ts) | 0 |
@@ -607,11 +607,11 @@ Evidence directory: [7 retained tests](https://github.com/stacksjs/stacks/blob/m
 
 Guidance: [`stacks-notifications`](../stacks-notifications/SKILL.md). Source: [storage/framework/core/notifications/src/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/index.ts).
 
-Declared runtime exports: `BroadcastNotificationDriver`, `DatabaseNotificationDriver`, `bulkSetPreferences`, `emailParagraphs`, `ensureSuccessfulEmailResult`, `ensureSuccessfulNotificationResults`, `filterChannelsByPreferences`, `getNotificationPreferences`, `makeDeliveryRecord`, `notification`, `notificationChannel`, `notificationEmailHtml`, `notificationEmailText`, `notify`, `recordNotificationDelivery`, `resolveDeliveryRecipient`, `setNotificationPreference`, `useBroadcast`, `useChat`, `useDatabase`, `useEmail`, `useNotification`, `usePush`, `useSMS`, `wherePreferenceCategory`.
+Declared runtime exports: `BroadcastNotificationDriver`, `DEFAULT_SMS_OPT_OUT`, `DEFAULT_UNSUBSCRIBE_NOTICE`, `DatabaseNotificationDriver`, `bulkSetPreferences`, `emailParagraphs`, `ensureSuccessfulEmailResult`, `ensureSuccessfulNotificationResults`, `filterChannelsByPreferences`, `getNotificationPreferences`, `listUnsubscribeHeaders`, `makeDeliveryRecord`, `notification`, `notificationChannel`, `notificationEmailHtml`, `notificationEmailMessage`, `notificationEmailText`, `notificationSmsBody`, `notificationUnsubscribeLinks`, `notificationUnsubscribeToken`, `notify`, `parseNotificationUnsubscribeToken`, `recordNotificationDelivery`, `resolveDeliveryRecipient`, `setNotificationPreference`, `unsubscribeTokenFromRequest`, `unsubscribeWithToken`, `useBroadcast`, `useChat`, `useDatabase`, `useEmail`, `useNotification`, `usePush`, `useSMS`, `wherePreferenceCategory`.
 
-Local source modules: [src/delivery.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/delivery.ts), [src/drivers/broadcast.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/drivers/broadcast.ts), [src/drivers/database.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/drivers/database.ts), [src/drivers/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/drivers/index.ts), [src/email-body.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/email-body.ts), [src/preferences.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/preferences.ts).
+Local source modules: [src/delivery.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/delivery.ts), [src/drivers/broadcast.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/drivers/broadcast.ts), [src/drivers/database.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/drivers/database.ts), [src/drivers/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/drivers/index.ts), [src/email-body.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/email-body.ts), [src/preferences.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/preferences.ts), [src/unsubscribe.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/unsubscribe.ts).
 
-Evidence directory: [11 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [12 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/objects
 

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

@@ -78,6 +78,44 @@ missing optional schema compatibility from real persistence failures. Apply
 model-driven migrations before relying on persistence. Inspect channel results
 and transport results rather than assuming a delivery log is provider proof.
 
+## Marketing: unsubscribe links and opt-out lines
+
+Give a marketing notification `payload.unsubscribe`, built per person with
+`notificationUnsubscribeLinks(userId, { notice })`:
+
+```ts
+await notify(
+  { userId, email },
+  { subject, body, unsubscribe: notificationUnsubscribeLinks(userId, { notice: 'You get these because marketing email is on.' }) },
+  ['email'],
+  { category: 'marketing' },
+)
+```
+
+The email's footer then shows the notice, **Unsubscribe** (`url`, default
+`{APP_URL}/unsubscribe?token=`) and **Email preferences** (`/settings`) instead
+of "do not reply"; the text part spells the link out; and the message carries
+`List-Unsubscribe: <oneClickUrl>` plus `List-Unsubscribe-Post:
+List-Unsubscribe=One-Click` (RFC 8058, default
+`{APP_URL}/api/notifications/unsubscribe?token=`). `payload.headers` adds
+other headers. The pure builders are `notificationEmailMessage`,
+`notificationEmailHtml`, `notificationEmailText` and `listUnsubscribeHeaders`.
+
+The token (`notificationUnsubscribeToken`, `parseNotificationUnsubscribeToken`)
+is `base64url("{userId}:{channel}:{category}:{hmac}")` signed with `APP_KEY`,
+which must be set in production. It does not expire. It turns off one
+preference (channel + category), unlike `@stacksjs/email`'s tokens, which
+suppress an address for good. The app owns the page and the route; the route's
+handler is `unsubscribeWithToken(await unsubscribeTokenFromRequest(request))`,
+which reads the query string (one-click form POSTs) before a JSON body, and
+answers 422 when it returns null. Ask before unsubscribing on the page, so a
+link scanner opening the URL changes nothing.
+
+A `marketing` text ends with "Reply STOP to opt out." (`notificationSmsBody`).
+`payload.smsOptOut` replaces the line (and adds it to other categories), and
+`false` leaves it out. STOP only becomes an opt-out the app sees when inbound
+SMS is wired up; see `stacks-sms`.
+
 ## Channel factories
 
 - `useEmail(driver?)` returns a sendable transport. Without a driver it uses

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.136",
+  "version": "0.75.138",
   "description": "Stacks, built into VS Code: stx templates, pickier linting and formatting, encrypted env files, the dev server preview and every buddy command. No other extensions required.",
   "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.136",
+  "version": "0.75.138",
   "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.35",
-    "@stacksjs/mobile": "0.75.136",
+    "@stacksjs/mobile": "0.75.138",
     "@stacksjs/sanitizer": "^0.2.422",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",

package/resources/components/NativeBarButton.stx

@@ -0,0 +1,169 @@
+<script server>
+interface NativeBarButtonProps {
+  /** Where the button goes, such as `/m/messages`. */
+  href: string
+  /** What a screen reader calls the button. */
+  label: string
+  /** The SF Symbol the native bar draws for it (`bubble.left`), drawn here with its Iconify stand-in. */
+  symbol?: string
+  /** An Iconify class for a symbol the stand-ins below don't cover. */
+  icon?: string
+  /** A picture (the account's own photo), drawn round inside the button. */
+  image?: string
+  /** A short title instead of the symbol: an account's initials. */
+  title?: string
+  /** A count on the button. Zero and empty draw nothing. */
+  badge?: string | number
+  /** `count` draws the number, `dot` a red dot (unread notifications). */
+  badgeStyle?: 'count' | 'dot'
+  /** `accent` sits a shade stronger in dark mode (chat); `account` is the default. */
+  variant?: 'accent' | 'account'
+}
+
+const { symbol = '', icon = '' } = defineProps<NativeBarButtonProps>()
+
+// The same names the native bar takes (mobileHeaderOptions-style rightButtons),
+// so one list of buttons describes both. Written out so the stylesheet
+// generator sees every class.
+const standIns: Record<string, string> = {
+  'bubble.left': 'i-lucide-message-square',
+  'bubble.left.and.bubble.right': 'i-lucide-messages-square',
+  'person.crop.circle': 'i-lucide-circle-user-round',
+  'bell': 'i-lucide-bell',
+  'gearshape': 'i-lucide-settings',
+  'plus': 'i-lucide-plus',
+  'magnifyingglass': 'i-lucide-search',
+  'square.and.arrow.up': 'i-lucide-share',
+}
+
+export const glyphClass = `${icon || standIns[symbol] || 'i-lucide-circle-user-round'} native-bar-glyph`
+</script>
+
+<script client>
+import { haptics } from '@stacksjs/mobile'
+
+// A round button at the top right of a phone screen, drawn exactly as the
+// app's native bar draws its buttons (Craft's accountNavigationButton in
+// CraftNativeScreen.swift): a 44pt circle tinted with the accent, a 20pt
+// glyph, a 36pt photo inset in the circle, a count badge or a red dot at its
+// top right. The native screens (Today, Calendar) and the web screens of the
+// same app then show one set of buttons, not two that almost match.
+//
+// Every prop through useReactiveProp, under names of its own: read as plain
+// {{ label }}, a host's client signal of the same name would be shown instead.
+// What shows (picture, title or glyph) is written in the template itself: a
+// derived only the template reads is dropped by the bundler's tree-shake.
+const barHref = useReactiveProp<string>('href', '')
+const barLabel = useReactiveProp<string>('label', '')
+const barImage = useReactiveProp<string>('image', '')
+const barTitle = useReactiveProp<string>('title', '')
+const barBadge = useReactiveProp<string | number>('badge', '')
+const barBadgeStyle = useReactiveProp<string>('badgeStyle', 'count')
+const barVariant = useReactiveProp<string>('variant', 'account')
+
+const barCount = derived(() => {
+  const value = barBadge()
+  return value === '' || value === 0 || value === '0' || value == null ? '' : Number(value) > 99 ? '99+' : String(value)
+})
+const barDot = derived(() => barBadgeStyle() === 'dot')
+const barPhoto = derived(() => (barImage() ? `background-image: url("${String(barImage()).replace(/"/g, '%22')}")` : ''))
+
+function tapBarButton(): void {
+  void haptics.selection()
+}
+</script>
+
+<a :href="barHref()" class="native-bar-button" :class="barVariant() === 'accent' ? 'native-bar-accent' : ''" draggable="false" data-stx-link data-stx-prefetch="eager" @click="tapBarButton()">
+  <span class="native-bar-label">{{ barLabel() }}<span :if="barCount()">, {{ barCount() }} unread</span></span>
+  <span :if="barImage()" aria-hidden="true" class="native-bar-photo" :style="barPhoto()"></span>
+  <span :if="!barImage() && barTitle()" aria-hidden="true" class="native-bar-title">{{ barTitle() }}</span>
+  <!-- :show, not :if: an :if branch is re-rendered in the browser, where the
+       server's glyphClass doesn't exist, and the glyph silently never drew. -->
+  <i :show="!barImage() && !barTitle()" aria-hidden="true" class="{{ glyphClass }}"></i>
+  <span :if="barCount() && !barDot()" aria-hidden="true" class="native-bar-count">{{ barCount() }}</span>
+  <span :if="barCount() && barDot()" aria-hidden="true" class="native-bar-dot"></span>
+</a>
+
+<style>
+  /* The values are Craft's (CraftNativeScreen.swift, accountNavigationButton):
+     keep them in step, or the web and native screens drift apart again. */
+  .native-bar-button {
+    position: relative;
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    width: 2.75rem;
+    height: 2.75rem;
+    border-radius: 999px;
+    color: rgb(28 77 217);
+    background: rgb(38 99 235 / 0.08);
+    text-decoration: none;
+    -webkit-tap-highlight-color: transparent;
+    -webkit-touch-callout: none;
+    transition: transform 120ms ease, opacity 120ms ease;
+  }
+
+  .native-bar-button:active { transform: scale(0.94); opacity: 0.85; }
+
+  .native-bar-label {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip: rect(0 0 0 0);
+    white-space: nowrap;
+  }
+
+  .native-bar-glyph { width: 1.25rem; height: 1.25rem; }
+
+  .native-bar-title {
+    font-size: 0.8125rem;
+    font-weight: 600;
+    letter-spacing: 0.01em;
+  }
+
+  .native-bar-photo {
+    width: 2.25rem;
+    height: 2.25rem;
+    border-radius: 999px;
+    background: center / cover no-repeat;
+  }
+
+  .native-bar-count {
+    position: absolute;
+    top: 0;
+    right: 0;
+    min-width: 1.125rem;
+    height: 1.125rem;
+    padding: 0 0.25rem;
+    border-radius: 999px;
+    color: white;
+    background: rgb(0 122 255);
+    font-size: 0.625rem;
+    font-weight: 700;
+    line-height: 1.125rem;
+    text-align: center;
+  }
+
+  .native-bar-dot {
+    position: absolute;
+    top: 0;
+    right: 0;
+    width: 0.5625rem;
+    height: 0.5625rem;
+    border-radius: 999px;
+    background: rgb(255 59 48);
+  }
+
+  .dark .native-bar-button {
+    color: rgb(148 196 252);
+    background: rgb(38 99 235 / 0.12);
+  }
+
+  .dark .native-bar-accent { background: rgb(38 99 235 / 0.24); }
+
+  @media (prefers-reduced-motion: reduce) {
+    .native-bar-button { transition: none; }
+  }
+</style>

package/resources/components/NativeComponents.test.ts

@@ -39,6 +39,19 @@ describe('Native components', () => {
     expect(button).not.toContain('<img')
   })
 
+  it('draws bar buttons as the native bar does, from the same SF Symbol names', () => {
+    const button = read('NativeBarButton')
+    // Craft's accountNavigationButton: a 44pt tinted circle, a 36pt photo inset.
+    expect(button).toContain('width: 2.75rem;')
+    expect(button).toContain('background: rgb(38 99 235 / 0.08);')
+    expect(button).toContain('width: 2.25rem;')
+    expect(button).toContain("'bubble.left': 'i-lucide-message-square'")
+    expect(button).toContain("useReactiveProp<string | number>('badge', '')")
+    expect(button).toContain('data-stx-link data-stx-prefetch="eager"')
+    // A photo is a background, not an <img>: apps check that every image goes through their delivery.
+    expect(button).not.toContain('<img')
+  })
+
   it('lifts the launch splash once the first screen has painted', () => {
     expect(read('NativeAppShell')).toContain('requestAnimationFrame(() => requestAnimationFrame(() => splash.hide()))')
   })

package/resources/emails/notification.stx

@@ -4,7 +4,8 @@
 // breaks kept, addresses as links) and, when the notification names one, a
 // button to where it happened. Same <EmailLayout> as the other prebaked
 // mailers (stacksjs/stacks#1901); an app's own resources/emails/notification
-// wins over this one.
+// wins over this one. A notification with `unsubscribe` (marketing) says why
+// it came and links to Unsubscribe in the footer instead of "do not reply".
 const appName = props.appName || 'Stacks'
 const primaryColor = props.primaryColor || '#3451b2'
 const subject = props.subject || appName
@@ -12,6 +13,9 @@ const paragraphs = Array.isArray(props.paragraphs) ? props.paragraphs : []
 const actionUrl = props.actionUrl || ''
 const actionLabel = props.actionLabel || 'Open'
 const preheader = props.preheader || ''
+const unsubscribeUrl = props.unsubscribeUrl || ''
+const unsubscribeNotice = props.unsubscribeNotice || 'You are receiving this because these emails are turned on in your settings.'
+const preferencesUrl = props.preferencesUrl || ''
 const year = props.year || new Date().getFullYear()
 </script>
 
@@ -36,7 +40,12 @@ const year = props.year || new Date().getFullYear()
   <template #footer>
     <tr>
       <td style="padding:20px 40px;background-color:#f9fafb;border-top:1px solid #e5e7eb;">
-        <p style="margin:0;color:#6b7280;font-size:12px;text-align:center;">This is an automated message from {{ appName }}. Please do not reply to this email.</p>
+        @if(unsubscribeUrl)
+          <p style="margin:0;color:#6b7280;font-size:12px;text-align:center;">{{ unsubscribeNotice }}</p>
+          <p style="margin:8px 0 0 0;color:#6b7280;font-size:12px;text-align:center;"><a href="{{ unsubscribeUrl }}" style="color:#6b7280;text-decoration:underline;">Unsubscribe</a>@if(preferencesUrl) &middot; <a href="{{ preferencesUrl }}" style="color:#6b7280;text-decoration:underline;">Email preferences</a>@endif</p>
+        @else
+          <p style="margin:0;color:#6b7280;font-size:12px;text-align:center;">This is an automated message from {{ appName }}. Please do not reply to this email.</p>
+        @endif
         <p style="margin:10px 0 0 0;color:#9ca3af;font-size:11px;text-align:center;">&copy; {{ year }} {{ appName }}. All rights reserved.</p>
       </td>
     </tr>