@aglyn/plugins-mui 1.0.0-beta.143

package/src/lib/components/collection.d.ts

@@ -0,0 +1,514 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import * as Aglyn from '@aglyn/aglyn';
+import { type StackProps } from '@mui/material/Stack';
+export declare const ENTRIES_ID: Aglyn.ComponentId;
+export declare const ENTRY_BODY_ID: Aglyn.ComponentId;
+export declare const RELATED_ID: Aglyn.ComponentId;
+export declare const SHARE_ID: Aglyn.ComponentId;
+export declare const ENTRY_META_ID: Aglyn.ComponentId;
+export declare const ENTRY_AUTHOR_ID: Aglyn.ComponentId;
+export declare const CATEGORIES_ID: Aglyn.ComponentId;
+export declare const SEARCH_ID: Aglyn.ComponentId;
+export declare const AUTHOR_PROFILE_ID: Aglyn.ComponentId;
+export interface CollectionEntriesProps extends StackProps {
+    /**
+     * Collection to repeat over (compose-time, AGL-551). Blank = the
+     * collection routed by the current URL on list-template screens.
+     */
+    collectionSlug?: string;
+    /** Maximum entries rendered (compose-time; blank = all, capped at 100). */
+    entriesLimit?: number | string;
+    /**
+     * Only entries in this category repeat (compose-time, AGL-582).
+     * Matches the collection's category by stable id or display name.
+     */
+    filterCategory?: string;
+    /** Only entries carrying this tag repeat (compose-time, AGL-582). */
+    filterTag?: string;
+    /**
+     * Entries per page (compose-time, AGL-620). When set, the block renders one
+     * page window instead of the top `entriesLimit`; the built-in collection
+     * list uses this with the `page` from `/{collection}/page/{n}`.
+     */
+    perPage?: number | string;
+    /** 1-based page for `perPage` (compose-time, AGL-620). */
+    page?: number | string;
+    /**
+     * Render this block only on page 1 of the routed listing (compose-time,
+     * AGL-1871). For a LEAD card — a block with no `perPage`, showing the top
+     * of the set — every `/{collection}/page/{n}` past the first otherwise
+     * repeats the identical entry above a page of different ones.
+     *
+     * Opt-in and default off: a block that legitimately belongs on every page
+     * of a listing (a "popular posts" rail) has exactly the same shape.
+     */
+    firstPageOnly?: boolean;
+    /**
+     * Show a search box that filters the RENDERED entries by title/excerpt as
+     * the reader types (AGL-1516, Figma 494:1220). Opt-in and default off, so
+     * every existing instance renders exactly as before.
+     *
+     * Client-evaluated over the entries this block already holds — the page is
+     * ISR-cached, so a keystroke never costs a Firestore read. That set is
+     * whatever the expansion left the block holding, which paging, an
+     * `entriesLimit` or the 100-entry cap can each cut down. A truncated block
+     * says so under its results either way — on a miss and on a hit
+     * (AGL-1516, AGL-2569) — rather than pretending global search.
+     */
+    search?: boolean;
+    /**
+     * What the search box DOES with a query (AGL-1525, Figma 496:1218).
+     *
+     * - `filter` (default, and the reading of an absent value) — hides the
+     *   non-matching cards in place. What AGL-1516 shipped.
+     * - `suggest` — the card grid stays exactly as it was and a floating panel
+     *   of matching entries opens under the field, ending in a link to the
+     *   site-wide results page. The frame's toolbar behaviour: a reader
+     *   skimming the list is not made to lose it to a typo.
+     */
+    searchMode?: CollectionSearchMode;
+    /** Hint text inside the search box (blank = "Search posts…"). */
+    searchPlaceholder?: string;
+    /**
+     * Server-stamped matchable text per rendered entry
+     * (`expandCollectionEntries`, AGL-1516); never set by hand.
+     */
+    searchIndex?: Aglyn.CollectionEntrySearchItem[];
+    /**
+     * How many entries `searchIndex` was drawn from — server-stamped by
+     * `expandCollectionEntries` alongside it (AGL-1516), never set by hand.
+     * `searchIndex.length < searchTotal` is the only honest test of whether
+     * this block holds the whole set; `perPage` is not, because
+     * `entriesLimit` and the 100-entry cap truncate too.
+     */
+    searchTotal?: number;
+    /**
+     * Whether the read behind `searchTotal` reached its own bound — server-
+     * stamped beside it (AGL-1516), never set by hand.
+     *
+     * `searchTotal` is a count of what the server SAW, and the collection read
+     * is limited. Without this flag a block holding 100 of 400 posts satisfies
+     * `searchIndex.length === searchTotal` and renders the one empty state that
+     * claims to have looked everywhere.
+     */
+    searchCapped?: boolean;
+}
+/** The two things the toolbar search box can do (AGL-1516/AGL-1525). */
+export type CollectionSearchMode = 'filter' | 'suggest';
+/**
+ * Author-facing choices for {@link CollectionEntriesProps.searchMode}.
+ *
+ * Both values are truthy on purpose (AGL-1453): `''` cannot survive a save,
+ * so an author who tried the other mode would have no route back. "Filter"
+ * carries the absent-value reading, which is what every block published
+ * before AGL-1525 has.
+ */
+export declare const COLLECTION_SEARCH_MODE_OPTIONS: ReadonlyArray<{
+    value: CollectionSearchMode;
+    label: string;
+}>;
+/**
+ * Repeats its children once per published entry of a content collection
+ * (AGL-551) — the collections sibling of the dataset repeatable. The tenant
+ * expands it at compose time with `{{entry.*}}` tokens; in the besigner the
+ * template renders once with literal tokens, matching the repeatable UX.
+ *
+ * Search (AGL-1516): with `search` on, a toolbar search box filters the
+ * rendered entry clones client-side against the server-stamped
+ * `searchIndex` — fuzzy, via the same Fuse the icon picker uses. The clones
+ * arrive as `children` in stamp order, one group of template roots per
+ * entry, so group N of the children IS entry N of the index. Matches keep
+ * the list's own order rather than Fuse's score order: a blog list is
+ * chronological, and search narrows it, it does not reshuffle it. In the
+ * besigner the field renders as an inert affordance (the template renders
+ * once with literal tokens and there is no index to search), matching how
+ * Category Pills go inert on editing surfaces.
+ */
+declare const CollectionEntries: import("react").ForwardRefExoticComponent<Omit<CollectionEntriesProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export declare const collectionEntriesSchema: Aglyn.ComponentSchema<CollectionEntriesProps>;
+export interface CollectionEntryBodyProps {
+    /**
+     * Markdown-lite source. On entry-template screens `{{entry.body}}`
+     * resolves to the rendered entry's body at compose time.
+     */
+    markdown?: string;
+    /**
+     * The pixel pair of each library image this body names, keyed by the target
+     * as the body writes it, stamped by the composition from the assets' DAM
+     * records (AGL-3149) — never set by hand, and never on the template, where
+     * `markdown` is still the `{{entry.body}}` token and names no asset.
+     */
+    intrinsicSizes?: Record<string, {
+        width: number;
+        height: number;
+    }>;
+}
+/**
+ * Renders a content entry's markdown-lite body as themed MUI elements
+ * (AGL-551): headings, paragraphs, lists, and images pick up the site
+ * theme's typography instead of the old unthemed article HTML. Parsing is
+ * pure, so the full body server-renders (SEO keeps the article text).
+ */
+declare const CollectionEntryBody: import("react").ForwardRefExoticComponent<CollectionEntryBodyProps & import("react").RefAttributes<HTMLDivElement>>;
+export declare const collectionEntryBodySchema: Aglyn.ComponentSchema<CollectionEntryBodyProps>;
+/** How the related posts are laid out (AGL-1457). */
+export type CollectionRelatedLayout = 'list' | 'cards';
+/** One related post as stamped by the compose pipeline (AGL-582). */
+export interface CollectionRelatedProps extends StackProps {
+    /** Section heading; empty string hides it. */
+    heading?: string;
+    /** Compose-time: most related posts listed (default 3). */
+    limit?: number | string;
+    /**
+     * Emit each entry's cover image (AGL-1457). OFF is the default and the
+     * shipped behaviour — the block is live on every blog entry, so turning
+     * covers on by default would restyle published pages nobody asked about.
+     */
+    showCover?: boolean;
+    /**
+     * `list` (default) is the plain-link list that has always shipped; `cards`
+     * is the article frame's grid of cover + category chip + title.
+     */
+    layout?: CollectionRelatedLayout;
+    /** Columns in the `cards` grid (default 3, the frame's 3-up). */
+    columns?: number | string;
+    /**
+     * Type step the section heading reads at (default `h5`). One of the
+     * theme's own rungs, shared with the Typography element — a heading sized
+     * by hand in the Styles panel is the pixel-typing the tokens exist to stop.
+     */
+    headingVariant?: string;
+    /**
+     * Type step each card title reads at (default `subtitle1`, what the block
+     * has always emitted). The title is the block's own markup, so the Styles
+     * panel — which edits the node's root — cannot reach it; this is the only
+     * handle on it.
+     */
+    titleVariant?: string;
+    /** Show each post's published date. On is the shipped behaviour. */
+    showDate?: boolean;
+    /**
+     * How each card's published date reads (AGL-1459) — a COMPOSE-TIME prop
+     * like {@link limit}: it is answered in `expandCollectionRelated`, where
+     * the timestamp still exists, and never reaches the DOM. Blank, or
+     * `default`, is the locale date the block has always emitted.
+     *
+     * Read here too, but only to date the SAMPLE cards: an editing surface has
+     * no routed entry and therefore no server fill, so the picker would
+     * otherwise preview nothing.
+     */
+    dateFormat?: Aglyn.CollectionEntryDateFormat;
+    /** Show each post's category. On is the shipped behaviour. */
+    showCategory?: boolean;
+    /**
+     * Show each post's excerpt. OFF is the default and the shipped behaviour:
+     * the excerpt has been stamped onto every related item since AGL-582 and
+     * rendered by nothing, so turning it on by default would add a paragraph
+     * to every published entry nobody asked about.
+     */
+    showExcerpt?: boolean;
+    /**
+     * Server-stamped related posts (`expandCollectionRelated`); never set by
+     * hand — the tenant computes it from the current entry's category/tags.
+     */
+    entries?: Aglyn.CollectionRelatedItem[];
+}
+/**
+ * Lists other entries of the same collection sharing the current entry's
+ * category or a tag (AGL-582). The tenant stamps `entries` at compose time
+ * on entry renders; without them the published site renders nothing and an
+ * editing surface renders sample cards (AGL-2486).
+ *
+ * Two layouts (AGL-1457). `list` is the plain-link list that has always
+ * shipped and stays the default — the block is live on every blog entry, so
+ * a new default would restyle published pages nobody asked about. `cards` is
+ * the article frame's grid: cover, category chip, title, at an author-set
+ * column count.
+ *
+ * The block owns its markup, so nothing inside a card is a node the Styles
+ * panel can select. Every part it renders therefore needs an attribute, or
+ * it is unauthorable by construction — which is what the type steps and the
+ * `show*` switches are (AGL-2486).
+ */
+declare const CollectionRelated: import("react").ForwardRefExoticComponent<Omit<CollectionRelatedProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export declare const collectionRelatedSchema: Aglyn.ComponentSchema<CollectionRelatedProps>;
+export interface CollectionShareProps extends StackProps {
+    /** Heading before the buttons; empty string hides it. */
+    heading?: string;
+}
+/**
+ * Share buttons for the CURRENT page URL (AGL-582): X, LinkedIn, Facebook,
+ * and copy-link. Pure client behavior — the URL is read at click time so
+ * SSR and besigner renders stay markup-identical; editing surfaces no-op.
+ */
+declare const CollectionShare: import("react").ForwardRefExoticComponent<Omit<CollectionShareProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export declare const collectionShareSchema: Aglyn.ComponentSchema<CollectionShareProps>;
+export interface CollectionEntryMetaProps extends StackProps {
+    /**
+     * Published date. Server-filled from the routed entry on entry templates
+     * (`expandCollectionEntryMeta`, AGL-1385); set it — or bind
+     * `{{entry.date}}` — only to override.
+     */
+    date?: string;
+    /**
+     * How {@link date} reads when the server fills it in (AGL-1459) — a
+     * COMPOSE-TIME prop, like Related Posts' `limit`: it is answered where the
+     * timestamp still exists (`expandCollectionEntryMeta`) and never reaches the
+     * DOM. Blank, or `default`, is the locale date the block has always emitted.
+     */
+    dateFormat?: Aglyn.CollectionEntryDateFormat;
+    /**
+     * Byline (AGL-1459). Server-filled from the entry's own author on entry
+     * templates, exactly like {@link date}; set it — or bind `{{entry.author}}`
+     * — only to override.
+     */
+    author?: string;
+    /** Category; server-filled, or bind `{{entry.category}}` to override. */
+    category?: string;
+    /** Comma-joined tags; server-filled, or bind `{{entry.tags}}`. */
+    tags?: string;
+    /**
+     * Round avatar shown before the byline (AGL-1459) — a media-picker target,
+     * so it holds a media reference (AGL-1215) as well as any URL form.
+     *
+     * A block-level pick, deliberately, and NOT a per-author image: entries
+     * carry an author NAME (`authorName`) and no portrait field, so a per-author
+     * avatar would need a schema decision on the entry model plus an editor
+     * field to fill it. Until then this is the site's brand mark, chosen once on
+     * the template — which is what the article frame actually asks for. Left
+     * unset it renders nothing at all, never a broken image.
+     */
+    avatarImage?: string;
+    showDate?: boolean;
+    showAuthor?: boolean;
+    /**
+     * Where the byline's NAME links — the author's page on this site
+     * (AGL-2519). Server-filled from the routed entry's author, like the
+     * avatar beside it; blank renders the name as plain text.
+     *
+     * Distinct from the author's own `url`, which the Entry Author card offers
+     * as a link row: this is "everything they wrote here", that is "their
+     * site", and a byline that conflated them would send a reader off-site from
+     * every article.
+     */
+    authorPageUrl?: string;
+    /** Off leaves the byline as plain text even when the author has a page. */
+    linkAuthor?: boolean;
+    showCategory?: boolean;
+    showTags?: boolean;
+    showAvatar?: boolean;
+}
+/**
+ * "{{entry.date}} · {{entry.category}}" meta line plus tag chips
+ * (AGL-582). Values arrive through entry tokens on entry renders; on other
+ * surfaces unresolved tokens collapse to nothing instead of leaking.
+ *
+ * On an entry template the tenant now also FILLS the three values from the
+ * routed entry when nothing is bound (`expandCollectionEntryMeta`, AGL-1385).
+ * Before that, a block dragged from the palette rather than dropped as the
+ * preset had no values at all — three "Show" switches gating nothing — and
+ * rendered as the empty `<Box>` below, at height 0.
+ */
+declare const CollectionEntryMeta: import("react").ForwardRefExoticComponent<Omit<CollectionEntryMetaProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export declare const collectionEntryMetaSchema: Aglyn.ComponentSchema<CollectionEntryMetaProps>;
+export interface CollectionEntryAuthorProps extends StackProps {
+    /**
+     * The byline. Server-filled from the routed entry's author record on entry
+     * templates (`expandCollectionEntryAuthor`), exactly like Entry Meta's
+     * fields; set it — or bind `{{entry.author}}` — only to override.
+     */
+    name?: string;
+    /**
+     * The author's blurb, from their record's `bio`; bind
+     * `{{entry.authorBio}}` to override.
+     */
+    bio?: string;
+    /**
+     * Portrait or logo — a media reference (AGL-1215) or any URL. Server-filled
+     * from the author record, so the face changes with the byline instead of
+     * being picked once on the template the way Entry Meta's avatar is.
+     */
+    image?: string;
+    /** The author's own site; offered as a link row beside the profile ones. */
+    url?: string;
+    /**
+     * The author's page on THIS site (AGL-2519), server-filled from the routed
+     * entry. The name links here.
+     *
+     * It wins over {@link url} for the NAME, and the ordering is the point: a
+     * reader who clicks a byline at the end of an article is asking "what else
+     * has this person written here", not "take me off this site". Their own
+     * url is still reachable — it is one of the link rows — so nothing is lost
+     * by giving the name the destination that answers the question asked.
+     */
+    pageUrl?: string;
+    /**
+     * The author's profile links, server-filled from their record (AGL-2516).
+     *
+     * Not authorable as text: each row carries a platform or a picked icon, and
+     * the console's author editor is where those are chosen. `Show links` is
+     * the template's control over them.
+     */
+    links?: Aglyn.ContentAuthorLink[];
+    showBio?: boolean;
+    showAvatar?: boolean;
+    showLinks?: boolean;
+}
+/**
+ * The author card that closes an article (AGL-2486) — portrait, byline, bio.
+ *
+ * Entry Meta prints a NAME beside a date, which is all an entry carried when
+ * it was written: one free-typed string. Custom authors made the byline a
+ * record with a portrait, a bio and a url, and a template that wanted the
+ * card the article frame draws still had to type the name and the blurb in as
+ * literal text — text that keeps saying whatever it said under posts somebody
+ * else wrote, and that no edit to the author record can ever reach. This is
+ * that card, filled from the record.
+ *
+ * Every field is independently overridable and every one of them collapses
+ * when empty: an author with no portrait renders the text alone rather than a
+ * gap where a face would be, and an entry with no author at all renders
+ * nothing — never an empty bordered box.
+ */
+declare const CollectionEntryAuthor: import("react").ForwardRefExoticComponent<Omit<CollectionEntryAuthorProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export declare const collectionEntryAuthorSchema: Aglyn.ComponentSchema<CollectionEntryAuthorProps>;
+export interface ContentAuthorProfileProps extends StackProps {
+    /**
+     * The byline. Server-filled from the routed author on their own page
+     * (`expandContentAuthorProfile`); set it — or bind `{{author.name}}` —
+     * only to override.
+     */
+    name?: string;
+    /** The blurb from their record; bind `{{author.bio}}` to override. */
+    bio?: string;
+    /**
+     * Portrait or logo — a media reference (AGL-1215) or any URL, filled from
+     * the record so the face follows the person rather than the template.
+     */
+    image?: string;
+    /** Person only — what they do; blank on an Organization. */
+    jobTitle?: string;
+    /** Person only — who they write for. */
+    worksFor?: string;
+    /**
+     * Their OWN site. The name links here; blank renders it as plain text.
+     * This block already IS the author's page, so it does not link to itself.
+     */
+    url?: string;
+    /** Their profile links, server-filled from the record (AGL-2516). */
+    links?: Aglyn.ContentAuthorLink[];
+    showBio?: boolean;
+    showAvatar?: boolean;
+    showRole?: boolean;
+    showLinks?: boolean;
+}
+/**
+ * Who an author page is about (AGL-2518) — portrait, name, role, bio, links.
+ *
+ * The Entry Author card renders the same person as a footnote under an
+ * article. This renders them as the SUBJECT of a page, which is why it has
+ * the two fields that card has no room for: `jobTitle` and `worksFor` are
+ * what tell a stranger who they are looking at, and they are already on the
+ * record because `schema.org/Person` defines them (AGL-2486).
+ *
+ * Every field is independently overridable and every one collapses when
+ * empty, exactly as the card's do — an author with no portrait renders the
+ * text alone rather than a gap where a face would be. On an editing surface
+ * the block previews its own shape with sample text, because a template is
+ * designed before any author is routed through it.
+ */
+declare const ContentAuthorProfile: import("react").ForwardRefExoticComponent<Omit<ContentAuthorProfileProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export { ContentAuthorProfile };
+export declare const contentAuthorProfileSchema: Aglyn.ComponentSchema<ContentAuthorProfileProps>;
+export interface CollectionCategoriesProps extends StackProps {
+    /**
+     * Collection whose taxonomy renders (compose-time). Blank = the collection
+     * routed by the current URL on list-template screens.
+     */
+    collectionSlug?: string;
+    /**
+     * Label for the unfiltered pill (default "All"). Clearing the field
+     * persists `Aglyn.COLLECTION_ALL_PILL_NONE`, which omits the pill —
+     * `''` cannot be stored at all (AGL-1336).
+     */
+    allLabel?: string;
+    /**
+     * Server-stamped pill links (`expandCollectionCategories`); never set by
+     * hand — the tenant builds them from the collection's categories and the
+     * routed category.
+     */
+    items?: Aglyn.CollectionCategoryLink[];
+}
+/**
+ * The category filter row for a collection listing (AGL-1321): "All" plus one
+ * pill per category, each a REAL anchor to `/{collection}/category/{slug}`.
+ *
+ * Anchors, not click handlers, and that is the whole design. A JS-only toggle
+ * would be invisible to crawlers, unopenable in a new tab, unlinkable, and
+ * unreachable without hydration — and it could not exist anyway, since the
+ * filter is resolved server-side before the page is composed. The pill the
+ * current URL selected carries `aria-current="page"`, stamped on the server so
+ * it is in the HTML rather than derived after hydration.
+ */
+declare const CollectionCategories: import("react").ForwardRefExoticComponent<Omit<CollectionCategoriesProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export declare const collectionCategoriesSchema: Aglyn.ComponentSchema<CollectionCategoriesProps>;
+export interface CollectionSearchProps extends StackProps {
+    /**
+     * Collection whose entries this box searches (compose-time). Blank = the
+     * collection routed by the current URL on list-template screens.
+     */
+    collectionSlug?: string;
+    /** Hint text inside the box (blank = "Search posts…"). */
+    searchPlaceholder?: string;
+    /**
+     * Server-stamped matchable text per entry (`expandCollectionSearch`);
+     * never set by hand.
+     */
+    searchIndex?: Aglyn.CollectionEntrySearchItem[];
+    /** How many entries the index was drawn from; never set by hand. */
+    searchTotal?: number;
+    /** Whether that read reached its bound; never set by hand. */
+    searchCapped?: boolean;
+}
+/**
+ * A search box for a collection that lives where the author puts it
+ * (AGL-1516, Figma 494:1220).
+ *
+ * The entries block has had a search box since AGL-1516's first half, and it
+ * renders inside that block — first child of its own stack. The frame puts
+ * the field in the listing's TOOLBAR: category pills on the left, search and
+ * RSS on the right, one row. That was unbuildable, and unbuildable in both
+ * directions — a block's own child cannot be lifted out of it, and the pills
+ * cannot be moved in, because every child of an entries block is cloned once
+ * per entry. Three passes of authoring hit the same wall.
+ *
+ * So the field became its own block. It searches the collection the listing
+ * beside it is drawn from, and answers with the suggestion panel (496:1218)
+ * — the only behaviour a standalone box can honestly have, since it owns no
+ * cards to hide. Enter submits to the site-wide results page, so the box
+ * works with no JavaScript at all.
+ *
+ * Inert on editing surfaces, like Category Pills: the besigner has no index
+ * to search, and a field that answered there would be answering about
+ * nothing.
+ */
+declare const CollectionSearch: import("react").ForwardRefExoticComponent<Omit<CollectionSearchProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export declare const collectionSearchSchema: Aglyn.ComponentSchema<CollectionSearchProps>;
+export declare const collectionPresets: Aglyn.PresetSchema[];
+export { CollectionCategories, CollectionEntries, CollectionEntryAuthor, CollectionEntryBody, CollectionEntryMeta, CollectionRelated, CollectionSearch, CollectionShare, };
+export default CollectionEntries;