draftail-text-utils 0.1.7__py3-none-any.whl

draftail_text_utils/rich_text/base.py

@@ -0,0 +1,267 @@
+"""
+Shared utilities for registering Draftail rich-text features.
+
+Provides helpers to reduce boilerplate when registering inline-style
+features, converter rules, and control plugins.
+"""
+
+from django.utils.html import json_script
+from wagtail.admin.rich_text.converters.html_to_contentstate import (
+    BlockElementHandler,
+    InlineStyleElementHandler,
+)
+from wagtail.admin.rich_text.editors.draftail.features import (
+    BlockFeature,
+    ControlFeature,
+    EntityFeature,
+    InlineStyleFeature,
+)
+
+
+def control_json_script(type_, label, description, icon, data=None):
+    """
+    Returns a JSON script for a toolbar control plugin for Draftail.
+    """
+    return json_script(
+        {
+            "type": type_,
+            "label": label,
+            "description": description,
+            "icon": icon,
+            "data": data,
+        },
+        f"draftail-plugin-control-{type_}",
+    )
+
+
+def register_inline_style_feature(
+    features,
+    type_,
+    style,
+    css_selector,
+    element="span",
+    props=None,
+    label=None,
+    description=None,
+    icon=None,
+):
+    """
+    Register a single inline-style Draftail feature with its converter rules.
+
+    :param features: The Features registry from the hook.
+    :param type_: Unique type identifer (e.g. ``"TEXT_COLOR_RED"``).
+    :param style: Draftail style dict (e.g. ``{"color": "#EF4444"}``).
+        Property names must be camelCase, i.e. `textAlign` instead of `text-align`.
+    :param css_selector: CSS selector for `from_database_format` (e.g.
+        ``'span[style="color: #EF4444;"]'``).
+    :param element: HTML element to use when converting back (default ``span``).
+    :param props: Extra HTML props for the output element.
+    :param label: Label for the control in the toolbar.
+    :param description: Description for the control in the toolbar.
+    :param icon: Icon name for the control in the toolbar.
+    """
+    control = {
+        "type": type_,
+        "style": style,
+    }
+    props = props or {}
+    props["style"] = style
+
+    if label:
+        control["label"] = label
+    if description:
+        control["description"] = description
+    if icon:
+        control["icon"] = icon
+
+    features.register_editor_plugin(
+        "draftail",
+        type_,
+        InlineStyleFeature(control),
+    )
+
+    db_conversion = {
+        "from_database_format": {css_selector: InlineStyleElementHandler(type_)},
+        "to_database_format": {
+            "style_map": {type_: {"element": element, "props": props}}
+        },
+    }
+
+    features.register_converter_rule("contentstate", type_, db_conversion)
+    features.default_features.append(type_)
+
+
+def register_block_feature(
+    features,
+    type_,
+    style,
+    css_selector,
+    element="div",
+    props=None,
+    label=None,
+    description=None,
+    icon=None,
+):
+    """
+    Register a single block Draftail feature with its converter rules.
+
+    :param features: The Features registry from the hook.
+    :param type_: Unique type identifer (e.g. ``"TEXT_COLOR_RED"``).
+    :param style: Draftail style dict (e.g. ``{"color": "#EF4444"}``).
+        Property names must be camelCase, i.e. `textAlign` instead of `text-align`.
+    :param css_selector: CSS selector for `from_database_format` (e.g.
+        ``'span[style="color: #EF4444;"]'``).
+    :param element: HTML element to use when converting back (default ``span``).
+    :param props: Extra HTML props for the output element.
+    :param label: Label for the control in the toolbar.
+    :param description: Description for the control in the toolbar.
+    :param icon: Icon name for the control in the toolbar.
+    """
+    control = {
+        "type": type_,
+        "style": style,
+    }
+    props = props or {}
+    props["style"] = style
+
+    if label:
+        control["label"] = label
+    if description:
+        control["description"] = description
+    if icon:
+        control["icon"] = icon
+
+    features.register_editor_plugin(
+        "draftail",
+        type_,
+        BlockFeature(control),
+    )
+
+    db_conversion = {
+        "from_database_format": {css_selector: BlockElementHandler(type_)},
+        "to_database_format": {
+            "block_map": {type_: {"element": element, "props": props}}
+        },
+    }
+
+    features.register_converter_rule("contentstate", type_, db_conversion)
+    features.default_features.append(type_)
+
+
+def register_control_feature(
+    features,
+    feature_name,
+    label=None,
+    description=None,
+    icon=None,
+    js_files=None,
+    css_files=None,
+    js=None,
+    css=None,
+):
+    """
+    Register a toolbar control plugin for Draftail.
+
+    :param features: The Features registry.
+    :param feature_name: The control's type identifer (e.g. ``"text-color"``).
+    :param label: Label for the control in the toolbar.
+    :param description: Description for the control in the toolbar.
+    :param icon: Icon name for the control in the toolbar.
+    :param js_files: List of JS file paths (e.g. ``["js/draftail/text_color.js"]``).
+    :param css_files: Dict of CSS files (e.g. ``{"all": ("css/draftail/text_color.css",)}``).
+    """
+    js_files = js_files or js or []
+    css_files = css_files or css or {}
+    control = {
+        "type": feature_name,
+    }
+
+    if label:
+        control["label"] = label
+    if description:
+        control["description"] = description
+    if icon:
+        control["icon"] = icon
+    features.register_editor_plugin(
+        "draftail",
+        feature_name,
+        ControlFeature(
+            control,
+            js=js_files,
+            css=css_files,
+        ),
+    )
+    features.default_features.append(feature_name)
+
+
+def register_entity_feature(
+    features,
+    feature_name,
+    entity_type,
+    attributes,
+    decorator_fn,
+    handler_cls,
+    label=None,
+    description=None,
+    icon=None,
+    js_files=None,
+    css_files=None,
+    js=None,
+    css=None,
+):
+    """
+    Register an entity-based Draftail feature (used for custom/arbitrary values).
+
+    :param features: The Features registry.
+    :param feature_name: Feature name (e.g. ``"custom-text-color"``).
+    :param entity_type: Draftail entity type (e.g. ``"CUSTOM_TEXT_COLOR"``).
+    :param attributes: Entity attributes list.
+    :param decorator_fn: Callable that receives props and returns a DOM element.
+    :param handler_cls: Subclass of ``InlineEntityElementHandler``.
+    :param label: Label for the control in the toolbar.
+    :param description: Description for the control in the toolbar.
+    :param icon: Icon name for the control in the toolbar.
+    :param js_files: JS files for the entity plugin.
+    :param css_files: Dict of CSS files (e.g. ``{"all": ("css/draftail/text_color.css",)}``).
+    """
+    js_files = js_files or js or []
+    css_files = css_files or css or {}
+
+    control = {
+        "type": entity_type,
+        "attributes": attributes,
+    }
+
+    if label:
+        control["label"] = label
+    if description:
+        control["description"] = description
+    if icon:
+        control["icon"] = icon
+
+    features.register_editor_plugin(
+        "draftail",
+        feature_name,
+        EntityFeature(
+            control,
+            js=js_files,
+            css=css_files,
+        ),
+    )
+
+    features.register_converter_rule(
+        "contentstate",
+        feature_name,
+        {
+            "from_database_format": {
+                f"span[data-entity-type='{entity_type}']": handler_cls(entity_type),
+            },
+            "to_database_format": {
+                "entity_decorators": {
+                    entity_type: decorator_fn,
+                }
+            },
+        },
+    )
+
+    features.default_features.append(feature_name)

