npm - @ydant/core - Versions diffs - 0.1.0 - Mend

@ydant/core 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025 cwd-k2
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,194 @@
+# @ydant/core
+Rendering engine and plugin system for Ydant.
+## Philosophy
+**@ydant/core is a pure engine that doesn't know "what" to render.**
+Core provides only:
+- Generator processing
+- Plugin dispatch
+- Context management
+It doesn't assume DOM existence. All concrete operations (DOM manipulation, lifecycle, keyed elements) are delegated to plugins. This separation keeps core's API surface minimal and stable, allowing plugins to extend functionality without modifying core.
+For user-facing APIs like element factories and primitives, see `@ydant/base`.
+## Installation
+```bash
+pnpm add @ydant/core
+```
+## Usage
+```typescript
+import { mount } from "@ydant/core";
+import { createBasePlugin, div, text, type Component } from "@ydant/base";
+const App: Component = () => div(() => [text("Hello!")]);
+mount(App, document.getElementById("app")!, {
+  plugins: [createBasePlugin()],
+});
+```
+## API
+### Mount
+```typescript
+function mount(component: Component, container: HTMLElement, options?: MountOptions): void;
+interface MountOptions {
+  plugins?: Plugin[];
+}
+```
+### Plugin System
+```typescript
+interface Plugin {
+  name: string;
+  types: string[];
+  /** Plugin names that must be registered before this plugin */
+  dependencies?: string[];
+  /** Initialize plugin-specific properties in RenderContext */
+  initContext?(ctx: Record<string, unknown>, parentCtx?: Record<string, unknown>): void;
+  /** Extend PluginAPI with plugin-specific methods */
+  extendAPI?(api: Record<string, unknown>, ctx: Record<string, unknown>): void;
+  /** Merge parent context into child context (called when creating child contexts) */
+  mergeChildContext?(childCtx: Record<string, unknown>, parentCtx: Record<string, unknown>): void;
+  /** Process a child element */
+  process(child: Child, api: PluginAPI): PluginResult;
+}
+interface PluginResult {
+  value?: unknown; // Value to pass back via next()
+}
+```
+### Types
+| Type               | Description                                                           |
+| ------------------ | --------------------------------------------------------------------- |
+| `Tagged<T,P>`      | Helper type for tagged unions: `{ type: T } & P`                      |
+| `Child`            | Union of all yieldable types (extended by plugins)                    |
+| `ChildNext`        | Union of values passed via `next()` (extended by plugins)             |
+| `ChildReturn`      | Union of return values (extended by plugins)                          |
+| `Render`           | `Generator<Child, ChildReturn, ChildNext>` - Base rendering generator |
+| `Component`        | `() => Render` - Root component type                                  |
+| `ComponentWith<P>` | `(props: P) => Render` - Component type with props                    |
+| `Builder`          | `() => Instructor \| Instruction[]` - Element factory argument        |
+| `Instructor`       | `Iterator<Child, ChildReturn, ChildNext>` - Internal iterator         |
+| `Instruction`      | `Generator<Child, ChildReturn, ChildNext>` - Primitive return type    |
+### Plugin Extension Interfaces
+Plugins can extend these interfaces via module augmentation:
+```typescript
+declare module "@ydant/core" {
+  // Extend RenderContext with custom properties
+  interface RenderContextExtensions {
+    myProperty: MyType;
+  }
+  // Extend PluginAPI with custom methods
+  interface PluginAPIExtensions {
+    myMethod(): void;
+  }
+  // Extend Child types (yieldable values)
+  interface PluginChildExtensions {
+    MyType: Tagged<"mytype", { value: string }>;
+  }
+  // Extend values passed via next()
+  interface PluginNextExtensions {
+    MyResult: MyResultType;
+  }
+  // Extend return values
+  interface PluginReturnExtensions {
+    MyResult: MyResultType;
+  }
+}
+```
+### RenderContext
+The rendering context holds state during rendering. Plugins extend it via `RenderContextExtensions`:
+```typescript
+interface RenderContextCore {
+  parent: Node;
+  currentElement: Element | null;
+  plugins: Map<string, Plugin>;
+}
+type RenderContext = RenderContextCore & RenderContextExtensions;
+```
+### Utilities
+| Function               | Description                            |
+| ---------------------- | -------------------------------------- |
+| `isTagged(value, tag)` | Type guard for tagged union types      |
+| `toChildren(result)`   | Normalize array/iterator to Instructor |
+## Creating Plugins
+```typescript
+import type { Plugin, PluginAPI, PluginResult, Child } from "@ydant/core";
+// 1. Declare type extensions
+declare module "@ydant/core" {
+  interface RenderContextExtensions {
+    myData: Map<string, unknown>;
+  }
+  interface PluginAPIExtensions {
+    getMyData(key: string): unknown;
+    setMyData(key: string, value: unknown): void;
+  }
+}
+// 2. Create the plugin
+export function createMyPlugin(): Plugin {
+  return {
+    name: "my-plugin",
+    types: ["mytype"],
+    dependencies: ["base"], // Ensure base plugin is registered first
+    // Initialize context properties
+    initContext(ctx, parentCtx) {
+      ctx.myData = parentCtx?.myData
+        ? new Map(parentCtx.myData as Map<string, unknown>)
+        : new Map();
+    },
+    // Merge parent context into child context
+    mergeChildContext(childCtx, parentCtx) {
+      childCtx.myData = new Map(parentCtx.myData as Map<string, unknown>);
+    },
+    // Extend PluginAPI with methods
+    extendAPI(api, ctx) {
+      const myData = ctx.myData as Map<string, unknown>;
+      api.getMyData = (key: string) => myData.get(key);
+      api.setMyData = (key: string, value: unknown) => myData.set(key, value);
+    },
+    // Process child elements
+    process(child: Child, api: PluginAPI): PluginResult {
+      if ((child as { type: string }).type === "mytype") {
+        // Process the child using api.getMyData(), api.setMyData()
+        return { value: result };
+      }
+      return {};
+    },
+  };
+}
+```

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,11 @@
+/**
+ * @ydant/core
+ *
+ * 純粋な DSL 処理系とプラグインシステム
+ */
+export type { CleanupFn, Tagged, Child, ChildOfType, ChildNext, ChildReturn, Builder, Instructor, Instruction, Primitive, ChildContent, Render, Component, PluginChildExtensions, PluginNextExtensions, PluginReturnExtensions, } from './types';
+export type { Plugin, PluginAPI, PluginAPIExtensions, PluginResult, MountOptions } from './plugin';
+export { isTagged, toChildren } from './utils';
+export { mount } from './mount';
+export { render, processIterator, createRenderContext, createPluginAPIFactory } from './render';
+export type { RenderContext, RenderContextCore, RenderContextExtensions } from './render';

