@pitchfork-ui/elements 0.0.0-stage → 0.2.1

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

package/dist/types/components/pf-file-uploader/pf-file-uploader.d.ts

@@ -0,0 +1,96 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * A form-associated file picker with a dropzone.
+ *
+ * All of the rules are core's — how a size is written, what makes two
+ * selections the same file, which files a selection leaves you with, what is
+ * wrong with the result and how the limits are described — so this and the
+ * React `FileUploader` cannot drift on any of them.
+ *
+ * It deliberately has **no Angular `ControlValueAccessor`**. The generator
+ * offers accessors that write `value`, a number or `checked`, and this
+ * control's value is a `File[]`: a text accessor would store `[object File]`.
+ * An Angular consumer binds `[files]` and `(pfChange)`, and the submission
+ * still works, because that goes through `ElementInternals` rather than
+ * through the accessor.
+ *
+ * @part field - the wrapper around label, dropzone and messages.
+ * @part label - the label element.
+ * @part dropzone - the button that opens the picker and takes the drop.
+ * @part icon - the dropzone's icon.
+ * @part list - the list of chosen files.
+ * @part file - one row of that list.
+ * @part remove - a row's remove button.
+ * @part description - the hint text.
+ * @part error - the error message.
+ */
+export declare class PfFileUploader {
+    internals: ElementInternals;
+    el: HTMLElement;
+    /**
+     * Submitted under this name.
+     *
+     * Reflected, because a form-associated custom element takes its submission
+     * name from the `name` content attribute rather than from this property.
+     */
+    name?: string;
+    /**
+     * The files chosen. A property only — there is no attribute that could
+     * carry a `File`.
+     */
+    files: File[];
+    /** The `accept` list, in the form an `<input type="file">` takes. */
+    accept?: string;
+    multiple: boolean;
+    /** The most files that may be held at once. */
+    maxFiles?: number;
+    /** The largest any one file may be, in bytes. */
+    maxFileSize?: number;
+    label?: string;
+    description?: string;
+    /** Error message from the consumer. Its presence marks the control invalid. */
+    error?: string;
+    required: boolean;
+    disabled: boolean;
+    /** Fires when the files held change, however they changed. */
+    pfChange: EventEmitter<{
+        files: File[];
+    }>;
+    /** Fires when a selection is refused, with the reason shown to the person. */
+    pfReject: EventEmitter<{
+        message: string;
+    }>;
+    /** The uploader's own complaint about the last selection. */
+    rejection?: string;
+    /**
+     * How deep the drag is.
+     *
+     * A counter rather than a boolean: `dragenter` and `dragleave` both bubble
+     * from the dropzone's own children, so moving the pointer from the icon to
+     * the title fires a leave and then an enter and a boolean flickers off. The
+     * React `FileUploader` has that flicker.
+     */
+    dragDepth: number;
+    /** What a form reset restores, captured before `files` can be replaced. */
+    private initialFiles;
+    private input?;
+    componentWillLoad(): void;
+    syncFormState(): void;
+    checkValidity(): Promise<boolean>;
+    reportValidity(): Promise<boolean>;
+    getValidationMessage(): Promise<string>;
+    /** Opens the file picker, as clicking the dropzone does. */
+    open(): Promise<void>;
+    /**
+     * A reset restores the files the control started with, not an empty list —
+     * the rule a native `<input value="initial">` follows.
+     */
+    formResetCallback(): void;
+    private get limits();
+    private addFiles;
+    private removeAt;
+    private onDragEnter;
+    private onDragLeave;
+    private onDrop;
+    render(): any;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * A single value drawn as a filled arc, with a label in the middle.
+ *
+ * The geometry is `getProgressCircleGeometry`, which `pf-progress-circle` and
+ * the React `ProgressCircle` already share: the dash offset only lands on the
+ * right angle if it and the circumference came from the same radius, and the
+ * radius has to be inset by half the stroke or half of it paints outside the
+ * viewBox.
+ *
+ * It names itself with `label` where the React `GaugeChart` puts the
+ * percentage in `aria-label`. A meter's name should say what is being
+ * measured; the value belongs in `aria-valuetext`, which is where a reader
+ * looks for it, and announcing "73%" as the name of a thing leaves a reader
+ * with no idea what is 73% full.
+ *
+ * @slot center - replaces the percentage in the middle.
+ * @slot sub - a second line under it.
+ * @part svg - the arc's canvas.
+ * @part track - the unfilled ring.
+ * @part fill - the filled arc.
+ * @part center - the box in the middle.
+ * @part label - the big number.
+ */
+export declare class PfGaugeChart {
+    value: number;
+    max: number;
+    /** Diameter, in pixels. */
+    size: number;
+    /** The arc's thickness, in pixels. */
+    strokeWidth: number;
+    /** Overrides the token colour. */
+    color?: string;
+    /** What is being measured. The meter's accessible name. */
+    label: string;
+    render(): any;
+}

package/dist/types/components/pf-header-navigation/pf-header-navigation.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A header navigation over `pf-nav-item` children.
+ *
+ * The group owns the one thing an item cannot know: which item is the current
+ * page. Core's rule decides, so the React `HeaderNavigation` marks the same
+ * one, and it is one index — which is what stops a navigation claiming two
+ * current pages.
+ *
+ * The host is **not** a banner. The React component renders a `<header>`,
+ * which is the banner landmark at the top level of a page, but an element
+ * cannot know whether it is the page's header: a second banner is a defect,
+ * not a decoration. So the shadow root renders only the `<nav>` landmark, and
+ * a consumer who wants a banner puts this inside their own `<header>`.
+ *
+ * @slot - the `pf-nav-item` children.
+ * @slot brand - a logo or product name, before the items.
+ * @slot actions - controls after the items, such as a sign-in button.
+ * @part nav - the navigation landmark.
+ * @part brand - the brand's box.
+ * @part list - the list the items are slotted into.
+ * @part actions - the actions' box.
+ */
+export declare class PfHeaderNavigation {
+    el: HTMLElement;
+    /** The navigation's accessible name. */
+    label: string;
+    /**
+     * Whether anything was slotted into `brand` and `actions`.
+     *
+     * 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 —
+     * and these two boxes have to exist when they are used: they are grid
+     * items, so an empty one still takes a column and a gap, which would push
+     * every item along by one `--space-3` for no visible reason.
+     */
+    hasBrand: boolean;
+    hasActions: boolean;
+    /** The light DOM is readable here, so first paint is already right. */
+    componentWillLoad(): void;
+    componentDidLoad(): void;
+    /**
+     * An item's `current` changed, so the resolution has to run again.
+     *
+     * The items are this navigation's own light-DOM children, so nothing is
+     * retargeted and a host listener is safe — the same reason the sidebar can
+     * listen for a section's copy of this event. `refresh()` stays for a
+     * consumer who changes something else the group reads.
+     */
+    handleStructureChange(event: CustomEvent<void>): void;
+    /**
+     * Re-reads the items, for a consumer who changed something the group reads
+     * and has no event for.
+     */
+    refresh(): Promise<void>;
+    /** Direct children only: a nested navigation owns its own items. */
+    private get items();
+    /**
+     * The property if the item has upgraded, the attribute if it has not:
+     * `componentWillLoad` can run before a child parsed from HTML upgrades.
+     */
+    private isCurrent;
+    private sync;
+    render(): any;
+}