@gjsify/adwaita-core 0.31.0 → 0.32.0

package/lib/types/avatar.d.ts

@@ -0,0 +1,112 @@
+/** How many colours `Adw.Avatar` picks between — libadwaita's `NUMBER_OF_COLORS`. */
+export declare const AVATAR_COLOR_COUNT = 14;
+/** One `$avatarcolorlist` entry: light `fg` text over a `start`→`stop` gradient. */
+export interface AdwAvatarColor {
+    /** Light tint used for the initials. */
+    fg: string;
+    /** Gradient start (top). */
+    start: string;
+    /** Gradient stop (bottom). */
+    stop: string;
+}
+/**
+ * The 14 libadwaita avatar colours, in `$avatarcolorlist` order — index `n` is
+ * the CSS class `color{n+1}`.
+ */
+export declare const AVATAR_COLORS: ReadonlyArray<AdwAvatarColor>;
+/**
+ * GLib's `g_str_hash` — the DJB2 variant `h = h * 33 + c`, as `guint32`.
+ *
+ * Two details decide whether the avatar colour matches GTK, and both were wrong
+ * in the renderer copies this replaces: `c` is a **`signed char` of the UTF-8
+ * encoding**, not a UTF-16 code unit, so bytes ≥ 0x80 contribute NEGATIVE values
+ * (`"Jörg Schröder"` picked colour 5 instead of 13); and the C loop stops at the
+ * first NUL byte, so an embedded `\0` truncates the input.
+ */
+export declare function gStrHash(text: string): number;
+/**
+ * The initials `Adw.Avatar` shows for `text`: the first character, plus the
+ * character following the LAST space if there is one.
+ *
+ * Mirrors `extract_initials_from_text` step for step — upcase, then strip, then
+ * NFC-normalise, then take code points (never UTF-16 units, so an astral first
+ * letter survives). Only a literal ASCII space separates the two initials, so
+ * `"Ada\tLovelace"` yields `"A"`, exactly as GTK does.
+ *
+ * Returns `''` for a blank name. libadwaita instead emits a one-NUL-byte label
+ * there, because its caller only guards the RAW text against being empty; an
+ * empty string is the sane rendering of the same "no initials" state.
+ */
+export declare function avatarInitials(text: string): string;
+/**
+ * The 1-based colour class (`color1`…`color14`) `Adw.Avatar` assigns to `text`,
+ * i.e. `set_class_color`'s `(g_str_hash (text) % NUMBER_OF_COLORS) + 1`.
+ *
+ * `null` for a blank name: libadwaita picks a RANDOM class there, so no value is
+ * derivable from the name. A renderer that wants that behaviour calls
+ * {@link randomAvatarColorClass}; one that paints nothing without initials — as
+ * both current renderers do — can ignore the `null`.
+ */
+export declare function avatarColorClass(text: string): number | null;
+/**
+ * A random colour class for a nameless avatar, matching libadwaita's
+ * `g_rand_int_range (rand, 1, NUMBER_OF_COLORS)` — which is the half-open range
+ * `[1, 14)`, so `color14` never comes up. Kept faithful rather than "fixed":
+ * a renderer that widened it would not match GTK.
+ */
+export declare function randomAvatarColorClass(random?: () => number): number;
+/**
+ * The palette entry `Adw.Avatar` paints for `text`. Falls back to the first
+ * colour for a blank name so a renderer always has something to paint; use
+ * {@link avatarColorClass} directly when the nameless case must stay random.
+ */
+export declare function avatarColor(text: string): AdwAvatarColor;
+/** Which of the three mutually exclusive things an avatar shows. */
+export type AdwAvatarMode = 'image' | 'initials' | 'icon';
+/**
+ * `update_visibility` (adw-avatar.c:117): a custom image wins outright,
+ * otherwise initials show when they were asked for and the name is non-empty,
+ * otherwise the fallback icon.
+ *
+ * The gate is the length of the TEXT, not of the derived initials — a
+ * whitespace-only name is in `'initials'` mode with a blank label, where a
+ * renderer keying on the initials would fall back to the icon instead.
+ */
+export declare function avatarMode(input: {
+    hasCustomImage: boolean;
+    showInitials: boolean;
+    text: string;
+}): AdwAvatarMode;
+/**
+ * The largest font size that still fits the initials inside the circle
+ * (`update_font_size`, adw-avatar.c:221-227): the biggest square inscribed in
+ * the circle, `size / 1.4142`, less a size-proportional padding
+ * `max(size * 0.4 - 5, 0)`.
+ *
+ * Monotonically increasing in `size`. A renderer that cannot measure text can
+ * use this alone and stay inside libadwaita's bound — which the browser
+ * renderer's old `size * (size < 32 ? 0.5 : 0.4)` did not: at size 31 it asked
+ * for 15.5px against a 14.5px cap, then DROPPED to 12.8px at size 32.
+ */
+export declare function avatarMaxFontSize(size: number): number;
+/**
+ * The font size `Adw.Avatar` gives the initials label, given the label's
+ * measured box: `height * (max / width)`, clamped to `[0, max]`.
+ *
+ * Text measurement is the one genuinely renderer-specific input, so it is
+ * injected — the same seam style as `ToastScheduler`. Only the ASPECT RATIO of
+ * the measurement matters (the formula scales it against the cap), so a renderer
+ * may measure at any font size it likes, exactly as Pango's reset-then-measure
+ * does. A non-positive width means "not laid out yet"; the cap is then the only
+ * defensible answer.
+ */
+export declare function avatarFontSize(size: number, measured: {
+    width: number;
+    height: number;
+}): number;
+/**
+ * The flat 50/50 blend of a palette entry's gradient, for renderers whose style
+ * layer has no gradients (the NativeScript CSS subset is the one that forced
+ * this). Returns a `#rrggbb` string.
+ */
+export declare function flattenAvatarGradient(color: AdwAvatarColor): string;

