@bstage-sdk/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bemyfriends Inc.
+
+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/dist/index.cjs

@@ -0,0 +1,432 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BstageContext: () => BstageContext,
+  BstageLocaleProvider: () => BstageLocaleProvider,
+  __bstage_registry__: () => __bstage_registry__,
+  createTemplate: () => createTemplate,
+  registerTemplate: () => registerTemplate,
+  useBstageContext: () => useBstageContext,
+  useBstageTranslations: () => useBstageTranslations,
+  useLocale: () => useLocale,
+  useMessages: () => useMessages,
+  useNavigation: () => useNavigation,
+  usePlatformEvent: () => usePlatformEvent,
+  useShadowStyle: () => useShadowStyle,
+  useSlotContext: () => useSlotContext
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/createTemplate.tsx
+var import_react = require("react");
+var __bstage_registry__ = /* @__PURE__ */ new Set();
+function createTemplate(Component, options) {
+  const { name } = options;
+  validateElementName(name);
+  const meta = {
+    name,
+    elementName: name,
+    framework: "react",
+    ...options.slot && { slot: options.slot },
+    ...options.type && { type: options.type }
+  };
+  function TemplateWrapper(props) {
+    return (0, import_react.createElement)(Component, props);
+  }
+  TemplateWrapper.displayName = `BstageTemplate(${name})`;
+  TemplateWrapper.__bstage_meta__ = meta;
+  TemplateWrapper.__bstage_options__ = options;
+  TemplateWrapper.__bstage_inner__ = Component;
+  const wrapper = TemplateWrapper;
+  __bstage_registry__.add(wrapper);
+  return wrapper;
+}
+var ELEMENT_NAME_RE = /^[a-z][a-z0-9-]*-[a-z0-9-]*$/;
+function validateElementName(name) {
+  if (!ELEMENT_NAME_RE.test(name)) {
+    throw new Error(
+      `createTemplate: \uC798\uBABB\uB41C name "${name}". Custom Element \uC2A4\uD399\uC0C1 \uC18C\uBB38\uC790\uB85C \uC2DC\uC791\uD558\uACE0 \uD558\uC774\uD508\uC744 1\uAC1C \uC774\uC0C1 \uD3EC\uD568\uD574\uC57C \uD558\uBA70, \uC18C\uBB38\uC790\xB7\uC22B\uC790\xB7\uD558\uC774\uD508\uB9CC \uC0AC\uC6A9\uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4. \uC608: "bmf-hello"`
+    );
+  }
+}
+
+// src/registerTemplate.ts
+var import_react3 = require("react");
+var import_client = require("react-dom/client");
+var import_core = require("@bstage-sdk/core");
+
+// src/BstageContext.tsx
+var import_react2 = require("react");
+var BstageContext = (0, import_react2.createContext)(null);
+function useBstageContext() {
+  const ctx = (0, import_react2.useContext)(BstageContext);
+  if (!ctx) {
+    throw new Error("[bstage] useBstageContext must be used inside a bstage template");
+  }
+  return ctx;
+}
+
+// src/registerTemplate.ts
+function ReadySignal({ host }) {
+  (0, import_react3.useEffect)(() => {
+    host.dispatchEvent(new CustomEvent("bstage:__ready__", { bubbles: false, composed: false }));
+  }, []);
+  return null;
+}
+var ReactAdapter = class {
+  constructor(options = {}) {
+    this.options = options;
+    this.root = null;
+    this.component = null;
+    this.contextValue = null;
+    this.host = null;
+  }
+  mount(component, container, props, bridge) {
+    this.component = component;
+    this.contextValue = { bridge };
+    this.host = bridge.getHost();
+    if (this.options.styles && container instanceof ShadowRoot) {
+      const style = document.createElement("style");
+      style.textContent = this.options.styles;
+      container.appendChild(style);
+    }
+    this.root = (0, import_client.createRoot)(container);
+    this.render(props);
+  }
+  update(props) {
+    this.render(props);
+  }
+  unmount() {
+    const root = this.root;
+    queueMicrotask(() => root?.unmount());
+    this.root = null;
+    this.component = null;
+    this.contextValue = null;
+    this.host = null;
+  }
+  render(props) {
+    if (!this.root || !this.component || !this.contextValue || !this.host) return;
+    this.root.render(
+      (0, import_react3.createElement)(
+        BstageContext.Provider,
+        { value: this.contextValue },
+        (0, import_react3.createElement)(this.component, props),
+        (0, import_react3.createElement)(ReadySignal, { host: this.host })
+      )
+    );
+  }
+};
+function registerTemplate(template) {
+  const meta = template.__bstage_meta__;
+  const options = template.__bstage_options__;
+  const Component = template.__bstage_inner__;
+  const tagName = meta.elementName;
+  const WebComponent = (0, import_core.createWebComponent)(
+    () => new ReactAdapter({ styles: options.styles }),
+    Component,
+    { ...options, framework: "react" }
+  );
+  if (!customElements.get(tagName)) {
+    customElements.define(tagName, WebComponent);
+  }
+  (0, import_core.announceElementName)(tagName);
+  return WebComponent;
+}
+
+// src/hooks/useNavigation.ts
+var import_react4 = require("react");
+function useNavigation() {
+  const ctx = (0, import_react4.useContext)(BstageContext);
+  const bridge = ctx?.bridge;
+  const navigate = (0, import_react4.useCallback)(
+    (path, params) => {
+      if (bridge) {
+        bridge.emit("navigate", { path, params });
+      } else {
+        const query = params ? "?" + new URLSearchParams(params).toString() : "";
+        window.location.href = path + query;
+      }
+    },
+    [bridge]
+  );
+  const goBack = (0, import_react4.useCallback)(() => {
+    if (bridge) {
+      bridge.emit("go-back", {});
+    } else {
+      window.history.back();
+    }
+  }, [bridge]);
+  const openExternal = (0, import_react4.useCallback)(
+    (url) => {
+      if (bridge) {
+        bridge.emit("open-external", { url });
+      } else {
+        window.open(url, "_blank");
+      }
+    },
+    [bridge]
+  );
+  return { navigate, goBack, openExternal };
+}
+
+// src/hooks/usePlatformEvent.ts
+var import_react5 = require("react");
+function usePlatformEvent(type, handler) {
+  const ctx = (0, import_react5.useContext)(BstageContext);
+  const bridge = ctx?.bridge;
+  const handlerRef = (0, import_react5.useRef)(handler);
+  handlerRef.current = handler;
+  (0, import_react5.useEffect)(() => {
+    if (!bridge) return;
+    return bridge.on(type, ((payload) => {
+      handlerRef.current(payload);
+    }));
+  }, [bridge, type]);
+}
+
+// src/hooks/useSlotContext.ts
+var import_react6 = require("react");
+function useSlotContext() {
+  const [context, setContext] = (0, import_react6.useState)();
+  usePlatformEvent("slot.context", (payload) => {
+    setContext(payload);
+  });
+  return context;
+}
+
+// src/hooks/useShadowStyle.ts
+var import_react7 = require("react");
+function useShadowStyle(css) {
+  const ref = (0, import_react7.useRef)(null);
+  const injected = (0, import_react7.useRef)(false);
+  (0, import_react7.useEffect)(() => {
+    if (injected.current || !ref.current) return;
+    const root = ref.current.getRootNode();
+    if (!(root instanceof ShadowRoot)) return;
+    const hash = hashString(css);
+    if (root.querySelector(`style[data-shadow-style="${hash}"]`)) return;
+    const style = document.createElement("style");
+    style.setAttribute("data-shadow-style", hash);
+    style.textContent = css;
+    root.appendChild(style);
+    injected.current = true;
+  });
+  return ref;
+}
+function hashString(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = Math.imul(31, hash) + str.charCodeAt(i) | 0;
+  }
+  return (hash >>> 0).toString(36);
+}
+
+// src/hooks/useLocale.ts
+var import_react9 = require("react");
+var import_core2 = require("@bstage-sdk/core");
+
+// src/LocaleProvider.tsx
+var import_react8 = require("react");
+var LocaleTargetContext = (0, import_react8.createContext)(null);
+function useLocaleTarget() {
+  const target = (0, import_react8.useContext)(LocaleTargetContext);
+  if (target === null) {
+    throw new Error(
+      "[bstage] \uB85C\uCF00\uC77C \uD6C5(useLocale/useMessages/useBstageTranslations)\uC740 <BstageLocaleProvider> \uC548\uC5D0\uC11C \uD638\uCD9C\uD574\uC57C \uD569\uB2C8\uB2E4."
+    );
+  }
+  return target;
+}
+function BstageLocaleProvider({
+  target = "user",
+  children
+}) {
+  return (0, import_react8.createElement)(LocaleTargetContext.Provider, { value: target }, children);
+}
+
+// src/hooks/useLocale.ts
+function useLocale() {
+  const target = useLocaleTarget();
+  const subscribe = (0, import_react9.useCallback)((onChange) => (0, import_core2.observeLocale)(onChange, target), [target]);
+  const getSnapshot = (0, import_react9.useCallback)(() => (0, import_core2.readLocale)(target), [target]);
+  const current = (0, import_react9.useSyncExternalStore)(subscribe, getSnapshot, () => import_core2.DEFAULT_LANGUAGE);
+  return { current };
+}
+
+// src/hooks/useMessages.ts
+var import_core3 = require("@bstage-sdk/core");
+
+// src/devWarn.ts
+var warned = /* @__PURE__ */ new Set();
+function devWarnOnce(dedupeKey, message) {
+  if (warned.has(dedupeKey)) return;
+  warned.add(dedupeKey);
+  console.warn(`[bstage] ${message}`);
+}
+
+// src/hooks/useMessages.ts
+function interpolate(template, params) {
+  if (!params) return template;
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    const value = params[key];
+    return value === void 0 ? `{{${key}}}` : String(value);
+  });
+}
+function useMessages(messages) {
+  const { current } = useLocale();
+  return (key, params) => {
+    if (process.env.NODE_ENV !== "production" && typeof params === "string") {
+      devWarnOnce(
+        `msg-string-param:${String(key)}`,
+        `useMessages\uC758 t('${String(key)}', ...) 2\uBC88\uC9F8 \uC778\uC790\uB294 \uBCF4\uAC04 \uD30C\uB77C\uBBF8\uD130 \uAC1D\uCCB4\uC785\uB2C8\uB2E4. fallback \uBB38\uC790\uC5F4\uC740 \uBB34\uC2DC\uB429\uB2C8\uB2E4.`
+      );
+    }
+    const dict = messages[current] ?? messages[import_core3.DEFAULT_LANGUAGE] ?? Object.values(messages)[0] ?? {};
+    const template = dict[key] ?? key;
+    return interpolate(template, params);
+  };
+}
+
+// src/hooks/useBstageTranslations.ts
+var import_react10 = require("react");
+var import_core4 = require("@bstage-sdk/core");
+var requiredDepth = /* @__PURE__ */ new Map();
+function useBstageTranslations() {
+  const { current } = useLocale();
+  const target = useLocaleTarget();
+  const depthKey = `${target}|${current}`;
+  const [dicts, setDicts] = (0, import_react10.useState)();
+  const [depth, setDepth] = (0, import_react10.useState)(() => requiredDepth.get(depthKey) ?? 1);
+  const pendingRef = (0, import_react10.useRef)(false);
+  (0, import_react10.useEffect)(() => {
+    setDicts(void 0);
+    setDepth(requiredDepth.get(depthKey) ?? 1);
+    pendingRef.current = false;
+  }, [depthKey]);
+  (0, import_react10.useEffect)(() => {
+    let active = true;
+    const chain = (0, import_core4.resolveTranslationChain)(current).slice(0, depth);
+    Promise.all(chain.map((locale) => (0, import_core4.fetchTranslations)(locale, target).catch(() => ({})))).then((loaded) => {
+      if (!active) return;
+      setDicts(loaded);
+      pendingRef.current = false;
+    }).catch(() => {
+      if (active) setDicts([]);
+    });
+    return () => {
+      active = false;
+    };
+  }, [current, target, depth]);
+  const requestFallback = (0, import_react10.useCallback)(
+    (chainLength) => {
+      if (pendingRef.current) return;
+      pendingRef.current = true;
+      queueMicrotask(
+        () => setDepth((d) => {
+          if (d >= chainLength) return d;
+          const next = d + 1;
+          requiredDepth.set(depthKey, Math.max(requiredDepth.get(depthKey) ?? 1, next));
+          return next;
+        })
+      );
+    },
+    [depthKey]
+  );
+  const resolveRaw = (0, import_react10.useCallback)(
+    (key) => {
+      const resolved = dicts ? (0, import_core4.pickTranslation)(dicts, key) : void 0;
+      if (resolved !== void 0) return resolved;
+      if (dicts) {
+        const chain = (0, import_core4.resolveTranslationChain)(current);
+        if (dicts.length < chain.length) {
+          requestFallback(chain.length);
+        } else if (process.env.NODE_ENV !== "production") {
+          devWarnOnce(
+            `t-missing-key:${String(key)}`,
+            `'${String(key)}'\uB294 \uD50C\uB7AB\uD3FC \uBC88\uC5ED \uC0AC\uC804\uC5D0 \uC5C6\uB294 \uD0A4\uC785\uB2C8\uB2E4(\uC624\uD0C8\uC790\uC774\uAC70\uB098 useMessages \uB300\uC0C1\uC77C \uC218 \uC788\uC74C). \uD0A4 \uBB38\uC790\uC5F4\uC774 \uADF8\uB300\uB85C \uB80C\uB354\uB429\uB2C8\uB2E4.`
+          );
+        }
+      }
+      return void 0;
+    },
+    [dicts, current, requestFallback]
+  );
+  const t = (0, import_react10.useCallback)(
+    (key, params) => {
+      if (process.env.NODE_ENV !== "production") {
+        if (typeof params === "string") {
+          devWarnOnce(
+            `t-string-param:${String(key)}`,
+            `t('${String(key)}', ...)\uC758 2\uBC88\uC9F8 \uC778\uC790\uB294 \uBCF4\uAC04 \uD30C\uB77C\uBBF8\uD130 \uAC1D\uCCB4\uC785\uB2C8\uB2E4. fallback \uBB38\uC790\uC5F4\uC740 \uBB34\uC2DC\uB418\uACE0 \uD50C\uB7AB\uD3FC \uC0AC\uC804 \uAC12\uC774 \uB80C\uB354\uB429\uB2C8\uB2E4 \u2014 \uD15C\uD50C\uB9BF \uC790\uCCB4 \uBB38\uAD6C\uB294 useMessages\uB97C \uC4F0\uC138\uC694.`
+          );
+        }
+      }
+      const raw = resolveRaw(key);
+      if (process.env.NODE_ENV !== "production" && raw !== void 0 && /<\d+>/.test(raw)) {
+        devWarnOnce(
+          `t-rich-text:${String(key)}`,
+          `'${String(key)}'\uB294 \uB9AC\uCE58\uD14D\uC2A4\uD2B8(<0>\u2026</0>) \uBB38\uAD6C\uC785\uB2C8\uB2E4. t()\uB294 \uBB38\uC790\uC5F4\uC744 \uBC18\uD658\uD558\uBBC0\uB85C \uD0DC\uADF8\uAC00 \uAE00\uC790\uB85C \uBCF4\uC785\uB2C8\uB2E4 \u2014 tNode('${String(key)}', { tags: { 0: <a href="\u2026" /> } })\uB97C \uC4F0\uC138\uC694.`
+        );
+      }
+      return (0, import_core4.interpolateTranslation)(raw ?? key, params);
+    },
+    [resolveRaw]
+  );
+  const tNode = (0, import_react10.useCallback)(
+    (key, options) => {
+      const raw = resolveRaw(key) ?? key;
+      const tokens = (0, import_core4.parseRichText)(raw, options?.params);
+      return tokens.map((token, i) => {
+        if (token.type === "text") return token.value;
+        const element = options?.tags?.[token.index];
+        if (!element) {
+          if (process.env.NODE_ENV !== "production") {
+            devWarnOnce(
+              `tnode-missing-tag:${String(key)}:${token.index}`,
+              `'${String(key)}'\uC758 <${token.index}> \uD0DC\uADF8\uC5D0 \uB300\uC751\uD558\uB294 \uC5D8\uB9AC\uBA3C\uD2B8\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4 \u2014 tags: { ${token.index}: <a href="\u2026" /> }\uB97C \uB118\uAE30\uC138\uC694. \uC9C0\uAE08\uC740 \uB0B4\uC6A9\uB9CC \uB80C\uB354\uB429\uB2C8\uB2E4.`
+            );
+          }
+          return token.value;
+        }
+        return (0, import_react10.cloneElement)(element, { key: i }, token.value);
+      });
+    },
+    [resolveRaw]
+  );
+  return { current, t, tNode, ready: dicts !== void 0 };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BstageContext,
+  BstageLocaleProvider,
+  __bstage_registry__,
+  createTemplate,
+  registerTemplate,
+  useBstageContext,
+  useBstageTranslations,
+  useLocale,
+  useMessages,
+  useNavigation,
+  usePlatformEvent,
+  useShadowStyle,
+  useSlotContext
+});