origam 2.2.1 → 2.5.0

package/dist/src/interfaces/Bracket/bracket-match.interface.d.ts

@@ -0,0 +1,51 @@
+import type { TBracketMatchStatus } from '../../types';
+import type { IBracketCompetitor } from './bracket-competitor.interface';
+/**
+ * A single match between two competitors.
+ *
+ * `competitorA` / `competitorB` are nullable so the bracket can render
+ * "TBD" placeholders for matches whose participants are not yet
+ * determined (e.g. winner of an earlier round).
+ *
+ * `scoreA` / `scoreB` accept `string` to allow non-numeric markers
+ * (`'—'`, `'DSQ'`, `'W/O'`, …) without forcing the consumer to coerce.
+ *
+ * `nextMatchId` lets `OrigamBracket` draw a connector from this match
+ * to the next round automatically. If `undefined`, the layout falls
+ * back to positional mapping (match `i` of round `n` connects to match
+ * `floor(i / 2)` of round `n + 1`).
+ */
+export interface IBracketMatch {
+    /** Stable identifier — required for connector linking. */
+    id: string | number;
+    /** Left-side / top-side competitor. `null` = TBD or bye. */
+    competitorA: IBracketCompetitor | null;
+    /** Right-side / bottom-side competitor. `null` = TBD or bye. */
+    competitorB: IBracketCompetitor | null;
+    /** Score of `competitorA`. Accepts `string` for non-numeric markers. */
+    scoreA?: number | string;
+    /** Score of `competitorB`. Accepts `string` for non-numeric markers. */
+    scoreB?: number | string;
+    /**
+     * Identifier of the declared winner. Falls back to `null` /
+     * `undefined` when the match is not yet completed. Used by the
+     * component to apply the `--winner` modifier class on the
+     * relevant competitor row.
+     */
+    winnerId?: string | number | null;
+    /**
+     * Optional lifecycle marker. Drives the visual `--status-{value}`
+     * modifier on the match card (e.g. live pulse, completed grey out).
+     */
+    status?: TBracketMatchStatus;
+    /**
+     * Optional id of the downstream match this one feeds into. Used
+     * by the connector layout to draw a path. If omitted, positional
+     * mapping is used.
+     */
+    nextMatchId?: string | number;
+    /** ISO date string — informative only, displayed when present. */
+    scheduledAt?: string;
+    /** Free-form payload — never read by the component. */
+    metadata?: Record<string, unknown>;
+}

package/dist/src/interfaces/Bracket/bracket-round-component.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Bracket/bracket-round-component.interface.d.ts

@@ -0,0 +1,26 @@
+import type { ICommonsComponentProps, IDirectionProps, ITagProps } from '../../interfaces';
+import type { TIntent } from '../../types';
+import type { IBracketRound } from './bracket-round.interface';
+/**
+ * Props for `<OrigamBracketRound>` — a single round (column in
+ * horizontal mode, row in vertical mode). Exported so consumers can
+ * render a round standalone (e.g. inside a custom layout).
+ */
+export interface IBracketRoundProps extends ICommonsComponentProps, ITagProps, IDirectionProps {
+    /** The round payload to render. */
+    round: IBracketRound;
+    /** Index of the round inside its bracket — drives the vertical offset. */
+    index: number;
+    /** Total number of rounds — used to flag the last round as final. */
+    totalRounds: number;
+    /** Toggle the round title heading. */
+    showRoundTitle?: boolean;
+    /** Forward to children — toggles score column. */
+    showScores?: boolean;
+    /** Forward to children — toggles seed prefix. */
+    showSeed?: boolean;
+    /** Forward to children — toggles match-card interactivity. */
+    interactive?: boolean;
+    /** Forward intent color. */
+    color?: TIntent;
+}

package/dist/src/interfaces/Bracket/bracket-round.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Bracket/bracket-round.interface.d.ts

