
# スタイルと状態

Material のコンポーネントは、状態 (ホバー、押下、フォーカス、無効など) ごとに見た目を持ちます。独自のウィジェットも同じものを持てます。`styles.<name>` の下に見た目を書き、各プロパティについて一つの値か、状態ごとの値を書きます。`ThemeStates` がマウス、フォーカス、タップに従い、正しい値をウィジェットに渡します。

```yaml
spring:
  flutter:
    theme:
      styles:
        neon-chip:
          padding: [12, 6]
          radius: $shape.small
          border:
            default: $colors.outline
            hovered: $colors.primary
            selected: $colors.primary
          fill:
            default: transparent
            selected: { color: $colors.primary, alpha: 12% }
          text:
            default: $colors.on-surface-variant
            hovered: $colors.primary
            disabled: { color: $colors.on-surface, alpha: 38% }
          transition: 120ms ease-out
```

## プロパティ

| プロパティ | 型 | 値 | デフォルト | 働き |
|---|---|---|---|---|
| `styles.<name>` | マップ | 任意の名前 | なし | 一つのスタイル。名前はどの綴りでも読まれる: `neon-chip`、`neonChip`、`neon_chip` は同じ |
| `styles.<name>.<property>` | 値、または状態のマップ | 以下の値の種類 | なし | スタイルの一つのプロパティ。どのプロパティ名でも使える。何を読むかはウィジェットが決める |
| `styles.<name>.<property>.<state>` | 値 | `default`、`hovered`、`focused`、`pressed`、`dragged`、`selected`、`scrolled-under`、`disabled`、`error` | なし | その状態でのプロパティの値 |
| `styles.<name>.transition` | テキスト | `<duration> [<curve>]` | アニメーションなし | 状態が変わったときに値が変わるまでの時間と、そのカーブ |

### 値の種類

