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

package/src/public/components/CnSiteHero.vue

@@ -0,0 +1,239 @@
+<!--
+  - SPDX-FileCopyrightText: 2026 Conduction B.V.
+  - SPDX-License-Identifier: EUPL-1.2
+-->
+
+<template>
+	<CnSiteSection variant="hero" :background-image="backgroundImage">
+		<!--
+			THE HEADING IS REAL BUT NOT NECESSARILY PAINTED, and that is a
+			deliberate improvement on the reference rather than a copy of it.
+
+			Measured on the NL Design System reference home page: the hero
+			contains NO heading element at all (its prompt lives inside the
+			search form) and the page therefore has no `h1` anywhere. Copying
+			that would inherit an outline defect.
+
+			Painting a heading directly on the band is the other trap. The band
+			is dark — `rgb(0, 56, 101)` on the reference — while the hero's own
+			computed colour is black, because the design system never puts bare
+			text there and so has no rule for it. A heading dropped onto that
+			band renders dark-on-dark: present, selectable, and unreadable.
+			(Exactly the failure that made this portal's footer links
+			`rgb(0, 68, 136)` on `rgb(0, 69, 137)`.)
+
+			So when the search box is shown, the heading stays in the DOM for
+			the outline and the VISIBLE prompt is the search label, which the
+			design system does style for this band. A host that wants a painted
+			heading asks for it with `heading-visible`.
+		-->
+		<component
+			:is="headingTag"
+			v-if="title"
+			:class="headingClass">
+			{{ title }}
+		</component>
+
+		<p v-if="subtitle" :class="subtitleClass">
+			{{ subtitle }}
+		</p>
+
+		<!--
+			THE CARD IS WHAT SIZES THE SEARCH BOX, and it is not decoration.
+			Captured from the reference:
+
+			  .ac-hero > .container > .ac-card.ac-card--blue.ac-card--padding-lg
+			    > .ac-card__content > form.ac-search-box
+
+			`nlds-app.css` says `.ac-hero .ac-card { inline-size: min(100%, 744px) }`,
+			and the card's padding takes the form from 744 down to 648. Rendered
+			without it the form simply filled the content column — measured 1168
+			against the design's 648 — because nothing else in the cascade
+			constrains it.
+		-->
+		<div v-if="search" class="ac-card ac-card--blue ac-card--padding-lg">
+			<div class="ac-card__content">
+				<CnSiteSearch
+					:label="effectiveSearchLabel"
+					:label-visible="true"
+					:placeholder="searchPlaceholder"
+					:submit-label="searchSubmitLabel"
+					:value="searchValue"
+					:input-id="searchInputId"
+					@search="$emit('search', $event)" />
+			</div>
+		</div>
+
+		<slot />
+	</CnSiteSection>
+</template>
+
+<script>
+import CnSiteSearch from './CnSiteSearch.vue'
+import CnSiteSection from './CnSiteSection.vue'
+
+/**
+ * The leading band of a site page.
+ *
+ * Composes the section band and, optionally, the search box — the shape the NL
+ * Design System reference uses on its home page, where the hero IS the search
+ * entry point rather than decoration above one.
+ *
+ * The search is opt-in (`search`), because a hero that always renders a search
+ * field would force every portal to either wire up a query back end or ship an
+ * inert control. An inert search box is worse than none: it invites the one
+ * interaction it cannot honour.
+ *
+ * PUBLIC-SAFE (see ../index.js): no `@nextcloud/*` import.
+ */
+export default {
+	name: 'CnSiteHero',
+
+	components: { CnSiteSearch, CnSiteSection },
+
+	props: {
+		/** The hero heading. */
+		title: {
+			type: String,
+			default: '',
+		},
+
+		/** Supporting line under the heading. */
+		subtitle: {
+			type: String,
+			default: '',
+		},
+
+		/** Heading level, so the page outline stays intact. */
+		headingLevel: {
+			type: Number,
+			default: 1,
+			validator: (v) => v >= 1 && v <= 6,
+		},
+
+		/** Whether to render the search box. */
+		search: {
+			type: Boolean,
+			default: false,
+		},
+
+		/**
+		 * Accessible name for the search landmark.
+		 *
+		 * EMPTY BY DEFAULT so `title` can serve as the prompt. This defaulted
+		 * to 'Zoeken', which made `searchLabel || title` dead code — the
+		 * fallback could never fire, and a host that set only `title` got the
+		 * generic word instead of its own question. Caught by the test that
+		 * asserts the visible label carries the hero's words.
+		 */
+		searchLabel: {
+			type: String,
+			default: '',
+		},
+
+		/** Placeholder inside the search field. */
+		searchPlaceholder: {
+			type: String,
+			default: '',
+		},
+
+		/** Visible text on the search button. */
+		searchSubmitLabel: {
+			type: String,
+			default: 'Zoeken',
+		},
+
+		/** Pre-filled search term. */
+		searchValue: {
+			type: String,
+			default: '',
+		},
+
+		/** DOM id for the search input. */
+		searchInputId: {
+			type: String,
+			default: 'cn-site-search',
+		},
+
+		/**
+		 * Optional background image for the band.
+		 *
+		 * The reference's hero carries one (`cover`, centred) over its blue.
+		 * A URL rather than a token because it is CONTENT — each portal's own
+		 * photograph — not a design decision the token set can make.
+		 */
+		backgroundImage: {
+			type: String,
+			default: '',
+		},
+
+		/**
+		 * Paint the heading on the band.
+		 *
+		 * Defaults to the safe answer: visible only when there is no search box
+		 * to carry the prompt. Forcing it on a dark band without a colour rule
+		 * for it is how a heading becomes invisible.
+		 */
+		headingVisible: {
+			type: Boolean,
+			default: null,
+		},
+	},
+
+	emits: ['search'],
+
+	computed: {
+		/**
+		 * @return {string} The heading element to render.
+		 */
+		headingTag() {
+			return `h${this.headingLevel}`
+		},
+
+		/**
+		 * The search box's accessible name.
+		 *
+		 * Prefers an explicit `searchLabel`, then the hero's own `title` — the
+		 * reference implementation's hero puts its question inside the form, so
+		 * the title IS the prompt there. Falls back to a generic word only when
+		 * a host supplies neither, because an unnamed search field is worse
+		 * than a generically named one.
+		 *
+		 * @return {string} A non-empty label.
+		 */
+		effectiveSearchLabel() {
+			return this.searchLabel || this.title || 'Zoeken'
+		},
+
+		/**
+		 * Whether the heading is painted.
+		 *
+		 * @return {boolean} True when it should be visible.
+		 */
+		showHeading() {
+			if (this.headingVisible !== null) {
+				return this.headingVisible
+			}
+
+			// With a search box the label carries the prompt, so a painted
+			// heading would duplicate it — and duplicate it in the one place
+			// the design system has no text colour for.
+			return this.search === false
+		},
+
+		/**
+		 * @return {Array} Classes for the heading.
+		 */
+		headingClass() {
+			return ['ac-hero__title', this.showHeading ? null : 'sr-only'].filter(Boolean)
+		},
+
+		/**
+		 * @return {Array} Classes for the subtitle.
+		 */
+		subtitleClass() {
+			return ['ac-hero__subtitle', this.showHeading ? null : 'sr-only'].filter(Boolean)
+		},
+	},
+}
+</script>

