@softov/scena 0.1.2

package/dist/types/command.d.ts

@@ -0,0 +1,62 @@
+import type { Disposable } from './disposable.js';
+import type { WhenClause } from './when.js';
+import type { EventBus } from './events.js';
+import type { ReactiveStore } from './reactive-store.js';
+import type { MountSurfaceRegistry } from './mount-surface.js';
+import type { BindingPath } from './component-graph.js';
+import type { Scena } from './scena.js';
+import type { ResourceColor } from './colors.js';
+import type { HostCtx } from './host.js';
+export type CommandSource = 'palette' | 'menu' | 'keybinding' | 'graph' | 'programmatic';
+export type ArgType = 'string' | 'string?' | 'number' | 'number?' | 'boolean' | 'boolean?' | readonly string[];
+export type ArgsSchema = Record<string, ArgType>;
+export interface CommandContext {
+    scena: Scena;
+    store: ReactiveStore;
+    surfaces: MountSurfaceRegistry;
+    commands: CommandRegistry;
+    events: EventBus;
+    source: CommandSource;
+    dataContext?: BindingPath;
+    host?: HostCtx;
+}
+export interface ExecuteOpts {
+    source?: CommandSource;
+    dataContext?: BindingPath;
+    host?: HostCtx;
+}
+export interface Command<TArgs = unknown> {
+    id: string;
+    title: string | ((ctx?: CommandContext) => string);
+    description?: string | ((ctx?: CommandContext) => string);
+    category?: string;
+    icon?: string;
+    color?: ResourceColor;
+    keywords?: string[];
+    shortcut?: string | string[];
+    keys?: string | string[];
+    slots?: string[];
+    active?: (ctx: CommandContext) => boolean;
+    disabled?: (ctx: CommandContext) => boolean;
+    when?: WhenClause;
+    acceptsQuery?: boolean;
+    submenu?: () => Promise<Command[]>;
+    args?: ArgsSchema;
+    dispatch?: 'client' | 'remote' | 'either';
+    run?: (ctx: CommandContext, args?: TArgs) => unknown | Promise<unknown>;
+}
+export interface CommandListFilter {
+    category?: string;
+    enabled?: boolean;
+    slot?: string | string[];
+    q?: string;
+}
+export interface CommandRegistry {
+    register<TArgs>(cmd: Command<TArgs>): Disposable;
+    unregister(id: string): void;
+    get(id: string): Command | undefined;
+    list(filter?: CommandListFilter): Command[];
+    listEnabled(filter?: Omit<CommandListFilter, 'enabled'>): Command[];
+    execute(id: string, args?: unknown, opts?: ExecuteOpts): Promise<unknown>;
+    executeFrom(source: CommandSource, id: string, args?: unknown, opts?: Omit<ExecuteOpts, 'source'>): Promise<unknown>;
+}

package/dist/types/command.js

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

package/dist/types/component-graph.d.ts

@@ -0,0 +1,72 @@
+export type NodeId = string;
+export type BindingPath = `$/${string}` | `/${string}`;
+export type DataBinding = {
+    path: BindingPath;
+};
+export type FunctionCall = {
+    call: string;
+    args?: Record<string, PropValue>;
+    callableFrom?: 'clientOnly';
+    returnType?: string;
+};
+export type DynamicValue = string | number | boolean | string[] | DataBinding | FunctionCall;
+export type DynamicString = string | DataBinding | FunctionCall;
+export type DynamicNumber = number | DataBinding | FunctionCall;
+export type DynamicBoolean = boolean | DataBinding | FunctionCall;
+export type DynamicStringList = string[] | DataBinding | FunctionCall;
+export type ChildList = ComponentNode[] | {
+    template: ComponentNode;
+    path: BindingPath;
+};
+export type Action = {
+    event: {
+        name: string;
+        context?: Record<string, PropValue>;
+        wantResponse?: boolean;
+        responsePath?: BindingPath;
+    };
+} | {
+    functionCall: FunctionCall;
+};
+export type CheckRule = {
+    condition: DynamicBoolean;
+    message?: DynamicString;
+};
+export type Checkable = {
+    checks?: CheckRule[];
+};
+export type AccessibilityAttributes = {
+    label?: DynamicString;
+    description?: DynamicString;
+};
+export type PropValue = string | number | boolean | null | DataBinding | FunctionCall | Action | ComponentNode | ComponentNode[] | {
+    template: ComponentNode;
+    path: BindingPath;
+} | {
+    [k: string]: PropValue;
+} | PropValue[];
+export type NodeMeta = {
+    origin?: {
+        format: string;
+        version?: string;
+        sourceNodeId?: NodeId;
+    };
+    fallback?: ComponentNode;
+};
+export type ComponentNode = {
+    id?: NodeId;
+    component: string;
+    $meta?: NodeMeta;
+    child?: PropValue | unknown;
+    children?: PropValue | unknown;
+    [prop: string]: unknown;
+};
+export type PageState = ComponentNode;
+export declare function isComponentNode(v: unknown): v is ComponentNode;
+export declare function isDataBinding(v: unknown): v is DataBinding;
+export declare function isFunctionCall(v: unknown): v is FunctionCall;
+export declare function isAction(v: unknown): v is Action;
+export declare function isDynamicChildList(v: unknown): v is {
+    template: ComponentNode;
+    path: BindingPath;
+};

