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

package/docs/API/40-json-web-token/40-utils/10-pemToBinary.ts

@@ -0,0 +1,11 @@
+/**
+ * @title pemToBinary
+ *
+ * Convertir une clé PEM en octets DER.
+ */
+import { pemToBinary } from "@duplojs/json-web-token";
+
+// clé PEM SPKI
+declare const publicKey: string;
+// octets DER
+const der = pemToBinary(publicKey);

package/docs/API/40-json-web-token/40-utils/index.llms.md

@@ -0,0 +1,76 @@
+## Utilitaires JWT
+
+Manipuler les encodages et les primitives cryptographiques publiques.
+
+### [AES_GCM.decrypt](10-AES_GCM.decrypt.ts)
+
+Déchiffrer avec AES-GCM et le vecteur associé.
+ 
+### [AES_GCM.encrypt](10-AES_GCM.encrypt.ts)
+
+Chiffrer avec AES-GCM et récupérer le vecteur utilisé.
+ 
+### [AES_GCM.generateInitializationVector](10-AES_GCM.generateInitializationVector.ts)
+
+Produire un vecteur aléatoire de 12 octets.
+ 
+### [HMAC.sign](10-HMAC.sign.ts)
+
+Signer avec HMAC.
+ 
+### [HMAC.verify](10-HMAC.verify.ts)
+
+Vérifier une signature HMAC.
+ 
+### [RSA.sign](10-RSA.sign.ts)
+
+Signer avec une clé privée RSA PKCS8.
+ 
+### [RSA.verify](10-RSA.verify.ts)
+
+Vérifier une signature RSA avec une clé publique SPKI.
+ 
+### [RSA_OAEP.decrypt](10-RSA_OAEP.decrypt.ts)
+
+Déchiffrer avec une clé privée RSA-OAEP PKCS8.
+ 
+### [RSA_OAEP.encrypt](10-RSA_OAEP.encrypt.ts)
+
+Chiffrer avec une clé publique RSA-OAEP SPKI.
+ 
+### [decodeBase64](10-decodeBase64.ts)
+
+Décoder du Base64 en octets.
+ 
+### [decodeBase64Url](10-decodeBase64Url.ts)
+
+Décoder du Base64URL en octets.
+ 
+### [decodeText](10-decodeText.ts)
+
+Décoder des octets UTF-8.
+ 
+### [encodeBase64](10-encodeBase64.ts)
+
+Encoder des octets en Base64.
+ 
+### [encodeBase64Url](10-encodeBase64Url.ts)
+
+Encoder du texte ou des octets en Base64URL sans remplissage.
+ 
+### [encodeText](10-encodeText.ts)
+
+Encoder une chaîne en UTF-8.
+ 
+### [isBase64Url](10-isBase64Url.ts)
+
+Vérifier la forme d’une chaîne Base64URL.
+ 
+### [jsonParse](10-jsonParse.ts)
+
+Lire du JSON ou renvoyer undefined si la syntaxe est invalide.
+ 
+### [pemToBinary](10-pemToBinary.ts)
+
+Convertir une clé PEM en octets DER.
+ 

package/docs/API/40-json-web-token/40-utils/index.md

@@ -0,0 +1,3 @@
+## Utilitaires JWT
+
+Manipuler les encodages et les primitives cryptographiques publiques.

package/docs/API/40-json-web-token/index.md

@@ -0,0 +1,3 @@
+# @duplojs/json-web-token
+
+Politiques JWT réutilisables, signature, chiffrement facultatif et primitives cryptographiques.

package/docs/API/50-form/10-vue/10-construction/10-createForm.ts

@@ -0,0 +1,48 @@
+/**
+ * @title createForm
+ *
+ * Associer des templates à une fabrique de formulaires Vue.
+ */
+import { createForm, useMultiLayout, type GetCheckedValue } 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 { grid } from "../fixtures/templates";
+
+// La fabrique peut servir à plusieurs formulaires ; chaque appel reçoit son champ racine.
+const useForm = createForm(grid.useTemplates());
+
+const { component: ContactForm, currentValue, check, reset, dispose } = useForm(
+	useMultiLayout({
+		email: useTextInput({
+			label: "Email",
+			dataStructure: DDataStructure.string([DDataStructure.email()]),
+		}),
+	}),
+);
+
+// La saisie brute reste une chaîne ; seul le succès de check garantit le format email.
+type _Raw = DCommon.ExpectType<
+	typeof currentValue.value,
+	{ email: string },
+	"strict"
+>;
+type _Checked = DCommon.ExpectType<
+	GetCheckedValue<typeof check>,
+	{ email: string & DString.Email },
+	"strict"
+>;
+
+// Succès avec la valeur validée, ou erreurs associées aux champs.
+const result = await check();
+void result;
+
+// À monter dans Vue ; son slot par défaut reçoit le bouton de soumission.
+void ContactForm;
+
+// Restaure la valeur initiale.
+reset();
+
+// Libère les scopes internes lorsque le formulaire n'est plus utilisé.
+dispose();

package/docs/API/50-form/10-vue/10-construction/10-createFormField.ts

