@krizaka/ui 2.2.0 → 2.3.0

package/dist/iso.d.ts

@@ -0,0 +1,400 @@
+import * as React from 'react';
+
+/** A point in plan (x, y) or on screen (X, Y). */
+type Vec2 = readonly [number, number];
+/** A point in the world: x, y on the floor, z up. */
+type Vec3 = readonly [number, number, number];
+/** The screen point of a world point. */
+declare function project([x, y, z]: Vec3): Vec2;
+/** A regular hexagon footprint (flat top in plan), centre (cx, cy), radius r. */
+declare function hexagon(cx: number, cy: number, r: number): Vec2[];
+/** A rectangle with 45° cut corners (the Krizaka chamfer), centre (cx, cy), size w × d, cut c (0: a plain rectangle). */
+declare function cutRect(cx: number, cy: number, w: number, d: number, c: number): Vec2[];
+/** The screen ellipse of a horizontal circle of radius r at height z: centre and radii. */
+declare function isoCircle(cx: number, cy: number, z: number, r: number): {
+    cx: number;
+    cy: number;
+    rx: number;
+    ry: number;
+};
+/** A point on a circle of the floor plan: angle in degrees, 0 toward the lower right (+x), clockwise on screen. */
+declare function onCircle(r: number, deg: number, [cx, cy]?: Vec2): Vec2;
+
+/** How a solid is lit: the page's surfaces (`base`), the brand accent, accent → accent-2, or frosted glass. */
+type IsoMaterial = "base" | "accent" | "accent2" | "glass";
+/** The footprint of a prism: a hexagon (the marks), a rectangle with 45° cut corners (the icons) or a plain one. */
+type IsoShape = "hex" | "cut" | "rect";
+/** A pictogram drawn on the top of a tile. */
+type IsoGlyph = "dots" | "lines" | "play" | "coin" | "lock" | "arrow" | "flag" | "heart" | "node" | "none";
+interface IsoSceneProps extends Omit<React.ComponentProps<"svg">, "children"> {
+    /** The accessible name of the scene ("A server stack under a dome") — passed translated. Without it the scene is decorative. */
+    label?: string;
+    /** A longer text version of what the scene shows, read by assistive technology. */
+    description?: string;
+    /**
+     * Half the size of the floor, in world units: what the camera frames.
+     * @default 240
+     */
+    extent?: number;
+    /**
+     * Height above the floor the camera keeps in view, in world units.
+     * @default 260
+     */
+    top?: number;
+    /**
+     * The perspective grid on the floor, fading into the page.
+     * @default true
+     */
+    grid?: boolean;
+    /**
+     * The spacing of the grid's lines.
+     * @default 40
+     */
+    step?: number;
+    /**
+     * Motion (entrance, breathing, flow, float). `false` draws the still frame — the one prefers-reduced-motion shows.
+     * @default true
+     */
+    animated?: boolean;
+    /** The objects, painted in order: put the farthest first (or use `IsoHub`, which sorts them). */
+    children?: React.ReactNode;
+}
+/**
+ * The stage: an isometric camera over a perspective grid that fades into the page. Its animations pause off screen and
+ * wait for the page to settle (MotionObserver); everything stops under prefers-reduced-motion.
+ */
+declare function IsoScene({ label, description, extent, top, grid, step, animated, viewBox, className, children, ...props }: IsoSceneProps): React.JSX.Element;
+interface ItemProps {
+    /** The name shown when the pointer (or the focus) lifts the object — passed translated. It also makes it focusable. */
+    label?: string;
+    /**
+     * Its rank in the entrance: objects rise into place one after the other.
+     * @default 0
+     */
+    index?: number;
+    /**
+     * Motion: entrance and loops. `false` keeps this object still.
+     * @default true
+     */
+    animated?: boolean;
+    /** Extra classes on the object's group. */
+    className?: string;
+}
+interface IsoPrismProps extends ItemProps {
+    /**
+     * The centre of its footprint on the floor plan (x, y).
+     * @default [0, 0]
+     */
+    at?: Vec2;
+    /**
+     * The height of its base above the floor.
+     * @default 0
+     */
+    z?: number;
+    /** Its height. */
+    height: number;
+    /**
+     * hex · cut (45° cut corners) · rect.
+     * @default "cut"
+     */
+    shape?: IsoShape;
+    /**
+     * Its width (a number: square or hexagon's diameter) or width × depth.
+     * @default 120
+     */
+    size?: number | Vec2;
+    /** The size of the 45° cut (`shape="cut"`); a sixth of the smaller side by default. */
+    cut?: number;
+    /**
+     * How it is lit.
+     * @default "base"
+     */
+    material?: IsoMaterial;
+    /** A dotted light strip around its front (the LEDs of a server), blinking slowly. */
+    strip?: boolean;
+}
+/** A vertical prism — hexagonal, cut-corner or rectangular — that stacks with others on `z`. */
+declare function IsoPrism({ at, z, height, shape, size, cut, material, strip, animated, ...item }: IsoPrismProps): React.JSX.Element;
+/** One stage of an `IsoStack`. */
+interface IsoLayer {
+    /** The stage's name, shown when it is lifted — passed translated. */
+    label?: string;
+    /**
+     * Its height.
+     * @default 22
+     */
+    height?: number;
+    /**
+     * How it is lit.
+     * @default "base"
+     */
+    material?: IsoMaterial;
+}
+interface IsoStackProps {
+    /** The stages, bottom first; they stack one after the other at the entrance. */
+    layers: readonly IsoLayer[];
+    /**
+     * The centre of the stack on the floor plan.
+     * @default [0, 0]
+     */
+    at?: Vec2;
+    /**
+     * The footprint of the stages.
+     * @default "cut"
+     */
+    shape?: IsoShape;
+    /**
+     * The width of the stages.
+     * @default 120
+     */
+    size?: number;
+    /**
+     * The space between two stages.
+     * @default 4
+     */
+    gap?: number;
+    /**
+     * A hexagonal plinth under the stack.
+     * @default true
+     */
+    plinth?: boolean;
+    /**
+     * A lit hexagonal core on top, its node glowing; a string names it.
+     * @default true
+     */
+    core?: boolean | string;
+    /**
+     * The rank of the first stage in the scene's entrance.
+     * @default 0
+     */
+    index?: number;
+    /**
+     * Motion: entrance and loops. `false` keeps the stack still.
+     * @default true
+     */
+    animated?: boolean;
+}
+/** A stack of stages on a plinth with a lit core on top — a server, a model, a pile of layers — driven by data. */
+declare function IsoStack({ layers, at, shape, size, gap, plinth, core, index, animated }: IsoStackProps): React.JSX.Element;
+interface IsoNodeProps {
+    /**
+     * Where, on the floor plan.
+     * @default [0, 0]
+     */
+    at?: Vec2;
+    /**
+     * Its height.
+     * @default 0
+     */
+    z?: number;
+    /**
+     * The radius of the node.
+     * @default 7
+     */
+    r?: number;
+    /**
+     * The radius of its glow (0: none).
+     * @default 70
+     */
+    glow?: number;
+    /**
+     * Its rank in the entrance.
+     * @default 0
+     */
+    index?: number;
+    /**
+     * Motion: the glow breathes. `false` keeps it still.
+     * @default true
+     */
+    animated?: boolean;
+}
+/** The Krizaka node: a point of light in the accent, breathing in its glow. */
+declare function IsoNode({ at, z, r, glow, index, animated }: IsoNodeProps): React.JSX.Element;
+interface IsoDomeProps {
+    /**
+     * Its centre on the floor plan.
+     * @default [0, 0]
+     */
+    at?: Vec2;
+    /**
+     * The radius of its rim on the floor.
+     * @default 158
+     */
+    radius?: number;
+    /**
+     * Its height.
+     * @default 250
+     */
+    height?: number;
+    /** Its name ("Your infrastructure") — passed translated; shown at the top of the dome, always. */
+    label?: string;
+    /**
+     * Motion: a sheen travels along the dome. `false` keeps it still.
+     * @default true
+     */
+    animated?: boolean;
+}
+/**
+ * A dome of light over what it protects: a rim on the floor, a glass arc, a sheen that travels along it. Draw its rim
+ * before the objects it covers and the dome after them (`part="rim"`, `part="arc"`), or let `IsoHub` do it.
+ */
+declare function IsoDome({ at, radius, height, label, animated, part }: IsoDomeProps & {
+    /**
+     * `rim` (the floor ellipse, drawn first), `arc` (the glass, drawn last) or `both`.
+     * @default "both"
+     */
+    part?: "rim" | "arc" | "both";
+}): React.JSX.Element;
+interface IsoTileProps extends ItemProps {
+    /** Its centre on the floor plan. */
+    at: Vec2;
+    /**
+     * The height it floats at.
+     * @default 90
+     */
+    z?: number;
+    /**
+     * Width × depth.
+     * @default [76, 52]
+     */
+    size?: Vec2;
+    /**
+     * The pictogram on its top.
+     * @default "none"
+     */
+    glyph?: IsoGlyph;
+    /**
+     * How it is lit.
+     * @default "accent"
+     */
+    material?: IsoMaterial;
+    /**
+     * It floats gently.
+     * @default true
+     */
+    float?: boolean;
+}
+/** A satellite: a thin cut-corner tile that floats beside the hero object, a pictogram on its top. */
+declare function IsoTile({ at, z, size, glyph, material, float, animated, ...item }: IsoTileProps): React.JSX.Element;
+interface IsoLinkProps {
+    /** Where it starts, on the floor plan. */
+    from: Vec2;
+    /** Where it ends, on the floor plan. */
+    to: Vec2;
+    /**
+     * The height it runs at.
+     * @default 0
+     */
+    z?: number;
+    /**
+     * `elbow` follows the floor's axes, like a circuit; `straight` goes directly.
+     * @default "elbow"
+     */
+    route?: "elbow" | "straight";
+    /**
+     * Which way the light flows: `out` from `from` to `to`, `in` back.
+     * @default "out"
+     */
+    direction?: "out" | "in";
+    /**
+     * Particles of light travelling along it (0: only the dashes flow).
+     * @default 2
+     */
+    particles?: number;
+    /**
+     * Seconds a particle takes to cross it.
+     * @default 3.6
+     */
+    duration?: number;
+    /** A value written on it ("90 %", "Tips") — passed translated. */
+    label?: string;
+    /**
+     * Motion: the flow and the particles. `false` draws them still, resting along the link.
+     * @default true
+     */
+    animated?: boolean;
+}
+/** A dotted link on the floor, light flowing along it and particles crossing it — a flow between two objects. */
+declare function IsoLink({ from, to, z, route, direction, particles, duration, label, animated }: IsoLinkProps): React.JSX.Element;
+interface IsoLabelProps {
+    /** Where, on the floor plan. */
+    at: Vec2;
+    /**
+     * Its height.
+     * @default 0
+     */
+    z?: number;
+    /** The text — passed translated. */
+    text: string;
+    /** A first part in the accent, bolder ("90 %" before " to the creator"). */
+    strong?: string;
+}
+/** A label in a pill, always visible, pinned to a point of the scene (a share, a name). */
+declare function IsoLabel({ at, z, text, strong }: IsoLabelProps): React.JSX.Element;
+/** A satellite of an `IsoHub`. */
+interface IsoSatellite {
+    /** Its name, shown when lifted — passed translated. */
+    label: string;
+    /**
+     * Its pictogram.
+     * @default "none"
+     */
+    glyph?: IsoGlyph;
+    /**
+     * The flow on its link: `in` toward the centre, `out` from it, `none` without a link.
+     * @default "in"
+     */
+    flow?: "in" | "out" | "none";
+    /** A value written on its link ("+ €5") — passed translated. */
+    value?: string;
+    /**
+     * How it is lit.
+     * @default "accent"
+     */
+    material?: IsoMaterial;
+}
+interface IsoHubProps extends Omit<IsoSceneProps, "children"> {
+    /** The hero object in the centre: its stages, bottom first. */
+    layers: readonly IsoLayer[];
+    /**
+     * The footprint of the stages.
+     * @default "cut"
+     */
+    shape?: IsoShape;
+    /**
+     * The width of the stages.
+     * @default 120
+     */
+    size?: number;
+    /**
+     * A lit core on top of the stack; a string names it.
+     * @default true
+     */
+    core?: boolean | string;
+    /** A dome over the centre: `true`, or its name ("Your servers"). */
+    dome?: boolean | string;
+    /**
+     * The objects around the centre, joined to it by flows of light. The first half stands on the left, the rest on the
+     * right, top to bottom: never in front of the hero, never hidden behind it.
+     */
+    satellites?: readonly IsoSatellite[];
+    /**
+     * The distance of the satellites from the centre.
+     * @default 210
+     */
+    radius?: number;
+    /** The angle of each satellite, in degrees (0: lower right, 90: lower left, 180: upper left, 270: upper right), to place them by hand. */
+    angles?: readonly number[];
+    /** A label pinned above the centre, its first part in the accent: `{ strong: "90 %", text: "to the creator" }`. */
+    highlight?: {
+        readonly strong?: string;
+        readonly text: string;
+    };
+}
+/**
+ * The hero, driven by data: a stack under an optional dome, satellites on both sides, a flow of light between each
+ * satellite and the centre. Objects are painted back to front and the camera frames exactly what is drawn.
+ */
+declare function IsoHub({ layers, shape, size, core, dome, satellites, radius, angles, highlight, animated, viewBox, extent, ...scene }: IsoHubProps): React.JSX.Element;
+
+export { IsoDome, type IsoDomeProps, type IsoGlyph, IsoHub, type IsoHubProps, IsoLabel, type IsoLabelProps, type IsoLayer, IsoLink, type IsoLinkProps, type IsoMaterial, IsoNode, type IsoNodeProps, IsoPrism, type IsoPrismProps, type IsoSatellite, IsoScene, type IsoSceneProps, type IsoShape, IsoStack, type IsoStackProps, IsoTile, type IsoTileProps, type Vec2, type Vec3, cutRect, hexagon, isoCircle, onCircle, project };