npm - origam - Versions diffs - 2.3.0 → 2.6.1 - Mend

origam 2.3.0 → 2.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1155) hide show

package/dist/src/interfaces/NumberFormat/number-format.interface.d.ts ADDED Viewed

@@ -0,0 +1,161 @@
+import type { ICommonsComponentProps, ITagProps } from '../../interfaces';
+import type { TNumberFormatCompactDisplay, TNumberFormatCurrencyDisplay, TNumberFormatFormat, TNumberFormatLocale, TNumberFormatNotation, TNumberFormatSignDisplay, TNumberFormatUnitDisplay, TNumberFormatUseGrouping } from '../../types';
+/**
+ * Props for `<OrigamNumberFormat>` — pure-display i18n number renderer
+ * powered by `Intl.NumberFormat` (zero external dep).
+ *
+ * The component owns NO state: it transforms `value` through the
+ * resolved `Intl` instance and emits the result into a `<tag>` element
+ * (default `<span>`). Consumers who want to override the rendering
+ * granularly use the scoped `#default` slot which exposes
+ * `{ formatted, parts, value }`.
+ */
+export interface INumberFormatProps extends ICommonsComponentProps, ITagProps {
+    /**
+     * Number to render. Strings are parsed via `Number()` — callers can
+     * pass a stringified BigInt-like to preserve precision before
+     * coercion (the actual formatting still goes through `Number`, so
+     * values beyond `Number.MAX_SAFE_INTEGER` may lose accuracy).
+     */
+    value: number | string;
+    /**
+     * High-level format dialect — see `TNumberFormatFormat`.
+     *
+     * @default 'decimal'
+     */
+    format?: TNumberFormatFormat;
+    /**
+     * BCP-47 locale tag (or array, for fallback chains). The literal
+     * string `'auto'` triggers the runtime resolution chain (`<html
+     * lang>` → `navigator.language` → `'en-US'`).
+     *
+     * @default 'auto'
+     */
+    locale?: TNumberFormatLocale;
+    /**
+     * ISO 4217 currency code. Required when `format === 'currency'`; we
+     * fall back to `'USD'` rather than throwing so storybook controls
+     * remain forgiving.
+     *
+     * @default 'USD' (only when format === 'currency')
+     */
+    currency?: string;
+    /**
+     * Currency-symbol rendering — `'symbol'` (`$`), `'narrowSymbol'`
+     * (`$` instead of `US$`), `'code'` (`USD`) or `'name'`
+     * (`US dollar`).
+     *
+     * @default 'symbol'
+     */
+    currencyDisplay?: TNumberFormatCurrencyDisplay;
+    /**
+     * Sanctioned unit identifier (e.g. `'kilometer-per-hour'`,
+     * `'celsius'`, `'liter'`). Required when `format === 'unit'`. The
+     * full ECMAScript-sanctioned list is exposed under
+     * `Intl.supportedValuesOf('unit')` at runtime.
+     */
+    unit?: string;
+    /**
+     * Unit-label rendering — `'short'` (`km/h`), `'long'`
+     * (`kilometers per hour`) or `'narrow'` (`kph`).
+     *
+     * @default 'short'
+     */
+    unitDisplay?: TNumberFormatUnitDisplay;
+    /**
+     * Raw `notation` override. Auto-set to `'compact'` when `format ===
+     * 'compact'`, to `'scientific'` / `'engineering'` for the matching
+     * formats. Explicit values still win — useful for `format:
+     * 'decimal'` with `notation: 'scientific'`.
+     */
+    notation?: TNumberFormatNotation;
+    /**
+     * Compact-notation rendering — `'short'` (`1M`) or `'long'`
+     * (`1 million`). Only honoured when `notation === 'compact'`.
+     *
+     * @default 'short'
+     */
+    compactDisplay?: TNumberFormatCompactDisplay;
+    /** Minimum digits after the decimal point. */
+    minimumFractionDigits?: number;
+    /** Maximum digits after the decimal point. */
+    maximumFractionDigits?: number;
+    /** Minimum significant digits (mutually exclusive with fraction digits). */
+    minimumSignificantDigits?: number;
+    /** Maximum significant digits (mutually exclusive with fraction digits). */
+    maximumSignificantDigits?: number;
+    /**
+     * Thousands-separator behaviour. `true` / `'auto'` keep the locale
+     * default, `false` removes them, `'always'` forces them on, `'min2'`
+     * only renders them when the integer part has at least 2 groups.
+     *
+     * @default true
+     */
+    useGrouping?: TNumberFormatUseGrouping;
+    /**
+     * Sign-display strategy. `'auto'` (default — only negatives),
+     * `'always'`, `'except-zero'`, `'negative'`, `'never'`.
+     *
+     * @default 'auto'
+     */
+    signDisplay?: TNumberFormatSignDisplay;
+}
+/**
+ * Bindings exposed by the scoped `#default` slot. Consumers use these
+ * to highlight specific parts of the formatted output (currency symbol,
+ * decimal separator, …) without re-running `Intl.NumberFormat`
+ * themselves.
+ */
+export interface INumberFormatScopedSlotBindings {
+    /** The locale-formatted string, ready to render. */
+    formatted: string;
+    /** The structured parts (`Intl.NumberFormatPart[]`). */
+    parts: Intl.NumberFormatPart[];
+    /** The numeric value after string-to-number coercion. */
+    value: number;
+}
+/**
+ * Slot signatures for `<OrigamNumberFormat>`.
+ */
+export interface INumberFormatSlots {
+    /**
+     * Custom render override. Scoped — receives the resolved value plus
+     * the structured parts so consumers can paint individual segments.
+     */
+    default?: (bindings: INumberFormatScopedSlotBindings) => any;
+}
+/**
+ * Options accepted by `useNumberFormat`. Mirrors the public props of
+ * `<OrigamNumberFormat>` minus the wiring concerns (`tag`, `class`,
+ * `style`).
+ */
+export interface IUseNumberFormatOptions {
+    /** Same semantics as `INumberFormatProps.format`. */
+    format?: TNumberFormatFormat;
+    /** Same semantics as `INumberFormatProps.locale`. */
+    locale?: TNumberFormatLocale;
+    /** Same semantics as `INumberFormatProps.currency`. */
+    currency?: string;
+    /** Same semantics as `INumberFormatProps.currencyDisplay`. */
+    currencyDisplay?: TNumberFormatCurrencyDisplay;
+    /** Same semantics as `INumberFormatProps.unit`. */
+    unit?: string;
+    /** Same semantics as `INumberFormatProps.unitDisplay`. */
+    unitDisplay?: TNumberFormatUnitDisplay;
+    /** Same semantics as `INumberFormatProps.notation`. */
+    notation?: TNumberFormatNotation;
+    /** Same semantics as `INumberFormatProps.compactDisplay`. */
+    compactDisplay?: TNumberFormatCompactDisplay;
+    /** Same semantics as `INumberFormatProps.minimumFractionDigits`. */
+    minimumFractionDigits?: number;
+    /** Same semantics as `INumberFormatProps.maximumFractionDigits`. */
+    maximumFractionDigits?: number;
+    /** Same semantics as `INumberFormatProps.minimumSignificantDigits`. */
+    minimumSignificantDigits?: number;
+    /** Same semantics as `INumberFormatProps.maximumSignificantDigits`. */
+    maximumSignificantDigits?: number;
+    /** Same semantics as `INumberFormatProps.useGrouping`. */
+    useGrouping?: TNumberFormatUseGrouping;
+    /** Same semantics as `INumberFormatProps.signDisplay`. */
+    signDisplay?: TNumberFormatSignDisplay;
+}