package/dist/types/component-graph.js

@@ -0,0 +1,40 @@
+// a2ui v0.10 component graph types.
+//
+// A page IS its root ComponentNode. Children are nested inline as ComponentNode
+// values on `child` / `children` props (no flat-by-id map, no slots bag).
+// Three structural keys are reserved on every node: `id`, `component`, `$meta`.
+export function isComponentNode(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'component' in v &&
+        typeof v.component === 'string');
+}
+export function isDataBinding(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'path' in v &&
+        typeof v.path === 'string' &&
+        !('component' in v) &&
+        !('template' in v) &&
+        !('componentId' in v));
+}
+export function isFunctionCall(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'call' in v &&
+        typeof v.call === 'string' &&
+        !('component' in v));
+}
+export function isAction(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        ('event' in v || 'functionCall' in v) &&
+        !('component' in v));
+}
+export function isDynamicChildList(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'template' in v &&
+        'path' in v &&
+        isComponentNode(v.template));
+}

package/dist/types/component-registry.d.ts

@@ -0,0 +1,70 @@
+import type { Disposable } from './disposable.js';
+import type { BindingPath, ComponentNode } from './component-graph.js';
+import type { WhenClause } from './when.js';
+import type { ResourceColor } from './colors.js';
+import type { MountDisplay, SurfaceName } from './mount-surface.js';
+import type { ReactiveStore } from './reactive-store.js';
+import type { Scena } from './scena.js';
+import type { Label } from './label.js';
+export type ComponentCategory = 'chrome' | 'page' | 'inline' | 'statusbar' | 'picker';
+export interface ComponentOpensSpec {
+    resourceKinds?: string[];
+    selector?: WhenClause;
+    title?: Label;
+    icon?: string;
+    color?: ResourceColor;
+    priority?: number;
+    preferredSurface?: SurfaceName;
+    namespace?: string;
+}
+export interface ComponentMountContext {
+    scena: Scena;
+    store: ReactiveStore;
+    mountKey: string | null;
+    dataContext?: BindingPath;
+}
+export type ComponentMountHandler = (ctx: ComponentMountContext) => (() => void) | void;
+export type PropsSchema = Record<string, string | readonly string[]>;
+export interface EditorMetadata {
+    insertable?: boolean;
+    acceptsChildren?: boolean;
+}
+export type RendererKind = {
+    kind: 'react';
+    load: () => Promise<{
+        default: unknown;
+    }>;
+} | {
+    kind: 'template';
+    template: ComponentNode;
+} | {
+    kind: 'html';
+    mount: (host: HTMLElement, props: unknown) => Disposable;
+};
+export interface ComponentDefinition {
+    component: string;
+    renderer: RendererKind;
+    propsSchema?: PropsSchema;
+    category?: ComponentCategory;
+    editor?: EditorMetadata;
+    fallback?: ComponentNode;
+    onMount?: ComponentMountHandler;
+    opens?: ComponentOpensSpec;
+    props?: MountDisplay;
+}
+export interface ResolvedRenderer {
+    component: string;
+    renderer: RendererKind;
+    definition: ComponentDefinition;
+}
+export interface ComponentRegistry {
+    register(def: ComponentDefinition): Disposable;
+    unregister(component: string): void;
+    get(component: string): ComponentDefinition | undefined;
+    list(): ComponentDefinition[];
+    findOpeners(resourceKind: string): ComponentDefinition[];
+    resolve(component: string, options?: {
+        timeoutMs?: number;
+    }): Promise<ResolvedRenderer>;
+    pending(): string[];
+}

