@vastare/fundatio 0.1.0

package/dist/types/elements/media/audio/index.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Fundatio Design Foundation: Audio element helpers.
+ *
+ * @remarks
+ * The audio element (`<audio>`) embeds sound content in documents.
+ * It can load audio via `src` or nested `<source>` elements, and it can
+ * also be a destination for streamed media via MediaStream.
+ *
+ * Best-practice guidance (MDN + platform norms):
+ * - Avoid autoplaying audio unless the user explicitly opts in.
+ * - Prefer showing controls (`controls`) when audio playback is user-facing.
+ * - Use `preload="metadata"` as a sensible hint if you want duration, etc.
+ * - Use CORS (`crossOrigin`) when audio might be reused by `<canvas>` without tainting.
+ * - Prefer multiple `<source>` elements for format fallbacks where needed.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create audio elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if Fundatio ever needs runtime behavior
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by Fundatio element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset that covers common cases and
+ * prevents typo-based ARIA bugs.
+ *
+ * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * Allowed `preload` values for media elements.
+ *
+ * @remarks
+ * Per MDN, browsers treat this as a hint and may ignore it; `metadata` is a
+ * common best-practice default in specs/guidance.
+ *
+ * @category Attributes
+ */
+export type AudioPreload = 'none' | 'metadata' | 'auto';
+/**
+ * Allowed values for the `crossorigin` attribute for media fetches.
+ *
+ * @category Attributes
+ */
+export type AudioCrossOrigin = 'anonymous' | 'use-credentials';
+/**
+ * Allowed tokens for the `controlslist` attribute (when `controls` is enabled).
+ *
+ * @remarks
+ * MDN lists allowed values including `nodownload`, `nofullscreen`, `noremoteplayback`.
+ * (`nofullscreen` is effectively video-oriented but is still a valid token in the attribute.)
+ *
+ * @category Attributes
+ */
+export type AudioControlsList = 'nodownload' | 'nofullscreen' | 'noremoteplayback';
+/**
+ * The semantic tag name for audio elements.
+ *
+ * @category Constants
+ */
+export declare const AUDIO_TAG: "audio";
+/**
+ * A CSS selector targeting audio elements.
+ *
+ * @category Constants
+ */
+export declare const AUDIO_SELECTOR = "audio";
+/**
+ * Attribute bag for audio creation/enhancement.
+ *
+ * @remarks
+ * Audio elements accept HTML global attributes plus a media-specific subset.
+ * Fundatio also supports structured ARIA input for common ARIA fields.
+ *
+ * @category Attributes
+ */
+export type AudioAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * The URL of the audio resource to embed.
+     *
+     * @remarks
+     * Optional if you instead provide nested `<source>` elements.
+     */
+    src?: string;
+    /**
+     * Whether browser playback controls should be shown.
+     */
+    controls?: boolean;
+    /**
+     * Whether playback should begin automatically.
+     *
+     * @remarks
+     * Autoplaying audio is often blocked unless user-initiated. If `autoplay`
+     * is enabled and `muted` is not specified, Fundatio defaults `muted` to `true`
+     * as a pragmatic alignment with autoplay policies.
+     */
+    autoplay?: boolean;
+    /**
+     * Whether the audio should loop back to the start after ending.
+     */
+    loop?: boolean;
+    /**
+     * Whether the audio should start out muted.
+     */
+    muted?: boolean;
+    /**
+     * Hint about how much to preload.
+     */
+    preload?: AudioPreload;
+    /**
+     * CORS mode for fetching the audio resource.
+     */
+    crossOrigin?: AudioCrossOrigin;
+    /**
+     * Restrict which built-in controls the user agent exposes (when `controls` is set).
+     *
+     * @example
+     * controlsList: ['nodownload', 'noremoteplayback']
+     */
+    controlsList?: AudioControlsList[];
+    /**
+     * Disable remote playback (Chromecast/AirPlay/etc).
+     */
+    disableRemotePlayback?: boolean;
+};
+/**
+ * Create an audio element with optional attributes.
+ *
+ * @remarks
+ * Global attributes are applied via Fundatio's shared DOM helper, including security
+ * guards that block inline event handler attributes (e.g. `onclick`) and raw
+ * `style` attribute strings through escape hatches.
+ *
+ * Media-specific attributes are applied directly to the element.
+ *
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<audio>` element.
+ *
+ * @example
+ * ```ts
+ * import { createAudio } from "@Vastare/Fundatio/elements/media/audio";
+ *
+ * document.body.appendChild(
+ *   createAudio({ controls: true, src: "/audio/intro.mp3", preload: "metadata" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createAudio(attrs?: AudioAttrs): ElementOf<typeof AUDIO_TAG>;
+/**
+ * Enhance audio elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `1.0.0`.
+ *
+ * Why does it exist?
+ * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)
+ * - It allows future progressive enhancements without changing consumer code
+ *
+ * What it will never do:
+ * - It will not inject styles (CSS remains the source of truth)
+ * - It will not introduce framework-specific behavior
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceAudios(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/media/audio/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/media/audio/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;AAExD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,iBAAiB,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,cAAc,GAAG,kBAAkB,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAG,OAAgB,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACnD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IAEvB;;OAEG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAE/B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAEnC;;OAEG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AA4BF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,OAAO,SAAS,CAAC,CAmC3E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG/D"}

package/dist/types/elements/media/canvas/index.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Fundatio Design Foundation: Canvas element helpers.
+ *
+ * @remarks
+ * The canvas element (`<canvas>`) provides a scriptable drawing surface.
+ *
+ * Best-practice guidance:
+ * - Prefer setting `width` and `height` attributes (not only CSS sizing) to avoid
+ *   rendering distortion from bitmap scaling.
+ * - Provide meaningful fallback content where appropriate (e.g. a short text
+ *   alternative) as the canvas element can represent its fallback content in
+ *   non-visual/unsupported contexts.
+ * - If the canvas conveys information, ensure it is labeled accessibly (e.g.
+ *   via `aria-label` / `aria-labelledby`) and that equivalent information is
+ *   available outside the canvas where needed.
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create canvas elements in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if Fundatio ever needs runtime behavior
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by Fundatio element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset that covers common cases and
+ * prevents typo-based ARIA bugs (e.g. `lable`).
+ *
+ * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference to the labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * The semantic tag name for canvas.
+ *
+ * @category Constants
+ */
+export declare const CANVAS_TAG: "canvas";
+/**
+ * A CSS selector targeting canvas elements.
+ *
+ * @category Constants
+ */
+export declare const CANVAS_SELECTOR = "canvas";
+/**
+ * Attribute bag for canvas creation/enhancement.
+ *
+ * @remarks
+ * Canvas supports:
+ * - standard HTML global attributes
+ * - `width` and `height` attributes for bitmap sizing
+ * - structured ARIA input mapped into `aria-*`
+ *
+ * @category Attributes
+ */
+export type CanvasAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+    /**
+     * Bitmap width (in CSS pixels) for the canvas drawing surface.
+     *
+     * @remarks
+     * Prefer this over CSS-only sizing to avoid scaling distortion.
+     */
+    width?: number;
+    /**
+     * Bitmap height (in CSS pixels) for the canvas drawing surface.
+     *
+     * @remarks
+     * Prefer this over CSS-only sizing to avoid scaling distortion.
+     */
+    height?: number;
+};
+/**
+ * Create a canvas element with optional fallback text content and attributes.
+ *
+ * @remarks
+ * - Text content is assigned via `textContent` (never `innerHTML`).
+ * - `width` and `height` (if provided) are applied as attributes via the safe
+ *   attribute path in `dom.ts`.
+ * - Global attributes are applied via Fundatio's shared DOM helper,
+ *   including security guards that block inline event handler attributes
+ *   (e.g. `onclick`) and raw `style` attribute strings.
+ *
+ * @param text - Optional fallback text content for the canvas.
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<canvas>` element.
+ *
+ * @example
+ * Create a 300x150 canvas with a label:
+ * ```ts
+ * import { createCanvas } from "@Vastare/Fundatio/elements/media/canvas";
+ *
+ * const el = createCanvas(undefined, {
+ *   width: 300,
+ *   height: 150,
+ *   aria: { label: "Sparkline chart" },
+ * });
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createCanvas(text?: string, attrs?: CanvasAttrs): ElementOf<typeof CANVAS_TAG>;
+/**
+ * Enhance canvas elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `1.0.0`.
+ *
+ * Why does it exist?
+ * - It establishes a stable integration pattern for frameworks (Vue/React/etc.)
+ * - It allows future progressive enhancements without changing consumer code
+ *
+ * What it will never do:
+ * - It will not inject styles (CSS remains the source of truth)
+ * - It will not introduce framework-specific behavior
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceCanvases(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/media/canvas/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/media/canvas/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAG,QAAiB,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACpD;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IAEtB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAmCF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAE7F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAGjE"}

package/dist/types/elements/media/embed/index.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Fundatio Design Foundation: Embed element helpers.
+ *
+ * @remarks
+ * The embed element (`<embed>`) embeds external content at a point in the
+ * document. Historically this was often browser plug-ins; modern browsers have
+ * largely removed plug-in support, so relying on `<embed>` is frequently a poor
+ * choice for general-purpose sites. Prefer purpose-built elements when possible
+ * (e.g. `<img>`, `<video>`, `<audio>`, `<iframe>`, or `<object>` depending on the use case).
+ *
+ * Best-practice guidance:
+ * - Prefer native elements over `<embed>` when there is a semantic alternative.
+ * - Use the `title` attribute to label embedded content for assistive technology.
+ * - `width`/`height` should be absolute pixel values (no percentages).
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create embed nodes in vanilla JS/TS without templates
+ * - apply consistent global attributes safely
+ * - use a stable "enhancement" hook if Fundatio ever needs runtime behavior
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * @module
+ * @category Elements
+ */
+import { type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+/**
+ * Structured ARIA input supported by Fundatio element factories.
+ *
+ * @remarks
+ * This is intentionally a small, typed subset that covers common cases and
+ * prevents typo-based ARIA bugs.
+ *
+ * It is mapped into {@link GlobalAttrs.aria} for application by `dom.ts`.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+    /**
+     * Accessible label, mapped to `aria-label`.
+     */
+    label?: string;
+    /**
+     * ID reference to labelling element(s), mapped to `aria-labelledby`.
+     */
+    labelledby?: string;
+    /**
+     * Decorative/hidden hint, mapped to `aria-hidden`.
+     */
+    hidden?: boolean;
+};
+/**
+ * The semantic tag name for embed.
+ *
+ * @category Constants
+ */
+export declare const EMBED_TAG: "embed";
+/**
+ * A CSS selector targeting embed elements.
+ *
+ * @category Constants
+ */
+export declare const EMBED_SELECTOR = "embed";
+/**
+ * Attribute bag for embed creation/enhancement.
+ *
+ * @remarks
+ * `<embed>` supports global attributes plus:
+ * - `src` (URL)
+ * - `type` (MIME type)
+ * - `width` / `height` (absolute pixel values; percentages are invalid)
+ *
+ * Accessibility:
+ * - Provide a `title` (global attribute) to label the embedded content.
+ *
+ * Fundatio also supports a structured ARIA input for common ARIA fields, mapped into
+ * `aria-*` attributes.
+ *
+ * @category Attributes
+ */
+export type EmbedAttrs = Omit<GlobalAttrs, 'aria'> & {
+    /**
+     * URL of the resource being embedded.
+     */
+    src?: string;
+    /**
+     * MIME type used to select the appropriate handler.
+     */
+    type?: string;
+    /**
+     * Displayed width in CSS pixels (absolute; percentages are not allowed).
+     */
+    width?: number | string;
+    /**
+     * Displayed height in CSS pixels (absolute; percentages are not allowed).
+     */
+    height?: number | string;
+    /**
+     * Structured ARIA fields mapped into `aria-*` attributes.
+     */
+    aria?: StructuredAria;
+};
+/**
+ * Create an embed element and apply attributes.
+ *
+ * @remarks
+ * Global attributes are applied via Fundatio's shared DOM helper, including security
+ * guards that block inline event handler attributes (e.g. `onclick`) and raw
+ * `style` attribute strings.
+ *
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<embed>` element.
+ *
+ * @example
+ * ```ts
+ * import { createEmbed } from "@Vastare/Fundatio/elements/media/embed";
+ *
+ * document.body.appendChild(
+ *   createEmbed({ src: "/files/manual.pdf", type: "application/pdf", title: "User manual" })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export declare function createEmbed(attrs?: EmbedAttrs): ElementOf<typeof EMBED_TAG>;
+/**
+ * Enhance embed elements within a given root.
+ *
+ * @remarks
+ * This is intentionally a no-op in `1.0.0`.
+ *
+ * @param root - The node to search within. Defaults to `document`.
+ *
+ * @category Enhancement
+ */
+export declare function enhanceEmbeds(root?: ParentNode): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/elements/media/embed/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/elements/media/embed/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAG,OAAgB,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IACnD;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEzB;;OAEG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAwFF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,OAAO,SAAS,CAAC,CAE3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,GAAE,UAAqB,GAAG,IAAI,CAG/D"}