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

package/docs/concepts/03-client/20-form/10-init.ts

@@ -0,0 +1,98 @@
+/**
+ * @title Créer un formulaire
+ *
+ * Initialisation et cycle de vie d’un formulaire Vue typé.
+ */
+import { createForm, useCheckLayout, useMultiLayout, type DetailsError } from "@duplojs/form/vue";
+import { templateFormAddButton, templateFormNextButton, templateFormPreviousButton, templateFormRemoveButton, templateFormResetButton, templateFormSelect, useNumberInput, useTextInput } from "@duplojs/form/vueDesignSystem";
+import { createGridTemplates } from "@duplojs/form/vueGrid";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DCommon from "@duplojs/lang/common";
+import type * as DEither from "@duplojs/lang/either";
+import type * as DString from "@duplojs/lang/string";
+
+// `createForm` fixe le système de rendu utilisé par cette famille de formulaires.
+// `repeat`, `step` et `union` demandent des composants dédiés pour ajouter,
+// retirer, changer d'étape ou sélectionner une variante.
+const gridTemplates = createGridTemplates({
+	repeat: {
+		addLabel: "Add another item",
+		removeLabel: "Remove this item",
+		addButton: templateFormAddButton,
+		removeButton: templateFormRemoveButton,
+		resetButton: templateFormResetButton,
+	},
+	step: {
+		nextLabel: "Continue",
+		previousLabel: "Back",
+		resetButton: templateFormResetButton,
+		nextButton: templateFormNextButton,
+		previousButton: templateFormPreviousButton,
+	},
+	union: { selectInputKind: templateFormSelect },
+});
+
+const useForm = createForm(
+	gridTemplates.useTemplates(),
+);
+
+// Le champ racine porte le schéma métier du formulaire.
+// Il peut être un input simple ou une composition de layouts et d'inputs.
+// Ce champ est un `FormField` : `useForm` l’associe aux templates configurés
+// pour exposer le composant Vue, la valeur courante et les opérations du formulaire.
+const { check, component: TheForm, currentValue, dispose, reset } = useForm(
+	useMultiLayout({
+		name: useTextInput({
+			label: "Name",
+			props: {
+				placeholder: "Your name",
+			},
+		}),
+		email: useCheckLayout(
+			useTextInput({
+				label: "Email",
+				props: {
+					placeholder: "yourEmail@mail.com",
+				},
+			}),
+			{
+				dataStructure: DDataStructure.string([DDataStructure.email()]),
+			},
+		),
+		age: useNumberInput({
+			label: "Age",
+			defaultValue: 18,
+		}),
+	}),
+);
+
+// Valeur brute synchronisée avec l'état Vue du formulaire.
+type _CheckCurrentValue = DCommon.ExpectType<
+	typeof currentValue.value,
+	{
+		name: string;
+		email: string;
+		age: number;
+	},
+	"strict"
+>;
+void currentValue;
+
+// `check` applique les validations déclarées et type la valeur validée.
+const checkedValue = await check();
+type _CheckValue = DCommon.ExpectType<typeof checkedValue, DEither.Error<DetailsError> | DEither.Success<{
+	name: string;
+	email: string & DString.Email;
+	age: number;
+}>, "strict">;
+
+void checkedValue;
+
+// `reset` restaure les `defaultValue` et les états internes des champs.
+reset();
+
+// `dispose` libère les scopes internes, généralement au démontage.
+dispose();
+
+// `component` est le composant Vue à monter ; le submit reste applicatif.
+void TheForm;

package/docs/concepts/03-client/20-form/20-input.ts

