@ghentcdh/ui 1.0.4 → 1.1.0

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@ghentcdh/ui",
   "author": "GhentCDH",
-  "version": "1.0.4",
+  "version": "1.1.0",
+  "type": "module",
   "main": "./index.js",
   "module": "./index.mjs",
   "types": "./index.d.ts",
@@ -11,6 +12,11 @@
       "import": "./index.mjs",
       "require": "./index.js"
     },
+    "./testing": {
+      "types": "./testing/index.d.ts",
+      "import": "./testing.mjs",
+      "require": "./testing.js"
+    },
     "./index.css": "./index.css",
     "./package.json": "./package.json"
   },
@@ -39,13 +45,20 @@
     "shell/**",
     "table/**",
     "test-utils/**",
+    "testing/**",
     "toast/**",
     "tree/**",
     "utils/**"
   ],
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
+  },
   "sideEffects": false,
   "peerDependencies": {
     "@ghentcdh/tools-vue": ">=0.6.0",
+    "@playwright/test": ">=1.50.0",
     "@heroicons/vue": "^2.2.0",
     "@tiptap/pm": "^3.0.0",
     "@tiptap/starter-kit": "^3.0.0",

package/testing/AlertHarness.d.ts

@@ -0,0 +1,16 @@
+import { Locator, Page } from '@playwright/test';
+import { Harness } from './Harness';
+/**
+ * Drives the `@ghentcdh/ui` `Alert` component.
+ *
+ * Renders `<div role="alert">` with a message and type-based CSS class.
+ */
+export declare class AlertHarness extends Harness {
+    /** Resolve the alert by its message text. */
+    static byMessage(parent: Locator | Page, message: string): AlertHarness;
+    /** Resolve the first (or only) alert on the page. */
+    static first(parent: Locator | Page): AlertHarness;
+    static for(locator: Locator): AlertHarness;
+    message(): Promise<string>;
+    hasClass(cls: string): Promise<boolean>;
+}

package/testing/AutocompleteHarness.d.ts

@@ -0,0 +1,29 @@
+import { Locator, Page } from '@playwright/test';
+import { Harness } from './Harness';
+/**
+ * Drives the `@ghentcdh/ui` `AutoComplete` component.
+ *
+ * Input is `role="combobox"`. Options are portaled `role="option"` items.
+ * The component supports remote-fetched options, freeText mode, and an
+ * optional "Create new" button.
+ */
+export declare class AutocompleteHarness extends Harness {
+    static byId(parent: Locator | Page, id: string): AutocompleteHarness;
+    static byLabel(parent: Locator | Page, label: string): AutocompleteHarness;
+    static for(locator: Locator): AutocompleteHarness;
+    /** Type a query, wait for the matching option, click it. */
+    fill(value: string): Promise<this>;
+    /** Just type a query without selecting — useful for asserting dropdown state. */
+    query(value: string): Promise<this>;
+    /** Pick a specific option by visible label, after `query()` has filtered. */
+    pickOption(label: string): Promise<this>;
+    /** Press a key — useful for arrow-down / Enter / Esc keyboard nav tests. */
+    press(key: string): Promise<this>;
+    /** Click the "Create new" button (requires `enableCreate`). */
+    clickCreateNew(): Promise<void>;
+    clear(): Promise<this>;
+    value(): Promise<string>;
+    /** The listbox is portaled — locate it relative to the Page. */
+    listbox(): Locator;
+    options(): Locator;
+}

package/testing/BooleanHarness.d.ts

@@ -0,0 +1,14 @@
+import { Locator, Page } from '@playwright/test';
+import { Harness } from './Harness';
+/**
+ * Drives the `@ghentcdh/ui` `Checkbox` component.
+ * Renders `<input role="checkbox" aria-label="{id}">`.
+ */
+export declare class BooleanHarness extends Harness {
+    static byId(parent: Locator | Page, id: string): BooleanHarness;
+    static byLabel(parent: Locator | Page, label: string): BooleanHarness;
+    static for(locator: Locator): BooleanHarness;
+    fill(value: boolean): Promise<this>;
+    toggle(): Promise<this>;
+    value(): Promise<boolean>;
+}

package/testing/ButtonHarness.d.ts

@@ -0,0 +1,16 @@
+import { Locator, Page } from '@playwright/test';
+import { Harness } from './Harness';
+/**
+ * Drives the `@ghentcdh/ui` `Btn` component.
+ *
+ * Renders `<button>` (or `<a>`) with optional icon, tooltip, disabled state,
+ * and emits `click`.
+ */
+export declare class ButtonHarness extends Harness {
+    /** Resolve by accessible name (button text / aria-label). */
+    static byName(parent: Locator | Page, name: string): ButtonHarness;
+    static for(locator: Locator): ButtonHarness;
+    click(): Promise<this>;
+    isDisabled(): Promise<boolean>;
+    text(): Promise<string>;
+}

package/testing/CollapseHarness.d.ts

@@ -0,0 +1,22 @@
+import { Locator, Page } from '@playwright/test';
+import { Harness } from './Harness';
+/**
+ * Drives the `@ghentcdh/ui` `Collapse` component.
+ *
+ * The collapse uses a hidden `<input type="checkbox" aria-label="Toggle {title}">`
+ * to control open/close state. Content lives inside `.collapse-content`.
+ */
+export declare class CollapseHarness extends Harness {
+    /** Resolve by the collapse title text. */
+    static byTitle(parent: Locator | Page, title: string): CollapseHarness;
+    static for(locator: Locator): CollapseHarness;
+    /** Toggle open/close by clicking the hidden checkbox. */
+    toggle(): Promise<this>;
+    /** Whether the collapse is currently open (checkbox checked). */
+    isOpen(): Promise<boolean>;
+    /** The title text element. */
+    title(): Locator;
+    /** The content wrapper. */
+    content(): Locator;
+    private checkbox;
+}

package/testing/DrawerHarness.d.ts

@@ -0,0 +1,21 @@
+import { Locator, Page } from '@playwright/test';
+import { Harness } from './Harness';
+/**
+ * Drives the `@ghentcdh/ui` `Drawer` component.
+ *
+ * The drawer has left/right toggle buttons with aria-labels like
+ * "Collapse left panel" / "Expand left panel".
+ */
+export declare class DrawerHarness extends Harness {
+    /** Resolve the drawer as the `<main>` containing the panels. */
+    static root(parent: Locator | Page): DrawerHarness;
+    static for(locator: Locator): DrawerHarness;
+    toggleLeft(): Promise<this>;
+    toggleRight(): Promise<this>;
+    isLeftOpen(): Promise<boolean>;
+    isRightOpen(): Promise<boolean>;
+    leftPanel(): Locator;
+    rightPanel(): Locator;
+    private leftButton;
+    private rightButton;
+}

package/testing/Harness.d.ts

@@ -0,0 +1,27 @@
+import { Locator, Page } from '@playwright/test';
+/**
+ * Base class for a Locator-scoped control driver.
+ *
+ * A Harness wraps one UI control (input, checkbox, autocomplete, …). It is
+ * agnostic of routes, fixtures, and the surrounding form — that's the job of
+ * `*Fixture` and `*Page` classes in the consuming packages.
+ *
+ * Concrete harnesses provide one or more `static` factory methods. The two
+ * conventional ones are `byLabel` (the user-visible label or aria-label) and
+ * `byId` (the `aria-label="{id}"` that lib components emit). Subclasses can
+ * add more — e.g. `MarkdownHarness.byTitle`.
+ */
+export declare abstract class Harness {
+    protected readonly locator: Locator;
+    constructor(locator: Locator);
+    /** Access the Page this harness was scoped against. */
+    protected page(): Page;
+    /** Get the underlying Locator — useful for assertions or further scoping. */
+    asLocator(): Locator;
+}
+/**
+ * Resolve a single role + accessible name inside a parent. The `name` option
+ * in Playwright matches accessible names case-insensitively by substring, so
+ * both `Author` and `author` will hit the same control.
+ */
+export declare const byRole: (parent: Locator | Page, role: "textbox" | "spinbutton" | "checkbox" | "combobox" | "button" | "dialog", name: string) => Locator;

package/testing/MarkdownHarness.d.ts

@@ -0,0 +1,24 @@
+import { Locator, Page } from '@playwright/test';
+import { Harness } from './Harness';
+export type MarkdownToolbarButton = 'B' | 'I';
+/**
+ * Drives the `@ghentcdh/ui` `Markdown` component (TipTap-backed).
+ *
+ * The component renders `<div role="textbox" aria-label="{id}">` with a
+ * toolbar of `<button>`s whose visible text is the mark label (`B`, `I`, …).
+ */
+export declare class MarkdownHarness extends Harness {
+    static byId(parent: Locator | Page, id: string): MarkdownHarness;
+    static byLabel(parent: Locator | Page, label: string): MarkdownHarness;
+    static for(locator: Locator): MarkdownHarness;
+    /** The editable inner surface — TipTap renders a nested `role="textbox"`. */
+    private get editor();
+    fill(value: string): Promise<this>;
+    clear(): Promise<this>;
+    typeBold(text: string): Promise<this>;
+    typeItalic(text: string): Promise<this>;
+    type(text: string): Promise<this>;
+    toolbar(name: MarkdownToolbarButton): Locator;
+    /** Is a toolbar mark currently active (the lib adds `btn-active`)? */
+    isMarkActive(name: MarkdownToolbarButton): Promise<boolean>;
+}

package/testing/ModalHarness.d.ts

@@ -0,0 +1,35 @@
+import { Locator, Page } from '@playwright/test';
+import { Harness } from './Harness';
+/**
+ * Drives the `@ghentcdh/ui` `Modal` component.
+ *
+ * Renders `<dialog role="dialog" aria-labelledby="{titleId}">` containing an
+ * `<h3 id="{titleId}">{{ modalTitle }}</h3>`, an `aria-label="Close"` button
+ * (unless `disableClose`), and `#content` / `#actions` slots.
+ *
+ * The native `<dialog>` element handles focus trap + Esc + backdrop click for
+ * us; the harness exposes the surface needed to assert that behavior.
+ */
+export declare class ModalHarness extends Harness {
+    /**
+     * Resolve by the dialog's accessible name (the `modalTitle` shown in the
+     * `<h3>`). Note: matches are case-insensitive substring.
+     */
+    static byTitle(parent: Locator | Page, title: string): ModalHarness;
+    /** Resolve the only-open dialog. Useful when there's just one at a time. */
+    static current(parent: Locator | Page): ModalHarness;
+    static for(locator: Locator): ModalHarness;
+    clickClose(): Promise<this>;
+    /** Press Esc on the dialog (handled by the native `<dialog>` element). */
+    pressEscape(): Promise<this>;
+    /** Click outside the modal box to attempt a backdrop close. */
+    clickBackdrop(): Promise<this>;
+    /** Click an action button in the modal's `#actions` slot by accessible name. */
+    clickAction(name: string): Promise<this>;
+    /** The `<h3>` title element. */
+    title(): Locator;
+    /** The content slot wrapper. */
+    content(): Locator;
+    /** Whether the dialog is currently visible (for `expect().toBeVisible()`). */
+    asLocator(): Locator;
+}

package/testing/MultiSelectHarness.d.ts

@@ -0,0 +1,16 @@
+import { Locator, Page } from '@playwright/test';
+import { Harness } from './Harness';
+/**
+ * Drives the `@ghentcdh/ui` `MultiSelect` component.
+ * Combobox shape like `SelectHarness`, but the list stays open across picks.
+ */
+export declare class MultiSelectHarness extends Harness {
+    static byId(parent: Locator | Page, id: string): MultiSelectHarness;
+    static byLabel(parent: Locator | Page, label: string): MultiSelectHarness;
+    static for(locator: Locator): MultiSelectHarness;
+    open(): Promise<this>;
+    fill(labels: string[]): Promise<this>;
+    select(label: string): Promise<this>;
+    /** Remove a selected chip by its label. */
+    removeChip(label: string): Promise<this>;
+}

package/testing/NumberHarness.d.ts

@@ -0,0 +1,14 @@
+import { Locator, Page } from '@playwright/test';
+import { Harness } from './Harness';
+/**
+ * Drives the `@ghentcdh/ui` `InputNumber` component.
+ * Renders `<input type="number" aria-label="{id}">` — role `spinbutton`.
+ */
+export declare class NumberHarness extends Harness {
+    static byId(parent: Locator | Page, id: string): NumberHarness;
+    static byLabel(parent: Locator | Page, label: string): NumberHarness;
+    static for(locator: Locator): NumberHarness;
+    fill(value: number): Promise<this>;
+    clear(): Promise<this>;
+    value(): Promise<number | null>;
+}

package/testing/SelectHarness.d.ts

@@ -0,0 +1,24 @@
+import { Locator, Page } from '@playwright/test';
+import { Harness } from './Harness';
+/**
+ * Drives the `@ghentcdh/ui` `SelectComponent`.
+ *
+ * Combobox button (`role="combobox"`) opens a portaled `role="listbox"` with
+ * `role="option"` items, each containing an `<a>` that emits the selection.
+ */
+export declare class SelectHarness extends Harness {
+    static byId(parent: Locator | Page, id: string): SelectHarness;
+    static byLabel(parent: Locator | Page, label: string): SelectHarness;
+    static for(locator: Locator): SelectHarness;
+    open(): Promise<this>;
+    fill(label: string): Promise<this>;
+    select(label: string): Promise<this>;
+    value(): Promise<string>;
+    /** Click the "Clear" button rendered next to the select. */
+    clear(): Promise<this>;
+    /**
+     * Click the "Create new" button. Requires `enableCreate` to be set on
+     * the component (SelectWrapper conditionally renders the button).
+     */
+    clickCreateNew(): Promise<void>;
+}

package/testing/TextAreaHarness.d.ts

@@ -0,0 +1,14 @@
+import { Locator, Page } from '@playwright/test';
+import { Harness } from './Harness';
+/**
+ * Drives the `@ghentcdh/ui` `Textarea` component.
+ * Plain text-area; use `MarkdownHarness` for the rich editor.
+ */
+export declare class TextAreaHarness extends Harness {
+    static byId(parent: Locator | Page, id: string): TextAreaHarness;
+    static byLabel(parent: Locator | Page, label: string): TextAreaHarness;
+    static for(locator: Locator): TextAreaHarness;
+    fill(value: string): Promise<this>;
+    clear(): Promise<this>;
+    value(): Promise<string>;
+}

package/testing/TextHarness.d.ts

@@ -0,0 +1,19 @@
+import { Locator, Page } from '@playwright/test';
+import { Harness } from './Harness';
+/**
+ * Drives the `@ghentcdh/ui` `Input` component. The component renders
+ * `<input aria-label="{id}">` inside a `ControlWrapper`, so we look up by
+ * the aria-label (= `id`) by default.
+ */
+export declare class TextHarness extends Harness {
+    static byId(parent: Locator | Page, id: string): TextHarness;
+    /** Resolve by visible label (the `<legend>` text). */
+    static byLabel(parent: Locator | Page, label: string): TextHarness;
+    static for(locator: Locator): TextHarness;
+    fill(value: string): Promise<this>;
+    /** Type character-by-character — useful when the control reacts to each keystroke. */
+    type(value: string): Promise<this>;
+    clear(): Promise<this>;
+    value(): Promise<string>;
+    blur(): Promise<this>;
+}

package/testing/index.d.ts

@@ -0,0 +1,14 @@
+export { Harness, byRole } from './Harness';
+export { TextHarness } from './TextHarness';
+export { NumberHarness } from './NumberHarness';
+export { TextAreaHarness } from './TextAreaHarness';
+export { BooleanHarness } from './BooleanHarness';
+export { SelectHarness } from './SelectHarness';
+export { AutocompleteHarness } from './AutocompleteHarness';
+export { MultiSelectHarness } from './MultiSelectHarness';
+export { MarkdownHarness, type MarkdownToolbarButton } from './MarkdownHarness';
+export { ModalHarness } from './ModalHarness';
+export { ButtonHarness } from './ButtonHarness';
+export { CollapseHarness } from './CollapseHarness';
+export { AlertHarness } from './AlertHarness';
+export { DrawerHarness } from './DrawerHarness';

package/testing.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});class r{constructor(t){this.locator=t}page(){return this.locator.page()}asLocator(){return this.locator}}const e=(x,t,a)=>x.getByRole(t,{name:a});class i extends r{static byId(t,a){return new i(e(t,"textbox",a))}static byLabel(t,a){return new i(e(t,"textbox",a))}static for(t){return new i(t)}async fill(t){return await this.locator.click(),await this.locator.fill(t),this}async type(t){return await this.locator.click(),await this.locator.pressSequentially(t),this}async clear(){return await this.locator.fill(""),this}async value(){return this.locator.inputValue()}async blur(){return await this.locator.press("Tab"),this}}class o extends r{static byId(t,a){return new o(e(t,"spinbutton",a))}static byLabel(t,a){return new o(e(t,"spinbutton",a))}static for(t){return new o(t)}async fill(t){return await this.locator.click(),await this.locator.fill(String(t)),await this.locator.press("Tab"),this}async clear(){return await this.locator.fill(""),this}async value(){const t=await this.locator.inputValue();return t===""?null:Number(t)}}class c extends r{static byId(t,a){return new c(e(t,"textbox",a))}static byLabel(t,a){return new c(e(t,"textbox",a))}static for(t){return new c(t)}async fill(t){return await this.locator.click(),await this.locator.fill(t),this}async clear(){return await this.locator.fill(""),this}async value(){return this.locator.inputValue()}}class s extends r{static byId(t,a){return new s(e(t,"checkbox",a))}static byLabel(t,a){return new s(e(t,"checkbox",a))}static for(t){return new s(t)}async fill(t){return t?await this.locator.check():await this.locator.uncheck(),this}async toggle(){return await this.locator.click(),this}async value(){return this.locator.isChecked()}}class n extends r{static byId(t,a){return new n(e(t,"combobox",a))}static byLabel(t,a){return new n(e(t,"combobox",a))}static for(t){return new n(t)}async open(){return await this.locator.click(),this}async fill(t){return this.select(t)}async select(t){return await this.open(),await this.page().getByRole("option",{name:t}).locator("a").click(),this}async value(){return(await this.locator.textContent())?.trim()??""}async clear(){return await this.locator.locator('xpath=ancestor::*[@role="select"][1]').getByRole("button",{name:"Clear"}).click(),this}async clickCreateNew(){await this.locator.locator('xpath=ancestor::*[@role="select"][1]').getByRole("button",{name:"create"}).click()}}class l extends r{static byId(t,a){return new l(e(t,"combobox",a))}static byLabel(t,a){return new l(e(t,"combobox",a))}static for(t){return new l(t)}async fill(t){return await this.locator.click(),await this.locator.fill(t),await this.page().getByRole("option",{name:t}).locator("a").click(),this}async query(t){return await this.locator.click(),await this.locator.fill(t),this}async pickOption(t){return await this.page().getByRole("option",{name:t}).locator("a").click(),this}async press(t){return await this.locator.press(t),this}async clickCreateNew(){await this.locator.locator('xpath=ancestor::*[@role="select"][1]').getByRole("button",{name:"create"}).click()}async clear(){return await this.locator.locator('xpath=ancestor::*[@role="select"][1]').getByRole("button",{name:"Clear"}).click(),this}async value(){return this.locator.inputValue()}listbox(){return this.page().getByRole("listbox")}options(){return this.page().getByRole("option")}}class u extends r{static byId(t,a){return new u(e(t,"combobox",a))}static byLabel(t,a){return new u(e(t,"combobox",a))}static for(t){return new u(t)}async open(){return await this.locator.click(),this}async fill(t){await this.open();for(const a of t)await this.page().getByRole("option",{name:a}).locator("a").click();return await this.locator.click(),this}async select(t){return await this.open(),await this.page().getByRole("option",{name:t}).locator("a").click(),this}async removeChip(t){return await this.locator.locator('xpath=ancestor::*[@role="select"][1]').getByText(t,{exact:!0}).getByRole("button").click(),this}}class h extends r{static byId(t,a){return new h(e(t,"textbox",a))}static byLabel(t,a){return new h(e(t,"textbox",a))}static for(t){return new h(t)}get editor(){return this.locator.getByRole("textbox")}async fill(t){return await this.editor.fill(t),this}async clear(){return await this.editor.fill(""),this}async typeBold(t){return await this.toolbar("B").click(),await this.editor.pressSequentially(t),await this.toolbar("B").click(),this}async typeItalic(t){return await this.toolbar("I").click(),await this.editor.pressSequentially(t),await this.toolbar("I").click(),this}async type(t){return await this.editor.pressSequentially(t),this}toolbar(t){return this.locator.getByRole("button",{name:t})}async isMarkActive(t){return(await this.toolbar(t).getAttribute("class")??"").includes("btn-active")}}class y extends r{static byTitle(t,a){return new y(t.getByRole("dialog",{name:a}))}static current(t){return new y(t.getByRole("dialog"))}static for(t){return new y(t)}async clickClose(){return await this.locator.getByRole("button",{name:"Close"}).click(),this}async pressEscape(){return await this.locator.press("Escape"),this}async clickBackdrop(){return await this.locator.click({position:{x:5,y:5}}),this}async clickAction(t){return await this.locator.getByRole("button",{name:t}).click(),this}title(){return this.locator.locator("h3").first()}content(){return this.locator.locator('[id$="_content"]').first()}asLocator(){return this.locator}}class b extends r{static byName(t,a){return new b(e(t,"button",a))}static for(t){return new b(t)}async click(){return await this.locator.click(),this}async isDisabled(){return this.locator.isDisabled()}async text(){return await this.locator.textContent()??""}}class p extends r{static byTitle(t,a){const f=t.getByLabel(`Toggle ${a}`);return new p(f.locator(".."))}static for(t){return new p(t)}async toggle(){return await this.checkbox().click(),this}async isOpen(){return this.checkbox().isChecked()}title(){return this.locator.locator(".collapse-title span").first()}content(){return this.locator.locator(".collapse-content")}checkbox(){return this.locator.locator('input[type="checkbox"]')}}class w extends r{static byMessage(t,a){return new w(t.getByRole("alert").filter({hasText:a}))}static first(t){return new w(t.getByRole("alert").first())}static for(t){return new w(t)}async message(){return await this.locator.locator("span").textContent()??""}async hasClass(t){return(await this.locator.getAttribute("class")??"").includes(t)}}class g extends r{static root(t){return new g(t.locator("main").first())}static for(t){return new g(t)}async toggleLeft(){return await this.leftButton().click(),this}async toggleRight(){return await this.rightButton().click(),this}async isLeftOpen(){return await this.leftButton().getAttribute("aria-expanded")==="true"}async isRightOpen(){return await this.rightButton().getAttribute("aria-expanded")==="true"}leftPanel(){return this.locator.locator("#drawer-left-panel")}rightPanel(){return this.locator.locator("#drawer-right-panel")}leftButton(){return this.locator.locator('button[aria-controls="drawer-left-panel"]')}rightButton(){return this.locator.locator('button[aria-controls="drawer-right-panel"]')}}exports.AlertHarness=w;exports.AutocompleteHarness=l;exports.BooleanHarness=s;exports.ButtonHarness=b;exports.CollapseHarness=p;exports.DrawerHarness=g;exports.Harness=r;exports.MarkdownHarness=h;exports.ModalHarness=y;exports.MultiSelectHarness=u;exports.NumberHarness=o;exports.SelectHarness=n;exports.TextAreaHarness=c;exports.TextHarness=i;exports.byRole=e;