@vastare/fundatio 0.1.0

package/src/elements/media/iframe/index.ts

@@ -0,0 +1,331 @@
+/**
+ * Fundatio Design Foundation: IFrame element helpers.
+ *
+ * @remarks
+ * The iframe element (`<iframe>`) embeds another HTML page into the current page.
+ *
+ * Best-practice guidance:
+ * - Prefer `<iframe>` only when you truly need third-party or isolated documents.
+ * - Consider `loading="lazy"` for non-critical iframes to reduce initial load cost.
+ * - Use `sandbox` with the least permissions possible when embedding untrusted content.
+ * - Prefer restrictive `referrerpolicy` when embedding third-party content.
+ * - Provide a meaningful `title` for accessibility (screen readers use it to identify the frame).
+ * - Avoid obsolete attributes like `frameborder`; use CSS instead.
+ *
+ * Security notes:
+ * - `srcdoc` embeds HTML directly. Fundatio does not sanitize or validate it.
+ *   If you build `srcdoc` from untrusted input, that is on you (and your incident report).
+ *
+ * This module provides small, framework-agnostic helpers so consumers can:
+ * - create iframes 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 { createElement, type ElementOf, type GlobalAttrs, type AttrValue } 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;
+};
+
+/**
+ * The semantic tag name for iframe embeds.
+ *
+ * @category Constants
+ */
+export const IFRAME_TAG = 'iframe' as const;
+
+/**
+ * A CSS selector targeting iframe elements.
+ *
+ * @category Constants
+ */
+export const IFRAME_SELECTOR = 'iframe';
+
+/**
+ * Allowed values for the iframe `loading` attribute.
+ *
+ * @category Types
+ */
+export type IFrameLoading = 'eager' | 'lazy';
+
+/**
+ * Allowed values for the iframe `referrerpolicy` attribute.
+ *
+ * @category Types
+ */
+export type IFrameReferrerPolicy =
+  | 'no-referrer'
+  | 'no-referrer-when-downgrade'
+  | 'origin'
+  | 'origin-when-cross-origin'
+  | 'same-origin'
+  | 'strict-origin'
+  | 'strict-origin-when-cross-origin'
+  | 'unsafe-url';
+
+/**
+ * Allowed values for the `fetchpriority` attribute.
+ *
+ * @category Types
+ */
+export type FetchPriority = 'high' | 'low' | 'auto';
+
+/**
+ * Attribute bag for iframe creation/enhancement.
+ *
+ * @remarks
+ * Iframes accept standard HTML global attributes plus iframe-specific attributes.
+ *
+ * Fundatio also supports a structured ARIA input for common ARIA fields, which is
+ * mapped into {@link GlobalAttrs.aria} without changing Fundatio's core DOM helpers.
+ *
+ * @category Attributes
+ */
+export type IFrameAttrs = Omit<GlobalAttrs, 'aria'> & {
+  /**
+   * Structured ARIA fields mapped into `aria-*` attributes.
+   */
+  aria?: StructuredAria;
+
+  /**
+   * Address of the document to embed.
+   */
+  src?: string;
+
+  /**
+   * Inline HTML to render within the iframe.
+   *
+   * @remarks
+   * Fundatio does not sanitize `srcdoc`.
+   */
+  srcdoc?: string;
+
+  /**
+   * A name for the browsing context.
+   */
+  name?: string;
+
+  /**
+   * A space-separated list of sandbox tokens.
+   *
+   * @remarks
+   * Use the least permissive sandbox you can.
+   */
+  sandbox?: string;
+
+  /**
+   * Permissions policy for the iframe (previously "feature policy").
+   *
+   * @remarks
+   * Example: `allow="fullscreen; geolocation 'none'"`.
+   */
+  allow?: string;
+
+  /**
+   * Whether fullscreen is allowed.
+   *
+   * @remarks
+   * Mirrors the `allowfullscreen` boolean attribute.
+   */
+  allowFullScreen?: boolean;
+
+  /**
+   * Whether the iframe should be loaded lazily or eagerly.
+   */
+  loading?: IFrameLoading;
+
+  /**
+   * Referrer policy for requests made by the iframe.
+   */
+  referrerPolicy?: IFrameReferrerPolicy;
+
+  /**
+   * Display width, in CSS pixels.
+   */
+  width?: number | string;
+
+  /**
+   * Display height, in CSS pixels.
+   */
+  height?: number | string;
+
+  /**
+   * Fetch priority hint.
+   */
+  fetchPriority?: FetchPriority;
+
+  /**
+   * Content Security Policy to apply to the embedded document.
+   *
+   * @remarks
+   * Support varies by browser and context.
+   */
+  csp?: string;
+
+  /**
+   * Whether to use a credentialless iframe (privacy-oriented isolation).
+   *
+   * @remarks
+   * Mirrors the `credentialless` boolean attribute where supported.
+   */
+  credentialless?: boolean;
+};
+
+/**
+ * Normalize {@link IFrameAttrs} into {@link GlobalAttrs} for `dom.ts`.
+ *
+ * @param attrs - The iframe attributes.
+ * @returns A {@link GlobalAttrs} object, or `undefined` if no attrs were provided.
+ *
+ * @category Internal
+ */
+function toGlobalAttrs(attrs?: IFrameAttrs): GlobalAttrs | undefined {
+  if (!attrs) return undefined;
+
+  const {
+    aria,
+    src,
+    srcdoc,
+    name,
+    sandbox,
+    allow,
+    allowFullScreen,
+    loading,
+    referrerPolicy,
+    width,
+    height,
+    fetchPriority,
+    csp,
+    credentialless,
+    ...rest
+  } = attrs;
+
+  // Start with any caller-provided attrs escape hatch (it is still validated by dom.ts).
+  const mergedAttrs: Record<string, AttrValue> = { ...(rest.attrs ?? {}) };
+
+  // Helper: only set if caller didn't already set the raw attribute explicitly.
+  const setIfUnset = (key: string, value: AttrValue | undefined): void => {
+    if (value === undefined) return;
+    if (Object.prototype.hasOwnProperty.call(mergedAttrs, key)) return;
+    mergedAttrs[key] = value;
+  };
+
+  setIfUnset('src', src);
+  setIfUnset('srcdoc', srcdoc);
+  setIfUnset('name', name);
+  setIfUnset('sandbox', sandbox);
+  setIfUnset('allow', allow);
+  setIfUnset('loading', loading);
+  setIfUnset('referrerpolicy', referrerPolicy);
+  setIfUnset('width', width);
+  setIfUnset('height', height);
+  setIfUnset('fetchpriority', fetchPriority);
+  setIfUnset('csp', csp);
+
+  // Boolean attributes are represented by presence. We set empty-string when true.
+  if (allowFullScreen === true) setIfUnset('allowfullscreen', '');
+  if (credentialless === true) setIfUnset('credentialless', '');
+
+  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};
+  if (aria) {
+    if (typeof aria.label === 'string') mappedAria.label = aria.label;
+    if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;
+    if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;
+  }
+
+  const hasMappedAria = Object.keys(mappedAria).length > 0;
+  const hasMergedAttrs = Object.keys(mergedAttrs).length > 0;
+
+  const next: GlobalAttrs = { ...rest };
+  if (hasMergedAttrs) next.attrs = mergedAttrs;
+  if (hasMappedAria) next.aria = mappedAria;
+
+  return next;
+}
+
+/**
+ * Create an iframe element with optional fallback text and attributes.
+ *
+ * @remarks
+ * - Fallback text is assigned via `textContent` (never `innerHTML`).
+ * - 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 iframe (rarely used, but valid).
+ * @param attrs - Optional attributes to apply.
+ * @returns The created `<iframe>` element.
+ *
+ * @example
+ * ```ts
+ * import { createIFrame } from "@Vastare/Fundatio/elements/media/iframe";
+ *
+ * document.body.appendChild(
+ *   createIFrame(undefined, {
+ *     title: "Embedded map",
+ *     src: "https://example.com/map",
+ *     loading: "lazy",
+ *     sandbox: "allow-scripts allow-same-origin"
+ *   })
+ * );
+ * ```
+ *
+ * @category DOM
+ */
+export function createIFrame(text?: string, attrs?: IFrameAttrs): ElementOf<typeof IFRAME_TAG> {
+  return createElement(IFRAME_TAG, toGlobalAttrs(attrs), text);
+}
+
+/**
+ * Enhance iframe 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 function enhanceIFrames(root: ParentNode = document): void {
+  // v1.0.0: no runtime behavior for iframe.
+  void root;
+}

package/src/elements/media/img/img.scss

@@ -0,0 +1,47 @@
+/**
+ * Fundatio Design Foundation: Image Element
+ *
+ * Embedded image (`img`)
+ *
+ * Baseline hygiene only.
+ *
+ * This module:
+ * - Normalizes `<img>` rendering across browsers
+ * - Removes legacy border behavior
+ * - Ensures predictable responsive scaling
+ * - Preserves intrinsic aspect ratio
+ * - Uses low-specificity selectors (`:where()`)
+ *
+ * @module
+ * @group  elements.media.img
+ * @access public
+ * @since  1.0.0
+ */
+
+:where(img) {
+  /* --------------------------------------------------------------------------
+   - Reset / normalization
+   -------------------------------------------------------------------------- */
+
+  // Replaced element baseline.
+  display: inline-block;
+  vertical-align: middle;
+
+  // Remove legacy border when image is inside anchor.
+  border: 0;
+
+  // Remove incidental spacing artifacts.
+  margin: 0;
+  padding: 0;
+
+  /* --------------------------------------------------------------------------
+   - Layout predictability
+   -------------------------------------------------------------------------- */
+
+  // Responsive containment without breaking intrinsic ratio.
+  max-width: 100%;
+  height: auto;
+
+  // Ensure sizing behaves predictably in constrained layouts.
+  box-sizing: border-box;
+}