draftail_text_utils/rich_text/font_family.py

@@ -0,0 +1,61 @@
+"""
+Draftail rich-text feature: Font family.
+
+Registers:
+- One ``InlineStyleFeature`` per configured custom font family.
+- A ``"font-family"`` ControlFeature for the toolbar dropdown.
+"""
+
+import re
+
+from draftail_text_utils.conf import feature_enabled, load_font_families
+
+from .base import (
+    control_json_script,
+    register_control_feature,
+    register_inline_style_feature,
+)
+
+
+def register(features):
+    if not feature_enabled("FONT_FAMILY"):
+        return
+
+    font_families = load_font_families()
+
+    if not font_families:
+        return
+
+    for font in font_families:
+        font_family = font["value"]
+        label = re.sub("[^0-9a-zA-Z]+", "_", font["label"]).upper()
+        type_ = font.get("type", f"FONT_FAMILY_{label}")
+
+        register_inline_style_feature(
+            features,
+            type_,
+            {"fontFamily": font_family},
+            f'span[style="font-family: {font_family};"]',
+        )
+
+    register_control_feature(
+        features,
+        "font-family",
+        icon="font",
+        label="Font Family",
+        description="Change font family",
+        js=["draftail_text_utils/js/font_family.js"],
+        css={"all": ("draftail_text_utils/css/font_family.css",)},
+    )
+
+
+def control():
+    if not feature_enabled("FONT_FAMILY"):
+        return
+
+    return control_json_script(
+        type_="font-family",
+        icon="font",
+        label="Font Family",
+        description="Change font family",
+    )

