@data-profile/fingerprint 0.0.0-stage → 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,247 @@
+/**
+ * `@data-profile/fingerprint`: the layout, as plain data, with no React. Lay items out
+ * with `layoutFingerprint`, derive a form with `formFromItems`, describe it with `describeLayout`.
+ * The data types and encoding come from `@data-profile/core`.
+ *
+ * @packageDocumentation
+ * @module fingerprint
+ */
+
+import type { Category } from '@data-profile/core';
+import type { Channel } from '@data-profile/core';
+import { DEFAULT_PALETTE } from '@data-profile/core';
+import type { Dimension } from '@data-profile/core';
+import type { Encoding } from '@data-profile/core';
+import { DataError as FingerprintDataError } from '@data-profile/core';
+import type { Item } from '@data-profile/core';
+import type { LegendEntry } from '@data-profile/core';
+import type { LegendGroup } from '@data-profile/core';
+import type { Mark } from '@data-profile/core';
+import { markOpacity } from '@data-profile/core';
+import type { Profile } from '@data-profile/core';
+import { UNKNOWN_CATEGORY_ID } from '@data-profile/core';
+import { UNKNOWN_COLOR } from '@data-profile/core';
+
+export { DEFAULT_PALETTE }
+
+/**
+ * A plain-language summary of what a layout shows, for a screen reader or a caption: the total, the
+ * largest categories of the arranging dimension with their counts, which dimension each visual
+ * property shows when they differ, and how many items each mark stands for. Every number in it is
+ * one the legends also show. Core's `describeProfile`.
+ */
+export declare function describeLayout(layout: FingerprintLayout, unit?: string): string;
+
+/**
+ * A note pinned to the fingerprint, such as "Mostly fiction". The consumer writes the words; the
+ * canvas points a leader at a real mark of the named categories.
+ */
+export declare interface FingerprintAnnotation {
+    /** Unique among the annotations. */
+    id: string;
+    /** Categories the note is about. Hidden when none has a mark. */
+    categoryIds: readonly string[];
+    /** The dimension those categories belong to. Defaults to the arranging dimension. */
+    dimensionId?: string;
+    /** The note's headline. */
+    title: string;
+    /** A sentence under it. */
+    body?: string;
+}
+
+/** One category of a dimension. Core's `Category`. */
+export declare type FingerprintCategory = Category;
+
+/** The visual properties a dimension can drive. `arrange` orders marks along the ridges. Core's `Channel`. */
+export declare type FingerprintChannel = Channel;
+
+export { FingerprintDataError }
+
+/** One way of grouping the items. Category order is the order marks are laid out in. Core's `Dimension`. */
+export declare type FingerprintDimension = Dimension;
+
+/**
+ * Which dimension drives which visual property, by dimension id. `arrange` orders marks along the
+ * ridges. Core's `Encoding`.
+ */
+export declare type FingerprintEncoding = Encoding;
+
+/**
+ * The print's form: its pattern and where its singular points sit. Every number is a small,
+ * bounded nudge, so any form still reads as a fingertip. (A mark's *shape* is something else: an
+ * encoding.)
+ */
+export declare interface FingerprintForm {
+    /** Loop, whorl or arch. */
+    pattern: RidgePattern;
+    /** Which way a loop opens, or a whorl twists. */
+    hand: -1 | 1;
+    /** -1 to 1: moves the core left or right of centre. */
+    coreX: number;
+    /** -1 to 1: moves the core up or down. */
+    coreY: number;
+    /** 0 to 1: how far the deltas sit from the core; wider reads looser. */
+    spread: number;
+    /** Degrees, -10 to 10: the whole pattern's lean. */
+    tilt: number;
+}
+
+/**
+ * The fingerprint's data contract. The data types are `@data-profile/core`'s, under the names this
+ * package has always used; the rest is the fingerprint's own geometry.
+ */
+/** One thing in the collection, drawn as one mark (below the mark cap). Core's `Item`. */
+export declare type FingerprintItem = Item;
+
+/**
+ * What `layoutFingerprint` returns: everything a renderer needs, in a fixed frame. Core's `Profile`
+ * with its marks placed as `nodes`, and the ridges they sit on.
+ */
+export declare interface FingerprintLayout extends Omit<Profile, "marks"> {
+    /** The fixed coordinate frame's width; resizing scales it, never changes it. */
+    width: number;
+    /** The fixed coordinate frame's height. */
+    height: number;
+    /** The marks, laid along the ridges from the core outwards. */
+    nodes: FingerprintNode[];
+    /** The ridges marks sit on, core outwards, as polylines of `[x, y]` points, for renderers that draw them. */
+    ridges: (readonly [x: number, y: number])[][];
+    /** The form actually drawn, every field resolved. */
+    form: FingerprintForm;
+    /** Centre-to-centre distance between neighbouring ridges. */
+    ridgeSpacing: number;
+}
+
+/** One category in a legend, with how its marks are drawn and how many items it holds. Core's `LegendEntry`. */
+export declare type FingerprintLegendEntry = LegendEntry;
+
+/** One dimension's legend, and which visual properties that dimension drives. Core's `LegendGroup`. */
+export declare type FingerprintLegendGroup = LegendGroup;
+
+/** A laid-out mark: core's `Mark`, placed in the layout's fixed coordinate frame. */
+export declare interface FingerprintNode extends Mark {
+    /** Centre, in the layout's frame. */
+    x: number;
+    /** Centre, in the layout's frame. */
+    y: number;
+    /** Degrees, the ridge's direction at this mark. */
+    rotation: number;
+    /** Diameter of the mark's footprint. Area is proportional to weight. */
+    size: number;
+}
+
+/**
+ * A shape that is the collection's own: derived only from the data, so the same collection always
+ * draws the same fingerprint, and it changes slowly as the collection grows. It is a signature,
+ * not a chart; say so beside it. The mapping, which a caption can state:
+ *
+ * - **Pattern.** An arch while there are fewer than 12 items; then a loop when one category of the
+ *   first dimension holds 40% or more of the items (a focused collection); otherwise a whorl.
+ * - **Core across, and loop direction.** Where the second dimension's values sit, on average, in its
+ *   category order: earlier categories pull the core left, later ones right.
+ * - **Core height.** The same for the third dimension.
+ * - **Spread.** The share of all categories that have at least one item: broader reads looser.
+ * - **Tilt.** From the seed only, so two equal collections still differ slightly.
+ */
+export declare function formFromItems(items: readonly FingerprintItem[], dimensions: readonly FingerprintDimension[], seed?: string): FingerprintForm;
+
+/**
+ * Lays the items out along fingerprint ridges.
+ *
+ * `encoding` says which dimension arranges the marks and which drive colour, shape and lightness
+ * (see `FingerprintEncoding`); left out, the first dimension does all but lightness. Items are
+ * sorted by the arranging dimension's category order, then by each other encoded dimension's,
+ * then by id, and laid along the ridges from the core outwards, so categories form runs. Mark
+ * **area** is proportional to weight; positions only arrange.
+ *
+ * A pure function of its input: the same items, dimensions, encoding and options give the same
+ * layout whatever order the items arrive in and whatever size it is drawn at. The ridges come from
+ * `form` (see `formFromItems`). The items array is treated as immutable: work is cached against it.
+ *
+ * Above `maxMarks` items, consecutive items that agree on **every** encoded dimension share a mark
+ * (`itemsPerMark` > 1), so a mark never misrepresents any item in it. Nothing is sampled away.
+ */
+export declare function layoutFingerprint(input: LayoutInput): FingerprintLayout;
+
+/**
+ * `layoutFingerprint`'s one argument. The items array is treated as immutable: work is cached
+ * against it, so pass a new array when the collection changes.
+ */
+export declare interface LayoutInput extends LayoutOptions {
+    /** One per mark (below the cap). Unique ids. */
+    items: readonly FingerprintItem[];
+    /** Every dimension the items carry values for; the encoding picks among them. */
+    dimensions: readonly FingerprintDimension[];
+}
+
+/** Everything `layoutFingerprint` takes besides the data. */
+export declare interface LayoutOptions {
+    /** Which dimension drives what. Defaults to the first dimension arranging, colouring and shaping. */
+    encoding?: FingerprintEncoding;
+    /** Seeds any form field not given, and nothing else. Same seed, same picture. */
+    seed?: string;
+    /** Overrides the print's form. `formFromItems` derives one from the data. */
+    form?: Partial<FingerprintForm>;
+    /**
+     * Above this many items, marks stand for several items each. Defaults to 600, the most marks a
+     * canvas glides smoothly (see `FingerprintCanvas`'s `motion`); raise it for denser prints. A
+     * layout can exceed it slightly, since every combination of encoded categories needs a mark.
+     */
+    maxMarks?: number;
+    /** Ridges never sit further apart than the frame's half-width divided by this. Defaults to 6. */
+    minRidges?: number;
+}
+
+export { markOpacity }
+
+/**
+ * Where each callout goes. Its anchor is a real mark of the categories it names, so the leader
+ * never points at empty paper; the label sits in the gutter on the anchor's side, as level with it
+ * as the other labels allow. Annotations whose categories have no marks are left out.
+ */
+export declare function placeCallouts(layout: FingerprintLayout, annotations: readonly FingerprintAnnotation[]): PlacedCallout[];
+
+/** Where `placeCallouts` puts one annotation, in the layout's frame. */
+export declare interface PlacedCallout {
+    /** The annotation placed. */
+    annotation: FingerprintAnnotation;
+    /** The mark the leader points at: the named categories' mark nearest their centre. */
+    anchor: {
+        x: number;
+        y: number;
+    };
+    /** Which gutter the label sits in: the side of the print its anchor is on. */
+    side: "left" | "right";
+    /** Top of the label, in layout units. */
+    labelY: number;
+    /** 1-based, in reading order: left side top to bottom, then right. */
+    number: number;
+}
+
+/** The three classes every fingerprint falls into. */
+export declare type RidgePattern = "loop" | "whorl" | "arch";
+
+/**
+ * How the ridges behind the marks are drawn. `auto` shows them while a collection is too small for
+ * its marks alone to read as a fingerprint, fading out as it fills.
+ */
+export declare interface RidgeStyle {
+    /** `auto` (the default), `always` or `never`. */
+    show?: "auto" | "always" | "never";
+    /** `auto`: full opacity at or below this many items. Defaults to 60. */
+    fadeFrom?: number;
+    /** `auto`: gone at or above this many items. Defaults to 160. */
+    fadeTo?: number;
+    /** Opacity at full strength. Defaults to 0.22. */
+    opacity?: number;
+    /** Any CSS colour. Defaults to `currentColor`. */
+    color?: string;
+    /** Stroke width as a share of the ridge spacing. Defaults to 0.12. */
+    width?: number;
+}
+
+export { UNKNOWN_CATEGORY_ID }
+
+export { UNKNOWN_COLOR }
+
+export { }

