Clippy Link

packages/clippy-components/package.json

@@ -40,13 +40,16 @@
     "test-build": "vitest --run --coverage",
     "test-install-browsers": "playwright install chromium",
     "test:unit": "vitest --run",
+    "test:watch": "vitest --watch",
     "preview": "vite preview"
   },
   "dependencies": {
     "@amsterdam/design-system-css": "2.2.0",
     "@nl-design-system-candidate/button-css": "1.0.0",
     "@nl-design-system-candidate/code-css": "2.0.3",
     "@nl-design-system-candidate/color-sample-css": "1.0.4",
+    "@nl-design-system-candidate/heading-css": "1.1.3",
+    "@nl-design-system-candidate/link-css": "2.0.3",
     "@utrecht/button-css": "3.0.1",
     "@utrecht/combobox-css": "2.0.1",
     "@utrecht/listbox-css": "2.0.1",

packages/clippy-components/src/clippy-link/README.md

@@ -0,0 +1,86 @@
+# `<clippy-link>`
+
+Link (anker) met NL Design System link styles. Gebaseerd op het [NL Design System Link candidate](https://github.com/nl-design-system/candidate/blob/main/packages/components-react/link-react/src/link.tsx) component. 
+
+De linktekst komt uit de standaard slot content.
+
+## Voorbeeld
+
+```html
+<clippy-link href="/voorbeeld">Lees meer</clippy-link>
+```
+
+## Class attribuut
+
+Je kunt een `class` attribuut op het `<clippy-link>` element zetten, deze wordt doorgestuurd naar het onderliggende `<a>` element en voegt zo extra styling toe.
+
+```html
+<clippy-link href="/voorbeeld" class="mijn-eigen-class">Lees meer</clippy-link>
+```
+
+## Externe link
+
+```html
+<clippy-link href="https://example.com" target="_blank" rel="noopener noreferrer">Voorbeeldsite</clippy-link>
+```
+
+## Disabled link
+
+Wanneer `disabled` actief is, gedraagt de link zich als “uitgeschakeld”:
+- `href`, `target` en `rel` worden niet gerenderd op het onderliggende `<a>`
+- `aria-disabled="true"` wordt gezet
+- `role="link"` wordt gezet
+- `tabindex="0"` wordt gezet op het host element
+
+```html
+<clippy-link href="/x" target="_blank" disabled>Lees meer</clippy-link>
+```
+
+## Attribuut-forwarding (`aria-*` / `data-*`)
+
+Standaard worden alleen `aria-*` en `data-*` attributes die je op `<clippy-link>` zet, doorgestuurd naar het onderliggende `<a>`.
+
+```html
+<clippy-link href="/x" aria-label="Meer info" data-testid="link">Lees meer</clippy-link>
+```
+
+Wil je *alle* (niet-interne) host attributes doorgeven, zet dan `forward-attributes="all"`.
+
+```html
+<clippy-link href="/x" forward-attributes="all" title="Tooltip">Lees meer</clippy-link>
+```
+
+> **Let op:** `class` en `style` worden niet doorgestuurd, ook niet met `forward-attributes="all"`.
+
+## Extra properties via `restProps` (property-only)
+
+Sommige `<a>`-properties zijn beschikbaar via `restProps` (dit is **geen** attribute-API; alleen via JavaScript). Deze properties worden via property bindings doorgestuurd naar het onderliggende `<a>` element:
+
+- `download`
+- `hreflang`
+- `ping`
+- `referrerPolicy`
+- `type`
+
+```js
+const el = document.querySelector('clippy-link');
+el.restProps = {
+  download: 'bestand.pdf',
+  hreflang: 'nl',
+  ping: 'https://example.com/ping',
+  referrerPolicy: 'no-referrer',
+  type: 'text/html',
+};
+```
+
+## API
+
+- **`href`**: string (standaard `""`) — wordt (wanneer niet `disabled`) doorgegeven aan het onderliggende `<a href="...">`.
+- **`target`**: string (standaard `""`) — wordt (wanneer niet `disabled`) doorgegeven aan `<a target="...">` (bijv. `_blank`).
+- **`rel`**: string (standaard `""`) — wordt (wanneer niet `disabled`) doorgegeven aan `<a rel="...">`.
+- **`current`**: string (standaard `""`) — alternatief voor `aria-current`; zet `aria-current` en voegt class `nl-link--current` toe.
+- **`inline-box`** (`inline-box` attribute): boolean (standaard `false`) — voegt class `nl-link--inline-box` toe.
+- **`disabled`**: boolean (standaard `false`) — voegt class `nl-link--disabled` toe, verwijdert `href/target/rel` van het onderliggende `<a>`, zet `aria-disabled="true"`, `role="link"` en `tabindex="0"` op het host element.
+- **`forward-attributes`**: `"aria-data"` (default) | `"all"` — bepaalt welke host attributes worden doorgestuurd naar het onderliggende `<a>`.
+- **`class`**: string (attribute op host) — wordt doorgestuurd naar het onderliggende `<a>` via classMap.
+- **`restProps`**: object (property-only) — extra (getypte) properties voor het onderliggende `<a>`, via property bindings: `download`, `hreflang`, `referrerPolicy`, `ping`, `type`.

packages/clippy-components/src/clippy-link/index.test.ts

@@ -0,0 +1,115 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import './index';
+
+const tag = 'clippy-link';
+
+describe(`<${tag}>`, () => {
+  beforeEach(() => {
+    document.body.innerHTML = `<${tag}></${tag}>`;
+  });
+
+  it('renders an anchor with base class and sets href', async () => {
+    document.body.innerHTML = `<${tag} href="/example"></${tag}>`;
+    const el = document.querySelector(tag);
+    expect(el).not.toBeNull();
+
+    await customElements.whenDefined(tag);
+    await el?.updateComplete;
+
+    const a = el?.shadowRoot?.querySelector('a');
+    expect(a).not.toBeNull();
+    expect(a?.classList.contains('nl-link')).toBe(true);
+    expect(a?.getAttribute('href')).toBe('/example');
+  });
+
+  it('does not forward arbitrary anchor-specific attributes from the host', async () => {
+    document.body.innerHTML = `<${tag} download="file.pdf" hreflang="en" ping="https://example.com/ping" referrerpolicy="no-referrer" type="application/pdf"></${tag}>`;
+    const el = document.querySelector(tag);
+    expect(el).not.toBeNull();
+
+    await customElements.whenDefined(tag);
+    await el?.updateComplete;
+
+    const a = el!.shadowRoot?.querySelector('a');
+    expect(a).not.toBeNull();
+    expect(a?.getAttribute('download')).toBeNull();
+    expect(a?.getAttribute('hreflang')).toBeNull();
+    expect(a?.getAttribute('ping')).toBeNull();
+    expect(a?.getAttribute('referrerpolicy')).toBeNull();
+    expect(a?.getAttribute('type')).toBeNull();
+  });
+
+  it('adds nl-link--current class when aria-current is set on the host', async () => {
+    document.body.innerHTML = `<${tag} aria-current="page"></${tag}>`;
+    const el = document.querySelector(tag);
+    expect(el).not.toBeNull();
+
+    await customElements.whenDefined(tag);
+    await el?.updateComplete;
+
+    const a = el?.shadowRoot?.querySelector('a');
+    expect(a).not.toBeNull();
+    expect(a?.classList.contains('nl-link--current')).toBe(true);
+    expect(a?.getAttribute('aria-current')).toBe('page');
+  });
+
+  it('adds nl-link--inline-box class when inline-box is set', async () => {
+    document.body.innerHTML = `<${tag} inline-box></${tag}>`;
+    const el = document.querySelector(tag);
+    expect(el).not.toBeNull();
+
+    await customElements.whenDefined(tag);
+    await el?.updateComplete;
+
+    const a = el?.shadowRoot?.querySelector('a');
+    expect(a).not.toBeNull();
+    expect(a?.classList.contains('nl-link--inline-box')).toBe(true);
+  });
+
+  it('disabled removes href/target and marks link as disabled', async () => {
+    document.body.innerHTML = `<${tag} href="/x" target="_blank" disabled>Lees meer</${tag}>`;
+    const el = document.querySelector(tag);
+    expect(el).not.toBeNull();
+
+    await customElements.whenDefined(tag);
+    await el?.updateComplete;
+
+    const a = el?.shadowRoot?.querySelector('a');
+    expect(a).not.toBeNull();
+    expect(a?.classList.contains('nl-link--disabled')).toBe(true);
+    expect(a?.getAttribute('aria-disabled')).toBe('true');
+    expect(a?.getAttribute('href')).toBeNull();
+    expect(a?.getAttribute('target')).toBeNull();
+    expect(a?.getAttribute('tabindex')).toBe('0');
+    expect(a?.getAttribute('role')).toBe('link');
+  });
+
+  it('does not forward non-component aria/data attributes to the rendered anchor', async () => {
+    document.body.innerHTML = `<${tag} href="/x" aria-label="Meer info" data-testid="link">Lees meer</${tag}>`;
+    const el = document.querySelector(tag);
+    expect(el).not.toBeNull();
+
+    await customElements.whenDefined(tag);
+    await el?.updateComplete;
+
+    const a = el?.shadowRoot?.querySelector('a');
+    expect(a).not.toBeNull();
+    expect(a?.getAttribute('aria-label')).toBeNull();
+    expect(a?.dataset['testid']).toBeUndefined();
+  });
+
+  it('forwards host class to inner anchor', async () => {
+    document.body.innerHTML = `<${tag}></${tag}>`;
+    const el = document.querySelector(tag);
+    expect(el).not.toBeNull();
+
+    await customElements.whenDefined(tag);
+
+    if (el) el.className = 'my-extra-class';
+    await el?.updateComplete;
+
+    const a = el?.shadowRoot?.querySelector('a');
+    expect(a).not.toBeNull();
+    expect(a?.classList.contains('my-extra-class')).toBe(true);
+  });
+});

packages/clippy-components/src/clippy-link/index.ts

@@ -0,0 +1,68 @@
+import linkCss from '@nl-design-system-candidate/link-css/link.css?inline';
+import { html, LitElement, nothing, unsafeCSS } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+import { classMap } from 'lit/directives/class-map.js';
+
+@customElement('clippy-link')
+export class ClippyLink extends LitElement {
+  @property() href = '';
+  @property() target = '';
+  @property() rel = '';
+
+  @property({ attribute: 'inline-box', type: Boolean }) inlineBox = false;
+  @property({ type: Boolean }) disabled = false;
+  @property({ attribute: 'aria-current' }) ariaCurrentValue: string = '';
+  @property({ attribute: false }) override className = '';
+
+  static override readonly styles = [unsafeCSS(linkCss)];
+
+  override render() {
+    const disabled = this.disabled;
+
+    // When disabled, remove href/target/rel and keep it focusable for accessibility.
+    const href = disabled ? nothing : this.href || nothing;
+    const target = disabled || !this.target ? nothing : this.target;
+    const rel = disabled || !this.rel ? nothing : this.rel;
+    const role = disabled ? 'link' : nothing;
+    const tabIndex = disabled ? 0 : nothing;
+    const ariaCurrent = this.ariaCurrentValue || nothing;
+
+    const classes = {
+      'nl-link': true,
+      'nl-link--current': Boolean(this.ariaCurrentValue),
+      'nl-link--disabled': disabled,
+      'nl-link--inline-box': this.inlineBox,
+    };
+
+    const hostClasses = (this.className || '')
+      .trim()
+      .split(/\s+/)
+      .filter(Boolean)
+      .reduce<Record<string, boolean>>((acc, name) => {
+        acc[name] = true;
+        return acc;
+      }, {});
+    const mergedClasses = { ...classes, ...hostClasses };
+
+    return html`
+      <a
+        class=${classMap(mergedClasses)}
+        href=${href}
+        target=${target}
+        rel=${rel}
+        aria-disabled=${disabled || nothing}
+        aria-current=${ariaCurrent}
+        role=${role}
+        tabindex=${tabIndex}
+      >
+        <slot></slot>
+      </a>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'clippy-link': ClippyLink;
+  }
+}