@danxbot/ui 3.13.0 → 4.0.0

package/dist/types/components/provenance/ConfidenceMeter.d.ts

@@ -1,6 +1,12 @@
+import { type ConfidenceScore } from "./types";
 export interface ConfidenceMeterProps {
-    /** 0..1, or null when nothing scored it. */
-    confidence: number | null;
+    /**
+     * A 0–1 score from `confidenceScore()`, or null when nothing scored it.
+     *
+     * Deliberately NOT a plain number — see the header. A raw literal will not
+     * type-check, which is what keeps a "4 out of 5" out of a percentage.
+     */
+    confidence: ConfidenceScore | null;
     /**
      * What to say when there is no score.
      *

package/dist/types/components/provenance/ConfidenceReadout.d.ts

@@ -0,0 +1,17 @@
+import type { ProvenanceConfidence } from "./types";
+export interface ConfidenceReadoutProps {
+    confidence: ProvenanceConfidence | null;
+    /**
+     * What to say when nothing scored it.
+     *
+     * Text rather than an empty bar, because a bar at zero and a bar with nothing
+     * to show look identical and mean opposite things.
+     */
+    unscoredLabel?: string;
+    /** What a RATING is of, at the head of its accessible name. @default "Confidence" */
+    ratingLabel?: string;
+    /** Hides the band name on a SCORE, for dense rows where the bar is enough. */
+    compact?: boolean;
+    className?: string;
+}
+export declare function ConfidenceReadout({ confidence, unscoredLabel, ratingLabel, compact, className, }: ConfidenceReadoutProps): import("react").JSX.Element;

package/dist/types/components/provenance/RatingPips.d.ts

@@ -0,0 +1,109 @@
+import { type VariantProps } from "tailwind-variants";
+declare const pips: import("tailwind-variants").TVReturnType<{
+    size: {
+        xs: {
+            root: string;
+            pip: string;
+        };
+        sm: {
+            root: string;
+            pip: string;
+        };
+    };
+    band: {
+        high: {
+            pip: string;
+        };
+        moderate: {
+            pip: string;
+        };
+        low: {
+            pip: string;
+        };
+    };
+}, {
+    root: string;
+    pip: string;
+}, undefined, {
+    size: {
+        xs: {
+            root: string;
+            pip: string;
+        };
+        sm: {
+            root: string;
+            pip: string;
+        };
+    };
+    band: {
+        high: {
+            pip: string;
+        };
+        moderate: {
+            pip: string;
+        };
+        low: {
+            pip: string;
+        };
+    };
+}, {
+    root: string;
+    pip: string;
+}, import("tailwind-variants").TVReturnTypeLike<{
+    size: {
+        xs: {
+            root: string;
+            pip: string;
+        };
+        sm: {
+            root: string;
+            pip: string;
+        };
+    };
+    band: {
+        high: {
+            pip: string;
+        };
+        moderate: {
+            pip: string;
+        };
+        low: {
+            pip: string;
+        };
+    };
+}, {
+    root: string;
+    pip: string;
+}>>;
+/** How big the ticks are. See the two variants above for where each is used. */
+export type RatingPipsSize = NonNullable<VariantProps<typeof pips>["size"]>;
+export interface RatingPipsProps {
+    /**
+     * The rating itself, on `scale`. Null when nothing rated it — which draws the
+     * empty box rather than nothing at all, so the row keeps its height.
+     */
+    rating: number | null;
+    /** The top of the scale — the "5" in "4 out of 5". */
+    scale: number;
+    /**
+     * What the rating is OF, used verbatim at the head of the accessible name and
+     * the tooltip: `"<label> 3 of 5"`.
+     *
+     * A default that named the consumer's domain would be a lie in every other
+     * consumer, so it is the blandest true word.
+     *
+     * @default "Confidence"
+     */
+    label?: string;
+    /**
+     * Draw the pips at full marks too.
+     *
+     * @default false — see "FULL MARKS DRAW NOTHING" above.
+     */
+    showWhenFull?: boolean;
+    /** @default "sm" */
+    size?: RatingPipsSize;
+    className?: string;
+}
+export declare function RatingPips({ rating, scale, label, showWhenFull, size, className, }: RatingPipsProps): import("react").JSX.Element;
+export {};

package/dist/types/components/provenance/index.d.ts

@@ -1,5 +1,7 @@
 export * from "./types";
 export * from "./ConfidenceMeter";