@@ -0,0 +1,103 @@
+/**
+ * @title Inputs de formulaire réutilisables
+ *
+ * Création, intégration et validation des champs de saisie d’un formulaire Vue.
+ */
+import { createForm, createInput, type DetailsError, useMultiLayout } from "@duplojs/form/vue";
+import { TextInput, templateFormAddButton, templateFormNextButton, templateFormPreviousButton, templateFormRemoveButton, templateFormResetButton, templateFormSelect, useNumberInput, useTextInput } from "@duplojs/form/vueDesignSystem";
+import { createGridTemplates } from "@duplojs/form/vueGrid";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DCommon from "@duplojs/lang/common";
+import type * as DEither from "@duplojs/lang/either";
+import type * as DString from "@duplojs/lang/string";
+
+const gridTemplates = createGridTemplates({
+	repeat: {
+		addLabel: "Add another item",
+		removeLabel: "Remove this item",
+		addButton: templateFormAddButton,
+		removeButton: templateFormRemoveButton,
+		resetButton: templateFormResetButton,
+	},
+	step: {
+		nextLabel: "Continue",
+		previousLabel: "Back",
+		resetButton: templateFormResetButton,
+		nextButton: templateFormNextButton,
+		previousButton: templateFormPreviousButton,
+	},
+	union: { selectInputKind: templateFormSelect },
+});
+
+const useForm = createForm(
+	gridTemplates.useTemplates(),
+);
+
+// Les inputs du design system sont déjà des briques de formulaire.
+// Ils retournent directement des champs composables dans `useForm`, avec des
+// props inférées depuis leur composant Vue.
+// Leur association composant/input peut aussi servir de référence pour créer
+// les inputs propres à une application.
+const { component: TheForm, currentValue } = useForm(
+	useMultiLayout({
+		name: useTextInput({
+			label: "Name",
+			props: {
+				placeholder: "Your name",
+			},
+		}),
+		age: useNumberInput({
+			label: "Age",
+			defaultValue: 18,
+		}),
+	}),
+);
+
+type _CheckCurrentValue = DCommon.ExpectType<typeof currentValue.value, {
+	name: string;
+	age: number;
+}, "strict">;
+void currentValue;
+void TheForm;
+
+// `createInput` transforme un composant Vue compatible en input de formulaire.
+// Le composant seul ne fournit pas de `FormField` : la fonction obtenue avec
+// `createInput` crée ce champ, composable dans un layout ou directement dans `useForm`.
+// Le contrat minimal du composant est de porter sa valeur avec `modelValue`
+// et `update:modelValue`. Il peut aussi exposer `check`, `reset` ou `dispose`
+// si son comportement interne en a besoin.
+const useCustomTextInput = createInput(
+	TextInput,
+	{
+		defaultValue: "custom text",
+		props: {
+			placeholder: "Your text",
+		},
+	},
+);
+
+// `defaultValue` est obligatoire : c'est la valeur initiale de l'input.
+// Elle peut être une valeur directe ou une fonction.
+// Les paramètres passés à l'utilisation complètent ou remplacent ensuite
+// les valeurs par défaut de `createInput`.
+const { check } = useForm(
+	useCustomTextInput({
+		label: "Email",
+		defaultValue: "",
+		props: {
+			placeholder: "yourEmail@mail.com",
+		},
+		dataStructure: DDataStructure.string([DDataStructure.email()]),
+	}),
+);
+
+// Lors du `check`, la librairie appelle d'abord le `check` exposé par le
+// composant s'il existe, puis applique la `dataStructure` de l'input.
+const checkedEmail = await check();
+type _CheckCheckedEmail = DCommon.ExpectType<
+	typeof checkedEmail,
+	DEither.Error<DetailsError> | DEither.Success<string & DString.Email>,
+	"strict"
+>;
+
+void checkedEmail;

package/docs/concepts/03-client/20-form/30-layout.ts

