astroidjs 0.1.1 → 0.2.0

package/dist/components/sections.d.ts

@@ -0,0 +1,577 @@
+import type { SectionCatalog, SectionDef, SectionField, SectionItem } from "louise-toolkit/content";
+export type { SectionCatalog, SectionDef, SectionField, SectionItem };
+/**
+ * Colorway → daisyUI surface classes, keyed to the `Theme.colors` set
+ * (brand/secondary/tertiary) plus the neutral base.
+ *
+ * This map is the site-owned half of the token contract: Louise stores
+ * `_settings.colorway = "brand"` and never learns what that renders as, so a
+ * brand re-theme is a change here and no content rewrite anywhere.
+ */
+export declare const COLORWAY_CLASS: {
+    readonly brand: "bg-primary text-primary-content";
+    readonly secondary: "bg-secondary text-secondary-content";
+    readonly tertiary: "bg-accent text-accent-content";
+    readonly base: "bg-base-100 text-base-content";
+};
+export type Colorway = keyof typeof COLORWAY_CLASS;
+/** Content alignment → flex/text-alignment utilities. Same token contract. */
+export declare const ALIGN_CLASS: {
+    readonly start: "text-start items-start";
+    readonly center: "text-center items-center";
+    readonly end: "text-end items-end";
+};
+export type Align = keyof typeof ALIGN_CLASS;
+/** Resolve a colorway token to its class string (default: neutral base). */
+export declare function colorwayClass(colorway?: string | undefined): string;
+/** Resolve an alignment token to its class string (default: start). */
+export declare function alignClass(align?: string | undefined): string;
+/**
+ * The shared `_settings` every section in the catalog accepts.
+ *
+ * These are closed token sets, declared as `select` (#272) so the inspector
+ * renders a picker and an unknown token is rejected on write. They used to be
+ * `text` with the valid values stuffed into `placeholder` — which meant a typo
+ * wasn't a validation error at all, just a silent fallback to the default
+ * inside `colorwayClass` at render time.
+ */
+export declare const SECTION_SETTINGS: Record<string, SectionField>;
+/**
+ * What every section render component receives.
+ *
+ * `base` is the whole point. It is this item's path within the page's `sections`
+ * array — `"2"` for a top-level section, `"2.blocks.0"` for a block inside it —
+ * and every marker the component stamps is built from it. Passing it down (rather
+ * than having each component work out its own depth) is what lets the exact same
+ * component render as a section or as a block, and what keeps `data-louise-sfield`
+ * paths correct at any nesting depth.
+ */
+export interface SectionRenderProps {
+    /** The stored item: `_type` plus its field values, settings, and blocks. */
+    item: SectionItem;
+    /** Path prefix for this item's markers (`"2"`, `"2.blocks.0"`). */
+    base: string;
+    /** Whether to stamp edit markers. Defaults to `Astro.locals.editMode`. */
+    edit?: boolean;
+    /** Alt/caption resolved from the media registry, keyed by public URL —
+     *  looked up once for the whole page by `<Sections>`. */
+    mediaMeta?: MediaMeta;
+}
+/** Asset-level `alt`/`caption` from the media registry, keyed by public URL. */
+export type MediaMeta = Record<string, {
+    alt?: string;
+    caption?: string;
+}>;
+/** Read a `_settings` token as a string, or a fallback. Tolerant by design: a
+ *  stored setting is untrusted JSON, and a bad token should degrade to the
+ *  default rather than throw during render. */
+export declare function setting(item: SectionItem, key: string, fallback?: string): string | undefined;
+/** Read a section field as a string (the common case for text/richText). */
+export declare function field(item: SectionItem, key: string): string | undefined;
+/** Read an `array` field as a list of objects, or `[]`. Stored arrays are
+ *  untrusted, so a non-array or a scalar entry is dropped rather than rendered. */
+export declare function list(item: SectionItem, key: string): Record<string, unknown>[];
+/** Read a string off an array item (see {@link list}). */
+export declare function itemField(row: Record<string, unknown>, key: string): string | undefined;
+/**
+ * Alt text for an image, resolving the ASSET-LEVEL fallback.
+ *
+ * The precedence is the whole reason `<Sections>` does its media lookup: a
+ * per-usage `alt` on the section wins, because the same photo means something
+ * different in a hero than in a thumbnail strip — but when there isn't one, the
+ * alt an editor typed once in the media library is used. That's what makes
+ * fixing alt text a single edit that propagates everywhere the asset appears,
+ * instead of a hunt through every page that embeds it.
+ *
+ * Returns `""` rather than undefined when neither exists: an image with no
+ * description is decorative as far as a screen reader is concerned, and an
+ * empty alt says exactly that. A missing attribute makes it read the filename.
+ */
+export declare function mediaAlt(mediaMeta: MediaMeta | undefined, src: string | undefined, override?: string): string;
+/** Caption for an image, same precedence as {@link mediaAlt}. Undefined when
+ *  there is none — a missing caption renders nothing, unlike a missing alt. */
+export declare function mediaCaption(mediaMeta: MediaMeta | undefined, src: string | undefined, override?: string): string | undefined;
+/**
+ * Every section type Astroid ships.
+ *
+ * `satisfies` rather than a `: SectionCatalog` annotation, and it matters:
+ * `SectionCatalog` is `Record<string, SectionDef>`, so annotating would widen
+ * `keyof typeof` to `string` and throw away the literal keys. Those keys are
+ * the project's whole section vocabulary — `SectionKind` is derived from them
+ * (config.ts), `isRenderableSection` narrows to them, and `<Section>` indexes
+ * its component map with them. Annotate this and all three silently degrade to
+ * "any string", which is how the dispatcher lost its type safety once already.
+ */
+export declare const astroidSectionCatalog: {
+    hero: {
+        label: string;
+        icon: string;
+        fields: {
+            heading: {
+                type: "text";
+                label: string;
+                validation: (r: import("louise-toolkit/content").Rule) => import("louise-toolkit/content").Rule;
+            };
+            subheading: {
+                type: "textarea";
+                label: string;
+            };
+            ctaLabel: {
+                type: "text";
+                label: string;
+            };
+            ctaHref: {
+                type: "text";
+                label: string;
+                inline: false;
+            };
+        };
+        settings: Record<string, SectionField>;
+    };
+    featureGrid: {
+        label: string;
+        icon: string;
+        fields: {
+            heading: {
+                type: "text";
+                label: string;
+            };
+            items: {
+                type: "array";
+                label: string;
+                itemLabel: string;
+                itemFields: {
+                    title: {
+                        type: "text";
+                        label: string;
+                        validation: (r: import("louise-toolkit/content").Rule) => import("louise-toolkit/content").Rule;
+                    };
+                    body: {
+                        type: "textarea";
+                        label: string;
+                    };
+                };
+            };
+        };
+        settings: Record<string, SectionField>;
+    };
+    cta: {
+        label: string;
+        icon: string;
+        fields: {
+            heading: {
+                type: "text";
+                label: string;
+                validation: (r: import("louise-toolkit/content").Rule) => import("louise-toolkit/content").Rule;
+            };
+            body: {
+                type: "textarea";
+                label: string;
+            };
+            ctaLabel: {
+                type: "text";
+                label: string;
+                validation: (r: import("louise-toolkit/content").Rule) => import("louise-toolkit/content").Rule;
+            };
+            ctaHref: {
+                type: "text";
+                label: string;
+                inline: false;
+            };
+        };
+        settings: Record<string, SectionField>;
+    };
+    gallery: {
+        label: string;
+        icon: string;
+        fields: {
+            heading: {
+                type: "text";
+                label: string;
+            };
+            items: {
+                type: "array";
+                label: string;
+                itemLabel: string;
+                itemFields: {
+                    image: {
+                        type: "image";
+                        label: string;
+                    };
+                    alt: {
+                        type: "text";
+                        label: string;
+                        inline: false;
+                    };
+                    caption: {
+                        type: "text";
+                        label: string;
+                    };
+                    href: {
+                        type: "text";
+                        label: string;
+                        inline: false;
+                    };
+                };
+            };
+        };
+        settings: Record<string, SectionField>;
+    };
+    media: {
+        label: string;
+        icon: string;
+        fields: {
+            heading: {
+                type: "text";
+                label: string;
+            };
+            image: {
+                type: "image";
+                label: string;
+            };
+            alt: {
+                type: "text";
+                label: string;
+                inline: false;
+            };
+            caption: {
+                type: "text";
+                label: string;
+            };
+        };
+        settings: Record<string, SectionField>;
+    };
+    splitImage: {
+        label: string;
+        icon: string;
+        fields: {
+            heading: {
+                type: "text";
+                label: string;
+                validation: (r: import("louise-toolkit/content").Rule) => import("louise-toolkit/content").Rule;
+            };
+            body: {
+                type: "richText";
+                label: string;
+            };
+            image: {
+                type: "image";
+                label: string;
+            };
+            alt: {
+                type: "text";
+                label: string;
+                inline: false;
+            };
+            ctaLabel: {
+                type: "text";
+                label: string;
+            };
+            ctaHref: {
+                type: "text";
+                label: string;
+                inline: false;
+            };
+        };
+        layouts: {
+            imageStart: {
+                label: string;
+            };
+            imageEnd: {
+                label: string;
+            };
+        };
+        settings: Record<string, SectionField>;
+    };
+    steps: {
+        label: string;
+        icon: string;
+        fields: {
+            heading: {
+                type: "text";
+                label: string;
+            };
+            items: {
+                type: "array";
+                label: string;
+                itemLabel: string;
+                itemFields: {
+                    title: {
+                        type: "text";
+                        label: string;
+                        validation: (r: import("louise-toolkit/content").Rule) => import("louise-toolkit/content").Rule;
+                    };
+                    body: {
+                        type: "textarea";
+                        label: string;
+                    };
+                };
+            };
+        };
+        settings: Record<string, SectionField>;
+    };
+    banner: {
+        label: string;
+        icon: string;
+        fields: {
+            text: {
+                type: "text";
+                label: string;
+                validation: (r: import("louise-toolkit/content").Rule) => import("louise-toolkit/content").Rule;
+            };
+            ctaLabel: {
+                type: "text";
+                label: string;
+            };
+            ctaHref: {
+                type: "text";
+                label: string;
+                inline: false;
+            };
+        };
+        settings: Record<string, SectionField>;
+    };
+    faq: {
+        label: string;
+        icon: string;
+        fields: {
+            heading: {
+                type: "text";
+                label: string;
+            };
+            items: {
+                type: "array";
+                label: string;
+                itemLabel: string;
+                itemFields: {
+                    question: {
+                        type: "text";
+                        label: string;
+                        validation: (r: import("louise-toolkit/content").Rule) => import("louise-toolkit/content").Rule;
+                    };
+                    answer: {
+                        type: "richText";
+                        label: string;
+                    };
+                };
+            };
+        };
+        settings: Record<string, SectionField>;
+    };
+    pricingTiers: {
+        label: string;
+        icon: string;
+        fields: {
+            heading: {
+                type: "text";
+                label: string;
+            };
+            items: {
+                type: "array";
+                label: string;
+                itemLabel: string;
+                itemFields: {
+                    name: {
+                        type: "text";
+                        label: string;
+                        validation: (r: import("louise-toolkit/content").Rule) => import("louise-toolkit/content").Rule;
+                    };
+                    price: {
+                        type: "text";
+                        label: string;
+                    };
+                    period: {
+                        type: "text";
+                        label: string;
+                    };
+                    features: {
+                        type: "array";
+                        label: string;
+                        itemLabel: string;
+                        itemFields: {
+                            text: {
+                                type: "text";
+                                label: string;
+                            };
+                        };
+                    };
+                    ctaLabel: {
+                        type: "text";
+                        label: string;
+                    };
+                    ctaHref: {
+                        type: "text";
+                        label: string;
+                        inline: false;
+                    };
+                    featured: {
+                        type: "select";
+                        label: string;
+                        inline: false;
+                        options: {
+                            value: string;
+                            label: string;
+                        }[];
+                    };
+                };
+            };
+        };
+        settings: Record<string, SectionField>;
+    };
+    testimonial: {
+        label: string;
+        icon: string;
+        fields: {
+            quote: {
+                type: "textarea";
+                label: string;
+                validation: (r: import("louise-toolkit/content").Rule) => import("louise-toolkit/content").Rule;
+            };
+            attribution: {
+                type: "text";
+                label: string;
+            };
+            role: {
+                type: "text";
+                label: string;
+            };
+            image: {
+                type: "image";
+                label: string;
+            };
+            alt: {
+                type: "text";
+                label: string;
+                inline: false;
+            };
+        };
+        settings: Record<string, SectionField>;
+    };
+    aboutIntro: {
+        label: string;
+        icon: string;
+        fields: {
+            heading: {
+                type: "text";
+                label: string;
+                validation: (r: import("louise-toolkit/content").Rule) => import("louise-toolkit/content").Rule;
+            };
+            body: {
+                type: "richText";
+                label: string;
+            };
+            image: {
+                type: "image";
+                label: string;
+            };
+            alt: {
+                type: "text";
+                label: string;
+                inline: false;
+            };
+        };
+        settings: Record<string, SectionField>;
+    };
+    productGrid: {
+        label: string;
+        icon: string;
+        fields: {
+            heading: {
+                type: "text";
+                label: string;
+            };
+            items: {
+                type: "array";
+                label: string;
+                itemLabel: string;
+                itemFields: {
+                    name: {
+                        type: "text";
+                        label: string;
+                        validation: (r: import("louise-toolkit/content").Rule) => import("louise-toolkit/content").Rule;
+                    };
+                    price: {
+                        type: "text";
+                        label: string;
+                    };
+                    image: {
+                        type: "image";
+                        label: string;
+                    };
+                    alt: {
+                        type: "text";
+                        label: string;
+                        inline: false;
+                    };
+                    href: {
+                        type: "text";
+                        label: string;
+                        inline: false;
+                    };
+                };
+            };
+        };
+        settings: Record<string, SectionField>;
+    };
+    locationHours: {
+        label: string;
+        icon: string;
+        fields: {
+            heading: {
+                type: "text";
+                label: string;
+            };
+            address: {
+                type: "textarea";
+                label: string;
+            };
+            phone: {
+                type: "text";
+                label: string;
+            };
+            items: {
+                type: "array";
+                label: string;
+                itemLabel: string;
+                itemFields: {
+                    day: {
+                        type: "text";
+                        label: string;
+                        validation: (r: import("louise-toolkit/content").Rule) => import("louise-toolkit/content").Rule;
+                    };
+                    hours: {
+                        type: "text";
+                        label: string;
+                    };
+                };
+            };
+        };
+        settings: Record<string, SectionField>;
+    };
+    contact: {
+        label: string;
+        icon: string;
+        fields: {
+            heading: {
+                type: "text";
+                label: string;
+            };
+            blurb: {
+                type: "textarea";
+                label: string;
+            };
+        };
+        settings: Record<string, SectionField>;
+    };
+};
+/** The `_type`s with a shipped render component — derived from the catalog, so
+ *  it can't drift from what `<Section>` actually dispatches. A literal union,
+ *  not `string`, because the catalog is declared with `satisfies`. */
+export type RenderableSectionType = keyof typeof astroidSectionCatalog;
+/**
+ * Does this `_type` have a shipped component? Narrows the untrusted `_type` of a
+ * stored item, so `<Sections>` can skip an unknown one instead of rendering a
+ * hole. (Unknown types are legitimate mid-migration, and `validateSections`
+ * already rejects them on write.)
+ */
+export declare function isRenderableSection(type: string): type is RenderableSectionType;