@cjlapao/ui-kit-vue 0.2.0 → 0.2.3

package/dist/types/common/gantt/types.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Gantt — framework-agnostic data model.
+ *
+ * The shape mirrors the best-in-class libraries (dhtmlxGantt, Bryntum Gantt,
+ * Syncfusion Gantt): a flat `tasks[]` with an optional `parent` id forming the
+ * hierarchy, a `links[]` array for dependencies, and optional `lanes[]`
+ * (swimlanes) that group rows. All dates travel as ISO-8601 strings; the
+ * engine normalises them to epoch-ms internally.
+ */
+import type { TrueColor } from "../theme/Theme";
+import type { GanttPt } from "./drag";
+export type { TrueColor };
+/** A date accepted anywhere the model takes one: ISO string or Date. */
+export type GanttDate = string | Date | number;
+/**
+ * Task kinds.
+ * - `task` — a regular duration bar.
+ * - `project` — a group header task; its bar spans its children and its
+ *   progress is the roll-up of its descendants.
+ * - `milestone` — zero-duration, rendered as a diamond.
+ */
+export type GanttTaskType = "task" | "project" | "milestone";
+/** Dependency types (standard project-management relations). */
+export type GanttLinkType = "fs" | "ff" | "sf" | "ss";
+export interface GanttTask {
+    id: string;
+    name: string;
+    /** Task start (ISO date / datetime, or Date, or epoch ms). */
+    start: GanttDate;
+    /** Task end — exclusive-style is fine; a milestone may equal `start`. */
+    end: GanttDate;
+    /** Completion, 0..1. Omitted = 0. */
+    progress?: number;
+    /** Defaults to `task`. */
+    type?: GanttTaskType;
+    /** Parent task id for hierarchy. Omitted/null = top level. */
+    parent?: string | null;
+    /** Swimlane / group id — see `GanttLane`. Omitted = default lane. */
+    lane?: string | null;
+    /** Bar colour. Defaults to the Gantt's `color` prop. */
+    color?: TrueColor;
+    /** Row collapsed/expanded (children hidden). Defaults to expanded. */
+    open?: boolean;
+    /** Optional owner label (rendered in a column when provided). */
+    owner?: string;
+    /** Optional short badge text (rendered in a column when provided). */
+    badge?: string;
+    /** Badge tone. */
+    badgeColor?: TrueColor;
+    /** Extra cell values for user-defined columns (`columns[].key`). */
+    values?: Record<string, string | number | boolean | null | undefined>;
+    /** Disable drag/resize/link for this task. */
+    locked?: boolean;
+    /** Extra data carried through events untouched. */
+    [key: string]: unknown;
+}
+export interface GanttLink {
+    id?: string;
+    /** Task id the dependency points from. */
+    source: string;
+    /** Task id the dependency points to. */
+    target: string;
+    /** Defaults to `fs` (finish-to-start). */
+    type?: GanttLinkType;
+    /** Arrow colour. Defaults to the Gantt's `color` prop. */
+    color?: TrueColor;
+    [key: string]: unknown;
+}
+/** A swimlane (lane / group band) the tasks can be assigned to via `task.lane`. */
+export interface GanttLane {
+    id: string;
+    label: string;
+    /** Lane band colour. Defaults to `neutral`. */
+    color?: TrueColor;
+    /** Optional second line under the label. */
+    description?: string;
+    /** Lane collapsed (rows hidden). Defaults to expanded. */
+    open?: boolean;
+}
+/**
+ * A left-panel table column. `key` resolves against
+ * `task.name` / `task.owner` / `task.badge` / `task.values[key]`.
+ */
+export interface GanttColumn {
+    key: string;
+    title: string;
+    /** Column header tone. Defaults to `neutral`. */
+    tone?: TrueColor;
+    /** CSS width, e.g. `"180px"`. Defaults to `"160px"`. */
+    width?: string;
+    /** Cell content alignment. */
+    align?: "left" | "center" | "right";
+    /**
+     * Custom cell renderer key: `"text"` | `"progress"` | `"owner"` |
+     * `"badge"`. Defaults to `"text"`.
+     */
+    kind?: "text" | "progress" | "owner" | "badge";
+    /**
+     * When false, this column cannot be resized even when `resizableColumns`
+     * is set on the Gantt. Defaults to true.
+     */
+    resizable?: boolean;
+}
+/** Snap targets for drag operations. */
+export type GanttSnap = "none" | "hour" | "day" | "week";
+/**
+ * Zoom, expressed as pixels per day. Presets (see `GANTT_ZOOM_PRESETS`):
+ * `day` = 48, `week` = 16, `month` = 5, `quarter` = 1.6. Continuous values in
+ * between are valid — the time scale re-derives its header levels for any.
+ */
+export type GanttZoom = number;
+export interface GANTT_ZOOM_PRESET {
+    label: string;
+    /** px per day */
+    value: number;
+}
+/** Discrete zoom presets for the toolbar. */
+export declare const GANTT_ZOOM_PRESETS: GANTT_ZOOM_PRESET[];
+/** Inclusive zoom bounds applied to wheel/button zoom. */
+export declare const GANTT_MIN_ZOOM = 0.4;
+export declare const GANTT_MAX_ZOOM = 96;
+/** Time scale header column. */
+export interface GanttTimeColumn {
+    id: string;
+    /** e.g. "Jan 2026", "Q1", "12", "W03" */
+    label: string;
+    /** e.g. "Jan", "2026", "Mon" — sub-label for two-line headers. */
+    subLabel?: string;
+    /** Epoch ms of column start (exclusive of anything before). */
+    start: number;
+    /** Epoch ms of column end (exclusive). */
+    end: number;
+    /** Rendered width in px. */
+    width: number;
+}
+/** A resolved time scale level (one row of headers). */
+export interface GanttTimeScaleLevel {
+    /** Stable level id: "year" | "quarter" | "month" | "week" | "day" */
+    id: string;
+    columns: GanttTimeColumn[];
+}
+/** A flattened, renderable row in the row model. */
+export interface GanttRow {
+    key: string;
+    /** Task rows reference the task; group rows reference their lane. */
+    task?: GanttTask;
+    lane?: GanttLane;
+    isGroup: boolean;
+    /** Hierarchy depth (0 = top level). */
+    depth: number;
+    /** Number of descendant rows (for group indentation spans). */
+    childCount: number;
+    /** Row height in px (groups can be shorter). */
+    height: number;
+    /** Top offset from the top of the row area (excl. header), px. */
+    top: number;
+    /** Cumulative roll-up progress for group/project rows (0..1). */
+    progress?: number;
+}
+/** Geometry needed to draw dependency arrows. */
+export interface GanttBarGeometry {
+    taskId: string;
+    /** Left offset of the bar within the timeline, px. */
+    left: number;
+    /** Bar width, px (0 for milestones — drawn at `left`). */
+    width: number;
+    /** Row top, px (relative to the row area). */
+    top: number;
+    /** Row height, px. */
+    height: number;
+    /** Milestones are diamonds centred on their date. */
+    milestone: boolean;
+}
+/** A point in the link layer's coordinate space (origin = timeline origin). */
+export interface GanttLinkPoint {
+    x: number;
+    y: number;
+}
+/** A resolved dependency arrow path in timeline pixel space. */
+export interface GanttLinkPath {
+    link: GanttLink;
+    /** SVG path `d` in the link layer's coordinate space (origin = timeline origin). */
+    d: string;
+    /**
+     * The route polyline (pre-corner-rounding) the same `d` is derived from —
+     * in the link layer's coordinate space. Kept on the path so hit-testing
+     * (`pickLinkAt`) can measure pointer distance without parsing path data.
+     */
+    points: GanttPt[];
+    /**
+     * Arrowhead polygon points (SVG `<polygon points>`), or undefined when the
+     * approach is too short for a head. Computed in the engine so the
+     * framework layer never has to parse paths.
+     */
+    arrow?: string;
+    /** Source port — the point on the source bar's edge the connector leaves. */
+    from: GanttLinkPoint;
+    /** Target port — the point on the target bar's edge the arrowhead lands on. */
+    to: GanttLinkPoint;
+    color?: TrueColor;
+    type: GanttLinkType;
+}
+/** Label overrides for every string the Gantt renders. */
+export interface GanttLabels {
+    loading: string;
+    empty: string;
+    today: string;
+    select: string;
+    move: string;
+    resize: string;
+    link: string;
+    progress: string;
+    duration: string;
+    task: string;
+}
+export declare const DEFAULT_GANTT_LABELS: GanttLabels;

package/dist/types/common/i18n/builtIn/de.d.ts

@@ -0,0 +1,2 @@
+import type { MessageCatalog } from "../types";
+export declare const DE_KIT_CATALOG: MessageCatalog;

package/dist/types/common/i18n/builtIn/en.d.ts

@@ -0,0 +1,2 @@
+import type { MessageCatalog } from "../types";
+export declare const EN_KIT_CATALOG: MessageCatalog;

package/dist/types/common/i18n/builtIn/es.d.ts

@@ -0,0 +1,2 @@
+import type { MessageCatalog } from "../types";
+export declare const ES_KIT_CATALOG: MessageCatalog;

package/dist/types/common/i18n/builtIn/fr.d.ts

@@ -0,0 +1,2 @@
+import type { MessageCatalog } from "../types";
+export declare const FR_KIT_CATALOG: MessageCatalog;

package/dist/types/common/i18n/builtIn/index.d.ts

@@ -0,0 +1,15 @@
+import type { LocaleTag, MessageCatalog } from "../types";
+export { DE_KIT_CATALOG } from "./de";
+export { EN_KIT_CATALOG } from "./en";
+export { ES_KIT_CATALOG } from "./es";
+export { FR_KIT_CATALOG } from "./fr";
+export { PT_KIT_CATALOG } from "./pt";
+/**
+ * Built-in kit catalogs (spec §4.3). `en` is the reference — its values are
+ * the components' current hardcoded literals (no-provider rendering is
+ * byte-identical to pre-i18n). `fr/es/de/pt` are curated initial translations
+ * (spec §15), overridable per key.
+ */
+export declare const BUILT_IN_CATALOGS: Record<LocaleTag, MessageCatalog>;
+/** Locales the kit ships curated kit strings for (the CLI's scaffold set). */
+export declare const CURATED_LOCALES: LocaleTag[];

package/dist/types/common/i18n/builtIn/pt.d.ts

@@ -0,0 +1,2 @@
+import type { MessageCatalog } from "../types";
+export declare const PT_KIT_CATALOG: MessageCatalog;

package/dist/types/common/i18n/catalog.d.ts

@@ -0,0 +1,32 @@
+import type { LocaleTag, MessageCatalog } from "./types";
+/**
+ * Flatten a nested catalog to dot-keys (spec §4.1).
+ *
+ * `a.b.c` → string; arrays keep their index (`kit.date.months.0`); non-string
+ * leaves are skipped with a deduped warn. Flattening happens once at provider
+ * setup — `lookup` never walks raw catalogs.
+ */
+export declare function flattenCatalog(catalog: MessageCatalog, warnPrefix?: string): Record<string, string>;
+export interface LookupResult {
+    value: string;
+    /** The locale the value was found in. */
+    resolvedLocale: LocaleTag;
+}
+/**
+ * Key-resolution structure (spec §4.2):
+ *
+ *   user[L] → kit[L] → kit[fallback]
+ *
+ * Built once; `lookup` is a plain map walk over that chain (no per-call
+ * catalog walking). Note: `user[fallback]` is NOT consulted for a different
+ * active locale — user catalogs are per-locale (deliberate v1 simplification).
+ */
+export interface Resolution {
+    lookup(key: string, locale: LocaleTag): LookupResult | undefined;
+    has(key: string, locale: LocaleTag): boolean;
+    /** Union of user + built-in tags, sorted. */
+    availableLocales(): LocaleTag[];
+    /** Merged `user[L]` over `kit[L]` (used for `kit.date.*` overrides). */
+    catalogFor(locale: LocaleTag): Record<string, string>;
+}
+export declare function buildResolution(userLocales: Record<LocaleTag, MessageCatalog>, builtIn: Record<LocaleTag, MessageCatalog>, fallback: LocaleTag): Resolution;

package/dist/types/common/i18n/createI18n.d.ts

@@ -0,0 +1,2 @@
+import type { I18nConfig, I18nEngine } from "./types";
+export declare function createI18n(config: I18nConfig): I18nEngine;

package/dist/types/common/i18n/dates.d.ts

