accessibility

package
v1.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: AGPL-3.0 Imports: 41 Imported by: 0

Documentation

Overview

Package accessibility checks emails for the accessibility failures a machine can find (design expansion, M19): images without alt text, links and buttons with no text, text contrast below WCAG 2.2 AA against the nearest background, link text that says nothing, skipped heading levels and text below the workspace's minimum size.

The checks run on the compiled HTML of every language version, the same implementation for the composer (as you edit), Send Readiness, publishing an automation or a transactional template, and the template gallery. An issue found in several versions is listed once with its languages, and points at its MJML element so the composer can show it and fix it.

What a machine can add safely is added when HTML is stored (Finalize): lang and dir from the version's language, and role="presentation" on layout tables MJML missed. The workspace policy decides whether serious issues only warn (the default) or block sends and publishing.

Index

Constants

View Source
const (
	AANormal  = 4.5
	AALarge   = 3.0
	AAANormal = 7.0
	AAALarge  = 4.5
)

Contrast requirements of WCAG 2.2.

View Source
const (
	FindingBlock = "block"
	FindingWarn  = "warn"
	FindingInfo  = "info"
	FindingPass  = "pass"
)

Finding statuses.

View Source
const (
	FixAltText    = "alt_text"
	FixDecorative = "decorative"
	FixLinkText   = "link_text"
	FixColor      = "color"
	FixHeading    = "heading"
	FixTextSize   = "text_size"
)

Fix kinds that FixRequest takes.

View Source
const (
	OwnerCampaign        = "campaign"
	OwnerAutomationEmail = "automation_email"
	OwnerTransactional   = "transactional_template"
)

Owner kinds of language versions (content languages).

View Source
const (
	ActionDecorative = "accessibility_decorative"
	ActionColor      = "accessibility_color"
	ActionOneClick   = "accessibility_one_click"
)

Fix actions Send Readiness offers.

View Source
const (
	KindAltText    = "alt_text"
	KindLinkNoText = "link_no_text"
	KindContrast   = "contrast"
	KindLinkText   = "link_text"
	KindHeading    = "heading"
	KindTextSize   = "text_size"
)

Issue kinds.

View Source
const (
	Serious  = "serious"
	Moderate = "moderate"
)

Severities. Serious issues can block sending when the workspace says so; moderate issues only warn.

View Source
const (
	PolicyWarn  = "warn"
	PolicyBlock = "block"
)

Workspace policy choices for serious issues.

View Source
const (
	DefaultMinTextPx = 12
	MinMinTextPx     = 12
	MaxMinTextPx     = 16
)

Minimum text size bounds (px).

View Source
const DirLTR = "ltr"

DirLTR is the only direction for now: right-to-left languages aren't supported yet.

View Source
const FixTextRole = "text_role"

