@types/govuk-frontend 5.7.0 → 5.8.0

govuk-frontend/README.md

@@ -8,7 +8,7 @@ This package contains type definitions for govuk-frontend (https://github.com/al
 Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/govuk-frontend.
 
 ### Additional Details
- * Last updated: Mon, 14 Oct 2024 16:41:00 GMT
+ * Last updated: Mon, 03 Feb 2025 16:02:40 GMT
  * Dependencies: none
 
 # Credits

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

@@ -1,3 +1,4 @@
+export { ConfigurableComponent } from "./common/configuration.mjs";
 export { version } from "./common/govuk-frontend-version.mjs";
 export { isSupported } from "./common/index.mjs";
 export { Accordion } from "./components/accordion/accordion.mjs";

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

@@ -1,3 +1,4 @@
+import { ConfigurableComponent } from "./common/configuration.js";
 import { version } from "./common/govuk-frontend-version.js";
 import { isSupported } from "./common/index.js";
 import { Accordion } from "./components/accordion/accordion.js";
@@ -38,6 +39,7 @@ declare const GOVUKFrontend: {
     SkipLink: typeof SkipLink;
     Tabs: typeof Tabs;
     Component: typeof Component;
+    ConfigurableComponent: typeof ConfigurableComponent;
     createAll: typeof createAll;
     initAll: typeof initAll;
 };

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

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

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

@@ -0,0 +1,208 @@
+import { GOVUKFrontendComponent } from "../govuk-frontend-component.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;
+
+/**
+ * Normalise dataset
+ *
+ * Loop over an object and normalise each value using {@link normaliseString},
+ * optionally expanding nested `i18n.field`
+ *
+ * @internal
+ * @param {{ schema?: Schema<ObjectNested>, moduleName: string }} Component - Component class
+ * @param {DOMStringMap} dataset - HTML element dataset
+ * @returns {ObjectNested} Normalised dataset
+ */
+export function normaliseDataset(
+    Component: {
+        schema?: Schema<ObjectNested>;
+        moduleName: string;
+    },
+    dataset: DOMStringMap,
+): ObjectNested;
+
+/**
+ * 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;
+};
+
+/**
+ * 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
+ * @template {Partial<Record<keyof ConfigurationType, unknown>>} ConfigurationType
+ * @param {Schema<ConfigurationType>} schema - The schema of a component
+ * @param {ConfigurationType} config - Component config
+ * @returns {string[]} List of validation errors
+ */
+export function validateConfig<
+    ConfigurationType extends Partial<
+        Record<keyof ConfigurationType, unknown>
+    >,
+>(
+    schema: Schema<ConfigurationType>,
+    config: ConfigurationType,
+): string[];
+
+/**
+ * Extracts keys starting with a particular namespace from dataset ('data-*')
+ * object, removing the namespace in the process, normalising all values
+ *
+ * @internal
+ * @template {Partial<Record<keyof ConfigurationType, unknown>>} ConfigurationType
+ * @param {Schema<ConfigurationType>} schema - The schema of a component
+ * @param {DOMStringMap} dataset - The object to extract key-value pairs from
+ * @param {keyof ConfigurationType} namespace - The namespace to filter keys with
+ * @returns {ObjectNested | undefined} Nested object with dot-separated key namespace removed
+ */
+export function extractConfigByNamespace<
+    ConfigurationType extends Partial<
+        Record<keyof ConfigurationType, unknown>
+    >,
+>(
+    schema: Schema<ConfigurationType>,
+    dataset: DOMStringMap,
+    namespace: keyof ConfigurationType,
+): ObjectNested | undefined;
+
+export const configOverride: unique symbol;
+
+/**
+ * Base Component class
+ *
+ * Centralises the behaviours shared by our components
+ *
+ * @template {Partial<Record<keyof ConfigurationType, unknown>>} [ConfigurationType=ObjectNested]
+ * @template {Element & { dataset: DOMStringMap }} [RootElementType=HTMLElement]
+ */
+export abstract class ConfigurableComponent<
+    ConfigurationType extends Partial<
+        Record<keyof ConfigurationType, unknown>
+    > = ObjectNested,
+    RootElementType extends Element & {
+        dataset: DOMStringMap;
+    } = HTMLElement,
+> extends GOVUKFrontendComponent<RootElementType> {
+    /**
+     * Constructs a new component, validating that GOV.UK Frontend is supported
+     *
+     * @internal
+     * @param {Element | null} [$root] - HTML element to use for component
+     * @param {ConfigurationType} [config] - HTML element to use for component
+     */
+    constructor($root?: Element | null, config?: ConfigurationType);
+
+    /**
+     * Returns the root element of the component
+     *
+     * @returns {ConfigurationType} - the root element of component
+     */
+    protected get config(): ConfigurationType;
+
+    /** */
+    _config: ConfigurationType;
+
+    /**
+     * configOverride
+     *
+     * Function which defines configuration overrides to prioritize
+     * properties from the root element's dataset.
+     *
+     * It should take a subset of configuration as input and return
+     * a new configuration object with properties that should be
+     * overridden based on the root element's dataset. A Symbol
+     * is used for indexing to prevent conflicts.
+     *
+     * @internal
+     * @param {Partial<ConfigurationType>} [param] - Configuration object
+     * @returns {Partial<ConfigurationType>} return - Configuration object
+     */
+    [configOverride](param?: Partial<ConfigurationType>): Partial<ConfigurationType>;
+}
+
+export type NestedKey = keyof ObjectNested;
+
+export interface ObjectNested {
+    [key: string]: string | boolean | number | ObjectNested | undefined;
+}
+
+/**
+ * Schema for component config
+ */
+export interface Schema<
+    ConfigurationType extends Partial<
+        Record<keyof ConfigurationType, unknown>
+    >,
+> {
+    /**
+     * - Schema properties
+     */
+    properties: Record<keyof ConfigurationType, 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;
+}

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

@@ -1,3 +1,5 @@
+import { type ObjectNested } from "./configuration.js";
+
 /**
  * Common helpers which do not require polyfill.
  *
@@ -5,41 +7,6 @@
  * 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
@@ -105,21 +72,18 @@ export function isInitialised($root: Element, moduleName: string): boolean;
 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}
+ * Check for an object
  *
  * @internal
- * @param {Schema} schema - Config schema
- * @param {{ [key: string]: unknown }} config - Component config
- * @returns {string[]} List of validation errors
+ * @template {Partial<Record<keyof ObjectType, unknown>>} [ObjectType=ObjectNested]
+ * @param {unknown | ObjectType} option - Option to check
+ * @returns {option is ObjectType} Whether the option is an object
  */
-export function validateConfig(schema: Schema, config: {
-    [key: string]: unknown;
-}): string[];
+export function isObject<
+    ObjectType extends Partial<Record<keyof ObjectType, unknown>> = ObjectNested,
+>(
+    option: unknown,
+): option is ObjectType;
 
 /**
  * Format error message
@@ -131,54 +95,6 @@ export function validateConfig(schema: Schema, config: {
  */
 export function formatErrorMessage(Component: ComponentWithModuleName, message: string): 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;
-}
-
 export interface ComponentWithModuleName {
     /**
      * - Name of the component

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

@@ -1,4 +1,4 @@
-import { GOVUKFrontendComponent } from "../../govuk-frontend-component.js";
+import { ConfigurableComponent } from "../../common/configuration.js";
 
 /**
  * Accordion component
@@ -12,7 +12,7 @@ import { GOVUKFrontendComponent } from "../../govuk-frontend-component.js";
  * The state of each section is saved to the DOM via the `aria-expanded`
  * attribute, which also provides accessibility.
  */
-export class Accordion extends GOVUKFrontendComponent<HTMLElement> {
+export class Accordion extends ConfigurableComponent<AccordionConfig, HTMLElement> {
     /**
      * Name for the component used when initialising using data-module attributes.
      */

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

@@ -1,9 +1,9 @@
-import { GOVUKFrontendComponent } from "../../govuk-frontend-component.js";
+import { ConfigurableComponent } from "../../common/configuration.js";
 
 /**
  * JavaScript enhancements for the Button component
  */
-export class Button extends GOVUKFrontendComponent<HTMLElement> {
+export class Button extends ConfigurableComponent<ButtonConfig, HTMLElement> {
     /**
      * Name for the component used when initialising using data-module attributes.
      */

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

@@ -1,4 +1,4 @@
-import { GOVUKFrontendComponent } from "../../govuk-frontend-component.js";
+import { configOverride, ConfigurableComponent } from "../../common/configuration.js";
 import { type TranslationPluralForms } from "../../i18n.js";
 
 /**
@@ -11,7 +11,7 @@ import { type TranslationPluralForms } from "../../i18n.js";
  * 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<HTMLElement> {
+export class CharacterCount extends ConfigurableComponent<CharacterCountConfig, HTMLElement> {
     /**
      * Name for the component used when initialising using data-module attributes.
      */
@@ -55,6 +55,19 @@ export class CharacterCount extends GOVUKFrontendComponent<HTMLElement> {
      * @param {CharacterCountConfig} [config] - Character count config
      */
     constructor($root: Element | null, config?: CharacterCountConfig);
+
+    /**
+     * Character count config override
+     *
+     * To ensure data-attributes take complete precedence, even if they change
+     * the type of count, we need to reset the `maxlength` and `maxwords` from
+     * the JavaScript config.
+     *
+     * @internal
+     * @param {CharacterCountConfig} datasetConfig - configuration specified by dataset
+     * @returns {CharacterCountConfig} - configuration to override by dataset
+     */
+    [configOverride](datasetConfig: CharacterCountConfig): CharacterCountConfig;
 }
 
 /**

govuk-frontend/dist/govuk/components/error-summary/error-summary.d.ts

@@ -1,4 +1,4 @@
-import { GOVUKFrontendComponent } from "../../govuk-frontend-component.js";
+import { ConfigurableComponent } from "../../common/configuration.js";
 
 /**
  * Error summary component
@@ -6,7 +6,7 @@ import { GOVUKFrontendComponent } from "../../govuk-frontend-component.js";
  * Takes focus on initialisation for accessible announcement, unless disabled in
  * configuration.
  */
-export class ErrorSummary extends GOVUKFrontendComponent<HTMLElement> {
+export class ErrorSummary extends ConfigurableComponent<ErrorSummaryConfig, HTMLElement> {
     /**
      * Name for the component used when initialising using data-module attributes.
      */

govuk-frontend/dist/govuk/components/exit-this-page/exit-this-page.d.ts

@@ -1,9 +1,9 @@
-import { GOVUKFrontendComponent } from "../../govuk-frontend-component.js";
+import { ConfigurableComponent } from "../../common/configuration.js";
 
 /**
  * Exit this page component
  */
-export class ExitThisPage extends GOVUKFrontendComponent<HTMLElement> {
+export class ExitThisPage extends ConfigurableComponent<ExitThisPageConfig, HTMLElement> {
     /**
      * Name for the component used when initialising using data-module attributes.
      */

govuk-frontend/dist/govuk/components/notification-banner/notification-banner.d.ts

@@ -1,9 +1,9 @@
-import { GOVUKFrontendComponent } from "../../govuk-frontend-component.js";
+import { ConfigurableComponent } from "../../common/configuration.js";
 
 /**
  * Notification Banner component
  */
-export class NotificationBanner extends GOVUKFrontendComponent<HTMLElement> {
+export class NotificationBanner extends ConfigurableComponent<NotificationBannerConfig, HTMLElement> {
     /**
      * Name for the component used when initialising using data-module attributes.
      */

govuk-frontend/dist/govuk/components/password-input/password-input.d.ts

@@ -1,9 +1,9 @@
-import { GOVUKFrontendComponent } from "../../govuk-frontend-component.js";
+import { ConfigurableComponent } from "../../common/configuration.js";
 
 /**
  * Password input component
  */
-export class PasswordInput extends GOVUKFrontendComponent<HTMLElement> {
+export class PasswordInput extends ConfigurableComponent<PasswordInputConfig, HTMLElement> {
     /**
      * Name for the component used when initialising using data-module attributes.
      */

govuk-frontend/dist/govuk/init.d.ts

@@ -8,7 +8,6 @@ import { type PasswordInputConfig } from "./components/password-input/password-i
 
 export interface CompatibleClass {
     new(...args: any[]): any;
-    defaults?: object;
     moduleName: string;
 }
 
@@ -57,7 +56,9 @@ export interface Config {
  */
 export type ConfigKey = keyof Config;
 
-export interface ErrorContext<T extends CompatibleClass> {
+export type ComponentConfig<ComponentClass extends CompatibleClass> = ConstructorParameters<ComponentClass>[1];
+
+export interface ErrorContext<ComponentClass extends CompatibleClass> {
     /**
      * - Element used for component module initialisation
      */
@@ -66,17 +67,20 @@ export interface ErrorContext<T extends CompatibleClass> {
     /**
      * - Class of component
      */
-    component?: T | undefined;
+    component?: ComponentClass | undefined;
 
     /**
      * - Config supplied to component
      */
-    config: T["defaults"];
+    config: ComponentConfig<ComponentClass>;
 }
 
-export type OnErrorCallback<T extends CompatibleClass> = (error: unknown, context: ErrorContext<T>) => any;
+export type OnErrorCallback<ComponentClass extends CompatibleClass> = (
+    error: unknown,
+    context: ErrorContext<ComponentClass>,
+) => any;
 
-export interface CreateAllOptions<T extends CompatibleClass> {
+export interface CreateAllOptions<ComponentClass extends CompatibleClass> {
     /**
      * - scope of the document to search within
      */
@@ -85,7 +89,7 @@ export interface CreateAllOptions<T extends CompatibleClass> {
     /**
      * - callback function if error throw by component on init
      */
-    onError?: OnErrorCallback<T> | undefined;
+    onError?: OnErrorCallback<ComponentClass> | undefined;
 }
 
 /**
@@ -112,14 +116,14 @@ export function initAll(
  *
  * Any component errors will be caught and logged to the console.
  *
- * @template {CompatibleClass} T
- * @param {T} Component - class of the component to create
- * @param {T["defaults"]} [config] - Config supplied to component
- * @param {OnErrorCallback<T> | Element | Document | CreateAllOptions<T> } [createAllOptions] - options for createAll including scope of the document to search within and callback function if error throw by component on init
- * @returns {Array<InstanceType<T>>} - array of instantiated components
+ * @template {CompatibleClass} ComponentClass
+ * @param {ComponentClass} Component - class of the component to create
+ * @param {ComponentConfig<ComponentClass>} [config] - Config supplied to component
+ * @param {OnErrorCallback<ComponentClass> | Element | Document | CreateAllOptions<ComponentClass> } [createAllOptions] - options for createAll including scope of the document to search within and callback function if error throw by component on init
+ * @returns {Array<InstanceType<ComponentClass>>} - array of instantiated components
  */
-export function createAll<T extends CompatibleClass>(
-    Component: T,
-    config?: T["defaults"],
-    createAllOptions?: Document | Element | OnErrorCallback<T> | CreateAllOptions<T>,
-): Array<InstanceType<T>>;
+export function createAll<ComponentClass extends CompatibleClass>(
+    Component: ComponentClass,
+    config?: ComponentConfig<ComponentClass>,
+    createAllOptions?: OnErrorCallback<ComponentClass> | Element | Document | CreateAllOptions<ComponentClass>,
+): Array<InstanceType<ComponentClass>>;

govuk-frontend/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@types/govuk-frontend",
-    "version": "5.7.0",
+    "version": "5.8.0",
     "description": "TypeScript definitions for govuk-frontend",
     "homepage": "https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/govuk-frontend",
     "license": "MIT",
@@ -32,6 +32,7 @@
     },
     "scripts": {},
     "dependencies": {},
-    "typesPublisherContentHash": "08d1cc6a671dadd0e0e9c1113ea085b28a6b2510f52991c817bfb8d71bc308ae",
-    "typeScriptVersion": "4.8"
+    "peerDependencies": {},
+    "typesPublisherContentHash": "3df1d321f714ae24feef605eab0f6302b12f0717613036605b5de394fb136253",
+    "typeScriptVersion": "5.0"
 }

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

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

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

@@ -1,16 +0,0 @@
-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

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

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

@@ -1,22 +0,0 @@
-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;