@gjsify/adwaita-nativescript 0.36.0 → 0.38.0

package/lib/types/widgets/view-switcher-model.d.ts

@@ -5,10 +5,8 @@ import type { AdwViewSwitcherPageInit, ViewSwitcherStateChange } from '@gjsify/a
  * One page registered with a view switcher.
  *
  * Mirrors `AdwViewStackPage`'s properties with their C defaults. `title` and
- * `icon` are NULLABLE on purpose: a page with neither renders no button at all
- * (adw-view-switcher.c:178), and once an absent title has been flattened to `''`
- * that rule is no longer expressible — which is why the old shape, with a
- * required `title: string`, could not implement it.
+ * `icon` are NULLABLE on purpose: a page with neither renders no button at all, and
+ * an absent title flattened to `''` makes that rule inexpressible.
  *
  * `icon` is an Adwaita symbolic SVG DOCUMENT here, not a GTK icon name: `AdwIcon`
  * rasterises the path data natively. The core treats the field as an opaque
@@ -16,12 +14,7 @@ import type { AdwViewSwitcherPageInit, ViewSwitcherStateChange } from '@gjsify/a
  * the fallback sentinel it hands back.
  */
 export interface AdwViewPage {
-    /**
-     * The switcher button label. ABSENT means the page has none — which is C's
-     * NULL, and the state the button-visibility rule turns on. Spelled as an
-     * optional `string` rather than `string | null` so the existing consumers
-     * that pass a plain `string` keep type-checking unchanged.
-     */
+    /** The switcher button label. ABSENT is C's NULL — the state button visibility turns on. */
     title?: string;
     /** The page content view, shown when this page is selected. */
     content: View;
@@ -47,9 +40,9 @@ export declare function createViewSwitcherBarState(): ViewSwitcherBarState;
 /**
  * Project one NS page onto the core's page init.
  *
- * A page without an explicit `name` gets its POSITION as the name — the NS API
- * has always been positional (`setViews` takes an array), and a stable id is
- * what the name-preserving rebuild needs to keep the selected page selected.
+ * A page without an explicit `name` gets its POSITION as the name: the NS API is
+ * positional (`setViews` takes an array), and the name-preserving rebuild needs a
+ * stable id to keep the selected page selected.
  */
 export declare function viewSwitcherPageSpec(page: AdwViewPage, index: number): AdwViewSwitcherPageInit;
 /** {@link viewSwitcherPageSpec} over a whole page list. */
@@ -57,11 +50,10 @@ export declare function viewSwitcherPageSpecs(pages: readonly AdwViewPage[]): Ad
 /**
  * Resolve the core's icon slot to something `AdwIcon` can rasterise.
  *
- * The core substitutes the NAME `image-missing` for an absent icon
- * (adw-view-switcher-button.c:405). On the browser side that name becomes a CSS
- * mask class; here it has to become the actual symbolic document, so the
- * sentinel is swapped for the vendored `image-missing-symbolic` SVG. Anything
- * else is already an SVG and passes through.
+ * The core substitutes the NAME `image-missing` for an absent icon. On the browser
+ * side that name becomes a CSS mask class; here it has to become the actual
+ * symbolic document, so the sentinel is swapped for the vendored
+ * `image-missing-symbolic` SVG. Anything else is already an SVG and passes through.
  */
 export declare function nsIconSvg(iconName: string): string;
 /**
@@ -76,24 +68,15 @@ export declare function applyViewSwitcherVisibility(pages: readonly AdwViewPage[
 /** Which switcher is asking — the two apply different visibility rules. */
 export type ViewSwitcherKind = 'switcher' | 'inline';
 /**
- * Whether a page gets a button/toggle at all.
+ * Whether a page gets a button/toggle at all. The two switchers genuinely differ:
  *
- * The two switchers genuinely differ, and the difference is easy to miss because
- * only one of them is documented where you would look:
+ * - `AdwViewSwitcher` needs a title or an icon ON TOP OF `visible`
+ *   (`visible && (title != NULL || icon_name != NULL)`).
+ * - `AdwInlineViewSwitcher` gates on `visible` alone, so a page with neither still
+ *   gets an empty toggle.
  *
- * - `AdwViewSwitcher` needs a title or an icon ON TOP OF `visible` —
- *   `gtk_widget_set_visible (button, visible && (title != NULL || icon_name !=
- *   NULL))` (adw-view-switcher.c:178).
- * - `AdwInlineViewSwitcher` does not. `populate_group` gates on `visible` alone
- *   (adw-inline-view-switcher.c:370-378), so a page with neither still gets an
- *   empty toggle.
- *
- * The inline widget inherited the stricter rule and silently dropped toggles
- * libadwaita draws. `@gjsify/adwaita-core` had spelled this out in
- * `buildInlineToggles`' doc and pinned it in `INLINE_TOGGLE_VECTORS` the whole
- * time — the rule just lived in a class that `extends GridLayout`, which no
- * spec can import, so nothing could reach it to check. That is why it is here
- * and not there.
+ * The rule lives here rather than in the widget because a class that `extends
+ * GridLayout` cannot be imported by a spec.
  */
 export declare function switcherButtonVisible(kind: ViewSwitcherKind, modelVisible: boolean, pageVisible: boolean): boolean;
 /** The data half of the `notify::selected` event (minus NS's `eventName`/`object`). */

package/lib/types/widgets/wrap-box-layout.d.ts

@@ -1,36 +1,25 @@
 import { normalizeWrapBoxSpacing, type AdwWrapBoxJustify, type AdwWrapBoxOrientation, type AdwWrapBoxPackDirection, type AdwWrapPolicy } from '@gjsify/adwaita-core';
 export { normalizeWrapBoxSpacing };
-/**
- * `Adw.WrapBox:child-spacing` / `:line-spacing` default, in DIPs.
- *
- * Both are `g_param_spec_int (…, 0, G_MAXINT, 0, …)` — adw-wrap-box.c:285-287
- * and :393-395. The port used to default both to 6, so identical markup was
- * looser on a phone than in the browser and an EMPTY wrap box was already 12
- * DIPs tall.
- */
+/** `Adw.WrapBox:child-spacing` / `:line-spacing` default, in DIPs. Both are 0 in C. */
 export declare const DEFAULT_WRAP_BOX_SPACING = 0;
 /**
  * Whether writing `next` over `current` is a change the widget must act on.
  *
- * The comparison happens AFTER the clamp (adw-wrap-box.c:592-593, :930-931), so
- * a negative value written over a spacing of 0 is an early return: it neither
- * reaches the layout nor notifies. On this port the same predicate decides
- * whether every child's margin is rewritten.
+ * The comparison happens AFTER the clamp, so a negative value written over a
+ * spacing of 0 is an early return: it neither reaches the layout nor notifies. Here
+ * the same predicate decides whether every child's margin is rewritten.
  */
 export declare function wrapBoxSpacingChanges(current: number, next: unknown): boolean;
 /**
  * The uniform margin that gives a `FlexboxLayout` child its share of the gaps.
  *
- * NativeScript has no gap property on any layout — `Style` carries no
- * `columnGap`/`rowGap` — so the inter-item spacing has to come out of the
- * children: half of it on each facing edge adds up to the whole gap between any
- * two neighbours. The margin string is NS's `top right bottom left` shorthand.
+ * Half the spacing on each facing edge adds up to the whole gap between any two
+ * neighbours. The margin string is NS's `top right bottom left` shorthand.
  *
- * This is the one place the port is knowingly looser than libadwaita: the halves
- * on the OUTER edges are an inset `Adw.WrapBox` does not have. It is invisible
- * at the default spacing of 0 and bounded by half a gap otherwise, where the
- * alternative — negative margins on the container — is not something the NS CSS
- * subset can be trusted with.
+ * Knowingly looser than libadwaita: the halves on the OUTER edges are an inset
+ * `Adw.WrapBox` does not have. Invisible at the default spacing of 0 and bounded by
+ * half a gap otherwise; the alternative is negative margins on the container, which
+ * the NS CSS subset cannot be trusted with.
  */
 export declare function wrapBoxChildMargin(childSpacing: number, lineSpacing: number): string;
 /** The `FlexboxLayout` knobs a wrap box's properties resolve to. */
@@ -63,14 +52,12 @@ export interface WrapBoxFlexInput {
  * The CONTAINER half of the decision, resolved onto `FlexboxLayout`.
  *
  * The line DECISION is `resolveWrapBoxLine` in `@gjsify/adwaita-core`, held to
- * `WRAP_BOX_LINE_VECTORS` — this function only maps its answer onto the knobs NS
- * has, exactly as the browser element maps it onto CSS.
+ * `WRAP_BOX_LINE_VECTORS`; this function only maps its answer onto the knobs NS has.
  *
- * Like a flex container, `FlexboxLayout` has ONE `justifyContent` for every
- * line, so it can only carry the COMPLETE-line rule. NativeScript offers no
- * `:only-child` selector and no generated content, so the final-line rule has no
- * container-level expression at all; what it CAN reach is the single-child case,
- * through {@link wrapBoxChildFlex}.
+ * `FlexboxLayout` has ONE `justifyContent` for every line, so it can only carry the
+ * COMPLETE-line rule. NativeScript offers no `:only-child` selector and no generated
+ * content, so the final-line rule has no container-level expression at all; the
+ * single-child case is reached through {@link wrapBoxChildFlex}.
  */
 export declare function wrapBoxFlexStyle(input: WrapBoxFlexInput): WrapBoxFlexStyle;
 /** What one child of the box gets set on it. */
@@ -83,15 +70,13 @@ export interface WrapBoxChildFlex {
 /**
  * The PER-CHILD half of the decision, which the container knobs cannot carry.
  *
- * Two of libadwaita's rules are facts about a child rather than about the box,
- * and a single `justifyContent` has nowhere to put either. A box with exactly
- * ONE child has one line, that line is the LAST one, and its child is alone on
- * it — so it is governed by `justify-last-line`, and `spread` STRETCHES it
- * rather than spreading anything (`n_children > 1` guards the keep-at-minimum
- * branch, adw-wrap-layout.c:338; adw-wrap-box.c:349-352 says so outright).
+ * A box with exactly ONE child has one line, that line is the LAST one, and its
+ * child is alone on it — so it is governed by `justify-last-line`, and `spread`
+ * STRETCHES it rather than spreading anything (C guards the keep-at-minimum branch
+ * with `n_children > 1`).
  *
- * `childCount` is the box's own child count, which is the most a renderer knows
- * without a layout pass: 1 means the lone-child-on-the-final-line case exactly,
- * anything more means at least one complete line.
+ * `childCount` is the box's own child count, the most a renderer knows without a
+ * layout pass: 1 is the lone-child-on-the-final-line case exactly, anything more
+ * means at least one complete line.
  */
 export declare function wrapBoxChildFlex(input: WrapBoxFlexInput, childCount: number): WrapBoxChildFlex;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-nativescript",
-    "version": "0.36.0",
+    "version": "0.38.0",
     "description": "Native Adwaita widgets for the NativeScript runtime — real NativeScript components (StackLayout/GridLayout/Switch/Label) styled like Libadwaita, not a webview",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -47,10 +47,10 @@
         "design-system"
     ],
     "dependencies": {
-        "@gjsify/adwaita-core": "^0.36.0",
-        "@gjsify/adwaita-fonts": "^0.36.0",
-        "@gjsify/adwaita-icons": "^0.36.0",
-        "@gjsify/native-platform": "^0.36.0"
+        "@gjsify/adwaita-core": "^0.38.0",
+        "@gjsify/adwaita-fonts": "^0.38.0",
+        "@gjsify/adwaita-icons": "^0.38.0",
+        "@gjsify/native-platform": "^0.38.0"
     },
     "peerDependencies": {
         "@nativescript/core": "*"
@@ -61,8 +61,8 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.36.0",
-        "@gjsify/unit": "^0.36.0",
+        "@gjsify/cli": "^0.38.0",
+        "@gjsify/unit": "^0.38.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },

package/src/theme/adwaita.css

@@ -1371,6 +1371,66 @@ Page.adw-window {
     margin: 0;
 }
 
+/* ===== Shortcut label (keycaps) =====
+ *
+ * libadwaita: `_shortcuts-dialog.scss:33-58` — 6 spacing at BOTH levels, keycaps
+ * filled with 10% of the current colour, an inset bottom edge, 6 radius, 6
+ * padding, 20 minimum width, and `> .dimmed { padding: 6 0 }` so a separator
+ * lines up with the caps beside it.
+ *
+ * Two substitutions the NS subset forces, both visible rather than silent:
+ *   - `color-mix(in srgb, currentColor 10%, transparent)` has no NS spelling, so
+ *     the fill is written out per scheme against that scheme's foreground;
+ *   - `box-shadow: inset 0 -2px` has none either (NS box-shadow is outer-only),
+ *     so the key's bottom edge is a 2 bottom BORDER. It occupies layout where the
+ *     shadow did not, which grows a keycap by 2 — the closest the subset gets.
+ */
+
+.adw-shortcut-label {
+    background-color: transparent;
+}
+
+/* The 6 that GTK gets from `border-spacing`, which puts it BETWEEN children
+ * only. NS has no `gap` and the subset no `:first-child`, so the widget adds
+ * this class to every child after the first. */
+.adw-shortcut-label-spaced {
+    margin-left: 6;
+}
+
+/* Scoped, because `keycap` is libadwaita's generic name and this theme is one
+ * flat file — an app with its own `.keycap` must not inherit these metrics. */
+.adw-shortcut-label .keycap {
+    background-color: rgba(0, 0, 0, 0.08);
+    border-radius: 6;
+    border-bottom-width: 2;
+    border-bottom-color: rgba(0, 0, 6, 0.07);
+    padding: 6;
+    min-width: 20;
+}
+
+.adw-shortcut-label-cap-text {
+    color: rgba(0, 0, 0, 0.8);
+    font-size: 14;
+    text-align: center;
+}
+
+/* `%s <small><b>%s</b></small>` (adw-shortcut-label.c:195) — the L/R marker is
+ * smaller and bold, and rides inside its keycap rather than beside it. */
+.adw-shortcut-label-side {
+    color: rgba(0, 0, 0, 0.8);
+    font-size: 11;
+    font-weight: 700;
+    margin-left: 2;
+}
+
+/* `dim_label` — `--dim-opacity: 55%` (`_colors.scss:319`). */
+.adw-shortcut-label .dimmed {
+    color: rgba(0, 0, 0, 0.8);
+    font-size: 14;
+    opacity: 0.55;
+    padding: 6 0 6 0;
+}
+
 /* ===== Dark variant (.ns-dark on the page/root) ===== */
 
 .ns-dark .adw-window,
@@ -1893,3 +1953,20 @@ Page.ns-dark.adw-window {
 .ns-dark .adw-preferences-dialog-close {
     color: rgba(255, 255, 255, 0.55);
 }
+
+/* ===== Dark: shortcut label =====
+ * The fill is 10% of the foreground, which is `#ffffff` here rather than the
+ * light scheme's near-black — the one reason these rules exist at all. The
+ * bottom edge follows `--card-shade-color`, which darkens in the dark theme
+ * (`_theme.scss:28`: 0.36 against the light scheme's 0.07). */
+
+.ns-dark .adw-shortcut-label .keycap {
+    background-color: rgba(255, 255, 255, 0.1);
+    border-bottom-color: rgba(0, 0, 6, 0.36);
+}
+
+.ns-dark .adw-shortcut-label-cap-text,
+.ns-dark .adw-shortcut-label-side,
+.ns-dark .adw-shortcut-label .dimmed {
+    color: #ffffff;
+}