@nocode-factory/sanity-kit 2.37.0 → 2.37.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,427 @@
1
+ import { SanityClient } from "sanity";
2
+ /**
3
+ * Configuration publique du plugin. Tout est optionnel sauf `pageTypes` :
4
+ * le kit ne doit rien savoir du contenu d'un projet client.
5
+ */
6
+ /** Un type de document considéré comme une page du site. */
7
+ interface NcfPageTypeInput {
8
+ /** Nom du type de document Sanity (ex. 'page'). */
9
+ type: string;
10
+ /**
11
+ * Champ de type `slug` portant l'URL. Hérite de `slugField` global.
12
+ * Mettre à `null` pour un type sans slug : `path` devient obligatoire.
13
+ */
14
+ slugField?: string | null;
15
+ /**
16
+ * Chemin fixe, pour les pages sans slug (ex. l'accueil : '/').
17
+ * Prioritaire sur `slugField` quand les deux sont renseignés.
18
+ */
19
+ path?: string;
20
+ /**
21
+ * Préfixe d'URL placé devant le slug, pour les collections servies sous un
22
+ * répertoire : `pathPrefix: '/blog'` donne `/blog/<slug>`. Sans effet avec
23
+ * `path`. C'est la clé `pathPrefix` du registre `site-routes.json` du starter.
24
+ */
25
+ pathPrefix?: string;
26
+ /** Champ portant le titre affiché. Hérite de `titleField` global. */
27
+ titleField?: string;
28
+ }
29
+ type NcfPageTypeConfig = string | NcfPageTypeInput;
30
+ /** Sites multilingues (ex. @sanity/document-internationalization). */
31
+ interface NcfI18nConfig {
32
+ /** Champ portant le code de langue sur le document. */
33
+ field?: string;
34
+ /** Langue servie à la racine, sans préfixe d'URL. */
35
+ defaultLocale?: string;
36
+ /** Langues attendues. Vide = déduites des documents rencontrés. */
37
+ locales?: string[];
38
+ /**
39
+ * Langue SOURCE des valeurs par défaut des composants (défaut : `en` si le site
40
+ * l'a, sinon la langue principale). Publier ses valeurs par défaut propose de
41
+ * retraduire celles des autres langues ; un champ qui hérite d'une valeur par
42
+ * défaut non traduite propose « Translate default with AI ».
43
+ */
44
+ defaultsSourceLocale?: string;
45
+ }
46
+ /**
47
+ * Aperçu visuel des blocs du page builder. Aujourd'hui un seul fournisseur :
48
+ * la page « design system » du front, avec les captures générées par la CI.
49
+ * Storybook viendra s'ajouter ici le jour où un projet en aura un.
50
+ */
51
+ interface NcfComponentPreviewConfig {
52
+ provider?: 'designSystemPage' | 'none';
53
+ /** Chemin de la page de démonstration, relatif à `previewUrl`. */
54
+ path?: string;
55
+ /** Ancre vers le bloc sur cette page. Gabarit : {name} / {kebab}. */
56
+ anchor?: string;
57
+ /** Chemin de la capture, relatif à `previewUrl`. Gabarit : {name} / {kebab}. */
58
+ thumbnail?: string;
59
+ /**
60
+ * Type du document des valeurs par défaut des composants (un champ par
61
+ * composant, nommé `{name}`). Présent dans le schéma : un clic sur un composant
62
+ * ouvre Presentation avec son rendu réel et ses valeurs par défaut côte à côte.
63
+ */
64
+ defaultsType?: string;
65
+ /** Page qui rend un composant seul, avec ses valeurs par défaut. Gabarit : {name} / {kebab}. */
66
+ live?: string;
67
+ }
68
+ /** Journal des modifications (phase 2). */
69
+ interface NcfHistoryConfig {
70
+ /**
71
+ * Clé de lecture du projet, écrite dans `studio/.env` par `npx ncf-kit setup`
72
+ * (variable `SANITY_STUDIO_NCF_PROJECT_KEY`). Elle voyage dans le bundle du
73
+ * Studio : imprévisible, pas confidentielle. Jamais une clé d'écriture.
74
+ * Vide ou absente : l'onglet Historique explique comment l'obtenir.
75
+ */
76
+ projectKey?: string;
77
+ /** Base des Edge Functions. Par défaut, le service du kit. */
78
+ endpoint?: string;
79
+ }
80
+ /** Étiquette de suivi posable sur une page dans le board. */
81
+ interface NcfBoardTag {
82
+ /** Identifiant stable, enregistré dans le document de disposition. */
83
+ id: string;
84
+ label: string;
85
+ /** Couleur CSS de la pastille et de la bordure du nœud. */
86
+ color: string;
87
+ }
88
+ /** Choix possible d'un champ de gestion interne de type « select ». */
89
+ interface NcfInternalFieldOption {
90
+ id: string;
91
+ label: string;
92
+ /** Couleur de la pastille. Sans elle, le choix s'affiche en texte. */
93
+ color?: string;
94
+ }
95
+ /**
96
+ * Champ de suivi éditorial, libre. Autant qu'on veut : responsable, cible,
97
+ * rôle de la page… Ces valeurs vivent dans le document du kit, jamais dans le
98
+ * schéma du client.
99
+ */
100
+ interface NcfInternalField {
101
+ /** Identifiant stable, enregistré avec la valeur. */
102
+ id: string;
103
+ label: string;
104
+ /** `text` par défaut. `select` exige `options`. */
105
+ type?: 'text' | 'select';
106
+ options?: NcfInternalFieldOption[];
107
+ }
108
+ /**
109
+ * Donnée du document de la page, affichable telle quelle dans une colonne.
110
+ *
111
+ * Réservé aux valeurs qui tiennent sur une ligne : une meta description, un
112
+ * booléen d'indexabilité, une date. Surtout pas un tableau de sections, qu'on
113
+ * ne saurait pas rendre dans une cellule.
114
+ */
115
+ interface NcfDocumentColumn {
116
+ /** Identifiant stable. Lettres, chiffres et tirets. */
117
+ key: string;
118
+ label: string;
119
+ /** Chemins essayés dans l'ordre, le premier renseigné gagne. */
120
+ path: string | string[];
121
+ /** `text` par défaut. `boolean` affiche Oui/Non. */
122
+ type?: 'text' | 'boolean' | 'number';
123
+ }
124
+ /**
125
+ * Une version du front déployée quelque part : production, préproduction,
126
+ * branche de recette.
127
+ *
128
+ * Le code change d'un environnement à l'autre, **pas les données** : c'est
129
+ * toujours le même dataset qu'on regarde. Voir le contenu de production dans
130
+ * le front d'une branche est justement l'intérêt.
131
+ */
132
+ interface NcfEnvironment {
133
+ /** Identifiant stable, retenu d'une session à l'autre. */
134
+ id: string;
135
+ label: string;
136
+ /** Base URL du front, sans slash final. */
137
+ url: string;
138
+ }
139
+ interface NcfToolsConfig {
140
+ pages?: boolean;
141
+ components?: boolean;
142
+ history?: boolean;
143
+ /** Bouton « Design system » : ouvre la page /design-system dans Presentation. */
144
+ designSystem?: boolean;
145
+ }
146
+ interface NcfKitConfig {
147
+ /** Types de documents traités comme des pages. Au moins un. */
148
+ pageTypes: NcfPageTypeConfig[];
149
+ /** Champ tableau du page builder. */
150
+ pageBuilderField?: string;
151
+ /**
152
+ * Préfixe commun aux types de blocs, retiré pour l'affichage et les gabarits
153
+ * d'URL. Ex. 'section.' pour des blocs nommés `section.hero`.
154
+ */
155
+ blockNamespace?: string;
156
+ /** Champ slug par défaut des `pageTypes`. */
157
+ slugField?: string;
158
+ /** Champ titre par défaut des `pageTypes`. */
159
+ titleField?: string;
160
+ /**
161
+ * Champ booléen marquant une page comme non indexable. Plusieurs chemins
162
+ * sont essayés dans l'ordre, le premier renseigné gagne.
163
+ * Défaut : `['seo.noindex', 'noindex']`.
164
+ */
165
+ noindexField?: string | string[];
166
+ /** Base URL du front, sans slash final. */
167
+ previewUrl?: string;
168
+ /**
169
+ * Fronts déployés entre lesquels basculer dans l'aperçu. Sans eux, le seul
170
+ * environnement proposé est `previewUrl`.
171
+ *
172
+ * Leurs origines doivent figurer dans `allowOrigins` de `presentationTool` :
173
+ * `ncfAllowedOrigins(config)` les produit.
174
+ */
175
+ environments?: NcfEnvironment[];
176
+ /**
177
+ * `false` retire la préproduction déduite par convention
178
+ * (`preview-<projet>.vercel.app`). Utile pour un projet qui n'en a pas.
179
+ */
180
+ preprodUrl?: false;
181
+ /**
182
+ * Gabarit d'URL de la capture d'une page, pour afficher la page entière dans
183
+ * le board plutôt qu'une iframe tronquée. Variables : {slug} (chemin sans
184
+ * slash de tête, avec des tirets), {locale}, {id}.
185
+ *
186
+ * Chemin relatif à `previewUrl` (« /pages/{slug}.png ») ou URL absolue.
187
+ * Vide : le board retombe sur l'aperçu iframe en direct.
188
+ */
189
+ pageThumbnail?: string;
190
+ /** `false` (défaut) pour un site monolingue. */
191
+ i18n?: NcfI18nConfig | false;
192
+ componentPreview?: NcfComponentPreviewConfig;
193
+ history?: NcfHistoryConfig;
194
+ /**
195
+ * Base des Edge Functions du kit, pour l'enregistrement et l'historique.
196
+ * `false` coupe tout appel sortant, y compris le signalement de présence.
197
+ */
198
+ serviceEndpoint?: string | false;
199
+ /** Permet de n'activer qu'une partie des outils. */
200
+ tools?: NcfToolsConfig;
201
+ /**
202
+ * Outils techniques rangés dans le menu « Plus » de la barre du Studio, pour ne
203
+ * pas encombrer le marketing. Par défaut : Vision et la planification
204
+ * (« Scheduled drafts » / Releases, nom d'outil `releases`). `false` : aucun.
205
+ */
206
+ moreTools?: string[] | false;
207
+ /**
208
+ * Étiquettes de suivi du board. Remplacent entièrement les valeurs par
209
+ * défaut quand elles sont fournies.
210
+ */
211
+ boardTags?: NcfBoardTag[];
212
+ /**
213
+ * Colonnes de l'onglet « Gestion interne » de la liste des pages.
214
+ * Remplacent entièrement les valeurs par défaut quand elles sont fournies.
215
+ */
216
+ internalFields?: NcfInternalField[];
217
+ /**
218
+ * Données du document affichables en colonne, proposées dans le sélecteur de
219
+ * colonnes. Masquées tant que personne ne les coche.
220
+ * Défaut : meta description, titre SEO, indexabilité.
221
+ */
222
+ documentColumns?: NcfDocumentColumn[];
223
+ }
224
+ interface ResolvedPageType {
225
+ type: string;
226
+ slugField: string | null;
227
+ path: string | null;
228
+ /** Préfixe normalisé ('/blog'), `null` pour une collection à la racine. */
229
+ pathPrefix: string | null;
230
+ titleField: string;
231
+ }
232
+ interface ResolvedI18n {
233
+ field: string;
234
+ defaultLocale: string;
235
+ locales: string[];
236
+ defaultsSourceLocale: string;
237
+ }
238
+ interface ResolvedComponentPreview {
239
+ provider: 'designSystemPage' | 'none';
240
+ path: string;
241
+ anchor: string;
242
+ thumbnail: string;
243
+ defaultsType: string;
244
+ live: string;
245
+ }
246
+ interface ResolvedKitConfig {
247
+ pageTypes: ResolvedPageType[];
248
+ pageTypeNames: string[];
249
+ pageBuilderField: string;
250
+ blockNamespace: string;
251
+ noindexFields: string[];
252
+ previewUrl: string | null;
253
+ environments: NcfEnvironment[];
254
+ pageThumbnail: string | null;
255
+ i18n: ResolvedI18n | null;
256
+ componentPreview: ResolvedComponentPreview;
257
+ history: ResolvedHistory | null;
258
+ /** `null` quand on a explicitement coupé les appels sortants. */
259
+ serviceEndpoint: string | null;
260
+ tools: Required<NcfToolsConfig>;
261
+ /** Outils rangés dans le menu « Plus » de la barre (noms d'outils). */
262
+ moreTools: string[];
263
+ boardTags: NcfBoardTag[];
264
+ internalFields: NcfInternalField[];
265
+ documentColumns: ResolvedDocumentColumn[];
266
+ }
267
+ interface ResolvedHistory {
268
+ projectKey: string;
269
+ endpoint: string;
270
+ }
271
+ interface ResolvedDocumentColumn {
272
+ key: string;
273
+ label: string;
274
+ /** Chemins retenus, nettoyés. */
275
+ paths: string[];
276
+ type: 'text' | 'boolean' | 'number';
277
+ /**
278
+ * Inverse un booléen à l'affichage. Sert à `noindex`, qu'on veut lire
279
+ * « Indexable : oui » plutôt que « Noindex : non ».
280
+ */
281
+ invert?: boolean;
282
+ }
283
+ type IssueLevel = 'error' | 'warning';
284
+ /**
285
+ * Un problème de configuration. `error` neutralise l'outil concerné (mais pas
286
+ * le Studio) ; `warning` laisse l'outil fonctionner en mode dégradé.
287
+ */
288
+ interface ConfigIssue {
289
+ level: IssueLevel;
290
+ /** Chemin de l'option fautive, ex. 'pageTypes[1].slugField'. */
291
+ path: string;
292
+ message: string;
293
+ /** Quels outils sont concernés. Vide = tous. */
294
+ tools?: NcfToolName[];
295
+ }
296
+ type NcfToolName = 'pages' | 'components' | 'history' | 'designSystem';
297
+ interface KitContextValue {
298
+ config: ResolvedKitConfig;
299
+ issues: ConfigIssue[];
300
+ }
301
+ declare const DEFAULT_COMPONENT_DEFAULTS_TYPE = "componentDefaults";
302
+ /** Nom du champ d'un composant dans le document des valeurs par défaut : `section.cta` -> `cta`. */
303
+ declare function defaultsFieldName(type: string, namespace?: string): string;
304
+ /** Document « Composants : valeurs par défaut », généré depuis les sections. */
305
+ declare function defineComponentDefaults(options: {
306
+ sections: readonly unknown[];
307
+ name?: string;
308
+ title?: string;
309
+ namespace?: string;
310
+ }): {
311
+ name: string;
312
+ title: string;
313
+ type: "document";
314
+ description: string;
315
+ fields: {
316
+ name: string;
317
+ title: string;
318
+ type: "object";
319
+ description: string;
320
+ options: {
321
+ collapsible: true;
322
+ collapsed: true;
323
+ };
324
+ fields: never;
325
+ }[];
326
+ preview: {
327
+ prepare: () => {
328
+ title: string;
329
+ };
330
+ };
331
+ };
332
+ /**
333
+ * Règle « obligatoire SAUF si le composant a une valeur par défaut » pour un autre
334
+ * type de document des valeurs par défaut ou un autre espace de noms.
335
+ * `validation: requiredUnlessDefaultFor({type: 'mesDefauts'})`
336
+ */
337
+ declare function requiredUnlessDefaultFor(options?: {
338
+ type?: string;
339
+ namespace?: string;
340
+ }): <R>(rule: R) => R;
341
+ /**
342
+ * Champ de section obligatoire, SAUF si le composant a une valeur par défaut
343
+ * pour ce champ (elle s'affichera). Tout type de champ.
344
+ * `validation: requiredUnlessDefault`
345
+ */
346
+ declare const requiredUnlessDefault: <R>(rule: R) => R;
347
+ /**
348
+ * Presentation : la page qui rend un composant seul (par défaut
349
+ * `/design-system/composant`) a pour document principal les valeurs par défaut.
350
+ * Rendu réel et réglages côte à côte, en direct.
351
+ * `presentationTool({resolve: {mainDocuments: defineDocuments([componentDefaultsMainDocument({language: 'fr'})])}})`
352
+ */
353
+ declare function componentDefaultsMainDocument(options?: {
354
+ language?: string;
355
+ route?: string;
356
+ type?: string;
357
+ }): {
358
+ route: string;
359
+ filter: string;
360
+ };
361
+ /**
362
+ * Presentation : les pages du design system ont pour document principal les valeurs
363
+ * par défaut des composants. `/design-system` (toute la bibliothèque) et
364
+ * `/design-system/composant` (un composant seul) : cliquer un composant ouvre ses
365
+ * réglages globaux, et un style changé change le composant partout où il n'est
366
+ * pas surchargé.
367
+ * `presentationTool({resolve: {mainDocuments: defineDocuments(componentDefaultsMainDocuments({language: 'fr'}))}})`
368
+ */
369
+ declare function componentDefaultsMainDocuments(options?: {
370
+ language?: string;
371
+ type?: string;
372
+ routes?: string[];
373
+ }): {
374
+ route: string;
375
+ filter: string;
376
+ }[];
377
+ /**
378
+ * RÈGLE D'OR DU MULTILINGUE : une référence ne propose que des documents de la
379
+ * MÊME langue que le document en cours (un article EN ne voit que les catégories EN,
380
+ * une page FR que les pages FR). Les documents sans langue (logos, régions, assets…)
381
+ * restent proposés. Un document commun à toutes les langues (Navigation…) vise la
382
+ * langue principale.
383
+ *
384
+ * Pose ce filtre sur TOUS les champs de référence des types donnés (champs, listes,
385
+ * objets imbriqués, annotations du texte riche), combiné avec un filtre déjà présent.
386
+ * À appliquer aux types du projet :
387
+ *
388
+ * ```ts
389
+ * schema: {types: withSameLanguageReferences(schemaTypes, ncfOptions)}
390
+ * ```
391
+ */
392
+ declare function withSameLanguageReferences<T>(types: T[], options: Pick<NcfKitConfig, 'i18n'>): T[];
393
+ interface CrossLanguageReport {
394
+ /** Références repointées (ou à repointer en simulation). */
395
+ fixed: {
396
+ documentId: string;
397
+ path: string;
398
+ from: string;
399
+ to: string;
400
+ }[];
401
+ /** Références croisées sans équivalent dans la langue du document (laissées). */
402
+ missing: {
403
+ documentId: string;
404
+ path: string;
405
+ ref: string;
406
+ language: string;
407
+ }[];
408
+ }
409
+ /**
410
+ * RÈGLE D'OR DU MULTILINGUE, côté données : chaque référence d'un document vise un
411
+ * document de SA langue (document sans langue : la langue principale). Une
412
+ * référence croisée est repointée vers la traduction de la bonne langue (liens de
413
+ * traduction) ; sans traduction, elle est signalée et laissée. Publiés et
414
+ * brouillons. `apply: false` : simulation.
415
+ *
416
+ * ```ts
417
+ * // studio/scripts/references-same-language.ts (sanity exec --with-user-token)
418
+ * const report = await fixCrossLanguageReferences(getCliClient(...), {defaultLocale: 'fr', apply})
419
+ * ```
420
+ */
421
+ declare function fixCrossLanguageReferences(client: SanityClient, options: {
422
+ field?: string;
423
+ defaultLocale: string;
424
+ apply?: boolean;
425
+ }): Promise<CrossLanguageReport>;
426
+ export { ResolvedI18n as A, NcfPageTypeConfig as C, ResolvedComponentPreview as D, NcfToolsConfig as E, ResolvedPageType as M, ResolvedDocumentColumn as O, NcfKitConfig as S, NcfToolName as T, NcfEnvironment as _, componentDefaultsMainDocument as a, NcfInternalField as b, defineComponentDefaults as c, ConfigIssue as d, IssueLevel as f, NcfDocumentColumn as g, NcfComponentPreviewConfig as h, DEFAULT_COMPONENT_DEFAULTS_TYPE as i, ResolvedKitConfig as j, ResolvedHistory as k, requiredUnlessDefault as l, NcfBoardTag as m, fixCrossLanguageReferences as n, componentDefaultsMainDocuments as o, KitContextValue as p, withSameLanguageReferences as r, defaultsFieldName as s, CrossLanguageReport as t, requiredUnlessDefaultFor as u, NcfHistoryConfig as v, NcfPageTypeInput as w, NcfInternalFieldOption as x, NcfI18nConfig as y };
427
+ //# sourceMappingURL=fixCrossLanguageReferences-D4phJn84.d.ts.map