@justeattakeaway/pie-webc-core 21.0.0 → 22.0.1

package/dist/index.d.ts

@@ -0,0 +1,296 @@
+import { LitElement } from 'lit';
+
+/**
+ * Context carrying a `ContextualAria` from a provider down to a consuming component. `undefined`
+ * when no ancestor provides ARIA (for example a standalone control).
+ *
+ * Why a context rather than ARIA props on each component:
+ * - it lets a wrapper name a control it does not own, carrying a resolved string across the shadow
+ *   boundary that `aria-labelledby` / `aria-describedby` IDREFs cannot cross;
+ * - it reaches consumers at any depth below the provider without prop drilling through the layers
+ *   in between;
+ * - it decouples provider from consumer (neither needs a reference to, or knowledge of, the other)
+ *   and is extensible by adding optional fields that consumers opt into.
+ * It is always a fallback behind a control's own ARIA props.
+ */
+export declare const ariaContext: {
+    __context__: ContextualAria | undefined;
+};
+
+/**
+ * An interface representing the structure of a class that has been extended
+ * with the AssociatedLabelMixin.
+ * @interface
+ */
+export declare interface AssociatedLabelInterface {
+    /** The text content of the element's associated `<label>`(s) */
+    readonly associatedLabelText?: string;
+}
+
+/**
+ * A mixin that mirrors the text content of a form-associated custom element's associated
+ * `<label>`(s) onto an `associatedLabelText` property.
+ *
+ * Safari doesn't compute the accessible name of a form-associated
+ * custom element from its associated `<label>` the way others do, so we need to use
+ * `associatedLabelText` as a fallback `aria-label`.
+ * https://bugs.webkit.org/show_bug.cgi?id=259124
+ *
+ *
+ * The class this mixin is applied to must already provide `_internals: ElementInternals`
+ * (for example via `FormControlMixin`), and must call `super.firstUpdated()` if it overrides
+ * `firstUpdated`.
+ *
+ * @param superClass - The LitElement class (with `_internals`) to extend.
+ * @returns A new class extending both the provided LitElement and AssociatedLabelInterface.
+ *
+ * @example
+ * ```typescript
+ * import { html } from 'lit';
+ * import { FormControlMixin, AssociatedLabelMixin } from '@justeattakeaway/pie-webc-core';
+ *
+ * class MyFormElement extends AssociatedLabelMixin(FormControlMixin(LitElement)) {
+ *   render () {
+ *     return html`<input aria-label="${this.associatedLabelText}">`;
+ *   }
+ * }
+ * ```
+ */
+export declare const AssociatedLabelMixin: <T extends GenericConstructor<LitElement & {
+    _internals: ElementInternals;
+}>>(superClass: T) => GenericConstructor<AssociatedLabelInterface> & T;
+
+/**
+ * This type should be used when defining the default props for a component.
+ * It is a generic type that takes two type parameters:
+ * - `T` is the type of the props object that the default props are being defined for.
+ * - `K` is the type of the keys in `T` that should be required in the default props.
+ * By default, `K` is set to be all the keys in `T`. This means that all the keys in `T` will be required in the default props.
+ * You can override this by specifying a subset of the keys in `T` that should be required in the default props.
+ *
+ * @example ```tsx
+ * interface MyComponentProps {
+ *   a: string;
+ *   b?: number;
+ *   c: boolean;
+ * }
+ * const allProps: ComponentDefaultProps<MyComponentProps> = {
+ *   a: 'default value',
+ *   b: 42,
+ *   c: true,
+ * };
+ *
+ * const pickProps: ComponentDefaultProps<MyComponentProps, 'a'> = {
+ *   a: 'default value',
+ * };
+ *
+ * const omitProps: ComponentDefaultProps<MyComponentProps, keyof Omit<MyComponentProps, 'a'>> = {
+ *   b: 42,
+ *   c: true,
+ * };
+ * ```
+ */
+export declare type ComponentDefaultProps<T, K extends keyof T = keyof T> = Readonly<Required<Pick<T, K>>>;
+
+/**
+ * A bag of accessible-name/description values an ancestor component can supply to a descendant
+ * across the shadow boundary (where `aria-labelledby` / `aria-describedby` IDREFs cannot reach).
+ * Restricted to string ARIA that can be applied directly to an element.
+ *
+ * This is deliberately an extensible bag: any provider can set it (for example a `pie-list-item`
+ * stitching its text), and any component can consume it and decide for itself what to do with each
+ * field, applying it to whichever element carries its semantics. Extend it with further optional
+ * string/boolean ARIA as needed; a consumer simply ignores fields it does not apply. There is no
+ * shared "apply" helper on purpose: where and how each field maps is component-specific (a radio
+ * names its host, a checkbox its internal input), so each subscriber owns that logic even if a
+ * little set/remove code is repeated. That keeps the contract open to new ARIA without a central
+ * mapper having to know how every component applies it.
+ */
+export declare interface ContextualAria {
+    label?: string;
+    description?: string;
+}
+
+/**
+ * Mixin to add `delegatesFocus: true` to a LitElement's shadow root options.
+ * This is useful for custom elements that act like form controls, allowing focus
+ * to be automatically delegated to the first focusable element inside the shadow DOM.
+ *
+ * @param superClass - The LitElement class to extend.
+ * @returns A class extending the provided LitElement with the delegatesFocus behaviour.
+ *
+ * @example
+ * ```typescript
+ * import { LitElement, html } from 'lit';
+ * import { DelegatesFocusMixin } from './path-to-DelegatesFocusMixin'; // Update the import path
+ *
+ * // Create a new component using the DelegatesFocusMixin
+ * class MyCustomInput extends DelegatesFocusMixin(LitElement) {
+ *   render() {
+ *     // The focus will automatically go to the input when the component is focused
+ *     return html`<input>`;
+ *   }
+ * }
+ *
+ * customElements.define('my-custom-input', MyCustomInput);
+ * ```
+ */
+export declare const DelegatesFocusMixin: <T extends GenericConstructor<LitElement>>(superClass: T) => T;
+
+/**
+ * Dispatch a custom event.
+ *
+ * To be used whenever we have custom events we want to
+ * bubble up through the component.
+ * Bubbles and composed event props are set to true.
+ * @param {Element} element The element to dispatch the event from.
+ * @param {string} eventType
+ * @param {any} detail
+ */
+export declare function dispatchCustomEvent(element: Element, eventType: string, detail?: CustomEventInit['detail']): void;
+
+/**
+ * Interface for FormControl behavior.
+ */
+export declare interface FormControlInterface {
+    _internals: ElementInternals;
+    get form(): HTMLFormElement | null;
+}
+
+/**
+ * Mixin to add form control behaviors to a LitElement.
+ * This mixin adds properties and methods to handle form-associated custom elements.
+ *
+ * @param superClass - The LitElement class to extend with form control functionality.
+ * @returns A class extending both the provided LitElement and _FormControlInterface.
+ *
+ * @example
+ * ```typescript
+ * import { LitElement, html } from 'lit';
+ * import { FormControlMixin } from './path-to-FormControlMixin'; // Update the import path
+ *
+ * // Create a new component using the FormControlMixin
+ * class MyFormElement extends FormControlMixin(LitElement) {
+ *   render() {
+ *     return html`<div>Form-associated element with form: ${this.form ? 'attached' : 'detached'}</div>`;
+ *   }
+ * }
+ *
+ * customElements.define('my-form-element', MyFormElement);
+ * ```
+ */
+export declare const FormControlMixin: <T extends GenericConstructor<LitElement>>(superClass: T) => GenericConstructor<FormControlInterface> & T;
+
+/**
+ * A type representing a constructor of any class.
+ * @typedef {new (...args: any[]) => T} Constructor
+ * @template T
+ */
+export declare type GenericConstructor<T> = new (...args: any[]) => T;
+
+/**
+ * Detects whether the current browser is Safari.
+ */
+export declare function isSafari(): boolean;
+
+/**
+ * Context a container uses to tell its descendants it is disabled, so they can reflect it (for
+ * example a disabled `pie-radio-group` / `pie-checkbox-group` suppressing a `pie-list-item`'s
+ * interactive hover and active states). Defaults to `false` when no ancestor provides it.
+ *
+ * This is deliberately generic: any disabling ancestor can provide it and any descendant can
+ * consume it. Like `ariaContext`, it crosses shadow boundaries and reaches descendants at any depth
+ * without prop drilling, and decouples the provider from the consumer.
+ */
+export declare const parentDisabledContext: {
+    __context__: boolean;
+};
+
+export declare interface PIEInputElement {
+    focusTarget: HTMLElement;
+}
+
+/**
+ * An interface representing the structure of RTL related class.
+ * @interface
+ */
+export declare interface RTLInterface {
+    /** A boolean indicating whether the text direction is right-to-left. */
+    isRTL: boolean;
+}
+
+/**
+ * A mixin to extend LitElement with right-to-left (RTL) text direction handling.
+ * This mixin adds a read-only `isRTL` property to the class it's applied to,
+ * allowing you to easily determine the text direction within your component.
+ *
+ * @function
+ * @param {GenericConstructor<LitElement>} superClass - The LitElement class to extend with RTL functionality.
+ * @returns {GenericConstructor<RTLInterface> & T} - A new class extending both LitElement and RTLInterface.
+ *
+ * @example
+ * ```typescript
+ * import { LitElement, html } from 'lit';
+ * import { RtlMixin } from './RtlMixin'; // Adjust the import path as needed
+ *
+ * class MyElement extends RtlMixin(LitElement) {
+ *   render() {
+ *     return html`<p>Text direction is ${this.isRTL ? 'right-to-left' : 'left-to-right'}</p>`;
+ *   }
+ * }
+ *
+ * customElements.define('my-element', MyElement);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { LitElement, html } from 'lit';
+ * import { RtlMixin } from './RtlMixin'; // Adjust the import path as needed
+ *
+ * class MyStyledElement extends RtlMixin(LitElement) {
+ *   render() {
+ *     return html`<div class="foo" ?data-is-rtl=${this.isRTL}>Content</div>`;
+ *   }
+ * }
+ *
+ * customElements.define('my-styled-element', MyStyledElement);
+ * ```
+ *
+ * The corresponding SCSS to leverage the `data-is-rtl` attribute:
+ * ```scss
+ * .foo[data-is-rtl] {
+ *   background-color: red;
+ *   text-align: right;
+ * }
+ * ```
+ */
+export declare const RtlMixin: <T extends GenericConstructor<LitElement>>(superClass: T) => GenericConstructor<RTLInterface> & T;
+
+/**
+ * Custom decorator that wraps Lit's customElement decorator with error handling.
+ * Logs a warning if the custom element has already been defined, including version info of the already registered component if available.
+ *
+ * @param {string} elementSelector - Custom element tag name.
+ * @returns {ClassDecorator}
+ */
+export declare function safeCustomElement(elementSelector: string): ClassDecorator;
+
+/**
+ * A decorator for specifying a list of valid values for a property.
+ * If this property's setter is called with an invalid value, an error is logged and the default value will be assigned instead.
+ * @param validValues - The array of valid values
+ * @param defaultValue - The value to fall back on
+ * @returns  - The decorator function
+ */
+export declare const validPropertyValues: <T>(componentName: string, validValues: readonly T[], defaultValue: T) => (target: object, propertyKey: string) => void;
+
+/**
+ * Wraps the native event in a custom event. This is useful for native events that have `composed` set to `false`
+ * as these cannot propagate outside of the shadow DOM.
+ * @param event - The native event.
+ */
+export declare function wrapNativeEvent(event: Event): CustomEvent<{
+    sourceEvent: Event;
+}>;
+
+export { }

