@forumone/throughline-design-system 0.0.0 → 1.0.0-next.2

package/dist/contract/schema.d.ts

@@ -0,0 +1,334 @@
+import { z } from 'zod';
+/**
+ * The current version of the contract schema. Bump this when making a
+ * backwards-incompatible change to the shape. Manifests declare the
+ * version they satisfy so the loader can reject mismatches loudly.
+ */
+export declare const CONTRACT_VERSION = "1.0.0";
+declare const FieldTypeSchema: z.ZodEnum<["text", "richtext", "link", "image", "video", "select", "group", "array", "boolean", "number"]>;
+declare const PlacementSchema: z.ZodEnum<["page", "section", "inline"]>;
+declare const CategorySchema: z.ZodEnum<["hero", "section", "card", "media", "cta", "navigation", "data", "form", "utility"]>;
+/**
+ * Where an editor looks for a component, as distinct from what the component
+ * *is*.
+ *
+ * `category` answers the second question and several consumers reason about it
+ * as a kind. It is a poor answer to the first: a real design system files
+ * roughly half its library under `section`, so a picker grouped on `category`
+ * hands back the flat list the grouping was meant to avoid, while `card` and
+ * `navigation` hold one entry each. Redistributing within `category` to even
+ * the shelves out would file components under the wrong kind for every other
+ * consumer.
+ *
+ * So this is a second, optional field. The values are shelf labels, chosen to
+ * split the sections a `category` cannot:
+ *
+ * - `hero`       — page openers
+ * - `narrative`  — sections that explain, walk through, or tell
+ * - `proof`      — sections that evidence a claim: testimony, clients, results
+ * - `listing`    — collections of records, usually repeating
+ * - `media`      — image, video, audio, and their captions
+ * - `form`       — anything an editor thinks of as a form
+ * - `cta`        — asks
+ * - `navigation` — wayfinding within or across pages
+ * - `utility`    — structural or incidental
+ *
+ * There is deliberately no `section`: a shelf that holds half the library is
+ * the problem this field exists to solve. There is no `card` or `data` either
+ * — both name a kind rather than a place to look, and their contents belong on
+ * `listing` and `proof` respectively.
+ */
+declare const GroupSchema: z.ZodEnum<["hero", "narrative", "proof", "listing", "media", "form", "cta", "navigation", "utility"]>;
+export type ContentField = {
+    name: string;
+    type: z.infer<typeof FieldTypeSchema>;
+    required: boolean;
+    maxLength?: number | undefined;
+    defaultValue?: boolean | undefined;
+    constraints?: string | undefined;
+    advanced?: boolean | undefined;
+    of?: ContentField[] | undefined;
+};
+/** Input shape for {@link ContentFieldSchema}: defaulted fields are optional. */
+export type ContentFieldInput = {
+    name: string;
+    type: z.infer<typeof FieldTypeSchema>;
+    required?: boolean | undefined;
+    maxLength?: number | undefined;
+    defaultValue?: boolean | undefined;
+    constraints?: string | undefined;
+    advanced?: boolean | undefined;
+    of?: ContentFieldInput[] | undefined;
+};
+export declare const ComponentContractSchema: z.ZodObject<{
+    name: z.ZodString;
+    category: z.ZodEnum<["hero", "section", "card", "media", "cta", "navigation", "data", "form", "utility"]>;
+    /**
+     * The shelf an authoring UI files this component under. Optional: when it is
+     * absent, {@link groupOf} falls back to {@link category}, so a design system
+     * that sets none groups exactly as it did before this field existed.
+     */
+    group: z.ZodOptional<z.ZodEnum<["hero", "narrative", "proof", "listing", "media", "form", "cta", "navigation", "utility"]>>;
+    description: z.ZodString;
+    intent: z.ZodString;
+    composition: z.ZodObject<{
+        placement: z.ZodArray<z.ZodEnum<["page", "section", "inline"]>, "atleastone">;
+        maxPerPage: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+        requiredSiblings: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        forbiddenAdjacent: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        allowedSlots: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+    }, "strip", z.ZodTypeAny, {
+        placement: ["inline" | "page" | "section", ...("inline" | "page" | "section")[]];
+        maxPerPage: number | null;
+        requiredSiblings: string[];
+        forbiddenAdjacent: string[];
+        allowedSlots?: Record<string, string[]> | undefined;
+    }, {
+        placement: ["inline" | "page" | "section", ...("inline" | "page" | "section")[]];
+        maxPerPage?: number | null | undefined;
+        requiredSiblings?: string[] | undefined;
+        forbiddenAdjacent?: string[] | undefined;
+        allowedSlots?: Record<string, string[]> | undefined;
+    }>;
+    content: z.ZodObject<{
+        fields: z.ZodArray<z.ZodType<ContentField, z.ZodTypeDef, ContentFieldInput>, "many">;
+        variants: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+            whenToUse: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            description: string;
+            whenToUse: string;
+        }, {
+            name: string;
+            description: string;
+            whenToUse: string;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        fields: ContentField[];
+        variants?: {
+            name: string;
+            description: string;
+            whenToUse: string;
+        }[] | undefined;
+    }, {
+        fields: ContentFieldInput[];
+        variants?: {
+            name: string;
+            description: string;
+            whenToUse: string;
+        }[] | undefined;
+    }>;
+    tokens: z.ZodObject<{
+        consumes: z.ZodArray<z.ZodString, "many">;
+        configurable: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            prop: z.ZodString;
+            tokenGroup: z.ZodString;
+            allowedValues: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            prop: string;
+            tokenGroup: string;
+            allowedValues: string[];
+        }, {
+            prop: string;
+            tokenGroup: string;
+            allowedValues: string[];
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        consumes: string[];
+        configurable?: {
+            prop: string;
+            tokenGroup: string;
+            allowedValues: string[];
+        }[] | undefined;
+    }, {
+        consumes: string[];
+        configurable?: {
+            prop: string;
+            tokenGroup: string;
+            allowedValues: string[];
+        }[] | undefined;
+    }>;
+    accessibility: z.ZodObject<{
+        role: z.ZodOptional<z.ZodString>;
+        keyboardSupport: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        screenReaderBehavior: z.ZodString;
+        contentWarnings: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        keyboardSupport: string[];
+        screenReaderBehavior: string;
+        contentWarnings: string[];
+        role?: string | undefined;
+    }, {
+        screenReaderBehavior: string;
+        role?: string | undefined;
+        keyboardSupport?: string[] | undefined;
+        contentWarnings?: string[] | undefined;
+    }>;
+    examples: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        intent: z.ZodString;
+        storyId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        label: string;
+        intent: string;
+        storyId: string;
+    }, {
+        label: string;
+        intent: string;
+        storyId: string;
+    }>, "many">;
+    antiExamples: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        why: z.ZodString;
+        useInstead: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        label: string;
+        why: string;
+        useInstead?: string | undefined;
+    }, {
+        label: string;
+        why: string;
+        useInstead?: string | undefined;
+    }>, "many">>;
+    behavior: z.ZodDefault<z.ZodObject<{
+        fetchesData: z.ZodDefault<z.ZodBoolean>;
+        hasClientState: z.ZodDefault<z.ZodBoolean>;
+        animates: z.ZodDefault<z.ZodBoolean>;
+        requiresAnalytics: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        fetchesData: boolean;
+        hasClientState: boolean;
+        animates: boolean;
+        requiresAnalytics: boolean;
+    }, {
+        fetchesData?: boolean | undefined;
+        hasClientState?: boolean | undefined;
+        animates?: boolean | undefined;
+        requiresAnalytics?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    content: {
+        fields: ContentField[];
+        variants?: {
+            name: string;
+            description: string;
+            whenToUse: string;
+        }[] | undefined;
+    };
+    category: "cta" | "data" | "section" | "hero" | "card" | "media" | "navigation" | "form" | "utility";
+    intent: string;
+    composition: {
+        placement: ["inline" | "page" | "section", ...("inline" | "page" | "section")[]];
+        maxPerPage: number | null;
+        requiredSiblings: string[];
+        forbiddenAdjacent: string[];
+        allowedSlots?: Record<string, string[]> | undefined;
+    };
+    tokens: {
+        consumes: string[];
+        configurable?: {
+            prop: string;
+            tokenGroup: string;
+            allowedValues: string[];
+        }[] | undefined;
+    };
+    accessibility: {
+        keyboardSupport: string[];
+        screenReaderBehavior: string;
+        contentWarnings: string[];
+        role?: string | undefined;
+    };
+    examples: {
+        label: string;
+        intent: string;
+        storyId: string;
+    }[];
+    antiExamples: {
+        label: string;
+        why: string;
+        useInstead?: string | undefined;
+    }[];
+    behavior: {
+        fetchesData: boolean;
+        hasClientState: boolean;
+        animates: boolean;
+        requiresAnalytics: boolean;
+    };
+    group?: "cta" | "hero" | "media" | "navigation" | "form" | "utility" | "narrative" | "proof" | "listing" | undefined;
+}, {
+    name: string;
+    description: string;
+    content: {
+        fields: ContentFieldInput[];
+        variants?: {
+            name: string;
+            description: string;
+            whenToUse: string;
+        }[] | undefined;
+    };
+    category: "cta" | "data" | "section" | "hero" | "card" | "media" | "navigation" | "form" | "utility";
+    intent: string;
+    composition: {
+        placement: ["inline" | "page" | "section", ...("inline" | "page" | "section")[]];
+        maxPerPage?: number | null | undefined;
+        requiredSiblings?: string[] | undefined;
+        forbiddenAdjacent?: string[] | undefined;
+        allowedSlots?: Record<string, string[]> | undefined;
+    };
+    tokens: {
+        consumes: string[];
+        configurable?: {
+            prop: string;
+            tokenGroup: string;
+            allowedValues: string[];
+        }[] | undefined;
+    };
+    accessibility: {
+        screenReaderBehavior: string;
+        role?: string | undefined;
+        keyboardSupport?: string[] | undefined;
+        contentWarnings?: string[] | undefined;
+    };
+    examples: {
+        label: string;
+        intent: string;
+        storyId: string;
+    }[];
+    group?: "cta" | "hero" | "media" | "navigation" | "form" | "utility" | "narrative" | "proof" | "listing" | undefined;
+    antiExamples?: {
+        label: string;
+        why: string;
+        useInstead?: string | undefined;
+    }[] | undefined;
+    behavior?: {
+        fetchesData?: boolean | undefined;
+        hasClientState?: boolean | undefined;
+        animates?: boolean | undefined;
+        requiresAnalytics?: boolean | undefined;
+    } | undefined;
+}>;
+export type ComponentContract = z.infer<typeof ComponentContractSchema>;
+export type ComponentCategory = z.infer<typeof CategorySchema>;
+export type ComponentGroup = z.infer<typeof GroupSchema>;
+/**
+ * The shelf a component is filed under: its `group` when set, otherwise its
+ * `category`.
+ *
+ * Anything that groups components should call this rather than reading either
+ * field directly, so a design system part-way through adopting `group` groups
+ * consistently instead of half one way and half the other. It takes a
+ * structural type so it also accepts the looser component shapes consumers
+ * carry around, not only a fully parsed {@link ComponentContract}.
+ */
+export declare function groupOf(component: {
+    category: string;
+    group?: string | undefined;
+}): string;
+export type ComponentPlacement = z.infer<typeof PlacementSchema>;
+export type ContentFieldType = z.infer<typeof FieldTypeSchema>;
+export {};
+//# sourceMappingURL=schema.d.ts.map

package/dist/contract/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/contract/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,UAAU,CAAA;AAEvC,QAAA,MAAM,eAAe,4GAWnB,CAAA;AAEF,QAAA,MAAM,eAAe,0CAAwC,CAAA;AAE7D,QAAA,MAAM,cAAc,iGAUlB,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,QAAA,MAAM,WAAW,uGAUf,CAAA;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;IACrC,QAAQ,EAAE,OAAO,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAClC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC9B,EAAE,CAAC,EAAE,YAAY,EAAE,GAAG,SAAS,CAAA;CAChC,CAAA;AAED,iFAAiF;AACjF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;IACrC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC9B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAClC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC9B,EAAE,CAAC,EAAE,iBAAiB,EAAE,GAAG,SAAS,CAAA;CACrC,CAAA;AAqED,eAAO,MAAM,uBAAuB;;;IAIlC;;;;OAIG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgFH,CAAA;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AACvE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA;AAC9D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAA;AAExD;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,MAAM,CAE3F;AACD,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAChE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA"}

package/dist/contract/schema.js

@@ -0,0 +1,224 @@
+import { z } from 'zod';
+/**
+ * The current version of the contract schema. Bump this when making a
+ * backwards-incompatible change to the shape. Manifests declare the
+ * version they satisfy so the loader can reject mismatches loudly.
+ */
+export const CONTRACT_VERSION = '1.0.0';
+const FieldTypeSchema = z.enum([
+    'text',
+    'richtext',
+    'link',
+    'image',
+    'video',
+    'select',
+    'group',
+    'array',
+    'boolean',
+    'number',
+]);
+const PlacementSchema = z.enum(['page', 'section', 'inline']);
+const CategorySchema = z.enum([
+    'hero',
+    'section',
+    'card',
+    'media',
+    'cta',
+    'navigation',
+    'data',
+    'form',
+    'utility',
+]);
+/**
+ * Where an editor looks for a component, as distinct from what the component
+ * *is*.
+ *
+ * `category` answers the second question and several consumers reason about it
+ * as a kind. It is a poor answer to the first: a real design system files
+ * roughly half its library under `section`, so a picker grouped on `category`
+ * hands back the flat list the grouping was meant to avoid, while `card` and
+ * `navigation` hold one entry each. Redistributing within `category` to even
+ * the shelves out would file components under the wrong kind for every other
+ * consumer.
+ *
+ * So this is a second, optional field. The values are shelf labels, chosen to
+ * split the sections a `category` cannot:
+ *
+ * - `hero`       — page openers
+ * - `narrative`  — sections that explain, walk through, or tell
+ * - `proof`      — sections that evidence a claim: testimony, clients, results
+ * - `listing`    — collections of records, usually repeating
+ * - `media`      — image, video, audio, and their captions
+ * - `form`       — anything an editor thinks of as a form
+ * - `cta`        — asks
+ * - `navigation` — wayfinding within or across pages
+ * - `utility`    — structural or incidental
+ *
+ * There is deliberately no `section`: a shelf that holds half the library is
+ * the problem this field exists to solve. There is no `card` or `data` either
+ * — both name a kind rather than a place to look, and their contents belong on
+ * `listing` and `proof` respectively.
+ */
+const GroupSchema = z.enum([
+    'hero',
+    'narrative',
+    'proof',
+    'listing',
+    'media',
+    'form',
+    'cta',
+    'navigation',
+    'utility',
+]);
+const ContentFieldSchema = z.lazy(() => z.object({
+    name: z.string().min(1),
+    type: FieldTypeSchema,
+    required: z.boolean().default(false),
+    maxLength: z.number().int().positive().optional(),
+    /*
+    What the field holds before an author touches it, for `boolean` only.
+
+    A component's own default lives in its signature — `hasFacade = true` — and
+    is reachable only when the prop arrives as `undefined`. A generated CMS
+    field never leaves it undefined: a checkbox is stored ticked or unticked,
+    so the component is always handed an explicit value and its default can
+    never apply. Without somewhere to declare it, every boolean a contract
+    describes reaches the component as `false`, whatever the component says.
+
+    That inverted `VideoEmbed.hasFacade`, whose whole purpose is to keep a
+    provider's iframe and its third-party cookies off the page until a reader
+    presses play. The contract said "Leave on"; every embed an author added
+    shipped with it off.
+
+    Deliberately boolean-only. `text` and `number` defaults are a different
+    question — an empty string and a missing number are already meaningful, and
+    a default there competes with `required` rather than completing it. Widen
+    this when a component needs it, not before.
+    */
+    defaultValue: z.boolean().optional(),
+    /** Human-readable constraint description the AI reasons about. */
+    constraints: z.string().optional(),
+    /*
+    An optional field that most authors, and most compositions, should leave
+    empty: an override of a default the component already chooses well, or
+    screen-reader and status copy it already supplies. `VideoHero.pauseLabel`
+    is the shape of it — the control is already called "Pause background
+    video", and a field an author meets on every hero asking them to rename it
+    is noise between them and the heading.
+
+    A hint about attention, not about validity. The CMS draws such a field in a
+    collapsed section; an agent composing a page can skip it. It never makes a
+    field required or forbidden, and it is refused on a required field, which by
+    definition cannot be left alone.
+    */
+    advanced: z.boolean().optional(),
+    /** For array or group fields, the nested field shape. */
+    of: z.array(ContentFieldSchema).optional(),
+}).superRefine((field, ctx) => {
+    // Only `boolean` reads `defaultValue`, so anywhere else it is a value the
+    // author expects to take effect and nothing ever will. Rejecting it is the
+    // difference between a contract that fails validation and a field that
+    // quietly ignores half of what it was told.
+    if (field.advanced && field.required) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['advanced'],
+            message: `"${field.name}" is required, so it cannot be advanced: an author has to fill it in.`,
+        });
+    }
+    if (field.defaultValue !== undefined && field.type !== 'boolean') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['defaultValue'],
+            message: `defaultValue is only read for boolean fields; "${field.name}" is ${field.type}.`,
+        });
+    }
+}));
+export const ComponentContractSchema = z.object({
+    // Identity
+    name: z.string().min(1).regex(/^[A-Z][A-Za-z0-9]+$/, 'Component names must be PascalCase'),
+    category: CategorySchema,
+    /**
+     * The shelf an authoring UI files this component under. Optional: when it is
+     * absent, {@link groupOf} falls back to {@link category}, so a design system
+     * that sets none groups exactly as it did before this field existed.
+     */
+    group: GroupSchema.optional(),
+    description: z.string().min(20).max(280),
+    intent: z.string().min(20).max(500),
+    // Composition
+    composition: z.object({
+        placement: z.array(PlacementSchema).nonempty(),
+        maxPerPage: z.number().int().positive().nullable().default(null),
+        requiredSiblings: z.array(z.string()).default([]),
+        forbiddenAdjacent: z.array(z.string()).default([]),
+        allowedSlots: z.record(z.string(), z.array(z.string())).optional(),
+    }),
+    // Content
+    content: z.object({
+        fields: z.array(ContentFieldSchema),
+        variants: z
+            .array(z.object({
+            name: z.string(),
+            description: z.string(),
+            whenToUse: z.string(),
+        }))
+            .optional(),
+    }),
+    // Tokens
+    tokens: z.object({
+        consumes: z.array(z.string()),
+        configurable: z
+            .array(z.object({
+            prop: z.string(),
+            tokenGroup: z.string(),
+            allowedValues: z.array(z.string()),
+        }))
+            .optional(),
+    }),
+    // Accessibility
+    accessibility: z.object({
+        role: z.string().optional(),
+        keyboardSupport: z.array(z.string()).default([]),
+        screenReaderBehavior: z.string().min(10),
+        contentWarnings: z.array(z.string()).default([]),
+    }),
+    // Examples
+    examples: z
+        .array(z.object({
+        label: z.string(),
+        intent: z.string(),
+        storyId: z.string(),
+    }))
+        .min(1, 'Each component must have at least one example'),
+    antiExamples: z
+        .array(z.object({
+        label: z.string(),
+        why: z.string(),
+        useInstead: z.string().optional(),
+    }))
+        .default([]),
+    // Behavioral
+    behavior: z
+        .object({
+        fetchesData: z.boolean().default(false),
+        hasClientState: z.boolean().default(false),
+        animates: z.boolean().default(false),
+        requiresAnalytics: z.boolean().default(false),
+    })
+        .default({}),
+});
+/**
+ * The shelf a component is filed under: its `group` when set, otherwise its
+ * `category`.
+ *
+ * Anything that groups components should call this rather than reading either
+ * field directly, so a design system part-way through adopting `group` groups
+ * consistently instead of half one way and half the other. It takes a
+ * structural type so it also accepts the looser component shapes consumers
+ * carry around, not only a fully parsed {@link ComponentContract}.
+ */
+export function groupOf(component) {
+    return component.group ?? component.category;
+}
+//# sourceMappingURL=schema.js.map