draftail_text_utils/rich_text/font_size.py

@@ -0,0 +1,94 @@
+"""
+Draftail rich-text feature: Font size.
+
+Registers:
+- A ``"font-size-entity"`` EntityFeature for arbitrary font sizes.
+- A ``"font-size"`` ControlFeature for the toolbar control.
+"""
+
+import cssutils
+
+from draftjs_exporter.dom import DOM
+from wagtail.admin.rich_text.converters.html_to_contentstate import (
+    InlineEntityElementHandler,
+)
+
+from draftail_text_utils.conf import feature_enabled
+
+from .base import (
+    control_json_script,
+    register_control_feature,
+    register_entity_feature,
+)
+
+
+class FontSizeEntityHandler(InlineEntityElementHandler):
+    """
+    Database HTML to Draft.js ContentState.
+    Converts span elements with ``style="font-size: <size>px;"`` to
+    ``FONT_SIZE_<size>`` entities.
+    """
+
+    mutability = "MUTABLE"
+
+    def get_attribute_data(self, attrs):
+        """
+        Extract the font size from the style attribute and return it as
+        an entity.
+        """
+        try:
+            return {"size": cssutils.parseStyle(attrs["style"])["font-size"]}
+        except Exception:
+            return {}
+
+
+def font_size_entity_decorator(props):
+    """
+    Draft.js ContentState to database HTML.
+    Converts ``FONT_SIZE`` entities to span elements with
+    ``style="font-size: <size>;"``.
+    """
+    size = props.get("size")
+    children = props.get("children")
+    attrs = {}
+    if size:
+        attrs["style"] = f"font-size: {size};"
+    attrs["data-entity-type"] = "FONT_SIZE"
+    return DOM.create_element("span", attrs, children)
+
+
+def register(features):
+    if not feature_enabled("FONT_SIZE"):
+        return
+
+    register_entity_feature(
+        features,
+        feature_name="font-size-entity",
+        entity_type="FONT_SIZE",
+        attributes=["size", "style", "data-entity-type"],
+        decorator_fn=font_size_entity_decorator,
+        handler_cls=FontSizeEntityHandler,
+        js=["draftail_text_utils/js/font_size_entity.js"],
+    )
+
+    register_control_feature(
+        features,
+        feature_name="font-size",
+        icon="text-height",
+        label="Font Size",
+        description="Change font size",
+        js=["draftail_text_utils/js/font_size.js"],
+        css={"all": ("draftail_text_utils/css/font_size.css",)},
+    )
+
+
+def control():
+    if not feature_enabled("FONT_SIZE"):
+        return
+
+    return control_json_script(
+        type_="font-size",
+        icon="text-height",
+        label="Font Size",
+        description="Change font size",
+    )

draftail_text_utils/rich_text/highlight_color.py

