@dooboostore/simple-web-component 1.0.53 → 1.0.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dooboostore/simple-web-component",
-  "version": "1.0.53",
+  "version": "1.0.55",
   "license": "MIT",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/decorators/addEventListener.ts

@@ -1172,6 +1172,22 @@ export const eventToggleAll = toggleAliases.all;
 export const eventToggleAppHost = toggleAliases.appHost;
 export const eventToggleWindow = toggleAliases.window;
 export const eventToggleDocument = toggleAliases.document;
+const visibilitychangeAliases = makeTypedEventAliases<Event>('visibilitychange');
+export const eventVisibilitychange = visibilitychangeAliases.base;
+export const eventVisibilitychangeDelegateLight = visibilitychangeAliases.delegateLight;
+export const eventVisibilitychangeDelegateShadow = visibilitychangeAliases.delegateShadow;
+export const eventVisibilitychangeDelegateAll = visibilitychangeAliases.delegateAll;
+export const eventVisibilitychangeDelegate = visibilitychangeAliases.delegate;
+export const eventVisibilitychangeMutationLight = visibilitychangeAliases.mutationLight;
+export const eventVisibilitychangeMutationShadow = visibilitychangeAliases.mutationShadow;
+export const eventVisibilitychangeMutationAll = visibilitychangeAliases.mutationAll;
+export const eventVisibilitychangeMutation = visibilitychangeAliases.mutation;
+export const eventVisibilitychangeLight = visibilitychangeAliases.light;
+export const eventVisibilitychangeShadow = visibilitychangeAliases.shadow;
+export const eventVisibilitychangeAll = visibilitychangeAliases.all;
+export const eventVisibilitychangeAppHost = visibilitychangeAliases.appHost;
+export const eventVisibilitychangeWindow = visibilitychangeAliases.window;
+export const eventVisibilitychangeDocument = visibilitychangeAliases.document;
 export const getAddEventListenerMetadata = (target: any): AddEventListenerMetadata<Event>[] | undefined => {
   const constructor = typeof target === 'function' ? target : target.constructor;
   return ReflectUtils.findAllMetadata<any[]>(ADD_EVENT_LISTENER_METADATA_KEY, constructor).flat();
@@ -1184,7 +1200,7 @@ import { ElementDefineLifeCycler, MutationObserverSetEntry, OnConnectedResult }
 import { Subject } from '@dooboostore/core';
 import { debounceTime, distinctUntilChanged, throttleTime } from '@dooboostore/core/message/operators';
 import { SwcUtils } from '../utils/Utils';
-import { buildSwcParameterArgs } from './parameter';
+import { buildSwcParameterArgs, buildCommonKindValues } from './parameter';
 
 export interface BoundListenerEntry {
   target: EventTarget;
@@ -1240,16 +1256,12 @@ export class EventListenerLifeCycler implements ElementDefineLifeCycler {
       if (options.stopPropagation) event.stopPropagation();
       if (options.stopImmediatePropagation) event.stopImmediatePropagation();
       if (options.preventDefault) event.preventDefault();
-      const currentHostSet = SwcUtils.getHostSet(inst);
-      const legacyArgs = [event, { currentHostSet, $matchedElement: matchedElement }, { event, ...currentHostSet, $el: target, $root: target }];
-      const currentHelperSet = SwcUtils.getHelperSet(currentWin);
-      const currentHelperHostSet = { ...currentHelperSet, ...currentHostSet, $this: inst };
+      const common = buildCommonKindValues(inst, currentWin);
+      const legacyArgs = [event, { currentHostSet: common.hostSet, $matchedElement: matchedElement }, { event, ...common.hostSet, $el: target, $root: target }];
       const buildArgs = (beforeReturn: any) => buildSwcParameterArgs(inst, meta.propertyKey, {
+        ...common,
         eventObject: event,
         matchedElement,
-        hostSet: currentHostSet,
-        helperHostSet: currentHelperHostSet,
-        helperSet: currentHelperSet,
         eventBeforeReturn: beforeReturn
       }, legacyArgs);
       // before를 먼저 돌려 그 리턴값을 @eventBeforeReturn 으로 주입. before엔 (아직 자기 리턴 전이라
@@ -1394,16 +1406,12 @@ export class EventListenerLifeCycler implements ElementDefineLifeCycler {
               if (m.options.stopPropagation) event.stopPropagation();
               if (m.options.stopImmediatePropagation) event.stopImmediatePropagation();
               if (m.options.preventDefault) event.preventDefault();
-              const hs = SwcUtils.getHostSet(inst);
-              const legacyArgs = [event, { ...hs, $matchedElement: matchedEl }, { event, ...hs, $el: matchedEl, $root: br }];
-              const helperSetForMatch = SwcUtils.getHelperSet(currentWin);
-              const helperHostSetForMatch = { ...helperSetForMatch, ...hs, $this: inst };
+              const common = buildCommonKindValues(inst, currentWin);
+              const legacyArgs = [event, { ...common.hostSet, $matchedElement: matchedEl }, { event, ...common.hostSet, $el: matchedEl, $root: br }];
               const buildArgs = (beforeReturn: any) => buildSwcParameterArgs(inst, m.propertyKey, {
+                ...common,
                 eventObject: event,
                 matchedElement: matchedEl,
-                hostSet: hs,
-                helperHostSet: helperHostSetForMatch,
-                helperSet: helperSetForMatch,
                 eventBeforeReturn: beforeReturn
               }, legacyArgs);
               // before를 먼저 돌려 그 리턴값을 @eventBeforeReturn 으로 주입.

package/src/decorators/applyAttribute.ts

@@ -369,6 +369,7 @@ export function attribute(selectorOrAttributeOrTarget?: AttributeSelector | Attr
 
 /**
  * @removeAttribute - 메서드 실행 시 엘리먼트 속성 제거 (반환값 그대로 통과).
+ * 반환값과 상관없이 지운다. valueKey 를 줬을 때만 그 키 값이 truthy 인지 본다 (@removeNode 와 같은 규칙).
  * 라우트 구독처럼 값을 리턴하면 안 되는 곳에서 @attribute 에 null 을 리턴하는 대신 명시적으로 사용.
  *
  * Usage:
@@ -382,16 +383,20 @@ export function removeAttribute(selector: AttributeSelector, attributeName: stri
     const original = descriptor.value;
     descriptor.value = function (...args: any[]) {
       const res = (original as any).apply(this, args);
-      const doRemove = () => {
+      // 이름에 이미 의도가 있으니 반환값과 상관없이 지운다. valueKey 를 줬을 때만 그 키 값이 truthy 인지 본다.
+      const doRemove = (v: any) => {
+        const vk = options?.valueKey;
+        const go = vk !== undefined ? (v && typeof v === 'object' ? v[vk] : undefined) : true;
+        if (!go) return;
         resolveAttributeTargets(this, selector, options ?? {}).forEach((el) => el.removeAttribute(attributeName));
       };
       if (res instanceof Promise) {
         return res.then((v: any) => {
-          doRemove();
+          doRemove(v);
           return v;
         });
       }
-      doRemove();
+      doRemove(res);
       return res;
     };
     return descriptor;

package/src/decorators/applyClass.ts

@@ -208,11 +208,31 @@ function createClassDecorator(action: ClassAction) {
           return resolvedValue;
         };
 
+        // 클래스 이름을 선언에 적은 add/remove/toggle 은 이름에 이미 의도가 있다 — 반환값과 상관없이 실행.
+        // valueKey 를 줬을 때만 그 키 값을 본다: add/remove 는 truthy 일 때만, toggle 은 true/false 로 켜고 끔.
+        // toggle 은 valueKey 없이 반환값이 없으면 그냥 토글, true/false 를 반환하면 그대로 켜고 끈다.
+        const fixedName = typeof classMap === 'string' && (action === 'add' || action === 'remove' || action === 'toggle') ? classMap : undefined;
+        const applyFixed = (raw: any) => {
+          const vk = finalOptions.valueKey;
+          const v = vk !== undefined ? (raw && typeof raw === 'object' ? raw[vk] : undefined) : action === 'toggle' ? raw : true;
+          if (vk !== undefined && (action === 'toggle' ? v === undefined : !v)) return;
+          const win = (this as any).ownerDocument?.defaultView || window;
+          const hostSet = { ...SwcUtils.getHelperAndHostSet(this as unknown as HTMLElement), $this: this };
+          getTargetElements(selector, this, win, finalOptions.root || 'auto').forEach(el => {
+            if (finalOptions.filter && !finalOptions.filter(el, v, { currentThis: this, helper: hostSet })) return;
+            if (action === 'add') el.classList.add(fixedName!);
+            else if (action === 'remove') el.classList.remove(fixedName!);
+            else if (v === undefined) el.classList.toggle(fixedName!);
+            else el.classList.toggle(fixedName!, !!v);
+          });
+        };
+        const run = (raw: any) => (fixedName ? applyFixed(raw) : handleResult(extractValue(raw)));
+
         if (res instanceof Promise) {
           // 자기 몫(valueKey)만 적용하고 원래 반환값은 그대로 위로 넘긴다 — 위에 쌓인 다른 아웃풋도 자기 키를 찾게
-          return res.then((v: any) => { handleResult(extractValue(v)); return v; });
+          return res.then((v: any) => { run(v); return v; });
         } else {
-          handleResult(extractValue(res));
+          run(res);
           return res;
         }
       };

package/src/decorators/applyNode.ts

@@ -86,6 +86,12 @@ const applyToDom = (currentThis: any, targetEl: HTMLElement, res: Node | string
     targetEl.replaceChildren();
     return [];
   }
+
+  // remove: 대상 자체를 DOM에서 뗀다. $this 처럼 shadow root 로 잡혔으면 그 주인 엘리먼트를 뗀다.
+  if (pos === 'remove') {
+    (targetEl instanceof win.ShadowRoot ? (targetEl as any).host : targetEl).remove();
+    return [];
+  }
   
   const doc = win.document;
   const hostSet = SwcUtils.getHelperAndHostSet(currentThis);
@@ -230,8 +236,20 @@ export function applyNode(selectorOrOptions: ApplyNodeSelector | ApplyNodeOption
         return v;
       };
 
+      // remove / clearChildren: 이름에 이미 의도가 있으니 반환값과 상관없이 실행한다.
+      // valueKey 를 줬을 때만 그 키 값이 truthy 인지 본다 (키가 없거나 falsy 면 안 함).
+      const decide = (raw: any) => {
+        if (options.position === 'remove' || options.position === 'clearChildren') {
+          if (options.valueKey === undefined) return true;
+          return raw && typeof raw === 'object' ? raw[options.valueKey] : undefined;
+        }
+        return extractValue(raw);
+      };
+
       const runApply = (target: any, val: any) => {
         const pos = options.position || 'beforeEnd';
+        // remove / clearChildren: valueKey 로 뽑은 값이 falsy 면 안 한다 (valueKey 없으면 decide 가 항상 true)
+        if ((pos === 'remove' || pos === 'clearChildren') && !val) return;
         // Delegate HTML/node processing to applyToDom which centralizes
         // processing. runApply should not call processHtml itself to avoid
         // duplicate processing.
@@ -253,13 +271,13 @@ export function applyNode(selectorOrOptions: ApplyNodeSelector | ApplyNodeOption
 
       if (res instanceof Promise) {
         return res.then(finalRes => {
-          const extracted = extractValue(finalRes);
+          const extracted = decide(finalRes);
           fallbackNodes.forEach((it: any)=>it.remove());
           if (extracted !== undefined && targetEl) runApply(targetEl, extracted);
           return finalRes;
         });
       } else {
-        const extracted = extractValue(res);
+        const extracted = decide(res);
         if (extracted !== undefined && targetEl) runApply(targetEl, extracted);
         return res;
       }
@@ -299,6 +317,7 @@ export function replaceChildren(selectorOrOptions?: ApplyNodeSelector | Omit<App
 
 /**
  * @clearChildrenNode decorator - clears all children of target element
+ * 반환값과 상관없이 비운다. valueKey 를 줬을 때만 그 키 값이 truthy 일 때 비운다 (@removeNode 와 같은 규칙).
  * 
  * Overloads:
  * - clearChildrenNode(selector, options) - Clear children of specific selector
@@ -323,6 +342,29 @@ export function clearChildrenNode(selectorOrOptions?: ApplyNodeSelector | Omit<A
 // Alias for clearChildrenNode
 export const clearNode = clearChildrenNode;
 
+/**
+ * @removeNode - 메서드가 끝나면 대상 엘리먼트를 DOM에서 제거한다. 반환값은 그대로 통과.
+ * - 이름에 의도가 있으니 반환값과 상관없이 지운다.
+ * - valueKey 를 줬을 때만 그 키 값을 본다: truthy 면 지우고, 키가 없거나 falsy 면 안 지운다.
+ * 선택자에 맞는 첫 번째 엘리먼트를 지운다. 선택자가 없거나 '$this' 면 자기 자신을 지운다.
+ *
+ * - @removeNode('.toast')  /  @removeNode('.toast', { valueKey: 'close' })
+ * - @removeNode({ valueKey: 'done' })  ($this)
+ * - @removeNode  ($this, bare)
+ */
+export function removeNode(selector: ApplyNodeSelector, options?: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function removeNode(options: Omit<ApplyNodeOptions, 'position'>): MethodDecorator;
+export function removeNode(target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor | void;
+export function removeNode(selectorOrOptions?: ApplyNodeSelector | Omit<ApplyNodeOptions, 'position'> | Object, maybeOptions?: Omit<ApplyNodeOptions, 'position'> | string | symbol, descriptor?: PropertyDescriptor): MethodDecorator | PropertyDescriptor | void {
+  if (descriptor !== undefined && (typeof maybeOptions === 'symbol' || typeof maybeOptions === 'string')) {
+    return applyNode({position: 'remove'})(selectorOrOptions as Object, maybeOptions, descriptor);
+  }
+  if (typeof selectorOrOptions === 'string' || typeof selectorOrOptions === 'function') {
+    return applyNode(selectorOrOptions as any, {...maybeOptions as Omit<ApplyNodeOptions, 'position'>, position: 'remove'});
+  }
+  return applyNode({...selectorOrOptions as Omit<ApplyNodeOptions, 'position'>, position: 'remove'});
+}
+
 /**
  * @innerHtmlNode decorator - sets innerHTML of target element
  * 

package/src/decorators/changedAttribute.ts

@@ -86,7 +86,7 @@ export const convertAttributeValue = (val: any, type?: typeof Number | typeof Bo
 import { ElementDefineLifeCycler, HelperHostSet } from '../types';
 import { getAttributeValue, convertValue } from './applyAttribute';
 import { SwcUtils } from '../utils/Utils';
-import { buildSwcParameterArgs } from './parameter';
+import { buildSwcParameterArgs, buildCommonKindValues } from './parameter';
 
 export class ChangedAttributeLifeCycler implements ElementDefineLifeCycler {
   private attrChangeMap: Map<string, ChangedAttributeThisMetadata[]> | null = null;
@@ -134,11 +134,10 @@ export class ChangedAttributeLifeCycler implements ElementDefineLifeCycler {
     void (async () => {
       const helper = SwcUtils.getHelperAndHostSet(inst);
       if (opts.filter && !(await opts.filter(value, { currentThis: inst, helper }))) return;
-      const hostSet = SwcUtils.getHostSet(inst);
-      const helperSet = SwcUtils.getHelperSet(helperHostSet.$w);
+      const common = buildCommonKindValues(inst, helperHostSet.$w);
       const legacyArgs = [value, old, name, helper];
       const buildArgs = (beforeReturn: any) => buildSwcParameterArgs(inst, meta.propertyKey, {
-        hostSet, helperHostSet: helper, helperSet, changedAttributeBeforeReturn: beforeReturn
+        ...common, changedAttributeBeforeReturn: beforeReturn
       }, [...legacyArgs, beforeReturn]);
       let args = buildArgs(undefined);
       if (opts.before) { const br = await opts.before(value, { currentThis: inst, helper }); args = buildArgs(br); }

package/src/decorators/elementDefine.ts

@@ -12,7 +12,7 @@ import {SwcUtils} from '../utils/Utils';
 import {DOM_EVENT_NAMES, HTML_TAG_ENTRIES} from '../config/config';
 import {SituationTypeContainer, SituationTypeContainers} from '@dooboostore/simple-boot/decorators/inject/Inject';
 import {FirstCheckMaker} from '@dooboostore/simple-boot';
-import {buildSwcParameterArgs, getParameterMetadata} from './parameter';
+import {buildSwcParameterArgs, buildDomStorageKindValues, getParameterMetadata} from './parameter';
 import {ElementDefineLifeCycler, HelperHostSet, HostSet, InjectSituationType, IntersectionObserverSet, MutationObserverSet, MutationObserverSetEntry, ObserverScope, OnConnectedResult, ResizeObserverSet, ResizeObserverSetEntry, SwcRootType} from '../types';
 import {ConvertUtils, ElementApply} from '@dooboostore/core-web';
 import {isSSR} from "../elements/SwcAppMixin";
@@ -25,7 +25,7 @@ import {SetIntervalLifeCycler} from "./setInterval";
 import {SetTimeoutLifeCycler} from "./setTimeout";
 import {RequestAnimationFrameLifeCycler} from "./requestAnimationFrame";
 import {EventMediaLifeCycler} from "./eventMedia";
-import {FetchLifeCycler} from "./fetch";
+import {FetchLifeCycler, assertFetchFields} from "./fetch";
 
 // --- Core Interfaces & Types ---
 
@@ -266,11 +266,17 @@ const setupPrototype = (proto: any, win: Window) => {
     const useHostSet = hostSet ?? SwcUtils.getHelperAndHostSet(this);
     const app = useHostSet?.$appHost?.simpleApplication;
 
-    // @hostSet/@helperHostSet/@helperSet(parameter.ts)를 위한 값. lifecycle 메서드는
-    // event/matched 개념이 없으므로 이 세 가지만 채운다.
+    // @hostSet/@helperHostSet/@helperSet/@swcAppRouter(parameter.ts)를 위한 값. lifecycle 메서드는
+    // event/matched 개념이 없으므로 이것들만 채운다.
     const helperSetValue = SwcUtils.getHelperSet(win);
     const helperHostSetValue = {...helperSetValue, ...useHostSet, $this: this};
-    const kindValues = {hostSet: useHostSet, helperHostSet: helperHostSetValue, helperSet: helperSetValue};
+    const kindValues = {
+      hostSet: useHostSet, helperHostSet: helperHostSetValue, helperSet: helperSetValue,
+      swcAppRouter: useHostSet?.$appHost?.router,
+      swcAppSimpleApplication: useHostSet?.$appHost?.simpleApplication,
+      swcAppHost: useHostSet?.$appHost,
+      ...buildDomStorageKindValues(this, win)
+    };
 
     // console.log('---->hh',app, this, methodName);
     if (app) {
@@ -288,12 +294,16 @@ const setupPrototype = (proto: any, win: Window) => {
       // 해석보다 먼저 처리되고(firstCheckMaker), 그 외 파라미터는 기존처럼 @Inject/타입
       // 기반으로 정상 해석된다 — 같은 메서드에서 두 방식을 섞어 써도 된다.
       // swc 파라미터 데코레이터가 붙은 자리는 DI 로 넘기지 않는다. lifecycle 이 못 채우는 kind
-      // (예: @fetchSettled — @fetch 가 나중에 채움)는 null. undefined 를 돌려주면
+      // (예: @fetchPromise — @fetch 가 채움)는 null. undefined 를 돌려주면
       // "처리 안 함"으로 보고 DI 가 파라미터 타입(Object 등)을 resolve 하려다 SimNoSuch 로 죽는다.
       const firstCheckMaker: FirstCheckMaker = ({target, targetKey}, token, idx) => {
         const saves = getParameterMetadata(target, targetKey!);
         const found = saves.find(s => s.index === idx);
-        return found ? ((kindValues as any)[found.kind] ?? null) : undefined;
+        if (!found) return undefined;
+        const value = (kindValues as any)[found.kind];
+        // 키를 받는 kind(@querySelectorParam/@attributeParam/@local·session·cookieParam 등)는
+        // buildSwcParameterArgs와 동일하게 value(key)로 해석한다 — 아니면 리졸버 함수 자체가 주입된다.
+        return (found.key !== undefined && typeof value === 'function' ? value(found.key) : value) ?? null;
       };
 
       return app.simstanceManager.executeBindParameterSim(
@@ -384,6 +394,8 @@ export const elementDefine =
       if (!metadata.window) {
         throw new Error('window is required');
       }
+      // 필드 @fetch 에 다른 데코레이터가 같이 붙었으면 정의 시점에 바로 알린다
+      assertFetchFields(constructor);
 
       let extendsTagName = metadata.extends;
       if (!extendsTagName) {

package/src/decorators/eventMedia.ts

@@ -1,7 +1,7 @@
 import { ReflectUtils } from '@dooboostore/core';
 import { ElementDefineLifeCycler, HelperHostSet } from '../types';
 import { SwcUtils } from '../utils/Utils';
-import { buildSwcParameterArgs } from './parameter';
+import { buildSwcParameterArgs, buildCommonKindValues } from './parameter';
 
 export const EVENT_MEDIA_METADATA_KEY = Symbol.for('simple-web-component:event-media');
 
@@ -70,14 +70,11 @@ export class EventMediaLifeCycler implements ElementDefineLifeCycler {
         try {
           const helper = SwcUtils.getHelperAndHostSet(inst);
           if (meta.filter && !(await meta.filter(e as MediaQueryListEvent, { currentThis: inst, helper }))) return;
-          const hostSet = SwcUtils.getHostSet(inst);
-          const helperSet = SwcUtils.getHelperSet(win);
+          const common = buildCommonKindValues(inst, win);
           const legacyArgs = [e, helperHostSet];
           const buildArgs = (beforeReturn: any) => buildSwcParameterArgs(inst, meta.propertyKey, {
+            ...common,
             eventObject: e,
-            hostSet,
-            helperHostSet: helper,
-            helperSet,
             eventMediaBeforeReturn: beforeReturn
           }, legacyArgs);
           // before를 먼저 돌려 그 리턴값을 @eventMediaBeforeReturn 으로 주입.