@iyulab/router 0.7.4 → 0.7.6

package/skills/iyulab-router/references/REFERENCE.md

@@ -0,0 +1,175 @@
+# @iyulab/router — Reference
+
+## URL Parameter Patterns
+
+```ts
+// Required
+{ path: '/user/:id' }
+
+// Optional
+{ path: '/posts/:category?' }
+
+// Wildcard (catch-all)
+{ path: '/docs/:path*' }
+
+// Multiple
+{ path: '/org/:orgId/repo/:repoId' }
+```
+
+Access via `ctx.params.id`, `ctx.params.category`, etc.
+
+## Query String
+
+```ts
+// URL: /search?q=hello&page=2
+ctx.query.get('q')     // 'hello'
+ctx.query.get('page')  // '2'
+```
+
+## Route Meta
+
+Meta from the full matched chain is merged (parent → child, child overrides):
+
+```ts
+{
+  path: '/admin',
+  meta: { requiresAuth: true, layout: 'admin' },
+  render: (ctx) => {
+    // ctx.meta === { requiresAuth: true, layout: 'admin' }
+    return html`<admin-layout><u-outlet></u-outlet></admin-layout>`;
+  },
+  children: [
+    {
+      path: 'settings',
+      meta: { role: 'superadmin' },
+      render: (ctx) => {
+        // ctx.meta === { requiresAuth: true, layout: 'admin', role: 'superadmin' }
+        return html`<admin-settings></admin-settings>`;
+      }
+    }
+  ]
+}
+```
+
+## Async Render with Progress
+
+```ts
+{
+  path: '/user/:id',
+  render: async (ctx) => {
+    ctx.progress(20);
+    const user = await fetchUser(ctx.params.id);
+    ctx.progress(80);
+    return html`<user-profile .data=${user}></user-profile>`;
+  }
+}
+```
+
+## Route Events
+
+```ts
+window.addEventListener('route-begin', (e) => {
+  console.log('navigating to:', e.context.pathname);
+});
+
+window.addEventListener('route-progress', (e) => {
+  progressBar.value = e.progress; // 0–100
+});
+
+window.addEventListener('route-done', (e) => {
+  analytics.track(e.context.pathname);
+});
+
+window.addEventListener('route-error', (e) => {
+  errorTracker.report(e.error);
+});
+```
+
+## Error Fallback
+
+```ts
+fallback: {
+  render: (ctx) => {
+    const { code, message } = ctx.error;
+    if (code === 'NOT_FOUND') return html`<not-found-page></not-found-page>`;
+    return html`<error-page .message=${message}></error-page>`;
+  }
+}
+```
+
+## React Usage
+
+```tsx
+import { UOutlet, ULink } from '@iyulab/router/react';
+
+export function AppRoot() {
+  return (
+    <div>
+      <nav>
+        <ULink href="/">Home</ULink>
+        <ULink href="/about">About</ULink>
+      </nav>
+      <main>
+        <UOutlet />
+      </main>
+    </div>
+  );
+}
+```
+
+Mixed Lit + React routes:
+
+```ts
+const routes = [
+  {
+    path: '/lit-page',
+    render: () => html`<my-lit-component></my-lit-component>`
+  },
+  {
+    path: '/react-page',
+    render: () => <MyReactComponent />
+  },
+  {
+    path: '/raw-element',
+    render: (ctx) => {
+      const el = document.createElement('my-element');
+      el.data = ctx.params;
+      return el;
+    }
+  }
+];
+```
+
+## RouterConfig Options
+
+| Option | Default | Description |
+|---|---|---|
+| `root` | — | Mount element (required) |
+| `basepath` | `'/'` | URL base path |
+| `routes` | `[]` | Route definitions |
+| `fallback` | built-in error page | Error/404 handler |
+| `useIntercept` | `true` | Intercept `<a>` clicks for client routing |
+| `initialLoad` | `true` | Auto-navigate to current URL on init |
+
+## Lit Element Integration
+
+```ts
+import "@iyulab/router"; // registers <u-outlet> and <u-link>
+import { LitElement, html } from 'lit';
+import { customElement } from 'lit/decorators.js';
+
+@customElement('app-root')
+export class AppRoot extends LitElement {
+  render() {
+    return html`
+      <nav>
+        <u-link href="/">Home</u-link>
+        <u-link href="/about">About</u-link>
+      </nav>
+      <main>
+        <u-outlet></u-outlet>
+      </main>
+    `;
+  }
+}
+```

package/dist/share-CG-3Tbuy.js

@@ -1,224 +0,0 @@
-import { render, css, LitElement, html } from "lit";
-import { property, customElement } from "lit/decorators.js";
-import { ifDefined } from "lit/directives/if-defined.js";
-class UOutlet extends HTMLElement {
-  /**
-   * 주어진 렌더링 옵션에 따라 컨텐츠를 렌더링합니다.
-   */
-  async render({ id, value, force }) {
-    if (this.routeId === id && force === false) return;
-    this.routeId = id;
-    this.reset();
-    if (value === null) {
-      throw new Error("Content is null and cannot be rendered.");
-    }
-    if (typeof value !== "object") {
-      throw new Error("Content is not a valid renderable object.");
-    }
-    if (value instanceof HTMLElement) {
-      this.replaceChildren(value);
-      this.root = void 0;
-    } else if ("_$litType$" in value) {
-      this.root = render(value, this);
-    } else if ("$$typeof" in value) {
-      const { createRoot } = await import("react-dom/client");
-      this.root = createRoot(this);
-      this.root.render(value);
-    } else {
-      throw new Error("not supported content type for Outlet rendering.");
-    }
-  }
-  /**
-   * 기존 DOM을 삭제하여, 초기 상태로 되돌립니다.
-   */
-  reset() {
-    if (this.root && "_$litPart$" in this) {
-      delete this._$litPart$;
-    }
-    if (this.root && "unmount" in this.root) {
-      this.root.unmount();
-    }
-    this.root = void 0;
-    this.innerHTML = "";
-  }
-}
-customElements.define("u-outlet", UOutlet);
-function isExternalUrl(url) {
-  if (!url) return false;
-  url = url.trim();
-  if (/^(?:mailto:|tel:|javascript:)/i.test(url)) return true;
-  if (url.startsWith("//")) return true;
-  try {
-    const base = typeof window !== "undefined" ? window.location.origin : "http://localhost";
-    const parsed = new URL(url, base);
-    if (/^(?:ftp:|ftps:|ws:|wss:)/i.test(parsed.protocol)) return true;
-    return parsed.origin !== new URL(base).origin;
-  } catch {
-    return false;
-  }
-}
-function parseUrl(url, basepath) {
-  let urlObj;
-  basepath = catchBasepath(basepath);
-  if (url.startsWith("http")) {
-    urlObj = new URL(url);
-  } else if (url.startsWith("/")) {
-    urlObj = new URL(url, window.location.origin);
-  } else if (url.startsWith("?")) {
-    urlObj = new URL(window.location.pathname + url, window.location.origin);
-  } else if (url.startsWith("#")) {
-    urlObj = new URL(window.location.pathname + window.location.search + url, window.location.origin);
-  } else {
-    urlObj = new URL(absolutePath(basepath, url), window.location.origin);
-  }
-  return {
-    href: urlObj.href,
-    origin: urlObj.origin,
-    basepath,
-    path: urlObj.href.replace(urlObj.origin, ""),
-    pathname: urlObj.pathname,
-    query: new URLSearchParams(urlObj.search),
-    hash: urlObj.hash,
-    params: {},
-    progress: () => {
-    },
-    meta: {}
-  };
-}
-function absolutePath(...paths) {
-  paths = paths.map((p) => p.replace(/^\/|\/$/g, "")).filter((p) => p.length > 0);
-  if (paths.length === 0) return "/";
-  return "/" + paths.join("/");
-}
-function catchBasepath(basepath) {
-  if (basepath === "/") return basepath;
-  let pattern = new URLPattern({ pathname: basepath + "/*" });
-  let match = pattern.exec({ pathname: window.location.pathname });
-  if (match) {
-    const rawPath = match.pathname.input;
-    const restPath = match.pathname.groups?.["0"];
-    return restPath !== void 0 && restPath !== "" ? rawPath.replace("/" + restPath, "") : rawPath.replace(/\/$/, "");
-  }
-  pattern = new URLPattern({ pathname: `${basepath}{/}?` });
-  match = pattern.exec({ pathname: window.location.pathname });
-  if (match) {
-    return match.pathname.input;
-  }
-  return basepath;
-}
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __decorateClass = (decorators, target, key, kind) => {
-  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
-  for (var i = decorators.length - 1, decorator; i >= 0; i--)
-    if (decorator = decorators[i])
-      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-  if (kind && result) __defProp(target, key, result);
-  return result;
-};
-let ULink = class extends LitElement {
-  constructor() {
-    super(...arguments);
-    this.isExternal = false;
-    this.handleClick = (event) => {
-      if (event.defaultPrevented) return;
-      if (event.button !== 0) return;
-      if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
-      if (this.target && this.target.toLowerCase() !== "_self") return;
-      const basepath = this.getBasepath();
-      if (!this.href) {
-        event.preventDefault();
-        this.dispatchPopstate(basepath, basepath);
-        return;
-      }
-      if (this.isExternal) return;
-      if (this.href.startsWith("#")) return;
-      event.preventDefault();
-      if (this.href.startsWith("?")) {
-        const url2 = window.location.pathname + this.href;
-        this.dispatchPopstate(basepath, url2);
-        return;
-      }
-      if (this.href.startsWith("/")) {
-        if (!this.href.startsWith(basepath)) {
-          window.location.assign(this.href);
-          return;
-        }
-        this.dispatchPopstate(basepath, this.href);
-        return;
-      }
-      const url = absolutePath(basepath, this.href);
-      this.dispatchPopstate(basepath, url);
-    };
-  }
-  connectedCallback() {
-    super.connectedCallback();
-    this.addEventListener("click", this.handleClick);
-  }
-  disconnectedCallback() {
-    this.removeEventListener("click", this.handleClick);
-    super.disconnectedCallback();
-  }
-  willUpdate(changedProperties) {
-    super.willUpdate(changedProperties);
-    if (changedProperties.has("href")) {
-      this.isExternal = isExternalUrl(this.href || "");
-    }
-  }
-  render() {
-    return html`
-      <a target=${ifDefined(this.target)} href=${this.compute(this.href)}>
-        <slot></slot>
-      </a>
-    `;
-  }
-  /** a 태그에 주입할 href 값을 계산합니다. */
-  compute(href) {
-    const basepath = this.getBasepath();
-    if (!href) return window.location.origin + basepath;
-    if (this.isExternal) return href;
-    if (href.startsWith("/")) return href;
-    if (href.startsWith("#") || href.startsWith("?")) return href;
-    return absolutePath(basepath, href);
-  }
-  /** 클라이언트 라우팅을 위해 popstate 이벤트를 발생시킵니다. */
-  dispatchPopstate(basepath, url) {
-    window.history.pushState({ basepath }, "", url);
-    window.dispatchEvent(new PopStateEvent("popstate"));
-  }
-  /** basepath를 state에서 꺼내는 헬퍼 */
-  getBasepath() {
-    return window.history.state?.basepath || "/";
-  }
-};
-ULink.styles = css`
-    :host {
-      cursor: pointer;
-    }
-
-    a {
-      text-decoration: none;
-
-      font-size: inherit;
-      font-weight: inherit;
-      font-family: inherit;
-      color: inherit;
-      cursor: inherit;
-    }
-  `;
-__decorateClass([
-  property({ type: String })
-], ULink.prototype, "target", 2);
-__decorateClass([
-  property({ type: String })
-], ULink.prototype, "href", 2);
-ULink = __decorateClass([
-  customElement("u-link")
-], ULink);
-export {
-  ULink as U,
-  absolutePath as a,
-  UOutlet as b,
-  isExternalUrl as i,
-  parseUrl as p
-};