@format.dev/react 0.0.0 → 0.1.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.
- package/dist/index.cjs +468 -0
- package/dist/index.d.cts +621 -0
- package/dist/index.d.cts.map +1 -0
- package/dist/index.d.ts +621 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +451 -0
- package/dist/index.js.map +1 -0
- package/package.json +49 -31
- package/README.md +0 -32
- package/index.d.ts +0 -2
- package/index.js +0 -3
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,621 @@
|
|
|
1
|
+
import * as react0 from "react";
|
|
2
|
+
import { CSSProperties, ElementType, HTMLAttributes, PropsWithChildren, ReactNode } from "react";
|
|
3
|
+
|
|
4
|
+
//#region src/types.d.ts
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* How a Flow splits content that overflows a page: at a `sentence`, `word`, or
|
|
8
|
+
* `grapheme` boundary, or `none` to keep the block whole and move it to the next
|
|
9
|
+
* page intact. Use the constant (`SplitGranularity.None`) or the plain string
|
|
10
|
+
* (`'none'`); both are accepted.
|
|
11
|
+
*/
|
|
12
|
+
declare const SplitGranularity: {
|
|
13
|
+
readonly Sentence: "sentence";
|
|
14
|
+
readonly Word: "word";
|
|
15
|
+
readonly Grapheme: "grapheme";
|
|
16
|
+
readonly None: "none";
|
|
17
|
+
};
|
|
18
|
+
type SplitGranularity = (typeof SplitGranularity)[keyof typeof SplitGranularity];
|
|
19
|
+
/**
|
|
20
|
+
* The dot leader between a contents entry's title and its page number. The default,
|
|
21
|
+
* `dots`, draws it; `none` leaves the run between them blank. Use the constant
|
|
22
|
+
* (`TocLeader.None`) or the plain string (`'none'`); both are accepted.
|
|
23
|
+
*/
|
|
24
|
+
declare const TocLeader: {
|
|
25
|
+
readonly Dots: "dots";
|
|
26
|
+
readonly None: "none";
|
|
27
|
+
};
|
|
28
|
+
type TocLeader = (typeof TocLeader)[keyof typeof TocLeader];
|
|
29
|
+
/** How a Layout or Flow decides where pages break: `auto` on overflow
|
|
30
|
+
* and at PageBreak markers, `manual` at PageBreak markers only. */
|
|
31
|
+
type PaginationStrategy = 'auto' | 'manual';
|
|
32
|
+
/**
|
|
33
|
+
* How the PDF embeds its fonts. Mirrors `FontMode` in `@format.dev/fonts`, which owns
|
|
34
|
+
* the canonical list and the default.
|
|
35
|
+
*/
|
|
36
|
+
type FontMode = 'fidelity' | 'compact';
|
|
37
|
+
/**
|
|
38
|
+
* A CSS `<counter-style>` name. The predefined styles autocomplete; any custom
|
|
39
|
+
* `@counter-style` name you define is accepted too.
|
|
40
|
+
*/
|
|
41
|
+
type CounterStyle = 'decimal' | 'decimal-leading-zero' | 'lower-roman' | 'upper-roman' | 'lower-alpha' | 'upper-alpha' | 'lower-latin' | 'upper-latin' | 'lower-greek' | (string & {});
|
|
42
|
+
//#endregion
|
|
43
|
+
//#region src/Document.d.ts
|
|
44
|
+
interface DocumentProps {
|
|
45
|
+
title: string;
|
|
46
|
+
subject?: string;
|
|
47
|
+
author?: string;
|
|
48
|
+
keywords?: string[];
|
|
49
|
+
/**
|
|
50
|
+
* How the PDF embeds its fonts — file size against rendering quality. Leave
|
|
51
|
+
* unset for most documents; set `'fidelity'` when exact text rendering
|
|
52
|
+
* matters more than file size.
|
|
53
|
+
*
|
|
54
|
+
* - Compact (the default) keeps files small: the fonts embed as subset CID
|
|
55
|
+
* instances, so the optical size is fixed and strokes can look slightly
|
|
56
|
+
* heavier in some viewers (for example macOS Preview).
|
|
57
|
+
* - Fidelity gives the best-looking output: text keeps its exact optical
|
|
58
|
+
* sizing and renders at the same weight in every PDF viewer. The cost is a
|
|
59
|
+
* larger file, since the fonts embed as Type 3.
|
|
60
|
+
*/
|
|
61
|
+
fonts?: FontMode;
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Props the Format runtime passes to a document entry function. The
|
|
65
|
+
* generic parameter is the shape of the active data variant.
|
|
66
|
+
*
|
|
67
|
+
* ```tsx
|
|
68
|
+
* import type { Invoice } from './types'
|
|
69
|
+
*
|
|
70
|
+
* export default function InvoiceDocument({ data }: RenderProps<Invoice>) {
|
|
71
|
+
* return <Document title={`Invoice #${data.id}`}>{/* ... *\/}</Document>
|
|
72
|
+
* }
|
|
73
|
+
* ```
|
|
74
|
+
*/
|
|
75
|
+
interface RenderProps<T = unknown> {
|
|
76
|
+
data: T;
|
|
77
|
+
}
|
|
78
|
+
declare function Document({
|
|
79
|
+
title,
|
|
80
|
+
subject,
|
|
81
|
+
author,
|
|
82
|
+
keywords,
|
|
83
|
+
fonts,
|
|
84
|
+
children
|
|
85
|
+
}: PropsWithChildren<DocumentProps>): react0.JSX.Element;
|
|
86
|
+
//#endregion
|
|
87
|
+
//#region src/Layout.d.ts
|
|
88
|
+
interface LayoutProps {
|
|
89
|
+
/** Design label, mirrored to each page as `data-layout-id` for CSS. Optional:
|
|
90
|
+
* when omitted, the engine generates one from the Layout's document position. */
|
|
91
|
+
id?: string;
|
|
92
|
+
width: number;
|
|
93
|
+
height: number;
|
|
94
|
+
paginationStrategy?: PaginationStrategy;
|
|
95
|
+
splitGranularity?: SplitGranularity;
|
|
96
|
+
}
|
|
97
|
+
declare function Layout({
|
|
98
|
+
id,
|
|
99
|
+
width,
|
|
100
|
+
height,
|
|
101
|
+
paginationStrategy,
|
|
102
|
+
splitGranularity,
|
|
103
|
+
children
|
|
104
|
+
}: PropsWithChildren<LayoutProps>): react0.JSX.Element;
|
|
105
|
+
//#endregion
|
|
106
|
+
//#region src/Flow.d.ts
|
|
107
|
+
interface FlowProps {
|
|
108
|
+
/** How content breaks when it doesn't fit the current page. When unset, it
|
|
109
|
+
* inherits from the enclosing Flow, then the Layout, then defaults to `none`. */
|
|
110
|
+
splitGranularity?: SplitGranularity;
|
|
111
|
+
/** Whether this Flow paginates on overflow (`auto`) or only at PageBreak
|
|
112
|
+
* markers (`manual`). Inherits the owning Layout's strategy when unset. */
|
|
113
|
+
paginationStrategy?: PaginationStrategy;
|
|
114
|
+
/** Opens a numbering scope of this counter name around the Flow's content, so
|
|
115
|
+
* a counter nested inside restarts per Flow instance (e.g. `1.1`, `1.2`). */
|
|
116
|
+
scope?: string;
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* A Flow is a region whose content paginates across pages. Everything inside the
|
|
120
|
+
* Flow that isn't its Stream is scaffolding that repeats on every page the
|
|
121
|
+
* content spans; the stream's items appear once and flow.
|
|
122
|
+
*
|
|
123
|
+
* Author the stream two ways:
|
|
124
|
+
*
|
|
125
|
+
* - **bare** — `<Flow>{items}</Flow>`: the Flow's own children are the stream,
|
|
126
|
+
* injected with no wrapper element.
|
|
127
|
+
* - **scaffolded** — wrap the stream in a `<Stream>` inside surrounding markup,
|
|
128
|
+
* e.g. `<Flow><table><thead/><Stream>{rows}</Stream><tfoot/></table></Flow>`:
|
|
129
|
+
* the table, thead, and tfoot repeat per page; the rows flow.
|
|
130
|
+
*
|
|
131
|
+
* Flows nest: a Flow placed inside another Flow's stream paginates against the
|
|
132
|
+
* nearest enclosing sealing region (a Frame, else the page), re-cloning its own
|
|
133
|
+
* scaffolding on each page its content reaches.
|
|
134
|
+
*/
|
|
135
|
+
declare function Flow({
|
|
136
|
+
splitGranularity,
|
|
137
|
+
paginationStrategy,
|
|
138
|
+
scope,
|
|
139
|
+
children
|
|
140
|
+
}: PropsWithChildren<FlowProps>): react0.JSX.Element;
|
|
141
|
+
//#endregion
|
|
142
|
+
//#region src/Stream.d.ts
|
|
143
|
+
/**
|
|
144
|
+
* A Stream marks where a scaffolded Flow's items land. Use it when a Flow wraps
|
|
145
|
+
* its content in repeating scaffolding (a table's header and footer, a titled
|
|
146
|
+
* panel) and you need to say where in that scaffolding the stream flows in:
|
|
147
|
+
*
|
|
148
|
+
* ```tsx
|
|
149
|
+
* <Flow>
|
|
150
|
+
* <table>
|
|
151
|
+
* <thead>…</thead>
|
|
152
|
+
* <Stream>{rows}</Stream>
|
|
153
|
+
* <tfoot>…</tfoot>
|
|
154
|
+
* </table>
|
|
155
|
+
* </Flow>
|
|
156
|
+
* ```
|
|
157
|
+
*
|
|
158
|
+
* Omit it for a bare Flow, where the Flow's own children are the stream.
|
|
159
|
+
*/
|
|
160
|
+
declare function Stream({
|
|
161
|
+
children
|
|
162
|
+
}: PropsWithChildren): react0.JSX.Element;
|
|
163
|
+
//#endregion
|
|
164
|
+
//#region src/PageBreak.d.ts
|
|
165
|
+
declare function PageBreak(): react0.JSX.Element;
|
|
166
|
+
//#endregion
|
|
167
|
+
//#region src/PageCounter.d.ts
|
|
168
|
+
interface PageCounterBaseProps extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
|
|
169
|
+
/**
|
|
170
|
+
* HTML tag to render. Defaults to `span`. Use `div` (or another block-level
|
|
171
|
+
* element) when the counter needs its own line.
|
|
172
|
+
*/
|
|
173
|
+
as?: ElementType;
|
|
174
|
+
/**
|
|
175
|
+
* CSS `<counter-style>` used to format the counter — e.g. `decimal`,
|
|
176
|
+
* `lower-roman`, `upper-alpha`, or a custom `@counter-style` name. Sets
|
|
177
|
+
* `--page-counter-style` inline; defaults to `decimal` from the base
|
|
178
|
+
* stylesheet when omitted.
|
|
179
|
+
*/
|
|
180
|
+
counterStyle?: CounterStyle;
|
|
181
|
+
}
|
|
182
|
+
//#endregion
|
|
183
|
+
//#region src/PageNumber.d.ts
|
|
184
|
+
type PageNumberProps = PageCounterBaseProps;
|
|
185
|
+
declare function PageNumber(props: PageNumberProps): react0.JSX.Element;
|
|
186
|
+
//#endregion
|
|
187
|
+
//#region src/PageCount.d.ts
|
|
188
|
+
type PageCountProps = PageCounterBaseProps;
|
|
189
|
+
declare function PageCount(props: PageCountProps): react0.JSX.Element;
|
|
190
|
+
//#endregion
|
|
191
|
+
//#region src/Counter.d.ts
|
|
192
|
+
interface CounterBase extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
|
|
193
|
+
/**
|
|
194
|
+
* The counter to read or advance. Counters are created on first use, so any
|
|
195
|
+
* name works — `figure`, `table`, `step`. The same name shares one running
|
|
196
|
+
* value across the whole document.
|
|
197
|
+
*/
|
|
198
|
+
name: string;
|
|
199
|
+
/**
|
|
200
|
+
* Read the current value without advancing it. Use this to refer back to a
|
|
201
|
+
* number you already showed, e.g. "see Figure <Counter name='figure' peek />".
|
|
202
|
+
*/
|
|
203
|
+
peek?: boolean;
|
|
204
|
+
/**
|
|
205
|
+
* Reset the counter to 0 at this point and render nothing — the start of a
|
|
206
|
+
* fresh run (a new chapter restarting its figures).
|
|
207
|
+
*/
|
|
208
|
+
reset?: boolean;
|
|
209
|
+
/**
|
|
210
|
+
* Join the whole nested chain of this counter with the given separator — the
|
|
211
|
+
* `counters()` read, for nested lists: `join="."` shows `1.2.1`. Without it,
|
|
212
|
+
* only the innermost value is shown.
|
|
213
|
+
*/
|
|
214
|
+
join?: string;
|
|
215
|
+
/**
|
|
216
|
+
* HTML tag to render. Defaults to `span`.
|
|
217
|
+
*/
|
|
218
|
+
as?: ElementType;
|
|
219
|
+
/**
|
|
220
|
+
* CSS `<counter-style>` used to format the value — e.g. `decimal`,
|
|
221
|
+
* `lower-roman`, `upper-alpha`. Defaults to `decimal`.
|
|
222
|
+
*/
|
|
223
|
+
counterStyle?: CounterStyle;
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* `set` and `by` are mutually exclusive: `set` jumps to an exact value, `by`
|
|
227
|
+
* advances. Passing both is a contradiction the type rejects.
|
|
228
|
+
*/
|
|
229
|
+
type CounterProps = CounterBase & ({
|
|
230
|
+
set?: undefined;
|
|
231
|
+
/** How much to advance by before showing the value. Defaults to 1. */
|
|
232
|
+
by?: number;
|
|
233
|
+
} | {
|
|
234
|
+
/** Set the counter to an exact value and show it. */
|
|
235
|
+
set: number;
|
|
236
|
+
by?: undefined;
|
|
237
|
+
});
|
|
238
|
+
/**
|
|
239
|
+
* A counter whose value survives pagination. Unlike a CSS counter, which resets
|
|
240
|
+
* on every page, this is resolved by Format before pages are split, so the
|
|
241
|
+
* number stays correct wherever the content lands.
|
|
242
|
+
*
|
|
243
|
+
* By default it advances the counter and shows the new value — the usual "this
|
|
244
|
+
* is Figure N" case. `peek` reads without advancing, `set` jumps to a value, and
|
|
245
|
+
* `reset` starts the count over. These three are mutually exclusive; when more
|
|
246
|
+
* than one is set, `reset` wins, then `set`, then `peek`. `by` applies only to
|
|
247
|
+
* the default advance.
|
|
248
|
+
*
|
|
249
|
+
* Give the counter an `id` to make it referenceable. A `<Ref to="that-id" />`
|
|
250
|
+
* then prints the exact value this counter showed, and `<Ref to="that-id" page />`
|
|
251
|
+
* the page it landed on — the same way a heading's id yields its section number.
|
|
252
|
+
*/
|
|
253
|
+
declare function Counter({
|
|
254
|
+
name,
|
|
255
|
+
peek,
|
|
256
|
+
reset,
|
|
257
|
+
set,
|
|
258
|
+
by,
|
|
259
|
+
join,
|
|
260
|
+
as: Tag,
|
|
261
|
+
counterStyle,
|
|
262
|
+
...rest
|
|
263
|
+
}: CounterProps): react0.JSX.Element;
|
|
264
|
+
//#endregion
|
|
265
|
+
//#region src/Numbering.d.ts
|
|
266
|
+
interface NumberingRuleBase {
|
|
267
|
+
/**
|
|
268
|
+
* CSS selector for the elements this rule numbers, e.g. `h2`, `figure figcaption`,
|
|
269
|
+
* `.step`. Every match advances the counter in document order.
|
|
270
|
+
*/
|
|
271
|
+
match: string;
|
|
272
|
+
/**
|
|
273
|
+
* The counter this rule advances. Defaults to the selector, so a single-tag
|
|
274
|
+
* rule needs no separate name.
|
|
275
|
+
*/
|
|
276
|
+
counter?: string;
|
|
277
|
+
/**
|
|
278
|
+
* The text inserted into each match, with `{counter}` placeholders. For
|
|
279
|
+
* example `Figure {figure}: ` or `{chapter:upper-roman}. `. A placeholder may
|
|
280
|
+
* carry its own style after a colon. When omitted, the rule advances the
|
|
281
|
+
* counter but inserts nothing — pair it with a <Counter> read.
|
|
282
|
+
*/
|
|
283
|
+
format?: string;
|
|
284
|
+
/**
|
|
285
|
+
* Default `<counter-style>` for placeholders in `format`. Defaults to `decimal`.
|
|
286
|
+
*/
|
|
287
|
+
counterStyle?: CounterStyle;
|
|
288
|
+
/**
|
|
289
|
+
* Where the formatted number goes relative to the matched element:
|
|
290
|
+
* `before` its content (the default), `after` it, or `none` to only keep the
|
|
291
|
+
* counter running. To restart a counter under another, declare it with
|
|
292
|
+
* `<CounterDef resetEach>`; to nest a counter, mark the container `data-scope`.
|
|
293
|
+
*/
|
|
294
|
+
insert?: 'before' | 'after' | 'none';
|
|
295
|
+
}
|
|
296
|
+
/**
|
|
297
|
+
* `set` and `increment` are mutually exclusive: `set` forces an exact value on
|
|
298
|
+
* each match, `increment` advances. Passing both is a contradiction the type
|
|
299
|
+
* rejects.
|
|
300
|
+
*/
|
|
301
|
+
type NumberingRuleProps = NumberingRuleBase & ({
|
|
302
|
+
set?: undefined;
|
|
303
|
+
/**
|
|
304
|
+
* How much to advance the counter on each match. Defaults to 1. Set to `0` when a
|
|
305
|
+
* rule should not advance a counter of its own, e.g. a rule whose only job is to
|
|
306
|
+
* reset another counter (a nested-list rule that opens a fresh scope for the
|
|
307
|
+
* counter you read).
|
|
308
|
+
*/
|
|
309
|
+
increment?: number;
|
|
310
|
+
} | {
|
|
311
|
+
/** Set the counter to this exact value on each match instead of advancing it. */
|
|
312
|
+
set: number;
|
|
313
|
+
increment?: undefined;
|
|
314
|
+
});
|
|
315
|
+
interface NumberingProps {
|
|
316
|
+
/**
|
|
317
|
+
* The default counter style for every counter the document numbers. Per-rule,
|
|
318
|
+
* per-Counter, and per-Footnotes styles override it. Defaults to `decimal`.
|
|
319
|
+
*/
|
|
320
|
+
counterStyle?: CounterStyle;
|
|
321
|
+
}
|
|
322
|
+
/**
|
|
323
|
+
* Turns on document-wide numbering. With no children it numbers headings `h1`
|
|
324
|
+
* through `h6` hierarchically — `1`, `1.1`, `1.1.1` — with each level resetting
|
|
325
|
+
* the ones beneath it. Add <NumberingRule> children to number other things or
|
|
326
|
+
* change the format.
|
|
327
|
+
*
|
|
328
|
+
* Numbers are resolved before pages are split, so they stay correct across page
|
|
329
|
+
* breaks where plain CSS counters would reset.
|
|
330
|
+
*
|
|
331
|
+
* ```tsx
|
|
332
|
+
* <Document title="Report">
|
|
333
|
+
* <Numbering />
|
|
334
|
+
* ...
|
|
335
|
+
* </Document>
|
|
336
|
+
* ```
|
|
337
|
+
*/
|
|
338
|
+
declare function Numbering({
|
|
339
|
+
counterStyle,
|
|
340
|
+
children
|
|
341
|
+
}: PropsWithChildren<NumberingProps>): react0.JSX.Element;
|
|
342
|
+
/**
|
|
343
|
+
* One numbering rule, used as `<NumberingRule>` inside `<Numbering>`. Each rule
|
|
344
|
+
* matches a selector and advances (and optionally inserts) a counter. Add rules
|
|
345
|
+
* to number things beyond the default headings, or to change the heading format.
|
|
346
|
+
*/
|
|
347
|
+
declare function NumberingRule({
|
|
348
|
+
match,
|
|
349
|
+
counter,
|
|
350
|
+
format,
|
|
351
|
+
increment,
|
|
352
|
+
set,
|
|
353
|
+
counterStyle,
|
|
354
|
+
insert
|
|
355
|
+
}: NumberingRuleProps): react0.JSX.Element;
|
|
356
|
+
interface CounterDefProps {
|
|
357
|
+
/** The counter this defines. Shared by name across the document. */
|
|
358
|
+
name: string;
|
|
359
|
+
/**
|
|
360
|
+
* The counter this one restarts under, if any: whenever that owner advances, this
|
|
361
|
+
* counter returns to 0. A `figure` set to restart under `chapter` reads "Figure 2.1".
|
|
362
|
+
* The restart cascades, so a new chapter zeros section and, under section, figure.
|
|
363
|
+
*/
|
|
364
|
+
resetEach?: string;
|
|
365
|
+
}
|
|
366
|
+
/**
|
|
367
|
+
* Declares one counter's behaviour, used as `<CounterDef>` inside `<Numbering>`. Name
|
|
368
|
+
* the counter and, optionally, the owner counter it restarts under. A counter with an
|
|
369
|
+
* owner returns to 0 every time the owner's value changes; one with no owner restarts
|
|
370
|
+
* only when you reset or set it yourself.
|
|
371
|
+
*
|
|
372
|
+
* ```tsx
|
|
373
|
+
* <Numbering>
|
|
374
|
+
* <CounterDef name="figure" resetEach="chapter" />
|
|
375
|
+
* <NumberingRule match="figcaption" counter="figure" format="Figure {chapter}.{figure}: " />
|
|
376
|
+
* </Numbering>
|
|
377
|
+
* ```
|
|
378
|
+
*/
|
|
379
|
+
declare function CounterDef({
|
|
380
|
+
name,
|
|
381
|
+
resetEach
|
|
382
|
+
}: CounterDefProps): react0.JSX.Element;
|
|
383
|
+
//#endregion
|
|
384
|
+
//#region src/Scope.d.ts
|
|
385
|
+
interface ScopeProps {
|
|
386
|
+
/**
|
|
387
|
+
* The counter to open a fresh nested instance for across this wrapper's content — a
|
|
388
|
+
* level of a nested list. Pass several space-separated to scope more than one. A
|
|
389
|
+
* `<Counter join>` inside reads the whole open stack.
|
|
390
|
+
*/
|
|
391
|
+
counter: string;
|
|
392
|
+
}
|
|
393
|
+
/**
|
|
394
|
+
* Opens a counter scope around its children and adds no element to the output: a
|
|
395
|
+
* `<Scope>` is the fallback for nesting content that has no element of its own to carry
|
|
396
|
+
* the scope. When the content already sits in a container or a `<Flow>`, mark that
|
|
397
|
+
* directly (`<ol data-scope="item">`, `<Flow scope="item">`) instead of wrapping.
|
|
398
|
+
*
|
|
399
|
+
* ```tsx
|
|
400
|
+
* <Scope counter="item">
|
|
401
|
+
* <Counter name="item" join="." /> First
|
|
402
|
+
* <Scope counter="item">
|
|
403
|
+
* <Counter name="item" join="." /> Nested
|
|
404
|
+
* </Scope>
|
|
405
|
+
* </Scope>
|
|
406
|
+
* ```
|
|
407
|
+
*/
|
|
408
|
+
declare function Scope({
|
|
409
|
+
counter,
|
|
410
|
+
children
|
|
411
|
+
}: PropsWithChildren<ScopeProps>): react0.JSX.Element;
|
|
412
|
+
//#endregion
|
|
413
|
+
//#region src/Ref.d.ts
|
|
414
|
+
interface RefProps extends Omit<HTMLAttributes<HTMLElement>, 'children'> {
|
|
415
|
+
/**
|
|
416
|
+
* The `id` to point at. Put an id on a heading to reference its section number,
|
|
417
|
+
* or on a `<Counter>` to reference the value that counter printed. The target
|
|
418
|
+
* can appear anywhere in the document, before or after this reference.
|
|
419
|
+
*/
|
|
420
|
+
to: string;
|
|
421
|
+
/**
|
|
422
|
+
* Read a named counter's value as it stood at the target, e.g. `counter="figure"`
|
|
423
|
+
* for the figure count at that point in the document. Omit it to show the
|
|
424
|
+
* target's own number — a heading's section number, or the value a
|
|
425
|
+
* `<Counter id="…">` printed.
|
|
426
|
+
*/
|
|
427
|
+
counter?: string;
|
|
428
|
+
/**
|
|
429
|
+
* Show the page the target landed on, e.g. "see page 12". Resolved after
|
|
430
|
+
* pagination. Takes precedence over `counter`.
|
|
431
|
+
*/
|
|
432
|
+
page?: boolean;
|
|
433
|
+
/**
|
|
434
|
+
* HTML tag to render. Defaults to `span`.
|
|
435
|
+
*/
|
|
436
|
+
as?: ElementType;
|
|
437
|
+
/**
|
|
438
|
+
* CSS `<counter-style>` used to format the value. Defaults to `decimal`.
|
|
439
|
+
*/
|
|
440
|
+
counterStyle?: CounterStyle;
|
|
441
|
+
}
|
|
442
|
+
/**
|
|
443
|
+
* A cross-reference to a numbered element — "see Section 2.1" or "Figure 3".
|
|
444
|
+
* Point it at an `id`: a heading's id yields its section number, a `<Counter>`'s
|
|
445
|
+
* id yields the value that counter printed. Add `page` for the page the target
|
|
446
|
+
* landed on, or `counter` to read a named counter's running value at the target.
|
|
447
|
+
*
|
|
448
|
+
* References resolve before pages are split and can point forward to an element
|
|
449
|
+
* that appears later in the document.
|
|
450
|
+
*
|
|
451
|
+
* ```tsx
|
|
452
|
+
* <figcaption>Figure <Counter name="figure" id="flow" />: the data flow</figcaption>
|
|
453
|
+
* // ...anywhere else in the document:
|
|
454
|
+
* <p>The method (see Section <Ref to="method" />) reads Figure <Ref to="flow" />,
|
|
455
|
+
* shown in full on page <Ref to="flow" page />.</p>
|
|
456
|
+
* ```
|
|
457
|
+
*/
|
|
458
|
+
declare function Ref({
|
|
459
|
+
to,
|
|
460
|
+
counter,
|
|
461
|
+
page,
|
|
462
|
+
as: Tag,
|
|
463
|
+
counterStyle,
|
|
464
|
+
...rest
|
|
465
|
+
}: RefProps): react0.JSX.Element;
|
|
466
|
+
//#endregion
|
|
467
|
+
//#region src/TableOfContents.d.ts
|
|
468
|
+
interface TableOfContentsProps {
|
|
469
|
+
/**
|
|
470
|
+
* CSS selector for the headings to list. Defaults to `h1, h2, h3`.
|
|
471
|
+
*/
|
|
472
|
+
collect?: string;
|
|
473
|
+
/**
|
|
474
|
+
* The dot leader between each entry's title and its page number. The default,
|
|
475
|
+
* `dots`, draws it; `none` leaves the run between them blank.
|
|
476
|
+
*/
|
|
477
|
+
leader?: TocLeader;
|
|
478
|
+
/**
|
|
479
|
+
* Repeat the leading content with the nav on every page the contents spans, like a
|
|
480
|
+
* running header. Off by default: the leading content shows once, above the entries.
|
|
481
|
+
*/
|
|
482
|
+
repeatHead?: boolean;
|
|
483
|
+
/**
|
|
484
|
+
* Leading content rendered at the top of the contents, above the entries — a
|
|
485
|
+
* "Contents" heading, an intro line, a rule. Shown once by default; set `repeatHead`
|
|
486
|
+
* to repeat it with the nav on every page the contents spans.
|
|
487
|
+
*/
|
|
488
|
+
children?: ReactNode;
|
|
489
|
+
/**
|
|
490
|
+
* A class on the rendered `<nav>`. Style the contents with your own CSS, or use
|
|
491
|
+
* `styled(TableOfContents)`.
|
|
492
|
+
*/
|
|
493
|
+
className?: string;
|
|
494
|
+
/** An inline style on the rendered `<nav>`. */
|
|
495
|
+
style?: CSSProperties;
|
|
496
|
+
}
|
|
497
|
+
/**
|
|
498
|
+
* A table of contents. Format fills it after laying out the document: one entry
|
|
499
|
+
* per heading the `collect` selector matches, each with the heading's number, its
|
|
500
|
+
* title, and the page it landed on.
|
|
501
|
+
*
|
|
502
|
+
* The entries are flat anchors in a `<div data-type="toc-entries">` inside a
|
|
503
|
+
* `<nav data-type="toc">`: each is an `<a data-type="toc-entry" data-depth="N">`
|
|
504
|
+
* (depth 0 at the top of the outline) holding `toc-number`, `toc-title`, and
|
|
505
|
+
* `toc-page` spans. Depth is data, not nesting, so the stylesheet indents and sizes
|
|
506
|
+
* by depth and a long contents paginates by breaking between anchors. Style it through
|
|
507
|
+
* the `data-type` hooks and the `--toc-*` custom properties (root size, per-depth size
|
|
508
|
+
* and indent, page-number size, leader, and vertical rhythm), or set a `className` (or
|
|
509
|
+
* `styled(TableOfContents)`) on the nav. Set `leader="none"` to omit the dot leader
|
|
510
|
+
* entirely, so no leader is drawn between a title and its page number.
|
|
511
|
+
*
|
|
512
|
+
* Children are leading content shown above the entries — put a "Contents" heading there.
|
|
513
|
+
* It shows once by default; set `repeatHead` to repeat it with the nav on every page.
|
|
514
|
+
*
|
|
515
|
+
* Give a collected heading a `data-toc-description` and its entry gains a
|
|
516
|
+
* `toc-description` line under the title (a one-line summary, as on a magazine or
|
|
517
|
+
* report contents):
|
|
518
|
+
*
|
|
519
|
+
* ```tsx
|
|
520
|
+
* <TableOfContents collect="h1, h2">
|
|
521
|
+
* <h2>Contents</h2>
|
|
522
|
+
* </TableOfContents>
|
|
523
|
+
*
|
|
524
|
+
* <h1 data-toc-description="Defining the studio's personality and direction.">
|
|
525
|
+
* Visual Positioning
|
|
526
|
+
* </h1>
|
|
527
|
+
* ```
|
|
528
|
+
*/
|
|
529
|
+
declare function TableOfContents({
|
|
530
|
+
collect,
|
|
531
|
+
leader,
|
|
532
|
+
repeatHead,
|
|
533
|
+
className,
|
|
534
|
+
style,
|
|
535
|
+
children
|
|
536
|
+
}: TableOfContentsProps): react0.JSX.Element;
|
|
537
|
+
//#endregion
|
|
538
|
+
//#region src/Footnote.d.ts
|
|
539
|
+
/**
|
|
540
|
+
* A footnote. Write the note's text as the children, at the point it's
|
|
541
|
+
* referenced; Format leaves a numbered marker inline and moves the text to the
|
|
542
|
+
* footer of whichever page the marker lands on. Footnotes are numbered
|
|
543
|
+
* continuously through the document.
|
|
544
|
+
*
|
|
545
|
+
* Pair it with a `<Footnotes />` region in the Layout to control where the notes
|
|
546
|
+
* sit; without one, Format adds a footer area to each page that needs it.
|
|
547
|
+
*
|
|
548
|
+
* ```tsx
|
|
549
|
+
* <p>The result holds<Footnote>under the stated assumptions</Footnote>.</p>
|
|
550
|
+
* ```
|
|
551
|
+
*/
|
|
552
|
+
declare function Footnote({
|
|
553
|
+
children
|
|
554
|
+
}: PropsWithChildren): react0.JSX.Element;
|
|
555
|
+
//#endregion
|
|
556
|
+
//#region src/Footnotes.d.ts
|
|
557
|
+
interface FootnotesProps {
|
|
558
|
+
/**
|
|
559
|
+
* The counter style for the note numbers and their inline markers. Defaults to
|
|
560
|
+
* the document's numbering style, or `decimal`.
|
|
561
|
+
*/
|
|
562
|
+
counterStyle?: CounterStyle;
|
|
563
|
+
/**
|
|
564
|
+
* Restart the numbering on each page, so every page's footer reads 1, 2, 3 rather
|
|
565
|
+
* than a count that runs the whole document. For a per-page footer in a Layout; the
|
|
566
|
+
* inline markers renumber to match. Off by default (continuous numbering).
|
|
567
|
+
*/
|
|
568
|
+
restartEachPage?: boolean;
|
|
569
|
+
/**
|
|
570
|
+
* Whether the leading content (a heading, a rule) repeats in every page's footer. On by
|
|
571
|
+
* default for a per-page Layout footer; an inline endnotes block shows it once. Set `false`
|
|
572
|
+
* to show a Layout footer's head on its first page only.
|
|
573
|
+
*/
|
|
574
|
+
repeatHead?: boolean;
|
|
575
|
+
/** A class name passed through to the wrapping footnotes container. */
|
|
576
|
+
className?: string;
|
|
577
|
+
/** An inline style passed through to the wrapping footnotes container. */
|
|
578
|
+
style?: CSSProperties;
|
|
579
|
+
}
|
|
580
|
+
/**
|
|
581
|
+
* The region that collects a page's footnotes, authored as a `<template>` Format
|
|
582
|
+
* fills. In a Layout it is a per-page footer gathering the notes whose markers
|
|
583
|
+
* landed there; in a flow's content it is an endnotes list. Format renders it as an
|
|
584
|
+
* `<aside data-type="footnotes">` holding a `<dl data-type="footnote-entries">`, where
|
|
585
|
+
* each note is a `<dt data-type="footnote-number">` term and a
|
|
586
|
+
* `<dd data-type="footnote-content">` definition; style the list as a grid with your
|
|
587
|
+
* own CSS.
|
|
588
|
+
*
|
|
589
|
+
* Put a heading or rule inside `<Footnotes>` to render it above the generated list,
|
|
590
|
+
* the way a table of contents renders its leading content above the entries:
|
|
591
|
+
*
|
|
592
|
+
* ```tsx
|
|
593
|
+
* <Footnotes>
|
|
594
|
+
* <h4>Notes</h4>
|
|
595
|
+
* </Footnotes>
|
|
596
|
+
* ```
|
|
597
|
+
*
|
|
598
|
+
* Omit it and Format adds a plain footer to each page that has footnotes.
|
|
599
|
+
*/
|
|
600
|
+
declare function Footnotes({
|
|
601
|
+
counterStyle,
|
|
602
|
+
restartEachPage,
|
|
603
|
+
repeatHead,
|
|
604
|
+
className,
|
|
605
|
+
style,
|
|
606
|
+
children
|
|
607
|
+
}: PropsWithChildren<FootnotesProps>): react0.JSX.Element;
|
|
608
|
+
//#endregion
|
|
609
|
+
//#region src/utils.d.ts
|
|
610
|
+
/**
|
|
611
|
+
* Tagged template for authoring CSS, typically inside a `<style>` element.
|
|
612
|
+
* Returns the string from the raw segments, so CSS escapes (`\2014`,
|
|
613
|
+
* icon-font codepoints, escaped selectors) survive intact. Interpolated
|
|
614
|
+
* `null`, `undefined`, and `false` collapse to an empty string for clean
|
|
615
|
+
* conditional rules. The `css` name also lets editors and the Format docs
|
|
616
|
+
* highlighter treat the contents as CSS.
|
|
617
|
+
*/
|
|
618
|
+
declare function css(parts: TemplateStringsArray, ...vals: unknown[]): string;
|
|
619
|
+
//#endregion
|
|
620
|
+
export { Counter, CounterDef, type CounterDefProps, type CounterProps, type CounterStyle, Document, type DocumentProps, Flow, type FlowProps, type FontMode, Footnote, Footnotes, type FootnotesProps, Layout, type LayoutProps, Numbering, type NumberingProps, NumberingRule, type NumberingRuleProps, PageBreak, PageCount, type PageCountProps, PageNumber, type PageNumberProps, type PaginationStrategy, Ref, type RefProps, type RenderProps, Scope, type ScopeProps, SplitGranularity, Stream, TableOfContents, type TableOfContentsProps, TocLeader, css };
|
|
621
|
+
//# sourceMappingURL=index.d.cts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types.ts","../src/Document.tsx","../src/Layout.tsx","../src/Flow.tsx","../src/Stream.tsx","../src/PageBreak.tsx","../src/PageCounter.tsx","../src/PageNumber.tsx","../src/PageCount.tsx","../src/Counter.tsx","../src/Numbering.tsx","../src/Scope.tsx","../src/Ref.tsx","../src/TableOfContents.tsx","../src/Footnote.tsx","../src/Footnotes.tsx","../src/utils.ts"],"sourcesContent":[],"mappings":"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"}
|