ksk-design-system 1.42.2 → 1.44.0

package/NATIVE_RECIPES.md

@@ -184,3 +184,49 @@ Web では `CompactFilePicker` / `ImageAttachmentPicker` が hidden file input
   </BottomSheetFrame>
 </Sheet>
 ```
+
+## Caption / attribution text
+
+出典・著作権表示など、控えめな注釈は `Text` の `variant="caption-strong"` を使います（11px・font-semibold 相当）。`text-[11px] font-semibold leading-4 text-hint` のようなマジックナンバーをローカルに書きません。色は未指定なら自動で hint 相当（`text.low-emphasis`）になります。
+
+```tsx
+import { Text } from "ksk-design-system/native/ui"
+
+{citationOf(question) && (
+  <Text variant="caption-strong" style={{ marginTop: 12 }}>
+    {citationOf(question)}
+  </Text>
+)}
+```
+
+通常の注釈（強調不要）には既存の `variant="caption"`（11px・通常ウェイト）を使います。
+
+## Masked / teaser progress bars
+
+未課金ユーザー向けのティザー表示など、実データを見せたくない進捗バーは `Progress` の `masked` を使います。`masked=true` の間はバー幅・色ともに `value`/`autoColor` を無視し固定表示になるため、幅から実データを逆算されません。
+
+```tsx
+import { Progress, Text } from "ksk-design-system/native/ui"
+
+<Text variant="body.sm">{masked ? "🔒 ??%" : `${accuracy}%（${correct}/${answered}）`}</Text>
+<Progress value={accuracy} masked={masked} />
+```
+
+Web 版 `Progress`（`ksk-design-system` の `Progress`）にも同じ `masked` prop があります。
+
+## Static document viewer (privacy policy / terms)
+
+プライバシーポリシー・利用規約などの静的文書画面は `DocumentScreen` + `Prose` を使います。見出し・本文・最終更新日・戻るヘッダのタイポとスペーシングは DS 側で一元管理されるため、consumer は `sections` の原稿データだけ持てば済みます。
+
+```tsx
+import { DocumentScreen, Prose } from "ksk-design-system/native/ui"
+
+const POLICY_SECTIONS = [
+  { title: "個人情報の取得", body: ["本アプリは以下の情報を取得します。", "…"] },
+  { title: "個人情報の利用目的", body: ["取得した情報は次の目的で利用します。"] },
+]
+
+<DocumentScreen title="プライバシーポリシー" lastUpdated="2026年7月7日" onBack={() => navigation.goBack()}>
+  <Prose sections={POLICY_SECTIONS} />
+</DocumentScreen>
+```

package/contracts/components.json

@@ -1,15 +1,15 @@
 {
   "meta": {
     "name": "KSK Design System — Component Contracts",
-    "version": "1.42.2",
+    "version": "1.44.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "counts": {
-      "ui": 58,
-      "patterns": 52,
+      "ui": 61,
+      "patterns": 54,
       "commerce": 12,
       "admin": 8,
       "shells": 3,
-      "total": 133
+      "total": 138
     }
   },
   "ui": [
@@ -72,6 +72,51 @@
         "Must use <Input> not <input>"
       ]
     },
+    {
+      "name": "CommitInput",
+      "path": "src/components/ui/commit-input.tsx",
+      "description": "IME(日本語変換)を壊さない Input の確定時コミット版。value + onCommit contract。store 直結の inline 編集で、変換中に onChange が store へ書き込んで変換が中断される問題を防ぐ。視覚は Input に完全委譲。共通ロジックは useCommitDraft フック。",
+      "variants": [],
+      "accessibility": [
+        "Must pair with <Label>"
+      ],
+      "rules": [
+        "value/onCommit contract。value は controlled、確定タイミングでのみ onCommit が呼ばれる",
+        "変換(composition)中は commit せず draft のみ更新。compositionEnd / 非変換入力時に commit",
+        "外部 value 変更は非変換中のみ draft へ反映(realtime 同期対応)",
+        "store 直結 controlled input で IME が壊れる場合に Input の代わりに使う"
+      ]
+    },
+    {
+      "name": "CommitTextarea",
+      "path": "src/components/ui/commit-textarea.tsx",
+      "description": "IME(日本語変換)を壊さない Textarea の確定時コミット版。value + onCommit contract。CommitInput と同じ流儀で compositionEnd / 非変換入力時のみ commit。視覚は Textarea に完全委譲。共通ロジックは useCommitDraft フック。",
+      "variants": [],
+      "accessibility": [
+        "Must pair with <Label>"
+      ],
+      "rules": [
+        "value/onCommit contract。value は controlled、確定タイミングでのみ onCommit が呼ばれる",
+        "変換(composition)中は commit せず draft のみ更新。compositionEnd / 非変換入力時に commit",
+        "外部 value 変更は非変換中のみ draft へ反映(realtime 同期対応)",
+        "store 直結 controlled textarea で IME が壊れる場合に Textarea の代わりに使う"
+      ]
+    },
+    {
+      "name": "CommitAutoGrowTextarea",
+      "path": "src/components/ui/commit-auto-grow-textarea.tsx",
+      "description": "IME(日本語変換)を壊さない AutoGrowTextarea の確定時コミット版。value + onCommit contract。AutoGrowTextarea の onChange は (value:string) を渡すため変換中判定は内部 composingRef のみで行う。視覚・auto-grow は AutoGrowTextarea に完全委譲。共通ロジックは useCommitDraft フック。",
+      "variants": [],
+      "accessibility": [
+        "Must pair with <Label>"
+      ],
+      "rules": [
+        "value/onCommit contract。value は controlled、確定タイミングでのみ onCommit が呼ばれる",
+        "変換(composition)中は commit せず draft のみ更新。compositionEnd / 非変換入力時に commit",
+        "外部 value 変更は非変換中のみ draft へ反映(realtime 同期対応)",
+        "store 直結 controlled AutoGrowTextarea で IME が壊れる場合に代わりに使う"
+      ]
+    },
     {
       "name": "Calendar",
       "path": "src/components/ui/calendar.tsx",
@@ -249,7 +294,7 @@
     {
       "name": "Sheet",
       "path": "src/components/ui/sheet.tsx",
-      "description": "サイドパネル・ボトムシート。フィルター・メニュー・補助入力に使用。モーダルより軽いコンテキストに。snapPoints でスナップ式、swipeToClose で下スワイプ閉じを有効化。autoFocus / restoreFocusOnClose / closeOnEsc / bodyScrollLock でフォーカス・スクロール挙動を制御可能。",
+      "description": "サイドパネル・ボトムシート。フィルター・メニュー・補助入力に使用。モーダルより軽いコンテキストに。snapPoints でスナップ式、swipeToClose で下スワイプ閉じを有効化。autoFocus / restoreFocusOnClose / closeOnEsc / bodyScrollLock でフォーカス・スクロール挙動を制御可能。 多段（シートの上にシート）では open 順に overlay/content の z-index が自動繰り上げされ、zIndex / overlayClassName で上書き可能。",
       "subcomponents": [
         "SheetTrigger",
         "SheetContent",
@@ -383,10 +428,13 @@
     {
       "name": "Skeleton",
       "path": "src/components/ui/skeleton.tsx",
-      "description": "読み込み中プレースホルダ。width/height/rounded shorthand 対応。",
+      "description": "読み込み中プレースホルダ。width/height/rounded shorthand 対応。SkeletonText は lines 指定の複数行テキストプレースホルダ（最終行短縮）。",
       "rules": [
         "数値は px、文字列は CSS 値として渡る",
         "rounded: none/sm/md/lg/xl/2xl/full プリセット"
+      ],
+      "subcomponents": [
+        "SkeletonText"
       ]
     },
     {
@@ -922,6 +970,24 @@
         "Color + icon + text. Include retry action."
       ]
     },
+    {
+      "name": "Prose",
+      "path": "src/components/patterns/prose.tsx",
+      "description": "静的文書（プライバシーポリシー・利用規約等）の本文レンダラー。sections: {title, body: string[]}[] を受けて見出し+段落を統一タイポで描画する。native の Prose.tsx と props 形が一致。",
+      "rules": [
+        "見出しは typo-heading-md、段落は typo-body-md",
+        "DocumentPage の子として使う想定だが単体でも利用可"
+      ]
+    },
+    {
+      "name": "DocumentPage",
+      "path": "src/components/patterns/document-page.tsx",
+      "description": "プライバシーポリシー・利用規約などの静的文書ページ。タイトル・最終更新日・本文（Prose）を固定スペーシングで組む。native の DocumentScreen.tsx に対応（web は単体ページのため命名を DocumentPage とし、戻るナビは呼び出し側のシェルに委ねる）。",
+      "rules": [
+        "本文は max-w-2xl に収めて読みやすい行長にする",
+        "戻るナビは持たない。必要なら呼び出し側のレイアウトシェルで用意する"
+      ]
+    },
     {
       "name": "SectionHeader",
       "path": "src/components/patterns/section-header.tsx",
@@ -1575,9 +1641,10 @@
     {
       "name": "BottomSheetFrame",
       "path": "src/components/patterns/bottom-sheet-frame.tsx",
-      "description": "SheetContent の responsive outer frame preset。mobile-full / mobile-form / desktop-floating を宣言し、DetailSheetScaffold と KeyboardAwareSheetFooter を内側で合成する。",
+      "description": "SheetContent の responsive outer frame preset。mobile-full / mobile-page（iOS ページシート風・上端 2rem ギャップ）/ mobile-form / desktop-floating を宣言し、DetailSheetScaffold と KeyboardAwareSheetFooter を内側で合成する。",
       "variants": [
         "mobile-full",
+        "mobile-page",
         "mobile-form",
         "desktop-floating"
       ],