tauri-plugin-live-activity 0.1.0-alpha.4 → 0.2.0

package/dist-js/index.d.ts

@@ -1,5 +1,8 @@
-import type { ActivityRecord, Capabilities, EndInput, PermissionKind, Permissions, StartInput, UpdateInput } from './types.js';
+import { type UnlistenFn } from '@tauri-apps/api/event';
+import type { ActionEvent, ActivityRecord, Capabilities, EndInput, LayoutActivityRecord, LayoutStartInput, LayoutUpdateInput, PermissionKind, Permissions, StartInput, UpdateInput } from './types.js';
 export type * from './types.js';
+/** Builders for the nodes of a layout tree. */
+export * as layout from './layout.js';
 /** Read backend features; this does not request OS permissions. */
 export declare function getCapabilities(): Promise<Capabilities>;
 /** Read current OS permission states without showing a permission prompt. */
@@ -14,3 +17,16 @@ export declare function update(input: UpdateInput): Promise<ActivityRecord>;
 export declare function end(input: EndInput): Promise<ActivityRecord>;
 /** Reconcile plugin-owned records with the OS; unknown is a valid observed state. */
 export declare function list(): Promise<readonly ActivityRecord[]>;
+/** Start a layout activity (contract v2); repeated identical starts for an active key are idempotent. */
+export declare function startLayout(input: LayoutStartInput): Promise<LayoutActivityRecord>;
+/** Replace every value with a newer revision; the layout stays as started. */
+export declare function updateLayout(input: LayoutUpdateInput): Promise<LayoutActivityRecord>;
+/** End this layout generation. A late update cannot revive it. */
+export declare function endLayout(input: EndInput): Promise<LayoutActivityRecord>;
+/** Reconcile plugin-owned layout records with the OS; `list` reports contract v1 activities. */
+export declare function listLayout(): Promise<readonly LayoutActivityRecord[]>;
+/**
+ * Receive button taps while this webview is alive; resolves to the function that stops listening.
+ * Listening uses Tauri's event permissions (`core:event:default`).
+ */
+export declare function onAction(handler: (event: ActionEvent) => void): Promise<UnlistenFn>;

package/dist-js/index.js

@@ -1,4 +1,7 @@
 import { invoke } from '@tauri-apps/api/core';