FixTextRole makes a Text block a paragraph or a heading (the Settings tab's Text role).

Variables

View Source
var ErrCompile = errors.New("the email doesn't compile")

ErrCompile means an MJML version doesn't compile, so it can't be checked.

View Source
var ErrFixTarget = errText(mErrTarget, nil)

ErrFixTarget means the element a fix points at isn't in the email any more.

View Source
var ErrMixedText = errText(mErrMixedText, nil)

ErrMixedText means a Text block holds several paragraphs: a heading gets a Text block of its own.

Functions

func ApplyFix

func ApplyFix(src string, f FixRequest) (string, error)

ApplyFix applies one fix to an MJML document.

func BareURL

func BareURL(text, href string) bool

BareURL reports whether a link's text is an address rather than words: "https://docs.acme.io/migrate-v2", "www.acme.io", "docs.acme.io/flags".

func BaseLanguage

func BaseLanguage(code string) string

BaseLanguage is the base of a BCP 47 code: "es-MX" → "es".

func ColorName

func ColorName(c Color) string

ColorName is "white" or "black" for those two, the hex value otherwise.

func EmailLanguage

func EmailLanguage(ctx context.Context, q store.Querier, wsID uuid.UUID, kind string, id uuid.UUID, version int32) string

EmailLanguage is the language an email's own content (its source) is written in: the source language content languages recorded, otherwise the workspace's default.

func ErrorIn

func ErrorIn(l i18n.Lang, err error) string

ErrorIn writes an error from this package (a fix that can't be applied) in a reader's language, in lower case as Error writes it; other errors keep their words.

func FinalizeStored

func FinalizeStored(ctx context.Context, q store.Querier, wsID uuid.UUID, kind string, id uuid.UUID, version int32, html string) string

FinalizeStored adds lang, dir and the layout tables' role to an email's HTML as it is stored, in the email's source language. Every save of compiled HTML (campaigns, automation emails, transactional templates) goes through it; language versions are finalized in their own language.

func FormatRatio

func FormatRatio(r float64) string

FormatRatio is "2.1:1".

func GallerySummary

func GallerySummary(issues []AccessibilityIssue) string

GallerySummary explains a template's issues in a sentence or two: the serious ones first, then the rest.

func GallerySummaryIn

func GallerySummaryIn(l i18n.Lang, issues []AccessibilityIssue) string

GallerySummaryIn is GallerySummary in a reader's language.

func HasPhrases

func HasPhrases(lang string) bool

HasPhrases reports whether the language has a list of phrases that say nothing.

func IssueCount

func IssueCount(n int, severity string) string

IssueCount is "1 serious issue" or "2 serious issues".

func LanguageList

func LanguageList(codes []string) string

LanguageList is "English, Spanish and German" for the given codes.

func LanguageListIn

func LanguageListIn(l i18n.Lang, codes []string) string

LanguageListIn is "English, Spanish and German" in a reader's language, as a list reads inside a sentence.

func LanguageName

func LanguageName(code string) string

LanguageName is the English name of a language code ("es-MX" → "Spanish").

func LanguageNameIn

func LanguageNameIn(l i18n.Lang, code string) string

LanguageNameIn names a content language in a reader's language: "es" is "Spanish" in English and "Tiếng Tây Ban Nha" in Vietnamese, as the app names it. A language without a name keeps its code.

func Large

func Large(sizePx float64, bold bool) bool

Large reports whether text counts as large: 24 px, or 18.66 px bold.

func LowerStep

func LowerStep(s string) string

LowerStep is "step 3 B" for "Step 3 B", for use inside a sentence.

func Luminance

func Luminance(c Color) float64

Luminance is the WCAG 2.2 relative luminance.

func Needs

func Needs(large bool) float64

Needs is the AA ratio text of this size needs.

func NeedsAAA

func NeedsAAA(large bool) float64

NeedsAAA is the AAA ratio text of this size needs.

func Ratio

func Ratio(a, b Color) float64

Ratio is the WCAG contrast ratio of two opaque colors (1 to 21).

func Register

func Register(h huma.API, s *Service)

Register adds the accessibility operations.

func RoundDown

func RoundDown(r float64) float64

RoundDown rounds a ratio down to one decimal, so 4.49 never shows as 4.5.

func SaysNothing

func SaysNothing(text, lang string) bool

SaysNothing reports whether a link's text is a phrase that doesn't say where the link goes in the given language.

func SeriousSummary

func SeriousSummary(issues []AccessibilityIssue, articles bool) string

SeriousSummary names an email's serious issues in a few words: "the hero image's alt text and the button contrast" (or, without articles, "button contrast").

func SeriousSummaryIn

func SeriousSummaryIn(l i18n.Lang, issues []AccessibilityIssue, articles bool) string

SeriousSummaryIn is SeriousSummary in a reader's language.

func ShortName

func ShortName(is AccessibilityIssue) string

ShortName names an issue inside a sentence: "the hero image's alt text", "the button contrast", "“Click here”", "2 “Read more” links", "a bare URL", "a skipped heading level", "11 px footer text".

func TextIn

func TextIn(l i18n.Lang, t i18n.Text) string

TextIn writes a text this package kept (an issue's title, a fix's summary) in a reader's language. Arguments name sections and languages in that language too: "section" holds a section label (mjml.SectionLabel), an argument ending in "Langs" language codes and one ending in "List" a list of words, both joined the way the language joins a list; "ratio" and "need" are contrast ratios (2.1:1). It returns "" for a message no catalog has.

func WorkspaceLanguage

func WorkspaceLanguage(ctx context.Context, q store.Querier, wsID uuid.UUID) string

WorkspaceLanguage is the language a workspace writes new emails in: its default content language, English when it never chose one.

Types

type AccessibilityCheckRequest

type AccessibilityCheckRequest struct {
	Lang string `json:"lang,omitempty" maxLength:"35" doc:"The language version being edited (the source when empty)"`
	MJML string `json:"mjml,omitempty" maxLength:"2000000"`
	HTML string `json:"html,omitempty" maxLength:"2500000"`
}

AccessibilityCheckRequest is the composer's content to check, unsaved edits included. Lang names the version on the canvas; the other versions are checked as saved.

type AccessibilityColorSuggestion

type AccessibilityColorSuggestion struct {
	Color string  `json:"color" example:"#0F766E"`
	Ratio float64 `json:"ratio" doc:"Contrast ratio, rounded down to one decimal"`
	// Reason: the color of the email's other buttons, the nearest shade that
	// passes AA, or one that passes AAA.
	Reason string `json:"reason" enum:"other_buttons,nearest_aa,aaa"`
}

AccessibilityColorSuggestion is a color that fixes a contrast issue.

type AccessibilityCounts

type AccessibilityCounts struct {
	// Languages are the codes lang was set to, one per version ("en", "es").
	Languages []string `json:"languages"`
	Dir       string   `json:"dir" enum:"ltr"`
	// LayoutTables carry role="presentation"; RoleAdded of them were marked
	// by ReputeCast; DataTables kept their meaning.
	LayoutTables int `json:"layoutTables"`
	RoleAdded    int `json:"roleAdded"`
	DataTables   int `json:"dataTables"`
	Images       int `json:"images"`
	// ImagesOK have alt text or are marked decorative.
	ImagesOK int `json:"imagesOk"`
	Links    int `json:"links"`
	// LinksOK say where they go.
	LinksOK int `json:"linksOk"`
	// OverImage counts texts over a background image, which can't be
	// checked for contrast ("Check it by eye"); they count as no issue.
	OverImage int `json:"overImage"`
}

AccessibilityCounts are the passing checks' numbers.

type AccessibilityElement

type AccessibilityElement struct {
	// Tag is the MJML component ("mj-image") or, inside a text block, the
	// HTML element ("a", "h3").
	Tag  string `json:"tag"`
	Role string `json:"role" enum:"image,linked_image,button,link,text,heading"`
	// Label is the button's label, the link's text in the first language,
	// the heading's text or the image's file name.
	Label string `json:"label,omitempty"`
	// Section is the label of the section it's in ("hero"), when the
	// section has one.
	Section string `json:"section,omitempty"`
	// Index locates an element inside a text block: the nth link or heading
	// of the component, from 0.
	Index int    `json:"index"`
	Href  string `json:"href,omitempty"`
	Src   string `json:"src,omitempty"`
	// Count is the number of elements the issue covers ("h3 × 2").
	Count int `json:"count"`
}

AccessibilityElement is the element an issue is about.

type AccessibilityFixInput

type AccessibilityFixInput struct {
	MJML string `json:"mjml" maxLength:"2000000"`
	Kind string `json:"kind" enum:"alt_text,decorative,link_text,color,heading,text_size,text_role"`
	// Path is the element (mj-body element-index path); Index the nth link
	// or image inside a text or Raw HTML block.
	Path  []int `json:"path" maxItems:"12"`
	Index int   `json:"index,omitempty" minimum:"0"`
	// Value is the alt text, the link text or the color.
	Value string `json:"value,omitempty" maxLength:"500"`
	// Target and From are a color fix's attribute ("background" or "text")
	// and the color it replaces inside the element.
	Target   string                       `json:"target,omitempty" enum:"background,text"`
	From     string                       `json:"from,omitempty" maxLength:"60"`
	Headings []AccessibilityHeadingChange `json:"headings,omitempty" maxItems:"50"`
	ToPx     int                          `json:"toPx,omitempty"`
	// Role is a Text block's new role (Settings › Text role).
	Role string `json:"role,omitempty" enum:"p,h1,h2,h3,h4,h5,h6"`
}

AccessibilityFixInput applies one fix to the composer's MJML.

type AccessibilityFixSpec

type AccessibilityFixSpec struct {
	Kind string `json:"kind" enum:"alt_text,link_text,color,heading,text_size"`
	// OneClick fixes need no words; they apply to every language version.
	OneClick bool `json:"oneClick"`
	// PerLanguage fixes are words, written in each language.
	PerLanguage bool `json:"perLanguage"`
	// Decorative is offered for images that aren't linked.
	Decorative bool `json:"decorative"`
	// Color fixes: the color that changes (Target, From), the one it is
	// compared with (Against), the ratio now and what it needs.
	Target      string                         `json:"target,omitempty" enum:"background,text"`
	From        string                         `json:"from,omitempty"`
	Against     string                         `json:"against,omitempty"`
	Ratio       float64                        `json:"ratio,omitempty"`
	Needs       float64                        `json:"needs,omitempty"`
	Large       bool                           `json:"large,omitempty"`
	Suggestions []AccessibilityColorSuggestion `json:"suggestions"`
	// Heading fixes: each heading's level now and after.
	Headings []AccessibilityHeadingChange `json:"headings"`
	// Text size fixes.
	FromPx float64 `json:"fromPx,omitempty"`
	ToPx   int     `json:"toPx,omitempty"`
	// Subject names what a one-click fix changes, as its preview lists it:
	// "Card titles", "Footer text".
	Subject string `json:"subject,omitempty"`
	// Links are the links a link-text fix changes (links that share their
	// words are one issue).
	Links []AccessibilityLinkTarget `json:"links"`
}

AccessibilityFixSpec says how an issue is fixed.

type AccessibilityFixed

type AccessibilityFixed struct {
	MJML string `json:"mjml"`
}

AccessibilityFixed is the MJML after a fix.

func FixContent

FixContent applies one fix to an email's MJML: the composer's buttons change the email the way Review & send's fixes do. Nothing is saved.

func FixContentIn

FixContentIn is FixContent with its problem in a reader's language.

type AccessibilityGallery

type AccessibilityGallery struct {
	// Language is the language the templates are checked in.
	Language     string                        `json:"language"`
	Templates    []AccessibilityTemplateResult `json:"templates"`
	LastCampaign *AccessibilityTemplateResult  `json:"lastCampaign,omitempty"`
}

AccessibilityGallery is every gallery template's result.

type AccessibilityHeadingChange

type AccessibilityHeadingChange struct {
	Path  []int  `json:"path"`
	Index int    `json:"index" doc:"The nth heading of the text block, from 0"`
	Text  string `json:"text"`
	From  int    `json:"from"`
	To    int    `json:"to"`
}

AccessibilityHeadingChange is one heading a level fix changes.

type AccessibilityImpact

type AccessibilityImpact struct {
	OnSerious string                        `json:"onSerious" enum:"warn,block"`
	Campaigns []AccessibilityImpactCampaign `json:"campaigns"`
	Flows     []AccessibilityImpactFlow     `json:"flows"`
	// Held counts the scheduled campaigns that would be held at their
	// send-time recheck.
	Held int `json:"held"`
}

AccessibilityImpact is what a policy would affect now.

type AccessibilityImpactCampaign

type AccessibilityImpactCampaign struct {
	ID          string     `json:"id"`
	Name        string     `json:"name"`
	Status      string     `json:"status" enum:"draft,approval,approved,scheduled"`
	ScheduledAt *time.Time `json:"scheduledAt,omitempty"`
	Serious     int        `json:"serious"`
	// Summary names the serious issues: "the hero image's alt text and the
	// button contrast".
	Summary string `json:"summary"`
	// Held is true for a scheduled send its send-time recheck would hold.
	Held bool `json:"held"`
}

AccessibilityImpactCampaign is a campaign the Block policy would stop.

type AccessibilityImpactFlow

type AccessibilityImpactFlow struct {
	AutomationID string `json:"automationId"`
	Name         string `json:"name"`
	Version      int    `json:"version"`
	LiveVersion  *int   `json:"liveVersion,omitempty"`
	// Step is how the flow names the step ("step 3 B").
	Step    string `json:"step"`
	Serious int    `json:"serious"`
	Summary string `json:"summary"`
}

AccessibilityImpactFlow is an automation draft whose publishing the Block policy would stop. The live version keeps sending.

type AccessibilityIssue

type AccessibilityIssue struct {
	// ID is stable while the email keeps its structure ("contrast:6-0-0").
	ID       string `json:"id"`
	Kind     string `json:"kind" enum:"alt_text,link_no_text,contrast,link_text,heading,text_size"`
	Severity string `json:"severity" enum:"serious,moderate"`
	// Title and Detail are the finding, in the language the request reads
	// in (English for API clients, MCP agents and Send Readiness).
	Title  string `json:"title"`
	Detail string `json:"detail,omitempty"`
	// Tag is the short label on the canvas ("No alt text").
	Tag string `json:"tag"`
	// Short names the issue inside a sentence: "the hero image's alt text",
	// "“Click here”", "a bare URL", "11 px footer text".
	Short string `json:"short"`
	// Name is what an image, link or button issue is about, as a sentence
	// starts: "The hero image", "A linked image in the footer section".
	Name string `json:"name,omitempty"`
	// Texts are the words above as messages, to write them in another
	// language (AccessibilityReport.In, TextIn).
	Texts     IssueTexts `json:"-"`
	Languages []string   `json:"languages"`
	// Path is the element-index path from mj-body of the (first) element;
	// Paths lists every element the issue covers. Empty for HTML-only emails.
	Path  []int   `json:"path"`
	Paths [][]int `json:"paths"`
	// Location is the element's path as the panel shows it:
	// ["mjml", "mj-body", "mj-section · hero", "mj-image"].
	Location []string                    `json:"location"`
	Element  AccessibilityElement        `json:"element"`
	Fix      AccessibilityFixSpec        `json:"fix"`
	Versions []AccessibilityIssueVersion `json:"versions"`
}

AccessibilityIssue is one finding, listed once with every language it's in.

func (AccessibilityIssue) In

In writes one issue's words in a reader's language.

type AccessibilityIssueVersion

type AccessibilityIssueVersion struct {
	Lang string `json:"lang"`
	// Text is the link's text in this language ("Haz clic aquí").
	Text string `json:"text,omitempty"`
	// Suggestion is the linked page's title, offered when the page is in
	// this language.
	Suggestion string `json:"suggestion,omitempty"`
}

AccessibilityIssueVersion is what an issue looks like in one language.

type AccessibilityLanguage

type AccessibilityLanguage struct {
	Code   string `json:"code" example:"es"`
	Name   string `json:"name" example:"Spanish"`
	Source bool   `json:"source"`
}

AccessibilityLanguage is a language version that was checked.

type AccessibilityLinkTarget

type AccessibilityLinkTarget struct {
	Path  []int  `json:"path"`
	Index int    `json:"index" doc:"The nth link of the text block, from 0"`
	Href  string `json:"href"`
}

AccessibilityLinkTarget is one link of a link-text issue.

type AccessibilityPolicy

type AccessibilityPolicy struct {
	OnSerious string `json:"onSerious" enum:"warn,block"`
	MinTextPx int    `json:"minTextPx" minimum:"12" maximum:"16"`
	// UpdatedBy and UpdatedAt say who changed it last (empty until someone does).
	UpdatedBy string     `json:"updatedBy,omitempty"`
	UpdatedAt *time.Time `json:"updatedAt,omitempty"`
	// CanManage is workspace:manage; Helpers are members who hold it.
	CanManage bool     `json:"canManage"`
	Helpers   []string `json:"helpers"`
}

AccessibilityPolicy is the workspace's policy as Settings › General shows it.

type AccessibilityPolicyInput

type AccessibilityPolicyInput struct {
	OnSerious string `json:"onSerious" enum:"warn,block"`
	MinTextPx int    `json:"minTextPx" minimum:"12" maximum:"16"`
}

AccessibilityPolicyInput changes the policy.

type AccessibilityReport

type AccessibilityReport struct {
	Issues    []AccessibilityIssue    `json:"issues"`
	Serious   int                     `json:"serious"`
	Moderate  int                     `json:"moderate"`
	Languages []AccessibilityLanguage `json:"languages"`
	Counts    AccessibilityCounts     `json:"counts"`
	// Policy is the workspace's: under "block", serious issues block sending.
	Policy     string    `json:"policy" enum:"warn,block"`
	MinTextPx  int       `json:"minTextPx"`
	CheckedAt  time.Time `json:"checkedAt"`
	DurationMs int       `json:"durationMs"`
	// Mode is how the email is written: issues of an HTML-only email have
	// no element path, so its fixes happen in the code.
	Mode string `json:"mode" enum:"mjml,html"`
}

AccessibilityReport is the accessibility of an email, every language version checked together.

func Check

func Check(versions []Version, opts Options) (AccessibilityReport, error)

Check runs every accessibility check on the compiled HTML of each language version and lists each issue once, with its languages.

func (AccessibilityReport) In

In writes a report in a reader's language: its issues' titles, details, tags, short names, names, fix subjects and locations, and its languages' names. Check writes English, and English readers get the report as it is.

func (AccessibilityReport) Summary

func (r AccessibilityReport) Summary() string

Summary is "6 issues: 2 serious, 4 moderate" or "No issues".

func (AccessibilityReport) SummaryIn

func (r AccessibilityReport) SummaryIn(l i18n.Lang) string

SummaryIn is Summary in a reader's language.

type AccessibilityTemplateResult

type AccessibilityTemplateResult struct {
	// ID is the template's ("starter:weekly-digest" or a saved template's id)
	// or, for the last sent campaign, the campaign's.
	ID      string `json:"id"`
	Issues  int    `json:"issues"`
	Serious int    `json:"serious"`
	// Summary explains the issues on the tile: "Serious: the linked logo
	// has no alt text, so its link has no text. Also two “Read more” links."
	Summary string `json:"summary,omitempty"`
}

AccessibilityTemplateResult is a gallery tile's result.

type Additions

type Additions struct {
	// Lang and Dir are the values on <html> and the email's wrapper.
	Lang string
	Dir  string
	// LangAdded is true when lang or dir was missing or different.
	LangAdded bool
	// LayoutTables counts the layout tables that carry role="presentation"
	// after finalizing; RoleAdded how many of them ReputeCast marked.
	LayoutTables int
	RoleAdded    int
	// DataTables counts the tables kept as data tables (header cells, or
	// the Table block).
	DataTables int
}

Additions says what Finalize set on an email's HTML.

func Finalize

func Finalize(src, lang string) (string, Additions)

Finalize adds what a machine can add safely to an email's HTML: lang and dir from the version's language, and role="presentation" on layout tables MJML didn't mark (tables inside Raw HTML blocks, for instance). Data tables keep their meaning: the Table block's table and any table with header cells. Only those attributes change; everything else in the HTML stays byte for byte, and running it again changes nothing.

type CampaignContent

type CampaignContent struct {
	ID     uuid.UUID
	Name   string
	Status string
	MJML   string
	HTML   string
	// Hash fingerprints the content (campaigns.content_hash).
	Hash string
}

CampaignContent is the content of a campaign to check.

type CampaignPath

type CampaignPath struct {
	api.WorkspaceInput
	CampaignID string `path:"campaignId" format:"uuid"`
}

type Color

type Color struct {
	R, G, B uint8
	A       float64
}

Color is an sRGB color with alpha (0 to 1).

func Nearest

func Nearest(from, fixed Color, need float64) (Color, float64, bool)

Nearest returns the color closest to from (same hue and saturation, the lightness moved one percent at a time) that reaches need against fixed, and its ratio. ok is false when no shade of that hue gets there.

func ParseColor

func ParseColor(v string) (Color, bool)

ParseColor reads a CSS color: #RGB, #RGBA, #RRGGBB, #RRGGBBAA, rgb(), rgba(), hsl(), hsla() and the named colors. ok is false for values that aren't a color (inherit, currentColor, a gradient, an image).

func (Color) Hex

func (c Color) Hex() string

Hex is "#RRGGBB" in capitals, as the boards write colors.

func (Color) Opaque

func (c Color) Opaque() bool

Opaque reports whether nothing shows through the color.

func (Color) Over

func (c Color) Over(bg Color) Color

Over composites c onto an opaque background.

type DraftBadge

type DraftBadge struct {
	Status string // ok, warn or bad
	Label  string
}

DraftBadge is a badge of the publish dialog.

type DraftCheck

type DraftCheck struct {
	Badges []DraftBadge
	// Blocked is set when the workspace blocks publishing with serious
	// issues; Blocker says what to fix.
	Blocked bool
	Blocker string
}

DraftCheck is what the publish dialog shows about accessibility.

type DraftEmail

type DraftEmail struct {
	AutomationID uuid.UUID
	Automation   string
	Version      int
	LiveVersion  *int
	// Step is how the flow names the step ("step 3 B").
	Step     string
	Versions []Version
}

DraftEmail is an email of an automation draft.

type DraftSource

type DraftSource func(ctx context.Context, ws *store.Workspace) ([]DraftEmail, error)

DraftSource lists the emails of the workspace's automation drafts.

type DraftStep

type DraftStep struct {
	// Step is how the flow names it ("Step 3 B").
	Step string
	MJML string
	HTML string
}

DraftStep is an email step of an automation version.

type Finding

type Finding struct {
	// ID is the issue's ID, or "ok", "lang_dir", "layout_tables".
	ID string
	// Status is block, warn, info or pass.
	Status string
	Title  string
	Detail string
	Path   []int
	// AltText marks an image without alt text: the editor offers its field.
	AltText bool
}

Finding is one line of a checks list outside Send Readiness (a transactional template's Checks tab): an issue, or a check that passed.

func Findings

func Findings(r AccessibilityReport) []Finding

Findings lists a report as checks: serious issues warn, or block under the Block policy (the live version keeps sending); moderate issues inform; then what passed. They are in English; FindingsIn writes them in a reader's language.

func FindingsIn

func FindingsIn(l i18n.Lang, r AccessibilityReport) []Finding

FindingsIn is Findings in a reader's language.

type FixChange

type FixChange struct {
	// Label is the version label part ("decorative image"); Applied the
	// sentence the page shows ("Marked the hero image as decorative").
	Label   string
	Applied string
	// Summary is what now passes ("Card titles are Heading 2, and footer
	// text is 12 px"); Kinds the fixed issue kinds.
	Summary string
	Kinds   []string
	// LabelText, AppliedTexts and SummaryTexts are the words above as
	// messages (LabelIn, AppliedIn, SummaryIn): Applied and Summary are
	// their items joined as a list.
	LabelText    i18n.Text
	AppliedTexts []i18n.Text
	SummaryTexts []i18n.Text
}

FixChange describes what a fix from Review & send changed.

func (FixChange) AppliedIn

func (c FixChange) AppliedIn(l i18n.Lang) string

AppliedIn is what the fix did, in a reader's language.

func (FixChange) LabelIn

func (c FixChange) LabelIn(l i18n.Lang) string

LabelIn is the version label part in a reader's language.

func (FixChange) SummaryIn

func (c FixChange) SummaryIn(l i18n.Lang) string

SummaryIn is what passes after the fix, in a reader's language.

type FixRecord

type FixRecord struct {
	By        string
	At        time.Time
	Summary   string
	Kinds     []string
	Languages []string
	// SummaryTexts are Summary's messages, one list per fix (SummaryIn);
	// empty for fixes recorded before they were kept.
	SummaryTexts [][]i18n.Text
}

FixRecord is a fix applied from Review & send.

func (FixRecord) SummaryIn

func (f FixRecord) SummaryIn(l i18n.Lang) string

SummaryIn writes the fix's summary in a reader's language; English readers, and fixes recorded before their messages were kept, read the English it was recorded with.

type FixRequest

type FixRequest struct {
	Kind string
	// Path is the element (mj-body element-index path); Index the nth link
	// or image inside a text or Raw HTML block.
	Path  []int
	Index int
	// Value is the alt text, the link text or the color.
	Value string
	// Target says which color changes: "background" or "text"; From is the
	// color it replaces inside the element.
	Target string
	From   string
	// Headings are the level changes of a heading fix.
	Headings []AccessibilityHeadingChange
	// ToPx is the text size of a text-size fix.
	ToPx int
	// Role is a text-role change's element: p, or h1 to h6.
	Role string
}

FixRequest is one fix to apply to an email's MJML. Fixes that need no words (color, heading, text size, decorative) go to every language version; alt text and link text to the version of Lang.

type HTTPTitles

type HTTPTitles struct {
	Client *http.Client
}

HTTPTitles reads titles over HTTP, never from internal addresses.

func NewHTTPTitles

func NewHTTPTitles() *HTTPTitles

NewHTTPTitles returns a fetcher with short timeouts and the SSRF guard.

func (*HTTPTitles) Fetch

func (h *HTTPTitles) Fetch(ctx context.Context, url string) (PageTitle, int, error)

Fetch implements TitleFetcher.

type IssueTexts

type IssueTexts struct {
	Title i18n.Text
	// Detail is one message a sentence.
	Detail []i18n.Text
	Tag    i18n.Text
	Short  i18n.Text
	// Name is what an image, link or button issue is about, as a sentence
	// starts ("The hero image"); zero for the other kinds.
	Name i18n.Text
	// Subject is what a one-click fix changes ("Card titles").
	Subject i18n.Text
}

IssueTexts are an issue's words as messages, kept so they can be written in each reader's language (TextIn); the issue's English fields are written from them.

type Options

type Options struct {
	// Policy is "warn" or "block"; MinTextPx the smallest text size.
	Policy    string
	MinTextPx int
	// Titles are linked pages' titles by URL.
	Titles map[string]PageTitle
	Now    func() time.Time
}

Options are the workspace's settings and what the link check knows.

type PageTitle

type PageTitle struct {
	Title string
	// Lang is the page's language (<html lang>), "" when it doesn't say.
	Lang string
}

PageTitle is what the link check read from a linked page.

func ParseTitle

func ParseTitle(r io.Reader) PageTitle

ParseTitle reads a page's <title> and <html lang>.

type ReadinessFacts

type ReadinessFacts struct {
	// Ran is false when Send Readiness has no accessibility checker: the
	// group is left out and alt text stays in Content.
	Ran bool
	// Checked is false when the checks couldn't run; Problem says why.
	Checked     bool
	Problem     string
	ProblemText i18n.Text
	Report      AccessibilityReport
	// PolicyBy and PolicyAt say who set the policy last, and when.
	PolicyBy string
	PolicyAt *time.Time
	// Fixed is the latest fix applied from Review & send, while the content
	// is still what that fix saved.
	Fixed *FixRecord
}

ReadinessFacts is what Send Readiness reads from the accessibility checks. Its words are English, as a run stores them, with their messages kept beside them (ProblemText, the issues' Texts, the fix's SummaryTexts).

type RiverTitles

type RiverTitles struct {
	Client func() *jobs.Client
}

RiverTitles queues title reads on River.

func (RiverTitles) Enqueue

func (r RiverTitles) Enqueue(ctx context.Context, urls []string) error

Enqueue implements TitleQueue.

type Service

type Service struct {
	Pool  *pgxpool.Pool
	Q     *store.Queries
	Audit *audit.Logger
	Log   *slog.Logger
	Now   func() time.Time
	// Versions lists an email's language versions around the one given
	// (the source until content languages exist). Nil: the email has one.
	Versions VersionSource
	// Language is the workspace's default content language ("en").
	Language func(ctx context.Context, ws *store.Workspace) string
	// Titles enqueues reading the titles of linked pages it doesn't know.
	Titles TitleQueue
	// Drafts lists automation drafts' emails (for the policy's impact).
	Drafts DraftSource
	// contains filtered or unexported fields
}

Service runs the accessibility checks for the workspace's emails, keeps the workspace policy and records the fixes applied from Review & send.

func (*Service) CampaignReport

func (s *Service) CampaignReport(ctx context.Context, ws *store.Workspace, id uuid.UUID) (AccessibilityReport, error)

CampaignReport checks a campaign as it is saved.

func (*Service) CheckCampaign

CheckCampaign checks the composer's current content.

func (*Service) CheckDraft

func (s *Service) CheckDraft(ctx context.Context, ws *store.Workspace, version int, live *int, steps []DraftStep) (DraftCheck, error)

CheckDraft checks the emails of an automation version before it is published: a badge per step with serious issues ("Step 3 B: 1 serious issue, button contrast"), which stop publishing when the workspace blocks on them. The live version keeps sending. Its words are in the request's language.

func (*Service) CheckVersions

func (s *Service) CheckVersions(ctx context.Context, wsID uuid.UUID, versions []Version) (AccessibilityReport, error)

CheckVersions checks language versions of an email outside campaigns (a transactional template, an automation email) with the workspace's policy.

func (*Service) FixMJML

func (s *Service) FixMJML(ctx context.Context, ws *store.Workspace, src, action string, params map[string]string) (string, FixChange, error)

FixMJML applies a Review & send fix to an email's MJML. These fixes need no words, so Send Readiness applies them to every language version alike. The change is in English with its messages kept; an error reads in the request's language.

func (*Service) Gallery

func (s *Service) Gallery(ctx context.Context, ws *store.Workspace, starterIDs []string) (AccessibilityGallery, error)

Gallery checks the starters, the saved templates and the last sent campaign, in the workspace's default language.

func (*Service) Impact

Impact lists the campaigns and automation drafts with serious issues: a Block policy would hold the scheduled ones at their send-time recheck and stop the others until they're fixed.

func (*Service) Policy

Policy returns the policy with who may change it.

func (*Service) ReadinessFacts

func (s *Service) ReadinessFacts(ctx context.Context, ws *store.Workspace, c CampaignContent) ReadinessFacts

ReadinessFacts checks a campaign for Send Readiness.

func (*Service) RecordFix

func (s *Service) RecordFix(ctx context.Context, ws *store.Workspace, p *authz.Principal, campaignID uuid.UUID, campaign, contentHash string, languages []string, changes []FixChange) error

RecordFix keeps the fixes applied from Review & send with the content they saved, and audits them. Their summaries keep their messages, so Send Readiness writes them in each reader's language.

func (*Service) Report

Report checks a campaign's content (all its language versions). Saved content is cached by its hash, so Review & send and the gallery don't compile the same email twice.

func (*Service) Settings

func (s *Service) Settings(ctx context.Context, wsID uuid.UUID) (string, int, error)

Settings returns the policy the checks apply: Warn or Block, the minimum size.

func (*Service) UpdatePolicy

UpdatePolicy saves the policy and records the change.

type TitleArgs

type TitleArgs struct {
	URLs []string `json:"urls"`
}

TitleArgs reads the titles of linked pages.

func (TitleArgs) InsertOpts

func (TitleArgs) InsertOpts() river.InsertOpts

InsertOpts implements river.JobArgsWithInsertOpts.

func (TitleArgs) Kind

func (TitleArgs) Kind() string

Kind implements river.JobArgs.

type TitleFetcher

type TitleFetcher interface {
	Fetch(ctx context.Context, url string) (PageTitle, int, error)
}

TitleFetcher reads a page's title and language.

type TitleQueue

type TitleQueue interface {
	Enqueue(ctx context.Context, urls []string) error
}

TitleQueue asks for linked pages' titles to be read in the background.

type TitleWorker

type TitleWorker struct {
	river.WorkerDefaults[TitleArgs]
	Q       *store.Queries
	Fetcher TitleFetcher
	Now     func() time.Time
}

TitleWorker stores the titles of linked pages.

func (*TitleWorker) Work

func (w *TitleWorker) Work(ctx context.Context, job *river.Job[TitleArgs]) error

Work implements river.Worker.

type Version

type Version struct {
	// Lang is its BCP 47 code ("en", "es").
	Lang string
	// MJML is the source; HTML the compiled email. With MJML the checks
	// compile it themselves, to point every issue at its element.
	MJML string
	HTML string
	// Source marks the version the others are translated from.
	Source bool
}

Version is one language version of an email.

type VersionSource

type VersionSource func(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, current Version) ([]Version, error)

VersionSource returns every language version of a campaign, with the given version in place of its stored content (the composer's unsaved edits).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL