@sebgroup/green-core 1.0.0-beta.10

package/utils/decorators/index.d.ts

@@ -0,0 +1,2 @@
+export * from './watch';
+export * from './observe-light-dom';

package/utils/decorators/observe-light-dom.d.ts

@@ -0,0 +1,7 @@
+import type { LitElement } from 'lit';
+declare type Handler = () => void;
+/**
+ * Runs when the light DOM children of the component changes.
+ */
+export declare function observeLightDOM(): <ElemClass extends LitElement>(proto: ElemClass, _propertyKey: string, descriptor: TypedPropertyDescriptor<Handler>) => void;
+export {};

package/utils/decorators/watch.d.ts

@@ -0,0 +1,23 @@
+import type { LitElement } from 'lit';
+declare type UpdateHandler = (prev?: unknown, next?: unknown) => void;
+interface WatchOptions {
+    /**
+     * If true, will only start watching after the initial update/render
+     */
+    waitUntilFirstUpdate?: boolean;
+}
+/**
+ * Runs when observed properties change, e.g. @property or @state, but before the component updates. To wait for an
+ * update to complete after a change occurs, use `await this.updateComplete` in the handler. To start watching after the
+ * initial update/render, use `{ waitUntilFirstUpdate: true }` or `this.hasUpdated` in the handler.
+ *
+ * Usage:
+ * ```javascript
+ * \@watch('propName')
+ * handlePropChange(oldValue, newValue) {
+ *   ...
+ * }
+ * ```
+ */
+export declare function watch(propertyName: string | string[], options?: WatchOptions): <ElemClass extends LitElement>(proto: ElemClass, propertyKey: string, descriptor: TypedPropertyDescriptor<UpdateHandler>) => void;
+export {};

package/utils/helpers/constrain-slots.d.ts

@@ -0,0 +1,17 @@
+import { LitElement } from 'lit';
+/**
+ * This function is used to constrain the slots of a component to only allow
+ * certain types of slotted elements. Add the `gds-allow` attribute to the slot
+ * element and specify the allowed elements as a space-separated list. Slots
+ * without the `gds-allow` attribute will not be constrained.
+ *
+ * Example:
+ * ```html
+ * <slot gds-allow="span p"></slot>
+ * ```
+ * This will only allow `span` and `p` elements to be slotted into this slot. Any other
+ * elements will be removed from the shadow DOM.
+ *
+ * @param self The element to apply the slot constraints to
+ */
+export declare function constrainSlots(self: LitElement): void;

package/utils/helpers/custom-element-scoping.d.ts

@@ -0,0 +1,97 @@
+/**
+ * # Custom element scoping
+ *
+ * One problem with the current state of the Custom Elements standard is that there is
+ * only a single, global, `CustomElementRegistry`. This means that if you have two different
+ * libraries, or two different versions of the same library, that both define a custom
+ * element with the same name, only one of them will be registered, and the other will
+ * throw an error.
+ *
+ * This is a problem for Green, because we need it to work well in a microfrontend
+ * architecture, where multiple apps can be loaded on the same page, and each app can
+ * potentially have its own version of Green.
+ *
+ * There is a (proposal)[https://github.com/WICG/webcomponents/blob/gh-pages/proposals/Scoped-Custom-Element-Registries.md]
+ * for enabling user instantiated CustomElementRegistry scoped to a ShodowRoot, but as of
+ * mid 2023 this is still only available in Chrome canary behind experimental flags.
+ *
+ * ## Solution
+ *
+ * To get around the problem we define our own scoping mechanism. It will works like this:
+ *
+ * * Green Core has its own lookup table of custom elements, and a suffix is added to the
+ *   name of each custom element. For example, `gds-popover` becomes `gds-popover-<versionstring>`.
+ *   The version string is deterministically generated based on the version of the Green
+ *   Core package.
+ *
+ * * We also define a new `customElement` decorator that will be used to register custom
+ *   elements. `@gdsCustomElement` will automatically add the version suffix to the name of
+ *   the custom element, and register it in the lookup table. If the custom element is already
+ *   registered, it will abort silently, with the assumption that the custom element was
+ *   already registered by the same version of Green Core and is therefor compatible.
+ *
+ * * There is also a custom `html` template tag that will automatically rewrite all custom
+ *   element names from the lookup table to include the version suffix, before passing the
+ *   template on to the Lit `html` tag. Alternatively, a templte tag factory can be used
+ *   to create a custom `html` tag, if Lit is not used by the consumer
+ *
+ * ## Caveats
+ *
+ * Consumers using top-level components from Green Core will have to add the version suffix
+ * in some way. The React and Angular wrappers takes care of this automatically. Another way
+ * is to use the `html` template tag or template tag factory from Green Core, but it will only
+ * work if the consumer is using javascript template literals.
+ *
+ * If the consumer is using hard coded HTML, or a templating language that does not support
+ * template tags, the consumer will have to manually add the version suffix to the custom
+ * element names, which would be cumbersome. In this edge-case, the scoping feature can be disabled,
+ * and the consumer will have to make sure that only a single version of Green Core is used
+ * on the page.
+ *
+ * The recommendation is to only consume Green Core though the React or Angular wrappers, or to
+ * use the `html` template tag or template tag factory from Green Core.
+ *
+ * At some point in the future, when the scoped custom element registry proposal has been
+ * implemented in all major browsers, we might remove this custom scoping mechanism and
+ * switch to using native scoped registries instead.
+ */
+/**
+ * Class decorator factory that defines the decorated class as a custom element, and registers
+ * it with the custom element registry under a versioned name.
+ *
+ * ```js
+ * @gdsCustomElement('my-element')
+ * class MyElement extends LitElement {
+ *   render() {
+ *     return html``;
+ *   }
+ * }
+ * ```
+ * @category Decorator
+ * @param tagName The tag name of the custom element to define.
+ */
+export declare const gdsCustomElement: (tagName: string) => (classOrDescriptor: {
+    prototype: HTMLElement;
+} | import("@lit/reactive-element/decorators/base").ClassDescriptor) => any;
+/**
+ * Template tag factory that creates a new template tag, which rewrites all custom element names from the
+ * lookup table to include the version suffix, and then passes the template on to the provided template tag.
+ */
+export declare function htmlTemplateTagFactory(extendedTag: (strings: TemplateStringsArray, ...values: any[]) => any): (strings: TemplateStringsArray, ...values: any[]) => any;
+/**
+ * Template tag that rewrites all custom element names from the lookup table to include the
+ * version suffix, before passing the template on to the Lit `html` tag.
+ */
+export declare const html: (strings: TemplateStringsArray, ...values: any[]) => any;
+/**
+ * Returns the correctly scoped tag name for the given tag.
+ * @param tagName The tag name to scope
+ */
+export declare function getScopedTagName(tagName: string): string;
+/**
+ * Returns the unscoped tag name for the given scoped tag.
+ * @param tagName The scoped tag name to unscope
+ */
+export declare function getUnscopedTagName(tagName: string): string | undefined;
+declare const _default: {};
+export default _default;

package/utils/helpers/id.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Generate a random id with `gds-` prefix
+ */
+export declare const randomId: () => string;

package/utils/helpers/index.d.ts

@@ -0,0 +1,2 @@
+export * from './constrain-slots';
+export * from './id';

package/utils/helpers/transitional-styles.d.ts

@@ -0,0 +1,12 @@
+export declare const registerTransitionalStyles: () => void;
+declare global {
+    var __gdsTransitionalStyles: TransitionalStyles;
+}
+export declare class TransitionalStyles {
+    static get instance(): TransitionalStyles;
+    private sheets;
+    private elements;
+    apply(element: HTMLElement, styleKey: string): void;
+    applyToElement(styleKey: string, sheet: CSSStyleSheet): void;
+    register(name: string, styles: string): void;
+}

package/utils/localization.d.ts

@@ -0,0 +1,5 @@
+export declare const getLocale: (() => string) & {
+    _LIT_LOCALIZE_GET_LOCALE_?: undefined;
+}, setLocale: ((newLocale: string) => Promise<void>) & {
+    _LIT_LOCALIZE_SET_LOCALE_?: undefined;
+};

package/utils/testing/index.d.ts

@@ -0,0 +1,30 @@
+/** A testing utility that measures an element's position and clicks on it. */
+export declare function clickOnElement(
+/** The element to click */
+el: Element, 
+/** The location of the element to click */
+position?: 'top' | 'right' | 'bottom' | 'left' | 'center', 
+/** The horizontal offset to apply to the position when clicking */
+offsetX?: number, 
+/** The vertical offset to apply to the position when clicking */
+offsetY?: number): Promise<void>;
+/** A testing utility that moves the mouse onto an element. */
+export declare function moveMouseOnElement(
+/** The element to click */
+el: Element, 
+/** The location of the element to click */
+position?: 'top' | 'right' | 'bottom' | 'left' | 'center', 
+/** The horizontal offset to apply to the position when clicking */
+offsetX?: number, 
+/** The vertical offset to apply to the position when clicking */
+offsetY?: number): Promise<void>;
+/** A testing utility that drags an element with the mouse. */
+export declare function dragElement(
+/** The element to drag */
+el: Element, 
+/** The horizontal distance to drag in pixels */
+deltaX?: number, 
+/** The vertical distance to drag in pixels */
+deltaY?: number): Promise<void>;
+/** A testing utility that waits for a specified amount of time. */
+export declare function timeout(ms: number): Promise<unknown>;