docs(api): inline svg/emoji recipes, blank-anchor @throws, emoji publish setup (#222)

* refactor(api): name paragraph inline svg/emoji adders inlineSvgIcon/inlineEmoji

ParagraphBuilder's inline adders now follow the existing inlineText /
inlineImage / inlineLink convention: svgIcon -> inlineSvgIcon and
emoji -> inlineEmoji (all overloads). RichText keeps its bare svgIcon /
emoji names, which are internally consistent there. The API is unreleased
(@SInCE 1.9.0), so there is no deprecation bridge.

Also adds two InlineSvgRenderTest cases for inline-SVG paths that only
single-line paragraphs reached before: an icon that wraps onto a later
line (asserting that line grows to the icon via lineHeight > textLineHeight)
and an icon inside a paragraph that splits across a page break (it still
paints on its head page).

* docs(api): add inline SVG/emoji recipes and document the blank-anchor throw

- New "Inline SVG icons" and "Emoji / shortcodes" sections in the
  rich-text recipe, restoring the "every shipped feature has a recipe"
  guarantee; both recipe indexes updated.
- @throws IllegalArgumentException on every link-by-anchor builder method
  (linkTo / inlineLinkTo / imageLinkTo / shapeLinkTo across RichText and the
  Paragraph / Barcode / Ellipse / Image / Line / Shape / Table builders),
  spelling out that a blank anchor throws while the anchor(...) setter clears.
- Correct EmojiLibrary's class doc: it bundles the Noto Emoji set (SIL OFL
  1.1), not a "small jdecked/twemoji starter set".

* build(release): align central-publishing to 0.11.0, add publish-emoji workflow

Bump central-publishing-maven-plugin 0.10.0 -> 0.11.0 in the emoji, fonts
and bundle standalone poms to match the engine pom (#219); they share no
parent, so the literal is swept by hand. Add publish-emoji.yml mirroring
publish-fonts.yml (emoji-v* tag, -f emoji/pom.xml, -P release) so
graph-compose-emoji publishes to Central independently — matching the
emoji-v* prose already in emoji/pom.xml.

Author: DemchaAV

.github/workflows/publish-emoji.yml

@@ -0,0 +1,67 @@
+name: Publish emoji to Maven Central
+
+# Publishes the graph-compose-emoji companion artifact to Maven Central,
+# independently of the engine. The bundled Noto Emoji glyphs change rarely, so
+# they release on their OWN tag line (emoji-v*) — pushing an engine v* tag
+# never touches them, and re-publishing emoji does not require an engine
+# release. This mirrors publish-fonts.yml but targets emoji/pom.xml.
+#
+# Tagging: emoji-vX.Y.Z (e.g. emoji-v1.0.0). The emoji artifact carries its
+# own independent version (see emoji/pom.xml) — keep it in sync with the tag.
+#
+# Human prerequisites are identical to publish.yml (GPG key + Central token
+# secrets). See docs/contributing/release-process.md for the runbook.
+
+on:
+  push:
+    tags:
+      - 'emoji-v*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Existing emoji-v*-prefixed tag to (re-)publish'
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  publish-emoji:
+    name: Publish ${{ github.ref_name }} to Maven Central
+    runs-on: ubuntu-latest
+    # Only ship plain semver tags (emoji-vX.Y.Z) to Central; pre-release
+    # suffixes ship nowhere from here.
+    if: |
+      github.event_name == 'workflow_dispatch' ||
+      (!contains(github.ref, '-rc') && !contains(github.ref, '-alpha') && !contains(github.ref, '-beta') && !contains(github.ref, '-snapshot'))
+    env:
+      JAVA_TOOL_OPTIONS: -Djava.awt.headless=true
+
+    steps:
+      - name: Check out repository at tag
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.inputs.tag || github.ref }}
+
+      - name: Set up Temurin JDK 17 with Central credentials and GPG key
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: '17'
+          cache: maven
+          server-id: central
+          server-username: CENTRAL_USERNAME
+          server-password: CENTRAL_TOKEN
+          gpg-private-key: ${{ secrets.MAVEN_GPG_PRIVATE_KEY }}
+          gpg-passphrase: MAVEN_GPG_PASSPHRASE
+
+      - name: Publish emoji to Maven Central
+        # Activates the emoji module's release profile (sources + javadoc +
+        # gpg sign + central-publishing) and flips gpg.skip=false. Blocks
+        # until Sonatype's validator confirms validation.
+        run: ./mvnw -B -ntp -f emoji/pom.xml -P release -Dgpg.skip=false deploy
+        env:
+          CENTRAL_USERNAME: ${{ secrets.CENTRAL_USERNAME }}
+          CENTRAL_TOKEN: ${{ secrets.CENTRAL_TOKEN }}
+          MAVEN_GPG_PASSPHRASE: ${{ secrets.MAVEN_GPG_PASSPHRASE }}

bundle/pom.xml

@@ -67,7 +67,7 @@
         <graphcompose.fonts.version>1.0.0</graphcompose.fonts.version>
 
         <maven.gpg.plugin.version>3.2.8</maven.gpg.plugin.version>
-        <central.publishing.plugin.version>0.10.0</central.publishing.plugin.version>
+        <central.publishing.plugin.version>0.11.0</central.publishing.plugin.version>
 
         <gpg.skip>true</gpg.skip>
     </properties>

docs/recipes.md

@@ -19,7 +19,7 @@ authoring API; public application code should not import
 | [Layered page design](recipes/layered-page-design.md) | Choosing between page backgrounds, rows, layer stacks, and canvases |
 | [Absolute placement](recipes/absolute-placement.md) | `addCanvas` + `position(x, y)` for pixel-precise certificates and badges |
 | [Tables](recipes/tables.md) | Row span, zebra rows, totals row, repeated header on page break |
-| [Rich text](recipes/rich-text.md) | `RichText` mixed-style runs, inline links/images/shapes, checkboxes |
+| [Rich text](recipes/rich-text.md) | `RichText` mixed-style runs, inline links/images/shapes, SVG icons, emoji shortcodes, checkboxes |
 | [Lists](recipes/lists.md) | `addList`, marker customisation, nested lists with per-depth markers |
 | [Timelines](recipes/timelines.md) | `addTimeline`: markers on a connector rail, geometry and text-style controls |
 | [Barcodes](recipes/barcodes.md) | QR / Code 128 / EAN / UPC and friends, tinting, quiet zone |

docs/recipes/README.md

@@ -8,7 +8,7 @@ API, with copy-pasteable snippets verified against the current release.
 | Recipe | Covers |
 |---|---|
 | [charts.md](charts.md) | Native vector bar / line / area / pie-donut charts: data–spec–style layers, axis & grid toggles, point markers, value-label halos, legend placement, translucent area fills |
-| [rich-text.md](rich-text.md) | `RichText` mixed-style runs in one paragraph: bold/accent/styled segments, inline links, inline images, inline shapes and checkboxes |
+| [rich-text.md](rich-text.md) | `RichText` mixed-style runs in one paragraph: bold/accent/styled segments, inline links, inline images, inline SVG icons, emoji shortcodes, inline shapes and checkboxes |
 | [lists.md](lists.md) | `addList`: quick bulleted lists, marker customisation, nested lists with per-depth markers, spacing and styled items |
 | [timelines.md](timelines.md) | `addTimeline`: markers (dot / circle / numbered / square) on a connector rail, geometry and text-style controls, pagination opt-ins |
 | [keep-together.md](keep-together.md) | `keepTogether()` / `keepEntriesTogether()` — blocks that relocate whole instead of orphaning a heading at a page break |

docs/recipes/rich-text.md

@@ -98,6 +98,52 @@ relative to the surrounding line (`CENTER` by default); the full
 overload adds a `baselineOffset` and `DocumentLinkOptions` for a
 clickable inline image.
 
