origam 2.3.0 → 2.5.0

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.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.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.d.ts

@@ -0,0 +1,78 @@
+import type { IChartTick } from '../../interfaces';
+/**
+ * Props for `<OrigamChartAxis>` — the cartesian-only axes + grid +
+ * tick labels block. Extracted from the legacy `<OrigamChart>`
+ * monolith so polar / radar / gauge families don't accidentally
+ * inherit cartesian chrome (the historical "pie has axis lines"
+ * bug).
+ *
+ * The component is a pure renderer: it expects pre-computed tick
+ * arrays + plot corners from `useChart` and paints them. No data
+ * coupling, no reactivity beyond its props.
+ */
+export interface IChartAxisProps {
+    /**
+     * Pixel coordinates of the plotting area's four corners.
+     * Comes verbatim from `useChart().plot.value`.
+     */
+    plot: {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+        cx: number;
+        cy: number;
+    };
+    /** Tick descriptors for X + Y (primary left axis). Comes from `useChart().ticks.value`. */
+    ticks: {
+        x: Array<IChartTick>;
+        y: Array<IChartTick>;
+    };
+    /**
+     * Tick descriptors for the secondary right Y axis.
+     * When provided, a second vertical axis is rendered on the
+     * right edge of the plot area. Comes from
+     * `useChart().secondaryTicks.value`.
+     */
+    secondaryYTicks?: Array<IChartTick>;
+    /**
+     * Render the four-corner axis frame + tick labels. When `false`,
+     * the component renders nothing (mirrors the legacy `showAxis`
+     * prop on `<OrigamChart>`).
+     */
+    showAxis?: boolean;
+    /**
+     * Render horizontal grid lines under the plot. When `false`,
+     * no grid is drawn (mirrors the legacy `showGrid` prop).
+     */
+    showGrid?: boolean;
+    /**
+     * Formatter applied to X-axis tick labels. Defaults to
+     * `String(value)`.
+     */
+    xAxisFormat?: (value: string | number) => string;
+    /**
+     * Formatter applied to Y-axis tick labels. Defaults to
+     * `String(value)`.
+     */
+    yAxisFormat?: (value: number) => string;
+    /**
+     * Formatter applied to the secondary (right) Y-axis tick labels.
+     * Falls back to `yAxisFormat`, then `String(value)`.
+     */
+    secondaryYAxisFormat?: (value: number) => string;
+}
+/**
+ * Configuration object for the secondary (right-hand) Y axis.
+ * Passed as the `secondaryYAxis` prop on `<OrigamChartCartesian>`.
+ */
+export interface IChartSecondaryYAxis {
+    /** Force the minimum value of the secondary Y scale. Auto-computed when absent. */
+    min?: number;
+    /** Force the maximum value of the secondary Y scale. Auto-computed when absent. */
+    max?: number;
+    /** Formatter applied to the right-axis tick labels. */
+    format?: (value: number) => string;
+    /** Optional axis title rendered alongside the right axis. */
+    title?: string;
+}

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

@@ -0,0 +1,87 @@
+import type { IBgColorProps, IChartPoint, IChartSeries, ICommonsComponentProps, IDimensionProps, IElevationProps, IMarginProps, IPaddingProps, IRoundedProps } from '../../interfaces';
+import type { TChartLegendPosition, TIntent } from '../../types';
+/**
+ * Props shared across every chart type. Per-type components
+ * (`OrigamChartBar`, `OrigamChartLine`, `OrigamChartPie`, …) extend
+ * this surface and layer their type-specific options on top
+ * (`stacked` for bar/column, `smoothing` for line/area,
+ * `donutHoleSize` for donut, etc.).
+ *
+ * The legacy `<OrigamChart>` (the universal variant-based component)
+ * stays available for advanced consumers — it uses `IChartProps`
+ * which is `IChartBaseProps + type + all type-specific options`.
+ */
+export interface IChartBaseProps extends ICommonsComponentProps, IDimensionProps, IMarginProps, IPaddingProps, IRoundedProps, IElevationProps, IBgColorProps {
+    /** Data series — one or more. Empty array renders the `#empty` slot. */
+    series: Array<IChartSeries>;
+    /**
+     * X axis labels (for line/area/bar/column/radar). Length should
+     * match the longest series; missing entries fall back to the
+     * numeric index. Ignored for pie / donut / scatter.
+     */
+    categories?: Array<string>;
+    /** Optional title rendered above the plotting area. */
+    title?: string;
+    /** Optional subtitle rendered below the title. */
+    subtitle?: string;
+    /** Toggle the legend block. Default `true`. */
+    showLegend?: boolean;
+    /** Anchor of the legend block. Default `'bottom'`. */
+    legendPosition?: TChartLegendPosition;
+    /** Toggle the hover tooltip. Default `true`. */
+    showTooltip?: boolean;
+    /**
+     * Animate paths / bars / slices on first paint and on data
+     * changes. Respects `prefers-reduced-motion`. Default `true`.
+     */
+    animated?: boolean;
+    /** Animation duration in ms. Default `600`. */
+    animationDuration?: number;
+    /**
+     * Palette used when a series does not pin its own `color`.
+     * Pass intent strings (cycled in order) or raw CSS colours.
+     * Default cycles through the 8 origam intents.
+     */
+    colorScheme?: Array<TIntent | string>;
+    /**
+     * CSS `aspect-ratio` shortcut (`'16/9'`, `'4/3'`, `'1/1'`…). When
+     * set, overrides `height` and lets the chart breathe with the
+     * container width.
+     */
+    aspectRatio?: string;
+}
+/**
+ * Emits surfaced by every per-type chart component. Identical to
+ * `IChartEmits` from the universal `<OrigamChart>` — the wrapper
+ * components forward verbatim.
+ */
+export interface IChartBaseEmits {
+    /** Mouse / keyboard activation on a data point. */
+    (e: 'point-click', point: IChartPoint, originalEvent: MouseEvent | KeyboardEvent): void;
+    /** Click on a legend entry — pair with `series-toggle` for state. */
+    (e: 'legend-click', series: IChartSeries, index: number): void;
+    /** Resulting visibility flip after a legend click. */
+    (e: 'series-toggle', series: IChartSeries, visible: boolean): void;
+}
+/**
+ * Slot signatures shared across every per-type chart component.
+ * Identical to `IChartSlots` from the universal `<OrigamChart>`.
+ */
+export interface IChartBaseSlots {
+    /** Replace the default tooltip body. */
+    tooltip?: (bindings: {
+        point: IChartPoint;
+        series: IChartSeries;
+        category: string | number;
+    }) => any;
+    /** Replace one legend entry. */
+    'legend-item'?: (bindings: {
+        series: IChartSeries;
+        index: number;
+        visible: boolean;
+    }) => any;
+    /** Replace the title block (title + subtitle). */
+    title?: () => any;
+    /** Render when `series` is empty / every series is hidden. */
+    empty?: () => any;
+}