package/src/elements/media/img/index.ts

@@ -0,0 +1,146 @@
+/**
+ * Fundatio Design Foundation: Img element helpers.
+ *
+ * @remarks
+ * The img element (`<img>`) embeds an image into the document.
+ *
+ * Best-practice guidance:
+ * - The `alt` attribute must always be present.
+ * - Use `alt=""` for purely decorative images.
+ * - Provide meaningful alternative text for informative images.
+ * - Do not rely on images alone to convey critical information.
+ *
+ * This module enforces:
+ * - `alt` always exists (defaults to empty string if not provided)
+ * - If neither `src` nor `srcset` is provided, a safe fallback
+ *   `src="data:,"` is applied to avoid broken network requests
+ * - All global attributes are applied via Fundatio's hardened DOM helpers
+ *
+ * This module has no side effects and does not mutate the DOM unless you call
+ * its functions.
+ *
+ * @module
+ * @category Elements
+ */
+
+import { createVoidElement, type ElementOf, type GlobalAttrs } from '../../../ts/dom';
+
+/**
+ * Structured ARIA input supported by Fundatio element factories.
+ *
+ * @category Attributes
+ */
+export type StructuredAria = {
+  label?: string;
+  labelledby?: string;
+  hidden?: boolean;
+};
+
+/**
+ * The semantic tag name for images.
+ *
+ * @category Constants
+ */
+export const IMG_TAG = 'img' as const;
+
+/**
+ * A CSS selector targeting img elements.
+ *
+ * @category Constants
+ */
+export const IMG_SELECTOR = 'img';
+
+/**
+ * Img-specific attributes.
+ *
+ * @remarks
+ * `alt` is mandatory per HTML specification.
+ *
+ * @category Attributes
+ */
+export type ImgAttrs = Omit<GlobalAttrs, 'aria'> & {
+  alt?: string;
+  src?: string;
+  srcset?: string;
+  sizes?: string;
+  width?: number;
+  height?: number;
+  loading?: 'lazy' | 'eager';
+  decoding?: 'sync' | 'async' | 'auto';
+  referrerPolicy?: string;
+  aria?: StructuredAria;
+};
+
+function toGlobalAttrs(attrs?: ImgAttrs): GlobalAttrs {
+  const {
+    aria,
+    alt,
+    src,
+    srcset,
+    sizes,
+    width,
+    height,
+    loading,
+    decoding,
+    referrerPolicy,
+    ...rest
+  } = attrs ?? {};
+
+  const mapped: GlobalAttrs = { ...rest };
+
+  const mappedAria: NonNullable<GlobalAttrs['aria']> = {};
+
+  if (aria) {
+    if (typeof aria.label === 'string') mappedAria.label = aria.label;
+    if (typeof aria.labelledby === 'string') mappedAria.labelledby = aria.labelledby;
+    if (typeof aria.hidden === 'boolean') mappedAria.hidden = aria.hidden;
+  }
+
+  if (Object.keys(mappedAria).length > 0) {
+    mapped.aria = mappedAria;
+  }
+
+  mapped.attrs = {
+    ...(mapped.attrs ?? {}),
+    alt: typeof alt === 'string' ? alt : '',
+  };
+
+  const hasSrc = typeof src === 'string' && src.length > 0;
+  const hasSrcset = typeof srcset === 'string' && srcset.length > 0;
+
+  if (hasSrc) mapped.attrs.src = src;
+  if (hasSrcset) mapped.attrs.srcset = srcset;
+  if (sizes) mapped.attrs.sizes = sizes;
+  if (typeof width === 'number') mapped.attrs.width = width;
+  if (typeof height === 'number') mapped.attrs.height = height;
+  if (loading) mapped.attrs.loading = loading;
+  if (decoding) mapped.attrs.decoding = decoding;
+  if (referrerPolicy) mapped.attrs.referrerpolicy = referrerPolicy;
+
+  if (!hasSrc && !hasSrcset) {
+    mapped.attrs.src = 'data:,';
+  }
+
+  return mapped;
+}
+
+/**
+ * Create an img element with enforced accessibility safeguards.
+ *
+ * @category DOM
+ */
+export function createImg(attrs?: ImgAttrs): ElementOf<typeof IMG_TAG> {
+  return createVoidElement(IMG_TAG, toGlobalAttrs(attrs));
+}
+
+/**
+ * Enhance img elements within a given root.
+ *
+ * @remarks
+ * No runtime behaviour in v1.0.0.
+ *
+ * @category Enhancement
+ */
+export function enhanceImgs(root: ParentNode = document): void {
+  void root;
+}

package/src/elements/media/index.ts

@@ -0,0 +1,97 @@
+/**
+ * Media element factories.
+ *
+ * Provides framework-agnostic factory functions for embedded, graphical,
+ * and time-based media elements.
+ *
+ * These factories:
+ * - Create semantic HTML media elements using Fundatio's hardened DOM helpers.
+ * - Forward curated global attributes.
+ * - Enforce structured, typed attribute bags.
+ * - Apply sensible fallbacks where required by the HTML specification.
+ * - Prevent unsafe attribute injection.
+ *
+ * @module elements/media
+ * @since 1.0.0
+ */
+
+/**
+ * `<img>` element factory namespace.
+ *
+ * Embeds raster images into the document.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img
+ */
+export * as img from './img';
+
+/**
+ * `<svg>` element factory namespace.
+ *
+ * Embeds scalable vector graphics content.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/svg
+ */
+export * as svg from './svg';
+
+/**
+ * `<math>` element factory namespace.
+ *
+ * Embeds MathML content for mathematical notation.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/math
+ */
+export * as math from './math';
+
+/**
+ * `<canvas>` element factory namespace.
+ *
+ * Provides a bitmap rendering surface for scripted drawing.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas
+ */
+export * as canvas from './canvas';
+
+/**
+ * `<iframe>` element factory namespace.
+ *
+ * Embeds another HTML page within the current document.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe
+ */
+export * as iframe from './iframe';
+
+/**
+ * `<embed>` element factory namespace.
+ *
+ * Embeds external content such as plugins or media resources.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/embed
+ */
+export * as embed from './embed';
+
+/**
+ * `<object>` element factory namespace.
+ *
+ * Embeds external resources such as images, PDFs, or interactive content.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/object
+ */
+export * as object from './object';
+
+/**
+ * `<video>` element factory namespace.
+ *
+ * Embeds time-based video media.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video
+ */
+export * as video from './video';
+
+/**
+ * `<audio>` element factory namespace.
+ *
+ * Embeds time-based audio media.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio
+ */
+export * as audio from './audio';