@salilvnair/dui 1.0.7 → 1.0.9

package/dist/lib/components/display/badge-chip-skins.d.ts

@@ -0,0 +1,496 @@
+/**
+ * Fifty ways to draw the same chip.
+ *
+ * The chip started as one look — a raised face with a light top edge, a dark
+ * inner bottom edge and a drop shadow. That reads well alone in a dense
+ * monospace row and badly in a line of five, where every chip looks like a
+ * button you could press and none of them are. Rather than argue the point
+ * once and bake in a second opinion, the look is a value.
+ *
+ * Each entry here is DATA, not a style function, and that is deliberate: the
+ * same table drives the component and the gallery that photographs it, so the
+ * sheet you choose from cannot drift from what the app renders.
+ *
+ * ── What a skin may and may not decide ──
+ *
+ * It decides the surface: fill, border, corner, depth, and how the text is set
+ * — caps or not, mono or not, weight, tracking. It does NOT decide the chip's
+ * height or font size; those come from `size`, so a row of chips in different
+ * skins still lines up on one baseline. A skin that wanted to be taller would
+ * be a different size, not a different skin.
+ *
+ * ── Where they come from ──
+ *
+ * Several are modelled on chips people already know from the web — Material's
+ * assist and filter chips, MUI's filled and outlined, Ant's tag, a GitHub
+ * label, a Tailwind badge with its inset ring, an Atlassian lozenge. They are
+ * named for what they look like rather than who ships them, with the lineage
+ * in the note, because the point is to recognise the shape, not to clone a
+ * product.
+ */
+/** Where the fill comes from, when it is not a percentage of the tone. */
+export type ChipFill = number | 'neutral' | 'surface' | 'sunken';
+export interface ChipSkin {
+    id: string;
+    /** What to call it in a picker. */
+    label: string;
+    /** One line: what it is, and where the shape is from. */
+    note: string;
+    fill?: ChipFill;
+    /** Border strength as a percentage of the tone. */
+    border?: number;
+    borderWidth?: number;
+    borderStyle?: 'solid' | 'dashed';
+    /**
+     * A saturated fill, as a percentage of the tone, with ink on top instead of
+     * the tone in the text. `ink` says which way the text goes.
+     */
+    solid?: number;
+    ink?: 'dark' | 'light';
+    /** An inset ring, the Tailwind badge trick: a border that costs no layout. */
+    ring?: number;
+    /** Corner. A number is px; `pill` is fully round; omitted takes the size's. */
+    radius?: number | 'pill';
+    /** Raised like the original, or sunk into the surface. */
+    depth?: 'raised' | 'inset' | 'lift';
+    /** Uppercase, and mono. Both default true — a label, not a sentence. */
+    caps?: boolean;
+    mono?: boolean;
+    weight?: number;
+    /** Letter-spacing in em. */
+    tracking?: number;
+    /** Added to the size's horizontal padding. */
+    padX?: number;
+    /** A tone-coloured dot before the text. */
+    dot?: boolean;
+    /** Square brackets around the text, which is the box. */
+    brackets?: boolean;
+    /** A rule under the text instead of a box around it. */
+    underline?: boolean;
+    /** A 2px tone edge on the left, square corners. */
+    rail?: boolean;
+    /** No box at all: the colour carries it. */
+    bare?: boolean;
+}
+export declare const BADGE_CHIP_SKINS: readonly [{
+    readonly id: "embossed";
+    readonly label: "Embossed";
+    readonly note: "The original: lit top edge, dark inner bottom, drop shadow.";
+    readonly fill: 20;
+    readonly border: 42;
+    readonly depth: "raised";
+}, {
+    readonly id: "flat";
+    readonly label: "Flat tint";
+    readonly note: "Fill and text, nothing else.";
+    readonly fill: 22;
+}, {
+    readonly id: "soft";
+    readonly label: "Soft";
+    readonly note: "A lighter tint, still boxed.";
+    readonly fill: 14;
+    readonly radius: 6;
+}, {
+    readonly id: "quiet";
+    readonly label: "Quiet";
+    readonly note: "Soft fill with a soft hairline. No depth.";
+    readonly fill: 12;
+    readonly border: 28;
+}, {
+    readonly id: "tint-strong";
+    readonly label: "Strong tint";
+    readonly note: "The tint turned up, no border.";
+    readonly fill: 34;
+}, {
+    readonly id: "ghost";
+    readonly label: "Ghost";
+    readonly note: "A neutral wash; the tone lives in the text.";
+    readonly fill: "neutral";
+}, {
+    readonly id: "surface";
+    readonly label: "Surface";
+    readonly note: "The panel surface with a hairline, like a small card.";
+    readonly fill: "surface";
+    readonly border: 22;
+}, {
+    readonly id: "recessed";
+    readonly label: "Recessed";
+    readonly note: "A well in the surface rather than a raised face.";
+    readonly fill: "sunken";
+    readonly depth: "inset";
+}, {
+    readonly id: "solid";
+    readonly label: "Solid";
+    readonly note: "Full tone with dark ink. The loudest of them.";
+    readonly solid: 100;
+    readonly ink: "dark";
+}, {
+    readonly id: "solid-soft";
+    readonly label: "Solid, softened";
+    readonly note: "The tone at three quarters.";
+    readonly solid: 74;
+    readonly ink: "dark";
+}, {
+    readonly id: "solid-muted";
+    readonly label: "Solid, muted";
+    readonly note: "Half tone with light text.";
+    readonly solid: 52;
+    readonly ink: "light";
+}, {
+    readonly id: "solid-pill";
+    readonly label: "Solid pill";
+    readonly note: "Full tone, fully round.";
+    readonly solid: 100;
+    readonly ink: "dark";
+    readonly radius: "pill";
+}, {
+    readonly id: "hairline";
+    readonly label: "Hairline";
+    readonly note: "Outline only, no fill.";
+    readonly border: 48;
+}, {
+    readonly id: "outline-strong";
+    readonly label: "Strong outline";
+    readonly note: "A heavier rule, still hollow.";
+    readonly border: 62;
+    readonly borderWidth: 1.5;
+}, {
+    readonly id: "outline-dashed";
+    readonly label: "Dashed outline";
+    readonly note: "Hollow and provisional — good for a draft state.";
+    readonly border: 55;
+    readonly borderStyle: "dashed";
+}, {
+    readonly id: "outline-tinted";
+    readonly label: "Tinted outline";
+    readonly note: "A hairline over a faint wash.";
+    readonly fill: 9;
+    readonly border: 44;
+}, {
+    readonly id: "ring";
+    readonly label: "Inset ring";
+    readonly note: "The border drawn inside, so the box never grows.";
+    readonly fill: 10;
+    readonly ring: 26;
+    readonly radius: 6;
+}, {
+    readonly id: "rect";
+    readonly label: "Square";
+    readonly note: "No corner at all.";
+    readonly fill: 16;
+    readonly border: 30;
+    readonly radius: 0;
+}, {
+    readonly id: "tag";
+    readonly label: "Tag";
+    readonly note: "Two-pixel corners. Terminal-ish.";
+    readonly fill: 16;
+    readonly border: 34;
+    readonly radius: 2;
+}, {
+    readonly id: "rounded";
+    readonly label: "Rounded";
+    readonly note: "Six-pixel corners, the web default.";
+    readonly fill: 16;
+    readonly border: 30;
+    readonly radius: 6;
+}, {
+    readonly id: "rounded-lg";
+    readonly label: "Rounded, large";
+    readonly note: "Ten pixels: a rounded rectangle, clearly.";
+    readonly fill: 16;
+    readonly border: 30;
+    readonly radius: 10;
+}, {
+    readonly id: "pill";
+    readonly label: "Pill";
+    readonly note: "Fully round, tinted.";
+    readonly fill: 18;
+    readonly radius: "pill";
+    readonly padX: 2;
+}, {
+    readonly id: "pill-outline";
+    readonly label: "Pill, outlined";
+    readonly note: "Fully round and hollow.";
+    readonly border: 46;
+    readonly radius: "pill";
+    readonly padX: 2;
+}, {
+    readonly id: "pill-quiet";
+    readonly label: "Pill, quiet";
+    readonly note: "Round, faint fill, faint edge.";
+    readonly fill: 11;
+    readonly border: 26;
+    readonly radius: "pill";
+    readonly padX: 2;
+}, {
+    readonly id: "mui-filled";
+    readonly label: "Filled, sentence case";
+    readonly note: "MUI’s filled chip: round, tinted, not shouted.";
+    readonly fill: 16;
+    readonly radius: "pill";
+    readonly padX: 3;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 500;
+    readonly tracking: 0;
+}, {
+    readonly id: "mui-outlined";
+    readonly label: "Outlined, sentence case";
+    readonly note: "MUI’s outlined chip.";
+    readonly border: 40;
+    readonly radius: "pill";
+    readonly padX: 3;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 500;
+    readonly tracking: 0;
+}, {
+    readonly id: "mui-solid";
+    readonly label: "Filled solid, sentence case";
+    readonly note: "MUI’s coloured chip, ink on tone.";
+    readonly solid: 100;
+    readonly ink: "dark";
+    readonly radius: "pill";
+    readonly padX: 3;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 500;
+    readonly tracking: 0;
+}, {
+    readonly id: "m3-assist";
+    readonly label: "Assist";
+    readonly note: "Material 3 assist chip: 8px corner, surface, thin outline.";
+    readonly fill: "surface";
+    readonly border: 26;
+    readonly radius: 8;
+    readonly padX: 2;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 500;
+    readonly tracking: 0;
+}, {
+    readonly id: "m3-filter";
+    readonly label: "Filter";
+    readonly note: "Material 3 filter chip: 8px corner, tinted, no outline.";
+    readonly fill: 20;
+    readonly radius: 8;
+    readonly padX: 2;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 500;
+    readonly tracking: 0;
+}, {
+    readonly id: "m3-input";
+    readonly label: "Input";
+    readonly note: "Material 3 input chip: outlined over a faint wash.";
+    readonly fill: 8;
+    readonly border: 34;
+    readonly radius: 8;
+    readonly padX: 2;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 500;
+    readonly tracking: 0;
+}, {
+    readonly id: "m3-elevated";
+    readonly label: "Elevated";
+    readonly note: "Material 3 elevated chip: a card shadow, no outline.";
+    readonly fill: "surface";
+    readonly radius: 8;
+    readonly depth: "lift";
+    readonly padX: 2;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 500;
+    readonly tracking: 0;
+}, {
+    readonly id: "ant-tag";
+    readonly label: "Tag, light";
+    readonly note: "Ant Design’s tag: 2px corner, pale fill, tone border.";
+    readonly fill: 10;
+    readonly border: 38;
+    readonly radius: 2;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 400;
+    readonly tracking: 0;
+}, {
+    readonly id: "github-label";
+    readonly label: "Issue label";
+    readonly note: "A GitHub label: round, tinted, tone border.";
+    readonly fill: 18;
+    readonly border: 30;
+    readonly radius: "pill";
+    readonly padX: 2;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 500;
+    readonly tracking: 0;
+}, {
+    readonly id: "stripe-badge";
+    readonly label: "Dashboard badge";
+    readonly note: "Stripe’s badge: 4px corner, pale, quiet weight.";
+    readonly fill: 13;
+    readonly radius: 4;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 500;
+    readonly tracking: 0;
+}, {
+    readonly id: "linear-badge";
+    readonly label: "Tracker badge";
+    readonly note: "Linear’s: surface fill, neutral edge, tone text.";
+    readonly fill: "surface";
+    readonly border: 18;
+    readonly radius: 4;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 500;
+    readonly tracking: 0;
+}, {
+    readonly id: "shadcn-outline";
+    readonly label: "Outline, round";
+    readonly note: "shadcn’s outline badge.";
+    readonly border: 42;
+    readonly radius: "pill";
+    readonly padX: 2;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 500;
+    readonly tracking: 0;
+}, {
+    readonly id: "shadcn-solid";
+    readonly label: "Default, round";
+    readonly note: "shadcn’s default badge, ink on tone.";
+    readonly solid: 100;
+    readonly ink: "dark";
+    readonly radius: "pill";
+    readonly padX: 2;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 500;
+    readonly tracking: 0;
+}, {
+    readonly id: "bootstrap";
+    readonly label: "Badge, square-ish";
+    readonly note: "Bootstrap’s badge: 4px corner, solid.";
+    readonly solid: 92;
+    readonly ink: "dark";
+    readonly radius: 4;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 600;
+    readonly tracking: 0;
+}, {
+    readonly id: "bootstrap-pill";
+    readonly label: "Badge, pill";
+    readonly note: "Bootstrap’s rounded-pill badge.";
+    readonly solid: 92;
+    readonly ink: "dark";
+    readonly radius: "pill";
+    readonly padX: 2;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 600;
+    readonly tracking: 0;
+}, {
+    readonly id: "lozenge";
+    readonly label: "Lozenge";
+    readonly note: "Atlassian’s: tiny, bold, uppercase, 3px corner.";
+    readonly fill: 26;
+    readonly radius: 3;
+    readonly weight: 700;
+    readonly tracking: 0.06;
+}, {
+    readonly id: "tailwind-badge";
+    readonly label: "Ring badge";
+    readonly note: "A Tailwind badge: pale fill, inset ring, 6px corner.";
+    readonly fill: 11;
+    readonly ring: 22;
+    readonly radius: 6;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 500;
+    readonly tracking: 0;
+}, {
+    readonly id: "chakra-subtle";
+    readonly label: "Subtle";
+    readonly note: "Chakra’s subtle tag: 6px corner, tinted, sentence case.";
+    readonly fill: 18;
+    readonly radius: 6;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 500;
+    readonly tracking: 0;
+}, {
+    readonly id: "notion-pill";
+    readonly label: "Property pill";
+    readonly note: "A Notion property: round, flat tint, no edge.";
+    readonly fill: 24;
+    readonly radius: "pill";
+    readonly padX: 2;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 400;
+    readonly tracking: 0;
+}, {
+    readonly id: "dot";
+    readonly label: "Dot and text";
+    readonly note: "A state mark, then the word. No box.";
+    readonly bare: true;
+    readonly dot: true;
+    readonly weight: 600;
+    readonly tracking: 0.05;
+}, {
+    readonly id: "dot-pill";
+    readonly label: "Dot in a pill";
+    readonly note: "The mark inside a neutral round box.";
+    readonly fill: "neutral";
+    readonly radius: "pill";
+    readonly padX: 3;
+    readonly dot: true;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 500;
+    readonly tracking: 0;
+}, {
+    readonly id: "dot-outline";
+    readonly label: "Dot, outlined";
+    readonly note: "The mark inside a hollow round box.";
+    readonly border: 34;
+    readonly radius: "pill";
+    readonly padX: 3;
+    readonly dot: true;
+    readonly caps: false;
+    readonly mono: false;
+    readonly weight: 500;
+    readonly tracking: 0;
+}, {
+    readonly id: "rail";
+    readonly label: "Left rail";
+    readonly note: "Square, with the tone as an edge down the left.";
+    readonly fill: 13;
+    readonly rail: true;
+}, {
+    readonly id: "underline";
+    readonly label: "Underline";
+    readonly note: "A rule under the word instead of a box.";
+    readonly bare: true;
+    readonly underline: true;
+}, {
+    readonly id: "bracketed";
+    readonly label: "Bracketed";
+    readonly note: "No box; the brackets are the box.";
+    readonly bare: true;
+    readonly brackets: true;
+}, {
+    readonly id: "text";
+    readonly label: "Text only";
+    readonly note: "The colour, and nothing else.";
+    readonly bare: true;
+}];
+export type BadgeChipVariant = (typeof BADGE_CHIP_SKINS)[number]['id'];
+/** Looked up by id, for the component and for anything that lists them. */
+export declare const CHIP_SKIN_BY_ID: Record<string, ChipSkin>;
+export declare const DEFAULT_CHIP_VARIANT: BadgeChipVariant;

