@cjlapao/ui-kit-vue 0.2.0 → 0.2.3

package/dist/types/common/theme/glass.d.ts

@@ -18,28 +18,68 @@ import type { TrueColor } from "./Theme";
 export type GlassVibrancy = "low" | "medium" | "high" | number;
 /**
  * Glass fill transparency level.
- * - `"frosted"` → 45 % light / 15 % dark  (default)
- * - `"light"`   → 70 % light / 25 % dark
- * - `"clear"`   → 20 % light /  5 % dark
+ * - `"frosted"` → 65 % light / 25 % dark  (default)
+ * - `"light"`   → 85 % light / 35 % dark
+ * - `"clear"`   → 30 % light / 10 % dark  (sheer — pair with a light backdrop)
  * - `number`    → 0–1 fraction; light = round(frac × 100), dark = min(round(frac × 30), 30)
+ *
+ * Only the three presets (and their +10 hover steps) are safelisted. A numeric
+ * value emits an arbitrary opacity that Tailwind's scanner cannot see, so the
+ * fill silently disappears unless that exact step happens to be generated —
+ * see `scripts/generate-safelist.mjs`.
  */
 export type GlassOpacity = "frosted" | "light" | "clear" | number;
 /**
  * Specular highlight mode for glass surfaces.
  * - `"none"`    → no specular overlay
- * - `"classic"` → single hairline gradient at top edge
- * - `"halo"`    → corner caps + diffuse band + bottom darken
+ * - `"classic"` → sheen falling from the top edge
+ * - `"halo"`    → broad bloom plus two off-centre corner glints
  */
 export type SpecularMode = "none" | "classic" | "halo";
 /**
  * Compute the Tailwind fill classes for a glass surface.
  *
- * Returns a string like `"bg-blue-100/55 hover:bg-blue-100/65 dark:bg-blue-600/25 dark:hover:bg-blue-600/35"`.
+ * Returns a string like `"bg-blue-200/65 hover:bg-blue-200/75 dark:bg-blue-500/25 dark:hover:bg-blue-500/35"`.
+ *
+ * The tint rides the `-200`/`-500` shades: a `-100` wash at these alphas is
+ * nearly colourless over white — exactly the “looks disabled” read glass
+ * used to get. The alpha ladder is unchanged; only the shade’s chroma moved
+ * one notch up.
  *
  * @param color   - TrueColor token (e.g. `"blue"`, `"red"`, `"fuchsia"`)
  * @param opacity - Glass opacity preset or numeric fraction (0–1)
  */
 export declare const getGlassFillClass: (color: TrueColor, opacity: GlassOpacity) => string;
+/**
+ * Glass fill for a *container* surface — `Panel` and anything built on it.
+ *
+ * Deliberately sheerer than `getGlassFillClass`, which is tuned for controls.
+ * A Button is a small target that has to stay legible against its own label; a
+ * Panel covers most of the viewport, and the same 65% fill over that area
+ * turns the backdrop into a flat wash and defeats the point of glass. It also
+ * omits the hover step: a card is not hoverable by default.
+ *
+ * `Panel` built these strings inline, so the two implementations of "glass
+ * fill" sat in different files with different scales and no shared safelist.
+ * The steps here are the ones `scripts/generate-safelist.mjs` emits.
+ */
+export declare const getSurfaceGlassFillClass: (color: TrueColor, opacity: GlassOpacity) => string;
+/**
+ * Halo specular for a container, as stacked full-bleed gradient layers for a
+ * `background-image`.
+ *
+ * Every layer spans the whole surface and reaches full transparency *inside*
+ * its own box, so none of them contributes a visible edge. An earlier version
+ * used two fixed `w-24 h-12` corner boxes filled with linear gradients — a
+ * linear gradient only fades along one axis, so the boxes' remaining edges cut
+ * off hard and read as two grey rectangles in the corners.
+ *
+ * Layer order is top-most first: the broad bloom, two off-centre glints that
+ * keep the light from looking symmetrical, then a little weight at the base.
+ * Exported so both kits' `Panel` paint the identical halo.
+ */
+export declare const SURFACE_HALO_LIGHT: string;
+export declare const SURFACE_HALO_DARK: string;
 /**
  * Map a vibrancy setting to a Tailwind backdrop-saturate class.
  *
@@ -48,12 +88,51 @@ export declare const getGlassFillClass: (color: TrueColor, opacity: GlassOpacity
  */
 export declare const getGlassVibrancyClass: (vibrancy: GlassVibrancy) => string;
 /**
- * Build Tailwind classes for a specular highlight overlay.
+ * Build the specular paint classes for a glass surface.
  *
- * - `"none"`       → `null` (no overlay)
- * - `"classic"`    → soft top-edge hairline reflection
- * - `"halo"`       → corner caps + diffuse top glow
+ * The caller owns positioning; this returns background utilities only.
  *
- * @returns class string or `null`
+ * @returns class string, or `null` for `"none"`
  */
 export declare const getSpecularClasses: (mode: SpecularMode) => string | null;
