@pine-ds/core 3.26.4 → 3.28.0

package/dist/types/i18n/i18n-format.d.ts

@@ -0,0 +1,38 @@
+export type I18nVars = Record<string, string | number>;
+export type PluralForms = Partial<Record<Intl.LDMLPluralRule, string>>;
+/**
+ * i18n formatting helpers for Pine components.
+ *
+ * Pine stays string-agnostic: user-facing text is supplied by the consumer as
+ * props (English-defaulted). These helpers only handle the two things a prop
+ * value can't express on its own — interpolating live component state into a
+ * translated template, and picking the right plural form. No stored strings, no
+ * locale registry; the locale is read from the DOM (`lang`), the web-standard
+ * signal a consumer already sets.
+ *
+ * Two limitations of DOM-`lang` locale resolution, both inherent to inferring
+ * locale from the DOM rather than being told it:
+ *
+ * 1. Not reactive. `resolveLocale` is read during render; Stencil has no
+ *    reactive dependency on a DOM attribute, so changing `lang` at runtime
+ *    (`document.documentElement.lang = 'pl'`) does NOT re-render mounted
+ *    components — the plural form stays stale until unrelated state forces a
+ *    render. Fine when locale changes via full-page navigation; a consumer that
+ *    switches locale client-side should pass the already-formatted/pluralized
+ *    string as the prop instead.
+ * 2. Does not cross shadow boundaries. `el.closest('[lang]')` stops at the host's
+ *    shadow root. A Pine component nested inside another custom element whose
+ *    `lang` sits on that outer host will not see it and falls back to
+ *    `document.documentElement.lang`. Set `lang` on (or above) the Pine element
+ *    in the same tree, or pass a pre-formatted string, when that matters.
+ */
+/** Replace `{token}` placeholders with `vars`; unknown tokens stay literal. */
+export declare function formatMessage(template: string, vars?: I18nVars): string;
+/** Nearest `[lang]` ancestor, then `<html lang>`, then `'en'`. */
+export declare function resolveLocale(el?: Element | null): string;
+/**
+ * Pick the CLDR plural form for `count` in the element's locale (via the
+ * platform `Intl.PluralRules`) and interpolate `{count}`. `forms` come from the
+ * caller — component props, English-defaulted — and fall back to `other`.
+ */
+export declare function pluralize(el: Element | null, count: number, forms: PluralForms, vars?: I18nVars): string;

package/dist/types/i18n/index.d.ts

@@ -0,0 +1,2 @@
+export { formatMessage, pluralize, resolveLocale } from './i18n-format';
+export type { I18nVars, PluralForms } from './i18n-format';

package/dist/types/stencil-public-runtime.d.ts

@@ -63,6 +63,12 @@ export interface ShadowRootOptions {
      * focusable part is given focus, and the shadow host is given any available `:focus` styling.
      */
     delegatesFocus?: boolean;
+    /**
+     * Sets the slot assignment mode for the shadow root. When set to `'manual'`, enables imperative
+     * slotting using the `HTMLSlotElement.assign()` method. Defaults to `'named'` for standard
+     * declarative slotting behavior.
+     */
+    slotAssignment?: 'manual' | 'named';
 }
 export interface ModeStyles {
     [modeName: string]: string | string[];
@@ -119,12 +125,34 @@ export interface EventOptions {
      */
     composed?: boolean;
 }
+export interface AttachInternalsOptions {
+    /**
+     * Initial custom states to set on the ElementInternals.states CustomStateSet.
+     * Each key is the state name and the value is the initial boolean state.
+     *
+     * These states can be targeted with the CSS `:state()` pseudo-class.
+     *
+     * @example
+     * ```tsx
+     * @AttachInternals({ states: { open: true, active: false } })
+     * internals: ElementInternals;
+     * ```
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet
+     */
+    states?: {
+        [stateName: string]: boolean;
+    };
+}
 export interface AttachInternalsDecorator {
-    (): PropertyDecorator;
+    (opts?: AttachInternalsOptions): PropertyDecorator;
 }
 export interface ListenDecorator {
     (eventName: string, opts?: ListenOptions): CustomMethodDecorator<any>;
 }
+export interface ResolveVarFunction {
+    <T>(variable: T): string;
+}
 export interface ListenOptions {
     /**
      * Handlers can also be registered for an event other than the host itself.
@@ -153,7 +181,9 @@ export interface StateDecorator {
     (): PropertyDecorator;
 }
 export interface WatchDecorator {
-    (propName: any): CustomMethodDecorator<(newValue?: any, oldValue?: any, propName?: any, ...args: any[]) => any | void>;
+    (propName: any, watchOptions?: {
+        immediate?: boolean;
+    }): CustomMethodDecorator<(newValue?: any, oldValue?: any, propName?: any, ...args: any[]) => any | void>;
 }
 export interface PropSerializeDecorator {
     (propName: any): CustomMethodDecorator<(newValue?: any, propName?: string, ...args: any[]) => string | null>;
@@ -208,6 +238,24 @@ export declare const AttachInternals: AttachInternalsDecorator;
  * https://stenciljs.com/docs/events#listen-decorator
  */
 export declare const Listen: ListenDecorator;
+/**
+ * The `resolveVar()` function is a compile-time utility that resolves const variables
+ * and object properties to their string literal values. This allows variables to be
+ * used in `@Listen` and `@Event` decorators instead of hardcoded strings.
+ *
+ * @example
+ * ```ts
+ * const MY_EVENT = 'myEvent';
+ * @Listen(resolveVar(MY_EVENT))
+ * ```
+ *
+ * @example
+ * ```ts
+ * const EVENTS = { MY_EVENT: 'myEvent' } as const;
+ * @Event({ eventName: resolveVar(EVENTS.MY_EVENT) })
+ * ```
+ */
+export declare const resolveVar: ResolveVarFunction;
 /**
  * The `@Method()` decorator is used to expose methods on the public API.
  * Class methods decorated with the @Method() decorator can be called directly
@@ -365,6 +413,27 @@ export declare function readTask(task: RafCallback): void;
  * Unhandled exception raised while rendering, during event handling, or lifecycles will trigger the custom event handler.
  */
 export declare const setErrorHandler: (handler: ErrorHandler) => void;
+export type TagTransformer = (tag: string) => string;
+/**
+ * Sets a tag transformer to be used when rendering your custom elements.
+ * ```ts
+ * setTagTransformer((tag) => {
+ *  if (tag.startsWith('my-')) return `new-${tag}`
+ *  return tag;
+ * });
+ * ```
+ * Will mean all your components that start with `my-` are defined instead with `new-my-` prefix.
+ *
+ * @param transformer the transformer function to use which must return a string.
+ */
+export declare function setTagTransformer(transformer: TagTransformer): void;
+/**
+ * Transforms a tag name using a transformer set via `setTagTransformer`
+ *
+ * @param tag - the tag to transform e.g. `my-tag`
+ * @returns the transformed tag e.g. `new-my-tag`
+ */
+export declare function transformTag(tag: string): string;
 /**
  * @deprecated - Use `MixedInCtor` instead:
  * ```ts
@@ -568,7 +637,7 @@ export interface FunctionalUtilities {
     map: (children: VNode[], cb: (vnode: ChildNode, index: number, array: ChildNode[]) => ChildNode) => VNode[];
 }
 export interface FunctionalComponent<T = {}> {
-    (props: T, children: VNode[], utils: FunctionalUtilities): VNode | VNode[];
+    (props: T, children: VNode[], utils: FunctionalUtilities): VNode | VNode[] | null;
 }
 /**
  * A Child VDOM node
@@ -610,6 +679,7 @@ export declare namespace h {
     function h(sel: any, data: VNodeData | null, text: string): VNode;
     function h(sel: any, data: VNodeData | null, children: Array<VNode | undefined | null>): VNode;
     function h(sel: any, data: VNodeData | null, children: VNode): VNode;
+    function h(sel: any, data: VNodeData | null, ...children: (VNode | string | number)[]): VNode;
     namespace JSX {
         interface IntrinsicElements extends LocalJSX.IntrinsicElements, JSXBase.IntrinsicElements {
             [tagName: string]: any;
@@ -624,6 +694,36 @@ export declare function h(sel: any, children: Array<VNode | undefined | null>):
 export declare function h(sel: any, data: VNodeData | null, text: string): VNode;
 export declare function h(sel: any, data: VNodeData | null, children: Array<VNode | undefined | null>): VNode;
 export declare function h(sel: any, data: VNodeData | null, children: VNode): VNode;
+export declare function h(sel: any, data: VNodeData | null, ...children: (VNode | string | number)[]): VNode;
+/**
+ * Automatic JSX runtime functions for TypeScript's react-jsx mode.
+ * These functions are called automatically by TypeScript when using "jsx": "react-jsx".
+ * @param type type of node
+ * @param props properties of node
+ * @param key optional key for the node
+ * @returns a jsx vnode
+ */
+export declare function jsx(type: any, props: any, key?: string): VNode;
+/**
+ * Automatic JSX runtime functions for TypeScript's react-jsxmode with multiple children.
+ * @param type type of node
+ * @param props properties of node
+ * @param key optional key for the node
+ * @returns a jsx vnode
+ */
+export declare function jsxs(type: any, props: any, key?: string): VNode;
+/**
+ * Automatic JSX runtime functions for TypeScript's react-jsxdev mode.
+ * These functions are called automatically by TypeScript when using "jsx": "react-jsxdev".
+ * @param type type of node
+ * @param props properties of node
+ * @param key optional key for the node
+ * @param isStaticChildren indicates if the children are static
+ * @param source source information
+ * @param self reference to the component instance
+ * @returns a jsx vnode
+ */
+export declare function jsxDEV(type: any, props: any, key?: string | number, isStaticChildren?: boolean, source?: any, self?: any): VNode;
 /**
  * A virtual DOM node
  */
@@ -653,7 +753,7 @@ declare namespace LocalJSX {
 export { LocalJSX as JSX };
 export declare namespace JSXBase {
     interface IntrinsicElements {
-        slot: JSXBase.SlotAttributes;
+        slot: JSXBase.SlotAttributes<HTMLSlotElement>;
         a: JSXBase.AnchorHTMLAttributes<HTMLAnchorElement>;
         abbr: JSXBase.HTMLAttributes;
         address: JSXBase.HTMLAttributes;
@@ -823,7 +923,7 @@ export declare namespace JSXBase {
         use: JSXBase.SVGAttributes;
         view: JSXBase.SVGAttributes;
     }
-    interface SlotAttributes extends JSXAttributes {
+    interface SlotAttributes<T = HTMLSlotElement> extends JSXAttributes<T> {
         name?: string;
         slot?: string;
         onSlotchange?: (event: Event) => void;
@@ -879,6 +979,9 @@ export declare namespace JSXBase {
         popoverTargetAction?: string;
         popoverTargetElement?: Element | null;
         popoverTarget?: string;
+        command?: string;
+        commandFor?: string;
+        commandfor?: string;
     }
     interface CanvasHTMLAttributes<T> extends HTMLAttributes<T> {
         height?: number | string;
@@ -967,6 +1070,7 @@ export declare namespace JSXBase {
         importance?: 'low' | 'auto' | 'high';
         height?: number | string;
         loading?: 'lazy' | 'auto' | 'eager';
+        referrerPolicy?: ReferrerPolicy;
         sizes?: string;
         src?: string;
         srcSet?: string;
@@ -1747,6 +1851,7 @@ export interface CustomElementsDefineOptions {
     exclude?: string[];
     resourcesUrl?: string;
     syncQueue?: boolean;
+    /** @deprecated in-favour of `setTagTransformer` and `transformTag` */
     transformTagName?: (tagName: string) => string;
     jmp?: (c: Function) => any;
     raf?: (c: FrameRequestCallback) => number;

package/dist/types/utils/test/axe.d.ts

@@ -38,9 +38,10 @@ export interface RunAxeOptions {
 export declare const DEFAULT_AXE_TAGS: readonly ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"];
 /**
  * Page-level axe rules that fire on the bare HTML harness Stencil's E2E
- * provides (no `<title>`, no `<html lang>`, no landmarks, no `<h1>`).
- * They are disabled by default because they describe document chrome,
- * not component behavior — flagging them at component scope yields noise.
+ * provides (no `<title>`, no `<html lang>`, no landmarks, no `<h1>`, and
+ * often without the full theme/global stylesheet).
+ * They are disabled by default because they describe document chrome or
+ * need themed context — flagging them at component scope yields noise or flakes.
  *
  * Tests can opt back in for a specific case:
  *
@@ -48,7 +49,7 @@ export declare const DEFAULT_AXE_TAGS: readonly ["wcag2a", "wcag2aa", "wcag21a",
  * await runAxe(page, { rules: { 'document-title': { enabled: true } } });
  * ```
  */
-export declare const DEFAULT_DISABLED_RULES: readonly ["document-title", "html-has-lang", "landmark-one-main", "page-has-heading-one", "region"];
+export declare const DEFAULT_DISABLED_RULES: readonly ["document-title", "html-has-lang", "landmark-one-main", "page-has-heading-one", "region", "color-contrast"];
 /**
  * Injects axe-core into an active Stencil E2EPage and returns any
  * accessibility violations found in the current document.

package/dist/types/utils/types.d.ts

@@ -5,3 +5,5 @@ export type BoxShadowSizeType = 'none' | '050' | '100' | '150' | '200' | '300' |
 export type ChipSentimentType = 'accent' | 'brand' | 'danger' | 'info' | 'neutral' | 'success' | 'warning';
 export type ChipSizeType = 'sm' | 'md' | 'lg';
 export type ChipVariantType = 'text' | 'tag' | 'dropdown';
+export declare const TEXT_SIZES: readonly ["2xl", "xl", "lg", "md", "sm", "xs", "2xs", "h1", "h2", "h3", "h4", "h5", "h6"];
+export type TextSizeType = (typeof TEXT_SIZES)[number];

package/hydrate/index.d.ts

@@ -3,6 +3,7 @@
 import { Readable } from 'node:stream';
 
 export declare function createWindowFromHtml(templateHtml: string, uniqueId: string): any;
+export type TagTransformer = (tag: string) => string;
 /**
  * Serialize a value to a string that can be deserialized later.
  * @param {unknown} value - The value to serialize.
@@ -271,5 +272,16 @@ export declare function renderToString(html: string | any, options: SerializeDoc
 export declare function hydrateDocument(doc: any | string, options?: HydrateDocumentOptions): Promise<HydrateResults>;
 export declare function hydrateDocument(doc: any | string, options: HydrateDocumentOptions | undefined, asStream?: boolean): Readable;
 export declare function serializeDocumentToString(doc: Document, opts: HydrateFactoryOptions): string;
+/**
+ * Transforms a tag name using the current tag transformer
+ * @param tag - the tag to transform e.g. `my-tag`
+ * @returns the transformed tag e.g. `new-my-tag`
+ */
+export declare function transformTag<T extends string>(tag: T): T;
+/**
+ * Sets the tag transformer to be used when rendering custom elements
+ * @param transformer the transformer function to use. Must return a string
+ */
+export declare function setTagTransformer(transformer: TagTransformer): void;
 
 export {};