@gjsify/adwaita-core 0.51.1 → 0.52.0

package/lib/types/source.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The read/advance surface a stream tokenizer needs from its host editor — the
+ * exact eight members {@link tokenizeAsm6502} touches, with CodeMirror's
+ * `StringStream` signatures, so passing one satisfies this structurally.
+ *
+ * `next()` returns `string | void` rather than `string | undefined` because
+ * that is what `StringStream` declares, and `void` is not assignable to
+ * `undefined`: narrowing here would reject the very class this exists to accept.
+ */
+export interface AdwSourceTokenStream {
+    /** The text consumed since the current token started. */
+    current(): string;
+    /** Consume the whitespace run ahead of the cursor; true if any was there. */
+    eatSpace(): boolean;
+    /** Consume while characters match; true if any were consumed. */
+    eatWhile(match: string | RegExp | ((ch: string) => boolean)): boolean;
+    /** True at the end of the line. */
+    eol(): boolean;
+    /** Read one character and advance. */
+    next(): string | void;
+    /** The character at the cursor, without advancing. */
+    peek(): string | undefined;
+    /** Jump to the end of the line. */
+    skipToEnd(): void;
+    /** True at the start of the line — what makes a bare word a label. */
+    sol(): boolean;
+}
+/** The token classes {@link tokenizeAsm6502} can emit. */
+export type AdwSourceTokenClass = 'comment' | 'directive' | 'identifier' | 'label' | 'number' | 'opcode' | 'operator' | 'register' | 'string';
+/** The 56 official NMOS 6502 mnemonics (uppercased for case-insensitive match). */
+export declare const ADW_SOURCE_6502_OPCODES: ReadonlySet<string>;
+/** The registers that appear as bare operands (`ASL A`, `LDA $00,X`). */
+export declare const ADW_SOURCE_6502_REGISTERS: ReadonlySet<string>;
+/** Assembler pseudo-ops. `define`/`dcb` are the easy6502 dialect; the rest are
+ *  common cross-assembler directives (with the leading dot handled separately). */
+export declare const ADW_SOURCE_6502_DIRECTIVES: ReadonlySet<string>;
+/** The comment introducer 6502 assembly uses, for an editor's comment command. */
+export declare const ADW_SOURCE_6502_LINE_COMMENT = ";";
+/**
+ * Classify an identifier-shaped token. Pure + side-effect-free so it is unit
+ * testable without a stream at all. `atLineStart` decides whether an unknown
+ * word is a label DEFINITION (column 0) or a symbol REFERENCE.
+ */
+export declare function classifyAsm6502Word(word: string, atLineStart: boolean): AdwSourceTokenClass;
+/**
+ * Tokenize one token from `stream`. Returns a token class or `null` for
+ * whitespace and unclassified punctuation, which is the contract a CodeMirror
+ * `StreamParser.token` wants — and, being typed on
+ * {@link AdwSourceTokenStream}, the contract any other editor can meet too.
+ */
+export declare function tokenizeAsm6502(stream: AdwSourceTokenStream): AdwSourceTokenClass | null;
+/**
+ * The colourable roles a token class maps onto. Fewer than the token classes,
+ * because a language names tokens after its own grammar (`opcode`) while a
+ * colour scheme names them after what a reader sees (`keyword`) — and the
+ * second set is what a scheme, a stylesheet or another language shares.
+ */
+export type AdwSourceSyntaxRole = 'comment' | 'directive' | 'keyword' | 'label' | 'number' | 'operator' | 'register' | 'string';
+/** The roles in the order a generated stylesheet emits them. */
+export declare const ADW_SOURCE_SYNTAX_ROLES: readonly AdwSourceSyntaxRole[];
+/** One colour per {@link AdwSourceSyntaxRole}, as a CSS-parsable colour. */
+export type AdwSourcePalette = Readonly<Record<AdwSourceSyntaxRole, string>>;
+/**
+ * Which role paints a token class. `identifier` maps to `null`: a plain symbol
+ * reference is deliberately UNCOLOURED, taking the view's foreground, exactly
+ * as the native GtkSourceView scheme leaves it.
+ */
+export declare const ADW_SOURCE_6502_TOKEN_ROLES: Readonly<Record<AdwSourceTokenClass, AdwSourceSyntaxRole | null>>;
+/** Light-scheme syntax colours (Adwaita named palette). */
+export declare const ADW_SOURCE_PALETTE_LIGHT: AdwSourcePalette;
+/** Dark-scheme syntax colours (Adwaita named palette). */
+export declare const ADW_SOURCE_PALETTE_DARK: AdwSourcePalette;
+/** Bytes represented per visual line in the hex monitor / hexdump gutter. */
+export declare const ADW_SOURCE_HEX_STRIDE = 16;
+/**
+ * Format a 1-based line number as a 4-digit uppercase hex address, the way the
+ * native GtkSourceView hex gutter renders monitor/hexdump rows: each row advances
+ * the address by `stride` bytes from `start` (the base address of the first row,
+ * e.g. 0x0600 for a 6502 program). `lineNo` is 1-based, per CodeMirror's
+ * `formatNumber` contract.
+ */
+export declare function formatHexAddress(lineNo: number, start: number, stride?: number): string;
+/**
+ * Format a 1-based line number for the normal (decimal) gutter, offset so
+ * `start` is the value shown on the first line — the web twin of the native
+ * renderer's `line + startValue`.
+ */
+export declare function formatLineNumber(lineNo: number, start?: number): string;
+/**
+ * Strip every whitespace character from `text` — the copy-without-spaces
+ * transform the native hex monitor applies so a copied address/byte run pastes
+ * as a compact hex string. Mirrors `text.replace(/\s/g, '')` in the GTK widget.
+ */
+export declare function stripSourceWhitespace(text: string): string;

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

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