package/dist/lib/components/display/badge-chip.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/components/display/hierarchy-layout.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Layout maths for the hierarchical charts.
+ *
+ * Kept apart from the components because this is the part that can be wrong in
+ * ways nobody sees: an arc that is two degrees short, a row whose widths do not
+ * sum to the parent, a depth that quietly drops the deepest frames. A chart
+ * that renders is not a chart that is correct, so the arithmetic is separated
+ * out where it can be checked.
+ */
+/** A node in anything hierarchical — a heap, a stack, a filesystem. */
+export interface HierarchyNode {
+    name: string;
+    /** Own size. Ignored when there are children — the parent is their sum. */
+    value?: number;
+    children?: HierarchyNode[];
+    /** Anything the caller wants back on the laid-out slice. */
+    meta?: unknown;
+}
+/** One laid-out ring segment. Angles are radians, clockwise from 12 o'clock. */
+export interface SunburstSlice {
+    name: string;
+    value: number;
+    depth: number;
+    startAngle: number;
+    endAngle: number;
+    /** Share of the whole, 0–1. Useful for labelling and for hiding slivers. */
+    share: number;
+    meta?: unknown;
+}
+/** One laid-out flame-graph cell. x and width are fractions of the total, 0–1. */
+export interface FlameCell {
+    name: string;
+    value: number;
+    depth: number;
+    x: number;
+    width: number;
+    meta?: unknown;
+}
+/**
+ * A node's total, computed once.
+ *
+ * A leaf is its own value; a parent is the sum of its children, and its own
+ * `value` is ignored rather than added. Adding both is the classic way to get
+ * a chart whose slices exceed the circle: every level double-counts, and the
+ * error compounds with depth so it looks fine at the top and absurd at the
+ * bottom.
+ */
+export declare function totalOf(node: HierarchyNode): number;
+/**
+ * Lay a hierarchy out as concentric rings.
+ *
+ * The root occupies the full circle and is not emitted — it is the hole in the
+ * middle, and drawing it would put a disc over the labels. Children divide
+ * their parent's arc in the order given, so a caller that wants them biggest
+ * first sorts before calling; this does not reorder, because for a stack the
+ * order IS the meaning.
+ *
+ * `minShare` drops slices too thin to see. They are dropped rather than
+ * merged into a sibling, and their arc is left empty: a "other" wedge invents
+ * a thing that is not in the data, and stretching the survivors to fill the
+ * gap would misstate every remaining share.
+ */
+export declare function sunburstLayout(root: HierarchyNode, opts?: {
+    maxDepth?: number;
+    minShare?: number;
+}): SunburstSlice[];
+/**
+ * Lay a hierarchy out as a flame graph.
+ *
+ * Same arithmetic as the sunburst, unrolled: each level is a row, a child's
+ * width is its share of the parent's width, and children sit directly beneath
+ * the parent they came from. The root is emitted here — in a flame graph it is
+ * the base everything stands on, and leaving it out makes the first real row
+ * look like it floats.
+ */
+export declare function flameLayout(root: HierarchyNode, opts?: {
+    maxDepth?: number;
+    minWidth?: number;
+}): FlameCell[];
+/** One laid-out donut segment. */
+export interface DonutSlice {
+    name: string;
+    value: number;
+    startAngle: number;
+    endAngle: number;
+    share: number;
+    meta?: unknown;
+}
+/**
+ * A single ring, with the tail rolled up.
+ *
+ * Unlike the sunburst this DOES gather what it drops, into an explicit
+ * "other" slice — a flat breakdown of a whole is read as a whole, and a
+ * missing wedge there reads as a rendering bug rather than as a decision.
+ * The rolled-up slice is named, so nobody mistakes it for a real category.
+ */
+export declare function donutLayout(items: {
+    name: string;
+    value: number;
+    meta?: unknown;
+}[], opts?: {
+    maxSlices?: number;
+    otherLabel?: string;
+}): DonutSlice[];
+/**
+ * An SVG arc path for a ring segment.
+ *
+ * Written out rather than pulled from a library because it is twenty lines and
+ * the alternative is a dependency in a component library. The full-circle case
+ * is special: an arc from an angle back to the same angle draws nothing, so a
+ * lone 100% slice would vanish — which is exactly the case a donut of one
+ * dominant thing produces.
+ */
+export declare function arcPath(cx: number, cy: number, rInner: number, rOuter: number, startAngle: number, endAngle: number): string;

