@sigx/lynx-markdown 0.4.1

package/README.md

@@ -0,0 +1,71 @@
+# @sigx/lynx-markdown
+
+Typed SignalX wrapper around Lynx's `<x-markdown>` XElement.
+
+## Status
+
+**Pre-release** — the wrapper compiles and types cleanly today, but the
+underlying native element ships per-platform on different schedules:
+
+| Platform | First version  | Notes                                          |
+| -------- | -------------- | ---------------------------------------------- |
+| Harmony  | Lynx 3.7.0     | Stable.                                        |
+| Android  | Lynx 3.8.0-rc.0 | Ships as `org.lynxsdk.lynx:lynx_xelement_markdown`. |
+| iOS      | (post-3.8.0)   | Currently only on the upstream `main` branch.  |
+
+On platforms where `<x-markdown>` is not yet registered, the component
+renders nothing at runtime. This package exists so that app code can
+already adopt the typed API surface — once you bump SignalX's Lynx pins
+to a release that includes the native element on your target platforms,
+it starts rendering without code changes.
+
+When the iOS/Android pods land in stable, this README will be updated
+with the matching native dependency wiring (Podfile + gradle).
+
+## Install
+
+```
+pnpm add @sigx/lynx-markdown
+```
+
+## Use
+
+```tsx
+import { Markdown } from '@sigx/lynx-markdown';
+
+export default function ArticleScreen() {
+  return (
+    <Markdown
+      value={"# Hello\n\nThis is **markdown**."}
+      effect="typewriter"
+      onLink={(e) => console.log('tapped', e.detail.url)}
+      onParseEnd={() => console.log('parsed')}
+    />
+  );
+}
+```
+
+## Props
+
+| Prop          | Type                                    | Notes                                               |
+| ------------- | --------------------------------------- | --------------------------------------------------- |
+| `value`       | `string`                                | Markdown source passed as a raw-text child.         |
+| `effect`      | `'typewriter' \| 'none' \| string`      | Maps to the `markdown-effect` attribute.            |
+| `attachments` | `ReadonlyArray<unknown>`                | Maps to `text-mark-attachments`. Engine-defined.    |
+| `class`       | `string`                                |                                                      |
+| `style`       | `string \| Record<string, ...>`         |                                                      |
+| `onLink`      | `(e: MarkdownLinkEvent) => void`        | Underlying `bindlink`.                              |
+| `onImageTap`  | `(e: MarkdownImageTapEvent) => void`    | Underlying `bindimageTap`.                          |
+| `onParseEnd`  | `(e: MarkdownParseEndEvent) => void`    | Underlying `bindparseEnd`.                          |
+
+## Native element methods
+
+The underlying `<x-markdown>` exposes UI methods you can invoke via a
+`main-thread:ref`:
+
+- `getContent`, `getParseResult`, `getImages`
+- `pauseAnimation`, `resumeAnimation`, `clearStatus`
+- `getTextBoundingRect`, `setTextSelection`, `getSelectedText`
+
+These are not yet wrapped by the component; drop down to the intrinsic
+`<x-markdown>` element with a ref to call them directly.

package/dist/Markdown.d.ts