@@ -0,0 +1,12 @@
+import type { LocaleTag } from "./types";
+/** Localized month names (Jan…Dec order). Catalog override, Intl, English. */
+export declare function getMonthNames(locale: LocaleTag, short?: boolean, catalog?: Record<string, string>): string[];
+/** Localized weekday names (Sunday-first, getDay() numbering). */
+export declare function getWeekdayNames(locale: LocaleTag, short?: boolean, catalog?: Record<string, string>): string[];
+/** All four name sets for locale-aware date parsing (Task 2.4 consumes this). */
+export declare function getLocalizedParseNames(locale: LocaleTag, catalog?: Record<string, string>): {
+    monthFull: string[];
+    monthShort: string[];
+    weekdayFull: string[];
+    weekdayShort: string[];
+};

package/dist/types/common/i18n/detect.d.ts

@@ -0,0 +1,29 @@
+import type { LocaleTag } from "./types";
+/** BCP-47 base language (`"fr-CA"` → `"fr"`), lowercased. */
+export declare function baseLanguage(tag: LocaleTag): string;
+/**
+ * Locale prefixes the kit treats as right-to-left (spec §6). A small static
+ * list keeps the engine dependency-free; extend as needed.
+ */
+export declare const RTL_PREFIXES: readonly LocaleTag[];
+export declare function isRTLLocale(tag: LocaleTag): boolean;
+/**
+ * The first candidate that has a catalog — exact tag, then base language
+ * (`matchTag(["fr-CA"], {"fr"})` → `"fr"`). `undefined` when none matches.
+ */
+export declare function matchTag(candidates: readonly LocaleTag[], available: ReadonlySet<LocaleTag>): LocaleTag | undefined;
+export interface InitialLocaleInput {
+    /** Explicit `locale` config — skips detection + persistence. */
+    explicit?: LocaleTag;
+    detect: boolean;
+    /** Stored tag (or `null`). */
+    stored: LocaleTag | null;
+    languages: readonly LocaleTag[];
+    available: ReadonlySet<LocaleTag>;
+    fallback: LocaleTag;
+}
+/**
+ * Detection order (spec §7): explicit → stored → `navigator.languages` →
+ * fallback. Invalid values fall through the chain — this never fails.
+ */
+export declare function resolveInitialLocale(input: InitialLocaleInput): LocaleTag;

package/dist/types/common/i18n/icu.d.ts

@@ -0,0 +1,36 @@
+export type IcuStyle = "number" | "date" | "time";
+export type IcuNode = {
+    type: "text";
+    value: string;
+} | {
+    type: "arg";
+    name: string;
+    style?: IcuStyle;
+    options?: Record<string, string>;
+} | {
+    type: "plural";
+    name: string;
+    offset: number;
+    branches: Map<string, IcuNode[]>;
+} | {
+    type: "select";
+    name: string;
+    branches: Map<string, IcuNode[]>;
+};
+/** Parse-time error (bad ICU source): carries key + position. */
+export declare class IcuParseError extends Error {
+    readonly key: string;
+    readonly source: string;
+    readonly position: number;
+    constructor(key: string, source: string, position: number, reason: string);
+}
+/** Runtime error: a message expects a value the caller did not provide. */
+export declare class IcuValueError extends Error {
+    readonly key: string;
+    readonly arg: string;
+    constructor(key: string, arg: string, detail: string);
+}
+/** Parse one ICU message into its AST. Throws `IcuParseError` on bad source. */
+export declare function parseMessage(source: string, key: string): IcuNode[];
+/** Resolve an AST against values. `dev` selects throw vs degrade. */
+export declare function resolveNodes(nodes: IcuNode[], values: Record<string, unknown>, locale: string, dev: boolean, key: string): string;

package/dist/types/common/i18n/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./types";
+export * from "./warn";
+export * from "./storage";
+export * from "./catalog";
+export * from "./icu";
+export * from "./detect";
+export * from "./dates";
+export * from "./builtIn";
+export * from "./createI18n";
+export * from "./provider";

package/dist/types/common/i18n/provider.d.ts

@@ -0,0 +1,7 @@
+import type { I18nConfig, I18nEngine } from "./types";
+/**
+ * Wrap an engine with the side effects a provider owns. Returns a new
+ * `I18nEngine` whose `setLocale` also persists (when `storageKey` allows)
+ * and updates `<html lang/dir>` (when `updateDocument !== false`).
+ */
+export declare function wrapEngineWithSideEffects(engine: I18nEngine, config: I18nConfig): I18nEngine;