package/dist/src/interfaces/NumberFormat/number-format.interface.js ADDED Viewed

File without changes

package/dist/src/interfaces/Nuxt/nuxt-module.interface.d.ts CHANGED Viewed

@@ -1,37 +1,68 @@
+import type { IOrigamTheme } from '../Theme/origam-theme.interface';
 /**
  * Options passed by a consumer in `nuxt.config.ts` under the `origam` key.
  *
  * All fields are optional — the module applies sensible defaults (see
- * `DEFAULTS` in `src/nuxt/module.ts`). Themes are auto-injected as CSS
- * imports; the active theme is resolved SSR-side via cookie and the
- * `Sec-CH-Prefers-Color-Scheme` client hint to avoid FOUC and hydration
- * mismatches.
+ * `DEFAULTS` in `src/nuxt/module.ts`). Themes are installed as runtime OBJECTS
+ * (ADR-004): the module passes the `themes` array straight through to the
+ * runtime config and on to `createOrigam` in the plugins, which inject each as
+ * a name×mode scoped `--origam-*` block. The theme-invariant `primitive` +
+ * `utilities` sheets are still loaded as CSS. Two orthogonal axes are resolved
+ * SSR-side to avoid FOUC: the brand `theme` (cookie) and the color `mode`
+ * (cookie + `Sec-CH-Prefers-Color-Scheme` hint).
+ *
+ * ADR-004 (Implemented): the DS ships exactly ONE neutral identity (the origam
+ * baseline). Brand themes live in the consuming app (e.g. the marketing
+ * package) and are passed here as `IOrigamTheme[]` objects authored in
+ * semantic JSON — the DS no longer resolves preset names or ships brand
+ * token sheets.
  */
 export interface IOrigamNuxtModuleOptions {
     /**
-     * Theme names whose CSS file must be loaded. Each name must match a
-     * generated `dist/src/assets/css/tokens/{theme}.css` exposed via
-     * `origam/tokens/css/{theme}`.
+     * Themes to install, as `IOrigamTheme` objects (one per brand×mode). The
+     * objects are passed verbatim to `createOrigam`, which injects each as a
+     * scoped CSS-var block — no pre-generated per-theme CSS file is loaded.
+     * When omitted, `createOrigam` installs the DS built-in baseline (neutral identity).
+     */
+    themes?: IOrigamTheme[];
+    /**
+     * Theme (brand) applied when no cookie is set. Use `'auto'` to render no
+     * `data-theme` attribute (the default brand).
+     *
+     * @default 'auto'
+     */
+    defaultTheme?: string;
+    /**
+     * Color modes supported by the loaded token sheets. Used to validate the
+     * resolved mode before applying it.
      *
      * @default ['light', 'dark']
      */
-    themes?: string[];
+    modes?: string[];
     /**
-     * Theme applied when no cookie is set and no usable
+     * Color mode applied when no cookie is set and no usable
      * `Sec-CH-Prefers-Color-Scheme` hint is sent. Use `'auto'` to let the
      * server fall back to the client hint (or `'light'` if absent).
      *
      * @default 'auto'
      */
-    defaultTheme?: string;
+    defaultMode?: string;
     /**
-     * Cookie name used to persist the user's chosen theme across sessions.
+     * Cookie name used to persist the user's chosen theme (brand) across
+     * sessions.
      *
      * @default 'origam-theme'
      */
     cookieName?: string;
     /**
-     * Cookie `max-age` in seconds.
+     * Cookie name used to persist the user's chosen color mode across
+     * sessions.
+     *
+     * @default 'origam-mode'
+     */
+    modeCookieName?: string;
+    /**
+     * Cookie `max-age` in seconds (shared by the theme and mode cookies).
      *
      * @default 31_536_000 (1 year)
      */
@@ -62,12 +93,21 @@ export interface IOrigamNuxtModuleOptions {
 }
 /**
  * Shape of the public runtime config exposed by the module on
- * `useRuntimeConfig().public.origam`. The plugins read this at boot to
- * resolve the active theme and configure the cookie.
+ * `useRuntimeConfig().public.origam`. The plugins read this at boot to install
+ * the theme objects, resolve the active theme/mode, and configure the cookies.
  */
 export interface IOrigamNuxtRuntimeConfig {
-    themes: string[];
+    /**
+     * Installed `IOrigamTheme` objects, in install order. The plugins pass
+     * these straight to `createOrigam` (no preset-name resolution — ADR-004).
+     * A switcher derives its brand list from `useInstalledThemes()` rather than
+     * from this payload.
+     */
+    themes: IOrigamTheme[];
     defaultTheme: string;
+    modes: string[];
+    defaultMode: string;
     cookieName: string;
+    modeCookieName: string;
     cookieMaxAge: number;
 }

package/dist/src/interfaces/OtpInputField/otp-input-field.interface.d.ts CHANGED Viewed

@@ -1,6 +1,6 @@
-import type { IColorProps, ICommonsComponentProps, IDensityProps, IDimensionProps, IElevationProps, IFieldEmits, IFieldProps, IFieldSlots, IFocusProps, IInputEmits, IInputProps, IInputSlots, IRoundedProps, IVariantProps } from "../../interfaces";
+import type { IFieldEmits, IFieldProps, IFieldSlots, IInputEmits, IInputProps, IInputSlots, IVariantProps } from "../../interfaces";
 import type { TOtpInputFieldType } from "../../types";
-export interface IOtpInputFieldProps extends ICommonsComponentProps, IColorProps, IDensityProps, IDimensionProps, IFieldProps, IInputProps, IRoundedProps, IElevationProps, IVariantProps, IFocusProps {
+export interface IOtpInputFieldProps extends IFieldProps, IInputProps, IVariantProps {
     autofocus?: boolean;
     divider?: string;
     focusAll?: boolean;
@@ -17,12 +17,14 @@ export interface IOtpInputFieldEmits extends IFieldEmits, IInputEmits {
     (e: 'mousedown:control', event: MouseEvent): void;
     (e: 'click:clear', event: MouseEvent): void;
 }
-export interface IOtpInputFieldSlots extends IFieldSlots, Omit<IInputSlots, 'default'> {
+export interface IOtpInputFieldSlots extends Omit<IFieldSlots, 'default'>, Omit<IInputSlots, 'default'> {
+    /** Generic slot — no slot props. */
+    default?: () => any;
     field?: (data: {
         id: string;
         isDisabled: boolean;
         isDirty: boolean;
-        isValid: boolean;
+        isValid: boolean | undefined;
         isReadonly: boolean;
     }) => any;
 }

package/dist/src/interfaces/Overlay/overlay-scrim.interface.d.ts CHANGED Viewed

@@ -1,7 +1,14 @@
-import type { ICommonsComponentProps, ITagProps, ITransitionComponentProps } from '../../interfaces';
+import type { IClickEmits, ICommonsComponentProps, ITagProps, ITransitionComponentProps } from '../../interfaces';
 export interface IOverlayScrimProps extends ICommonsComponentProps, ITagProps, ITransitionComponentProps, IScrimProps {
     active?: boolean;
 }
 export interface IScrimProps {
     scrim?: boolean | string;
 }
+/** Emits fired by `<OrigamOverlayScrim>` — click + pointer hover events
+ *  surface to the parent overlay (so it can close on backdrop click
+ *  or pause its auto-close timer while the pointer is over the scrim). */
+export interface IOverlayScrimEmits extends IClickEmits {
+    (e: 'mouseenter', event: MouseEvent): void;
+    (e: 'mouseleave', event: MouseEvent): void;
+}

package/dist/src/interfaces/Overlay/overlay.interface.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import type { IActivatorProps, ICommonsComponentProps, IDimensionProps, ILazyProps, ILocationStrategyProps, IScrimProps, IScrollStrategyProps, ITransitionComponentProps } from '../../interfaces';
+import type { IActivatorProps, IClickOutsideEmits, ICommonsComponentEmits, ICommonsComponentProps, IDimensionProps, ILazyProps, ILocationStrategyProps, IScrimProps, IScrollStrategyProps, ITransitionComponentProps } from '../../interfaces';
 export interface IOverlayProps extends ICommonsComponentProps, IDimensionProps, IActivatorProps, ILocationStrategyProps, IScrollStrategyProps, ILazyProps, ITransitionComponentProps, IScrimProps {
     absolute?: boolean;
     attach?: boolean | string | Element;
@@ -12,3 +12,10 @@ export interface IOverlayProps extends ICommonsComponentProps, IDimensionProps,
     disableGlobalStack?: boolean;
     persistent?: boolean;
 }
+/** Emits fired by `<OrigamOverlay>` — v-model on the open state, outside
+ *  click, transition lifecycle hooks, and keyboard bubble. */
+export interface IOverlayEmits extends ICommonsComponentEmits, IClickOutsideEmits {
+    (e: 'afterEnter'): void;
+    (e: 'afterLeave'): void;
+    (e: 'keydown', event: KeyboardEvent): void;
+}

package/dist/src/interfaces/Pagination/pagination.interface.d.ts CHANGED Viewed

@@ -1,6 +1,6 @@
-import type { IBorderProps, IBgColorProps, IColorProps, ICommonsComponentProps, IDensityProps, IElevationProps, IMarginProps, IPaddingProps, ISizeProps, ITagProps } from "../../interfaces";
-import type { TIcon } from "../../types";
-export interface IPaginationProps extends ICommonsComponentProps, ITagProps, IColorProps, IBgColorProps, IBorderProps, IPaddingProps, IMarginProps, IElevationProps, ISizeProps, IDensityProps {
+import type { IBorderProps, IBgColorProps, IColorProps, ICommonsComponentEmits, ICommonsComponentProps, IDensityProps, IElevationProps, IMarginProps, IPaddingProps, ISizeProps, ITagProps, ITypographyProps } from "../../interfaces";
+import type { TColor, TIcon } from "../../types";
+export interface IPaginationProps extends ICommonsComponentProps, ITagProps, IColorProps, IBgColorProps, IBorderProps, IPaddingProps, IMarginProps, IElevationProps, ISizeProps, IDensityProps, ITypographyProps {
     start?: number;
     modelValue?: number;
     disabled?: boolean;
@@ -56,4 +56,27 @@ export interface IPaginationProps extends ICommonsComponentProps, ITagProps, ICo
      * (`"Next"` in English).
      */
     nextText?: string;
+    /**
+     * aria-label for the compact mode page number `<input>`. Falls back to
+     * the `origam.pagination.ariaLabel.pageNumber` i18n key.
+     *
+     * @default 'origam.pagination.ariaLabel.pageNumber'
+     */
+    pageNumberAriaLabel?: string;
+    /** @deprecated Use the `hover` object prop instead. Kept for back-compat. */
+    hoverColor?: TColor;
+    /** @deprecated Use the `hover` object prop instead. Kept for back-compat. */
+    hoverBgColor?: TColor;
+    /** @deprecated Use the `active` object prop instead. Kept for back-compat. */
+    activeColor?: TColor;
+    /** @deprecated Use the `active` object prop instead. Kept for back-compat. */
+    activeBgColor?: TColor;
+}
+/** Emits fired by `<OrigamPagination>` — current page v-model + the four
+ *  navigation shortcuts (first / prev / next / last). */
+export interface IPaginationEmits extends ICommonsComponentEmits {
+    (e: 'first', value: number): void;
+    (e: 'prev', value: number): void;
+    (e: 'next', value: number): void;
+    (e: 'last', value: number): void;
 }

package/dist/src/interfaces/Parallax/parallax.interface.d.ts CHANGED Viewed

@@ -1,7 +1,7 @@
-import type { IAudioProps, IBorderProps, IBox, IBgColorProps, IColorProps, ICommonsComponentProps, IDimensionProps, IElevationProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps, IParallaxLayerRegistry } from '../../interfaces';
+import type { IAudioProps, IBorderProps, IBox, IBgColorProps, IColorProps, ICommonsComponentProps, IDimensionProps, IElevationProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps, IParallaxLayerRegistry, IUseAudioProps } from '../../interfaces';
 import type { TParallaxDirection, TParallaxEasing, TParallaxEvent, TPoint } from '../../types';
 import type { Ref } from 'vue';
-export interface IParallaxProps extends ICommonsComponentProps, ITagProps, IColorProps, IBgColorProps, IPaddingProps, IMarginProps, IBorderProps, IRoundedProps, IElevationProps, IDimensionProps, IAudioProps {
+export interface IParallaxProps extends ICommonsComponentProps, ITagProps, IColorProps, IBgColorProps, IPaddingProps, IMarginProps, IBorderProps, IRoundedProps, IElevationProps, IDimensionProps, IAudioProps, IUseAudioProps {
     /**
      * @deprecated Use `duration` instead. `animationDuration` is kept as a
      * silent alias for backwards-compat and will be removed in v3.0.0.

package/dist/src/interfaces/PasswordField/password-field.interface.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import type { IAdjacentInnerProps, IColorProps, ICommonsComponentProps, IDensityProps, IElevationProps, IFieldEmits, IFieldSlots, IInputEmits, IInputSlots, IMenuProps, IPasswordRequirement, IRoundedProps, ITextFieldProps } from '../../interfaces';
+import type { IFieldEmits, IFieldSlots, IInputEmits, IInputSlots, IMenuProps, IPasswordRequirement, ITextFieldProps } from '../../interfaces';
 import type { TIcon, TPasswordStrengthLevel } from '../../types';
 /**
  * Props for `<OrigamPasswordField>` — a TextField specialised for password
@@ -14,7 +14,7 @@ import type { TIcon, TPasswordStrengthLevel } from '../../types';
  * Extends `ITextFieldProps` so anything you can pass to TextField
  * (counter, placeholder, persistentPlaceholder, etc.) flows through.
  */
-export interface IPasswordFieldProps extends ICommonsComponentProps, IColorProps, IDensityProps, ITextFieldProps, IRoundedProps, IElevationProps, IAdjacentInnerProps {
+export interface IPasswordFieldProps extends ITextFieldProps {
     /** Icon shown when the password is HIDDEN (toggle reveals). */
     onIcon?: TIcon;
     /** Icon shown when the password is VISIBLE (toggle hides). */
@@ -99,7 +99,7 @@ export interface IPasswordFieldSlots extends IFieldSlots, Omit<IInputSlots, 'def
         id: string;
         isDisabled: boolean;
         isDirty: boolean;
-        isValid: boolean;
+        isValid: boolean | undefined;
         isReadonly: boolean;
     }) => any;
 }

package/dist/src/interfaces/Picker/picker-title.interface.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import type { IBgColorProps, IColorProps, ICommonsComponentProps, ITagProps } from "../../interfaces";
-export interface IPickerTitleProps extends ICommonsComponentProps, ITagProps, IColorProps, IBgColorProps {
+import type { IBgColorProps, IColorProps, ICommonsComponentProps, ITagProps, ITypographyProps } from "../../interfaces";
+export interface IPickerTitleProps extends ICommonsComponentProps, ITagProps, IColorProps, IBgColorProps, ITypographyProps {
     title?: string;
 }

package/dist/src/interfaces/Picker/picker.interface.d.ts CHANGED Viewed

@@ -1,5 +1,5 @@
-import type { IBorderProps, IBgColorProps, IColorProps, ICommonsComponentProps, IElevationProps, IMarginProps, IPaddingProps, IPickerTitleProps, IRoundedProps, ISheetProps } from "../../interfaces";
-export interface IPickerProps extends ICommonsComponentProps, IColorProps, IBgColorProps, ISheetProps, IBorderProps, IPaddingProps, IMarginProps, IElevationProps, IRoundedProps, IPickerTitleProps {
+import type { IBgColorProps, IPickerTitleProps, ISheetProps } from "../../interfaces";
+export interface IPickerProps extends ISheetProps, IBgColorProps, IPickerTitleProps {
     landscape?: boolean;
     hideHeader?: boolean;
 }

package/dist/src/interfaces/Progress/progress.interface.d.ts CHANGED Viewed

@@ -1,9 +1,9 @@
-import type { IColorProps, ICommonsComponentProps, IMarginProps, IPaddingProps, IProgressCircularProps, IProgressLinearProps, ITagProps } from '../../interfaces';
+import type { IBgColorProps, IColorProps, ICommonsComponentProps, IMarginProps, IPaddingProps, IProgressCircularProps, IProgressLinearProps, ITagProps } from '../../interfaces';
 import type { TProgressType } from '../../types';
 export interface IProgressProps extends IProgressLinearProps, IProgressCircularProps {
     type?: TProgressType;
 }
-export interface IProgressTypeProps extends ITagProps, ICommonsComponentProps, IColorProps, IPaddingProps, IMarginProps {
+export interface IProgressTypeProps extends ITagProps, ICommonsComponentProps, IColorProps, IBgColorProps, IPaddingProps, IMarginProps {
     indeterminate?: boolean;
     modelValue?: string | number;
     thickness?: string | number;
@@ -11,4 +11,10 @@ export interface IProgressTypeProps extends ITagProps, ICommonsComponentProps, I
     absolute?: boolean;
     max?: number | string;
     striped?: boolean;
+    /**
+     * Accessible label for the progress bar (aria-label). When omitted,
+     * defaults to `'Loading'`. Pass a localised string via your i18n
+     * provider or the parent component's `labels` mechanism.
+     */
+    label?: string;
 }

package/dist/src/interfaces/QrCode/qr-code-logo.interface.cjs ADDED Viewed

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

package/dist/src/interfaces/QrCode/qr-code-logo.interface.d.ts ADDED Viewed

@@ -0,0 +1,47 @@
+/**
+ * Optional logo overlay rendered at the centre of an OrigamQrCode.
+ *
+ * The overlay is painted **on top** of the QR matrix — any module
+ * underneath becomes unreadable. Error-correction takes care of the
+ * loss as long as the overlay stays small enough:
+ *
+ *   - L  →  do not use a logo (≤7% redundancy budget).
+ *   - M  →  ≤10% of QR width.
+ *   - Q  →  ≤20% of QR width.
+ *   - H  →  ≤25–30% of QR width.
+ *
+ * `<OrigamQrCode>` does **not** enforce these caps — the consumer
+ * decides what's acceptable. We warn (`console.warn`) when `size` is
+ * configured above 0.3 because no error-correction level survives that.
+ */
+export interface IQrCodeLogo {
+    /**
+     * Logo source. Any URL accepted by `<image href>` works — SVG, PNG,
+     * data-URI, …. The SVG fragment loads the asset asynchronously; if
+     * it fails the QR remains valid (only the overlay disappears).
+     */
+    src: string;
+    /**
+     * Logo width as a proportion of the QR width (0..1).
+     *
+     * @default 0.2
+     */
+    size?: number;
+    /**
+     * Pixel padding of the (opaque) backdrop drawn around the logo.
+     * Keeps the modules immediately adjacent to the logo readable —
+     * without padding, the scanner sees a soft-edged blob and fails.
+     *
+     * @default 6
+     */
+    padding?: number;
+    /**
+     * Backdrop colour painted under the logo (and within the padding
+     * box). Defaults to the QR background; pass a different value to
+     * paint a coloured halo (e.g. brand colour for a logotype that
+     * already includes its own white box).
+     *
+     * @default — falls back to the QR `background` prop.
+     */
+    background?: string;
+}

package/dist/src/interfaces/QrCode/qr-code-logo.interface.js ADDED Viewed

File without changes

package/dist/src/interfaces/QrCode/qr-code.interface.cjs ADDED Viewed

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

package/dist/src/interfaces/QrCode/qr-code.interface.d.ts ADDED Viewed

@@ -0,0 +1,152 @@
+import type { IBgColorProps, IBorderProps, IColorProps, ICommonsComponentProps, IElevationProps, IMarginProps, IPaddingProps, IRoundedProps, ISizeProps, ISrcObject, ITagProps } from '../../interfaces';
+import type { TIcon, TQrCodeErrorCorrectionLevel } from '../../types';
+/**
+ * Per-matrix overrides — applied INSIDE the SVG (modules + quiet
+ * zone) independently of the wrapper-level same-name props. Pass via
+ * the `qrCodeProps` slot on `<OrigamQrCode>`:
+ *
+ *   - `qrCodeProps.color`   → modules colour (overrides the wrapper
+ *                             `color` for the matrix paint only).
+ *   - `qrCodeProps.bgColor` → fill of the SVG's quiet-zone rect.
+ *   - `qrCodeProps.rounded` → per-module corner radius (mapped to
+ *                             [0, 0.5] module units via
+ *                             `resolveQrCornerRadius`).
+ *
+ * The DS-shape values (intents, hex, `currentColor`, named rungs)
+ * are transformed by `resolveQrColor` / `resolveQrCornerRadius` in
+ * `src/utils/QrCode/qr-code-adapters.util.ts` — consumers always pass
+ * canonical DS values, the component handles the SVG-side translation.
+ */
+export interface IQrCodeOptions extends IRoundedProps, IBgColorProps, IColorProps {
+}
+/**
+ * Props for `<OrigamQrCode>` — SVG QR code renderer.
+ *
+ * The component owns no state: every prop change rebuilds the
+ * underlying matrix through `qrcode-generator` and re-emits the SVG.
+ * The renderer is SSR-safe — no `window` / `document` / `canvas` API
+ * is touched.
+ *
+ * DS transverse props (all applied to the WRAPPER element, the
+ * standard chrome you get on every Origam component):
+ *
+ *   - `color`     (`IColorProps`)     — wrapper `color:` (text colour).
+ *                                       The SVG modules inherit this via
+ *                                       `fill="currentColor"` unless
+ *                                       `qrCodeProps.color` overrides.
+ *   - `bgColor`   (`IBgColorProps`)   — wrapper `background-color:`.
+ *   - `rounded`   (`IRoundedProps`)   — wrapper `border-radius`.
+ *   - `border`    (`IBorderProps`)    — wrapper `border`.
+ *   - `size`      (`ISizeProps`)      — wrapper width/height.
+ *   - `padding`   (`IPaddingProps`)   — wrapper inner spacing.
+ *   - `margin`    (`IMarginProps`)    — wrapper outer spacing.
+ *   - `elevation` (`IElevationProps`) — wrapper `box-shadow`.
+ *
+ * QR-internal props (apply to the SVG itself, NOT the wrapper):
+ *
+ *   - `qrCodeProps.color` / `.bgColor` / `.rounded` — see
+ *     `IQrCodeOptions` above for the full mapping.
+ */
+export interface IQrCodeProps extends ICommonsComponentProps, ITagProps, IColorProps, IBgColorProps, IRoundedProps, IBorderProps, IElevationProps, ISizeProps, IPaddingProps, IMarginProps {
+    /**
+     * Text or URL encoded into the QR matrix. UTF-8 is supported via
+     * the underlying `qrcode-generator` Byte mode.
+     */
+    value: string;
+    /**
+     * Optional heading rendered above the QR matrix inside the
+     * wrapper. Useful when the QR is presented alongside meta
+     * (campaign name, recipient, …) — no manual extra markup needed.
+     */
+    title?: string;
+    /**
+     * Per-matrix overrides — see `IQrCodeOptions`. When omitted, the
+     * SVG inherits the wrapper-level `color` / `bgColor` / and
+     * defaults to square modules.
+     */
+    qrCodeProps?: IQrCodeOptions;
+    /**
+     * Reed-Solomon redundancy level. Higher levels reserve more matrix
+     * cells for correction codewords (and therefore tolerate more
+     * damage / overlay). See `TQrCodeErrorCorrectionLevel` for the
+     * tradeoff matrix.
+     *
+     * @default 'M'
+     */
+    errorCorrectionLevel?: TQrCodeErrorCorrectionLevel;
+    /**
+     * Number of modules reserved as quiet-zone padding around the
+     * matrix. The ISO spec mandates ≥4 — anything smaller risks
+     * scanner failures, anything larger is purely aesthetic.
+     *
+     * @default 4
+     */
+    quietZone?: number;
+    /**
+     * Optional centred icon overlay — rendered via `<OrigamIcon>` on
+     * top of the matrix. Coexists with `image`; the `#center` slot
+     * overrides both when provided.
+     */
+    icon?: TIcon;
+    /**
+     * Optional centred image overlay. Accepts a raw URL (string) or
+     * the standard `ISrcObject` shape (src / srcset / lazySrc /
+     * aspectRatio / alt). Rendered as an `<OrigamAvatar>` overlay.
+     */
+    image?: string | ISrcObject;
+    /**
+     * Accessible label used as `aria-label`. When omitted, the
+     * component falls back to `"QR code for {value}"`.
+     */
+    ariaLabel?: string;
+}
+/**
+ * Options accepted by `useQrCode`. Lower-level than `IQrCodeProps`:
+ * the composable does not speak the canonical DS contracts. It only
+ * owns the raw SVG string — the wrapper component is responsible for
+ * mapping `color` / `bgColor` / `rounded` (wrapper or qrCodeProps)
+ * down to the primitive `foreground` / `background` / `cornerRadius`
+ * keys here.
+ */
+export interface IUseQrCodeOptions {
+    /** Reed-Solomon level — same semantics as `IQrCodeProps`. */
+    errorCorrectionLevel?: TQrCodeErrorCorrectionLevel;
+    /** Raw CSS colour painted on dark modules. */
+    foreground?: string;
+    /** Raw CSS colour painted behind the matrix (quiet zone). */
+    background?: string;
+    /** Quiet-zone padding in module units. */
+    margin?: number;
+    /**
+     * Per-module corner radius in module units (0 → square,
+     * 0.5 → circle). The component layer derives this from the
+     * public `qrCodeProps.rounded` prop via `resolveQrCornerRadius`.
+     */
+    cornerRadius?: number;
+    /**
+     * Optional logo overlay rendered inside the SVG via `<image>`.
+     * Public consumers should use the `image` prop on
+     * `<OrigamQrCode>`; this lower-level shape stays here for direct
+     * `useQrCode` consumers.
+     */
+    logo?: {
+        src: string;
+        size?: number;
+        padding?: number;
+        background?: string;
+    };
+}
+/**
+ * Slot signatures for `<OrigamQrCode>`.
+ *
+ * - `center` — replaces the default `icon` / `image` overlay.
+ *   Receives the resolved size of the central reserved square (in
+ *   matrix module units) so the consumer can paint a custom SVG /
+ *   icon without re-deriving the geometry. When this slot is
+ *   provided, both `icon` and `image` props are ignored.
+ */
+export interface IQrCodeSlots {
+    center?: (bindings: {
+        size: number;
+    }) => any;
+}

package/dist/src/interfaces/QrCode/qr-code.interface.js ADDED Viewed

File without changes