@@ -0,0 +1,30 @@
+import { type Define } from '@sigx/lynx';
+import './jsx-augment.js';
+import type { MarkdownLinkEvent, MarkdownImageTapEvent, MarkdownParseEndEvent } from './jsx-augment.js';
+export type MarkdownEffect = 'typewriter' | 'none' | (string & {});
+export type MarkdownProps = Define.Prop<'value', string, false> & Define.Prop<'effect', MarkdownEffect, false> & Define.Prop<'attachments', ReadonlyArray<unknown>, false> & Define.Prop<'class', string, false> & Define.Prop<'style', string | Record<string, string | number>, false> & Define.Prop<'onLink', (e: MarkdownLinkEvent) => void, false> & Define.Prop<'onImageTap', (e: MarkdownImageTapEvent) => void, false> & Define.Prop<'onParseEnd', (e: MarkdownParseEndEvent) => void, false>;
+/**
+ * Render a markdown document using Lynx's `<x-markdown>` XElement.
+ *
+ * The markdown source is passed via the `value` prop; it is delivered to the
+ * native element as a raw-text child (per the 3.7.0 "raw-text node
+ * optimization" path). Event props use signalx's automatic
+ * `onLink`→`bindlink` mapping in `nodeOps.parseEventProp`, so handlers wire
+ * up without any per-event glue.
+ *
+ * @example
+ * ```tsx
+ * <Markdown
+ *   value={"# Hello\n\nThis is **markdown**."}
+ *   effect="typewriter"
+ *   onLink={(e) => console.log('tapped', e.detail.url)}
+ * />
+ * ```
+ *
+ * @remarks
+ * Availability of the `<x-markdown>` element is platform-dependent — see
+ * `jsx-augment.ts` for the per-platform schedule. On platforms where the
+ * native element is not registered, the engine logs a warning and renders
+ * no view; there is no JS-side feature gate.
+ */
+export declare const Markdown: import("@sigx/runtime-core").ComponentFactory<MarkdownProps, void, {}>;

package/dist/Markdown.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx } from "@sigx/lynx/jsx-runtime";
+import { component } from '@sigx/lynx';
+import './jsx-augment.js';
+/**
+ * Render a markdown document using Lynx's `<x-markdown>` XElement.
+ *
+ * The markdown source is passed via the `value` prop; it is delivered to the
+ * native element as a raw-text child (per the 3.7.0 "raw-text node
+ * optimization" path). Event props use signalx's automatic
+ * `onLink`→`bindlink` mapping in `nodeOps.parseEventProp`, so handlers wire
+ * up without any per-event glue.
+ *
+ * @example
+ * ```tsx
+ * <Markdown
+ *   value={"# Hello\n\nThis is **markdown**."}
+ *   effect="typewriter"
+ *   onLink={(e) => console.log('tapped', e.detail.url)}
+ * />
+ * ```
+ *
+ * @remarks
+ * Availability of the `<x-markdown>` element is platform-dependent — see
+ * `jsx-augment.ts` for the per-platform schedule. On platforms where the
+ * native element is not registered, the engine logs a warning and renders
+ * no view; there is no JS-side feature gate.
+ */
+export const Markdown = component(({ props }) => {
+    return () => (_jsx("x-markdown", { "markdown-effect": props.effect, "text-mark-attachments": props.attachments, class: props.class, style: props.style, bindlink: props.onLink, bindimageTap: props.onImageTap, bindparseEnd: props.onParseEnd, children: props.value ?? '' }));
+});

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import './jsx-augment.js';
+export { Markdown } from './Markdown.js';
+export type { MarkdownProps, MarkdownEffect } from './Markdown.js';
+export type { XMarkdownAttributes, MarkdownLinkEvent, MarkdownLinkEventDetail, MarkdownImageTapEvent, MarkdownImageTapEventDetail, MarkdownParseEndEvent, MarkdownParseEndEventDetail, } from './jsx-augment.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+import './jsx-augment.js';
+export { Markdown } from './Markdown.js';

package/dist/jsx-augment.d.ts

