@duplojs/agents-kit 0.1.0-beta.3 → 0.1.0-beta.6

package/docs/API/50-form/10-vue/10-construction/fixtures/AddressInput.vue

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+defineProps<{
+	hint: string;
+	placeholder?: string;
+}>();
+const model = defineModel<string>({ required: true });
+</script>
+
+<template>
+	<div>
+		<input
+			v-model="model"
+			:placeholder="placeholder"
+			type="email"
+		/>
+
+		<small>{{ hint }}</small>
+	</div>
+</template>

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

@@ -0,0 +1,24 @@
+### Construction de formulaires
+
+Fabriques de formulaires, de champs et de templates.
+
+### [createForm](10-createForm.ts)
+
+Associer des templates à une fabrique de formulaires Vue.
+ 
+### [createFormField](10-createFormField.ts)
+
+Construire une primitive de champ personnalisée pour un formulaire Vue.
+ 
+### [createGridTemplates](10-createGridTemplates.ts)
+
+Configurer les templates Vue en grille et leurs commandes.
+ 
+### [createInput](10-createInput.ts)
+
+Construire un champ à partir d'un composant Vue compatible avec v-model.
+ 
+### [createTemplate](10-createTemplate.ts)
+
+Configurer un composant Vue comme template de formulaire.
+ 

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

@@ -0,0 +1,3 @@
+### Construction de formulaires
+
+Fabriques de formulaires, de champs et de templates.

package/docs/API/50-form/10-vue/20-layouts/10-useCheckLayout.ts

@@ -0,0 +1,40 @@
+/**
+ * @title useCheckLayout
+ *
+ * Ajouter une validation à un champ ou à une composition de champs.
+ */
+import { useCheckLayout, type GetFormFieldCheckedValue, type GetFormFieldValue } from "@duplojs/form/vue";
+import { useTextInput } from "@duplojs/form/vueDesignSystem";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DString from "@duplojs/lang/string";
+import * as DEither from "@duplojs/lang/either";
+
+const email = useCheckLayout(
+	useTextInput({ label: "Email" }),
+	{
+		dataStructure: DDataStructure.string([DDataStructure.email()]),
+	},
+);
+
+type _Raw = DCommon.ExpectType<
+	GetFormFieldValue<typeof email>,
+	string,
+	"strict"
+>;
+type _Checked = DCommon.ExpectType<
+	GetFormFieldCheckedValue<typeof email>,
+	string & DString.Email,
+	"strict"
+>;
+
+// refine reçoit la valeur déjà vérifiée par le champ et produit un message en cas de refus.
+const username = useCheckLayout(
+	useTextInput({ label: "Username" }),
+	{
+		refine: (value) => value === "admin"
+			? DEither.error("Reserved name")
+			: DEither.ok(),
+	},
+);
+void username;

package/docs/API/50-form/10-vue/20-layouts/10-useDisabledLayout.ts

@@ -0,0 +1,34 @@
+/**
+ * @title useDisabledLayout
+ *
+ * Retirer conditionnellement un champ du rendu et de la validation.
+ */
+import { useDisabledLayout, type GetFormFieldCheckedValue, type GetFormFieldValue } from "@duplojs/form/vue";
+import { useTextInput } from "@duplojs/form/vueDesignSystem";
+import type * as DCommon from "@duplojs/lang/common";
+import { ref } from "vue";
+
+const isGuest = ref(true);
+
+const company = useDisabledLayout(
+	useTextInput({
+		label: "Company",
+	}),
+	{
+		isDisabled: () => isGuest.value,
+	},
+);
+
+// Le modèle garde la saisie pendant que le champ est masqué.
+type _Raw = DCommon.ExpectType<
+	GetFormFieldValue<typeof company>,
+	string,
+	"strict"
+>;
+
+// Lorsque isDisabled retourne true, check ne valide pas l'enfant et réussit avec undefined.
+type _Checked = DCommon.ExpectType<
+	GetFormFieldCheckedValue<typeof company>,
+	string | undefined,
+	"strict"
+>;