+import { listen } from '@tauri-apps/api/event';
+/** Builders for the nodes of a layout tree. */
+export * as layout from './layout.js';
 /** Read backend features; this does not request OS permissions. */
 export function getCapabilities() {
     return invoke('plugin:live-activity|get_capabilities', {});
@@ -27,3 +30,26 @@ export function end(input) {
 export function list() {
     return invoke('plugin:live-activity|list', {});
 }
+/** Start a layout activity (contract v2); repeated identical starts for an active key are idempotent. */
+export function startLayout(input) {
+    return invoke('plugin:live-activity|start_layout', { input });
+}
+/** Replace every value with a newer revision; the layout stays as started. */
+export function updateLayout(input) {
+    return invoke('plugin:live-activity|update_layout', { input });
+}
+/** End this layout generation. A late update cannot revive it. */
+export function endLayout(input) {
+    return invoke('plugin:live-activity|end_layout', { input });
+}
+/** Reconcile plugin-owned layout records with the OS; `list` reports contract v1 activities. */
+export function listLayout() {
+    return invoke('plugin:live-activity|list_layout', {});
+}
+/**
+ * Receive button taps while this webview is alive; resolves to the function that stops listening.
+ * Listening uses Tauri's event permissions (`core:event:default`).
+ */
+export function onAction(handler) {
+    return listen('live-activity://action', event => handler(event.payload));
+}

package/dist-js/layout.d.ts

@@ -0,0 +1,32 @@
+import type { LayoutButtonNode, LayoutDividerNode, LayoutGaugeNode, LayoutHStackNode, LayoutImageNode, LayoutNode, LayoutPathNode, LayoutProgressNode, LayoutSpacerNode, LayoutSymbolNode, LayoutTextNode, LayoutTimerTextNode, LayoutVStackNode, LayoutZStackNode } from './types.js';
+/** The members of a node that its builder does not take as arguments. */
+type Options<N extends LayoutNode, Argument extends keyof N = never> = N extends unknown ? Omit<N, 'type' | Argument> : never;
+/** Children from top to bottom. */
+export declare function vstack(children: readonly LayoutNode[], options?: Options<LayoutVStackNode, 'children'>): LayoutVStackNode;
+/** Children side by side. */
+export declare function hstack(children: readonly LayoutNode[], options?: Options<LayoutHStackNode, 'children'>): LayoutHStackNode;
+/** Children on top of each other, the first at the back. */
+export declare function zstack(children: readonly LayoutNode[], options?: Options<LayoutZStackNode, 'children'>): LayoutZStackNode;
+/** Flexible space inside a stack. */
+export declare function spacer(options?: Options<LayoutSpacerNode>): LayoutSpacerNode;
+/** A separator line. */
+export declare function divider(options?: Options<LayoutDividerNode>): LayoutDividerNode;
+/** Literal text. */
+export declare function text(value: string, options?: Options<LayoutTextNode, 'value' | 'bind'>): LayoutTextNode;
+/** Text that shows the value of `key`. */
+export declare function bound(key: string, options?: Options<LayoutTextNode, 'value' | 'bind'>): LayoutTextNode;
+/** An SF Symbol. */
+export declare function symbol(name: string, options?: Options<LayoutSymbolNode, 'name'>): LayoutSymbolNode;
+/** An image of the widget extension's asset catalog. */
+export declare function image(asset: string, options?: Options<LayoutImageNode, 'source'>): LayoutImageNode;
+/** A shape from SVG path data `d`, drawn in a `box` of `[width, height]`. */
+export declare function path(d: string, box: readonly [number, number], options?: Options<LayoutPathNode, 'd' | 'box'>): LayoutPathNode;
+/** A progress bar or ring for the number value of `key`. */
+export declare function progress(key: string, options?: Options<LayoutProgressNode, 'bind'>): LayoutProgressNode;
+/** A gauge for the number value of `key`. */
+export declare function gauge(key: string, options?: Options<LayoutGaugeNode, 'bind'>): LayoutGaugeNode;
+/** A timer the system draws between the epoch-millisecond values of the `start` and `end` keys. */
+export declare function timerText(start: string, end: string, options?: Options<LayoutTimerTextNode, 'start' | 'end'>): LayoutTimerTextNode;
+/** A button around `child`; a tap reports `actionId` to `onAction`. */
+export declare function button(actionId: string, child: LayoutNode, options?: Options<LayoutButtonNode, 'actionId' | 'child'>): LayoutButtonNode;
+export {};

package/dist-js/layout.js

@@ -0,0 +1,61 @@
+/** Copies the options that were given, so that a node never carries an undefined member. */
+function given(options) {
+    return Object.fromEntries(Object.entries(options ?? {}).filter(([, value]) => value !== undefined));
+}
+// The builders return plain node objects. They do not validate: the plugin checks the whole request.
+/** Children from top to bottom. */
+export function vstack(children, options) {
+    return { type: 'vstack', children, ...given(options) };
+}
+/** Children side by side. */
+export function hstack(children, options) {
+    return { type: 'hstack', children, ...given(options) };
+}
+/** Children on top of each other, the first at the back. */
+export function zstack(children, options) {
+    return { type: 'zstack', children, ...given(options) };
+}
+/** Flexible space inside a stack. */
+export function spacer(options) {
+    return { type: 'spacer', ...given(options) };
+}
+/** A separator line. */
+export function divider(options) {
+    return { type: 'divider', ...given(options) };
+}
+/** Literal text. */
+export function text(value, options) {
+    return { type: 'text', value, ...given(options) };
+}
+/** Text that shows the value of `key`. */
+export function bound(key, options) {
+    return { type: 'text', bind: key, ...given(options) };
+}
+/** An SF Symbol. */
+export function symbol(name, options) {
+    return { type: 'symbol', name, ...given(options) };
+}
+/** An image of the widget extension's asset catalog. */
+export function image(asset, options) {
+    return { type: 'image', source: { asset }, ...given(options) };
+}
+/** A shape from SVG path data `d`, drawn in a `box` of `[width, height]`. */
+export function path(d, box, options) {
+    return { type: 'path', d, box, ...given(options) };
+}
+/** A progress bar or ring for the number value of `key`. */
+export function progress(key, options) {
+    return { type: 'progress', bind: key, ...given(options) };
+}
+/** A gauge for the number value of `key`. */
+export function gauge(key, options) {
+    return { type: 'gauge', bind: key, ...given(options) };
+}
+/** A timer the system draws between the epoch-millisecond values of the `start` and `end` keys. */
+export function timerText(start, end, options) {
+    return { type: 'timerText', start, end, ...given(options) };
+}
+/** A button around `child`; a tap reports `actionId` to `onAction`. */
+export function button(actionId, child, options) {
+    return { type: 'button', actionId, child, ...given(options) };
+}

package/dist-js/types.d.ts

@@ -15,6 +15,8 @@ export interface Capabilities {
     readonly stateObservation: FeatureSupport;
     readonly silentUpdate: FeatureSupport;
     readonly nativeLiveActivity: FeatureSupport;
+    /** Layout activities of request contract v2. */
+    readonly layout: FeatureSupport;
     readonly maxPayloadBytes: number;
 }
 export interface Permissions {
@@ -103,4 +105,255 @@ export interface LiveActivityError {
     readonly code: ErrorCode;
     readonly message: string;
 }
+/** Text of at most 1000 Unicode code points, a number from -8640000000000000 to 8640000000000000, or a boolean. */
+export type LayoutValue = string | number | boolean;
+/** At most 32 entries. A key is an ASCII letter followed by up to 31 ASCII letters, digits or `_`. */
+export interface LayoutValues {
+    readonly [key: string]: LayoutValue;
+}
+export interface LayoutSnapshot {
+    /** Nonnegative JavaScript safe integer; strictly increases when the values change. */
+    readonly revision: number;
+    /** The complete map. An update keeps the keys and the value types accepted at start. */
+    readonly values: LayoutValues;
+    /** UTC Unix epoch milliseconds. */
+    readonly staleAt?: number;
+}
+type ColorName = 'primary' | 'secondary' | 'accent' | 'red' | 'orange' | 'yellow' | 'green' | 'mint' | 'teal' | 'cyan' | 'blue' | 'indigo' | 'purple' | 'pink' | 'brown' | 'white' | 'black' | 'gray' | 'clear';
+/** `#RRGGBB` or `#RRGGBBAA`. */
+type HexColor = `#${string}`;
+/** A semantic name, one hex color for both appearances, or a light and dark pair. */
+export type LayoutColor = ColorName | HexColor | {
+    readonly light: HexColor;
+    readonly dark: HexColor;
+};
+type Anchor = 'center' | 'leading' | 'trailing' | 'top' | 'bottom' | 'topLeading' | 'topTrailing' | 'bottomLeading' | 'bottomTrailing';
+/** At least one member. Sizes are points from 0 to 1024. */
+export interface LayoutFrame {
+    readonly width?: number;
+    readonly height?: number;
+    readonly minWidth?: number;
+    readonly minHeight?: number;
+    readonly maxWidth?: number | 'infinity';
+    readonly maxHeight?: number | 'infinity';
+    readonly alignment?: Anchor;
+}
+interface StyleFields {
+    readonly weight?: 'ultraLight' | 'thin' | 'light' | 'regular' | 'medium' | 'semibold' | 'bold' | 'heavy' | 'black';
+    readonly design?: 'default' | 'rounded' | 'serif' | 'monospaced';
+    readonly monospacedDigit?: boolean;
+    /** Foreground color. */
+    readonly color?: LayoutColor;
+    /** Integer from 1 to 10. */
+    readonly lineLimit?: number;
+    /** From 0.1 to 1. */
+    readonly minimumScaleFactor?: number;
+    /** Alignment of text that spans several lines. */
+    readonly alignment?: 'leading' | 'center' | 'trailing';
+    /** Points from 0 to 64: one number for every edge, or `[top, leading, bottom, trailing]`. */
+    readonly padding?: number | readonly [number, number, number, number];
+    readonly frame?: LayoutFrame;
+    readonly background?: LayoutColor;
+    /** Points from 0 to 64. */
+    readonly cornerRadius?: number;
+    /** From 0 to 1. */
+    readonly opacity?: number;
+    /** Tint of buttons, progress views and gauges. */
+    readonly tint?: LayoutColor;
+    readonly buttonStyle?: 'automatic' | 'bordered' | 'borderedProminent' | 'plain';
+}
+/** At least one member. `font`, a system text style, and `size`, points from 6 to 96, exclude each other. */
+export type LayoutStyle = StyleFields & ({
+    readonly font?: 'largeTitle' | 'title' | 'title2' | 'title3' | 'headline' | 'subheadline' | 'body' | 'callout' | 'footnote' | 'caption' | 'caption2';
+    readonly size?: never;
+} | {
+    readonly size?: number;
+    readonly font?: never;
+});
+/** Members every node may carry. A condition names a value key; `if` and `unless` exclude each other. */
+type NodeFields = {
+    /** A token of the request's `styles` table. */
+    readonly style?: string;
+} & ({
+    readonly if?: string;
+    readonly unless?: never;
+} | {
+    readonly unless?: string;
+    readonly if?: never;
+});
+export type LayoutVStackNode = NodeFields & {
+    readonly type: 'vstack';
+    /** Between 1 and 12 nodes. */
+    readonly children: readonly LayoutNode[];
+    /** Points from 0 to 64. */
+    readonly spacing?: number;
+    readonly alignment?: 'leading' | 'center' | 'trailing';
+};
+export type LayoutHStackNode = NodeFields & {
+    readonly type: 'hstack';
+    /** Between 1 and 12 nodes. */
+    readonly children: readonly LayoutNode[];
+    /** Points from 0 to 64. */
+    readonly spacing?: number;
+    readonly alignment?: 'top' | 'center' | 'bottom' | 'firstTextBaseline';
+};
+export type LayoutZStackNode = NodeFields & {
+    readonly type: 'zstack';
+    /** Between 1 and 12 nodes. */
+    readonly children: readonly LayoutNode[];
+    readonly alignment?: Anchor;
+};
+export type LayoutSpacerNode = NodeFields & {
+    readonly type: 'spacer';
+    /** Points from 0 to 256. */
+    readonly minLength?: number;
+};
+export type LayoutDividerNode = NodeFields & {
+    readonly type: 'divider';
+};
+/** Literal text of at most 200 Unicode code points, or the value of a key. */
+export type LayoutTextNode = NodeFields & {
+    readonly type: 'text';
+} & ({
+    readonly value: string;
+    readonly bind?: never;
+} | {
+    readonly bind: string;
+    readonly value?: never;
+});
+export type LayoutSymbolNode = NodeFields & {
+    readonly type: 'symbol';
+    /** SF Symbol name: lowercase letters and digits in parts joined by dots, 64 characters at most. */
+    readonly name: string;
+    readonly rendering?: 'monochrome' | 'hierarchical' | 'palette' | 'multicolor';
+    /** Key of a number value: the symbol's variable value, from 0 to 1. */
+    readonly variableBind?: string;
+};
+export type LayoutImageNode = NodeFields & {
+    readonly type: 'image';
+    /** Name of an image in the widget extension's asset catalog. */
+    readonly source: {
+        readonly asset: string;
+    };
+    readonly resizable?: boolean;
+    readonly contentMode?: 'fit' | 'fill';
+};
+export type LayoutPathNode = NodeFields & {
+    readonly type: 'path';
+    /** SVG path data of at most 512 bytes; commands `M L H V C S Q T Z` in either case, no arcs. */
+    readonly d: string;
+    /** `[width, height]` of the coordinate space of `d`, each from 1 to 1024. */
+    readonly box: readonly [number, number];
+    /** Line width from 0.5 to 16; the path is filled when absent. */
+    readonly stroke?: number;
+};
+export type LayoutProgressNode = NodeFields & {
+    readonly type: 'progress';
+    /** Key of a number value, shown clamped to 0..1. */
+    readonly bind: string;
+    readonly kind?: 'linear' | 'circular';
+};
+export type LayoutGaugeNode = NodeFields & {
+    readonly type: 'gauge';
+    /** Key of a number value. */
+    readonly bind: string;
+    /** Defaults to 0; less than `max`. */
+    readonly min?: number;
+    /** Defaults to 1. */
+    readonly max?: number;
+    readonly kind?: 'linear' | 'circular';
+};
+export type LayoutTimerTextNode = NodeFields & {
+    readonly type: 'timerText';
+    /** Key of a number value: UTC Unix epoch milliseconds. */
+    readonly start: string;
+    /** Key of a number value: UTC Unix epoch milliseconds after `start`. */
+    readonly end: string;
+    /** Defaults to true. */
+    readonly countsDown?: boolean;
+};
+/** Allowed in the lock screen and the expanded regions, never inside another button. */
+export type LayoutButtonNode = NodeFields & {
+    readonly type: 'button';
+    /** Reported by `onAction`: starts with a letter or digit, then letters, digits or `._:-`, 64 characters at most. */
+    readonly actionId: string;
+    readonly child: LayoutNode;
+};
+export type LayoutNode = LayoutVStackNode | LayoutHStackNode | LayoutZStackNode | LayoutSpacerNode | LayoutDividerNode | LayoutTextNode | LayoutSymbolNode | LayoutImageNode | LayoutPathNode | LayoutProgressNode | LayoutGaugeNode | LayoutTimerTextNode | LayoutButtonNode;
+/** At least one region, each of at most 12 nodes. */
+export interface LayoutIslandExpanded {
+    readonly leading?: LayoutNode;
+    readonly trailing?: LayoutNode;
+    readonly center?: LayoutNode;
+    readonly bottom?: LayoutNode;
+}
+/** At least one member; a missing part renders a default. */
+export interface LayoutIsland {
+    readonly expanded?: LayoutIslandExpanded;
+    /** At most 3 nodes and no button. */
+    readonly compactLeading?: LayoutNode;
+    /** At most 3 nodes and no button. */
+    readonly compactTrailing?: LayoutNode;
+    /** At most 2 nodes and no button. */
+    readonly minimal?: LayoutNode;
+}
+/** Trees are at most 8 levels deep and hold at most 4 buttons per region. */
+export interface Layout {
+    /** At most 40 nodes. */
+    readonly lockScreen: LayoutNode;
+    readonly island?: LayoutIsland;
+    /** Tint behind the lock screen presentation. */
+    readonly background?: LayoutColor;
+    /** Tint of the Dynamic Island keyline. */
+    readonly keyline?: LayoutColor;
+}
+export interface LayoutAndroidOptions {
+    /** Lock screen visibility of the notification. */
+    readonly visibility: 'public' | 'private' | 'secret';
+}
+export interface LayoutStartInput {
+    /** Stable app-owned key; do not put credentials or private data in this key. */
+    readonly activityKey: string;
+    readonly schemaVersion: 2;
+    /** Explicitly permits or forbids selection of the notification fallback. */
+    readonly fallback: Fallback;
+    /** Fixed for this generation; updates replace the values only. */
+    readonly layout: Layout;
+    /** Between 1 and 24 styles by token; a token follows the rule for value keys. */
+    readonly styles?: {
+        readonly [token: string]: LayoutStyle;
+    };
+    readonly snapshot: LayoutSnapshot;
+    /** Ignored on iOS. */
+    readonly android?: LayoutAndroidOptions;
+}
+export interface LayoutUpdateInput {
+    readonly id: string;
+    /** Complete replacement snapshot, not a partial update. */
+    readonly snapshot: LayoutSnapshot;
+}
+/** The record does not repeat the layout. */
+export interface LayoutActivityRecord {
+    /** Opaque handle for this generation; contract v1 commands do not see it. */
+    readonly id: string;
+    readonly activityKey: string;
+    readonly schemaVersion: 2;
+    readonly snapshot: LayoutSnapshot;
+    readonly backend: Backend;
+    readonly state: ActivityState;
+    /** A successful OS call does not prove that the user can see the activity. */
+    readonly visibility: 'unknown';
+    /** What this backend left out, for example `layout.island` on Android. */
+    readonly degradedFeatures: readonly string[];
+    readonly promotionRequested: boolean;
+    readonly promotionState: PromotionState;
+}
+/** A tap on a button node. */
+export interface ActionEvent {
+    readonly actionId: string;
+    /** Handle of the activity that showed the button. */
+    readonly activityId: string;
+    /** The key of that activity, when the plugin knows it. */
+    readonly activityKey?: string;
+}
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tauri-plugin-live-activity",
-  "version": "0.1.0-alpha.4",
+  "version": "0.2.0",
   "description": "Tauri 2 plugin for iOS Live Activities (ActivityKit and Dynamic Island) and Android Live Updates with ongoing notification fallback",
   "author": "1eedaegon",
   "type": "module",
@@ -28,9 +28,9 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p examples/demo/tsconfig.json",
     "test": "npm run build && npm run test:contracts && npm run test:api && npm run test:demo",
-    "test:contracts": "node --test --experimental-test-coverage \"--test-coverage-include=tools/validate-request.mjs\" --test-coverage-lines=80 --test-coverage-branches=80 --test-coverage-functions=80 tests/requests.test.mjs",
+    "test:contracts": "node --test --experimental-test-coverage \"--test-coverage-include=tools/validate-request.mjs\" --test-coverage-lines=80 --test-coverage-branches=80 --test-coverage-functions=80 tests/requests.test.mjs tests/layout-requests.test.mjs",
     "test:api": "node --test --experimental-test-coverage \"--test-coverage-include=dist-js/*.js\" --test-coverage-lines=80 --test-coverage-branches=80 --test-coverage-functions=80 tests/api.test.mjs",
-    "test:demo": "node --experimental-strip-types --test --experimental-test-coverage \"--test-coverage-include=examples/demo/src/*.ts\" \"--test-coverage-exclude=examples/demo/tests/**\" --test-coverage-lines=80 --test-coverage-branches=80 --test-coverage-functions=80 examples/demo/tests/self-test.test.mjs examples/demo/tests/ui-state.test.mjs",
+    "test:demo": "node --experimental-strip-types --test --experimental-test-coverage \"--test-coverage-include=examples/demo/src/*.ts\" \"--test-coverage-exclude=examples/demo/tests/**\" --test-coverage-lines=80 --test-coverage-branches=80 --test-coverage-functions=80 examples/demo/tests/self-test.test.mjs examples/demo/tests/ui-state.test.mjs examples/demo/tests/layouts.test.mjs examples/demo/tests/setup.test.mjs",
     "build:demo": "npm run build && node examples/demo/build.mjs",
     "prepack": "npm run build",
     "pack:check": "npm pack --dry-run"