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" }

export function characterCount(text: string, limit: number, unit: CountUnit, threshold: number | null): CharacterCount

export type CountUnit = "characters" | "words";

/** How much has been typed against a limit, and what to tell the person. */
export interface CharacterCount {
  /** characters or words typed */
  readonly count: number;
  /** limit less count; negative when over the limit */
  readonly remaining: number;
  /** more than the limit has been typed */
  readonly over: boolean;
  /** the message should be shown: always when over, else when count reaches the threshold */
  readonly visible: boolean;
  /** "You have 12 characters remaining", "You have 1 word too many" */
  readonly message: string;
  /** the limit said up front, "You can enter up to 200 characters", for a page without JavaScript */
  readonly description: string;
}

import { characterCount } from "#fune/form.character-count@^1";

import type { CharacterCount, CountUnit } from "./form_character_count_types.ts";

/**
 * The Unicode White_Space property, spelled out so all three languages agree
 * on what separates words (JavaScript's \s, Python's str.isspace and Rust's
 * char::is_whitespace each draw the line slightly differently).
 */
function isWhitespace(cp: number): boolean {
  return (
    (cp >= 0x09 && cp <= 0x0d) ||
    cp === 0x20 ||
    cp === 0x85 ||
    cp === 0xa0 ||
    cp === 0x1680 ||
    (cp >= 0x2000 && cp <= 0x200a) ||
    cp === 0x2028 ||
    cp === 0x2029 ||
    cp === 0x202f ||
    cp === 0x205f ||
    cp === 0x3000
  );
}

function countWords(text: string): number {
  let words = 0;
  let inWord = false;
  for (const ch of text) {
    if (isWhitespace(ch.codePointAt(0) as number)) {
      inWord = false;
    } else if (!inWord) {
      inWord = true;
      words++;
    }
  }
  return words;
}

/**
 * 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 text box.
 */
export function characterCount(text: string, limit: number, unit: CountUnit, threshold: number | null): CharacterCount {
  if (typeof text !== "string") throw new TypeError("text must be a string");
  if (!Number.isInteger(limit) || limit < 1) throw new RangeError(`limit must be a whole number of at least 1, received ${limit}`);
  if (unit !== "characters" && unit !== "words") throw new RangeError(`unit must be characters or words, received ${unit}`);
  if (threshold !== null && (!Number.isInteger(threshold) || threshold < 0 || threshold > 100)) {
    throw new RangeError(`threshold must be a whole number from 0 to 100, received ${threshold}`);
  }
  // Code points, not UTF-16 units: an emoji is one character, as in Python and Rust.
  const count = unit === "words" ? countWords(text) : Array.from(text).length;
  const remaining = limit - count;
  const over = remaining < 0;
  // count >= limit * threshold / 100, kept in whole numbers so 50% of 3 is 1.5, not 1.
  const visible = over || threshold === null || count * 100 >= limit * threshold;
  const one = unit === "words" ? "word" : "character";
  const noun = (n: number) => (n === 1 ? one : unit);
  const message = over ? `You have ${-remaining} ${noun(-remaining)} too many` : `You have ${remaining} ${noun(remaining)} remaining`;
  return { count, remaining, over, visible, message, description: `You can enter up to ${limit} ${noun(limit)}` };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript 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 TypeScript implementation. Install it without the registry with fune add ./form.character-count-1.0.1-typescript.fune, or fetch it from a terminal with fune pull form.character-count@1.0.1:typescript.

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