+/**
+ * Text, rim and focus ring for a glass control.
+ *
+ * Glass surfaces drop the variant's own colour classes (those paint an opaque
+ * fill), which previously left the control with **no** text colour, border or
+ * focus ring at all — the label inherited whatever the page happened to set.
+ *
+ * The rim is deliberately tone-independent white: a saturated `{color}-500`
+ * edge fights the backdrop the control is meant to sit over. Matches the rim
+ * `Panel` uses for its glass variants.
+ */
+export interface GlassChromeOptions {
+    /**
+     * Include the hover response and focus ring. Turn it off for a glass surface
+     * that is only a label — a rim that brightens under the cursor on something
+     * you cannot click reads as a broken affordance.
+     * @default true
+     */
+    interactive?: boolean;
+}
+export declare const getGlassChromeClasses: (color: TrueColor, options?: GlassChromeOptions) => string;
+/**
+ * The secondary stop derived from a `GlassBackground` primary: a neighbouring
+ * hue, close enough to harmonise and far enough for the gradient to read as a
+ * blend rather than a fade of one colour.
+ *
+ * Typed as a full `Record` over `TrueColor`, so every tone must have a real
+ * partner — the maps this replaced were hand-kept and silently missed
+ * `fuchsia`, `yellow` and `slate`, whose gradients collapsed to two stops.
+ */
+export declare const GLASS_BACKGROUND_SECONDARY_TONES: Record<TrueColor, TrueColor>;
+/**
+ * The deep stop derived from a `GlassBackground` primary: the far end of the
+ * blend — deeper or cooler than the primary so the gradient settles instead
+ * of just lightening. Same full-coverage rule as the secondary map.
+ */
+export declare const GLASS_BACKGROUND_DEEP_TONES: Record<TrueColor, TrueColor>;
+/** The secondary stop derived from a primary tone. */
+export declare const getGlassBackgroundSecondaryTone: (color: TrueColor) => TrueColor;
+/** The deep stop derived from a primary tone. */
+export declare const getGlassBackgroundDeepTone: (color: TrueColor) => TrueColor;

package/dist/types/common/theme/randomThemeColor.d.ts

