@pitchfork-ui/elements 0.0.0-stage → 0.1.0

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,55 @@
+/**
+ * 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;
+    /**
+     * Re-reads the items, for a consumer who marked one current through its
+     * *property* — which leaves no attribute and fires no `slotchange`.
+     */
+    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;
+}

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

@@ -0,0 +1,55 @@
+import { type HeatmapDatumLike } from '@pitchfork-ui/core';
+/**
+ * A calendar heatmap: one cell per day, darker where the value is higher.
+ *
+ * All of the arithmetic is core's, and the date stepping goes through
+ * `date.ts`, which pins every date to midday — a day step from midnight
+ * across a daylight-saving boundary loses or repeats a day, which is
+ * invisible under UTC and is why both test projects now run in a timezone
+ * that has daylight saving.
+ *
+ * @slot empty - what to show when there is nothing to draw.
+ * @part empty - the empty state's box.
+ * @part weekdays - the column of weekday names.
+ * @part months - the row of month names.
+ * @part grid - the cells.
+ * @part cell - one day.
+ */
+export declare class PfHeatmap {
+    /**
+     * One entry per day with a value, as `{ date: 'YYYY-MM-DD', value }`.
+     *
+     * An array for a framework consumer, or JSON for plain HTML, because
+     * Stencil coerces an attribute only for the primitive types it recognises
+     * and would otherwise hand this the string verbatim.
+     */
+    data: HeatmapDatumLike[] | string;
+    /** First day to draw. Defaults to the earliest in the data. */
+    startDate?: string;
+    /** Last day to draw. Defaults to the latest in the data. */
+    endDate?: string;
+    /** Colour buckets, counting the empty one. */
+    levels: number;
+    /** 0 = Sunday, 1 = Monday. Read through a getter, which coerces. */
+    weekStartsOn: 0 | 1;
+    cellSize: number;
+    cellGap: number;
+    showWeekdayLabels: boolean;
+    showMonthLabels: boolean;
+    /** The chart's accessible name. One is generated when it has none. */
+    label?: string;
+    /** The entries, however they arrived. */
+    private get entries();
+    /**
+     * `0 | 1`, coerced.
+     *
+     * Written out as `0 | 1` rather than as an imported alias, which is the
+     * difference that decides whether Stencil coerces the attribute: measured
+     * side by side, this arrives as the **number** `1` while
+     * `pf-time-picker`'s imported `HourCycle` arrives as the string `"12"`.
+     * The getter stays anyway — it costs nothing and covers a consumer who
+     * sets the property to a string.
+     */
+    private get weekStart();
+    render(): any;
+}

package/dist/types/components/pf-icon/bundled-icons.d.ts

@@ -0,0 +1,3 @@
+export declare const registerBundledIcons: () => void;
+/** The names this package bundles, for the spec that checks them against core. */
+export declare const getBundledIconNames: () => string[];

package/dist/types/components/pf-icon/custom-icons.d.ts

@@ -0,0 +1,3 @@
+import { type VNode } from '../../stencil-public-runtime';
+/** The glyph for a name, as a VNode, or undefined if it is not a custom one. */
+export declare const renderCustomIcon: (name: string) => VNode | undefined;

package/dist/types/components/pf-icon/icon-names.d.ts

@@ -0,0 +1,6 @@
+/** Every name `<pf-icon>` can draw without anything being registered first. */
+export declare const getAvailableIconNames: () => string[];
+/** Just the custom glyphs, the ones with no Font Awesome equivalent. */
+export declare const getCustomIconNames: () => string[];
+/** The Font Awesome names this package bundles, for the spec that checks them. */
+export declare const bundledIconNames: () => string[];

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

@@ -0,0 +1,22 @@
+/**
+ * One glyph from the icon registry.
+ *
+ * The registry is core's, not this element's, and that is deliberate: a
+ * consumer calling `registerIcons()` has to get the icon in the React
+ * components *and* here, and a registry per layer would silently give them
+ * one or the other. A name the registry does not hold renders nothing and
+ * warns once.
+ *
+ * @part svg - the rendered glyph.
+ */
+export declare class PfIcon {
+    /** A registered Font Awesome name, one of its aliases, or a custom glyph. */
+    name: string;
+    /**
+     * Accessible name. Without one the icon is decorative and hidden from
+     * assistive technology, which is the right default beside a text label.
+     */
+    label?: string;
+    render(): any;
+    private renderGlyph;
+}