package/docs/API/50-form/10-vue/20-layouts/10-useMultiLayout.ts

@@ -0,0 +1,32 @@
+/**
+ * @title useMultiLayout
+ *
+ * Assembler plusieurs champs dans une valeur objet.
+ */
+import { useMultiLayout, type GetFormFieldValue } from "@duplojs/form/vue";
+import { useNumberInput, useTextInput } from "@duplojs/form/vueDesignSystem";
+import type * as DCommon from "@duplojs/lang/common";
+
+const profile = useMultiLayout({
+	name: useTextInput(),
+	age: useNumberInput(),
+});
+
+// Chaque clé conserve le type de son champ.
+type _Raw = DCommon.ExpectType<
+	GetFormFieldValue<typeof profile>,
+	{
+		name: string;
+		age: number;
+	},
+	"strict"
+>;
+
+// Les entrées permettent de construire les clés dynamiquement ; leur type devient un dictionnaire.
+declare const names: [string, ReturnType<typeof useTextInput>][];
+const dynamicFields = useMultiLayout(names);
+type _Dynamic = DCommon.ExpectType<
+	GetFormFieldValue<typeof dynamicFields>,
+	{ [key: string]: string },
+	"strict"
+>;

package/docs/API/50-form/10-vue/20-layouts/10-useRepeatLayout.ts

@@ -0,0 +1,34 @@
+/**
+ * @title useRepeatLayout
+ *
+ * Répéter un champ avec une cardinalité minimale et maximale.
+ */
+import { useRepeatLayout, type GetFormFieldValue } from "@duplojs/form/vue";
+import { useTextInput } from "@duplojs/form/vueDesignSystem";
+import type * as DCommon from "@duplojs/lang/common";
+
+const contacts = useRepeatLayout(
+	useTextInput({ label: "Contact" }),
+	{
+		min: 1,
+		max: 3,
+	},
+);
+
+// Le minimum littéral garantit un premier élément ; max borne les actions au runtime.
+type _Contacts = DCommon.ExpectType<
+	GetFormFieldValue<typeof contacts>,
+	[string, ...string[]],
+	"strict"
+>;
+
+const optionalContacts = useRepeatLayout(
+	useTextInput(),
+	{ max: 3 },
+);
+
+type _Optional = DCommon.ExpectType<
+	GetFormFieldValue<typeof optionalContacts>,
+	string[],
+	"strict"
+>;

package/docs/API/50-form/10-vue/20-layouts/10-useSectionLayout.ts

@@ -0,0 +1,20 @@
+/**
+ * @title useSectionLayout
+ *
+ * Présenter un champ dans une section sans modifier sa valeur.
+ */
+import { useSectionLayout, type GetFormFieldValue } from "@duplojs/form/vue";
+import { useTextInput } from "@duplojs/form/vueDesignSystem";
+import type * as DCommon from "@duplojs/lang/common";
+
+const section = useSectionLayout(
+	useTextInput({ label: "Name" }),
+	{ title: "Profile" },
+);
+
+// La section change le rendu sans modifier le modèle ou le résultat validé.
+type _Value = DCommon.ExpectType<
+	GetFormFieldValue<typeof section>,
+	string,
+	"strict"
+>;

package/docs/API/50-form/10-vue/20-layouts/10-useSlotLayout.ts

