@aleph-alpha/settings-kit 0.1.0 → 1.0.0

package/dist/composables/useSettingsLayout/useSettingsLayout.d.ts

@@ -0,0 +1,71 @@
+import type { ComputedRef, MaybeRefOrGetter } from 'vue';
+import { type LayoutIssue, type LayoutNavigationNode, type ResolvedLayout, type ResolvedPage, type SettingsLayout } from '../../core/layout';
+import type { SettingField, StandardSchemaV1, StateManager } from '../../core/types';
+import type { UseFieldValidatorReturn } from '../useFieldValidator/useFieldValidator';
+import type { SettingsLocale } from '../useSettingsLocale/useSettingsLocale';
+/** Options for `useSettingsLayout`. */
+export interface UseSettingsLayoutOptions {
+    /** Where each setting renders. */
+    layout: MaybeRefOrGetter<SettingsLayout>;
+    /**
+     * The state manager to read fields and values from and to stage edits in.
+     * Omitted, the nearest `useSettingsForm` session is used; without one, a
+     * private manager is created from `fields`.
+     */
+    session?: StateManager;
+    /**
+     * Field descriptors. With a private manager they are its `fields`; with a
+     * host session each one is registered into it, so the layout resolves and
+     * rules evaluate before any field mounts. Fields the session already
+     * declares win.
+     */
+    fields?: MaybeRefOrGetter<SettingField[] | undefined>;
+    /** External validators per setting key (any Standard Schema). */
+    validators?: Record<string, StandardSchemaV1>;
+    /**
+     * Locale context for labels and validation wording. Omitted, the nearest
+     * `provideSettingsLocale` is used. `inject` does not see a `provide` in
+     * the same component. If one component provides and calls this
+     * composable, pass the value that `provideSettingsLocale` returns.
+     */
+    settingsLocale?: SettingsLocale;
+}
+/** What `useSettingsLayout` returns. */
+export interface SettingsLayoutModel {
+    /** The state manager in use; also provided to descendant fields. */
+    session: StateManager;
+    /** The resolved tree: ordered, rule-filtered, with unique ids. */
+    resolved: ComputedRef<ResolvedLayout>;
+    /** Every page in display order. */
+    pages: ComputedRef<ResolvedPage[]>;
+    /** Categories > pages, with `invalid` marks from the shown errors. */
+    navigation: ComputedRef<LayoutNavigationNode[]>;
+    /** Page by id (`<category>/<page>`). */
+    page: (id: string | undefined) => ResolvedPage | undefined;
+    /** Layout problems against the known fields (see `validateLayout`). */
+    issues: ComputedRef<LayoutIssue[]>;
+    /** Fields that are placed and currently visible: what gets validated. */
+    fields: ComputedRef<SettingField[]>;
+    /** Validation of the visible fields against the session's values. */
+    validator: UseFieldValidatorReturn;
+    /**
+     * Errors to display: server issues always; client issues once the setting
+     * is dirty or after `revealErrors()`.
+     */
+    errorsByKey: ComputedRef<Record<string, string[]>>;
+    /** Shows every client error, e.g. after a failed apply. */
+    revealErrors: () => void;
+    /** Back to showing client errors on dirty settings only. */
+    resetErrors: () => void;
+}
+/**
+ * Headless layout model. Resolves the layout against the state manager —
+ * fields from `session.fieldByKey`, rule values from `session.valueOf` — so
+ * the tree, navigation and validation follow every staged edit. Renders
+ * nothing; `SkLayout` and `SkShell` are built on it.
+ *
+ * Provides the session to its descendants, so every
+ * `SkField` rendered below stages edits in the same manager.
+ */
+export declare function useSettingsLayout(options: UseSettingsLayoutOptions): SettingsLayoutModel;
+//# sourceMappingURL=useSettingsLayout.d.ts.map