@@ -0,0 +1,155 @@
+/**
+ * @title Composer avec les layouts
+ *
+ * Composition de la structure des données et des comportements d’un formulaire.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import type * as DEither from "@duplojs/lang/either";
+import { createForm, type DetailsError, useCheckLayout, useDisabledLayout, useMultiLayout, useRepeatLayout, useSectionLayout, useSlotLayout, useStepLayout, useUnionLayout } from "@duplojs/form/vue";
+import { templateFormAddButton, templateFormNextButton, templateFormPreviousButton, templateFormRemoveButton, templateFormResetButton, templateFormSelect, useTextareaInput, useTextInput } from "@duplojs/form/vueDesignSystem";
+import { createGridTemplates } from "@duplojs/form/vueGrid";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DString from "@duplojs/lang/string";
+import { ref } from "vue";
+
+const gridTemplates = createGridTemplates({
+	repeat: {
+		addLabel: "Add another item",
+		removeLabel: "Remove this item",
+		addButton: templateFormAddButton,
+		removeButton: templateFormRemoveButton,
+		resetButton: templateFormResetButton,
+	},
+	step: {
+		nextLabel: "Continue",
+		previousLabel: "Back",
+		resetButton: templateFormResetButton,
+		nextButton: templateFormNextButton,
+		previousButton: templateFormPreviousButton,
+	},
+	union: { selectInputKind: templateFormSelect },
+});
+
+const useForm = createForm(
+	gridTemplates.useTemplates(),
+);
+
+// Les layouts de structure modifient directement la forme de `currentValue`
+// et la forme de la valeur retournée par `check`.
+// Un layout reçoit un ou plusieurs champs et produit un nouveau `FormField`.
+// Ici, les inputs sont composés dans des layouts, eux-mêmes imbriqués dans
+// `useMultiLayout`, puis `useSectionLayout` fournit le champ racine à `useForm`.
+const { check: checkStructureForm, component: StructureForm, currentValue: currentStructureValue } = useForm(
+	useSectionLayout(
+		useMultiLayout({
+			identity: useMultiLayout({
+				firstName: useTextInput({ label: "First name" }),
+				lastName: useTextInput({ label: "Last name" }),
+			}),
+			contacts: useRepeatLayout(
+				useTextInput({ label: "Email" }),
+				{
+					min: 1,
+					max: 3,
+				},
+			),
+			preferredContact: useUnionLayout(
+				[
+					["email", useTextInput({ label: "Email" })],
+					["phone", useTextInput({ label: "Phone" })],
+				],
+				{ defaultKind: "email" },
+			),
+			message: useSlotLayout(
+				"customMessage",
+				useTextareaInput({ label: "Message" }),
+			),
+		}),
+		{ title: "Profile" },
+	),
+);
+
+type _CheckContacts = DCommon.ExpectType<typeof currentStructureValue.value.contacts, [string, ...string[]], "strict">;
+type _CheckPreferredContactKind = DCommon.ExpectType<
+	typeof currentStructureValue.value.preferredContact.kind,
+	"email" | "phone",
+	"strict"
+>;
+void currentStructureValue;
+
+const checkedStructureValue = await checkStructureForm();
+type _CheckCheckedStructureValueLine96 = DCommon.ExpectType<
+	typeof checkedStructureValue,
+	DEither.Error<DetailsError> | DEither.Success<{
+		identity: {
+			firstName: string;
+			lastName: string;
+		};
+		contacts: [string, ...string[]];
+		preferredContact: {
+			kind: "email";
+			value: string;
+		} | {
+			kind: "phone";
+			value: string;
+		};
+		message: string | undefined;
+	}>,
+	"strict"
+>;
+
+void checkedStructureValue;
+void StructureForm;
+
+const hasCompany = ref(false);
+
+// Les layouts de contrôle changent surtout le flux du formulaire.
+// `step` impose une progression, `check` ajoute une validation autour d'un
+// champ existant, et `disabled` retire temporairement un champ du rendu et
+// de la valeur validée.
+const { check: checkFlowForm, component: FlowForm, currentValue: currentFlowValue } = useForm(
+	useStepLayout(
+		[
+			useMultiLayout({
+				fullName: useTextInput({ label: "Full name" }),
+				email: useCheckLayout(
+					useTextInput({ label: "Email" }),
+					{
+						dataStructure: DDataStructure.string([DDataStructure.email()]),
+					},
+				),
+			}),
+			useMultiLayout({
+				company: useDisabledLayout(
+					useTextInput({ label: "Company" }),
+					{
+						isDisabled: () => !hasCompany.value,
+					},
+				),
+				notes: useTextareaInput({ label: "Notes" }),
+			}),
+		],
+		{
+			errorMessageNotAtLastStep: "Complete all steps before submitting.",
+		},
+	),
+);
+
+type _CheckCurrentStep = DCommon.ExpectType<typeof currentFlowValue.value.currentStep, 0 | 1, "strict">;
+void currentFlowValue;
+
+const checkedFlowValue = await checkFlowForm();
+type _CheckCheckedFlowValueLine160 = DCommon.ExpectType<
+	typeof checkedFlowValue,
+	DEither.Error<DetailsError> | DEither.Success<readonly [
+		{
+			fullName: string;
+			email: string & DString.Email;
+		},
+		{
+			company: string | undefined;
+			notes: string;
+		},
+	]>,
+	"strict"
+>;

package/docs/concepts/03-client/20-form/40-template.ts

@@ -0,0 +1,94 @@
+/**
+ * @title Personnaliser les templates
+ *
+ * Personnalisation globale ou locale du rendu Vue des formulaires et de leurs champs.
+ */
+import { createForm, createTemplate, useMultiLayout, type InputTemplateProperties, type VueComponent } from "@duplojs/form/vue";
+import { templateFormAddButton, templateFormNextButton, templateFormPreviousButton, templateFormRemoveButton, templateFormResetButton, templateFormSelect, useTextareaInput, useTextInput } from "@duplojs/form/vueDesignSystem";
+import { createGridTemplates } from "@duplojs/form/vueGrid";
+import type * as DCommon from "@duplojs/lang/common";
+
+// Un template transforme les props système et les slots en interface Vue.
+// Il reste générique : la connaissance métier appartient au formulaire.
+// Remplacer le template change le rendu ; la structure des champs, leurs
+// validations et leurs valeurs restent définies par les inputs et les layouts.
+interface HeroInputTemplateProperties {
+	props: (
+		& InputTemplateProperties["props"]
+		& {
+			tone?: "default" | "accent";
+		}
+	);
+	slots: InputTemplateProperties["slots"];
+}
+
+declare const HeroInputTemplate: VueComponent<HeroInputTemplateProperties>;
+
+// La clé `"input"` indique quelle partie du rendu est remplacée.
+const useHeroInputTemplate = createTemplate(
+	"input",
+	HeroInputTemplate,
+	{
+		props: {
+			tone: "default",
+		},
+	},
+);
+
+// Les templates grid fournissent une base visuelle remplaçable globalement
+// ou localement.
+const gridTemplates = createGridTemplates({
+	repeat: {
+		addLabel: "Add another item",
+		removeLabel: "Remove this item",
+		addButton: templateFormAddButton,
+		removeButton: templateFormRemoveButton,
+		resetButton: templateFormResetButton,
+	},
+	step: {
+		nextLabel: "Continue",
+		previousLabel: "Back",
+		resetButton: templateFormResetButton,
+		nextButton: templateFormNextButton,
+		previousButton: templateFormPreviousButton,
+	},
+	union: { selectInputKind: templateFormSelect },
+});
+
+// La surcharge globale s'applique à tous les champs concernés par ce formulaire.
+const useForm = createForm({
+	...gridTemplates.useTemplates(),
+	input: useHeroInputTemplate({ tone: "accent" }),
+});
+
+const { component: TheForm, currentValue } = useForm(
+	useMultiLayout({
+		title: useTextInput({
+			label: "Title",
+		}),
+		subtitle: useTextInput({
+			label: "Subtitle",
+			template: useHeroInputTemplate({ tone: "default" }),
+		}),
+		summary: useTextareaInput({
+			label: "Summary",
+			template: gridTemplates.useInputTemplate({
+				columns: 12,
+			}),
+		}),
+	}),
+);
+
+// `title` utilise le template global, `subtitle` le surcharge localement,
+// `summary` revient au template grid.
+//
+type _CheckCurrentValue = DCommon.ExpectType<
+	typeof currentValue.value,
+	{
+		title: string;
+		subtitle: string;
+		summary: string;
+	},
+	"strict"
+>;
+void currentValue;

