npm package: @stellaps/form
Description: Reusable form utilities (custom element).
Author: riki
Latest version: 0.0.18

# @stellaps/form

再利用可能なフォームユーティリティ（Web Components）

## インストール

```bash
# npm
npm install @stellaps/form

# yarn
yarn add @stellaps/form

# pnpm
pnpm add @stellaps/form
```

## 基本的な使用方法

### HTML（スタンドアロン）

```html
<!DOCTYPE html>
<html>
  <head>
    <script
      type="module"
      src="https://unpkg.com/@stellaps/form/dist/element.global.js"
    ></script>
  </head>
  <body>
    <sales-form title="お問い合わせフォーム" endpoint="/api/contact">
    </sales-form>
  </body>
</html>
```

### React

```jsx
import { SalesFormReact } from "@stellaps/form/react";

function App() {
  return (
    <SalesFormReact title="お問い合わせフォーム" endpoint="/api/contact" />
  );
}
```

### Node.js/ES Modules

```javascript
import { SalesForm } from "@stellaps/form";

// Web Components として利用
// HTMLで <sales-form> タグが使用可能になります
```

## カスタムスタイリング

### 1. カスタムスタイルファイルの作成

パッケージをインストールすると、自動的に `diesales-style.css` ファイルがプロジェクトルートに作成されます。このファイルは自動的に読み込まれるため、`css`属性を指定する必要はありません。

**重要**: `diesales-style.css` ファイルは、Web サーバーのドキュメントルート（`/diesales-style.css`）からアクセス可能な場所に配置する必要があります。

**フォールバック機能**: `diesales-style.css` ファイルが存在しない、または読み込みに失敗した場合、自動的にデフォルトスタイルが適用されます。そのため、カスタムスタイルファイルがなくてもフォームは正常に動作します。

一般的な配置場所：

- **静的サイト**: `public/diesales-style.css` または プロジェクトルート
- **Next.js**: `public/diesales-style.css`
- **Vite/Webpack**: `public/diesales-style.css`
- **Express.js**: 静的ファイル提供ディレクトリ内

#### プロジェクト構成例

**Next.js プロジェクト:**

```
my-nextjs-project/
├── public/
│   ├── diesales-style.css  ← ここに配置
│   └── favicon.ico
├── pages/
│   └── index.js
└── package.json
```

**Vite プロジェクト:**

```
my-vite-project/
├── public/
│   ├── diesales-style.css  ← ここに配置
│   └── vite.svg
├── src/
│   └── main.js
└── package.json
```

**静的サイト:**

```
my-website/
├── diesales-style.css  ← ここに配置
├── index.html
└── package.json
```

#### ファイル移動手順

パッケージインストール後、作成された `diesales-style.css` ファイルを適切な場所に移動してください：

```bash
# Next.js / Vite プロジェクトの場合
mv diesales-style.css public/

# 静的サイトの場合（既に正しい場所にあります）
# 移動不要
```

手動で作成・再作成したい場合は、以下のコマンドを使用できます：

```bash
# npm
npx @stellaps/form init-styles

# yarn
yarn dlx @stellaps/form init-styles

# 確認なしで自動作成
npx @stellaps/form init-styles --auto

# 既存ファイルを上書きする場合
npx @stellaps/form init-styles --force
```

### 2. フォームの使用

```html
<sales-form title="お問い合わせフォーム" endpoint="/api/contact"> </sales-form>
```

**注意**: `diesales-style.css` ファイルは自動的に読み込まれるため、属性で指定する必要はありません。

### 3. スタイルのカスタマイズ

`diesales-style.css` ファイルを編集して、以下の要素をスタイリングできます：

- `form` - フォーム全体
- `h2` - タイトル
- `label` - ラベル
- `input[name="name"]` - 名前入力フィールド
- `input[name="company"]` - 会社名入力フィールド
- `input[name="email"]` - メールアドレス入力フィールド
- `textarea[name="message"]` - メッセージ入力フィールド
- `button` - 送信ボタン
- `.status.success` - 成功メッセージ
- `.status.error` - エラーメッセージ

#### カスタマイズ例

`diesales-style.css` ファイルに以下のように記述することで、フォームをカスタマイズできます：

```css
/* 名前フィールドに青いボーダーを追加 */
input[name="name"] {
  border-left: 4px solid #4299e1;
  background: linear-gradient(90deg, #ebf8ff 0%, #ffffff 100%);
}

/* 送信ボタンのカスタマイズ */
button {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  text-transform: uppercase;
  letter-spacing: 0.5px;
}

button:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);
}
```

## API リファレンス

### 属性

| 属性       | 型     | デフォルト     | 説明                           |
| ---------- | ------ | -------------- | ------------------------------ |
| `title`    | string | "Contact us"   | フォームのタイトル             |
| `endpoint` | string | "/api/contact" | フォーム送信先のエンドポイント |

**注意**: 以前のバージョンでは `css` 属性がありましたが、現在は `diesales-style.css` ファイルが自動的に読み込まれるため不要です。

### フォームデータ

送信されるデータの形式：

```json
{
  "name": "田中太郎",
  "company": "株式会社サンプル",
  "email": "taro@example.com",
  "message": "お問い合わせ内容..."
}
```

## サーバーサイドの実装例

### Express.js

```javascript
app.post("/api/contact", express.json(), (req, res) => {
  const { name, company, email, message } = req.body;

  // バリデーション
  if (!name || !email || !message) {
    return res.status(400).json({ error: "Required fields are missing" });
  }

  // メール送信やデータベース保存などの処理
  // ...

  res.json({ success: true });
});
```

### Next.js API Routes

```javascript
export default async function handler(req, res) {
  if (req.method !== "POST") {
    return res.status(405).json({ error: "Method not allowed" });
  }

  const { name, company, email, message } = req.body;

  // バリデーション
  if (!name || !email || !message) {
    return res.status(400).json({ error: "Required fields are missing" });
  }

  // 処理...

  res.json({ success: true });
}
```

## ブラウザサポート

- Chrome 54+
- Firefox 63+
- Safari 10.1+
- Edge 79+

## ライセンス

MIT

## 開発・貢献

```bash
# クローン
git clone https://github.com/stellaps/form.git
cd form

# 依存関係のインストール
yarn install

# 開発モード
yarn dev

# ビルド
yarn build
```

## 更新履歴

### 0.0.8

- カスタムスタイリング機能を追加
- `diesales-style.css` ファイルを自動作成・自動読み込み
- `init-styles` CLI コマンドを追加
- `css` 属性を削除（固定で `diesales-style.css` を読み込み）