@code0-tech/triangulum 0.37.0 → 0.37.2

package/dist/util/schema.util.d.ts

@@ -189,8 +189,42 @@ export interface DataInput extends Input {
  */
 export interface ListInput extends Input {
     input?: "list";
-    /** Schema or array of schemas for list items */
+    /**
+     * Schema or array of schemas for list items.
+     *
+     * In a parameter schema this is *value-driven*: once an array value is
+     * entered it holds exactly one entry per entered element, so it says what the
+     * list currently contains — not what an element may be. Use
+     * {@link ListInput.declaredItems} for the latter.
+     *
+     * An entered entry only ever *refines* one of the `declaredItems`: it is that
+     * option's input kind, properties and suggestions, with the concrete value's
+     * `type` and per-element cardinality filled in. A union element type is
+     * resolved to the member the entered element picked, so the COLOR entries of a
+     * `LIST<COLOR | OBJECT<…>>` stay color inputs and its object entries keep the
+     * declared object's property schemas.
+     */
     items?: Schema[];
+    /**
+     * The item schemas the *declared* element type produces — what `items` holds
+     * while no value is entered, and therefore the answer to "what may an element
+     * of this list be": its input kind, and the suggestions an element slot offers.
+     * A union element contributes one entry per member (e.g. all six methods of a
+     * `LIST<HTTP_METHOD>`), so the entries enumerate the element's options rather
+     * than the list's contents.
+     *
+     * Always present alongside `items` on an input slot's schema — an entered
+     * value can empty `items` (`[]`) or reduce it to the elements that happen to be
+     * there, and neither tells the UI what to render for a new element or which
+     * candidates the element slot accepts. An unconstrained element slot (a generic
+     * `LIST<T>`, or a list in a slot the declared type does not describe) yields a
+     * single generic entry carrying the "accepts anything" suggestion set.
+     *
+     * Omitted on schemas that describe a *produced* value rather than an input slot
+     * (a signature's return type, {@link getTypeSchema}); there `items` is already
+     * the declared expansion.
+     */
+    declaredItems?: Schema[];
 }
 /**
  * Represents a type input.
@@ -248,6 +282,36 @@ export declare const getSchema: (checker: ts.TypeChecker, node: ts.VariableDecla
  * {@link mergeSchemas}.
  */
 export declare const normalizeNodeSchema: (schema: Schema) => Schema;
+/**
+ * Strips `undefined` and `null` from a union type so the *declared* shape can be
+ * inspected. An optional parameter (or property) resolves to
+ * `<declared> | undefined`, and a union carries none of its members' type flags —
+ * so a test like "is this an object" or `checker.isArrayType` answers `false` for
+ * every optional slot unless the nullish part is removed first. A union that has
+ * more than one real member left is returned unchanged: there is no single
+ * declared shape to speak of then.
+ */
+export declare const nonNullishType: (type: ts.Type) => ts.Type;
+/**
+ * Sets a schema's `suggestions` to the given set, dropping the key entirely when
+ * the set is empty or missing. Suggestion-carrying schemas are built with the
+ * key always present (an empty array when nothing matched), whereas the rest of
+ * the pipeline omits it — so every schema that is spread into a result passes
+ * through here instead of relying on the spread.
+ */
+export declare const withSuggestions: <T extends Schema>(schema: T, suggestions: Input["suggestions"] | undefined) => T;
+/**
+ * A declared (function-side) schema kept as the answer for its position, because
+ * the node side has no counterpart to merge into it — e.g. a property the entered
+ * value does not carry, or a union-typed position whose members no longer line up.
+ *
+ * The declared schema already carries the suggestions of every level it
+ * describes; only a fully generic slot inside it is rewritten to the constant
+ * `any` set, which is what the merge itself would have produced for such a slot
+ * (see {@link genericNodeSchema}). Empty suggestion arrays are dropped so the
+ * result follows the same convention as every other schema.
+ */
+export declare const declaredSchema: (schema: Schema, anySuggestions?: Input["suggestions"]) => Schema;
 /**
  * Treats a node-side schema as sitting in a fully generic ("accepts anything")
  * slot: the declared type constrains nothing here, so the value keeps its shape
@@ -264,8 +328,37 @@ export declare const normalizeNodeSchema: (schema: Schema) => Schema;
  * type-parameter constraint — e.g. `keyof T` — so they are kept). Descendants are
  * always overridden regardless.
  */
+/**
+ * The declared element expansion of a list slot: the function-side `items`, each
+ * kept as the declared answer for its position (see {@link declaredSchema}). An
+ * element the declared type leaves unconstrained — a generic `LIST<T>`, or a list
+ * in a slot with no declared type at all — yields a single generic entry carrying
+ * the "accepts anything" set, which is what such an element slot accepts.
+ *
+ * This is what {@link ListInput.declaredItems} carries, and it never depends on the
+ * entered value.
+ */
+export declare const declaredItemsOf: (functionItems: Schema[] | undefined, anySuggestions?: Input["suggestions"]) => Schema[];
 export declare const genericNodeSchema: (schema: Schema, anySuggestions?: Input["suggestions"], overrideRoot?: boolean) => Schema;
 export declare const mergeSchemas: (functionSchema: Schema | undefined, nodeSchema: Schema, valueProvided?: boolean, anySuggestions?: Input["suggestions"], topLevel?: boolean) => Schema;
+/**
+ * Checks whether a union's members are the *options of one input* rather than
+ * alternative inputs: a string/number literal union (`'GET' | 'POST' | …`, which
+ * renders as a single select offering all of them) or `boolean` (internally the
+ * union `true | false`, which renders as a single boolean input).
+ *
+ * The distinction decides whether an entered value may narrow a union-typed slot
+ * to the single member it picked. For an options union it must not: narrowing
+ * `HTTP_METHOD` to the entered "GET" would hide the five other options of the
+ * very select the user is filling. For a union of alternative inputs
+ * (`COLOR | OBJECT<…>`, `TEXT | NUMBER`) it must: the member the value picked is
+ * the one input of the set that describes it, and it is also the entry the slot's
+ * {@link ListInput.declaredItems} already offers for it.
+ *
+ * @param type - The type to check
+ * @returns True if the type is a union whose members are options of one input
+ */
+export declare function isOptionsUnion(type: ts.Type): boolean;
 /**
  * Checks if a type is a callable type (has call signatures).
  *