@oracle/oraclejet-preact 14.0.0

package/types/UNSAFE_MessageBanner/MessageBanner.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @license
+ * Copyright (c) %FIRST_YEAR% %CURRENT_YEAR%, Oracle and/or its affiliates.
+ * The Universal Permissive License (UPL), Version 1.0
+ * as shown at https://oss.oracle.com/licenses/upl/
+ * @ignore
+ */
+import { ComponentChildren, VNode } from 'preact';
+import { Item, ItemMetadata } from '../utils/UNSAFE_dataProvider';
+/**
+ * An object representing a single message in MessageBanner component.
+ */
+export declare type MessageBannerItem = {
+    /**
+     * Defines whether or not to include the close icon for the message
+     */
+    closeAffordance?: 'on' | 'off';
+    /**
+     * Defines the detail text of the message
+     */
+    detail?: string;
+    /**
+     * Defines the severity of the message
+     */
+    severity?: 'none' | 'error' | 'warning' | 'confirmation' | 'info';
+    /**
+     * Defines the sound to be played when opening the message
+     */
+    sound?: 'default' | 'none' | string;
+    /**
+     * Defines the primary text of the message
+     */
+    summary?: string;
+    /**
+     * Defines the timestamp for the message in ISO format
+     */
+    timestamp?: string;
+};
+/**
+ * Structure of data item passed to the renderers
+ */
+export declare type MessageBannerRendererDataItem<K, D> = {
+    /**
+     * The data for the current message
+     */
+    data: D;
+    /**
+     * The zero-based index of the current message
+     */
+    index: number;
+    /**
+     * The key for the current message
+     */
+    key: K;
+    /**
+     * The metadata for the current message
+     */
+    metadata?: ItemMetadata<K>;
+};
+/**
+ * Props for the MessageBanner Component
+ */
+declare type Props<Key, Data> = {
+    /**
+     * Data for the MessageBanner component. This data is used for rendering each banner message.
+     * The key for each message will be configured using the key of the corresponding item. This way,
+     * the component will know whether a new message is being added or an existing message is being updated/removed
+     * when the new data comes in.
+     */
+    data: Item<Key, Data>[];
+    /**
+     * A Banner message can have a different look and feel. For example, when using page-level
+     * messaging the messages need to be rendered from edge to edge without any outline. On the other
+     * hand, when they are being used in a section of a page or a dialog, they need to be rendered
+     * with an outline. This attribute can be used to specify where the component is being used so that
+     * it will render the messages accordingly.
+     */
+    type?: 'page' | 'section';
+    /**
+     * Triggered when a user tries to close a message through UI interaction. The application
+     * should listen to this event and remove the corresponding message item from the data
+     * which would then result in the message closed. If the application
+     * fails to remove the message item from the data, then no change will be done in the
+     * UI by the component and the message will stay in the UI opened.
+     */
+    onClose?: (item: Item<Key, Data>) => void;
+    /**
+     * Applications can use this property to provide the key of a renderer or a function that
+     * returns the key of a renderer to use for rendering the detail content.
+     *
+     * When a renderer key is provided as a value for this property, the corresponding renderer
+     * will be used for rendering the detail content for all the messages. If applications want
+     * to use a different renderer for different messages, they can provide a function that
+     * returns a renderer key instead.
+     *
+     * The provided function should accept an Item and return a key to a renderer for
+     * rendering the corresponding message's detail content. The value returned from this function
+     * should be a key to one of the renderers provided. If the returned value is not
+     * one of the keys of the provided renderers, the component will throw an Error.
+     *
+     * If the function returns undefined, the component then will perform default rendering
+     * of the detail content using the detail property of the corresponding message.
+     *
+     * If an application specifies both detail and a valid detailRendererKey, the detailRendererKey will
+     * take precedence and the corresponding renderer will be used for rendering the detail content.
+     */
+    detailRendererKey?: string | ((item: Item<Key, Data>) => string | undefined);
+    /**
+     * A set of available renderers for rendering the message content. Which renderer is used
+     * for rendering which content will be decided by specific properties in the row data.
+     */
+    renderers?: Record<string, (data: MessageBannerRendererDataItem<Key, Data>) => ComponentChildren>;
+    /**
+     * A renderer that renders the close button in the message.
+     */
+    closeButtonRenderer?: (title: string, onAction: (event?: Event) => void) => VNode;
+    /**
+     * Translations resources
+     */
+    translations?: {
+        /**
+         * Label for the message close button
+         */
+        close?: string;
+        /**
+         * Text for 'error' severity level
+         */
+        error?: string;
+        /**
+         * Text for 'warning' severity level
+         */
+        warning?: string;
+        /**
+         * Text for 'info' severity level
+         */
+        info?: string;
+        /**
+         * Text for 'confirmation' severity level
+         */
+        confirmation?: string;
+        /**
+         * Text to guide keyboard users navigate to prior focussed element when the messages
+         * region gains focus
+         */
+        navigationFromMessagesRegion?: string;
+        /**
+         * Text to guide keyboard users navigate to new displayed messages when focus is outside
+         * the messages region
+         */
+        navigationToMessagesRegion?: string;
+    };
+};
+/**
+ * Renders individual messages based on the provided data
+ */
+declare function MessageBanner<K extends string | number = string | number, D extends MessageBannerItem = MessageBannerItem>({ closeButtonRenderer, detailRendererKey, data, onClose, renderers, translations, type }: Props<K, D>): import("preact").JSX.Element | null;
+export { MessageBanner };