@@ -0,0 +1,66 @@
+/**
+ * @title createFormField
+ *
+ * Construire une primitive de champ personnalisée pour un formulaire Vue.
+ */
+import { createForm, createFormField, useMultiLayout, type FormField, type FormFieldSlots } from "@duplojs/form/vue";
+import { useTextInput } from "@duplojs/form/vueDesignSystem";
+import type * as DCommon from "@duplojs/lang/common";
+import { grid } from "../fixtures/templates";
+
+// Un layout qui présente un champ dans une section utilise le template du contexte.
+// Le champ enfant conserve son modèle et ses garanties de validation.
+function useTitledField<GenericValue, GenericChecked, GenericSlots extends FormFieldSlots>(
+	field: FormField<GenericValue, GenericChecked, GenericSlots>,
+	title: string,
+) {
+	return createFormField<
+		GenericValue,
+		GenericChecked,
+		GenericSlots
+	>(
+		(modelValue, parentKey, context) => {
+			const key = `${parentKey}_TITLE`;
+			const child = field.new(modelValue, key, context);
+
+			return {
+				check: () => child.check(),
+				reset: () => child.reset(),
+				dispose: () => child.dispose(),
+				getVNode: () => context.templates.section.getVNode(
+					{
+						fieldKey: key,
+						getCurrentValue: () => modelValue.value,
+						title,
+					},
+					{ formField: () => child.getVNode() },
+				),
+			};
+		},
+		field.defaultValue,
+	);
+}
+
+// Le formulaire instancie le layout avec le modèle initial du champ enfant.
+const useForm = createForm(grid.useTemplates());
+const { component: ProfileForm, currentValue, check, reset, dispose } = useForm(
+	useTitledField(
+		useMultiLayout({
+			name: useTextInput({ label: "Name" }),
+		}),
+		"Profile",
+	),
+);
+
+type _Value = DCommon.ExpectType<
+	typeof currentValue.value,
+	{ name: string },
+	"strict"
+>;
+
+// check, reset et dispose sont délégués à l'enfant ; reset du formulaire restaure aussi le modèle initial.
+const result = await check();
+void result;
+void ProfileForm;
+reset();
+dispose();

package/docs/API/50-form/10-vue/10-construction/10-createGridTemplates.ts

@@ -0,0 +1,39 @@
+/**
+ * @title createGridTemplates
+ *
+ * Configurer les templates Vue en grille et leurs commandes.
+ */
+import { createForm } from "@duplojs/form/vue";
+import { templateFormAddButton, templateFormNextButton, templateFormPreviousButton, templateFormRemoveButton, templateFormResetButton, templateFormSelect, useTextInput } from "@duplojs/form/vueDesignSystem";
+import { createGridTemplates } from "@duplojs/form/vueGrid";
+
+// La configuration Grid exige les options repeat, step et union, même si le formulaire ne les utilise pas.
+// Les options form, input, multi, check et section peuvent être omises.
+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 },
+	input: { columns: 6 },
+});
+
+// Ensemble complet pour createForm.
+const useForm = createForm(grid.useTemplates());
+const { component: TheForm } = useForm(
+	useTextInput({
+		label: "Title",
+		// Surcharge locale de la configuration input.
+		template: grid.useInputTemplate({ columns: 12 }),
+	}),
+);

package/docs/API/50-form/10-vue/10-construction/10-createInput.ts

@@ -0,0 +1,46 @@
+/**
+ * @title createInput
+ *
+ * Construire un champ à partir d'un composant Vue compatible avec v-model.
+ */
+import { createInput, type GetFormFieldCheckedValue, type GetFormFieldValue } from "@duplojs/form/vue";
+import AddressInput from "./fixtures/AddressInput.vue";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DString from "@duplojs/lang/string";
+
+// AddressInput.vue déclare modelValue comme chaîne et exige la prop hint.
+// La fabrique fournit cette prop requise et une valeur initiale inférée depuis le composant.
+const useAddressInput = createInput(
+	AddressInput,
+	{
+		defaultValue: "",
+		props: {
+			hint: "We use this address to contact you.",
+			placeholder: "name@example.com",
+		},
+	},
+);
+
+const address = useAddressInput({
+	label: "Email",
+	props: {
+		hint: "Your contact address",
+		placeholder: "contact@example.com",
+	},
+	dataStructure: DDataStructure.string([DDataStructure.email()]),
+});
+
+// Les props locales doivent respecter le contrat du composant, y compris ses props requises.
+// Elles complètent les props initiales et remplacent les clés communes.
+// La validation enrichit le résultat.
+type _Raw = DCommon.ExpectType<
+	GetFormFieldValue<typeof address>,
+	string,
+	"strict"
+>;
+type _Checked = DCommon.ExpectType<
+	GetFormFieldCheckedValue<typeof address>,
+	string & DString.Email,
+	"strict"
+>;

package/docs/API/50-form/10-vue/10-construction/10-createTemplate.ts

@@ -0,0 +1,36 @@
+/**
+ * @title createTemplate
+ *
+ * Configurer un composant Vue comme template de formulaire.
+ */
+import { createForm, createTemplate, useMultiLayout } from "@duplojs/form/vue";
+import { useTextInput } from "@duplojs/form/vueDesignSystem";
+import { GridInputTemplate } from "@duplojs/form/vueGrid";
+import { grid } from "../fixtures/templates";
+
+// La fabrique fixe le composant et les props par défaut hors props système.
+const useCompactInputTemplate = createTemplate(
+	"input",
+	GridInputTemplate,
+	{ props: { columns: 6 } },
+);
+
+// Le template global utilise six colonnes pour les inputs de ce formulaire.
+const useForm = createForm({
+	...grid.useTemplates(),
+	input: useCompactInputTemplate(),
+});
+
+const { component: ArticleForm, dispose } = useForm(
+	useMultiLayout({
+		title: useTextInput({ label: "Title" }),
+		summary: useTextInput({
+			label: "Summary",
+			// Cette instance surcharge les colonnes pour ce champ uniquement.
+			template: useCompactInputTemplate({ columns: 12 }),
+		}),
+	}),
+);
+
+void ArticleForm;
+dispose();

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();