@@ -17,8 +17,8 @@ export declare const getRandomThemeColorValue: () => RandomThemeColorValue;
 export declare const getRandomThemeColorClass: (prefix?: "bg" | "text" | "border") => string;
 /**
  * Returns an array of `count` Tailwind color utility classes.
- * Uses TrueColor values in order (at intensity 500) for the first N items,
- * then falls back to `getRandomThemeColorClass` for any overflow.
+ * Uses TrueColor values in order (at intensity 500), cycling once the
+ * spectrum runs out, so the result is a pure function of `count`.
  *
  * @example
  * getColorPalette(5)           // ['bg-red-500', 'bg-orange-500', ...]
@@ -27,8 +27,8 @@ export declare const getRandomThemeColorClass: (prefix?: "bg" | "text" | "border
 export declare const getColorPalette: (count: number, prefix?: "bg" | "text" | "border") => string[];
 /**
  * Returns an array of `count` TrueColor names (e.g. `'red'`, `'orange'`, `'blue'`).
- * Uses TrueColor values in order for the first N items,
- * then falls back to random colors from RANDOM_THEME_COLORS for overflow.
+ * Uses TrueColor values in order, cycling once the spectrum runs out, so the
+ * result is a pure function of `count`.
  * Useful when components construct their own Tailwind class strings via template literals.
  *
  * @example

package/dist/types/common/tooltip/placement.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Tooltip placement with collision handling.
+ *
+ * Pure geometry, deliberately free of DOM and framework: both kits call the
+ * same function so a tooltip lands in the same place in React and in Vue, and
+ * so the interesting part — the flipping and clamping — can be tested directly
+ * instead of through a rendered component.
+ *
+ * What this replaces: the previous implementation clamped the tooltip
+ * *horizontally* and nothing else. A `top` tooltip on a trigger near the top of
+ * the window rendered off-screen, `left` and `right` did not exist as
+ * placements at all, and the caret could drift off the end of a clamped
+ * tooltip.
+ */
+export declare const TOOLTIP_POSITIONS: readonly ["top", "bottom", "left", "right"];
+export type TooltipPosition = (typeof TOOLTIP_POSITIONS)[number];
+/** The subset of `DOMRect` this needs. */
+export interface TooltipRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+export interface TooltipViewport {
+    width: number;
+    height: number;
+}
+export interface TooltipPlacementInput {
+    /** The trigger's viewport-relative box. */
+    trigger: TooltipRect;
+    /** The tooltip's measured size. */
+    tooltip: {
+        width: number;
+        height: number;
+    };
+    viewport: TooltipViewport;
+    /**
+     * Region the tooltip must stay inside, in viewport coordinates. Defaults to
+     * the viewport itself.
+     *
+     * Pass a scroll container's or panel's rect to keep a tooltip within it —
+     * the tooltip then flips and clamps against *that* edge, which is what makes
+     * a bounded demo (or a tooltip inside a modal) behave the way the surrounding
+     * box implies it should. The boundary is intersected with the viewport, so a
+     * constrained tooltip still never leaves the screen.
+     */
+    boundary?: TooltipRect;
+    /** Preferred side. Flipped or reassigned when it does not fit. */
+    preferred: TooltipPosition;
+    /** Gap between trigger and tooltip. @default 8 */
+    offset?: number;
+    /** Minimum distance to keep from every viewport edge. @default 8 */
+    margin?: number;
+    /**
+     * Keeps the caret this far from the tooltip's corners, so it never sits on
+     * the rounded part or pokes past the end. @default 10
+     */
+    caretInset?: number;
+    /**
+     * How the box aligns along the caret axis.
+     *
+     * `"center"` (default) centres the box on the trigger — what a tooltip
+     * should do: it is a label and it floats over its target.
+     *
+     * `"grow"` grows the box away from the trigger, aligning the near edge
+     * with the trigger's near edge: it grows toward the side that has room, so
+     * right (left edges aligned) when the box fits there, otherwise left
+     * (right edges aligned). What a popover should do: the panel reads as
+     * anchored to the button it came from, not floating over its centre.
+     *
+     * The caret maths below are identical for both — the caret always tracks
+     * the trigger's centre after clamping.
+     */
+    align?: "center" | "grow";
+}
+export interface TooltipPlacement {
+    /** The side actually used — may differ from `preferred` after a flip. */
+    side: TooltipPosition;
+    /** Viewport-relative position for the tooltip box. */
+    left: number;
+    top: number;
+    /**
+     * Caret offset in px from the tooltip's leading edge, along whichever axis
+     * the caret slides on: x for `top`/`bottom`, y for `left`/`right`.
+     */
+    caret: number;
+    /** True when the preferred side could not be used. */
+    flipped: boolean;
+}
+/**
+ * Chooses a side: the preferred one if it fits, then its opposite, then the
+ * remaining two — and if nothing fits, whichever has the most room, so the
+ * tooltip degrades to "least bad" instead of running off the screen.
+ */
+export declare const resolveTooltipSide: (input: TooltipPlacementInput) => {
+    side: TooltipPosition;
+    flipped: boolean;
+};
+/**
+ * Full placement: side, box position, and where the caret has to sit so it
+ * still points at the trigger's centre after any clamping.
+ */
+export declare const resolveTooltipPlacement: (input: TooltipPlacementInput) => TooltipPlacement;

package/dist/types/common/tooltip/tokens.d.ts

@@ -0,0 +1,40 @@
+import type { TooltipPosition } from "./placement";
+/**
+ * How the tooltip is painted.
+ *
+ * `surface` follows the theme — a light card in light mode, a dark one in dark
+ * mode. `inverted` contrasts against the page instead, which is the classic
+ * tooltip convention.
+ *
+ * The component used to be `bg-neutral-900 … dark:bg-neutral-700`: dark in
+ * *both* themes, with no light appearance at all.
+ */
+export declare const TOOLTIP_VARIANTS: readonly ["surface", "inverted"];
+export type TooltipVariant = (typeof TOOLTIP_VARIANTS)[number];
+export interface TooltipVariantTokens {
+    /** Classes for the tooltip box, including its border. */
+    box: string;
+    /**
+     * Classes for the arrow. It is a rotated square sharing the box's fill and
+     * border, not a CSS-triangle: a triangle built from `border-*-<colour>` has
+     * no outline of its own, so on the light `surface` variant it was a white
+     * shape on a white page — invisible, which is exactly how it was reported.
+     */
+    arrow: string;
+}
+export declare const getTooltipVariantTokens: (variant: TooltipVariant) => TooltipVariantTokens;
+/**
+ * Which box edge the arrow's centre sits on. `top` means the tooltip is above
+ * the trigger, so the arrow hangs off its bottom edge.
+ */
+export declare const TOOLTIP_ARROW_EDGE: Record<TooltipPosition, string>;
+/**
+ * Which two edges of the (unrotated) square keep their border.
+ *
+ * The square is rotated 45°, so its original edges face diagonally: a vector
+ * pointing right becomes down-right, and one pointing down becomes down-left.
+ * Only the two faces pointing *away* from the box are outlined — the two
+ * facing into it share the box's fill and vanish into it, which is what makes
+ * the arrow read as part of the bubble rather than a diamond stuck to it.
+ */
+export declare const TOOLTIP_ARROW_BORDER: Record<TooltipPosition, string>;

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

@@ -0,0 +1,15 @@
+/**
+ * Unified snapshot of all user-configurable table preferences.
+ *
+ * Defined here (not in a kit) because it is the persistence contract shared
+ * by the React and Vue kits and by the storage helpers in
+ * `common/utils/tableStorage.ts`. A kit's Table component re-exports it.
+ */
+export interface TableSettings {
+    columnVisibility?: Record<string, boolean>;
+    columnWidths?: Record<string, number>;
+    activeView?: "table" | "panel";
+    groupBy?: string | null;
+    showGroupHeader?: boolean;
+    stickyColumns?: Record<string, "left" | "right">;
+}

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

@@ -1,11 +1,81 @@
+import type { TrueColor } from "../theme/Theme";
+/** Whether a token expands to a plain value or an environment reference. */
 export type SmartVariableType = "var" | "env";
-export type SmartVariableSource = "global" | "system" | "service";
+/**
+ * Which group a token belongs to — the middle segment of
+ * `{{ type::source::name }}`.
+ *
+ * An open string, not a fixed union. It used to be
+ * `"global" | "system" | "service"`, which hardcoded one product's taxonomy
+ * into the kit; the caller now names its own groups.
+ */
+export type SmartVariableSource = string;
+/** A token found in, or about to be inserted into, a value. */
 export interface SmartVariable {
     fullToken: string;
     type: SmartVariableType;
     source: SmartVariableSource;
     name: string;
+    label?: string;
     description?: string;
+    /** Concrete value, when the caller already knows it. */
+    value?: string;
     defaultValue?: string;
+    /** Masks the value in the preview. */
+    secret?: boolean;
 }