+## Inline SVG icons
+
+A parsed `SvgIcon` sits on the text baseline like a word, drawn as crisp
+vector layers that carry their own colours — so it renders independently
+of the active font's glyph coverage. `size` is the glyph height in points;
+the width follows the icon's aspect ratio.
+
+```java
+import com.demcha.compose.document.svg.SvgIcon;
+
+SvgIcon star = SvgIcon.parse(
+        "<svg viewBox='0 0 24 24'>"
+      + "  <path d='M12 2l3 7h7l-5.5 4 2 7L12 16l-6.5 4 2-7L2 9h7z' fill='#f5b301'/>"
+      + "</svg>");
+
+section.addRich(rich -> rich
+        .plain("Rated ")
+        .svgIcon(star, 11)
+        .plain(" by reviewers."));
+```
+
+On `ParagraphBuilder` the equivalent call is `inlineSvgIcon(icon, size)`;
+both take `alignment` / `baselineOffset` / link overloads and a clickable
+form via `DocumentLinkOptions`. `SvgIcon.parse(String)` reads inline SVG
+markup; `SvgIcon.read(Path)` loads it from a file.
+
+## Emoji / shortcodes
+
+`emoji(":code:")` resolves a GitHub-style shortcode to an inline colour
+glyph through `EmojiLibrary`. Resolution is lenient: an unknown shortcode —
+or no emoji set on the classpath — falls back to the literal text, the way
+GitHub renders an unrecognised `:code:`.
+
+```java
+section.addRich(rich -> rich
+        .plain("Deploy ")
+        .emoji(":white_check_mark:", 11)
+        .plain(" succeeded ")
+        .emoji(":rocket:", 11));
+```
+
+On `ParagraphBuilder` the call is `inlineEmoji(":code:", size)`. Glyphs ship
+in the optional, independently-versioned `graph-compose-emoji` companion
+artifact (Noto Emoji, SIL OFL 1.1) — add it to the classpath to resolve
+shortcodes; the engine itself carries no emoji art.
+
 ## Inline shapes and checkboxes
 
 Geometric figures drawn from geometry — not font glyphs — so they render

emoji/pom.xml

@@ -80,7 +80,7 @@
         <maven.source.plugin.version>3.4.0</maven.source.plugin.version>
         <maven.javadoc.plugin.version>3.12.0</maven.javadoc.plugin.version>
         <maven.gpg.plugin.version>3.2.8</maven.gpg.plugin.version>
-        <central.publishing.plugin.version>0.10.0</central.publishing.plugin.version>
+        <central.publishing.plugin.version>0.11.0</central.publishing.plugin.version>
 
         <!-- See the engine pom: opted in via -Dgpg.skip=false on the publish workflow. -->
         <gpg.skip>true</gpg.skip>

fonts/pom.xml

@@ -77,7 +77,7 @@
         <maven.source.plugin.version>3.4.0</maven.source.plugin.version>
         <maven.javadoc.plugin.version>3.12.0</maven.javadoc.plugin.version>
         <maven.gpg.plugin.version>3.2.8</maven.gpg.plugin.version>
-        <central.publishing.plugin.version>0.10.0</central.publishing.plugin.version>
+        <central.publishing.plugin.version>0.11.0</central.publishing.plugin.version>
 
         <!-- See the engine pom: opted in via -Dgpg.skip=false on the publish workflow. -->
         <gpg.skip>true</gpg.skip>

src/main/java/com/demcha/compose/document/dsl/BarcodeBuilder.java

@@ -246,6 +246,7 @@ public BarcodeBuilder linkTarget(DocumentLinkTarget linkTarget) {
      *
      * @param anchor target anchor name
      * @return this builder
+     * @throws IllegalArgumentException if {@code anchor} is blank
      * @since 1.9.0
      */
     public BarcodeBuilder linkTo(String anchor) {

src/main/java/com/demcha/compose/document/dsl/EllipseBuilder.java

@@ -158,6 +158,7 @@ public EllipseBuilder linkTarget(DocumentLinkTarget linkTarget) {
      *
      * @param anchor target anchor name
      * @return this builder
+     * @throws IllegalArgumentException if {@code anchor} is blank
      * @since 1.9.0
      */
     public EllipseBuilder linkTo(String anchor) {

src/main/java/com/demcha/compose/document/dsl/ImageBuilder.java

@@ -192,6 +192,7 @@ public ImageBuilder linkTarget(DocumentLinkTarget linkTarget) {
      *
      * @param anchor target anchor name
      * @return this builder
+     * @throws IllegalArgumentException if {@code anchor} is blank
      * @since 1.9.0
      */
     public ImageBuilder linkTo(String anchor) {