@tryghost/metafield-types 0.2.0 → 0.4.0

package/build/structure.d.ts

@@ -1,78 +1,302 @@
 /**
  * What a field type is made of, with no opinion on what a valid value looks like.
  *
- * This is the half of the catalog a renderer needs. Drawing an address means knowing
- * it has six parts, in that order, and that the last of them holds a country code —
- * nothing about lengths, formats, or what happens when one is left blank.
+ * Every type is composed from a few building blocks. A leaf is one value: text of a size, a
+ * choice from a list. A type is a leaf on its own, a record of named leaves, or a set of options its
+ * field offers. Everything that stores, exports, edits, filters or draws a value is written
+ * once per building block, so a type composed from existing blocks needs nothing beyond its entry
+ * here.
  *
- * It is separate from `./index` because that half is built out of zod, and zod is
- * sixty-odd kilobytes. Ghost's server enforces the rules and can afford them; Portal
- * only draws the inputs, and it loads on every page view of every themed site. Split
- * this way a renderer imports well under a kilobyte and still gets the types.
- *
- * The two halves cannot drift, because the schemas are built from these declarations
- * rather than beside them: adding a part here without a rule in `./index` fails to
- * compile.
+ * This half is separate from `./index` because that half is built out of zod, and zod is
+ * sixty-odd kilobytes. Ghost's server enforces the rules and can afford them; Portal only draws
+ * the inputs, and it loads on every page view of every themed site.
  */
-/** The source for the union type, the zod enum and the `FIELD_TYPES` keys alike. */
-export declare const FIELD_TYPE_IDS: readonly ['short_text', 'long_text', 'address'];
-export type FieldType = (typeof FIELD_TYPE_IDS)[number];
+/** How much text a text leaf holds. Each size has its bound, and its message, in `./index`. */
+export declare const TEXT_SIZES: readonly ['line', 'code', 'long'];
+export type TextSize = (typeof TEXT_SIZES)[number];
+/** The lists a choice can pick from. Each list says which keys it accepts in `./index`. */
+export declare const LIST_SOURCES: readonly ['countries'];
+export type ListSource = (typeof LIST_SOURCES)[number];
+export interface TextLeaf {
+    readonly leaf: 'text';
+    readonly size: TextSize;
+}
+export interface ChoiceLeaf {
+    readonly leaf: 'choice';
+    readonly from: ListSource;
+}
+/** One value. */
+export type Leaf = TextLeaf | ChoiceLeaf;
+export type LeafKind = Leaf['leaf'];
+/** What a value of each kind of leaf is, as JSON carries it. */
+export interface LeafValues {
+    text: string;
+    choice: string;
+}
+export type LeafValue<L extends Leaf> = LeafValues[L['leaf']];
+export declare const text: <const S extends TextSize>(size: S) => {
+    readonly leaf: 'text';
+    readonly size: S;
+};
+export declare const choice: <const F extends ListSource>(from: F) => {
+    readonly leaf: 'choice';
+    readonly from: F;
+};
+/** A country, as the two-letter code a list of countries offers. */
+export declare const country: {
+    readonly leaf: 'choice';
+    readonly from: "countries";
+};
+/** A type whose value is one leaf. */
+export interface ScalarStructure {
+    readonly shape: 'scalar';
+    readonly leaf: Leaf;
+}
 /**
- * What kind of thing a type's value is, as anything comparing values needs to know.
- *
- * Coarser than the type: `short_text` and `long_text` are both text, and differ only in
- * how much of it. This is the level at which a value can be ordered, matched or grouped,
- * so it is what a filter, a sort or an export reads to decide how to treat a value —
- * without either of them enumerating the types themselves.
- *
- * Deliberately not presentation: it says a value is a date, not that its operator is
- * called "is before". Naming the operators stays with whoever renders them.
+ * A type whose value is a leaf per named part. Parts are listed in the order they are shown, and
+ * that order is relied on wherever parts are laid out.
  */