package/src/public/components/CnSiteIcon.vue

@@ -0,0 +1,90 @@
+<!--
+  - SPDX-FileCopyrightText: 2026 Conduction B.V.
+  - SPDX-License-Identifier: EUPL-1.2
+-->
+
+<template>
+	<svg
+		v-if="path"
+		class="ac-icon"
+		:class="`ac-icon--${name}`"
+		:width="size"
+		:height="size"
+		viewBox="0 0 24 24"
+		fill="none"
+		aria-hidden="true"
+		focusable="false">
+		<path :d="path" fill="currentColor" />
+	</svg>
+</template>
+
+<script>
+/**
+ * A small inline icon from a CLOSED vocabulary.
+ *
+ * WHY INLINE SVG AND NOT AN ICON FONT
+ *
+ * An icon font is a webfont, and this codebase has already been bitten by
+ * exactly that: the reference application's stylesheets declare `ac-icons` with
+ * a root-relative url, which from a portal's own path resolves against the
+ * ORIGIN and 404s. A missing icon font does not fail loudly — it renders a
+ * blank box or a stray letter, and the page looks finished.
+ *
+ * WHY A CLOSED SET AND NOT AN ARBITRARY `path` PROP
+ *
+ * Page content is authored data. Letting an author supply raw SVG path data
+ * would put attacker-controlled markup inside an `<svg>` on a public government
+ * page. A name resolved against a fixed map cannot express anything the map
+ * does not already contain, and an unknown name renders NOTHING rather than
+ * guessing.
+ *
+ * ALWAYS DECORATIVE. Every icon here sits beside its own visible label, so it
+ * is `aria-hidden` with `focusable="false"`. An icon that repeats the adjacent
+ * text is one more thing announced for no gain, and `focusable="false"` keeps
+ * IE-era SVG out of the tab order.
+ *
+ * PUBLIC-SAFE (see ../index.js): no `@nextcloud/*` import.
+ */
+
+/**
+ * The icon vocabulary. Paths are 24x24, single-path, currentColor.
+ *
+ * @type {Record<string, string>}
+ */
+const ICON_PATHS = {
+	search: 'M10 4a6 6 0 1 0 3.7 10.72l4.29 4.29a1 1 0 0 0 1.42-1.42l-4.29-4.29A6 6 0 0 0 10 4Zm-4 6a4 4 0 1 1 8 0 4 4 0 0 1-8 0Z',
+	document: 'M6 2h7l5 5v15H6V2Zm7 1.5V8h4.5L13 3.5ZM8 12h8v1.5H8V12Zm0 4h8v1.5H8V16Z',
+	globe: 'M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20Zm6.9 9h-3a15.6 15.6 0 0 0-1.2-5.4A8 8 0 0 1 18.9 11ZM12 4.2c.8 1.2 1.5 3.4 1.7 6.8h-3.4c.2-3.4.9-5.6 1.7-6.8ZM5.1 11a8 8 0 0 1 4.2-5.4A15.6 15.6 0 0 0 8.1 11h-3Zm0 2h3a15.6 15.6 0 0 0 1.2 5.4A8 8 0 0 1 5.1 13Zm6.9 6.8c-.8-1.2-1.5-3.4-1.7-6.8h3.4c-.2 3.4-.9 5.6-1.7 6.8Zm2.7-1.4a15.6 15.6 0 0 0 1.2-5.4h3a8 8 0 0 1-4.2 5.4Z',
+	'external-link': 'M14 3h7v7h-2V6.41l-9.29 9.3-1.42-1.42 9.3-9.29H14V3ZM5 5h5v2H7v10h10v-3h2v5H5V5Z',
+	'arrow-right': 'M13.17 5.17 12 6.34 16.66 11H4v2h12.66L12 17.66l1.17 1.17L20 12l-6.83-6.83Z',
+	information: 'M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20Zm1 15h-2v-6h2v6Zm0-8h-2V7h2v2Z',
+	email: 'M4 4h16v16H4V4Zm2 2v.5l6 4 6-4V6H6Zm12 3-6 4-6-4v9h12V9Z',
+}
+
+export default {
+	name: 'CnSiteIcon',
+
+	props: {
+		/** Icon name from the closed vocabulary. Unknown names render nothing. */
+		name: {
+			type: String,
+			required: true,
+		},
+
+		/** Square size in pixels. */
+		size: {
+			type: [Number, String],
+			default: 20,
+		},
+	},
+
+	computed: {
+		/**
+		 * @return {string} The path data, or '' when the name is unknown.
+		 */
+		path() {
+			return ICON_PATHS[this.name] || ''
+		},
+	},
+}
+</script>

