@conduction/nextcloud-vue 2.3.0-beta.1 → 2.3.0-beta.2

package/src/public/components/CnSiteSection.vue

@@ -0,0 +1,120 @@
+<!--
+  - SPDX-FileCopyrightText: 2026 Conduction B.V.
+  - SPDX-License-Identifier: EUPL-1.2
+-->
+
+<template>
+	<section :class="sectionClass" :style="sectionStyle">
+		<div class="container">
+			<slot />
+		</div>
+	</section>
+</template>
+
+<script>
+/**
+ * A full-bleed band with a constrained reading column inside it.
+ *
+ * The band paints edge to edge and the `.container` holds the content at the
+ * design system's column width. That split is not cosmetic: every band in the
+ * NL Design System reference works this way, and a region that emits its
+ * content WITHOUT a container renders body copy hard against the viewport edge
+ * while the navigation above and the footer below start inset.
+ *
+ * PUBLIC-SAFE (see ../index.js): no `@nextcloud/*` import, directly or
+ * transitively. This component must render at a public origin where there is
+ * no Nextcloud, no `OC` global and no translation bundle.
+ */
+export default {
+	name: 'CnSiteSection',
+
+	props: {
+		/**
+		 * Vertical rhythm. `spacing` adds the design system's block padding;
+		 * `hero` is the taller leading band.
+		 */
+		variant: {
+			type: String,
+			default: 'spacing',
+			validator: (v) => ['spacing', 'hero', 'flush'].includes(v),
+		},
+
+		/** Optional background image URL, layered over the band's colour. */
+		backgroundImage: {
+			type: String,
+			default: '',
+		},
+	},
+
+	computed: {
+		/**
+		 * Inline background, when the host supplies an image.
+		 *
+		 * Inline rather than a class because the URL is per-portal CONTENT; a
+		 * stylesheet cannot enumerate them. `background-image` is layered OVER
+		 * the band's own colour rather than replacing it, so a slow or blocked
+		 * image leaves the blue behind it and the text stays readable — an
+		 * image that fails is not allowed to become white-on-white.
+		 *
+		 * @return {object|null} Style bindings, or null.
+		 */
+		sectionStyle() {
+			if (this.backgroundImage === '') {
+				return null
+			}
+
+			return {
+				backgroundImage: `url(${JSON.stringify(this.backgroundImage)})`,
+				backgroundSize: 'cover',
+				backgroundPosition: '50% 50%',
+				backgroundRepeat: 'no-repeat',
+			}
+		},
+
+		/**
+		 * @return {Array} The band's classes.
+		 */
+		sectionClass() {
+			return [
+				'ac-section',
+				this.variant === 'hero' ? 'ac-hero' : null,
+				this.variant === 'spacing' ? 'ac-section--spacing' : null,
+			].filter(Boolean)
+		},
+	},
+}
+</script>
+
+<style scoped>
+/*
+ * ONLY THE TEXT THAT ACTUALLY SITS ON THE BAND IS RECOLOURED.
+ *
+ * `.ac-hero` paints itself `--tilburg-color-blue-500` — dark — and defines no
+ * colour for text placed directly on it, because the reference implementation
+ * never puts any there: its hero holds a white input and a blue button, both
+ * of which bring their own surface. So a heading or paragraph dropped onto the
+ * band inherits the document's dark body colour and lands dark-on-dark.
+ *
+ * THIS RULE WAS FIRST WRITTEN ON `.ac-hero` ITSELF, AND THAT WAS WRONG — it is
+ * the very mistake the rest of this codebase keeps recording. Colour set on an
+ * ancestor cannot know that a descendant paints its own background:
+ * `.ac-search-box` has one, `rgb(230, 246, 255)`, and inheriting white into it
+ * put the label and button at contrast 1.11 and the input's text at 1.0.
+ *
+ * Worse, the "bug" that prompted it was a MEASUREMENT ERROR. The label
+ * computed `rgb(51, 51, 51)`, which was compared against the BAND and scored
+ * 1.06 — but the label does not sit on the band, it sits on the search box's
+ * own light surface, where that colour is entirely correct. The contrast probe
+ * has to walk up to the first ancestor that actually paints a background;
+ * against the nearest NAMED band it reports a failure that is not there, and
+ * then invites a fix that breaks something real.
+ *
+ * So: the hero's own title and subtitle, and nothing else. The system's
+ * inverse token rather than a literal, so a theme with a light hero corrects
+ * both together.
+ */
+.ac-hero__title,
+.ac-hero__subtitle {
+	color: var(--utrecht-document-inverse-color, #ffffff);
+}
+</style>

package/src/public/index.js

@@ -0,0 +1,130 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * PUBLIC-SAFE SITE BLOCKS — the entry point a portal renderer can import when
+ * it runs at a public origin with NO Nextcloud behind it.
+ *
+ * WHY THIS ENTRY POINT EXISTS AT ALL
+ *
+ * nc-vue's main entry is deeply coupled to the Nextcloud runtime: measured on
+ * the published build, 154 files reference `@nextcloud/axios` and 157
+ * reference `@nextcloud/router`. That is correct for an app rendering inside
+ * Nextcloud and fatal for one rendering at `https://portaal.gemeente.nl`,
+ * where there is no `OC` global, no session and no translation bundle.
+ *
+ * WHY THESE ARE NEW COMPONENTS RATHER THAN RE-EXPORTS
+ *
+ * The first plan was to re-export the existing widgets that "looked clean".
+ * A DIRECT import check agreed: 12 of 13 candidates had no `@nextcloud/*`
+ * import in their own file. A TRANSITIVE check — following relative imports
+ * through the tree — inverted that result completely:
+ *
+ *     CnTextWidget        -> @nextcloud/l10n
+ *     CnHeaderWidget      -> @nextcloud/l10n, @nextcloud/router
+ *     CnCardGrid          -> @nextcloud/l10n, @nextcloud/vue,
+ *                            @nextcloud/auth, @nextcloud/event-bus
+ *     ... 12 of 13 unsafe
+ *
+ * Only `CnCard` was clean all the way down. Re-exporting the rest under a
+ * name promising public safety would have shipped a guarantee that the first
+ * public deployment disproved — and it would have failed at RUNTIME, in a
+ * browser, on a government portal, rather than at build time here.
+ *
+ * So these blocks take their strings as PROPS instead of calling `t()`. That
+ * single decision is what keeps them portable: `@nextcloud/l10n` is the
+ * dependency almost every existing widget trips over.
+ *
+ * THE GUARANTEE IS CHECKED, NOT ASSERTED. `npm run check:public-safe` walks
+ * this entry's transitive imports and fails on any `@nextcloud/*`. A comment
+ * claiming purity is worth nothing; the check is in CI.
+ */
+
+import CnSiteCard from './components/CnSiteCard.vue'
+import CnSiteCardGrid from './components/CnSiteCardGrid.vue'
+import CnSiteEmptyState from './components/CnSiteEmptyState.vue'
+import CnSiteHero from './components/CnSiteHero.vue'
+import CnSiteIcon from './components/CnSiteIcon.vue'
+import CnSiteSearch from './components/CnSiteSearch.vue'
+import CnSiteSection from './components/CnSiteSection.vue'
+
+export {
+	CnSiteCard,
+	CnSiteCardGrid,
+	CnSiteEmptyState,
+	CnSiteHero,
+	CnSiteIcon,
+	CnSiteSearch,
+	CnSiteSection,
+}
+
+/**
+ * The block vocabulary, keyed by the `widgetKey` a page body declares.
+ *
+ * A REGISTRY rather than a switch in the consumer. A consumer that resolves
+ * blocks with `if (key === 'markdown')` cannot be extended without editing the
+ * consumer, which is how portaliq ended up supporting exactly one block type
+ * while this library already shipped thirty-four.
+ *
+ * Anything not in this map is UNKNOWN, and a renderer must say so visibly
+ * rather than render nothing — a page silently missing a block looks identical
+ * to a page that was authored empty.
+ *
+ * @type {Record<string, object>}
+ */
+export const siteBlockRegistry = {
+	hero: CnSiteHero,
+	search: CnSiteSearch,
+	section: CnSiteSection,
+	cardGrid: CnSiteCardGrid,
+	card: CnSiteCard,
+	emptyState: CnSiteEmptyState,
+}
+
+/**
+ * Blocks that are FULL-BLEED BANDS and carry their own container.
+ *
+ * A band paints edge to edge and constrains its content itself. Rendering one
+ * inside a host's content column silently shrinks it: measured against the NL
+ * Design System reference, a hero nested in the page container came out
+ * 1168px wide against the design's 1280, and no amount of styling inside the
+ * hero could recover the missing width because the clamp was an ancestor.
+ *
+ * The reference's own structure is the model — `main` is full-bleed and every
+ * `section` brings a `.container` — so a host must ask this before deciding
+ * whether to wrap a block.
+ *
+ * @param {string} key The block key.
+ * @return {boolean} True when the block must NOT be wrapped in a container.
+ */
+export function siteBlockIsBand(key) {
+	return SITE_BAND_BLOCKS.includes(key)
+}
+
+/**
+ * @type {Array<string>} The band block keys.
+ */
+export const SITE_BAND_BLOCKS = ['hero', 'section']
+
+/**
+ * Resolve a block component by key.
+ *
+ * @param {string} key The `widgetKey` from a page body.
+ * @return {object|null} The component, or null when the key is unknown.
+ */
+export function siteBlockFor(key) {
+	return siteBlockRegistry[key] || null
+}
+
+/**
+ * The keys this entry point can render.
+ *
+ * Exported so a consumer — or a test — can assert the vocabulary it depends on
+ * is actually present, rather than discovering a missing block as a blank area
+ * on a live page.
+ *
+ * @return {Array<string>} The known block keys.
+ */
+export function listSiteBlocks() {
+	return Object.keys(siteBlockRegistry)
+}