package/dist/types/common/i18n/storage.d.ts

@@ -0,0 +1,8 @@
+import type { I18nConfig, LocaleTag } from "./types";
+export declare const DEFAULT_STORAGE_KEY = "ui-kit:locale";
+/** The effective storage key (`null` = persistence disabled). */
+export declare function storageKeyOf(config: Pick<I18nConfig, "storageKey">): string | null;
+/** The persisted locale choice, or `null` (SSR-safe). */
+export declare function readStoredLocale(config: Pick<I18nConfig, "storageKey">): LocaleTag | null;
+/** Persist the active locale (no-op when disabled or unavailable). */
+export declare function persistLocale(config: Pick<I18nConfig, "storageKey">, locale: LocaleTag): void;

package/dist/types/common/i18n/types.d.ts

@@ -0,0 +1,64 @@
+import type { DateParseNames } from "../utils/dates";
+/** BCP-47 language tag: `"en"`, `"fr"`, `"fr-CA"`. */
+export type LocaleTag = string;
+/**
+ * A catalog: message map. Values are usually message strings, but nested
+ * objects are allowed (flattened to dot-keys) as are string arrays (used by
+ * the `kit.date.*` name overrides). Non-string leaves are skipped with a
+ * dev warning.
+ */
+export type MessageCatalog = Record<string, unknown>;
+/** Object form of `t` — the future extraction phase's entry point. */
+export interface I18nMessage {
+    id: string;
+    /** Used when `id` is missing everywhere (resolved as an ICU message). */
+    defaultMessage?: string;
+    values?: Record<string, unknown>;
+}
+export interface I18nConfig {
+    /** User catalogs, keyed by locale tag. */
+    locales: Record<LocaleTag, MessageCatalog>;
+    /** Key-resolution fallback locale. @default "en" */
+    fallbackLocale?: LocaleTag;
+    /** Explicit active locale — skips detection and persistence reads. */
+    locale?: LocaleTag;
+    /** Detect from `navigator.languages`. @default true (no-op in SSR). */
+    detect?: boolean;
+    /**
+     * localStorage key for the persisted choice; `null` = never persist (and
+     * never read). @default "ui-kit:locale"
+     */
+    storageKey?: string | null;
+    /** Set `document.documentElement.lang`/`dir` at init and on change. @default true */
+    updateDocument?: boolean;
+    /** Called when a key resolves via fallback or `defaultMessage`. */
+    onFallbackKey?(key: string, requested: LocaleTag, resolved: LocaleTag): void;
+}
+export interface I18nEngine {
+    /** Translate `key` with ICU values. Missing → en fallback → the key. */
+    t(key: string, values?: Record<string, unknown>): string;
+    t(msg: I18nMessage): string;
+    /** Active locale tag. */
+    locale: LocaleTag;
+    /** All available tags (user ∪ built-in), sorted. */
+    locales: LocaleTag[];
+    has(key: string, locale?: LocaleTag): boolean;
+    /** Exact or base-language match; otherwise warn + no-op. */
+    setLocale(tag: LocaleTag): void;
+    formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
+    formatDate(value: Date, options?: Intl.DateTimeFormatOptions): string;
+    monthNames(locale?: LocaleTag, short?: boolean): string[];
+    weekdayNames(locale?: LocaleTag, short?: boolean): string[];
+    /**
+     * Localized month/weekday names for locale-aware DATE PARSING (spec §6) —
+     * feeds `parseDateText`/`parseValueText`'s `names` param. Catalog overrides
+     * included (same chain as `monthNames`).
+     */
+    parseNames(locale?: LocaleTag): DateParseNames;
+    /** Whether the active locale is right-to-left. */
+    isRTL: boolean;
+    /** Subscribe to locale changes; returns the unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** Bumped on every locale change (useSyncExternalStore-friendly). */
+    getVersion(): number;
+}

package/dist/types/common/i18n/warn.d.ts

@@ -0,0 +1,5 @@
+export declare function isDev(): boolean;
+/** Warn at most once per `id`, in dev and prod alike. */
+export declare function devWarnOnce(id: string, message: string): void;
+/** Test helper: clear the dedupe set between tests. */
+export declare function resetWarned(): void;