origam 2.2.1 → 2.5.0

package/dist/src/types/EmptyState/empty-state-align.type.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Horizontal alignment of the icon / title / description / actions
+ * stack inside `<OrigamEmptyState>`.
+ *
+ * - `center` — default. Centred stack, content also `text-align: center`.
+ *              Best for full-page or full-section placeholders.
+ * - `left`   — left-aligned stack. Best for narrow side panels or list
+ *              empty zones where the surrounding content is left-aligned.
+ */
+export type TEmptyStateAlign = 'center' | 'left';

package/dist/src/types/EmptyState/empty-state-preset.type.cjs

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

package/dist/src/types/EmptyState/empty-state-preset.type.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Visual presets for `<OrigamEmptyState>`. Each preset bundles a
+ * default icon + intent mapping so consumers do not need to wire those
+ * by hand for the 95% case. The icon and intent can still be
+ * overridden via the matching props when a one-off variation is
+ * needed.
+ *
+ * - `no-data`     — generic "nothing to show yet" (empty collection).
+ * - `no-results`  — search or filter returned nothing.
+ * - `error`       — an operation failed; retry CTA is typical.
+ * - `offline`     — connectivity issue; offline-mode CTA is typical.
+ * - `locked`      — feature is gated (auth, plan, permissions).
+ */
+export type TEmptyStatePreset = 'no-data' | 'no-results' | 'error' | 'offline' | 'locked';

package/dist/src/types/EmptyState/empty-state-size.type.cjs

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

package/dist/src/types/EmptyState/empty-state-size.type.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Vertical density of `<OrigamEmptyState>`. Drives icon size + title /
+ * description font sizes + gap + padding via per-size token overrides.
+ *
+ * - `sm` — compact (inline empty zones inside dense containers).
+ * - `md` — default (full-page-section empty states).
+ * - `lg` — generous (hero empty pages, marketing-style placeholders).
+ */
+export type TEmptyStateSize = 'sm' | 'md' | 'lg';

package/dist/src/types/Grid/grid-align.type.cjs

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

package/dist/src/types/Grid/grid-align.type.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Place-items (`align-items` + `justify-items`) accepts the 4-value
+ * subset of CSS Box Alignment. `baseline` is excluded on purpose —
+ * it has no useful meaning when items can span rows / columns.
+ */
+export type TGridPlaceItems = 'start' | 'center' | 'end' | 'stretch';
+/**
+ * Place-content (`align-content` + `justify-content`) — aligns the
+ * full grid inside its container when the grid is smaller than the
+ * available space. Mirrors the CSS Box Alignment matrix.
+ */
+export type TGridPlaceContent = 'start' | 'center' | 'end' | 'stretch' | 'space-between' | 'space-around' | 'space-evenly';
+/**
+ * Place-self (`align-self` + `justify-self`) on a grid item.
+ * Same matrix as place-items.
+ */
+export type TGridPlaceSelf = 'start' | 'center' | 'end' | 'stretch';
+/**
+ * Gap size tokens (`'xs' | 'sm' | 'md' | 'lg' | 'xl'`). When the
+ * consumer passes one of these strings to the `gap` / `columnGap`
+ * / `rowGap` prop, `<OrigamGrid>` resolves it to a `var(--origam-grid---gap-{token})`
+ * reference (which itself points at `space.*` primitives via
+ * `tokens/component/grid.json`).
+ *
+ * Any other string is passed through verbatim (`'24px'`, `'1rem 2rem'`).
+ * Plain `number` is interpreted as pixels.
+ */
+export type TGridGapSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';

package/dist/src/types/Grid/grid-flow.type.cjs

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

package/dist/src/types/Grid/grid-flow.type.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Closed list of CSS `grid-auto-flow` values surfaced by `<OrigamGrid>`.
+ *
+ * The native CSS spec accepts more permutations (`column dense`,
+ * `row column dense`, …), but the matrix below is what 99 % of
+ * dashboards / page-builders need. If a consumer needs a more
+ * exotic value, they can pass a raw string via `:style` on the
+ * outer container — we don't double-validate `grid-auto-flow`.
+ */
+export type TGridAutoFlow = 'row' | 'column' | 'row dense' | 'column dense';

package/dist/src/types/InlineEdit/inline-edit-input-type.type.cjs

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

package/dist/src/types/InlineEdit/inline-edit-input-type.type.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Native HTML input types accepted by `<OrigamInlineEdit>` when not in
+ * multiline mode. Intentionally a closed set — `password`, `file`,
+ * `checkbox`, … don't fit the edit-in-place pattern and would require
+ * a different UX surface.
+ */
+export type TInlineEditInputType = 'text' | 'number' | 'email' | 'tel';

package/dist/src/types/Mask/built-in-pattern.type.cjs

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

package/dist/src/types/Mask/built-in-pattern.type.d.ts

@@ -0,0 +1,7 @@
+import type { BUILT_IN_PATTERN } from '../../enums';
+/**
+ * Discriminated union of every curated mask preset shipped
+ * with origam. New presets must be added to
+ * `BUILT_IN_PATTERN` AND `BUILT_IN_PATTERNS` (const map).
+ */
+export type TBuiltInPattern = typeof BUILT_IN_PATTERN[keyof typeof BUILT_IN_PATTERN];

package/dist/src/types/Mask/mask.type.cjs

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

package/dist/src/types/Mask/mask.type.d.ts

@@ -0,0 +1,19 @@
+import type { IMaskOptions } from '../../interfaces';
+import type { TBuiltInPattern } from './built-in-pattern.type';
+/**
+ * Accepted value for the `OrigamTextField.mask` prop and the
+ * `useMask` first arg. Either a built-in preset key, a raw
+ * pattern string (with `#`, `A`, `*`, literals), or a full
+ * options object.
+ */
+export type TMask = TBuiltInPattern | string | IMaskOptions | null;
+/**
+ * Token kinds recognised by the in-house token-walker.
+ *
+ * - `digit`    : consumer slot, accepts `[0-9]` only.    (`#`)
+ * - `letter`   : consumer slot, accepts `[a-zA-Z]` only. (`A`)
+ * - `any`      : consumer slot, accepts any character.   (`*`)
+ * - `literal`  : emitted as-is, does NOT consume the
+ *                input character.
+ */
+export type TMaskTokenKind = 'digit' | 'letter' | 'any' | 'literal';

package/dist/src/types/Mask/pattern-validator.type.cjs

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

package/dist/src/types/Mask/pattern-validator.type.d.ts

@@ -0,0 +1,16 @@
+import type { PATTERN_VALIDATOR } from '../../enums';
+/**
+ * Built-in validator name (string) — recognised by
+ * `validatePattern`.
+ */
+export type TPatternValidatorName = typeof PATTERN_VALIDATOR[keyof typeof PATTERN_VALIDATOR];
+/**
+ * User-supplied validator function — receives the UNMASKED
+ * value and returns `true` if it passes business rules.
+ */
+export type TPatternValidatorFn = (unmasked: string) => boolean;
+/**
+ * Validator passed to `useMask` / accepted by `resolveMaskConfig`.
+ * Either a registered name, or an arbitrary function.
+ */
+export type TPatternValidator = TPatternValidatorName | TPatternValidatorFn;

package/dist/src/types/Masonry/masonry-align.type.cjs

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

package/dist/src/types/Masonry/masonry-align.type.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Vertical alignment of items inside a single masonry column.
+ *
+ * - `'top'`     — items packed against the top of the column (default,
+ *                 Pinterest-style).
+ * - `'center'`  — column content is centred vertically inside the
+ *                 container height (rare, but useful when the masonry
+ *                 sits inside a taller flex parent and the consumer
+ *                 wants the visual centre of gravity in the middle).
+ *
+ * Only honoured by the JS fallback path — the CSS-native masonry path
+ * uses `align-items` semantics, which already maps to `start` (top).
+ * The CSS path therefore always aligns to top; switching to `'center'`
+ * implicitly forces the JS fallback so the value is observable.
+ */
+export type TMasonryAlign = 'top' | 'center';

