@pitchfork-ui/elements 0.0.0-stage → 0.1.0

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;
+}

package/dist/types/components/pf-context-menu/pf-context-menu.d.ts

@@ -0,0 +1,54 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * A menu opened by right-clicking the region it wraps.
+ *
+ * Unlike `pf-dropdown` there is no anchor element — the menu opens at the
+ * pointer — so it is placed with core's `clampToViewport` rather than the
+ * anchoring observer. The same `pf-menu-item` children serve both.
+ *
+ * @slot - the region that responds to a right-click.
+ * @slot menu - `pf-menu-item` and `pf-menu-separator` children.
+ * @part menu - the floating menu panel.
+ */
+export declare class PfContextMenu {
+    el: HTMLElement;
+    /** Whether the menu is showing. Reflected so the stylesheet can select on it. */
+    open: boolean;
+    /** Accessible name for the menu. */
+    label: string;
+    /**
+     * Let the browser's own context menu through instead. Reflected so the
+     * stylesheet can select on it.
+     */
+    disabled: boolean;
+    /** Fires whenever the menu opens or closes, whoever caused it. */
+    pfOpenChange: EventEmitter<{
+        open: boolean;
+    }>;
+    /** Fires with the chosen item's value. The menu closes itself afterwards. */
+    pfSelect: EventEmitter<{
+        value: string;
+    }>;
+    /** Where the menu was asked to appear, in client coordinates. */
+    private point;
+    /** See pf-popover: the watch is the one place every path passes through. */
+    syncOpen(next: boolean, previous: boolean): void;
+    /** Opens the menu at a point in client coordinates. */
+    showAt(x: number, y: number): Promise<void>;
+    /** Closes the menu. */
+    hide(): Promise<void>;
+    private get panel();
+    private get items();
+    private get enabledItems();
+    private showMenu;
+    private hideMenu;
+    handleContextMenu(event: MouseEvent): void;
+    /** A second right-click moves the open menu, which `showMenu` would skip. */
+    private showMenuAtNewPoint;
+    handleMenuSelect(event: CustomEvent<{
+        value: string;
+    }>): void;
+    handleKeyDown(event: KeyboardEvent): void;
+    private onToggle;
+    render(): any;
+}

package/dist/types/components/pf-credit-card/pf-credit-card.d.ts

@@ -0,0 +1,31 @@
+export type PfCreditCardBrand = 'generic' | 'visa' | 'mastercard' | 'amex';
+/**
+ * A card-shaped display of payment details. Presentational only — it stores
+ * nothing and submits nothing.
+ *
+ * @part glare - the decorative highlight overlay.
+ * @part chip - the decorative chip.
+ * @part brand - the brand wordmark.
+ * @part number - the grouped card number.
+ * @part meta - the row of labelled fields.
+ * @part label - each field's caption.
+ * @part value - each field's value.
+ */
+export declare class PfCreditCard {
+    /** Card network. Reflected so the stylesheet can pick the gradient. */
+    brand: PfCreditCardBrand;
+    /** The number to display. Separators in the input are regrouped. */
+    cardNumber: string;
+    /** Name on the card. */
+    cardholderName: string;
+    /** Expiry, displayed as given. */
+    expiry: string;
+    /** Security code. Omit it to leave the field out entirely. */
+    cvc?: string;
+    /**
+     * Hide all but the last four digits, and the CVC with it. Defaults to true,
+     * so the careless case is the safe one. Reflected for the stylesheet.
+     */
+    masked: boolean;
+    render(): any;
+}

package/dist/types/components/pf-date-picker/pf-date-picker.d.ts

@@ -0,0 +1,121 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * A form-associated date field: a trigger that opens `pf-calendar` in a
+ * popover.
+ *
+ * Form-associated, which the React `DatePicker` is not — it is a button and a
+ * portal, so its value reaches a surrounding `<form>` only if the consumer
+ * wires it there themselves. Here the value is submitted as `YYYY-MM-DD`,
+ * constraint validation works, and Angular's generated accessor has something
+ * to bind to.
+ *
+ * The panel is a `popover`, so light dismiss and Escape are the browser's.
+ * Unlike `pf-dropdown`, the trigger and the panel are both in *this* shadow
+ * root, so `aria-controls` resolves and is worth setting — a same-root IDREF
+ * is the one case that works, measured.
+ *
+ * @part field - the wrapper around label, control and messages.
+ * @part label - the label element.
+ * @part trigger - the button that opens the calendar.
+ * @part clear - the clear button.
+ * @part panel - the floating panel holding the calendar.
+ * @part calendar - the calendar itself.
+ * @part description - the hint text below the control.
+ * @part error - the error message below the control.
+ */
+export declare class PfDatePicker {
+    el: HTMLElement;
+    internals: ElementInternals;
+    /**
+     * Submitted under this name. Reflected, because the submission name comes
+     * from the content attribute and the generated bindings set properties.
+     */
+    name?: string;
+    /** The selected date as `YYYY-MM-DD`, or empty. */
+    value: string;
+    /** Whether the calendar is showing. Reflected for the stylesheet. */
+    open: boolean;
+    /** Visible label. In the same root as the trigger, so `for` works. */
+    label?: string;
+    /** Hint text below the control. */
+    description?: string;
+    /** Error message. Its presence is what marks the control invalid. */
+    error?: string;
+    placeholder: string;
+    required: boolean;
+    disabled: boolean;
+    /** Offer a button that empties the field. */
+    allowClear: boolean;
+    /** Earliest selectable date, as `YYYY-MM-DD`. */
+    min?: string;
+    /** Latest selectable date, as `YYYY-MM-DD`. */
+    max?: string;
+    startYear?: number;
+    endYear?: number;
+    showOutsideDays: boolean;
+    /** A predicate for days that cannot be chosen; see `pf-calendar`. */
+    isDateDisabled?: (date: Date) => boolean;
+    /** Fires when a date is chosen or cleared. */
+    pfChange: EventEmitter<{
+        value: string;
+    }>;
+    /** Fires whenever the calendar opens or closes, whoever caused it. */
+    pfOpenChange: EventEmitter<{
+        open: boolean;
+    }>;
+    /** What a form reset restores; `value` has been overwritten by then. */
+    private initialValue;
+    private stopObserving?;
+    componentWillLoad(): void;
+    disconnectedCallback(): void;
+    syncFormState(): void;
+    /** The one place an open or close is announced, whatever caused it. */
+    syncOpen(next: boolean, previous: boolean): void;
+    /** Opens the calendar. */
+    show(): Promise<void>;
+    /** Closes the calendar. */
+    hide(): Promise<void>;
+    checkValidity(): Promise<boolean>;
+    reportValidity(): Promise<boolean>;
+    getValidationMessage(): Promise<string>;
+    /** A reset restores the value the field started with, not an empty one. */
+    formResetCallback(): void;
+    private get panel();
+    private get trigger();
+    private get calendar();
+    private showPanel;
+    private hidePanel;
+    /**
+     * Mirrors a browser-driven close — a light dismiss or Escape — back into
+     * `open`, which is what then announces it.
+     */
+    private onToggle;
+    /**
+     * Listens on the calendar element itself, not on the host.
+     *
+     * Both were tried. A `@Listen('pfChange')` on the host sees the calendar's
+     * event *and* this element's own — a Stencil event is composed, so by then
+     * both have been retargeted to the host and `event.target` cannot tell them
+     * apart. Worse, `stopPropagation()` there does not help: the consumer's
+     * listener is on that same node, and stopping propagation never stops
+     * same-node listeners, so every pick reported twice. Caught by a test that
+     * counted them.
+     *
+     * On the calendar, the event is stopped before it reaches the host at all,
+     * which does not depend on listener registration order the way
+     * `stopImmediatePropagation` would.
+     */
+    private bindCalendar;
+    private boundCalendar?;
+    private onCalendarChange;
+    private clear;
+    /**
+     * Down opens the calendar from a closed trigger, as a popup button should.
+     * Escape is the browser's while the panel is open — `popover="auto"` handles
+     * it — so there is nothing to do here for it.
+     */
+    private onTriggerKeyDown;
+    /** `MMM D, YYYY`, matching the React component's trigger text. */
+    private formatted;
+    render(): any;
+}

package/dist/types/components/pf-date-range-picker/pf-date-range-picker.d.ts