package/src/public/components/CnSiteSearch.vue

@@ -0,0 +1,173 @@
+<!--
+  - SPDX-FileCopyrightText: 2026 Conduction B.V.
+  - SPDX-License-Identifier: EUPL-1.2
+-->
+
+<template>
+	<form
+		class="ac-search-box ac-search-box--home"
+		role="search"
+		:aria-label="label"
+		@submit.prevent="submit">
+		<!--
+			A LABEL, not just a placeholder. A placeholder disappears the moment
+			the field has content and is not reliably announced, so a
+			placeholder-only search box leaves a screen-reader user with an
+			unnamed text input.
+
+			VISIBLE BY DEFAULT when the host asks for it, because on the NL
+			Design System reference the prompt IS this label — measured on its
+			home page, the hero contains no heading element at all and the
+			question sits inside the form. Hiding it there would delete the only
+			visible prompt on the band.
+		-->
+		<!--
+			Class names captured from the running reference rather than guessed —
+			`utrecht-form-label`, `utrecht-textbox--html-input` and
+			`utrecht-button--primary-action` are what the design system's CSS
+			actually selects on. Without the primary-action modifier the submit
+			button renders as the SUBTLE variant: measured, transparent
+			background and rgb(10, 39, 80) text where the design wants a filled
+			rgb(0, 68, 136) button with white text.
+		-->
+		<div class="ac-flex ac-flex--column ac-flex--spacing-sm">
+			<label :class="labelClass" :for="inputId">
+				{{ label }}
+			</label>
+
+			<div class="ac-search-box__search">
+				<input
+					:id="inputId"
+					v-model="term"
+					type="text"
+					name="q"
+					class="ac-search-box__input utrecht-textbox utrecht-textbox--html-input"
+					:placeholder="placeholder"
+					autocomplete="off">
+				<button
+					type="submit"
+					class="ac-search-box__button utrecht-button utrecht-button--submit utrecht-button--primary-action">
+					<!--
+						DECORATIVE, so `aria-hidden` and no title: the button
+						already has a text label beside it, and an icon that
+						repeats it is one more thing for a screen reader to read
+						out for no gain.
+					-->
+					<svg
+						class="ac-search-box__search-icon"
+						width="20"
+						height="20"
+						viewBox="0 0 20 20"
+						fill="none"
+						aria-hidden="true"
+						focusable="false">
+						<path
+							d="M8.5 3a5.5 5.5 0 1 0 3.383 9.83l3.643 3.644a.75.75 0 1 0 1.061-1.06l-3.644-3.644A5.5 5.5 0 0 0 8.5 3Zm-4 5.5a4 4 0 1 1 8 0 4 4 0 0 1-8 0Z"
+							fill="currentColor" />
+					</svg>
+					{{ submitLabel }}
+				</button>
+			</div>
+		</div>
+	</form>
+</template>
+
+<script>
+/**
+ * The site search box.
+ *
+ * Emits `search` with the term and does NOT fetch anything itself. A block
+ * that owned its own transport could only ever work against one back end,
+ * which is the opposite of what a shared library is for — the host decides
+ * where a query goes.
+ *
+ * It is a real `<form>` with a submit button so that Enter works and the
+ * control is reachable and operable by keyboard without any script.
+ *
+ * PUBLIC-SAFE (see ../index.js): no `@nextcloud/*` import. Labels arrive as
+ * props rather than through `t()`, because the translation layer is exactly
+ * the dependency that makes a component unusable outside Nextcloud.
+ */
+export default {
+	name: 'CnSiteSearch',
+
+	props: {
+		/** Accessible name for the search landmark and its input. */
+		label: {
+			type: String,
+			default: 'Zoeken',
+		},
+
+		/** Placeholder shown inside the field. */
+		placeholder: {
+			type: String,
+			default: '',
+		},
+
+		/** Visible text on the submit button. */
+		submitLabel: {
+			type: String,
+			default: 'Zoeken',
+		},
+
+		/** Pre-filled term, so a results page can round-trip the query. */
+		value: {
+			type: String,
+			default: '',
+		},
+
+		/** DOM id for the input, so the label can reference it. */
+		inputId: {
+			type: String,
+			default: 'cn-site-search',
+		},
+
+		/**
+		 * Whether the label is shown or only exposed to assistive tech.
+		 *
+		 * It is ALWAYS in the DOM either way — this only decides whether it is
+		 * painted. A search box whose label is hidden with `display: none`
+		 * would be hidden from screen readers too, which is why the hidden
+		 * state is a clip-based `sr-only`, not a display toggle.
+		 */
+		labelVisible: {
+			type: Boolean,
+			default: false,
+		},
+	},
+
+	emits: ['search'],
+
+	data() {
+		return {
+			term: this.value,
+		}
+	},
+
+	computed: {
+		/**
+		 * @return {Array} Classes for the label.
+		 */
+		labelClass() {
+			return ['ac-search-box__label', 'utrecht-form-label', this.labelVisible ? null : 'sr-only'].filter(Boolean)
+		},
+	},
+
+	watch: {
+		value(next) {
+			this.term = next
+		},
+	},
+
+	methods: {
+		/**
+		 * Hand the term to the host.
+		 *
+		 * @return {void}
+		 */
+		submit() {
+			this.$emit('search', this.term)
+		},
+	},
+}
+</script>

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>