@godxjp/ui 28.9.0 → 28.12.0

package/agent/patterns/transactional-email.json

@@ -0,0 +1,22 @@
+{
+  "aliases": [
+    "email-template",
+    "email-tokens",
+    "blade-email",
+    "html-email"
+  ],
+  "code": "// ───────────────────────────────────────────────────────────────────────\n// WHY a separate export: an email is rendered by Blade/Twig/MJML and by clients that strip\n// <style>, ignore CSS custom properties and block remote images. So NEITHER the React components\n// NOR @godxjp/ui/tokens are reachable — every value must be a LITERAL inline style.\n// @godxjp/ui/email is that bridge. It is React-free and dependency-free, and every value is\n// DERIVED from src/tokens/ (HSL→hex at module load), so it can never drift from the web palette.\n//\n// ❌ style=\"background:#0077c7\"                 // hand-copied hex → drifts the first re-theme\n// ❌ style=\"padding: var(--space-8)\"            // no email client resolves var()\n// ❌ style=\"width: 30rem\"                       // rem is unreliable; use literal px\n// ❌ <img src=\"https://cdn…/logo.png\">          // blocked by default in most clients\n// ❌ an emerald pill with no internal glyph     // that is the INCOMPLETE mark\n// ✅ every value from the token export + the embedded brand mark below\n\nimport {\n  EMAIL_BRAND_MARK,\n  EMAIL_COLORS,\n  EMAIL_CTA,\n  EMAIL_FOOTER,\n  EMAIL_MOBILE,\n  EMAIL_SHELL,\n  EMAIL_TYPOGRAPHY,\n  emailBrandMarkSvg,\n  emailInlineStyle,\n} from \"@godxjp/ui/email\";\n\nconst c = EMAIL_COLORS;\n\n// 1) THE 480px SHELL — a table, not a div: Outlook's Word renderer has no flex/grid.\nconst page = emailInlineStyle({ padding: EMAIL_SHELL.pagePadding, backgroundColor: c.background });\nconst card = emailInlineStyle({\n  width: EMAIL_SHELL.width,               // \"480px\" — EMAIL_SHELL.widthPx (480) for width=\"480\"\n  maxWidth: \"100%\",\n  backgroundColor: c.surface,             // ← --card\n  border: `${EMAIL_SHELL.borderWidth} solid ${c.border}`,\n  borderRadius: EMAIL_SHELL.radius,\n});\nconst body = emailInlineStyle({\n  padding: EMAIL_SHELL.padding,           // content column = EMAIL_SHELL.contentWidth (416px)\n  fontFamily: EMAIL_TYPOGRAPHY.fontFamily,\n  fontSize: EMAIL_TYPOGRAPHY.bodyFontSize,\n  lineHeight: EMAIL_TYPOGRAPHY.bodyLineHeight,\n  color: c.foreground,\n});\n\n// 2) THE BRAND MARK — emerald capsule + internal glyph, embedded, zero network fetch.\n//    EMAIL_BRAND_MARK.svg        inline <svg>            (Apple Mail, iOS, Thunderbird)\n//    EMAIL_BRAND_MARK.dataUri    data: URL for <img src> (no request)\n//    EMAIL_BRAND_MARK.tableHtml  <table> fallback        (renders everywhere)\n//    The header is a LOCKUP: mark (22px) + EMAIL_BRAND_MARK.gap + the wordmark at\n//    EMAIL_BRAND_MARK.wordmarkFontSize/wordmarkFontWeight. The mark is DECORATIVE there —\n//    emailBrandMarkSvg({ label: \"\" }) — so the wordmark carries the name and it is announced once.\nconst mark = emailBrandMarkSvg({ label: \"\" });\n\n// 3) THE CTA — line-height EQUALS height, so the label centres with no flexbox.\nconst ctaCell = emailInlineStyle({\n  height: EMAIL_CTA.height,               // 36px — the canonical box (mirrors --control-height-lg)\n  borderRadius: EMAIL_CTA.radius,\n  backgroundColor: c.primary,\n});\nconst ctaLink = emailInlineStyle({\n  display: \"inline-block\",\n  padding: `0 ${EMAIL_CTA.paddingX}`,\n  lineHeight: EMAIL_CTA.lineHeight,\n  fontSize: EMAIL_CTA.fontSize,\n  fontWeight: EMAIL_CTA.fontWeight,\n  color: c.primaryForeground,\n  textDecoration: \"none\",\n});\n\n// 4) LEGAL FOOTER — quiet type over a hairline; links separated by a fixed-width spacer span\n//    (margins between inline links are dropped by several clients).\nconst footer = emailInlineStyle({\n  borderTop: `${EMAIL_FOOTER.borderWidth} solid ${c.border}`,\n  paddingTop: EMAIL_FOOTER.paddingTop,\n  fontSize: EMAIL_FOOTER.fontSize,\n  lineHeight: EMAIL_FOOTER.lineHeight,\n  color: c.mutedForeground,\n});\nconst linkSpacer = emailInlineStyle({ display: \"inline-block\", width: EMAIL_FOOTER.linkGap });\n\nexport const html = `\n<table role=\"presentation\" border=\"0\" cellpadding=\"0\" cellspacing=\"0\" width=\"100%\">\n  <tr><td align=\"center\" style=\"${page}\">\n    <table role=\"presentation\" border=\"0\" cellpadding=\"0\" cellspacing=\"0\"\n           width=\"${EMAIL_SHELL.widthPx}\" class=\"email-card\" style=\"${card}\">\n      <tr><td class=\"email-body\" style=\"${body}\">\n        ${mark}\n        <h1 class=\"email-heading\">Your subject line</h1>\n        <p>Your body copy.</p>\n        <table role=\"presentation\" border=\"0\" cellpadding=\"0\" cellspacing=\"0\">\n          <tr><td class=\"email-cta\" align=\"center\" style=\"${ctaCell}\">\n            <a class=\"email-cta-link\" href=\"https://your.app/action\" style=\"${ctaLink}\">Continue</a>\n          </td></tr>\n        </table>\n        <table role=\"presentation\" border=\"0\" cellpadding=\"0\" cellspacing=\"0\" width=\"100%\">\n          <tr><td style=\"${footer}\">\n            <p>This mailbox is not monitored.</p>\n            <p><a href=\"#\">Help</a><span style=\"${linkSpacer}\">&#8203;</span><a href=\"#\">Privacy</a></p>\n          </td></tr>\n        </table>\n      </td></tr>\n    </table>\n  </td></tr>\n</table>`;\n\n// 5) MOBILE REFLOW — progressive enhancement ONLY. Every rule below has an inline equivalent\n//    above, so a client that strips <style> still renders the desktop layout, never a broken one.\nexport const mediaQuery = `\n@media (max-width: ${EMAIL_MOBILE.maxWidth}) {\n  .email-card { width: ${EMAIL_MOBILE.width} !important; }\n  .email-body { padding: ${EMAIL_MOBILE.padding} !important; }\n  .email-heading { font-size: ${EMAIL_MOBILE.headingFontSize} !important; }\n  .email-cta, .email-cta-link { width: ${EMAIL_MOBILE.ctaWidth} !important; }\n}`;\n\n// 6) BLADE / TWIG / any non-JS engine — dump the same values once in the build step:\n//    node --input-type=module -e 'import(\"@godxjp/ui/email\").then(m => process.stdout.write(m.EMAIL_TOKENS_JSON))' > resources/design/email-tokens.json\n//    then read the JSON from PHP. Same numbers, same source, no copy-paste.",
+  "name": "transactional-email",
+  "tagline": "Build a transactional HTML email (Blade/Twig/MJML/React) from @godxjp/ui/email — literal hex + px derived from the web tokens, the canonical GoDX brand mark, a bulletproof CTA, legal footer and mobile reflow. NEVER hand-copy hex or hand-draw the logo in a mail template.",
+  "tags": [
+    "email",
+    "transactional",
+    "blade",
+    "laravel",
+    "tokens",
+    "brand",
+    "mark",
+    "mjml",
+    "cta"
+  ]
+}