+export * from "./ConfidenceReadout";
+export * from "./RatingPips";
 export * from "./ProvenanceBadge";
 export * from "./ProvenanceDetail";
 export * from "./ProvenanceDisclosure";

package/dist/types/components/provenance/types.d.ts

@@ -56,8 +56,12 @@ export interface ProvenanceRecord {
     /** Null when it failed, or when the viewer may not see it. */
     value: ReactNode | null;
     state: ProvenanceState;
-    /** 0..1. Null when nothing scored it. */
-    confidence: number | null;
+    /**
+     * How sure the author was, on whichever scale they said it — `scoredConfidence`
+     * for a continuous 0–1 figure, `ratedConfidence` for "4 out of 5". Null when
+     * nothing scored it, which is a different claim from a score of zero.
+     */
+    confidence: ProvenanceConfidence | null;
     source: ProvenanceSource | null;
     reasoning: string | null;
     check: ProvenanceCheck | null;
@@ -73,6 +77,73 @@ export interface ProvenanceRecord {
      */
     redacted?: boolean;
 }
+declare const CONFIDENCE_SCORE: unique symbol;
+/**
+ * A confidence on the CONTINUOUS 0–1 scale — the one thing that may be drawn as
+ * a percentage.
+ *
+ * Nominal on purpose. It IS a number at runtime and arithmetic on it behaves
+ * exactly as it reads, but a raw `0.94` is not assignable to it. `confidenceScore`
+ * is the only way in, and is therefore the one place a range can be checked.
+ */
+export type ConfidenceScore = number & {
+    readonly [CONFIDENCE_SCORE]: "score";
+};
+/**
+ * Mint a 0–1 score.
+ *
+ * Out of range is CLAMPED and warned about rather than thrown: the caller most
+ * likely to be out of range is one holding a rating on some other scale, and a
+ * blank page is a worse outcome than a bar at one end with a line in the console
+ * naming the function that fixes it.
+ */
+export declare function confidenceScore(value: number): ConfidenceScore;
+/**
+ * HOW SURE THE AUTHOR WAS, carrying WHICH KIND OF SCALE it was said on.
+ *
+ * Never written as a literal — see the brand above. `scoredConfidence` and
+ * `ratedConfidence` are the two doors, and which door a value came through is
+ * what the renderer dispatches on.
+ */
+export type ProvenanceConfidence = 
+/** Continuous 0–1. Drawn as a banded meter with its percentage. */
+{
+    readonly kind: "score";
+    readonly score: ConfidenceScore;
+}
+/**
+ * `rating` out of `scale`, both whole numbers. Drawn as pips — one per point
+ * — because the scale's own granularity is the finest thing that can honestly
+ * be shown.
+ */
+ | {
+    readonly kind: "rating";
+    readonly rating: number;
+    readonly scale: number;
+};
+/** A continuous 0–1 confidence, for a record. */
+export declare function scoredConfidence(value: number): ProvenanceConfidence;
+/**
+ * A discrete `rating` out of `scale`, for a record.
+ *
+ * The denominator travels WITH the number, because "4" means nothing on its own
+ * and every consumer that has had to pass a rating around without one has ended
+ * up hard-coding the scale at the far end.
+ */
+export declare function ratedConfidence(rating: number, scale: number): ProvenanceConfidence;
 /** 0..1 to a band. A bare percentage invites false precision. */
 export type ConfidenceBand = "high" | "moderate" | "low";
-export declare function confidenceBand(confidence: number): ConfidenceBand;
+export declare function confidenceBand(confidence: ConfidenceScore): ConfidenceBand;
+/**
+ * A RATING to the same three bands, so pips and a meter agree about what
+ * "moderate" looks like.
+ *
+ * Full marks are their own band — `high` — and the rest fall where the same
+ * thresholds put them once the rating is read as a fraction of its own scale.
+ * That is the only conversion to a fraction anywhere in this file, and it feeds
+ * a COLOUR rather than a printed figure, which is the distinction the whole
+ * split rests on: a band is a judgement three values wide and survives the trip;
+ * a percentage is a figure and does not.
+ */
+export declare function ratingBand(rating: number, scale: number): ConfidenceBand;
+export {};

package/dist/types/index.d.ts

@@ -109,7 +109,7 @@ export { AmbiguousTimeError, addDays, addDuration, addMonths, atMidnight, atTime
 export { allDayBandSegment, dayKey, daySlots, isAllDay, packBand, packLanes, snapFractionToInstant, timeSegments, timedBandSegment, type AllDayEvent, type BandInput, type BandOptions, type BandPlacement, type BandResult, type BandSegment, type CalendarEvent, type CalendarEventId, type CalendarView, type DaySlot, type DragKind, type EventDraft, type EventPalette, type LaneInput, type LaneOptions, type LanePlacement, type PaletteEntry, type TimeSegment, type TimedEvent, type VisibleRange, } from "./lib/calendar";
 export { RBACProvider, useRBAC, AccountMenu, DevToolsPopover, RolePermissionMatrix, ProfilePage, RolesPermissionsPage, type RBACProviderProps, type RBACHookResult, type AccountMenuProps, type DevToolsPopoverProps, type RolePermissionMatrixProps, type Permission, type Role, type User, type Team, type TeamMembership, } from "./components/rbac";
 export { UseCaseCard, RoadmapItemCard, RoadmapSwimlaneBoard, UseCaseLedgerPage, RoadmapPage, PhaseManager, TrackManager, deriveRoadmapItemStatus, isFullyBuilt, isUnbuilt, trackIds, trackProgress, toneForIndex, CATEGORY_TONES, type Domain, type Phase, type Track, type RoadmapItem, type RoadmapItemStatus, type UseCase, type UseCaseStatus, type UseCaseDecision, type UseCaseCardProps, type RoadmapItemCardProps, type RoadmapSwimlaneBoardProps, type UseCaseLedgerPageProps, type RoadmapPageProps, type PhaseManagerProps, type TrackManagerProps, } from "./components/roadmap";
-export { ProvenanceDisclosure, ProvenanceDetail, ProvenanceBadge, ConfidenceMeter, provenanceStateLabel, confidenceBand, type ProvenanceRecord, type ProvenanceState, type ProvenanceSource, type ProvenanceCheck, type ProvenanceCall, type ProvenanceSignoff, type ConfidenceBand, type ProvenanceDisclosureProps, type ProvenanceDetailProps, type ProvenanceDetailTitleAs, type ProvenanceTriggerBadge, type ProvenanceBadgeProps, type ProvenanceBadgeAppearance, type ConfidenceMeterProps, } from "./components/provenance";
+export { ProvenanceDisclosure, ProvenanceDetail, ProvenanceBadge, ConfidenceReadout, ConfidenceMeter, RatingPips, provenanceStateLabel, confidenceBand, ratingBand, confidenceScore, scoredConfidence, ratedConfidence, type ProvenanceRecord, type ProvenanceState, type ProvenanceSource, type ProvenanceCheck, type ProvenanceCall, type ProvenanceSignoff, type ConfidenceBand, type ConfidenceScore, type ProvenanceConfidence, type ConfidenceReadoutProps, type RatingPipsProps, type RatingPipsSize, type ProvenanceDisclosureProps, type ProvenanceDetailProps, type ProvenanceDetailTitleAs, type ProvenanceTriggerBadge, type ProvenanceBadgeProps, type ProvenanceBadgeAppearance, type ConfidenceMeterProps, } from "./components/provenance";
 export { createSimStore, resetSimStores, useSimSettings, setSimSettings, getNetworkSpeed, getDataSource, simulateLatency, SimNetworkError, type SimStore, type SimStoreOptions, type SimSettings, type NetworkSpeed, type DataSource, type SimNamespace, } from "./lib/sim";
 export { NodeCanvas, LAYOUT_DEFAULTS, layoutTree, pathToNode, type NodeCanvasProps, type CanvasEdge, type CanvasLayout, type CanvasNode, type CanvasOrientation, type LayoutOptions, type NodeRenderContext, type NodeRenderer, type PlacedNode, } from "./components/node-canvas";
 export { defineRecordType, resetRecordTypes, useRecord, useRecords, useStaleness, write, writeAll, peekRecord, readState, readStaleness, subscribeToKey, subscribeToStaleness, retainKeys, sweepRecords, setRecordStoreTenant, getRecordStoreTenant, flushRecordNotifications, resetRecordStore, recordStoreStats, UNKNOWN_STATE, normalizeTypeName, normalizeTimestamp, recordKey, isRecordRef, type RecordRef, type ReadOptions, type RecordPayload, type RecordState, type RecordTypeOptions, type RecordTypeToken, type StalenessEntry, type WriteAllResult, type WriteOptions, type WriteResult, type WriteSource, type WriteVerdict, } from "./lib/records";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "3.13.0",
+  "version": "4.0.0",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",