melta-app 0.5.0 → 0.5.1

package/README.md

@@ -7,7 +7,9 @@
 - **Showcase / Live Catalog**: https://app.melta.tsubotax.com （Live Catalog は実 RN コンポーネントの web export。HTML 再現デモではない）
 - **Web 版 showcase**: https://melta.tsubotax.com
 
-D2I アプリが最初の adopter / dogfood。最初の実需は「活動記録をサマリーカードに焼いて外部シェア」機能。
+**現在の adopter は 1 つ**（非公開プロジェクトのモバイルアプリ）。dogfood はそこで回している。
+D2I は当初想定していた最初の adopter だが、mobile 側はまだ melta-app を導入していない
+（D2I の web 側が使っているのは melta-ui）。
 
 ## Install
 
@@ -74,10 +76,33 @@ const theme = defineTheme({
 
 > 現状 `color.primary` / `text-accent` / `elevation` / status の light 値は、単一 dark のテーマでも**必須のまま**。省略できるのは `color.semantic` の mode だけで、他の軸を「持たない」と宣言する仕組みは後続で入れる。
 
+### 押せるカード（`variant="action"` / `"link"`）
+
+**カード面そのものは操作要素ではない。** 面を押せるのはポインタ利用者向けの近道で、
+キーボードとスクリーンリーダーからの到達手段は**カード内の操作要素**が担う。
+そのため `primaryAction` が必須になっている。
+
+```tsx
+<Card
+  variant="action"
+  onPress={openLog}
+  primaryAction={<Button label="製作ログを見る" onPress={openLog} />}
+>
+  <Text variant="lg" role="heading">工房 #12</Text>
+</Card>
+```
+
+- `primaryAction` は面の `onPress` と**同じ操作**を指す（別の遷移先にしない）
+- ラベルは `primaryAction` 側に付ける。カードは名前を持たない（`role="article"` の領域）
+- カード内に操作要素が複数あってよい。`primaryAction` に置くのは**主アクション**（面を押したときの遷移先と一致するもの）
+- 面に `accessibilityRole="button"` は付かない。`Button` を内包しても DOM が壊れない
+
+0.4.x からの移行は [CHANGELOG](./CHANGELOG.md#050--2026-07-29) を参照。
+
 ## 設計の核
 
 - **契約は共有、実装は各最適**: tokens / 禁止ルール / component 契約は `melta-contracts`（JSON）が SSOT。melta-app に token は持たない（二重化を物理防止）。
-- **公開 DS の純度を守る**: 汎用 UI プリミティブだけを置く。D2I 固有 UI（アプリ固有の画面・機能）は **D2I 側**に置き、ここには混ぜない。
+- **公開 DS の純度を守る**: 汎用 UI プリミティブだけを置く。アプリ固有の UI（特定サービスの画面・機能・語彙）は**各アプリ側**に置き、ここには混ぜない。
 - **依存最小**: 初期は RN `StyleSheet` 固定（nativewind / unistyles 等の runtime styling lib を入れない）。Storybook RN も使わず自前カタログ。
 
 ## AI-Ready

package/lib/module/components/Card.js

@@ -33,14 +33,27 @@
  * - media variant は overflow:hidden で角丸に画像をクリップし、body だけにパディング（contract と整合）。
  */
 
+import { useEffect } from "react";
 import { Pressable, View } from "react-native";
 import { useTheme } from "../theme/index.js";
 import { CONTRACTS } from "../contracts/contract-types.js";
+import { isDev } from "../theme/define-theme.js";
 import { CARD_INTERACTIVE, resolveCardShape, resolveCardBodyStyle } from "./card.styles.js";
+import { validateCardProps } from "./card.validate.js";
+
+/**
+ * 同じ問題を毎レンダー報告しないためのラッチ。
+ *
+ * **報告は effect の中で行う**（render 中ではない）。render 中だと、React が破棄する
+ * speculative render や StrictMode の二重 render でもラッチが消費され、実際に commit された
+ * 違反が報告されなくなりうる。検査の中身は card.validate.ts の純関数側でテストする。
+ */
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+const reported = new Set();
 
 // action/link（インタラクティブ）は onPress と primaryAction が必須、
 // basic/media はどちらも取らない（§4 DU 精神）。
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+
 export function Card({
   variant = "basic",
   header,
@@ -57,6 +70,18 @@ export function Card({
     mode
   } = useTheme();
   const interactive = CARD_INTERACTIVE[variant] && onPress != null;
+  useEffect(() => {
+    if (!isDev) return;
+    for (const problem of validateCardProps({
+      variant,
+      onPress,
+      primaryAction
+    })) {
+      if (reported.has(problem)) continue;
+      reported.add(problem);
+      console.error(`melta: ${problem}`);
+    }
+  }, [variant, onPress, primaryAction]);
   const isMedia = variant === "media";
   const inner = /*#__PURE__*/_jsxs(_Fragment, {
     children: [media != null && /*#__PURE__*/_jsx(View, {

package/lib/module/components/Card.js.map

@@ -1 +1 @@
-{"version":3,"names":["Pressable","View","useTheme","CONTRACTS","CARD_INTERACTIVE","resolveCardShape","resolveCardBodyStyle","jsx","_jsx","jsxs","_jsxs","Fragment","_Fragment","Card","variant","header","footer","media","onPress","primaryAction","style","testID","children","theme","mode","interactive","isMedia","inner","content","borderRadius","radius","lg","overflow","role","accessible","pressed","__contract","card"],"sourceRoot":"../../../src","sources":["components/Card.tsx"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA,SAASA,SAAS,EAAEC,IAAI,QAAwC,cAAc;AAC9E,SAASC,QAAQ,QAAQ,mBAAU;AACnC,SAASC,SAAS,QAAQ,gCAA6B;AACvD,SAASC,gBAAgB,EAAEC,gBAAgB,EAAEC,oBAAoB,QAAQ,kBAAe;;AAYxF;AACA;AAAA,SAAAC,GAAA,IAAAC,IAAA,EAAAC,IAAA,IAAAC,KAAA,EAAAC,QAAA,IAAAC,SAAA;AAgBA,OAAO,SAASC,IAAIA,CAAC;EACnBC,OAAO,GAAG,OAAO;EACjBC,MAAM;EACNC,MAAM;EACNC,KAAK;EACLC,OAAO;EACPC,aAAa;EACbC,KAAK;EACLC,MAAM;EACNC;AACS,CAAC,EAAE;EACZ,MAAM;IAAEC,KAAK;IAAEC;EAAK,CAAC,GAAGtB,QAAQ,CAAC,CAAC;EAClC,MAAMuB,WAAW,GAAGrB,gBAAgB,CAACU,OAAO,CAAC,IAAII,OAAO,IAAI,IAAI;EAChE,MAAMQ,OAAO,GAAGZ,OAAO,KAAK,OAAO;EAEnC,MAAMa,KAAK,gBACTjB,KAAA,CAAAE,SAAA;IAAAU,QAAA,GACGL,KAAK,IAAI,IAAI,iBAAIT,IAAA,CAACP,IAAI;MAAAqB,QAAA,EAAEL;IAAK,CAAO,CAAC,eACtCP,KAAA,CAACT,IAAI;MAACmB,KAAK,EAAEd,oBAAoB,CAACiB,KAAK,EAAET,OAAO,CAAE;MAAAQ,QAAA,GAC/CP,MAAM,EACNO,QAAQ,EACRN,MAAM,EACNG,aAAa;IAAA,CACV,CAAC;EAAA,CACP,CACH;;EAED;EACA;EACA,MAAMS,OAAO,GAAGF,OAAO,gBACrBlB,IAAA,CAACP,IAAI;IAACmB,KAAK,EAAE;MAAES,YAAY,EAAEN,KAAK,CAACO,MAAM,CAACC,EAAE;MAAEC,QAAQ,EAAE;IAAS,CAAE;IAAAV,QAAA,EAAEK;EAAK,CAAO,CAAC,GAElFA,KACD;EAED,IAAI,CAACF,WAAW,EAAE;IAChB,oBACEjB,IAAA,CAACP,IAAI;MAACgC,IAAI,EAAC,SAAS;MAACZ,MAAM,EAAEA,MAAO;MAACD,KAAK,EAAE,CAACf,gBAAgB,CAACkB,KAAK,EAAEC,IAAI,EAAEV,OAAO,CAAC,EAAEM,KAAK,CAAE;MAAAE,QAAA,EACzFM;IAAO,CACJ,CAAC;EAEX;;EAEA;EACA,oBACEpB,IAAA,CAACR,SAAS;IACRiC,IAAI,EAAC,SAAS;IACdf,OAAO,EAAEA;IACT;IACA;IACA;IAAA;IACAgB,UAAU,EAAE,KAAM;IAClBb,MAAM,EAAEA,MAAO;IACfD,KAAK,EAAEA,CAAC;MAAEe;IAAQ,CAAC,KAAK,CAAC9B,gBAAgB,CAACkB,KAAK,EAAEC,IAAI,EAAEV,OAAO,EAAEqB,OAAO,CAAC,EAAEf,KAAK,CAAE;IAAAE,QAAA,EAEhFM;EAAO,CACC,CAAC;AAEhB;;AAEA;AACAf,IAAI,CAACuB,UAAU,GAAGjC,SAAS,CAACkC,IAAI","ignoreList":[]}
+{"version":3,"names":["useEffect","Pressable","View","useTheme","CONTRACTS","isDev","CARD_INTERACTIVE","resolveCardShape","resolveCardBodyStyle","validateCardProps","jsx","_jsx","jsxs","_jsxs","Fragment","_Fragment","reported","Set","Card","variant","header","footer","media","onPress","primaryAction","style","testID","children","theme","mode","interactive","problem","has","add","console","error","isMedia","inner","content","borderRadius","radius","lg","overflow","role","accessible","pressed","__contract","card"],"sourceRoot":"../../../src","sources":["components/Card.tsx"],"mappings":"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","ignoreList":[]}

package/lib/module/components/card.validate.js

@@ -0,0 +1,67 @@
+"use strict";
+
+/**
+ * card.validate — Card の props が contract 2.1.0 を満たしているかの検査（純関数）。
+ *
+ * **なぜ実行時に検査するか**: props の型は TypeScript を使う利用者にしか効かない。
+ * JavaScript から使われたとき、contract の要求が静かに破られるのを防ぐ。
+ *
+ * react-native を import しない純粋モジュールにして、node テスト（tsx --test）から
+ * 直接網羅できるようにしている。Card 側は結果を dev で1回だけ報告するだけ
+ * （警告のラッチに依存せずに検査内容そのものをテストできる形にするため）。
+ */
+
+import { isValidElement } from "react";
+import { CARD_INTERACTIVE } from "./card.styles.js";
+/**
+ * 問題の一覧を返す（空配列 ＝ 問題なし）。
+ *
+ * 検出できるのは「欠落」と「明らかに型が違う」ところまで。
+ * `primaryAction` が**本当に操作可能か**、面と**同じ遷移先か**は任意の ReactElement からは
+ * 判定できない（そこは契約の文と README の説明が担う）。
+ */
+export function validateCardProps({
+  variant,
+  onPress,
+  primaryAction
+}) {
+  // 未知の variant は CARD_INTERACTIVE で undefined になり、以降の分岐が
+  // 「非インタラクティブ」に倒れて静かに通ってしまう。型を持たない利用者の typo
+  //（variant="acton" 等）が押せないカードとして出荷されるので、最初に弾く。
+  //
+  // ⚠️ 文字列型の確認を hasOwnProperty より**先**に置くこと。プロパティキーは
+  // ToPropertyKey で文字列化されるため、
+  //   - `new String("action")` や `{ toString: () => "action" }` が正規 variant として通る
+  //   - `Object.create(null)` は文字列化できず **TypeError で検査自体が落ちる**
+  //     （dev の防御が防御にならない）
+  // いずれも実測で再現済み（Codex レビュー3周目）。
+  if (typeof variant !== "string") {
+    return [`Card の variant は文字列で渡す（受け取ったのは ${variant === null ? "null" : typeof variant}）。`];
+  }
+  if (!Object.prototype.hasOwnProperty.call(CARD_INTERACTIVE, variant)) {
+    return [`Card の variant="${String(variant)}" は存在しない（` + `${Object.keys(CARD_INTERACTIVE).join(" / ")} のいずれか）。`];
+  }
+  if (!CARD_INTERACTIVE[variant]) {
+    const problems = [];
+    if (onPress != null) {
+      problems.push(`Card variant="${variant}" は onPress を取らない（押せるのは action / link）。`);
+    }
+    if (primaryAction != null) {
+      problems.push(`Card variant="${variant}" は primaryAction を取らない（押せるのは action / link）。`);
+    }
+    return problems;
+  }
+  const problems = [];
+  if (onPress == null) {
+    problems.push(`Card variant="${variant}" は onPress が要る。渡さないと押せない見た目のまま非対話になる。`);
+  } else if (typeof onPress !== "function") {
+    problems.push(`Card variant="${variant}" の onPress が関数でない（${typeof onPress}）。`);
+  }
+  if (primaryAction == null) {
+    problems.push(`Card variant="${variant}" は primaryAction が要る（contract 2.1.0）。` + "カード面は操作要素ではないので、これが無いとキーボード / スクリーンリーダーから" + "カードのアクションに到達できない。面の onPress と同じ操作を指す Button 等を渡すこと。");
+  } else if (! /*#__PURE__*/isValidElement(primaryAction)) {
+    problems.push(`Card variant="${variant}" の primaryAction が React 要素でない（${typeof primaryAction}）。` + "文字列や真偽値では操作要素にならない。");
+  }
+  return problems;
+}
+//# sourceMappingURL=card.validate.js.map

package/lib/module/components/card.validate.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["isValidElement","CARD_INTERACTIVE","validateCardProps","variant","onPress","primaryAction","Object","prototype","hasOwnProperty","call","String","keys","join","problems","push"],"sourceRoot":"../../../src","sources":["components/card.validate.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,cAAc,QAAQ,OAAO;AAEtC,SAASC,gBAAgB,QAAQ,kBAAe;AAQhD;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,iBAAiBA,CAAC;EAChCC,OAAO;EACPC,OAAO;EACPC;AACsB,CAAC,EAAY;EACnC;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,IAAI,OAAOF,OAAO,KAAK,QAAQ,EAAE;IAC/B,OAAO,CACL,kCAAkCA,OAAO,KAAK,IAAI,GAAG,MAAM,GAAG,OAAOA,OAAO,IAAI,CACjF;EACH;EACA,IAAI,CAACG,MAAM,CAACC,SAAS,CAACC,cAAc,CAACC,IAAI,CAACR,gBAAgB,EAAEE,OAAO,CAAC,EAAE;IACpE,OAAO,CACL,mBAAmBO,MAAM,CAACP,OAAO,CAAC,WAAW,GAC3C,GAAGG,MAAM,CAACK,IAAI,CAACV,gBAAgB,CAAC,CAACW,IAAI,CAAC,KAAK,CAAC,UAAU,CACzD;EACH;EAEA,IAAI,CAACX,gBAAgB,CAACE,OAAO,CAAC,EAAE;IAC9B,MAAMU,QAAkB,GAAG,EAAE;IAC7B,IAAIT,OAAO,IAAI,IAAI,EAAE;MACnBS,QAAQ,CAACC,IAAI,CAAC,iBAAiBX,OAAO,yCAAyC,CAAC;IAClF;IACA,IAAIE,aAAa,IAAI,IAAI,EAAE;MACzBQ,QAAQ,CAACC,IAAI,CAAC,iBAAiBX,OAAO,+CAA+C,CAAC;IACxF;IACA,OAAOU,QAAQ;EACjB;EAEA,MAAMA,QAAkB,GAAG,EAAE;EAE7B,IAAIT,OAAO,IAAI,IAAI,EAAE;IACnBS,QAAQ,CAACC,IAAI,CACX,iBAAiBX,OAAO,wCAC1B,CAAC;EACH,CAAC,MAAM,IAAI,OAAOC,OAAO,KAAK,UAAU,EAAE;IACxCS,QAAQ,CAACC,IAAI,CAAC,iBAAiBX,OAAO,sBAAsB,OAAOC,OAAO,IAAI,CAAC;EACjF;EAEA,IAAIC,aAAa,IAAI,IAAI,EAAE;IACzBQ,QAAQ,CAACC,IAAI,CACX,iBAAiBX,OAAO,wCAAwC,GAC9D,2CAA2C,GAC3C,qDACJ,CAAC;EACH,CAAC,MAAM,IAAI,eAACH,cAAc,CAACK,aAAa,CAAC,EAAE;IACzCQ,QAAQ,CAACC,IAAI,CACX,iBAAiBX,OAAO,mCAAmC,OAAOE,aAAa,IAAI,GACjF,qBACJ,CAAC;EACH;EAEA,OAAOQ,QAAQ;AACjB","ignoreList":[]}

package/lib/typescript/src/components/Card.d.ts

@@ -30,7 +30,7 @@
  *   呼び出し側（例: D2I）は用途に応じて slot に Image+Metric を compose する。
  * - media variant は overflow:hidden で角丸に画像をクリップし、body だけにパディング（contract と整合）。
  */
-import type { ReactElement, ReactNode } from "react";
+import { type ReactElement, type ReactNode } from "react";
 import { type StyleProp, type ViewStyle } from "react-native";
 interface CardBase {
     header?: ReactNode;

package/lib/typescript/src/components/Card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Card.d.ts","sourceRoot":"","sources":["../../../../src/components/Card.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACrD,OAAO,EAAmB,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAK/E,UAAU,QAAQ;IAChB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY;IACZ,QAAQ,EAAE,SAAS,CAAC;CACrB;AAID,KAAK,SAAS,GAAG,QAAQ,GACvB,CACI;IAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,KAAK,CAAC;IAAC,aAAa,CAAC,EAAE,KAAK,CAAA;CAAE,GACvE;IACE,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB;;;;OAIG;IACH,aAAa,EAAE,YAAY,CAAC;CAC7B,CACJ,CAAC;AAEJ,wBAAgB,IAAI,CAAC,EACnB,OAAiB,EACjB,MAAM,EACN,MAAM,EACN,KAAK,EACL,OAAO,EACP,aAAa,EACb,KAAK,EACL,MAAM,EACN,QAAQ,GACT,EAAE,SAAS,2CAgDX;yBA1De,IAAI"}
+{"version":3,"file":"Card.d.ts","sourceRoot":"","sources":["../../../../src/components/Card.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAa,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACrE,OAAO,EAAmB,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAgB/E,UAAU,QAAQ;IAChB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY;IACZ,QAAQ,EAAE,SAAS,CAAC;CACrB;AAID,KAAK,SAAS,GAAG,QAAQ,GACvB,CACI;IAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,KAAK,CAAC;IAAC,aAAa,CAAC,EAAE,KAAK,CAAA;CAAE,GACvE;IACE,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB;;;;OAIG;IACH,aAAa,EAAE,YAAY,CAAC;CAC7B,CACJ,CAAC;AAEJ,wBAAgB,IAAI,CAAC,EACnB,OAAiB,EACjB,MAAM,EACN,MAAM,EACN,KAAK,EACL,OAAO,EACP,aAAa,EACb,KAAK,EACL,MAAM,EACN,QAAQ,GACT,EAAE,SAAS,2CAyDX;yBAnEe,IAAI"}

package/lib/typescript/src/components/card.validate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * card.validate — Card の props が contract 2.1.0 を満たしているかの検査（純関数）。
+ *
+ * **なぜ実行時に検査するか**: props の型は TypeScript を使う利用者にしか効かない。
+ * JavaScript から使われたとき、contract の要求が静かに破られるのを防ぐ。
+ *
+ * react-native を import しない純粋モジュールにして、node テスト（tsx --test）から
+ * 直接網羅できるようにしている。Card 側は結果を dev で1回だけ報告するだけ
+ * （警告のラッチに依存せずに検査内容そのものをテストできる形にするため）。
+ */
+import type { CardVariant } from "./card.styles";
+export interface CardPropsForValidation {
+    variant: CardVariant;
+    onPress?: unknown;
+    primaryAction?: unknown;
+}
+/**
+ * 問題の一覧を返す（空配列 ＝ 問題なし）。
+ *
+ * 検出できるのは「欠落」と「明らかに型が違う」ところまで。
+ * `primaryAction` が**本当に操作可能か**、面と**同じ遷移先か**は任意の ReactElement からは
+ * 判定できない（そこは契約の文と README の説明が担う）。
+ */
+export declare function validateCardProps({ variant, onPress, primaryAction, }: CardPropsForValidation): string[];
+//# sourceMappingURL=card.validate.d.ts.map

package/lib/typescript/src/components/card.validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.validate.d.ts","sourceRoot":"","sources":["../../../../src/components/card.validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,OAAO,EACP,OAAO,EACP,aAAa,GACd,EAAE,sBAAsB,GAAG,MAAM,EAAE,CA0DnC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "melta-app",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "melta for APP — melta デザインシステムの React Native UI kit。melta-contracts（デザイン契約）を single source of truth に RN 実装でその契約を満たす。アプリ本体ではなくライブラリ。",
   "license": "MIT",
   "homepage": "https://app.melta.tsubotax.com",

package/src/components/Card.tsx

@@ -31,11 +31,22 @@
  * - media variant は overflow:hidden で角丸に画像をクリップし、body だけにパディング（contract と整合）。
  */
 
-import type { ReactElement, ReactNode } from "react";
+import { useEffect, type ReactElement, type ReactNode } from "react";
 import { Pressable, View, type StyleProp, type ViewStyle } from "react-native";
 import { useTheme } from "../theme";
 import { CONTRACTS } from "../contracts/contract-types";
+import { isDev } from "../theme/define-theme";
 import { CARD_INTERACTIVE, resolveCardShape, resolveCardBodyStyle } from "./card.styles";
+import { validateCardProps } from "./card.validate";
+
+/**
+ * 同じ問題を毎レンダー報告しないためのラッチ。
+ *
+ * **報告は effect の中で行う**（render 中ではない）。render 中だと、React が破棄する
+ * speculative render や StrictMode の二重 render でもラッチが消費され、実際に commit された
+ * 違反が報告されなくなりうる。検査の中身は card.validate.ts の純関数側でテストする。
+ */
+const reported = new Set<string>();
 
 interface CardBase {
   header?: ReactNode;
@@ -77,6 +88,15 @@ export function Card({
 }: CardProps) {
   const { theme, mode } = useTheme();
   const interactive = CARD_INTERACTIVE[variant] && onPress != null;
+
+  useEffect(() => {
+    if (!isDev) return;
+    for (const problem of validateCardProps({ variant, onPress, primaryAction })) {
+      if (reported.has(problem)) continue;
+      reported.add(problem);
+      console.error(`melta: ${problem}`);
+    }
+  }, [variant, onPress, primaryAction]);
   const isMedia = variant === "media";
 
   const inner = (

package/src/components/card.validate.ts

@@ -0,0 +1,91 @@
+/**
+ * card.validate — Card の props が contract 2.1.0 を満たしているかの検査（純関数）。
+ *
+ * **なぜ実行時に検査するか**: props の型は TypeScript を使う利用者にしか効かない。
+ * JavaScript から使われたとき、contract の要求が静かに破られるのを防ぐ。
+ *
+ * react-native を import しない純粋モジュールにして、node テスト（tsx --test）から
+ * 直接網羅できるようにしている。Card 側は結果を dev で1回だけ報告するだけ
+ * （警告のラッチに依存せずに検査内容そのものをテストできる形にするため）。
+ */
+
+import { isValidElement } from "react";
+import type { CardVariant } from "./card.styles";
+import { CARD_INTERACTIVE } from "./card.styles";
+
+export interface CardPropsForValidation {
+  variant: CardVariant;
+  onPress?: unknown;
+  primaryAction?: unknown;
+}
+
+/**
+ * 問題の一覧を返す（空配列 ＝ 問題なし）。
+ *
+ * 検出できるのは「欠落」と「明らかに型が違う」ところまで。
+ * `primaryAction` が**本当に操作可能か**、面と**同じ遷移先か**は任意の ReactElement からは
+ * 判定できない（そこは契約の文と README の説明が担う）。
+ */
+export function validateCardProps({
+  variant,
+  onPress,
+  primaryAction,
+}: CardPropsForValidation): string[] {
+  // 未知の variant は CARD_INTERACTIVE で undefined になり、以降の分岐が
+  // 「非インタラクティブ」に倒れて静かに通ってしまう。型を持たない利用者の typo
+  //（variant="acton" 等）が押せないカードとして出荷されるので、最初に弾く。
+  //
+  // ⚠️ 文字列型の確認を hasOwnProperty より**先**に置くこと。プロパティキーは
+  // ToPropertyKey で文字列化されるため、
+  //   - `new String("action")` や `{ toString: () => "action" }` が正規 variant として通る
+  //   - `Object.create(null)` は文字列化できず **TypeError で検査自体が落ちる**
+  //     （dev の防御が防御にならない）
+  // いずれも実測で再現済み（Codex レビュー3周目）。
+  if (typeof variant !== "string") {
+    return [
+      `Card の variant は文字列で渡す（受け取ったのは ${variant === null ? "null" : typeof variant}）。`,
+    ];
+  }
+  if (!Object.prototype.hasOwnProperty.call(CARD_INTERACTIVE, variant)) {
+    return [
+      `Card の variant="${String(variant)}" は存在しない（` +
+        `${Object.keys(CARD_INTERACTIVE).join(" / ")} のいずれか）。`,
+    ];
+  }
+
+  if (!CARD_INTERACTIVE[variant]) {
+    const problems: string[] = [];
+    if (onPress != null) {
+      problems.push(`Card variant="${variant}" は onPress を取らない（押せるのは action / link）。`);
+    }
+    if (primaryAction != null) {
+      problems.push(`Card variant="${variant}" は primaryAction を取らない（押せるのは action / link）。`);
+    }
+    return problems;
+  }
+
+  const problems: string[] = [];
+
+  if (onPress == null) {
+    problems.push(
+      `Card variant="${variant}" は onPress が要る。渡さないと押せない見た目のまま非対話になる。`,
+    );
+  } else if (typeof onPress !== "function") {
+    problems.push(`Card variant="${variant}" の onPress が関数でない（${typeof onPress}）。`);
+  }
+
+  if (primaryAction == null) {
+    problems.push(
+      `Card variant="${variant}" は primaryAction が要る（contract 2.1.0）。` +
+        "カード面は操作要素ではないので、これが無いとキーボード / スクリーンリーダーから" +
+        "カードのアクションに到達できない。面の onPress と同じ操作を指す Button 等を渡すこと。",
+    );
+  } else if (!isValidElement(primaryAction)) {
+    problems.push(
+      `Card variant="${variant}" の primaryAction が React 要素でない（${typeof primaryAction}）。` +
+        "文字列や真偽値では操作要素にならない。",
+    );
+  }
+
+  return problems;
+}