package/dist/src/types/Media/index.cjs

@@ -0,0 +1,27 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _mediaScrubberOrientation = require("./media-scrubber-orientation.type.cjs");
+Object.keys(_mediaScrubberOrientation).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _mediaScrubberOrientation[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _mediaScrubberOrientation[key];
+    }
+  });
+});
+var _qualityOption = require("./quality-option.type.cjs");
+Object.keys(_qualityOption).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _qualityOption[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _qualityOption[key];
+    }
+  });
+});

package/dist/src/types/Media/index.d.ts

@@ -0,0 +1,2 @@
+export * from './media-scrubber-orientation.type';
+export * from './quality-option.type';

package/dist/src/types/Media/index.js

@@ -0,0 +1,2 @@
+export * from "./media-scrubber-orientation.type.js";
+export * from "./quality-option.type.js";

package/dist/src/types/Media/media-scrubber-orientation.type.cjs

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

package/dist/src/types/Media/media-scrubber-orientation.type.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Layout axis for `<OrigamMediaScrubber>`. Horizontal is the default,
+ * matches the YouTube timeline shape; vertical is the volume / level
+ * meter shape (top = max, bottom = min).
+ */
+export type TMediaScrubberOrientation = 'horizontal' | 'vertical';

package/dist/src/types/Media/quality-option.type.cjs

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

package/dist/src/types/Media/quality-option.type.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Single entry of the quality drill-down inside the
+ * `<OrigamMediaController>` config menu.
+ *
+ * Shared shape between `<OrigamVideo>` (which derives it from its
+ * `<source>` array) and `<OrigamAudio>` (step 4 — will derive it from
+ * its own source array). The `quality` field is the stable identifier
+ * passed back via `quality-change`; `label` is the human-readable text
+ * shown in the menu.
+ *
+ * Lives in `types/` rather than `interfaces/` because the shape is a
+ * plain data record — `T`-prefix per project convention.
+ */
+export type TQualityOption = {
+    /** Stable identifier exposed via `quality-change` (e.g. `"1080p"`). */
+    quality: string;
+    /** Human-readable label shown in the menu. */
+    label: string;
+    /** Optional source URL — only used when the parent wants to embed
+     *  it inside the option for a one-shot swap. The Controller never
+     *  reads this field; consumers do. */
+    src?: string;
+    /** Optional MIME type — same rationale as `src`. */
+    type?: string;
+};

package/dist/src/types/NumberFormat/number-format-format.type.cjs

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

package/dist/src/types/NumberFormat/number-format-format.type.d.ts

