@gtkx/react 1.0.0-rc.3 → 1.0.0-rc.4

package/src/reconciler/placement.ts

@@ -27,7 +27,7 @@ const createEntry = (slot: string, node: PlaceableNode): PlacedChild | null => {
         return null;
     }
 
-    return { node, object, adopted: null, slot, behavior: null, attached: false };
+    return { node, object, adopted: null, slot, behavior: null, isAttached: false };
 };
 
 const siblingAt = (entries: PlacedChild[], index: number): GObject.Object | null =>
@@ -80,7 +80,7 @@ const setObjectSlot = (parent: ElementNode, entry: PlacedChild): void => {
     writeSlot(parent, entry, entry.object);
     wireBufferView(entry.node, parent);
     entry.behavior = null;
-    entry.attached = true;
+    entry.isAttached = true;
 };
 
 const didAttach = (ctx: AttachContext, behavior: ElementBehavior): boolean => {
@@ -99,7 +99,7 @@ const didAttach = (ctx: AttachContext, behavior: ElementBehavior): boolean => {
 
     ctx.entry.behavior = behavior;
     adoptedFrom(ctx.parent, ctx.entry, behavior, claim);
-    ctx.entry.attached = true;
+    ctx.entry.isAttached = true;
     applyLazyProps(ctx.entry);
 
     return true;
@@ -147,11 +147,11 @@ const runDetach = (parent: ElementNode, entry: PlacedChild): void => {
 };
 
 const detachEntry = (parent: ElementNode, entry: PlacedChild): void => {
-    if (!entry.attached) {
+    if (!entry.isAttached) {
         return;
     }
 
-    entry.attached = false;
+    entry.isAttached = false;
 
     applyWrite(() => {
         runDetach(parent, entry);
@@ -175,7 +175,7 @@ const getPosition = (entries: PlacedChild[], before: PlaceableNode | null): numb
 const placeNew = (parent: ElementNode, entry: PlacedChild, entries: PlacedChild[], index: number): void => {
     attachEntry(parent, entry, index, siblingAt(entries, index));
 
-    if (!entry.attached) {
+    if (!entry.isAttached) {
         remove(entries, entry);
 
         return;

package/src/reconciler/registry.ts

@@ -5,62 +5,86 @@ type Props = Record<string, unknown>;
 
 /** Per-child values a slot hook receives while placing or moving one child. */
 type PlaceInfo = {
+    /** Name of the slot being filled: `children`, or the prop the child was nested under. */
     slot: string;
+    /** Position of the child among the slot's children. */
     index: number;
+    /** Object of the preceding child in the slot, or null when the child comes first. */
     sibling: GObject.Object | null;
+    /** Object adopted for this child by an earlier attach, or null before it has one. */
     adopted: GObject.Object | null;
+    /** Props of the child element. */
     props: Props;
+    /** Value `initialize` returned for this behavior on the parent. */
     context: unknown;
 };
 
 /** Per-child values a slot hook receives while removing one child. */
 type DetachInfo = {
+    /** Name of the slot the child is leaving. */
     slot: string;
+    /** Object the container adopted for this child, or null when it adopted none. */
     adopted: GObject.Object | null;
+    /** Props of the child element. */
     props: Props;
+    /** Value `initialize` returned for this behavior on the parent. */
     context: unknown;
 };
 
 /**
- * Customizes how one element type places children and applies props. Every hook receives the
- * GObject instance and a private per-node `context` built once by `createContext`. A slot hook
- * claims a child by returning a non-`undefined` value; that value, or `resolve`, is the object
- * the container adopts for the child. `update` returns the prop names it consumed so those props
- * are not also set as plain GObject properties. `create` builds the GObject for types whose
- * constructor does more than set properties, and is consulted for its own type only, never
- * inherited by subtypes.
+ * Customizes how one element type places children and applies props. Hooks other than `create` receive the
+ * GObject instance; `update`, `flush`, `mount` and `unmount` also take the private per-node context
+ * `initialize` built, and `attach`, `reorder` and `detach` read it off their info object. Subtypes inherit a
+ * type's behaviors, except for `create`, which is consulted only for the type it is registered on.
  */
 type ElementBehavior<T extends GObject.Object = GObject.Object> = {
+    /** Builds the GObject from its construct props, for types whose constructor does more than set properties. */
     create?: (props: Props) => GObject.Object;
-    createContext?: (object: T) => unknown;
+    /** Builds the private per-node context the other hooks receive, once per node. */
+    initialize?: (object: T) => unknown;
+    /** Places a child, claiming it by returning anything other than `undefined`. */
     attach?: (object: T, child: GObject.Object, info: PlaceInfo) => unknown;
+    /** Moves an already-attached child; without it, the whole slot is detached and re-attached in order. */
     reorder?: (object: T, child: GObject.Object, info: PlaceInfo) => unknown;
+    /** Removes a child this behavior attached. */
     detach?: (object: T, child: GObject.Object, info: DetachInfo) => void;
+    /** Returns the object the container adopts for a child, overriding whatever `attach` returned. */
     resolve?: (object: T, child: GObject.Object) => GObject.Object | null;
+    /** Applies changed props and returns the names it consumed, which are then not set as GObject properties. */
     update?: (object: T, prev: Props, next: Props, context: unknown) => Iterable<string> | undefined;
+    /** Runs after the commit that touched the node, once every child has been placed. */
     flush?: (object: T, context: unknown) => void;
+    /** Runs once the node and its initial children are attached. */
     mount?: (object: T, context: unknown) => void;
+    /** Runs when React deletes the node. */
     unmount?: (object: T, context: unknown) => void;
+    /** Props to withhold from the constructor, leaving them for a later hook to apply. */
     deferred?: string[];
 };
 
 /** A named export in a module, referenced as plain data (the module is never imported at runtime). */
-type ModuleExport = { module: string; export: string };
+type ModuleExport = {
+    /** Specifier the export is imported from. */
+    module: string;
+    /** Identifier the module exports it under. */
+    export: string;
+};
 
 /**
- * Per-element configuration keyed by GLib type name: whether the element is lazy (its GObject is
- * created by its parent container, as pages and layout children are), the custom behaviors bound to
- * its type, an optional component that wraps the generated element, the base props interface its
- * generated props extend, and the GObject properties to leave out of the generated props (those a
- * behavior already writes from children, such as the `child` and `content` properties). `component`,
- * `props` and `omitProps` are inert at runtime; they are read only by codegen.
+ * How one GLib type is rendered. `component`, `props` and `omittedProps` are inert at runtime; they are
+ * read only by codegen.
  */
 type ElementConfig<T extends GObject.Object = GObject.Object> = {
-    lazy?: boolean;
+    /** The element has no GObject of its own; its parent container creates one, as it does for pages. */
+    isLazy?: boolean;
+    /** Behaviors bound to the type, consulted in registration order and inherited by its subtypes. */
     behaviors?: ElementBehavior<T>[];
+    /** Component that wraps the generated element. */
     component?: ModuleExport;
+    /** Base props interface the generated props extend. */
     props?: ModuleExport;
-    omitProps?: string[];
+    /** GObject properties to leave out of the generated props, such as those a behavior writes from children. */
+    omittedProps?: string[];
 };
 
 /**
@@ -69,7 +93,6 @@ type ElementConfig<T extends GObject.Object = GObject.Object> = {
  */
 const ELEMENTS: Record<string, ElementConfig> = {};
 
-/** Props a behavior applies after construction; the constructor is never given them. */
 const deferredProps = (behavior: ElementBehavior): string[] => behavior.deferred ?? [];
 
 const mergeBehaviors = (base: ElementConfig, added: ElementBehavior[], isPrepended: boolean): ElementBehavior[] => {
@@ -79,19 +102,19 @@ const mergeBehaviors = (base: ElementConfig, added: ElementBehavior[], isPrepend
 };
 
 const mergeConfigEntry = (base: ElementConfig, added: ElementConfig<never>, isPrepended = false): ElementConfig => {
-    const { behaviors, lazy, omitProps, ...rest } = added;
+    const { behaviors, isLazy, omittedProps, ...rest } = added;
     const entry: ElementConfig = { ...base, ...rest };
 
     if (behaviors !== undefined) {
         entry.behaviors = mergeBehaviors(base, behaviors as ElementBehavior[], isPrepended);
     }
 
-    if (omitProps !== undefined) {
-        entry.omitProps = [...(base.omitProps ?? []), ...omitProps];
+    if (omittedProps !== undefined) {
+        entry.omittedProps = [...(base.omittedProps ?? []), ...omittedProps];
     }
 
-    if (lazy === true) {
-        entry.lazy = true;
+    if (isLazy === true) {
+        entry.isLazy = true;
     }
 
     return entry;
@@ -99,9 +122,9 @@ const mergeConfigEntry = (base: ElementConfig, added: ElementConfig<never>, isPr
 
 /**
  * Merges maps of {@link ElementConfig} keyed by GLib type name into one, concatenating each type's
- * behaviors and omitted props in the order the maps are given (an earlier map's behaviors come first)
- * and taking the last lazy flag, component, and props seen. Use it to combine an app's element config
- * with its behaviors.
+ * behaviors and omitted props in the order the maps are given (an earlier map's behaviors come first),
+ * taking the last component and props seen, and marking a type lazy if any map does. Use it to combine
+ * an app's element config with its behaviors.
  */
 const mergeElementConfigs = (...maps: Record<string, ElementConfig<never>>[]): Record<string, ElementConfig> => {
     const merged: Record<string, ElementConfig> = {};
@@ -115,23 +138,17 @@ const mergeElementConfigs = (...maps: Record<string, ElementConfig<never>>[]): R
     return merged;
 };
 
-/**
- * Registers a map of {@link ElementConfig} keyed by GLib type name, merging each entry into the
- * registry. Behaviors are appended by default (the framework's built-ins register this way); pass
- * `{ prepend: true }` for an app's own configuration so its behaviors are consulted before the
- * built-ins for the same slot, letting it override them regardless of registration order.
- */
 const registerElements = (
     map: Record<string, ElementConfig<never>>,
-    options: { prepend?: boolean } = {},
+    options: { isPrepended?: boolean } = {},
 ): void => {
     for (const [type, config] of Object.entries(map)) {
-        ELEMENTS[type] = mergeConfigEntry(ELEMENTS[type] ?? {}, config, options.prepend === true);
+        ELEMENTS[type] = mergeConfigEntry(ELEMENTS[type] ?? {}, config, options.isPrepended === true);
     }
 };
 
 /**
- * Identity helper that types the module named by the `elements` entry of `gtkx.config.ts`, enabling
+ * Identity helper that types the module named by `elements.behaviors` in `gtkx.config.ts`, enabling
  * editor autocompletion and type checking. Key each entry by GLib type name and write each behavior
  * with {@link defineBehavior} so its hooks receive the concrete GObject class.
  */
@@ -150,11 +167,9 @@ const defineElements = (elements: Record<string, ElementConfig<never>>): Record<
  */
 const defineBehavior = <T extends GObject.Object>(hooks: ElementBehavior<T>): ElementBehavior<never> => hooks;
 
-/** Spreads one config across many GLib type names. */
 const forTypes = (types: string[], config: ElementConfig<never>): Record<string, ElementConfig<never>> =>
     Object.fromEntries(types.map((type) => [type, config]));
 
-/** References a base props interface exported from `@gtkx/react/internal`. */
 const internal = (name: string): ModuleExport => ({ module: "@gtkx/react/internal", export: name });
 
 export {

package/src/reconciler/root-element.ts

@@ -5,7 +5,6 @@ const ROOT_ELEMENT_BRAND: unique symbol = Symbol.for("gtkx:root-element");
 /** A shared marker value used as the default top-level container for rendering and portals. */
 const rootElement: RootElement = { [ROOT_ELEMENT_BRAND]: true };
 
-/** Reports whether an arbitrary value is a {@link rootElement} marker. */
 const isRootElement = (value: unknown): value is RootElement =>
     typeof value === "object" && value !== null && Object.hasOwn(value, ROOT_ELEMENT_BRAND);
 

package/src/reconciler/root.ts

@@ -15,7 +15,6 @@ type RootErrorCallbacks = {
 
 type ReconcilerRootOptions = RootErrorCallbacks & { containerInfo: Container };
 
-/** A root that mounts an element tree into an explicit container and reports render errors. */
 type ReconcilerRoot = {
     update: (element: ReactNode) => void;
     unmount: (teardown: (root: ReconcilerRoot) => Promise<void>) => Promise<void>;
@@ -23,7 +22,9 @@ type ReconcilerRoot = {
 
 /** The object {@link createRoot} returns: it renders an element tree into a container and can tear it down. */
 type Root = {
+    /** Mounts an element tree into the container, or updates the tree already mounted there. */
     render: (element: ReactNode) => void;
+    /** Unmounts the rendered tree and runs its effect cleanups. */
     unmount: () => void;
 };
 
@@ -49,12 +50,6 @@ function createErrorHandlerSlot(): ErrorHandlerSlot {
     };
 }
 
-/**
- * Installs a process-wide handler for errors thrown while rendering or applying an update.
- *
- * @param handler The handler to install.
- * @returns The previously installed handler, or null.
- */
 const setReconcilerErrorHandler = (handler: ErrorHandler): ErrorHandler | null => errorHandlerSlot.set(handler);
 
 const rethrowUncaughtRenderError = (error: unknown): never => {
@@ -97,12 +92,6 @@ const unmountContainer = (container: OpaqueRoot): void => {
     activeRoots.delete(container);
 };
 
-/**
- * Creates a root that mounts an element tree into a container, routing render errors to the supplied callbacks.
- *
- * @param options The container to render into and the error callbacks to route failures to.
- * @returns A {@link ReconcilerRoot}.
- */
 const createReconcilerRoot = (options: ReconcilerRootOptions): ReconcilerRoot => {
     const container = openContainer(options.containerInfo, options);
 
@@ -120,10 +109,10 @@ const createReconcilerRoot = (options: ReconcilerRootOptions): ReconcilerRoot =>
 };
 
 /**
- * Creates a render root for a GTKX application.
+ * Creates a render root for a GTKX application. Uncaught render errors are rethrown and errors caught by an
+ * error boundary are logged.
  *
- * @param container The top-level container to render into; defaults to the shared {@link rootElement}.
- * @returns A {@link Root} exposing render and unmount.
+ * @param container The GObject to render into; defaults to the shared {@link rootElement}, which holds no object.
  */
 const createRoot = (container: Container = rootElement): Root => {
     const opaque = openContainer(container, {
@@ -153,10 +142,7 @@ const quit = (): typeof Gdk.EVENT_STOP => {
 /**
  * Renders children into a container other than the surrounding tree.
  *
- * @param children The element tree to render.
- * @param container The GObject, application, or {@link rootElement} to render into.
- * @param key An optional stable key.
- * @returns A React portal.
+ * @param container The GObject to render into, or {@link rootElement} to render at the top level.
  */
 const createPortal = (children: ReactNode, container: Container, key?: string): ReactPortal =>
     reconciler.createPortal(children, container, null, key ?? null) as unknown as ReactPortal;

package/src/reconciler/signals.ts

@@ -36,7 +36,7 @@ const invokeHandler = (
 
 const wrapHandler = (target: SignalTarget, record: HandlerRecord, notifyProperty: string | null): SignalHandler =>
     (...args: unknown[]): unknown => {
-        if (record.blockable && isApplyingWrite()) {
+        if (record.isBlockable && isApplyingWrite()) {
             return undefined;
         }
 
@@ -58,7 +58,7 @@ const connectHandler = (target: SignalTarget, prop: string, signal: string, hand
 
     const isBlockable = isBlockableSignal(typeInfoFor(target.typeName), signal);
     const notifyProperty = getNotifyProperty(signal);
-    const record: HandlerRecord = { signal, handler, wrapped: (): undefined => undefined, blockable: isBlockable };
+    const record: HandlerRecord = { signal, handler, wrapped: (): undefined => undefined, isBlockable };
     record.wrapped = wrapHandler(target, record, notifyProperty);
     target.object.on(signal, record.wrapped);
     target.handlers.set(prop, record);

package/src/reconciler/text.ts

@@ -7,7 +7,7 @@ import type { Props } from "./registry.js";
 import { ELEMENT_KIND, TEXT_KIND } from "./node.js";
 import { applyWrite } from "./signals.js";
 
-type OffsetResult = { found: boolean; offset: number };
+type OffsetResult = { wasFound: boolean; offset: number };
 
 type BufferBuild = {
     buffer: Gtk.TextBuffer;
@@ -76,14 +76,14 @@ const isTagElement = (node: ContentChild): node is ElementNode =>
 
 const stepOffset = (node: ContentChild, target: TextNode, offset: number): OffsetResult => {
     if (node === target) {
-        return { found: true, offset };
+        return { wasFound: true, offset };
     }
 
     if (isTagElement(node)) {
         return getOffset(node.content, target, offset);
     }
 
-    return { found: false, offset: offset + contentTextLength(node) };
+    return { wasFound: false, offset: offset + contentTextLength(node) };
 };
 
 const getOffset = (nodes: ContentChild[], target: TextNode, start: number): OffsetResult => {
@@ -92,14 +92,14 @@ const getOffset = (nodes: ContentChild[], target: TextNode, start: number): Offs
     for (const node of nodes) {
         const step = stepOffset(node, target, offset);
 
-        if (step.found) {
+        if (step.wasFound) {
             return step;
         }
 
         offset = step.offset;
     }
 
-    return { found: false, offset };
+    return { wasFound: false, offset };
 };
 
 const enclosingTagNodes = (node: TextNode): ElementNode[] => {
@@ -379,7 +379,7 @@ const didUpdateTextSurgically = (host: ElementNode, node: TextNode, oldText: str
 
     const located = getOffset(host.content, node, 0);
 
-    if (!located.found) {
+    if (!located.wasFound) {
         return false;
     }
 

package/src/utils/accessible-metadata.ts

@@ -15,13 +15,6 @@ const deleteAccessibleMetadata = (widget: object, name: string): void => {
     metadataStore.get(widget)?.delete(name);
 };
 
-/**
- * Returns the last value applied for an accessible prop on a widget, or null when none was applied.
- *
- * @param widget The widget to read from.
- * @param name The accessible prop name.
- * @returns The last applied value, or null.
- */
 const getAccessibleMetadata = (widget: object, name: string): unknown => {
     const value = metadataStore.get(widget)?.get(name);
 

package/src/utils/accessible-props.ts

@@ -6,55 +6,103 @@ import { deleteAccessibleMetadata, setAccessibleMetadata } from "./accessible-me
 /**
  * Accessibility props available on every widget. Each member maps to a GTK4 accessible attribute
  * (a `Gtk.AccessibleProperty`, `Gtk.AccessibleState`, or `Gtk.AccessibleRelation`) and is applied
- * to the widget's accessible interface; setting a member to `undefined` resets that attribute to its default.
+ * to the widget's accessible interface. Setting a member to `null` or `undefined`, or dropping it from the
+ * props, resets that attribute to its default.
  */
 type AccessibleProps = {
+    /** How the widget completes the text being typed into it. */
     accessibleAutocomplete?: Gtk.AccessibleAutocomplete | null | undefined;
+    /** Longer description announced after the label. */
     accessibleDescription?: string | null | undefined;
+    /** Whether activating the widget opens a popup. */
     accessibleHasPopup?: boolean | null | undefined;
+    /** Keyboard shortcuts that activate the widget. */
     accessibleKeyShortcuts?: string | null | undefined;
+    /** Short name announced for the widget. */
     accessibleLabel?: string | null | undefined;
+    /** Depth of the widget within a hierarchy of headings, list items, or tree rows. */
     accessibleLevel?: number | null | undefined;
+    /** Whether the widget blocks interaction with everything behind it. */
     accessibleModal?: boolean | null | undefined;
+    /** Whether the text input accepts more than one line. */
     accessibleMultiLine?: boolean | null | undefined;
+    /** Whether more than one of the widget's items can be selected at a time. */
     accessibleMultiSelectable?: boolean | null | undefined;
+    /** Whether the widget arranges its items horizontally or vertically. */
     accessibleOrientation?: Gtk.Orientation | null | undefined;
+    /** Hint announced while the input is empty. */
     accessiblePlaceholder?: string | null | undefined;
+    /** Whether the value can be read but not changed. */
     accessibleReadOnly?: boolean | null | undefined;
+    /** Whether a value has to be supplied before the form can be submitted. */
     accessibleRequired?: boolean | null | undefined;
+    /** Wording that replaces the default announcement of the widget's role. */
     accessibleRoleDescription?: string | null | undefined;
+    /** Direction the widget's items are sorted in. */
     accessibleSort?: Gtk.AccessibleSort | null | undefined;
+    /** Upper bound of the widget's value range. */
     accessibleValueMax?: number | null | undefined;
+    /** Lower bound of the widget's value range. */
     accessibleValueMin?: number | null | undefined;
+    /** Current value within the widget's range. */
     accessibleValueNow?: number | null | undefined;
+    /** Wording announced in place of the numeric value. */
     accessibleValueText?: string | null | undefined;
+    /** Help text describing how to use the widget. */
     accessibleHelpText?: string | null | undefined;
+    /** Whether the widget is still loading and its content may yet change. */
     accessibleBusy?: boolean | null | undefined;
+    /** Checked state of a check button or menu item, which may be mixed. */
     accessibleChecked?: Gtk.AccessibleTristate | null | undefined;
+    /** Whether the widget is visible but cannot be edited or operated. */
     accessibleDisabled?: boolean | null | undefined;
+    /** Whether the content the widget discloses is showing. */
     accessibleExpanded?: boolean | null | undefined;
+    /** Whether the widget is kept out of the accessibility tree. */
     accessibleHidden?: boolean | null | undefined;
+    /** Whether the entered value fails validation, and in what way. */
     accessibleInvalid?: Gtk.AccessibleInvalidState | null | undefined;
+    /** Pressed state of a toggle button, which may be mixed. */
     accessiblePressed?: Gtk.AccessibleTristate | null | undefined;
+    /** Whether the widget is selected within its container. */
     accessibleSelected?: boolean | null | undefined;
+    /** Whether the link has already been followed. */
     accessibleVisited?: boolean | null | undefined;
+    /** Descendant that holds the focus while the widget itself keeps it. */
     accessibleActiveDescendant?: Gtk.Widget | null | undefined;
+    /** Total number of columns in the table, including any that are not rendered. */
     accessibleColCount?: number | null | undefined;
+    /** One-based column position of the cell within its table. */
     accessibleColIndex?: number | null | undefined;
+    /** Wording announced in place of the numeric column position. */
     accessibleColIndexText?: string | null | undefined;
+    /** Number of columns the cell spans. */
     accessibleColSpan?: number | null | undefined;
+    /** Widgets whose content or presence this widget controls. */
     accessibleControls?: Gtk.Widget[] | null | undefined;
+    /** Widgets that describe this one. */
     accessibleDescribedBy?: Gtk.Widget[] | null | undefined;
+    /** Widgets holding extended detail about this one. */
     accessibleDetails?: Gtk.Widget[] | null | undefined;
+    /** Widgets holding the message that explains why the value is invalid. */
     accessibleErrorMessage?: Gtk.Widget[] | null | undefined;
+    /** Widgets to read next, overriding the default reading order. */
     accessibleFlowTo?: Gtk.Widget[] | null | undefined;
+    /** Widgets that label this one. */
     accessibleLabelledBy?: Gtk.Widget[] | null | undefined;
+    /** Widgets this one owns that the widget hierarchy does not already imply. */
     accessibleOwns?: Gtk.Widget[] | null | undefined;
+    /** One-based position of the widget within its set. */
     accessiblePosInSet?: number | null | undefined;
+    /** Total number of rows in the table, including any that are not rendered. */
     accessibleRowCount?: number | null | undefined;
+    /** One-based row position of the cell within its table. */
     accessibleRowIndex?: number | null | undefined;
+    /** Wording announced in place of the numeric row position. */
     accessibleRowIndexText?: string | null | undefined;
+    /** Number of rows the cell spans. */
     accessibleRowSpan?: number | null | undefined;
+    /** Total number of items in the set the widget belongs to. */
     accessibleSetSize?: number | null | undefined;
 };
 

package/src/utils/ref-prop.ts

@@ -9,12 +9,6 @@ type RefProp<T extends object> = T | RefObject<T | null> | null | undefined;
 const isRefObject = <T extends object>(value: T | RefObject<T | null>): value is RefObject<T | null> =>
     typeof value === "object" && "current" in value;
 
-/**
- * Resolves a {@link RefProp} to the concrete object it points at, or null when it is absent or unresolved.
- *
- * @param prop The target object, a ref to one, or null/undefined.
- * @returns The resolved object, or null.
- */
 const resolveRefProp = <T extends object>(prop: RefProp<T>): T | null => {
     if (prop === null || prop === undefined) {
         return null;

package/src/utils/settings.ts

@@ -1,13 +1,19 @@
 import type * as Gio from "@gtkx/gi/gio";
 import { packVariant, parseVariantType, unpackVariant, type VariantValue } from "./variant.js";
 
+/** Maps each key of a GSettings schema to its kind: a GVariant type string, or `enum` or `flags`. */
 type SettingsSchemaKeys = Record<string, string>;
 type SettingKindValue<S extends string> = S extends "enum" | "flags" ? number : VariantValue<S>;
+/** The JavaScript type key `P` holds: `number` for `enum` and `flags`, otherwise the unpacked GVariant. */
 type SettingValue<K extends SettingsSchemaKeys, P extends keyof K> = SettingKindValue<K[P] & string>;
 
+/** A GSettings schema, as described by the modules GTKX generates from a project's `.gschema.xml` files. */
 type SettingsSchema<K extends SettingsSchemaKeys = SettingsSchemaKeys> = {
+    /** Schema id it is looked up by, such as `org.gtkx.Example`. */
     id: string;
+    /** Path a relocatable schema is instantiated at, or `null` to use the schema's own path. */
     path: string | null;
+    /** Kind of every key the schema declares, which types reads and writes of that key. */
     keys: K;
 };