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

package/src/public/components/CnSiteEmptyState.vue

@@ -0,0 +1,172 @@
+<!--
+  - SPDX-FileCopyrightText: 2026 Conduction B.V.
+  - SPDX-License-Identifier: EUPL-1.2
+-->
+
+<template>
+	<div
+		:class="['ac-empty-state', `ac-empty-state--${variant}`]"
+		:role="variant === 'error' ? 'alert' : undefined"
+		:aria-busy="variant === 'loading' ? 'true' : undefined"
+		:aria-live="variant === 'loading' ? 'polite' : undefined">
+		<CnSiteIcon v-if="icon" :name="icon" :size="32" />
+
+		<component :is="headingTag" v-if="title" :class="headingClass">
+			{{ title }}
+		</component>
+
+		<p v-if="description" class="utrecht-paragraph">
+			{{ description }}
+		</p>
+
+		<a v-if="link" class="utrecht-link utrecht-link--html-a" :href="link">
+			{{ linkLabel || link }}
+		</a>
+
+		<slot />
+	</div>
+</template>
+
+<script>
+import CnSiteIcon from './CnSiteIcon.vue'
+
+/**
+ * The state a page shows when there is nothing to show yet, nothing to show at
+ * all, or nothing showable because something failed.
+ *
+ * WHY THIS IS NOT `NcEmptyContent`
+ *
+ * Nextcloud's own empty-state component is the obvious reuse and it cannot be
+ * used here: it comes from `@nextcloud/vue`, which is exactly the runtime
+ * coupling this entry point exists to keep out. A portal served from a
+ * municipality's own domain has no `OC` global, no session and no translation
+ * bundle, and a component reaching for them fails in a browser rather than at
+ * build time. The transitive-import guard in this package's CI would reject the
+ * import outright.
+ *
+ * WHY THE THREE VARIANTS ARE ONE COMPONENT
+ *
+ * `loading`, `empty` and `error` differ in what they ANNOUNCE, not in what they
+ * look like, and getting the announcement right is the entire point of having a
+ * component rather than a paragraph:
+ *
+ *   loading  aria-busy + aria-live="polite" — a screen reader is told the
+ *            region is working and will be told again when it settles, rather
+ *            than being handed a silent blank area
+ *   error    role="alert" — announced immediately, because a visitor who
+ *            cannot see the page must not sit waiting for content that will
+ *            never arrive
+ *   empty    neither. "There is nothing here" is ordinary content, and
+ *            announcing it as an alert cries wolf.
+ *
+ * Splitting them into three components would let a caller pick the wrong
+ * announcement for the right visual, which is precisely the mistake this
+ * prevents.
+ *
+ * IT REPLACES A BARE SENTENCE. The portal previously rendered `<p>Bezig met
+ * laden…</p>` — no landmark, no live region, no icon, unstyled, and identical
+ * in markup to an error. A sighted visitor saw a stray line under the header; a
+ * screen-reader user was told nothing at all.
+ *
+ * PUBLIC-SAFE (see ../index.js): no `@nextcloud/*` import. All copy arrives as
+ * props, because `t()` is the dependency that makes a component unusable
+ * outside Nextcloud.
+ */
+export default {
+	name: 'CnSiteEmptyState',
+
+	components: { CnSiteIcon },
+
+	props: {
+		/**
+		 * Which state this is. Decides the ARIA posture, not the styling.
+		 */
+		variant: {
+			type: String,
+			default: 'empty',
+			validator: (v) => ['loading', 'empty', 'error'].includes(v),
+		},
+
+		/** Headline, e.g. "Bezig met laden…" or "Pagina niet gevonden". */
+		title: {
+			type: String,
+			default: '',
+		},
+
+		/** Supporting line under the headline. */
+		description: {
+			type: String,
+			default: '',
+		},
+
+		/** Icon name from the closed vocabulary; '' renders none. */
+		icon: {
+			type: String,
+			default: '',
+		},
+
+		/** Optional way out — a link back to somewhere that works. */
+		link: {
+			type: String,
+			default: '',
+		},
+
+		/** Visible text for that link. */
+		linkLabel: {
+			type: String,
+			default: '',
+		},
+
+		/**
+		 * Heading level, so the page outline stays intact.
+		 *
+		 * An empty state usually replaces a page's main content, so it usually
+		 * wants the level that content would have had — not a fixed one.
+		 */
+		headingLevel: {
+			type: Number,
+			default: 2,
+			validator: (v) => v >= 1 && v <= 6,
+		},
+	},
+
+	computed: {
+		/**
+		 * @return {string} The heading element to render.
+		 */
+		headingTag() {
+			return `h${this.headingLevel}`
+		},
+
+		/**
+		 * The heading's class, tracking its level — the design system styles
+		 * the class, not the tag.
+		 *
+		 * @return {string} e.g. `utrecht-heading-2`.
+		 */
+		headingClass() {
+			return `utrecht-heading-${this.headingLevel}`
+		},
+	},
+}
+</script>
+
+<style scoped>
+/*
+ * Layout only, and deliberately token-driven.
+ *
+ * No colours are set here: an empty state can land on any surface a host puts
+ * it on, and this codebase has three separate bugs on record from rules that
+ * coloured text without knowing its background. The design system colours the
+ * heading, paragraph and link classes already.
+ */
+.ac-empty-state {
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	justify-content: center;
+	text-align: center;
+	gap: var(--utrecht-space-block-md, 0.75rem);
+	padding-block: var(--utrecht-space-block-2xl, 3rem);
+}
+</style>

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>