@duplojs/agents-kit 0.0.0-stage → 0.1.0-beta.6

package/docs/API/50-form/10-vue/30-designSystem/10-useNumberInput.ts

@@ -0,0 +1,18 @@
+/**
+ * @title useNumberInput
+ *
+ * Saisir un nombre.
+ */
+import { useNumberInput } from "@duplojs/form/vueDesignSystem";
+
+// La valeur initiale est zéro ; les bornes configurent le composant.
+const quantity = useNumberInput({
+	label: "Quantity",
+	props: {
+		min: 0,
+		max: 100,
+		step: 1,
+	},
+});
+
+void quantity;

package/docs/API/50-form/10-vue/30-designSystem/10-useRadioGroup.ts

@@ -0,0 +1,31 @@
+/**
+ * @title useRadioGroup
+ *
+ * Choisir une option avec des boutons radio.
+ */
+import { useRadioGroup } from "@duplojs/form/vueDesignSystem";
+import type { GetFormFieldValue } from "@duplojs/form/vue";
+import type * as DCommon from "@duplojs/lang/common";
+
+// La sélection initiale est null.
+const frequency = useRadioGroup({
+	label: "Frequency",
+	props: {
+		options: [
+			{
+				label: "Daily",
+				value: "daily",
+			},
+			{
+				label: "Weekly",
+				value: "weekly",
+			},
+		],
+	},
+});
+
+type _Value = DCommon.ExpectType<
+	GetFormFieldValue<typeof frequency>,
+	string | null,
+	"strict"
+>;

package/docs/API/50-form/10-vue/30-designSystem/10-useRangeDateInput.ts

@@ -0,0 +1,23 @@
+/**
+ * @title useRangeDateInput
+ *
+ * Choisir un intervalle de dates Chrono.
+ */
+import { useRangeDateInput } from "@duplojs/form/vueDesignSystem";
+import type { GetFormFieldValue } from "@duplojs/form/vue";
+import type * as DCommon from "@duplojs/lang/common";
+import type * as DChrono from "@duplojs/lang/chrono";
+
+// La valeur comporte from et to ; les dates initiales sont le jour courant et le lendemain.
+const period = useRangeDateInput({
+	label: "Booking period",
+});
+
+type _Value = DCommon.ExpectType<
+	GetFormFieldValue<typeof period>,
+	{
+		from: DChrono.TheDate | DChrono.SerializedTheDate | null;
+		to: DChrono.TheDate | DChrono.SerializedTheDate | null;
+	},
+	"strict"
+>;

package/docs/API/50-form/10-vue/30-designSystem/10-useRangeInput.ts

@@ -0,0 +1,18 @@
+/**
+ * @title useRangeInput
+ *
+ * Choisir un nombre avec un curseur.
+ */
+import { useRangeInput } from "@duplojs/form/vueDesignSystem";
+
+// La valeur initiale est zéro ; les bornes configurent le curseur.
+const volume = useRangeInput({
+	label: "Volume",
+	props: {
+		min: 0,
+		max: 100,
+		step: 5,
+	},
+});
+
+void volume;

package/docs/API/50-form/10-vue/30-designSystem/10-useRangeTimeInput.ts

@@ -0,0 +1,23 @@
+/**
+ * @title useRangeTimeInput
+ *
+ * Choisir un intervalle d’heures Chrono.
+ */
+import { useRangeTimeInput } from "@duplojs/form/vueDesignSystem";
+import type { GetFormFieldValue } from "@duplojs/form/vue";
+import type * as DCommon from "@duplojs/lang/common";
+import type * as DChrono from "@duplojs/lang/chrono";
+
+// La valeur comporte from et to, initialisées à zéro seconde.
+const hours = useRangeTimeInput({
+	label: "Opening hours",
+});
+
+type _Value = DCommon.ExpectType<
+	GetFormFieldValue<typeof hours>,
+	{
+		from: DChrono.TheTime | DChrono.SerializedTheTime | null;
+		to: DChrono.TheTime | DChrono.SerializedTheTime | null;
+	},
+	"strict"
+>;