@@ -0,0 +1,27 @@
+import type { TBracketRoundSide } from '../../types';
+import type { IBracketMatch } from './bracket-match.interface';
+/**
+ * A round (column in horizontal mode, row in vertical mode) of the
+ * tournament tree.
+ *
+ * Title is required — `OrigamBracket` renders it above (or beside) the
+ * matches list when `showRoundTitles` is enabled. Consumers should
+ * pre-translate the label (the component does not call `useT`).
+ *
+ * `side` is only meaningful for double-elimination — single-elim
+ * tournaments leave it `undefined`.
+ */
+export interface IBracketRound {
+    /** Stable identifier — used as key and in slot scopes. */
+    id: string | number;
+    /** Pre-translated label ("Quarter-finals", "Semi-finals", "Final"). */
+    title: string;
+    /** Ordered list of matches that belong to this round. */
+    matches: IBracketMatch[];
+    /**
+     * Optional bracket-side marker for double-elimination layouts.
+     * Drives grouping into Winner Bracket / Loser Bracket / Grand
+     * Final sections.
+     */
+    side?: TBracketRoundSide;
+}

package/dist/src/interfaces/Bracket/bracket.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Bracket/bracket.interface.d.ts

@@ -0,0 +1,64 @@
+import type { IBgColorProps, IColorProps, ICommonsComponentProps, IDensityProps, IDimensionProps, IElevationProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps } from '../../interfaces';
+import type { TBracketVariant } from '../../types';
+import type { IBracketRound } from './bracket-round.interface';
+/**
+ * Props for `<OrigamBracket>` — a tournament tree renderer supporting
+ * single-elimination, double-elimination and round-robin layouts.
+ *
+ * The component is purely presentational: it accepts an immutable
+ * `rounds` payload and emits user-interaction events (`match-click`,
+ * `winner-click`, `competitor-click`) so the consumer can update the
+ * data and re-render. No internal state is held about scores or
+ * winners — the data passed in is the source of truth.
+ */
+export interface IBracketProps extends ICommonsComponentProps, ITagProps, IDensityProps, IRoundedProps, IColorProps, IBgColorProps, IDimensionProps, IElevationProps, IMarginProps, IPaddingProps {
+    /**
+     * Required. Pre-ordered list of rounds. For single-elimination,
+     * the rounds are laid out from earliest (e.g. round-of-16) to
+     * final. For double-elimination, segregate by `IBracketRound.side`
+     * (`'winner'`, `'loser'`, `'grand-final'`).
+     */
+    rounds: IBracketRound[];
+    /**
+     * Tournament shape. Single-elimination is the default.
+     * Round-robin renders a NxN matrix instead of a tree.
+     *
+     * @default 'single-elimination'
+     */
+    variant?: TBracketVariant;
+    /**
+     * Layout axis. Horizontal stacks rounds as columns (the classic
+     * tournament tree look). Vertical stacks rounds as rows — useful
+     * for narrow viewports. Ignored when `variant === 'round-robin'`
+     * (the matrix layout has its own grid axis).
+     *
+     * @default 'horizontal'
+     */
+    direction?: 'horizontal' | 'vertical';
+    /**
+     * Toggle round headers (`<h3>Quarter-finals</h3>`).
+     *
+     * @default true
+     */
+    showRoundTitles?: boolean;
+    /**
+     * Toggle the score column on each competitor row.
+     *
+     * @default true
+     */
+    showScores?: boolean;
+    /**
+     * Toggle the seed prefix on competitor names (e.g. `1. Team Liquid`).
+     *
+     * @default false
+     */
+    showSeed?: boolean;
+    /**
+     * Whether match cards should be interactive (cursor, hover state,
+     * keyboard focus). When `false`, click handlers still fire but the
+     * cards do not advertise affordance.
+     *
+     * @default true
+     */
+    interactive?: boolean;
+}

package/dist/src/interfaces/Breadcrumb/breadcrumb-item.interface.d.ts

@@ -1,5 +1,8 @@
-import type { IActiveProps, IAdjacentProps, IBorderProps, IBgColorProps, IColorProps, ICommonsComponentProps, IDensityProps, IHoverProps, ILinkProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps } from '../../interfaces';
+import type { IActiveProps, IAdjacentEmits, IAdjacentProps, IBorderProps, IBgColorProps, IColorProps, ICommonsComponentProps, IDensityProps, IHoverProps, ILinkProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps } from '../../interfaces';
 export interface IBreadcrumbItemProps extends ICommonsComponentProps, ITagProps, IBorderProps, IPaddingProps, IMarginProps, IRoundedProps, ILinkProps, IColorProps, IBgColorProps, IDensityProps, IAdjacentProps, IHoverProps, IActiveProps {
     title: string;
     disabled?: boolean;
 }
+/** Emits fired by `<OrigamBreadcrumbItem>` — clicks on prepend/append icons. */
+export interface IBreadcrumbItemEmits extends IAdjacentEmits {
+}

package/dist/src/interfaces/Btn/btn-toggle.interface.d.ts

@@ -1,3 +1,6 @@
-import type { IBtnGroupProps, IGroupProps } from '../../interfaces';
+import type { IBtnGroupProps, ICommonsComponentEmits, IGroupProps } from '../../interfaces';
 export interface IBtnToggleProps extends IBtnGroupProps, IGroupProps {
 }
+/** Emits fired by `<OrigamBtnToggle>` — v-model on the active toggle index. */
+export interface IBtnToggleEmits extends ICommonsComponentEmits {
+}

package/dist/src/interfaces/Btn/btn.interface.d.ts

@@ -1,4 +1,4 @@
-import type { IAdjacentProps, IBorderProps, IBgColorProps, IColorProps, ICommonsComponentProps, IDensityProps, IDimensionProps, IElevationProps, IGroupItemProps, IHoverProps, ILinkProps, ILoaderProps, ILocationProps, IMarginProps, IPaddingProps, IPositionProps, IRippleProps, IRoundedProps, ISizeProps, IStatusProps, ITagProps, IVariantProps } from '../../interfaces';
+import type { IAdjacentEmits, IAdjacentProps, IBorderProps, IBgColorProps, IColorProps, ICommonsComponentProps, IDensityProps, IDimensionProps, IElevationProps, IGroupEmits, IGroupItemProps, IHoverProps, ILinkProps, ILoaderProps, ILocationProps, IMarginProps, IPaddingProps, IPositionProps, IRippleProps, IRoundedProps, ISizeProps, IStatusProps, ITagProps, IVariantProps } from '../../interfaces';
 import type { TIcon } from '../../types';
 export interface IBtnProps extends ICommonsComponentProps, IColorProps, IBgColorProps, IBorderProps, IDensityProps, IDimensionProps, IElevationProps, IRoundedProps, ITagProps, ISizeProps, ILinkProps, IRippleProps, ILoaderProps, IPositionProps, ILocationProps, IGroupItemProps, IPaddingProps, IMarginProps, IAdjacentProps, IStatusProps, IHoverProps, IVariantProps {
     active?: boolean;
@@ -10,3 +10,7 @@ export interface IBtnProps extends ICommonsComponentProps, IColorProps, IBgColor
     stacked?: boolean;
     text?: string;
 }
+/** Emits fired by `<OrigamBtn>` — clicks on prepend/append slots and
+ *  group-membership lifecycle. */
+export interface IBtnEmits extends IAdjacentEmits, IGroupEmits {
+}

package/dist/src/interfaces/Calendar/calendar.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Calendar/calendar.interface.d.ts

