@usenagi/core 0.3.0 → 0.4.1

package/types/core/addon.d.ts

@@ -20,13 +20,6 @@ export type AddonContext = {
     addMountMiddleware(middleware: MountMiddleware): void;
     addUnmountMiddleware(middleware: UnmountMiddleware): void;
 };
-type AddonRegistry = AddonContext & {
-    composeComponent<S extends ComponentSetup>(setup: S): S;
-    composeMount(mountFn: MountFn, setup: ComponentSetup, opts: MountOptions): MountFn;
-    composeUnmount(unmountFn: UnmountFn): UnmountFn;
-    install(addon: Addon): void;
-};
-export declare function createAddonRegistry(): AddonRegistry;
 /**
  * Identity helper for type inference only — no runtime effect.
  */

package/types/core/app.d.ts

@@ -1,9 +1,8 @@
-import type { ComponentSetup, RefElement } from "../types";
+import type { ComponentContext, ComponentSetup, ExposedSetup, RefElement } from "../types";
 import type { Addon, MountOptions } from "./addon";
-import type { ComponentContext } from "./component";
 type App = {
     install(...addons: Addon[]): App;
-    component<S extends ComponentSetup>(component: S, opts?: MountOptions): (el: RefElement, props?: Record<string, any>) => ComponentContext<ReturnType<S["setup"]>> | void;
+    component<S extends ComponentSetup>(component: S, opts?: MountOptions): (el: RefElement, props?: Record<string, any>) => ComponentContext<ExposedSetup<ReturnType<S["setup"]>>> | void;
     unmount(targets: RefElement[]): void;
 };
 export declare function create(): App;

package/types/core/component.d.ts

@@ -1,26 +1,4 @@
 import type { ComponentProps, ComponentSetup, RefElement } from "../types";
