@forinda/kickjs-view 0.5.0 → 0.7.0

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.
Files changed (44) hide show
  1. package/dist/cli.d.ts +61 -2
  2. package/dist/cli.d.ts.map +1 -1
  3. package/dist/cli.js +5 -2
  4. package/dist/cli.js.map +1 -1
  5. package/dist/edge.d.ts +8 -5
  6. package/dist/edge.js +2 -2
  7. package/dist/exports-CII2eM6o.js +17 -0
  8. package/dist/exports-CII2eM6o.js.map +1 -0
  9. package/dist/file-BIua9gOB.d.ts +925 -0
  10. package/dist/file-BIua9gOB.d.ts.map +1 -0
  11. package/dist/file-loader.d.ts +2 -2
  12. package/dist/file-loader.js +3 -3
  13. package/dist/file-loader.js.map +1 -1
  14. package/dist/format-CvHG95ck.js +18 -0
  15. package/dist/format-CvHG95ck.js.map +1 -0
  16. package/dist/i18n-EriU9b68.js +12 -0
  17. package/dist/i18n-EriU9b68.js.map +1 -0
  18. package/dist/index.d.ts +12 -5
  19. package/dist/index.d.ts.map +1 -1
  20. package/dist/index.js +2 -2
  21. package/dist/index.js.map +1 -1
  22. package/dist/project-mP4NzZhQ.d.ts +50 -0
  23. package/dist/project-mP4NzZhQ.d.ts.map +1 -0
  24. package/dist/serve-Df9_MrXE.d.ts +173 -0
  25. package/dist/serve-Df9_MrXE.d.ts.map +1 -0
  26. package/dist/summary-DOhWOKmu.js +20 -0
  27. package/dist/summary-DOhWOKmu.js.map +1 -0
  28. package/package.json +12 -10
  29. package/virtual.d.ts +4 -1
  30. package/dist/ast-bZ1jJ5-w.d.ts +0 -372
  31. package/dist/ast-bZ1jJ5-w.d.ts.map +0 -1
  32. package/dist/exports-DNeTdtX4.js +0 -17
  33. package/dist/exports-DNeTdtX4.js.map +0 -1
  34. package/dist/format-Cig7Gm1h.js +0 -18
  35. package/dist/format-Cig7Gm1h.js.map +0 -1
  36. package/dist/project-XUrj8cl0.d.ts +0 -29
  37. package/dist/project-XUrj8cl0.d.ts.map +0 -1
  38. package/dist/rolldown-runtime-BLRzqIEa.js +0 -11
  39. package/dist/serve-fHP-Eia9.d.ts +0 -97
  40. package/dist/serve-fHP-Eia9.d.ts.map +0 -1
  41. package/dist/template-DU9sjMgd.js +0 -20
  42. package/dist/template-DU9sjMgd.js.map +0 -1
  43. package/dist/views-_eQ9NTKn.d.ts +0 -198
  44. package/dist/views-_eQ9NTKn.d.ts.map +0 -1
