@types/govuk-frontend 5.4.0

govuk-frontend/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

govuk-frontend/README.md

@@ -0,0 +1,15 @@
+# Installation
+> `npm install --save @types/govuk-frontend`
+
+# Summary
+This package contains type definitions for govuk-frontend (https://github.com/alphagov/govuk-frontend).
+
+# Details
+Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/govuk-frontend.
+
+### Additional Details
+ * Last updated: Thu, 25 Jul 2024 08:37:24 GMT
+ * Dependencies: none
+
+# Credits
+These definitions were written by [Colin Rotherham](https://github.com/colinrotherham).

govuk-frontend/dist/govuk/all.bundle.d.mts

@@ -0,0 +1,14 @@
+export { version } from "./common/govuk-frontend-version.mjs";
+export { Accordion } from "./components/accordion/accordion.mjs";
+export { Button } from "./components/button/button.mjs";
+export { CharacterCount } from "./components/character-count/character-count.mjs";
+export { Checkboxes } from "./components/checkboxes/checkboxes.mjs";
+export { ErrorSummary } from "./components/error-summary/error-summary.mjs";
+export { ExitThisPage } from "./components/exit-this-page/exit-this-page.mjs";
+export { Header } from "./components/header/header.mjs";
+export { NotificationBanner } from "./components/notification-banner/notification-banner.mjs";
+export { PasswordInput } from "./components/password-input/password-input.mjs";
+export { Radios } from "./components/radios/radios.mjs";
+export { SkipLink } from "./components/skip-link/skip-link.mjs";
+export { Tabs } from "./components/tabs/tabs.mjs";
+export { type Config, type ConfigKey, createAll, initAll } from "./init.mjs";

govuk-frontend/dist/govuk/all.bundle.d.ts

@@ -0,0 +1,39 @@
+import { version } from "./common/govuk-frontend-version.js";
+import { Accordion } from "./components/accordion/accordion.js";
+import { Button } from "./components/button/button.js";
+import { CharacterCount } from "./components/character-count/character-count.js";
+import { Checkboxes } from "./components/checkboxes/checkboxes.js";
+import { ErrorSummary } from "./components/error-summary/error-summary.js";
+import { ExitThisPage } from "./components/exit-this-page/exit-this-page.js";
+import { Header } from "./components/header/header.js";
+import { NotificationBanner } from "./components/notification-banner/notification-banner.js";
+import { PasswordInput } from "./components/password-input/password-input.js";
+import { Radios } from "./components/radios/radios.js";
+import { SkipLink } from "./components/skip-link/skip-link.js";
+import { Tabs } from "./components/tabs/tabs.js";
+import { type Config as ConfigImport, type ConfigKey as ConfigKeyImport, createAll, initAll } from "./init.js";
+
+declare namespace GOVUKFrontend {
+    type Config = ConfigImport;
+    type ConfigKey = ConfigKeyImport;
+}
+
+declare const GOVUKFrontend: {
+    version: typeof version;
+    Accordion: typeof Accordion;
+    Button: typeof Button;
+    CharacterCount: typeof CharacterCount;
+    Checkboxes: typeof Checkboxes;
+    ErrorSummary: typeof ErrorSummary;
+    ExitThisPage: typeof ExitThisPage;
+    Header: typeof Header;
+    NotificationBanner: typeof NotificationBanner;
+    PasswordInput: typeof PasswordInput;
+    Radios: typeof Radios;
+    SkipLink: typeof SkipLink;
+    Tabs: typeof Tabs;
+    createAll: typeof createAll;
+    initAll: typeof initAll;
+};
+
+export = GOVUKFrontend;

govuk-frontend/dist/govuk/all.d.mts

@@ -0,0 +1 @@
+export * from "./all.bundle.mjs";

govuk-frontend/dist/govuk/common/closest-attribute-value.d.mts

@@ -0,0 +1 @@
+export * from "./closest-attribute-value.js";

govuk-frontend/dist/govuk/common/closest-attribute-value.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns the value of the given attribute closest to the given element (including itself)
+ *
+ * @internal
+ * @param {Element} $element - The element to start walking the DOM tree up
+ * @param {string} attributeName - The name of the attribute
+ * @returns {string | null} Attribute value
+ */
+export function closestAttributeValue($element: Element, attributeName: string): string | null;

govuk-frontend/dist/govuk/common/govuk-frontend-version.d.mts

@@ -0,0 +1 @@
+export * from "./govuk-frontend-version.js";

govuk-frontend/dist/govuk/common/govuk-frontend-version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * GOV.UK Frontend release version
+ *
+ * {@link https://github.com/alphagov/govuk-frontend/releases}
+ */
+export const version: "development";

govuk-frontend/dist/govuk/common/index.d.mts

@@ -0,0 +1 @@
+export * from "./index.js";

govuk-frontend/dist/govuk/common/index.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Common helpers which do not require polyfill.
+ *
+ * IMPORTANT: If a helper require a polyfill, please isolate it in its own module
+ * so that the polyfill can be properly tree-shaken and does not burden
+ * the components that do not need that helper
+ */
+/**
+ * Config merging function
+ *
+ * Takes any number of objects and combines them together, with
+ * greatest priority on the LAST item passed in.
+ *
+ * @internal
+ * @param {...{ [key: string]: unknown }} configObjects - Config objects to merge
+ * @returns {{ [key: string]: unknown }} A merged config object
+ */
+export function mergeConfigs(
+    ...configObjects: Array<{
+        [key: string]: unknown;
+    }>
+): {
+    [key: string]: unknown;
+};
+
+/**
+ * Extracts keys starting with a particular namespace from dataset ('data-*')
+ * object, removing the namespace in the process, normalising all values
+ *
+ * @internal
+ * @param {{ schema: Schema }} Component - Component class
+ * @param {DOMStringMap} dataset - The object to extract key-value pairs from
+ * @param {string} namespace - The namespace to filter keys with
+ * @returns {ObjectNested | undefined} Nested object with dot-separated key namespace removed
+ */
+export function extractConfigByNamespace(
+    Component: {
+        schema: Schema;
+    },
+    dataset: DOMStringMap,
+    namespace: string,
+): ObjectNested | undefined;
+
+/**
+ * Get hash fragment from URL
+ *
+ * Extract the hash fragment (everything after the hash) from a URL,
+ * but not including the hash symbol
+ *
+ * @param {string} url - URL
+ * @returns {string | undefined} Fragment from URL, without the hash
+ */
+export function getFragmentFromUrl(url: string): string | undefined;
+
+/**
+ * Get GOV.UK Frontend breakpoint value from CSS custom property
+ *
+ * @param {string} name - Breakpoint name
+ * @returns {{ property: string, value?: string }} Breakpoint object
+ */
+export function getBreakpoint(name: string): {
+    property: string;
+    value?: string;
+};
+
+/**
+ * Move focus to element
+ *
+ * Sets tabindex to -1 to make the element programmatically focusable,
+ * but removes it on blur as the element doesn't need to be focused again.
+ *
+ * @template {HTMLElement} FocusElement
+ * @param {FocusElement} $element - HTML element
+ * @param {object} [options] - Handler options
+ * @param {function(this: FocusElement): void} [options.onBeforeFocus] - Callback before focus
+ * @param {function(this: FocusElement): void} [options.onBlur] - Callback on blur
+ */
+export function setFocus<FocusElement extends HTMLElement>(
+    $element: FocusElement,
+    options?: {
+        onBeforeFocus?: ((this: FocusElement) => void) | undefined;
+        onBlur?: ((this: FocusElement) => void) | undefined;
+    },
+): void;
+
+/**
+ * Checks if GOV.UK Frontend is supported on this page
+ *
+ * Some browsers will load and run our JavaScript but GOV.UK Frontend
+ * won't be supported.
+ *
+ * @internal
+ * @param {HTMLElement | null} [$scope] - HTML element `<body>` checked for browser support
+ * @returns {boolean} Whether GOV.UK Frontend is supported on this page
+ */
+export function isSupported($scope?: HTMLElement | null): boolean;
+
+/**
+ * Validate component config by schema
+ *
+ * Follows limited examples in JSON schema for wider support in future
+ *
+ * {@link https://ajv.js.org/json-schema.html#compound-keywords}
+ * {@link https://ajv.js.org/packages/ajv-errors.html#single-message}
+ *
+ * @internal
+ * @param {Schema} schema - Config schema
+ * @param {{ [key: string]: unknown }} config - Component config
+ * @returns {string[]} List of validation errors
+ */
+export function validateConfig(schema: Schema, config: {
+    [key: string]: unknown;
+}): string[];
+
+/**
+ * Schema for component config
+ */
+export interface Schema {
+    /**
+     * - Schema properties
+     */
+    properties: {
+        [field: string]: SchemaProperty | undefined;
+    };
+
+    /**
+     * - List of schema conditions
+     */
+    anyOf?: SchemaCondition[] | undefined;
+}
+
+/**
+ * Schema property for component config
+ */
+export interface SchemaProperty {
+    /**
+     * - Property type
+     */
+    type: "string" | "boolean" | "number" | "object";
+}
+
+/**
+ * Schema condition for component config
+ */
+export interface SchemaCondition {
+    /**
+     * - List of required config fields
+     */
+    required: string[];
+
+    /**
+     * - Error message when required config fields not provided
+     */
+    errorMessage: string;
+}
+export type NestedKey = keyof ObjectNested;
+export interface ObjectNested {
+    [key: string]: string | boolean | number | ObjectNested | undefined;
+}

govuk-frontend/dist/govuk/common/normalise-dataset.d.mts

@@ -0,0 +1 @@
+export * from "./normalise-dataset.js";

govuk-frontend/dist/govuk/common/normalise-dataset.d.ts

@@ -0,0 +1,16 @@
+import { type ObjectNested, type Schema } from "./index.js";
+
+/**
+ * Normalise dataset
+ *
+ * Loop over an object and normalise each value using {@link normaliseString},
+ * optionally expanding nested `i18n.field`
+ *
+ * @internal
+ * @param {{ schema: Schema }} Component - Component class
+ * @param {DOMStringMap} dataset - HTML element dataset
+ * @returns {ObjectNested} Normalised dataset
+ */
+export function normaliseDataset(Component: {
+    schema: Schema;
+}, dataset: DOMStringMap): ObjectNested;

govuk-frontend/dist/govuk/common/normalise-string.d.mts

@@ -0,0 +1 @@
+export * from "./normalise-string.js";

govuk-frontend/dist/govuk/common/normalise-string.d.ts

@@ -0,0 +1,22 @@
+import { type SchemaProperty } from "./index.js";
+
+/**
+ * Normalise string
+ *
+ * 'If it looks like a duck, and it quacks like a duck…' 🦆
+ *
+ * If the passed value looks like a boolean or a number, convert it to a boolean
+ * or number.
+ *
+ * Designed to be used to convert config passed via data attributes (which are
+ * always strings) into something sensible.
+ *
+ * @internal
+ * @param {DOMStringMap[string]} value - The value to normalise
+ * @param {SchemaProperty} [property] - Component schema property
+ * @returns {string | boolean | number | undefined} Normalised data
+ */
+export function normaliseString(
+    value: DOMStringMap[string],
+    property?: SchemaProperty,
+): string | boolean | number | undefined;

govuk-frontend/dist/govuk/components/accordion/accordion.d.mts

@@ -0,0 +1 @@
+export * from "./accordion.js";

govuk-frontend/dist/govuk/components/accordion/accordion.d.ts

@@ -0,0 +1,120 @@
+import { GOVUKFrontendComponent } from "../../govuk-frontend-component.js";
+
+/**
+ * Accordion component
+ *
+ * This allows a collection of sections to be collapsed by default, showing only
+ * their headers. Sections can be expanded or collapsed individually by clicking
+ * their headers. A "Show all sections" button is also added to the top of the
+ * accordion, which switches to "Hide all sections" when all the sections are
+ * expanded.
+ *
+ * The state of each section is saved to the DOM via the `aria-expanded`
+ * attribute, which also provides accessibility.
+ */
+export class Accordion extends GOVUKFrontendComponent {
+    /**
+     * Name for the component used when initialising using data-module attributes.
+     */
+    static moduleName: string;
+
+    /**
+     * Accordion default config
+     *
+     * @see {@link AccordionConfig}
+     */
+    static defaults: AccordionConfig;
+
+    /**
+     * Accordion config schema
+     *
+     * @satisfies {Schema}
+     */
+    static schema: Readonly<{
+        properties: {
+            i18n: {
+                type: "object";
+            };
+            rememberExpanded: {
+                type: "boolean";
+            };
+        };
+    }>;
+
+    /**
+     * @param {Element | null} $module - HTML element to use for accordion
+     * @param {AccordionConfig} [config] - Accordion config
+     */
+    constructor($module: Element | null, config?: AccordionConfig);
+
+    /**
+     * Get the identifier for a section
+     *
+     * We need a unique way of identifying each content in the Accordion.
+     * Since an `#id` should be unique and an `id` is required for `aria-`
+     * attributes `id` can be safely used.
+     *
+     * @param {Element} $section - Section element
+     * @returns {string | undefined | null} Identifier for section
+     */
+    getIdentifier($section: Element): string | undefined | null;
+}
+
+/**
+ * Accordion config
+ */
+export interface AccordionConfig {
+    /**
+     * - Accordion translations
+     */
+    i18n?: AccordionTranslations | undefined;
+
+    /**
+     * - Whether the expanded and collapsed
+     * state of each section is remembered and restored when navigating.
+     */
+    rememberExpanded?: boolean | undefined;
+}
+
+/**
+ * Messages used by the component for the labels of its buttons. This includes
+ * the visible text shown on screen, and text to help assistive technology users
+ * for the buttons toggling each section.
+ */
+export interface AccordionTranslations {
+    /**
+     * - The text content for the 'Hide all
+     * sections' button, used when at least one section is expanded.
+     */
+    hideAllSections?: string | undefined;
+
+    /**
+     * - The text content for the 'Hide'
+     * button, used when a section is expanded.
+     */
+    hideSection?: string | undefined;
+
+    /**
+     * - The text content appended to the
+     * 'Hide' button's accessible name when a section is expanded.
+     */
+    hideSectionAriaLabel?: string | undefined;
+
+    /**
+     * - The text content for the 'Show all
+     * sections' button, used when all sections are collapsed.
+     */
+    showAllSections?: string | undefined;
+
+    /**
+     * - The text content for the 'Show'
+     * button, used when a section is collapsed.
+     */
+    showSection?: string | undefined;
+
+    /**
+     * - The text content appended to the
+     * 'Show' button's accessible name when a section is expanded.
+     */
+    showSectionAriaLabel?: string | undefined;
+}

govuk-frontend/dist/govuk/components/button/button.d.mts

@@ -0,0 +1 @@
+export * from "./button.js";

govuk-frontend/dist/govuk/components/button/button.d.ts

@@ -0,0 +1,48 @@
+import { GOVUKFrontendComponent } from "../../govuk-frontend-component.js";
+
+/**
+ * JavaScript enhancements for the Button component
+ */
+export class Button extends GOVUKFrontendComponent {
+    /**
+     * Name for the component used when initialising using data-module attributes.
+     */
+    static moduleName: string;
+
+    /**
+     * Button default config
+     *
+     * @see {@link ButtonConfig}
+     */
+    static defaults: ButtonConfig;
+
+    /**
+     * Button config schema
+     *
+     * @satisfies {Schema}
+     */
+    static schema: Readonly<{
+        properties: {
+            preventDoubleClick: {
+                type: "boolean";
+            };
+        };
+    }>;
+
+    /**
+     * @param {Element | null} $module - HTML element to use for button
+     * @param {ButtonConfig} [config] - Button config
+     */
+    constructor($module: Element | null, config?: ButtonConfig);
+}
+
+/**
+ * Button config
+ */
+export interface ButtonConfig {
+    /**
+     * - Prevent accidental double
+     * clicks on submit buttons from submitting forms multiple times.
+     */
+    preventDoubleClick?: boolean | undefined;
+}

govuk-frontend/dist/govuk/components/character-count/character-count.d.mts

@@ -0,0 +1 @@
+export * from "./character-count.js";

govuk-frontend/dist/govuk/components/character-count/character-count.d.ts

@@ -0,0 +1,158 @@
+import { GOVUKFrontendComponent } from "../../govuk-frontend-component.js";
+import { type TranslationPluralForms } from "../../i18n.js";
+
+/**
+ * Character count component
+ *
+ * Tracks the number of characters or words in the `.govuk-js-character-count`
+ * `<textarea>` inside the element. Displays a message with the remaining number
+ * of characters/words available, or the number of characters/words in excess.
+ *
+ * You can configure the message to only appear after a certain percentage
+ * of the available characters/words has been entered.
+ */
+export class CharacterCount extends GOVUKFrontendComponent {
+    /**
+     * Name for the component used when initialising using data-module attributes.
+     */
+    static moduleName: string;
+
+    /**
+     * Character count default config
+     *
+     * @see {@link CharacterCountConfig}
+     */
+    static defaults: CharacterCountConfig;
+
+    /**
+     * Character count config schema
+     *
+     * @satisfies {Schema}
+     */
+    static schema: Readonly<{
+        properties: {
+            i18n: {
+                type: "object";
+            };
+            maxwords: {
+                type: "number";
+            };
+            maxlength: {
+                type: "number";
+            };
+            threshold: {
+                type: "number";
+            };
+        };
+        anyOf: Array<{
+            required: string[];
+            errorMessage: string;
+        }>;
+    }>;
+
+    /**
+     * @param {Element | null} $module - HTML element to use for character count
+     * @param {CharacterCountConfig} [config] - Character count config
+     */
+    constructor($module: Element | null, config?: CharacterCountConfig);
+}
+
+/**
+ * Character count config
+ */
+export interface CharacterCountConfig {
+    /**
+     * - The maximum number of characters.
+     * If maxwords is provided, the maxlength option will be ignored.
+     */
+    maxlength?: number | undefined;
+
+    /**
+     * - The maximum number of words. If maxwords is
+     * provided, the maxlength option will be ignored.
+     */
+    maxwords?: number | undefined;
+
+    /**
+     * - The percentage value of the limit at
+     * which point the count message is displayed. If this attribute is set, the
+     * count message will be hidden by default.
+     */
+    threshold?: number | undefined;
+
+    /**
+     * - Character count translations
+     */
+    i18n?: CharacterCountTranslations | undefined;
+}
+
+/**
+ * Messages shown to users as they type. It provides feedback on how many words
+ * or characters they have remaining or if they are over the limit. This also
+ * includes a message used as an accessible description for the textarea.
+ */
+export interface CharacterCountTranslations {
+    /**
+     * - Message displayed
+     * when the number of characters is under the configured maximum, `maxlength`.
+     * This message is displayed visually and through assistive technologies. The
+     * component will replace the `%{count}` placeholder with the number of
+     * remaining characters. This is a [pluralised list of
+     * messages](https://frontend.design-system.service.gov.uk/localise-govuk-frontend).
+     */
+    charactersUnderLimit?: TranslationPluralForms | undefined;
+
+    /**
+     * - Message displayed when the number of
+     * characters reaches the configured maximum, `maxlength`. This message is
+     * displayed visually and through assistive technologies.
+     */
+    charactersAtLimit?: string | undefined;
+
+    /**
+     * - Message displayed
+     * when the number of characters is over the configured maximum, `maxlength`.
+     * This message is displayed visually and through assistive technologies. The
+     * component will replace the `%{count}` placeholder with the number of
+     * remaining characters. This is a [pluralised list of
+     * messages](https://frontend.design-system.service.gov.uk/localise-govuk-frontend).
+     */
+    charactersOverLimit?: TranslationPluralForms | undefined;
+
+    /**
+     * - Message displayed when
+     * the number of words is under the configured maximum, `maxlength`. This
+     * message is displayed visually and through assistive technologies. The
+     * component will replace the `%{count}` placeholder with the number of
+     * remaining words. This is a [pluralised list of
+     * messages](https://frontend.design-system.service.gov.uk/localise-govuk-frontend).
+     */
+    wordsUnderLimit?: TranslationPluralForms | undefined;
+
+    /**
+     * - Message displayed when the number of
+     * words reaches the configured maximum, `maxlength`. This message is
+     * displayed visually and through assistive technologies.
+     */
+    wordsAtLimit?: string | undefined;
+
+    /**
+     * - Message displayed when
+     * the number of words is over the configured maximum, `maxlength`. This
+     * message is displayed visually and through assistive technologies. The
+     * component will replace the `%{count}` placeholder with the number of
+     * remaining words. This is a [pluralised list of
+     * messages](https://frontend.design-system.service.gov.uk/localise-govuk-frontend).
+     */
+    wordsOverLimit?: TranslationPluralForms | undefined;
+
+    /**
+     * - Message made
+     * available to assistive technologies, if none is already present in the
+     * HTML, to describe that the component accepts only a limited amount of
+     * content. It is visible on the page when JavaScript is unavailable. The
+     * component will replace the `%{count}` placeholder with the value of the
+     * `maxlength` or `maxwords` parameter.
+     */
+    textareaDescription?: TranslationPluralForms | undefined;
+}

govuk-frontend/dist/govuk/components/checkboxes/checkboxes.d.mts

@@ -0,0 +1 @@
+export * from "./checkboxes.js";