package/docs/API/50-form/10-vue/30-designSystem/10-useSelectInput.ts

@@ -0,0 +1,31 @@
+/**
+ * @title useSelectInput
+ *
+ * Choisir une option dans une liste déroulante.
+ */
+import { useSelectInput } from "@duplojs/form/vueDesignSystem";
+import type { GetFormFieldValue } from "@duplojs/form/vue";
+import type * as DCommon from "@duplojs/lang/common";
+
+// La sélection initiale est null.
+const priority = useSelectInput({
+	label: "Priority",
+	props: {
+		options: [
+			{
+				label: "High",
+				value: "high",
+			},
+			{
+				label: "Low",
+				value: "low",
+			},
+		],
+	},
+});
+
+type _Value = DCommon.ExpectType<
+	GetFormFieldValue<typeof priority>,
+	string | null,
+	"strict"
+>;

package/docs/API/50-form/10-vue/30-designSystem/10-useTextInput.ts

@@ -0,0 +1,14 @@
+/**
+ * @title useTextInput
+ *
+ * Saisir un texte court.
+ */
+import { useTextInput } from "@duplojs/form/vueDesignSystem";
+
+// Une chaîne vide est utilisée initialement.
+const title = useTextInput({
+	label: "Title",
+	props: { placeholder: "Article title" },
+});
+
+void title;

package/docs/API/50-form/10-vue/30-designSystem/10-useTextareaInput.ts

@@ -0,0 +1,14 @@
+/**
+ * @title useTextareaInput
+ *
+ * Saisir un texte multiligne.
+ */
+import { useTextareaInput } from "@duplojs/form/vueDesignSystem";
+
+// La valeur initiale est une chaîne vide.
+const description = useTextareaInput({
+	label: "Description",
+	props: { placeholder: "Describe the issue" },
+});
+
+void description;

package/docs/API/50-form/10-vue/30-designSystem/10-useTimeInput.ts

@@ -0,0 +1,20 @@
+/**
+ * @title useTimeInput
+ *
+ * Choisir une heure Chrono.
+ */
+import { useTimeInput } from "@duplojs/form/vueDesignSystem";
+import type { GetFormFieldValue } from "@duplojs/form/vue";
+import type * as DCommon from "@duplojs/lang/common";
+import type * as DChrono from "@duplojs/lang/chrono";
+
+// La valeur initiale correspond à zéro seconde.
+const time = useTimeInput({
+	label: "Opening time",
+});
+
+type _Value = DCommon.ExpectType<
+	GetFormFieldValue<typeof time>,
+	DChrono.TheTime | DChrono.SerializedTheTime | null,
+	"strict"
+>;

package/docs/API/50-form/10-vue/30-designSystem/20-components.md

@@ -0,0 +1,11 @@
+#### Composants et champs fournis
+
+Choisir les inputs et commandes Vue du design system.
+
+---
+
+Les fonctions `useTextInput`, `useTextareaInput`, `useNumberInput`, `useFileInput`, `useSelectInput`, `useRadioGroup`, `useCheckbox`, `useCheckboxPolicy`, `useRangeInput`, `useDualRangeInput`, `useDateInput`, `useRangeDateInput`, `useTimeInput` et `useRangeTimeInput` produisent des champs `FormField`. Elles acceptent les paramètres de `createInput`, dont `label`, `defaultValue`, `props` et `dataStructure`.
+
+Les valeurs initiales sont respectivement une chaîne vide pour les textes, zéro pour nombre et plage simple, `null` pour fichier, sélection et radio, `false` pour les cases, `{ start: 0, end: 100 }` pour la double plage, la date courante pour la date et des valeurs Chrono pour les dates et heures. Les intervalles date et heure utilisent `{ from, to }`. Les sélections et radios reçoivent leurs choix dans `props.options` ; les fichiers acceptent notamment `accept` et `multiple`.
+
+Les composants Vue correspondants sont aussi exportés pour une utilisation directe ou avec `createInput`. Les boutons `PrimaryButton`, `OutlineButton`, `DestructiveButton`, `GhostButton` et `TheButton` servent aux actions de l'interface. Les adaptateurs `templateFormAddButton`, `templateFormRemoveButton`, `templateFormResetButton`, `templateFormNextButton`, `templateFormPreviousButton` et `templateFormSelect` répondent aux contrats de commandes de Grid. Charger les styles avec `@duplojs/form/vueDesignSystem.css` et `@duplojs/form/vueGrid.css` dans l'application.