package/dist/types/component-registry.js

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

package/dist/types/converter-registry.d.ts

@@ -0,0 +1,17 @@
+import type { ComponentNode } from './component-graph.js';
+import type { Disposable } from './disposable.js';
+export type SchemaMatcher = {
+    header: string;
+    value?: string;
+} | ((input: unknown) => boolean);
+export interface Converter {
+    id: string;
+    accepts: SchemaMatcher;
+    translate(input: unknown): ComponentNode;
+}
+export interface ConverterRegistry {
+    register(converter: Converter): Disposable;
+    unregister(id: string): void;
+    list(): Converter[];
+    translate(input: unknown): ComponentNode;
+}

package/dist/types/converter-registry.js

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

package/dist/types/disposable.d.ts

@@ -0,0 +1,3 @@
+export interface Disposable {
+    dispose(): void;
+}

package/dist/types/disposable.js

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

package/dist/types/events.d.ts

@@ -0,0 +1,75 @@
+import type { Disposable } from './disposable.js';
+import type { ComponentNode, PropValue, BindingPath } from './component-graph.js';
+import type { SurfaceName } from './mount-surface.js';
+import type { ScenaLayout } from './layout.js';
+export type ScenaSystemEvent = 'scena:mount:opened' | 'scena:mount:closed' | 'scena:mount:focused' | 'scena:mount:blurred' | 'scena:registry:changed' | 'scena:store:changed' | 'scena:menu:changed' | 'scena:layout:changed' | 'scena:shell:changed' | 'scena:plugin:contributed' | 'scena:plugin:unloaded' | 'scena:session:skipped' | 'scena:converter:applied' | 'scena:permission:denied' | 'scena:action:event';
+export interface ScenaEventMap {
+    'scena:mount:opened': {
+        key: string;
+        surface: SurfaceName;
+        component: ComponentNode;
+    };
+    'scena:mount:closed': {
+        key: string;
+        reason?: string;
+    };
+    'scena:mount:focused': {
+        key: string;
+        surface: SurfaceName;
+    };
+    'scena:mount:blurred': {
+        key: string;
+        surface: SurfaceName;
+    };
+    'scena:registry:changed': {
+        registry: 'components' | 'commands' | 'converters' | 'menus' | 'keybindings' | 'shells' | 'layouts';
+    };
+    'scena:store:changed': {
+        path: string;
+        value: unknown;
+        previous: unknown;
+    };
+    'scena:menu:changed': {
+        slot: string;
+    };
+    'scena:layout:changed': ScenaLayout;
+    'scena:shell:changed': {
+        shellId: string;
+    };
+    'scena:plugin:contributed': {
+        sourceId: string;
+        version?: string;
+    };
+    'scena:plugin:unloaded': {
+        sourceId: string;
+    };
+    'scena:session:skipped': {
+        key: string;
+        surface: SurfaceName;
+        reason: string;
+    };
+    'scena:converter:applied': {
+        converterId: string;
+        sourceFormat: string;
+        nodeId?: string;
+    };
+    'scena:permission:denied': {
+        sourceId: string;
+        kind: 'read' | 'write' | 'command' | 'surface' | 'register';
+        path?: string;
+    };
+    'scena:action:event': {
+        mountKey: string | null;
+        name: string;
+        context?: Record<string, PropValue>;
+        wantResponse?: boolean;
+        responsePath?: BindingPath;
+    };
+}
+export interface EventBus {
+    emit<K extends keyof ScenaEventMap>(event: K, payload: ScenaEventMap[K]): void;
+    emit(event: string, payload?: unknown): void;
+    on<K extends keyof ScenaEventMap>(event: K, fn: (payload: ScenaEventMap[K]) => void): Disposable;
+    on(event: string, fn: (payload: unknown) => void): Disposable;
+    off(event: string, fn: (payload: unknown) => void): void;
+}

package/dist/types/events.js

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

package/dist/types/host.d.ts