package/dist/internals.d.ts

@@ -0,0 +1,8 @@
+import { LitElement } from 'lit';
+
+export declare class PieElement extends LitElement {
+    static readonly v: string;
+    protected willUpdate(): void;
+}
+
+export { }

package/dist/internals.js

@@ -0,0 +1,11 @@
+import { LitElement as s } from "lit";
+const t = class t extends s {
+  willUpdate() {
+    this.getAttribute("v") || this.setAttribute("v", t.v);
+  }
+};
+t.v = "22.0.1";
+let i = t;
+export {
+  i as PieElement
+};

package/package.json

@@ -1,9 +1,21 @@
 {
   "name": "@justeattakeaway/pie-webc-core",
-  "version": "21.0.0",
+  "version": "22.0.1",
   "description": "PIE design system base classes, mixins and utilities for web components",
   "type": "module",
   "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "src/internals/PieElement": [
+        "dist/internals.d.ts"
+      ],
+      "src/internals/PieElement.js": [
+        "dist/internals.d.ts"
+      ]
+    }
+  },
   "author": "Just Eat Takeaway.com - Design System Team",
   "license": "Apache-2.0",
   "files": [
@@ -13,12 +25,16 @@
     "src/interfaces",
     "src/mixins",
     "src/types",
-    "index.ts"
+    "src/index.ts",
+    "index.ts",
+    "dist",
+    "**/*.d.ts"
   ],
   "scripts": {
     "build": "run -T vite build",
     "lint:scripts": "run -T eslint .",
     "lint:scripts:fix": "run -T eslint . --fix",
+    "watch": "run -T vite build --watch",
     "test": "run -T vitest run --config ../../../vite.config.js",
     "test:ci": "yarn test",
     "test:browsers": "run -T playwright test -c ./playwright-lit.config.ts",
@@ -33,6 +49,7 @@
     "@justeattakeaway/pie-css": "1.x"
   },
   "devDependencies": {
-    "@justeattakeaway/pie-components-config": "0.21.4"
+    "@justeattakeaway/pie-components-config": "0.21.5",
+    "@justeattakeaway/pie-monorepo-utils": "0.9.11"
   }
 }