@pitchfork-ui/elements 0.0.0-stage → 0.2.1

package/dist/types/components/pf-carousel/pf-carousel.d.ts

@@ -0,0 +1,73 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * A carousel over `pf-carousel-slide` children.
+ *
+ * The group owns the index, the controls, the indicators and the live region
+ * that announces the move; each slide owns only whether it is the one on show.
+ *
+ * `role="region"` with `aria-roledescription="carousel"` rather than any of
+ * the tab or listbox patterns: a carousel is a region whose content changes,
+ * and the announcement is what tells a reader it has.
+ *
+ * @slot - the `pf-carousel-slide` children.
+ * @slot empty - what to show when there are no slides.
+ * @part viewport - the clipping box.
+ * @part track - the strip that slides.
+ * @part controls - the row holding the buttons and the indicators.
+ * @part previous - the step-back button.
+ * @part next - the step-forward button.
+ * @part indicators - the box holding the dots.
+ * @part indicator - one dot.
+ */
+export declare class PfCarousel {
+    el: HTMLElement;
+    /** The slide on show, counting from 0. */
+    index: number;
+    /** Wrap at both ends rather than stopping. */
+    loop: boolean;
+    /** Show the dots. */
+    showIndicators: boolean;
+    /** Step forward on a timer. */
+    autoPlay: boolean;
+    /** How long between steps, in milliseconds. */
+    autoPlayInterval: number;
+    /** The carousel's accessible name. */
+    label: string;
+    /** The step-back button's accessible name. */
+    previousLabel: string;
+    /** The step-forward button's accessible name. */
+    nextLabel: string;
+    /** Fires when the slide on show changes, however it changed. */
+    pfChange: EventEmitter<{
+        index: number;
+    }>;
+    /** How many slides there are, which every control depends on. */
+    total: number;
+    private timer?;
+    /** The light DOM is readable here, so first paint is already right. */
+    componentWillLoad(): void;
+    componentDidLoad(): void;
+    disconnectedCallback(): void;
+    handleIndexChange(): void;
+    handleTimerChange(): void;
+    /** Re-reads the slides, for a consumer who changed them imperatively. */
+    refresh(): Promise<void>;
+    /** Steps one slide forward, as the button and the timer do. */
+    next(): Promise<void>;
+    /** Steps one slide back. */
+    previous(): Promise<void>;
+    /** Direct children only: a nested carousel owns its own slides. */
+    private get slides();
+    /** The slide actually on show, which an out-of-range index resolves to. */
+    private get resolved();
+    private sync;
+    private goTo;
+    /**
+     * One timer, restarted rather than stacked: a consumer changing the interval
+     * while it runs would otherwise leave the old one going, and the carousel
+     * would step twice as often for no visible reason.
+     */
+    private startTimer;
+    private stopTimer;
+    render(): any;
+}

package/dist/types/components/pf-carousel-slide/pf-carousel-slide.d.ts

@@ -0,0 +1,19 @@
+/**
+ * One slide of a `pf-carousel`.
+ *
+ * The carousel tells it where it sits and whether it is the one on show; it
+ * owns only what that means for itself — chiefly that an off-screen slide is
+ * `inert`, so the focusable content inside it cannot be tabbed to while it is
+ * scrolled out of sight.
+ *
+ * @slot - the slide's content.
+ */
+export declare class PfCarouselSlide {
+    /** Set by the carousel: the slide on show. Reflected for the stylesheet. */
+    active: boolean;
+    /** Set by the carousel: this slide's place, counting from 1. */
+    position: number;
+    /** Set by the carousel: how many slides there are. */
+    total: number;
+    render(): any;
+}

package/dist/types/components/pf-chart-series/pf-chart-series.d.ts

@@ -0,0 +1,33 @@
+/**
+ * One series of a `pf-line-chart` or a `pf-bar-chart`, and its own row in the
+ * legend.
+ *
+ * The chart's data is a single array of rows keyed by series — bulk numbers,
+ * which belong in a property — while the series are the part with names and
+ * colours, which belong in the light DOM so a consumer can loop over them and
+ * so the legend can hold their labels. A legend built in the chart's shadow
+ * root could not reach a slotted label at all.
+ *
+ * `swatch` is the chart's to set: only it knows this series' place in the
+ * palette.
+ *
+ * @slot - the series' name. Falls back to `seriesKey`.
+ * @part dot - the colour swatch.
+ * @part label - the name.
+ */
+export declare class PfChartSeries {
+    /**
+     * The property each data row carries this series' value under.
+     *
+     * `seriesKey`, not `key`: `key` is the vdom's own prop name and reserved,
+     * the same family as `animate` shadowing `Element.prototype.animate`.
+     */
+    seriesKey: string;
+    /** Overrides the palette colour the chart would give it. */
+    color?: string;
+    /** Draw this series' line dashed. Line charts only. Reflected. */
+    dashed: boolean;
+    /** Set by the chart: the colour actually used, palette or override. */
+    swatch: string;
+    render(): any;
+}

package/dist/types/components/pf-checkbox/pf-checkbox.d.ts

@@ -0,0 +1,57 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * A form-associated checkbox.
+ *
+ * @part field - the wrapper around control and label.
+ * @part input - the native checkbox.
+ * @part label - the label element.
+ */
+export declare class PfCheckbox {
+    el: HTMLElement;
+    internals: ElementInternals;
+    /**
+     * Submitted under this name.
+     *
+     * Reflected, because a form-associated custom element takes its submission
+     * name from the `name` *content attribute* -- not from this property. A
+     * framework wrapper that sets properties rather than attributes (the
+     * generated React bindings do) would otherwise leave the control nameless
+     * and absent from the submission, with every other sign of working.
+     */
+    name?: string;
+    /** Whether the box is ticked. Reflected so the stylesheet can select on it. */
+    checked: boolean;
+    /**
+     * What is submitted when ticked. Mirrors the native attribute, whose default
+     * is also `on` — a checkbox with no value still submits something.
+     */
+    value: string;
+    /** Visible label, rendered in the same root so `for` actually associates. */
+    label?: string;
+    /** Error message. Its presence is what marks the control invalid. */
+    error?: string;
+    required: boolean;
+    disabled: boolean;
+    /** Fires when the user ticks or unticks the box. */
+    pfChange: EventEmitter<{
+        checked: boolean;
+        value: string;
+    }>;
+    /** The state a form reset restores, which is the initial attribute. */
+    private initialChecked;
+    componentWillLoad(): void;
+    syncFormState(): void;
+    /** A form-associated custom element does not inherit this. */
+    checkValidity(): Promise<boolean>;
+    /** As `checkValidity`, but also shows the browser's validation message. */
+    reportValidity(): Promise<boolean>;
+    /** The message explaining why the control is invalid, or an empty string. */
+    getValidationMessage(): Promise<string>;
+    /**
+     * A reset restores the initial state, not `false` — a native
+     * `<input type=checkbox checked>` comes back ticked.
+     */
+    formResetCallback(): void;
+    private onChange;
+    render(): any;
+}

package/dist/types/components/pf-code-snippet/pf-code-snippet.d.ts

