@ohos-ports/formatter 0.0.0-stage → 0.11.1-beta.0

package/README.md

@@ -1,3 +1,318 @@
-# Temporary Holding Version
+# Herb Formatter <Badge type="warning" text="experimental preview" />
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Package:** [`@herb-tools/formatter`](https://www.npmjs.com/package/@herb-tools/formatter)
+
+> [!WARNING] Experimental Preview
+> This formatter is currently in experimental preview. While it works for many common cases, it may potentially corrupt files in edge cases. Only use on files that can be restored via git or other version control systems.
+
+---
+
+Auto-formatter for HTML+ERB templates with intelligent indentation, line wrapping, and ERB-aware pretty-printing.
+
+Perfect for format-on-save in editors and formatting verification in CI/CD pipelines. Transforms templates into consistently formatted, readable code while preserving all functionality.
+
+## Installation
+
+### Global Installation
+
+:::code-group
+
+```shell [npm]
+npm install -g @herb-tools/formatter
+```
+
+```shell [pnpm]
+pnpm add -g @herb-tools/formatter
+```
+
+```shell [yarn 1]
+yarn global add @herb-tools/formatter
+```
+
+```shell [yarn 4]
+yarn dlx @herb-tools/formatter template.html.erb
+```
+
+```shell [bun]
+bun add -g @herb-tools/formatter
+```
+
+:::
+
+### One-time Usage
+For occasional use without installing:
+
+```bash
+npx @herb-tools/formatter template.html.erb
+```
+
+### Preview Releases
+
+Want to try unreleased features? Use pkg.pr.new to run the formatter from any commit or PR:
+
+```bash
+npx https://pkg.pr.new/@herb-tools/formatter@{commit} template.html.erb
+```
+
+Replace `{commit}` with a commit SHA (e.g., `0d2eabe`) or branch name (e.g., `main`). Find available previews at [pkg.pr.new/~/marcoroth/herb](https://pkg.pr.new/~/marcoroth/herb).
+
+### Project Installation
+
+:::code-group
+
+```shell [npm]
+npm add -D @herb-tools/formatter
+```
+
+```shell [pnpm]
+pnpm add -D @herb-tools/formatter
+```
+
+```shell [yarn]
+yarn add -D @herb-tools/formatter
+```
+
+```shell [bun]
+bun add -D @herb-tools/formatter
+```
+
+:::
+
+After installing as a dev dependency, initialize the configuration:
+
+:::code-group
+
+```shell [npm]
+npx herb-format --init
+```
+
+```shell [pnpm]
+pnpm herb-format --init
+```
+
+```shell [yarn]
+yarn herb-format --init
+```
+
+```shell [bun]
+bunx herb-format --init
+```
+
+:::
+
+Then add format scripts to your `package.json`:
+```json [package.json]
+{
+  "scripts": {
+    "herb:format": "herb-format",
+    "herb:format:check": "herb-format --check"
+  }
+}
+```
+
+Then run the scripts:
+
+:::code-group
+
+```shell [npm]
+npm run herb:format
+npm run herb:format:check
+```
+
+```shell [pnpm]
+pnpm herb:format
+pnpm herb:format:check
+```
+
+```shell [yarn]
+yarn herb:format
+yarn herb:format:check
+```
+
+```shell [bun]
+bun run herb:format
+bun run herb:format:check
+```
+
+:::
+
+## Usage
+
+### Command Line
+
+Basic usage:
+```bash
+herb-format
+herb-format template.html.erb
+herb-format templates/
+```
+
+**Initialize configuration:**
+```bash
+# Create a .herb.yml configuration file
+herb-format --init
+```
+
+#### Options
+
+**Check Mode:**
+```bash
+# Check if files are formatted without modifying them
+herb-format --check template.html.erb
+
+# Check all files in current directory
+herb-format --check
+```
+
+**Input Sources:**
+```bash
+# Format specific file
+herb-format templates/index.html.erb
+
+# Format all .html.erb files in directory
+herb-format templates/
+
+# Format all .html.erb files in current directory (default)
+herb-format
+
+# Format from stdin
+cat template.html.erb | herb-format
+```
+
+**Quiet Mode:**
+```bash
+# Suppress the experimental preview banner and the config file notice on stderr
+herb-format --quiet
+
+# Combine with other options
+herb-format --check --quiet
+```
+
+**Help and Version:**
+```bash
+# Show help
+herb-format --help
+
+# Show version information
+herb-format --version
+```
+
+## Configuration
+
+Create a `.herb.yml` file in your project root to configure the formatter:
+
+```bash
+herb-format --init
+```
+
+### Basic Configuration
+
+```yaml [.herb.yml]
+formatter:
+  enabled: true  # Must be enabled for formatting to work
+  indentWidth: 2
+  indentStyle: space
+  maxLineLength: 80
+
+  # Additional glob patterns to include (additive to defaults)
+  include:
+    - '**/*.xml.erb'
+
+  # Glob patterns to exclude from formatting
+  exclude:
+    - 'vendor/**/*'
+    - 'node_modules/**/*'
+    - 'app/views/generated/**/*'
+```
+
+### Default File Patterns
+
+By default, the formatter processes:
+- `**/*.html`
+- `**/*.rhtml`
+- `**/*.html.erb`
+- `**/*.html+*.erb`
+- `**/*.turbo_stream.erb`
+
+The `include` patterns are **additive** - they add to the defaults.
+
+### Configuration Options
+
+- **`enabled`**: `true` or `false` - Must be `true` to enable formatting
+- **`indentWidth`**: Number (default: `2`) - Spaces per indentation level
+- **`indentStyle`**: `"space"` or `"tab"` (default: `"space"`) - Character used for indentation
+- **`maxLineLength`**: Number (default: `80`) - Maximum line length before wrapping. Tags whose attributes would exceed this length are wrapped one-per-line.
+- **`include`**: Array of glob patterns - Additional patterns to format (additive to defaults)
+- **`exclude`**: Array of glob patterns - Patterns to exclude from formatting
+
+### Force Flag
+
+Format files even when formatter is disabled:
+
+```bash
+# Force formatting when disabled in config
+herb-format --force
+
+# Force formatting on an excluded file
+herb-format --force app/views/excluded-file.html.erb
+```
+
+When using `--force` on an excluded file, the formatter will show a warning but proceed with formatting.
+
+### Disabling Formatting for Entire Files <Badge type="info" text="v0.8.2+" />
+
+You can disable formatting for an entire file by adding the `ignore` directive anywhere in your template:
+
+```erb
+<%# herb:formatter ignore %>
+```
+
+**Example:**
+
+:::code-group
+```erb [ignored.html.erb]
+<%# herb:formatter ignore %>
+
+<div><div>This entire file will not be formatted</div></div>
+```
+
+```erb [formatted.html.erb]
+<div>
+  <div>This file will be formatted</div>
+</div>
+```
+:::
+
+::: warning Important
+The `<%# herb:formatter ignore %>` directive must be an exact match. Extra text or spacing will prevent it from working.
+:::
+
+## Rewriters
+
+The formatter supports **rewriters** that allow you to transform templates before and after formatting.
+
+Configure rewriters in your `.herb.yml`:
+
+```yaml [.herb.yml]
+formatter:
+  enabled: true
+  indentWidth: 2
+
+  rewriter:
+    # Pre-format rewriters (run before formatting)
+    pre:
+      - tailwind-class-sorter
+
+    # Post-format rewriters (run after formatting)
+    post: []
+```
+
+### Built-in Rewriters
+
+- **`tailwind-class-sorter`** - Automatically sorts Tailwind CSS classes according to the recommended order
+
+### Custom Rewriters
+
+You can create custom rewriters by placing them in `.herb/rewriters/` and referencing them in your config.
+
+For detailed documentation on creating and using rewriters, see the [Rewriter Documentation](/projects/rewriter).

package/bin/herb-format

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import("../dist/herb-format.js")