@@ -0,0 +1,159 @@
+import type { ICommonsComponentProps, IEvent } from '../../interfaces';
+import type { TCalendarNavigate, TCalendarTimeFormat, TCalendarView, TIntent } from '../../types';
+/**
+ * Props for `<OrigamCalendar>`. Two-way bindings on `view` and
+ * `currentDate` so the parent can sync with router state or persist
+ * across page reloads without owning a watcher.
+ */
+export interface ICalendarProps extends ICommonsComponentProps {
+    /** Active view mode. v-model:view. */
+    view?: TCalendarView;
+    /** Anchor date. v-model:currentDate. */
+    currentDate?: Date | string;
+    /** Event list. Recurring events are expanded internally. */
+    events?: Array<IEvent>;
+    /**
+     * First weekday rendered as the leftmost column. `1` (Monday) for
+     * EU/ISO, `0` (Sunday) for US. Default `1`.
+     */
+    firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /** Clock format for time labels. Default `'24h'`. */
+    timeFormat?: TCalendarTimeFormat;
+    /** BCP 47 locale tag — drives weekday / month names. */
+    locale?: string;
+    /** Enable drag-select on the grid. Default `true`. */
+    selectable?: boolean;
+    /**
+     * Which property of `IEvent` to read for colouring. Default
+     * `'category'`. Setting to `'color'` makes the calendar use the
+     * direct override exclusively.
+     */
+    eventColorKey?: 'category' | 'color' | string;
+    /**
+     * Map category string → intent / CSS colour. Skip the prop to
+     * fall back to the neutral surface for all categories.
+     */
+    categoryColors?: Record<string, TIntent | string>;
+    /** Tint Saturday + Sunday in month / week views. Default `true`. */
+    weekendHighlight?: boolean;
+    /**
+     * Render a leading ISO week-number column. Useful for project /
+     * billing calendars. Default `false`.
+     */
+    showWeekNumbers?: boolean;
+    /** First hour rendered in week / day views. Default `0`. */
+    dayStartHour?: number;
+    /** Last hour rendered in week / day views. Default `24`. */
+    dayEndHour?: number;
+    /**
+     * Minutes per row in the timeline. `30` for half-hour granularity
+     * (default), `15` for fine-grained drag-create, `60` for compact.
+     */
+    slotDuration?: number;
+    /** Lower navigation bound. The toolbar disables `<` past this. */
+    minDate?: Date | string;
+    /** Upper navigation bound. The toolbar disables `>` past this. */
+    maxDate?: Date | string;
+    /**
+     * Cells to grey out. Accepts an array (Dates or ISO strings) or a
+     * predicate when the disabling rule is too dynamic to enumerate.
+     */
+    disabledDates?: Array<Date | string> | ((d: Date) => boolean);
+}
+/**
+ * Default values applied by `<OrigamCalendar>` and consumed by the
+ * composable. Kept here as a single source of truth for the
+ * "non-undefined" prop surface — the SFC still inlines the literals
+ * inside `withDefaults` (cf. CLAUDE.md rule), this interface is for
+ * the composable to type its merged options.
+ */
+export interface IResolvedCalendarOptions {
+    view: TCalendarView;
+    currentDate: Date;
+    events: Array<IEvent>;
+    firstDayOfWeek: number;
+    timeFormat: TCalendarTimeFormat;
+    locale: string;
+    selectable: boolean;
+    eventColorKey: string;
+    categoryColors: Record<string, TIntent | string>;
+    weekendHighlight: boolean;
+    showWeekNumbers: boolean;
+    dayStartHour: number;
+    dayEndHour: number;
+    slotDuration: number;
+    minDate: Date | null;
+    maxDate: Date | null;
+    disabledDatesPredicate: (date: Date) => boolean;
+}
+/**
+ * Emits surfaced by `<OrigamCalendar>`. Mirrors the doc — every
+ * payload is plain serialisable data (Date instances + the original
+ * event reference) so consumers can forward them through a Pinia
+ * action or a websocket without unwrapping refs.
+ */
+export interface ICalendarEmits {
+    (e: 'update:view', view: TCalendarView): void;
+    (e: 'update:currentDate', date: Date): void;
+    (e: 'event-click', event: IEvent, originalDOMEvent: MouseEvent): void;
+    (e: 'date-click', date: Date): void;
+    (e: 'range-select', start: Date, end: Date): void;
+    (e: 'create-event-request', start: Date, end: Date): void;
+    (e: 'view-change', view: TCalendarView): void;
+    (e: 'navigate', direction: TCalendarNavigate): void;
+}
+/**
+ * Slot signatures. The default toolbar can be replaced wholesale via
+ * `#header`, individual day cells via `#day` / `#dayHeader`, and the
+ * event card via `#event`. Empty agenda state via `#empty`.
+ */
+export interface ICalendarSlots {
+    header?: (bindings: ICalendarHeaderSlotBindings) => any;
+    event?: (bindings: ICalendarEventSlotBindings) => any;
+    day?: (bindings: ICalendarDaySlotBindings) => any;
+    dayHeader?: (bindings: {
+        date: Date;
+    }) => any;
+    empty?: (bindings: {
+        view: TCalendarView;
+    }) => any;
+}
+/** Bindings handed to the `#event` slot — one per visible event. */
+export interface ICalendarEventSlotBindings {
+    event: IEvent;
+    view: TCalendarView;
+    isPast: boolean;
+    isToday: boolean;
+}
+/** Bindings handed to the `#day` slot — one per cell in month view. */
+export interface ICalendarDaySlotBindings {
+    date: Date;
+    events: Array<IEvent>;
+    isToday: boolean;
+    isPast: boolean;
+    isOutside: boolean;
+    isWeekend: boolean;
+    isDisabled: boolean;
+}
+/** Bindings handed to the `#header` slot — full toolbar replacement. */
+export interface ICalendarHeaderSlotBindings {
+    view: TCalendarView;
+    title: string;
+    canPrev: boolean;
+    canNext: boolean;
+    setView: (next: TCalendarView) => void;
+    navigate: (direction: TCalendarNavigate) => void;
+}
+/** Composable options — strict version of the props after defaulting. */
+export interface IUseCalendarOptions {
+    events: () => Array<IEvent>;
+    view: () => TCalendarView;
+    currentDate: () => Date;
+    firstDayOfWeek: () => number;
+    slotDuration: () => number;
+    dayStartHour: () => number;
+    dayEndHour: () => number;
+    minDate?: () => Date | null;
+    maxDate?: () => Date | null;
+    locale?: () => string;
+}

package/dist/src/interfaces/Calendar/event.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Calendar/event.interface.d.ts

@@ -0,0 +1,54 @@
+import type { TIntent } from '../../types';
+/**
+ * Public event shape consumed by `<OrigamCalendar>` and the
+ * `useCalendar` composable. Designed to be friendly to JSON
+ * round-trips — `start` / `end` may be passed as ISO-8601 strings,
+ * Date objects, or epoch numbers; the calendar normalises them
+ * internally.
+ *
+ * `rrule` follows a strict subset of RFC 5545 (see
+ * `src/utils/Calendar/rrule.util.ts`): `FREQ=DAILY|WEEKLY|MONTHLY`
+ * + `INTERVAL=N` + `COUNT=N` + `UNTIL=...` + `BYDAY=...`. Anything
+ * else is ignored — flag this in the consumer-facing doc.
+ */
+export interface IEvent {
+    /** Stable identifier — used as `:key` and for click-target wiring. */
+    id: string | number;
+    /** Displayed title — also read by the default `aria-label`. */
+    title: string;
+    /** Optional long-form description — surfaced in the agenda view. */
+    description?: string;
+    /** Start instant. ISO-8601 strings and `Date` instances both work. */
+    start: string | Date;
+    /**
+     * End instant. Omitted when `allDay=true` (the calendar treats the
+     * event as a single-day block) or for "point-in-time" events with
+     * no measurable duration.
+     */
+    end?: string | Date;
+    /**
+     * `true` to render the event in the all-day band above the time
+     * grid (week / day views). Has no effect in month view.
+     */
+    allDay?: boolean;
+    /**
+     * Free-form category string — used as the lookup key for
+     * `categoryColors`. Useful when multiple events share a colour
+     * (e.g. "meeting", "focus", "personal").
+     */
+    category?: string;
+    /**
+     * Direct colour override. Wins over `category` when both are set.
+     * Accepts a `TIntent` (matches the design-token rail) or any CSS
+     * colour string.
+     */
+    color?: TIntent | string;
+    /**
+     * RRULE subset string. The calendar expands the recurrence to
+     * the visible range at render time; the original event is **not**
+     * mutated.
+     */
+    rrule?: string;
+    /** Free-form metadata — passed through to the `event-click` payload. */
+    metadata?: Record<string, unknown>;
+}

package/dist/src/interfaces/Card/card-header.interface.d.ts

@@ -1,5 +1,8 @@
-import type { IAdjacentProps, IBorderProps, ICommonsComponentProps, IDensityProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps } from '../../interfaces';
+import type { IAdjacentEmits, IAdjacentProps, IBorderProps, ICommonsComponentProps, IDensityProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps } from '../../interfaces';
 export interface ICardHeaderProps extends ITagProps, ICommonsComponentProps, IBorderProps, IRoundedProps, IPaddingProps, IMarginProps, IDensityProps, IAdjacentProps {
     subtitle?: string | number;
     title?: string | number;
 }
+/** Emits fired by `<OrigamCardHeader>` — clicks on prepend/append slots. */
+export interface ICardHeaderEmits extends IAdjacentEmits {
+}

package/dist/src/interfaces/Card/card.interface.d.ts

@@ -1,4 +1,4 @@
-import type { IActiveProps, IAdjacentProps, IBorderProps, IBgColorProps, IColorProps, ICommonsComponentProps, IDensityProps, IDimensionProps, IElevationProps, ILinkProps, ILoaderProps, ILocationProps, IMarginProps, IPaddingProps, IPositionProps, IRippleProps, IRoundedProps, ITagProps } from '../../interfaces';
+import type { IActiveEmits, IActiveProps, IAdjacentEmits, IAdjacentProps, IBorderProps, IBgColorProps, IColorProps, ICommonsComponentProps, IDensityProps, IDimensionProps, IElevationProps, IHoverEmits, ILinkProps, ILoaderProps, ILocationProps, IMarginProps, IPaddingProps, IPositionProps, IRippleProps, IRoundedProps, ITagProps } from '../../interfaces';
 import type { TCardType } from '../../types';
 export interface ICardProps extends ICommonsComponentProps, ITagProps, IBorderProps, IColorProps, IBgColorProps, IDensityProps, IDimensionProps, IElevationProps, ILoaderProps, ILocationProps, IPositionProps, IRoundedProps, IMarginProps, IPaddingProps, ILinkProps, IRippleProps, IAdjacentProps, IActiveProps {
     disabled?: boolean;
@@ -11,3 +11,7 @@ export interface ICardProps extends ICommonsComponentProps, ITagProps, IBorderPr
     title?: string | number;
     type?: TCardType;
 }
+/** Emits fired by `<OrigamCard>` — prepend/append clicks + active/hover
+ *  state propagation. */
+export interface ICardEmits extends IAdjacentEmits, IActiveEmits, IHoverEmits {
+}

package/dist/src/interfaces/Carousel/carousel.interface.d.ts

@@ -1,4 +1,4 @@
-import type { IColorProps, ICommonsComponentProps, IDimensionProps, ITagProps, IWindowProps } from '../../interfaces';
+import type { IColorProps, ICommonsComponentEmits, ICommonsComponentProps, IDimensionProps, ITagProps, IWindowProps } from '../../interfaces';
 import type { TIcon, TInline } from '../../types';
 export interface ICarouselProps extends IWindowProps, IColorProps, ICommonsComponentProps, ITagProps, IDimensionProps {
     cycle?: boolean;
@@ -9,3 +9,6 @@ export interface ICarouselProps extends IWindowProps, IColorProps, ICommonsCompo
     progress?: boolean;
     verticalDelimiters?: boolean | TInline;
 }
+/** Emits fired by `<OrigamCarousel>` — v-model on the active slide index. */
+export interface ICarouselEmits extends ICommonsComponentEmits {
+}

package/dist/src/interfaces/Chart/chart-annotation.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Chart/chart-annotation.interface.d.ts