package/dist/composables/useSettingsLayout/useSettingsLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSettingsLayout.d.ts","sourceRoot":"","sources":["../../../src/composables/useSettingsLayout/useSettingsLayout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,KAAK,CAAC;AAEzD,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACb,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AAMtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAI7E,uCAAuC;AACvC,MAAM,WAAW,wBAAwB;IACvC,kCAAkC;IAClC,MAAM,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC;IACzC;;;;OAIG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC,YAAY,EAAE,GAAG,SAAS,CAAC,CAAC;IACtD,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC9C;;;;;OAKG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,OAAO,EAAE,YAAY,CAAC;IACtB,kEAAkE;IAClE,QAAQ,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC;IACtC,mCAAmC;IACnC,KAAK,EAAE,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC;IACnC,sEAAsE;IACtE,UAAU,EAAE,WAAW,CAAC,oBAAoB,EAAE,CAAC,CAAC;IAChD,wCAAwC;IACxC,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,KAAK,YAAY,GAAG,SAAS,CAAC;IAC3D,uEAAuE;IACvE,MAAM,EAAE,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC;IACnC,yEAAyE;IACzE,MAAM,EAAE,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC;IACpC,qEAAqE;IACrE,SAAS,EAAE,uBAAuB,CAAC;IACnC;;;OAGG;IACH,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IACnD,2DAA2D;IAC3D,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAChC,mBAAmB,CA8FrB"}

package/dist/composables/useSettingsLocale/useSettingsLocale.d.ts

@@ -0,0 +1,38 @@
+import type { ComputedRef, InjectionKey, MaybeRefOrGetter } from 'vue';
+import type { KitMessageKey, KitMessageOverrides } from '../../core';
+import type { LocalizedText } from '../../core/types';
+/** What the application passes to `provideSettingsLocale`. */
+export interface SettingsLocaleOptions {
+    /** Language of the admin. Defaults to `'en'`. */
+    locale?: MaybeRefOrGetter<string>;
+    /** Used when `locale` has no translation. */
+    fallbackLocale?: MaybeRefOrGetter<string | undefined>;
+    /** Replaces kit wording per key. Pass every key to replace all of it. */
+    messages?: MaybeRefOrGetter<KitMessageOverrides | undefined>;
+}
+/** What `useSettingsLocale` hands back. */
+export interface SettingsLocale {
+    locale: ComputedRef<string>;
+    fallbackLocale: ComputedRef<string | undefined>;
+    /** Replacement wording from the application, if any. */
+    messages: ComputedRef<KitMessageOverrides | undefined>;
+    /** Resolves schema text with the locale chain. */
+    resolveText: (text: LocalizedText) => string;
+    /** Resolves wording owned by the kit. */
+    message: (key: KitMessageKey, params?: Record<string, string | number>) => string;
+}
+/** Injection key fields use to find the locale settings. */
+export declare const settingsLocaleKey: InjectionKey<SettingsLocale>;
+/**
+ * Sets the locale for all fields below the calling component, and returns it.
+ * An option you leave out comes from the parent provider. Messages merge
+ * with the parent messages per locale, and your own win.
+ *
+ * Inject does not see a provide in the same component. To use the locale in
+ * this component, for example with `useFieldValidator`, pass the same refs
+ * to that composable as options.
+ */
+export declare function provideSettingsLocale(options?: SettingsLocaleOptions): SettingsLocale;
+/** The nearest provided locale. Without a provider it uses the kit defaults. */
+export declare function useSettingsLocale(): SettingsLocale;
+//# sourceMappingURL=useSettingsLocale.d.ts.map

package/dist/composables/useSettingsLocale/useSettingsLocale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSettingsLocale.d.ts","sourceRoot":"","sources":["../../../src/composables/useSettingsLocale/useSettingsLocale.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,KAAK,CAAC;AAGvE,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAMrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,MAAM,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAClC,6CAA6C;IAC7C,cAAc,CAAC,EAAE,gBAAgB,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACtD,yEAAyE;IACzE,QAAQ,CAAC,EAAE,gBAAgB,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAAC;CAC9D;AAED,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5B,cAAc,EAAE,WAAW,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAChD,wDAAwD;IACxD,QAAQ,EAAE,WAAW,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAAC;IACvD,kDAAkD;IAClD,WAAW,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,MAAM,CAAC;IAC7C,yCAAyC;IACzC,OAAO,EAAE,CACP,GAAG,EAAE,aAAa,EAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KACrC,MAAM,CAAC;CACb;AAED,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,EAAE,YAAY,CAAC,cAAc,CAChC,CAAC;AAuB5B;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,qBAA0B,GAClC,cAAc,CAoBhB;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,IAAI,cAAc,CAKlD"}

