# #124 Filter Operation & HTML Functional Class Guide

## About this guide
This guide is intended to be sufficient for using #124 Filter without a separate document. The formal Development Order v1.1.1 responsibility is display-filter management. The seven formal types are Blur, Brightness, Contrast, Saturation, Grayscale, Sepia, and Hue Rotate.

## Start here
#124 Filter applies a static visual filter to rendered content. It is not a search/data-query filter. Effect orchestration (#116), Animation timing (#117), Trigger start conditions (#120), Timeline control (#121), Particle (#123), and Blend composition (#125) remain separate responsibilities.

## What is Filter
A Filter expression is `{type, value}`. BoneFilter converts it to a real CSS `filter` value such as `blur(4px)` or `brightness(120%)` and applies it to a target element.

## HTML Functional Class
The single normal-use class is **`bf-filter`**. Do not create one HTML class per Public API. Normal users start with `bf-filter`.

### Class list
- `bf-filter` — the formal HTML entry point for #124 Filter.

### When to use it
Use it when an image, card, preview, or other HTML element needs a static Blur / Brightness / Contrast / Saturation / Grayscale / Sepia / Hue Rotate filter.

### Where to use it
Add `class="bf-filter"` to the element whose rendered result should be filtered.

### Referenced data
| Setting | Meaning | Example |
|---|---|---|
| `class="bf-filter"` | Enables #124 Filter | `class="bf-filter"` |
| `data-filter-type` | One of the seven formal types | `data-filter-type="Blur"` |
| `data-filter-value` | Numeric value for the selected type | `data-filter-value="4"` |

The Runtime-added `bone-filter` class and `data-bone-filter-*` attributes are runtime state markers, not the normal initial configuration contract.

### Minimal HTML
```html
<div class="bf-filter" data-filter-type="Blur">
  Filter target
</div>
```

Complete installed-site sample:

```html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Bone Flow #124 Filter sample</title>
  <link rel="stylesheet" href="/boneflow/css/bone-filter.css">
</head>
<body>
  <div class="bf-filter" data-filter-type="Blur">
    Filter target
  </div>

  <script src="/boneflow/js/bone-filter.js"></script>
  <script src="/boneflow/js/bone-filter-functional-class.js"></script>
</body>
</html>
```

### Minimal result
The Functional Class mounts automatically. Blur uses Runtime Default `4`, producing **`blur(4px)`**.

### Configured HTML
```html
<div class="bf-filter"
     data-filter-type="Brightness"
     data-filter-value="80">
  Brightness 80%
</div>
```
Result: **`brightness(80%)`**.

```html
<div class="bf-filter"
     data-filter-type="Hue Rotate"
     data-filter-value="180">
  Hue Rotate 180deg
</div>
```
Result: **`hue-rotate(180deg)`**.

### Meaning of each HTML setting
`data-filter-type` must exactly match a formal type; lowercase aliases such as `blur` are not silently normalized. `data-filter-value` is numeric and must be within the selected type's Runtime range. If omitted, the Runtime default is used.

### JavaScript operation through the Functional Class
```html
<div id="photo" class="bf-filter" data-filter-type="Grayscale" data-filter-value="100">Target</div>
<script>
  const target = document.getElementById("photo");
  BoneFilterFunctionalClass.setType(target, "Sepia");
  BoneFilterFunctionalClass.setValue(target, 60);
  console.log(BoneFilterFunctionalClass.getCssFilter(target));
  // sepia(60%)
</script>
```

## Runtime defaults / numeric ranges
Development Order defines the seven type names, not numeric ranges/defaults. These are the current BoneFilter 1.0.0 implementation values and are not separately claimed as frozen source specification.