@@ -0,0 +1,56 @@
+/**
+ * High-level format dialect understood by `<OrigamNumberFormat>` and
+ * `useNumberFormat`. Each value maps to a known `Intl.NumberFormat`
+ * configuration (style + notation) so callers do not have to wire the
+ * raw `Intl` options themselves for the 95% case.
+ *
+ * - `decimal` — plain number, locale-aware grouping (default).
+ * - `currency` — uses `currency` + `currencyDisplay` (style: 'currency').
+ * - `percent` — multiplies by 100 and appends the locale percent glyph
+ *   (style: 'percent').
+ * - `unit` — pairs with `unit` + `unitDisplay` (style: 'unit').
+ * - `compact` — short / long compact notation (1.2K / 1.2 million),
+ *   internally sets `notation: 'compact'`.
+ * - `scientific` — exponent notation (1.234E5).
+ * - `engineering` — engineering-style exponent (multiples of 3).
+ */
+export type TNumberFormatFormat = 'decimal' | 'currency' | 'percent' | 'unit' | 'compact' | 'scientific' | 'engineering';
+/**
+ * Currency-symbol rendering — forwarded to `Intl.NumberFormat`'s
+ * `currencyDisplay` option.
+ */
+export type TNumberFormatCurrencyDisplay = 'symbol' | 'narrowSymbol' | 'code' | 'name';
+/**
+ * Unit-label rendering — forwarded to `Intl.NumberFormat`'s
+ * `unitDisplay` option.
+ */
+export type TNumberFormatUnitDisplay = 'short' | 'long' | 'narrow';
+/**
+ * Compact-notation rendering — forwarded to `Intl.NumberFormat`'s
+ * `compactDisplay` option. Only applies when `notation === 'compact'`.
+ */
+export type TNumberFormatCompactDisplay = 'short' | 'long';
+/**
+ * Raw `notation` mirror — exposed for advanced callers who set
+ * `format: 'decimal'` but still want scientific / engineering output.
+ */
+export type TNumberFormatNotation = 'standard' | 'compact' | 'scientific' | 'engineering';
+/**
+ * Sign-display strategy — forwarded to `Intl.NumberFormat`'s
+ * `signDisplay` option.
+ */
+export type TNumberFormatSignDisplay = 'auto' | 'always' | 'except-zero' | 'negative' | 'never';
+/**
+ * Grouping (thousands separator) strategy — boolean kept for backwards
+ * compat with the original `Intl.NumberFormat` API; the string variants
+ * (`'always' | 'auto' | 'min2'`) match the modern proposal landed in
+ * Chrome 106+ / Safari 16.4+.
+ */
+export type TNumberFormatUseGrouping = boolean | 'always' | 'auto' | 'min2';
+/**
+ * Sentinel for the locale prop — `'auto'` triggers the runtime
+ * resolution chain (`<html lang>` → `navigator.language` → `'en-US'`).
+ * Any other value (a BCP-47 tag or array of tags) is passed through to
+ * `Intl.NumberFormat` verbatim.
+ */
+export type TNumberFormatLocale = string | string[];

package/dist/src/types/Parallax/parallax-direction.type.cjs

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

package/dist/src/types/Parallax/parallax-direction.type.d.ts

@@ -0,0 +1,2 @@
+import { PARALLAX_DIRECTION } from '../../enums';
+export type TParallaxDirection = `${PARALLAX_DIRECTION}`;

package/dist/src/types/Parallax/parallax-easing.type.cjs

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

package/dist/src/types/Parallax/parallax-easing.type.d.ts

@@ -0,0 +1,2 @@
+import { PARALLAX_EASING } from '../../enums';
+export type TParallaxEasing = `${PARALLAX_EASING}`;

package/dist/src/types/QrCode/qr-code-error-correction.type.cjs

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

package/dist/src/types/QrCode/qr-code-error-correction.type.d.ts

@@ -0,0 +1,22 @@
+/**
+ * QR Code error-correction level (Reed-Solomon redundancy budget).
+ * The higher the level, the more of the matrix is reserved for
+ * correction codewords — which means:
+ *
+ *   - more dense / larger matrices for the same payload
+ *   - more tolerance for damage, occlusion, or a logo overlay
+ *
+ * The four levels are defined by ISO/IEC 18004:
+ *
+ * | Level | Recovery | Use case                                                  |
+ * |-------|----------|-----------------------------------------------------------|
+ * | `L`   | ~7%      | Clean printing surface, no overlay, dense data.           |
+ * | `M`   | ~15%     | Default — good balance for digital / print without logo.  |
+ * | `Q`   | ~25%     | Mild damage / dirt / scuff risk, small logo overlay.      |
+ * | `H`   | ~30%     | Marketing-style codes with centred logo (up to ~25–30%).  |
+ *
+ * A logo overlay obscures payload bits — pick `Q` for ≤20% logo, `H`
+ * for ≥20%. Below `Q`, the redundancy budget is too thin for any
+ * meaningful overlay.
+ */
+export type TQrCodeErrorCorrectionLevel = 'L' | 'M' | 'Q' | 'H';