package/dist/composables/useStateManager/useStateManager.d.ts

@@ -0,0 +1,10 @@
+import type { StateManager, StateManagerOptions } from '../../core/types';
+/**
+ * Headless state manager behind `useSettingsForm`. Owns every field's
+ * unsaved work, baseline and save status, resolves inheritance, and batches
+ * saves. Nothing here needs a component.
+ */
+export declare function createStateManager(options?: StateManagerOptions): StateManager;
+/** `createStateManager` under the Vue naming convention, for use inside `setup()`. */
+export declare function useStateManager(options?: StateManagerOptions): StateManager;
+//# sourceMappingURL=useStateManager.d.ts.map

package/dist/composables/useStateManager/useStateManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStateManager.d.ts","sourceRoot":"","sources":["../../../src/composables/useStateManager/useStateManager.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAOV,YAAY,EACZ,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AA+B1B;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,mBAAwB,GAChC,YAAY,CA2ad;AAED,sFAAsF;AACtF,wBAAgB,eAAe,CAC7B,OAAO,GAAE,mBAAwB,GAChC,YAAY,CAEd"}

package/dist/core/controls/controlDefinitions.d.ts

@@ -0,0 +1,33 @@
+import { type Component } from 'vue';
+import type { SettingField } from '../types';
+/** Locale-resolved schema data a control's prop mapper can draw from. */
+export interface ControlPropsContext {
+    /** Field label resolved for the active locale. */
+    label: string;
+    /** Field description resolved for the active locale. */
+    tooltip?: string;
+}
+/**
+ * What a control emits. `input` controls edit a value and fire
+ * `update:modelValue`/`change`; `button` controls hold no value and fire
+ * `action` with the pressed option's method.
+ */
+export type ControlKind = 'input' | 'button';
+/**
+ * Internal schema of one control: the component the factory produces, what
+ * kind of events it emits, and how schema data maps to the control's props.
+ * Every control extends the base contract in `../core`, so all entries also
+ * accept the same shared attrs.
+ */
+export interface ControlDefinition {
+    component: Component;
+    /** Decides which listeners `SkField` attaches to the control. */
+    kind: ControlKind;
+    /** Maps schema data to the control's own props. */
+    props: (field: SettingField, context: ControlPropsContext) => Record<string, unknown>;
+}
+/** Built-in map from `presentation.control` to that control's definition. */
+export declare const controlDefinitions: Record<string, ControlDefinition>;
+/** Definition used when a control has no dedicated entry in the map. */
+export declare const fallbackDefinition: ControlDefinition;
+//# sourceMappingURL=controlDefinitions.d.ts.map

package/dist/core/controls/controlDefinitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controlDefinitions.d.ts","sourceRoot":"","sources":["../../../src/core/controls/controlDefinitions.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,SAAS,EAAE,MAAM,KAAK,CAAC;AAI9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,yEAAyE;AACzE,MAAM,WAAW,mBAAmB;IAClC,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,SAAS,CAAC;IACrB,iEAAiE;IACjE,IAAI,EAAE,WAAW,CAAC;IAClB,mDAAmD;IACnD,KAAK,EAAE,CACL,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,mBAAmB,KACzB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAqCD,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAqFhE,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,EAAE,iBAOhC,CAAC"}

package/dist/core/controls/index.d.ts