package/dist/index.es.js ADDED Viewed

@@ -0,0 +1,131 @@
+function C(t, o) {
+  return t.type === o;
+}
+function y(t) {
+  return Array.isArray(t) ? (function* () {
+    for (const o of t)
+      yield* o;
+  })() : t;
+}
+function p(t, o) {
+  const n = /* @__PURE__ */ new Set();
+  for (const i of t.values())
+    n.has(i.name) || (n.add(i.name), o(i));
+}
+function A(t, o, n) {
+  return {
+    parent: t,
+    currentElement: o,
+    plugins: n
+  };
+}
+function d(t, o, n, i) {
+  const r = A(t, o, n);
+  return p(n, (e) => {
+    e.initContext?.(r, i);
+  }), r;
+}
+function g(t) {
+  return function o(n) {
+    if (n._cachedAPI)
+      return n._cachedAPI;
+    const i = {
+      // ========================================================================
+      // コア機能（プラグインが拡張する基盤）
+      // ========================================================================
+      get parent() {
+        return n.parent;
+      },
+      get currentElement() {
+        return n.currentElement;
+      },
+      processChildren(e, u) {
+        const l = u?.parent ?? n.parent, s = d(
+          l,
+          l instanceof globalThis.Element ? l : null,
+          n.plugins,
+          n
+        ), c = y(e());
+        t(c, s), p(n.plugins, (P) => {
+          P.mergeChildContext?.(n, s);
+        });
+      },
+      createChildAPI(e) {
+        const u = d(
+          e,
+          e instanceof globalThis.Element ? e : null,
+          n.plugins,
+          n
+        );
+        return o(u);
+      }
+    };
+    p(n.plugins, (e) => {
+      e.extendAPI?.(i, n);
+    });
+    const r = i;
+    return n._cachedAPI = r, r;
+  };
+}
+let a = null;
+function h(t, o) {
+  a || (a = g(h));
+  let n = t.next();
+  for (; !n.done; ) {
+    const i = n.value;
+    if (i && typeof i == "object" && "type" in i) {
+      const r = i.type, e = o.plugins.get(r);
+      if (e) {
+        const u = a(o), l = e.process(i, u);
+        n = t.next(l.value);
+        continue;
+      }
+    }
+    n = t.next();
+  }
+}
+let f = null;
+function m(t, o, n) {
+  o.innerHTML = "";
+  const i = d(o, null, n);
+  f || (f = g(h));
+  let r = t.next();
+  for (; !r.done; ) {
+    const e = r.value;
+    if (e && typeof e == "object" && "type" in e) {
+      const u = e.type, l = n.get(u);
+      if (l) {
+        const s = f(i), c = l.process(e, s);
+        r = t.next(c.value);
+        continue;
+      }
+    }
+    r = t.next(void 0);
+  }
+}
+function I(t, o, n) {
+  const i = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Set();
+  if (n?.plugins) {
+    for (const e of n.plugins) {
+      r.add(e.name);
+      for (const u of e.types)
+        i.set(u, e);
+    }
+    for (const e of n.plugins)
+      if (e.dependencies)
+        for (const u of e.dependencies)
+          r.has(u) || console.warn(
+            `[ydant] Plugin "${e.name}" depends on "${u}", but "${u}" is not registered.`
+          );
+  }
+  m(t(), o, i);
+}
+export {
+  g as createPluginAPIFactory,
+  d as createRenderContext,
+  C as isTagged,
+  I as mount,
+  h as processIterator,
+  m as render,
+  y as toChildren
+};