| Type | CSS | Range | Step | Default |
|---|---|---:|---:|---:|
| Blur | `blur(px)` | 0–40 | 1 | 4 |
| Brightness | `brightness(%)` | 0–200 | 1 | 120 |
| Contrast | `contrast(%)` | 0–200 | 1 | 120 |
| Saturation | `saturate(%)` | 0–200 | 1 | 140 |
| Grayscale | `grayscale(%)` | 0–100 | 1 | 100 |
| Sepia | `sepia(%)` | 0–100 | 1 | 100 |
| Hue Rotate | `hue-rotate(deg)` | 0–360 | 1 | 90 |

## Property Editor
Property Language switches Japanese / English. Filter Type selects the expression type. Filter Value is synchronized between range and numeric controls and is applied to the preview.

## Seven formal types
- Blur
- Brightness
- Contrast
- Saturation
- Grayscale
- Sepia
- Hue Rotate

## How to use
Normal use is: add `bf-filter`, select a type with `data-filter-type`, and optionally set `data-filter-value`. Use the Functional Class API or BoneFilter Public API only for dynamic changes. The order of QA buttons on the TEST page is not the usage model of the component.

## Preview
The TEST page converts the selected expression to a real CSS filter and shows Type / Value / CSS / Expression / Runtime together.

## Dependencies / responsibility boundary
#001 Bone Core is the foundation. Connection Image and Delivery QA delegate to canonical #002 Bone Joint 1.1.36. #124 does not implement a private Joint and does not take ownership of #116/#117/#120/#121/#123/#125 responsibilities.

## Connection Image / Joint
The normal case carries an expression object into Filter and a generated CSS string out to the target. Missing fields and type mismatches use official #002 abnormal rendering.

## WAIT / FIFO / BLOCKED
Delivery uses the official #002 `createDeliveryChannel()`. WAIT queues until the target becomes ready, then delivers FIFO. BLOCKED does not deliver to the target. Do not invent `connectionEstablished` inside `getState()`.

## Security
Unknown types, non-exact type names, out-of-range values, arrays, null, and objects with getters/setters are rejected. Validation does not execute an untrusted getter.

## Smoke Test / Validation
Smoke checks Runtime, seven types, Functional Class, Preview, #002 Joint, and Delivery. Validation checks responsibility boundaries, HTML IDs, Completion gate, and abnormal connection cases. Unexecuted localhost tests are not ALL PASS.

## Completion
Completion requires executed Smoke/Validation plus localhost visual confirmation of Filter Preview, Joint, WAIT→READY→FIFO, and BLOCKED. Before USER LOCALHOST confirmation, the package remains Development / Candidate.

## Public API
### BoneFilter Runtime
`getFormalTypes`, `getFilterDefinition`, `normalizeType`, `normalizeValue`, `normalizeExpression`, `validateExpression`, `toCssFilter`, `create`, `mount`, `setExpression`, `setType`, `setValue`, `getExpression`, `getType`, `getValue`, `getCssFilter`, `getState`, `complete`, `reopen`, `destroy`, `isInstance`.

### BoneFilterFunctionalClass
`mount`, `mountAll`, `refresh`, `setExpression`, `setType`, `setValue`, `getExpression`, `getCssFilter`, `unmount`, `isMounted`.

The HTML Functional Class is the normal-use entry point; Public APIs are for advanced/dynamic operations.

## Error / Troubleshooting
- No filter effect: verify `/boneflow/js/bone-filter.js`, `/boneflow/js/bone-filter-functional-class.js`, `bf-filter`, and `data-filter-type`.
- `FILTER_TYPE_INVALID`: verify exact formal type spelling/case.
- `FILTER_VALUE_RANGE`: verify the selected type's range.
- `FILTER_UNTRUSTED_ACCESSOR`: do not pass getter/setter properties in an expression object.
- Changed HTML data attributes are not reflected: call `BoneFilterFunctionalClass.refresh(element)` after changing them.

## Version / Status
Package Version 1.0.1 / Runtime BoneFilter 1.0.0 / HTML Functional Class `bf-filter` 1.0.0. Status remains Development / Candidate until USER LOCALHOST confirmation.