package/docs/concepts/03-client/20-form/50-integration.md

@@ -0,0 +1,11 @@
+## Intégrer un formulaire dans une page Vue
+
+Séparer la logique d'un formulaire de son rendu dans une page Vue.
+
+---
+
+Une séparation recommandée consiste à construire le formulaire et à regrouper ses opérations dans un composable. La page consomme son interface et reste centrée sur la présentation ; Form n'impose pas cette organisation.
+
+Dans [usePostModeration.ts](./examples/postModeration/usePostModeration.ts), le composable configure les champs, choisit la variante, valide la soumission et libère le formulaire à la fin du scope Vue. Il expose le composant `ModerationForm` et les seuls états et actions utiles à la page. En cas de validation réussie, il utilise la valeur validée ; les erreurs restent affichées par les templates du formulaire.
+
+[ThePage.vue](./examples/postModeration/ThePage.vue) monte ce composant, place le bouton de soumission dans son slot par défaut et relie son événement `submit` à l'opération du composable. Les boutons de décision illustrent le changement de variante depuis l'interface.

package/docs/concepts/03-client/20-form/examples/postModeration/ThePage.vue

@@ -0,0 +1,32 @@
+<script setup lang="ts">
+import { PrimaryButton, OutlineButton, DestructiveButton } from "@duplojs/form/vueDesignSystem";
+import { usePostModeration } from "./usePostModeration";
+
+const { ModerationForm, selectedDecision, submitted, selectApproval, selectRejection, submit } = usePostModeration();
+</script>
+
+<template>
+	<section>
+		<h1>Moderate post</h1>
+
+		<OutlineButton @click="selectApproval">
+			Approve
+		</OutlineButton>
+
+		<DestructiveButton @click="selectRejection">
+			Reject
+		</DestructiveButton>
+
+		<p>Selected decision: {{ selectedDecision }}</p>
+
+		<ModerationForm @submit="submit">
+			<PrimaryButton type="submit">
+				Submit decision
+			</PrimaryButton>
+		</ModerationForm>
+
+		<p v-if="submitted">
+			{{ submitted }}
+		</p>
+	</section>
+</template>

