melta-app 0.6.0 → 0.7.0

package/src/safe-area/index.ts

@@ -11,9 +11,10 @@
  *   import { enableSafeAreaContext } from "melta-app/safe-area";
  *   enableSafeAreaContext();
  *
- * これで Screen の SafeArea が useSafeAreaInsets() + View の adapter に切り替わる。
- * Provider の context 値を render 中に同期参照して padding を付けるため、native
- * SafeAreaView の layout/state 更新を待たず、初回 render から inset が反映される。
+ * これで Screen / ActionSheet / BottomSheet の SafeArea が useSafeAreaInsets() + View の
+ * adapter に切り替わる。Provider の context 値を render 中に同期参照して padding を付けるため、
+ * native SafeAreaView の layout/state 更新を待たず、初回 render から inset が反映される。
+ * Android でも効く（RN core の SafeAreaView は Android では完全 no-op）。
  *
  * ⚠️ 前提: アプリの root に SafeAreaProvider が必要（無いと useSafeAreaInsets が throw
  * する）。初回 render から正しい inset を使うには Provider に initialMetrics も渡す。
@@ -35,13 +36,21 @@ import {
   setSafeAreaView,
   type SafeAreaViewLike,
   type SafeAreaViewLikeProps,
-} from "../components/safe-area-registry";
+} from "../components/safe-area-registry.js";
 
 const ALL_EDGES = ["top", "right", "bottom", "left"] as const satisfies readonly Edge[];
 
 /** enableSafeAreaContext() の設定。edges 省略時は従来相当の全 edge。 */
 export interface EnableSafeAreaContextOptions {
-  /** Screen に適用する edge。tab bar 等が担当する edge は除外する。 */
+  /**
+   * **Screen の既定 edge**（`edges` prop を渡さなかった Screen に適用される）。
+   * tab bar 等が担当する edge は除外する。
+   *
+   * ⚠️ 0.5.x までは「アプリ全体で 1 個のグローバル」だったが、edge は消費者ごとに
+   * 決まるべきものなので既定値の意味に変わった。ActionSheet / BottomSheet は画面下端に
+   * 出る都合上、ここの指定に関わらず自前の edge（bottom + 左右）を使う。
+   * 画面ごとに変えたい場合は `<Screen edges={["top"]} />` のように Screen 側で指定する。
+   */
   edges?: readonly Edge[];
 }
 
@@ -100,7 +109,12 @@ function createContextSafeAreaView(selectedEdges: readonly Edge[]): SafeAreaView
   return ContextSafeAreaView;
 }
 
-/** Screen の SafeArea を context 同期参照の View adapter に切り替える。 */
+/**
+ * melta の SafeArea を context 同期参照の View adapter に切り替える。
+ *
+ * registry には**ファクトリ**を渡す（消費者ごとに edges が違うため）。同じ edges 集合には
+ * 同じコンポーネント参照が返るよう memo するのは registry 側の責務。
+ */
 export function enableSafeAreaContext(options: EnableSafeAreaContextOptions = {}): void {
-  setSafeAreaView(createContextSafeAreaView(options.edges ?? ALL_EDGES));
+  setSafeAreaView(createContextSafeAreaView, options.edges ?? ALL_EDGES);
 }

package/src/theme/ThemeProvider.tsx

@@ -14,9 +14,9 @@
 
 import { createContext, useContext, useMemo, type ReactNode } from "react";
 import { useColorScheme } from "react-native";
-import { nativeTheme } from "./native-theme";
-import { defineTheme, isDev, resolveMode, type ResolvedCapabilities, type ResolvedNativeTheme, type ThemeModeViolation } from "./define-theme";
-import type { NativeTheme, SemanticColors, ThemeMode } from "./types";
+import { nativeTheme } from "./native-theme.js";
+import { defineTheme, isDev, resolveMode, type ResolvedCapabilities, type ResolvedNativeTheme, type ThemeModeViolation } from "./define-theme.js";
+import type { NativeTheme, SemanticColors, ThemeMode } from "./types.js";
 
 export type { ThemeMode };
 
@@ -41,8 +41,11 @@ const ThemeContext = createContext<ThemeContextValue | null>(null);
 
 /**
  * 既定 theme。melta-contracts 由来の codegen 結果を注入経路と同じ形に通す（自分でも dogfood する）。
- * 副作用として dev では `nativeTheme` の入れ子オブジェクト（トークン群）も freeze される
- * — 生成物のトークンを実行時に書き換える経路は元々無いので、意図した副作用として許容する。
+ *
+ * dev で freeze されるのは **`defineTheme()` の戻り値**（= `useTheme().theme` として配られる
+ * 解決済み theme）で、入れ子のトークン群まで再帰的に凍る。公開 export の `nativeTheme` 自体は
+ * `defineTheme` 内の `cloneTokenTree` で参照が切り離されているので**凍らない**
+ * （0.4.3 で意図的にこう変えた: 凍らせると `{ ...nativeTheme }` からの正当な派生が dev で壊れるため）。
  */
 const DEFAULT_THEME: ResolvedNativeTheme = defineTheme({ ...nativeTheme, id: "melta" });
 

