@data-profile/fingerprint 0.0.0-stage → 0.2.0

package/dist/react/index.d.ts

@@ -0,0 +1,300 @@
+/**
+ * `@data-profile/fingerprint/react`: the canvas, legends, list and view switch, the
+ * `useFingerprint` hook that wires them together, and the built-in renderers.
+ *
+ * @packageDocumentation
+ * @module react
+ */
+
+import type { FingerprintAnnotation } from '@data-profile/fingerprint';
+import { FingerprintDataError } from '@data-profile/fingerprint';
+import type { FingerprintDimension } from '@data-profile/fingerprint';
+import type { FingerprintEncoding } from '@data-profile/fingerprint';
+import type { FingerprintForm } from '@data-profile/fingerprint';
+import type { FingerprintItem } from '@data-profile/fingerprint';
+import type { FingerprintLayout } from '@data-profile/fingerprint';
+import type { FingerprintLegendGroup } from '@data-profile/fingerprint';
+import type { FingerprintNode } from '@data-profile/fingerprint';
+import { JSX } from 'react';
+import { markOpacity } from '@data-profile/fingerprint';
+import type { ReactNode } from 'react';
+import type { RidgeStyle } from '@data-profile/fingerprint';
+
+/** Every mark a dot, shape ignored. Only for when shape must carry nothing. */
+export declare const dotsRenderer: FingerprintRenderer;
+
+/** Where callouts go. */
+export declare interface FingerprintCallouts {
+    /** `auto` (the default) puts them beside the print when there is room and numbered below it when not. */
+    placement?: "auto" | "beside" | "below";
+    /** Below this container width, `auto` puts callouts below. Defaults to 640 px. */
+    breakpoint?: number;
+}
+
+/**
+ * The fingerprint itself: ridges, one mark per laid-out node drawn by `renderer`, and optional
+ * callouts. Marks move to their new places when the layout's view changes (instantly under reduced
+ * motion), and marks outside a selection dim. Both are CSS: a selection re-renders no marks. The SVG is one image to assistive technology, named and described by `title` and
+ * `description`; choosing a category is done from the legend or list, which are keyboard
+ * reachable, and also by pointer on a mark.
+ */
+export declare function FingerprintCanvas({ layout, title, description, renderer, ridges, selected, onSelect, annotations, callouts, unit, motion, className, }: FingerprintCanvasProps): JSX.Element;
+
+/** Props for `FingerprintCanvas`, ready to spread; add a `title`. */
+export declare interface FingerprintCanvasBinding {
+    /** The current view's layout. */
+    layout: FingerprintLayout;
+    /** `describeLayout`'s summary of it, or the data error's message. */
+    description: string;
+    /** The current selection. */
+    selected: FingerprintSelection | null;
+    /** Updates the selection. */
+    onSelect: (selection: FingerprintSelection | null) => void;
+    /** What one item is. */
+    unit: string;
+}
+
+/** Props of `FingerprintCanvas`. `useFingerprint`'s `canvasProps` supplies most of them. */
+export declare interface FingerprintCanvasProps {
+    /** What to draw: from `useFingerprint` (`canvasProps`) or `layoutFingerprint`. */
+    layout: FingerprintLayout;
+    /** The drawing's accessible name. */
+    title: string;
+    /** What it shows, in words (`describeLayout` writes one). */
+    description: string;
+    /** Draws each mark. Defaults to `shapesRenderer`. */
+    renderer?: FingerprintRenderer;
+    /** How the ridges behind the marks are drawn. Defaults to `{ show: "auto" }`. */
+    ridges?: RidgeStyle;
+    /** Marks in this category of this dimension are highlighted, the rest dimmed. */
+    selected?: FingerprintSelection | null;
+    /**
+     * Called when a mark is clicked, with its category in the arranging dimension, or null when that
+     * is already the selection.
+     */
+    onSelect?: (selection: FingerprintSelection | null) => void;
+    /** Notes pinned to the print, each with a leader to a mark of the categories it names. */
+    annotations?: readonly FingerprintAnnotation[];
+    /** Where the annotations go. See `FingerprintCallouts`. */
+    callouts?: FingerprintCallouts;
+    /** Names what one item is, for the selection announcement. Defaults to "items". */
+    unit?: string;
+    /** How marks move when the view changes. See `FingerprintMotion`. */
+    motion?: FingerprintMotion;
+    /** Extra class on the canvas's wrapper. */
+    className?: string;
+}
+
+/** Props for `FingerprintLegend` or `FingerprintList`, for one legend group, ready to spread. */
+export declare interface FingerprintGroupBinding {
+    /** The legend group. */
+    group: FingerprintLegendGroup;
+    /** The current selection. */
+    selected: FingerprintSelection | null;
+    /** Updates the selection. */
+    onSelect: (selection: FingerprintSelection | null) => void;
+}
+
+/**
+ * One dimension's categories, each drawn as a mark of it would be in the properties this dimension
+ * drives (a colour swatch for colour, a neutral shape for shape, a fading tone for lightness), and
+ * each a toggle that selects it in the canvas. Render one per `layout.legends` group: the legends
+ * are how a keyboard reaches a category, and what names it.
+ */
+export declare function FingerprintLegend({ group, renderer, selected, onSelect, heading, counts, hideEmpty, className, }: FingerprintLegendProps): JSX.Element;
+
+/** Props of `FingerprintLegend`. `useFingerprint`'s `legendProps(group)` supplies most of them. */
+export declare interface FingerprintLegendProps {
+    /** One dimension's legend, from `layout.legends`. */
+    group: FingerprintLegendGroup;
+    /** The current selection, from `useFingerprint`. */
+    selected?: FingerprintSelection | null;
+    /** Called with a category of this group, or null to clear; makes each entry a toggle. */
+    onSelect?: (selection: FingerprintSelection | null) => void;
+    /** Extra class on the outer element. */
+    className?: string;
+    /** Draws each entry's swatch; use the canvas's renderer so they match. Defaults to `shapesRenderer`. */
+    renderer?: FingerprintRenderer;
+    /** Show the dimension's label above its entries. Defaults to true. */
+    heading?: boolean;
+    /** Show each category's count. Defaults to true. */
+    counts?: boolean;
+    /** Leave out categories with no items. Defaults to false. */
+    hideEmpty?: boolean;
+}
+
+/**
+ * One dimension as a table: every category with its exact count and share. Render one per
+ * `layout.legends` group: together they are the accessible equivalent of the drawing, and the place
+ * a callout's claim can be checked.
+ */
+export declare function FingerprintList({ group, unit, linkLabel, selected, onSelect, className, }: FingerprintListProps): JSX.Element;
+
+/** Props of `FingerprintList`. `useFingerprint`'s `listProps(group)` supplies most of them. */
+export declare interface FingerprintListProps {
+    /** One dimension's legend, from `layout.legends`. */
+    group: FingerprintLegendGroup;
+    /** The current selection, from `useFingerprint`. */
+    selected?: FingerprintSelection | null;
+    /** Called with a category of this group, or null to clear; makes each entry a toggle. */
+    onSelect?: (selection: FingerprintSelection | null) => void;
+    /** Extra class on the outer element. */
+    className?: string;
+    /** What one item is, e.g. "sets". Defaults to "items". */
+    unit?: string;
+    /** Text for each category's link, when it has an `href`. Defaults to "Explore". */
+    linkLabel?: string;
+}
+
+/** What a renderer's `mark` receives. */
+export declare interface FingerprintMarkProps {
+    /** Carries the resolved `color`, `shape` (null when unknown) and `lightness` (null when full strength). */
+    node: FingerprintNode;
+    /** Prefix for any ids the renderer's `defs` declared, unique to this drawing. */
+    idPrefix: string;
+}
+
+/**
+ * How marks move when the view changes. SVG animates only so many marks smoothly, so above each
+ * limit the change is instant instead of stuttering. Under `prefers-reduced-motion` nothing moves.
+ */
+export declare interface FingerprintMotion {
+    /**
+     * Marks glide to their new places while there are at most this many. Defaults to 800: about what
+     * SVG animates smoothly enough (43-50 fps in Chrome); 1,500 gliding marks fell to 16-27 fps. It
+     * sits above the default mark cap of 600 because a layout can exceed its cap slightly.
+     */
+    glide?: number;
+    /**
+     * Colours, fills and lightness fade while there are at most this many marks. Defaults to 400:
+     * fades on top of a glide cost a third of the frame rate at 600 marks, and nothing at 400.
+     */
+    fade?: number;
+}
+
+/**
+ * Draws marks. `mark` draws one mark centred on the origin, `node.size` across, with the ridge
+ * running along the x axis: the canvas positions and rotates it, so a renderer never changes
+ * layout, counts or selection. It should honour `node.color`, `node.shape` and `node.lightness`
+ * (see `markOpacity`), since those carry data. `defs` runs once per drawing. Marks are memoised and
+ * selection is drawn by the canvas (dimming the rest), so `mark` must depend on its props alone.
+ * The canvas transitions the fill, fill-opacity and stroke of each mark's top-level elements.
+ */
+export declare interface FingerprintRenderer {
+    /** A name for debugging and for telling renderers apart. */
+    name: string;
+    /** Shared SVG definitions (gradients, patterns, symbols), rendered once per drawing. */
+    defs?: (props: {
+        idPrefix: string;
+        legends: readonly FingerprintLegendGroup[];
+    }) => ReactNode;
+    /** Draws one mark. */
+    mark: (props: FingerprintMarkProps) => ReactNode;
+}
+
+/** A category of one dimension: what a legend entry or a mark selects. */
+export declare interface FingerprintSelection {
+    /** The dimension the category belongs to. */
+    dimensionId: string;
+    /** The category's id, or `UNKNOWN_CATEGORY_ID`. */
+    categoryId: string;
+}
+
+/** What `useFingerprint` returns. */
+export declare interface FingerprintState {
+    /** The current view's layout; empty while `error` is set. */
+    layout: FingerprintLayout;
+    /** A plain-language summary of the layout, for the canvas's description. */
+    description: string;
+    /** Invalid data (duplicate ids, lightness on an unordered dimension, …), or null. */
+    error: FingerprintDataError | null;
+    /** The views, as given or one per dimension. */
+    views: readonly FingerprintView[];
+    /** The active view. */
+    view: FingerprintView | undefined;
+    /** The active view's id. */
+    viewId: string;
+    /** Switches view and clears the selection. */
+    setViewId: (viewId: string) => void;
+    /** The selected category of a dimension, or null. */
+    selected: FingerprintSelection | null;
+    /** Selects a category of a dimension, or clears with null. */
+    setSelected: (selection: FingerprintSelection | null) => void;
+    /** Spread onto `FingerprintCanvas`, with a `title`. */
+    canvasProps: FingerprintCanvasBinding;
+    /** Spread onto a `FingerprintLegend` for one group. */
+    legendProps: (group: FingerprintLegendGroup) => FingerprintGroupBinding;
+    /** Spread onto a `FingerprintList` for one group, with `unit` included. */
+    listProps: (group: FingerprintLegendGroup) => FingerprintGroupBinding & {
+        unit: string;
+    };
+}
+
+/** A named way of looking at the items: which dimension drives which visual property. */
+export declare interface FingerprintView {
+    /** Unique among the views. */
+    id: string;
+    /** The switch's button text. */
+    label: string;
+    /** Which dimension drives what in this view. */
+    encoding: FingerprintEncoding;
+}
+
+/** One pressed button per view. */
+export declare function FingerprintViewSwitch({ views, value, onChange, label, className, }: FingerprintViewSwitchProps): JSX.Element;
+
+/** Props of `FingerprintViewSwitch`. */
+export declare interface FingerprintViewSwitchProps {
+    /** The views, in button order. */
+    views: readonly FingerprintView[];
+    /** The active view's id. */
+    value: string;
+    /** Called with a view's id when its button is pressed. */
+    onChange: (viewId: string) => void;
+    /** The group's accessible name. Defaults to "View". */
+    label?: string;
+    /** Extra class on the group. */
+    className?: string;
+}
+
+export { markOpacity }
+
+/**
+ * The default: five shapes (circle, rounded square, triangle, diamond, hexagon) by `node.shape`, a
+ * ring in the mark's colour when its shape category is unknown, and lightness as opacity.
+ */
+export declare const shapesRenderer: FingerprintRenderer;
+
+/**
+ * The state a fingerprint needs: the active view, the selected category, the layout for both, and
+ * prop bundles that wire them to the components. The form is derived from all the items and
+ * dimensions, never the active view, so the ridges hold still and only the marks move when the
+ * view changes. Changing view clears the selection. Invalid data comes back as `error` with an
+ * empty layout, rather than throwing out of render.
+ */
+export declare function useFingerprint({ items, dimensions, views: given, initialViewId, form, seed, maxMarks, unit, }: UseFingerprintOptions): FingerprintState;
+
+/** What `useFingerprint` takes. */
+export declare interface UseFingerprintOptions {
+    /** One per mark (below the cap), unique ids. Treated as immutable: pass a new array to change it. */
+    items: readonly FingerprintItem[];
+    /** Every dimension the items carry values for. */
+    dimensions: readonly FingerprintDimension[];
+    /**
+     * The ways of looking, in switcher order. Defaults to one view per dimension, each driving
+     * colour, shape and arrangement from that dimension alone.
+     */
+    views?: readonly FingerprintView[];
+    /** The view shown first. Defaults to the first. */
+    initialViewId?: string;
+    /** Overrides fields of the form `formFromItems` derives from the data. */
+    form?: Partial<FingerprintForm>;
+    /** Seeds the form's free fields. Same seed, same picture. Defaults to "fingerprint". */
+    seed?: string;
+    /** Above this many items, marks stand for several. Defaults to 600. */
+    maxMarks?: number;
+    /** What one item is, for the description and announcements. Defaults to "items". */
+    unit?: string;
+}
+
+export { }