@@ -0,0 +1,83 @@
+/**
+ * JSX intrinsic type augmentation for Lynx's `<x-markdown>` XElement.
+ *
+ * Importing this module registers `'x-markdown'` as a valid JSX intrinsic
+ * with its 3.7.0+ attributes and events. Pulled in automatically by
+ * `@sigx/lynx-markdown`'s entry point so consumers do not need to import
+ * it directly.
+ *
+ * The native element ships per-platform on different schedules:
+ *   - Harmony: available since 3.7.0
+ *   - Android: available since 3.8.0-rc.0 (artifact `lynx_xelement_markdown`)
+ *   - iOS:     not yet in any tagged release; lands on the main branch
+ *               post-3.8.0
+ *
+ * `<x-markdown>` props in JSX still type-check on every platform. At
+ * runtime the SignalX renderer issues a `__CreateElement('x-markdown')`
+ * op unconditionally; on platforms where the native element is not
+ * registered, the underlying engine handles the unknown tag (today it
+ * logs a warning and emits no view). There is no JS-side feature gate
+ * in this package — once you upgrade to a Lynx release that ships the
+ * element on your target platforms, rendering activates automatically.
+ */
+import type { LynxCommonAttributes, LynxEventHandler } from '@sigx/lynx-runtime';
+/** Detail payload of `bindlink` — the engine ships `url` plus optional fields. */
+export interface MarkdownLinkEventDetail {
+    url: string;
+    [k: string]: unknown;
+}
+export interface MarkdownLinkEvent {
+    type: 'link';
+    detail: MarkdownLinkEventDetail;
+}
+/** Detail payload of `bindimageTap`. */
+export interface MarkdownImageTapEventDetail {
+    src: string;
+    [k: string]: unknown;
+}
+export interface MarkdownImageTapEvent {
+    type: 'imageTap';
+    detail: MarkdownImageTapEventDetail;
+}
+/** Detail payload of `bindparseEnd`. */
+export interface MarkdownParseEndEventDetail {
+    [k: string]: unknown;
+}
+export interface MarkdownParseEndEvent {
+    type: 'parseEnd';
+    detail: MarkdownParseEndEventDetail;
+}
+export interface XMarkdownAttributes extends LynxCommonAttributes {
+    /**
+     * Raw markdown source. Lynx parses the first text child of
+     * `<x-markdown>` per the 3.7.0 raw-text-node optimization. Passing a
+     * single string here is the common path; JSX expressions resolving to
+     * a string also work.
+     */
+    children?: any;
+    /**
+     * Render-time effect applied to the parsed markdown output.
+     * Known values: `'typewriter'`, `'none'`. The engine treats unknown
+     * strings as `'none'`.
+     */
+    'markdown-effect'?: string;
+    /**
+     * Inline view attachments referenced by markdown text marks. Shape is
+     * engine-defined; passed through as-is.
+     */
+    'text-mark-attachments'?: ReadonlyArray<unknown>;
+    /** Fires when the user taps an `[anchor](url)` link. */
+    bindlink?: LynxEventHandler<MarkdownLinkEvent>;
+    /** Fires when the user taps an inline image. */
+    bindimageTap?: LynxEventHandler<MarkdownImageTapEvent>;
+    /** Fires once the engine finishes parsing the source. */
+    bindparseEnd?: LynxEventHandler<MarkdownParseEndEvent>;
+}
+declare global {
+    namespace JSX {
+        interface IntrinsicElements {
+            'x-markdown': XMarkdownAttributes;
+        }
+    }
+}
+export {};

package/dist/jsx-augment.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,55 @@
+{
+    "name": "@sigx/lynx-markdown",
+    "version": "0.4.1",
+    "description": "Typed signalx wrapper around Lynx's <x-markdown> element. Renders markdown source via XElement/Markdown.",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "node ../../scripts/clean.mjs dist && tsgo",
+        "dev": "tsgo --watch",
+        "clean": "node ../../scripts/clean.mjs dist .turbo"
+    },
+    "peerDependencies": {
+        "@sigx/lynx": "workspace:^"
+    },
+    "devDependencies": {
+        "@sigx/lynx": "workspace:^",
+        "@typescript/native-preview": "7.0.0-dev.20260511.1",
+        "typescript": "^6.0.3"
+    },
+    "author": "Andreas Ekdahl",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/signalxjs/lynx.git",
+        "directory": "packages/lynx-markdown"
+    },
+    "homepage": "https://github.com/signalxjs/lynx/tree/main/packages/lynx-markdown",
+    "bugs": {
+        "url": "https://github.com/signalxjs/lynx/issues"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "keywords": [
+        "signalx",
+        "sigx",
+        "lynx",
+        "markdown",
+        "x-markdown"
+    ]
+}