-export declare const FIELD_KINDS: readonly ['text', 'date', 'number', 'record'];
-export type FieldKind = (typeof FIELD_KINDS)[number];
+export interface RecordStructure {
+    readonly shape: 'record';
+    readonly parts: Readonly<Record<string, Leaf>>;
+}
 /**
- * The types a composite's parts can declare. A country code and a postal code both
- * store short text, but they are different things — the part's type is what a control
- * or a filter dispatches on, the way a field's own type is for a scalar.
+ * A type whose value is some of the options its field offers, each named by its text. Which
+ * options there are, and whether a member picks one or several, are settings of the field rather
+ * than of its type, so each field asks a question of its own.
  */
-export declare const PART_TYPE_IDS: readonly ['short_text', 'postal_code', 'country_code'];
-export type PartType = (typeof PART_TYPE_IDS)[number];
+export interface SetStructure {
+    readonly shape: 'set';
+}
+export type FieldStructure = ScalarStructure | RecordStructure | SetStructure;
+export type FieldShape = FieldStructure['shape'];
+/** The source for the union type, the zod enum and the `FIELD_STRUCTURES` keys alike. */
+export declare const FIELD_TYPE_IDS: readonly ['short_text', 'long_text', 'list', 'address'];
+export type FieldType = (typeof FIELD_TYPE_IDS)[number];
 /**
- * Which parts each type has, in the order they are shown, and what each part holds.
- * `null` for a type whose value is a single thing.
+ * What each type is composed of.
  *
- * An address is a delivery address, modeled on Stripe's Address object. Who the parcel
- * is addressed to is not here: a parcel needs a name as well as an address, but that is
- * a fact about posting parcels rather than about either type, and the name is often not
- * the account name — gift subscriptions, workplace deliveries, c/o. A site that needs
- * one keeps it in a field of its own, which is also how Stripe hands it back.
- */
-export declare const FIELD_PARTS: {
-    readonly short_text: null;
-    readonly long_text: null;
+ * An address is a delivery address, modeled on Stripe's Address object. Who the parcel is
+ * addressed to is not here: a parcel needs a name as well as an address, but that is a fact about
+ * posting parcels rather than about either type, and the name is often not the account name, as
+ * with gift subscriptions, workplace deliveries or c/o. A site that needs one keeps it in a field of
+ * its own, which is also how Stripe hands it back.
+ */
+export declare const FIELD_STRUCTURES: {
+    readonly short_text: {
+        readonly shape: 'scalar';
+        readonly leaf: {
+            readonly leaf: 'text';
+            readonly size: "line";
+        };
+    };
+    readonly long_text: {
+        readonly shape: 'scalar';
+        readonly leaf: {
+            readonly leaf: 'text';
+            readonly size: "long";
+        };
+    };
+    readonly list: {
+        readonly shape: 'set';
+    };
     readonly address: {
-        readonly line1: 'short_text';
-        readonly line2: 'short_text';
-        readonly city: 'short_text';
-        readonly state: 'short_text';
-        readonly postal_code: 'postal_code';
-        readonly country: 'country_code';
+        readonly shape: 'record';
+        readonly parts: {
+            readonly line1: {
+                readonly leaf: 'text';
+                readonly size: "line";
+            };
+            readonly line2: {
+                readonly leaf: 'text';
+                readonly size: "line";
+            };
+            readonly city: {
+                readonly leaf: 'text';
+                readonly size: "line";
+            };
+            readonly state: {
+                readonly leaf: 'text';
+                readonly size: "line";
+            };
+            readonly postal_code: {
+                readonly leaf: 'text';
+                readonly size: "code";
+            };
+            readonly country: {
+                readonly leaf: 'choice';
+                readonly from: "countries";
+            };
+        };
     };
 };
+export type StructureOf<T extends FieldType> = (typeof FIELD_STRUCTURES)[T];
+export type ShapeOf<T extends FieldType> = StructureOf<T>['shape'];
+export type FieldTypeOfShape<S extends FieldShape> = {
+    [T in FieldType]: ShapeOf<T> extends S ? T : never;
+}[FieldType];
 /**
- * The parts a record type declares, or never for a type whose value is a single thing.
- *
- * Distributed over `T`, so a caller holding a type it only knows as `FieldType` gets
- * every part any type declares rather than the empty intersection of all of them.
+ * The parts a record type declares, or never for another shape. Distributes over `T`, so a union
+ * of types gives every part any of them declares.
  */
-export type PartsOf<T extends FieldType> = T extends FieldType ? (typeof FIELD_PARTS)[T] extends null ? never : Extract<keyof (typeof FIELD_PARTS)[T], string> : never;
+export type PartsOf<T extends FieldType> = T extends FieldType ? StructureOf<T> extends {
+    parts: infer P;
+} ? Extract<keyof P, string> : never : never;
+type ValueOfStructure<S extends FieldStructure> = {
+    scalar: S extends {
+        leaf: infer L extends Leaf;
+    } ? LeafValue<L> : never;
+    record: S extends {
+        parts: infer P;
+    } ? {
+        [K in keyof P]?: P[K] extends Leaf ? LeafValue<P[K]> : never;
+    } : never;
+    set: string[];
+}[S['shape']];
 /**
- * The parts of a record type in declaration order, or null for a type with none.
- *
- * Typed to the parts the caller's type declares, so a caller holding one of these can
- * index a value of that type without restating which parts exist.
+ * A value of a type, by its shape: one string for a scalar, a string for any of its declared parts
+ * for a record, and the text of each option picked for a set, even when its field takes only one.
+ * Every value is laid out this way, so storage, which keeps one string per leaf or option, can
+ * always read back what was written.
+ */
+export type ValueOf<T extends FieldType> = T extends FieldType ? ValueOfStructure<StructureOf<T>> : never;
+type WriteOfStructure<S extends FieldStructure> = {
+    scalar: ValueOfStructure<S>;
+    record: S extends {
+        parts: infer P;
+    } ? {
+        [K in keyof P]?: (P[K] extends Leaf ? LeafValue<P[K]> : never) | null;
+    } : never;
+    set: ValueOfStructure<S>;
+}[S['shape']];
+/**
+ * What a write gives a field of a type that still holds a value afterwards; `null` clears the
+ * whole field. As in JSON Merge Patch, a record's write names a part as `null` to clear it and
+ * leaves out a part to leave it alone, so a write is not a value: a value never holds `null`.
+ */
+export type WriteOf<T extends FieldType> = T extends FieldType ? WriteOfStructure<StructureOf<T>> : never;
+/**
+ * The keys a value has, typed as its type's keys rather than as strings, which is what
+ * `Object.keys` gives: a `for...in` over a value of a generic type gives each key as typed.
+ */
+export declare function keysOf<R extends object>(value: R): Extract<keyof R, string>[];
+/**
+ * What a field of a set type is set up with: the options it offers, in the order they are shown,
+ * and whether a member may pick more than one. An option is named by its text alone, so the same
+ * text is the same option whenever it is offered, and nothing else identifies one.
+ */
+export interface SetSettings {
+    readonly options: string[];
+    readonly multiple: boolean;
+}
+/** How many options a set field offers: at least two, or it isn't a choice, and at most a hundred. */
+export declare const MIN_OPTIONS = 2;
+export declare const MAX_OPTIONS = 100;
+/**
+ * What joins a member's options in one cell when a set is exported, and splits them when one is
+ * imported. No option may contain it, so a cell always splits back into what was joined. Chosen
+ * because it is rare in names and no spreadsheet splits columns on it by default.
+ */
+export declare const OPTION_SEPARATOR = "|";
+/**
+ * An option's text as it is matched: without surrounding spaces, and with accented letters
+ * encoded one way. Neither changes how the text reads, and without them an option pasted from a
+ * spreadsheet, or typed on a system that encodes accents differently, would not match one that
+ * reads exactly the same. Everything else is kept, case included, so an answer always reads as
+ * it was given.
+ */
+export declare function optionText(option: string): string;
+/**
+ * What two options are compared by to tell whether they are the same option: their text as
+ * `optionText` tidies it, without regard to case. A list offers each option once, so it can't
+ * offer both "Podcasts" and "podcasts". Lower-casing, upper-casing and lower-casing again also
+ * matches letters that one change of case keeps apart, such as "ß", "ẞ" and "SS", or a final "ς"
+ * and "σ", and does so the same way whatever the locale.
+ */
+export declare function optionKey(option: string): string;
+/** The answers among `held` that a set field offers, in the order it offers them. */
+export declare function inOptionOrder(settings: SetSettings, held: readonly unknown[]): string[];
+/**
+ * What a form editing a set field's answers starts from: only the options the field offers now,
+ * since one it no longer offers can't be picked again. A field that has gone from several answers
+ * to one starts unanswered while the member holds several, even if only one of them is still
+ * offered, so the next answer replaces them rather than one being shown as their only answer.
+ */
+export declare function editableAnswers(settings: SetSettings, held: readonly unknown[]): string[];
+/**
+ * What a field of each shape is set up with beyond its name: a set's options, and nothing for any
+ * other shape.
+ */
+export interface SettingsOfShape {
+    scalar: undefined;
+    record: undefined;
+    set: SetSettings;
+}
+export type SettingsOf<T extends FieldType> = T extends FieldType ? SettingsOfShape[ShapeOf<T>] : never;
+/** A field's settings, which a field whose type has nothing to set up doesn't have. */
+type SettingsField<S> = [S] extends [undefined] ? {
+    readonly settings?: undefined;
+} : {
+    readonly settings: S;
+};
+/**
+ * A field's type together with what the field is set up with. They are one value because only the
+ * two together say what the field takes: a list field without its options has no answers to
+ * offer, and a short text field has no settings at all.
+ */
+export type TypedSettings = {
+    [T in FieldType]: {
+        readonly type: T;
+    } & SettingsField<SettingsOf<T>>;
+}[FieldType];
+/** The fields among `F` whose type has shape `S`, with their settings narrowed to match. */
+export type FieldOfShape<S extends FieldShape, F extends TypedSettings = TypedSettings> = Extract<F, {
+    type: FieldTypeOfShape<S>;
+}>;
+/**
+ * Whether a value names a type this build knows. A site newer than an integration can send a type
+ * the integration doesn't know, so check a type from the wire with this first. `constructor` and
+ * other names every object has are not types.
+ */
+export declare function isFieldType(value: unknown): value is FieldType;
+export type ShapeHandlers<R> = {
+    [S in FieldShape]: (structure: Extract<FieldStructure, {
+        shape: S;
+    }>, type: FieldTypeOfShape<S>) => R;
+};
+/** Every type of shape `shape`, in catalog order. */
+export declare const typesOfShape: <S extends FieldShape>(shape: S) => FieldTypeOfShape<S>[];
+/**
+ * Calls the handler for the shape `type` declares, with the type narrowed to that shape. Throws,
+ * naming the type, for one this build doesn't know; check with `isFieldType` first.
+ */
+export declare function matchShape<R>(type: FieldType, handlers: ShapeHandlers<R>): R;
+export type FieldHandlers<F extends TypedSettings, R> = {
+    [S in FieldShape]: (field: FieldOfShape<S, F>) => R;
+};
+/**
+ * Calls the handler for the shape a field's type declares, with the field narrowed to that shape,
+ * settings included, for a caller that needs what the field is set up with rather than only its
+ * type. Throws, naming the type, for one this build doesn't know.
+ */
+export declare function matchField<F extends TypedSettings, R>(field: F, handlers: FieldHandlers<F, R>): R;
+export type LeafHandlers<R> = {
+    [K in LeafKind]: (leaf: Extract<Leaf, {
+        leaf: K;
+    }>) => R;
+};
+/** Calls the handler for a leaf's kind. */
+export declare function matchLeaf<R>(leaf: Leaf, handlers: LeafHandlers<R>): R;
+/**
+ * Whether a value is laid out as a record: an object of parts, which a list is not. What a record
+ * must hold is its type's rule to decide.
+ */
+export declare function isRecordValue(value: unknown): value is Record<string, unknown>;
+/**
+ * A record type's parts in declaration order, or null for any other type, including one this build
+ * doesn't know. Parts are plain strings here; `FIELD_STRUCTURES[type].parts` gives one type's parts
+ * with typed keys.
  */
-export declare function partsOf<T extends FieldType>(type: T): PartsOf<T>[] | null;
-/** Each part's declared type, keyed by part; null for a type with none, and for one this build has never heard of. */
-export declare function partTypesOf<T extends FieldType>(type: T): Record<PartsOf<T>, PartType> | null;
+export declare function partsOf(type: FieldType): string[] | null;
+export {};
 //# sourceMappingURL=structure.d.ts.map

package/build/structure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"structure.d.ts","sourceRoot":"","sources":["../src/structure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,oFAAoF;AACpF,eAAO,MAAM,cAAc,YAAI,YAAY,EAAE,WAAW,EAAE,SAAS,CAAU,CAAC;AAC9E,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,YAAI,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AACzE,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,aAAa,YAAI,YAAY,EAAE,aAAa,EAAE,cAAc,CAAU,CAAC;AACpF,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW;;;;iBAIpB,KAAK,EAAE,YAAY;iBACnB,KAAK,EAAE,YAAY;iBACnB,IAAI,EAAE,YAAY;iBAClB,KAAK,EAAE,YAAY;iBACnB,WAAW,EAAE,aAAa;iBAC1B,OAAO,EAAE,cAAc;;CAEsD,CAAC;AAElF;;;;;GAKG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,SAAS,IAAI,CAAC,SAAS,SAAS,GAC1D,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,GAClC,KAAK,GACL,OAAO,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,GAChD,KAAK,CAAC;AAEV;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAKzE;AAED,sHAAsH;AACtH,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,IAAI,CAG7F"}
+{"version":3,"file":"structure.d.ts","sourceRoot":"","sources":["../src/structure.ts"],"names":[],"mappings":"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"}

package/build/structure.js

@@ -1,76 +1,196 @@
 /**
  * What a field type is made of, with no opinion on what a valid value looks like.
  *
- * This is the half of the catalog a renderer needs. Drawing an address means knowing
- * it has six parts, in that order, and that the last of them holds a country code —
- * nothing about lengths, formats, or what happens when one is left blank.
+ * Every type is composed from a few building blocks. A leaf is one value: text of a size, a
+ * choice from a list. A type is a leaf on its own, a record of named leaves, or a set of options its
+ * field offers. Everything that stores, exports, edits, filters or draws a value is written
+ * once per building block, so a type composed from existing blocks needs nothing beyond its entry
+ * here.
  *
- * It is separate from `./index` because that half is built out of zod, and zod is
- * sixty-odd kilobytes. Ghost's server enforces the rules and can afford them; Portal
- * only draws the inputs, and it loads on every page view of every themed site. Split
- * this way a renderer imports well under a kilobyte and still gets the types.
- *
- * The two halves cannot drift, because the schemas are built from these declarations
- * rather than beside them: adding a part here without a rule in `./index` fails to
- * compile.
+ * This half is separate from `./index` because that half is built out of zod, and zod is
+ * sixty-odd kilobytes. Ghost's server enforces the rules and can afford them; Portal only draws
+ * the inputs, and it loads on every page view of every themed site.
  */
-/** The source for the union type, the zod enum and the `FIELD_TYPES` keys alike. */
-export const FIELD_TYPE_IDS = ['short_text', 'long_text', 'address'];
+/** How much text a text leaf holds. Each size has its bound, and its message, in `./index`. */
+export const TEXT_SIZES = ['line', 'code', 'long'];
+/** The lists a choice can pick from. Each list says which keys it accepts in `./index`. */
+export const LIST_SOURCES = ['countries'];
+export const text = (size) => ({ leaf: 'text', size });
+export const choice = (from) => ({ leaf: 'choice', from });
+/** A country, as the two-letter code a list of countries offers. */
+export const country = choice('countries');
+/** The source for the union type, the zod enum and the `FIELD_STRUCTURES` keys alike. */
+export const FIELD_TYPE_IDS = ['short_text', 'long_text', 'list', 'address'];
 /**
- * What kind of thing a type's value is, as anything comparing values needs to know.
- *
- * Coarser than the type: `short_text` and `long_text` are both text, and differ only in
- * how much of it. This is the level at which a value can be ordered, matched or grouped,
- * so it is what a filter, a sort or an export reads to decide how to treat a value —
- * without either of them enumerating the types themselves.
+ * What each type is composed of.
  *
- * Deliberately not presentation: it says a value is a date, not that its operator is
- * called "is before". Naming the operators stays with whoever renders them.
+ * An address is a delivery address, modeled on Stripe's Address object. Who the parcel is
+ * addressed to is not here: a parcel needs a name as well as an address, but that is a fact about
+ * posting parcels rather than about either type, and the name is often not the account name, as
+ * with gift subscriptions, workplace deliveries or c/o. A site that needs one keeps it in a field of
+ * its own, which is also how Stripe hands it back.
  */
-export const FIELD_KINDS = ['text', 'date', 'number', 'record'];
+export const FIELD_STRUCTURES = {
+    short_text: { shape: 'scalar', leaf: text('line') },
+    long_text: { shape: 'scalar', leaf: text('long') },
+    list: { shape: 'set' },
+    address: {
+        shape: 'record',
+        parts: {
+            line1: text('line'),
+            line2: text('line'),
+            city: text('line'),
+            state: text('line'),
+            postal_code: text('code'),
+            country,
+        },
+    },
+};
 /**
- * The types a composite's parts can declare. A country code and a postal code both
- * store short text, but they are different things — the part's type is what a control
- * or a filter dispatches on, the way a field's own type is for a scalar.
+ * The keys a value has, typed as its type's keys rather than as strings, which is what
+ * `Object.keys` gives: a `for...in` over a value of a generic type gives each key as typed.
  */
-export const PART_TYPE_IDS = ['short_text', 'postal_code', 'country_code'];
+export function keysOf(value) {
+    const keys = [];
+    for (const key in value) {
+        keys.push(key);
+    }
+    return keys;
+}
+/** How many options a set field offers: at least two, or it isn't a choice, and at most a hundred. */
+export const MIN_OPTIONS = 2;
+export const MAX_OPTIONS = 100;
 /**
- * Which parts each type has, in the order they are shown, and what each part holds.
- * `null` for a type whose value is a single thing.
- *
- * An address is a delivery address, modeled on Stripe's Address object. Who the parcel
- * is addressed to is not here: a parcel needs a name as well as an address, but that is
- * a fact about posting parcels rather than about either type, and the name is often not
- * the account name — gift subscriptions, workplace deliveries, c/o. A site that needs
- * one keeps it in a field of its own, which is also how Stripe hands it back.
+ * What joins a member's options in one cell when a set is exported, and splits them when one is
+ * imported. No option may contain it, so a cell always splits back into what was joined. Chosen
+ * because it is rare in names and no spreadsheet splits columns on it by default.
  */
-export const FIELD_PARTS = {
-    short_text: null,
-    long_text: null,
-    address: {
-        line1: 'short_text',
-        line2: 'short_text',
-        city: 'short_text',
-        state: 'short_text',
-        postal_code: 'postal_code',
-        country: 'country_code',
-    },
-};
+export const OPTION_SEPARATOR = '|';
 /**
- * The parts of a record type in declaration order, or null for a type with none.
- *
- * Typed to the parts the caller's type declares, so a caller holding one of these can
- * index a value of that type without restating which parts exist.
+ * An option's text as it is matched: without surrounding spaces, and with accented letters
+ * encoded one way. Neither changes how the text reads, and without them an option pasted from a
+ * spreadsheet, or typed on a system that encodes accents differently, would not match one that
+ * reads exactly the same. Everything else is kept, case included, so an answer always reads as
+ * it was given.
  */
-export function partsOf(type) {
-    // Optional because a caller built against an older catalog than the server it talks
-    // to reaches here with a type this build has never heard of, which reads as no parts.
-    const parts = FIELD_PARTS[type];
-    return parts ? Object.keys(parts) : null;
+export function optionText(option) {
+    return option.trim().normalize('NFC');
+}
+/**
+ * What two options are compared by to tell whether they are the same option: their text as
+ * `optionText` tidies it, without regard to case. A list offers each option once, so it can't
+ * offer both "Podcasts" and "podcasts". Lower-casing, upper-casing and lower-casing again also
+ * matches letters that one change of case keeps apart, such as "ß", "ẞ" and "SS", or a final "ς"
+ * and "σ", and does so the same way whatever the locale.
+ */
+export function optionKey(option) {
+    return optionText(option).toLowerCase().toUpperCase().toLowerCase();
+}
+/** The answers among `held` that a set field offers, in the order it offers them. */
+export function inOptionOrder(settings, held) {
+    return settings.options.filter((option) => held.includes(option));
+}
+/**
+ * What a form editing a set field's answers starts from: only the options the field offers now,
+ * since one it no longer offers can't be picked again. A field that has gone from several answers
+ * to one starts unanswered while the member holds several, even if only one of them is still
+ * offered, so the next answer replaces them rather than one being shown as their only answer.
+ */
+export function editableAnswers(settings, held) {
+    return !settings.multiple && held.length > 1 ? [] : inOptionOrder(settings, held);
 }
-/** Each part's declared type, keyed by part; null for a type with none, and for one this build has never heard of. */
-export function partTypesOf(type) {
-    const parts = FIELD_PARTS[type];
-    return parts ? { ...parts } : null;
+/**
+ * Whether a value names a type this build knows. A site newer than an integration can send a type
+ * the integration doesn't know, so check a type from the wire with this first. `constructor` and
+ * other names every object has are not types.
+ */
+export function isFieldType(value) {
+    return FIELD_TYPE_IDS.some((id) => id === value);
+}
+const hasShape = (shape) => (type) => isFieldType(type) && FIELD_STRUCTURES[type].shape === shape;
+const isScalarType = hasShape('scalar');
+const isRecordType = hasShape('record');
+const isSetType = hasShape('set');
+/** Every type of shape `shape`, in catalog order. */
+export const typesOfShape = (shape) => FIELD_TYPE_IDS.filter(hasShape(shape));
+/**
+ * Calls the handler for the shape `type` declares, with the type narrowed to that shape. Throws,
+ * naming the type, for one this build doesn't know; check with `isFieldType` first.
+ */
+export function matchShape(type, handlers) {
+    if (isScalarType(type)) {
+        return handlers.scalar(FIELD_STRUCTURES[type], type);
+    }
+    if (isRecordType(type)) {
+        return handlers.record(FIELD_STRUCTURES[type], type);
+    }
+    if (isSetType(type)) {
+        return handlers.set(FIELD_STRUCTURES[type], type);
+    }
+    return unknownType(type);
+}
+const fieldHasShape = (shape) => (field) => hasShape(shape)(field.type);
+const isScalarField = fieldHasShape('scalar');
+const isRecordField = fieldHasShape('record');
+const isSetField = fieldHasShape('set');
+/**
+ * Calls the handler for the shape a field's type declares, with the field narrowed to that shape,
+ * settings included, for a caller that needs what the field is set up with rather than only its
+ * type. Throws, naming the type, for one this build doesn't know.
+ */
+export function matchField(field, handlers) {
+    if (isScalarField(field)) {
+        return handlers.scalar(field);
+    }
+    if (isRecordField(field)) {
+        return handlers.record(field);
+    }
+    if (isSetField(field)) {
+        return handlers.set(field);
+    }
+    // A type this build doesn't know, which a plain JavaScript caller can still pass. The guards
+    // above can't narrow a generic field to never, so this can't be `unknownType`.
+    // oxlint-disable-next-line ghost/ghost-custom/no-native-error
+    throw new Error(`Unknown field type: ${String(field.type)}`);
+}
+/**
+ * Every shape has a branch above, so only a type this build doesn't know, which a plain
+ * JavaScript caller can still pass, reaches here.
+ */
+function unknownType(type) {
+    // A native error, because this module imports nothing, @tryghost/errors included.
+    // oxlint-disable-next-line ghost/ghost-custom/no-native-error
+    throw new Error(`Unknown field type: ${String(type)}`);
+}
+/** Calls the handler for a leaf's kind. */
+export function matchLeaf(leaf, handlers) {
+    switch (leaf.leaf) {
+        case 'text':
+            return handlers.text(leaf);
+        case 'choice':
+            return handlers.choice(leaf);
+    }
+}
+/**
+ * Whether a value is laid out as a record: an object of parts, which a list is not. What a record
+ * must hold is its type's rule to decide.
+ */
+export function isRecordValue(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * A record type's parts in declaration order, or null for any other type, including one this build
+ * doesn't know. Parts are plain strings here; `FIELD_STRUCTURES[type].parts` gives one type's parts
+ * with typed keys.
+ */
+export function partsOf(type) {
+    if (!isFieldType(type)) {
+        return null;
+    }
+    return matchShape(type, {
+        scalar: () => null,
+        record: ({ parts }) => Object.keys(parts),
+        set: () => null,
+    });
 }
 //# sourceMappingURL=structure.js.map