package/types/UNSAFE_MessageBanner/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright (c) %FIRST_YEAR% %CURRENT_YEAR%, Oracle and/or its affiliates.
+ * The Universal Permissive License (UPL), Version 1.0
+ * as shown at https://oss.oracle.com/licenses/upl/
+ * @ignore
+ */
+export { MessageBanner } from './MessageBanner';
+export type { MessageBannerItem, MessageBannerRendererDataItem } from './MessageBanner';

package/types/UNSAFE_MessageToast/MessageToast.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * Copyright (c) %FIRST_YEAR% %CURRENT_YEAR%, Oracle and/or its affiliates.
+ * The Universal Permissive License (UPL), Version 1.0
+ * as shown at https://oss.oracle.com/licenses/upl/
+ * @ignore
+ */
+import { ComponentChildren } from 'preact';
+import { Item, ItemMetadata } from '../utils/UNSAFE_dataProvider';
+declare const positions: ("bottom" | "top" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "top-left" | "top-right" | "bottom-left" | "bottom-right")[];
+declare type Position = typeof positions[number];
+declare type Offset = number | {
+    horizontal?: number;
+    vertical?: number;
+};
+/**
+ * An object representing a single message in MessageToast component.
+ */
+export declare type MessageToastItem = {
+    /**
+     * Defines whether or not to include the close icon for the message
+     *
+     * @default 'on'
+     */
+    closeAffordance?: 'on' | 'off';
+    /**
+     * Defines the detail text of the message
+     */
+    detail?: string;
+    /**
+     * Defines the severity of the message
+     *
+     * @default 'error'
+     */
+    severity?: 'none' | 'error' | 'warning' | 'confirmation' | 'info';
+    /**
+     * Defines the sound to be played when opening the message
+     *
+     * @default 'none'
+     */
+    sound?: 'default' | 'none' | string;
+    /**
+     * Defines the primary text of the message
+     */
+    summary?: string;
+    /**
+     * Defines the time after which the message is to be closed automatically
+     *
+     * on - default of 5s
+     * off - no auto timeout, manually dismissed
+     * number - seconds in milliseconds format
+     *
+     * @default 'off'
+     */
+    autoTimeout?: 'on' | 'off' | number;
+};
+/**
+ * Structure of data item passed to the renderers
+ */
+export declare type MessageToastRendererDataItem<K, D> = {
+    /**
+     * The data for the current message
+     */
+    data: D;
+    /**
+     * The key for the current message
+     */
+    key: K;
+    /**
+     * The metadata for the current message
+     */
+    metadata?: ItemMetadata<K>;
+};
+declare type Props<Key, Data> = {
+    /**
+     * Defines the fixed position where the notifications will to be placed on the screen.
+     * - top-start resolves to top-left in LTR (top-right in RTL)
+     * - top-end resolves to top-right in LTR (top-left in RTL)
+     * - bottom-start resolves to bottom-left in LTR (bottom-right in RTL)
+     * - bottom-end resolves to bottom-right in LTR (bottom-left in RTL)
+     *
+     * default bottom
+     */
+    position?: Position;
+    /**
+     * Defines an offset (in pixels) in the placement. Value can be supplied as a number or
+     * an object with horizontal and vertical values.
+     *
+     * default 0
+     */
+    offset?: Offset;
+    /**
+     * Data for the MessageToast component. This data is used for rendering each toast message.
+     * The key for each message will be configured using the key of the corresponding item. This way,
+     * the component will know whether a new message is being added or an existing message is being updated/removed
+     * when the new data comes in.
+     */
+    data: Item<Key, Data>[];
+    /**
+     * Triggered when a user tries to close a message through UI interaction. The application
+     * should listen to this event and remove the corresponding message item from the data
+     * which would then result in the message closed. If the application
+     * fails to remove the message item from the data, then no change will be done in the
+     * UI by the component and the message will stay in the UI opened.
+     */
+    onClose?: (item: Item<Key, Data>) => void;
+    /**
+     * Applications can use this property to provide the key of a renderer or a function that
+     * returns the key of a renderer to use for rendering the detail content.
+     *
+     * When a renderer key is provided as a value for this property, the corresponding renderer
+     * will be used for rendering the detail content for all the messages. If applications want
+     * to use a different renderer for different messages, they can provide a function that
+     * returns a renderer key instead.
+     *
+     * The provided function should accept an Item and return a key to a renderer for
+     * rendering the corresponding message's detail content. The value returned from this function
+     * should be a key to one of the renderers provided. If the returned value is not
+     * one of the keys of the provided renderers, the component will throw an Error.
+     *
+     * If the function returns undefined, the component then will perform default rendering
+     * of the detail content using the detail property of the corresponding message.
+     *
+     * If an application specifies both detail and a valid detailRendererKey, the detailRendererKey will
+     * take precedence and the corresponding renderer will be used for rendering the detail content.
+     */
+    detailRendererKey?: string | ((item: Item<Key, Data>) => string | undefined);
+    /**
+     * Applications can use this property to provide the key of a renderer or a function that
+     * returns the key of the renderer to use for rendering the start icon.
+     *
+     * When a renderer key is provided as a value for this property, the corresponding renderer
+     * will be used for rendering the start icon for all the messages. If applications want
+     * to use a different renderer for different messages, they can provide a function that
+     * returns a renderer key instead.
+     *
+     * The provided function should accept an Item and return a key to a renderer for
+     * rendering the corresponding message's start icon. The value returned from this function
+     * should be a key to one of the renderers provided. If the returned value is not
+     * one of the keys of the provided renderers, the component will throw an Error.
+     *
+     * If the function returns undefined, the component then will perform default rendering
+     * of the start icon using the severity property of the corresponding message.
+     *
+     * If an application specifies both severity and a valid iconRendererKey, the iconRendererKey will
+     * take precedence and the corresponding renderer will be used for rendering the start icon.
+     */
+    iconRendererKey?: string | ((item: Item<Key, Data>) => string | undefined);
+    /**
+     * A set of available renderers for rendering the message content. Which renderer is used
+     * for rendering which content will be decided by specific properties in the row data.
+     */
+    renderers?: Record<string, (data: MessageToastRendererDataItem<Key, Data>) => ComponentChildren>;
+};
+export declare function MessageToast<K extends string | number, D extends MessageToastItem>({ data, detailRendererKey, iconRendererKey, renderers, onClose, offset, position }: Props<K, D>): import("preact").JSX.Element;
+export {};

package/types/UNSAFE_MessageToast/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright (c) %FIRST_YEAR% %CURRENT_YEAR%, Oracle and/or its affiliates.
+ * The Universal Permissive License (UPL), Version 1.0
+ * as shown at https://oss.oracle.com/licenses/upl/
+ * @ignore
+ */
+export { MessageToast } from './MessageToast';
+export type { MessageToastItem } from './MessageToast';

package/types/UNSAFE_MeterBar/MeterBar.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright (c) %FIRST_YEAR% %CURRENT_YEAR%, Oracle and/or its affiliates.
+ * The Universal Permissive License (UPL), Version 1.0
+ * as shown at https://oss.oracle.com/licenses/upl/
+ * @ignore
+ */
+import { MeterBarProps } from './MeterBar.types';
+/**
+ * A Meter bar displays information graphically in a rectangular bar, highlighting a specific metric value's progress in relation to its min, max, or thresholds.
+ */
+export declare function MeterBar({ max, min, value, step, length, size, orientation, isTrackRendered, thresholdDisplay, indicatorSize, ...props }: MeterBarProps): import("preact").JSX.Element;

package/types/UNSAFE_MeterBar/MeterBar.types.d.ts

@@ -0,0 +1,90 @@
+import { Size } from '../utils/UNSAFE_size';
+import { InputDetail, CommitDetail, Threshold, ReferenceLine, MeterSize, ThresholdDisplay } from '../utils/UNSAFE_meterTypes';
+import { ColorProps } from '../utils/UNSAFE_interpolations/colors';
+/**
+ * Props for Meter Gauge.
+ */
+export declare type MeterBarProps = {
+    /**
+     * The size of the meter bar.
+     */
+    size?: MeterSize;
+    /**
+     * The value of the meter bar.
+     */
+    value?: number;
+    /**
+     * Integer value specifying the maximum value of the meter bar.
+     */
+    max?: number;
+    /**
+     * Integer value specifying the minimum value of the meter bar.
+     */
+    min?: number;
+    /**
+     * The orientation of the gauge.
+     */
+    orientation?: 'vertical' | 'horizontal';
+    /**
+     * Specifies the increment by which values can be changed by the end user.
+     */
+    step?: number;
+    /**
+     * The length of meter bar.
+     */
+    length?: Size;
+    /**
+     * The datatip shown for meter bar. If datatip is undefined, meter bar will use the default datatip. If datatip is null, no datatip is shown.
+     */
+    datatip?: string | null;
+    /**
+     * The callback called in response to focus or keyboard (up, down, left, right, home, and end) or mouse (dragging) interactions that change the value of the meter bar.
+     */
+    onInput?: (detail: InputDetail) => void;
+    /**
+     * The callback called when value of the meter bar is submitted on Enter, blur, click, or drag end.
+     */
+    onCommit?: (detail: CommitDetail) => void;
+    /**
+     * Defines the ratio of relative thickness of the indicator to the track. Only supports number between 0 and 1.
+     */
+    indicatorSize?: number;
+    /**
+     * The color of the indicator of the bar.
+     */
+    indicatorColor?: ColorProps['color'];
+    /**
+     * Specifies if the track is rendered.
+     */
+    isTrackRendered?: boolean;
+    /**
+     * The color of the track.
+     */
+    trackColor?: ColorProps['color'];
+    /**
+     * Controls whether the current threshold is displayed on the indicator, in the track, or if all the thresholds are displayed in the track.
+     */
+    thresholdDisplay?: ThresholdDisplay;
+    /**
+     * An array of Threshold objects.
+     * Applications are required to include information about thresholds for screen readers to make their component accessible by using ariaDescribedBy, ariaLabelledBy or accessibleLabel.
+     */
+    thresholds?: Threshold[];
+    /**
+     * Reference lines for the gauge value bar.
+     * Applications are required to include information about reference lines for screen readers to make their component accessible by using ariaDescribedBy, ariaLabelledBy or accessibleLabel.
+     */
+    referenceLines?: ReferenceLine[];
+    /**
+     * A label to be used for accessibility purposes. Default label will be used if not provided.
+     */
+    accessibleLabel?: string;
+    /**
+     * One or more ids (separated by spaces) of elements that label the meter bar.
+     */
+    ariaLabelledBy?: string;
+    /**
+     * One or more ids (separated by spaces) of elements that describe the meter bar.
+     */
+    ariaDescribedBy?: string;
+};

package/types/UNSAFE_MeterBar/MeterUtils.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright (c) %FIRST_YEAR% %CURRENT_YEAR%, Oracle and/or its affiliates.
+ * The Universal Permissive License (UPL), Version 1.0
+ * as shown at https://oss.oracle.com/licenses/upl/
+ * @ignore
+ */
+import type { Ref } from 'preact/hooks';
+import { ReferenceLine } from '../utils/UNSAFE_meterTypes';
+declare type Dimensions = {
+    width: number;
+    height: number;
+};
+/**
+ * Returns the metric value of the clicked point.
+ * @param event The PointerEvent
+ * @param dimensionsRef Ref to stored dimensions of the meter bar.
+ * @param min The minimum value of the meter bar.
+ * @param max The maximum value of the meter bar.
+ * @param step The step value of the meter bar.
+ * @param orientation The orientation of the meter bar.
+ * @param isRtl Whether the reading mode is 'rtl'
+ * @returns The metric value of the clicked point.
+ */
+export declare function getValue(event: PointerEvent, dimensionsRef: Ref<Dimensions>, min: number, max: number, step: number, orientation?: 'horizontal' | 'vertical', isRtl?: boolean): number | undefined;
+/**
+ * Returns the true dimension of the meter bar after first render. All dimensions are 0 for initial render.
+ * @param element The meter bar track HTML element
+ * @returns The dimension of the meter bar.
+ */
+export declare function getDimensions(element: HTMLElement | null): Dimensions;
+/**
+ * Returns object with 'start' and 'end' keys. Value for each key will be true if at least one ref line with correposnding position is present in meter bar.
+ * @param lines The array of reference lines.
+ * @returns Returns object with start and end keys.
+ */
+export declare function getRefLinesInfo(lines?: ReferenceLine[]): {
+    start: boolean;
+    end: boolean;
+};
+/**
+ * Returns the total component size taking into account the presence or absence of
+ * reference line in either or both side of reference bar. This method assumes that reference line
+ * is always larger than the track size.
+ * @param refLineInfo Object sepecifying if ref lines with start, end or both position are present.
+ * @param size The size of the meter bar.
+ * @returns {string}
+ */
+export declare function getComponentSize(refLineInfo: {
+    start: boolean;
+    end: boolean;
+}, size: 'sm' | 'md' | 'lg'): string;
+export {};

package/types/UNSAFE_MeterBar/ReferenceLines.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright (c) %FIRST_YEAR% %CURRENT_YEAR%, Oracle and/or its affiliates.
+ * The Universal Permissive License (UPL), Version 1.0
+ * as shown at https://oss.oracle.com/licenses/upl/
+ * @ignore
+ */
+import { ColorProps } from '../utils/UNSAFE_interpolations/colors';
+declare type ReferenceLineProps = {
+    orientation: 'horizontal' | 'vertical';
+    percentage: string;
+    position?: 'start' | 'end';
+    color?: ColorProps['color'];
+};
+export declare function ReferenceLineBar({ orientation, percentage, color, position }: ReferenceLineProps): import("preact").JSX.Element;
+export {};

package/types/UNSAFE_MeterBar/ThresholdBar.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright (c) %FIRST_YEAR% %CURRENT_YEAR%, Oracle and/or its affiliates.
+ * The Universal Permissive License (UPL), Version 1.0
+ * as shown at https://oss.oracle.com/licenses/upl/
+ * @ignore
+ */
+import { HTMLAttributesSignalExcluded } from '../utils/UNSAFE_attributeUtils';
+import { ColorProps } from '../utils/UNSAFE_interpolations/colors';
+declare type IntrinsicProps = Pick<HTMLAttributesSignalExcluded<HTMLDivElement>, 'class'>;
+declare type ThresholdBarProps = IntrinsicProps & {
+    color?: ColorProps['color'];
+    length: string;
+    orientation: 'horizontal' | 'vertical';
+};
+export declare function ThresholdBar({ color, length, orientation, ...otherProps }: ThresholdBarProps): import("preact").JSX.Element;
+export {};

package/types/UNSAFE_MeterBar/index.d.ts

@@ -0,0 +1 @@
+export { MeterBar } from './MeterBar';

package/types/UNSAFE_MeterCircle/CircleMeterUtils.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright (c) %FIRST_YEAR% %CURRENT_YEAR%, Oracle and/or its affiliates.
+ * The Universal Permissive License (UPL), Version 1.0
+ * as shown at https://oss.oracle.com/licenses/upl/
+ * @ignore
+ */
+import type { Ref } from 'preact/hooks';
+import { Sector } from '../utils/PRIVATE_meterUtils';
+import { CenterContext } from './MeterCircle.types';
+declare type Dimensions = {
+    width: number;
+    height: number;
+    innerRadius: number;
+    outerRadius: number;
+};
+/**
+ * Returns the true dimensions of the meter circle after initial render. All dimensions are 0 for initial render.
+ * @param element The HTML element that wraps the track and indicator div.
+ * @param section The section in which the meter circle lies.
+ * @returns The dimensions of the meter circle.
+ */
+export declare function getDimensions(element: HTMLElement | null, section: Sector): Dimensions;
+/**
+ * Returns the value corresponding to clicked point in the meter circle. Returns undefined if the clicked point is
+ * outside the track of the meter circle.
+ * @param pageX The pageX of the click event
+ * @param pageY The pageY of the click event
+ * @param max The max value of the meter circle.
+ * @param min The min value of the meter circle.
+ * @param step The step of the metercircle.
+ * @param dimensionsRef The ref that stores dimensions reference of meter circle.
+ * @param startAngle The startAngle of the meter circle.
+ * @param angleExtent The angleExtent of the meter circle
+ * @returns {number} The value corresponding to clicked point in the meter circle.
+ */
+export declare function getValue(event: PointerEvent, min: number, max: number, step: number, dimensionsRef: Ref<Dimensions>, startAngle: number, angleExtent: number, section: Sector, isRtl: boolean): number | undefined;
+/**
+ * Returns the fraction of angle extent for given delta.
+ * @param delta The delta of metric values.
+ * @param min The minimum value of the meter circle.
+ * @param max The maximum value of the meter circle.
+ * @param angleExtent The angle extent of the meter circle.
+ * @returns The angle extent corresponding to delta in metric value.
+ */
+export declare function getAngleExtentFromDelta(delta: number, min: number, max: number, angleExtent: number): number;
+/**
+ * Returns the start angle for given metric value.
+ * @param value The metric value
+ * @param min The minimum value of the meter circle.
+ * @param max The maximum value of the meter circle.
+ * @param startAngle The startAngle of the meter circle.
+ * @param angleExtent The angleExtent of the meter circle.
+ * @param isRtl Whether the reading mode is 'rtl'
+ * @returns The startAngle for the metric value.
+ */
+export declare function getStartAngleForValue(value: number, min: number, max: number, startAngle: number, angleExtent: number, isRtl: boolean): number;
+/**
+ * Returns the center context of for the meter circle.
+ */
+export declare function getCenterContext(dimensionsRef: Ref<Dimensions>, section: 'top' | 'bottom' | 'left' | 'right' | 'full'): CenterContext | undefined;
+export {};

package/types/UNSAFE_MeterCircle/CircularReferenceLine.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright (c) %FIRST_YEAR% %CURRENT_YEAR%, Oracle and/or its affiliates.
+ * The Universal Permissive License (UPL), Version 1.0
+ * as shown at https://oss.oracle.com/licenses/upl/
+ * @ignore
+ */
+import { getCenterCoord } from '../utils/PRIVATE_meterUtils';
+import { ColorProps } from '../utils/UNSAFE_interpolations/colors';
+declare type getCenterCoordParamType = Parameters<typeof getCenterCoord>;
+export declare type CircularReferenceLineProps = {
+    color?: ColorProps['color'];
+    angle: number;
+    radius: string;
+    length: string;
+    section: getCenterCoordParamType[0];
+};
+export declare function CircularReferenceLine({ color, angle, radius, length, section }: CircularReferenceLineProps): import("preact").JSX.Element;
+export {};