@@ -0,0 +1,26 @@
+import type { Component, InjectionKey } from 'vue';
+import { type ControlDefinition } from './controlDefinitions';
+import type { SettingField, SettingFieldControl } from '../types';
+export type { ControlDefinition, ControlKind, ControlPropsContext, } from './controlDefinitions';
+/** Control definitions by `presentation.control` name. */
+export type ControlRegistry = Readonly<Record<string, ControlDefinition>>;
+/** Injection key for the control registry fields resolve against. */
+export declare const skControlRegistryKey: InjectionKey<ControlRegistry>;
+/**
+ * Adds or replaces controls for every field below the caller. Entries merge
+ * over the nearest provided registry (the built-ins at the top), so a
+ * custom `presentation.control` name renders the component given here.
+ */
+export declare function provideControls(definitions: Record<string, ControlDefinition>): ControlRegistry;
+/** The nearest provided registry, else the built-in controls. */
+export declare function useControlRegistry(): ControlRegistry;
+/** The control a field renders: `presentation.control` or the type default. */
+export declare function resolveFieldControl(field: SettingField): SettingFieldControl | undefined;
+/**
+ * The control definition for a field from `registry` (the built-ins by
+ * default), else the unsupported fallback.
+ */
+export declare function resolveControlDefinition(field: SettingField, registry?: ControlRegistry): ControlDefinition;
+/** The input component a field renders with the built-in controls. */
+export declare function createFieldInput(field: SettingField): Component;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/controls/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/controls/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,KAAK,CAAC;AAEnD,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EAEpB,MAAM,UAAU,CAAC;AAElB,YAAY,EACV,iBAAiB,EACjB,WAAW,EACX,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAE9B,0DAA0D;AAC1D,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAE1E,qEAAqE;AACrE,eAAO,MAAM,oBAAoB,EAAE,YAAY,CAAC,eAAe,CAE9D,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAC7C,eAAe,CAIjB;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,IAAI,eAAe,CAKpD;AAaD,+EAA+E;AAC/E,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,YAAY,GAClB,mBAAmB,GAAG,SAAS,CAEjC;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,YAAY,EACnB,QAAQ,GAAE,eAAoC,GAC7C,iBAAiB,CAGnB;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,CAE/D"}

package/dist/core/index.d.ts

@@ -0,0 +1,18 @@
+export { skBaseControlDefaults, skPeriodUnits } from './utils/consts';
+export type { SkPeriodUnit } from './utils/consts';
+export { skA11yAttrs, skDescriptionId, skErrorId, useA11yAttrs, } from './utils/a11y';
+export { useName } from './utils/useName';
+export { skCastModelValue } from './utils/cast';
+export type { SkModelCastModifiers } from './utils/cast';
+export { resolveLocalizedText } from './utils/localizedText';
+export { resolveKitMessage } from './utils/kitMessages';
+export type { KitMessageKey, KitMessageOverrides } from './utils/kitMessages';
+export type { A11yAttrName, A11yAttrs } from './utils/a11y';
+export { useControlModel } from './useControlModel';
+export { evaluateCondition, evaluateFieldRules, evaluateRuleStates, validateFieldRules, } from './validate/rules';
+export type { SettingFieldRuleState } from './validate/rules';
+export { checkFieldConstraints, resolveConstraintMessage, } from './validate/constraints';
+export { byOrder, keysOf, layoutIdSegment, layoutPageId, resolveLayout, toNavigation, validateLayout, } from './layout';
+export type * from './layout';
+export type * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACtE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EACL,WAAW,EACX,eAAe,EACf,SAAS,EACT,YAAY,GACb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EACL,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,OAAO,EACP,MAAM,EACN,eAAe,EACf,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,cAAc,GACf,MAAM,UAAU,CAAC;AAClB,mBAAmB,UAAU,CAAC;AAC9B,mBAAmB,SAAS,CAAC"}

package/dist/core/layout/index.d.ts

@@ -0,0 +1,8 @@
+export type * from './types';
+export { byOrder, layoutIdSegment, layoutPageId, resolveLayout, } from './resolve';
+export type { ResolveLayoutOptions, ResolveLayoutSource } from './resolve';
+export { keysOf, toNavigation } from './navigation';
+export type { LayoutNavigationNode, LayoutNavigationOptions, } from './navigation';
+export { validateLayout } from './validate';
+export type { LayoutIssue, LayoutIssueCode } from './validate';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/layout/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/layout/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,SAAS,CAAC;AAC7B,OAAO,EACL,OAAO,EACP,eAAe,EACf,YAAY,EACZ,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACpD,YAAY,EACV,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/core/layout/navigation.d.ts

