EventHandler
URL parser
{{ EventHandler }}
```
### How it works?
tl;dr: We created a search API over CSS Working Group's Shepherd APIs.
- HTTP API
- https://respec.org/xref
- Integrates CSSWG's Shepherd API via [tabatkins/bikeshed-data](https://github.com/tabatkins/bikeshed-data).
- Links definitions exported from a spec (which have `data-export`).
- ReSpec
- Collect terms to link and along with their _contextual information_.
- Send request to the API.
- Link terms.
- Profit.
### How to use xref?
Earlier, to link to [URL parser](https://url.spec.whatwg.org/#concept-url-parser) defined in [[URL]] spec, we had to write `URL parser`.
Now we can write `URL parser` or `[\= URL parser =]` (`\` added to prevent automatic linking in this document, for demonstration).
We have to tell ReSpec in which specs we want to search the definitions for. Set `respecConfig.xref = ["url"]` to let ReSpec know that we want to link to terms defined in [[URL]] spec. Now it will search for terms and link them. You can write spec shortnames as well as spec IDs, though shortnames are preferred.
We can also link to IDL terms using **IDL Linking micro-syntax**. Instead of writing `EventHandler`, we can write `{{\ EventHandler }}` (but don't forget to change [`respecConfig.xref`](https://github.com/speced/respec/wiki/xref) to `["url", "html"]`).
A whitespace-separated list of specs can be added on <body> as: <body data-cite="url html">, instead of adding it in `respecConfig.xref`.
We also support nested contextual linking, for example, `{{\ EventTarget.addEventListener(type, callback) }}` will link to both EventTarget interface as well as addEventListener method on EventTarget.
Note: Keep in mind that the IDL linking micro-syntax is case sensitive.
It may become a little cumbersome to specify all the specs we want to search in. We also support profiles that expand to list of specs. Setting `respecConfig.xref = "web-platform"` is equivalent to `respecConfig.xref = ["HTML", "INFRA", "URL", "WEBIDL", "DOM", "FETCH"]`. At the time of writing, only "web-platform" profile is supported.
### Context
We can provide search context in 3 ways:
- Which spec(s)?
- What type: IDL (interface, attribute, ...), Concept (dfn, event, element)
- `data-dfn-for` AKA "for context"
#### spec context
We can write specs to search using `data-cite` attributes. Go through the following example as an explanation.
```html
event handler: - will be searched in either [dom] or [html] (closest data-cite)
event handler - will be first searched in [svg] - then the search will fallback to [dom] - then the search will fallback to [dom], [html] (all will be done in a single request, so it's fast)
If you provide a `data-cite` directly on `<a>`, fallback won't be used: event handler: - search for "event handler" in [fetch], which fails. - the element will link to [fetch] for backward compatibility. - an error will be shown saying the term couldn't be found.
We can also use the inline `[[\ spec ]]` biblio reference syntax to create context. Here, [[css-scoping]] is to create context for shadow root
Ambiguous Definition: defined in multiple specs: [^script^]. Defined in both [html] and [svg2]. Resolution: Provide a stricter data-cite.
No such term found: [= foobar =] Term not found. Possible reasons: - the data-cite asked to search in wrong specs. - the context was too strict. - the term isn't exported from the spec. - Verify the spec exports the term. - Contact us or the spec author. - our database (Shepherd) doesn't have it. Create an issue on GitHub.
Defined in multiple ways in a single spec: [= request =] Not enough context to understand. Provide context: - [=cache batch operation/request=] - {{FetchEventInit/request}} - {{FetchEvent/request}}
``` ### xref search UI As we kinda created a search engine for the terms in Shepherd database, we also added a UI to make it easy to search for them. The UI can be accessed in following ways: - via the ReSpec pill - Click the ReSpec pill in top-right corner of page - Select "Search definitions" - or, visit https://respec.org/xref/ ## Web IDL linking We added several features using Web IDL parser library named [webidl2.js](https://github.com/speced/webidl2.js/) and the first of them is automatic IDL linking.
[Exposed=Window]
interface LinkWorksEvent: Event {
void makeLinkWork(EventInit init);
attribute HTMLLinkElement link;
};
webidl2.js detects that this IDL block has several identifiers that needs
linking, and then it uses the cross reference feature we mentioned earlier to
link them to the relevant lines of their specifications. Here we have `Event`
to DOM and `HTMLLinkElement` to HTML, and you can click them to navigate to
their relevant specifications.
[Exposed=Window]
partial interface Navigator {};
ReSpec also supports linking partial types. Here, you can click `Navigator` to
navigate to the relevant section of HTML.
## IDL self-definition
[Exposed=Window]
interface TryLinkingToMe {};
Previously we had to provide a proper `` element when we define any IDL
types. Now you can skip it if you are sure you don't need one and prefer
simpler document structure. We still recommends you to provide a good
explanation for your IDL types with `` whenever possible.
```
TryLinkingToMe // This is now optional
TryLinkingToMe // Linking is now possible without
```
## Web IDL validations
One of the best feature frow webidl2.js is validation! It's easy to write
invalid IDL because specification authors are not always IDL experts. Also, the
Web IDL specification itself can change in a breaking way. The
validation feature in ReSpec helps fixing IDL when that happens.
### Duplicate identifiers
// No duplicate ids allowed!
[Exposed=Window]
interface Duplicated {};
dictionary Duplicated {}; // oops!
ReSpec warns if there are duplicated identifiers. You can read
the relevant error messages and the exact position of the errors when you click
the ReSpec pill. You can also click `[1]` to see where the erroneous IDL blocks
are.
### Constructor syntax
// Use new constructor() - can be autofixed!
[Exposed=Window, Constructor]
interface IHaveConstructor {
};
Recently Web IDL specification is changed to use new `constructor()` operation
syntax instead of previous `[Constructor]` extended attribute. Now ReSpec warns
when you use `[Constructor]`, and it also provides an automatically suggested
fix from the ReSpec pill! You can copy-paste the suggestion to fix IDLs and
voila! The error disappears.
### Implicitly exposed types
// Needs explicit [Exposed]
interface ImplicitlyExposed {};
Previously interfaces with explicit `[Exposed]` are considered as being
implicitly exposed to `Window` only. Now interfaces are required to exposed
explicitly, and thus ReSpec automatically suggests adding `[Exposed=Window]`.
### Optional dictionary argument
// optional dictionary argument
// needs a default value
dictionary MyDictionary {};
[Exposed=Window]
interface IUseTheDictionary {
void doTheFoo(optional MyDictionary dict);
};
Similarly, ReSpec now suggest adding `= {}` because optional dictionary
arguments are now required to have an explicit default value.
### Why just warnings, could it just fix everything for us?
* Changes should be reviewed, shouldn't be magic.
We want authors to know what's exactly happening, and also there are cases
that authors might want to review before applying the fix. For example,
authors might want to add `[Exposed=(Window,Worker)]` instead of just
`[Exposed=Window]` suggested from ReSpec.
* There is [a bot](https://github.com/speced/payment-handler/pull/343) to fix IDLs for us.
Because copy-paste is hard! It also helps non-ReSpec specifications to get
correct IDLs.
## Algorithms
- var pipe syntax
- type annotations
- variable highlighting