@@ -0,0 +1,122 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * A form-associated date-range field: two month grids in a popover, with a
+ * preview that follows the pointer while the range is half-made.
+ *
+ * **It submits two entries from one control.** `setFormValue` accepts a
+ * `FormData`, and every entry in it is submitted — measured, along with the
+ * fact that the element's own `name` attribute is then ignored entirely. So a
+ * range goes in as `${name}-start` and `${name}-end`, which is what a server
+ * handling a form actually wants, rather than one field a handler has to split.
+ * The `value` property stays a single round-trippable `start/end` string.
+ *
+ * The grids are rendered here rather than composed from two `pf-calendar`s:
+ * the range preview spans both months, so one element has to own the hover and
+ * the selection for both. The day-state and selection rules are core's, shared
+ * with the React component.
+ *
+ * @part field - the wrapper around label, control and messages.
+ * @part label - the label element.
+ * @part trigger - the button that opens the grids.
+ * @part clear - the clear button.
+ * @part panel - the floating panel.
+ * @part grid - each month grid.
+ * @part day - every day cell.
+ * @part description - the hint text below the control.
+ * @part error - the error message below the control.
+ */
+export declare class PfDateRangePicker {
+    el: HTMLElement;
+    internals: ElementInternals;
+    /**
+     * The base name for the two submitted entries, `${name}-start` and
+     * `${name}-end`. Reflected for selectors; the submission reads the property,
+     * because a `FormData` value carries its own keys.
+     */
+    name?: string;
+    /** The range as `YYYY-MM-DD/YYYY-MM-DD`, or empty. */
+    value: string;
+    /** Whether the panel is showing. Reflected for the stylesheet. */
+    open: boolean;
+    label?: string;
+    description?: string;
+    error?: string;
+    placeholder: string;
+    required: boolean;
+    disabled: boolean;
+    /** Offer a button that empties the range. */
+    allowClear: boolean;
+    min?: string;
+    max?: string;
+    startYear?: number;
+    endYear?: number;
+    /** A predicate for days that cannot be chosen; see `pf-calendar`. */
+    isDateDisabled?: (date: Date) => boolean;
+    /** Fires when the range changes or is cleared, with the `start/end` string. */
+    pfChange: EventEmitter<{
+        value: string;
+        start: string;
+        end: string;
+    }>;
+    /** Fires whenever the panel opens or closes, whoever caused it. */
+    pfOpenChange: EventEmitter<{
+        open: boolean;
+    }>;
+    /** The left-hand month; the right-hand one is always the month after. */
+    leftMonth: Date;
+    /** The day the grids' single tab stop sits on. */
+    focusedDate: Date;
+    /** The day under the pointer, which previews the missing end. */
+    hovered: Date | null;
+    /** True once a start is chosen and the next click sets the end. */
+    awaitingEnd: boolean;
+    private initialValue;
+    /**
+     * The start held while the range is half-made.
+     *
+     * Not in `value`, because `value` is the *submitted* range and a half-made
+     * one is not a range — a form read mid-selection would see a start with no
+     * end. Held here instead, and folded back in for rendering.
+     */
+    private pendingStart;
+    private stopObserving?;
+    private shouldRestoreFocus;
+    componentWillLoad(): void;
+    componentDidRender(): void;
+    disconnectedCallback(): void;
+    /**
+     * Follows a range set from outside, so the grids show what they are told.
+     *
+     * Without this the element kept whatever month it loaded with, and a
+     * consumer assigning `value` got a correct value over the wrong months —
+     * the days it names were not even rendered.
+     */
+    syncDisplayedMonths(): void;
+    syncFormState(): void;
+    syncOpen(next: boolean, previous: boolean): void;
+    show(): Promise<void>;
+    hide(): Promise<void>;
+    checkValidity(): Promise<boolean>;
+    reportValidity(): Promise<boolean>;
+    getValidationMessage(): Promise<string>;
+    formResetCallback(): void;
+    private range;
+    private get years();
+    private clamp;
+    private get panel();
+    private get trigger();
+    private isDisabled;
+    private showPanel;
+    private hidePanel;
+    private onToggle;
+    /** One click through core's state machine, plus this element's side-effects. */
+    private pick;
+    /** What the grids draw: the committed range, or the half-made one. */
+    private displayRange;
+    private moveFocus;
+    private onKeyDown;
+    private clear;
+    private formatted;
+    private renderGrid;
+    render(): any;
+}

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