@@ -0,0 +1,925 @@
1
+
2
+ /**
3
+ * Message catalogues for the `t` pipe: `<viewsDir>/locales/<locale>.json`,
4
+ * nested keys addressed with dots, plural forms picked by `Intl.PluralRules`.
5
+ *
6
+ * ```json
7
+ * { "cart": { "title": "Cart", "items": { "one": "{count} item", "other": "{count} items" } } }
8
+ * ```
9
+ */
10
+ declare const PLURAL_FORMS: readonly ['zero', 'one', 'two', 'few', 'many', 'other'];
11
+ type PluralForm = (typeof PLURAL_FORMS)[number];
12
+ /** A message: text, or one text per plural form (`other` required). */
13
+ type Message = string | ({
14
+ other: string;
15
+ } & Partial<Record<Exclude<PluralForm, 'other'>, string>>);
16
+ /** Locale → dot key → message. */
17
+ type Messages = Record<string, Record<string, Message>>;
18
+ /** What the check knows of the catalogues: each key's locales and placeholders. */
19
+ interface CatalogIndex {
20
+ /** The catalogue folder, as messages name it (`src/views/locales`). */
21
+ where: string;
22
+ locales: string[];
23
+ keys: Map<string, {
24
+ locales: Set<string>;
25
+ params: Set<string>;
26
+ }>;
27
+ }
28
+ /** The catalogues indexed for checking `t` calls. */
29
+ declare function catalogIndex(messages: Messages, where: string): CatalogIndex;
30
+ /** A point in a template: 0-based offset, 1-based line and column (UTF-16 units). */
31
+ interface Pos {
32
+ offset: number;
33
+ line: number;
34
+ column: number;
35
+ }
36
+ /** A source range in a template, start and end. */
37
+ interface Span {
38
+ start: Pos;
39
+ end: Pos;
40
+ }
41
+ /** An error or warning from parsing, checking or rendering a template. */
42
+ interface Diagnostic {
43
+ file: string;
44
+ span: Span;
45
+ message: string;
46
+ severity: 'error' | 'warning';
47
+ /** The templates being rendered, outermost first, when the error came from a render. */
48
+ stack?: string[];
49
+ }
50
+ /** The position of `offset` in `source`. */
51
+ declare const positionAt: (source: string, offset: number) => Pos;
52
+ /** Bumped when the shape of a checked template changes; builds and runtimes must agree. */
53
+ declare const AST_FORMAT_VERSION = 3;
54
+ /** A literal value in a template expression. */
55
+ type Literal = string | number | boolean | null;
56
+ /** One step of a path expression: `.name`, `[expr]`, or their `?.` forms. */
57
+ interface PathSegment {
58
+ /** `.name` / `?.name` */
59
+ name?: string;
60
+ /** `[expr]` / `?.[expr]` */
61
+ computed?: Expr;
62
+ optional: boolean;
63
+ }
64
+ /** A parsed template expression. */
65
+ type Expr = {
66
+ kind: 'literal';
67
+ value: Literal;
68
+ span: Span;
69
+ } | {
70
+ kind: 'path';
71
+ root: string;
72
+ segments: PathSegment[];
73
+ span: Span;
74
+ } | {
75
+ kind: 'unary';
76
+ op: '!' | '-';
77
+ arg: Expr;
78
+ span: Span;
79
+ } | {
80
+ kind: 'binary';
81
+ op: '+' | '-' | '<' | '>' | '<=' | '>=' | '==' | '!=' | '===' | '!==';
82
+ left: Expr;
83
+ right: Expr;
84
+ span: Span;
85
+ } | {
86
+ kind: 'logical';
87
+ op: '&&' | '||' | '??';
88
+ left: Expr;
89
+ right: Expr;
90
+ span: Span;
91
+ } | {
92
+ kind: 'conditional';
93
+ test: Expr;
94
+ whenTrue: Expr;
95
+ whenFalse: Expr;
96
+ span: Span;
97
+ } | {
98
+ kind: 'pipe';
99
+ input: Expr;
100
+ name: string;
101
+ args: Expr[];
102
+ span: Span;
103
+ };
104
+ /** Where an interpolation lands, which decides how its value is escaped. */
105
+ type Ctx = 'text' | 'rcdata' | 'raw-text' | 'comment';
106
+ /** A parsed element attribute. */
107
+ interface Attr {
108
+ /** As written: `href`, `userId` (from `[userId]`), `on` (from `[class.on]`). */
109
+ name: string;
110
+ /**
111
+ * `static` `a="x"`, `interp` `a="x{{ y }}"`, `bare` `a`, `bind` `[a]="expr"`,
112
+ * `class` `[class.a]="expr"`, `style` `[style.a(.unit)]="expr"`.
113
+ */
114
+ kind: 'static' | 'interp' | 'bare' | 'bind' | 'class' | 'style';
115
+ /** `static` / `interp`: the value, literal text and expressions in order. */
116
+ parts?: Array<string | Expr>;
117
+ /** `bind` / `class` / `style`: the bound expression. */
118
+ expr?: Expr;
119
+ /** `[style.width.px]`: `px`. */
120
+ unit?: string;
121
+ quoted: boolean;
122
+ span: Span;
123
+ }
124
+ /** A parsed HTML element. */
125
+ interface Element {
126
+ k: 'element';
127
+ /** As written. */
128
+ tag: string;
129
+ attrs: Attr[];
130
+ children: Node[];
131
+ /** Inside `<svg>` / `<math>`: names keep their case. */
132
+ foreign: boolean;
133
+ void: boolean;
134
+ selfClosing: boolean;
135
+ span: Span;
136
+ }
137
+ /** One branch of an `@if` / `@else if` / `@else` chain. */
138
+ interface IfBranch {
139
+ /** Absent on `@else`. */
140
+ cond?: Expr;
141
+ /** `@if (x; as y)` */
142
+ alias?: string;
143
+ body: Node[];
144
+ }
145
+ /** A loop variable an `@for` can bind with `let`. */
146
+ type LoopVar = '$index' | '$first' | '$last' | '$even' | '$odd' | '$count';
147
+ /** A parsed template node. */
148
+ type Node = {
149
+ k: 'text';
150
+ value: string;
151
+ span: Span;
152
+ } | {
153
+ k: 'interp';
154
+ expr: Expr;
155
+ ctx: Ctx;
156
+ span: Span;
157
+ } | Element | {
158
+ k: 'comment';
159
+ children: Node[];
160
+ span: Span;
161
+ } | {
162
+ k: 'if';
163
+ branches: IfBranch[];
164
+ span: Span;
165
+ } | {
166
+ k: 'for';
167
+ item: string | [string, string];
168
+ of: Expr;
169
+ lets: Record<string, LoopVar>;
170
+ body: Node[];
171
+ empty?: Node[];
172
+ span: Span;
173
+ } | {
174
+ k: 'switch';
175
+ on: Expr;
176
+ cases: Array<{
177
+ value: Expr;
178
+ body: Node[];
179
+ }>;
180
+ default?: Node[];
181
+ span: Span;
182
+ } | {
183
+ k: 'let';
184
+ name: string;
185
+ expr: Expr;
186
+ span: Span;
187
+ } | {
188
+ k: 'verbatim';
189
+ text: string;
190
+ span: Span;
191
+ } |
192
+ /** `<slot name="n" [x]="expr">`: the values (`offers`) it hands the caller's content */
193
+ {
194
+ k: 'slot-outlet';
195
+ name?: string;
196
+ offers: Array<{
197
+ name: string;
198
+ expr: Expr;
199
+ span: Span;
200
+ }>;
201
+ fallback: Node[];
202
+ span: Span;
203
+ } |
204
+ /** `@slot('n'; let a, b = c) { }`: `lets` bind offered values (`from`) to names */
205
+ {
206
+ k: 'slot-fill';
207
+ name: string;
208
+ lets: Array<{
209
+ name: string;
210
+ from: string;
211
+ }>;
212
+ body: Node[];
213
+ span: Span;
214
+ } | {
215
+ k: 'assets';
216
+ entry: string;
217
+ span: Span;
218
+ } |
219
+ /** `@fragment('name') { }`: a block a render can ask for on its own */
220
+ {
221
+ k: 'fragment';
222
+ name: string;
223
+ body: Node[];
224
+ span: Span;
225
+ } |
226
+ /** `@push('name') { }`: content for a layout's `<stack name>` */
227
+ {
228
+ k: 'push';
229
+ name: string;
230
+ body: Node[];
231
+ span: Span;
232
+ } |
233
+ /** `@snippet name(a, b = 'x') { }`: a block of markup with parameters, top level only */
234
+ {
235
+ k: 'snippet';
236
+ name: string;
237
+ params: Array<{
238
+ name: string;
239
+ default?: Literal;
240
+ }>;
241
+ body: Node[];
242
+ span: Span;
243
+ } |
244
+ /** `@render name(args)`: run a snippet of this file */
245
+ {
246
+ k: 'render';
247
+ name: string;
248
+ args: Expr[];
249
+ span: Span;
250
+ } |
251
+ /** `<stack name="…" />`: where pushed content goes; `children` must be blank (checked) */
252
+ {
253
+ k: 'stack';
254
+ name: string;
255
+ children: Node[];
256
+ span: Span;
257
+ };
258
+ /** An `@input` declaration, with its default when given. */
259
+ interface InputDecl {
260
+ name: string;
261
+ /** `@input name: Type`: the TypeScript type, as written (typegen copies it) */
262
+ type?: string;
263
+ default?: {
264
+ value: Literal;
265
+ span: Span;
266
+ };
267
+ span: Span;
268
+ }
269
+ /** A parsed template: its layout, inputs and body. */
270
+ interface TemplateAst {
271
+ file: string;
272
+ /** `undefined`: none declared (the default layout applies); `null`: `@layout(none)`. */
273
+ layout?: string | null;
274
+ layoutSpan?: Span;
275
+ inputs: InputDecl[];
276
+ /** `@import type … from '…'` lines, as written without the `@` (typegen copies them) */
277
+ typeImports?: string[];
278
+ body: Node[];
279
+ }
280
+ /** `[line, column]` of a node in its template, for render errors. */
281
+ type At = [number, number];
282
+ /** A path segment: `.n` or `[e]`; `o` marks `?.`. */
283
+ type CSeg = {
284
+ n: string;
285
+ o?: 1;
286
+ } | {
287
+ e: CExpr;
288
+ o?: 1;
289
+ };
290
+ /** A checked expression, as the renderer reads it. */
291
+ type CExpr =
292
+ /** literal */
293
+ {
294
+ k: 'l';
295
+ v: Literal;
296
+ } |
297
+ /** undefined (a name a component doesn't have) */
298
+ {
299
+ k: 'x';
300
+ } |
301
+ /** page / shared data: `n` then the path */
302
+ {
303
+ k: 'd';
304
+ n: string;
305
+ p: CSeg[];
306
+ } |
307
+ /** a scope slot (@let, loop item, @if alias, component input) then the path */
308
+ {
309
+ k: 'v';
310
+ s: number;
311
+ p: CSeg[];
312
+ } |
313
+ /** a loop variable of the loop whose meta is in slot `s` */
314
+ {
315
+ k: 'm';
316
+ s: number;
317
+ w: LoopVar;
318
+ } | {
319
+ k: 'u';
320
+ o: '!' | '-';
321
+ a: CExpr;
322
+ } | {
323
+ k: 'b';
324
+ o: string;
325
+ l: CExpr;
326
+ r: CExpr;
327
+ } | {
328
+ k: 'c';
329
+ t: CExpr;
330
+ y: CExpr;
331
+ n: CExpr;
332
+ } | {
333
+ k: 'p';
334
+ n: string;
335
+ i: CExpr;
336
+ a: CExpr[];
337
+ };
338
+ /** One attribute of an element whose attributes need work at render time. */
339
+ type CAttr =
340
+ /** static; `v: true` is a bare attribute */
341
+ {
342
+ t: 's';
343
+ n: string;
344
+ v: string | true;
345
+ } |
346
+ /** `n="text {{ e }}"`; `u` marks a URL attribute (`srcset` checks each candidate) */
347
+ {
348
+ t: 'i';
349
+ n: string;
350
+ p: Array<string | CExpr>;
351
+ u?: 'url' | 'srcset';
352
+ } |
353
+ /** `[n]="e"` */
354
+ {
355
+ t: 'b';
356
+ n: string;
357
+ e: CExpr;
358
+ u?: 'url' | 'srcset';
359
+ } |
360
+ /** `[class.n]="e"` */
361
+ {
362
+ t: 'c';
363
+ n: string;
364
+ e: CExpr;
365
+ } |
366
+ /** `[style.n(.x)]="e"` */
367
+ {
368
+ t: 'y';
369
+ n: string;
370
+ e: CExpr;
371
+ x?: string;
372
+ };
373
+ /** A checked template node, as the renderer walks it. */
374
+ /**
375
+ * Slot content: its nodes, compiled in the caller's scope, and the offered
376
+ * values it takes (`let x = from`), each bound to caller slot `s`.
377
+ */
378
+ interface CFill {
379
+ nodes: CNode[];
380
+ params?: Array<{
381
+ from: string;
382
+ s: number;
383
+ }>;
384
+ }
385
+ type CNode =
386
+ /** static output */
387
+ {
388
+ k: 's';
389
+ t: string;
390
+ } |
391
+ /** `{{ e }}`: `text` escapes HTML (trusted HTML prints as is), `rcdata` (`<title>`, `<textarea>`) escapes everything, `json` is the one value of a JSON script */
392
+ {
393
+ k: 'i';
394
+ c: 'text' | 'rcdata' | 'json' | 'css';
395
+ e: CExpr;
396
+ at: At;
397
+ } |
398
+ /** the attributes of an element (between `<tag` and `>`); `f` takes a component caller's fallthrough attributes */
399
+ {
400
+ k: 'A';
401
+ tag: string;
402
+ a: CAttr[];
403
+ f?: 1;
404
+ at: At;
405
+ } | {
406
+ k: 'if';
407
+ br: Array<{
408
+ c?: CExpr;
409
+ a?: number;
410
+ b: CNode[];
411
+ }>;
412
+ } | {
413
+ k: 'for';
414
+ e: CExpr;
415
+ it: number | [number, number];
416
+ m: number;
417
+ b: CNode[];
418
+ em?: CNode[];
419
+ at: At;
420
+ } | {
421
+ k: 'sw';
422
+ e: CExpr;
423
+ cs: Array<{
424
+ e: CExpr;
425
+ b: CNode[];
426
+ }>;
427
+ d?: CNode[];
428
+ } | {
429
+ k: 'let';
430
+ s: number;
431
+ e: CExpr;
432
+ } |
433
+ /** a component: inputs into its slots, fallthrough attributes, slot fills (`''` is the default) */
434
+ {
435
+ k: 'cmp';
436
+ n: string;
437
+ in: Array<{
438
+ s: number;
439
+ e: CExpr;
440
+ }>;
441
+ /** inputs of wrapped components further down the chain, by name */
442
+ ci?: Array<{
443
+ n: string;
444
+ e: CExpr;
445
+ }>;
446
+ fa: CAttr[];
447
+ f: Record<string, CFill>;
448
+ /** this call is its template's root: it takes the caller's chained attributes */
449
+ r?: 1;
450
+ at: At;
451
+ } |
452
+ /**
453
+ * `<slot name="n" [x]="e">fallback</slot>`: `v` are the values it offers;
454
+ * while the fallback renders they sit in slots `fs` (same order).
455
+ */
456
+ {
457
+ k: 'o';
458
+ n: string;
459
+ fb: CNode[];
460
+ v?: Array<{
461
+ n: string;
462
+ e: CExpr;
463
+ }>;
464
+ fs?: number[];
465
+ } |
466
+ /**
467
+ * `<component [is]="e" of="…">`: one compiled call per candidate tag, picked
468
+ * by `e`. The slot content `f` is compiled once, here, and given to whichever
469
+ * candidate renders (it's in the caller's scope, the same for all).
470
+ */
471
+ {
472
+ k: 'dyn';
473
+ e: CExpr;
474
+ c: Record<string, CNode>;
475
+ f: Record<string, CFill>;
476
+ at: At;
477
+ } |
478
+ /** `@render n(args)`: run snippet `n` of the current template */
479
+ {
480
+ k: 'rnd';
481
+ n: string;
482
+ a: CExpr[];
483
+ at: At;
484
+ } |
485
+ /** `@push('n') { }`: rendered, then added to stack `n` */
486
+ {
487
+ k: 'push';
488
+ n: string;
489
+ b: CNode[];
490
+ } |
491
+ /** `<stack name="n" />`: filled once the render is done */
492
+ {
493
+ k: 'stk';
494
+ n: string;
495
+ } | {
496
+ k: 'as';
497
+ en: string;
498
+ };
499
+ /** A template after `check`: plain JSON the renderer walks, which a build can ship as data. */
500
+ /**
501
+ * A `@snippet`, in its own slot space: the template's inputs first (same
502
+ * indexes as in the template), then `params`, then its own variables.
503
+ */
504
+ interface CSnippet {
505
+ params: number[];
506
+ defaults: Array<Literal | undefined>;
507
+ slots: number;
508
+ body: CNode[];
509
+ /** a field in it has `validate` */
510
+ validates?: true;
511
+ }
512
+ /** A page's `@fragment`, compiled to render on its own. */
513
+ interface CheckedFragment {
514
+ /** names enclosing blocks bound (loop items, aliases, `@let`): the caller passes them */
515
+ needs: string[];
516
+ /** scope slots the unit needs */
517
+ slots: number;
518
+ body: CNode[];
519
+ /** a field in it has `validate` */
520
+ validates?: true;
521
+ }
522
+ interface CheckedTemplate {
523
+ v: typeof AST_FORMAT_VERSION;
524
+ name: string;
525
+ file: string;
526
+ /** declared layout; `null` is `@layout(none)`; absent means the default layout applies to a page */
527
+ layout?: string | null;
528
+ /** scope slots the template needs */
529
+ slots: number;
530
+ /** a component's inputs: name, slot, default, required */
531
+ inputs: Array<{
532
+ n: string;
533
+ s: number;
534
+ d?: Literal;
535
+ r: boolean;
536
+ }>;
537
+ /** `@slot('name') { }` fills a page passes to its layout */
538
+ fills: Record<string, CFill>;
539
+ body: CNode[];
540
+ /** a component's `<script client>`: TypeScript as written (`js: false`), or plain JS once a build stripped it */
541
+ client?: {
542
+ code: string;
543
+ js: boolean;
544
+ };
545
+ /** a field in it has `validate`: pages rendering it ship the validator script */
546
+ validates?: true;
547
+ /** a page's `@input name = value` defaults: data that fills in when nobody supplied it */
548
+ defaults?: Record<string, Literal>;
549
+ /** its `@snippet`s, by name */
550
+ snippets?: Record<string, CSnippet>;
551
+ /** its `@fragment`s, by name */
552
+ fragments?: Record<string, CheckedFragment>;
553
+ }
554
+ /**
555
+ * Every `.kick` page by name: the data it reads and its fragments' needs.
556
+ * Filled by `kick typegen`; don't write entries by hand.
557
+ *
558
+ * @see https://kickjs.app/guide/views/typed-render-data
559
+ */
560
+ interface KickViews {}
561
+ /**
562
+ * Names `createViews({ share })` supplies to every page, so a controller
563
+ * needn't pass them. Declare them once:
564
+ *
565
+ * ```ts
566
+ * declare module '@forinda/kickjs-view' {
567
+ * interface KickViewShared { user: User | undefined; csrfToken: string }
568
+ * }
569
+ * ```
570
+ *
571
+ * @see https://kickjs.app/guide/views/typed-render-data
572
+ */
573
+ interface KickViewShared {}
574
+ /**
575
+ * Switches for the render types. `otherEngines: true` lets names outside
576
+ * {@link KickViews} through — for an app that also renders EJS or Pug with
577
+ * `ViewAdapter` (a misspelled `.kick` name then compiles too).
578
+ *
579
+ * @see https://kickjs.app/guide/views/typed-render-data
580
+ */
581
+ interface KickViewTypeOptions {}
582
+ type Opts = Omit<RenderOptions, 'fragment'> & {
583
+ ctx?: unknown;
584
+ };
585
+ /** Template names `R` knows, `string` while it's empty or other engines are on. */
586
+ type ViewNameOf<R, O> = [keyof R] extends [never] ? string : O extends {
587
+ otherEngines: true;
588
+ } ? string : Extract<keyof R, string>;
589
+ type DataOf<R, N> = N extends keyof R ? (R[N] extends {
590
+ data: infer D;
591
+ } ? D : never) : never;
592
+ type Intersect<U> = (U extends unknown ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
593
+ /**
594
+ * Shared names may be left out; extra keys are fine. The union keeps an
595
+ * interface or class instance assignable (they have no index signature),
596
+ * while an object literal's extra keys are allowed by the second member.
597
+ */
598
+ type Shaped<D, S> = Omit<D, keyof S> & Partial<Pick<D, Extract<keyof D, keyof S>>>;
599
+ type WithShared<D, S> = Shaped<D, S> | (Shaped<D, S> & Record<string, unknown>);
600
+ /** The data `ctx.render(N, data)` takes; for a union of names, what every one of those pages needs. */
601
+ type ViewDataOf<R, S, N> = [DataOf<R, N>] extends [never] ? Record<string, any> : WithShared<Intersect<DataOf<R, N>>, S>;
602
+ type FragmentsOf<R, N> = N extends keyof R ? (R[N] extends {
603
+ fragments: infer F;
604
+ } ? F : {}) : never;
605
+ /** A fragment name of page `N` (any string for names the registry doesn't know). */
606
+ type ViewFragmentNameOf<R, N> = [FragmentsOf<R, N>] extends [never] ? string : Extract<keyof FragmentsOf<R, N>, string>;
607
+ /** What `opts.fragment` may be: one fragment of page `N`, or a list of them. */
608
+ type FragmentNames<R, N> = ViewFragmentNameOf<R, N> | readonly ViewFragmentNameOf<R, N>[];
609
+ type Part<R, N, K, P extends 'needs' | 'reads'> = K extends keyof FragmentsOf<R, N> ? FragmentsOf<R, N>[K] extends Record<P, infer X> ? X : never : never;
610
+ type Listed<F> = F extends readonly (infer X)[] ? X : F;
611
+ /**
612
+ * The data a fragment render takes: for every fragment named, its needs
613
+ * exactly (the controller passes them; `share()` doesn't count at render),
614
+ * plus the page data it reads.
615
+ */
616
+ type ViewFragmentDataOf<R, S, N, F> = [FragmentsOf<R, N>] extends [never] ? Record<string, any> : Intersect<Part<R, N, Listed<F>, 'needs'>> & WithShared<Intersect<Part<R, N, Listed<F>, 'reads'>>, S>;
617
+ /**
618
+ * The arguments after the name, without a fragment: `data` (required when
619
+ * the page needs any) and options. Fragment renders have their own overload.
620
+ */
621
+ type RenderArgs<R, S, N> = [DataOf<R, N>] extends [never] ? [data?: Record<string, any>, opts?: Opts & {
622
+ fragment?: string | readonly string[];
623
+ }] : {} extends ViewDataOf<R, S, N> ? [data?: ViewDataOf<R, S, N>, opts?: Opts & {
624
+ fragment?: undefined;
625
+ }] : [data: ViewDataOf<R, S, N>, opts?: Opts & {
626
+ fragment?: undefined;
627
+ }];
628
+ /**
629
+ * What name `N` the loose overload takes: any string while the registry is
630
+ * empty (so generic helpers compile); with other engines on, any name but a
631
+ * registered one — a known page can't skip its data through it; else none.
632
+ */
633
+ type LooseViewNameOf<R, O, N> = [keyof R] extends [never] ? string : O extends {
634
+ otherEngines: true;
635
+ } ? [Extract<N, keyof R>] extends [never] ? string : never : never;
636
+ /** The app's template names. */
637
+ type ViewName = ViewNameOf<KickViews, KickViewTypeOptions>;
638
+ /** The data page `N` takes. */
639
+ type ViewData<N> = ViewDataOf<KickViews, KickViewShared, N>;
640
+ /** Arguments after the name, for the app's registry. */
641
+ type ViewRenderArgs<N> = RenderArgs<KickViews, KickViewShared, N>;
642
+ /** `opts.fragment` for page `N`. */
643
+ type ViewFragmentNames<N> = FragmentNames<KickViews, N>;
644
+ /** The data a fragment render of page `N` takes. */
645
+ type ViewFragmentData<N, F> = ViewFragmentDataOf<KickViews, KickViewShared, N, F>;
646
+ /** The loose overload's name, for the app's registry. */
647
+ type LooseViewName<N> = LooseViewNameOf<KickViews, KickViewTypeOptions, N>;
648
+ /** A pipe: takes the piped value and the pipe's arguments, returns the new value. */
649
+ type Pipe = (value: unknown, ...args: unknown[]) => unknown;
650
+ /** What a render needs besides the data: locale, pipes, how to resolve layouts and components. */
651
+ interface RenderEnv {
652
+ locale: string;
653
+ timeZone: string;
654
+ strict: boolean;
655
+ pipes: Record<string, Pipe>;
656
+ warn(message: string): void;
657
+ /** A checked template by name: layouts and components. */
658
+ resolve(name: string): CheckedTemplate;
659
+ /** The layout a page gets when it declares none (a folder mapping, usually). */
660
+ layoutFor?(page: string): string | undefined;
661
+ /** The shell wrapped around every page's outermost layout. */
662
+ baseLayout?: string;
663
+ /** `@assets('entry')`: the tags for a Vite entry; `data` is the page's (for a CSP nonce). */
664
+ assets?(entry: string, data: Record<string, unknown>): string;
665
+ /** A component with a `<script client>` rendered: the page ships its script. */
666
+ clientScript?(t: CheckedTemplate): void;
667
+ /** A template with a `validate` field rendered: the page ships the validator script. */
668
+ validation?(): void;
669
+ }
670
+ /** Thrown when a render fails; `diagnostic` has the template, position and message. */
671
+ declare class RenderError extends Error {
672
+ readonly diagnostic: Diagnostic;
673
+ constructor(diagnostic: Diagnostic);
674
+ }
675
+ /** The most components one render may nest — a self-including component stops here. */
676
+ declare const MAX_DEPTH = 64;
677
+ /**
678
+ * Render a checked page with `data`. Its layouts wrap it, outermost last:
679
+ * `opts.layout` (a name, or `false` for none), else the page's `@layout`, else
680
+ * the environment's mapping — then the base layout around the outermost one.
681
+ * `@layout(none)` and `layout: false` skip the base too.
682
+ */
683
+ declare function render(template: CheckedTemplate, data: object, env: RenderEnv, opts?: {
684
+ layout?: boolean | string;
685
+ /** Render only these fragments of the page, without layouts. */
686
+ fragment?: string | readonly string[];
687
+ /** The caller's own data, which a fragment's needs are checked against (default `data`). */
688
+ callerData?: object;
689
+ }): string;
690
+ /** HTML a pipe or the app marked as trusted: printed unescaped, in text only. */
691
+ declare class SafeHtml {
692
+ readonly html: string;
693
+ constructor(html: string);
694
+ toString(): string;
695
+ }
696
+ /**
697
+ * Read `obj[key]` for a template. Forbidden names and function values read
698
+ * as `undefined`, so a template can neither reach a prototype nor get hold of
699
+ * something to call. Getters and Proxy traps run: they are the app's own code.
700
+ */
701
+ declare function read(obj: unknown, key: unknown): unknown;
702
+ /** Escapes `&`, `<`, `>`, `"` and `'` for HTML text and attribute values. */
703
+ declare const escapeHtml: (s: string) => string;
704
+ /**
705
+ * A URL attribute's value, or `#` when its scheme could run script.
706
+ * Browsers ignore ASCII whitespace and control characters inside a scheme
707
+ * (`java\tscript:`), so those are removed before the scheme is read.
708
+ */
709
+ declare function sanitizeUrl(value: string): string;
710
+ /** `srcset`: each candidate URL is checked on its own. */
711
+ declare function sanitizeSrcset(value: string): string;
712
+ /** JSON text made safe inside `<script type="application/json">`: no `</script`, no `<!--`. */
713
+ declare const escapeJsonForScript: (json: string) => string;
714
+ /** A CSS value for `[style.prop]`, or `undefined` when it could leave its property. */
715
+ declare function safeStyleValue(v: string): string | undefined;
716
+ /** The names of the built-in pipes. */
717
+ declare const BUILTIN_PIPES: readonly string[];
718
+ /**
719
+ * Built-ins added later: an app pipe of the same name wins, so apps that
720
+ * already had their own `ago` or `truncate` keep it.
721
+ */
722
+ declare const OVERRIDABLE_PIPES: readonly string[];
723
+ /** What built-in pipes read from the render: locale, time zone, and the request's `urlFor`. */
724
+ interface PipeEnv {
725
+ locale: string;
726
+ timeZone: string;
727
+ /** The request's `ctx.urlFor` (params in path order), for `kvRoute`. Absent outside a request. */
728
+ urlFor?: (name: string, params: Array<string | number>) => string;
729
+ /** The render's message lookup, for `t`; absent outside `createViews` (then `t` prints the key). */
730
+ translate?: (key: string, params: Record<string, unknown>) => string;
731
+ }
732
+ /**
733
+ * The built-in pipes bound to a render's locale and time zone (`date`, `currency`, `kvRoute`, ...).
734
+ *
735
+ * @see https://kickjs.app/guide/views/pipes
736
+ */
737
+ declare function builtinPipes(env: PipeEnv): Record<string, Pipe>;
738
+ declare const ENV_PIPE: unique symbol;
739
+ /** A pipe built per render from the render's locale and time zone. */
740
+ interface EnvPipe {
741
+ [ENV_PIPE]: (env: PipeEnv) => Pipe;
742
+ }
743
+ /**
744
+ * A pipe that needs the render's locale or time zone:
745
+ * `export const ago = withEnv(({ locale }) => (date: Date) => …)`.
746
+ */
747
+ declare function withEnv(make: (env: PipeEnv) => Pipe): EnvPipe;
748
+ /** Mark HTML as trusted: a pipe returning it prints unescaped, in text only. */
749
+ declare const safeHtml: (html: string) => SafeHtml;
750
+ /** The pipes for one render: the built-ins and the app's, with env pipes built for `env`. */
751
+ declare function pipesFor(app: Record<string, Pipe | EnvPipe>, env: PipeEnv): Record<string, Pipe>;
752
+ /** Where `createViews` reads template sources from. */
753
+ interface Loader {
754
+ /** Every template name (`users/show`, `components/user-card`). */
755
+ list(): Promise<string[]>;
756
+ read(name: string): Promise<string>;
757
+ /** Changes when the source changes (an mtime); checked on every render in dev. */
758
+ version?(name: string): Promise<number>;
759
+ /** The file `name` came from, for messages (default `<name>.kick`). */
760
+ file?(name: string): string;
761
+ }
762
+ /** What a build emits: checked templates as data. */
763
+ interface ViewsBundle {
764
+ v: number;
765
+ templates: Record<string, CheckedTemplate>;
766
+ /** Client scripts bundled by the build: each component's entry file, and every file (entries and shared chunks). */
767
+ client?: {
768
+ entries: Record<string, string>;
769
+ /** Each entry's stylesheets, by component tag. */
770
+ css?: Record<string, string[]>;
771
+ /** Files kept in the bundle (`clientFiles: 'bundle'`). */
772
+ files?: Record<string, string>;
773
+ /** Files the build wrote to disk, under `clientDir` (`clientFiles: 'disk'`). */
774
+ disk?: string[];
775
+ };
776
+ }
777
+ /** Per-render options: layout, locale and time zone. */
778
+ interface RenderOptions {
779
+ /** A layout for this render, or `false` for none at all (htmx and other partial responses). */
780
+ layout?: boolean | string;
781
+ /**
782
+ * Render only these `@fragment`s of the page, in order, without layouts —
783
+ * an htmx swap (several for out-of-band swaps).
784
+ */
785
+ fragment?: string | readonly string[];
786
+ locale?: string;
787
+ timeZone?: string;
788
+ }
789
+ /** What `share` can read from the request: KickJS's `RequestContext` has both. */
790
+ interface ShareContext {
791
+ req: unknown;
792
+ get(key: string): unknown;
793
+ }
794
+ /** Options for `createViews` and `KickView`. */
795
+ interface ViewsOptions {
796
+ /** Default `src/views`. */
797
+ viewsDir?: string;
798
+ /**
799
+ * More view folders, by name (absolute paths): `{ billing: '/app/src/modules/billing/views' }`
800
+ * renders `billing::invoices/show`. The Vite plugin fills it in from kick.config's `views.roots`.
801
+ */
802
+ roots?: Record<string, string>;
803
+ /** Default `components`, inside the views folder. */
804
+ componentsDir?: string;
805
+ /** Default `src/views/pipes.ts`. Read when `pipes` isn't given and there is no bundle. */
806
+ pipesFile?: string;
807
+ /** Default `<viewsDir>/validators.ts`: the app's browser validators. Read when there is no bundle. */
808
+ validatorsFile?: string;
809
+ pipes?: Record<string, Pipe | EnvPipe>;
810
+ /**
811
+ * Message catalogues for `t`: locale → dot key → message. Default: read from
812
+ * `<viewsDir>/locales/*.json` (the Vite plugin bundles them as `messages`).
813
+ */
814
+ messages?: Messages;
815
+ /** The locale a message falls back to. Default: `locale`, else `en-US`. */
816
+ messagesLocale?: string;
817
+ /**
818
+ * The layout a page gets when it declares none: one name, or folder prefix →
819
+ * layout (`{ admin: 'layouts/admin', '': 'layouts/main' }`; the longest prefix wins).
820
+ */
821
+ layout?: string | Record<string, string>;
822
+ /** The shell (CSS, assets, SEO tags) wrapped around every page's outermost layout. */
823
+ baseLayout?: string;
824
+ /** Default `en-US`. */
825
+ locale?: string;
826
+ /** Default `UTC`. */
827
+ timeZone?: string;
828
+ /** Unresolved names and values that can't print become errors. */
829
+ strict?: boolean;
830
+ /** Default `true`. `false` re-reads and re-checks on every render. */
831
+ cache?: boolean;
832
+ /**
833
+ * Data every render gets, under the page's own: the current user, a CSP nonce.
834
+ * `ctx` is the request the page renders in (KickJS's `RequestContext`), or
835
+ * `undefined` outside one.
836
+ */
837
+ share?: (ctx: ShareContext | undefined) => object | Promise<object>;
838
+ loader?: Loader;
839
+ /** Checked templates from the build (`virtual:kick-views`); `null` in dev. */
840
+ bundle?: ViewsBundle | null;
841
+ /** Re-check templates whose source changed, on every render. Default: on when `bundle` is `null` (`kick dev`). */
842
+ dev?: boolean;
843
+ /**
844
+ * `@assets('entry')`: usually `(entry, data) => assetTags(entry, mode, data.cspNonce)`.
845
+ * `data` is the page's data with shared data merged in.
846
+ */
847
+ assets?: (entry: string, data: Record<string, unknown>) => string;
848
+ warn?: (message: string) => void;
849
+ /** Strips a `<script client>`'s TypeScript when a build hasn't. Default: Node's `stripTypeScriptTypes` (22.13+), on the Node entry. */
850
+ stripTypes?: (code: string) => string | Promise<string>;
851
+ /** Where component scripts are served. Default `'/_kick/c'`. */
852
+ clientScriptPath?: string;
853
+ /** A `file:` URL of the folder holding the bundle's `disk` files; `virtual:kick-views` exports it. */
854
+ clientDir?: string;
855
+ }
856
+ /** A views instance: renders templates and serves component client scripts. */
857
+ interface Views {
858
+ render<N extends ViewName>(name: N, ...args: ViewRenderArgs<N>): Promise<string>;
859
+ render<N extends ViewName, const F extends ViewFragmentNames<N>>(name: N, data: ViewFragmentData<N, F>, opts: RenderOptions & {
860
+ fragment: F;
861
+ ctx?: unknown;
862
+ }): Promise<string>;
863
+ render<N extends string>(name: N & LooseViewName<N>, data?: object, opts?: RenderOptions & {
864
+ ctx?: unknown;
865
+ }): Promise<string>;
866
+ /** A component's script by its served file name (`<tag>.<hash>.js`); `undefined` when there's none by that name. */
867
+ clientScript(file: string): Promise<string | undefined>;
868
+ /** A client file (script, stylesheet, asset) by its served name, with its content type. */
869
+ clientFile(file: string): Promise<{
870
+ body: string | Uint8Array;
871
+ type: string;
872
+ } | undefined>;
873
+ /** The path component scripts are served under (`clientScriptPath`). */
874
+ readonly clientScriptPath: string;
875
+ /** Whether `name` is one of these views — `ctx.render` falls through to another engine when not. */
876
+ has(name: string): Promise<boolean>;
877
+ /** A message from the catalogues, as `t` prints it: for controllers, emails and flash messages. */
878
+ t(key: string, params?: Record<string, unknown>, opts?: {
879
+ locale?: string;
880
+ }): Promise<string>;
881
+ }
882
+ /** A loader over a build's bundle; throws when the bundle's format version doesn't match this runtime. */
883
+ declare function bundleLoader(bundle: ViewsBundle): Loader;
884
+ type FileLoaderModule = typeof file_d_exports;
885
+ /**
886
+ * How `createViews` reaches the file loader when it's given neither a loader
887
+ * nor a bundle. The Node entry sets it; the edge entry (`workerd`, `worker`,
888
+ * `browser` conditions) doesn't, so an edge build never contains `node:fs`.
889
+ */
890
+ declare function useFileLoader(load: () => Promise<FileLoaderModule>): void;
891
+ /** The TypeScript stripper for `<script client>`; the Node entry sets it. */
892
+ declare function useStripTypes(strip: (code: string) => string): void;
893
+ /** Reads a client file the build wrote to disk; the Node entry sets it. */
894
+ declare function useClientFiles(read: ((url: URL) => Promise<Uint8Array>) | undefined): void;
895
+ /**
896
+ * Creates a views instance: templates from a loader or a build's bundle, checked on first use
897
+ * and cached, rendered with the app's pipes and shared data. Use it directly to render
898
+ * outside a request (emails, tests), or pass it to `KickView({ views })`.
899
+ *
900
+ * @example
901
+ * ```ts
902
+ * const views = createViews({ layout: 'layouts/main' })
903
+ * const html = await views.render('emails/welcome', { user })
904
+ * ```
905
+ *
906
+ * @see https://kickjs.app/guide/views
907
+ */
908
+ declare function createViews(options?: ViewsOptions): Views;
909
+ declare namespace file_d_exports {
910
+ export { fileLoader, loadPipesFile, multiRootLoader, readCatalogs, readTextFile };
911
+ }
912
+ declare function fileLoader(viewsDir: string): Loader;
913
+ /**
914
+ * The app's views folder plus named roots: a root's templates are listed and
915
+ * read as `root::path`.
916
+ */
917
+ declare function multiRootLoader(appDir: string, roots: Record<string, string>): Loader;
918
+ /** The app's pipes file, if there is one, imported as a module. */
919
+ declare function loadPipesFile(file: string): Promise<Record<string, unknown> | undefined>;
920
+ /** A text file's contents, or undefined when there's none. */
921
+ declare function readTextFile(file: string): Promise<string | undefined>;
922
+ /** Every `<locale>.json` in `dir`; `undefined` when there's no such folder. */
923
+ declare function readCatalogs(dir: string): Promise<Messages | undefined>;
924
+ export { CExpr as $, sanitizeSrcset as A, KickViews as B, PipeEnv as C, escapeJsonForScript as D, escapeHtml as E, RenderError as F, ViewFragmentData as G, RenderArgs as H, render as I, ViewNameOf as J, ViewFragmentDataOf as K, FragmentNames as L, MAX_DEPTH as M, Pipe as N, read as O, RenderEnv as P, CAttr as Q, KickViewShared as R, OVERRIDABLE_PIPES as S, SafeHtml as T, ViewData as U, LooseViewNameOf as V, ViewDataOf as W, AST_FORMAT_VERSION as X, ViewRenderArgs as Y, Attr as Z, EnvPipe as _, CatalogIndex as _t, readTextFile as a, Expr as at, withEnv as b, catalogIndex as bt, ShareContext as c, Literal as ct, ViewsOptions as d, PathSegment as dt, CNode as et, bundleLoader as f, TemplateAst as ft, useStripTypes as g, positionAt as gt, useFileLoader as h, Span as ht, readCatalogs as i, Element as it, sanitizeUrl as j, safeStyleValue as k, Views as l, LoopVar as lt, useClientFiles as m, Pos as mt, loadPipesFile as n, CheckedTemplate as nt, Loader as o, IfBranch as ot, createViews as p, Diagnostic as pt, ViewName as q, multiRootLoader as r, Ctx as rt, RenderOptions as s, InputDecl as st, fileLoader as t, CSeg as tt, ViewsBundle as u, Node as ut, pipesFor as v, Message as vt, builtinPipes as w, BUILTIN_PIPES as x, safeHtml as y, Messages as yt, KickViewTypeOptions as z };
925
+ //# sourceMappingURL=file-BIua9gOB.d.ts.map