@lo-tek/interfaces 0.0.0 → 0.38.0

package/dist/components/frame/tabs/lt-tabs.d.ts

@@ -0,0 +1,426 @@
+import { HostElement } from "../../host-element.js";
+export declare const LT_TABS_TAG: "lt-tabs";
+/**
+ * The parts the tabs look for, as selectors relative to the element. The
+ * web component finds its parts with these, and the manifest describes them
+ * for anyone writing the markup by hand, so the two cannot disagree.
+ */
+export declare const LT_TABS_PARTS: {
+    /** The tab list: the one the server gave the role, or the class from `tabs.css`. */
+    readonly list: "[role='tablist'], .lt-tabs__list";
+    /**
+     * A tab is a link to a panel in the tab list. A link is the only tab
+     * pattern that works without JavaScript: without the script the tab list is
+     * a table of contents, and the links lead to the panels. If the server has
+     * written the roles, only the links with `role="tab"` are tabs.
+     */
+    readonly tab: "a[role='tab'][href^='#'], .lt-tabs__list a[href^='#']:not([role])";
+    /** A panel: the role when it is there, otherwise the class without a role. */
+    readonly panel: "[role='tabpanel'], .lt-tabs__panel:not([role])";
+};
+/**
+ * Keyboard behaviour in a tab list, and the wiring when the markup comes
+ * without it.
+ *
+ * The tabs are links to their panels, the way GOV.UK does it:
+ *
+ * ```html
+ * <lt-tabs>
+ *   <ul class="lt-tabs__list" aria-label="Parts of the case">
+ *     <li><a href="#application">Application</a></li>
+ *     <li><a href="#attachments">Attachments</a></li>
+ *   </ul>
+ *   <section class="lt-tabs__panel" id="application"><h2>Application</h2>…</section>
+ *   <section class="lt-tabs__panel" id="attachments"><h2>Attachments</h2>…</section>
+ * </lt-tabs>
+ * ```
+ *
+ * Without JavaScript this is a table of contents with all the panels one
+ * after another, and the links work. What the template writes is an id on
+ * the panels, and it needs the links anyway.
+ *
+ * The web component never writes an id on a tab or a panel. Datastar and
+ * idiomorph recognise an element by its id, and an element with an id the
+ * server did not send is replaced at the next update, along with the tab
+ * selection and focus. The panels' ids come from the server, so they are
+ * kept. What the web component fills in, it computes from the markup: the
+ * roles, `aria-controls` from `href`, `role="presentation"` on the list
+ * items, and the panel's name, which is the tab's. The heading in the panel
+ * is the name when it says the same as the tab. Only the selected panel is a
+ * tab stop.
+ *
+ * The panels that are not selected are hidden with `hidden="until-found"`, so
+ * find in page and a link to something in a panel reach them, and the
+ * browser fires `beforematch`, which the web component selects the tab from.
+ * If the server wrote `hidden` itself, it is written back in the server's
+ * form, across the whole tab list: `lt.tabs()` from
+ * `@lo-tek/interfaces/react` gives `hidden=""`, because React cannot write
+ * `until-found`. The address selects the tab when the page loads and when it
+ * changes, and each selection is written to the address, unless it already
+ * points to the selected panel or something in it. On load the server's
+ * `aria-selected` comes before the address, and under `server-controlled`
+ * the address never selects.
+ *
+ * What the server has written stays. Which tab is selected is read from
+ * `aria-selected`, and when that is missing, from which panel is not hidden;
+ * if nothing is said, it is the first. Before the web component is
+ * registered, `tabs.css` shows only the panel the web component is going to
+ * select: the first visible one, or the one the address points to, so the
+ * content does not jump when the rest are hidden.
+ *
+ * What the web component then does is what the browser does not do by
+ * itself: Tab skips past the whole tab list and into the panel, while the
+ * arrow keys move between the tabs. With `activation="manual"` the arrow keys
+ * only move focus, and Enter or Space selects.
+ *
+ * The tab selection belongs to the user, and the web component restores it
+ * when a patch strips it. If the server needs to move the tab, as in
+ * "continue to step 2", set `server-controlled` on the host, and then every
+ * patch decides.
+ */
+export declare class LtTabs extends HostElement {
+    /**
+     * `server-controlled` and `activation`. Which tab is selected is in the
+     * markup the server sent, as `aria-selected` on the tab and `hidden` on the
+     * panels, and is read from there. A separate `selected` would have been a
+     * parallel copy of the same thing.
+     */
+    static observedAttributes: readonly ["server-controlled", "activation"];
+    private observer?;
+    /**
+     * The panel the user's tab points to, remembered so a patch cannot take
+     * the selection.
+     *
+     * Not the index and not the node. An index is not an identity: if the
+     * server inserts a tab first in the list, the same index points to
+     * something else. The node is not one either: the links have no id, so
+     * Datastar and idiomorph match them by position, and the node the user
+     * pressed became the inserted tab. The panel's id is the server's and
+     * stays; a tab pointing to another panel is another tab.
+     *
+     * Remembered with the link, `chosenTab`.
+     *
+     * `undefined` means the user has not selected anything yet, and then the
+     * server's markup applies.
+     */
+    private chosenTarget?;
+    /**
+     * The link the user pressed, with `chosenTarget`. While it is in the tab
+     * list and points to the same panel, it is the user's tab, also when
+     * another tab points to that panel too. When a morph has turned it into
+     * another tab, or dropped it while it kept other links, the tab that points
+     * to the panel is found. When the links were replaced, none of the row is
+     * left, as `innerHTML` does, and the selection is forgotten rather than
+     * guessed; the address still has it, see `selectFromAddress`.
+     */
+    private chosenTab?;
+    /** The tab list as it was when the user's tab was last found. */
+    private chosenRow;
+    /**
+     * Roles the web component set itself. Tells a bare tab list, where every
+     * link is a tab, from one where the server wrote the roles, where a link
+     * without a role is something else, such as a help link.
+     */
+    private readonly roledByMe;
+    private selectedMemory;
+    private hiddenMemory;
+    /**
+     * The form the server hides panels in, the last time it hid something:
+     * `""` from `lt.tabs()`, `"until-found"` or something else. The web
+     * component writes `hidden` in that form on every panel in the tab list,
+     * including a panel the server never hid. Otherwise one panel got
+     * `until-found` and the others `""` in the same tab list. If the server has
+     * never hidden anything, it is `until-found`, so find in page reaches the
+     * panel.
+     */
+    private hiddenForm;
+    /**
+     * The id the web component gave the heading in a panel, per panel. A morph
+     * strips the id from the heading and `aria-labelledby` from the panel,
+     * since neither was in the server's HTML, and the panel must get the same
+     * one back, so a screen reader does not follow a reference that changes
+     * under it.
+     */
+    private readonly headingIds;
+    /** The name the web component wrote in `aria-label` on a panel without a heading. */
+    private readonly labelByMe;
+    /**
+     * The tab the user clicked under `server-controlled`, until the server
+     * answers.
+     *
+     * It is not the user's selection in the sense of `chosenTarget`: it is never
+     * restored against the server's word. It only lasts until someone else has
+     * touched `aria-selected` or `hidden`, added a tab or a panel, removed the
+     * tab, or removed `server-controlled`. Without it, `repair()` read the
+     * server's old word from memory in the next microtask and undid the click,
+     * so the tabs could not be switched, and a `data-attr:hidden` that wrote the
+     * same as the web component had just written was never seen.
+     */
+    private pendingTab?;
+    /**
+     * The panel the browser is revealing after `beforematch`.
+     *
+     * The browser removes `hidden` itself after the event, and then moves on to
+     * the ancestors, such as an outer panel or a closed `<details>`. But only as
+     * long as the panel still has `hidden="until-found"` when the event is done.
+     * When the search comes from the user, the browser runs the microtasks after
+     * each listener, the observer included, and when the web component removed
+     * `hidden` in that round, Chromium and WebKit stopped. The match in a tab
+     * list inside a hidden panel stayed invisible. The panel is therefore not
+     * touched until the next task, when the browser is done, see `revealed()`.
+     */
+    private revealing?;
+    /**
+     * Whether the tab list has loaded: whether the address or the server's
+     * selection has been read. That happens the first time the tab list has
+     * tabs and the address can be resolved, see `sync()`, not when the element
+     * is connected. An `<lt-tabs>` the server fills in later otherwise always
+     * got the first tab.
+     */
+    private started;
+    /**
+     * The root `beforematch` is listened for on. The event bubbles, but is not
+     * `composed`, so from a panel in a shadow root it never reaches the
+     * document.
+     */
+    private root?;
+    connectedCallback(): void;
+    attributeChangedCallback(name: string): void;
+    disconnectedCallback(): void;
+    /**
+     * The tabs that belong to this tab list, and only those.
+     *
+     * Tabs inside tabs are ordinary markup. Without the boundary an inner tab
+     * list became part of the outer one: a click on an inner tab hid the outer
+     * panel it was in, and both web components attached listeners to the same
+     * tabs.
+     */
+    private get tabs();
+    /** Remembers the user's tab: the link, and the panel it points to. */
+    private choose;
+    /**
+     * Where the user's tab is now, or -1: the link while it points to the same
+     * panel; the tab that points to that panel when a morph has turned the
+     * link into another tab, or dropped it and kept others (the morphers match
+     * links without ids by position, and look ahead when one is removed);
+     * none when the links were replaced, with nothing of the row left.
+     */
+    private chosenIndex;
+    /** The server's word about an attribute, against what the web component last wrote. */
+    private serverWord;
+    /** Is there something on a tab or a panel other than what the web component wrote? */
+    private touchedByOthers;
+    /**
+     * Releases the click, and makes what is in the markup now the server's
+     * word.
+     *
+     * The memory holds the server's word from before the click, and it is
+     * stale: the server has answered. An attribute the server wrote the same as
+     * the web component cannot be told from one it did not touch, so the old
+     * words won, and the tab list jumped back to the tab from before the click
+     * just as the server confirmed the new one.
+     *
+     * `hidden` on the panels is therefore read as it is. `aria-selected` is read
+     * as it is when the server has touched at least one tab, that is, when the
+     * server speaks through `aria-selected`. If it has not, the values are the
+     * ones the web component wrote for the click, and then the panels say which
+     * tab applies.
+     */
+    private releasePending;
+    private serverSelected;
+    /** The server's word about `hidden` on the panel: the form, or `null` for visible. */
+    private serverHidden;
+    /**
+     * Can any of the changes concern the tab list?
+     *
+     * The observer sees the whole tree, and a suggestion field, a counter or an
+     * inner tab list in a panel changes `aria-selected`, `hidden` and text on
+     * every keystroke. Each of them gave a full round, with styles read for the
+     * names. Only what is deep inside one of the tab list's panels is skipped,
+     * and only when it is neither a heading in the panel, something
+     * `aria-labelledby` points to, nor an id, which can make an element
+     * something a tab points to. Everything else gives a round, as before.
+     */
+    private concerns;
+    /**
+     * The ids `aria-labelledby` points to from the tabs, what is inside them,
+     * and the panels. Before the tab list has loaded, also the id the address
+     * points to: the tab list waits for that element, see `sync()`, and it can
+     * arrive deep inside a panel.
+     */
+    private watchedIds;
+    /** Is the element inside an element with one of the ids, or is it one itself? */
+    private within;
+    /** Does an added or removed node carry one of the ids, itself or inside it? */
+    private carries;
+    /** The tab list the tabs are in, when it belongs to this web component. */
+    private get list();
+    /**
+     * The panel a tab controls, through the id it points to.
+     *
+     * The panel can be outside the host. It is then not in what the web
+     * component observes, so if a patch strips `hidden` from it, it does not
+     * come back by itself. If the tab points to nothing, the answer is nothing,
+     * and the web component warns. The order is not a fallback: two tabs could
+     * then have got the same panel, and the two wrote opposite `hidden` on it in
+     * every single round.
+     */
+    private panelFor;
+    /** The element a fragment points to, as written or decoded. */
+    private byFragment;
+    /**
+     * A tab that cannot be selected, with either mouse or keyboard: disabled,
+     * or hidden with `hidden`. A hidden tab cannot take focus, so when an arrow
+     * key selected it, the tab stop was left on something Tab never reaches.
+     */
+    private isDisabled;
+    /** The arrow keys only move focus, and Enter or Space selects. */
+    private get manual();
+    /**
+     * The index of the marked tab, or `-1` when none is.
+     *
+     * `selected` answers 0 in that case, because it is public API and a tab
+     * list in practice always has a selected tab. But that lie cannot be used
+     * internally: when it said 0 with nothing marked, `select(0)` returned at
+     * once, and the tab list did not respond to a click at all.
+     */
+    private get markedIndex();
+    /** The index of the selected tab. */
+    get selected(): number;
+    set selected(index: number);
+    private sync;
+    /**
+     * Fills in the wiring where the markup came without it.
+     *
+     * Only what is missing, with one exception: `aria-controls` is written from
+     * `href`, since the two are the same information and `href` is the one that
+     * works without JavaScript. Any other attribute the server has written is
+     * the server's word, even when it says something other than the web
+     * component would have said.
+     */
+    private wire;
+    /**
+     * Gives the panel a name, when the server has not given it one.
+     *
+     * The panel is named what the tab is named, as the APG does it. The APG
+     * lets the panel point to the tab, but the tab has no id here, and the web
+     * component writes none. If the heading in the panel says the same as the
+     * tab, the heading is the name, and it can get an id from the web
+     * component: it has no state the user can lose. Otherwise the name is the
+     * tab's, as `aria-label`.
+     *
+     * An `aria-label` or `aria-labelledby` the server wrote is never changed,
+     * even when the reference points to something that does not exist yet.
+     * Until it arrives, the tab's name stands as `aria-label`: a reference
+     * without a match is ignored when the name is computed, and then
+     * `aria-label` applies.
+     */
+    private name;
+    /** Writes the tab's name as `aria-label`, and remembers that the web component wrote it. */
+    private setOwnLabel;
+    /** Removes the fallback, when a name that exists has taken over. */
+    private dropOwnLabel;
+    /** Does at least one of the ids point to an element that exists? */
+    private resolves;
+    /**
+     * The tab the server says is selected, when the user has not selected
+     * anything.
+     *
+     * The server's word, not what is there: what the web component wrote does
+     * not count, see `Word`. `aria-selected` first. When that is missing, as in
+     * markup written without JavaScript, `hidden` on the panels says the same:
+     * the first panel the server shows belongs to the selected tab. If the
+     * markup says nothing, or hides every panel, it is the first, which is what
+     * a tab list starts on anyway.
+     */
+    private get derivedIndex();
+    /**
+     * Restores the user's selection after a patch.
+     *
+     * Without this the template had to write
+     * `data-preserve-attr="aria-selected tabindex"` on every tab and `hidden` on
+     * every panel, that is, list the attributes the web component was going to
+     * touch. No compiler looked at that list.
+     *
+     * `apply()` is called whether or not the tabs look right, because a patch
+     * may have touched only the panels. That is the narrow patch the
+     * documentation itself recommends, and a check on `aria-selected` alone did
+     * not see it: the tab said one thing and the screen another.
+     */
+    private repair;
+    private bind;
+    /** What the server has called a tab in the tab list, but is not a link to a panel. */
+    private nonLinkTabs;
+    /**
+     * The tab in this tab list the event came from, or -1.
+     *
+     * `indexOf` and not just `closest`: a tab list inside a panel bubbles its
+     * clicks up here too, and they do not belong to this tab list.
+     */
+    private tabIndexOf;
+    private handleClick;
+    /** Find in page or a link revealed a hidden panel. */
+    private handleBeforematch;
+    /**
+     * Releases the panel after `beforematch`, in the task after the browser has
+     * finished revealing, and writes the tab list.
+     *
+     * Usually the browser has removed `hidden` by then. It has not when the
+     * panel was taken out of the document during the event, and without this
+     * round the panel stayed hidden even though the tab was selected.
+     */
+    private revealed;
+    private handleHashchange;
+    /**
+     * The index of the tab the address points to, or -1: the panel itself, such
+     * as `#attachments`, or something inside it, such as a heading in the panel.
+     */
+    private get addressIndex();
+    /**
+     * Corrects the address when it points to another tab in the tab list than
+     * the selected one, as when the server has moved the selection. An address
+     * to something outside the tab list stays.
+     */
+    private alignAddress;
+    /**
+     * Writes the tab to the address, so it can be shared, and so the selection
+     * survives the server replacing the links.
+     *
+     * If the address already points to the selected panel or something in it,
+     * it stays: a link into the content must not be lost. `replaceState`, so
+     * the selection does not become an entry in the history.
+     */
+    private showInAddress;
+    /**
+     * Selects the tab the address points to.
+     *
+     * On load, on `hashchange`, and when the server replaces the links without
+     * saying which one is selected: the selection is then still in the
+     * address. Not under `server-controlled`, where the server decides.
+     */
+    private selectFromAddress;
+    private handleKeydown;
+    /**
+     * The next tab that can be selected, in one direction, wrapping round if
+     * needed.
+     *
+     * A tab that cannot be selected is skipped. When a hidden tab was selected,
+     * it got the tab stop, and Tab never reached the tab list. The keyboard
+     * user was locked out.
+     */
+    private nextEnabled;
+    /** Selects a tab and fires the event. */
+    select(index: number): void;
+    /** Announces which tab is selected now. */
+    private notify;
+    /**
+     * Writes the selection out into the markup.
+     *
+     * Every write compares first. The web component observes the same
+     * attributes it sets, so a write without a comparison would trigger the
+     * observer, which would write again, forever.
+     */
+    private apply;
+}
+export declare function defineLtTabs(tagName?: string): void;
+//# sourceMappingURL=lt-tabs.d.ts.map

package/dist/components/frame/tabs/lt-tabs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lt-tabs.d.ts","sourceRoot":"","sources":["../../../../src/components/frame/tabs/lt-tabs.ts"],"names":[],"mappings":"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"}