@adminiumjs/widgets 0.1.0-rc.1

package/dist/families/domain/domain-lib.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Shared PURE helpers for the `domain` family (annex §13) — a deterministic
+ * seeded PRNG, tone coercion, the cycle-safe self-FK → tree adapter + tidy-tree
+ * layout behind `org-chart`, and the time-axis geometry behind `gantt-chart`.
+ *
+ * DOM-free and React-free on purpose: every layout decision is a pure function
+ * of its inputs, so the geometry is golden-testable (04-T17 determinism gate)
+ * and the definitions module can import the demo generators without dragging
+ * component code into the eager registry chunk (04 §2.3).
+ *
+ * DIRECTION POLICY (10-i18n-theming.md §5.5) — the two widgets sit on OPPOSITE
+ * sides of the mirroring rule, and this module keeps both honest by emitting
+ * LTR-canonical geometry in both cases:
+ *
+ *   - `org-chart` is a hierarchy, not a time axis → it MIRRORS. The layout below
+ *     is canonical-LTR and the component maps it onto `inset-inline-start`, so
+ *     the browser mirrors the tree under `dir="rtl"` (the same logical-CSS
+ *     mechanism the `calendar` family relies on for its month grid).
+ *   - `gantt-chart` is a time axis → it does NOT mirror. Per §5.5 the timeline
+ *     canvas is a **fixed-LTR island** ("time flows left→right … the label
+ *     column stays physically left of the canvas so labels align with the time
+ *     origin"); only the surrounding chrome mirrors. `@adminium/charts` already
+ *     encodes this for `chart-timeline-lanes` (geometry/timelineLanes.ts: "The
+ *     time axis is an LTR island … so event x-positions are LTR here").
+ */
+import type { Tone } from '@adminium/ui';
+import type { GanttGroup, GanttModel, OrgNode } from './domain-types.js';
+/** Mulberry32 — the repo's deterministic seeded PRNG (see boards/calendar/feeds). */
+export declare function mulberry32(seed: number): () => number;
+/** Deterministic pick from a non-empty tuple. */
+export declare function pickFrom<T>(random: () => number, items: readonly T[]): T;
+/**
+ * Fixed demo anchor — 2026-07-01T00:00:00Z. `demoData(seed)` derives every date
+ * from this constant so payloads are byte-identical across runs and never read
+ * the wall clock (04 §7.7 / determinism gate).
+ */
+export declare const DOMAIN_DEMO_EPOCH: number;
+/** Milliseconds in a whole day — the gantt axis unit. */
+export declare const DAY_MS = 86400000;
+/** Coerce an untrusted tone string to a valid `Tone`, defaulting as given. */
+export declare function toneOf(value: unknown, fallback?: Tone): Tone;
+/** Stable FNV-1a-ish hash of a string → index into a palette. */
+export declare function hashIndex(value: string, modulo: number): number;
+/**
+ * Tone for a category (department / phase), honoring an explicit map, else a
+ * stable hashed cycle — the same category always draws the same color.
+ */
+export declare function categoryTone(category: string | undefined, map?: Record<string, string> | undefined): Tone;
+/** Tone → solid background (bars, dots, connectors). */
+export declare const TONE_SOLID_BG: Record<Tone, string>;
+/** Tone → soft tint + tone text (dept chips, group summary bars). */
+export declare const TONE_SOFT: Record<Tone, string>;
+/** Tone → border color only (node card top rule / tinted report cards). */
+export declare const TONE_BORDER: Record<Tone, string>;
+type Rec = Record<string, unknown>;
+export declare function asRecord(value: unknown): Rec | null;
+/** Read a field as a trimmed string; undefined when absent/blank. */
+export declare function stringField(row: Rec, field: string): string | undefined;
+/** Read a field as a finite number; undefined when unparseable. */
+export declare function numberField(row: Rec, field: string): number | undefined;
+/**
+ * Coalesce an empty/whitespace locale to `en-US` — a schema-valid
+ * `format.locale: ''` otherwise reaches `Avatar`'s `toLocaleUpperCase('')`,
+ * which throws `RangeError` (see calendar-lib.ts for the same guard).
+ */
+export declare function resolveLocale(locale: string | undefined): string;
+/** Field names that map a flat self-FK people row onto an `OrgNode`. */
+export interface OrgFieldMap {
+    idField: string;
+    parentField: string;
+    labelField: string;
+    roleField?: string | undefined;
+    deptField?: string | undefined;
+    avatarField?: string | undefined;
+    toneField?: string | undefined;
+}
+/**
+ * Adapt a FLAT self-referencing people `record-list` (`manager_id → id`) into
+ * the canonical `hierarchy/tree` roots.
+ *
+ * CYCLE SAFETY (a hard requirement — a corrupt `manager_id` cycle must never
+ * hang the render): the walk is structurally incapable of looping.
+ *   1. Self-edges (`manager_id === id`) are dropped up front.
+ *   2. Edges to a non-existent manager are dropped — that row becomes a root.
+ *   3. Roots are the rows left with no surviving parent edge; each is expanded
+ *      by a DFS that marks nodes `visited` BEFORE recursing, so a back-edge into
+ *      an already-visited node is skipped rather than followed.
+ *   4. Any row still unvisited after the root pass is, by construction, inside a
+ *      cycle (or hanging off one). Those are promoted to roots in stable input
+ *      order and expanded by the same guarded DFS.
+ * Every row therefore renders EXACTLY once, and termination is guaranteed
+ * because each DFS step consumes an unvisited node from a finite set.
+ */
+export declare function buildOrgTree(rows: readonly Rec[], fields: OrgFieldMap): {
+    roots: OrgNode[];
+    total: number;
+};
+/**
+ * Read an `org-chart` payload into tree roots, accepting BOTH shapes the widget
+ * declares: the canonical `hierarchy/tree` envelope (`{ roots }`) and the flat
+ * self-FK `record-list` (`{ rows }`) a real people table returns.
+ */
+export declare function orgRootsOf(data: unknown, fields: OrgFieldMap): {
+    roots: OrgNode[];
+    total: number;
+};
+/** Total node count across a forest. */
+export declare function countNodes(roots: readonly OrgNode[]): number;
+export interface OrgLayoutOptions {
+    /** Node card width in px. */
+    nodeWidth?: number;
+    /** Node card height in px. */
+    nodeHeight?: number;
+    /** Horizontal gap between sibling subtrees, px. */
+    hGap?: number;
+    /** Vertical gap between depth bands, px. */
+    vGap?: number;
+    /** Depth beyond which nodes are pruned (root = depth 0). */
+    maxDepth?: number;
+    /** Ids whose subtree is collapsed (children laid out as if absent). */
+    collapsed?: ReadonlySet<string>;
+}
+export interface OrgLayoutNode {
+    node: OrgNode;
+    id: string;
+    depth: number;
+    /** Top-inline-start corner of the card, in canonical-LTR px. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Has children in the DATA (may be hidden by collapse/maxDepth). */
+    hasChildren: boolean;
+    /** Direct-report count — the "N reports" footer. */
+    childCount: number;
+    /** Subtree hidden because this node is collapsed or at `maxDepth`. */
+    collapsed: boolean;
+    /**
+     * Subtree hidden by the `maxDepth` cap rather than by the user. Such a node
+     * can NEVER expand — toggling its collapsed state is a no-op — so the caller
+     * must not offer an expand affordance or advertise `aria-expanded` on it.
+     */
+    pruned: boolean;
+}
+export interface OrgConnector {
+    parentId: string;
+    childId: string;
+    /** SVG elbow path in canonical-LTR coordinates. */
+    d: string;
+}
+export interface OrgLayout {
+    nodes: OrgLayoutNode[];
+    connectors: OrgConnector[];
+    /** Canvas extents in px. */
+    width: number;
+    height: number;
+}
+/**
+ * Deterministic tidy-tree layout — a classic two-pass layered algorithm, no
+ * external lib:
+ *   pass 1 (post-order): leaves consume successive x slots; an internal node is
+ *           centered over the span of its laid-out children.
+ *   pass 2: y = depth · (nodeHeight + vGap) — a strict layered band per depth.
+ * Multiple roots lay out left-to-right in input order, so a forest (several CEOs
+ * / an orphan set / a broken cycle promoted to roots) renders side by side.
+ *
+ * Output is CANONICAL-LTR (see the direction policy at the top of this file);
+ * the component maps `x` onto `inset-inline-start` and lets the browser mirror
+ * the whole tree under `dir="rtl"`.
+ *
+ * Pure: same input → byte-identical output, no clock, no RNG, no DOM.
+ */
+export declare function layoutOrgTree(roots: readonly OrgNode[], options?: OrgLayoutOptions): OrgLayout;
+/** Field names mapping a task `record-list` row onto the gantt model. */
+export interface GanttFieldMap {
+    idField: string;
+    labelField: string;
+    startField: string;
+    endField: string;
+    progressField?: string | undefined;
+    phaseField?: string | undefined;
+    ownerField?: string | undefined;
+    milestoneField?: string | undefined;
+}
+/** Parse an ISO date/datetime (or epoch ms) to an epoch-ms instant. */
+export declare function parseDateMs(value: unknown): number | undefined;
+/** Whole days between two epoch-ms instants (floor toward the origin). */
+export declare function dayOffset(ms: number, originMs: number): number;
+export interface GanttModelOptions {
+    /** Force the axis length; else derived from the data span. */
+    totalDays?: number | undefined;
+    /** Epoch ms for the today marker; omit to hide it. */
+    todayMs?: number | undefined;
+    /** Explicit phase → tone map (annex `phaseColors`). */
+    phaseColors?: Record<string, string> | undefined;
+    /** Fallback group name for rows with no phase FK. */
+    ungroupedLabel?: string | undefined;
+}
+/**
+ * Project a task `record-list` onto the gantt model: parse start/end, derive the
+ * axis origin + span, bucket rows under their phase FK (input order preserved
+ * within a group, groups in first-seen order — deterministic), and locate the
+ * today marker.
+ *
+ * Rows with an unparseable/absent start are DROPPED (a bar with no position is
+ * meaningless); an absent/earlier end yields a 1-day bar. A row whose duration
+ * rounds to 0 days — or that sets the milestone field — becomes a diamond.
+ *
+ * Positions are canonical-LTR day offsets: day 0 is the oldest instant and the
+ * axis grows toward `totalDays`. This does NOT flip under RTL — per
+ * 10-i18n-theming.md §5.5 the gantt canvas is a fixed-LTR island.
+ */
+export declare function toGanttModel(rows: readonly Rec[], fields: GanttFieldMap, options?: GanttModelOptions): GanttModel;
+export declare function clamp(value: number, min: number, max: number): number;
+/** A group's summary span — earliest start → latest end across its tasks. */
+export declare function groupSpan(group: GanttGroup): {
+    startDay: number;
+    durDays: number;
+};
+/** Percent of the axis a day offset sits at — the CSS positioning unit. */
+export declare function dayToPercent(day: number, totalDays: number): number;
+/** Percent width for a span of `days`, clamped so a bar never overflows. */
+export declare function daysToPercent(startDay: number, days: number, totalDays: number): number;
+/** Week-bucket origins across the axis — the date-header tick instants. */
+export declare function weekTicks(originMs: number, totalDays: number): number[];
+export {};
+//# sourceMappingURL=domain-lib.d.ts.map

package/dist/families/domain/domain-lib.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-lib.d.ts","sourceRoot":"","sources":["../../../src/families/domain/domain-lib.ts"],"names":[],"mappings":"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"}