form.character-count

characterCount("Hello", 10, "characters", null)
// { count: 5, remaining: 5, over: false, visible: true,
//   message: "You have 5 characters remaining",
//   description: "You can enter up to 10 characters" }

def character_count(text: str, limit: int, unit: CountUnit, threshold: Optional[int]) -> CharacterCount

CountUnit = Literal["characters", "words"]

@dataclass(frozen=True)
class CharacterCount:
    """How much has been typed against a limit, and what to tell the person."""

    #: characters or words typed
    count: int
    #: limit less count; negative when over the limit
    remaining: int
    #: more than the limit has been typed
    over: bool
    #: the message should be shown: always when over, else when count reaches the threshold
    visible: bool
    #: "You have 12 characters remaining", "You have 1 word too many"
    message: str
    #: the limit said up front, "You can enter up to 200 characters", for a page without JavaScript
    description: str

from fune.form.character_count import character_count  # form.character-count@^1

from typing import Any, Optional

from .form_character_count_types import CharacterCount, CountUnit


def _whole(value: Any) -> bool:
    # bool is an int in Python; True is not a limit of one here.
    return isinstance(value, int) and not isinstance(value, bool)


def _is_whitespace(ch: str) -> bool:
    """The Unicode White_Space property, spelled out so all three languages
    agree: str.isspace also accepts U+001C-U+001F, which JavaScript and Rust
    do not.
    """
    cp = ord(ch)
    return (
        0x09 <= cp <= 0x0D
        or cp == 0x20
        or cp == 0x85
        or cp == 0xA0
        or cp == 0x1680
        or 0x2000 <= cp <= 0x200A
        or cp == 0x2028
        or cp == 0x2029
        or cp == 0x202F
        or cp == 0x205F
        or cp == 0x3000
    )


def _count_words(text: str) -> int:
    words = 0
    in_word = False
    for ch in text:
        if _is_whitespace(ch):
            in_word = False
        elif not in_word:
            in_word = True
            words += 1
    return words


def character_count(text: str, limit: int, unit: CountUnit, threshold: Optional[int]) -> CharacterCount:
    """GOV.UK's character count: how many characters (code points) or words
    have been typed against a limit, and the sentence to show under the box.
    """
    if not isinstance(text, str):
        raise TypeError("text must be a string")
    if not _whole(limit) or limit < 1:
        raise ValueError("limit must be a whole number of at least 1, received %r" % (limit,))
    if unit not in ("characters", "words"):
        raise ValueError("unit must be characters or words, received %r" % (unit,))
    if threshold is not None and (not _whole(threshold) or threshold < 0 or threshold > 100):
        raise ValueError("threshold must be a whole number from 0 to 100, received %r" % (threshold,))
    # A Python str is indexed by code point already.
    count = _count_words(text) if unit == "words" else len(text)
    remaining = limit - count
    over = remaining < 0
    # count >= limit * threshold / 100, kept in whole numbers so 50% of 3 is 1.5, not 1.
    visible = over or threshold is None or count * 100 >= limit * threshold
    one = "word" if unit == "words" else "character"

    def noun(n: int) -> str:
        return one if n == 1 else unit

    if over:
        message = "You have %d %s too many" % (-remaining, noun(-remaining))
    else:
        message = "You have %d %s remaining" % (remaining, noun(remaining))
    return CharacterCount(
        count=count,
        remaining=remaining,
        over=over,
        visible=visible,
        message=message,
        description="You can enter up to %d %s" % (limit, noun(limit)),
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add form.character-count

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./form.character-count-1.0.1-python.fune, or fetch it from a terminal with fune pull form.character-count@1.0.1:python.

The whole function, every language, is one file too: form.character-count-1.0.1.fune, 25,373 bytes, sha256 09734b67f0d2f813a074ca016c5da79fa9a3dd8e621c10f984d1144a87919df2. It installs into a project of any language.

# fune: before form.character-count

# fune: after form.character-count

# fune: step form.character-count after <n|label>

More from the author

`react.form.textarea` shows it live as the person types. It is written in all three languages because the server has to enforce the same limit: a count the browser and the API disagree on is a form that says "0 remaining" and then rejects the post.

## Decisions

- **Characters are Unicode code points.** An emoji is 1, not the 2 UTF-16 units JavaScript's `length` (and GOV.UK's own script) counts, so all three languages agree. A decomposed accent (`e` plus a combining acute) is 2. Text is counted as given: a browser posts a line break in a textarea as `\r\n`, which is 2 characters, so normalise line breaks before counting on the server if the limit must match the browser's. - **Words are runs of anything but whitespace**, like GOV.UK's `/\S+/g`, with whitespace spelled out as the Unicode White_Space set (tab to carriage return, space, U+0085, no-break space, U+1680, U+2000-U+200A, the line and paragraph separators, U+202F, U+205F, U+3000) so every language splits alike. Punctuation does not split: `two,three` is one word. - **The threshold** is a percentage of the limit below which the message is not shown (`visible` false), as GOV.UK's `threshold` option. The comparison is `count * 100 >= limit * threshold` in whole numbers, so 50% of 3 is 1.5 and one character stays below it. `null` shows the message always; so does being over the limit, whatever the threshold. The message is worked out even when not visible. - **remaining** goes negative when over; `message` says the positive number "too many". - **description** is GOV.UK's `textareaDescriptionText`, "You can enter up to 200 characters" (singular for a limit of 1), for a page before its script runs.

Errors, identical in every language: `limit must be a whole number of at least 1`, `threshold must be a whole number from 0 to 100`, `unit must be characters or words`.

Sources: GOV.UK Design System, "Character count" https://design-system.service.gov.uk/components/character-count/; the wording and the threshold rule from govuk-frontend's `character-count.mjs` (`charactersUnderLimit`, `charactersAtLimit`, `charactersOverLimit`, `wordsUnderLimit`, `wordsAtLimit`, `wordsOverLimit`, `isOverThreshold`) https://github.com/alphagov/govuk-frontend/blob/main/packages/govuk-frontend/src/govuk/components/character-count/character-count.mjs.

## Notices

Portions derived from GOV.UK Frontend (https://github.com/alphagov/govuk-frontend), Copyright (c) 2017 Crown Copyright (Government Digital Service), under the MIT License; the full notice is in NOTICE.

1.0.1 adds its attribution notices (NOTICE). The code and the tests are unchanged.

Files