+/**
+ * One variable a caller offers in the picker. Replaces the
+ * `CapsuleBlueprintParameter` shape the component used to require.
+ */
+export interface SmartVariableDefinition {
+    /** Token name — the third segment. */
+    key: string;
+    /** Display name. Falls back to `key`. */
+    label?: string;
+    description?: string;
+    /** @default "var" */
+    type?: SmartVariableType;
+    /** Concrete value, if known now. */
+    value?: string;
+    defaultValue?: string;
+    /** Renders the resolved value masked. */
+    secret?: boolean;
+    /** Resolves to a value only at run time — shown as a distinct state. */
+    runtime?: boolean;
+}
+/** A named set of variables, rendered as one tab in the picker. */
+export interface SmartVariableGroup {
+    /** Becomes the token's `source` segment. */
+    id: SmartVariableSource;
+    label: string;
+    /** Icon name from the kit's registry. */
+    icon?: string;
+    /** Accent colour for badges from this group. */
+    tone?: TrueColor;
+    variables: SmartVariableDefinition[];
+    /** Shown when the group is empty or filtered to nothing. */
+    emptyMessage?: string;
+}
+/**
+ * How a token turned out.
+ * - `resolved` — a concrete value is known
+ * - `runtime`  — valid, but only gets a value when the thing actually runs
+ * - `missing`  — no such variable, or it resolved to nothing
+ */
+export type SmartVariableState = "resolved" | "runtime" | "missing";
+export interface SmartVariableResolution {
+    value: string;
+    state: SmartVariableState;
+}
+/**
+ * Turns a token into a display value. Supplied by the caller, so product rules
+ * — derived values, environment lookups, runtime placeholders — live in the
+ * app rather than in the kit.
+ */
+export type SmartVariableResolver = (variable: SmartVariable) => SmartVariableResolution;
+/**
+ * @deprecated Parallels-specific sample data. Pass your own
+ * `SmartVariableGroup[]` instead; kept so existing call sites keep compiling.
+ */
 export declare const SYSTEM_VARIABLES: SmartVariable[];

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

