@samline/string 1.0.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1 +1,254 @@
1
- export { CaseOptions, InitialsOptions, SlugifyOptions, TitleCaseOptions, TruncateOptions, camelCase, capitalize, constantCase, dotCase, initials, kebabCase, pascalCase, removeAccents, sentenceCase, slugify, snakeCase, titleCase, truncate, uncapitalize, words } from '../index.cjs';
1
+ import { ConvertOptions, Conversion, HashColorOptions, MatchOptions, TruncatePosition } from '../index.cjs';
2
+ export { CHAR_MAPS, CONVERSIONS, CYRILLIC, CaseOptions, CharMap, CharMapName, ClosestOptions, CompareOptions, FoldOptions, GERMAN, GREEK, HighlightSegment, InitialsOptions, PluralForms, PluralizeOptions, ReadingTime, ReadingTimeOptions, RemoveAccentsOptions, Replacements, SimilarityOptions, SlugifyOptions, TakenSlugs, TemplateOptions, TitleCaseOptions, TruncateOptions, UniqueSlugOptions, WordCountOptions, camelCase, capitalize, closest, compareNatural, constantCase, contains, convert, distance, dotCase, escapeHtml, fold, graphemes, hashColor, highlight, initials, isConversion, kebabCase, pascalCase, pathCase, pluralize, readingTime, removeAccents, sentenceCase, similarity, slugify, snakeCase, stripTags, template, titleCase, trainCase, truncate, uncapitalize, unescapeHtml, uniqueSlug, wordCount, words } from '../index.cjs';
3
+
4
+ /** Anything a utility accepts as its target. */
5
+ type ElementTarget = Element | string | Iterable<Element> | ArrayLike<Element> | null | undefined;
6
+ interface AutoInitController {
7
+ /** Initialize matching elements that are not initialized yet. */
8
+ refresh: () => void;
9
+ /** Run every cleanup and stop watching. */
10
+ destroy: () => void;
11
+ }
12
+
13
+ declare const ATTRIBUTE = "data-string";
14
+ declare const STATE_ATTRIBUTE = "data-string-state";
15
+ declare const CHANGE_EVENT = "string:change";
16
+ /** CSS custom property set by `data-string-color`. */
17
+ declare const COLOR_PROPERTY = "--string-color";
18
+ /**
19
+ * - `ready`: the element shows its converted text.
20
+ * - `following`: a field copies its converted `source` (a slug that follows the title).
21
+ * - `edited`: the user typed in a field that had a `source`; it no longer follows.
22
+ */
23
+ type StringState = 'ready' | 'following' | 'edited';
24
+ interface StringOptions extends ConvertOptions {
25
+ /** The conversion. `data-string="kebab"` wins over this option. */
26
+ to?: Conversion;
27
+ /**
28
+ * An input, textarea or element whose text feeds this element, for example
29
+ * the title that fills a slug field. `data-string-source="#title"`.
30
+ */
31
+ source?: ElementTarget;
32
+ /**
33
+ * Convert fields while the user types (separators the user just typed are
34
+ * kept until the field loses focus). Defaults to `true`; `false` converts on
35
+ * blur only. `truncate` and `initials` always wait for blur.
36
+ */
37
+ live?: boolean;
38
+ /** Called with the new value after every conversion that changed it. */
39
+ onChange?: (value: string, element: HTMLElement) => void;
40
+ /**
41
+ * Set `--string-color` to a stable color for the text (before conversion),
42
+ * for avatar backgrounds: `background: var(--string-color)`. `true` or
43
+ * `hashColor` options. `data-string-color` turns it on.
44
+ */
45
+ color?: boolean | HashColorOptions;
46
+ }
47
+ interface StringController {
48
+ /** Read the attributes again and convert again. */
49
+ refresh: () => void;
50
+ /** Remove every listener and restore the original markup. Safe to call twice. */
51
+ destroy: () => void;
52
+ }
53
+ interface AutoStringOptions extends StringOptions {
54
+ /** Elements to convert. Defaults to `[data-string]`. */
55
+ selector?: string;
56
+ /** Where to look. Defaults to `document`. */
57
+ scope?: ParentNode;
58
+ /** Pick up elements added later and clean up removed ones. Defaults to `true`. */
59
+ observe?: boolean;
60
+ }
61
+ /**
62
+ * Convert text in the page from HTML attributes.
63
+ *
64
+ * - On any element, `data-string="kebab"` replaces its text with the
65
+ * converted text; `destroy()` puts the original markup back.
66
+ * - On an input or textarea, the value is converted as the user types and
67
+ * finalized on blur.
68
+ * - With `data-string-source="#title"`, the element follows another field:
69
+ * a slug field fills itself from the title until the user edits it, and
70
+ * follows again when the user empties it.
71
+ *
72
+ * Returns `{ refresh, destroy }`. Without a DOM it does nothing.
73
+ */
74
+ declare const string: (target?: ElementTarget, options?: StringOptions) => StringController;
75
+ /**
76
+ * Convert every `[data-string]` element in `scope`, including elements added
77
+ * later, and clean up elements that are removed.
78
+ */
79
+ declare const autoString: ({ selector, scope, observe, ...options }?: AutoStringOptions) => AutoInitController;
80
+
81
+ declare const SEARCH_ATTRIBUTE = "data-string-search";
82
+ declare const SEARCH_STATE_ATTRIBUTE = "data-string-search-state";
83
+ declare const SEARCH_EMPTY_ATTRIBUTE = "data-string-search-empty";
84
+ declare const SEARCH_EVENT = "string:search";
85
+ /**
86
+ * - `idle`: the query is shorter than `min`; every item is shown.
87
+ * - `results`: at least one item matches.
88
+ * - `empty`: nothing matches; the empty message is shown.
89
+ */
90
+ type SearchState = 'idle' | 'results' | 'empty';
91
+ interface SearchResult {
92
+ query: string;
93
+ /** Items that match, in document order. */
94
+ matches: HTMLElement[];
95
+ /** Number of items searched. */
96
+ total: number;
97
+ state: SearchState;
98
+ }
99
+ interface SearchOptions extends MatchOptions {
100
+ /** The search field. `data-string-search="#q"` wins over this option. */
101
+ input?: ElementTarget;
102
+ /** Selector for the items inside the list. Defaults to its direct children. */
103
+ items?: string;
104
+ /** Wrap matching text in `<mark>`. Defaults to `true`. */
105
+ highlight?: boolean;
106
+ /** Shortest query that filters, in characters. Defaults to `1`. */
107
+ min?: number;
108
+ /** Element shown when nothing matches. Defaults to a `[data-string-search-empty]` child. */
109
+ empty?: ElementTarget;
110
+ /** Called after every search. */
111
+ onSearch?: (result: SearchResult, list: HTMLElement) => void;
112
+ }
113
+ interface SearchController {
114
+ /** Collect the items again (after adding or removing some) and search again. */
115
+ refresh: () => void;
116
+ /** Remove listeners and marks and show every item as it was. Safe to call twice. */
117
+ destroy: () => void;
118
+ }
119
+ interface AutoSearchOptions extends SearchOptions {
120
+ /** Lists to filter. Defaults to `[data-string-search]`. */
121
+ selector?: string;
122
+ /** Where to look. Defaults to `document`. */
123
+ scope?: ParentNode;
124
+ /** Pick up lists added later and clean up removed ones. Defaults to `true`. */
125
+ observe?: boolean;
126
+ }
127
+ /**
128
+ * Filter a list as the user types, ignoring accents and case, and highlight
129
+ * the matching text.
130
+ *
131
+ * ```html
132
+ * <input id="q" type="search" />
133
+ * <ul data-string-search="#q">
134
+ * <li>Café de olla</li>
135
+ * <li hidden data-string-search-empty>No results</li>
136
+ * </ul>
137
+ * ```
138
+ *
139
+ * Items that do not match get `hidden`; matches are wrapped in `<mark>`.
140
+ * Returns `{ refresh, destroy }`. Without a DOM it does nothing.
141
+ */
142
+ declare const search: (target?: ElementTarget, options?: SearchOptions) => SearchController;
143
+ /** Filter every `[data-string-search]` list in `scope`, including lists added later. */
144
+ declare const autoSearch: ({ selector, scope, observe, ...options }?: AutoSearchOptions) => AutoInitController;
145
+
146
+ interface Controller {
147
+ /** Read the attributes again and update. */
148
+ refresh: () => void;
149
+ /** Remove listeners and restore the original markup. Safe to call twice. */
150
+ destroy: () => void;
151
+ }
152
+ interface AutoOptions {
153
+ /** Elements to start. Defaults to the behavior's attribute. */
154
+ selector?: string;
155
+ /** Where to look. Defaults to `document`. */
156
+ scope?: ParentNode;
157
+ /** Pick up elements added later and clean up removed ones. Defaults to `true`. */
158
+ observe?: boolean;
159
+ }
160
+
161
+ declare const COUNT_ATTRIBUTE = "data-string-count";
162
+ declare const COUNT_STATE_ATTRIBUTE = "data-string-count-state";
163
+ declare const COUNT_EVENT = "string:count";
164
+ /** `ok` below `near`, `near` when few are left, `over` past `max`. */
165
+ type CountState = 'ok' | 'near' | 'over';
166
+ type CountUnit = 'characters' | 'words';
167
+ interface CountInfo {
168
+ count: number;
169
+ /** `undefined` without a maximum. */
170
+ max: number | undefined;
171
+ /** `max - count`, negative when over; `undefined` without a maximum. */
172
+ remaining: number | undefined;
173
+ state: CountState;
174
+ }
175
+ interface CountOptions {
176
+ /** The field to count. `data-string-count="#bio"` wins over this option. */
177
+ field?: ElementTarget;
178
+ /** Count characters (graphemes, so 😀 is one) or words. Defaults to `'characters'`. */
179
+ unit?: CountUnit;
180
+ /** Maximum. Defaults to the field's `maxlength`, if any. */
181
+ max?: number;
182
+ /** Remaining count at which the state becomes `near`. Defaults to 10% of `max`. */
183
+ near?: number;
184
+ /**
185
+ * Text shown: a template with `{count}`, `{max}` and `{remaining}`, or a
186
+ * function. Defaults to `'{remaining}'` with a maximum and `'{count}'` without.
187
+ */
188
+ format?: string | ((info: CountInfo) => string);
189
+ /** Locale for word boundaries. */
190
+ locale?: string | string[];
191
+ /** Called after every update. */
192
+ onCount?: (info: CountInfo, element: HTMLElement) => void;
193
+ }
194
+ type AutoCountOptions = CountOptions & AutoOptions;
195
+ /**
196
+ * Show how many characters or words a field has, or how many are left:
197
+ * `<textarea id="bio" maxlength="160"></textarea>
198
+ * <output data-string-count="#bio"></output>`.
199
+ */
200
+ declare const count: (target?: ElementTarget, options?: CountOptions) => Controller;
201
+ /** Start every `[data-string-count]` element in `scope`, including elements added later. */
202
+ declare const autoCount: ({ selector: chosen, scope, observe, ...options }?: AutoOptions & CountOptions) => AutoInitController;
203
+
204
+ declare const FIT_ATTRIBUTE = "data-string-fit";
205
+ declare const FIT_STATE_ATTRIBUTE = "data-string-fit-state";
206
+ /** `full` when the whole text fits, `truncated` when it was shortened. */
207
+ type FitState = 'full' | 'truncated';
208
+ interface FitOptions {
209
+ /** Where the text is cut. `data-string-fit="end"` wins. Defaults to `'middle'`. */
210
+ position?: TruncatePosition;
211
+ /** Defaults to `'…'`. */
212
+ ellipsis?: string;
213
+ }
214
+ type AutoFitOptions = FitOptions & AutoOptions;
215
+ /**
216
+ * Shorten text to fit its element's width, cutting in the middle by
217
+ * default, and fit again when the width changes:
218
+ * `<span data-string-fit style="display: block">annual-report-2026-final.pdf</span>`.
219
+ * The element needs a width (block, inline-block, flex or grid item).
220
+ */
221
+ declare const fit: (target?: ElementTarget, options?: FitOptions) => Controller;
222
+ /** Start every `[data-string-fit]` element in `scope`, including elements added later. */
223
+ declare const autoFit: ({ selector: chosen, scope, observe, ...options }?: AutoOptions & FitOptions) => AutoInitController;
224
+
225
+ declare const COPY_ATTRIBUTE = "data-string-copy";
226
+ declare const COPY_STATE_ATTRIBUTE = "data-string-copy-state";
227
+ declare const COPY_EVENT = "string:copy";
228
+ /** `copied` or `error` for `reset` milliseconds after a click. */
229
+ type CopyState = 'copied' | 'error';
230
+ interface CopyDetail {
231
+ value: string;
232
+ ok: boolean;
233
+ }
234
+ interface CopyOptions extends ConvertOptions {
235
+ /** Element or field whose text is copied. `data-string-copy="#title"` wins. */
236
+ source?: ElementTarget;
237
+ /** Conversion applied before copying. `data-string-copy-as="kebab"` wins. */
238
+ as?: Conversion;
239
+ /** Milliseconds before the state is cleared. Defaults to `2000`. */
240
+ reset?: number;
241
+ /** Called after every copy attempt. */
242
+ onCopy?: (detail: CopyDetail, button: HTMLElement) => void;
243
+ }
244
+ type AutoCopyOptions = CopyOptions & AutoOptions;
245
+ /**
246
+ * Copy another element's text, converted, to the clipboard:
247
+ * `<button data-string-copy="#title" data-string-copy-as="kebab">Copy</button>`.
248
+ * The button gets `data-string-copy-state="copied"` (or `error`) for two seconds.
249
+ */
250
+ declare const copy: (target?: ElementTarget, options?: CopyOptions) => Controller;
251
+ /** Start every `[data-string-copy]` button in `scope`, including buttons added later. */
252
+ declare const autoCopy: ({ selector: chosen, scope, observe, ...options }?: AutoOptions & CopyOptions) => AutoInitController;
253
+
254
+ export { ATTRIBUTE, type AutoCopyOptions, type AutoCountOptions, type AutoFitOptions, type AutoInitController, type AutoOptions, type AutoSearchOptions, type AutoStringOptions, CHANGE_EVENT, COLOR_PROPERTY, COPY_ATTRIBUTE, COPY_EVENT, COPY_STATE_ATTRIBUTE, COUNT_ATTRIBUTE, COUNT_EVENT, COUNT_STATE_ATTRIBUTE, type Controller, Conversion, ConvertOptions, type CopyDetail, type CopyOptions, type CopyState, type CountInfo, type CountOptions, type CountState, type CountUnit, type ElementTarget, FIT_ATTRIBUTE, FIT_STATE_ATTRIBUTE, type FitOptions, type FitState, HashColorOptions, MatchOptions, SEARCH_ATTRIBUTE, SEARCH_EMPTY_ATTRIBUTE, SEARCH_EVENT, SEARCH_STATE_ATTRIBUTE, STATE_ATTRIBUTE, type SearchController, type SearchOptions, type SearchResult, type SearchState, type StringController, type StringOptions, type StringState, TruncatePosition, autoCopy, autoCount, autoFit, autoSearch, autoString, copy, count, fit, search, string };
@@ -1 +1,254 @@
1
- export { CaseOptions, InitialsOptions, SlugifyOptions, TitleCaseOptions, TruncateOptions, camelCase, capitalize, constantCase, dotCase, initials, kebabCase, pascalCase, removeAccents, sentenceCase, slugify, snakeCase, titleCase, truncate, uncapitalize, words } from '../index.js';
1
+ import { ConvertOptions, Conversion, HashColorOptions, MatchOptions, TruncatePosition } from '../index.js';
2
+ export { CHAR_MAPS, CONVERSIONS, CYRILLIC, CaseOptions, CharMap, CharMapName, ClosestOptions, CompareOptions, FoldOptions, GERMAN, GREEK, HighlightSegment, InitialsOptions, PluralForms, PluralizeOptions, ReadingTime, ReadingTimeOptions, RemoveAccentsOptions, Replacements, SimilarityOptions, SlugifyOptions, TakenSlugs, TemplateOptions, TitleCaseOptions, TruncateOptions, UniqueSlugOptions, WordCountOptions, camelCase, capitalize, closest, compareNatural, constantCase, contains, convert, distance, dotCase, escapeHtml, fold, graphemes, hashColor, highlight, initials, isConversion, kebabCase, pascalCase, pathCase, pluralize, readingTime, removeAccents, sentenceCase, similarity, slugify, snakeCase, stripTags, template, titleCase, trainCase, truncate, uncapitalize, unescapeHtml, uniqueSlug, wordCount, words } from '../index.js';
3
+
4
+ /** Anything a utility accepts as its target. */
5
+ type ElementTarget = Element | string | Iterable<Element> | ArrayLike<Element> | null | undefined;
6
+ interface AutoInitController {
7
+ /** Initialize matching elements that are not initialized yet. */
8
+ refresh: () => void;
9
+ /** Run every cleanup and stop watching. */
10
+ destroy: () => void;
11
+ }
12
+
13
+ declare const ATTRIBUTE = "data-string";
14
+ declare const STATE_ATTRIBUTE = "data-string-state";
15
+ declare const CHANGE_EVENT = "string:change";
16
+ /** CSS custom property set by `data-string-color`. */
17
+ declare const COLOR_PROPERTY = "--string-color";
18
+ /**
19
+ * - `ready`: the element shows its converted text.
20
+ * - `following`: a field copies its converted `source` (a slug that follows the title).
21
+ * - `edited`: the user typed in a field that had a `source`; it no longer follows.
22
+ */
23
+ type StringState = 'ready' | 'following' | 'edited';
24
+ interface StringOptions extends ConvertOptions {
25
+ /** The conversion. `data-string="kebab"` wins over this option. */
26
+ to?: Conversion;
27
+ /**
28
+ * An input, textarea or element whose text feeds this element, for example
29
+ * the title that fills a slug field. `data-string-source="#title"`.
30
+ */
31
+ source?: ElementTarget;
32
+ /**
33
+ * Convert fields while the user types (separators the user just typed are
34
+ * kept until the field loses focus). Defaults to `true`; `false` converts on
35
+ * blur only. `truncate` and `initials` always wait for blur.
36
+ */
37
+ live?: boolean;
38
+ /** Called with the new value after every conversion that changed it. */
39
+ onChange?: (value: string, element: HTMLElement) => void;
40
+ /**
41
+ * Set `--string-color` to a stable color for the text (before conversion),
42
+ * for avatar backgrounds: `background: var(--string-color)`. `true` or
43
+ * `hashColor` options. `data-string-color` turns it on.
44
+ */
45
+ color?: boolean | HashColorOptions;
46
+ }
47
+ interface StringController {
48
+ /** Read the attributes again and convert again. */
49
+ refresh: () => void;
50
+ /** Remove every listener and restore the original markup. Safe to call twice. */
51
+ destroy: () => void;
52
+ }
53
+ interface AutoStringOptions extends StringOptions {
54
+ /** Elements to convert. Defaults to `[data-string]`. */
55
+ selector?: string;
56
+ /** Where to look. Defaults to `document`. */
57
+ scope?: ParentNode;
58
+ /** Pick up elements added later and clean up removed ones. Defaults to `true`. */
59
+ observe?: boolean;
60
+ }
61
+ /**
62
+ * Convert text in the page from HTML attributes.
63
+ *
64
+ * - On any element, `data-string="kebab"` replaces its text with the
65
+ * converted text; `destroy()` puts the original markup back.
66
+ * - On an input or textarea, the value is converted as the user types and
67
+ * finalized on blur.
68
+ * - With `data-string-source="#title"`, the element follows another field:
69
+ * a slug field fills itself from the title until the user edits it, and
70
+ * follows again when the user empties it.
71
+ *
72
+ * Returns `{ refresh, destroy }`. Without a DOM it does nothing.
73
+ */
74
+ declare const string: (target?: ElementTarget, options?: StringOptions) => StringController;
75
+ /**
76
+ * Convert every `[data-string]` element in `scope`, including elements added
77
+ * later, and clean up elements that are removed.
78
+ */
79
+ declare const autoString: ({ selector, scope, observe, ...options }?: AutoStringOptions) => AutoInitController;
80
+
81
+ declare const SEARCH_ATTRIBUTE = "data-string-search";
82
+ declare const SEARCH_STATE_ATTRIBUTE = "data-string-search-state";
83
+ declare const SEARCH_EMPTY_ATTRIBUTE = "data-string-search-empty";
84
+ declare const SEARCH_EVENT = "string:search";
85
+ /**
86
+ * - `idle`: the query is shorter than `min`; every item is shown.
87
+ * - `results`: at least one item matches.
88
+ * - `empty`: nothing matches; the empty message is shown.
89
+ */
90
+ type SearchState = 'idle' | 'results' | 'empty';
91
+ interface SearchResult {
92
+ query: string;
93
+ /** Items that match, in document order. */
94
+ matches: HTMLElement[];
95
+ /** Number of items searched. */
96
+ total: number;
97
+ state: SearchState;
98
+ }
99
+ interface SearchOptions extends MatchOptions {
100
+ /** The search field. `data-string-search="#q"` wins over this option. */
101
+ input?: ElementTarget;
102
+ /** Selector for the items inside the list. Defaults to its direct children. */
103
+ items?: string;
104
+ /** Wrap matching text in `<mark>`. Defaults to `true`. */
105
+ highlight?: boolean;
106
+ /** Shortest query that filters, in characters. Defaults to `1`. */
107
+ min?: number;
108
+ /** Element shown when nothing matches. Defaults to a `[data-string-search-empty]` child. */
109
+ empty?: ElementTarget;
110
+ /** Called after every search. */
111
+ onSearch?: (result: SearchResult, list: HTMLElement) => void;
112
+ }
113
+ interface SearchController {
114
+ /** Collect the items again (after adding or removing some) and search again. */
115
+ refresh: () => void;
116
+ /** Remove listeners and marks and show every item as it was. Safe to call twice. */
117
+ destroy: () => void;
118
+ }
119
+ interface AutoSearchOptions extends SearchOptions {
120
+ /** Lists to filter. Defaults to `[data-string-search]`. */
121
+ selector?: string;
122
+ /** Where to look. Defaults to `document`. */
123
+ scope?: ParentNode;
124
+ /** Pick up lists added later and clean up removed ones. Defaults to `true`. */
125
+ observe?: boolean;
126
+ }
127
+ /**
128
+ * Filter a list as the user types, ignoring accents and case, and highlight
129
+ * the matching text.
130
+ *
131
+ * ```html
132
+ * <input id="q" type="search" />
133
+ * <ul data-string-search="#q">
134
+ * <li>Café de olla</li>
135
+ * <li hidden data-string-search-empty>No results</li>
136
+ * </ul>
137
+ * ```
138
+ *
139
+ * Items that do not match get `hidden`; matches are wrapped in `<mark>`.
140
+ * Returns `{ refresh, destroy }`. Without a DOM it does nothing.
141
+ */
142
+ declare const search: (target?: ElementTarget, options?: SearchOptions) => SearchController;
143
+ /** Filter every `[data-string-search]` list in `scope`, including lists added later. */
144
+ declare const autoSearch: ({ selector, scope, observe, ...options }?: AutoSearchOptions) => AutoInitController;
145
+
146
+ interface Controller {
147
+ /** Read the attributes again and update. */
148
+ refresh: () => void;
149
+ /** Remove listeners and restore the original markup. Safe to call twice. */
150
+ destroy: () => void;
151
+ }
152
+ interface AutoOptions {
153
+ /** Elements to start. Defaults to the behavior's attribute. */
154
+ selector?: string;
155
+ /** Where to look. Defaults to `document`. */
156
+ scope?: ParentNode;
157
+ /** Pick up elements added later and clean up removed ones. Defaults to `true`. */
158
+ observe?: boolean;
159
+ }
160
+
161
+ declare const COUNT_ATTRIBUTE = "data-string-count";
162
+ declare const COUNT_STATE_ATTRIBUTE = "data-string-count-state";
163
+ declare const COUNT_EVENT = "string:count";
164
+ /** `ok` below `near`, `near` when few are left, `over` past `max`. */
165
+ type CountState = 'ok' | 'near' | 'over';
166
+ type CountUnit = 'characters' | 'words';
167
+ interface CountInfo {
168
+ count: number;
169
+ /** `undefined` without a maximum. */
170
+ max: number | undefined;
171
+ /** `max - count`, negative when over; `undefined` without a maximum. */
172
+ remaining: number | undefined;
173
+ state: CountState;
174
+ }
175
+ interface CountOptions {
176
+ /** The field to count. `data-string-count="#bio"` wins over this option. */
177
+ field?: ElementTarget;
178
+ /** Count characters (graphemes, so 😀 is one) or words. Defaults to `'characters'`. */
179
+ unit?: CountUnit;
180
+ /** Maximum. Defaults to the field's `maxlength`, if any. */
181
+ max?: number;
182
+ /** Remaining count at which the state becomes `near`. Defaults to 10% of `max`. */
183
+ near?: number;
184
+ /**
185
+ * Text shown: a template with `{count}`, `{max}` and `{remaining}`, or a
186
+ * function. Defaults to `'{remaining}'` with a maximum and `'{count}'` without.
187
+ */
188
+ format?: string | ((info: CountInfo) => string);
189
+ /** Locale for word boundaries. */
190
+ locale?: string | string[];
191
+ /** Called after every update. */
192
+ onCount?: (info: CountInfo, element: HTMLElement) => void;
193
+ }
194
+ type AutoCountOptions = CountOptions & AutoOptions;
195
+ /**
196
+ * Show how many characters or words a field has, or how many are left:
197
+ * `<textarea id="bio" maxlength="160"></textarea>
198
+ * <output data-string-count="#bio"></output>`.
199
+ */
200
+ declare const count: (target?: ElementTarget, options?: CountOptions) => Controller;
201
+ /** Start every `[data-string-count]` element in `scope`, including elements added later. */
202
+ declare const autoCount: ({ selector: chosen, scope, observe, ...options }?: AutoOptions & CountOptions) => AutoInitController;
203
+
204
+ declare const FIT_ATTRIBUTE = "data-string-fit";
205
+ declare const FIT_STATE_ATTRIBUTE = "data-string-fit-state";
206
+ /** `full` when the whole text fits, `truncated` when it was shortened. */
207
+ type FitState = 'full' | 'truncated';
208
+ interface FitOptions {
209
+ /** Where the text is cut. `data-string-fit="end"` wins. Defaults to `'middle'`. */
210
+ position?: TruncatePosition;
211
+ /** Defaults to `'…'`. */
212
+ ellipsis?: string;
213
+ }
214
+ type AutoFitOptions = FitOptions & AutoOptions;
215
+ /**
216
+ * Shorten text to fit its element's width, cutting in the middle by
217
+ * default, and fit again when the width changes:
218
+ * `<span data-string-fit style="display: block">annual-report-2026-final.pdf</span>`.
219
+ * The element needs a width (block, inline-block, flex or grid item).
220
+ */
221
+ declare const fit: (target?: ElementTarget, options?: FitOptions) => Controller;
222
+ /** Start every `[data-string-fit]` element in `scope`, including elements added later. */
223
+ declare const autoFit: ({ selector: chosen, scope, observe, ...options }?: AutoOptions & FitOptions) => AutoInitController;
224
+
225
+ declare const COPY_ATTRIBUTE = "data-string-copy";
226
+ declare const COPY_STATE_ATTRIBUTE = "data-string-copy-state";
227
+ declare const COPY_EVENT = "string:copy";
228
+ /** `copied` or `error` for `reset` milliseconds after a click. */
229
+ type CopyState = 'copied' | 'error';
230
+ interface CopyDetail {
231
+ value: string;
232
+ ok: boolean;
233
+ }
234
+ interface CopyOptions extends ConvertOptions {
235
+ /** Element or field whose text is copied. `data-string-copy="#title"` wins. */
236
+ source?: ElementTarget;
237
+ /** Conversion applied before copying. `data-string-copy-as="kebab"` wins. */
238
+ as?: Conversion;
239
+ /** Milliseconds before the state is cleared. Defaults to `2000`. */
240
+ reset?: number;
241
+ /** Called after every copy attempt. */
242
+ onCopy?: (detail: CopyDetail, button: HTMLElement) => void;
243
+ }
244
+ type AutoCopyOptions = CopyOptions & AutoOptions;
245
+ /**
246
+ * Copy another element's text, converted, to the clipboard:
247
+ * `<button data-string-copy="#title" data-string-copy-as="kebab">Copy</button>`.
248
+ * The button gets `data-string-copy-state="copied"` (or `error`) for two seconds.
249
+ */
250
+ declare const copy: (target?: ElementTarget, options?: CopyOptions) => Controller;
251
+ /** Start every `[data-string-copy]` button in `scope`, including buttons added later. */
252
+ declare const autoCopy: ({ selector: chosen, scope, observe, ...options }?: AutoOptions & CopyOptions) => AutoInitController;
253
+
254
+ export { ATTRIBUTE, type AutoCopyOptions, type AutoCountOptions, type AutoFitOptions, type AutoInitController, type AutoOptions, type AutoSearchOptions, type AutoStringOptions, CHANGE_EVENT, COLOR_PROPERTY, COPY_ATTRIBUTE, COPY_EVENT, COPY_STATE_ATTRIBUTE, COUNT_ATTRIBUTE, COUNT_EVENT, COUNT_STATE_ATTRIBUTE, type Controller, Conversion, ConvertOptions, type CopyDetail, type CopyOptions, type CopyState, type CountInfo, type CountOptions, type CountState, type CountUnit, type ElementTarget, FIT_ATTRIBUTE, FIT_STATE_ATTRIBUTE, type FitOptions, type FitState, HashColorOptions, MatchOptions, SEARCH_ATTRIBUTE, SEARCH_EMPTY_ATTRIBUTE, SEARCH_EVENT, SEARCH_STATE_ATTRIBUTE, STATE_ATTRIBUTE, type SearchController, type SearchOptions, type SearchResult, type SearchState, type StringController, type StringOptions, type StringState, TruncatePosition, autoCopy, autoCount, autoFit, autoSearch, autoString, copy, count, fit, search, string };