@@ -0,0 +1,66 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * A menu of actions, anchored to a trigger.
+ *
+ * `popover="auto"`, so light-dismiss and Escape are the browser's, as in
+ * `pf-popover`. The keyboard pattern is the ARIA menu one and reuses core's
+ * roving module — its third consumer, after `pf-toolbar` and
+ * `pf-radio-group` — because the items are custom elements rather than native
+ * controls and have to be queried by tag.
+ *
+ * @slot - the trigger.
+ * @slot menu - `pf-menu-item` and `pf-menu-separator` children.
+ * @part menu - the floating menu panel.
+ */
+export declare class PfDropdown {
+    el: HTMLElement;
+    /** Whether the menu is showing. Reflected so the stylesheet can select on it. */
+    open: boolean;
+    /** Which edge of the trigger the menu lines up with. */
+    align: 'start' | 'end';
+    /** Accessible name for the menu. */
+    label: string;
+    /** Prevent opening. Reflected so the stylesheet can select on it. */
+    disabled: boolean;
+    /** Fires whenever the menu opens or closes, whoever caused it. */
+    pfOpenChange: EventEmitter<{
+        open: boolean;
+    }>;
+    /** Fires with the chosen item's value. The menu closes itself afterwards. */
+    pfSelect: EventEmitter<{
+        value: string;
+    }>;
+    private stopObserving?;
+    componentDidLoad(): void;
+    disconnectedCallback(): void;
+    /** Opens the menu. */
+    show(): Promise<void>;
+    /** Closes the menu. */
+    hide(): Promise<void>;
+    /** See pf-popover: the watch is the one place every path passes through. */
+    syncOpen(next: boolean, previous: boolean): void;
+    private get panel();
+    private get trigger();
+    /** The actionable items, in source order. Separators are not items. */
+    private get items();
+    private get enabledItems();
+    /**
+     * `aria-controls` is absent on purpose: an IDREF does not cross a shadow
+     * boundary, so pointing it at the panel would dangle. `aria-haspopup` and
+     * `aria-expanded` carry what is announced.
+     */
+    private syncTrigger;
+    private showMenu;
+    private hideMenu;
+    handleClick(event: MouseEvent): void;
+    /**
+     * An item asked to be acted on. The menu reports it and closes, which is
+     * what makes `pf-menu-item` reusable: it knows nothing about its container.
+     */
+    handleMenuSelect(event: CustomEvent<{
+        value: string;
+    }>): void;
+    handleKeyDown(event: KeyboardEvent): void;
+    private onToggle;
+    render(): any;
+}

package/dist/types/components/pf-empty-state/pf-empty-state.d.ts

@@ -0,0 +1,43 @@
+export type PfEmptyStateSize = 'sm' | 'md' | 'lg';
+/**
+ * What to show in place of content that is not there: an icon, a heading, a
+ * line of explanation and something to do about it.
+ *
+ * The icon can be a name — `icon="folder-open"`, which renders a `pf-icon` —
+ * or anything slotted into the `icon` slot, for an illustration this library
+ * does not have. The slot wins where both are given.
+ *
+ * @slot - the heading.
+ * @slot description - a line explaining the emptiness.
+ * @slot action - what to do about it, usually a button.
+ * @slot icon - an icon or illustration, in place of the `icon` name.
+ * @part icon - the icon's box.
+ * @part heading - the heading's box.
+ * @part action - the box holding the action slot.
+ */
+export declare class PfEmptyState {
+    el: HTMLElement;
+    /** Padding and type scale. Reflected so the stylesheet can select on it. */
+    size: PfEmptyStateSize;
+    /** An icon name from the same registry as `pf-icon`. */
+    icon?: string;
+    /**
+     * Whether anything is slotted into the `icon` and `action` slots, which
+     * decides whether their boxes are drawn at all.
+     *
+     * Asked in JS, because a wrapper around a slot cannot be collapsed from
+     * CSS: `:not(:has(*))` never matches, since the `<slot>` is itself a child.
+     * The description needs no box of its own, so it is styled through
+     * `::slotted()` and collapses on its own — these two carry layout their
+     * content cannot.
+     */
+    hasIcon: boolean;
+    hasAction: boolean;
+    /**
+     * Read from the light DOM so first paint is right: the mock DOM never fires
+     * `slotchange`, and a real one fires it after the first render.
+     */
+    componentWillLoad(): void;
+    private read;
+    render(): any;
+}