package/src/theme/define-theme.ts

@@ -32,7 +32,7 @@ import type {
   StatusColors,
   ThemeColor,
   ThemeMode,
-} from "./types";
+} from "./types.js";
 
 // ---------------------------------------------------------------------------
 // dev 判定
@@ -214,13 +214,19 @@ const FONT_WEIGHT_KEYS = keysOf<Record<FontWeightKey, true>>({
  * プロパティにも true を返すので、それで判定すると「持っていない mode に置いた番人の getter」を
  * 値として数えてしまい、解決後の theme に対して常に light / dark 両方を返す（0.4.0 の不具合）。
  * 入力（素のデータプロパティ）と解決後（番人つき）のどちらに対しても正しく答える必要がある。
+ *
+ * @experimental 公開しているが安定 API ではない。挙動・シグネチャは予告なく変わりうる。
  */
 export function declaredModes(semantic: Partial<Record<ThemeMode, SemanticColors>>): ThemeMode[] {
   const withValue = new Set(Object.keys(semantic));
   return MODES.filter((mode) => withValue.has(mode));
 }
 
-/** colorScheme capability を `color.semantic` のキー集合から導出する。 */
+/**
+ * colorScheme capability を `color.semantic` のキー集合から導出する。
+ *
+ * @experimental 公開しているが安定 API ではない。挙動・シグネチャは予告なく変わりうる。
+ */
 export function deriveColorScheme(
   semantic: Partial<Record<ThemeMode, SemanticColors>>,
 ): ColorSchemeCapability {
@@ -239,6 +245,8 @@ export function deriveColorScheme(
  * 未知の値は**黙って light-dark 扱いにしない**。TypeScript を使わない消費者や、将来
  * capability の値が増えたときに、誤った値が「両対応の theme」として通ってしまうと、
  * 持っていない mode で描画されて初めて壊れる（＝原因から遠い場所で落ちる）。
+ *
+ * @experimental 公開しているが安定 API ではない。挙動・シグネチャは予告なく変わりうる。
  */
 export function supportedModes(colorScheme: ColorSchemeCapability): ThemeMode[] {
   switch (colorScheme) {
@@ -268,6 +276,8 @@ export function supportedModes(colorScheme: ColorSchemeCapability): ThemeMode[]
  * - **`forcedMode` との不一致は報告する**。宣言同士の矛盾＝呼び出し側の間違いなので violation を返す。
  *   ただし throw はしない（clamp して描き続ける）。厳格に落としたいテストや compiler が
  *   violation を error に昇格させる側の責務にする。
+ *
+ * @experimental 公開しているが安定 API ではない。挙動・シグネチャ・violation の内容は予告なく変わりうる。
  */
 export function resolveMode(
   colorScheme: ColorSchemeCapability,
@@ -504,6 +514,9 @@ function deepFreeze(value: unknown): void {
  *
  * dev では validateTheme を1回通し、問題があれば throw する（構造が壊れた theme は
  * 後段で必ず事故になるので早く落とす）。production では検査ごと省く。
+ *
+ * dev では**戻り値だけ**が入れ子まで再帰 freeze される。入力オブジェクトと公開 export の
+ * `nativeTheme` は `cloneTokenTree` で参照を切ってあるので凍らない（0.4.3 で意図的にこうした）。
  */
 export function defineTheme(options: ThemeOptions): ResolvedNativeTheme {
   if (isDev) {

package/src/theme/index.ts

@@ -4,16 +4,22 @@
  * 消費者ブランドの theme を注入する口は define-theme.ts（`defineTheme`）。
  */
 
-export * from "./types";
-export { nativeTheme } from "./native-theme";
-export { ThemeProvider, useTheme } from "./ThemeProvider";
-export type { ThemeContextValue, ThemeMode } from "./ThemeProvider";
-export { defineTheme } from "./define-theme";
+export * from "./types.js";
+export { nativeTheme } from "./native-theme.js";
+export { ThemeProvider, useTheme } from "./ThemeProvider.js";
+export type { ThemeContextValue, ThemeMode } from "./ThemeProvider.js";
+export { defineTheme } from "./define-theme.js";
 export {
   DEFAULT_MIN_LINE_HEIGHT_RATIO,
   minLineHeightFor,
   clampLineHeight,
-} from "./line-height";
+} from "./line-height.js";
+/**
+ * letterSpacingRatio（em 相当の比率）を適用先の fontSize から letterSpacing(pt) に解決する helper。
+ * 実体は pure module（./letter-spacing）。resolver 側は index を経由せず直接 import する
+ * （index は ThemeProvider = react-native を引くため）。
+ */
+export { resolveLetterSpacing } from "./letter-spacing.js";
 /**
  * 以下は theme の解決規則を外から検証・再利用するためのヘルパ。
  * **@experimental — 安定 API ではない。** 挙動・シグネチャ・メッセージは予告なく変わりうる。
@@ -25,20 +31,11 @@ export {
   supportedModes,
   deriveColorScheme,
   declaredModes,
-} from "./define-theme";
+} from "./define-theme.js";
 export type {
   ColorSchemeCapability,
   ResolvedCapabilities,
   ResolvedNativeTheme,
   ThemeModeViolation,
   ThemeOptions,
-} from "./define-theme";
-
-/**
- * letterSpacingRatio（em 相当の比率）を、適用先の fontSize から RN の letterSpacing(pt) に解決する。
- * 例: resolveLetterSpacing(18, theme.typography.letterSpacingRatio.body)
- * theme.typography.letterSpacingRatio.* をそのまま style.letterSpacing に入れる誤用を避けるための helper。
- */
-export function resolveLetterSpacing(fontSize: number, ratio: number): number {
-  return fontSize * ratio;
-}
+} from "./define-theme.js";

package/src/theme/letter-spacing.ts

@@ -0,0 +1,17 @@
+/**
+ * letter-spacing — letterSpacingRatio（em 相当の比率）→ RN の letterSpacing(pt) の解決。
+ *
+ * theme/index.ts は ThemeProvider（react-native 依存）を re-export するので、pure style resolver や
+ * node テストから index 経由でこの helper を引くと RN を巻き込んでしまう。そのため実体は
+ * line-height.ts と同じく **pure module** に置き、index.ts は re-export だけする
+ * （公開 API の位置と名前は不変）。以前は index.ts に実体があり、pure 側は同じ式を直書きしていた。
+ */
+
+/**
+ * letterSpacingRatio（em 相当の比率）を、適用先の fontSize から RN の letterSpacing(pt) に解決する。
+ * 例: resolveLetterSpacing(18, theme.typography.letterSpacingRatio.body)
+ * theme.typography.letterSpacingRatio.* をそのまま style.letterSpacing に入れる誤用を避けるための helper。
+ */
+export function resolveLetterSpacing(fontSize: number, ratio: number): number {
+  return fontSize * ratio;
+}

package/src/theme/line-height.ts

@@ -23,6 +23,15 @@
  */
 export const DEFAULT_MIN_LINE_HEIGHT_RATIO = 1.45;
 
+/**
+ * theme が宣言する最小行間比を取り出す（未宣言なら既定へ倒す）。
+ * `theme.typography.minLineHeightRatio ?? DEFAULT_MIN_LINE_HEIGHT_RATIO` を各 resolver が
+ * 写経すると、既定へ倒す規則が一箇所ずつ腐る（片方だけ ?? を落とす等）ためここに集約する。
+ */
+export function minRatioOf(theme: { typography: { minLineHeightRatio?: number } }): number {
+  return theme.typography.minLineHeightRatio ?? DEFAULT_MIN_LINE_HEIGHT_RATIO;
+}
+
 /**
  * fontSize に対する安全な最小 lineHeight（px）。
  * **切り上げ**であることが要点: 四捨五入だと 32 × 1.45 = 46.4 → 46 で下限を割る。

package/src/theme/native-theme.ts

@@ -2,7 +2,7 @@
 // 生成元: scripts/generate-native-theme.ts（入力 melta-contracts tokens.json）
 // tokens version: 1.0.0
 
-import type { NativeTheme } from "./types";
+import type { NativeTheme } from "./types.js";
 
 export const nativeTheme: NativeTheme = {
   "color": {
@@ -38,7 +38,7 @@ export const nativeTheme: NativeTheme = {
       },
       "dark": {
         "bg-page": "#0f172a",
-        "bg-page-alt": "#1e293b",
+        "bg-page-alt": "#334155",
         "bg-surface": "#1e293b",
         "bg-surface-alt": "#0f172a",
         "text-heading": "#f1f5f9",

package/src/theme/types.ts

@@ -77,7 +77,7 @@ export interface ThemeTypography {
   /**
    * 初期は system default（未指定 = OS デフォルトフォント）。RN の fontFamily は string 一本で
    * web の fallback 配列のようには効かず、Inter 等を焼くと expo-font でのロード必須になり実機で崩れる。
-   * Inter / JetBrains Mono の embed は expo-font 導入後に generator へ font マップを渡す Phase 2。
+   * Inter / JetBrains Mono の embed は expo-font を導入し、generator へ font マップを渡す形になる（未着手）。
    * それまでは sans/mono とも未指定（= OS の sans / monospace）にする。
    */
   fontFamily: { sans?: string; mono?: string };