@@ -0,0 +1,33 @@
+import type { LayoutNodeKind, ResolvedLayout, ResolvedPage } from './types';
+/** One entry of the navigation outline. */
+export interface LayoutNavigationNode {
+    /** The resolved node's unique `id`. */
+    id: string;
+    kind: LayoutNodeKind;
+    label: string;
+    /** Route path, on page nodes only. */
+    path?: string;
+    /** Whether a visible setting below this node currently has errors. */
+    invalid: boolean;
+    children: LayoutNavigationNode[];
+}
+/** Options for `toNavigation`. */
+export interface LayoutNavigationOptions {
+    /** Deepest level in the outline. Defaults to `page`. */
+    depth?: 'page' | 'item';
+    /** Locale for item labels. Defaults to `en`. */
+    locale?: string;
+    /** Used when `locale` has no translation. Then `en`, then any translation. */
+    fallbackLocale?: string;
+    /** Whether a setting key currently has errors; marks `invalid` up the tree. */
+    isInvalid?: (key: string) => boolean;
+}
+/**
+ * The navigation outline of a resolved layout: categories > pages, and with
+ * `depth: 'item'` down to the settings. Only what the resolver kept appears;
+ * an unlabelled section or group hands its children to its parent.
+ */
+export declare function toNavigation(layout: ResolvedLayout, options?: LayoutNavigationOptions): LayoutNavigationNode[];
+/** Visible setting keys of a page, actions included, in display order. */
+export declare function keysOf(page: ResolvedPage): string[];
+//# sourceMappingURL=navigation.d.ts.map

package/dist/core/layout/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../../src/core/layout/navigation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EAGd,cAAc,EACd,YAAY,EAEb,MAAM,SAAS,CAAC;AAEjB,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,oBAAoB,EAAE,CAAC;CAClC;AAED,kCAAkC;AAClC,MAAM,WAAW,uBAAuB;IACtC,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACtC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,uBAA4B,GACpC,oBAAoB,EAAE,CAkExB;AAED,0EAA0E;AAC1E,wBAAgB,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,EAAE,CAUnD"}

package/dist/core/layout/resolve.d.ts

@@ -0,0 +1,41 @@
+import type { SettingField } from '../types';
+import type { ResolvedLayout, SettingsLayout } from './types';
+/** What the resolver reads; `createStateManager` satisfies it directly. */
+export interface ResolveLayoutSource {
+    /** Field descriptor for a key; `undefined` skips the item. */
+    fieldByKey: (key: string) => SettingField | undefined;
+    /** Effective value of a key, used to evaluate rules. */
+    valueOf: (key: string) => unknown;
+}
+/** Options for `resolveLayout`. */
+export interface ResolveLayoutOptions {
+    /** Locale for every label and description. Defaults to `en`. */
+    locale?: string;
+    /** Used when `locale` has no translation. Then `en`, then any translation. */
+    fallbackLocale?: string;
+}
+/**
+ * Stable sort by `order`. Entries whose `order` is missing or not finite
+ * sort as `missing` (after every ordered entry by default); ties keep their
+ * array position.
+ */
+export declare function byOrder<T extends {
+    order?: number;
+}>(entries: readonly T[], missing?: number): T[];
+/** Id segment for a uid: URI-encoded so `/` in a uid cannot fake nesting. */
+export declare function layoutIdSegment(uid: string): string;
+/** Page id: `<category>/<page>`, each segment encoded. */
+export declare function layoutPageId(categoryUid: string, pageUid: string): string;
+/**
+ * Turns a layout plus the field source into the tree every renderer and
+ * navigation reads. The tree holds only what is shown:
+ *
+ * - every level sorted by `order` (see `byOrder`); items without `order` keep
+ *   their position and come before a section's groups;
+ * - a uid repeated among siblings, an unknown key, or a key placed a second
+ *   time is skipped (first wins; `validateLayout` reports it);
+ * - a rule-hidden item is dropped, and so is a group or section left empty;
+ * - `actions` fields move to their page's `actions`.
+ */
+export declare function resolveLayout(layout: SettingsLayout, source: ResolveLayoutSource, options?: ResolveLayoutOptions): ResolvedLayout;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/core/layout/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../src/core/layout/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAG7C,OAAO,KAAK,EASV,cAAc,EAGd,cAAc,EACf,MAAM,SAAS,CAAC;AAEjB,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,YAAY,GAAG,SAAS,CAAC;IACtD,wDAAwD;IACxD,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACnC;AAED,mCAAmC;AACnC,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAClD,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,OAAO,GAAE,MAAiC,GACzC,CAAC,EAAE,CAOL;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzE;AAgBD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,mBAAmB,EAC3B,OAAO,GAAE,oBAAyB,GACjC,cAAc,CAyKhB"}