package/lib/types/tags.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `AdwPreferencesGroup` -> `adw-preferences-group`.
+ *
+ * THE RULE: the last capital of an acronym run opens the next word, which is why `GLArea`
+ * is `gl-area` and not `g-l-area`. The first version of this function was a naive
+ * `([a-z0-9])([A-Z])` split, and `GtkGLArea` caught it — it produced `gtk-glarea` where
+ * `gtk-host` stamps `gtk-gl-area`, which is why arm 11 of `check-generated-website-data.mjs`
+ * holds the `scripts/` restatement against every row of the generated table rather than
+ * against a handful of tags a corpus happens to use today.
+ *
+ * NOT AN INVERSE OF ANYTHING. Tag -> GType is lossy in exactly that case — `gtk-gl-area`
+ * reads back as `GtkGlArea` and no case rule can know better — so a reverse lookup has to be
+ * a table read backwards, never a second rule.
+ */
+export declare const hostTagOf: (gtype: string) => string;
+/**
+ * `buttonLabel` -> `button-label`.
+ *
+ * NOT AN ALIAS TABLE and not a second transform beside {@link hostTagOf}: a case rule over
+ * the authored property NAME, with no entry to give a name it does not recognise. A markup
+ * renderer's tree builder turns an authored prop into a DOM attribute with this rule, and
+ * arm 13 of `check-generated-website-data.mjs` reads a gallery fence's attributes back
+ * through the `scripts/` restatement of it, so the two stay one spelling rather than two.
+ */
+export declare const attributeOf: (prop: string) => string;
+/**
+ * `maximum-size` -> `maximumSize`: a GObject property name as the JavaScript member a
+ * NativeScript widget declares for it.
+ *
+ * A `.blp` projects its properties under their GIR spelling, because that is what GtkBuilder
+ * and the `<adw-*>` attributes read. The NativeScript port names the same property in camel
+ * case (`Adw.Clamp:maximum-size` is `AdwClamp.maximumSize`), so a builder handed a projected
+ * tree needs this rule to find the member, and without it every hyphenated property of a real
+ * `.blp` is refused as reaching nothing. GObject treats `_` and `-` in a property name as one
+ * separator, so both close a word here. Idempotent on a camel-case name, which is how the
+ * gallery's hand-authored trees already spell theirs.
+ */
+export declare const propertyOf: (name: string) => string;
+/**
+ * `GtkWidget`'s four margins, as the CSS property each one 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
+ * into a stylesheet portably (`attr()` with a type is not in every engine). ONE table for the
+ * two places that do it: `buildSharedTree` in `@gjsify/adwaita-web`, and `sharedTreeHtml` in
+ * `./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>>;

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

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

package/lib/types/tokens.generated.d.ts

@@ -31,4 +31,4 @@ export declare const ADWAITA_DARK_ONLY_TOKENS: readonly string[];
  */
 export declare const ADWAITA_UNRESOLVED_TOKENS: readonly string[];
 /** How many tokens the light contract carries — derived, never typed. */
-export declare const ADWAITA_TOKEN_COUNT = 68;
+export declare const ADWAITA_TOKEN_COUNT = 69;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-core",
-    "version": "0.51.1",
+    "version": "0.52.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",
@@ -17,6 +17,14 @@
         "./tokens": {
             "types": "./lib/types/tokens.d.ts",
             "default": "./lib/esm/tokens.js"
+        },
+        "./tags": {
+            "types": "./lib/types/tags.d.ts",
+            "default": "./lib/esm/tags.js"
+        },
+        "./markup": {
+            "types": "./lib/types/markup.d.ts",
+            "default": "./lib/esm/markup.js"
         }
     },
     "files": [
@@ -36,7 +44,7 @@
         "test:gjs": "gjsify run test.gjs.mjs",
         "test:node": "node test.node.mjs",
         "test:bun": "bun test.node.mjs",
-        "test:deno": "deno run -A --no-lock --node-modules-dir=none test.node.mjs",
+        "test:deno": "deno run -A --no-lock --node-modules-dir=none --min-dep-age=0 test.node.mjs",
         "test:cross-runtime": "gjsify run build:test:node && gjsify run test:node && gjsify run test:bun && gjsify run test:deno"
     },
     "keywords": [
@@ -50,8 +58,8 @@
         "headless"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.51.1",
-        "@gjsify/unit": "^0.51.1",
+        "@gjsify/cli": "^0.52.0",
+        "@gjsify/unit": "^0.52.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },