@oslokommune/punkt-elements 19.10.2 → 19.11.0

package/dist/directives/slot-content.d.ts

@@ -1,138 +1,330 @@
 import { LitElement } from 'lit';
 import { AsyncDirective, PartInfo } from 'lit/async-directive.js';
 import { ChildPart, ElementPart } from 'lit/directive.js';
-/**
- * Returns the SlotManager for a host, creating one if it doesn't exist.
- * Call this in connectedCallback() to eagerly collect children before Lit renders.
- */
+/** Returns the host's SlotManager, and creates it the first time. */
 export declare function getSlotManager(host: LitElement): SlotManager;
+/** The default slot's key. A symbol, so no slot name can be mistaken for it. */
 declare const DEFAULT_SLOT: unique symbol;
 type SlotKey = string | typeof DEFAULT_SLOT;
+/** Which of a source host's slots a forwarding hands to which of the child's slots. */
 type SlotMapping = Array<[from: SlotKey, to: SlotKey]>;
+/** The forwardSlots() argument: slot names kept as they are, or a map from name to name. */
 type ForwardedSlots = Array<string | null> | Record<string, string | null>;
 /**
- * Per-host singleton that manages node collection and observation.
- * Scans host children, categorizes them by slot attribute, and notifies
- * registered directives when children change.
- *
- * IMPORTANT: collectNodes() must be called BEFORE Lit's first render
- * (typically in connectedCallback via PktElement.hasSlotContent or getSlotManager).
- * Lit's first render clears host children, so collecting during render is too late.
+ * Keeps track of one host's content: which nodes belong to which slot, where each distributed
+ * node's placeholder is, and which parts show them. It learns about changes in three ways:
+ * through the host's overridden DOM methods (handled at once), through a MutationObserver on
+ * the host's subtree, and through text accessors (watchText()).
  */
 export declare class SlotManager {
     private host;
-    private observer;
+    /** The content by slot, in the order of the host's children. Includes mirrors. */
     private nodesBySlot;
-    private directives;
-    private observing;
+    /** The content nodes this manager owns. Mirrors are not tracked. */
     private trackedNodes;
-    generation: number;
-    private initialCollectionDone;
-    private processingMutations;
+    /** Placeholder to distributed node, and whitespace to its mirror. */
     private placeholderToNode;
+    /** Distributed node to placeholder, and mirror to its whitespace. */
     private nodeToPlaceholder;
     private static PLACEHOLDER_PREFIX;
+    /** Whitespace among the host's children that lies between content, and its mirror. */
+    private mirrorOf;
+    /** Whether the host has had whitespace text, which syncWhitespace() then has to look at. */
+    private hasWhitespace;
+    /** Where the first and last default-slot content stood at the last syncWhitespace(). */
+    private contentBounds;
+    /** Whitespace added or changed since the last syncWhitespace(). */
+    private changedWhitespace;
+    /** The host's slotContent() parts. */
+    private directives;
+    /** Hosts whose content this manager includes, by the forwardSlots() directive that set it up. */
     private sources;
+    /** Managers that include this host's content. */
     private subscribers;
-    private followsHostRenders;
+    /** Bumped on every change, so that a part can skip placing nodes when nothing changed. */
+    generation: number;
+    /** Whether collectNodes() has run. */
+    private initialCollectionDone;
+    /** True during an own change (see asOwnChange()). */
+    private inOwnChange;
+    /** True while Lit renders the host. Lit's insertions into the host are then left alone. */
+    private rendering;
+    /** The comment between the content and the template (see insertContentEnd()). */
+    private contentEnd;
+    /** Lit's marker at the start of the template. The content end goes back in front of it. */
+    private rootMarker;
+    private observer;
+    private observing;
+    /** Whether the observer should run whenever the host is connected. */
     private wantsObserver;
+    /** Whether the host is a LitElement, whose renders the manager hooks into. */
+    private followsHostRenders;
+    /**
+     * Hooks into the host's lifecycle:
+     * - hostConnected: observe again, and catch up on changes made while disconnected
+     * - hostUpdate, before Lit renders: handle pending changes by others, and before the first
+     *   render, register content added since connectedCallback and insert the content end
+     * - hostUpdated, after Lit renders: note Lit's root marker, and handle the render's own
+     *   changes as Lit's, not as content changes
+     */
     constructor(host: LitElement);
     /**
-     * Collect original children BEFORE Lit's first render.
-     * Must be called in connectedCallback or earlier.
-     * Safe to call multiple times — only the first call scans.
+     * Registers the host's children as content. Runs once: in connectedCallback, or earlier when
+     * a part or a forwarding needs the content first.
      */
     collectNodes(): void;
+    /** Registers children added between connectedCallback and the first render. */
     private collectLateChildren;
-    /**
-     * Register a directive instance and start observing for dynamic changes.
-     */
+    /** Registers a slotContent() part of the host, and starts observing. */
     addDirective(d: SlotContentDirective): void;
+    /** Unregisters a part, when Lit disconnects it. */
+    removeDirective(d: SlotContentDirective): void;
     /**
-     * Unregister a directive instance. Stops observing if no directives remain.
+     * Includes another host's slots in this manager's slots, as set up by the forwardSlots()
+     * directive `token`. The source keeps observing its own children while anyone subscribes.
      */
-    removeDirective(d: SlotContentDirective): void;
     addSource(token: object, manager: SlotManager, mapping: SlotMapping): void;
+    /** Stops including the slots that the forwardSlots() directive `token` handed over. */
     removeSource(token: object): void;
+    /** Unsubscribes from a source manager, unless another forwarding still uses it. */
+    private detachFrom;
     /**
-     * Returns nodes matching the given slot name.
+     * The parts that show this host's content: its own, and those of every manager that includes
+     * it, through whole forwarding chains.
      */
+    private reachableParts;
+    /** The content of a slot, forwarded content included. Behind hasSlotContent(). */
     getNodes(slotName?: string): Node[];
-    /**
-     * Returns whether the given slot has any content.
-     */
+    /** The nodes a part places: the slot's content, and the mirrors between it. */
+    placementNodes(slotName?: string): Node[];
+    /** Whether a slot has content. */
     hasContent(slotName?: string): boolean;
+    /** The host's own nodes for a slot, followed by those forwarded to it. */
+    private nodesFor;
     /**
-     * Ensure a placeholder comment exists for a node that is about to be distributed.
-     * Called by the directive before Lit moves the node to the target position.
-     * The placeholder stays between Lit's ChildPart markers so that when the parent
-     * template conditionally removes the content, the MutationObserver can detect
-     * the placeholder removal and clean up the real node.
+     * Gives a node a placeholder among the host's children before a part moves it away. For
+     * forwarded content the source host gets the placeholder. Content found in the template
+     * region (inserted there past the overrides) gets its placeholder at the end of the content.
      */
     ensurePlaceholder(node: Node): void;
-    private nodesFor;
-    private detachFrom;
-    private handleChange;
-    private stopObservingIfUnused;
     /**
-     * Start MutationObserver for dynamic child changes.
+     * Creates and registers a node's placeholder. A text node's placeholder forwards writes to
+     * `data` to the text: a Lit parent updates a text binding by writing to the node after its
+     * marker, and once the text is distributed, that node is the placeholder.
+     */
+    private createPlaceholder;
+    /** Unregisters a node's placeholder and returns it. The placeholder stays in the DOM. */
+    private forgetPlaceholder;
+    /** The placeholder of a node this manager tracks. Mirrors have none. */
+    private placeholderOf;
+    /**
+     * Runs a change that others make to the host's children, and handles it at once instead of
+     * when the observer reports it. While Lit renders the host, the change is Lit's own and runs
+     * as it is.
+     */
+    handleNow<T>(change: () => T): T;
+    /**
+     * Translates a reference node given to the host's DOM methods (insertBefore(node, child)) to
+     * the host child to insert before:
+     * - a distributed node: its placeholder
+     * - another node in a part, like Lit's end marker after the last distributed node: next to
+     *   the nearest distributed node, or the end of the content when the part holds none
+     * - `null`, or a node of the template: the end of the content
+     * Anything else is returned as it is, and the native method decides.
+     */
+    positionInHost(node: Node | null): Node | null;
+    /** Whether this manager tracks a node, so the host's removeChild() may remove it from a part. */
+    owns(node: Node): boolean;
+    /**
+     * Moves a distributed node to a new position: its placeholder among the host's children
+     * (before `before`, or last), and the node itself to the matching place in its part. This is
+     * a keyed reorder (Vue v-for, React key), done without placing the whole slot again. Returns
+     * false when the move is not that simple, and the caller inserts natively instead.
+     */
+    moveDistributed(node: Node, before: Node | null): boolean;
+    /**
+     * Replaces all the host's content with the given nodes and leaves the template alone. Behind
+     * the textContent, innerHTML and innerText setters and replaceChildren(). Returns false when
+     * the native method should run instead: before the content is collected or the template
+     * rendered, and when a node contains the host, which the native method rejects.
+     */
+    replaceContent(newNodes: Node[]): boolean;
+    /** Makes text among the host's children content, once it has more than whitespace. */
+    adoptText(text: Text): void;
+    /**
+     * Text among the host's children changed without getting real text. Whitespace updates its
+     * mirror; otherwise the whitespace between content is worked out again.
+     */
+    blankTextChanged(text: Text): void;
+    /**
+     * Distributed text that became empty or blank is no longer content. It goes back to its
+     * placeholder's place among the host's children, where a Lit parent or a framework can give
+     * it text again (adoptText()).
+     */
+    releaseText(text: Text): void;
+    /** Watches text among the host's children, and notes whitespace for syncWhitespace(). */
+    private watchHostText;
+    /**
+     * Gives whitespace among the host's children that lies between the first and the last
+     * default-slot content a mirror in the slot, and takes it away from whitespace that no longer
+     * does. Whitespace at the start or the end of the content gets none. Runs on every change, so
+     * it only looks where something can have changed:
+     * - mirrors that are no longer between content sit at the ends of the default slot's list,
+     *   since the list is in the order of the host's children
+     * - whitespace that was added or changed
+     * - whitespace where the first or the last content moved outwards, or next to the new first
+     *   or last content when it moved inwards
+     *
+     * The whitespace itself is never moved, because a Lit parent may use it as the end of a
+     * part (`${a} ${b}`): moving it would make clearing `a` remove `b` as well. It acts as the
+     * mirror's placeholder instead, so the mirror moves and goes with it.
+     */
+    private syncWhitespace;
+    /** Drops the mirrors before the first and after the last content in the default slot. */
+    private dropMirrorsOutside;
+    /** Whether one child of the host comes before another. */
+    private precedes;
+    /** Adds the whitespace next to a content's place, up to the nearest other content, to `into`. */
+    private collectBlankBeside;
+    /** The first and last default-slot content that has a place among the host's children. */
+    private findContentBounds;
+    /** The host child that holds a content node's place: its placeholder, or the node itself. */
+    private placeOf;
+    /** Whether a child of the host stands between the first and the last content. */
+    private isBetween;
+    /** Adds the whitespace among the host's children between two of its children to `into`. */
+    private collectBlankBetween;
+    /** Gives a piece of whitespace its mirror, in its place in the default slot. */
+    private addMirror;
+    /** Removes the mirror of a piece of whitespace, from the DOM and from the slot. */
+    private dropMirror;
+    /**
+     * Appends the content end, right before the first render, so that Lit renders the template
+     * after it. Insertions with no reference node go before it (positionInHost()).
+     *
+     * It reports no next sibling. A Lit parent with no whitespace before the closing tag
+     * (`<pkt-button>${label}</pkt-button>`) has a part that runs to the end of the host, and
+     * clears it by following nextSibling until null, so the clear stops here instead of removing
+     * the template. Such a clear removes the content end itself, and getContentEnd() puts it back.
+     */
+    private insertContentEnd;
+    /**
+     * Returns the content end, after putting it back in front of the template if a clear removed
+     * it. Null before the first render.
+     */
+    private getContentEnd;
+    /** Whether a child of the host is the content end or comes after it: Lit's template. */
+    private isInTemplate;
+    /**
+     * Starts the MutationObserver on the host's subtree. It sees content added to the host,
+     * content removed wherever it is (in parts too), and nodes frameworks insert into parts.
      */
     private startObserving;
-    private flushMutations;
+    /** Stops the observer. Pending records are dropped; resync() catches up on reconnect. */
     private stopObserving;
+    /** Stops observing when the host is disconnected, or nobody needs the observer anymore. */
+    private stopObservingIfUnused;
     /**
-     * Handle MutationObserver mutations incrementally.
-     * Only processes nodes that are NOT already part of Lit's rendered template.
-     *
-     * Uses a guard flag to prevent recursive handling: when notifyDirectives()
-     * makes a directive move nodes (e.g., from host into a ChildPart container),
-     * that move triggers another mutation which must be ignored.
+     * Handles the observer's pending records now. `fromHostRender` marks them as changes Lit made
+     * while rendering the host, which are not content changes.
      */
+    private flushMutations;
+    /** Handles observer records as an own change, so the moves it makes are not handled again. */
     private handleMutations;
+    /** Updates the content from what others added to and removed from the host's subtree. */
+    private applyMutations;
+    /**
+     * Handles nodes a framework inserted inside a part while removing some of this host's content
+     * from it, which is how Vue replaces a distributed element: it works through the element's
+     * current parent. Content is registered where it is, with a placeholder at the matching
+     * position among the host's children, so focus and state survive. Anything else (anchors) is
+     * moved to that position among the host's children, where the framework expects it.
+     */
     private adoptNodesInParts;
+    /**
+     * Where among the host's children a node in a part belongs: by the placeholders of the
+     * distributed nodes next to it in the part, or else where a node was just removed from the
+     * same part.
+     */
     private hostPositionFor;
-    private placeholderOf;
-    private reachableParts;
-    private insertInSlotOrder;
+    /**
+     * Catches up on changes made while the host was disconnected and nothing observed it:
+     * content removed meanwhile (or whose placeholder was removed) is dropped instead of being
+     * put back, content added meanwhile is registered, and moved placeholders reorder the slot.
+     */
+    private resync;
+    /**
+     * Puts each slot in the order of its placeholders. When the order changed, the slot's nodes
+     * are taken out of their parts, and the parts place them again in the new order.
+     */
+    private sortSlots;
+    /**
+     * Called after every content change: works out the whitespace between content again, has the
+     * parts and the managers that include this host place their nodes, and re-renders the host,
+     * so that anything computed from hasSlotContent() is up to date.
+     */
+    private handleChange;
+    /** Tells the host's parts to place their nodes. */
+    private notifyDirectives;
+    /**
+     * Runs DOM changes made by this file, and drops the observer records they cause, so that they
+     * are not handled as changes by others. Restores the flag even if a change throws.
+     */
+    private asOwnChange;
+    /** Registers a content node, at its place in its slot. */
+    private addContent;
+    /** Unregisters a content node. Its placeholder is left to the caller. */
+    private removeContent;
+    /** Marks a node as content of this host, and watches it if it is text. */
     private track;
     private untrack;
     /**
-     * Determines if a node is user-provided content (not Lit's rendered template).
-     * Lit's rendered content includes comment markers and elements created by the template.
+     * Adds a node to its slot's list, ordered by where it stands among the host's children (by
+     * its placeholder, if it has one).
      */
-    private isUserContent;
+    private insertInSlotOrder;
+    /** Removes a node from whichever slot's list holds it. */
     private removeFromSlots;
-    private notifyDirectives;
 }
 /**
- * AsyncDirective that places slot content at its position in a Lit template.
- *
- * Usage:
- *   html`<div>${slotContent(this)}</div>`              // default slot
- *   html`<div>${slotContent(this, 'helptext')}</div>`   // named slot
+ * The directive behind slotContent(): one instance per part. It moves its slot's nodes into the
+ * part itself and always returns noChange, so Lit never commits the nodes. If Lit did, it would
+ * clear the whole part on every change, framework anchors in it included.
  */
 declare class SlotContentDirective extends AsyncDirective {
     private manager;
     private host;
     private part;
     private slotName;
+    /** The manager's generation when the part last placed its nodes. */
     private lastGeneration;
     constructor(partInfo: PartInfo);
     render(_host: LitElement, _slotName?: string): unknown;
+    /** Runs on each host render: registers the part with the host's manager, and places nodes. */
     update(part: ChildPart, [host, slotName]: [LitElement, string?]): unknown;
-    /**
-     * Called by SlotManager when child mutations are detected.
-     */
+    /** Called by the manager after a change. */
     handleNodesChanged(): void;
+    /** Lit removed the part, or the host left the document. */
     disconnected(): void;
     reconnected(): void;
+    /** Whether a node sits in this part. */
     contains(node: Node): boolean;
+    /** The part's start and end markers. */
     bounds(): {
         startNode: Node | null;
         endNode: Node | null;
     };
+    /** The part's container. ChildPart.parentNode skips the cloned fragment during a first render. */
     parentOfPart(): Node | null;
+    /**
+     * Moves the slot's nodes that are not in the part yet into it, in order. Walking from the last
+     * node, each missing node goes before the node after it, or before the part's end. Nodes that
+     * are already in the part stay put, so focus and framework anchors there are left alone.
+     */
     private placeNodes;
+    /** Whether the part spans its whole container, so any node in the container is in the part. */
+    private coversContainer;
+    /** Whether a node is in the container, between the part's start and end markers. */
     private isInsidePart;
 }
 /**
@@ -150,12 +342,17 @@ declare class SlotContentDirective extends AsyncDirective {
  * html`<div class="help">${slotContent(this, 'helptext')}</div>`
  */
 export declare const slotContent: (_host: LitElement, _slotName?: string | undefined) => import('lit-html/directive.js').DirectiveResult<typeof SlotContentDirective>;