@@ -0,0 +1,99 @@
+"""
+Draftail rich-text feature: Highlight color.
+
+Registers:
+- A ``"highlight-color-entity"`` EntityFeature for arbitrary text colors.
+- A ``"highlight-color"`` ControlFeature for the toolbar control.
+"""
+
+import cssutils
+
+from draftjs_exporter.dom import DOM
+from wagtail.admin.rich_text.converters.html_to_contentstate import (
+    InlineEntityElementHandler,
+)
+
+from draftail_text_utils.conf import feature_enabled
+
+from .base import (
+    control_json_script,
+    register_control_feature,
+    register_entity_feature,
+)
+
+
+class HighlightColorEntityHandler(InlineEntityElementHandler):
+    """
+    Database HTML to Draft.js ContentState.
+    Converts span elements with ``style="background-color: <color>;"`` to
+    ``HIGHLIGHT_COLOR`` entities.
+    """
+
+    mutability = "MUTABLE"
+
+    def get_attribute_data(self, attrs):
+        """
+        Extract the color from the style attribute and return it as
+        an entity.
+        """
+        try:
+            return {
+                "backgroundColor": cssutils.parseStyle(attrs["style"])[
+                    "background-color"
+                ]
+            }
+        except Exception:
+            return {}
+
+
+def highlight_color_entity_decorator(props):
+    """
+    Draft.js ContentState to database HTML.
+    Converts ``HIGHLIGHT_COLOR`` entities to span elements with
+    ``style="background-color: <backgroundColor>;"``.
+    """
+    background_color = props.get("backgroundColor", None)
+    children = props.get("children", None)
+
+    if not background_color and not children:
+        return None
+
+    attrs = {}
+    if background_color:
+        attrs["style"] = f"background-color: {background_color};"
+    attrs["data-entity-type"] = "HIGHLIGHT_COLOR"
+    return DOM.create_element("span", attrs, children)
+
+
+def register(features):
+    if not feature_enabled("HIGHLIGHT_COLOR"):
+        return
+
+    register_entity_feature(
+        features,
+        feature_name="highlight-color-entity",
+        entity_type="HIGHLIGHT_COLOR",
+        attributes=["backgroundColor", "style", "data-entity-type"],
+        decorator_fn=highlight_color_entity_decorator,
+        handler_cls=HighlightColorEntityHandler,
+        js=["draftail_text_utils/js/highlight_color_entity.js"],
+    )
+
+    register_control_feature(
+        features,
+        feature_name="highlight-color",
+        js=["draftail_text_utils/js/highlight_color.js"],
+        css={"all": ("draftail_text_utils/css/highlight_color.css",)},
+    )
+
+
+def control():
+    if not feature_enabled("HIGHLIGHT_COLOR"):
+        return
+
+    return control_json_script(
+        type_="highlight-color",
+        icon="highlighter",
+        label="Highlight Color",
+        description="Change highlight color",
+    )

draftail_text_utils/rich_text/text_alignment.py

@@ -0,0 +1,70 @@
+"""
+Draftail rich-text feature: Text alignment.
+
+Registers:
+- Four ``BlockFeature``s per alignment value.
+- A ``"text-alignment"`` ControlFeature for the toolbar button group.
+"""
+
+from django.utils.translation import gettext_lazy as _
+
+from draftail_text_utils.conf import feature_enabled
+
+from .base import (
+    control_json_script,
+    register_block_feature,
+    register_control_feature,
+)
+
+
+ALIGNMENTS = [
+    ("ALIGNMENT_LEFT", "left", "start", _("Left")),
+    ("ALIGNMENT_CENTER", "center", "center", _("Center")),
+    ("ALIGNMENT_RIGHT", "right", "end", _("Right")),
+    ("ALIGNMENT_JUSTIFY", "justify", "justify", _("Justify")),
+]
+
+
+def register(features):
+    if not feature_enabled("TEXT_ALIGNMENT"):
+        return
+
+    for type_, _value, styleValue, _label in ALIGNMENTS:
+        register_block_feature(
+            features,
+            type_,
+            {},
+            css_selector=f".dtu-block_text-align[data-dtu-text-align='{styleValue}']",
+            props={
+                "class": "dtu-block_text-align",
+                "data-dtu-text-align": styleValue,
+            },
+        )
+
+    register_control_feature(
+        features,
+        "text-alignment",
+        js=["draftail_text_utils/js/text_alignment.js"],
+        css={"all": ("draftail_text_utils/css/text_alignment.css",)},
+    )
+
+
+def control():
+    if not feature_enabled("TEXT_ALIGNMENT"):
+        return
+
+    return control_json_script(
+        type_="text-alignment",
+        label="Align Text",
+        description="Change text alignment",
+        icon="align-left",
+        data=[
+            {
+                "type": type_,
+                "label": label,
+                "style": {"textAlign": styleValue},
+                "icon": f"align-{value}",
+            }
+            for type_, value, styleValue, label in ALIGNMENTS
+        ],
+    )

