@webx-ui/core 0.38.0 → 0.40.0

package/dist/composables/useTokens.d.ts

@@ -0,0 +1,94 @@
+/**
+ * One placeholder a text field offers: `[name]` in the text, which whoever prints the text swaps
+ * for something else — a phone number kept in settings, the year, a company name.
+ *
+ * The field never swaps anything itself. It stores the brackets as typed and only helps to type
+ * them: a list that opens on `[`, a button with every placeholder there is, and the known ones
+ * drawn as chips so they read as one thing rather than as punctuation.
+ */
+export interface TokenOption {
+    /** What goes between the brackets: `/^[a-z][a-z0-9_-]{0,63}$/`. */
+    name: string;
+    /** What it stands for right now, shown beside the name as a hint. */
+    value?: string;
+    /** One line about what it is, for a name that does not say. */
+    description?: string;
+}
+/** The props every field that offers placeholders shares. */
+export interface TokenFieldProps {
+    /** Placeholders to suggest on `[` and to draw as chips. Nothing changes without them. */
+    tokens?: TokenOption[];
+    /** Heading of the list the help button opens. */
+    tokensTitle?: string;
+    /** Accessible name and tooltip of the help button. */
+    tokensLabel?: string;
+}
+export declare const TOKEN_NAME: RegExp;
+export interface TokenSpan {
+    from: number;
+    to: number;
+    name: string;
+}
+/** Where the known placeholders of a text are. Unknown names and `[[escaped]]` ones are text. */
+export declare function tokenSpans(text: string, known: ReadonlySet<string>): TokenSpan[];
+export interface TokenSegment {
+    text: string;
+    token: string | null;
+}
+/** The text cut at its placeholders — what a mirror behind a plain field draws. */
+export declare function tokenSegments(text: string, known: ReadonlySet<string>): TokenSegment[];
+/**
+ * The placeholder being typed right before the caret: `[` and the start of a name. A `[` after
+ * another `[` is the start of an escaped one, and nobody wants a list for that.
+ */
+export declare function tokenQuery(before: string): {
+    from: number;
+    query: string;
+} | null;
+/** The text a chosen placeholder is written as. */
+export declare function tokenText(token: TokenOption): string;
+/** Where the list hangs from: a rectangle in the viewport, and the element it scrolls with. */
+export interface TokenAnchor {
+    getBoundingClientRect: () => DOMRect;
+    contextElement?: Element;
+}
+export declare function tokenAnchor(rect: DOMRect, owner: Element | null): TokenAnchor;
+/** A rectangle by hand: `new DOMRect` is not everywhere these fields are rendered. */
+export declare function rectOf(x: number, y: number, width: number, height: number): DOMRect;
+/**
+ * Under the field, at the caret's column: the list of a one-line field hangs from the field's
+ * bottom edge rather than from the caret, so it never covers the line being typed.
+ */
+export declare function fieldAnchor(owner: HTMLElement | null, caret: DOMRect | null): TokenAnchor | undefined;
+/**
+ * The rectangle of one character of an element's text, by its offset — the caret's place in a
+ * mirror that draws the same text as the field in the same box. Null where layout is not
+ * measured (a test), and the caller falls back to the field.
+ */
+export declare function textRect(root: HTMLElement, offset: number): DOMRect | null;
+export interface TokenRange {
+    from: number;
+    to: number;
+}
+/**
+ * The list of placeholders and what the keyboard does to it, for any field — where the text is
+ * and how a choice is written back is the field's business.
+ *
+ * Two ways in: typing (`[ph` before the caret, the list filtered by it, the choice replacing it)
+ * and browsing (the help button, every placeholder, the choice going where the caret is).
+ */
+export declare function useTokenMenu(tokens: () => TokenOption[] | undefined): {
+    open: import('vue').Ref<boolean, boolean>;
+    browsing: import('vue').Ref<boolean, boolean>;
+    items: import('vue').ComputedRef<TokenOption[]>;
+    active: import('vue').Ref<number, number>;
+    anchor: import('vue').ShallowRef<TokenAnchor | undefined, TokenAnchor | undefined>;
+    all: import('vue').ComputedRef<TokenOption[]>;
+    known: import('vue').ComputedRef<ReadonlySet<string>>;
+    close: () => void;
+    suggest: (before: string, caret: number, at: () => TokenAnchor | undefined) => void;
+    browse: (at: TokenRange, where: TokenAnchor | undefined) => void;
+    choose: (token: TokenOption, insert: (token: TokenOption, at: TokenRange) => void) => void;
+    keydown: (event: KeyboardEvent, insert: (token: TokenOption, at: TokenRange) => void) => boolean;
+};
+export type TokenMenu = ReturnType<typeof useTokenMenu>;

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { WebxUI, type WebxUiOptions } from './plugin';
 export type { ControlSize, ControlStatus, ValidationErrors } from './composables/useFormField';
 export { useControlAttrs, type ControlAttrs } from './composables/useControlAttrs';
 export { provideLocales, useLocales, useLocalized, localeLabel, localizedValue, localesKey, type LocaleOption, type LocalesContext, type LocalizedValue, type LocalizedFieldProps, } from './composables/useLocalized';
+export { tokenSpans, tokenQuery, type TokenFieldProps, type TokenOption, type TokenSpan, } from './composables/useTokens';
 export { provideDateLocale, useDateLocale, dateLocaleKey, type DateLocaleSource, } from './composables/useDateLocale';
 export { provideDateTimezone, useDateTimezone, dateTimezoneKey, type DateTimezoneSource, } from './composables/useDateTimezone';
 export type { DateFnsLocale } from './internal/dateLocale';