package/dist/src/types/SliderField/slider-field-variant.type.cjs

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

package/dist/src/types/SliderField/slider-field-variant.type.d.ts

@@ -0,0 +1,10 @@
+import { SLIDER_FIELD_VARIANT } from '../../enums';
+/**
+ * Visual variant of `<OrigamSliderField>`. Drives the rendering path:
+ * - `'field'`  → wrapped in `<origam-input>` (label, messages, …).
+ * - `'timer'`  → bare wrapper, sober video-scrubber look.
+ * - `'audio'`  → bare wrapper + waveform background painted from `peaks`.
+ *
+ * Default is `'field'` (no behavioural break vs. Phase 1).
+ */
+export type TSliderFieldVariant = `${SLIDER_FIELD_VARIANT}`;

package/dist/src/types/Snackbar/snackbar-group-direction.type.cjs

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

package/dist/src/types/Snackbar/snackbar-group-direction.type.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Stacking direction for `OrigamSnackbarGroup`.
+ *
+ * - `top-down` — newest item appended at the bottom of the visible
+ *   list (older items drift upward as the stack grows). Default for
+ *   locations anchored to the top edge.
+ * - `bottom-up` — newest item appears at the top of the visible list
+ *   (older items drift downward). Default for locations anchored to
+ *   the bottom edge.
+ */
+export type TSnackbarGroupDirection = 'top-down' | 'bottom-up';

package/dist/src/types/Snackbar/snackbar-group-location.type.cjs

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

package/dist/src/types/Snackbar/snackbar-group-location.type.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Anchor locations supported by `OrigamSnackbarGroup`.
+ *
+ * Two-keyword strings (e.g. `'top-right'`) describe a corner, single
+ * keyword strings (`'top'`, `'bottom'`) describe a viewport edge with
+ * horizontal centering. Each location maps to a CSS pinning pair on
+ * the stack root (`top` / `bottom` + `left` / `right` / centered).
+ */
+export type TSnackbarGroupLocation = 'top-left' | 'top-right' | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center' | 'top' | 'bottom';

package/dist/src/types/Snackbar/snackbar-group.type.cjs

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

package/dist/src/types/Snackbar/snackbar-group.type.d.ts

@@ -0,0 +1,2 @@
+import type { OrigamSnackbarGroup } from "../../components";
+export type TOrigamSnackbarGroup = InstanceType<typeof OrigamSnackbarGroup>;

package/dist/src/types/Tabs/tab-panel.type.cjs

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

package/dist/src/types/Tabs/tab-panel.type.d.ts

@@ -0,0 +1,2 @@
+import { OrigamTabPanel } from '../../components';
+export type TOrigamTabPanel = InstanceType<typeof OrigamTabPanel>;

package/dist/src/types/Tabs/tab-panels.type.cjs

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

package/dist/src/types/Tabs/tab-panels.type.d.ts

@@ -0,0 +1,2 @@
+import { OrigamTabPanels } from '../../components';
+export type TOrigamTabPanels = InstanceType<typeof OrigamTabPanels>;

package/dist/src/types/Tabs/tab-variant.type.cjs

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

package/dist/src/types/Tabs/tab-variant.type.d.ts

@@ -0,0 +1,2 @@
+import { TAB_VARIANT } from '../../enums';
+export type TTabVariant = `${TAB_VARIANT}`;

package/dist/src/types/Tabs/tab.type.cjs

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

package/dist/src/types/Tabs/tab.type.d.ts

@@ -0,0 +1,2 @@
+import { OrigamTab } from '../../components';
+export type TOrigamTab = InstanceType<typeof OrigamTab>;

package/dist/src/types/Tabs/tabs.type.cjs

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

package/dist/src/types/Tabs/tabs.type.d.ts