@@ -0,0 +1,74 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * A code block with a copy button.
+ *
+ * **No syntax highlighting, deliberately.** The React `CodeSnippet` uses
+ * `prism-react-renderer`, which is a React renderer and has no equivalent
+ * here; the alternatives are all large runtime dependencies, and an element in
+ * a design system should not make a consumer's bundle choose one. A consumer
+ * who already highlights code slots the markup their highlighter produced into
+ * the default slot, and this renders that instead of the plain text — it still
+ * owns the frame, the header, the copy button and the announcement.
+ *
+ * Line numbers are offered only for the plain-text path. Aligning a gutter
+ * with someone else's markup needs to know where their lines break, which only
+ * they know.
+ *
+ * @slot - pre-highlighted markup, rendered instead of `code`.
+ * @part figure - the frame.
+ * @part header - the title, language and copy button.
+ * @part title - the title text.
+ * @part language - the language tag.
+ * @part copy - the copy button.
+ * @part pre - the code block.
+ * @part line - one numbered line, when line numbers are on.
+ * @part line-number - that line's number.
+ */
+export declare class PfCodeSnippet {
+    el: HTMLElement;
+    /** The code, as plain text. */
+    code: string;
+    /** Shown as a tag in the header, and not used for anything else. */
+    language?: string;
+    /** Shown in the header. */
+    heading?: string;
+    showLineNumbers: boolean;
+    /** Scrolls past this height, in pixels. */
+    maxHeight?: number;
+    copyLabel: string;
+    copiedLabel: string;
+    copyFailedLabel: string;
+    /**
+     * How long the button keeps saying what the last press did, in
+     * milliseconds.
+     *
+     * A prop rather than a constant because a live region that still holds
+     * "Copied" when the next copy happens announces nothing, so how long it
+     * holds is a real decision — and because a test cannot use fake timers
+     * here: `vi.useFakeTimers()` replaces `requestAnimationFrame`, which
+     * Stencil's render queue runs on, and wedges every test after it.
+     */
+    feedbackDuration: number;
+    /** Fires with the text that reached the clipboard. Not fired on a failure. */
+    pfCopy: EventEmitter<{
+        code: string;
+    }>;
+    /** Fires when the copy could not be made, with the reason shown. */
+    pfCopyError: EventEmitter<{
+        message: string;
+    }>;
+    copied: boolean;
+    failed: boolean;
+    /** Whether the consumer slotted their own highlighted markup. */
+    hasMarkup: boolean;
+    private resetTimer?;
+    /** The light DOM is readable here, so first paint is already right. */
+    componentWillLoad(): void;
+    disconnectedCallback(): void;
+    /** Copies the snippet, as pressing the button does. */
+    copy(): Promise<boolean>;
+    /** What gets copied: the code, or the slotted markup's own text. */
+    private get text();
+    private readSlot;
+    render(): any;
+}

package/dist/types/components/pf-collapsible/pf-collapsible.d.ts

@@ -0,0 +1,56 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * One disclosure: a header that shows and hides the content below it.
+ *
+ * The same panel mechanics as `pf-accordion-item` — a `0fr` → `1fr` grid row
+ * so the height animates to the content's own, and `inert` on the closed panel
+ * because that height still holds focusable content — but no group above it,
+ * so this element owns `open` itself.
+ *
+ * Both IDREFs stay inside this one shadow root, which is where an IDREF
+ * resolves: the header names the panel with `aria-controls` and the panel
+ * names the header back with `aria-labelledby`.
+ *
+ * @slot trigger - the header's label.
+ * @slot - the content.
+ * @part trigger - the header button.
+ * @part label - the label's box inside the header.
+ * @part icon - the chevron.
+ * @part panel - the animating box around the content.
+ * @part content - the region holding the content.
+ */
+export declare class PfCollapsible {
+    /** Whether the content is showing. Reflected so the stylesheet selects on it. */
+    open: boolean;
+    /** Reflected, so the stylesheet can mark the header. */
+    disabled: boolean;
+    /** Show the rotating chevron. Defaults to true. */
+    showChevron: boolean;
+    /** Fires whenever the content opens or closes, whoever caused it. */
+    pfOpenChange: EventEmitter<{
+        open: boolean;
+    }>;
+    /** Opens the content. */
+    show(): Promise<void>;
+    /** Closes the content. */
+    hide(): Promise<void>;
+    /**
+     * The one place the change is announced, whatever caused it: the header, a
+     * method, or a consumer writing the prop. Announcing it from the click
+     * handler instead would miss the other two — the same mistake `pf-popover`
+     * and `pf-modal` both made from their DOM-event handlers.
+     *
+     * A consumer mirroring the value back sets `open` to what it already is,
+     * which Stencil does not treat as a change, so there is no loop.
+     */
+    handleOpenChange(next: boolean, previous: boolean): void;
+    private onClick;
+    /**
+     * Escape closes it from the header, which is what the React component does.
+     * Only from the header: Escape inside the content belongs to whatever is in
+     * there — a dialog, or a field clearing itself.
+     */
+    handleKeyDown(event: KeyboardEvent): void;
+    private trigger?;
+    render(): any;
+}

package/dist/types/components/pf-combobox/pf-combobox.d.ts

@@ -0,0 +1,123 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * A form-associated combobox: an editable field that filters `pf-option`
+ * children.
+ *
+ * It shares `pf-option` with `pf-select`, which is why the option reads a
+ * generic `--pf-option-*` set that each container maps to its own family —
+ * the same arrangement as `pf-menu-item` between the two menus.
+ *
+ * Filtering is core's `matchesCommandQuery`, and so is the rule that a query
+ * which is only the chosen label echoed back does not filter: without it,
+ * reopening the list to change your mind would show the one answer you already
+ * had. Both shared with the React component, which is now rewired to them.
+ *
+ * Two things the React `Combobox` does not do, both gaps rather than choices:
+ * Home and End, and arrows that wrap rather than stop at the ends — which is
+ * what `pf-select` does, and one design system should not have two arrow
+ * behaviours in neighbouring controls.
+ *
+ * @slot - the `pf-option` children.
+ * @part field - the wrapper around label, control and messages.
+ * @part label - the label element.
+ * @part control - the box holding the input, clear button and chevron.
+ * @part input - the editable field.
+ * @part clear - the clear button.
+ * @part listbox - the floating listbox the options are slotted into.
+ * @part empty - the message shown when nothing matches.
+ * @part description - the hint text below the control.
+ * @part error - the error message below the control.
+ */
+export declare class PfCombobox {
+    el: HTMLElement;
+    internals: ElementInternals;
+    /** Submitted under this name. Reflected; the submission reads the attribute. */
+    name?: string;
+    /** The chosen option's value, or empty. */
+    value: string;
+    /** Whether the listbox is showing. Reflected for the stylesheet. */
+    open: boolean;
+    label?: string;
+    description?: string;
+    error?: string;
+    placeholder: string;
+    /** Shown when the query matches nothing. */
+    emptyMessage: string;
+    required: boolean;
+    disabled: boolean;
+    /** Offer a button that empties the field. */
+    clearable: boolean;
+    /** Accessible name for that button. */
+    clearLabel: string;
+    /** Fires when the chosen value changes. */
+    pfChange: EventEmitter<{
+        value: string;
+    }>;
+    /** Fires whenever the listbox opens or closes, whoever caused it. */
+    pfOpenChange: EventEmitter<{
+        open: boolean;
+    }>;
+    /** What the field holds, which is not the value until an option is chosen. */
+    query: string;
+    matchCount: number;
+    private initialValue;
+    private stopObserving?;
+    private activeOption;
+    componentWillLoad(): void;
+    componentDidRender(): void;
+    disconnectedCallback(): void;
+    syncFormState(): void;
+    /** A value set from outside puts its label in the field and marks the option. */
+    syncSelection(): void;
+    syncOpen(next: boolean, previous: boolean): void;
+    show(): Promise<void>;
+    hide(): Promise<void>;
+    checkValidity(): Promise<boolean>;
+    reportValidity(): Promise<boolean>;
+    getValidationMessage(): Promise<string>;
+    formResetCallback(): void;
+    /** Re-reads the options, for a label edited in place (no `slotchange` fires). */
+    refresh(): Promise<void>;
+    private onSlotChange;
+    private options;
+    private visible;
+    /** The property, never the attribute: a binding may only have set the former. */
+    private optionValue;
+    private selectedLabel;
+    private get listbox();
+    private get input();
+    private get control();
+    /**
+     * Hides the options the query excludes.
+     *
+     * `hidden` plus `:host([hidden]) { display: none }` on the option, because
+     * the attribute alone loses to the option's own `display: block`.
+     */
+    private applyQuery;
+    private showListbox;
+    private hideListbox;
+    /**
+     * A browser-driven close — light dismiss or Escape — reverts the field to
+     * the chosen label, so a half-typed query never lingers over a different
+     * value. Focus goes back to the input rather than the trigger, because here
+     * the input *is* the control.
+     */
+    private onToggle;
+    private setActive;
+    /**
+     * Set as an element, not an IDREF: the input is in this shadow root and the
+     * options are slotted light DOM, and a cross-root IDREF is absent from the
+     * accessibility tree — measured. Feature-detected, because where element
+     * reflection is missing there is no cross-root equivalent.
+     */
+    private syncActiveDescendant;
+    private commit;
+    handleOptionSelect(event: CustomEvent<{
+        value: string;
+    }>): void;
+    private move;
+    private onInput;
+    private clear;
+    private onKeyDown;
+    render(): any;
+}

package/dist/types/components/pf-command-group/pf-command-group.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A labelled section of a `pf-command-palette`.
+ *
+ * Grouping is structural here, where the React component takes a `group` name
+ * on each item and buckets them itself. That is not a stylistic choice: the
+ * items are slotted light-DOM children, and a shadow root cannot wrap a subset
+ * of its slotted children in a box — one `<slot>` renders them all, in source
+ * order. So the consumer expresses a group by nesting, which is also what
+ * §2.1 asks for everywhere else.
+ *
+ * @slot - `pf-command-item` children.
+ * @part label - the section heading.
+ */
+export declare class PfCommandGroup {
+    /** The section heading. Searched along with each item's own text. */
+    label?: string;
+    render(): any;
+}

package/dist/types/components/pf-command-item/pf-command-item.d.ts

@@ -0,0 +1,41 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * One command in a `pf-command-palette`.
+ *
+ * It only reports that it was chosen; the palette owns filtering, the active
+ * option and closing, exactly as `pf-radio-group` owns selection for its
+ * radios and `pf-dropdown` owns it for its menu items.
+ *
+ * @slot - the command's label, which is also what the palette searches.
+ * @slot icon - a leading icon.
+ * @part label - the label's box.
+ * @part description - the supporting line.
+ */
+export declare class PfCommandItem {
+    el: HTMLElement;
+    /**
+     * Identifies the command in the palette's select event.
+     *
+     * Reflected, and not only for tidiness: the generated React and Angular
+     * bindings set props as *properties*, so without this there is no `value`
+     * attribute and anything selecting on one — the palette's own item query
+     * included — finds nothing. The same defect as an unreflected `name` on a
+     * form control, and caught the same way, by the consumer apps.
+     */
+    value: string;
+    /** A supporting line under the label. Searched along with the label. */
+    description?: string;
+    /** Reflected so the stylesheet and the palette's item query can select on it. */
+    disabled: boolean;
+    /** Asks the palette to run this command. The palette decides and closes. */
+    pfCommandSelect: EventEmitter<{
+        value: string;
+    }>;
+    /**
+     * Mouse only. The palette keeps keyboard focus in its input and tracks the
+     * active option with `aria-activedescendant`, so Enter is the palette's to
+     * handle — an item never has focus to receive a key on.
+     */
+    private onClick;
+    render(): any;
+}

package/dist/types/components/pf-command-palette/pf-command-palette.d.ts