package/dist/contract/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/contract/schema.ts"],"names":[],"mappings":"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"}

package/dist/generate/blocks.d.ts

@@ -0,0 +1,79 @@
+import type { Block } from 'payload';
+import type { Overrides } from '../overrides.js';
+import { type ContentField } from './fields.js';
+/** The slice of a manifest component entry the generator reads. */
+export interface ManifestComponent {
+    name: string;
+    category: string;
+    group?: string;
+    description: string;
+    intent: string;
+    composition: {
+        placement: string[];
+        maxPerPage: number | null;
+        requiredSiblings: string[];
+        forbiddenAdjacent: string[];
+        allowedSlots?: Record<string, string[]>;
+    };
+    content: {
+        fields: ContentField[];
+    };
+}
+export interface ManifestLike {
+    components: Record<string, ManifestComponent>;
+}
+export interface GenerateOptions {
+    manifest: ManifestLike;
+    overrides: Overrides;
+    mediaCollection: string;
+    linkCollections: string[];
+    resolveSelectOptions: (component: string, path: string) => readonly string[] | null;
+    resolveNamedOptions: (typeName: string) => readonly string[] | null;
+    /**
+     * The host's labels for option values whose meaning is particular to its
+     * design system — `{ 'text-image': 'Text and image' }`. Consulted before the
+     * generic words in `./labels.ts`, which cover heading levels, HTML elements
+     * and anything that reads well split into words.
+     */
+    optionLabels?: Readonly<Record<string, string>>;
+    /**
+     * A thumbnail for the block picker, or null for none.
+     *
+     * Payload draws a generic placeholder when a block has no `imageURL`, so a
+     * palette this size renders as dozens of identical grey mountains — worse
+     * than nothing, because the uniformity implies the images carry information.
+     */
+    resolvePreview?: (component: string) => {
+        url: string;
+        alt?: string;
+    } | null;
+}
+export interface GeneratedBlock {
+    block: Block;
+    component: ManifestComponent;
+}
+/**
+ * Which components are authorable as blocks.
+ *
+ * `inline` placement means the component is a building block used *inside*
+ * another one — a `Card` within a `CardGrid`, a `Button` within a CTA. It
+ * reaches the page through its parent's fields, so offering it in the palette
+ * would let an author drop a bare card onto a page with nothing around it.
+ *
+ * `page` and `section` are the two that stand on their own. `notABlock` in the
+ * overrides removes the handful that are page-level but not authored — the
+ * chrome a template renders rather than a block an author places.
+ */
+export declare function isBlockCandidate(component: ManifestComponent, overrides: Overrides): boolean;
+/**
+ * The block slug is the manifest component name, byte for byte.
+ *
+ * Not a stylistic choice. `@forumone/throughline/publishing`'s composition step maps
+ * `blockType` straight to `type` with no transformation and looks it up in the
+ * manifest; a miss is an `unknown-component` **error**, which blocks publish.
+ * Kebab-casing the slugs would make every block on every page unpublishable,
+ * and the error would point at the design system rather than at the naming.
+ */
+export declare function generateBlock(component: ManifestComponent, options: GenerateOptions): Block;
+export declare function generateBlocks(options: GenerateOptions): GeneratedBlock[];
+//# sourceMappingURL=blocks.d.ts.map

