From aac139b95b95bd2770811fa7475b47d89547360c Mon Sep 17 00:00:00 2001 From: Jacobus Geluk Date: Wed, 18 Nov 2026 13:36:15 +0000 Subject: [PATCH] feat(publication): add callout, term list and compact section presentations Project pages gain three RDF-selected section presentations: a call-to-action band (ga:calloutSection), a term/definition list (ga:termSection) and compact step sections (ga:compactSection). Section action rows mark links internal or external. A publication inventory's dcat:landingPage makes version paths display site-relative. A profile may omit the footer generator credit with ga:generatorCredit false; it stays on by default. The EKGF project theme follows ekgf.org's header, heading, leading and timeline metrics through theme tokens, with the outline GitHub mark. Co-Authored-By: Claude Opus 5.5 --- docs/other/ontology/publication.shacl.ttl | 12 + docs/other/ontology/publication.ttl | 13 ++ docs/usage/project-websites.md | 8 +- src/publication/collect/page_presentation.rs | 9 + .../document/publication_inventory.rs | 1 + .../document/publication_inventory/model.rs | 27 ++- .../document/publication_inventory/page.rs | 19 +- .../render/website/community_footer.html | 2 +- .../render/website/ekgf_project.css | 13 ++ src/publication/render/website/project.css | 63 +++++- .../render/website/project/presentation.rs | 44 ++++ .../render/website/project/sections.rs | 130 +++++++++-- src/publication/render/website/repository.rs | 15 +- src/publication/render/website/shell.rs | 23 +- src/publication/render/website/site.rs | 2 +- .../render/website/site_chrome/footer.rs | 19 +- .../render/website/site_chrome/options.rs | 8 + src/publication/render/website/theme.rs | 14 +- tests/project_section_presentations.rs | 212 ++++++++++++++++++ tests/publication_inventory.rs | 45 +++- 20 files changed, 629 insertions(+), 50 deletions(-) create mode 100644 src/publication/render/website/ekgf_project.css create mode 100644 tests/project_section_presentations.rs diff --git a/docs/other/ontology/publication.shacl.ttl b/docs/other/ontology/publication.shacl.ttl index a4472d28..9d557a04 100644 --- a/docs/other/ontology/publication.shacl.ttl +++ b/docs/other/ontology/publication.shacl.ttl @@ -337,6 +337,18 @@ ga:ProjectCardPresentationShape a sh:NodeShape ; ga:PageResourceSectionShape a sh:NodeShape ; sh:targetSubjectsOf ga:resourceSection ; sh:property [ sh:path ga:resourceSection ; sh:datatype xsd:string ; sh:maxCount 32 ; sh:minLength 1 ; sh:maxLength 128 ; sh:pattern "^[\\p{L}\\p{N}_-]+$" ] . +ga:PageCalloutSectionShape a sh:NodeShape ; sh:targetSubjectsOf ga:calloutSection ; + sh:property [ sh:path ga:calloutSection ; sh:datatype xsd:string ; sh:maxCount 32 ; sh:minLength 1 ; sh:maxLength 128 ; sh:pattern "^[\\p{L}\\p{N}_-]+$" ] . + +ga:PageTermSectionShape a sh:NodeShape ; sh:targetSubjectsOf ga:termSection ; + sh:property [ sh:path ga:termSection ; sh:datatype xsd:string ; sh:maxCount 32 ; sh:minLength 1 ; sh:maxLength 128 ; sh:pattern "^[\\p{L}\\p{N}_-]+$" ] . + +ga:PageCompactSectionShape a sh:NodeShape ; sh:targetSubjectsOf ga:compactSection ; + sh:property [ sh:path ga:compactSection ; sh:datatype xsd:string ; sh:maxCount 32 ; sh:minLength 1 ; sh:maxLength 128 ; sh:pattern "^[\\p{L}\\p{N}_-]+$" ] . + +ga:GeneratorCreditShape a sh:NodeShape ; sh:targetSubjectsOf ga:generatorCredit ; + sh:property [ sh:path ga:generatorCredit ; sh:datatype xsd:boolean ; sh:maxCount 1 ] . + ga:PageHeroShape a sh:NodeShape ; sh:targetSubjectsOf ga:heroKind ; sh:property [ sh:path ga:heroKind ; sh:datatype xsd:string ; sh:maxCount 1 ; sh:in ("landing" "introduction") ] . diff --git a/docs/other/ontology/publication.ttl b/docs/other/ontology/publication.ttl index a942e80b..c6c8c682 100644 --- a/docs/other/ontology/publication.ttl +++ b/docs/other/ontology/publication.ttl @@ -1840,6 +1840,10 @@ ga:timelineStatus a owl:ObjectProperty ; rdfs:label "timeline status"@en ; rdfs: ga:statusLabel a owl:DatatypeProperty ; rdfs:label "status label"@en ; rdfs:isDefinedBy ; skos:definition "Names a timeline status exactly as timeline items write it."@en ; dct:description "Names a timeline status exactly as timeline items write it."@en ; rdfs:domain rdfs:Resource ; rdfs:range xsd:string . ga:eyebrow a owl:DatatypeProperty ; rdfs:label "eyebrow"@en ; rdfs:isDefinedBy ; skos:definition "Supplies the short label shown above the title of a generated page."@en ; dct:description "Supplies the short label shown above the title of a generated page."@en ; rdfs:domain ga:DocumentorUse ; rdfs:range xsd:string . +ga:calloutSection a owl:DatatypeProperty ; rdfs:label "callout section"@en ; rdfs:isDefinedBy ; skos:definition "Selects a level-two heading anchor whose section is presented as a call-to-action band on the theme's accent colour."@en ; dct:description "Selects a level-two heading anchor whose section is presented as a call-to-action band on the theme's accent colour."@en ; rdfs:domain ga:Page ; rdfs:range xsd:string ; skos:scopeNote "The band keeps the section's heading, prose, list and links-only action row. The first actions are solid and a final one of several is outlined."@en . +ga:termSection a owl:DatatypeProperty ; rdfs:label "term section"@en ; rdfs:isDefinedBy ; skos:definition "Selects a level-two heading anchor whose level-three cards are presented as a term/definition list."@en ; dct:description "Selects a level-two heading anchor whose level-three cards are presented as a term/definition list."@en ; rdfs:domain ga:Page ; rdfs:range xsd:string ; skos:scopeNote "Each level-three heading is a term, shown in its card presentation's tone. A following paragraph that is wholly strong text is the term's expansion beneath it; the rest of the card is its definition beside it. A term heading that is one link makes the row that link."@en . +ga:compactSection a owl:DatatypeProperty ; rdfs:label "compact section"@en ; rdfs:isDefinedBy ; skos:definition "Selects a level-two heading anchor for a compact section with a smaller heading; consecutive compact sections read as one continuous section."@en ; dct:description "Selects a level-two heading anchor for a compact section with a smaller heading; consecutive compact sections read as one continuous section."@en ; rdfs:domain ga:Page ; rdfs:range xsd:string ; skos:scopeNote "Suits a sequence of steps. A compact section may also select another presentation."@en . + ga:resourceSection a owl:DatatypeProperty ; rdfs:label "resource section"@en ; rdfs:isDefinedBy ; skos:definition "Selects a level-two heading anchor for a single-column list of resource cards."@en ; dct:description "Selects a level-two heading anchor for a single-column list of resource cards."@en ; rdfs:domain ga:Page ; rdfs:range xsd:string ; skos:scopeNote "Naming the anchor of the page title presents the cards directly after the introduction as this list. A card whose title is one link gains a trailing arrow and acts as that link; a wholly emphasized paragraph in a card is shown as its metadata line."@en . ga:heroKind a owl:DatatypeProperty ; rdfs:label "hero kind"@en ; rdfs:isDefinedBy ; skos:definition "Selects a landing campaign hero or an interior introduction for a project page."@en ; dct:description "Selects a landing campaign hero or an interior introduction for a project page."@en ; rdfs:domain ga:Page ; rdfs:range xsd:string . @@ -3540,6 +3544,15 @@ ga:projectNavigation a owl:DatatypeProperty ; rdfs:domain ga:Profile ; rdfs:range xsd:boolean . +ga:generatorCredit a owl:DatatypeProperty ; + rdfs:label "Generator credit"@en ; + rdfs:isDefinedBy ; + skos:definition "States whether website page footers show the line naming the generating GraphArch build and linking the provenance page; the default is true."@en ; + dct:description "States whether website page footers show the line naming the generating GraphArch build and linking the provenance page; the default is true."@en ; + skos:scopeNote "Use false only when the publisher states provenance elsewhere. The provenance page and the build metadata are still published."@en ; + rdfs:domain ga:Profile ; + rdfs:range xsd:boolean . + ga:siteSearch a owl:DatatypeProperty ; rdfs:label "Website search"@en ; rdfs:isDefinedBy ; diff --git a/docs/usage/project-websites.md b/docs/usage/project-websites.md index dc278211..b789f84e 100644 --- a/docs/usage/project-websites.md +++ b/docs/usage/project-websites.md @@ -183,7 +183,13 @@ timeline_statuses: Planned: {name: circle, tone: muted} ``` -An undeclared status fails the build. A thematic break (`---`) ends the current card, so a following block quote is shown as the section's closing note. A footer link may name a bundled icon with `ga:iconName`, such as `github`. +An undeclared status fails the build. + +Three more section presentations are selected by heading anchor. `callout_sections: [join-us]` presents a section as a call-to-action band on the accent colour, keeping its heading, prose, list and links-only action row; the first actions are solid and a final one of several is outlined. `term_sections: [standards]` presents a section's level-three cards as a term/definition list: each heading is a term in its card presentation's tone, a following wholly strong paragraph is its expansion, and the rest of the card is the definition beside it; a term heading that is one link makes the row that link. `compact_sections: [step-1, step-2]` gives sections a smaller heading and a tighter rhythm, so consecutive compact sections read as one section of steps. A section takes one of the callout, term, feature, resource or timeline presentations; compact combines with any of them. Links in a section's action row are marked as leading to another page or away from the site, as in cards. + +A publication inventory may declare its website root with `dcat:landingPage`. Versions beneath it then show their path relative to that root, such as `/spec/main`, while their links stay relative and correct. + +Website footers end with a line naming the generating GraphArch build and linking the provenance page. A profile may omit that line with `ga:generatorCredit false`; the provenance page and build metadata are still published. A thematic break (`---`) ends the current card, so a following block quote is shown as the section's closing note. A footer link may name a bundled icon with `ga:iconName`, such as `github`. Links to absolute URLs beneath the website target's `ga:thisVersion` or `ga:latestVersion` render relative to the linking page; those locations are used only for canonical, Open Graph and sitemap URLs. diff --git a/src/publication/collect/page_presentation.rs b/src/publication/collect/page_presentation.rs index 665439de..a142eb19 100644 --- a/src/publication/collect/page_presentation.rs +++ b/src/publication/collect/page_presentation.rs @@ -35,6 +35,12 @@ pub(super) struct Hints { #[serde(default)] timeline_sections: Vec, #[serde(default)] + callout_sections: Vec, + #[serde(default)] + term_sections: Vec, + #[serde(default)] + compact_sections: Vec, + #[serde(default)] card_icons: BTreeMap, #[serde(default)] timeline_statuses: BTreeMap, @@ -71,6 +77,9 @@ impl Hints { ("featureSection", &self.feature_sections), ("resourceSection", &self.resource_sections), ("timelineSection", &self.timeline_sections), + ("calloutSection", &self.callout_sections), + ("termSection", &self.term_sections), + ("compactSection", &self.compact_sections), ] { ensure!( anchors.len() <= SECTIONS, diff --git a/src/publication/document/publication_inventory.rs b/src/publication/document/publication_inventory.rs index 357defd5..a812381b 100644 --- a/src/publication/document/publication_inventory.rs +++ b/src/publication/document/publication_inventory.rs @@ -45,6 +45,7 @@ pub(crate) async fn document( job: &job, description: description.as_deref(), versions: &inventory.versions, + site: inventory.site.as_deref(), } .markdown()?; let revision = format!("publication-inventory-v1:{snapshot}"); diff --git a/src/publication/document/publication_inventory/model.rs b/src/publication/document/publication_inventory/model.rs index dd96ec75..5609f38c 100644 --- a/src/publication/document/publication_inventory/model.rs +++ b/src/publication/document/publication_inventory/model.rs @@ -20,6 +20,10 @@ pub(crate) const DCAT: &str = "http://www.w3.org/ns/dcat#"; #[serde(deny_unknown_fields)] pub(crate) struct Inventory { pub observed_at: String, + /// The website root that version paths are displayed beneath. Display + /// only: the route manifest that hosting reads never carries it. + #[serde(skip)] + pub site: Option, // bounded: explicit catalogue limited to 1000 publication records. pub versions: Vec, } @@ -162,6 +166,23 @@ impl Inventory { anyhow::bail!("publication inventory requires observation time") }; chrono::DateTime::parse_from_rfc3339(observed_at.value())?; + let site = match view + .optional_by( + subject, + &NamedNode::new(format!("{DCAT}landingPage"))?, + ) + .await? + { + None => None, + Some(Term::NamedNode(site)) if site.as_str().ends_with('/') => { + Some(site.into_string()) + }, + Some(_) => { + anyhow::bail!( + "publication inventory landingPage must be a directory IRI" + ) + }, + }; let members = view.pattern(&format!("{subject} <{DCT}hasPart> ?version"), 0); let fields = view.pattern("?version ?predicate ?object", 1); @@ -227,7 +248,11 @@ impl Inventory { versions.iter().all(|v| slugs.insert(v.slug.clone())), "publication slugs collide" ); - Ok(Self { observed_at: observed_at.value().into(), versions }) + Ok(Self { + observed_at: observed_at.value().into(), + site, + versions, + }) } } diff --git a/src/publication/document/publication_inventory/page.rs b/src/publication/document/publication_inventory/page.rs index 389be999..2e74a54b 100644 --- a/src/publication/document/publication_inventory/page.rs +++ b/src/publication/document/publication_inventory/page.rs @@ -60,6 +60,8 @@ pub(super) struct VersionPage<'a> { pub job: &'a Job, pub description: Option<&'a str>, pub versions: &'a [Version], + /// The website root; a version beneath it shows its site-relative path. + pub site: Option<&'a str>, } impl VersionPage<'_> { @@ -87,7 +89,7 @@ impl VersionPage<'_> { badge: version.status.clone(), }); } - body.push_str(&Self::card(version)); + body.push_str(&self.card(version)); } let frontmatter = serde_yaml::to_string(&Frontmatter { nav_order: self.job.order, @@ -97,7 +99,7 @@ impl VersionPage<'_> { } /// One version: its linked title, description and location line. - fn card(version: &Version) -> String { + fn card(&self, version: &Version) -> String { let mut card = format!( "### [{}](<{}>)\n\n", text(&version.label), @@ -107,7 +109,7 @@ impl VersionPage<'_> { card.push_str(&format!("{}\n\n", text(description))); } // Double-backtick spans hold any branch name verbatim. - let mut location = format!("`` {} ``", version.location()); + let mut location = format!("`` {} ``", self.location(version)); if version.branch != version.slug { location.push_str(&format!(" · branch `` {} ``", version.branch)); } @@ -120,6 +122,17 @@ impl VersionPage<'_> { } } +impl VersionPage<'_> { + /// Where a version is shown to be served: beneath the website root as a + /// root-relative path, such as `/spec/main`, else its route or URL. + fn location(&self, version: &Version) -> String { + match self.site.and_then(|site| version.url.strip_prefix(site)) { + Some(path) => format!("/{}", path.trim_end_matches('/')), + None => version.location().to_owned(), + } + } +} + /// Escape Markdown syntax in plain text. fn text(value: &str) -> String { let mut output = String::new(); diff --git a/src/publication/render/website/community_footer.html b/src/publication/render/website/community_footer.html index a99c720d..e6aa78d8 100644 --- a/src/publication/render/website/community_footer.html +++ b/src/publication/render/website/community_footer.html @@ -6,5 +6,5 @@ - + diff --git a/src/publication/render/website/ekgf_project.css b/src/publication/render/website/ekgf_project.css new file mode 100644 index 00000000..dd76a18d --- /dev/null +++ b/src/publication/render/website/ekgf_project.css @@ -0,0 +1,13 @@ +/* EKGF project sites follow the ekgf.org product layout metrics. The values + are theme tokens; the rules below only apply them. */ +.theme-ekgf{--project-body-leading:1.5;--project-heading-weight:700;--project-heading-tracking:normal;--project-nav-padding:8px 16px;--project-nav-height:36px;--project-control-size:36px;--project-header-start:max(20px,calc(50vw - 654px));--project-header-end:max(20px,calc(50vw - 616px))} +.theme-ekgf{line-height:var(--project-body-leading)} +.theme-ekgf .project-section h2,.theme-ekgf .project-section-heading h2{font-weight:var(--project-heading-weight);letter-spacing:var(--project-heading-tracking)} +.theme-ekgf .project-section-callout h2{font-weight:600} +.community-menu .ekgf-header-navigation a{padding:var(--project-nav-padding);line-height:20px} +.community-header-row .source-link,.community-header-row .color-scheme-toggle{box-sizing:border-box;min-width:var(--project-control-size);min-height:var(--project-control-size);width:var(--project-control-size);height:var(--project-control-size);padding:8px;display:inline-flex;align-items:center;justify-content:center} +.community-header-row .source-link svg{width:20px;height:20px} +@media(min-width:1151px){.community-header-row{max-width:none;padding-inline:var(--project-header-start) var(--project-header-end)}} +.community-menu>nav{gap:4px} +.community-header-row .site-links{gap:16px} +.community-header-row .source-link svg{fill:none;stroke:currentColor} diff --git a/src/publication/render/website/project.css b/src/publication/render/website/project.css index 04308531..eee76e8f 100644 --- a/src/publication/render/website/project.css +++ b/src/publication/render/website/project.css @@ -113,12 +113,71 @@ html[data-color-scheme="dark"] .project-badge-accent{color:#ff9b4d} .project-section-resources .project-card-linked:hover{background:color-mix(in srgb,var(--accent) 5%,transparent);box-shadow:none} .project-section>.project-container>blockquote{grid-column:1/-1;margin:2rem 0 0;padding:1.5rem;border:1px dashed var(--line);border-radius:.5rem;color:var(--muted);background:none;font-size:.875rem;line-height:1.5} .project-section>.project-container>blockquote p{margin:0} -.project-timeline{list-style:none;margin:0;padding:0 0 0 1.75rem;border-left:1px solid var(--line);display:grid;gap:1.5rem} +.project-timeline{list-style:none;margin:0;padding:0 0 0 2rem;border-left:1px solid var(--line);display:grid;gap:2.5rem} .project-timeline-item{position:relative;margin:0} -.project-timeline-item>.project-card-icon{position:absolute;left:-2.5rem;top:0;width:1.5rem;height:1.5rem;margin:0;padding:.2rem;border-radius:999px;background:var(--paper);border:1px solid currentColor;box-sizing:border-box} +.project-timeline-item>.project-card-icon{position:absolute;left:-2.4rem;top:0;width:2rem;height:2rem;margin:0;padding:.45rem;border-radius:999px;background:var(--paper);border:1px solid currentColor;box-sizing:border-box} .project-timeline-meta{display:flex;align-items:center;gap:.75rem;margin:0 0 .25rem} .project-timeline-meta .project-badge{border:0;background:none;padding:0} .project-timeline-date{font-size:.75rem;color:var(--muted)} .project-timeline-content p.project-timeline-title{font-size:1.125rem;line-height:1.75rem;font-weight:600;color:var(--ink);margin:0 0 .5rem} .project-timeline-content p{color:var(--muted);margin:0} @media(prefers-reduced-motion:reduce){.project-card-arrow{transition:none}} + +/* Section actions mark each link internal or external, as in cards. */ +.project-section-actions a{gap:.5rem;padding:.5rem .75rem;border-radius:.375rem;background:var(--paper);color:var(--ink)} +.project-section-actions svg{width:1rem;height:1rem;flex:none} + +/* Compact sections: consecutive steps read as one section with smaller headings. */ +.project-section-compact:has(+.project-section-compact){border-bottom:0;padding-bottom:0} +.project-section-compact+.project-section-compact{padding-top:4rem} +.project-section-compact h2{font-size:1.5rem;line-height:2rem;font-weight:700} +.project-section-compact .project-section-heading{align-items:center;gap:.75rem;margin-bottom:1rem} +.project-section-compact h2+p,.project-section-compact .project-section-heading+p{margin-top:0} +.project-section-compact p{color:var(--muted);margin-bottom:1.5rem} +.project-section-compact pre{margin:0 0 1.5rem} +.project-section-compact>.project-container>:last-child{margin-bottom:0} + +/* A callout band: the section's content on an accent panel. */ +.project-section-callout>.project-container{max-width:56rem;padding:1.5rem;border-radius:.75rem;background:linear-gradient(135deg,var(--accent),color-mix(in srgb,var(--accent) 75%,#000));color:#fff;box-shadow:0 1px 3px #0000001a,0 1px 2px #0000000f} +.project-section-callout h2{font-size:1.5rem;line-height:2rem;font-weight:600;color:#fff;margin:0 0 .5rem} +.project-section-callout p,.project-section-callout li{color:#ffffffe6} +.project-section-callout p{margin:0} +.project-section-callout ul{list-style:none;margin:1rem 0 0;padding:0;font-size:.875rem;line-height:1.25rem} +.project-section-callout li+li{margin-top:.5rem} +.project-section-callout li::before{content:"•";margin-right:.5rem} +.project-section-callout .project-section-actions{margin-top:1.5rem;gap:1rem} +.project-section-callout .project-section-actions a{height:2.5rem;box-sizing:border-box;padding:0 1rem;border:0;background:#fff;color:var(--accent)} +.project-section-callout .project-section-actions a:hover{background:#ffffffe6;color:var(--accent)} +.project-section-callout .project-section-actions a:last-child:not(:first-child){padding:0 1.5rem;border:1px solid #fff;background:none;color:#fff} +.project-section-callout .project-section-actions a:last-child:not(:first-child)>svg{display:none} +.project-section-callout a:focus-visible{outline-color:#fff} + +/* A term list: each term and its expansion beside the definition. */ +.project-section-terms>.project-container{max-width:64rem} +.project-section-terms .project-section-heading{align-items:center;gap:.75rem;margin-bottom:2.5rem} +.project-section-terms .project-section-heading .project-card-icon{width:1.75rem;height:1.75rem;margin:0} +.project-section-terms h2+p,.project-section-terms .project-section-heading+p{max-width:48rem;font-size:1.125rem;line-height:1.75rem;color:var(--muted);margin-bottom:2.5rem} +.project-term{position:relative;display:flex;gap:1.5rem;align-items:flex-start;padding:1.5rem;margin:0 0 1rem;border:1px solid var(--line);border-radius:.5rem;transition:background-color .15s} +.project-term-name{flex:0 0 10rem;min-width:0} +.project-term-name h3{margin:0!important;font-size:1.5rem!important;line-height:2rem!important;font-weight:900!important;letter-spacing:-.025em!important} +.project-term-primary h3,.project-term-primary h3 a{color:var(--accent)} +.project-term-accent h3,.project-term-accent h3 a{color:#ff6f00} +html[data-color-scheme="dark"] .project-term-accent h3,html[data-color-scheme="dark"] .project-term-accent h3 a{color:#ff9b4d} +.project-term-muted h3{color:var(--muted)} +.project-term h3 a{text-decoration:none} +.project-term h3 a::after{content:"";position:absolute;inset:0;border-radius:inherit} +.project-term:has(h3 a):hover{background:color-mix(in srgb,var(--accent) 5%,transparent)} +.project-term:has(h3 a:focus-visible){outline:2px solid var(--accent);outline-offset:2px} +.project-term h3 a:focus-visible{outline:none} +.project-section-terms p.project-term-expansion{margin:0;font-size:.875rem;line-height:1.25rem;color:var(--muted)} +.project-term-expansion strong{font-weight:400} +.project-term-definition{flex:1;min-width:0;color:var(--muted)} +.project-term-definition p{margin:0 0 .5rem} +.project-term-definition>:last-child{margin-bottom:0} +@media(max-width:760px){.project-term{flex-direction:column;gap:.5rem}.project-term-name{flex:none}} +@media(prefers-reduced-motion:reduce){.project-term{transition:none}} +.project-term-arrow{flex:none;width:1rem;height:1rem;margin-left:auto;color:var(--muted)} +.project-term-arrow svg{display:block;width:100%;height:100%} +.project-term:hover .project-term-arrow{color:var(--accent)} +@media(max-width:760px){.project-term-arrow{position:absolute;top:1.5rem;right:1.5rem}} +.project-section-actions a{flex-direction:row-reverse} diff --git a/src/publication/render/website/project/presentation.rs b/src/publication/render/website/project/presentation.rs index 0bee8b2f..6a1842f3 100644 --- a/src/publication/render/website/project/presentation.rs +++ b/src/publication/render/website/project/presentation.rs @@ -14,6 +14,12 @@ pub(in crate::publication::render::website) struct Presentation { pub resources: Vec, pub icons: BTreeMap, pub timelines: Vec, + /// Sections presented as a call-to-action band. + pub callouts: Vec, + /// Sections whose cards are presented as a term/definition list. + pub terms: Vec, + /// Sections sharing one tighter rhythm with adjacent compact sections. + pub compacts: Vec, pub statuses: BTreeMap, } @@ -176,6 +182,27 @@ impl Presentation { ); value.timelines.push(anchor); } + value.callouts = + anchors(plan, page, "calloutSection", "callout section").await?; + value.terms = + anchors(plan, page, "termSection", "term section").await?; + for anchor in value.callouts.iter().chain(&value.terms) { + ensure!( + !value.features.contains(anchor) && + !value.resources.contains(anchor) && + !value.timelines.contains(anchor), + "section {anchor} has conflicting presentations" + ); + } + if let Some(anchor) = value + .callouts + .iter() + .find(|anchor| value.terms.contains(anchor)) + { + anyhow::bail!("section {anchor} has conflicting presentations") + } + value.compacts = + anchors(plan, page, "compactSection", "compact section").await?; let mut rows = plan.source.objects(page, "timelineStatus").await?; while let Some(row) = rows.next().await? { ensure!( @@ -201,6 +228,23 @@ impl Presentation { Ok(value) } } +/// The heading anchors a page selects for one section presentation. +async fn anchors( + plan: &Plan, + page: &NamedNode, + property: &str, + name: &str, +) -> Result> { + // bounded: at most 32 sections per presentation. + let mut anchors = Vec::new(); + let mut rows = plan.source.objects(page, property).await?; + while let Some(row) = rows.next().await? { + ensure!(anchors.len() < 32, "page exceeds 32 {name}s"); + anchors.push(literal(&row["value"], name)?); + } + Ok(anchors) +} + fn literal(value: &Term, name: &str) -> Result { let Term::Literal(value) = value else { anyhow::bail!("{name} must be a literal") diff --git a/src/publication/render/website/project/sections.rs b/src/publication/render/website/project/sections.rs index 6758f45c..0a01c6bc 100644 --- a/src/publication/render/website/project/sections.rs +++ b/src/publication/render/website/project/sections.rs @@ -49,12 +49,23 @@ enum Kind { Grid, Resources, Timeline, + Terms, } /// The open card; a linked resource card closes with a trailing arrow. struct Card { resource: bool, arrow: bool, + /// A term row; `definition` once its definition column has opened. + term: Option, +} + +/// The open row of a term list. +#[derive(Clone, Copy)] +struct TermRow { + definition: bool, + /// The trailing icon of a term whose heading is one link. + icon: Option<&'static str>, } struct Builder<'a> { @@ -111,6 +122,25 @@ impl Builder<'_> { fn content(&mut self, element: ElementRef) { let html = element.html(); + if let Some(row) = + self.card.as_mut().and_then(|card| card.term.as_mut()) + { + if !row.definition && strong_paragraph(element) { + self.output.push_str(&html.replacen( + "

", + "

", + 1, + )); + return; + } + if !row.definition { + row.definition = true; + self.output + .push_str("

"); + } + self.output.push_str(&html); + return; + } if self.section.is_none() && action_paragraph(element) { self.output.push_str(&html.replacen( "

", @@ -118,7 +148,8 @@ impl Builder<'_> { 1, )); } else if self.card.is_some() && action_paragraph(element) { - self.output.push_str(&card_actions(element)); + self.output + .push_str(&linked_actions(element, "project-card-action")); } else if self.card.is_some() && emphasis_paragraph(element) { self.output.push_str(&html.replacen( "

", @@ -126,10 +157,9 @@ impl Builder<'_> { 1, )); } else if self.section.is_some() && action_paragraph(element) { - self.output.push_str(&html.replacen( - "

", - "

", - 1, + self.output.push_str(&linked_actions( + element, + "project-section-actions", )); } else { self.output.push_str(&html); @@ -151,6 +181,8 @@ impl Builder<'_> { Kind::Resources } else if selected(&self.presentation.timelines) { Kind::Timeline + } else if selected(&self.presentation.terms) { + Kind::Terms } else { Kind::Grid }; @@ -161,9 +193,16 @@ impl Builder<'_> { if selected(&self.presentation.features) { classes.push_str(" project-section-features"); } + if selected(&self.presentation.callouts) { + classes.push_str(" project-section-callout"); + } + if selected(&self.presentation.compacts) { + classes.push_str(" project-section-compact"); + } classes.push_str(match kind { Kind::Resources => " project-section-resources", Kind::Timeline => " project-section-timeline", + Kind::Terms => " project-section-terms", Kind::Grid => "", }); self.output.push_str(&format!( @@ -178,6 +217,28 @@ impl Builder<'_> { let title = self.title.clone(); self.open_section(title.as_deref()); } + let style = heading + .value() + .attr("id") + .and_then(|id| self.presentation.icons.get(id)); + if self.section == Some(Kind::Terms) { + let tone = + style.map_or("primary", |style| style.marker.tone.class()); + self.output.push_str(&format!( + "

{}", + heading.html() + )); + self.card = Some(Card { + resource: false, + arrow: false, + term: Some(TermRow { + definition: false, + icon: title_link(heading).then(|| link_icon(heading)), + }), + }); + return; + } let linked = title_link(heading); let resource = self.section == Some(Kind::Resources); self.output.push_str( @@ -187,10 +248,6 @@ impl Builder<'_> { "
" }, ); - let style = heading - .value() - .attr("id") - .and_then(|id| self.presentation.icons.get(id)); if let Some(style) = style { self.output.push_str(&style.marker.html()); } @@ -206,11 +263,23 @@ impl Builder<'_> { }, None => self.output.push_str(&heading.html()), } - self.card = Some(Card { resource, arrow: resource && linked }); + self.card = + Some(Card { resource, arrow: resource && linked, term: None }); } fn close_card(&mut self) { let Some(card) = self.card.take() else { return }; + if let Some(row) = card.term { + self.output.push_str("
"); + if let Some(icon) = row.icon { + self.output.push_str(&format!( + "{icon}" + )); + } + self.output.push_str("
"); + return; + } if card.resource { self.output.push_str("
"); } @@ -251,20 +320,14 @@ fn title_link(heading: ElementRef) -> bool { } } -/// A card's call-to-action row, each link marked internal or external. -fn card_actions(element: ElementRef) -> String { +/// A call-to-action row in `class`, each link marked internal or external. +fn linked_actions(element: ElementRef, class: &str) -> String { let mut actions = element .html() - .replacen("

", "

", 1); + .replacen("

", &format!("

"), 1); for link in element.child_elements() { - let icon = if link.value().attr("href").is_some_and(|href| { - href.starts_with("https://") || href.starts_with("http://") - }) { - include_str!("icons/external-link.svg") - } else { - include_str!("icons/arrow-right.svg") - }; + let icon = link_icon(link); actions = actions.replace( &link.html(), &link.html().replace("", &format!("{icon}")), @@ -273,6 +336,28 @@ fn card_actions(element: ElementRef) -> String { actions } +/// The icon marking where the first link within `element` leads: away from +/// the site, or to another of its pages. +fn link_icon(element: ElementRef) -> &'static str { + let link = if element.value().name() == "a" { + Some(element) + } else { + element + .child_elements() + .find(|child| child.value().name() == "a") + }; + if link + .and_then(|link| link.value().attr("href")) + .is_some_and(|href| { + href.starts_with("https://") || href.starts_with("http://") + }) + { + include_str!("icons/external-link.svg") + } else { + include_str!("icons/arrow-right.svg") + } +} + /// Whether a paragraph consists only of `element_name` children and /// whitespace, with at least one such child. fn only_children(element: ElementRef<'_>, element_name: &str) -> bool { @@ -297,6 +382,11 @@ fn action_paragraph(element: ElementRef<'_>) -> bool { only_children(element, "a") } +// A wholly strong paragraph names a term's expansion. +fn strong_paragraph(element: ElementRef<'_>) -> bool { + only_children(element, "strong") +} + // A wholly emphasized card paragraph is secondary metadata, such as a path. fn emphasis_paragraph(element: ElementRef<'_>) -> bool { only_children(element, "em") diff --git a/src/publication/render/website/repository.rs b/src/publication/render/website/repository.rs index 9c801c08..26f8f8c6 100644 --- a/src/publication/render/website/repository.rs +++ b/src/publication/render/website/repository.rs @@ -1,11 +1,16 @@ //! Repository identity comes from the pinned project, never the template. use { - super::super::{markup::html_escape as esc, model::Plan}, + super::{ + super::{markup::html_escape as esc, model::Plan}, + theme::Theme, + }, anyhow::{Result, ensure}, oxrdf::Term, }; -pub(super) async fn link(plan: &Plan) -> Result { +/// The header's source link; a project theme draws GitHub with the outline +/// mark its decorative icons share. +pub(super) async fn link(plan: &Plan, theme: Theme) -> Result { let Some(repository) = plan.source.optional(&plan.project, "repository").await? else { @@ -28,7 +33,11 @@ pub(super) async fn link(plan: &Plan) -> Result { ) { ( "View source on GitHub", - include_str!("icons/github.svg"), + if theme.project() { + include_str!("project/icons/github.svg") + } else { + include_str!("icons/github.svg") + }, ) } else { ("View source repository", "Source") diff --git a/src/publication/render/website/shell.rs b/src/publication/render/website/shell.rs index caf14a0c..bef9643b 100644 --- a/src/publication/render/website/shell.rs +++ b/src/publication/render/website/shell.rs @@ -68,7 +68,14 @@ pub(super) fn render( "

Quality issues

" ) }; - let generator_credit = super::super::credit::html(); + let generator_credit = if header.chrome.generator_credit() { + format!( + "{} · Provenance · ", + super::super::credit::html() + ) + } else { + String::new() + }; let organization_identity = header.theme.identity(); let header_links = header.theme.links( repository, @@ -123,14 +130,18 @@ pub(super) fn render( }; let identity_attribution = header.theme.attribution(prefix); let community_footer = match &header.footer { - Some(footer) => footer.html(prefix)?, - None => header.theme.community_footer(prefix), + Some(footer) => { + footer.html(prefix, header.chrome.generator_credit())? + }, + None => { + header + .theme + .community_footer(prefix, header.chrome.generator_credit()) + }, }; let article_footer = if community_footer.is_empty() { format!( - "
{generator_credit} · Provenance · Documentation \ + "" ) } else { diff --git a/src/publication/render/website/site.rs b/src/publication/render/website/site.rs index bfe395c9..e04d17fa 100644 --- a/src/publication/render/website/site.rs +++ b/src/publication/render/website/site.rs @@ -99,7 +99,7 @@ pub(in crate::publication::render) async fn write( .await?; let header = Header { title: title(&plan.source, &plan.project).await?, - repository: repository::link(plan).await?, + repository: repository::link(plan, theme).await?, theme, links: header_links::Links::read(plan).await?, metadata: metadata::Metadata::read(plan).await?, diff --git a/src/publication/render/website/site_chrome/footer.rs b/src/publication/render/website/site_chrome/footer.rs index ca54fd79..5b19d628 100644 --- a/src/publication/render/website/site_chrome/footer.rs +++ b/src/publication/render/website/site_chrome/footer.rs @@ -93,8 +93,9 @@ impl SiteFooter { Ok(Some(Self { groups, notes })) } - /// The footer, closed by the engine's generator credit and provenance. - pub fn html(&self, prefix: &str) -> Result { + /// The footer, closed by the engine's generator credit and provenance + /// unless the profile omits them. + pub fn html(&self, prefix: &str, credit: bool) -> Result { let mut html = String::from( "
", - super::super::super::credit::html() - )); + if credit { + html.push_str(&format!( + "", + super::super::super::credit::html() + )); + } + html.push_str("
"); Ok(html) } } diff --git a/src/publication/render/website/site_chrome/options.rs b/src/publication/render/website/site_chrome/options.rs index 90ac0fb8..1b67ca4f 100644 --- a/src/publication/render/website/site_chrome/options.rs +++ b/src/publication/render/website/site_chrome/options.rs @@ -7,11 +7,13 @@ use { const PROJECT_NAVIGATION: Flag<'static> = Flag::new("projectNavigation", true); const SITE_SEARCH: Flag<'static> = Flag::new("siteSearch", true); +const GENERATOR_CREDIT: Flag<'static> = Flag::new("generatorCredit", true); #[derive(Clone, Copy)] pub(in crate::publication::render::website) struct Options { project_navigation: bool, search: bool, + generator_credit: bool, } impl Options { @@ -21,6 +23,9 @@ impl Options { .read(plan, &plan.profile) .await?, search: SITE_SEARCH.read(plan, &plan.profile).await?, + generator_credit: GENERATOR_CREDIT + .read(plan, &plan.profile) + .await?, }) } @@ -29,4 +34,7 @@ impl Options { /// Whether the site publishes its search index, button and dialog. pub fn search(self) -> bool { self.search } + + /// Whether page footers carry the generator credit and provenance link. + pub fn generator_credit(self) -> bool { self.generator_credit } } diff --git a/src/publication/render/website/theme.rs b/src/publication/render/website/theme.rs index a785ac92..e5d079e3 100644 --- a/src/publication/render/website/theme.rs +++ b/src/publication/render/website/theme.rs @@ -53,6 +53,8 @@ impl Theme { "\n", include_str!("project.css"), "\n", + include_str!("ekgf_project.css"), + "\n", include_str!("color_scheme.css") ) }, @@ -102,7 +104,7 @@ impl Theme { format!("
Menu
{search}{repository}\"Object
") } - pub fn community_footer(self, prefix: &str) -> String { + pub fn community_footer(self, prefix: &str, credit: bool) -> String { if self == Self::Default { return String::new(); } @@ -112,7 +114,15 @@ impl Theme { .replace("{home}", home) .replace( "{generator_credit}", - &super::super::credit::html(), + &if credit { + format!( + "{} · Provenance · ", + super::super::credit::html() + ) + } else { + String::new() + }, ) } diff --git a/tests/project_section_presentations.rs b/tests/project_section_presentations.rs new file mode 100644 index 00000000..a08c0ed7 --- /dev/null +++ b/tests/project_section_presentations.rs @@ -0,0 +1,212 @@ +//! Generic project-section presentations selected by RDF hints: callout +//! bands, term lists and compact step sections, and the profile's opt-out of +//! the generator credit line. +use { + anyhow::Result, + grapharch::publication::{ + dataset::Dataset, + render::{PublishOutcome, Publisher}, + website, + }, +}; + +const DEFINITIONS: &str = r#" +@prefix ga: . +@prefix dct: . + a ga:Project; dct:title "Example"; ga:scope ; ga:target . + a ga:Scope . + a ga:Profile; ga:theme ga:EkgfProjectTheme; ga:siteFooter . + a ga:SiteFooter; ga:footerGroup . + dct:title "Links"; ga:order 1; ga:footerLink . + dct:title "GitHub"; ga:url "https://github.com/example/example"; ga:order 1 . + a ga:Target; dct:title "Site"; ga:scope ; ga:profile ; ga:renderer ; ga:destination "site" . +"#; + +const PAGE: &str = r#"--- +title: Plan +permalink: / +grapharch: + subject: urn:plan + callout_sections: [join-us] + term_sections: [standards] + compact_sections: [one, two] + card_icons: + dcat: {name: layers, tone: primary} + rdf: {name: layers, tone: accent} +--- +# Plan + +The lead. + +## One + +First step. + +[Examples](https://example.org/examples/) [Local](#two) + +## Two + +Second step. + +## Standards + +The stack. + +### [DCAT](https://example.org/dcat/) + +**Data Catalog Vocabulary** + +Catalogues. + +### RDF + +**Resource Description Framework** + +Graphs. + +## Join us + +Come along. + +[Specification](#one) [Repository](https://example.org/repo/) +"#; + +async fn publish(definitions_text: &str, page: &str) -> Result { + let input = tempfile::tempdir()?; + let definitions = input.path().join("project.ttl"); + tokio::fs::write(&definitions, definitions_text).await?; + tokio::fs::write(input.path().join("index.md"), page).await?; + let collected = website::collect( + input.path(), + &definitions, + "urn:project", + "urn:target", + 2, + ) + .await?; + let export = tempfile::tempdir()?; + collected + .dataset + .export(export.path().join("kg.nq")) + .await?; + input.close()?; + let restored = Dataset::memory()?; + restored.import(export.path().join("kg.nq")).await?; + let output = tempfile::tempdir()?; + let PublishOutcome::Published(publication) = Publisher::new(restored) + .with_edition(grapharch::publication::pdf_name::Edition::Default) + .render(&collected.plan, output.path()) + .await? + else { + panic!("publication required") + }; + Ok( + tokio::fs::read_to_string(publication.directory.join("index.html")) + .await?, + ) +} + +fn count(html: &str, selector: &str) -> usize { + scraper::Html::parse_document(html) + .select(&scraper::Selector::parse(selector).unwrap()) + .count() +} + +#[tokio::test] +async fn hints_select_callouts_term_lists_and_compact_sections() -> Result<()> { + let html = publish(DEFINITIONS, PAGE).await?; + // A callout band keeps its heading, prose and action row. + assert_eq!( + count( + &html, + "section.project-section-callout h2#join-us" + ), + 1 + ); + assert_eq!( + count( + &html, + ".project-section-callout p.project-section-actions a" + ), + 2 + ); + // A term list: one row per level-three heading, its strong paragraph as + // the expansion beside the term and the rest as the definition. + assert_eq!( + count(&html, ".project-section-terms .project-term"), + 2 + ); + assert_eq!( + count(&html, ".project-section-terms .project-card"), + 0 + ); + assert_eq!( + count( + &html, + ".project-term-primary > .project-term-name h3#dcat" + ), + 1 + ); + assert_eq!( + count( + &html, + ".project-term-accent > .project-term-name \ + p.project-term-expansion" + ), + 1 + ); + assert_eq!(count(&html, ".project-term-definition > p"), 2); + assert_eq!( + count(&html, ".project-term .project-card-icon"), + 0 + ); + // Compact sections stay ordinary sections, marked for one rhythm. + assert_eq!(count(&html, "section.project-section-compact"), 2); + // Section actions mark each link internal or external. + assert_eq!( + count( + &html, + "#one ~ p.project-section-actions a svg, .project-section-compact \ + p.project-section-actions a svg" + ), + 2 + ); + // The generator credit is on unless the profile turns it off. + assert_eq!(count(&html, ".site-footer-credit"), 1); + Ok(()) +} + +#[tokio::test] +async fn a_profile_can_omit_the_generator_credit() -> Result<()> { + let html = publish( + &DEFINITIONS.replace( + "ga:siteFooter .", + "ga:siteFooter ; ga:generatorCredit false .", + ), + PAGE, + ) + .await?; + assert_eq!(count(&html, ".site-footer-credit"), 0); + assert!(!html.contains("Generated by")); + assert_eq!(count(&html, ".site-footer"), 1); + Ok(()) +} + +#[tokio::test] +async fn a_section_selects_one_presentation() -> Result<()> { + let error = publish( + DEFINITIONS, + &PAGE.replace( + "term_sections: [standards]", + "term_sections: [join-us]", + ), + ) + .await + .unwrap_err(); + assert!( + format!("{error:#}") + .contains("section join-us has conflicting presentations"), + "{error:#}" + ); + Ok(()) +} diff --git a/tests/publication_inventory.rs b/tests/publication_inventory.rs index 68308f66..8f90df4c 100644 --- a/tests/publication_inventory.rs +++ b/tests/publication_inventory.rs @@ -9,6 +9,12 @@ use { /// Render the inventory fixture from a restored KG; return the output root. async fn publish() -> Result<(tempfile::TempDir, std::path::PathBuf)> { + publish_with(|definitions| definitions.to_owned()).await +} + +async fn publish_with( + edit: impl Fn(&str) -> String, +) -> Result<(tempfile::TempDir, std::path::PathBuf)> { let source = tempfile::tempdir()?; tokio::fs::write( source.path().join("index.md"), @@ -21,7 +27,7 @@ async fn publish() -> Result<(tempfile::TempDir, std::path::PathBuf)> { ) .await?; let definitions = source.path().join("project.ttl"); - tokio::fs::write(&definitions,r#" + tokio::fs::write(&definitions, edit(r#" @prefix ga: . @prefix dct: . @prefix doap: . @@ -36,7 +42,7 @@ async fn publish() -> Result<(tempfile::TempDir, std::path::PathBuf)> { a doap:Version; ga:order 2; dct:title "Develop (latest)"; dct:identifier "develop"; doap:branch "develop"; dcat:accessURL ; ga:advertised true . a doap:Version; dct:title "ballot/4"; dct:identifier "ballot-4"; doap:branch "ballot/4"; ga:publicationStatus "Unstandardized pull request preview"; dcat:accessURL ; ga:advertised true . a doap:Version; dct:title "merged-branch"; dct:identifier "merged-branch"; doap:branch "merged-branch"; dcat:accessURL ; ga:advertised false . -"#).await?; +"#)).await?; let collected = website::collect( source.path(), &definitions, @@ -259,3 +265,38 @@ async fn versions_carry_their_own_badge_description_icon_and_location() ); Ok(()) } + +/// A declared website root displays each version beneath it by its +/// site-relative path, while its link still points at the version. +#[tokio::test] +async fn versions_beneath_the_landing_page_show_site_relative_paths() +-> Result<()> { + let (_output, directory) = publish_with(|definitions| { + definitions.replace( + " dct:modified", + " dcat:landingPage ; \ + dct:modified", + ) + }) + .await?; + let html = + tokio::fs::read_to_string(directory.join("spec-versions/index.html")) + .await?; + let document = scraper::Html::parse_document(&html); + let meta = document + .select(&scraper::Selector::parse("p.project-card-meta").unwrap()) + .map(|element| element.text().collect::()) + .collect::>(); + assert_eq!(meta[0], "/spec/main"); + assert_eq!(meta[1], "/spec/develop"); + assert!(meta[2].starts_with("https://preview.example.org/dprod/spec/")); + assert!(html.contains("href=\"../spec/main/\""), "{html}"); + // The route manifest that hosting reads keeps its own fields only. + let manifest = + tokio::fs::read_to_string(directory.join("publication-versions.json")) + .await?; + assert!( + !manifest.contains("landingPage") && !manifest.contains("\"site\"") + ); + Ok(()) +}