package/dist/index.umd.js ADDED Viewed

@@ -0,0 +1 @@

package/dist/mount.d.ts ADDED Viewed

@@ -0,0 +1,24 @@
+import { MountOptions } from './plugin';
+import { Render } from './types';
+type Component = () => Render;
+/**
+ * Component を DOM にマウントする
+ *
+ * @param app - マウントするコンポーネント
+ * @param parent - マウント先の DOM 要素
+ * @param options - マウントオプション（プラグインなど）
+ *
+ * @example
+ * ```typescript
+ * import { mount } from "@ydant/core";
+ * import { createBasePlugin, div, text } from "@ydant/base";
+ *
+ * const App = () => div(() => [text("Hello!")]);
+ *
+ * mount(App, document.getElementById("app")!, {
+ *   plugins: [createBasePlugin()],
+ * });
+ * ```
+ */
+export declare function mount(app: Component, parent: HTMLElement, options?: MountOptions): void;
+export {};

package/dist/plugin.d.ts ADDED Viewed

@@ -0,0 +1,79 @@
+import { Child, ChildNext } from './types';
+import { RenderContext, RenderContextCore, RenderContextExtensions } from './render/types';
+/**
+ * プラグインが PluginAPI を拡張するためのインターフェース
+ *
+ * @example
+ * ```typescript
+ * // @ydant/base で DOM 操作用のメソッドを追加
+ * declare module "@ydant/core" {
+ *   interface PluginAPIExtensions extends BasePluginAPI {}
+ * }
+ * ```
+ */
+export interface PluginAPIExtensions {
+}
+/**
+ * プラグインが使用できる API
+ *
+ * 実際のメソッドは @ydant/base の PluginAPIExtensions 拡張で定義される
+ */
+export type PluginAPI = PluginAPIExtensions;
+/**
+ * プラグインの処理結果
+ */
+export interface PluginResult {
+    /** ジェネレータに返す値 */
+    value?: ChildNext | undefined;
+}
+/**
+ * DOM レンダラープラグイン
+ */
+export interface Plugin {
+    /** プラグイン識別子 */
+    readonly name: string;
+    /** このプラグインが処理する type タグの配列 */
+    readonly types: readonly string[];
+    /** 依存するプラグインの name 配列 */
+    readonly dependencies?: readonly string[];
+    /**
+     * RenderContext を初期化する
+     *
+     * mount 時および子コンテキスト作成時に呼び出される。
+     * プラグインは RenderContextExtensions で定義した独自プロパティを
+     * ここで初期化する。
+     *
+     * @param ctx - 初期化対象のコンテキスト（構築途中のため Partial）
+     * @param parentCtx - 親コンテキスト（ルートの場合は undefined）
+     */
+    initContext?(ctx: RenderContextCore & Partial<RenderContextExtensions>, parentCtx?: RenderContext): void;
+    /**
+     * PluginAPI を拡張する
+     *
+     * プラグイン固有のメソッドを PluginAPI に追加する。
+     * PluginAPIExtensions で定義した独自のメソッドをここで実装する。
+     *
+     * @param api - 拡張対象の PluginAPI オブジェクト
+     * @param ctx - 現在の RenderContext（initContext 後なので構築済み）
+     */
+    extendAPI?(api: Partial<PluginAPIExtensions>, ctx: RenderContext): void;
+    /**
+     * 子コンテキストの状態を親コンテキストにマージする
+     *
+     * processChildren 内で子イテレータ処理後に呼び出される。
+     * プラグインは子コンテキストから親コンテキストへの状態伝搬をここで実装する。
+     *
+     * @param parentCtx - 親コンテキスト
+     * @param childCtx - 子コンテキスト
+     */
+    mergeChildContext?(parentCtx: RenderContext, childCtx: RenderContext): void;
+    /** Child を処理する */
+    process(child: Child, api: PluginAPI): PluginResult;
+}
+/**
+ * mount のオプション
+ */
+export interface MountOptions {
+    /** 使用するプラグインの配列 */
+    plugins?: Plugin[];
+}

