@emuanalytics/flow-rdf-ui 4.0.0-preview.9 → 4.0.0

package/dist/index.cjs

@@ -1,5 +1,9 @@
 'use strict';
 
+const chart_js = require('chart.js');
+const chartjsChartMatrix = require('chartjs-chart-matrix');
+const AnnotationPlugin = require('chartjs-plugin-annotation');
+const d3Scale = require('d3-scale');
 const lit = require('lit');
 const decorators_js = require('lit/decorators.js');
 const classMap_js = require('lit/directives/class-map.js');
@@ -8,11 +12,7 @@ const staticHtml_js = require('lit/static-html.js');
 const luxon = require('luxon');
 const map_js = require('lit/directives/map.js');
 const range_js = require('lit/directives/range.js');
-const chart_js = require('chart.js');
 const ref_js = require('lit/directives/ref.js');
-const chartjsChartMatrix = require('chartjs-chart-matrix');
-const AnnotationPlugin = require('chartjs-plugin-annotation');
-const d3Scale = require('d3-scale');
 const live_js = require('lit/directives/live.js');
 const tinycolor = require('@ctrl/tinycolor');
 const styleMap_js = require('lit/directives/style-map.js');
@@ -1451,8 +1451,8 @@ function unregisterIconLibrary(name) {
 function setDefaultLocale(locale) {
   luxon.Settings.defaultLocale = locale;
 }
-function setDefaultTimeZone(timeZone) {
-  luxon.Settings.defaultZone = timeZone;
+function setDefaultTimeZone(timezone) {
+  luxon.Settings.defaultZone = timezone;
 }
 
 function filterRuleSet(ruleset, options) {
@@ -1939,7 +1939,6 @@ function getAnimation(el, animationName, options) {
 
 const connectedElements = /* @__PURE__ */ new Set();
 const translations = /* @__PURE__ */ new Map();
-const isClient = isDefined(MutationObserver) && isDefined(document) && isDefined(document.documentElement);
 let fallback;
 let documentDirection = "ltr";
 let documentLanguage = "en";
@@ -1953,8 +1952,8 @@ function registerTranslation(...translation) {
     }
     if (!fallback) {
       fallback = t;
-      const isClient2 = isDefined(MutationObserver) && isDefined(document) && isDefined(document.documentElement);
-      if (isClient2) {
+      const isClient = isDefined(MutationObserver) && isDefined(document) && isDefined(document.documentElement);
+      if (isClient) {
         const documentElementObserver = new MutationObserver(update);
         documentDirection = document.documentElement.dir || "ltr";
         documentLanguage = document.documentElement.lang || navigator.language;
@@ -1968,6 +1967,7 @@ function registerTranslation(...translation) {
   update();
 }
 function update() {
+  const isClient = isDefined(document) && isDefined(document.documentElement);
   if (isClient) {
     documentDirection = document.documentElement.dir || "ltr";
     documentLanguage = document.documentElement.lang || navigator.language;
@@ -3988,6 +3988,11 @@ const styles$U = lit.css`
     color: var(--flow-ui-color-neutral-0);
   }
 
+  .badge--secondary {
+    background-color: var(--flow-ui-color-secondary-500);
+    color: var(--flow-ui-color-neutral-0);
+  }
+
   .badge--success {
     background-color: var(--flow-ui-color-success-600);
     color: var(--flow-ui-color-neutral-0);
@@ -4022,6 +4027,10 @@ const styles$U = lit.css`
     --pulse-color: var(--flow-ui-color-primary-500);
   }
 
+  .badge--pulse.badge--secondary {
+    --pulse-color: var(--flow-ui-color-secondary-500);
+  }
+
   .badge--pulse.badge--success {
     --pulse-color: var(--flow-ui-color-success-600);
   }
@@ -4081,6 +4090,7 @@ class FlowUiBadge extends FlowRdfElement {
         class=${classMap_js.classMap({
       badge: true,
       "badge--primary": this.variant === "primary",
+      "badge--secondary": this.variant === "secondary",
       "badge--success": this.variant === "success",
       "badge--neutral": this.variant === "neutral",
       "badge--warning": this.variant === "warning",
@@ -13382,13 +13392,13 @@ const styles$y = lit.css`
   }
 
   /* Wrapper needed to support text ellipsis in flex item */
-  .gauge__header-text-wrapper {
+  .gauge__title-wrapper {
     flex: 1;
     min-width: 0;
     display: flex;
   }
 
-  .gauge__header-text {
+  .gauge__title {
     text-overflow: ellipsis;
     white-space: nowrap;
     overflow: hidden;
@@ -13522,7 +13532,7 @@ class FlowUiGauge extends FlowRdfElement {
       <flow-ui-dialog class="gauge__info-dialog">
         <div slot="label" class="gauge__info-dialog-label">
           ${this.headerIconTemplate()}
-          <slot name="header-text">${this.heading}</slot>
+          <slot name="title-text">${this.title}</slot>
         </div>
         <slot name="info"></slot>
         <div slot="footer">
@@ -13542,9 +13552,9 @@ class FlowUiGauge extends FlowRdfElement {
       >
         <div part="header" class="gauge__header">
           ${this.headerIconTemplate()}
-          <span class="gauge__header-text-wrapper">
-            <span part="header-text" class="gauge__header-text">
-              <slot name="header-text">${this.heading}</slot>
+          <span class="gauge__title-wrapper">
+            <span part="title" class="gauge__title">
+              <slot name="title">${this.title}</slot>
             </span>
           </span>
           ${hasInfo ? this.infoButtonTemplate() : lit.nothing}
@@ -13569,7 +13579,7 @@ __decorateClass$w([
 ], FlowUiGauge.prototype, "_infoDialog", 2);
 __decorateClass$w([
   decorators_js.property()
-], FlowUiGauge.prototype, "heading", 2);
+], FlowUiGauge.prototype, "title", 2);
 __decorateClass$w([
   decorators_js.property()
 ], FlowUiGauge.prototype, "units", 2);
@@ -24774,7 +24784,7 @@ function registerComponents() {
   FlowUiVisuallyHidden.define("flow-ui-visually-hidden");
 }
 
-const version = "4.0.0-preview.8";
+const version = "4.0.0";
 
 const CONSOLE_HIGHLIGHT_STYLE = `
   padding: 2px 4px;
@@ -24861,6 +24871,7 @@ const translation = {
 const es = translation;
 
 function initialize() {
+  initializeChartJs();
   registerTranslation(en);
   registerTranslation(enGB);
   registerTranslation(es);

package/dist/index.d.cts

@@ -572,31 +572,123 @@ declare module '@shoelace-style/animations' {
   export const zoomOutUp: Animation;
 }
 
-/** Gets a list of all supported animation names. */
+/**
+ * Returns a list of all supported animation names.
+ *
+ * Supply the required animation as the `name` property of the
+ * `<flow-ui-animation>` component.
+ */
 declare function getAnimationNames(): string[];
-/** Gets a list of all supported easing function names. */
+/**
+ * Returns a list of all supported easing method names.
+ *
+ * Supply the required easing method as the `easing` property of the
+ * `<flow-ui-animation>` component.
+ */
 declare function getEasingNames(): string[];
 
+/**
+ * @internal
+ *
+ * Registers standard Chart.js components and plugins,
+ * and sets default options.
+ */
 declare function initializeChartJs(): void;
 declare function registerChartComponent(...components: ChartComponentLike[]): void;
 
-/** Hello how are you? */
+/**
+ *
+ * The following code shows how to import FontAwesome SVG icons from the `flow-rdf-ui/icons` package and add them to the
+ * default icon library.
+ * ```js
+ * // Import and register icons
+ * import {fasHouse, fasGear, fasUser} from '@emuanalytics/flow-rdf-ui/icons';
+ * import {addIcons} from '@emuanalytics/flow-rdf-ui';
+ * addIcons({fasHouse, fasGear, fasUser});
+ * ```
+ *
+ * Icons are registered under their camelCase name **and** kebab-case name.
+ * Once registered, they can be used in the following way:
+ *
+ * ```html
+ * <flow-ui-icon name="fas-house"></flow-ui-icon>
+ * ```
+ *
+ * Note that missing or mis-spelled icons will be displayed as <flow-ui-icon name="unknown"></flow-ui-icon>.
+ *
+ * For a list of available icons, see the [FontAwesome icon gallery](https://fontawesome.com/search?o=r&m=free).
+ */
 declare const addIcons: (icons: {
     [name: string]: string;
 }) => void;
 
 type IconLibraryResolver = (name: string) => string;
 type IconLibraryMutator = (svg: SVGElement) => void;
-/** Adds an icon library to the registry, or overrides an existing one. */
+/**
+ *
+ * Use this function to add a custom icon library to the registry or overrides an existing one.
+ * Provide a resolver function that returns the URL of the icon based on its name.
+ * Optionally, provide a mutator function that modifies the SVG element of the icon.
+ *
+ * Two icon libraries are included by default:
+ * - `system` (System icons used by `flow-rdf-ui` components)
+ * - `default` (FontAwesome 5.15.4)
+ *
+ * To use a custom icon library, set the `library` property of the `<flow-ui-icon>` component
+ * to the registered name of the library. If omitted, the `default` library is used.
+ *
+ * ```typescript
+ * // Register FontAwesome icon library using SVGs from Flo.w CDN
+ * registerIconLibrary('fa', {
+ *   resolver: (name) => {
+ *     const filename = name.replace(/^fa[rbs]-/, '');
+ *     let folder = 'regular';
+ *     if (name.substring(0, 4) === 'fas-') folder = 'solid';
+ *     if (name.substring(0, 4) === 'fab-') folder = 'brands';
+ *     return `https://flow-cdn.emu-analytics.net/icons/fontawesome-6.4.2/${folder}/${filename}.svg`;
+ *   },
+ *   mutator: (svg) => svg.setAttribute('fill', 'currentColor')
+ * });
+ * ```
+ *
+ * ```html
+ * <flow-ui-icon library="fa" name="fas-house"></flow-ui-icon>
+ * ```
+ *
+ * @param name The name of the custom icon library.
+ * @param options The icon library resolver and optional mutator.
+ * @param options.resolver A function that returns the URL of given icon.
+ * @param options.mutator An optional function that mutates the SVG element of the icon.
+ */
 declare function registerIconLibrary(name: string, options: {
     resolver: IconLibraryResolver;
     mutator?: IconLibraryMutator;
 }): void;
-/** Removes an icon library from the registry. */
+/**
+ * Removes a custom icon library from the registry.
+ */
 declare function unregisterIconLibrary(name: string): void;
 
+/**
+ * Set the default locale used by date/time-sensitive components including
+ * `<flow-ui-calendar>`, `<flow-ui-date-time-picker>` and `<flow-ui-timer>`.
+ *
+ * The default locale is can be overridden by setting the `locale` attribute
+ * of date/time-sensitive components.
+ *
+ * @param locale Locale code (e.g. `'en'`, `'en-US'`, `'es-ES'`)
+ */
 declare function setDefaultLocale(locale: string): void;
-declare function setDefaultTimeZone(timeZone: string): void;
+/**
+ * Set the default timezone used by date/time-sensitive components including
+ * `<flow-ui-calendar>`, `<flow-ui-date-time-picker>` and `<flow-ui-timer>`.
+ *
+ * The default timezone is can be overridden by setting the `timezone` attribute
+ * of date/time-sensitive components.
+ *
+ * @param timezone Timezone (e.g. `'Europe/London'`, `'America/New_York'`)
+ */
+declare function setDefaultTimeZone(timezone: string): void;
 
 interface VirtualElement {
     getBoundingClientRect: () => DOMRect;
@@ -1096,38 +1188,84 @@ interface FlowQueryBuilderConverterOptions {
 type FlowQueryBuilderConverter = (ruleSet: FlowQueryBuilderRuleSet, config: FlowQueryBuilderConfig, options?: FlowQueryBuilderConverterOptions) => any;
 
 /**
- * Given a FlowQueryBuilderRuleSet this function will recursively filter rules.
+ * Recursively applies filters to the supplied {@link FlowQueryBuilderRuleSet}
+ * returning a new rule set.
  *
- * This can be used to sanitize user queries before they are executed.
+ * This is used to sanitize user queries before they are executed by removing
+ * excluded fields or including only the specified fields.
+ *
+ * Note that `includeFields` takes precedence over `excludeFields`.
+ *
+ * ```ts
+ * const ruleSet = {
+ *   condition: 'and',
+ *   rules: [ { field: 'a', ... }, { field: 'b', ... }, { field: 'c', ... } ]
+ * };
+ *
+ * const filteredRuleSet = filterRuleSet(ruleSet, { excludeFields: ['b', 'c'] });
+ * ```
  *
  * @param ruleset Rule set to filter
- * @param options Fields to include or exclude
+ * @param options Filter rules
+ * @param options.excludeFields Fields to exclude from the {@link FlowQueryBuilderRuleSet}
+ * @param options.includeFields Fields to include in the {@link FlowQueryBuilderRuleSet}
  */
 declare function filterRuleSet(ruleset: FlowQueryBuilderRuleSet, options: {
     excludeFields?: string[];
     includeFields?: string[];
 }): FlowQueryBuilderRuleSet;
+/**
+ * Recursively renames fields in the supplied {@link FlowQueryBuilderRuleSet}
+ * returning a new rule set.
+ *
+ * This can be used to sanitize user queries before they are executed.
+ *
+ * ```ts
+ * const ruleSet = {
+ *   condition: 'and',
+ *   rules: [ { field: 'a', ... }, { field: 'b', ... }, ... } ]
+ * };
+ *
+ * const renamedRuleSet = renameRuleSetFields(ruleSet, { a: 'renamedA' });
+ *
+ * // renamedRuleSet = {
+ * //   condition: 'and',
+ * //   rules: [ { field: 'renamedA', ... }, { field: 'b', ... }, ... } ]
+ * // };
+ *
+ * ```
+ *
+ * @param ruleset Rule set to rename.
+ * @param replacements Set of field name replacements.
+ * @returns A new {@link FlowQueryBuilderRuleSet} with renamed fields.
+ */
 declare function renameRuleSetFields(ruleset: FlowQueryBuilderRuleSet, replacements: Record<string, string>): FlowQueryBuilderRuleSet;
 /**
- * Given a FlowQueryBuilderRuleSet this function will recursively apply
- * a transform function to each rule.
+ * Recursively applies a tranform function to the supplied {@link FlowQueryBuilderRuleSet} returning a new rule set.
  *
- * The transform fn should expect a single FlowQueryBuilderRule and return:
+ * The transform function should expect a single `FlowQueryBuilderRule` and return:
  *
- * - the same rule unmodifed or modified in place
+ * - the same rule unmodified or modified in place
  * - `undefined` to exclude the rule from the rule set
  *
- * This can be used to sanitize rule sets before they are used to perform queries.
+ * This can be used to modify and sanitize rule sets before they are used to perform queries.
  *
- * @param ruleSet query builder rule set
- * @param transformFn transform function
+ * @param ruleSet Query builder rule set to transform.
+ * @param transformFn Transform function
+ * @returns A new {@link FlowQueryBuilderRuleSet} with transformed rules.
  */
 declare function transformRuleSet(ruleSet: FlowQueryBuilderRuleSet, transformFn: (rule: FlowQueryBuilderRule) => FlowQueryBuilderRule | undefined, clone?: boolean): FlowQueryBuilderRuleSet;
 /**
- * Helper functions to determine if supplied argument is a FlowQueryBuilderRule or FlowQueryBuilderRuleSet
+ * Helper function to determine if the supplied argument is a {@link FlowQueryBuilderRule}
  */
 declare const isRule: (r: unknown) => r is FlowQueryBuilderRule;
+/**
+ * Helper function to determine if the supplied argument is a {@link FlowQueryBuilderRuleSet}
+ */
 declare const isRuleSet: (r: unknown) => r is FlowQueryBuilderRuleSet;
+/**
+ * Helper function to determine if the supplied argument is a {@link FlowQueryBuilderRule} or {@link FlowQueryBuilderRuleSet}
+ */
 declare const isRuleOrRuleset: (r: unknown) => r is FlowQueryBuilderRule | FlowQueryBuilderRuleSet;
 
 declare const converter$1: FlowQueryBuilderConverter;
@@ -1135,7 +1273,19 @@ declare const converter$1: FlowQueryBuilderConverter;
 declare const converter: FlowQueryBuilderConverter;
 
 /**
- * Register all Flo.w RDF UI components.
+ * Call this function to register all Flo.w RDF UI custom elements.
+ *
+ * Alternatively, you can register each required custom element individually
+ * using the `define` method of the custom element class as shown below:
+ *
+ * ```typescript
+ * // Selectively register the `<flow-ui-alert>` custom element
+ * import { FlowAlert } from '@emuanalytics/flow-rdf-ui';
+ * FlowAlert.define('flow-ui-alert');
+ * ```
+ *
+ * This function is called automatically when using the `flow-rdf-angular`
+ * support library.
  */
 declare function registerComponents(): void;
 
@@ -1157,25 +1307,7 @@ interface ExistsOptions {
 }
 /** Registers one or more translations */
 declare function registerTranslation(...translation: Translation$1[]): void;
-/**
- * Localize Reactive Controller for components built with Lit
- *
- * To use this controller, import the class and instantiate it in a custom element constructor:
- *
- * private localize = new LocalizeController(this);
- *
- * This will add the element to the set and make it respond to changes to <html dir|lang> automatically. To make it
- * respond to changes to its own dir|lang properties, make it a property:
- *
- *   @property() dir: string;
- *   @property() lang: string;
- *
- * To use a translation method, call it like this:
- *
- *   ${this.localize.term('term_key_here')}
- *   ${this.localize.date('2021-12-03')}
- *   ${this.localize.number(1000000)}
- */
+/** @internal */
 declare class LocalizeController$1<UserTranslation extends Translation$1 = DefaultTranslation> implements ReactiveController {
     host: ReactiveControllerHost & HTMLElement;
     constructor(host: ReactiveControllerHost & HTMLElement);
@@ -1204,6 +1336,7 @@ declare class LocalizeController$1<UserTranslation extends Translation$1 = Defau
     relativeTime(value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions): string;
 }
 
+/** @internal */
 declare class LocalizeController extends LocalizeController$1<Translation> {
 }
 
@@ -1233,6 +1366,12 @@ interface Translation extends Translation$1 {
     toggleColorFormat: string;
 }
 
+/**
+ * Initializes the the `flow-rdf-ui` library.
+ *
+ * This function is called automatically when using the `flow-rdf-angular`
+ * support library.
+ */
 declare function initialize(): void;
 
 /**
@@ -1440,7 +1579,7 @@ declare global {
 declare class FlowUiBadge extends FlowRdfElement {
     static styles: CSSResultGroup;
     /** The badge's theme variant. */
-    variant: 'primary' | 'success' | 'neutral' | 'warning' | 'danger';
+    variant: 'primary' | 'secondary' | 'success' | 'neutral' | 'warning' | 'danger';
     /** Draws a pill-style badge with rounded edges. */
     pill: boolean;
     /** Makes the badge pulsate to draw attention. */
@@ -1940,8 +2079,6 @@ declare global {
  *
  * - Consistent theming with other flow-rdf-ui components.
  * - Additional plugins and charts types for commonly-used charts.
- * - Convenience child components (`flow-ui-chart-data` and `flow-ui-chart-scale`) for defining chart data and scales.
- *
  * @tagname flow-ui-chart
  * @summary The chart component displays Chart.js charts.
  *
@@ -3321,7 +3458,7 @@ declare global {
  * @dependency flow-ui-dialog
  * @dependency flow-ui-button
  *
- * @slot header-text - The gauge's heading text. Alternatively, you can use the `heading` attribute.
+ * @slot title - The gauge's title. Alternatively, you can use the `title` attribute.
  * @slot value - The gauge's value. Alternatively, you can use the `value` attribute.
  * @slot unit - Alternatively, you can use the `unit` attribute.
  * @slot info - The content to display in the gauge's info dialog. If this is set then an info button will be displayed in the gauge's header.
@@ -3329,17 +3466,16 @@ declare global {
  * @csspart base - The component's base wrapper.
  * @csspart header - The gauge's header.
  * @csspart header-icon - The icon in the gauge's header.
- * @csspart header-text - The text in the gauge's header.
+ * @csspart title - The text in the gauge's header.
  * @csspart info-button - The info button in the gauge's header (if info dialog configured).
- *
  */
 declare class FlowUiGauge extends FlowRdfElement {
     static styles: CSSResultGroup;
     private readonly hasSlotController;
     private _formatter;
     private _infoDialog;
-    /** The heading text of the gauge. */
-    heading: string;
+    /** The title text of the gauge. Alternatively, use the `title` slot to enhance the title with HTML markup. */
+    title: string;
     /** The units of the gauge value. */
     units: string;
     /** The value to display in the gauge. */