@@ -0,0 +1,2 @@
+import { OrigamTabs } from '../../components';
+export type TOrigamTabs = InstanceType<typeof OrigamTabs>;

package/dist/src/types/TextMask/text-mask-animation.type.cjs

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

package/dist/src/types/TextMask/text-mask-animation.type.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Animation strategy applied to the background painted under the
+ * `background-clip: text` mask.
+ *
+ *   - `pan`    — translate the gradient horizontally (default; great for
+ *                long horizontal `linear-gradient` ramps).
+ *   - `rotate` — rotate the background-image (best fit for `conic` gradients
+ *                where every angle is meaningful).
+ *   - `pulse`  — scale 1 → 1.2 → 1 (subtle breathing effect).
+ *   - `zoom`   — continuous scale 1 → 2 (cinematic "moving forward" feel).
+ *
+ * Every animation respects `prefers-reduced-motion: reduce` — the SCSS
+ * disables the keyframes entirely so users opting out of motion get a
+ * static painted text without flashes or transforms.
+ */
+export type TTextMaskAnimation = 'pan' | 'rotate' | 'pulse' | 'zoom';

package/dist/src/types/TextMask/text-mask.type.cjs

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

package/dist/src/types/TextMask/text-mask.type.d.ts

@@ -0,0 +1,2 @@
+import { OrigamTextMask } from "../../components";
+export type TOrigamTextMask = InstanceType<typeof OrigamTextMask>;

package/dist/src/types/Textarea/textarea-mode.type.cjs

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

package/dist/src/types/Textarea/textarea-mode.type.d.ts

@@ -0,0 +1,2 @@
+import type { TEXTAREA_MODE } from '../../enums';
+export type TTextareaMode = `${TEXTAREA_MODE}`;

package/dist/src/types/Textarea/textarea-output.type.cjs

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

package/dist/src/types/Textarea/textarea-output.type.d.ts

@@ -0,0 +1,2 @@
+import type { TEXTAREA_OUTPUT } from '../../enums';
+export type TTextareaOutput = `${TEXTAREA_OUTPUT}`;

package/dist/src/types/Textarea/textarea-toolbar-command.type.cjs

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

package/dist/src/types/Textarea/textarea-toolbar-command.type.d.ts

@@ -0,0 +1,2 @@
+import type { TEXTAREA_TOOLBAR_COMMAND } from '../../enums';
+export type TTextareaToolbarCommand = `${TEXTAREA_TOOLBAR_COMMAND}`;

package/dist/src/types/Textarea/textarea-toolbar-position.type.cjs

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

package/dist/src/types/Textarea/textarea-toolbar-position.type.d.ts

@@ -0,0 +1,2 @@
+import type { TEXTAREA_TOOLBAR_POSITION } from '../../enums';
+export type TTextareaToolbarPosition = `${TEXTAREA_TOOLBAR_POSITION}`;

package/dist/src/types/Video/video-controls.type.cjs

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

package/dist/src/types/Video/video-controls.type.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Controls rendering strategy for `<OrigamVideo>`.
+ *
+ * - `'custom'` (default): the component paints its own toolbar with
+ *   play/pause, scrubber, volume, captions, PIP and fullscreen buttons.
+ *   The `<video>` element is rendered WITHOUT the native `controls`
+ *   attribute so the two UIs do not stack.
+ * - `'native'`: the `<video>` element receives the native `controls`
+ *   attribute and the browser paints its own toolbar. No custom UI is
+ *   rendered. Useful when the consumer needs the platform-specific
+ *   accessibility shortcuts (e.g. AirPlay button on Safari) or when
+ *   rendering inside a Tauri shell that talks to native players.
+ * - `'none'`: neither the custom nor the native toolbar is rendered.
+ *   The consumer drives playback programmatically through the
+ *   `#controls` slot or the exposed composable methods.
+ */
+export type TVideoControls = 'custom' | 'native' | 'none';