package/lib/types/avatar.spec.d.ts

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

package/lib/types/banner.d.ts

@@ -0,0 +1,104 @@
+/**
+ * `AdwBannerButtonStyle` as a string union — the two enum nicks
+ * (adw-banner.c:23-35, Since 1.7).
+ */
+export type AdwBannerButtonStyle = 'default' | 'suggested';
+/** Both `AdwBannerButtonStyle` members, in enum order. */
+export declare const ADW_BANNER_BUTTON_STYLES: readonly AdwBannerButtonStyle[];
+/**
+ * Every style class `button-style` MANAGES on the banner button.
+ *
+ * A renderer swaps within this set and leaves every other class alone — the C
+ * only ever adds or removes `suggested-action` (:766, :769), it never rewrites
+ * the button's class list.
+ */
+export declare const ADW_BANNER_BUTTON_STYLE_CLASSES: readonly string[];
+/** The five `Adw.Banner` properties, as a renderer holds them. */
+export interface AdwBannerProps {
+    /** `title` — the message. Pango markup when {@link useMarkup}. */
+    title: string;
+    /** `button-label` — empty means no button. */
+    buttonLabel: string;
+    /** `revealed` — whether the strip is on screen. */
+    revealed: boolean;
+    /** `use-markup` — whether {@link title} is Pango markup. */
+    useMarkup: boolean;
+    /** `button-style` — grey (`'default'`) or `.suggested-action`. */
+    buttonStyle: AdwBannerButtonStyle;
+}
+/**
+ * The property defaults a freshly constructed `Adw.Banner` has, straight from
+ * the `GParamSpec`s.
+ *
+ * Two of these are the whole reason this module exists, and both are easy to get
+ * backwards from the rendered widget rather than from the source: `revealed` is
+ * FALSE (:456-459) and `use-markup` is TRUE (:422-425).
+ */
+export declare const ADW_BANNER_DEFAULTS: Readonly<AdwBannerProps>;
+/** Whether `value` is one of the two `AdwBannerButtonStyle` nicks. */
+export declare function isBannerButtonStyle(value: unknown): value is AdwBannerButtonStyle;
+/**
+ * The button style for a renderer-supplied string — an HTML attribute, an XML
+ * property, a JSON config.
+ *
+ * Anything that is not a nick becomes `'default'`. That is NOT the C setter's
+ * behaviour and cannot be: `adw_banner_set_button_style` guards the ENUM range
+ * (:756-757) and returns without changing anything, because by the time it runs
+ * the value is already an `AdwBannerButtonStyle`. A string never becomes one, so
+ * there is nothing to keep — falling back to the property default is what
+ * GObject itself does when an invalid nick reaches `g_object_set`.
+ */
+export declare function parseBannerButtonStyle(value: string | null | undefined): AdwBannerButtonStyle;
+/**
+ * The style classes the banner button carries for `style` —
+ * `adw_banner_set_button_style`'s switch (:764-774).
+ */
+export declare function bannerButtonStyleClasses(style: AdwBannerButtonStyle): readonly string[];
+/**
+ * Whether the action button is shown: `gtk_widget_set_visible (button, label &&
+ * label[0])` (:663).
+ *
+ * The test is on the FIRST CHARACTER, so it is not a trim and not a truthiness
+ * check on the trimmed value — `" "` is a one-character label and its button is
+ * shown, blank-looking though it is. A renderer that trimmed here would silently
+ * drop a button GTK draws.
+ */
+export declare function bannerButtonVisible(label: string | null | undefined): boolean;
+/**
+ * The text painted on the action button.
+ *
+ * The template pins the button to `use-underline=True` (adw-banner.ui:33) and
+ * exposes no property to turn it off, so an `_` in `button-label` is ALWAYS an
+ * accelerator marker — `"_Resume"` reads `Resume` with an underlined R. A
+ * renderer with no accelerator layer wants the marker gone, which is what
+ * {@link stripMnemonic} returns.
+ *
+ * The TITLE deliberately has no counterpart here: the same template pins the
+ * title label to `use-underline=False` (adw-banner.ui:20), so a title keeps
+ * every underscore it was given. Passing a title through this function would be
+ * a bug, not a symmetry.
+ */
+export declare function bannerButtonText(label: string): string;
+/** What one banner derivation tells a renderer to draw. */
+export interface AdwBannerRenderState {
+    /** Whether the strip is on screen (`GtkRevealer:reveal-child`, :817). */
+    revealed: boolean;
+    /** Whether {@link AdwBannerProps.title} is to be read as Pango markup. */
+    useMarkup: boolean;
+    /** Whether the action button is in the tree (:663). */
+    buttonVisible: boolean;
+    /** The button's label with mnemonic markers removed. */
+    buttonText: string;
+    /** The style classes `button-style` puts on the button (:764-774). */
+    buttonClasses: readonly string[];
+}
+/**
+ * The full render state for a banner, filling every unset property from
+ * {@link ADW_BANNER_DEFAULTS}.
+ *
+ * Takes a `Partial` on purpose: a renderer reading attributes has "not set" as a
+ * real state, and the whole point of this module is that "not set" resolves to
+ * the libadwaita default rather than to whatever the renderer's field
+ * initialiser happened to be.
+ */
+export declare function bannerRenderState(props?: Partial<AdwBannerProps>): AdwBannerRenderState;

