@gjsify/adwaita-core 0.55.0 → 0.57.0

package/lib/types/index.d.ts

@@ -50,6 +50,8 @@ export type { BoxOrientation } from './box.js';
 export { DEFAULT_LABEL_ELLIPSIZE, DEFAULT_LABEL_LINES, DEFAULT_LABEL_MAX_WIDTH_CHARS, DEFAULT_LABEL_WIDTH_CHARS, DEFAULT_LABEL_WRAP_MODE, DEFAULT_LABEL_XALIGN, DEFAULT_LABEL_YALIGN, LABEL_ELLIPSIZE_MODES, LABEL_JUSTIFICATIONS, LABEL_WRAP_MODES, labelDisplayText, labelEffectiveLines, labelEllipsizeOverflowValue, labelMarkupIsUnparseable, labelWidthCharsExtent, labelYalignAlignItems, normalizeLabelEllipsize, normalizeLabelJustify, normalizeLabelLines, normalizeLabelMaxWidthChars, normalizeLabelWidthChars, normalizeLabelWrapMode, normalizeLabelXalign, normalizeLabelYalign, } from './label.js';
 export type { LabelAlignItems, LabelEllipsizeMode, LabelJustification, LabelWidthCharsExtent, LabelWrapMode, } from './label.js';
 export { glibClamp, gStrStrip, stringIsNotEmpty } from './glib.js';
+export { createGLibTimers } from './glib-timers.js';
+export type { GLibTimers, SourceFunc, TimerHost } from './glib-timers.js';
 export { ViewStackState, normalizeIconName, resolvePageTitle } from './view-stack.js';
 export type { AdwViewStackPageInfo, AdwViewStackPageSpec, ViewStackStateChange, ViewStackStateListener, } from './view-stack.js';
 export { BACK_BUTTON_FALLBACK_TOOLTIP, NavigationViewState, describeNavigationDiagnostic } from './navigation-view.js';
