@fusion.dev/helix-headless 0.219.0 → 0.221.0

package/dist/element-events.generated.js

@@ -53,7 +53,7 @@ registerElementEvents({
         'helix-copy-error',
         'helix-toggle',
     ],
-    'helix-headless-code-editor': ['change', 'helix-before-change', 'input'],
+    'helix-headless-code-editor': ['change', 'helix-before-change', 'helix-found', 'input'],
     'helix-headless-code-input': [
         'change',
         'helix-before-change',
@@ -138,6 +138,7 @@ registerElementEvents({
     'helix-headless-drawer': ['close', 'helix-before-close', 'helix-before-open', 'toggle'],
     'helix-headless-drilldown': ['helix-navigate', 'helix-select'],
     'helix-headless-drilldown-item': ['helix-select'],
+    'helix-headless-editor': ['helix-found'],
     'helix-headless-file-input': ['change', 'helix-before-change', 'helix-reject', 'input'],
     'helix-headless-filter-chip': ['helix-dismiss'],
     'helix-headless-filter-input': [
@@ -154,6 +155,7 @@ registerElementEvents({
         'toggle',
     ],
     'helix-headless-filter-menu': ['helix-facet'],
+    'helix-headless-find': ['helix-before-close', 'helix-before-open', 'helix-found', 'toggle'],
     'helix-headless-graph': [
         'helix-activate',
         'helix-before-activate',
@@ -378,6 +380,7 @@ registerElementEvents({
     'helix-headless-tag-group': ['change', 'helix-before-change', 'helix-dismiss'],
     'helix-headless-terminal': [
         'helix-copy',
+        'helix-found',
         'helix-terminal-bell',
         'helix-terminal-input',
         'helix-terminal-link',

package/dist/find/index.d.ts

@@ -0,0 +1 @@
+export * from './root/find-root.js';

package/dist/find/index.js

@@ -0,0 +1 @@
+export * from './root/find-root.js';

package/dist/find/root/find-root.d.ts

@@ -0,0 +1,314 @@
+import { type Finder, type FindResult, HelixElement } from '@fusion.dev/helix-core';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
+import '../../button/index.js';
+import '../../icon-button/index.js';
+import '../../toolbar/index.js';
+export type { FindDirection, Finder, FindQuery, FindResult } from '@fusion.dev/helix-core';
+/** What `attach` returns: how a finder reports a search it finished later, and lets go of Find. */
+export interface FindSink {
+    /** Takes the finder's marks away, and Find goes back to searching what `for` names. */
+    detach(): void;
+    /** Reports where a search stands, for a finder whose `find` returned nothing and counted later. */
+    found(result: FindResult): void;
+}
+/** The options a bar can show, in the order it shows them. */
+export type FindOption = 'match-case' | 'regex' | 'whole-word';
+declare const HelixHeadlessFind_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
+/**
+ * @summary A bar that finds words in content and moves among the matches.
+ *
+ * @description
+ * Searches the content `for` names, by id, and marks every match, with the
+ * current one marked apart. The count says which match is current and how many
+ * there are. Find opens with Command+F, or Control+F on Windows and Linux,
+ * while the reader is in that content or in the bar. Everywhere else on the
+ * page, the key opens the browser's own find. `shortcut` changes the key, and
+ * empty turns it off.
+ *
+ * The match case, whole word, and regular expression options are drawn in the
+ * bar. `options` names the ones it draws. Text that is not shown is not
+ * searched, nor text under `inert` or `aria-hidden="true"`, nor what `skip`
+ * matches. Text under `hidden="until-found"` and in a closed `<details>` is
+ * searched, and opened when its match becomes current, as the browser's find
+ * opens it: an Accordion section opens. A match is scrolled into the middle of
+ * what scrolls it unless it is already in sight. While Find is open, a change
+ * to the content searches again once the content is still.
+ *
+ * Content drawn some other way, such as a terminal's grid, an editor's
+ * document, or rows of a list that are not all in the page, is searched by a
+ * finder the page attaches with `attach(finder)`. Terminal and Code Editor
+ * draw a Find of their own, which searches through their renderer. Find offers
+ * replacing to a finder that can replace, unless `readonly` is set.
+ *
+ * The bar is a search landmark named by `label`. The count is said in a live
+ * region as it changes.
+ *
+ * **Keyboard.** In the field, Enter moves to the next match and Shift+Enter to
+ * the previous one. Escape closes the bar from anywhere in it, and focus
+ * returns to where it was before the bar opened. The find key pressed again
+ * moves focus to the field and selects what it holds. In the replace field,
+ * Enter replaces the current match, and Command+Enter or Control+Enter
+ * replaces every match.
+ *
+ * @since 0.220.0
+ * @status experimental
+ * @category navigation
+ * @documentation https://fusion.dev/helix/components/find
+ *
+ * @slot actions - Controls of your own in the bar's toolbar, between its options and the buttons that move between matches.
+ * @slot close-icon - Replaces the glyph inside the close button.
+ * @slot match-case-icon - Replaces the glyph inside the match case button.
+ * @slot next-icon - Replaces the glyph inside the next match button.
+ * @slot previous-icon - Replaces the glyph inside the previous match button.
+ * @slot regex-icon - Replaces the glyph inside the regular expression button.
+ * @slot whole-word-icon - Replaces the glyph inside the whole word button.
+ *
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the bar closes, and cancelable.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the bar opens, and cancelable. Canceling it keeps the bar closed.
+ * @event {HelixFoundEvent} helix-found - Sent after each search and each move among the matches, with `count` and the current match's `index`, counting from 0, or -1 for none.
+ * @event {ToggleEvent} toggle - Sent when the bar opens or closes, with `newState` and `oldState`.
+ *
+ * @csspart actions - The `actions` slot, in the toolbar.
+ * @csspart bar - The bar, a search landmark: the field, the count, the toolbar, and the replace row while it shows.
+ * @csspart close - The button that closes the bar.
+ * @csspart close-button - The close button's inner button.
+ * @csspart close-live - The close button's live region, which speaks while the button is pending.
+ * @csspart close-spinner - The ring the close button turns while it is pending.
+ * @csspart close-text - The box the close button's icon sits in.
+ * @csspart controls - The toolbar: the options, your actions, and the buttons that move between matches and close the bar.
+ * @csspart controls-toolbar - The box inside the toolbar that lays its buttons out.
+ * @csspart count - Which match is current and how many there are, such as "3 of 12 matches".
+ * @csspart field - The search field.
+ * @csspart live - The live region that says the count as it changes.
+ * @csspart match-case - The button that matches case. Pressed while it does.
+ * @csspart match-case-button - The match case button's inner button.
+ * @csspart match-case-live - The match case button's live region, which speaks while the button is pending.
+ * @csspart match-case-pressed - The match case button while case has to match, beside `match-case`.
+ * @csspart match-case-spinner - The ring the match case button turns while it is pending.
+ * @csspart match-case-text - The box the match case button's icon sits in.
+ * @csspart next - The button that moves to the next match.
+ * @csspart next-button - The next match button's inner button.
+ * @csspart next-live - The next match button's live region, which speaks while the button is pending.
+ * @csspart next-spinner - The ring the next match button turns while it is pending.
+ * @csspart next-text - The box the next match button's icon sits in.
+ * @csspart previous - The button that moves to the previous match.
+ * @csspart previous-button - The previous match button's inner button.
+ * @csspart previous-live - The previous match button's live region, which speaks while the button is pending.
+ * @csspart previous-spinner - The ring the previous match button turns while it is pending.
+ * @csspart previous-text - The box the previous match button's icon sits in.
+ * @csspart regex - The button that reads the field as a regular expression. Pressed while it does.
+ * @csspart regex-button - The regular expression button's inner button.
+ * @csspart regex-live - The regular expression button's live region, which speaks while the button is pending.
+ * @csspart regex-pressed - The regular expression button while the field reads as one, beside `regex`.
+ * @csspart regex-spinner - The ring the regular expression button turns while it is pending.
+ * @csspart regex-text - The box the regular expression button's icon sits in.
+ * @csspart replace - The button that replaces the current match.
+ * @csspart replace-all - The button that replaces every match.
+ * @csspart replace-all-button - The Replace all button's inner button.
+ * @csspart replace-all-live - The Replace all button's live region, which speaks while the button is pending.
+ * @csspart replace-all-spinner - The ring the Replace all button turns while it is pending.
+ * @csspart replace-all-text - The box the Replace all button's words sit in.
+ * @csspart replace-button - The Replace button's inner button.
+ * @csspart replace-field - The field the replacement is typed in.
+ * @csspart replace-live - The Replace button's live region, which speaks while the button is pending.
+ * @csspart replace-spinner - The ring the Replace button turns while it is pending.
+ * @csspart replace-text - The box the Replace button's words sit in.
+ * @csspart replace-toggle - The button that shows the replace row. Expanded while it shows.
+ * @csspart replace-toggle-button - The replace toggle's inner button.
+ * @csspart replace-toggle-live - The replace toggle's live region, which speaks while the button is pending.
+ * @csspart replace-toggle-spinner - The ring the replace toggle turns while it is pending.
+ * @csspart replace-toggle-text - The box the replace toggle's icon sits in.
+ * @csspart whole-word - The button that matches whole words only. Pressed while it does.
+ * @csspart whole-word-button - The whole word button's inner button.
+ * @csspart whole-word-live - The whole word button's live region, which speaks while the button is pending.
+ * @csspart whole-word-pressed - The whole word button while only whole words match, beside `whole-word`.
+ * @csspart whole-word-spinner - The ring the whole word button turns while it is pending.
+ * @csspart whole-word-text - The box the whole word button's icon sits in.
+ *
+ * @cssstate open - While the bar is open.
+ * @cssstate replace-open - While the replace row shows.
+ */
+export declare class HelixHeadlessFind extends HelixHeadlessFind_base {
+    protected static markRules: string[];
+    /**
+     * The key this family's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-find': { label: 'Suchen' } })`.
+     */
+    static words: string;
+    /** The close button's label. */
+    closeLabel: string;
+    /** The name of the bar's toolbar, read by screen readers. */
+    controlsLabel: string;
+    /**
+     * The id of the element whose text Find searches, in the same tree as Find.
+     * With a finder attached, it names only where the find key opens the bar.
+     */
+    for: string;
+    /** What the count says when the regular expression cannot be read. */
+    invalidLabel: string;
+    /** The field's name and placeholder, and the name of the bar. */
+    label: string;
+    /** Whether case has to match, so "Error" does not find "error". The reader turns it on and off from the bar. */
+    matchCase: boolean;
+    /** The match case button's label. */
+    matchCaseLabel: string;
+    /**
+     * What the count says of the matches. `{index}` is the current match,
+     * counting from 1, and `{count}` how many there are.
+     */
+    matchesLabel: string;
+    /** The next match button's label. */
+    nextLabel: string;
+    /**
+     * Which options the bar draws, as a list of `match-case`, `whole-word`, and
+     * `regex`, or `none`. They are always drawn in that order.
+     */
+    options: string;
+    /** The previous match button's label. */
+    previousLabel: string;
+    /** What the field holds: what the reader typed, or what you set. */
+    query: string;
+    /** Hides replacing, for content the reader cannot change. The attribute is `readonly`, the platform's spelling. */
+    readOnly: boolean;
+    /** Whether the field reads as a regular expression, in JavaScript's syntax. The reader turns it on and off from the bar. */
+    regex: boolean;
+    /** The regular expression button's label. */
+    regexLabel: string;
+    /** The Replace all button's words. */
+    replaceAllLabel: string;
+    /** The replace field's name and placeholder. */
+    replaceFieldLabel: string;
+    /** The Replace button's words. */
+    replaceLabel: string;
+    /** What the replace field holds, which Replace puts in place of a match. */
+    replacement: string;
+    /** The label of the button that shows the replace row. */
+    replaceToggleLabel: string;
+    /**
+     * The key that opens the bar, as a chord such as `mod+f`, where `mod` is
+     * Command on an Apple keyboard and Control elsewhere. Empty turns the key
+     * off, as for a bar the page opens itself.
+     */
+    shortcut: string;
+    /**
+     * Elements inside the content whose text is not searched, as a selector,
+     * such as line numbers or the buttons beside each message.
+     */
+    skip: string;
+    /** Whether only whole words match. The reader turns it on and off from the bar. */
+    wholeWord: boolean;
+    /** The whole word button's label. */
+    wholeWordLabel: string;
+    /** Where the search stands, or nothing before one. */
+    private result;
+    /** Whether the replace row shows, where the finder can replace. */
+    private replaceOpen;
+    /** The finder a frame or the page attached, which searches in place of the text finder. */
+    private attached;
+    /** What the live region says now, and how many times something has been said. */
+    private announcement;
+    private said;
+    /** The text finder over the content `for` names, made for that content and `skip`. */
+    private own;
+    /** The finder whose marks are drawn, which `end` is sent to. */
+    private marking;
+    /** Where focus was before the bar opened, which it returns to as the bar closes. */
+    private returnTo;
+    /** Whether the reader last pressed or focused inside the content or the bar, where the find key is Find's. */
+    private inside;
+    /**
+     * Searches with `finder` in place of the text finder, and returns how it
+     * reports a search it finishes later. Attaching another lets go of this one.
+     */
+    attach(finder: Finder): FindSink;
+    /**
+     * Opens the bar and puts focus in its field, with what it holds selected.
+     * Text selected in the content, on one line, becomes the search.
+     */
+    show(): Promise<void>;
+    /** Closes the bar and takes the marks away. Focus in the bar returns to where it was before the bar opened. */
+    hide(): void;
+    /** Moves to the next match, after the last one to the first. */
+    next(): void;
+    /** Moves to the previous match, before the first one to the last. */
+    previous(): void;
+    /** Searches again, staying on the current match where it still matches, for content changed in a way Find cannot see. */
+    refresh(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /** The element `for` names, or nothing. */
+    private get target();
+    /** The finder that searches now: the one attached, or the text finder over what `for` names. */
+    private get finder();
+    /** The query as a finder reads it. */
+    private get findQuery();
+    /** Whether the field can be searched for: empty, or a pattern that reads. */
+    private get readable();
+    /**
+     * Whether the finder can replace and the content can be changed. Never
+     * while hydrating, since a server has no finder: the update after hydration
+     * draws the replace toggle.
+     */
+    private get replaceable();
+    /** Whether the replace row shows. */
+    private get replacing();
+    /**
+     * The count, as the reader reads it, and empty before a search. The
+     * template writes `nothing` for empty: Lit hydrating a server's empty string
+     * has no text node to change, and writes the next count into the part's
+     * closing marker, where nothing shows.
+     */
+    private get countText();
+    /** Whether the bar draws an option. */
+    private offers;
+    /** The text selected in the content, where it lies on one line, or nothing. */
+    private selectedText;
+    /** Searches with the finder, and says where the search stands. */
+    private search;
+    /** Takes the last search's marks away, where it drew any. */
+    private endSearch;
+    /** Where a search stands, drawn in the count, said, and sent as `helix-found`. Nothing while the bar is closed. */
+    private report;
+    /** Replaces the current match, or every match. */
+    private replace;
+    /** Says something in the live region, once, even where it is what was said last. */
+    private say;
+    /** Whether an event's path runs through the bar or the content. */
+    private within;
+    /** Where the reader last pressed or put focus, which decides whose the find key is. */
+    private readonly handleWhere;
+    /**
+     * The find key, heard on the document before anything else, and taken only
+     * where the reader is in the content or the bar, so the key opens the
+     * browser's own find everywhere else.
+     */
+    private readonly handleShortcut;
+    private readonly handleInput;
+    private readonly handleReplaceInput;
+    /** Escape closes the bar from anywhere in it, and Enter moves between matches or replaces. */
+    private readonly handleKeys;
+    /** Turns one of the options on or off, which searches again with it. */
+    private toggleOption;
+    /** The button that shows the replace row, drawn where the finder can replace. */
+    protected renderReplaceToggle(): TemplateResult | typeof nothing;
+    /** The options the bar draws, each pressed while it applies. */
+    protected renderOptionButtons(): TemplateResult;
+    /**
+     * The toolbar after the field: the options, the page's actions, and the
+     * buttons that move between matches and close the bar. The field stands
+     * outside it, because a toolbar takes the arrows and a text field needs
+     * them.
+     */
+    protected renderControls(): TemplateResult;
+    /** The replace row: its field, then Replace and Replace all. */
+    protected renderReplace(): TemplateResult | typeof nothing;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-find': HelixHeadlessFind;
+    }
+}