package/dist/core/layout/types.d.ts

@@ -0,0 +1,160 @@
+import type { LocalizedText, SettingField } from '../types';
+import type { SettingFieldRuleState } from '../validate/rules';
+/** Grid settings for a section or group of items. */
+export interface LayoutGridSettings {
+    /**
+     * Logical columns from the small breakpoint up. Items flow one per column;
+     * below it every grid reflows to a single column.
+     */
+    columns: number;
+}
+/** Column split of a page's content sidebar: 8/4, 7/5, or 6/6. */
+export type LayoutSidebarMode = 'default' | 'wide' | 'max';
+/** Header options shared by sections and groups. */
+export interface LayoutPresentation {
+    /** Hide the heading block when `false`. Defaults to shown. */
+    showHeader?: boolean;
+}
+/**
+ * Presentation for one page. Adds the content sidebar to the shared header
+ * options. `sidebar` turns the slot on for that page; the host fills it.
+ */
+export interface LayoutPagePresentation extends LayoutPresentation {
+    /** Render the content sidebar beside this page. */
+    sidebar?: boolean;
+    /** Column split while that sidebar slot is filled. Defaults to `default`. */
+    sidebarMode?: LayoutSidebarMode;
+}
+/** Reference to a setting field placed in a section or group. */
+export interface LayoutItem {
+    /** Key of the setting field to render (matches `SettingField.key`). */
+    key: string;
+    /**
+     * Position among its siblings. Items without one keep their array position
+     * and come before every group of the same section.
+     */
+    order?: number;
+    /** 1-based column the item is pinned to; defaults to natural flow. */
+    column?: number;
+}
+/** A labelled cluster of items inside a section. */
+export interface LayoutGroup {
+    uid: string;
+    label?: LocalizedText;
+    description?: LocalizedText;
+    order: number;
+    presentation?: LayoutPresentation;
+    layout?: LayoutGridSettings;
+    items: LayoutItem[];
+}
+/** A block on a page; holds items directly and/or via groups. */
+export interface LayoutSection {
+    uid: string;
+    label?: LocalizedText;
+    description?: LocalizedText;
+    order: number;
+    presentation?: LayoutPresentation;
+    layout?: LayoutGridSettings;
+    items?: LayoutItem[];
+    groups?: LayoutGroup[];
+}
+/** A navigable settings page composed of sections. */
+export interface LayoutPage {
+    uid: string;
+    label: LocalizedText;
+    description?: LocalizedText;
+    order: number;
+    presentation?: LayoutPagePresentation;
+    sections: LayoutSection[];
+}
+/** Top-level navigation group of pages. */
+export interface LayoutCategory {
+    uid: string;
+    label: LocalizedText;
+    order: number;
+    pages: LayoutPage[];
+}
+/** Full settings layout: what the backend delivers next to the fields. */
+export interface SettingsLayout {
+    categories: LayoutCategory[];
+}
+/** The five layout levels, outermost first. */
+export type LayoutNodeKind = 'category' | 'page' | 'section' | 'group' | 'item';
+/**
+ * Identity shared by every resolved node. `id` is unique across the whole
+ * layout: the URI-encoded uid path from the category down, e.g.
+ * `appearance/branding/colors`.
+ */
+interface ResolvedNodeBase {
+    id: string;
+    uid: string;
+}
+/** A placed setting, with its field and current rule state. */
+export interface ResolvedItem extends ResolvedNodeBase {
+    kind: 'item';
+    /** The setting key; equal to `uid`. */
+    key: string;
+    field: SettingField;
+    /** 1-based column pin, clamped to the parent grid. */
+    column?: number;
+    /** Rule outcome against the current values. */
+    rule: SettingFieldRuleState;
+}
+/** A labelled cluster of items. */
+export interface ResolvedGroup extends ResolvedNodeBase {
+    kind: 'group';
+    label?: string;
+    description?: string;
+    showHeader: boolean;
+    columns: number;
+    children: ResolvedItem[];
+}
+/** A block on a page. Children are items and groups in display order. */
+export interface ResolvedSection extends ResolvedNodeBase {
+    kind: 'section';
+    label?: string;
+    description?: string;
+    showHeader: boolean;
+    columns: number;
+    children: (ResolvedItem | ResolvedGroup)[];
+}
+/**
+ * A navigable page. `actions` are the `actions` fields placed anywhere in
+ * it; they render once, in the page footer, instead of inline.
+ */
+export interface ResolvedPage extends ResolvedNodeBase {
+    kind: 'page';
+    /** Uid of the owning category. */
+    categoryId: string;
+    /** Always `/<category>/<page>`, each segment URI-encoded. */
+    path: string;
+    label: string;
+    description?: string;
+    showHeader: boolean;
+    sidebar: boolean;
+    sidebarMode: LayoutSidebarMode;
+    children: ResolvedSection[];
+    actions: ResolvedItem[];
+}
+/** A top-level navigation group of pages. */
+export interface ResolvedCategory extends ResolvedNodeBase {
+    kind: 'category';
+    label: string;
+    children: ResolvedPage[];
+}
+/** Any resolved node. */
+export type ResolvedLayoutNode = ResolvedCategory | ResolvedPage | ResolvedSection | ResolvedGroup | ResolvedItem;
+/** The resolved tree plus flat lookups. */
+export interface ResolvedLayout {
+    categories: ResolvedCategory[];
+    /** Every page in display order. */
+    pages: ResolvedPage[];
+    /** Page by `id`. */
+    pageById: Map<string, ResolvedPage>;
+    /** Page id by placed setting key. */
+    pageOfKey: Map<string, string>;
+    /** Keys placed in the layout, visible or not, in display order. */
+    placedKeys: string[];
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/core/layout/types.d.ts.map

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

package/dist/core/layout/validate.d.ts

@@ -0,0 +1,26 @@
+import type { SettingField } from '../types';
+import type { SettingsLayout } from './types';
+/** What `validateLayout` can report. */
+export type LayoutIssueCode = 'empty-uid' | 'duplicate-uid' | 'unknown-key' | 'duplicate-key' | 'invalid-column' | 'path-collision' | 'unplaced-field';
+/** One problem in a layout. */
+export interface LayoutIssue {
+    code: LayoutIssueCode;
+    /**
+     * `error`: the resolver drops or rewrites something.
+     * `warning`: renders, but is probably not what the author meant.
+     */
+    severity: 'error' | 'warning';
+    /** Uid path of the offending node, e.g. `appearance/branding/colors`. */
+    path: string;
+    /** Human-readable explanation for logs. */
+    message: string;
+}
+/**
+ * Checks a layout against its fields. Never throws: the resolver already
+ * tolerates every reported case (first wins, unknown is skipped), so a host
+ * can log the issues in development and still render.
+ *
+ * Without `fields`, key checks (`unknown-key`, `unplaced-field`) are skipped.
+ */
+export declare function validateLayout(layout: SettingsLayout, fields?: readonly SettingField[]): LayoutIssue[];
+//# sourceMappingURL=validate.d.ts.map

package/dist/core/layout/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/core/layout/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,OAAO,KAAK,EAIV,cAAc,EACf,MAAM,SAAS,CAAC;AAEjB,wCAAwC;AACxC,MAAM,MAAM,eAAe,GACvB,WAAW,GACX,eAAe,GACf,aAAa,GACb,eAAe,GACf,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,CAAC;AAErB,+BAA+B;AAC/B,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,eAAe,CAAC;IACtB;;;OAGG;IACH,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;CACjB;AAwID;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,cAAc,EACtB,MAAM,CAAC,EAAE,SAAS,YAAY,EAAE,GAC/B,WAAW,EAAE,CAuCf"}