値は、[トークン](tokens-and-references.md#値の型の決まり方) と同じルールで、見た目によって型が決まります。

| 種類 | 書き方 | Dart では (`StyleValues`) |
|---|---|---|
| 色 | `#FF40A0`、`deepPurple`、`$colors.primary`、`{ color: $colors.primary, alpha: 12% }` | `values.color('fill')` |
| 数値 | `14`、`1.5` | `values.number('radius')` |
| 余白 | YAML のリスト `[12, 6]`、または `12, 6` | `values.insets('padding')` |
| 期間 | `250ms`、`1.5s`、`2m`、`1h`、`0.5d` | `values.duration('delay')` |
| テキスト | それ以外すべて | `values.text('label')` |

余白は `[all]`、`[horizontal, vertical]`、または `[left, top, right, bottom]` です。三つ、または五つ以上の数値のリストはエラーです。余白を読む場所では数値を使え、すべての辺で同じ値を意味します。

マップであるプロパティは状態だけを持たなければなりません。別のキーを持つマップは起動を止め、状態を列挙します。

### 一つの値、または状態ごとの値

```yaml
spring:
  flutter:
    theme:
      styles:
        field:
          radius: 8                       # すべての状態で同じ
          border:                         # 状態ごとの値
            default: $colors.outline
            focused: $colors.primary
            error: $colors.error
```

- 状態を持つプロパティには `default` が必要です。他のどの状態も当てはまらないときの値です。
- プロパティのすべての状態は同じ種類を持ちます。余白の隣の数値は余白に広げられます。色と数値を混ぜるとエラーです。
- 一つの状態だけについて書いたプロパティは、`default` を持つ限りエラーではありません。

### トランジション

`transition: <duration> [<curve>]` は、状態の間の変化をアニメーションさせます。長さは単位付きの数値 (`120ms`、`0.2s`、`1h`) で、単なるミリ秒の数値でもかまいません。カーブは任意の [名前付きのカーブまたは四つの数値](motion-and-animations.md#カーブ) です。カーブがなければ変化は線形です。`transition` がなければ値は即座に変わります。

```yaml
spring:
  flutter:
    theme:
      styles:
        tag:
          fill: { default: transparent, hovered: '#33FFFFFF' }
          transition: $motion.durations.fast ease-out
```

色、数値、余白、期間は、状態の間で滑らかに混ざります。テキストはトランジションの中間で切り替わります。行き過ぎるカーブ (`ease-out-back`、`elastic-out`) でも、パディングが負になることはありません。

## 状態

| 状態 | ウィジェットがその状態になる時 |
|---|---|
| `default` | 他のどれも当てはまらない、または他のものがこのプロパティの値を持たない |
| `hovered` | マウスのポインターがその上にある |
| `focused` | キーボードのフォーカスを持つ |
| `pressed` | 主マウスボタンまたは指がその上で押されている |
| `dragged` | ドラッグされている |
| `selected` | 選択されている (`selected` 引数) |
| `scrolled-under` | コンテンツがその下にスクロールしている |
| `disabled` | 使えない (`onPressed` が `null`) |
| `error` | エラー状態にある (`error` 引数) |

ウィジェットは同時に複数の状態にありえます。各プロパティについて、**値を持つ最も強い状態が優先されます**。強いものから:

1. `disabled`
2. `error`
3. `pressed`
4. `dragged`
5. `hovered`
6. `focused`
7. `selected`
8. `scrolled-under`
9. `default`

そのため、ホバーされている選択済みのチップは、`hovered` の値があればそれを、なければ `selected` の値を、それもなければ `default` を表示します。各プロパティは独立に決まります。無効なウィジェットで `disabled` の値を持たないプロパティは、値を持つ次の状態に移ります。

`ThemeStates` は `hovered`、`focused`、`pressed`、`disabled`、`selected`、`error` を設定します。`dragged` と `scrolled-under` は決して設定しません。それらは、独自の状態の集合で `StateStyle.resolve` を呼ぶコードのためのものです。

## `ThemeStates`

`ThemeStates` は処理を行うウィジェットです。

```dart
ThemeStates(
  style: context.theme.styles.neonChip,
  selected: selected,
  onPressed: onPressed,          // null: チップは無効
  builder: (context, s) => Container(
    padding: s.padding,           // EdgeInsets
    decoration: BoxDecoration(
      color: s.fill,              // Color
      borderRadius: BorderRadius.circular(s.radius),
      border: Border.all(color: s.border),
    ),
    child: Text(label, style: TextStyle(color: s.text)),
  ),
)
```

| 引数 | 型 | デフォルト | 働き |
|---|---|---|---|
| `style` | `ThemeStyle` | 必須 | スタイル: `context.theme.styles.<name>` (生成される) または `StateStyle` |
| `builder` | 関数 | 必須 | 現在の状態の値から子を組み立てる |
| `selected` | bool | `false` | ウィジェットが選択されているかどうか |
| `error` | bool | `false` | ウィジェットがエラー状態にあるかどうか |
| `onPressed` | コールバック | なし | タップ、クリック、Enter、Space で呼ばれる。`null` はウィジェットを無効にする |
| `focusNode` | `FocusNode` | 独自のもの | 使うフォーカスノード |
| `autofocus` | bool | `false` | 最初に表示されたときにフォーカスを取る |
| `mouseCursor` | `MouseCursor` | クリック (無効なときは基本) | ウィジェットの上のカーソル |
| `showFocusAlways` | bool | `false` | キーボードだけでなく、どの方法でフォーカスが来ても (タップやクリックでも) `focused` を表示する。ユーザーがタップしたときに枠が光らなければならないテキスト入力で有効にする。ボタンは Flutter と同じく無効のままにする |

マウス、フォーカス、押下に従い、Enter と Space を扱い、カーソルを設定し、`transition` にわたって値を混ぜます。デバイスが動きを減らすよう求めている場合 (`MediaQuery.disableAnimations`)、値は即座に変わります。

### 生成されるクラス

ジェネレーターがあれば、`styles.<name>` はクラス `AppStyle<Name>` に、その値はクラス `AppStyle<Name>Values` になります。そのため、`text` や `button` という名前のスタイルが Flutter の `TextStyle` や `ButtonStyle` を隠すことはありません。値のクラスは、プロパティごとに型付きのゲッター (`Color fill`、`double radius`、`EdgeInsets padding`、`Duration delay`、`String label`) を持ちます。プロパティは、すべてのテーマとすべての状態で一つの種類を持たなければなりません。そうでなければビルドは失敗し、両方の場所を示します。

```dart
context.theme.styles.neonChip;     // AppStyleNeonChip、ThemeStyle<AppStyleNeonChipValues>
```

ジェネレーターがなければ、スタイルを名前で読みます。

```dart
final style = SpringTheme.of(context).styles['neonchip']!;   // StateStyle
final values = style.resolve({WidgetState.hovered});
values.color('fill');
```

## コンポーネントの状態ごとの値

Material のアプリのコンポーネントのテーマ (`spring_boot_starter_flutter_material` が読む) は、Flutter が状態ごとに扱うもの (ボタンの塗り、アウトラインのボタンの辺、チェックボックスの塗り) について、同じ状態と同じ順序で、同じ状態のマップを受け取ります。その書き方と、どのプロパティが状態を受け取るかは、[コンポーネントのテーマ](../../spring-boot-starter-flutter-material/components/index.md#状態ごとの値)にあります。

## Markdown とコード: `styles.code`

`MarkdownView` (と、ルートの Markdown を表示するナビゲーションの `RouteContentView`) は、その見た目をテーマから得ます。見出しは `headline-*` と `title-*` から、テキストは `body-large` から、リンクは `colors.primary` から得ます。インラインとフェンス付きブロックのコードは、`code` テキストスタイル (`typography.code`) とスタイル `styles.code` の色を使います。

```yaml
spring:
  flutter:
    theme:
      typography:
        code: { font-family: JetBrains Mono, size: 13 }
      styles:
        code:
          background: $colors.surface-container-low
          text: $colors.on-surface
          keyword: '#C678DD'     # final、class、true
          string: '#98C379'      # 'text'、"text"
          comment: '#5C6370'     # // と #
          number: '#D19A66'      # 42、1.5
          key: '#E06C75'         # YAML と .properties のキー
          annotation: '#61AFEF'  # @Service
          variable: '#E5C07B'    # $colors.primary、${PORT}、&anchor
          type: '#56B6C2'        # String、Basket、int
          punctuation: '#ABB2BF' # { } [ ] , : -
```

| プロパティ | デフォルト | 色付けするもの |
|---|---|---|
| `background` | `$colors.surface-container-highest` | ブロックの塗りとインラインコードの背景 |
| `text` | `code` テキストスタイルの色 | 以下に挙げないものすべて |
| `keyword` | `$colors.primary` | キーワード、`true` / `false` / `null` |
| `string` | `$colors.tertiary` | 文字列、引用符のない YAML と `.properties` の値 (`ease-out`) |
| `comment` | `$colors.outline` | コメント |
| `number` | `$colors.secondary` | 数値。単位付きのもの (`120ms`、`1.5s`、`35%`) も |
| `key` | `$colors.primary` | YAML、`.properties`、JSON のキー。シェルコマンドのオプション (`--port`) |
| `annotation` | `$colors.secondary` | アノテーション、YAML のタグ (`!include`) |
| `variable` | `$colors.on-tertiary-container` | 参照とプレースホルダー: `$colors.primary`、`${PORT}`、シェルの `$HOME`、YAML のアンカーとエイリアス (`&base`、`*base`) |
| `type` | `$colors.on-secondary-container` | Dart の型: `String`、`Basket`、`int` |
| `punctuation` | `$colors.on-surface-variant` | 括弧、波括弧、カンマ、コロン、リストのダッシュ |
| `inline-text` | `code` テキストスタイルの色 | インラインコード (`` `@Bean()` ``) |
| `inline-background` | `background` | インラインコードの背景 |
| `header` | `background` | タイトルを持つブロックのヘッダー |
| `title` | `$colors.on-surface-variant` | ブロックのタイトルとそのコピーボタン |

ブロック自体はさらに四つのプロパティを取ります。

| プロパティ | デフォルト | 意味 |
|---|---|---|
| `padding` | `12` | ブロックの内側の余白: `16`、`[16, 12]` |
| `radius` | `6` | 角の半径 |
| `border` | なし | 枠線の色 |
| `border-width` | `1` | `border` が設定されている場合の枠線の幅 |
| `copy` | `true` | ブロックのテキストをコピーするボタン。`title=` を持つブロックではヘッダーに、それ以外では隅に置く。`false` でなし |

どのプロパティも省略できます。`styles.code` がなければコードはカラースキームに従うため、すでにどのテーマにも合います。`themes.<name>` のテーマは、他のキーと同じく、書いた色だけを上書きします。

フェンス付きブロックは、バッククォートの後に言語を指定します (` ```dart `)。スターター自体はどの言語も知りません。コードが何でできているかは、テーマの `syntax.<language>` (次のセクション) から来ます。どのテーマも持たない言語のブロックは `text` の色で表示されます。

## コードの言語: `syntax`

`syntax.<language>` は、コードを `styles.code` が色付けする断片に分割します。言語はルールのリストで、それぞれが正規表現とそれが一致するものの種類であり、コードの各位置で順に試されます。最初に一致したものが断片を作ります。

```yaml
spring:
  flutter:
    theme:
      syntax:
        java:
          aliases: [jav]                    # フェンス付きブロックでの別の名前
          keywords: [class, public, return, new, 'true', 'false', 'null']
          types: '^[A-Z][A-Za-z0-9_]*[a-z]' # 型の名前である単語
          rules:
            - { match: '//[^\n]*|/\*[\s\S]*?\*/', kind: comment }
            - { match: '"(?:\\.|[^"\\\n])*"', kind: string }
            - { match: '@[A-Za-z_][\w.]*', kind: annotation }
            - { match: '\b\d+(?:\.\d+)?\b', kind: number }
            - { match: '[A-Za-z_$][\w$]*', kind: word }
            - { match: '[{}()\[\];,]', kind: punctuation }
```

| プロパティ | 意味 |
|---|---|
| `rules` | 必須。それぞれ `{ match, kind }`。`match` は書いたとおりに解釈される正規表現 (`$` の参照なし)。`^` と `$` は行の始まりと終わり。`kind` は `comment`、`string`、`annotation`、`number`、`key`、`keyword`、`type`、`variable`、`punctuation`、`plain`、または `word` |
| `keywords` | `word` のルールが `keyword` として色付けする単語。YAML が値として読む `'true'`、`'false'`、`'null'` は引用符で囲む |
| `types` | 正規表現: これに一致する `word` のルールの単語は `type` |
| `aliases` | フェンス付きブロックでの言語の別の名前 (`yaml` に対する `yml`) |

どのルールにも一致しないものはプレーンテキストです。不正なルール (未知の種類、コンパイルできない正規表現、ルールのない言語) は、プロパティを示して起動を止めます。

### URL からの言語

言語を自分で書くことはまれです。farum-azula/themes リポジトリには、Dart、Java、YAML、プロパティ、シェル、JSON が一つのファイルにあります。`spring.flutter.theme` 自体の `source` で、アプリのすべてのテーマのためにそれをダウンロードしてください ([URL からのテーマ](properties.md#url-からのテーマ) を参照)。

```yaml
spring:
  flutter:
    theme:
      source: github:farum-azula/themes/themes/code.yml@code-v0.2.0
      themes:
        neon:
          syntax:
            java: { ... }   # テーマはそれでも一つの言語を置き換えられる
```

ダウンロードした値はすべてのテーマで共有され、独自のファイルの下にあります。自分で書いた `syntax.<language>` が優先されます。

```dart
MarkdownView(text, onLink: (href) => launchUrl(Uri.parse(href)));
MarkdownView.resource('resources:content/docs/beans.md');
const MarkdownView.code('server:\n  port: 8080', language: 'yaml'); // 一つのブロック
```

言語の後に `title` を持つフェンス付きブロックは、タイトルとコードをコピーするボタンを持つヘッダーを得ます。

````markdown
```dart title="lib/orders.dart"
@Service()
class OrderService { ... }
```
````

リンクは `styles.link.color` (デフォルトは `$colors.primary`) を使います。

見出しはタイポグラフィのサイズ (`#` は `headline-large`、`##` は `headline-medium`、`###` は `headline-small`、次に `title-large`、`title-medium`、`title-small`) と `styles.heading` の色を使います。すべてのレベルには `color`、一つのレベルには `h1` ... `h6` です。なければテキストの色になります。

```yaml
styles:
  heading:
    color: $colors.primary     # すべての見出し
    h1: $colors.on-surface     # ただし # はテキストの色
```

表の列はそのテキストの幅になり、最大で `styles.table.cell-width` (デフォルトは 280) まで広がり、そこでテキストが折り返されます。ビューより広い表は、列を詰める代わりに横にスクロールするため、スマートフォンでも読めます。ビューより狭い表は、周りのテキストと揃うよう列をビューの幅まで広げます。`fill: false` はテキストの幅のままにします。

```yaml
styles:
  table:
    cell-width: 240
    fill: true        # デフォルト
```

### コールアウト

GitHub のコールアウトは、その種類の色の、種類の名前をタイトルとするボックスです。

```markdown
> [!WARNING]
> A missing bean stops the start.
```

種類は `note`、`tip`、`important`、`warning`、`caution` です。その色は `styles.callout.<kind>` (デフォルトは `primary`、`tertiary`、`secondary`、`error`、`error`) で、タイトルはメッセージ `markdown.alert.<kind>` です (なければ `Note`、`Tip` など)。そのため `messages_ja.properties` で翻訳できます。

```yaml
styles:
  callout:
    note: $colors.secondary
    warning: '#FF5C7A'
```

### ページの見出し

`MarkdownOutline` は、`MarkdownView` (またはナビゲーションの `RouteContentView`) が表示するページの見出しを、それぞれ GitHub のアンカー (`## Bean methods` は `#bean-methods`) とともに受け取ります。「このページの内容」のリストに使います。`show(id)` はその一つまでスクロールします。ページ内の `#id` へのリンクは自動的にスクロールし、アンカー付きのアドレス (`/docs/beans#scopes`) はその見出しで開きます。

```dart
final outline = MarkdownOutline();

RouteContentView(outline: outline);
ListenableBuilder(
  listenable: outline,
  builder: (context, _) => Column(children: [
    for (final heading in outline.headings.where((h) => h.level == 2))
      TextButton(
        onPressed: () => outline.show(heading.id),
        child: Text(heading.text),
      ),
  ]),
);
```

### リソースの言語

`MarkdownView.resource('resources:content/beans.md')` は、アプリの言語が日本語でそのファイルが存在する場合、代わりに `beans.ja.md` を表示し、言語とともに変わります。

`MarkdownView.code` は、一つのコードブロックを Markdown ページのフェンス付きブロックとまったく同じように表示するため、アプリのすべてのコードサンプルが一つの見た目を共有します。テキストは選択できます。`MaterialApp` の外 (`CupertinoApp`、`WidgetsApp`) では、選択にメニューはありません。

## 関連項目

- [トークンと参照](tokens-and-references.md): 値の型の決まり方と参照のしかた
- [モーションとアニメーション](motion-and-animations.md): カーブと長さ
- [形状、余白、エレベーション](shape-spacing-elevation.md)
- [コンポーネントのテーマ](../../spring-boot-starter-flutter-material/components/index.md): Material のコンポーネントの状態ごとの値
- [タイポグラフィ](typography.md): `code` テキストスタイル