@@ -72,6 +74,11 @@ export type { AdwPackType, AdwTextDirection, NavigationActionInput, NavigationAc
 export { DEFAULT_DROPDOWN_TOOLTIP, SPLIT_BUTTON_DISABLED_OPACITY, SplitButtonState, isSplitButtonDirection, menuButtonArrowIcon, menuButtonPopupDirection, resolveDropdownTooltip, splitButtonArrowIcon, splitButtonPopupDirection, splitButtonRootState, splitButtonStyleClasses, } from './split-button.js';
 export type { AdwArrowIcon, SplitButtonChange, SplitButtonContentMode, SplitButtonDirection, SplitButtonHalfState, SplitButtonListener, SplitButtonProperty, SplitButtonStyleClass, } from './split-button.js';
 export { GioMenu, GioMenuItem } from './gio-menu.js';
+export { activateMenuItem, menuActionsFor } from './menu-actions.js';
+export { assertPopupMenuPlan, planPopupMenu } from './popup-menu-plan.js';
+export type { PopupMenuEntryPlan, PopupMenuGroupPlan, PopupMenuItemPlan, PopupMenuLevelPlan, PopupMenuPlan, PopupMenuRefusal, PopupMenuSubmenuPlan, } from './popup-menu-plan.js';
+export { menuAssignments } from './menu-tree.js';
+export type { MenuTreeNode } from './menu-tree.js';
 export { ADW_MENU_SURFACE_NATIVESCRIPT, ADW_MENU_SURFACE_WEB, assertMenuRenderable, flattenMenu, menuItemAt, menuNodeAt, menuRefusals, normalizeMenuModel, parseDetailedAction, parseMenuModel, resolveMenuItemState, } from './menu.js';
 export type { AdwDetailedAction, AdwMenuAction, AdwMenuActions, AdwMenuDisplayHint, AdwMenuEntryInput, AdwMenuFlatRow, AdwMenuHiddenWhen, AdwMenuInput, AdwMenuItem, AdwMenuItemInput, AdwMenuItemRole, AdwMenuItemState, AdwMenuModel, AdwMenuNode, AdwMenuPath, AdwMenuRefusal, AdwMenuSection, AdwMenuSectionInput, AdwMenuSubmenu, AdwMenuSubmenuInput, AdwMenuSurface, AdwMenuTextDirection, } from './menu.js';
 export { DEFAULT_INDICATOR_DESCRIPTION_STRINGS, INLINE_VIEW_SWITCHER_DISPLAY_MODES, VIEW_SWITCHER_BADGE_LIMIT, VIEW_SWITCHER_DRAG_SWITCH_DELAY, VIEW_SWITCHER_FALLBACK_ICON, VIEW_SWITCHER_NO_SELECTION, VIEW_SWITCHER_POLICIES, ViewSwitcherBarState, ViewSwitcherDragSwitch, ViewSwitcherState, buildInlineToggles, buildViewSwitcherButtons, createViewSwitcherPage, inlineToggleTooltip, isInlineViewSwitcherDisplayMode, isViewSwitcherButtonVisible, isViewSwitcherPolicy, pageIndexForToggle, shouldRevealViewSwitcherBar, stripMnemonic, toggleIndexForPage, viewSwitcherBadgeLabel, viewSwitcherButtonOrientation, viewSwitcherIconName, viewSwitcherIndicatorDescription, viewSwitcherLabel, viewSwitcherPageFromStackPage, viewSwitcherPagesFromStack, viewSwitcherSidebarSections, } from './view-switcher.js';
@@ -101,3 +108,9 @@ export { ADW_WRAP_BOX_DEFAULT_ALIGN, ADW_WRAP_BOX_DEFAULT_JUSTIFY, ADW_WRAP_BOX_
 export type { AdwWrapBoxJustify, AdwWrapBoxOrientation, AdwWrapBoxPackDirection, AdwWrapPolicy, WrapBoxChildFlex, WrapBoxChildOrderOp, WrapBoxFlexInput, WrapBoxFlexStyle, WrapBoxLineLayout, } from './wrap-box.js';
 export { ADW_SOURCE_6502_DIRECTIVES, ADW_SOURCE_6502_LINE_COMMENT, ADW_SOURCE_6502_OPCODES, ADW_SOURCE_6502_REGISTERS, ADW_SOURCE_6502_TOKEN_ROLES, ADW_SOURCE_HEX_STRIDE, ADW_SOURCE_PALETTE_DARK, ADW_SOURCE_PALETTE_LIGHT, ADW_SOURCE_SYNTAX_ROLES, classifyAsm6502Word, formatHexAddress, formatLineNumber, stripSourceWhitespace, tokenizeAsm6502, } from './source.js';
 export type { AdwSourcePalette, AdwSourceSyntaxRole, AdwSourceTokenClass, AdwSourceTokenStream } from './source.js';
+export { GObjectObject, META_SYMBOLS, ParamFlags, ParamSpec, TYPE_BOOLEAN, TYPE_DOUBLE, TYPE_INT, TYPE_STRING, TYPE_UINT, UnsupportedGObjectError, bindProperties, connectInstance, constructRegistered, createClosure, createGObject, disconnectInstance, emitInstance, notifyInstance, registeredClassOf, registerBaseClass, UNLOCKED_VFUNCS, GIR_TYPE, } from './gobject.js';
+export { ApplicationFlags, GioApplicationBase, GtkApplicationBase, withGtkApplication, isValidApplicationId, } from './application.js';
+export type { ApplicationHost, GtkApplicationMembers, GtkApplicationConstructor } from './application.js';
+export { ActionRegistry, SimpleAction, actionRegistryOf, activateWidgetAction, applicationOfWindow, findActionGroup, insertActionGroup, installActionMap, linkWindow, } from './gio-actions.js';
+export type { ActionActivateHandler, ActionGroupLike, ActionLike, SimpleActionProps } from './gio-actions.js';
+export type { Binding, BindingFlag, BlueprintTemplate, BuiltTemplate, ClassLike, ClassMeta, GObjectConstructor, GObjectDoor, GObjectInstance, GObjectNamespace, GType, ParamKind, RegisterClass, RegisteredClass, SignalHandler, SignalMeta, TemplateScope, } from './gobject.js';

package/lib/types/menu-actions.d.ts

@@ -0,0 +1,16 @@
+import type { AdwMenuActions, AdwMenuModel, AdwMenuItem } from './menu.js';
+type Parent = (node: object) => object | null | undefined;
+/**
+ * The actions the model's items name, as `widget` resolves them. An action the walk does not find,
+ * because no group has its prefix or the group lacks it, is left out, which is "missing" and makes
+ * the item insensitive. That is GTK's answer, measured on GJS (`menu-actions.gjs.spec.ts`), and it
+ * overrules ADR 0097 § 3's "no group dims nothing": an application that dispatches an action
+ * itself declares it, or passes `actions` to say what it knows.
+ */
+export declare function menuActionsFor(model: AdwMenuModel, widget: object, parent: Parent): AdwMenuActions;
+/**
+ * Fire the action an item names, the way `GtkMenuTrackerItem` does on activation. A target is
+ * passed as its text: `GLib.Variant` is outside the subset until stage 3.
+ */
+export declare function activateMenuItem(item: AdwMenuItem, widget: object, parent: Parent): boolean;
+export {};

package/lib/types/menu-actions.gjs.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/menu-actions.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/menu-tree.d.ts

@@ -0,0 +1,12 @@
+import type { AdwMenuModel } from './menu.js';
+/** The slice of a tree node this reads. */
+export interface MenuTreeNode {
+    readonly tag: string;
+    readonly props?: Readonly<Record<string, string | number | boolean>>;
+    readonly menuModels?: Readonly<Record<string, readonly unknown[]>>;
+}
+/**
+ * The menus a node assigns, as `[property, model]`: the root menu `menu-model: id` names, and each
+ * model written at a property. An id with no root menu is refused by name.
+ */
+export declare function menuAssignments(node: MenuTreeNode, menus: Readonly<Record<string, readonly unknown[]>> | undefined): Array<[string, AdwMenuModel]>;

package/lib/types/menu-tree.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/popup-menu-plan.d.ts

@@ -0,0 +1,47 @@
+import type { AdwMenuActions, AdwMenuModel, AdwMenuPath } from './menu.js';
+/** An item of the plan; `path` maps a tap back to the model. */
+export interface PopupMenuItemPlan {
+    readonly kind: 'item';
+    readonly path: AdwMenuPath;
+    readonly title: string;
+    /** Shown disabled, not omitted: the dimmed row is the platform's own idiom (0097 § 2). */
+    readonly enabled: boolean;
+    /** CHECK items set it themselves; a RADIO item takes it from its exclusive group. */
+    readonly checkable: boolean;
+    readonly checked: boolean;
+    readonly role: 'normal' | 'check' | 'radio';
+    /** The action name without its target: the identity of a radio run. */
+    readonly action?: string;
+}
+/** A submenu: `Menu.addSubMenu`, whose items are a level of their own. */
+export interface PopupMenuSubmenuPlan {
+    readonly kind: 'submenu';
+    readonly path: AdwMenuPath;
+    readonly title: string;
+    readonly level: PopupMenuLevelPlan;
+}
+export type PopupMenuEntryPlan = PopupMenuItemPlan | PopupMenuSubmenuPlan;
+/** One `groupId`: a section, or the run of items outside any section. */
+export interface PopupMenuGroupPlan {
+    /** `exclusive` is `setGroupCheckable(group, true, true)`; the flag is per group on Android. */
+    readonly checkable: 'none' | 'exclusive';
+    readonly entries: readonly PopupMenuEntryPlan[];
+}
+export interface PopupMenuLevelPlan {
+    readonly groups: readonly PopupMenuGroupPlan[];
+}
+/** What `PopupMenu` cannot express, by the name the diagnostic uses. */
+export interface PopupMenuRefusal {
+    readonly what: 'custom' | 'section-label' | 'mixed-radio-section';
+    /** The item for `custom`, the section (or the submenu / root holding the loose items) otherwise. */
+    readonly path: AdwMenuPath;
+    readonly message: string;
+}
+export interface PopupMenuPlan {
+    readonly level: PopupMenuLevelPlan;
+    readonly refusals: readonly PopupMenuRefusal[];
+}
+/** Lower `model` for `PopupMenu`. `actions` is what {@link resolveMenuItemState} reads. */
+export declare function planPopupMenu(model: AdwMenuModel, actions?: AdwMenuActions): PopupMenuPlan;
+/** Throw naming every refusal, as `assertMenuRenderable` does for the sheet. */
+export declare function assertPopupMenuPlan(plan: PopupMenuPlan): void;

package/lib/types/popup-menu-plan.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/tags.d.ts

@@ -37,7 +37,7 @@ export declare const attributeOf: (prop: string) => string;
  */
 export declare const propertyOf: (name: string) => string;
 /**
- * `GtkWidget`'s four margins, as the CSS property each one is — `start`/`end` the LOGICAL
+ * `GtkWidget`'s four margins, as the CSS property each is — `start`/`end` the LOGICAL
  * edges `gtk_widget_set_margin_start` documents, `top`/`bottom` physical as in GTK.
  *
  * A markup renderer writes them as inline style, because an attribute cannot carry a length
@@ -46,3 +46,45 @@ export declare const propertyOf: (name: string) => string;
  * `./markup.ts`, whose markup has to parse back to exactly what that builder made.
  */
 export declare const GTK_WIDGET_MARGIN_CSS: Readonly<Record<string, string>>;
+/**
+ * `GtkWidget:hexpand` / `vexpand`, the two booleans whose `false` is an AUTHORED answer: the
+ * attribute's absence says "not written", and a widget that expands by default
+ * (`<gtk-scrolled-window>`) needs the author's `false` to stop. A renderer writes `true` as
+ * the bare attribute and `false` as `hexpand="false"`, which the stylesheet reads.
+ */
+export declare const GTK_WIDGET_EXPAND: readonly ["hexpand", "vexpand"];
+/**
+ * `GtkWidget:width-request` / `height-request`, as the CSS minimum each one is. A size request
+ * is a MINIMUM in GTK (`gtk_widget_set_size_request`: the widget is never measured below it,
+ * and its natural size still wins when larger), so `min-*` is the same sentence and `width`
+ * would claim an exactness GTK does not give. -1 is the pspec's "not set".
+ */
+export declare const GTK_WIDGET_SIZE_CSS: Readonly<Record<string, string>>;
+/**
+ * The inline-style declaration an authored GtkWidget length property stands for, or
+ * `undefined` when `attribute` is not one. `null` is a size request of -1: the author said
+ * "unset", so nothing is written (and an earlier value is to be cleared).
+ */
+export declare function widgetLengthStyle(attribute: string, value: string | number | boolean): readonly [property: string, length: string | null] | undefined;
+/**
+ * Kebab-case attribute names of GTK boolean properties that default to TRUE.
+ * These are VALUE-BASED: `attr="false"` means false, absent means true (the default).
+ * Style classes like `flat`/`round`/`compact` are PRESENCE-BASED and NOT in this set.
+ * ADR 0049, ADR 0034 own the presence vs. value split.
+ *
+ * @deprecated Use {@link isValueBasedBooleanAttr} instead. This flat set cannot express
+ *   that the same attribute name (e.g. `revealed`) is value-based for one widget
+ *   (`gtk-action-bar`) but presence-based for another (`adw-banner`).
+ */
+export declare const VALUE_BASED_BOOLEAN_ATTRS: Set<string>;
+/**
+ * Whether the given attribute on the given widget tag is VALUE-BASED.
+ *
+ * Value-based means: `attr="false"` spells false, absent spells the default (TRUE).
+ * Presence-based means: the attribute's PRESENCE spells true, absence spells false.
+ *
+ * @param tagName The element's tag name (e.g. `adw-banner`, `gtk-action-bar`).
+ * @param attrName The kebab-case attribute name (e.g. `revealed`, `can-pop`).
+ * @returns True if the attribute should be written as `attr="true"|"false"`.
+ */
+export declare function isValueBasedBooleanAttr(tagName: string, attrName: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-core",
-    "version": "0.55.0",
+    "version": "0.57.0",
     "description": "Headless Adwaita widget behavior (breakpoint condition grammar + apply/unapply state machine, color-scheme observable, avatar derivation) shared by the web and NativeScript Adwaita renderers — pure TS, no platform imports",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -58,8 +58,8 @@
         "headless"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.55.0",
-        "@gjsify/unit": "^0.55.0",
+        "@gjsify/cli": "^0.57.0",
+        "@gjsify/unit": "^0.57.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },