@nexxtmove/ui 1.47.0 → 1.48.0

package/dist/components/organisms/IconPicker/IconPicker.vue.d.ts

@@ -0,0 +1,142 @@
+/** One icon in the catalogue the consumer hands in. */
+export interface NexxtIconPickerIcon {
+    /** Identity: stored on the model and handed to `iconClass`. */
+    name: string;
+    /** Shown in the trigger and the footer, read out as the cell's name, searched. */
+    label: string;
+    /** Extra search words, e.g. `home` for a house. */
+    terms: string[];
+    /** The ids of the styles the icon exists in; only these are ever drawn or written. */
+    styles: string[];
+}
+/** A category in the rail. */
+export interface NexxtIconPickerCategory {
+    /** Identity of the category, unique within `categories`. */
+    id: string;
+    /** Text of the rail item; the rail sorts on it. */
+    label: string;
+    /** Names of the icons in the category; a name the catalogue does not know is skipped. */
+    icons: string[];
+}
+/** The section above "all icons", e.g. the icons already on the page. */
+export interface NexxtIconPickerPinned {
+    /** Heading of the section, e.g. `'Op deze pagina'`. */
+    label: string;
+    /** Icon names. The current icon always leads the section; two rows at most. */
+    icons: string[];
+}
+/** A style the icons can be drawn in, with the classes that draw it. */
+export interface NexxtIconPickerStyle {
+    /** Identity: what `NexxtIconPickerIcon.styles` lists and the model stores. */
+    id: string;
+    /** Shown behind the icon's label in the trigger, e.g. `'Light'`. */
+    label: string;
+    /** The classes that draw a glyph in this style, next to the class from `iconClass`. */
+    classes: readonly string[];
+}
+/** What the picker reads and writes. */
+export interface NexxtIconPickerValue {
+    /** An icon `name`. */
+    icon: string;
+    /** A style `id`. */
+    style: string;
+}
+/** Overridable copy. Every key is optional and merged per key with the Dutch defaults. */
+export interface NexxtIconPickerMessages {
+    /** In the trigger while there is no value. Defaults to `'Kies een icoon'`. */
+    placeholder?: string;
+    /** Placeholder of the search field. Defaults to `'Zoek in het Engels, bijv. house'`. */
+    searchPlaceholder?: string;
+    /** Accessible name of the search field. Defaults to `'Icoon zoeken'`. */
+    searchLabel?: string;
+    /** Accessible name of the category rail. Defaults to `'Categorieën'`. */
+    categoriesLabel?: string;
+    /** The first rail item, and the heading of the full list under a pinned section. Defaults to `'Alle iconen'`. */
+    allIcons?: string;
+    /** Read out as the description of the current icon. Defaults to `'Huidige keuze'`. */
+    current?: string;
+    /** Heading of the empty search state. Defaults to `'Geen iconen gevonden'`. */
+    emptyTitle?: string;
+    /** Line under the empty heading; receives the trimmed search term. */
+    emptyDescription?: (search: string) => string;
+    /** Button in the empty state that clears the search. Defaults to `'Zoekopdracht wissen'`. */
+    clearSearch?: string;
+    /** Notice under the grid when the catalogue could not be loaded. */
+    catalogueError?: string;
+    /** Button in that notice. Defaults to `'Opnieuw proberen'`. */
+    retry?: string;
+    /** Announced 500ms after a search or a category change; receives the number of icons. */
+    results?: (count: number) => string;
+}
+export interface NexxtIconPickerProps {
+    /** The catalogue. The component fetches nothing itself: load it on `@open`. */
+    icons: NexxtIconPickerIcon[];
+    /** The categories of the rail, after "Alle iconen"; sorted on label in `sortLocale`. */
+    categories: NexxtIconPickerCategory[];
+    /**
+     * A section above "Alle iconen" while there is no search and no category, e.g. the icons
+     * already on the page. The current icon always leads it; two rows at most. Not shown when it
+     * would be empty.
+     */
+    pinned?: NexxtIconPickerPinned;
+    /**
+     * The styles, in the order of preference: a cell shows its icon in the current style when the
+     * icon has it, otherwise in the first of these it has, and choosing it writes that style.
+     */
+    styles: NexxtIconPickerStyle[];
+    /**
+     * State of fetching the catalogue. `loading` shows skeletons while `icons` is empty; `error`
+     * shows a notice with a retry button. Without a catalogue the current icon stays the one
+     * choosable cell; a search typed meanwhile applies once the catalogue is in.
+     */
+    catalogueStatus?: 'loading' | 'ready' | 'error';
+    /**
+     * The class that picks an icon's glyph, next to the classes of its style. The component knows no
+     * icon set: for Font Awesome it returns the class of the named glyph.
+     */
+    iconClass: (name: string) => string;
+    /**
+     * Visible label above the trigger, for a form. Give this or `ariaLabel`: without either the
+     * trigger has no name for the field, and a development build warns in the console.
+     */
+    label?: string;
+    /**
+     * Accessible name when there is no visible label, as in the editor. The trigger reads it
+     * followed by the icon and its style: "Symbool, Star, Light". Give this or `label`.
+     */
+    ariaLabel?: string;
+    /**
+     * Copy of the trigger and the panel. Merged per key with the Dutch defaults, so overriding one
+     * key keeps the others. Copy is never translated inside the component.
+     */
+    messages?: NexxtIconPickerMessages;
+    /**
+     * Where the panel opens. `left` is for a picker in a side panel: the panel opens beside it, top
+     * aligned, and below it (right aligned) when the room on the left is less than the panel plus
+     * an 8px viewport margin.
+     */
+    side?: 'bottom' | 'left';
+    /** Distance between trigger and panel when it opens to the left, e.g. to clear a panel edge. */
+    sideOffset?: number;
+    /** Locale the rail and the grid sort their labels in. */
+    sortLocale?: string;
+}
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: import('vue').DefineComponent<NexxtIconPickerProps & {
+    /** The chosen icon and style. Only a choice writes the model; moving the highlight never does. */
+    modelValue?: NexxtIconPickerValue | null;
+}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    close: () => any;
+    "update:modelValue": (value: NexxtIconPickerValue | null) => any;
+    open: () => any;
+    retry: () => any;
+}, string, import('vue').PublicProps, Readonly<NexxtIconPickerProps & {
+    /** The chosen icon and style. Only a choice writes the model; moving the highlight never does. */
+    modelValue?: NexxtIconPickerValue | null;
+}> & Readonly<{
+    onClose?: (() => any) | undefined;
+    "onUpdate:modelValue"?: ((value: NexxtIconPickerValue | null) => any) | undefined;
+    onOpen?: (() => any) | undefined;
+    onRetry?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;

package/dist/components/organisms/IconPicker/_IconPickerGrid.vue.d.ts

@@ -0,0 +1,40 @@
+import { IconPickerGridHandle } from './useIconPickerNavigation';
+import { NexxtIconPickerIcon } from './IconPicker.vue';
+import { GridPosition, GridRow } from './useIconPickerCatalogue';
+interface IconPickerGridProps {
+    /** Every row of the list on show; only those in view (and the overscan) are rendered. */
+    rows: GridRow[];
+    /** Skeleton cells instead of the rows: the catalogue is on its way. */
+    skeleton?: boolean;
+    /** Id of the grid element, for the search field's `aria-controls`. */
+    gridId: string;
+    /** Id of the active tab that names the grid. */
+    labelledby: string;
+    /** A cell's id is this prefix, its row and its column. */
+    cellIdPrefix: string;
+    /** Id of the hidden "Huidige keuze", the description of the selected cell. */
+    currentDescriptionId: string;
+    /** The highlighted cell; drawn while the grid has focus. */
+    highlight: GridPosition | null;
+    /** Whether the grid has focus. */
+    focused: boolean;
+    /** The one selected cell: the first place of the current icon. */
+    selected: GridPosition | null;
+    /** The classes that draw an icon's glyph in the style a choice would write. */
+    glyphClass: (icon: NexxtIconPickerIcon) => string[];
+}
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: import('vue').DefineComponent<IconPickerGridProps, IconPickerGridHandle, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    focus: () => any;
+    blur: () => any;
+    keydown: (event: KeyboardEvent) => any;
+    hover: (position: GridPosition) => any;
+    choose: (icon: NexxtIconPickerIcon) => any;
+}, string, import('vue').PublicProps, Readonly<IconPickerGridProps> & Readonly<{
+    onFocus?: (() => any) | undefined;
+    onBlur?: (() => any) | undefined;
+    onKeydown?: ((event: KeyboardEvent) => any) | undefined;
+    onHover?: ((position: GridPosition) => any) | undefined;
+    onChoose?: ((icon: NexxtIconPickerIcon) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;

package/dist/components/organisms/IconPicker/_IconPickerRail.vue.d.ts

@@ -0,0 +1,22 @@
+import { RailTab } from './useIconPickerCatalogue';
+interface IconPickerRailProps {
+    /** "Alle iconen" first, then the categories that hold an icon, sorted. */
+    tabs: RailTab[];
+    /** Index of the selected tab in `tabs`: the one tab stop. */
+    activeIndex: number;
+    /** Accessible name of the tablist. */
+    label: string;
+    /** Id of the tab panel every tab controls. */
+    panelId: string;
+    /** The id of the tab at an index; the tab panel and the grid are labelled by the active one. */
+    tabId: (index: number) => string;
+    /** Skeleton bars after the tabs: the categories are on their way. */
+    loading?: boolean;
+}
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: import('vue').DefineComponent<IconPickerRailProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    select: (id: string | null) => any;
+}, string, import('vue').PublicProps, Readonly<IconPickerRailProps> & Readonly<{
+    onSelect?: ((id: string | null) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;

package/dist/components/organisms/IconPicker/iconPickerHelpers.d.ts

@@ -0,0 +1,39 @@
+import { NexxtIconPickerIcon } from './IconPicker.vue';
+/**
+ * The pure parts of `NexxtIconPicker`: the label of an icon outside the catalogue, the sort, the
+ * search and the style an icon is drawn in. Generic like the picker itself: no icon set, no class
+ * names.
+ */
+/** The locale rail and grid sort in unless the consumer gives another. */
+export declare const DEFAULT_SORT_LOCALE = "nl";
+/** An icon in the search index: its words prepared once, not per keystroke. */
+export interface NexxtIconPickerSearchEntry {
+    icon: NexxtIconPickerIcon;
+    /** The label, lower case. */
+    label: string;
+    /** Name, label and terms in one lower-case string, for the substring match. */
+    haystack: string;
+    /** The words of the name and the label, for "a word starts with". */
+    words: string[];
+}
+/**
+ * `house-chimney` → `House chimney`. What an icon is called while the catalogue that holds its
+ * label is not in yet, and the label a catalogue can derive for every icon whose label is just its
+ * name.
+ */
+export declare const iconLabelFromName: (name: string) => string;
+/** A sorted copy, alphabetical on label in `locale`. */
+export declare const sortIconsByLabel: (icons: readonly NexxtIconPickerIcon[], locale?: string) => NexxtIconPickerIcon[];
+/** Sorted by label, so the stable sort of a search keeps every rank in alphabetical order. */
+export declare const iconSearchIndex: (icons: readonly NexxtIconPickerIcon[], locale?: string) => NexxtIconPickerSearchEntry[];
+/**
+ * Every word of the search has to occur in the name, the label or the terms (AND, any case); the
+ * results come in the order of `searchRank`, alphabetical within a rank. An empty search finds
+ * nothing.
+ */
+export declare const searchIcons: (index: readonly NexxtIconPickerSearchEntry[], search: string) => NexxtIconPickerIcon[];
+/**
+ * The style an icon is drawn and chosen in: the given one when the icon has it, otherwise the
+ * first of `order` it has. `null` only for an icon that has none of the styles in `order`.
+ */
+export declare const iconStyleFor: (styles: readonly string[], preferred: string | undefined, order: readonly string[]) => string | null;

package/dist/components/organisms/IconPicker/useIconPickerCatalogue.d.ts

@@ -0,0 +1,72 @@
+import { MaybeRefOrGetter, Ref } from 'vue';
+import { NexxtIconPickerCategory, NexxtIconPickerIcon, NexxtIconPickerPinned, NexxtIconPickerStyle, NexxtIconPickerValue } from './IconPicker.vue';
+/**
+ * Six columns with a 12px gap (`gap-3`) scan more easily than eight close together. `grid-cols-6`
+ * in `_IconPickerGrid.vue` is the same number: change both together.
+ */
+export declare const COLUMNS = 6;
+/** A line of the grid: a section heading, or up to `COLUMNS` icons. */
+export type GridRow = {
+    kind: 'heading';
+    key: string;
+    label: string;
+} | {
+    kind: 'icons';
+    key: string;
+    icons: NexxtIconPickerIcon[];
+};
+/** A cell, by its index in the rows and its column. */
+export interface GridPosition {
+    row: number;
+    col: number;
+}
+/** A rail item; `null` is "all icons". */
+export interface RailTab {
+    id: string | null;
+    label: string;
+}
+interface IconPickerCatalogueOptions {
+    icons: MaybeRefOrGetter<NexxtIconPickerIcon[]>;
+    categories: MaybeRefOrGetter<NexxtIconPickerCategory[]>;
+    pinned: MaybeRefOrGetter<NexxtIconPickerPinned | undefined>;
+    styles: MaybeRefOrGetter<NexxtIconPickerStyle[]>;
+    /** A getter, never the function itself: `toValue` would call that without a name. */
+    iconClass: () => (name: string) => string;
+    sortLocale: MaybeRefOrGetter<string>;
+    /** Heading of the full list under a pinned section. */
+    allIconsLabel: MaybeRefOrGetter<string>;
+    model: Ref<NexxtIconPickerValue | null>;
+    /** The trimmed search. */
+    term: Ref<string>;
+    /** The chosen category; `null` is "all icons". */
+    category: Ref<string | null>;
+}
+/**
+ * What the picker shows, derived from the catalogue, the model, the search and the category: the
+ * rail's categories, the grid's rows and where the current icon is in them, and the classes that
+ * draw a glyph. No DOM, no focus: that is `useIconPickerNavigation` and the parts.
+ */
+export declare const useIconPickerCatalogue: (options: IconPickerCatalogueOptions) => {
+    shownCategories: import('vue').ComputedRef<{
+        id: string;
+        label: string;
+        icons: NexxtIconPickerIcon[];
+    }[]>;
+    activeCategory: import('vue').ComputedRef<{
+        id: string;
+        label: string;
+        icons: NexxtIconPickerIcon[];
+    } | null>;
+    catalogueEmpty: import('vue').ComputedRef<boolean>;
+    currentIcon: import('vue').ComputedRef<NexxtIconPickerIcon | null>;
+    currentStyle: import('vue').ComputedRef<NexxtIconPickerStyle | null>;
+    rows: import('vue').ComputedRef<GridRow[]>;
+    iconRows: import('vue').ComputedRef<number[]>;
+    iconCount: import('vue').ComputedRef<number>;
+    currentPosition: import('vue').ComputedRef<GridPosition | null>;
+    rowLength: (row: number | undefined) => number;
+    iconAt: (position: GridPosition | null) => NexxtIconPickerIcon | null;
+    styleOf: (icon: NexxtIconPickerIcon) => string | null;
+    glyphClass: (icon: NexxtIconPickerIcon, style?: string | null) => string[];
+};
+export {};

package/dist/components/organisms/IconPicker/useIconPickerNavigation.d.ts

@@ -0,0 +1,60 @@
+import { ComputedRef, Ref } from 'vue';
+import { NexxtIconPickerIcon } from './IconPicker.vue';
+import { GridPosition } from './useIconPickerCatalogue';
+/** What the grid part exposes: the parts of navigating that need its scroll box. */
+export interface IconPickerGridHandle {
+    /** Focus the grid itself; the highlight is its active descendant. */
+    focus: () => void;
+    /** Scroll the least needed to show the row, and render the rows there at once. */
+    reveal: (row: number) => void;
+    /** Whether the row is fully in view. */
+    inView: (row: number) => boolean;
+    /** The rows that fit in view, less one, at least one. */
+    pageRows: () => number;
+    scrollToTop: () => void;
+}
+interface IconPickerNavigationOptions {
+    /** The indexes of the rows that hold icons, in order. */
+    iconRows: ComputedRef<number[]>;
+    currentPosition: ComputedRef<GridPosition | null>;
+    iconCount: ComputedRef<number>;
+    catalogueEmpty: ComputedRef<boolean>;
+    iconAt: (position: GridPosition | null) => NexxtIconPickerIcon | null;
+    rowLength: (row: number | undefined) => number;
+    /** The raw search: a letter typed in the grid is appended to it. */
+    search: Ref<string>;
+    /** The trimmed search. */
+    term: ComputedRef<string>;
+    category: Ref<string | null>;
+    isOpen: Ref<boolean>;
+    grid: () => IconPickerGridHandle | null | undefined;
+    focusSearch: () => void;
+    choose: (icon: NexxtIconPickerIcon) => void;
+    /** The copy of the announcement. */
+    results: () => (count: number) => string;
+}
+/**
+ * The keyboard, highlight and focus state of the picker: the highlighted cell and whether the grid
+ * has focus, the keys of the search field and the grid, the move from one to the other, and the
+ * results count for the live region. Only a choice writes the model; moving the highlight never does.
+ */
+export declare const useIconPickerNavigation: (options: IconPickerNavigationOptions) => {
+    highlight: Ref<{
+        row: number;
+        col: number;
+    } | null, GridPosition | {
+        row: number;
+        col: number;
+    } | null>;
+    highlightedIcon: ComputedRef<NexxtIconPickerIcon | null>;
+    gridFocused: Ref<boolean, boolean>;
+    announcement: Ref<string, string>;
+    open: (reset: () => void) => void;
+    close: () => void;
+    onGridFocus: () => void;
+    onGridBlur: () => void;
+    onCellHover: (position: GridPosition) => void;
+    onGridKeydown: (event: KeyboardEvent) => void;
+    onSearchKeydown: (event: KeyboardEvent) => void;
+};
+export {};

package/dist/index.d.ts

@@ -41,6 +41,9 @@ export type { EditorLetterSpacingMessages, EditorLetterSpacingValue, NexxtEditor
 export { EDITOR_FONT_SIZE_STEPS } from './components/editor/molecules/EditorFontSize/EditorFontSize.vue';
 export type { EditorFontSizeMessages, EditorFontSizeValue, NexxtEditorFontSizeProps, } from './components/editor/molecules/EditorFontSize/EditorFontSize.vue';
 export type { NexxtFontPickerFont, NexxtFontPickerInherit, NexxtFontPickerMessages, NexxtFontPickerProps, } from './components/organisms/FontPicker/FontPicker.vue';
+export type { NexxtIconPickerCategory, NexxtIconPickerIcon, NexxtIconPickerMessages, NexxtIconPickerPinned, NexxtIconPickerProps, NexxtIconPickerStyle, NexxtIconPickerValue, } from './components/organisms/IconPicker/IconPicker.vue';
+export { iconLabelFromName, iconSearchIndex, iconStyleFor, searchIcons, sortIconsByLabel, } from './components/organisms/IconPicker/iconPickerHelpers';
+export type { NexxtIconPickerSearchEntry } from './components/organisms/IconPicker/iconPickerHelpers';
 export { EDITOR_PADDING_STEPS } from './components/editor/molecules/EditorPadding/EditorPadding.vue';
 export type { EditorPaddingMessages, EditorPaddingStep, } from './components/editor/molecules/EditorPadding/EditorPadding.vue';
 export { EDITOR_DIMENSION_LIMITS } from './components/editor/atoms/EditorDimensionField/EditorDimensionField.vue';
@@ -100,6 +103,7 @@ export { default as NexxtFloatingPanel } from './components/atoms/FloatingPanel/
 export { default as NexxtFontPicker } from './components/organisms/FontPicker/FontPicker.vue';
 export { default as NexxtHeader } from './components/organisms/Header/Header.vue';
 export { default as NexxtIcon } from './components/atoms/Icon/Icon.vue';
+export { default as NexxtIconPicker } from './components/organisms/IconPicker/IconPicker.vue';
 export { default as NexxtInfoBlock } from './components/molecules/InfoBlock/InfoBlock.vue';
 export { default as NexxtInputField } from './components/molecules/InputField/InputField.vue';
 export { default as NexxtInputSelect } from './components/molecules/InputSelect/InputSelect.vue';