package/dist/index.js

@@ -0,0 +1,25 @@
+import {
+  DataError,
+  UNKNOWN_CATEGORY_ID,
+  describeLayout,
+  formFromItems,
+  layoutFingerprint,
+  placeCallouts
+} from "./chunk-y8jc1j2x.js";
+
+// temp/src/index.ts
+import { DEFAULT_PALETTE, UNKNOWN_COLOR, markOpacity } from "@data-profile/core";
+export {
+  placeCallouts,
+  markOpacity,
+  layoutFingerprint,
+  formFromItems,
+  describeLayout,
+  UNKNOWN_COLOR,
+  UNKNOWN_CATEGORY_ID,
+  DataError as FingerprintDataError,
+  DEFAULT_PALETTE
+};
+
+//# debugId=044A7D70804C965764756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../temp/src/index.ts"],
+  "sourcesContent": [
+    "/**\n * `@data-profile/fingerprint`: the layout, as plain data, with no React. Lay items out\n * with `layoutFingerprint`, derive a form with `formFromItems`, describe it with `describeLayout`.\n * The data types and encoding come from `@data-profile/core`.\n *\n * @packageDocumentation\n * @module fingerprint\n */\nexport { layoutFingerprint, FingerprintDataError, UNKNOWN_CATEGORY_ID } from \"./layout\";\nexport { DEFAULT_PALETTE, UNKNOWN_COLOR, markOpacity } from \"@data-profile/core\";\nexport { formFromItems } from \"./form\";\nexport { placeCallouts, type PlacedCallout } from \"./callouts\";\nexport { describeLayout } from \"./describe\";\nexport type {\n  FingerprintAnnotation,\n  FingerprintCategory,\n  FingerprintChannel,\n  FingerprintDimension,\n  FingerprintEncoding,\n  FingerprintForm,\n  FingerprintItem,\n  FingerprintLayout,\n  FingerprintLegendEntry,\n  FingerprintLegendGroup,\n  FingerprintNode,\n  LayoutInput,\n  LayoutOptions,\n  RidgePattern,\n  RidgeStyle,\n} from \"./types\";\n"
+  ],
+  "mappings": ";;;;;;;;;;AASA;",
+  "debugId": "044A7D70804C965764756E2164756E21",
+  "names": []
+}

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 fingerprint/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/core';
+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 { }