@yoyaflow/yoya-ui 0.3.2 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yoyaflow/yoya-ui",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "A browser-native JS UI library with declarative HTML authoring: component library, router, i18n, theming and layout, works with or without a build tool, SSR-ready.",
   "type": "module",
   "private": false,
@@ -18,6 +18,10 @@
       "types": "./types/yoya.core.d.ts",
       "import": "./dist/yoya.core.js"
     },
+    "./devtools": {
+      "types": "./types/yoya.devtools.d.ts",
+      "import": "./dist/yoya.devtools.js"
+    },
     "./echart": {
       "types": "./types/yoya.echart.d.ts",
       "import": "./dist/yoya.echart.js"
@@ -81,12 +85,20 @@
     "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
   },
   "devDependencies": {
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/state": "^6.7.4",
+    "@codemirror/theme-one-dark": "^6.1.3",
     "@eslint/js": "^10.0.1",
     "@preact/signals-core": "^1.14.4",
+    "@toast-ui/editor": "^3.2.2",
+    "ag-grid-community": "^36.1.0",
+    "codemirror": "^6.0.2",
     "eslint": "^10.8.1",
     "globals": "^17.11.0",
     "jsdom": "^29.1.1",
+    "leaflet": "^1.9.4",
     "prettier": "^3.9.6",
+    "quill": "^2.0.3",
     "typescript": "^7.0.2",
     "vite": "^8.2.0",
     "vitest": "^4.1.10"

package/types/core.d.ts

@@ -58,6 +58,7 @@ export interface ElementOptions {
   attrs?: Record<string, AttrValue>;
   style?: StyleInput;
   children?: ChildInput;
+  access?: AccessSpec;
   [key: `on${string}`]: EventHandler | undefined;
   [key: string]: unknown;
 }
@@ -83,6 +84,114 @@ export type StateType = 'boolean' | 'string' | 'number' | null | undefined;
 /** State handler invoked when a registered state changes. */
 export type StateHandler<N = ViewNode> = (value: unknown, node: N, oldValue: unknown) => void;
 
+// ---------------------------------------------------------------------------
+// Access control
+// ---------------------------------------------------------------------------
+
+export type AccessLevel = 'read' | 'write';
+
+/** Permission code on a node. Components pass bare resource codes, e.g. "system:member"; read/write level is decided by the user's grants. */
+export type AccessSpec = string;
+
+/** Options accepted by createAccess(). */
+export interface AccessOptions {
+  /** Granted permission strings, e.g. ["r.system:member", "w.system:member"]. */
+  permissions?: string[];
+  /** Roles held by the current request, e.g. ["admin"]. */
+  roles?: string[];
+  /** Roles that bypass every check (default ["super_admin"]). */
+  superAdmins?: string[];
+}
+
+/** Per-request permission context: decided by withAccess scope. */
+export interface AccessContext {
+  roles(): string[];
+  permissions(): string[];
+  isSuper(): boolean;
+  /** True when any grant (bare / r. / w.) covers the code. */
+  has(spec: AccessSpec): boolean;
+  /** True when a read grant (bare / r. / w.) covers the code. */
+  canRead(spec: AccessSpec): boolean;
+  /** True when a write grant (bare or w.) covers the code. */
+  canWrite(spec: AccessSpec): boolean;
+  setPermissions(permissions: string[]): AccessContext;
+  subscribe(listener: () => void): () => void;
+}
+
+/** Creates a per-request access context. */
+export function createAccess(options?: AccessOptions): AccessContext;
+
+/** Normalizes an access spec into { code, level }. */
+export function parseAccessSpec(
+  spec: AccessSpec | { code: string; level?: AccessLevel }
+): { code: string; level: AccessLevel } | null;
+
+/** Returns the resource code of a spec, without the read/write prefix. */
+export function stripAccessCode(spec: AccessSpec): string;
+
+/** Runs build() with the access context active, then restores the outer one. */
+export function withAccess<T>(access: AccessContext | null, build: () => T): T;
+
+/** Returns the access context active in the current render scope. */
+export function currentAccess(): AccessContext | null;
+
+/** Installs a global access context (single-user SPA); overridden by SSR options.access or withAccess scope. */
+export function installAccess(access: AccessContext | null): AccessContext | null;
+
+// ---
+// Generic scoped context
+// ---
+
+/** Per-render provider map injected by withContext / SSR options.context. */
+export type ContextProviders = Record<string, unknown>;
+
+/** Runs build() with the providers active, then restores the outer scope. */
+export function withContext<T>(providers: ContextProviders | null | undefined, build: () => T): T;
+
+/** Installs a global fallback context (single-user SPA). */
+export function installContext(
+  providers: ContextProviders | null | undefined
+): ContextProviders | null;
+
+/** Removes the globally installed fallback context. */
+export function clearInstalledContext(): null;
+
+/** Returns the nearest value for a key; falls back to installed context and defaultValue. */
+export function currentContext<T = unknown>(key: string, defaultValue?: T): T | undefined;
+
+/** Returns a shallow merged snapshot of the active context. */
+export function snapshotContext(): ContextProviders;
+
+// ---
+// Accessibility primitives
+// ---
+
+export interface FocusTrapOptions {
+  onEscape?: (event: Event) => void;
+  restoreFocus?: boolean;
+}
+
+export interface FocusTrapHandle {
+  activate(): void;
+  destroy(): void;
+}
+
+export function getFocusableElements(root: Element | null | undefined): Element[];
+export function createFocusTrap(
+  root: Element | null | undefined,
+  options?: FocusTrapOptions
+): FocusTrapHandle;
+export function announce(
+  message: string,
+  options?: { politeness?: 'polite' | 'assertive'; dedupeKey?: string }
+): HTMLElement | null;
+export function moveByKey(options: {
+  key: string;
+  items: readonly unknown[];
+  currentIndex?: number;
+  shiftKey?: boolean;
+}): number;
+
 // ---------------------------------------------------------------------------
 // View tree nodes
 // ---------------------------------------------------------------------------
@@ -109,6 +218,9 @@ export class ViewNode {
   /** Adds a text child. */
   text(content: string | number): this;
 
+  /** Declares access control: bare default read, "w.xxx" write, "r.xxx" read. */
+  access(spec: AccessSpec): this;
+
   /** Registers an event listener, bound immediately or at render time. */
   on(eventName: string, handler: EventHandler, options?: EventOptions): this;
 
@@ -362,6 +474,12 @@ export class I18n {
   /** Registers or merges a dictionary for one language. */
   register(language: string, messages?: Record<string, unknown>): this;
 
+  /** Lazily registers a language; returns a promise resolved after merge and notify. */
+  registerLocale(
+    name: string,
+    loader: () => Record<string, unknown> | Promise<Record<string, unknown>>
+  ): Promise<this>;
+
   /** Registers one or more corpora: multi-language files or { language, messages }. */
   registerMessages(corpus?: Record<string, unknown> | Array<unknown>): this;
 
@@ -559,7 +677,10 @@ export function bindWindowEvent(
 ): () => void;
 
 /** Injects a <style> into <head>; dataAttribute is used for dedup and identification. */
-export function injectDocumentStyle(styleText: string, dataAttribute?: string | null): HTMLStyleElement | null;
+export function injectDocumentStyle(
+  styleText: string,
+  dataAttribute?: string | null
+): HTMLStyleElement | null;
 
 /** Initializes theme mode/name from explicit values or persisted storage. */
 export function initYoyaTheme(options?: InitYoyaThemeOptions): {

package/types/data-display.d.ts

@@ -344,7 +344,9 @@ export interface TreeRanger {
   [key: string]: any;
 }
 
-export function vTreeRanger(setup?: TreeRangerColumn[] | TreeRangerOptions | SetupCallback<TreeRanger>): TreeRanger;
+export function vTreeRanger(
+  setup?: TreeRangerColumn[] | TreeRangerOptions | SetupCallback<TreeRanger>
+): TreeRanger;
 export const treeRanger: typeof vTreeRanger;
 export function vTreeRangerColumn(setup?: unknown): unknown;
 
@@ -518,6 +520,39 @@ export const vProgress: ElementFactory<VProgress>;
 export const vRingStat: ElementFactory<VRingStat>;
 export const vScroll: ElementFactory<VScroll>;
 export const vSparkline: ElementFactory<VSparkline>;
+export interface TreeTableColumn {
+  key?: string;
+  title?: ChildInput;
+  dataIndex?: string;
+  sorter?: boolean;
+  filterOptions?: Array<{ label: ChildInput; value: string | number }>;
+  render?: (value: unknown, row: Record<string, unknown>, index: number) => ChildInput;
+  editable?: boolean;
+  fixed?: 'left' | 'right' | string;
+  validate?: (value: unknown) => string | null | undefined;
+  width?: string | number;
+  [key: string]: any;
+}
+/** Tree table: flat rows with indent, expand/collapse, selection linkage, lazy load. */
+export class VTreeTable extends HtmlElementNode {
+  columns(value?: Array<string | number | TreeTableColumn>): this;
+  nodes(value?: Array<Record<string, any>>): this;
+  rowKey(handler?: (node: Record<string, unknown>, index: number) => string | number): this;
+  rowSelection(value?: boolean): boolean | VTreeTable;
+  lazyLoad(
+    handler?: (
+      node: Record<string, unknown>
+    ) => Array<Record<string, unknown>> | Promise<Array<Record<string, unknown>>>
+  ): VTreeTable;
+  expandedKeys(value?: Array<string>): Array<string> | VTreeTable;
+  expandKeys(value?: Array<string>): VTreeTable;
+  checkedKeys(value?: Array<string>): Array<string> | VTreeTable;
+  expandAll(): VTreeTable;
+  collapseAll(): VTreeTable;
+  visibleRowCount(): number;
+}
+
+export const vTreeTable: ElementFactory<VTreeTable>;
 export const vTable: ElementFactory<VTable>;
 export const vTbody: ElementFactory<VTbody>;
 export const vTd: ElementFactory<VTd>;
@@ -556,7 +591,10 @@ export class VImagePreview extends HtmlElementNode {
 }
 
 export const vImagePreview: ElementFactory<VImagePreview> & {
-  (first?: SetupInput<VImagePreview> | null, callback?: SetupCallback<VImagePreview>): VImagePreview;
+  (
+    first?: SetupInput<VImagePreview> | null,
+    callback?: SetupCallback<VImagePreview>
+  ): VImagePreview;
 };
 
 /** Parent-shortcut surface merged onto HtmlElementNode. */
@@ -601,6 +639,10 @@ export interface DataDisplayParentShortcuts {
     first?: SetupInput<VSparkline> | null,
     callback?: SetupCallback<VSparkline>
   ): VSparkline;
+  vTreeTable(
+    first?: SetupInput<VTreeTable> | null,
+    callback?: SetupCallback<VTreeTable>
+  ): VTreeTable;
   vTable(first?: SetupInput<VTable> | null, callback?: SetupCallback<VTable>): VTable;
   vTimeline(first?: SetupInput<VTimeline> | null, callback?: SetupCallback<VTimeline>): VTimeline;
   vTimelineItem(

package/types/devtools.d.ts

@@ -0,0 +1,156 @@
+/**
+ * yoya-ui devtools type declarations.
+ *
+ * The devtools runtime ships as a separate entry so the production main
+ * bundle never contains the debug surface. All hooks are opt-in and are
+ * no-ops until `enableDevtools()` is called.
+ */
+
+import type { ViewNode } from './core.js';
+
+/** Base shape shared by every devtools lifecycle event. */
+export interface DevtoolsEventBase {
+  /** Event kind: 'commit' | 'destroy' (extended by update/state kinds). */
+  type: string;
+  /** The view node the event belongs to, when one exists. */
+  node?: unknown;
+  /** Monotonically increasing event sequence across the stream. */
+  seq: number;
+  /** Stable id of the node the event belongs to. */
+  nodeId?: number;
+  /** Human-readable node description (tag/classes/text/component). */
+  nodeLabel?: string;
+}
+
+/** Emitted when an element is first rendered into the DOM. */
+export interface DevtoolsCommitEvent extends DevtoolsEventBase {
+  type: 'commit';
+  kind: 'mount' | 'update';
+}
+
+/** Emitted when a node is destroyed. */
+export interface DevtoolsDestroyEvent extends DevtoolsEventBase {
+  type: 'destroy';
+}
+
+/** Emitted when an attribute (including the mirrored class) changes. */
+export interface DevtoolsAttrEvent extends DevtoolsEventBase {
+  type: 'attr';
+  name: string;
+  previous?: DevtoolsAttrValue;
+  next?: DevtoolsAttrValue;
+}
+
+/** Emitted when an inline style property changes. */
+export interface DevtoolsStyleEvent extends DevtoolsEventBase {
+  type: 'style';
+  name: string;
+  previous?: string;
+  next?: string;
+}
+
+/** Emitted when a child is added, removed, or reordered. */
+export interface DevtoolsChildEvent extends DevtoolsEventBase {
+  type: 'child';
+  added?: number[];
+  removed?: number[];
+  reordered?: boolean;
+}
+
+/** Emitted when a mounted text node's content changes. */
+export interface DevtoolsTextEvent extends DevtoolsEventBase {
+  type: 'text';
+  from?: string;
+  to: string;
+}
+
+/** Emitted when a vStateNode state change is applied. */
+export interface DevtoolsStateEvent extends DevtoolsEventBase {
+  type: 'state';
+  /** Per-key before/after values for the changed state entries. */
+  changed: Record<string, { from: unknown; to: unknown }>;
+  /** Full state snapshot after the change was applied. */
+  state: Record<string, unknown>;
+  /** How the change was applied: update | bindings | rebuild | pending. */
+  handling: 'update' | 'bindings' | 'rebuild' | 'pending' | 'none';
+}
+
+/** Lifecycle events currently emitted by the devtools hook. */
+export type DevtoolsEvent =
+  | DevtoolsCommitEvent
+  | DevtoolsDestroyEvent
+  | DevtoolsAttrEvent
+  | DevtoolsStyleEvent
+  | DevtoolsChildEvent
+  | DevtoolsTextEvent
+  | DevtoolsStateEvent;
+
+/** Listener callback for the devtools event stream. */
+export type DevtoolsListener = (event: DevtoolsEvent) => void;
+
+/** Turns the devtools event stream on. Returns the new enabled state. */
+export function enableDevtools(): boolean;
+
+/** Turns the devtools event stream off. Returns the new enabled state. */
+export function disableDevtools(): boolean;
+
+/** Whether the devtools event stream is currently enabled. */
+export function isDevtoolsEnabled(): boolean;
+
+/**
+ * Subscribes to lifecycle events emitted while devtools is enabled.
+ * Returns an unsubscribe function; listener errors never break rendering.
+ */
+export function subscribeDevtools(listener: DevtoolsListener): () => void;
+
+/** Attribute values reflected from the node's attribute map. */
+export type DevtoolsAttrValue = string | number | boolean;
+
+/** Plain-shape snapshot of a node subtree for inspection. */
+export interface DevtoolsSnapshot {
+  /** Node kind: element | text | component | view | root. */
+  kind: string;
+  /** Stable per-node identifier assigned while devtools is active. */
+  id?: number;
+  /** Element tag name for element nodes. */
+  tagName?: string;
+  /** Element attribute map, including the mirrored class attribute. */
+  attrs?: Record<string, DevtoolsAttrValue>;
+  /** Text content for text nodes. */
+  text?: string;
+  /** Child snapshots. */
+  children: DevtoolsSnapshot[];
+}
+
+/** Returns a plain-shape snapshot of a node subtree. */
+export function getDevtoolsSnapshot(root: ViewNode | null): DevtoolsSnapshot;
+
+/**
+ * Returns the rendered DOM node for a snapshot id (element or text node),
+ * or null when the node is not rendered or has been destroyed.
+ */
+export function getDevtoolsDom(id: number): Element | Text | null;
+
+/** Declared access spec on a node. */
+export interface DevtoolsAccessDetail {
+  code: string;
+  level: 'write' | 'read';
+}
+
+/** Scope details for a snapshot id (access/context/i18n). */
+export interface DevtoolsScope {
+  id: number;
+  access: DevtoolsAccessDetail | null;
+  /** Effective permission result for the node, when available. */
+  permissionState?: 'active' | 'readonly' | 'hidden';
+  /** Context captured while the node was built, when devtools was on. */
+  context: Record<string, unknown> | null;
+  /** i18n instance detail for translated text nodes. */
+  i18n: { key?: string; language: string } | null;
+}
+
+/**
+ * Returns scope details for a snapshot id, or null when the node has been
+ * destroyed (or the id is unknown).
+ */
+export function getDevtoolsScope(id: number): DevtoolsScope | null;

package/types/feedback.d.ts

@@ -93,6 +93,19 @@ export const toast: {
   clear(): VMessageContainer;
 };
 
+export interface ConfirmOptions {
+  title?: ChildInput;
+  content?: ChildInput;
+  confirmText?: ChildInput;
+  cancelText?: ChildInput;
+  danger?: boolean;
+  onConfirm?: () => boolean | void | Promise<boolean>;
+  onCancel?: () => void;
+}
+
+/** 命令式确认弹窗：resolves true on confirm, false on cancel / danger. */
+export function vConfirm(options?: ConfirmOptions): Promise<boolean>;
+
 export const vDialog: ElementFactory<VDialog>;
 export const vMessage: ElementFactory<VMessage>;
 export const vMessageContainer: ElementFactory<VMessageContainer>;

package/types/form.d.ts

@@ -74,7 +74,7 @@ export class VSvgIconPicker extends HtmlElementNode {
   disabled(): boolean;
   disabled(next: boolean): VSvgIconPicker;
   name(): string;
-  name(next: string): VSvgIconPicker;
+  name(next: string): this;
   required(): boolean;
   required(next: boolean): VSvgIconPicker;
   icons(): string[];

package/types/ssr.d.ts

@@ -1,4 +1,11 @@
-import type { ComponentLike, I18n, ViewNode } from './core.js';
+import type {
+  AccessContext,
+  ComponentLike,
+  ContextProviders,
+  ElementNode,
+  I18n,
+  ViewNode
+} from './core.js';
 import type { HtmlElementNode } from './html.js';
 
 export type PageFactory<S = unknown> = (state: S) => ViewNode | ComponentLike | PageFactory<S>;
@@ -12,7 +19,18 @@ export interface SsrI18nOption<S = unknown> {
   i18n?: I18n | ((state: S | null) => I18n);
 }
 
-export interface RenderOptions<S = unknown> extends SsrI18nOption<S> {
+/** Optional access binding: an AccessContext, or a factory resolved per build. */
+export interface SsrAccessOption {
+  access?: AccessContext | (() => AccessContext | null) | null;
+}
+
+/** Optional generic context binding: a provider map, or a factory resolved per build. */
+export interface SsrContextOption {
+  context?: ContextProviders | ((state: unknown) => ContextProviders);
+}
+
+export interface RenderOptions<S = unknown>
+  extends SsrI18nOption<S>, SsrAccessOption, SsrContextOption {
   maxNodes?: number;
   state?: S | null;
 }
@@ -70,7 +88,7 @@ export function mount<S = unknown>(
   component: ViewNode | ComponentLike | PageFactory<S>,
   target: string | ParentNode,
   state?: S | null,
-  options?: SsrI18nOption<S>
+  options?: SsrI18nOption<S> & SsrAccessOption & SsrContextOption
 ): ViewNode;
 
 /** Hydrates server-rendered DOM: adopts elements and binds pending events. */
@@ -78,11 +96,11 @@ export function hydrate<S = unknown>(
   component: ViewNode | ComponentLike | PageFactory<S>,
   target: string | ParentNode,
   state?: S | null,
-  options?: SsrI18nOption<S>
+  options?: SsrI18nOption<S> & SsrAccessOption & SsrContextOption
 ): ViewNode;
 
 /** Document builder node used by renderPage: head/body callbacks build the page. */
-export class PageDocumentNode extends HtmlElementNode {
+export class PageDocumentNode extends ElementNode {
   head(callback: (node: HtmlElementNode, state: unknown) => void): PageDocumentNode;
   body(callback: (node: HtmlElementNode, state: unknown) => void): PageDocumentNode;
   vBody(...args: unknown[]): PageDocumentNode;
@@ -92,7 +110,8 @@ export interface RenderPageConfig<S = unknown> {
   page: (page: PageDocumentNode, state: S | null) => void;
 }
 
-export interface RenderPageOptions<S = unknown> extends SsrI18nOption<S> {
+export interface RenderPageOptions<S = unknown>
+  extends SsrI18nOption<S>, SsrAccessOption, SsrContextOption {
   /** Per-request dictionary; builds an I18n instance from state.lang. */
   messages?: Record<string, any>;
   maxNodes?: number;
@@ -111,7 +130,8 @@ export function renderPage<S = unknown>(
   options?: RenderPageOptions<S>
 ): string;
 
-export interface HydrateOrMountOptions<S = unknown> extends SsrI18nOption<S> {
+export interface HydrateOrMountOptions<S = unknown>
+  extends SsrI18nOption<S>, SsrAccessOption, SsrContextOption {
   messages?: Record<string, any>;
   stateId?: string;
   target?: string | ParentNode;

package/types/yoya.devtools.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Entry types for `yoya-ui/devtools`: opt-in dev lifecycle event stream and
+ * view-tree snapshot helpers.
+ */
+export * from './devtools.js';