トラブルシューティング

タグはあるがオーブが表示されない

カスタム要素が未登録の可能性があります。クライアントコードでブラウザーエントリーをインポートします。


import "@neongate-ai/orbz/browser";

次に登録状況を調べます。


console.log(customElements.get("orb-z"));

React や Next.js ではクライアントで @neongate-ai/orbz/browser をインポートし、<orb-z> を直接描画します。パッケージのソースファイルは参照しません。

サーバーで `HTMLElement` や `customElements` が未定義になる

文書化された入口を使い、ブラウザー専用コードをサーバーで実行しないでください。Orbz の登録には保護がありますが、アプリ側もサーバー描画中に DOM のグローバルを呼べません。

DOM 操作はクライアント起動処理、effect、マウントフックに移します。SSR とハイドレーションを参照してください。

React で TypeScript が `<orb-z>` を認識しない

React と Next.js のガイドのとおり React.JSX.IntrinsicElements にタグを追加します。ラッパーで回避せず、実行時要素は <orb-z> のままにします。

プリセットと独自色が競合する

モードを一つ選びます。preset を使うか、削除して color-* を設定します。併存するとプリセットが優先され、競合属性がログに出ます。

`palette` が効かない

palette は公開の属性やプロパティではありません。preset を使います。


<orb-z preset="magenta"></orb-z>

組み込み外観は Neongate（既定）、periwinkle、magenta、peach、mocha、ivory です。ORBZ_PRESET_NAMES から対応キーを取得します。プリセット名を参照してください。

独自色が表示されない

独自モードに入る前に preset を削除します。


orb.removeAttribute("preset");
orb.setAttribute("color-primary", "#7C3AED");

有効な CSS 色であり、属性が color-primary、color-secondary、color-accent、color-highlight、color-background のいずれかであることも確認します。

`paused="false"` や `elevated="false"` でも有効になる

HTML の真偽値属性なので、文字列にかかわらず存在すれば真です。属性を削除します。


orb.removeAttribute("paused");
orb.removeAttribute("elevated");

または対応するプロパティを使います。


orb.paused = false;
orb.elevated = false;

テンプレート型フレームワークでは、属性をなくす時に null か undefined をバインドします。

アニメーションが動かない

次の順に確認します。

paused を削除するかプロパティを false にします。
reduced-motion を確認します。always は静止表示です。
system なら OS の動きを減らす設定を確認します。
speed が正数か確認します。
要素が接続・登録済みか確認します。

restart() は現在の状態の動きを再構築しますが、一時停止や動きを減らす設定は上書きしません。

状態・速度・プリセットが違う

未対応の実行時値は安全な既定値に正規化されます。

制御	既定値
`state`	`idle`
`speed`	`1`
`preset`	`DEFAULT_ORBZ_PRESET`（Neongate）
`reduced-motion`	`system`
`size`	空の値や無効な数値プロパティは `16rem`

公開された TypeScript の型と定数で、実行前に未対応値を検出します。

Vue が `orb-z` を解決できないと警告する

Vue のテンプレートコンパイラーでカスタム要素として扱うよう設定します。


vue({
  template: {
    compilerOptions: {
      isCustomElement: (tag) => tag === "orb-z",
    },
  },
})

Vue のクライアント入口で @neongate-ai/orbz/browser もインポートします。

Angular が `orb-z` を未知の要素とする

テンプレートを持つ standalone コンポーネントか NgModule に CUSTOM_ELEMENTS_SCHEMA を追加します。


schemas: [CUSTOM_ELEMENTS_SCHEMA]

次に、アプリの起動前にブラウザーエントリーをインポートします。

二つのマイクロフロントエンドが別バージョンを読む

Custom Elements の登録はタグ名ごとに一つです。重複を防ぐため、最初に登録した実装が使われます。各リモートで正確な同一バージョンを揃えるか、シェルに登録を任せます。マイクロフロントエンドの Orbzを参照してください。

Shadow DOM を調査・装飾できない

Shadow root は意図的に閉じています。公開 CSS 変数、パーツ、内部クラスやレイヤー参照には対応しません。文書化された属性を使い、共通の正当な用途を表せない場合は GitHub Issues に具体的な提案を出してください。

まだ解決しない場合

Issue には次を含めます。

Orbz のバージョンと入口
フレームワークとバージョン
ブラウザーと OS
問題を再現する最小限の <orb-z> マークアップ
関連するビルドやコンソールの出力

Orbz の Issue を作成 · npm パッケージを見る