@@ -0,0 +1,113 @@
+import { isSameDay } from "date-fns/isSameDay";
+/**
+ * Date mechanics for the kit's date controls (currently `DatePicker`).
+ *
+ * Framework-agnostic on purpose: the Vue port reuses this module, and keeping
+ * the calendar maths out of the component files means a component test fails
+ * on a wrong date, not on a wrong class. Formatting and parsing use
+ * date-fns token strings so a `format` prop is exactly what date-fns
+ * documents.
+ */
+export type DatePickerSelectionMode = "single" | "range";
+/**
+ * What a DatePicker holds.
+ *
+ * - `single` → `Date | null`
+ * - `range`  → `[start, end | null] | null` — the second element is `null`
+ *   while the range is still open (start picked, end not yet).
+ */
+export type DatePickerValue = Date | [Date, Date | null] | null;
+export declare const DEFAULT_DATE_FORMAT = "MMM d, yyyy";
+/** Literal separator range values and range input text use. */
+export declare const RANGE_SEPARATOR = " - ";
+/** Sunday-first, matching `Date.getDay()`. */
+export declare const WEEKDAY_LABELS: string[];
+export declare const WEEKDAY_LABELS_SHORT: string[];
+export declare const MONTH_NAMES: string[];
+export declare const MONTH_NAMES_SHORT: string[];
+/** Same calendar day (local time) — date-fns' `isSameDay` re-exported under a
+ *  kit-facing name so callers don't need to know the library. */
+export declare const isSameDayDate: typeof isSameDay;
+/** `Date` instances and ISO-ish strings/numbers normalise to a fresh `Date`, or `null`. */
+export declare const normalizeDate: (value: Date | string | number | null | undefined) => Date | null;
+/** Local-midnight display of a date: `format(value, "EEE d MMM yyyy")` for labels. */
+export declare const formatDateLabel: (value: Date) => string;
+export declare const formatDate: (value: Date, formatString?: string) => string;
+/** A value (or each end of a range) rendered in the input. */
+export declare const formatValue: (value: DatePickerValue, formatString?: string) => string;
+/**
+ * Localized month/weekday names for locale-aware parsing (i18n, spec §6).
+ * date-fns parses English-only month names, so candidates are normalised
+ * locale → English before parsing; all four sets are optional (a missing set
+ * simply is not normalised).
+ */
+export interface DateParseNames {
+    monthFull?: string[];
+    monthShort?: string[];
+    weekdayFull?: string[];
+    weekdayShort?: string[];
+}
+export declare const parseDateText: (text: string, formatString?: string, reference?: Date, names?: DateParseNames) => Date | null;
+/**
+ * Free-typed input → value. Single: one date. Range: `start - end`, where a
+ * missing or empty end yields an open range `[start, null]`. An end before the
+ * start, or an unparseable start, yields `null` (the text stays as typed and
+ * is flagged invalid by the caller).
+ */
+export declare const parseValueText: (text: string, selectionMode?: DatePickerSelectionMode, formatString?: string, reference?: Date, names?: DateParseNames) => DatePickerValue | null;
+export interface DateConstraints {
+    /** Earliest selectable day (inclusive), day-level. */
+    minDate?: Date | null;
+    /** Latest selectable day (inclusive), day-level. */
+    maxDate?: Date | null;
+    /** Weekdays that are never selectable — `getDay()` numbering, 0 = Sunday. */
+    disabledDays?: number[];
+    /** Exact dates (compared day-level) or a predicate. */
+    disabledDates?: Date[] | ((date: Date) => boolean) | null;
+}
+/** Whether a calendar day may be picked, under the given constraints. */
+export declare const isDateSelectable: (date: Date, constraints?: DateConstraints) => boolean;
+export interface DayCell {
+    date: Date;
+    /** Day of month — the number drawn in the cell. */
+    day: number;
+    /** Day belongs to a neighbouring month (leading/trailing filler). */
+    otherMonth: boolean;
+    /** Day is today. */
+    today: boolean;
+    /** Passes the constraints AND is allowed by `selectOtherMonths`. */
+    selectable: boolean;
+}
+/**
+ * A full 6×7 month grid — always 42 cells.
+ *
+ * Other-month days fill the leading and trailing slots, so the panel's height
+ * never changes from month to month. PrimeVue renders 4–6 rows instead and the
+ * overlay resizes mid-animation; a fixed grid is the only shape the open/close
+ * motion can rely on.
+ */
+export declare const buildMonthGrid: (year: number, month: number, options?: {
+    weekStartsOn?: 0 | 1;
+    constraints?: DateConstraints;
+    today?: Date;
+    selectOtherMonths?: boolean;
+}) => DayCell[];
+/** Days in the given (0-based) month. */
+export declare const getDaysInMonth: (year: number, month: number) => number;
+/** Month arithmetic with date-fns' end-of-month clamping (Jan 31 + 1m → Feb 28/29). */
+export declare const addMonthsToDate: (date: Date, amount: number) => Date;
+export declare const addYearsToDate: (date: Date, amount: number) => Date;
+/** Day-level `a < b` — the comparison the range model makes everywhere. */
+export declare const isBeforeDay: (a: Date, b: Date) => boolean;
+/** Inclusive, day-level `start <= date <= end`. */
+export declare const isDateBetween: (start: Date, end: Date, date: Date) => boolean;
+/** The decade a year view covers: `2025` → `[2020, 2029]`. */
+export declare const getDecadeRange: (year: number) => [number, number];
+/**
+ * Which month the calendar should show for a value — PrimeVue's `viewDate`
+ * rule: single → the date, range → the start, empty → today clamped into the
+ * constraint range (so an out-of-bounds "today" does not open on a dead month).
+ */
+export declare const getViewDate: (value: DatePickerValue, constraints?: DateConstraints) => Date;
+/** `true` when nothing is selected (single: `null`; range: start unset). */
+export declare const isValueEmpty: (value: DatePickerValue | [Date | null, Date | null]) => boolean;

