@lingxia/elements 0.14.0 → 0.16.0

package/src/inline-native/style.ts

@@ -0,0 +1,111 @@
+import type { AuthorNode } from "./types.js";
+
+// Computed values catch unsupported styles from classes as well as inline CSS.
+const unsupportedDefaults: Record<string, readonly string[]> = {
+  transform: ["none"], translate: ["none"], rotate: ["none"], scale: ["none"],
+  perspective: ["none"], clipPath: ["none"], maskImage: ["none"],
+  boxShadow: ["none"], filter: ["none"], backdropFilter: ["none"],
+  mixBlendMode: ["normal"], backgroundImage: ["none"],
+  animationName: ["none"], transitionDuration: ["0s"],
+  textDecorationLine: ["none"], fontStyle: ["normal"],
+  letterSpacing: ["normal", "0px"], textShadow: ["none"],
+};
+const layoutProperties = new Set([
+  "transform", "translate", "rotate", "scale", "perspective", "clipPath", "maskImage",
+]);
+
+export const OBSERVED_STYLE_FIELDS = [
+  ...Object.keys(unsupportedDefaults), "display", "visibility", "opacity", "overflowX", "overflowY",
+  "color", "backgroundColor", "accentColor", "fontSize", "fontWeight", "lineHeight", "textAlign", "direction",
+  ...["Top", "Right", "Bottom", "Left"].flatMap(side => ["Width", "Style", "Color"].map(suffix => `border${side}${suffix}`)),
+  "borderTopLeftRadius", "borderTopRightRadius", "borderBottomLeftRadius", "borderBottomRightRadius",
+];
+
+/** Native nodes are flat siblings, so each receives its cumulative alpha. */
+export function effectiveOpacity(element: Element): number {
+  let opacity = 1;
+  for (let node: Element | null = element; node; node = node.parentElement) {
+    opacity *= Number(node.ownerDocument.defaultView?.getComputedStyle(node).opacity ?? 1);
+  }
+  return opacity;
+}
+
+const colorContexts = new WeakMap<Document, CanvasRenderingContext2D>();
+const colors = new Map<string, string>();
+
+/** Canvas resolves browser-supported CSS colors into the hosts' sRGB wire format. */
+export function normalizeNativeColor(document: Document, value: string): string | undefined {
+  if (/^rgba?\([\d.,\s]+\)$/.test(value) || /^#[\da-f]{6}([\da-f]{2})?$/i.test(value)) return value;
+  const cached = colors.get(value);
+  if (cached) return cached;
+  let context = colorContexts.get(document);
+  if (!context) {
+    const canvas = document.createElement("canvas");
+    canvas.width = canvas.height = 1;
+    context = canvas.getContext("2d", { willReadFrequently: true, colorSpace: "srgb" }) ?? undefined;
+    if (!context) return undefined;
+    colorContexts.set(document, context);
+  }
+  context.fillStyle = "#010203";
+  context.fillStyle = value;
+  const first = context.fillStyle;
+  context.fillStyle = "#040506";
+  context.fillStyle = value;
+  if (context.fillStyle !== first) return undefined;
+  context.clearRect(0, 0, 1, 1);
+  context.fillRect(0, 0, 1, 1);
+  const [r, g, b, a] = context.getImageData(0, 0, 1, 1).data;
+  const result = `rgba(${r}, ${g}, ${b}, ${a / 255})`;
+  if (colors.size >= 256) colors.clear();
+  colors.set(value, result);
+  return result;
+}
+
+export function collectNativeStyleIssues(element: Element): NonNullable<AuthorNode["styleIssues"]> {
+  const view = element.ownerDocument?.defaultView;
+  if (!view?.getComputedStyle) return [];
+  const style = view.getComputedStyle(element);
+  const issues: NonNullable<AuthorNode["styleIssues"]> = [];
+  for (const property of ["color", "backgroundColor", "borderTopColor", "accentColor"] as const) {
+    const value = style[property];
+    if (value && value !== "auto" && !normalizeNativeColor(element.ownerDocument, value)) {
+      issues.push({ property, value, layout: false });
+    }
+  }
+  for (const [property, defaults] of Object.entries(unsupportedDefaults)) {
+    const value = String(style[property as keyof CSSStyleDeclaration] ?? "").trim();
+    if (!value || defaults.includes(value)) continue;
+    if (property === "backgroundImage" && isVideoPoster(element, value)) continue;
+    if (property === "transitionDuration" && value.split(",").every((duration) => parseFloat(duration) === 0)) continue;
+    issues.push({ property, value, layout: layoutProperties.has(property) });
+  }
+  const corners = [style.borderTopLeftRadius, style.borderTopRightRadius,
+    style.borderBottomRightRadius, style.borderBottomLeftRadius];
+  if (corners.some((value) => value && (value !== corners[0] || !/^\d+(\.\d+)?px$/.test(value)))) {
+    issues.push({ property: "borderRadius", value: corners.join(" / "), layout: false });
+  }
+  for (const suffix of ["Width", "Color", "Style"] as const) {
+    const values = [style[`borderTop${suffix}`], style[`borderRight${suffix}`],
+      style[`borderBottom${suffix}`], style[`borderLeft${suffix}`]];
+    const hasBorder = [style.borderTopWidth, style.borderRightWidth,
+      style.borderBottomWidth, style.borderLeftWidth].some((width) => parseFloat(width) > 0);
+    if (hasBorder && (values.some((value) => value !== values[0]) ||
+        (suffix === "Style" && values.some((value) => value !== "solid" && value !== "none")))) {
+      issues.push({ property: `border${suffix}`, value: values.join(" / "), layout: false });
+    }
+  }
+  return issues;
+}
+
+function isVideoPoster(element: Element, background: string): boolean {
+  if (element.tagName.toLowerCase() !== "lx-video") return false;
+  const poster = element.getAttribute("poster");
+  const url = /^url\("(.*)"\)$/.exec(background)?.[1];
+  if (!poster || !url) return false;
+  // LxVideo owns this DOM placeholder; the native backend paints its poster prop.
+  try {
+    return new URL(url.replace(/\\(["\\])/g, "$1"), element.baseURI).href === new URL(poster, element.baseURI).href;
+  } catch {
+    return false;
+  }
+}

package/src/inline-native/types.ts

@@ -0,0 +1,105 @@
+import type {
+  CoreKind,
+  HostFactoryKind,
+  NativeErrorCode,
+  PublicComponentName,
+} from "./schema.js";
+
+export interface RootRef {
+  surfaceInstanceId: string;
+  pageInstanceId: string;
+  documentInstanceId: string;
+  rootKey: string;
+  rootEpoch: number;
+}
+
+export interface NodeRef extends RootRef {
+  nodeKey: string;
+  nodeEpoch: number;
+}
+
+export interface NativeError {
+  code: NativeErrorCode;
+  scope: "node" | "root";
+  recoverable: boolean;
+  root: RootRef;
+  node?: NodeRef;
+  message: string;
+}
+
+export interface PressPayload {
+  source: "pointer" | "keyboard" | "accessibility";
+}
+
+export interface ValuePayload {
+  value: number;
+}
+
+export interface FocusPayload {
+  source: "pointer" | "keyboard" | "accessibility";
+}
+
+export interface PointerPayload {
+  source: "pointer";
+}
+
+export type NativeHandler<TPayload> = (payload: TPayload) => void;
+
+export type AuthorChild =
+  | AuthorNode
+  | string
+  | number
+  | false
+  | null
+  | undefined
+  | readonly AuthorChild[];
+
+export interface AuthorNode {
+  type: string;
+  authorId?: string;
+  automationId?: string;
+  props?: Record<string, unknown>;
+  children?: AuthorChild;
+  textContent?: string | number;
+  styleIssues?: Array<{ property: string; value: string; layout: boolean }>;
+}
+
+export interface CoreNode {
+  kind: HostFactoryKind;
+  authorType: PublicComponentName;
+  authorId?: string;
+  automationId?: string;
+  props: Record<string, unknown>;
+  children: CoreNode[];
+  text?: string;
+}
+
+export interface CompiledNativeRoot {
+  authorType: "LxNativeRoot";
+  authorId?: string;
+  automationId?: string;
+  props: Record<string, unknown>;
+  children: CoreNode[];
+  kind: Extract<CoreKind, "root">;
+}
+
+export type CompileInlineNativeResult =
+  | { ok: true; root: CompiledNativeRoot; diagnostics: NativeError[] }
+  | { ok: false; error: NativeError; diagnostics: NativeError[] };
+
+export interface CompileInlineNativeOptions {
+  rootRef?: RootRef;
+  /**
+   * When true, `controls` defaults to `true` (author contract). Tests and
+   * wrappers should leave this on; only a host fixture may override it.
+   */
+  defaultVideoControls?: boolean;
+}
+
+export const EMPTY_ROOT_REF: RootRef = {
+  surfaceInstanceId: "",
+  pageInstanceId: "",
+  documentInstanceId: "",
+  rootKey: "",
+  rootEpoch: 0,
+};

package/src/inline-native/unwrap.ts

@@ -0,0 +1,34 @@
+/**
+ * Payload-first unwrap used by React/Vue wrappers. HTML keeps CustomEvent.
+ *
+ * A real DOM Event (or an event-like `{ type, detail }` used by unit tests)
+ * yields `detail`. A bare payload object is returned as-is so wrappers can
+ * also be called with already-unwrapped values.
+ */
+export function unwrapNativeEventPayload<TPayload>(event: unknown): TPayload {
+  if (isDomEvent(event) || isEventLike(event)) {
+    const detail = (event as { detail?: TPayload }).detail;
+    return (detail === undefined ? ({} as TPayload) : detail) as TPayload;
+  }
+  return event as TPayload;
+}
+
+export function isDomEvent(value: unknown): value is Event {
+  return typeof Event !== "undefined" && value instanceof Event;
+}
+
+function isEventLike(value: unknown): value is { detail?: unknown; type?: unknown } {
+  if (!value || typeof value !== "object") return false;
+  const record = value as { detail?: unknown; type?: unknown; target?: unknown };
+  if (!("detail" in record)) return false;
+  return "type" in record || "target" in record || "currentTarget" in record;
+}
+
+export function bindPayloadHandler<TPayload>(
+  handler: ((payload: TPayload) => void) | undefined
+): EventListener {
+  return (event: Event) => {
+    if (typeof handler !== "function") return;
+    handler(unwrapNativeEventPayload<TPayload>(event));
+  };
+}

package/src/inline-native/video.ts

@@ -0,0 +1,125 @@
+import type { NodeRef } from "./types.js";
+
+export const VIDEO_COMMANDS = [
+  "play",
+  "pause",
+  "stop",
+  "seek",
+  "enterFullscreen",
+  "exitFullscreen",
+  "setStreamSource",
+] as const;
+
+export type VideoCommandName = (typeof VIDEO_COMMANDS)[number];
+
+export type VideoCommand =
+  | { name: "play" }
+  | { name: "pause" }
+  | { name: "stop" }
+  | { name: "seek"; seconds: number }
+  | { name: "enterFullscreen" }
+  | { name: "exitFullscreen" }
+  | { name: "setStreamSource"; options: Record<string, unknown> };
+
+export interface VideoCommandRequest {
+  action: "video.command";
+  owner: NodeRef;
+  requestId: string;
+  command: VideoCommand;
+}
+
+export interface VideoControlDescriptorBase {
+  controlId: string;
+  label: string;
+  frame: { x: number; y: number; width: number; height: number };
+  visible: boolean;
+  disabled?: boolean;
+}
+
+export type VideoControlDescriptor =
+  | (VideoControlDescriptorBase & {
+      role: "button";
+      pressed?: boolean;
+      expanded?: boolean;
+      actions: ReadonlyArray<"focus" | "blur" | "activate">;
+    })
+  | (VideoControlDescriptorBase & {
+      role: "slider";
+      value: number;
+      min: number;
+      max: number;
+      actions: ReadonlyArray<"focus" | "blur" | "increment" | "decrement" | "setValue">;
+    });
+
+export interface VideoControlsSemanticSnapshot {
+  action: "video.controlsSemanticSnapshot";
+  owner: NodeRef;
+  revision: number;
+  controls: readonly VideoControlDescriptor[];
+}
+
+export function buildVideoCommandRequest(
+  owner: NodeRef,
+  command: VideoCommand,
+  requestId: string
+): VideoCommandRequest {
+  return { action: "video.command", owner, requestId, command };
+}
+
+export function videoCommandUrls(command: VideoCommand): string[] {
+  if (command.name !== "setStreamSource") return [];
+  const options = command.options ?? {};
+  const urls: string[] = [];
+  for (const key of ["url", "src", "uri"]) {
+    const value = options[key];
+    if (typeof value === "string" && value) urls.push(value);
+  }
+  return urls;
+}
+
+export function collectVideoResourceUrls(props: Record<string, unknown>): string[] {
+  const urls: string[] = [];
+  for (const key of ["src", "poster"]) {
+    const value = props[key];
+    if (typeof value === "string" && value) urls.push(value);
+  }
+  const watermark = props.watermark as { resource?: { url?: string } } | undefined;
+  if (watermark?.resource && typeof watermark.resource === "object") {
+    const url = (watermark.resource as { url?: string }).url;
+    if (typeof url === "string" && url) urls.push(url);
+  }
+  const qualities = props.qualities;
+  if (Array.isArray(qualities)) {
+    for (const item of qualities) {
+      if (item && typeof item === "object" && typeof (item as { url?: string }).url === "string") {
+        urls.push((item as { url: string }).url);
+      }
+    }
+  }
+  return urls;
+}
+
+export function validateControlsSnapshot(
+  snapshot: VideoControlsSemanticSnapshot,
+  lastRevision: number
+): { ok: true } | { ok: false; message: string } {
+  if (snapshot.revision <= lastRevision) {
+    return { ok: false, message: "controls snapshot revision must increase" };
+  }
+  const seen = new Set<string>();
+  for (const control of snapshot.controls) {
+    if (!control.controlId || seen.has(control.controlId)) {
+      return { ok: false, message: "controlId must be unique and non-empty" };
+    }
+    seen.add(control.controlId);
+    if (control.role === "slider") {
+      if (![control.min, control.max, control.value].every(Number.isFinite)) {
+        return { ok: false, message: "slider descriptor values must be finite" };
+      }
+      if (control.min > control.value || control.value > control.max) {
+        return { ok: false, message: "slider descriptor value is out of range" };
+      }
+    }
+  }
+  return { ok: true };
+}

package/src/native_component_wrapper_shared.ts

@@ -1,7 +1,7 @@
-import type { NavigatorEnvVersion, NavigatorOpenType, NavigatorTarget } from "./navigator.js";
+import type { NavigatorChannel, NavigatorOpenType, NavigatorTarget } from "./navigator.js";
 import type { NavigatorQuery } from "./navigator.js";
 import type { LxMediaSwiperItem } from "./media_swiper.js";
-import type { LxVideoQuality } from "./video.js";
+import type { LxVideoQuality, LxVideoEventPayloads } from "./video.js";
 
 export function appendDataAttrs(
   attrs: Record<string, unknown>,
@@ -39,7 +39,7 @@ export interface NavigatorNativeAttrOptions {
   delta?: number;
   appId?: string;
   query?: NavigatorQuery;
-  envVersion?: NavigatorEnvVersion;
+  channel?: NavigatorChannel;
   targetVersion?: string;
   phoneNumber?: string;
   hoverClass?: string;
@@ -66,7 +66,7 @@ export function buildNavigatorNativeAttrs(
   if (options.target) result.target = options.target;
   if (options.appId) result["app-id"] = options.appId;
   if (options.query) result.query = JSON.stringify(options.query);
-  if (options.envVersion) result["env-version"] = options.envVersion;
+  if (options.channel) result.channel = options.channel;
   if (options.targetVersion) result["target-version"] = options.targetVersion;
   if (options.phoneNumber) result["phone-number"] = options.phoneNumber;
 
@@ -208,7 +208,8 @@ export const VIDEO_DOM_EVENT_MAP = {
   onWaiting: "waiting",
   onQualityChange: "qualitychange",
   onRateChange: "ratechange",
-} as const;
+  onVolumeChange: "volumechange",
+} as const satisfies Record<keyof LxVideoEventPayloads, string>;
 
 export interface VideoNativeAttrOptions {
   id?: string;
@@ -238,7 +239,8 @@ export function buildVideoNativeAttrs(
   if (options.autoplay) result.autoplay = "";
   if (options.loop) result.loop = "";
   if (options.muted) result.muted = "";
-  if (options.controls) result.controls = "";
+  if (options.controls === false) result.controls = "false";
+  else if (options.controls) result.controls = "";
   if (options.progressBar === false) result["progress-bar"] = "false";
   if (options.live) result.live = "";
   if (options.volume !== undefined) result.volume = options.volume;

package/src/nativecomponent.ts

@@ -7,7 +7,9 @@ const NATIVE_COMPONENT_LAYOUT_INVALIDATED_EVENT = "lingxia:native-component-layo
 let pendingLayoutInvalidationFrame: number | null = null;
 const pendingLayoutInvalidationTimers = new Map<number, number>();
 
-export function sendNativeComponentMessage(message: NativeComponentMessage) {
+/// Returns false when the native channel is not up yet and the message was
+/// dropped, so callers that carry state (an island's first commit) can retry.
+export function sendNativeComponentMessage(message: NativeComponentMessage): boolean {
   const sender =
     typeof window !== "undefined"
       ? window.LingXiaBridge?.nativeComponents?.send
@@ -17,9 +19,10 @@ export function sendNativeComponentMessage(message: NativeComponentMessage) {
       warnedNoHandler = true;
       console.warn("[LingXia NativeComponent] message handler not available");
     }
-    return;
+    return false;
   }
   sender(message);
+  return true;
 }
 
 export function registerNativeComponentHandler(
@@ -33,19 +36,11 @@ export function registerNativeComponentHandler(
   const registerFn = nativeComponents?.register;
   if (typeof registerFn === "function") {
     const unregister = registerFn(id, handler as Parameters<typeof registerFn>[1]);
-    const platform = window.LingXiaBridge?.platform;
-    const requiresReadyHandshake = !!(
-      platform?.isIOS?.() ||
-      platform?.isAndroid?.() ||
-      platform?.isMacOS?.()
-    );
-    const hasHandler = nativeComponents?.hasHandler;
     const send = nativeComponents?.send;
+    // Always announce ready after the leaf handler is registered, including
+    // Windows: island video queues play/playing until this id's handshake.
     if (typeof send === "function") {
-      const nativeReady = typeof hasHandler === "function" ? hasHandler() : true;
-      if (requiresReadyHandshake || nativeReady) {
-        send({ action: "component.ready", id });
-      }
+      send({ action: "component.ready", id });
     }
     return unregister;
   }

package/src/navigator.ts

@@ -18,7 +18,7 @@ export type NavigatorTarget =
 
 export type NavigatorQueryValue = string | number | boolean | null | undefined;
 export type NavigatorQuery = Record<string, NavigatorQueryValue>;
-export type NavigatorEnvVersion = 'release' | 'preview' | 'developer';
+export type NavigatorChannel = 'release' | 'preview' | 'draft';
 
 export interface LxNavigatorEventDetail {
   success?: boolean;
@@ -44,7 +44,7 @@ export type LxNavigatorAttributes = {
 
   // Open external lxapp
   'app-id'?: string;              // Target lxapp ID
-  'env-version'?: NavigatorEnvVersion; // Target lxapp envVersion
+  channel?: NavigatorChannel; // Target lxapp channel
   'target-version'?: string;      // Exact target lxapp version
 
   // Phone call
@@ -89,7 +89,7 @@ export class LxNavigatorElement extends HTMLElement {
       "target",
       "delta",
       "app-id",
-      "env-version",
+      "channel",
       "target-version",
       "phone-number",
       "hover-class",
@@ -263,7 +263,7 @@ export class LxNavigatorElement extends HTMLElement {
     const explicitTarget = this.getAttribute('target') as NavigatorTarget | null;
     const delta = parseInt(this.getAttribute('delta') || '1', 10);
     const appId = this.getAttribute('app-id');
-    const envVersion = this.getAttribute('env-version') as NavigatorEnvVersion | null;
+    const channel = this.getAttribute('channel') as NavigatorChannel | null;
     const targetVersion = this.getAttribute('target-version');
     const phoneNumber = this.getAttribute('phone-number');
 
@@ -279,7 +279,7 @@ export class LxNavigatorElement extends HTMLElement {
       target,
       delta,
       appId,
-      envVersion,
+      channel,
       targetVersion,
       phoneNumber
     });
@@ -322,7 +322,7 @@ export class LxNavigatorElement extends HTMLElement {
     target: NavigatorTarget;
     delta: number;
     appId?: string | null;
-    envVersion?: NavigatorEnvVersion | null;
+    channel?: NavigatorChannel | null;
     targetVersion?: string | null;
     phoneNumber?: string | null;
   }) {
@@ -415,7 +415,7 @@ export class LxNavigatorElement extends HTMLElement {
     target: NavigatorTarget;
     delta: number;
     appId?: string | null;
-    envVersion?: NavigatorEnvVersion | null;
+    channel?: NavigatorChannel | null;
     targetVersion?: string | null;
     phoneNumber?: string | null;
   }) {
@@ -530,13 +530,13 @@ export class LxNavigatorElement extends HTMLElement {
     appId?: string | null;
     page?: string | null;
     query?: string | null;
-    envVersion?: NavigatorEnvVersion | null;
+    channel?: NavigatorChannel | null;
     targetVersion?: string | null;
   }): Record<string, unknown> {
     const target: Record<string, unknown> = { appId: options.appId };
     const pageTarget = this.buildPageTarget(options);
     if (pageTarget) Object.assign(target, pageTarget);
-    if (options.envVersion) target.envVersion = options.envVersion;
+    if (options.channel) target.channel = options.channel;
     if (options.targetVersion) target.targetVersion = options.targetVersion;
     return target;
   }

package/src/picker.ts

@@ -5,7 +5,16 @@ import {
 } from "./nativecomponent.js";
 import { ensureComponentId } from "./component.js";
 import { measureElement } from "./dom.js";
-import { isAndroid, isHarmony, isDesktop } from "./platform.js";
+import { isAndroid, isHarmony, isIOS } from "./platform.js";
+
+// Which hosts register a `picker.native` component. A capability question, not
+// a form-factor one: macOS and Windows have no picker factory, so they draw the
+// web picker even in the Runner's phone frame, where the host class is mobile
+// but the machine underneath is still a Mac or a PC. Harmony has its own embed
+// path and never reaches either branch.
+function hasNativePicker(): boolean {
+  return isIOS() || isAndroid();
+}
 
 const HARMONY_PROPS_PREFIX = "data:application/json,";
 
@@ -90,7 +99,7 @@ export class LxPickerElement extends HTMLElement {
   private removeLayoutInvalidationListener?: () => void;
   private readonly layoutInvalidationListener: EventListenerObject = {
     handleEvent: () => {
-      if (!this.isConnected || isHarmony() || isDesktop()) return;
+      if (!this.isConnected || isHarmony() || !hasNativePicker()) return;
       void this.mountPicker();
     }
   };
@@ -146,7 +155,7 @@ export class LxPickerElement extends HTMLElement {
     this.removeLayoutInvalidationListener?.();
     this.removeLayoutInvalidationListener = undefined;
 
-    if (this.componentId && !isHarmony() && !isDesktop()) {
+    if (this.componentId && !isHarmony() && hasNativePicker()) {
       sendNativeComponentMessage({
         action: "component.unmount",
         id: this.componentId
@@ -301,7 +310,7 @@ export class LxPickerElement extends HTMLElement {
       return;
     }
 
-    if (isDesktop()) {
+    if (!hasNativePicker()) {
       if (this.webCleanup) return;
       const { renderWebPicker } = await import('./picker-web.js');
       if (!this.isConnected || !this.componentId || this.webCleanup) return;

package/src/video-events.ts

@@ -0,0 +1,16 @@
+/** Keep platform spelling differences out of the public DOM/payload contract. */
+export function normalizeVideoEventDetail(event: string, payload: unknown): Record<string, unknown> {
+  const detail = payload && typeof payload === "object" ? payload as Record<string, unknown> : {};
+  if (["playrequest", "play", "playing", "pause", "stop", "ended", "waiting"].includes(event)) return {};
+  if (event === "fullscreenchange") {
+    return { ...detail, fullscreen: detail.fullscreen ?? detail.fullScreen ?? false };
+  }
+  if (event === "error") {
+    return {
+      ...detail,
+      code: String(detail.code ?? "NATIVE_COMPONENT_COMMAND_FAILED"),
+      message: String(detail.message ?? detail.errMsg ?? "Native video failed"),
+    };
+  }
+  return detail;
+}