# useProperties

壁紙マニフェスト（`fluxlay.yaml`）で定義され、エンドユーザーが Fluxlay アプリの設定 UI でカスタマイズしたプロパティ値をサブスクライブします。

## インポート

```tsx
import { useProperties } from "@fluxlay/react";
```

## シグネチャ

```tsx
function useProperties<T extends PropertyValues = PropertyValues>(): T;
```

### 型パラメータ

| パラメータ | デフォルト       | 説明                                                                                                           |
| ---------- | ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `T`        | `PropertyValues` | プロパティ値オブジェクトの型。`Record<string, number \| string \| boolean \| string[] \| null>` を拡張します。 |

## 戻り値

現在のプロパティ値を含むオブジェクトを返します。各キーは `fluxlay.yaml` で定義したプロパティ ID に対応します。値はマニフェストのデフォルト値に、ユーザーのカスタマイズが上書きされた結果を反映しています。

初期値の取得が完了するまで `{}` を返します。

## マニフェスト定義

プロパティは `fluxlay.yaml` で定義します:

```yaml title="fluxlay.yaml"
schemaVersion: 1
properties:
  particleCount:
    type: number
    label: パーティクル数
    default: 100
    min: 10
    max: 500
    step: 10
  themeColor:
    type: color
    label: テーマカラー
    default: "#ff6b35"
  showClock:
    type: boolean
    label: 時計を表示
    default: true
  animationStyle:
    type: select
    label: アニメーションスタイル
    default: wave
    options:
      - value: wave
        label: Wave
      - value: spiral
        label: Spiral
```

`properties` の完全なスキーマは[マニフェストリファレンス](/ja/studio/developer/reference/cli/manifest.md)を参照してください。

## プロパティ型

| 型             | TypeScript 型    | UI コントロール                 | 説明                                                              |
| -------------- | ---------------- | ------------------------------- | ----------------------------------------------------------------- |
| `number`       | `number`         | ステッパー / 入力               | min/max/step を任意で指定可能な数値。                             |
| `range`        | `number`         | スライダー                      | スライダー UI を強制する数値。`min` / `max` 必須。                |
| `color`        | `string`         | カラーピッカー                  | hex カラー文字列（例: `"#ff6b35"`）。                             |
| `boolean`      | `boolean`        | トグルスイッチ                  | true または false。                                               |
| `text`         | `string`         | テキスト入力                    | 自由入力テキスト。`maxLength` / `placeholder` を任意指定。        |
| `select`       | `string`         | ドロップダウン                  | 定義済みオプションからの単一選択。                                |
| `multi-select` | `string[]`       | チェックリスト / マルチセレクト | 定義済みオプションからの複数選択。`min` / `max` で個数制約。      |
| `image`        | `string \| null` | ファイルピッカー（画像）        | エンドユーザーが選んだローカル画像の絶対パス。未設定時は `null`。 |
| `file`         | `string \| null` | ファイルピッカー                | 任意のローカルファイルの絶対パス。未設定時は `null`。             |
| `font`         | `string`         | フォントセレクタ                | フォントファミリ名。`sources: [system, google]` で取得元を指定。  |

## 使用例

```tsx
interface WallpaperProperties {
  particleCount: number;
  themeColor: string;
  showClock: boolean;
  animationStyle: string;
}

function Wallpaper() {
  const { particleCount, themeColor, showClock, animationStyle } = useProperties<WallpaperProperties>();

  return (
    <div style={{ backgroundColor: themeColor }}>
      <p>パーティクル数: {particleCount}</p>
      <p>アニメーション: {animationStyle}</p>
      {showClock && <Clock />}
    </div>
  );
}
```

## 備考

- プロパティ値はマウント時に取得され、その後リアルタイムでストリーミングされます。ユーザーが設定 UI で値を変更すると、フックは更新された値で即座に再レンダリングされます。
- ユーザーのカスタマイズは壁紙の slug ごとに永続化されます。同じ壁紙を再インストールまたは再割り当てしても、以前のカスタマイズが復元されます。
- このフックは Fluxlay デスクトップアプリ内でのみ動作します。通常のブラウザでは `{}` を返します。
- `image` / `file` の値はホスト OS 上のファイルパスです。ファイルが移動・削除されると読み込みに失敗するため、壁紙側でフォールバック処理を実装してください。
- マニフェストには `schemaVersion: 1` の宣言が必須です。旧形式の `type: string` は廃止され、`select`（options 必須）または `text`（自由入力）に分割されています。