package/dist/types/common/utils/gravatar.d.ts

@@ -1,11 +1 @@
-/**
- * Returns a Gravatar URL for the given email.
- *
- * @param email - The user's email address.
- * @param size  - Image size in pixels (default 200).
- * @param defaultImage - Gravatar fallback when no image exists.
- *   Common values: `'404'` (return HTTP 404), `'mp'` (mystery-person silhouette),
- *   `'identicon'` (geometric pattern), `'retro'` (8-bit style).
- *   Defaults to `'mp'` so a valid image is always returned.
- */
 export declare const getGravatarUrl: (email: string, size?: number, defaultImage?: string) => string;

package/dist/types/common/utils/safeStorage.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A best-effort `Storage` wrapper, shared by every component that persists
+ * settings of its own.
+ *
+ * It swallows quota errors, private-mode rejections and SSR (no `window`), so
+ * persistence can never crash a render. Any `Storage`-shaped object
+ * (sessionStorage, a test double, an IndexedDB adapter) can be passed in its
+ * place.
+ *
+ * This was `Table`'s alone. `SmartGridLayout` needs the identical thing, and a
+ * second copy of "degrade instead of throwing" logic is a second chance to get
+ * one of the failure modes wrong.
+ */
+/** The subset of `Storage` these components actually use. */
+export interface KitStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Resolves `localStorage` lazily *inside* each call's try/catch: access itself
+ * throws in some blocked-storage configurations, so resolving once up front
+ * would break the module rather than the call.
+ */
+export declare const createSafeLocalStorage: () => KitStorageAdapter;
+/** Namespaced key, so component entries never collide with app keys. */
+export declare const buildStorageKey: (prefix: string, key: string) => string;
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;

package/dist/types/common/utils/sanitizeSvg.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Conservative SVG sanitiser.
+ *
+ * `DynamicImg` injects caller-supplied SVG with `dangerouslySetInnerHTML` /
+ * `v-html`. SVG is not an inert image format — it can carry `<script>`, `on*`
+ * event attributes, `<foreignObject>` holding arbitrary HTML, SMIL animations
+ * that set event handlers, and `<image>`/`href` pointing at a remote URL. A
+ * "dynamic image" is by definition data the app did not author, so every one
+ * of those is a live stored-XSS or exfiltration vector.
+ *
+ * This walks the parsed document and rebuilds it from an allowlist: anything
+ * not named here is dropped. An allowlist fails closed — an unknown element or
+ * attribute is discarded rather than passed through.
+ */
+export interface SanitizeSvgOptions {
+    /**
+     * Replaces every fill that is not `none`. `none` is left alone — recolouring
+     * it turns an outline-only shape into a solid blob.
+     */
+    fill?: string;
+    /** Replaces every stroke that is not `none`. */
+    stroke?: string;
+}
+/**
+ * Returns sanitised `<svg>` markup, or `null` when the input is not an SVG or
+ * cannot be parsed. Callers must treat `null` as "show the fallback" — never
+ * as "render the original".
+ */
+export declare const sanitizeSvg: (markup: string, options?: SanitizeSvgOptions) => string | null;
+export interface ParsedImageSource {
+    kind: "svg" | "raster";
+    /** The original data URL, for the raster case. */
+    src: string;
+    /** Decoded markup, for the SVG case. */
+    markup?: string;
+}
+/**
+ * Works out what a caller handed over: a raster data URL, an SVG data URL
+ * (base64 or URL-encoded), or raw `<svg>` markup.
+ *
+ * The old check was `base64.includes("data:image/png;base64,")` — `includes`,
+ * not `startsWith`, so the marker only had to appear *somewhere* in the string.
+ */
+export declare const parseImageSource: (value: string) => ParsedImageSource | null;