-export declare enum LifecycleHooks {
-    MOUNTED = "Mounted",
-    UNMOUNTED = "Unmounted"
-}
-export declare class ComponentContext<T = any> {
-    #private;
-    private [LifecycleHooks.MOUNTED];
-    private [LifecycleHooks.UNMOUNTED];
-    parent: ComponentContext<T> | null;
-    readonly uid: string;
-    readonly name: string;
-    current: ReturnType<ComponentSetup<T>["setup"]>;
-    props: Parameters<ComponentSetup<T>["setup"]>[1];
-    element: RefElement;
-    provides: Map<symbol, unknown>;
-    constructor(element: RefElement, name: string);
-    onMount: () => void;
-    onUnmount: () => void;
-    addChild: (child: ComponentContext) => void;
-    removeChild: (child: ComponentContext) => void;
-    get childElements(): RefElement[];
-}
 export declare function defineComponent<SetupResult extends Record<string, unknown> | void, Props extends Record<string, unknown>>(opts: {
     name: string;
     props: Props;

package/types/core/error.d.ts

@@ -1,5 +1,5 @@
 import type { RefElement } from "../types";
-import type { ComponentContext } from "./component";
+import type { ComponentContextImpl } from "./_internal/component";
 export type LifecycleErrorDetails = {
     phase: "setup" | "mount" | "unmount" | "removeChild";
     name: string;
@@ -11,10 +11,9 @@ export type LifecycleErrorDetails = {
     props?: unknown;
     cause: unknown;
 };
-export declare function traceComponentTree(context: ComponentContext): string;
 export declare class LifecycleError extends Error {
     readonly details: LifecycleErrorDetails;
     constructor(details: LifecycleErrorDetails);
-    static create(phase: LifecycleErrorDetails["phase"], target: ComponentContext, cause: unknown, parent?: ComponentContext | null | undefined, extra?: Partial<LifecycleErrorDetails>): LifecycleError;
+    static create(phase: LifecycleErrorDetails["phase"], target: ComponentContextImpl, cause: unknown, parent?: ComponentContextImpl | null | undefined, extra?: Partial<LifecycleErrorDetails>): LifecycleError;
 }
 export declare function isLifecycleError(error: unknown): error is LifecycleError;

package/types/core/runtime.d.ts

@@ -1,4 +1,5 @@
-import { ComponentContext } from "./component";
+import { ComponentContextImpl } from "./_internal/component";
 import type { ComponentSetup, RefElement } from "../types";
-export declare function getCurrentComponent(hookName: string): ComponentContext;
-export declare function createComponent(wrap: ComponentSetup, root: RefElement, props?: Record<string, any>): ComponentContext<any>;
+declare function getCurrentComponent(hookName: string): ComponentContextImpl;
+declare function createComponent<S extends ComponentSetup>(wrap: S, root: RefElement, props?: Record<string, any>): ComponentContextImpl<ReturnType<S["setup"]>>;
+export {};

package/types/hooks/{useDomRef.d.ts → core/useDomRef.d.ts}

@@ -1,4 +1,4 @@
-import type { RefElement } from "../types";
+import type { RefElement } from "../../types";
 export declare function useDomRef<T extends Record<string, RefElement | RefElement[] | null>>(): {
     refs: T;
 };

package/types/hooks/{useSlot.d.ts → core/useSlot.d.ts}

@@ -1,6 +1,5 @@
-import type { ComponentContext } from "../core/component";
-import type { ComponentSetup, RefElement } from "../types";
+import type { ComponentContext, ComponentSetup, ExposedSetup, RefElement } from "../../types";
 export declare function useSlot(): {
-    addChild<Child extends ComponentSetup>(targetOrTargets: RefElement | RefElement[], child: Child, props?: Partial<Parameters<Child["setup"]>[1]>): ComponentContext<ReturnType<Child["setup"]>>[];
+    addChild<Child extends ComponentSetup>(targetOrTargets: RefElement | RefElement[], child: Child, props?: Partial<Parameters<Child["setup"]>[1]>): ComponentContext<ExposedSetup<ReturnType<Child["setup"]>>>[];
     removeChild(children: ComponentContext[]): void;
 };

package/types/main.d.ts

@@ -1,19 +1,18 @@
 export { defineAddon } from "./core/addon";
 export { create } from "./core/app";
 export { defineComponent } from "./core/component";
+export { createContext, withContext } from "./core/context";
 export { isLifecycleError, LifecycleError } from "./core/error";
 export { useMount, useUnmount } from "./core/lifecycle";
+export { propTypes } from "./core/props";
 export { readonly, signal, useComputed, useWatch } from "./core/reactivity";
-export { createContext, withContext } from "./hooks/createContext";
-export { useDomRef } from "./hooks/useDomRef";
+export { useDomRef } from "./hooks/core/useDomRef";
+export { useSlot } from "./hooks/core/useSlot";
 export { useEvent } from "./hooks/useEvent";
 export { useIntersectionWatch } from "./hooks/useIntersectionWatch";
 export { useMediaQuery } from "./hooks/useMediaQuery";
-export { useSlot } from "./hooks/useSlot";
-export { propTypes } from "./props";
-export type { Addon, AddonContext, ComponentMiddleware, MountFn, MountMiddleware, MountOptions, UnmountFn, UnmountMiddleware, } from "./core/addon";
-export type { ComponentContext } from "./core/component";
+export type { Addon, AddonContext, MountOptions } from "./core/addon";
+export type { Provider } from "./core/context";
 export type { LifecycleErrorDetails } from "./core/error";
 export type { ReadonlySignal, Signal } from "./core/reactivity";
-export type { Provider } from "./hooks/createContext";
-export type { ComponentSetup, Cue, IComponent, RefElement, SchedulePriority, Scheduler, } from "./types";
+export type { Cleanup, ComponentContext, ComponentSetup, Cue, RefElement, SchedulePriority, } from "./types";

package/types/types.d.ts

@@ -1,18 +1,20 @@
 export type RefElement = HTMLElement | SVGElement;
 export type ComponentProps<Props> = Readonly<Props>;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/** Normalize the return value of setup to the type stored in `current` (void / undefined → empty object). */
+export type ExposedSetup<T> = IsAny<T> extends true ? Record<string, unknown> : [T] extends [void | undefined] ? Record<string, never> : T extends Record<string, unknown> ? T : Record<string, never>;
 export type ComponentSetup<SetupResult = void | Record<string, unknown>, Props extends Record<string, unknown> = Record<string, unknown>> = {
     name: string;
     setup(el: RefElement, props: ComponentProps<Props>): SetupResult;
 };
-/** @deprecated Use `ComponentSetup` instead. */
-export type IComponent<SetupResult = void | Record<string, unknown>, Props extends Record<string, unknown> = Record<string, unknown>> = ComponentSetup<SetupResult, Props>;
+/** Mounted component instance exposed to app / hook callers. */
+export type ComponentContext<Exposed extends Record<string, unknown> = Record<string, never>> = {
+    readonly current: Exposed;
+    readonly element: RefElement;
+    readonly name: string;
+};
 export type Cleanup = () => void;
 export type LifecycleHandler = () => void | Cleanup;
 export type SchedulePriority = "user-blocking" | "user-visible" | "background";
-export type Scheduler = {
-    schedule(task: () => void, options?: {
-        priority?: SchedulePriority;
-        signal?: AbortSignal;
-    }): void;
-};
 export type Cue = (el: RefElement, signal: AbortSignal) => Promise<void>;
+export {};

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2022 hayakawasho
-
-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.ja.md

@@ -1,269 +0,0 @@
-[English](./README.md) | **日本語**
-
-# nagi
-
-**Composition-style ergonomics for vanilla DOM. Bring your own mounter.**
-
-[![npm](https://img.shields.io/npm/v/@usenagi/core)](https://www.npmjs.com/package/@usenagi/core)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/@usenagi/core)](https://bundlephobia.com/package/@usenagi/core)
-[![license](https://img.shields.io/npm/l/@usenagi/core)](./LICENSE)
-
----
-
-## Why nagi?
-
-**既存 HTML に小さく足せる**
-
-WordPress、CMS、Webflow、静的サイトなどに、仮想 DOM やテンプレートを持ち込まず、`setup()` / lifecycle / reactivity を追加できる。
-
-**アニメーションと相性が良い**
-
-GSAP、Lenis、IntersectionObserver などを `setup()` で初期化し、`useUnmount()` でクリーンアップできる。
-
-**マウント戦略を縛らない**
-
-`[data-component]` スキャン、manifest、lazy import、MutationObserver などは、利用側で自由に組み立てられる。
-
----
-
-## 30-second example
-
-```ts
-// counter.ts
-import { create, signal, useWatch, useDomRef } from "@usenagi/core";
-
-const { component } = create();
-
-component({
-  name: "counter",
-  setup() {
-    const { refs } = useDomRef<{
-      count: HTMLSpanElement;
-      btn: HTMLButtonElement;
-    }>();
-
-    const n = signal(0);
-    useWatch(n, (v) => {
-      refs.count.textContent = String(v);
-    });
-    refs.btn.addEventListener("click", () => {
-      n.value++;
-    });
-  },
-})(document.querySelector("#counter")!);
-```
-
-```html
-<div id="counter">
-  <span data-ref="count">0</span>
-  <button data-ref="btn">+</button>
-</div>
-```
-
----
-
-## Quick start
-
-```bash
-npm i @usenagi/core
-```
-
-### First component
-
-```ts
-import { create, defineComponent, signal, useWatch, useDomRef } from "@usenagi/core";
-
-const Greeting = defineComponent({
-  name: "greeting",
-  setup(el, props) {
-    const { refs } = useDomRef<{ message: HTMLParagraphElement }>();
-    const text = signal((props.name as string) ?? "world");
-
-    useWatch(text, (v) => {
-      refs.message.textContent = `Hello, ${v}!`;
-    });
-    refs.message.textContent = `Hello, ${text.value}!`;
-  },
-});
-
-create().component(Greeting)(document.querySelector("#app")!);
-```
-
-### Scheduler + deferred mount
-
-遅延マウントが必要な場合は、scheduler / cue addons を追加する。
-
-```ts
-import { create } from "@usenagi/core";
-import { schedulerAddon } from "@usenagi/core/addons/scheduler";
-import { visible, idle } from "@usenagi/core/addons/cue";
-
-const app = create().install(schedulerAddon());
-
-// mount when the element enters the viewport
-app.component(HeavyWidget, { when: visible() })(el);
-
-// mount during browser idle time
-app.component(Analytics, { when: idle() })(el);
-```
-
-`schedulerAddon()` を使うと、`when` は `setup()` の前に待機する条件、`priority` は `setup()` を含む mount task の実行タイミングを決める。
-
-### BYO mounter recipe
-
-`[data-component]` スキャン、manifest、cue を組み合わせた自動マウントの例。
-→ [examples/recipes/byo-mounter](./examples/recipes/byo-mounter/main.ts)
-
----
-
-## API
-
-### Reactivity
-
-| API                    | 説明                                                   |
-| ---------------------- | ------------------------------------------------------ |
-| `signal(value)`        | `.value` を持つリアクティブな値コンテナを作成する      |
-| `readonly(signal)`     | 書き込み可能な `signal` の読み取り専用ラッパー         |
-| `useComputed(fn)`      | `signal` の依存を自動追跡する派生値                    |
-| `useWatch(target, cb)` | 値変更時に `cb` を呼ぶ。unmount 時に自動で購読解除する |
-
-```ts
-const width = signal(10);
-const height = signal(5);
-const area = useComputed(() => width.value * height.value); // auto-recomputed
-
-useWatch(area, (v) => {
-  output.textContent = String(v);
-});
-```
-
-### Lifecycle
-
-| API              | 説明                                        |
-| ---------------- | ------------------------------------------- |
-| `useMount(fn)`   | コンポーネントのマウント完了後に1回実行する |
-| `useUnmount(fn)` | unmount 時に実行する。クリーンアップに使う  |
-
-```ts
-import gsap from 'gsap';
-
-setup(el) {
-  const tween = gsap.from(el, { opacity: 0, duration: 0.4 });
-  useUnmount(() => tween.kill());
-}
-```
-
-### DOM helpers
-
-ルート要素には **`setup(el)`** を、**`[data-ref]`** の子要素には **`useDomRef()`** を使う。
-
-| API                            | 説明                                                    |
-| ------------------------------ | ------------------------------------------------------- |
-| `useDomRef<T>()`               | `[data-ref]` 要素への型付きアクセス                     |
-| `useEvent(el, event, handler)` | イベントリスナーを追加する。unmount 時に自動で除去する  |
-| `useSlot()`                    | 子コンポーネントをマウントする。親の unmount に連動する |
-
-### Parent / child
-
-`useSlot()` で子コンポーネントをマウントできる。親から子へは `props` または `createContext` / `withContext` で値を渡せる。`addChild()` が返す child context から、子の `setup()` の返り値も参照できる。
-
-→ [examples/parent-child](./examples/parent-child/main.ts)
-
-### Observers
-
-| API                               | 説明                                                        |
-| --------------------------------- | ----------------------------------------------------------- |
-| `useIntersectionWatch(cb, opts?)` | IntersectionObserver のラッパー。unmount 時に自動で切断する |
-| `useMediaQuery(query)`            | `matchMedia` の結果を `ReadonlySignal<boolean>` で返す      |
-
-### Addons
-
-```ts
-import { create, defineAddon } from "@usenagi/core";
-import { schedulerAddon } from "@usenagi/core/addons/scheduler";
-
-const app = create().install(schedulerAddon(), myAddon());
-```
-
-| API | 説明 |
-| --- | --- |
-| `defineAddon({ name, install(ctx) })` | addon を定義する（`ctx` は `AddonContext`） |
-| `app.install(...addons)` | app に addon を登録する（複数可） |
-| `ctx.addMountMiddleware` / `addUnmountMiddleware` / `addComponentMiddleware` | mount / unmount / ComponentSetup の middleware を追加する |
-| `ctx.installedAddons` | この app に install 済みの addon 名 |
-
-`addMountMiddleware` / `addUnmountMiddleware` / `addComponentMiddleware` は **後から install した addon ほど外側**に適用される（`install(a, b)` なら実行順は `b → a → コア`）。
-
-遅延 mount には `schedulerAddon()` が必要。`when` や `priority` を使う場合も同様で、これらの mount option は scheduler addon が解釈する。addon の状態（scheduler / pending）は **各 app の `install` ごと**に作られる。
-
-#### Scheduler + cue
-
-```ts
-import { schedulerAddon } from "@usenagi/core/addons/scheduler";
-import { visible, idle, interaction, media } from "@usenagi/core/addons/cue";
-```
-
-| API | 説明 |
-| --- | --- |
-| `schedulerAddon(opts?)` | 遅延 mount 用 addon（内部で `createScheduler` を使用） |
-| `createScheduler(opts?)` | カスタム Scheduler 実装用の low-level API |
-| `visible(opts?)` | 要素が viewport に入ったときに解決する Cue |
-| `idle(timeout?)` | `requestIdleCallback` で解決する Cue |
-| `interaction(events?)` | 最初のユーザー操作で解決する Cue |
-| `media(query)` | media query が一致したときに解決する Cue |
-
----
-
-## Comparison
-
-|                            | **nagi** | Alpine.js | Stimulus | petite-vue |
-| -------------------------- | -------- | --------- | -------- | ---------- |
-| Inline JS in HTML          | ✗        | ◯         | ✗        | ◯          |
-| Composition-style setup    | ◯        | △         | ✗        | ◯          |
-| BYO mounter                | ◯        | △         | △        | △          |
-| Async mount cue            | ◯        | ✗         | ✗        | ✗          |
-| Lifecycle cleanup          | ◯        | △         | ◯        | △          |
-| computed (derived signals) | ◯        | ◯         | ✗        | ◯          |
-| Core gzip                  | ~2.5 kB  | ~16 kB    | ~8 kB    | ~6 kB      |
-
-(◯ = 組み込み、△ = 利用側の実装・規約で対応可能、✗ = 主な機能ではない)
-
-- **vs Alpine / petite-vue**: HTML に式を直接書かず、ロジックを `.ts` に集約する。
-- **vs Stimulus**: Controller 規約はない。マウント戦略は利用側で自由に組み立てられる。
-- **vs React / Vue**: 宣言的 UI フレームワークではなく、既存 DOM に lifecycle を足す薄いレイヤー。
-
----
-
-## When to use / When not to
-
-**向いているケース:**
-
-- React や Vue のランタイムを持ち込みにくいプロジェクト（CMS、Webflow、WordPress など）
-- GSAP や Lenis を多用する、アニメーション主体のサイト
-- ページの一部だけにインタラクティブな UI を追加したい場合
-- `setup()`、lifecycle、reactivity による composition-style で書きたいが、仮想 DOM は不要な場合
-
-**向いていないケース:**
-
-- リスト描画や条件分岐を HTML テンプレートで書きたい場合（`v-for` や `v-if` 相当はない）
-- 複雑なオブジェクトの深いリアクティビティが必要な場合（`reactive({})` は提供しない）
-- SSR / hydration が必要な場合
-- 状態管理、ルーティング、宣言的な view rendering をフレームワークにまとめて任せたい場合
-
----
-
-## Examples
-
-| Example                                               | 説明                                                |
-| ----------------------------------------------------- | --------------------------------------------------- |
-| [basic-counter](./examples/basic-counter/)            | 最小の `signal` + `useWatch` 例                     |
-| [computed](./examples/computed/)                      | `useComputed` による派生値（width × height = area） |
-| [parent-child](./examples/parent-child/)              | `createContext` + `withContext` + `useSlot`         |
-| [lenis-scroll-scene](./examples/lenis-scroll-scene/)  | Lenis + `useComputed` によるスクロール進捗連動      |
-| [byo-mounter recipe](./examples/recipes/byo-mounter/) | `[data-component]` スキャン + manifest + cue        |
-
----
-
-## License
-
-MIT © [hayakawasho](https://github.com/hayakawasho)