package/docs/API/50-form/10-vue/30-designSystem/index.llms.md

@@ -0,0 +1,65 @@
+### Design system
+
+Composants et inputs prêts à l'emploi pour construire les formulaires et les commandes des templates Grid.
+
+#### [Composants et champs fournis](20-components.md)
+
+Choisir les inputs et commandes Vue du design system.
+
+
+### [useCheckbox](10-useCheckbox.ts)
+
+Saisir une valeur booléenne avec une case.
+ 
+### [useCheckboxPolicy](10-useCheckboxPolicy.ts)
+
+Présenter une case de consentement.
+ 
+### [useDateInput](10-useDateInput.ts)
+
+Choisir une date Chrono.
+ 
+### [useDualRangeInput](10-useDualRangeInput.ts)
+
+Choisir les deux extrémités numériques d’une plage.
+ 
+### [useFileInput](10-useFileInput.ts)
+
+Sélectionner un ou plusieurs fichiers.
+ 
+### [useNumberInput](10-useNumberInput.ts)
+
+Saisir un nombre.
+ 
+### [useRadioGroup](10-useRadioGroup.ts)
+
+Choisir une option avec des boutons radio.
+ 
+### [useRangeDateInput](10-useRangeDateInput.ts)
+
+Choisir un intervalle de dates Chrono.
+ 
+### [useRangeInput](10-useRangeInput.ts)
+
+Choisir un nombre avec un curseur.
+ 
+### [useRangeTimeInput](10-useRangeTimeInput.ts)
+
+Choisir un intervalle d’heures Chrono.
+ 
+### [useSelectInput](10-useSelectInput.ts)
+
+Choisir une option dans une liste déroulante.
+ 
+### [useTextInput](10-useTextInput.ts)
+
+Saisir un texte court.
+ 
+### [useTextareaInput](10-useTextareaInput.ts)
+
+Saisir un texte multiligne.
+ 
+### [useTimeInput](10-useTimeInput.ts)
+
+Choisir une heure Chrono.
+ 

package/docs/API/50-form/10-vue/30-designSystem/index.md

@@ -0,0 +1,3 @@
+### Design system
+
+Composants et inputs prêts à l'emploi pour construire les formulaires et les commandes des templates Grid.

package/docs/API/50-form/10-vue/fixtures/templates.ts

@@ -0,0 +1,20 @@
+import { createGridTemplates } from "@duplojs/form/vueGrid";
+import { templateFormAddButton, templateFormNextButton, templateFormPreviousButton, templateFormRemoveButton, templateFormResetButton, templateFormSelect } from "@duplojs/form/vueDesignSystem";
+
+export const grid = createGridTemplates({
+	repeat: {
+		addLabel: "Add",
+		removeLabel: "Remove",
+		addButton: templateFormAddButton,
+		removeButton: templateFormRemoveButton,
+		resetButton: templateFormResetButton,
+	},
+	step: {
+		nextLabel: "Continue",
+		previousLabel: "Back",
+		nextButton: templateFormNextButton,
+		previousButton: templateFormPreviousButton,
+		resetButton: templateFormResetButton,
+	},
+	union: { selectInputKind: templateFormSelect },
+});

package/docs/API/50-form/10-vue/index.md

@@ -0,0 +1,3 @@
+## Form pour Vue
+
+Fabriques de formulaires, de champs et de templates pour l'intégration Vue.

package/docs/API/50-form/index.md

@@ -0,0 +1,3 @@
+# @duplojs/form
+
+Construction de formulaires typés à partir de champs composables et de leurs validations.

package/docs/API/60-playwright/10-construction/10-createComponent.ts