package/dist/types/components/pf-inline-cta/pf-inline-cta.d.ts

@@ -0,0 +1,69 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+export type PfInlineCtaTone = 'default' | 'info' | 'success' | 'warning' | 'danger';
+/**
+ * A prompt in the flow of a page: an icon, a line or two, something to do, and
+ * optionally a way to send it away.
+ *
+ * Dismissal waits on `Animation.finished` rather than a timeout. The React
+ * `useExitAnimation` guesses 220ms and calls back then, which is wrong twice
+ * over: it fires too early or too late if the stylesheet's duration changes,
+ * and it fires at all when nothing animated. Reading `getAnimations()` after a
+ * frame answers both — the same arrangement `pf-notification.dismiss()` uses,
+ * and for the same measured reason: an `animationend` listener never fires
+ * when no animation started, which is the ordinary case under
+ * `prefers-reduced-motion` or with the stylesheet unloaded.
+ *
+ * @slot - the heading.
+ * @slot description - a line below the heading.
+ * @slot action - what to do about it, usually a button.
+ * @slot icon - an icon, in place of the `icon` name.
+ * @part icon - the icon's box.
+ * @part heading - the heading's box.
+ * @part content - the box holding the heading and the description.
+ * @part action - the box holding the action slot.
+ * @part dismiss - the dismiss button, when `dismissible` is set.
+ */
+export declare class PfInlineCta {
+    el: HTMLElement;
+    /** Colour treatment. Reflected so the stylesheet can select on it. */
+    tone: PfInlineCtaTone;
+    /** An icon name from the same registry as `pf-icon`. */
+    icon: string;
+    /** Offer a dismiss button. Reflected: it changes the padding. */
+    dismissible: boolean;
+    /** The dismiss button's accessible name. */
+    dismissLabel: string;
+    /** Fires once the prompt has finished leaving. */
+    pfDismiss: EventEmitter<void>;
+    /** Whether the exit animation is running. Reflected for the stylesheet. */
+    exiting: boolean;
+    /** Whether anything is slotted into the boxes that carry layout. */
+    hasIcon: boolean;
+    hasAction: boolean;
+    /** Read from the light DOM, so first paint is right without `slotchange`. */
+    componentWillLoad(): void;
+    private read;
+    /**
+     * Plays the exit animation and resolves once it has finished, then reports.
+     *
+     * `getAnimations()` read after a frame, so the class the stylesheet animates
+     * has landed; an empty list resolves at once, which is what makes this
+     * correct with no stylesheet, under `prefers-reduced-motion`, and in both
+     * test projects.
+     */
+    dismiss(): Promise<void>;
+    /**
+     * Waits for the exit animation, or returns straight away when there is not
+     * one.
+     *
+     * The `typeof` guard is for the mock DOM, which has no `getAnimations` at
+     * all — one more of its gaps, alongside the missing `toggleAttribute`. It
+     * surfaced here rather than vanishing because a `TypeError` inside an
+     * `@Method` rejects the promise it returned, where Stencil's `safeCall`
+     * swallows one thrown from a lifecycle method.
+     *
+     * A cancelled animation rejects, which is still "done leaving".
+     */
+    private waitForExit;
+    render(): any;
+}

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