package/dist/lib/components/display/hierarchy-layout.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/components/display/lane-scale.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Time-to-pixel maths for the lane charts.
+ *
+ * Separated for the same reason as the hierarchy layout: a chart that renders
+ * is not a chart that is correct. A segment one pixel wide when it should be
+ * forty, a lane whose last event falls off the right edge, two lanes that
+ * disagree about where "now" is — all of them look like a drawing and none of
+ * them look like a bug.
+ */
+export interface Span {
+    /** Start, in whatever unit the caller is using. Milliseconds, usually. */
+    from: number;
+    to: number;
+}
+/** A span placed on the axis, as fractions of the width. */
+export interface PlacedSpan {
+    x: number;
+    width: number;
+    /** True when the span was cut by the window rather than ending inside it. */
+    clippedStart: boolean;
+    clippedEnd: boolean;
+}
+/**
+ * The window every lane shares.
+ *
+ * Computed once from all lanes rather than per lane, because a shared axis is
+ * the entire point: two lanes scaled independently put simultaneous events in
+ * different places, which is worse than not drawing them at all.
+ */
+export declare function windowOf(spans: Span[]): Span | null;
+/**
+ * Place a span on the axis, clipped to the window.
+ *
+ * Returns null when the span is entirely outside, so a caller can drop it
+ * rather than draw a zero-width rectangle at the edge — which reads as an
+ * event that happened at the boundary and did not.
+ */
+export declare function place(span: Span, win: Span): PlacedSpan | null;
+/** A single instant on the axis, for a marker. */
+export declare function placeAt(at: number, win: Span): number | null;
+/**
+ * A polyline through a series, in fractions of width and height.
+ *
+ * y is inverted here — 0 is the top in screen space and the highest value
+ * should be highest on screen. Doing that at the call site is how a chart ends
+ * up upside down in one lane and not the others.
+ */
+export declare function polyline(points: {
+    at: number;
+    value: number;
+}[], win: Span, opts?: {
+    min?: number;
+    max?: number;
+}): {
+    x: number;
+    y: number;
+}[];
+/** An SVG path for a polyline already in fractions, scaled to a box. */
+export declare function pathFor(pts: {
+    x: number;
+    y: number;
+}[], w: number, h: number): string;
+/** The same polyline closed to the baseline, for an area fill. */
+export declare function areaFor(pts: {
+    x: number;
+    y: number;
+}[], w: number, h: number): string;

package/dist/lib/components/display/lane-scale.test.d.ts

@@ -0,0 +1 @@
+export {};