draftail_text_utils/rich_text/text_color.py

@@ -0,0 +1,95 @@
+"""
+Draftail rich-text feature: Text color.
+
+Registers:
+- A ``"text-color-entity"`` EntityFeature for arbitrary text colors.
+- A ``"text-color"`` ControlFeature for the toolbar control.
+"""
+
+import cssutils
+
+from draftjs_exporter.dom import DOM
+from wagtail.admin.rich_text.converters.html_to_contentstate import (
+    InlineEntityElementHandler,
+)
+
+from draftail_text_utils.conf import feature_enabled
+
+from .base import (
+    control_json_script,
+    register_control_feature,
+    register_entity_feature,
+)
+
+
+class TextColorEntityHandler(InlineEntityElementHandler):
+    """
+    Database HTML to Draft.js ContentState.
+    Converts span elements with ``style="color: <color>;"`` to
+    ``TEXT_COLOR`` entities.
+    """
+
+    mutability = "MUTABLE"
+
+    def get_attribute_data(self, attrs):
+        """
+        Extract the color from the style attribute and return it as
+        an entity.
+        """
+        try:
+            return {"color": cssutils.parseStyle(attrs["style"])["color"]}
+        except Exception:
+            return {}
+
+
+def text_color_entity_decorator(props):
+    """
+    Draft.js ContentState to database HTML.
+    Converts ``TEXT_COLOR`` entities to span elements with
+    ``style="color: <color>;"``.
+    """
+    color = props.get("color", None)
+    children = props.get("children", None)
+
+    if not color and not children:
+        return None
+
+    attrs = {}
+    if color:
+        attrs["style"] = f"color: {color};"
+    attrs["data-entity-type"] = "TEXT_COLOR"
+    return DOM.create_element("span", attrs, children)
+
+
+def register(features):
+    if not feature_enabled("TEXT_COLOR"):
+        return
+
+    register_entity_feature(
+        features,
+        feature_name="text-color-entity",
+        entity_type="TEXT_COLOR",
+        attributes=["color", "style", "data-entity-type"],
+        decorator_fn=text_color_entity_decorator,
+        handler_cls=TextColorEntityHandler,
+        js=["draftail_text_utils/js/text_color_entity.js"],
+    )
+
+    register_control_feature(
+        features,
+        feature_name="text-color",
+        js=["draftail_text_utils/js/text_color.js"],
+        css={"all": ("draftail_text_utils/css/text_color.css",)},
+    )
+
+
+def control():
+    if not feature_enabled("TEXT_COLOR"):
+        return
+
+    return control_json_script(
+        type_="text-color",
+        icon="palette",
+        label="Text Color",
+        description="Change text color",
+    )

draftail_text_utils/static/draftail_text_utils/css/draftail_text_utils.css

@@ -0,0 +1,5 @@
+/* stylelint-disable selector-class-pattern */
+/* stylelint-disable declaration-property-value-allowed-list */
+.dtu-block_text-align {
+  text-align: attr(data-dtu-text-align type(<custom-ident>), left);
+}