@ministryofjustice/frontend-types 1.0.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Change log
+
+## 1.0.0-alpha.1
+
+Adding manually-created ambient modules defining the exported items of:
+- GOV.UK frontend 5.14.0
+- MoJ frontend 8.0.1
+- Accessible Autocomplete 3.0.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crown Copyright (Ministry of Justice)
+
+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.

package/README.md

@@ -0,0 +1,57 @@
+# @ministryofjustice/frontend-types
+
+Provides typescript definitions as ambient modules for these client-side libraries/components:
+
+- [GOV.UK frontend](https://design-system.service.gov.uk)
+- [MoJ frontend](https://design-patterns.service.justice.gov.uk)
+- [Accessible Autocomplete](https://github.com/alphagov/accessible-autocomplete)
+
+## Status
+
+**This library is currently: ready to trial.**
+Teams are welcome to trial this library. Please provide feedback via slack to the `#typescript` channel.
+
+## Usage
+
+Usage will be best demonstrated by the [HMPPS typescript template](https://github.com/ministryofjustice/hmpps-template-typescript)
+once this package is published and [incorporated](https://github.com/ministryofjustice/hmpps-template-typescript/pull/681).
+
+Note the `tsconfig.json` in the /assets/js folder, particularly the `lib` and `typeRoots` properties.
+
+```typescript
+import * as govukFrontend from 'govuk-frontend'
+import * as mojFrontend from '@ministryofjustice/frontend'
+
+govukFrontend.initAll()
+mojFrontend.initAll()
+
+class MyPrintButton extends govukFrontend.Component {
+  static moduleName = 'my-print-btn'
+
+  constructor(root: HTMLElement) {
+    super(root)
+    root.addEventListener('click', event => {
+      event.preventDefault()
+      window.print()
+    })
+  }
+}
+
+govukFrontend.createAll(MyPrintLink)
+```
+
+```html
+<a href="#" data-module="my-print-link">Print</a>
+```
+
+## Developing this package
+
+Type definitions in the `src/@types` folder must be ambient typescript modules. All of these are concatenated into
+one file during build; sources and tests are not included.
+
+When adding or updating type defitions, the target version or version ranges should be updated
+in the `peerDependencies` property in package.json. These peer dependencies should be marked as optional so that
+client projects aren’t required to install them.
+
+The `devDependencies` property should contain a precise version
+(which is compatible with the peer dependency version ranges) so that this package can be tested in isolation.

package/dist/index.d.ts

@@ -0,0 +1,242 @@
+/**
+ * GOV.UK Accessible Autocomplete types based on v3.0.1
+ * https://github.com/alphagov/accessible-autocomplete
+ *
+ * NB: this was recreated manually from javascript sources and may be incomplete!
+ */
+
+declare module 'accessible-autocomplete' {
+  type Source =
+    | string[]
+    | {
+        (query: string, populateResults: (options: string[]) => void): void
+      }
+
+  interface Options {
+    element: HTMLElement
+    id: string
+    source: Source
+    inputClasses?: string | null
+    hintClasses?: string | null
+    menuAttributes?: DOMStringMap
+    menuClasses?: string | null
+    autoselect?: boolean
+    confirmOnBlur?: boolean
+    cssNamespace?: string
+    defaultValue?: string
+    displayMenu?: 'inline' | 'overlay'
+    minLength?: number
+    name?: string
+    onConfirm?: (confirmed: string) => void
+    placeholder?: string
+    required?: boolean
+    showAllValues?: boolean
+    showNoOptionsFound?: boolean
+    templates?: {
+      inputValue: (input: string) => string
+      suggestion: (input: string) => string
+    }
+    dropdownArrow?: (obj: { className: string }) => string
+    tNoResults?: () => string
+    tStatusQueryTooShort?: (chars: number) => string
+    tStatusNoResults?: () => string
+    tStatusSelectedOption?: (selectedOption: string, length: number, index: number) => string
+    tStatusResults?: (length: number, contentSelectedOption: string) => string
+    tAssistiveHint?: () => string
+  }
+
+  interface EnhanceSelectOptions extends Omit<Partial<Options>, 'element'> {
+    selectElement: HTMLElement
+    preserveNullOptions?: boolean
+  }
+
+  interface AccessibleAutocomplete {
+    (options: Options): void
+
+    enhanceSelectElement(options: EnhanceSelectOptions): void
+  }
+
+  const accessibleAutocomplete: AccessibleAutocomplete
+
+  export default accessibleAutocomplete
+}
+/**
+ * GOV.UK Frontend types based on v5.14.0
+ * https://github.com/alphagov/govuk-frontend
+ *
+ * NB: this was recreated manually from javascript sources and may be incomplete!
+ */
+
+// eslint-disable-next-line max-classes-per-file
+declare module 'govuk-frontend' {
+  /** @since 5.7.0 */
+  export abstract class Component<RootElement extends HTMLElement = HTMLElement> {
+    static checkSupport(): void
+
+    static moduleName: string
+
+    // technically `typeof RootElement`, but static properties cannot refer to generic parameters
+    static elementType: typeof HTMLElement
+
+    constructor($root: RootElement)
+
+    /** Returns the root element of the component */
+    get $root(): RootElement
+
+    checkInitialised(): void
+  }
+
+  const configOverride: unique symbol
+
+  interface SchemaProperty {
+    type: 'string' | 'boolean' | 'number' | 'object'
+  }
+
+  interface Schema {
+    properties: Record<string, SchemaProperty | undefined>
+    anyOf?: { required: string[]; errorMessage: string }[]
+  }
+
+  type ObjectNested = {
+    [key: string]: string | boolean | number | ObjectNested | undefined
+  }
+
+  /** @since 5.8.0 */
+  export abstract class ConfigurableComponent<
+    RootElement extends HTMLElement = HTMLElement,
+    Config = Record<string, string | boolean | number>,
+  > extends Component<RootElement> {
+    // technically types of `schema` and `defaults` should be strongly tied to `Config`,
+    // but static properties cannot refer to generic parameters
+    static schema: Schema
+
+    static defaults: ObjectNested
+
+    constructor($root: RootElement, config: Config)
+
+    [configOverride](datasetConfig: Partial<Config>): object
+
+    get config(): Config
+  }
+
+  /** @since 5.0.0 */
+  export class Accordion extends ConfigurableComponent {}
+  /** @since 5.0.0 */
+  export class Button extends ConfigurableComponent {}
+  /** @since 5.0.0 */
+  export class CharacterCount extends ConfigurableComponent {}
+  /** @since 5.0.0 */
+  export class Checkboxes extends Component {}
+  /** @since 5.0.0 */
+  export class ErrorSummary extends ConfigurableComponent {}
+  /** @since 5.0.0 */
+  export class ExitThisPage extends ConfigurableComponent {}
+  /** @since 5.9.0 */
+  export class FileUpload extends ConfigurableComponent {}
+  /**
+   * NB: removed in 6.0.0
+   * @since 5.0.0
+   */
+  export class Header extends Component {}
+  /** @since 5.0.0 */
+  export class NotificationBanner extends ConfigurableComponent {}
+  /** @since 5.3.0 */
+  export class PasswordInput extends ConfigurableComponent {}
+  /** @since 5.0.0 */
+  export class Radios extends Component {}
+  /** @since 5.6.0 */
+  export class ServiceNavigation extends Component {}
+  /** @since 5.0.0 */
+  export class SkipLink extends Component<HTMLAnchorElement> {}
+  /** @since 5.0.0 */
+  export class Tabs extends Component {}
+
+  /**
+   * 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.
+   *
+   * @since 5.7.0
+   */
+  export function isSupported(scope?: HTMLElement): boolean
+
+  interface ErrorContext {
+    config: Record<string, string | boolean | number>
+    component?: Component
+    element?: HTMLElement
+  }
+
+  interface ErrorCallback {
+    onError: (error: Error, context: ErrorContext) => void
+  }
+
+  interface InitAllOptions {
+    scope?: HTMLElement | Document
+    /** @since 5.7.0 */
+    onError?: ErrorCallback
+  }
+
+  /**
+   * Initialise all components
+   *
+   * Use the `data-module` attributes to find, instantiate and init all of the
+   * components provided as part of GOV.UK Frontend.
+   *
+   * @since 5.0.0
+   */
+  export function initAll(config?: InitAllOptions): void
+
+  type CreateAllOptions = InitAllOptions | HTMLElement | Document | ErrorCallback
+
+  /**
+   * Create all instances of a specific component on the page
+   *
+   * Uses the `data-module` attribute to find all elements matching the specified
+   * component on the page, creating instances of the component object for each
+   * of them.
+   *
+   * Any component errors will be caught and logged to the console.
+   *
+   * @since 5.4.0
+   */
+  export function createAll<
+    E extends HTMLElement,
+    C extends Component<E>,
+    Class extends { new (element: never, config: never): C },
+  >(component: Class, config?: ConstructorParameters<Class>[1]): void
+
+  /** @since 5.0.0 */
+  export const version: string
+}
+/**
+ * MoJ Frontend types based on v8.0.1
+ * https://github.com/ministryofjustice/moj-frontend
+ *
+ * NB: this was recreated manually from javascript sources and may be incomplete!
+ */
+
+// eslint-disable-next-line max-classes-per-file
+declare module '@ministryofjustice/frontend' {
+  import type { Component, ConfigurableComponent, CreateAllOptions } from 'govuk-frontend'
+
+  export function initAll(scopeOrConfig?: CreateAllOptions): void
+
+  export class AddAnother extends Component {}
+  export class Alert extends ConfigurableComponent {}
+  export class ButtonMenu extends ConfigurableComponent {}
+  export class DatePicker extends ConfigurableComponent {}
+  export class MultiSelect extends ConfigurableComponent {}
+  export class PasswordReveal extends Component {}
+  export class PdsHeader extends Component {}
+  export class RichTextEditor extends ConfigurableComponent {}
+  export class SearchToggle extends ConfigurableComponent {}
+  export class SortableTable extends ConfigurableComponent {}
+
+  // these components don’t seem to get initialised by initAll
+  export class FilterToggleButton extends ConfigurableComponent {}
+  export class FormValidator extends ConfigurableComponent {}
+  export class MultiFileUpload extends ConfigurableComponent {}
+
+  export const version: string
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ministryofjustice/frontend-types",
+  "version": "1.0.0-alpha.1",
+  "description": "",
+  "author": "hmpps-developers",
+  "license": "MIT",
+  "homepage": "https://github.com/ministryofjustice/hmpps-typescript-lib#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ministryofjustice/hmpps-typescript-lib.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "main": "",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "*.md",
+    "dist/**/*"
+  ],
+  "engines": {
+    "node": "20 || 22 || 24"
+  },
+  "scripts": {
+    "build": "mkdir -p ./dist && cat ./src/@types/*.d.ts > ./dist/index.d.ts",
+    "clean": "rm -rf ./dist/",
+    "test": "tsc",
+    "lint": "eslint src --cache --max-warnings 0",
+    "lint-fix": "eslint src --cache --max-warnings 0 --fix",
+    "check-for-updates": "npx npm-check-updates -u"
+  },
+  "devDependencies": {
+    "@ministryofjustice/frontend": "8.0.1",
+    "accessible-autocomplete": "3.0.1",
+    "govuk-frontend": "5.14.0"
+  },
+  "peerDependencies": {
+    "@ministryofjustice/frontend": "6 || 7 || 8 || 9",
+    "accessible-autocomplete": "3",
+    "govuk-frontend": "5 || 6.0.x"
+  },
+  "peerDependenciesMeta": {
+    "@ministryofjustice/frontend": {
+      "optional": true
+    },
+    "accessible-autocomplete": {
+      "optional": true
+    },
+    "govuk-frontend": {
+      "optional": true
+    }
+  }
+}