@@ -0,0 +1,37 @@
+/**
+ * @title useSlotLayout
+ *
+ * Exposer un slot Vue pour personnaliser le rendu ou fournir un champ manuel.
+ */
+import { useSlotLayout, type GetFormFieldCheckedValue, type GetFormFieldSlots } from "@duplojs/form/vue";
+import { useTextInput } from "@duplojs/form/vueDesignSystem";
+import type * as DCommon from "@duplojs/lang/common";
+
+// Le slot reçoit value, update et formField.
+const note = useSlotLayout(
+	"note",
+	useTextInput({ label: "Note" }),
+);
+
+type _Checked = DCommon.ExpectType<
+	GetFormFieldCheckedValue<typeof note>,
+	string | undefined,
+	"strict"
+>;
+type _SlotName = DCommon.ExpectType<
+	keyof GetFormFieldSlots<typeof note>,
+	"note",
+	"strict"
+>;
+
+// Sans champ enveloppé, le slot fournit directement la valeur initiale et update.
+const rating = useSlotLayout(
+	"rating",
+	{ defaultValue: 0 },
+);
+
+type _Rating = DCommon.ExpectType<
+	GetFormFieldCheckedValue<typeof rating>,
+	0,
+	"strict"
+>;

package/docs/API/50-form/10-vue/20-layouts/10-useStepLayout.ts

@@ -0,0 +1,31 @@
+/**
+ * @title useStepLayout
+ *
+ * Répartir des champs dans un parcours à étapes.
+ */
+import { useStepLayout, type GetFormFieldCheckedValue, type GetFormFieldValue } from "@duplojs/form/vue";
+import { useNumberInput, useTextInput } from "@duplojs/form/vueDesignSystem";
+import type * as DCommon from "@duplojs/lang/common";
+
+const registration = useStepLayout(
+	[
+		useTextInput({ label: "Name" }),
+		useNumberInput({ label: "Age" }),
+	],
+	{ errorMessageNotAtLastStep: "Complete all steps" },
+);
+
+// Le check final refuse une soumission avant la dernière étape et revient à la première étape invalide.
+type _Raw = DCommon.ExpectType<
+	GetFormFieldValue<typeof registration>,
+	{
+		currentStep: 0 | 1;
+		steps: [string, number];
+	},
+	"strict"
+>;
+type _Checked = DCommon.ExpectType<
+	GetFormFieldCheckedValue<typeof registration>,
+	readonly [string, number],
+	"strict"
+>;

package/docs/API/50-form/10-vue/20-layouts/10-useUnionLayout.ts

@@ -0,0 +1,48 @@
+/**
+ * @title useUnionLayout
+ *
+ * Choisir une variante de champ et conserver sa valeur associée.
+ */
+import { createForm, useUnionLayout } from "@duplojs/form/vue";
+import { useNumberInput, useTextInput } from "@duplojs/form/vueDesignSystem";
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+import { grid } from "../fixtures/templates";
+
+const useForm = createForm(grid.useTemplates());
+const { currentValue, check, dispose } = useForm(
+	useUnionLayout(
+		[
+			["email", useTextInput({ label: "Email" })],
+			["pickup", useNumberInput({ label: "Pickup point" })],
+		],
+		{ defaultKind: "email" },
+	),
+);
+
+// La valeur explicite correspond au kind choisi ; le retour à email restaure sa saisie précédente.
+currentValue.value.value = "contact@example.com";
+currentValue.value.updateKind("pickup", 42);
+currentValue.value.updateKind("email");
+
+const result = await check();
+if (DEither.isRight(result)) {
+	const delivery = DEither.unwrapRight(result);
+
+	// La valeur validée correspond à la variante active, sans la méthode updateKind.
+	if (delivery.kind === "email") {
+		type _Email = DCommon.ExpectType<
+			typeof delivery.value,
+			string,
+			"strict"
+		>;
+	} else {
+		type _Pickup = DCommon.ExpectType<
+			typeof delivery.value,
+			number,
+			"strict"
+		>;
+	}
+}
+
+dispose();

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