@@ -0,0 +1,79 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+export type PfInputType = 'text' | 'email' | 'password' | 'search' | 'tel' | 'url';
+/**
+ * A form-associated text input.
+ *
+ * `formAssociated` plus `ElementInternals` is what makes this participate in a
+ * real `<form>`: the value reaches `FormData`, constraint validation works, and
+ * Angular's generated value accessor has something to bind to. A plain
+ * `<input>` inside a shadow root does none of that.
+ *
+ * @part field - the wrapper around label, control and messages.
+ * @part label - the label element.
+ * @part input - the native input.
+ * @part description - the hint text below the control.
+ * @part error - the error message below the control.
+ */
+export declare class PfInput {
+    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;
+    /** The control's value. */
+    value: string;
+    type: PfInputType;
+    /** Visible label. Rendered in the same root as the input, 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;
+    readonly: boolean;
+    /** Fires on every keystroke, like the native `input` event. */
+    pfInput: EventEmitter<{
+        value: string;
+    }>;
+    /** Fires when the value is committed, like the native `change` event. */
+    pfChange: EventEmitter<{
+        value: string;
+    }>;
+    /**
+     * The value the control had when it was created, which is what a form reset
+     * restores. Captured here because `value` has been overwritten by then.
+     */
+    private initialValue;
+    componentWillLoad(): void;
+    syncFormState(): void;
+    /**
+     * Whether the control currently satisfies its constraints.
+     *
+     * A form-associated custom element does not inherit `checkValidity` from
+     * anywhere -- the spec puts it on ElementInternals, so the element has to
+     * forward it or consumers cannot ask.
+     */
+    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 value the control started with, not an empty string —
+     * verified against a native `<input value="initial">`, which comes back to
+     * "initial" rather than to "". Clearing it was a real defect: a
+     * `<pf-input value="…">` in a form lost its value on any reset.
+     */
+    formResetCallback(): void;
+    private onInput;
+    private onChange;
+    render(): any;
+}

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

@@ -0,0 +1,18 @@
+export type PfKbdSize = 'sm' | 'md';
+/**
+ * A keyboard key or a combination of them, as `<kbd>` elements.
+ *
+ * `keys` renders one cap per entry with separators between; a single key can
+ * be slotted instead.
+ *
+ * @slot - a single key, when `keys` is not given.
+ * @part kbd - the native kbd element.
+ */
+export declare class PfKbd {
+    /** A key combination rendered as one cap, e.g. `["⌘", "K"]`. */
+    keys?: string[];
+    size: PfKbdSize;
+    /** Separator between keys in a combination. Defaults to `+`. */
+    separator: string;
+    render(): any;
+}

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

@@ -0,0 +1,68 @@
+/** One row of a chart's data: a label and a number per series. */
+export type PfChartRow = {
+    label: string;
+} & Record<string, string | number>;
+/**
+ * A line or area chart over `pf-chart-series` children.
+ *
+ * The split follows what the data is: the rows are bulk numbers and live in a
+ * property, while the series are the part with names and colours and live in
+ * the light DOM, where a consumer can loop over them and where the legend can
+ * reach their labels.
+ *
+ * Every scale and path is core's, so this and the React `LineChart` draw the
+ * same chart — the axis labels and the geometry have to come from the same
+ * tick scale, or the gridlines say one thing and the line says another.
+ *
+ * @slot - the `pf-chart-series` children.
+ * @slot empty - what to show when there is nothing to draw.
+ * @part svg - the drawing.
+ * @part grid - one gridline.
+ * @part tick - one axis label.
+ * @part line - one series' line.
+ * @part area - one series' fill, on the area variant.
+ * @part dot - one data point.
+ * @part legend - the list the series are slotted into.
+ * @part empty - the empty state's box.
+ */
+export declare class PfLineChart {
+    el: HTMLElement;
+    /**
+     * The rows to plot.
+     *
+     * An array for a framework consumer, or JSON for plain HTML, because
+     * Stencil coerces an attribute only for the primitive types it recognises.
+     */
+    data: PfChartRow[] | string;
+    /** Fill under each line. Reflected. */
+    area: boolean;
+    /** Curve the lines through their points rather than joining them straight. */
+    curved: boolean;
+    showLegend: boolean;
+    /** Printed down the y axis, and used as the chart's name when it has none. */
+    yAxisLabel?: string;
+    /** The chart's accessible name. */
+    label?: string;
+    /** The series, read from the light DOM. */
+    series: {
+        key: string;
+        color: string;
+        dashed: boolean;
+    }[];
+    /** The light DOM is readable here, so first paint is already right. */
+    componentWillLoad(): void;
+    componentDidLoad(): void;
+    /** Re-reads the series, for a consumer who changed one through a property. */
+    refresh(): Promise<void>;
+    /**
+     * Direct children only: a nested chart owns its own series.
+     *
+     * Named `seriesElements`, not `children`: a component class's members land
+     * on the custom element itself, so a getter called `children` shadows
+     * `Element.children` and anything that walks it recurses for ever.
+     */
+    private get seriesElements();
+    private get rows();
+    sync(): void;
+    render(): any;
+}

