=== Uplink Editorial Semantics ===
Contributors: stphnwlkr
Tags: block-editor, semantic-html, quotes, accessibility, formatting
Requires at least: 7.0
Tested up to: 7.1
Requires PHP: 8.3
Stable tag: 1.0.0
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Adds semantic inline formats, controlled inline spans, and a structured quotation block to the WordPress Block Editor.

== Description ==

Uplink Editorial Semantics adds editorial markup tools to Rich Text fields in the WordPress Block Editor. The saved content uses standard HTML and does not require front-end JavaScript.

Inline formats:

* **Inline quotation** (`q`) with optional BCP 47 language and citation URL attributes.
* **Citation** (`cite`) for the title of a creative work.
* **Abbreviation** (`abbr`) with a required expanded form.
* **Defining instance** (`dfn`) for the occurrence of a term being defined.
* **Inline span** (`span`) with optional sanitized CSS classes and one custom `data-*` name/value pair for cases where no semantic element is appropriate.
* **Link attributes** for adding one custom `data-*` name/value pair and an optional `aria-label` to an existing native hyperlink.

The **Editorial Quotation** block saves a `figure` containing a `blockquote` and an optional `figcaption`. Its quotation area accepts Paragraph, Heading, and List blocks. The plugin supplies no front-end styling, allowing the active theme to control presentation.

== Installation ==

1. Install and activate the plugin.
2. Open a post or page in the Block Editor.
3. Select text in a Rich Text field to use the added formatting controls, or insert the Editorial Quotation block.

== Frequently Asked Questions ==

= Where are the inline formats? =

Select text in a supported Rich Text field. The available controls appear with the editor's other inline formatting tools.

= When should I use Citation? =

Use `cite` for the title of a work, such as a book, article, film, or report. Do not use it merely to italicize a person's name.

= When should I use Inline Span? =

Use it only when no semantic HTML element describes the text and you need a stable CSS or JavaScript hook. The plugin adds its own base class, sanitizes the custom class tokens you enter, and can add one custom data attribute. Enter the part after `data-` using lowercase letters, numbers, and hyphens; for example, the name `state` and value `active` save as `data-state="active"`.

= How do I add attributes to a link? =

Place the text cursor inside an existing hyperlink or select linked text, then choose **Link attributes** from the inline formatting toolbar. You can enter the part after `data-` and its value, an `aria-label`, or both. The plugin preserves these attributes when the link is later edited with WordPress's native link controls.

An `aria-label` replaces the link's visible text as its accessible name. Normally, include the visible link text in the complete label. For example, a visible **Download report** link that opens a new tab could use `Download report (opens in a new tab)`.

= Does the plugin add front-end scripts or styles? =

No. It saves standard HTML and leaves its presentation to your theme.

= What happens if I deactivate the plugin? =

Published HTML remains in the content. The custom formatting controls and Editorial Quotation editing interface are unavailable until the plugin is reactivated.

= Does the plugin collect data? =

No. It stores no plugin settings, sends no network requests, and performs no tracking.

== Development ==

Human-readable source is included in the plugin's `src` directory, and the build configuration is included in `package.json`. Public source and contribution history are also available at https://github.com/stphnwlkr/uplink-editorial-semantics.

To build the production assets, install Node.js and npm, run `npm install`, and then run `npm run build`. The compiled files are written to the `build` directory.

== Changelog ==

= 1.0.0 =

* Initial WordPress.org release.
* Added inline quotation, citation, abbreviation, defining-instance, and controlled inline-span formats.
* Added an optional custom `data-*` name/value pair to inline spans.
* Added a companion control for custom `data-*` attributes on native hyperlinks.
* Added an optional `aria-label` field with accessibility guidance for native hyperlinks.
* Added the Editorial Quotation block with an optional attribution.
