@thomasfosterau/components 0.0.0-stage → 0.1.0

package/dist/citations/ISSNLink.svelte.d.ts

@@ -0,0 +1,19 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAnchorAttributes } from 'svelte/elements';
+interface Props extends Omit<HTMLAnchorAttributes, 'children'> {
+    /** The ISSN, without a prefix. */
+    issn: string;
+    /**
+     * Schema.org `itemprop` on the link, when the identifier is a property of an enclosing item.
+     */
+    itemprop?: string | undefined;
+    /**
+     * Replaces the link text.
+     * @defaultValue the bare ISSN
+     */
+    children?: Snippet<[]> | undefined;
+}
+/** An ISSN rendered as a WorldCat lookup link that opens in a new tab. */
+declare const ISSNLink: import("svelte").Component<Props, {}, "">;
+type ISSNLink = ReturnType<typeof ISSNLink>;
+export default ISSNLink;

package/dist/citations/Publisher.svelte

@@ -0,0 +1,34 @@
+<!-- @component
+A publisher or awarding institution as Schema.org microdata: "Oxford, Oxfordshire, UK: Oxford University Press".
+-->
+<!--
+  Publisher — a publisher (or awarding institution) as Schema.org microdata:
+  "Oxford, Oxfordshire, UK: Oxford University Press". The place is a
+  `PostalAddress` of whichever of locality / region / country are present,
+  and is omitted, colon included, when none are.
+
+  Microdata, not ARIA: the name is plain text; the structure is for machines.
+  `itemprop` defaults to `publisher` and is a prop so a thesis can credit its
+  awarding institution as `sourceOrganization`.
+-->
+<script lang="ts">let { publisher, itemprop = "publisher" } = $props();
+const placeParts = $derived([
+	["addressLocality", publisher.address?.locality],
+	["addressRegion", publisher.address?.region],
+	["addressCountry", publisher.address?.country]
+].flatMap(([prop, value]) => value === undefined || value === "" ? [] : [{
+	prop,
+	value
+}]));
+export {};
+</script>
+
+<span {itemprop} itemscope itemtype={`https://schema.org/${publisher.itemtype ?? 'Organization'}`}>
+  {#if placeParts.length > 0}
+    <span itemprop="location" itemscope itemtype="https://schema.org/PostalAddress"
+      >{#each placeParts as { prop, value }, index (prop)}<span itemprop={prop}>{value}</span
+        >{#if index < placeParts.length - 1},{' '}{/if}{/each}</span
+    >:
+  {/if}
+  <span itemprop="name">{publisher.name}</span>
+</span>

package/dist/citations/Publisher.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { PublisherRecord } from './csl.ts';
+interface Props {
+    /** The publisher to render; its place is omitted when it has none. */
+    publisher: PublisherRecord;
+    /**
+     * Schema.org `itemprop` on the root.
+     * @defaultValue `'publisher'`
+     */
+    itemprop?: string | undefined;
+}
+/** A publisher or awarding institution as Schema.org microdata: "Oxford, Oxfordshire, UK: Oxford University Press". */
+declare const Publisher: import("svelte").Component<Props, {}, "">;
+type Publisher = ReturnType<typeof Publisher>;
+export default Publisher;

package/dist/citations/ReferenceList.svelte

@@ -0,0 +1,53 @@
+<!-- @component
+The numbered bibliography a page’s `<Citation>` markers accumulated, in citation order.
+-->
+<!--
+  ReferenceList — the numbered bibliography a page's `<Citation>` markers
+  accumulated, rendered in citation order.
+
+  Formatting happens once, in a single `$derived` over the whole list, rather
+  than per-entry inside the template on every reactive change — and pulling
+  it into `formatCitation` (`./citation.ts`) is what makes the style testable
+  besides.
+
+  There is no "alphabetical" style: sorting a numbered style alphabetically
+  breaks the `[n]` markers already printed in the prose, so that would need to
+  be a different style entirely, not a display toggle on this one.
+-->
+<script lang="ts">import { getBibliographyContext } from "./bibliography.svelte.js";
+import { formatCitation } from "./citation.js";
+let { title = "References", showTitle = true, headingLevel = 2 } = $props();
+const manager = getBibliographyContext();
+// One pass over the whole list, recomputed only when the list changes.
+const entries = $derived(manager.citations().map((entry) => ({
+	id: entry.citation.id,
+	order: entry.order,
+	text: formatCitation(entry.citation),
+	url: entry.citation.url
+})));
+const Heading = $derived(`h${headingLevel}`);
+</script>
+
+{#if entries.length > 0}
+  <section class="mt-8 space-y-3">
+    {#if showTitle}
+      <svelte:element this={Heading} class="text-xl font-semibold">{title}</svelte:element>
+    {/if}
+
+    <ol class="space-y-2 text-sm">
+      {#each entries as entry (entry.id)}
+        <li id="ref-{entry.id}" class="text-base-content/80 flex gap-2 leading-relaxed">
+          <span class="text-base-content/60 shrink-0 font-medium">[{entry.order}]</span>
+          <span>
+            {entry.text}
+            {#if entry.url}
+              <a class="link link-hover" href={entry.url} rel="noreferrer nofollow" target="_blank">
+                {entry.url}
+              </a>
+            {/if}
+          </span>
+        </li>
+      {/each}
+    </ol>
+  </section>
+{/if}

package/dist/citations/ReferenceList.svelte.d.ts

@@ -0,0 +1,21 @@
+interface Props {
+    /**
+     * Heading text.
+     * @defaultValue `'References'`
+     */
+    title?: string | undefined;
+    /**
+     * Render the heading. Off when the page supplies its own.
+     * @defaultValue `true`
+     */
+    showTitle?: boolean | undefined;
+    /**
+     * Heading level, for a page whose outline this list sits deeper in.
+     * @defaultValue `2`
+     */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6 | undefined;
+}
+/** The numbered bibliography a page’s `<Citation>` markers accumulated, in citation order. */
+declare const ReferenceList: import("svelte").Component<Props, {}, "">;
+type ReferenceList = ReturnType<typeof ReferenceList>;
+export default ReferenceList;

package/dist/citations/ReportCitation.svelte

@@ -0,0 +1,41 @@
+<!-- @component
+A report as "Authors, <cite>Title</cite> (2021) Canberra: Department of X pp 88", with Schema.org `Report` microdata.
+-->
+<!--
+  ReportCitation — a report as "Authors, <cite>Title</cite> (2021) Canberra:
+  Department of X pp 88", with Schema.org Report microdata. Same shape as
+  `BookCitation` without edition, series or ISBN; a report's author and
+  publisher are usually the same Organization.
+
+  The record type is local — see `./csl.ts`. Every string is a prop with an
+  English default.
+-->
+<script lang="ts">import Year from "../formatting/Year.svelte";
+import CreditList from "./CreditList.svelte";
+import Publisher from "./Publisher.svelte";
+let { report, itemid, untitledLabel = "Untitled report", noDateLabel = "no date", pageCountLabel = "pp", availableOnlineLabel = "available online at", locales } = $props();
+const authors = $derived(report.authors ?? []);
+</script>
+
+<span itemscope {itemid} itemtype="https://schema.org/Report">
+  {#if authors.length > 0}
+    <CreditList credits={authors} role="author" {locales} />,
+  {/if}
+  <cite itemprop="name">{report.title ?? untitledLabel}</cite>
+  <CreditList credits={report.editors ?? []} role="editor" {locales} />
+  <CreditList credits={report.translators ?? []} role="translator" {locales} />
+  ({#if report.datePublished !== undefined}<Year
+      value={report.datePublished}
+      itemprop="datePublished"
+      {locales}
+    />{:else}{noDateLabel}{/if})
+  {#if report.publisher !== undefined}
+    <Publisher publisher={report.publisher} />
+  {/if}
+  {#if report.numberOfPages !== undefined}
+    {pageCountLabel} <span itemprop="numberOfPages">{report.numberOfPages}</span>
+  {/if}
+  {#if report.url !== undefined}
+    {availableOnlineLabel} <a itemprop="url" href={report.url}>{report.url}</a>
+  {/if}
+</span>

package/dist/citations/ReportCitation.svelte.d.ts

@@ -0,0 +1,36 @@
+import type { ReportRecord } from './csl.ts';
+interface Props {
+    /** The report record; absent fields are left out of the rendering. */
+    report: ReportRecord;
+    /** Schema.org `itemid` on the root. */
+    itemid?: string | undefined;
+    /**
+     * Rendered in place of a missing title.
+     * @defaultValue `'Untitled report'`
+     */
+    untitledLabel?: string | undefined;
+    /**
+     * Rendered in place of a missing date.
+     * @defaultValue `'no date'`
+     */
+    noDateLabel?: string | undefined;
+    /**
+     * Abbreviation after a page count.
+     * @defaultValue `'pp'`
+     */
+    pageCountLabel?: string | undefined;
+    /**
+     * Lead-in before the record’s URL.
+     * @defaultValue `'available online at'`
+     */
+    availableOnlineLabel?: string | undefined;
+    /**
+     * Locale(s) for the joined name lists.
+     * @defaultValue the components context's `locale()`
+     */
+    locales?: string | readonly string[] | undefined;
+}
+/** A report as "Authors, <cite>Title</cite> (2021) Canberra: Department of X pp 88", with Schema.org `Report` microdata. */
+declare const ReportCitation: import("svelte").Component<Props, {}, "">;
+type ReportCitation = ReturnType<typeof ReportCitation>;
+export default ReportCitation;

package/dist/citations/ScholarlyArticleCitation.svelte

@@ -0,0 +1,64 @@
+<!-- @component
+A journal article as "Authors, ‘Title’ (2019) <cite>Periodical</cite> 12 (3) pp 45–67", with the Schema.org article → issue → volume → periodical chain as microdata.
+-->
+<!--
+  ScholarlyArticleCitation — a journal article as "Authors, 'Title' (2019)
+  <cite>Periodical</cite> 12 (3) pp 45–67 doi ISSN", with the Schema.org
+  ScholarlyArticle → PublicationIssue → PublicationVolume → Periodical chain
+  as nested `isPartOf` microdata.
+
+  The record type is local — see `./csl.ts`. Every string is a prop with an
+  English default.
+-->
+<script lang="ts">import Year from "../formatting/Year.svelte";
+import CreditList from "./CreditList.svelte";
+import DOILink from "./DOILink.svelte";
+import ISSNLink from "./ISSNLink.svelte";
+let { article, itemid, untitledLabel = "Untitled article", noDateLabel = "no date", pageLabel = "p", pagesLabel = "pp", availableOnlineLabel = "available online at", locales } = $props();
+const authors = $derived(article.authors ?? []);
+</script>
+
+<span itemscope {itemid} itemtype="https://schema.org/ScholarlyArticle">
+  {#if authors.length > 0}
+    <CreditList credits={authors} role="author" {locales} />,
+  {/if}
+  '<cite class="not-italic" itemprop="headline name">{article.title ?? untitledLabel}</cite>'
+  ({#if article.datePublished !== undefined}<Year
+      value={article.datePublished}
+      itemprop="datePublished"
+      {locales}
+    />{:else}{noDateLabel}{/if})
+  {#if article.periodical !== undefined || article.volumeNumber !== undefined || article.issueNumber !== undefined}
+    <span itemprop="isPartOf" itemscope itemtype="https://schema.org/PublicationIssue">
+      <span itemprop="isPartOf" itemscope itemtype="https://schema.org/PublicationVolume">
+        {#if article.periodical?.title !== undefined}
+          <span itemprop="isPartOf" itemscope itemtype="https://schema.org/Periodical">
+            <cite class="italic" itemprop="name">{article.periodical.title}</cite>
+          </span>
+        {/if}
+        {#if article.volumeNumber !== undefined}
+          <span itemprop="volumeNumber">{article.volumeNumber}</span>
+        {/if}
+      </span>
+      {#if article.issueNumber !== undefined}
+        (<span itemprop="issueNumber">{article.issueNumber}</span>)
+      {/if}
+    </span>
+  {/if}
+  {#if article.pageStart !== undefined && article.pageEnd !== undefined}
+    {pagesLabel} <span itemprop="pageStart">{article.pageStart}</span>–<span itemprop="pageEnd"
+      >{article.pageEnd}</span
+    >
+  {:else if article.pageStart !== undefined}
+    {pageLabel} <span itemprop="pageStart">{article.pageStart}</span>
+  {/if}
+  {#if article.doi !== undefined}
+    <DOILink doi={article.doi} itemprop="identifier sameAs" />
+  {/if}
+  {#if article.periodical?.issn !== undefined}
+    <ISSNLink issn={article.periodical.issn} />
+  {/if}
+  {#if article.url !== undefined}
+    {availableOnlineLabel} <a itemprop="url" href={article.url}>{article.url}</a>
+  {/if}
+</span>

package/dist/citations/ScholarlyArticleCitation.svelte.d.ts

@@ -0,0 +1,41 @@
+import type { ScholarlyArticleRecord } from './csl.ts';
+interface Props {
+    /** The article record, with its periodical, volume and issue; absent fields are left out. */
+    article: ScholarlyArticleRecord;
+    /** Microdata `itemid` — the article's canonical URL. */
+    itemid?: string | undefined;
+    /**
+     * Rendered in place of a missing title.
+     * @defaultValue `'Untitled article'`
+     */
+    untitledLabel?: string | undefined;
+    /**
+     * Rendered in place of a missing date.
+     * @defaultValue `'no date'`
+     */
+    noDateLabel?: string | undefined;
+    /**
+     * Abbreviation before a single page.
+     * @defaultValue `'p'`
+     */
+    pageLabel?: string | undefined;
+    /**
+     * Abbreviation before a page range.
+     * @defaultValue `'pp'`
+     */
+    pagesLabel?: string | undefined;
+    /**
+     * Lead-in before the record’s URL.
+     * @defaultValue `'available online at'`
+     */
+    availableOnlineLabel?: string | undefined;
+    /**
+     * Locale(s) for the joined name lists.
+     * @defaultValue the components context's `locale()`
+     */
+    locales?: string | readonly string[] | undefined;
+}
+/** A journal article as "Authors, ‘Title’ (2019) <cite>Periodical</cite> 12 (3) pp 45–67", with the Schema.org article → issue → volume → periodical chain as microdata. */
+declare const ScholarlyArticleCitation: import("svelte").Component<Props, {}, "">;
+type ScholarlyArticleCitation = ReturnType<typeof ScholarlyArticleCitation>;
+export default ScholarlyArticleCitation;

package/dist/citations/ThesisCitation.svelte

@@ -0,0 +1,35 @@
+<!-- @component
+A thesis as "Author, <cite>Title</cite> (2019) PhD thesis, University of Sydney", with Schema.org `Thesis` microdata.
+-->
+<!--
+  ThesisCitation — a thesis as "Author, <cite>Title</cite> (2019) PhD thesis,
+  University of Sydney", with Schema.org Thesis microdata.
+
+  The record type is local — see `./csl.ts`. Every string is a prop with an
+  English default.
+-->
+<script lang="ts">import Year from "../formatting/Year.svelte";
+import CreditList from "./CreditList.svelte";
+import Publisher from "./Publisher.svelte";
+let { thesis, untitledLabel = "Untitled thesis", degreeLabel = (degree) => degree === undefined ? "thesis" : `${degree} thesis`, availableOnlineLabel = "available online at", locales } = $props();
+const authors = $derived(thesis.authors ?? []);
+</script>
+
+<span itemscope itemtype="https://schema.org/Thesis">
+  {#if authors.length > 0}
+    <CreditList credits={authors} role="author" {locales} />,
+  {/if}
+  <cite itemprop="name">{thesis.title ?? untitledLabel}</cite>
+  {#if thesis.datePublished !== undefined}
+    (<Year value={thesis.datePublished} itemprop="datePublished" {locales} />)
+  {/if}
+  {#if thesis.degree !== undefined || thesis.institution !== undefined}
+    <span itemprop="inSupportOf">{degreeLabel(thesis.degree)}</span
+    >{#if thesis.institution !== undefined},
+      <Publisher publisher={thesis.institution} itemprop="sourceOrganization" />
+    {/if}
+  {/if}
+  {#if thesis.url !== undefined}
+    {availableOnlineLabel} <a itemprop="url" href={thesis.url}>{thesis.url}</a>
+  {/if}
+</span>

package/dist/citations/ThesisCitation.svelte.d.ts

@@ -0,0 +1,29 @@
+import type { ThesisRecord } from "./csl.ts";
+interface Props {
+    /** The thesis record; absent fields are left out of the rendering. */
+    thesis: ThesisRecord;
+    /**
+     * Rendered in place of a missing title.
+     * @defaultValue `'Untitled thesis'`
+     */
+    untitledLabel?: string | undefined;
+    /**
+     * Degree → its label.
+     * @defaultValue `"<degree> thesis"`, or `"thesis"` without a degree
+     */
+    degreeLabel?: ((degree: string | undefined) => string) | undefined;
+    /**
+     * Lead-in before the record’s URL.
+     * @defaultValue `'available online at'`
+     */
+    availableOnlineLabel?: string | undefined;
+    /**
+     * Locale(s) for the joined name lists.
+     * @defaultValue the components context's `locale()`
+     */
+    locales?: string | readonly string[] | undefined;
+}
+/** A thesis as "Author, <cite>Title</cite> (2019) PhD thesis, University of Sydney", with Schema.org `Thesis` microdata. */
+declare const ThesisCitation: import("svelte").Component<Props, {}, "">;
+type ThesisCitation = ReturnType<typeof ThesisCitation>;
+export default ThesisCitation;

package/dist/citations/bibliography.svelte.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The bibliography context a page's citations and footnotes collect into.
+ *
+ * A `<Citation>` in prose has to know its own number, and the number depends
+ * on how many distinct sources were cited before it — which only the
+ * surrounding page knows. So the four components share one manager through
+ * Svelte context: `<Citation>` registers a source and gets its ordinal back,
+ * `<ReferenceList>` renders what accumulated, and the footnote pair does the
+ * same for notes.
+ *
+ * `getBibliographyContext` does not throw when no provider is mounted: it
+ * falls back to a fresh manager, matching how this package's
+ * `setComponentsContext` degrades (`../context.svelte.ts`). A `<Citation>`
+ * rendered on its own — in a story, in a unit test, or on a page that never
+ * calls `setupBibliography` — is a legitimate use; it just numbers from one
+ * and has no reference list to link to.
+ *
+ * @module
+ */
+import type { Citation, Footnote } from './citation.ts';
+/** One collected source, with the order it was first cited in. */
+export interface BibliographyEntry {
+    readonly citation: Citation;
+    readonly order: number;
+}
+/**
+ * The per-page collector. Citations dedupe by id — the same source cited
+ * three times is `[1]` three times, which is the whole point of a numbered
+ * style — and footnotes dedupe by their own key.
+ */
+export declare class BibliographyManager {
+    #private;
+    /**
+     * Register a source and return its bibliography number, assigning the next
+     * one if this is its first appearance.
+     */
+    addCitation(citation: Citation): number;
+    /** Every collected source, in citation order. */
+    citations(): readonly BibliographyEntry[];
+    /** Register a footnote under a caller-supplied key. */
+    addFootnote(id: string, footnote: Footnote): void;
+    /** Every collected footnote, in registration order. */
+    footnotes(): readonly (readonly [string, Footnote])[];
+}
+/**
+ * Provide a bibliography to a component subtree. Call once, in the page (or
+ * layout) whose prose carries the citations.
+ */
+export declare const setupBibliography: () => BibliographyManager;
+/**
+ * The nearest provided bibliography, or a fresh standalone one.
+ *
+ * Falling back rather than throwing is deliberate (see the module doc).
+ */
+export declare const getBibliographyContext: () => BibliographyManager;

package/dist/citations/bibliography.svelte.js

@@ -0,0 +1,78 @@
+/**
+ * The bibliography context a page's citations and footnotes collect into.
+ *
+ * A `<Citation>` in prose has to know its own number, and the number depends
+ * on how many distinct sources were cited before it — which only the
+ * surrounding page knows. So the four components share one manager through
+ * Svelte context: `<Citation>` registers a source and gets its ordinal back,
+ * `<ReferenceList>` renders what accumulated, and the footnote pair does the
+ * same for notes.
+ *
+ * `getBibliographyContext` does not throw when no provider is mounted: it
+ * falls back to a fresh manager, matching how this package's
+ * `setComponentsContext` degrades (`../context.svelte.ts`). A `<Citation>`
+ * rendered on its own — in a story, in a unit test, or on a page that never
+ * calls `setupBibliography` — is a legitimate use; it just numbers from one
+ * and has no reference list to link to.
+ *
+ * @module
+ */
+import { getContext, setContext } from 'svelte';
+const BIBLIOGRAPHY_KEY = Symbol('components/bibliography');
+/**
+ * The per-page collector. Citations dedupe by id — the same source cited
+ * three times is `[1]` three times, which is the whole point of a numbered
+ * style — and footnotes dedupe by their own key.
+ */
+export class BibliographyManager {
+    #entries = $state(new Map());
+    #footnotes = $state(new Map());
+    #nextOrder = $state(1);
+    /**
+     * Register a source and return its bibliography number, assigning the next
+     * one if this is its first appearance.
+     */
+    addCitation(citation) {
+        const existing = this.#entries.get(citation.id);
+        if (existing !== undefined)
+            return existing.order;
+        const order = this.#nextOrder;
+        this.#entries.set(citation.id, { citation, order });
+        this.#nextOrder = order + 1;
+        return order;
+    }
+    /** Every collected source, in citation order. */
+    citations() {
+        return [...this.#entries.values()].sort((a, b) => a.order - b.order);
+    }
+    /** Register a footnote under a caller-supplied key. */
+    addFootnote(id, footnote) {
+        this.#footnotes.set(id, footnote);
+    }
+    /** Every collected footnote, in registration order. */
+    footnotes() {
+        return [...this.#footnotes.entries()];
+    }
+}
+/**
+ * Provide a bibliography to a component subtree. Call once, in the page (or
+ * layout) whose prose carries the citations.
+ */
+export const setupBibliography = () => {
+    const manager = new BibliographyManager();
+    setContext(BIBLIOGRAPHY_KEY, manager);
+    return manager;
+};
+/**
+ * The nearest provided bibliography, or a fresh standalone one.
+ *
+ * Falling back rather than throwing is deliberate (see the module doc).
+ */
+export const getBibliographyContext = () => {
+    // `getContext<T>` is typed to return `T`, but returns `undefined` when no
+    // provider is mounted — the `??` is the runtime fallback that type does not
+    // describe, which is why the annotation stays `BibliographyManager` rather
+    // than widening the whole call site to a union.
+    const provided = getContext(BIBLIOGRAPHY_KEY);
+    return provided ?? new BibliographyManager();
+};

package/dist/citations/citation.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The citation vocabulary and its formatter.
+ *
+ * The shape a `Citation` carries is deliberately not any particular app's
+ * publication model: this package is app-agnostic and presentational, and a
+ * component that imported a models package would put the whole model layer
+ * into every consumer's bundle for the sake of a title and a year. The app
+ * maps its resource onto this shape at its own seam, which is also what lets
+ * a Storybook story or a test render one from a literal.
+ *
+ * ## Why the formatter is a pure function here
+ *
+ * Formatting inside the component recomputes on every re-render and cannot
+ * be tested without mounting a component. Pulling it out fixes both — the
+ * caller can memoise, the list derives once — and a citation style is a pile
+ * of conditional punctuation, which is exactly the kind of code that is
+ * wrong in the fourth branch and never noticed by eye.
+ *
+ * The style is a compact author–date one. It is not CSL: a full CSL
+ * implementation is a dependency and a style-file pipeline, and most
+ * consumers need one readable rendering rather than eleven switchable ones.
+ *
+ * @module
+ */
+/** The kinds a citation renders differently. */
+export type CitationKind = 'article' | 'book' | 'chapter' | 'thesis' | 'report' | 'conference' | 'web' | 'dataset' | 'software' | 'media' | 'periodical';
+/**
+ * One bibliography entry, as a presentational component needs it.
+ *
+ * Every field beyond `id` / `kind` / `title` is optional, because every one of
+ * them is missing from some real citation: a thesis has no journal, a
+ * mononymous eighteenth-century author has no given name, and grey literature
+ * routinely has no year.
+ */
+export interface Citation {
+    /** The publication's node id — also the anchor `#ref-<id>` links to. */
+    readonly id: string;
+    readonly kind: CitationKind;
+    readonly title: string;
+    /** Author display names, already ordered by the byline's own ordinal. */
+    readonly authors?: readonly string[] | undefined;
+    /** Publication year, as printed. */
+    readonly year?: number | undefined;
+    /** The serial an article appeared in, or the book a chapter is from. */
+    readonly container?: string | undefined;
+    readonly volume?: string | undefined;
+    readonly issue?: string | undefined;
+    /** Page span, already assembled (`"12–34"`). */
+    readonly pages?: string | undefined;
+    readonly publisher?: string | undefined;
+    readonly place?: string | undefined;
+    readonly url?: string | undefined;
+    readonly doi?: string | undefined;
+    /** When the citing author read a web source. */
+    readonly accessed?: Date | undefined;
+}
+/** A footnote — tracked separately from citations. */
+export interface Footnote {
+    /** The note's text. */
+    readonly content: string;
+    /** A custom marker (`*`, `†`) instead of the auto-assigned number. */
+    readonly symbol?: string | undefined;
+}
+/**
+ * Render a citation as one formatted string.
+ *
+ * Pure and total: every branch is reachable from real data and none throws on
+ * a citation carrying nothing but a title, which is a state the corpus can
+ * genuinely be in (an ingested reference awaiting enrichment).
+ */
+export declare const formatCitation: (citation: Citation) => string;