@@ -0,0 +1,50 @@
+import type { ResourceColor } from './colors.js';
+export interface HostCtx {
+    pushList(spec: ListSpec): void;
+    replaceList(spec: ListSpec): void;
+    openInline(componentId: string, props?: Record<string, unknown>): void;
+    openPopover(componentId: string, props?: Record<string, unknown>, anchor?: {
+        x: number;
+        y: number;
+    }): void;
+    back(): void;
+    closeMenu(): void;
+    keepOpen(): void;
+    insertAtCursor(text: string): void;
+    replaceActiveToken(replacement: string): void;
+    query: string;
+}
+export type PickerAction = {
+    commandId: string;
+    args?: Record<string, unknown>;
+} | {
+    title: string;
+    description?: string;
+    icon?: string;
+    color?: ResourceColor;
+    shortcut?: string;
+    keys?: string;
+    group?: string;
+    active?: boolean;
+    disabled?: boolean;
+    onSelect(host: HostCtx): void | Promise<void>;
+};
+export type ListLayout = 'list' | 'info-list' | 'header-list';
+export interface ListSpec {
+    items?: PickerAction[];
+    extraItems?: PickerAction[];
+    provider?: (host: HostCtx) => PickerAction[] | Promise<PickerAction[]>;
+    query?: {
+        slot: string | string[];
+        q?: string;
+    };
+    layout?: ListLayout;
+    rich?: boolean;
+    header?: (host: HostCtx) => unknown;
+    detail?: (host: HostCtx, focused?: PickerAction) => unknown;
+    customHeader?: (host: HostCtx) => unknown;
+    footerHints?: boolean;
+    groupOrder?: string[];
+    title?: string;
+    sentinel?: string | string[];
+}

package/dist/types/host.js

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

package/dist/types/index.d.ts

@@ -0,0 +1,23 @@
+export * from './disposable.js';
+export * from './component-graph.js';
+export * from './when.js';
+export * from './reactive-store.js';
+export * from './scope-backend.js';
+export * from './query.js';
+export * from './label.js';
+export * from './binding-resolver.js';
+export * from './mount-surface.js';
+export * from './mount-menu.js';
+export * from './component-registry.js';
+export * from './converter-registry.js';
+export * from './permissions.js';
+export * from './events.js';
+export * from './command.js';
+export * from './colors.js';
+export * from './host.js';
+export * from './keybinding.js';
+export * from './session.js';
+export * from './layout.js';
+export * from './shell.js';
+export * from './manifest.js';
+export * from './scena.js';

package/dist/types/index.js

@@ -0,0 +1,23 @@
+export * from './disposable.js';
+export * from './component-graph.js';
+export * from './when.js';
+export * from './reactive-store.js';
+export * from './scope-backend.js';
+export * from './query.js';
+export * from './label.js';
+export * from './binding-resolver.js';
+export * from './mount-surface.js';
+export * from './mount-menu.js';
+export * from './component-registry.js';
+export * from './converter-registry.js';
+export * from './permissions.js';
+export * from './events.js';
+export * from './command.js';
+export * from './colors.js';
+export * from './host.js';
+export * from './keybinding.js';
+export * from './session.js';
+export * from './layout.js';
+export * from './shell.js';
+export * from './manifest.js';
+export * from './scena.js';

package/dist/types/keybinding.d.ts

@@ -0,0 +1,36 @@
+import type { Disposable } from './disposable.js';
+import type { WhenClause } from './when.js';
+import type { SurfaceName } from './mount-surface.js';
+export interface KeyEventLike {
+    key: string;
+    ctrlKey?: boolean;
+    shiftKey?: boolean;
+    altKey?: boolean;
+    metaKey?: boolean;
+}
+export interface Keybinding {
+    keys: string;
+    commandId: string;
+    args?: unknown[];
+    when?: WhenClause;
+    scope?: {
+        surfaceName?: SurfaceName;
+        viewId?: string;
+    };
+}
+export type KeybindingResolution = {
+    kind: 'none';
+} | {
+    kind: 'chord-pending';
+    depth: number;
+} | {
+    kind: 'fire';
+    commandId: string;
+    args?: unknown[];
+};
+export interface KeybindingRegistry {
+    register(binding: Keybinding): Disposable;
+    unregister(keys: string, commandId: string): void;
+    list(): Keybinding[];
+    resolve(event: KeyEventLike): KeybindingResolution;
+}