package/agent/patterns-index.json

@@ -0,0 +1,323 @@
+[
+  {
+    "name": "common-fixes",
+    "tagline": "Fix the most common @godxjp/ui consumer mistakes & visual bugs (StatCard double-border, grey Badge, crushed/empty table headers, washed-out sidebar footer, Inertia layout crash, SSR hydration). Before → after.",
+    "tags": [
+      "fixes",
+      "migration",
+      "bug",
+      "cardstat",
+      "statusbadge",
+      "datatable",
+      "sidebar",
+      "gotcha",
+      "review"
+    ]
+  },
+  {
+    "name": "signup-form",
+    "tagline": "Card-wrapped sign-up form using react-hook-form + zod with FormField/Input and a CardFooter action bar (real @godxjp/ui API).",
+    "tags": [
+      "form",
+      "auth",
+      "sign-up",
+      "zod",
+      "validation",
+      "react-hook-form"
+    ]
+  },
+  {
+    "aliases": [
+      "settings-tabs",
+      "settings-page",
+      "settings-layout"
+    ],
+    "name": "settings-page-responsive",
+    "tagline": "Route-backed settings: persistent desktop local navigation, compact mobile tab strip, deep links + browser history, and bounded form content — NO Card wrapper, NO undefined CSS.",
+    "tags": [
+      "settings",
+      "form",
+      "tabs",
+      "admin",
+      "responsive",
+      "navigation"
+    ]
+  },
+  {
+    "aliases": [
+      "settings-section",
+      "settings-row",
+      "danger-zone",
+      "billing-handoff",
+      "preferences-rows",
+      "account-identity"
+    ],
+    "name": "settings-section-rows",
+    "tagline": "The four canonical settings BLOCKS — identity · preference rows · billing handoff · danger zone — composed from Card + ListRow + Descriptions + StatusBadge + AlertDialog. A COMPOSITION pattern: godx-ui ships no SettingsSection/SettingsRow/DangerZone component and never will.",
+    "tags": [
+      "settings",
+      "account",
+      "billing",
+      "danger",
+      "preferences",
+      "listrow",
+      "card",
+      "admin"
+    ]
+  },
+  {
+    "name": "confirm-destructive",
+    "tagline": "Type-to-confirm destructive dialog — AlertDialogRoot + Input gate + toast (real @godxjp/ui API).",
+    "tags": [
+      "dialog",
+      "confirm",
+      "destructive",
+      "delete"
+    ]
+  },
+  {
+    "name": "deferred-loading",
+    "tagline": "Inertia deferred props with a Skeleton fallback — SkeletonTable while data loads, then DataTable (real @godxjp/ui API).",
+    "tags": [
+      "loading",
+      "skeleton",
+      "deferred",
+      "inertia",
+      "table"
+    ]
+  },
+  {
+    "name": "inertia-list-page",
+    "tagline": "Inertia + @godxjp/ui list page — PageContainer + Toolbar + DataTable + Badge + Pagination (current primitive API).",
+    "tags": [
+      "inertia",
+      "list",
+      "table",
+      "page",
+      "filter",
+      "pagination",
+      "datatable",
+      "crm"
+    ]
+  },
+  {
+    "name": "inertia-detail-page",
+    "tagline": "Inertia detail page — receives {id} prop, Descriptions (compound) + StatCard + EmptyState fallback.",
+    "tags": [
+      "inertia",
+      "detail",
+      "show",
+      "page",
+      "keyvaluegrid",
+      "crm"
+    ]
+  },
+  {
+    "name": "inertia-persistent-layout",
+    "tagline": "Inertia persistent layout (AppShell+Sidebar) — the array-form gotcha + the SSR/Math.random gotcha.",
+    "tags": [
+      "inertia",
+      "layout",
+      "appshell",
+      "sidebar",
+      "ssr",
+      "hydration",
+      "gotcha"
+    ]
+  },
+  {
+    "aliases": [
+      "error-surface",
+      "errorsurface",
+      "403",
+      "404",
+      "500",
+      "503",
+      "exception-page"
+    ],
+    "name": "error-pages",
+    "tagline": "400 / 403 / 404 / 500 / 503 exception pages. USE THE COMPONENT: import { ErrorSurface } from \"@godxjp/ui/layout\". `mode=\"application\"` (400/403/404) is the body you put inside the AppShell the route already renders; `mode=\"system\"` (500/503) owns the page via CenteredShell align=\"center\".",
+    "tags": [
+      "error",
+      "errorsurface",
+      "403",
+      "404",
+      "500",
+      "503",
+      "maintenance",
+      "inertia",
+      "ssr",
+      "layout",
+      "emptystate",
+      "centeredshell"
+    ]
+  },
+  {
+    "name": "badge-coloring",
+    "tagline": "Colour a Badge for localized labels and tiers via tone + icon (escape-hatch props).",
+    "tags": [
+      "statusbadge",
+      "badge",
+      "tone",
+      "color",
+      "status",
+      "tier",
+      "table"
+    ]
+  },
+  {
+    "aliases": [
+      "loading-states",
+      "data-state",
+      "query-states"
+    ],
+    "name": "async-data-state",
+    "tagline": "The full async state machine — ONE primary state at a time: prerequisite, disabled-vs-loading, stale refresh, populated, real-empty, and cause-aware error (401/403/404/422/transient) with correct recovery.",
+    "tags": [
+      "async",
+      "loading",
+      "query",
+      "error",
+      "empty",
+      "prerequisite",
+      "retry",
+      "react-query"
+    ]
+  },
+  {
+    "aliases": [
+      "filter-bar",
+      "table-state",
+      "list-page"
+    ],
+    "name": "data-table-page",
+    "tagline": "Filter (Toolbar) + table surface + bottom pagination driven by a query state machine — pagination shows ONLY for successful multi-page data; filters/page survive a transient retry.",
+    "tags": [
+      "table",
+      "pagination",
+      "filter",
+      "async",
+      "toolbar",
+      "datatable"
+    ]
+  },
+  {
+    "aliases": [
+      "organization-switcher",
+      "workspace-switcher",
+      "received-invitations",
+      "memberships"
+    ],
+    "name": "organization-memberships",
+    "tagline": "Workspace membership list — recognizable identity, current/active state, role, permission-aware Open/Switch/Manage/Leave row actions, page-level Create, and CONDITIONAL invitations (omit when none).",
+    "tags": [
+      "organization",
+      "workspace",
+      "membership",
+      "invitation",
+      "account",
+      "switcher"
+    ]
+  },
+  {
+    "aliases": [
+      "password-recovery",
+      "forgot-password",
+      "reset-password",
+      "mfa-challenge",
+      "two-factor-challenge",
+      "2fa-challenge",
+      "otp-challenge",
+      "passkey-failure",
+      "scr-008"
+    ],
+    "name": "auth-recovery-panels",
+    "tagline": "Signed-OUT password recovery + sign-in MFA challenge panels (SCR-008). There is NO PasswordRecoveryPanel and NO MfaChallengePanel — compose Card + AuthStack + FormField/InputOTP + Button inside AuthShell preset=\"account-recovery\" (the 432px token-owned measure).",
+    "tags": [
+      "auth",
+      "authshell",
+      "recovery",
+      "password",
+      "mfa",
+      "2fa",
+      "otp",
+      "inputotp",
+      "passkey",
+      "layout",
+      "presentation"
+    ]
+  },
+  {
+    "aliases": [
+      "recovery-email",
+      "backup-codes",
+      "security-settings",
+      "recovery-settings"
+    ],
+    "name": "account-recovery-settings",
+    "tagline": "Signed-in recovery: compact method status/action rows (email · phone · backup codes) + a separate password-change destination — capability-aware, risk-appropriate, NO stacked Info Alerts.",
+    "tags": [
+      "account",
+      "recovery",
+      "security",
+      "backup-codes",
+      "password",
+      "settings"
+    ]
+  },
+  {
+    "aliases": [
+      "email-template",
+      "email-tokens",
+      "blade-email",
+      "html-email"
+    ],
+    "name": "transactional-email",
+    "tagline": "Build a transactional HTML email (Blade/Twig/MJML/React) from @godxjp/ui/email — literal hex + px derived from the web tokens, the canonical GoDX brand mark, a bulletproof CTA, legal footer and mobile reflow. NEVER hand-copy hex or hand-draw the logo in a mail template.",
+    "tags": [
+      "email",
+      "transactional",
+      "blade",
+      "laravel",
+      "tokens",
+      "brand",
+      "mark",
+      "mjml",
+      "cta"
+    ]
+  },
+  {
+    "aliases": [
+      "cards-in-page",
+      "page-layout",
+      "stack-cards"
+    ],
+    "name": "page-sections",
+    "tagline": "A page made of several Card sections: PageContainer spaces its direct children by default; group items inside a section with Flex/ResponsiveGrid, never Tailwind gap-*/p-*.",
+    "tags": [
+      "layout",
+      "page",
+      "card",
+      "spacing",
+      "flex",
+      "grid"
+    ]
+  },
+  {
+    "aliases": [
+      "user-chip",
+      "account-menu",
+      "signed-in-user"
+    ],
+    "name": "topbar-account-chip",
+    "tagline": "Signed-in user in a PageContainer `extra` slot: Avatar + name + sign-out as a Flex row of primitives — same control height as the buttons beside it. Never a hand-rolled rounded-full border div.",
+    "tags": [
+      "auth",
+      "topbar",
+      "avatar",
+      "header",
+      "account",
+      "chip"
+    ]
+  }
+]