@@ -0,0 +1,47 @@
+/**
+ * @title createComponent
+ *
+ * Définir une zone réutilisable et ses éléments, méthodes et composants enfants.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import { createComponent, type Website } from "@duplojs/playwright";
+
+declare const website: Website;
+
+const feedbackEngine = createComponent("feedback", {
+	getMainElement: ({ body }) => body.locator("[data-search-feedback]"),
+});
+
+const searchFormEngine = createComponent("search form", {
+	getMainElement: ({ body }) => body.locator("form[data-search]"),
+	getElements: ({ mainElement }) => ({
+		query: mainElement.locator("input[name='query']"),
+		submit: mainElement.locator("button[type='submit']"),
+	}),
+	getMethods: ({ elements }) => ({
+		async search(query: string) {
+			await elements.query.fill(query);
+			await elements.submit.click();
+		},
+	}),
+	components: [feedbackEngine],
+});
+
+const searchForm = searchFormEngine(website);
+// Les éléments retournés par getElements deviennent les seules clés utilisables par les interactions.
+type _CheckElementKeys = DCommon.ExpectType<
+	keyof typeof searchForm.elements,
+	"query" | "submit",
+	"strict"
+>;
+await searchForm.methods.search("TypeScript");
+
+// La recherche par nom vérifie la visibilité de la racine et conserve le type de l’enfant.
+const feedback = await searchForm.iWantToSeeComponent("feedback");
+type _CheckFeedbackName = DCommon.ExpectType<
+	typeof feedback.name,
+	"feedback",
+	"strict"
+>;
+// Chaque fabrique enfant recherche sa racine depuis body, pas depuis la racine du parent.
+// Les méthodes personnalisées sont exécutées dans des étapes Playwright.

package/docs/API/60-playwright/10-construction/10-createComponentInteraction.ts

@@ -0,0 +1,28 @@
+/**
+ * @title createComponentInteraction
+ *
+ * Créer une interaction typée sur un élément nommé et une étape Playwright.
+ */
+import { createComponent, createComponentInteraction, type Website } from "@duplojs/playwright";
+
+declare const website: Website;
+
+const articleListEngine = createComponent("article list", {
+	getMainElement: ({ body }) => body.locator("[data-article-list]"),
+	getElements: ({ mainElement }) => ({ articles: mainElement.locator("article") }),
+});
+const articleList = articleListEngine(website);
+
+// Une interaction réutilisable lit l’identifiant métier d’un article de la liste.
+const readArticleId = createComponentInteraction(
+	"$component: read id of $element",
+	({ element }) => element.getAttribute("data-article-id"),
+);
+
+// Le tuple sélectionne le premier, le dernier ou l’élément d’indice zéro-based.
+const firstId = await readArticleId(articleList, ["articles", "first"]);
+await readArticleId(articleList, ["articles", "last"]);
+await readArticleId(articleList, ["articles", 1]);
+// Au runtime firstId vaut l’attribut ou null ; le retour public est typé Promise<any>.
+// Les marqueurs du titre sont remplacés par le nom du composant et la désignation choisie.
+// Une clé absente au runtime provoque MissingComponentElementError avant l’étape.

package/docs/API/60-playwright/10-construction/10-createPage.ts

@@ -0,0 +1,34 @@
+/**
+ * @title createPage
+ *
+ * Définir un écran navigable et son chemin typé.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import { createPage, type Website } from "@duplojs/playwright";
+
+declare const website: Website;
+
+const articlePage = createPage("article", {
+	makePath: ({ slug }: { slug: string }) => `/articles/${slug}`,
+	getMainElement: ({ body }) => body.locator("article"),
+	getElements: ({ mainElement }) => ({ title: mainElement.locator("h1") }),
+});
+
+// Le paramètre de makePath est requis par la navigation et choisit l’article affiché.
+const introduction = await website.iNavigateTo(articlePage, { slug: "introduction" });
+await website.iNavigateTo(articlePage, { slug: "testing" });
+
+// La navigation conserve le nom littéral et les éléments propres à cette page.
+type _CheckName = DCommon.ExpectType<
+	typeof introduction.name,
+	"article",
+	"strict"
+>;
+await introduction.elements.title.textContent();
+
+// Une page sans paramètre de chemin se navigue sans argument supplémentaire.
+const homePage = createPage("home", {
+	makePath: () => "/",
+	getMainElement: ({ body }) => body.locator("main"),
+});
+await website.iNavigateTo(homePage);

package/docs/API/60-playwright/10-construction/10-createStepWrapper.ts

@@ -0,0 +1,23 @@
+/**
+ * @title createStepWrapper
+ *
+ * Envelopper des interactions dans une étape Playwright personnalisée.
+ */
+import { createComponent, createComponentInteraction, createStepWrapper, type Website } from "@duplojs/playwright";
+
+declare const website: Website;
+
+const articleListEngine = createComponent("article list", {
+	getMainElement: ({ body }) => body.locator("[data-article-list]"),
+	getElements: ({ mainElement }) => ({ articles: mainElement.locator("article") }),
+});
+const articleList = articleListEngine(website);
+const readArticleId = createComponentInteraction(
+	"$component: read id of $element",
+	({ element }) => element.getAttribute("data-article-id"),
+);
+
+const withStep = createStepWrapper({ readArticleId });
+// Le rapport contient l’étape nommée autour de l’étape propre à l’interaction.
+const articleId = await withStep("Identifier le premier article").readArticleId(articleList, ["articles", "first"]);
+// La valeur runtime est celle de l’interaction enveloppée ; son type public reste any.

package/docs/API/60-playwright/10-construction/10-createWebsite.ts

@@ -0,0 +1,57 @@
+/**
+ * @title createWebsite
+ *
+ * Construire le contexte du site et naviguer ou vérifier ses pages et composants.
+ */
+import { createComponent, createPage, createWebsite } from "@duplojs/playwright";
+import type { BrowserContext, Page } from "playwright/test";
+
+declare const playwrightPage: Page;
+declare const playwrightBrowserContext: BrowserContext;
+
+const website = createWebsite({
+	playwrightPage,
+	playwrightBrowserContext,
+	envConfig: {
+		baseUrl: "https://example.com",
+		prefix: "admin",
+	},
+	hooks: {
+		beforeNavigateOnPage: () => playwrightPage.waitForLoadState(),
+		afterNavigateOnPage: () => playwrightPage.waitForLoadState(),
+	},
+});
+const dashboard = createPage("dashboard", {
+	makePath: () => "/dashboard",
+	getMainElement: ({ body }) => body.locator("main"),
+});
+const notice = createComponent("notice", {
+	getMainElement: ({ body }) => body.locator("[data-notice]"),
+});
+
+// URL https://example.com/admin/dashboard ; vérifie l’URL et la visibilité de la racine.
+await website.iNavigateTo(dashboard);
+
+// iGoTo navigue sans ces deux assertions ; les deux navigations exécutent les hooks.
+await website.iGoTo(dashboard);
+// racine visible, sans contrôle d’URL
+await website.iWantToBeOnPage(dashboard);
+// racine visible
+await website.iWantToSee(notice);
+// racine attachée au DOM
+await website.iWantToExist(notice);
+await website.iExpectTitleIs(/Dashboard/);
+await website.iExpectUrlIs(/dashboard/);
+await website.addCookies([
+	{
+		name: "session",
+		value: "token",
+		url: "https://example.com",
+	},
+]);
+// retire le préfixe pour les prochaines navigations
+website.setPrefix();
+// recharge puis exécute le hook afterNavigateOnPage
+await website.refresh();
+// attend [aria-hydrated="true"] visible pendant 5 s au plus
+await website.waitForHydration();

package/docs/API/60-playwright/10-construction/10-initClient.ts

@@ -0,0 +1,38 @@
+/**
+ * @title Initialiser un client de test Playwright
+ *
+ * Étendre le client Playwright avec une fixture Website DuploJS utilisable dans les tests.
+ */
+import { createPage, createWebsite, type Website } from "@duplojs/playwright";
+import test from "playwright/test";
+
+interface TestFixtures {
+	website: Website;
+}
+
+// Playwright fournit une page et un contexte isolés pour chaque test.
+export const testClient = test.extend<TestFixtures>({
+	async website({ page, context }, use) {
+		const website = createWebsite({
+			playwrightPage: page,
+			playwrightBrowserContext: context,
+			envConfig: {
+				baseUrl: "http://localhost:3000",
+			},
+		});
+
+		// La fixture met le Website à disposition pendant le test.
+		await use(website);
+	},
+});
+
+const homePage = createPage("home", {
+	makePath: () => "/",
+	getMainElement: ({ body }) => body.locator("main"),
+});
+
+// Les tests importent testClient et reçoivent la fixture typée parmi les fixtures Playwright.
+testClient("le site affiche son titre", async({ website }) => {
+	await website.iNavigateTo(homePage);
+	await website.iExpectTitleIs(/Accueil/);
+});

package/docs/API/60-playwright/10-construction/index.llms.md

@@ -0,0 +1,28 @@
+## Construction
+
+Fabriques de sites, pages, composants, interactions et wrappers de parcours.
+
+### [createComponent](10-createComponent.ts)
+
+Définir une zone réutilisable et ses éléments, méthodes et composants enfants.
+ 
+### [createComponentInteraction](10-createComponentInteraction.ts)
+
+Créer une interaction typée sur un élément nommé et une étape Playwright.
+ 
+### [createPage](10-createPage.ts)
+
+Définir un écran navigable et son chemin typé.
+ 
+### [createStepWrapper](10-createStepWrapper.ts)
+
+Envelopper des interactions dans une étape Playwright personnalisée.
+ 
+### [createWebsite](10-createWebsite.ts)
+
+Construire le contexte du site et naviguer ou vérifier ses pages et composants.
+ 
+### [Initialiser un client de test Playwright](10-initClient.ts)
+
+Étendre le client Playwright avec une fixture Website DuploJS utilisable dans les tests.
+ 

package/docs/API/60-playwright/10-construction/index.md

@@ -0,0 +1,3 @@
+## Construction
+
+Fabriques de sites, pages, composants, interactions et wrappers de parcours.

package/docs/API/60-playwright/20-actions/10-check.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Actions.check
+ *
+ * Cocher un élément visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+await Actions.check(searchForm, "onlyPublished");

package/docs/API/60-playwright/20-actions/10-clear.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Actions.clear
+ *
+ * Effacer un champ visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+await Actions.clear(searchForm, "query");

package/docs/API/60-playwright/20-actions/10-click.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Actions.click
+ *
+ * Cliquer sur un élément visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+await Actions.click(searchForm, "submit");

package/docs/API/60-playwright/20-actions/10-dragTo.ts

@@ -0,0 +1,10 @@
+/**
+ * @title Actions.dragTo
+ *
+ * Glisser un élément visible vers une cible visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { board } from "../fixtures/component";
+
+// La source et la cible doivent être visibles avant le glisser-déposer.
+await Actions.dragTo(board, "task", board.elements.doneColumn, { timeout: 5000 });

package/docs/API/60-playwright/20-actions/10-extractContent.ts

@@ -0,0 +1,10 @@
+/**
+ * @title Actions.extractContent
+ *
+ * Extraire le contenu textuel d’un élément visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { articleList } from "../fixtures/component";
+
+// Le résultat runtime est le texte du titre, ou null si son contenu textuel est absent.
+const title = await Actions.extractContent(articleList, "title");

package/docs/API/60-playwright/20-actions/10-fill.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Actions.fill
+ *
+ * Remplacer la valeur d’un champ visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+await Actions.fill(searchForm, "query", "TypeScript");

package/docs/API/60-playwright/20-actions/10-focus.ts

@@ -0,0 +1,9 @@
+/**
+ * @title Actions.focus
+ *
+ * Donner le focus à un élément visible.
+ */
+import { Actions } from "@duplojs/playwright";
+import { searchForm } from "../fixtures/component";
+
+await Actions.focus(searchForm, "query");