@phis/contracts 0.4.0 → 0.5.0

package/dist/catalog.d.ts

@@ -1,3 +1,4 @@
+import { type PhiCmsAreaKey } from "./cms.js";
 /**
  * What a Module is for, as an operator reads it on the Modules page.
  *
@@ -64,6 +65,19 @@ export type PhisModulePackageEntry = {
      * asks at intake, where refusing costs the publisher a message rather than the operator a page.
      */
     category: string;
+    /**
+     * The Areas the Module may serve, and the only place a package states them.
+     *
+     * Here and not in the Module's definition, because the reader that needs them first cannot run the
+     * definition: `phis module` writes one Client projection per Area and must know, without loading a
+     * stranger's code, which packages' Client doors belong in which. A definition that stated them as
+     * well would be a second answer that can disagree with this one; the generated projection hands
+     * these to the definition instead.
+     *
+     * Membership, unlike the category: an Area is a place the Site renders, and one this build has no
+     * place for cannot be served at all.
+     */
+    eligibleAreas: PhiCmsAreaKey[];
 };
 /**
  * What a Module package says about itself, without being run.

package/dist/catalog.js

@@ -1,3 +1,4 @@
+import { isPhiCmsAreaKey } from "./cms.js";
 /**
  * What a Module is for, as an operator reads it on the Modules page.
  *
@@ -103,14 +104,25 @@ export function readPhisModulePackageDeclaration(packageJson) {
         if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
             throw new Error(`"${at}" must be an object.`);
         }
-        const { moduleId, category } = entry;
+        const { moduleId, category, eligibleAreas } = entry;
         if (typeof moduleId !== "string" || !moduleId.trim()) {
             throw new Error(`"${at}.moduleId" must be a non-empty string.`);
         }
         if (typeof category !== "string" || !category.trim()) {
             throw new Error(`"${at}.category" must be a non-empty string.`);
         }
-        return { moduleId, category };
+        if (!Array.isArray(eligibleAreas) || eligibleAreas.length === 0) {
+            throw new Error(`"${at}.eligibleAreas" must name at least one Area.`);
+        }
+        for (const area of eligibleAreas) {
+            if (!isPhiCmsAreaKey(area)) {
+                throw new Error(`"${at}.eligibleAreas" names "${String(area)}", which is not an Area.`);
+            }
+        }
+        if (new Set(eligibleAreas).size !== eligibleAreas.length) {
+            throw new Error(`"${at}.eligibleAreas" names an Area twice.`);
+        }
+        return { moduleId, category, eligibleAreas: [...eligibleAreas] };
     });
     return { sourceLocale: typeof sourceLocale === "string" ? sourceLocale : null, modules };
 }

package/dist/cms.d.ts

@@ -50,6 +50,17 @@ export type PhiCmsRegionTypeValue = (typeof PhiCmsRegionType)[keyof typeof PhiCm
  * Bits 2, 5 and 7 are unassigned. That is what makes the numbers worth stating once: 8 reads like the
  * fourth Area and is the third, and phi-server stores it as `area_id` where nothing spells it out.
  */