package/dist/render/context.d.ts ADDED Viewed

@@ -0,0 +1,24 @@
+import { Instructor } from '../types';
+import { Plugin, PluginAPI } from '../plugin';
+import { RenderContext, RenderContextCore } from './types';
+/** RenderContext のコア部分を作成 */
+export declare function createRenderContextCore(parent: Node, currentElement: globalThis.Element | null, plugins: Map<string, Plugin>): RenderContextCore;
+/**
+ * RenderContext を作成し、各プラグインで初期化
+ *
+ * @param parent - 親ノード
+ * @param currentElement - 現在の要素
+ * @param plugins - 登録されたプラグイン
+ * @param parentCtx - 親コンテキスト（子コンテキスト作成時）
+ */
+export declare function createRenderContext(parent: Node, currentElement: globalThis.Element | null, plugins: Map<string, Plugin>, parentCtx?: RenderContext): RenderContext;
+/**
+ * RenderContext から PluginAPI を作成
+ *
+ * processIterator を循環参照で受け取る必要があるため、
+ * ファクトリ関数として実装
+ *
+ * NOTE: core は基本的な API のみを提供し、プラグイン固有のメソッドは
+ * 各プラグインの extendAPI で追加される。
+ */
+export declare function createPluginAPIFactory(processIterator: (iter: Instructor, ctx: RenderContext) => void): (ctx: RenderContext) => PluginAPI;

package/dist/render/index.d.ts ADDED Viewed

@@ -0,0 +1,9 @@
+import { Render } from '../types';
+import { Plugin } from '../plugin';
+/**
+ * Render（ジェネレータ）を DOM に描画
+ */
+export declare function render(gen: Render, parent: HTMLElement, plugins: Map<string, Plugin>): void;
+export { processIterator } from './iterator';
+export { createRenderContext, createPluginAPIFactory } from './context';
+export type { RenderContext, RenderContextCore, RenderContextExtensions } from './types';

package/dist/render/iterator.d.ts ADDED Viewed

@@ -0,0 +1,9 @@
+import { Instructor } from '../types';
+import { RenderContext } from './types';
+/**
+ * Child イテレータを処理し、DOM に反映する
+ *
+ * すべての type はプラグインで処理される。
+ * 対応するプラグインがない type はスキップされる。
+ */
+export declare function processIterator(iter: Instructor, ctx: RenderContext): void;

package/dist/render/types.d.ts ADDED Viewed

@@ -0,0 +1,30 @@
+import { Plugin } from '../plugin';
+/**
+ * プラグインが RenderContext を拡張するためのインターフェース
+ *
+ * @example
+ * ```typescript
+ * // @ydant/base で keyed 要素管理用のプロパティを追加
+ * declare module "@ydant/core" {
+ *   interface RenderContextExtensions {
+ *     pendingKey: string | number | null;
+ *     keyedNodes: Map<string | number, unknown>;
+ *   }
+ * }
+ * ```
+ */
+export interface RenderContextExtensions {
+}
+/** レンダリングコンテキスト（コア部分） */
+export interface RenderContextCore {
+    /** 親ノード */
+    parent: Node;
+    /** 現在処理中の要素 */
+    currentElement: globalThis.Element | null;
+    /** 登録されたプラグイン */
+    plugins: Map<string, Plugin>;
+    /** キャッシュされた PluginAPI（内部用） */
+    _cachedAPI?: import('../plugin').PluginAPI;
+}
+/** レンダリングコンテキスト */
+export type RenderContext = RenderContextCore & RenderContextExtensions;

package/dist/types.d.ts ADDED Viewed