@@ -0,0 +1,99 @@
+import type { TIntent } from '../../types';
+/**
+ * A single overlay annotation drawn on top of a cartesian chart's
+ * SVG surface. Annotations are positioned in data coordinates and
+ * projected to pixel space by the chart's X/Y scales. They are
+ * cartesian-only — polar, radar, gauge and other non-cartesian
+ * families ignore this prop.
+ *
+ * Four kinds are supported:
+ *
+ * - `'arrow'`   — a directed line with an arrowhead at the head end,
+ *                 optional text label near the tail.
+ * - `'label'`   — a rounded-rect callout box with text, connected to
+ *                 the data point by a thin leader line.
+ * - `'circle'`  — a stroked circle centred on the data point,
+ *                 optional text label next to it.
+ * - `'bracket'` — a horizontal or L-shaped bracket spanning two data
+ *                 coordinates, centered text label above/below.
+ */
+export interface IChartAnnotation {
+    /** Annotation kind. */
+    kind: 'arrow' | 'label' | 'circle' | 'bracket';
+    /** Source / anchor data coordinate on the X axis (category string or numeric index). */
+    x: number | string;
+    /** Source / anchor data coordinate on the Y axis. */
+    y: number;
+    /**
+     * End-point X coordinate in data space.
+     * Required for `'arrow'` (head position) and `'bracket'` (right edge).
+     */
+    x2?: number | string;
+    /**
+     * End-point Y coordinate in data space.
+     * Optional for `'bracket'` — when omitted the bracket stays
+     * horizontal (`y2 === y`).
+     */
+    y2?: number;
+    /** Text content rendered alongside the annotation. */
+    text?: string;
+    /** Stroke / fill colour — accepts a `TIntent` name or any CSS colour string. */
+    color?: TIntent | string;
+    /** Stroke width in SVG units. Default `1.5`. */
+    width?: number;
+    /** Circle radius in SVG units. Applies to the `'circle'` kind only. Default `12`. */
+    radius?: number;
+    /**
+     * Horizontal offset of the text label relative to its anchor
+     * point, in SVG units. Positive values push the label right.
+     * Default `0`.
+     */
+    dx?: number;
+    /**
+     * Vertical offset of the text label relative to its anchor
+     * point, in SVG units. Positive values push the label down.
+     * Default `-14`.
+     */
+    dy?: number;
+}
+/**
+ * Resolved SVG geometry for one annotation. Produced by
+ * `computeAnnotationGeometry` in `chart.composable.ts` and consumed
+ * directly by `<OrigamChartCartesian>` for rendering. Fields are
+ * gated per `kind` — the renderer checks `kind` before reading each
+ * optional field.
+ */
+export interface IChartAnnotationGeo {
+    kind: IChartAnnotation['kind'];
+    /** Resolved CSS colour string. */
+    stroke: string;
+    strokeWidth: number;
+    /** Anchor pixel coordinate (tail of arrow / anchor of label / centre of circle / left edge of bracket). */
+    ax: number;
+    ay: number;
+    /** End pixel coordinate (head of arrow / right edge of bracket). Equals `(ax, ay)` when unused. */
+    bx: number;
+    by: number;
+    /** Arrowhead polygon `points` attribute — populated for `kind === 'arrow'`. */
+    arrowPoints?: string;
+    /** Text content to display alongside the annotation. */
+    text?: string;
+    /** Resolved horizontal text offset in SVG units. */
+    dx: number;
+    /** Resolved vertical text offset in SVG units. */
+    dy: number;
+    /** Circle radius in SVG units — populated for `kind === 'circle'`. */
+    radius: number;
+    /** Callout rounded-rect geometry — populated for `kind === 'label'`. */
+    callout?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Bottom-centre of the callout box where the leader line terminates — populated for `kind === 'label'`. */
+    leaderEnd?: {
+        x: number;
+        y: number;
+    };
+}

package/dist/src/interfaces/Chart/chart-axis.interface.cjs

@@ -0,0 +1 @@
+"use strict";