package/docs/concepts/03-client/20-form/examples/postModeration/usePostModeration.ts

@@ -0,0 +1,80 @@
+import { createForm, useMultiLayout, useUnionLayout } from "@duplojs/form/vue";
+import { templateFormAddButton, templateFormNextButton, templateFormPreviousButton, templateFormRemoveButton, templateFormResetButton, templateFormSelect, useTextareaInput, useTextInput } from "@duplojs/form/vueDesignSystem";
+import { createGridTemplates } from "@duplojs/form/vueGrid";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+import { computed, onScopeDispose, ref } from "vue";
+
+const templates = 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 },
+});
+
+const useForm = createForm(templates.useTemplates());
+
+export function usePostModeration() {
+	const { component: ModerationForm, currentValue, check, dispose } = useForm(
+		useUnionLayout(
+			[
+				["approve", useTextInput({ label: "Public note" })],
+				[
+					"reject",
+					useMultiLayout({
+						reason: useTextareaInput({
+							label: "Reason for rejection",
+							dataStructure: DDataStructure.string([DDataStructure.minCharacters(1)]),
+						}),
+					}),
+				],
+			],
+			{ defaultKind: "approve" },
+		),
+	);
+	const selectedDecision = computed(() => currentValue.value.kind);
+	const submitted = ref("");
+
+	function selectApproval() {
+		currentValue.value.updateKind("approve");
+	}
+
+	function selectRejection() {
+		currentValue.value.updateKind("reject");
+	}
+
+	async function submit() {
+		submitted.value = "";
+		const result = await check();
+
+		if (DEither.isRight(result)) {
+			const decision = DEither.unwrapRight(result);
+
+			submitted.value = decision.kind === "approve"
+				? `Approved: ${decision.value}`
+				: `Rejected: ${decision.value.reason}`;
+		}
+	}
+
+	onScopeDispose(dispose);
+
+	return {
+		ModerationForm,
+		selectedDecision,
+		submitted,
+		selectApproval,
+		selectRejection,
+		submit,
+	};
+}

package/docs/concepts/03-client/20-form/index.md

@@ -0,0 +1,3 @@
+## Form
+
+Création et gestion de formulaires typés pour les interfaces utilisateur.

package/docs/concepts/03-client/index.md

@@ -0,0 +1 @@
+# Client