@@ -0,0 +1,96 @@
+/** Tagged Union を作成するヘルパー型 */
+export type Tagged<T extends string, P = {}> = {
+    type: T;
+} & P;
+/** ライフサイクルや副作用のクリーンアップ関数 */
+export type CleanupFn = () => void;
+/**
+ * プラグインが Child 型を拡張するためのインターフェース
+ *
+ * @example
+ * ```typescript
+ * // @ydant/base で Element 型を追加
+ * declare module "@ydant/core" {
+ *   interface PluginChildExtensions {
+ *     Element: Tagged<"element", { tag: string; children: Instructor }>;
+ *   }
+ * }
+ * ```
+ */
+export interface PluginChildExtensions {
+}
+/**
+ * プラグインが next() に渡す値の型を拡張するためのインターフェース
+ *
+ * @example
+ * ```typescript
+ * // @ydant/base で Slot を追加
+ * declare module "@ydant/core" {
+ *   interface PluginNextExtensions {
+ *     Slot: Slot;
+ *   }
+ * }
+ * ```
+ */
+export interface PluginNextExtensions {
+}
+/**
+ * プラグインが return で返す値の型を拡張するためのインターフェース
+ *
+ * @example
+ * ```typescript
+ * // @ydant/base で Slot を追加
+ * declare module "@ydant/core" {
+ *   interface PluginReturnExtensions {
+ *     Slot: Slot;
+ *   }
+ * }
+ * ```
+ */
+export interface PluginReturnExtensions {
+}
+/** 子要素として yield できるもの（プラグインによって拡張可能） */
+export type Child = PluginChildExtensions[keyof PluginChildExtensions];
+/** Child から特定の type を抽出するヘルパー型 */
+export type ChildOfType<T extends string> = Extract<Child, {
+    type: T;
+}>;
+/** next() に渡される値の型（プラグインによって拡張可能） */
+export type ChildNext = void | PluginNextExtensions[keyof PluginNextExtensions];
+/** return で返される値の型（プラグインによって拡張可能） */
+export type ChildReturn = void | PluginReturnExtensions[keyof PluginReturnExtensions];
+/** レンダリング命令の Iterator（内部処理用） */
+export type Instructor = Iterator<Child, ChildReturn, ChildNext>;
+/** レンダリング命令（text, attr, on 等）の戻り値型 */
+export type Instruction = Generator<Child, ChildReturn, ChildNext>;
+/** 要素ファクトリ（div, span 等）の引数型 */
+export type Builder = () => Instructor | Instruction[];
+/** 副作用のみを実行する DSL プリミティブの戻り値型 */
+export type Primitive<T extends Child> = Generator<T, void, void>;
+/** コンポーネントの children として渡すビルダー関数の戻り値型 */
+export type ChildContent = Generator<Child, unknown, ChildNext>;
+/**
+ * Element を yield し、最終的に ChildReturn を返すジェネレーター
+ *
+ * base パッケージでは Slot が PluginReturnExtensions に追加されるため、
+ * より具体的な型 (Generator<Child, Slot, Slot>) として使用される
+ */
+export type Render = Generator<Child, ChildReturn, ChildNext>;
+/**
+ * コンポーネント型
+ *
+ * - `Component` — 引数なし `() => Render`
+ * - `Component<Props>` — Props を受け取る `(props: Props) => Render`
+ *
+ * @example
+ * ```typescript
+ * const App: Component = () => div(function* () { ... });
+ *
+ * interface CounterProps { initial: number }
+ * const Counter: Component<CounterProps> = (props) =>
+ *   div(function* () {
+ *     yield* text(`Count: ${props.initial}`);
+ *   });
+ * ```
+ */
+export type Component<P = void> = [P] extends [void] ? () => Render : (props: P) => Render;

package/dist/utils.d.ts ADDED Viewed

@@ -0,0 +1,8 @@
+import { Tagged, Child, ChildOfType, Instruction, Instructor } from './types';
+/** Tagged 型の判定関数（Child に対する型ガード付きオーバーロード） */
+export declare function isTagged<T extends Child["type"]>(value: Child, tag: T): value is ChildOfType<T>;
+export declare function isTagged<T extends string>(value: {
+    type: string;
+}, tag: T): value is Tagged<T, Record<string, unknown>>;
+/** Builder の結果を Instructor に正規化する */
+export declare function toChildren(result: Instructor | Instruction[]): Instructor;

package/package.json ADDED Viewed

@@ -0,0 +1,46 @@
+{
+  "name": "@ydant/core",
+  "version": "0.1.0",
+  "description": "Generator-based DOM rendering DSL",
+  "keywords": [
+    "dsl",
+    "generator",
+    "rendering",
+    "ui",
+    "ydant"
+  ],
+  "homepage": "https://github.com/cwd-k2/ydant#readme",
+  "bugs": {
+    "url": "https://github.com/cwd-k2/ydant/issues"
+  },
+  "license": "MIT",
+  "author": "cwd-k2",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cwd-k2/ydant.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "main": "./dist/index.umd.js",
+  "module": "./dist/index.es.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "@ydant/dev": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.umd.js"
+    }
+  },
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc --noEmit"
+  }
+}