package/dist/generate/blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../src/generate/blocks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAS,MAAM,SAAS,CAAA;AAE3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAkB,KAAK,YAAY,EAAqB,MAAM,aAAa,CAAA;AAOlF,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE;QACX,SAAS,EAAE,MAAM,EAAE,CAAA;QACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;QACzB,gBAAgB,EAAE,MAAM,EAAE,CAAA;QAC1B,iBAAiB,EAAE,MAAM,EAAE,CAAA;QAC3B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;KACxC,CAAA;IACD,OAAO,EAAE;QAAE,MAAM,EAAE,YAAY,EAAE,CAAA;KAAE,CAAA;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAA;CAC9C;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,YAAY,CAAA;IACtB,SAAS,EAAE,SAAS,CAAA;IACpB,eAAe,EAAE,MAAM,CAAA;IACvB,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,oBAAoB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,GAAG,IAAI,CAAA;IACnF,mBAAmB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,GAAG,IAAI,CAAA;IACnE;;;;;OAKG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC/C;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CAC7E;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,KAAK,CAAA;IACZ,SAAS,EAAE,iBAAiB,CAAA;CAC7B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,iBAAiB,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAG5F;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,iBAAiB,EAAE,OAAO,EAAE,eAAe,GAAG,KAAK,CAwE3F;AAYD,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,cAAc,EAAE,CAKzE"}