+/**
+ * The directive behind forwardSlots(), on a child component's element in the host's template.
+ * It makes the child's manager (the target) include the host's slots (the source).
+ */
 declare class ForwardSlotsDirective extends AsyncDirective {
     private target;
     private source;
     private mapping;
     constructor(partInfo: PartInfo);
     render(_host: LitElement, _slots: ForwardedSlots): unknown;
+    /** Runs on each host render: connects the host's manager to the child element's manager. */
     update(part: ElementPart, [host, slots]: [LitElement, ForwardedSlots]): unknown;
     disconnected(): void;
     reconnected(): void;

package/dist/docs/components/alert.d.ts

@@ -1,7 +1,7 @@
 import { PktElement } from '../../base-elements/element';
 export declare class Alert extends PktElement {
     skins: ("info" | "success" | "warning" | "error")[];
-    sizes: ("medium" | "small" | "xsmall")[];
+    sizes: ("small" | "medium" | "xsmall")[];
     shortMessage: string;
     content: string;
     private onClose;

package/dist/docs/components/slot-internals.d.ts

@@ -0,0 +1,14 @@
+import { TemplateResult } from 'lit';
+import { PktElement } from '../../base-elements/element';
+export declare class SlotInternals extends PktElement {
+    private scenarioIndex;
+    private get scenario();
+    /** 'on' when the chosen scenario is one of the space-separated `scenarios` */
+    private on;
+    private layoutFigure;
+    private mapFigure;
+    private contentEndFigure;
+    private whitespaceFigure;
+    private forwardingFigure;
+    render(): TemplateResult<1>;
+}

package/dist/docs/components/slots.d.ts

@@ -32,4 +32,6 @@ export declare class Slots extends PktElement {
     private renderConditionalContent;
     private renderNestedComponents;
     private renderInnerHtmlTest;
+    private changeImperativeAlert;
+    private firstImperativeNode;
 }