package/dist/types/keybinding.js

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

package/dist/types/label.d.ts

@@ -0,0 +1,9 @@
+export type Label = string | {
+    path: string;
+} | {
+    t: string;
+};
+export interface LabelResolveContext {
+    get: (path: string) => unknown;
+    translate: (key: string) => string;
+}

package/dist/types/label.js

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

package/dist/types/layout.d.ts

@@ -0,0 +1,117 @@
+import type { Disposable } from './disposable.js';
+import type { SurfaceName, ResolvedMount } from './mount-surface.js';
+import type { ReactiveStore } from './reactive-store.js';
+export interface SpatialBounds {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export type SpatialArrangement = 'cascade' | 'grid' | 'manual';
+export interface SpatialViewport {
+    scale: number;
+    panX: number;
+    panY: number;
+}
+export type TabPanelNode = TabPanelLeaf | TabPanelSplit;
+export interface TabPanelLeaf {
+    kind: 'leaf';
+    id: string;
+    tabs: string[];
+    activeKey?: string;
+}
+export type TabPanelDirection = 'row' | 'column';
+export interface TabPanelSplit {
+    kind: 'split';
+    direction: TabPanelDirection;
+    ratio?: number;
+    first: TabPanelNode;
+    second: TabPanelNode;
+}
+export type SurfacePresentation = 'docked' | 'floating' | 'sheet' | 'bar';
+export interface SurfaceLayoutState {
+    visible: boolean;
+    size?: number;
+    side?: 'left' | 'right' | 'top' | 'bottom';
+    layout?: string;
+    activeContainerKey?: string;
+    section?: string;
+    split?: {
+        ratios?: number[];
+        order?: string[];
+        collapsed?: string[];
+        pinned?: string[];
+    };
+    tabPanel?: {
+        tree: TabPanelNode;
+    };
+    spatial?: {
+        arrangement?: SpatialArrangement;
+        bounds?: Record<string, SpatialBounds>;
+        selectedKey?: string;
+        viewport?: SpatialViewport;
+    };
+    stack?: {
+        container?: {
+            title?: string;
+            icon?: string;
+            color?: string;
+        };
+        hidden?: string[];
+    };
+}
+export interface ScenaLayout {
+    surfaces: Partial<Record<SurfaceName, SurfaceLayoutState>>;
+}
+export type DeepPartial<T> = T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+export interface SetSurfaceOptions {
+    transient?: boolean;
+}
+export interface LayoutAPI {
+    get(): ScenaLayout;
+    set(layout: ScenaLayout): void;
+    patch(patch: DeepPartial<ScenaLayout>): void;
+    setSurface(surface: SurfaceName, state: Partial<SurfaceLayoutState>, opts?: SetSurfaceOptions): void;
+    subscribe(fn: (layout: ScenaLayout) => void): Disposable;
+}
+export interface LayoutStorage {
+    load(): Promise<ScenaLayout | null>;
+    save(layout: ScenaLayout): Promise<void>;
+    clear(): Promise<void>;
+}
+export interface LayoutLifecycleContext {
+    surface: SurfaceName;
+    mounts: ResolvedMount[];
+    store: ReactiveStore;
+    previousLayoutId?: string;
+}
+export interface LayoutProps {
+    surface: SurfaceName;
+    mounts: ResolvedMount[];
+    state: SurfaceLayoutState;
+    presentation?: SurfacePresentation;
+    setState(patch: Partial<SurfaceLayoutState>): void;
+    renderMount(mount: ResolvedMount): unknown;
+    onActivate(key: string): void;
+    onClose(key: string, opts?: {
+        reason?: string;
+    }): void;
+    onReorder(fromIndex: number, toIndex: number): void;
+}
+export interface LayoutDefinition {
+    id: string;
+    title: string;
+    component: unknown;
+    appliesTo?: SurfaceName[];
+    icon?: string;
+    onActivate?(ctx: LayoutLifecycleContext): void;
+    onDeactivate?(ctx: LayoutLifecycleContext): void;
+}
+export interface LayoutRegistry {
+    register(layout: LayoutDefinition): Disposable;
+    unregister(id: string): void;
+    get(id: string): LayoutDefinition | undefined;
+    list(): LayoutDefinition[];
+}

package/dist/types/layout.js

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