package/dist/types/components/pf-loading-dots/pf-loading-dots.d.ts

@@ -0,0 +1,14 @@
+export type PfLoadingDotsSize = 'sm' | 'md' | 'lg';
+/**
+ * Three pulsing dots, for an indeterminate wait in a tight space.
+ *
+ * @part dot - each of the three dots.
+ * @part label - the visually hidden text the live region announces.
+ */
+export declare class PfLoadingDots {
+    /** Dot size. Reflected so the stylesheet can select on it. */
+    size: PfLoadingDotsSize;
+    /** Accessible name, announced by the live region. */
+    label: string;
+    render(): any;
+}

package/dist/types/components/pf-loading-skeleton/pf-loading-skeleton.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A shimmering placeholder for content that has not arrived.
+ *
+ * @part label - the visually hidden text the live region announces.
+ */
+export declare class PfLoadingSkeleton {
+    /** Width, as a CSS length. A bare number is read as pixels. */
+    width: number | string;
+    /** Height, as a CSS length. A bare number is read as pixels. */
+    height: number | string;
+    /** Use a pill radius instead of the default. Reflected for the stylesheet. */
+    rounded: boolean;
+    /** Accessible name, announced by the live region. */
+    label: string;
+    /**
+     * The React component branches on `typeof width === 'number'`. An attribute
+     * is always a string, so `width="120"` would arrive as `"120"` and be used
+     * as an invalid bare length. Treating a numeric string as pixels keeps
+     * `width="120"` and `width={120}` meaning the same thing, while `width="50%"`
+     * and `width="4rem"` pass through untouched.
+     */
+    private static toLength;
+    render(): any;
+}

package/dist/types/components/pf-loading-spinner/pf-loading-spinner.d.ts

@@ -0,0 +1,12 @@
+/**
+ * An indeterminate spinner.
+ *
+ * @part label - the visually hidden text the live region announces.
+ */
+export declare class PfLoadingSpinner {
+    /** Diameter in pixels. */
+    size: number;
+    /** Accessible name, announced by the live region. */
+    label: string;
+    render(): any;
+}

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

@@ -0,0 +1,43 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * One action inside a `pf-dropdown` or a `pf-context-menu`.
+ *
+ * Shared by both, because the React library's `DropdownItem` and
+ * `ContextMenuItem` are the same shape and the two menus render them
+ * identically — one element rather than two that would drift.
+ *
+ * It only reports that it was chosen. The menu owns focus, closing and the
+ * keyboard pattern, exactly as `pf-radio-group` owns selection for its radios.
+ *
+ * @slot - the item's label.
+ * @slot icon - a leading icon.
+ * @slot shortcut - a trailing keyboard hint.
+ * @part label - the label's box.
+ */
+export declare class PfMenuItem {
+    /**
+     * Identifies the item in the menu's select event.
+     *
+     * Reflected because the generated bindings set props as properties, so
+     * without it a consumer selecting `pf-menu-item[value="..."]` in a React or
+     * Angular app finds nothing. The menus themselves read the property, so this
+     * was not a live defect here -- it is the same trap that was one in
+     * `pf-command-item`.
+     */
+    value: string;
+    /** Reflected so the stylesheet and the menu's item query can select on it. */
+    disabled: boolean;
+    /** Style as a destructive action. Reflected for the stylesheet. */
+    destructive: boolean;
+    /** Asks the menu to act on this item. The menu decides and then closes. */
+    pfMenuSelect: EventEmitter<{
+        value: string;
+    }>;
+    handleClick(event: MouseEvent): void;
+    /**
+     * Enter and Space activate, as they do on a menuitem. The arrows are the
+     * menu's: only it knows the other items.
+     */
+    handleKeyDown(event: KeyboardEvent): void;
+    render(): any;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * A rule between groups of menu items.
+ *
+ * Unlike `pf-toolbar-separator` this needs no orientation: a menu is always a
+ * column, so the rule is always horizontal.
+ */
+export declare class PfMenuSeparator {
+    render(): any;
+}