+/**
+ * The Areas a Site has, by name.
+ *
+ * The numbering below already lived here, because both sides store it and a renumbering neither of
+ * them noticed would put a Page in a different Area than it was written into. The names are the same
+ * agreement read the other way round and stood in two more copies -- one per repository -- so a Site
+ * that gained an Area would have had to gain it three times.
+ */
+export declare const PHI_CMS_AREA_KEYS: readonly ["public", "app", "admin", "builder", "editor", "accounting"];
+export type PhiCmsAreaKey = (typeof PHI_CMS_AREA_KEYS)[number];
+export declare function isPhiCmsAreaKey(value: unknown): value is PhiCmsAreaKey;
 export declare const PhiCmsVisibilityContext: {
     readonly PublicArea: number;
     readonly AppArea: number;

package/dist/cms.js

@@ -49,6 +49,26 @@ export const PhiCmsRegionType = {
  * Bits 2, 5 and 7 are unassigned. That is what makes the numbers worth stating once: 8 reads like the
  * fourth Area and is the third, and phi-server stores it as `area_id` where nothing spells it out.
  */
+/**
+ * The Areas a Site has, by name.
+ *
+ * The numbering below already lived here, because both sides store it and a renumbering neither of
+ * them noticed would put a Page in a different Area than it was written into. The names are the same
+ * agreement read the other way round and stood in two more copies -- one per repository -- so a Site
+ * that gained an Area would have had to gain it three times.
+ */
+export const PHI_CMS_AREA_KEYS = [
+    "public",
+    "app",
+    "admin",
+    "builder",
+    "editor",
+    "accounting",
+];
+const PHI_CMS_AREA_KEY_SET = new Set(PHI_CMS_AREA_KEYS);
+export function isPhiCmsAreaKey(value) {
+    return typeof value === "string" && PHI_CMS_AREA_KEY_SET.has(value);
+}
 export const PhiCmsVisibilityContext = {
     PublicArea: 1 << 0,
     AppArea: 1 << 1,

package/dist/conditions.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The grammar of a runtime condition: when a Widget shows, when a Form field is visible or disabled.
+ *
+ * Stored inside descriptors phis-server keeps, a Form's `visibleWhen` among them, so it is read here and
+ * read once -- the renderer evaluates what the server accepted, by the same rules.
+ */
+import { type PhiControllerSignalAddress, type PhiSignalAddress } from "./signals.js";
+/**
+ * Where a condition reads the value it judges.
+ *
+ * `row`, `form`, `controller` and `widget` are values the page produced: a record under the cursor, what
+ * has been typed, what a Controller holds, what a neighbouring Widget found out. `feature` is what this
+ * Site was configured to have -- a named fact a Module publishes about its own setup, such as whether a
+ * sign-in method is switched on, settled before anything renders and never seen by the browser. `page`
+ * is the one the visitor arrived with --
+ * the address of the page they opened, which is state as much as any of the others and the only kind
+ * that is already settled before the first Widget renders. A confirmation link carries its token there,
+ * an external login returns with its outcome there, and a Widget that should appear only for one of
+ * those can say so without a component of its own to read the query string.
+ */
+export declare const PHI_RUNTIME_CONDITION_SOURCES: readonly ["row", "form", "controller", "page", "widget", "feature"];
+export declare const PHI_RUNTIME_CONDITION_OPERATORS: readonly ["truthy", "falsy", "equals", "contains"];
+export declare const PHI_RUNTIME_CONDITION_GROUP_MATCHES: readonly ["all", "any"];
+export type PhiRuntimeConditionSource = (typeof PHI_RUNTIME_CONDITION_SOURCES)[number];
+export type PhiRuntimeConditionOperator = (typeof PHI_RUNTIME_CONDITION_OPERATORS)[number];
+export type PhiRuntimeConditionGroupMatch = (typeof PHI_RUNTIME_CONDITION_GROUP_MATCHES)[number];
+export type PhiRuntimeConditionValue = string;
+export type PhiRuntimeValueCondition = {
+    source: PhiRuntimeConditionSource;
+    controllerAddress?: PhiControllerSignalAddress;
+    /**
+     * Which Widget is being asked, for a `widget` condition.
+     *
+     * A Controller is state that outlives the Widgets reading it; a Widget reports only what it found out
+     * for itself. Both answer on the same channel, so a Widget beside another one -- a preview of what a
+     * link will do, next to the form that does it -- needs no Controller of its own to be composed with.
+     */
+    widgetAddress?: PhiSignalAddress;
+    valuePath: string;
+    operator: PhiRuntimeConditionOperator;
+    value?: PhiRuntimeConditionValue;
+    /**
+     * How to read a sender that has not said anything yet. Absent means "not matched".
+     *
+     * Hiding until told is right for a fact that is being fetched: a form that spends a confirmation link
+     * must not appear before the link has been checked. It is wrong for a state that only a later action
+     * can bring about -- nobody is halfway through a second authentication factor when the page opens, so
+     * a Widget standing back "while a step is under way" would stand back forever, waiting for a report
+     * that nothing is happening.
+     */
+    whenUnavailable?: PhiRuntimeConditionResult;
+    reason?: string;
+};
+export type PhiRuntimeConditionExpression = PhiRuntimeValueCondition | {
+    match: PhiRuntimeConditionGroupMatch;
+    conditions: readonly PhiRuntimeConditionExpression[];
+};
+export type PhiRuntimeConditionResult = "matched" | "not-matched" | "unavailable";
+/**
+ * The address of the page as the visitor opened it, which is what a `page` condition reads.
+ *
+ * A missing query parameter is an answer rather than a gap: `falsy` on `query.token` matches on the
+ * page without one, which is how a form with two stages knows which of them it is on.
+ */
+export type PhiRuntimePageConditionState = {
+    path: string;
+    query: Readonly<Record<string, string>>;
+};
+/**
+ * What the active Modules report about this Site's configuration, by namespaced name.
+ *
+ * A Module publishes these the way it publishes signal capabilities: deliberately, under a name it
+ * keeps. A condition reads `auth.password`, not a field of somebody's internal context, so renaming
+ * something inside a Module cannot silently change which Widgets a page shows.
+ */
+export type PhiRuntimeFeatureState = Readonly<Record<string, unknown>>;
+export type PhiRuntimeConditionSourceValues = {
+    row?: Record<string, unknown> | null;
+    features?: PhiRuntimeFeatureState | null;
+    form?: Record<string, unknown> | null;
+    controllers?: Readonly<Record<string, Record<string, unknown>>> | null;
+    /** Reported by Widgets, keyed by the address each one sends from. */
+    widgets?: Readonly<Record<string, Record<string, unknown>>> | null;
+    page?: PhiRuntimePageConditionState | null;
+};
+export type PhiRuntimeConditionStateSignalValue = {
+    state: Record<string, unknown>;
+};
+export declare function readPhiRuntimeValueCondition(value: unknown): PhiRuntimeValueCondition | null;
+export declare function readPhiRuntimeConditionExpression(value: unknown): PhiRuntimeConditionExpression | null;
+export declare function collectPhiRuntimeValueConditions(expression: PhiRuntimeConditionExpression | null | undefined): PhiRuntimeValueCondition[];
+export declare function combinePhiRuntimeConditionExpressions(match: PhiRuntimeConditionGroupMatch, expressions: readonly (PhiRuntimeConditionExpression | null | undefined)[]): PhiRuntimeConditionExpression | undefined;
+export declare function readPhiRuntimeConditionStateSignalValue(value: unknown): PhiRuntimeConditionStateSignalValue | null;
+export declare function readPhiRuntimeConditionValue(input: unknown, valuePath: string): unknown;
+export declare function matchesPhiRuntimeValueCondition(condition: PhiRuntimeValueCondition, sources: PhiRuntimeConditionSourceValues): boolean;
+export declare function evaluatePhiRuntimeConditionExpression(expression: PhiRuntimeConditionExpression, sources: PhiRuntimeConditionSourceValues): PhiRuntimeConditionResult;

package/dist/conditions.js

@@ -0,0 +1,163 @@
+/**
+ * The grammar of a runtime condition: when a Widget shows, when a Form field is visible or disabled.
+ *
+ * Stored inside descriptors phis-server keeps, a Form's `visibleWhen` among them, so it is read here and
+ * read once -- the renderer evaluates what the server accepted, by the same rules.
+ */
+import { readPhiControllerSignalAddress, readPhiSignalAddress, } from "./signals.js";
+import { isPhiRecord, readPhiDotPath } from "./record.js";
+/**
+ * Where a condition reads the value it judges.
+ *
+ * `row`, `form`, `controller` and `widget` are values the page produced: a record under the cursor, what
+ * has been typed, what a Controller holds, what a neighbouring Widget found out. `feature` is what this
+ * Site was configured to have -- a named fact a Module publishes about its own setup, such as whether a
+ * sign-in method is switched on, settled before anything renders and never seen by the browser. `page`
+ * is the one the visitor arrived with --
+ * the address of the page they opened, which is state as much as any of the others and the only kind
+ * that is already settled before the first Widget renders. A confirmation link carries its token there,
+ * an external login returns with its outcome there, and a Widget that should appear only for one of
+ * those can say so without a component of its own to read the query string.
+ */
+export const PHI_RUNTIME_CONDITION_SOURCES = ["row", "form", "controller", "page", "widget", "feature"];
+export const PHI_RUNTIME_CONDITION_OPERATORS = ["truthy", "falsy", "equals", "contains"];
+export const PHI_RUNTIME_CONDITION_GROUP_MATCHES = ["all", "any"];
+function readConditionValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function readConditionSource(value) {
+    return PHI_RUNTIME_CONDITION_SOURCES.includes(value)
+        ? value
+        : null;
+}
+export function readPhiRuntimeValueCondition(value) {
+    if (!isPhiRecord(value))
+        return null;
+    const source = readConditionSource(value.source);
+    const operator = value.operator === "truthy" || value.operator === "falsy" ||
+        value.operator === "equals" || value.operator === "contains"
+        ? value.operator
+        : null;
+    const valuePath = typeof value.valuePath === "string" ? value.valuePath.trim() : "";
+    const whenUnavailable = value.whenUnavailable === "matched" || value.whenUnavailable === "not-matched"
+        ? value.whenUnavailable
+        : undefined;
+    const controllerAddress = source === "controller"
+        ? readPhiControllerSignalAddress(value.controllerAddress)
+        : undefined;
+    const widgetAddress = source === "widget"
+        ? readPhiSignalAddress(value.widgetAddress)
+        : undefined;
+    const conditionValue = readConditionValue(value.value);
+    if (!source ||
+        !operator ||
+        !valuePath ||
+        (source === "controller" && !controllerAddress) ||
+        (source === "widget" && !widgetAddress) ||
+        (operator !== "truthy" && operator !== "falsy" && conditionValue === undefined)) {
+        return null;
+    }
+    return {
+        source,
+        controllerAddress,
+        widgetAddress,
+        valuePath,
+        operator,
+        whenUnavailable,
+        value: operator === "truthy" || operator === "falsy" ? undefined : conditionValue,
+        reason: typeof value.reason === "string" && value.reason.trim() ? value.reason.trim() : undefined,
+    };
+}
+export function readPhiRuntimeConditionExpression(value) {
+    const leaf = readPhiRuntimeValueCondition(value);
+    if (leaf)
+        return leaf;
+    if (!isPhiRecord(value) || (value.match !== "all" && value.match !== "any") || !Array.isArray(value.conditions)) {
+        return null;
+    }
+    const conditions = value.conditions.map(readPhiRuntimeConditionExpression);
+    if (conditions.length === 0 || conditions.some((condition) => condition == null)) {
+        return null;
+    }
+    return {
+        match: value.match,
+        conditions: conditions,
+    };
+}
+export function collectPhiRuntimeValueConditions(expression) {
+    if (!expression)
+        return [];
+    if ("source" in expression)
+        return [expression];
+    return expression.conditions.flatMap(collectPhiRuntimeValueConditions);
+}
+export function combinePhiRuntimeConditionExpressions(match, expressions) {
+    const conditions = expressions.filter((entry) => Boolean(entry));
+    if (conditions.length === 0)
+        return undefined;
+    if (conditions.length === 1)
+        return conditions[0];
+    return { match, conditions };
+}
+export function readPhiRuntimeConditionStateSignalValue(value) {
+    return isPhiRecord(value) && isPhiRecord(value.state) ? { state: value.state } : null;
+}
+export function readPhiRuntimeConditionValue(input, valuePath) {
+    return readPhiDotPath(input, valuePath);
+}
+function resolvePhiRuntimeConditionSource(condition, sources) {
+    if (condition.source === "row")
+        return sources.row ?? null;
+    if (condition.source === "form")
+        return sources.form ?? null;
+    if (condition.source === "page")
+        return sources.page ?? null;
+    if (condition.source === "feature")
+        return sources.features ?? null;
+    if (condition.source === "widget") {
+        return condition.widgetAddress ? sources.widgets?.[condition.widgetAddress] ?? null : null;
+    }
+    return condition.controllerAddress
+        ? sources.controllers?.[condition.controllerAddress] ?? null
+        : null;
+}
+export function matchesPhiRuntimeValueCondition(condition, sources) {
+    const source = resolvePhiRuntimeConditionSource(condition, sources);
+    if (source == null)
+        return false;
+    const current = readPhiRuntimeConditionValue(source, condition.valuePath);
+    if ((condition.source === "controller" || condition.source === "widget") && current === undefined)
+        return false;
+    if (condition.operator === "truthy")
+        return Boolean(current);
+    if (condition.operator === "falsy")
+        return !current;
+    if (condition.operator === "equals")
+        return Object.is(current, condition.value);
+    return Array.isArray(current)
+        ? current.some((entry) => typeof entry === "string" && entry === condition.value)
+        : typeof current === "string" && typeof condition.value === "string"
+            ? current.includes(condition.value)
+            : false;
+}
+export function evaluatePhiRuntimeConditionExpression(expression, sources) {
+    if ("source" in expression) {
+        const source = resolvePhiRuntimeConditionSource(expression, sources);
+        if (source == null)
+            return expression.whenUnavailable ?? "unavailable";
+        if ((expression.source === "controller" || expression.source === "widget") &&
+            readPhiRuntimeConditionValue(source, expression.valuePath) === undefined) {
+            return expression.whenUnavailable ?? "unavailable";
+        }
+        return matchesPhiRuntimeValueCondition(expression, sources) ? "matched" : "not-matched";
+    }
+    const results = expression.conditions.map((condition) => evaluatePhiRuntimeConditionExpression(condition, sources));
+    if (expression.match === "all") {
+        if (results.some((result) => result === "not-matched"))
+            return "not-matched";
+        return results.every((result) => result === "matched") ? "matched" : "unavailable";
+    }
+    if (results.some((result) => result === "matched"))
+        return "matched";
+    return results.every((result) => result === "not-matched") ? "not-matched" : "unavailable";
+}

package/dist/controls.d.ts

@@ -0,0 +1,83 @@
+/**
+ * What a choice control offers, and where it asks for its choices when they are not written out.
+ *
+ * Here because stored descriptors carry both: a Form field lists its options or names the provider
+ * that answers for them, and phis-server reads that field as it is stored.
+ */
+export type PhiRuntimeDataProviderKey = `${string}/${string}`;
+/**
+ * `<namespace>/<name>`: an identifier that says whose it is.
+ *
+ * Provider keys, item renderer keys and everything else a Module may contribute to a shared registry
+ * share this shape, so they share one check. A second spelling of it is the one that drifts.
+ */
+export declare function isPhiNamespacedRuntimeKey(value: unknown): value is `${string}/${string}`;
+export declare function isPhiRuntimeDataProviderKey(value: unknown): value is PhiRuntimeDataProviderKey;
+export type PhiControlOption<TValue extends string | number = string> = {
+    value: TValue;
+    label: string;
+    disabled?: boolean;
+    description?: string;
+    icon?: string;
+    preview?: PhiControlOptionPreview;
+    /**
+     * The heading this option is listed under, where the Control can group -- a Select shows consecutive
+     * options with the same group under one heading. A Control that cannot group lists the options as they
+     * come, so the order has to make sense without the headings.
+     */
+    group?: string;
+};
+export type PhiControlOptionPreview = PhiControlOptionBackgroundPreview | PhiControlOptionFontPreview;
+/**
+ * The option's label set in the typeface it names, so a list of fonts shows the fonts.
+ *
+ * `fontFamily` is a complete `font-family` value -- a family, its fallback, a generic -- because the
+ * option is drawn in a popup outside the page's root, where a variable that names a font is not in
+ * scope. Whoever builds the option resolves the variable first.
+ */
+export type PhiControlOptionFontPreview = {
+    kind: "font";
+    fontFamily: string;
+};
+export type PhiControlOptionBackgroundPreview = {
+    kind: "background";
+    backgroundColor?: string;
+    backgroundImage?: string;
+    backgroundSize?: string;
+    backgroundPosition?: string;
+    backgroundRepeat?: string;
+};
+export type PhiControlOptionsProviderLoadMode = "client" | "server" | "hybrid";
+export type PhiControlOptionsProviderSearchConfig = {
+    enabled?: boolean;
+    minChars?: number;
+};
+/**
+ * A value this provider needs that another field holds.
+ *
+ * `source` and `valuePath` are the vocabulary conditions already use, so "the value of a sibling field"
+ * is said the same way everywhere. `form` reads the live form values; `config` reads the field or Widget
+ * configuration the control was built from, which is what an Inspector has instead of a form.
+ *
+ * `required` is the difference between narrowing a list and having no list: a provider whose answer is
+ * meaningless without the parent value is not asked at all until it has one, rather than answering with
+ * everything and looking as if the dependency were ignored.
+ */
+export type PhiControlOptionsProviderDependency = {
+    /** The name the provider reads this value under. */
+    param: string;
+    source: "form" | "config";
+    valuePath: string;
+    required?: boolean;
+};
+export type PhiControlOptionsProviderConfig = {
+    providerKey: PhiRuntimeDataProviderKey;
+    scopeKey?: string;
+    area?: string;
+    params?: Record<string, unknown>;
+    loadMode?: PhiControlOptionsProviderLoadMode;
+    search?: PhiControlOptionsProviderSearchConfig;
+    dependencies?: readonly PhiControlOptionsProviderDependency[];
+};
+export declare function parsePhiControlOptionsProviderConfig(value: unknown): PhiControlOptionsProviderConfig | null;
+export declare function readPhiControlOptions(value: unknown): PhiControlOption[];

package/dist/controls.js

@@ -0,0 +1,133 @@
+/**
+ * What a choice control offers, and where it asks for its choices when they are not written out.
+ *
+ * Here because stored descriptors carry both: a Form field lists its options or names the provider
+ * that answers for them, and phis-server reads that field as it is stored.
+ */
+/**
+ * `<namespace>/<name>`: an identifier that says whose it is.
+ *
+ * Provider keys, item renderer keys and everything else a Module may contribute to a shared registry
+ * share this shape, so they share one check. A second spelling of it is the one that drifts.
+ */
+export function isPhiNamespacedRuntimeKey(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    const separatorIndex = value.lastIndexOf("/");
+    return separatorIndex > 0 && separatorIndex < value.length - 1;
+}
+export function isPhiRuntimeDataProviderKey(value) {
+    return isPhiNamespacedRuntimeKey(value);
+}
+function readString(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}
+function readRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function readLoadMode(value) {
+    return value === "client" || value === "server" || value === "hybrid" ? value : undefined;
+}
+function readSearchConfig(value) {
+    const record = readRecord(value);
+    if (!record) {
+        return undefined;
+    }
+    const enabled = typeof record.enabled === "boolean" ? record.enabled : undefined;
+    const minChars = typeof record.minChars === "number" && Number.isFinite(record.minChars)
+        ? Math.max(0, Math.trunc(record.minChars))
+        : undefined;
+    if (enabled === undefined && minChars === undefined) {
+        return undefined;
+    }
+    return {
+        enabled,
+        minChars,
+    };
+}
+function readDependencies(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const dependencies = value.flatMap((entry) => {
+        const record = readRecord(entry);
+        const param = readString(record?.param);
+        const valuePath = readString(record?.valuePath);
+        const source = record?.source === "form" || record?.source === "config" ? record.source : undefined;
+        if (!param || !valuePath || !source) {
+            return [];
+        }
+        return [{
+                param,
+                source,
+                valuePath,
+                required: record?.required === true ? true : undefined,
+            }];
+    });
+    return dependencies.length > 0 ? dependencies : undefined;
+}
+function readOptionPreview(value) {
+    const record = readRecord(value);
+    if (record?.kind === "font") {
+        const fontFamily = readString(record.fontFamily);
+        return fontFamily ? { kind: "font", fontFamily } : undefined;
+    }
+    if (record?.kind !== "background")
+        return undefined;
+    return {
+        kind: "background",
+        backgroundColor: readString(record.backgroundColor),
+        backgroundImage: readString(record.backgroundImage),
+        backgroundSize: readString(record.backgroundSize),
+        backgroundPosition: readString(record.backgroundPosition),
+        backgroundRepeat: readString(record.backgroundRepeat),
+    };
+}
+export function parsePhiControlOptionsProviderConfig(value) {
+    const record = readRecord(value);
+    if (!record) {
+        return null;
+    }
+    const providerKey = readString(record.providerKey);
+    if (!isPhiRuntimeDataProviderKey(providerKey)) {
+        return null;
+    }
+    return {
+        providerKey,
+        scopeKey: readString(record.scopeKey),
+        area: readString(record.area),
+        params: readRecord(record.params),
+        loadMode: readLoadMode(record.loadMode),
+        search: readSearchConfig(record.search),
+        dependencies: readDependencies(record.dependencies),
+    };
+}
+export function readPhiControlOptions(value) {
+    if (Array.isArray(value)) {
+        return value
+            .map((item) => {
+            if (!item || typeof item !== "object" || Array.isArray(item)) {
+                return null;
+            }
+            const record = item;
+            const optionValue = readString(record.value);
+            if (!optionValue) {
+                return null;
+            }
+            return {
+                value: optionValue,
+                label: readString(record.label) ?? optionValue,
+                disabled: typeof record.disabled === "boolean" ? record.disabled : undefined,
+                description: readString(record.description),
+                icon: readString(record.icon),
+                preview: readOptionPreview(record.preview),
+                group: readString(record.group),
+            };
+        })
+            .filter((item) => item != null);
+    }
+    return [];
+}