@@ -0,0 +1,102 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * A searchable command list in a modal dialog.
+ *
+ * A native `<dialog>` opened with `showModal()`, like `pf-modal` and
+ * `pf-slideout-menu`: the focus trap, Escape and the backdrop come free, and
+ * the React component's `useFocusTrap` has no equivalent here. Page scroll is
+ * the one part the dialog does not do, so that is core's reference-counted
+ * lock.
+ *
+ * **The active option is set as an element, not an IDREF.** The input lives in
+ * this shadow root and the options are slotted light-DOM children, and
+ * `aria-activedescendant` does not cross a shadow boundary — measured against
+ * Chromium's accessibility tree, where a cross-root IDREF is simply absent
+ * from it. `ariaActiveDescendantElement` does resolve, because the option sits
+ * in an ancestor scope of the input's tree, which is the direction element
+ * reflection allows. (`pf-tooltip` needed the opposite direction — a trigger
+ * referencing something inside a shadow root it does not own — and that one
+ * reads back empty, which is why it copies text into `aria-description`
+ * instead.)
+ *
+ * @slot - `pf-command-item` and `pf-command-group` children.
+ * @part dialog - the native dialog, which is also the backdrop.
+ * @part panel - the floating panel.
+ * @part input - the search input.
+ * @part list - the listbox the items are slotted into.
+ * @part empty - the message shown when nothing matches.
+ */
+export declare class PfCommandPalette {
+    el: HTMLElement;
+    /** Whether the palette is showing. Reflected so the stylesheet selects on it. */
+    open: boolean;
+    /** Placeholder for the search input. */
+    placeholder: string;
+    /** Shown when the query matches nothing. */
+    emptyMessage: string;
+    /** Accessible name for the dialog. */
+    label: string;
+    /** Close on Escape or a click on the backdrop. Defaults to true. */
+    dismissable: boolean;
+    /** Fires whenever the palette opens or closes, whoever caused it. */
+    pfOpenChange: EventEmitter<{
+        open: boolean;
+    }>;
+    /** Fires with the chosen item's `value`. The palette then closes. */
+    pfSelect: EventEmitter<{
+        value: string;
+    }>;
+    query: string;
+    matchCount: number;
+    private releaseScroll;
+    private activeItem;
+    componentWillLoad(): void;
+    componentDidLoad(): void;
+    componentDidRender(): void;
+    disconnectedCallback(): void;
+    /** Opens the palette. */
+    show(): Promise<void>;
+    /** Closes the palette. */
+    hide(): Promise<void>;
+    syncOpen(next: boolean, previous: boolean): void;
+    /** A child asking to be run. The palette decides, reports and closes. */
+    handleCommandSelect(event: CustomEvent<{
+        value: string;
+    }>): void;
+    private onSlotChange;
+    /** Re-reads the children and re-applies the current query. */
+    refresh(): Promise<void>;
+    private get dialog();
+    private get input();
+    private items;
+    /** The items a query left showing, which is what the arrows move through. */
+    private visibleItems;
+    private lockScroll;
+    private unlockScroll;
+    private showDialog;
+    private closeDialog;
+    private onCancel;
+    private onClose;
+    /** A click on the dialog itself landed on the backdrop, not the panel. */
+    private onDialogClick;
+    private onInput;
+    /**
+     * Hides the items a query excludes, and any group left with none showing.
+     *
+     * The group's own label counts towards each of its items, so typing a
+     * section name narrows to that section — which is what the React component
+     * does with its `group` field.
+     */
+    private applyQuery;
+    private setActive;
+    /**
+     * Feature-detected: where ARIA element reflection is missing there is no
+     * cross-root equivalent, so the active option stops being *announced* while
+     * the arrows, the highlight and Enter all still work. Recorded in `todo.md`.
+     */
+    private syncActiveDescendant;
+    private move;
+    private runActive;
+    private onKeyDown;
+    render(): any;
+}

package/dist/types/components/pf-content-divider/pf-content-divider.d.ts

@@ -0,0 +1,39 @@
+export type PfContentDividerOrientation = 'horizontal' | 'vertical';
+/**
+ * A rule that separates content, optionally labelled.
+ *
+ * @slot - the divider's label. Leave it empty for a plain rule; the element
+ * notices either way and lays the rule out accordingly. Ignored when
+ * `orientation` is `vertical`, which has nowhere to put a label.
+ *
+ * @part line - each of the two rule segments either side of the label, or the
+ * single segment when there is no label.
+ * @part label - the wrapper around the slotted label.
+ */
+export declare class PfContentDivider {
+    el: HTMLElement;
+    /** Reflected so the stylesheet can select on it. */
+    orientation: PfContentDividerOrientation;
+    /** Pad the divider horizontally. Reflected so the stylesheet can select on it. */
+    inset: boolean;
+    /**
+     * Whether anything is slotted. Drives the layout: a labelled divider is
+     * rule-label-rule, an unlabelled one is a single rule. It cannot be a `@Prop`
+     * because the consumer never states it — the presence of slotted content is
+     * the statement, and that can change after first render.
+     */
+    hasLabel: boolean;
+    componentWillLoad(): void;
+    /**
+     * Reads the light DOM rather than the slot's `assignedNodes()`. Both give the
+     * same answer for a single default slot, but the light DOM can be read before
+     * first render, so the divider lays out correctly on its first paint instead
+     * of flickering from unlabelled to labelled once `slotchange` lands. It is
+     * also the only one of the two that Stencil's mock DOM implements.
+     *
+     * A whitespace-only text node is what a formatter leaves behind in
+     * `<pf-content-divider>\n</pf-content-divider>`, and it is not a label.
+     */
+    private syncLabel;
+    render(): any;
+}