package/lib/types/banner.spec.d.ts

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

package/lib/types/button-content.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The style class `AdwButtonContent` stamps on its parent button (:115) and
+ * removes again on unroot (:126).
+ */
+export declare const BUTTON_CONTENT_STYLE_CLASS = "image-text-button";
+/** The icon `GtkImage` falls back to for an empty `icon-name` (:355-356). */
+export declare const BUTTON_CONTENT_FALLBACK_ICON = "image-missing";
+/** How `can-shrink` reaches the label — `PangoEllipsizeMode` as a string union. */
+export type ButtonContentEllipsize = 'none' | 'end';
+/** The four `AdwButtonContent` properties, as a renderer holds them. */
+export interface AdwButtonContentProps {
+    /** `icon-name` — an icon-theme name. Empty means {@link BUTTON_CONTENT_FALLBACK_ICON}. */
+    iconName: string;
+    /** `label` — empty hides the label node. */
+    label: string;
+    /** `use-underline` — whether `_` marks a mnemonic in {@link label}. */
+    useUnderline: boolean;
+    /** `can-shrink` — whether the label ellipsizes rather than widening the button. */
+    canShrink: boolean;
+}
+/**
+ * The property defaults a freshly constructed `AdwButtonContent` has, straight
+ * from the `GParamSpec`s. All four are the empty/false end of their type.
+ */
+export declare const ADW_BUTTON_CONTENT_DEFAULTS: Readonly<AdwButtonContentProps>;
+/**
+ * Whether the icon slot is empty — the `!icon_name[0]` test at :355.
+ *
+ * The one icon question that does not depend on how a renderer represents the
+ * icon: a name is empty or it is not, an SVG string is empty or it is not. Kept
+ * separate from {@link buttonContentIconName} so the NativeScript port, which
+ * holds SVG source rather than theme names, has something in core to ask.
+ */
+export declare function buttonContentIconIsEmpty(icon: string): boolean;
+/**
+ * The icon-theme name the image is actually set from: `icon_name`, or
+ * `image-missing` when it is empty (:355-358).
+ *
+ * UPSTREAM CONTRADICTION — the code and the docs disagree, and this follows the
+ * CODE. Both doc comments say the icon "is not shown" when `icon-name` is empty
+ * (:228 on the property, :343 on the setter), but nothing in the widget ever
+ * hides `self->icon`: `gtk_widget_set_visible` is called on the LABEL (:300,
+ * :398) and never on the image, `init` sets the image to `image-missing` while
+ * `icon_name` is still `""` (:284, :294), and the setter re-applies that
+ * fallback for every empty value (:355-356). A default-constructed
+ * `AdwButtonContent` therefore draws the broken-image glyph. Both ports followed
+ * the prose and hid the icon; a vector written from the prose would have pinned
+ * that guess and shipped it under the word "conformance", which is the one thing
+ * these tables must not do.
+ */
+export declare function buttonContentIconName(iconName: string): string;
+/**
+ * Whether the label node is in the tree: `gtk_widget_set_visible (self->label,
+ * label[0])` (:398).
+ *
+ * First character, not truthiness and not a trim — `" "` is a label and its node
+ * is shown, exactly as with the banner button.
+ */
+export declare function buttonContentLabelVisible(label: string): boolean;
+/**
+ * Whether the icon takes the box's free space: `gtk_widget_set_hexpand
+ * (self->icon, !label[0])` (:399), matching the `TRUE` init sets while the label
+ * is still empty (:296).
+ *
+ * The complement of {@link buttonContentLabelVisible} by construction, and named
+ * for what it DOES rather than derived at each call site: with no label the icon
+ * expands and so centres itself inside the button; with a label the pair sits
+ * together under the box's `halign: CENTER` (:289).
+ */
+export declare function buttonContentIconExpands(label: string): boolean;
+/**
+ * The text painted on the label, with mnemonic markers removed when
+ * `use-underline` is set (:442).
+ *
+ * Default FALSE (:253-256), so an underscore survives unless the app asked for
+ * mnemonics — the opposite default to the banner's action button, which its
+ * template pins to TRUE.
+ */
+export declare function buttonContentLabelText(label: string, useUnderline: boolean): string;
+/**
+ * The label's `PangoEllipsizeMode` for `can-shrink` — `END` or `NONE`
+ * (:489-491), which is also how the getter reads the property back (:462).
+ */
+export declare function buttonContentEllipsize(canShrink: boolean): ButtonContentEllipsize;
+/**
+ * One entry of the ancestor chain `adw_button_content_root` walks, nearest
+ * first, tagged by the only distinction the C makes.
+ *
+ * `'button'` is a `GtkButton` (or any subclass); `'menu-button'` and
+ * `'split-button'` are `GtkMenuButton` and `AdwSplitButton`, neither of which
+ * derives from `GtkButton` — `AdwSplitButton` is a `GtkWidget`
+ * (adw-split-button.c:112), which is exactly why it cannot be found by
+ * `gtk_widget_get_ancestor (…, GTK_TYPE_BUTTON)` and needs the retarget.
+ * `'other'` is any other container.
+ */
+export type ButtonContentAncestor = 'button' | 'menu-button' | 'split-button' | 'other';
+/**
+ * Which ancestor receives {@link BUTTON_CONTENT_STYLE_CLASS}, as an INDEX into
+ * `ancestors` (nearest first), or `null` when there is no button ancestor.
+ *
+ * `adw_button_content_root` (:108-116) takes the nearest `GtkButton`, then makes
+ * ONE substitution: if that button's DIRECT parent is an `AdwSplitButton`, the
+ * class goes on the split button instead (:112-113), because the split button is
+ * the node the stylesheet styles (`splitbutton.image-text-button > button`,
+ * _buttons.scss:499-507). Inside a `GtkMenuButton` no substitution happens, so
+ * the menu button's INTERNAL button keeps the class — which is what the class
+ * docs describe (:56-59).
+ *
+ * `null` is this port's answer to a case the C does not survive: with no button
+ * ancestor at all `gtk_widget_get_ancestor` returns `NULL`, and the very next
+ * lines call `gtk_widget_get_parent (NULL)` and `gtk_widget_add_css_class (NULL,
+ * …)` (:112-115), which are two `CRITICAL`s. A renderer has nothing to style,
+ * and saying so is better than reproducing a crash.
+ */
+export declare function buttonContentStyleTargetIndex(ancestors: readonly ButtonContentAncestor[]): number | null;
+/** What one button-content derivation tells a renderer to draw. */
+export interface AdwButtonContentRenderState {
+    /** The icon-theme name the image node shows (:355-358). */
+    iconName: string;
+    /** Whether {@link iconName} is the empty-slot fallback rather than an app value. */
+    iconIsFallback: boolean;
+    /** Whether the icon takes the box's free space (:399). */
+    iconExpands: boolean;
+    /** Whether the label node is in the tree (:398). */
+    labelVisible: boolean;
+    /** The label text, mnemonic markers resolved (:442). */
+    labelText: string;
+    /** The label's ellipsize mode (:489-491). */
+    ellipsize: ButtonContentEllipsize;
+    /** The style class the parent button carries while this content is rooted (:115). */
+    parentClass: string;
+}
+/**
+ * The full render state for a button content, filling every unset property from
+ * {@link ADW_BUTTON_CONTENT_DEFAULTS}.
+ *
+ * `parentClass` is constant, and is in the state anyway so a renderer takes the
+ * class from the same call that gives it the rest — the whole defect this module
+ * fixes was a renderer never being handed that string at all.
+ */
+export declare function buttonContentRenderState(props?: Partial<AdwButtonContentProps>): AdwButtonContentRenderState;

package/lib/types/button-content.spec.d.ts

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