@@ -0,0 +1,36 @@
+### Layouts
+
+Composition des champs et ajout de structure, validation, contrôle de flux et slots.
+
+### [useCheckLayout](10-useCheckLayout.ts)
+
+Ajouter une validation à un champ ou à une composition de champs.
+ 
+### [useDisabledLayout](10-useDisabledLayout.ts)
+
+Retirer conditionnellement un champ du rendu et de la validation.
+ 
+### [useMultiLayout](10-useMultiLayout.ts)
+
+Assembler plusieurs champs dans une valeur objet.
+ 
+### [useRepeatLayout](10-useRepeatLayout.ts)
+
+Répéter un champ avec une cardinalité minimale et maximale.
+ 
+### [useSectionLayout](10-useSectionLayout.ts)
+
+Présenter un champ dans une section sans modifier sa valeur.
+ 
+### [useSlotLayout](10-useSlotLayout.ts)
+
+Exposer un slot Vue pour personnaliser le rendu ou fournir un champ manuel.
+ 
+### [useStepLayout](10-useStepLayout.ts)
+
+Répartir des champs dans un parcours à étapes.
+ 
+### [useUnionLayout](10-useUnionLayout.ts)
+
+Choisir une variante de champ et conserver sa valeur associée.
+ 

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

@@ -0,0 +1,3 @@
+### Layouts
+
+Composition des champs et ajout de structure, validation, contrôle de flux et slots.

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

@@ -0,0 +1,13 @@
+/**
+ * @title useCheckbox
+ *
+ * Saisir une valeur booléenne avec une case.
+ */
+import { useCheckbox } from "@duplojs/form/vueDesignSystem";
+
+// La case est initialement décochée.
+const newsletter = useCheckbox({
+	label: "Subscribe to updates",
+});
+
+void newsletter;

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

@@ -0,0 +1,18 @@
+/**
+ * @title useCheckboxPolicy
+ *
+ * Présenter une case de consentement.
+ */
+import { useCheckboxPolicy } from "@duplojs/form/vueDesignSystem";
+
+// La case est initialement décochée ; check échoue tant que required est vrai et que la case reste décochée.
+const policy = useCheckboxPolicy({
+	label: "Privacy policy",
+	props: {
+		title: "I accept the privacy policy",
+		required: true,
+		errorMessage: "Acceptance is required",
+	},
+});
+
+void policy;

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

@@ -0,0 +1,20 @@
+/**
+ * @title useDateInput
+ *
+ * Choisir une date Chrono.
+ */
+import { useDateInput } 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 date initiale est calculée avec DChrono.now() à la création du champ.
+const date = useDateInput({
+	label: "Appointment date",
+});
+
+type _Value = DCommon.ExpectType<
+	GetFormFieldValue<typeof date>,
+	DChrono.TheDate | DChrono.SerializedTheDate | null,
+	"strict"
+>;

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

@@ -0,0 +1,27 @@
+/**
+ * @title useDualRangeInput
+ *
+ * Choisir les deux extrémités numériques d’une plage.
+ */
+import { useDualRangeInput } from "@duplojs/form/vueDesignSystem";
+import type { GetFormFieldValue } from "@duplojs/form/vue";
+import type * as DCommon from "@duplojs/lang/common";
+
+// La plage initiale est { start: 0, end: 100 }.
+const price = useDualRangeInput({
+	label: "Price range",
+	props: {
+		min: 0,
+		max: 100,
+		step: 5,
+	},
+});
+
+type _Value = DCommon.ExpectType<
+	GetFormFieldValue<typeof price>,
+	{
+		start: number;
+		end: number;
+	},
+	"strict"
+>;

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

@@ -0,0 +1,23 @@
+/**
+ * @title useFileInput
+ *
+ * Sélectionner un ou plusieurs fichiers.
+ */
+import { useFileInput } from "@duplojs/form/vueDesignSystem";
+import type { GetFormFieldValue } from "@duplojs/form/vue";
+import type * as DCommon from "@duplojs/lang/common";
+
+// La valeur initiale est null ; le composant accepte une liste de fichiers.
+const attachments = useFileInput({
+	label: "Attachments",
+	props: {
+		accept: ".pdf",
+		multiple: true,
+	},
+});
+
+type _Value = DCommon.ExpectType<
+	GetFormFieldValue<typeof attachments>,
+	File[] | null,
+	"strict"
+>;

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;